From 5d01c254c8de65bfbcb1155d2d7531cc4898dfb4 Mon Sep 17 00:00:00 2001
From: KorryKatti <143781663+KorryKatti@users.noreply.github.com>
Date: Mon, 18 Nov 2024 23:17:25 +0530
Subject: [PATCH 001/151] Update 01-zig-weird.qmd

---
 Chapters/01-zig-weird.qmd | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index 7f564f7e..c1539784 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -359,6 +359,26 @@ zig run src/main.zig
 ```
 Hello, world!
 ```
+### Important Note for Windows Users
+
+On Windows, certain global initializations that rely on runtime resources, such as `std.io.getStdOut().writer()`, may fail. This happens because global variables in Zig are initialized at **compile-time**, and operations like accessing `stdout` or opening files are restricted to runtime.
+
+### Example
+**Incorrect:**
+```{zig}
+#| eval: false
+#| auto_main: false
+const stdout = std.io.getStdOut().writer(); // ❌ Compile-time error on Windows
+```
+Correct:
+
+```{zig}
+#| eval: false
+#| auto_main: false
+pub fn main() void {
+    const stdout = std.io.getStdOut().writer(); // ✅ Runtime initialization
+}
+```
 
 ### Compiling the entire project {#sec-compile-project}
 

From 96e86e97db6c11a9af399cb8162ceafa5eb559c2 Mon Sep 17 00:00:00 2001
From: KorryKatti <143781663+KorryKatti@users.noreply.github.com>
Date: Thu, 21 Nov 2024 21:21:46 +0530
Subject: [PATCH 002/151] Update 03-structs.qmd

---
 Chapters/03-structs.qmd | 21 ++++++++++++---------
 1 file changed, 12 insertions(+), 9 deletions(-)

diff --git a/Chapters/03-structs.qmd b/Chapters/03-structs.qmd
index 11b4861f..ef7c740c 100644
--- a/Chapters/03-structs.qmd
+++ b/Chapters/03-structs.qmd
@@ -282,15 +282,18 @@ switch statement two times, before ending at the `3` branch.
 #| auto_main: false
 #| build_type: "lib"
 #| eval: false
-xsw: switch (@as(u8, 1)) {
-    1 => {
-        try stdout.print("First branch\n", .{});
-        continue :xsw 2;
-    },
-    2 => continue :xsw 3,
-    3 => return,
-    4 => {},
-}
+    xsw: switch (@as(u8, 1)) {
+        1 => {
+            try stdout.print("First branch\n", .{});
+            continue :xsw 2;
+        },
+        2 => continue :xsw 3,
+        3 => return,
+        4 => {},
+        else => {
+            try stdout.print("Unmatched case, value: {d}\n", .{@as(u8, 1)});
+        },
+    }
 ```
 
 

From 426b59ba234ad2eb27ffef0a089d90ac9ed824d0 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sun, 24 Nov 2024 20:17:42 -0300
Subject: [PATCH 003/151] Fix indentation

---
 Chapters/03-structs.qmd | 26 ++++++++++++++------------
 1 file changed, 14 insertions(+), 12 deletions(-)

diff --git a/Chapters/03-structs.qmd b/Chapters/03-structs.qmd
index ef7c740c..1dd3552d 100644
--- a/Chapters/03-structs.qmd
+++ b/Chapters/03-structs.qmd
@@ -282,18 +282,20 @@ switch statement two times, before ending at the `3` branch.
 #| auto_main: false
 #| build_type: "lib"
 #| eval: false
-    xsw: switch (@as(u8, 1)) {
-        1 => {
-            try stdout.print("First branch\n", .{});
-            continue :xsw 2;
-        },
-        2 => continue :xsw 3,
-        3 => return,
-        4 => {},
-        else => {
-            try stdout.print("Unmatched case, value: {d}\n", .{@as(u8, 1)});
-        },
-    }
+xsw: switch (@as(u8, 1)) {
+    1 => {
+        try stdout.print("First branch\n", .{});
+        continue :xsw 2;
+    },
+    2 => continue :xsw 3,
+    3 => return,
+    4 => {},
+    else => {
+        try stdout.print(
+            "Unmatched case, value: {d}\n", .{@as(u8, 1)}
+        );
+    },
+}
 ```
 
 

From a0532a5b0c56ef04076c7e4e66e7a3e1ef3a1a36 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sun, 24 Nov 2024 20:20:27 -0300
Subject: [PATCH 004/151] Recompile book with changes from #95

---
 _freeze/Chapters/03-structs/execute-results/html.json | 8 +++++---
 docs/Chapters/03-structs.html                         | 7 ++++++-
 docs/index.html                                       | 4 ++--
 docs/search.json                                      | 2 +-
 4 files changed, 14 insertions(+), 7 deletions(-)

diff --git a/_freeze/Chapters/03-structs/execute-results/html.json b/_freeze/Chapters/03-structs/execute-results/html.json
index 55c219e2..a9593c0d 100644
--- a/_freeze/Chapters/03-structs/execute-results/html.json
+++ b/_freeze/Chapters/03-structs/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "d6fc1ed4bd224ef816cd041a3496fc12",
+  "hash": "fe9a62d3c3cabeb2802974d2becced51",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Control flow, structs, modules and types\n\nWe have discussed a lot of Zig's syntax in the last chapter,\nespecially in @sec-root-file and @sec-main-file.\nBut we still need to discuss some other very important\nelements of the language. Elements that you will use constantly on your day-to-day\nroutine.\n\nWe begin this chapter by discussing the different keywords and structures\nin Zig related to control flow (e.g. loops and if statements).\nThen, we talk about structs and how they can be used to do some\nbasic Object-Oriented (OOP) patterns in Zig. We also talk about\ntype inference and type casting.\nFinally, we end this chapter by discussing modules, and how they relate\nto structs.\n\n\n\n## Control flow {#sec-zig-control-flow}\n\nSometimes, you need to make decisions in your program. Maybe you need to decide\nwhether or not to execute a specific piece of code. Or maybe,\nyou need to apply the same operation over a sequence of values. These kinds of tasks,\ninvolve using structures that are capable of changing the \"control flow\" of our program.\n\nIn computer science, the term \"control flow\" usually refers to the order in which expressions (or commands)\nare evaluated in a given language or program. But this term is also used to refer\nto structures that are capable of changing this \"evaluation order\" of the commands\nexecuted by a given language/program.\n\nThese structures are better known\nby a set of terms, such as: loops, if/else statements, switch statements, among others. So,\nloops and if/else statements are examples of structures that can change the \"control\nflow\" of our program. The keywords `continue` and `break` are also examples of symbols\nthat can change the order of evaluation, since they can move our program to the next iteration\nof a loop, or make the loop stop completely.\n\n\n### If/else statements\n\nAn if/else statement performs a \"conditional flow operation\".\nA conditional flow control (or choice control) allows you to execute\nor ignore a certain block of commands based on a logical condition.\nMany programmers and computer science professionals also use\nthe term \"branching\" in this case.\nIn essence, an if/else statement allow us to use the result of a logical test\nto decide whether or not to execute a given block of commands.\n\nIn Zig, we write if/else statements by using the keywords `if` and `else`.\nWe start with the `if` keyword followed by a logical test inside a pair\nof parentheses, followed by a pair of curly braces which contains the lines\nof code to be executed in case the logical test returns the value `true`.\n\nAfter that, you can optionally add an `else` statement. To do that, just add the `else`\nkeyword followed by a pair of curly braces, with the lines of code\nto executed in case the logical test defined at `if` returns `false`.\n\nIn the example below, we are testing if the object `x` contains a number\nthat is greater than 10. Judging by the output printed to the console,\nwe know that this logical test returned `false`. Because the output\nin the console is compatible with the line of code present in the\n`else` branch of the if/else statement.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x = 5;\nif (x > 10) {\n    try stdout.print(\n        \"x > 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x <= 10!\\n\", .{}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nx <= 10!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n### Switch statements {#sec-switch}\n\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust.\nAs you would expect, to write a switch statement in Zig we use the `switch` keyword.\nWe provide the value that we want to \"switch over\" inside a\npair of parentheses. Then, we list the possible combinations (or \"branches\")\ninside a pair of curly braces.\n\nLet's take a look at the code example below. You can see that\nI'm creating an enum type called `Role`. We talk more about enums in @sec-enum.\nBut in summary, this `Role` type is listing different types of roles in a fictitious\ncompany, like `SE` for Software Engineer, `DE` for Data Engineer, `PM` for Product Manager,\netc.\n\nNotice that we are using the value from the `role` object in the\nswitch statement, to discover which exact area we need to store in the `area` variable object.\nAlso notice that we are using type inference inside the switch statement, with the dot character,\nas we are going to describe in @sec-type-inference.\nThis makes the `zig` compiler infer the correct data type of the values (`PM`, `SE`, etc.) for us.\n\nAlso notice that, we are grouping multiple values in the same branch of the switch statement.\nWe just separate each possible value with a comma. For example, if `role` contains either `DE` or `DA`,\nthe `area` variable would contain the value `\"Data & Analytics\"`, instead of `\"Platform\"` or `\"Sales\"`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO => {\n            area = \"Platform\";\n        },\n        .DE, .DA => {\n            area = \"Data & Analytics\";\n        },\n        .KS => {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nPlatform\n```\n\n\n:::\n:::\n\n\n\n\n\n\n#### Switch statements must exhaust all possibilities\n\nOne very important aspect about switch statements in Zig\nis that they must exhaust all existing possibilities.\nIn other words, all possible values that could be found inside the `order`\nobject must be explicitly handled in this switch statement.\n\nSince the `role` object have type `Role`, the only possible values to\nbe found inside this object are `PM`, `SE`, `DPE`, `PO`, `DE`, `DA` and `KS`.\nThere are no other possible values to be stored in this `role` object.\nThus, the switch statements must have a combination (branch) for each one of these values.\nThis is what \"exhaust all existing possibilities\" means. The switch statement covers\nevery possible case.\n\nTherefore, you cannot write a switch statement in Zig, and leave an edge case\nwith no explicit action to be taken.\nThis is a similar behaviour to switch statements in Rust, which also have to\nhandle all possible cases.\n\n\n\n#### The else branch\n\nTake a look at the `dump_hex_fallible()` function below as an example. This function\ncomes from the Zig Standard Library. More precisely, from the\n[`debug.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/debug.zig)[^debug-mod].\nThere are multiple lines in this function, but I omitted them to focus solely on the\nswitch statement found in this function. Notice that this switch statement has four\npossible cases (i.e. four explicit branches). Also, notice that we used an `else` branch\nin this case.\n\nAn `else` branch in a switch statement works as the \"default branch\".\nWhenever you have multiple cases in your switch statement where\nyou want to apply the exact same action, you can use an `else` branch to do that.\n\n[^debug-mod]: <https://github.com/ziglang/zig/blob/master/lib/std/debug.zig>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' => try writer.writeAll(\"␊\"),\n        '\\r' => try writer.writeAll(\"␍\"),\n        '\\t' => try writer.writeAll(\"␉\"),\n        else => try writer.writeByte('.'),\n    }\n}\n```\n:::\n\n\n\n\n\nMany programmers would also use an `else` branch to handle a \"not supported\" case.\nThat is, a case that cannot be properly handled by your code, or, just a case that\nshould not be \"fixed\". Therefore, you can use an `else` branch to panic (or raise an error)\nin your program to stop the current execution.\n\nTake the code example below. We can see that, we are handling the cases\nfor the `level` object being either 1, 2, or 3. All other possible cases are not supported by default,\nand, as consequence, we raise a runtime error in such cases through the `@panic()` built-in function.\n\nAlso notice that, we are assigning the result of the switch statement to a new object called `category`.\nThis is another thing that you can do with switch statements in Zig. If a branch\noutputs a value as result, you can store the result value of the switch statement into\na new object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 => \"beginner\",\n    3 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n:::\n\n\n\n\n\n```\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n```\n\n\n\n#### Using ranges in switch\n\nFurthermore, you can also use ranges of values in switch statements.\nThat is, you can create a branch in your switch statement that is used\nwhenever the input value is within the specified range. These \"range expressions\"\nare created with the operator `...`. It is important\nto emphasize that the ranges created by this operator are\ninclusive on both ends.\n\nFor example, I could easily change the previous code example to support all\nlevels between 0 and 100. Like this:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 => \"beginner\",\n    26...75 => \"intermediary\",\n    76...100 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nbeginner\n```\n\n\n:::\n:::\n\n\n\n\n\nThis is neat, and it works with character ranges too. That is, I could\nsimply write `'a'...'z'`, to match any character value that is a\nlowercase letter, and it would work fine.\n\n\n#### Labeled switch statements\n\nIn @sec-blocks we have talked about labeling blocks, and also, about using these labels\nto return a value from the block. Well, from version 0.14.0 and onwards of the `zig` compiler,\nyou can also apply labels over switch statements, which makes it possible to almost implement a\n\"C `goto`\" like pattern.\n\nFor example, if you give the label `xsw` to a switch statement, you can use this\nlabel in conjunction with the `continue` keyword to go back to the beginning of the switch\nstatement. In the example below, the execution goes back to the beginning of the\nswitch statement two times, before ending at the `3` branch.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nxsw: switch (@as(u8, 1)) {\n    1 => {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 => continue :xsw 3,\n    3 => return,\n    4 => {},\n}\n```\n:::\n\n\n\n\n\n\n### The `defer` keyword {#sec-defer}\n\nWith the `defer` keyword you can register an expression to be executed when you exit the current scope.\nTherefore, this keyword has a similar functionality as the `on.exit()` function from R.\nTake the `foo()` function below as an example. When we execute this `foo()` function, the expression\nthat prints the message \"Exiting function ...\" is getting executed only when the function exits\nits scope.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n```\n:::\n\n\n\n\n\n```\nAdding some numbers ...\nMultiplying ...\nExiting function ...\n```\n\nTherefore, we can use `defer` to declare an expression that is going to be executed\nwhen your code exits the current scope. Some programmers like to interpret the phrase \"exit of the current scope\"\nas \"the end of the current scope\". But this interpretation might not be entirely correct, depending\non what you consider as \"the end of the current scope\".\n\nI mean, what do you consider as **the end** of the current scope? Is it the closing curly bracket (`}`) of the scope?\nIs it when the last expression in the function get's executed? Is it when the function returns to the previous scope?\nEtc. For example, it would not be correct to interpret the \"exit of the current scope\" as the closing\ncurly bracket of the scope. Because the function might exit from an earlier position than this\nclosing curly bracket (e.g. an error value was generated at a previous line inside the function;\nthe function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\n\nNow, if you remember of what we have discussed in @sec-blocks, there are multiple structures in the language\nthat create their own separate scopes. For/while loops, if/else statements,\nfunctions, normal blocks, etc. This also affects the interpretation of `defer`.\nFor example, if you use `defer` inside a for loop, then, the given expression\nwill be executed everytime this specific for loop exits its own scope.\n\nBefore we continue, is worth emphasizing that the `defer` keyword is an \"unconditional defer\".\nWhich means that the given expression will be executed no matter how the code exits\nthe current scope. For example, your code might exit the current scope because of an error value\nbeing generated, or, because of a return statement, or, a break statement, etc.\n\n\n\n### The `errdefer` keyword {#sec-errdefer1}\n\nOn the previous section, we have discussed the `defer` keyword, which you can use to\nregister an expression to be executed at the exit of the current scope.\nBut this keyword has a brother, which is the `errdefer` keyword. While `defer`\nis an \"unconditional defer\", the `errdefer` keyword is a \"conditional defer\".\nWhich means that the given expression is executed only when you exit the current\nscope on a very specific circumstance.\n\nIn more details, the expression given to `errdefer` is executed only when an error occurs in the current scope.\nTherefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope\nin a normal situation, without errors, the expression given to `errdefer` is not executed.\n\nThis makes the `errdefer` keyword one of the many tools available in Zig for error handling.\nIn this section, we are more concerned with the control flow aspects around `errdefer`.\nBut we are going to discuss `errdefer` later as a error handling tool in @sec-errdefer2.\n\nThe code example below demonstrates three things:\n\n- that `defer` is an \"unconditional defer\", because the given expression get's executed regardless of how the function `foo()` exits its own scope.\n- that `errdefer` is executed because the function `foo()` returned an error value.\n- that `defer` and `errdefer` expressions are executed in a LIFO (*last in, first out*) order.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n```\n:::\n\n\n\n\n\n```\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\nWhen I say that \"defer expressions\" are executed in a LIFO order, what I want to say is that\nthe last `defer` or `errdefer` expressions in the code are the first ones to be executed.\nYou could also interpret this as: \"defer expressions\" are executed from bottom to top, or,\nfrom last to first.\n\nTherefore, if I change the order of the `defer` and `errdefer` expressions, you will notice that\nthe value of `i` that get's printed to the console changes to 1. This doesn't mean that the\n`defer` expression was not executed in this case. This actually means that the `defer` expression\nwas executed only after the `errdefer` expression. The code example below demonstrates this:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n```\n:::\n\n\n\n\n\n```\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\n\n\n### For loops\n\nA loop allows you to execute the same lines of code multiple times,\nthus, creating a \"repetition space\" in the execution flow of your program.\nLoops are particularly useful when we want to replicate the same function\n(or the same set of commands) over different inputs.\n\nThere are different types of loops available in Zig. But the most\nessential of them all is probably the *for loop*. A for loop is\nused to apply the same piece of code over the elements of a slice, or, an array.\n\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from\nother languages. You start with the `for` keyword, then, you\nlist the items that you want to iterate\nover inside a pair of parentheses. Then, inside of a pair of pipes (`|`)\nyou should declare an identifier that will serve as your iterator, or,\nthe \"repetition index of the loop\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (items) |value| {\n    // code to execute\n}\n```\n:::\n\n\n\n\n\nTherefore, instead of using a `(value in items)` syntax,\nin Zig, for loops use the syntax `(items) |value|`. In the example\nbelow, you can see that we are looping through the items\nof the array stored at the object `name`, and printing to the\nconsole the decimal representation of each character in this array.\n\nIf we wanted, we could also iterate through a slice (or a portion) of\nthe array, instead of iterating through the entire array stored in the `name` object.\nJust use a range selector to select the section you want. For example,\nI could provide the expression `name[0..3]` to the for loop, to iterate\njust through the first 3 elements in the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n80 | 101 | 100 | 114 | 111 | \n```\n\n\n:::\n:::\n\n\n\n\n\nIn the above example we are using the value itself of each\nelement in the array as our iterator. But there are many situations where\nwe need to use an index instead of the actual values of the items.\n\nYou can do that by providing a second set of items to iterate over.\nMore precisely, you provide the range selector `0..` to the for loop. So,\nyes, you can use two different iterators at the same time in a for\nloop in Zig.\n\nBut remember from @sec-assignments that, every object\nyou create in Zig must be used in some way. So if you declare two iterators\nin your for loop, you must use both iterators inside the for loop body.\nBut if you want to use just the index iterator, and not use the \"value iterator\",\nthen, you can discard the value iterator by maching the\nvalue items to the underscore character, like in the example below:\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n:::\n\n\n\n\n\n```\n0 | 1 | 2 | 3 | 4 |\n```\n\n\n### While loops\n\nA while loop is created from the `while` keyword. A `for` loop\niterates through the items of an array, but a `while` loop\nwill loop continuously, and infinitely, until a logical test\n(specified by you) becomes false.\n\nYou start with the `while` keyword, then, you define a logical\nexpression inside a pair of parentheses, and the body of the\nloop is provided inside a pair of curly braces, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\n\nYou can also specify the increment expression to be used at the beginning of a while loop.\nTo do that, we write the increment expression inside a pair of parentheses after a colon character (`:`).\nThe code example below demonstrates this other pattern.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\n\n### Using `break` and `continue`\n\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using\nthe keywords `break` and `continue`, respectively. The `while` loop presented in the next code example is,\nat first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to `true`.\nBut what makes this `while` loop stop when the `i` object reaches the count\n10? It is the `break` keyword!\n\nInside the while loop, we have an if statement that is constantly checking if the `i` variable\nis equal to 10. Since we are incrementing the value of `i` at each iteration of the\nwhile loop, this `i` object will eventually be equal to 10, and when it is, the if statement\nwill execute the `break` expression, and, as a result, the execution of the while loop is stopped.\n\nNotice the use of the `expect()` function from the Zig Standard Library after the while loop.\nThis `expect()` function is an \"assert\" type of function.\nThis function checks if the logical test provided is equal to true. If so, the function do nothing.\nOtherwise (i.e. the logical test is equal to false), the function raises an assertion error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nEverything worked!\n```\n\n\n:::\n:::\n\n\n\n\n\nSince this code example was executed successfully by the `zig` compiler,\nwithout raising any errors, we known that, after the execution of the while loop,\nthe `i` object is equal to 10. Because if it wasn't equal to 10, an error would have\nbeen raised by `expect()`.\n\nNow, in the next example, we have a use case for\nthe `continue` keyword. The if statement is constantly\nchecking if the current index is a multiple of 2. If\nit is, we jump to the next iteration of the loop.\nOtherwise, the loop just prints the current index to the console.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 3 | 5 | \n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n## Function parameters are immutable {#sec-fun-pars}\n\nWe have already discussed a lot of the syntax behind function declarations in @sec-root-file and @sec-main-file.\nBut I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig.\nIn summary, function parameters are immutable in Zig.\n\nTake the code example below, where we declare a simple function that just tries to add\nsome amount to the input integer, and returns the result back. If you look closely\nat the body of this `add2()` function, you will notice that we try\nto save the result back into the `x` function argument.\n\nIn other words, this function not only uses the value that it received through the function argument\n`x`, but it also tries to change the value of this function argument, by assigning the addition result\ninto `x`. However, function arguments in Zig are immutable. You cannot change their values, or, you\ncannot assign values to them inside the body's function.\n\nThis is the reason why, the code example below does not compile successfully. If you try to compile\nthis code example, you will get a compile error message about \"trying to change the value of a\nimmutable (i.e. constant) object\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n\n\n\n```\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n```\n\n\n### A free optimization\n\nIf a function argument receives as input an object whose data type is\nany of the primitive types that we have listed in @sec-primitive-data-types,\nthis object is always passed by value to the function. In other words, this object\nis copied into the function stack frame.\n\nHowever, if the input object have a more complex data type, for example, it might\nbe a struct instance, or an array, or an union value, etc., in cases like that, the `zig` compiler\nwill take the liberty of deciding for you which strategy is best. Thus, the `zig` compiler will\npass your object to the function either by value, or by reference. The compiler will always\nchoose the strategy that is faster for you.\nThis optimization that you get for free is possible only because function arguments are\nimmutable in Zig.\n\n\n### How to overcome this barrier\n\nThere are some situations where you might need to change the value of your function argument\ndirectly inside the function's body. This happens more often when we are passing\nC structs as inputs to Zig functions.\n\nIn a situation like this, you can overcome this barrier by using a pointer. In other words,\ninstead of passing a value as input to the argument, you can pass a \"pointer to value\" instead.\nYou can change the value that the pointer points to, by dereferencing it.\n\nTherefore, if we take our previous `add2()` example, we can change the value of the\nfunction argument `x` inside the function's body by marking the `x` argument as a\n\"pointer to a `u32` value\" (i.e. `*u32` data type), instead of a `u32` value.\nBy making it a pointer, we can finally alter the value of this function argument directly inside\nthe body of the `add2()` function. You can see that the code example below compiles successfully.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n```\n:::\n\n\n\n\n\n```\nResult: 6\n```\n\n\nEven in this code example above, the `x` argument is still immutable. Which means that the pointer itself is immutable.\nTherefore, you cannot change the memory address that it points to. However, you can dereference the pointer\nto access the value that it points to, and also, to change this value, if you need to.\n\n\n\n\n\n## Structs and OOP {#sec-structs-and-oop}\n\nZig is a language more closely related to C (which is a procedural language),\nthan it is to C++ or Java (which are object-oriented languages). Because of that, you do not\nhave advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or\nclass inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\n\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C.\nYou give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can\nalso register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object\nthat you create with this new type, will always have these methods available and associated with them.\n\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which\nis used to construct (or, to instantiate) every object of this particular class, and we also have\na destructor method (or a destructor function), which is the function responsible for destroying\nevery object of this class.\n\nIn Zig, we normally declare the constructor and the destructor methods\nof our structs, by declaring an `init()` and a `deinit()` methods inside the struct.\nThis is just a naming convention that you will find across the entire Zig Standard Library.\nSo, in Zig, the `init()` method of a struct is normally the constructor method of the class represented by this struct.\nWhile the `deinit()` method is the method used for destroying an existing instance of that struct.\n\nThe `init()` and `deinit()` methods are both used extensively in Zig code, and you will see both of\nthem being used when we talk about allocators in @sec-allocators.\nBut, as another example, let's build a simple `User` struct to represent a user of some sort of system.\n\nIf you look at the `User` struct below, you can see the `struct` keyword.\nNotice the data members of this struct: `id`, `name` and `email`. Every data member has its\ntype explicitly annotated, with the colon character (`:`) syntax that we described earlier in @sec-root-file.\nBut also notice that every line in the struct body that describes a data member, ends with a comma character (`,`).\nSo every time you declare a data member in your Zig code, always end the line with a comma character, instead\nof ending it with the traditional semicolon character (`;`).\n\nNext, we have registered an `init()` function as a method\nof this `User` struct. This `init()` method is the constructor method that we will use to instantiate\nevery new `User` object. That is why this `init()` function returns a new `User` object as result.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    pub fn init(id: u64,\n                name: []const u8,\n                email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    pub fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\npedro\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `pub` keyword plays an important role in struct declarations, and OOP in Zig.\nEvery method that you declare in your struct that is marked with the keyword `pub`,\nbecomes a public method of this particular struct.\n\nSo every method that you create inside your struct, is, at first, a private method\nof that struct. Meaning that, this method can only be called from within this\nstruct. But, if you mark this method as public, with the keyword `pub`, then,\nyou can call the method directly from an instance of the `User` struct.\n\nIn other words, the functions marked by the keyword `pub`\nare members of the public API of that struct.\nFor example, if I did not mark the `print_name()` method as public,\nthen, I could not execute the line `u.print_name()`. Because I would\nnot be authorized to call this method directly in my code.\n\n\n\n### Anonymous struct literals {#sec-anonymous-struct-literals}\n\nYou can declare a struct object as a literal value. When we do that, we normally specify the\ndata type of this struct literal by writing its data type just before the opening curly brace.\nFor example, I could write a struct literal value of the type `User` that we have defined\nin the previous section like this:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n```\n:::\n\n\n\n\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a\nstruct literal, but not specify explicitly the type of this particular struct.\nAn anonymous struct is written by using the syntax `.{}`. So, we essentially\nreplaced the explicit type of the struct literal with a dot character (`.`).\n\nAs we described in @sec-type-inference, when you put a dot before a struct literal,\nthe type of this struct literal is automatically inferred by the `zig` compiler.\nIn essence, the `zig` compiler will look for some hint of what is the type of that struct.\nThis hint can be the type annotation of a function argument,\nor the return type annotation of the function that you are using, or the type annotation\nof an existing object.\nIf the compiler does find such type annotation, it will use this\ntype in your literal struct.\n\nAnonymous structs are very commonly used as inputs to function arguments in Zig.\nOne example that you have seen already constantly, is the `print()`\nfunction from the `stdout` object.\nThis function takes two arguments.\nThe first argument, is a template string, which should\ncontain string format specifiers in it, which tells how the values provided\nin the second argument should be printed into the message.\n\nWhile the second argument is a struct literal that lists the values\nto be printed into the template message specified in the first argument.\nYou normally want to use an anonymous struct literal here, so that the\n`zig` compiler do the job of specifying the type of this particular\nanonymous struct for you.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello, world!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n### Struct declarations must be constant\n\nTypes in Zig must be `const` or `comptime` (we are going to talk more about comptime in @sec-comptime).\nWhat this means is that you cannot create a new data type, and mark it as variable with the `var` keyword.\nSo struct declarations are always constant. You cannot declare a new struct type using the `var` keyword.\nIt must be `const`.\n\nIn the `Vec3` example below, this declaration is allowed because I'm using the `const` keyword\nto declare this new data type.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n```\n:::\n\n\n\n\n\n\n### The `self` method argument {#sec-self-arg}\n\nIn every language that have OOP, when we declare a method of some class or struct, we\nusually declare this method as a function that has a `self` argument.\nThis `self` argument is the reference to the object itself from which the method\nis being called from.\n\nIt is not mandatory to use this `self` argument. But why would you not use this `self` argument?\nThere is no reason to not use it. Because the only way to get access to the data stored in the\ndata members of your struct is to access them through this `self` argument.\nIf you don't need to use the data in the data members of your struct inside your method, you very likely don't need\na method. You can just declare this logic as a simple function, outside of your\nstruct declaration.\n\n\nTake the `Vec3` struct below. Inside this `Vec3` struct we declared a method named `distance()`.\nThis method calculates the distance between two `Vec3` objects, by following the distance\nformula in euclidean space. Notice that this `distance()` method takes two `Vec3` objects\nas input, `self` and `other`.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n```\n:::\n\n\n\n\n\n\nThe `self` argument corresponds to the `Vec3` object from which this `distance()` method\nis being called from. While the `other` is a separate `Vec3` object that is given as input\nto this method. In the example below, the `self` argument corresponds to the object\n`v1`, because the `distance()` method is being called from the `v1` object,\nwhile the `other` argument corresponds to the object `v2`.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n```\n:::\n\n\n\n\n\n```\nDistance: 3.3970575502926055\n```\n\n\n\n### About the struct state\n\nSometimes you don't need to care about the state of your struct object. Sometimes, you just need\nto instantiate and use the objects, without altering their state. You can notice that when you have methods\ninside your struct declaration that might use the values that are present in the data members, but they\ndo not alter the values in these data members of the struct in anyway.\n\nThe `Vec3` struct that was presented in @sec-self-arg is an example of that.\nThis struct have a single method named `distance()`, and this method does use the values\npresent in all three data members of the struct (`x`, `y` and `z`). But at the same time,\nthis method does not change the values of these data members at any point.\n\nAs a result of that, when we create `Vec3` objects we usually create them as\nconstant objects, like the `v1` and `v2` objects presented in @sec-self-arg.\nWe can create them as variable objects with the `var` keyword,\nif we want to. But because the methods of this `Vec3` struct do not change\nthe state of the objects in any point, it's unnecessary to mark them\nas variable objects.\n\nBut why? Why am I talking about this here? It's because the `self` argument\nin the methods is affected depending on whether the\nmethods present in a struct change or don't change the state of the object itself.\nMore specifically, when you have a method in a struct that changes the state\nof the object (i.e. change the value of a data member), the `self` argument\nin this method must be annotated in a different manner.\n\nAs I described in @sec-self-arg, the `self` argument in methods of\na struct is the argument that receives as input the object from which the method\nwas called from. We usually annotate this argument in the methods by writing `self`,\nfollowed by the colon character (`:`), and the data type of the struct to which\nthe method belongs to (e.g. `User`, `Vec3`, etc.).\n\nIf we take the `Vec3` struct that we defined in the previous section as an example,\nwe can see in the `distance()` method that this `self` argument is annotated as\n`self: Vec3`. Because the state of the `Vec3` object is never altered by this\nmethod.\n\nBut what if we do have a method that alters the state of the object, by altering the\nvalues of its data members, how should we annotate `self` in this instance? The answer is:\n\"we should annotate `self` as a pointer of `x`, instead of just `x`\".\nIn other words, you should annotate `self` as `self: *x`, instead of annotating it\nas `self: x`.\n\nIf we create a new method inside the `Vec3` object that, for example, expands the\nvector by multiplying its coordinates by a factor of two, then, we need to follow\nthis rule specified in the previous paragraph. The code example below demonstrates\nthis idea:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n```\n:::\n\n\n\n\n\nNotice in the code example above that we have added a new method\nto our `Vec3` struct named `twice()`. This method doubles the\ncoordinate values of our vector object. In the\ncase of the `twice()` method, we annotated the `self` argument as `*Vec3`,\nindicating that this argument receives a pointer (or a reference, if you prefer to call it this way)\nto a `Vec3` object as input.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n```\n:::\n\n\n\n\n\n```\nDoubled: 8.4\n```\n\n\n\nNow, if you change the `self` argument in this `twice()` method to `self: Vec3`, like in the\n`distance()` method, you will get the compiler error exposed below as result. Notice that this\nerror message is showing a line from the `twice()` method body,\nindicating that you cannot alter the value of the `x` data member.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n```\n:::\n\n\n\n\n\n```\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\n```\n\nThis error message indicates that the `x` data member belongs to a constant object,\nand, because of that, it cannot be changed. Ultimately, this error message\nis telling us that the `self` argument is constant.\n\nIf you take some time, and think hard about this error message, you will understand it.\nYou already have the tools to understand why we are getting this error message.\nWe have talked about it already in @sec-fun-pars.\nSo remember, every function argument is immutable in Zig, and `self`\nis no exception to this rule.\n\nIn this example, we marked the `v3` object as a variable object.\nBut this does not matter. Because it is not about the input object, it is about\nthe function argument.\n\nThe problem begins when we try to alter the value of `self` directly, which is a function argument,\nand, every function argument is immutable by default. You may ask yourself how can we overcome\nthis barrier, and once again, the solution was also discussed in @sec-fun-pars.\nWe overcome this barrier, by explicitly marking the `self` argument as a pointer.\n\n\n::: {.callout-note}\nIf a method of your `x` struct alters the state of the object, by\nchanging the value of any data member, then, remember to use `self: *x`,\ninstead of `self: x` in the function signature of this method.\n:::\n\n\nYou could also interpret the content discussed in this section as:\n\"if you need to alter the state of your `x` struct object in one of its methods,\nyou must explicitly pass the `x` struct object by reference to the `self` argument of this method\".\n\n\n\n## Type inference {#sec-type-inference}\n\nZig is a strongly typed language. But, there are some situations\nwhere you don't have to explicitly write the type of every single object in your source code,\nas you would expect from a traditional strongly typed language, such as C and C++.\n\nIn some situations, the `zig` compiler can use type inference to solve the data types for you, easing some of\nthe burden that you carry as a developer.\nThe most common way this happens is through function arguments that receive struct objects\nas input.\n\nIn general, type inference in Zig is done by using the dot character (`.`).\nEverytime you see a dot character written before a struct literal, or before an enum value, or something like that,\nyou know that this dot character is playing a special party in this place. More specifically, it is\ntelling the `zig` compiler something along the lines of: \"Hey! Can you infer the type of this\nvalue for me? Please!\". In other words, this dot character is playing a similar role as the `auto` keyword in C++.\n\nI gave you some examples of this in @sec-anonymous-struct-literals, where we used anonymous struct literals.\nAnonymous struct literals are, struct literals that use type inference to\ninfer the exact type of this particular struct literal.\nThis type inference is done by looking for some minimal hint of the correct data type to be used.\nYou could say that the `zig` compiler looks for any neighbouring type annotation that might tell it\nwhat the correct type would be.\n\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in @sec-switch).\nI also gave some other examples of type inference in @sec-switch, where we were inferring the data types of enum values listed inside\nof switch statements (e.g. `.DE`).\nBut as another example, take a look at this `fence()` function reproduced below,\nwhich comes from the [`atomic.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig)[^fence-fn]\nof the Zig Standard Library.\n\n[^fence-fn]: <https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig>.\n\nThere are a lot of things in this function that we haven't talked about yet, such as:\nwhat `comptime` means? `inline`? `extern`?\nLet's just ignore all of these things, and focus solely on the switch statement\nthat is inside this function.\n\nWe can see that this switch statement uses the `order` object as input. This `order`\nobject is one of the inputs of this `fence()` function, and we can see in the type annotation,\nthat this object is of type `AtomicOrder`. We can also see a bunch of values inside the\nswitch statements that begin with a dot character, such as `.release` and `.acquire`.\n\nBecause these weird values contain a dot character before them, we are asking the `zig`\ncompiler to infer the types of these values inside the switch statement. Then, the `zig`\ncompiler is looking into the current context where these values are being used, and it is\ntrying to infer the types of these values.\n\nSince they are being used inside a switch statement, the `zig` compiler looks into the type\nof the input object given to the switch statement, which is the `order` object in this case.\nBecause this object have type `AtomicOrder`, the `zig` compiler infers that these values\nare data members from this type `AtomicOrder`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic => @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire => tsan.__tsan_acquire(addr),\n            .release => tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst => {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n```\n:::\n\n\n\n\n\nThis is how basic type inference is done in Zig. If we didn't use the dot character before\nthe values inside this switch statement, then, we would be forced to explicitly write\nthe data types of these values. For example, instead of writing `.release` we would have to\nwrite `AtomicOrder.release`. We would have to do this for every single value\nin this switch statement, and this is a lot of work. That is why type inference\nis commonly used on switch statements in Zig.\n\n\n\n## Type casting {#sec-type-cast}\n\nIn this section, I want to discuss type casting (or, type conversion) with you.\nWe use type casting when we have an object of type \"x\", and we want to convert\nit into an object of type \"y\", i.e. we want to change the data type of the object.\n\nMost languages have a formal way to perform type casting. In Rust for example, we normally\nuse the keyword `as`, and in C, we normally use the type casting syntax, e.g. `(int) x`.\nIn Zig, we use the `@as()` built-in function to cast an object of type \"x\", into\nan object of type \"y\".\n\nThis `@as()` function is the preferred way to perform type conversion (or type casting)\nin Zig. Because it is explicit, and, it also performs the casting only if it\nis unambiguous and safe. To use this function, you just provide the target data type\nin the first argument, and, the object that you want cast as the second argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n```\n:::\n\n\n\n\n\nThis is the general way to perform type casting in Zig. But remember, `@as()` works only when casting\nis unambiguous and safe, and there are situations where these assumptions do not hold. For example,\nwhen casting an integer value into a float value, or vice-versa, it is not clear to the compiler\nhow to perform this conversion safely.\n\nTherefore, we need to use specialized \"casting functions\" in such situations.\nFor example, if you want to cast an integer value into a float value, then, you\nshould use the `@floatFromInt()` function. In the inverse scenario, you should use\nthe `@intFromFloat()` function.\n\nIn these functions, you just provide the object that you want to\ncast as input. Then, the target data type of the \"type casting operation\" is determined by\nthe type annotation of the object where you are saving the results.\nIn the example below, we are casting the object `x` into a value of type `f32`,\nbecause the object `y`, which is where we are saving the results, is annotated\nas an object of type `f32`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n```\n:::\n\n\n\n\n\nAnother built-in function that is very useful when performing type casting operations is `@ptrCast()`.\nIn essence, we use the `@as()` built-in function when we want to explicit convert (or cast) a Zig value/object\nfrom a type \"x\" to a type \"y\", etc. However, pointers (we are going to discuss pointers\nin more depth in @sec-pointer) are a special type of object in Zig,\ni.e. they are treated differently from \"normal objects\".\n\nEverytime a pointer is involved in some \"type casting operation\" in Zig, the `@ptrCast()` function is used.\nThis function works similarly to `@floatFromInt()`.\nYou just provide the pointer object that you want to cast as input to this function, and the\ntarget data type is, once again, determined by the type annotation of the object where the results are being\nstored.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n```\n:::\n\n\n\n\n\n\n\n\n\n## Modules\n\nWe already talked about what modules are, and also, how to import other modules into\nyour current module via *import statements*. Every Zig module (i.e. a `.zig` file) that you write in your project\nis internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the\nZig Standard Library into our current module.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n```\n:::\n\n\n\n\n\nWhen we want to access the functions and objects from the standard library, we\nare basically accessing the data members of the struct stored in the `std`\nobject. That is why we use the same syntax that we use in normal structs, with the dot operator (`.`)\nto access the data members and methods of the struct.\n\nWhen this \"import statement\" get's executed, the result of this expression is a struct\nobject that contains the Zig Standard Library modules, global variables, functions, etc.\nAnd this struct object get's saved (or stored) inside the constant object named `std`.\n\n\nTake the [`thread_pool.zig` module from the project `zap`](https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig)[^thread]\nas an example. This module is written as if it was\na big struct. That is why we have a top-level and public `init()` method\nwritten in this module. The idea is that all top-level functions written in this\nmodule are methods from the struct, and all top-level objects and struct declarations\nare data members of this struct. The module is the struct itself.\n\n[^thread]: <https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig>\n\n\nSo you would import and use this module by doing something like this:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst ThreadPool = @import(\"thread_pool.zig\");\nconst num_cpus = std.Thread.getCpuCount()\n    catch @panic(\"failed to get cpu core count\");\nconst num_threads = std.math.cast(u16, num_cpus)\n    catch std.math.maxInt(u16);\nconst pool = ThreadPool.init(\n    .{ .max_threads = num_threads }\n);\n```\n:::\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Control flow, structs, modules and types\n\nWe have discussed a lot of Zig's syntax in the last chapter,\nespecially in @sec-root-file and @sec-main-file.\nBut we still need to discuss some other very important\nelements of the language. Elements that you will use constantly on your day-to-day\nroutine.\n\nWe begin this chapter by discussing the different keywords and structures\nin Zig related to control flow (e.g. loops and if statements).\nThen, we talk about structs and how they can be used to do some\nbasic Object-Oriented (OOP) patterns in Zig. We also talk about\ntype inference and type casting.\nFinally, we end this chapter by discussing modules, and how they relate\nto structs.\n\n\n\n## Control flow {#sec-zig-control-flow}\n\nSometimes, you need to make decisions in your program. Maybe you need to decide\nwhether or not to execute a specific piece of code. Or maybe,\nyou need to apply the same operation over a sequence of values. These kinds of tasks,\ninvolve using structures that are capable of changing the \"control flow\" of our program.\n\nIn computer science, the term \"control flow\" usually refers to the order in which expressions (or commands)\nare evaluated in a given language or program. But this term is also used to refer\nto structures that are capable of changing this \"evaluation order\" of the commands\nexecuted by a given language/program.\n\nThese structures are better known\nby a set of terms, such as: loops, if/else statements, switch statements, among others. So,\nloops and if/else statements are examples of structures that can change the \"control\nflow\" of our program. The keywords `continue` and `break` are also examples of symbols\nthat can change the order of evaluation, since they can move our program to the next iteration\nof a loop, or make the loop stop completely.\n\n\n### If/else statements\n\nAn if/else statement performs a \"conditional flow operation\".\nA conditional flow control (or choice control) allows you to execute\nor ignore a certain block of commands based on a logical condition.\nMany programmers and computer science professionals also use\nthe term \"branching\" in this case.\nIn essence, an if/else statement allow us to use the result of a logical test\nto decide whether or not to execute a given block of commands.\n\nIn Zig, we write if/else statements by using the keywords `if` and `else`.\nWe start with the `if` keyword followed by a logical test inside a pair\nof parentheses, followed by a pair of curly braces which contains the lines\nof code to be executed in case the logical test returns the value `true`.\n\nAfter that, you can optionally add an `else` statement. To do that, just add the `else`\nkeyword followed by a pair of curly braces, with the lines of code\nto executed in case the logical test defined at `if` returns `false`.\n\nIn the example below, we are testing if the object `x` contains a number\nthat is greater than 10. Judging by the output printed to the console,\nwe know that this logical test returned `false`. Because the output\nin the console is compatible with the line of code present in the\n`else` branch of the if/else statement.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x = 5;\nif (x > 10) {\n    try stdout.print(\n        \"x > 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x <= 10!\\n\", .{}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nx <= 10!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Switch statements {#sec-switch}\n\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust.\nAs you would expect, to write a switch statement in Zig we use the `switch` keyword.\nWe provide the value that we want to \"switch over\" inside a\npair of parentheses. Then, we list the possible combinations (or \"branches\")\ninside a pair of curly braces.\n\nLet's take a look at the code example below. You can see that\nI'm creating an enum type called `Role`. We talk more about enums in @sec-enum.\nBut in summary, this `Role` type is listing different types of roles in a fictitious\ncompany, like `SE` for Software Engineer, `DE` for Data Engineer, `PM` for Product Manager,\netc.\n\nNotice that we are using the value from the `role` object in the\nswitch statement, to discover which exact area we need to store in the `area` variable object.\nAlso notice that we are using type inference inside the switch statement, with the dot character,\nas we are going to describe in @sec-type-inference.\nThis makes the `zig` compiler infer the correct data type of the values (`PM`, `SE`, etc.) for us.\n\nAlso notice that, we are grouping multiple values in the same branch of the switch statement.\nWe just separate each possible value with a comma. For example, if `role` contains either `DE` or `DA`,\nthe `area` variable would contain the value `\"Data & Analytics\"`, instead of `\"Platform\"` or `\"Sales\"`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO => {\n            area = \"Platform\";\n        },\n        .DE, .DA => {\n            area = \"Data & Analytics\";\n        },\n        .KS => {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nPlatform\n```\n\n\n:::\n:::\n\n\n\n\n\n#### Switch statements must exhaust all possibilities\n\nOne very important aspect about switch statements in Zig\nis that they must exhaust all existing possibilities.\nIn other words, all possible values that could be found inside the `order`\nobject must be explicitly handled in this switch statement.\n\nSince the `role` object have type `Role`, the only possible values to\nbe found inside this object are `PM`, `SE`, `DPE`, `PO`, `DE`, `DA` and `KS`.\nThere are no other possible values to be stored in this `role` object.\nThus, the switch statements must have a combination (branch) for each one of these values.\nThis is what \"exhaust all existing possibilities\" means. The switch statement covers\nevery possible case.\n\nTherefore, you cannot write a switch statement in Zig, and leave an edge case\nwith no explicit action to be taken.\nThis is a similar behaviour to switch statements in Rust, which also have to\nhandle all possible cases.\n\n\n\n#### The else branch\n\nTake a look at the `dump_hex_fallible()` function below as an example. This function\ncomes from the Zig Standard Library. More precisely, from the\n[`debug.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/debug.zig)[^debug-mod].\nThere are multiple lines in this function, but I omitted them to focus solely on the\nswitch statement found in this function. Notice that this switch statement has four\npossible cases (i.e. four explicit branches). Also, notice that we used an `else` branch\nin this case.\n\nAn `else` branch in a switch statement works as the \"default branch\".\nWhenever you have multiple cases in your switch statement where\nyou want to apply the exact same action, you can use an `else` branch to do that.\n\n[^debug-mod]: <https://github.com/ziglang/zig/blob/master/lib/std/debug.zig>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' => try writer.writeAll(\"␊\"),\n        '\\r' => try writer.writeAll(\"␍\"),\n        '\\t' => try writer.writeAll(\"␉\"),\n        else => try writer.writeByte('.'),\n    }\n}\n```\n:::\n\n\n\n\nMany programmers would also use an `else` branch to handle a \"not supported\" case.\nThat is, a case that cannot be properly handled by your code, or, just a case that\nshould not be \"fixed\". Therefore, you can use an `else` branch to panic (or raise an error)\nin your program to stop the current execution.\n\nTake the code example below. We can see that, we are handling the cases\nfor the `level` object being either 1, 2, or 3. All other possible cases are not supported by default,\nand, as consequence, we raise a runtime error in such cases through the `@panic()` built-in function.\n\nAlso notice that, we are assigning the result of the switch statement to a new object called `category`.\nThis is another thing that you can do with switch statements in Zig. If a branch\noutputs a value as result, you can store the result value of the switch statement into\na new object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 => \"beginner\",\n    3 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n:::\n\n\n\n\n```\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n```\n\n\n\n#### Using ranges in switch\n\nFurthermore, you can also use ranges of values in switch statements.\nThat is, you can create a branch in your switch statement that is used\nwhenever the input value is within the specified range. These \"range expressions\"\nare created with the operator `...`. It is important\nto emphasize that the ranges created by this operator are\ninclusive on both ends.\n\nFor example, I could easily change the previous code example to support all\nlevels between 0 and 100. Like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 => \"beginner\",\n    26...75 => \"intermediary\",\n    76...100 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nbeginner\n```\n\n\n:::\n:::\n\n\n\n\nThis is neat, and it works with character ranges too. That is, I could\nsimply write `'a'...'z'`, to match any character value that is a\nlowercase letter, and it would work fine.\n\n\n#### Labeled switch statements\n\nIn @sec-blocks we have talked about labeling blocks, and also, about using these labels\nto return a value from the block. Well, from version 0.14.0 and onwards of the `zig` compiler,\nyou can also apply labels over switch statements, which makes it possible to almost implement a\n\"C `goto`\" like pattern.\n\nFor example, if you give the label `xsw` to a switch statement, you can use this\nlabel in conjunction with the `continue` keyword to go back to the beginning of the switch\nstatement. In the example below, the execution goes back to the beginning of the\nswitch statement two times, before ending at the `3` branch.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nxsw: switch (@as(u8, 1)) {\n    1 => {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 => continue :xsw 3,\n    3 => return,\n    4 => {},\n    else => {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n```\n:::\n\n\n\n\n\n### The `defer` keyword {#sec-defer}\n\nWith the `defer` keyword you can register an expression to be executed when you exit the current scope.\nTherefore, this keyword has a similar functionality as the `on.exit()` function from R.\nTake the `foo()` function below as an example. When we execute this `foo()` function, the expression\nthat prints the message \"Exiting function ...\" is getting executed only when the function exits\nits scope.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nAdding some numbers ...\nMultiplying ...\nExiting function ...\n```\n\nTherefore, we can use `defer` to declare an expression that is going to be executed\nwhen your code exits the current scope. Some programmers like to interpret the phrase \"exit of the current scope\"\nas \"the end of the current scope\". But this interpretation might not be entirely correct, depending\non what you consider as \"the end of the current scope\".\n\nI mean, what do you consider as **the end** of the current scope? Is it the closing curly bracket (`}`) of the scope?\nIs it when the last expression in the function get's executed? Is it when the function returns to the previous scope?\nEtc. For example, it would not be correct to interpret the \"exit of the current scope\" as the closing\ncurly bracket of the scope. Because the function might exit from an earlier position than this\nclosing curly bracket (e.g. an error value was generated at a previous line inside the function;\nthe function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\n\nNow, if you remember of what we have discussed in @sec-blocks, there are multiple structures in the language\nthat create their own separate scopes. For/while loops, if/else statements,\nfunctions, normal blocks, etc. This also affects the interpretation of `defer`.\nFor example, if you use `defer` inside a for loop, then, the given expression\nwill be executed everytime this specific for loop exits its own scope.\n\nBefore we continue, is worth emphasizing that the `defer` keyword is an \"unconditional defer\".\nWhich means that the given expression will be executed no matter how the code exits\nthe current scope. For example, your code might exit the current scope because of an error value\nbeing generated, or, because of a return statement, or, a break statement, etc.\n\n\n\n### The `errdefer` keyword {#sec-errdefer1}\n\nOn the previous section, we have discussed the `defer` keyword, which you can use to\nregister an expression to be executed at the exit of the current scope.\nBut this keyword has a brother, which is the `errdefer` keyword. While `defer`\nis an \"unconditional defer\", the `errdefer` keyword is a \"conditional defer\".\nWhich means that the given expression is executed only when you exit the current\nscope on a very specific circumstance.\n\nIn more details, the expression given to `errdefer` is executed only when an error occurs in the current scope.\nTherefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope\nin a normal situation, without errors, the expression given to `errdefer` is not executed.\n\nThis makes the `errdefer` keyword one of the many tools available in Zig for error handling.\nIn this section, we are more concerned with the control flow aspects around `errdefer`.\nBut we are going to discuss `errdefer` later as a error handling tool in @sec-errdefer2.\n\nThe code example below demonstrates three things:\n\n- that `defer` is an \"unconditional defer\", because the given expression get's executed regardless of how the function `foo()` exits its own scope.\n- that `errdefer` is executed because the function `foo()` returned an error value.\n- that `defer` and `errdefer` expressions are executed in a LIFO (*last in, first out*) order.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\nWhen I say that \"defer expressions\" are executed in a LIFO order, what I want to say is that\nthe last `defer` or `errdefer` expressions in the code are the first ones to be executed.\nYou could also interpret this as: \"defer expressions\" are executed from bottom to top, or,\nfrom last to first.\n\nTherefore, if I change the order of the `defer` and `errdefer` expressions, you will notice that\nthe value of `i` that get's printed to the console changes to 1. This doesn't mean that the\n`defer` expression was not executed in this case. This actually means that the `defer` expression\nwas executed only after the `errdefer` expression. The code example below demonstrates this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\n\n\n### For loops\n\nA loop allows you to execute the same lines of code multiple times,\nthus, creating a \"repetition space\" in the execution flow of your program.\nLoops are particularly useful when we want to replicate the same function\n(or the same set of commands) over different inputs.\n\nThere are different types of loops available in Zig. But the most\nessential of them all is probably the *for loop*. A for loop is\nused to apply the same piece of code over the elements of a slice, or, an array.\n\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from\nother languages. You start with the `for` keyword, then, you\nlist the items that you want to iterate\nover inside a pair of parentheses. Then, inside of a pair of pipes (`|`)\nyou should declare an identifier that will serve as your iterator, or,\nthe \"repetition index of the loop\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (items) |value| {\n    // code to execute\n}\n```\n:::\n\n\n\n\nTherefore, instead of using a `(value in items)` syntax,\nin Zig, for loops use the syntax `(items) |value|`. In the example\nbelow, you can see that we are looping through the items\nof the array stored at the object `name`, and printing to the\nconsole the decimal representation of each character in this array.\n\nIf we wanted, we could also iterate through a slice (or a portion) of\nthe array, instead of iterating through the entire array stored in the `name` object.\nJust use a range selector to select the section you want. For example,\nI could provide the expression `name[0..3]` to the for loop, to iterate\njust through the first 3 elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n80 | 101 | 100 | 114 | 111 | \n```\n\n\n:::\n:::\n\n\n\n\nIn the above example we are using the value itself of each\nelement in the array as our iterator. But there are many situations where\nwe need to use an index instead of the actual values of the items.\n\nYou can do that by providing a second set of items to iterate over.\nMore precisely, you provide the range selector `0..` to the for loop. So,\nyes, you can use two different iterators at the same time in a for\nloop in Zig.\n\nBut remember from @sec-assignments that, every object\nyou create in Zig must be used in some way. So if you declare two iterators\nin your for loop, you must use both iterators inside the for loop body.\nBut if you want to use just the index iterator, and not use the \"value iterator\",\nthen, you can discard the value iterator by maching the\nvalue items to the underscore character, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n:::\n\n\n\n\n```\n0 | 1 | 2 | 3 | 4 |\n```\n\n\n### While loops\n\nA while loop is created from the `while` keyword. A `for` loop\niterates through the items of an array, but a `while` loop\nwill loop continuously, and infinitely, until a logical test\n(specified by you) becomes false.\n\nYou start with the `while` keyword, then, you define a logical\nexpression inside a pair of parentheses, and the body of the\nloop is provided inside a pair of curly braces, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\nYou can also specify the increment expression to be used at the beginning of a while loop.\nTo do that, we write the increment expression inside a pair of parentheses after a colon character (`:`).\nThe code example below demonstrates this other pattern.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\n### Using `break` and `continue`\n\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using\nthe keywords `break` and `continue`, respectively. The `while` loop presented in the next code example is,\nat first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to `true`.\nBut what makes this `while` loop stop when the `i` object reaches the count\n10? It is the `break` keyword!\n\nInside the while loop, we have an if statement that is constantly checking if the `i` variable\nis equal to 10. Since we are incrementing the value of `i` at each iteration of the\nwhile loop, this `i` object will eventually be equal to 10, and when it is, the if statement\nwill execute the `break` expression, and, as a result, the execution of the while loop is stopped.\n\nNotice the use of the `expect()` function from the Zig Standard Library after the while loop.\nThis `expect()` function is an \"assert\" type of function.\nThis function checks if the logical test provided is equal to true. If so, the function do nothing.\nOtherwise (i.e. the logical test is equal to false), the function raises an assertion error.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nEverything worked!\n```\n\n\n:::\n:::\n\n\n\n\nSince this code example was executed successfully by the `zig` compiler,\nwithout raising any errors, we known that, after the execution of the while loop,\nthe `i` object is equal to 10. Because if it wasn't equal to 10, an error would have\nbeen raised by `expect()`.\n\nNow, in the next example, we have a use case for\nthe `continue` keyword. The if statement is constantly\nchecking if the current index is a multiple of 2. If\nit is, we jump to the next iteration of the loop.\nOtherwise, the loop just prints the current index to the console.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 3 | 5 | \n```\n\n\n:::\n:::\n\n\n\n\n\n\n## Function parameters are immutable {#sec-fun-pars}\n\nWe have already discussed a lot of the syntax behind function declarations in @sec-root-file and @sec-main-file.\nBut I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig.\nIn summary, function parameters are immutable in Zig.\n\nTake the code example below, where we declare a simple function that just tries to add\nsome amount to the input integer, and returns the result back. If you look closely\nat the body of this `add2()` function, you will notice that we try\nto save the result back into the `x` function argument.\n\nIn other words, this function not only uses the value that it received through the function argument\n`x`, but it also tries to change the value of this function argument, by assigning the addition result\ninto `x`. However, function arguments in Zig are immutable. You cannot change their values, or, you\ncannot assign values to them inside the body's function.\n\nThis is the reason why, the code example below does not compile successfully. If you try to compile\nthis code example, you will get a compile error message about \"trying to change the value of a\nimmutable (i.e. constant) object\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n\n\n```\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n```\n\n\n### A free optimization\n\nIf a function argument receives as input an object whose data type is\nany of the primitive types that we have listed in @sec-primitive-data-types,\nthis object is always passed by value to the function. In other words, this object\nis copied into the function stack frame.\n\nHowever, if the input object have a more complex data type, for example, it might\nbe a struct instance, or an array, or an union value, etc., in cases like that, the `zig` compiler\nwill take the liberty of deciding for you which strategy is best. Thus, the `zig` compiler will\npass your object to the function either by value, or by reference. The compiler will always\nchoose the strategy that is faster for you.\nThis optimization that you get for free is possible only because function arguments are\nimmutable in Zig.\n\n\n### How to overcome this barrier\n\nThere are some situations where you might need to change the value of your function argument\ndirectly inside the function's body. This happens more often when we are passing\nC structs as inputs to Zig functions.\n\nIn a situation like this, you can overcome this barrier by using a pointer. In other words,\ninstead of passing a value as input to the argument, you can pass a \"pointer to value\" instead.\nYou can change the value that the pointer points to, by dereferencing it.\n\nTherefore, if we take our previous `add2()` example, we can change the value of the\nfunction argument `x` inside the function's body by marking the `x` argument as a\n\"pointer to a `u32` value\" (i.e. `*u32` data type), instead of a `u32` value.\nBy making it a pointer, we can finally alter the value of this function argument directly inside\nthe body of the `add2()` function. You can see that the code example below compiles successfully.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n```\n:::\n\n\n\n\n```\nResult: 6\n```\n\n\nEven in this code example above, the `x` argument is still immutable. Which means that the pointer itself is immutable.\nTherefore, you cannot change the memory address that it points to. However, you can dereference the pointer\nto access the value that it points to, and also, to change this value, if you need to.\n\n\n\n\n\n## Structs and OOP {#sec-structs-and-oop}\n\nZig is a language more closely related to C (which is a procedural language),\nthan it is to C++ or Java (which are object-oriented languages). Because of that, you do not\nhave advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or\nclass inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\n\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C.\nYou give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can\nalso register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object\nthat you create with this new type, will always have these methods available and associated with them.\n\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which\nis used to construct (or, to instantiate) every object of this particular class, and we also have\na destructor method (or a destructor function), which is the function responsible for destroying\nevery object of this class.\n\nIn Zig, we normally declare the constructor and the destructor methods\nof our structs, by declaring an `init()` and a `deinit()` methods inside the struct.\nThis is just a naming convention that you will find across the entire Zig Standard Library.\nSo, in Zig, the `init()` method of a struct is normally the constructor method of the class represented by this struct.\nWhile the `deinit()` method is the method used for destroying an existing instance of that struct.\n\nThe `init()` and `deinit()` methods are both used extensively in Zig code, and you will see both of\nthem being used when we talk about allocators in @sec-allocators.\nBut, as another example, let's build a simple `User` struct to represent a user of some sort of system.\n\nIf you look at the `User` struct below, you can see the `struct` keyword.\nNotice the data members of this struct: `id`, `name` and `email`. Every data member has its\ntype explicitly annotated, with the colon character (`:`) syntax that we described earlier in @sec-root-file.\nBut also notice that every line in the struct body that describes a data member, ends with a comma character (`,`).\nSo every time you declare a data member in your Zig code, always end the line with a comma character, instead\nof ending it with the traditional semicolon character (`;`).\n\nNext, we have registered an `init()` function as a method\nof this `User` struct. This `init()` method is the constructor method that we will use to instantiate\nevery new `User` object. That is why this `init()` function returns a new `User` object as result.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    pub fn init(id: u64,\n                name: []const u8,\n                email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    pub fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\npedro\n```\n\n\n:::\n:::\n\n\n\n\nThe `pub` keyword plays an important role in struct declarations, and OOP in Zig.\nEvery method that you declare in your struct that is marked with the keyword `pub`,\nbecomes a public method of this particular struct.\n\nSo every method that you create inside your struct, is, at first, a private method\nof that struct. Meaning that, this method can only be called from within this\nstruct. But, if you mark this method as public, with the keyword `pub`, then,\nyou can call the method directly from an instance of the `User` struct.\n\nIn other words, the functions marked by the keyword `pub`\nare members of the public API of that struct.\nFor example, if I did not mark the `print_name()` method as public,\nthen, I could not execute the line `u.print_name()`. Because I would\nnot be authorized to call this method directly in my code.\n\n\n\n### Anonymous struct literals {#sec-anonymous-struct-literals}\n\nYou can declare a struct object as a literal value. When we do that, we normally specify the\ndata type of this struct literal by writing its data type just before the opening curly brace.\nFor example, I could write a struct literal value of the type `User` that we have defined\nin the previous section like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n```\n:::\n\n\n\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a\nstruct literal, but not specify explicitly the type of this particular struct.\nAn anonymous struct is written by using the syntax `.{}`. So, we essentially\nreplaced the explicit type of the struct literal with a dot character (`.`).\n\nAs we described in @sec-type-inference, when you put a dot before a struct literal,\nthe type of this struct literal is automatically inferred by the `zig` compiler.\nIn essence, the `zig` compiler will look for some hint of what is the type of that struct.\nThis hint can be the type annotation of a function argument,\nor the return type annotation of the function that you are using, or the type annotation\nof an existing object.\nIf the compiler does find such type annotation, it will use this\ntype in your literal struct.\n\nAnonymous structs are very commonly used as inputs to function arguments in Zig.\nOne example that you have seen already constantly, is the `print()`\nfunction from the `stdout` object.\nThis function takes two arguments.\nThe first argument, is a template string, which should\ncontain string format specifiers in it, which tells how the values provided\nin the second argument should be printed into the message.\n\nWhile the second argument is a struct literal that lists the values\nto be printed into the template message specified in the first argument.\nYou normally want to use an anonymous struct literal here, so that the\n`zig` compiler do the job of specifying the type of this particular\nanonymous struct for you.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello, world!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Struct declarations must be constant\n\nTypes in Zig must be `const` or `comptime` (we are going to talk more about comptime in @sec-comptime).\nWhat this means is that you cannot create a new data type, and mark it as variable with the `var` keyword.\nSo struct declarations are always constant. You cannot declare a new struct type using the `var` keyword.\nIt must be `const`.\n\nIn the `Vec3` example below, this declaration is allowed because I'm using the `const` keyword\nto declare this new data type.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n```\n:::\n\n\n\n\n\n### The `self` method argument {#sec-self-arg}\n\nIn every language that have OOP, when we declare a method of some class or struct, we\nusually declare this method as a function that has a `self` argument.\nThis `self` argument is the reference to the object itself from which the method\nis being called from.\n\nIt is not mandatory to use this `self` argument. But why would you not use this `self` argument?\nThere is no reason to not use it. Because the only way to get access to the data stored in the\ndata members of your struct is to access them through this `self` argument.\nIf you don't need to use the data in the data members of your struct inside your method, you very likely don't need\na method. You can just declare this logic as a simple function, outside of your\nstruct declaration.\n\n\nTake the `Vec3` struct below. Inside this `Vec3` struct we declared a method named `distance()`.\nThis method calculates the distance between two `Vec3` objects, by following the distance\nformula in euclidean space. Notice that this `distance()` method takes two `Vec3` objects\nas input, `self` and `other`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n```\n:::\n\n\n\n\n\nThe `self` argument corresponds to the `Vec3` object from which this `distance()` method\nis being called from. While the `other` is a separate `Vec3` object that is given as input\nto this method. In the example below, the `self` argument corresponds to the object\n`v1`, because the `distance()` method is being called from the `v1` object,\nwhile the `other` argument corresponds to the object `v2`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n```\n:::\n\n\n\n\n```\nDistance: 3.3970575502926055\n```\n\n\n\n### About the struct state\n\nSometimes you don't need to care about the state of your struct object. Sometimes, you just need\nto instantiate and use the objects, without altering their state. You can notice that when you have methods\ninside your struct declaration that might use the values that are present in the data members, but they\ndo not alter the values in these data members of the struct in anyway.\n\nThe `Vec3` struct that was presented in @sec-self-arg is an example of that.\nThis struct have a single method named `distance()`, and this method does use the values\npresent in all three data members of the struct (`x`, `y` and `z`). But at the same time,\nthis method does not change the values of these data members at any point.\n\nAs a result of that, when we create `Vec3` objects we usually create them as\nconstant objects, like the `v1` and `v2` objects presented in @sec-self-arg.\nWe can create them as variable objects with the `var` keyword,\nif we want to. But because the methods of this `Vec3` struct do not change\nthe state of the objects in any point, it's unnecessary to mark them\nas variable objects.\n\nBut why? Why am I talking about this here? It's because the `self` argument\nin the methods is affected depending on whether the\nmethods present in a struct change or don't change the state of the object itself.\nMore specifically, when you have a method in a struct that changes the state\nof the object (i.e. change the value of a data member), the `self` argument\nin this method must be annotated in a different manner.\n\nAs I described in @sec-self-arg, the `self` argument in methods of\na struct is the argument that receives as input the object from which the method\nwas called from. We usually annotate this argument in the methods by writing `self`,\nfollowed by the colon character (`:`), and the data type of the struct to which\nthe method belongs to (e.g. `User`, `Vec3`, etc.).\n\nIf we take the `Vec3` struct that we defined in the previous section as an example,\nwe can see in the `distance()` method that this `self` argument is annotated as\n`self: Vec3`. Because the state of the `Vec3` object is never altered by this\nmethod.\n\nBut what if we do have a method that alters the state of the object, by altering the\nvalues of its data members, how should we annotate `self` in this instance? The answer is:\n\"we should annotate `self` as a pointer of `x`, instead of just `x`\".\nIn other words, you should annotate `self` as `self: *x`, instead of annotating it\nas `self: x`.\n\nIf we create a new method inside the `Vec3` object that, for example, expands the\nvector by multiplying its coordinates by a factor of two, then, we need to follow\nthis rule specified in the previous paragraph. The code example below demonstrates\nthis idea:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n```\n:::\n\n\n\n\nNotice in the code example above that we have added a new method\nto our `Vec3` struct named `twice()`. This method doubles the\ncoordinate values of our vector object. In the\ncase of the `twice()` method, we annotated the `self` argument as `*Vec3`,\nindicating that this argument receives a pointer (or a reference, if you prefer to call it this way)\nto a `Vec3` object as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n```\n:::\n\n\n\n\n```\nDoubled: 8.4\n```\n\n\n\nNow, if you change the `self` argument in this `twice()` method to `self: Vec3`, like in the\n`distance()` method, you will get the compiler error exposed below as result. Notice that this\nerror message is showing a line from the `twice()` method body,\nindicating that you cannot alter the value of the `x` data member.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n```\n:::\n\n\n\n\n```\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\n```\n\nThis error message indicates that the `x` data member belongs to a constant object,\nand, because of that, it cannot be changed. Ultimately, this error message\nis telling us that the `self` argument is constant.\n\nIf you take some time, and think hard about this error message, you will understand it.\nYou already have the tools to understand why we are getting this error message.\nWe have talked about it already in @sec-fun-pars.\nSo remember, every function argument is immutable in Zig, and `self`\nis no exception to this rule.\n\nIn this example, we marked the `v3` object as a variable object.\nBut this does not matter. Because it is not about the input object, it is about\nthe function argument.\n\nThe problem begins when we try to alter the value of `self` directly, which is a function argument,\nand, every function argument is immutable by default. You may ask yourself how can we overcome\nthis barrier, and once again, the solution was also discussed in @sec-fun-pars.\nWe overcome this barrier, by explicitly marking the `self` argument as a pointer.\n\n\n::: {.callout-note}\nIf a method of your `x` struct alters the state of the object, by\nchanging the value of any data member, then, remember to use `self: *x`,\ninstead of `self: x` in the function signature of this method.\n:::\n\n\nYou could also interpret the content discussed in this section as:\n\"if you need to alter the state of your `x` struct object in one of its methods,\nyou must explicitly pass the `x` struct object by reference to the `self` argument of this method\".\n\n\n\n## Type inference {#sec-type-inference}\n\nZig is a strongly typed language. But, there are some situations\nwhere you don't have to explicitly write the type of every single object in your source code,\nas you would expect from a traditional strongly typed language, such as C and C++.\n\nIn some situations, the `zig` compiler can use type inference to solve the data types for you, easing some of\nthe burden that you carry as a developer.\nThe most common way this happens is through function arguments that receive struct objects\nas input.\n\nIn general, type inference in Zig is done by using the dot character (`.`).\nEverytime you see a dot character written before a struct literal, or before an enum value, or something like that,\nyou know that this dot character is playing a special party in this place. More specifically, it is\ntelling the `zig` compiler something along the lines of: \"Hey! Can you infer the type of this\nvalue for me? Please!\". In other words, this dot character is playing a similar role as the `auto` keyword in C++.\n\nI gave you some examples of this in @sec-anonymous-struct-literals, where we used anonymous struct literals.\nAnonymous struct literals are, struct literals that use type inference to\ninfer the exact type of this particular struct literal.\nThis type inference is done by looking for some minimal hint of the correct data type to be used.\nYou could say that the `zig` compiler looks for any neighbouring type annotation that might tell it\nwhat the correct type would be.\n\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in @sec-switch).\nI also gave some other examples of type inference in @sec-switch, where we were inferring the data types of enum values listed inside\nof switch statements (e.g. `.DE`).\nBut as another example, take a look at this `fence()` function reproduced below,\nwhich comes from the [`atomic.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig)[^fence-fn]\nof the Zig Standard Library.\n\n[^fence-fn]: <https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig>.\n\nThere are a lot of things in this function that we haven't talked about yet, such as:\nwhat `comptime` means? `inline`? `extern`?\nLet's just ignore all of these things, and focus solely on the switch statement\nthat is inside this function.\n\nWe can see that this switch statement uses the `order` object as input. This `order`\nobject is one of the inputs of this `fence()` function, and we can see in the type annotation,\nthat this object is of type `AtomicOrder`. We can also see a bunch of values inside the\nswitch statements that begin with a dot character, such as `.release` and `.acquire`.\n\nBecause these weird values contain a dot character before them, we are asking the `zig`\ncompiler to infer the types of these values inside the switch statement. Then, the `zig`\ncompiler is looking into the current context where these values are being used, and it is\ntrying to infer the types of these values.\n\nSince they are being used inside a switch statement, the `zig` compiler looks into the type\nof the input object given to the switch statement, which is the `order` object in this case.\nBecause this object have type `AtomicOrder`, the `zig` compiler infers that these values\nare data members from this type `AtomicOrder`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic => @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire => tsan.__tsan_acquire(addr),\n            .release => tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst => {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n```\n:::\n\n\n\n\nThis is how basic type inference is done in Zig. If we didn't use the dot character before\nthe values inside this switch statement, then, we would be forced to explicitly write\nthe data types of these values. For example, instead of writing `.release` we would have to\nwrite `AtomicOrder.release`. We would have to do this for every single value\nin this switch statement, and this is a lot of work. That is why type inference\nis commonly used on switch statements in Zig.\n\n\n\n## Type casting {#sec-type-cast}\n\nIn this section, I want to discuss type casting (or, type conversion) with you.\nWe use type casting when we have an object of type \"x\", and we want to convert\nit into an object of type \"y\", i.e. we want to change the data type of the object.\n\nMost languages have a formal way to perform type casting. In Rust for example, we normally\nuse the keyword `as`, and in C, we normally use the type casting syntax, e.g. `(int) x`.\nIn Zig, we use the `@as()` built-in function to cast an object of type \"x\", into\nan object of type \"y\".\n\nThis `@as()` function is the preferred way to perform type conversion (or type casting)\nin Zig. Because it is explicit, and, it also performs the casting only if it\nis unambiguous and safe. To use this function, you just provide the target data type\nin the first argument, and, the object that you want cast as the second argument.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n```\n:::\n\n\n\n\nThis is the general way to perform type casting in Zig. But remember, `@as()` works only when casting\nis unambiguous and safe, and there are situations where these assumptions do not hold. For example,\nwhen casting an integer value into a float value, or vice-versa, it is not clear to the compiler\nhow to perform this conversion safely.\n\nTherefore, we need to use specialized \"casting functions\" in such situations.\nFor example, if you want to cast an integer value into a float value, then, you\nshould use the `@floatFromInt()` function. In the inverse scenario, you should use\nthe `@intFromFloat()` function.\n\nIn these functions, you just provide the object that you want to\ncast as input. Then, the target data type of the \"type casting operation\" is determined by\nthe type annotation of the object where you are saving the results.\nIn the example below, we are casting the object `x` into a value of type `f32`,\nbecause the object `y`, which is where we are saving the results, is annotated\nas an object of type `f32`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n```\n:::\n\n\n\n\nAnother built-in function that is very useful when performing type casting operations is `@ptrCast()`.\nIn essence, we use the `@as()` built-in function when we want to explicit convert (or cast) a Zig value/object\nfrom a type \"x\" to a type \"y\", etc. However, pointers (we are going to discuss pointers\nin more depth in @sec-pointer) are a special type of object in Zig,\ni.e. they are treated differently from \"normal objects\".\n\nEverytime a pointer is involved in some \"type casting operation\" in Zig, the `@ptrCast()` function is used.\nThis function works similarly to `@floatFromInt()`.\nYou just provide the pointer object that you want to cast as input to this function, and the\ntarget data type is, once again, determined by the type annotation of the object where the results are being\nstored.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n```\n:::\n\n\n\n\n\n\n\n\n## Modules\n\nWe already talked about what modules are, and also, how to import other modules into\nyour current module via *import statements*. Every Zig module (i.e. a `.zig` file) that you write in your project\nis internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the\nZig Standard Library into our current module.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n```\n:::\n\n\n\n\nWhen we want to access the functions and objects from the standard library, we\nare basically accessing the data members of the struct stored in the `std`\nobject. That is why we use the same syntax that we use in normal structs, with the dot operator (`.`)\nto access the data members and methods of the struct.\n\nWhen this \"import statement\" get's executed, the result of this expression is a struct\nobject that contains the Zig Standard Library modules, global variables, functions, etc.\nAnd this struct object get's saved (or stored) inside the constant object named `std`.\n\n\nTake the [`thread_pool.zig` module from the project `zap`](https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig)[^thread]\nas an example. This module is written as if it was\na big struct. That is why we have a top-level and public `init()` method\nwritten in this module. The idea is that all top-level functions written in this\nmodule are methods from the struct, and all top-level objects and struct declarations\nare data members of this struct. The module is the struct itself.\n\n[^thread]: <https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig>\n\n\nSo you would import and use this module by doing something like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst ThreadPool = @import(\"thread_pool.zig\");\nconst num_cpus = std.Thread.getCpuCount()\n    catch @panic(\"failed to get cpu core count\");\nconst num_threads = std.math.cast(u16, num_cpus)\n    catch std.math.maxInt(u16);\nconst pool = ThreadPool.init(\n    .{ .max_threads = num_threads }\n);\n```\n:::\n",
+    "supporting": [
+      "03-structs_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/docs/Chapters/03-structs.html b/docs/Chapters/03-structs.html
index e4dfa23f..a9014775 100644
--- a/docs/Chapters/03-structs.html
+++ b/docs/Chapters/03-structs.html
@@ -464,7 +464,12 @@ <h4 data-number="2.1.2.4" class="anchored" data-anchor-id="labeled-switch-statem
 <span id="cb10-6"><a href="#cb10-6" aria-hidden="true" tabindex="-1"></a>    <span class="dv">2</span> =&gt; <span class="kw">continue</span> :xsw <span class="dv">3</span>,</span>
 <span id="cb10-7"><a href="#cb10-7" aria-hidden="true" tabindex="-1"></a>    <span class="dv">3</span> =&gt; <span class="kw">return</span>,</span>
 <span id="cb10-8"><a href="#cb10-8" aria-hidden="true" tabindex="-1"></a>    <span class="dv">4</span> =&gt; <span class="op">{}</span>,</span>
-<span id="cb10-9"><a href="#cb10-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<span id="cb10-9"><a href="#cb10-9" aria-hidden="true" tabindex="-1"></a>    <span class="kw">else</span> =&gt; <span class="op">{</span></span>
+<span id="cb10-10"><a href="#cb10-10" aria-hidden="true" tabindex="-1"></a>        <span class="kw">try</span> stdout.print(</span>
+<span id="cb10-11"><a href="#cb10-11" aria-hidden="true" tabindex="-1"></a>            <span class="st">"Unmatched case, value: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="bu">@as</span>(<span class="dt">u8</span>, <span class="dv">1</span>)<span class="op">}</span></span>
+<span id="cb10-12"><a href="#cb10-12" aria-hidden="true" tabindex="-1"></a>        );</span>
+<span id="cb10-13"><a href="#cb10-13" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>,</span>
+<span id="cb10-14"><a href="#cb10-14" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
 </section>
diff --git a/docs/index.html b/docs/index.html
index cdf70e0c..6725b3d8 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -7,7 +7,7 @@
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 <meta name="author" content="Pedro Duarte Faria">
-<meta name="dcterms.date" content="2024-11-17">
+<meta name="dcterms.date" content="2024-11-24">
 
 <title>Introduction to Zig</title>
 <style>
@@ -287,7 +287,7 @@ <h1 class="title">Introduction to Zig</h1>
     <div>
     <div class="quarto-title-meta-heading">Published</div>
     <div class="quarto-title-meta-contents">
-      <p class="date">November 17, 2024</p>
+      <p class="date">November 24, 2024</p>
     </div>
   </div>
   
diff --git a/docs/search.json b/docs/search.json
index e59bd46f..af71dee7 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -234,7 +234,7 @@
     "href": "Chapters/03-structs.html#sec-zig-control-flow",
     "title": "2  Control flow, structs, modules and types",
     "section": "",
-    "text": "2.1.1 If/else statements\nAn if/else statement performs a “conditional flow operation”. A conditional flow control (or choice control) allows you to execute or ignore a certain block of commands based on a logical condition. Many programmers and computer science professionals also use the term “branching” in this case. In essence, an if/else statement allow us to use the result of a logical test to decide whether or not to execute a given block of commands.\nIn Zig, we write if/else statements by using the keywords if and else. We start with the if keyword followed by a logical test inside a pair of parentheses, followed by a pair of curly braces which contains the lines of code to be executed in case the logical test returns the value true.\nAfter that, you can optionally add an else statement. To do that, just add the else keyword followed by a pair of curly braces, with the lines of code to executed in case the logical test defined at if returns false.\nIn the example below, we are testing if the object x contains a number that is greater than 10. Judging by the output printed to the console, we know that this logical test returned false. Because the output in the console is compatible with the line of code present in the else branch of the if/else statement.\n\nconst x = 5;\nif (x &gt; 10) {\n    try stdout.print(\n        \"x &gt; 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x &lt;= 10!\\n\", .{}\n    );\n}\n\nx &lt;= 10!\n\n\n\n\n2.1.2 Switch statements\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust. As you would expect, to write a switch statement in Zig we use the switch keyword. We provide the value that we want to “switch over” inside a pair of parentheses. Then, we list the possible combinations (or “branches”) inside a pair of curly braces.\nLet’s take a look at the code example below. You can see that I’m creating an enum type called Role. We talk more about enums in Section 7.6. But in summary, this Role type is listing different types of roles in a fictitious company, like SE for Software Engineer, DE for Data Engineer, PM for Product Manager, etc.\nNotice that we are using the value from the role object in the switch statement, to discover which exact area we need to store in the area variable object. Also notice that we are using type inference inside the switch statement, with the dot character, as we are going to describe in Section 2.4. This makes the zig compiler infer the correct data type of the values (PM, SE, etc.) for us.\nAlso notice that, we are grouping multiple values in the same branch of the switch statement. We just separate each possible value with a comma. For example, if role contains either DE or DA, the area variable would contain the value \"Data & Analytics\", instead of \"Platform\" or \"Sales\".\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO =&gt; {\n            area = \"Platform\";\n        },\n        .DE, .DA =&gt; {\n            area = \"Data & Analytics\";\n        },\n        .KS =&gt; {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n\nPlatform\n\n\n\n2.1.2.1 Switch statements must exhaust all possibilities\nOne very important aspect about switch statements in Zig is that they must exhaust all existing possibilities. In other words, all possible values that could be found inside the order object must be explicitly handled in this switch statement.\nSince the role object have type Role, the only possible values to be found inside this object are PM, SE, DPE, PO, DE, DA and KS. There are no other possible values to be stored in this role object. Thus, the switch statements must have a combination (branch) for each one of these values. This is what “exhaust all existing possibilities” means. The switch statement covers every possible case.\nTherefore, you cannot write a switch statement in Zig, and leave an edge case with no explicit action to be taken. This is a similar behaviour to switch statements in Rust, which also have to handle all possible cases.\n\n\n2.1.2.2 The else branch\nTake a look at the dump_hex_fallible() function below as an example. This function comes from the Zig Standard Library. More precisely, from the debug.zig module1. There are multiple lines in this function, but I omitted them to focus solely on the switch statement found in this function. Notice that this switch statement has four possible cases (i.e. four explicit branches). Also, notice that we used an else branch in this case.\nAn else branch in a switch statement works as the “default branch”. Whenever you have multiple cases in your switch statement where you want to apply the exact same action, you can use an else branch to do that.\n\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' =&gt; try writer.writeAll(\"␊\"),\n        '\\r' =&gt; try writer.writeAll(\"␍\"),\n        '\\t' =&gt; try writer.writeAll(\"␉\"),\n        else =&gt; try writer.writeByte('.'),\n    }\n}\n\nMany programmers would also use an else branch to handle a “not supported” case. That is, a case that cannot be properly handled by your code, or, just a case that should not be “fixed”. Therefore, you can use an else branch to panic (or raise an error) in your program to stop the current execution.\nTake the code example below. We can see that, we are handling the cases for the level object being either 1, 2, or 3. All other possible cases are not supported by default, and, as consequence, we raise a runtime error in such cases through the @panic() built-in function.\nAlso notice that, we are assigning the result of the switch statement to a new object called category. This is another thing that you can do with switch statements in Zig. If a branch outputs a value as result, you can store the result value of the switch statement into a new object.\n\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 =&gt; \"beginner\",\n    3 =&gt; \"professional\",\n    else =&gt; {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n\n\n2.1.2.3 Using ranges in switch\nFurthermore, you can also use ranges of values in switch statements. That is, you can create a branch in your switch statement that is used whenever the input value is within the specified range. These “range expressions” are created with the operator .... It is important to emphasize that the ranges created by this operator are inclusive on both ends.\nFor example, I could easily change the previous code example to support all levels between 0 and 100. Like this:\n\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 =&gt; \"beginner\",\n    26...75 =&gt; \"intermediary\",\n    76...100 =&gt; \"professional\",\n    else =&gt; {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n\nbeginner\n\n\nThis is neat, and it works with character ranges too. That is, I could simply write 'a'...'z', to match any character value that is a lowercase letter, and it would work fine.\n\n\n2.1.2.4 Labeled switch statements\nIn Section 1.7 we have talked about labeling blocks, and also, about using these labels to return a value from the block. Well, from version 0.14.0 and onwards of the zig compiler, you can also apply labels over switch statements, which makes it possible to almost implement a “C goto” like pattern.\nFor example, if you give the label xsw to a switch statement, you can use this label in conjunction with the continue keyword to go back to the beginning of the switch statement. In the example below, the execution goes back to the beginning of the switch statement two times, before ending at the 3 branch.\n\nxsw: switch (@as(u8, 1)) {\n    1 =&gt; {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 =&gt; continue :xsw 3,\n    3 =&gt; return,\n    4 =&gt; {},\n}\n\n\n\n\n2.1.3 The defer keyword\nWith the defer keyword you can register an expression to be executed when you exit the current scope. Therefore, this keyword has a similar functionality as the on.exit() function from R. Take the foo() function below as an example. When we execute this foo() function, the expression that prints the message “Exiting function …” is getting executed only when the function exits its scope.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n\nAdding some numbers ...\nMultiplying ...\nExiting function ...\nTherefore, we can use defer to declare an expression that is going to be executed when your code exits the current scope. Some programmers like to interpret the phrase “exit of the current scope” as “the end of the current scope”. But this interpretation might not be entirely correct, depending on what you consider as “the end of the current scope”.\nI mean, what do you consider as the end of the current scope? Is it the closing curly bracket (}) of the scope? Is it when the last expression in the function get’s executed? Is it when the function returns to the previous scope? Etc. For example, it would not be correct to interpret the “exit of the current scope” as the closing curly bracket of the scope. Because the function might exit from an earlier position than this closing curly bracket (e.g. an error value was generated at a previous line inside the function; the function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\nNow, if you remember of what we have discussed in Section 1.7, there are multiple structures in the language that create their own separate scopes. For/while loops, if/else statements, functions, normal blocks, etc. This also affects the interpretation of defer. For example, if you use defer inside a for loop, then, the given expression will be executed everytime this specific for loop exits its own scope.\nBefore we continue, is worth emphasizing that the defer keyword is an “unconditional defer”. Which means that the given expression will be executed no matter how the code exits the current scope. For example, your code might exit the current scope because of an error value being generated, or, because of a return statement, or, a break statement, etc.\n\n\n2.1.4 The errdefer keyword\nOn the previous section, we have discussed the defer keyword, which you can use to register an expression to be executed at the exit of the current scope. But this keyword has a brother, which is the errdefer keyword. While defer is an “unconditional defer”, the errdefer keyword is a “conditional defer”. Which means that the given expression is executed only when you exit the current scope on a very specific circumstance.\nIn more details, the expression given to errdefer is executed only when an error occurs in the current scope. Therefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope in a normal situation, without errors, the expression given to errdefer is not executed.\nThis makes the errdefer keyword one of the many tools available in Zig for error handling. In this section, we are more concerned with the control flow aspects around errdefer. But we are going to discuss errdefer later as a error handling tool in Section 10.2.4.\nThe code example below demonstrates three things:\n\nthat defer is an “unconditional defer”, because the given expression get’s executed regardless of how the function foo() exits its own scope.\nthat errdefer is executed because the function foo() returned an error value.\nthat defer and errdefer expressions are executed in a LIFO (last in, first out) order.\n\n\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\nWhen I say that “defer expressions” are executed in a LIFO order, what I want to say is that the last defer or errdefer expressions in the code are the first ones to be executed. You could also interpret this as: “defer expressions” are executed from bottom to top, or, from last to first.\nTherefore, if I change the order of the defer and errdefer expressions, you will notice that the value of i that get’s printed to the console changes to 1. This doesn’t mean that the defer expression was not executed in this case. This actually means that the defer expression was executed only after the errdefer expression. The code example below demonstrates this:\n\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n\n\n2.1.5 For loops\nA loop allows you to execute the same lines of code multiple times, thus, creating a “repetition space” in the execution flow of your program. Loops are particularly useful when we want to replicate the same function (or the same set of commands) over different inputs.\nThere are different types of loops available in Zig. But the most essential of them all is probably the for loop. A for loop is used to apply the same piece of code over the elements of a slice, or, an array.\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from other languages. You start with the for keyword, then, you list the items that you want to iterate over inside a pair of parentheses. Then, inside of a pair of pipes (|) you should declare an identifier that will serve as your iterator, or, the “repetition index of the loop”.\n\nfor (items) |value| {\n    // code to execute\n}\n\nTherefore, instead of using a (value in items) syntax, in Zig, for loops use the syntax (items) |value|. In the example below, you can see that we are looping through the items of the array stored at the object name, and printing to the console the decimal representation of each character in this array.\nIf we wanted, we could also iterate through a slice (or a portion) of the array, instead of iterating through the entire array stored in the name object. Just use a range selector to select the section you want. For example, I could provide the expression name[0..3] to the for loop, to iterate just through the first 3 elements in the array.\n\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n\n80 | 101 | 100 | 114 | 111 | \n\n\nIn the above example we are using the value itself of each element in the array as our iterator. But there are many situations where we need to use an index instead of the actual values of the items.\nYou can do that by providing a second set of items to iterate over. More precisely, you provide the range selector 0.. to the for loop. So, yes, you can use two different iterators at the same time in a for loop in Zig.\nBut remember from Section 1.4 that, every object you create in Zig must be used in some way. So if you declare two iterators in your for loop, you must use both iterators inside the for loop body. But if you want to use just the index iterator, and not use the “value iterator”, then, you can discard the value iterator by maching the value items to the underscore character, like in the example below:\n\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n\n0 | 1 | 2 | 3 | 4 |\n\n\n2.1.6 While loops\nA while loop is created from the while keyword. A for loop iterates through the items of an array, but a while loop will loop continuously, and infinitely, until a logical test (specified by you) becomes false.\nYou start with the while keyword, then, you define a logical expression inside a pair of parentheses, and the body of the loop is provided inside a pair of curly braces, like in the example below:\n\nvar i: u8 = 1;\nwhile (i &lt; 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n\n1 | 2 | 3 | 4 | \n\n\nYou can also specify the increment expression to be used at the beginning of a while loop. To do that, we write the increment expression inside a pair of parentheses after a colon character (:). The code example below demonstrates this other pattern.\n\nvar i: u8 = 1;\nwhile (i &lt; 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n\n1 | 2 | 3 | 4 | \n\n\n\n\n2.1.7 Using break and continue\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using the keywords break and continue, respectively. The while loop presented in the next code example is, at first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to true. But what makes this while loop stop when the i object reaches the count 10? It is the break keyword!\nInside the while loop, we have an if statement that is constantly checking if the i variable is equal to 10. Since we are incrementing the value of i at each iteration of the while loop, this i object will eventually be equal to 10, and when it is, the if statement will execute the break expression, and, as a result, the execution of the while loop is stopped.\nNotice the use of the expect() function from the Zig Standard Library after the while loop. This expect() function is an “assert” type of function. This function checks if the logical test provided is equal to true. If so, the function do nothing. Otherwise (i.e. the logical test is equal to false), the function raises an assertion error.\n\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n\nEverything worked!\n\n\nSince this code example was executed successfully by the zig compiler, without raising any errors, we known that, after the execution of the while loop, the i object is equal to 10. Because if it wasn’t equal to 10, an error would have been raised by expect().\nNow, in the next example, we have a use case for the continue keyword. The if statement is constantly checking if the current index is a multiple of 2. If it is, we jump to the next iteration of the loop. Otherwise, the loop just prints the current index to the console.\n\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n\n1 | 3 | 5 |",
+    "text": "2.1.1 If/else statements\nAn if/else statement performs a “conditional flow operation”. A conditional flow control (or choice control) allows you to execute or ignore a certain block of commands based on a logical condition. Many programmers and computer science professionals also use the term “branching” in this case. In essence, an if/else statement allow us to use the result of a logical test to decide whether or not to execute a given block of commands.\nIn Zig, we write if/else statements by using the keywords if and else. We start with the if keyword followed by a logical test inside a pair of parentheses, followed by a pair of curly braces which contains the lines of code to be executed in case the logical test returns the value true.\nAfter that, you can optionally add an else statement. To do that, just add the else keyword followed by a pair of curly braces, with the lines of code to executed in case the logical test defined at if returns false.\nIn the example below, we are testing if the object x contains a number that is greater than 10. Judging by the output printed to the console, we know that this logical test returned false. Because the output in the console is compatible with the line of code present in the else branch of the if/else statement.\n\nconst x = 5;\nif (x &gt; 10) {\n    try stdout.print(\n        \"x &gt; 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x &lt;= 10!\\n\", .{}\n    );\n}\n\nx &lt;= 10!\n\n\n\n\n2.1.2 Switch statements\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust. As you would expect, to write a switch statement in Zig we use the switch keyword. We provide the value that we want to “switch over” inside a pair of parentheses. Then, we list the possible combinations (or “branches”) inside a pair of curly braces.\nLet’s take a look at the code example below. You can see that I’m creating an enum type called Role. We talk more about enums in Section 7.6. But in summary, this Role type is listing different types of roles in a fictitious company, like SE for Software Engineer, DE for Data Engineer, PM for Product Manager, etc.\nNotice that we are using the value from the role object in the switch statement, to discover which exact area we need to store in the area variable object. Also notice that we are using type inference inside the switch statement, with the dot character, as we are going to describe in Section 2.4. This makes the zig compiler infer the correct data type of the values (PM, SE, etc.) for us.\nAlso notice that, we are grouping multiple values in the same branch of the switch statement. We just separate each possible value with a comma. For example, if role contains either DE or DA, the area variable would contain the value \"Data & Analytics\", instead of \"Platform\" or \"Sales\".\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO =&gt; {\n            area = \"Platform\";\n        },\n        .DE, .DA =&gt; {\n            area = \"Data & Analytics\";\n        },\n        .KS =&gt; {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n\nPlatform\n\n\n\n2.1.2.1 Switch statements must exhaust all possibilities\nOne very important aspect about switch statements in Zig is that they must exhaust all existing possibilities. In other words, all possible values that could be found inside the order object must be explicitly handled in this switch statement.\nSince the role object have type Role, the only possible values to be found inside this object are PM, SE, DPE, PO, DE, DA and KS. There are no other possible values to be stored in this role object. Thus, the switch statements must have a combination (branch) for each one of these values. This is what “exhaust all existing possibilities” means. The switch statement covers every possible case.\nTherefore, you cannot write a switch statement in Zig, and leave an edge case with no explicit action to be taken. This is a similar behaviour to switch statements in Rust, which also have to handle all possible cases.\n\n\n2.1.2.2 The else branch\nTake a look at the dump_hex_fallible() function below as an example. This function comes from the Zig Standard Library. More precisely, from the debug.zig module1. There are multiple lines in this function, but I omitted them to focus solely on the switch statement found in this function. Notice that this switch statement has four possible cases (i.e. four explicit branches). Also, notice that we used an else branch in this case.\nAn else branch in a switch statement works as the “default branch”. Whenever you have multiple cases in your switch statement where you want to apply the exact same action, you can use an else branch to do that.\n\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' =&gt; try writer.writeAll(\"␊\"),\n        '\\r' =&gt; try writer.writeAll(\"␍\"),\n        '\\t' =&gt; try writer.writeAll(\"␉\"),\n        else =&gt; try writer.writeByte('.'),\n    }\n}\n\nMany programmers would also use an else branch to handle a “not supported” case. That is, a case that cannot be properly handled by your code, or, just a case that should not be “fixed”. Therefore, you can use an else branch to panic (or raise an error) in your program to stop the current execution.\nTake the code example below. We can see that, we are handling the cases for the level object being either 1, 2, or 3. All other possible cases are not supported by default, and, as consequence, we raise a runtime error in such cases through the @panic() built-in function.\nAlso notice that, we are assigning the result of the switch statement to a new object called category. This is another thing that you can do with switch statements in Zig. If a branch outputs a value as result, you can store the result value of the switch statement into a new object.\n\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 =&gt; \"beginner\",\n    3 =&gt; \"professional\",\n    else =&gt; {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n\n\n2.1.2.3 Using ranges in switch\nFurthermore, you can also use ranges of values in switch statements. That is, you can create a branch in your switch statement that is used whenever the input value is within the specified range. These “range expressions” are created with the operator .... It is important to emphasize that the ranges created by this operator are inclusive on both ends.\nFor example, I could easily change the previous code example to support all levels between 0 and 100. Like this:\n\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 =&gt; \"beginner\",\n    26...75 =&gt; \"intermediary\",\n    76...100 =&gt; \"professional\",\n    else =&gt; {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n\nbeginner\n\n\nThis is neat, and it works with character ranges too. That is, I could simply write 'a'...'z', to match any character value that is a lowercase letter, and it would work fine.\n\n\n2.1.2.4 Labeled switch statements\nIn Section 1.7 we have talked about labeling blocks, and also, about using these labels to return a value from the block. Well, from version 0.14.0 and onwards of the zig compiler, you can also apply labels over switch statements, which makes it possible to almost implement a “C goto” like pattern.\nFor example, if you give the label xsw to a switch statement, you can use this label in conjunction with the continue keyword to go back to the beginning of the switch statement. In the example below, the execution goes back to the beginning of the switch statement two times, before ending at the 3 branch.\n\nxsw: switch (@as(u8, 1)) {\n    1 =&gt; {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 =&gt; continue :xsw 3,\n    3 =&gt; return,\n    4 =&gt; {},\n    else =&gt; {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n\n\n\n\n2.1.3 The defer keyword\nWith the defer keyword you can register an expression to be executed when you exit the current scope. Therefore, this keyword has a similar functionality as the on.exit() function from R. Take the foo() function below as an example. When we execute this foo() function, the expression that prints the message “Exiting function …” is getting executed only when the function exits its scope.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n\nAdding some numbers ...\nMultiplying ...\nExiting function ...\nTherefore, we can use defer to declare an expression that is going to be executed when your code exits the current scope. Some programmers like to interpret the phrase “exit of the current scope” as “the end of the current scope”. But this interpretation might not be entirely correct, depending on what you consider as “the end of the current scope”.\nI mean, what do you consider as the end of the current scope? Is it the closing curly bracket (}) of the scope? Is it when the last expression in the function get’s executed? Is it when the function returns to the previous scope? Etc. For example, it would not be correct to interpret the “exit of the current scope” as the closing curly bracket of the scope. Because the function might exit from an earlier position than this closing curly bracket (e.g. an error value was generated at a previous line inside the function; the function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\nNow, if you remember of what we have discussed in Section 1.7, there are multiple structures in the language that create their own separate scopes. For/while loops, if/else statements, functions, normal blocks, etc. This also affects the interpretation of defer. For example, if you use defer inside a for loop, then, the given expression will be executed everytime this specific for loop exits its own scope.\nBefore we continue, is worth emphasizing that the defer keyword is an “unconditional defer”. Which means that the given expression will be executed no matter how the code exits the current scope. For example, your code might exit the current scope because of an error value being generated, or, because of a return statement, or, a break statement, etc.\n\n\n2.1.4 The errdefer keyword\nOn the previous section, we have discussed the defer keyword, which you can use to register an expression to be executed at the exit of the current scope. But this keyword has a brother, which is the errdefer keyword. While defer is an “unconditional defer”, the errdefer keyword is a “conditional defer”. Which means that the given expression is executed only when you exit the current scope on a very specific circumstance.\nIn more details, the expression given to errdefer is executed only when an error occurs in the current scope. Therefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope in a normal situation, without errors, the expression given to errdefer is not executed.\nThis makes the errdefer keyword one of the many tools available in Zig for error handling. In this section, we are more concerned with the control flow aspects around errdefer. But we are going to discuss errdefer later as a error handling tool in Section 10.2.4.\nThe code example below demonstrates three things:\n\nthat defer is an “unconditional defer”, because the given expression get’s executed regardless of how the function foo() exits its own scope.\nthat errdefer is executed because the function foo() returned an error value.\nthat defer and errdefer expressions are executed in a LIFO (last in, first out) order.\n\n\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\nWhen I say that “defer expressions” are executed in a LIFO order, what I want to say is that the last defer or errdefer expressions in the code are the first ones to be executed. You could also interpret this as: “defer expressions” are executed from bottom to top, or, from last to first.\nTherefore, if I change the order of the defer and errdefer expressions, you will notice that the value of i that get’s printed to the console changes to 1. This doesn’t mean that the defer expression was not executed in this case. This actually means that the defer expression was executed only after the errdefer expression. The code example below demonstrates this:\n\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n\n\n2.1.5 For loops\nA loop allows you to execute the same lines of code multiple times, thus, creating a “repetition space” in the execution flow of your program. Loops are particularly useful when we want to replicate the same function (or the same set of commands) over different inputs.\nThere are different types of loops available in Zig. But the most essential of them all is probably the for loop. A for loop is used to apply the same piece of code over the elements of a slice, or, an array.\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from other languages. You start with the for keyword, then, you list the items that you want to iterate over inside a pair of parentheses. Then, inside of a pair of pipes (|) you should declare an identifier that will serve as your iterator, or, the “repetition index of the loop”.\n\nfor (items) |value| {\n    // code to execute\n}\n\nTherefore, instead of using a (value in items) syntax, in Zig, for loops use the syntax (items) |value|. In the example below, you can see that we are looping through the items of the array stored at the object name, and printing to the console the decimal representation of each character in this array.\nIf we wanted, we could also iterate through a slice (or a portion) of the array, instead of iterating through the entire array stored in the name object. Just use a range selector to select the section you want. For example, I could provide the expression name[0..3] to the for loop, to iterate just through the first 3 elements in the array.\n\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n\n80 | 101 | 100 | 114 | 111 | \n\n\nIn the above example we are using the value itself of each element in the array as our iterator. But there are many situations where we need to use an index instead of the actual values of the items.\nYou can do that by providing a second set of items to iterate over. More precisely, you provide the range selector 0.. to the for loop. So, yes, you can use two different iterators at the same time in a for loop in Zig.\nBut remember from Section 1.4 that, every object you create in Zig must be used in some way. So if you declare two iterators in your for loop, you must use both iterators inside the for loop body. But if you want to use just the index iterator, and not use the “value iterator”, then, you can discard the value iterator by maching the value items to the underscore character, like in the example below:\n\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n\n0 | 1 | 2 | 3 | 4 |\n\n\n2.1.6 While loops\nA while loop is created from the while keyword. A for loop iterates through the items of an array, but a while loop will loop continuously, and infinitely, until a logical test (specified by you) becomes false.\nYou start with the while keyword, then, you define a logical expression inside a pair of parentheses, and the body of the loop is provided inside a pair of curly braces, like in the example below:\n\nvar i: u8 = 1;\nwhile (i &lt; 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n\n1 | 2 | 3 | 4 | \n\n\nYou can also specify the increment expression to be used at the beginning of a while loop. To do that, we write the increment expression inside a pair of parentheses after a colon character (:). The code example below demonstrates this other pattern.\n\nvar i: u8 = 1;\nwhile (i &lt; 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n\n1 | 2 | 3 | 4 | \n\n\n\n\n2.1.7 Using break and continue\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using the keywords break and continue, respectively. The while loop presented in the next code example is, at first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to true. But what makes this while loop stop when the i object reaches the count 10? It is the break keyword!\nInside the while loop, we have an if statement that is constantly checking if the i variable is equal to 10. Since we are incrementing the value of i at each iteration of the while loop, this i object will eventually be equal to 10, and when it is, the if statement will execute the break expression, and, as a result, the execution of the while loop is stopped.\nNotice the use of the expect() function from the Zig Standard Library after the while loop. This expect() function is an “assert” type of function. This function checks if the logical test provided is equal to true. If so, the function do nothing. Otherwise (i.e. the logical test is equal to false), the function raises an assertion error.\n\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n\nEverything worked!\n\n\nSince this code example was executed successfully by the zig compiler, without raising any errors, we known that, after the execution of the while loop, the i object is equal to 10. Because if it wasn’t equal to 10, an error would have been raised by expect().\nNow, in the next example, we have a use case for the continue keyword. The if statement is constantly checking if the current index is a multiple of 2. If it is, we jump to the next iteration of the loop. Otherwise, the loop just prints the current index to the console.\n\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n\n1 | 3 | 5 |",
     "crumbs": [
       "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
     ]

From 6895ef764b0cf3e0e69104d08f47f1cb9d39e362 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sun, 24 Nov 2024 21:01:30 -0300
Subject: [PATCH 005/151] Rewrite note

---
 Chapters/01-zig-weird.qmd | 63 ++++++++++++++++++++++++++++++++++-----
 1 file changed, 55 insertions(+), 8 deletions(-)

diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index c1539784..c68cad50 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -359,27 +359,74 @@ zig run src/main.zig
 ```
 Hello, world!
 ```
-### Important Note for Windows Users
 
-On Windows, certain global initializations that rely on runtime resources, such as `std.io.getStdOut().writer()`, may fail. This happens because global variables in Zig are initialized at **compile-time**, and operations like accessing `stdout` or opening files are restricted to runtime.
 
-### Example
-**Incorrect:**
+### Important note for Windows users
+
+First of all, this is a Windows-specific thing, and, therefore, does not apply to other
+operational systems, such as Linux and MacOs. In summary, if you have a piece of Zig code that
+includes some global variables whose initialization rely on runtime resources, then,
+you might have some troubles while trying to compile this Zig code on Windows.
+
+An example of that is accessing the `stdout` (i.e. the *standard output* of your system), which is usually
+done in Zig by using the expression `std.io.getStdOut()`. Thus, if you use this expression to instantiate
+a global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,
+with a "unable to evaluate comptime expression" error message.
+
+This failure in the compilation process happens because all global variables in Zig are initialized
+at *compile-time*. However, operations like accessing the `stdout` (or opening a file) on Windows
+depends on resources that are available only at *runtime* (you will learn more about compile-time
+versus runtime at @sec-compile-time).
+
+For example, if you try to compile this code example on Windows, you will likely get the error message
+exposed below:
+
 ```{zig}
 #| eval: false
 #| auto_main: false
-const stdout = std.io.getStdOut().writer(); // ❌ Compile-time error on Windows
+const std = @import("std");
+// ERROR: Compile-time error on Windows
+const stdout = std.io.getStdOut().writer();
+
+pub fn main() !void {
+    _ = try stdout.write("Hello\n");
+}
+```
+
+```
+t.zig:2107:28: error: unable to evaluate comptime expression
+    break :blk asm {
+               ^~~
 ```
-Correct:
+
+
+
+To avoid this problem on Windows, we need to force the `zig` compiler to instantiate this
+`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve
+that by simply moving the expression to a function body.
+
+This solves the problem because all expressions that are inside a function body in Zig
+are evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.
+You will learn more about this `comptime` keyword at @sec-comptime.
+
 
 ```{zig}
 #| eval: false
 #| auto_main: false
-pub fn main() void {
-    const stdout = std.io.getStdOut().writer(); // ✅ Runtime initialization
+const std = @import("std");
+pub fn main() !void {
+    // SUCCESS: Stdout initialized at runtime.
+    const stdout = std.io.getStdOut().writer();
+    _ = try stdout.write("Hello\n");
 }
 ```
 
+```
+Hello
+```
+
+
+
 ### Compiling the entire project {#sec-compile-project}
 
 Just as I described at @sec-project-files, as our project grows in size and

From 46167ad94f7d7dfa4dc7ce5d91f28a6356312710 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sun, 24 Nov 2024 21:05:33 -0300
Subject: [PATCH 006/151] Add footnotes

---
 Chapters/01-zig-weird.qmd | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index c68cad50..5d7ff596 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -425,6 +425,11 @@ pub fn main() !void {
 Hello
 ```
 
+You can read more details about this Windows-specific limitation at a couple of
+GitHub issues opened at the official Zig repository[^cissue1][^cissue2].
+
+[^cissue1]: <https://github.com/ziglang/zig/issues/17186>
+[^cissue2]: <https://github.com/ziglang/zig/issues/19864>
 
 
 ### Compiling the entire project {#sec-compile-project}

From 7615f8bc793b0bbaa55bbbacbcfba822eee121ea Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sun, 24 Nov 2024 21:11:32 -0300
Subject: [PATCH 007/151] Improve comment

---
 Chapters/01-zig-weird.qmd                     |   6 +-
 .../01-zig-weird/execute-results/html.json    |   8 +-
 docs/Chapters/01-zig-weird.html               | 461 ++++++++++--------
 docs/index.html                               |   4 +-
 docs/search.json                              |  12 +-
 5 files changed, 263 insertions(+), 228 deletions(-)

diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index 5d7ff596..65839232 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -385,7 +385,8 @@ exposed below:
 #| eval: false
 #| auto_main: false
 const std = @import("std");
-// ERROR: Compile-time error on Windows
+// ERROR! Compile-time error that emerge from
+// this next line, on the `stdout` object
 const stdout = std.io.getStdOut().writer();
 
 pub fn main() !void {
@@ -426,7 +427,8 @@ Hello
 ```
 
 You can read more details about this Windows-specific limitation at a couple of
-GitHub issues opened at the official Zig repository[^cissue1][^cissue2].
+GitHub issues opened at the official Zig repository. More specifically, the issues 
+17186 [^cissue1] and 19864 [^cissue2].
 
 [^cissue1]: <https://github.com/ziglang/zig/issues/17186>
 [^cissue2]: <https://github.com/ziglang/zig/issues/19864>
diff --git a/_freeze/Chapters/01-zig-weird/execute-results/html.json b/_freeze/Chapters/01-zig-weird/execute-results/html.json
index 9d657580..317b33ea 100644
--- a/_freeze/Chapters/01-zig-weird/execute-results/html.json
+++ b/_freeze/Chapters/01-zig-weird/execute-results/html.json
@@ -1,11 +1,9 @@
 {
-  "hash": "143b2e8f648cc24b18d46ae197d20d97",
+  "hash": "7dd731d3bc677839fb57a945a5a74e77",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\nlanguage, it is still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. They really make it sometimes hard to debug\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscures the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that get's compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e. it is where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `ìnit` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contain Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nTherefore, Zig contains a native build system in it, and\nwe can use this build system to write small scripts in Zig,\nwhich describes the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is the Zig package manager configuration file,\nwhere you can list and manage the dependencies of your project. Yes, Zig has\na package manager (like `pip` in Python, `cargo` in Rust, or `npm` in Javascript) called Zon,\nand this `build.zig.zon` file is similar to the `package.json` file\nin Javascript projects, or, the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects.\n\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e. creating new objects)\nare made in Zig. You can create a new object in Zig by using the following syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). At @sec-assignments we talk more about objects in general.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that at @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return\ntype of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function\nmight return an error.\n\nIn this example, the `main()` function can either return `void` or return an error.\nThis is an interesting feature of Zig. If you write a function and something inside of\nthe body of this function might return an error then you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error\n- explicitly handle this error inside the function\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does nothing. It only passes the value forward.\nBut if the expression does return an error, then, the `try` keyword just unwrap the error value,\nand return this error from the function and also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword.\nIt marks the `main()` function as a *public function* from this module.\n\nEvery function in your Zig module is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\nThis means that the `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++.\n\nBy making a function \"public\" you allow other Zig modules to access and call it.\nA calling Zig module imports the module with the `@import()`\nbuilt-in. That makes all public functions from the imported module visible.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portale C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nOn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described at @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig latter in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig? \nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar in our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentations.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It is a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (at YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e. identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compiles successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nIn contrast, if you use `var`, then, the object created is a variable object.\nWith `var` you can declare this object in your source code, and then,\nchange the value of this object how many times you want over future points\nin your source code.\n\nSo, using the same code example exposed above, if I change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it is an \"variable object\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIs important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code use this object while it is uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object. \n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e. if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to an special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It is discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also get's discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e. the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\nIs worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array. \n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it is a slice that\naccess all elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" at @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth at @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially at @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned at @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e. the start and the end of this range)\nis known at compile-time, the slice object that get's created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nat @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that get's created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e. a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can \ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n```\n:::\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat get's created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, the `slice` object have a runtime known range, because the end index of the range\nis not known at compile time. In other words, the size of the array at `buffer` is not known\nat compile time. When we execute this program, the size of the array might be 10, or, it might be 12\ndepending on where we execute it. Therefore, we don't know at compile time if\nthe slice object have a range of size 10, or, a range of size 12.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e. a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented at @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e. `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIs worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e. the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause is much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e. if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it is a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n:::\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIs important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n```\nHello you!\n```\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operational system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligates you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig at @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers at @sec-root-file and especially at @sec-assignments.\n- How strings work in Zig at @sec-zig-strings.\n- How to use arrays and slices at @sec-arrays.\n- How to import functionality from other Zig modules at @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* at @sec-structs-and-oop.\n- Basic control flow syntax at @sec-zig-control-flow.\n- Enums at @sec-enum;\n- Pointers and Optionals at @sec-pointer;\n- Error handling with `try` and `catch` at @sec-error-handling;\n- Unit tests at @sec-unittests;\n- Vectors at @sec-vectors-simd;\n- Build System at @sec-build-system;\n\n\n\n\n",
-    "supporting": [
-      "01-zig-weird_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\nlanguage, it is still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. They really make it sometimes hard to debug\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscures the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that get's compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e. it is where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `ìnit` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contain Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nTherefore, Zig contains a native build system in it, and\nwe can use this build system to write small scripts in Zig,\nwhich describes the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is the Zig package manager configuration file,\nwhere you can list and manage the dependencies of your project. Yes, Zig has\na package manager (like `pip` in Python, `cargo` in Rust, or `npm` in Javascript) called Zon,\nand this `build.zig.zon` file is similar to the `package.json` file\nin Javascript projects, or, the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects.\n\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e. creating new objects)\nare made in Zig. You can create a new object in Zig by using the following syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). At @sec-assignments we talk more about objects in general.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that at @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return\ntype of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function\nmight return an error.\n\nIn this example, the `main()` function can either return `void` or return an error.\nThis is an interesting feature of Zig. If you write a function and something inside of\nthe body of this function might return an error then you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error\n- explicitly handle this error inside the function\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does nothing. It only passes the value forward.\nBut if the expression does return an error, then, the `try` keyword just unwrap the error value,\nand return this error from the function and also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword.\nIt marks the `main()` function as a *public function* from this module.\n\nEvery function in your Zig module is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\nThis means that the `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++.\n\nBy making a function \"public\" you allow other Zig modules to access and call it.\nA calling Zig module imports the module with the `@import()`\nbuilt-in. That makes all public functions from the imported module visible.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portale C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nOn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperational systems, such as Linux and MacOs. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e. the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. Thus, if you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith a \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, operations like accessing the `stdout` (or opening a file) on Windows\ndepends on resources that are available only at *runtime* (you will learn more about compile-time\nversus runtime at @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword at @sec-comptime.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation at a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues \n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described at @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig latter in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig? \nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar in our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentations.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It is a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (at YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e. identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compiles successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nIn contrast, if you use `var`, then, the object created is a variable object.\nWith `var` you can declare this object in your source code, and then,\nchange the value of this object how many times you want over future points\nin your source code.\n\nSo, using the same code example exposed above, if I change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it is an \"variable object\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIs important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code use this object while it is uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object. \n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e. if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to an special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It is discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also get's discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e. the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\n\nIs worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array. \n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it is a slice that\naccess all elements in the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" at @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth at @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially at @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned at @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e. the start and the end of this range)\nis known at compile-time, the slice object that get's created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nat @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that get's created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e. a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can \ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n```\n:::\n\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat get's created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, the `slice` object have a runtime known range, because the end index of the range\nis not known at compile time. In other words, the size of the array at `buffer` is not known\nat compile time. When we execute this program, the size of the array might be 10, or, it might be 12\ndepending on where we execute it. Therefore, we don't know at compile time if\nthe slice object have a range of size 10, or, a range of size 12.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e. a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented at @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e. `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIs worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e. the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause is much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e. if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it is a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n:::\n\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIs important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\n```\nHello you!\n```\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operational system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligates you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig at @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers at @sec-root-file and especially at @sec-assignments.\n- How strings work in Zig at @sec-zig-strings.\n- How to use arrays and slices at @sec-arrays.\n- How to import functionality from other Zig modules at @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* at @sec-structs-and-oop.\n- Basic control flow syntax at @sec-zig-control-flow.\n- Enums at @sec-enum;\n- Pointers and Optionals at @sec-pointer;\n- Error handling with `try` and `catch` at @sec-error-handling;\n- Unit tests at @sec-unittests;\n- Vectors at @sec-vectors-simd;\n- Build System at @sec-build-system;\n\n\n\n\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/docs/Chapters/01-zig-weird.html b/docs/Chapters/01-zig-weird.html
index 9e8e7a45..7b4a3931 100644
--- a/docs/Chapters/01-zig-weird.html
+++ b/docs/Chapters/01-zig-weird.html
@@ -306,7 +306,8 @@ <h2 id="toc-title">Table of contents</h2>
   <li><a href="#sec-main-file" id="toc-sec-main-file" class="nav-link" data-scroll-target="#sec-main-file"><span class="header-section-number">1.2.3</span> The <code>main.zig</code> file</a></li>
   <li><a href="#sec-compile-code" id="toc-sec-compile-code" class="nav-link" data-scroll-target="#sec-compile-code"><span class="header-section-number">1.2.4</span> Compiling your source code</a></li>
   <li><a href="#sec-compile-run-code" id="toc-sec-compile-run-code" class="nav-link" data-scroll-target="#sec-compile-run-code"><span class="header-section-number">1.2.5</span> Compile and execute at the same time</a></li>
-  <li><a href="#sec-compile-project" id="toc-sec-compile-project" class="nav-link" data-scroll-target="#sec-compile-project"><span class="header-section-number">1.2.6</span> Compiling the entire project</a></li>
+  <li><a href="#important-note-for-windows-users" id="toc-important-note-for-windows-users" class="nav-link" data-scroll-target="#important-note-for-windows-users"><span class="header-section-number">1.2.6</span> Important note for Windows users</a></li>
+  <li><a href="#sec-compile-project" id="toc-sec-compile-project" class="nav-link" data-scroll-target="#sec-compile-project"><span class="header-section-number">1.2.7</span> Compiling the entire project</a></li>
   </ul></li>
   <li><a href="#how-to-learn-zig" id="toc-how-to-learn-zig" class="nav-link" data-scroll-target="#how-to-learn-zig"><span class="header-section-number">1.3</span> How to learn Zig?</a></li>
   <li><a href="#sec-assignments" id="toc-sec-assignments" class="nav-link" data-scroll-target="#sec-assignments"><span class="header-section-number">1.4</span> Creating new objects in Zig (i.e.&nbsp;identifiers)</a>
@@ -470,16 +471,48 @@ <h3 data-number="1.2.5" class="anchored" data-anchor-id="sec-compile-run-code"><
 <div class="sourceCode" id="cb12"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zig</span> run src/main.zig</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <pre><code>Hello, world!</code></pre>
 </section>
-<section id="sec-compile-project" class="level3" data-number="1.2.6">
-<h3 data-number="1.2.6" class="anchored" data-anchor-id="sec-compile-project"><span class="header-section-number">1.2.6</span> Compiling the entire project</h3>
+<section id="important-note-for-windows-users" class="level3" data-number="1.2.6">
+<h3 data-number="1.2.6" class="anchored" data-anchor-id="important-note-for-windows-users"><span class="header-section-number">1.2.6</span> Important note for Windows users</h3>
+<p>First of all, this is a Windows-specific thing, and, therefore, does not apply to other operational systems, such as Linux and MacOs. In summary, if you have a piece of Zig code that includes some global variables whose initialization rely on runtime resources, then, you might have some troubles while trying to compile this Zig code on Windows.</p>
+<p>An example of that is accessing the <code>stdout</code> (i.e.&nbsp;the <em>standard output</em> of your system), which is usually done in Zig by using the expression <code>std.io.getStdOut()</code>. Thus, if you use this expression to instantiate a global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows, with a “unable to evaluate comptime expression” error message.</p>
+<p>This failure in the compilation process happens because all global variables in Zig are initialized at <em>compile-time</em>. However, operations like accessing the <code>stdout</code> (or opening a file) on Windows depends on resources that are available only at <em>runtime</em> (you will learn more about compile-time versus runtime at <a href="01-memory.html#sec-compile-time" class="quarto-xref"><span>Section 3.1.1</span></a>).</p>
+<p>For example, if you try to compile this code example on Windows, you will likely get the error message exposed below:</p>
+<div class="cell">
+<div class="sourceCode cell-code" id="cb14"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb14-2"><a href="#cb14-2" aria-hidden="true" tabindex="-1"></a><span class="co">// ERROR! Compile-time error that emerge from</span></span>
+<span id="cb14-3"><a href="#cb14-3" aria-hidden="true" tabindex="-1"></a><span class="co">// this next line, on the `stdout` object</span></span>
+<span id="cb14-4"><a href="#cb14-4" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
+<span id="cb14-5"><a href="#cb14-5" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb14-6"><a href="#cb14-6" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb14-7"><a href="#cb14-7" aria-hidden="true" tabindex="-1"></a>    _ = <span class="kw">try</span> stdout.write(<span class="st">"Hello</span><span class="sc">\n</span><span class="st">"</span>);</span>
+<span id="cb14-8"><a href="#cb14-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+</div>
+<pre><code>t.zig:2107:28: error: unable to evaluate comptime expression
+    break :blk asm {
+               ^~~</code></pre>
+<p>To avoid this problem on Windows, we need to force the <code>zig</code> compiler to instantiate this <code>stdout</code> object only at runtime, instead of instantiating it at compile-time. We can achieve that by simply moving the expression to a function body.</p>
+<p>This solves the problem because all expressions that are inside a function body in Zig are evaluated only at runtime, unless you use the <code>comptime</code> keyword explicitly to change this behaviour. You will learn more about this <code>comptime</code> keyword at <a href="10-stack-project.html#sec-comptime" class="quarto-xref"><span>Section 12.1</span></a>.</p>
+<div class="cell">
+<div class="sourceCode cell-code" id="cb16"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb16-2"><a href="#cb16-2" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb16-3"><a href="#cb16-3" aria-hidden="true" tabindex="-1"></a>    <span class="co">// SUCCESS: Stdout initialized at runtime.</span></span>
+<span id="cb16-4"><a href="#cb16-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
+<span id="cb16-5"><a href="#cb16-5" aria-hidden="true" tabindex="-1"></a>    _ = <span class="kw">try</span> stdout.write(<span class="st">"Hello</span><span class="sc">\n</span><span class="st">"</span>);</span>
+<span id="cb16-6"><a href="#cb16-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+</div>
+<pre><code>Hello</code></pre>
+<p>You can read more details about this Windows-specific limitation at a couple of GitHub issues opened at the official Zig repository. More specifically, the issues 17186 <a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a> and 19864 <a href="#fn4" class="footnote-ref" id="fnref4" role="doc-noteref"><sup>4</sup></a>.</p>
+</section>
+<section id="sec-compile-project" class="level3" data-number="1.2.7">
+<h3 data-number="1.2.7" class="anchored" data-anchor-id="sec-compile-project"><span class="header-section-number">1.2.7</span> Compiling the entire project</h3>
 <p>Just as I described at <a href="#sec-project-files" class="quarto-xref"><span>Section 1.2.1</span></a>, as our project grows in size and complexity, we usually prefer to organize the compilation and build process of the project into a build script, using some sort of “build system”.</p>
 <p>In other words, as our project grows in size and complexity, the <code>build-exe</code>, <code>build-lib</code> and <code>build-obj</code> commands become harder to use directly. Because then, we start to list multiple and multiple modules at the same time. We also start to add built-in compilation flags to customize the build process for our needs, etc. It becomes a lot of work to write the necessary commands by hand.</p>
 <p>In C/C++ projects, programmers normally opt to use CMake, Ninja, <code>Makefile</code> or <code>configure</code> scripts to organize this process. However, in Zig, we have a native build system in the language itself. So, we can write build scripts in Zig to compile and build Zig projects. Then, all we need to do, is to call the <code>zig build</code> command to build our project.</p>
 <p>So, when you execute the <code>zig build</code> command, the <code>zig</code> compiler will search for a Zig module named <code>build.zig</code> inside your current directory, which should be your build script, containing the necessary code to compile and build your project. If the compiler does find this <code>build.zig</code> file in your directory, then, the compiler will essentially execute a <code>zig run</code> command over this <code>build.zig</code> file, to compile and execute this build script, which in turn, will compile and build your entire project.</p>
-<div class="sourceCode" id="cb14"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zig</span> build</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode" id="cb18"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb18-1"><a href="#cb18-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zig</span> build</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <p>After you execute this “build project” command, a <code>zig-out</code> directory is created in the root of your project directory, where you can find the binary executables and libraries created from your Zig modules accordingly to the build commands that you specified at <code>build.zig</code>. We will talk more about the build system in Zig latter in this book.</p>
 <p>In the example below, I’m executing the binary executable named <code>hello_world</code> that was generated by the compiler after the <code>zig build</code> command.</p>
-<div class="sourceCode" id="cb15"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb15-1"><a href="#cb15-1" aria-hidden="true" tabindex="-1"></a><span class="ex">./zig-out/bin/hello_world</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode" id="cb19"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb19-1"><a href="#cb19-1" aria-hidden="true" tabindex="-1"></a><span class="ex">./zig-out/bin/hello_world</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <pre><code>Hello, world!</code></pre>
 </section>
 </section>
@@ -493,17 +526,17 @@ <h2 data-number="1.3" class="anchored" data-anchor-id="how-to-learn-zig"><span c
 <li>Discord, Slack, Telegram, and others: <a href="https://github.com/ziglang/zig/wiki/Community" class="uri">https://github.com/ziglang/zig/wiki/Community</a>;</li>
 </ul>
 <p>Now, one of the best ways to learn Zig is to simply read Zig code. Try to read Zig code often, and things will become more clear. A C/C++ programmer would also probably give you this same tip. Because this strategy really works!</p>
-<p>Now, where can you find Zig code to read? I personally think that, the best way of reading Zig code is to read the source code of the Zig Standard Library. The Zig Standard Library is available at the <a href="https://github.com/ziglang/zig/tree/master/lib/std"><code>lib/std</code> folder</a><a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a> on the official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.</p>
+<p>Now, where can you find Zig code to read? I personally think that, the best way of reading Zig code is to read the source code of the Zig Standard Library. The Zig Standard Library is available at the <a href="https://github.com/ziglang/zig/tree/master/lib/std"><code>lib/std</code> folder</a><a href="#fn5" class="footnote-ref" id="fnref5" role="doc-noteref"><sup>5</sup></a> on the official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.</p>
 <p>Also, a great alternative is to read code from other large Zig codebases, such as:</p>
 <ol type="1">
-<li>the <a href="https://github.com/oven-sh/bun">Javascript runtime Bun</a><a href="#fn4" class="footnote-ref" id="fnref4" role="doc-noteref"><sup>4</sup></a>.</li>
-<li>the <a href="https://github.com/hexops/mach">game engine Mach</a><a href="#fn5" class="footnote-ref" id="fnref5" role="doc-noteref"><sup>5</sup></a>.</li>
-<li>a <a href="https://github.com/cgbur/llama2.zig/tree/main">LLama 2 LLM model implementation in Zig</a><a href="#fn6" class="footnote-ref" id="fnref6" role="doc-noteref"><sup>6</sup></a>.</li>
-<li>the <a href="https://github.com/tigerbeetle/tigerbeetle">financial transactions database <code>tigerbeetle</code></a><a href="#fn7" class="footnote-ref" id="fnref7" role="doc-noteref"><sup>7</sup></a>.</li>
-<li>the <a href="https://github.com/Hejsil/zig-clap">command-line arguments parser <code>zig-clap</code></a><a href="#fn8" class="footnote-ref" id="fnref8" role="doc-noteref"><sup>8</sup></a>.</li>
-<li>the <a href="https://github.com/capy-ui/capy">UI framework <code>capy</code></a><a href="#fn9" class="footnote-ref" id="fnref9" role="doc-noteref"><sup>9</sup></a>.</li>
-<li>the <a href="https://github.com/zigtools/zls">Language Protocol implementation for Zig, <code>zls</code></a><a href="#fn10" class="footnote-ref" id="fnref10" role="doc-noteref"><sup>10</sup></a>.</li>
-<li>the <a href="https://github.com/mitchellh/libxev">event-loop library <code>libxev</code></a><a href="#fn11" class="footnote-ref" id="fnref11" role="doc-noteref"><sup>11</sup></a>.</li>
+<li>the <a href="https://github.com/oven-sh/bun">Javascript runtime Bun</a><a href="#fn6" class="footnote-ref" id="fnref6" role="doc-noteref"><sup>6</sup></a>.</li>
+<li>the <a href="https://github.com/hexops/mach">game engine Mach</a><a href="#fn7" class="footnote-ref" id="fnref7" role="doc-noteref"><sup>7</sup></a>.</li>
+<li>a <a href="https://github.com/cgbur/llama2.zig/tree/main">LLama 2 LLM model implementation in Zig</a><a href="#fn8" class="footnote-ref" id="fnref8" role="doc-noteref"><sup>8</sup></a>.</li>
+<li>the <a href="https://github.com/tigerbeetle/tigerbeetle">financial transactions database <code>tigerbeetle</code></a><a href="#fn9" class="footnote-ref" id="fnref9" role="doc-noteref"><sup>9</sup></a>.</li>
+<li>the <a href="https://github.com/Hejsil/zig-clap">command-line arguments parser <code>zig-clap</code></a><a href="#fn10" class="footnote-ref" id="fnref10" role="doc-noteref"><sup>10</sup></a>.</li>
+<li>the <a href="https://github.com/capy-ui/capy">UI framework <code>capy</code></a><a href="#fn11" class="footnote-ref" id="fnref11" role="doc-noteref"><sup>11</sup></a>.</li>
+<li>the <a href="https://github.com/zigtools/zls">Language Protocol implementation for Zig, <code>zls</code></a><a href="#fn12" class="footnote-ref" id="fnref12" role="doc-noteref"><sup>12</sup></a>.</li>
+<li>the <a href="https://github.com/mitchellh/libxev">event-loop library <code>libxev</code></a><a href="#fn13" class="footnote-ref" id="fnref13" role="doc-noteref"><sup>13</sup></a>.</li>
 </ol>
 <p>All these assets are available on GitHub, and this is great, because we can use the GitHub search bar in our advantage, to find Zig code that fits our description. For example, you can always include <code>lang:Zig</code> in the GitHub search bar when you are searching for a particular pattern. This will limit the search to only Zig modules.</p>
 <p>Also, a great alternative is to consult online resources and documentations. Here is a quick list of resources that I personally use from time to time to learn more about the language each day:</p>
@@ -516,9 +549,9 @@ <h2 data-number="1.3" class="anchored" data-anchor-id="how-to-learn-zig"><span c
 <li>Read the code written by one of the Zig core team members: <a href="https://github.com/kubkon" class="uri">https://github.com/kubkon</a>;</li>
 <li>Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <a href="https://www.youtube.com/@ZigSHOWTIME/videos" class="uri">https://www.youtube.com/@ZigSHOWTIME/videos</a>;</li>
 </ul>
-<p>Another great strategy to learn Zig, or honestly, to learn any language you want, is to practice it by solving exercises. For example, there is a famous repository in the Zig community called <a href="https://ziglings.org">Ziglings</a><a href="#fn12" class="footnote-ref" id="fnref12" role="doc-noteref"><sup>12</sup></a> , which contains more than 100 small exercises that you can solve. It is a repository of tiny programs written in Zig that are currently broken, and your responsibility is to fix these programs, and make them work again.</p>
-<p>A famous tech YouTuber known as <em>The Primeagen</em> also posted some videos (at YouTube) where he solves these exercises from Ziglings. The first video is named <a href="https://www.youtube.com/watch?v=OPuztQfM3Fg&amp;t=2524s&amp;ab_channel=TheVimeagen">“Trying Zig Part 1”</a><a href="#fn13" class="footnote-ref" id="fnref13" role="doc-noteref"><sup>13</sup></a>.</p>
-<p>Another great alternative, is to solve the <a href="https://adventofcode.com/">Advent of Code exercises</a><a href="#fn14" class="footnote-ref" id="fnref14" role="doc-noteref"><sup>14</sup></a>. There are people that already took the time to learn and solve the exercises, and they posted their solutions on GitHub as well, so, in case you need some resource to compare while solving the exercises, you can look at these two repositories:</p>
+<p>Another great strategy to learn Zig, or honestly, to learn any language you want, is to practice it by solving exercises. For example, there is a famous repository in the Zig community called <a href="https://ziglings.org">Ziglings</a><a href="#fn14" class="footnote-ref" id="fnref14" role="doc-noteref"><sup>14</sup></a> , which contains more than 100 small exercises that you can solve. It is a repository of tiny programs written in Zig that are currently broken, and your responsibility is to fix these programs, and make them work again.</p>
+<p>A famous tech YouTuber known as <em>The Primeagen</em> also posted some videos (at YouTube) where he solves these exercises from Ziglings. The first video is named <a href="https://www.youtube.com/watch?v=OPuztQfM3Fg&amp;t=2524s&amp;ab_channel=TheVimeagen">“Trying Zig Part 1”</a><a href="#fn15" class="footnote-ref" id="fnref15" role="doc-noteref"><sup>15</sup></a>.</p>
+<p>Another great alternative, is to solve the <a href="https://adventofcode.com/">Advent of Code exercises</a><a href="#fn16" class="footnote-ref" id="fnref16" role="doc-noteref"><sup>16</sup></a>. There are people that already took the time to learn and solve the exercises, and they posted their solutions on GitHub as well, so, in case you need some resource to compare while solving the exercises, you can look at these two repositories:</p>
 <ul>
 <li><a href="https://github.com/SpexGuy/Zig-AoC-Template" class="uri">https://github.com/SpexGuy/Zig-AoC-Template</a>;</li>
 <li><a href="https://github.com/fjebaker/advent-of-code-2022" class="uri">https://github.com/fjebaker/advent-of-code-2022</a>;</li>
@@ -534,9 +567,9 @@ <h3 data-number="1.4.1" class="anchored" data-anchor-id="constant-objects-vs-var
 <p>In the code example below, we are creating a new constant object called <code>age</code>. This object stores a number representing the age of someone. However, this code example does not compiles successfully. Because on the next line of code, we are trying to change the value of the object <code>age</code> to 25.</p>
 <p>The <code>zig</code> compiler detects that we are trying to change the value of an object/identifier that is constant, and because of that, the compiler will raise a compilation error, warning us about the mistake.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb17"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> age = <span class="dv">24</span>;</span>
-<span id="cb17-2"><a href="#cb17-2" aria-hidden="true" tabindex="-1"></a><span class="co">// The line below is not valid!</span></span>
-<span id="cb17-3"><a href="#cb17-3" aria-hidden="true" tabindex="-1"></a>age = <span class="dv">25</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb21"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb21-1"><a href="#cb21-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> age = <span class="dv">24</span>;</span>
+<span id="cb21-2"><a href="#cb21-2" aria-hidden="true" tabindex="-1"></a><span class="co">// The line below is not valid!</span></span>
+<span id="cb21-3"><a href="#cb21-3" aria-hidden="true" tabindex="-1"></a>age = <span class="dv">25</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>t.zig:10:5: error: cannot assign to constant
     age = 25;
@@ -544,8 +577,8 @@ <h3 data-number="1.4.1" class="anchored" data-anchor-id="constant-objects-vs-var
 <p>In contrast, if you use <code>var</code>, then, the object created is a variable object. With <code>var</code> you can declare this object in your source code, and then, change the value of this object how many times you want over future points in your source code.</p>
 <p>So, using the same code example exposed above, if I change the declaration of the <code>age</code> object to use the <code>var</code> keyword, then, the program gets compiled successfully. Because now, the <code>zig</code> compiler detects that we are changing the value of an object that allows this behaviour, because it is an “variable object”.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb19"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb19-1"><a href="#cb19-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> age: <span class="dt">u8</span> = <span class="dv">24</span>;</span>
-<span id="cb19-2"><a href="#cb19-2" aria-hidden="true" tabindex="-1"></a>age = <span class="dv">25</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb23"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb23-1"><a href="#cb23-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> age: <span class="dt">u8</span> = <span class="dv">24</span>;</span>
+<span id="cb23-2"><a href="#cb23-2" aria-hidden="true" tabindex="-1"></a>age = <span class="dv">25</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
 <section id="declaring-without-an-initial-value" class="level3" data-number="1.4.2">
@@ -555,8 +588,8 @@ <h3 data-number="1.4.2" class="anchored" data-anchor-id="declaring-without-an-in
 <p>Is important to emphasize that, you should avoid using <code>undefined</code> as much as possible. Because when you use this keyword, you leave your object uninitialized, and, as a consequence, if for some reason, your code use this object while it is uninitialized, then, you will definitely have undefined behaviour and major bugs in your program.</p>
 <p>In the example below, I’m declaring the <code>age</code> object again. But this time, I do not give it an initial value. The variable is only initialized at the second line of code, where I store the number 25 in this object.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb20"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb20-1"><a href="#cb20-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> age: <span class="dt">u8</span> = <span class="cn">undefined</span>;</span>
-<span id="cb20-2"><a href="#cb20-2" aria-hidden="true" tabindex="-1"></a>age = <span class="dv">25</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb24"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb24-1"><a href="#cb24-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> age: <span class="dt">u8</span> = <span class="cn">undefined</span>;</span>
+<span id="cb24-2"><a href="#cb24-2" aria-hidden="true" tabindex="-1"></a>age = <span class="dv">25</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>Having these points in mind, just remember that you should avoid as much as possible to use <code>undefined</code> in your code. Always declare and initialize your objects. Because this gives you much more safety in your program. But in case you really need to declare an object without initializing it… the <code>undefined</code> keyword is the way to do it in Zig.</p>
 </section>
@@ -566,7 +599,7 @@ <h3 data-number="1.4.3" class="anchored" data-anchor-id="there-is-no-such-thing-
 <p>It doesn’t matter in which way you use it. As long as you use it. If you try to break this rule, i.e.&nbsp;if your try to declare a object, but not use it, the <code>zig</code> compiler will not compile your Zig source code, and it will issue a error message warning that you have unused objects in your code.</p>
 <p>Let’s demonstrate this with an example. In the source code below, we declare a constant object called <code>age</code>. If you try to compile a simple Zig program with this line of code below, the compiler will return an error as demonstrated below:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb21"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb21-1"><a href="#cb21-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> age = <span class="dv">15</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb25"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb25-1"><a href="#cb25-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> age = <span class="dv">15</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>t.zig:4:11: error: unused local constant
     const age = 15;
@@ -579,18 +612,18 @@ <h3 data-number="1.4.3" class="anchored" data-anchor-id="there-is-no-such-thing-
 <p>To explicitly discard the value of any object (constant or variable), all you need to do is to assign this object to an special character in Zig, which is the underscore (<code>_</code>). When you assign an object to a underscore, like in the example below, the <code>zig</code> compiler will automatically discard the value of this particular object.</p>
 <p>You can see in the example below that, this time, the compiler did not complain about any “unused constant”, and successfully compiled our source code.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb23"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb23-1"><a href="#cb23-1" aria-hidden="true" tabindex="-1"></a><span class="co">// It compiles!</span></span>
-<span id="cb23-2"><a href="#cb23-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> age = <span class="dv">15</span>;</span>
-<span id="cb23-3"><a href="#cb23-3" aria-hidden="true" tabindex="-1"></a>_ = age;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb27"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb27-1"><a href="#cb27-1" aria-hidden="true" tabindex="-1"></a><span class="co">// It compiles!</span></span>
+<span id="cb27-2"><a href="#cb27-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> age = <span class="dv">15</span>;</span>
+<span id="cb27-3"><a href="#cb27-3" aria-hidden="true" tabindex="-1"></a>_ = age;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>Now, remember, everytime you assign a particular object to the underscore, this object is essentially destroyed. It is discarded by the compiler. This means that you can no longer use this object further in your code. It doesn’t exist anymore.</p>
 <p>So if you try to use the constant <code>age</code> in the example below, after we discarded it, you will get a loud error message from the compiler (talking about a “pointless discard”) warning you about this mistake.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb24"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb24-1"><a href="#cb24-1" aria-hidden="true" tabindex="-1"></a><span class="co">// It does not compile.</span></span>
-<span id="cb24-2"><a href="#cb24-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> age = <span class="dv">15</span>;</span>
-<span id="cb24-3"><a href="#cb24-3" aria-hidden="true" tabindex="-1"></a>_ = age;</span>
-<span id="cb24-4"><a href="#cb24-4" aria-hidden="true" tabindex="-1"></a><span class="co">// Using a discarded value!</span></span>
-<span id="cb24-5"><a href="#cb24-5" aria-hidden="true" tabindex="-1"></a>std.debug.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>age + <span class="dv">2</span><span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb28"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb28-1"><a href="#cb28-1" aria-hidden="true" tabindex="-1"></a><span class="co">// It does not compile.</span></span>
+<span id="cb28-2"><a href="#cb28-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> age = <span class="dv">15</span>;</span>
+<span id="cb28-3"><a href="#cb28-3" aria-hidden="true" tabindex="-1"></a>_ = age;</span>
+<span id="cb28-4"><a href="#cb28-4" aria-hidden="true" tabindex="-1"></a><span class="co">// Using a discarded value!</span></span>
+<span id="cb28-5"><a href="#cb28-5" aria-hidden="true" tabindex="-1"></a>std.debug.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>age + <span class="dv">2</span><span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>t.zig:7:5: error: pointless discard
     of local constant</code></pre>
@@ -602,8 +635,8 @@ <h3 data-number="1.4.4" class="anchored" data-anchor-id="you-must-mutate-every-v
 <p>The concept behind this is that every object you create in Zig should be preferably a constant object, unless you really need an object whose value will change during the execution of your program.</p>
 <p>So, if I try to declare a variable object such as <code>where_i_live</code> below, and I do not change the value of this object in some way, the <code>zig</code> compiler raises an error message with the phrase “variable is never mutated”.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb26"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb26-1"><a href="#cb26-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> where_i_live = <span class="st">"Belo Horizonte"</span>;</span>
-<span id="cb26-2"><a href="#cb26-2" aria-hidden="true" tabindex="-1"></a>_ = where_i_live;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb30"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb30-1"><a href="#cb30-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> where_i_live = <span class="st">"Belo Horizonte"</span>;</span>
+<span id="cb30-2"><a href="#cb30-2" aria-hidden="true" tabindex="-1"></a>_ = where_i_live;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>t.zig:7:5: error: local variable is never mutated
 t.zig:7:5: note: consider using 'const'</code></pre>
@@ -611,7 +644,7 @@ <h3 data-number="1.4.4" class="anchored" data-anchor-id="you-must-mutate-every-v
 </section>
 <section id="sec-primitive-data-types" class="level2" data-number="1.5">
 <h2 data-number="1.5" class="anchored" data-anchor-id="sec-primitive-data-types"><span class="header-section-number">1.5</span> Primitive Data Types</h2>
-<p>Zig have many different primitive data types available for you to use. You can see the full list of available data types at the official <a href="https://ziglang.org/documentation/master/#Primitive-Types">Language Reference page</a><a href="#fn15" class="footnote-ref" id="fnref15" role="doc-noteref"><sup>15</sup></a>.</p>
+<p>Zig have many different primitive data types available for you to use. You can see the full list of available data types at the official <a href="https://ziglang.org/documentation/master/#Primitive-Types">Language Reference page</a><a href="#fn17" class="footnote-ref" id="fnref17" role="doc-noteref"><sup>17</sup></a>.</p>
 <p>But here is a quick list:</p>
 <ul>
 <li>Unsigned integers: <code>u8</code>, 8-bit integer; <code>u16</code>, 16-bit integer; <code>u32</code>, 32-bit integer; <code>u64</code>, 64-bit integer; <code>u128</code>, 128-bit integer.</li>
@@ -629,17 +662,17 @@ <h2 data-number="1.6" class="anchored" data-anchor-id="sec-arrays"><span class="
 <p>After that, you simply list the values that you want to store in this array inside a pair of curly braces. In the example below, I am creating two constant objects that contain different arrays. The first object contains an array of 4 integer values, while the second object, an array of 3 floating point values.</p>
 <p>Now, you should notice that in the object <code>ls</code>, I am not explicitly specifying the size of the array inside of the brackets. Instead of using a literal value (like the value 4 that I used in the <code>ns</code> object), I am using the special character underscore (<code>_</code>). This syntax tells the <code>zig</code> compiler to fill this field with the number of elements listed inside of the curly braces. So, this syntax <code>[_]</code> is for lazy (or smart) programmers who leave the job of counting how many elements there are in the curly braces for the compiler.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb28"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb28-1"><a href="#cb28-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ns = [<span class="dv">4</span>]<span class="dt">u8</span><span class="op">{</span><span class="dv">48</span>, <span class="dv">24</span>, <span class="dv">12</span>, <span class="dv">6</span><span class="op">}</span>;</span>
-<span id="cb28-2"><a href="#cb28-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ls = [_]<span class="dt">f64</span><span class="op">{</span><span class="fl">432.1</span>, <span class="fl">87.2</span>, <span class="fl">900.05</span><span class="op">}</span>;</span>
-<span id="cb28-3"><a href="#cb28-3" aria-hidden="true" tabindex="-1"></a>_ = ns; _ = ls;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb32"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb32-1"><a href="#cb32-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ns = [<span class="dv">4</span>]<span class="dt">u8</span><span class="op">{</span><span class="dv">48</span>, <span class="dv">24</span>, <span class="dv">12</span>, <span class="dv">6</span><span class="op">}</span>;</span>
+<span id="cb32-2"><a href="#cb32-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ls = [_]<span class="dt">f64</span><span class="op">{</span><span class="fl">432.1</span>, <span class="fl">87.2</span>, <span class="fl">900.05</span><span class="op">}</span>;</span>
+<span id="cb32-3"><a href="#cb32-3" aria-hidden="true" tabindex="-1"></a>_ = ns; _ = ls;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>Is worth noting that these are static arrays, meaning that they cannot grow in size. Once you declare your array, you cannot change the size of it. This is very common in low level languages. Because low level languages normally wants to give you (the programmer) full control over memory, and the way in which arrays are expanded is tightly related to memory management.</p>
 <section id="sec-select-array-elem" class="level3" data-number="1.6.1">
 <h3 data-number="1.6.1" class="anchored" data-anchor-id="sec-select-array-elem"><span class="header-section-number">1.6.1</span> Selecting elements of the array</h3>
 <p>One very common activity is to select specific portions of an array you have in your source code. In Zig, you can select a specific element from your array, by simply providing the index of this particular element inside brackets after the object name. In the example below, I am selecting the third element from the <code>ns</code> array. Notice that Zig is a “zero-index” based language, like C, C++, Rust, Python, and many other languages.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb29"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb29-1"><a href="#cb29-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ns = [<span class="dv">4</span>]<span class="dt">u8</span><span class="op">{</span><span class="dv">48</span>, <span class="dv">24</span>, <span class="dv">12</span>, <span class="dv">6</span><span class="op">}</span>;</span>
-<span id="cb29-2"><a href="#cb29-2" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span> ns[<span class="dv">2</span>] <span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb33"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb33-1"><a href="#cb33-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ns = [<span class="dv">4</span>]<span class="dt">u8</span><span class="op">{</span><span class="dv">48</span>, <span class="dv">24</span>, <span class="dv">12</span>, <span class="dv">6</span><span class="op">}</span>;</span>
+<span id="cb33-2"><a href="#cb33-2" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span> ns[<span class="dv">2</span>] <span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>12</code></pre>
 </div>
@@ -647,22 +680,22 @@ <h3 data-number="1.6.1" class="anchored" data-anchor-id="sec-select-array-elem">
 <p>In contrast, you can also select specific slices (or sections) of your array, by using a range selector. Some programmers also call these selectors of “slice selectors”, and they also exist in Rust, and have the exact same syntax as in Zig. Anyway, a range selector is a special expression in Zig that defines a range of indexes, and it have the syntax <code>start..end</code>.</p>
 <p>In the example below, at the second line of code, the <code>sl</code> object stores a slice (or a portion) of the <code>ns</code> array. More precisely, the elements at index 1 and 2 in the <code>ns</code> array.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb31"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb31-1"><a href="#cb31-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ns = [<span class="dv">4</span>]<span class="dt">u8</span><span class="op">{</span><span class="dv">48</span>, <span class="dv">24</span>, <span class="dv">12</span>, <span class="dv">6</span><span class="op">}</span>;</span>
-<span id="cb31-2"><a href="#cb31-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> sl = ns[<span class="dv">1</span>..<span class="dv">3</span>];</span>
-<span id="cb31-3"><a href="#cb31-3" aria-hidden="true" tabindex="-1"></a>_ = sl;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb35"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb35-1"><a href="#cb35-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ns = [<span class="dv">4</span>]<span class="dt">u8</span><span class="op">{</span><span class="dv">48</span>, <span class="dv">24</span>, <span class="dv">12</span>, <span class="dv">6</span><span class="op">}</span>;</span>
+<span id="cb35-2"><a href="#cb35-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> sl = ns[<span class="dv">1</span>..<span class="dv">3</span>];</span>
+<span id="cb35-3"><a href="#cb35-3" aria-hidden="true" tabindex="-1"></a>_ = sl;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>When you use the <code>start..end</code> syntax, the “end tail” of the range selector is non-inclusive, meaning that, the index at the end is not included in the range that is selected from the array. Therefore, the syntax <code>start..end</code> actually means <code>start..end - 1</code> in practice.</p>
 <p>You can for example, create a slice that goes from the first to the last elements of the array, by using <code>ar[0..ar.len]</code> syntax In other words, it is a slice that access all elements in the array.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb32"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb32-1"><a href="#cb32-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ar = [<span class="dv">4</span>]<span class="dt">u8</span><span class="op">{</span><span class="dv">48</span>, <span class="dv">24</span>, <span class="dv">12</span>, <span class="dv">6</span><span class="op">}</span>;</span>
-<span id="cb32-2"><a href="#cb32-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> sl = ar[<span class="dv">0</span>..ar.len];</span>
-<span id="cb32-3"><a href="#cb32-3" aria-hidden="true" tabindex="-1"></a>_ = sl;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb36"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb36-1"><a href="#cb36-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ar = [<span class="dv">4</span>]<span class="dt">u8</span><span class="op">{</span><span class="dv">48</span>, <span class="dv">24</span>, <span class="dv">12</span>, <span class="dv">6</span><span class="op">}</span>;</span>
+<span id="cb36-2"><a href="#cb36-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> sl = ar[<span class="dv">0</span>..ar.len];</span>
+<span id="cb36-3"><a href="#cb36-3" aria-hidden="true" tabindex="-1"></a>_ = sl;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>You can also use the syntax <code>start..</code> in your range selector. Which tells the <code>zig</code> compiler to select the portion of the array that begins at the <code>start</code> index until the last element of the array. In the example below, we are selecting the range from index 1 until the end of the array.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb33"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb33-1"><a href="#cb33-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ns = [<span class="dv">4</span>]<span class="dt">u8</span><span class="op">{</span><span class="dv">48</span>, <span class="dv">24</span>, <span class="dv">12</span>, <span class="dv">6</span><span class="op">}</span>;</span>
-<span id="cb33-2"><a href="#cb33-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> sl = ns[<span class="dv">1</span>..];</span>
-<span id="cb33-3"><a href="#cb33-3" aria-hidden="true" tabindex="-1"></a>_ = sl;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb37"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb37-1"><a href="#cb37-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ns = [<span class="dv">4</span>]<span class="dt">u8</span><span class="op">{</span><span class="dv">48</span>, <span class="dv">24</span>, <span class="dv">12</span>, <span class="dv">6</span><span class="op">}</span>;</span>
+<span id="cb37-2"><a href="#cb37-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> sl = ns[<span class="dv">1</span>..];</span>
+<span id="cb37-3"><a href="#cb37-3" aria-hidden="true" tabindex="-1"></a>_ = sl;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
 <section id="more-on-slices" class="level3" data-number="1.6.2">
@@ -675,9 +708,9 @@ <h3 data-number="1.6.2" class="anchored" data-anchor-id="more-on-slices"><span c
 <p>Through the pointer contained inside the slice you can access the elements (or values) that are inside this range (or portion) that you selected from the original array. But the length number (which you can access through the <code>len</code> property of your slice object) is the really big improvement (over C arrays for example) that Zig brings to the table here.</p>
 <p>Because with this length number the <code>zig</code> compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice, or, if you are causing any buffer overflow problems. In the example below, we access the <code>len</code> property of the slice <code>sl</code>, which tells us that this slice have 2 elements in it.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb34"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb34-1"><a href="#cb34-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ns = [<span class="dv">4</span>]<span class="dt">u8</span><span class="op">{</span><span class="dv">48</span>, <span class="dv">24</span>, <span class="dv">12</span>, <span class="dv">6</span><span class="op">}</span>;</span>
-<span id="cb34-2"><a href="#cb34-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> sl = ns[<span class="dv">1</span>..<span class="dv">3</span>];</span>
-<span id="cb34-3"><a href="#cb34-3" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>sl.len<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb38"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb38-1"><a href="#cb38-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ns = [<span class="dv">4</span>]<span class="dt">u8</span><span class="op">{</span><span class="dv">48</span>, <span class="dv">24</span>, <span class="dv">12</span>, <span class="dv">6</span><span class="op">}</span>;</span>
+<span id="cb38-2"><a href="#cb38-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> sl = ns[<span class="dv">1</span>..<span class="dv">3</span>];</span>
+<span id="cb38-3"><a href="#cb38-3" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>sl.len<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>2</code></pre>
 </div>
@@ -689,10 +722,10 @@ <h3 data-number="1.6.3" class="anchored" data-anchor-id="array-operators"><span
 <p>One important detail about these two operators is that they work only when both operands have a size (or “length”) that is compile-time known. We are going to talk more about the differences between “compile-time known” and “runtime known” at <a href="01-memory.html#sec-compile-time" class="quarto-xref"><span>Section 3.1.1</span></a>. But for now, keep this information in mind, that you cannot use these operators in every situation.</p>
 <p>In summary, the <code>++</code> operator creates a new array that is the concatenation, of both arrays provided as operands. So, the expression <code>a ++ b</code> produces a new array which contains all the elements from arrays <code>a</code> and <code>b</code>.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb36"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb36-1"><a href="#cb36-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> a = [_]<span class="dt">u8</span><span class="op">{</span><span class="dv">1</span>,<span class="dv">2</span>,<span class="dv">3</span><span class="op">}</span>;</span>
-<span id="cb36-2"><a href="#cb36-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> b = [_]<span class="dt">u8</span><span class="op">{</span><span class="dv">4</span>,<span class="dv">5</span><span class="op">}</span>;</span>
-<span id="cb36-3"><a href="#cb36-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> c = a ++ b;</span>
-<span id="cb36-4"><a href="#cb36-4" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{any}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>c<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb40"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb40-1"><a href="#cb40-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> a = [_]<span class="dt">u8</span><span class="op">{</span><span class="dv">1</span>,<span class="dv">2</span>,<span class="dv">3</span><span class="op">}</span>;</span>
+<span id="cb40-2"><a href="#cb40-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> b = [_]<span class="dt">u8</span><span class="op">{</span><span class="dv">4</span>,<span class="dv">5</span><span class="op">}</span>;</span>
+<span id="cb40-3"><a href="#cb40-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> c = a ++ b;</span>
+<span id="cb40-4"><a href="#cb40-4" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{any}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>c<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>{ 1, 2, 3, 4, 5 }</code></pre>
 </div>
@@ -700,9 +733,9 @@ <h3 data-number="1.6.3" class="anchored" data-anchor-id="array-operators"><span
 <p>This <code>++</code> operator is particularly useful to concatenate strings together. Strings in Zig are described in depth at <a href="#sec-zig-strings" class="quarto-xref"><span>Section 1.8</span></a>. In summary, a string object in Zig is essentially an arrays of bytes. So, you can use this array concatenation operator to effectively concatenate strings together.</p>
 <p>In contrast, the <code>**</code> operator is used to replicate an array multiple times. In other words, the expression <code>a ** 3</code> creates a new array which contains the elements of the array <code>a</code> repeated 3 times.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb38"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb38-1"><a href="#cb38-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> a = [_]<span class="dt">u8</span><span class="op">{</span><span class="dv">1</span>,<span class="dv">2</span>,<span class="dv">3</span><span class="op">}</span>;</span>
-<span id="cb38-2"><a href="#cb38-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> c = a ** <span class="dv">2</span>;</span>
-<span id="cb38-3"><a href="#cb38-3" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{any}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>c<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb42"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb42-1"><a href="#cb42-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> a = [_]<span class="dt">u8</span><span class="op">{</span><span class="dv">1</span>,<span class="dv">2</span>,<span class="dv">3</span><span class="op">}</span>;</span>
+<span id="cb42-2"><a href="#cb42-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> c = a ** <span class="dv">2</span>;</span>
+<span id="cb42-3"><a href="#cb42-3" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{any}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>c<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>{ 1, 2, 3, 1, 2, 3 }</code></pre>
 </div>
@@ -715,33 +748,33 @@ <h3 data-number="1.6.4" class="anchored" data-anchor-id="runtime-versus-compile-
 <p>You don’t need to precisely understand what that means now. We are going to talk a lot about pointers at <a href="05-pointers.html" class="quarto-xref"><span>Chapter 6</span></a>. For now, just understand that, when the range of indexes is known at compile-time, the slice that get’s created is just a pointer to an array, accompanied by a length value that tells the size of the slice.</p>
 <p>If you have a slice object like this, i.e.&nbsp;a slice that has a compile-time known range, you can use common pointer operations over this slice object. For example, you can dereference the pointer of this slice, by using the <code>.*</code> method, like you would do on a normal pointer object.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb40"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb40-1"><a href="#cb40-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> arr1 = [<span class="dv">10</span>]<span class="dt">u64</span> <span class="op">{</span></span>
-<span id="cb40-2"><a href="#cb40-2" aria-hidden="true" tabindex="-1"></a>    <span class="dv">1</span>, <span class="dv">2</span>, <span class="dv">3</span>, <span class="dv">4</span>, <span class="dv">5</span>,</span>
-<span id="cb40-3"><a href="#cb40-3" aria-hidden="true" tabindex="-1"></a>    <span class="dv">6</span>, <span class="dv">7</span>, <span class="dv">8</span>, <span class="dv">9</span>, <span class="dv">10</span></span>
-<span id="cb40-4"><a href="#cb40-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
-<span id="cb40-5"><a href="#cb40-5" aria-hidden="true" tabindex="-1"></a><span class="co">// This slice have a compile-time known range.</span></span>
-<span id="cb40-6"><a href="#cb40-6" aria-hidden="true" tabindex="-1"></a><span class="co">// Because we know both the start and end of the range.</span></span>
-<span id="cb40-7"><a href="#cb40-7" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> slice = arr1[<span class="dv">1</span>..<span class="dv">4</span>];</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb44"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb44-1"><a href="#cb44-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> arr1 = [<span class="dv">10</span>]<span class="dt">u64</span> <span class="op">{</span></span>
+<span id="cb44-2"><a href="#cb44-2" aria-hidden="true" tabindex="-1"></a>    <span class="dv">1</span>, <span class="dv">2</span>, <span class="dv">3</span>, <span class="dv">4</span>, <span class="dv">5</span>,</span>
+<span id="cb44-3"><a href="#cb44-3" aria-hidden="true" tabindex="-1"></a>    <span class="dv">6</span>, <span class="dv">7</span>, <span class="dv">8</span>, <span class="dv">9</span>, <span class="dv">10</span></span>
+<span id="cb44-4"><a href="#cb44-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
+<span id="cb44-5"><a href="#cb44-5" aria-hidden="true" tabindex="-1"></a><span class="co">// This slice have a compile-time known range.</span></span>
+<span id="cb44-6"><a href="#cb44-6" aria-hidden="true" tabindex="-1"></a><span class="co">// Because we know both the start and end of the range.</span></span>
+<span id="cb44-7"><a href="#cb44-7" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> slice = arr1[<span class="dv">1</span>..<span class="dv">4</span>];</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>On the other hand, if the range of indexes is not known at compile time, then, the slice object that get’s created is not a pointer anymore, and, thus, it does not support pointer operations. For example, maybe the start index is known at compile time, but the end index is not. In such case, the range of the slice becomes runtime known only.</p>
 <p>In the example below, the <code>slice</code> object have a runtime known range, because the end index of the range is not known at compile time. In other words, the size of the array at <code>buffer</code> is not known at compile time. When we execute this program, the size of the array might be 10, or, it might be 12 depending on where we execute it. Therefore, we don’t know at compile time if the slice object have a range of size 10, or, a range of size 12.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb41"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb41-1"><a href="#cb41-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb41-2"><a href="#cb41-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> builtin = <span class="bu">@import</span>(<span class="st">"builtin"</span>);</span>
-<span id="cb41-3"><a href="#cb41-3" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb41-4"><a href="#cb41-4" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb41-5"><a href="#cb41-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> gpa = std.heap.GeneralPurposeAllocator(.<span class="op">{}</span>)<span class="op">{}</span>;</span>
-<span id="cb41-6"><a href="#cb41-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> allocator = gpa.allocator();</span>
-<span id="cb41-7"><a href="#cb41-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> n: <span class="dt">usize</span> = <span class="dv">0</span>;</span>
-<span id="cb41-8"><a href="#cb41-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> (builtin.target.os.tag == .windows) <span class="op">{</span></span>
-<span id="cb41-9"><a href="#cb41-9" aria-hidden="true" tabindex="-1"></a>        n = <span class="dv">10</span>;</span>
-<span id="cb41-10"><a href="#cb41-10" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span> <span class="kw">else</span> <span class="op">{</span></span>
-<span id="cb41-11"><a href="#cb41-11" aria-hidden="true" tabindex="-1"></a>        n = <span class="dv">12</span>;</span>
-<span id="cb41-12"><a href="#cb41-12" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb41-13"><a href="#cb41-13" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> buffer = <span class="kw">try</span> allocator.alloc(<span class="dt">u64</span>, n);</span>
-<span id="cb41-14"><a href="#cb41-14" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> slice = buffer[<span class="dv">0</span>..];</span>
-<span id="cb41-15"><a href="#cb41-15" aria-hidden="true" tabindex="-1"></a>    _ = slice;</span>
-<span id="cb41-16"><a href="#cb41-16" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb45"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb45-1"><a href="#cb45-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb45-2"><a href="#cb45-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> builtin = <span class="bu">@import</span>(<span class="st">"builtin"</span>);</span>
+<span id="cb45-3"><a href="#cb45-3" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb45-4"><a href="#cb45-4" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb45-5"><a href="#cb45-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> gpa = std.heap.GeneralPurposeAllocator(.<span class="op">{}</span>)<span class="op">{}</span>;</span>
+<span id="cb45-6"><a href="#cb45-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> allocator = gpa.allocator();</span>
+<span id="cb45-7"><a href="#cb45-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> n: <span class="dt">usize</span> = <span class="dv">0</span>;</span>
+<span id="cb45-8"><a href="#cb45-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> (builtin.target.os.tag == .windows) <span class="op">{</span></span>
+<span id="cb45-9"><a href="#cb45-9" aria-hidden="true" tabindex="-1"></a>        n = <span class="dv">10</span>;</span>
+<span id="cb45-10"><a href="#cb45-10" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span> <span class="kw">else</span> <span class="op">{</span></span>
+<span id="cb45-11"><a href="#cb45-11" aria-hidden="true" tabindex="-1"></a>        n = <span class="dv">12</span>;</span>
+<span id="cb45-12"><a href="#cb45-12" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb45-13"><a href="#cb45-13" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> buffer = <span class="kw">try</span> allocator.alloc(<span class="dt">u64</span>, n);</span>
+<span id="cb45-14"><a href="#cb45-14" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> slice = buffer[<span class="dv">0</span>..];</span>
+<span id="cb45-15"><a href="#cb45-15" aria-hidden="true" tabindex="-1"></a>    _ = slice;</span>
+<span id="cb45-16"><a href="#cb45-16" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
 </section>
@@ -754,14 +787,14 @@ <h2 data-number="1.7" class="anchored" data-anchor-id="sec-blocks"><span class="
 <p>You can create blocks within blocks, with multiple levels of nesting. You can also (if you want to) give a label to a particular block, with the colon character (<code>:</code>). Just write <code>label:</code> before you open the pair of curly braces that delimits your block. When you label a block in Zig, you can use the <code>break</code> keyword to return a value from this block, like as if it was a function’s body. You just write the <code>break</code> keyword, followed by the block label in the format <code>:label</code>, and the expression that defines the value that you want to return.</p>
 <p>Like in the example below, where we are returning the value from the <code>y</code> object from the block <code>add_one</code>, and saving the result inside the <code>x</code> object.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb42"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb42-1"><a href="#cb42-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> y: <span class="dt">i32</span> = <span class="dv">123</span>;</span>
-<span id="cb42-2"><a href="#cb42-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> x = add_one: <span class="op">{</span></span>
-<span id="cb42-3"><a href="#cb42-3" aria-hidden="true" tabindex="-1"></a>    y += <span class="dv">1</span>;</span>
-<span id="cb42-4"><a href="#cb42-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">break</span> :add_one y;</span>
-<span id="cb42-5"><a href="#cb42-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
-<span id="cb42-6"><a href="#cb42-6" aria-hidden="true" tabindex="-1"></a><span class="kw">if</span> (x == <span class="dv">124</span> <span class="kw">and</span> y == <span class="dv">124</span>) <span class="op">{</span></span>
-<span id="cb42-7"><a href="#cb42-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"Hey!"</span>, .<span class="op">{}</span>);</span>
-<span id="cb42-8"><a href="#cb42-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb46"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb46-1"><a href="#cb46-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> y: <span class="dt">i32</span> = <span class="dv">123</span>;</span>
+<span id="cb46-2"><a href="#cb46-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> x = add_one: <span class="op">{</span></span>
+<span id="cb46-3"><a href="#cb46-3" aria-hidden="true" tabindex="-1"></a>    y += <span class="dv">1</span>;</span>
+<span id="cb46-4"><a href="#cb46-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">break</span> :add_one y;</span>
+<span id="cb46-5"><a href="#cb46-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
+<span id="cb46-6"><a href="#cb46-6" aria-hidden="true" tabindex="-1"></a><span class="kw">if</span> (x == <span class="dv">124</span> <span class="kw">and</span> y == <span class="dv">124</span>) <span class="op">{</span></span>
+<span id="cb46-7"><a href="#cb46-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"Hey!"</span>, .<span class="op">{}</span>);</span>
+<span id="cb46-8"><a href="#cb46-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>Hey!</code></pre>
 </div>
@@ -779,37 +812,37 @@ <h2 data-number="1.8" class="anchored" data-anchor-id="sec-zig-strings"><span cl
 <p>On the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes, or, in other words, a slice of <code>u8</code> values (slices were presented at <a href="#sec-arrays" class="quarto-xref"><span>Section 1.6</span></a>). Thus, a string object have a data type of <code>[]u8</code> or <code>[]const u8</code>, depending if the string object is marked as constant with <code>const</code>, or as variable with <code>var</code>.</p>
 <p>Because a string object is essentially a slice, it means that a string object always contains two things: a pointer to an array of bytes (i.e.&nbsp;<code>u8</code> values) that represents the string value; and also, a length value, which specifies the size of the slice, or, how many elements there is in the slice. Is worth to emphasize that the array of bytes in a string object is not null-terminated, like in a string literal value.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb44"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb44-1"><a href="#cb44-1" aria-hidden="true" tabindex="-1"></a><span class="co">// This is a string literal value:</span></span>
-<span id="cb44-2"><a href="#cb44-2" aria-hidden="true" tabindex="-1"></a><span class="st">"A literal value"</span>;</span>
-<span id="cb44-3"><a href="#cb44-3" aria-hidden="true" tabindex="-1"></a><span class="co">// This is a string object:</span></span>
-<span id="cb44-4"><a href="#cb44-4" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> object: []<span class="kw">const</span> <span class="dt">u8</span> = <span class="st">"A string object"</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb48"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb48-1"><a href="#cb48-1" aria-hidden="true" tabindex="-1"></a><span class="co">// This is a string literal value:</span></span>
+<span id="cb48-2"><a href="#cb48-2" aria-hidden="true" tabindex="-1"></a><span class="st">"A literal value"</span>;</span>
+<span id="cb48-3"><a href="#cb48-3" aria-hidden="true" tabindex="-1"></a><span class="co">// This is a string object:</span></span>
+<span id="cb48-4"><a href="#cb48-4" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> object: []<span class="kw">const</span> <span class="dt">u8</span> = <span class="st">"A string object"</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>Zig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every sequence of bytes you’re working with, but is not really Zig’s job to fix the encoding of your strings (you can use <a href="https://www.gnu.org/software/libiconv/"><code>iconv</code></a><a href="#fn16" class="footnote-ref" id="fnref16" role="doc-noteref"><sup>16</sup></a> for that). Today, most of the text in our modern world, especially on the web, should be UTF-8 encoded. So if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.</p>
+<p>Zig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every sequence of bytes you’re working with, but is not really Zig’s job to fix the encoding of your strings (you can use <a href="https://www.gnu.org/software/libiconv/"><code>iconv</code></a><a href="#fn18" class="footnote-ref" id="fnref18" role="doc-noteref"><sup>18</sup></a> for that). Today, most of the text in our modern world, especially on the web, should be UTF-8 encoded. So if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.</p>
 <p>Let’s take for example the word “Hello”. In UTF-8, this sequence of characters (H, e, l, l, o) is represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this sequence is <code>0x48</code>, <code>0x65</code>, <code>0x6C</code>, <code>0x6C</code>, <code>0x6F</code>. So if I take this sequence of hexadecimal values, and ask Zig to print this sequence of bytes as a sequence of characters (i.e.&nbsp;a string), then, the text “Hello” will be printed into the terminal:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb45"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb45-1"><a href="#cb45-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb45-2"><a href="#cb45-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
-<span id="cb45-3"><a href="#cb45-3" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb45-4"><a href="#cb45-4" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb45-5"><a href="#cb45-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> bytes = [_]<span class="dt">u8</span><span class="op">{</span><span class="bn">0x48</span>, <span class="bn">0x65</span>, <span class="bn">0x6C</span>, <span class="bn">0x6C</span>, <span class="bn">0x6F</span><span class="op">}</span>;</span>
-<span id="cb45-6"><a href="#cb45-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"{s}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>bytes<span class="op">}</span>);</span>
-<span id="cb45-7"><a href="#cb45-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb49"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb49-1"><a href="#cb49-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb49-2"><a href="#cb49-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
+<span id="cb49-3"><a href="#cb49-3" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb49-4"><a href="#cb49-4" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb49-5"><a href="#cb49-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> bytes = [_]<span class="dt">u8</span><span class="op">{</span><span class="bn">0x48</span>, <span class="bn">0x65</span>, <span class="bn">0x6C</span>, <span class="bn">0x6C</span>, <span class="bn">0x6F</span><span class="op">}</span>;</span>
+<span id="cb49-6"><a href="#cb49-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"{s}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>bytes<span class="op">}</span>);</span>
+<span id="cb49-7"><a href="#cb49-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>Hello</code></pre>
 </div>
 </div>
-<p>If you want to see the actual bytes that represents a string in Zig, you can use a <code>for</code> loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal value to the terminal. You do that by using a <code>print()</code> statement with the <code>X</code> formatting specifier, like you would normally do with the <a href="https://cplusplus.com/reference/cstdio/printf/"><code>printf()</code> function</a><a href="#fn17" class="footnote-ref" id="fnref17" role="doc-noteref"><sup>17</sup></a> in C.</p>
+<p>If you want to see the actual bytes that represents a string in Zig, you can use a <code>for</code> loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal value to the terminal. You do that by using a <code>print()</code> statement with the <code>X</code> formatting specifier, like you would normally do with the <a href="https://cplusplus.com/reference/cstdio/printf/"><code>printf()</code> function</a><a href="#fn19" class="footnote-ref" id="fnref19" role="doc-noteref"><sup>19</sup></a> in C.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb47"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb47-1"><a href="#cb47-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb47-2"><a href="#cb47-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
-<span id="cb47-3"><a href="#cb47-3" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb47-4"><a href="#cb47-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> string_object = <span class="st">"This is an example"</span>;</span>
-<span id="cb47-5"><a href="#cb47-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"Bytes that represents the string object: "</span>, .<span class="op">{}</span>);</span>
-<span id="cb47-6"><a href="#cb47-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">for</span> (string_object) |byte| <span class="op">{</span></span>
-<span id="cb47-7"><a href="#cb47-7" aria-hidden="true" tabindex="-1"></a>        <span class="kw">try</span> stdout.print(<span class="st">"{X} "</span>, .<span class="op">{</span>byte<span class="op">}</span>);</span>
-<span id="cb47-8"><a href="#cb47-8" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb47-9"><a href="#cb47-9" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{}</span>);</span>
-<span id="cb47-10"><a href="#cb47-10" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb51"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb51-1"><a href="#cb51-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb51-2"><a href="#cb51-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
+<span id="cb51-3"><a href="#cb51-3" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb51-4"><a href="#cb51-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> string_object = <span class="st">"This is an example"</span>;</span>
+<span id="cb51-5"><a href="#cb51-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"Bytes that represents the string object: "</span>, .<span class="op">{}</span>);</span>
+<span id="cb51-6"><a href="#cb51-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">for</span> (string_object) |byte| <span class="op">{</span></span>
+<span id="cb51-7"><a href="#cb51-7" aria-hidden="true" tabindex="-1"></a>        <span class="kw">try</span> stdout.print(<span class="st">"{X} "</span>, .<span class="op">{</span>byte<span class="op">}</span>);</span>
+<span id="cb51-8"><a href="#cb51-8" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb51-9"><a href="#cb51-9" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{}</span>);</span>
+<span id="cb51-10"><a href="#cb51-10" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>Bytes that represents the string object: 54 68 69 
    73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 </code></pre>
@@ -822,28 +855,28 @@ <h3 data-number="1.8.1" class="anchored" data-anchor-id="strings-in-c"><span cla
 <p>To achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless. So getting this kind of safety is not automatic and much harder to do in C. For example, if you want to track the length of your string throughout your program in C, then, you first need to loop through the array of bytes that represents this string, and find the null element (<code>'\0'</code>) position to discover where exactly the array ends, or, in other words, to find how much elements the array of bytes contain.</p>
 <p>To do that, you would need something like this in C. In this example, the C string stored in the object <code>array</code> is 25 bytes long:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb49"><pre class="sourceCode c code-with-copy"><code class="sourceCode c"><span id="cb49-1"><a href="#cb49-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im">&lt;stdio.h&gt;</span></span>
-<span id="cb49-2"><a href="#cb49-2" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> main<span class="op">()</span> <span class="op">{</span></span>
-<span id="cb49-3"><a href="#cb49-3" aria-hidden="true" tabindex="-1"></a>    <span class="dt">char</span><span class="op">*</span> array <span class="op">=</span> <span class="st">"An example of string in C"</span><span class="op">;</span></span>
-<span id="cb49-4"><a href="#cb49-4" aria-hidden="true" tabindex="-1"></a>    <span class="dt">int</span> index <span class="op">=</span> <span class="dv">0</span><span class="op">;</span></span>
-<span id="cb49-5"><a href="#cb49-5" aria-hidden="true" tabindex="-1"></a>    <span class="cf">while</span> <span class="op">(</span><span class="dv">1</span><span class="op">)</span> <span class="op">{</span></span>
-<span id="cb49-6"><a href="#cb49-6" aria-hidden="true" tabindex="-1"></a>        <span class="cf">if</span> <span class="op">(</span>array<span class="op">[</span>index<span class="op">]</span> <span class="op">==</span> <span class="ch">'</span><span class="sc">\0</span><span class="ch">'</span><span class="op">)</span> <span class="op">{</span></span>
-<span id="cb49-7"><a href="#cb49-7" aria-hidden="true" tabindex="-1"></a>            <span class="cf">break</span><span class="op">;</span></span>
-<span id="cb49-8"><a href="#cb49-8" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span></span>
-<span id="cb49-9"><a href="#cb49-9" aria-hidden="true" tabindex="-1"></a>        index<span class="op">++;</span></span>
-<span id="cb49-10"><a href="#cb49-10" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb49-11"><a href="#cb49-11" aria-hidden="true" tabindex="-1"></a>    printf<span class="op">(</span><span class="st">"Number of elements in the array: </span><span class="sc">%d\n</span><span class="st">"</span><span class="op">,</span> index<span class="op">);</span></span>
-<span id="cb49-12"><a href="#cb49-12" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb53"><pre class="sourceCode c code-with-copy"><code class="sourceCode c"><span id="cb53-1"><a href="#cb53-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im">&lt;stdio.h&gt;</span></span>
+<span id="cb53-2"><a href="#cb53-2" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> main<span class="op">()</span> <span class="op">{</span></span>
+<span id="cb53-3"><a href="#cb53-3" aria-hidden="true" tabindex="-1"></a>    <span class="dt">char</span><span class="op">*</span> array <span class="op">=</span> <span class="st">"An example of string in C"</span><span class="op">;</span></span>
+<span id="cb53-4"><a href="#cb53-4" aria-hidden="true" tabindex="-1"></a>    <span class="dt">int</span> index <span class="op">=</span> <span class="dv">0</span><span class="op">;</span></span>
+<span id="cb53-5"><a href="#cb53-5" aria-hidden="true" tabindex="-1"></a>    <span class="cf">while</span> <span class="op">(</span><span class="dv">1</span><span class="op">)</span> <span class="op">{</span></span>
+<span id="cb53-6"><a href="#cb53-6" aria-hidden="true" tabindex="-1"></a>        <span class="cf">if</span> <span class="op">(</span>array<span class="op">[</span>index<span class="op">]</span> <span class="op">==</span> <span class="ch">'</span><span class="sc">\0</span><span class="ch">'</span><span class="op">)</span> <span class="op">{</span></span>
+<span id="cb53-7"><a href="#cb53-7" aria-hidden="true" tabindex="-1"></a>            <span class="cf">break</span><span class="op">;</span></span>
+<span id="cb53-8"><a href="#cb53-8" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span></span>
+<span id="cb53-9"><a href="#cb53-9" aria-hidden="true" tabindex="-1"></a>        index<span class="op">++;</span></span>
+<span id="cb53-10"><a href="#cb53-10" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb53-11"><a href="#cb53-11" aria-hidden="true" tabindex="-1"></a>    printf<span class="op">(</span><span class="st">"Number of elements in the array: </span><span class="sc">%d\n</span><span class="st">"</span><span class="op">,</span> index<span class="op">);</span></span>
+<span id="cb53-12"><a href="#cb53-12" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Number of elements in the array: 25</code></pre>
 <p>You don’t have this kind of work in Zig. Because the length of the string is always present and accessible. In a string object for example, you can easily access the length of the string through the <code>len</code> attribute. As an example, the <code>string_object</code> object below is 43 bytes long:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb51"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb51-1"><a href="#cb51-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb51-2"><a href="#cb51-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
-<span id="cb51-3"><a href="#cb51-3" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb51-4"><a href="#cb51-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> string_object = <span class="st">"This is an example of string literal in Zig"</span>;</span>
-<span id="cb51-5"><a href="#cb51-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>string_object.len<span class="op">}</span>);</span>
-<span id="cb51-6"><a href="#cb51-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb55"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb55-1"><a href="#cb55-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb55-2"><a href="#cb55-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
+<span id="cb55-3"><a href="#cb55-3" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb55-4"><a href="#cb55-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> string_object = <span class="st">"This is an example of string literal in Zig"</span>;</span>
+<span id="cb55-5"><a href="#cb55-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>string_object.len<span class="op">}</span>);</span>
+<span id="cb55-6"><a href="#cb55-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>43</code></pre>
 </div>
@@ -856,23 +889,23 @@ <h3 data-number="1.8.2" class="anchored" data-anchor-id="a-better-look-at-the-ob
 <p>Now, if we create an pointer to the <code>simple_array</code> object, then, we get a constant pointer to an array of 4 elements (<code>*const [4]i32</code>), which is very similar to the type of the string literal value. This demonstrates that a string literal value in Zig is already a pointer to a null-terminated array of bytes.</p>
 <p>Furthermore, if we take a look at the type of the <code>string_obj</code> object, you will see that it is a slice object (hence the <code>[]</code> portion of the type) to a sequence of constant <code>u8</code> values (hence the <code>const u8</code> portion of the type).</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb53"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb53-1"><a href="#cb53-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb53-2"><a href="#cb53-2" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb53-3"><a href="#cb53-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> simple_array = [_]<span class="dt">i32</span><span class="op">{</span><span class="dv">1</span>, <span class="dv">2</span>, <span class="dv">3</span>, <span class="dv">4</span><span class="op">}</span>;</span>
-<span id="cb53-4"><a href="#cb53-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> string_obj: []<span class="kw">const</span> <span class="dt">u8</span> = <span class="st">"A string object"</span>;</span>
-<span id="cb53-5"><a href="#cb53-5" aria-hidden="true" tabindex="-1"></a>    std.debug.print(</span>
-<span id="cb53-6"><a href="#cb53-6" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Type 1: {}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="bu">@TypeOf</span>(simple_array)<span class="op">}</span></span>
-<span id="cb53-7"><a href="#cb53-7" aria-hidden="true" tabindex="-1"></a>    );</span>
-<span id="cb53-8"><a href="#cb53-8" aria-hidden="true" tabindex="-1"></a>    std.debug.print(</span>
-<span id="cb53-9"><a href="#cb53-9" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Type 2: {}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="bu">@TypeOf</span>(<span class="st">"A string literal"</span>)<span class="op">}</span></span>
-<span id="cb53-10"><a href="#cb53-10" aria-hidden="true" tabindex="-1"></a>    );</span>
-<span id="cb53-11"><a href="#cb53-11" aria-hidden="true" tabindex="-1"></a>    std.debug.print(</span>
-<span id="cb53-12"><a href="#cb53-12" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Type 3: {}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="bu">@TypeOf</span>(&amp;simple_array)<span class="op">}</span></span>
-<span id="cb53-13"><a href="#cb53-13" aria-hidden="true" tabindex="-1"></a>    );</span>
-<span id="cb53-14"><a href="#cb53-14" aria-hidden="true" tabindex="-1"></a>    std.debug.print(</span>
-<span id="cb53-15"><a href="#cb53-15" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Type 4: {}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="bu">@TypeOf</span>(string_obj)<span class="op">}</span></span>
-<span id="cb53-16"><a href="#cb53-16" aria-hidden="true" tabindex="-1"></a>    );</span>
-<span id="cb53-17"><a href="#cb53-17" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb57"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb57-1"><a href="#cb57-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb57-2"><a href="#cb57-2" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb57-3"><a href="#cb57-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> simple_array = [_]<span class="dt">i32</span><span class="op">{</span><span class="dv">1</span>, <span class="dv">2</span>, <span class="dv">3</span>, <span class="dv">4</span><span class="op">}</span>;</span>
+<span id="cb57-4"><a href="#cb57-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> string_obj: []<span class="kw">const</span> <span class="dt">u8</span> = <span class="st">"A string object"</span>;</span>
+<span id="cb57-5"><a href="#cb57-5" aria-hidden="true" tabindex="-1"></a>    std.debug.print(</span>
+<span id="cb57-6"><a href="#cb57-6" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Type 1: {}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="bu">@TypeOf</span>(simple_array)<span class="op">}</span></span>
+<span id="cb57-7"><a href="#cb57-7" aria-hidden="true" tabindex="-1"></a>    );</span>
+<span id="cb57-8"><a href="#cb57-8" aria-hidden="true" tabindex="-1"></a>    std.debug.print(</span>
+<span id="cb57-9"><a href="#cb57-9" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Type 2: {}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="bu">@TypeOf</span>(<span class="st">"A string literal"</span>)<span class="op">}</span></span>
+<span id="cb57-10"><a href="#cb57-10" aria-hidden="true" tabindex="-1"></a>    );</span>
+<span id="cb57-11"><a href="#cb57-11" aria-hidden="true" tabindex="-1"></a>    std.debug.print(</span>
+<span id="cb57-12"><a href="#cb57-12" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Type 3: {}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="bu">@TypeOf</span>(&amp;simple_array)<span class="op">}</span></span>
+<span id="cb57-13"><a href="#cb57-13" aria-hidden="true" tabindex="-1"></a>    );</span>
+<span id="cb57-14"><a href="#cb57-14" aria-hidden="true" tabindex="-1"></a>    std.debug.print(</span>
+<span id="cb57-15"><a href="#cb57-15" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Type 4: {}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="bu">@TypeOf</span>(string_obj)<span class="op">}</span></span>
+<span id="cb57-16"><a href="#cb57-16" aria-hidden="true" tabindex="-1"></a>    );</span>
+<span id="cb57-17"><a href="#cb57-17" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Type 1: [4]i32
 Type 2: *const [16:0]u8
@@ -885,17 +918,17 @@ <h3 data-number="1.8.3" class="anchored" data-anchor-id="byte-vs-unicode-points"
 <p>The encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in the string. For example, the character “H” is stored in UTF-8 as the decimal number 72. This means that the number 72 is the unicode point for the character “H”. Each possible character that can appear in a UTF-8 encoded string have its own unicode point.</p>
 <p>For example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point) 570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which is 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why, the unicode point 570 is actually stored inside the computer’s memory as the bytes <code>C8 BA</code>.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb55"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb55-1"><a href="#cb55-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb55-2"><a href="#cb55-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
-<span id="cb55-3"><a href="#cb55-3" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb55-4"><a href="#cb55-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> string_object = <span class="st">"Ⱥ"</span>;</span>
-<span id="cb55-5"><a href="#cb55-5" aria-hidden="true" tabindex="-1"></a>    _ = <span class="kw">try</span> stdout.write(</span>
-<span id="cb55-6"><a href="#cb55-6" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Bytes that represents the string object: "</span></span>
-<span id="cb55-7"><a href="#cb55-7" aria-hidden="true" tabindex="-1"></a>    );</span>
-<span id="cb55-8"><a href="#cb55-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">for</span> (string_object) |char| <span class="op">{</span></span>
-<span id="cb55-9"><a href="#cb55-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">try</span> stdout.print(<span class="st">"{X} "</span>, .<span class="op">{</span>char<span class="op">}</span>);</span>
-<span id="cb55-10"><a href="#cb55-10" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb55-11"><a href="#cb55-11" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb59"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb59-1"><a href="#cb59-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb59-2"><a href="#cb59-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
+<span id="cb59-3"><a href="#cb59-3" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb59-4"><a href="#cb59-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> string_object = <span class="st">"Ⱥ"</span>;</span>
+<span id="cb59-5"><a href="#cb59-5" aria-hidden="true" tabindex="-1"></a>    _ = <span class="kw">try</span> stdout.write(</span>
+<span id="cb59-6"><a href="#cb59-6" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Bytes that represents the string object: "</span></span>
+<span id="cb59-7"><a href="#cb59-7" aria-hidden="true" tabindex="-1"></a>    );</span>
+<span id="cb59-8"><a href="#cb59-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">for</span> (string_object) |char| <span class="op">{</span></span>
+<span id="cb59-9"><a href="#cb59-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">try</span> stdout.print(<span class="st">"{X} "</span>, .<span class="op">{</span>char<span class="op">}</span>);</span>
+<span id="cb59-10"><a href="#cb59-10" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb59-11"><a href="#cb59-11" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>Bytes that represents the string object: C8 BA </code></pre>
 </div>
@@ -907,19 +940,19 @@ <h3 data-number="1.8.3" class="anchored" data-anchor-id="byte-vs-unicode-points"
 <p>If you need to iterate through the characters of a string, instead of its bytes, then, you can use the <code>std.unicode.Utf8View</code> struct to create an iterator that iterates through the unicode points of your string.</p>
 <p>In the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in this string is represented by three bytes. But the for loop iterates four times, one iteration for each character/unicode point in this string:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb57"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb57-1"><a href="#cb57-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb57-2"><a href="#cb57-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
-<span id="cb57-3"><a href="#cb57-3" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb57-4"><a href="#cb57-4" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb57-5"><a href="#cb57-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> utf8 = <span class="kw">try</span> std.unicode.Utf8View.init(<span class="st">"アメリカ"</span>);</span>
-<span id="cb57-6"><a href="#cb57-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> iterator = utf8.iterator();</span>
-<span id="cb57-7"><a href="#cb57-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">while</span> (iterator.nextCodepointSlice()) |codepoint| <span class="op">{</span></span>
-<span id="cb57-8"><a href="#cb57-8" aria-hidden="true" tabindex="-1"></a>        <span class="kw">try</span> stdout.print(</span>
-<span id="cb57-9"><a href="#cb57-9" aria-hidden="true" tabindex="-1"></a>            <span class="st">"got codepoint {}</span><span class="sc">\n</span><span class="st">"</span>,</span>
-<span id="cb57-10"><a href="#cb57-10" aria-hidden="true" tabindex="-1"></a>            .<span class="op">{</span>std.fmt.fmtSliceHexUpper(codepoint)<span class="op">}</span>,</span>
-<span id="cb57-11"><a href="#cb57-11" aria-hidden="true" tabindex="-1"></a>        );</span>
-<span id="cb57-12"><a href="#cb57-12" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb57-13"><a href="#cb57-13" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb61"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb61-1"><a href="#cb61-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb61-2"><a href="#cb61-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
+<span id="cb61-3"><a href="#cb61-3" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb61-4"><a href="#cb61-4" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb61-5"><a href="#cb61-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> utf8 = <span class="kw">try</span> std.unicode.Utf8View.init(<span class="st">"アメリカ"</span>);</span>
+<span id="cb61-6"><a href="#cb61-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> iterator = utf8.iterator();</span>
+<span id="cb61-7"><a href="#cb61-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">while</span> (iterator.nextCodepointSlice()) |codepoint| <span class="op">{</span></span>
+<span id="cb61-8"><a href="#cb61-8" aria-hidden="true" tabindex="-1"></a>        <span class="kw">try</span> stdout.print(</span>
+<span id="cb61-9"><a href="#cb61-9" aria-hidden="true" tabindex="-1"></a>            <span class="st">"got codepoint {}</span><span class="sc">\n</span><span class="st">"</span>,</span>
+<span id="cb61-10"><a href="#cb61-10" aria-hidden="true" tabindex="-1"></a>            .<span class="op">{</span>std.fmt.fmtSliceHexUpper(codepoint)<span class="op">}</span>,</span>
+<span id="cb61-11"><a href="#cb61-11" aria-hidden="true" tabindex="-1"></a>        );</span>
+<span id="cb61-12"><a href="#cb61-12" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb61-13"><a href="#cb61-13" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>got codepoint E382A2
 got codepoint E383A1
@@ -943,10 +976,10 @@ <h3 data-number="1.8.4" class="anchored" data-anchor-id="sec-strings-useful-funs
 <p>Notice that all of these functions come from the <code>mem</code> module of the Zig Standard Library. This module contains multiple functions and methods that are useful to work with memory and sequences of bytes in general.</p>
 <p>The <code>eql()</code> function is used to check if two arrays of data are equal or not. Since strings are just arbitrary arrays of bytes, we can use this function to compare two strings together. This function returns a boolean value indicating if the two strings are equal or not. The first argument of this function is the data type of the elements of the arrays that are being compared.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb59"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb59-1"><a href="#cb59-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> name: []<span class="kw">const</span> <span class="dt">u8</span> = <span class="st">"Pedro"</span>;</span>
-<span id="cb59-2"><a href="#cb59-2" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(</span>
-<span id="cb59-3"><a href="#cb59-3" aria-hidden="true" tabindex="-1"></a>    <span class="st">"{any}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>std.mem.eql(<span class="dt">u8</span>, name, <span class="st">"Pedro"</span>)<span class="op">}</span></span>
-<span id="cb59-4"><a href="#cb59-4" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb63"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb63-1"><a href="#cb63-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> name: []<span class="kw">const</span> <span class="dt">u8</span> = <span class="st">"Pedro"</span>;</span>
+<span id="cb63-2"><a href="#cb63-2" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(</span>
+<span id="cb63-3"><a href="#cb63-3" aria-hidden="true" tabindex="-1"></a>    <span class="st">"{any}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>std.mem.eql(<span class="dt">u8</span>, name, <span class="st">"Pedro"</span>)<span class="op">}</span></span>
+<span id="cb63-4"><a href="#cb63-4" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>true</code></pre>
 </div>
@@ -954,34 +987,34 @@ <h3 data-number="1.8.4" class="anchored" data-anchor-id="sec-strings-useful-funs
 <p>The <code>splitScalar()</code> and <code>splitSequence()</code> functions are useful to split a string into multiple fragments, like the <code>split()</code> method from Python strings. The difference between these two methods is that the <code>splitScalar()</code> uses a single character as the separator to split the string, while <code>splitSequence()</code> uses a sequence of characters (a.k.a. a substring) as the separator. There is a practical example of these functions later in the book.</p>
 <p>The <code>startsWith()</code> and <code>endsWith()</code> functions are pretty straightforward. They return a boolean value indicating if the string (or, more precisely, if the array of data) begins (<code>startsWith</code>) or ends (<code>endsWith</code>) with the sequence provided.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb61"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb61-1"><a href="#cb61-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> name: []<span class="kw">const</span> <span class="dt">u8</span> = <span class="st">"Pedro"</span>;</span>
-<span id="cb61-2"><a href="#cb61-2" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(</span>
-<span id="cb61-3"><a href="#cb61-3" aria-hidden="true" tabindex="-1"></a>    <span class="st">"{any}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>std.mem.startsWith(<span class="dt">u8</span>, name, <span class="st">"Pe"</span>)<span class="op">}</span></span>
-<span id="cb61-4"><a href="#cb61-4" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb65"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb65-1"><a href="#cb65-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> name: []<span class="kw">const</span> <span class="dt">u8</span> = <span class="st">"Pedro"</span>;</span>
+<span id="cb65-2"><a href="#cb65-2" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(</span>
+<span id="cb65-3"><a href="#cb65-3" aria-hidden="true" tabindex="-1"></a>    <span class="st">"{any}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>std.mem.startsWith(<span class="dt">u8</span>, name, <span class="st">"Pe"</span>)<span class="op">}</span></span>
+<span id="cb65-4"><a href="#cb65-4" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>true</code></pre>
 </div>
 </div>
 <p>The <code>concat()</code> function, as the name suggests, concatenate two or more strings together. Because the process of concatenating the strings involves allocating enough space to accomodate all the strings together, this <code>concat()</code> function receives an allocator object as input.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb63"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb63-1"><a href="#cb63-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> str1 = <span class="st">"Hello"</span>;</span>
-<span id="cb63-2"><a href="#cb63-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> str2 = <span class="st">" you!"</span>;</span>
-<span id="cb63-3"><a href="#cb63-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> str3 = <span class="kw">try</span> std.mem.concat(</span>
-<span id="cb63-4"><a href="#cb63-4" aria-hidden="true" tabindex="-1"></a>    allocator, <span class="dt">u8</span>, &amp;[_][]<span class="kw">const</span> <span class="dt">u8</span><span class="op">{</span> str1, str2 <span class="op">}</span></span>
-<span id="cb63-5"><a href="#cb63-5" aria-hidden="true" tabindex="-1"></a>);</span>
-<span id="cb63-6"><a href="#cb63-6" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{s}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>str3<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb67"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb67-1"><a href="#cb67-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> str1 = <span class="st">"Hello"</span>;</span>
+<span id="cb67-2"><a href="#cb67-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> str2 = <span class="st">" you!"</span>;</span>
+<span id="cb67-3"><a href="#cb67-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> str3 = <span class="kw">try</span> std.mem.concat(</span>
+<span id="cb67-4"><a href="#cb67-4" aria-hidden="true" tabindex="-1"></a>    allocator, <span class="dt">u8</span>, &amp;[_][]<span class="kw">const</span> <span class="dt">u8</span><span class="op">{</span> str1, str2 <span class="op">}</span></span>
+<span id="cb67-5"><a href="#cb67-5" aria-hidden="true" tabindex="-1"></a>);</span>
+<span id="cb67-6"><a href="#cb67-6" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{s}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>str3<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Hello you!</code></pre>
 <p>As you can imagine, the <code>replace()</code> function is used to replace substrings in a string by another substring. This function works very similarly to the <code>replace()</code> method from Python strings. Therefore, you provide a substring to search, and every time that the <code>replace()</code> function finds this substring within the input string, it replaces this substring with the “replacement substring” that you provided as input.</p>
 <p>In the example below, we are taking the input string “Hello”, and replacing all occurrences of the substring “el” inside this input string with “34”, and saving the results inside the <code>buffer</code> object. As result, the <code>replace()</code> function returns an <code>usize</code> value that indicates how many replacements were performed.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb65"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb65-1"><a href="#cb65-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> str1 = <span class="st">"Hello"</span>;</span>
-<span id="cb65-2"><a href="#cb65-2" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> buffer: [<span class="dv">5</span>]<span class="dt">u8</span> = <span class="cn">undefined</span>;</span>
-<span id="cb65-3"><a href="#cb65-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> nrep = std.mem.replace(</span>
-<span id="cb65-4"><a href="#cb65-4" aria-hidden="true" tabindex="-1"></a>    <span class="dt">u8</span>, str1, <span class="st">"el"</span>, <span class="st">"34"</span>, buffer[<span class="dv">0</span>..]</span>
-<span id="cb65-5"><a href="#cb65-5" aria-hidden="true" tabindex="-1"></a>);</span>
-<span id="cb65-6"><a href="#cb65-6" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"New string: {s}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>buffer<span class="op">}</span>);</span>
-<span id="cb65-7"><a href="#cb65-7" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"N of replacements: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>nrep<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb69"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb69-1"><a href="#cb69-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> str1 = <span class="st">"Hello"</span>;</span>
+<span id="cb69-2"><a href="#cb69-2" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> buffer: [<span class="dv">5</span>]<span class="dt">u8</span> = <span class="cn">undefined</span>;</span>
+<span id="cb69-3"><a href="#cb69-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> nrep = std.mem.replace(</span>
+<span id="cb69-4"><a href="#cb69-4" aria-hidden="true" tabindex="-1"></a>    <span class="dt">u8</span>, str1, <span class="st">"el"</span>, <span class="st">"34"</span>, buffer[<span class="dv">0</span>..]</span>
+<span id="cb69-5"><a href="#cb69-5" aria-hidden="true" tabindex="-1"></a>);</span>
+<span id="cb69-6"><a href="#cb69-6" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"New string: {s}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>buffer<span class="op">}</span>);</span>
+<span id="cb69-7"><a href="#cb69-7" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"N of replacements: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>nrep<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>New string: H34lo
 N of replacements: 1</code></pre>
@@ -991,9 +1024,9 @@ <h3 data-number="1.8.4" class="anchored" data-anchor-id="sec-strings-useful-funs
 <h2 data-number="1.9" class="anchored" data-anchor-id="safety-in-zig"><span class="header-section-number">1.9</span> Safety in Zig</h2>
 <p>A general trend in modern low-level programming languages is safety. As our modern world becomes more interconnected with technology and computers, the data produced by all of this technology becomes one of the most important (and also, one of the most dangerous) assets that we have.</p>
 <p>This is probably the main reason why modern low-level programming languages have been giving great attention to safety, especially memory safety, because memory corruption is still the main target for hackers to exploit. The reality is that we don’t have an easy solution for this problem. For now, we only have techniques and strategies that mitigates these problems.</p>
-<p>As Richard Feldman explains on his <a href="https://www.youtube.com/watch?v=jIZpKpLCOiU&amp;ab_channel=GOTOConferences">most recent GOTO conference talk</a><a href="#fn18" class="footnote-ref" id="fnref18" role="doc-noteref"><sup>18</sup></a> , we haven’t figured it out yet a way to achieve <strong>true safety in technology</strong>. In other words, we haven’t found a way to build software that won’t be exploited with 100% certainty. We can greatly reduce the risks of our software being exploited, by ensuring memory safety for example. But this is not enough to achieve “true safety” territory.</p>
+<p>As Richard Feldman explains on his <a href="https://www.youtube.com/watch?v=jIZpKpLCOiU&amp;ab_channel=GOTOConferences">most recent GOTO conference talk</a><a href="#fn20" class="footnote-ref" id="fnref20" role="doc-noteref"><sup>20</sup></a> , we haven’t figured it out yet a way to achieve <strong>true safety in technology</strong>. In other words, we haven’t found a way to build software that won’t be exploited with 100% certainty. We can greatly reduce the risks of our software being exploited, by ensuring memory safety for example. But this is not enough to achieve “true safety” territory.</p>
 <p>Because even if you write your program in a “safe language”, hackers can still exploit failures in the operational system where your program is running (e.g.&nbsp;maybe the system where your code is running has a “backdoor exploit” that can still affect your code in unexpected ways), or also, they can exploit the features from the architecture of your computer. A recently found exploit that involves memory invalidation through a feature of “memory tags” present in ARM chips is an example of that <span class="citation" data-cites="exploit1">(<a href="../references.html#ref-exploit1" role="doc-biblioref">Kim et al. 2024</a>)</span>.</p>
-<p>The question is: what have Zig and other languages been doing to mitigate this problem? If we take Rust as an example, Rust is, for the most part<a href="#fn19" class="footnote-ref" id="fnref19" role="doc-noteref"><sup>19</sup></a>, a memory safe language by enforcing specific rules to the developer. In other words, the key feature of Rust, the <em>borrow checker</em>, forces you to follow a specific logic when you are writing your Rust code, and the Rust compiler will always complain everytime you try to go out of this pattern.</p>
+<p>The question is: what have Zig and other languages been doing to mitigate this problem? If we take Rust as an example, Rust is, for the most part<a href="#fn21" class="footnote-ref" id="fnref21" role="doc-noteref"><sup>21</sup></a>, a memory safe language by enforcing specific rules to the developer. In other words, the key feature of Rust, the <em>borrow checker</em>, forces you to follow a specific logic when you are writing your Rust code, and the Rust compiler will always complain everytime you try to go out of this pattern.</p>
 <p>In contrast, the Zig language is not a memory safe language by default. There are some memory safety features that you get for free in Zig, especially in arrays and pointer objects. But there are other tools offered by the language, that are not used by default. In other words, the <code>zig</code> compiler does not obligates you to use such tools.</p>
 <p>The tools listed below are related to memory safety. That is, they help you to achieve memory safety in your Zig code:</p>
 <ul>
@@ -1047,23 +1080,25 @@ <h2 data-number="1.10" class="anchored" data-anchor-id="other-parts-of-zig"><spa
 <ol>
 <li id="fn1"><p><a href="https://ziglang.org/learn/overview/#zig-build-system" class="uri">https://ziglang.org/learn/overview/#zig-build-system</a>.<a href="#fnref1" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
 <li id="fn2"><p><a href="https://en.wikipedia.org/wiki/List_of_C-family_programming_languages" class="uri">https://en.wikipedia.org/wiki/List_of_C-family_programming_languages</a><a href="#fnref2" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn3"><p><a href="https://github.com/ziglang/zig/tree/master/lib/std" class="uri">https://github.com/ziglang/zig/tree/master/lib/std</a><a href="#fnref3" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn4"><p><a href="https://github.com/oven-sh/bun" class="uri">https://github.com/oven-sh/bun</a>.<a href="#fnref4" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn5"><p><a href="https://github.com/hexops/mach" class="uri">https://github.com/hexops/mach</a><a href="#fnref5" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn6"><p><a href="https://github.com/cgbur/llama2.zig/tree/main" class="uri">https://github.com/cgbur/llama2.zig/tree/main</a><a href="#fnref6" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn7"><p><a href="https://github.com/tigerbeetle/tigerbeetle" class="uri">https://github.com/tigerbeetle/tigerbeetle</a><a href="#fnref7" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn8"><p><a href="https://github.com/Hejsil/zig-clap" class="uri">https://github.com/Hejsil/zig-clap</a><a href="#fnref8" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn9"><p><a href="https://github.com/capy-ui/capy" class="uri">https://github.com/capy-ui/capy</a><a href="#fnref9" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn10"><p><a href="https://github.com/zigtools/zls" class="uri">https://github.com/zigtools/zls</a><a href="#fnref10" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn11"><p><a href="https://github.com/mitchellh/libxev" class="uri">https://github.com/mitchellh/libxev</a><a href="#fnref11" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn12"><p><a href="https://ziglings.org" class="uri">https://ziglings.org</a>.<a href="#fnref12" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn13"><p><a href="https://www.youtube.com/watch?v=OPuztQfM3Fg&amp;t=2524s&amp;ab_channel=TheVimeagen" class="uri">https://www.youtube.com/watch?v=OPuztQfM3Fg&amp;t=2524s&amp;ab_channel=TheVimeagen</a>.<a href="#fnref13" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn14"><p><a href="https://adventofcode.com/" class="uri">https://adventofcode.com/</a><a href="#fnref14" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn15"><p><a href="https://ziglang.org/documentation/master/#Primitive-Types" class="uri">https://ziglang.org/documentation/master/#Primitive-Types</a>.<a href="#fnref15" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn16"><p><a href="https://www.gnu.org/software/libiconv/" class="uri">https://www.gnu.org/software/libiconv/</a><a href="#fnref16" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn17"><p><a href="https://cplusplus.com/reference/cstdio/printf/" class="uri">https://cplusplus.com/reference/cstdio/printf/</a><a href="#fnref17" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn18"><p><a href="https://www.youtube.com/watch?v=jIZpKpLCOiU&amp;ab_channel=GOTOConferences" class="uri">https://www.youtube.com/watch?v=jIZpKpLCOiU&amp;ab_channel=GOTOConferences</a><a href="#fnref18" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn19"><p>Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (<em>foreign function interface</em>), which disables the borrow-checker features through the <code>unsafe</code> keyword.<a href="#fnref19" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn3"><p><a href="https://github.com/ziglang/zig/issues/17186" class="uri">https://github.com/ziglang/zig/issues/17186</a><a href="#fnref3" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn4"><p><a href="https://github.com/ziglang/zig/issues/19864" class="uri">https://github.com/ziglang/zig/issues/19864</a><a href="#fnref4" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn5"><p><a href="https://github.com/ziglang/zig/tree/master/lib/std" class="uri">https://github.com/ziglang/zig/tree/master/lib/std</a><a href="#fnref5" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn6"><p><a href="https://github.com/oven-sh/bun" class="uri">https://github.com/oven-sh/bun</a>.<a href="#fnref6" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn7"><p><a href="https://github.com/hexops/mach" class="uri">https://github.com/hexops/mach</a><a href="#fnref7" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn8"><p><a href="https://github.com/cgbur/llama2.zig/tree/main" class="uri">https://github.com/cgbur/llama2.zig/tree/main</a><a href="#fnref8" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn9"><p><a href="https://github.com/tigerbeetle/tigerbeetle" class="uri">https://github.com/tigerbeetle/tigerbeetle</a><a href="#fnref9" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn10"><p><a href="https://github.com/Hejsil/zig-clap" class="uri">https://github.com/Hejsil/zig-clap</a><a href="#fnref10" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn11"><p><a href="https://github.com/capy-ui/capy" class="uri">https://github.com/capy-ui/capy</a><a href="#fnref11" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn12"><p><a href="https://github.com/zigtools/zls" class="uri">https://github.com/zigtools/zls</a><a href="#fnref12" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn13"><p><a href="https://github.com/mitchellh/libxev" class="uri">https://github.com/mitchellh/libxev</a><a href="#fnref13" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn14"><p><a href="https://ziglings.org" class="uri">https://ziglings.org</a>.<a href="#fnref14" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn15"><p><a href="https://www.youtube.com/watch?v=OPuztQfM3Fg&amp;t=2524s&amp;ab_channel=TheVimeagen" class="uri">https://www.youtube.com/watch?v=OPuztQfM3Fg&amp;t=2524s&amp;ab_channel=TheVimeagen</a>.<a href="#fnref15" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn16"><p><a href="https://adventofcode.com/" class="uri">https://adventofcode.com/</a><a href="#fnref16" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn17"><p><a href="https://ziglang.org/documentation/master/#Primitive-Types" class="uri">https://ziglang.org/documentation/master/#Primitive-Types</a>.<a href="#fnref17" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn18"><p><a href="https://www.gnu.org/software/libiconv/" class="uri">https://www.gnu.org/software/libiconv/</a><a href="#fnref18" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn19"><p><a href="https://cplusplus.com/reference/cstdio/printf/" class="uri">https://cplusplus.com/reference/cstdio/printf/</a><a href="#fnref19" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn20"><p><a href="https://www.youtube.com/watch?v=jIZpKpLCOiU&amp;ab_channel=GOTOConferences" class="uri">https://www.youtube.com/watch?v=jIZpKpLCOiU&amp;ab_channel=GOTOConferences</a><a href="#fnref20" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn21"><p>Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (<em>foreign function interface</em>), which disables the borrow-checker features through the <code>unsafe</code> keyword.<a href="#fnref21" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
 </ol>
 </section>
 
diff --git a/docs/index.html b/docs/index.html
index cdf70e0c..6725b3d8 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -7,7 +7,7 @@
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 <meta name="author" content="Pedro Duarte Faria">
-<meta name="dcterms.date" content="2024-11-17">
+<meta name="dcterms.date" content="2024-11-24">
 
 <title>Introduction to Zig</title>
 <style>
@@ -287,7 +287,7 @@ <h1 class="title">Introduction to Zig</h1>
     <div>
     <div class="quarto-title-meta-heading">Published</div>
     <div class="quarto-title-meta-contents">
-      <p class="date">November 17, 2024</p>
+      <p class="date">November 24, 2024</p>
     </div>
   </div>
   
diff --git a/docs/search.json b/docs/search.json
index e59bd46f..4846f6f9 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -124,7 +124,7 @@
     "href": "Chapters/01-zig-weird.html#hello-world-in-zig",
     "title": "1  Introducing Zig",
     "section": "1.2 Hello world in Zig",
-    "text": "1.2 Hello world in Zig\nWe begin our journey in Zig by creating a small “Hello World” program. To start a new Zig project in your computer, you simply call the init command from the zig compiler. Just create a new directory in your computer, then, init a new Zig project inside this directory, like this:\nmkdir hello_world\ncd hello_world\nzig init\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n\n1.2.1 Understanding the project files\nAfter you run the init command from the zig compiler, some new files are created inside of your current directory. First, a “source” (src) directory is created, containing two files, main.zig and root.zig. Each .zig file is a separate Zig module, which is simply a text file that contains some Zig code.\nBy convention, the main.zig module is where your main function lives. Thus, if you are building an executable program in Zig, you need to declare a main() function, which represents the entrypoint of your program, i.e. it is where the execution of your program begins.\nHowever, if you are building a library (instead of an executable program), then, the normal procedure is to delete this main.zig file and start with the root.zig module. By convention, the root.zig module is the root source file of your library.\ntree .\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\nThe ìnit command also creates two additional files in our working directory: build.zig and build.zig.zon. The first file (build.zig) represents a build script written in Zig. This script is executed when you call the build command from the zig compiler. In other words, this file contain Zig code that executes the necessary steps to build the entire project.\nLow-level languages normally use a compiler to build your source code into binary executables or binary libraries. Nevertheless, this process of compiling your source code and building binary executables or binary libraries from it, became a real challenge in the programming world, once the projects became bigger and bigger. As a result, programmers created “build systems”, which are a second set of tools designed to make this process of compiling and building complex projects, easier.\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja, which are used to build complex C and C++ projects. With these systems, you can write scripts, which are called “build scripts”. They simply are scripts that describes the necessary steps to compile/build your project.\nHowever, these are separate tools, that do not belong to C/C++ compilers, like gcc or clang. As a result, in C/C++ projects, you have not only to install and manage your C/C++ compilers, but you also have to install and manage these build systems separately.\nIn Zig, we don’t need to use a separate set of tools to build our projects, because a build system is embedded inside the language itself. Therefore, Zig contains a native build system in it, and we can use this build system to write small scripts in Zig, which describes the necessary steps to build/compile our Zig project1. So, everything you need to build a complex Zig project is the zig compiler, and nothing more.\nThe second generated file (build.zig.zon) is the Zig package manager configuration file, where you can list and manage the dependencies of your project. Yes, Zig has a package manager (like pip in Python, cargo in Rust, or npm in Javascript) called Zon, and this build.zig.zon file is similar to the package.json file in Javascript projects, or, the Pipfile file in Python projects, or the Cargo.toml file in Rust projects.\n\n\n1.2.2 The file root.zig\nLet’s take a look into the root.zig file. You might have noticed that every line of code with an expression ends with a semicolon (;). This follows the syntax of a C-family programming language2.\nAlso, notice the @import() call at the first line. We use this built-in function to import functionality from other Zig modules into our current module. This @import() function works similarly to the #include pre-processor in C or C++, or, to the import statement in Python or Javascript code. In this example, we are importing the std module, which gives you access to the Zig Standard Library.\nIn this root.zig file, we can also see how assignments (i.e. creating new objects) are made in Zig. You can create a new object in Zig by using the following syntax (const|var) name = value;. In the example below, we are creating two constant objects (std and testing). At Section 1.4 we talk more about objects in general.\n\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n\nFunctions in Zig are declared using the fn keyword. In this root.zig module, we are declaring a function called add(), which has two arguments named a and b. The function returns an integer of the type i32 as result.\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit the type of an object in your code, if this type can be inferred by the zig compiler (we talk more about that at Section 2.4). But there are other situations where you do need to be explicit. For example, you do have to explicitly specify the type of each function argument, and also, the return type of every function that you create in Zig.\nWe specify the type of an object or a function argument in Zig by using a colon character (:) followed by the type after the name of this object/function argument. With the expressions a: i32 and b: i32, we know that both a and b arguments have type i32, which is a signed 32 bit integer. In this part, the syntax in Zig is identical to the syntax in Rust, which also specifies types by using the colon character.\nLastly, we have the return type of the function at the end of the line, before we open the curly braces to start writing the function’s body. In the example above, this type is also a signed 32 bit integer (i32) value.\nNotice that we also have an export keyword before the function declaration. This keyword is similar to the extern keyword in C. It exposes the function to make it available in the library API. Therefore, if you are writing a library for other people to use, you have to expose the functions you write in the public API of this library by using this export keyword. If we removed the export keyword from the add() function declaration, then, this function would be no longer exposed in the library object built by the zig compiler.\n\n\n1.2.3 The main.zig file\nNow that we have learned a lot about Zig’s syntax from the root.zig file, let’s take a look at the main.zig file. A lot of the elements we saw in root.zig are also present in main.zig. But there are some other elements that we haven’t seen yet, so let’s dive in.\nFirst, look at the return type of the main() function in this file. We can see a small change. The return type of the function (void) is accompanied by an exclamation mark (!). This exclamation mark tells us that this main() function might return an error.\nIn this example, the main() function can either return void or return an error. This is an interesting feature of Zig. If you write a function and something inside of the body of this function might return an error then you are forced to:\n\neither add the exclamation mark to the return type of the function and make it clear that this function might return an error\nexplicitly handle this error inside the function\n\nIn most programming languages, we normally handle (or deal with) an error through a try catch pattern. Zig does have both try and catch keywords. But they work a little differently than what you’re probably used to in other languages.\nIf we look at the main() function below, you can see that we do have a try keyword on the 5th line. But we do not have a catch keyword in this code. In Zig, we use the try keyword to execute an expression that might return an error, which, in this example, is the stdout.print() expression.\nIn essence, the try keyword executes the expression stdout.print(). If this expression returns a valid value, then, the try keyword does nothing. It only passes the value forward. But if the expression does return an error, then, the try keyword just unwrap the error value, and return this error from the function and also prints the current stack trace to stderr.\nThis might sound weird to you if you come from a high-level language. Because in high-level languages, such as Python, if an error occurs somewhere, this error is automatically returned and the execution of your program will automatically stop even if you don’t want to stop the execution. You are obligated to face the error.\n\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n\nAnother thing that you might have noticed in this code example, is that the main() function is marked with the pub keyword. It marks the main() function as a public function from this module.\nEvery function in your Zig module is by default private to this Zig module and can only be called from within the module. Unless, you explicitly mark this function as a public function with the pub keyword. This means that the pub keyword in Zig does essentially the opposite of what the static keyword do in C/C++.\nBy making a function “public” you allow other Zig modules to access and call it. A calling Zig module imports the module with the @import() built-in. That makes all public functions from the imported module visible.\n\n\n1.2.4 Compiling your source code\nYou can compile your Zig modules into a binary executable by running the build-exe command from the zig compiler. You simply list all the Zig modules that you want to build after the build-exe command, separated by spaces. In the example below, we are compiling the module main.zig.\nzig build-exe src/main.zig\nSince we are building an executable, the zig compiler will look for a main() function declared in any of the files that you list after the build-exe command. If the compiler does not find a main() function declared somewhere, a compilation error will be raised, warning about this mistake.\nThe zig compiler also offers a build-lib and build-obj commands, which work the exact same way as the build-exe command. The only difference is that, they compile your Zig modules into a portale C ABI library, or, into object files, respectively.\nIn the case of the build-exe command, a binary executable file is created by the zig compiler in the root directory of your project. If we take a look now at the contents of our current directory, with a simple ls command, we can see the binary file called main that was created by the compiler.\nls\nbuild.zig  build.zig.zon  main  src\nIf I execute this binary executable, I get the “Hello World” message in the terminal , as we expected.\n./main\nHello, world!\n\n\n1.2.5 Compile and execute at the same time\nOn the previous section, I presented the zig build-exe command, which compiles Zig modules into an executable file. However, this means that, in order to execute the executable file, we have to run two different commands. First, the zig build-exe command, and then, we call the executable file created by the compiler.\nBut what if we wanted to perform these two steps, all at once, in a single command? We can do that by using the zig run command.\nzig run src/main.zig\nHello, world!\n\n\n1.2.6 Compiling the entire project\nJust as I described at Section 1.2.1, as our project grows in size and complexity, we usually prefer to organize the compilation and build process of the project into a build script, using some sort of “build system”.\nIn other words, as our project grows in size and complexity, the build-exe, build-lib and build-obj commands become harder to use directly. Because then, we start to list multiple and multiple modules at the same time. We also start to add built-in compilation flags to customize the build process for our needs, etc. It becomes a lot of work to write the necessary commands by hand.\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, Makefile or configure scripts to organize this process. However, in Zig, we have a native build system in the language itself. So, we can write build scripts in Zig to compile and build Zig projects. Then, all we need to do, is to call the zig build command to build our project.\nSo, when you execute the zig build command, the zig compiler will search for a Zig module named build.zig inside your current directory, which should be your build script, containing the necessary code to compile and build your project. If the compiler does find this build.zig file in your directory, then, the compiler will essentially execute a zig run command over this build.zig file, to compile and execute this build script, which in turn, will compile and build your entire project.\nzig build\nAfter you execute this “build project” command, a zig-out directory is created in the root of your project directory, where you can find the binary executables and libraries created from your Zig modules accordingly to the build commands that you specified at build.zig. We will talk more about the build system in Zig latter in this book.\nIn the example below, I’m executing the binary executable named hello_world that was generated by the compiler after the zig build command.\n./zig-out/bin/hello_world\nHello, world!",
+    "text": "1.2 Hello world in Zig\nWe begin our journey in Zig by creating a small “Hello World” program. To start a new Zig project in your computer, you simply call the init command from the zig compiler. Just create a new directory in your computer, then, init a new Zig project inside this directory, like this:\nmkdir hello_world\ncd hello_world\nzig init\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n\n1.2.1 Understanding the project files\nAfter you run the init command from the zig compiler, some new files are created inside of your current directory. First, a “source” (src) directory is created, containing two files, main.zig and root.zig. Each .zig file is a separate Zig module, which is simply a text file that contains some Zig code.\nBy convention, the main.zig module is where your main function lives. Thus, if you are building an executable program in Zig, you need to declare a main() function, which represents the entrypoint of your program, i.e. it is where the execution of your program begins.\nHowever, if you are building a library (instead of an executable program), then, the normal procedure is to delete this main.zig file and start with the root.zig module. By convention, the root.zig module is the root source file of your library.\ntree .\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\nThe ìnit command also creates two additional files in our working directory: build.zig and build.zig.zon. The first file (build.zig) represents a build script written in Zig. This script is executed when you call the build command from the zig compiler. In other words, this file contain Zig code that executes the necessary steps to build the entire project.\nLow-level languages normally use a compiler to build your source code into binary executables or binary libraries. Nevertheless, this process of compiling your source code and building binary executables or binary libraries from it, became a real challenge in the programming world, once the projects became bigger and bigger. As a result, programmers created “build systems”, which are a second set of tools designed to make this process of compiling and building complex projects, easier.\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja, which are used to build complex C and C++ projects. With these systems, you can write scripts, which are called “build scripts”. They simply are scripts that describes the necessary steps to compile/build your project.\nHowever, these are separate tools, that do not belong to C/C++ compilers, like gcc or clang. As a result, in C/C++ projects, you have not only to install and manage your C/C++ compilers, but you also have to install and manage these build systems separately.\nIn Zig, we don’t need to use a separate set of tools to build our projects, because a build system is embedded inside the language itself. Therefore, Zig contains a native build system in it, and we can use this build system to write small scripts in Zig, which describes the necessary steps to build/compile our Zig project1. So, everything you need to build a complex Zig project is the zig compiler, and nothing more.\nThe second generated file (build.zig.zon) is the Zig package manager configuration file, where you can list and manage the dependencies of your project. Yes, Zig has a package manager (like pip in Python, cargo in Rust, or npm in Javascript) called Zon, and this build.zig.zon file is similar to the package.json file in Javascript projects, or, the Pipfile file in Python projects, or the Cargo.toml file in Rust projects.\n\n\n1.2.2 The file root.zig\nLet’s take a look into the root.zig file. You might have noticed that every line of code with an expression ends with a semicolon (;). This follows the syntax of a C-family programming language2.\nAlso, notice the @import() call at the first line. We use this built-in function to import functionality from other Zig modules into our current module. This @import() function works similarly to the #include pre-processor in C or C++, or, to the import statement in Python or Javascript code. In this example, we are importing the std module, which gives you access to the Zig Standard Library.\nIn this root.zig file, we can also see how assignments (i.e. creating new objects) are made in Zig. You can create a new object in Zig by using the following syntax (const|var) name = value;. In the example below, we are creating two constant objects (std and testing). At Section 1.4 we talk more about objects in general.\n\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n\nFunctions in Zig are declared using the fn keyword. In this root.zig module, we are declaring a function called add(), which has two arguments named a and b. The function returns an integer of the type i32 as result.\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit the type of an object in your code, if this type can be inferred by the zig compiler (we talk more about that at Section 2.4). But there are other situations where you do need to be explicit. For example, you do have to explicitly specify the type of each function argument, and also, the return type of every function that you create in Zig.\nWe specify the type of an object or a function argument in Zig by using a colon character (:) followed by the type after the name of this object/function argument. With the expressions a: i32 and b: i32, we know that both a and b arguments have type i32, which is a signed 32 bit integer. In this part, the syntax in Zig is identical to the syntax in Rust, which also specifies types by using the colon character.\nLastly, we have the return type of the function at the end of the line, before we open the curly braces to start writing the function’s body. In the example above, this type is also a signed 32 bit integer (i32) value.\nNotice that we also have an export keyword before the function declaration. This keyword is similar to the extern keyword in C. It exposes the function to make it available in the library API. Therefore, if you are writing a library for other people to use, you have to expose the functions you write in the public API of this library by using this export keyword. If we removed the export keyword from the add() function declaration, then, this function would be no longer exposed in the library object built by the zig compiler.\n\n\n1.2.3 The main.zig file\nNow that we have learned a lot about Zig’s syntax from the root.zig file, let’s take a look at the main.zig file. A lot of the elements we saw in root.zig are also present in main.zig. But there are some other elements that we haven’t seen yet, so let’s dive in.\nFirst, look at the return type of the main() function in this file. We can see a small change. The return type of the function (void) is accompanied by an exclamation mark (!). This exclamation mark tells us that this main() function might return an error.\nIn this example, the main() function can either return void or return an error. This is an interesting feature of Zig. If you write a function and something inside of the body of this function might return an error then you are forced to:\n\neither add the exclamation mark to the return type of the function and make it clear that this function might return an error\nexplicitly handle this error inside the function\n\nIn most programming languages, we normally handle (or deal with) an error through a try catch pattern. Zig does have both try and catch keywords. But they work a little differently than what you’re probably used to in other languages.\nIf we look at the main() function below, you can see that we do have a try keyword on the 5th line. But we do not have a catch keyword in this code. In Zig, we use the try keyword to execute an expression that might return an error, which, in this example, is the stdout.print() expression.\nIn essence, the try keyword executes the expression stdout.print(). If this expression returns a valid value, then, the try keyword does nothing. It only passes the value forward. But if the expression does return an error, then, the try keyword just unwrap the error value, and return this error from the function and also prints the current stack trace to stderr.\nThis might sound weird to you if you come from a high-level language. Because in high-level languages, such as Python, if an error occurs somewhere, this error is automatically returned and the execution of your program will automatically stop even if you don’t want to stop the execution. You are obligated to face the error.\n\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n\nAnother thing that you might have noticed in this code example, is that the main() function is marked with the pub keyword. It marks the main() function as a public function from this module.\nEvery function in your Zig module is by default private to this Zig module and can only be called from within the module. Unless, you explicitly mark this function as a public function with the pub keyword. This means that the pub keyword in Zig does essentially the opposite of what the static keyword do in C/C++.\nBy making a function “public” you allow other Zig modules to access and call it. A calling Zig module imports the module with the @import() built-in. That makes all public functions from the imported module visible.\n\n\n1.2.4 Compiling your source code\nYou can compile your Zig modules into a binary executable by running the build-exe command from the zig compiler. You simply list all the Zig modules that you want to build after the build-exe command, separated by spaces. In the example below, we are compiling the module main.zig.\nzig build-exe src/main.zig\nSince we are building an executable, the zig compiler will look for a main() function declared in any of the files that you list after the build-exe command. If the compiler does not find a main() function declared somewhere, a compilation error will be raised, warning about this mistake.\nThe zig compiler also offers a build-lib and build-obj commands, which work the exact same way as the build-exe command. The only difference is that, they compile your Zig modules into a portale C ABI library, or, into object files, respectively.\nIn the case of the build-exe command, a binary executable file is created by the zig compiler in the root directory of your project. If we take a look now at the contents of our current directory, with a simple ls command, we can see the binary file called main that was created by the compiler.\nls\nbuild.zig  build.zig.zon  main  src\nIf I execute this binary executable, I get the “Hello World” message in the terminal , as we expected.\n./main\nHello, world!\n\n\n1.2.5 Compile and execute at the same time\nOn the previous section, I presented the zig build-exe command, which compiles Zig modules into an executable file. However, this means that, in order to execute the executable file, we have to run two different commands. First, the zig build-exe command, and then, we call the executable file created by the compiler.\nBut what if we wanted to perform these two steps, all at once, in a single command? We can do that by using the zig run command.\nzig run src/main.zig\nHello, world!\n\n\n1.2.6 Important note for Windows users\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other operational systems, such as Linux and MacOs. In summary, if you have a piece of Zig code that includes some global variables whose initialization rely on runtime resources, then, you might have some troubles while trying to compile this Zig code on Windows.\nAn example of that is accessing the stdout (i.e. the standard output of your system), which is usually done in Zig by using the expression std.io.getStdOut(). Thus, if you use this expression to instantiate a global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows, with a “unable to evaluate comptime expression” error message.\nThis failure in the compilation process happens because all global variables in Zig are initialized at compile-time. However, operations like accessing the stdout (or opening a file) on Windows depends on resources that are available only at runtime (you will learn more about compile-time versus runtime at Section 3.1.1).\nFor example, if you try to compile this code example on Windows, you will likely get the error message exposed below:\n\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\nTo avoid this problem on Windows, we need to force the zig compiler to instantiate this stdout object only at runtime, instead of instantiating it at compile-time. We can achieve that by simply moving the expression to a function body.\nThis solves the problem because all expressions that are inside a function body in Zig are evaluated only at runtime, unless you use the comptime keyword explicitly to change this behaviour. You will learn more about this comptime keyword at Section 12.1.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nHello\nYou can read more details about this Windows-specific limitation at a couple of GitHub issues opened at the official Zig repository. More specifically, the issues 17186 3 and 19864 4.\n\n\n1.2.7 Compiling the entire project\nJust as I described at Section 1.2.1, as our project grows in size and complexity, we usually prefer to organize the compilation and build process of the project into a build script, using some sort of “build system”.\nIn other words, as our project grows in size and complexity, the build-exe, build-lib and build-obj commands become harder to use directly. Because then, we start to list multiple and multiple modules at the same time. We also start to add built-in compilation flags to customize the build process for our needs, etc. It becomes a lot of work to write the necessary commands by hand.\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, Makefile or configure scripts to organize this process. However, in Zig, we have a native build system in the language itself. So, we can write build scripts in Zig to compile and build Zig projects. Then, all we need to do, is to call the zig build command to build our project.\nSo, when you execute the zig build command, the zig compiler will search for a Zig module named build.zig inside your current directory, which should be your build script, containing the necessary code to compile and build your project. If the compiler does find this build.zig file in your directory, then, the compiler will essentially execute a zig run command over this build.zig file, to compile and execute this build script, which in turn, will compile and build your entire project.\nzig build\nAfter you execute this “build project” command, a zig-out directory is created in the root of your project directory, where you can find the binary executables and libraries created from your Zig modules accordingly to the build commands that you specified at build.zig. We will talk more about the build system in Zig latter in this book.\nIn the example below, I’m executing the binary executable named hello_world that was generated by the compiler after the zig build command.\n./zig-out/bin/hello_world\nHello, world!",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -134,7 +134,7 @@
     "href": "Chapters/01-zig-weird.html#how-to-learn-zig",
     "title": "1  Introducing Zig",
     "section": "1.3 How to learn Zig?",
-    "text": "1.3 How to learn Zig?\nWhat are the best strategies to learn Zig? First of all, of course this book will help you a lot on your journey through Zig. But you will also need some extra resources if you want to be really good at Zig.\nAs a first tip, you can join a community with Zig programmers to get some help , when you need it:\n\nReddit forum: https://www.reddit.com/r/Zig/;\nZiggit community: https://ziggit.dev/;\nDiscord, Slack, Telegram, and others: https://github.com/ziglang/zig/wiki/Community;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try to read Zig code often, and things will become more clear. A C/C++ programmer would also probably give you this same tip. Because this strategy really works!\nNow, where can you find Zig code to read? I personally think that, the best way of reading Zig code is to read the source code of the Zig Standard Library. The Zig Standard Library is available at the lib/std folder3 on the official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\nAlso, a great alternative is to read code from other large Zig codebases, such as:\n\nthe Javascript runtime Bun4.\nthe game engine Mach5.\na LLama 2 LLM model implementation in Zig6.\nthe financial transactions database tigerbeetle7.\nthe command-line arguments parser zig-clap8.\nthe UI framework capy9.\nthe Language Protocol implementation for Zig, zls10.\nthe event-loop library libxev11.\n\nAll these assets are available on GitHub, and this is great, because we can use the GitHub search bar in our advantage, to find Zig code that fits our description. For example, you can always include lang:Zig in the GitHub search bar when you are searching for a particular pattern. This will limit the search to only Zig modules.\nAlso, a great alternative is to consult online resources and documentations. Here is a quick list of resources that I personally use from time to time to learn more about the language each day:\n\nZig Language Reference: https://ziglang.org/documentation/master/;\nZig Standard Library Reference: https://ziglang.org/documentation/master/std/;\nZig Guide: https://zig.guide/;\nKarl Seguin Blog: https://www.openmymind.net/;\nZig News: https://zig.news/;\nRead the code written by one of the Zig core team members: https://github.com/kubkon;\nSome livecoding sessions are transmitted in the Zig Showtime Youtube Channel: https://www.youtube.com/@ZigSHOWTIME/videos;\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want, is to practice it by solving exercises. For example, there is a famous repository in the Zig community called Ziglings12 , which contains more than 100 small exercises that you can solve. It is a repository of tiny programs written in Zig that are currently broken, and your responsibility is to fix these programs, and make them work again.\nA famous tech YouTuber known as The Primeagen also posted some videos (at YouTube) where he solves these exercises from Ziglings. The first video is named “Trying Zig Part 1”13.\nAnother great alternative, is to solve the Advent of Code exercises14. There are people that already took the time to learn and solve the exercises, and they posted their solutions on GitHub as well, so, in case you need some resource to compare while solving the exercises, you can look at these two repositories:\n\nhttps://github.com/SpexGuy/Zig-AoC-Template;\nhttps://github.com/fjebaker/advent-of-code-2022;",
+    "text": "1.3 How to learn Zig?\nWhat are the best strategies to learn Zig? First of all, of course this book will help you a lot on your journey through Zig. But you will also need some extra resources if you want to be really good at Zig.\nAs a first tip, you can join a community with Zig programmers to get some help , when you need it:\n\nReddit forum: https://www.reddit.com/r/Zig/;\nZiggit community: https://ziggit.dev/;\nDiscord, Slack, Telegram, and others: https://github.com/ziglang/zig/wiki/Community;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try to read Zig code often, and things will become more clear. A C/C++ programmer would also probably give you this same tip. Because this strategy really works!\nNow, where can you find Zig code to read? I personally think that, the best way of reading Zig code is to read the source code of the Zig Standard Library. The Zig Standard Library is available at the lib/std folder5 on the official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\nAlso, a great alternative is to read code from other large Zig codebases, such as:\n\nthe Javascript runtime Bun6.\nthe game engine Mach7.\na LLama 2 LLM model implementation in Zig8.\nthe financial transactions database tigerbeetle9.\nthe command-line arguments parser zig-clap10.\nthe UI framework capy11.\nthe Language Protocol implementation for Zig, zls12.\nthe event-loop library libxev13.\n\nAll these assets are available on GitHub, and this is great, because we can use the GitHub search bar in our advantage, to find Zig code that fits our description. For example, you can always include lang:Zig in the GitHub search bar when you are searching for a particular pattern. This will limit the search to only Zig modules.\nAlso, a great alternative is to consult online resources and documentations. Here is a quick list of resources that I personally use from time to time to learn more about the language each day:\n\nZig Language Reference: https://ziglang.org/documentation/master/;\nZig Standard Library Reference: https://ziglang.org/documentation/master/std/;\nZig Guide: https://zig.guide/;\nKarl Seguin Blog: https://www.openmymind.net/;\nZig News: https://zig.news/;\nRead the code written by one of the Zig core team members: https://github.com/kubkon;\nSome livecoding sessions are transmitted in the Zig Showtime Youtube Channel: https://www.youtube.com/@ZigSHOWTIME/videos;\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want, is to practice it by solving exercises. For example, there is a famous repository in the Zig community called Ziglings14 , which contains more than 100 small exercises that you can solve. It is a repository of tiny programs written in Zig that are currently broken, and your responsibility is to fix these programs, and make them work again.\nA famous tech YouTuber known as The Primeagen also posted some videos (at YouTube) where he solves these exercises from Ziglings. The first video is named “Trying Zig Part 1”15.\nAnother great alternative, is to solve the Advent of Code exercises16. There are people that already took the time to learn and solve the exercises, and they posted their solutions on GitHub as well, so, in case you need some resource to compare while solving the exercises, you can look at these two repositories:\n\nhttps://github.com/SpexGuy/Zig-AoC-Template;\nhttps://github.com/fjebaker/advent-of-code-2022;",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -154,7 +154,7 @@
     "href": "Chapters/01-zig-weird.html#sec-primitive-data-types",
     "title": "1  Introducing Zig",
     "section": "1.5 Primitive Data Types",
-    "text": "1.5 Primitive Data Types\nZig have many different primitive data types available for you to use. You can see the full list of available data types at the official Language Reference page15.\nBut here is a quick list:\n\nUnsigned integers: u8, 8-bit integer; u16, 16-bit integer; u32, 32-bit integer; u64, 64-bit integer; u128, 128-bit integer.\nSigned integers: i8, 8-bit integer; i16, 16-bit integer; i32, 32-bit integer; i64, 64-bit integer; i128, 128-bit integer.\nFloat number: f16, 16-bit floating point; f32, 32-bit floating point; f64, 64-bit floating point; f128, 128-bit floating point;\nBoolean: bool, represents true or false values.\nC ABI compatible types: c_long, c_char, c_short, c_ushort, c_int, c_uint, and many others.\nPointer sized integers: isize and usize.",
+    "text": "1.5 Primitive Data Types\nZig have many different primitive data types available for you to use. You can see the full list of available data types at the official Language Reference page17.\nBut here is a quick list:\n\nUnsigned integers: u8, 8-bit integer; u16, 16-bit integer; u32, 32-bit integer; u64, 64-bit integer; u128, 128-bit integer.\nSigned integers: i8, 8-bit integer; i16, 16-bit integer; i32, 32-bit integer; i64, 64-bit integer; i128, 128-bit integer.\nFloat number: f16, 16-bit floating point; f32, 32-bit floating point; f64, 64-bit floating point; f128, 128-bit floating point;\nBoolean: bool, represents true or false values.\nC ABI compatible types: c_long, c_char, c_short, c_ushort, c_int, c_uint, and many others.\nPointer sized integers: isize and usize.",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -184,7 +184,7 @@
     "href": "Chapters/01-zig-weird.html#sec-zig-strings",
     "title": "1  Introducing Zig",
     "section": "1.8 How strings work in Zig?",
-    "text": "1.8 How strings work in Zig?\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (Chapter 4). But in order for us to build such a thing, we need to get a better understanding on how strings work in Zig. So let’s discuss this specific aspect of Zig.\nIn summary, there are two types of string values that you care about in Zig, which are:\n\nString literal values.\nString objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string). But in Zig, a string literal value also embeds the length of the string into the data type of the value itself. Therefore, a string literal value have a data type in the format *const [n:0]u8. The n in the data type indicates the size of the string.\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes, or, in other words, a slice of u8 values (slices were presented at Section 1.6). Thus, a string object have a data type of []u8 or []const u8, depending if the string object is marked as constant with const, or as variable with var.\nBecause a string object is essentially a slice, it means that a string object always contains two things: a pointer to an array of bytes (i.e. u8 values) that represents the string value; and also, a length value, which specifies the size of the slice, or, how many elements there is in the slice. Is worth to emphasize that the array of bytes in a string object is not null-terminated, like in a string literal value.\n\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every sequence of bytes you’re working with, but is not really Zig’s job to fix the encoding of your strings (you can use iconv16 for that). Today, most of the text in our modern world, especially on the web, should be UTF-8 encoded. So if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\nLet’s take for example the word “Hello”. In UTF-8, this sequence of characters (H, e, l, l, o) is represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this sequence is 0x48, 0x65, 0x6C, 0x6C, 0x6F. So if I take this sequence of hexadecimal values, and ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then, the text “Hello” will be printed into the terminal:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n\nHello\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use a for loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal value to the terminal. You do that by using a print() statement with the X formatting specifier, like you would normally do with the printf() function17 in C.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n\n\n\n1.8.1 Strings in C\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well. In more details, string values in C are treated internally as an array of arbitrary bytes, and this array is also null-terminated.\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of the string inside the object itself. In the case of a string literal value, this length is stored in the data type of the value (i.e. the n variable in [n:0]u8). While, in a string object, the length is stored in the len attribute of the slice that represents the string object. This small detail makes your code safer, because is much easier for the Zig compiler to check if you are trying to access an element that is “out of bounds”, i.e. if your trying to access memory that does not belong to you.\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless. So getting this kind of safety is not automatic and much harder to do in C. For example, if you want to track the length of your string throughout your program in C, then, you first need to loop through the array of bytes that represents this string, and find the null element ('\\0') position to discover where exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\nTo do that, you would need something like this in C. In this example, the C string stored in the object array is 25 bytes long:\n\n#include &lt;stdio.h&gt;\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n\nNumber of elements in the array: 25\nYou don’t have this kind of work in Zig. Because the length of the string is always present and accessible. In a string object for example, you can easily access the length of the string through the len attribute. As an example, the string_object object below is 43 bytes long:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n\n43\n\n\n\n\n1.8.2 A better look at the object type\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the @TypeOf() function. If we look at the type of the simple_array object below, you will find that this object is an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type i32 in Zig. That is what an object of type [4]i32 is.\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a constant pointer (hence the *const annotation) to an array of 16 elements (or 16 bytes). Each element is a single byte (more precisely, an unsigned 8 bit integer - u8), that is why we have the [16:0]u8 portion of the type below. In other words, the string literal value exposed below is 16 bytes long.\nNow, if we create an pointer to the simple_array object, then, we get a constant pointer to an array of 4 elements (*const [4]i32), which is very similar to the type of the string literal value. This demonstrates that a string literal value in Zig is already a pointer to a null-terminated array of bytes.\nFurthermore, if we take a look at the type of the string_obj object, you will see that it is a slice object (hence the [] portion of the type) to a sequence of constant u8 values (hence the const u8 portion of the type).\n\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n\n\n1.8.3 Byte vs unicode points\nIs important to point out that each byte in the array is not necessarily a single character. This fact arises from the difference between a single byte and a single unicode point.\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in the string. For example, the character “H” is stored in UTF-8 as the decimal number 72. This means that the number 72 is the unicode point for the character “H”. Each possible character that can appear in a UTF-8 encoded string have its own unicode point.\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point) 570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which is 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why, the unicode point 570 is actually stored inside the computer’s memory as the bytes C8 BA.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n\nBytes that represents the string object: C8 BA \n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together to represent the number 570. That is why the relationship between bytes and unicode points is not always 1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds to a single unicode point.\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the bytes that represents that string, and not through the characters of that string. In the Ⱥ example above, the for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a consequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because the number of bytes will be equal to the number of characters in that string. In other words, in this specific situation, the relationship between bytes and unicode points is 1 to 1.\nBut on the other side, if your string contains other types of letters… for example, you might be working with text data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent your UTF-8 string will likely be much higher than the number of characters in that string.\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the std.unicode.Utf8View struct to create an iterator that iterates through the unicode points of your string.\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in this string is represented by three bytes. But the for loop iterates four times, one iteration for each character/unicode point in this string:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n\n\n1.8.4 Some useful functions for strings\nIn this section, I just want to quickly describe some functions from the Zig Standard Library that are very useful to use when working with strings. Most notably:\n\nstd.mem.eql(): to compare if two strings are equal.\nstd.mem.splitScalar(): to split a string into an array of substrings given a delimiter value.\nstd.mem.splitSequence(): to split a string into an array of substrings given a substring delimiter.\nstd.mem.startsWith(): to check if string starts with substring.\nstd.mem.endsWith(): to check if string ends with substring.\nstd.mem.trim(): to remove specific values from both start and end of the string.\nstd.mem.concat(): to concatenate strings together.\nstd.mem.count(): to count the occurrences of substring in the string.\nstd.mem.replace(): to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the mem module of the Zig Standard Library. This module contains multiple functions and methods that are useful to work with memory and sequences of bytes in general.\nThe eql() function is used to check if two arrays of data are equal or not. Since strings are just arbitrary arrays of bytes, we can use this function to compare two strings together. This function returns a boolean value indicating if the two strings are equal or not. The first argument of this function is the data type of the elements of the arrays that are being compared.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n\ntrue\n\n\nThe splitScalar() and splitSequence() functions are useful to split a string into multiple fragments, like the split() method from Python strings. The difference between these two methods is that the splitScalar() uses a single character as the separator to split the string, while splitSequence() uses a sequence of characters (a.k.a. a substring) as the separator. There is a practical example of these functions later in the book.\nThe startsWith() and endsWith() functions are pretty straightforward. They return a boolean value indicating if the string (or, more precisely, if the array of data) begins (startsWith) or ends (endsWith) with the sequence provided.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n\ntrue\n\n\nThe concat() function, as the name suggests, concatenate two or more strings together. Because the process of concatenating the strings involves allocating enough space to accomodate all the strings together, this concat() function receives an allocator object as input.\n\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n\nHello you!\nAs you can imagine, the replace() function is used to replace substrings in a string by another substring. This function works very similarly to the replace() method from Python strings. Therefore, you provide a substring to search, and every time that the replace() function finds this substring within the input string, it replaces this substring with the “replacement substring” that you provided as input.\nIn the example below, we are taking the input string “Hello”, and replacing all occurrences of the substring “el” inside this input string with “34”, and saving the results inside the buffer object. As result, the replace() function returns an usize value that indicates how many replacements were performed.\n\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n\nNew string: H34lo\nN of replacements: 1",
+    "text": "1.8 How strings work in Zig?\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (Chapter 4). But in order for us to build such a thing, we need to get a better understanding on how strings work in Zig. So let’s discuss this specific aspect of Zig.\nIn summary, there are two types of string values that you care about in Zig, which are:\n\nString literal values.\nString objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string). But in Zig, a string literal value also embeds the length of the string into the data type of the value itself. Therefore, a string literal value have a data type in the format *const [n:0]u8. The n in the data type indicates the size of the string.\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes, or, in other words, a slice of u8 values (slices were presented at Section 1.6). Thus, a string object have a data type of []u8 or []const u8, depending if the string object is marked as constant with const, or as variable with var.\nBecause a string object is essentially a slice, it means that a string object always contains two things: a pointer to an array of bytes (i.e. u8 values) that represents the string value; and also, a length value, which specifies the size of the slice, or, how many elements there is in the slice. Is worth to emphasize that the array of bytes in a string object is not null-terminated, like in a string literal value.\n\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every sequence of bytes you’re working with, but is not really Zig’s job to fix the encoding of your strings (you can use iconv18 for that). Today, most of the text in our modern world, especially on the web, should be UTF-8 encoded. So if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\nLet’s take for example the word “Hello”. In UTF-8, this sequence of characters (H, e, l, l, o) is represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this sequence is 0x48, 0x65, 0x6C, 0x6C, 0x6F. So if I take this sequence of hexadecimal values, and ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then, the text “Hello” will be printed into the terminal:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n\nHello\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use a for loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal value to the terminal. You do that by using a print() statement with the X formatting specifier, like you would normally do with the printf() function19 in C.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n\n\n\n1.8.1 Strings in C\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well. In more details, string values in C are treated internally as an array of arbitrary bytes, and this array is also null-terminated.\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of the string inside the object itself. In the case of a string literal value, this length is stored in the data type of the value (i.e. the n variable in [n:0]u8). While, in a string object, the length is stored in the len attribute of the slice that represents the string object. This small detail makes your code safer, because is much easier for the Zig compiler to check if you are trying to access an element that is “out of bounds”, i.e. if your trying to access memory that does not belong to you.\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless. So getting this kind of safety is not automatic and much harder to do in C. For example, if you want to track the length of your string throughout your program in C, then, you first need to loop through the array of bytes that represents this string, and find the null element ('\\0') position to discover where exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\nTo do that, you would need something like this in C. In this example, the C string stored in the object array is 25 bytes long:\n\n#include &lt;stdio.h&gt;\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n\nNumber of elements in the array: 25\nYou don’t have this kind of work in Zig. Because the length of the string is always present and accessible. In a string object for example, you can easily access the length of the string through the len attribute. As an example, the string_object object below is 43 bytes long:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n\n43\n\n\n\n\n1.8.2 A better look at the object type\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the @TypeOf() function. If we look at the type of the simple_array object below, you will find that this object is an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type i32 in Zig. That is what an object of type [4]i32 is.\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a constant pointer (hence the *const annotation) to an array of 16 elements (or 16 bytes). Each element is a single byte (more precisely, an unsigned 8 bit integer - u8), that is why we have the [16:0]u8 portion of the type below. In other words, the string literal value exposed below is 16 bytes long.\nNow, if we create an pointer to the simple_array object, then, we get a constant pointer to an array of 4 elements (*const [4]i32), which is very similar to the type of the string literal value. This demonstrates that a string literal value in Zig is already a pointer to a null-terminated array of bytes.\nFurthermore, if we take a look at the type of the string_obj object, you will see that it is a slice object (hence the [] portion of the type) to a sequence of constant u8 values (hence the const u8 portion of the type).\n\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n\n\n1.8.3 Byte vs unicode points\nIs important to point out that each byte in the array is not necessarily a single character. This fact arises from the difference between a single byte and a single unicode point.\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in the string. For example, the character “H” is stored in UTF-8 as the decimal number 72. This means that the number 72 is the unicode point for the character “H”. Each possible character that can appear in a UTF-8 encoded string have its own unicode point.\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point) 570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which is 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why, the unicode point 570 is actually stored inside the computer’s memory as the bytes C8 BA.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n\nBytes that represents the string object: C8 BA \n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together to represent the number 570. That is why the relationship between bytes and unicode points is not always 1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds to a single unicode point.\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the bytes that represents that string, and not through the characters of that string. In the Ⱥ example above, the for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a consequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because the number of bytes will be equal to the number of characters in that string. In other words, in this specific situation, the relationship between bytes and unicode points is 1 to 1.\nBut on the other side, if your string contains other types of letters… for example, you might be working with text data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent your UTF-8 string will likely be much higher than the number of characters in that string.\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the std.unicode.Utf8View struct to create an iterator that iterates through the unicode points of your string.\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in this string is represented by three bytes. But the for loop iterates four times, one iteration for each character/unicode point in this string:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n\n\n1.8.4 Some useful functions for strings\nIn this section, I just want to quickly describe some functions from the Zig Standard Library that are very useful to use when working with strings. Most notably:\n\nstd.mem.eql(): to compare if two strings are equal.\nstd.mem.splitScalar(): to split a string into an array of substrings given a delimiter value.\nstd.mem.splitSequence(): to split a string into an array of substrings given a substring delimiter.\nstd.mem.startsWith(): to check if string starts with substring.\nstd.mem.endsWith(): to check if string ends with substring.\nstd.mem.trim(): to remove specific values from both start and end of the string.\nstd.mem.concat(): to concatenate strings together.\nstd.mem.count(): to count the occurrences of substring in the string.\nstd.mem.replace(): to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the mem module of the Zig Standard Library. This module contains multiple functions and methods that are useful to work with memory and sequences of bytes in general.\nThe eql() function is used to check if two arrays of data are equal or not. Since strings are just arbitrary arrays of bytes, we can use this function to compare two strings together. This function returns a boolean value indicating if the two strings are equal or not. The first argument of this function is the data type of the elements of the arrays that are being compared.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n\ntrue\n\n\nThe splitScalar() and splitSequence() functions are useful to split a string into multiple fragments, like the split() method from Python strings. The difference between these two methods is that the splitScalar() uses a single character as the separator to split the string, while splitSequence() uses a sequence of characters (a.k.a. a substring) as the separator. There is a practical example of these functions later in the book.\nThe startsWith() and endsWith() functions are pretty straightforward. They return a boolean value indicating if the string (or, more precisely, if the array of data) begins (startsWith) or ends (endsWith) with the sequence provided.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n\ntrue\n\n\nThe concat() function, as the name suggests, concatenate two or more strings together. Because the process of concatenating the strings involves allocating enough space to accomodate all the strings together, this concat() function receives an allocator object as input.\n\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n\nHello you!\nAs you can imagine, the replace() function is used to replace substrings in a string by another substring. This function works very similarly to the replace() method from Python strings. Therefore, you provide a substring to search, and every time that the replace() function finds this substring within the input string, it replaces this substring with the “replacement substring” that you provided as input.\nIn the example below, we are taking the input string “Hello”, and replacing all occurrences of the substring “el” inside this input string with “34”, and saving the results inside the buffer object. As result, the replace() function returns an usize value that indicates how many replacements were performed.\n\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n\nNew string: H34lo\nN of replacements: 1",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -194,7 +194,7 @@
     "href": "Chapters/01-zig-weird.html#safety-in-zig",
     "title": "1  Introducing Zig",
     "section": "1.9 Safety in Zig",
-    "text": "1.9 Safety in Zig\nA general trend in modern low-level programming languages is safety. As our modern world becomes more interconnected with technology and computers, the data produced by all of this technology becomes one of the most important (and also, one of the most dangerous) assets that we have.\nThis is probably the main reason why modern low-level programming languages have been giving great attention to safety, especially memory safety, because memory corruption is still the main target for hackers to exploit. The reality is that we don’t have an easy solution for this problem. For now, we only have techniques and strategies that mitigates these problems.\nAs Richard Feldman explains on his most recent GOTO conference talk18 , we haven’t figured it out yet a way to achieve true safety in technology. In other words, we haven’t found a way to build software that won’t be exploited with 100% certainty. We can greatly reduce the risks of our software being exploited, by ensuring memory safety for example. But this is not enough to achieve “true safety” territory.\nBecause even if you write your program in a “safe language”, hackers can still exploit failures in the operational system where your program is running (e.g. maybe the system where your code is running has a “backdoor exploit” that can still affect your code in unexpected ways), or also, they can exploit the features from the architecture of your computer. A recently found exploit that involves memory invalidation through a feature of “memory tags” present in ARM chips is an example of that (Kim et al. 2024).\nThe question is: what have Zig and other languages been doing to mitigate this problem? If we take Rust as an example, Rust is, for the most part19, a memory safe language by enforcing specific rules to the developer. In other words, the key feature of Rust, the borrow checker, forces you to follow a specific logic when you are writing your Rust code, and the Rust compiler will always complain everytime you try to go out of this pattern.\nIn contrast, the Zig language is not a memory safe language by default. There are some memory safety features that you get for free in Zig, especially in arrays and pointer objects. But there are other tools offered by the language, that are not used by default. In other words, the zig compiler does not obligates you to use such tools.\nThe tools listed below are related to memory safety. That is, they help you to achieve memory safety in your Zig code:\n\ndefer allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, “use after free”, and also “double-free” problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\nerrdefer helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\npointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\nZig offers some native types of allocators (called “testing allocators”) that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\narrays and slices in Zig have their lengths embedded in the object itself, which makes the zig compiler very effective on detecting “index out-of-range” type of errors, and avoiding buffer overflows.\n\nDespite these features that Zig offers that are related to memory safety issues, the language also has some rules that help you to achieve another type of safety, which is more related to program logic safety. These rules are:\n\npointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\nswitch statements must exaust all possible options.\nthe zig compiler forces you to handle every possible error in your program.",
+    "text": "1.9 Safety in Zig\nA general trend in modern low-level programming languages is safety. As our modern world becomes more interconnected with technology and computers, the data produced by all of this technology becomes one of the most important (and also, one of the most dangerous) assets that we have.\nThis is probably the main reason why modern low-level programming languages have been giving great attention to safety, especially memory safety, because memory corruption is still the main target for hackers to exploit. The reality is that we don’t have an easy solution for this problem. For now, we only have techniques and strategies that mitigates these problems.\nAs Richard Feldman explains on his most recent GOTO conference talk20 , we haven’t figured it out yet a way to achieve true safety in technology. In other words, we haven’t found a way to build software that won’t be exploited with 100% certainty. We can greatly reduce the risks of our software being exploited, by ensuring memory safety for example. But this is not enough to achieve “true safety” territory.\nBecause even if you write your program in a “safe language”, hackers can still exploit failures in the operational system where your program is running (e.g. maybe the system where your code is running has a “backdoor exploit” that can still affect your code in unexpected ways), or also, they can exploit the features from the architecture of your computer. A recently found exploit that involves memory invalidation through a feature of “memory tags” present in ARM chips is an example of that (Kim et al. 2024).\nThe question is: what have Zig and other languages been doing to mitigate this problem? If we take Rust as an example, Rust is, for the most part21, a memory safe language by enforcing specific rules to the developer. In other words, the key feature of Rust, the borrow checker, forces you to follow a specific logic when you are writing your Rust code, and the Rust compiler will always complain everytime you try to go out of this pattern.\nIn contrast, the Zig language is not a memory safe language by default. There are some memory safety features that you get for free in Zig, especially in arrays and pointer objects. But there are other tools offered by the language, that are not used by default. In other words, the zig compiler does not obligates you to use such tools.\nThe tools listed below are related to memory safety. That is, they help you to achieve memory safety in your Zig code:\n\ndefer allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, “use after free”, and also “double-free” problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\nerrdefer helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\npointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\nZig offers some native types of allocators (called “testing allocators”) that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\narrays and slices in Zig have their lengths embedded in the object itself, which makes the zig compiler very effective on detecting “index out-of-range” type of errors, and avoiding buffer overflows.\n\nDespite these features that Zig offers that are related to memory safety issues, the language also has some rules that help you to achieve another type of safety, which is more related to program logic safety. These rules are:\n\npointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\nswitch statements must exaust all possible options.\nthe zig compiler forces you to handle every possible error in your program.",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -214,7 +214,7 @@
     "href": "Chapters/01-zig-weird.html#footnotes",
     "title": "1  Introducing Zig",
     "section": "",
-    "text": "https://ziglang.org/learn/overview/#zig-build-system.↩︎\nhttps://en.wikipedia.org/wiki/List_of_C-family_programming_languages↩︎\nhttps://github.com/ziglang/zig/tree/master/lib/std↩︎\nhttps://github.com/oven-sh/bun.↩︎\nhttps://github.com/hexops/mach↩︎\nhttps://github.com/cgbur/llama2.zig/tree/main↩︎\nhttps://github.com/tigerbeetle/tigerbeetle↩︎\nhttps://github.com/Hejsil/zig-clap↩︎\nhttps://github.com/capy-ui/capy↩︎\nhttps://github.com/zigtools/zls↩︎\nhttps://github.com/mitchellh/libxev↩︎\nhttps://ziglings.org.↩︎\nhttps://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen.↩︎\nhttps://adventofcode.com/↩︎\nhttps://ziglang.org/documentation/master/#Primitive-Types.↩︎\nhttps://www.gnu.org/software/libiconv/↩︎\nhttps://cplusplus.com/reference/cstdio/printf/↩︎\nhttps://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences↩︎\nActually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (foreign function interface), which disables the borrow-checker features through the unsafe keyword.↩︎",
+    "text": "https://ziglang.org/learn/overview/#zig-build-system.↩︎\nhttps://en.wikipedia.org/wiki/List_of_C-family_programming_languages↩︎\nhttps://github.com/ziglang/zig/issues/17186↩︎\nhttps://github.com/ziglang/zig/issues/19864↩︎\nhttps://github.com/ziglang/zig/tree/master/lib/std↩︎\nhttps://github.com/oven-sh/bun.↩︎\nhttps://github.com/hexops/mach↩︎\nhttps://github.com/cgbur/llama2.zig/tree/main↩︎\nhttps://github.com/tigerbeetle/tigerbeetle↩︎\nhttps://github.com/Hejsil/zig-clap↩︎\nhttps://github.com/capy-ui/capy↩︎\nhttps://github.com/zigtools/zls↩︎\nhttps://github.com/mitchellh/libxev↩︎\nhttps://ziglings.org.↩︎\nhttps://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen.↩︎\nhttps://adventofcode.com/↩︎\nhttps://ziglang.org/documentation/master/#Primitive-Types.↩︎\nhttps://www.gnu.org/software/libiconv/↩︎\nhttps://cplusplus.com/reference/cstdio/printf/↩︎\nhttps://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences↩︎\nActually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (foreign function interface), which disables the borrow-checker features through the unsafe keyword.↩︎",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]

From a5b760fea36644c649e6b9f20164734e2be2d2ba Mon Sep 17 00:00:00 2001
From: Vedang Manerikar <ved.manerikar@gmail.com>
Date: Wed, 27 Nov 2024 02:31:30 +0530
Subject: [PATCH 008/151] Specify the CRAN mirror server in install.packages

As someone with no experience with R, I just installed R using:

`brew install --cask R`

and tried to run the script with:

`Rscript dependencies.R`

It threw the error:

```
Error in contrib.url(repos, "source") :
  trying to use CRAN without setting a mirror
Calls: install.packages -> contrib.url
Execution halted
```

Google told me that the repos parameter would tell R where to install
the packages from, and this change fixed the script for me.

Thanks!
---
 dependencies.R | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/dependencies.R b/dependencies.R
index 69fd8e7c..d2bb4a66 100644
--- a/dependencies.R
+++ b/dependencies.R
@@ -7,5 +7,5 @@ install.packages(
     "gt",
     "tibble"
   )
+  , repos = "http://cran.us.r-project.org"
 )
-

From 37c322e24daf0efffdf7d806727e2465c459216b Mon Sep 17 00:00:00 2001
From: Pedro Faria <69123925+pedropark99@users.noreply.github.com>
Date: Wed, 27 Nov 2024 15:56:28 -0300
Subject: [PATCH 009/151] Update dependencies.R

---
 dependencies.R | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/dependencies.R b/dependencies.R
index d2bb4a66..a17b9e76 100644
--- a/dependencies.R
+++ b/dependencies.R
@@ -7,5 +7,6 @@ install.packages(
     "gt",
     "tibble"
   )
-  , repos = "http://cran.us.r-project.org"
+  , repos = "https://cloud.r-project.org"
+
 )

From 885b9772fb58d98a048be1ece995f90928b56fe4 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Wed, 27 Nov 2024 15:58:50 -0300
Subject: [PATCH 010/151] Add @vedang to contributors list

---
 _freeze/index/execute-results/html.json | 2 +-
 contributors.txt                        | 1 +
 docs/index.html                         | 8 ++++----
 docs/search.json                        | 4 ++--
 4 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/_freeze/index/execute-results/html.json b/_freeze/index/execute-results/html.json
index a7b4efd1..7a43f8dd 100644
--- a/_freeze/index/execute-results/html.json
+++ b/_freeze/index/execute-results/html.json
@@ -2,7 +2,7 @@
   "hash": "0d9977ad882089aad1460aa86ce0e48e",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy an eBook or a physical copy\nof the book on Amazon:\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e. it is open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria have a bachelor degree in Economics from Federal University of Ouro Preto - Brazil.\nCurrently, he is a Data Platform Engineer at [Blip](https://www.blip.ai/en/)[^blip], and\nan Associate Developer for Apache Spark 3.0 certified by Databricks.\n\n[^blip]: <https://www.blip.ai/en/>\n\n\nThe author have more than 4 years of experience in the data industry. Developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nbrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer that loves to\nlearn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2024 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n\n\n- System version: Linux, 6.8.0-48-generic, NA, x86_64.\n- Zig version: 0.14.0-dev.2051+b1361f237.\n- Quarto version: 1.5.57.\n\n\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti)\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy an eBook or a physical copy\nof the book on Amazon:\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e. it is open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria have a bachelor degree in Economics from Federal University of Ouro Preto - Brazil.\nCurrently, he is a Data Platform Engineer at [Blip](https://www.blip.ai/en/)[^blip], and\nan Associate Developer for Apache Spark 3.0 certified by Databricks.\n\n[^blip]: <https://www.blip.ai/en/>\n\n\nThe author have more than 4 years of experience in the data industry. Developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nbrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer that loves to\nlearn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2024 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n\n- System version: Linux, 6.8.0-49-generic, NA, x86_64.\n- Zig version: 0.14.0-dev.2051+b1361f237.\n- Quarto version: 1.5.57.\n\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang)\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
diff --git a/contributors.txt b/contributors.txt
index 17bbcd5c..18cad9e2 100644
--- a/contributors.txt
+++ b/contributors.txt
@@ -11,3 +11,4 @@ Chris Boesch,@chrboesch
 Bruno,@PoorlyDefinedBehaviour
 Ilia Choly,@icholy
 Korri Katti,@KorryKatti
+Vedang Manerikar,@vedang
diff --git a/docs/index.html b/docs/index.html
index 6725b3d8..73c18985 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -7,7 +7,7 @@
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 <meta name="author" content="Pedro Duarte Faria">
-<meta name="dcterms.date" content="2024-11-24">
+<meta name="dcterms.date" content="2024-11-27">
 
 <title>Introduction to Zig</title>
 <style>
@@ -287,7 +287,7 @@ <h1 class="title">Introduction to Zig</h1>
     <div>
     <div class="quarto-title-meta-heading">Published</div>
     <div class="quarto-title-meta-contents">
-      <p class="date">November 24, 2024</p>
+      <p class="date">November 27, 2024</p>
     </div>
   </div>
   
@@ -411,7 +411,7 @@ <h2 class="unnumbered anchored" data-anchor-id="license">License</h2>
 <h2 class="unnumbered anchored" data-anchor-id="book-compilation-metadata">Book compilation metadata</h2>
 <p>This book was compiled using the following versions of <a href="https://ziglang.org">Zig</a> and <a href="https://quarto.org">Quarto</a>:</p>
 <ul>
-<li>System version: Linux, 6.8.0-48-generic, NA, x86_64.</li>
+<li>System version: Linux, 6.8.0-49-generic, NA, x86_64.</li>
 <li>Zig version: 0.14.0-dev.2051+b1361f237.</li>
 <li>Quarto version: 1.5.57.</li>
 </ul>
@@ -439,7 +439,7 @@ <h2 class="unnumbered anchored" data-anchor-id="corresponding-author-and-maintai
 <section id="acknowledgments" class="level2 unnumbered">
 <h2 class="unnumbered anchored" data-anchor-id="acknowledgments">Acknowledgments</h2>
 <p>This book is also a product of many conversations and exchanges that we had with different people from the Zig community. I (Pedro Duarte Faria) am incredibly grateful for these conversations, and also, for some direct contributions that we had. Below we have a list of the people involved (name of the person with their usename in GitHub):</p>
-<p>Calin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti)</p>
+<p>Calin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang)</p>
 
 
 </section>
diff --git a/docs/search.json b/docs/search.json
index 7e5b9b3f..d4e230f5 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -54,7 +54,7 @@
     "href": "index.html#book-compilation-metadata",
     "title": "Introduction to Zig",
     "section": "Book compilation metadata",
-    "text": "Book compilation metadata\nThis book was compiled using the following versions of Zig and Quarto:\n\nSystem version: Linux, 6.8.0-48-generic, NA, x86_64.\nZig version: 0.14.0-dev.2051+b1361f237.\nQuarto version: 1.5.57.",
+    "text": "Book compilation metadata\nThis book was compiled using the following versions of Zig and Quarto:\n\nSystem version: Linux, 6.8.0-49-generic, NA, x86_64.\nZig version: 0.14.0-dev.2051+b1361f237.\nQuarto version: 1.5.57.",
     "crumbs": [
       "Welcome"
     ]
@@ -84,7 +84,7 @@
     "href": "index.html#acknowledgments",
     "title": "Introduction to Zig",
     "section": "Acknowledgments",
-    "text": "Acknowledgments\nThis book is also a product of many conversations and exchanges that we had with different people from the Zig community. I (Pedro Duarte Faria) am incredibly grateful for these conversations, and also, for some direct contributions that we had. Below we have a list of the people involved (name of the person with their usename in GitHub):\nCalin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti)",
+    "text": "Acknowledgments\nThis book is also a product of many conversations and exchanges that we had with different people from the Zig community. I (Pedro Duarte Faria) am incredibly grateful for these conversations, and also, for some direct contributions that we had. Below we have a list of the people involved (name of the person with their usename in GitHub):\nCalin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang)",
     "crumbs": [
       "Welcome"
     ]

From 78ac8e04a99c5b30f8bd7ed19d9c92ff2c81dfd8 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Wed, 4 Dec 2024 19:22:25 -0300
Subject: [PATCH 011/151] Rewrite Zig engine

---
 Chapters/01-memory.qmd                        |  55 +-
 Chapters/01-zig-weird.qmd                     |  23 +-
 Chapters/03-structs.qmd                       |  20 +-
 Chapters/13-image-filter.qmd                  |   2 +-
 .../image_filter/pedro_pascal_filter.png      | Bin 171108 -> 171105 bytes
 ZigExamples/image_filter/src/image_filter.zig |   2 +-
 ZigExamples/zig-basics/string_replace.zig     |  10 +
 .../01-base64/execute-results/html.json       |   4 +-
 .../01-memory/execute-results/html.json       |   4 +-
 .../01-zig-weird/execute-results/html.json    |   4 +-
 .../02-debugging/execute-results/html.json    |   2 +-
 .../03-structs/execute-results/html.json      |   4 +-
 .../03-unittests/execute-results/html.json    |   2 +-
 .../04-http-server/execute-results/html.json  |   4 +-
 .../05-pointers/execute-results/html.json     |   6 +-
 .../07-build-system/execute-results/html.json |   4 +-
 .../execute-results/html.json                 |   6 +-
 .../execute-results/html.json                 |   6 +-
 .../execute-results/html.json                 |   6 +-
 .../12-file-op/execute-results/html.json      |   4 +-
 .../13-image-filter/execute-results/html.json |   8 +-
 .../14-threads/execute-results/html.json      |   4 +-
 .../execute-results/html.json                 |   4 +-
 _freeze/index/execute-results/html.json       |   2 +-
 docs/Chapters/01-memory.html                  |  60 ++-
 docs/Chapters/01-zig-weird.html               |  81 +--
 docs/Chapters/02-debugging.html               | 153 +++---
 docs/Chapters/03-structs.html                 | 327 ++++++------
 docs/Chapters/03-unittests.html               | 114 ++--
 docs/Chapters/05-pointers.html                | 125 ++---
 docs/Chapters/09-data-structures.html         | 174 +++---
 docs/Chapters/09-error-handling.html          | 134 ++---
 docs/Chapters/10-stack-project.html           | 311 ++++++-----
 docs/Chapters/13-image-filter.html            |   2 +-
 .../image_filter/pedro_pascal_filter.png      | Bin 171108 -> 171105 bytes
 docs/index.html                               |   6 +-
 docs/search.json                              |  32 +-
 zig_engine.R                                  | 503 +++++++++++++-----
 38 files changed, 1262 insertions(+), 946 deletions(-)
 create mode 100644 ZigExamples/zig-basics/string_replace.zig

diff --git a/Chapters/01-memory.qmd b/Chapters/01-memory.qmd
index 037cd9c1..0c4de856 100644
--- a/Chapters/01-memory.qmd
+++ b/Chapters/01-memory.qmd
@@ -98,17 +98,18 @@ whose value can be identified at compile time.
 
 
 ```{zig}
-#| auto_main: true
+#| auto_main: false
 #| build_type: "run"
-// ======== Variables
-const name = "Pedro";
-const array = [_]u8{1, 2, 3, 4};
-_ = name; _ = array;
-// ========= Function
 fn input_length(input: []const u8) usize {
     const n = input.len;
     return n;
 }
+
+pub fn main() !void {
+    const name = "Pedro";
+    const array = [_]u8{1, 2, 3, 4};
+    _ = name; _ = array;
+}
 ```
 
 The other side of the spectrum are objects whose values are not known at compile time.
@@ -203,16 +204,17 @@ But since it is declared in the "outer" scope, this object is stored in the
 stack space that belongs to this outer scope.
 
 ```{zig}
-#| auto_main: true
+#| auto_main: false
 #| build_type: "run"
-// ==== Variable
-const r = add(5, 27);
-_ = r;
-// ====== Function
 fn add(x: u8, y: u8) u8 {
     const result = x + y;
     return result;
 }
+
+pub fn main() !void {
+    const r = add(5, 27);
+    _ = r;
+}
 ```
 
 
@@ -297,19 +299,19 @@ bugs in your program [@zigdocs, see "Lifetime and Ownership"[^life] and "Undefin
 
 
 ```{zig}
-#| auto_main: true
+#| auto_main: false
 #| build_type: "run"
-// This code compiles successfully. But it has
-// undefined behaviour. Never do this!!!
-// ==== Variable
-// The `r` object is undefined!
-const r = add(5, 27);
-_ = r;
-// ====== Function
 fn add(x: u8, y: u8) *const u8 {
     const result = x + y;
     return &result;
 }
+
+pub fn main() !void {
+    // This code compiles successfully. But it has
+    // undefined behaviour. Never do this!!!
+    // The `r` object is undefined!
+    const r = add(5, 27); _ = r;
+}
 ```
 
 This "invalid pointer to stack variable" problem is very known across many programming language communities.
@@ -411,8 +413,7 @@ on the stack. You can see below that this program does not run succesfully, beca
 with a "segmentation fault" error message.
 
 ```{zig}
-#| eval: false
-#| build_type: "run"
+#| build_type: "ast"
 #| auto_main: true
 var very_big_alloc: [1000 * 1000 * 24]u64 = undefined;
 @memset(very_big_alloc[0..], 0);
@@ -628,8 +629,7 @@ allocator objects. You would have to allocate this very big buffer object on the
 The example below demonstrates this case.
 
 ```{zig}
-#| eval: false
-#| build_type: "run"
+#| build_type: "ast"
 #| auto_main: true
 const heap = std.heap.page_allocator;
 const memory_buffer = try heap.alloc(
@@ -665,17 +665,16 @@ below, I called `alloc()` 3 times. So, if I did not use an arena allocator, then
 `free()` 3 times to free all the allocated memory.
 
 ```{zig}
-#| eval: false
 #| auto_main: true
-#| build_type: "run"
+#| build_type: "lib"
 var gpa = std.heap.GeneralPurposeAllocator(.{}){};
 var aa = std.heap.ArenaAllocator.init(gpa.allocator());
 defer aa.deinit();
 const allocator = aa.allocator();
 
-const in1 = allocator.alloc(u8, 5);
-const in2 = allocator.alloc(u8, 10);
-const in3 = allocator.alloc(u8, 15);
+const in1 = try allocator.alloc(u8, 5);
+const in2 = try allocator.alloc(u8, 10);
+const in3 = try allocator.alloc(u8, 15);
 _ = in1; _ = in2; _ = in3;
 ```
 
diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index 65839232..6acd1bb5 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -189,7 +189,8 @@ objects (`std` and `testing`). At @sec-assignments we talk more about objects in
 
 
 ```{zig}
-#| eval: false
+#| auto_main: false
+#| build_type: "ast"
 const std = @import("std");
 const testing = std.testing;
 
@@ -272,8 +273,8 @@ to stop the execution. You are obligated to face the error.
 
 
 ```{zig}
-#| eval: false
 #| auto_main: false
+#| build_type: "ast"
 const std = @import("std");
 
 pub fn main() !void {
@@ -382,8 +383,8 @@ For example, if you try to compile this code example on Windows, you will likely
 exposed below:
 
 ```{zig}
-#| eval: false
 #| auto_main: false
+#| build_type: "ast"
 const std = @import("std");
 // ERROR! Compile-time error that emerge from
 // this next line, on the `stdout` object
@@ -412,7 +413,7 @@ You will learn more about this `comptime` keyword at @sec-comptime.
 
 
 ```{zig}
-#| eval: false
+#| build_type: "ast"
 #| auto_main: false
 const std = @import("std");
 pub fn main() !void {
@@ -692,8 +693,8 @@ called `age`. If you try to compile a simple Zig program with this line of code
 the compiler will return an error as demonstrated below:
 
 ```{zig}
-#| build_type: "run"
-#| eval: false
+#| build_type: "ast"
+#| auto_main: false
 const age = 15;
 ```
 
@@ -1015,7 +1016,8 @@ dereference the pointer of this slice, by using the `.*` method, like you would
 do on a normal pointer object.
 
 ```{zig}
-#| eval: false
+#| auto_main: false
+#| build_type: "ast"
 const arr1 = [10]u64 {
     1, 2, 3, 4, 5,
     6, 7, 8, 9, 10
@@ -1371,7 +1373,7 @@ character/unicode point in this string:
 
 ```{zig}
 #| auto_main: false
-#| eval: false
+#| build_type: "lib"
 const std = @import("std");
 const stdout = std.io.getStdOut().writer();
 
@@ -1457,7 +1459,7 @@ object as input.
 ```{zig}
 #| eval: false
 #| auto_main: true
-#| build_type: "run"
+#| build_type: "ast"
 const str1 = "Hello";
 const str2 = " you!";
 const str3 = try std.mem.concat(
@@ -1466,9 +1468,6 @@ const str3 = try std.mem.concat(
 try stdout.print("{s}\n", .{str3});
 ```
 
-```
-Hello you!
-```
 
 As you can imagine, the `replace()` function is used to replace substrings in a string by another substring.
 This function works very similarly to the `replace()` method from Python strings. Therefore, you
diff --git a/Chapters/03-structs.qmd b/Chapters/03-structs.qmd
index 1dd3552d..6ef11ae4 100644
--- a/Chapters/03-structs.qmd
+++ b/Chapters/03-structs.qmd
@@ -213,7 +213,8 @@ outputs a value as result, you can store the result value of the switch statemen
 a new object.
 
 ```{zig}
-#| eval: false
+#| auto_main: true
+#| build_type: "lib"
 const level: u8 = 4;
 const category = switch (level) {
     1, 2 => "beginner",
@@ -279,9 +280,8 @@ statement. In the example below, the execution goes back to the beginning of the
 switch statement two times, before ending at the `3` branch.
 
 ```{zig}
-#| auto_main: false
+#| auto_main: true
 #| build_type: "lib"
-#| eval: false
 xsw: switch (@as(u8, 1)) {
     1 => {
         try stdout.print("First branch\n", .{});
@@ -385,7 +385,8 @@ The code example below demonstrates three things:
 - that `defer` and `errdefer` expressions are executed in a LIFO (*last in, first out*) order.
 
 ```{zig}
-#| eval: false
+#| auto_main: false
+#| build_type: "lib"
 const std = @import("std");
 fn foo() !void { return error.FooError; }
 pub fn main() !void {
@@ -416,7 +417,8 @@ the value of `i` that get's printed to the console changes to 1. This doesn't me
 was executed only after the `errdefer` expression. The code example below demonstrates this:
 
 ```{zig}
-#| eval: false
+#| auto_main: false
+#| build_type: "lib"
 const std = @import("std");
 fn foo() !void { return error.FooError; }
 pub fn main() !void {
@@ -502,7 +504,9 @@ value items to the underscore character, like in the example below:
 
 
 ```{zig}
-#| eval: false
+#| auto_main: true
+#| build_type: "ast"
+const name = "Pedro";
 for (name, 0..) |_, i| {
     try stdout.print("{d} | ", .{i});
 }
@@ -626,6 +630,8 @@ immutable (i.e. constant) object".
 
 ```{zig}
 #| eval: false
+#| auto_main: false
+#| build_type: "lib"
 const std = @import("std");
 fn add2(x: u32) u32 {
     x = x + 2;
@@ -922,6 +928,8 @@ while the `other` argument corresponds to the object `v2`.
 
 ```{zig}
 #| eval: false
+#| auto_main: true
+#| build_type: "ast"
 const v1 = Vec3 {
     .x = 4.2, .y = 2.4, .z = 0.9
 };
diff --git a/Chapters/13-image-filter.qmd b/Chapters/13-image-filter.qmd
index edc75093..13037aab 100644
--- a/Chapters/13-image-filter.qmd
+++ b/Chapters/13-image-filter.qmd
@@ -522,7 +522,7 @@ fn apply_image_filter(buffer:[]u8) !void {
     const green_factor: f16 = 0.7152;
     const blue_factor: f16 = 0.0722;
     var index: u64 = 0;
-    while (index < (len - 4)) : (index += 4) {
+    while (index <= (len - 4)) : (index += 4) {
         const rf: f16 = @floatFromInt(buffer[index]);
         const gf: f16 = @floatFromInt(buffer[index + 1]);
         const bf: f16 = @floatFromInt(buffer[index + 2]);
diff --git a/ZigExamples/image_filter/pedro_pascal_filter.png b/ZigExamples/image_filter/pedro_pascal_filter.png
index bdce0380b5c0f138546e189851262424517f1c54..45bf4ed35f67ccb92ca00e2d7aedbf290dc9d82e 100644
GIT binary patch
delta 45
zcmaE|gX`fAu7(!IEleVfj27EP8<|X{#kv3UJ4AX5bUJP3U;qM7S3j3^P6<r_WvmVk

delta 48
zcmaF3gX_r-u7(!IEleVfjMm#l8<|X{rI;svH2Y)k+~lLEl_C0q0SG)@{an^LB{Ts5
Dtq%}5

diff --git a/ZigExamples/image_filter/src/image_filter.zig b/ZigExamples/image_filter/src/image_filter.zig
index f6d237ab..95a2575e 100644
--- a/ZigExamples/image_filter/src/image_filter.zig
+++ b/ZigExamples/image_filter/src/image_filter.zig
@@ -103,7 +103,7 @@ fn apply_image_filter(image_data: *ImageData) !void {
     const green_factor: f16 = 0.7152;
     const blue_factor: f16 = 0.0722;
     var index: u64 = 0;
-    while (index < (len - 4)) : (index += 4) {
+    while (index <= (len - 4)) : (index += 4) {
         const rf: f16 = @floatFromInt(image_data.data[index]);
         const gf: f16 = @floatFromInt(image_data.data[index + 1]);
         const bf: f16 = @floatFromInt(image_data.data[index + 2]);
diff --git a/ZigExamples/zig-basics/string_replace.zig b/ZigExamples/zig-basics/string_replace.zig
new file mode 100644
index 00000000..884dc40b
--- /dev/null
+++ b/ZigExamples/zig-basics/string_replace.zig
@@ -0,0 +1,10 @@
+const std = @import("std");
+const stdout = std.io.getStdOut().writer();
+
+pub fn main() !void {
+    const str1 = "Hello";
+    var buffer: [5]u8 = undefined;
+    const nrep = std.mem.replace(u8, str1, "el", "34", buffer[0..]);
+    try stdout.print("New string: {s}\n", .{buffer});
+    try stdout.print("N of replacements: {d}\n", .{nrep});
+}
diff --git a/_freeze/Chapters/01-base64/execute-results/html.json b/_freeze/Chapters/01-base64/execute-results/html.json
index 2849f469..74060eb2 100644
--- a/_freeze/Chapters/01-base64/execute-results/html.json
+++ b/_freeze/Chapters/01-base64/execute-results/html.json
@@ -3,9 +3,7 @@
   "result": {
     "engine": "knitr",
     "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 1 - Building a base64 encoder/decoder {#sec-base64}\n\nAs our first small project, I want to implement a base64 encoder/decoder with you.\nBase64 is an encoding system which translates binary data to text.\nA big chunk of the web uses base64 to deliver binary data to systems\nthat can only read text data.\n\nThe most common example of a modern use case for base64 is essentially any email system,\nlike GMail, Outlook, etc. Because email systems normally use\nthe Simple Mail Transfer Protocol (SMTP), which is a web protocol\nthat supports only text data. So, if you need, for any reason, to\nsend a binary file (like for example, a PDF, or an Excel file) as\nan attachment in your email, these binary files are normally\nconverted to base64, before they are included in the SMTP message.\nSo, the base64 encoding is largely used in these email systems to include\nbinary data into the SMTP message.\n\n\n\n\n\n\n## How the base64 algorithm work?\n\nBut how exactly does the algorithm behind the base64 encoding work? Let's discuss that. First, I will\nexplain the base64 scale, which is the 64-character scale that is the basis for\nthe base64 encoding system.\n\nAfter that, I explain the algorithm behind a base64 encoder, which is the part of the algorithm that is responsible for encoding messages\ninto the base64 encoding system. Then, after that, I explain the algorithm behind a base64 decoder, which is\nthe part of the algorithm that is responsible for translating base64 messages back into their original meaning.\n\nIf you are unsure about the differences between an \"encoder\" and a \"decoder\",\ntake a look at @sec-encode-vs-decode.\n\n\n### The base64 scale {#sec-base64-scale}\n\nThe base64 encoding system is based on a scale that goes from 0 to 63 (hence the name).\nEach index in this scale is represented by a character (it is a scale of 64 characters).\nSo, in order to convert some binary data, to the base64 encoding, we need to convert each binary number to the corresponding\ncharacter in this \"scale of 64 characters\".\n\nThe base64 scale starts with all ASCII uppercase letters (A to Z) which represents\nthe first 25 indexes in this scale (0 to 25). After that, we have all ASCII lowercase letters\n(a to z), which represents the range 26 to 51 in the scale. After that, we\nhave the one digit numbers (0 to 9), which represents the indexes from 52 to 61 in the scale.\nFinally, the last two indexes in the scale (62 and 63) are represented by the characters `+` and `/`,\nrespectively.\n\nThese are the 64 characters that compose the base64 scale. The equal sign character (`=`) is not part of the scale itself,\nbut it is a special character in the base64 encoding system. This character is used solely as a suffix, to mark the end of the character sequence,\nor, to mark the end of meaningful characters in the sequence.\n\nThe bullet points below summarises the base64 scale:\n\n- range 0 to 25 is represented by: ASCII uppercase letters `-> [A-Z]`;\n- range 26 to 51 is represented by: ASCII lowercase letters `-> [a-z]`;\n- range 52 to 61 is represented by: one digit numbers `-> [0-9]`;\n- index 62 and 63 are represented by the characters `+` and `/`, respectively;\n- the character `=` represents the end of meaningful characters in the sequence;\n\n\n\n\n### Creating the scale as a lookup table {#sec-base64-table}\n\nThe best way to represent this scale in code, is to represent it as a *lookup table*.\nLookup tables are a classic strategy in computer science to speed up calculations. The basic idea\nis to replace a runtime calculation (which can take a long time to be done) with a basic array indexing\noperation.\n\nInstead of calculating the results everytime you need them, you calculate all possible results at once, and then, you store them in an array\n(which behaves lake a \"table\"). Then, every time you need to use one of the characters in the base64 scale, instead of\nusing many resources to calculate the exact character to be used, you simply retrieve this character\nfrom the array where you stored all the possible characters in the base64 scale.\nWe retrieve the character that we need directly from memory.\n\nWe can start building a Zig struct to store our base64 decoder/encoder logic.\nWe start with the `Base64` struct below. For now, we only have one single data member in this\nstruct, i.e. the member `_table`, which represents our lookup table. We also have an `init()` method,\nto create a new instance of a `Base64` object, and, a `_char_at()` method, which is a\n\"get character at index $x$\" type of function.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Base64 = struct {\n    _table: *const [64]u8,\n\n    pub fn init() Base64 {\n        const upper = \"ABCDEFGHIJKLMNOPQRSTUVWXYZ\";\n        const lower = \"abcdefghijklmnopqrstuvwxyz\";\n        const numbers_symb = \"0123456789+/\";\n        return Base64{\n            ._table = upper ++ lower ++ numbers_symb,\n        };\n    }\n\n    pub fn _char_at(self: Base64, index: u8) u8 {\n        return self._table[index];\n    }\n};\n```\n:::\n\n\n\n\n\nIn other words, the `_char_at()` method is responsible for getting the character in the lookup\ntable (i.e. the `_table` struct data member) that corresponds to a particular index in the\n\"base64 scale\". So, in the example below, we know that the character that corresponds to the\nindex 28 in the \"base64 scale\" is the character \"c\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst base64 = Base64.init();\ntry stdout.print(\n    \"Character at index 28: {c}\\n\",\n    .{base64._char_at(28)}\n);\n```\n:::\n\n\n\n\n```\nCharacter at index 28: c\n```\n\n\n\n### A base64 encoder {#sec-base64-encoder-algo}\n\nThe algorithm behind a base64 encoder usually works on a window of 3 bytes. Because each byte has\n8 bits, so, 3 bytes forms a set of $8 \\times 3 = 24$ bits. This is desirable for the base64 algorithm, because\n24 bits is divisible by 6, which forms $24 / 6 = 4$ groups of 6 bits each.\n\nTherefore, the base64 algorithm works by converting 3 bytes at a time\ninto 4 characters from the base64 scale. It keeps iterating through the input string,\n3 bytes at a time, and converting them into the base64 scale, producing 4 characters\nper iteration. It keeps iterating, and producing these \"new characters\"\nuntil it hits the end of the input string.\n\nNow, you may think, what if you have a particular string that have a number of bytes\nthat is not divisible by 3? What happens? For example, if you have a string\nthat contains only two characters/bytes, such as \"Hi\". How the\nalgorithm would behave in such situation? You find the answer at @fig-base64-algo1.\nYou can see at @fig-base64-algo1 that the string \"Hi\", when converted to base64,\nbecomes the string \"SGk=\":\n\n![The logic behind a base64 encoder](./../Figures/base64-encoder-flow.png){#fig-base64-algo1}\n\nTaking the string \"Hi\" as an example, we have 2 bytes, or, 16 bits in total. So, we lack a full byte (8 bits)\nto complete the window of 24 bits that the base64 algorithm likes to work on. The first thing that\nthe algorithm does, is to check how to divide the input bytes into groups of 6 bits.\n\nIf the algorithm notices that there is a group of 6 bits that, have some bits in it, but, at the same time, it is not full\n(in other words, $0 < nbits < 6$, being $nbits$ the number of bits), meaning that, it lacks\nsome bits to fill the 6-bits requirement, the algorithm simply add extra zeros in this group\nto fill the space that it needs. That is why at @fig-base64-algo1, on the third group after the 6-bit transformation,\n2 extra zeros were added to fill the gap in this group.\n\nWhen we have a 6-bit group that is not completely full, like the third group, extra zeros\nare added to fill the gap. But what about when an entire 6-bit group is empty, or, it \nsimply doesn't exist? This is the case of the fourth 6-bit group exposed at\n@fig-base64-algo1.\n\nThis fourth group is necessary, because the algorithm works on 4 groups of 6 bits.\nBut the input string does not have enough bytes to create a fourth 6-bit group.\nEvery time this happens, where an entire group of 6 bits is empty,\nthis group becomes a \"padding group\". Every \"padding group\" is mapped to\nthe character `=` (equal sign), which represents \"null\", or, the end\nof meaningful characters in the sequence. Hence, everytime that the algorithm produces a\n\"padding group\", this group is automatically mapped to `=`.\n\nAs another example, if you give the string \"0\" as input to a base64 encoder, this string is\ntranslated into the base64 sequence \"MA==\".\nThe character \"0\" is, in binary, the sequence `00110000`[^zero-note]. So, with the 6-bit transformation\nexposed at @fig-base64-algo1, this single character would produce these two 6-bit groups: `001100`, `000000`.\nThe remaining two 6-bit groups become \"padding groups\". That is why the last\ntwo characters in the output sequence (MA==) are `==`.\n\n\n[^zero-note]: Notice that, the character \"0\" is different than the actual number 0, which is simply zero in binary.\n\n### A base64 decoder {#sec-base64-decoder-algo}\n\nThe algorithm behind a base64 decoder is essentially the inverse process of a base64 encoder.\nA base64 decoder needs to translate base64 messages back into their original meaning,\ni.e. into the original sequence of binary data.\n\nA base64 decoder usually works on a window of 4 bytes. Because it wants to convert these 4 bytes\nback into the original sequence of 3 bytes, that was converted into 4 groups of 6 bits by the\nbase64 encoder. Remember, in a base64 decoder we are essentially reverting the process made\nby the base64 encoder.\n\nEach byte in the input string (the base64 encoded string) normally contributes to re-create\ntwo different bytes in the output (the original binary data).\nIn other words, each byte that comes out of a base64 decoder is created by transforming merging two different\nbytes in the input together. You can visualize this relationship at @fig-base64-algo2:\n\n![The logic behind a base64 decoder](./../Figures/base64-decoder-flow.png){#fig-base64-algo2}\n\nThe exact transformations, or, the exact steps applied to each byte from the input to transform them\ninto the bytes of the output, are a bit tricky to visualize in a figure like this. Because of that, I have\nsummarized these transformations as \"Some bit shifting and additions ...\" in the figure. These transformations\nwill be described in depth later.\n\nBesides that, if you look again at @fig-base64-algo2, you will notice that the character `=` was completely\nignored by the algorithm. Remember, this is just a special character that marks the end of meaningful characters\nin the base64 sequence. So, every `=` character in a base64 encoded sequence should be ignored by a base64 decoder.\n\n\n## Difference between encode and decode {#sec-encode-vs-decode}\n\nIf you don't have any previous experience with base64, you might not understand the differences\nbetween \"encode\" and \"decode\". Essentially, the terms \"encode\" and \"decode\" here\nhave the exact same meaning as they have in the field of encryption (i.e. they mean the same thing as \"encode\" and \"decode\" in hashing\nalgorithms, like the MD5 algorithm).\n\nThus, \"encode\" means that we want to encode, or, in other words, we want to translate some message into\nthe base64 encoding system. We want to produce the sequence of base64 characters that represent this\noriginal message in the base64 encoding system.\n\nIn contrast, \"decode\" represents the inverse process.\nWe want to decode, or, in other words, translate a base64 message back to its original content.\nSo, in this process we get a sequence of base64 characters as input, and produce as output,\nthe binary data that is represented by this sequence of base64 characters.\n\nAny base64 library is normally composed of these two parts: 1) the encoder, which is a function that encodes\n(i.e. it converts) any sequence of binary data into a sequence of base64 characters; 2) the decoder, which is a function\nthat converts a sequence of base64 characters back into the original sequence of binary data.\n\n\n\n## Calculating the size of the output {#sec-base64-length-out}\n\nOne task that we need to do is to calculate how much space we need to reserve for the\noutput, both of the encoder and decoder. This is simple math, and can be done easily in Zig\nbecause every array has its length (its number of elements) easily accesible by consulting\nthe `.len` property of the array.\n\nFor the encoder, the logic is the following: for each 3 bytes that we find in the input,\n4 new bytes are created in the output. So, we take the number of bytes in the input, divide it\nby 3, use a ceiling function, then, we multiply the result by 4. That way, we get the total\nnumber of bytes that will be produced by the encoder in its output.\n\nThe `_calc_encode_length()` function below encapsulates this logic.\nInside this function, we take the length of the input array,\nwe divide it by 3, and apply a ceil operation over the result by using the\n`divCeil()` function from the Zig Standard Library. Lastly, we multiply\nthe end result by 4 to get the answer we need.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_encode_length(input: []const u8) !usize {\n    if (input.len < 3) {\n        const n_output: usize = 4;\n        return n_output;\n    }\n    const n_output: usize = try std.math.divCeil(\n        usize, input.len, 3\n    );\n    return n_output * 4;\n}\n```\n:::\n\n\n\n\n\nAlso, you might have notice that, if the input length is less than 3 bytes, then, the output length of the encoder is\nalways 4 bytes. This is the case for every input with less than 3 bytes, because, as I described at @sec-base64-encoder-algo,\nthe algorithm always produces enough \"padding-groups\" in the end result, to complete the 4 bytes window.\n\nNow, for the decoder, we just need to apply the inverse logic: for each 4 bytes in the input, 3 bytes\nwill be produced in the output of the decoder. I mean, this is roughly true, because we also need to\ntake the `=` character into account, which is always ignored by the decoder, as we described at @sec-base64-decoder-algo, and,\nat @fig-base64-algo2. But we can ignore this fact for now, just to keep things simple.\n\nThe function `_calc_decode_length()` exposed below summarizes this logic that we described. It is very similar\nto the function `_calc_encode_length()`. Only the division part is twisted, and also, in the special\ncase where we have less than 4 bytes in the input to work on. Also notice that this time, we apply\na floor operation over the output of the division, by using the `divFloor()`\nfunction (instead of a ceiling operation with `divCeil()`).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_decode_length(input: []const u8) !usize {\n    if (input.len < 4) {\n        const n_output: usize = 3;\n        return n_output;\n    }\n    const n_output: usize = try std.math.divFloor(\n        usize, input.len, 4\n    );\n    return n_output * 3;\n}\n```\n:::\n\n\n\n\n\n## Building the encoder logic {#sec-encoder-logic}\n\nIn this section, we can start building the logic behind the `encode()` function, which\nwill be responsible for encoding messages into the base64 encoding system.\nIf you are an anxious person, and you want to see now the full source code of the implementation\nfor this base64 encoder/decoder, you can find it at the `ZigExamples` folder in the official repository of\nthis book[^zig-base64-algo].\n\n[^zig-base64-algo]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/base64/base64_basic.zig>.\n\n\n\n### The 6-bit transformation {#sec-6bit-transf}\n\nThe 6-bit transformation presented at @fig-base64-algo1 is the core part of the base64 encoder algorithm.\nBy understanding how this transformation is made in code, the rest of the algorithm becomes much simpler\nto comprehend.\n\nIn essence, this 6-bit transformation is made with the help of bitwise operators.\nBitwise operators are essential to any type of low-level operation that is done at the bit-level. For the specific case of the base64 algorithm,\nthe operators *bif shift to the left* (`<<`), *bit shift to the right* (`>>`), and the *bitwise and* (`&`) are used. They\nare the core solution for the 6-bit transformation.\n\nThere are 3 different scenarios that we need to take into account in this transformation. First, is the perfect scenario,\nwhere we have the perfect window of 3 bytes to work on. Second, we have the scenario where we have a window of only\ntwo bytes to work with. And last, we have the scenario where we have a window of one single byte.\n\nIn each of these 3 scenarios, the 6-bit transformation works a bit differently. To make the explanation\neasier, I will use the variable `output` to refer to the bytes in the output of the base64 encoder,\nand the variable `input` to refer to the bytes in the input of the encoder.\n\n\nSo, if you have the perfect window of 3 bytes, these are steps for the 6-bit transformation:\n\n1. `output[0]` is produced by moving the bits from `input[0]` two positions to the right.\n1. `output[1]` is produced by summing two components. First, take the last two bits from `input[0]`, then, move them four positions to the left. Second, move the bits from `input[1]` four positions to the right. Sum these two components.\n1. `output[2]` is produced by summing two components. First, take the last four bits from `input[1]`, then, move them two positions to the left. Second, move the bits from `input[2]` six positions to the right. Sum these two components.\n1. `output[3]` is produced by taking the last six bits from `input[2]`.\n\n\nThis is the perfect scenario, where we have a full window of 3 bytes to work on.\nJust to make things as clear as possible, the @fig-encoder-bitshift demonstrates visually how\nthe step 2 mentioned above works. So the 2nd byte in the `output` of the encoder, is made by taking the 1st byte (dark purple)\nand the 2nd byte (orange) from the input. You can see that, at the end of the process, we get a new\nbyte that contains the last 2 bits from the 1st byte in the `input`, and the first 4 bits\nfrom the 2nd byte in the `input`.\n\n![How the 2nd byte in the output of the encoder is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input.](../Figures/base64-encoder-bit-shift.png){#fig-encoder-bitshift}\n\nOn the other hand, we must be prepared for the instances where we do not have the perfect window of 3 bytes.\nIf you have a window of 2 bytes, then, the steps 3 and 4, which produces the bytes `output[2]` and `output[3]`, change a little bit,\nand they become:\n\n- `output[2]` is produced by taking the last 4 bits from `input[1]`, then, move them two positions to the left.\n- `output[3]` is the character `'='`.\n\n\nFinally, if you have a window of a single byte, then, the steps 2 to 4, which produces the bytes `output[1]`, `output[2]` and `output[3]` change,\nbecoming:\n\n- `output[1]` is produced by taking the last two bits from `input[0]`, then, move them four positions to the left.\n- `output[2]` and `output[3]` are the character `=`.\n\n\nIf these bullet points were a bit confusing for you, you may find the @tbl-transf-6bit more intuitive.\nThis table unifies all this logic into a simple table. Notice that\nthis table also provides the exact expression in Zig that creates the corresponding\nbyte in the output.\n\n\n::: {#tbl-transf-6bit}\n\n| Number of bytes in the window | Byte index in the output | In code                                    |\n|-------------------------------|--------------------------|--------------------------------------------|\n| 3                             | 0                        | input[0] >> 2                              |\n| 3                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 3                             | 2                        | ((input[1] & 0x0f) << 2) + (input[2] >> 6) |\n| 3                             | 3                        | input[2] & 0x3f                            |\n| 2                             | 0                        | input[0] >> 2                              |\n| 2                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 2                             | 2                        | ((input[1] & 0x0f) << 2)                   |\n| 2                             | 3                        | '='                                        |\n| 1                             | 0                        | input[0] >> 2                              |\n| 1                             | 1                        | ((input[0] & 0x03) << 4)                   |\n| 1                             | 2                        | '='                                        |\n| 1                             | 3                        | '='                                        |\n\n: How the 6-bit transformation translates into code in different window settings.\n\n:::\n\n\n\n\n\n\n### Bit-shifting in Zig\n\nBit-shifting in Zig works similarly to bit-shifting in C.\nAll bitwise operators that exist in C are available in Zig.\nHere, in the base64 encoder algorithm, they are essential\nto produce the result we want.\n\nFor those who are not familiar with these operators, they are\noperators that operates at the bit-level of your values.\nThis means that these operators takes the bits that form the value\nyou have, and change them in some way. This ultimately also changes\nthe value itself, because the binary representation of this value\nchanges.\n\nWe have already seen at @fig-encoder-bitshift the effect produced by a bit-shift.\nBut let's use the first byte in the output of the base64 encoder as another example of what\nbit-shifting means. This is the easiest byte of the 4 bytes in the output\nto build. Because we only need to move the bits from the first byte in the input two positions to the right,\nwith the *bit shift to the right* (`>>`) operator.\n\nIf we take the string \"Hi\" that we used at @fig-base64-algo1 as an example, the first byte in\nthis string is \"H\", which is the sequence `01001000` in binary.\nIf we move the bits of this byte, two places to the right, we get the sequence `00010010` as result.\nThis binary sequence is the value `18` in decimal, and also, the value `0x12` in hexadecimal.\nNotice that the first 6 bits of \"H\" were moved to the end of the byte.\nWith this operation, we get the first byte of the output.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const input = \"Hi\";\n    try stdout.print(\"{d}\\n\", .{input[0] >> 2});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n18\n```\n\n\n:::\n:::\n\n\n\n\nIf you recall @fig-base64-algo1, the first byte present in the output should\nbe equivalent to the 6-bit group `010010`. Although being visually different, the\nsequences `010010` and `00010010` are semantically equal. They mean the same thing.\nThey both represent the number 18 in decimal, and the value `0x12` in hexadecimal.\n\nSo, don't take the \"6-bit group\" factor so seriously. We do not need necessarily to\nget a 6-bit sequence as result. As long as the meaning of the 8-bit sequence we get is the same\nof the 6-bit sequence, we are in the clear.\n\n\n\n### Selecting specific bits with the `&` operator\n\nIf you comeback to @sec-6bit-transf, you will see that, in order to produce\nthe second and third bytes in the output, we need to select specific\nbits from the first and second bytes in the input string. But how\ncan we do that? The answer relies on the *bitwise and* (`&`) operator.\n\nThe @fig-encoder-bitshift already showed you what effect this `&` operator\nproduces in the bits of its operands. But let's make a clear description of it.\n\nIn summary, the `&` operator performs a logical conjunction operation\nbetween the bits of its operands. In more details, the operator `&`\ncompares each bit of the first operand to the corresponding bit of the second operand.\nIf both bits are 1, the corresponding result bit is set to 1.\nOtherwise, the corresponding result bit is set to 0 [@microsoftbitwiseand].\n\nSo, if we apply this operator to the binary sequences `1000100` and `00001101`\nthe result of this operation is the binary sequence `00000100`. Because only\nat the sixth position in both binary sequences we had a 1 value. So any\nposition where we do not have both binary sequences setted to 1, we get\na 0 bit in the resulting binary sequence.\n\nWe lose information about the original bit values\nfrom both sequences in this case. Because we no longer know\nif this 0 bit in the resulting binary sequence was produced by\ncombining 0 with 0, or 1 with 0, or 0 with 1.\n\nAs an example, suppose you have the binary sequence `10010111`, which is the number 151 in decimal. How\ncan we get a new binary sequence which contains only the third and\nfourth bits of this sequence?\n\nWe just need to combine this sequence with `00110000` (is `0x30` in hexadecimal) using the `&` operator.\nNotice that only the third and fourth positions in this binary sequence is setted to 1. As a consequence, only the\nthird and fourth values of both binary sequences are potentially preserved in the output. All the remaining positions\nare setted to zero in the output sequence, which is `00010000` (is the number 16 in decimal).\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const bits = 0b10010111;\n    try stdout.print(\"{d}\\n\", .{bits & 0b00110000});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n16\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Allocating space for the output\n\nAs I described at @sec-stack, to store an object in the stack,\nthis object needs to have a known and fixed length at compile-time. This is an important\nlimitation for our base64 encoder/decoder case. Because the size of\nthe output (from both the encoder and decoder) depends\ndirectly on the size of the input.\n\nHaving this in mind, we cannot know at compile time which is\nthe size of the output for both the encoder and decoder.\nSo, if we can't know the size of the output at compile time,\nthis means that we cannot store the output for both the encoder\nand decoder in the stack.\n\nConsequently, we need to store this output on the heap,\nand, as I commented at @sec-heap, we can only\nstore objects in the heap by using allocator objects.\nSo, one the arguments to both the `encode()` and `decode()`\nfunctions, needs to be an allocator object, because\nwe know for sure that, at some point inside the body of these\nfunctions, we need to allocate space on the heap to\nstore the output of these functions.\n\nThat is why, both the `encode()` and `decode()` functions that I\npresent in this book, have an argument called `allocator`,\nwhich receives a allocator object as input, identified by\nthe type `std.mem.Allocator` from the Zig Standard Library.\n\n\n\n### Writing the `encode()` function\n\nNow that we have a basic understanding on how the bitwise operators work, and how\nexactly they help us to achieve the result we want to achieve. We can now encapsulate\nall the logic that we have described at @fig-base64-algo1 and @tbl-transf-6bit into a nice\nfunction that we can add to our `Base64` struct definition, that we started at @sec-base64-table.\n\nYou can find the `encode()` function below. Notice that the first argument of this function,\nis the `Base64` struct itself. Therefore, this argument clearly signals\nthat this function is a method from the `Base64` struct.\n\nBecause the `encode()` function itself is fairly long,\nI intentionally omitted the `Base64` struct definition in this source code,\njust for brevity reasons. So, just remember that this function is a public function (or a public method) from the\n`Base64` struct.\n\nFurthermore, this `encode()` function has two other arguments:\n\n1. `input` is the input sequence of characters that you want to encode in base64;\n1. `allocator` is an allocator object to use in the necessary memory allocations.\n\nI described everything you need to know about allocator objects at @sec-allocators.\nSo, if you are not familiar with them, I highly recommend you to comeback to\nthat section, and read it.\nBy looking at the `encode()` function, you will see that we use this\nallocator object to allocate enough memory to store the output of\nthe encoding process.\n\nThe main for loop in the function is responsible for iterating through the entire input string.\nIn every iteration, we use a `count` variable to count how many iterations we had at the\nmoment. When `count` reaches 3, then, we try to encode the 3 characters (or bytes) that we have accumulated\nin the temporary buffer object (`buf`).\n\nAfter encoding these 3 characters and storing the result in the `output` variable, we reset\nthe `count` variable to zero, and start to count again on the next iteration of the loop.\nIf the loop hits the end of the string, and, the `count` variable is less than 3, then, it means that\nthe temporary buffer contains the last 1 or 2 bytes from the input.\nThat is why we have two `if` statements after the for loop. To deal which each possible case.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn encode(self: Base64,\n              allocator: std.mem.Allocator,\n              input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n\n    const n_out = try _calc_encode_length(input);\n    var out = try allocator.alloc(u8, n_out);\n    var buf = [3]u8{ 0, 0, 0 };\n    var count: u8 = 0;\n    var iout: u64 = 0;\n\n    for (input, 0..) |_, i| {\n        buf[count] = input[i];\n        count += 1;\n        if (count == 3) {\n            out[iout] = self._char_at(buf[0] >> 2);\n            out[iout + 1] = self._char_at(\n                ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n            );\n            out[iout + 2] = self._char_at(\n                ((buf[1] & 0x0f) << 2) + (buf[2] >> 6)\n            );\n            out[iout + 3] = self._char_at(buf[2] & 0x3f);\n            iout += 4;\n            count = 0;\n        }\n    }\n\n    if (count == 1) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            (buf[0] & 0x03) << 4\n        );\n        out[iout + 2] = '=';\n        out[iout + 3] = '=';\n    }\n\n    if (count == 2) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n        );\n        out[iout + 2] = self._char_at(\n            (buf[1] & 0x0f) << 2\n        );\n        out[iout + 3] = '=';\n        iout += 4;\n    }\n\n    return out;\n}\n```\n:::\n\n\n\n\n\n\n## Building the decoder logic {#sec-decoder-logic}\n\nNow, we can focus on writing the base64 decoder logic. Remember from @fig-base64-algo2 that,\na base64 decoder does the inverse process of an encoder. So, all we need to do, is to\nwrite a `decode()` function that performs the inverse process that I exposed at @sec-encoder-logic.\n\n\n### Mapping base64 characters to their indexes {#sec-map-base64-index}\n\nOne thing that we need to do, in order to decode a base64-encoded message, is to calculate\nthe index in the base64 scale of every base64 character that we encounter in the decoder input.\n\nIn other words, the decoder receives as input, a sequence of base64 characters. We need\nto translate this sequence of characters into a sequence of indexes. These indexes\nare the index of each character in the base64 scale. This way, we get the value/byte\nthat was calculated in the 6-bit transformation step of the encoder process.\n\nThere are probably better/faster ways to calculate this, especially using a \"divide and conquer\"\ntype of strategy. But for now, I am satisfied with a simple and \"brute force\" type of strategy.\nThe `_char_index()` function below contains this strategy.\n\nWe are essentially looping through the *lookup table* with the base64 scale,\nand comparing the character we got with each character in the base64 scale.\nIf these characters match, then, we return the index of this character in the\nbase64 scale as the result.\n\nNotice that, if the input character is `'='`, the function returns the index 64, which is\n\"out of range\" in the scale. But, as I described at @sec-base64-scale,\nthe character `'='` does not belong to the base64 scale itself.\nIt is a special and meaningless character in base64.\n\nAlso notice that this `_char_index()` function is a method from our `Base64` struct,\nbecause of the `self` argument. Again, I have omitted the `Base64` struct definition in this example\nfor brevity reasons.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn _char_index(self: Base64, char: u8) u8 {\n    if (char == '=')\n        return 64;\n    var index: u8 = 0;\n    for (0..63) |i| {\n        if (self._char_at(i) == char) {\n            index = i;\n            break;\n        }\n    }\n\n    return index;\n}\n```\n:::\n\n\n\n\n\n\n### The 6-bit transformation\n\nOnce again, the core part of the algorithm is the 6-bit transformation.\nIf we understand the necessary steps to perform this transformation, the rest\nof the algorithm becomes much easier.\n\nFirst of all, before we actually go to the 6-bit transformation,\nwe need to make sure that we use `_char_index()` to convert the sequence of base64 characters\ninto a sequence of indexes. So the snippet below is important for the job that will be done.\nThe result of `_char_index()` is stored in a temporary buffer, and this temporary buffer\nis what we are going to use in the 6-bit transformation, instead of the actual `input` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (0..input.len) |i| {\n    buf[i] = self._char_index(input[i]);\n}\n```\n:::\n\n\n\n\nNow, instead of producing 4 bytes (or 4 characters) as output per each window of 3 characters in the input,\na base64 decoder produces 3 bytes (or 3 characters) as output per each window of 4 characters in the input.\nOnce again, is the inverse process.\n\nSo, the steps to produce the 3 bytes in the output are:\n\n1. `output[0]` is produced by summing two components. First, move the bits from `buf[0]` two positions to the left. Second, move the bits from `buf[1]` 4 positions to the right. Then, sum these two components.\n1. `output[1]` is produced by summing two components. First, move the bits from `buf[1]` four positions to the left. Second, move the bits from `buf[2]` 2 positions to the right. Then, sum these two components.\n1. `output[2]` is produced by summing two components. First, move the bits from `buf[2]` six positions to the left. Then, you sum the result with `buf[3]`.\n\n\nBefore we continue, let's try to visualize how these transformations make the original bytes that we had\nbefore the encoding process. First, think back to the 6-bit transformation performed by the encoder exposed at @sec-encoder-logic.\nThe first byte in the output of the encoder is produced by moving the bits in the first byte of the input two positions to the right.\n\nIf for example the first byte in the input of the encoder was the sequence `ABCDEFGH`, then, the first byte in the output of the encoder would be\n`00ABCDEF` (this sequence would be the first byte in the input of the decoder). Now, if the second byte in the input of the encoder was the sequence\n`IJKLMNOP`, then, the second byte in the encoder output would be `00GHIJKL` (as we demonstrated at @fig-encoder-bitshift).\n\nHence, if the sequences `00ABCDEF` and `00GHIJKL` are the first and second bytes, respectively, in the input of the decoder, the\n@fig-decoder-bitshift demonstrates visually how these two bytes are transformed into the first byte of the output of the decoder.\nNotice that the output byte is the sequence `ABCDEFGH`, which is the original byte from the input of the encoder.\n\n![How the 1st byte in the decoder output is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input](../Figures/base64-decoder-bit-shift.png){#fig-decoder-bitshift}\n\nThe @tbl-6bit-decode presents how the three steps described earlier translate into Zig code:\n\n\n\n::: {#tbl-6bit-decode}\n\n| Byte index in the output | In code                       |\n|--------------------------|-------------------------------|\n| 0                        | (buf[0] << 2) + (buf[1] >> 4) |\n| 1                        | (buf[1] << 4) + (buf[2] >> 2) |\n| 2                        | (buf[2] << 6) + buf[3]        |\n\n: The necessary steps for the 6-transformation in the decode process.\n\n\n:::\n\n\n\n\n\n\n\n### Writing the `decode()` function\n\nThe `decode()` function below contains the entire decoding process.\nWe first calculate the size of the output, with\n`_calc_decode_length()`, then, we allocate enough memory for this output with\nthe allocator object.\n\nThree temporary variables are created: 1) `count`, to hold the window count\nin each iteration of the for loop; 2) `iout`, to hold the current index in the output;\n3) `buf`, which is the temporary buffer that holds the base64 indexes to be\nconverted through the 6-bit transformation.\n\nThen, in each iteration of the for loop we fill the temporary buffer with the current\nwindow of bytes. When `count` hits the number 4, then, we have a full window of\nindexes in `buf` to be converted, and then, we apply the 6-bit transformation\nover the temporary buffer.\n\nNotice that we check if the indexes 2 and 3 in the temporary buffer are the number 64, which, if you recall\nfrom @sec-map-base64-index, is when the `_calc_index()` function receives a `'='` character\nas input. So, if these indexes are equal to the number 64, the `decode()` function knows\nthat it can simply ignore these indexes. They are not converted because, as I described before,\nthe character `'='` has no meaning, despite being the end of meaningful characters in the sequence.\nSo we can safely ignore them when they appear in the sequence.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn decode(self: Base64,\n          allocator: std.mem.Allocator,\n          input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n    const n_output = try _calc_decode_length(input);\n    var output = try allocator.alloc(u8, n_output);\n    var count: u8 = 0;\n    var iout: u64 = 0;\n    var buf = [4]u8{ 0, 0, 0, 0 };\n\n    for (0..input.len) |i| {\n        buf[count] = self._char_index(input[i]);\n        count += 1;\n        if (count == 4) {\n            output[iout] = (buf[0] << 2) + (buf[1] >> 4);\n            if (buf[2] != 64) {\n                output[iout + 1] = (buf[1] << 4) + (buf[2] >> 2);\n            }\n            if (buf[3] != 64) {\n                output[iout + 2] = (buf[2] << 6) + buf[3];\n            }\n            iout += 3;\n            count = 0;\n        }\n    }\n\n    return output;\n}\n```\n:::\n\n\n\n\n\n## The end result\n\nNow that we have both `decode()` and `encode()` implemented. We have a fully functioning\nbase64 encoder/decoder implemented in Zig. Here is an usage example of our\n`Base64` struct with the `encode()` and `decode()` methods that we have implemented.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar memory_buffer: [1000]u8 = undefined;\nvar fba = std.heap.FixedBufferAllocator.init(\n    &memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst text = \"Testing some more shit\";\nconst etext = \"VGVzdGluZyBzb21lIG1vcmUgc2hpdA==\";\nconst base64 = Base64.init();\nconst encoded_text = try base64.encode(\n    allocator, text\n);\nconst decoded_text = try base64.decode(\n    allocator, etext\n);\ntry stdout.print(\n    \"Encoded text: {s}\\n\", .{encoded_text}\n);\ntry stdout.print(\n    \"Decoded text: {s}\\n\", .{decoded_text}\n);\n```\n:::\n\n\n\n\n```\nEncoded text: VGVzdGluZyBzb21lIG1vcmUgc2hpdA==\nDecoded text: Testing some more shit\n```\n\nYou can also see the full source code at once, by visiting the official repository of this book[^repo].\nMore precisely inside the `ZigExamples` folder[^zig-base64-algo].\n\n[^repo]: <https://github.com/pedropark99/zig-book>\n",
-    "supporting": [
-      "01-base64_files"
-    ],
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/01-memory/execute-results/html.json b/_freeze/Chapters/01-memory/execute-results/html.json
index bd757ea4..29ccbc27 100644
--- a/_freeze/Chapters/01-memory/execute-results/html.json
+++ b/_freeze/Chapters/01-memory/execute-results/html.json
@@ -1,8 +1,8 @@
 {
-  "hash": "d1d879f29390bf8c35a2e71736e05d45",
+  "hash": "0a086161bb0eedee4b92cc3e013bd2f2",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Memory and Allocators\n\n\nIn this chapter, we will talk about memory. How does Zig control memory? What\ncommon tools are used? Are there any important aspects that make memory\ndifferent/special in Zig? You will find the answers here.\n\nComputers fundamentally rely on memory to function. This memory acts as a temporary storage\nspace for the data and values generated during computations. Without memory, the core\nconcepts of \"variables\" and \"objects\" in programming languages would be impossible.\n\n\n\n\n## Memory spaces\n\nEvery object that you create in your Zig source code needs to be stored somewhere,\nin your computer's memory. Depending on where and how you define your object, Zig\nwill use a different \"memory space\", or a different\ntype of memory to store this object.\n\nEach type of memory normally serves for different purposes.\nIn Zig, there are 3 types of memory (or 3 different memory spaces) that we care about. They are:\n\n- Global data register (or the \"global data section\");\n- Stack;\n- Heap;\n\n\n### Compile-time known versus runtime known {#sec-compile-time}\n\nOne strategy that Zig uses to decide where it will store each object that you declare, is by looking\nat the value of this particular object. More specifically, by investigating if this value is\nknown at \"compile-time\" or at \"runtime\".\n\nWhen you write a program in Zig, the values of some of the objects that you write in your program are *known\nat compile time*. Meaning that, when you compile your Zig source code, during the compilation process,\nthe `zig` compiler can figure out the exact value of a particular object\nthat exists in your source code.\nKnowing the length (or the size) of each object is also important. So the length (or the size) of each object that you write in your program is,\nin some cases, *known at compile time*.\n\nThe `zig` compiler cares more about knowing the length (or the size) of a particular object\n, than to know its actual value. But, if the `zig` compiler knows the value of the object, then, it\nautomatically knows the size of this object. Because it can simply calculate the\nsize of the object by looking at the size of the value.\n\nTherefore, the priority for the `zig` compiler is to discover the size of each object in your source code.\nIf the value of the object in question is known at compile-time, then, the `zig` compiler\nautomatically knows the size/length of this object. But if the value of this object is not\nknown at compile-time, then, the size of this object is only known at compile-time if,\nand only if, the type of this object has a known fixed size.\n\nIn order for a type to have a known fixed size, this type must have data members whose size is fixed.\nIf this type includes, for example, a variable sized array in it, then, this type does not have a known\nfixed size. Because this array can have any size at runtime\n(i.e. it can be an array of 2 elements, or 50 elements, or 1 thousand elements, etc.).\n\nFor example, a string object, which internally is an array of constant u8 values (`[]const u8`)\nhas a variable size. It can be a string object with 100 or 500 characters in it. If we do not\nknow at compile-time, which exact string will be stored inside this string object, then, we cannot calculate\nthe size of this string object at compile-time. So, any type, or any struct declaration that you make, that\nincludes a string data member that does not have an explicit fixed size, makes this type, or this\nnew struct that you are declaring, a type that does not have a known fixed size at compile-time.\n\nIn contrast, if the type of this struct that you are declaring, includes a data member that is an array,\nbut this array has a known fixed size, like `[60]u8` (which declares an array of 60 `u8` values), then,\nthis type, or, this struct that you are declaring, becomes a type with a known fixed size at compile-time.\nAnd because of that, in this case, the `zig` compiler does not need to know at compile-time the exact value of\nany object of this type. Since the compiler can find the necessary size to store this object by\nlooking at the size of its type.\n\n\nLet's look at an example. In the source code below, we have two constant objects (`name` and `array`) declared.\nBecause the values of these particular objects are written down, in the source code itself (`\"Pedro\"`\nand the number sequence from 1 to 4), the `zig` compiler can easily discover the values of these constant\nobjects (`name` and `array`) during the compilation process.\nThis is what \"known at compile time\" means. It refers to any object that you have in your Zig source code\nwhose value can be identified at compile time.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = \"Pedro\";\nconst array = [_]u8{1, 2, 3, 4};\n_ = name; _ = array;\n\nfn input_length(input: []const u8) usize {\n    const n = input.len;\n    return n;\n}\n```\n:::\n\n\n\n\n\nThe other side of the spectrum are objects whose values are not known at compile time.\nFunction arguments are a classic example of this. Because the value of each function\nargument depends on the value that you assign to this particular argument,\nwhen you call the function.\n\nFor example, the function `input_length()` contains an argument named `input`, which is an array of constant `u8` integers (`[]const u8`).\nIt is impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length\nof this particular argument. Because it is an array that do not have a fixed size specified explicitly in the argument type annotation.\n\nSo, we know that this `input` argument will be an array of `u8` integers. But we do not know at compile-time, its value, and neither his size.\nThis information is known only at runtime, which is the period of time when you program is executed.\nAs a consequence, the value of the expression `input.len` is also known only at runtime.\nThis is an intrinsic characteristic of any function. Just remember that the value of function arguments is usually not \"compile-time known\".\n\nHowever, as I mentioned earlier, what really matters to the compiler is to know the size of the object\nat compile-time, and not necessarily its value. So, although we don't know the value of the object `n`, which is the result of the expression\n`input.len`, at compile-time, we do know its size. Because the expression `input.len` always returns a value of type `usize`,\nand the type `usize` has a known fixed size.\n\n\n\n### Global data register\n\nThe global data register is a specific section of the executable of your Zig program, that is responsible\nfor storing any value that is known at compile time.\n\nEvery constant object whose value is known at compile time that you declare in your source code,\nis stored in the global data register. Also, every literal value that you write in your source code,\nsuch as the string `\"this is a string\"`, or the integer `10`, or a boolean value such as `true`,\nis also stored in the global data register.\n\nHonestly, you don't need to care much about this memory space. Because you can't control it,\nyou can't deliberately access it or use it for your own purposes.\nAlso, this memory space does not affect the logic of your program.\nIt simply exists in your program.\n\n\n### Stack vs Heap\n\nIf you are familiar with system's programming, or just low-level programming in general, you\nprobably have heard of the \"duel\" between Stack vs Heap. These are two different types of memory,\nor different memory spaces, which are both available in Zig.\n\nThese two types of memory don't actually duel with\neach other. This is a common mistake that beginners have, when seeing \"x vs y\" styles of\ntabloid headlines. These two types of memory are actually complementary to each other.\nSo, in almost every Zig program that you ever write, you will likely use a combination of both.\nI will describe each memory space in detail over the next sections. But for now, I just want to\nstablish the main difference between these two types of memory.\n\nIn essence, the stack memory is normally used to store values whose length is fixed and known\nat compile time. In contrast, the heap memory is a *dynamic* type of memory space, meaning that, it is\nused to store values whose length might grow during the execution (runtime) of your program [@jenny2022].\n\nLengths that grow during runtime are intrinsically associated with \"runtime known\" type of values.\nIn other words, if you have an object whose length might grow during runtime, then, the length\nof this object becomes not known at compile time. If the length is not known at compile-time,\nthe value of this object also becomes not known at compile-time.\nThese types of objects should be stored in the heap memory space, which is\na dynamic memory space, which can grow or shrink to fit the size of your objects.\n\n\n\n### Stack {#sec-stack}\n\nThe stack is a type of memory that uses the power of the *stack data structure*, hence the name. \nA \"stack\" is a type of *data structure* that uses a \"last in, first out\" (LIFO) mechanism to store the values\nyou give it to. I imagine you are familiar with this data structure.\nBut, if you are not, the [Wikipedia page](https://en.wikipedia.org/wiki/Stack_(abstract_data_type))[^wiki-stack]\n, or, the [Geeks For Geeks page](https://www.geeksforgeeks.org/stack-data-structure/)[^geek-stack] are both\nexcellent and easy resources to fully understand how this data structure works.\n\n[^wiki-stack]: <https://en.wikipedia.org/wiki/Stack_(abstract_data_type)>\n[^geek-stack]: <https://www.geeksforgeeks.org/stack-data-structure/>\n\nSo, the stack memory space is a type of memory that stores values using a stack data structure.\nIt adds and removes values from the memory by following a \"last in, first out\" (LIFO) principle.\n\nEvery time you make a function call in Zig, an amount of space in the stack is\nreserved for this particular function call [@jenny2022; @zigdocs].\nThe value of each function argument given to the function in this function call is stored in this\nstack space. Also, every local object that you declare inside the function scope is\nusually stored in this same stack space.\n\n\nLooking at the example below, the object `result` is a local object declared inside the scope of the `add()`\nfunction. Because of that, this object is stored inside the stack space reserved for the `add()` function.\nThe `r` object (which is declared outside of the `add()` function scope) is also stored in the stack.\nBut since it is declared in the \"outer\" scope, this object is stored in the\nstack space that belongs to this outer scope.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst r = add(5, 27);\n_ = r;\n\nfn add(x: u8, y: u8) u8 {\n    const result = x + y;\n    return result;\n}\n```\n:::\n\n\n\n\n\n\nSo, any object that you declare inside the scope of a function is always stored inside\nthe space that was reserved for that particular function in the stack memory. This\nalso counts for any object declared inside the scope of your `main()` function for example.\nAs you would expect, in this case, they\nare stored inside the stack space reserved for the `main()` function.\n\nOne very important detail about the stack memory is that **it frees itself automatically**.\nThis is very important, remember that. When objects are stored in the stack memory,\nyou don't have the work (or the responsibility) of freeing/destroying these objects.\nBecause they will be automatically destroyed once the stack space is freed at the end of the function scope.\n\nSo, once the function call returns (or ends, if you prefer to call it this way)\nthe space that was reserved in the stack is destroyed, and all of the objects that were in that space goes away with it.\nThis mechanism exists because this space, and the objects within it, are not necessary anymore,\nsince the function \"finished its business\".\nUsing the `add()` function that we exposed above as an example, it means that the object `result` is automatically\ndestroyed once the function returns.\n\n::: {.callout-important}\nLocal objects that are stored in the stack space of a function are automatically\nfreed/destroyed at the end of the function scope.\n:::\n\n\nThis same logic applies to any other special structure in Zig that have its own scope by surrounding\nit with curly braces (`{}`).\nFor loops, while loops, if else statements, etc. For example, if you declare any local\nobject in the scope of a for loop, this local object is accessible only within the scope\nof this particular for loop. Because once the scope of this for loop ends, the space in the stack\nreserved for this for loop is freed.\nThe example below demonstrates this idea.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This does not compile successfully!\nconst a = [_]u8{0, 1, 2, 3, 4};\nfor (0..a.len) |i| {\n    const index = i;\n    _ = index;\n}\n// Trying to use an object that was\n// declared in the for loop scope,\n// and that does not exist anymore.\nstd.debug.print(\"{d}\\n\", index);\n```\n:::\n\n\n\n\n\n\n\nOne important consequence of this mechanism is that, once the function returns, you can no longer access any memory\naddress that was inside the space in the stack reserved for this particular function. Because this space was\ndestroyed. This means that, if this local object is stored in the stack,\nyou cannot make a function that **returns a pointer to this object**.\n\nThink about that for a second. If all local objects in the stack are destroyed at the end of the function scope, why\nwould you even consider returning a pointer to one of these objects? This pointer is at best,\ninvalid, or, more likely, \"undefined\".\n\nConclusion, it is totally fine to write a function that returns the local object\nitself as result, because then, you return the value of that object as the result.\nBut, if this local object is stored in the stack, you should never write a function\nthat returns a pointer to this local object. Because the memory address pointed by the pointer\nno longer exists.\n\n\nSo, using again the `add()` function as an example, if you rewrite this function so that it\nreturns a pointer to the local object `result`, the `zig` compiler will actually compile\nyour program, with no warnings or errors. At first glance, it looks that this is good code\nthat works as expected. But this is a lie!\n\nIf you try to take a look at the value inside of the `r` object,\nor, if you try to use this `r` object in another expression\nor function call, then, you would have undefined behaviour, and major\nbugs in your program [@zigdocs, see \"Lifetime and Ownership\"[^life] and \"Undefined Behaviour\"[^undef] sections].\n\n[^life]: <https://ziglang.org/documentation/master/#Lifetime-and-Ownership>\n[^undef]: <https://ziglang.org/documentation/master/#Undefined-Behavior>\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This code compiles successfully. But it has\n// undefined behaviour. Never do this!!!\n\n// The `r` object is undefined!\nconst r = add(5, 27);\n_ = r;\n\nfn add(x: u8, y: u8) *const u8 {\n    const result = x + y;\n    return &result;\n}\n```\n:::\n\n\n\n\n\nThis \"invalid pointer to stack variable\" problem is very known across many programming language communities.\nIf you try to do the same thing, for example, in a C or C++ program (i.e. returning an address to\na local object stored in the stack), you would also get undefined behaviour\nin the program.\n\n::: {.callout-important}\nIf a local object in your function is stored in the stack, you should never\nreturn a pointer to this local object from the function. Because\nthis pointer will always become undefined after the function returns, since the stack space of the function\nis destroyed at the end of its scope.\n:::\n\nBut what if you really need to use this local object in some way after your function returns?\nHow can you do this? The answer is: \"in the same you would do if this was a C or C++ program. By returning\nan address to an object stored in the heap\". The heap memory has a much more flexible lifecycle,\nand allows you to get a valid pointer to a local object of a function that already returned\nfrom its scope.\n\n\n### Heap {#sec-heap}\n\nOne important limitation of the stack, is that, only objects whose length/size is known at compile-time can be\nstored in it. In contrast, the heap is a much more dynamic\n(and flexible) type of memory. It is the perfect type of memory to use\nfor objects whose size/length might grow during the execution of your program.\n\nVirtually any application that behaves as a server is a classic use case of the heap.\nA HTTP server, a SSH server, a DNS server, a LSP server, ... any type of server.\nIn summary, a server is a type of application that runs for long periods of time,\nand that serves (or \"deals with\") any incoming request that reaches this particular server.\n\nThe heap is a good choice for this type of system, mainly because the server does not know upfront\nhow many requests it will receive from users, while it is active. It could be one single request,\nor, 5 thousand requests, or, it could also be zero requests.\nThe server needs to have the ability to allocate and manage its memory according to how many requests it receives.\n\nAnother key difference between the stack and the heap, is that the heap is a type\nof memory that you, the programmer, have complete control over. This makes the heap a\nmore flexible type of memory, but it also makes it harder to work with. Because you,\nthe programmer, is responsible for managing everything related to it. Including where the memory is allocated,\nhow much memory is allocated, and where this memory is freed.\n\n> Unlike stack memory, heap memory is allocated explicitly by programmers and it won’t be deallocated until it is explicitly freed [@jenny2022].\n\nTo store an object in the heap, you, the programmer, needs to explicitly tells Zig to do so,\nby using an allocator to allocate some space in the heap. At @sec-allocators, I will present how you can use allocators to allocate memory\nin Zig.\n\n::: {.callout-important}\nEvery memory you allocate in the heap needs to be explicitly freed by you, the programmer.\n:::\n\nThe majority of allocators in Zig do allocate memory on the heap. But some exceptions to this rule are\n`ArenaAllocator()` and `FixedBufferAllocator()`. The `ArenaAllocator()` is a special\ntype of allocator that works in conjunction with a second type of allocator.\nOn the other side, the `FixedBufferAllocator()` is an allocator that works based on\nbuffer objects created on the stack. This means that the `FixedBufferAllocator()` makes\nallocations only on the stack.\n\n\n\n\n### Summary\n\nAfter discussing all of these boring details, we can quickly recap what we learned.\nIn summary, the Zig compiler will use the following rules to decide where each\nobject you declare is stored:\n\n1. every literal value (such as `\"this is string\"`, `10`, or `true`) is stored in the global data section.\n1. every constant object (`const`) whose value **is known at compile-time** is also stored in the global data section.\n1. every object (constant or not) whose length/size **is known at compile time** is stored in the stack space for the current scope.\n1. if an object is created with the method `alloc()` or `create()` of an allocator object, this object is stored in the memory space used by this particular allocator object. Most of allocators available in Zig use the heap memory, so, this object is likely stored in the heap (`FixedBufferAllocator()` is an exception to that).\n1. the heap can only be accessed through allocators. If your object was not created through the `alloc()` or `create()` methods of an allocator object, then, he is most certainly not an object stored in the heap.\n\n\n## Stack overflows {#sec-stack-overflow}\n\nAllocating memory on the stack is generally faster than allocating it on the heap.\nBut this better performance comes with many restrictions. We have already discussed\nmany of these restrictions of the stack at @sec-stack. But there is one more important\nlimitation that I want to talk about, which is the size of the stack itself.\n\nThe stack is limited in size. This size varies from computer to computer, and it depends on\na lot of things (the computer architecture, the operating system, etc.). Nevertheless, this size is usually\nnot that big. This is why we normally use the stack to store only temporary and small objects in memory.\n\nIn essence, if you try to make an allocation on the stack, that is so big that exceeds the stack size limit,\na *stack overflow* happens, and your program just crashes as a result of that. In other words, a stack overflow happens when\nyou attempt to use more space than is available on the stack.\n\nThis type of problem is very similar to a *buffer overflow*, i.e. you are trying to use more space\nthan is available in the \"buffer object\". However, a stack overflow always cause your program to crash,\nwhile a buffer overflow not always cause your program to crash (although it often does).\n\nYou can see an example of a stack overflow in the example below. We are trying to allocate a very big array of `u64` values\non the stack. You can see below that this program does not run succesfully, because it crashed\nwith a \"segmentation fault\" error message.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar very_big_alloc: [1000 * 1000 * 24]u64 = undefined;\n@memset(very_big_alloc[0..], 0);\n```\n:::\n\n\n\n\n\n```\nSegmentation fault (core dumped)\n```\n\nThis segmentation fault error is a result of the stack overflow that was caused by the big\nmemory allocation made on the stack, to store the `very_big_alloc` object.\nThis is why very big objects are usually stored on the heap, instead of the stack.\n\n\n\n## Allocators {#sec-allocators}\n\nOne key aspect about Zig, is that there are \"no hidden-memory allocations\" in Zig.\nWhat that really means, is that \"no allocations happen behind your back in the standard library\" [@zigguide].\n\nThis is a known problem, especially in C++. Because in C++, there are some operators that do allocate\nmemory behind the scene, and there is no way for you to know that, until you actually read the\nsource code of these operators, and find the memory allocation calls.\nMany programmers find this behaviour annoying and hard to keep track of.\n\nBut, in Zig, if a function, an operator, or anything from the standard library\nneeds to allocate some memory during its execution, then, this function/operator needs to receive (as input) an allocator\nprovided by the user, to actually be able to allocate the memory it needs.\n\nThis creates a clear distinction between functions that \"do not\" from those that \"actually do\"\nallocate memory. Just look at the arguments of this function.\nIf a function, or operator, has an allocator object as one of its inputs/arguments, then, you know for\nsure that this function/operator will allocate some memory during its execution.\n\nAn example is the `allocPrint()` function from the Zig Standard Library. With this function, you can\nwrite a new string using format specifiers. So, this function is, for example, very similar to the function `sprintf()` in C.\nIn order to write such new string, the `allocPrint()` function needs to allocate some memory to store the\noutput string.\n\nThat is why, the first argument of this function is an allocator object that you, the user/programmer, gives\nas input to the function. In the example below, I am using the `GeneralPurposeAllocator()` as my allocator\nobject. But I could easily use any other type of allocator object from the Zig Standard Library.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst name = \"Pedro\";\nconst output = try std.fmt.allocPrint(\n    allocator,\n    \"Hello {s}!!!\",\n    .{name}\n);\ntry stdout.print(\"{s}\\n\", .{output});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello Pedro!!!\n```\n\n\n:::\n:::\n\n\n\n\n\n\nYou get a lot of control over where and how much memory this function can allocate.\nBecause it is you, the user/programmer, that provides the allocator for the function to use.\nThis makes \"total control\" over memory management easier to achieve in Zig.\n\n### What are allocators?\n\nAllocators in Zig are objects that you can use to allocate memory for your program.\nThey are similar to the memory allocating functions in C, like `malloc()` and `calloc()`.\nSo, if you need to use more memory than you initially have, during the execution of your program, you can simply ask\nfor more memory by using an allocator object.\n\nZig offers different types of allocators, and they are usually available through the `std.heap` module of\nthe standard library. Thus, just import the Zig Standard Library into your Zig module (with `@import(\"std\")`), and you can start\nusing these allocators in your code.\n\nFurthermore, every allocator object is built on top of the `Allocator` interface in Zig.\nThis means that, every allocator object you find in Zig must have the methods `alloc()`,\n`create()`, `free()` and `destroy()`. So, you can change the type of allocator you are using,\nbut you don't need to change the function calls to the methods that do the memory allocation\n(and the free memory operations) for your program.\n\n### Why you need an allocator?\n\nAs we described at @sec-stack, everytime you make a function call in Zig,\na space in the stack is reserved for this function call. But the stack\nhas a key limitation which is: every object stored in the stack have a\nknown fixed length.\n\nBut in reality, there are two very common instances where this \"fixed length limitation\" of the stack is a deal braker:\n\n1. the objects that you create inside your function might grow in size during the execution of the function.\n1. sometimes, it is impossible to know upfront how many inputs you will receive, or how big this input will be.\n\nAlso, there is another instance where you might want to use an allocator, which is when you want to write a function that returns a pointer\nto a local object. As I described at @sec-stack, you cannot do that if this local object is stored in the\nstack. However, if this object is stored in the heap, then, you can return a pointer to this object at the\nend of the function. Because you (the programmer) control the lifetime of any heap memory that you allocate. You decide\nwhen this memory gets destroyed/freed.\n\nThese are common situations where the stack is not good for.\nThat is why you need a different memory management strategy to\nstore these objects inside your function. You need to use\na memory type that can grow together with your objects, or that you\ncan control the lifetime of this memory.\nThe heap fits this description.\n\nAllocating memory on the heap is commonly known as dynamic memory management. As the objects you create grow in size\nduring the execution of your program, you grow the amount of memory\nyou have by allocating more memory in the heap to store these objects. \nAnd you do that in Zig, by using an allocator object.\n\n\n### The different types of allocators\n\n\nAt the moment of the writing of this book, in Zig, we have 6 different\nallocators available in the standard library:\n\n- `GeneralPurposeAllocator()`.\n- `page_allocator()`.\n- `FixedBufferAllocator()` and `ThreadSafeFixedBufferAllocator()`.\n- `ArenaAllocator()`.\n- `c_allocator()` (requires you to link to libc).\n\n\nEach allocator has its own perks and limitations. All allocators, except `FixedBufferAllocator()` and `ArenaAllocator()`,\nare allocators that use the heap memory. So any memory that you allocate with\nthese allocators, will be placed in the heap.\n\n### General-purpose allocators\n\nThe `GeneralPurposeAllocator()`, as the name suggests, is a \"general purpose\" allocator. You can use it for every type\nof task. In the example below, I'm allocating enough space to store a single integer in the object `some_number`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const some_number = try allocator.create(u32);\n    defer allocator.destroy(some_number);\n\n    some_number.* = @as(u32, 45);\n}\n```\n:::\n\n\n\n\n\n\nWhile useful, you might want to use the `c_allocator()`, which is a alias to the C standard allocator `malloc()`. So, yes, you can use\n`malloc()` in Zig if you want to. Just use the `c_allocator()` from the Zig standard library. However,\nif you do use `c_allocator()`, you must link to Libc when compiling your source code with the\n`zig` compiler, by including the flag `-lc` in your compilation process.\nIf you do not link your source code to Libc, Zig will not be able to find the\n`malloc()` implementation in your system.\n\n### Page allocator\n\nThe `page_allocator()` is an allocator that allocates full pages of memory in the heap. In other words,\nevery time you allocate memory with `page_allocator()`, a full page of memory in the heap is allocated,\ninstead of just a small piece of it.\n\nThe size of this page depends on the system you are using.\nMost systems use a page size of 4KB in the heap, so, that is the amount of memory that is normally\nallocated in each call by `page_allocator()`. That is why, `page_allocator()` is considered a\nfast, but also \"wasteful\" allocator in Zig. Because it allocates a big amount of memory\nin each call, and you most likely will not need that much memory in your program.\n\n### Buffer allocators\n\nThe `FixedBufferAllocator()` and `ThreadSafeFixedBufferAllocator()` are allocator objects that\nwork with a fixed sized buffer object at the back. In other words, they use a fixed sized buffer\nobject as the basis for the memory. When you ask these allocator objects to allocate some memory for you,\nthey are essentially reserving some amount of space inside this fixed sized buffer object for you to use.\n\nThis means that, in order to use these allocators, you must first create a buffer object in your code,\nand then, give this buffer object as an input to these allocators.\n\nThis also means that, these allocator objects can allocate memory both in the stack or in the heap.\nEverything depends on where the buffer object that you provide lives. If this buffer object lives\nin the stack, then, the memory allocated is \"stack-based\". But if it lives on the heap, then,\nthe memory allocated is \"heap-based\".\n\n\nIn the example below, I'm creating a `buffer` object on the stack that is 10 elements long.\nNotice that I give this `buffer` object to the `FixedBufferAllocator()` constructor.\nNow, because this `buffer` object is 10 elements long, this means that I am limited to this space.\nI cannot allocate more than 10 elements with this allocator object. If I try to\nallocate more than that, the `alloc()` method will return an `OutOfMemory` error value.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar buffer: [10]u8 = undefined;\nfor (0..buffer.len) |i| {\n    buffer[i] = 0; // Initialize to zero\n}\n\nvar fba = std.heap.FixedBufferAllocator.init(&buffer);\nconst allocator = fba.allocator();\nconst input = try allocator.alloc(u8, 5);\ndefer allocator.free(input);\n```\n:::\n\n\n\n\n\nRemember, the memory allocated by these allocator objects can be either from\nthe stack, or, from the heap. It all depends on where the buffer object that you provide lives.\nIn the above example, the `buffer` object lives in the stack, and, therefore, the memory allocated\nis based in the stack. But what if it was based on the heap?\n\nAs we described at @sec-stack-overflow, one of the main reasons why you would use the heap,\ninstead of the stack, is to allocate huge amounts of space to store very big objects.\nThus, let's suppose you wanted to use a very big buffer object as the basis for your\nallocator objects. You would have to allocate this very big buffer object on the heap.\nThe example below demonstrates this case.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst heap = std.heap.page_allocator;\nconst memory_buffer = try heap.alloc(\n    u8, 100 * 1024 * 1024 // 100 MB memory\n);\ndefer heap.free(memory_buffer);\nvar fba = std.heap.FixedBufferAllocator.init(\n    memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst input = try allocator.alloc(u8, 1000);\ndefer allocator.free(input);\n```\n:::\n\n\n\n\n\n\n\n### Arena allocator {#sec-arena-allocator}\n\nThe `ArenaAllocator()` is an allocator object that takes a child allocator as input. The idea behind the `ArenaAllocator()` in Zig\nis similar to the concept of \"arenas\" in the programming language Go[^go-arena]. It is an allocator object that allows you\nto allocate memory as many times you want, but free all memory only once.\nIn other words, if you have, for example, called 5 times the method `alloc()` of an `ArenaAllocator()` object, you can\nfree all the memory you allocated over these 5 calls at once, by simply calling the `deinit()` method of the same `ArenaAllocator()` object.\n\n[^go-arena]: <https://go.dev/src/arena/arena.go>\n\nIf you give, for example, a `GeneralPurposeAllocator()` object as input to the `ArenaAllocator()` constructor, like in the example below, then, the allocations\nyou perform with `alloc()` will actually be made with the underlying object `GeneralPurposeAllocator()` that was passed.\nSo, with an arena allocator, any new memory you ask for is allocated by the child allocator. The only thing that an arena allocator\nreally does is help you to free all the memory you allocated multiple times with just a single command. In the example\nbelow, I called `alloc()` 3 times. So, if I did not use an arena allocator, then, I would need to call\n`free()` 3 times to free all the allocated memory.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nvar aa = std.heap.ArenaAllocator.init(gpa.allocator());\ndefer aa.deinit();\nconst allocator = aa.allocator();\n\nconst in1 = allocator.alloc(u8, 5);\nconst in2 = allocator.alloc(u8, 10);\nconst in3 = allocator.alloc(u8, 15);\n_ = in1; _ = in2; _ = in3;\n```\n:::\n\n\n\n\n\n\n\n### The `alloc()` and `free()` methods\n\nIn the code example below, we are accessing the `stdin`, which is\nthe standard input channel, to receive an input from the\nuser. We read the input given by the user with the `readUntilDelimiterOrEof()`\nmethod.\n\nNow, after reading the input of the user, we need to store this input somewhere in\nour program. That is why I use an allocator in this example. I use it to allocate some\namount of memory to store this input given by the user. More specifically, the method `alloc()`\nof the allocator object is used to allocate an array capable of storing 50 `u8` values.\n\nNotice that this `alloc()` method receives two inputs. The first one, is a type.\nThis defines what type of values the allocated array will store. In the example\nbelow, we are allocating an array of unsigned 8-bit integers (`u8`). But\nyou can create an array to store any type of value you want. Next, on the second argument, we\ndefine the size of the allocated array, by specifying how many elements\nthis array will contain. In the case below, we are allocating an array of 50 elements.\n\nAt @sec-zig-strings we described that strings in Zig are simply arrays of characters.\nEach character is represented by a `u8` value. So, this means that the array that\nwas allocated in the object `input` is capable of storing a string that is\n50-characters long.\n\nSo, in essence, the expression `var input: [50]u8 = undefined` would create\nan array for 50 `u8` values in the stack of the current scope. But, you\ncan allocate the same array in the heap by using the expression `var input = try allocator.alloc(u8, 50)`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdin = std.io.getStdIn();\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var input = try allocator.alloc(u8, 50);\n    defer allocator.free(input);\n    for (0..input.len) |i| {\n        input[i] = 0; // initialize all fields to zero.\n    }\n    // read user input\n    const input_reader = stdin.reader();\n    _ = try input_reader.readUntilDelimiterOrEof(\n        input,\n        '\\n'\n    );\n    std.debug.print(\"{s}\\n\", .{input});\n}\n```\n:::\n\n\n\n\n\nAlso, notice that in this example, we use the `defer` keyword (which I described at @sec-defer) to run a small\npiece of code at the end of the current scope, which is the expression `allocator.free(input)`.\nWhen you execute this expression, the allocator will free the memory that it allocated\nfor the `input` object.\n\nWe have talked about this at @sec-heap. You **should always** explicitly free any memory that you allocate\nusing an allocator! You do that by using the `free()` method of the same allocator object you\nused to allocate this memory. The `defer` keyword is used in this example only to help us execute\nthis free operation at the end of the current scope.\n\n\n### The `create()` and `destroy()` methods\n\nWith the `alloc()` and `free()` methods, you can allocate memory to store multiple elements\nat once. In other words, with these methods, we always allocate an array to store multiple elements at once.\nBut what if you need enough space to store just a single item? Should you\nallocate an array of a single element through `alloc()`?\n\nThe answer is no! In this case,\nyou should use the `create()` method of the allocator object.\nEvery allocator object offers the `create()` and `destroy()` methods,\nwhich are used to allocate and free memory for a single item, respectively.\n\nSo, in essence, if you want to allocate memory to store an array of elements, you\nshould use `alloc()` and `free()`. But if you need to store just a single item,\nthen, the `create()` and `destroy()` methods are ideal for you.\n\nIn the example below, I'm defining a struct to represent an user of some sort.\nIt could be an user for a game, or a software to manage resources, it doesn't mater.\nNotice that I use the `create()` method this time, to store a single `User` object\nin the program. Also notice that I use the `destroy()` method to free the memory\nused by this object at the end of the scope.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst User = struct {\n    id: usize,\n    name: []const u8,\n\n    pub fn init(id: usize, name: []const u8) User {\n        return .{ .id = id, .name = name };\n    }\n};\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const user = try allocator.create(User);\n    defer allocator.destroy(user);\n\n    user.* = User.init(0, \"Pedro\");\n}\n```\n:::\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Memory and Allocators\n\n\nIn this chapter, we will talk about memory. How does Zig control memory? What\ncommon tools are used? Are there any important aspects that make memory\ndifferent/special in Zig? You will find the answers here.\n\nComputers fundamentally rely on memory to function. This memory acts as a temporary storage\nspace for the data and values generated during computations. Without memory, the core\nconcepts of \"variables\" and \"objects\" in programming languages would be impossible.\n\n\n\n\n## Memory spaces\n\nEvery object that you create in your Zig source code needs to be stored somewhere,\nin your computer's memory. Depending on where and how you define your object, Zig\nwill use a different \"memory space\", or a different\ntype of memory to store this object.\n\nEach type of memory normally serves for different purposes.\nIn Zig, there are 3 types of memory (or 3 different memory spaces) that we care about. They are:\n\n- Global data register (or the \"global data section\");\n- Stack;\n- Heap;\n\n\n### Compile-time known versus runtime known {#sec-compile-time}\n\nOne strategy that Zig uses to decide where it will store each object that you declare, is by looking\nat the value of this particular object. More specifically, by investigating if this value is\nknown at \"compile-time\" or at \"runtime\".\n\nWhen you write a program in Zig, the values of some of the objects that you write in your program are *known\nat compile time*. Meaning that, when you compile your Zig source code, during the compilation process,\nthe `zig` compiler can figure out the exact value of a particular object\nthat exists in your source code.\nKnowing the length (or the size) of each object is also important. So the length (or the size) of each object that you write in your program is,\nin some cases, *known at compile time*.\n\nThe `zig` compiler cares more about knowing the length (or the size) of a particular object\n, than to know its actual value. But, if the `zig` compiler knows the value of the object, then, it\nautomatically knows the size of this object. Because it can simply calculate the\nsize of the object by looking at the size of the value.\n\nTherefore, the priority for the `zig` compiler is to discover the size of each object in your source code.\nIf the value of the object in question is known at compile-time, then, the `zig` compiler\nautomatically knows the size/length of this object. But if the value of this object is not\nknown at compile-time, then, the size of this object is only known at compile-time if,\nand only if, the type of this object has a known fixed size.\n\nIn order for a type to have a known fixed size, this type must have data members whose size is fixed.\nIf this type includes, for example, a variable sized array in it, then, this type does not have a known\nfixed size. Because this array can have any size at runtime\n(i.e. it can be an array of 2 elements, or 50 elements, or 1 thousand elements, etc.).\n\nFor example, a string object, which internally is an array of constant u8 values (`[]const u8`)\nhas a variable size. It can be a string object with 100 or 500 characters in it. If we do not\nknow at compile-time, which exact string will be stored inside this string object, then, we cannot calculate\nthe size of this string object at compile-time. So, any type, or any struct declaration that you make, that\nincludes a string data member that does not have an explicit fixed size, makes this type, or this\nnew struct that you are declaring, a type that does not have a known fixed size at compile-time.\n\nIn contrast, if the type of this struct that you are declaring, includes a data member that is an array,\nbut this array has a known fixed size, like `[60]u8` (which declares an array of 60 `u8` values), then,\nthis type, or, this struct that you are declaring, becomes a type with a known fixed size at compile-time.\nAnd because of that, in this case, the `zig` compiler does not need to know at compile-time the exact value of\nany object of this type. Since the compiler can find the necessary size to store this object by\nlooking at the size of its type.\n\n\nLet's look at an example. In the source code below, we have two constant objects (`name` and `array`) declared.\nBecause the values of these particular objects are written down, in the source code itself (`\"Pedro\"`\nand the number sequence from 1 to 4), the `zig` compiler can easily discover the values of these constant\nobjects (`name` and `array`) during the compilation process.\nThis is what \"known at compile time\" means. It refers to any object that you have in your Zig source code\nwhose value can be identified at compile time.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn input_length(input: []const u8) usize {\n    const n = input.len;\n    return n;\n}\n\npub fn main() !void {\n    const name = \"Pedro\";\n    const array = [_]u8{1, 2, 3, 4};\n    _ = name; _ = array;\n}\n```\n:::\n\n\n\n\n\nThe other side of the spectrum are objects whose values are not known at compile time.\nFunction arguments are a classic example of this. Because the value of each function\nargument depends on the value that you assign to this particular argument,\nwhen you call the function.\n\nFor example, the function `input_length()` contains an argument named `input`, which is an array of constant `u8` integers (`[]const u8`).\nIt is impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length\nof this particular argument. Because it is an array that do not have a fixed size specified explicitly in the argument type annotation.\n\nSo, we know that this `input` argument will be an array of `u8` integers. But we do not know at compile-time, its value, and neither his size.\nThis information is known only at runtime, which is the period of time when you program is executed.\nAs a consequence, the value of the expression `input.len` is also known only at runtime.\nThis is an intrinsic characteristic of any function. Just remember that the value of function arguments is usually not \"compile-time known\".\n\nHowever, as I mentioned earlier, what really matters to the compiler is to know the size of the object\nat compile-time, and not necessarily its value. So, although we don't know the value of the object `n`, which is the result of the expression\n`input.len`, at compile-time, we do know its size. Because the expression `input.len` always returns a value of type `usize`,\nand the type `usize` has a known fixed size.\n\n\n\n### Global data register\n\nThe global data register is a specific section of the executable of your Zig program, that is responsible\nfor storing any value that is known at compile time.\n\nEvery constant object whose value is known at compile time that you declare in your source code,\nis stored in the global data register. Also, every literal value that you write in your source code,\nsuch as the string `\"this is a string\"`, or the integer `10`, or a boolean value such as `true`,\nis also stored in the global data register.\n\nHonestly, you don't need to care much about this memory space. Because you can't control it,\nyou can't deliberately access it or use it for your own purposes.\nAlso, this memory space does not affect the logic of your program.\nIt simply exists in your program.\n\n\n### Stack vs Heap\n\nIf you are familiar with system's programming, or just low-level programming in general, you\nprobably have heard of the \"duel\" between Stack vs Heap. These are two different types of memory,\nor different memory spaces, which are both available in Zig.\n\nThese two types of memory don't actually duel with\neach other. This is a common mistake that beginners have, when seeing \"x vs y\" styles of\ntabloid headlines. These two types of memory are actually complementary to each other.\nSo, in almost every Zig program that you ever write, you will likely use a combination of both.\nI will describe each memory space in detail over the next sections. But for now, I just want to\nstablish the main difference between these two types of memory.\n\nIn essence, the stack memory is normally used to store values whose length is fixed and known\nat compile time. In contrast, the heap memory is a *dynamic* type of memory space, meaning that, it is\nused to store values whose length might grow during the execution (runtime) of your program [@jenny2022].\n\nLengths that grow during runtime are intrinsically associated with \"runtime known\" type of values.\nIn other words, if you have an object whose length might grow during runtime, then, the length\nof this object becomes not known at compile time. If the length is not known at compile-time,\nthe value of this object also becomes not known at compile-time.\nThese types of objects should be stored in the heap memory space, which is\na dynamic memory space, which can grow or shrink to fit the size of your objects.\n\n\n\n### Stack {#sec-stack}\n\nThe stack is a type of memory that uses the power of the *stack data structure*, hence the name. \nA \"stack\" is a type of *data structure* that uses a \"last in, first out\" (LIFO) mechanism to store the values\nyou give it to. I imagine you are familiar with this data structure.\nBut, if you are not, the [Wikipedia page](https://en.wikipedia.org/wiki/Stack_(abstract_data_type))[^wiki-stack]\n, or, the [Geeks For Geeks page](https://www.geeksforgeeks.org/stack-data-structure/)[^geek-stack] are both\nexcellent and easy resources to fully understand how this data structure works.\n\n[^wiki-stack]: <https://en.wikipedia.org/wiki/Stack_(abstract_data_type)>\n[^geek-stack]: <https://www.geeksforgeeks.org/stack-data-structure/>\n\nSo, the stack memory space is a type of memory that stores values using a stack data structure.\nIt adds and removes values from the memory by following a \"last in, first out\" (LIFO) principle.\n\nEvery time you make a function call in Zig, an amount of space in the stack is\nreserved for this particular function call [@jenny2022; @zigdocs].\nThe value of each function argument given to the function in this function call is stored in this\nstack space. Also, every local object that you declare inside the function scope is\nusually stored in this same stack space.\n\n\nLooking at the example below, the object `result` is a local object declared inside the scope of the `add()`\nfunction. Because of that, this object is stored inside the stack space reserved for the `add()` function.\nThe `r` object (which is declared outside of the `add()` function scope) is also stored in the stack.\nBut since it is declared in the \"outer\" scope, this object is stored in the\nstack space that belongs to this outer scope.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn add(x: u8, y: u8) u8 {\n    const result = x + y;\n    return result;\n}\n\npub fn main() !void {\n    const r = add(5, 27);\n    _ = r;\n}\n```\n:::\n\n\n\n\n\n\nSo, any object that you declare inside the scope of a function is always stored inside\nthe space that was reserved for that particular function in the stack memory. This\nalso counts for any object declared inside the scope of your `main()` function for example.\nAs you would expect, in this case, they\nare stored inside the stack space reserved for the `main()` function.\n\nOne very important detail about the stack memory is that **it frees itself automatically**.\nThis is very important, remember that. When objects are stored in the stack memory,\nyou don't have the work (or the responsibility) of freeing/destroying these objects.\nBecause they will be automatically destroyed once the stack space is freed at the end of the function scope.\n\nSo, once the function call returns (or ends, if you prefer to call it this way)\nthe space that was reserved in the stack is destroyed, and all of the objects that were in that space goes away with it.\nThis mechanism exists because this space, and the objects within it, are not necessary anymore,\nsince the function \"finished its business\".\nUsing the `add()` function that we exposed above as an example, it means that the object `result` is automatically\ndestroyed once the function returns.\n\n::: {.callout-important}\nLocal objects that are stored in the stack space of a function are automatically\nfreed/destroyed at the end of the function scope.\n:::\n\n\nThis same logic applies to any other special structure in Zig that have its own scope by surrounding\nit with curly braces (`{}`).\nFor loops, while loops, if else statements, etc. For example, if you declare any local\nobject in the scope of a for loop, this local object is accessible only within the scope\nof this particular for loop. Because once the scope of this for loop ends, the space in the stack\nreserved for this for loop is freed.\nThe example below demonstrates this idea.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This does not compile successfully!\nconst a = [_]u8{0, 1, 2, 3, 4};\nfor (0..a.len) |i| {\n    const index = i;\n    _ = index;\n}\n// Trying to use an object that was\n// declared in the for loop scope,\n// and that does not exist anymore.\nstd.debug.print(\"{d}\\n\", index);\n```\n:::\n\n\n\n\n\n\n\nOne important consequence of this mechanism is that, once the function returns, you can no longer access any memory\naddress that was inside the space in the stack reserved for this particular function. Because this space was\ndestroyed. This means that, if this local object is stored in the stack,\nyou cannot make a function that **returns a pointer to this object**.\n\nThink about that for a second. If all local objects in the stack are destroyed at the end of the function scope, why\nwould you even consider returning a pointer to one of these objects? This pointer is at best,\ninvalid, or, more likely, \"undefined\".\n\nConclusion, it is totally fine to write a function that returns the local object\nitself as result, because then, you return the value of that object as the result.\nBut, if this local object is stored in the stack, you should never write a function\nthat returns a pointer to this local object. Because the memory address pointed by the pointer\nno longer exists.\n\n\nSo, using again the `add()` function as an example, if you rewrite this function so that it\nreturns a pointer to the local object `result`, the `zig` compiler will actually compile\nyour program, with no warnings or errors. At first glance, it looks that this is good code\nthat works as expected. But this is a lie!\n\nIf you try to take a look at the value inside of the `r` object,\nor, if you try to use this `r` object in another expression\nor function call, then, you would have undefined behaviour, and major\nbugs in your program [@zigdocs, see \"Lifetime and Ownership\"[^life] and \"Undefined Behaviour\"[^undef] sections].\n\n[^life]: <https://ziglang.org/documentation/master/#Lifetime-and-Ownership>\n[^undef]: <https://ziglang.org/documentation/master/#Undefined-Behavior>\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn add(x: u8, y: u8) *const u8 {\n    const result = x + y;\n    return &result;\n}\n\npub fn main() !void {\n    // This code compiles successfully. But it has\n    // undefined behaviour. Never do this!!!\n    // The `r` object is undefined!\n    const r = add(5, 27); _ = r;\n}\n```\n:::\n\n\n\n\n\nThis \"invalid pointer to stack variable\" problem is very known across many programming language communities.\nIf you try to do the same thing, for example, in a C or C++ program (i.e. returning an address to\na local object stored in the stack), you would also get undefined behaviour\nin the program.\n\n::: {.callout-important}\nIf a local object in your function is stored in the stack, you should never\nreturn a pointer to this local object from the function. Because\nthis pointer will always become undefined after the function returns, since the stack space of the function\nis destroyed at the end of its scope.\n:::\n\nBut what if you really need to use this local object in some way after your function returns?\nHow can you do this? The answer is: \"in the same you would do if this was a C or C++ program. By returning\nan address to an object stored in the heap\". The heap memory has a much more flexible lifecycle,\nand allows you to get a valid pointer to a local object of a function that already returned\nfrom its scope.\n\n\n### Heap {#sec-heap}\n\nOne important limitation of the stack, is that, only objects whose length/size is known at compile-time can be\nstored in it. In contrast, the heap is a much more dynamic\n(and flexible) type of memory. It is the perfect type of memory to use\nfor objects whose size/length might grow during the execution of your program.\n\nVirtually any application that behaves as a server is a classic use case of the heap.\nA HTTP server, a SSH server, a DNS server, a LSP server, ... any type of server.\nIn summary, a server is a type of application that runs for long periods of time,\nand that serves (or \"deals with\") any incoming request that reaches this particular server.\n\nThe heap is a good choice for this type of system, mainly because the server does not know upfront\nhow many requests it will receive from users, while it is active. It could be one single request,\nor, 5 thousand requests, or, it could also be zero requests.\nThe server needs to have the ability to allocate and manage its memory according to how many requests it receives.\n\nAnother key difference between the stack and the heap, is that the heap is a type\nof memory that you, the programmer, have complete control over. This makes the heap a\nmore flexible type of memory, but it also makes it harder to work with. Because you,\nthe programmer, is responsible for managing everything related to it. Including where the memory is allocated,\nhow much memory is allocated, and where this memory is freed.\n\n> Unlike stack memory, heap memory is allocated explicitly by programmers and it won’t be deallocated until it is explicitly freed [@jenny2022].\n\nTo store an object in the heap, you, the programmer, needs to explicitly tells Zig to do so,\nby using an allocator to allocate some space in the heap. At @sec-allocators, I will present how you can use allocators to allocate memory\nin Zig.\n\n::: {.callout-important}\nEvery memory you allocate in the heap needs to be explicitly freed by you, the programmer.\n:::\n\nThe majority of allocators in Zig do allocate memory on the heap. But some exceptions to this rule are\n`ArenaAllocator()` and `FixedBufferAllocator()`. The `ArenaAllocator()` is a special\ntype of allocator that works in conjunction with a second type of allocator.\nOn the other side, the `FixedBufferAllocator()` is an allocator that works based on\nbuffer objects created on the stack. This means that the `FixedBufferAllocator()` makes\nallocations only on the stack.\n\n\n\n\n### Summary\n\nAfter discussing all of these boring details, we can quickly recap what we learned.\nIn summary, the Zig compiler will use the following rules to decide where each\nobject you declare is stored:\n\n1. every literal value (such as `\"this is string\"`, `10`, or `true`) is stored in the global data section.\n1. every constant object (`const`) whose value **is known at compile-time** is also stored in the global data section.\n1. every object (constant or not) whose length/size **is known at compile time** is stored in the stack space for the current scope.\n1. if an object is created with the method `alloc()` or `create()` of an allocator object, this object is stored in the memory space used by this particular allocator object. Most of allocators available in Zig use the heap memory, so, this object is likely stored in the heap (`FixedBufferAllocator()` is an exception to that).\n1. the heap can only be accessed through allocators. If your object was not created through the `alloc()` or `create()` methods of an allocator object, then, he is most certainly not an object stored in the heap.\n\n\n## Stack overflows {#sec-stack-overflow}\n\nAllocating memory on the stack is generally faster than allocating it on the heap.\nBut this better performance comes with many restrictions. We have already discussed\nmany of these restrictions of the stack at @sec-stack. But there is one more important\nlimitation that I want to talk about, which is the size of the stack itself.\n\nThe stack is limited in size. This size varies from computer to computer, and it depends on\na lot of things (the computer architecture, the operating system, etc.). Nevertheless, this size is usually\nnot that big. This is why we normally use the stack to store only temporary and small objects in memory.\n\nIn essence, if you try to make an allocation on the stack, that is so big that exceeds the stack size limit,\na *stack overflow* happens, and your program just crashes as a result of that. In other words, a stack overflow happens when\nyou attempt to use more space than is available on the stack.\n\nThis type of problem is very similar to a *buffer overflow*, i.e. you are trying to use more space\nthan is available in the \"buffer object\". However, a stack overflow always cause your program to crash,\nwhile a buffer overflow not always cause your program to crash (although it often does).\n\nYou can see an example of a stack overflow in the example below. We are trying to allocate a very big array of `u64` values\non the stack. You can see below that this program does not run succesfully, because it crashed\nwith a \"segmentation fault\" error message.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar very_big_alloc: [1000 * 1000 * 24]u64 = undefined;\n@memset(very_big_alloc[0..], 0);\n```\n:::\n\n\n\n\n\n```\nSegmentation fault (core dumped)\n```\n\nThis segmentation fault error is a result of the stack overflow that was caused by the big\nmemory allocation made on the stack, to store the `very_big_alloc` object.\nThis is why very big objects are usually stored on the heap, instead of the stack.\n\n\n\n## Allocators {#sec-allocators}\n\nOne key aspect about Zig, is that there are \"no hidden-memory allocations\" in Zig.\nWhat that really means, is that \"no allocations happen behind your back in the standard library\" [@zigguide].\n\nThis is a known problem, especially in C++. Because in C++, there are some operators that do allocate\nmemory behind the scene, and there is no way for you to know that, until you actually read the\nsource code of these operators, and find the memory allocation calls.\nMany programmers find this behaviour annoying and hard to keep track of.\n\nBut, in Zig, if a function, an operator, or anything from the standard library\nneeds to allocate some memory during its execution, then, this function/operator needs to receive (as input) an allocator\nprovided by the user, to actually be able to allocate the memory it needs.\n\nThis creates a clear distinction between functions that \"do not\" from those that \"actually do\"\nallocate memory. Just look at the arguments of this function.\nIf a function, or operator, has an allocator object as one of its inputs/arguments, then, you know for\nsure that this function/operator will allocate some memory during its execution.\n\nAn example is the `allocPrint()` function from the Zig Standard Library. With this function, you can\nwrite a new string using format specifiers. So, this function is, for example, very similar to the function `sprintf()` in C.\nIn order to write such new string, the `allocPrint()` function needs to allocate some memory to store the\noutput string.\n\nThat is why, the first argument of this function is an allocator object that you, the user/programmer, gives\nas input to the function. In the example below, I am using the `GeneralPurposeAllocator()` as my allocator\nobject. But I could easily use any other type of allocator object from the Zig Standard Library.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst name = \"Pedro\";\nconst output = try std.fmt.allocPrint(\n    allocator,\n    \"Hello {s}!!!\",\n    .{name}\n);\ntry stdout.print(\"{s}\\n\", .{output});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello Pedro!!!\n```\n\n\n:::\n:::\n\n\n\n\n\n\nYou get a lot of control over where and how much memory this function can allocate.\nBecause it is you, the user/programmer, that provides the allocator for the function to use.\nThis makes \"total control\" over memory management easier to achieve in Zig.\n\n### What are allocators?\n\nAllocators in Zig are objects that you can use to allocate memory for your program.\nThey are similar to the memory allocating functions in C, like `malloc()` and `calloc()`.\nSo, if you need to use more memory than you initially have, during the execution of your program, you can simply ask\nfor more memory by using an allocator object.\n\nZig offers different types of allocators, and they are usually available through the `std.heap` module of\nthe standard library. Thus, just import the Zig Standard Library into your Zig module (with `@import(\"std\")`), and you can start\nusing these allocators in your code.\n\nFurthermore, every allocator object is built on top of the `Allocator` interface in Zig.\nThis means that, every allocator object you find in Zig must have the methods `alloc()`,\n`create()`, `free()` and `destroy()`. So, you can change the type of allocator you are using,\nbut you don't need to change the function calls to the methods that do the memory allocation\n(and the free memory operations) for your program.\n\n### Why you need an allocator?\n\nAs we described at @sec-stack, everytime you make a function call in Zig,\na space in the stack is reserved for this function call. But the stack\nhas a key limitation which is: every object stored in the stack have a\nknown fixed length.\n\nBut in reality, there are two very common instances where this \"fixed length limitation\" of the stack is a deal braker:\n\n1. the objects that you create inside your function might grow in size during the execution of the function.\n1. sometimes, it is impossible to know upfront how many inputs you will receive, or how big this input will be.\n\nAlso, there is another instance where you might want to use an allocator, which is when you want to write a function that returns a pointer\nto a local object. As I described at @sec-stack, you cannot do that if this local object is stored in the\nstack. However, if this object is stored in the heap, then, you can return a pointer to this object at the\nend of the function. Because you (the programmer) control the lifetime of any heap memory that you allocate. You decide\nwhen this memory gets destroyed/freed.\n\nThese are common situations where the stack is not good for.\nThat is why you need a different memory management strategy to\nstore these objects inside your function. You need to use\na memory type that can grow together with your objects, or that you\ncan control the lifetime of this memory.\nThe heap fits this description.\n\nAllocating memory on the heap is commonly known as dynamic memory management. As the objects you create grow in size\nduring the execution of your program, you grow the amount of memory\nyou have by allocating more memory in the heap to store these objects. \nAnd you do that in Zig, by using an allocator object.\n\n\n### The different types of allocators\n\n\nAt the moment of the writing of this book, in Zig, we have 6 different\nallocators available in the standard library:\n\n- `GeneralPurposeAllocator()`.\n- `page_allocator()`.\n- `FixedBufferAllocator()` and `ThreadSafeFixedBufferAllocator()`.\n- `ArenaAllocator()`.\n- `c_allocator()` (requires you to link to libc).\n\n\nEach allocator has its own perks and limitations. All allocators, except `FixedBufferAllocator()` and `ArenaAllocator()`,\nare allocators that use the heap memory. So any memory that you allocate with\nthese allocators, will be placed in the heap.\n\n### General-purpose allocators\n\nThe `GeneralPurposeAllocator()`, as the name suggests, is a \"general purpose\" allocator. You can use it for every type\nof task. In the example below, I'm allocating enough space to store a single integer in the object `some_number`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const some_number = try allocator.create(u32);\n    defer allocator.destroy(some_number);\n\n    some_number.* = @as(u32, 45);\n}\n```\n:::\n\n\n\n\n\n\nWhile useful, you might want to use the `c_allocator()`, which is a alias to the C standard allocator `malloc()`. So, yes, you can use\n`malloc()` in Zig if you want to. Just use the `c_allocator()` from the Zig standard library. However,\nif you do use `c_allocator()`, you must link to Libc when compiling your source code with the\n`zig` compiler, by including the flag `-lc` in your compilation process.\nIf you do not link your source code to Libc, Zig will not be able to find the\n`malloc()` implementation in your system.\n\n### Page allocator\n\nThe `page_allocator()` is an allocator that allocates full pages of memory in the heap. In other words,\nevery time you allocate memory with `page_allocator()`, a full page of memory in the heap is allocated,\ninstead of just a small piece of it.\n\nThe size of this page depends on the system you are using.\nMost systems use a page size of 4KB in the heap, so, that is the amount of memory that is normally\nallocated in each call by `page_allocator()`. That is why, `page_allocator()` is considered a\nfast, but also \"wasteful\" allocator in Zig. Because it allocates a big amount of memory\nin each call, and you most likely will not need that much memory in your program.\n\n### Buffer allocators\n\nThe `FixedBufferAllocator()` and `ThreadSafeFixedBufferAllocator()` are allocator objects that\nwork with a fixed sized buffer object at the back. In other words, they use a fixed sized buffer\nobject as the basis for the memory. When you ask these allocator objects to allocate some memory for you,\nthey are essentially reserving some amount of space inside this fixed sized buffer object for you to use.\n\nThis means that, in order to use these allocators, you must first create a buffer object in your code,\nand then, give this buffer object as an input to these allocators.\n\nThis also means that, these allocator objects can allocate memory both in the stack or in the heap.\nEverything depends on where the buffer object that you provide lives. If this buffer object lives\nin the stack, then, the memory allocated is \"stack-based\". But if it lives on the heap, then,\nthe memory allocated is \"heap-based\".\n\n\nIn the example below, I'm creating a `buffer` object on the stack that is 10 elements long.\nNotice that I give this `buffer` object to the `FixedBufferAllocator()` constructor.\nNow, because this `buffer` object is 10 elements long, this means that I am limited to this space.\nI cannot allocate more than 10 elements with this allocator object. If I try to\nallocate more than that, the `alloc()` method will return an `OutOfMemory` error value.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar buffer: [10]u8 = undefined;\nfor (0..buffer.len) |i| {\n    buffer[i] = 0; // Initialize to zero\n}\n\nvar fba = std.heap.FixedBufferAllocator.init(&buffer);\nconst allocator = fba.allocator();\nconst input = try allocator.alloc(u8, 5);\ndefer allocator.free(input);\n```\n:::\n\n\n\n\n\nRemember, the memory allocated by these allocator objects can be either from\nthe stack, or, from the heap. It all depends on where the buffer object that you provide lives.\nIn the above example, the `buffer` object lives in the stack, and, therefore, the memory allocated\nis based in the stack. But what if it was based on the heap?\n\nAs we described at @sec-stack-overflow, one of the main reasons why you would use the heap,\ninstead of the stack, is to allocate huge amounts of space to store very big objects.\nThus, let's suppose you wanted to use a very big buffer object as the basis for your\nallocator objects. You would have to allocate this very big buffer object on the heap.\nThe example below demonstrates this case.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst heap = std.heap.page_allocator;\nconst memory_buffer = try heap.alloc(\n    u8, 100 * 1024 * 1024 // 100 MB memory\n);\ndefer heap.free(memory_buffer);\nvar fba = std.heap.FixedBufferAllocator.init(\n    memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst input = try allocator.alloc(u8, 1000);\ndefer allocator.free(input);\n```\n:::\n\n\n\n\n\n\n\n### Arena allocator {#sec-arena-allocator}\n\nThe `ArenaAllocator()` is an allocator object that takes a child allocator as input. The idea behind the `ArenaAllocator()` in Zig\nis similar to the concept of \"arenas\" in the programming language Go[^go-arena]. It is an allocator object that allows you\nto allocate memory as many times you want, but free all memory only once.\nIn other words, if you have, for example, called 5 times the method `alloc()` of an `ArenaAllocator()` object, you can\nfree all the memory you allocated over these 5 calls at once, by simply calling the `deinit()` method of the same `ArenaAllocator()` object.\n\n[^go-arena]: <https://go.dev/src/arena/arena.go>\n\nIf you give, for example, a `GeneralPurposeAllocator()` object as input to the `ArenaAllocator()` constructor, like in the example below, then, the allocations\nyou perform with `alloc()` will actually be made with the underlying object `GeneralPurposeAllocator()` that was passed.\nSo, with an arena allocator, any new memory you ask for is allocated by the child allocator. The only thing that an arena allocator\nreally does is help you to free all the memory you allocated multiple times with just a single command. In the example\nbelow, I called `alloc()` 3 times. So, if I did not use an arena allocator, then, I would need to call\n`free()` 3 times to free all the allocated memory.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nvar aa = std.heap.ArenaAllocator.init(gpa.allocator());\ndefer aa.deinit();\nconst allocator = aa.allocator();\n\nconst in1 = try allocator.alloc(u8, 5);\nconst in2 = try allocator.alloc(u8, 10);\nconst in3 = try allocator.alloc(u8, 15);\n_ = in1; _ = in2; _ = in3;\n```\n:::\n\n\n\n\n\n\n\n### The `alloc()` and `free()` methods\n\nIn the code example below, we are accessing the `stdin`, which is\nthe standard input channel, to receive an input from the\nuser. We read the input given by the user with the `readUntilDelimiterOrEof()`\nmethod.\n\nNow, after reading the input of the user, we need to store this input somewhere in\nour program. That is why I use an allocator in this example. I use it to allocate some\namount of memory to store this input given by the user. More specifically, the method `alloc()`\nof the allocator object is used to allocate an array capable of storing 50 `u8` values.\n\nNotice that this `alloc()` method receives two inputs. The first one, is a type.\nThis defines what type of values the allocated array will store. In the example\nbelow, we are allocating an array of unsigned 8-bit integers (`u8`). But\nyou can create an array to store any type of value you want. Next, on the second argument, we\ndefine the size of the allocated array, by specifying how many elements\nthis array will contain. In the case below, we are allocating an array of 50 elements.\n\nAt @sec-zig-strings we described that strings in Zig are simply arrays of characters.\nEach character is represented by a `u8` value. So, this means that the array that\nwas allocated in the object `input` is capable of storing a string that is\n50-characters long.\n\nSo, in essence, the expression `var input: [50]u8 = undefined` would create\nan array for 50 `u8` values in the stack of the current scope. But, you\ncan allocate the same array in the heap by using the expression `var input = try allocator.alloc(u8, 50)`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdin = std.io.getStdIn();\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var input = try allocator.alloc(u8, 50);\n    defer allocator.free(input);\n    for (0..input.len) |i| {\n        input[i] = 0; // initialize all fields to zero.\n    }\n    // read user input\n    const input_reader = stdin.reader();\n    _ = try input_reader.readUntilDelimiterOrEof(\n        input,\n        '\\n'\n    );\n    std.debug.print(\"{s}\\n\", .{input});\n}\n```\n:::\n\n\n\n\n\nAlso, notice that in this example, we use the `defer` keyword (which I described at @sec-defer) to run a small\npiece of code at the end of the current scope, which is the expression `allocator.free(input)`.\nWhen you execute this expression, the allocator will free the memory that it allocated\nfor the `input` object.\n\nWe have talked about this at @sec-heap. You **should always** explicitly free any memory that you allocate\nusing an allocator! You do that by using the `free()` method of the same allocator object you\nused to allocate this memory. The `defer` keyword is used in this example only to help us execute\nthis free operation at the end of the current scope.\n\n\n### The `create()` and `destroy()` methods\n\nWith the `alloc()` and `free()` methods, you can allocate memory to store multiple elements\nat once. In other words, with these methods, we always allocate an array to store multiple elements at once.\nBut what if you need enough space to store just a single item? Should you\nallocate an array of a single element through `alloc()`?\n\nThe answer is no! In this case,\nyou should use the `create()` method of the allocator object.\nEvery allocator object offers the `create()` and `destroy()` methods,\nwhich are used to allocate and free memory for a single item, respectively.\n\nSo, in essence, if you want to allocate memory to store an array of elements, you\nshould use `alloc()` and `free()`. But if you need to store just a single item,\nthen, the `create()` and `destroy()` methods are ideal for you.\n\nIn the example below, I'm defining a struct to represent an user of some sort.\nIt could be an user for a game, or a software to manage resources, it doesn't mater.\nNotice that I use the `create()` method this time, to store a single `User` object\nin the program. Also notice that I use the `destroy()` method to free the memory\nused by this object at the end of the scope.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst User = struct {\n    id: usize,\n    name: []const u8,\n\n    pub fn init(id: usize, name: []const u8) User {\n        return .{ .id = id, .name = name };\n    }\n};\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const user = try allocator.create(User);\n    defer allocator.destroy(user);\n\n    user.* = User.init(0, \"Pedro\");\n}\n```\n:::\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
diff --git a/_freeze/Chapters/01-zig-weird/execute-results/html.json b/_freeze/Chapters/01-zig-weird/execute-results/html.json
index 317b33ea..9f589e01 100644
--- a/_freeze/Chapters/01-zig-weird/execute-results/html.json
+++ b/_freeze/Chapters/01-zig-weird/execute-results/html.json
@@ -1,8 +1,8 @@
 {
-  "hash": "7dd731d3bc677839fb57a945a5a74e77",
+  "hash": "ac000692a82a7bd85e0b2c4d90fd55b3",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\nlanguage, it is still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. They really make it sometimes hard to debug\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscures the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that get's compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e. it is where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `ìnit` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contain Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nTherefore, Zig contains a native build system in it, and\nwe can use this build system to write small scripts in Zig,\nwhich describes the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is the Zig package manager configuration file,\nwhere you can list and manage the dependencies of your project. Yes, Zig has\na package manager (like `pip` in Python, `cargo` in Rust, or `npm` in Javascript) called Zon,\nand this `build.zig.zon` file is similar to the `package.json` file\nin Javascript projects, or, the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects.\n\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e. creating new objects)\nare made in Zig. You can create a new object in Zig by using the following syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). At @sec-assignments we talk more about objects in general.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that at @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return\ntype of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function\nmight return an error.\n\nIn this example, the `main()` function can either return `void` or return an error.\nThis is an interesting feature of Zig. If you write a function and something inside of\nthe body of this function might return an error then you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error\n- explicitly handle this error inside the function\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does nothing. It only passes the value forward.\nBut if the expression does return an error, then, the `try` keyword just unwrap the error value,\nand return this error from the function and also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword.\nIt marks the `main()` function as a *public function* from this module.\n\nEvery function in your Zig module is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\nThis means that the `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++.\n\nBy making a function \"public\" you allow other Zig modules to access and call it.\nA calling Zig module imports the module with the `@import()`\nbuilt-in. That makes all public functions from the imported module visible.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portale C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nOn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperational systems, such as Linux and MacOs. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e. the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. Thus, if you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith a \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, operations like accessing the `stdout` (or opening a file) on Windows\ndepends on resources that are available only at *runtime* (you will learn more about compile-time\nversus runtime at @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword at @sec-comptime.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation at a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues \n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described at @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig latter in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig? \nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar in our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentations.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It is a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (at YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e. identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compiles successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nIn contrast, if you use `var`, then, the object created is a variable object.\nWith `var` you can declare this object in your source code, and then,\nchange the value of this object how many times you want over future points\nin your source code.\n\nSo, using the same code example exposed above, if I change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it is an \"variable object\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIs important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code use this object while it is uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object. \n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e. if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to an special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It is discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also get's discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e. the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\n\nIs worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array. \n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it is a slice that\naccess all elements in the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" at @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth at @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially at @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned at @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e. the start and the end of this range)\nis known at compile-time, the slice object that get's created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nat @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that get's created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e. a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can \ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n```\n:::\n\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat get's created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, the `slice` object have a runtime known range, because the end index of the range\nis not known at compile time. In other words, the size of the array at `buffer` is not known\nat compile time. When we execute this program, the size of the array might be 10, or, it might be 12\ndepending on where we execute it. Therefore, we don't know at compile time if\nthe slice object have a range of size 10, or, a range of size 12.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e. a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented at @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e. `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIs worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e. the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause is much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e. if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it is a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n:::\n\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIs important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\n```\nHello you!\n```\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operational system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligates you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig at @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers at @sec-root-file and especially at @sec-assignments.\n- How strings work in Zig at @sec-zig-strings.\n- How to use arrays and slices at @sec-arrays.\n- How to import functionality from other Zig modules at @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* at @sec-structs-and-oop.\n- Basic control flow syntax at @sec-zig-control-flow.\n- Enums at @sec-enum;\n- Pointers and Optionals at @sec-pointer;\n- Error handling with `try` and `catch` at @sec-error-handling;\n- Unit tests at @sec-unittests;\n- Vectors at @sec-vectors-simd;\n- Build System at @sec-build-system;\n\n\n\n\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\nlanguage, it is still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. They really make it sometimes hard to debug\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscures the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that get's compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e. it is where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `ìnit` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contain Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nTherefore, Zig contains a native build system in it, and\nwe can use this build system to write small scripts in Zig,\nwhich describes the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is the Zig package manager configuration file,\nwhere you can list and manage the dependencies of your project. Yes, Zig has\na package manager (like `pip` in Python, `cargo` in Rust, or `npm` in Javascript) called Zon,\nand this `build.zig.zon` file is similar to the `package.json` file\nin Javascript projects, or, the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects.\n\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e. creating new objects)\nare made in Zig. You can create a new object in Zig by using the following syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). At @sec-assignments we talk more about objects in general.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that at @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return\ntype of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function\nmight return an error.\n\nIn this example, the `main()` function can either return `void` or return an error.\nThis is an interesting feature of Zig. If you write a function and something inside of\nthe body of this function might return an error then you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error\n- explicitly handle this error inside the function\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does nothing. It only passes the value forward.\nBut if the expression does return an error, then, the `try` keyword just unwrap the error value,\nand return this error from the function and also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword.\nIt marks the `main()` function as a *public function* from this module.\n\nEvery function in your Zig module is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\nThis means that the `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++.\n\nBy making a function \"public\" you allow other Zig modules to access and call it.\nA calling Zig module imports the module with the `@import()`\nbuilt-in. That makes all public functions from the imported module visible.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portale C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nOn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperational systems, such as Linux and MacOs. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e. the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. Thus, if you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith a \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, operations like accessing the `stdout` (or opening a file) on Windows\ndepends on resources that are available only at *runtime* (you will learn more about compile-time\nversus runtime at @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword at @sec-comptime.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation at a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues \n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described at @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig latter in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig? \nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar in our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentations.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It is a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (at YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e. identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compiles successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nIn contrast, if you use `var`, then, the object created is a variable object.\nWith `var` you can declare this object in your source code, and then,\nchange the value of this object how many times you want over future points\nin your source code.\n\nSo, using the same code example exposed above, if I change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it is an \"variable object\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIs important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code use this object while it is uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object. \n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e. if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to an special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It is discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also get's discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e. the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\n\nIs worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array. \n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it is a slice that\naccess all elements in the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" at @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth at @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially at @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned at @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e. the start and the end of this range)\nis known at compile-time, the slice object that get's created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nat @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that get's created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e. a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can \ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n```\n:::\n\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat get's created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, the `slice` object have a runtime known range, because the end index of the range\nis not known at compile time. In other words, the size of the array at `buffer` is not known\nat compile time. When we execute this program, the size of the array might be 10, or, it might be 12\ndepending on where we execute it. Therefore, we don't know at compile time if\nthe slice object have a range of size 10, or, a range of size 12.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e. a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented at @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e. `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIs worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e. the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause is much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e. if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it is a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIs important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operational system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligates you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig at @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers at @sec-root-file and especially at @sec-assignments.\n- How strings work in Zig at @sec-zig-strings.\n- How to use arrays and slices at @sec-arrays.\n- How to import functionality from other Zig modules at @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* at @sec-structs-and-oop.\n- Basic control flow syntax at @sec-zig-control-flow.\n- Enums at @sec-enum;\n- Pointers and Optionals at @sec-pointer;\n- Error handling with `try` and `catch` at @sec-error-handling;\n- Unit tests at @sec-unittests;\n- Vectors at @sec-vectors-simd;\n- Build System at @sec-build-system;\n\n\n\n\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
diff --git a/_freeze/Chapters/02-debugging/execute-results/html.json b/_freeze/Chapters/02-debugging/execute-results/html.json
index 4d4bdcd7..a656866e 100644
--- a/_freeze/Chapters/02-debugging/execute-results/html.json
+++ b/_freeze/Chapters/02-debugging/execute-results/html.json
@@ -2,7 +2,7 @@
   "hash": "5bb29adee558edcbecbe21f328df9519",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Debugging Zig applications\n\nBeing able to debug your applications is essential for any programmer who wants to\ndo serious programming in any language. That is why, in this chapter, we are going to talk about the\navailable strategies and tools to debug applications written in Zig.\n\n\n## Print debugging\n\nWe begin with the classic and battle-tested *print debugging* strategy.\nThe key advantage that debugging offers you is *visibility*.\nWith *print statements* you can easily see what results and objects\nare being produced by your application.\n\nThat is the essence of *print debugging*. Is to use\nprint expressions to see the values that are being generated by your program,\nand, as a result, get a much better understanding of how your program\nis behaving.\n\nMany programmers often resort to the print functions in Zig, such as the `stdout.print()`,\nor, the `std.debug.print()`, to get a better understanding of their programs.\nThis is a known and old strategy that is very simple and effective, and it is better known within\nthe programming community as *print debugging*.\nIn Zig, you can print information to the `stdout` or `stderr` streams of your system.\n\nLet's begin with `stdout`. First, you\nneed to get access to the `stdout`, by calling the `getStdOut()` method, from\nthe Zig Standard Library. This method returns a *file descriptor* object,\nand, through this object you can read/write to the `stdout`.\nI recommend you to check out all methods available in this object, by [checking the page in\nthe Zig Standard Library Official Reference for the type `File`](https://ziglang.org/documentation/master/std/#std.fs.File)[^zig-fiile-reference].\n\n[^zig-fiile-reference]: <https://ziglang.org/documentation/master/std/#std.fs.File>.\n\nFor our purpose here, which is to write something to the `stdout`, especially to debug our\nprogram, I recommend you to use the `writer()` method, which gives your a *writer* object.\nThis *writer* object offers some helper methods to write stuff into the file descriptor object\nthat represents the `stdout` stream. In special, the `print()` method.\n\n\nThe `print()` method from this *writer* object is a \"print formatter\" type of a function.\nIn other words, this method works exactly like the `printf()` function from C,\nor, like `println!()` from Rust.\nIn the first argument of the function, you specify a template string, and,\nin the second argument, you provide a list of values (or objects) that you want to insert\ninto your template message.\n\nIdeally, the template string in the first argument should contain some format specifier.\nEach format specifier is matched to a value (or object) that you have listed in the second argument.\nSo, if you provided 5 different objects in the second argument, then, the template string\nshould contain 5 format specifiers, one for each object provided.\n\nEach format specifier is represented by a single letter, and\nyou provide this format specifier inside a pair of curly braces. So, if you want to format\nyour object using the string specifier (`s`), then, you can insert the text `{s}` in your template string.\nHere is a quick list of the most used format specifiers:\n\n- `d`: for printing integers and floating-point numbers.\n- `c`: for printing characters.\n- `s`: for printing strings.\n- `p`: for printing memory addresses.\n- `x`: for printing hexadecimal values.\n- `any`: use any compatible format specifier (i.e. it automatically selects a format specifier for you).\n\nThe code example below gives you an example of use of this `print()` method\nwith the `d` format specifier.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    _ = try stdout.print(\"Result: {d}\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\n\n\nIs important to emphasize that, the `stdout.print()` method, as you would expect,\nprint your template string into the `stdout` stream of your system.\nHowever, you can also print your template string into the `stderr` stream\nif your prefer. All you need to do, is to replace the `stdout.print()`\ncall with the function `std.debug.print()`. Like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    std.debug.print(\"Result: {d}\\n\", .{result});\n}\n```\n:::\n\n\n\n\n```\nResult: 50\n```\n\nYou could also achieve the exact same result by getting a file descriptor object to `stderr`,\nthen, creating a *writer* object to `stderr`, then, using the `print()` method of this\n*writer* object, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stderr = std.io.getStdErr().writer();\n// some more lines ...\n_ = try stderr.print(\"Result: {d}\", .{result});\n```\n:::\n\n\n\n\n\n\n## Debugging through debuggers\n\nAlthough *print debugging* being a valid and very useful strategy,\nmost programmers prefer to use a debugger to debug their programs.\nSince Zig is a low-level language, you can use either GDB (GNU Debugger),\nor LLDB (LLVM Project Debugger) as your debugger.\n\nBoth debuggers can work with Zig code, and it's a matter of taste here.\nYou choose the debugger of your preference, and you work with it.\nIn this book, I will use LLDB as my debugger on the examples.\n\n\n### Compile your source code in debug mode {#sec-compile-debug-mode}\n\nIn order to debug your program through a debugger, you must compile\nyour source code in `Debug` mode. Because when you compile your\nsource code in other modes (such as `Release`), the compiler usually\nstrips out some essential information that is used by the debugger\nto read and track your program, like PDB (*Program Database*) files.\n\nBy compiling your source code in `Debug` mode, you ensure that the debugger\nwill find the necessary information in your program to debug it.\nBy default, the compiler uses the `Debug` mode when compiling your code.\nHaving this in mind, when you compile your program with the `build-exe`\ncommand (which was described at @sec-compile-code), if you don't specify\nan explicit mode through the `-O` command-line [^oargument]\nargument, then, the compiler will compile your code in `Debug` mode.\n\n[^oargument]: See <https://ziglang.org/documentation/master/#Debug>.\n\n\n### Let's debug a program\n\nAs an example, let's use LLDB to navigate and investigate the following\npiece of Zig code:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\nfn add_and_increment(a: u8, b: u8) u8 {\n    const sum = a + b;\n    const incremented = sum + 1;\n    return incremented;\n}\n\npub fn main() !void {\n    var n = add_and_increment(2, 3);\n    n = add_and_increment(n, n);\n    _ = try stdout.print(\"Result: {d}!\\n\", .{n});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 13!\n```\n\n\n:::\n:::\n\n\n\n\nThere is nothing wrong with this program. But it is\na good start for us. First, we need to compile\nthis program with the `zig build-exe` command.\nFor this example, suppose that I have compiled the above\nZig code into a binary executable called `add_program`.\n\n```bash\nzig build-exe add_program.zig\n```\n\nNow, we can start LLDB with `add_program`, like this:\n\n```bash\nlldb add_program\n```\n\nFrom now on, LLDB is started, and you can know that I'm\nexecuting LLDB commands by looking at the prefix `(lldb)`.\nIf something is prefixed with `(lldb)`, then you know\nthat it is a LLDB command.\n\nThe first thing I will do, is to set a breakpoint at\nthe `main()` function, by executing `b main`.\nAfter that, I just start the execution of the program\nwith `run`.\nYou can see in the output below, that the execution\nstopped at the first line in the function `main()`, as we expected.\n\n```bash\n(lldb) b main\nBreakpoint 1: where = debugging`debug1.main + 22\n    at debug1.zig:11:30, address = 0x00000000010341a6\n(lldb) run\nProcess 8654 launched: 'add_program' (x86_64)\nProcess 8654 stopped\n* thread #1, name = 'add_program',\n    stop reason = breakpoint 1.1 frame #0: 0x10341a6\n    add_program`debug1.main at add_program.zig:11:30\n   8   \t}\n   9   \t\n   10  \tpub fn main() !void {\n-> 11  \t    var n = add_and_increment(2, 3);\n   12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n```\n\nI can start navigating through the code, and checking the objects\nthat are being generated. If you are not familiar with the commands\navailable in LLDB, I recommend you to read the official documentation\nof the project[^lldb].\nYou can also look for cheat sheets, which quickly describes all commands\navailable for you[^lldb-quick-list].\n\n[^lldb]: <https://lldb.llvm.org/>\n[^lldb-quick-list]: <https://gist.github.com/ryanchang/a2f738f0c3cc6fbd71fa>.\n\nCurrently, we are in the first line at the `main()` function. In this line, we create\nthe `n` object, by executing the `add_and_increment()` function.\nTo execute the current line of code, and go to the next line, we can\nrun the `n` LLDB command. Let's execute this command.\n\nAfter we executed this line, we can also look at the value stored inside this `n` object\nby using the `p` LLDB command. The syntax for this command is `p <name-of-object>`.\n\nIf we take a look at the value stored in the `n` object (`p n`),\nnotice that it stores the hexadecimal value `0x06`, which\nis the number 6 in decimal. We can also see that, this value have a type `unsigned char`,\nwhich is an unsigned 8-bit integer.\nWe have talked already about this at @sec-zig-strings, that `u8` integers in Zig are equivalent\nto the C data type `unsigned char`.\n\n\n\n```bash\n(lldb) n\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step over frame #0: 0x10341ae\n    debugging`debug1.main at debug1.zig:12:26\n   9   \t\n   10  \tpub fn main() !void {\n   11  \t    var n = add_and_increment(2, 3);\n-> 12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n(lldb) p n\n(unsigned char) $1 = '\\x06'\n```\n\nNow, on the next line of code, we are executing the `add_and_increment()` function once again.\nWhy not step inside this function? Shall we? We can do that, by executing the `s` LLDB command.\nNotice in the example below that, after executing this command, we have entered into the context of the\n`add_and_increment()` function.\n\nAlso notice in the example below that, I have walked two more lines in the function's body, then,\nI execute the `frame variable` LLDB command, to see at once, the value stored in each of the variables\nthat were created inside the current scope.\n\nYou can see in the output below that, the object `sum` stores the value `\\f`,\nwhich represents the *form feed* character. This character in the ASCII table,\ncorresponds to the hexadecimal value `0x0C`, or, in decimal, the number 12.\nSo, this means that the result of the expression `a + b` executed at line\n5, resulted in the number 12.\n\n```bash\n(lldb) s\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step in frame #0: 0x10342de\n    debugging`debug1.add_and_increment(a='\\x02', b='\\x03')\n    at debug1.zig:4:39\n-> 4   \tfn add_and_increment(a: u8, b: u8) u8 {\n   5   \t    const sum = a + b;\n   6   \t    const incremented = sum + 1;\n   7   \t    return incremented;\n(lldb) n\n(lldb) n\n(lldb) frame variable\n(unsigned char) a = '\\x06'\n(unsigned char) b = '\\x06'\n(unsigned char) sum = '\\f'\n(unsigned char) incremented = '\\x06'\n```\n\n\n\n## How to investigate the data type of your objects\n\nSince Zig is a strongly-typed language, the data types associated with your objects\nare very important for your program. So, debugging the data types associated\nwith your objects might be important to understand bugs and errors in your program.\n\nWhen you walk through your program with a debugger, you can inspect the types of\nyour objects by simply printing them to the console, with the LLDB `p` command.\nBut you also have alternatives embedded in the language itself to access the data\ntypes of your objects.\n\nIn Zig, you can retrieve the data type of an object, by using the built-in function\n`@TypeOf()`. Just apply this function over the object, and you get access to \nthe data type of the object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst expect = std.testing.expect;\n\npub fn main() !void {\n    const number: i32 = 5;\n    try expect(@TypeOf(number) == i32);\n    try stdout.print(\"{any}\\n\", .{@TypeOf(number)});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ni32\n```\n\n\n:::\n:::\n\n\n\n\nThis function is similar to the `type()` built-in function from Python,\nor, the `typeof` operator in Javascript.\n\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Debugging Zig applications\n\nBeing able to debug your applications is essential for any programmer who wants to\ndo serious programming in any language. That is why, in this chapter, we are going to talk about the\navailable strategies and tools to debug applications written in Zig.\n\n\n## Print debugging\n\nWe begin with the classic and battle-tested *print debugging* strategy.\nThe key advantage that debugging offers you is *visibility*.\nWith *print statements* you can easily see what results and objects\nare being produced by your application.\n\nThat is the essence of *print debugging*. Is to use\nprint expressions to see the values that are being generated by your program,\nand, as a result, get a much better understanding of how your program\nis behaving.\n\nMany programmers often resort to the print functions in Zig, such as the `stdout.print()`,\nor, the `std.debug.print()`, to get a better understanding of their programs.\nThis is a known and old strategy that is very simple and effective, and it is better known within\nthe programming community as *print debugging*.\nIn Zig, you can print information to the `stdout` or `stderr` streams of your system.\n\nLet's begin with `stdout`. First, you\nneed to get access to the `stdout`, by calling the `getStdOut()` method, from\nthe Zig Standard Library. This method returns a *file descriptor* object,\nand, through this object you can read/write to the `stdout`.\nI recommend you to check out all methods available in this object, by [checking the page in\nthe Zig Standard Library Official Reference for the type `File`](https://ziglang.org/documentation/master/std/#std.fs.File)[^zig-fiile-reference].\n\n[^zig-fiile-reference]: <https://ziglang.org/documentation/master/std/#std.fs.File>.\n\nFor our purpose here, which is to write something to the `stdout`, especially to debug our\nprogram, I recommend you to use the `writer()` method, which gives your a *writer* object.\nThis *writer* object offers some helper methods to write stuff into the file descriptor object\nthat represents the `stdout` stream. In special, the `print()` method.\n\n\nThe `print()` method from this *writer* object is a \"print formatter\" type of a function.\nIn other words, this method works exactly like the `printf()` function from C,\nor, like `println!()` from Rust.\nIn the first argument of the function, you specify a template string, and,\nin the second argument, you provide a list of values (or objects) that you want to insert\ninto your template message.\n\nIdeally, the template string in the first argument should contain some format specifier.\nEach format specifier is matched to a value (or object) that you have listed in the second argument.\nSo, if you provided 5 different objects in the second argument, then, the template string\nshould contain 5 format specifiers, one for each object provided.\n\nEach format specifier is represented by a single letter, and\nyou provide this format specifier inside a pair of curly braces. So, if you want to format\nyour object using the string specifier (`s`), then, you can insert the text `{s}` in your template string.\nHere is a quick list of the most used format specifiers:\n\n- `d`: for printing integers and floating-point numbers.\n- `c`: for printing characters.\n- `s`: for printing strings.\n- `p`: for printing memory addresses.\n- `x`: for printing hexadecimal values.\n- `any`: use any compatible format specifier (i.e. it automatically selects a format specifier for you).\n\nThe code example below gives you an example of use of this `print()` method\nwith the `d` format specifier.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    _ = try stdout.print(\"Result: {d}\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\n\n\nIs important to emphasize that, the `stdout.print()` method, as you would expect,\nprint your template string into the `stdout` stream of your system.\nHowever, you can also print your template string into the `stderr` stream\nif your prefer. All you need to do, is to replace the `stdout.print()`\ncall with the function `std.debug.print()`. Like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    std.debug.print(\"Result: {d}\\n\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\n\n\n```\nResult: 50\n```\n\nYou could also achieve the exact same result by getting a file descriptor object to `stderr`,\nthen, creating a *writer* object to `stderr`, then, using the `print()` method of this\n*writer* object, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stderr = std.io.getStdErr().writer();\n// some more lines ...\n_ = try stderr.print(\"Result: {d}\", .{result});\n```\n:::\n\n\n\n\n\n\n## Debugging through debuggers\n\nAlthough *print debugging* being a valid and very useful strategy,\nmost programmers prefer to use a debugger to debug their programs.\nSince Zig is a low-level language, you can use either GDB (GNU Debugger),\nor LLDB (LLVM Project Debugger) as your debugger.\n\nBoth debuggers can work with Zig code, and it's a matter of taste here.\nYou choose the debugger of your preference, and you work with it.\nIn this book, I will use LLDB as my debugger on the examples.\n\n\n### Compile your source code in debug mode {#sec-compile-debug-mode}\n\nIn order to debug your program through a debugger, you must compile\nyour source code in `Debug` mode. Because when you compile your\nsource code in other modes (such as `Release`), the compiler usually\nstrips out some essential information that is used by the debugger\nto read and track your program, like PDB (*Program Database*) files.\n\nBy compiling your source code in `Debug` mode, you ensure that the debugger\nwill find the necessary information in your program to debug it.\nBy default, the compiler uses the `Debug` mode when compiling your code.\nHaving this in mind, when you compile your program with the `build-exe`\ncommand (which was described at @sec-compile-code), if you don't specify\nan explicit mode through the `-O` command-line [^oargument]\nargument, then, the compiler will compile your code in `Debug` mode.\n\n[^oargument]: See <https://ziglang.org/documentation/master/#Debug>.\n\n\n### Let's debug a program\n\nAs an example, let's use LLDB to navigate and investigate the following\npiece of Zig code:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\nfn add_and_increment(a: u8, b: u8) u8 {\n    const sum = a + b;\n    const incremented = sum + 1;\n    return incremented;\n}\n\npub fn main() !void {\n    var n = add_and_increment(2, 3);\n    n = add_and_increment(n, n);\n    _ = try stdout.print(\"Result: {d}!\\n\", .{n});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 13!\n```\n\n\n:::\n:::\n\n\n\n\nThere is nothing wrong with this program. But it is\na good start for us. First, we need to compile\nthis program with the `zig build-exe` command.\nFor this example, suppose that I have compiled the above\nZig code into a binary executable called `add_program`.\n\n```bash\nzig build-exe add_program.zig\n```\n\nNow, we can start LLDB with `add_program`, like this:\n\n```bash\nlldb add_program\n```\n\nFrom now on, LLDB is started, and you can know that I'm\nexecuting LLDB commands by looking at the prefix `(lldb)`.\nIf something is prefixed with `(lldb)`, then you know\nthat it is a LLDB command.\n\nThe first thing I will do, is to set a breakpoint at\nthe `main()` function, by executing `b main`.\nAfter that, I just start the execution of the program\nwith `run`.\nYou can see in the output below, that the execution\nstopped at the first line in the function `main()`, as we expected.\n\n```bash\n(lldb) b main\nBreakpoint 1: where = debugging`debug1.main + 22\n    at debug1.zig:11:30, address = 0x00000000010341a6\n(lldb) run\nProcess 8654 launched: 'add_program' (x86_64)\nProcess 8654 stopped\n* thread #1, name = 'add_program',\n    stop reason = breakpoint 1.1 frame #0: 0x10341a6\n    add_program`debug1.main at add_program.zig:11:30\n   8   \t}\n   9   \t\n   10  \tpub fn main() !void {\n-> 11  \t    var n = add_and_increment(2, 3);\n   12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n```\n\nI can start navigating through the code, and checking the objects\nthat are being generated. If you are not familiar with the commands\navailable in LLDB, I recommend you to read the official documentation\nof the project[^lldb].\nYou can also look for cheat sheets, which quickly describes all commands\navailable for you[^lldb-quick-list].\n\n[^lldb]: <https://lldb.llvm.org/>\n[^lldb-quick-list]: <https://gist.github.com/ryanchang/a2f738f0c3cc6fbd71fa>.\n\nCurrently, we are in the first line at the `main()` function. In this line, we create\nthe `n` object, by executing the `add_and_increment()` function.\nTo execute the current line of code, and go to the next line, we can\nrun the `n` LLDB command. Let's execute this command.\n\nAfter we executed this line, we can also look at the value stored inside this `n` object\nby using the `p` LLDB command. The syntax for this command is `p <name-of-object>`.\n\nIf we take a look at the value stored in the `n` object (`p n`),\nnotice that it stores the hexadecimal value `0x06`, which\nis the number 6 in decimal. We can also see that, this value have a type `unsigned char`,\nwhich is an unsigned 8-bit integer.\nWe have talked already about this at @sec-zig-strings, that `u8` integers in Zig are equivalent\nto the C data type `unsigned char`.\n\n\n\n```bash\n(lldb) n\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step over frame #0: 0x10341ae\n    debugging`debug1.main at debug1.zig:12:26\n   9   \t\n   10  \tpub fn main() !void {\n   11  \t    var n = add_and_increment(2, 3);\n-> 12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n(lldb) p n\n(unsigned char) $1 = '\\x06'\n```\n\nNow, on the next line of code, we are executing the `add_and_increment()` function once again.\nWhy not step inside this function? Shall we? We can do that, by executing the `s` LLDB command.\nNotice in the example below that, after executing this command, we have entered into the context of the\n`add_and_increment()` function.\n\nAlso notice in the example below that, I have walked two more lines in the function's body, then,\nI execute the `frame variable` LLDB command, to see at once, the value stored in each of the variables\nthat were created inside the current scope.\n\nYou can see in the output below that, the object `sum` stores the value `\\f`,\nwhich represents the *form feed* character. This character in the ASCII table,\ncorresponds to the hexadecimal value `0x0C`, or, in decimal, the number 12.\nSo, this means that the result of the expression `a + b` executed at line\n5, resulted in the number 12.\n\n```bash\n(lldb) s\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step in frame #0: 0x10342de\n    debugging`debug1.add_and_increment(a='\\x02', b='\\x03')\n    at debug1.zig:4:39\n-> 4   \tfn add_and_increment(a: u8, b: u8) u8 {\n   5   \t    const sum = a + b;\n   6   \t    const incremented = sum + 1;\n   7   \t    return incremented;\n(lldb) n\n(lldb) n\n(lldb) frame variable\n(unsigned char) a = '\\x06'\n(unsigned char) b = '\\x06'\n(unsigned char) sum = '\\f'\n(unsigned char) incremented = '\\x06'\n```\n\n\n\n## How to investigate the data type of your objects\n\nSince Zig is a strongly-typed language, the data types associated with your objects\nare very important for your program. So, debugging the data types associated\nwith your objects might be important to understand bugs and errors in your program.\n\nWhen you walk through your program with a debugger, you can inspect the types of\nyour objects by simply printing them to the console, with the LLDB `p` command.\nBut you also have alternatives embedded in the language itself to access the data\ntypes of your objects.\n\nIn Zig, you can retrieve the data type of an object, by using the built-in function\n`@TypeOf()`. Just apply this function over the object, and you get access to \nthe data type of the object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst expect = std.testing.expect;\n\npub fn main() !void {\n    const number: i32 = 5;\n    try expect(@TypeOf(number) == i32);\n    try stdout.print(\"{any}\\n\", .{@TypeOf(number)});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ni32\n```\n\n\n:::\n:::\n\n\n\n\nThis function is similar to the `type()` built-in function from Python,\nor, the `typeof` operator in Javascript.\n\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
diff --git a/_freeze/Chapters/03-structs/execute-results/html.json b/_freeze/Chapters/03-structs/execute-results/html.json
index a9593c0d..549083fc 100644
--- a/_freeze/Chapters/03-structs/execute-results/html.json
+++ b/_freeze/Chapters/03-structs/execute-results/html.json
@@ -1,8 +1,8 @@
 {
-  "hash": "fe9a62d3c3cabeb2802974d2becced51",
+  "hash": "5d7f2c2e3cfbfb6754b90978cd0a4b89",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Control flow, structs, modules and types\n\nWe have discussed a lot of Zig's syntax in the last chapter,\nespecially in @sec-root-file and @sec-main-file.\nBut we still need to discuss some other very important\nelements of the language. Elements that you will use constantly on your day-to-day\nroutine.\n\nWe begin this chapter by discussing the different keywords and structures\nin Zig related to control flow (e.g. loops and if statements).\nThen, we talk about structs and how they can be used to do some\nbasic Object-Oriented (OOP) patterns in Zig. We also talk about\ntype inference and type casting.\nFinally, we end this chapter by discussing modules, and how they relate\nto structs.\n\n\n\n## Control flow {#sec-zig-control-flow}\n\nSometimes, you need to make decisions in your program. Maybe you need to decide\nwhether or not to execute a specific piece of code. Or maybe,\nyou need to apply the same operation over a sequence of values. These kinds of tasks,\ninvolve using structures that are capable of changing the \"control flow\" of our program.\n\nIn computer science, the term \"control flow\" usually refers to the order in which expressions (or commands)\nare evaluated in a given language or program. But this term is also used to refer\nto structures that are capable of changing this \"evaluation order\" of the commands\nexecuted by a given language/program.\n\nThese structures are better known\nby a set of terms, such as: loops, if/else statements, switch statements, among others. So,\nloops and if/else statements are examples of structures that can change the \"control\nflow\" of our program. The keywords `continue` and `break` are also examples of symbols\nthat can change the order of evaluation, since they can move our program to the next iteration\nof a loop, or make the loop stop completely.\n\n\n### If/else statements\n\nAn if/else statement performs a \"conditional flow operation\".\nA conditional flow control (or choice control) allows you to execute\nor ignore a certain block of commands based on a logical condition.\nMany programmers and computer science professionals also use\nthe term \"branching\" in this case.\nIn essence, an if/else statement allow us to use the result of a logical test\nto decide whether or not to execute a given block of commands.\n\nIn Zig, we write if/else statements by using the keywords `if` and `else`.\nWe start with the `if` keyword followed by a logical test inside a pair\nof parentheses, followed by a pair of curly braces which contains the lines\nof code to be executed in case the logical test returns the value `true`.\n\nAfter that, you can optionally add an `else` statement. To do that, just add the `else`\nkeyword followed by a pair of curly braces, with the lines of code\nto executed in case the logical test defined at `if` returns `false`.\n\nIn the example below, we are testing if the object `x` contains a number\nthat is greater than 10. Judging by the output printed to the console,\nwe know that this logical test returned `false`. Because the output\nin the console is compatible with the line of code present in the\n`else` branch of the if/else statement.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x = 5;\nif (x > 10) {\n    try stdout.print(\n        \"x > 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x <= 10!\\n\", .{}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nx <= 10!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Switch statements {#sec-switch}\n\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust.\nAs you would expect, to write a switch statement in Zig we use the `switch` keyword.\nWe provide the value that we want to \"switch over\" inside a\npair of parentheses. Then, we list the possible combinations (or \"branches\")\ninside a pair of curly braces.\n\nLet's take a look at the code example below. You can see that\nI'm creating an enum type called `Role`. We talk more about enums in @sec-enum.\nBut in summary, this `Role` type is listing different types of roles in a fictitious\ncompany, like `SE` for Software Engineer, `DE` for Data Engineer, `PM` for Product Manager,\netc.\n\nNotice that we are using the value from the `role` object in the\nswitch statement, to discover which exact area we need to store in the `area` variable object.\nAlso notice that we are using type inference inside the switch statement, with the dot character,\nas we are going to describe in @sec-type-inference.\nThis makes the `zig` compiler infer the correct data type of the values (`PM`, `SE`, etc.) for us.\n\nAlso notice that, we are grouping multiple values in the same branch of the switch statement.\nWe just separate each possible value with a comma. For example, if `role` contains either `DE` or `DA`,\nthe `area` variable would contain the value `\"Data & Analytics\"`, instead of `\"Platform\"` or `\"Sales\"`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO => {\n            area = \"Platform\";\n        },\n        .DE, .DA => {\n            area = \"Data & Analytics\";\n        },\n        .KS => {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nPlatform\n```\n\n\n:::\n:::\n\n\n\n\n\n#### Switch statements must exhaust all possibilities\n\nOne very important aspect about switch statements in Zig\nis that they must exhaust all existing possibilities.\nIn other words, all possible values that could be found inside the `order`\nobject must be explicitly handled in this switch statement.\n\nSince the `role` object have type `Role`, the only possible values to\nbe found inside this object are `PM`, `SE`, `DPE`, `PO`, `DE`, `DA` and `KS`.\nThere are no other possible values to be stored in this `role` object.\nThus, the switch statements must have a combination (branch) for each one of these values.\nThis is what \"exhaust all existing possibilities\" means. The switch statement covers\nevery possible case.\n\nTherefore, you cannot write a switch statement in Zig, and leave an edge case\nwith no explicit action to be taken.\nThis is a similar behaviour to switch statements in Rust, which also have to\nhandle all possible cases.\n\n\n\n#### The else branch\n\nTake a look at the `dump_hex_fallible()` function below as an example. This function\ncomes from the Zig Standard Library. More precisely, from the\n[`debug.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/debug.zig)[^debug-mod].\nThere are multiple lines in this function, but I omitted them to focus solely on the\nswitch statement found in this function. Notice that this switch statement has four\npossible cases (i.e. four explicit branches). Also, notice that we used an `else` branch\nin this case.\n\nAn `else` branch in a switch statement works as the \"default branch\".\nWhenever you have multiple cases in your switch statement where\nyou want to apply the exact same action, you can use an `else` branch to do that.\n\n[^debug-mod]: <https://github.com/ziglang/zig/blob/master/lib/std/debug.zig>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' => try writer.writeAll(\"␊\"),\n        '\\r' => try writer.writeAll(\"␍\"),\n        '\\t' => try writer.writeAll(\"␉\"),\n        else => try writer.writeByte('.'),\n    }\n}\n```\n:::\n\n\n\n\nMany programmers would also use an `else` branch to handle a \"not supported\" case.\nThat is, a case that cannot be properly handled by your code, or, just a case that\nshould not be \"fixed\". Therefore, you can use an `else` branch to panic (or raise an error)\nin your program to stop the current execution.\n\nTake the code example below. We can see that, we are handling the cases\nfor the `level` object being either 1, 2, or 3. All other possible cases are not supported by default,\nand, as consequence, we raise a runtime error in such cases through the `@panic()` built-in function.\n\nAlso notice that, we are assigning the result of the switch statement to a new object called `category`.\nThis is another thing that you can do with switch statements in Zig. If a branch\noutputs a value as result, you can store the result value of the switch statement into\na new object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 => \"beginner\",\n    3 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n:::\n\n\n\n\n```\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n```\n\n\n\n#### Using ranges in switch\n\nFurthermore, you can also use ranges of values in switch statements.\nThat is, you can create a branch in your switch statement that is used\nwhenever the input value is within the specified range. These \"range expressions\"\nare created with the operator `...`. It is important\nto emphasize that the ranges created by this operator are\ninclusive on both ends.\n\nFor example, I could easily change the previous code example to support all\nlevels between 0 and 100. Like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 => \"beginner\",\n    26...75 => \"intermediary\",\n    76...100 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nbeginner\n```\n\n\n:::\n:::\n\n\n\n\nThis is neat, and it works with character ranges too. That is, I could\nsimply write `'a'...'z'`, to match any character value that is a\nlowercase letter, and it would work fine.\n\n\n#### Labeled switch statements\n\nIn @sec-blocks we have talked about labeling blocks, and also, about using these labels\nto return a value from the block. Well, from version 0.14.0 and onwards of the `zig` compiler,\nyou can also apply labels over switch statements, which makes it possible to almost implement a\n\"C `goto`\" like pattern.\n\nFor example, if you give the label `xsw` to a switch statement, you can use this\nlabel in conjunction with the `continue` keyword to go back to the beginning of the switch\nstatement. In the example below, the execution goes back to the beginning of the\nswitch statement two times, before ending at the `3` branch.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nxsw: switch (@as(u8, 1)) {\n    1 => {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 => continue :xsw 3,\n    3 => return,\n    4 => {},\n    else => {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n```\n:::\n\n\n\n\n\n### The `defer` keyword {#sec-defer}\n\nWith the `defer` keyword you can register an expression to be executed when you exit the current scope.\nTherefore, this keyword has a similar functionality as the `on.exit()` function from R.\nTake the `foo()` function below as an example. When we execute this `foo()` function, the expression\nthat prints the message \"Exiting function ...\" is getting executed only when the function exits\nits scope.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nAdding some numbers ...\nMultiplying ...\nExiting function ...\n```\n\nTherefore, we can use `defer` to declare an expression that is going to be executed\nwhen your code exits the current scope. Some programmers like to interpret the phrase \"exit of the current scope\"\nas \"the end of the current scope\". But this interpretation might not be entirely correct, depending\non what you consider as \"the end of the current scope\".\n\nI mean, what do you consider as **the end** of the current scope? Is it the closing curly bracket (`}`) of the scope?\nIs it when the last expression in the function get's executed? Is it when the function returns to the previous scope?\nEtc. For example, it would not be correct to interpret the \"exit of the current scope\" as the closing\ncurly bracket of the scope. Because the function might exit from an earlier position than this\nclosing curly bracket (e.g. an error value was generated at a previous line inside the function;\nthe function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\n\nNow, if you remember of what we have discussed in @sec-blocks, there are multiple structures in the language\nthat create their own separate scopes. For/while loops, if/else statements,\nfunctions, normal blocks, etc. This also affects the interpretation of `defer`.\nFor example, if you use `defer` inside a for loop, then, the given expression\nwill be executed everytime this specific for loop exits its own scope.\n\nBefore we continue, is worth emphasizing that the `defer` keyword is an \"unconditional defer\".\nWhich means that the given expression will be executed no matter how the code exits\nthe current scope. For example, your code might exit the current scope because of an error value\nbeing generated, or, because of a return statement, or, a break statement, etc.\n\n\n\n### The `errdefer` keyword {#sec-errdefer1}\n\nOn the previous section, we have discussed the `defer` keyword, which you can use to\nregister an expression to be executed at the exit of the current scope.\nBut this keyword has a brother, which is the `errdefer` keyword. While `defer`\nis an \"unconditional defer\", the `errdefer` keyword is a \"conditional defer\".\nWhich means that the given expression is executed only when you exit the current\nscope on a very specific circumstance.\n\nIn more details, the expression given to `errdefer` is executed only when an error occurs in the current scope.\nTherefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope\nin a normal situation, without errors, the expression given to `errdefer` is not executed.\n\nThis makes the `errdefer` keyword one of the many tools available in Zig for error handling.\nIn this section, we are more concerned with the control flow aspects around `errdefer`.\nBut we are going to discuss `errdefer` later as a error handling tool in @sec-errdefer2.\n\nThe code example below demonstrates three things:\n\n- that `defer` is an \"unconditional defer\", because the given expression get's executed regardless of how the function `foo()` exits its own scope.\n- that `errdefer` is executed because the function `foo()` returned an error value.\n- that `defer` and `errdefer` expressions are executed in a LIFO (*last in, first out*) order.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\nWhen I say that \"defer expressions\" are executed in a LIFO order, what I want to say is that\nthe last `defer` or `errdefer` expressions in the code are the first ones to be executed.\nYou could also interpret this as: \"defer expressions\" are executed from bottom to top, or,\nfrom last to first.\n\nTherefore, if I change the order of the `defer` and `errdefer` expressions, you will notice that\nthe value of `i` that get's printed to the console changes to 1. This doesn't mean that the\n`defer` expression was not executed in this case. This actually means that the `defer` expression\nwas executed only after the `errdefer` expression. The code example below demonstrates this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\n\n\n### For loops\n\nA loop allows you to execute the same lines of code multiple times,\nthus, creating a \"repetition space\" in the execution flow of your program.\nLoops are particularly useful when we want to replicate the same function\n(or the same set of commands) over different inputs.\n\nThere are different types of loops available in Zig. But the most\nessential of them all is probably the *for loop*. A for loop is\nused to apply the same piece of code over the elements of a slice, or, an array.\n\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from\nother languages. You start with the `for` keyword, then, you\nlist the items that you want to iterate\nover inside a pair of parentheses. Then, inside of a pair of pipes (`|`)\nyou should declare an identifier that will serve as your iterator, or,\nthe \"repetition index of the loop\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (items) |value| {\n    // code to execute\n}\n```\n:::\n\n\n\n\nTherefore, instead of using a `(value in items)` syntax,\nin Zig, for loops use the syntax `(items) |value|`. In the example\nbelow, you can see that we are looping through the items\nof the array stored at the object `name`, and printing to the\nconsole the decimal representation of each character in this array.\n\nIf we wanted, we could also iterate through a slice (or a portion) of\nthe array, instead of iterating through the entire array stored in the `name` object.\nJust use a range selector to select the section you want. For example,\nI could provide the expression `name[0..3]` to the for loop, to iterate\njust through the first 3 elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n80 | 101 | 100 | 114 | 111 | \n```\n\n\n:::\n:::\n\n\n\n\nIn the above example we are using the value itself of each\nelement in the array as our iterator. But there are many situations where\nwe need to use an index instead of the actual values of the items.\n\nYou can do that by providing a second set of items to iterate over.\nMore precisely, you provide the range selector `0..` to the for loop. So,\nyes, you can use two different iterators at the same time in a for\nloop in Zig.\n\nBut remember from @sec-assignments that, every object\nyou create in Zig must be used in some way. So if you declare two iterators\nin your for loop, you must use both iterators inside the for loop body.\nBut if you want to use just the index iterator, and not use the \"value iterator\",\nthen, you can discard the value iterator by maching the\nvalue items to the underscore character, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n:::\n\n\n\n\n```\n0 | 1 | 2 | 3 | 4 |\n```\n\n\n### While loops\n\nA while loop is created from the `while` keyword. A `for` loop\niterates through the items of an array, but a `while` loop\nwill loop continuously, and infinitely, until a logical test\n(specified by you) becomes false.\n\nYou start with the `while` keyword, then, you define a logical\nexpression inside a pair of parentheses, and the body of the\nloop is provided inside a pair of curly braces, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\nYou can also specify the increment expression to be used at the beginning of a while loop.\nTo do that, we write the increment expression inside a pair of parentheses after a colon character (`:`).\nThe code example below demonstrates this other pattern.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\n### Using `break` and `continue`\n\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using\nthe keywords `break` and `continue`, respectively. The `while` loop presented in the next code example is,\nat first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to `true`.\nBut what makes this `while` loop stop when the `i` object reaches the count\n10? It is the `break` keyword!\n\nInside the while loop, we have an if statement that is constantly checking if the `i` variable\nis equal to 10. Since we are incrementing the value of `i` at each iteration of the\nwhile loop, this `i` object will eventually be equal to 10, and when it is, the if statement\nwill execute the `break` expression, and, as a result, the execution of the while loop is stopped.\n\nNotice the use of the `expect()` function from the Zig Standard Library after the while loop.\nThis `expect()` function is an \"assert\" type of function.\nThis function checks if the logical test provided is equal to true. If so, the function do nothing.\nOtherwise (i.e. the logical test is equal to false), the function raises an assertion error.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nEverything worked!\n```\n\n\n:::\n:::\n\n\n\n\nSince this code example was executed successfully by the `zig` compiler,\nwithout raising any errors, we known that, after the execution of the while loop,\nthe `i` object is equal to 10. Because if it wasn't equal to 10, an error would have\nbeen raised by `expect()`.\n\nNow, in the next example, we have a use case for\nthe `continue` keyword. The if statement is constantly\nchecking if the current index is a multiple of 2. If\nit is, we jump to the next iteration of the loop.\nOtherwise, the loop just prints the current index to the console.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 3 | 5 | \n```\n\n\n:::\n:::\n\n\n\n\n\n\n## Function parameters are immutable {#sec-fun-pars}\n\nWe have already discussed a lot of the syntax behind function declarations in @sec-root-file and @sec-main-file.\nBut I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig.\nIn summary, function parameters are immutable in Zig.\n\nTake the code example below, where we declare a simple function that just tries to add\nsome amount to the input integer, and returns the result back. If you look closely\nat the body of this `add2()` function, you will notice that we try\nto save the result back into the `x` function argument.\n\nIn other words, this function not only uses the value that it received through the function argument\n`x`, but it also tries to change the value of this function argument, by assigning the addition result\ninto `x`. However, function arguments in Zig are immutable. You cannot change their values, or, you\ncannot assign values to them inside the body's function.\n\nThis is the reason why, the code example below does not compile successfully. If you try to compile\nthis code example, you will get a compile error message about \"trying to change the value of a\nimmutable (i.e. constant) object\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n\n\n```\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n```\n\n\n### A free optimization\n\nIf a function argument receives as input an object whose data type is\nany of the primitive types that we have listed in @sec-primitive-data-types,\nthis object is always passed by value to the function. In other words, this object\nis copied into the function stack frame.\n\nHowever, if the input object have a more complex data type, for example, it might\nbe a struct instance, or an array, or an union value, etc., in cases like that, the `zig` compiler\nwill take the liberty of deciding for you which strategy is best. Thus, the `zig` compiler will\npass your object to the function either by value, or by reference. The compiler will always\nchoose the strategy that is faster for you.\nThis optimization that you get for free is possible only because function arguments are\nimmutable in Zig.\n\n\n### How to overcome this barrier\n\nThere are some situations where you might need to change the value of your function argument\ndirectly inside the function's body. This happens more often when we are passing\nC structs as inputs to Zig functions.\n\nIn a situation like this, you can overcome this barrier by using a pointer. In other words,\ninstead of passing a value as input to the argument, you can pass a \"pointer to value\" instead.\nYou can change the value that the pointer points to, by dereferencing it.\n\nTherefore, if we take our previous `add2()` example, we can change the value of the\nfunction argument `x` inside the function's body by marking the `x` argument as a\n\"pointer to a `u32` value\" (i.e. `*u32` data type), instead of a `u32` value.\nBy making it a pointer, we can finally alter the value of this function argument directly inside\nthe body of the `add2()` function. You can see that the code example below compiles successfully.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n```\n:::\n\n\n\n\n```\nResult: 6\n```\n\n\nEven in this code example above, the `x` argument is still immutable. Which means that the pointer itself is immutable.\nTherefore, you cannot change the memory address that it points to. However, you can dereference the pointer\nto access the value that it points to, and also, to change this value, if you need to.\n\n\n\n\n\n## Structs and OOP {#sec-structs-and-oop}\n\nZig is a language more closely related to C (which is a procedural language),\nthan it is to C++ or Java (which are object-oriented languages). Because of that, you do not\nhave advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or\nclass inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\n\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C.\nYou give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can\nalso register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object\nthat you create with this new type, will always have these methods available and associated with them.\n\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which\nis used to construct (or, to instantiate) every object of this particular class, and we also have\na destructor method (or a destructor function), which is the function responsible for destroying\nevery object of this class.\n\nIn Zig, we normally declare the constructor and the destructor methods\nof our structs, by declaring an `init()` and a `deinit()` methods inside the struct.\nThis is just a naming convention that you will find across the entire Zig Standard Library.\nSo, in Zig, the `init()` method of a struct is normally the constructor method of the class represented by this struct.\nWhile the `deinit()` method is the method used for destroying an existing instance of that struct.\n\nThe `init()` and `deinit()` methods are both used extensively in Zig code, and you will see both of\nthem being used when we talk about allocators in @sec-allocators.\nBut, as another example, let's build a simple `User` struct to represent a user of some sort of system.\n\nIf you look at the `User` struct below, you can see the `struct` keyword.\nNotice the data members of this struct: `id`, `name` and `email`. Every data member has its\ntype explicitly annotated, with the colon character (`:`) syntax that we described earlier in @sec-root-file.\nBut also notice that every line in the struct body that describes a data member, ends with a comma character (`,`).\nSo every time you declare a data member in your Zig code, always end the line with a comma character, instead\nof ending it with the traditional semicolon character (`;`).\n\nNext, we have registered an `init()` function as a method\nof this `User` struct. This `init()` method is the constructor method that we will use to instantiate\nevery new `User` object. That is why this `init()` function returns a new `User` object as result.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    pub fn init(id: u64,\n                name: []const u8,\n                email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    pub fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\npedro\n```\n\n\n:::\n:::\n\n\n\n\nThe `pub` keyword plays an important role in struct declarations, and OOP in Zig.\nEvery method that you declare in your struct that is marked with the keyword `pub`,\nbecomes a public method of this particular struct.\n\nSo every method that you create inside your struct, is, at first, a private method\nof that struct. Meaning that, this method can only be called from within this\nstruct. But, if you mark this method as public, with the keyword `pub`, then,\nyou can call the method directly from an instance of the `User` struct.\n\nIn other words, the functions marked by the keyword `pub`\nare members of the public API of that struct.\nFor example, if I did not mark the `print_name()` method as public,\nthen, I could not execute the line `u.print_name()`. Because I would\nnot be authorized to call this method directly in my code.\n\n\n\n### Anonymous struct literals {#sec-anonymous-struct-literals}\n\nYou can declare a struct object as a literal value. When we do that, we normally specify the\ndata type of this struct literal by writing its data type just before the opening curly brace.\nFor example, I could write a struct literal value of the type `User` that we have defined\nin the previous section like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n```\n:::\n\n\n\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a\nstruct literal, but not specify explicitly the type of this particular struct.\nAn anonymous struct is written by using the syntax `.{}`. So, we essentially\nreplaced the explicit type of the struct literal with a dot character (`.`).\n\nAs we described in @sec-type-inference, when you put a dot before a struct literal,\nthe type of this struct literal is automatically inferred by the `zig` compiler.\nIn essence, the `zig` compiler will look for some hint of what is the type of that struct.\nThis hint can be the type annotation of a function argument,\nor the return type annotation of the function that you are using, or the type annotation\nof an existing object.\nIf the compiler does find such type annotation, it will use this\ntype in your literal struct.\n\nAnonymous structs are very commonly used as inputs to function arguments in Zig.\nOne example that you have seen already constantly, is the `print()`\nfunction from the `stdout` object.\nThis function takes two arguments.\nThe first argument, is a template string, which should\ncontain string format specifiers in it, which tells how the values provided\nin the second argument should be printed into the message.\n\nWhile the second argument is a struct literal that lists the values\nto be printed into the template message specified in the first argument.\nYou normally want to use an anonymous struct literal here, so that the\n`zig` compiler do the job of specifying the type of this particular\nanonymous struct for you.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello, world!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Struct declarations must be constant\n\nTypes in Zig must be `const` or `comptime` (we are going to talk more about comptime in @sec-comptime).\nWhat this means is that you cannot create a new data type, and mark it as variable with the `var` keyword.\nSo struct declarations are always constant. You cannot declare a new struct type using the `var` keyword.\nIt must be `const`.\n\nIn the `Vec3` example below, this declaration is allowed because I'm using the `const` keyword\nto declare this new data type.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n```\n:::\n\n\n\n\n\n### The `self` method argument {#sec-self-arg}\n\nIn every language that have OOP, when we declare a method of some class or struct, we\nusually declare this method as a function that has a `self` argument.\nThis `self` argument is the reference to the object itself from which the method\nis being called from.\n\nIt is not mandatory to use this `self` argument. But why would you not use this `self` argument?\nThere is no reason to not use it. Because the only way to get access to the data stored in the\ndata members of your struct is to access them through this `self` argument.\nIf you don't need to use the data in the data members of your struct inside your method, you very likely don't need\na method. You can just declare this logic as a simple function, outside of your\nstruct declaration.\n\n\nTake the `Vec3` struct below. Inside this `Vec3` struct we declared a method named `distance()`.\nThis method calculates the distance between two `Vec3` objects, by following the distance\nformula in euclidean space. Notice that this `distance()` method takes two `Vec3` objects\nas input, `self` and `other`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n```\n:::\n\n\n\n\n\nThe `self` argument corresponds to the `Vec3` object from which this `distance()` method\nis being called from. While the `other` is a separate `Vec3` object that is given as input\nto this method. In the example below, the `self` argument corresponds to the object\n`v1`, because the `distance()` method is being called from the `v1` object,\nwhile the `other` argument corresponds to the object `v2`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n```\n:::\n\n\n\n\n```\nDistance: 3.3970575502926055\n```\n\n\n\n### About the struct state\n\nSometimes you don't need to care about the state of your struct object. Sometimes, you just need\nto instantiate and use the objects, without altering their state. You can notice that when you have methods\ninside your struct declaration that might use the values that are present in the data members, but they\ndo not alter the values in these data members of the struct in anyway.\n\nThe `Vec3` struct that was presented in @sec-self-arg is an example of that.\nThis struct have a single method named `distance()`, and this method does use the values\npresent in all three data members of the struct (`x`, `y` and `z`). But at the same time,\nthis method does not change the values of these data members at any point.\n\nAs a result of that, when we create `Vec3` objects we usually create them as\nconstant objects, like the `v1` and `v2` objects presented in @sec-self-arg.\nWe can create them as variable objects with the `var` keyword,\nif we want to. But because the methods of this `Vec3` struct do not change\nthe state of the objects in any point, it's unnecessary to mark them\nas variable objects.\n\nBut why? Why am I talking about this here? It's because the `self` argument\nin the methods is affected depending on whether the\nmethods present in a struct change or don't change the state of the object itself.\nMore specifically, when you have a method in a struct that changes the state\nof the object (i.e. change the value of a data member), the `self` argument\nin this method must be annotated in a different manner.\n\nAs I described in @sec-self-arg, the `self` argument in methods of\na struct is the argument that receives as input the object from which the method\nwas called from. We usually annotate this argument in the methods by writing `self`,\nfollowed by the colon character (`:`), and the data type of the struct to which\nthe method belongs to (e.g. `User`, `Vec3`, etc.).\n\nIf we take the `Vec3` struct that we defined in the previous section as an example,\nwe can see in the `distance()` method that this `self` argument is annotated as\n`self: Vec3`. Because the state of the `Vec3` object is never altered by this\nmethod.\n\nBut what if we do have a method that alters the state of the object, by altering the\nvalues of its data members, how should we annotate `self` in this instance? The answer is:\n\"we should annotate `self` as a pointer of `x`, instead of just `x`\".\nIn other words, you should annotate `self` as `self: *x`, instead of annotating it\nas `self: x`.\n\nIf we create a new method inside the `Vec3` object that, for example, expands the\nvector by multiplying its coordinates by a factor of two, then, we need to follow\nthis rule specified in the previous paragraph. The code example below demonstrates\nthis idea:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n```\n:::\n\n\n\n\nNotice in the code example above that we have added a new method\nto our `Vec3` struct named `twice()`. This method doubles the\ncoordinate values of our vector object. In the\ncase of the `twice()` method, we annotated the `self` argument as `*Vec3`,\nindicating that this argument receives a pointer (or a reference, if you prefer to call it this way)\nto a `Vec3` object as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n```\n:::\n\n\n\n\n```\nDoubled: 8.4\n```\n\n\n\nNow, if you change the `self` argument in this `twice()` method to `self: Vec3`, like in the\n`distance()` method, you will get the compiler error exposed below as result. Notice that this\nerror message is showing a line from the `twice()` method body,\nindicating that you cannot alter the value of the `x` data member.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n```\n:::\n\n\n\n\n```\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\n```\n\nThis error message indicates that the `x` data member belongs to a constant object,\nand, because of that, it cannot be changed. Ultimately, this error message\nis telling us that the `self` argument is constant.\n\nIf you take some time, and think hard about this error message, you will understand it.\nYou already have the tools to understand why we are getting this error message.\nWe have talked about it already in @sec-fun-pars.\nSo remember, every function argument is immutable in Zig, and `self`\nis no exception to this rule.\n\nIn this example, we marked the `v3` object as a variable object.\nBut this does not matter. Because it is not about the input object, it is about\nthe function argument.\n\nThe problem begins when we try to alter the value of `self` directly, which is a function argument,\nand, every function argument is immutable by default. You may ask yourself how can we overcome\nthis barrier, and once again, the solution was also discussed in @sec-fun-pars.\nWe overcome this barrier, by explicitly marking the `self` argument as a pointer.\n\n\n::: {.callout-note}\nIf a method of your `x` struct alters the state of the object, by\nchanging the value of any data member, then, remember to use `self: *x`,\ninstead of `self: x` in the function signature of this method.\n:::\n\n\nYou could also interpret the content discussed in this section as:\n\"if you need to alter the state of your `x` struct object in one of its methods,\nyou must explicitly pass the `x` struct object by reference to the `self` argument of this method\".\n\n\n\n## Type inference {#sec-type-inference}\n\nZig is a strongly typed language. But, there are some situations\nwhere you don't have to explicitly write the type of every single object in your source code,\nas you would expect from a traditional strongly typed language, such as C and C++.\n\nIn some situations, the `zig` compiler can use type inference to solve the data types for you, easing some of\nthe burden that you carry as a developer.\nThe most common way this happens is through function arguments that receive struct objects\nas input.\n\nIn general, type inference in Zig is done by using the dot character (`.`).\nEverytime you see a dot character written before a struct literal, or before an enum value, or something like that,\nyou know that this dot character is playing a special party in this place. More specifically, it is\ntelling the `zig` compiler something along the lines of: \"Hey! Can you infer the type of this\nvalue for me? Please!\". In other words, this dot character is playing a similar role as the `auto` keyword in C++.\n\nI gave you some examples of this in @sec-anonymous-struct-literals, where we used anonymous struct literals.\nAnonymous struct literals are, struct literals that use type inference to\ninfer the exact type of this particular struct literal.\nThis type inference is done by looking for some minimal hint of the correct data type to be used.\nYou could say that the `zig` compiler looks for any neighbouring type annotation that might tell it\nwhat the correct type would be.\n\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in @sec-switch).\nI also gave some other examples of type inference in @sec-switch, where we were inferring the data types of enum values listed inside\nof switch statements (e.g. `.DE`).\nBut as another example, take a look at this `fence()` function reproduced below,\nwhich comes from the [`atomic.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig)[^fence-fn]\nof the Zig Standard Library.\n\n[^fence-fn]: <https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig>.\n\nThere are a lot of things in this function that we haven't talked about yet, such as:\nwhat `comptime` means? `inline`? `extern`?\nLet's just ignore all of these things, and focus solely on the switch statement\nthat is inside this function.\n\nWe can see that this switch statement uses the `order` object as input. This `order`\nobject is one of the inputs of this `fence()` function, and we can see in the type annotation,\nthat this object is of type `AtomicOrder`. We can also see a bunch of values inside the\nswitch statements that begin with a dot character, such as `.release` and `.acquire`.\n\nBecause these weird values contain a dot character before them, we are asking the `zig`\ncompiler to infer the types of these values inside the switch statement. Then, the `zig`\ncompiler is looking into the current context where these values are being used, and it is\ntrying to infer the types of these values.\n\nSince they are being used inside a switch statement, the `zig` compiler looks into the type\nof the input object given to the switch statement, which is the `order` object in this case.\nBecause this object have type `AtomicOrder`, the `zig` compiler infers that these values\nare data members from this type `AtomicOrder`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic => @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire => tsan.__tsan_acquire(addr),\n            .release => tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst => {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n```\n:::\n\n\n\n\nThis is how basic type inference is done in Zig. If we didn't use the dot character before\nthe values inside this switch statement, then, we would be forced to explicitly write\nthe data types of these values. For example, instead of writing `.release` we would have to\nwrite `AtomicOrder.release`. We would have to do this for every single value\nin this switch statement, and this is a lot of work. That is why type inference\nis commonly used on switch statements in Zig.\n\n\n\n## Type casting {#sec-type-cast}\n\nIn this section, I want to discuss type casting (or, type conversion) with you.\nWe use type casting when we have an object of type \"x\", and we want to convert\nit into an object of type \"y\", i.e. we want to change the data type of the object.\n\nMost languages have a formal way to perform type casting. In Rust for example, we normally\nuse the keyword `as`, and in C, we normally use the type casting syntax, e.g. `(int) x`.\nIn Zig, we use the `@as()` built-in function to cast an object of type \"x\", into\nan object of type \"y\".\n\nThis `@as()` function is the preferred way to perform type conversion (or type casting)\nin Zig. Because it is explicit, and, it also performs the casting only if it\nis unambiguous and safe. To use this function, you just provide the target data type\nin the first argument, and, the object that you want cast as the second argument.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n```\n:::\n\n\n\n\nThis is the general way to perform type casting in Zig. But remember, `@as()` works only when casting\nis unambiguous and safe, and there are situations where these assumptions do not hold. For example,\nwhen casting an integer value into a float value, or vice-versa, it is not clear to the compiler\nhow to perform this conversion safely.\n\nTherefore, we need to use specialized \"casting functions\" in such situations.\nFor example, if you want to cast an integer value into a float value, then, you\nshould use the `@floatFromInt()` function. In the inverse scenario, you should use\nthe `@intFromFloat()` function.\n\nIn these functions, you just provide the object that you want to\ncast as input. Then, the target data type of the \"type casting operation\" is determined by\nthe type annotation of the object where you are saving the results.\nIn the example below, we are casting the object `x` into a value of type `f32`,\nbecause the object `y`, which is where we are saving the results, is annotated\nas an object of type `f32`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n```\n:::\n\n\n\n\nAnother built-in function that is very useful when performing type casting operations is `@ptrCast()`.\nIn essence, we use the `@as()` built-in function when we want to explicit convert (or cast) a Zig value/object\nfrom a type \"x\" to a type \"y\", etc. However, pointers (we are going to discuss pointers\nin more depth in @sec-pointer) are a special type of object in Zig,\ni.e. they are treated differently from \"normal objects\".\n\nEverytime a pointer is involved in some \"type casting operation\" in Zig, the `@ptrCast()` function is used.\nThis function works similarly to `@floatFromInt()`.\nYou just provide the pointer object that you want to cast as input to this function, and the\ntarget data type is, once again, determined by the type annotation of the object where the results are being\nstored.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n```\n:::\n\n\n\n\n\n\n\n\n## Modules\n\nWe already talked about what modules are, and also, how to import other modules into\nyour current module via *import statements*. Every Zig module (i.e. a `.zig` file) that you write in your project\nis internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the\nZig Standard Library into our current module.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n```\n:::\n\n\n\n\nWhen we want to access the functions and objects from the standard library, we\nare basically accessing the data members of the struct stored in the `std`\nobject. That is why we use the same syntax that we use in normal structs, with the dot operator (`.`)\nto access the data members and methods of the struct.\n\nWhen this \"import statement\" get's executed, the result of this expression is a struct\nobject that contains the Zig Standard Library modules, global variables, functions, etc.\nAnd this struct object get's saved (or stored) inside the constant object named `std`.\n\n\nTake the [`thread_pool.zig` module from the project `zap`](https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig)[^thread]\nas an example. This module is written as if it was\na big struct. That is why we have a top-level and public `init()` method\nwritten in this module. The idea is that all top-level functions written in this\nmodule are methods from the struct, and all top-level objects and struct declarations\nare data members of this struct. The module is the struct itself.\n\n[^thread]: <https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig>\n\n\nSo you would import and use this module by doing something like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst ThreadPool = @import(\"thread_pool.zig\");\nconst num_cpus = std.Thread.getCpuCount()\n    catch @panic(\"failed to get cpu core count\");\nconst num_threads = std.math.cast(u16, num_cpus)\n    catch std.math.maxInt(u16);\nconst pool = ThreadPool.init(\n    .{ .max_threads = num_threads }\n);\n```\n:::\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Control flow, structs, modules and types\n\nWe have discussed a lot of Zig's syntax in the last chapter,\nespecially in @sec-root-file and @sec-main-file.\nBut we still need to discuss some other very important\nelements of the language. Elements that you will use constantly on your day-to-day\nroutine.\n\nWe begin this chapter by discussing the different keywords and structures\nin Zig related to control flow (e.g. loops and if statements).\nThen, we talk about structs and how they can be used to do some\nbasic Object-Oriented (OOP) patterns in Zig. We also talk about\ntype inference and type casting.\nFinally, we end this chapter by discussing modules, and how they relate\nto structs.\n\n\n\n## Control flow {#sec-zig-control-flow}\n\nSometimes, you need to make decisions in your program. Maybe you need to decide\nwhether or not to execute a specific piece of code. Or maybe,\nyou need to apply the same operation over a sequence of values. These kinds of tasks,\ninvolve using structures that are capable of changing the \"control flow\" of our program.\n\nIn computer science, the term \"control flow\" usually refers to the order in which expressions (or commands)\nare evaluated in a given language or program. But this term is also used to refer\nto structures that are capable of changing this \"evaluation order\" of the commands\nexecuted by a given language/program.\n\nThese structures are better known\nby a set of terms, such as: loops, if/else statements, switch statements, among others. So,\nloops and if/else statements are examples of structures that can change the \"control\nflow\" of our program. The keywords `continue` and `break` are also examples of symbols\nthat can change the order of evaluation, since they can move our program to the next iteration\nof a loop, or make the loop stop completely.\n\n\n### If/else statements\n\nAn if/else statement performs a \"conditional flow operation\".\nA conditional flow control (or choice control) allows you to execute\nor ignore a certain block of commands based on a logical condition.\nMany programmers and computer science professionals also use\nthe term \"branching\" in this case.\nIn essence, an if/else statement allow us to use the result of a logical test\nto decide whether or not to execute a given block of commands.\n\nIn Zig, we write if/else statements by using the keywords `if` and `else`.\nWe start with the `if` keyword followed by a logical test inside a pair\nof parentheses, followed by a pair of curly braces which contains the lines\nof code to be executed in case the logical test returns the value `true`.\n\nAfter that, you can optionally add an `else` statement. To do that, just add the `else`\nkeyword followed by a pair of curly braces, with the lines of code\nto executed in case the logical test defined at `if` returns `false`.\n\nIn the example below, we are testing if the object `x` contains a number\nthat is greater than 10. Judging by the output printed to the console,\nwe know that this logical test returned `false`. Because the output\nin the console is compatible with the line of code present in the\n`else` branch of the if/else statement.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x = 5;\nif (x > 10) {\n    try stdout.print(\n        \"x > 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x <= 10!\\n\", .{}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nx <= 10!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Switch statements {#sec-switch}\n\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust.\nAs you would expect, to write a switch statement in Zig we use the `switch` keyword.\nWe provide the value that we want to \"switch over\" inside a\npair of parentheses. Then, we list the possible combinations (or \"branches\")\ninside a pair of curly braces.\n\nLet's take a look at the code example below. You can see that\nI'm creating an enum type called `Role`. We talk more about enums in @sec-enum.\nBut in summary, this `Role` type is listing different types of roles in a fictitious\ncompany, like `SE` for Software Engineer, `DE` for Data Engineer, `PM` for Product Manager,\netc.\n\nNotice that we are using the value from the `role` object in the\nswitch statement, to discover which exact area we need to store in the `area` variable object.\nAlso notice that we are using type inference inside the switch statement, with the dot character,\nas we are going to describe in @sec-type-inference.\nThis makes the `zig` compiler infer the correct data type of the values (`PM`, `SE`, etc.) for us.\n\nAlso notice that, we are grouping multiple values in the same branch of the switch statement.\nWe just separate each possible value with a comma. For example, if `role` contains either `DE` or `DA`,\nthe `area` variable would contain the value `\"Data & Analytics\"`, instead of `\"Platform\"` or `\"Sales\"`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO => {\n            area = \"Platform\";\n        },\n        .DE, .DA => {\n            area = \"Data & Analytics\";\n        },\n        .KS => {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nPlatform\n```\n\n\n:::\n:::\n\n\n\n\n\n#### Switch statements must exhaust all possibilities\n\nOne very important aspect about switch statements in Zig\nis that they must exhaust all existing possibilities.\nIn other words, all possible values that could be found inside the `order`\nobject must be explicitly handled in this switch statement.\n\nSince the `role` object have type `Role`, the only possible values to\nbe found inside this object are `PM`, `SE`, `DPE`, `PO`, `DE`, `DA` and `KS`.\nThere are no other possible values to be stored in this `role` object.\nThus, the switch statements must have a combination (branch) for each one of these values.\nThis is what \"exhaust all existing possibilities\" means. The switch statement covers\nevery possible case.\n\nTherefore, you cannot write a switch statement in Zig, and leave an edge case\nwith no explicit action to be taken.\nThis is a similar behaviour to switch statements in Rust, which also have to\nhandle all possible cases.\n\n\n\n#### The else branch\n\nTake a look at the `dump_hex_fallible()` function below as an example. This function\ncomes from the Zig Standard Library. More precisely, from the\n[`debug.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/debug.zig)[^debug-mod].\nThere are multiple lines in this function, but I omitted them to focus solely on the\nswitch statement found in this function. Notice that this switch statement has four\npossible cases (i.e. four explicit branches). Also, notice that we used an `else` branch\nin this case.\n\nAn `else` branch in a switch statement works as the \"default branch\".\nWhenever you have multiple cases in your switch statement where\nyou want to apply the exact same action, you can use an `else` branch to do that.\n\n[^debug-mod]: <https://github.com/ziglang/zig/blob/master/lib/std/debug.zig>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' => try writer.writeAll(\"␊\"),\n        '\\r' => try writer.writeAll(\"␍\"),\n        '\\t' => try writer.writeAll(\"␉\"),\n        else => try writer.writeByte('.'),\n    }\n}\n```\n:::\n\n\n\n\nMany programmers would also use an `else` branch to handle a \"not supported\" case.\nThat is, a case that cannot be properly handled by your code, or, just a case that\nshould not be \"fixed\". Therefore, you can use an `else` branch to panic (or raise an error)\nin your program to stop the current execution.\n\nTake the code example below. We can see that, we are handling the cases\nfor the `level` object being either 1, 2, or 3. All other possible cases are not supported by default,\nand, as consequence, we raise a runtime error in such cases through the `@panic()` built-in function.\n\nAlso notice that, we are assigning the result of the switch statement to a new object called `category`.\nThis is another thing that you can do with switch statements in Zig. If a branch\noutputs a value as result, you can store the result value of the switch statement into\na new object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 => \"beginner\",\n    3 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n:::\n\n\n\n\n```\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n```\n\n\n\n#### Using ranges in switch\n\nFurthermore, you can also use ranges of values in switch statements.\nThat is, you can create a branch in your switch statement that is used\nwhenever the input value is within the specified range. These \"range expressions\"\nare created with the operator `...`. It is important\nto emphasize that the ranges created by this operator are\ninclusive on both ends.\n\nFor example, I could easily change the previous code example to support all\nlevels between 0 and 100. Like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 => \"beginner\",\n    26...75 => \"intermediary\",\n    76...100 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nbeginner\n```\n\n\n:::\n:::\n\n\n\n\nThis is neat, and it works with character ranges too. That is, I could\nsimply write `'a'...'z'`, to match any character value that is a\nlowercase letter, and it would work fine.\n\n\n#### Labeled switch statements\n\nIn @sec-blocks we have talked about labeling blocks, and also, about using these labels\nto return a value from the block. Well, from version 0.14.0 and onwards of the `zig` compiler,\nyou can also apply labels over switch statements, which makes it possible to almost implement a\n\"C `goto`\" like pattern.\n\nFor example, if you give the label `xsw` to a switch statement, you can use this\nlabel in conjunction with the `continue` keyword to go back to the beginning of the switch\nstatement. In the example below, the execution goes back to the beginning of the\nswitch statement two times, before ending at the `3` branch.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nxsw: switch (@as(u8, 1)) {\n    1 => {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 => continue :xsw 3,\n    3 => return,\n    4 => {},\n    else => {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n```\n:::\n\n\n\n\n\n### The `defer` keyword {#sec-defer}\n\nWith the `defer` keyword you can register an expression to be executed when you exit the current scope.\nTherefore, this keyword has a similar functionality as the `on.exit()` function from R.\nTake the `foo()` function below as an example. When we execute this `foo()` function, the expression\nthat prints the message \"Exiting function ...\" is getting executed only when the function exits\nits scope.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nAdding some numbers ...\nMultiplying ...\nExiting function ...\n```\n\nTherefore, we can use `defer` to declare an expression that is going to be executed\nwhen your code exits the current scope. Some programmers like to interpret the phrase \"exit of the current scope\"\nas \"the end of the current scope\". But this interpretation might not be entirely correct, depending\non what you consider as \"the end of the current scope\".\n\nI mean, what do you consider as **the end** of the current scope? Is it the closing curly bracket (`}`) of the scope?\nIs it when the last expression in the function get's executed? Is it when the function returns to the previous scope?\nEtc. For example, it would not be correct to interpret the \"exit of the current scope\" as the closing\ncurly bracket of the scope. Because the function might exit from an earlier position than this\nclosing curly bracket (e.g. an error value was generated at a previous line inside the function;\nthe function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\n\nNow, if you remember of what we have discussed in @sec-blocks, there are multiple structures in the language\nthat create their own separate scopes. For/while loops, if/else statements,\nfunctions, normal blocks, etc. This also affects the interpretation of `defer`.\nFor example, if you use `defer` inside a for loop, then, the given expression\nwill be executed everytime this specific for loop exits its own scope.\n\nBefore we continue, is worth emphasizing that the `defer` keyword is an \"unconditional defer\".\nWhich means that the given expression will be executed no matter how the code exits\nthe current scope. For example, your code might exit the current scope because of an error value\nbeing generated, or, because of a return statement, or, a break statement, etc.\n\n\n\n### The `errdefer` keyword {#sec-errdefer1}\n\nOn the previous section, we have discussed the `defer` keyword, which you can use to\nregister an expression to be executed at the exit of the current scope.\nBut this keyword has a brother, which is the `errdefer` keyword. While `defer`\nis an \"unconditional defer\", the `errdefer` keyword is a \"conditional defer\".\nWhich means that the given expression is executed only when you exit the current\nscope on a very specific circumstance.\n\nIn more details, the expression given to `errdefer` is executed only when an error occurs in the current scope.\nTherefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope\nin a normal situation, without errors, the expression given to `errdefer` is not executed.\n\nThis makes the `errdefer` keyword one of the many tools available in Zig for error handling.\nIn this section, we are more concerned with the control flow aspects around `errdefer`.\nBut we are going to discuss `errdefer` later as a error handling tool in @sec-errdefer2.\n\nThe code example below demonstrates three things:\n\n- that `defer` is an \"unconditional defer\", because the given expression get's executed regardless of how the function `foo()` exits its own scope.\n- that `errdefer` is executed because the function `foo()` returned an error value.\n- that `defer` and `errdefer` expressions are executed in a LIFO (*last in, first out*) order.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\nWhen I say that \"defer expressions\" are executed in a LIFO order, what I want to say is that\nthe last `defer` or `errdefer` expressions in the code are the first ones to be executed.\nYou could also interpret this as: \"defer expressions\" are executed from bottom to top, or,\nfrom last to first.\n\nTherefore, if I change the order of the `defer` and `errdefer` expressions, you will notice that\nthe value of `i` that get's printed to the console changes to 1. This doesn't mean that the\n`defer` expression was not executed in this case. This actually means that the `defer` expression\nwas executed only after the `errdefer` expression. The code example below demonstrates this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\n\n\n### For loops\n\nA loop allows you to execute the same lines of code multiple times,\nthus, creating a \"repetition space\" in the execution flow of your program.\nLoops are particularly useful when we want to replicate the same function\n(or the same set of commands) over different inputs.\n\nThere are different types of loops available in Zig. But the most\nessential of them all is probably the *for loop*. A for loop is\nused to apply the same piece of code over the elements of a slice, or, an array.\n\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from\nother languages. You start with the `for` keyword, then, you\nlist the items that you want to iterate\nover inside a pair of parentheses. Then, inside of a pair of pipes (`|`)\nyou should declare an identifier that will serve as your iterator, or,\nthe \"repetition index of the loop\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (items) |value| {\n    // code to execute\n}\n```\n:::\n\n\n\n\nTherefore, instead of using a `(value in items)` syntax,\nin Zig, for loops use the syntax `(items) |value|`. In the example\nbelow, you can see that we are looping through the items\nof the array stored at the object `name`, and printing to the\nconsole the decimal representation of each character in this array.\n\nIf we wanted, we could also iterate through a slice (or a portion) of\nthe array, instead of iterating through the entire array stored in the `name` object.\nJust use a range selector to select the section you want. For example,\nI could provide the expression `name[0..3]` to the for loop, to iterate\njust through the first 3 elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n80 | 101 | 100 | 114 | 111 | \n```\n\n\n:::\n:::\n\n\n\n\nIn the above example we are using the value itself of each\nelement in the array as our iterator. But there are many situations where\nwe need to use an index instead of the actual values of the items.\n\nYou can do that by providing a second set of items to iterate over.\nMore precisely, you provide the range selector `0..` to the for loop. So,\nyes, you can use two different iterators at the same time in a for\nloop in Zig.\n\nBut remember from @sec-assignments that, every object\nyou create in Zig must be used in some way. So if you declare two iterators\nin your for loop, you must use both iterators inside the for loop body.\nBut if you want to use just the index iterator, and not use the \"value iterator\",\nthen, you can discard the value iterator by maching the\nvalue items to the underscore character, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n:::\n\n\n\n\n```\n0 | 1 | 2 | 3 | 4 |\n```\n\n\n### While loops\n\nA while loop is created from the `while` keyword. A `for` loop\niterates through the items of an array, but a `while` loop\nwill loop continuously, and infinitely, until a logical test\n(specified by you) becomes false.\n\nYou start with the `while` keyword, then, you define a logical\nexpression inside a pair of parentheses, and the body of the\nloop is provided inside a pair of curly braces, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\nYou can also specify the increment expression to be used at the beginning of a while loop.\nTo do that, we write the increment expression inside a pair of parentheses after a colon character (`:`).\nThe code example below demonstrates this other pattern.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\n### Using `break` and `continue`\n\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using\nthe keywords `break` and `continue`, respectively. The `while` loop presented in the next code example is,\nat first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to `true`.\nBut what makes this `while` loop stop when the `i` object reaches the count\n10? It is the `break` keyword!\n\nInside the while loop, we have an if statement that is constantly checking if the `i` variable\nis equal to 10. Since we are incrementing the value of `i` at each iteration of the\nwhile loop, this `i` object will eventually be equal to 10, and when it is, the if statement\nwill execute the `break` expression, and, as a result, the execution of the while loop is stopped.\n\nNotice the use of the `expect()` function from the Zig Standard Library after the while loop.\nThis `expect()` function is an \"assert\" type of function.\nThis function checks if the logical test provided is equal to true. If so, the function do nothing.\nOtherwise (i.e. the logical test is equal to false), the function raises an assertion error.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nEverything worked!\n```\n\n\n:::\n:::\n\n\n\n\nSince this code example was executed successfully by the `zig` compiler,\nwithout raising any errors, we known that, after the execution of the while loop,\nthe `i` object is equal to 10. Because if it wasn't equal to 10, an error would have\nbeen raised by `expect()`.\n\nNow, in the next example, we have a use case for\nthe `continue` keyword. The if statement is constantly\nchecking if the current index is a multiple of 2. If\nit is, we jump to the next iteration of the loop.\nOtherwise, the loop just prints the current index to the console.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 3 | 5 | \n```\n\n\n:::\n:::\n\n\n\n\n\n\n## Function parameters are immutable {#sec-fun-pars}\n\nWe have already discussed a lot of the syntax behind function declarations in @sec-root-file and @sec-main-file.\nBut I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig.\nIn summary, function parameters are immutable in Zig.\n\nTake the code example below, where we declare a simple function that just tries to add\nsome amount to the input integer, and returns the result back. If you look closely\nat the body of this `add2()` function, you will notice that we try\nto save the result back into the `x` function argument.\n\nIn other words, this function not only uses the value that it received through the function argument\n`x`, but it also tries to change the value of this function argument, by assigning the addition result\ninto `x`. However, function arguments in Zig are immutable. You cannot change their values, or, you\ncannot assign values to them inside the body's function.\n\nThis is the reason why, the code example below does not compile successfully. If you try to compile\nthis code example, you will get a compile error message about \"trying to change the value of a\nimmutable (i.e. constant) object\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n\n\n```\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n```\n\n\n### A free optimization\n\nIf a function argument receives as input an object whose data type is\nany of the primitive types that we have listed in @sec-primitive-data-types,\nthis object is always passed by value to the function. In other words, this object\nis copied into the function stack frame.\n\nHowever, if the input object have a more complex data type, for example, it might\nbe a struct instance, or an array, or an union value, etc., in cases like that, the `zig` compiler\nwill take the liberty of deciding for you which strategy is best. Thus, the `zig` compiler will\npass your object to the function either by value, or by reference. The compiler will always\nchoose the strategy that is faster for you.\nThis optimization that you get for free is possible only because function arguments are\nimmutable in Zig.\n\n\n### How to overcome this barrier\n\nThere are some situations where you might need to change the value of your function argument\ndirectly inside the function's body. This happens more often when we are passing\nC structs as inputs to Zig functions.\n\nIn a situation like this, you can overcome this barrier by using a pointer. In other words,\ninstead of passing a value as input to the argument, you can pass a \"pointer to value\" instead.\nYou can change the value that the pointer points to, by dereferencing it.\n\nTherefore, if we take our previous `add2()` example, we can change the value of the\nfunction argument `x` inside the function's body by marking the `x` argument as a\n\"pointer to a `u32` value\" (i.e. `*u32` data type), instead of a `u32` value.\nBy making it a pointer, we can finally alter the value of this function argument directly inside\nthe body of the `add2()` function. You can see that the code example below compiles successfully.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 6\n```\n\n\n:::\n:::\n\n\n\n\n```\nResult: 6\n```\n\n\nEven in this code example above, the `x` argument is still immutable. Which means that the pointer itself is immutable.\nTherefore, you cannot change the memory address that it points to. However, you can dereference the pointer\nto access the value that it points to, and also, to change this value, if you need to.\n\n\n\n\n\n## Structs and OOP {#sec-structs-and-oop}\n\nZig is a language more closely related to C (which is a procedural language),\nthan it is to C++ or Java (which are object-oriented languages). Because of that, you do not\nhave advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or\nclass inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\n\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C.\nYou give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can\nalso register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object\nthat you create with this new type, will always have these methods available and associated with them.\n\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which\nis used to construct (or, to instantiate) every object of this particular class, and we also have\na destructor method (or a destructor function), which is the function responsible for destroying\nevery object of this class.\n\nIn Zig, we normally declare the constructor and the destructor methods\nof our structs, by declaring an `init()` and a `deinit()` methods inside the struct.\nThis is just a naming convention that you will find across the entire Zig Standard Library.\nSo, in Zig, the `init()` method of a struct is normally the constructor method of the class represented by this struct.\nWhile the `deinit()` method is the method used for destroying an existing instance of that struct.\n\nThe `init()` and `deinit()` methods are both used extensively in Zig code, and you will see both of\nthem being used when we talk about allocators in @sec-allocators.\nBut, as another example, let's build a simple `User` struct to represent a user of some sort of system.\n\nIf you look at the `User` struct below, you can see the `struct` keyword.\nNotice the data members of this struct: `id`, `name` and `email`. Every data member has its\ntype explicitly annotated, with the colon character (`:`) syntax that we described earlier in @sec-root-file.\nBut also notice that every line in the struct body that describes a data member, ends with a comma character (`,`).\nSo every time you declare a data member in your Zig code, always end the line with a comma character, instead\nof ending it with the traditional semicolon character (`;`).\n\nNext, we have registered an `init()` function as a method\nof this `User` struct. This `init()` method is the constructor method that we will use to instantiate\nevery new `User` object. That is why this `init()` function returns a new `User` object as result.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    pub fn init(id: u64,\n                name: []const u8,\n                email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    pub fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\npedro\n```\n\n\n:::\n:::\n\n\n\n\nThe `pub` keyword plays an important role in struct declarations, and OOP in Zig.\nEvery method that you declare in your struct that is marked with the keyword `pub`,\nbecomes a public method of this particular struct.\n\nSo every method that you create inside your struct, is, at first, a private method\nof that struct. Meaning that, this method can only be called from within this\nstruct. But, if you mark this method as public, with the keyword `pub`, then,\nyou can call the method directly from an instance of the `User` struct.\n\nIn other words, the functions marked by the keyword `pub`\nare members of the public API of that struct.\nFor example, if I did not mark the `print_name()` method as public,\nthen, I could not execute the line `u.print_name()`. Because I would\nnot be authorized to call this method directly in my code.\n\n\n\n### Anonymous struct literals {#sec-anonymous-struct-literals}\n\nYou can declare a struct object as a literal value. When we do that, we normally specify the\ndata type of this struct literal by writing its data type just before the opening curly brace.\nFor example, I could write a struct literal value of the type `User` that we have defined\nin the previous section like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n```\n:::\n\n\n\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a\nstruct literal, but not specify explicitly the type of this particular struct.\nAn anonymous struct is written by using the syntax `.{}`. So, we essentially\nreplaced the explicit type of the struct literal with a dot character (`.`).\n\nAs we described in @sec-type-inference, when you put a dot before a struct literal,\nthe type of this struct literal is automatically inferred by the `zig` compiler.\nIn essence, the `zig` compiler will look for some hint of what is the type of that struct.\nThis hint can be the type annotation of a function argument,\nor the return type annotation of the function that you are using, or the type annotation\nof an existing object.\nIf the compiler does find such type annotation, it will use this\ntype in your literal struct.\n\nAnonymous structs are very commonly used as inputs to function arguments in Zig.\nOne example that you have seen already constantly, is the `print()`\nfunction from the `stdout` object.\nThis function takes two arguments.\nThe first argument, is a template string, which should\ncontain string format specifiers in it, which tells how the values provided\nin the second argument should be printed into the message.\n\nWhile the second argument is a struct literal that lists the values\nto be printed into the template message specified in the first argument.\nYou normally want to use an anonymous struct literal here, so that the\n`zig` compiler do the job of specifying the type of this particular\nanonymous struct for you.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello, world!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Struct declarations must be constant\n\nTypes in Zig must be `const` or `comptime` (we are going to talk more about comptime in @sec-comptime).\nWhat this means is that you cannot create a new data type, and mark it as variable with the `var` keyword.\nSo struct declarations are always constant. You cannot declare a new struct type using the `var` keyword.\nIt must be `const`.\n\nIn the `Vec3` example below, this declaration is allowed because I'm using the `const` keyword\nto declare this new data type.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n```\n:::\n\n\n\n\n\n### The `self` method argument {#sec-self-arg}\n\nIn every language that have OOP, when we declare a method of some class or struct, we\nusually declare this method as a function that has a `self` argument.\nThis `self` argument is the reference to the object itself from which the method\nis being called from.\n\nIt is not mandatory to use this `self` argument. But why would you not use this `self` argument?\nThere is no reason to not use it. Because the only way to get access to the data stored in the\ndata members of your struct is to access them through this `self` argument.\nIf you don't need to use the data in the data members of your struct inside your method, you very likely don't need\na method. You can just declare this logic as a simple function, outside of your\nstruct declaration.\n\n\nTake the `Vec3` struct below. Inside this `Vec3` struct we declared a method named `distance()`.\nThis method calculates the distance between two `Vec3` objects, by following the distance\nformula in euclidean space. Notice that this `distance()` method takes two `Vec3` objects\nas input, `self` and `other`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n```\n:::\n\n\n\n\n\nThe `self` argument corresponds to the `Vec3` object from which this `distance()` method\nis being called from. While the `other` is a separate `Vec3` object that is given as input\nto this method. In the example below, the `self` argument corresponds to the object\n`v1`, because the `distance()` method is being called from the `v1` object,\nwhile the `other` argument corresponds to the object `v2`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n```\n:::\n\n\n\n\n```\nDistance: 3.3970575502926055\n```\n\n\n\n### About the struct state\n\nSometimes you don't need to care about the state of your struct object. Sometimes, you just need\nto instantiate and use the objects, without altering their state. You can notice that when you have methods\ninside your struct declaration that might use the values that are present in the data members, but they\ndo not alter the values in these data members of the struct in anyway.\n\nThe `Vec3` struct that was presented in @sec-self-arg is an example of that.\nThis struct have a single method named `distance()`, and this method does use the values\npresent in all three data members of the struct (`x`, `y` and `z`). But at the same time,\nthis method does not change the values of these data members at any point.\n\nAs a result of that, when we create `Vec3` objects we usually create them as\nconstant objects, like the `v1` and `v2` objects presented in @sec-self-arg.\nWe can create them as variable objects with the `var` keyword,\nif we want to. But because the methods of this `Vec3` struct do not change\nthe state of the objects in any point, it's unnecessary to mark them\nas variable objects.\n\nBut why? Why am I talking about this here? It's because the `self` argument\nin the methods is affected depending on whether the\nmethods present in a struct change or don't change the state of the object itself.\nMore specifically, when you have a method in a struct that changes the state\nof the object (i.e. change the value of a data member), the `self` argument\nin this method must be annotated in a different manner.\n\nAs I described in @sec-self-arg, the `self` argument in methods of\na struct is the argument that receives as input the object from which the method\nwas called from. We usually annotate this argument in the methods by writing `self`,\nfollowed by the colon character (`:`), and the data type of the struct to which\nthe method belongs to (e.g. `User`, `Vec3`, etc.).\n\nIf we take the `Vec3` struct that we defined in the previous section as an example,\nwe can see in the `distance()` method that this `self` argument is annotated as\n`self: Vec3`. Because the state of the `Vec3` object is never altered by this\nmethod.\n\nBut what if we do have a method that alters the state of the object, by altering the\nvalues of its data members, how should we annotate `self` in this instance? The answer is:\n\"we should annotate `self` as a pointer of `x`, instead of just `x`\".\nIn other words, you should annotate `self` as `self: *x`, instead of annotating it\nas `self: x`.\n\nIf we create a new method inside the `Vec3` object that, for example, expands the\nvector by multiplying its coordinates by a factor of two, then, we need to follow\nthis rule specified in the previous paragraph. The code example below demonstrates\nthis idea:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n```\n:::\n\n\n\n\nNotice in the code example above that we have added a new method\nto our `Vec3` struct named `twice()`. This method doubles the\ncoordinate values of our vector object. In the\ncase of the `twice()` method, we annotated the `self` argument as `*Vec3`,\nindicating that this argument receives a pointer (or a reference, if you prefer to call it this way)\nto a `Vec3` object as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n```\n:::\n\n\n\n\n```\nDoubled: 8.4\n```\n\n\n\nNow, if you change the `self` argument in this `twice()` method to `self: Vec3`, like in the\n`distance()` method, you will get the compiler error exposed below as result. Notice that this\nerror message is showing a line from the `twice()` method body,\nindicating that you cannot alter the value of the `x` data member.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n```\n:::\n\n\n\n\n```\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\n```\n\nThis error message indicates that the `x` data member belongs to a constant object,\nand, because of that, it cannot be changed. Ultimately, this error message\nis telling us that the `self` argument is constant.\n\nIf you take some time, and think hard about this error message, you will understand it.\nYou already have the tools to understand why we are getting this error message.\nWe have talked about it already in @sec-fun-pars.\nSo remember, every function argument is immutable in Zig, and `self`\nis no exception to this rule.\n\nIn this example, we marked the `v3` object as a variable object.\nBut this does not matter. Because it is not about the input object, it is about\nthe function argument.\n\nThe problem begins when we try to alter the value of `self` directly, which is a function argument,\nand, every function argument is immutable by default. You may ask yourself how can we overcome\nthis barrier, and once again, the solution was also discussed in @sec-fun-pars.\nWe overcome this barrier, by explicitly marking the `self` argument as a pointer.\n\n\n::: {.callout-note}\nIf a method of your `x` struct alters the state of the object, by\nchanging the value of any data member, then, remember to use `self: *x`,\ninstead of `self: x` in the function signature of this method.\n:::\n\n\nYou could also interpret the content discussed in this section as:\n\"if you need to alter the state of your `x` struct object in one of its methods,\nyou must explicitly pass the `x` struct object by reference to the `self` argument of this method\".\n\n\n\n## Type inference {#sec-type-inference}\n\nZig is a strongly typed language. But, there are some situations\nwhere you don't have to explicitly write the type of every single object in your source code,\nas you would expect from a traditional strongly typed language, such as C and C++.\n\nIn some situations, the `zig` compiler can use type inference to solve the data types for you, easing some of\nthe burden that you carry as a developer.\nThe most common way this happens is through function arguments that receive struct objects\nas input.\n\nIn general, type inference in Zig is done by using the dot character (`.`).\nEverytime you see a dot character written before a struct literal, or before an enum value, or something like that,\nyou know that this dot character is playing a special party in this place. More specifically, it is\ntelling the `zig` compiler something along the lines of: \"Hey! Can you infer the type of this\nvalue for me? Please!\". In other words, this dot character is playing a similar role as the `auto` keyword in C++.\n\nI gave you some examples of this in @sec-anonymous-struct-literals, where we used anonymous struct literals.\nAnonymous struct literals are, struct literals that use type inference to\ninfer the exact type of this particular struct literal.\nThis type inference is done by looking for some minimal hint of the correct data type to be used.\nYou could say that the `zig` compiler looks for any neighbouring type annotation that might tell it\nwhat the correct type would be.\n\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in @sec-switch).\nI also gave some other examples of type inference in @sec-switch, where we were inferring the data types of enum values listed inside\nof switch statements (e.g. `.DE`).\nBut as another example, take a look at this `fence()` function reproduced below,\nwhich comes from the [`atomic.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig)[^fence-fn]\nof the Zig Standard Library.\n\n[^fence-fn]: <https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig>.\n\nThere are a lot of things in this function that we haven't talked about yet, such as:\nwhat `comptime` means? `inline`? `extern`?\nLet's just ignore all of these things, and focus solely on the switch statement\nthat is inside this function.\n\nWe can see that this switch statement uses the `order` object as input. This `order`\nobject is one of the inputs of this `fence()` function, and we can see in the type annotation,\nthat this object is of type `AtomicOrder`. We can also see a bunch of values inside the\nswitch statements that begin with a dot character, such as `.release` and `.acquire`.\n\nBecause these weird values contain a dot character before them, we are asking the `zig`\ncompiler to infer the types of these values inside the switch statement. Then, the `zig`\ncompiler is looking into the current context where these values are being used, and it is\ntrying to infer the types of these values.\n\nSince they are being used inside a switch statement, the `zig` compiler looks into the type\nof the input object given to the switch statement, which is the `order` object in this case.\nBecause this object have type `AtomicOrder`, the `zig` compiler infers that these values\nare data members from this type `AtomicOrder`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic => @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire => tsan.__tsan_acquire(addr),\n            .release => tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst => {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n```\n:::\n\n\n\n\nThis is how basic type inference is done in Zig. If we didn't use the dot character before\nthe values inside this switch statement, then, we would be forced to explicitly write\nthe data types of these values. For example, instead of writing `.release` we would have to\nwrite `AtomicOrder.release`. We would have to do this for every single value\nin this switch statement, and this is a lot of work. That is why type inference\nis commonly used on switch statements in Zig.\n\n\n\n## Type casting {#sec-type-cast}\n\nIn this section, I want to discuss type casting (or, type conversion) with you.\nWe use type casting when we have an object of type \"x\", and we want to convert\nit into an object of type \"y\", i.e. we want to change the data type of the object.\n\nMost languages have a formal way to perform type casting. In Rust for example, we normally\nuse the keyword `as`, and in C, we normally use the type casting syntax, e.g. `(int) x`.\nIn Zig, we use the `@as()` built-in function to cast an object of type \"x\", into\nan object of type \"y\".\n\nThis `@as()` function is the preferred way to perform type conversion (or type casting)\nin Zig. Because it is explicit, and, it also performs the casting only if it\nis unambiguous and safe. To use this function, you just provide the target data type\nin the first argument, and, the object that you want cast as the second argument.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filefe9b6a29a64b.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\nThis is the general way to perform type casting in Zig. But remember, `@as()` works only when casting\nis unambiguous and safe, and there are situations where these assumptions do not hold. For example,\nwhen casting an integer value into a float value, or vice-versa, it is not clear to the compiler\nhow to perform this conversion safely.\n\nTherefore, we need to use specialized \"casting functions\" in such situations.\nFor example, if you want to cast an integer value into a float value, then, you\nshould use the `@floatFromInt()` function. In the inverse scenario, you should use\nthe `@intFromFloat()` function.\n\nIn these functions, you just provide the object that you want to\ncast as input. Then, the target data type of the \"type casting operation\" is determined by\nthe type annotation of the object where you are saving the results.\nIn the example below, we are casting the object `x` into a value of type `f32`,\nbecause the object `y`, which is where we are saving the results, is annotated\nas an object of type `f32`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filefe9b126af3c3.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\nAnother built-in function that is very useful when performing type casting operations is `@ptrCast()`.\nIn essence, we use the `@as()` built-in function when we want to explicit convert (or cast) a Zig value/object\nfrom a type \"x\" to a type \"y\", etc. However, pointers (we are going to discuss pointers\nin more depth in @sec-pointer) are a special type of object in Zig,\ni.e. they are treated differently from \"normal objects\".\n\nEverytime a pointer is involved in some \"type casting operation\" in Zig, the `@ptrCast()` function is used.\nThis function works similarly to `@floatFromInt()`.\nYou just provide the pointer object that you want to cast as input to this function, and the\ntarget data type is, once again, determined by the type annotation of the object where the results are being\nstored.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filefe9b7366fb7.test_0...OKAll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## Modules\n\nWe already talked about what modules are, and also, how to import other modules into\nyour current module via *import statements*. Every Zig module (i.e. a `.zig` file) that you write in your project\nis internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the\nZig Standard Library into our current module.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n```\n:::\n\n\n\n\nWhen we want to access the functions and objects from the standard library, we\nare basically accessing the data members of the struct stored in the `std`\nobject. That is why we use the same syntax that we use in normal structs, with the dot operator (`.`)\nto access the data members and methods of the struct.\n\nWhen this \"import statement\" get's executed, the result of this expression is a struct\nobject that contains the Zig Standard Library modules, global variables, functions, etc.\nAnd this struct object get's saved (or stored) inside the constant object named `std`.\n\n\nTake the [`thread_pool.zig` module from the project `zap`](https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig)[^thread]\nas an example. This module is written as if it was\na big struct. That is why we have a top-level and public `init()` method\nwritten in this module. The idea is that all top-level functions written in this\nmodule are methods from the struct, and all top-level objects and struct declarations\nare data members of this struct. The module is the struct itself.\n\n[^thread]: <https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig>\n\n\nSo you would import and use this module by doing something like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst ThreadPool = @import(\"thread_pool.zig\");\nconst num_cpus = std.Thread.getCpuCount()\n    catch @panic(\"failed to get cpu core count\");\nconst num_threads = std.math.cast(u16, num_cpus)\n    catch std.math.maxInt(u16);\nconst pool = ThreadPool.init(\n    .{ .max_threads = num_threads }\n);\n```\n:::\n",
     "supporting": [
       "03-structs_files"
     ],
diff --git a/_freeze/Chapters/03-unittests/execute-results/html.json b/_freeze/Chapters/03-unittests/execute-results/html.json
index 9bac9305..dbaf31eb 100644
--- a/_freeze/Chapters/03-unittests/execute-results/html.json
+++ b/_freeze/Chapters/03-unittests/execute-results/html.json
@@ -2,7 +2,7 @@
   "hash": "8380b8e0995a3f1298d8bf31e661dba2",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Unit tests {#sec-unittests}\n\nIn this chapter, I want to dive in on how unit tests are done in\nZig. We are going to talk about what is the testing workflow in Zig, and\nalso, about the `test` command from the `zig` compiler.\n\n\n## Introducing the `test` block\n\nIn Zig, unit tests are written inside a `test` declaration, or, how I prefer to call it, inside a `test` block.\nEvery `test` block is written by using the keyword `test`.\nYou can optionally use a string literal to write a label, which is responsible for identifying\nthe specific group of unit tests that you are writing inside this specific `test` block.\n\nIn the example below, we are testing if the sum of two objects (`a` and `b`)\nis equal to 4. The `expect()` function from the Zig Standard Library\nis a function that receives a logical test as input. If this logical test\nresults in `true`, then, the test passes. But if it results\nin `false`, then, the test fails.\n\nYou can write any Zig code you want inside a `test` block.\nPart of this code might be some necessary commands to setup your testing\nenvironment, or just initializing some objects that you need to use\nin your unit tests.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest \"testing simple sum\" {\n    const a: u8 = 2;\n    const b: u8 = 2;\n    try expect((a + b) == 4);\n}\n```\n:::\n\n\n\n\nYou can have multiple `test` blocks written on the same Zig module.\nAlso, you can mix `test` blocks with your source code, with no problems\nor consequences. If you mix `test` blocks with your normal source code,\nwhen you execute the `build`, `build-exe`, `build-obj` or `build-lib` commands from the\n`zig` compiler that we exposed at @sec-compile-code, these `test` blocks are automatically\nignored by the compiler.\n\nIn other words, the `zig` compiler builds and execute your unit tests only\nwhen you ask it to. By default, the compiler always ignore `test`\nblocks written in your Zig modules. The compiler normally checks only if\nthere are any syntax errors in these `test` blocks.\n\nIf you take a look at the source code for most of the files present in the\nZig Standard Library[^zig-std-lib], you can see that the `test` blocks\nare written together with the normal source code of the library.\nYou can see this for example, at the [`array_list` module](https://github.com/ziglang/zig/blob/master/lib/std/array_list.zig)[^zig-array].\nSo, the standard that the Zig developers decided to adopt\nis to keep their unit tests together with the source code\nof the functionality that they are testing.\n\nEach programmer might have a different opinion on this.\nSome of them might prefer to keep unit tests separate from the actual\nsource code of their application. If that is your case, you can\nsimply create a separate `tests` folder in your project, and\nstart writing Zig modules that contains only unit tests (as you would normally do\non a Python project with `pytest`, for example), and everything will work fine.\nIt boils down to which is your preference here.\n\n[^zig-std-lib]: <https://github.com/ziglang/zig/tree/master/lib/std>\n[^zig-array]: <https://github.com/ziglang/zig/blob/master/lib/std/array_list.zig>\n\n\n## How to run your tests\n\nIf the `zig` compiler ignores any `test` block by default, how can\nyou compile and run your unit tests? The answer is the `test` command from\nthe `zig` compiler. By running the `zig test` command, the compiler will\nfind every instance of a `test` block in your Zig modules, and, it will\ncompile and run the unit tests that you wrote.\n\n\n```bash\nzig test simple_sum.zig\n```\n\n```\n1/1 simple_sum.test.testing simple sum... OK\nAll 1 tests passed.\n```\n\n\n## Testing memory allocations\n\nOne of the advantages of Zig is that it offers great tools\nthat help us, programmers, to avoid (but also detect) memory problems, such as\nmemory leaks and double-frees. The `defer` keyword\nis especially helpful in this regard.\n\nWhen developing your source code, you, the programmer, is responsible for making\nsure that your code do not produce such problems. However,\nyou can also use a special type of an allocator object in Zig\nthat is capable of automatically detecting such problems for you.\nThis is the `std.testing.allocator` object.\nThis allocator object offers some basic memory safety detection\nfeatures, which are capable of detecting memory leaks.\n\nAs we described at @sec-heap, to allocate memory on the heap, you need\nto use an allocator object, and your functions that use these objects to allocate memory\non the heap, should receive an allocator object as one of its inputs.\nEvery memory on the heap that you allocate using these allocator objects,\nmust also be freed using this same allocator object.\n\nSo, if you want to test the memory allocations performed by your functions,\nand make sure that you don't have problems in these allocations, you can simply\nwrite unit tests for these functions, where you provide the\n`std.testing.allocator` object as input to these functions.\n\nLook at the example below, where I'm defining a function that clearly causes\na memory leak. Because we allocate memory, but, at the same time,\nwe do not free this allocated memory at any point. So, when the function\nreturns, we lose the reference to the `buffer` object, which contains\nthe allocated memory, and, as a result, we can no longer free this memory.\n\nNotice that, inside a `test` block I execute this function with\nthe `std.testing.allocator`. The allocator object was capable\nof looking deeper in our program, and detecting the memory leak. As a result,\nthis allocator object returns an error message of \"memory leaked\", and also,\na stack trace showing the exact point where the memory was leaked.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nfn some_memory_leak(allocator: Allocator) !void {\n    const buffer = try allocator.alloc(u32, 10);\n    _ = buffer;\n    // Return without freeing the\n    // allocated memory\n}\n\ntest \"memory leak\" {\n    const allocator = std.testing.allocator;\n    try some_memory_leak(allocator);\n}\n```\n:::\n\n\n\n\n```\nTest [1/1] leak_memory.test.memory leak...\n    [gpa] (err): memory address 0x7c1fddf39000 leaked: \n./ZigExamples/debugging/leak_memory.zig:4:39: 0x10395f2\n    const buffer = try allocator.alloc(u32, 10);\n                                      ^\n./ZigExamples/debugging/leak_memory.zig:12:25: 0x10398ea\n    try some_memory_leak(allocator);\n\n... more stack trace\n```\n\n\n## Testing errors\n\nOne common style of unit tests are those that look for\nspecific errors in your functions. In other words, you write\na unit test that tries to assert if a specific function call\nreturns any error, or a specific type of error.\n\nIn C++ you would normally write this style of unit tests using, for example,\nthe functions `REQUIRE_THROWS()` or `CHECK_THROWS()` from the [`Catch2` test framework](https://github.com/catchorg/Catch2/tree/devel)[^catch2].\nIn the case of a Python project, you would probably use the\n[`raises()` function from `pytest`](https://docs.pytest.org/en/7.1.x/reference/reference.html#pytest-raises)[^pytest].\nWhile in Rust, you would probably use `assert_eq!()` in conjunction with `Err()`.\n\n[^pytest]: <https://docs.pytest.org/en/7.1.x/reference/reference.html#pytest-raises>\n[^catch2]: <https://github.com/catchorg/Catch2/tree/devel>\n\n\nBut in Zig, we use the `expectError()` function, from the `std.testing` module.\nWith this function, you can test if a specific function call returns the exact\ntype of error that you expect it to return. To use this function, you first write\n`try expectError()`. Then, on the first argument, you provide the type of error that you\nare expecting from the function call. Then, on the second argument, you write\nthe function call that you expect to fail.\n\nThe code example below demonstrates such type of unit test in Zig.\nNotice that, inside the function `alloc_error()` we are allocating\n100 bytes of memory, or, an array of 100 elements, for the object `ibuffer`. However,\nin the `test` block, we are using the `FixedBufferAllocator()`\nallocator object, which is limited to 10 bytes of space, because\nthe object `buffer`, which we provided to the allocator object,\nhave only 10 bytes of space.\n\nThat is why, the `alloc_error()` function raises an `OutOfMemory` error\non this case.\nBecause this function is trying to allocate more space than the allocator\nobject allows.\nSo, in essence, we are testing for a specific type of error,\nwhich is `OutOfMemory`. If the `alloc_error()` function returns any other type of error,\nthen, the `expectError()` function would make the entire test fail.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst expectError = std.testing.expectError;\nfn alloc_error(allocator: Allocator) !void {\n    var ibuffer = try allocator.alloc(u8, 100);\n    defer allocator.free(ibuffer);\n    ibuffer[0] = 2;\n}\n\ntest \"testing error\" {\n    var buffer: [10]u8 = undefined;\n    var fba = std.heap.FixedBufferAllocator.init(&buffer);\n    const allocator = fba.allocator();\n    try expectError(error.OutOfMemory, alloc_error(allocator));\n}\n```\n:::\n\n\n\n\n```\n1/1 oom.test.testing error... OK\nAll 1 tests passed.\n```\n\n\n\n## Testing simple equalities\n\nIn Zig, there are some different ways you can test for an equality.\nYou already saw that we can use `expect()` with the logical operator `==`\nto essentially reproduce an equality test. But we also have\nsome other helper functions that you should know about, especially\n`expectEqual()`, `expectEqualSlices()` and `expectEqualStrings()`.\n\n\nThe `expectEqual()` function, as the name suggests, is a classic\ntest equality function. It receives two objects as input. The first\nobject is the value that you expect to be in the second object.\nWhile second object is the object you have, or, the object that your application\nproduced as result. So, with `expectEqual()` you are essentially\ntesting if the values stored inside these two objects\nare equal or not.\n\nYou can see in the example below that, the test performed by\n`expectEqual()` failed. Because the objects `v1` and `v2` contain\ndifferent values in them.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"values are equal?\" {\n    const v1 = 15;\n    const v2 = 18;\n    try std.testing.expectEqual(v1, v2);\n}\n```\n:::\n\n\n\n\n```\n1/1 ve.test.values are equal?...\n    expected 15, found 18\n    FAIL (TestExpectedEqual)\nve.zig:5:5: test.values are equal? (test)\n    try std.testing.expectEqual(v1, v2);\n    ^\n0 passed; 0 skipped; 1 failed.\n```\n\n\nAlthough useful, the `expectEqual()` function does not work with arrays.\nFor testing if two arrays are equal, you should use the `expectEqualSlices()`\nfunction instead. This function have three arguments. First, you provide\nthe data type contained in both arrays that you are trying to compare.\nWhile the second and third arguments corresponds to the array objects that you want to compare.\n\nIn the example below, we are using this function to test if two array\nobjects (`array1` and `array2`) are equal or not. Since they\nare in fact equal, the unit test passed with no errors.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"arrays are equal?\" {\n    const array1 = [3]u32{1, 2, 3};\n    const array2 = [3]u32{1, 2, 3};\n    try std.testing.expectEqualSlices(\n        u32, &array1, &array2\n    );\n}\n```\n:::\n\n\n\n\n```\n1/1 oom.test.arrays are equal?... OK\nAll 1 tests passed.\n```\n\n\nAt last, you might also want to use the `expectEqualStrings()` function.\nAs the name suggests, you can use this function to test if two strings\nare equal or not. Just provide the two string objects that you want to compare,\nas inputs to the function.\n\nIf the function finds any existing differences between the two strings,\nthen, the function will raise an error, and also, print an error message\nthat shows the exact difference between the two string objects provided,\nas the example below demonstrates:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"strings are equal?\" {\n    const str1 = \"hello, world!\";\n    const str2 = \"Hello, world!\";\n    try std.testing.expectEqualStrings(\n        str1, str2\n    );\n}\n```\n:::\n\n\n\n\n```\n1/1 t.test.strings are equal?... \n====== expected this output: =========\nhello, world!␃\n======== instead found this: =========\nHello, world!␃\n======================================\nFirst difference occurs on line 1:\nexpected:\nhello, world!\n^ ('\\x68')\nfound:\nHello, world!\n^ ('\\x48')\n```\n\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Unit tests {#sec-unittests}\n\nIn this chapter, I want to dive in on how unit tests are done in\nZig. We are going to talk about what is the testing workflow in Zig, and\nalso, about the `test` command from the `zig` compiler.\n\n\n## Introducing the `test` block\n\nIn Zig, unit tests are written inside a `test` declaration, or, how I prefer to call it, inside a `test` block.\nEvery `test` block is written by using the keyword `test`.\nYou can optionally use a string literal to write a label, which is responsible for identifying\nthe specific group of unit tests that you are writing inside this specific `test` block.\n\nIn the example below, we are testing if the sum of two objects (`a` and `b`)\nis equal to 4. The `expect()` function from the Zig Standard Library\nis a function that receives a logical test as input. If this logical test\nresults in `true`, then, the test passes. But if it results\nin `false`, then, the test fails.\n\nYou can write any Zig code you want inside a `test` block.\nPart of this code might be some necessary commands to setup your testing\nenvironment, or just initializing some objects that you need to use\nin your unit tests.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest \"testing simple sum\" {\n    const a: u8 = 2;\n    const b: u8 = 2;\n    try expect((a + b) == 4);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file103bc24525048.test.testing simple sum...OK\n  KAll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\nYou can have multiple `test` blocks written on the same Zig module.\nAlso, you can mix `test` blocks with your source code, with no problems\nor consequences. If you mix `test` blocks with your normal source code,\nwhen you execute the `build`, `build-exe`, `build-obj` or `build-lib` commands from the\n`zig` compiler that we exposed at @sec-compile-code, these `test` blocks are automatically\nignored by the compiler.\n\nIn other words, the `zig` compiler builds and execute your unit tests only\nwhen you ask it to. By default, the compiler always ignore `test`\nblocks written in your Zig modules. The compiler normally checks only if\nthere are any syntax errors in these `test` blocks.\n\nIf you take a look at the source code for most of the files present in the\nZig Standard Library[^zig-std-lib], you can see that the `test` blocks\nare written together with the normal source code of the library.\nYou can see this for example, at the [`array_list` module](https://github.com/ziglang/zig/blob/master/lib/std/array_list.zig)[^zig-array].\nSo, the standard that the Zig developers decided to adopt\nis to keep their unit tests together with the source code\nof the functionality that they are testing.\n\nEach programmer might have a different opinion on this.\nSome of them might prefer to keep unit tests separate from the actual\nsource code of their application. If that is your case, you can\nsimply create a separate `tests` folder in your project, and\nstart writing Zig modules that contains only unit tests (as you would normally do\non a Python project with `pytest`, for example), and everything will work fine.\nIt boils down to which is your preference here.\n\n[^zig-std-lib]: <https://github.com/ziglang/zig/tree/master/lib/std>\n[^zig-array]: <https://github.com/ziglang/zig/blob/master/lib/std/array_list.zig>\n\n\n## How to run your tests\n\nIf the `zig` compiler ignores any `test` block by default, how can\nyou compile and run your unit tests? The answer is the `test` command from\nthe `zig` compiler. By running the `zig test` command, the compiler will\nfind every instance of a `test` block in your Zig modules, and, it will\ncompile and run the unit tests that you wrote.\n\n\n```bash\nzig test simple_sum.zig\n```\n\n```\n1/1 simple_sum.test.testing simple sum... OK\nAll 1 tests passed.\n```\n\n\n## Testing memory allocations\n\nOne of the advantages of Zig is that it offers great tools\nthat help us, programmers, to avoid (but also detect) memory problems, such as\nmemory leaks and double-frees. The `defer` keyword\nis especially helpful in this regard.\n\nWhen developing your source code, you, the programmer, is responsible for making\nsure that your code do not produce such problems. However,\nyou can also use a special type of an allocator object in Zig\nthat is capable of automatically detecting such problems for you.\nThis is the `std.testing.allocator` object.\nThis allocator object offers some basic memory safety detection\nfeatures, which are capable of detecting memory leaks.\n\nAs we described at @sec-heap, to allocate memory on the heap, you need\nto use an allocator object, and your functions that use these objects to allocate memory\non the heap, should receive an allocator object as one of its inputs.\nEvery memory on the heap that you allocate using these allocator objects,\nmust also be freed using this same allocator object.\n\nSo, if you want to test the memory allocations performed by your functions,\nand make sure that you don't have problems in these allocations, you can simply\nwrite unit tests for these functions, where you provide the\n`std.testing.allocator` object as input to these functions.\n\nLook at the example below, where I'm defining a function that clearly causes\na memory leak. Because we allocate memory, but, at the same time,\nwe do not free this allocated memory at any point. So, when the function\nreturns, we lose the reference to the `buffer` object, which contains\nthe allocated memory, and, as a result, we can no longer free this memory.\n\nNotice that, inside a `test` block I execute this function with\nthe `std.testing.allocator`. The allocator object was capable\nof looking deeper in our program, and detecting the memory leak. As a result,\nthis allocator object returns an error message of \"memory leaked\", and also,\na stack trace showing the exact point where the memory was leaked.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nfn some_memory_leak(allocator: Allocator) !void {\n    const buffer = try allocator.alloc(u32, 10);\n    _ = buffer;\n    // Return without freeing the\n    // allocated memory\n}\n\ntest \"memory leak\" {\n    const allocator = std.testing.allocator;\n    try some_memory_leak(allocator);\n}\n```\n:::\n\n\n\n\n```\nTest [1/1] leak_memory.test.memory leak...\n    [gpa] (err): memory address 0x7c1fddf39000 leaked: \n./ZigExamples/debugging/leak_memory.zig:4:39: 0x10395f2\n    const buffer = try allocator.alloc(u32, 10);\n                                      ^\n./ZigExamples/debugging/leak_memory.zig:12:25: 0x10398ea\n    try some_memory_leak(allocator);\n\n... more stack trace\n```\n\n\n## Testing errors\n\nOne common style of unit tests are those that look for\nspecific errors in your functions. In other words, you write\na unit test that tries to assert if a specific function call\nreturns any error, or a specific type of error.\n\nIn C++ you would normally write this style of unit tests using, for example,\nthe functions `REQUIRE_THROWS()` or `CHECK_THROWS()` from the [`Catch2` test framework](https://github.com/catchorg/Catch2/tree/devel)[^catch2].\nIn the case of a Python project, you would probably use the\n[`raises()` function from `pytest`](https://docs.pytest.org/en/7.1.x/reference/reference.html#pytest-raises)[^pytest].\nWhile in Rust, you would probably use `assert_eq!()` in conjunction with `Err()`.\n\n[^pytest]: <https://docs.pytest.org/en/7.1.x/reference/reference.html#pytest-raises>\n[^catch2]: <https://github.com/catchorg/Catch2/tree/devel>\n\n\nBut in Zig, we use the `expectError()` function, from the `std.testing` module.\nWith this function, you can test if a specific function call returns the exact\ntype of error that you expect it to return. To use this function, you first write\n`try expectError()`. Then, on the first argument, you provide the type of error that you\nare expecting from the function call. Then, on the second argument, you write\nthe function call that you expect to fail.\n\nThe code example below demonstrates such type of unit test in Zig.\nNotice that, inside the function `alloc_error()` we are allocating\n100 bytes of memory, or, an array of 100 elements, for the object `ibuffer`. However,\nin the `test` block, we are using the `FixedBufferAllocator()`\nallocator object, which is limited to 10 bytes of space, because\nthe object `buffer`, which we provided to the allocator object,\nhave only 10 bytes of space.\n\nThat is why, the `alloc_error()` function raises an `OutOfMemory` error\non this case.\nBecause this function is trying to allocate more space than the allocator\nobject allows.\nSo, in essence, we are testing for a specific type of error,\nwhich is `OutOfMemory`. If the `alloc_error()` function returns any other type of error,\nthen, the `expectError()` function would make the entire test fail.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst expectError = std.testing.expectError;\nfn alloc_error(allocator: Allocator) !void {\n    var ibuffer = try allocator.alloc(u8, 100);\n    defer allocator.free(ibuffer);\n    ibuffer[0] = 2;\n}\n\ntest \"testing error\" {\n    var buffer: [10]u8 = undefined;\n    var fba = std.heap.FixedBufferAllocator.init(&buffer);\n    const allocator = fba.allocator();\n    try expectError(error.OutOfMemory, alloc_error(allocator));\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file103bc545495c8.test.testing error...OKAll 1\n  1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n```\n1/1 oom.test.testing error... OK\nAll 1 tests passed.\n```\n\n\n\n## Testing simple equalities\n\nIn Zig, there are some different ways you can test for an equality.\nYou already saw that we can use `expect()` with the logical operator `==`\nto essentially reproduce an equality test. But we also have\nsome other helper functions that you should know about, especially\n`expectEqual()`, `expectEqualSlices()` and `expectEqualStrings()`.\n\n\nThe `expectEqual()` function, as the name suggests, is a classic\ntest equality function. It receives two objects as input. The first\nobject is the value that you expect to be in the second object.\nWhile second object is the object you have, or, the object that your application\nproduced as result. So, with `expectEqual()` you are essentially\ntesting if the values stored inside these two objects\nare equal or not.\n\nYou can see in the example below that, the test performed by\n`expectEqual()` failed. Because the objects `v1` and `v2` contain\ndifferent values in them.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"values are equal?\" {\n    const v1 = 15;\n    const v2 = 18;\n    try std.testing.expectEqual(v1, v2);\n}\n```\n:::\n\n\n\n\n```\n1/1 ve.test.values are equal?...\n    expected 15, found 18\n    FAIL (TestExpectedEqual)\nve.zig:5:5: test.values are equal? (test)\n    try std.testing.expectEqual(v1, v2);\n    ^\n0 passed; 0 skipped; 1 failed.\n```\n\n\nAlthough useful, the `expectEqual()` function does not work with arrays.\nFor testing if two arrays are equal, you should use the `expectEqualSlices()`\nfunction instead. This function have three arguments. First, you provide\nthe data type contained in both arrays that you are trying to compare.\nWhile the second and third arguments corresponds to the array objects that you want to compare.\n\nIn the example below, we are using this function to test if two array\nobjects (`array1` and `array2`) are equal or not. Since they\nare in fact equal, the unit test passed with no errors.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"arrays are equal?\" {\n    const array1 = [3]u32{1, 2, 3};\n    const array2 = [3]u32{1, 2, 3};\n    try std.testing.expectEqualSlices(\n        u32, &array1, &array2\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file103bc78cf09de.test.arrays are equal?...OKA\n  All 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n```\n1/1 oom.test.arrays are equal?... OK\nAll 1 tests passed.\n```\n\n\nAt last, you might also want to use the `expectEqualStrings()` function.\nAs the name suggests, you can use this function to test if two strings\nare equal or not. Just provide the two string objects that you want to compare,\nas inputs to the function.\n\nIf the function finds any existing differences between the two strings,\nthen, the function will raise an error, and also, print an error message\nthat shows the exact difference between the two string objects provided,\nas the example below demonstrates:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"strings are equal?\" {\n    const str1 = \"hello, world!\";\n    const str2 = \"Hello, world!\";\n    try std.testing.expectEqualStrings(\n        str1, str2\n    );\n}\n```\n:::\n\n\n\n\n```\n1/1 t.test.strings are equal?... \n====== expected this output: =========\nhello, world!␃\n======== instead found this: =========\nHello, world!␃\n======================================\nFirst difference occurs on line 1:\nexpected:\nhello, world!\n^ ('\\x68')\nfound:\nHello, world!\n^ ('\\x48')\n```\n\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
diff --git a/_freeze/Chapters/04-http-server/execute-results/html.json b/_freeze/Chapters/04-http-server/execute-results/html.json
index c2f423f2..8f509955 100644
--- a/_freeze/Chapters/04-http-server/execute-results/html.json
+++ b/_freeze/Chapters/04-http-server/execute-results/html.json
@@ -3,9 +3,7 @@
   "result": {
     "engine": "knitr",
     "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 2 - Building a HTTP Server from scratch\n\nIn this chapter, I want to implement a new\nsmall project with you. This time, we are going\nto implement a basic HTTP Server from scratch.\n\nThe Zig Standard Library already have a HTTP Server\nimplemented, which is available at `std.http.Server`.\nBut again, our objective here in this chapter, is to implement\nit **from scratch**. So we can't use this server object available\nfrom the Zig Standard Library.\n\n## What is a HTTP Server?\n\nFirst of all, what is a HTTP Server?\nA HTTP server, as any other type of server, is essentially\na program that runs indefinitely, on an infinite loop, waiting for incoming connections\nfrom clients. Once the server receives an incoming connection, it will\naccept this connection, and it will send messages back-and-forth to the client\nthrough this connection.\n\nBut the messages that are transmitted inside this connection are in a\nspecific format. They are HTTP messages\n(i.e. messages that use the HTTP Protocol specification).\nThe HTTP Protocol is the backbone of the modern web.\nThe world wide web as we know it today, would not exist without the \nHTTP Protocol.\n\nSo, Web servers (which is just a fancy name to\nHTTP Servers) are servers that exchange HTTP messages with clients.\nAnd these HTTP servers and the HTTP Protocol specification\nare essential to the operation of the world wide web today.\n\nThat is the whole picture of the process.\nAgain, we have two subjects involved here, a server (which is\na program that is running indefinitely, waiting to receive incoming connections),\nand a client (which is someone that wants to connect to the server,\nand exchange HTTP messages with it).\n\nYou may find the material about the [HTTP Protocol available at the Mozilla MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview)[^mdn-http]\n, a great resource for you to also look at. It gives you a great overview on how\nHTTP works, and what role the server plays in this matter.\n\n[^mdn-http]: <https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview>.\n\n\n## How a HTTP Server works? {#sec-how-http-works}\n\nImagine a HTTP Server as if it were the receptionist of a large hotel. In a hotel,\nyou have a reception, and inside that reception there is a receptionist\nwaiting for customers to arrive. A HTTP Server is essentially a receptionist\nthat is indefinitely waiting for new customers (or, in the context of HTTP, new clients)\nto arrive in the hotel.\n\nWhen a customer arrives at the hotel, that customer starts a conversation with the\nreceptionist. He tells the receptionist how many days he wants to stay at the hotel.\nThen, the receptionist search for an available apartment. If there is an available apartment\nat the moment, the customer pays the hotel fees, then, he gets the keys to the apartment,\nand then, he goes to the apartment to rest.\n\nAfter this entire process of dealing with the customer (searching for available apartments,\nreceiving payment, handing over the keys), the receptionist goes back to what he was\ndoing earlier, which is to wait. Wait for new customers to arrive.\n\nThat is, in a nutshell, what a HTTP Server do. It waits for clients to connect to the\nserver. When a client attempts to connect to the server, the server accepts this connection,\nand it starts to exchange messages with the client through this connection.\nThe first message that happens inside this connection is always a message from the client\nto the server. This message is called the *HTTP Request*.\n\nThis HTTP Request is a HTTP message that contains what\nthe client wants from the server. It is literally a request. The client\nthat connected to the server is asking this server to do something for him.\n\nThere are different \"types of request\" that a client can send to a HTTP Server.\nBut the most basic type of request, is when a client ask to the\nHTTP Server to serve (i.e. to send) some specific web page (which is a HTML file) to him.\nWhen you type `google.com` in your web browser, you are essentially sending a HTTP Request to Google's\nHTTP servers. This request is asking these servers to send the Google webpage to you.\n\nNonetheless, when the server receives this first message, the *HTTP Request*, it\nanalyzes this request, to understand: who the client is? What he wants the server to do?\nThis client has provided all the necessary information to perform the action that he\nasked? Etc.\n\nOnce the server understands what the client wants, he simply perform the action\nthat was requested, and, to finish the whole process, the server sends back\na HTTP message to the client, informing if the action performed was successful or not,\nand, at last, the server ends (or closes) the connection with the client.\n\nThis last HTTP message sent from the server to the client, is called the *HTTP Response*.\nBecause the server is responding to the action that was requested by the client.\nThe main objective of this response message is let the client know if the\naction requested was successful or not, before the server closes the connection.\n\n\n## How a HTTP server is normally implemented? {#sec-http-how-impl}\n\nLet's use the C language as an example. There are many materials\nteaching how to write a simple HTTP server in C code, like @jeffrey_http,\nor @nipun_http, or @eric_http.\nHaving this in mind, I will not show C code examples here, because you\ncan find them on the internet.\nBut I will describe the theory behind the necessary steps to create\nsuch HTTP server in C.\n\n\nIn essence, we normally implement a HTTP server in C by using WebSocket technology,\nwhich involves the following steps:\n\n1. Create a socket object.\n1. Bind a name (or more specifically, an address) to this socket object.\n1. Make this socket object to start listening and waiting for incoming connections.\n1. When a connection arrive, we accept this connection, and we exchange the HTTP messages (HTTP Request and HTTP Response).\n1. Then, we simply close this connection.\n\n\nA socket object is essentially a channel of communication.\nYou are creating a channel where people can send messages through.\nWhen you create a socket object, this object is not binded to any particular\naddress. This means that with this object you have a representation of a channel of communication\nin your hands. But this channel is not currently available, or, it is not currently accessible,\nbecause it do not have a known address where you can find it.\n\nThat is what the \"bind\" operation do. It binds a name (or more specifically, an address) to\nthis socket object, or, this channel of communication, so that it becomes available,\nor, accessible through this address. While the \"listen\" operation makes the socket object to\nlisten for incoming connections in this address. In other words, the \"listen\" operation\nmakes the socket to wait for incoming connections.\ncurrently\nNow, when a client actually attempts to connect to the server through the socket address\nthat we have specified, in order to establish this connection with the client,\nthe socket object needs to accept this incoming connection. Thus, when we\naccept an incoming connection, the client and the server become\nconnected to each other, and they can start reading or writing messages into this\nestablished connection.\n\nAfter we receive the HTTP Request from the client, analyze it, and send the HTTP Response\nto the client, we can then close the connection, and end this communication.\n\n\n## Implementing the server - Part 1\n\n### Creating the socket object {#sec-create-socket}\n\nLet's begin with creating the socket object for our server.\nJust to make things shorter, I will create this socket object in\na separate Zig module. I will name it `config.zig`.\n\nIn Zig, we can create a web socket using\nthe `std.posix.socket()` function, from the Zig Standard Library.\nAs I mentioned earlier at @sec-http-how-impl, every socket object that we create\nrepresents a communication channel, and we need to bind this channel to a specific address.\nAn \"address\" is defined as an IP address, or, more specifically, an IPv4 address^[It can be also an IPv6 address. But normally, we use a IPv4 address for that.].\nEvery IPv4 address is composed by two components. The first component is the host,\nwhich is a sequence of 4 numbers separated by dot characters (`.`) that identifies the machine used.\nWhile the second component is a port number, which identifies the specific\ndoor, or, the specific port to use in the host machine.\n\nThe sequence of 4 numbers (i.e. the host) identifies the machine (i.e. the computer itself) where\nthis socket will live in. Every computer normally have multiple \"doors\" available inside of him, because \nthis allows the computer to receive and work with multiple connections at the same time.\nHe simply use a single door for each connection. So the port number, is\nessentially a number that identifies the specific door in the computer that will be responsible\nfor receiving the connection. That is, it identifies the \"door\" in the computer that the socket will use\nto receive incoming connections.\n\nTo make things simpler, I will use an IP address that identifies our current machine in this example.\nThis means that, our socket object will reside on the same computer that we are currently using\n(this is also known as the \"localhost\") to write this Zig source code.\n\nBy convention, the IP address that identifies the \"localhost\", which is the current machine we\nare using, is the IP `127.0.0.1`. So, that is the IP\naddress we are going to use in our server. I can declare it in Zig\nby using an array of 4 integers, like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst localhost = [4]u8{ 127, 0, 0, 1 };\n_ = localhost;\n```\n:::\n\n\n\n\nNow, we need to decide which port number to use. By convention, there are some\nport numbers that are reserved, meaning that, we cannot use them for our own\npurposes, like the port 22 (which is normally used for SSH connections).\nFor TCP connections, which is our case here,\na port number is a 16-bit unsigned integer (type `u16` in Zig),\nthus ranging from 0 to 65535 [@wikipedia_port].\nSo, we can choose\na number from 0 to 65535 for our port number. In the \nexample of this book, I will use the port number 3490\n(just a random number).\n\n\nNow that we have these two informations at hand, I can\nfinally create our socket object, using the `std.posix.socket()` function.\nFirst, we use the host and the port number to create an `Address` object,\nwith the `std.net.Address.initIp4()` function, like in the example below.\nAfter that, I use this address object inside the `socket()` function\nto create our socket object.\n\nThe `Socket` struct defined below summarizes all the logic behind\nthis process. In this struct, we have two data members, which are:\n1)  the address object; 2) and a stream object, which is\nthe object we will use to read and write the messages into any connection we establish.\n\nNotice that, inside the constructor method of this struct,\nwhen we create the socket object, we are using the `IPROTO.TCP` property as an input to\ntell the function to create a socket for TCP connections.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\nconst net = @import(\"std\").net;\n\npub const Socket = struct {\n    _address: std.net.Address,\n    _stream: std.net.Stream,\n\n    pub fn init() !Socket {\n        const host = [4]u8{ 127, 0, 0, 1 };\n        const port = 3490;\n        const addr = net.Address.initIp4(host, port);\n        const socket = try std.posix.socket(\n            addr.any.family,\n            std.posix.SOCK.STREAM,\n            std.posix.IPPROTO.TCP\n        );\n        const stream = net.Stream{ .handle = socket };\n        return Socket{ ._address = addr, ._stream = stream };\n    }\n};\n```\n:::\n\n\n\n\n\n### Listening and receiving connections\n\nRemember that we stored the `Socket` struct\ndeclaration that we built at @sec-create-socket inside a Zig module named `config.zig`.\nThis is why I imported this module into our main module (`main.zig`) in the example below, as the `SocketConf` object,\nto access the `Socket` struct.\n\nOnce we created our socket object, we can focus now on making this socket object\nlisten and receive new incoming connections. We do that, by calling the `listen()`\nmethod from the `Address` object that is contained inside the socket object, and then,\nwe call the `accept()` method over the result.\n\nThe `listen()` method from the `Address` object produces a server object,\nwhich is an object that will stay open and running indefinitely, waiting\nto receive an incoming connection. Therefore, if you try to run the code\nexample below, by calling the `run` command from the `zig` compiler,\nyou will notice that the programs keeps running indefinitely,\nwithout a clear end.\n\nThis happens, because the program is waiting for something to happen.\nIt is waiting for someone to try to connect to the address (`http://127.0.0.1:3490`) where\nthe server is running and listening for incoming connections. This is what\nthe `listen()` method do, it makes the socket to be active waiting for someone\nto connect.\n\nOn the other side, the `accept()` method is the function that establishes the connection\nwhen someone tries to connect to the socket. This means that, the `accept()` method\nreturns a new connection object as a result. And you can use this connection object\nto read or write messages from or to the client.\nFor now, we are not doing anything with this connection object.\nBut we are going to use it on the next section.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n    _ = connection;\n}\n```\n:::\n\n\n\n\nThis code example allows one single connection. In other words, the\nserver will wait for one incoming connection, and as soon as the\nserver is done with this first connection that it establishes, the\nprogram ends, and the server stops.\n\nThis is not the norm on the real world. Most people that write\na HTTP server like this, usually put the `accept()` method\ninside a `while` (infinite) loop, where if a connection\nis created with `accept()`, a new thread of execution is created to deal with\nthis new connection and the client. That is, real-world examples of HTTP Servers\nnormally rely on parallel computing to work.\n\nWith this design, the server simply accepts the connection,\nand the whole process of dealing with the client, and receiving\nthe HTTP Request, and sending the HTTP Response, all of this\nis done in the background, on a separate execution thread.\n\nSo, as soon as the server accepts the connection, and creates\nthe separate thread, the server goes back to what he was doing earlier,\nwhich is to wait indefinitely for a new connection to accept.\nHaving this in mind, the code example exposed above, is a\nserver that serves only a single client. Because the program\nterminates as soon as the connection is accepted.\n\n\n\n### Reading the message from the client {#sec-read-http-message}\n\nNow that we have a connection established, i.e. the connection\nobject that we created through the `accept()` function, we can now\nuse this connection object to read any messages that the client\nsend to our server. But we can also use it to send messages back\nto the client.\n\nThe basic idea is, if we **write** any data into this connection object,\nthen, we are sending data to the client, and if we **read** the data present in\nthis connection object, then, we are reading any data that the\nclient sent to us, through this connection object. So, just\nhave this logic in mind. \"Read\" is for reading messages from the client,\nand \"write\" is to send a message to the client.\n\nRemember from @sec-how-http-works that, the first thing that we need to do is to read the HTTP Request\nsent by the client to our server. Because it is the first message that happens\ninside the established connection, and, as a consequence, it is the first\nthing that we need to deal with.\n\nThat is why, I'm going to create a new Zig module in this small project, named `request.zig`\nto keep all functions related to the HTTP Request\ntogether. Then, I will create a new function named `read_request()` that will\nuse our connection object to read the message sent by the client,\nwhich is the HTTP Request.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Connection = std.net.Server.Connection;\npub fn read_request(conn: Connection,\n                    buffer: []u8) !void {\n    const reader = conn.stream.reader();\n    _ = try reader.read(buffer);\n}\n```\n:::\n\n\n\n\n\nThis function accepts a slice object which behaves as a buffer.\nThe `read_request()` function reads the message sent into\nthe connection object, and saves this message into this buffer object that\nwe have provided as input.\n\nNotice that I'm using the connection object that we created to read\nthe message from the client. I first access the `reader` object that lives inside the\nconnection object. Then, I call the `read()` method of this `reader` object\nto effectively read and save the data sent by the client into the buffer object\nthat we created earlier. I'm discarding the return value\nof the `read()` method, by assigning it to the underscore character (`_`),\nbecause this return value is not useful for us right now.\n\n\n\n## Looking at the current state of the program\n\n\nI think now is a good time to see how our program is currently working. Shall we?\nSo, the first thing I will do is to update the `main.zig` module in our small Zig project,\nso that the `main()` function call this new `read_request()` function that we have just created.\nI will also add a print statement at the end of the `main()` function,\njust so that you can see what the HTTP Request that we have just loaded into the buffer object\nlooks like.\n\nAlso, I'm creating the buffer object in the `main()` function, which will be\nresponsible for storing the message sent by the client, and, I'm also\nusing a `for` loop to initialize all fields of this buffer object to the number zero.\nThis is important to make sure that we don't have uninitialized memory in\nthis object. Because uninitialized memory may cause undefined behaviour in our program.\n\nSince the `read_request()` function should receive as input the buffer object as a slice object (`[]u8`),\nI am using the syntax `array[0..array.len]` to get access to a slice of this `buffer` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    _ = try Request.read_request(\n        connection, buffer[0..buffer.len]\n    );\n    try stdout.print(\"{s}\\n\", .{buffer});\n}\n```\n:::\n\n\n\n\nNow, I'm going to execute this program, with the `run` command from the\n`zig` compiler. But remember, as we sad earlier, as soon as I execute this program, it will\nhang indefinitely, because the program is waiting for a client trying to\nconnect to the server.\n\nMore specifically, the program will pause at the line\nwith the `accept()` call. As soon as a client try to connect to the\nserver, then, the execution will \"unpause\", and the `accept()` function\nwill finally be executed to create the\nconnection object that we need, and the remaining of the program\nwill run.\n\nYou can see that at @fig-print-zigrun1. The message `Server Addr: 127.0.0.1:3490`\nis printed to the console, and the program is now waiting for an incoming connection.\n\n![A screenshot of running the program](./../Figures/print-zigrun1.png){#fig-print-zigrun1}\n\n\nWe can finally try to connect to this server, and there are several ways we can do this.\nFor example, we could use the following Python script:\n\n```python\nimport requests\nrequests.get(\"http://127.0.0.1:3490\")\n```\n\nOr, we could also open any web browser of our preference, and type\nthe URL `localhost:3490`. OBS: `localhost` is the same thing as the\nIP `127.0.0.1`. When you press enter, and your web browser go\nto this address, first, the browser will probably print a message\nsaying that \"this page isn't working\", and, then, it will\nprobably change to a new message saying that \"the site can't be\nreached\".\n\nYou get these \"error messages\" in the web browser, because\nit got no response back from the server. In other words, when the web\nbrowser connected to our server, it did send the HTTP Request through the established connection.\nThen, the web browser was expecting to receive a HTTP Response back, but\nit got no response from the server (we didn't implemented the HTTP Response logic yet).\n\nBut that is okay. We have achieved the result that we wanted for now,\nwhich is to connect to the server, and see the HTTP Request\nthat was sent by the web browser (or by the Python script)\nto the server.\n\nIf you comeback to the console that you left open\nwhen you have executed the program, you will see that the\nprogram finished its execution, and, a new message is\nprinted in the console, which is the actual HTTP Request\nmessage that was sent by the web browser to the server.\nYou can see this message at @fig-print-zigrun2.\n\n![A screenshot of the HTTP Request sent by the web browser](./../Figures/print-zigrun2.png){#fig-print-zigrun2}\n\n\n\n\n## Learning about Enums in Zig {#sec-enum}\n\nEnums structures are available in Zig through the `enum` keyword.\nAn enum (short for \"enumeration\") is a special structure that represents a group of constant values.\nSo, if you have a variable which can assume a short and known\nset of values, you might want to associate this variable to an enum structure,\nto make sure that this variable only assumes a value from this set.\n\nA classic example for enums are primary colors. If for some reason, your program\nneeds to represent one of the primary colors, you can create an enum\nthat represents one of these colors.\nIn the example below, we are creating the enum `PrimaryColorRGB`, which\nrepresents a primary color from the RGB color system. By using this enum,\nI am guaranteed that the `acolor` object for example, will contain\none of these three values: `RED`, `GREEN` or `BLUE`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst PrimaryColorRGB = enum {\n    RED, GREEN, BLUE\n};\nconst acolor = PrimaryColorRGB.RED;\n_ = acolor;\n```\n:::\n\n\n\n\nIf for some reason, my code tries to save in `acolor`,\na value that is not in this set, I will get an error message\nwarning me that a value such as \"MAGENTA\" do not exist\ninside the `PrimaryColorRGB` enum.\nThen I can easily fix my mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst acolor = PrimaryColorRGB.MAGENTA;\n```\n:::\n\n\n\n\n```\ne1.zig:5:36: error: enum 'PrimaryColorRGB' has\n        no member named 'MAGENTA':\n    const acolor = PrimaryColorRGB.MAGENTA;\n                                   ^~~~~~~\n```\n\nBehind the hood, enums in Zig work the same way that enums\nwork in C. Each enum value is essentially represented as an integer.\nThe first value in the set is represented as zero,\nthen, the second value is one, ... etc.\n\nOne thing that we are going to learn on the next section is that\nenums can have methods in them. Wait... What? This is amazing!\nYes, enums in Zig are similar to structs, and they can have\nprivate and public methods inside them.\n\n\n\n\n\n\n\n## Implementing the server - Part 2\n\nNow, on this section, I want to focus on parsing\nthe HTTP Request that we received from the client.\nHowever, to effectively parse a HTTP Request message, we first need to understand its\nstructure.\nIn summary, a HTTP Request is a text message that is divided into 3 different\nsections (or parts):\n\n- The top-level header indicating the method of the HTTP Request, the URI, and the HTTP version used in the message.\n- A list of HTTP Headers.\n- The body of the HTTP Request.\n\n### The top-level header\n\nThe first line of text in a HTTP Request always come with the three most essential\ninformation about the request. These three key attributes of the HTTP Request\nare separated by a simple space in this first line of the request.\nThe first information is the HTTP method that is being\nused in the request, second, we have the URI to which this HTTP Request is being sent to,\nand third, we have the version of the HTTP protocol that is being used in this HTTP Request.\n\nIn the snippet below, you can find an example of this first line in a HTTP Request.\nFirst, we have the HTTP method of this request (`GET`). Many programmers\nrefer to the URI component (`/users/list`) as the \"API endpoint\" to which the HTTP Request\nis being sent to. In the context of this specific request, since it is a GET request,\nyou could also say that the URI component is the path to the resource we want to access,\nor, the path to the document (or the file) that we want to retrieve from the server.\n\n```\nGET /users/list HTTP/1.1\n```\n\nAlso, notice that this HTTP Request is using the version 1.1 of the HTTP protocol,\nwhich is the most popular version of the protocol used in the web.\n\n\n\n### The list of HTTP headers\n\nMost HTTP Requests also include a section of HTTP Headers,\nwhich is just a list of attributes or key-value pairs associated with this\nparticular request. This section always comes right after the \"top-level header\" of the request.\n\nFor our purpose in this chapter, which is to build a simple HTTP Server,\nwe are going to ignore this section of the HTTP Request, for simplicity.\nBut most HTTP servers that exist in the wild parses and use these\nHTTP headers to change the way that the server responds to the request\nsent by the client.\n\nFor example, many requests we encounter in the real-world comes with\na HTTP header called `Accept`. In this header, we find a list of [MIME types](https://en.wikipedia.org/wiki/Media_type)[^mime].\nThis list indicates the file formats that the client can read, or parse, or interpret.\nIn other words, you also interpret this header as the client saying the following phrase\nto the server: \"Hey! Look, I can read only HTML documents, so please, send me back\na document that is in a HTML format.\".\n\n[^mime]: <https://en.wikipedia.org/wiki/Media_type>.\n\nIf the HTTP server can read and use this `Accept` header, then, the server can identify\nwhich is the best file format for the document to be sent to the client. Maybe the HTTP server have\nthe same document in multiple formats, for example, in JSON, in XML, in HTML and in PDF,\nbut the client can only understand documents in the HTML format. That is the purpose\nof this `Accept` header.\n\n\n### The body\n\nThe body comes after the list of HTTP headers, and it is an optional section of the HTTP Request, meaning that, not\nall HTTP Request will come with a body in it. For example, every HTTP Request that uses the\nGET method usually do not come with a body.\n\nBecause a GET request is used to request data, instead of sending it to the server.\nSo, the body section is more related to the POST method, which is a method that involves\nsending data to the server, to be processed and stored.\n\nSince we are going to support only the GET method in this project, it means that\nwe also do not need to care about the body of the request.\n\n\n\n### Creating the HTTP Method enum\n\nEvery HTTP Request comes with a explicit method. The method used in a HTTP Request\nis identified by one these words:\n\n- GET;\n- POST;\n- OPTIONS;\n- PATCH;\n- DELETE;\n- and some other methods.\n\nEach HTTP method is used for a specific type of task. The POST method for example is normally\nused to post some data into the destination. In other words, it is used\nto send some data to the HTTP server, so that it can be processed and stored by the server.\n\nAs another example, the GET method is normally used to get content from the server.\nIn other words, we use this method whenever we want the server to send some\ncontent back to us. It can be any type of content. It can be a web page,\na document file, or some data in a JSON format.\n\nWhen a client sends a POST HTTP Request, the HTTP Response sent by the server normally have the sole purpose of\nletting the client know if the server processed and stored the data successfully.\nIn contrast, when the server receives a GET HTTP Request, then, the server sends the content\nthat the client asked for in the HTTP Response itself. This demonstrates that the method associated\nwith the HTTP Request changes a lot on the dynamics and the roles that each party\nplays in the whole process.\n\nSince the HTTP method of the HTTP Request is identified by this very small and specific\nset of words, it would be interesting to create an enum structure to represent a HTTP method.\nThis way, we can easily check if the HTTP Request we receive from the client is a\nHTTP method that we currently support in our small HTTP server project.\n\nThe `Method` structure below represents this enumeration.\nNotice that, for now, only the GET HTTP method is included in this\nenumeration. Because, for the purpose of this chapter, I want to\nimplement only the GET HTTP method. That is why I am not\nincluding the other HTTP methods in this enumeration.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const Method = enum {\n    GET\n};\n```\n:::\n\n\n\n\n\nNow, I think we should add two methods to this enum structure. One method is `is_supported()`,\nwhich will be a function that returns a boolean value, indicating if the input HTTP method is supported\nor not by our HTTP Server. The other is `init()`, which is a constructor function that takes a string as input,\nand tries to convert it into a `Method` value.\n\n\nBut in order to build these functions, I will use a functionality from the Zig Standard Library, called\n`StaticStringMap()`. This function allows us to create a simple map from strings to enum values.\nIn other words, we can use this map structure to map a string to the respective enum value.\nTo some extent, this specific structure from the standard library works almost like a \"hashtable\" structure,\nand it is optimized for small sets of words, or, small sets of keys, which is our case here.\nWe are going to talk more about hashtables in Zig at @sec-maps-hashtables.\n\nTo use this \"static string map\" structure, you have to import it from the `std.static_string_map` module\nof the Zig Standard Library. Just to make things shorter and easier to type, I am going to import this\nfunction through a different and shorter name (`Map`).\n\nWith `Map()` imported, we can just apply this function over the enum structure\nthat we are going to use in the resulting map. In our case here, it is the `Method` enum structure\nthat we declared at the last code example. Then, I call the `initComptime()` method with the\nmap, i.e. the list of key-value pairs that we are going to use.\n\nYou can see in the example below that I wrote this map using multiple anonymous struct literals.\nInside the first (or \"top-level\") struct literal, we have a list (or a sequence) of struct literals.\nEach struct literal in this list represents a separate key-value pair. The first element (or the key)\nin each key-value pair should always be a string value. While the second element should\nbe a value from the enum structure that you have used inside the `Map()` function.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Map = std.static_string_map.StaticStringMap;\nconst MethodMap = Map(Method).initComptime(.{\n    .{ \"GET\", Method.GET },\n});\n```\n:::\n\n\n\n\nTherefore, the `MethodMap` object is basically a `std::map` object from C++, or,\na `dict` object from Python. You can retrieve (or get) the enum value that\ncorresponds to a particular key, by using the `get()` method from the map\nobject. This method returns an optional value, so, the `get()` method might\nresult in a null value.\n\nWe can use this in our advantage to detect if a particular HTTP method is\nsupported or not in our HTTP server. Because, if the `get()` method returns null,\nit means that it did not found the method that we provided inside the `MethodMap` object, and,\nas a consequence, this method is not supported by our HTTP server.\n\nThe `init()` method below, takes a string value as input, and then, it simply passes this string value\nto the `get()` method of our `MethodMap` object. As consequence, we should get the enum value that corresponds\nto this input string.\n\nNotice in the example below that, the `init()` method returns either an error\n(which might happen if the `?` method returns `unreacheable`, checkout @sec-null-handling for more details)\nor a `Method` object as result. Since `GET` is currently the only value in our `Method` enum\nstructure, it means that, the `init()` method will most likely return the value `Method.GET` as result.\n\nAlso notice that, in the `is_supported()` method, we are using the optional value returned\nby the `get()` method from our `MethodMap` object. The if statement unwraps the optional value\nreturned by this method, and returns `true` in case this optional value is a not-null value.\nOtherwise, it simply returns `false`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const Method = enum {\n    GET,\n    pub fn init(text: []const u8) !Method {\n        return MethodMap.get(text).?;\n    }\n    pub fn is_supported(m: []const u8) bool {\n        const method = MethodMap.get(m);\n        if (method) |_| {\n            return true;\n        }\n        return false;\n    }\n};\n```\n:::\n\n\n\n\n\n\n\n\n\n\n### Writing the parse request function\n\nNow that we created the enum that represents our HTTP method,\nwe should start to write the function responsible for\nactually parsing the HTTP Request.\n\nThe first thing we can do, is to write a struct to represent the HTTP Request.\nTake the `Request` struct below as an example. It contains the three\nessential information from the \"top-level\" header (i.e. the first line)\nin the HTTP Request.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Request = struct {\n    method: Method,\n    version: []const u8,\n    uri: []const u8,\n    pub fn init(method: Method,\n                uri: []const u8,\n                version: []const u8) Request {\n        return Request{\n            .method = method,\n            .uri = uri,\n            .version = version,\n        };\n    }\n};\n```\n:::\n\n\n\n\n\nThe `parse_request()` function should receive a string as input. This input string\ncontains the entire HTTP Request message, and the parsing function should\nread and understand the individual parts of this message.\n\nNow, remember that for the purpose of this chapter, we care only about the first\nline in this message, which contains the \"top-level header\", or, the three essential attributes about the HTTP Request,\nwhich are the HTTP method used, the URI and the HTTP version.\n\nNotice that I use the function `indexOfScalar()` in `parse_request()`. This function from the\nZig Standard Library returns the first index where the scalar value that we provide\nhappens in a string. In this case, I'm looking at the first occurrence of the new line character (`\\n`).\nBecause once again, we care only about the first line in the HTTP Request message.\nThis is the line where we have the three information that we want to parse\n(version of HTTP, the HTTP method and the URI).\n\nTherefore, we are using this `indexOfScalar()` function\nto limit our parsing process to the first line in the message.\nIs also worth mentioning that, the `indexOfScalar()` function returns an optional value.\nThat is why I use the `orelse` keyword to provide an alternative value, in case\nthe value returned by the function is a null value.\n\nSince each of these three attributes are separated by a simple space, we\ncould use the function `splitScalar()` from the Zig Standard Library to split\nthe input string into sections by looking for every position that appears\na simple space. In other words, this `splitScalar()` function is equivalent\nto the `split()` method in Python, or, the `std::getline()` function from C++,\nor the `strtok()` function in C.\n\nWhen you use this `splitScalar()` function, you get an iterator as the result.\nThis iterator have a `next()` method that you can use to advance the iterator\nto the next position, or, to the next section of the splitted string.\nNote that, when you use `next()`, the method not only advances the iterator,\nbut it also returns a slice to the current section of the splitted\nstring as result.\n\nNow, if you want to get a slice to the current section of the splitted\nstring, but not advance the iterator to the next position, you can use\nthe `peek()` method. Both `next()` and `peek()` methods return an optional value, that is\nwhy I use the `?` method to unwrap these optional values.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn parse_request(text: []u8) Request {\n    const line_index = std.mem.indexOfScalar(\n        u8, text, '\\n'\n    ) orelse text.len;\n    var iterator = std.mem.splitScalar(\n        u8, text[0..line_index], ' '\n    );\n    const method = try Method.init(iterator.next().?);\n    const uri = iterator.next().?;\n    const version = iterator.next().?;\n    const request = Request.init(method, uri, version);\n    return request;\n}\n```\n:::\n\n\n\n\n\nAs I described at @sec-zig-strings, strings in Zig are simply arrays of bytes in the language.\nSo, you will find lots of excellent utility functions to work directly with strings\ninside this `mem` module from the Zig Standard Library.\nWe have described some of these useful utility functions already\nat @sec-strings-useful-funs.\n\n\n\n### Using the parse request function\n\nNow that we wrote the function responsible for parsing the HTTP Request,\nwe can add the function call to `parse_request()` in\nthe `main()` function of our program.\n\nAfter that, is a good idea to test once again the state of our program.\nI execute this program again with the `run` command from the `zig` compiler,\nthen, I use my web browser to connect once again to the server through the URL `localhost:3490`, and finally,\nthe end result of our `Request` object is printed to the console.\n\nA quick observation, since I have used the `any` format specifier in the\nprint statement, the data members `version` and `uri` of the `Request`\nstruct were printed as raw integer values. String data being printed\nas integer values is common in Zig, and remember, these integer values are just the decimal representation of\nthe bytes that form the string in question.\n\nIn the result below, the sequence of decimal values 72, 84, 84, 80, 47, 49, 46, 49, and 13,\nare the bytes that form the text \"HTTP/1.1\". And the integer 47, is the decimal value of\nthe character `/`, which represents our URI in this request.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    try Request.read_request(\n        connection, buffer[0..buffer.len]\n    );\n    const request = Request.parse_request(\n        buffer[0..buffer.len]\n    );\n    try stdout.print(\"{any}\\n\", .{request});\n}\n```\n:::\n\n\n\n\n```\nrequest.Request{\n    .method = request.Method.GET,\n    .version = {72, 84, 84, 80, 47, 49, 46, 49, 13},\n    .uri = {47}\n}\n```\n\n\n\n### Sending the HTTP Response to the client\n\nIn this last part, we are going to write the logic responsible for\nsending the HTTP Response from the server to the client. To make things\nsimple, the server in this project will send just a simple web page\ncontaining the text \"Hello world\".\n\nFirst, I create a new Zig module in the project, named `response.zig`.\nIn this module, I will declare just two functions. Each function\ncorresponds to a specific status code in the HTTP Response.\nThe `send_200()` function will send a HTTP Response with status code 200\n(which means \"Success\") to the client. While the `send_404()` function sends a response\nwith status code 404 (which means \"Not found\").\n\nThis is definitely not the most ergonomic and adequate way of handling the\nHTTP Response, but it works for our case here. We are just building toy projects\nin this book after all, therefore, the source code that we write do not need to be perfect.\nIt just needs to work!\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Connection = std.net.Server.Connection;\npub fn send_200(conn: Connection) !void {\n    const message = (\n        \"HTTP/1.1 200 OK\\nContent-Length: 48\"\n        ++ \"\\nContent-Type: text/html\\n\"\n        ++ \"Connection: Closed\\n\\n<html><body>\"\n        ++ \"<h1>Hello, World!</h1></body></html>\"\n    );\n    _ = try conn.stream.write(message);\n}\n\npub fn send_404(conn: Connection) !void {\n    const message = (\n        \"HTTP/1.1 404 Not Found\\nContent-Length: 50\"\n        ++ \"\\nContent-Type: text/html\\n\"\n        ++ \"Connection: Closed\\n\\n<html><body>\"\n        ++ \"<h1>File not found!</h1></body></html>\"\n    );\n    _ = try conn.stream.write(message);\n}\n```\n:::\n\n\n\n\nNotice that both functions receives the connection object as input, and\nuse the `write()` method to write the HTTP Response message directly\ninto this communication channel. As result, the party in the other\nside of the connection (i.e. the client), will receive such message.\n\nMost real-world HTTP Servers will have a single function (or a single struct) to effectively handle\nthe response. It gets the HTTP Request already parsed as input, and then, it tries to build\nthe HTTP Response bit by bit, before the function sends it over the connection.\n\nWe would also have a specialized struct to represent a HTTP Response, and\na lot of methods that would be used to build each part or component of the response object.\nTake the `Response` struct created by the Javascript runtime Bun as an example.\nYou can find this struct in the [`response.zig` module](https://github.com/oven-sh/bun/blob/main/src/bun.js/webcore/response.zig)[^bun-resp]\nin their GitHub project.\n\n[^bun-resp]: <https://github.com/oven-sh/bun/blob/main/src/bun.js/webcore/response.zig>.\n\n\n## The end result\n\nWe can now, update once again our `main()` function to incorporate our new\nfunctions from the `response.zig` module. First, I need to import this module\ninto our `main.zig` module, then, I add the function calls to `send_200()`\nand `send_404()`.\n\nNotice that I'm using if statements to decide which \"response function\" to call,\nbased especially on the URI present in the HTTP Request. If the user asked for\na content (or a document) that is not present in our server, we should respond\nwith a 404 status code. But since we have just a simple HTTP server, with no\nreal documents to send, we can just check if the URI is the root path (`/`)\nor not to decide which function to call.\n\nAlso, notice that I'm using the function `std.mem.eql()` from the Zig Standard Library\nto check if the string from `uri` is equal or not the string `\"/\"`. We have\ndescribed this function already at @sec-strings-useful-funs, so, comeback to\nthat section if you are not familiar yet with this function.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst Response = @import(\"response.zig\");\nconst Method = Request.Method;\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    try Request.read_request(connection, buffer[0..buffer.len]);\n    const request = Request.parse_request(\n        buffer[0..buffer.len]\n    );\n    if (request.method == Method.GET) {\n        if (std.mem.eql(u8, request.uri, \"/\")) {\n            try Response.send_200(connection);\n        } else {\n            try Response.send_404(connection);\n        }\n    }\n}\n```\n:::\n\n\n\n\n\nNow that we adjusted our `main()` function, I can now execute our program, and\nsee the effects of these last changes. First, I execute the program once again, with the\n`run` command of the `zig` compiler. The program will hang, waiting for a client to connect.\n\nThen, I open my web browser, and try to connect to the server again, using the URL `localhost:3490`.\nThis time, instead of getting some sort of an error message from the browser, you will get the message\n\"Hello World\" printed into your web browser. Because this time, the server sended the HTTP Response\nsuccessfully to the web browser, as demonstrated by @fig-print-zigrun3.\n\n\n![The Hello World message sent in the HTTP Response](./../Figures/print-zigrun3.png){#fig-print-zigrun3}\n\n",
-    "supporting": [
-      "04-http-server_files"
-    ],
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/05-pointers/execute-results/html.json b/_freeze/Chapters/05-pointers/execute-results/html.json
index b67758d3..45caa69d 100644
--- a/_freeze/Chapters/05-pointers/execute-results/html.json
+++ b/_freeze/Chapters/05-pointers/execute-results/html.json
@@ -2,10 +2,8 @@
   "hash": "cdc04b429a135bfc11ee404aac1b9919",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Pointers and Optionals {#sec-pointer}\n\nOn our next project we are going to build a HTTP server from scratch.\nBut in order to do that, we need to learn more about pointers and how they work in Zig.\nPointers in Zig are similar to pointers in C. But they come with some extra advantages in Zig.\n\nA pointer is an object that contains a memory address. This memory address is the address where\na particular value is stored in memory. It can be any value. Most of the times,\nit is a value that comes from another object (or variable) present in our code.\n\nIn the example below, I'm creating two objects (`number` and `pointer`).\nThe `pointer` object contains the memory address where the value of the `number` object\n(the number 5) is stored. So, that is a pointer in a nutshell. It is a memory\naddress that points to a particular existing value in the memory. You could\nalso say, that, the `pointer` object points to the memory address where the `number` object is\nstored.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number: u8 = 5;\nconst pointer = &number;\n_ = pointer;\n```\n:::\n\n\n\n\nWe create a pointer object in Zig by using the `&` operator. When you put this operator\nbefore the name of an existing object, you get the memory address of this object as result.\nWhen you store this memory address inside a new object, this new object becomes a pointer object.\nBecause it stores a memory address.\n\nPeople mostly use pointers as an alternative way to access a particular value.\nFor example, I can use the `pointer` object to access the value stored by\nthe `number` object. This operation of accessing the value that the\npointer \"points to\" is normally called of *dereferencing the pointer*.\nWe can dereference a pointer in Zig by using the `*` method of the pointer object. Like in the example\nbelow, where we take the number 5 pointed by the `pointer` object,\nand double it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number: u8 = 5;\nconst pointer = &number;\nconst doubled = 2 * pointer.*;\nstd.debug.print(\"{d}\\n\", .{doubled});\n```\n:::\n\n\n\n\n```\n10\n```\n\nThis syntax to dereference the pointer is nice. Because we can easily chain it with\nmethods of the value pointed by the pointer. We can use the `User` struct that we have\ncreated at @sec-structs-and-oop as an example. If you comeback to that section,\nyou will see that this struct have a method named `print_name()`.\n\nSo, for example, if we have an user object, and a pointer that points to this user object,\nwe can use the pointer to access this user object, and, at the same time, call the method `print_name()`\non it, by chaining the dereference method (`*`) with the `print_name()` method. Like in the\nexample below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst u = User.init(1, \"pedro\", \"email@gmail.com\");\nconst pointer = &u;\ntry pointer.*.print_name();\n```\n:::\n\n\n\n\n```\npedro\n```\n\nWe can also use pointers to effectively alter the value of an object.\nFor example, I could use the `pointer` object to set\nthe value of the object `number` to 6, like in the example below.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n6\n```\n\n\n:::\n:::\n\n\n\n\n\nTherefore, as I mentioned earlier, people use pointers as an alternative way to access a particular value.\nAnd they use it especially when they do not want to \"move\" these values around. There are situations where,\nyou want to access a particular value in a different scope (i.e. a different location) of your code,\nbut you do not want to \"move\" this value to this new scope (or location) that you are in.\n\nThis matters especially if this value is big in size. Because if it is, then,\nmoving this value becomes an expensive operation to do.\nThe computer will have to spend a considerable amount of time\ncopying this value to this new location.\n\nTherefore, many programmers prefer to avoid this heavy operation of copying the value\nto the new location, by accessing this value through pointers.\nWe are going to talk more about this \"moving operation\" over the next sections.\nFor now, just keep in mind that avoiding this \"move operation\" is\none of main reasons why pointers are used in programming languages.\n\n\n\n\n\n## Constant objects vs variable objects {#sec-pointer-var}\n\nYou can have a pointer that points to a constant object, or, a pointer that points to a variable object.\nBut regardless of who this pointer is, a pointer **must always respect the characteristics of the object that it points to**.\nAs a consequence, if the pointer points to a constant object, then, you cannot use this pointer\nto change the value that it points to. Because it points to a value that is constant. As we discussed at @sec-assignments, you cannot\nchange a value that is constant.\n\nFor example, if I have a `number` object, which is constant, I cannot execute\nthe expression below where I'm trying to change the value of `number` to 6 through\nthe `pointer` object. As demonstrated below, when you try to do something\nlike that, you get a compile time error:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number = 5;\nconst pointer = &number;\npointer.* = 6;\n```\n:::\n\n\n\n\n```\np.zig:6:12: error: cannot assign to constant\n    pointer.* = 6;\n```\n\nIf I change the `number` object to be a variable object, by introducing the `var` keyword,\nthen, I can successfully change the value of this object through a pointer, as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n6\n```\n\n\n:::\n:::\n\n\n\n\nYou can see this relationship between \"constant versus variable\" on the data type of\nyour pointer object. In other words, the data type of a pointer object already gives you\nsome clues about whether the value that it points to is constant or not.\n\nWhen a pointer object points to a constant value, then, this pointer have a data type `*const T`,\nwhich means \"a pointer to a constant value of type `T`\".\nIn contrast, if the pointer points to a variable value, then, the type of the pointer is usually `*T`, which is\nsimply \"a pointer to a value of type `T`\".\nHence, whenever you see a pointer object whose data type is in the format `*const T`, then,\nyou know that you cannot use this pointer to change the value that it points to.\nBecause this pointer points to a constant value of type `T`.\n\n\nWe have talked about the value pointed by the pointer being constant or not,\nand the consequences that arises from it. But, what about the pointer object itself? I mean, what happens\nif the pointer object itself is constant or not? Think about it.\nWe can have a constant pointer that points to a constant value.\nBut we can also have a variable pointer that points to a constant value. And vice-versa.\n\nUntil this point, the `pointer` object was always constant,\nbut what this means for us? What is the consequence of the\n`pointer` object being constant? The consequence is that\nwe cannot change the pointer object, because it is constant. We can use the\npointer object in multiple ways, but we cannot change the\nmemory address that is inside this pointer object.\n\nHowever, if we mark the `pointer` object as a variable object,\nthen, we can change the memory address pointed by this `pointer` object.\nThe example below demonstrates that. Notice that the object pointed\nby the `pointer` object changes from `c1` to `c2`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c1: u8 = 5;\nconst c2: u8 = 6;\nvar pointer = &c1;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\npointer = &c2;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\n```\n:::\n\n\n\n\n```\n5\n6\n```\n\nThus, by setting the `pointer` object to a `var` or `const` object,\nyou specify if the memory address contained in this pointer object can change or not\nin your program. On the other side, you can change the value pointed by the pointer,\nif, and only if this value is stored in a variable object. If this value\nis in a constant object, then, you cannot change this value through a pointer.\n\n\n## Types of pointer\n\nIn Zig, there are two types of pointers [@zigdocs], which are:\n\n- single-item pointer (`*`);\n- many-item pointer (`[*]`);\n\n\nSingle-item pointer objects are objects whose data types are in the format `*T`.\nSo, for example, if an object have a data type `*u32`, it means that, this\nobject contains a single-item pointer that points to an unsigned 32-bit integer value.\nAs another example, if an object have type `*User`, then, it contains\na single-item pointer to an `User` value.\n\nIn contrast, many-item pointers are objects whose data types are in the format `[*]T`.\nNotice that the star symbol (`*`) is now inside a pair of brackets (`[]`). If the star\nsymbol is inside a pair of brackets, you know that this object is a many-item pointer.\n\nWhen you apply the `&` operator over an object, you will always get a single-item pointer.\nMany-item pointers are more of a \"internal type\" of the language, more closely\nrelated to slices. So, when you deliberately create a pointer with the `&` operator,\nyou always get a single-item pointer as result.\n\n\n\n## Pointer arithmetic\n\nPointer arithmetic is available in Zig, and they work the same way they work in C.\nWhen you have a pointer that points to an array, the pointer usually points to\nthe first element in the array, and you can use pointer arithmetic to\nadvance this pointer and access the other elements in the array.\n\n\nNotice in the example below, that initially, the `ptr` object was pointing\nto the first element in the array `ar`. But then, I started to walk through the array, by advancing\nthe pointer with simple pointer arithmetic.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [_]i32{1,2,3,4};\nvar ptr = &ar;\ntry stdout.print(\"{d}\\n\", .{ptr.*});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr.*});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr.*});\n```\n:::\n\n\n\n\n```\n1\n2\n3\n```\n\nAlthough you can create a pointer to an array like that, and\nstart to walk through this array by using pointer arithmetic,\nin Zig, we prefer to use slices, which were presented at @sec-arrays.\n\nBehind the hood, slices already are pointers,\nand they also come with the `len` property, which indicates\nhow many elements are in the slice. This is good because the `zig` compiler\ncan use it to check for potential buffer overflows, and other problems like that.\n\nAlso, you don't need to use pointer arithmetic to walk through the elements\nof a slice. You can simply use the `slice[index]` syntax to directly access\nany element you want in the slice.\nAs I mentioned at @sec-arrays, you can get a slice from an array by using\na range selector inside brackets. In the example below, I'm creating\na slice (`sl`) that covers the entire `ar` array. I can access any\nelement of `ar` from this slice, and, the slice itself already is a pointer\nbehind the hood.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [_]i32{1,2,3,4};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\n\n## Optionals and Optional Pointers\n\nLet's talk about optionals and how they relate to pointers in Zig.\nBy default, objects in Zig are **non-nullable**. This means that, in Zig,\nyou can safely assume that any object in your source code is not null.\n\nThis is a powerful feature of Zig when you compare it to the developer experience in C.\nBecause in C, any object can be null at any point, and, as consequence, a pointer in C\nmight point to a null value. This is a common source of undefined behaviour in C.\nWhen programmers work with pointers in C, they have to constantly check if\ntheir pointers are pointing to null values or not.\n\nIf for some reason, your Zig code produces a null value somewhere, and, this null\nvalue ends up in an object that is non-nullable, a runtime error is always\nraised by your Zig program. Take the program below as an example.\nThe `zig` compiler can see the `null` value at compile time, and, as result,\nit raises a compile time error. But, if a `null` value is raised during\nruntime, a runtime error is also raised by the Zig program, with a\n\"attempt to use null value\" message.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nnumber = null;\n```\n:::\n\n\n\n```\np5.zig:5:14: error: expected type 'u8',\n        found '@TypeOf(null)'\n    number = null;\n             ^~~~\n```\n\n\nYou don't get this type of safety in C.\nIn C, you don't get warnings or errors about null values being produced in your program.\nIf for some reason, your code produces a null value in C, most of the times, you end up getting a segmentation fault error\nas result, which can mean many things.\nThat is why programmers have to constantly check for null values in C.\n\nPointers in Zig are also, by default, **non-nullable**. This is another amazing\nfeature in Zig. So, you can safely assume that any pointer that you create in\nyour Zig code is pointing to a non-null value.\nTherefore, you don't have this heavy work of checking if the pointers you create\nin Zig are pointing to a null value.\n\n\n### What are optionals?\n\nOk, we know now that all objects are non-nullable by default in Zig.\nBut what if we actually need to use an object that might receive a null value?\nHere is where optionals come in.\n\nAn optional object in Zig is an object that can be null.\nTo mark an object as optional, we use the `?` operator. When you put\nthis `?` operator right before the data type of an object, you transform\nthis data type into an optional data type, and the object becomes an optional object.\n\nTake the snippet below as an example. We are creating a new variable object\ncalled `num`. This object have the data type `?i32`, which means that,\nthis object contains either a signed 32-bit integer (`i32`), or, a null value.\nBoth alternatives are valid values to the `num` object.\nThat is why, I can actually change the value of this object to null, and,\nno errors are raised by the `zig` compiler, as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: ?i32 = 5;\nnum = null;\n```\n:::\n\n\n\n\n### Optional pointers\n\nYou can also mark a pointer object as an optional pointer, meaning that,\nthis object contains either a null value, or, a pointer that points to a value.\nWhen you mark a pointer as optional, the data type of this pointer object\nbecomes `?*const T` or `?*T`, depending if the value pointed by the pointer\nis a constant value or not. The `?` identifies the object as optional, while\nthe `*` identifies it as a pointer object.\n\nIn the example below, we are creating a variable object named `num`, and an\noptional pointer object named `ptr`. Notice that the data type of the object\n`ptr` indicates that it is either a null value, or a pointer to an `i32` value.\nAlso, notice that the pointer object (`ptr`) can be marked as optional, even if\nthe object `num` is not optional.\n\nWhat this code tells us is that, the `num` variable will never contain a null value.\nThis variable will always contain a valid `i32` value. But in contrast, the `ptr` object might contain either a null\nvalue, or, a pointer to an `i32` value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: i32 = 5;\nvar ptr: ?*i32 = &num;\nptr = null;\nnum = 6;\n```\n:::\n\n\n\n\nBut what happens if we turn the table, and mark the `num` object as optional,\ninstead of the pointer object. If we do that, then, the pointer object is\nnot optional anymore. It would be a similar (although different) result. Because then, we would have\na pointer to an optional value. In other words, a pointer to a value that is either a\nnull value, or, a not-null value.\n\nIn the example below, we are recreating this idea. Now, the `ptr` object\nhave a data type of `*?i32`, instead of `?*i32`. Notice that the `*` symbol comes before of `?`\nthis time. So now, we have a pointer that points to a value that is either null\n, or, a signed 32-bit integer.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: ?i32 = 5;\n// ptr have type `*?i32`, instead of `?*i32`.\nconst ptr = &num;\n_ = ptr;\n```\n:::\n\n\n\n\n\n### Null handling in optionals {#sec-null-handling}\n\nWhen you have an optional object in your Zig code, you have to explicitly handle\nthe possibility of this object being null. It is like error-handling with `try` and `catch`.\nIn Zig you also have to handle null values like if they were a type of error.\n\nWe can do that, by using either:\n\n- an if statement, like you would do in C.\n- the `orelse` keyword.\n- unwrap the optional value with the `?` method.\n\nWhen you use an if statement, you use a pair of pipes\nto unwrap the optional value, and use this \"unwrapped object\"\ninside the if block.\nUsing the example below as a reference, if the object `num` is null,\nthen, the code inside the if statement is not executed. Otherwise,\nthe if statement will unwrap the object `num` into the `not_null_num`\nobject. This `not_null_num` object is guaranteed to be not null inside\nthe scope of the if statement.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst num: ?i32 = 5;\nif (num) |not_null_num| {\n    try stdout.print(\"{d}\\n\", .{not_null_num});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n5\n```\n\n\n:::\n:::\n\n\n\n\nNow, the `orelse` keyword behaves like a binary operator. You connect two expressions with this keyword.\nOn the left side of `orelse`, you provide the expression that might result\nin a null value, and on the right side of `orelse`, you provide another expression\nthat will not result in a null value.\n\nThe idea behind the `orelse` keyword is: if the expression on the left side\nresult in a not-null value, then, this not-null value is used. However,\nif this expression on the left side result in a null value, then, the value\nof the expression on the right side is used instead.\n\nLooking at the example below, since the `x` object is currently null, the\n`orelse` decided to use the alternative value, which is the number 15.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x: ?i32 = null;\nconst dbl = (x orelse 15) * 2;\ntry stdout.print(\"{d}\\n\", .{dbl});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n30\n```\n\n\n:::\n:::\n\n\n\n\nYou can use the if statement or the `orelse` keyword, when you want to\nsolve (or deal with) this null value. However, if there is no clear solution\nto this null value, and the most logic and sane path is to simply panic\nand raise a loud error in your program when this null value is encountered,\nyou can use the `?` method of your optional object.\n\nIn essence, when you use this `?` method, the optional object is unwrapped.\nIf a not-null value is found in the optional object, then, this not-null value is used.\nOtherwise, the `unreachable` keyword is used. You can read more about this\n[`unreacheable` keyword at the official documentation](https://ziglang.org/documentation/master/#unreachable)[^un-docs].\nBut in essence, when you build your Zig source code using the build modes `ReleaseSafe` or `Debug`, this\n`unreacheable` keyword causes the program to panic and raise an error during runtime,\nlike in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn return_null(n: i32) ?i32 {\n    if (n == 5) return null;\n    return n;\n}\n\npub fn main() !void {\n    const x: i32 = 5;\n    const y: ?i32 = return_null(x);\n    try stdout.print(\"{d}\\n\", .{y.?});\n}\n```\n:::\n\n\n\n\n```\nthread 12767 panic: attempt to use null value\np7.zig:12:34: 0x103419d in main (p7):\n    try stdout.print(\"{d}\\n\", .{y.?});\n                                 ^\n```\n\n\n[^un-docs]: <https://ziglang.org/documentation/master/#unreachable>.\n\n\n",
-    "supporting": [
-      "05-pointers_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Pointers and Optionals {#sec-pointer}\n\nOn our next project we are going to build a HTTP server from scratch.\nBut in order to do that, we need to learn more about pointers and how they work in Zig.\nPointers in Zig are similar to pointers in C. But they come with some extra advantages in Zig.\n\nA pointer is an object that contains a memory address. This memory address is the address where\na particular value is stored in memory. It can be any value. Most of the times,\nit is a value that comes from another object (or variable) present in our code.\n\nIn the example below, I'm creating two objects (`number` and `pointer`).\nThe `pointer` object contains the memory address where the value of the `number` object\n(the number 5) is stored. So, that is a pointer in a nutshell. It is a memory\naddress that points to a particular existing value in the memory. You could\nalso say, that, the `pointer` object points to the memory address where the `number` object is\nstored.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number: u8 = 5;\nconst pointer = &number;\n_ = pointer;\n```\n:::\n\n\n\n\nWe create a pointer object in Zig by using the `&` operator. When you put this operator\nbefore the name of an existing object, you get the memory address of this object as result.\nWhen you store this memory address inside a new object, this new object becomes a pointer object.\nBecause it stores a memory address.\n\nPeople mostly use pointers as an alternative way to access a particular value.\nFor example, I can use the `pointer` object to access the value stored by\nthe `number` object. This operation of accessing the value that the\npointer \"points to\" is normally called of *dereferencing the pointer*.\nWe can dereference a pointer in Zig by using the `*` method of the pointer object. Like in the example\nbelow, where we take the number 5 pointed by the `pointer` object,\nand double it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number: u8 = 5;\nconst pointer = &number;\nconst doubled = 2 * pointer.*;\nstd.debug.print(\"{d}\\n\", .{doubled});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n10\n```\n\n\n:::\n:::\n\n\n\n\n```\n10\n```\n\nThis syntax to dereference the pointer is nice. Because we can easily chain it with\nmethods of the value pointed by the pointer. We can use the `User` struct that we have\ncreated at @sec-structs-and-oop as an example. If you comeback to that section,\nyou will see that this struct have a method named `print_name()`.\n\nSo, for example, if we have an user object, and a pointer that points to this user object,\nwe can use the pointer to access this user object, and, at the same time, call the method `print_name()`\non it, by chaining the dereference method (`*`) with the `print_name()` method. Like in the\nexample below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst u = User.init(1, \"pedro\", \"email@gmail.com\");\nconst pointer = &u;\ntry pointer.*.print_name();\n```\n:::\n\n\n\n\n```\npedro\n```\n\nWe can also use pointers to effectively alter the value of an object.\nFor example, I could use the `pointer` object to set\nthe value of the object `number` to 6, like in the example below.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n6\n```\n\n\n:::\n:::\n\n\n\n\n\nTherefore, as I mentioned earlier, people use pointers as an alternative way to access a particular value.\nAnd they use it especially when they do not want to \"move\" these values around. There are situations where,\nyou want to access a particular value in a different scope (i.e. a different location) of your code,\nbut you do not want to \"move\" this value to this new scope (or location) that you are in.\n\nThis matters especially if this value is big in size. Because if it is, then,\nmoving this value becomes an expensive operation to do.\nThe computer will have to spend a considerable amount of time\ncopying this value to this new location.\n\nTherefore, many programmers prefer to avoid this heavy operation of copying the value\nto the new location, by accessing this value through pointers.\nWe are going to talk more about this \"moving operation\" over the next sections.\nFor now, just keep in mind that avoiding this \"move operation\" is\none of main reasons why pointers are used in programming languages.\n\n\n\n\n\n## Constant objects vs variable objects {#sec-pointer-var}\n\nYou can have a pointer that points to a constant object, or, a pointer that points to a variable object.\nBut regardless of who this pointer is, a pointer **must always respect the characteristics of the object that it points to**.\nAs a consequence, if the pointer points to a constant object, then, you cannot use this pointer\nto change the value that it points to. Because it points to a value that is constant. As we discussed at @sec-assignments, you cannot\nchange a value that is constant.\n\nFor example, if I have a `number` object, which is constant, I cannot execute\nthe expression below where I'm trying to change the value of `number` to 6 through\nthe `pointer` object. As demonstrated below, when you try to do something\nlike that, you get a compile time error:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number = 5;\nconst pointer = &number;\npointer.* = 6;\n```\n:::\n\n\n\n\n```\np.zig:6:12: error: cannot assign to constant\n    pointer.* = 6;\n```\n\nIf I change the `number` object to be a variable object, by introducing the `var` keyword,\nthen, I can successfully change the value of this object through a pointer, as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n6\n```\n\n\n:::\n:::\n\n\n\n\nYou can see this relationship between \"constant versus variable\" on the data type of\nyour pointer object. In other words, the data type of a pointer object already gives you\nsome clues about whether the value that it points to is constant or not.\n\nWhen a pointer object points to a constant value, then, this pointer have a data type `*const T`,\nwhich means \"a pointer to a constant value of type `T`\".\nIn contrast, if the pointer points to a variable value, then, the type of the pointer is usually `*T`, which is\nsimply \"a pointer to a value of type `T`\".\nHence, whenever you see a pointer object whose data type is in the format `*const T`, then,\nyou know that you cannot use this pointer to change the value that it points to.\nBecause this pointer points to a constant value of type `T`.\n\n\nWe have talked about the value pointed by the pointer being constant or not,\nand the consequences that arises from it. But, what about the pointer object itself? I mean, what happens\nif the pointer object itself is constant or not? Think about it.\nWe can have a constant pointer that points to a constant value.\nBut we can also have a variable pointer that points to a constant value. And vice-versa.\n\nUntil this point, the `pointer` object was always constant,\nbut what this means for us? What is the consequence of the\n`pointer` object being constant? The consequence is that\nwe cannot change the pointer object, because it is constant. We can use the\npointer object in multiple ways, but we cannot change the\nmemory address that is inside this pointer object.\n\nHowever, if we mark the `pointer` object as a variable object,\nthen, we can change the memory address pointed by this `pointer` object.\nThe example below demonstrates that. Notice that the object pointed\nby the `pointer` object changes from `c1` to `c2`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c1: u8 = 5;\nconst c2: u8 = 6;\nvar pointer = &c1;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\npointer = &c2;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\n```\n:::\n\n\n\n\n```\n5\n6\n```\n\nThus, by setting the `pointer` object to a `var` or `const` object,\nyou specify if the memory address contained in this pointer object can change or not\nin your program. On the other side, you can change the value pointed by the pointer,\nif, and only if this value is stored in a variable object. If this value\nis in a constant object, then, you cannot change this value through a pointer.\n\n\n## Types of pointer\n\nIn Zig, there are two types of pointers [@zigdocs], which are:\n\n- single-item pointer (`*`);\n- many-item pointer (`[*]`);\n\n\nSingle-item pointer objects are objects whose data types are in the format `*T`.\nSo, for example, if an object have a data type `*u32`, it means that, this\nobject contains a single-item pointer that points to an unsigned 32-bit integer value.\nAs another example, if an object have type `*User`, then, it contains\na single-item pointer to an `User` value.\n\nIn contrast, many-item pointers are objects whose data types are in the format `[*]T`.\nNotice that the star symbol (`*`) is now inside a pair of brackets (`[]`). If the star\nsymbol is inside a pair of brackets, you know that this object is a many-item pointer.\n\nWhen you apply the `&` operator over an object, you will always get a single-item pointer.\nMany-item pointers are more of a \"internal type\" of the language, more closely\nrelated to slices. So, when you deliberately create a pointer with the `&` operator,\nyou always get a single-item pointer as result.\n\n\n\n## Pointer arithmetic\n\nPointer arithmetic is available in Zig, and they work the same way they work in C.\nWhen you have a pointer that points to an array, the pointer usually points to\nthe first element in the array, and you can use pointer arithmetic to\nadvance this pointer and access the other elements in the array.\n\n\nNotice in the example below, that initially, the `ptr` object was pointing\nto the first element in the array `ar`. But then, I started to walk through the array, by advancing\nthe pointer with simple pointer arithmetic.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [_]i32{1,2,3,4};\nvar ptr = &ar;\ntry stdout.print(\"{d}\\n\", .{ptr.*});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr.*});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr.*});\n```\n:::\n\n\n\n\n```\n1\n2\n3\n```\n\nAlthough you can create a pointer to an array like that, and\nstart to walk through this array by using pointer arithmetic,\nin Zig, we prefer to use slices, which were presented at @sec-arrays.\n\nBehind the hood, slices already are pointers,\nand they also come with the `len` property, which indicates\nhow many elements are in the slice. This is good because the `zig` compiler\ncan use it to check for potential buffer overflows, and other problems like that.\n\nAlso, you don't need to use pointer arithmetic to walk through the elements\nof a slice. You can simply use the `slice[index]` syntax to directly access\nany element you want in the slice.\nAs I mentioned at @sec-arrays, you can get a slice from an array by using\na range selector inside brackets. In the example below, I'm creating\na slice (`sl`) that covers the entire `ar` array. I can access any\nelement of `ar` from this slice, and, the slice itself already is a pointer\nbehind the hood.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [_]i32{1,2,3,4};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\n\n## Optionals and Optional Pointers\n\nLet's talk about optionals and how they relate to pointers in Zig.\nBy default, objects in Zig are **non-nullable**. This means that, in Zig,\nyou can safely assume that any object in your source code is not null.\n\nThis is a powerful feature of Zig when you compare it to the developer experience in C.\nBecause in C, any object can be null at any point, and, as consequence, a pointer in C\nmight point to a null value. This is a common source of undefined behaviour in C.\nWhen programmers work with pointers in C, they have to constantly check if\ntheir pointers are pointing to null values or not.\n\nIf for some reason, your Zig code produces a null value somewhere, and, this null\nvalue ends up in an object that is non-nullable, a runtime error is always\nraised by your Zig program. Take the program below as an example.\nThe `zig` compiler can see the `null` value at compile time, and, as result,\nit raises a compile time error. But, if a `null` value is raised during\nruntime, a runtime error is also raised by the Zig program, with a\n\"attempt to use null value\" message.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nnumber = null;\n```\n:::\n\n\n\n```\np5.zig:5:14: error: expected type 'u8',\n        found '@TypeOf(null)'\n    number = null;\n             ^~~~\n```\n\n\nYou don't get this type of safety in C.\nIn C, you don't get warnings or errors about null values being produced in your program.\nIf for some reason, your code produces a null value in C, most of the times, you end up getting a segmentation fault error\nas result, which can mean many things.\nThat is why programmers have to constantly check for null values in C.\n\nPointers in Zig are also, by default, **non-nullable**. This is another amazing\nfeature in Zig. So, you can safely assume that any pointer that you create in\nyour Zig code is pointing to a non-null value.\nTherefore, you don't have this heavy work of checking if the pointers you create\nin Zig are pointing to a null value.\n\n\n### What are optionals?\n\nOk, we know now that all objects are non-nullable by default in Zig.\nBut what if we actually need to use an object that might receive a null value?\nHere is where optionals come in.\n\nAn optional object in Zig is an object that can be null.\nTo mark an object as optional, we use the `?` operator. When you put\nthis `?` operator right before the data type of an object, you transform\nthis data type into an optional data type, and the object becomes an optional object.\n\nTake the snippet below as an example. We are creating a new variable object\ncalled `num`. This object have the data type `?i32`, which means that,\nthis object contains either a signed 32-bit integer (`i32`), or, a null value.\nBoth alternatives are valid values to the `num` object.\nThat is why, I can actually change the value of this object to null, and,\nno errors are raised by the `zig` compiler, as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: ?i32 = 5;\nnum = null;\n```\n:::\n\n\n\n\n### Optional pointers\n\nYou can also mark a pointer object as an optional pointer, meaning that,\nthis object contains either a null value, or, a pointer that points to a value.\nWhen you mark a pointer as optional, the data type of this pointer object\nbecomes `?*const T` or `?*T`, depending if the value pointed by the pointer\nis a constant value or not. The `?` identifies the object as optional, while\nthe `*` identifies it as a pointer object.\n\nIn the example below, we are creating a variable object named `num`, and an\noptional pointer object named `ptr`. Notice that the data type of the object\n`ptr` indicates that it is either a null value, or a pointer to an `i32` value.\nAlso, notice that the pointer object (`ptr`) can be marked as optional, even if\nthe object `num` is not optional.\n\nWhat this code tells us is that, the `num` variable will never contain a null value.\nThis variable will always contain a valid `i32` value. But in contrast, the `ptr` object might contain either a null\nvalue, or, a pointer to an `i32` value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: i32 = 5;\nvar ptr: ?*i32 = &num;\nptr = null;\nnum = 6;\n```\n:::\n\n\n\n\nBut what happens if we turn the table, and mark the `num` object as optional,\ninstead of the pointer object. If we do that, then, the pointer object is\nnot optional anymore. It would be a similar (although different) result. Because then, we would have\na pointer to an optional value. In other words, a pointer to a value that is either a\nnull value, or, a not-null value.\n\nIn the example below, we are recreating this idea. Now, the `ptr` object\nhave a data type of `*?i32`, instead of `?*i32`. Notice that the `*` symbol comes before of `?`\nthis time. So now, we have a pointer that points to a value that is either null\n, or, a signed 32-bit integer.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: ?i32 = 5;\n// ptr have type `*?i32`, instead of `?*i32`.\nconst ptr = &num;\n_ = ptr;\n```\n:::\n\n\n\n\n\n### Null handling in optionals {#sec-null-handling}\n\nWhen you have an optional object in your Zig code, you have to explicitly handle\nthe possibility of this object being null. It is like error-handling with `try` and `catch`.\nIn Zig you also have to handle null values like if they were a type of error.\n\nWe can do that, by using either:\n\n- an if statement, like you would do in C.\n- the `orelse` keyword.\n- unwrap the optional value with the `?` method.\n\nWhen you use an if statement, you use a pair of pipes\nto unwrap the optional value, and use this \"unwrapped object\"\ninside the if block.\nUsing the example below as a reference, if the object `num` is null,\nthen, the code inside the if statement is not executed. Otherwise,\nthe if statement will unwrap the object `num` into the `not_null_num`\nobject. This `not_null_num` object is guaranteed to be not null inside\nthe scope of the if statement.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst num: ?i32 = 5;\nif (num) |not_null_num| {\n    try stdout.print(\"{d}\\n\", .{not_null_num});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n5\n```\n\n\n:::\n:::\n\n\n\n\nNow, the `orelse` keyword behaves like a binary operator. You connect two expressions with this keyword.\nOn the left side of `orelse`, you provide the expression that might result\nin a null value, and on the right side of `orelse`, you provide another expression\nthat will not result in a null value.\n\nThe idea behind the `orelse` keyword is: if the expression on the left side\nresult in a not-null value, then, this not-null value is used. However,\nif this expression on the left side result in a null value, then, the value\nof the expression on the right side is used instead.\n\nLooking at the example below, since the `x` object is currently null, the\n`orelse` decided to use the alternative value, which is the number 15.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x: ?i32 = null;\nconst dbl = (x orelse 15) * 2;\ntry stdout.print(\"{d}\\n\", .{dbl});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n30\n```\n\n\n:::\n:::\n\n\n\n\nYou can use the if statement or the `orelse` keyword, when you want to\nsolve (or deal with) this null value. However, if there is no clear solution\nto this null value, and the most logic and sane path is to simply panic\nand raise a loud error in your program when this null value is encountered,\nyou can use the `?` method of your optional object.\n\nIn essence, when you use this `?` method, the optional object is unwrapped.\nIf a not-null value is found in the optional object, then, this not-null value is used.\nOtherwise, the `unreachable` keyword is used. You can read more about this\n[`unreacheable` keyword at the official documentation](https://ziglang.org/documentation/master/#unreachable)[^un-docs].\nBut in essence, when you build your Zig source code using the build modes `ReleaseSafe` or `Debug`, this\n`unreacheable` keyword causes the program to panic and raise an error during runtime,\nlike in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn return_null(n: i32) ?i32 {\n    if (n == 5) return null;\n    return n;\n}\n\npub fn main() !void {\n    const x: i32 = 5;\n    const y: ?i32 = return_null(x);\n    try stdout.print(\"{d}\\n\", .{y.?});\n}\n```\n:::\n\n\n\n\n```\nthread 12767 panic: attempt to use null value\np7.zig:12:34: 0x103419d in main (p7):\n    try stdout.print(\"{d}\\n\", .{y.?});\n                                 ^\n```\n\n\n[^un-docs]: <https://ziglang.org/documentation/master/#unreachable>.\n\n\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/07-build-system/execute-results/html.json b/_freeze/Chapters/07-build-system/execute-results/html.json
index cf292412..c55ec51f 100644
--- a/_freeze/Chapters/07-build-system/execute-results/html.json
+++ b/_freeze/Chapters/07-build-system/execute-results/html.json
@@ -3,9 +3,7 @@
   "result": {
     "engine": "knitr",
     "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Build System {#sec-build-system}\n\n\nIn this chapter, we are going to talk about the build system, and how an entire project\nis built in Zig.\nOne key advantage of Zig is that it includes a build system embedded in the language itself.\nThis is great, because then you do not have to depend on an external system, separated\nfrom the compiler, to build your code.\n\n\nYou can find a good description of Zig's build system\non the [article entitled \"Build System\"](https://ziglang.org/learn/build-system/#user-provided-options)[^zig-art1]\nfrom the official Zig's website.\nWe also have the excellent [series of posts written by Felix](https://zig.news/xq/zig-build-explained-part-1-59lf)[^felix].\nHence, this chapter represents an extra resource for you to consult and rely on.\n\n[^felix]: <https://zig.news/xq/zig-build-explained-part-1-59lf>\n[^zig-art1]: <https://ziglang.org/learn/build-system/#user-provided-options>\n\nBuilding code is one of the things that Zig is best at. One thing that is particularly\ndifficult in C/C++ and even in Rust, is to cross-compile source code to multiple targets\n(e.g. multiple computer architectures and operational systems),\nand the `zig` compiler is known for being one of the best existing pieces of software\nfor this particular task.\n\n\n\n\n## How source code is built?\n\nWe already have talked about the challenges of building source code in low-level languages\nat @sec-project-files. As we described at that section, programmers invented Build Systems\nto surpass these challenges on the process of building source code in low-level languages.\n\nLow-level languages uses a compiler to compile (or to build) your source code into binary instructions.\nIn C and C++, we normally use compilers like `gcc`, `g++` or `clang` to compile\nour C and C++ source code into these instructions.\nEvery language have its own compiler, and this is no different in Zig.\n\nIn Zig, we have the `zig` compiler to compile our Zig source code into\nbinary instructions that can be executed by our computer.\nIn Zig, the compilation (or the build) process involves\nthe following components:\n\n- The Zig modules that contains your source code;\n- Library files (either a dynamic library or a static library);\n- Compiler flags that tailors the build process to your needs.\n\nThese are the things that you need to connect together in order to build your\nsource code in Zig. In C and C++, you would have an extra component, which are the header files of\nthe libraries that you are using. But header files do not exist in Zig, so, you only need\nto care about them if you are linking your Zig source code with a C library.\nIf that is not your case, you can forget about it.\n\nYour build process is usually organized in a build script. In Zig, we normally\nwrite this build script into a Zig module in the root directory of our project,\nnamed as `build.zig`. You write this build script, then, when you run it, your project\nget's built into binary files that you can use and distribute to your users.\n\nThis build script is normally organized around *target objects*. A target is simply\nsomething to be built, or, in other words, it's something that you want the `zig` compiler\nto build for you. This concept of \"targets\" is present in most Build Systems,\nespecially in CMake[^cmake].\n\n[^cmake]: <https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html>\n\nThere are four types of target objects that you can build in Zig, which are:\n\n- An executable (e.g. a `.exe` file on Windows).\n- A shared library (e.g. a `.so` file in Linux or a `.dll` file on Windows).\n- A static library (e.g. a `.a` file in Linux or a `.lib` file on Windows).\n- An executable file that executes only unit tests (or, a \"unit tests executable\").\n\nWe are going to talk more about these target objects at @sec-targets.\n\n\n\n## The `build()` function {#sec-build-fun}\n\nA build script in Zig always contains a public (and top-level) `build()` function declared.\nIt is like the `main()` function on the main Zig module of your project, that we discussed at @sec-main-file.\nBut instead of creating the entrypoint to your code, this `build()` function is the entrypoint to the build process.\n\nThis `build()` function should accept a pointer to a `Build` object as input, and it should use this \"build object\" to perform\nthe necessary steps to build your project. The return type of this function is always `void`,\nand this `Build` struct comes directly from the Zig Standard Library (`std.Build`). So, you can \naccess this struct by just importing the Zig Standard Library into your `build.zig` module.\n\nJust as a very simple example, here you can see the source code necessary to build\nan executable file from the `hello.zig` Zig module.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"hello.zig\"),\n        .target = b.host,\n    });\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\nYou can define and use other functions and objects in this build script. You can also import\nother Zig modules as you would normally do in any other module of your project.\nThe only real requirement for this build script, is to have a public and top-level\n`build()` function defined, that accepts a pointer to a `Build` struct as input.\n\n\n## Target objects {#sec-targets}\n\nAs we described over the previous sections, a build script is composed around target objects.\nEach target object is normally a binary file (or an output) that you want to get from the build process. You can list\nmultiple target objects in your build script, so that the build process generates multiple\nbinary files for you at once.\n\nFor example, maybe you are a developer working in a cross-platform application,\nand, because this application is cross-platform, you probably need to release\nbinary files of your software for each OS supported by your application to your end users.\nThus, you can define a different target object in your build script\nfor each OS (Windows, Linux, etc.) where you want to publish your software.\nThis will make the `zig` compiler to build your project to multiple target OS's at once.\nThe Zig Build System official documentation have a [great code example that demonstrates this strategy](https://ziglang.org/learn/build-system/#handy-examples)[^zig-ex].\n\n[^zig-ex]: <https://ziglang.org/learn/build-system/#handy-examples>\n\n\nA target object is created by the following methods of the `Build` struct that we introduced\nat @sec-build-fun:\n\n- `addExecutable()` creates an executable file;\n- `addSharedLibrary()` creates a shared library file;\n- `addStaticLibrary()` creates a static library file;\n- `addTest()` creates an executable file that executes unit tests.\n\n\nThese functions are methods from the `Build` struct that you receive\nas input of the `build()` function. All of them, create as output\na `Compile` object, which represents a target object to be compiled\nby the `zig` compiler. All of these functions accept a similar struct literal as input.\nThis struct literal defines three essential specs about this target object that you are building:\n`name`, `target` and `root_source_file`.\n\nWe have already seen these three options being used on the previous example,\nwhere we used the `addExecutable()` method to create an executable target object.\nThis example is reproduced below. Notice the use of the `path()` method\nfrom the `Build` struct, to define a path in the `root_source_file` option.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nexe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n```\n:::\n\n\n\n\nThe `name` option specify the name that you want to give to the binary file defined\nby this target object. So, in this example, we are building an executable file named `hello`.\nIs common to set this `name` option to the name of your project.\n\n\nFurthermore, the `target` option specify the target computer architecture (or the target operational system) of this\nbinary file. For example, if you want this target object to run on a Windows machine\nthat uses a `x86_64` architecture, you can set this `target` option to `x86_64-windows-gnu` for example.\nThis will make the `zig` compiler to compile the project to run on a `x86_64` Windows machine.\nYou can see the full list of architectures and OS's that the `zig` compiler supports by running\nthe `zig targets` command in the terminal.\n\nNow, if you are building the project to run on the current machine\nthat you are using to run this build script, you can set this `target`\noption to the `host` method of the `Build` object, like we did in the example above.\nThis `host` method identifies the current machine where you are\ncurrently running the `zig` compiler.\n\n\nAt last, the `root_source_file` option specifies the root Zig module of your project.\nThat is the Zig module that contains the entrypoint to your application (i.e. the `main()` function), or, the main API of your library.\nThis also means that, all the Zig modules that compose your project are automatically discovered\nfrom the import statements you have inside this \"root source file\".\nThe `zig` compiler can detect when a Zig module depends on the other through the import statements,\nand, as a result, it can discover the entire map of Zig modules used in your project.\n\nThis is handy, and it is different from what happens in other build systems.\nIn CMake for example, you have to explicitly list the paths to all source files that you want to\ninclude in your build process. This is probably a symptom of the \"lack of conditional\ncompilation\" in the C and C++ compilers. Since they lack this feature, you have\nto explicitly choose which source files should be sent to the C/C++ compiler, because not\nevery C/C++ code is portable or supported in every operational system, and, therefore,\nwould cause a compilation error in the C/C++ compiler.\n\n\nNow, one important detail about the build process is that, you have to **explicitly\ninstall the target objects that you create in your build script**, by using the\n`installArtifact()` method of the `Build` struct.\n\nEverytime you invoke the build process of your project, by calling the `build` command\nof the `zig` compiler, a new directory named `zig-out` is created in the root\ndirectory of your project. This new directory contains the outputs of the build process,\nthat is, the binary files built from your source code.\n\nWhat the `installArtifact()` method do is to install (or copy) the built target objects\nthat you defined to this `zig-out` directory.\nThis means that, if you do not\ninstall the target objects you define in your build script, these target objects are\nessentially discarded at the end of the build process.\n\nFor example, you might be building a project that uses a third party library that is built\ntogether with the project. So, when you build your project, you would need first, to\nbuild the third party library, and then, you link it with the source code of your project.\nSo, in this case, we have two binary files that are generated in the build process (the executable file of your project, and the third party library).\nBut only one is of interest, which is the executable file of our project.\nWe can discard the binary file of the third party library, by simply not installing it\ninto this `zig-out` directory.\n\nThis `installArtifact()` method is pretty straightforward. Just remember to apply it to every\ntarget object that you want to save into the `zig-out` directory, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nexe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n## Setting the build mode\n\nWe have talked about the three essential options that are set when you create a new target object.\nBut there is also a fourth option that you can use to set the build mode of this target object,\nwhich is the `optimize` option.\nThis option is called this way, because the build modes in Zig are treated more of\nan \"optimization vs safety\" problem. So optimization plays an important role here.\nDon't worry, I'm going back to this question very soon.\n\nIn Zig, we have four build modes (which are listed below). Each one of these build modes offer\ndifferent advantages and characteristics. As we described at @sec-compile-debug-mode, the `zig` compiler\nuses the `Debug` build mode by default, when you don't explicitly choose a build mode.\n\n- `Debug`, mode that produces and includes debugging information in the output of the build process (i.e. the binary file defined by the target object);\n- `ReleaseSmall`, mode that tries to produce a binary file that is small in size;\n- `ReleaseFast`, mode that tries to optimize your code, in order to produce a binary file that is as fast as possible;\n- `ReleaseSafe`, mode that tries to make your code as safe as possible, by including safeguards when possible.\n\nSo, when you build your project, you can set the build mode of your target object to `ReleaseFast` for example, which will tell\nthe `zig` compiler to apply important optimizations in your code. This creates a binary file\nthat simply runs faster on most contexts, because it contains a more optimized version of your code.\nHowever, as a result, we often lose some safety features in our code.\nBecause some safety checks are removed from the final binary file,\nwhich makes your code run faster, but in a less safe manner.\n\nThis choice depends on your current priorities. If you are building a cryptography or banking system, you might\nprefer to prioritize safety in your code, so, you would choose the `ReleaseSafe` build mode, which is a little\nslower to run, but much more secure, because it includes all possible runtime safety checks in the binary file\nbuilt in the build process. In the other hand, if you are writing a game for example, you might prefer to prioritize performance\nover safety, by using the `ReleaseFast` build mode, so that your users can experience faster frame rates in your game.\n\nIn the example below, we are creating the same target object that we have used on previous examples.\nBut this time, we are specifying the build mode of this target object to the `ReleaseSafe` mode.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .optimize = .ReleaseSafe\n});\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n## Setting the version of your build\n\nEverytime you build a target object in your build script, you can assign a version\nnumber to this specific build, following a semantic versioning framework.\nYou can find more about semantic versioning by visiting the [Semantic Versioning website](https://semver.org/)[^semver].\nAnyway, in Zig, you can specify the version of your build, by providing a `SemanticVersion` struct to\nthe `version` option, like in the example below:\n\n\n[^semver]: <https://semver.org/>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .version = .{\n        .major = 2, .minor = 9, .patch = 7\n    }\n});\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n## Detecting the OS in your build script {#sec-detect-os}\n\nIs very common in Build Systems to use different options, or, to include different modules, or,\nto link against different libraries depending on the Operational System (OS)\nthat you are targeting in the build process.\n\nIn Zig, you can detect the target OS of the build process, by looking\nat the `os.tag` inside the `builtin` module from the Zig library.\nIn the example below, we are using an if statement to run some\narbitrary code when the target of the build process is a\nWindows system.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nif (builtin.target.os.tag == .windows) {\n    // Code that runs only when the target of\n    // the compilation process is Windows.\n}\n```\n:::\n\n\n\n\n\n## Adding a run step to your build process\n\nOne thing that is neat in Rust is that you can compile and run your\nsource code with one single command (`cargo run`) from the Rust compiler.\nWe saw at @sec-compile-run-code how can we perform a similar job in Zig, by\nbuilding and running our Zig source code through the `run` command from the `zig` compiler.\n\nBut how can we, at the same time, build and run the binary file specified by a target object in our\nbuild script?\nThe answer is by including a \"run artifact\" in our build script.\nA run artifact is created through the `addRunArtifact()` method from the `Build` struct.\nWe simply provide as input to this function the target object that describes the binary file that we\nwant to execute. As a result, this function creates a run artifact that is capable of executing\nthis binary file.\n\nIn the example below, we are defining an executable binary file named `hello`,\nand we use this `addRunArtifact()` method to create a run artifact that will execute\nthis `hello` executable file.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"src/hello.zig\"),\n    .target = b.host\n});\nb.installArtifact(exe);\nconst run_arti = b.addRunArtifact(exe);\n```\n:::\n\n\n\n\nNow that we have created this run artifact, we need to include it in\nthe build process. We do that by declaring a new step in our build\nscript to call this artifact, through the `step()` method of the `Build`\nstruct.\n\nWe can give any name we want to this step, but, for our\ncontext here, I'm going to name this step as \"run\".\nAlso, I give it a brief description to this step (\"Run the project\").\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst run_step = b.step(\n    \"run\", \"Run the project\"\n);\n```\n:::\n\n\n\n\n\nNow that we have declared this \"run step\" we need to tell Zig that\nthis \"run step\" depends on the run artifact.\nIn other words, a run artifact always depends on a \"step\" to effectively be executed.\nBy creating this dependency\nwe finally stablish the necessary commands to build and run the executable file\nfrom the build script.\n\nWe can establish a dependency between the run step and the run artifact\nby using the `dependsOn()` method from the run step. So, we first\ncreate the run step, and then, we link it with the run artifact, by\nusing this `dependsOn()` method from the run step.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nrun_step.dependOn(&run_arti.step);\n```\n:::\n\n\n\n\nThe entire source code of this specific build script that\nwe wrote, piece by piece, in this section, is\navailable in the `build_and_run.zig` module. You can\nsee this module by\n[visiting the official repository of this book](https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig)\n[^module-src].\n\n\n[^module-src]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig>\n\nWhen you declare a new step in your build script, this step\nbecomes available through the `build` command in the `zig` compiler.\nYou can actually see this step by running `zig build --help` in the terminal, like\nin the example below, where we can see that this new \"run\"\nstep that we declared in the build script appeared in the output.\n\n```bash\nzig build --help\n```\n\n```\nSteps:\n  ...\n  run   Run the project\n  ...\n```\n\nNow, everything that we need to is to\ncall this \"run\" step that we created in our build script. We\ncall it by using the name that we gave to this step\nafter the `build` command from the `zig` compiler.\nThis will cause the compiler to build our executable file\nand execute it at the same time.\n\n```bash\nzig build run\n```\n\n## Build unit tests in your project\n\nWe have talked at length about writing unit tests in Zig at @sec-unittests,\nand we also have talked about how to execute these unit tests through\nthe `test` command of the `zig` compiler. However,\nas we did with the `run` command on the previous section, we also might want to\ninclude some commands in our build script to also build and execute the unit tests in our project.\n\nSo, once again, we are going to discuss how a specific built-in command from the `zig` compiler,\n(in this case, the `test` command) can be used in a build script in Zig.\nHere is where a \"test target object\" comes into play.\nAs was described at @sec-targets, we can create a test target object by using the `addTest()` method of\nthe `Build` struct. The first thing that we need to do is to\ndeclare a test target object in our build script.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst test_exe = b.addTest(.{\n    .name = \"unit_tests\",\n    .root_source_file = b.path(\"src/main.zig\"),\n    .target = b.host,\n});\nb.installArtifact(test_exe);\n```\n:::\n\n\n\n\n\nA test target object essentially selects all `test` blocks in all Zig modules\nacross your project, and builds only the source code present inside\nthese `test` blocks in your project. As a result, this target object\ncreates an executable file that contains only the source code present\nin all of these `test` blocks (i.e. the unit tests) in your project.\n\nPerfect! Now that we have declared this test target object, an executable file\nnamed `unit_tests` is built by the `zig` compiler when we trigger the build\nscript with the `build` command. After the build\nprocess is finished, we can simply execute this `unit_tests` executable\nin the terminal.\n\nHowever, if you remember the previous section, we already learned\nhow can we create a run step in our build script, to execute an executable file\nbuilt by the build script.\n\nSo, we could simply add a run step in our build script to run these unit tests\nfrom a single command in the `zig` compiler, to make our lifes easier.\nIn the example below, we demonstrate the commands to\nregister a new build step called \"tests\" in our build script\nto run these unit tests.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst run_arti = b.addRunArtifact(test_exe);\nconst run_step = b.step(\"tests\", \"Run unit tests\");\nrun_step.dependOn(&run_arti.step);\n```\n:::\n\n\n\n\nNow that we registered this new build step, we can trigger it by calling the command below\nin the terminal. You can also checkout the complete source\ncode for this specific build script at the `build_tests.zig` module at the\n[official repository of this book](https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig)\n[^module-src2].\n\n\n[^module-src2]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig>\n\n\n```bash\nzig build tests\n```\n\n\n## Tailoring your build process with user-provided options\n\nSometimes, you want to make a build script that is customizable by the user\nof your project. You can do that by creating user-provided options in\nyour build script. We create an user-provided option by using the\n`option()` method from the `Build` struct.\n\nWith this method, we create a \"build option\" which can be passed\nto the `build.zig` script at the command line. The user have the power of setting\nthis option at the `build` command from the\n`zig` compiler. In other words, each build option that we create\nbecomes a new command line argument that is accessible through the `build` command\nof the compiler.\n\nThese \"user-provided options\" are set by using the prefix `-D` in the command line.\nFor example, if we declare an option named `use_zlib`, that receives a boolean value which\nindicates if we should link our source code to `zlib` or not, we can set the value\nof this option in the command line with `-Duse_zlib`. The code example below\ndemonstrates this idea:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const use_zlib = b.option(\n        bool,\n        \"use_zlib\",\n        \"Should link to zlib?\"\n    ) orelse false;\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"example.zig\"),\n        .target = b.host,\n    });\n    if (use_zlib) {\n        exe.linkSystemLibrary(\"zlib\");\n    }\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\n```bash\nzig build -Duse_zlib=false\n```\n\n\n## Linking to external libraries\n\n\nOne essential part of every build process is the linking stage.\nThis stage is responsible for combining the multiple object files\nthat represent your code, into a single executable file. It also links\nthis executable file to external libraries, if you use any in your code.\n\nIn Zig, we have two notions of a \"library\", which are: 1) a system's library;\n2) a local library. A system's library is just a library that already is installed\nin your system. While a local library is a library that belongs to the current\nproject. Is a library that is present in your project directory, and\nthat you are building together with your project source code.\n\nThe basic difference between the two, is that a system's library is already\nbuilt and installed in your system, supposedly, and all you need to do\nis to link your source code to this library to start using it.\nWe do that by using the `linkSystemLibrary()` method from a\n`Compile` object. This method accepts the name of the library\nin a string as input. Remember from @sec-targets that a `Compile` object\nis a target object that you declare in your build script.\n\nWhen you link a particular target object with a system's library,\nthe `zig` compiler will use `pkg-config` to find where\nare the binary files and also the header files of this library\nin your system.\nWhen it finds these files, the linker present in the `zig` compiler\nwill link your object files with the files of this library to\nproduce a single binary file for you.\n\nIn the example below, we are creating an executable file named `image_filter`,\nand, we are linking this executable file to the C Standard Library with the\nmethod `linkLibC()`, but we also are linking this executable file to the\nC library `libpng` that is currently installed in my system.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"image_filter\",\n        .root_source_file = b.path(\"src/main.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n    exe.linkLibC();\n    exe.linkSystemLibrary(\"png\");\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\nIf you are linking with a C library in your project, is generally a good idea\nto also link your code with the C Standard Library. Because is very likely\nthat this C library uses some functionality of the C Standard Library at some point.\nThe same goes to C++ libraries. So, if you are linking with\nC++ libraries, is a good idea to link your project with the C++\nStandard Library by using the `linkLibCpp()` method.\n\nOn the order side, when you want to link with a local library,\nyou should use the `linkLibrary()` method of a `Compile` object.\nThis method expects to receive another `Compile` object as input.\nThat is, another target object defined in your build script,\nusing either the `addStaticLibrary()` or `addSharedLibrary()` methods\nwhich defines a library to be built.\n\nAs we discussed earlier, a local library is a library\nthat is local to your project, and that is being built together\nwith your project. So, you need to create a target object in your build script\nto build this local library. Then, you link the target objects of interest in your project,\nwith this target object that identifies this local library.\n\nTake a look at this example extracted from the build script of the [`libxev` library](https://github.com/mitchellh/libxev/tree/main)[^libxev2].\nYou can see in this snippet that\nwe are declaring a shared library file, from the `c_api.zig`\nmodule. Then, later in the build script, we declare an\nexecutable file named `\"dynamic-binding-test\"`, which\nlinks to this shared library that we defined earlier\nin the script.\n\n[^libxev2]: <https://github.com/mitchellh/libxev/tree/main>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst optimize = b.standardOptimizeOption(.{});\nconst target = b.standardTargetOptions(.{});\n\nconst dynamic_lib = b.addSharedLibrary(.{\n    .name = dynamic_lib_name,\n    .root_source_file = b.path(\"src/c_api.zig\"),\n    .target = target,\n    .optimize = optimize,\n});\nb.installArtifact(dynamic_lib);\n// ... more lines in the script\nconst dynamic_binding_test = b.addExecutable(.{\n    .name = \"dynamic-binding-test\",\n    .target = target,\n    .optimize = optimize,\n});\ndynamic_binding_test.linkLibrary(dynamic_lib);\n```\n:::\n\n\n\n\n\n\n## Building C code {#sec-building-c-code}\n\nThe `zig` compiler comes with a C compiler embedded in it. In other words,\nyou can use the `zig` compiler to build C projects. This C compiler is available\nthrough the `cc` command of the `zig` compiler.\n\nAs an example, let's use the famous [FreeType library](https://freetype.org/)[^freetype].\nFreeType is one of the most widely used pieces of software in the world.\nIt is a C library designed to produce high-quality fonts. But it is also\nheavily used in the industry to natively render text and fonts\nin the screen of your computer.\n\nIn this section, we are going to write a build script, piece by piece, that is capable\nof building the FreeType project from source.\nYou can find the source code of this build script on the\n[`freetype-zig` repository](https://github.com/pedropark99/freetype-zig/tree/main)[^freetype-zig]\navailable at GitHub.\n\n[^freetype]: <https://freetype.org/>\n[^freetype-zig]: <https://github.com/pedropark99/freetype-zig/tree/main>\n\nAfter you download the source code of FreeType from the official website[^freetype],\nyou can start writing the `build.zig` module. We begin by defining the target object\nthat defines the binary file that we want to compile.\n\nAs an example, I will build the project as a static library file using the `addStaticLibrary()` method\nto create the target object.\nAlso, since FreeType is a C library, I will also link the library\nagainst `libc` through the `linkLibC()` method, to guarantee that any use\nof the C Standard Library is covered in the compilation process.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst target = b.standardTargetOptions(.{});\nconst opti = b.standardOptimizeOption(.{});\nconst lib = b.addStaticLibrary(.{\n    .name = \"freetype\",\n    .optimize = opti,\n    .target = target,\n});\nlib.linkLibC();\n```\n:::\n\n\n\n\n### Creating C compiler flags\n\nCompiler flags are also known as \"compiler options\" by many programmers,\nor also, as \"command options\" in the GCC official documentation.\nIt's fair to also call them as the \"command-line arguments\" of the C compiler.\nIn general, we use compiler flags to turn on (or turn off) some features from the compiler,\nor to tweak the compilation process to fit the needs of our project.\n\nIn build scripts written in Zig, we normally list the C compiler flags to be used in the compilation process\nin a simple array, like in the example below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c_flags = [_][]const u8{\n    \"-Wall\",\n    \"-Wextra\",\n    \"-Werror\",\n};\n```\n:::\n\n\n\n\nIn theory, there is nothing stopping you from using this array to add \"include paths\" (with the `-I` flag)\nor \"library paths\" (with the `-L` flag) to the compilation process. But there are formal ways in Zig to\nadd these types of paths in the compilation process. Both are discussed at @sec-include-paths\nand @sec-library-paths.\n\nAnyway, in Zig, we add C flags to the build process together with the C files that we want to compile, by using the\n`addCSourceFile()` and `addCSourceFiles()` methods. In the example above, we have just declared\nthe C flags that we want to use. But we haven't added them to the build process yet.\nTo do that, we also need to list the C files to be compiled.\n\n### Listing your C files\n\nThe C files that contains \"cross-platform\" source code are listed in the `c_source_files`\nobject below. These are the C files that are included by default in every platform\nsupported by the FreeType library. Now, since the amount of C files in the FreeType library is big,\nI have omitted the rest of the files in the code example below, for brevity purposes.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c_source_files = [_][]const u8{\n    \"src/autofit/autofit.c\",\n    \"src/base/ftbase.c\",\n    // ... and many other C files.\n};\n```\n:::\n\n\n\n\nNow, in addition to \"cross-platform\" source code, we also have some C files in the FreeType project\nthat are platform-specific, meaning that, they contain source code that can only be compiled in specific platforms,\nand, as a result, they are only included in the build process on these specific target platforms.\nThe objects that list these C files are exposed in the code example below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst windows_c_source_files = [_][]const u8{\n    \"builds/windows/ftdebug.c\",\n    \"builds/windows/ftsystem.c\"\n};\nconst linux_c_source_files = [_][]const u8{\n    \"src/base/ftsystem.c\",\n    \"src/base/ftdebug.c\"\n};\n```\n:::\n\n\n\n\nNow that we declared both the files that we want to include and the C compiler flags to be used,\nwe can add them to the target object that describes the FreeType library, by using the\n`addCSourceFile()` and `addCSourceFiles()` methods.\n\nBoth of these functions are methods from a `Compile` object (i.e. a target object).\nThe `addCSourceFile()` method is capable of adding a single C file to the target object,\nwhile the `addCSourceFiles()` method is used to add multiple C files in a single command.\nYou might prefer to use `addCSourceFile()` when you need to use different compiler flags\non specific C files in your project. But, if you can use the same compiler flags\nacross all C files, then, you will probably find `addCSourceFiles()` a better choice.\n\nNotice that we are using the `addCSourceFiles()` method in the example below,\nto add both the C files and the C compiler flags. Also notice that we\nare using the `os.tag` that we learned about at @sec-detect-os, to add the platform-specific\nC files.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nlib.addCSourceFiles(\n    &c_source_files, &c_flags\n);\n\nswitch (builtin.target.os.tag) {\n    .windows => {\n        lib.addCSourceFiles(\n            &windows_c_source_files,\n            &c_flags\n        );\n    },\n    .linux => {\n        lib.addCSourceFiles(\n            &linux_c_source_files,\n            &c_flags\n        );\n    },\n    else => {},\n}\n```\n:::\n\n\n\n\n\n### Defining C Macros\n\nC Macros are an essential part of the C programming language,\nand they are commonly defined through the `-D` flag from a C compiler.\nIn Zig, you can define a C Macro to be used in your build process\nby using the `defineCMacro()` method from the target object that\ndefines the binary file that you are building.\n\nIn the example below, we are using the `lib` object that we have defined\non the previous sections to define some C Macros used by the FreeType project\nin the compilation process. These C Macros specify if FreeType\nshould (or should not) include functionalities from different\nexternal libraries.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nlib.defineCMacro(\"FT_DISABLE_ZLIB\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_PNG\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_HARFBUZZ\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BZIP2\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BROTLI\", \"TRUE\");\nlib.defineCMacro(\"FT2_BUILD_LIBRARY\", \"TRUE\");\n```\n:::\n\n\n\n\n\n### Adding library paths {#sec-library-paths}\n\nLibrary paths are paths in your computer where the C compiler will look (or search) for\nlibrary files to link against your source code. In other words, when you use a library in your\nC source code, and you ask the C compiler to link your source code against this library,\nthe C compiler will search for the binary files of this library across the paths listed\nin this \"library paths\" set.\n\nThese paths are platform specific, and, by default, the C compiler starts by looking at a\npre-defined set of places in your computer. But you can add more paths (or more places)\nto this list. For example, you may have a library installed in a non-conventional place of your\ncomputer, and you can make the C compiler \"see\" this \"non-conventional place\" by adding this path\nto this list of pre-defined paths.\n\nIn Zig, you can add more paths to this set by using the `addLibraryPath()` method from your target object.\nFirst, you defined a `LazyPath` object, containing the path you want to add, then,\nyou provide this object as input to the `addLibraryPath()` method, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst lib_path: std.Build.LazyPath = .{\n    .cwd_relative = \"/usr/local/lib/\"\n};\nlib.addLibraryPath(lib_path);\n```\n:::\n\n\n\n\n\n\n\n### Adding include paths {#sec-include-paths}\n\nThe preprocessor search path is a popular concept from the\nC community, but it is also known by many C programmers as \"include paths\", because\nthe paths in this \"search path\" relate to the `#include` statements found in the C files.\n\nInclude paths are similar to library paths. They are a set of pre-defined places in your computer where\nthe C compiler will look for files during the compilation process. But instead of looking for\nlibrary files, the include paths are places where the compiler looks for header files included\nin your C source code.\nThis is why many C programmers prefer to call these paths as the \"preprocessor search path\".\nBecause header files are processed during the preprocessor stage of the compilation\nprocess.\n\nSo, every header file that you include in your C source code, through a `#include` statements needs to\nbe found somewhere, and the C compiler will search for this header file across the paths listed in this \"include paths\" set.\nInclude paths are added to the compilation process through the `-I` flag.\n\nIn Zig, you can add new paths to this pre-defined set of paths, by using the `addIncludePath()` method\nfrom your target object. This method also accepts a `LazyPath` object as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst inc_path: std.Build.LazyPath = .{\n    .path = \"./include\"\n};\nlib.addIncludePath(inc_path);\n```\n:::\n",
-    "supporting": [
-      "07-build-system_files"
-    ],
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/09-data-structures/execute-results/html.json b/_freeze/Chapters/09-data-structures/execute-results/html.json
index c9619737..4675c1a3 100644
--- a/_freeze/Chapters/09-data-structures/execute-results/html.json
+++ b/_freeze/Chapters/09-data-structures/execute-results/html.json
@@ -2,10 +2,8 @@
   "hash": "3788497b9fd5f45d000ca7f61478a997",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Data Structures\n\nIn this chapter, I want to present the most common Data Structures that are available from\nthe Zig Standard Library, especially `ArrayList` and also `HashMap`. These are generic Data Structures\nthat you can use to store and control any type of data that is produced by your application.\n\n## Dynamic Arrays {#sec-dynamic-array}\n\nIn high level languages, arrays are usually dynamic. They can easily grow\nin size when they have to, and you don't need to worry about it.\nIn contrast, arrays in low level languages are usually static by default.\nThis is the reality of C, C++, Rust and also Zig. Static arrays were presented at\n@sec-arrays, but in this section, we are going to talk about dynamic arrays in Zig.\n\nDynamic arrays are simply arrays that can grow in size during the runtime\nof your program. Most low level languages have some implementation of\na dynamic array in their standard library. C++ have `std::vector`, Rust have `Vec`,\nand Zig have `std.ArrayList`.\n\nThe `std.ArrayList` struct provides a contiguous and growable array for you.\nIt works like any other dynamic array, it allocates a contiguous block of memory, and when this block have no space left,\n`ArrayList` allocates another contiguous and bigger block of memory, copies the\nelements to this new location, and erases (or frees) the previous block of memory.\n\n\n### Capacity vs Length\n\nWhen we talk about dynamic arrays, we usually have two similar concepts that\nare very essential to how a dynamic array works behind the hood.\nThese concepts are *capacity* and *length*. In some contexts, especially\nin C++, *length* is also called of *size*.\n\nAlthough they look similar, these concepts represent different things\nin the context of a dynamic array. *Capacity* is the number of items (or elements)\nthat your dynamic array can currently hold without the need to allocate more memory.\n\nIn contrast, the *length* refers to how many elements in the array\nare currently being used, or, in other words, how many elements in this array\nthat you have assigned a value to. Every dynamic array works around\na block of allocated memory, which represents an array with total capacity for $n$ elements.\nHowever, only a portion of these $n$ elements are being used most of the time. This portion\nof $n$ is the *length* of the array. So every time you append a new value\nto the array, you are incrementing its *length* by one.\n\nThis means that a dynamic array usually works with an extra margin, or, an extra space\nwhich is currently empty, but it is waiting and ready to be used. This \"extra space\"\nis essentially the difference between *capacity* and *length*. *Capacity* represents\nthe total number of elements that the array can hold without the need to re-allocate\nor re-expand the array, while the *length* represents how much of this capacity\nis currently being used to hold/store values.\n\n@fig-capacity-length presents this idea visually. Notice that, at first,\nthe capacity of the array is greater than the length of the array.\nSo, the dynamic array have extra space that is currently empty, but it\nis ready to receive a value to be stored.\n\n![Difference between capacity and length in a dynamic array](./../Figures/dynamic-array.png){#fig-capacity-length}\n\nWe can also see at @fig-capacity-length that, when *length* and *capacity* are equal, it means that the array have no space left.\nWe have reached the ceiling of our capacity, and because of that, if we want to store more values\nin this array, we need to expand it. We need to get a bigger space that can hold more values\nthan what we currently have.\n\nA dynamic array works by expanding the underlying array, whenever the *length* becomes equal\nto the *capacity* of the array. It basically allocates a new contiguous block of memory that is bigger\nthan the previous one, then, it copies all values that are currently being stored to this new\nlocation (i.e. this new block of memory), then, it frees the previous block of\nmemory. At the end of this process, the new underlying array have a bigger *capacity*, and, therefore,\nthe *length* becomes, once again, smaller than the *capacity* of the array.\n\nThis is the cycle of an dynamic array. Notice that, throughout this cycle, the *capacity* is always\neither equal to or higher than the *length* of the array. If youh have an `ArrayList` object (let's suppose\nyou named it `buffer`), you can check the current capacity of your array by accessing the `capacity`\nattribute of your `ArrayList` object, while the current *length* of it is available at the `items.len`\nattribute.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// Check capacity\nbuffer.capacity;\n// Check length\nbuffer.items.len;\n```\n:::\n\n\n\n\n\n### Creating an `ArrayList` object\n\nIn order to use `ArrayList`, you must provide an allocator object to it.\nRemember, Zig does not have a default memory allocator. And as I described at @sec-allocators, all memory\nallocations must be done by an allocator object that you define, that\nyou have control over. In our example here, I'm going to use\na general purpose allocator, but you can use any other allocator\nof your preference.\n\nWhen you initialize an `ArrayList` object, you must provide the data type of the elements of\nthe array. In other words, this defines the type of data that this array (or container) will\nstore. Therefore, if I provide the `u8` type to it, then, I will create a dynamic\narray of `u8` values. However, if I provide a struct that I have defined instead, like the struct `User`\nfrom @sec-structs-and-oop, then, a dynamic array of `User` values\nwill be created. In the example below, with the expression `ArrayList(u8)` we\nare creating a dynamic array of `u8` values.\n\nAfter you provide the data type of the elements of the array, you can initialize\nan `ArrayList` object by either using the `init()` or the `initCapacity()` methods.\nThe former method receives only the allocator object\nas input, while the latter method receives both the allocator object and a capacity number as inputs.\nWith the latter method, you not only initialize the struct, but you\nalso set the starting capacity of the allocated array.\n\nUsing the `initCapacity()` method is the preferred way to initialize your dynamic array.\nBecause reallocations, or, in other words, the process of expanding the capacity of the array,\nis always a high cost operation. You should take any possible opportunity to avoid reallocations in\nyour array. If you know how much space your array needs to occupy at the beginning,\nyou should always use `initCapacity()` to create your dynamic array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n```\n:::\n\n\n\n\n\nIn the example above, the `buffer` object starts as an array of 100 elements. If this\n`buffer` object needs to create more space to accomodate more elements during the runtime of your program, the `ArrayList`\ninternals will perform the necessary actions for you automatically.\nAlso notice the `deinit()` method being used to destroy the `buffer` object at the\nend of the current scope, by freeing all the memory that was allocated for the dynamic\narray stored in this `buffer` object.\n\n\n### Adding new elements to the array\n\nNow that we have created our dynamic array, we can start to use it. You can append (a.k.a \"add\")\nnew values to this array by using the `append()` method. This method works the same way\nas the `append()` method from a Python list, or, the `emplace_back()` method from `std::vector` of C++.\nYou provide a single value to this method, and the method appends this value to the array.\n\nYou can also use the `appendSlice()` method to append multiple values at once. You provide\na slice (slices were described at @sec-arrays) to this method, and the method adds all values present\nin this slice to your dynamic array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry buffer.append('H');\ntry buffer.append('e');\ntry buffer.append('l');\ntry buffer.append('l');\ntry buffer.append('o');\ntry buffer.appendSlice(\" World!\");\n```\n:::\n\n\n\n\n### Removing elements from the array {#sec-dynamic-array-remove}\n\nYou can use the `pop()` method to \"pop\" or remove\nthe last element in the array. Is worth noting that this method\ndo not change the capacity of the array. It just deletes or erases\nthe last value stored in the array.\n\nAlso, this method returns as result the value that got deleted. That is, you can\nuse this method to both get the last value in the array, and also, remove\nit from the array. It is a \"get and remove value\" type of method.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exclamation_mark = buffer.pop();\n```\n:::\n\n\n\n\nNow, if you want to remove specific elements from specific positions\nof your array, you can use the `orderedRemove()` method from your\n`ArrayList` object. With this method, you can provide an index as input,\nthen, the method will delete the value that is at this index in the array.\nYou are effectively reducing the *length* of the array everytime you execute\nan `orderedRemove()` operation.\n\nIn the example below, we first create an `ArrayList` object, and we fill it\nwith numbers. Then, we use `orderedRemove()` to remove the value at\nindex 3 in the array, two consecutive times.\n\nAlso, notice that we are assigning the result of `orderedRemove()` to the\nunderscore character. So we are discarding the result value of this method.\nThe `orderedRemove()` method returns the value that got deleted, in a similar\nstyle to the `pop()` method.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n\nfor (0..10) |i| {\n    const index: u8 = @intCast(i);\n    try buffer.append(index);\n}\n\nstd.debug.print(\n    \"{any}\\n\", .{buffer.items}\n);\n_ = buffer.orderedRemove(3);\n_ = buffer.orderedRemove(3);\n\nstd.debug.print(\"{any}\\n\", .{buffer.items});\nstd.debug.print(\"{any}\\n\", .{buffer.items.len});\n```\n:::\n\n\n\n\n```\n{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }\n{ 0, 1, 2, 5, 6, 7, 8, 9 }\n8\n```\n\nOne key characteristic about `orderedRemove()` is that it preserves the order\nof the values in the array. So, it deletes the value that you asked it to\nremove, but it also makes sure that the order of the values that remain in the array\nstay the same as before.\n\nNow, if you don't care about the order of the values, for example, maybe you want to treat\nyour dynamic array as a set of values, like the `std::unordered_set`\nstructure from C++, you can use the `swapRemove()` method instead. This method\nworks similarly to the `orderedRemove()` method. You give an index to this\nmethod, then, it deletes the value that is at this index in the array.\nBut this method does not preserve the original order of the values that remain\nin the array. As a result, `swapRemove()` is, in general, faster than `orderedRemove()`.\n\n\n### Inserting elements at specific indexes\n\nWhen you need to insert values in the middle of your array,\ninstead of just appending them to the end of the array, you need to use\nthe `insert()` and `insertSlice()` methods, instead of\nthe `append()` and `appendSlice()` methods.\n\nThese two methods work very similarly to `insert()` and `insert_range()`\nfrom the C++ `std::vector` class. You provide an index to these methods,\nand they insert the values that you provide at that index in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 10);\ndefer buffer.deinit();\n\ntry buffer.appendSlice(\"My Pedro\");\ntry buffer.insert(4, '3');\ntry buffer.insertSlice(2, \" name\");\nfor (buffer.items) |char| {\n    try stdout.print(\"{c}\", .{char});\n}\n```\n:::\n\n\n\n\n```\nMy name P3edro\n```\n\n\n### Conclusion\n\nIf you feel the lack of some other method, I recommend\nyou to read the [official documentation for the `ArrayListAligned`](https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned)[^zig-array2]\nstruct, which describes most of the methods available\nthrough the `ArrayList` object.\n\nYou will notice that there is a lot of other methods in this page that\nI did not described here, and I recommend you to explore these methods,\nand understand how they work.\n\n[^zig-array2]: <https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned>\n\n\n\n## Maps or HashTables {#sec-maps-hashtables}\n\nSome professionals know this type of data structure by different terms, like \"map\",\n\"hashmap\" or \"associative arrays\". But the most common term used is *hashtable*.\nEvery programming language normally have some implementation of a hashtable in their\nstandard libraries. Python have `dict()`, C++ have `std::map` and `std::unordered_map`, Rust\nhave `HashMap`, Javascript have `Object()` and `Map()`, etc.\n\n\n\n### What is a hashtable?\n\nA hashtable is a data structure based on key-value pairs.\nYou provide a key and a value to this structure, then, the hashtable will store\nthe input value at a location that can be identified by the input\nkey that you provided.\nIt does that by using an underlying array and a hash function.\nThese two components are essential to how a hashtable works.\n\nUnder the hood, the hashtable contains an array. This array is where the values\nare stored, and the elements of this array are usually called of *buckets*.\nSo the values that you provide to the hashtable are stored inside buckets,\nand you access each bucket by using an index.\n\nWhen you provide a key to a hashtable, it passes this key to the\nhash function. This hash function uses some sort of hashing algorithm to transform\nthis key into an index. This index is actually an array index. It is a position\nin the underlying array of the hashtable.\nThis is how a key identifies a specific position (or location) inside the hashtable\nstructure.\n\nTherefore, you provide a key to the hashtable, and this key identifies a specific location\ninside the hashtable, then, the hashtable takes the input value that you provided,\nand stores this value in the location identified by this input key.\nYou could say that the key maps to the value stored in the hashtable. You find\nthe value, by using the key that identifies the location where the value is stored.\nThe @fig-hashtable presents this process visually.\n\n\n![A diagram of a Hashtable. Source: Wikipedia, the free encyclopedia.](./../Figures/hashtable.svg){#fig-hashtable}\n\n\nThe operation described in the previous paragraph is normally called an *insertion* operation.\nBecause you are inserting new values into the hashtable.\nBut there are other types of operations in hashtables such as *delete* and *lookup*.\nDelete is self describing, it is when you delete (or remove) a value from the hashtable.\nWhile lookup corresponds to when you look at a value that is stored in\nthe hashtable, by using the key that identifies the location where this value is stored.\n\nSometimes, instead of storing the values directly, the underlying array of the hashtable might be an array of pointers,\ni.e. the buckets of the array stores pointers that points to the value,\nor also, may be an array of linked lists.\nThese cases are common on hashtables that allows duplicate keys, or, in other words,\non hashtables that effectively handle \"collisions\" that may arise from the hash function.\n\nDuplicate keys, or this \"collision\" thing that I'm talking about, is when you have two different keys\nthat points to the same location (i.e. to the same index)\nin the underlying array of the hashtable. This might happen depending on the characteristics of the hash function\nthat is being used in the hashtable. Some implementations of the hashtable will actively deal with collisions,\nmeaning that, they will handle this case in some way. For example, the hashtable\nmight transform all buckets into linked lists. Because with a linked list you can store\nmultiple values into a single bucket.\n\nThere are different techniques to handle collisions in hashtables, which I will not describe\nin this book, because it is not our main scope here. But you can find a good description of\nsome of the most common techniques at the Wikipedia page of hashtables [@wikipedia_hashtables].\n\n\n### Hashtables in Zig {#sec-hashmap}\n\nThe Zig Standard Library provides different implementations of a hashtable.\nEach implementation have its own cons and pros, which we will\ndiscuss later on, and all of them are available through the `std.hash_map` module.\n\nThe `HashMap` struct is a general-purpose hashtable,\nwhich have very fast operations (lookup, insertion, delete), and also,\nquite high load factors for low memory usage. You can create and provide a context object\nto the `HashMap` constructor. This context object allows you to tailor\nthe behaviour of the hashtable itself, because you can\nprovide a hash function implementation to be used by the hashtable\nthrough this context object.\n\nBut let's not worry about this context object now, because it is meant to be used\nby \"experts in the field of hashtables\". Since we are most likely not\nexperts in this field, we are going to take the easy way to create\na hashtable. Which is by using the `AutoHashMap()` function.\n\n\nThis `AutoHashMap()` function is essentially a \"create a hashtable object that uses the default settings\"\ntype of function. It automatically chooses a context object, and, therefore, a hash function implementation,\nfor you. This function receives two data types as input, the first input is the data type of the keys\nthat will be used in this hashtable, while the second input is the data type of the data that will be\nstored inside the hashtable, that is, the data type of the values to be stored.\n\nIn the example below, we are providing the data type `u32` in the first argument, and `u16` in the second argument of this\nfunction. This means that we are going to use `u32` values as keys in this hashtable, while `u16` values are the actual values\nthat are going to be stored into this hashtable.\nAt the end of this process, the `hash_table` object contains a `HashMap` object\nthat uses the default settings and context.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n    std.debug.print(\n        \"Value at key 50050: {d}\\n\",\n        .{hash_table.get(50050).?}\n    );\n\n    if (hash_table.remove(57709)) {\n        std.debug.print(\n            \"Value at key 57709 successfully removed!\\n\",\n            .{}\n        );\n    }\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n}\n```\n:::\n\n\n\n\n```\nN of values stored: 3\nValue at key 50050: 55\nValue at key 57709 successfully removed!\nN of values stored: 2\n```\n\nYou can add/put new values into the hashtable by using the `put()` method. The first argument\nis the key to be used, and the second argument is the actual value that you want to store inside\nthe hashtable. In the example below, we first add the value 89 using the key 54321, next, we add\nthe value 55 using the key 50050, etc.\n\nNotice that we have used the method `count()` to see how many values are currently stored in the\nhashtable. After that, we also use the `get()` method to access (or look) at the value stored in\nthe position identified by the key 500050. The output of this `get()` method is an optional value.\nThis is why we use the `?` method at the end to get the actual value.\n\nAlso notice that we can remove (or delete) values from the hashtable by using the `remove()` method.\nYou provide the key that identifies the value that you want to delete, then, the method will\ndelete this value and return a `true` value as output. This `true` value essentially tells us\nthat the method successfully deleted the value.\n\nBut this delete operation might not be always successful. For example, you might provide the wrong\nkey to this method. I mean, maybe you provide\n(either intentionally or unintentionally) a key that points to an empty bucket,\ni.e. a bucket that still doesn't have a value in it.\nIn this case, the `remove()` method would return a `false` value.\n\n\n\n### Iterating through the hashtable\n\nIterating through the keys and values that are currently being stored in\nthe hashtable is a very common necessity.\nYou can do that in Zig by using an iterator object that can iterate\nthrough the elements of your hashtable object.\n\nThis iterator object works like any other iterator object that you would\nfind in languages such as C++ and Rust. It is basically a pointer object\nthat points to some value in the container, and has a `next()` method\nthat you can use to navigate (or iterate) through the values in the\ncontainer.\n\nYou can create such iterator object by using the `iterator()` method of the hashtable object.\nThis method returns an iterator object, from which you can use the `next()` method in conjunction\nwith a while loop to iterate through the elements of your hashtable. The `next()` method returns an optional\n`Entry` value, and therefore, you must unwrap this optional value to get the actual `Entry` value\nfrom which you can access the key and also the value identified by this key.\n\nWith this `Entry` value at hand, you can access the key of this current entry by using the `key_ptr`\nattribute and dereferencing the pointer that lives inside of it, while the value identified by this\nkey is accessed through the `value_ptr` attribute instead, which is also a pointer to be dereferenced.\nThe code example below demonstrates the use of these elements:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n\n    var it = hash_table.iterator();\n    while (it.next()) |kv| {\n        // Access the current key\n        std.debug.print(\"Key: {d} | \", .{kv.key_ptr.*});\n        // Access the current value\n        std.debug.print(\"Value: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n:::\n\n\n\n\n```\nKey: 54321 | Value: 89\nKey: 50050 | Value: 55\nKey: 57709 | Value: 41\n```\n\n\nIf you want to iterate specifically through the values or the keys of your hashtable,\nyou can create a key iterator or a value iterator object. These are also iterator\nobjects, which have the same `next()` method that you can use to iterate through the\nhashtable.\n\nKey iterators are created from the `keyIterator()` method of your\nhashtable object, while value iterators are created from the `valueIterator()` method.\nAll you have to do is to unwrap the value from the `next()` method and deference it\ndirectly to access the key or the value that you are iterating over.\nThe code example below demonstrates the use of a key iterator,\nbut you can replicate the same logic to a value iterator.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar kit = hash_table.keyIterator();\nwhile (kit.next()) |key| {\n    std.debug.print(\"Key: {d}\\n\", .{key.*});\n}\n```\n:::\n\n\n\n\n```\nKey: 54321\nKey: 50050\nKey: 57709\n```\n\n\n### The `ArrayHashMap` hashtable {#sec-array-map}\n\nIf you need to iterate through the elements of your hashtable constantly,\nyou might want to use the `ArrayHashMap` struct for your specific case,\ninstead of going with the usual and general-purpose `HashMap` struct.\n\nThe `ArrayHashMap` struct creates a hashtable that is faster to iterate over.\nThat is why this specific type of hashtable might be valuable to you.\nSome other properties of a `ArrayHashMap` hashtable are:\n\n- the order of insertion is preserved, i.e. the order of the values that you find while iterating through this hashtable is actually the order in which these values were inserted in the hashtable.\n- the key-value pairs are stored sequentially, one after another.\n\n\nYou can create an `ArrayHashMap` object by using, once again, a helper function that\nchooses automatically for you a hash function implementation. This is the\n`AutoArrayHashMap()` function, which works very similarly to the `AutoHashMap()`\nfunction that we presented at @sec-hashmap.\n\nYou provide two data types to this function. The data type of the keys that will be\nused in this hashtable, and the data type of the values that will be stored in\nthis hashtable.\n\nAn `ArrayHashMap` object have essentially the exact same methods from the `HashMap` struct.\nSo you can insert new values into the hashtable by using the `put()` method, and you can look (or get)\na value from the hashtable by using the `get()` method. But the `remove()` method is not available\nin this specific type of hashtable.\n\nIn order to delete values from the hashtable, you would use the same methods that you find in\nan `ArrayList` object, i.e. a dynamic array. I presented these methods at @sec-dynamic-array-remove,\nwhich are the `swapRemove()` and `orderedRemove()` methods. These methods have the same meaning here, or,\nthe same effect that they have in an `ArrayList` object.\n\nThis means that, with `swapRemove()` you remove the value from the hashtable, but you do not preserve\nthe order in which the values were inserted into the structure. While `orderedRemove()` is able\nto retain the order in which these values were inserted.\n\nBut instead of providing an index as input to `swapRemove()` or `orderedRemove()`, like I described\nat @sec-dynamic-array-remove, these methods here in an `ArrayHashMap` take a key as input, like\nthe `remove()` method from a `HashMap` object. If you want to provide an index as input, instead\nof a key, you should use the `swapRemoveAt()` and `orderedRemoveAt()` methods.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar hash_table = AutoArrayHashMap(u32, u16)\n    .init(allocator);\ndefer hash_table.deinit();\n```\n:::\n\n\n\n\n\n\n### The `StringHashMap` hashtable {#sec-string-hash-map}\n\nOne thing that you will notice in the other two types of hashtables that I have\npresented over the last sections, is that neither of them accepts a slice data type\nin their keys.\nWhat this means is that you cannot use a slice value to represent a key in\nthese types of hashtable.\n\nThe most obvious consequence of this, is that you cannot use strings as keys\nin these hashtables. But it is extremely common to use strings as keys\nin hashtables.\n\nTake this very simple Javascript code snippet as an example. We are creating\na simple hashtable object named `people`. Then, we add a new entry to this\nhashtable, which is identified by the string `'Pedro'`. This string is the\nkey in this case, while the object containing different personal information such as\nage, height and city, is the value to be stored in the hashtable.\n\n```js\nvar people = new Object();\npeople['Pedro'] = {\n    'age': 25,\n    'height': 1.67,\n    'city': 'Belo Horizonte'\n};\n```\n\nThis pattern of using strings as keys is very common in\nall sorts of situations. That is why the Zig Standard Library offers a\nspecific type of hashtable for this purpose, which is created through the `StringHashMap()` function.\nThis function creates a hashtable that uses strings as keys. The only input of this\nfunction is the data type of the values that will be stored into this hashtable.\n\nIn the example below, I'm creating a hashtable to store the ages of different people.\nEach key in this hashtable is represented by the name of each person, while the value stored in the\nhashtable is the age of this person identified by the key.\n\nThat is why I provide the `u8` data type (which is the data type used by the age values) as input to this `StringHashMap()` function.\nAs the result, it creates a hashtable that uses string values as keys, and, that stores\n`u8` values in it. Notice that an allocator object is provided at the `init()` method of the\nresulting object from the `StringHashMap()` function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var ages = std.StringHashMap(u8).init(allocator);\n    defer ages.deinit();\n\n    try ages.put(\"Pedro\", 25);\n    try ages.put(\"Matheus\", 21);\n    try ages.put(\"Abgail\", 42);\n\n    var it = ages.iterator();\n    while (it.next()) |kv| {\n        std.debug.print(\"Key: {s} | \", .{kv.key_ptr.*});\n        std.debug.print(\"Age: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n:::\n\n\n\n\n```\nKey: Pedro | Age: 25\nKey: Abgail | Age: 42\nKey: Matheus | Age: 21\n```\n\n\n### The `StringArrayHashMap` hashtable\n\nThe Zig Standard Library also provides a type of hashtable that mix the cons and pros of the\n`StringHashMap` and `ArrayHashMap` together. That is, a hashtable\nthat uses strings as keys, but also have the advantages from `ArrayHashMap`.\nIn other words, you can have a hashtable that is fast to iterate over,\nthat preserves insertion order, and also, that uses strings as keys.\n\nYou can create such type of hashtable by using the `StringArrayHashMap()` function.\nThis function accepts a data type as input, which is the data type of the values that are\ngoing to be stored inside this hashtable, in the same style as the function presented\nat @sec-string-hash-map.\n\nYou can insert new values into this hashtable by using the same `put()` method that\nwe have discussed at @sec-string-hash-map. And you can also get values from the hashtable\nby using the same `get()` method.\nLike its `ArrayHashMap` brother, to delete values from this specific type of hashtable,\nwe also use the `orderedRemove()` and `swapRemove()` methods, with the same effects that\nI have described at @sec-array-map.\n\nIf we take the code example that was exposed at @sec-string-hash-map, we can\nachieve the exact same result with `StringArrayHashMap()`:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar ages = std.StringArrayHashMap(u8).init(allocator);\n```\n:::\n\n\n\n\n\n\n\n## Linked lists\n\nThe Zig Standard Library provides an implementation for both singly and doubly linked lists.\nA linked list is a linear data structure that looks like a chain, or, a rope.\nThe main advantage of this data structure is that you normally have very fast\ninsertion and deletion operations. But, as a disadvantage, iterating through\nthis data structure is usually not so fast as iterating through an array.\n\nThe idea behind a linked list is to build a structure that consists of a sequence of nodes\nconnected to each other by pointers. This means that linked lists are usually not contiguous\nin memory, because each node might be anywhere in memory. They do not need to be close to\none another.\n\nAt @fig-linked-list we can see a diagram of a singly linked list. We begin at the first node\n(which is usually called \"the head of the linked list\"). Then, from this\nfirst node we uncover the remaining nodes in the structure, by following the locations pointed\nby the pointers found in each node.\n\nEach node has two things in it. It has the value that is stored in the current node\n, and also, a pointer. This pointer points to the next node in the list. If this pointer\nis null, then, it means that we have reached the end of our linked list.\n\n![A diagram of a singly linked list.](./../Figures/linked-list.png){#fig-linked-list}\n\n\nAt @fig-linked-list2 we can see a diagram of a doubly linked list. The only thing that really\nchanges now is that every node in the linked list has both a pointer to the previous node,\nand, a pointer to the next node. So every node in a doubly linked list has two pointers in it. These are\nusually called the `prev` (for \"previous\") and the `next` (for \"next\") pointers of the node.\n\nIn the singly linked list example, we had only one single pointer in each node, and this singular\npointer was always pointing to the next node in the sequence. This means that singly linked lists\nnormally have only the `next` pointer in them.\n\n![A diagram of a doubly linked list.](./../Figures/doubly-linked-list.png){#fig-linked-list2}\n\n\nLinked lists are available in Zig through the functions `SinglyLinkedList()` and\n`DoublyLinkedList()`, for \"singly linked lists\" and \"doubly linked lists\", respectively. These functions are\nactually generic functions, which we are going to talk more about at @sec-generic-fun.\n\nFor now, just understand that, in order to create a linked list object,\nwe begin by providing a data type to these functions. This data type defines\nthe type of data that each node in this linked list will store. In the example below,\nwe are creating a singly linked list of `u32` values.\nSo each node in this linked list will store a `u32` value.\n\nBoth the `SinglyLinkedList()` and `DoublyLinkedList()` functions returns a type,\ni.e. a struct definition, as output. Therefore, the object `Lu32` is actually\na struct definition. It defines the type \"singly linked list of `u32` values\".\n\nNow that we have the definition of the struct, we need to instantiate a `Lu32` object.\nWe normally instantiate struct objects in Zig by using an `init()` method.\nBut in this case, we are instantiating the struct directly, by using an empty\n`struct` literal, in the expression `Lu32{}`.\n\nIn this example, we first create multiple node objects, and after we create them,\nwe start to insert and connect these nodes to build the linked list, using the\n`prepend()` and `insertAfter()` methods. Notice that the `prepend()` method\nis a method from the linked list object, while the `insertAfter()` is a method\npresent in the node objects.\n\nIn essence, the `prepend()` method inserts a node at the beginning of the linked\nlist. In other words, the node that you provide to this method, becomes the new\n\"head node\" of the linked list. It becomes the first node in the list (see @fig-linked-list).\n\nOn the other side, the `insertAfter()` method is used to basically connect two nodes together.\nWhen you provide a node to this method, it creates a pointer to this input node,\nand stores this pointer in the `next` attribute of the current node, from which the method was called from.\n\nBecause doubly linked lists have both a `next` and a `prev` attributes in each node\n(as described at @fig-linked-list2), a node object created from\na `DoublyLinkedList` object have both an `insertBefore()` (for `prev`)\nand an `insertAfter()` (for `next`) methods available.\n\nThus, if we have used a doubly linked list, we can use the `insertBefore()` method\nto store the pointer to the input node in the `prev` attribute. This would put the input\nnode as the \"previous node\", or, the node before the current node. In contrast, the `insertAfter()` method\nputs the pointer created to the input node in the `next` attribute of the current node,\nand as result, the input node becomes the \"next node\" of the current node.\n\nSince we are using a singly linked list in this example, we have only the `insertAfter()` method\navailable in the node objects that we create from our `Lu32` type.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SinglyLinkedList = std.SinglyLinkedList;\nconst Lu32 = SinglyLinkedList(u32);\n\npub fn main() !void {\n    var list = Lu32{};\n    var one = Lu32.Node{ .data = 1 };\n    var two = Lu32.Node{ .data = 2 };\n    var three = Lu32.Node{ .data = 3 };\n    var four = Lu32.Node{ .data = 4 };\n    var five = Lu32.Node{ .data = 5 };\n\n    list.prepend(&two); // {2}\n    two.insertAfter(&five); // {2, 5}\n    list.prepend(&one); // {1, 2, 5}\n    two.insertAfter(&three); // {1, 2, 3, 5}\n    three.insertAfter(&four); // {1, 2, 3, 4, 5}\n}\n```\n:::\n\n\n\n\n\nThere are other methods available from the linked list object, depending if this object is\na singly linked list or a doubly linked list, that might be very useful for you. You can find a\nsummary of them in the bullet points below:\n\n- `remove()` to remove a specific node from the linked list.\n- if singly linked list, `len()` to count how many nodes there is in the linked list.\n- if doubly linked list, checkout the `len` attribute to see how many nodes there is in the linked list.\n- if singly linked list, `popFirst()` to remove the first node (i.e. the \"head\") from the linked list.\n- if doubly linked list, `pop()` and `popFirst()` to remove the last and first nodes from the linked list, respectively.\n- if doubly linked list, `append()` to add a new node to end of the linked list (i.e. inverse of `prepend()`).\n\n\n\n## Multi array structure\n\nZig introduces a new data structure called `MultiArrayList()`. It is a different version of the dynamic array\nthat we have introduced at @sec-dynamic-array. The difference between this structure and the `ArrayList()`\nthat we know from @sec-dynamic-array, is that `MultiArrayList()` creates a separate dynamic array\nfor each field of the struct that you provide as input.\n\nConsider the following code example. We create a new custom struct called `Person`. This\nstruct contains three different data members, or, three different fields. As consequence,\nwhen we provide this `Person` data type as input to `MultiArrayList()`, this\ncreates a \"struct of three different arrays\" called `PersonArray`. In other words,\nthis `PersonArray` is a struct that contains three internal dynamic arrays in it.\nOne array for each field found in the `Person` struct definition.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Person = struct {\n    name: []const u8,\n    age: u8,\n    height: f32,\n};\nconst PersonArray = std.MultiArrayList(Person);\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var people = PersonArray{};\n    defer people.deinit(allocator);\n\n    try people.append(allocator, .{\n        .name = \"Auguste\", .age = 15, .height = 1.54\n    });\n    try people.append(allocator, .{\n        .name = \"Elena\", .age = 26, .height = 1.65\n    });\n    try people.append(allocator, .{\n        .name = \"Michael\", .age = 64, .height = 1.87\n    });\n}\n```\n:::\n\n\n\n\nIn other words, instead of creating an array of \"persons\", the `MultiArrayList()` function\ncreates a \"struct of arrays\". Each data member of this struct is a different array that stores\nthe values of a specific field from the `Person` values that were added (or, appended) to this \"struct of arrays\".\nOne important detail is that each of these separate internal arrays stored inside `PersonArray`\nare dynamic arrays. This means that these arrays can grow in capacity automatically as needed, to accomodate\nmore values.\n\nThe @fig-multi-array exposed below presents a diagram that describes the `PersonArray` struct\nthat we have created in the previous code example. Notice that the values of the data members\npresent in each of the three `Person` values that we have appended into the `PersonArray` object\n, are scattered across three different internal arrays of the `PersonArray` object.\n\n![A diagram of the `PersonArray` struct.](./../Figures/multi-array.png){#fig-multi-array}\n\nYou can easily access each of these arrays separately, and iterate over the values of each array.\nFor that, you will need to call the `items()` method from the `PersonArray` object, and provide as input\nto this method, the name of the field that you want to iterate over.\nIf you want to iterate through the `.age` array for example, then, you need to call `items(.age)` from\nthe `PersonArray` object, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (people.items(.age)) |*age| {\n    try stdout.print(\"Age: {d}\\n\", .{age.*});\n}\n```\n:::\n\n\n\n\n```\nAge: 15\nAge: 26\nAge: 64\n```\n\n\nIn the above example, we are iterating over the values of the `.age` array, or,\nthe internal array of the `PersonArray` object that contains the values of the `age`\ndata member from the `Person` values that were added to the multi array struct.\n\nIn this example we are calling the `items()` method directly from the `PersonArray`\nobject. However, it is recommended on most situations to call this `items()` method\nfrom a \"slice object\", which you can create from the `slice()` method.\nThe reason for this is that calling `items()` multiple times have better performance\nif you use a slice object.\n\nTherefore, if you are planning to access only one of the\ninternal arrays from your \"multi array struct\", it is fine to call `items()` directly\nfrom the multi array object. But if you need to access many of the internal arrays\nfrom your \"multi array struct\", then, you will likely need to call `items()` more\nthan once, and, in such circumstance, is better to call `items()` through a slice object.\nThe example below demonstrates the use of such object:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar slice = people.slice();\nfor (slice.items(.age)) |*age| {\n    age.* += 10;\n}\nfor (slice.items(.name), slice.items(.age)) |*n,*a| {\n    try stdout.print(\n        \"Name: {s}, Age: {d}\\n\", .{n.*, a.*}\n    );\n}\n```\n:::\n\n\n\n\n```\nName: Auguste, Age: 25\nName: Elena, Age: 36\nName: Michael, Age: 74\n```\n\n\n## Conclusion\n\nThere are many other data structures that I haven't presented here.\nBut you can check them out at the official Zig Standard Library documentation page.\nActually, when you get into the [homepage of the documentation](https://ziglang.org/documentation/master/std/#)[^home], the first thing\nthat appears to you in this page, is a list of types and data structures that\nare available in the Zig Standard Library.\nThere are some very specific data structures in this list, like a\n[`BoundedArray` struct](https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray)[^bounded]\n, but there is also some more general structures, such as a\n[`PriorityQueue` struct](https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue)[^priority].\n\n\n[^home]: <https://ziglang.org/documentation/master/std/#>\n[^priority]: <https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue>.\n[^bounded]: <https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray>\n\n\n\n\n\n\n",
-    "supporting": [
-      "09-data-structures_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Data Structures\n\nIn this chapter, I want to present the most common Data Structures that are available from\nthe Zig Standard Library, especially `ArrayList` and also `HashMap`. These are generic Data Structures\nthat you can use to store and control any type of data that is produced by your application.\n\n## Dynamic Arrays {#sec-dynamic-array}\n\nIn high level languages, arrays are usually dynamic. They can easily grow\nin size when they have to, and you don't need to worry about it.\nIn contrast, arrays in low level languages are usually static by default.\nThis is the reality of C, C++, Rust and also Zig. Static arrays were presented at\n@sec-arrays, but in this section, we are going to talk about dynamic arrays in Zig.\n\nDynamic arrays are simply arrays that can grow in size during the runtime\nof your program. Most low level languages have some implementation of\na dynamic array in their standard library. C++ have `std::vector`, Rust have `Vec`,\nand Zig have `std.ArrayList`.\n\nThe `std.ArrayList` struct provides a contiguous and growable array for you.\nIt works like any other dynamic array, it allocates a contiguous block of memory, and when this block have no space left,\n`ArrayList` allocates another contiguous and bigger block of memory, copies the\nelements to this new location, and erases (or frees) the previous block of memory.\n\n\n### Capacity vs Length\n\nWhen we talk about dynamic arrays, we usually have two similar concepts that\nare very essential to how a dynamic array works behind the hood.\nThese concepts are *capacity* and *length*. In some contexts, especially\nin C++, *length* is also called of *size*.\n\nAlthough they look similar, these concepts represent different things\nin the context of a dynamic array. *Capacity* is the number of items (or elements)\nthat your dynamic array can currently hold without the need to allocate more memory.\n\nIn contrast, the *length* refers to how many elements in the array\nare currently being used, or, in other words, how many elements in this array\nthat you have assigned a value to. Every dynamic array works around\na block of allocated memory, which represents an array with total capacity for $n$ elements.\nHowever, only a portion of these $n$ elements are being used most of the time. This portion\nof $n$ is the *length* of the array. So every time you append a new value\nto the array, you are incrementing its *length* by one.\n\nThis means that a dynamic array usually works with an extra margin, or, an extra space\nwhich is currently empty, but it is waiting and ready to be used. This \"extra space\"\nis essentially the difference between *capacity* and *length*. *Capacity* represents\nthe total number of elements that the array can hold without the need to re-allocate\nor re-expand the array, while the *length* represents how much of this capacity\nis currently being used to hold/store values.\n\n@fig-capacity-length presents this idea visually. Notice that, at first,\nthe capacity of the array is greater than the length of the array.\nSo, the dynamic array have extra space that is currently empty, but it\nis ready to receive a value to be stored.\n\n![Difference between capacity and length in a dynamic array](./../Figures/dynamic-array.png){#fig-capacity-length}\n\nWe can also see at @fig-capacity-length that, when *length* and *capacity* are equal, it means that the array have no space left.\nWe have reached the ceiling of our capacity, and because of that, if we want to store more values\nin this array, we need to expand it. We need to get a bigger space that can hold more values\nthan what we currently have.\n\nA dynamic array works by expanding the underlying array, whenever the *length* becomes equal\nto the *capacity* of the array. It basically allocates a new contiguous block of memory that is bigger\nthan the previous one, then, it copies all values that are currently being stored to this new\nlocation (i.e. this new block of memory), then, it frees the previous block of\nmemory. At the end of this process, the new underlying array have a bigger *capacity*, and, therefore,\nthe *length* becomes, once again, smaller than the *capacity* of the array.\n\nThis is the cycle of an dynamic array. Notice that, throughout this cycle, the *capacity* is always\neither equal to or higher than the *length* of the array. If youh have an `ArrayList` object (let's suppose\nyou named it `buffer`), you can check the current capacity of your array by accessing the `capacity`\nattribute of your `ArrayList` object, while the current *length* of it is available at the `items.len`\nattribute.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// Check capacity\nbuffer.capacity;\n// Check length\nbuffer.items.len;\n```\n:::\n\n\n\n\n\n### Creating an `ArrayList` object\n\nIn order to use `ArrayList`, you must provide an allocator object to it.\nRemember, Zig does not have a default memory allocator. And as I described at @sec-allocators, all memory\nallocations must be done by an allocator object that you define, that\nyou have control over. In our example here, I'm going to use\na general purpose allocator, but you can use any other allocator\nof your preference.\n\nWhen you initialize an `ArrayList` object, you must provide the data type of the elements of\nthe array. In other words, this defines the type of data that this array (or container) will\nstore. Therefore, if I provide the `u8` type to it, then, I will create a dynamic\narray of `u8` values. However, if I provide a struct that I have defined instead, like the struct `User`\nfrom @sec-structs-and-oop, then, a dynamic array of `User` values\nwill be created. In the example below, with the expression `ArrayList(u8)` we\nare creating a dynamic array of `u8` values.\n\nAfter you provide the data type of the elements of the array, you can initialize\nan `ArrayList` object by either using the `init()` or the `initCapacity()` methods.\nThe former method receives only the allocator object\nas input, while the latter method receives both the allocator object and a capacity number as inputs.\nWith the latter method, you not only initialize the struct, but you\nalso set the starting capacity of the allocated array.\n\nUsing the `initCapacity()` method is the preferred way to initialize your dynamic array.\nBecause reallocations, or, in other words, the process of expanding the capacity of the array,\nis always a high cost operation. You should take any possible opportunity to avoid reallocations in\nyour array. If you know how much space your array needs to occupy at the beginning,\nyou should always use `initCapacity()` to create your dynamic array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n```\n:::\n\n\n\n\n\nIn the example above, the `buffer` object starts as an array of 100 elements. If this\n`buffer` object needs to create more space to accomodate more elements during the runtime of your program, the `ArrayList`\ninternals will perform the necessary actions for you automatically.\nAlso notice the `deinit()` method being used to destroy the `buffer` object at the\nend of the current scope, by freeing all the memory that was allocated for the dynamic\narray stored in this `buffer` object.\n\n\n### Adding new elements to the array\n\nNow that we have created our dynamic array, we can start to use it. You can append (a.k.a \"add\")\nnew values to this array by using the `append()` method. This method works the same way\nas the `append()` method from a Python list, or, the `emplace_back()` method from `std::vector` of C++.\nYou provide a single value to this method, and the method appends this value to the array.\n\nYou can also use the `appendSlice()` method to append multiple values at once. You provide\na slice (slices were described at @sec-arrays) to this method, and the method adds all values present\nin this slice to your dynamic array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry buffer.append('H');\ntry buffer.append('e');\ntry buffer.append('l');\ntry buffer.append('l');\ntry buffer.append('o');\ntry buffer.appendSlice(\" World!\");\n```\n:::\n\n\n\n\n### Removing elements from the array {#sec-dynamic-array-remove}\n\nYou can use the `pop()` method to \"pop\" or remove\nthe last element in the array. Is worth noting that this method\ndo not change the capacity of the array. It just deletes or erases\nthe last value stored in the array.\n\nAlso, this method returns as result the value that got deleted. That is, you can\nuse this method to both get the last value in the array, and also, remove\nit from the array. It is a \"get and remove value\" type of method.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exclamation_mark = buffer.pop();\n```\n:::\n\n\n\n\nNow, if you want to remove specific elements from specific positions\nof your array, you can use the `orderedRemove()` method from your\n`ArrayList` object. With this method, you can provide an index as input,\nthen, the method will delete the value that is at this index in the array.\nYou are effectively reducing the *length* of the array everytime you execute\nan `orderedRemove()` operation.\n\nIn the example below, we first create an `ArrayList` object, and we fill it\nwith numbers. Then, we use `orderedRemove()` to remove the value at\nindex 3 in the array, two consecutive times.\n\nAlso, notice that we are assigning the result of `orderedRemove()` to the\nunderscore character. So we are discarding the result value of this method.\nThe `orderedRemove()` method returns the value that got deleted, in a similar\nstyle to the `pop()` method.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n\nfor (0..10) |i| {\n    const index: u8 = @intCast(i);\n    try buffer.append(index);\n}\n\nstd.debug.print(\n    \"{any}\\n\", .{buffer.items}\n);\n_ = buffer.orderedRemove(3);\n_ = buffer.orderedRemove(3);\n\nstd.debug.print(\"{any}\\n\", .{buffer.items});\nstd.debug.print(\"{any}\\n\", .{buffer.items.len});\n```\n:::\n\n\n\n\n```\n{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }\n{ 0, 1, 2, 5, 6, 7, 8, 9 }\n8\n```\n\nOne key characteristic about `orderedRemove()` is that it preserves the order\nof the values in the array. So, it deletes the value that you asked it to\nremove, but it also makes sure that the order of the values that remain in the array\nstay the same as before.\n\nNow, if you don't care about the order of the values, for example, maybe you want to treat\nyour dynamic array as a set of values, like the `std::unordered_set`\nstructure from C++, you can use the `swapRemove()` method instead. This method\nworks similarly to the `orderedRemove()` method. You give an index to this\nmethod, then, it deletes the value that is at this index in the array.\nBut this method does not preserve the original order of the values that remain\nin the array. As a result, `swapRemove()` is, in general, faster than `orderedRemove()`.\n\n\n### Inserting elements at specific indexes\n\nWhen you need to insert values in the middle of your array,\ninstead of just appending them to the end of the array, you need to use\nthe `insert()` and `insertSlice()` methods, instead of\nthe `append()` and `appendSlice()` methods.\n\nThese two methods work very similarly to `insert()` and `insert_range()`\nfrom the C++ `std::vector` class. You provide an index to these methods,\nand they insert the values that you provide at that index in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 10);\ndefer buffer.deinit();\n\ntry buffer.appendSlice(\"My Pedro\");\ntry buffer.insert(4, '3');\ntry buffer.insertSlice(2, \" name\");\nfor (buffer.items) |char| {\n    try stdout.print(\"{c}\", .{char});\n}\n```\n:::\n\n\n\n\n```\nMy name P3edro\n```\n\n\n### Conclusion\n\nIf you feel the lack of some other method, I recommend\nyou to read the [official documentation for the `ArrayListAligned`](https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned)[^zig-array2]\nstruct, which describes most of the methods available\nthrough the `ArrayList` object.\n\nYou will notice that there is a lot of other methods in this page that\nI did not described here, and I recommend you to explore these methods,\nand understand how they work.\n\n[^zig-array2]: <https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned>\n\n\n\n## Maps or HashTables {#sec-maps-hashtables}\n\nSome professionals know this type of data structure by different terms, like \"map\",\n\"hashmap\" or \"associative arrays\". But the most common term used is *hashtable*.\nEvery programming language normally have some implementation of a hashtable in their\nstandard libraries. Python have `dict()`, C++ have `std::map` and `std::unordered_map`, Rust\nhave `HashMap`, Javascript have `Object()` and `Map()`, etc.\n\n\n\n### What is a hashtable?\n\nA hashtable is a data structure based on key-value pairs.\nYou provide a key and a value to this structure, then, the hashtable will store\nthe input value at a location that can be identified by the input\nkey that you provided.\nIt does that by using an underlying array and a hash function.\nThese two components are essential to how a hashtable works.\n\nUnder the hood, the hashtable contains an array. This array is where the values\nare stored, and the elements of this array are usually called of *buckets*.\nSo the values that you provide to the hashtable are stored inside buckets,\nand you access each bucket by using an index.\n\nWhen you provide a key to a hashtable, it passes this key to the\nhash function. This hash function uses some sort of hashing algorithm to transform\nthis key into an index. This index is actually an array index. It is a position\nin the underlying array of the hashtable.\nThis is how a key identifies a specific position (or location) inside the hashtable\nstructure.\n\nTherefore, you provide a key to the hashtable, and this key identifies a specific location\ninside the hashtable, then, the hashtable takes the input value that you provided,\nand stores this value in the location identified by this input key.\nYou could say that the key maps to the value stored in the hashtable. You find\nthe value, by using the key that identifies the location where the value is stored.\nThe @fig-hashtable presents this process visually.\n\n\n![A diagram of a Hashtable. Source: Wikipedia, the free encyclopedia.](./../Figures/hashtable.svg){#fig-hashtable}\n\n\nThe operation described in the previous paragraph is normally called an *insertion* operation.\nBecause you are inserting new values into the hashtable.\nBut there are other types of operations in hashtables such as *delete* and *lookup*.\nDelete is self describing, it is when you delete (or remove) a value from the hashtable.\nWhile lookup corresponds to when you look at a value that is stored in\nthe hashtable, by using the key that identifies the location where this value is stored.\n\nSometimes, instead of storing the values directly, the underlying array of the hashtable might be an array of pointers,\ni.e. the buckets of the array stores pointers that points to the value,\nor also, may be an array of linked lists.\nThese cases are common on hashtables that allows duplicate keys, or, in other words,\non hashtables that effectively handle \"collisions\" that may arise from the hash function.\n\nDuplicate keys, or this \"collision\" thing that I'm talking about, is when you have two different keys\nthat points to the same location (i.e. to the same index)\nin the underlying array of the hashtable. This might happen depending on the characteristics of the hash function\nthat is being used in the hashtable. Some implementations of the hashtable will actively deal with collisions,\nmeaning that, they will handle this case in some way. For example, the hashtable\nmight transform all buckets into linked lists. Because with a linked list you can store\nmultiple values into a single bucket.\n\nThere are different techniques to handle collisions in hashtables, which I will not describe\nin this book, because it is not our main scope here. But you can find a good description of\nsome of the most common techniques at the Wikipedia page of hashtables [@wikipedia_hashtables].\n\n\n### Hashtables in Zig {#sec-hashmap}\n\nThe Zig Standard Library provides different implementations of a hashtable.\nEach implementation have its own cons and pros, which we will\ndiscuss later on, and all of them are available through the `std.hash_map` module.\n\nThe `HashMap` struct is a general-purpose hashtable,\nwhich have very fast operations (lookup, insertion, delete), and also,\nquite high load factors for low memory usage. You can create and provide a context object\nto the `HashMap` constructor. This context object allows you to tailor\nthe behaviour of the hashtable itself, because you can\nprovide a hash function implementation to be used by the hashtable\nthrough this context object.\n\nBut let's not worry about this context object now, because it is meant to be used\nby \"experts in the field of hashtables\". Since we are most likely not\nexperts in this field, we are going to take the easy way to create\na hashtable. Which is by using the `AutoHashMap()` function.\n\n\nThis `AutoHashMap()` function is essentially a \"create a hashtable object that uses the default settings\"\ntype of function. It automatically chooses a context object, and, therefore, a hash function implementation,\nfor you. This function receives two data types as input, the first input is the data type of the keys\nthat will be used in this hashtable, while the second input is the data type of the data that will be\nstored inside the hashtable, that is, the data type of the values to be stored.\n\nIn the example below, we are providing the data type `u32` in the first argument, and `u16` in the second argument of this\nfunction. This means that we are going to use `u32` values as keys in this hashtable, while `u16` values are the actual values\nthat are going to be stored into this hashtable.\nAt the end of this process, the `hash_table` object contains a `HashMap` object\nthat uses the default settings and context.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n    std.debug.print(\n        \"Value at key 50050: {d}\\n\",\n        .{hash_table.get(50050).?}\n    );\n\n    if (hash_table.remove(57709)) {\n        std.debug.print(\n            \"Value at key 57709 successfully removed!\\n\",\n            .{}\n        );\n    }\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n}\n```\n:::\n\n\n\n\n```\nN of values stored: 3\nValue at key 50050: 55\nValue at key 57709 successfully removed!\nN of values stored: 2\n```\n\nYou can add/put new values into the hashtable by using the `put()` method. The first argument\nis the key to be used, and the second argument is the actual value that you want to store inside\nthe hashtable. In the example below, we first add the value 89 using the key 54321, next, we add\nthe value 55 using the key 50050, etc.\n\nNotice that we have used the method `count()` to see how many values are currently stored in the\nhashtable. After that, we also use the `get()` method to access (or look) at the value stored in\nthe position identified by the key 500050. The output of this `get()` method is an optional value.\nThis is why we use the `?` method at the end to get the actual value.\n\nAlso notice that we can remove (or delete) values from the hashtable by using the `remove()` method.\nYou provide the key that identifies the value that you want to delete, then, the method will\ndelete this value and return a `true` value as output. This `true` value essentially tells us\nthat the method successfully deleted the value.\n\nBut this delete operation might not be always successful. For example, you might provide the wrong\nkey to this method. I mean, maybe you provide\n(either intentionally or unintentionally) a key that points to an empty bucket,\ni.e. a bucket that still doesn't have a value in it.\nIn this case, the `remove()` method would return a `false` value.\n\n\n\n### Iterating through the hashtable\n\nIterating through the keys and values that are currently being stored in\nthe hashtable is a very common necessity.\nYou can do that in Zig by using an iterator object that can iterate\nthrough the elements of your hashtable object.\n\nThis iterator object works like any other iterator object that you would\nfind in languages such as C++ and Rust. It is basically a pointer object\nthat points to some value in the container, and has a `next()` method\nthat you can use to navigate (or iterate) through the values in the\ncontainer.\n\nYou can create such iterator object by using the `iterator()` method of the hashtable object.\nThis method returns an iterator object, from which you can use the `next()` method in conjunction\nwith a while loop to iterate through the elements of your hashtable. The `next()` method returns an optional\n`Entry` value, and therefore, you must unwrap this optional value to get the actual `Entry` value\nfrom which you can access the key and also the value identified by this key.\n\nWith this `Entry` value at hand, you can access the key of this current entry by using the `key_ptr`\nattribute and dereferencing the pointer that lives inside of it, while the value identified by this\nkey is accessed through the `value_ptr` attribute instead, which is also a pointer to be dereferenced.\nThe code example below demonstrates the use of these elements:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n\n    var it = hash_table.iterator();\n    while (it.next()) |kv| {\n        // Access the current key\n        std.debug.print(\"Key: {d} | \", .{kv.key_ptr.*});\n        // Access the current value\n        std.debug.print(\"Value: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nKey: 54321 | Value: 89Key: 50050 | Value: 55Key: 5\n  57709 | Value: 41\n```\n\n\n:::\n:::\n\n\n\n\n```\nKey: 54321 | Value: 89\nKey: 50050 | Value: 55\nKey: 57709 | Value: 41\n```\n\n\nIf you want to iterate specifically through the values or the keys of your hashtable,\nyou can create a key iterator or a value iterator object. These are also iterator\nobjects, which have the same `next()` method that you can use to iterate through the\nhashtable.\n\nKey iterators are created from the `keyIterator()` method of your\nhashtable object, while value iterators are created from the `valueIterator()` method.\nAll you have to do is to unwrap the value from the `next()` method and deference it\ndirectly to access the key or the value that you are iterating over.\nThe code example below demonstrates the use of a key iterator,\nbut you can replicate the same logic to a value iterator.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar kit = hash_table.keyIterator();\nwhile (kit.next()) |key| {\n    std.debug.print(\"Key: {d}\\n\", .{key.*});\n}\n```\n:::\n\n\n\n\n```\nKey: 54321\nKey: 50050\nKey: 57709\n```\n\n\n### The `ArrayHashMap` hashtable {#sec-array-map}\n\nIf you need to iterate through the elements of your hashtable constantly,\nyou might want to use the `ArrayHashMap` struct for your specific case,\ninstead of going with the usual and general-purpose `HashMap` struct.\n\nThe `ArrayHashMap` struct creates a hashtable that is faster to iterate over.\nThat is why this specific type of hashtable might be valuable to you.\nSome other properties of a `ArrayHashMap` hashtable are:\n\n- the order of insertion is preserved, i.e. the order of the values that you find while iterating through this hashtable is actually the order in which these values were inserted in the hashtable.\n- the key-value pairs are stored sequentially, one after another.\n\n\nYou can create an `ArrayHashMap` object by using, once again, a helper function that\nchooses automatically for you a hash function implementation. This is the\n`AutoArrayHashMap()` function, which works very similarly to the `AutoHashMap()`\nfunction that we presented at @sec-hashmap.\n\nYou provide two data types to this function. The data type of the keys that will be\nused in this hashtable, and the data type of the values that will be stored in\nthis hashtable.\n\nAn `ArrayHashMap` object have essentially the exact same methods from the `HashMap` struct.\nSo you can insert new values into the hashtable by using the `put()` method, and you can look (or get)\na value from the hashtable by using the `get()` method. But the `remove()` method is not available\nin this specific type of hashtable.\n\nIn order to delete values from the hashtable, you would use the same methods that you find in\nan `ArrayList` object, i.e. a dynamic array. I presented these methods at @sec-dynamic-array-remove,\nwhich are the `swapRemove()` and `orderedRemove()` methods. These methods have the same meaning here, or,\nthe same effect that they have in an `ArrayList` object.\n\nThis means that, with `swapRemove()` you remove the value from the hashtable, but you do not preserve\nthe order in which the values were inserted into the structure. While `orderedRemove()` is able\nto retain the order in which these values were inserted.\n\nBut instead of providing an index as input to `swapRemove()` or `orderedRemove()`, like I described\nat @sec-dynamic-array-remove, these methods here in an `ArrayHashMap` take a key as input, like\nthe `remove()` method from a `HashMap` object. If you want to provide an index as input, instead\nof a key, you should use the `swapRemoveAt()` and `orderedRemoveAt()` methods.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar hash_table = AutoArrayHashMap(u32, u16)\n    .init(allocator);\ndefer hash_table.deinit();\n```\n:::\n\n\n\n\n\n\n### The `StringHashMap` hashtable {#sec-string-hash-map}\n\nOne thing that you will notice in the other two types of hashtables that I have\npresented over the last sections, is that neither of them accepts a slice data type\nin their keys.\nWhat this means is that you cannot use a slice value to represent a key in\nthese types of hashtable.\n\nThe most obvious consequence of this, is that you cannot use strings as keys\nin these hashtables. But it is extremely common to use strings as keys\nin hashtables.\n\nTake this very simple Javascript code snippet as an example. We are creating\na simple hashtable object named `people`. Then, we add a new entry to this\nhashtable, which is identified by the string `'Pedro'`. This string is the\nkey in this case, while the object containing different personal information such as\nage, height and city, is the value to be stored in the hashtable.\n\n```js\nvar people = new Object();\npeople['Pedro'] = {\n    'age': 25,\n    'height': 1.67,\n    'city': 'Belo Horizonte'\n};\n```\n\nThis pattern of using strings as keys is very common in\nall sorts of situations. That is why the Zig Standard Library offers a\nspecific type of hashtable for this purpose, which is created through the `StringHashMap()` function.\nThis function creates a hashtable that uses strings as keys. The only input of this\nfunction is the data type of the values that will be stored into this hashtable.\n\nIn the example below, I'm creating a hashtable to store the ages of different people.\nEach key in this hashtable is represented by the name of each person, while the value stored in the\nhashtable is the age of this person identified by the key.\n\nThat is why I provide the `u8` data type (which is the data type used by the age values) as input to this `StringHashMap()` function.\nAs the result, it creates a hashtable that uses string values as keys, and, that stores\n`u8` values in it. Notice that an allocator object is provided at the `init()` method of the\nresulting object from the `StringHashMap()` function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var ages = std.StringHashMap(u8).init(allocator);\n    defer ages.deinit();\n\n    try ages.put(\"Pedro\", 25);\n    try ages.put(\"Matheus\", 21);\n    try ages.put(\"Abgail\", 42);\n\n    var it = ages.iterator();\n    while (it.next()) |kv| {\n        std.debug.print(\"Key: {s} | \", .{kv.key_ptr.*});\n        std.debug.print(\"Age: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n:::\n\n\n\n\n```\nKey: Pedro | Age: 25\nKey: Abgail | Age: 42\nKey: Matheus | Age: 21\n```\n\n\n### The `StringArrayHashMap` hashtable\n\nThe Zig Standard Library also provides a type of hashtable that mix the cons and pros of the\n`StringHashMap` and `ArrayHashMap` together. That is, a hashtable\nthat uses strings as keys, but also have the advantages from `ArrayHashMap`.\nIn other words, you can have a hashtable that is fast to iterate over,\nthat preserves insertion order, and also, that uses strings as keys.\n\nYou can create such type of hashtable by using the `StringArrayHashMap()` function.\nThis function accepts a data type as input, which is the data type of the values that are\ngoing to be stored inside this hashtable, in the same style as the function presented\nat @sec-string-hash-map.\n\nYou can insert new values into this hashtable by using the same `put()` method that\nwe have discussed at @sec-string-hash-map. And you can also get values from the hashtable\nby using the same `get()` method.\nLike its `ArrayHashMap` brother, to delete values from this specific type of hashtable,\nwe also use the `orderedRemove()` and `swapRemove()` methods, with the same effects that\nI have described at @sec-array-map.\n\nIf we take the code example that was exposed at @sec-string-hash-map, we can\nachieve the exact same result with `StringArrayHashMap()`:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar ages = std.StringArrayHashMap(u8).init(allocator);\n```\n:::\n\n\n\n\n\n\n\n## Linked lists\n\nThe Zig Standard Library provides an implementation for both singly and doubly linked lists.\nA linked list is a linear data structure that looks like a chain, or, a rope.\nThe main advantage of this data structure is that you normally have very fast\ninsertion and deletion operations. But, as a disadvantage, iterating through\nthis data structure is usually not so fast as iterating through an array.\n\nThe idea behind a linked list is to build a structure that consists of a sequence of nodes\nconnected to each other by pointers. This means that linked lists are usually not contiguous\nin memory, because each node might be anywhere in memory. They do not need to be close to\none another.\n\nAt @fig-linked-list we can see a diagram of a singly linked list. We begin at the first node\n(which is usually called \"the head of the linked list\"). Then, from this\nfirst node we uncover the remaining nodes in the structure, by following the locations pointed\nby the pointers found in each node.\n\nEach node has two things in it. It has the value that is stored in the current node\n, and also, a pointer. This pointer points to the next node in the list. If this pointer\nis null, then, it means that we have reached the end of our linked list.\n\n![A diagram of a singly linked list.](./../Figures/linked-list.png){#fig-linked-list}\n\n\nAt @fig-linked-list2 we can see a diagram of a doubly linked list. The only thing that really\nchanges now is that every node in the linked list has both a pointer to the previous node,\nand, a pointer to the next node. So every node in a doubly linked list has two pointers in it. These are\nusually called the `prev` (for \"previous\") and the `next` (for \"next\") pointers of the node.\n\nIn the singly linked list example, we had only one single pointer in each node, and this singular\npointer was always pointing to the next node in the sequence. This means that singly linked lists\nnormally have only the `next` pointer in them.\n\n![A diagram of a doubly linked list.](./../Figures/doubly-linked-list.png){#fig-linked-list2}\n\n\nLinked lists are available in Zig through the functions `SinglyLinkedList()` and\n`DoublyLinkedList()`, for \"singly linked lists\" and \"doubly linked lists\", respectively. These functions are\nactually generic functions, which we are going to talk more about at @sec-generic-fun.\n\nFor now, just understand that, in order to create a linked list object,\nwe begin by providing a data type to these functions. This data type defines\nthe type of data that each node in this linked list will store. In the example below,\nwe are creating a singly linked list of `u32` values.\nSo each node in this linked list will store a `u32` value.\n\nBoth the `SinglyLinkedList()` and `DoublyLinkedList()` functions returns a type,\ni.e. a struct definition, as output. Therefore, the object `Lu32` is actually\na struct definition. It defines the type \"singly linked list of `u32` values\".\n\nNow that we have the definition of the struct, we need to instantiate a `Lu32` object.\nWe normally instantiate struct objects in Zig by using an `init()` method.\nBut in this case, we are instantiating the struct directly, by using an empty\n`struct` literal, in the expression `Lu32{}`.\n\nIn this example, we first create multiple node objects, and after we create them,\nwe start to insert and connect these nodes to build the linked list, using the\n`prepend()` and `insertAfter()` methods. Notice that the `prepend()` method\nis a method from the linked list object, while the `insertAfter()` is a method\npresent in the node objects.\n\nIn essence, the `prepend()` method inserts a node at the beginning of the linked\nlist. In other words, the node that you provide to this method, becomes the new\n\"head node\" of the linked list. It becomes the first node in the list (see @fig-linked-list).\n\nOn the other side, the `insertAfter()` method is used to basically connect two nodes together.\nWhen you provide a node to this method, it creates a pointer to this input node,\nand stores this pointer in the `next` attribute of the current node, from which the method was called from.\n\nBecause doubly linked lists have both a `next` and a `prev` attributes in each node\n(as described at @fig-linked-list2), a node object created from\na `DoublyLinkedList` object have both an `insertBefore()` (for `prev`)\nand an `insertAfter()` (for `next`) methods available.\n\nThus, if we have used a doubly linked list, we can use the `insertBefore()` method\nto store the pointer to the input node in the `prev` attribute. This would put the input\nnode as the \"previous node\", or, the node before the current node. In contrast, the `insertAfter()` method\nputs the pointer created to the input node in the `next` attribute of the current node,\nand as result, the input node becomes the \"next node\" of the current node.\n\nSince we are using a singly linked list in this example, we have only the `insertAfter()` method\navailable in the node objects that we create from our `Lu32` type.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SinglyLinkedList = std.SinglyLinkedList;\nconst Lu32 = SinglyLinkedList(u32);\n\npub fn main() !void {\n    var list = Lu32{};\n    var one = Lu32.Node{ .data = 1 };\n    var two = Lu32.Node{ .data = 2 };\n    var three = Lu32.Node{ .data = 3 };\n    var four = Lu32.Node{ .data = 4 };\n    var five = Lu32.Node{ .data = 5 };\n\n    list.prepend(&two); // {2}\n    two.insertAfter(&five); // {2, 5}\n    list.prepend(&one); // {1, 2, 5}\n    two.insertAfter(&three); // {1, 2, 3, 5}\n    three.insertAfter(&four); // {1, 2, 3, 4, 5}\n}\n```\n:::\n\n\n\n\n\nThere are other methods available from the linked list object, depending if this object is\na singly linked list or a doubly linked list, that might be very useful for you. You can find a\nsummary of them in the bullet points below:\n\n- `remove()` to remove a specific node from the linked list.\n- if singly linked list, `len()` to count how many nodes there is in the linked list.\n- if doubly linked list, checkout the `len` attribute to see how many nodes there is in the linked list.\n- if singly linked list, `popFirst()` to remove the first node (i.e. the \"head\") from the linked list.\n- if doubly linked list, `pop()` and `popFirst()` to remove the last and first nodes from the linked list, respectively.\n- if doubly linked list, `append()` to add a new node to end of the linked list (i.e. inverse of `prepend()`).\n\n\n\n## Multi array structure\n\nZig introduces a new data structure called `MultiArrayList()`. It is a different version of the dynamic array\nthat we have introduced at @sec-dynamic-array. The difference between this structure and the `ArrayList()`\nthat we know from @sec-dynamic-array, is that `MultiArrayList()` creates a separate dynamic array\nfor each field of the struct that you provide as input.\n\nConsider the following code example. We create a new custom struct called `Person`. This\nstruct contains three different data members, or, three different fields. As consequence,\nwhen we provide this `Person` data type as input to `MultiArrayList()`, this\ncreates a \"struct of three different arrays\" called `PersonArray`. In other words,\nthis `PersonArray` is a struct that contains three internal dynamic arrays in it.\nOne array for each field found in the `Person` struct definition.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Person = struct {\n    name: []const u8,\n    age: u8,\n    height: f32,\n};\nconst PersonArray = std.MultiArrayList(Person);\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var people = PersonArray{};\n    defer people.deinit(allocator);\n\n    try people.append(allocator, .{\n        .name = \"Auguste\", .age = 15, .height = 1.54\n    });\n    try people.append(allocator, .{\n        .name = \"Elena\", .age = 26, .height = 1.65\n    });\n    try people.append(allocator, .{\n        .name = \"Michael\", .age = 64, .height = 1.87\n    });\n}\n```\n:::\n\n\n\n\nIn other words, instead of creating an array of \"persons\", the `MultiArrayList()` function\ncreates a \"struct of arrays\". Each data member of this struct is a different array that stores\nthe values of a specific field from the `Person` values that were added (or, appended) to this \"struct of arrays\".\nOne important detail is that each of these separate internal arrays stored inside `PersonArray`\nare dynamic arrays. This means that these arrays can grow in capacity automatically as needed, to accomodate\nmore values.\n\nThe @fig-multi-array exposed below presents a diagram that describes the `PersonArray` struct\nthat we have created in the previous code example. Notice that the values of the data members\npresent in each of the three `Person` values that we have appended into the `PersonArray` object\n, are scattered across three different internal arrays of the `PersonArray` object.\n\n![A diagram of the `PersonArray` struct.](./../Figures/multi-array.png){#fig-multi-array}\n\nYou can easily access each of these arrays separately, and iterate over the values of each array.\nFor that, you will need to call the `items()` method from the `PersonArray` object, and provide as input\nto this method, the name of the field that you want to iterate over.\nIf you want to iterate through the `.age` array for example, then, you need to call `items(.age)` from\nthe `PersonArray` object, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (people.items(.age)) |*age| {\n    try stdout.print(\"Age: {d}\\n\", .{age.*});\n}\n```\n:::\n\n\n\n\n```\nAge: 15\nAge: 26\nAge: 64\n```\n\n\nIn the above example, we are iterating over the values of the `.age` array, or,\nthe internal array of the `PersonArray` object that contains the values of the `age`\ndata member from the `Person` values that were added to the multi array struct.\n\nIn this example we are calling the `items()` method directly from the `PersonArray`\nobject. However, it is recommended on most situations to call this `items()` method\nfrom a \"slice object\", which you can create from the `slice()` method.\nThe reason for this is that calling `items()` multiple times have better performance\nif you use a slice object.\n\nTherefore, if you are planning to access only one of the\ninternal arrays from your \"multi array struct\", it is fine to call `items()` directly\nfrom the multi array object. But if you need to access many of the internal arrays\nfrom your \"multi array struct\", then, you will likely need to call `items()` more\nthan once, and, in such circumstance, is better to call `items()` through a slice object.\nThe example below demonstrates the use of such object:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar slice = people.slice();\nfor (slice.items(.age)) |*age| {\n    age.* += 10;\n}\nfor (slice.items(.name), slice.items(.age)) |*n,*a| {\n    try stdout.print(\n        \"Name: {s}, Age: {d}\\n\", .{n.*, a.*}\n    );\n}\n```\n:::\n\n\n\n\n```\nName: Auguste, Age: 25\nName: Elena, Age: 36\nName: Michael, Age: 74\n```\n\n\n## Conclusion\n\nThere are many other data structures that I haven't presented here.\nBut you can check them out at the official Zig Standard Library documentation page.\nActually, when you get into the [homepage of the documentation](https://ziglang.org/documentation/master/std/#)[^home], the first thing\nthat appears to you in this page, is a list of types and data structures that\nare available in the Zig Standard Library.\nThere are some very specific data structures in this list, like a\n[`BoundedArray` struct](https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray)[^bounded]\n, but there is also some more general structures, such as a\n[`PriorityQueue` struct](https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue)[^priority].\n\n\n[^home]: <https://ziglang.org/documentation/master/std/#>\n[^priority]: <https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue>.\n[^bounded]: <https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray>\n\n\n\n\n\n\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/09-error-handling/execute-results/html.json b/_freeze/Chapters/09-error-handling/execute-results/html.json
index cd40a1d4..a655e2a5 100644
--- a/_freeze/Chapters/09-error-handling/execute-results/html.json
+++ b/_freeze/Chapters/09-error-handling/execute-results/html.json
@@ -2,10 +2,8 @@
   "hash": "0e6b825195db1ba992b740206fa34ec0",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Error handling and unions {#sec-error-handling}\n\nIn this chapter, I want to discuss how error handling is done in Zig.\nWe already briefly learned about one of the available strategies to handle errors in Zig,\nwhich is the `try` keyword presented at @sec-main-file. But we still haven't learned about\nthe other methods, such as the `catch` keyword.\nI also want to discuss in this chapter how union types are created in Zig.\n\n## Learning more about errors in Zig\n\nBefore we get into how error handling is done, we need to learn more about what errors are in Zig.\nAn error is actually a value in Zig [@zigoverview]. In other words, when an error occurs inside your Zig program,\nit means that somewhere in your Zig codebase, an error value is being generated.\nAn error value is similar to any integer value that you create in your Zig code.\nYou can take an error value and pass it as input to a function,\nand you can also cast (or coerce) it into a different type of an error value.\n\nThis have some similarities with exceptions in C++ and Python.\nBecause in C++ and Python, when an exception happens inside a `try` block,\nyou can use a `catch` block (in C++) or an `except` block (in Python)\nto capture the exception produced in the `try` block,\nand pass it to functions as an input.\n\nHowever, error values in Zig are treated very differently than exceptions.\nFirst, you cannot ignore error values in your Zig code. Meaning that, if an error\nvalue appears somewhere in your source code, this error value must be explicitly handled in some way.\nThis also means that you cannot discard error values by assigning them to an underscore,\nas you could do with normal values and objects.\n\nTake the source code below as an example. Here we are trying to open a file that does not exist\nin my computer, and as a result, an obvious error value of `FileNotFound` is returned from the `openFile()`\nfunction. But because I'm assigning the result of this function to an underscore, I end up\ntrying to discard an error value.\n\nThe `zig` compiler detects this mistake, and raises a compile\nerror telling me that I'm trying to discard an error value.\nIt also adds a note message that suggests the use of `try`,\n`catch` or an if statement to explicitly handle this error value\nThis note is reinforcing that every possible error value must be explicitly handled in Zig.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst dir = std.fs.cwd();\n_ = dir.openFile(\"doesnt_exist.txt\", .{});\n```\n:::\n\n\n\n\n```\nt.zig:8:17: error: error set is discarded\nt.zig:8:17: note: consider using 'try', 'catch', or 'if'\n```\n\n\n### Returning errors from functions\n\nAs we described at @sec-main-file, when we have a function that might return an error\nvalue, this function normally includes an exclamation mark (`!`) in its return type\nannotation. The presence of this exclamation mark indicates that this function might\nreturn an error value as result, and, the `zig` compiler forces you to always handle explicitly\nthe case of this function returning an error value.\n\nTake a look at the `print_name()` function below. This function might return an error in the `stdout.print()` function call,\nand, as a consequence, its return type (`!void`) includes an exclamation mark in it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_name() !void {\n    const stdout = std.getStdOut().writer();\n    try stdout.print(\"My name is Pedro!\", .{});\n}\n```\n:::\n\n\n\n\nIn the example above, we are using the exclamation mark to tell the `zig` compiler\nthat this function might return some error. But which error exactly is returned from\nthis function? For now, we are not specifying a specific error value. We only\nknown for now that some error value (whatever it is) might be returned.\n\nBut in fact, you can (if you want to) specify clearly which exact error values\nmight be returned from this function. There are lot of examples of\nthis in the Zig Standard Library. Take this `fill()` function from\nthe `http.Client` module as an example. This function returns\neither a error value of type `ReadError`, or `void`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn fill(conn: *Connection) ReadError!void {\n    // The body of this function ...\n}\n```\n:::\n\n\n\n\nThis idea of specifying the exact error values that you expect to be returned\nfrom the function is interesting. Because they automatically become some sort of documentation\nof your function, and also, it allows the `zig` compiler to perform some extra checks over\nyour code. Because it can check if there is any other type of error value\nthat is being generated inside your function, and, that it is not being accounted\nfor in this return type annotation.\n\nAnyway, you can list the types of errors that can be returned from the function\nby listing them on the left side of the exclamation mark. While the valid values\nstay on the right side of the exclamation mark. So the syntax format become:\n\n```\n<error-value>!<valid-value>\n```\n\n\n### Error sets\n\nBut what about when we have a single function that might return different types of errors?\nWhen you have such a function, you can list\nall of these different types of errors that can be returned from this function,\nthrough a structure in Zig that we call of an *error set*.\n\nAn error set is a special case of an union type. It is an union that contains error values in it.\nNot all programming languages have a notion of an \"union object\".\nBut in summary, an union is just a set of data types.\nUnions are used to allow an object to have multiple data types.\nFor example, a union of `x`, `y` and `z`, means that\nan object can be either of type `x`, or type `y` or type `z`.\n\nWe are going to talk in more depth about unions at @sec-unions.\nBut you can write an error set by writing the keyword `error` before\na pair of curly braces, then you list the error values that can be\nreturned from the function inside this pair of curly braces.\n\nTake the `resolvePath()` function below as an example, which comes from the\n`introspect.zig` module of the Zig Standard Library. We can see in its return type annotation, that this\nfunction return either: 1) a valid slice of `u8` values (`[]u8`); or, 2) one of the three different\ntypes of error values listed inside the error set (`OutOfMemory`, `Unexpected`, etc.).\nThis is an usage example of an error set.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn resolvePath(\n    ally: mem.Allocator,\n    p: []const u8,\n) error{\n    OutOfMemory,\n    CurrentWorkingDirectoryUnlinked,\n    Unexpected,\n}![]u8 {\n    // The body of the function ...\n}\n```\n:::\n\n\n\n\n\nThis is a valid way of annotating the return value of a Zig function. But, if you navigate through\nthe modules that composes the Zig Standard Library, you will notice that, for the majority of cases,\nthe programmers prefer to give a descriptive name to this error set, and then, use this name (or this \"label\")\nof the error set in the return type annotation, instead of using the error set directly.\n\nWe can see that in the `ReadError` error set that we showed earlier in the `fill()` function,\nwhich is defined in the `http.Client` module.\nSo yes, I presented the `ReadError` as if it was just a standard and single error value, but in fact,\nit is an error set defined in the `http.Client` module, and therefore, it actually represents\na set of different error values that might happen inside the `fill()` function.\n\n\nTake a look at the `ReadError` definition reproduced below. Notice that we are grouping all of these\ndifferent error values into a single object, and then, we use this object into the return type annotation of the function.\nLike the `fill()` function that we showed earlier, or, the `readvDirect()` function from the same module,\nwhich is reproduced below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const ReadError = error{\n    TlsFailure,\n    TlsAlert,\n    ConnectionTimedOut,\n    ConnectionResetByPeer,\n    UnexpectedReadFailure,\n    EndOfStream,\n};\n// Some lines of code\npub fn readvDirect(\n        conn: *Connection,\n        buffers: []std.posix.iovec\n    ) ReadError!usize {\n    // The body of the function ...\n}\n```\n:::\n\n\n\n\nSo, an error set is just a convenient way of grouping a set of\npossible error values into a single object, or a single type of an error value.\n\n\n### Casting error values\n\nLet's suppose you have two different error sets, named `A` and `B`.\nIf error set `A` is a superset of error set `B`, then, you can cast (or coerce)\nerror values from `B` into error values of `A`.\n\nError sets are just a set of error values. So, if the error set `A`\ncontains all error values from the error set `B`, then `A`\nbecomes a superset of `B`. You could also say\nthat the error set `B` is a subset of error set `A`.\n\nThe example below demonstrates this idea. Because `A` contains all\nvalues from `B`, `A` is a superset of `B`.\nIn math notation, we would say that $A \\supset B$.\nAs a consequence, we can give an error value from `B` as input to the `cast()`\nfunction, and, implicitly cast this input into the same error value, but from the `A` set.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst A = error{\n    ConnectionTimeoutError,\n    DatabaseNotFound,\n    OutOfMemory,\n    InvalidToken,\n};\nconst B = error {\n    OutOfMemory,\n};\n\nfn cast(err: B) A {\n    return err;\n}\n\ntest \"coerce error value\" {\n    const error_value = cast(B.OutOfMemory);\n    try std.testing.expect(\n        error_value == A.OutOfMemory\n    );\n}\n```\n:::\n\n\n\n\n\n## How to handle errors\n\nNow that we learned more about what errors are in Zig,\nlet's discuss the available strategies to handle these errors,\nwhich are:\n\n- `try` keyword;\n- `catch` keyword;\n- an if statement;\n- `errdefer` keyword;\n\n\n\n### What `try` means?\n\nAs I described over the previous sections, when we say that an expression might\nreturn an error, we are basically referring to an expression that have\na return type in the format `!T`.\nThe `!` indicates that this expression returns either an error value, or a value of type `T`.\n\nAt @sec-main-file, I presented the `try` keyword and where to use it.\nBut I did not talked about what exactly this keyword does to your code,\nor, in other words, I have not explained yet what `try` means in your code.\n\nIn essence, when you use the `try` keyword in an expression, you are telling\nthe `zig` compiler the following: \"Hey! Execute this expression for me,\nand, if this expression return an error, please, return this error for me\nand stop the execution of my program. But if this expression return a valid\nvalue, then, return this value, and move on\".\n\nIn other words, the `try` keyword is essentially, a strategy to enter in panic mode, and stop\nthe execution of your program in case an error occurs.\nWith the `try` keyword, you are telling the `zig` compiler, that stopping the execution\nof your program is the most reasonable strategy to take if an error occurs\nin that particular expression.\n\n### The `catch` keyword\n\nOk, now that we understand properly what `try` means, let's discuss `catch` now.\nOne important detail here, is that you can use `try` or `catch` to handle your errors,\nbut you **cannot use `try` and `catch` together**. In other words, `try` and `catch`\nare different and completely separate strategies in the Zig language.\n\nThis is uncommon, and different than what happens in other languages. Most\nprogramming languages that adopts the *try catch* pattern (such as C++, R, Python, Javascript, etc.), normally use\nthese two keywords together to form the complete logic to\nproperly handle the errors.\nAnyway, Zig tries a different approach in the *try catch* pattern.\n\nSo, we learned already about what `try` means, and we also known that both\n`try` and `catch` should be used alone, separate from each other. But\nwhat exactly `catch` do in Zig? With `catch`, we can construct a block of\nlogic to handle the error value, in case it happens in the current expression.\n\nLook at the code example below. Once again, we go back to the previous\nexample where we were trying to open a file that doesn't exist in my computer,\nbut this time, I use `catch` to actually implement a logic to handle the error, instead of\njust stopping the execution right away.\n\nMore specifically, in this example, I'm using a logger object to record some logs into\nthe system, before I return the error, and stop the execution of the program. For example,\nthis could be some part of the codebase of a complex system that I do not have full control over,\nand I want to record these logs before the program crashes, so that I can debug it later\n(e.g. maybe I cannot compile the full program, and properly debug it with a debugger. So, these logs might\nbe a valid strategy to surpass this barrier).\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst dir = std.fs.cwd();\nconst file = dir.openFile(\n    \"doesnt_exist.txt\", .{}\n) catch |err| {\n    logger.record_context();\n    logger.log_error(err);\n    return err;\n};\n```\n:::\n\n\n\n\n\nTherefore, we use `catch` to create a block of expressions that will handle the error.\nI can return the error value from this block of expressions, like I did in the above example,\nwhich, will make the program enter in panic mode, and, stop the execution.\nBut I could also, return a valid value from this block of code, which would\nbe stored in the `file` object.\n\nNotice that, instead of writing the keyword before the expression that might return the error,\nlike we do with `try`, we write `catch` after the expression. We can open the pair of pipes (`|`),\nwhich captures the error value returned by the expression, and makes\nthis error value available in the scope of the `catch` block as the object named `err`.\nIn other words, because I wrote `|err|` in the code, I can access the error value\nreturned by the expression, by using the `err` object.\n\nAlthough this being the most common use of `catch`, you can also use this keyword\nto handle the error in a \"default value\" style. That is, if the expression returns\nan error, we use the default value instead. Otherwise, we use the valid value returned\nby the expression.\n\nThe Zig official language reference, provides a great example of this \"default value\"\nstrategy with `catch`. This example is reproduced below. Notice that we are trying to parse\nsome unsigned integer from a string object named `str`. In other words, this function\nis trying to transform an object of type `[]const u8` (i.e. an array of characters, a string, etc.)\ninto an object of type `u64`.\n\nBut this parsing process done by the function `parseU64()` may fail, resulting in a runtime error.\nThe `catch` keyword used in this example provides an alternative value (13) to be used in case\nthis `parseU64()` function raises an error. So, the expression below essentially means:\n\"Hey! Please, parse this string into a `u64` for me, and store the results into the\nobject `number`. But, if an error occurs, then, use the value `13` instead\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number = parseU64(str, 10) catch 13;\n```\n:::\n\n\n\n\nSo, at the end of this process, the object `number` will contain either a `u64` integer\nthat was parsed successfully from the input string `str`, or, if an error occurs in the\nparsing process, it will contain the `u64` value `13` that was provided by the `catch`\nkeyword as the \"default\", or, the \"alternative\" value.\n\n\n\n### Using if statements\n\nNow, you can also use if statements to handle errors in your Zig code.\nIn the example below, I'm reproducing the previous example, where\nwe try to parse an integer value from an input string with a function\nnamed `parseU64()`.\n\nWe execute the expression inside the \"if\". If this expression returns an\nerror value, the \"if branch\" (or, the \"true branch\") of the if statement is not executed.\nBut if this expression returns a valid value instead, then, this value is unwrapped\ninto the `number` object.\n\nThis means that, if the `parseU64()` expression returns a valid value, this value becomes available\ninside the scope of this \"if branch\" (i.e. the \"true branch\") through the object that we listed inside the pair\nof pipe character (`|`), which is the object `number`.\n\nIf an error occurs, we can use an \"else branch\" (or the \"false branch\") of the if statement\nto handle the error. In the example below, we are using the `else` in the if statement\nto unwrap the error value (that was returned by `parseU64()`) into the `err` object,\nand handle the error.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (parseU64(str, 10)) |number| {\n    // do something with `number` here\n} else |err| {\n    // handle the error value.\n}\n```\n:::\n\n\n\n\nNow, if the expression that you are executing returns different types of error values,\nand you want to take a different action in each of these types of error values, the\n`try` and `catch` keywords, and the if statement strategy, becomes limited.\n\nFor this type of situation, the official documentation of the language suggests\nthe use of a switch statement together with an if statement [@zigdocs].\nThe basic idea is, to use the if statement to execute the expression, and\nuse the \"else branch\" to pass the error value to a switch statement, where\nyou define a different action for each type of error value that might be\nreturned by the expression executed in the if statement.\n\nThe example below demonstrates this idea. We first try to add (or register) a set of\ntasks to a queue. If this \"registration process\" occurs well, we then try\nto distribute these tasks across the workers of our system. But\nif this \"registration process\" returns an error value, we then use a switch\nstatement in the \"else branch\" to handle each possible error value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (add_tasks_to_queue(&queue, tasks)) |_| {\n    distribute_tasks(&queue);\n} else |err| switch (err) {\n    error.InvalidTaskName => {\n        // do something\n    },\n    error.TimeoutTooBig => {\n        // do something\n    },\n    error.QueueNotFound => {\n        // do something\n    },\n    // and all the other error options ...\n}\n```\n:::\n\n\n\n\n\n### The `errdefer` keyword {#sec-errdefer2}\n\nA common pattern in C programs in general, is to clean resources when an error occurs during\nthe execution of the program. In other words, one common way to handle errors, is to perform\n\"cleanup actions\" before we exit our program. This guarantees that a runtime error does not make\nour program to leak resources of the system.\n\n\nThe `errdefer` keyword is a tool to perform such \"cleanup actions\" in hostile situations.\nThis keyword is commonly used to clean (or to free) allocated resources, before the execution of our program\nget's stopped because of an error value being generated.\n\nThe basic idea is to provide an expression to the `errdefer` keyword. Then,\n`errdefer` executes this expression if, and only if, an error occurs\nduring the execution of the current scope.\nIn the example below, we are using an allocator object (that we have presented at @sec-allocators)\nto create a new `User` object. If we are successful in creating and registering this new user,\nthis `create_user()` function will return this new `User` object as its return value.\n\nHowever, if for some reason, an error value is generated by some expression\nthat is after the `errdefer` line, for example, in the `db.add(user)` expression,\nthe expression registered by `errdefer` get's executed before the error value is returned\nfrom the function, and before the program enters in panic mode and stops the\ncurrent execution.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn create_user(db: Database, allocator: Allocator) !User {\n    const user = try allocator.create(User);\n    errdefer allocator.destroy(user);\n\n    // Register new user in the Database.\n    _ = try db.register_user(user);\n    return user;\n}\n```\n:::\n\n\n\n\nBy using `errdefer` to destroy the `user` object that we have just created,\nwe guarantee that the memory allocated for this `user` object\nget's freed, before the execution of the program stops.\nBecause if the expression `try db.add(user)` returns an error value,\nthe execution of our program stops, and we lose all references and control over the memory\nthat we have allocated for the `user` object.\nAs a result, if we do not free the memory associated with the `user` object before the program stops,\nwe cannot free this memory anymore. We simply lose our chance to do the right thing.\nThat is why `errdefer` is essential in this situation.\n\nJust to state clearly the differences between `defer` and `errdefer`\n(which I described at @sec-defer and @sec-errdefer1), it might be worth\nto discuss the subject a bit further. You might still have the question\n\"why use `errdefer` if we can use `defer` instead?\" in your mind.\n\nAlthough being similar, the key difference between `errdefer` and `defer` keyword\nis when the provided expression get's executed.\nThe `defer` keyword always execute the provided expression at the end of the\ncurrent scope, no matter how your code exits this scope.\nIn contrast, `errdefer` executes the provided expression only when an error occurs in the\ncurrent scope.\n\nThis becomes important if a resource that you allocate in the\ncurrent scope get's freed later in your code, in a different scope.\nThe `create_user()` functions is an example of this. If you think\nclosely about this function, you will notice that this function returns\nthe `user` object as the result.\n\nIn other words, the allocated memory for the `user` object does not get\nfreed inside the `create_user()` function, if it returns successfully.\nSo, if an error does not occur inside this function, the `user` object\nis returned from the function, and probably, the code that runs after\nthis `create_user()` function will be responsible for freeing\nthe memory of the `user` object.\n\nBut what if an error occurs inside the `create_user()` function? What happens then?\nThis would mean that the execution of your code would stop in this `create_user()`\nfunction, and, as a consequence, the code that runs after this `create_user()`\nfunction would simply not run, and, as a result, the memory of the `user` object\nwould not be freed before your program stops.\n\nThis is the perfect scenario for `errdefer`. We use this keyword to guarantee\nthat our program will free the allocated memory for the `user` object,\neven if an error occurs inside the `create_user()` function.\n\nIf you allocate and free some memory for an object inside the same scope, then,\njust use `defer` and be happy, i.e. `errdefer` have no use for you in such situation.\nBut if you allocate some memory in a scope A, but you only free this memory\nlater, in a scope B for example, then, `errdefer` becomes useful to avoid leaking memory\nin sketchy situations.\n\n\n\n## Union type in Zig {#sec-unions}\n\nAn union type defines a set of types that an object can be. It is like a list of\noptions. Each option is a type that an object can assume. Therefore, unions in Zig\nhave the same meaning, or, the same role as unions in C. They are used for the same purpose.\nYou could also say that unions in Zig produces a similar effect to\n[using `typing.Union` in Python](https://docs.python.org/3/library/typing.html#typing.Union)[^pyunion].\n\n[^pyunion]: <https://docs.python.org/3/library/typing.html#typing.Union>\n\nFor example, you might be creating an API that sends data to a data lake, hosted\nin some private cloud infrastructure. Suppose you have created different structs in your codebase,\nto store the necessary information that you need, in order to connect to the services of\neach mainstream data lake service (Amazon S3, Azure Blob, etc.).\n\nNow, suppose you also have a function named `send_event()` that receives an event as input,\nand, a target data lake, and it sends the input event to the data lake specified in the\ntarget data lake argument. But this target data lake could be any of the three mainstream data lakes\nservices (Amazon S3, Azure Blob, etc.). Here is where an union can help you.\n\nThe union `LakeTarget` defined below allows the `lake_target` argument of `send_event()`\nto be either an object of type `AzureBlob`, or type `AmazonS3`, or type `GoogleGCP`.\nThis union allows the `send_event()` function to receive an object of any of these three types\nas input in the `lake_target` argument.\n\nRemember that each of these three types (`AmazonS3`, `GoogleGCP` and `AzureBlob`)\nare separate structs that we have defined in our source code. So, at first glance,\nthey are separate data types in our source code. But is the `union` keyword that\nunifies them into a single data type called `LakeTarget`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst LakeTarget = union {\n    azure: AzureBlob,\n    amazon: AmazonS3,\n    google: GoogleGCP,\n};\n\nfn send_event(\n    event: Event,\n    lake_target: LakeTarget\n) bool {\n    // body of the function ...\n}\n```\n:::\n\n\n\n\nAn union definition is composed by a list of data members. Each data member is of a specific data type.\nIn the example above, the `LakeTarget` union have three data members (`azure`, `amazon`, `google`).\nWhen you instantiate an object that uses an union type, you can only use one of its data members\nin this instantiation.\n\nYou could also interpret this as: only one data member of an union type can be activated at a time, the other data\nmembers remain deactivated and unaccessible. For example, if you create a `LakeTarget` object that uses\nthe `azure` data member, you can no longer use or access the data members `google` or `amazon`.\nIt is like if these other data members didn't exist at all in the `LakeTarget` type.\n\nYou can see this logic in the example below. Notice that, we first instantiate the union\nobject using the `azure` data member. As a result, this `target` object contains only\nthe `azure` data member inside of it. Only this data member is active in this object.\nThat is why the last line in this code example is invalid. Because we are trying to instantiate the data member\n`google`, which is currently inactive for this `target` object, and as a result, the program\nenters in panic mode warning us about this mistake through a loud error message.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar target = LakeTarget {\n    .azure = AzureBlob.init()\n};\n// Only the `azure` data member exist inside\n// the `target` object, and, as a result, this\n// line below is invalid:\ntarget.google = GoogleGCP.init();\n```\n:::\n\n\n\n\n```\nthread 2177312 panic: access of union field 'google' while\n    field 'azure' is active:\n    target.google = GoogleGCP.init();\n          ^\n```\n\nSo, when you instantiate an union object, you must choose one of the data types (or, one of the data members)\nlisted in the union type. In the example above, I choose to use the `azure` data member, and, as a result,\nall other data members were automatically deactivated,\nand you can no longer use them after you instantiate the object.\n\nYou can activate another data member by completely redefining the entire enum object.\nIn the example below, I initially use the `azure` data member. But then, I redefine the\n`target` object to use a new `LakeTarget` object, which uses the `google` data member.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar target = LakeTarget {\n    .azure = AzureBlob.init()\n};\ntarget = LakeTarget {\n    .google = GoogleGCP.init()\n};\n```\n:::\n\n\n\n\nA curious fact about union types, is that, at first, you cannot use them in switch statements (which were presented at @sec-switch).\nIn other words, if you have an object of type `LakeTarget` for example, you cannot give this object\nas input to a switch statement.\n\nBut what if you really need to do so? What if you actually need to\nprovide an \"union object\" to a switch statement? The answer to this question relies on another special type in Zig,\nwhich are the *tagged unions*. To create a tagged union, all you have to do is to add\nan enum type into your union declaration.\n\nAs an example of a tagged union in Zig, take the `Registry` type exposed\nbelow. This type comes from the\n[`grammar.zig` module](https://github.com/ziglang/zig/blob/30b4a87db711c368853b3eff8e214ab681810ef9/tools/spirv/grammar.zig)[^grammar]\nfrom the Zig repository. This union type lists different types of registries.\nBut notice this time, the use of `(enum)` after the `union` keyword. This is what makes\nthis union type a tagged union. By being a tagged union, an object of this `Registry` type\ncan be used as input in a switch statement. This is all you have to do. Just add `(enum)`\nto your `union` declaration, and you can use it in switch statements.\n\n[^grammar]: <https://github.com/ziglang/zig/blob/30b4a87db711c368853b3eff8e214ab681810ef9/tools/spirv/grammar.zig>.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const Registry = union(enum) {\n    core: CoreRegistry,\n    extension: ExtensionRegistry,\n};\n```\n:::\n",
-    "supporting": [
-      "09-error-handling_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Error handling and unions {#sec-error-handling}\n\nIn this chapter, I want to discuss how error handling is done in Zig.\nWe already briefly learned about one of the available strategies to handle errors in Zig,\nwhich is the `try` keyword presented at @sec-main-file. But we still haven't learned about\nthe other methods, such as the `catch` keyword.\nI also want to discuss in this chapter how union types are created in Zig.\n\n## Learning more about errors in Zig\n\nBefore we get into how error handling is done, we need to learn more about what errors are in Zig.\nAn error is actually a value in Zig [@zigoverview]. In other words, when an error occurs inside your Zig program,\nit means that somewhere in your Zig codebase, an error value is being generated.\nAn error value is similar to any integer value that you create in your Zig code.\nYou can take an error value and pass it as input to a function,\nand you can also cast (or coerce) it into a different type of an error value.\n\nThis have some similarities with exceptions in C++ and Python.\nBecause in C++ and Python, when an exception happens inside a `try` block,\nyou can use a `catch` block (in C++) or an `except` block (in Python)\nto capture the exception produced in the `try` block,\nand pass it to functions as an input.\n\nHowever, error values in Zig are treated very differently than exceptions.\nFirst, you cannot ignore error values in your Zig code. Meaning that, if an error\nvalue appears somewhere in your source code, this error value must be explicitly handled in some way.\nThis also means that you cannot discard error values by assigning them to an underscore,\nas you could do with normal values and objects.\n\nTake the source code below as an example. Here we are trying to open a file that does not exist\nin my computer, and as a result, an obvious error value of `FileNotFound` is returned from the `openFile()`\nfunction. But because I'm assigning the result of this function to an underscore, I end up\ntrying to discard an error value.\n\nThe `zig` compiler detects this mistake, and raises a compile\nerror telling me that I'm trying to discard an error value.\nIt also adds a note message that suggests the use of `try`,\n`catch` or an if statement to explicitly handle this error value\nThis note is reinforcing that every possible error value must be explicitly handled in Zig.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst dir = std.fs.cwd();\n_ = dir.openFile(\"doesnt_exist.txt\", .{});\n```\n:::\n\n\n\n\n```\nt.zig:8:17: error: error set is discarded\nt.zig:8:17: note: consider using 'try', 'catch', or 'if'\n```\n\n\n### Returning errors from functions\n\nAs we described at @sec-main-file, when we have a function that might return an error\nvalue, this function normally includes an exclamation mark (`!`) in its return type\nannotation. The presence of this exclamation mark indicates that this function might\nreturn an error value as result, and, the `zig` compiler forces you to always handle explicitly\nthe case of this function returning an error value.\n\nTake a look at the `print_name()` function below. This function might return an error in the `stdout.print()` function call,\nand, as a consequence, its return type (`!void`) includes an exclamation mark in it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_name() !void {\n    const stdout = std.getStdOut().writer();\n    try stdout.print(\"My name is Pedro!\", .{});\n}\n```\n:::\n\n\n\n\nIn the example above, we are using the exclamation mark to tell the `zig` compiler\nthat this function might return some error. But which error exactly is returned from\nthis function? For now, we are not specifying a specific error value. We only\nknown for now that some error value (whatever it is) might be returned.\n\nBut in fact, you can (if you want to) specify clearly which exact error values\nmight be returned from this function. There are lot of examples of\nthis in the Zig Standard Library. Take this `fill()` function from\nthe `http.Client` module as an example. This function returns\neither a error value of type `ReadError`, or `void`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn fill(conn: *Connection) ReadError!void {\n    // The body of this function ...\n}\n```\n:::\n\n\n\n\nThis idea of specifying the exact error values that you expect to be returned\nfrom the function is interesting. Because they automatically become some sort of documentation\nof your function, and also, it allows the `zig` compiler to perform some extra checks over\nyour code. Because it can check if there is any other type of error value\nthat is being generated inside your function, and, that it is not being accounted\nfor in this return type annotation.\n\nAnyway, you can list the types of errors that can be returned from the function\nby listing them on the left side of the exclamation mark. While the valid values\nstay on the right side of the exclamation mark. So the syntax format become:\n\n```\n<error-value>!<valid-value>\n```\n\n\n### Error sets\n\nBut what about when we have a single function that might return different types of errors?\nWhen you have such a function, you can list\nall of these different types of errors that can be returned from this function,\nthrough a structure in Zig that we call of an *error set*.\n\nAn error set is a special case of an union type. It is an union that contains error values in it.\nNot all programming languages have a notion of an \"union object\".\nBut in summary, an union is just a set of data types.\nUnions are used to allow an object to have multiple data types.\nFor example, a union of `x`, `y` and `z`, means that\nan object can be either of type `x`, or type `y` or type `z`.\n\nWe are going to talk in more depth about unions at @sec-unions.\nBut you can write an error set by writing the keyword `error` before\na pair of curly braces, then you list the error values that can be\nreturned from the function inside this pair of curly braces.\n\nTake the `resolvePath()` function below as an example, which comes from the\n`introspect.zig` module of the Zig Standard Library. We can see in its return type annotation, that this\nfunction return either: 1) a valid slice of `u8` values (`[]u8`); or, 2) one of the three different\ntypes of error values listed inside the error set (`OutOfMemory`, `Unexpected`, etc.).\nThis is an usage example of an error set.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn resolvePath(\n    ally: mem.Allocator,\n    p: []const u8,\n) error{\n    OutOfMemory,\n    CurrentWorkingDirectoryUnlinked,\n    Unexpected,\n}![]u8 {\n    // The body of the function ...\n}\n```\n:::\n\n\n\n\n\nThis is a valid way of annotating the return value of a Zig function. But, if you navigate through\nthe modules that composes the Zig Standard Library, you will notice that, for the majority of cases,\nthe programmers prefer to give a descriptive name to this error set, and then, use this name (or this \"label\")\nof the error set in the return type annotation, instead of using the error set directly.\n\nWe can see that in the `ReadError` error set that we showed earlier in the `fill()` function,\nwhich is defined in the `http.Client` module.\nSo yes, I presented the `ReadError` as if it was just a standard and single error value, but in fact,\nit is an error set defined in the `http.Client` module, and therefore, it actually represents\na set of different error values that might happen inside the `fill()` function.\n\n\nTake a look at the `ReadError` definition reproduced below. Notice that we are grouping all of these\ndifferent error values into a single object, and then, we use this object into the return type annotation of the function.\nLike the `fill()` function that we showed earlier, or, the `readvDirect()` function from the same module,\nwhich is reproduced below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const ReadError = error{\n    TlsFailure,\n    TlsAlert,\n    ConnectionTimedOut,\n    ConnectionResetByPeer,\n    UnexpectedReadFailure,\n    EndOfStream,\n};\n// Some lines of code\npub fn readvDirect(\n        conn: *Connection,\n        buffers: []std.posix.iovec\n    ) ReadError!usize {\n    // The body of the function ...\n}\n```\n:::\n\n\n\n\nSo, an error set is just a convenient way of grouping a set of\npossible error values into a single object, or a single type of an error value.\n\n\n### Casting error values\n\nLet's suppose you have two different error sets, named `A` and `B`.\nIf error set `A` is a superset of error set `B`, then, you can cast (or coerce)\nerror values from `B` into error values of `A`.\n\nError sets are just a set of error values. So, if the error set `A`\ncontains all error values from the error set `B`, then `A`\nbecomes a superset of `B`. You could also say\nthat the error set `B` is a subset of error set `A`.\n\nThe example below demonstrates this idea. Because `A` contains all\nvalues from `B`, `A` is a superset of `B`.\nIn math notation, we would say that $A \\supset B$.\nAs a consequence, we can give an error value from `B` as input to the `cast()`\nfunction, and, implicitly cast this input into the same error value, but from the `A` set.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst A = error{\n    ConnectionTimeoutError,\n    DatabaseNotFound,\n    OutOfMemory,\n    InvalidToken,\n};\nconst B = error {\n    OutOfMemory,\n};\n\nfn cast(err: B) A {\n    return err;\n}\n\ntest \"coerce error value\" {\n    const error_value = cast(B.OutOfMemory);\n    try std.testing.expect(\n        error_value == A.OutOfMemory\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file10459ffd0e21.test.coerce error value...OKA\n  All 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n## How to handle errors\n\nNow that we learned more about what errors are in Zig,\nlet's discuss the available strategies to handle these errors,\nwhich are:\n\n- `try` keyword;\n- `catch` keyword;\n- an if statement;\n- `errdefer` keyword;\n\n\n\n### What `try` means?\n\nAs I described over the previous sections, when we say that an expression might\nreturn an error, we are basically referring to an expression that have\na return type in the format `!T`.\nThe `!` indicates that this expression returns either an error value, or a value of type `T`.\n\nAt @sec-main-file, I presented the `try` keyword and where to use it.\nBut I did not talked about what exactly this keyword does to your code,\nor, in other words, I have not explained yet what `try` means in your code.\n\nIn essence, when you use the `try` keyword in an expression, you are telling\nthe `zig` compiler the following: \"Hey! Execute this expression for me,\nand, if this expression return an error, please, return this error for me\nand stop the execution of my program. But if this expression return a valid\nvalue, then, return this value, and move on\".\n\nIn other words, the `try` keyword is essentially, a strategy to enter in panic mode, and stop\nthe execution of your program in case an error occurs.\nWith the `try` keyword, you are telling the `zig` compiler, that stopping the execution\nof your program is the most reasonable strategy to take if an error occurs\nin that particular expression.\n\n### The `catch` keyword\n\nOk, now that we understand properly what `try` means, let's discuss `catch` now.\nOne important detail here, is that you can use `try` or `catch` to handle your errors,\nbut you **cannot use `try` and `catch` together**. In other words, `try` and `catch`\nare different and completely separate strategies in the Zig language.\n\nThis is uncommon, and different than what happens in other languages. Most\nprogramming languages that adopts the *try catch* pattern (such as C++, R, Python, Javascript, etc.), normally use\nthese two keywords together to form the complete logic to\nproperly handle the errors.\nAnyway, Zig tries a different approach in the *try catch* pattern.\n\nSo, we learned already about what `try` means, and we also known that both\n`try` and `catch` should be used alone, separate from each other. But\nwhat exactly `catch` do in Zig? With `catch`, we can construct a block of\nlogic to handle the error value, in case it happens in the current expression.\n\nLook at the code example below. Once again, we go back to the previous\nexample where we were trying to open a file that doesn't exist in my computer,\nbut this time, I use `catch` to actually implement a logic to handle the error, instead of\njust stopping the execution right away.\n\nMore specifically, in this example, I'm using a logger object to record some logs into\nthe system, before I return the error, and stop the execution of the program. For example,\nthis could be some part of the codebase of a complex system that I do not have full control over,\nand I want to record these logs before the program crashes, so that I can debug it later\n(e.g. maybe I cannot compile the full program, and properly debug it with a debugger. So, these logs might\nbe a valid strategy to surpass this barrier).\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst dir = std.fs.cwd();\nconst file = dir.openFile(\n    \"doesnt_exist.txt\", .{}\n) catch |err| {\n    logger.record_context();\n    logger.log_error(err);\n    return err;\n};\n```\n:::\n\n\n\n\n\nTherefore, we use `catch` to create a block of expressions that will handle the error.\nI can return the error value from this block of expressions, like I did in the above example,\nwhich, will make the program enter in panic mode, and, stop the execution.\nBut I could also, return a valid value from this block of code, which would\nbe stored in the `file` object.\n\nNotice that, instead of writing the keyword before the expression that might return the error,\nlike we do with `try`, we write `catch` after the expression. We can open the pair of pipes (`|`),\nwhich captures the error value returned by the expression, and makes\nthis error value available in the scope of the `catch` block as the object named `err`.\nIn other words, because I wrote `|err|` in the code, I can access the error value\nreturned by the expression, by using the `err` object.\n\nAlthough this being the most common use of `catch`, you can also use this keyword\nto handle the error in a \"default value\" style. That is, if the expression returns\nan error, we use the default value instead. Otherwise, we use the valid value returned\nby the expression.\n\nThe Zig official language reference, provides a great example of this \"default value\"\nstrategy with `catch`. This example is reproduced below. Notice that we are trying to parse\nsome unsigned integer from a string object named `str`. In other words, this function\nis trying to transform an object of type `[]const u8` (i.e. an array of characters, a string, etc.)\ninto an object of type `u64`.\n\nBut this parsing process done by the function `parseU64()` may fail, resulting in a runtime error.\nThe `catch` keyword used in this example provides an alternative value (13) to be used in case\nthis `parseU64()` function raises an error. So, the expression below essentially means:\n\"Hey! Please, parse this string into a `u64` for me, and store the results into the\nobject `number`. But, if an error occurs, then, use the value `13` instead\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number = parseU64(str, 10) catch 13;\n```\n:::\n\n\n\n\nSo, at the end of this process, the object `number` will contain either a `u64` integer\nthat was parsed successfully from the input string `str`, or, if an error occurs in the\nparsing process, it will contain the `u64` value `13` that was provided by the `catch`\nkeyword as the \"default\", or, the \"alternative\" value.\n\n\n\n### Using if statements\n\nNow, you can also use if statements to handle errors in your Zig code.\nIn the example below, I'm reproducing the previous example, where\nwe try to parse an integer value from an input string with a function\nnamed `parseU64()`.\n\nWe execute the expression inside the \"if\". If this expression returns an\nerror value, the \"if branch\" (or, the \"true branch\") of the if statement is not executed.\nBut if this expression returns a valid value instead, then, this value is unwrapped\ninto the `number` object.\n\nThis means that, if the `parseU64()` expression returns a valid value, this value becomes available\ninside the scope of this \"if branch\" (i.e. the \"true branch\") through the object that we listed inside the pair\nof pipe character (`|`), which is the object `number`.\n\nIf an error occurs, we can use an \"else branch\" (or the \"false branch\") of the if statement\nto handle the error. In the example below, we are using the `else` in the if statement\nto unwrap the error value (that was returned by `parseU64()`) into the `err` object,\nand handle the error.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (parseU64(str, 10)) |number| {\n    // do something with `number` here\n} else |err| {\n    // handle the error value.\n}\n```\n:::\n\n\n\n\nNow, if the expression that you are executing returns different types of error values,\nand you want to take a different action in each of these types of error values, the\n`try` and `catch` keywords, and the if statement strategy, becomes limited.\n\nFor this type of situation, the official documentation of the language suggests\nthe use of a switch statement together with an if statement [@zigdocs].\nThe basic idea is, to use the if statement to execute the expression, and\nuse the \"else branch\" to pass the error value to a switch statement, where\nyou define a different action for each type of error value that might be\nreturned by the expression executed in the if statement.\n\nThe example below demonstrates this idea. We first try to add (or register) a set of\ntasks to a queue. If this \"registration process\" occurs well, we then try\nto distribute these tasks across the workers of our system. But\nif this \"registration process\" returns an error value, we then use a switch\nstatement in the \"else branch\" to handle each possible error value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (add_tasks_to_queue(&queue, tasks)) |_| {\n    distribute_tasks(&queue);\n} else |err| switch (err) {\n    error.InvalidTaskName => {\n        // do something\n    },\n    error.TimeoutTooBig => {\n        // do something\n    },\n    error.QueueNotFound => {\n        // do something\n    },\n    // and all the other error options ...\n}\n```\n:::\n\n\n\n\n\n### The `errdefer` keyword {#sec-errdefer2}\n\nA common pattern in C programs in general, is to clean resources when an error occurs during\nthe execution of the program. In other words, one common way to handle errors, is to perform\n\"cleanup actions\" before we exit our program. This guarantees that a runtime error does not make\nour program to leak resources of the system.\n\n\nThe `errdefer` keyword is a tool to perform such \"cleanup actions\" in hostile situations.\nThis keyword is commonly used to clean (or to free) allocated resources, before the execution of our program\nget's stopped because of an error value being generated.\n\nThe basic idea is to provide an expression to the `errdefer` keyword. Then,\n`errdefer` executes this expression if, and only if, an error occurs\nduring the execution of the current scope.\nIn the example below, we are using an allocator object (that we have presented at @sec-allocators)\nto create a new `User` object. If we are successful in creating and registering this new user,\nthis `create_user()` function will return this new `User` object as its return value.\n\nHowever, if for some reason, an error value is generated by some expression\nthat is after the `errdefer` line, for example, in the `db.add(user)` expression,\nthe expression registered by `errdefer` get's executed before the error value is returned\nfrom the function, and before the program enters in panic mode and stops the\ncurrent execution.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn create_user(db: Database, allocator: Allocator) !User {\n    const user = try allocator.create(User);\n    errdefer allocator.destroy(user);\n\n    // Register new user in the Database.\n    _ = try db.register_user(user);\n    return user;\n}\n```\n:::\n\n\n\n\nBy using `errdefer` to destroy the `user` object that we have just created,\nwe guarantee that the memory allocated for this `user` object\nget's freed, before the execution of the program stops.\nBecause if the expression `try db.add(user)` returns an error value,\nthe execution of our program stops, and we lose all references and control over the memory\nthat we have allocated for the `user` object.\nAs a result, if we do not free the memory associated with the `user` object before the program stops,\nwe cannot free this memory anymore. We simply lose our chance to do the right thing.\nThat is why `errdefer` is essential in this situation.\n\nJust to state clearly the differences between `defer` and `errdefer`\n(which I described at @sec-defer and @sec-errdefer1), it might be worth\nto discuss the subject a bit further. You might still have the question\n\"why use `errdefer` if we can use `defer` instead?\" in your mind.\n\nAlthough being similar, the key difference between `errdefer` and `defer` keyword\nis when the provided expression get's executed.\nThe `defer` keyword always execute the provided expression at the end of the\ncurrent scope, no matter how your code exits this scope.\nIn contrast, `errdefer` executes the provided expression only when an error occurs in the\ncurrent scope.\n\nThis becomes important if a resource that you allocate in the\ncurrent scope get's freed later in your code, in a different scope.\nThe `create_user()` functions is an example of this. If you think\nclosely about this function, you will notice that this function returns\nthe `user` object as the result.\n\nIn other words, the allocated memory for the `user` object does not get\nfreed inside the `create_user()` function, if it returns successfully.\nSo, if an error does not occur inside this function, the `user` object\nis returned from the function, and probably, the code that runs after\nthis `create_user()` function will be responsible for freeing\nthe memory of the `user` object.\n\nBut what if an error occurs inside the `create_user()` function? What happens then?\nThis would mean that the execution of your code would stop in this `create_user()`\nfunction, and, as a consequence, the code that runs after this `create_user()`\nfunction would simply not run, and, as a result, the memory of the `user` object\nwould not be freed before your program stops.\n\nThis is the perfect scenario for `errdefer`. We use this keyword to guarantee\nthat our program will free the allocated memory for the `user` object,\neven if an error occurs inside the `create_user()` function.\n\nIf you allocate and free some memory for an object inside the same scope, then,\njust use `defer` and be happy, i.e. `errdefer` have no use for you in such situation.\nBut if you allocate some memory in a scope A, but you only free this memory\nlater, in a scope B for example, then, `errdefer` becomes useful to avoid leaking memory\nin sketchy situations.\n\n\n\n## Union type in Zig {#sec-unions}\n\nAn union type defines a set of types that an object can be. It is like a list of\noptions. Each option is a type that an object can assume. Therefore, unions in Zig\nhave the same meaning, or, the same role as unions in C. They are used for the same purpose.\nYou could also say that unions in Zig produces a similar effect to\n[using `typing.Union` in Python](https://docs.python.org/3/library/typing.html#typing.Union)[^pyunion].\n\n[^pyunion]: <https://docs.python.org/3/library/typing.html#typing.Union>\n\nFor example, you might be creating an API that sends data to a data lake, hosted\nin some private cloud infrastructure. Suppose you have created different structs in your codebase,\nto store the necessary information that you need, in order to connect to the services of\neach mainstream data lake service (Amazon S3, Azure Blob, etc.).\n\nNow, suppose you also have a function named `send_event()` that receives an event as input,\nand, a target data lake, and it sends the input event to the data lake specified in the\ntarget data lake argument. But this target data lake could be any of the three mainstream data lakes\nservices (Amazon S3, Azure Blob, etc.). Here is where an union can help you.\n\nThe union `LakeTarget` defined below allows the `lake_target` argument of `send_event()`\nto be either an object of type `AzureBlob`, or type `AmazonS3`, or type `GoogleGCP`.\nThis union allows the `send_event()` function to receive an object of any of these three types\nas input in the `lake_target` argument.\n\nRemember that each of these three types (`AmazonS3`, `GoogleGCP` and `AzureBlob`)\nare separate structs that we have defined in our source code. So, at first glance,\nthey are separate data types in our source code. But is the `union` keyword that\nunifies them into a single data type called `LakeTarget`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst LakeTarget = union {\n    azure: AzureBlob,\n    amazon: AmazonS3,\n    google: GoogleGCP,\n};\n\nfn send_event(\n    event: Event,\n    lake_target: LakeTarget\n) bool {\n    // body of the function ...\n}\n```\n:::\n\n\n\n\nAn union definition is composed by a list of data members. Each data member is of a specific data type.\nIn the example above, the `LakeTarget` union have three data members (`azure`, `amazon`, `google`).\nWhen you instantiate an object that uses an union type, you can only use one of its data members\nin this instantiation.\n\nYou could also interpret this as: only one data member of an union type can be activated at a time, the other data\nmembers remain deactivated and unaccessible. For example, if you create a `LakeTarget` object that uses\nthe `azure` data member, you can no longer use or access the data members `google` or `amazon`.\nIt is like if these other data members didn't exist at all in the `LakeTarget` type.\n\nYou can see this logic in the example below. Notice that, we first instantiate the union\nobject using the `azure` data member. As a result, this `target` object contains only\nthe `azure` data member inside of it. Only this data member is active in this object.\nThat is why the last line in this code example is invalid. Because we are trying to instantiate the data member\n`google`, which is currently inactive for this `target` object, and as a result, the program\nenters in panic mode warning us about this mistake through a loud error message.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar target = LakeTarget {\n    .azure = AzureBlob.init()\n};\n// Only the `azure` data member exist inside\n// the `target` object, and, as a result, this\n// line below is invalid:\ntarget.google = GoogleGCP.init();\n```\n:::\n\n\n\n\n```\nthread 2177312 panic: access of union field 'google' while\n    field 'azure' is active:\n    target.google = GoogleGCP.init();\n          ^\n```\n\nSo, when you instantiate an union object, you must choose one of the data types (or, one of the data members)\nlisted in the union type. In the example above, I choose to use the `azure` data member, and, as a result,\nall other data members were automatically deactivated,\nand you can no longer use them after you instantiate the object.\n\nYou can activate another data member by completely redefining the entire enum object.\nIn the example below, I initially use the `azure` data member. But then, I redefine the\n`target` object to use a new `LakeTarget` object, which uses the `google` data member.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar target = LakeTarget {\n    .azure = AzureBlob.init()\n};\ntarget = LakeTarget {\n    .google = GoogleGCP.init()\n};\n```\n:::\n\n\n\n\nA curious fact about union types, is that, at first, you cannot use them in switch statements (which were presented at @sec-switch).\nIn other words, if you have an object of type `LakeTarget` for example, you cannot give this object\nas input to a switch statement.\n\nBut what if you really need to do so? What if you actually need to\nprovide an \"union object\" to a switch statement? The answer to this question relies on another special type in Zig,\nwhich are the *tagged unions*. To create a tagged union, all you have to do is to add\nan enum type into your union declaration.\n\nAs an example of a tagged union in Zig, take the `Registry` type exposed\nbelow. This type comes from the\n[`grammar.zig` module](https://github.com/ziglang/zig/blob/30b4a87db711c368853b3eff8e214ab681810ef9/tools/spirv/grammar.zig)[^grammar]\nfrom the Zig repository. This union type lists different types of registries.\nBut notice this time, the use of `(enum)` after the `union` keyword. This is what makes\nthis union type a tagged union. By being a tagged union, an object of this `Registry` type\ncan be used as input in a switch statement. This is all you have to do. Just add `(enum)`\nto your `union` declaration, and you can use it in switch statements.\n\n[^grammar]: <https://github.com/ziglang/zig/blob/30b4a87db711c368853b3eff8e214ab681810ef9/tools/spirv/grammar.zig>.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const Registry = union(enum) {\n    core: CoreRegistry,\n    extension: ExtensionRegistry,\n};\n```\n:::\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/10-stack-project/execute-results/html.json b/_freeze/Chapters/10-stack-project/execute-results/html.json
index 4daf8bfb..8835df3a 100644
--- a/_freeze/Chapters/10-stack-project/execute-results/html.json
+++ b/_freeze/Chapters/10-stack-project/execute-results/html.json
@@ -2,10 +2,8 @@
   "hash": "aa5d168604f4fcb0ae811071177c31fe",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 3 - Building a stack data structure\n\nIn this chapter we are going to implement a stack data structure as our next small project\nin this book. Implementing basic data structures in any language is kind of a\n\"kindergarten task\" (if this term even exist) in computer science (CS), because\nwe normally learn and implement them in the first semesters of CS.\n\nBut this is actually good! Since this should be a very easy task, we don't need much to explain\nwhat a stack is, then, we can concentrate on what is really important here, which is learning\nhow the concept of \"generics\" is implemented in the Zig language, and how one of the key\nfeatures of Zig, which is comptime, works, and use the stack data structure to demonstrate\nthese concepts on the fly.\n\nBut before we get into building the stack data structure, we first need to understand\nwhat the `comptime` keyword does to your code, and after that, we also need to learn about\nhow generics work in Zig.\n\n\n## Understanding `comptime` in Zig {#sec-comptime}\n\nOne of the key features of Zig is `comptime`. This keyword introduces a whole\nnew concept and paradigm, that is tightly connected with the compilation process.\nAt @sec-compile-time we have described the importance and the role that \"compile-time versus runtime\"\nplays into Zig. At that section, we learned that the rules applied to a value/object change\na lot depending on whether this value is known at compile-time, or just at runtime.\n\nThe `comptime` keyword is strongly related to these two spaces in time (compile-time and runtime).\nLet's quickly recap the differences. Compile-time is the period of time when your\nZig source code is being compiled by the `zig` compiler, while the runtime is\nthe period of time when your Zig program is being executed, i.e. when we execute\nthe binary files that were generated by the `zig` compiler.\n\nThere are three ways in which you can apply the `comptime` keyword, which are:\n\n- apply `comptime` on a function argument.\n- apply `comptime` on an object.\n- apply `comptime` on a block of expressions.\n\n\n\n### Applying over a function argument\n\nWhen you apply the `comptime` keyword on a function argument, you are saying to the `zig` compiler\nthat the value assigned to that particular function argument must be known at compile-time.\nWe explained in details at @sec-compile-time what exactly \"value known at compile-time\" means, so,\nin case you have doubts about this idea, come back to that section.\n\nNow let's think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement\nto that particular function argument. If the programmer accidentally tries to give a value to this\nfunction argument that is not known at compile time, the `zig` compiler will notice this problem, and\nas a consequence, it will raise a compilation error saying that it cannot compile your program. Because\nyou are providing a value that is \"runtime known\" to a function argument that must be \"compile-time known\".\n\nTake a look at this very simple example below, where we define a `twice()` function, that simply\ndoubles the input value named `num`. Notice that we use the `comptime` keyword before the name\nof the function argument. This keyword is marking the function argument `num` as a \"comptime argument\".\n\nThat is a function argument whose value must be compile-time known. This is why the expression\n`twice(5678)` is valid, and no compilation errors are raised. Because the value `5678`\nis compile-time known, so this is the expected behaviour for this function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n```\n:::\n\n\n\n\nBut what if we provide a number that is not compile-time known to this function?\nFor example, we might provide a different input value to this function depending\non the target OS of our compilation process. The code example below demonstrates such case.\n\nBecause the value of the object `n` is determined at runtime, we cannot provide this object\nas input to the `twice()` function. The `zig` compiler will not allow it, because we marked\nthe `num` argument as a \"comptime argument\". That is why the `zig` compiler raises\nthe compile-time error exposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    var n: u32 = undefined;\n    if (builtin.target.os.tag == .windows) {\n        n = 1234;\n    } else {\n        n = 5678;\n    }\n    _ = twice(n);\n}\n```\n:::\n\n\n\n\n```\nt.zig:12:16: error: runtime-known argument passed to comptime parameter \n```\n\nComptime arguments are frequently used on functions that return some sort\nof generic structure. In fact, `comptime` is the essence (or the basis) to make generics in Zig.\nWe are going to talk more about generics at @sec-generics.\n\nFor now, let's take a look at this code example from @karlseguin_generics. You\ncan see that this `IntArray()` function have one argument named `length`.\nThis argument is marked as comptime, and receives a value of type `usize` as input. So the value given to this argument\nmust be compile-time known.\nWe can also see that this function returns an array of `i64` values as output.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n```\n:::\n\n\n\n\nNow, the key component of this function is the `length` argument. This argument\nis used to determine the size of the array that is produced by the function. Let's\nthink about the consequences of that. If the size of the array is dependent on\nthe value assigned to the `length` argument, this means that the data type of the\noutput of the function depends on the value of this `length` argument.\n\nLet this statement sink for a bit in your mind. As I described at @sec-root-file,\nZig is a strongly-typed language, especially on function declarations.\nSo every time we write a function in Zig, we have to annotate the data type of\nthe value returned by the function. But how can we do that, if this data type\ndepends on the value given to the argument of the function?\n\nThink about this for a second. If `length` is equal to 3 for example, then, the\nreturn type of the function is `[3]i64`. But if `length` is equal to 40, then,\nthe return type becomes `[40]i64`. At this point the `zig` compiler would be confused,\nand raise a compilation error, saying something like this:\n\n> Hey! You have annotated that this function should return a `[3]i64` value, but I got a `[40]i64` value instead! This doesn't look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when\nthe `type` keyword comes in. This `type` keyword is basically saying to the\n`zig` compiler that this function will return some data type as output, but it doesn't know yet\nwhat exactly data type that is. We will talk more about this at @sec-generics.\n\n\n\n### Applying over an expression\n\nWhen you apply the `comptime` keyword over an expression, then, it is guaranteed that the `zig` compiler will\nexecute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time\n(e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the `zig` compiler\nwill raise a compilation error.\n\nTake this example from the official documentation of Zig [@zigdocs]. We\nare executing the same `fibonacci()` function both at runtime, and, at compile-time.\nThe function is by default executed at runtime, but because we use the `comptime`\nkeyword at the second \"try expression\", this expression is executed at compile-time.\n\nThis might be a bit confusing for some people. Yes! When I say that this expression\nis executed at compile-time, I mean that this expression is compiled and executed\nwhile the `zig` compiler is compiling your Zig source code.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n```\n:::\n\n\n\n\nA lot of your Zig source code might be potentially executed at compile-time,\nbecause the `zig` compiler can figure it out the output of some expressions.\nEspecially if these expressions depends only at compile-time known values.\nWe have talked about this at @sec-compile-time.\n\nBut when you use the `comptime` keyword on an expression, there is no \"it might be executed\nat compile-time\" anymore. With the `comptime` keyword you are ordering the `zig` compiler\nto execute this expression at compile-time. You are imposing this rule, it is guaranteed\nthat the compiler will always execute it at compile-time. Or, at least, the compiler\nwill try to execute it. If the compiler cannot execute the expression for whatever reason,\nthe compiler will raise a compilation error.\n\n\n### Applying over a block\n\nBlocks were described at @sec-blocks. When you apply the `comptime` keyword over a\nblock of expressions, you get essentially the same effect when you apply this keyword to\na single expression. That is, the entire block of expressions is executed at\ncompile-time by the `zig` compiler.\n\nIn the example below, we mark the block labeled of `blk` as a comptime block,\nand, therefore, the expressions inside this block are executed at compile-time.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n```\n:::\n\n\n\n\n\n\n\n\n## Introducing Generics {#sec-generics}\n\nFirst of all, what is a generic? Generic is the idea to allow a type\n(`f64`, `u8`, `u32`, `bool`, and also, user-defined types, like the `User` struct\nthat we defined at @sec-structs-and-oop) to be a parameter to methods, classes and\ninterfaces [@geeks_generics]. In other words, a \"generic\" is a class (or a method) that can work\nwith multiple data types.\n\nFor example, in Java, generics are created through the operator `<>`. With this operator,\na Java class is capable of receiving a data type as input, and therefore, the class can fit\nits features according to this input data type.\nAs another example, generics in C++ are supported through the concept of templates.\nClass templates in C++ are generics.\n\nIn Zig, generics are implemented through `comptime`. The `comptime` keyword\nallows us to collect a data type at compile time, and pass this data type as\ninput to a piece of code.\n\n\n### A generic function {#sec-generic-fun}\n\nTake the `max()` function exposed below as a first example.\nThis function is essentially a \"generic function\".\nIn this function, we have a comptime function argument named `T`.\nNotice that this `T` argument have a data type of `type`. Weird right? This `type` keyword is the\n\"father of all types\", or, \"the type of types\" in Zig.\n\nBecause we have used this `type` keyword in the `T` argument, we are telling\nthe `zig` compiler that this `T` argument will receive some data type as input.\nAlso notice the use of the `comptime` keyword in this argument.\nAs I described at @sec-comptime, every time you use this keyword in a function argument,\nthis means that the value of this argument must be known at compile-time.\nThis makes sense, right? Because there is no data type that is not known at compile-time.\n\nThink about this. Every data type that you will ever write is always\nknown at compile-time. Especially because data types are an essential\ninformation for the compiler to actually compile your source code.\nHaving this in mind, makes sense to mark this argument as a comptime argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\n```\n:::\n\n\n\n\nAlso notice that the value of the `T` argument is actually used\nto define the data type of the other arguments in the function, `a` and `b`, and also at the\nreturn type annotation of the function.\nThat is, the data type of these arguments (`a` and `b`), and, the return data type of the function itself,\nare determined by the input value given to the `T` argument.\n\nAs a result, we have a generic function that works with different data types.\nFor example, I can provide `u8` values to this `max()` function, and it will work as expected.\nBut if I provide `f64` values instead, it will also work as expected.\nWithout a generic function, I would have to write a different `max()` function\nfor each one of the data types that I wanted to use.\nThis generic function provides a very useful shortcut for us.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\ntest \"test max\" {\n    const n1 = max(u8, 4, 10);\n    std.debug.print(\"Max n1: {d}\\n\", .{n1});\n    const n2 = max(f64, 89.24, 64.001);\n    std.debug.print(\"Max n2: {d}\\n\", .{n2});\n}\n```\n:::\n\n\n\n\n```\nMax n1: 10\nMax n2: 89.24\n```\n\n\n\n### A generic data structure {#sec-generic-struct}\n\nEvery data structure that you find in the Zig Standard Library (e.g. `ArrayList`, `HashMap`, etc.)\nis essentially a generic data structure.\nThese data structures are generic in the sense that they work with any data type you want.\nYou just say which is the data type of the values that are going to be stored in this data\nstructure, and they just work as expected.\n\nA generic data structure in Zig is how you replicate a generic class from Java,\nor, a class template from C++. But you may quest yourself: how do we build a\ngeneric data structure in Zig?\n\nThe basic idea is to write a generic function that creates the data structure definition\nfor the specific type we want. In other words, this generic function behaves as a \"factory of data structures\".\nThe generic function outputs the `struct` definition that defines this data structure for a\nspecific data type.\n\nTo create such function, we need to add a comptime argument to this function that receives a data type\nas input. We already learned how to do this at the previous section (@sec-generic-fun).\nI think the best way to demonstrate how to create a generic data structure is to actually write one.\nThis where we go into our next small project in this book. This one is a very small project,\nwhich is to write a generic stack data structure.\n\n\n\n\n## What is a stack? {#sec-what-stack}\n\nA stack data structure is a structure that follows a LIFO (*last in, first out*) principle.\nOnly two operations are normally supported in a stack data structure, which are `push` and `pop`.\nThe `push` operation is used to add new values to the stack, while `pop` is used to remove\nvalues from the stack.\n\nWhen people try to explain how the stack data structure works, the most common analogy\nthat they use is a stack of plates. Imagine that you have a stack of plates,\nfor example, a stack of 10 plates in your table. Each plate represents a value that\nis currently stored in this stack.\n\nWe begin with a stack of 10 different values, or 10 different plates. Now, imagine that you want to\nadd a new plate (or a new value) to this stack, which translates to the `push` operation.\nYou would add this plate (or this value) by just putting the new plate\non the top of the stack. Then, you would increase the stack to 11 plates.\n\nBut how would you remove plates (or remove values) from this stack (a.k.a. the `pop` operation) ?\nTo do that, we would have to remove the plate on the top of the stack, and, as a result, we would\nhave, once again, 10 plates in the stack.\n\nThis demonstrates the LIFO concept, because the first plate in the stack, which is the plate\nin the bottom of the stack, is always the last plate to get out of the stack. Think about it. In order\nto remove this specific plate from the stack, we have to remove all plates in the\nstack. So every operation in the stack, either insertion or deletion, is always made at the top of the stack.\nThe @fig-stack below exposes this logic visually:\n\n![A diagram of a stack structure. Source: Wikipedia, the free encyclopedia.](./../Figures/lifo-stack.svg){#fig-stack}\n\n\n\n## Writing the stack data structure\n\nWe are going to write the stack data structure in two steps. First, we are going\nto implement a stack that can only store `u32` values. Then, after that, we are going\nto extend our implementation to make it generic, so that it works with any data type\nwe want.\n\nFirst, we need to decide how the values will be stored inside the stack. There are multiple\nways to implement the storage behind a stack structure. Some people prefer to use a doubly linked list,\nsome others prefer to use a dynamic array, etc. In this example we are going to use an array behind the hood,\nto store the values in the stack, which is the `items` data member of our `Stack` struct definition.\n\nAlso notice in our `Stack` struct that we have three other data members: `capacity`, `length` and `allocator`.\nThe `capacity` member contains the capacity of the underlying array that stores the values in the stack.\nThe `length` contains the number of values that are currently being stored in the stack.\nAnd the `allocator` contains the allocator object that will be used by the stack structure whenever it\nneeds to allocate more space for the values that are being stored.\n\nWe begin by defining an `init()` method of this struct, which is going to be\nresponsible for instantiating a `Stack` object. Notice that, inside this\n`init()` method, we start by allocating an array with the capacity specified\nin the `capacity` argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst Stack = struct {\n    items: []u32,\n    capacity: usize,\n    length: usize,\n    allocator: Allocator,\n\n    pub fn init(allocator: Allocator, capacity: usize) !Stack {\n        var buf = try allocator.alloc(u32, capacity);\n        return .{\n            .items = buf[0..],\n            .capacity = capacity,\n            .length = 0,\n            .allocator = allocator,\n        };\n    }\n};\n```\n:::\n\n\n\n\n\n### Implementing the `push` operation\n\nNow that we have written the basic logic to create a new `Stack` object,\nwe can start writing the logic responsible for performing a push operation.\nRemember, a push operation in a stack data structure is the operation\nresponsible for adding a new value to the stack.\n\nSo how can we add a new value to the `Stack` object that we have?\nThe `push()` function exposed below is a possible answer to this question.\nRemember from what we discussed at @sec-what-stack that values are always added to the top of the stack.\nThis means that this `push()` function must always find the element in the underlying array\nthat currently represents the top position of the stack, and then, add the input value there.\n\nFirst, we have an if statement in this function. This if statement is\nchecking whether we need to expand the underlying array to store\nthis new value that we are adding to the stack. In other words, maybe\nthe underlying array does not have enough capacity to store this new\nvalue, and, in this case, we need to expand our array to get the capacity that we need.\n\nSo, if the logical test in this if statement returns true, it means that the array\ndoes not have enough capacity, and we need to expand it before we store this new value.\nSo inside this if statement we are executing the necessary expressions to expand the underlying array.\nNotice that we use the allocator object to allocate a new array that is twice as bigger\nthan the current array (`self.capacity * 2`).\n\nAfter that, we use a different built-in function named `@memcpy()`. This built-in function\nis equivalent to the `memcpy()` function from the C Standard Library[^cmemcpy]. It is used to\ncopy the values from one block of memory to another block of memory. In other words,\nyou can use this function to copy the values from one array into another array.\n\n[^cmemcpy]: <https://www.tutorialspoint.com/c_standard_library/c_function_memcpy.htm>\n\nWe are using this `@memcpy()` built-in function to copy the values that are currently stored\nin the underlying array of the stack object (`self.items`) into our new and bigger array that\nwe have allocated (`new_buf`). After we execute this function, the `new_buf` contains a copy\nof the values that are present at `self.items`.\n\nNow that we have secured a copy of our current values in the `new_buf` object, we\ncan now free the memory currently allocated at `self.items`. After that, we just need\nto assign our new and bigger array to `self.items`. This is the sequence\nof steps necessary to expand our array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn push(self: *Stack, val: u32) !void {\n    if ((self.length + 1) > self.capacity) {\n        var new_buf = try self.allocator.alloc(\n            u32, self.capacity * 2\n        );\n        @memcpy(\n            new_buf[0..self.capacity], self.items\n        );\n        self.allocator.free(self.items);\n        self.items = new_buf;\n        self.capacity = self.capacity * 2;\n    }\n\n    self.items[self.length] = val;\n    self.length += 1;\n}\n```\n:::\n\n\n\n\nAfter we make sure that we have enough room to store this new value\nthat we are adding to the stack, all we have to do is to assign\nthis value to the top element in this stack, and, increase the\nvalue of the `length` attribute by one. We find the top element\nin the stack by using the `length` attribute.\n\n\n\n### Implementing the `pop` operation\n\nNow we can implement the pop operation of our stack object.\nThis is a much easier operation to implement, and the `pop()` method below summarises\nall the logic that is needed.\n\nWe just have to find the element in the underlying array that currently represents the top\nof the stack, and set this element to \"undefined\", to indicate that\nthis element is \"empty\". After that, we also need to decrease\nthe `length` attribute of the stack by one.\n\nIf the current length of the stack is zero, it means that there is\nno values being stored in the stack currently. So, in this case,\nwe could just return from the function and do nothing really.\nThis is what the if statement inside this function is checking for.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn pop(self: *Stack) void {\n    if (self.length == 0) return;\n\n    self.items[self.length - 1] = undefined;\n    self.length -= 1;\n}\n```\n:::\n\n\n\n\n\n\n### Implementing the `deinit` method\n\nWe have implemented the methods responsible for the two main operations\nassociated with the stack data structure, which is `pop()` and `push()`,\nand we also have implemented the method responsible for instantiating\na new `Stack` object, which is the `init()` method.\n\nBut now, we need to implement also the method responsible for destroying\na `Stack` object. In Zig, this task is commonly associated with the method\nnamed `deinit()`. Most struct objects in Zig have such method, and it\nis commonly nicknamed \"the destructor method\".\n\nIn theory, all we have to do to destroy the `Stack` object is to make\nsure that we free the allocated memory for the underlying array, using\nthe allocator object that is stored inside the `Stack` object.\nThis is what the `deinit()` method below is doing.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn deinit(self: *Stack) void {\n    self.allocator.free(self.items);\n}\n```\n:::\n\n\n\n\n\n\n\n## Making it generic\n\nNow that we have implemented the basic skeleton of our stack data structure,\nwe can now focus on discussing how can we make it generic. How can we make\nthis basic skeleton to work not only with `u32` values, but also, with any other\ndata type we want?\nFor example, we might need to create a stack object to store `User` values\nin it. How can we make this possible? The answer lies on the use of generics\nand `comptime`.\n\nAs I described at @sec-generic-struct, the basic idea is to write a generic\nfunction that returns a struct definition as output.\nIn theory, we do not need much to transform our `Stack` struct into a generic\ndata structure. All that we need to do is to transform the underlying array\nof the stack into a generic array.\n\nIn other words, this underlying array needs to be a \"chameleon\". It needs to adapt,\nand transform it into an array of any data type that we want. For example, if we need to create\na stack that will store `u8` values, then, this underlying array needs to be\na `u8` array (i.e. `[]u8`). But if we need to store `User` values instead, then,\nthis array needs to be a `User` array (i.e. `[]User`). Etc.\n\nWe do that by using a generic function. Because a generic function can receive a data type\nas input, and we can pass this data type to the struct definition of our `Stack` object.\nTherefore, we can use the generic function to create a `Stack` object that can store\nthe data type we want. If we want to create a stack structure that stores `User` values,\nwe pass the `User` data type to this generic function, and it will create for us\nthe struct definition that describes a `Stack` object that can store `User` values in it.\n\nLook at the code example below. I have omitted some parts of the `Stack` struct definition\nfor brevity reasons. However, if a specific part of our `Stack` struct is not exposed here\nin this example, then it is because this part did not change from the previous example.\nIt remains the same.\n\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn Stack(comptime T: type) type {\n    return struct {\n        items: []T,\n        capacity: usize,\n        length: usize,\n        allocator: Allocator,\n        const Self = @This();\n\n        pub fn init(allocator: Allocator,\n                    capacity: usize) !Stack(T) {\n            var buf = try allocator.alloc(T, capacity);\n            return .{\n                .items = buf[0..],\n                .capacity = capacity,\n                .length = 0,\n                .allocator = allocator,\n            };\n        }\n\n        pub fn push(self: *Self, val: T) !void {\n        // Truncate the rest of the struct\n    };\n}\n```\n:::\n\n\n\n\nNotice that we have created a function in this example named `Stack()`. This function\ntakes a type as input, and passes this type to the struct definition of our\n`Stack` object. The data member `items` is now, an array of type `T`, which is the\ndata type that we have provided as input to the function. The function argument\n`val` in the `push()` function is now a value of type `T` too.\n\nWe can just provide a data type to this function, and it will create a definition of a\n`Stack` object that can store values of the data type that we have provided. In the example below, we are creating\nthe definition of a\n`Stack` object that can store `u8` values in it. This definition is stored at the `Stacku8` object.\nThis `Stacku8` object becomes our new struct, it is the struct that we are going to use\nto create our `Stack` object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst Stacku8 = Stack(u8);\nvar stack = try Stacku8.init(allocator, 10);\ndefer stack.deinit();\ntry stack.push(1);\ntry stack.push(2);\ntry stack.push(3);\ntry stack.push(4);\ntry stack.push(5);\ntry stack.push(6);\n\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\"Stack capacity: {d}\\n\", .{stack.capacity});\n\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\n    \"Stack state: {any}\\n\",\n    .{stack.items[0..stack.length]}\n);\n```\n:::\n\n\n\n\n```\nStack len: 6\nStack capacity: 10\nStack len: 5\nStack len: 4\nStack state: { 1, 2, 3, 4, 0, 0, 0, 0, 0, 0 }\n```\n\nEvery generic data structure in the Zig Standard Library (`ArrayList`, `HashMap`, `SinlyLinkedList`, etc.)\nis implemented through this logic. They use a generic function to create the struct definition that can work\nwith the data type that you provided as input.\n\n\n\n\n## Conclusion\n\nThe full source code of the stack structure discussed in this chapter is freely available at the official\nrepository of this book. Just checkout the [`stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig)[^zig-stack]\nfor the `u32` version of our stack,\nand the [`generic_stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig)[^zig-stack2]\nfor the generic version, available inside the `ZigExamples` folder of the repository.\n\n\n[^zig-stack]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig>\n[^zig-stack2]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig>\n\n",
-    "supporting": [
-      "10-stack-project_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 3 - Building a stack data structure\n\nIn this chapter we are going to implement a stack data structure as our next small project\nin this book. Implementing basic data structures in any language is kind of a\n\"kindergarten task\" (if this term even exist) in computer science (CS), because\nwe normally learn and implement them in the first semesters of CS.\n\nBut this is actually good! Since this should be a very easy task, we don't need much to explain\nwhat a stack is, then, we can concentrate on what is really important here, which is learning\nhow the concept of \"generics\" is implemented in the Zig language, and how one of the key\nfeatures of Zig, which is comptime, works, and use the stack data structure to demonstrate\nthese concepts on the fly.\n\nBut before we get into building the stack data structure, we first need to understand\nwhat the `comptime` keyword does to your code, and after that, we also need to learn about\nhow generics work in Zig.\n\n\n## Understanding `comptime` in Zig {#sec-comptime}\n\nOne of the key features of Zig is `comptime`. This keyword introduces a whole\nnew concept and paradigm, that is tightly connected with the compilation process.\nAt @sec-compile-time we have described the importance and the role that \"compile-time versus runtime\"\nplays into Zig. At that section, we learned that the rules applied to a value/object change\na lot depending on whether this value is known at compile-time, or just at runtime.\n\nThe `comptime` keyword is strongly related to these two spaces in time (compile-time and runtime).\nLet's quickly recap the differences. Compile-time is the period of time when your\nZig source code is being compiled by the `zig` compiler, while the runtime is\nthe period of time when your Zig program is being executed, i.e. when we execute\nthe binary files that were generated by the `zig` compiler.\n\nThere are three ways in which you can apply the `comptime` keyword, which are:\n\n- apply `comptime` on a function argument.\n- apply `comptime` on an object.\n- apply `comptime` on a block of expressions.\n\n\n\n### Applying over a function argument\n\nWhen you apply the `comptime` keyword on a function argument, you are saying to the `zig` compiler\nthat the value assigned to that particular function argument must be known at compile-time.\nWe explained in details at @sec-compile-time what exactly \"value known at compile-time\" means, so,\nin case you have doubts about this idea, come back to that section.\n\nNow let's think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement\nto that particular function argument. If the programmer accidentally tries to give a value to this\nfunction argument that is not known at compile time, the `zig` compiler will notice this problem, and\nas a consequence, it will raise a compilation error saying that it cannot compile your program. Because\nyou are providing a value that is \"runtime known\" to a function argument that must be \"compile-time known\".\n\nTake a look at this very simple example below, where we define a `twice()` function, that simply\ndoubles the input value named `num`. Notice that we use the `comptime` keyword before the name\nof the function argument. This keyword is marking the function argument `num` as a \"comptime argument\".\n\nThat is a function argument whose value must be compile-time known. This is why the expression\n`twice(5678)` is valid, and no compilation errors are raised. Because the value `5678`\nis compile-time known, so this is the expected behaviour for this function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file1054863994c6f.test.test comptime...OKAll 1\n  1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\nBut what if we provide a number that is not compile-time known to this function?\nFor example, we might provide a different input value to this function depending\non the target OS of our compilation process. The code example below demonstrates such case.\n\nBecause the value of the object `n` is determined at runtime, we cannot provide this object\nas input to the `twice()` function. The `zig` compiler will not allow it, because we marked\nthe `num` argument as a \"comptime argument\". That is why the `zig` compiler raises\nthe compile-time error exposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    var n: u32 = undefined;\n    if (builtin.target.os.tag == .windows) {\n        n = 1234;\n    } else {\n        n = 5678;\n    }\n    _ = twice(n);\n}\n```\n:::\n\n\n\n\n```\nt.zig:12:16: error: runtime-known argument passed to comptime parameter \n```\n\nComptime arguments are frequently used on functions that return some sort\nof generic structure. In fact, `comptime` is the essence (or the basis) to make generics in Zig.\nWe are going to talk more about generics at @sec-generics.\n\nFor now, let's take a look at this code example from @karlseguin_generics. You\ncan see that this `IntArray()` function have one argument named `length`.\nThis argument is marked as comptime, and receives a value of type `usize` as input. So the value given to this argument\nmust be compile-time known.\nWe can also see that this function returns an array of `i64` values as output.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n```\n:::\n\n\n\n\nNow, the key component of this function is the `length` argument. This argument\nis used to determine the size of the array that is produced by the function. Let's\nthink about the consequences of that. If the size of the array is dependent on\nthe value assigned to the `length` argument, this means that the data type of the\noutput of the function depends on the value of this `length` argument.\n\nLet this statement sink for a bit in your mind. As I described at @sec-root-file,\nZig is a strongly-typed language, especially on function declarations.\nSo every time we write a function in Zig, we have to annotate the data type of\nthe value returned by the function. But how can we do that, if this data type\ndepends on the value given to the argument of the function?\n\nThink about this for a second. If `length` is equal to 3 for example, then, the\nreturn type of the function is `[3]i64`. But if `length` is equal to 40, then,\nthe return type becomes `[40]i64`. At this point the `zig` compiler would be confused,\nand raise a compilation error, saying something like this:\n\n> Hey! You have annotated that this function should return a `[3]i64` value, but I got a `[40]i64` value instead! This doesn't look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when\nthe `type` keyword comes in. This `type` keyword is basically saying to the\n`zig` compiler that this function will return some data type as output, but it doesn't know yet\nwhat exactly data type that is. We will talk more about this at @sec-generics.\n\n\n\n### Applying over an expression\n\nWhen you apply the `comptime` keyword over an expression, then, it is guaranteed that the `zig` compiler will\nexecute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time\n(e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the `zig` compiler\nwill raise a compilation error.\n\nTake this example from the official documentation of Zig [@zigdocs]. We\nare executing the same `fibonacci()` function both at runtime, and, at compile-time.\nThe function is by default executed at runtime, but because we use the `comptime`\nkeyword at the second \"try expression\", this expression is executed at compile-time.\n\nThis might be a bit confusing for some people. Yes! When I say that this expression\nis executed at compile-time, I mean that this expression is compiled and executed\nwhile the `zig` compiler is compiling your Zig source code.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file10548bb87337.test.fibonacci...OKAll 1 test\n  ts passed.\n```\n\n\n:::\n:::\n\n\n\n\nA lot of your Zig source code might be potentially executed at compile-time,\nbecause the `zig` compiler can figure it out the output of some expressions.\nEspecially if these expressions depends only at compile-time known values.\nWe have talked about this at @sec-compile-time.\n\nBut when you use the `comptime` keyword on an expression, there is no \"it might be executed\nat compile-time\" anymore. With the `comptime` keyword you are ordering the `zig` compiler\nto execute this expression at compile-time. You are imposing this rule, it is guaranteed\nthat the compiler will always execute it at compile-time. Or, at least, the compiler\nwill try to execute it. If the compiler cannot execute the expression for whatever reason,\nthe compiler will raise a compilation error.\n\n\n### Applying over a block\n\nBlocks were described at @sec-blocks. When you apply the `comptime` keyword over a\nblock of expressions, you get essentially the same effect when you apply this keyword to\na single expression. That is, the entire block of expressions is executed at\ncompile-time by the `zig` compiler.\n\nIn the example below, we mark the block labeled of `blk` as a comptime block,\nand, therefore, the expressions inside this block are executed at compile-time.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file105482dc0b880.test.fibonacci in a block...\n  .OKAll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## Introducing Generics {#sec-generics}\n\nFirst of all, what is a generic? Generic is the idea to allow a type\n(`f64`, `u8`, `u32`, `bool`, and also, user-defined types, like the `User` struct\nthat we defined at @sec-structs-and-oop) to be a parameter to methods, classes and\ninterfaces [@geeks_generics]. In other words, a \"generic\" is a class (or a method) that can work\nwith multiple data types.\n\nFor example, in Java, generics are created through the operator `<>`. With this operator,\na Java class is capable of receiving a data type as input, and therefore, the class can fit\nits features according to this input data type.\nAs another example, generics in C++ are supported through the concept of templates.\nClass templates in C++ are generics.\n\nIn Zig, generics are implemented through `comptime`. The `comptime` keyword\nallows us to collect a data type at compile time, and pass this data type as\ninput to a piece of code.\n\n\n### A generic function {#sec-generic-fun}\n\nTake the `max()` function exposed below as a first example.\nThis function is essentially a \"generic function\".\nIn this function, we have a comptime function argument named `T`.\nNotice that this `T` argument have a data type of `type`. Weird right? This `type` keyword is the\n\"father of all types\", or, \"the type of types\" in Zig.\n\nBecause we have used this `type` keyword in the `T` argument, we are telling\nthe `zig` compiler that this `T` argument will receive some data type as input.\nAlso notice the use of the `comptime` keyword in this argument.\nAs I described at @sec-comptime, every time you use this keyword in a function argument,\nthis means that the value of this argument must be known at compile-time.\nThis makes sense, right? Because there is no data type that is not known at compile-time.\n\nThink about this. Every data type that you will ever write is always\nknown at compile-time. Especially because data types are an essential\ninformation for the compiler to actually compile your source code.\nHaving this in mind, makes sense to mark this argument as a comptime argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nAll 0 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\nAlso notice that the value of the `T` argument is actually used\nto define the data type of the other arguments in the function, `a` and `b`, and also at the\nreturn type annotation of the function.\nThat is, the data type of these arguments (`a` and `b`), and, the return data type of the function itself,\nare determined by the input value given to the `T` argument.\n\nAs a result, we have a generic function that works with different data types.\nFor example, I can provide `u8` values to this `max()` function, and it will work as expected.\nBut if I provide `f64` values instead, it will also work as expected.\nWithout a generic function, I would have to write a different `max()` function\nfor each one of the data types that I wanted to use.\nThis generic function provides a very useful shortcut for us.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\ntest \"test max\" {\n    const n1 = max(u8, 4, 10);\n    std.debug.print(\"Max n1: {d}\\n\", .{n1});\n    const n2 = max(f64, 89.24, 64.001);\n    std.debug.print(\"Max n2: {d}\\n\", .{n2});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file105482071daf3.test.test max...Max n1: 10Ma\n  ax n2: 89.24OKAll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n```\nMax n1: 10\nMax n2: 89.24\n```\n\n\n\n### A generic data structure {#sec-generic-struct}\n\nEvery data structure that you find in the Zig Standard Library (e.g. `ArrayList`, `HashMap`, etc.)\nis essentially a generic data structure.\nThese data structures are generic in the sense that they work with any data type you want.\nYou just say which is the data type of the values that are going to be stored in this data\nstructure, and they just work as expected.\n\nA generic data structure in Zig is how you replicate a generic class from Java,\nor, a class template from C++. But you may quest yourself: how do we build a\ngeneric data structure in Zig?\n\nThe basic idea is to write a generic function that creates the data structure definition\nfor the specific type we want. In other words, this generic function behaves as a \"factory of data structures\".\nThe generic function outputs the `struct` definition that defines this data structure for a\nspecific data type.\n\nTo create such function, we need to add a comptime argument to this function that receives a data type\nas input. We already learned how to do this at the previous section (@sec-generic-fun).\nI think the best way to demonstrate how to create a generic data structure is to actually write one.\nThis where we go into our next small project in this book. This one is a very small project,\nwhich is to write a generic stack data structure.\n\n\n\n\n## What is a stack? {#sec-what-stack}\n\nA stack data structure is a structure that follows a LIFO (*last in, first out*) principle.\nOnly two operations are normally supported in a stack data structure, which are `push` and `pop`.\nThe `push` operation is used to add new values to the stack, while `pop` is used to remove\nvalues from the stack.\n\nWhen people try to explain how the stack data structure works, the most common analogy\nthat they use is a stack of plates. Imagine that you have a stack of plates,\nfor example, a stack of 10 plates in your table. Each plate represents a value that\nis currently stored in this stack.\n\nWe begin with a stack of 10 different values, or 10 different plates. Now, imagine that you want to\nadd a new plate (or a new value) to this stack, which translates to the `push` operation.\nYou would add this plate (or this value) by just putting the new plate\non the top of the stack. Then, you would increase the stack to 11 plates.\n\nBut how would you remove plates (or remove values) from this stack (a.k.a. the `pop` operation) ?\nTo do that, we would have to remove the plate on the top of the stack, and, as a result, we would\nhave, once again, 10 plates in the stack.\n\nThis demonstrates the LIFO concept, because the first plate in the stack, which is the plate\nin the bottom of the stack, is always the last plate to get out of the stack. Think about it. In order\nto remove this specific plate from the stack, we have to remove all plates in the\nstack. So every operation in the stack, either insertion or deletion, is always made at the top of the stack.\nThe @fig-stack below exposes this logic visually:\n\n![A diagram of a stack structure. Source: Wikipedia, the free encyclopedia.](./../Figures/lifo-stack.svg){#fig-stack}\n\n\n\n## Writing the stack data structure\n\nWe are going to write the stack data structure in two steps. First, we are going\nto implement a stack that can only store `u32` values. Then, after that, we are going\nto extend our implementation to make it generic, so that it works with any data type\nwe want.\n\nFirst, we need to decide how the values will be stored inside the stack. There are multiple\nways to implement the storage behind a stack structure. Some people prefer to use a doubly linked list,\nsome others prefer to use a dynamic array, etc. In this example we are going to use an array behind the hood,\nto store the values in the stack, which is the `items` data member of our `Stack` struct definition.\n\nAlso notice in our `Stack` struct that we have three other data members: `capacity`, `length` and `allocator`.\nThe `capacity` member contains the capacity of the underlying array that stores the values in the stack.\nThe `length` contains the number of values that are currently being stored in the stack.\nAnd the `allocator` contains the allocator object that will be used by the stack structure whenever it\nneeds to allocate more space for the values that are being stored.\n\nWe begin by defining an `init()` method of this struct, which is going to be\nresponsible for instantiating a `Stack` object. Notice that, inside this\n`init()` method, we start by allocating an array with the capacity specified\nin the `capacity` argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst Stack = struct {\n    items: []u32,\n    capacity: usize,\n    length: usize,\n    allocator: Allocator,\n\n    pub fn init(allocator: Allocator, capacity: usize) !Stack {\n        var buf = try allocator.alloc(u32, capacity);\n        return .{\n            .items = buf[0..],\n            .capacity = capacity,\n            .length = 0,\n            .allocator = allocator,\n        };\n    }\n};\n```\n:::\n\n\n\n\n\n### Implementing the `push` operation\n\nNow that we have written the basic logic to create a new `Stack` object,\nwe can start writing the logic responsible for performing a push operation.\nRemember, a push operation in a stack data structure is the operation\nresponsible for adding a new value to the stack.\n\nSo how can we add a new value to the `Stack` object that we have?\nThe `push()` function exposed below is a possible answer to this question.\nRemember from what we discussed at @sec-what-stack that values are always added to the top of the stack.\nThis means that this `push()` function must always find the element in the underlying array\nthat currently represents the top position of the stack, and then, add the input value there.\n\nFirst, we have an if statement in this function. This if statement is\nchecking whether we need to expand the underlying array to store\nthis new value that we are adding to the stack. In other words, maybe\nthe underlying array does not have enough capacity to store this new\nvalue, and, in this case, we need to expand our array to get the capacity that we need.\n\nSo, if the logical test in this if statement returns true, it means that the array\ndoes not have enough capacity, and we need to expand it before we store this new value.\nSo inside this if statement we are executing the necessary expressions to expand the underlying array.\nNotice that we use the allocator object to allocate a new array that is twice as bigger\nthan the current array (`self.capacity * 2`).\n\nAfter that, we use a different built-in function named `@memcpy()`. This built-in function\nis equivalent to the `memcpy()` function from the C Standard Library[^cmemcpy]. It is used to\ncopy the values from one block of memory to another block of memory. In other words,\nyou can use this function to copy the values from one array into another array.\n\n[^cmemcpy]: <https://www.tutorialspoint.com/c_standard_library/c_function_memcpy.htm>\n\nWe are using this `@memcpy()` built-in function to copy the values that are currently stored\nin the underlying array of the stack object (`self.items`) into our new and bigger array that\nwe have allocated (`new_buf`). After we execute this function, the `new_buf` contains a copy\nof the values that are present at `self.items`.\n\nNow that we have secured a copy of our current values in the `new_buf` object, we\ncan now free the memory currently allocated at `self.items`. After that, we just need\nto assign our new and bigger array to `self.items`. This is the sequence\nof steps necessary to expand our array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn push(self: *Stack, val: u32) !void {\n    if ((self.length + 1) > self.capacity) {\n        var new_buf = try self.allocator.alloc(\n            u32, self.capacity * 2\n        );\n        @memcpy(\n            new_buf[0..self.capacity], self.items\n        );\n        self.allocator.free(self.items);\n        self.items = new_buf;\n        self.capacity = self.capacity * 2;\n    }\n\n    self.items[self.length] = val;\n    self.length += 1;\n}\n```\n:::\n\n\n\n\nAfter we make sure that we have enough room to store this new value\nthat we are adding to the stack, all we have to do is to assign\nthis value to the top element in this stack, and, increase the\nvalue of the `length` attribute by one. We find the top element\nin the stack by using the `length` attribute.\n\n\n\n### Implementing the `pop` operation\n\nNow we can implement the pop operation of our stack object.\nThis is a much easier operation to implement, and the `pop()` method below summarises\nall the logic that is needed.\n\nWe just have to find the element in the underlying array that currently represents the top\nof the stack, and set this element to \"undefined\", to indicate that\nthis element is \"empty\". After that, we also need to decrease\nthe `length` attribute of the stack by one.\n\nIf the current length of the stack is zero, it means that there is\nno values being stored in the stack currently. So, in this case,\nwe could just return from the function and do nothing really.\nThis is what the if statement inside this function is checking for.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn pop(self: *Stack) void {\n    if (self.length == 0) return;\n\n    self.items[self.length - 1] = undefined;\n    self.length -= 1;\n}\n```\n:::\n\n\n\n\n\n\n### Implementing the `deinit` method\n\nWe have implemented the methods responsible for the two main operations\nassociated with the stack data structure, which is `pop()` and `push()`,\nand we also have implemented the method responsible for instantiating\na new `Stack` object, which is the `init()` method.\n\nBut now, we need to implement also the method responsible for destroying\na `Stack` object. In Zig, this task is commonly associated with the method\nnamed `deinit()`. Most struct objects in Zig have such method, and it\nis commonly nicknamed \"the destructor method\".\n\nIn theory, all we have to do to destroy the `Stack` object is to make\nsure that we free the allocated memory for the underlying array, using\nthe allocator object that is stored inside the `Stack` object.\nThis is what the `deinit()` method below is doing.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn deinit(self: *Stack) void {\n    self.allocator.free(self.items);\n}\n```\n:::\n\n\n\n\n\n\n\n## Making it generic\n\nNow that we have implemented the basic skeleton of our stack data structure,\nwe can now focus on discussing how can we make it generic. How can we make\nthis basic skeleton to work not only with `u32` values, but also, with any other\ndata type we want?\nFor example, we might need to create a stack object to store `User` values\nin it. How can we make this possible? The answer lies on the use of generics\nand `comptime`.\n\nAs I described at @sec-generic-struct, the basic idea is to write a generic\nfunction that returns a struct definition as output.\nIn theory, we do not need much to transform our `Stack` struct into a generic\ndata structure. All that we need to do is to transform the underlying array\nof the stack into a generic array.\n\nIn other words, this underlying array needs to be a \"chameleon\". It needs to adapt,\nand transform it into an array of any data type that we want. For example, if we need to create\na stack that will store `u8` values, then, this underlying array needs to be\na `u8` array (i.e. `[]u8`). But if we need to store `User` values instead, then,\nthis array needs to be a `User` array (i.e. `[]User`). Etc.\n\nWe do that by using a generic function. Because a generic function can receive a data type\nas input, and we can pass this data type to the struct definition of our `Stack` object.\nTherefore, we can use the generic function to create a `Stack` object that can store\nthe data type we want. If we want to create a stack structure that stores `User` values,\nwe pass the `User` data type to this generic function, and it will create for us\nthe struct definition that describes a `Stack` object that can store `User` values in it.\n\nLook at the code example below. I have omitted some parts of the `Stack` struct definition\nfor brevity reasons. However, if a specific part of our `Stack` struct is not exposed here\nin this example, then it is because this part did not change from the previous example.\nIt remains the same.\n\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn Stack(comptime T: type) type {\n    return struct {\n        items: []T,\n        capacity: usize,\n        length: usize,\n        allocator: Allocator,\n        const Self = @This();\n\n        pub fn init(allocator: Allocator,\n                    capacity: usize) !Stack(T) {\n            var buf = try allocator.alloc(T, capacity);\n            return .{\n                .items = buf[0..],\n                .capacity = capacity,\n                .length = 0,\n                .allocator = allocator,\n            };\n        }\n\n        pub fn push(self: *Self, val: T) !void {\n        // Truncate the rest of the struct\n    };\n}\n```\n:::\n\n\n\n\nNotice that we have created a function in this example named `Stack()`. This function\ntakes a type as input, and passes this type to the struct definition of our\n`Stack` object. The data member `items` is now, an array of type `T`, which is the\ndata type that we have provided as input to the function. The function argument\n`val` in the `push()` function is now a value of type `T` too.\n\nWe can just provide a data type to this function, and it will create a definition of a\n`Stack` object that can store values of the data type that we have provided. In the example below, we are creating\nthe definition of a\n`Stack` object that can store `u8` values in it. This definition is stored at the `Stacku8` object.\nThis `Stacku8` object becomes our new struct, it is the struct that we are going to use\nto create our `Stack` object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst Stacku8 = Stack(u8);\nvar stack = try Stacku8.init(allocator, 10);\ndefer stack.deinit();\ntry stack.push(1);\ntry stack.push(2);\ntry stack.push(3);\ntry stack.push(4);\ntry stack.push(5);\ntry stack.push(6);\n\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\"Stack capacity: {d}\\n\", .{stack.capacity});\n\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\n    \"Stack state: {any}\\n\",\n    .{stack.items[0..stack.length]}\n);\n```\n:::\n\n\n\n\n```\nStack len: 6\nStack capacity: 10\nStack len: 5\nStack len: 4\nStack state: { 1, 2, 3, 4, 0, 0, 0, 0, 0, 0 }\n```\n\nEvery generic data structure in the Zig Standard Library (`ArrayList`, `HashMap`, `SinlyLinkedList`, etc.)\nis implemented through this logic. They use a generic function to create the struct definition that can work\nwith the data type that you provided as input.\n\n\n\n\n## Conclusion\n\nThe full source code of the stack structure discussed in this chapter is freely available at the official\nrepository of this book. Just checkout the [`stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig)[^zig-stack]\nfor the `u32` version of our stack,\nand the [`generic_stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig)[^zig-stack2]\nfor the generic version, available inside the `ZigExamples` folder of the repository.\n\n\n[^zig-stack]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig>\n[^zig-stack2]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig>\n\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/12-file-op/execute-results/html.json b/_freeze/Chapters/12-file-op/execute-results/html.json
index 11b3e5f8..db6b2f0f 100644
--- a/_freeze/Chapters/12-file-op/execute-results/html.json
+++ b/_freeze/Chapters/12-file-op/execute-results/html.json
@@ -3,9 +3,7 @@
   "result": {
     "engine": "knitr",
     "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n\n# Filesystem and Input/Output (IO) {#sec-filesystem}\n\nIn this chapter we are going to discuss how to use the cross-platform structs and functions\nfrom the Zig Standard Library that can execute filesystem operations. Most of these functions and structs\ncomes from the `std.fs` module.\n\nWe are also going to talk about Input/Output (also known as IO) operations in Zig. Most of\nthese operations are made by using the structs and functions from `std.io` module, which defines\nfile descriptors for the *standard channels* of your system (`stdout` and `stdin`), and also,\nfunctions to create and use I/O streams.\n\n\n## Input/Output basics {#sec-io-basics}\n\nIf you have some experience in a high-level language, you have certainly used\nthese input and output functionalities before in this language. In other words, you certainly have\nbeen in a situation where you needed to sent some output to the user, or, to receive an input\nfrom the user.\n\nFor example, in Python we can receive some input from the user by using the `input()` built-in\nfunction. But we can also print (or \"show\") some output to the user by using the `print()`\nbuilt-in function. So yes, if you have programmed before in Python, you certainly have\nused these functions once before.\n\nBut do you know how these functions relate back to your operating system (OS)? How exactly\nthey are interacting with the resources of your OS to receive or sent some input/output.\nIn essence, these input/output functions from high-level languages are just abstractions\nover the *standard output* and *standard input* channels of your operating system.\n\nThis means that we receive an input, or send some output, through the operating system.\nIt is the OS that makes the bridge between the user and your program. Your program\ndoes not have a direct access to the user. It is the OS that intermediates every\nmessage exchanged between your program and the user.\n\nThe *standard output* and *standard input* channels of your OS are commonly known as the\n`stdout` and `stdin` channels of your OS, respectively. In some contexts, they are also\ncalled the *standard output device* and the *standard input device*. As the name suggests,\nthe *standard output* is the channel through which output flows, while the *standard input*\nis the channel in which input flows.\n\nFurthermore, OS's also normally create a dedicated channel for exchanging error messages, which is known as the\n*standard error* channel, or, the `stderr` channel. This is the channel to which error and warning messages\nare usually sent to. These are the messages that are normally displayed in red-like or orange-like colors\ninto your terminal.\n\nNormally, every OS (e.g. Windows, MacOS, Linux, etc.) creates a dedicated and separate set of\n*standard output*, *standard error* and *standard input* channels for every single program (or process) that runs in your computer.\nThis means that every program you write have a dedicated `stdin`, `stderr` and `stdout` that are separate\nfrom the `stdin`, `stderr` and `stdout` of other programs and processes that are currently running.\n\nThis is a behaviour from your OS. This does not come from the programming language that you are using.\nBecause as I sad earlier, input and output in programming languages, especially\nin high-level ones, are just a simple abstraction over the `stdin`, `stderr` and `stdout` from your current OS.\nThat is, your OS is the intermediary between every input/output operation made in your program,\nregardless of the programming language that you are using.\n\n\n### The writer and reader pattern {#sec-writer-reader}\n\nIn Zig, there is a pattern around input/output (IO). I (the author of this book) don't know if there\nis an official name for this pattern. But here, in this book, I will call it the \"writer and reader pattern\".\nIn essence, every IO operation in Zig is made through either a `GenericReader` or a `GenericWriter` object[^gen-zig].\n\nThese two data types come from the `std.io` module of the Zig Standard Library. As their names suggests, a\n`GenericReader` is an object that offers tools to read data from \"something\" (or \"somewhere\"), while a `GenericWriter`\noffers tools to write data into this \"something\". This \"something\" might be different things: like a\nfile that exists in your filesystem; or, it might be a network socket in your system[^sock]; or,\na continuous stream of data, like a standard input device from your system, that might be constantly\nreceiving new data from users, or, as another example, a live chat in a game that is constantly\nreceiving and displaying new messages from the players of the game.\n\n[^gen-zig]: Previously, these objects were known as the `Reader` and `Writer` objects.\n[^sock]: The socket objects that we have created at @sec-create-socket, are examples of network sockets.\n\nSo, if you want to **read** data from something, or somewhere, it means that you need to use a `GenericReader` object.\nBut if you need instead, to **write** data into this \"something\", then, you need to use a `GenericWriter` object instead.\nBoth of these objects are normally created from a file descriptor object. More specifically, through the `writer()` and `reader()`\nmethods of this file descriptor object. If you are not familiar with this type of object, go to the next section.\n\nEvery `GenericWriter` object have methods like `print()`, which allows you to write/send a formatted string\n(i.e. this formatted string is like a `f` string in Python, or, similar to the `printf()` C function)\ninto the \"something\" (file, socket, stream, etc.) that you are using. It also have a `writeAll()` method, which allows you to\nwrite a string, or, an array of bytes into the \"something\".\n\nLikewise, every `GenericReader` object have methods like `readAll()`, which allows you to read the\ndata from the \"something\" (file, socket, stream, etc.) until it fills a particular array (i.e. a \"buffer\") object.\nIn other words, if you provide an array object of 300 `u8` values to `readAll()`, then, this method attempts to read 300 bytes\nof data from the \"something\", and it stores them into the array object that you have provided.\n\nWe also have other methods, like the `readAtLeast()` method, which allows you to specify how\nmany bytes exactly you want to read from the \"something\". In more details, if you give the\nnumber $n$ as input to this method, then, it will attempt to read at least $n$ bytes of data\nfrom the \"something\". The \"something\" might have less than $n$ bytes of data available for you\nto read, so, it is not guaranteed that you will get precisely $n$ bytes as result.\n\nAnother useful method is `readUntilDelimiterOrEof()`. In this method, you specify a \"delimiter character\".\nThe idea is that this function will attempt to read as many bytes of data as possible from the \"something\",\nuntil it encounters the end of the stream, or, it encounters the \"delimiter character\" that you have specified.\n\nIf you don't know exactly how many bytes will come from the \"something\", you may find the `readAllAlloc()` method\nuseful. In essence, you provide an allocator object to this method, so that it can allocate more space if needed.\nAs consequence, this method will try to read all bytes of the \"something\", and, if it runs out of space at some point\nduring the \"reading process\", it uses the allocator object to allocate more space to continue reading the bytes.\nAs result, this method returns a slice to the array object containing all the bytes read.\n\nThis is just a quick description of the methods present in these types of objects. But I recommend you\nto read the official docs, both for\n[`GenericWriter`](https://ziglang.org/documentation/master/std/#std.io.GenericWriter)[^gen-write] and\n[`GenericReader`](https://ziglang.org/documentation/master/std/#std.io.GenericReader)[^gen-read].\nI also think it is a good idea to read the source code of the modules in the Zig Standard Library\nthat defines the methods present in these objects, which are the\n[`Reader.zig`](https://github.com/ziglang/zig/blob/master/lib/std/io/Reader.zig)[^mod-read]\nand [`Writer.zig`]()[^mod-write].\n\n[^gen-read]: <https://ziglang.org/documentation/master/std/#std.io.GenericReader>.\n[^gen-write]: <https://ziglang.org/documentation/master/std/#std.io.GenericWriter>.\n[^mod-read]: <https://github.com/ziglang/zig/blob/master/lib/std/io/Reader.zig>.\n[^mod-write]: <https://github.com/ziglang/zig/blob/master/lib/std/io/Writer.zig>.\n\n\n\n### Introducing file descriptors {#sec-file-descriptor}\n\nA \"file descriptor\" object is a core component behind every IO operation that is made in any operating system (OS).\nSuch object is an identifier for a particular input/output (IO) resource from your OS [@wiki_file_descriptor].\nIt describes and identifies this particular resource. An IO resource might be:\n\n- an existing file in your filesystem.\n- an existing network socket.\n- other types of stream channels.\n- a pipeline (or just \"pipe\") in your terminal[^pipes].\n\n[^pipes]: A pipeline is a mechanism for inter-process communication, or, inter-process IO. You could also interpret a pipeline as a \"set of processes that are chained together, through the standard input/output devices of the system\". At Linux for example, a pipeline is created inside a terminal, by connecting two or more terminal commands with the \"pipe\" character (`|`).\n\nFrom the bullet points listed above, we know that although the term \"file\" is present,\na \"file descriptor\" might describe something more than just a file.\nThis concept of a \"file descriptor\" comes from the Portable Operating System Interface (POSIX) API,\nwhich is a set of standards that guide how operating systems across the world should be implemented,\nto maintain compatibility between them.\n\nA file descriptor not only identifies the input/output resource that you are using to receive or send some data,\nbut it also describes where this resource is, and also, which IO mode this resource is currently using.\nFor example, this IO resource might be using only the \"read\" IO mode, which means that this resource\nis open to \"read operations\", while \"write operations\" are not authorized.\nThese IO modes are essentially the modes that you provide to the argument `mode`\nfrom the `fopen()` C function, and also, from the `open()` Python built-in function.\n\nIn C, a \"file descriptor\" is a `FILE` pointer, but, in Zig, a file descriptor is a `File` object.\nThis data type (`File`) is described in the `std.fs` module of the Zig Standard Library.\nWe normally don't create a `File` object directly in our Zig code. Instead, we normally get such object as result when we\nopen an IO resource. In other words, we normally ask our OS to open a particular IO resource for us,\nand, if the OS do open successfully this IO resource, the OS normally handles back to us\na file descriptor to this particular IO resource.\n\nSo you usually get a `File` object by using functions and methods from the Zig Standard Library\nthat asks the OS to open some IO resource, like the `openFile()` method that opens a file in the\nfilesystem. The `net.Stream` object that we have created at @sec-create-socket is also a type of\nfile descriptor object.\n\n\n### The *standard output*\n\nYou already saw across this book, how can we access and use specifically the `stdout` in Zig\nto send some output to the user.\nFor that, we use the `getStdOut()` function from the `std.io` module. This function returns\na file descriptor that describes the `stdout` channel of your current OS. Through this file\ndescriptor object, we can read from or write stuff to the `stdout` of our program.\n\nAlthough we can read stuff recorded into the `stdout` channel, we normally only\nwrite to (or \"print\") stuff into this channel. The reason is very similar to what we discussed at\n@sec-read-http-message, when we were discussing what \"reading from\" versus \"writing to\" the connection\nobject from our small HTTP Server project would mean.\n\nWhen we write stuff into a channel, we are essentially sending data to the other end of this channel.\nIn contrast, when we read stuff from this channel, we are essentially reading the data that was sent\nthrough this channel. Since the `stdout` is a channel to send output to the user, the key verb here\nis **send**. We want to send something to someone, and, as consequence, we want to **write** something\ninto some channel.\n\nThat is why, when we use `getStdOut()`, most of the times, we also use the `writer()` method from the `stdout` file descriptor,\nto get access to a writer object that we can use to write stuff into this `stdout` channel.\nMore specifically, this `writer()` method returns a `GenericWriter` object. One of the\nmain methods of this `GenericWriter` object is the `print()` method that we have used\nbefore to write (or \"print\") a formatted string into the `stdout` channel.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    try stdout.writeAll(\n        \"This message was written into stdout.\\n\"\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nThis message was written into stdout.\n```\n\n\n:::\n:::\n\n\n\n\n\n\nThis `GenericWriter` object is like any other generic writer object that you would normally get from a file descriptor object.\nSo, the same methods from a generic writer object that you would use while writing files to the filesystem for example, you could also\nuse them here, from the file descriptor object of `stdout`, and vice-versa.\n\n\n### The *standard input*\n\nYou can access the *standard input* (i.e. `stdin`) in Zig by using the `getStdIn()` function from the `std.io` module.\nLike its brother (`getStdOut()`), this function also returns a file descriptor object that describes the `stdin` channel\nof your OS.\n\nBecause we want to receive some input from the user, the key verb here becomes **receive**, and, as consequence,\nwe usually want to **read** data from the `stdin` channel, instead of writing data into it. So, we normally use\nthe `reader()` method of the file descriptor object returned by `getStdIn()`, to get access to a `GenericReader`\nobject that we can use to read data from `stdin`.\n\nIn the example below, we are creating a small buffer capable of holding 20 characters. Then, we try to read\nthe data from the `stdin` with the `readUntilDelimiterOrEof()` method, and save this data into the `buffer` object.\nAlso notice that we are reading the data from the `stdin` until we hit a new line character (`'\\n'`).\n\nIf you execute this program, you will notice that it stops the execution, ands start to wait indefinitely\nfor some input from the user. In other words, you need to type your name into the terminal, and then, you press Enter to\nsend your name to `stdin`. After you send your name to `stdin`, the program reads this input, and continues with the execution,\nby printing the given name to `stdout`. In the example below, I typed my name (Pedro) into the terminal, and then, pressed Enter.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst stdin = std.io.getStdIn().reader();\npub fn main() !void {\n    try stdout.writeAll(\"Type your name\\n\");\n    var buffer: [20]u8 = undefined;\n    @memset(buffer[0..], 0);\n    _ = try stdin.readUntilDelimiterOrEof(buffer[0..], '\\n');\n    try stdout.print(\"Your name is: {s}\\n\", .{buffer});\n}\n```\n:::\n\n\n\n\n```\nType your name\nYour name is: Pedro\n\n```\n\n\n### The *standard error*\n\nThe *standard error* (a.k.a. the `stderr`) works exactly the same as `stdout` and `stdin`.\nYou just call the `getStdErr()` function from the `std.io` module, and you get the file descriptor to `stderr`.\nIdeally, you should write only error or warning messages to `stderr`, because this is\nthe purpose of this channel.\n\n\n\n\n\n## Buffered IO\n\nAs we described at @sec-io-basics, input/output (IO) operations are made directly by the operating system.\nIt is the OS that manages the IO resource that you want to use for your IO operations.\nThe consequence of this fact is that IO operations are heavily based on system calls (i.e. calling the operating system directly).\n\nJust to be clear, there is nothing particularly wrong with system calls. We use them all the time on\nany serious codebase written in any low-level programming language. However, system calls are\nalways orders of magnitude slower than many different types of operations.\n\nSo is perfectly fine to use a system call once in a while. But when these system calls are used often,\nyou can clearly notice most of the time the loss of performance in your application. So, the good rule of thumbs\nis to use a system call only when it is needed, and also, only in infrequent situations, to reduce\nthe number of system calls performed to a minimum.\n\n\n### Understanding how buffered IO works\n\nBuffered IO is a strategy to achieve better performance. It is used to reduce the number of system calls made by IO operations, and, as\nconsequence, achieve a much higher performance. At @fig-unbuffered-io and @fig-buffered-io you can find two different diagrams\nwhich presents the difference between read operations performed in an unbuffered IO environment versus a buffered IO environment.\n\nTo give a better context to these diagrams, let's suppose that we have a text file that contains the famous Lorem ipsum text[^lorem]\nin our filesystem. Let's also suppose that these diagrams at @fig-unbuffered-io and @fig-buffered-io\nare showing the read operations that we are performing to read the Lorem ipsum text from this text file.\nThe first thing you will notice when looking at these diagrams, is that in an unbuffered environment\nthe read operations leads to many system calls.\nMore precisely, in the diagram exposed at @fig-unbuffered-io we get one system call per each byte that we read from the text file.\nOn the other hand, at @fig-buffered-io we have only one system call at the very beginning.\n\nWhen we use a buffered IO system, at the first read operation we perform, instead of sending one single byte directly\nto our program, the OS first sends a chunk of bytes from the file to a buffer object (i.e. an array).\nThis chunk of bytes are cached/stored inside this buffer object.\n\nTherefore, from now on, for every new read operation that you perform, instead of making a new system call to ask\nfor the next byte in the file to the OS, this read operation is redirected to the buffer object, that have\nthis next byte already cached and ready to go.\n\n\n[^lorem]: <https://www.lipsum.com/>.\n\n\n![Unbuffered IO](./../Figures/unbuffered-io.png){#fig-unbuffered-io width=60%}\n\n![Buffered IO](./../Figures/buffered-io.png){#fig-buffered-io}\n\n\n\nThis is the basic logic behind buffered IO systems. The size of the buffer object depends on multiple factors. But it is usually\nequal to the size of a full page of memory (4096 bytes). If we follow this logic, then, the OS reads the first 4096 bytes\nof the file and caches it into the buffer object. As long as your program does not consume all of these 4096 bytes from the buffer,\nyou will not create new system calls.\n\nHowever, as soon as you consume all of these 4096 bytes from the buffer, it means that there is no bytes left in the buffer.\nIn this situation, a new system call is made to ask the OS to send the next 4096 bytes in the file, and once again,\nthese bytes are cached into the buffer object, and the cycle starts once again.\n\n\n### Buffered IO across different languages\n\nIO operations made through a `FILE` pointer in C are buffered\nby default, so, at least in C, you don't need to worry about this subject. But in contrast, IO operations in both Rust and Zig are not\nbuffered depending on which functions from the standard libraries that you are using.\n\nFor example, in Rust, buffered IO is implemented through the `BufReader` and `BufWriter` structs, while in Zig, it is implemented\nthrough the `BufferedReader` and `BufferedWriter` structs.\nSo any IO operation that you perform through the `GenericWriter` and `GenericReader` objects\nthat I presented at @sec-writer-reader are not buffered, which means that these objects\nmight create a lot of system calls depending on the situation.\n\n\n### Using buffered IO in Zig\n\nUsing buffered IO in Zig is actually very easy. All you have to do is to just\ngive the `GenericWriter` object to the `bufferedWriter()` function, or, to give the `GenericReader`\nobject to the `bufferedReader()` function. These functions come from the `std.io` module,\nand they will construct the `BufferedWriter` or `BufferedReader` object for you.\n\nAfter you create this new `BufferedWriter` or `BufferedReader` object, you can call the `writer()`\nor `reader()` method of this new object, to get access to a new (and buffered) generic reader or\ngeneric writer.\n\nLet's describe the process once again. Every time that you have a file descriptor object, you first get the generic writer or generic reader\nobject from it, by calling the `writer()` or `reader()` methods of this file descriptor object.\nThen, you provide this generic writer or generic reader to the `bufferedWriter()` or `bufferedReader()`\nfunction, which creates a new `BufferedWriter` or `BufferedReader` object. Then, you call\nthe `writer()` or `reader()` methods of this buffered writer or buffered reader object,\nwhich gives you access to a generic writer or a generic reader object that is buffered.\n\nTake this program as an example. This program is demonstrating the process exposed at @fig-buffered-io.\nWe are simply opening a text file that contains the Lorem ipsum text, and then, we create a buffered IO reader object\nat `bufreader`, and we use this `bufreader` object to read the contents of this file into a buffer object, then,\nwe end the program by printing this buffer to `stdout`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar file = try std.fs.cwd().openFile(\n    \"ZigExamples/file-io/lorem.txt\", .{}\n);\ndefer file.close();\nvar buffered = std.io.bufferedReader(file.reader());\nvar bufreader = buffered.reader();\n\nvar buffer: [1000]u8 = undefined;\n@memset(buffer[0..], 0);\n\n_ = try bufreader.readUntilDelimiterOrEof(\n    buffer[0..], '\\n'\n);\ntry stdout.print(\"{s}\\n\", .{buffer});\n```\n:::\n\n\n\n\n```\nLorem ipsum dolor sit amet, consectetur\nadipiscing elit. Sed tincidunt erat sed nulla ornare, nec\naliquet ex laoreet. Ut nec rhoncus nunc. Integer magna metus,\nultrices eleifend porttitor ut, finibus ut tortor. Maecenas\nsapien justo, finibus tincidunt dictum ac, semper et lectus.\nVivamus molestie egestas orci ac viverra. Pellentesque nec\narcu facilisis, euismod eros eu, sodales nisl. Ut egestas\nsagittis arcu, in accumsan sapien rhoncus sit amet. Aenean\nneque lectus, imperdiet ac lobortis a, ullamcorper sed massa.\nNullam porttitor porttitor erat nec dapibus. Ut vel dui nec\nnulla vulputate molestie eget non nunc. Ut commodo luctus ipsum,\nin finibus libero feugiat eget. Etiam vel ante at urna tincidunt\nposuere sit amet ut felis. Maecenas finibus suscipit tristique.\nDonec viverra non sapien id suscipit.\n```\n\nDespite being a buffered IO reader, this `bufreader` object is similar to any other `GenericReader` object,\nand have the exact same methods. So, although these two types of objects perform very different IO operations,\nthey have the same interface, so you, the programmer, can interchangeably use them\nwithout the need to change anything in your source code.\nSo a buffered IO reader or a buffered IO writer objects have the same methods than its generic and unbuffered brothers,\ni.e. the generic reader and generic writer objects that I presented at @sec-writer-reader.\n\n::: {.callout-tip}\nIn general, you should always use a buffered IO reader or a buffered IO writer object to perform\nIO operations in Zig. Because they deliver better performance to your IO operations.\n:::\n\n\n## Filesystem basics\n\nNow that we have discussed the basics around Input/Output operations in Zig, we need to\ntalk about the basics around filesystems, which is another core part of any operating system.\nAlso, filesystems are related to input/output, because the files that we store and create in our\ncomputer are considered an IO resource, as we described at @sec-file-descriptor.\n\n\n### The concept of current working directory (CWD)\n\nThe working directory is the folder on your computer where you are currently rooted at.\nIn other words, it is the folder that your program is currently looking at.\nTherefore, whenever you are executing a program, this program is always working with\na specific folder on your computer. It is always in this folder that the program will initially\nlook for the files you require, and it is also in this folder that the program\nwill initially save all the files you ask it to save.\n\nThe working directory is determined by the folder from which you invoke your program\nin the terminal. In other words, if you are in the terminal of your OS, and you\nexecute a binary file (i.e. a program) from this terminal, the folder to which your terminal\nis pointing at is the current working directory of your program that is being executed.\n\nAt @fig-cwd we have an example of me executing a program from the terminal. We are executing\nthe program outputted by the `zig` compiler by compiling the Zig module named `hello.zig`.\nThe CWD in this case is the `zig-book` folder. In other words, while the `hello.zig` program\nis executing, it will be looking at the `zig-book` folder, and any file operation that we perform\ninside this program, will be using this `zig-book` folder as the \"starting point\", or, as the \"central focus\".\n\n![Executing a program from the terminal](./../Figures/cwd.png){#fig-cwd}\n\nJust because we are rooted inside a particular folder (in the case of @fig-cwd, the `zig-book` folder) of our computer,\nit doesn't mean that we cannot access or write resources in other locations of our computer.\nThe current working directory (CWD) mechanism just defines where your program will look first\nfor the files you ask for. This does not prevent you from accessing files that are located\nelsewhere on your computer. However, to access any file that is in a folder other than your\ncurrent working directory, you must provide a path to that file or folder.\n\n\n### The concept of paths\n\nA path is essentially a location. It points to a location in your filesystem. We use\npaths to describe the location of files and folders in our computer.\nOne important aspect about paths is that they are always written inside strings,\ni.e. they are always provided as text values.\n\nThere are two types of paths that you can provide to any program in any OS: a relative path, or an absolute path.\nAbsolute paths are paths that start at the root of your filesystem, and go all the way to the file name or the specific folder\nthat you are referring to. This type of path is called absolute, because it points to an unique and absolute location on your computer.\nThat is, there is no other existing location on your computer that corresponds to this path. It is an unique identifier.\n\nIn Windows, an absolute path is a path that starts with a hard disk identifier (e.g. `C:/Users/pedro`).\nOn the other hand, absolute paths in Linux and MacOS, are paths that start with a forward slash character (e.g. `/usr/local/bin`).\nNotice that a path is composed by \"segments\". Each segment is connected to each other by a slash character (`\\` or `/`).\nOn Windows, the backward slash (`\\`) is normally used to connect the path segments. While on Linux and MacOS, the forward\nslash (`/`) is the character used to connect path segments.\n\nA relative path is a path that start at the CWD. In other words, a relative path is\n\"relative to the CWD\". The path used to access the `hello.zig` file at @fig-cwd is an example of a relative path. This path\nis reproduced below. This path begins at the CWD, which in the context of @fig-cwd, is the `zig-book` folder,\nthen, it goes to the `ZigExamples` folder, then, into `zig-basics`, then, to the `hello.zig` file.\n\n```\nZigExamples/zig-basics/hello_world.zig\n```\n\n\n### Path wildcards\n\nWhen providing paths, especially relative paths, you have the option of using a *wildcard*.\nThere are two commonly used *wildcards* in paths, which are \"one period\" (.) and \"two periods\" (..).\nIn other words, these two specific characters have special meanings when used in paths,\nand can be used on any operating system (Mac, Windows, Linux, etc.). That is, they\nare \"cross platform\".\n\nThe \"one period\" represents an alias for the current directory.\nThis means that the relative paths `\"./Course/Data/covid.csv\"` and `\"Course/Data/covid.csv\"` are equivalent.\nOn the other hand, the \"two periods\" refers to the previous directory.\nFor example, the path `\"Course/..\"` is equivalent to the path `\".\"`, that is, the current working directory.\n\nTherefore, the path `\"Course/..\"` refers to the folder before the `Course` folder.\nAs another example, the path `\"src/writexml/../xml.cpp\"` refers to the file `xml.cpp`\nthat is inside the folder before the `writexml` folder, which in this example is the `src` folder.\nTherefore, this path is equivalent to `\"src/xml.cpp\"`.\n\n\n\n\n## The CWD handler\n\nIn Zig, filesystem operations are usually made through a directory handler object.\nA directory handler in Zig is an object of type `Dir`, which is an object that describes\na particular folder in the filesystem of our computer.\nYou normally create a `Dir` object, by calling the `std.fs.cwd()` function.\nThis function returns a `Dir` object that points to (or, that describes) the\ncurrent working directory (CWD).\n\nThrough this `Dir` object, you can create new files, or modify, or read existing ones that are\ninside your CWD. In other words, a `Dir` object is the main entrypoint in Zig to perform\nmultiple types of filesystem operations.\nIn the example below, we are creating this `Dir` object, and storing it\ninside the `cwd` object. Although we are not using this object at this code example,\nwe are going to use it a lot over the next examples.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\n_ = cwd;\n```\n:::\n\n\n\n\n\n\n\n\n\n\n\n## File operations\n\n### Creating files {#sec-creating-files}\n\nWe create new files by using the `createFile()` method from the `Dir` object.\nJust provide the name of the file that you want to create, and this function will\ndo the necessary steps to create such file. You can also provide a relative path to this function,\nand it will create the file by following this path, which is relative to the CWD.\n\nThis function might return an error, so, you should use `try`, `catch`, or any of the other methods presented\nat @sec-error-handling to handle the possible error. But if everything goes well,\nthis `createFile()` method returns a file descriptor object (i.e. a `File` object) as result,\nthrough which you can add content to the file with the IO operations that I presented before.\n\nTake this code example below. In this example, we are creating a new text file\nnamed `foo.txt`. If the function `createFile()` succeeds, the object named `file` will contain a file descriptor\nobject, which we can use to write (or add) new content to the file, like we do in this example, by using\na buffered writer object to write a new line of text to the file.\n\nNow, a quick note, when we create a file descriptor object in C, by using a C function like `fopen()`, we must always close the file\nat the end of our program, or, as soon as we complete all operations that we wanted to perform\non the file. In Zig, this is no different. So everytime we create a new file, this file remains\n\"open\", waiting for some operation to be performed. As soon as we are done with it, we always have\nto close this file, to free the resources associated with it.\nIn Zig, we do this by calling the method `close()` from the file descriptor object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.createFile(\"foo.txt\", .{});\n// Don't forget to close the file at the end.\ndefer file.close();\n// Do things with the file ...\nvar fw = file.writer();\n_ = try fw.writeAll(\n    \"Writing this line to the file\\n\"\n);\n```\n:::\n\n\n\n\n\nSo, in this example we not only have created a file into the filesystem,\nbut we also wrote some data into this file, using the file descriptor object\nreturned by `createFile()`. If the file that you are trying to create\nalready exists in your filesystem, this `createFile()` call will\noverwrite the contents of the file, or, in other words, it will\nin erase all the contents of the existing file.\n\nIf you don't want this to happen, meaning, that you don't want to overwrite\nthe contents of the existing file, but you want to write data to this file anyway\n(i.e. you want to append data to the file), you should use the `openFile()`\nmethod from the `Dir` object.\n\nAnother important aspect about `createFile()` is that this method creates a file\nthat is not open to read operations by default. It means that you cannot read this file.\nYou are not allowed to.\nSo for example, you might want to write some stuff into this file at the beginning of the execution\nof your program. Then, at a future point in your program you might need to read what you\nwrote in this file. If you try to read data from this file, you will likely\nget a `NotOpenForReading` error as result.\n\n\nBut how can you overcome this barrier? How can you create a file that is open\nto read operations? All you have to do, is to set the `read` flag to true\nin the second argument of `createFile()`. When you set this flag to true,\nthen the file get's create with \"read permissions\", and, as consequence,\na program like this one below becomes valid:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.createFile(\n    \"foo.txt\",\n    .{ .read = true }\n);\ndefer file.close();\n\nvar fw = file.writer();\n_ = try fw.writeAll(\"We are going to read this line\\n\");\n\nvar buffer: [300]u8 = undefined;\n@memset(buffer[0..], 0);\ntry file.seekTo(0);\nvar fr = file.reader();\n_ = try fr.readAll(buffer[0..]);\ntry stdout.print(\"{s}\\n\", .{buffer});\n```\n:::\n\n\n\n\n\n```\nWe are going to read this line\n```\n\n\nIf you are not familiar with position indicators, you might not recognize the method\n`seekTo()`. If that is your case, do not worry,\nwe are going to talk more about this method at @sec-indicators. But essentially\nthis method is moving the position indicator back to the beginning of the file,\nso that we can read the contents of the file from the beginning.\n\n\n### Opening files and appending data to it\n\nOpening files is easy. Just use the `openFile()` method instead of `createFile()`.\nIn the first argument of `openFile()` you provide the path to the file that\nyou want to open. Then, on the second argument you provide the flags (or, the options)\nthat dictates how the file is opened.\n\nYou can see the full list of options for `openFile()` by visiting the documentation for\n[`OpenFlags`](https://ziglang.org/documentation/master/std/#std.fs.File.OpenFlags)[^oflags].\nBut the main flag that you will most certainly use is the `mode` flag.\nThis flag specifies the IO mode that the file will be using when it get's opened.\nThere are three IO modes, or, three values that you can provide to this flag, which are:\n\n- `read_only`, allows only read operations on the file. All write operations are blocked.\n- `write_only`, allows only write operations on the file. All read operations are blocked. \n- `read_write`, allows both write and read operations on the file.\n\n[^oflags]: <https://ziglang.org/documentation/master/std/#std.fs.File.OpenFlags>\n\nThese modes are similar to the modes that you provide to the `mode` argument of the\n`open()` Python built-in function[^py-open], or, the `mode` argument of the\n`fopen()` C function[^c-open].\nIn the code example below, we are opening the `foo.txt` text file with a `write_only` mode,\nand appending a new line of text to the end of the file. We use `seekFromEnd()` this time\nto guarantee that we are going to append the text to the end of the file. Once again, methods\nsuch as `seekFromEnd()` are described in more depth at @sec-indicators.\n\n[^py-open]: <https://docs.python.org/3/tutorial/inputoutput.html#reading-and-writing-files>\n[^c-open]: <https://www.tutorialspoint.com/c_standard_library/c_function_fopen.htm>\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.openFile(\n    \"foo.txt\", .{ .mode = .write_only }\n);\ndefer file.close();\ntry file.seekFromEnd(0);\nvar fw = file.writer();\n_ = try fw.writeAll(\"Some random text to write\\n\");\n```\n:::\n\n\n\n\n\n### Deleting files\n\nSometimes, we just need to delete/remove the files that we have.\nTo do that, we use the `deleteFile()` method. You just provide the path of the\nfile that you want to delete, and this method will try to delete the file located\nat this path.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.deleteFile(\"foo.txt\");\n```\n:::\n\n\n\n\n### Copying files\n\nTo copy existing files, we use the `copyFile()` method. The first argument in this method\nis the path to the file that you want to copy. The second argument is a `Dir` object, i.e. a directory handler,\nmore specifically, a `Dir` object that points to the folder in your computer where you want to\ncopy the file to. The third argument is the new path of the file, or, in other words, the new location\nof the file. The fourth argument is the options (or flags) to be used in the copy operation.\n\nThe `Dir` object that you provide as input to this method will be used to copy the file to\nthe new location. You may create this `Dir` object before calling the `copyFile()` method.\nMaybe you are planning to copy the file to a completely different location in your computer,\nso it might be worth to create a directory handler to that location. But if you are copying the\nfile to a subfolder of your CWD, then, you can just simply pass the CWD handler to this argument.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.copyFile(\n    \"foo.txt\",\n    cwd,\n    \"ZigExamples/file-io/foo.txt\",\n    .{}\n);\n```\n:::\n\n\n\n\n\n### Read the docs!\n\nThere are some other useful methods for file operations available at `Dir` objects,\nsuch as the `writeFile()` method, but I recommend you to read the docs for the\n[`Dir` type](https://ziglang.org/documentation/master/std/#std.fs.Dir)[^zig-dir]\nto explore the other available methods, since I already talked too much about them.\n\n\n[^zig-dir]: <https://ziglang.org/documentation/master/std/#std.fs.Dir>\n\n\n\n\n## Position indicators {#sec-indicators}\n\nA position indicator is like a type of cursor, or, an index. This \"index\" identifies the current\nlocation in the file (or, in the data stream) that the file descriptor object that you have\nis currently looking at.\nWhen you create a file descriptor, the position indicator starts at the beginning of the file,\nor, at the beginning of the stream. When you read from or write into the file (or socket, or data stream, etc.)\ndescribed by this file descriptor object, you end up moving the position indicator.\n\nIn other words, any IO operation have a common side effect, which is to move the position indicator.\nFor example, suppose that we have a file of 300 bytes total in size. If you\nread 100 bytes from the file, then, the position indicator moves 100 bytes forward. If you try\nto write 50 bytes into this same file, these 50 bytes will be written from the current\nposition indicated by the position indicator. Since the indicator is at a 100 bytes forward from\nthe beginning of the file, these 50 bytes would be written in the middle of the file.\n\nThis is why we have used the `seekTo()` method at the last code example presented at @sec-creating-files.\nWe have used this method to move the position indicator back to the beginning of the file, which\nwould make sure that we would write the text that we wanted to write from the beginning of the file,\ninstead of writing it from the middle of the file. Because before the write operation, we had\nperformed a read operation, which means that the position indicator was moved in this read operation.\n\nThe position indicators of a file descriptor object can be changed (or altered) by using the\n\"seek\" methods from this file descriptor, which are: `seekTo()`, `seekFromEnd()` and `seekBy()`.\nThese methods have the same effect, or, the same responsibility that the\n[`fseek()`](https://en.cppreference.com/w/c/io/fseek)[^c-fseek] C function.\n\n[^c-fseek]: <https://en.cppreference.com/w/c/io/fseek>\n\n\nConsidering that `offset` refers to the index that you provide as input to these \"seek\" methods,\nthe bullet points below summarises what is the effect of each of these methods.\nAs a quick note, in the case of `seekFromEnd()` and `seekBy()`, the `offset` provided can be either a\npositive or a negative index.\n\n- `seekTo()` will move the position indicator to the location that is `offset` bytes from the beginning of the file.\n- `seekFromEnd()` will move the position indicator to the location that is `offset` bytes from the end of the file.\n- `seekBy()` will move the position indicator to the location that is `offset` bytes from the current position in the file.\n\n\n\n\n\n\n\n## Directory operations\n\n### Iterating through the files in a directory\n\nOne of the most classic tasks related to filesystem is to be able\nto iterate through the existing files in a directory. To iterate over the\nfiles in a directory, we need to create an iterator object.\n\nYou can produce such iterator object by using either the `iterate()` or `walk()` methods\nof a `Dir` object. Both methods return an iterator object as output, which you can advance by using the\n`next()` method. The difference between these methods, is that `iterate()` returns a non-recursive iterator,\nwhile `walk()` does. It means that the iterator returned by `walk()` will not only iterate through\nthe files available in the current directory, but also, through the files from any subdirectory found\ninside the current directory.\n\nIn the example below, we are displaying the names of the files stored inside the\ndirectory `ZigExamples/file-io`. Notice that we had to open this directory through\nthe `openDir()` function. Also notice that we provided the flag `iterate` in the\nsecond argument of `openDir()`. This flag is important, because without this flag,\nwe would not be allowed to iterate through the files in this directory.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst dir = try cwd.openDir(\n    \"ZigExamples/file-io/\",\n    .{ .iterate = true }\n);\nvar it = dir.iterate();\nwhile (try it.next()) |entry| {\n    try stdout.print(\n        \"File name: {s}\\n\",\n        .{entry.name}\n    );\n}\n```\n:::\n\n\n\n\n```\nFile name: create_file_and_write_toit.zig\nFile name: create_file.zig\nFile name: lorem.txt\nFile name: iterate.zig\nFile name: delete_file.zig\nFile name: append_to_file.zig\nFile name: user_input.zig\nFile name: foo.txt\nFile name: create_file_and_read.zig\nFile name: buff_io.zig\nFile name: copy_file.zig\n```\n\n\n### Creating new directories\n\nThere are two methods that are important when it comes to\ncreating directories, which are `makeDir()` and `makePath()`.\nThe difference between these two methods is that `makeDir()` can\nonly create one single directory in the current directory in each call,\nwhile `makePath()` is capable of recursively create subdirectories in the same call.\n\n\nThis is why the name of this method is \"make path\". It will create as many\nsubdirectories as necessary to create the path that you provided as input.\nSo, if you provide the path `\"sub1/sub2/sub3\"` as input to this method,\nit will create three different subdirectories, `sub1`, `sub2` and `sub3`,\nwithin the same function call. In contrast, if you provided such path\nas input to `makeDir()`, you would likely get an error as result, since\nthis method can only create a single subdirectory.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.makeDir(\"src\");\ntry cwd.makePath(\"src/decoders/jpg/\");\n```\n:::\n\n\n\n\n### Deleting directories\n\nTo delete a directory, just provide the path to the directory that you want to delete\nas input to the `deleteDir()` method from a `Dir` object. In the example below,\nwe are deleting the `src` directory that we have just created in the previous example.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.deleteDir(\"src\");\n```\n:::\n\n\n\n\n\n## Conclusion\n\nIn this chapter, I have described how to perform in Zig the most common filesystem and IO operations.\nBut you might feel the lack of some other, less common, operation in this chapter, such as: how to rename files,\nor how to open a directory, or how to create symbolic links, or how to use `access()` to test if a particular\npath exists in your computer. But for all of these less common tasks, I recommend you to read\nthe documentation of the [`Dir` type](https://ziglang.org/documentation/master/std/#std.fs.Dir)[^zig-dir]\n, since you can find a good description of these cases there.\n\n\n\n\n",
-    "supporting": [
-      "12-file-op_files"
-    ],
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/13-image-filter/execute-results/html.json b/_freeze/Chapters/13-image-filter/execute-results/html.json
index 186c9f2e..60992ffa 100644
--- a/_freeze/Chapters/13-image-filter/execute-results/html.json
+++ b/_freeze/Chapters/13-image-filter/execute-results/html.json
@@ -1,11 +1,9 @@
 {
-  "hash": "f7b409727ce7dda7b1ad5ee0a774b918",
+  "hash": "57cac9850f9e50201803beaf886a66e8",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 4 - Developing an image filter\n\nIn this chapter we are going to build a new project. The objective of\nthis project is to write a program that applies a filter over an image.\nMore specifically, a \"grayscale filter\", which transforms\nany color image into a grayscale image.\n\nWe are going to use the image displayed at @fig-pascal in this project.\nIn other words, we want to transform this colored image into a grayscale image,\nby using our \"image filter program\" written in Zig.\n\n![A photo of the chilean-american actor Pedro Pascal. Source: Google Images.](../ZigExamples/image_filter/pedro_pascal.png){#fig-pascal}\n\nWe don't need to write a lot of code to build such \"image filter program\". However, we first need\nto understand how digital images work. That is why we begin this chapter\nby explaining the theory behind digital images and how colors are represented in modern computers.\nWe also give a brief explanation about the PNG (Portable Network Graphics) file format, which is the format used\nin the example images.\n\nAt the end of this chapter, we should have a full example of a program that takes the PNG image displayed at @fig-pascal\nas input, and writes a new image to the current working directory that is the grayscale version of this input image.\nThis grayscale version of @fig-pascal is exposed at @fig-pascal-gray.\nYou can find the full source code of this small project at the `ZigExamples/image_filter`\n[folder at the official repository of this book](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter)[^img-filter-folder].\n\n\n![The grayscale version of the photo.](../ZigExamples/image_filter/pedro_pascal_filter.png){#fig-pascal-gray}\n\n\n## How we see things? {#sec-eyes}\n\nIn this section, I want to briefly describe to you how we (humans) actually see things with our own eyes.\nI mean, how our eyes work? If you do have a very basic understanding of how our eyes work, you will understand\nmore easily how digital images are made. Because the techniques behind digital images\nwere developed by taking a lot of inspiration from how our human eyes work.\n\nYou can interpret a human eye as a light sensor, or, a light receptor. The eye receives some amount of light as input,\nand it interprets the colors that are present in this \"amount of light\".\nIf no amount of light hits the eye, then, the eye cannot extract color from it, and as result,\nwe end up seeing nothing, or, more precisely, we see complete blackness.\n\nTherefore, everything depends on light. What we actually see are the colors (blue, red, orange, green, purple, yellow, etc.) that\nare being reflected from the light that is hitting our eyes. **Light is the source of all colors!**\nThis is what Isaac Newton discovered on his famous prism experiment[^newton] in the 1660s.\n\n[^newton]: <https://library.si.edu/exhibition/color-in-a-new-light/science>\n\nInside our eyes, we have a specific type of cell called the \"cone cell\".\nOur eye have three different types, or, three different versions of these \"cone cells\".\nEach type of cone cell is very sensitive to a specific spectrum of the light. More specifically,\nto the spectrums that define the colors red, green and blue.\nSo, in summary, our eyes have specific types of cells that\nare highly sensitive to these three colors (red, green and blue).\n\nThese are the cells responsible for perceiving the color present in the light that hits our eyes.\nAs a result, our eyes perceives color as a mixture of these three colors (red, green and blue). By having an amount\nof each one of these three colors, and mixing them together, we can get any other visible color\nthat we want. So every color that we see is perceived as a specific mixture of blues, greens and reds,\nlike 30% of red, plus 20% of green, plus 50% of blue.\n\nWhen these cone cells perceive (or, detect) the colors that are found in the\nlight that is hitting our eyes, these cells produce electrical signals, which are sent to the brain.\nOur brain interprets these electrical signals, and use them to form the image that we are seeing\ninside our head.\n\nBased on what we have discussed here, the bullet points exposed below describes the sequence of events that\ncomposes this very simplified version of how our human eyes work:\n\n1. Light hits our eyes.\n1. The cone cells perceive the colors that are present in this light.\n1. Cone cells produce electrical signals that describes the colors that were perceived in the light.\n1. The electrical signals are sent to the brain.\n1. Brain interprets these signals, and form the image based on the colors identified by these electrical signals.\n\n\n## How digital images work? {#sec-digital-img}\n\nA digital image is a \"digital representation\" of an image that we see with our eyes.\nIn other words, a digital image is a \"digital representation\" of the colors that we see\nand perceive through the light.\nIn the digital world, we have two types of images, which are: vector images and raster images.\nVector images are not described here. So just remember that the content discussed here\n**is related solely to raster images**, and not vector images.\n\nA raster image is a type of digital image that is represented as a 2D (two dimensional) matrix\nof pixels. In other words, every raster image is basically a rectangle of pixels, and each pixel have a particular color.\nSo, a raster image is just a rectangle of pixels, and each of these pixels are displayed in the screen of your computer (or the screen\nof any other device, e.g. laptop, tablet, smartphone, etc.) as a color.\n\n@fig-raster demonstrates this idea. If you take any raster image, and you zoom into it very hard,\nyou will see the actual pixels of the image. JPEG, TIFF and PNG are file formats that are commonly\nused to store raster images.\n\n![Zooming over a raster image to see the pixels. Source: Google Images.](../Figures/imagem-raster.png){#fig-raster}\n\nThe more pixels the image has, the more information and detail we can include in the image.\nThe more accurate, sharp and pretty the image will look. This is why photographic cameras\nusually produce big raster images, with several megapixels of resolution, to include as much detail as possible into the final image.\nAs an example, a digital image with dimensions of 1920 pixels wide and 1080 pixels high, would be a image that\ncontains $1920 \\times 1080 = 2073600$ pixels in total. You could also say that the \"total area\" of the image is\nof 2073600 pixels, although the concept of \"area\" is not really used here in computer graphics.\n\nMost digital images we see in our modern world uses the RGB color model. RGB stands for (red, green and blue).\nSo the color of each pixel in these raster images are usually represented as a mixture of red, green and blue,\njust like in our eyes. That is, the color of each pixel is identified by a set of\nthree different integer values. Each integer value identifies the \"amount\" of each color (red, green and blue).\nFor example, the set `(199, 78, 70)` identifies a color that is more close to red. We have 199 of red, 78 of green,\nand 70 of blue. In contrast, the set `(129, 77, 250)` describes a color that is more close to purple. Et cetera.\n\n\n\n### Images are displayed from top to bottom\n\nThis is not a rule written in stone, but the big majority of digital images are displayed from top\nto bottom and left to right. Most computers screens also follow this pattern. So, the first pixels\nin the image are the ones that are at the top and left corner of the image. You can find a visual representation\nof this logic at @fig-img-display.\n\nAlso notice in @fig-img-display that, because a raster image is essentially a 2D matrix of pixels,\nthe image is organized into rows and columns of pixels. The columns are defined by the horizontal x axis,\nwhile the rows are defined by the vertical y axis.\n\nEach pixel (i.e. the gray rectangles) exposed at @fig-img-display contains a number inside of it.\nThese numbers are the indexes of the pixels. You can notice that the first pixels are in the top and left\ncorner, and also, that the indexes of these pixels \"grow to the sides\", or, in other words, they grow in the direction of the horizontal x axis.\nMost raster images are organized as rows of pixels. Thus, when these digital images are\ndisplayed, the screen display the first row of pixels, then, the second row, then, the third row, etc.\n\n![How the pixels of raster images are displayed.](./../Figures/image-display.png){#fig-img-display}\n\n\n\n\n\n\n### Representing the matrix of pixels in code {#sec-pixel-repr}\n\nOk, we know already that raster images are represented as 2D matrices of pixels.\nBut we do not have a notion of a 2D matrix in Zig. Actually, most low-level languages in general\n(Zig, C, Rust, etc.) do not have such notion.\nSo how can we represent such matrix of pixels in Zig, or any other low-level language?\nThe strategy that most programmers choose in this situation is to just use a normal 1D array to store the values of\nthis 2D matrix. In other words, you just create an normal 1D array, and store all values from both dimensions into this 1D array.\n\nAs an example, suppose we have a very small image of dimensions 4x3.\nSince a raster image is represented as a 2D matrix of pixels, and each pixel\nis represented by 3 \"unsigned 8-bit\" integer values, we have 12 pixels in\ntotal in this image, which are represented by $3 \\times 12 = 36$ integer values.\nTherefore, we need to create an array of 36 `u8` values to store this small image.\n\nThe reason why unsigned 8-bit integer (`u8`) values are used to represent the amounts of each color,\ninstead of any other integer type, is because they take the minimum amount of space as possible, or,\nthe minimum amount of bits as possible. Which helps to reduces the binary size of the image, i.e. the 2D matrix.\nAlso, they convey a good amount of precision and detail about the colors, even though they can represent\na relatively small range (from 0 to 255) of \"color amounts\".\n\nComing back to our initial example of a 4x3 image,\nthe `matrix` object exposed below could be an example of an 1D array that stores\nthe data that represents this 4x3 image.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst matrix = [_]u8{\n    201, 10, 25, 185, 65, 70,\n    65, 120, 110, 65, 120, 117,\n    98, 95, 12, 213, 26, 88,\n    143, 112, 65, 97, 99, 205,\n    234, 105, 56, 43, 44, 216,\n    45, 59, 243, 211, 209, 54,\n};\n```\n:::\n\n\n\n\nThe first three integer values in this array are the color amounts of the first pixel in the image.\nThe next three integers are the colors amounts for the second pixel.\nAnd the sequence goes on in this pattern. Having that in mind, the size of the array that stores\na raster image is usually a multiple of 3. In this case, the array have a size of 36.\n\nI mean, the size of the array is **usually** a multiple of 3, because in specific circumstances,\nit can also be a multiple of 4. This happens when a transparency amount is\nalso included into the raster image. In other words, there are some types of raster images\nthat uses a different color model, which is the RGBA (red, green, blue and alpha)\ncolor model. The \"alpha\" corresponds to an amount of transparency in the pixel.\nSo every pixel in a RGBA image is represented by a red, green, blue and alpha values.\n\nMost raster images uses the standard RGB model, so, for the most part, you will\nsee arrays sizes that are multiples of 3. But some images, especially the ones\nthat are stored in PNG files, might be using the RGBA model, and, therefore, are\nrepresented by an array whose size is a multiple of 4.\n\nIn our case here, the example image of our project (@fig-pascal) is a raster image\nstored in a PNG file, and this specific image is using the RGBA color model. Therefore,\neach pixel in the image is represented by 4 different integer values, and, as consequence,\nto store this image in our Zig code, we need to create an array whose size is a multiple of 4.\n\n\n## The PNG library that we are going to use\n\nLet's begin our project by focusing on writing the necessary Zig code to\nread the data from the PNG file. In other words, we want to read the PNG file exposed\nat @fig-pascal, and parse its data to extract the 2D matrix of pixels that represents the image.\n\nAs we have discussed at @sec-pixel-repr, the image that we are using as example here\nis a PNG file that uses the RGBA color model, and, therefore, each pixel of the image\nis represented by 4 integer values. You can download this image by visiting the `ZigExamples/image_filter`\n[folder at the official repository of this book](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter)[^img-filter-folder].\nYou can also find in this folder the complete source code of this small project that we\nare developing here.\n\n[^img-filter-folder]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter>\n\nThere are some C libraries available that we can use to read and parse PNG files.\nThe most famous and used of all is `libpng`, which is the \"official library\" for reading and writing\nPNG files. Although this library is available on most operating system, it is well known\nfor being complex and hard to use.\n\nThat is why, I'm going to use a more modern alternative here in this project, which is the `libspng` library.\nI choose to use this C library here, because it is much, much simpler to use than `libpng`,\nand it also offers very good performance for all operations. You can checkout the\n[official website of the library](https://libspng.org/)[^libspng]\nto know more about it. You will also find there some documentation that might help you to understand and\nfollow the code examples exposed here.\n\n[^libspng]: <https://libspng.org/>\n\n\nFirst of all, remember to build and install this `libspng` into your system. Because\nif you don't do this step, the `zig` compiler will not be able to find the files and resources of\nthis library in your computer, and link them with the Zig source code that we are writing together here.\nThere is good information about how to build and install the library at the\n[build section of the library documentation](https://libspng.org/docs/build/)[^lib-build].\n\n[^lib-build]: <https://libspng.org/docs/build/>\n\n\n\n\n## Reading the PNG file\n\nIn order to extract the pixel data from the PNG file, we need to read and decode the file.\nA PNG file is just a binary file written in the \"PNG format\". Luckily, the `libspng` library offers\na function called `spng_decode_image()` that does all this heavy work for us.\n\nNow, since `libspng` is a C library, most of the file and I/O operations in this library are made by using\na `FILE` C pointer. Because of that, is probably a better idea to use the `fopen()` C function\nto open our PNG file, instead of using the `openFile()` method that I introduced at @sec-filesystem.\nThat is why I'm importing the `stdio.h` C header in this project, and using the `fopen()` C function to open the file.\n\nIf you look at the snippet below, you can see that we are:\n\n1. opening the PNG file with `fopen()`.\n1. creating the `libspng` context with `spng_ctx_new()`.\n1. using `spng_set_png_file()` to specify the `FILE` object that reads the PNG file that we are going to use.\n\nEvery operation in `libspng` is made through a \"context object\". In our snippet below, this object is `ctx`.\nAlso, to perform an operation over a PNG file, we need to specify which exact PNG file we are referring to.\nThis is the job of `spng_set_png_file()`. We are using this function to specify the file descriptor\nobject that reads the PNG file that we want to use.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n    @cInclude(\"spng.h\");\n});\n\nconst path = \"pedro_pascal.png\";\nconst file_descriptor = c.fopen(path, \"rb\");\nif (file_descriptor == null) {\n    @panic(\"Could not open file!\");\n}\nconst ctx = c.spng_ctx_new(0) orelse unreachable;\n_ = c.spng_set_png_file(\n    ctx, @ptrCast(file_descriptor)\n);\n```\n:::\n\n\n\n\nBefore we continue, is important to emphasize the following: since we have opened the file with `fopen()`,\nwe have to remember to close the file at the end of the program, with `fclose()`.\nIn other words, after we have done everything that we wanted to do with the PNG file\n`pedro_pascal.png`, we need to close this file, by applying `fclose()` over the file descriptor object.\nWe could use also the `defer` keyword to help us in this task, if we want to.\nThis code snippet below demonstrates this step:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (c.fclose(file_descriptor) != 0) {\n    return error.CouldNotCloseFileDescriptor;\n}\n```\n:::\n\n\n\n\n\n\n\n### Reading the image header section\n\nNow, the context object `ctx` is aware of our PNG file `pedro_pascal.png`, because it has access to\na file descriptor object to this file. The first thing that we are going to do is to read the\n\"image header section\" of the PNG file. This \"image header section\" is the section\nof the file that contains some basic information about the PNG file, like, the bit depth of the pixel data\nof the image, the color model used in the file, the dimensions of the image (height and width in number of pixels),\netc.\n\nTo make things easier, I will encapsulate this \"read image header\" operation into a\nnice and small function called `get_image_header()`. All that this function needs to do\nis to call the `spng_get_ihdr()` function. This function from `libspng` is responsible\nfor reading the image header data, and storing it into a C struct named `spng_ihdr`.\nThus, an object of type `spng_ihdr` is a C struct that contains the data from the\nimage header section of the PNG file.\n\nSince this Zig function is receiving a C object (the `libspng` context object) as input, I marked\nthe function argument `ctx` as \"a pointer to the context object\" (`*c.spng_ctx`), following the recommendations\nthat we have discussed at @sec-pass-c-structs.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn get_image_header(ctx: *c.spng_ctx) !c.spng_ihdr {\n    var image_header: c.spng_ihdr = undefined;\n    if (c.spng_get_ihdr(ctx, &image_header) != 0) {\n        return error.CouldNotGetImageHeader;\n    }\n\n    return image_header;\n}\n\nvar image_header = try get_image_header(ctx);\n```\n:::\n\n\n\n\nAlso notice in this function, that I'm checking if the `spng_get_ihdr()` function call have\nreturned or not an integer value that is different than zero. Most functions from the\n`libspng` library return a code status as result, and the code status \"zero\" means\n\"success\". So any code status that is different than zero means that an error\noccurred while running `spng_get_ihdr()`. This is why I'm returning an error value from\nthe function in case the code status returned by the function is different than zero.\n\n\n### Allocating space for the pixel data\n\nBefore we read the pixel data from the PNG file, we need to allocate enough space to hold this data.\nBut in order to allocate such space, we first need to know how much space we need to allocate.\nThe dimensions of the image are obviously needed to calculate the size of this space. But there are\nother elements that also affect this number, such as the color model used in the image, the bit depth, and others.\n\nAnyway, all of this means that calculating the size of the space that we need, is not a simple task.\nThat is why the `libspng` library offers an utility function named\n`spng_decoded_image_size()` to calculate this size for us. Once again, I'm going\nto encapsulate the logic around this C function into a nice and small Zig function\nnamed `calc_output_size()`. You can see below that this function returns a nice\ninteger value as result, informing the size of the space that we need to allocate.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn calc_output_size(ctx: *c.spng_ctx) !u64 {\n    var output_size: u64 = 0;\n    const status = c.spng_decoded_image_size(\n        ctx, c.SPNG_FMT_RGBA8, &output_size\n    );\n    if (status != 0) {\n        return error.CouldNotCalcOutputSize;\n    }\n    return output_size;\n}\n```\n:::\n\n\n\n\n\n\nYou might quest yourself what the value `SPNG_FMT_RGBA8` means. This value is actually an enum\nvalue defined in the `spng.h` C header file. This enum is used to identify a \"PNG format\".\nMore precisely, it identifies a PNG file that uses the RGBA color model and 8 bit depth.\nSo, by providing this enum value as input to the `spng_decoded_image_size()` function,\nwe are saying to this function to calculate the size of the decoded pixel data, by considering\na PNG file that follows this \"RGBA color model with 8 bit depth\" format.\n\nHaving this function, we can use it in conjunction with an allocator object, to allocate an\narray of bytes (`u8` values) that is big enough to store the decoded pixel data of the image.\nNotice that I'm using `@memset()` to initialize the entire array to zero.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst output_size = try calc_output_size(ctx);\nvar buffer = try allocator.alloc(u8, output_size);\n@memset(buffer[0..], 0);\n```\n:::\n\n\n\n\n\n### Decoding the image data\n\nNow that we have the necessary space to store the decoded pixel data of the image,\nwe can start to actually decode and extract this pixel data from the image,\nby using the `spng_decode_image()` C function.\n\nThe `read_data_to_buffer()` Zig function exposed below summarises the necessary\nsteps to read this decoded pixel data, and store it into an input buffer.\nNotice that this function is encapsulating the logic around the `spng_decode_image()` function.\nAlso, we are using the `SPNG_FMT_RGBA8` enum value once again to inform the corresponding function,\nthat the PNG image being decoded, uses the RGBA color model and 8 bit depth.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn read_data_to_buffer(ctx: *c.spng_ctx, buffer: []u8) !void {\n    const status = c.spng_decode_image(\n        ctx,\n        buffer.ptr,\n        buffer.len,\n        c.SPNG_FMT_RGBA8,\n        0\n    );\n\n    if (status != 0) {\n        return error.CouldNotDecodeImage;\n    }\n}\n```\n:::\n\n\n\n\nHaving this function at hand, we can apply it over our context object, and also, over\nthe buffer object that we have allocated in the previous section to hold the decoded pixel data\nof the image:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry read_data_to_buffer(ctx, buffer[0..]);\n```\n:::\n\n\n\n\n\n### Looking at the pixel data\n\nNow that we have the pixel data stored in our \"buffer object\", we can take\na quick look at the bytes. In the example below, we are looking at the first\n12 bytes in the decoded pixel data.\n\nIf you take a close look at these values, you might notice that every 4 bytes\nin the sequence is 255. Which, coincidentally is the maximum possible integer value\nto be represented by a `u8` value. So, if the range from 0 to 255, which is the range\nof integer values that can be represented by an `u8` value, can be represented as a scale from 0% to 100%,\nthese 255 values are essentially 100% in that scale.\n\nIf you recall from @sec-pixel-repr, I have\ndescribed in that section that our `pedro_pascal.png` PNG file uses the RGBA color model,\nwhich adds an alpha (or transparency) byte to each pixel in the image.\nAs consequence, each pixel in the image is represented by 4 bytes. Since we are looking\nhere are the first 12 bytes in the image, it means that we are looking at the data from\nthe first $12 / 4 = 3$ pixels in the image.\n\nSo, based on how these first 12 bytes (or these 3 pixels) look, with these 255 values at every 4 bytes, we can say that is likely\nthat every pixel in the image have alpha (or transparency) setted to 100%. This might not be true,\nbut, is the most likely possibility. Also, if we look at the image itself, which if your recall is\nexposed at @fig-pascal, we can see that the transparency does not change across the image,\nwhich enforces this theory.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry stdout.print(\"{any}\\n\", .{buffer[0..12]});\n```\n:::\n\n\n\n\n```\n{\n    200, 194, 216, 255, 203, 197,\n    219, 255, 206, 200, 223, 255\n}\n```\n\n\nWe can see in the above result that the first pixel in this image have 200 of red, 194 of green, and 216 of blue.\nHow do I know the order in which the colors appears in the sequence? If you have not guessed that yet,\nis because of the acronym RGB. First RED, then GREEN, then BLUE. If we scale these integer values\naccording to our scale of 0% to 100% (0 to 255), we get 78% of red, 76% of green and 85% of blue.\n\n\n\n## Applying the image filter\n\nNow that we have the data of each pixel in the image, we can focus on applying our image\nfilter over these pixels. Remember, our objective here is to apply a grayscale filter over\nthe image. A grayscale filter is a filter that transforms a colored image into a grayscale image.\n\nThere are different formulas and strategies to transform a colored image into a grayscale image.\nBut all of these different strategies normally involve applying some math over the colors of each pixel.\nIn this project, we are going to use the most general formula, which is exposed below.\nThis formula considers $r$ as the red of the pixel, $g$ as the green, $b$ as the blue, and $p'$ as the\nlinear luminance of the pixel.\n\n$$\n    p' = (0.2126 \\times r) + (0.7152 \\times g) + (0.0722 \\times b)\n$${#eq-grayscale}\n\nThis @eq-grayscale is the formula to calculate the linear luminance of a pixel. Is worth noting that this formula\nworks only for images whose pixels are using the sRGB color space, which is the standard color space\nfor the web. Thus, ideally, all images on the web should use this color space. Luckily,\nthis is our case here, i.e. the `pedro_pascal.png` image is using this sRGB color space, and, as consequence,\nwe can use the @eq-grayscale. You can read more about this formula at the Wikipedia page for grayscale [@wiki_grayscale].\n\nThe `apply_image_filter()` function exposed below summarises the necessary steps to\napply @eq-grayscale over the pixels in the image. We just apply this function\nover our buffer object that contains our pixel data, and, as result, the pixel\ndata stored in this buffer object should now represent the grayscale version of our image.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn apply_image_filter(buffer:[]u8) !void {\n    const len = buffer.len;\n    const red_factor: f16 = 0.2126;\n    const green_factor: f16 = 0.7152;\n    const blue_factor: f16 = 0.0722;\n    var index: u64 = 0;\n    while (index < (len - 4)) : (index += 4) {\n        const rf: f16 = @floatFromInt(buffer[index]);\n        const gf: f16 = @floatFromInt(buffer[index + 1]);\n        const bf: f16 = @floatFromInt(buffer[index + 2]);\n        const y_linear: f16 = (\n            (rf * red_factor) + (gf * green_factor)\n            + (bf * blue_factor)\n        );\n        buffer[index] = @intFromFloat(y_linear);\n        buffer[index + 1] = @intFromFloat(y_linear);\n        buffer[index + 2] = @intFromFloat(y_linear);\n    }\n}\n\ntry apply_image_filter(buffer[0..]);\n```\n:::\n\n\n\n\n\n\n## Saving the grayscale version of the image\n\nSince we have now the grayscale version of our image stored in our buffer object,\nwe need to encode this buffer object back into the \"PNG format\", and save the encoded data into\na new PNG file in our filesystem, so that we can access and see the grayscale version of our image\nthat was produced by our small program.\n\nTo do that, the `libspng` library help us once again by offering an \"encode data to PNG\" type of function,\nwhich is the `spng_encode_image()` function. But in order to \"encode data to PNG\" with `libspng`, we need\nto create a new context object. This new context object must use an \"encoder context\", which\nis identified by the enum value `SPNG_CTX_ENCODER`.\n\nThe `save_png()` function exposed below, summarises all the necessary steps to save the\ngrayscale version of our image into a new PNG file in the filesystem. By default, this\nfunction will save the grayscale image into a file named `pedro_pascal_filter.png` in the CWD.\n\nNotice in this code example that we are using the same image header object (`image_header`) that we have\ncollected previously with the `get_image_header()` function. Remember, this image header object\nis a C struct (`spng_ihdr`) that contains basic information about our PNG file, such as\nthe dimensions of the image, the color model used, etc.\n\nIf we wanted to save a very different image in this new PNG file, e.g. an image\nwith different dimensions, or, an image that uses a different color model, a different bit depth, etc.\nwe would have to create a new image header (`spng_ihdr`) object that describes the properties\nof this new image.\n\nBut we are essentially saving the same image that we have begin with here (the dimensions of\nthe image, the color model, etc. are all still the same). The only difference\nbetween the two images are the colors of the pixels, which are now \"shades of gray\".\nAs consequence, we can safely use the exact same image header data in this new PNG file.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn save_png(image_header: *c.spng_ihdr, buffer: []u8) !void {\n    const path = \"pedro_pascal_filter.png\";\n    const file_descriptor = c.fopen(path.ptr, \"wb\");\n    if (file_descriptor == null) {\n        return error.CouldNotOpenFile;\n    }\n    const ctx = (\n        c.spng_ctx_new(c.SPNG_CTX_ENCODER)\n        orelse unreachable\n    );\n    defer c.spng_ctx_free(ctx);\n    _ = c.spng_set_png_file(ctx, @ptrCast(file_descriptor));\n    _ = c.spng_set_ihdr(ctx, image_header);\n\n    const encode_status = c.spng_encode_image(\n        ctx,\n        buffer.ptr,\n        buffer.len,\n        c.SPNG_FMT_PNG,\n        c.SPNG_ENCODE_FINALIZE\n    );\n    if (encode_status != 0) {\n        return error.CouldNotEncodeImage;\n    }\n    if (c.fclose(file_descriptor) != 0) {\n        return error.CouldNotCloseFileDescriptor;\n    }\n}\n\ntry save_png(&image_header, buffer[0..]);\n```\n:::\n\n\n\n\nAfter we execute this `save_png()` function, we should have a new PNG file\ninside our CWD, named `pedro_pascal_filter.png`. If we open this PNG file,\nwe will see the same image exposed at @fig-pascal-gray.\n\n\n## Building our project\n\nNow that we have written the code, let's discuss how can we build/compile this project.\nTo do that, I'm going to create a `build.zig` file in the root directory of our project,\nand start writing the necessary code to compile the project, using the knowledge\nthat we have acquired from @sec-build-system.\n\n\nWe first create the build target for our executable file, that executes our\nZig code. Let's suppose that all of our Zig code was written into a Zig module\nnamed `image_filter.zig`. The `exe` object exposed in the build script below\ndescribes the build target for our executable file.\n\nSince we have used some C code from the `libspng` library in our Zig code,\nwe need to link our Zig code (which is in the `exe` build target) to both\nthe C Standard Library, and, to the `libspng` library. We do that, by calling\nthe `linkLibC()` and `linkSystemLibrary()` methods from our `exe` build target.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const target = b.standardTargetOptions(.{});\n    const optimize = b.standardOptimizeOption(.{});\n    const exe = b.addExecutable(.{\n        .name = \"image_filter\",\n        .root_source_file = b.path(\"src/image_filter.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n    exe.linkLibC();\n    // Link to libspng library:\n    exe.linkSystemLibrary(\"spng\");\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\nSince we are using the `linkSystemLibrary()` method, it means that the library\nfiles for `libspng` are searched in your system to be linked with the `exe` build target.\nIf you have not yet built and installed the `libspng` library into your system, this\nlinkage step will likely not work. Because it will not find the library files in your system.\n\nSo, just remember to install `libspng` in your system, if you want to build this project.\nHaving this build script above written, we can finally build our project by\nrunning the `zig build` command in the terminal.\n\n```bash\nzig build\n```\n\n\n",
-    "supporting": [
-      "13-image-filter_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 4 - Developing an image filter\n\nIn this chapter we are going to build a new project. The objective of\nthis project is to write a program that applies a filter over an image.\nMore specifically, a \"grayscale filter\", which transforms\nany color image into a grayscale image.\n\nWe are going to use the image displayed at @fig-pascal in this project.\nIn other words, we want to transform this colored image into a grayscale image,\nby using our \"image filter program\" written in Zig.\n\n![A photo of the chilean-american actor Pedro Pascal. Source: Google Images.](../ZigExamples/image_filter/pedro_pascal.png){#fig-pascal}\n\nWe don't need to write a lot of code to build such \"image filter program\". However, we first need\nto understand how digital images work. That is why we begin this chapter\nby explaining the theory behind digital images and how colors are represented in modern computers.\nWe also give a brief explanation about the PNG (Portable Network Graphics) file format, which is the format used\nin the example images.\n\nAt the end of this chapter, we should have a full example of a program that takes the PNG image displayed at @fig-pascal\nas input, and writes a new image to the current working directory that is the grayscale version of this input image.\nThis grayscale version of @fig-pascal is exposed at @fig-pascal-gray.\nYou can find the full source code of this small project at the `ZigExamples/image_filter`\n[folder at the official repository of this book](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter)[^img-filter-folder].\n\n\n![The grayscale version of the photo.](../ZigExamples/image_filter/pedro_pascal_filter.png){#fig-pascal-gray}\n\n\n## How we see things? {#sec-eyes}\n\nIn this section, I want to briefly describe to you how we (humans) actually see things with our own eyes.\nI mean, how our eyes work? If you do have a very basic understanding of how our eyes work, you will understand\nmore easily how digital images are made. Because the techniques behind digital images\nwere developed by taking a lot of inspiration from how our human eyes work.\n\nYou can interpret a human eye as a light sensor, or, a light receptor. The eye receives some amount of light as input,\nand it interprets the colors that are present in this \"amount of light\".\nIf no amount of light hits the eye, then, the eye cannot extract color from it, and as result,\nwe end up seeing nothing, or, more precisely, we see complete blackness.\n\nTherefore, everything depends on light. What we actually see are the colors (blue, red, orange, green, purple, yellow, etc.) that\nare being reflected from the light that is hitting our eyes. **Light is the source of all colors!**\nThis is what Isaac Newton discovered on his famous prism experiment[^newton] in the 1660s.\n\n[^newton]: <https://library.si.edu/exhibition/color-in-a-new-light/science>\n\nInside our eyes, we have a specific type of cell called the \"cone cell\".\nOur eye have three different types, or, three different versions of these \"cone cells\".\nEach type of cone cell is very sensitive to a specific spectrum of the light. More specifically,\nto the spectrums that define the colors red, green and blue.\nSo, in summary, our eyes have specific types of cells that\nare highly sensitive to these three colors (red, green and blue).\n\nThese are the cells responsible for perceiving the color present in the light that hits our eyes.\nAs a result, our eyes perceives color as a mixture of these three colors (red, green and blue). By having an amount\nof each one of these three colors, and mixing them together, we can get any other visible color\nthat we want. So every color that we see is perceived as a specific mixture of blues, greens and reds,\nlike 30% of red, plus 20% of green, plus 50% of blue.\n\nWhen these cone cells perceive (or, detect) the colors that are found in the\nlight that is hitting our eyes, these cells produce electrical signals, which are sent to the brain.\nOur brain interprets these electrical signals, and use them to form the image that we are seeing\ninside our head.\n\nBased on what we have discussed here, the bullet points exposed below describes the sequence of events that\ncomposes this very simplified version of how our human eyes work:\n\n1. Light hits our eyes.\n1. The cone cells perceive the colors that are present in this light.\n1. Cone cells produce electrical signals that describes the colors that were perceived in the light.\n1. The electrical signals are sent to the brain.\n1. Brain interprets these signals, and form the image based on the colors identified by these electrical signals.\n\n\n## How digital images work? {#sec-digital-img}\n\nA digital image is a \"digital representation\" of an image that we see with our eyes.\nIn other words, a digital image is a \"digital representation\" of the colors that we see\nand perceive through the light.\nIn the digital world, we have two types of images, which are: vector images and raster images.\nVector images are not described here. So just remember that the content discussed here\n**is related solely to raster images**, and not vector images.\n\nA raster image is a type of digital image that is represented as a 2D (two dimensional) matrix\nof pixels. In other words, every raster image is basically a rectangle of pixels, and each pixel have a particular color.\nSo, a raster image is just a rectangle of pixels, and each of these pixels are displayed in the screen of your computer (or the screen\nof any other device, e.g. laptop, tablet, smartphone, etc.) as a color.\n\n@fig-raster demonstrates this idea. If you take any raster image, and you zoom into it very hard,\nyou will see the actual pixels of the image. JPEG, TIFF and PNG are file formats that are commonly\nused to store raster images.\n\n![Zooming over a raster image to see the pixels. Source: Google Images.](../Figures/imagem-raster.png){#fig-raster}\n\nThe more pixels the image has, the more information and detail we can include in the image.\nThe more accurate, sharp and pretty the image will look. This is why photographic cameras\nusually produce big raster images, with several megapixels of resolution, to include as much detail as possible into the final image.\nAs an example, a digital image with dimensions of 1920 pixels wide and 1080 pixels high, would be a image that\ncontains $1920 \\times 1080 = 2073600$ pixels in total. You could also say that the \"total area\" of the image is\nof 2073600 pixels, although the concept of \"area\" is not really used here in computer graphics.\n\nMost digital images we see in our modern world uses the RGB color model. RGB stands for (red, green and blue).\nSo the color of each pixel in these raster images are usually represented as a mixture of red, green and blue,\njust like in our eyes. That is, the color of each pixel is identified by a set of\nthree different integer values. Each integer value identifies the \"amount\" of each color (red, green and blue).\nFor example, the set `(199, 78, 70)` identifies a color that is more close to red. We have 199 of red, 78 of green,\nand 70 of blue. In contrast, the set `(129, 77, 250)` describes a color that is more close to purple. Et cetera.\n\n\n\n### Images are displayed from top to bottom\n\nThis is not a rule written in stone, but the big majority of digital images are displayed from top\nto bottom and left to right. Most computers screens also follow this pattern. So, the first pixels\nin the image are the ones that are at the top and left corner of the image. You can find a visual representation\nof this logic at @fig-img-display.\n\nAlso notice in @fig-img-display that, because a raster image is essentially a 2D matrix of pixels,\nthe image is organized into rows and columns of pixels. The columns are defined by the horizontal x axis,\nwhile the rows are defined by the vertical y axis.\n\nEach pixel (i.e. the gray rectangles) exposed at @fig-img-display contains a number inside of it.\nThese numbers are the indexes of the pixels. You can notice that the first pixels are in the top and left\ncorner, and also, that the indexes of these pixels \"grow to the sides\", or, in other words, they grow in the direction of the horizontal x axis.\nMost raster images are organized as rows of pixels. Thus, when these digital images are\ndisplayed, the screen display the first row of pixels, then, the second row, then, the third row, etc.\n\n![How the pixels of raster images are displayed.](./../Figures/image-display.png){#fig-img-display}\n\n\n\n\n\n\n### Representing the matrix of pixels in code {#sec-pixel-repr}\n\nOk, we know already that raster images are represented as 2D matrices of pixels.\nBut we do not have a notion of a 2D matrix in Zig. Actually, most low-level languages in general\n(Zig, C, Rust, etc.) do not have such notion.\nSo how can we represent such matrix of pixels in Zig, or any other low-level language?\nThe strategy that most programmers choose in this situation is to just use a normal 1D array to store the values of\nthis 2D matrix. In other words, you just create an normal 1D array, and store all values from both dimensions into this 1D array.\n\nAs an example, suppose we have a very small image of dimensions 4x3.\nSince a raster image is represented as a 2D matrix of pixels, and each pixel\nis represented by 3 \"unsigned 8-bit\" integer values, we have 12 pixels in\ntotal in this image, which are represented by $3 \\times 12 = 36$ integer values.\nTherefore, we need to create an array of 36 `u8` values to store this small image.\n\nThe reason why unsigned 8-bit integer (`u8`) values are used to represent the amounts of each color,\ninstead of any other integer type, is because they take the minimum amount of space as possible, or,\nthe minimum amount of bits as possible. Which helps to reduces the binary size of the image, i.e. the 2D matrix.\nAlso, they convey a good amount of precision and detail about the colors, even though they can represent\na relatively small range (from 0 to 255) of \"color amounts\".\n\nComing back to our initial example of a 4x3 image,\nthe `matrix` object exposed below could be an example of an 1D array that stores\nthe data that represents this 4x3 image.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst matrix = [_]u8{\n    201, 10, 25, 185, 65, 70,\n    65, 120, 110, 65, 120, 117,\n    98, 95, 12, 213, 26, 88,\n    143, 112, 65, 97, 99, 205,\n    234, 105, 56, 43, 44, 216,\n    45, 59, 243, 211, 209, 54,\n};\n```\n:::\n\n\n\n\nThe first three integer values in this array are the color amounts of the first pixel in the image.\nThe next three integers are the colors amounts for the second pixel.\nAnd the sequence goes on in this pattern. Having that in mind, the size of the array that stores\na raster image is usually a multiple of 3. In this case, the array have a size of 36.\n\nI mean, the size of the array is **usually** a multiple of 3, because in specific circumstances,\nit can also be a multiple of 4. This happens when a transparency amount is\nalso included into the raster image. In other words, there are some types of raster images\nthat uses a different color model, which is the RGBA (red, green, blue and alpha)\ncolor model. The \"alpha\" corresponds to an amount of transparency in the pixel.\nSo every pixel in a RGBA image is represented by a red, green, blue and alpha values.\n\nMost raster images uses the standard RGB model, so, for the most part, you will\nsee arrays sizes that are multiples of 3. But some images, especially the ones\nthat are stored in PNG files, might be using the RGBA model, and, therefore, are\nrepresented by an array whose size is a multiple of 4.\n\nIn our case here, the example image of our project (@fig-pascal) is a raster image\nstored in a PNG file, and this specific image is using the RGBA color model. Therefore,\neach pixel in the image is represented by 4 different integer values, and, as consequence,\nto store this image in our Zig code, we need to create an array whose size is a multiple of 4.\n\n\n## The PNG library that we are going to use\n\nLet's begin our project by focusing on writing the necessary Zig code to\nread the data from the PNG file. In other words, we want to read the PNG file exposed\nat @fig-pascal, and parse its data to extract the 2D matrix of pixels that represents the image.\n\nAs we have discussed at @sec-pixel-repr, the image that we are using as example here\nis a PNG file that uses the RGBA color model, and, therefore, each pixel of the image\nis represented by 4 integer values. You can download this image by visiting the `ZigExamples/image_filter`\n[folder at the official repository of this book](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter)[^img-filter-folder].\nYou can also find in this folder the complete source code of this small project that we\nare developing here.\n\n[^img-filter-folder]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter>\n\nThere are some C libraries available that we can use to read and parse PNG files.\nThe most famous and used of all is `libpng`, which is the \"official library\" for reading and writing\nPNG files. Although this library is available on most operating system, it is well known\nfor being complex and hard to use.\n\nThat is why, I'm going to use a more modern alternative here in this project, which is the `libspng` library.\nI choose to use this C library here, because it is much, much simpler to use than `libpng`,\nand it also offers very good performance for all operations. You can checkout the\n[official website of the library](https://libspng.org/)[^libspng]\nto know more about it. You will also find there some documentation that might help you to understand and\nfollow the code examples exposed here.\n\n[^libspng]: <https://libspng.org/>\n\n\nFirst of all, remember to build and install this `libspng` into your system. Because\nif you don't do this step, the `zig` compiler will not be able to find the files and resources of\nthis library in your computer, and link them with the Zig source code that we are writing together here.\nThere is good information about how to build and install the library at the\n[build section of the library documentation](https://libspng.org/docs/build/)[^lib-build].\n\n[^lib-build]: <https://libspng.org/docs/build/>\n\n\n\n\n## Reading the PNG file\n\nIn order to extract the pixel data from the PNG file, we need to read and decode the file.\nA PNG file is just a binary file written in the \"PNG format\". Luckily, the `libspng` library offers\na function called `spng_decode_image()` that does all this heavy work for us.\n\nNow, since `libspng` is a C library, most of the file and I/O operations in this library are made by using\na `FILE` C pointer. Because of that, is probably a better idea to use the `fopen()` C function\nto open our PNG file, instead of using the `openFile()` method that I introduced at @sec-filesystem.\nThat is why I'm importing the `stdio.h` C header in this project, and using the `fopen()` C function to open the file.\n\nIf you look at the snippet below, you can see that we are:\n\n1. opening the PNG file with `fopen()`.\n1. creating the `libspng` context with `spng_ctx_new()`.\n1. using `spng_set_png_file()` to specify the `FILE` object that reads the PNG file that we are going to use.\n\nEvery operation in `libspng` is made through a \"context object\". In our snippet below, this object is `ctx`.\nAlso, to perform an operation over a PNG file, we need to specify which exact PNG file we are referring to.\nThis is the job of `spng_set_png_file()`. We are using this function to specify the file descriptor\nobject that reads the PNG file that we want to use.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n    @cInclude(\"spng.h\");\n});\n\nconst path = \"pedro_pascal.png\";\nconst file_descriptor = c.fopen(path, \"rb\");\nif (file_descriptor == null) {\n    @panic(\"Could not open file!\");\n}\nconst ctx = c.spng_ctx_new(0) orelse unreachable;\n_ = c.spng_set_png_file(\n    ctx, @ptrCast(file_descriptor)\n);\n```\n:::\n\n\n\n\nBefore we continue, is important to emphasize the following: since we have opened the file with `fopen()`,\nwe have to remember to close the file at the end of the program, with `fclose()`.\nIn other words, after we have done everything that we wanted to do with the PNG file\n`pedro_pascal.png`, we need to close this file, by applying `fclose()` over the file descriptor object.\nWe could use also the `defer` keyword to help us in this task, if we want to.\nThis code snippet below demonstrates this step:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (c.fclose(file_descriptor) != 0) {\n    return error.CouldNotCloseFileDescriptor;\n}\n```\n:::\n\n\n\n\n\n\n\n### Reading the image header section\n\nNow, the context object `ctx` is aware of our PNG file `pedro_pascal.png`, because it has access to\na file descriptor object to this file. The first thing that we are going to do is to read the\n\"image header section\" of the PNG file. This \"image header section\" is the section\nof the file that contains some basic information about the PNG file, like, the bit depth of the pixel data\nof the image, the color model used in the file, the dimensions of the image (height and width in number of pixels),\netc.\n\nTo make things easier, I will encapsulate this \"read image header\" operation into a\nnice and small function called `get_image_header()`. All that this function needs to do\nis to call the `spng_get_ihdr()` function. This function from `libspng` is responsible\nfor reading the image header data, and storing it into a C struct named `spng_ihdr`.\nThus, an object of type `spng_ihdr` is a C struct that contains the data from the\nimage header section of the PNG file.\n\nSince this Zig function is receiving a C object (the `libspng` context object) as input, I marked\nthe function argument `ctx` as \"a pointer to the context object\" (`*c.spng_ctx`), following the recommendations\nthat we have discussed at @sec-pass-c-structs.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn get_image_header(ctx: *c.spng_ctx) !c.spng_ihdr {\n    var image_header: c.spng_ihdr = undefined;\n    if (c.spng_get_ihdr(ctx, &image_header) != 0) {\n        return error.CouldNotGetImageHeader;\n    }\n\n    return image_header;\n}\n\nvar image_header = try get_image_header(ctx);\n```\n:::\n\n\n\n\nAlso notice in this function, that I'm checking if the `spng_get_ihdr()` function call have\nreturned or not an integer value that is different than zero. Most functions from the\n`libspng` library return a code status as result, and the code status \"zero\" means\n\"success\". So any code status that is different than zero means that an error\noccurred while running `spng_get_ihdr()`. This is why I'm returning an error value from\nthe function in case the code status returned by the function is different than zero.\n\n\n### Allocating space for the pixel data\n\nBefore we read the pixel data from the PNG file, we need to allocate enough space to hold this data.\nBut in order to allocate such space, we first need to know how much space we need to allocate.\nThe dimensions of the image are obviously needed to calculate the size of this space. But there are\nother elements that also affect this number, such as the color model used in the image, the bit depth, and others.\n\nAnyway, all of this means that calculating the size of the space that we need, is not a simple task.\nThat is why the `libspng` library offers an utility function named\n`spng_decoded_image_size()` to calculate this size for us. Once again, I'm going\nto encapsulate the logic around this C function into a nice and small Zig function\nnamed `calc_output_size()`. You can see below that this function returns a nice\ninteger value as result, informing the size of the space that we need to allocate.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn calc_output_size(ctx: *c.spng_ctx) !u64 {\n    var output_size: u64 = 0;\n    const status = c.spng_decoded_image_size(\n        ctx, c.SPNG_FMT_RGBA8, &output_size\n    );\n    if (status != 0) {\n        return error.CouldNotCalcOutputSize;\n    }\n    return output_size;\n}\n```\n:::\n\n\n\n\n\n\nYou might quest yourself what the value `SPNG_FMT_RGBA8` means. This value is actually an enum\nvalue defined in the `spng.h` C header file. This enum is used to identify a \"PNG format\".\nMore precisely, it identifies a PNG file that uses the RGBA color model and 8 bit depth.\nSo, by providing this enum value as input to the `spng_decoded_image_size()` function,\nwe are saying to this function to calculate the size of the decoded pixel data, by considering\na PNG file that follows this \"RGBA color model with 8 bit depth\" format.\n\nHaving this function, we can use it in conjunction with an allocator object, to allocate an\narray of bytes (`u8` values) that is big enough to store the decoded pixel data of the image.\nNotice that I'm using `@memset()` to initialize the entire array to zero.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst output_size = try calc_output_size(ctx);\nvar buffer = try allocator.alloc(u8, output_size);\n@memset(buffer[0..], 0);\n```\n:::\n\n\n\n\n\n### Decoding the image data\n\nNow that we have the necessary space to store the decoded pixel data of the image,\nwe can start to actually decode and extract this pixel data from the image,\nby using the `spng_decode_image()` C function.\n\nThe `read_data_to_buffer()` Zig function exposed below summarises the necessary\nsteps to read this decoded pixel data, and store it into an input buffer.\nNotice that this function is encapsulating the logic around the `spng_decode_image()` function.\nAlso, we are using the `SPNG_FMT_RGBA8` enum value once again to inform the corresponding function,\nthat the PNG image being decoded, uses the RGBA color model and 8 bit depth.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn read_data_to_buffer(ctx: *c.spng_ctx, buffer: []u8) !void {\n    const status = c.spng_decode_image(\n        ctx,\n        buffer.ptr,\n        buffer.len,\n        c.SPNG_FMT_RGBA8,\n        0\n    );\n\n    if (status != 0) {\n        return error.CouldNotDecodeImage;\n    }\n}\n```\n:::\n\n\n\n\nHaving this function at hand, we can apply it over our context object, and also, over\nthe buffer object that we have allocated in the previous section to hold the decoded pixel data\nof the image:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry read_data_to_buffer(ctx, buffer[0..]);\n```\n:::\n\n\n\n\n\n### Looking at the pixel data\n\nNow that we have the pixel data stored in our \"buffer object\", we can take\na quick look at the bytes. In the example below, we are looking at the first\n12 bytes in the decoded pixel data.\n\nIf you take a close look at these values, you might notice that every 4 bytes\nin the sequence is 255. Which, coincidentally is the maximum possible integer value\nto be represented by a `u8` value. So, if the range from 0 to 255, which is the range\nof integer values that can be represented by an `u8` value, can be represented as a scale from 0% to 100%,\nthese 255 values are essentially 100% in that scale.\n\nIf you recall from @sec-pixel-repr, I have\ndescribed in that section that our `pedro_pascal.png` PNG file uses the RGBA color model,\nwhich adds an alpha (or transparency) byte to each pixel in the image.\nAs consequence, each pixel in the image is represented by 4 bytes. Since we are looking\nhere are the first 12 bytes in the image, it means that we are looking at the data from\nthe first $12 / 4 = 3$ pixels in the image.\n\nSo, based on how these first 12 bytes (or these 3 pixels) look, with these 255 values at every 4 bytes, we can say that is likely\nthat every pixel in the image have alpha (or transparency) setted to 100%. This might not be true,\nbut, is the most likely possibility. Also, if we look at the image itself, which if your recall is\nexposed at @fig-pascal, we can see that the transparency does not change across the image,\nwhich enforces this theory.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry stdout.print(\"{any}\\n\", .{buffer[0..12]});\n```\n:::\n\n\n\n\n```\n{\n    200, 194, 216, 255, 203, 197,\n    219, 255, 206, 200, 223, 255\n}\n```\n\n\nWe can see in the above result that the first pixel in this image have 200 of red, 194 of green, and 216 of blue.\nHow do I know the order in which the colors appears in the sequence? If you have not guessed that yet,\nis because of the acronym RGB. First RED, then GREEN, then BLUE. If we scale these integer values\naccording to our scale of 0% to 100% (0 to 255), we get 78% of red, 76% of green and 85% of blue.\n\n\n\n## Applying the image filter\n\nNow that we have the data of each pixel in the image, we can focus on applying our image\nfilter over these pixels. Remember, our objective here is to apply a grayscale filter over\nthe image. A grayscale filter is a filter that transforms a colored image into a grayscale image.\n\nThere are different formulas and strategies to transform a colored image into a grayscale image.\nBut all of these different strategies normally involve applying some math over the colors of each pixel.\nIn this project, we are going to use the most general formula, which is exposed below.\nThis formula considers $r$ as the red of the pixel, $g$ as the green, $b$ as the blue, and $p'$ as the\nlinear luminance of the pixel.\n\n$$\n    p' = (0.2126 \\times r) + (0.7152 \\times g) + (0.0722 \\times b)\n$${#eq-grayscale}\n\nThis @eq-grayscale is the formula to calculate the linear luminance of a pixel. Is worth noting that this formula\nworks only for images whose pixels are using the sRGB color space, which is the standard color space\nfor the web. Thus, ideally, all images on the web should use this color space. Luckily,\nthis is our case here, i.e. the `pedro_pascal.png` image is using this sRGB color space, and, as consequence,\nwe can use the @eq-grayscale. You can read more about this formula at the Wikipedia page for grayscale [@wiki_grayscale].\n\nThe `apply_image_filter()` function exposed below summarises the necessary steps to\napply @eq-grayscale over the pixels in the image. We just apply this function\nover our buffer object that contains our pixel data, and, as result, the pixel\ndata stored in this buffer object should now represent the grayscale version of our image.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn apply_image_filter(buffer:[]u8) !void {\n    const len = buffer.len;\n    const red_factor: f16 = 0.2126;\n    const green_factor: f16 = 0.7152;\n    const blue_factor: f16 = 0.0722;\n    var index: u64 = 0;\n    while (index <= (len - 4)) : (index += 4) {\n        const rf: f16 = @floatFromInt(buffer[index]);\n        const gf: f16 = @floatFromInt(buffer[index + 1]);\n        const bf: f16 = @floatFromInt(buffer[index + 2]);\n        const y_linear: f16 = (\n            (rf * red_factor) + (gf * green_factor)\n            + (bf * blue_factor)\n        );\n        buffer[index] = @intFromFloat(y_linear);\n        buffer[index + 1] = @intFromFloat(y_linear);\n        buffer[index + 2] = @intFromFloat(y_linear);\n    }\n}\n\ntry apply_image_filter(buffer[0..]);\n```\n:::\n\n\n\n\n\n\n## Saving the grayscale version of the image\n\nSince we have now the grayscale version of our image stored in our buffer object,\nwe need to encode this buffer object back into the \"PNG format\", and save the encoded data into\na new PNG file in our filesystem, so that we can access and see the grayscale version of our image\nthat was produced by our small program.\n\nTo do that, the `libspng` library help us once again by offering an \"encode data to PNG\" type of function,\nwhich is the `spng_encode_image()` function. But in order to \"encode data to PNG\" with `libspng`, we need\nto create a new context object. This new context object must use an \"encoder context\", which\nis identified by the enum value `SPNG_CTX_ENCODER`.\n\nThe `save_png()` function exposed below, summarises all the necessary steps to save the\ngrayscale version of our image into a new PNG file in the filesystem. By default, this\nfunction will save the grayscale image into a file named `pedro_pascal_filter.png` in the CWD.\n\nNotice in this code example that we are using the same image header object (`image_header`) that we have\ncollected previously with the `get_image_header()` function. Remember, this image header object\nis a C struct (`spng_ihdr`) that contains basic information about our PNG file, such as\nthe dimensions of the image, the color model used, etc.\n\nIf we wanted to save a very different image in this new PNG file, e.g. an image\nwith different dimensions, or, an image that uses a different color model, a different bit depth, etc.\nwe would have to create a new image header (`spng_ihdr`) object that describes the properties\nof this new image.\n\nBut we are essentially saving the same image that we have begin with here (the dimensions of\nthe image, the color model, etc. are all still the same). The only difference\nbetween the two images are the colors of the pixels, which are now \"shades of gray\".\nAs consequence, we can safely use the exact same image header data in this new PNG file.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn save_png(image_header: *c.spng_ihdr, buffer: []u8) !void {\n    const path = \"pedro_pascal_filter.png\";\n    const file_descriptor = c.fopen(path.ptr, \"wb\");\n    if (file_descriptor == null) {\n        return error.CouldNotOpenFile;\n    }\n    const ctx = (\n        c.spng_ctx_new(c.SPNG_CTX_ENCODER)\n        orelse unreachable\n    );\n    defer c.spng_ctx_free(ctx);\n    _ = c.spng_set_png_file(ctx, @ptrCast(file_descriptor));\n    _ = c.spng_set_ihdr(ctx, image_header);\n\n    const encode_status = c.spng_encode_image(\n        ctx,\n        buffer.ptr,\n        buffer.len,\n        c.SPNG_FMT_PNG,\n        c.SPNG_ENCODE_FINALIZE\n    );\n    if (encode_status != 0) {\n        return error.CouldNotEncodeImage;\n    }\n    if (c.fclose(file_descriptor) != 0) {\n        return error.CouldNotCloseFileDescriptor;\n    }\n}\n\ntry save_png(&image_header, buffer[0..]);\n```\n:::\n\n\n\n\nAfter we execute this `save_png()` function, we should have a new PNG file\ninside our CWD, named `pedro_pascal_filter.png`. If we open this PNG file,\nwe will see the same image exposed at @fig-pascal-gray.\n\n\n## Building our project\n\nNow that we have written the code, let's discuss how can we build/compile this project.\nTo do that, I'm going to create a `build.zig` file in the root directory of our project,\nand start writing the necessary code to compile the project, using the knowledge\nthat we have acquired from @sec-build-system.\n\n\nWe first create the build target for our executable file, that executes our\nZig code. Let's suppose that all of our Zig code was written into a Zig module\nnamed `image_filter.zig`. The `exe` object exposed in the build script below\ndescribes the build target for our executable file.\n\nSince we have used some C code from the `libspng` library in our Zig code,\nwe need to link our Zig code (which is in the `exe` build target) to both\nthe C Standard Library, and, to the `libspng` library. We do that, by calling\nthe `linkLibC()` and `linkSystemLibrary()` methods from our `exe` build target.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const target = b.standardTargetOptions(.{});\n    const optimize = b.standardOptimizeOption(.{});\n    const exe = b.addExecutable(.{\n        .name = \"image_filter\",\n        .root_source_file = b.path(\"src/image_filter.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n    exe.linkLibC();\n    // Link to libspng library:\n    exe.linkSystemLibrary(\"spng\");\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\nSince we are using the `linkSystemLibrary()` method, it means that the library\nfiles for `libspng` are searched in your system to be linked with the `exe` build target.\nIf you have not yet built and installed the `libspng` library into your system, this\nlinkage step will likely not work. Because it will not find the library files in your system.\n\nSo, just remember to install `libspng` in your system, if you want to build this project.\nHaving this build script above written, we can finally build our project by\nrunning the `zig build` command in the terminal.\n\n```bash\nzig build\n```\n\n\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/14-threads/execute-results/html.json b/_freeze/Chapters/14-threads/execute-results/html.json
index 6bd8b089..391ecd93 100644
--- a/_freeze/Chapters/14-threads/execute-results/html.json
+++ b/_freeze/Chapters/14-threads/execute-results/html.json
@@ -3,9 +3,7 @@
   "result": {
     "engine": "knitr",
     "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Introducing threads and parallelism in Zig {#sec-thread}\n\nThreads are available in Zig through the `Thread` struct from the Zig Standard Library.\nThis struct represents a kernel thread, and it follows a POSIX Thread pattern,\nmeaning that, it works similarly to a thread from the `pthread` C library, which is usually available on any distribution\nof the GNU C Compiler (`gcc`). If you are not familiar with threads, I will give you some theory behind it first, shall we?\n\n\n## What are threads? {#sec-what-thread}\n\nA thread is basically a separate context of execution.\nWe use threads to introduce parallelism into our program,\nwhich in most cases, makes the program run faster, because we have multiple tasks\nbeing performed at the same time, parallel to each other.\n\nPrograms are normally single-threaded by default. Which means that each program\nusually runs on a single thread, or, a single context of execution. When we have only one thread running, we have no\nparallelism. And when we don't have parallelism, the commands are executed sequentially, that is,\nonly one command is executed at a time, one after another. By creating multiple threads inside our program,\nwe start to execute multiple commands at the same time.\n\nPrograms that create multiple threads are very common on the wild. Because many different types\nof applications are well suited for parallelism. Good examples are video and photo-editing applications\n(e.g. Adobe Photoshop or DaVinci Resolve), games (e.g. The Witcher 3), and also web browsers\n(e.g. Google Chrome, Firefox, Microsoft Edge, etc).\nFor example, in web browsers, threads are normally used to implement tabs.\nThe tabs in a web browsers usually run as separate threads in the main process of\nthe web browser. That is, each new tab that you open in your web browser,\nusually runs on a separate thread of execution.\n\nBy running each tab in a separate thread, we allow all open tabs in the browser to run at the same time,\nand independently from each other. For example, you might have YouTube, or Spotify, currently opened in\na tab, and you are listening to some podcast in that tab, while, at the same time,\nyou are working in another tab, writing an essay on Google Docs. Even if you are not looking\ninto the YouTube tab, you can still hear the podcast only because this YouTube tab is running in parallel\nwith the other tab where Google Docs is running.\n\nWithout threads, the other alternative would be to run each tab as a completely separate\nprocess in your computer. But that would be a bad choice, because just a few tabs would already consume\ntoo much power and resources from your computer. In other words, is very expensive to create a completely new process,\ncompared to creating a new thread of execution. Also, the chances of you experiencing lag and overhead\nwhile using the browser would be significant. Threads are faster to create, and they also consume\nmuch, much less resources from the computer, especially because they share some resources\nwith the main process.\n\nTherefore, is the use of threads in modern web browsers that allows you to hear the podcast\nat the same time while you are writing something on Google Docs.\nWithout threads, a web browser would probably be limited to just one single tab.\n\nThreads are also well-suited for anything that involves serving requests or orders.\nBecause serving a request takes time, and usually involves a lot of \"waiting time\".\nIn other words, we spend a lot of time in idle, waiting for something to complete.\nFor example, consider a restaurant. Serving orders in a restaurant usually involves\nthe following steps:\n\n1. receive order from the client.\n1. pass the order to the kitchen, and wait for the food to be cooked.\n1. start cooking the food in the kitchen.\n1. when the food is fully cooked deliver this food to the client.\n\nIf you think about the bullet points above, you will notice that one big moment of waiting time\nis present in this whole process, which is while the food is being cooked\ninside the kitchen. While the food is being prepped, both the waiter and the client\nitself are waiting for the food to be ready and delivered.\n\nIf we write a program to represent this restaurant, more specifically, a single-threaded program, then,\nthis program would be very inefficient. Because the program would stay in idle, waiting for a considerable amount\nof time on the \"check if food is ready\" step. Consider the code snippet exposed below that could\npotentially represent such program.\n\nThe problem with this program is the while loop. This program will spend a lot of time\nwaiting on the while loop, doing nothing more than just checking if the food is ready.\nThis is a waste of time. Instead of waiting for something to happen, the waiter\ncould just send the order to the kitchen, and just move on, and continue with receiving\nmore orders from other clients, and sending more orders to the kitchen, instead\nof doing nothing and waiting for the food to be ready.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst order = Order.init(\"Pizza Margherita\", n = 1);\nconst waiter = Waiter.init();\nwaiter.receive_order(order);\nwaiter.ask_kitchen_to_cook();\nvar food_not_ready = true;\nwhile (food_not_ready) {\n    food_not_ready = waiter.is_food_ready();\n}\nconst food = waiter.get_food_from_kitchen();\nwaiter.send_food_to_client(food);\n```\n:::\n\n\n\n\nThis is why threads would be a great fit for this program. We could use threads\nto free the waiters from their \"waiting duties\", so they can go on with their\nother tasks, and receive more orders. Take a look at the next example, where I have re-written the above\nprogram into a different program that uses threads to cook and deliver the orders.\n\nYou can see in this program that when a waiter receives a new order\nfrom a client, this waiter executes the `send_order()` function.\nThe only thing that this function does is to create a new thread\nand detaches it. Since creating a thread is a very fast operation,\nthis `send_order()` function returns almost immediately,\nso the waiter spends almost no time worrying about the order, and just\nmove on and tries to get the next order from the clients.\n\nInside the new thread created, the order get's cooked by a chef, and when the\nfood is ready, it is delivered to the client's table.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn cook_and_deliver_order(order: *Order) void {\n    const chef = Chef.init();\n    const food = chef.cook(order.*);\n    chef.deliver_food(food);\n}\nfn send_order(order: Order) void {\n    const cook_thread = Thread.spawn(\n        .{}, cook_and_deliver_order, .{&order}\n    );\n    cook_thread.detach();\n}\n\nconst waiter = Waiter.init();\nwhile (true) {\n    const order = waiter.get_new_order();\n    if (order) {\n        send_order(order);\n    }\n}\n```\n:::\n\n\n\n\n\n\n## Threads versus processes\n\nWhen we run a program, this program is executed as a *process* in the operating system.\nThis is a one to one relationship, each program or application that you execute\nis a separate process in the operating system. But each program, or each process,\ncan create and contain multiple threads inside of it. Therefore,\nprocesses and threads have a one to many relationship.\n\nThis also means that every thread that we create is always associated with a particular process in our computer.\nIn other words, a thread is always a subset (or a children) of an existing process.\nAll threads share some of the resources associated with the process from which they were created.\nAnd because threads share resources with the process, they are very good for making communication\nbetween tasks easier.\n\nFor example, suppose that you were developing a big and complex application\nthat would be much simpler if you could split it in two, and make these two separate pieces talk\nwith each other. Some programmers opt to effectively write these two pieces of the codebase as two\ncompletely separate programs, and then, they use IPC (*inter-process communication*) to make these\ntwo separate programs/processes talk to each other, and make them work together.\n\nHowever, some programmers find IPC hard to deal with, and, as consequence,\nthey prefer to write one piece of the codebase as the \"main part of the program\",\nor, as the part of the code that runs as the process in the operating system,\nwhile the other piece of the codebase is written as a task to be executed in\na new thread. A process and a thread can easily comunicate with each other\nthrough both control flow, and also, through data, because they share and have\naccess to the same standard file descriptors (`stdout`, `stdin`, `stderr`), and also to the\nsame memory space on the heap and global data section.\n\n\nIn more details, each thread that you create have a separate stack frame reserved just for that thread,\nwhich essentially means that each local object that you create inside this thread, is local to that\nthread, i.e. the other threads cannot see this local object. Unless this object that you have created\nis an object that lives on the heap. In other words, if the memory associated with this object\nis on the heap, then, the other threads can potentially access this object.\n\nTherefore, objects that are stored in the stack are local to the thread where they were created.\nBut objects that are stored on the heap are potentially accessible to other threads. All of this means that,\neach thread have its own separate stack frame, but, at the same time, all threads share\nthe same heap, the same standard file descriptors (which means that they share the same `stdout`, `stdin`, `stderr`),\nand the same global data section in the program.\n\n\n\n## Creating a thread\n\nWe create new threads in Zig, by first, importing the `Thread` struct into\nour current Zig module, and then, calling the `spawn()` method of this struct,\nwhich creates (or, \"spawns\") a new thread of execution from our current process.\nThis method have three arguments, which are, respectively:\n\n1. a `SpawnConfig` object, which contains configurations for the spawn process.\n1. the name of the function that is going to be executed (or, that is going to be \"called\") inside this new thread.\n1. a list of arguments (or inputs) to be passed to the function provided in the second argument.\n\nWith these three arguments, you can control how the thread get's created, and also, specify which\nwork (or \"tasks\") will be performed inside this new thread. A thread is just a separate context of execution,\nand we usually create new threads in our code, because we want to perform some work inside this\nnew context of execution. And we specify which exact work, or, which exact steps that are going to be\nperformed inside this context, by providing the name of a function on the second argument of the `spawn()` method.\n\nThus, when this new thread get's created, this function that you provided as input to the `spawn()`\nmethod get's called, or, get's executed inside this new thread. You can control the\narguments, or, the inputs that are passed to this function when it get's called, by providing\na list of arguments (or a list of inputs) on the third argument of the `spawn()` method.\nThese arguments are passed to the function in the same order that they are\nprovided to `spawn()`.\n\nFurthermore, the `SpawnConfig` is a struct object with only two possible fields, or, two possible members, that you\ncan set to tailor the spawn behaviour. These fields are:\n\n- `stack_size`: you can provide an `usize` value to specify the size (in bytes) of the thread's stack frame. By default, this value is: $16 \\times 1024 \\times 1024$.\n- `allocator`: you can provide an allocator object to be used when allocating memory for the thread.\n\nTo use one of these two fields (or, \"configs\") you just have to create a new object of type `SpawnConfig`,\nand provide this object as input to the `spawn()` method. But, if you are not interested in using\none of these configs, and you are ok with using just the defaults, you can just provide an anonymous\nstruct literal (`.{}`) in the place of this `SpawnConfig` argument.\n\nAs our first, and very simple example, consider the code exposed below.\nInside the same program, you can create multiple threads of execution if you want to.\nBut, in this first example, we are creating just a single thread of execution, because\nwe call `spawn()` only once.\n\nAlso, notice in this example that we are executing the function `do_some_work()`\ninside the new thread. Since this function receives no inputs, because it has\nno arguments, we have passed an empty list in this instance, or, more precisely,\nan empty and anonymous struct (`.{}`) in the third argument of `spawn()`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Thread = std.Thread;\nfn do_some_work() !void {\n    _ = try stdout.write(\"Starting the work.\\n\");\n    std.time.sleep(100 * std.time.ns_per_ms);\n    _ = try stdout.write(\"Finishing the work.\\n\");\n}\n\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, do_some_work, .{});\n    thread.join();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nStarting the work.Finishing the work.\n```\n\n\n:::\n:::\n\n\n\n\nNotice the use of `try` when calling the `spawn()` method. This means\nthat this method can return an error in some circumstances. One circumstance\nin particular is when you attempt to create a new thread, when you have already\ncreated too much (i.e. you have exceeded the quota of concurrent threads in your system).\n\nBut, if the new thread is successfully created, the `spawn()` method returns a handler\nobject (which is just an object of type `Thread`) to this new thread. You can use\nthis handler object to effectively control all aspects of the thread.\n\nWhen the thread get's created, the function that you provided as input to `spawn()`\nget's invoked (i.e. get's called) to start the execution on this new thread.\nIn other words, everytime you call `spawn()`, not only a new thread get's created,\nbut also, the \"start work button\" of this thread get's automatically pressed.\nSo the work being performed in this thread starts at the moment that the thread is created.\nThis is similar to how `pthread_create()` from the `pthreads` library in C works,\nwhich also starts the execution at the moment that the thread get's created.\n\n\n## Returning from a thread\n\nWe have learned on the previous section that the execution of the thread starts at the moment\nthat the thread get's created. Now, we will learn how to \"join\" or \"detach\" a thread in Zig.\n\"Join\" and \"detach\" are operations that control how the thread returns to\nthe main thread, or, to the main process in our program.\n\nWe perform these operations by using the methods `join()` and `detach()` from the thread handler object.\nEvery thread that you create can be marked as either *joinable* or *detached* [@linux_pthread_create].\nYou can turn a thread into a *detached* thread by calling the `detach()` method\nfrom the thread handler object. But if you call the `join()` method instead, then, this thread\nbecomes a *joinable* thread.\n\nA thread cannot be both *joinable* and *detached*. Which in general means\nthat you cannot call both `join()` and `detach()` on the same thread.\nBut a thread must be one of the two, meaning that, you should always call\neither `join()` or `detach()` over a thread. If you don't call\none of these two methods over your thread, you introduce undefined behaviour into your program,\nwhich is described at @sec-not-call-join-detach.\n\nNow, let's describe what each of these two methods do to your thread.\n\n\n### Joining a thread\n\nWhen you join a thread, you are essentially saying: \"Hey! Could you please wait for the thread to finish,\nbefore you continue with your execution?\". For example, if we comeback to our first and simpliest example\nof a thread in Zig, in that example we have created a single thread inside the `main()` function of our program,\nand just called `join()` over this thread at the end. This section of the code example is reproduced below.\n\nBecause we are joining this new thread inside the `main()`'s scope, it means that the\nexecution of the `main()` function is temporarily stopped, to wait for the execution of the thread\nto finish. That is, the execution of `main()` stops temporarily at the line where `join()` get's called,\nand it will continue only after the thread has finished its tasks.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, do_some_work, .{});\n    thread.join();\n}\n```\n:::\n\n\n\n\nBecause we have joined this new thread inside the `main()` scope, we have a\nguarantee that this new thread will finish before the end of the execution of `main()`.\nBecause it is guaranteed that `main()` will wait for the thread to finish its tasks.\n\nIn the example above, there are no more expressions after the `join()` call. We just have the end\nof the `main()`'s scope, and, therefore, the execution of our program just ends after the thread finishes its tasks,\nsince there is nothing more to do. But what if we had more stuff to do after the join call?\n\nTo demonstrate this other possibility, consider the next example exposed\nbelow. Here, we create a `print_id()` function, that just receives an id\nas input, and prints it to `stdout`. In this example, we are creating two\nnew threads, one after another. Then, we join the first thread, then,\nwe wait for two whole seconds, then, at last, we join the second thread.\n\nThe idea behind this example is that the last `join()` call is executed\nonly after the first thread finishes its task (i.e. the first `join()` call),\nand also, after the two seconds of delay. If you compile and run this\nexample, you will notice that most messages are quickly printed to `stdout`,\ni.e. they appear almost instantly on your screen.\nHowever, the last message (\"Joining thread 2\") takes around 2 seconds to appear\nin the screen.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_id(id: *const u8) !void {\n    try stdout.print(\"Thread ID: {d}\\n\", .{id.*});\n}\n\npub fn main() !void {\n    const id1: u8 = 1;\n    const id2: u8 = 2;\n    const thread1 = try Thread.spawn(.{}, print_id, .{&id1});\n    const thread2 = try Thread.spawn(.{}, print_id, .{&id2});\n\n    _ = try stdout.write(\"Joining thread 1\\n\");\n    thread1.join();\n    std.time.sleep(2 * std.time.ns_per_s);\n    _ = try stdout.write(\"Joining thread 2\\n\");\n    thread2.join();\n}\n```\n:::\n\n\n\n\n```\nThread ID: Joining thread 1\n1\nThread ID: 2\nJoining thread 2\n```\n\nThis demonstrates that both threads finish their work (i.e. printing the IDs)\nvery fast, before the two seconds of delay end. Because of that, the last `join()` call\nreturns pretty much instantly. Because when this last `join()` call happens, the second\nthread have already finished its task.\n\nNow, if you compile and run this example, you will also notice that, in some cases,\nthe messages intertwine with each other. In other words, you might see\nthe message \"Joining thread 1\" inserted in the middle of the message \"Thread 1\",\nor vice-versa. This happens because:\n\n- the threads are executing basically at the same time as the main process of the program (i.e. the `main()` function).\n- the threads share the same `stdout` from the main process of the program, which means that the messages that the threads produce are sent to exact same place as the messages produced by the main process.\n\nBoth of these points were described previously at @sec-what-thread.\nSo the messages might get intertwined because they are being produced and\nsent to the same `stdout` roughly at the same time.\nAnyway, when you call `join()` over a thread, the current process will wait\nfor the thread to finish before it continues, and, when the thread does finishes its\ntask, the resources associated with this thread are automatically freed, and,\nthe current process continues with its execution.\n\n\n### Detaching a thread\n\nWhen you detach a thread, the resources associated with this thread are automatically\nreleased back to the system, without the need for another thread to join with this terminated thread.\n\nIn other words, when you call `detach()` over a thread it's like when your children becomes adults,\ni.e. they become independent from you. A detached thread frees itself, and when this thread finishes its\ntasks, it does not report the results back to you. Thus, you normally mark a thread as *detached*\nwhen you don't need to use the return value of the thread, or, when you don't care about\nwhen exactly the thread finishes its job, i.e. the thread solves everything by itself.\n\nTake the code example below. We create a new thread, detach it, and then, we just\nprint a final message before we end our program. We use the same `print_id()`\nfunction that we have used over the previous examples.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_id(id: *const u8) !void {\n    try stdout.print(\"Thread ID: {d}\\n\", .{id.*});\n}\n\npub fn main() !void {\n    const id1: u8 = 1;\n    const thread1 = try Thread.spawn(.{}, print_id, .{&id1});\n    thread1.detach();\n    _ = try stdout.write(\"Finish main\\n\");\n}\n```\n:::\n\n\n\n\n```\nFinish main\n```\n\nNow, if you look closely at the output of this code example, you will notice\nthat only the final message in main was printed to the console. The message\nthat was supposed to be printed by `print_id()` did not appear in the console.\nWhy? Is because the main process of our program has finished first,\nbefore the thread was able to say anything.\n\nAnd that is perfectly ok behaviour, because the thread was detached, so, it was\nable to free itself, without the need to wait for the main process.\nIf you ask main to sleep (or \"wait\") for some extra nanoseconds, before it ends, you will likely\nsee the message printed by `print_id()`, because you give enough time for the thread to\nfinish before the main process ends.\n\n\n## Thread pools\n\nThread pools is a very popular programming pattern, which is used especially on servers and daemons processes.\nA thread pool is just a set of threads, or, a \"pool\" of threads. Many programmers like to use this pattern, because it makes\neasier to manage and use multiple threads in your program, instead of manually creating the threads when you need them.\n\nAlso, using thread pools might increase performance as well in your program,\nespecially if your program is constantly creating threads to perform short-lived tasks.\nIn such instance, a thread pool might cause an increase in performance because you do not have be constantly\ncreating and destroying threads all the time, so you don't face a lot of the overhead involved\nin this constant process of creating and destroying threads.\n\nThe main idea behind a thread pool is to have a set of threads already created and ready to perform\ntasks at all times. You create a set of threads at the moment that your program starts, and keep\nthese threads alive while your program runs. Each of these threads will be either performing a task, or,\nwaiting for a task to be assigned.\nEvery time a new task emerges in your program, this task is added to a \"queue of tasks\",\nand the moment that a thread becomes available and ready to perform a new task,\nthis thread takes the next task from the \"queue of tasks\", and it simply performs the task.\n\nThe Zig Standard Library offers a thread pool implementation on the `std.Thread.Pool` struct.\nYou create a new instance of a `Pool` object by providing a `Pool.Options` object\nas input to the `init()` method of this struct. A `Pool.Options` object, is a struct object that contains\nconfigurations for the pool of threads. The most important settings in this struct object are\nthe members `n_jobs` and `allocator`. As the name suggests, the member `allocator` should receive an allocator object,\nwhile the member `n_jobs` specifies the number of threads to be created and maintained in this pool.\n\nConsider the example exposed below, that demonstrates how can we create a new thread pool object.\nHere, we create a `Pool.Options` object that contains\na general purpose allocator object, and also, the `n_jobs` member was set to 4, which\nmeans that the thread pool will create and use 4 threads.\n\nAlso notice that the `pool` object was initially set to `undefined`. This allow us\nto initially declare the thread pool object, but not properly instantiate the\nunderlying memory of the object. You have to initially declare your thread pool object\nby using `undefined` like this, because the `init()` method of `Pool` needs\nto have an initial pointer to properly instantiate the object.\n\nSo, just remember to create your thread pool object by using `undefined`, and then,\nafter that, you call the `init()` method over the object.\nYou should also not forget to call the `deinit()` method over the thread pool\nobject, once you are done with it, to release the resources allocated for the thread pool. Otherwise, you will\nhave a memory leak in your program.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Pool = std.Thread.Pool;\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const opt = Pool.Options{\n        .n_jobs = 4,\n        .allocator = allocator,\n    };\n    var pool: Pool = undefined;\n    _ = try pool.init(opt);\n    defer pool.deinit();\n}\n```\n:::\n\n\n\n\nNow that we know how to create `Pool` objects, we have\nto understand how to assign tasks to be executed by the threads in this pool object.\nTo assign a task to be performed by a thread, we need to call the `spawn()` method\nfrom the thread pool object.\n\nThis `spawn()` method works identical to the `spawn()` method from the\n`Thread` object. The method have almost the same arguments as the previous one,\nmore precisely, we don't have to provide a `SpawnConfig` object in this case.\nBut instead of creating a new thread, this `spawn()` method from\nthe thread pool object just register a new task in the internal \"queue of tasks\" to be performed,\nand any available thread in the pool will get this task, and it will simply perform the task.\n\nIn the example below, we are using our previous `print_id()` function once again.\nBut you may notice that the `print_id()` function is a little different this time,\nbecause now we are using `catch` instead of `try` in the `print()` call.\nCurrently, the `Pool` struct only supports functions that don't return errors\nas tasks. Thus, when assigning tasks to threads in a thread pool, is essential to use functions\nthat don't return errors. That is why we are using `catch` here, so that the\n`print_id()` function don't return an error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_id(id: *const u8) void {\n    _ = stdout.print(\"Thread ID: {d}\\n\", .{id.*})\n        catch void;\n}\nconst id1: u8 = 1;\nconst id2: u8 = 2;\ntry pool.spawn(print_id, .{&id1});\ntry pool.spawn(print_id, .{&id2});\n```\n:::\n\n\n\n\nThis limitation should probably not exist, and, in fact, it is already on the radar of the\nZig team to fix this issue, and it is being tracked on an [open issue](https://github.com/ziglang/zig/issues/18810)[^issue].\nSo, if you do need to provide a function that might return an error as the task\nto be performed by the threads in the thread pool, then, you are either limited to:\n\n- implementing your own thread pool that does not have this limitation.\n- wait for the Zig team to actually fix this issue.\n\n[^issue]: <https://github.com/ziglang/zig/issues/18810>\n\n\n\n\n## Mutexes\n\nMutexes are a classic component of every thread library. In essence, a mutex is a *Mutually Exclusive Flag*, and this flag\nacts like a type of \"lock\", or as a gate keeper to a particular section of your code. Mutexes are related to thread synchronization,\nmore specifically, they prevent you from having some classic race conditions in your program,\nand, therefore, major bugs and undefined behaviour that are usually difficult to track and understand.\n\nThe main idea behind a mutex is to help us to control the execution of a particular section of the code, and to\nprevent two or more threads from executing this particular section of the code at the same time.\nMany programmers like to compare a mutex to a bathroom door (which usually have a lock).\nWhen a thread locks its own mutex object, it is like if the bathroom door was locked,\nand, therefore, the other people (in this case, the other threads) that wants to use the same bathroom at the same time\nhave to be patient, and simply wait for the other person (or the other thread) to unlock the door and get out of the bathroom.\n\nSome other programmers also like to explain mutexes by using the analogy of \"each person will have their turn to speak\".\nThis is the analogy used on the [*Multithreading Code* video from the Computerphile project](https://www.youtube.com/watch?v=7ENFeb-J75k&ab_channel=Computerphile)[^computerphile].\nImagine if you are in a conversation circle. There is a moderator in this circle, which is the person that decides who\nhave the right to speak at that particular moment. The moderator gives a green card (or some sort of an authorization card) to the person that\nis going to speak, and, as a result, everyone else must be silent and hear this person that has the green card.\nWhen the person finishes talking, it gives the green card back to the moderator, and the moderator decides\nwho is going to talk next, and delivers the green card to that person. And the cycle goes on like this.\n\n[^computerphile]: <https://www.youtube.com/watch?v=7ENFeb-J75k&ab_channel=Computerphile>\n\n\nA mutex acts like the moderator in this conversation circle. The mutex authorizes one single thread to execute a specific section of the code,\nand it also blocks the other threads from executing this same section of the code. If these other threads want to execute this same\npiece of the code, they are forced to wait for the the authorized thread to finish first.\nWhen the authorized thread finishes executing this code, the mutex authorizes the next thread to execute this code,\nand the other threads are still blocked. Therefore, a mutex is like a moderator that does a \"each\nthread will have their turn to execute this section of the code\" type of control.\n\n\nMutexes are especially used to prevent data race problems from happening. A data race problem happens when two or more threads\nare trying to read from or write to the same shared object at the same time.\nSo, when you have an object that is shared will all threads, and, you want to avoid two or more threads from\naccessing this same object at the same time, you can use a mutex to lock the part of the code that access this specific object.\nWhen a thread tries to run this code that is locked by a mutex, this thread stops its execution,\nand patiently waits for this section of the codebase to be unlocked to continue.\n\nNotice that mutexes are normally used to lock areas of the codebase that access/modify data that is **shared** with all threads,\ni.e. objects that are either stored in the global data section, or, in the heap space of your program.\nSo mutexes are not normally used on areas of the codebase that access/modify objects that are local to the thread.\n\n\n\n### Critical section {#sec-critical-section}\n\nCritical section is a concept commonly associated with mutexes and thread synchronization.\nIn essence, a critical section is the section of the program that a thread access/modify a shared resource\n(i.e. an object, a file descriptor, something that all threads have access to). In other words,\na critical section is the section of the program where race conditions might happen, and, therefore,\nwhere undefined behaviour can be introduced into the program.\n\nWhen we use mutexes in our program, the critical section defines the area of the codebase that we want to lock.\nSo we normally lock the mutex object at the beginning of the critical section,\nand then, we unlock it at the end of the critical section.\nThe two bullet points exposed below comes from the \"Critical Section\" article from GeekFromGeeks,\nand they summarise well the role that a critical section plays in the thread synchronization problem [@geeks_critical_section].\n\n\n1. The critical section must be executed as an atomic operation, which means that once one thread or process has entered the critical section, all other threads or processes must wait until the executing thread or process exits the critical section. The purpose of synchronization mechanisms is to ensure that only one thread or process can execute the critical section at a time.\n1. The concept of a critical section is central to synchronization in computer systems, as it is necessary to ensure that multiple threads or processes can execute concurrently without interfering with each other. Various synchronization mechanisms such as semaphores, mutexes, monitors, and condition variables are used to implement critical sections and ensure that shared resources are accessed in a mutually exclusive manner.\n\n\n### Atomic operations {#sec-atomic-operation}\n\nYou will also see the term \"atomic operation\" a lot when reading about threads, race conditions and mutexes.\nIn summary, an operation is categorized as \"atomic\", when there is no way to happen a context switch in\nthe middle of this operation. In other words, this operation is always done from beginning to end, without interruptions\nof another process or operation in the middle of its execution phase.\n\nNot many operations today are atomic. But why atomic operations matters here? Is because data races\n(which is a type of a race condition) cannot happen on operations that are atomic.\nSo if a particular line in your code performs an atomic operation, then, this line will never\nsuffer from a data race problem. Therefore, programmers sometimes use an atomic operation\nto protect themselves from data race problems in their code.\n\nWhen you have an operation that is compiled into just one single assembly instruction, this operation might be atomic,\nbecause it is just one assembly instruction. But this is not guaranteed. This is usually true for old CPU architectures\n(such as `x86`). But nowadays, most assembly instructions in modern CPU architectures turn into multiple micro-tasks,\nwhich inherently makes the operation not atomic anymore, even though it has just one single assembly instruction.\n\nThe Zig Standard Library offers some atomic functionality at the `std.atomic` module.\nIn this module, you will find a public and generic function called `Value()`. With this function we create an \"atomic object\", which is\na value that contains some native atomic operations, most notably, a `load()` and a `fetchAdd()` operation.\nIf you have experience with multithreading in C++, you probably have recognized this pattern. So yes, this generic\n\"atomic object\" in Zig is essentially identical to the template struct `std::atomic` from the C++ Standard Library.\nIs important to emphasize that only primitive data types (i.e. the types presented at @sec-primitive-data-types)\nare supported by these atomic operations in Zig.\n\n\n\n\n\n### Data races and race conditions\n\nTo understand why mutexes are used, we need to understand better the problem that they seek\nto solve, which can be summarized into data races problems. A data race problem is a type of a race condition,\nwhich happens when one thread is accessing a particular memory location (i.e. a particular shared object) at the same\ntime that another thread is trying to write/save new data into this same memory location (i.e. the same shared object).\n\nWe can simply define a race condition as any type of bug in your program that is based\non a \"who get's there first\" problem. A data race problem is a type of a race condition, because it occurs when two or more parties\nare trying to read and write into the same memory location at the same time, and, therefore, the end result of this operation\ndepends completely on who get's to this memory location first.\nAs consequence, a program that have a data race problem will likely produce a different result each time that we execute it.\n\nThus, race conditions produce undefined behaviour and unpredictability because the program produces\na different answer in each time that a different person get's to the target location first than the others.\nAnd we have no easy way to either predict or control who is getting to this target location first.\nIn other words, in each execution of your program, you get a different answer, because a different person,\nor, a different function, or, a different part of the code is finishing its tasks first than the others.\n\nAs an example, consider the code snippet exposed below. In this example, we create a global counter\nvariable, and we also create an `increment()` function, whose job is to just increment this global counter\nvariable in a for loop.\n\nSince the for loop iterates 1 hundred thousand times, and, we create two separate threads\nin this code example, what number do you expect to see in the final message printed to `stdout`?\nThe answer should be 2 hundred thousand. Right? Well, in theory, this program was supposed\nto print 2 hundred thousand at the end, but in practice, every time that I execute this program\nI get a different answer.\n\nIn the example exposed below, you can see that this time the end\nresult was 117254, instead of the expected 200000. The second time I have executed this program,\nI got the number 108592 as result. So the end result of this program is varying, but it never gets\nto the expected 200000 that we want.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// Global counter variable\nvar counter: usize = 0;\n// Function to increment the counter\nfn increment() void {\n    for (0..100000) |_| {\n        counter += 1;\n    }\n}\n\npub fn main() !void {\n    const thr1 = try Thread.spawn(.{}, increment, .{});\n    const thr2 = try Thread.spawn(.{}, increment, .{});\n    thr1.join();\n    thr2.join();\n    try stdout.print(\"Couter value: {d}\\n\", .{counter});\n}\n```\n:::\n\n\n\n\n```\nCouter value: 117254\n```\n\n\nWhy this is happening? The answer is: because this program contains a data race problem.\nThis program would print the correct number 200000, if, and only if the first thread finishes\nits tasks before the second thread starts to execute. But that is very unlikely to happen.\nBecause the process of creating the thread is too fast, and therefore, both threads starts to execute roughly\nat the same time. If you change this code to add some nanoseconds of sleep between the first and the second calls to `spawn()`,\nyou will increase the chances of the program producing the \"correct result\".\n\nSo the data race problem happens, because both threads are reading and writing to the same\nmemory location at roughly the same time. In this example, each thread is essentially performing\nthree basic operations at each iteration of the for loop, which are:\n\n1. reading the current value of `count`.\n1. incrementing this value by 1.\n1. writing the result back into `count`.\n\nIdeally, a thread B should read the value of `count`, only after the other thread A has finished\nwriting the incremented value back into the `count` object. Therefore, in the ideal scenario, which is demonstrated\nat @tbl-data-race-ideal, the threads should work in sync with each other. But the reality is that these\nthreads are out of sync, and because of that, they suffer from a data race problem, which is demonstrated\nat @tbl-data-race-not.\n\nNotice that, in the data race scenario (@tbl-data-race-not), the read performed by a thread B happens\nbefore the write operation of thread A, and that ultimately leads to wrong results at the end of the program.\nBecause when the thread B reads the value from the `count` variable, the thread A is still processing\nthe initial value from `count`, and it did not write the new and incremented value into `count` yet. So what\nhappens is that thread B ends up reading the same initial value (the \"old\" value) from `count`, instead of\nreading the new and incremented version of this value that would be calculated by thread A.\n\n\n::: {#tbl-data-race-ideal}\n\n| Thread 1    | Thread 2    | Integer value |\n|-------------|-------------|---------------|\n| read value  |             | 0             |\n| increment   |             | 1             |\n| write value |             | 1             |\n|             | read value  | 1             |\n|             | increment   | 2             |\n|             | write value | 2             |\n\n: An ideal scenario for two threads incrementing the same integer value\n:::\n\n::: {#tbl-data-race-not}\n\n| Thread 1    | Thread 2    | Integer value |\n|-------------|-------------|---------------|\n| read value  |             | 0             |\n|             | read value  | 0             |\n| increment   |             | 1             |\n|             | increment   | 1             |\n| write value |             | 1             |\n|             | write value | 1             |\n\n: A data race scenario when two threads are incrementing the same integer value\n:::\n\n\nIf you think about these diagrams exposed in form of tables, you will notice that they relate back to our discussion of atomic operations\nat @sec-atomic-operation. Remember, atomic operations are operations that the CPU executes\nfrom beginning to end, without interruptions from other threads or processes. So,\nthe scenario exposed at @tbl-data-race-ideal do not suffer from a data race, because\nthe operations performed by thread A are not interrupted in the middle by the operations\nfrom thread B.\n\nIf we also think about the discussion of critical section from @sec-critical-section, we can identify\nthe section that representes the critical section of the program, which is the section that is vulnerable\nto data race conditions. In this example, the critical section of the program is the line where we increment\nthe `counter` variable (`counter += 1`). So, ideally, we want to use a mutex, and lock right before this line, and then,\nunlock right after this line.\n\n\n\n\n### Using mutexes in Zig\n\nNow that we know the problem that mutexes seek to solve, we can learn how to use them in Zig.\nMutexes in Zig are available through the `std.Thread.Mutex` struct from the Zig Standard Library.\nIf we take the same code example from the previous example, and improve it with mutexes, to solve\nour data race problem, we get the code example exposed below.\n\nNotice that we had this time to alter the `increment()` function to receive a pointer to\nthe `Mutex` object as input. All that we need to do, to make this program safe against\ndata race problems, is to call the `lock()` method at the beginning of\nthe critical section, and then, call `unlock()` at the end of the critical section.\nNotice that the output of this program is now the correct number of 200000.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Thread = std.Thread;\nconst Mutex = std.Thread.Mutex;\nvar counter: usize = 0;\nfn increment(mutex: *Mutex) void {\n    for (0..100000) |_| {\n        mutex.lock();\n        counter += 1;\n        mutex.unlock();\n    }\n}\n\npub fn main() !void {\n    var mutex: Mutex = .{};\n    const thr1 = try Thread.spawn(.{}, increment, .{&mutex});\n    const thr2 = try Thread.spawn(.{}, increment, .{&mutex});\n    thr1.join();\n    thr2.join();\n    try stdout.print(\"Couter value: {d}\\n\", .{counter});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nCouter value: 200000\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n## Read/Write locks\n\nMutexes are normally used when is always not safe to have two or more threads running the same\npiece of code at the same time. In contrast, read/write locks are normally used in situations\nwhere you have a mixture of scenarios, i.e. there are some pieces of the codebase that are safe\nto run in parallel, and other pieces that are not safe.\n\nFor example, suppose that you have multiple threads that uses the same shared file in the filesystem to store some configurations, or,\nstatistics. If two or more threads try to read the data from this same file at the same time, nothing bad happens.\nSo this part of the codebase is perfectly safe to be executed in parallel, with multiple threads reading the same file at the same time.\n\nHowever, if two or more threads try to write data into this same file at the same time, then, we cause some race conditions\nproblems. So this other part of the codebase is not safe to be executed in parallel.\nMore specifically, a thread might end up writing data in the middle of the data written by the other thread.\nThis process of two or more threads writing to the same location, might lead to data corruption.\nThis specific situation is usually called of a *torn write*.\n\nThus, what we can extract from this example is that there is certain types of operations that causes\na race condition, but there are also, other types of operations that do not cause a race condition problem.\nYou could also say that, there are types of operations that are susceptible to race condition problems,\nand there are other types of operations that are not.\n\nA read/write lock is a type of lock that acknowledges the existance of this specific scenario, and you can\nuse this type of lock to control which parts of the codebase are safe to run in parallel, and which parts are not safe.\n\n\n\n### Exclusive lock vs shared lock\n\nTherefore, a read/write lock is a little different from a mutex. Because a mutex is always an *exclusive lock*, meaning that, only\none thread is allowed to execute at all times. With an exclusive lock, the other threads are always \"excluded\",\ni.e. they are always blocked from executing. But in a read/write lock, the other threads might be authorized\nto run at the same time, depending on the type of lock that they acquire.\n\nWe have two types of locks in a read/write lock, which are: an exclusive lock and a shared lock. An exclusive lock works exactly the same\nas a mutex, while a shared lock is a lock that does not block the other threads from running at the same time.\nIn the `pthreads` C library, read/write locks are available through the `pthread_rwlock_t` C struct. With\nthis C struct, you can create:\n\n- a \"write lock\", which corresponds to an exclusive lock.\n- a \"read lock\", which corresponds to a shared lock.\n\nThe terminology might be a little different compared to Zig. But the meaning is still the same.\nTherefore, just remember this relationship, write locks are exclusive locks, while read locks are shared locks.\n\nWhen a thread tries to acquire a read lock (i.e. a shared lock), this thread get's the shared lock\nif, and only if another thread does not currently holds a write lock (i.e. an exclusive lock), and also,\nif there are no other threads that are already in the queue,\nwaiting for their turn to acquire a write lock. In other words, the thread in the queue have attempted\nto get a write lock earlier, but this thread was blocked\nbecause there was another thread running that already had a write lock. As consequence, this thread is on the queue to get a write lock,\nand it's currently waiting for the other thread with a write lock to finish its execution.\n\nWhen a thread tries to acquire a read lock, but it fails in acquiring this read lock, either because there is\na thread with a write lock already running, or, because there is a thread in the queue to get a write lock,\nthe execution of this thread is instantly blocked, i.e. paused. This thread will indefinitely attempt to get the\nread lock, and its execution will be unblocked (or unpaused) only after this thread successfully acquires the read lock.\n\nIf you think deeply about this dynamic between read locks versus write locks, you might notice that a read lock is basically a safety mechanism.\nMore specifically, it is a way for us to\nallow a particular thread to run together with the other threads, only when it's safe to. In other words, if there is currently\na thread with a write lock running, then, it is very likely not safe for the thread that is trying to acquire the read lock to run now.\nAs consequence, the read lock protects this thread from running into dangerous waters, and patiently waits for the\n\"write lock\" thread to finishes its tasks before it continues.\n\nOn the other hand, if there are only \"read lock\" (i.e. \"shared lock\") threads currently running\n(i.e. not a single \"write lock\" thread currently exists), then,\nis perfectly safe for this thread that is acquiring the read lock to run in parallel with the other\nthreads. As a result, the read lock just\nallows for this thread to run together with the other threads.\n\nThus, by using read locks (shared locks) in conjunction with write locks (exclusive locks), we can control which regions or sections\nof our multithreaded code is safe to have parallelism, and which sections are not safe to have parallelism.\n\n\n\n\n\n### Using read/write locks in Zig\n\nThe Zig Standard Library supports read/write locks through the `std.Thread.RwLock` module.\nIf you want to a particular thread to acquire a shared lock (i.e. a read lock), you should\ncall the `lockShared()` method from the `RwLock` object. But, if you want for this thread\nto acquire an exclusive lock (i.e. a write lock) instead, then, you should call the\n`lock()` method from the `RwLock` object.\n\nAs with mutexes, we also have to unlock the shared or exclusive locks that we acquire through a read/write lock object,\nonce we are at the end of our \"critical section\". If you have acquired an exclusive lock, then, you unlock\nthis exclusive lock by calling the `unlock()` method from the read/write lock object. In contrast,\nif you have acquired a shared lock instead, then, call `unlockShared()` to unlock this shared lock.\n\nAs a simple example, the snippet exposed below creates three separate threads responsible for reading the\ncurrent value in a `counter` object, and it also creates another thread, responsible for writing\nnew data into the `counter` object (incrementing it, more specifically).\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar counter: u32 = 0;\nfn reader(lock: *RwLock) !void {\n    while (true) {\n        lock.lockShared();\n        const v: u32 = counter;\n        try stdout.print(\"{d}\", .{v});\n        lock.unlockShared();\n        std.time.sleep(2 * std.time.ns_per_s);\n    }\n}\nfn writer(lock: *RwLock) void {\n    while (true) {\n        lock.lock();\n        counter += 1;\n        lock.unlock();\n        std.time.sleep(2 * std.time.ns_per_s);\n    }\n}\n\npub fn main() !void {\n    var lock: RwLock = .{};\n    const thr1 = try Thread.spawn(.{}, reader, .{&lock});\n    const thr2 = try Thread.spawn(.{}, reader, .{&lock});\n    const thr3 = try Thread.spawn(.{}, reader, .{&lock});\n    const wthread = try Thread.spawn(.{}, writer, .{&lock});\n\n    thr1.join();\n    thr2.join();\n    thr3.join();\n    wthread.join();\n}\n```\n:::\n\n\n\n\n\n## Yielding a thread\n\nThe `Thread` struct supports yielding through the `yield()` method.\nYielding a thread means that the execution of the thread is temporarily stopped,\nand the thread comes back to the end of the queue of priority of the scheduler from\nyour operating system.\n\nThat is, when you yield a thread, you are essentially saying the following to your OS:\n\"Hey! Could you please stop executing this thread for now, and comeback to continue it later?\".\nYou could also interpret this yield operation as: \"Could you please deprioritize this thread,\nto focus on doing other things instead?\".\nSo this yield operation is also a way for you\nto stop a particular thread, so that you can work and prioritize other threads instead.\n\nIs important to say that, yielding a thread is a \"not so common\" thread operation these days.\nIn other words, not many programmers use yielding in production, simply because is hard to use\nthis operation and make it work properly, and also, there\nare better alternatives. Most programmers prefer to use `join()` instead.\nIn fact, most of the times, when you see somebody using this \"yield\" operation in some code example,\nthey are mostly using it to help them debug race conditions in their applications.\nThat is, this \"yield\" operation is mostly used as a debug tool nowadays.\n\nAnyway, if you want to yield a thread, just call the `yield()` method from it, like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nthread.yield();\n```\n:::\n\n\n\n\n\n\n\n\n\n## Common problems in threads\n\n\n\n### Deadlocks\n\nA deadlock occurs when two or more threads are blocked forever,\nwaiting for each other to release a resource. This usually happens when multiple locks are involved,\nand the order of acquiring them is not well managed.\n\nThe code example below demonstrates a deadlock situation. We have two different threads that execute\ntwo different functions (`work1()` and `work2()`) in this example. And we also have two separate\nmutexes. If you compile and run this code example, you will notice that the program just runs indefinitely,\nwithout ending.\n\nWhen we look into the first thread, which executes the `work1()` function, we can\nnotice that this function acquires the `mut1` lock first. Because this is the first operation\nthat is executed inside this thread, which is the first thread created in the program.\nAfter that, the function sleeps for 1 second, to\nsimulate some type of work, and then, the function tries to acquire the `mut2` lock.\n\nOn the other hand, when we look into the second thread, which executes the `work2()` function,\nwe can see that this function acquires the `mut2` lock first. Because when this thread get's created and it tries\nto acquire this `mut2` lock, the first thread is still sleeping on that \"sleep 1 second\" line.\nAfter acquiring `mut2`, the `work2()` function also sleeps for 1 second, to\nsimulate some type of work, and then, the function tries to acquire the `mut1` lock.\n\nThis creates a deadlock situation, because after the \"sleep for 1 second\" line in both threads,\nthe thread 1 is trying to acquire the `mut2` lock, but this lock is currently being used by thread 2.\nHowever, at this moment, the thread 2 is also trying to acquire the `mut1` lock, which is currently\nbeing used by thread 1. Therefore, both threads end up waiting for ever. Waiting for their peer to\nfree the lock that they want to acquire.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar mut1: Mutex = .{}; var mut2: Mutex = .{};\nfn work1() !void {\n    mut1.lock();\n    std.time.sleep(1 * std.time.ns_per_s);\n    mut2.lock();\n    _ = try stdout.write(\"Doing some work 1\\n\");\n    mut2.unlock(); mut1.unlock();\n}\n\nfn work2() !void {\n    mut2.lock();\n    std.time.sleep(1 * std.time.ns_per_s);\n    mut1.lock();\n    _ = try stdout.write(\"Doing some work 1\\n\");\n    mut1.unlock(); mut2.unlock();\n}\n\npub fn main() !void {\n    const thr1 = try Thread.spawn(.{}, work1, .{});\n    const thr2 = try Thread.spawn(.{}, work2, .{});\n    thr1.join();\n    thr2.join();\n}\n```\n:::\n\n\n\n\n\n### Not calling `join()` or `detach()` {#sec-not-call-join-detach}\n\nWhen you do not call either `join()` or `detach()` over a thread, then, this thread becomes a \"zombie thread\",\nbecause it does not have a clear \"return point\".\nYou could also interpret this as: \"nobody is properly responsible for managing the thread\".\nWhen we don't establish if a thread is either *joinable* or *detached*,\nnobody becomes responsible for dealing with the return value of this thread, and also,\nnobody becomes responsible for clearing (or freeing) the resources associated with this thread.\n\nYou don't want to be in this situation, so remember to always use `join()` or `detach()`\non the threads that you create. When you don't use one of these methods, we lose\ncontrol over the thread, and its resources are never freed\n(i.e. you have leaked resources in the system).\n\n\n### Cancelling or killing a particular thread\n\nWhen we think about the `pthreads` C library, there is a possible way to asynchronously kill or cancel\na thread, which is by sending a `SIGTERM` signal to the thread through the `pthread_kill()` function.\nBut canceling a thread like this is bad. Is dangerously bad. As consequence, the Zig implementation\nof threads does not have a similar function, or, a similar way to asynchronously cancel or kill\na thread.\n\nTherefore, if you want to cancel a thread in the middle of its execution in Zig,\nthen, one good strategy that you can take is to use control flow in conjunction with `join()`.\nMore specifically, you can design your thread around a while loop, that is constantly\nchecking if the thread should continue running.\nIf is time to cancel the thread, we could make the while loop break, and join the thread with the main thread\nby calling `join()`.\n\nThe code example below demonstrates to some extent this strategy.\nHere, we are using control flow to break the while loop, and exit the thread earlier than\nwhat we have initially planned to. This example also demonstrates how can we use\natomic objects in Zig with the `Value()` generic function that we have mentioned at @sec-atomic-operation.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Thread = std.Thread;\nconst stdout = std.io.getStdOut().writer();\nvar running = std.atomic.Value(bool).init(true);\nvar counter: u64 = 0;\nfn do_more_work() void {\n    std.time.sleep(2 * std.time.ns_per_s);\n}\nfn work() !void {\n    while (running.load(.monotonic)) {\n        for (0..10000) |_| { counter += 1; }\n        if (counter < 15000) {\n            _ = try stdout.write(\n                \"Time to cancel the thread.\\n\"\n            );\n            running.store(false, .monotonic);\n        } else {\n            _ = try stdout.write(\"Time to do more work.\\n\");\n            do_more_work();\n            running.store(false, .monotonic);\n        }\n    }\n}\n\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, work, .{});\n    thread.join();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nTime to cancel the thread.\n```\n\n\n:::\n:::\n",
-    "supporting": [
-      "14-threads_files"
-    ],
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/14-zig-c-interop/execute-results/html.json b/_freeze/Chapters/14-zig-c-interop/execute-results/html.json
index be5a846d..dac50d94 100644
--- a/_freeze/Chapters/14-zig-c-interop/execute-results/html.json
+++ b/_freeze/Chapters/14-zig-c-interop/execute-results/html.json
@@ -3,9 +3,7 @@
   "result": {
     "engine": "knitr",
     "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Zig interoperability with C\n\nIn this chapter, we are going to discuss the interoperability of Zig with C.\nWe have discussed at @sec-building-c-code how you can use the `zig` compiler to build C code.\nBut we haven't discussed yet how to actually use C code in Zig. In other words,\nwe haven't discussed yet how to call and use C code from Zig.\n\nThis is the main subject of this chapter.\nAlso, in our next small project in this book, we are going to use a C library in it.\nAs consequence, we will put in practice a lot of the knowledge discussed here on\nthis next project.\n\n\n## How to call C code from Zig\n\nInteroperability with C is not something new. Most high-level programming languages have FFI (foreign function interfaces),\nwhich can be used to call C code. For example, Python have Cython, R have `.Call()`, Javascript have `ccall()`, etc.\nBut Zig integrates with C in a deeper level, which affects not only the way that C code get's called, but also,\nhow this C code is compiled and incorporated into your Zig project.\n\nIn summary, Zig have great interoperability with C. If you want to call any C code from Zig,\nyou have to perform the following steps:\n\n- import a C header file into your Zig code.\n- link your Zig code with the C library.\n\n\n### Strategies to import C header files {#sec-strategy-c}\n\nUsing C code in Zig always involves performing the two steps cited above. However, when\nwe talk specifically about the first step listed above, there are currently two\ndifferent ways to perform this first step, which are:\n\n- translating the C header file into Zig code, through the `zig translate-c` command, and then, import and use the translated Zig code.\n- importing the C header file directly into your Zig module through the `@cImport()` built-in function.\n\nIf you are not familiar with `translate-c`, this is a subcommand inside the `zig` compiler that takes C files\nas input, and outputs the Zig representation of the C code present in these C files.\nIn other words, this subcommand works like a transpiler. It takes C code, and translates it into\nthe equivalent Zig code.\n\nI think it would be ok to interpret `translate-c` as a tool to generate Zig bindings\nto C code, similarly to the `rust-bindgen`[^bindgen] tool, which generates Rust FFI bindings to C code.\nBut that would not be a precise interpretation of `translate-c`. The idea behind this tool is\nto really translate the C code into Zig code.\n\n[^bindgen]: <https://github.com/rust-lang/rust-bindgen>\n\nNow, on a surface level, `@cImport()` versus `translate-c` might seem like\ntwo completely different strategies. But in fact, they are effectively the exact same strategy.\nBecause, under the hood, the `@cImport()` built-in function is just a shortcut to `translate-c`.\nBoth tools use the same \"C to Zig\" translation functionality. So when you use `@cImport()`,\nyou are essentially asking the `zig` compiler to translate the C header file into Zig code, then,\nto import this Zig code into your current Zig module.\n\nAt the present moment, there is an accepted proposal at the Zig project, to move `@cImport()`\nto the Zig build system[^cimport-issue]. If this proposal is completed, then, the \"use `@cImport()`\"\nstrategy would be transformed into \"call a translate C function in your Zig build script\".\nSo, the step of translating the C code into Zig code would be moved to\nthe build script of your Zig project, and you would only need to import the translated Zig code into\nyour Zig module to start calling C code from Zig.\n\n[^cimport-issue]: <https://github.com/ziglang/zig/issues/20630>\n\nIf you think about this proposal for a minute, you will understand that this is actually\na small change. I mean, the logic is the same, and the steps are still essentially the same.\nThe only difference is that one of the steps will be moved to the build script of your Zig project.\n\n\n\n### Linking Zig code with a C library {#sec-linking-c}\n\nRegardless of which of the two strategies from the previous section you choose,\nif you want to call C code from Zig, you must link your Zig code\nwith the C library that contains the C code that you want to call.\n\nIn other words, everytime you use some C code in your Zig code, **you introduce a dependency in your build process**.\nThis should come as no surprise to anyone that have any experience with C and C++.\nBecause this is no different in C. Everytime you use a C library in your C code, you also\nhave to build and link your C code with this C library that you are using.\n\nWhen we use a C library in our Zig code, the `zig` compiler needs to access the definition of the C functions that\nare being called in your Zig code. The C header file of this library provides the\ndeclarations of these C functions, but not their definitions. So, in order to access these definitions,\nthe `zig` compiler needs to build your Zig code and link it with the C library during the build process.\n\nAs we discussed across the @sec-build-system, there are different strategies to link something with a library.\nThis might involve building the C library first, and then, linking it with the Zig code. Or,\nit could also involve just the linking step, if this C library is already built and\ninstalled in your system. Anyway, if you have doubts about this, comeback to @sec-build-system.\n\n\n\n## Importing C header files {#sec-import-c-header}\n\nAt @sec-strategy-c, we have described that, currently, there are two different paths that\nyou can take to import a C header file into your Zig modules, `translate-c` or `@cImport()`.\nThis section describes each strategy separately in more details.\n\n### Strategy 1: using `translate-c`\n\nWhen we choose this strategy, we first need to use the `translate-c` tool to translate\nthe C header files that we want to use into Zig code. For example, suppose we wanted to\nuse the `fopen()` C function from the `stdio.h` C header file. We can translate the\n`stdio.h` C header file through the bash command below:\n\n```bash\nzig translate-c /usr/include/stdio.h \\\n    -lc -I/usr/include \\\n    -D_NO_CRT_STDIO_INLINE=1 > c.zig \\\n```\n\nNotice that, in this bash command, we are passing the necessary compiler flags (`-D` to define macros,\n`-l` to link libraries, `-I` to add an \"include path\") to compile and use the `stdio.h` header file.\nAlso notice that we are saving the results of the translation process inside a Zig module called `c.zig`.\n\nTherefore, after running this command, all we have to do is to import this `c.zig` module, and start\ncalling the C functions that you want to call from it. The example below demonstrates that.\nIs important to remember what we've discussed at @sec-linking-c. In order to compile this\nexample you have to link this code with `libc`, by passing the flag `-lc` to the `zig` compiler.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @import(\"c.zig\");\npub fn main() !void {\n    const x: f32 = 1772.94122;\n    _ = c.printf(\"%.3f\\n\", x);\n}\n```\n:::\n\n\n\n\n```\n1772.941\n```\n\n\n### Strategy 2: using `@cImport()`\n\nTo import a C header file into our Zig code, we can use the built-in functions `@cInclude()` and `@cImport()`.\nInside the `@cImport()` function, we open a block (with a pair of curly braces). Inside this block\nwe can (if we need to) include multiple `@cDefine()` calls to define C macros when including this specific C header file.\nBut for the most part, you will probably need to use just a single call inside this block,\nwhich is a call to `@cInclude()`.\n\nThis `@cInclude()` function is equivalent to the `#include` statement in C.\nYou provide the name of the C header that you want to include as input to this `@cInclude()` function,\nthen, in conjunction with `@cImport()`, it will perform the necessary steps\nto include this C header file into your Zig code.\n\nYou should bind the result of `@cImport()` to a constant object, pretty much like you would do with\n`@import()`. You just assign the result to a constant object in your\nZig code, and, as consequence, all C functions, C structs, C macros, etc. that are defined inside the\nC header files will be available through this constant object.\n\nLook at the code example below, where we are importing the Standard I/O C Library (`stdio.h`),\nand calling the `printf()`[^printf] C function. Notice that we have also used in this example the C function `powf()`[^powf],\nwhich comes from the C Math Library (`math.h`).\nIn order to compile this example, you have to link this Zig code with both\nthe C Standard Library and the C Math Library, by passing the flags `-lc` and `-lm`\nto the `zig` compiler.\n\n[^printf]: <https://cplusplus.com/reference/cstdio/printf/>\n[^powf]: <https://en.cppreference.com/w/c/numeric/math/pow>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n    @cInclude(\"math.h\");\n});\n\npub fn main() !void {\n    const x: f32 = 15.2;\n    const y = c.powf(x, @as(f32, 2.6));\n    _ = c.printf(\"%.3f\\n\", y);\n}\n```\n:::\n\n\n\n\n```\n1182.478\n```\n\n\n## About passing Zig values to C functions {#sec-zig-obj-to-c}\n\nZig objects have some intrinsic differences between their C equivalents.\nProbably the most noticeable one is the difference between C strings and Zig strings,\nwhich I described at @sec-zig-strings.\nZig strings are objects that contains both an array of arbitrary bytes and a length value.\nOn the other hand, a C string is usually just a pointer to a null-terminated array of arbitrary bytes.\n\nBecause of these intrinsic differences, in some specific cases, you cannot pass Zig objects directly\nas inputs to C functions before you convert them into C compatible values. However, in some other cases,\nyou are allowed to pass Zig objects and Zig literal values directly as inputs to C functions,\nand everything will work just fine, because the `zig` compiler will handle everything for you.\n\nSo we have two different scenarios being described here. Let's call them \"auto-conversion\" and \"need-conversion\".\nThe \"auto-conversion\" scenario is when the `zig` compiler handles everything for you, and automatically convert your\nZig objects/values into C compatible values. In contrast,\nthe \"need-conversion\" scenario is when you, the programmer, have the responsibility of converting\nthat Zig object into a C compatible value, before passing it to C code.\n\nThere is also a third scenario that is not being described here, which is when you create a C object, or, a C struct, or\na C compatible value in your Zig code, and you pass this C object/value as input to a C function in your Zig code.\nThis scenario will be described later at @sec-c-inputs. In this section, we are focused on the scenarios where\nwe are passing Zig objects/values to C code, instead of C objects/values being passed to C code.\n\n\n### The \"auto-conversion\" scenario\n\nAn \"auto-conversion\" scenario is when the `zig` compiler automatically converts our Zig objects into\nC compatible values for us. This specific scenario happens mostly in two instances:\n\n- with string literal values;\n- with any of the primitive data types that were introduced at @sec-primitive-data-types.\n\nWhen we think about the second instance described above, the `zig` compiler does automatically\nconvert any of the primitive data types into their C equivalents, because the compiler knows how\nto properly convert a `i16` into a `signed short`, or, a `u8` into a `unsigned char`, etc.\nNow, when we think about string literal values, they can be automatically\nconverted into C strings as well, especially because the `zig` compiler does not forces\na specific Zig data type into a string literal at first glance, unless you store this\nstring literal into a Zig object, and explicitly annotate the data type of this object.\n\nThus, with string literal values, the `zig` compiler have more freedom to infer which is the appropriate data type\nto be used in each situation. You could say that the string literal value \"inherits its data type\" depending on the context that\nit is used. Most of the times, this data type is going to be the type that we commonly associate with Zig strings (`[]const u8`).\nBut it might be a different type depending on the situation. When the `zig` compiler detects that you are providing\na string literal value as input to some C function, the compiler automatically interprets this string\nliteral as a C string value.\n\nAs an example, look at the code exposed below. Here we are using\nthe `fopen()` C function to simply open and close a file. If you do not know how this `fopen()`\nfunction works in C, it takes two C strings as input. But in this code example below, we are passing some\nstring literals written in our Zig code directly as inputs to this `fopen()` C function.\n\nIn other words, we are not doing any conversion from a Zig string to a C string.\nWe are just passing the Zig string literals directly as inputs to the C function. And it works just fine!\nBecause the compiler interprets the string `\"foo.txt\"` as a C string given the current context.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n});\n\npub fn main() !void {\n    const file = c.fopen(\"foo.txt\", \"rb\");\n    if (file == null) {\n        @panic(\"Could not open file!\");\n    }\n    if (c.fclose(file) != 0) {\n        return error.CouldNotCloseFileDescriptor;\n    }\n}\n```\n:::\n\n\n\n\nLet's make some experiments, by writing the same code in different manners, and we\nsee how this affects the program. As a starting point, let's store the `\"foo.txt\"` string inside\na Zig object, like the `path` object below, and then, we pass this Zig object as input to the `fopen()` C function.\n\nIf we do this, the program still compiles and runs successfully. Notice that I have omitted most of the code in this example below.\nThis is just for brevity reasons, because the remainder of the program is still the same.\nThe only difference between this example and the previous one is just these two lines exposed below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\n\nNow, what happens if you give an explicit data type to the `path` object? Well, if I force\nthe `zig` compiler to interpret this `path` object as a Zig string object,\nby annotating the `path` object with the data type `[]const u8`, then, I actually get a compile error\nas demonstrated below. We get this compile error because now I'm forcing the `zig` compiler\nto interpret `path` as a Zig string object.\n\nAccording to the error message, the `fopen()` C function was expecting to receive an\ninput value of type `[*c]const u8` (C string) instead of a value of type `[]const u8` (Zig string).\nIn more details, the type `[*c]const u8` is actually the Zig type representation of a C string.\nThe `[*c]` portion of this type identifies a C pointer. So, this Zig type essentially means: a C pointer to an array (`[*c]`) of\nconstant bytes (`const u8`).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\n\n```\nt.zig:2:7 error: expected type '[*c]const u8', found '[]const u8':\n    const file = c.fopen(path, \"rb\");\n                         ^~~~\n```\n\nTherefore, when we talk exclusively about string literal values, as long as you don't give an\nexplicit data type to these string literal values, the `zig` compiler should be capable of automatically\nconverting them into C strings as needed.\n\nBut what about using one of the primitive data types that were introduced at @sec-primitive-data-types?\nLet's take code exposed below as an example of that. Here, we are giving some float literal values as input\nto the C function `powf()`. Notice that this code example compiles and runs successfully.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst cmath = @cImport({\n    @cInclude(\"math.h\");\n});\n\npub fn main() !void {\n    const y = cmath.powf(15.68, 2.32);\n    try stdout.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n\n\n```\n593.2023\n```\n\nOnce again, because the `zig` compiler does not associate a specific data type with the literal values\n`15.68` and `2.32` at first glance, the compiler can automatically convert these values\ninto their C `float` (or `double`) equivalents, before it passes to the `powf()` C function.\nNow, even if I give an explicit Zig data type to these literal values, by storing them into a Zig object,\nand explicit annotating the type of these objects, the code still compiles and runs successfully.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const x: f32 = 15.68;\n    const y = cmath.powf(x, 2.32);\n    // The remainder of the program\n```\n:::\n\n\n\n\n```\n593.2023\n```\n\n\n\n### The \"need-conversion\" scenario\n\nA \"need-conversion\" scenario is when we need to manually convert our Zig objects into C compatible values\nbefore passing them as input to C functions. You will fall in this scenario, when passing Zig string objects\nto C functions.\n\nWe have already seen this specific circumstance in the last `fopen()` example,\nwhich is reproduced below. You can see in this example, that we have given an explicit Zig data type\n(`[]const u8`) to our `path` object, and, as a consequence of that, we have forced the `zig` compiler\nto see this `path` object, as a Zig string object. Therefore, we need now to manually convert\nthis `path` object into a C string before we pass it to `fopen()`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\n\n```\nt.zig:10:26: error: expected type '[*c]const u8', found '[]const u8'\n    const file = c.fopen(path, \"rb\");\n                         ^~~~\n```\n\n\nThere are different ways to convert a Zig string object into a C string.\nOne way to solve this problem is to provide the pointer to the underlying array\nof bytes, instead of providing the Zig object directly as input.\nYou can access this pointer by using the `ptr` property of the Zig string object.\n\nThe code example below demonstrates this strategy. Notice that, by giving the\npointer to the underlying array in `path` through the `ptr` property, we get no compile errors as result\nwhile using the `fopen()` C function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path.ptr, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\n\nThis strategy works because this pointer to the underlying array found in the `ptr` property,\nis semantically identical to a C pointer to an array of bytes, i.e. a C object of type `*unsigned char`.\nThis is why this option also solves the problem of converting the Zig string into a C string.\n\nAnother option is to explicitly convert the Zig string object into a C pointer by using the\nbuilt-in function `@ptrCast()`. With this function we can convert\nan object of type `[]const u8` into an object of type `[*c]const u8`.\nAs I described at the previous section, the `[*c]` portion of the type\nmeans that it is a C pointer. This strategy is not-recommended. But it is\nuseful to demonstrate the use of `@ptrCast()`.\n\nYou may recall of `@as()` and `@ptrCast()` from @sec-type-cast. Just as a recap,\nthe `@as()` built-in function is used to explicitly convert (or cast) a Zig value\nfrom a type \"x\" into a value of type \"y\". But in our case here, we are converting\na pointer object. Everytime a pointer is involved in some \"type casting operation\" in Zig,\nthe `@ptrCast()` function is involved.\n\nIn the example below, we are using this function to cast our `path` object\ninto a C pointer to an array of bytes. Then, we pass this C pointer as input\nto the `fopen()` function. Notice that this code example compiles successfully\nwith no errors.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path: []const u8 = \"foo.txt\";\n    const c_path: [*c]const u8 = @ptrCast(path);\n    const file = c.fopen(c_path, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\n\n\n\n## Creating C objects in Zig {#sec-c-inputs}\n\nCreating C objects, or, in other words, creating instances of C structs in your Zig code\nis actually something quite easy to do. You first need to import the C header file (like I described at @sec-import-c-header) that defines\nthe C struct that you are trying to instantiate in your Zig code. After that, you can just\ncreate a new object in your Zig code, and annotate it with the data type of the C struct.\n\nFor example, suppose we have a C header file called `user.h`, and that this header file is declaring a new struct named `User`.\nThis C header file is exposed below:\n\n```c\n#include <stdint.h>\n\ntypedef struct {\n    uint64_t id;\n    char* name;\n} User;\n```\n\nThis `User` C struct have two distinct fields, or two struct members, named `id` and `name`.\nThe field `id` is an unsigned 64-bit integer value, while the field `name` is just a standard C string.\nNow, suppose that I want to create an instance of this `User` struct in my Zig code.\nI can do that by importing this `user.h` header file into my Zig code, and creating\na new object with type `User`. These steps are reproduced in the code example below.\n\nNotice that I have used the keyword `undefined` in this example. This allows me to\ncreate the `new_user` object without the need to provide an initial value to the object.\nAs consequence, the underlying memory associated with this `new_user` object is uninitialized,\ni.e. the memory is currently populated with \"garbage\" values.\nThus, this expression have the exact same effect of the expression `User new_user;` in C,\nwhich means \"declare a new object named `new_user` of type `User`\".\n\nIs our responsibility to properly initialize this memory associated with this `new_user` object,\nby assigning valid values to the members (or the fields) of the C struct. In the example below,\nI'm assigning the integer 1 to the member `id`. I am also saving the string `\"pedropark99\"` into the member `name`.\nNotice in this example that I manually add the null character (zero byte) to the end of the allocated array\nfor this string. This null character marks the end of the array in C.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst c = @cImport({\n    @cInclude(\"user.h\");\n});\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n\n    var new_user: c.User = undefined;\n    new_user.id = 1;\n    var user_name = try allocator.alloc(u8, 12);\n    defer allocator.free(user_name);\n    @memcpy(user_name[0..(user_name.len - 1)], \"pedropark99\");\n    user_name[user_name.len - 1] = 0;\n    new_user.name = user_name.ptr;\n}\n```\n:::\n\n\n\n\nSo, in this example above, we are manually initializing each field of the C struct.\nWe could say that, in this instance, we are \"manually instantiating\nthe C struct object\". However, when we use C libraries in our Zig code, we rarely need\nto manually instantiate the C structs like that. Only because C libraries\nusually provide a \"constructor function\" in their public APIs. As consequence, we normally rely on\nthese constructor functions to properly initialize the C structs, and\nthe struct fields for us.\n\nFor example, consider the Harfbuzz C library. This a text shaping C library,\nand it works around a \"buffer object\", or, more specifically, an instance of\nthe C struct `hb_buffer_t`. Therefore, we need to create an instance of\nthis C struct if we want to use this C library. Luckily, this library offers\nthe function `hb_buffer_create()`, which we can use to create such object.\nSo the Zig code necessary to create such object would probably look something like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cInclude(\"hb.h\");\n});\nvar buf: c.hb_buffer_t = c.hb_buffer_create();\n// Do stuff with the \"buffer object\"\n```\n:::\n\n\n\n\nTherefore, we do not need to manually create an instance of the C struct\n`hb_buffer_t` here, and manually assign valid values to each field in this C struct.\nBecause the constructor function `hb_buffer_create()` is doing this heavy job for us.\n\nSince this `buf` object, and also, the `new_user` object from previous examples, are instances of C structs, these\nobjects are by themselves C compatible values. They are C objects defined in our Zig code. As consequence,\nyou can freely pass these objects as input to any C function that expects to receive this type\nof C struct as input. You do not need to use any special syntax, or, to convert them in\nany special manner to use them in C code. This is how we create and use C objects in our Zig code.\n\n\n\n## Passing C structs across Zig functions {#sec-pass-c-structs}\n\nNow that we have learned how to create/declare C objects in our Zig code, we\nneed to learn how to pass these C objects as inputs to Zig functions.\nAs I described at @sec-c-inputs, we can freely pass these C objects as inputs to C code\nthat we call from our Zig code. But what about passing these C objects to Zig functions?\n\nIn essence, this specific case requires one small adjustment in the Zig function declaration.\nAll you need to do, is to make sure that you pass your C object *by reference* to the function,\ninstead of passing it *by value*. To do that, you have to annotate the data type of the function argument\nthat is receiving this C object as \"a pointer to the C struct\", instead of annotating it as \"an instance of the C struct\".\n\nLet's consider the C struct `User` from the `user.h` C header file that we have used at @sec-c-inputs.\nNow, consider that we want to create a Zig function that sets the value of the `id` field\nin this C struct, like the `set_user_id()` function declared below.\nNotice that the `user` argument in this function is annotated as a pointer (`*`) to a `c.User` object.\n\nTherefore, all you have to do when passing C objects to Zig functions, is to add `*` to the\ndata type of the function argument that is receiving the C object. This will make sure that\nthe C object is passed *by reference* to the function.\n\nBecause we have transformed the function argument into a pointer,\neverytime that you have to access the value pointed by this input pointer inside the function body, for whatever reason (e.g. you want\nto read, update, or delete this value), you have to dereference the pointer with the `.*` syntax that we\nlearned from @sec-pointer. Notice that the `set_user_id()` function is using this syntax to alter\nthe value in the `id` field of the `User` struct pointed by the input pointer.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst c = @cImport({\n    @cInclude(\"user.h\");\n});\nfn set_user_id(id: u64, user: *c.User) void {\n    user.*.id = id;\n}\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n\n    var new_user: c.User = undefined;\n    new_user.id = 1;\n    var user_name = try allocator.alloc(u8, 12);\n    defer allocator.free(user_name);\n    @memcpy(user_name[0..(user_name.len - 1)], \"pedropark99\");\n    user_name[user_name.len - 1] = 0;\n    new_user.name = user_name.ptr;\n\n    set_user_id(25, &new_user);\n    try stdout.print(\"New ID: {any}\\n\", .{new_user.id});\n}\n```\n:::\n\n\n\n\n```\nNew ID: 25\n```\n\n",
-    "supporting": [
-      "14-zig-c-interop_files"
-    ],
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/index/execute-results/html.json b/_freeze/index/execute-results/html.json
index 7a43f8dd..0d36ad04 100644
--- a/_freeze/index/execute-results/html.json
+++ b/_freeze/index/execute-results/html.json
@@ -2,7 +2,7 @@
   "hash": "0d9977ad882089aad1460aa86ce0e48e",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy an eBook or a physical copy\nof the book on Amazon:\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e. it is open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria have a bachelor degree in Economics from Federal University of Ouro Preto - Brazil.\nCurrently, he is a Data Platform Engineer at [Blip](https://www.blip.ai/en/)[^blip], and\nan Associate Developer for Apache Spark 3.0 certified by Databricks.\n\n[^blip]: <https://www.blip.ai/en/>\n\n\nThe author have more than 4 years of experience in the data industry. Developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nbrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer that loves to\nlearn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2024 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n\n- System version: Linux, 6.8.0-49-generic, NA, x86_64.\n- Zig version: 0.14.0-dev.2051+b1361f237.\n- Quarto version: 1.5.57.\n\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang)\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy an eBook or a physical copy\nof the book on Amazon:\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e. it is open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria have a bachelor degree in Economics from Federal University of Ouro Preto - Brazil.\nCurrently, he is a Data Platform Engineer at [Blip](https://www.blip.ai/en/)[^blip], and\nan Associate Developer for Apache Spark 3.0 certified by Databricks.\n\n[^blip]: <https://www.blip.ai/en/>\n\n\nThe author have more than 4 years of experience in the data industry. Developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nbrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer that loves to\nlearn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2024 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n\n- System version: Linux, 6.8.0-49-generic, NA, x86_64.\n- Zig version: 0.14.0-dev.2371+c013f45ad.\n- Quarto version: 1.5.57.\n\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang)\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
diff --git a/docs/Chapters/01-memory.html b/docs/Chapters/01-memory.html
index 23a683fc..0e748f6f 100644
--- a/docs/Chapters/01-memory.html
+++ b/docs/Chapters/01-memory.html
@@ -367,14 +367,16 @@ <h3 data-number="3.1.1" class="anchored" data-anchor-id="sec-compile-time"><span
 <p>In contrast, if the type of this struct that you are declaring, includes a data member that is an array, but this array has a known fixed size, like <code>[60]u8</code> (which declares an array of 60 <code>u8</code> values), then, this type, or, this struct that you are declaring, becomes a type with a known fixed size at compile-time. And because of that, in this case, the <code>zig</code> compiler does not need to know at compile-time the exact value of any object of this type. Since the compiler can find the necessary size to store this object by looking at the size of its type.</p>
 <p>Let’s look at an example. In the source code below, we have two constant objects (<code>name</code> and <code>array</code>) declared. Because the values of these particular objects are written down, in the source code itself (<code>"Pedro"</code> and the number sequence from 1 to 4), the <code>zig</code> compiler can easily discover the values of these constant objects (<code>name</code> and <code>array</code>) during the compilation process. This is what “known at compile time” means. It refers to any object that you have in your Zig source code whose value can be identified at compile time.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb1"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> name = <span class="st">"Pedro"</span>;</span>
-<span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> array = [_]<span class="dt">u8</span><span class="op">{</span><span class="dv">1</span>, <span class="dv">2</span>, <span class="dv">3</span>, <span class="dv">4</span><span class="op">}</span>;</span>
-<span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a>_ = name; _ = array;</span>
-<span id="cb1-4"><a href="#cb1-4" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> input_length(input: []<span class="kw">const</span> <span class="dt">u8</span>) <span class="dt">usize</span> <span class="op">{</span></span>
-<span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> n = input.len;</span>
-<span id="cb1-7"><a href="#cb1-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> n;</span>
-<span id="cb1-8"><a href="#cb1-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb1"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> input_length(input: []<span class="kw">const</span> <span class="dt">u8</span>) <span class="dt">usize</span> <span class="op">{</span></span>
+<span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> n = input.len;</span>
+<span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> n;</span>
+<span id="cb1-4"><a href="#cb1-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
+<span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb1-7"><a href="#cb1-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> name = <span class="st">"Pedro"</span>;</span>
+<span id="cb1-8"><a href="#cb1-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> array = [_]<span class="dt">u8</span><span class="op">{</span><span class="dv">1</span>, <span class="dv">2</span>, <span class="dv">3</span>, <span class="dv">4</span><span class="op">}</span>;</span>
+<span id="cb1-9"><a href="#cb1-9" aria-hidden="true" tabindex="-1"></a>    _ = name; _ = array;</span>
+<span id="cb1-10"><a href="#cb1-10" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>The other side of the spectrum are objects whose values are not known at compile time. Function arguments are a classic example of this. Because the value of each function argument depends on the value that you assign to this particular argument, when you call the function.</p>
 <p>For example, the function <code>input_length()</code> contains an argument named <code>input</code>, which is an array of constant <code>u8</code> integers (<code>[]const u8</code>). It is impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length of this particular argument. Because it is an array that do not have a fixed size specified explicitly in the argument type annotation.</p>
@@ -401,13 +403,15 @@ <h3 data-number="3.1.4" class="anchored" data-anchor-id="sec-stack"><span class=
 <p>Every time you make a function call in Zig, an amount of space in the stack is reserved for this particular function call <span class="citation" data-cites="jenny2022 zigdocs">(<a href="../references.html#ref-jenny2022" role="doc-biblioref">Chen and Guo 2022</a>; <a href="../references.html#ref-zigdocs" role="doc-biblioref">Zig Software Foundation 2024</a>)</span>. The value of each function argument given to the function in this function call is stored in this stack space. Also, every local object that you declare inside the function scope is usually stored in this same stack space.</p>
 <p>Looking at the example below, the object <code>result</code> is a local object declared inside the scope of the <code>add()</code> function. Because of that, this object is stored inside the stack space reserved for the <code>add()</code> function. The <code>r</code> object (which is declared outside of the <code>add()</code> function scope) is also stored in the stack. But since it is declared in the “outer” scope, this object is stored in the stack space that belongs to this outer scope.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb2"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> r = add(<span class="dv">5</span>, <span class="dv">27</span>);</span>
-<span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a>_ = r;</span>
-<span id="cb2-3"><a href="#cb2-3" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb2-4"><a href="#cb2-4" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> add(x: <span class="dt">u8</span>, y: <span class="dt">u8</span>) <span class="dt">u8</span> <span class="op">{</span></span>
-<span id="cb2-5"><a href="#cb2-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> result = x + y;</span>
-<span id="cb2-6"><a href="#cb2-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> result;</span>
-<span id="cb2-7"><a href="#cb2-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb2"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> add(x: <span class="dt">u8</span>, y: <span class="dt">u8</span>) <span class="dt">u8</span> <span class="op">{</span></span>
+<span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> result = x + y;</span>
+<span id="cb2-3"><a href="#cb2-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> result;</span>
+<span id="cb2-4"><a href="#cb2-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
+<span id="cb2-5"><a href="#cb2-5" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb2-6"><a href="#cb2-6" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb2-7"><a href="#cb2-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> r = add(<span class="dv">5</span>, <span class="dv">27</span>);</span>
+<span id="cb2-8"><a href="#cb2-8" aria-hidden="true" tabindex="-1"></a>    _ = r;</span>
+<span id="cb2-9"><a href="#cb2-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>So, any object that you declare inside the scope of a function is always stored inside the space that was reserved for that particular function in the stack memory. This also counts for any object declared inside the scope of your <code>main()</code> function for example. As you would expect, in this case, they are stored inside the stack space reserved for the <code>main()</code> function.</p>
 <p>One very important detail about the stack memory is that <strong>it frees itself automatically</strong>. This is very important, remember that. When objects are stored in the stack memory, you don’t have the work (or the responsibility) of freeing/destroying these objects. Because they will be automatically destroyed once the stack space is freed at the end of the function scope.</p>
@@ -444,16 +448,16 @@ <h3 data-number="3.1.4" class="anchored" data-anchor-id="sec-stack"><span class=
 <p>So, using again the <code>add()</code> function as an example, if you rewrite this function so that it returns a pointer to the local object <code>result</code>, the <code>zig</code> compiler will actually compile your program, with no warnings or errors. At first glance, it looks that this is good code that works as expected. But this is a lie!</p>
 <p>If you try to take a look at the value inside of the <code>r</code> object, or, if you try to use this <code>r</code> object in another expression or function call, then, you would have undefined behaviour, and major bugs in your program <span class="citation" data-cites="zigdocs">(<a href="../references.html#ref-zigdocs" role="doc-biblioref">Zig Software Foundation 2024</a>, see “Lifetime and Ownership”<a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a> and “Undefined Behaviour”<a href="#fn4" class="footnote-ref" id="fnref4" role="doc-noteref"><sup>4</sup></a> sections)</span>.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb4"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="co">// This code compiles successfully. But it has</span></span>
-<span id="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a><span class="co">// undefined behaviour. Never do this!!!</span></span>
-<span id="cb4-3"><a href="#cb4-3" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb4-4"><a href="#cb4-4" aria-hidden="true" tabindex="-1"></a><span class="co">// The `r` object is undefined!</span></span>
-<span id="cb4-5"><a href="#cb4-5" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> r = add(<span class="dv">5</span>, <span class="dv">27</span>);</span>
-<span id="cb4-6"><a href="#cb4-6" aria-hidden="true" tabindex="-1"></a>_ = r;</span>
-<span id="cb4-7"><a href="#cb4-7" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb4-8"><a href="#cb4-8" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> add(x: <span class="dt">u8</span>, y: <span class="dt">u8</span>) *<span class="kw">const</span> <span class="dt">u8</span> <span class="op">{</span></span>
-<span id="cb4-9"><a href="#cb4-9" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> result = x + y;</span>
-<span id="cb4-10"><a href="#cb4-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> &amp;result;</span>
+<div class="sourceCode cell-code" id="cb4"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> add(x: <span class="dt">u8</span>, y: <span class="dt">u8</span>) *<span class="kw">const</span> <span class="dt">u8</span> <span class="op">{</span></span>
+<span id="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> result = x + y;</span>
+<span id="cb4-3"><a href="#cb4-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> &amp;result;</span>
+<span id="cb4-4"><a href="#cb4-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
+<span id="cb4-5"><a href="#cb4-5" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb4-6"><a href="#cb4-6" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb4-7"><a href="#cb4-7" aria-hidden="true" tabindex="-1"></a>    <span class="co">// This code compiles successfully. But it has</span></span>
+<span id="cb4-8"><a href="#cb4-8" aria-hidden="true" tabindex="-1"></a>    <span class="co">// undefined behaviour. Never do this!!!</span></span>
+<span id="cb4-9"><a href="#cb4-9" aria-hidden="true" tabindex="-1"></a>    <span class="co">// The `r` object is undefined!</span></span>
+<span id="cb4-10"><a href="#cb4-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> r = add(<span class="dv">5</span>, <span class="dv">27</span>); _ = r;</span>
 <span id="cb4-11"><a href="#cb4-11" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>This “invalid pointer to stack variable” problem is very known across many programming language communities. If you try to do the same thing, for example, in a C or C++ program (i.e.&nbsp;returning an address to a local object stored in the stack), you would also get undefined behaviour in the program.</p>
@@ -642,9 +646,9 @@ <h3 data-number="3.3.7" class="anchored" data-anchor-id="sec-arena-allocator"><s
 <span id="cb12-3"><a href="#cb12-3" aria-hidden="true" tabindex="-1"></a><span class="kw">defer</span> aa.deinit();</span>
 <span id="cb12-4"><a href="#cb12-4" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> allocator = aa.allocator();</span>
 <span id="cb12-5"><a href="#cb12-5" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb12-6"><a href="#cb12-6" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> in1 = allocator.alloc(<span class="dt">u8</span>, <span class="dv">5</span>);</span>
-<span id="cb12-7"><a href="#cb12-7" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> in2 = allocator.alloc(<span class="dt">u8</span>, <span class="dv">10</span>);</span>
-<span id="cb12-8"><a href="#cb12-8" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> in3 = allocator.alloc(<span class="dt">u8</span>, <span class="dv">15</span>);</span>
+<span id="cb12-6"><a href="#cb12-6" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> in1 = <span class="kw">try</span> allocator.alloc(<span class="dt">u8</span>, <span class="dv">5</span>);</span>
+<span id="cb12-7"><a href="#cb12-7" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> in2 = <span class="kw">try</span> allocator.alloc(<span class="dt">u8</span>, <span class="dv">10</span>);</span>
+<span id="cb12-8"><a href="#cb12-8" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> in3 = <span class="kw">try</span> allocator.alloc(<span class="dt">u8</span>, <span class="dv">15</span>);</span>
 <span id="cb12-9"><a href="#cb12-9" aria-hidden="true" tabindex="-1"></a>_ = in1; _ = in2; _ = in3;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
diff --git a/docs/Chapters/01-zig-weird.html b/docs/Chapters/01-zig-weird.html
index 7b4a3931..ac94c65e 100644
--- a/docs/Chapters/01-zig-weird.html
+++ b/docs/Chapters/01-zig-weird.html
@@ -906,6 +906,10 @@ <h3 data-number="1.8.2" class="anchored" data-anchor-id="a-better-look-at-the-ob
 <span id="cb57-15"><a href="#cb57-15" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Type 4: {}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="bu">@TypeOf</span>(string_obj)<span class="op">}</span></span>
 <span id="cb57-16"><a href="#cb57-16" aria-hidden="true" tabindex="-1"></a>    );</span>
 <span id="cb57-17"><a href="#cb57-17" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="cell-output cell-output-stdout">
+<pre><code>Type 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons
+  st [4]i32Type 4: []const u8</code></pre>
+</div>
 </div>
 <pre><code>Type 1: [4]i32
 Type 2: *const [16:0]u8
@@ -918,17 +922,17 @@ <h3 data-number="1.8.3" class="anchored" data-anchor-id="byte-vs-unicode-points"
 <p>The encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in the string. For example, the character “H” is stored in UTF-8 as the decimal number 72. This means that the number 72 is the unicode point for the character “H”. Each possible character that can appear in a UTF-8 encoded string have its own unicode point.</p>
 <p>For example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point) 570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which is 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why, the unicode point 570 is actually stored inside the computer’s memory as the bytes <code>C8 BA</code>.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb59"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb59-1"><a href="#cb59-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb59-2"><a href="#cb59-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
-<span id="cb59-3"><a href="#cb59-3" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb59-4"><a href="#cb59-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> string_object = <span class="st">"Ⱥ"</span>;</span>
-<span id="cb59-5"><a href="#cb59-5" aria-hidden="true" tabindex="-1"></a>    _ = <span class="kw">try</span> stdout.write(</span>
-<span id="cb59-6"><a href="#cb59-6" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Bytes that represents the string object: "</span></span>
-<span id="cb59-7"><a href="#cb59-7" aria-hidden="true" tabindex="-1"></a>    );</span>
-<span id="cb59-8"><a href="#cb59-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">for</span> (string_object) |char| <span class="op">{</span></span>
-<span id="cb59-9"><a href="#cb59-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">try</span> stdout.print(<span class="st">"{X} "</span>, .<span class="op">{</span>char<span class="op">}</span>);</span>
-<span id="cb59-10"><a href="#cb59-10" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb59-11"><a href="#cb59-11" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb60"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb60-1"><a href="#cb60-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb60-2"><a href="#cb60-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
+<span id="cb60-3"><a href="#cb60-3" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb60-4"><a href="#cb60-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> string_object = <span class="st">"Ⱥ"</span>;</span>
+<span id="cb60-5"><a href="#cb60-5" aria-hidden="true" tabindex="-1"></a>    _ = <span class="kw">try</span> stdout.write(</span>
+<span id="cb60-6"><a href="#cb60-6" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Bytes that represents the string object: "</span></span>
+<span id="cb60-7"><a href="#cb60-7" aria-hidden="true" tabindex="-1"></a>    );</span>
+<span id="cb60-8"><a href="#cb60-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">for</span> (string_object) |char| <span class="op">{</span></span>
+<span id="cb60-9"><a href="#cb60-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">try</span> stdout.print(<span class="st">"{X} "</span>, .<span class="op">{</span>char<span class="op">}</span>);</span>
+<span id="cb60-10"><a href="#cb60-10" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb60-11"><a href="#cb60-11" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>Bytes that represents the string object: C8 BA </code></pre>
 </div>
@@ -940,19 +944,19 @@ <h3 data-number="1.8.3" class="anchored" data-anchor-id="byte-vs-unicode-points"
 <p>If you need to iterate through the characters of a string, instead of its bytes, then, you can use the <code>std.unicode.Utf8View</code> struct to create an iterator that iterates through the unicode points of your string.</p>
 <p>In the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in this string is represented by three bytes. But the for loop iterates four times, one iteration for each character/unicode point in this string:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb61"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb61-1"><a href="#cb61-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb61-2"><a href="#cb61-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
-<span id="cb61-3"><a href="#cb61-3" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb61-4"><a href="#cb61-4" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb61-5"><a href="#cb61-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> utf8 = <span class="kw">try</span> std.unicode.Utf8View.init(<span class="st">"アメリカ"</span>);</span>
-<span id="cb61-6"><a href="#cb61-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> iterator = utf8.iterator();</span>
-<span id="cb61-7"><a href="#cb61-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">while</span> (iterator.nextCodepointSlice()) |codepoint| <span class="op">{</span></span>
-<span id="cb61-8"><a href="#cb61-8" aria-hidden="true" tabindex="-1"></a>        <span class="kw">try</span> stdout.print(</span>
-<span id="cb61-9"><a href="#cb61-9" aria-hidden="true" tabindex="-1"></a>            <span class="st">"got codepoint {}</span><span class="sc">\n</span><span class="st">"</span>,</span>
-<span id="cb61-10"><a href="#cb61-10" aria-hidden="true" tabindex="-1"></a>            .<span class="op">{</span>std.fmt.fmtSliceHexUpper(codepoint)<span class="op">}</span>,</span>
-<span id="cb61-11"><a href="#cb61-11" aria-hidden="true" tabindex="-1"></a>        );</span>
-<span id="cb61-12"><a href="#cb61-12" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb61-13"><a href="#cb61-13" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb62"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb62-1"><a href="#cb62-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb62-2"><a href="#cb62-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
+<span id="cb62-3"><a href="#cb62-3" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb62-4"><a href="#cb62-4" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb62-5"><a href="#cb62-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> utf8 = <span class="kw">try</span> std.unicode.Utf8View.init(<span class="st">"アメリカ"</span>);</span>
+<span id="cb62-6"><a href="#cb62-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> iterator = utf8.iterator();</span>
+<span id="cb62-7"><a href="#cb62-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">while</span> (iterator.nextCodepointSlice()) |codepoint| <span class="op">{</span></span>
+<span id="cb62-8"><a href="#cb62-8" aria-hidden="true" tabindex="-1"></a>        <span class="kw">try</span> stdout.print(</span>
+<span id="cb62-9"><a href="#cb62-9" aria-hidden="true" tabindex="-1"></a>            <span class="st">"got codepoint {}</span><span class="sc">\n</span><span class="st">"</span>,</span>
+<span id="cb62-10"><a href="#cb62-10" aria-hidden="true" tabindex="-1"></a>            .<span class="op">{</span>std.fmt.fmtSliceHexUpper(codepoint)<span class="op">}</span>,</span>
+<span id="cb62-11"><a href="#cb62-11" aria-hidden="true" tabindex="-1"></a>        );</span>
+<span id="cb62-12"><a href="#cb62-12" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb62-13"><a href="#cb62-13" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>got codepoint E382A2
 got codepoint E383A1
@@ -976,10 +980,10 @@ <h3 data-number="1.8.4" class="anchored" data-anchor-id="sec-strings-useful-funs
 <p>Notice that all of these functions come from the <code>mem</code> module of the Zig Standard Library. This module contains multiple functions and methods that are useful to work with memory and sequences of bytes in general.</p>
 <p>The <code>eql()</code> function is used to check if two arrays of data are equal or not. Since strings are just arbitrary arrays of bytes, we can use this function to compare two strings together. This function returns a boolean value indicating if the two strings are equal or not. The first argument of this function is the data type of the elements of the arrays that are being compared.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb63"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb63-1"><a href="#cb63-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> name: []<span class="kw">const</span> <span class="dt">u8</span> = <span class="st">"Pedro"</span>;</span>
-<span id="cb63-2"><a href="#cb63-2" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(</span>
-<span id="cb63-3"><a href="#cb63-3" aria-hidden="true" tabindex="-1"></a>    <span class="st">"{any}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>std.mem.eql(<span class="dt">u8</span>, name, <span class="st">"Pedro"</span>)<span class="op">}</span></span>
-<span id="cb63-4"><a href="#cb63-4" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb64"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb64-1"><a href="#cb64-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> name: []<span class="kw">const</span> <span class="dt">u8</span> = <span class="st">"Pedro"</span>;</span>
+<span id="cb64-2"><a href="#cb64-2" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(</span>
+<span id="cb64-3"><a href="#cb64-3" aria-hidden="true" tabindex="-1"></a>    <span class="st">"{any}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>std.mem.eql(<span class="dt">u8</span>, name, <span class="st">"Pedro"</span>)<span class="op">}</span></span>
+<span id="cb64-4"><a href="#cb64-4" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>true</code></pre>
 </div>
@@ -987,24 +991,23 @@ <h3 data-number="1.8.4" class="anchored" data-anchor-id="sec-strings-useful-funs
 <p>The <code>splitScalar()</code> and <code>splitSequence()</code> functions are useful to split a string into multiple fragments, like the <code>split()</code> method from Python strings. The difference between these two methods is that the <code>splitScalar()</code> uses a single character as the separator to split the string, while <code>splitSequence()</code> uses a sequence of characters (a.k.a. a substring) as the separator. There is a practical example of these functions later in the book.</p>
 <p>The <code>startsWith()</code> and <code>endsWith()</code> functions are pretty straightforward. They return a boolean value indicating if the string (or, more precisely, if the array of data) begins (<code>startsWith</code>) or ends (<code>endsWith</code>) with the sequence provided.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb65"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb65-1"><a href="#cb65-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> name: []<span class="kw">const</span> <span class="dt">u8</span> = <span class="st">"Pedro"</span>;</span>
-<span id="cb65-2"><a href="#cb65-2" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(</span>
-<span id="cb65-3"><a href="#cb65-3" aria-hidden="true" tabindex="-1"></a>    <span class="st">"{any}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>std.mem.startsWith(<span class="dt">u8</span>, name, <span class="st">"Pe"</span>)<span class="op">}</span></span>
-<span id="cb65-4"><a href="#cb65-4" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb66"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb66-1"><a href="#cb66-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> name: []<span class="kw">const</span> <span class="dt">u8</span> = <span class="st">"Pedro"</span>;</span>
+<span id="cb66-2"><a href="#cb66-2" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(</span>
+<span id="cb66-3"><a href="#cb66-3" aria-hidden="true" tabindex="-1"></a>    <span class="st">"{any}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>std.mem.startsWith(<span class="dt">u8</span>, name, <span class="st">"Pe"</span>)<span class="op">}</span></span>
+<span id="cb66-4"><a href="#cb66-4" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>true</code></pre>
 </div>
 </div>
 <p>The <code>concat()</code> function, as the name suggests, concatenate two or more strings together. Because the process of concatenating the strings involves allocating enough space to accomodate all the strings together, this <code>concat()</code> function receives an allocator object as input.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb67"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb67-1"><a href="#cb67-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> str1 = <span class="st">"Hello"</span>;</span>
-<span id="cb67-2"><a href="#cb67-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> str2 = <span class="st">" you!"</span>;</span>
-<span id="cb67-3"><a href="#cb67-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> str3 = <span class="kw">try</span> std.mem.concat(</span>
-<span id="cb67-4"><a href="#cb67-4" aria-hidden="true" tabindex="-1"></a>    allocator, <span class="dt">u8</span>, &amp;[_][]<span class="kw">const</span> <span class="dt">u8</span><span class="op">{</span> str1, str2 <span class="op">}</span></span>
-<span id="cb67-5"><a href="#cb67-5" aria-hidden="true" tabindex="-1"></a>);</span>
-<span id="cb67-6"><a href="#cb67-6" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{s}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>str3<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb68"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb68-1"><a href="#cb68-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> str1 = <span class="st">"Hello"</span>;</span>
+<span id="cb68-2"><a href="#cb68-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> str2 = <span class="st">" you!"</span>;</span>
+<span id="cb68-3"><a href="#cb68-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> str3 = <span class="kw">try</span> std.mem.concat(</span>
+<span id="cb68-4"><a href="#cb68-4" aria-hidden="true" tabindex="-1"></a>    allocator, <span class="dt">u8</span>, &amp;[_][]<span class="kw">const</span> <span class="dt">u8</span><span class="op">{</span> str1, str2 <span class="op">}</span></span>
+<span id="cb68-5"><a href="#cb68-5" aria-hidden="true" tabindex="-1"></a>);</span>
+<span id="cb68-6"><a href="#cb68-6" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{s}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>str3<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<pre><code>Hello you!</code></pre>
 <p>As you can imagine, the <code>replace()</code> function is used to replace substrings in a string by another substring. This function works very similarly to the <code>replace()</code> method from Python strings. Therefore, you provide a substring to search, and every time that the <code>replace()</code> function finds this substring within the input string, it replaces this substring with the “replacement substring” that you provided as input.</p>
 <p>In the example below, we are taking the input string “Hello”, and replacing all occurrences of the substring “el” inside this input string with “34”, and saving the results inside the <code>buffer</code> object. As result, the <code>replace()</code> function returns an <code>usize</code> value that indicates how many replacements were performed.</p>
 <div class="cell">
diff --git a/docs/Chapters/02-debugging.html b/docs/Chapters/02-debugging.html
index 74a25692..4463b19c 100644
--- a/docs/Chapters/02-debugging.html
+++ b/docs/Chapters/02-debugging.html
@@ -356,14 +356,17 @@ <h2 data-number="5.1" class="anchored" data-anchor-id="print-debugging"><span cl
 <span id="cb3-7"><a href="#cb3-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> result = add(<span class="dv">34</span>, <span class="dv">16</span>);</span>
 <span id="cb3-8"><a href="#cb3-8" aria-hidden="true" tabindex="-1"></a>    std.debug.print(<span class="st">"Result: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>result<span class="op">}</span>);</span>
 <span id="cb3-9"><a href="#cb3-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="cell-output cell-output-stdout">
+<pre><code>Result: 50</code></pre>
+</div>
 </div>
 <pre><code>Result: 50</code></pre>
 <p>You could also achieve the exact same result by getting a file descriptor object to <code>stderr</code>, then, creating a <em>writer</em> object to <code>stderr</code>, then, using the <code>print()</code> method of this <em>writer</em> object, like in the example below:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb5"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stderr = std.io.getStdErr().writer();</span>
-<span id="cb5-3"><a href="#cb5-3" aria-hidden="true" tabindex="-1"></a><span class="co">// some more lines ...</span></span>
-<span id="cb5-4"><a href="#cb5-4" aria-hidden="true" tabindex="-1"></a>_ = <span class="kw">try</span> stderr.print(<span class="st">"Result: {d}"</span>, .<span class="op">{</span>result<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb6"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb6-2"><a href="#cb6-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stderr = std.io.getStdErr().writer();</span>
+<span id="cb6-3"><a href="#cb6-3" aria-hidden="true" tabindex="-1"></a><span class="co">// some more lines ...</span></span>
+<span id="cb6-4"><a href="#cb6-4" aria-hidden="true" tabindex="-1"></a>_ = <span class="kw">try</span> stderr.print(<span class="st">"Result: {d}"</span>, .<span class="op">{</span>result<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
 <section id="debugging-through-debuggers" class="level2" data-number="5.2">
@@ -379,83 +382,83 @@ <h3 data-number="5.2.1" class="anchored" data-anchor-id="sec-compile-debug-mode"
 <h3 data-number="5.2.2" class="anchored" data-anchor-id="lets-debug-a-program"><span class="header-section-number">5.2.2</span> Let’s debug a program</h3>
 <p>As an example, let’s use LLDB to navigate and investigate the following piece of Zig code:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb6"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb6-2"><a href="#cb6-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
-<span id="cb6-3"><a href="#cb6-3" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb6-4"><a href="#cb6-4" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> add_and_increment(a: <span class="dt">u8</span>, b: <span class="dt">u8</span>) <span class="dt">u8</span> <span class="op">{</span></span>
-<span id="cb6-5"><a href="#cb6-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> sum = a + b;</span>
-<span id="cb6-6"><a href="#cb6-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> incremented = sum + <span class="dv">1</span>;</span>
-<span id="cb6-7"><a href="#cb6-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> incremented;</span>
-<span id="cb6-8"><a href="#cb6-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
-<span id="cb6-9"><a href="#cb6-9" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb6-10"><a href="#cb6-10" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb6-11"><a href="#cb6-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> n = add_and_increment(<span class="dv">2</span>, <span class="dv">3</span>);</span>
-<span id="cb6-12"><a href="#cb6-12" aria-hidden="true" tabindex="-1"></a>    n = add_and_increment(n, n);</span>
-<span id="cb6-13"><a href="#cb6-13" aria-hidden="true" tabindex="-1"></a>    _ = <span class="kw">try</span> stdout.print(<span class="st">"Result: {d}!</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>n<span class="op">}</span>);</span>
-<span id="cb6-14"><a href="#cb6-14" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb7"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb7-2"><a href="#cb7-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
+<span id="cb7-3"><a href="#cb7-3" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb7-4"><a href="#cb7-4" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> add_and_increment(a: <span class="dt">u8</span>, b: <span class="dt">u8</span>) <span class="dt">u8</span> <span class="op">{</span></span>
+<span id="cb7-5"><a href="#cb7-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> sum = a + b;</span>
+<span id="cb7-6"><a href="#cb7-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> incremented = sum + <span class="dv">1</span>;</span>
+<span id="cb7-7"><a href="#cb7-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> incremented;</span>
+<span id="cb7-8"><a href="#cb7-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
+<span id="cb7-9"><a href="#cb7-9" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb7-10"><a href="#cb7-10" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb7-11"><a href="#cb7-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> n = add_and_increment(<span class="dv">2</span>, <span class="dv">3</span>);</span>
+<span id="cb7-12"><a href="#cb7-12" aria-hidden="true" tabindex="-1"></a>    n = add_and_increment(n, n);</span>
+<span id="cb7-13"><a href="#cb7-13" aria-hidden="true" tabindex="-1"></a>    _ = <span class="kw">try</span> stdout.print(<span class="st">"Result: {d}!</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>n<span class="op">}</span>);</span>
+<span id="cb7-14"><a href="#cb7-14" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>Result: 13!</code></pre>
 </div>
 </div>
 <p>There is nothing wrong with this program. But it is a good start for us. First, we need to compile this program with the <code>zig build-exe</code> command. For this example, suppose that I have compiled the above Zig code into a binary executable called <code>add_program</code>.</p>
-<div class="sourceCode" id="cb8"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zig</span> build-exe add_program.zig</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode" id="cb9"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb9-1"><a href="#cb9-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zig</span> build-exe add_program.zig</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <p>Now, we can start LLDB with <code>add_program</code>, like this:</p>
-<div class="sourceCode" id="cb9"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb9-1"><a href="#cb9-1" aria-hidden="true" tabindex="-1"></a><span class="ex">lldb</span> add_program</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode" id="cb10"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="ex">lldb</span> add_program</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <p>From now on, LLDB is started, and you can know that I’m executing LLDB commands by looking at the prefix <code>(lldb)</code>. If something is prefixed with <code>(lldb)</code>, then you know that it is a LLDB command.</p>
 <p>The first thing I will do, is to set a breakpoint at the <code>main()</code> function, by executing <code>b main</code>. After that, I just start the execution of the program with <code>run</code>. You can see in the output below, that the execution stopped at the first line in the function <code>main()</code>, as we expected.</p>
-<div class="sourceCode" id="cb10"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">b</span> main</span>
-<span id="cb10-2"><a href="#cb10-2" aria-hidden="true" tabindex="-1"></a><span class="ex">Breakpoint</span> 1: where = debugging<span class="kw">`</span><span class="ex">debug1.main</span> + 22</span>
-<span id="cb10-3"><a href="#cb10-3" aria-hidden="true" tabindex="-1"></a>    <span class="ex">at</span> debug1.zig:11:30, address = 0x00000000010341a6</span>
-<span id="cb10-4"><a href="#cb10-4" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">run</span></span>
-<span id="cb10-5"><a href="#cb10-5" aria-hidden="true" tabindex="-1"></a><span class="ex">Process</span> 8654 launched: <span class="st">'add_program'</span> <span class="er">(</span><span class="ex">x86_64</span><span class="kw">)</span></span>
-<span id="cb10-6"><a href="#cb10-6" aria-hidden="true" tabindex="-1"></a><span class="ex">Process</span> 8654 stopped</span>
-<span id="cb10-7"><a href="#cb10-7" aria-hidden="true" tabindex="-1"></a><span class="ex">*</span> thread <span class="co">#1, name = 'add_program',</span></span>
-<span id="cb10-8"><a href="#cb10-8" aria-hidden="true" tabindex="-1"></a>    <span class="ex">stop</span> reason = breakpoint 1.1 frame <span class="co">#0: 0x10341a6</span></span>
-<span id="cb10-9"><a href="#cb10-9" aria-hidden="true" tabindex="-1"></a>    <span class="ex">add_program</span><span class="kw">`</span>debug1.main at add_program.zig:11:30</span>
-<span id="cb10-10"><a href="#cb10-10" aria-hidden="true" tabindex="-1"></a>   <span class="ex">8</span>    }</span>
-<span id="cb10-11"><a href="#cb10-11" aria-hidden="true" tabindex="-1"></a>   <span class="ex">9</span>    </span>
-<span id="cb10-12"><a href="#cb10-12" aria-hidden="true" tabindex="-1"></a>   <span class="ex">10</span>   pub fn main<span class="er">(</span><span class="kw">)</span> <span class="ex">!void</span> {</span>
-<span id="cb10-13"><a href="#cb10-13" aria-hidden="true" tabindex="-1"></a><span class="ex">-</span><span class="op">&gt;</span> 11       var n = add_and_increment<span class="er">(</span><span class="ex">2,</span> 3<span class="kw">);</span></span>
-<span id="cb10-14"><a href="#cb10-14" aria-hidden="true" tabindex="-1"></a>   <span class="ex">12</span>       n = add_and_increment<span class="er">(</span><span class="ex">n,</span> n<span class="kw">);</span></span>
-<span id="cb10-15"><a href="#cb10-15" aria-hidden="true" tabindex="-1"></a>   <span class="ex">13</span>       try stdout.print<span class="er">(</span><span class="st">"Result: {d}!\n"</span><span class="ex">,</span> .{n}<span class="kw">);</span></span>
-<span id="cb10-16"><a href="#cb10-16" aria-hidden="true" tabindex="-1"></a>   <span class="ex">14</span>   }</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode" id="cb11"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">b</span> main</span>
+<span id="cb11-2"><a href="#cb11-2" aria-hidden="true" tabindex="-1"></a><span class="ex">Breakpoint</span> 1: where = debugging<span class="kw">`</span><span class="ex">debug1.main</span> + 22</span>
+<span id="cb11-3"><a href="#cb11-3" aria-hidden="true" tabindex="-1"></a>    <span class="ex">at</span> debug1.zig:11:30, address = 0x00000000010341a6</span>
+<span id="cb11-4"><a href="#cb11-4" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">run</span></span>
+<span id="cb11-5"><a href="#cb11-5" aria-hidden="true" tabindex="-1"></a><span class="ex">Process</span> 8654 launched: <span class="st">'add_program'</span> <span class="er">(</span><span class="ex">x86_64</span><span class="kw">)</span></span>
+<span id="cb11-6"><a href="#cb11-6" aria-hidden="true" tabindex="-1"></a><span class="ex">Process</span> 8654 stopped</span>
+<span id="cb11-7"><a href="#cb11-7" aria-hidden="true" tabindex="-1"></a><span class="ex">*</span> thread <span class="co">#1, name = 'add_program',</span></span>
+<span id="cb11-8"><a href="#cb11-8" aria-hidden="true" tabindex="-1"></a>    <span class="ex">stop</span> reason = breakpoint 1.1 frame <span class="co">#0: 0x10341a6</span></span>
+<span id="cb11-9"><a href="#cb11-9" aria-hidden="true" tabindex="-1"></a>    <span class="ex">add_program</span><span class="kw">`</span>debug1.main at add_program.zig:11:30</span>
+<span id="cb11-10"><a href="#cb11-10" aria-hidden="true" tabindex="-1"></a>   <span class="ex">8</span>    }</span>
+<span id="cb11-11"><a href="#cb11-11" aria-hidden="true" tabindex="-1"></a>   <span class="ex">9</span>    </span>
+<span id="cb11-12"><a href="#cb11-12" aria-hidden="true" tabindex="-1"></a>   <span class="ex">10</span>   pub fn main<span class="er">(</span><span class="kw">)</span> <span class="ex">!void</span> {</span>
+<span id="cb11-13"><a href="#cb11-13" aria-hidden="true" tabindex="-1"></a><span class="ex">-</span><span class="op">&gt;</span> 11       var n = add_and_increment<span class="er">(</span><span class="ex">2,</span> 3<span class="kw">);</span></span>
+<span id="cb11-14"><a href="#cb11-14" aria-hidden="true" tabindex="-1"></a>   <span class="ex">12</span>       n = add_and_increment<span class="er">(</span><span class="ex">n,</span> n<span class="kw">);</span></span>
+<span id="cb11-15"><a href="#cb11-15" aria-hidden="true" tabindex="-1"></a>   <span class="ex">13</span>       try stdout.print<span class="er">(</span><span class="st">"Result: {d}!\n"</span><span class="ex">,</span> .{n}<span class="kw">);</span></span>
+<span id="cb11-16"><a href="#cb11-16" aria-hidden="true" tabindex="-1"></a>   <span class="ex">14</span>   }</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <p>I can start navigating through the code, and checking the objects that are being generated. If you are not familiar with the commands available in LLDB, I recommend you to read the official documentation of the project<a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a>. You can also look for cheat sheets, which quickly describes all commands available for you<a href="#fn4" class="footnote-ref" id="fnref4" role="doc-noteref"><sup>4</sup></a>.</p>
 <p>Currently, we are in the first line at the <code>main()</code> function. In this line, we create the <code>n</code> object, by executing the <code>add_and_increment()</code> function. To execute the current line of code, and go to the next line, we can run the <code>n</code> LLDB command. Let’s execute this command.</p>
 <p>After we executed this line, we can also look at the value stored inside this <code>n</code> object by using the <code>p</code> LLDB command. The syntax for this command is <code>p &lt;name-of-object&gt;</code>.</p>
 <p>If we take a look at the value stored in the <code>n</code> object (<code>p n</code>), notice that it stores the hexadecimal value <code>0x06</code>, which is the number 6 in decimal. We can also see that, this value have a type <code>unsigned char</code>, which is an unsigned 8-bit integer. We have talked already about this at <a href="01-zig-weird.html#sec-zig-strings" class="quarto-xref"><span>Section 1.8</span></a>, that <code>u8</code> integers in Zig are equivalent to the C data type <code>unsigned char</code>.</p>
-<div class="sourceCode" id="cb11"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">n</span></span>
-<span id="cb11-2"><a href="#cb11-2" aria-hidden="true" tabindex="-1"></a><span class="ex">Process</span> 4798 stopped</span>
-<span id="cb11-3"><a href="#cb11-3" aria-hidden="true" tabindex="-1"></a><span class="ex">*</span> thread <span class="co">#1, name = 'debugging',</span></span>
-<span id="cb11-4"><a href="#cb11-4" aria-hidden="true" tabindex="-1"></a>    <span class="ex">stop</span> reason = step over frame <span class="co">#0: 0x10341ae</span></span>
-<span id="cb11-5"><a href="#cb11-5" aria-hidden="true" tabindex="-1"></a>    <span class="ex">debugging</span><span class="kw">`</span><span class="ex">debug1.main</span> at debug1.zig:12:26</span>
-<span id="cb11-6"><a href="#cb11-6" aria-hidden="true" tabindex="-1"></a>   <span class="ex">9</span>    </span>
-<span id="cb11-7"><a href="#cb11-7" aria-hidden="true" tabindex="-1"></a>   <span class="ex">10</span>   pub fn main<span class="er">(</span><span class="kw">)</span> <span class="ex">!void</span> {</span>
-<span id="cb11-8"><a href="#cb11-8" aria-hidden="true" tabindex="-1"></a>   <span class="ex">11</span>       var n = add_and_increment<span class="er">(</span><span class="ex">2,</span> 3<span class="kw">);</span></span>
-<span id="cb11-9"><a href="#cb11-9" aria-hidden="true" tabindex="-1"></a><span class="ex">-</span><span class="op">&gt;</span> 12       n = add_and_increment<span class="er">(</span><span class="ex">n,</span> n<span class="kw">);</span></span>
-<span id="cb11-10"><a href="#cb11-10" aria-hidden="true" tabindex="-1"></a>   <span class="ex">13</span>       try stdout.print<span class="er">(</span><span class="st">"Result: {d}!\n"</span><span class="ex">,</span> .{n}<span class="kw">);</span></span>
-<span id="cb11-11"><a href="#cb11-11" aria-hidden="true" tabindex="-1"></a>   <span class="ex">14</span>   }</span>
-<span id="cb11-12"><a href="#cb11-12" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">p</span> n</span>
-<span id="cb11-13"><a href="#cb11-13" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">unsigned</span> char<span class="kw">)</span> <span class="va">$1</span> = <span class="st">'\x06'</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode" id="cb12"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">n</span></span>
+<span id="cb12-2"><a href="#cb12-2" aria-hidden="true" tabindex="-1"></a><span class="ex">Process</span> 4798 stopped</span>
+<span id="cb12-3"><a href="#cb12-3" aria-hidden="true" tabindex="-1"></a><span class="ex">*</span> thread <span class="co">#1, name = 'debugging',</span></span>
+<span id="cb12-4"><a href="#cb12-4" aria-hidden="true" tabindex="-1"></a>    <span class="ex">stop</span> reason = step over frame <span class="co">#0: 0x10341ae</span></span>
+<span id="cb12-5"><a href="#cb12-5" aria-hidden="true" tabindex="-1"></a>    <span class="ex">debugging</span><span class="kw">`</span><span class="ex">debug1.main</span> at debug1.zig:12:26</span>
+<span id="cb12-6"><a href="#cb12-6" aria-hidden="true" tabindex="-1"></a>   <span class="ex">9</span>    </span>
+<span id="cb12-7"><a href="#cb12-7" aria-hidden="true" tabindex="-1"></a>   <span class="ex">10</span>   pub fn main<span class="er">(</span><span class="kw">)</span> <span class="ex">!void</span> {</span>
+<span id="cb12-8"><a href="#cb12-8" aria-hidden="true" tabindex="-1"></a>   <span class="ex">11</span>       var n = add_and_increment<span class="er">(</span><span class="ex">2,</span> 3<span class="kw">);</span></span>
+<span id="cb12-9"><a href="#cb12-9" aria-hidden="true" tabindex="-1"></a><span class="ex">-</span><span class="op">&gt;</span> 12       n = add_and_increment<span class="er">(</span><span class="ex">n,</span> n<span class="kw">);</span></span>
+<span id="cb12-10"><a href="#cb12-10" aria-hidden="true" tabindex="-1"></a>   <span class="ex">13</span>       try stdout.print<span class="er">(</span><span class="st">"Result: {d}!\n"</span><span class="ex">,</span> .{n}<span class="kw">);</span></span>
+<span id="cb12-11"><a href="#cb12-11" aria-hidden="true" tabindex="-1"></a>   <span class="ex">14</span>   }</span>
+<span id="cb12-12"><a href="#cb12-12" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">p</span> n</span>
+<span id="cb12-13"><a href="#cb12-13" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">unsigned</span> char<span class="kw">)</span> <span class="va">$1</span> = <span class="st">'\x06'</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <p>Now, on the next line of code, we are executing the <code>add_and_increment()</code> function once again. Why not step inside this function? Shall we? We can do that, by executing the <code>s</code> LLDB command. Notice in the example below that, after executing this command, we have entered into the context of the <code>add_and_increment()</code> function.</p>
 <p>Also notice in the example below that, I have walked two more lines in the function’s body, then, I execute the <code>frame variable</code> LLDB command, to see at once, the value stored in each of the variables that were created inside the current scope.</p>
 <p>You can see in the output below that, the object <code>sum</code> stores the value <code>\f</code>, which represents the <em>form feed</em> character. This character in the ASCII table, corresponds to the hexadecimal value <code>0x0C</code>, or, in decimal, the number 12. So, this means that the result of the expression <code>a + b</code> executed at line 5, resulted in the number 12.</p>
-<div class="sourceCode" id="cb12"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">s</span></span>
-<span id="cb12-2"><a href="#cb12-2" aria-hidden="true" tabindex="-1"></a><span class="ex">Process</span> 4798 stopped</span>
-<span id="cb12-3"><a href="#cb12-3" aria-hidden="true" tabindex="-1"></a><span class="ex">*</span> thread <span class="co">#1, name = 'debugging',</span></span>
-<span id="cb12-4"><a href="#cb12-4" aria-hidden="true" tabindex="-1"></a>    <span class="ex">stop</span> reason = step in frame <span class="co">#0: 0x10342de</span></span>
-<span id="cb12-5"><a href="#cb12-5" aria-hidden="true" tabindex="-1"></a>    <span class="ex">debugging</span><span class="kw">`</span><span class="ex">debug1.add_and_increment</span><span class="er">(</span><span class="va">a</span><span class="op">=</span><span class="st">'\x02'</span>, <span class="va">b</span><span class="op">=</span><span class="st">'\x03'</span><span class="kw">)</span></span>
-<span id="cb12-6"><a href="#cb12-6" aria-hidden="true" tabindex="-1"></a>    <span class="ex">at</span> debug1.zig:4:39</span>
-<span id="cb12-7"><a href="#cb12-7" aria-hidden="true" tabindex="-1"></a><span class="ex">-</span><span class="op">&gt;</span> 4    fn add_and_increment<span class="er">(</span><span class="ex">a:</span> u8, b: u8<span class="kw">)</span> <span class="ex">u8</span> {</span>
-<span id="cb12-8"><a href="#cb12-8" aria-hidden="true" tabindex="-1"></a>   <span class="ex">5</span>        const sum = a + b<span class="kw">;</span></span>
-<span id="cb12-9"><a href="#cb12-9" aria-hidden="true" tabindex="-1"></a>   <span class="ex">6</span>        const incremented = sum + 1<span class="kw">;</span></span>
-<span id="cb12-10"><a href="#cb12-10" aria-hidden="true" tabindex="-1"></a>   <span class="ex">7</span>        return incremented<span class="kw">;</span></span>
-<span id="cb12-11"><a href="#cb12-11" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">n</span></span>
-<span id="cb12-12"><a href="#cb12-12" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">n</span></span>
-<span id="cb12-13"><a href="#cb12-13" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">frame</span> variable</span>
-<span id="cb12-14"><a href="#cb12-14" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">unsigned</span> char<span class="kw">)</span> <span class="ex">a</span> = <span class="st">'\x06'</span></span>
-<span id="cb12-15"><a href="#cb12-15" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">unsigned</span> char<span class="kw">)</span> <span class="ex">b</span> = <span class="st">'\x06'</span></span>
-<span id="cb12-16"><a href="#cb12-16" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">unsigned</span> char<span class="kw">)</span> <span class="fu">sum</span> = <span class="st">'\f'</span></span>
-<span id="cb12-17"><a href="#cb12-17" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">unsigned</span> char<span class="kw">)</span> <span class="ex">incremented</span> = <span class="st">'\x06'</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode" id="cb13"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">s</span></span>
+<span id="cb13-2"><a href="#cb13-2" aria-hidden="true" tabindex="-1"></a><span class="ex">Process</span> 4798 stopped</span>
+<span id="cb13-3"><a href="#cb13-3" aria-hidden="true" tabindex="-1"></a><span class="ex">*</span> thread <span class="co">#1, name = 'debugging',</span></span>
+<span id="cb13-4"><a href="#cb13-4" aria-hidden="true" tabindex="-1"></a>    <span class="ex">stop</span> reason = step in frame <span class="co">#0: 0x10342de</span></span>
+<span id="cb13-5"><a href="#cb13-5" aria-hidden="true" tabindex="-1"></a>    <span class="ex">debugging</span><span class="kw">`</span><span class="ex">debug1.add_and_increment</span><span class="er">(</span><span class="va">a</span><span class="op">=</span><span class="st">'\x02'</span>, <span class="va">b</span><span class="op">=</span><span class="st">'\x03'</span><span class="kw">)</span></span>
+<span id="cb13-6"><a href="#cb13-6" aria-hidden="true" tabindex="-1"></a>    <span class="ex">at</span> debug1.zig:4:39</span>
+<span id="cb13-7"><a href="#cb13-7" aria-hidden="true" tabindex="-1"></a><span class="ex">-</span><span class="op">&gt;</span> 4    fn add_and_increment<span class="er">(</span><span class="ex">a:</span> u8, b: u8<span class="kw">)</span> <span class="ex">u8</span> {</span>
+<span id="cb13-8"><a href="#cb13-8" aria-hidden="true" tabindex="-1"></a>   <span class="ex">5</span>        const sum = a + b<span class="kw">;</span></span>
+<span id="cb13-9"><a href="#cb13-9" aria-hidden="true" tabindex="-1"></a>   <span class="ex">6</span>        const incremented = sum + 1<span class="kw">;</span></span>
+<span id="cb13-10"><a href="#cb13-10" aria-hidden="true" tabindex="-1"></a>   <span class="ex">7</span>        return incremented<span class="kw">;</span></span>
+<span id="cb13-11"><a href="#cb13-11" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">n</span></span>
+<span id="cb13-12"><a href="#cb13-12" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">n</span></span>
+<span id="cb13-13"><a href="#cb13-13" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">frame</span> variable</span>
+<span id="cb13-14"><a href="#cb13-14" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">unsigned</span> char<span class="kw">)</span> <span class="ex">a</span> = <span class="st">'\x06'</span></span>
+<span id="cb13-15"><a href="#cb13-15" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">unsigned</span> char<span class="kw">)</span> <span class="ex">b</span> = <span class="st">'\x06'</span></span>
+<span id="cb13-16"><a href="#cb13-16" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">unsigned</span> char<span class="kw">)</span> <span class="fu">sum</span> = <span class="st">'\f'</span></span>
+<span id="cb13-17"><a href="#cb13-17" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">unsigned</span> char<span class="kw">)</span> <span class="ex">incremented</span> = <span class="st">'\x06'</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </section>
 </section>
 <section id="how-to-investigate-the-data-type-of-your-objects" class="level2" data-number="5.3">
@@ -464,15 +467,15 @@ <h2 data-number="5.3" class="anchored" data-anchor-id="how-to-investigate-the-da
 <p>When you walk through your program with a debugger, you can inspect the types of your objects by simply printing them to the console, with the LLDB <code>p</code> command. But you also have alternatives embedded in the language itself to access the data types of your objects.</p>
 <p>In Zig, you can retrieve the data type of an object, by using the built-in function <code>@TypeOf()</code>. Just apply this function over the object, and you get access to the data type of the object.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb13"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb13-2"><a href="#cb13-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
-<span id="cb13-3"><a href="#cb13-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = std.testing.expect;</span>
-<span id="cb13-4"><a href="#cb13-4" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb13-5"><a href="#cb13-5" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb13-6"><a href="#cb13-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> number: <span class="dt">i32</span> = <span class="dv">5</span>;</span>
-<span id="cb13-7"><a href="#cb13-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(number) == <span class="dt">i32</span>);</span>
-<span id="cb13-8"><a href="#cb13-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"{any}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="bu">@TypeOf</span>(number)<span class="op">}</span>);</span>
-<span id="cb13-9"><a href="#cb13-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb14"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb14-2"><a href="#cb14-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
+<span id="cb14-3"><a href="#cb14-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = std.testing.expect;</span>
+<span id="cb14-4"><a href="#cb14-4" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb14-5"><a href="#cb14-5" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb14-6"><a href="#cb14-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> number: <span class="dt">i32</span> = <span class="dv">5</span>;</span>
+<span id="cb14-7"><a href="#cb14-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(number) == <span class="dt">i32</span>);</span>
+<span id="cb14-8"><a href="#cb14-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"{any}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="bu">@TypeOf</span>(number)<span class="op">}</span>);</span>
+<span id="cb14-9"><a href="#cb14-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>i32</code></pre>
 </div>
diff --git a/docs/Chapters/03-structs.html b/docs/Chapters/03-structs.html
index a9014775..a469e292 100644
--- a/docs/Chapters/03-structs.html
+++ b/docs/Chapters/03-structs.html
@@ -570,9 +570,10 @@ <h3 data-number="2.1.5" class="anchored" data-anchor-id="for-loops"><span class=
 <p>You can do that by providing a second set of items to iterate over. More precisely, you provide the range selector <code>0..</code> to the for loop. So, yes, you can use two different iterators at the same time in a for loop in Zig.</p>
 <p>But remember from <a href="01-zig-weird.html#sec-assignments" class="quarto-xref"><span>Section 1.4</span></a> that, every object you create in Zig must be used in some way. So if you declare two iterators in your for loop, you must use both iterators inside the for loop body. But if you want to use just the index iterator, and not use the “value iterator”, then, you can discard the value iterator by maching the value items to the underscore character, like in the example below:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb20"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb20-1"><a href="#cb20-1" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (name, <span class="dv">0</span>..) |_, i| <span class="op">{</span></span>
-<span id="cb20-2"><a href="#cb20-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"{d} | "</span>, .<span class="op">{</span>i<span class="op">}</span>);</span>
-<span id="cb20-3"><a href="#cb20-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb20"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb20-1"><a href="#cb20-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> name = <span class="st">"Pedro"</span>;</span>
+<span id="cb20-2"><a href="#cb20-2" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (name, <span class="dv">0</span>..) |_, i| <span class="op">{</span></span>
+<span id="cb20-3"><a href="#cb20-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"{d} | "</span>, .<span class="op">{</span>i<span class="op">}</span>);</span>
+<span id="cb20-4"><a href="#cb20-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>0 | 1 | 2 | 3 | 4 |</code></pre>
 </section>
@@ -679,6 +680,9 @@ <h3 data-number="2.2.2" class="anchored" data-anchor-id="how-to-overcome-this-ba
 <span id="cb32-9"><a href="#cb32-9" aria-hidden="true" tabindex="-1"></a>    add2(&amp;x);</span>
 <span id="cb32-10"><a href="#cb32-10" aria-hidden="true" tabindex="-1"></a>    std.debug.print(<span class="st">"Result: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>x<span class="op">}</span>);</span>
 <span id="cb32-11"><a href="#cb32-11" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="cell-output cell-output-stdout">
+<pre><code>Result: 6</code></pre>
+</div>
 </div>
 <pre><code>Result: 6</code></pre>
 <p>Even in this code example above, the <code>x</code> argument is still immutable. Which means that the pointer itself is immutable. Therefore, you cannot change the memory address that it points to. However, you can dereference the pointer to access the value that it points to, and also, to change this value, if you need to.</p>
@@ -694,33 +698,33 @@ <h2 data-number="2.3" class="anchored" data-anchor-id="sec-structs-and-oop"><spa
 <p>If you look at the <code>User</code> struct below, you can see the <code>struct</code> keyword. Notice the data members of this struct: <code>id</code>, <code>name</code> and <code>email</code>. Every data member has its type explicitly annotated, with the colon character (<code>:</code>) syntax that we described earlier in <a href="01-zig-weird.html#sec-root-file" class="quarto-xref"><span>Section 1.2.2</span></a>. But also notice that every line in the struct body that describes a data member, ends with a comma character (<code>,</code>). So every time you declare a data member in your Zig code, always end the line with a comma character, instead of ending it with the traditional semicolon character (<code>;</code>).</p>
 <p>Next, we have registered an <code>init()</code> function as a method of this <code>User</code> struct. This <code>init()</code> method is the constructor method that we will use to instantiate every new <code>User</code> object. That is why this <code>init()</code> function returns a new <code>User</code> object as result.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb34"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb34-1"><a href="#cb34-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb34-2"><a href="#cb34-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
-<span id="cb34-3"><a href="#cb34-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> User = <span class="kw">struct</span> <span class="op">{</span></span>
-<span id="cb34-4"><a href="#cb34-4" aria-hidden="true" tabindex="-1"></a>    id: <span class="dt">u64</span>,</span>
-<span id="cb34-5"><a href="#cb34-5" aria-hidden="true" tabindex="-1"></a>    name: []<span class="kw">const</span> <span class="dt">u8</span>,</span>
-<span id="cb34-6"><a href="#cb34-6" aria-hidden="true" tabindex="-1"></a>    email: []<span class="kw">const</span> <span class="dt">u8</span>,</span>
-<span id="cb34-7"><a href="#cb34-7" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb34-8"><a href="#cb34-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> init(id: <span class="dt">u64</span>,</span>
-<span id="cb34-9"><a href="#cb34-9" aria-hidden="true" tabindex="-1"></a>                name: []<span class="kw">const</span> <span class="dt">u8</span>,</span>
-<span id="cb34-10"><a href="#cb34-10" aria-hidden="true" tabindex="-1"></a>                email: []<span class="kw">const</span> <span class="dt">u8</span>) User <span class="op">{</span></span>
-<span id="cb34-11"><a href="#cb34-11" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb34-12"><a href="#cb34-12" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> User <span class="op">{</span></span>
-<span id="cb34-13"><a href="#cb34-13" aria-hidden="true" tabindex="-1"></a>            .id = id,</span>
-<span id="cb34-14"><a href="#cb34-14" aria-hidden="true" tabindex="-1"></a>            .name = name,</span>
-<span id="cb34-15"><a href="#cb34-15" aria-hidden="true" tabindex="-1"></a>            .email = email</span>
-<span id="cb34-16"><a href="#cb34-16" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span>;</span>
-<span id="cb34-17"><a href="#cb34-17" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb34-18"><a href="#cb34-18" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb34-19"><a href="#cb34-19" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> print_name(self: User) !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb34-20"><a href="#cb34-20" aria-hidden="true" tabindex="-1"></a>        <span class="kw">try</span> stdout.print(<span class="st">"{s}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>self.name<span class="op">}</span>);</span>
-<span id="cb34-21"><a href="#cb34-21" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb34-22"><a href="#cb34-22" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
-<span id="cb34-23"><a href="#cb34-23" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb34-24"><a href="#cb34-24" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb34-25"><a href="#cb34-25" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> u = User.init(<span class="dv">1</span>, <span class="st">"pedro"</span>, <span class="st">"email@gmail.com"</span>);</span>
-<span id="cb34-26"><a href="#cb34-26" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> u.print_name();</span>
-<span id="cb34-27"><a href="#cb34-27" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb35"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb35-1"><a href="#cb35-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb35-2"><a href="#cb35-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
+<span id="cb35-3"><a href="#cb35-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> User = <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb35-4"><a href="#cb35-4" aria-hidden="true" tabindex="-1"></a>    id: <span class="dt">u64</span>,</span>
+<span id="cb35-5"><a href="#cb35-5" aria-hidden="true" tabindex="-1"></a>    name: []<span class="kw">const</span> <span class="dt">u8</span>,</span>
+<span id="cb35-6"><a href="#cb35-6" aria-hidden="true" tabindex="-1"></a>    email: []<span class="kw">const</span> <span class="dt">u8</span>,</span>
+<span id="cb35-7"><a href="#cb35-7" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb35-8"><a href="#cb35-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> init(id: <span class="dt">u64</span>,</span>
+<span id="cb35-9"><a href="#cb35-9" aria-hidden="true" tabindex="-1"></a>                name: []<span class="kw">const</span> <span class="dt">u8</span>,</span>
+<span id="cb35-10"><a href="#cb35-10" aria-hidden="true" tabindex="-1"></a>                email: []<span class="kw">const</span> <span class="dt">u8</span>) User <span class="op">{</span></span>
+<span id="cb35-11"><a href="#cb35-11" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb35-12"><a href="#cb35-12" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> User <span class="op">{</span></span>
+<span id="cb35-13"><a href="#cb35-13" aria-hidden="true" tabindex="-1"></a>            .id = id,</span>
+<span id="cb35-14"><a href="#cb35-14" aria-hidden="true" tabindex="-1"></a>            .name = name,</span>
+<span id="cb35-15"><a href="#cb35-15" aria-hidden="true" tabindex="-1"></a>            .email = email</span>
+<span id="cb35-16"><a href="#cb35-16" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span>;</span>
+<span id="cb35-17"><a href="#cb35-17" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb35-18"><a href="#cb35-18" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb35-19"><a href="#cb35-19" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> print_name(self: User) !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb35-20"><a href="#cb35-20" aria-hidden="true" tabindex="-1"></a>        <span class="kw">try</span> stdout.print(<span class="st">"{s}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>self.name<span class="op">}</span>);</span>
+<span id="cb35-21"><a href="#cb35-21" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb35-22"><a href="#cb35-22" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
+<span id="cb35-23"><a href="#cb35-23" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb35-24"><a href="#cb35-24" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb35-25"><a href="#cb35-25" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> u = User.init(<span class="dv">1</span>, <span class="st">"pedro"</span>, <span class="st">"email@gmail.com"</span>);</span>
+<span id="cb35-26"><a href="#cb35-26" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> u.print_name();</span>
+<span id="cb35-27"><a href="#cb35-27" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>pedro</code></pre>
 </div>
@@ -732,23 +736,23 @@ <h2 data-number="2.3" class="anchored" data-anchor-id="sec-structs-and-oop"><spa
 <h3 data-number="2.3.1" class="anchored" data-anchor-id="sec-anonymous-struct-literals"><span class="header-section-number">2.3.1</span> Anonymous struct literals</h3>
 <p>You can declare a struct object as a literal value. When we do that, we normally specify the data type of this struct literal by writing its data type just before the opening curly brace. For example, I could write a struct literal value of the type <code>User</code> that we have defined in the previous section like this:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb36"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb36-1"><a href="#cb36-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> eu = User <span class="op">{</span></span>
-<span id="cb36-2"><a href="#cb36-2" aria-hidden="true" tabindex="-1"></a>    .id = <span class="dv">1</span>,</span>
-<span id="cb36-3"><a href="#cb36-3" aria-hidden="true" tabindex="-1"></a>    .name = <span class="st">"Pedro"</span>,</span>
-<span id="cb36-4"><a href="#cb36-4" aria-hidden="true" tabindex="-1"></a>    .email = <span class="st">"someemail@gmail.com"</span></span>
-<span id="cb36-5"><a href="#cb36-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
-<span id="cb36-6"><a href="#cb36-6" aria-hidden="true" tabindex="-1"></a>_ = eu;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb37"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb37-1"><a href="#cb37-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> eu = User <span class="op">{</span></span>
+<span id="cb37-2"><a href="#cb37-2" aria-hidden="true" tabindex="-1"></a>    .id = <span class="dv">1</span>,</span>
+<span id="cb37-3"><a href="#cb37-3" aria-hidden="true" tabindex="-1"></a>    .name = <span class="st">"Pedro"</span>,</span>
+<span id="cb37-4"><a href="#cb37-4" aria-hidden="true" tabindex="-1"></a>    .email = <span class="st">"someemail@gmail.com"</span></span>
+<span id="cb37-5"><a href="#cb37-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
+<span id="cb37-6"><a href="#cb37-6" aria-hidden="true" tabindex="-1"></a>_ = eu;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>However, in Zig, we can also write an anonymous struct literal. That is, you can write a struct literal, but not specify explicitly the type of this particular struct. An anonymous struct is written by using the syntax <code>.{}</code>. So, we essentially replaced the explicit type of the struct literal with a dot character (<code>.</code>).</p>
 <p>As we described in <a href="#sec-type-inference" class="quarto-xref"><span>Section 2.4</span></a>, when you put a dot before a struct literal, the type of this struct literal is automatically inferred by the <code>zig</code> compiler. In essence, the <code>zig</code> compiler will look for some hint of what is the type of that struct. This hint can be the type annotation of a function argument, or the return type annotation of the function that you are using, or the type annotation of an existing object. If the compiler does find such type annotation, it will use this type in your literal struct.</p>
 <p>Anonymous structs are very commonly used as inputs to function arguments in Zig. One example that you have seen already constantly, is the <code>print()</code> function from the <code>stdout</code> object. This function takes two arguments. The first argument, is a template string, which should contain string format specifiers in it, which tells how the values provided in the second argument should be printed into the message.</p>
 <p>While the second argument is a struct literal that lists the values to be printed into the template message specified in the first argument. You normally want to use an anonymous struct literal here, so that the <code>zig</code> compiler do the job of specifying the type of this particular anonymous struct for you.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb37"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb37-1"><a href="#cb37-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb37-2"><a href="#cb37-2" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb37-3"><a href="#cb37-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
-<span id="cb37-4"><a href="#cb37-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"Hello, {s}!</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="st">"world"</span><span class="op">}</span>);</span>
-<span id="cb37-5"><a href="#cb37-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb38"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb38-1"><a href="#cb38-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb38-2"><a href="#cb38-2" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb38-3"><a href="#cb38-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
+<span id="cb38-4"><a href="#cb38-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"Hello, {s}!</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="st">"world"</span><span class="op">}</span>);</span>
+<span id="cb38-5"><a href="#cb38-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>Hello, world!</code></pre>
 </div>
@@ -759,11 +763,11 @@ <h3 data-number="2.3.2" class="anchored" data-anchor-id="struct-declarations-mus
 <p>Types in Zig must be <code>const</code> or <code>comptime</code> (we are going to talk more about comptime in <a href="10-stack-project.html#sec-comptime" class="quarto-xref"><span>Section 12.1</span></a>). What this means is that you cannot create a new data type, and mark it as variable with the <code>var</code> keyword. So struct declarations are always constant. You cannot declare a new struct type using the <code>var</code> keyword. It must be <code>const</code>.</p>
 <p>In the <code>Vec3</code> example below, this declaration is allowed because I’m using the <code>const</code> keyword to declare this new data type.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb39"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb39-1"><a href="#cb39-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Vec3 = <span class="kw">struct</span> <span class="op">{</span></span>
-<span id="cb39-2"><a href="#cb39-2" aria-hidden="true" tabindex="-1"></a>    x: <span class="dt">f64</span>,</span>
-<span id="cb39-3"><a href="#cb39-3" aria-hidden="true" tabindex="-1"></a>    y: <span class="dt">f64</span>,</span>
-<span id="cb39-4"><a href="#cb39-4" aria-hidden="true" tabindex="-1"></a>    z: <span class="dt">f64</span>,</span>
-<span id="cb39-5"><a href="#cb39-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb40"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb40-1"><a href="#cb40-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Vec3 = <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb40-2"><a href="#cb40-2" aria-hidden="true" tabindex="-1"></a>    x: <span class="dt">f64</span>,</span>
+<span id="cb40-3"><a href="#cb40-3" aria-hidden="true" tabindex="-1"></a>    y: <span class="dt">f64</span>,</span>
+<span id="cb40-4"><a href="#cb40-4" aria-hidden="true" tabindex="-1"></a>    z: <span class="dt">f64</span>,</span>
+<span id="cb40-5"><a href="#cb40-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
 <section id="sec-self-arg" class="level3" data-number="2.3.3">
@@ -772,34 +776,34 @@ <h3 data-number="2.3.3" class="anchored" data-anchor-id="sec-self-arg"><span cla
 <p>It is not mandatory to use this <code>self</code> argument. But why would you not use this <code>self</code> argument? There is no reason to not use it. Because the only way to get access to the data stored in the data members of your struct is to access them through this <code>self</code> argument. If you don’t need to use the data in the data members of your struct inside your method, you very likely don’t need a method. You can just declare this logic as a simple function, outside of your struct declaration.</p>
 <p>Take the <code>Vec3</code> struct below. Inside this <code>Vec3</code> struct we declared a method named <code>distance()</code>. This method calculates the distance between two <code>Vec3</code> objects, by following the distance formula in euclidean space. Notice that this <code>distance()</code> method takes two <code>Vec3</code> objects as input, <code>self</code> and <code>other</code>.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb40"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb40-1"><a href="#cb40-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb40-2"><a href="#cb40-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> m = std.math;</span>
-<span id="cb40-3"><a href="#cb40-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Vec3 = <span class="kw">struct</span> <span class="op">{</span></span>
-<span id="cb40-4"><a href="#cb40-4" aria-hidden="true" tabindex="-1"></a>    x: <span class="dt">f64</span>,</span>
-<span id="cb40-5"><a href="#cb40-5" aria-hidden="true" tabindex="-1"></a>    y: <span class="dt">f64</span>,</span>
-<span id="cb40-6"><a href="#cb40-6" aria-hidden="true" tabindex="-1"></a>    z: <span class="dt">f64</span>,</span>
-<span id="cb40-7"><a href="#cb40-7" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb40-8"><a href="#cb40-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> distance(self: Vec3, other: Vec3) <span class="dt">f64</span> <span class="op">{</span></span>
-<span id="cb40-9"><a href="#cb40-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> xd = m.pow(<span class="dt">f64</span>, self.x - other.x, <span class="fl">2.0</span>);</span>
-<span id="cb40-10"><a href="#cb40-10" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> yd = m.pow(<span class="dt">f64</span>, self.y - other.y, <span class="fl">2.0</span>);</span>
-<span id="cb40-11"><a href="#cb40-11" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> zd = m.pow(<span class="dt">f64</span>, self.z - other.z, <span class="fl">2.0</span>);</span>
-<span id="cb40-12"><a href="#cb40-12" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> m.sqrt(xd + yd + zd);</span>
-<span id="cb40-13"><a href="#cb40-13" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb40-14"><a href="#cb40-14" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb41"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb41-1"><a href="#cb41-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb41-2"><a href="#cb41-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> m = std.math;</span>
+<span id="cb41-3"><a href="#cb41-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Vec3 = <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb41-4"><a href="#cb41-4" aria-hidden="true" tabindex="-1"></a>    x: <span class="dt">f64</span>,</span>
+<span id="cb41-5"><a href="#cb41-5" aria-hidden="true" tabindex="-1"></a>    y: <span class="dt">f64</span>,</span>
+<span id="cb41-6"><a href="#cb41-6" aria-hidden="true" tabindex="-1"></a>    z: <span class="dt">f64</span>,</span>
+<span id="cb41-7"><a href="#cb41-7" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb41-8"><a href="#cb41-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> distance(self: Vec3, other: Vec3) <span class="dt">f64</span> <span class="op">{</span></span>
+<span id="cb41-9"><a href="#cb41-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> xd = m.pow(<span class="dt">f64</span>, self.x - other.x, <span class="fl">2.0</span>);</span>
+<span id="cb41-10"><a href="#cb41-10" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> yd = m.pow(<span class="dt">f64</span>, self.y - other.y, <span class="fl">2.0</span>);</span>
+<span id="cb41-11"><a href="#cb41-11" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> zd = m.pow(<span class="dt">f64</span>, self.z - other.z, <span class="fl">2.0</span>);</span>
+<span id="cb41-12"><a href="#cb41-12" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> m.sqrt(xd + yd + zd);</span>
+<span id="cb41-13"><a href="#cb41-13" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb41-14"><a href="#cb41-14" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>The <code>self</code> argument corresponds to the <code>Vec3</code> object from which this <code>distance()</code> method is being called from. While the <code>other</code> is a separate <code>Vec3</code> object that is given as input to this method. In the example below, the <code>self</code> argument corresponds to the object <code>v1</code>, because the <code>distance()</code> method is being called from the <code>v1</code> object, while the <code>other</code> argument corresponds to the object <code>v2</code>.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb41"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb41-1"><a href="#cb41-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> v1 = Vec3 <span class="op">{</span></span>
-<span id="cb41-2"><a href="#cb41-2" aria-hidden="true" tabindex="-1"></a>    .x = <span class="fl">4.2</span>, .y = <span class="fl">2.4</span>, .z = <span class="fl">0.9</span></span>
-<span id="cb41-3"><a href="#cb41-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
-<span id="cb41-4"><a href="#cb41-4" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> v2 = Vec3 <span class="op">{</span></span>
-<span id="cb41-5"><a href="#cb41-5" aria-hidden="true" tabindex="-1"></a>    .x = <span class="fl">5.1</span>, .y = <span class="fl">5.6</span>, .z = <span class="fl">1.6</span></span>
-<span id="cb41-6"><a href="#cb41-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
-<span id="cb41-7"><a href="#cb41-7" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb41-8"><a href="#cb41-8" aria-hidden="true" tabindex="-1"></a>std.debug.print(</span>
-<span id="cb41-9"><a href="#cb41-9" aria-hidden="true" tabindex="-1"></a>    <span class="st">"Distance: {d}</span><span class="sc">\n</span><span class="st">"</span>,</span>
-<span id="cb41-10"><a href="#cb41-10" aria-hidden="true" tabindex="-1"></a>    .<span class="op">{</span>v1.distance(v2)<span class="op">}</span></span>
-<span id="cb41-11"><a href="#cb41-11" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb42"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb42-1"><a href="#cb42-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> v1 = Vec3 <span class="op">{</span></span>
+<span id="cb42-2"><a href="#cb42-2" aria-hidden="true" tabindex="-1"></a>    .x = <span class="fl">4.2</span>, .y = <span class="fl">2.4</span>, .z = <span class="fl">0.9</span></span>
+<span id="cb42-3"><a href="#cb42-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
+<span id="cb42-4"><a href="#cb42-4" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> v2 = Vec3 <span class="op">{</span></span>
+<span id="cb42-5"><a href="#cb42-5" aria-hidden="true" tabindex="-1"></a>    .x = <span class="fl">5.1</span>, .y = <span class="fl">5.6</span>, .z = <span class="fl">1.6</span></span>
+<span id="cb42-6"><a href="#cb42-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
+<span id="cb42-7"><a href="#cb42-7" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb42-8"><a href="#cb42-8" aria-hidden="true" tabindex="-1"></a>std.debug.print(</span>
+<span id="cb42-9"><a href="#cb42-9" aria-hidden="true" tabindex="-1"></a>    <span class="st">"Distance: {d}</span><span class="sc">\n</span><span class="st">"</span>,</span>
+<span id="cb42-10"><a href="#cb42-10" aria-hidden="true" tabindex="-1"></a>    .<span class="op">{</span>v1.distance(v2)<span class="op">}</span></span>
+<span id="cb42-11"><a href="#cb42-11" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Distance: 3.3970575502926055</code></pre>
 </section>
@@ -814,40 +818,40 @@ <h3 data-number="2.3.4" class="anchored" data-anchor-id="about-the-struct-state"
 <p>But what if we do have a method that alters the state of the object, by altering the values of its data members, how should we annotate <code>self</code> in this instance? The answer is: “we should annotate <code>self</code> as a pointer of <code>x</code>, instead of just <code>x</code>”. In other words, you should annotate <code>self</code> as <code>self: *x</code>, instead of annotating it as <code>self: x</code>.</p>
 <p>If we create a new method inside the <code>Vec3</code> object that, for example, expands the vector by multiplying its coordinates by a factor of two, then, we need to follow this rule specified in the previous paragraph. The code example below demonstrates this idea:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb43"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb43-1"><a href="#cb43-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb43-2"><a href="#cb43-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> m = std.math;</span>
-<span id="cb43-3"><a href="#cb43-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Vec3 = <span class="kw">struct</span> <span class="op">{</span></span>
-<span id="cb43-4"><a href="#cb43-4" aria-hidden="true" tabindex="-1"></a>    x: <span class="dt">f64</span>,</span>
-<span id="cb43-5"><a href="#cb43-5" aria-hidden="true" tabindex="-1"></a>    y: <span class="dt">f64</span>,</span>
-<span id="cb43-6"><a href="#cb43-6" aria-hidden="true" tabindex="-1"></a>    z: <span class="dt">f64</span>,</span>
-<span id="cb43-7"><a href="#cb43-7" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb43-8"><a href="#cb43-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> distance(self: Vec3, other: Vec3) <span class="dt">f64</span> <span class="op">{</span></span>
-<span id="cb43-9"><a href="#cb43-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> xd = m.pow(<span class="dt">f64</span>, self.x - other.x, <span class="fl">2.0</span>);</span>
-<span id="cb43-10"><a href="#cb43-10" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> yd = m.pow(<span class="dt">f64</span>, self.y - other.y, <span class="fl">2.0</span>);</span>
-<span id="cb43-11"><a href="#cb43-11" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> zd = m.pow(<span class="dt">f64</span>, self.z - other.z, <span class="fl">2.0</span>);</span>
-<span id="cb43-12"><a href="#cb43-12" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> m.sqrt(xd + yd + zd);</span>
-<span id="cb43-13"><a href="#cb43-13" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb43-14"><a href="#cb43-14" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb43-15"><a href="#cb43-15" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> twice(self: *Vec3) <span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb43-16"><a href="#cb43-16" aria-hidden="true" tabindex="-1"></a>        self.x = self.x * <span class="fl">2.0</span>;</span>
-<span id="cb43-17"><a href="#cb43-17" aria-hidden="true" tabindex="-1"></a>        self.y = self.y * <span class="fl">2.0</span>;</span>
-<span id="cb43-18"><a href="#cb43-18" aria-hidden="true" tabindex="-1"></a>        self.z = self.z * <span class="fl">2.0</span>;</span>
-<span id="cb43-19"><a href="#cb43-19" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb43-20"><a href="#cb43-20" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb44"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb44-1"><a href="#cb44-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb44-2"><a href="#cb44-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> m = std.math;</span>
+<span id="cb44-3"><a href="#cb44-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Vec3 = <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb44-4"><a href="#cb44-4" aria-hidden="true" tabindex="-1"></a>    x: <span class="dt">f64</span>,</span>
+<span id="cb44-5"><a href="#cb44-5" aria-hidden="true" tabindex="-1"></a>    y: <span class="dt">f64</span>,</span>
+<span id="cb44-6"><a href="#cb44-6" aria-hidden="true" tabindex="-1"></a>    z: <span class="dt">f64</span>,</span>
+<span id="cb44-7"><a href="#cb44-7" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb44-8"><a href="#cb44-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> distance(self: Vec3, other: Vec3) <span class="dt">f64</span> <span class="op">{</span></span>
+<span id="cb44-9"><a href="#cb44-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> xd = m.pow(<span class="dt">f64</span>, self.x - other.x, <span class="fl">2.0</span>);</span>
+<span id="cb44-10"><a href="#cb44-10" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> yd = m.pow(<span class="dt">f64</span>, self.y - other.y, <span class="fl">2.0</span>);</span>
+<span id="cb44-11"><a href="#cb44-11" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> zd = m.pow(<span class="dt">f64</span>, self.z - other.z, <span class="fl">2.0</span>);</span>
+<span id="cb44-12"><a href="#cb44-12" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> m.sqrt(xd + yd + zd);</span>
+<span id="cb44-13"><a href="#cb44-13" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb44-14"><a href="#cb44-14" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb44-15"><a href="#cb44-15" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> twice(self: *Vec3) <span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb44-16"><a href="#cb44-16" aria-hidden="true" tabindex="-1"></a>        self.x = self.x * <span class="fl">2.0</span>;</span>
+<span id="cb44-17"><a href="#cb44-17" aria-hidden="true" tabindex="-1"></a>        self.y = self.y * <span class="fl">2.0</span>;</span>
+<span id="cb44-18"><a href="#cb44-18" aria-hidden="true" tabindex="-1"></a>        self.z = self.z * <span class="fl">2.0</span>;</span>
+<span id="cb44-19"><a href="#cb44-19" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb44-20"><a href="#cb44-20" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>Notice in the code example above that we have added a new method to our <code>Vec3</code> struct named <code>twice()</code>. This method doubles the coordinate values of our vector object. In the case of the <code>twice()</code> method, we annotated the <code>self</code> argument as <code>*Vec3</code>, indicating that this argument receives a pointer (or a reference, if you prefer to call it this way) to a <code>Vec3</code> object as input.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb44"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb44-1"><a href="#cb44-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> v3 = Vec3 <span class="op">{</span></span>
-<span id="cb44-2"><a href="#cb44-2" aria-hidden="true" tabindex="-1"></a>    .x = <span class="fl">4.2</span>, .y = <span class="fl">2.4</span>, .z = <span class="fl">0.9</span></span>
-<span id="cb44-3"><a href="#cb44-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
-<span id="cb44-4"><a href="#cb44-4" aria-hidden="true" tabindex="-1"></a>v3.twice();</span>
-<span id="cb44-5"><a href="#cb44-5" aria-hidden="true" tabindex="-1"></a>std.debug.print(<span class="st">"Doubled: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>v3.x<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb45"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb45-1"><a href="#cb45-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> v3 = Vec3 <span class="op">{</span></span>
+<span id="cb45-2"><a href="#cb45-2" aria-hidden="true" tabindex="-1"></a>    .x = <span class="fl">4.2</span>, .y = <span class="fl">2.4</span>, .z = <span class="fl">0.9</span></span>
+<span id="cb45-3"><a href="#cb45-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
+<span id="cb45-4"><a href="#cb45-4" aria-hidden="true" tabindex="-1"></a>v3.twice();</span>
+<span id="cb45-5"><a href="#cb45-5" aria-hidden="true" tabindex="-1"></a>std.debug.print(<span class="st">"Doubled: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>v3.x<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Doubled: 8.4</code></pre>
 <p>Now, if you change the <code>self</code> argument in this <code>twice()</code> method to <code>self: Vec3</code>, like in the <code>distance()</code> method, you will get the compiler error exposed below as result. Notice that this error message is showing a line from the <code>twice()</code> method body, indicating that you cannot alter the value of the <code>x</code> data member.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb46"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb46-1"><a href="#cb46-1" aria-hidden="true" tabindex="-1"></a><span class="co">// If we change the function signature of double to:</span></span>
-<span id="cb46-2"><a href="#cb46-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> twice(self: Vec3) <span class="dt">void</span> <span class="op">{</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb47"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb47-1"><a href="#cb47-1" aria-hidden="true" tabindex="-1"></a><span class="co">// If we change the function signature of double to:</span></span>
+<span id="cb47-2"><a href="#cb47-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> twice(self: Vec3) <span class="dt">void</span> <span class="op">{</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>t.zig:16:13: error: cannot assign to constant
         self.x = self.x * 2.0;
@@ -884,31 +888,31 @@ <h2 data-number="2.4" class="anchored" data-anchor-id="sec-type-inference"><span
 <p>Because these weird values contain a dot character before them, we are asking the <code>zig</code> compiler to infer the types of these values inside the switch statement. Then, the <code>zig</code> compiler is looking into the current context where these values are being used, and it is trying to infer the types of these values.</p>
 <p>Since they are being used inside a switch statement, the <code>zig</code> compiler looks into the type of the input object given to the switch statement, which is the <code>order</code> object in this case. Because this object have type <code>AtomicOrder</code>, the <code>zig</code> compiler infers that these values are data members from this type <code>AtomicOrder</code>.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb48"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb48-1"><a href="#cb48-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">inline</span> <span class="kw">fn</span> fence(self: *Self, <span class="kw">comptime</span> order: AtomicOrder) <span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb48-2"><a href="#cb48-2" aria-hidden="true" tabindex="-1"></a>    <span class="co">// many lines of code ...</span></span>
-<span id="cb48-3"><a href="#cb48-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> (builtin.sanitize_thread) <span class="op">{</span></span>
-<span id="cb48-4"><a href="#cb48-4" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> tsan = <span class="kw">struct</span> <span class="op">{</span></span>
-<span id="cb48-5"><a href="#cb48-5" aria-hidden="true" tabindex="-1"></a>            <span class="kw">extern</span> <span class="st">"c"</span> <span class="kw">fn</span> __tsan_acquire(addr: *anyopaque) <span class="dt">void</span>;</span>
-<span id="cb48-6"><a href="#cb48-6" aria-hidden="true" tabindex="-1"></a>            <span class="kw">extern</span> <span class="st">"c"</span> <span class="kw">fn</span> __tsan_release(addr: *anyopaque) <span class="dt">void</span>;</span>
-<span id="cb48-7"><a href="#cb48-7" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span>;</span>
-<span id="cb48-8"><a href="#cb48-8" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb48-9"><a href="#cb48-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> addr: *anyopaque = self;</span>
-<span id="cb48-10"><a href="#cb48-10" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> <span class="kw">switch</span> (order) <span class="op">{</span></span>
-<span id="cb48-11"><a href="#cb48-11" aria-hidden="true" tabindex="-1"></a>            .unordered, .monotonic =&gt; <span class="bu">@compileError</span>(</span>
-<span id="cb48-12"><a href="#cb48-12" aria-hidden="true" tabindex="-1"></a>                <span class="bu">@tagName</span>(order)</span>
-<span id="cb48-13"><a href="#cb48-13" aria-hidden="true" tabindex="-1"></a>                ++ <span class="st">" only applies to atomic loads and stores"</span></span>
-<span id="cb48-14"><a href="#cb48-14" aria-hidden="true" tabindex="-1"></a>            ),</span>
-<span id="cb48-15"><a href="#cb48-15" aria-hidden="true" tabindex="-1"></a>            .acquire =&gt; tsan.__tsan_acquire(addr),</span>
-<span id="cb48-16"><a href="#cb48-16" aria-hidden="true" tabindex="-1"></a>            .release =&gt; tsan.__tsan_release(addr),</span>
-<span id="cb48-17"><a href="#cb48-17" aria-hidden="true" tabindex="-1"></a>            .acq_rel, .seq_cst =&gt; <span class="op">{</span></span>
-<span id="cb48-18"><a href="#cb48-18" aria-hidden="true" tabindex="-1"></a>                tsan.__tsan_acquire(addr);</span>
-<span id="cb48-19"><a href="#cb48-19" aria-hidden="true" tabindex="-1"></a>                tsan.__tsan_release(addr);</span>
-<span id="cb48-20"><a href="#cb48-20" aria-hidden="true" tabindex="-1"></a>            <span class="op">}</span>,</span>
-<span id="cb48-21"><a href="#cb48-21" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span>;</span>
-<span id="cb48-22"><a href="#cb48-22" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb48-23"><a href="#cb48-23" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb48-24"><a href="#cb48-24" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> <span class="bu">@fence</span>(order);</span>
-<span id="cb48-25"><a href="#cb48-25" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb49"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb49-1"><a href="#cb49-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">inline</span> <span class="kw">fn</span> fence(self: *Self, <span class="kw">comptime</span> order: AtomicOrder) <span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb49-2"><a href="#cb49-2" aria-hidden="true" tabindex="-1"></a>    <span class="co">// many lines of code ...</span></span>
+<span id="cb49-3"><a href="#cb49-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> (builtin.sanitize_thread) <span class="op">{</span></span>
+<span id="cb49-4"><a href="#cb49-4" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> tsan = <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb49-5"><a href="#cb49-5" aria-hidden="true" tabindex="-1"></a>            <span class="kw">extern</span> <span class="st">"c"</span> <span class="kw">fn</span> __tsan_acquire(addr: *anyopaque) <span class="dt">void</span>;</span>
+<span id="cb49-6"><a href="#cb49-6" aria-hidden="true" tabindex="-1"></a>            <span class="kw">extern</span> <span class="st">"c"</span> <span class="kw">fn</span> __tsan_release(addr: *anyopaque) <span class="dt">void</span>;</span>
+<span id="cb49-7"><a href="#cb49-7" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span>;</span>
+<span id="cb49-8"><a href="#cb49-8" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb49-9"><a href="#cb49-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> addr: *anyopaque = self;</span>
+<span id="cb49-10"><a href="#cb49-10" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> <span class="kw">switch</span> (order) <span class="op">{</span></span>
+<span id="cb49-11"><a href="#cb49-11" aria-hidden="true" tabindex="-1"></a>            .unordered, .monotonic =&gt; <span class="bu">@compileError</span>(</span>
+<span id="cb49-12"><a href="#cb49-12" aria-hidden="true" tabindex="-1"></a>                <span class="bu">@tagName</span>(order)</span>
+<span id="cb49-13"><a href="#cb49-13" aria-hidden="true" tabindex="-1"></a>                ++ <span class="st">" only applies to atomic loads and stores"</span></span>
+<span id="cb49-14"><a href="#cb49-14" aria-hidden="true" tabindex="-1"></a>            ),</span>
+<span id="cb49-15"><a href="#cb49-15" aria-hidden="true" tabindex="-1"></a>            .acquire =&gt; tsan.__tsan_acquire(addr),</span>
+<span id="cb49-16"><a href="#cb49-16" aria-hidden="true" tabindex="-1"></a>            .release =&gt; tsan.__tsan_release(addr),</span>
+<span id="cb49-17"><a href="#cb49-17" aria-hidden="true" tabindex="-1"></a>            .acq_rel, .seq_cst =&gt; <span class="op">{</span></span>
+<span id="cb49-18"><a href="#cb49-18" aria-hidden="true" tabindex="-1"></a>                tsan.__tsan_acquire(addr);</span>
+<span id="cb49-19"><a href="#cb49-19" aria-hidden="true" tabindex="-1"></a>                tsan.__tsan_release(addr);</span>
+<span id="cb49-20"><a href="#cb49-20" aria-hidden="true" tabindex="-1"></a>            <span class="op">}</span>,</span>
+<span id="cb49-21"><a href="#cb49-21" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span>;</span>
+<span id="cb49-22"><a href="#cb49-22" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb49-23"><a href="#cb49-23" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb49-24"><a href="#cb49-24" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> <span class="bu">@fence</span>(order);</span>
+<span id="cb49-25"><a href="#cb49-25" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>This is how basic type inference is done in Zig. If we didn’t use the dot character before the values inside this switch statement, then, we would be forced to explicitly write the data types of these values. For example, instead of writing <code>.release</code> we would have to write <code>AtomicOrder.release</code>. We would have to do this for every single value in this switch statement, and this is a lot of work. That is why type inference is commonly used on switch statements in Zig.</p>
 </section>
@@ -918,60 +922,71 @@ <h2 data-number="2.5" class="anchored" data-anchor-id="sec-type-cast"><span clas
 <p>Most languages have a formal way to perform type casting. In Rust for example, we normally use the keyword <code>as</code>, and in C, we normally use the type casting syntax, e.g.&nbsp;<code>(int) x</code>. In Zig, we use the <code>@as()</code> built-in function to cast an object of type “x”, into an object of type “y”.</p>
 <p>This <code>@as()</code> function is the preferred way to perform type conversion (or type casting) in Zig. Because it is explicit, and, it also performs the casting only if it is unambiguous and safe. To use this function, you just provide the target data type in the first argument, and, the object that you want cast as the second argument.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb49"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb49-1"><a href="#cb49-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb49-2"><a href="#cb49-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = std.testing.expect;</span>
-<span id="cb49-3"><a href="#cb49-3" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="op">{</span></span>
-<span id="cb49-4"><a href="#cb49-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> x: <span class="dt">usize</span> = <span class="dv">500</span>;</span>
-<span id="cb49-5"><a href="#cb49-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> y = <span class="bu">@as</span>(<span class="dt">u32</span>, x);</span>
-<span id="cb49-6"><a href="#cb49-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(y) == <span class="dt">u32</span>);</span>
-<span id="cb49-7"><a href="#cb49-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb50"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb50-1"><a href="#cb50-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb50-2"><a href="#cb50-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = std.testing.expect;</span>
+<span id="cb50-3"><a href="#cb50-3" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="op">{</span></span>
+<span id="cb50-4"><a href="#cb50-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> x: <span class="dt">usize</span> = <span class="dv">500</span>;</span>
+<span id="cb50-5"><a href="#cb50-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> y = <span class="bu">@as</span>(<span class="dt">u32</span>, x);</span>
+<span id="cb50-6"><a href="#cb50-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(y) == <span class="dt">u32</span>);</span>
+<span id="cb50-7"><a href="#cb50-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="cell-output cell-output-stdout">
+<pre><code>1/1 filefe9b6a29a64b.test_0...OKAll 1 tests passed
+  d.</code></pre>
+</div>
 </div>
 <p>This is the general way to perform type casting in Zig. But remember, <code>@as()</code> works only when casting is unambiguous and safe, and there are situations where these assumptions do not hold. For example, when casting an integer value into a float value, or vice-versa, it is not clear to the compiler how to perform this conversion safely.</p>
 <p>Therefore, we need to use specialized “casting functions” in such situations. For example, if you want to cast an integer value into a float value, then, you should use the <code>@floatFromInt()</code> function. In the inverse scenario, you should use the <code>@intFromFloat()</code> function.</p>
 <p>In these functions, you just provide the object that you want to cast as input. Then, the target data type of the “type casting operation” is determined by the type annotation of the object where you are saving the results. In the example below, we are casting the object <code>x</code> into a value of type <code>f32</code>, because the object <code>y</code>, which is where we are saving the results, is annotated as an object of type <code>f32</code>.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb50"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb50-1"><a href="#cb50-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb50-2"><a href="#cb50-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = std.testing.expect;</span>
-<span id="cb50-3"><a href="#cb50-3" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="op">{</span></span>
-<span id="cb50-4"><a href="#cb50-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> x: <span class="dt">usize</span> = <span class="dv">565</span>;</span>
-<span id="cb50-5"><a href="#cb50-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> y: <span class="dt">f32</span> = <span class="bu">@floatFromInt</span>(x);</span>
-<span id="cb50-6"><a href="#cb50-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(y) == <span class="dt">f32</span>);</span>
-<span id="cb50-7"><a href="#cb50-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb52"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb52-1"><a href="#cb52-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb52-2"><a href="#cb52-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = std.testing.expect;</span>
+<span id="cb52-3"><a href="#cb52-3" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="op">{</span></span>
+<span id="cb52-4"><a href="#cb52-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> x: <span class="dt">usize</span> = <span class="dv">565</span>;</span>
+<span id="cb52-5"><a href="#cb52-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> y: <span class="dt">f32</span> = <span class="bu">@floatFromInt</span>(x);</span>
+<span id="cb52-6"><a href="#cb52-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(y) == <span class="dt">f32</span>);</span>
+<span id="cb52-7"><a href="#cb52-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="cell-output cell-output-stdout">
+<pre><code>1/1 filefe9b126af3c3.test_0...OKAll 1 tests passed
+  d.</code></pre>
+</div>
 </div>
 <p>Another built-in function that is very useful when performing type casting operations is <code>@ptrCast()</code>. In essence, we use the <code>@as()</code> built-in function when we want to explicit convert (or cast) a Zig value/object from a type “x” to a type “y”, etc. However, pointers (we are going to discuss pointers in more depth in <a href="05-pointers.html" class="quarto-xref"><span>Chapter 6</span></a>) are a special type of object in Zig, i.e.&nbsp;they are treated differently from “normal objects”.</p>
 <p>Everytime a pointer is involved in some “type casting operation” in Zig, the <code>@ptrCast()</code> function is used. This function works similarly to <code>@floatFromInt()</code>. You just provide the pointer object that you want to cast as input to this function, and the target data type is, once again, determined by the type annotation of the object where the results are being stored.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb51"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb51-1"><a href="#cb51-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb51-2"><a href="#cb51-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = std.testing.expect;</span>
-<span id="cb51-3"><a href="#cb51-3" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="op">{</span></span>
-<span id="cb51-4"><a href="#cb51-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> bytes <span class="kw">align</span>(<span class="bu">@alignOf</span>(<span class="dt">u32</span>)) = [_]<span class="dt">u8</span><span class="op">{</span></span>
-<span id="cb51-5"><a href="#cb51-5" aria-hidden="true" tabindex="-1"></a>        <span class="bn">0x12</span>, <span class="bn">0x12</span>, <span class="bn">0x12</span>, <span class="bn">0x12</span></span>
-<span id="cb51-6"><a href="#cb51-6" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>;</span>
-<span id="cb51-7"><a href="#cb51-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> u32_ptr: *<span class="kw">const</span> <span class="dt">u32</span> = <span class="bu">@ptrCast</span>(&amp;bytes);</span>
-<span id="cb51-8"><a href="#cb51-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(u32_ptr) == *<span class="kw">const</span> <span class="dt">u32</span>);</span>
-<span id="cb51-9"><a href="#cb51-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb54"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb54-1"><a href="#cb54-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb54-2"><a href="#cb54-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = std.testing.expect;</span>
+<span id="cb54-3"><a href="#cb54-3" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="op">{</span></span>
+<span id="cb54-4"><a href="#cb54-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> bytes <span class="kw">align</span>(<span class="bu">@alignOf</span>(<span class="dt">u32</span>)) = [_]<span class="dt">u8</span><span class="op">{</span></span>
+<span id="cb54-5"><a href="#cb54-5" aria-hidden="true" tabindex="-1"></a>        <span class="bn">0x12</span>, <span class="bn">0x12</span>, <span class="bn">0x12</span>, <span class="bn">0x12</span></span>
+<span id="cb54-6"><a href="#cb54-6" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>;</span>
+<span id="cb54-7"><a href="#cb54-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> u32_ptr: *<span class="kw">const</span> <span class="dt">u32</span> = <span class="bu">@ptrCast</span>(&amp;bytes);</span>
+<span id="cb54-8"><a href="#cb54-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(u32_ptr) == *<span class="kw">const</span> <span class="dt">u32</span>);</span>
+<span id="cb54-9"><a href="#cb54-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="cell-output cell-output-stdout">
+<pre><code>1/1 filefe9b7366fb7.test_0...OKAll 1 tests passed.</code></pre>
+</div>
 </div>
 </section>
 <section id="modules" class="level2" data-number="2.6">
 <h2 data-number="2.6" class="anchored" data-anchor-id="modules"><span class="header-section-number">2.6</span> Modules</h2>
 <p>We already talked about what modules are, and also, how to import other modules into your current module via <em>import statements</em>. Every Zig module (i.e.&nbsp;a <code>.zig</code> file) that you write in your project is internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the Zig Standard Library into our current module.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb52"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb52-1"><a href="#cb52-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb56"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb56-1"><a href="#cb56-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>When we want to access the functions and objects from the standard library, we are basically accessing the data members of the struct stored in the <code>std</code> object. That is why we use the same syntax that we use in normal structs, with the dot operator (<code>.</code>) to access the data members and methods of the struct.</p>
 <p>When this “import statement” get’s executed, the result of this expression is a struct object that contains the Zig Standard Library modules, global variables, functions, etc. And this struct object get’s saved (or stored) inside the constant object named <code>std</code>.</p>
 <p>Take the <a href="https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig"><code>thread_pool.zig</code> module from the project <code>zap</code></a><a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a> as an example. This module is written as if it was a big struct. That is why we have a top-level and public <code>init()</code> method written in this module. The idea is that all top-level functions written in this module are methods from the struct, and all top-level objects and struct declarations are data members of this struct. The module is the struct itself.</p>
 <p>So you would import and use this module by doing something like this:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb53"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb53-1"><a href="#cb53-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb53-2"><a href="#cb53-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ThreadPool = <span class="bu">@import</span>(<span class="st">"thread_pool.zig"</span>);</span>
-<span id="cb53-3"><a href="#cb53-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> num_cpus = std.Thread.getCpuCount()</span>
-<span id="cb53-4"><a href="#cb53-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">catch</span> <span class="bu">@panic</span>(<span class="st">"failed to get cpu core count"</span>);</span>
-<span id="cb53-5"><a href="#cb53-5" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> num_threads = std.math.cast(<span class="dt">u16</span>, num_cpus)</span>
-<span id="cb53-6"><a href="#cb53-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">catch</span> std.math.maxInt(<span class="dt">u16</span>);</span>
-<span id="cb53-7"><a href="#cb53-7" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> pool = ThreadPool.init(</span>
-<span id="cb53-8"><a href="#cb53-8" aria-hidden="true" tabindex="-1"></a>    .<span class="op">{</span> .max_threads = num_threads <span class="op">}</span></span>
-<span id="cb53-9"><a href="#cb53-9" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb57"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb57-1"><a href="#cb57-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb57-2"><a href="#cb57-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ThreadPool = <span class="bu">@import</span>(<span class="st">"thread_pool.zig"</span>);</span>
+<span id="cb57-3"><a href="#cb57-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> num_cpus = std.Thread.getCpuCount()</span>
+<span id="cb57-4"><a href="#cb57-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">catch</span> <span class="bu">@panic</span>(<span class="st">"failed to get cpu core count"</span>);</span>
+<span id="cb57-5"><a href="#cb57-5" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> num_threads = std.math.cast(<span class="dt">u16</span>, num_cpus)</span>
+<span id="cb57-6"><a href="#cb57-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">catch</span> std.math.maxInt(<span class="dt">u16</span>);</span>
+<span id="cb57-7"><a href="#cb57-7" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> pool = ThreadPool.init(</span>
+<span id="cb57-8"><a href="#cb57-8" aria-hidden="true" tabindex="-1"></a>    .<span class="op">{</span> .max_threads = num_threads <span class="op">}</span></span>
+<span id="cb57-9"><a href="#cb57-9" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 
 
diff --git a/docs/Chapters/03-unittests.html b/docs/Chapters/03-unittests.html
index 8abbb454..0d3e2651 100644
--- a/docs/Chapters/03-unittests.html
+++ b/docs/Chapters/03-unittests.html
@@ -322,6 +322,10 @@ <h2 data-number="8.1" class="anchored" data-anchor-id="introducing-the-test-bloc
 <span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> b: <span class="dt">u8</span> = <span class="dv">2</span>;</span>
 <span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect((a + b) == <span class="dv">4</span>);</span>
 <span id="cb1-7"><a href="#cb1-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="cell-output cell-output-stdout">
+<pre><code>1/1 file103bc24525048.test.testing simple sum...OK
+  KAll 1 tests passed.</code></pre>
+</div>
 </div>
 <p>You can have multiple <code>test</code> blocks written on the same Zig module. Also, you can mix <code>test</code> blocks with your source code, with no problems or consequences. If you mix <code>test</code> blocks with your normal source code, when you execute the <code>build</code>, <code>build-exe</code>, <code>build-obj</code> or <code>build-lib</code> commands from the <code>zig</code> compiler that we exposed at <a href="01-zig-weird.html#sec-compile-code" class="quarto-xref"><span>Section 1.2.4</span></a>, these <code>test</code> blocks are automatically ignored by the compiler.</p>
 <p>In other words, the <code>zig</code> compiler builds and execute your unit tests only when you ask it to. By default, the compiler always ignore <code>test</code> blocks written in your Zig modules. The compiler normally checks only if there are any syntax errors in these <code>test</code> blocks.</p>
@@ -331,7 +335,7 @@ <h2 data-number="8.1" class="anchored" data-anchor-id="introducing-the-test-bloc
 <section id="how-to-run-your-tests" class="level2" data-number="8.2">
 <h2 data-number="8.2" class="anchored" data-anchor-id="how-to-run-your-tests"><span class="header-section-number">8.2</span> How to run your tests</h2>
 <p>If the <code>zig</code> compiler ignores any <code>test</code> block by default, how can you compile and run your unit tests? The answer is the <code>test</code> command from the <code>zig</code> compiler. By running the <code>zig test</code> command, the compiler will find every instance of a <code>test</code> block in your Zig modules, and, it will compile and run the unit tests that you wrote.</p>
-<div class="sourceCode" id="cb2"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zig</span> test simple_sum.zig</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode" id="cb3"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zig</span> test simple_sum.zig</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <pre><code>1/1 simple_sum.test.testing simple sum... OK
 All 1 tests passed.</code></pre>
 </section>
@@ -344,19 +348,19 @@ <h2 data-number="8.3" class="anchored" data-anchor-id="testing-memory-allocation
 <p>Look at the example below, where I’m defining a function that clearly causes a memory leak. Because we allocate memory, but, at the same time, we do not free this allocated memory at any point. So, when the function returns, we lose the reference to the <code>buffer</code> object, which contains the allocated memory, and, as a result, we can no longer free this memory.</p>
 <p>Notice that, inside a <code>test</code> block I execute this function with the <code>std.testing.allocator</code>. The allocator object was capable of looking deeper in our program, and detecting the memory leak. As a result, this allocator object returns an error message of “memory leaked”, and also, a stack trace showing the exact point where the memory was leaked.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb4"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Allocator = std.mem.Allocator;</span>
-<span id="cb4-3"><a href="#cb4-3" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> some_memory_leak(allocator: Allocator) !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb4-4"><a href="#cb4-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> buffer = <span class="kw">try</span> allocator.alloc(<span class="dt">u32</span>, <span class="dv">10</span>);</span>
-<span id="cb4-5"><a href="#cb4-5" aria-hidden="true" tabindex="-1"></a>    _ = buffer;</span>
-<span id="cb4-6"><a href="#cb4-6" aria-hidden="true" tabindex="-1"></a>    <span class="co">// Return without freeing the</span></span>
-<span id="cb4-7"><a href="#cb4-7" aria-hidden="true" tabindex="-1"></a>    <span class="co">// allocated memory</span></span>
-<span id="cb4-8"><a href="#cb4-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
-<span id="cb4-9"><a href="#cb4-9" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb4-10"><a href="#cb4-10" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="st">"memory leak"</span> <span class="op">{</span></span>
-<span id="cb4-11"><a href="#cb4-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> allocator = std.testing.allocator;</span>
-<span id="cb4-12"><a href="#cb4-12" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> some_memory_leak(allocator);</span>
-<span id="cb4-13"><a href="#cb4-13" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb5"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Allocator = std.mem.Allocator;</span>
+<span id="cb5-3"><a href="#cb5-3" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> some_memory_leak(allocator: Allocator) !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb5-4"><a href="#cb5-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> buffer = <span class="kw">try</span> allocator.alloc(<span class="dt">u32</span>, <span class="dv">10</span>);</span>
+<span id="cb5-5"><a href="#cb5-5" aria-hidden="true" tabindex="-1"></a>    _ = buffer;</span>
+<span id="cb5-6"><a href="#cb5-6" aria-hidden="true" tabindex="-1"></a>    <span class="co">// Return without freeing the</span></span>
+<span id="cb5-7"><a href="#cb5-7" aria-hidden="true" tabindex="-1"></a>    <span class="co">// allocated memory</span></span>
+<span id="cb5-8"><a href="#cb5-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
+<span id="cb5-9"><a href="#cb5-9" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb5-10"><a href="#cb5-10" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="st">"memory leak"</span> <span class="op">{</span></span>
+<span id="cb5-11"><a href="#cb5-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> allocator = std.testing.allocator;</span>
+<span id="cb5-12"><a href="#cb5-12" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> some_memory_leak(allocator);</span>
+<span id="cb5-13"><a href="#cb5-13" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Test [1/1] leak_memory.test.memory leak...
     [gpa] (err): memory address 0x7c1fddf39000 leaked: 
@@ -376,21 +380,25 @@ <h2 data-number="8.4" class="anchored" data-anchor-id="testing-errors"><span cla
 <p>The code example below demonstrates such type of unit test in Zig. Notice that, inside the function <code>alloc_error()</code> we are allocating 100 bytes of memory, or, an array of 100 elements, for the object <code>ibuffer</code>. However, in the <code>test</code> block, we are using the <code>FixedBufferAllocator()</code> allocator object, which is limited to 10 bytes of space, because the object <code>buffer</code>, which we provided to the allocator object, have only 10 bytes of space.</p>
 <p>That is why, the <code>alloc_error()</code> function raises an <code>OutOfMemory</code> error on this case. Because this function is trying to allocate more space than the allocator object allows. So, in essence, we are testing for a specific type of error, which is <code>OutOfMemory</code>. If the <code>alloc_error()</code> function returns any other type of error, then, the <code>expectError()</code> function would make the entire test fail.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb6"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb6-2"><a href="#cb6-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Allocator = std.mem.Allocator;</span>
-<span id="cb6-3"><a href="#cb6-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expectError = std.testing.expectError;</span>
-<span id="cb6-4"><a href="#cb6-4" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> alloc_error(allocator: Allocator) !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb6-5"><a href="#cb6-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> ibuffer = <span class="kw">try</span> allocator.alloc(<span class="dt">u8</span>, <span class="dv">100</span>);</span>
-<span id="cb6-6"><a href="#cb6-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">defer</span> allocator.free(ibuffer);</span>
-<span id="cb6-7"><a href="#cb6-7" aria-hidden="true" tabindex="-1"></a>    ibuffer[<span class="dv">0</span>] = <span class="dv">2</span>;</span>
-<span id="cb6-8"><a href="#cb6-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
-<span id="cb6-9"><a href="#cb6-9" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb6-10"><a href="#cb6-10" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="st">"testing error"</span> <span class="op">{</span></span>
-<span id="cb6-11"><a href="#cb6-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> buffer: [<span class="dv">10</span>]<span class="dt">u8</span> = <span class="cn">undefined</span>;</span>
-<span id="cb6-12"><a href="#cb6-12" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> fba = std.heap.FixedBufferAllocator.init(&amp;buffer);</span>
-<span id="cb6-13"><a href="#cb6-13" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> allocator = fba.allocator();</span>
-<span id="cb6-14"><a href="#cb6-14" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expectError(<span class="kw">error</span>.OutOfMemory, alloc_error(allocator));</span>
-<span id="cb6-15"><a href="#cb6-15" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb7"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb7-2"><a href="#cb7-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Allocator = std.mem.Allocator;</span>
+<span id="cb7-3"><a href="#cb7-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expectError = std.testing.expectError;</span>
+<span id="cb7-4"><a href="#cb7-4" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> alloc_error(allocator: Allocator) !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb7-5"><a href="#cb7-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> ibuffer = <span class="kw">try</span> allocator.alloc(<span class="dt">u8</span>, <span class="dv">100</span>);</span>
+<span id="cb7-6"><a href="#cb7-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">defer</span> allocator.free(ibuffer);</span>
+<span id="cb7-7"><a href="#cb7-7" aria-hidden="true" tabindex="-1"></a>    ibuffer[<span class="dv">0</span>] = <span class="dv">2</span>;</span>
+<span id="cb7-8"><a href="#cb7-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
+<span id="cb7-9"><a href="#cb7-9" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb7-10"><a href="#cb7-10" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="st">"testing error"</span> <span class="op">{</span></span>
+<span id="cb7-11"><a href="#cb7-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> buffer: [<span class="dv">10</span>]<span class="dt">u8</span> = <span class="cn">undefined</span>;</span>
+<span id="cb7-12"><a href="#cb7-12" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> fba = std.heap.FixedBufferAllocator.init(&amp;buffer);</span>
+<span id="cb7-13"><a href="#cb7-13" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> allocator = fba.allocator();</span>
+<span id="cb7-14"><a href="#cb7-14" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expectError(<span class="kw">error</span>.OutOfMemory, alloc_error(allocator));</span>
+<span id="cb7-15"><a href="#cb7-15" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="cell-output cell-output-stdout">
+<pre><code>1/1 file103bc545495c8.test.testing error...OKAll 1
+  1 tests passed.</code></pre>
+</div>
 </div>
 <pre><code>1/1 oom.test.testing error... OK
 All 1 tests passed.</code></pre>
@@ -401,12 +409,12 @@ <h2 data-number="8.5" class="anchored" data-anchor-id="testing-simple-equalities
 <p>The <code>expectEqual()</code> function, as the name suggests, is a classic test equality function. It receives two objects as input. The first object is the value that you expect to be in the second object. While second object is the object you have, or, the object that your application produced as result. So, with <code>expectEqual()</code> you are essentially testing if the values stored inside these two objects are equal or not.</p>
 <p>You can see in the example below that, the test performed by <code>expectEqual()</code> failed. Because the objects <code>v1</code> and <code>v2</code> contain different values in them.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb8"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb8-2"><a href="#cb8-2" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="st">"values are equal?"</span> <span class="op">{</span></span>
-<span id="cb8-3"><a href="#cb8-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> v1 = <span class="dv">15</span>;</span>
-<span id="cb8-4"><a href="#cb8-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> v2 = <span class="dv">18</span>;</span>
-<span id="cb8-5"><a href="#cb8-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> std.testing.expectEqual(v1, v2);</span>
-<span id="cb8-6"><a href="#cb8-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb10"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb10-2"><a href="#cb10-2" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="st">"values are equal?"</span> <span class="op">{</span></span>
+<span id="cb10-3"><a href="#cb10-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> v1 = <span class="dv">15</span>;</span>
+<span id="cb10-4"><a href="#cb10-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> v2 = <span class="dv">18</span>;</span>
+<span id="cb10-5"><a href="#cb10-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> std.testing.expectEqual(v1, v2);</span>
+<span id="cb10-6"><a href="#cb10-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>1/1 ve.test.values are equal?...
     expected 15, found 18
@@ -418,28 +426,32 @@ <h2 data-number="8.5" class="anchored" data-anchor-id="testing-simple-equalities
 <p>Although useful, the <code>expectEqual()</code> function does not work with arrays. For testing if two arrays are equal, you should use the <code>expectEqualSlices()</code> function instead. This function have three arguments. First, you provide the data type contained in both arrays that you are trying to compare. While the second and third arguments corresponds to the array objects that you want to compare.</p>
 <p>In the example below, we are using this function to test if two array objects (<code>array1</code> and <code>array2</code>) are equal or not. Since they are in fact equal, the unit test passed with no errors.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb10"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb10-2"><a href="#cb10-2" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="st">"arrays are equal?"</span> <span class="op">{</span></span>
-<span id="cb10-3"><a href="#cb10-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> array1 = [<span class="dv">3</span>]<span class="dt">u32</span><span class="op">{</span><span class="dv">1</span>, <span class="dv">2</span>, <span class="dv">3</span><span class="op">}</span>;</span>
-<span id="cb10-4"><a href="#cb10-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> array2 = [<span class="dv">3</span>]<span class="dt">u32</span><span class="op">{</span><span class="dv">1</span>, <span class="dv">2</span>, <span class="dv">3</span><span class="op">}</span>;</span>
-<span id="cb10-5"><a href="#cb10-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> std.testing.expectEqualSlices(</span>
-<span id="cb10-6"><a href="#cb10-6" aria-hidden="true" tabindex="-1"></a>        <span class="dt">u32</span>, &amp;array1, &amp;array2</span>
-<span id="cb10-7"><a href="#cb10-7" aria-hidden="true" tabindex="-1"></a>    );</span>
-<span id="cb10-8"><a href="#cb10-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb12"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb12-2"><a href="#cb12-2" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="st">"arrays are equal?"</span> <span class="op">{</span></span>
+<span id="cb12-3"><a href="#cb12-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> array1 = [<span class="dv">3</span>]<span class="dt">u32</span><span class="op">{</span><span class="dv">1</span>, <span class="dv">2</span>, <span class="dv">3</span><span class="op">}</span>;</span>
+<span id="cb12-4"><a href="#cb12-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> array2 = [<span class="dv">3</span>]<span class="dt">u32</span><span class="op">{</span><span class="dv">1</span>, <span class="dv">2</span>, <span class="dv">3</span><span class="op">}</span>;</span>
+<span id="cb12-5"><a href="#cb12-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> std.testing.expectEqualSlices(</span>
+<span id="cb12-6"><a href="#cb12-6" aria-hidden="true" tabindex="-1"></a>        <span class="dt">u32</span>, &amp;array1, &amp;array2</span>
+<span id="cb12-7"><a href="#cb12-7" aria-hidden="true" tabindex="-1"></a>    );</span>
+<span id="cb12-8"><a href="#cb12-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="cell-output cell-output-stdout">
+<pre><code>1/1 file103bc78cf09de.test.arrays are equal?...OKA
+  All 1 tests passed.</code></pre>
+</div>
 </div>
 <pre><code>1/1 oom.test.arrays are equal?... OK
 All 1 tests passed.</code></pre>
 <p>At last, you might also want to use the <code>expectEqualStrings()</code> function. As the name suggests, you can use this function to test if two strings are equal or not. Just provide the two string objects that you want to compare, as inputs to the function.</p>
 <p>If the function finds any existing differences between the two strings, then, the function will raise an error, and also, print an error message that shows the exact difference between the two string objects provided, as the example below demonstrates:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb12"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb12-2"><a href="#cb12-2" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="st">"strings are equal?"</span> <span class="op">{</span></span>
-<span id="cb12-3"><a href="#cb12-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> str1 = <span class="st">"hello, world!"</span>;</span>
-<span id="cb12-4"><a href="#cb12-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> str2 = <span class="st">"Hello, world!"</span>;</span>
-<span id="cb12-5"><a href="#cb12-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> std.testing.expectEqualStrings(</span>
-<span id="cb12-6"><a href="#cb12-6" aria-hidden="true" tabindex="-1"></a>        str1, str2</span>
-<span id="cb12-7"><a href="#cb12-7" aria-hidden="true" tabindex="-1"></a>    );</span>
-<span id="cb12-8"><a href="#cb12-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb15"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb15-1"><a href="#cb15-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb15-2"><a href="#cb15-2" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="st">"strings are equal?"</span> <span class="op">{</span></span>
+<span id="cb15-3"><a href="#cb15-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> str1 = <span class="st">"hello, world!"</span>;</span>
+<span id="cb15-4"><a href="#cb15-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> str2 = <span class="st">"Hello, world!"</span>;</span>
+<span id="cb15-5"><a href="#cb15-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> std.testing.expectEqualStrings(</span>
+<span id="cb15-6"><a href="#cb15-6" aria-hidden="true" tabindex="-1"></a>        str1, str2</span>
+<span id="cb15-7"><a href="#cb15-7" aria-hidden="true" tabindex="-1"></a>    );</span>
+<span id="cb15-8"><a href="#cb15-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>1/1 t.test.strings are equal?... 
 ====== expected this output: =========
diff --git a/docs/Chapters/05-pointers.html b/docs/Chapters/05-pointers.html
index 0949abf8..98ebe8b1 100644
--- a/docs/Chapters/05-pointers.html
+++ b/docs/Chapters/05-pointers.html
@@ -347,22 +347,25 @@ <h1 class="title"><span id="sec-pointer" class="quarto-section-identifier"><span
 <span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> pointer = &amp;number;</span>
 <span id="cb2-3"><a href="#cb2-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> doubled = <span class="dv">2</span> * pointer.*;</span>
 <span id="cb2-4"><a href="#cb2-4" aria-hidden="true" tabindex="-1"></a>std.debug.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>doubled<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="cell-output cell-output-stdout">
+<pre><code>10</code></pre>
+</div>
 </div>
 <pre><code>10</code></pre>
 <p>This syntax to dereference the pointer is nice. Because we can easily chain it with methods of the value pointed by the pointer. We can use the <code>User</code> struct that we have created at <a href="03-structs.html#sec-structs-and-oop" class="quarto-xref"><span>Section 2.3</span></a> as an example. If you comeback to that section, you will see that this struct have a method named <code>print_name()</code>.</p>
 <p>So, for example, if we have an user object, and a pointer that points to this user object, we can use the pointer to access this user object, and, at the same time, call the method <code>print_name()</code> on it, by chaining the dereference method (<code>*</code>) with the <code>print_name()</code> method. Like in the example below:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb4"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> u = User.init(<span class="dv">1</span>, <span class="st">"pedro"</span>, <span class="st">"email@gmail.com"</span>);</span>
-<span id="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> pointer = &amp;u;</span>
-<span id="cb4-3"><a href="#cb4-3" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> pointer.*.print_name();</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb5"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> u = User.init(<span class="dv">1</span>, <span class="st">"pedro"</span>, <span class="st">"email@gmail.com"</span>);</span>
+<span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> pointer = &amp;u;</span>
+<span id="cb5-3"><a href="#cb5-3" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> pointer.*.print_name();</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>pedro</code></pre>
 <p>We can also use pointers to effectively alter the value of an object. For example, I could use the <code>pointer</code> object to set the value of the object <code>number</code> to 6, like in the example below.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb6"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> number: <span class="dt">u8</span> = <span class="dv">5</span>;</span>
-<span id="cb6-2"><a href="#cb6-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> pointer = &amp;number;</span>
-<span id="cb6-3"><a href="#cb6-3" aria-hidden="true" tabindex="-1"></a>pointer.* = <span class="dv">6</span>;</span>
-<span id="cb6-4"><a href="#cb6-4" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>number<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb7"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> number: <span class="dt">u8</span> = <span class="dv">5</span>;</span>
+<span id="cb7-2"><a href="#cb7-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> pointer = &amp;number;</span>
+<span id="cb7-3"><a href="#cb7-3" aria-hidden="true" tabindex="-1"></a>pointer.* = <span class="dv">6</span>;</span>
+<span id="cb7-4"><a href="#cb7-4" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>number<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>6</code></pre>
 </div>
@@ -375,18 +378,18 @@ <h2 data-number="6.1" class="anchored" data-anchor-id="sec-pointer-var"><span cl
 <p>You can have a pointer that points to a constant object, or, a pointer that points to a variable object. But regardless of who this pointer is, a pointer <strong>must always respect the characteristics of the object that it points to</strong>. As a consequence, if the pointer points to a constant object, then, you cannot use this pointer to change the value that it points to. Because it points to a value that is constant. As we discussed at <a href="01-zig-weird.html#sec-assignments" class="quarto-xref"><span>Section 1.4</span></a>, you cannot change a value that is constant.</p>
 <p>For example, if I have a <code>number</code> object, which is constant, I cannot execute the expression below where I’m trying to change the value of <code>number</code> to 6 through the <code>pointer</code> object. As demonstrated below, when you try to do something like that, you get a compile time error:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb8"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> number = <span class="dv">5</span>;</span>
-<span id="cb8-2"><a href="#cb8-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> pointer = &amp;number;</span>
-<span id="cb8-3"><a href="#cb8-3" aria-hidden="true" tabindex="-1"></a>pointer.* = <span class="dv">6</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb9"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb9-1"><a href="#cb9-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> number = <span class="dv">5</span>;</span>
+<span id="cb9-2"><a href="#cb9-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> pointer = &amp;number;</span>
+<span id="cb9-3"><a href="#cb9-3" aria-hidden="true" tabindex="-1"></a>pointer.* = <span class="dv">6</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>p.zig:6:12: error: cannot assign to constant
     pointer.* = 6;</code></pre>
 <p>If I change the <code>number</code> object to be a variable object, by introducing the <code>var</code> keyword, then, I can successfully change the value of this object through a pointer, as demonstrated below:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb10"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> number: <span class="dt">u8</span> = <span class="dv">5</span>;</span>
-<span id="cb10-2"><a href="#cb10-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> pointer = &amp;number;</span>
-<span id="cb10-3"><a href="#cb10-3" aria-hidden="true" tabindex="-1"></a>pointer.* = <span class="dv">6</span>;</span>
-<span id="cb10-4"><a href="#cb10-4" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>number<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb11"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> number: <span class="dt">u8</span> = <span class="dv">5</span>;</span>
+<span id="cb11-2"><a href="#cb11-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> pointer = &amp;number;</span>
+<span id="cb11-3"><a href="#cb11-3" aria-hidden="true" tabindex="-1"></a>pointer.* = <span class="dv">6</span>;</span>
+<span id="cb11-4"><a href="#cb11-4" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>number<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>6</code></pre>
 </div>
@@ -397,12 +400,12 @@ <h2 data-number="6.1" class="anchored" data-anchor-id="sec-pointer-var"><span cl
 <p>Until this point, the <code>pointer</code> object was always constant, but what this means for us? What is the consequence of the <code>pointer</code> object being constant? The consequence is that we cannot change the pointer object, because it is constant. We can use the pointer object in multiple ways, but we cannot change the memory address that is inside this pointer object.</p>
 <p>However, if we mark the <code>pointer</code> object as a variable object, then, we can change the memory address pointed by this <code>pointer</code> object. The example below demonstrates that. Notice that the object pointed by the <code>pointer</code> object changes from <code>c1</code> to <code>c2</code>.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb12"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> c1: <span class="dt">u8</span> = <span class="dv">5</span>;</span>
-<span id="cb12-2"><a href="#cb12-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> c2: <span class="dt">u8</span> = <span class="dv">6</span>;</span>
-<span id="cb12-3"><a href="#cb12-3" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> pointer = &amp;c1;</span>
-<span id="cb12-4"><a href="#cb12-4" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>pointer.*<span class="op">}</span>);</span>
-<span id="cb12-5"><a href="#cb12-5" aria-hidden="true" tabindex="-1"></a>pointer = &amp;c2;</span>
-<span id="cb12-6"><a href="#cb12-6" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>pointer.*<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb13"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> c1: <span class="dt">u8</span> = <span class="dv">5</span>;</span>
+<span id="cb13-2"><a href="#cb13-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> c2: <span class="dt">u8</span> = <span class="dv">6</span>;</span>
+<span id="cb13-3"><a href="#cb13-3" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> pointer = &amp;c1;</span>
+<span id="cb13-4"><a href="#cb13-4" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>pointer.*<span class="op">}</span>);</span>
+<span id="cb13-5"><a href="#cb13-5" aria-hidden="true" tabindex="-1"></a>pointer = &amp;c2;</span>
+<span id="cb13-6"><a href="#cb13-6" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>pointer.*<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>5
 6</code></pre>
@@ -424,13 +427,13 @@ <h2 data-number="6.3" class="anchored" data-anchor-id="pointer-arithmetic"><span
 <p>Pointer arithmetic is available in Zig, and they work the same way they work in C. When you have a pointer that points to an array, the pointer usually points to the first element in the array, and you can use pointer arithmetic to advance this pointer and access the other elements in the array.</p>
 <p>Notice in the example below, that initially, the <code>ptr</code> object was pointing to the first element in the array <code>ar</code>. But then, I started to walk through the array, by advancing the pointer with simple pointer arithmetic.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb14"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ar = [_]<span class="dt">i32</span><span class="op">{</span><span class="dv">1</span>,<span class="dv">2</span>,<span class="dv">3</span>,<span class="dv">4</span><span class="op">}</span>;</span>
-<span id="cb14-2"><a href="#cb14-2" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> ptr = &amp;ar;</span>
-<span id="cb14-3"><a href="#cb14-3" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>ptr.*<span class="op">}</span>);</span>
-<span id="cb14-4"><a href="#cb14-4" aria-hidden="true" tabindex="-1"></a>ptr += <span class="dv">1</span>;</span>
-<span id="cb14-5"><a href="#cb14-5" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>ptr.*<span class="op">}</span>);</span>
-<span id="cb14-6"><a href="#cb14-6" aria-hidden="true" tabindex="-1"></a>ptr += <span class="dv">1</span>;</span>
-<span id="cb14-7"><a href="#cb14-7" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>ptr.*<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb15"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb15-1"><a href="#cb15-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ar = [_]<span class="dt">i32</span><span class="op">{</span><span class="dv">1</span>,<span class="dv">2</span>,<span class="dv">3</span>,<span class="dv">4</span><span class="op">}</span>;</span>
+<span id="cb15-2"><a href="#cb15-2" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> ptr = &amp;ar;</span>
+<span id="cb15-3"><a href="#cb15-3" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>ptr.*<span class="op">}</span>);</span>
+<span id="cb15-4"><a href="#cb15-4" aria-hidden="true" tabindex="-1"></a>ptr += <span class="dv">1</span>;</span>
+<span id="cb15-5"><a href="#cb15-5" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>ptr.*<span class="op">}</span>);</span>
+<span id="cb15-6"><a href="#cb15-6" aria-hidden="true" tabindex="-1"></a>ptr += <span class="dv">1</span>;</span>
+<span id="cb15-7"><a href="#cb15-7" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>ptr.*<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>1
 2
@@ -439,9 +442,9 @@ <h2 data-number="6.3" class="anchored" data-anchor-id="pointer-arithmetic"><span
 <p>Behind the hood, slices already are pointers, and they also come with the <code>len</code> property, which indicates how many elements are in the slice. This is good because the <code>zig</code> compiler can use it to check for potential buffer overflows, and other problems like that.</p>
 <p>Also, you don’t need to use pointer arithmetic to walk through the elements of a slice. You can simply use the <code>slice[index]</code> syntax to directly access any element you want in the slice. As I mentioned at <a href="01-zig-weird.html#sec-arrays" class="quarto-xref"><span>Section 1.6</span></a>, you can get a slice from an array by using a range selector inside brackets. In the example below, I’m creating a slice (<code>sl</code>) that covers the entire <code>ar</code> array. I can access any element of <code>ar</code> from this slice, and, the slice itself already is a pointer behind the hood.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb16"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ar = [_]<span class="dt">i32</span><span class="op">{</span><span class="dv">1</span>,<span class="dv">2</span>,<span class="dv">3</span>,<span class="dv">4</span><span class="op">}</span>;</span>
-<span id="cb16-2"><a href="#cb16-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> sl = ar[<span class="dv">0</span>..ar.len];</span>
-<span id="cb16-3"><a href="#cb16-3" aria-hidden="true" tabindex="-1"></a>_ = sl;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb17"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ar = [_]<span class="dt">i32</span><span class="op">{</span><span class="dv">1</span>,<span class="dv">2</span>,<span class="dv">3</span>,<span class="dv">4</span><span class="op">}</span>;</span>
+<span id="cb17-2"><a href="#cb17-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> sl = ar[<span class="dv">0</span>..ar.len];</span>
+<span id="cb17-3"><a href="#cb17-3" aria-hidden="true" tabindex="-1"></a>_ = sl;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
 <section id="optionals-and-optional-pointers" class="level2" data-number="6.4">
@@ -450,8 +453,8 @@ <h2 data-number="6.4" class="anchored" data-anchor-id="optionals-and-optional-po
 <p>This is a powerful feature of Zig when you compare it to the developer experience in C. Because in C, any object can be null at any point, and, as consequence, a pointer in C might point to a null value. This is a common source of undefined behaviour in C. When programmers work with pointers in C, they have to constantly check if their pointers are pointing to null values or not.</p>
 <p>If for some reason, your Zig code produces a null value somewhere, and, this null value ends up in an object that is non-nullable, a runtime error is always raised by your Zig program. Take the program below as an example. The <code>zig</code> compiler can see the <code>null</code> value at compile time, and, as result, it raises a compile time error. But, if a <code>null</code> value is raised during runtime, a runtime error is also raised by the Zig program, with a “attempt to use null value” message.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb17"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> number: <span class="dt">u8</span> = <span class="dv">5</span>;</span>
-<span id="cb17-2"><a href="#cb17-2" aria-hidden="true" tabindex="-1"></a>number = <span class="cn">null</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb18"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb18-1"><a href="#cb18-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> number: <span class="dt">u8</span> = <span class="dv">5</span>;</span>
+<span id="cb18-2"><a href="#cb18-2" aria-hidden="true" tabindex="-1"></a>number = <span class="cn">null</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>p5.zig:5:14: error: expected type 'u8',
         found '@TypeOf(null)'
@@ -465,8 +468,8 @@ <h3 data-number="6.4.1" class="anchored" data-anchor-id="what-are-optionals"><sp
 <p>An optional object in Zig is an object that can be null. To mark an object as optional, we use the <code>?</code> operator. When you put this <code>?</code> operator right before the data type of an object, you transform this data type into an optional data type, and the object becomes an optional object.</p>
 <p>Take the snippet below as an example. We are creating a new variable object called <code>num</code>. This object have the data type <code>?i32</code>, which means that, this object contains either a signed 32-bit integer (<code>i32</code>), or, a null value. Both alternatives are valid values to the <code>num</code> object. That is why, I can actually change the value of this object to null, and, no errors are raised by the <code>zig</code> compiler, as demonstrated below:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb19"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb19-1"><a href="#cb19-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> num: ?<span class="dt">i32</span> = <span class="dv">5</span>;</span>
-<span id="cb19-2"><a href="#cb19-2" aria-hidden="true" tabindex="-1"></a>num = <span class="cn">null</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb20"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb20-1"><a href="#cb20-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> num: ?<span class="dt">i32</span> = <span class="dv">5</span>;</span>
+<span id="cb20-2"><a href="#cb20-2" aria-hidden="true" tabindex="-1"></a>num = <span class="cn">null</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
 <section id="optional-pointers" class="level3" data-number="6.4.2">
@@ -475,18 +478,18 @@ <h3 data-number="6.4.2" class="anchored" data-anchor-id="optional-pointers"><spa
 <p>In the example below, we are creating a variable object named <code>num</code>, and an optional pointer object named <code>ptr</code>. Notice that the data type of the object <code>ptr</code> indicates that it is either a null value, or a pointer to an <code>i32</code> value. Also, notice that the pointer object (<code>ptr</code>) can be marked as optional, even if the object <code>num</code> is not optional.</p>
 <p>What this code tells us is that, the <code>num</code> variable will never contain a null value. This variable will always contain a valid <code>i32</code> value. But in contrast, the <code>ptr</code> object might contain either a null value, or, a pointer to an <code>i32</code> value.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb20"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb20-1"><a href="#cb20-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> num: <span class="dt">i32</span> = <span class="dv">5</span>;</span>
-<span id="cb20-2"><a href="#cb20-2" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> ptr: ?*<span class="dt">i32</span> = &amp;num;</span>
-<span id="cb20-3"><a href="#cb20-3" aria-hidden="true" tabindex="-1"></a>ptr = <span class="cn">null</span>;</span>
-<span id="cb20-4"><a href="#cb20-4" aria-hidden="true" tabindex="-1"></a>num = <span class="dv">6</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb21"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb21-1"><a href="#cb21-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> num: <span class="dt">i32</span> = <span class="dv">5</span>;</span>
+<span id="cb21-2"><a href="#cb21-2" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> ptr: ?*<span class="dt">i32</span> = &amp;num;</span>
+<span id="cb21-3"><a href="#cb21-3" aria-hidden="true" tabindex="-1"></a>ptr = <span class="cn">null</span>;</span>
+<span id="cb21-4"><a href="#cb21-4" aria-hidden="true" tabindex="-1"></a>num = <span class="dv">6</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>But what happens if we turn the table, and mark the <code>num</code> object as optional, instead of the pointer object. If we do that, then, the pointer object is not optional anymore. It would be a similar (although different) result. Because then, we would have a pointer to an optional value. In other words, a pointer to a value that is either a null value, or, a not-null value.</p>
 <p>In the example below, we are recreating this idea. Now, the <code>ptr</code> object have a data type of <code>*?i32</code>, instead of <code>?*i32</code>. Notice that the <code>*</code> symbol comes before of <code>?</code> this time. So now, we have a pointer that points to a value that is either null , or, a signed 32-bit integer.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb21"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb21-1"><a href="#cb21-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> num: ?<span class="dt">i32</span> = <span class="dv">5</span>;</span>
-<span id="cb21-2"><a href="#cb21-2" aria-hidden="true" tabindex="-1"></a><span class="co">// ptr have type `*?i32`, instead of `?*i32`.</span></span>
-<span id="cb21-3"><a href="#cb21-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ptr = &amp;num;</span>
-<span id="cb21-4"><a href="#cb21-4" aria-hidden="true" tabindex="-1"></a>_ = ptr;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb22"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb22-1"><a href="#cb22-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> num: ?<span class="dt">i32</span> = <span class="dv">5</span>;</span>
+<span id="cb22-2"><a href="#cb22-2" aria-hidden="true" tabindex="-1"></a><span class="co">// ptr have type `*?i32`, instead of `?*i32`.</span></span>
+<span id="cb22-3"><a href="#cb22-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ptr = &amp;num;</span>
+<span id="cb22-4"><a href="#cb22-4" aria-hidden="true" tabindex="-1"></a>_ = ptr;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
 <section id="sec-null-handling" class="level3" data-number="6.4.3">
@@ -500,10 +503,10 @@ <h3 data-number="6.4.3" class="anchored" data-anchor-id="sec-null-handling"><spa
 </ul>
 <p>When you use an if statement, you use a pair of pipes to unwrap the optional value, and use this “unwrapped object” inside the if block. Using the example below as a reference, if the object <code>num</code> is null, then, the code inside the if statement is not executed. Otherwise, the if statement will unwrap the object <code>num</code> into the <code>not_null_num</code> object. This <code>not_null_num</code> object is guaranteed to be not null inside the scope of the if statement.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb22"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb22-1"><a href="#cb22-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> num: ?<span class="dt">i32</span> = <span class="dv">5</span>;</span>
-<span id="cb22-2"><a href="#cb22-2" aria-hidden="true" tabindex="-1"></a><span class="kw">if</span> (num) |not_null_num| <span class="op">{</span></span>
-<span id="cb22-3"><a href="#cb22-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>not_null_num<span class="op">}</span>);</span>
-<span id="cb22-4"><a href="#cb22-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb23"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb23-1"><a href="#cb23-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> num: ?<span class="dt">i32</span> = <span class="dv">5</span>;</span>
+<span id="cb23-2"><a href="#cb23-2" aria-hidden="true" tabindex="-1"></a><span class="kw">if</span> (num) |not_null_num| <span class="op">{</span></span>
+<span id="cb23-3"><a href="#cb23-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>not_null_num<span class="op">}</span>);</span>
+<span id="cb23-4"><a href="#cb23-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>5</code></pre>
 </div>
@@ -512,9 +515,9 @@ <h3 data-number="6.4.3" class="anchored" data-anchor-id="sec-null-handling"><spa
 <p>The idea behind the <code>orelse</code> keyword is: if the expression on the left side result in a not-null value, then, this not-null value is used. However, if this expression on the left side result in a null value, then, the value of the expression on the right side is used instead.</p>
 <p>Looking at the example below, since the <code>x</code> object is currently null, the <code>orelse</code> decided to use the alternative value, which is the number 15.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb24"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb24-1"><a href="#cb24-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> x: ?<span class="dt">i32</span> = <span class="cn">null</span>;</span>
-<span id="cb24-2"><a href="#cb24-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> dbl = (x <span class="kw">orelse</span> <span class="dv">15</span>) * <span class="dv">2</span>;</span>
-<span id="cb24-3"><a href="#cb24-3" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>dbl<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb25"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb25-1"><a href="#cb25-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> x: ?<span class="dt">i32</span> = <span class="cn">null</span>;</span>
+<span id="cb25-2"><a href="#cb25-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> dbl = (x <span class="kw">orelse</span> <span class="dv">15</span>) * <span class="dv">2</span>;</span>
+<span id="cb25-3"><a href="#cb25-3" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>dbl<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>30</code></pre>
 </div>
@@ -522,18 +525,18 @@ <h3 data-number="6.4.3" class="anchored" data-anchor-id="sec-null-handling"><spa
 <p>You can use the if statement or the <code>orelse</code> keyword, when you want to solve (or deal with) this null value. However, if there is no clear solution to this null value, and the most logic and sane path is to simply panic and raise a loud error in your program when this null value is encountered, you can use the <code>?</code> method of your optional object.</p>
 <p>In essence, when you use this <code>?</code> method, the optional object is unwrapped. If a not-null value is found in the optional object, then, this not-null value is used. Otherwise, the <code>unreachable</code> keyword is used. You can read more about this <a href="https://ziglang.org/documentation/master/#unreachable"><code>unreacheable</code> keyword at the official documentation</a><a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>. But in essence, when you build your Zig source code using the build modes <code>ReleaseSafe</code> or <code>Debug</code>, this <code>unreacheable</code> keyword causes the program to panic and raise an error during runtime, like in the example below:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb26"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb26-1"><a href="#cb26-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb26-2"><a href="#cb26-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
-<span id="cb26-3"><a href="#cb26-3" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> return_null(n: <span class="dt">i32</span>) ?<span class="dt">i32</span> <span class="op">{</span></span>
-<span id="cb26-4"><a href="#cb26-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> (n == <span class="dv">5</span>) <span class="kw">return</span> <span class="cn">null</span>;</span>
-<span id="cb26-5"><a href="#cb26-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> n;</span>
-<span id="cb26-6"><a href="#cb26-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
-<span id="cb26-7"><a href="#cb26-7" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb26-8"><a href="#cb26-8" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb26-9"><a href="#cb26-9" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> x: <span class="dt">i32</span> = <span class="dv">5</span>;</span>
-<span id="cb26-10"><a href="#cb26-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> y: ?<span class="dt">i32</span> = return_null(x);</span>
-<span id="cb26-11"><a href="#cb26-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>y.?<span class="op">}</span>);</span>
-<span id="cb26-12"><a href="#cb26-12" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb27"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb27-1"><a href="#cb27-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb27-2"><a href="#cb27-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
+<span id="cb27-3"><a href="#cb27-3" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> return_null(n: <span class="dt">i32</span>) ?<span class="dt">i32</span> <span class="op">{</span></span>
+<span id="cb27-4"><a href="#cb27-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> (n == <span class="dv">5</span>) <span class="kw">return</span> <span class="cn">null</span>;</span>
+<span id="cb27-5"><a href="#cb27-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> n;</span>
+<span id="cb27-6"><a href="#cb27-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
+<span id="cb27-7"><a href="#cb27-7" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb27-8"><a href="#cb27-8" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb27-9"><a href="#cb27-9" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> x: <span class="dt">i32</span> = <span class="dv">5</span>;</span>
+<span id="cb27-10"><a href="#cb27-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> y: ?<span class="dt">i32</span> = return_null(x);</span>
+<span id="cb27-11"><a href="#cb27-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>y.?<span class="op">}</span>);</span>
+<span id="cb27-12"><a href="#cb27-12" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>thread 12767 panic: attempt to use null value
 p7.zig:12:34: 0x103419d in main (p7):
diff --git a/docs/Chapters/09-data-structures.html b/docs/Chapters/09-data-structures.html
index 75cbf5a3..c556478d 100644
--- a/docs/Chapters/09-data-structures.html
+++ b/docs/Chapters/09-data-structures.html
@@ -599,6 +599,10 @@ <h3 data-number="11.2.3" class="anchored" data-anchor-id="iterating-through-the-
 <span id="cb11-19"><a href="#cb11-19" aria-hidden="true" tabindex="-1"></a>        std.debug.print(<span class="st">"Value: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>kv.value_ptr.*<span class="op">}</span>);</span>
 <span id="cb11-20"><a href="#cb11-20" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
 <span id="cb11-21"><a href="#cb11-21" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="cell-output cell-output-stdout">
+<pre><code>Key: 54321 | Value: 89Key: 50050 | Value: 55Key: 5
+  57709 | Value: 41</code></pre>
+</div>
 </div>
 <pre><code>Key: 54321 | Value: 89
 Key: 50050 | Value: 55
@@ -606,10 +610,10 @@ <h3 data-number="11.2.3" class="anchored" data-anchor-id="iterating-through-the-
 <p>If you want to iterate specifically through the values or the keys of your hashtable, you can create a key iterator or a value iterator object. These are also iterator objects, which have the same <code>next()</code> method that you can use to iterate through the hashtable.</p>
 <p>Key iterators are created from the <code>keyIterator()</code> method of your hashtable object, while value iterators are created from the <code>valueIterator()</code> method. All you have to do is to unwrap the value from the <code>next()</code> method and deference it directly to access the key or the value that you are iterating over. The code example below demonstrates the use of a key iterator, but you can replicate the same logic to a value iterator.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb13"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> kit = hash_table.keyIterator();</span>
-<span id="cb13-2"><a href="#cb13-2" aria-hidden="true" tabindex="-1"></a><span class="kw">while</span> (kit.next()) |key| <span class="op">{</span></span>
-<span id="cb13-3"><a href="#cb13-3" aria-hidden="true" tabindex="-1"></a>    std.debug.print(<span class="st">"Key: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>key.*<span class="op">}</span>);</span>
-<span id="cb13-4"><a href="#cb13-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb14"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> kit = hash_table.keyIterator();</span>
+<span id="cb14-2"><a href="#cb14-2" aria-hidden="true" tabindex="-1"></a><span class="kw">while</span> (kit.next()) |key| <span class="op">{</span></span>
+<span id="cb14-3"><a href="#cb14-3" aria-hidden="true" tabindex="-1"></a>    std.debug.print(<span class="st">"Key: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>key.*<span class="op">}</span>);</span>
+<span id="cb14-4"><a href="#cb14-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Key: 54321
 Key: 50050
@@ -630,9 +634,9 @@ <h3 data-number="11.2.4" class="anchored" data-anchor-id="sec-array-map"><span c
 <p>This means that, with <code>swapRemove()</code> you remove the value from the hashtable, but you do not preserve the order in which the values were inserted into the structure. While <code>orderedRemove()</code> is able to retain the order in which these values were inserted.</p>
 <p>But instead of providing an index as input to <code>swapRemove()</code> or <code>orderedRemove()</code>, like I described at <a href="#sec-dynamic-array-remove" class="quarto-xref"><span>Section 11.1.4</span></a>, these methods here in an <code>ArrayHashMap</code> take a key as input, like the <code>remove()</code> method from a <code>HashMap</code> object. If you want to provide an index as input, instead of a key, you should use the <code>swapRemoveAt()</code> and <code>orderedRemoveAt()</code> methods.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb15"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb15-1"><a href="#cb15-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> hash_table = AutoArrayHashMap(<span class="dt">u32</span>, <span class="dt">u16</span>)</span>
-<span id="cb15-2"><a href="#cb15-2" aria-hidden="true" tabindex="-1"></a>    .init(allocator);</span>
-<span id="cb15-3"><a href="#cb15-3" aria-hidden="true" tabindex="-1"></a><span class="kw">defer</span> hash_table.deinit();</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb16"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> hash_table = AutoArrayHashMap(<span class="dt">u32</span>, <span class="dt">u16</span>)</span>
+<span id="cb16-2"><a href="#cb16-2" aria-hidden="true" tabindex="-1"></a>    .init(allocator);</span>
+<span id="cb16-3"><a href="#cb16-3" aria-hidden="true" tabindex="-1"></a><span class="kw">defer</span> hash_table.deinit();</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
 <section id="sec-string-hash-map" class="level3" data-number="11.2.5">
@@ -640,33 +644,33 @@ <h3 data-number="11.2.5" class="anchored" data-anchor-id="sec-string-hash-map"><
 <p>One thing that you will notice in the other two types of hashtables that I have presented over the last sections, is that neither of them accepts a slice data type in their keys. What this means is that you cannot use a slice value to represent a key in these types of hashtable.</p>
 <p>The most obvious consequence of this, is that you cannot use strings as keys in these hashtables. But it is extremely common to use strings as keys in hashtables.</p>
 <p>Take this very simple Javascript code snippet as an example. We are creating a simple hashtable object named <code>people</code>. Then, we add a new entry to this hashtable, which is identified by the string <code>'Pedro'</code>. This string is the key in this case, while the object containing different personal information such as age, height and city, is the value to be stored in the hashtable.</p>
-<div class="sourceCode" id="cb16"><pre class="sourceCode js code-with-copy"><code class="sourceCode javascript"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> people <span class="op">=</span> <span class="kw">new</span> <span class="bu">Object</span>()<span class="op">;</span></span>
-<span id="cb16-2"><a href="#cb16-2" aria-hidden="true" tabindex="-1"></a>people[<span class="st">'Pedro'</span>] <span class="op">=</span> {</span>
-<span id="cb16-3"><a href="#cb16-3" aria-hidden="true" tabindex="-1"></a>    <span class="st">'age'</span><span class="op">:</span> <span class="dv">25</span><span class="op">,</span></span>
-<span id="cb16-4"><a href="#cb16-4" aria-hidden="true" tabindex="-1"></a>    <span class="st">'height'</span><span class="op">:</span> <span class="fl">1.67</span><span class="op">,</span></span>
-<span id="cb16-5"><a href="#cb16-5" aria-hidden="true" tabindex="-1"></a>    <span class="st">'city'</span><span class="op">:</span> <span class="st">'Belo Horizonte'</span></span>
-<span id="cb16-6"><a href="#cb16-6" aria-hidden="true" tabindex="-1"></a>}<span class="op">;</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode" id="cb17"><pre class="sourceCode js code-with-copy"><code class="sourceCode javascript"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> people <span class="op">=</span> <span class="kw">new</span> <span class="bu">Object</span>()<span class="op">;</span></span>
+<span id="cb17-2"><a href="#cb17-2" aria-hidden="true" tabindex="-1"></a>people[<span class="st">'Pedro'</span>] <span class="op">=</span> {</span>
+<span id="cb17-3"><a href="#cb17-3" aria-hidden="true" tabindex="-1"></a>    <span class="st">'age'</span><span class="op">:</span> <span class="dv">25</span><span class="op">,</span></span>
+<span id="cb17-4"><a href="#cb17-4" aria-hidden="true" tabindex="-1"></a>    <span class="st">'height'</span><span class="op">:</span> <span class="fl">1.67</span><span class="op">,</span></span>
+<span id="cb17-5"><a href="#cb17-5" aria-hidden="true" tabindex="-1"></a>    <span class="st">'city'</span><span class="op">:</span> <span class="st">'Belo Horizonte'</span></span>
+<span id="cb17-6"><a href="#cb17-6" aria-hidden="true" tabindex="-1"></a>}<span class="op">;</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <p>This pattern of using strings as keys is very common in all sorts of situations. That is why the Zig Standard Library offers a specific type of hashtable for this purpose, which is created through the <code>StringHashMap()</code> function. This function creates a hashtable that uses strings as keys. The only input of this function is the data type of the values that will be stored into this hashtable.</p>
 <p>In the example below, I’m creating a hashtable to store the ages of different people. Each key in this hashtable is represented by the name of each person, while the value stored in the hashtable is the age of this person identified by the key.</p>
 <p>That is why I provide the <code>u8</code> data type (which is the data type used by the age values) as input to this <code>StringHashMap()</code> function. As the result, it creates a hashtable that uses string values as keys, and, that stores <code>u8</code> values in it. Notice that an allocator object is provided at the <code>init()</code> method of the resulting object from the <code>StringHashMap()</code> function.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb17"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb17-2"><a href="#cb17-2" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb17-3"><a href="#cb17-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> gpa = std.heap.GeneralPurposeAllocator(.<span class="op">{}</span>)<span class="op">{}</span>;</span>
-<span id="cb17-4"><a href="#cb17-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> allocator = gpa.allocator();</span>
-<span id="cb17-5"><a href="#cb17-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> ages = std.StringHashMap(<span class="dt">u8</span>).init(allocator);</span>
-<span id="cb17-6"><a href="#cb17-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">defer</span> ages.deinit();</span>
-<span id="cb17-7"><a href="#cb17-7" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb17-8"><a href="#cb17-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> ages.put(<span class="st">"Pedro"</span>, <span class="dv">25</span>);</span>
-<span id="cb17-9"><a href="#cb17-9" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> ages.put(<span class="st">"Matheus"</span>, <span class="dv">21</span>);</span>
-<span id="cb17-10"><a href="#cb17-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> ages.put(<span class="st">"Abgail"</span>, <span class="dv">42</span>);</span>
-<span id="cb17-11"><a href="#cb17-11" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb17-12"><a href="#cb17-12" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> it = ages.iterator();</span>
-<span id="cb17-13"><a href="#cb17-13" aria-hidden="true" tabindex="-1"></a>    <span class="kw">while</span> (it.next()) |kv| <span class="op">{</span></span>
-<span id="cb17-14"><a href="#cb17-14" aria-hidden="true" tabindex="-1"></a>        std.debug.print(<span class="st">"Key: {s} | "</span>, .<span class="op">{</span>kv.key_ptr.*<span class="op">}</span>);</span>
-<span id="cb17-15"><a href="#cb17-15" aria-hidden="true" tabindex="-1"></a>        std.debug.print(<span class="st">"Age: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>kv.value_ptr.*<span class="op">}</span>);</span>
-<span id="cb17-16"><a href="#cb17-16" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb17-17"><a href="#cb17-17" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb18"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb18-1"><a href="#cb18-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb18-2"><a href="#cb18-2" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb18-3"><a href="#cb18-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> gpa = std.heap.GeneralPurposeAllocator(.<span class="op">{}</span>)<span class="op">{}</span>;</span>
+<span id="cb18-4"><a href="#cb18-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> allocator = gpa.allocator();</span>
+<span id="cb18-5"><a href="#cb18-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> ages = std.StringHashMap(<span class="dt">u8</span>).init(allocator);</span>
+<span id="cb18-6"><a href="#cb18-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">defer</span> ages.deinit();</span>
+<span id="cb18-7"><a href="#cb18-7" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb18-8"><a href="#cb18-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> ages.put(<span class="st">"Pedro"</span>, <span class="dv">25</span>);</span>
+<span id="cb18-9"><a href="#cb18-9" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> ages.put(<span class="st">"Matheus"</span>, <span class="dv">21</span>);</span>
+<span id="cb18-10"><a href="#cb18-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> ages.put(<span class="st">"Abgail"</span>, <span class="dv">42</span>);</span>
+<span id="cb18-11"><a href="#cb18-11" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb18-12"><a href="#cb18-12" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> it = ages.iterator();</span>
+<span id="cb18-13"><a href="#cb18-13" aria-hidden="true" tabindex="-1"></a>    <span class="kw">while</span> (it.next()) |kv| <span class="op">{</span></span>
+<span id="cb18-14"><a href="#cb18-14" aria-hidden="true" tabindex="-1"></a>        std.debug.print(<span class="st">"Key: {s} | "</span>, .<span class="op">{</span>kv.key_ptr.*<span class="op">}</span>);</span>
+<span id="cb18-15"><a href="#cb18-15" aria-hidden="true" tabindex="-1"></a>        std.debug.print(<span class="st">"Age: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>kv.value_ptr.*<span class="op">}</span>);</span>
+<span id="cb18-16"><a href="#cb18-16" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb18-17"><a href="#cb18-17" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Key: Pedro | Age: 25
 Key: Abgail | Age: 42
@@ -679,7 +683,7 @@ <h3 data-number="11.2.6" class="anchored" data-anchor-id="the-stringarrayhashmap
 <p>You can insert new values into this hashtable by using the same <code>put()</code> method that we have discussed at <a href="#sec-string-hash-map" class="quarto-xref"><span>Section 11.2.5</span></a>. And you can also get values from the hashtable by using the same <code>get()</code> method. Like its <code>ArrayHashMap</code> brother, to delete values from this specific type of hashtable, we also use the <code>orderedRemove()</code> and <code>swapRemove()</code> methods, with the same effects that I have described at <a href="#sec-array-map" class="quarto-xref"><span>Section 11.2.4</span></a>.</p>
 <p>If we take the code example that was exposed at <a href="#sec-string-hash-map" class="quarto-xref"><span>Section 11.2.5</span></a>, we can achieve the exact same result with <code>StringArrayHashMap()</code>:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb19"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb19-1"><a href="#cb19-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> ages = std.StringArrayHashMap(<span class="dt">u8</span>).init(allocator);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb20"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb20-1"><a href="#cb20-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> ages = std.StringArrayHashMap(<span class="dt">u8</span>).init(allocator);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
 </section>
@@ -722,24 +726,24 @@ <h2 data-number="11.3" class="anchored" data-anchor-id="linked-lists"><span clas
 <p>Thus, if we have used a doubly linked list, we can use the <code>insertBefore()</code> method to store the pointer to the input node in the <code>prev</code> attribute. This would put the input node as the “previous node”, or, the node before the current node. In contrast, the <code>insertAfter()</code> method puts the pointer created to the input node in the <code>next</code> attribute of the current node, and as result, the input node becomes the “next node” of the current node.</p>
 <p>Since we are using a singly linked list in this example, we have only the <code>insertAfter()</code> method available in the node objects that we create from our <code>Lu32</code> type.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb20"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb20-1"><a href="#cb20-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb20-2"><a href="#cb20-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> SinglyLinkedList = std.SinglyLinkedList;</span>
-<span id="cb20-3"><a href="#cb20-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Lu32 = SinglyLinkedList(<span class="dt">u32</span>);</span>
-<span id="cb20-4"><a href="#cb20-4" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb20-5"><a href="#cb20-5" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb20-6"><a href="#cb20-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> list = Lu32<span class="op">{}</span>;</span>
-<span id="cb20-7"><a href="#cb20-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> one = Lu32.Node<span class="op">{</span> .data = <span class="dv">1</span> <span class="op">}</span>;</span>
-<span id="cb20-8"><a href="#cb20-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> two = Lu32.Node<span class="op">{</span> .data = <span class="dv">2</span> <span class="op">}</span>;</span>
-<span id="cb20-9"><a href="#cb20-9" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> three = Lu32.Node<span class="op">{</span> .data = <span class="dv">3</span> <span class="op">}</span>;</span>
-<span id="cb20-10"><a href="#cb20-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> four = Lu32.Node<span class="op">{</span> .data = <span class="dv">4</span> <span class="op">}</span>;</span>
-<span id="cb20-11"><a href="#cb20-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> five = Lu32.Node<span class="op">{</span> .data = <span class="dv">5</span> <span class="op">}</span>;</span>
-<span id="cb20-12"><a href="#cb20-12" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb20-13"><a href="#cb20-13" aria-hidden="true" tabindex="-1"></a>    list.prepend(&amp;two); <span class="co">// {2}</span></span>
-<span id="cb20-14"><a href="#cb20-14" aria-hidden="true" tabindex="-1"></a>    two.insertAfter(&amp;five); <span class="co">// {2, 5}</span></span>
-<span id="cb20-15"><a href="#cb20-15" aria-hidden="true" tabindex="-1"></a>    list.prepend(&amp;one); <span class="co">// {1, 2, 5}</span></span>
-<span id="cb20-16"><a href="#cb20-16" aria-hidden="true" tabindex="-1"></a>    two.insertAfter(&amp;three); <span class="co">// {1, 2, 3, 5}</span></span>
-<span id="cb20-17"><a href="#cb20-17" aria-hidden="true" tabindex="-1"></a>    three.insertAfter(&amp;four); <span class="co">// {1, 2, 3, 4, 5}</span></span>
-<span id="cb20-18"><a href="#cb20-18" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb21"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb21-1"><a href="#cb21-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb21-2"><a href="#cb21-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> SinglyLinkedList = std.SinglyLinkedList;</span>
+<span id="cb21-3"><a href="#cb21-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Lu32 = SinglyLinkedList(<span class="dt">u32</span>);</span>
+<span id="cb21-4"><a href="#cb21-4" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb21-5"><a href="#cb21-5" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb21-6"><a href="#cb21-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> list = Lu32<span class="op">{}</span>;</span>
+<span id="cb21-7"><a href="#cb21-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> one = Lu32.Node<span class="op">{</span> .data = <span class="dv">1</span> <span class="op">}</span>;</span>
+<span id="cb21-8"><a href="#cb21-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> two = Lu32.Node<span class="op">{</span> .data = <span class="dv">2</span> <span class="op">}</span>;</span>
+<span id="cb21-9"><a href="#cb21-9" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> three = Lu32.Node<span class="op">{</span> .data = <span class="dv">3</span> <span class="op">}</span>;</span>
+<span id="cb21-10"><a href="#cb21-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> four = Lu32.Node<span class="op">{</span> .data = <span class="dv">4</span> <span class="op">}</span>;</span>
+<span id="cb21-11"><a href="#cb21-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> five = Lu32.Node<span class="op">{</span> .data = <span class="dv">5</span> <span class="op">}</span>;</span>
+<span id="cb21-12"><a href="#cb21-12" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb21-13"><a href="#cb21-13" aria-hidden="true" tabindex="-1"></a>    list.prepend(&amp;two); <span class="co">// {2}</span></span>
+<span id="cb21-14"><a href="#cb21-14" aria-hidden="true" tabindex="-1"></a>    two.insertAfter(&amp;five); <span class="co">// {2, 5}</span></span>
+<span id="cb21-15"><a href="#cb21-15" aria-hidden="true" tabindex="-1"></a>    list.prepend(&amp;one); <span class="co">// {1, 2, 5}</span></span>
+<span id="cb21-16"><a href="#cb21-16" aria-hidden="true" tabindex="-1"></a>    two.insertAfter(&amp;three); <span class="co">// {1, 2, 3, 5}</span></span>
+<span id="cb21-17"><a href="#cb21-17" aria-hidden="true" tabindex="-1"></a>    three.insertAfter(&amp;four); <span class="co">// {1, 2, 3, 4, 5}</span></span>
+<span id="cb21-18"><a href="#cb21-18" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>There are other methods available from the linked list object, depending if this object is a singly linked list or a doubly linked list, that might be very useful for you. You can find a summary of them in the bullet points below:</p>
 <ul>
@@ -756,30 +760,30 @@ <h2 data-number="11.4" class="anchored" data-anchor-id="multi-array-structure"><
 <p>Zig introduces a new data structure called <code>MultiArrayList()</code>. It is a different version of the dynamic array that we have introduced at <a href="#sec-dynamic-array" class="quarto-xref"><span>Section 11.1</span></a>. The difference between this structure and the <code>ArrayList()</code> that we know from <a href="#sec-dynamic-array" class="quarto-xref"><span>Section 11.1</span></a>, is that <code>MultiArrayList()</code> creates a separate dynamic array for each field of the struct that you provide as input.</p>
 <p>Consider the following code example. We create a new custom struct called <code>Person</code>. This struct contains three different data members, or, three different fields. As consequence, when we provide this <code>Person</code> data type as input to <code>MultiArrayList()</code>, this creates a “struct of three different arrays” called <code>PersonArray</code>. In other words, this <code>PersonArray</code> is a struct that contains three internal dynamic arrays in it. One array for each field found in the <code>Person</code> struct definition.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb21"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb21-1"><a href="#cb21-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb21-2"><a href="#cb21-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Person = <span class="kw">struct</span> <span class="op">{</span></span>
-<span id="cb21-3"><a href="#cb21-3" aria-hidden="true" tabindex="-1"></a>    name: []<span class="kw">const</span> <span class="dt">u8</span>,</span>
-<span id="cb21-4"><a href="#cb21-4" aria-hidden="true" tabindex="-1"></a>    age: <span class="dt">u8</span>,</span>
-<span id="cb21-5"><a href="#cb21-5" aria-hidden="true" tabindex="-1"></a>    height: <span class="dt">f32</span>,</span>
-<span id="cb21-6"><a href="#cb21-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
-<span id="cb21-7"><a href="#cb21-7" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> PersonArray = std.MultiArrayList(Person);</span>
-<span id="cb21-8"><a href="#cb21-8" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb21-9"><a href="#cb21-9" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb21-10"><a href="#cb21-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> gpa = std.heap.GeneralPurposeAllocator(.<span class="op">{}</span>)<span class="op">{}</span>;</span>
-<span id="cb21-11"><a href="#cb21-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> allocator = gpa.allocator();</span>
-<span id="cb21-12"><a href="#cb21-12" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> people = PersonArray<span class="op">{}</span>;</span>
-<span id="cb21-13"><a href="#cb21-13" aria-hidden="true" tabindex="-1"></a>    <span class="kw">defer</span> people.deinit(allocator);</span>
-<span id="cb21-14"><a href="#cb21-14" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb21-15"><a href="#cb21-15" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
-<span id="cb21-16"><a href="#cb21-16" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Auguste"</span>, .age = <span class="dv">15</span>, .height = <span class="fl">1.54</span></span>
-<span id="cb21-17"><a href="#cb21-17" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
-<span id="cb21-18"><a href="#cb21-18" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
-<span id="cb21-19"><a href="#cb21-19" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Elena"</span>, .age = <span class="dv">26</span>, .height = <span class="fl">1.65</span></span>
-<span id="cb21-20"><a href="#cb21-20" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
-<span id="cb21-21"><a href="#cb21-21" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
-<span id="cb21-22"><a href="#cb21-22" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Michael"</span>, .age = <span class="dv">64</span>, .height = <span class="fl">1.87</span></span>
-<span id="cb21-23"><a href="#cb21-23" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
-<span id="cb21-24"><a href="#cb21-24" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb22"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb22-1"><a href="#cb22-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb22-2"><a href="#cb22-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Person = <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb22-3"><a href="#cb22-3" aria-hidden="true" tabindex="-1"></a>    name: []<span class="kw">const</span> <span class="dt">u8</span>,</span>
+<span id="cb22-4"><a href="#cb22-4" aria-hidden="true" tabindex="-1"></a>    age: <span class="dt">u8</span>,</span>
+<span id="cb22-5"><a href="#cb22-5" aria-hidden="true" tabindex="-1"></a>    height: <span class="dt">f32</span>,</span>
+<span id="cb22-6"><a href="#cb22-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
+<span id="cb22-7"><a href="#cb22-7" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> PersonArray = std.MultiArrayList(Person);</span>
+<span id="cb22-8"><a href="#cb22-8" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb22-9"><a href="#cb22-9" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb22-10"><a href="#cb22-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> gpa = std.heap.GeneralPurposeAllocator(.<span class="op">{}</span>)<span class="op">{}</span>;</span>
+<span id="cb22-11"><a href="#cb22-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> allocator = gpa.allocator();</span>
+<span id="cb22-12"><a href="#cb22-12" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> people = PersonArray<span class="op">{}</span>;</span>
+<span id="cb22-13"><a href="#cb22-13" aria-hidden="true" tabindex="-1"></a>    <span class="kw">defer</span> people.deinit(allocator);</span>
+<span id="cb22-14"><a href="#cb22-14" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb22-15"><a href="#cb22-15" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
+<span id="cb22-16"><a href="#cb22-16" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Auguste"</span>, .age = <span class="dv">15</span>, .height = <span class="fl">1.54</span></span>
+<span id="cb22-17"><a href="#cb22-17" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
+<span id="cb22-18"><a href="#cb22-18" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
+<span id="cb22-19"><a href="#cb22-19" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Elena"</span>, .age = <span class="dv">26</span>, .height = <span class="fl">1.65</span></span>
+<span id="cb22-20"><a href="#cb22-20" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
+<span id="cb22-21"><a href="#cb22-21" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
+<span id="cb22-22"><a href="#cb22-22" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Michael"</span>, .age = <span class="dv">64</span>, .height = <span class="fl">1.87</span></span>
+<span id="cb22-23"><a href="#cb22-23" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
+<span id="cb22-24"><a href="#cb22-24" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>In other words, instead of creating an array of “persons”, the <code>MultiArrayList()</code> function creates a “struct of arrays”. Each data member of this struct is a different array that stores the values of a specific field from the <code>Person</code> values that were added (or, appended) to this “struct of arrays”. One important detail is that each of these separate internal arrays stored inside <code>PersonArray</code> are dynamic arrays. This means that these arrays can grow in capacity automatically as needed, to accomodate more values.</p>
 <p>The <a href="#fig-multi-array" class="quarto-xref">Figure&nbsp;<span>11.5</span></a> exposed below presents a diagram that describes the <code>PersonArray</code> struct that we have created in the previous code example. Notice that the values of the data members present in each of the three <code>Person</code> values that we have appended into the <code>PersonArray</code> object , are scattered across three different internal arrays of the <code>PersonArray</code> object.</p>
@@ -795,9 +799,9 @@ <h2 data-number="11.4" class="anchored" data-anchor-id="multi-array-structure"><
 </div>
 <p>You can easily access each of these arrays separately, and iterate over the values of each array. For that, you will need to call the <code>items()</code> method from the <code>PersonArray</code> object, and provide as input to this method, the name of the field that you want to iterate over. If you want to iterate through the <code>.age</code> array for example, then, you need to call <code>items(.age)</code> from the <code>PersonArray</code> object, like in the example below:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb22"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb22-1"><a href="#cb22-1" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (people.items(.age)) |*age| <span class="op">{</span></span>
-<span id="cb22-2"><a href="#cb22-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"Age: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>age.*<span class="op">}</span>);</span>
-<span id="cb22-3"><a href="#cb22-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb23"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb23-1"><a href="#cb23-1" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (people.items(.age)) |*age| <span class="op">{</span></span>
+<span id="cb23-2"><a href="#cb23-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"Age: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>age.*<span class="op">}</span>);</span>
+<span id="cb23-3"><a href="#cb23-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Age: 15
 Age: 26
@@ -806,15 +810,15 @@ <h2 data-number="11.4" class="anchored" data-anchor-id="multi-array-structure"><
 <p>In this example we are calling the <code>items()</code> method directly from the <code>PersonArray</code> object. However, it is recommended on most situations to call this <code>items()</code> method from a “slice object”, which you can create from the <code>slice()</code> method. The reason for this is that calling <code>items()</code> multiple times have better performance if you use a slice object.</p>
 <p>Therefore, if you are planning to access only one of the internal arrays from your “multi array struct”, it is fine to call <code>items()</code> directly from the multi array object. But if you need to access many of the internal arrays from your “multi array struct”, then, you will likely need to call <code>items()</code> more than once, and, in such circumstance, is better to call <code>items()</code> through a slice object. The example below demonstrates the use of such object:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb24"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb24-1"><a href="#cb24-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> slice = people.slice();</span>
-<span id="cb24-2"><a href="#cb24-2" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (slice.items(.age)) |*age| <span class="op">{</span></span>
-<span id="cb24-3"><a href="#cb24-3" aria-hidden="true" tabindex="-1"></a>    age.* += <span class="dv">10</span>;</span>
-<span id="cb24-4"><a href="#cb24-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
-<span id="cb24-5"><a href="#cb24-5" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (slice.items(.name), slice.items(.age)) |*n,*a| <span class="op">{</span></span>
-<span id="cb24-6"><a href="#cb24-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(</span>
-<span id="cb24-7"><a href="#cb24-7" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Name: {s}, Age: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>n.*, a.*<span class="op">}</span></span>
-<span id="cb24-8"><a href="#cb24-8" aria-hidden="true" tabindex="-1"></a>    );</span>
-<span id="cb24-9"><a href="#cb24-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb25"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb25-1"><a href="#cb25-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> slice = people.slice();</span>
+<span id="cb25-2"><a href="#cb25-2" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (slice.items(.age)) |*age| <span class="op">{</span></span>
+<span id="cb25-3"><a href="#cb25-3" aria-hidden="true" tabindex="-1"></a>    age.* += <span class="dv">10</span>;</span>
+<span id="cb25-4"><a href="#cb25-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
+<span id="cb25-5"><a href="#cb25-5" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (slice.items(.name), slice.items(.age)) |*n,*a| <span class="op">{</span></span>
+<span id="cb25-6"><a href="#cb25-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(</span>
+<span id="cb25-7"><a href="#cb25-7" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Name: {s}, Age: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>n.*, a.*<span class="op">}</span></span>
+<span id="cb25-8"><a href="#cb25-8" aria-hidden="true" tabindex="-1"></a>    );</span>
+<span id="cb25-9"><a href="#cb25-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Name: Auguste, Age: 25
 Name: Elena, Age: 36
diff --git a/docs/Chapters/09-error-handling.html b/docs/Chapters/09-error-handling.html
index 2adad9db..597d0a92 100644
--- a/docs/Chapters/09-error-handling.html
+++ b/docs/Chapters/09-error-handling.html
@@ -468,6 +468,10 @@ <h3 data-number="10.1.3" class="anchored" data-anchor-id="casting-error-values">
 <span id="cb8-19"><a href="#cb8-19" aria-hidden="true" tabindex="-1"></a>        error_value == A.OutOfMemory</span>
 <span id="cb8-20"><a href="#cb8-20" aria-hidden="true" tabindex="-1"></a>    );</span>
 <span id="cb8-21"><a href="#cb8-21" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="cell-output cell-output-stdout">
+<pre><code>1/1 file10459ffd0e21.test.coerce error value...OKA
+  All 1 tests passed.</code></pre>
+</div>
 </div>
 </section>
 </section>
@@ -495,14 +499,14 @@ <h3 data-number="10.2.2" class="anchored" data-anchor-id="the-catch-keyword"><sp
 <p>Look at the code example below. Once again, we go back to the previous example where we were trying to open a file that doesn’t exist in my computer, but this time, I use <code>catch</code> to actually implement a logic to handle the error, instead of just stopping the execution right away.</p>
 <p>More specifically, in this example, I’m using a logger object to record some logs into the system, before I return the error, and stop the execution of the program. For example, this could be some part of the codebase of a complex system that I do not have full control over, and I want to record these logs before the program crashes, so that I can debug it later (e.g.&nbsp;maybe I cannot compile the full program, and properly debug it with a debugger. So, these logs might be a valid strategy to surpass this barrier).</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb9"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb9-1"><a href="#cb9-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> dir = std.fs.cwd();</span>
-<span id="cb9-2"><a href="#cb9-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> file = dir.openFile(</span>
-<span id="cb9-3"><a href="#cb9-3" aria-hidden="true" tabindex="-1"></a>    <span class="st">"doesnt_exist.txt"</span>, .<span class="op">{}</span></span>
-<span id="cb9-4"><a href="#cb9-4" aria-hidden="true" tabindex="-1"></a>) <span class="kw">catch</span> |err| <span class="op">{</span></span>
-<span id="cb9-5"><a href="#cb9-5" aria-hidden="true" tabindex="-1"></a>    logger.record_context();</span>
-<span id="cb9-6"><a href="#cb9-6" aria-hidden="true" tabindex="-1"></a>    logger.log_error(err);</span>
-<span id="cb9-7"><a href="#cb9-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> err;</span>
-<span id="cb9-8"><a href="#cb9-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb10"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> dir = std.fs.cwd();</span>
+<span id="cb10-2"><a href="#cb10-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> file = dir.openFile(</span>
+<span id="cb10-3"><a href="#cb10-3" aria-hidden="true" tabindex="-1"></a>    <span class="st">"doesnt_exist.txt"</span>, .<span class="op">{}</span></span>
+<span id="cb10-4"><a href="#cb10-4" aria-hidden="true" tabindex="-1"></a>) <span class="kw">catch</span> |err| <span class="op">{</span></span>
+<span id="cb10-5"><a href="#cb10-5" aria-hidden="true" tabindex="-1"></a>    logger.record_context();</span>
+<span id="cb10-6"><a href="#cb10-6" aria-hidden="true" tabindex="-1"></a>    logger.log_error(err);</span>
+<span id="cb10-7"><a href="#cb10-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> err;</span>
+<span id="cb10-8"><a href="#cb10-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>Therefore, we use <code>catch</code> to create a block of expressions that will handle the error. I can return the error value from this block of expressions, like I did in the above example, which, will make the program enter in panic mode, and, stop the execution. But I could also, return a valid value from this block of code, which would be stored in the <code>file</code> object.</p>
 <p>Notice that, instead of writing the keyword before the expression that might return the error, like we do with <code>try</code>, we write <code>catch</code> after the expression. We can open the pair of pipes (<code>|</code>), which captures the error value returned by the expression, and makes this error value available in the scope of the <code>catch</code> block as the object named <code>err</code>. In other words, because I wrote <code>|err|</code> in the code, I can access the error value returned by the expression, by using the <code>err</code> object.</p>
@@ -510,7 +514,7 @@ <h3 data-number="10.2.2" class="anchored" data-anchor-id="the-catch-keyword"><sp
 <p>The Zig official language reference, provides a great example of this “default value” strategy with <code>catch</code>. This example is reproduced below. Notice that we are trying to parse some unsigned integer from a string object named <code>str</code>. In other words, this function is trying to transform an object of type <code>[]const u8</code> (i.e.&nbsp;an array of characters, a string, etc.) into an object of type <code>u64</code>.</p>
 <p>But this parsing process done by the function <code>parseU64()</code> may fail, resulting in a runtime error. The <code>catch</code> keyword used in this example provides an alternative value (13) to be used in case this <code>parseU64()</code> function raises an error. So, the expression below essentially means: “Hey! Please, parse this string into a <code>u64</code> for me, and store the results into the object <code>number</code>. But, if an error occurs, then, use the value <code>13</code> instead”.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb10"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> number = parseU64(str, <span class="dv">10</span>) <span class="kw">catch</span> <span class="dv">13</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb11"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> number = parseU64(str, <span class="dv">10</span>) <span class="kw">catch</span> <span class="dv">13</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>So, at the end of this process, the object <code>number</code> will contain either a <code>u64</code> integer that was parsed successfully from the input string <code>str</code>, or, if an error occurs in the parsing process, it will contain the <code>u64</code> value <code>13</code> that was provided by the <code>catch</code> keyword as the “default”, or, the “alternative” value.</p>
 </section>
@@ -521,30 +525,30 @@ <h3 data-number="10.2.3" class="anchored" data-anchor-id="using-if-statements"><
 <p>This means that, if the <code>parseU64()</code> expression returns a valid value, this value becomes available inside the scope of this “if branch” (i.e.&nbsp;the “true branch”) through the object that we listed inside the pair of pipe character (<code>|</code>), which is the object <code>number</code>.</p>
 <p>If an error occurs, we can use an “else branch” (or the “false branch”) of the if statement to handle the error. In the example below, we are using the <code>else</code> in the if statement to unwrap the error value (that was returned by <code>parseU64()</code>) into the <code>err</code> object, and handle the error.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb11"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a><span class="kw">if</span> (parseU64(str, <span class="dv">10</span>)) |number| <span class="op">{</span></span>
-<span id="cb11-2"><a href="#cb11-2" aria-hidden="true" tabindex="-1"></a>    <span class="co">// do something with `number` here</span></span>
-<span id="cb11-3"><a href="#cb11-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span> <span class="kw">else</span> |err| <span class="op">{</span></span>
-<span id="cb11-4"><a href="#cb11-4" aria-hidden="true" tabindex="-1"></a>    <span class="co">// handle the error value.</span></span>
-<span id="cb11-5"><a href="#cb11-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb12"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a><span class="kw">if</span> (parseU64(str, <span class="dv">10</span>)) |number| <span class="op">{</span></span>
+<span id="cb12-2"><a href="#cb12-2" aria-hidden="true" tabindex="-1"></a>    <span class="co">// do something with `number` here</span></span>
+<span id="cb12-3"><a href="#cb12-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span> <span class="kw">else</span> |err| <span class="op">{</span></span>
+<span id="cb12-4"><a href="#cb12-4" aria-hidden="true" tabindex="-1"></a>    <span class="co">// handle the error value.</span></span>
+<span id="cb12-5"><a href="#cb12-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>Now, if the expression that you are executing returns different types of error values, and you want to take a different action in each of these types of error values, the <code>try</code> and <code>catch</code> keywords, and the if statement strategy, becomes limited.</p>
 <p>For this type of situation, the official documentation of the language suggests the use of a switch statement together with an if statement <span class="citation" data-cites="zigdocs">(<a href="../references.html#ref-zigdocs" role="doc-biblioref">Zig Software Foundation 2024b</a>)</span>. The basic idea is, to use the if statement to execute the expression, and use the “else branch” to pass the error value to a switch statement, where you define a different action for each type of error value that might be returned by the expression executed in the if statement.</p>
 <p>The example below demonstrates this idea. We first try to add (or register) a set of tasks to a queue. If this “registration process” occurs well, we then try to distribute these tasks across the workers of our system. But if this “registration process” returns an error value, we then use a switch statement in the “else branch” to handle each possible error value.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb12"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a><span class="kw">if</span> (add_tasks_to_queue(&amp;queue, tasks)) |_| <span class="op">{</span></span>
-<span id="cb12-2"><a href="#cb12-2" aria-hidden="true" tabindex="-1"></a>    distribute_tasks(&amp;queue);</span>
-<span id="cb12-3"><a href="#cb12-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span> <span class="kw">else</span> |err| <span class="kw">switch</span> (err) <span class="op">{</span></span>
-<span id="cb12-4"><a href="#cb12-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">error</span>.InvalidTaskName =&gt; <span class="op">{</span></span>
-<span id="cb12-5"><a href="#cb12-5" aria-hidden="true" tabindex="-1"></a>        <span class="co">// do something</span></span>
-<span id="cb12-6"><a href="#cb12-6" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>,</span>
-<span id="cb12-7"><a href="#cb12-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">error</span>.TimeoutTooBig =&gt; <span class="op">{</span></span>
-<span id="cb12-8"><a href="#cb12-8" aria-hidden="true" tabindex="-1"></a>        <span class="co">// do something</span></span>
-<span id="cb12-9"><a href="#cb12-9" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>,</span>
-<span id="cb12-10"><a href="#cb12-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">error</span>.QueueNotFound =&gt; <span class="op">{</span></span>
-<span id="cb12-11"><a href="#cb12-11" aria-hidden="true" tabindex="-1"></a>        <span class="co">// do something</span></span>
-<span id="cb12-12"><a href="#cb12-12" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>,</span>
-<span id="cb12-13"><a href="#cb12-13" aria-hidden="true" tabindex="-1"></a>    <span class="co">// and all the other error options ...</span></span>
-<span id="cb12-14"><a href="#cb12-14" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb13"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true" tabindex="-1"></a><span class="kw">if</span> (add_tasks_to_queue(&amp;queue, tasks)) |_| <span class="op">{</span></span>
+<span id="cb13-2"><a href="#cb13-2" aria-hidden="true" tabindex="-1"></a>    distribute_tasks(&amp;queue);</span>
+<span id="cb13-3"><a href="#cb13-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span> <span class="kw">else</span> |err| <span class="kw">switch</span> (err) <span class="op">{</span></span>
+<span id="cb13-4"><a href="#cb13-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">error</span>.InvalidTaskName =&gt; <span class="op">{</span></span>
+<span id="cb13-5"><a href="#cb13-5" aria-hidden="true" tabindex="-1"></a>        <span class="co">// do something</span></span>
+<span id="cb13-6"><a href="#cb13-6" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>,</span>
+<span id="cb13-7"><a href="#cb13-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">error</span>.TimeoutTooBig =&gt; <span class="op">{</span></span>
+<span id="cb13-8"><a href="#cb13-8" aria-hidden="true" tabindex="-1"></a>        <span class="co">// do something</span></span>
+<span id="cb13-9"><a href="#cb13-9" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>,</span>
+<span id="cb13-10"><a href="#cb13-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">error</span>.QueueNotFound =&gt; <span class="op">{</span></span>
+<span id="cb13-11"><a href="#cb13-11" aria-hidden="true" tabindex="-1"></a>        <span class="co">// do something</span></span>
+<span id="cb13-12"><a href="#cb13-12" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>,</span>
+<span id="cb13-13"><a href="#cb13-13" aria-hidden="true" tabindex="-1"></a>    <span class="co">// and all the other error options ...</span></span>
+<span id="cb13-14"><a href="#cb13-14" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
 <section id="sec-errdefer2" class="level3" data-number="10.2.4">
@@ -554,14 +558,14 @@ <h3 data-number="10.2.4" class="anchored" data-anchor-id="sec-errdefer2"><span c
 <p>The basic idea is to provide an expression to the <code>errdefer</code> keyword. Then, <code>errdefer</code> executes this expression if, and only if, an error occurs during the execution of the current scope. In the example below, we are using an allocator object (that we have presented at <a href="01-memory.html#sec-allocators" class="quarto-xref"><span>Section 3.3</span></a>) to create a new <code>User</code> object. If we are successful in creating and registering this new user, this <code>create_user()</code> function will return this new <code>User</code> object as its return value.</p>
 <p>However, if for some reason, an error value is generated by some expression that is after the <code>errdefer</code> line, for example, in the <code>db.add(user)</code> expression, the expression registered by <code>errdefer</code> get’s executed before the error value is returned from the function, and before the program enters in panic mode and stops the current execution.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb13"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> create_user(db: Database, allocator: Allocator) !User <span class="op">{</span></span>
-<span id="cb13-2"><a href="#cb13-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> user = <span class="kw">try</span> allocator.create(User);</span>
-<span id="cb13-3"><a href="#cb13-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">errdefer</span> allocator.destroy(user);</span>
-<span id="cb13-4"><a href="#cb13-4" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb13-5"><a href="#cb13-5" aria-hidden="true" tabindex="-1"></a>    <span class="co">// Register new user in the Database.</span></span>
-<span id="cb13-6"><a href="#cb13-6" aria-hidden="true" tabindex="-1"></a>    _ = <span class="kw">try</span> db.register_user(user);</span>
-<span id="cb13-7"><a href="#cb13-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> user;</span>
-<span id="cb13-8"><a href="#cb13-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb14"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> create_user(db: Database, allocator: Allocator) !User <span class="op">{</span></span>
+<span id="cb14-2"><a href="#cb14-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> user = <span class="kw">try</span> allocator.create(User);</span>
+<span id="cb14-3"><a href="#cb14-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">errdefer</span> allocator.destroy(user);</span>
+<span id="cb14-4"><a href="#cb14-4" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb14-5"><a href="#cb14-5" aria-hidden="true" tabindex="-1"></a>    <span class="co">// Register new user in the Database.</span></span>
+<span id="cb14-6"><a href="#cb14-6" aria-hidden="true" tabindex="-1"></a>    _ = <span class="kw">try</span> db.register_user(user);</span>
+<span id="cb14-7"><a href="#cb14-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> user;</span>
+<span id="cb14-8"><a href="#cb14-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>By using <code>errdefer</code> to destroy the <code>user</code> object that we have just created, we guarantee that the memory allocated for this <code>user</code> object get’s freed, before the execution of the program stops. Because if the expression <code>try db.add(user)</code> returns an error value, the execution of our program stops, and we lose all references and control over the memory that we have allocated for the <code>user</code> object. As a result, if we do not free the memory associated with the <code>user</code> object before the program stops, we cannot free this memory anymore. We simply lose our chance to do the right thing. That is why <code>errdefer</code> is essential in this situation.</p>
 <p>Just to state clearly the differences between <code>defer</code> and <code>errdefer</code> (which I described at <a href="03-structs.html#sec-defer" class="quarto-xref"><span>Section 2.1.3</span></a> and <a href="03-structs.html#sec-errdefer1" class="quarto-xref"><span>Section 2.1.4</span></a>), it might be worth to discuss the subject a bit further. You might still have the question “why use <code>errdefer</code> if we can use <code>defer</code> instead?” in your mind.</p>
@@ -581,30 +585,30 @@ <h2 data-number="10.3" class="anchored" data-anchor-id="sec-unions"><span class=
 <p>The union <code>LakeTarget</code> defined below allows the <code>lake_target</code> argument of <code>send_event()</code> to be either an object of type <code>AzureBlob</code>, or type <code>AmazonS3</code>, or type <code>GoogleGCP</code>. This union allows the <code>send_event()</code> function to receive an object of any of these three types as input in the <code>lake_target</code> argument.</p>
 <p>Remember that each of these three types (<code>AmazonS3</code>, <code>GoogleGCP</code> and <code>AzureBlob</code>) are separate structs that we have defined in our source code. So, at first glance, they are separate data types in our source code. But is the <code>union</code> keyword that unifies them into a single data type called <code>LakeTarget</code>.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb14"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> LakeTarget = <span class="kw">union</span> <span class="op">{</span></span>
-<span id="cb14-2"><a href="#cb14-2" aria-hidden="true" tabindex="-1"></a>    azure: AzureBlob,</span>
-<span id="cb14-3"><a href="#cb14-3" aria-hidden="true" tabindex="-1"></a>    amazon: AmazonS3,</span>
-<span id="cb14-4"><a href="#cb14-4" aria-hidden="true" tabindex="-1"></a>    google: GoogleGCP,</span>
-<span id="cb14-5"><a href="#cb14-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
-<span id="cb14-6"><a href="#cb14-6" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb14-7"><a href="#cb14-7" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> send_event(</span>
-<span id="cb14-8"><a href="#cb14-8" aria-hidden="true" tabindex="-1"></a>    event: Event,</span>
-<span id="cb14-9"><a href="#cb14-9" aria-hidden="true" tabindex="-1"></a>    lake_target: LakeTarget</span>
-<span id="cb14-10"><a href="#cb14-10" aria-hidden="true" tabindex="-1"></a>) <span class="dt">bool</span> <span class="op">{</span></span>
-<span id="cb14-11"><a href="#cb14-11" aria-hidden="true" tabindex="-1"></a>    <span class="co">// body of the function ...</span></span>
-<span id="cb14-12"><a href="#cb14-12" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb15"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb15-1"><a href="#cb15-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> LakeTarget = <span class="kw">union</span> <span class="op">{</span></span>
+<span id="cb15-2"><a href="#cb15-2" aria-hidden="true" tabindex="-1"></a>    azure: AzureBlob,</span>
+<span id="cb15-3"><a href="#cb15-3" aria-hidden="true" tabindex="-1"></a>    amazon: AmazonS3,</span>
+<span id="cb15-4"><a href="#cb15-4" aria-hidden="true" tabindex="-1"></a>    google: GoogleGCP,</span>
+<span id="cb15-5"><a href="#cb15-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
+<span id="cb15-6"><a href="#cb15-6" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb15-7"><a href="#cb15-7" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> send_event(</span>
+<span id="cb15-8"><a href="#cb15-8" aria-hidden="true" tabindex="-1"></a>    event: Event,</span>
+<span id="cb15-9"><a href="#cb15-9" aria-hidden="true" tabindex="-1"></a>    lake_target: LakeTarget</span>
+<span id="cb15-10"><a href="#cb15-10" aria-hidden="true" tabindex="-1"></a>) <span class="dt">bool</span> <span class="op">{</span></span>
+<span id="cb15-11"><a href="#cb15-11" aria-hidden="true" tabindex="-1"></a>    <span class="co">// body of the function ...</span></span>
+<span id="cb15-12"><a href="#cb15-12" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>An union definition is composed by a list of data members. Each data member is of a specific data type. In the example above, the <code>LakeTarget</code> union have three data members (<code>azure</code>, <code>amazon</code>, <code>google</code>). When you instantiate an object that uses an union type, you can only use one of its data members in this instantiation.</p>
 <p>You could also interpret this as: only one data member of an union type can be activated at a time, the other data members remain deactivated and unaccessible. For example, if you create a <code>LakeTarget</code> object that uses the <code>azure</code> data member, you can no longer use or access the data members <code>google</code> or <code>amazon</code>. It is like if these other data members didn’t exist at all in the <code>LakeTarget</code> type.</p>
 <p>You can see this logic in the example below. Notice that, we first instantiate the union object using the <code>azure</code> data member. As a result, this <code>target</code> object contains only the <code>azure</code> data member inside of it. Only this data member is active in this object. That is why the last line in this code example is invalid. Because we are trying to instantiate the data member <code>google</code>, which is currently inactive for this <code>target</code> object, and as a result, the program enters in panic mode warning us about this mistake through a loud error message.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb15"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb15-1"><a href="#cb15-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> target = LakeTarget <span class="op">{</span></span>
-<span id="cb15-2"><a href="#cb15-2" aria-hidden="true" tabindex="-1"></a>    .azure = AzureBlob.init()</span>
-<span id="cb15-3"><a href="#cb15-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
-<span id="cb15-4"><a href="#cb15-4" aria-hidden="true" tabindex="-1"></a><span class="co">// Only the `azure` data member exist inside</span></span>
-<span id="cb15-5"><a href="#cb15-5" aria-hidden="true" tabindex="-1"></a><span class="co">// the `target` object, and, as a result, this</span></span>
-<span id="cb15-6"><a href="#cb15-6" aria-hidden="true" tabindex="-1"></a><span class="co">// line below is invalid:</span></span>
-<span id="cb15-7"><a href="#cb15-7" aria-hidden="true" tabindex="-1"></a>target.google = GoogleGCP.init();</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb16"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> target = LakeTarget <span class="op">{</span></span>
+<span id="cb16-2"><a href="#cb16-2" aria-hidden="true" tabindex="-1"></a>    .azure = AzureBlob.init()</span>
+<span id="cb16-3"><a href="#cb16-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
+<span id="cb16-4"><a href="#cb16-4" aria-hidden="true" tabindex="-1"></a><span class="co">// Only the `azure` data member exist inside</span></span>
+<span id="cb16-5"><a href="#cb16-5" aria-hidden="true" tabindex="-1"></a><span class="co">// the `target` object, and, as a result, this</span></span>
+<span id="cb16-6"><a href="#cb16-6" aria-hidden="true" tabindex="-1"></a><span class="co">// line below is invalid:</span></span>
+<span id="cb16-7"><a href="#cb16-7" aria-hidden="true" tabindex="-1"></a>target.google = GoogleGCP.init();</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>thread 2177312 panic: access of union field 'google' while
     field 'azure' is active:
@@ -613,21 +617,21 @@ <h2 data-number="10.3" class="anchored" data-anchor-id="sec-unions"><span class=
 <p>So, when you instantiate an union object, you must choose one of the data types (or, one of the data members) listed in the union type. In the example above, I choose to use the <code>azure</code> data member, and, as a result, all other data members were automatically deactivated, and you can no longer use them after you instantiate the object.</p>
 <p>You can activate another data member by completely redefining the entire enum object. In the example below, I initially use the <code>azure</code> data member. But then, I redefine the <code>target</code> object to use a new <code>LakeTarget</code> object, which uses the <code>google</code> data member.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb17"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> target = LakeTarget <span class="op">{</span></span>
-<span id="cb17-2"><a href="#cb17-2" aria-hidden="true" tabindex="-1"></a>    .azure = AzureBlob.init()</span>
-<span id="cb17-3"><a href="#cb17-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
-<span id="cb17-4"><a href="#cb17-4" aria-hidden="true" tabindex="-1"></a>target = LakeTarget <span class="op">{</span></span>
-<span id="cb17-5"><a href="#cb17-5" aria-hidden="true" tabindex="-1"></a>    .google = GoogleGCP.init()</span>
-<span id="cb17-6"><a href="#cb17-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb18"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb18-1"><a href="#cb18-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> target = LakeTarget <span class="op">{</span></span>
+<span id="cb18-2"><a href="#cb18-2" aria-hidden="true" tabindex="-1"></a>    .azure = AzureBlob.init()</span>
+<span id="cb18-3"><a href="#cb18-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
+<span id="cb18-4"><a href="#cb18-4" aria-hidden="true" tabindex="-1"></a>target = LakeTarget <span class="op">{</span></span>
+<span id="cb18-5"><a href="#cb18-5" aria-hidden="true" tabindex="-1"></a>    .google = GoogleGCP.init()</span>
+<span id="cb18-6"><a href="#cb18-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>A curious fact about union types, is that, at first, you cannot use them in switch statements (which were presented at <a href="03-structs.html#sec-switch" class="quarto-xref"><span>Section 2.1.2</span></a>). In other words, if you have an object of type <code>LakeTarget</code> for example, you cannot give this object as input to a switch statement.</p>
 <p>But what if you really need to do so? What if you actually need to provide an “union object” to a switch statement? The answer to this question relies on another special type in Zig, which are the <em>tagged unions</em>. To create a tagged union, all you have to do is to add an enum type into your union declaration.</p>
 <p>As an example of a tagged union in Zig, take the <code>Registry</code> type exposed below. This type comes from the <a href="https://github.com/ziglang/zig/blob/30b4a87db711c368853b3eff8e214ab681810ef9/tools/spirv/grammar.zig"><code>grammar.zig</code> module</a><a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a> from the Zig repository. This union type lists different types of registries. But notice this time, the use of <code>(enum)</code> after the <code>union</code> keyword. This is what makes this union type a tagged union. By being a tagged union, an object of this <code>Registry</code> type can be used as input in a switch statement. This is all you have to do. Just add <code>(enum)</code> to your <code>union</code> declaration, and you can use it in switch statements.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb18"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb18-1"><a href="#cb18-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">const</span> Registry = <span class="kw">union</span>(<span class="kw">enum</span>) <span class="op">{</span></span>
-<span id="cb18-2"><a href="#cb18-2" aria-hidden="true" tabindex="-1"></a>    core: CoreRegistry,</span>
-<span id="cb18-3"><a href="#cb18-3" aria-hidden="true" tabindex="-1"></a>    extension: ExtensionRegistry,</span>
-<span id="cb18-4"><a href="#cb18-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb19"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb19-1"><a href="#cb19-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">const</span> Registry = <span class="kw">union</span>(<span class="kw">enum</span>) <span class="op">{</span></span>
+<span id="cb19-2"><a href="#cb19-2" aria-hidden="true" tabindex="-1"></a>    core: CoreRegistry,</span>
+<span id="cb19-3"><a href="#cb19-3" aria-hidden="true" tabindex="-1"></a>    extension: ExtensionRegistry,</span>
+<span id="cb19-4"><a href="#cb19-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 
 
diff --git a/docs/Chapters/10-stack-project.html b/docs/Chapters/10-stack-project.html
index 5aa73bba..b19573e2 100644
--- a/docs/Chapters/10-stack-project.html
+++ b/docs/Chapters/10-stack-project.html
@@ -369,31 +369,35 @@ <h3 data-number="12.1.1" class="anchored" data-anchor-id="applying-over-a-functi
 <span id="cb1-4"><a href="#cb1-4" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="st">"test comptime"</span> <span class="op">{</span></span>
 <span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a>    _ = twice(<span class="dv">5678</span>);</span>
 <span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="cell-output cell-output-stdout">
+<pre><code>1/1 file1054863994c6f.test.test comptime...OKAll 1
+  1 tests passed.</code></pre>
+</div>
 </div>
 <p>But what if we provide a number that is not compile-time known to this function? For example, we might provide a different input value to this function depending on the target OS of our compilation process. The code example below demonstrates such case.</p>
 <p>Because the value of the object <code>n</code> is determined at runtime, we cannot provide this object as input to the <code>twice()</code> function. The <code>zig</code> compiler will not allow it, because we marked the <code>num</code> argument as a “comptime argument”. That is why the <code>zig</code> compiler raises the compile-time error exposed below:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb2"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> builtin = <span class="bu">@import</span>(<span class="st">"builtin"</span>);</span>
-<span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> twice(<span class="kw">comptime</span> num: <span class="dt">u32</span>) <span class="dt">u32</span> <span class="op">{</span></span>
-<span id="cb2-3"><a href="#cb2-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> num * <span class="dv">2</span>;</span>
-<span id="cb2-4"><a href="#cb2-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
-<span id="cb2-5"><a href="#cb2-5" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="st">"test comptime"</span> <span class="op">{</span></span>
-<span id="cb2-6"><a href="#cb2-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> n: <span class="dt">u32</span> = <span class="cn">undefined</span>;</span>
-<span id="cb2-7"><a href="#cb2-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> (builtin.target.os.tag == .windows) <span class="op">{</span></span>
-<span id="cb2-8"><a href="#cb2-8" aria-hidden="true" tabindex="-1"></a>        n = <span class="dv">1234</span>;</span>
-<span id="cb2-9"><a href="#cb2-9" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span> <span class="kw">else</span> <span class="op">{</span></span>
-<span id="cb2-10"><a href="#cb2-10" aria-hidden="true" tabindex="-1"></a>        n = <span class="dv">5678</span>;</span>
-<span id="cb2-11"><a href="#cb2-11" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb2-12"><a href="#cb2-12" aria-hidden="true" tabindex="-1"></a>    _ = twice(n);</span>
-<span id="cb2-13"><a href="#cb2-13" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb3"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> builtin = <span class="bu">@import</span>(<span class="st">"builtin"</span>);</span>
+<span id="cb3-2"><a href="#cb3-2" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> twice(<span class="kw">comptime</span> num: <span class="dt">u32</span>) <span class="dt">u32</span> <span class="op">{</span></span>
+<span id="cb3-3"><a href="#cb3-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> num * <span class="dv">2</span>;</span>
+<span id="cb3-4"><a href="#cb3-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
+<span id="cb3-5"><a href="#cb3-5" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="st">"test comptime"</span> <span class="op">{</span></span>
+<span id="cb3-6"><a href="#cb3-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> n: <span class="dt">u32</span> = <span class="cn">undefined</span>;</span>
+<span id="cb3-7"><a href="#cb3-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> (builtin.target.os.tag == .windows) <span class="op">{</span></span>
+<span id="cb3-8"><a href="#cb3-8" aria-hidden="true" tabindex="-1"></a>        n = <span class="dv">1234</span>;</span>
+<span id="cb3-9"><a href="#cb3-9" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span> <span class="kw">else</span> <span class="op">{</span></span>
+<span id="cb3-10"><a href="#cb3-10" aria-hidden="true" tabindex="-1"></a>        n = <span class="dv">5678</span>;</span>
+<span id="cb3-11"><a href="#cb3-11" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb3-12"><a href="#cb3-12" aria-hidden="true" tabindex="-1"></a>    _ = twice(n);</span>
+<span id="cb3-13"><a href="#cb3-13" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>t.zig:12:16: error: runtime-known argument passed to comptime parameter </code></pre>
 <p>Comptime arguments are frequently used on functions that return some sort of generic structure. In fact, <code>comptime</code> is the essence (or the basis) to make generics in Zig. We are going to talk more about generics at <a href="#sec-generics" class="quarto-xref"><span>Section 12.2</span></a>.</p>
 <p>For now, let’s take a look at this code example from <span class="citation" data-cites="karlseguin_generics">Seguin (<a href="../references.html#ref-karlseguin_generics" role="doc-biblioref">2024</a>)</span>. You can see that this <code>IntArray()</code> function have one argument named <code>length</code>. This argument is marked as comptime, and receives a value of type <code>usize</code> as input. So the value given to this argument must be compile-time known. We can also see that this function returns an array of <code>i64</code> values as output.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb4"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> IntArray(<span class="kw">comptime</span> length: <span class="dt">usize</span>) <span class="dt">type</span> <span class="op">{</span></span>
-<span id="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> [length]<span class="dt">i64</span>;</span>
-<span id="cb4-3"><a href="#cb4-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb5"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> IntArray(<span class="kw">comptime</span> length: <span class="dt">usize</span>) <span class="dt">type</span> <span class="op">{</span></span>
+<span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> [length]<span class="dt">i64</span>;</span>
+<span id="cb5-3"><a href="#cb5-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>Now, the key component of this function is the <code>length</code> argument. This argument is used to determine the size of the array that is produced by the function. Let’s think about the consequences of that. If the size of the array is dependent on the value assigned to the <code>length</code> argument, this means that the data type of the output of the function depends on the value of this <code>length</code> argument.</p>
 <p>Let this statement sink for a bit in your mind. As I described at <a href="01-zig-weird.html#sec-root-file" class="quarto-xref"><span>Section 1.2.2</span></a>, Zig is a strongly-typed language, especially on function declarations. So every time we write a function in Zig, we have to annotate the data type of the value returned by the function. But how can we do that, if this data type depends on the value given to the argument of the function?</p>
@@ -409,18 +413,22 @@ <h3 data-number="12.1.2" class="anchored" data-anchor-id="applying-over-an-expre
 <p>Take this example from the official documentation of Zig <span class="citation" data-cites="zigdocs">(<a href="../references.html#ref-zigdocs" role="doc-biblioref">Zig Software Foundation 2024</a>)</span>. We are executing the same <code>fibonacci()</code> function both at runtime, and, at compile-time. The function is by default executed at runtime, but because we use the <code>comptime</code> keyword at the second “try expression”, this expression is executed at compile-time.</p>
 <p>This might be a bit confusing for some people. Yes! When I say that this expression is executed at compile-time, I mean that this expression is compiled and executed while the <code>zig</code> compiler is compiling your Zig source code.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb5"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = <span class="bu">@import</span>(<span class="st">"std"</span>).testing.expect;</span>
-<span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> fibonacci(index: <span class="dt">u32</span>) <span class="dt">u32</span> <span class="op">{</span></span>
-<span id="cb5-3"><a href="#cb5-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> (index &lt; <span class="dv">2</span>) <span class="kw">return</span> index;</span>
-<span id="cb5-4"><a href="#cb5-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> fibonacci(index - <span class="dv">1</span>) + fibonacci(index - <span class="dv">2</span>);</span>
-<span id="cb5-5"><a href="#cb5-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
-<span id="cb5-6"><a href="#cb5-6" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb5-7"><a href="#cb5-7" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="st">"fibonacci"</span> <span class="op">{</span></span>
-<span id="cb5-8"><a href="#cb5-8" aria-hidden="true" tabindex="-1"></a>    <span class="co">// test fibonacci at run-time</span></span>
-<span id="cb5-9"><a href="#cb5-9" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(fibonacci(<span class="dv">7</span>) == <span class="dv">13</span>);</span>
-<span id="cb5-10"><a href="#cb5-10" aria-hidden="true" tabindex="-1"></a>    <span class="co">// test fibonacci at compile-time</span></span>
-<span id="cb5-11"><a href="#cb5-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> <span class="kw">comptime</span> expect(fibonacci(<span class="dv">7</span>) == <span class="dv">13</span>);</span>
-<span id="cb5-12"><a href="#cb5-12" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb6"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = <span class="bu">@import</span>(<span class="st">"std"</span>).testing.expect;</span>
+<span id="cb6-2"><a href="#cb6-2" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> fibonacci(index: <span class="dt">u32</span>) <span class="dt">u32</span> <span class="op">{</span></span>
+<span id="cb6-3"><a href="#cb6-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> (index &lt; <span class="dv">2</span>) <span class="kw">return</span> index;</span>
+<span id="cb6-4"><a href="#cb6-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> fibonacci(index - <span class="dv">1</span>) + fibonacci(index - <span class="dv">2</span>);</span>
+<span id="cb6-5"><a href="#cb6-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
+<span id="cb6-6"><a href="#cb6-6" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb6-7"><a href="#cb6-7" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="st">"fibonacci"</span> <span class="op">{</span></span>
+<span id="cb6-8"><a href="#cb6-8" aria-hidden="true" tabindex="-1"></a>    <span class="co">// test fibonacci at run-time</span></span>
+<span id="cb6-9"><a href="#cb6-9" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(fibonacci(<span class="dv">7</span>) == <span class="dv">13</span>);</span>
+<span id="cb6-10"><a href="#cb6-10" aria-hidden="true" tabindex="-1"></a>    <span class="co">// test fibonacci at compile-time</span></span>
+<span id="cb6-11"><a href="#cb6-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> <span class="kw">comptime</span> expect(fibonacci(<span class="dv">7</span>) == <span class="dv">13</span>);</span>
+<span id="cb6-12"><a href="#cb6-12" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="cell-output cell-output-stdout">
+<pre><code>1/1 file10548bb87337.test.fibonacci...OKAll 1 test
+  ts passed.</code></pre>
+</div>
 </div>
 <p>A lot of your Zig source code might be potentially executed at compile-time, because the <code>zig</code> compiler can figure it out the output of some expressions. Especially if these expressions depends only at compile-time known values. We have talked about this at <a href="01-memory.html#sec-compile-time" class="quarto-xref"><span>Section 3.1.1</span></a>.</p>
 <p>But when you use the <code>comptime</code> keyword on an expression, there is no “it might be executed at compile-time” anymore. With the <code>comptime</code> keyword you are ordering the <code>zig</code> compiler to execute this expression at compile-time. You are imposing this rule, it is guaranteed that the compiler will always execute it at compile-time. Or, at least, the compiler will try to execute it. If the compiler cannot execute the expression for whatever reason, the compiler will raise a compilation error.</p>
@@ -430,22 +438,26 @@ <h3 data-number="12.1.3" class="anchored" data-anchor-id="applying-over-a-block"
 <p>Blocks were described at <a href="01-zig-weird.html#sec-blocks" class="quarto-xref"><span>Section 1.7</span></a>. When you apply the <code>comptime</code> keyword over a block of expressions, you get essentially the same effect when you apply this keyword to a single expression. That is, the entire block of expressions is executed at compile-time by the <code>zig</code> compiler.</p>
 <p>In the example below, we mark the block labeled of <code>blk</code> as a comptime block, and, therefore, the expressions inside this block are executed at compile-time.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb6"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = <span class="bu">@import</span>(<span class="st">"std"</span>).testing.expect;</span>
-<span id="cb6-2"><a href="#cb6-2" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> fibonacci(index: <span class="dt">u32</span>) <span class="dt">u32</span> <span class="op">{</span></span>
-<span id="cb6-3"><a href="#cb6-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> (index &lt; <span class="dv">2</span>) <span class="kw">return</span> index;</span>
-<span id="cb6-4"><a href="#cb6-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> fibonacci(index - <span class="dv">1</span>) + fibonacci(index - <span class="dv">2</span>);</span>
-<span id="cb6-5"><a href="#cb6-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
-<span id="cb6-6"><a href="#cb6-6" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb6-7"><a href="#cb6-7" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="st">"fibonacci in a block"</span> <span class="op">{</span></span>
-<span id="cb6-8"><a href="#cb6-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> x = <span class="kw">comptime</span> blk: <span class="op">{</span></span>
-<span id="cb6-9"><a href="#cb6-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> n1 = <span class="dv">5</span>;</span>
-<span id="cb6-10"><a href="#cb6-10" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> n2 = <span class="dv">2</span>;</span>
-<span id="cb6-11"><a href="#cb6-11" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> n3 = n1 + n2;</span>
-<span id="cb6-12"><a href="#cb6-12" aria-hidden="true" tabindex="-1"></a>        <span class="kw">try</span> expect(fibonacci(n3) == <span class="dv">13</span>);</span>
-<span id="cb6-13"><a href="#cb6-13" aria-hidden="true" tabindex="-1"></a>        <span class="kw">break</span> :blk n3;</span>
-<span id="cb6-14"><a href="#cb6-14" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>;</span>
-<span id="cb6-15"><a href="#cb6-15" aria-hidden="true" tabindex="-1"></a>    _ = x;</span>
-<span id="cb6-16"><a href="#cb6-16" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb8"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = <span class="bu">@import</span>(<span class="st">"std"</span>).testing.expect;</span>
+<span id="cb8-2"><a href="#cb8-2" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> fibonacci(index: <span class="dt">u32</span>) <span class="dt">u32</span> <span class="op">{</span></span>
+<span id="cb8-3"><a href="#cb8-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> (index &lt; <span class="dv">2</span>) <span class="kw">return</span> index;</span>
+<span id="cb8-4"><a href="#cb8-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> fibonacci(index - <span class="dv">1</span>) + fibonacci(index - <span class="dv">2</span>);</span>
+<span id="cb8-5"><a href="#cb8-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
+<span id="cb8-6"><a href="#cb8-6" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb8-7"><a href="#cb8-7" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="st">"fibonacci in a block"</span> <span class="op">{</span></span>
+<span id="cb8-8"><a href="#cb8-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> x = <span class="kw">comptime</span> blk: <span class="op">{</span></span>
+<span id="cb8-9"><a href="#cb8-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> n1 = <span class="dv">5</span>;</span>
+<span id="cb8-10"><a href="#cb8-10" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> n2 = <span class="dv">2</span>;</span>
+<span id="cb8-11"><a href="#cb8-11" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> n3 = n1 + n2;</span>
+<span id="cb8-12"><a href="#cb8-12" aria-hidden="true" tabindex="-1"></a>        <span class="kw">try</span> expect(fibonacci(n3) == <span class="dv">13</span>);</span>
+<span id="cb8-13"><a href="#cb8-13" aria-hidden="true" tabindex="-1"></a>        <span class="kw">break</span> :blk n3;</span>
+<span id="cb8-14"><a href="#cb8-14" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>;</span>
+<span id="cb8-15"><a href="#cb8-15" aria-hidden="true" tabindex="-1"></a>    _ = x;</span>
+<span id="cb8-16"><a href="#cb8-16" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="cell-output cell-output-stdout">
+<pre><code>1/1 file105482dc0b880.test.fibonacci in a block...
+  .OKAll 1 tests passed.</code></pre>
+</div>
 </div>
 </section>
 </section>
@@ -460,23 +472,30 @@ <h3 data-number="12.2.1" class="anchored" data-anchor-id="sec-generic-fun"><span
 <p>Because we have used this <code>type</code> keyword in the <code>T</code> argument, we are telling the <code>zig</code> compiler that this <code>T</code> argument will receive some data type as input. Also notice the use of the <code>comptime</code> keyword in this argument. As I described at <a href="#sec-comptime" class="quarto-xref"><span>Section 12.1</span></a>, every time you use this keyword in a function argument, this means that the value of this argument must be known at compile-time. This makes sense, right? Because there is no data type that is not known at compile-time.</p>
 <p>Think about this. Every data type that you will ever write is always known at compile-time. Especially because data types are an essential information for the compiler to actually compile your source code. Having this in mind, makes sense to mark this argument as a comptime argument.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb7"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> max(<span class="kw">comptime</span> T: <span class="dt">type</span>, a: T, b: T) T <span class="op">{</span></span>
-<span id="cb7-2"><a href="#cb7-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> <span class="kw">if</span> (a &gt; b) a <span class="kw">else</span> b;</span>
-<span id="cb7-3"><a href="#cb7-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb10"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> max(<span class="kw">comptime</span> T: <span class="dt">type</span>, a: T, b: T) T <span class="op">{</span></span>
+<span id="cb10-2"><a href="#cb10-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> <span class="kw">if</span> (a &gt; b) a <span class="kw">else</span> b;</span>
+<span id="cb10-3"><a href="#cb10-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="cell-output cell-output-stdout">
+<pre><code>All 0 tests passed.</code></pre>
+</div>
 </div>
 <p>Also notice that the value of the <code>T</code> argument is actually used to define the data type of the other arguments in the function, <code>a</code> and <code>b</code>, and also at the return type annotation of the function. That is, the data type of these arguments (<code>a</code> and <code>b</code>), and, the return data type of the function itself, are determined by the input value given to the <code>T</code> argument.</p>
 <p>As a result, we have a generic function that works with different data types. For example, I can provide <code>u8</code> values to this <code>max()</code> function, and it will work as expected. But if I provide <code>f64</code> values instead, it will also work as expected. Without a generic function, I would have to write a different <code>max()</code> function for each one of the data types that I wanted to use. This generic function provides a very useful shortcut for us.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb8"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb8-2"><a href="#cb8-2" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> max(<span class="kw">comptime</span> T: <span class="dt">type</span>, a: T, b: T) T <span class="op">{</span></span>
-<span id="cb8-3"><a href="#cb8-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> <span class="kw">if</span> (a &gt; b) a <span class="kw">else</span> b;</span>
-<span id="cb8-4"><a href="#cb8-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
-<span id="cb8-5"><a href="#cb8-5" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="st">"test max"</span> <span class="op">{</span></span>
-<span id="cb8-6"><a href="#cb8-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> n1 = max(<span class="dt">u8</span>, <span class="dv">4</span>, <span class="dv">10</span>);</span>
-<span id="cb8-7"><a href="#cb8-7" aria-hidden="true" tabindex="-1"></a>    std.debug.print(<span class="st">"Max n1: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>n1<span class="op">}</span>);</span>
-<span id="cb8-8"><a href="#cb8-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> n2 = max(<span class="dt">f64</span>, <span class="fl">89.24</span>, <span class="fl">64.001</span>);</span>
-<span id="cb8-9"><a href="#cb8-9" aria-hidden="true" tabindex="-1"></a>    std.debug.print(<span class="st">"Max n2: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>n2<span class="op">}</span>);</span>
-<span id="cb8-10"><a href="#cb8-10" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb12"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb12-2"><a href="#cb12-2" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> max(<span class="kw">comptime</span> T: <span class="dt">type</span>, a: T, b: T) T <span class="op">{</span></span>
+<span id="cb12-3"><a href="#cb12-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> <span class="kw">if</span> (a &gt; b) a <span class="kw">else</span> b;</span>
+<span id="cb12-4"><a href="#cb12-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
+<span id="cb12-5"><a href="#cb12-5" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="st">"test max"</span> <span class="op">{</span></span>
+<span id="cb12-6"><a href="#cb12-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> n1 = max(<span class="dt">u8</span>, <span class="dv">4</span>, <span class="dv">10</span>);</span>
+<span id="cb12-7"><a href="#cb12-7" aria-hidden="true" tabindex="-1"></a>    std.debug.print(<span class="st">"Max n1: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>n1<span class="op">}</span>);</span>
+<span id="cb12-8"><a href="#cb12-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> n2 = max(<span class="dt">f64</span>, <span class="fl">89.24</span>, <span class="fl">64.001</span>);</span>
+<span id="cb12-9"><a href="#cb12-9" aria-hidden="true" tabindex="-1"></a>    std.debug.print(<span class="st">"Max n2: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>n2<span class="op">}</span>);</span>
+<span id="cb12-10"><a href="#cb12-10" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="cell-output cell-output-stdout">
+<pre><code>1/1 file105482071daf3.test.test max...Max n1: 10Ma
+  ax n2: 89.24OKAll 1 tests passed.</code></pre>
+</div>
 </div>
 <pre><code>Max n1: 10
 Max n2: 89.24</code></pre>
@@ -514,24 +533,24 @@ <h2 data-number="12.4" class="anchored" data-anchor-id="writing-the-stack-data-s
 <p>Also notice in our <code>Stack</code> struct that we have three other data members: <code>capacity</code>, <code>length</code> and <code>allocator</code>. The <code>capacity</code> member contains the capacity of the underlying array that stores the values in the stack. The <code>length</code> contains the number of values that are currently being stored in the stack. And the <code>allocator</code> contains the allocator object that will be used by the stack structure whenever it needs to allocate more space for the values that are being stored.</p>
 <p>We begin by defining an <code>init()</code> method of this struct, which is going to be responsible for instantiating a <code>Stack</code> object. Notice that, inside this <code>init()</code> method, we start by allocating an array with the capacity specified in the <code>capacity</code> argument.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb10"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb10-2"><a href="#cb10-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Allocator = std.mem.Allocator;</span>
-<span id="cb10-3"><a href="#cb10-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Stack = <span class="kw">struct</span> <span class="op">{</span></span>
-<span id="cb10-4"><a href="#cb10-4" aria-hidden="true" tabindex="-1"></a>    items: []<span class="dt">u32</span>,</span>
-<span id="cb10-5"><a href="#cb10-5" aria-hidden="true" tabindex="-1"></a>    capacity: <span class="dt">usize</span>,</span>
-<span id="cb10-6"><a href="#cb10-6" aria-hidden="true" tabindex="-1"></a>    length: <span class="dt">usize</span>,</span>
-<span id="cb10-7"><a href="#cb10-7" aria-hidden="true" tabindex="-1"></a>    allocator: Allocator,</span>
-<span id="cb10-8"><a href="#cb10-8" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb10-9"><a href="#cb10-9" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> init(allocator: Allocator, capacity: <span class="dt">usize</span>) !Stack <span class="op">{</span></span>
-<span id="cb10-10"><a href="#cb10-10" aria-hidden="true" tabindex="-1"></a>        <span class="kw">var</span> buf = <span class="kw">try</span> allocator.alloc(<span class="dt">u32</span>, capacity);</span>
-<span id="cb10-11"><a href="#cb10-11" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> .<span class="op">{</span></span>
-<span id="cb10-12"><a href="#cb10-12" aria-hidden="true" tabindex="-1"></a>            .items = buf[<span class="dv">0</span>..],</span>
-<span id="cb10-13"><a href="#cb10-13" aria-hidden="true" tabindex="-1"></a>            .capacity = capacity,</span>
-<span id="cb10-14"><a href="#cb10-14" aria-hidden="true" tabindex="-1"></a>            .length = <span class="dv">0</span>,</span>
-<span id="cb10-15"><a href="#cb10-15" aria-hidden="true" tabindex="-1"></a>            .allocator = allocator,</span>
-<span id="cb10-16"><a href="#cb10-16" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span>;</span>
-<span id="cb10-17"><a href="#cb10-17" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb10-18"><a href="#cb10-18" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb15"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb15-1"><a href="#cb15-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb15-2"><a href="#cb15-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Allocator = std.mem.Allocator;</span>
+<span id="cb15-3"><a href="#cb15-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Stack = <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb15-4"><a href="#cb15-4" aria-hidden="true" tabindex="-1"></a>    items: []<span class="dt">u32</span>,</span>
+<span id="cb15-5"><a href="#cb15-5" aria-hidden="true" tabindex="-1"></a>    capacity: <span class="dt">usize</span>,</span>
+<span id="cb15-6"><a href="#cb15-6" aria-hidden="true" tabindex="-1"></a>    length: <span class="dt">usize</span>,</span>
+<span id="cb15-7"><a href="#cb15-7" aria-hidden="true" tabindex="-1"></a>    allocator: Allocator,</span>
+<span id="cb15-8"><a href="#cb15-8" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb15-9"><a href="#cb15-9" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> init(allocator: Allocator, capacity: <span class="dt">usize</span>) !Stack <span class="op">{</span></span>
+<span id="cb15-10"><a href="#cb15-10" aria-hidden="true" tabindex="-1"></a>        <span class="kw">var</span> buf = <span class="kw">try</span> allocator.alloc(<span class="dt">u32</span>, capacity);</span>
+<span id="cb15-11"><a href="#cb15-11" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> .<span class="op">{</span></span>
+<span id="cb15-12"><a href="#cb15-12" aria-hidden="true" tabindex="-1"></a>            .items = buf[<span class="dv">0</span>..],</span>
+<span id="cb15-13"><a href="#cb15-13" aria-hidden="true" tabindex="-1"></a>            .capacity = capacity,</span>
+<span id="cb15-14"><a href="#cb15-14" aria-hidden="true" tabindex="-1"></a>            .length = <span class="dv">0</span>,</span>
+<span id="cb15-15"><a href="#cb15-15" aria-hidden="true" tabindex="-1"></a>            .allocator = allocator,</span>
+<span id="cb15-16"><a href="#cb15-16" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span>;</span>
+<span id="cb15-17"><a href="#cb15-17" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb15-18"><a href="#cb15-18" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <section id="implementing-the-push-operation" class="level3" data-number="12.4.1">
 <h3 data-number="12.4.1" class="anchored" data-anchor-id="implementing-the-push-operation"><span class="header-section-number">12.4.1</span> Implementing the <code>push</code> operation</h3>
@@ -543,22 +562,22 @@ <h3 data-number="12.4.1" class="anchored" data-anchor-id="implementing-the-push-
 <p>We are using this <code>@memcpy()</code> built-in function to copy the values that are currently stored in the underlying array of the stack object (<code>self.items</code>) into our new and bigger array that we have allocated (<code>new_buf</code>). After we execute this function, the <code>new_buf</code> contains a copy of the values that are present at <code>self.items</code>.</p>
 <p>Now that we have secured a copy of our current values in the <code>new_buf</code> object, we can now free the memory currently allocated at <code>self.items</code>. After that, we just need to assign our new and bigger array to <code>self.items</code>. This is the sequence of steps necessary to expand our array.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb11"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> push(self: *Stack, val: <span class="dt">u32</span>) !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb11-2"><a href="#cb11-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> ((self.length + <span class="dv">1</span>) &gt; self.capacity) <span class="op">{</span></span>
-<span id="cb11-3"><a href="#cb11-3" aria-hidden="true" tabindex="-1"></a>        <span class="kw">var</span> new_buf = <span class="kw">try</span> self.allocator.alloc(</span>
-<span id="cb11-4"><a href="#cb11-4" aria-hidden="true" tabindex="-1"></a>            <span class="dt">u32</span>, self.capacity * <span class="dv">2</span></span>
-<span id="cb11-5"><a href="#cb11-5" aria-hidden="true" tabindex="-1"></a>        );</span>
-<span id="cb11-6"><a href="#cb11-6" aria-hidden="true" tabindex="-1"></a>        <span class="bu">@memcpy</span>(</span>
-<span id="cb11-7"><a href="#cb11-7" aria-hidden="true" tabindex="-1"></a>            new_buf[<span class="dv">0</span>..self.capacity], self.items</span>
-<span id="cb11-8"><a href="#cb11-8" aria-hidden="true" tabindex="-1"></a>        );</span>
-<span id="cb11-9"><a href="#cb11-9" aria-hidden="true" tabindex="-1"></a>        self.allocator.free(self.items);</span>
-<span id="cb11-10"><a href="#cb11-10" aria-hidden="true" tabindex="-1"></a>        self.items = new_buf;</span>
-<span id="cb11-11"><a href="#cb11-11" aria-hidden="true" tabindex="-1"></a>        self.capacity = self.capacity * <span class="dv">2</span>;</span>
-<span id="cb11-12"><a href="#cb11-12" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb11-13"><a href="#cb11-13" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb11-14"><a href="#cb11-14" aria-hidden="true" tabindex="-1"></a>    self.items[self.length] = val;</span>
-<span id="cb11-15"><a href="#cb11-15" aria-hidden="true" tabindex="-1"></a>    self.length += <span class="dv">1</span>;</span>
-<span id="cb11-16"><a href="#cb11-16" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb16"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> push(self: *Stack, val: <span class="dt">u32</span>) !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb16-2"><a href="#cb16-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> ((self.length + <span class="dv">1</span>) &gt; self.capacity) <span class="op">{</span></span>
+<span id="cb16-3"><a href="#cb16-3" aria-hidden="true" tabindex="-1"></a>        <span class="kw">var</span> new_buf = <span class="kw">try</span> self.allocator.alloc(</span>
+<span id="cb16-4"><a href="#cb16-4" aria-hidden="true" tabindex="-1"></a>            <span class="dt">u32</span>, self.capacity * <span class="dv">2</span></span>
+<span id="cb16-5"><a href="#cb16-5" aria-hidden="true" tabindex="-1"></a>        );</span>
+<span id="cb16-6"><a href="#cb16-6" aria-hidden="true" tabindex="-1"></a>        <span class="bu">@memcpy</span>(</span>
+<span id="cb16-7"><a href="#cb16-7" aria-hidden="true" tabindex="-1"></a>            new_buf[<span class="dv">0</span>..self.capacity], self.items</span>
+<span id="cb16-8"><a href="#cb16-8" aria-hidden="true" tabindex="-1"></a>        );</span>
+<span id="cb16-9"><a href="#cb16-9" aria-hidden="true" tabindex="-1"></a>        self.allocator.free(self.items);</span>
+<span id="cb16-10"><a href="#cb16-10" aria-hidden="true" tabindex="-1"></a>        self.items = new_buf;</span>
+<span id="cb16-11"><a href="#cb16-11" aria-hidden="true" tabindex="-1"></a>        self.capacity = self.capacity * <span class="dv">2</span>;</span>
+<span id="cb16-12"><a href="#cb16-12" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb16-13"><a href="#cb16-13" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb16-14"><a href="#cb16-14" aria-hidden="true" tabindex="-1"></a>    self.items[self.length] = val;</span>
+<span id="cb16-15"><a href="#cb16-15" aria-hidden="true" tabindex="-1"></a>    self.length += <span class="dv">1</span>;</span>
+<span id="cb16-16"><a href="#cb16-16" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>After we make sure that we have enough room to store this new value that we are adding to the stack, all we have to do is to assign this value to the top element in this stack, and, increase the value of the <code>length</code> attribute by one. We find the top element in the stack by using the <code>length</code> attribute.</p>
 </section>
@@ -568,12 +587,12 @@ <h3 data-number="12.4.2" class="anchored" data-anchor-id="implementing-the-pop-o
 <p>We just have to find the element in the underlying array that currently represents the top of the stack, and set this element to “undefined”, to indicate that this element is “empty”. After that, we also need to decrease the <code>length</code> attribute of the stack by one.</p>
 <p>If the current length of the stack is zero, it means that there is no values being stored in the stack currently. So, in this case, we could just return from the function and do nothing really. This is what the if statement inside this function is checking for.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb12"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> pop(self: *Stack) <span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb12-2"><a href="#cb12-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> (self.length == <span class="dv">0</span>) <span class="kw">return</span>;</span>
-<span id="cb12-3"><a href="#cb12-3" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb12-4"><a href="#cb12-4" aria-hidden="true" tabindex="-1"></a>    self.items[self.length - <span class="dv">1</span>] = <span class="cn">undefined</span>;</span>
-<span id="cb12-5"><a href="#cb12-5" aria-hidden="true" tabindex="-1"></a>    self.length -= <span class="dv">1</span>;</span>
-<span id="cb12-6"><a href="#cb12-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb17"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> pop(self: *Stack) <span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb17-2"><a href="#cb17-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> (self.length == <span class="dv">0</span>) <span class="kw">return</span>;</span>
+<span id="cb17-3"><a href="#cb17-3" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb17-4"><a href="#cb17-4" aria-hidden="true" tabindex="-1"></a>    self.items[self.length - <span class="dv">1</span>] = <span class="cn">undefined</span>;</span>
+<span id="cb17-5"><a href="#cb17-5" aria-hidden="true" tabindex="-1"></a>    self.length -= <span class="dv">1</span>;</span>
+<span id="cb17-6"><a href="#cb17-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
 <section id="implementing-the-deinit-method" class="level3" data-number="12.4.3">
@@ -582,9 +601,9 @@ <h3 data-number="12.4.3" class="anchored" data-anchor-id="implementing-the-deini
 <p>But now, we need to implement also the method responsible for destroying a <code>Stack</code> object. In Zig, this task is commonly associated with the method named <code>deinit()</code>. Most struct objects in Zig have such method, and it is commonly nicknamed “the destructor method”.</p>
 <p>In theory, all we have to do to destroy the <code>Stack</code> object is to make sure that we free the allocated memory for the underlying array, using the allocator object that is stored inside the <code>Stack</code> object. This is what the <code>deinit()</code> method below is doing.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb13"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> deinit(self: *Stack) <span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb13-2"><a href="#cb13-2" aria-hidden="true" tabindex="-1"></a>    self.allocator.free(self.items);</span>
-<span id="cb13-3"><a href="#cb13-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb18"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb18-1"><a href="#cb18-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> deinit(self: *Stack) <span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb18-2"><a href="#cb18-2" aria-hidden="true" tabindex="-1"></a>    self.allocator.free(self.items);</span>
+<span id="cb18-3"><a href="#cb18-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
 </section>
@@ -596,56 +615,56 @@ <h2 data-number="12.5" class="anchored" data-anchor-id="making-it-generic"><span
 <p>We do that by using a generic function. Because a generic function can receive a data type as input, and we can pass this data type to the struct definition of our <code>Stack</code> object. Therefore, we can use the generic function to create a <code>Stack</code> object that can store the data type we want. If we want to create a stack structure that stores <code>User</code> values, we pass the <code>User</code> data type to this generic function, and it will create for us the struct definition that describes a <code>Stack</code> object that can store <code>User</code> values in it.</p>
 <p>Look at the code example below. I have omitted some parts of the <code>Stack</code> struct definition for brevity reasons. However, if a specific part of our <code>Stack</code> struct is not exposed here in this example, then it is because this part did not change from the previous example. It remains the same.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb14"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> Stack(<span class="kw">comptime</span> T: <span class="dt">type</span>) <span class="dt">type</span> <span class="op">{</span></span>
-<span id="cb14-2"><a href="#cb14-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> <span class="kw">struct</span> <span class="op">{</span></span>
-<span id="cb14-3"><a href="#cb14-3" aria-hidden="true" tabindex="-1"></a>        items: []T,</span>
-<span id="cb14-4"><a href="#cb14-4" aria-hidden="true" tabindex="-1"></a>        capacity: <span class="dt">usize</span>,</span>
-<span id="cb14-5"><a href="#cb14-5" aria-hidden="true" tabindex="-1"></a>        length: <span class="dt">usize</span>,</span>
-<span id="cb14-6"><a href="#cb14-6" aria-hidden="true" tabindex="-1"></a>        allocator: Allocator,</span>
-<span id="cb14-7"><a href="#cb14-7" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> Self = <span class="bu">@This</span>();</span>
-<span id="cb14-8"><a href="#cb14-8" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb14-9"><a href="#cb14-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">pub</span> <span class="kw">fn</span> init(allocator: Allocator,</span>
-<span id="cb14-10"><a href="#cb14-10" aria-hidden="true" tabindex="-1"></a>                    capacity: <span class="dt">usize</span>) !Stack(T) <span class="op">{</span></span>
-<span id="cb14-11"><a href="#cb14-11" aria-hidden="true" tabindex="-1"></a>            <span class="kw">var</span> buf = <span class="kw">try</span> allocator.alloc(T, capacity);</span>
-<span id="cb14-12"><a href="#cb14-12" aria-hidden="true" tabindex="-1"></a>            <span class="kw">return</span> .<span class="op">{</span></span>
-<span id="cb14-13"><a href="#cb14-13" aria-hidden="true" tabindex="-1"></a>                .items = buf[<span class="dv">0</span>..],</span>
-<span id="cb14-14"><a href="#cb14-14" aria-hidden="true" tabindex="-1"></a>                .capacity = capacity,</span>
-<span id="cb14-15"><a href="#cb14-15" aria-hidden="true" tabindex="-1"></a>                .length = <span class="dv">0</span>,</span>
-<span id="cb14-16"><a href="#cb14-16" aria-hidden="true" tabindex="-1"></a>                .allocator = allocator,</span>
-<span id="cb14-17"><a href="#cb14-17" aria-hidden="true" tabindex="-1"></a>            <span class="op">}</span>;</span>
-<span id="cb14-18"><a href="#cb14-18" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span></span>
-<span id="cb14-19"><a href="#cb14-19" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb14-20"><a href="#cb14-20" aria-hidden="true" tabindex="-1"></a>        <span class="kw">pub</span> <span class="kw">fn</span> push(self: *Self, val: T) !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb14-21"><a href="#cb14-21" aria-hidden="true" tabindex="-1"></a>        <span class="co">// Truncate the rest of the struct</span></span>
-<span id="cb14-22"><a href="#cb14-22" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>;</span>
-<span id="cb14-23"><a href="#cb14-23" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb19"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb19-1"><a href="#cb19-1" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> Stack(<span class="kw">comptime</span> T: <span class="dt">type</span>) <span class="dt">type</span> <span class="op">{</span></span>
+<span id="cb19-2"><a href="#cb19-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb19-3"><a href="#cb19-3" aria-hidden="true" tabindex="-1"></a>        items: []T,</span>
+<span id="cb19-4"><a href="#cb19-4" aria-hidden="true" tabindex="-1"></a>        capacity: <span class="dt">usize</span>,</span>
+<span id="cb19-5"><a href="#cb19-5" aria-hidden="true" tabindex="-1"></a>        length: <span class="dt">usize</span>,</span>
+<span id="cb19-6"><a href="#cb19-6" aria-hidden="true" tabindex="-1"></a>        allocator: Allocator,</span>
+<span id="cb19-7"><a href="#cb19-7" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> Self = <span class="bu">@This</span>();</span>
+<span id="cb19-8"><a href="#cb19-8" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb19-9"><a href="#cb19-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">pub</span> <span class="kw">fn</span> init(allocator: Allocator,</span>
+<span id="cb19-10"><a href="#cb19-10" aria-hidden="true" tabindex="-1"></a>                    capacity: <span class="dt">usize</span>) !Stack(T) <span class="op">{</span></span>
+<span id="cb19-11"><a href="#cb19-11" aria-hidden="true" tabindex="-1"></a>            <span class="kw">var</span> buf = <span class="kw">try</span> allocator.alloc(T, capacity);</span>
+<span id="cb19-12"><a href="#cb19-12" aria-hidden="true" tabindex="-1"></a>            <span class="kw">return</span> .<span class="op">{</span></span>
+<span id="cb19-13"><a href="#cb19-13" aria-hidden="true" tabindex="-1"></a>                .items = buf[<span class="dv">0</span>..],</span>
+<span id="cb19-14"><a href="#cb19-14" aria-hidden="true" tabindex="-1"></a>                .capacity = capacity,</span>
+<span id="cb19-15"><a href="#cb19-15" aria-hidden="true" tabindex="-1"></a>                .length = <span class="dv">0</span>,</span>
+<span id="cb19-16"><a href="#cb19-16" aria-hidden="true" tabindex="-1"></a>                .allocator = allocator,</span>
+<span id="cb19-17"><a href="#cb19-17" aria-hidden="true" tabindex="-1"></a>            <span class="op">}</span>;</span>
+<span id="cb19-18"><a href="#cb19-18" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span></span>
+<span id="cb19-19"><a href="#cb19-19" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb19-20"><a href="#cb19-20" aria-hidden="true" tabindex="-1"></a>        <span class="kw">pub</span> <span class="kw">fn</span> push(self: *Self, val: T) !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb19-21"><a href="#cb19-21" aria-hidden="true" tabindex="-1"></a>        <span class="co">// Truncate the rest of the struct</span></span>
+<span id="cb19-22"><a href="#cb19-22" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>;</span>
+<span id="cb19-23"><a href="#cb19-23" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>Notice that we have created a function in this example named <code>Stack()</code>. This function takes a type as input, and passes this type to the struct definition of our <code>Stack</code> object. The data member <code>items</code> is now, an array of type <code>T</code>, which is the data type that we have provided as input to the function. The function argument <code>val</code> in the <code>push()</code> function is now a value of type <code>T</code> too.</p>
 <p>We can just provide a data type to this function, and it will create a definition of a <code>Stack</code> object that can store values of the data type that we have provided. In the example below, we are creating the definition of a <code>Stack</code> object that can store <code>u8</code> values in it. This definition is stored at the <code>Stacku8</code> object. This <code>Stacku8</code> object becomes our new struct, it is the struct that we are going to use to create our <code>Stack</code> object.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb15"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb15-1"><a href="#cb15-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> gpa = std.heap.GeneralPurposeAllocator(.<span class="op">{}</span>)<span class="op">{}</span>;</span>
-<span id="cb15-2"><a href="#cb15-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> allocator = gpa.allocator();</span>
-<span id="cb15-3"><a href="#cb15-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Stacku8 = Stack(<span class="dt">u8</span>);</span>
-<span id="cb15-4"><a href="#cb15-4" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> stack = <span class="kw">try</span> Stacku8.init(allocator, <span class="dv">10</span>);</span>
-<span id="cb15-5"><a href="#cb15-5" aria-hidden="true" tabindex="-1"></a><span class="kw">defer</span> stack.deinit();</span>
-<span id="cb15-6"><a href="#cb15-6" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stack.push(<span class="dv">1</span>);</span>
-<span id="cb15-7"><a href="#cb15-7" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stack.push(<span class="dv">2</span>);</span>
-<span id="cb15-8"><a href="#cb15-8" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stack.push(<span class="dv">3</span>);</span>
-<span id="cb15-9"><a href="#cb15-9" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stack.push(<span class="dv">4</span>);</span>
-<span id="cb15-10"><a href="#cb15-10" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stack.push(<span class="dv">5</span>);</span>
-<span id="cb15-11"><a href="#cb15-11" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stack.push(<span class="dv">6</span>);</span>
-<span id="cb15-12"><a href="#cb15-12" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb15-13"><a href="#cb15-13" aria-hidden="true" tabindex="-1"></a>std.debug.print(<span class="st">"Stack len: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>stack.length<span class="op">}</span>);</span>
-<span id="cb15-14"><a href="#cb15-14" aria-hidden="true" tabindex="-1"></a>std.debug.print(<span class="st">"Stack capacity: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>stack.capacity<span class="op">}</span>);</span>
-<span id="cb15-15"><a href="#cb15-15" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb15-16"><a href="#cb15-16" aria-hidden="true" tabindex="-1"></a>stack.pop();</span>
-<span id="cb15-17"><a href="#cb15-17" aria-hidden="true" tabindex="-1"></a>std.debug.print(<span class="st">"Stack len: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>stack.length<span class="op">}</span>);</span>
-<span id="cb15-18"><a href="#cb15-18" aria-hidden="true" tabindex="-1"></a>stack.pop();</span>
-<span id="cb15-19"><a href="#cb15-19" aria-hidden="true" tabindex="-1"></a>std.debug.print(<span class="st">"Stack len: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>stack.length<span class="op">}</span>);</span>
-<span id="cb15-20"><a href="#cb15-20" aria-hidden="true" tabindex="-1"></a>std.debug.print(</span>
-<span id="cb15-21"><a href="#cb15-21" aria-hidden="true" tabindex="-1"></a>    <span class="st">"Stack state: {any}</span><span class="sc">\n</span><span class="st">"</span>,</span>
-<span id="cb15-22"><a href="#cb15-22" aria-hidden="true" tabindex="-1"></a>    .<span class="op">{</span>stack.items[<span class="dv">0</span>..stack.length]<span class="op">}</span></span>
-<span id="cb15-23"><a href="#cb15-23" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb20"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb20-1"><a href="#cb20-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> gpa = std.heap.GeneralPurposeAllocator(.<span class="op">{}</span>)<span class="op">{}</span>;</span>
+<span id="cb20-2"><a href="#cb20-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> allocator = gpa.allocator();</span>
+<span id="cb20-3"><a href="#cb20-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Stacku8 = Stack(<span class="dt">u8</span>);</span>
+<span id="cb20-4"><a href="#cb20-4" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> stack = <span class="kw">try</span> Stacku8.init(allocator, <span class="dv">10</span>);</span>
+<span id="cb20-5"><a href="#cb20-5" aria-hidden="true" tabindex="-1"></a><span class="kw">defer</span> stack.deinit();</span>
+<span id="cb20-6"><a href="#cb20-6" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stack.push(<span class="dv">1</span>);</span>
+<span id="cb20-7"><a href="#cb20-7" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stack.push(<span class="dv">2</span>);</span>
+<span id="cb20-8"><a href="#cb20-8" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stack.push(<span class="dv">3</span>);</span>
+<span id="cb20-9"><a href="#cb20-9" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stack.push(<span class="dv">4</span>);</span>
+<span id="cb20-10"><a href="#cb20-10" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stack.push(<span class="dv">5</span>);</span>
+<span id="cb20-11"><a href="#cb20-11" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stack.push(<span class="dv">6</span>);</span>
+<span id="cb20-12"><a href="#cb20-12" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb20-13"><a href="#cb20-13" aria-hidden="true" tabindex="-1"></a>std.debug.print(<span class="st">"Stack len: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>stack.length<span class="op">}</span>);</span>
+<span id="cb20-14"><a href="#cb20-14" aria-hidden="true" tabindex="-1"></a>std.debug.print(<span class="st">"Stack capacity: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>stack.capacity<span class="op">}</span>);</span>
+<span id="cb20-15"><a href="#cb20-15" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb20-16"><a href="#cb20-16" aria-hidden="true" tabindex="-1"></a>stack.pop();</span>
+<span id="cb20-17"><a href="#cb20-17" aria-hidden="true" tabindex="-1"></a>std.debug.print(<span class="st">"Stack len: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>stack.length<span class="op">}</span>);</span>
+<span id="cb20-18"><a href="#cb20-18" aria-hidden="true" tabindex="-1"></a>stack.pop();</span>
+<span id="cb20-19"><a href="#cb20-19" aria-hidden="true" tabindex="-1"></a>std.debug.print(<span class="st">"Stack len: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>stack.length<span class="op">}</span>);</span>
+<span id="cb20-20"><a href="#cb20-20" aria-hidden="true" tabindex="-1"></a>std.debug.print(</span>
+<span id="cb20-21"><a href="#cb20-21" aria-hidden="true" tabindex="-1"></a>    <span class="st">"Stack state: {any}</span><span class="sc">\n</span><span class="st">"</span>,</span>
+<span id="cb20-22"><a href="#cb20-22" aria-hidden="true" tabindex="-1"></a>    .<span class="op">{</span>stack.items[<span class="dv">0</span>..stack.length]<span class="op">}</span></span>
+<span id="cb20-23"><a href="#cb20-23" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Stack len: 6
 Stack capacity: 10
diff --git a/docs/Chapters/13-image-filter.html b/docs/Chapters/13-image-filter.html
index 609d19f9..af1fa84c 100644
--- a/docs/Chapters/13-image-filter.html
+++ b/docs/Chapters/13-image-filter.html
@@ -606,7 +606,7 @@ <h2 data-number="15.5" class="anchored" data-anchor-id="applying-the-image-filte
 <span id="cb11-4"><a href="#cb11-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> green_factor: <span class="dt">f16</span> = <span class="fl">0.7152</span>;</span>
 <span id="cb11-5"><a href="#cb11-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> blue_factor: <span class="dt">f16</span> = <span class="fl">0.0722</span>;</span>
 <span id="cb11-6"><a href="#cb11-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> index: <span class="dt">u64</span> = <span class="dv">0</span>;</span>
-<span id="cb11-7"><a href="#cb11-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">while</span> (index &lt; (len - <span class="dv">4</span>)) : (index += <span class="dv">4</span>) <span class="op">{</span></span>
+<span id="cb11-7"><a href="#cb11-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">while</span> (index &lt;= (len - <span class="dv">4</span>)) : (index += <span class="dv">4</span>) <span class="op">{</span></span>
 <span id="cb11-8"><a href="#cb11-8" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> rf: <span class="dt">f16</span> = <span class="bu">@floatFromInt</span>(buffer[index]);</span>
 <span id="cb11-9"><a href="#cb11-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> gf: <span class="dt">f16</span> = <span class="bu">@floatFromInt</span>(buffer[index + <span class="dv">1</span>]);</span>
 <span id="cb11-10"><a href="#cb11-10" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> bf: <span class="dt">f16</span> = <span class="bu">@floatFromInt</span>(buffer[index + <span class="dv">2</span>]);</span>
diff --git a/docs/ZigExamples/image_filter/pedro_pascal_filter.png b/docs/ZigExamples/image_filter/pedro_pascal_filter.png
index bdce0380b5c0f138546e189851262424517f1c54..45bf4ed35f67ccb92ca00e2d7aedbf290dc9d82e 100644
GIT binary patch
delta 45
zcmaE|gX`fAu7(!IEleVfj27EP8<|X{#kv3UJ4AX5bUJP3U;qM7S3j3^P6<r_WvmVk

delta 48
zcmaF3gX_r-u7(!IEleVfjMm#l8<|X{rI;svH2Y)k+~lLEl_C0q0SG)@{an^LB{Ts5
Dtq%}5

diff --git a/docs/index.html b/docs/index.html
index 73c18985..2f9822ba 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -7,7 +7,7 @@
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 <meta name="author" content="Pedro Duarte Faria">
-<meta name="dcterms.date" content="2024-11-27">
+<meta name="dcterms.date" content="2024-12-04">
 
 <title>Introduction to Zig</title>
 <style>
@@ -287,7 +287,7 @@ <h1 class="title">Introduction to Zig</h1>
     <div>
     <div class="quarto-title-meta-heading">Published</div>
     <div class="quarto-title-meta-contents">
-      <p class="date">November 27, 2024</p>
+      <p class="date">December 4, 2024</p>
     </div>
   </div>
   
@@ -412,7 +412,7 @@ <h2 class="unnumbered anchored" data-anchor-id="book-compilation-metadata">Book
 <p>This book was compiled using the following versions of <a href="https://ziglang.org">Zig</a> and <a href="https://quarto.org">Quarto</a>:</p>
 <ul>
 <li>System version: Linux, 6.8.0-49-generic, NA, x86_64.</li>
-<li>Zig version: 0.14.0-dev.2051+b1361f237.</li>
+<li>Zig version: 0.14.0-dev.2371+c013f45ad.</li>
 <li>Quarto version: 1.5.57.</li>
 </ul>
 </section>
diff --git a/docs/search.json b/docs/search.json
index d4e230f5..5ac48cc7 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -54,7 +54,7 @@
     "href": "index.html#book-compilation-metadata",
     "title": "Introduction to Zig",
     "section": "Book compilation metadata",
-    "text": "Book compilation metadata\nThis book was compiled using the following versions of Zig and Quarto:\n\nSystem version: Linux, 6.8.0-49-generic, NA, x86_64.\nZig version: 0.14.0-dev.2051+b1361f237.\nQuarto version: 1.5.57.",
+    "text": "Book compilation metadata\nThis book was compiled using the following versions of Zig and Quarto:\n\nSystem version: Linux, 6.8.0-49-generic, NA, x86_64.\nZig version: 0.14.0-dev.2371+c013f45ad.\nQuarto version: 1.5.57.",
     "crumbs": [
       "Welcome"
     ]
@@ -184,7 +184,7 @@
     "href": "Chapters/01-zig-weird.html#sec-zig-strings",
     "title": "1  Introducing Zig",
     "section": "1.8 How strings work in Zig?",
-    "text": "1.8 How strings work in Zig?\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (Chapter 4). But in order for us to build such a thing, we need to get a better understanding on how strings work in Zig. So let’s discuss this specific aspect of Zig.\nIn summary, there are two types of string values that you care about in Zig, which are:\n\nString literal values.\nString objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string). But in Zig, a string literal value also embeds the length of the string into the data type of the value itself. Therefore, a string literal value have a data type in the format *const [n:0]u8. The n in the data type indicates the size of the string.\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes, or, in other words, a slice of u8 values (slices were presented at Section 1.6). Thus, a string object have a data type of []u8 or []const u8, depending if the string object is marked as constant with const, or as variable with var.\nBecause a string object is essentially a slice, it means that a string object always contains two things: a pointer to an array of bytes (i.e. u8 values) that represents the string value; and also, a length value, which specifies the size of the slice, or, how many elements there is in the slice. Is worth to emphasize that the array of bytes in a string object is not null-terminated, like in a string literal value.\n\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every sequence of bytes you’re working with, but is not really Zig’s job to fix the encoding of your strings (you can use iconv18 for that). Today, most of the text in our modern world, especially on the web, should be UTF-8 encoded. So if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\nLet’s take for example the word “Hello”. In UTF-8, this sequence of characters (H, e, l, l, o) is represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this sequence is 0x48, 0x65, 0x6C, 0x6C, 0x6F. So if I take this sequence of hexadecimal values, and ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then, the text “Hello” will be printed into the terminal:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n\nHello\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use a for loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal value to the terminal. You do that by using a print() statement with the X formatting specifier, like you would normally do with the printf() function19 in C.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n\n\n\n1.8.1 Strings in C\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well. In more details, string values in C are treated internally as an array of arbitrary bytes, and this array is also null-terminated.\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of the string inside the object itself. In the case of a string literal value, this length is stored in the data type of the value (i.e. the n variable in [n:0]u8). While, in a string object, the length is stored in the len attribute of the slice that represents the string object. This small detail makes your code safer, because is much easier for the Zig compiler to check if you are trying to access an element that is “out of bounds”, i.e. if your trying to access memory that does not belong to you.\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless. So getting this kind of safety is not automatic and much harder to do in C. For example, if you want to track the length of your string throughout your program in C, then, you first need to loop through the array of bytes that represents this string, and find the null element ('\\0') position to discover where exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\nTo do that, you would need something like this in C. In this example, the C string stored in the object array is 25 bytes long:\n\n#include &lt;stdio.h&gt;\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n\nNumber of elements in the array: 25\nYou don’t have this kind of work in Zig. Because the length of the string is always present and accessible. In a string object for example, you can easily access the length of the string through the len attribute. As an example, the string_object object below is 43 bytes long:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n\n43\n\n\n\n\n1.8.2 A better look at the object type\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the @TypeOf() function. If we look at the type of the simple_array object below, you will find that this object is an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type i32 in Zig. That is what an object of type [4]i32 is.\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a constant pointer (hence the *const annotation) to an array of 16 elements (or 16 bytes). Each element is a single byte (more precisely, an unsigned 8 bit integer - u8), that is why we have the [16:0]u8 portion of the type below. In other words, the string literal value exposed below is 16 bytes long.\nNow, if we create an pointer to the simple_array object, then, we get a constant pointer to an array of 4 elements (*const [4]i32), which is very similar to the type of the string literal value. This demonstrates that a string literal value in Zig is already a pointer to a null-terminated array of bytes.\nFurthermore, if we take a look at the type of the string_obj object, you will see that it is a slice object (hence the [] portion of the type) to a sequence of constant u8 values (hence the const u8 portion of the type).\n\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n\n\n1.8.3 Byte vs unicode points\nIs important to point out that each byte in the array is not necessarily a single character. This fact arises from the difference between a single byte and a single unicode point.\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in the string. For example, the character “H” is stored in UTF-8 as the decimal number 72. This means that the number 72 is the unicode point for the character “H”. Each possible character that can appear in a UTF-8 encoded string have its own unicode point.\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point) 570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which is 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why, the unicode point 570 is actually stored inside the computer’s memory as the bytes C8 BA.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n\nBytes that represents the string object: C8 BA \n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together to represent the number 570. That is why the relationship between bytes and unicode points is not always 1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds to a single unicode point.\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the bytes that represents that string, and not through the characters of that string. In the Ⱥ example above, the for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a consequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because the number of bytes will be equal to the number of characters in that string. In other words, in this specific situation, the relationship between bytes and unicode points is 1 to 1.\nBut on the other side, if your string contains other types of letters… for example, you might be working with text data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent your UTF-8 string will likely be much higher than the number of characters in that string.\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the std.unicode.Utf8View struct to create an iterator that iterates through the unicode points of your string.\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in this string is represented by three bytes. But the for loop iterates four times, one iteration for each character/unicode point in this string:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n\n\n1.8.4 Some useful functions for strings\nIn this section, I just want to quickly describe some functions from the Zig Standard Library that are very useful to use when working with strings. Most notably:\n\nstd.mem.eql(): to compare if two strings are equal.\nstd.mem.splitScalar(): to split a string into an array of substrings given a delimiter value.\nstd.mem.splitSequence(): to split a string into an array of substrings given a substring delimiter.\nstd.mem.startsWith(): to check if string starts with substring.\nstd.mem.endsWith(): to check if string ends with substring.\nstd.mem.trim(): to remove specific values from both start and end of the string.\nstd.mem.concat(): to concatenate strings together.\nstd.mem.count(): to count the occurrences of substring in the string.\nstd.mem.replace(): to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the mem module of the Zig Standard Library. This module contains multiple functions and methods that are useful to work with memory and sequences of bytes in general.\nThe eql() function is used to check if two arrays of data are equal or not. Since strings are just arbitrary arrays of bytes, we can use this function to compare two strings together. This function returns a boolean value indicating if the two strings are equal or not. The first argument of this function is the data type of the elements of the arrays that are being compared.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n\ntrue\n\n\nThe splitScalar() and splitSequence() functions are useful to split a string into multiple fragments, like the split() method from Python strings. The difference between these two methods is that the splitScalar() uses a single character as the separator to split the string, while splitSequence() uses a sequence of characters (a.k.a. a substring) as the separator. There is a practical example of these functions later in the book.\nThe startsWith() and endsWith() functions are pretty straightforward. They return a boolean value indicating if the string (or, more precisely, if the array of data) begins (startsWith) or ends (endsWith) with the sequence provided.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n\ntrue\n\n\nThe concat() function, as the name suggests, concatenate two or more strings together. Because the process of concatenating the strings involves allocating enough space to accomodate all the strings together, this concat() function receives an allocator object as input.\n\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n\nHello you!\nAs you can imagine, the replace() function is used to replace substrings in a string by another substring. This function works very similarly to the replace() method from Python strings. Therefore, you provide a substring to search, and every time that the replace() function finds this substring within the input string, it replaces this substring with the “replacement substring” that you provided as input.\nIn the example below, we are taking the input string “Hello”, and replacing all occurrences of the substring “el” inside this input string with “34”, and saving the results inside the buffer object. As result, the replace() function returns an usize value that indicates how many replacements were performed.\n\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n\nNew string: H34lo\nN of replacements: 1",
+    "text": "1.8 How strings work in Zig?\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (Chapter 4). But in order for us to build such a thing, we need to get a better understanding on how strings work in Zig. So let’s discuss this specific aspect of Zig.\nIn summary, there are two types of string values that you care about in Zig, which are:\n\nString literal values.\nString objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string). But in Zig, a string literal value also embeds the length of the string into the data type of the value itself. Therefore, a string literal value have a data type in the format *const [n:0]u8. The n in the data type indicates the size of the string.\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes, or, in other words, a slice of u8 values (slices were presented at Section 1.6). Thus, a string object have a data type of []u8 or []const u8, depending if the string object is marked as constant with const, or as variable with var.\nBecause a string object is essentially a slice, it means that a string object always contains two things: a pointer to an array of bytes (i.e. u8 values) that represents the string value; and also, a length value, which specifies the size of the slice, or, how many elements there is in the slice. Is worth to emphasize that the array of bytes in a string object is not null-terminated, like in a string literal value.\n\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every sequence of bytes you’re working with, but is not really Zig’s job to fix the encoding of your strings (you can use iconv18 for that). Today, most of the text in our modern world, especially on the web, should be UTF-8 encoded. So if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\nLet’s take for example the word “Hello”. In UTF-8, this sequence of characters (H, e, l, l, o) is represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this sequence is 0x48, 0x65, 0x6C, 0x6C, 0x6F. So if I take this sequence of hexadecimal values, and ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then, the text “Hello” will be printed into the terminal:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n\nHello\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use a for loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal value to the terminal. You do that by using a print() statement with the X formatting specifier, like you would normally do with the printf() function19 in C.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n\n\n\n1.8.1 Strings in C\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well. In more details, string values in C are treated internally as an array of arbitrary bytes, and this array is also null-terminated.\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of the string inside the object itself. In the case of a string literal value, this length is stored in the data type of the value (i.e. the n variable in [n:0]u8). While, in a string object, the length is stored in the len attribute of the slice that represents the string object. This small detail makes your code safer, because is much easier for the Zig compiler to check if you are trying to access an element that is “out of bounds”, i.e. if your trying to access memory that does not belong to you.\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless. So getting this kind of safety is not automatic and much harder to do in C. For example, if you want to track the length of your string throughout your program in C, then, you first need to loop through the array of bytes that represents this string, and find the null element ('\\0') position to discover where exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\nTo do that, you would need something like this in C. In this example, the C string stored in the object array is 25 bytes long:\n\n#include &lt;stdio.h&gt;\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n\nNumber of elements in the array: 25\nYou don’t have this kind of work in Zig. Because the length of the string is always present and accessible. In a string object for example, you can easily access the length of the string through the len attribute. As an example, the string_object object below is 43 bytes long:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n\n43\n\n\n\n\n1.8.2 A better look at the object type\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the @TypeOf() function. If we look at the type of the simple_array object below, you will find that this object is an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type i32 in Zig. That is what an object of type [4]i32 is.\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a constant pointer (hence the *const annotation) to an array of 16 elements (or 16 bytes). Each element is a single byte (more precisely, an unsigned 8 bit integer - u8), that is why we have the [16:0]u8 portion of the type below. In other words, the string literal value exposed below is 16 bytes long.\nNow, if we create an pointer to the simple_array object, then, we get a constant pointer to an array of 4 elements (*const [4]i32), which is very similar to the type of the string literal value. This demonstrates that a string literal value in Zig is already a pointer to a null-terminated array of bytes.\nFurthermore, if we take a look at the type of the string_obj object, you will see that it is a slice object (hence the [] portion of the type) to a sequence of constant u8 values (hence the const u8 portion of the type).\n\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n\n\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n\n\n1.8.3 Byte vs unicode points\nIs important to point out that each byte in the array is not necessarily a single character. This fact arises from the difference between a single byte and a single unicode point.\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in the string. For example, the character “H” is stored in UTF-8 as the decimal number 72. This means that the number 72 is the unicode point for the character “H”. Each possible character that can appear in a UTF-8 encoded string have its own unicode point.\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point) 570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which is 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why, the unicode point 570 is actually stored inside the computer’s memory as the bytes C8 BA.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n\nBytes that represents the string object: C8 BA \n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together to represent the number 570. That is why the relationship between bytes and unicode points is not always 1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds to a single unicode point.\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the bytes that represents that string, and not through the characters of that string. In the Ⱥ example above, the for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a consequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because the number of bytes will be equal to the number of characters in that string. In other words, in this specific situation, the relationship between bytes and unicode points is 1 to 1.\nBut on the other side, if your string contains other types of letters… for example, you might be working with text data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent your UTF-8 string will likely be much higher than the number of characters in that string.\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the std.unicode.Utf8View struct to create an iterator that iterates through the unicode points of your string.\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in this string is represented by three bytes. But the for loop iterates four times, one iteration for each character/unicode point in this string:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n\n\n1.8.4 Some useful functions for strings\nIn this section, I just want to quickly describe some functions from the Zig Standard Library that are very useful to use when working with strings. Most notably:\n\nstd.mem.eql(): to compare if two strings are equal.\nstd.mem.splitScalar(): to split a string into an array of substrings given a delimiter value.\nstd.mem.splitSequence(): to split a string into an array of substrings given a substring delimiter.\nstd.mem.startsWith(): to check if string starts with substring.\nstd.mem.endsWith(): to check if string ends with substring.\nstd.mem.trim(): to remove specific values from both start and end of the string.\nstd.mem.concat(): to concatenate strings together.\nstd.mem.count(): to count the occurrences of substring in the string.\nstd.mem.replace(): to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the mem module of the Zig Standard Library. This module contains multiple functions and methods that are useful to work with memory and sequences of bytes in general.\nThe eql() function is used to check if two arrays of data are equal or not. Since strings are just arbitrary arrays of bytes, we can use this function to compare two strings together. This function returns a boolean value indicating if the two strings are equal or not. The first argument of this function is the data type of the elements of the arrays that are being compared.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n\ntrue\n\n\nThe splitScalar() and splitSequence() functions are useful to split a string into multiple fragments, like the split() method from Python strings. The difference between these two methods is that the splitScalar() uses a single character as the separator to split the string, while splitSequence() uses a sequence of characters (a.k.a. a substring) as the separator. There is a practical example of these functions later in the book.\nThe startsWith() and endsWith() functions are pretty straightforward. They return a boolean value indicating if the string (or, more precisely, if the array of data) begins (startsWith) or ends (endsWith) with the sequence provided.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n\ntrue\n\n\nThe concat() function, as the name suggests, concatenate two or more strings together. Because the process of concatenating the strings involves allocating enough space to accomodate all the strings together, this concat() function receives an allocator object as input.\n\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n\nAs you can imagine, the replace() function is used to replace substrings in a string by another substring. This function works very similarly to the replace() method from Python strings. Therefore, you provide a substring to search, and every time that the replace() function finds this substring within the input string, it replaces this substring with the “replacement substring” that you provided as input.\nIn the example below, we are taking the input string “Hello”, and replacing all occurrences of the substring “el” inside this input string with “34”, and saving the results inside the buffer object. As result, the replace() function returns an usize value that indicates how many replacements were performed.\n\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n\nNew string: H34lo\nN of replacements: 1",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -234,7 +234,7 @@
     "href": "Chapters/03-structs.html#sec-zig-control-flow",
     "title": "2  Control flow, structs, modules and types",
     "section": "",
-    "text": "2.1.1 If/else statements\nAn if/else statement performs a “conditional flow operation”. A conditional flow control (or choice control) allows you to execute or ignore a certain block of commands based on a logical condition. Many programmers and computer science professionals also use the term “branching” in this case. In essence, an if/else statement allow us to use the result of a logical test to decide whether or not to execute a given block of commands.\nIn Zig, we write if/else statements by using the keywords if and else. We start with the if keyword followed by a logical test inside a pair of parentheses, followed by a pair of curly braces which contains the lines of code to be executed in case the logical test returns the value true.\nAfter that, you can optionally add an else statement. To do that, just add the else keyword followed by a pair of curly braces, with the lines of code to executed in case the logical test defined at if returns false.\nIn the example below, we are testing if the object x contains a number that is greater than 10. Judging by the output printed to the console, we know that this logical test returned false. Because the output in the console is compatible with the line of code present in the else branch of the if/else statement.\n\nconst x = 5;\nif (x &gt; 10) {\n    try stdout.print(\n        \"x &gt; 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x &lt;= 10!\\n\", .{}\n    );\n}\n\nx &lt;= 10!\n\n\n\n\n2.1.2 Switch statements\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust. As you would expect, to write a switch statement in Zig we use the switch keyword. We provide the value that we want to “switch over” inside a pair of parentheses. Then, we list the possible combinations (or “branches”) inside a pair of curly braces.\nLet’s take a look at the code example below. You can see that I’m creating an enum type called Role. We talk more about enums in Section 7.6. But in summary, this Role type is listing different types of roles in a fictitious company, like SE for Software Engineer, DE for Data Engineer, PM for Product Manager, etc.\nNotice that we are using the value from the role object in the switch statement, to discover which exact area we need to store in the area variable object. Also notice that we are using type inference inside the switch statement, with the dot character, as we are going to describe in Section 2.4. This makes the zig compiler infer the correct data type of the values (PM, SE, etc.) for us.\nAlso notice that, we are grouping multiple values in the same branch of the switch statement. We just separate each possible value with a comma. For example, if role contains either DE or DA, the area variable would contain the value \"Data & Analytics\", instead of \"Platform\" or \"Sales\".\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO =&gt; {\n            area = \"Platform\";\n        },\n        .DE, .DA =&gt; {\n            area = \"Data & Analytics\";\n        },\n        .KS =&gt; {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n\nPlatform\n\n\n\n2.1.2.1 Switch statements must exhaust all possibilities\nOne very important aspect about switch statements in Zig is that they must exhaust all existing possibilities. In other words, all possible values that could be found inside the order object must be explicitly handled in this switch statement.\nSince the role object have type Role, the only possible values to be found inside this object are PM, SE, DPE, PO, DE, DA and KS. There are no other possible values to be stored in this role object. Thus, the switch statements must have a combination (branch) for each one of these values. This is what “exhaust all existing possibilities” means. The switch statement covers every possible case.\nTherefore, you cannot write a switch statement in Zig, and leave an edge case with no explicit action to be taken. This is a similar behaviour to switch statements in Rust, which also have to handle all possible cases.\n\n\n2.1.2.2 The else branch\nTake a look at the dump_hex_fallible() function below as an example. This function comes from the Zig Standard Library. More precisely, from the debug.zig module1. There are multiple lines in this function, but I omitted them to focus solely on the switch statement found in this function. Notice that this switch statement has four possible cases (i.e. four explicit branches). Also, notice that we used an else branch in this case.\nAn else branch in a switch statement works as the “default branch”. Whenever you have multiple cases in your switch statement where you want to apply the exact same action, you can use an else branch to do that.\n\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' =&gt; try writer.writeAll(\"␊\"),\n        '\\r' =&gt; try writer.writeAll(\"␍\"),\n        '\\t' =&gt; try writer.writeAll(\"␉\"),\n        else =&gt; try writer.writeByte('.'),\n    }\n}\n\nMany programmers would also use an else branch to handle a “not supported” case. That is, a case that cannot be properly handled by your code, or, just a case that should not be “fixed”. Therefore, you can use an else branch to panic (or raise an error) in your program to stop the current execution.\nTake the code example below. We can see that, we are handling the cases for the level object being either 1, 2, or 3. All other possible cases are not supported by default, and, as consequence, we raise a runtime error in such cases through the @panic() built-in function.\nAlso notice that, we are assigning the result of the switch statement to a new object called category. This is another thing that you can do with switch statements in Zig. If a branch outputs a value as result, you can store the result value of the switch statement into a new object.\n\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 =&gt; \"beginner\",\n    3 =&gt; \"professional\",\n    else =&gt; {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n\n\n2.1.2.3 Using ranges in switch\nFurthermore, you can also use ranges of values in switch statements. That is, you can create a branch in your switch statement that is used whenever the input value is within the specified range. These “range expressions” are created with the operator .... It is important to emphasize that the ranges created by this operator are inclusive on both ends.\nFor example, I could easily change the previous code example to support all levels between 0 and 100. Like this:\n\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 =&gt; \"beginner\",\n    26...75 =&gt; \"intermediary\",\n    76...100 =&gt; \"professional\",\n    else =&gt; {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n\nbeginner\n\n\nThis is neat, and it works with character ranges too. That is, I could simply write 'a'...'z', to match any character value that is a lowercase letter, and it would work fine.\n\n\n2.1.2.4 Labeled switch statements\nIn Section 1.7 we have talked about labeling blocks, and also, about using these labels to return a value from the block. Well, from version 0.14.0 and onwards of the zig compiler, you can also apply labels over switch statements, which makes it possible to almost implement a “C goto” like pattern.\nFor example, if you give the label xsw to a switch statement, you can use this label in conjunction with the continue keyword to go back to the beginning of the switch statement. In the example below, the execution goes back to the beginning of the switch statement two times, before ending at the 3 branch.\n\nxsw: switch (@as(u8, 1)) {\n    1 =&gt; {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 =&gt; continue :xsw 3,\n    3 =&gt; return,\n    4 =&gt; {},\n    else =&gt; {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n\n\n\n\n2.1.3 The defer keyword\nWith the defer keyword you can register an expression to be executed when you exit the current scope. Therefore, this keyword has a similar functionality as the on.exit() function from R. Take the foo() function below as an example. When we execute this foo() function, the expression that prints the message “Exiting function …” is getting executed only when the function exits its scope.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n\nAdding some numbers ...\nMultiplying ...\nExiting function ...\nTherefore, we can use defer to declare an expression that is going to be executed when your code exits the current scope. Some programmers like to interpret the phrase “exit of the current scope” as “the end of the current scope”. But this interpretation might not be entirely correct, depending on what you consider as “the end of the current scope”.\nI mean, what do you consider as the end of the current scope? Is it the closing curly bracket (}) of the scope? Is it when the last expression in the function get’s executed? Is it when the function returns to the previous scope? Etc. For example, it would not be correct to interpret the “exit of the current scope” as the closing curly bracket of the scope. Because the function might exit from an earlier position than this closing curly bracket (e.g. an error value was generated at a previous line inside the function; the function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\nNow, if you remember of what we have discussed in Section 1.7, there are multiple structures in the language that create their own separate scopes. For/while loops, if/else statements, functions, normal blocks, etc. This also affects the interpretation of defer. For example, if you use defer inside a for loop, then, the given expression will be executed everytime this specific for loop exits its own scope.\nBefore we continue, is worth emphasizing that the defer keyword is an “unconditional defer”. Which means that the given expression will be executed no matter how the code exits the current scope. For example, your code might exit the current scope because of an error value being generated, or, because of a return statement, or, a break statement, etc.\n\n\n2.1.4 The errdefer keyword\nOn the previous section, we have discussed the defer keyword, which you can use to register an expression to be executed at the exit of the current scope. But this keyword has a brother, which is the errdefer keyword. While defer is an “unconditional defer”, the errdefer keyword is a “conditional defer”. Which means that the given expression is executed only when you exit the current scope on a very specific circumstance.\nIn more details, the expression given to errdefer is executed only when an error occurs in the current scope. Therefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope in a normal situation, without errors, the expression given to errdefer is not executed.\nThis makes the errdefer keyword one of the many tools available in Zig for error handling. In this section, we are more concerned with the control flow aspects around errdefer. But we are going to discuss errdefer later as a error handling tool in Section 10.2.4.\nThe code example below demonstrates three things:\n\nthat defer is an “unconditional defer”, because the given expression get’s executed regardless of how the function foo() exits its own scope.\nthat errdefer is executed because the function foo() returned an error value.\nthat defer and errdefer expressions are executed in a LIFO (last in, first out) order.\n\n\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\nWhen I say that “defer expressions” are executed in a LIFO order, what I want to say is that the last defer or errdefer expressions in the code are the first ones to be executed. You could also interpret this as: “defer expressions” are executed from bottom to top, or, from last to first.\nTherefore, if I change the order of the defer and errdefer expressions, you will notice that the value of i that get’s printed to the console changes to 1. This doesn’t mean that the defer expression was not executed in this case. This actually means that the defer expression was executed only after the errdefer expression. The code example below demonstrates this:\n\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n\n\n2.1.5 For loops\nA loop allows you to execute the same lines of code multiple times, thus, creating a “repetition space” in the execution flow of your program. Loops are particularly useful when we want to replicate the same function (or the same set of commands) over different inputs.\nThere are different types of loops available in Zig. But the most essential of them all is probably the for loop. A for loop is used to apply the same piece of code over the elements of a slice, or, an array.\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from other languages. You start with the for keyword, then, you list the items that you want to iterate over inside a pair of parentheses. Then, inside of a pair of pipes (|) you should declare an identifier that will serve as your iterator, or, the “repetition index of the loop”.\n\nfor (items) |value| {\n    // code to execute\n}\n\nTherefore, instead of using a (value in items) syntax, in Zig, for loops use the syntax (items) |value|. In the example below, you can see that we are looping through the items of the array stored at the object name, and printing to the console the decimal representation of each character in this array.\nIf we wanted, we could also iterate through a slice (or a portion) of the array, instead of iterating through the entire array stored in the name object. Just use a range selector to select the section you want. For example, I could provide the expression name[0..3] to the for loop, to iterate just through the first 3 elements in the array.\n\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n\n80 | 101 | 100 | 114 | 111 | \n\n\nIn the above example we are using the value itself of each element in the array as our iterator. But there are many situations where we need to use an index instead of the actual values of the items.\nYou can do that by providing a second set of items to iterate over. More precisely, you provide the range selector 0.. to the for loop. So, yes, you can use two different iterators at the same time in a for loop in Zig.\nBut remember from Section 1.4 that, every object you create in Zig must be used in some way. So if you declare two iterators in your for loop, you must use both iterators inside the for loop body. But if you want to use just the index iterator, and not use the “value iterator”, then, you can discard the value iterator by maching the value items to the underscore character, like in the example below:\n\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n\n0 | 1 | 2 | 3 | 4 |\n\n\n2.1.6 While loops\nA while loop is created from the while keyword. A for loop iterates through the items of an array, but a while loop will loop continuously, and infinitely, until a logical test (specified by you) becomes false.\nYou start with the while keyword, then, you define a logical expression inside a pair of parentheses, and the body of the loop is provided inside a pair of curly braces, like in the example below:\n\nvar i: u8 = 1;\nwhile (i &lt; 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n\n1 | 2 | 3 | 4 | \n\n\nYou can also specify the increment expression to be used at the beginning of a while loop. To do that, we write the increment expression inside a pair of parentheses after a colon character (:). The code example below demonstrates this other pattern.\n\nvar i: u8 = 1;\nwhile (i &lt; 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n\n1 | 2 | 3 | 4 | \n\n\n\n\n2.1.7 Using break and continue\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using the keywords break and continue, respectively. The while loop presented in the next code example is, at first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to true. But what makes this while loop stop when the i object reaches the count 10? It is the break keyword!\nInside the while loop, we have an if statement that is constantly checking if the i variable is equal to 10. Since we are incrementing the value of i at each iteration of the while loop, this i object will eventually be equal to 10, and when it is, the if statement will execute the break expression, and, as a result, the execution of the while loop is stopped.\nNotice the use of the expect() function from the Zig Standard Library after the while loop. This expect() function is an “assert” type of function. This function checks if the logical test provided is equal to true. If so, the function do nothing. Otherwise (i.e. the logical test is equal to false), the function raises an assertion error.\n\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n\nEverything worked!\n\n\nSince this code example was executed successfully by the zig compiler, without raising any errors, we known that, after the execution of the while loop, the i object is equal to 10. Because if it wasn’t equal to 10, an error would have been raised by expect().\nNow, in the next example, we have a use case for the continue keyword. The if statement is constantly checking if the current index is a multiple of 2. If it is, we jump to the next iteration of the loop. Otherwise, the loop just prints the current index to the console.\n\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n\n1 | 3 | 5 |",
+    "text": "2.1.1 If/else statements\nAn if/else statement performs a “conditional flow operation”. A conditional flow control (or choice control) allows you to execute or ignore a certain block of commands based on a logical condition. Many programmers and computer science professionals also use the term “branching” in this case. In essence, an if/else statement allow us to use the result of a logical test to decide whether or not to execute a given block of commands.\nIn Zig, we write if/else statements by using the keywords if and else. We start with the if keyword followed by a logical test inside a pair of parentheses, followed by a pair of curly braces which contains the lines of code to be executed in case the logical test returns the value true.\nAfter that, you can optionally add an else statement. To do that, just add the else keyword followed by a pair of curly braces, with the lines of code to executed in case the logical test defined at if returns false.\nIn the example below, we are testing if the object x contains a number that is greater than 10. Judging by the output printed to the console, we know that this logical test returned false. Because the output in the console is compatible with the line of code present in the else branch of the if/else statement.\n\nconst x = 5;\nif (x &gt; 10) {\n    try stdout.print(\n        \"x &gt; 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x &lt;= 10!\\n\", .{}\n    );\n}\n\nx &lt;= 10!\n\n\n\n\n2.1.2 Switch statements\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust. As you would expect, to write a switch statement in Zig we use the switch keyword. We provide the value that we want to “switch over” inside a pair of parentheses. Then, we list the possible combinations (or “branches”) inside a pair of curly braces.\nLet’s take a look at the code example below. You can see that I’m creating an enum type called Role. We talk more about enums in Section 7.6. But in summary, this Role type is listing different types of roles in a fictitious company, like SE for Software Engineer, DE for Data Engineer, PM for Product Manager, etc.\nNotice that we are using the value from the role object in the switch statement, to discover which exact area we need to store in the area variable object. Also notice that we are using type inference inside the switch statement, with the dot character, as we are going to describe in Section 2.4. This makes the zig compiler infer the correct data type of the values (PM, SE, etc.) for us.\nAlso notice that, we are grouping multiple values in the same branch of the switch statement. We just separate each possible value with a comma. For example, if role contains either DE or DA, the area variable would contain the value \"Data & Analytics\", instead of \"Platform\" or \"Sales\".\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO =&gt; {\n            area = \"Platform\";\n        },\n        .DE, .DA =&gt; {\n            area = \"Data & Analytics\";\n        },\n        .KS =&gt; {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n\nPlatform\n\n\n\n2.1.2.1 Switch statements must exhaust all possibilities\nOne very important aspect about switch statements in Zig is that they must exhaust all existing possibilities. In other words, all possible values that could be found inside the order object must be explicitly handled in this switch statement.\nSince the role object have type Role, the only possible values to be found inside this object are PM, SE, DPE, PO, DE, DA and KS. There are no other possible values to be stored in this role object. Thus, the switch statements must have a combination (branch) for each one of these values. This is what “exhaust all existing possibilities” means. The switch statement covers every possible case.\nTherefore, you cannot write a switch statement in Zig, and leave an edge case with no explicit action to be taken. This is a similar behaviour to switch statements in Rust, which also have to handle all possible cases.\n\n\n2.1.2.2 The else branch\nTake a look at the dump_hex_fallible() function below as an example. This function comes from the Zig Standard Library. More precisely, from the debug.zig module1. There are multiple lines in this function, but I omitted them to focus solely on the switch statement found in this function. Notice that this switch statement has four possible cases (i.e. four explicit branches). Also, notice that we used an else branch in this case.\nAn else branch in a switch statement works as the “default branch”. Whenever you have multiple cases in your switch statement where you want to apply the exact same action, you can use an else branch to do that.\n\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' =&gt; try writer.writeAll(\"␊\"),\n        '\\r' =&gt; try writer.writeAll(\"␍\"),\n        '\\t' =&gt; try writer.writeAll(\"␉\"),\n        else =&gt; try writer.writeByte('.'),\n    }\n}\n\nMany programmers would also use an else branch to handle a “not supported” case. That is, a case that cannot be properly handled by your code, or, just a case that should not be “fixed”. Therefore, you can use an else branch to panic (or raise an error) in your program to stop the current execution.\nTake the code example below. We can see that, we are handling the cases for the level object being either 1, 2, or 3. All other possible cases are not supported by default, and, as consequence, we raise a runtime error in such cases through the @panic() built-in function.\nAlso notice that, we are assigning the result of the switch statement to a new object called category. This is another thing that you can do with switch statements in Zig. If a branch outputs a value as result, you can store the result value of the switch statement into a new object.\n\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 =&gt; \"beginner\",\n    3 =&gt; \"professional\",\n    else =&gt; {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n\n\n2.1.2.3 Using ranges in switch\nFurthermore, you can also use ranges of values in switch statements. That is, you can create a branch in your switch statement that is used whenever the input value is within the specified range. These “range expressions” are created with the operator .... It is important to emphasize that the ranges created by this operator are inclusive on both ends.\nFor example, I could easily change the previous code example to support all levels between 0 and 100. Like this:\n\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 =&gt; \"beginner\",\n    26...75 =&gt; \"intermediary\",\n    76...100 =&gt; \"professional\",\n    else =&gt; {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n\nbeginner\n\n\nThis is neat, and it works with character ranges too. That is, I could simply write 'a'...'z', to match any character value that is a lowercase letter, and it would work fine.\n\n\n2.1.2.4 Labeled switch statements\nIn Section 1.7 we have talked about labeling blocks, and also, about using these labels to return a value from the block. Well, from version 0.14.0 and onwards of the zig compiler, you can also apply labels over switch statements, which makes it possible to almost implement a “C goto” like pattern.\nFor example, if you give the label xsw to a switch statement, you can use this label in conjunction with the continue keyword to go back to the beginning of the switch statement. In the example below, the execution goes back to the beginning of the switch statement two times, before ending at the 3 branch.\n\nxsw: switch (@as(u8, 1)) {\n    1 =&gt; {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 =&gt; continue :xsw 3,\n    3 =&gt; return,\n    4 =&gt; {},\n    else =&gt; {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n\n\n\n\n2.1.3 The defer keyword\nWith the defer keyword you can register an expression to be executed when you exit the current scope. Therefore, this keyword has a similar functionality as the on.exit() function from R. Take the foo() function below as an example. When we execute this foo() function, the expression that prints the message “Exiting function …” is getting executed only when the function exits its scope.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n\nAdding some numbers ...\nMultiplying ...\nExiting function ...\nTherefore, we can use defer to declare an expression that is going to be executed when your code exits the current scope. Some programmers like to interpret the phrase “exit of the current scope” as “the end of the current scope”. But this interpretation might not be entirely correct, depending on what you consider as “the end of the current scope”.\nI mean, what do you consider as the end of the current scope? Is it the closing curly bracket (}) of the scope? Is it when the last expression in the function get’s executed? Is it when the function returns to the previous scope? Etc. For example, it would not be correct to interpret the “exit of the current scope” as the closing curly bracket of the scope. Because the function might exit from an earlier position than this closing curly bracket (e.g. an error value was generated at a previous line inside the function; the function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\nNow, if you remember of what we have discussed in Section 1.7, there are multiple structures in the language that create their own separate scopes. For/while loops, if/else statements, functions, normal blocks, etc. This also affects the interpretation of defer. For example, if you use defer inside a for loop, then, the given expression will be executed everytime this specific for loop exits its own scope.\nBefore we continue, is worth emphasizing that the defer keyword is an “unconditional defer”. Which means that the given expression will be executed no matter how the code exits the current scope. For example, your code might exit the current scope because of an error value being generated, or, because of a return statement, or, a break statement, etc.\n\n\n2.1.4 The errdefer keyword\nOn the previous section, we have discussed the defer keyword, which you can use to register an expression to be executed at the exit of the current scope. But this keyword has a brother, which is the errdefer keyword. While defer is an “unconditional defer”, the errdefer keyword is a “conditional defer”. Which means that the given expression is executed only when you exit the current scope on a very specific circumstance.\nIn more details, the expression given to errdefer is executed only when an error occurs in the current scope. Therefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope in a normal situation, without errors, the expression given to errdefer is not executed.\nThis makes the errdefer keyword one of the many tools available in Zig for error handling. In this section, we are more concerned with the control flow aspects around errdefer. But we are going to discuss errdefer later as a error handling tool in Section 10.2.4.\nThe code example below demonstrates three things:\n\nthat defer is an “unconditional defer”, because the given expression get’s executed regardless of how the function foo() exits its own scope.\nthat errdefer is executed because the function foo() returned an error value.\nthat defer and errdefer expressions are executed in a LIFO (last in, first out) order.\n\n\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\nWhen I say that “defer expressions” are executed in a LIFO order, what I want to say is that the last defer or errdefer expressions in the code are the first ones to be executed. You could also interpret this as: “defer expressions” are executed from bottom to top, or, from last to first.\nTherefore, if I change the order of the defer and errdefer expressions, you will notice that the value of i that get’s printed to the console changes to 1. This doesn’t mean that the defer expression was not executed in this case. This actually means that the defer expression was executed only after the errdefer expression. The code example below demonstrates this:\n\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n\n\n2.1.5 For loops\nA loop allows you to execute the same lines of code multiple times, thus, creating a “repetition space” in the execution flow of your program. Loops are particularly useful when we want to replicate the same function (or the same set of commands) over different inputs.\nThere are different types of loops available in Zig. But the most essential of them all is probably the for loop. A for loop is used to apply the same piece of code over the elements of a slice, or, an array.\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from other languages. You start with the for keyword, then, you list the items that you want to iterate over inside a pair of parentheses. Then, inside of a pair of pipes (|) you should declare an identifier that will serve as your iterator, or, the “repetition index of the loop”.\n\nfor (items) |value| {\n    // code to execute\n}\n\nTherefore, instead of using a (value in items) syntax, in Zig, for loops use the syntax (items) |value|. In the example below, you can see that we are looping through the items of the array stored at the object name, and printing to the console the decimal representation of each character in this array.\nIf we wanted, we could also iterate through a slice (or a portion) of the array, instead of iterating through the entire array stored in the name object. Just use a range selector to select the section you want. For example, I could provide the expression name[0..3] to the for loop, to iterate just through the first 3 elements in the array.\n\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n\n80 | 101 | 100 | 114 | 111 | \n\n\nIn the above example we are using the value itself of each element in the array as our iterator. But there are many situations where we need to use an index instead of the actual values of the items.\nYou can do that by providing a second set of items to iterate over. More precisely, you provide the range selector 0.. to the for loop. So, yes, you can use two different iterators at the same time in a for loop in Zig.\nBut remember from Section 1.4 that, every object you create in Zig must be used in some way. So if you declare two iterators in your for loop, you must use both iterators inside the for loop body. But if you want to use just the index iterator, and not use the “value iterator”, then, you can discard the value iterator by maching the value items to the underscore character, like in the example below:\n\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n\n0 | 1 | 2 | 3 | 4 |\n\n\n2.1.6 While loops\nA while loop is created from the while keyword. A for loop iterates through the items of an array, but a while loop will loop continuously, and infinitely, until a logical test (specified by you) becomes false.\nYou start with the while keyword, then, you define a logical expression inside a pair of parentheses, and the body of the loop is provided inside a pair of curly braces, like in the example below:\n\nvar i: u8 = 1;\nwhile (i &lt; 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n\n1 | 2 | 3 | 4 | \n\n\nYou can also specify the increment expression to be used at the beginning of a while loop. To do that, we write the increment expression inside a pair of parentheses after a colon character (:). The code example below demonstrates this other pattern.\n\nvar i: u8 = 1;\nwhile (i &lt; 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n\n1 | 2 | 3 | 4 | \n\n\n\n\n2.1.7 Using break and continue\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using the keywords break and continue, respectively. The while loop presented in the next code example is, at first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to true. But what makes this while loop stop when the i object reaches the count 10? It is the break keyword!\nInside the while loop, we have an if statement that is constantly checking if the i variable is equal to 10. Since we are incrementing the value of i at each iteration of the while loop, this i object will eventually be equal to 10, and when it is, the if statement will execute the break expression, and, as a result, the execution of the while loop is stopped.\nNotice the use of the expect() function from the Zig Standard Library after the while loop. This expect() function is an “assert” type of function. This function checks if the logical test provided is equal to true. If so, the function do nothing. Otherwise (i.e. the logical test is equal to false), the function raises an assertion error.\n\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n\nEverything worked!\n\n\nSince this code example was executed successfully by the zig compiler, without raising any errors, we known that, after the execution of the while loop, the i object is equal to 10. Because if it wasn’t equal to 10, an error would have been raised by expect().\nNow, in the next example, we have a use case for the continue keyword. The if statement is constantly checking if the current index is a multiple of 2. If it is, we jump to the next iteration of the loop. Otherwise, the loop just prints the current index to the console.\n\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n\n1 | 3 | 5 |",
     "crumbs": [
       "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
     ]
@@ -244,7 +244,7 @@
     "href": "Chapters/03-structs.html#sec-fun-pars",
     "title": "2  Control flow, structs, modules and types",
     "section": "2.2 Function parameters are immutable",
-    "text": "2.2 Function parameters are immutable\nWe have already discussed a lot of the syntax behind function declarations in Section 1.2.2 and Section 1.2.3. But I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig. In summary, function parameters are immutable in Zig.\nTake the code example below, where we declare a simple function that just tries to add some amount to the input integer, and returns the result back. If you look closely at the body of this add2() function, you will notice that we try to save the result back into the x function argument.\nIn other words, this function not only uses the value that it received through the function argument x, but it also tries to change the value of this function argument, by assigning the addition result into x. However, function arguments in Zig are immutable. You cannot change their values, or, you cannot assign values to them inside the body’s function.\nThis is the reason why, the code example below does not compile successfully. If you try to compile this code example, you will get a compile error message about “trying to change the value of a immutable (i.e. constant) object”.\n\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n\n2.2.1 A free optimization\nIf a function argument receives as input an object whose data type is any of the primitive types that we have listed in Section 1.5, this object is always passed by value to the function. In other words, this object is copied into the function stack frame.\nHowever, if the input object have a more complex data type, for example, it might be a struct instance, or an array, or an union value, etc., in cases like that, the zig compiler will take the liberty of deciding for you which strategy is best. Thus, the zig compiler will pass your object to the function either by value, or by reference. The compiler will always choose the strategy that is faster for you. This optimization that you get for free is possible only because function arguments are immutable in Zig.\n\n\n2.2.2 How to overcome this barrier\nThere are some situations where you might need to change the value of your function argument directly inside the function’s body. This happens more often when we are passing C structs as inputs to Zig functions.\nIn a situation like this, you can overcome this barrier by using a pointer. In other words, instead of passing a value as input to the argument, you can pass a “pointer to value” instead. You can change the value that the pointer points to, by dereferencing it.\nTherefore, if we take our previous add2() example, we can change the value of the function argument x inside the function’s body by marking the x argument as a “pointer to a u32 value” (i.e. *u32 data type), instead of a u32 value. By making it a pointer, we can finally alter the value of this function argument directly inside the body of the add2() function. You can see that the code example below compiles successfully.\n\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n\nResult: 6\nEven in this code example above, the x argument is still immutable. Which means that the pointer itself is immutable. Therefore, you cannot change the memory address that it points to. However, you can dereference the pointer to access the value that it points to, and also, to change this value, if you need to.",
+    "text": "2.2 Function parameters are immutable\nWe have already discussed a lot of the syntax behind function declarations in Section 1.2.2 and Section 1.2.3. But I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig. In summary, function parameters are immutable in Zig.\nTake the code example below, where we declare a simple function that just tries to add some amount to the input integer, and returns the result back. If you look closely at the body of this add2() function, you will notice that we try to save the result back into the x function argument.\nIn other words, this function not only uses the value that it received through the function argument x, but it also tries to change the value of this function argument, by assigning the addition result into x. However, function arguments in Zig are immutable. You cannot change their values, or, you cannot assign values to them inside the body’s function.\nThis is the reason why, the code example below does not compile successfully. If you try to compile this code example, you will get a compile error message about “trying to change the value of a immutable (i.e. constant) object”.\n\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n\n2.2.1 A free optimization\nIf a function argument receives as input an object whose data type is any of the primitive types that we have listed in Section 1.5, this object is always passed by value to the function. In other words, this object is copied into the function stack frame.\nHowever, if the input object have a more complex data type, for example, it might be a struct instance, or an array, or an union value, etc., in cases like that, the zig compiler will take the liberty of deciding for you which strategy is best. Thus, the zig compiler will pass your object to the function either by value, or by reference. The compiler will always choose the strategy that is faster for you. This optimization that you get for free is possible only because function arguments are immutable in Zig.\n\n\n2.2.2 How to overcome this barrier\nThere are some situations where you might need to change the value of your function argument directly inside the function’s body. This happens more often when we are passing C structs as inputs to Zig functions.\nIn a situation like this, you can overcome this barrier by using a pointer. In other words, instead of passing a value as input to the argument, you can pass a “pointer to value” instead. You can change the value that the pointer points to, by dereferencing it.\nTherefore, if we take our previous add2() example, we can change the value of the function argument x inside the function’s body by marking the x argument as a “pointer to a u32 value” (i.e. *u32 data type), instead of a u32 value. By making it a pointer, we can finally alter the value of this function argument directly inside the body of the add2() function. You can see that the code example below compiles successfully.\n\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n\nResult: 6\n\n\nResult: 6\nEven in this code example above, the x argument is still immutable. Which means that the pointer itself is immutable. Therefore, you cannot change the memory address that it points to. However, you can dereference the pointer to access the value that it points to, and also, to change this value, if you need to.",
     "crumbs": [
       "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
     ]
@@ -274,7 +274,7 @@
     "href": "Chapters/03-structs.html#sec-type-cast",
     "title": "2  Control flow, structs, modules and types",
     "section": "2.5 Type casting",
-    "text": "2.5 Type casting\nIn this section, I want to discuss type casting (or, type conversion) with you. We use type casting when we have an object of type “x”, and we want to convert it into an object of type “y”, i.e. we want to change the data type of the object.\nMost languages have a formal way to perform type casting. In Rust for example, we normally use the keyword as, and in C, we normally use the type casting syntax, e.g. (int) x. In Zig, we use the @as() built-in function to cast an object of type “x”, into an object of type “y”.\nThis @as() function is the preferred way to perform type conversion (or type casting) in Zig. Because it is explicit, and, it also performs the casting only if it is unambiguous and safe. To use this function, you just provide the target data type in the first argument, and, the object that you want cast as the second argument.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n\nThis is the general way to perform type casting in Zig. But remember, @as() works only when casting is unambiguous and safe, and there are situations where these assumptions do not hold. For example, when casting an integer value into a float value, or vice-versa, it is not clear to the compiler how to perform this conversion safely.\nTherefore, we need to use specialized “casting functions” in such situations. For example, if you want to cast an integer value into a float value, then, you should use the @floatFromInt() function. In the inverse scenario, you should use the @intFromFloat() function.\nIn these functions, you just provide the object that you want to cast as input. Then, the target data type of the “type casting operation” is determined by the type annotation of the object where you are saving the results. In the example below, we are casting the object x into a value of type f32, because the object y, which is where we are saving the results, is annotated as an object of type f32.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n\nAnother built-in function that is very useful when performing type casting operations is @ptrCast(). In essence, we use the @as() built-in function when we want to explicit convert (or cast) a Zig value/object from a type “x” to a type “y”, etc. However, pointers (we are going to discuss pointers in more depth in Chapter 6) are a special type of object in Zig, i.e. they are treated differently from “normal objects”.\nEverytime a pointer is involved in some “type casting operation” in Zig, the @ptrCast() function is used. This function works similarly to @floatFromInt(). You just provide the pointer object that you want to cast as input to this function, and the target data type is, once again, determined by the type annotation of the object where the results are being stored.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}",
+    "text": "2.5 Type casting\nIn this section, I want to discuss type casting (or, type conversion) with you. We use type casting when we have an object of type “x”, and we want to convert it into an object of type “y”, i.e. we want to change the data type of the object.\nMost languages have a formal way to perform type casting. In Rust for example, we normally use the keyword as, and in C, we normally use the type casting syntax, e.g. (int) x. In Zig, we use the @as() built-in function to cast an object of type “x”, into an object of type “y”.\nThis @as() function is the preferred way to perform type conversion (or type casting) in Zig. Because it is explicit, and, it also performs the casting only if it is unambiguous and safe. To use this function, you just provide the target data type in the first argument, and, the object that you want cast as the second argument.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n\n1/1 filefe9b6a29a64b.test_0...OKAll 1 tests passed\n  d.\n\n\nThis is the general way to perform type casting in Zig. But remember, @as() works only when casting is unambiguous and safe, and there are situations where these assumptions do not hold. For example, when casting an integer value into a float value, or vice-versa, it is not clear to the compiler how to perform this conversion safely.\nTherefore, we need to use specialized “casting functions” in such situations. For example, if you want to cast an integer value into a float value, then, you should use the @floatFromInt() function. In the inverse scenario, you should use the @intFromFloat() function.\nIn these functions, you just provide the object that you want to cast as input. Then, the target data type of the “type casting operation” is determined by the type annotation of the object where you are saving the results. In the example below, we are casting the object x into a value of type f32, because the object y, which is where we are saving the results, is annotated as an object of type f32.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n\n1/1 filefe9b126af3c3.test_0...OKAll 1 tests passed\n  d.\n\n\nAnother built-in function that is very useful when performing type casting operations is @ptrCast(). In essence, we use the @as() built-in function when we want to explicit convert (or cast) a Zig value/object from a type “x” to a type “y”, etc. However, pointers (we are going to discuss pointers in more depth in Chapter 6) are a special type of object in Zig, i.e. they are treated differently from “normal objects”.\nEverytime a pointer is involved in some “type casting operation” in Zig, the @ptrCast() function is used. This function works similarly to @floatFromInt(). You just provide the pointer object that you want to cast as input to this function, and the target data type is, once again, determined by the type annotation of the object where the results are being stored.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n\n1/1 filefe9b7366fb7.test_0...OKAll 1 tests passed.",
     "crumbs": [
       "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
     ]
@@ -314,7 +314,7 @@
     "href": "Chapters/01-memory.html#memory-spaces",
     "title": "3  Memory and Allocators",
     "section": "",
-    "text": "Global data register (or the “global data section”);\nStack;\nHeap;\n\n\n3.1.1 Compile-time known versus runtime known\nOne strategy that Zig uses to decide where it will store each object that you declare, is by looking at the value of this particular object. More specifically, by investigating if this value is known at “compile-time” or at “runtime”.\nWhen you write a program in Zig, the values of some of the objects that you write in your program are known at compile time. Meaning that, when you compile your Zig source code, during the compilation process, the zig compiler can figure out the exact value of a particular object that exists in your source code. Knowing the length (or the size) of each object is also important. So the length (or the size) of each object that you write in your program is, in some cases, known at compile time.\nThe zig compiler cares more about knowing the length (or the size) of a particular object , than to know its actual value. But, if the zig compiler knows the value of the object, then, it automatically knows the size of this object. Because it can simply calculate the size of the object by looking at the size of the value.\nTherefore, the priority for the zig compiler is to discover the size of each object in your source code. If the value of the object in question is known at compile-time, then, the zig compiler automatically knows the size/length of this object. But if the value of this object is not known at compile-time, then, the size of this object is only known at compile-time if, and only if, the type of this object has a known fixed size.\nIn order for a type to have a known fixed size, this type must have data members whose size is fixed. If this type includes, for example, a variable sized array in it, then, this type does not have a known fixed size. Because this array can have any size at runtime (i.e. it can be an array of 2 elements, or 50 elements, or 1 thousand elements, etc.).\nFor example, a string object, which internally is an array of constant u8 values ([]const u8) has a variable size. It can be a string object with 100 or 500 characters in it. If we do not know at compile-time, which exact string will be stored inside this string object, then, we cannot calculate the size of this string object at compile-time. So, any type, or any struct declaration that you make, that includes a string data member that does not have an explicit fixed size, makes this type, or this new struct that you are declaring, a type that does not have a known fixed size at compile-time.\nIn contrast, if the type of this struct that you are declaring, includes a data member that is an array, but this array has a known fixed size, like [60]u8 (which declares an array of 60 u8 values), then, this type, or, this struct that you are declaring, becomes a type with a known fixed size at compile-time. And because of that, in this case, the zig compiler does not need to know at compile-time the exact value of any object of this type. Since the compiler can find the necessary size to store this object by looking at the size of its type.\nLet’s look at an example. In the source code below, we have two constant objects (name and array) declared. Because the values of these particular objects are written down, in the source code itself (\"Pedro\" and the number sequence from 1 to 4), the zig compiler can easily discover the values of these constant objects (name and array) during the compilation process. This is what “known at compile time” means. It refers to any object that you have in your Zig source code whose value can be identified at compile time.\n\nconst name = \"Pedro\";\nconst array = [_]u8{1, 2, 3, 4};\n_ = name; _ = array;\n\nfn input_length(input: []const u8) usize {\n    const n = input.len;\n    return n;\n}\n\nThe other side of the spectrum are objects whose values are not known at compile time. Function arguments are a classic example of this. Because the value of each function argument depends on the value that you assign to this particular argument, when you call the function.\nFor example, the function input_length() contains an argument named input, which is an array of constant u8 integers ([]const u8). It is impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length of this particular argument. Because it is an array that do not have a fixed size specified explicitly in the argument type annotation.\nSo, we know that this input argument will be an array of u8 integers. But we do not know at compile-time, its value, and neither his size. This information is known only at runtime, which is the period of time when you program is executed. As a consequence, the value of the expression input.len is also known only at runtime. This is an intrinsic characteristic of any function. Just remember that the value of function arguments is usually not “compile-time known”.\nHowever, as I mentioned earlier, what really matters to the compiler is to know the size of the object at compile-time, and not necessarily its value. So, although we don’t know the value of the object n, which is the result of the expression input.len, at compile-time, we do know its size. Because the expression input.len always returns a value of type usize, and the type usize has a known fixed size.\n\n\n3.1.2 Global data register\nThe global data register is a specific section of the executable of your Zig program, that is responsible for storing any value that is known at compile time.\nEvery constant object whose value is known at compile time that you declare in your source code, is stored in the global data register. Also, every literal value that you write in your source code, such as the string \"this is a string\", or the integer 10, or a boolean value such as true, is also stored in the global data register.\nHonestly, you don’t need to care much about this memory space. Because you can’t control it, you can’t deliberately access it or use it for your own purposes. Also, this memory space does not affect the logic of your program. It simply exists in your program.\n\n\n3.1.3 Stack vs Heap\nIf you are familiar with system’s programming, or just low-level programming in general, you probably have heard of the “duel” between Stack vs Heap. These are two different types of memory, or different memory spaces, which are both available in Zig.\nThese two types of memory don’t actually duel with each other. This is a common mistake that beginners have, when seeing “x vs y” styles of tabloid headlines. These two types of memory are actually complementary to each other. So, in almost every Zig program that you ever write, you will likely use a combination of both. I will describe each memory space in detail over the next sections. But for now, I just want to stablish the main difference between these two types of memory.\nIn essence, the stack memory is normally used to store values whose length is fixed and known at compile time. In contrast, the heap memory is a dynamic type of memory space, meaning that, it is used to store values whose length might grow during the execution (runtime) of your program (Chen and Guo 2022).\nLengths that grow during runtime are intrinsically associated with “runtime known” type of values. In other words, if you have an object whose length might grow during runtime, then, the length of this object becomes not known at compile time. If the length is not known at compile-time, the value of this object also becomes not known at compile-time. These types of objects should be stored in the heap memory space, which is a dynamic memory space, which can grow or shrink to fit the size of your objects.\n\n\n3.1.4 Stack\nThe stack is a type of memory that uses the power of the stack data structure, hence the name. A “stack” is a type of data structure that uses a “last in, first out” (LIFO) mechanism to store the values you give it to. I imagine you are familiar with this data structure. But, if you are not, the Wikipedia page1 , or, the Geeks For Geeks page2 are both excellent and easy resources to fully understand how this data structure works.\nSo, the stack memory space is a type of memory that stores values using a stack data structure. It adds and removes values from the memory by following a “last in, first out” (LIFO) principle.\nEvery time you make a function call in Zig, an amount of space in the stack is reserved for this particular function call (Chen and Guo 2022; Zig Software Foundation 2024). The value of each function argument given to the function in this function call is stored in this stack space. Also, every local object that you declare inside the function scope is usually stored in this same stack space.\nLooking at the example below, the object result is a local object declared inside the scope of the add() function. Because of that, this object is stored inside the stack space reserved for the add() function. The r object (which is declared outside of the add() function scope) is also stored in the stack. But since it is declared in the “outer” scope, this object is stored in the stack space that belongs to this outer scope.\n\nconst r = add(5, 27);\n_ = r;\n\nfn add(x: u8, y: u8) u8 {\n    const result = x + y;\n    return result;\n}\n\nSo, any object that you declare inside the scope of a function is always stored inside the space that was reserved for that particular function in the stack memory. This also counts for any object declared inside the scope of your main() function for example. As you would expect, in this case, they are stored inside the stack space reserved for the main() function.\nOne very important detail about the stack memory is that it frees itself automatically. This is very important, remember that. When objects are stored in the stack memory, you don’t have the work (or the responsibility) of freeing/destroying these objects. Because they will be automatically destroyed once the stack space is freed at the end of the function scope.\nSo, once the function call returns (or ends, if you prefer to call it this way) the space that was reserved in the stack is destroyed, and all of the objects that were in that space goes away with it. This mechanism exists because this space, and the objects within it, are not necessary anymore, since the function “finished its business”. Using the add() function that we exposed above as an example, it means that the object result is automatically destroyed once the function returns.\n\n\n\n\n\n\nImportant\n\n\n\nLocal objects that are stored in the stack space of a function are automatically freed/destroyed at the end of the function scope.\n\n\nThis same logic applies to any other special structure in Zig that have its own scope by surrounding it with curly braces ({}). For loops, while loops, if else statements, etc. For example, if you declare any local object in the scope of a for loop, this local object is accessible only within the scope of this particular for loop. Because once the scope of this for loop ends, the space in the stack reserved for this for loop is freed. The example below demonstrates this idea.\n\n// This does not compile successfully!\nconst a = [_]u8{0, 1, 2, 3, 4};\nfor (0..a.len) |i| {\n    const index = i;\n    _ = index;\n}\n// Trying to use an object that was\n// declared in the for loop scope,\n// and that does not exist anymore.\nstd.debug.print(\"{d}\\n\", index);\n\nOne important consequence of this mechanism is that, once the function returns, you can no longer access any memory address that was inside the space in the stack reserved for this particular function. Because this space was destroyed. This means that, if this local object is stored in the stack, you cannot make a function that returns a pointer to this object.\nThink about that for a second. If all local objects in the stack are destroyed at the end of the function scope, why would you even consider returning a pointer to one of these objects? This pointer is at best, invalid, or, more likely, “undefined”.\nConclusion, it is totally fine to write a function that returns the local object itself as result, because then, you return the value of that object as the result. But, if this local object is stored in the stack, you should never write a function that returns a pointer to this local object. Because the memory address pointed by the pointer no longer exists.\nSo, using again the add() function as an example, if you rewrite this function so that it returns a pointer to the local object result, the zig compiler will actually compile your program, with no warnings or errors. At first glance, it looks that this is good code that works as expected. But this is a lie!\nIf you try to take a look at the value inside of the r object, or, if you try to use this r object in another expression or function call, then, you would have undefined behaviour, and major bugs in your program (Zig Software Foundation 2024, see “Lifetime and Ownership”3 and “Undefined Behaviour”4 sections).\n\n// This code compiles successfully. But it has\n// undefined behaviour. Never do this!!!\n\n// The `r` object is undefined!\nconst r = add(5, 27);\n_ = r;\n\nfn add(x: u8, y: u8) *const u8 {\n    const result = x + y;\n    return &result;\n}\n\nThis “invalid pointer to stack variable” problem is very known across many programming language communities. If you try to do the same thing, for example, in a C or C++ program (i.e. returning an address to a local object stored in the stack), you would also get undefined behaviour in the program.\n\n\n\n\n\n\nImportant\n\n\n\nIf a local object in your function is stored in the stack, you should never return a pointer to this local object from the function. Because this pointer will always become undefined after the function returns, since the stack space of the function is destroyed at the end of its scope.\n\n\nBut what if you really need to use this local object in some way after your function returns? How can you do this? The answer is: “in the same you would do if this was a C or C++ program. By returning an address to an object stored in the heap”. The heap memory has a much more flexible lifecycle, and allows you to get a valid pointer to a local object of a function that already returned from its scope.\n\n\n3.1.5 Heap\nOne important limitation of the stack, is that, only objects whose length/size is known at compile-time can be stored in it. In contrast, the heap is a much more dynamic (and flexible) type of memory. It is the perfect type of memory to use for objects whose size/length might grow during the execution of your program.\nVirtually any application that behaves as a server is a classic use case of the heap. A HTTP server, a SSH server, a DNS server, a LSP server, … any type of server. In summary, a server is a type of application that runs for long periods of time, and that serves (or “deals with”) any incoming request that reaches this particular server.\nThe heap is a good choice for this type of system, mainly because the server does not know upfront how many requests it will receive from users, while it is active. It could be one single request, or, 5 thousand requests, or, it could also be zero requests. The server needs to have the ability to allocate and manage its memory according to how many requests it receives.\nAnother key difference between the stack and the heap, is that the heap is a type of memory that you, the programmer, have complete control over. This makes the heap a more flexible type of memory, but it also makes it harder to work with. Because you, the programmer, is responsible for managing everything related to it. Including where the memory is allocated, how much memory is allocated, and where this memory is freed.\n\nUnlike stack memory, heap memory is allocated explicitly by programmers and it won’t be deallocated until it is explicitly freed (Chen and Guo 2022).\n\nTo store an object in the heap, you, the programmer, needs to explicitly tells Zig to do so, by using an allocator to allocate some space in the heap. At Section 3.3, I will present how you can use allocators to allocate memory in Zig.\n\n\n\n\n\n\nImportant\n\n\n\nEvery memory you allocate in the heap needs to be explicitly freed by you, the programmer.\n\n\nThe majority of allocators in Zig do allocate memory on the heap. But some exceptions to this rule are ArenaAllocator() and FixedBufferAllocator(). The ArenaAllocator() is a special type of allocator that works in conjunction with a second type of allocator. On the other side, the FixedBufferAllocator() is an allocator that works based on buffer objects created on the stack. This means that the FixedBufferAllocator() makes allocations only on the stack.\n\n\n3.1.6 Summary\nAfter discussing all of these boring details, we can quickly recap what we learned. In summary, the Zig compiler will use the following rules to decide where each object you declare is stored:\n\nevery literal value (such as \"this is string\", 10, or true) is stored in the global data section.\nevery constant object (const) whose value is known at compile-time is also stored in the global data section.\nevery object (constant or not) whose length/size is known at compile time is stored in the stack space for the current scope.\nif an object is created with the method alloc() or create() of an allocator object, this object is stored in the memory space used by this particular allocator object. Most of allocators available in Zig use the heap memory, so, this object is likely stored in the heap (FixedBufferAllocator() is an exception to that).\nthe heap can only be accessed through allocators. If your object was not created through the alloc() or create() methods of an allocator object, then, he is most certainly not an object stored in the heap.",
+    "text": "Global data register (or the “global data section”);\nStack;\nHeap;\n\n\n3.1.1 Compile-time known versus runtime known\nOne strategy that Zig uses to decide where it will store each object that you declare, is by looking at the value of this particular object. More specifically, by investigating if this value is known at “compile-time” or at “runtime”.\nWhen you write a program in Zig, the values of some of the objects that you write in your program are known at compile time. Meaning that, when you compile your Zig source code, during the compilation process, the zig compiler can figure out the exact value of a particular object that exists in your source code. Knowing the length (or the size) of each object is also important. So the length (or the size) of each object that you write in your program is, in some cases, known at compile time.\nThe zig compiler cares more about knowing the length (or the size) of a particular object , than to know its actual value. But, if the zig compiler knows the value of the object, then, it automatically knows the size of this object. Because it can simply calculate the size of the object by looking at the size of the value.\nTherefore, the priority for the zig compiler is to discover the size of each object in your source code. If the value of the object in question is known at compile-time, then, the zig compiler automatically knows the size/length of this object. But if the value of this object is not known at compile-time, then, the size of this object is only known at compile-time if, and only if, the type of this object has a known fixed size.\nIn order for a type to have a known fixed size, this type must have data members whose size is fixed. If this type includes, for example, a variable sized array in it, then, this type does not have a known fixed size. Because this array can have any size at runtime (i.e. it can be an array of 2 elements, or 50 elements, or 1 thousand elements, etc.).\nFor example, a string object, which internally is an array of constant u8 values ([]const u8) has a variable size. It can be a string object with 100 or 500 characters in it. If we do not know at compile-time, which exact string will be stored inside this string object, then, we cannot calculate the size of this string object at compile-time. So, any type, or any struct declaration that you make, that includes a string data member that does not have an explicit fixed size, makes this type, or this new struct that you are declaring, a type that does not have a known fixed size at compile-time.\nIn contrast, if the type of this struct that you are declaring, includes a data member that is an array, but this array has a known fixed size, like [60]u8 (which declares an array of 60 u8 values), then, this type, or, this struct that you are declaring, becomes a type with a known fixed size at compile-time. And because of that, in this case, the zig compiler does not need to know at compile-time the exact value of any object of this type. Since the compiler can find the necessary size to store this object by looking at the size of its type.\nLet’s look at an example. In the source code below, we have two constant objects (name and array) declared. Because the values of these particular objects are written down, in the source code itself (\"Pedro\" and the number sequence from 1 to 4), the zig compiler can easily discover the values of these constant objects (name and array) during the compilation process. This is what “known at compile time” means. It refers to any object that you have in your Zig source code whose value can be identified at compile time.\n\nfn input_length(input: []const u8) usize {\n    const n = input.len;\n    return n;\n}\n\npub fn main() !void {\n    const name = \"Pedro\";\n    const array = [_]u8{1, 2, 3, 4};\n    _ = name; _ = array;\n}\n\nThe other side of the spectrum are objects whose values are not known at compile time. Function arguments are a classic example of this. Because the value of each function argument depends on the value that you assign to this particular argument, when you call the function.\nFor example, the function input_length() contains an argument named input, which is an array of constant u8 integers ([]const u8). It is impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length of this particular argument. Because it is an array that do not have a fixed size specified explicitly in the argument type annotation.\nSo, we know that this input argument will be an array of u8 integers. But we do not know at compile-time, its value, and neither his size. This information is known only at runtime, which is the period of time when you program is executed. As a consequence, the value of the expression input.len is also known only at runtime. This is an intrinsic characteristic of any function. Just remember that the value of function arguments is usually not “compile-time known”.\nHowever, as I mentioned earlier, what really matters to the compiler is to know the size of the object at compile-time, and not necessarily its value. So, although we don’t know the value of the object n, which is the result of the expression input.len, at compile-time, we do know its size. Because the expression input.len always returns a value of type usize, and the type usize has a known fixed size.\n\n\n3.1.2 Global data register\nThe global data register is a specific section of the executable of your Zig program, that is responsible for storing any value that is known at compile time.\nEvery constant object whose value is known at compile time that you declare in your source code, is stored in the global data register. Also, every literal value that you write in your source code, such as the string \"this is a string\", or the integer 10, or a boolean value such as true, is also stored in the global data register.\nHonestly, you don’t need to care much about this memory space. Because you can’t control it, you can’t deliberately access it or use it for your own purposes. Also, this memory space does not affect the logic of your program. It simply exists in your program.\n\n\n3.1.3 Stack vs Heap\nIf you are familiar with system’s programming, or just low-level programming in general, you probably have heard of the “duel” between Stack vs Heap. These are two different types of memory, or different memory spaces, which are both available in Zig.\nThese two types of memory don’t actually duel with each other. This is a common mistake that beginners have, when seeing “x vs y” styles of tabloid headlines. These two types of memory are actually complementary to each other. So, in almost every Zig program that you ever write, you will likely use a combination of both. I will describe each memory space in detail over the next sections. But for now, I just want to stablish the main difference between these two types of memory.\nIn essence, the stack memory is normally used to store values whose length is fixed and known at compile time. In contrast, the heap memory is a dynamic type of memory space, meaning that, it is used to store values whose length might grow during the execution (runtime) of your program (Chen and Guo 2022).\nLengths that grow during runtime are intrinsically associated with “runtime known” type of values. In other words, if you have an object whose length might grow during runtime, then, the length of this object becomes not known at compile time. If the length is not known at compile-time, the value of this object also becomes not known at compile-time. These types of objects should be stored in the heap memory space, which is a dynamic memory space, which can grow or shrink to fit the size of your objects.\n\n\n3.1.4 Stack\nThe stack is a type of memory that uses the power of the stack data structure, hence the name. A “stack” is a type of data structure that uses a “last in, first out” (LIFO) mechanism to store the values you give it to. I imagine you are familiar with this data structure. But, if you are not, the Wikipedia page1 , or, the Geeks For Geeks page2 are both excellent and easy resources to fully understand how this data structure works.\nSo, the stack memory space is a type of memory that stores values using a stack data structure. It adds and removes values from the memory by following a “last in, first out” (LIFO) principle.\nEvery time you make a function call in Zig, an amount of space in the stack is reserved for this particular function call (Chen and Guo 2022; Zig Software Foundation 2024). The value of each function argument given to the function in this function call is stored in this stack space. Also, every local object that you declare inside the function scope is usually stored in this same stack space.\nLooking at the example below, the object result is a local object declared inside the scope of the add() function. Because of that, this object is stored inside the stack space reserved for the add() function. The r object (which is declared outside of the add() function scope) is also stored in the stack. But since it is declared in the “outer” scope, this object is stored in the stack space that belongs to this outer scope.\n\nfn add(x: u8, y: u8) u8 {\n    const result = x + y;\n    return result;\n}\n\npub fn main() !void {\n    const r = add(5, 27);\n    _ = r;\n}\n\nSo, any object that you declare inside the scope of a function is always stored inside the space that was reserved for that particular function in the stack memory. This also counts for any object declared inside the scope of your main() function for example. As you would expect, in this case, they are stored inside the stack space reserved for the main() function.\nOne very important detail about the stack memory is that it frees itself automatically. This is very important, remember that. When objects are stored in the stack memory, you don’t have the work (or the responsibility) of freeing/destroying these objects. Because they will be automatically destroyed once the stack space is freed at the end of the function scope.\nSo, once the function call returns (or ends, if you prefer to call it this way) the space that was reserved in the stack is destroyed, and all of the objects that were in that space goes away with it. This mechanism exists because this space, and the objects within it, are not necessary anymore, since the function “finished its business”. Using the add() function that we exposed above as an example, it means that the object result is automatically destroyed once the function returns.\n\n\n\n\n\n\nImportant\n\n\n\nLocal objects that are stored in the stack space of a function are automatically freed/destroyed at the end of the function scope.\n\n\nThis same logic applies to any other special structure in Zig that have its own scope by surrounding it with curly braces ({}). For loops, while loops, if else statements, etc. For example, if you declare any local object in the scope of a for loop, this local object is accessible only within the scope of this particular for loop. Because once the scope of this for loop ends, the space in the stack reserved for this for loop is freed. The example below demonstrates this idea.\n\n// This does not compile successfully!\nconst a = [_]u8{0, 1, 2, 3, 4};\nfor (0..a.len) |i| {\n    const index = i;\n    _ = index;\n}\n// Trying to use an object that was\n// declared in the for loop scope,\n// and that does not exist anymore.\nstd.debug.print(\"{d}\\n\", index);\n\nOne important consequence of this mechanism is that, once the function returns, you can no longer access any memory address that was inside the space in the stack reserved for this particular function. Because this space was destroyed. This means that, if this local object is stored in the stack, you cannot make a function that returns a pointer to this object.\nThink about that for a second. If all local objects in the stack are destroyed at the end of the function scope, why would you even consider returning a pointer to one of these objects? This pointer is at best, invalid, or, more likely, “undefined”.\nConclusion, it is totally fine to write a function that returns the local object itself as result, because then, you return the value of that object as the result. But, if this local object is stored in the stack, you should never write a function that returns a pointer to this local object. Because the memory address pointed by the pointer no longer exists.\nSo, using again the add() function as an example, if you rewrite this function so that it returns a pointer to the local object result, the zig compiler will actually compile your program, with no warnings or errors. At first glance, it looks that this is good code that works as expected. But this is a lie!\nIf you try to take a look at the value inside of the r object, or, if you try to use this r object in another expression or function call, then, you would have undefined behaviour, and major bugs in your program (Zig Software Foundation 2024, see “Lifetime and Ownership”3 and “Undefined Behaviour”4 sections).\n\nfn add(x: u8, y: u8) *const u8 {\n    const result = x + y;\n    return &result;\n}\n\npub fn main() !void {\n    // This code compiles successfully. But it has\n    // undefined behaviour. Never do this!!!\n    // The `r` object is undefined!\n    const r = add(5, 27); _ = r;\n}\n\nThis “invalid pointer to stack variable” problem is very known across many programming language communities. If you try to do the same thing, for example, in a C or C++ program (i.e. returning an address to a local object stored in the stack), you would also get undefined behaviour in the program.\n\n\n\n\n\n\nImportant\n\n\n\nIf a local object in your function is stored in the stack, you should never return a pointer to this local object from the function. Because this pointer will always become undefined after the function returns, since the stack space of the function is destroyed at the end of its scope.\n\n\nBut what if you really need to use this local object in some way after your function returns? How can you do this? The answer is: “in the same you would do if this was a C or C++ program. By returning an address to an object stored in the heap”. The heap memory has a much more flexible lifecycle, and allows you to get a valid pointer to a local object of a function that already returned from its scope.\n\n\n3.1.5 Heap\nOne important limitation of the stack, is that, only objects whose length/size is known at compile-time can be stored in it. In contrast, the heap is a much more dynamic (and flexible) type of memory. It is the perfect type of memory to use for objects whose size/length might grow during the execution of your program.\nVirtually any application that behaves as a server is a classic use case of the heap. A HTTP server, a SSH server, a DNS server, a LSP server, … any type of server. In summary, a server is a type of application that runs for long periods of time, and that serves (or “deals with”) any incoming request that reaches this particular server.\nThe heap is a good choice for this type of system, mainly because the server does not know upfront how many requests it will receive from users, while it is active. It could be one single request, or, 5 thousand requests, or, it could also be zero requests. The server needs to have the ability to allocate and manage its memory according to how many requests it receives.\nAnother key difference between the stack and the heap, is that the heap is a type of memory that you, the programmer, have complete control over. This makes the heap a more flexible type of memory, but it also makes it harder to work with. Because you, the programmer, is responsible for managing everything related to it. Including where the memory is allocated, how much memory is allocated, and where this memory is freed.\n\nUnlike stack memory, heap memory is allocated explicitly by programmers and it won’t be deallocated until it is explicitly freed (Chen and Guo 2022).\n\nTo store an object in the heap, you, the programmer, needs to explicitly tells Zig to do so, by using an allocator to allocate some space in the heap. At Section 3.3, I will present how you can use allocators to allocate memory in Zig.\n\n\n\n\n\n\nImportant\n\n\n\nEvery memory you allocate in the heap needs to be explicitly freed by you, the programmer.\n\n\nThe majority of allocators in Zig do allocate memory on the heap. But some exceptions to this rule are ArenaAllocator() and FixedBufferAllocator(). The ArenaAllocator() is a special type of allocator that works in conjunction with a second type of allocator. On the other side, the FixedBufferAllocator() is an allocator that works based on buffer objects created on the stack. This means that the FixedBufferAllocator() makes allocations only on the stack.\n\n\n3.1.6 Summary\nAfter discussing all of these boring details, we can quickly recap what we learned. In summary, the Zig compiler will use the following rules to decide where each object you declare is stored:\n\nevery literal value (such as \"this is string\", 10, or true) is stored in the global data section.\nevery constant object (const) whose value is known at compile-time is also stored in the global data section.\nevery object (constant or not) whose length/size is known at compile time is stored in the stack space for the current scope.\nif an object is created with the method alloc() or create() of an allocator object, this object is stored in the memory space used by this particular allocator object. Most of allocators available in Zig use the heap memory, so, this object is likely stored in the heap (FixedBufferAllocator() is an exception to that).\nthe heap can only be accessed through allocators. If your object was not created through the alloc() or create() methods of an allocator object, then, he is most certainly not an object stored in the heap.",
     "crumbs": [
       "<span class='chapter-number'>3</span>  <span class='chapter-title'>Memory and Allocators</span>"
     ]
@@ -334,7 +334,7 @@
     "href": "Chapters/01-memory.html#sec-allocators",
     "title": "3  Memory and Allocators",
     "section": "3.3 Allocators",
-    "text": "3.3 Allocators\nOne key aspect about Zig, is that there are “no hidden-memory allocations” in Zig. What that really means, is that “no allocations happen behind your back in the standard library” (Sobeston 2024).\nThis is a known problem, especially in C++. Because in C++, there are some operators that do allocate memory behind the scene, and there is no way for you to know that, until you actually read the source code of these operators, and find the memory allocation calls. Many programmers find this behaviour annoying and hard to keep track of.\nBut, in Zig, if a function, an operator, or anything from the standard library needs to allocate some memory during its execution, then, this function/operator needs to receive (as input) an allocator provided by the user, to actually be able to allocate the memory it needs.\nThis creates a clear distinction between functions that “do not” from those that “actually do” allocate memory. Just look at the arguments of this function. If a function, or operator, has an allocator object as one of its inputs/arguments, then, you know for sure that this function/operator will allocate some memory during its execution.\nAn example is the allocPrint() function from the Zig Standard Library. With this function, you can write a new string using format specifiers. So, this function is, for example, very similar to the function sprintf() in C. In order to write such new string, the allocPrint() function needs to allocate some memory to store the output string.\nThat is why, the first argument of this function is an allocator object that you, the user/programmer, gives as input to the function. In the example below, I am using the GeneralPurposeAllocator() as my allocator object. But I could easily use any other type of allocator object from the Zig Standard Library.\n\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst name = \"Pedro\";\nconst output = try std.fmt.allocPrint(\n    allocator,\n    \"Hello {s}!!!\",\n    .{name}\n);\ntry stdout.print(\"{s}\\n\", .{output});\n\nHello Pedro!!!\n\n\nYou get a lot of control over where and how much memory this function can allocate. Because it is you, the user/programmer, that provides the allocator for the function to use. This makes “total control” over memory management easier to achieve in Zig.\n\n3.3.1 What are allocators?\nAllocators in Zig are objects that you can use to allocate memory for your program. They are similar to the memory allocating functions in C, like malloc() and calloc(). So, if you need to use more memory than you initially have, during the execution of your program, you can simply ask for more memory by using an allocator object.\nZig offers different types of allocators, and they are usually available through the std.heap module of the standard library. Thus, just import the Zig Standard Library into your Zig module (with @import(\"std\")), and you can start using these allocators in your code.\nFurthermore, every allocator object is built on top of the Allocator interface in Zig. This means that, every allocator object you find in Zig must have the methods alloc(), create(), free() and destroy(). So, you can change the type of allocator you are using, but you don’t need to change the function calls to the methods that do the memory allocation (and the free memory operations) for your program.\n\n\n3.3.2 Why you need an allocator?\nAs we described at Section 3.1.4, everytime you make a function call in Zig, a space in the stack is reserved for this function call. But the stack has a key limitation which is: every object stored in the stack have a known fixed length.\nBut in reality, there are two very common instances where this “fixed length limitation” of the stack is a deal braker:\n\nthe objects that you create inside your function might grow in size during the execution of the function.\nsometimes, it is impossible to know upfront how many inputs you will receive, or how big this input will be.\n\nAlso, there is another instance where you might want to use an allocator, which is when you want to write a function that returns a pointer to a local object. As I described at Section 3.1.4, you cannot do that if this local object is stored in the stack. However, if this object is stored in the heap, then, you can return a pointer to this object at the end of the function. Because you (the programmer) control the lifetime of any heap memory that you allocate. You decide when this memory gets destroyed/freed.\nThese are common situations where the stack is not good for. That is why you need a different memory management strategy to store these objects inside your function. You need to use a memory type that can grow together with your objects, or that you can control the lifetime of this memory. The heap fits this description.\nAllocating memory on the heap is commonly known as dynamic memory management. As the objects you create grow in size during the execution of your program, you grow the amount of memory you have by allocating more memory in the heap to store these objects. And you do that in Zig, by using an allocator object.\n\n\n3.3.3 The different types of allocators\nAt the moment of the writing of this book, in Zig, we have 6 different allocators available in the standard library:\n\nGeneralPurposeAllocator().\npage_allocator().\nFixedBufferAllocator() and ThreadSafeFixedBufferAllocator().\nArenaAllocator().\nc_allocator() (requires you to link to libc).\n\nEach allocator has its own perks and limitations. All allocators, except FixedBufferAllocator() and ArenaAllocator(), are allocators that use the heap memory. So any memory that you allocate with these allocators, will be placed in the heap.\n\n\n3.3.4 General-purpose allocators\nThe GeneralPurposeAllocator(), as the name suggests, is a “general purpose” allocator. You can use it for every type of task. In the example below, I’m allocating enough space to store a single integer in the object some_number.\n\nconst std = @import(\"std\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const some_number = try allocator.create(u32);\n    defer allocator.destroy(some_number);\n\n    some_number.* = @as(u32, 45);\n}\n\nWhile useful, you might want to use the c_allocator(), which is a alias to the C standard allocator malloc(). So, yes, you can use malloc() in Zig if you want to. Just use the c_allocator() from the Zig standard library. However, if you do use c_allocator(), you must link to Libc when compiling your source code with the zig compiler, by including the flag -lc in your compilation process. If you do not link your source code to Libc, Zig will not be able to find the malloc() implementation in your system.\n\n\n3.3.5 Page allocator\nThe page_allocator() is an allocator that allocates full pages of memory in the heap. In other words, every time you allocate memory with page_allocator(), a full page of memory in the heap is allocated, instead of just a small piece of it.\nThe size of this page depends on the system you are using. Most systems use a page size of 4KB in the heap, so, that is the amount of memory that is normally allocated in each call by page_allocator(). That is why, page_allocator() is considered a fast, but also “wasteful” allocator in Zig. Because it allocates a big amount of memory in each call, and you most likely will not need that much memory in your program.\n\n\n3.3.6 Buffer allocators\nThe FixedBufferAllocator() and ThreadSafeFixedBufferAllocator() are allocator objects that work with a fixed sized buffer object at the back. In other words, they use a fixed sized buffer object as the basis for the memory. When you ask these allocator objects to allocate some memory for you, they are essentially reserving some amount of space inside this fixed sized buffer object for you to use.\nThis means that, in order to use these allocators, you must first create a buffer object in your code, and then, give this buffer object as an input to these allocators.\nThis also means that, these allocator objects can allocate memory both in the stack or in the heap. Everything depends on where the buffer object that you provide lives. If this buffer object lives in the stack, then, the memory allocated is “stack-based”. But if it lives on the heap, then, the memory allocated is “heap-based”.\nIn the example below, I’m creating a buffer object on the stack that is 10 elements long. Notice that I give this buffer object to the FixedBufferAllocator() constructor. Now, because this buffer object is 10 elements long, this means that I am limited to this space. I cannot allocate more than 10 elements with this allocator object. If I try to allocate more than that, the alloc() method will return an OutOfMemory error value.\n\nvar buffer: [10]u8 = undefined;\nfor (0..buffer.len) |i| {\n    buffer[i] = 0; // Initialize to zero\n}\n\nvar fba = std.heap.FixedBufferAllocator.init(&buffer);\nconst allocator = fba.allocator();\nconst input = try allocator.alloc(u8, 5);\ndefer allocator.free(input);\n\nRemember, the memory allocated by these allocator objects can be either from the stack, or, from the heap. It all depends on where the buffer object that you provide lives. In the above example, the buffer object lives in the stack, and, therefore, the memory allocated is based in the stack. But what if it was based on the heap?\nAs we described at Section 3.2, one of the main reasons why you would use the heap, instead of the stack, is to allocate huge amounts of space to store very big objects. Thus, let’s suppose you wanted to use a very big buffer object as the basis for your allocator objects. You would have to allocate this very big buffer object on the heap. The example below demonstrates this case.\n\nconst heap = std.heap.page_allocator;\nconst memory_buffer = try heap.alloc(\n    u8, 100 * 1024 * 1024 // 100 MB memory\n);\ndefer heap.free(memory_buffer);\nvar fba = std.heap.FixedBufferAllocator.init(\n    memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst input = try allocator.alloc(u8, 1000);\ndefer allocator.free(input);\n\n\n\n3.3.7 Arena allocator\nThe ArenaAllocator() is an allocator object that takes a child allocator as input. The idea behind the ArenaAllocator() in Zig is similar to the concept of “arenas” in the programming language Go5. It is an allocator object that allows you to allocate memory as many times you want, but free all memory only once. In other words, if you have, for example, called 5 times the method alloc() of an ArenaAllocator() object, you can free all the memory you allocated over these 5 calls at once, by simply calling the deinit() method of the same ArenaAllocator() object.\nIf you give, for example, a GeneralPurposeAllocator() object as input to the ArenaAllocator() constructor, like in the example below, then, the allocations you perform with alloc() will actually be made with the underlying object GeneralPurposeAllocator() that was passed. So, with an arena allocator, any new memory you ask for is allocated by the child allocator. The only thing that an arena allocator really does is help you to free all the memory you allocated multiple times with just a single command. In the example below, I called alloc() 3 times. So, if I did not use an arena allocator, then, I would need to call free() 3 times to free all the allocated memory.\n\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nvar aa = std.heap.ArenaAllocator.init(gpa.allocator());\ndefer aa.deinit();\nconst allocator = aa.allocator();\n\nconst in1 = allocator.alloc(u8, 5);\nconst in2 = allocator.alloc(u8, 10);\nconst in3 = allocator.alloc(u8, 15);\n_ = in1; _ = in2; _ = in3;\n\n\n\n3.3.8 The alloc() and free() methods\nIn the code example below, we are accessing the stdin, which is the standard input channel, to receive an input from the user. We read the input given by the user with the readUntilDelimiterOrEof() method.\nNow, after reading the input of the user, we need to store this input somewhere in our program. That is why I use an allocator in this example. I use it to allocate some amount of memory to store this input given by the user. More specifically, the method alloc() of the allocator object is used to allocate an array capable of storing 50 u8 values.\nNotice that this alloc() method receives two inputs. The first one, is a type. This defines what type of values the allocated array will store. In the example below, we are allocating an array of unsigned 8-bit integers (u8). But you can create an array to store any type of value you want. Next, on the second argument, we define the size of the allocated array, by specifying how many elements this array will contain. In the case below, we are allocating an array of 50 elements.\nAt Section 1.8 we described that strings in Zig are simply arrays of characters. Each character is represented by a u8 value. So, this means that the array that was allocated in the object input is capable of storing a string that is 50-characters long.\nSo, in essence, the expression var input: [50]u8 = undefined would create an array for 50 u8 values in the stack of the current scope. But, you can allocate the same array in the heap by using the expression var input = try allocator.alloc(u8, 50).\n\nconst std = @import(\"std\");\nconst stdin = std.io.getStdIn();\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var input = try allocator.alloc(u8, 50);\n    defer allocator.free(input);\n    for (0..input.len) |i| {\n        input[i] = 0; // initialize all fields to zero.\n    }\n    // read user input\n    const input_reader = stdin.reader();\n    _ = try input_reader.readUntilDelimiterOrEof(\n        input,\n        '\\n'\n    );\n    std.debug.print(\"{s}\\n\", .{input});\n}\n\nAlso, notice that in this example, we use the defer keyword (which I described at Section 2.1.3) to run a small piece of code at the end of the current scope, which is the expression allocator.free(input). When you execute this expression, the allocator will free the memory that it allocated for the input object.\nWe have talked about this at Section 3.1.5. You should always explicitly free any memory that you allocate using an allocator! You do that by using the free() method of the same allocator object you used to allocate this memory. The defer keyword is used in this example only to help us execute this free operation at the end of the current scope.\n\n\n3.3.9 The create() and destroy() methods\nWith the alloc() and free() methods, you can allocate memory to store multiple elements at once. In other words, with these methods, we always allocate an array to store multiple elements at once. But what if you need enough space to store just a single item? Should you allocate an array of a single element through alloc()?\nThe answer is no! In this case, you should use the create() method of the allocator object. Every allocator object offers the create() and destroy() methods, which are used to allocate and free memory for a single item, respectively.\nSo, in essence, if you want to allocate memory to store an array of elements, you should use alloc() and free(). But if you need to store just a single item, then, the create() and destroy() methods are ideal for you.\nIn the example below, I’m defining a struct to represent an user of some sort. It could be an user for a game, or a software to manage resources, it doesn’t mater. Notice that I use the create() method this time, to store a single User object in the program. Also notice that I use the destroy() method to free the memory used by this object at the end of the scope.\n\nconst std = @import(\"std\");\nconst User = struct {\n    id: usize,\n    name: []const u8,\n\n    pub fn init(id: usize, name: []const u8) User {\n        return .{ .id = id, .name = name };\n    }\n};\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const user = try allocator.create(User);\n    defer allocator.destroy(user);\n\n    user.* = User.init(0, \"Pedro\");\n}\n\n\n\n\n\nChen, Jenny, and Ruohao Guo. 2022. “Stack and Heap Memory.” Introduction to Data Structures and Algorithms with C++. https://courses.engr.illinois.edu/cs225/fa2022/resources/stack-heap/.\n\n\nSobeston. 2024. “Zig Guide.” https://zig.guide/.\n\n\nZig Software Foundation. 2024. “Language Reference.” Zig Software Foundation. https://ziglang.org/documentation/master/.",
+    "text": "3.3 Allocators\nOne key aspect about Zig, is that there are “no hidden-memory allocations” in Zig. What that really means, is that “no allocations happen behind your back in the standard library” (Sobeston 2024).\nThis is a known problem, especially in C++. Because in C++, there are some operators that do allocate memory behind the scene, and there is no way for you to know that, until you actually read the source code of these operators, and find the memory allocation calls. Many programmers find this behaviour annoying and hard to keep track of.\nBut, in Zig, if a function, an operator, or anything from the standard library needs to allocate some memory during its execution, then, this function/operator needs to receive (as input) an allocator provided by the user, to actually be able to allocate the memory it needs.\nThis creates a clear distinction between functions that “do not” from those that “actually do” allocate memory. Just look at the arguments of this function. If a function, or operator, has an allocator object as one of its inputs/arguments, then, you know for sure that this function/operator will allocate some memory during its execution.\nAn example is the allocPrint() function from the Zig Standard Library. With this function, you can write a new string using format specifiers. So, this function is, for example, very similar to the function sprintf() in C. In order to write such new string, the allocPrint() function needs to allocate some memory to store the output string.\nThat is why, the first argument of this function is an allocator object that you, the user/programmer, gives as input to the function. In the example below, I am using the GeneralPurposeAllocator() as my allocator object. But I could easily use any other type of allocator object from the Zig Standard Library.\n\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst name = \"Pedro\";\nconst output = try std.fmt.allocPrint(\n    allocator,\n    \"Hello {s}!!!\",\n    .{name}\n);\ntry stdout.print(\"{s}\\n\", .{output});\n\nHello Pedro!!!\n\n\nYou get a lot of control over where and how much memory this function can allocate. Because it is you, the user/programmer, that provides the allocator for the function to use. This makes “total control” over memory management easier to achieve in Zig.\n\n3.3.1 What are allocators?\nAllocators in Zig are objects that you can use to allocate memory for your program. They are similar to the memory allocating functions in C, like malloc() and calloc(). So, if you need to use more memory than you initially have, during the execution of your program, you can simply ask for more memory by using an allocator object.\nZig offers different types of allocators, and they are usually available through the std.heap module of the standard library. Thus, just import the Zig Standard Library into your Zig module (with @import(\"std\")), and you can start using these allocators in your code.\nFurthermore, every allocator object is built on top of the Allocator interface in Zig. This means that, every allocator object you find in Zig must have the methods alloc(), create(), free() and destroy(). So, you can change the type of allocator you are using, but you don’t need to change the function calls to the methods that do the memory allocation (and the free memory operations) for your program.\n\n\n3.3.2 Why you need an allocator?\nAs we described at Section 3.1.4, everytime you make a function call in Zig, a space in the stack is reserved for this function call. But the stack has a key limitation which is: every object stored in the stack have a known fixed length.\nBut in reality, there are two very common instances where this “fixed length limitation” of the stack is a deal braker:\n\nthe objects that you create inside your function might grow in size during the execution of the function.\nsometimes, it is impossible to know upfront how many inputs you will receive, or how big this input will be.\n\nAlso, there is another instance where you might want to use an allocator, which is when you want to write a function that returns a pointer to a local object. As I described at Section 3.1.4, you cannot do that if this local object is stored in the stack. However, if this object is stored in the heap, then, you can return a pointer to this object at the end of the function. Because you (the programmer) control the lifetime of any heap memory that you allocate. You decide when this memory gets destroyed/freed.\nThese are common situations where the stack is not good for. That is why you need a different memory management strategy to store these objects inside your function. You need to use a memory type that can grow together with your objects, or that you can control the lifetime of this memory. The heap fits this description.\nAllocating memory on the heap is commonly known as dynamic memory management. As the objects you create grow in size during the execution of your program, you grow the amount of memory you have by allocating more memory in the heap to store these objects. And you do that in Zig, by using an allocator object.\n\n\n3.3.3 The different types of allocators\nAt the moment of the writing of this book, in Zig, we have 6 different allocators available in the standard library:\n\nGeneralPurposeAllocator().\npage_allocator().\nFixedBufferAllocator() and ThreadSafeFixedBufferAllocator().\nArenaAllocator().\nc_allocator() (requires you to link to libc).\n\nEach allocator has its own perks and limitations. All allocators, except FixedBufferAllocator() and ArenaAllocator(), are allocators that use the heap memory. So any memory that you allocate with these allocators, will be placed in the heap.\n\n\n3.3.4 General-purpose allocators\nThe GeneralPurposeAllocator(), as the name suggests, is a “general purpose” allocator. You can use it for every type of task. In the example below, I’m allocating enough space to store a single integer in the object some_number.\n\nconst std = @import(\"std\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const some_number = try allocator.create(u32);\n    defer allocator.destroy(some_number);\n\n    some_number.* = @as(u32, 45);\n}\n\nWhile useful, you might want to use the c_allocator(), which is a alias to the C standard allocator malloc(). So, yes, you can use malloc() in Zig if you want to. Just use the c_allocator() from the Zig standard library. However, if you do use c_allocator(), you must link to Libc when compiling your source code with the zig compiler, by including the flag -lc in your compilation process. If you do not link your source code to Libc, Zig will not be able to find the malloc() implementation in your system.\n\n\n3.3.5 Page allocator\nThe page_allocator() is an allocator that allocates full pages of memory in the heap. In other words, every time you allocate memory with page_allocator(), a full page of memory in the heap is allocated, instead of just a small piece of it.\nThe size of this page depends on the system you are using. Most systems use a page size of 4KB in the heap, so, that is the amount of memory that is normally allocated in each call by page_allocator(). That is why, page_allocator() is considered a fast, but also “wasteful” allocator in Zig. Because it allocates a big amount of memory in each call, and you most likely will not need that much memory in your program.\n\n\n3.3.6 Buffer allocators\nThe FixedBufferAllocator() and ThreadSafeFixedBufferAllocator() are allocator objects that work with a fixed sized buffer object at the back. In other words, they use a fixed sized buffer object as the basis for the memory. When you ask these allocator objects to allocate some memory for you, they are essentially reserving some amount of space inside this fixed sized buffer object for you to use.\nThis means that, in order to use these allocators, you must first create a buffer object in your code, and then, give this buffer object as an input to these allocators.\nThis also means that, these allocator objects can allocate memory both in the stack or in the heap. Everything depends on where the buffer object that you provide lives. If this buffer object lives in the stack, then, the memory allocated is “stack-based”. But if it lives on the heap, then, the memory allocated is “heap-based”.\nIn the example below, I’m creating a buffer object on the stack that is 10 elements long. Notice that I give this buffer object to the FixedBufferAllocator() constructor. Now, because this buffer object is 10 elements long, this means that I am limited to this space. I cannot allocate more than 10 elements with this allocator object. If I try to allocate more than that, the alloc() method will return an OutOfMemory error value.\n\nvar buffer: [10]u8 = undefined;\nfor (0..buffer.len) |i| {\n    buffer[i] = 0; // Initialize to zero\n}\n\nvar fba = std.heap.FixedBufferAllocator.init(&buffer);\nconst allocator = fba.allocator();\nconst input = try allocator.alloc(u8, 5);\ndefer allocator.free(input);\n\nRemember, the memory allocated by these allocator objects can be either from the stack, or, from the heap. It all depends on where the buffer object that you provide lives. In the above example, the buffer object lives in the stack, and, therefore, the memory allocated is based in the stack. But what if it was based on the heap?\nAs we described at Section 3.2, one of the main reasons why you would use the heap, instead of the stack, is to allocate huge amounts of space to store very big objects. Thus, let’s suppose you wanted to use a very big buffer object as the basis for your allocator objects. You would have to allocate this very big buffer object on the heap. The example below demonstrates this case.\n\nconst heap = std.heap.page_allocator;\nconst memory_buffer = try heap.alloc(\n    u8, 100 * 1024 * 1024 // 100 MB memory\n);\ndefer heap.free(memory_buffer);\nvar fba = std.heap.FixedBufferAllocator.init(\n    memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst input = try allocator.alloc(u8, 1000);\ndefer allocator.free(input);\n\n\n\n3.3.7 Arena allocator\nThe ArenaAllocator() is an allocator object that takes a child allocator as input. The idea behind the ArenaAllocator() in Zig is similar to the concept of “arenas” in the programming language Go5. It is an allocator object that allows you to allocate memory as many times you want, but free all memory only once. In other words, if you have, for example, called 5 times the method alloc() of an ArenaAllocator() object, you can free all the memory you allocated over these 5 calls at once, by simply calling the deinit() method of the same ArenaAllocator() object.\nIf you give, for example, a GeneralPurposeAllocator() object as input to the ArenaAllocator() constructor, like in the example below, then, the allocations you perform with alloc() will actually be made with the underlying object GeneralPurposeAllocator() that was passed. So, with an arena allocator, any new memory you ask for is allocated by the child allocator. The only thing that an arena allocator really does is help you to free all the memory you allocated multiple times with just a single command. In the example below, I called alloc() 3 times. So, if I did not use an arena allocator, then, I would need to call free() 3 times to free all the allocated memory.\n\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nvar aa = std.heap.ArenaAllocator.init(gpa.allocator());\ndefer aa.deinit();\nconst allocator = aa.allocator();\n\nconst in1 = try allocator.alloc(u8, 5);\nconst in2 = try allocator.alloc(u8, 10);\nconst in3 = try allocator.alloc(u8, 15);\n_ = in1; _ = in2; _ = in3;\n\n\n\n3.3.8 The alloc() and free() methods\nIn the code example below, we are accessing the stdin, which is the standard input channel, to receive an input from the user. We read the input given by the user with the readUntilDelimiterOrEof() method.\nNow, after reading the input of the user, we need to store this input somewhere in our program. That is why I use an allocator in this example. I use it to allocate some amount of memory to store this input given by the user. More specifically, the method alloc() of the allocator object is used to allocate an array capable of storing 50 u8 values.\nNotice that this alloc() method receives two inputs. The first one, is a type. This defines what type of values the allocated array will store. In the example below, we are allocating an array of unsigned 8-bit integers (u8). But you can create an array to store any type of value you want. Next, on the second argument, we define the size of the allocated array, by specifying how many elements this array will contain. In the case below, we are allocating an array of 50 elements.\nAt Section 1.8 we described that strings in Zig are simply arrays of characters. Each character is represented by a u8 value. So, this means that the array that was allocated in the object input is capable of storing a string that is 50-characters long.\nSo, in essence, the expression var input: [50]u8 = undefined would create an array for 50 u8 values in the stack of the current scope. But, you can allocate the same array in the heap by using the expression var input = try allocator.alloc(u8, 50).\n\nconst std = @import(\"std\");\nconst stdin = std.io.getStdIn();\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var input = try allocator.alloc(u8, 50);\n    defer allocator.free(input);\n    for (0..input.len) |i| {\n        input[i] = 0; // initialize all fields to zero.\n    }\n    // read user input\n    const input_reader = stdin.reader();\n    _ = try input_reader.readUntilDelimiterOrEof(\n        input,\n        '\\n'\n    );\n    std.debug.print(\"{s}\\n\", .{input});\n}\n\nAlso, notice that in this example, we use the defer keyword (which I described at Section 2.1.3) to run a small piece of code at the end of the current scope, which is the expression allocator.free(input). When you execute this expression, the allocator will free the memory that it allocated for the input object.\nWe have talked about this at Section 3.1.5. You should always explicitly free any memory that you allocate using an allocator! You do that by using the free() method of the same allocator object you used to allocate this memory. The defer keyword is used in this example only to help us execute this free operation at the end of the current scope.\n\n\n3.3.9 The create() and destroy() methods\nWith the alloc() and free() methods, you can allocate memory to store multiple elements at once. In other words, with these methods, we always allocate an array to store multiple elements at once. But what if you need enough space to store just a single item? Should you allocate an array of a single element through alloc()?\nThe answer is no! In this case, you should use the create() method of the allocator object. Every allocator object offers the create() and destroy() methods, which are used to allocate and free memory for a single item, respectively.\nSo, in essence, if you want to allocate memory to store an array of elements, you should use alloc() and free(). But if you need to store just a single item, then, the create() and destroy() methods are ideal for you.\nIn the example below, I’m defining a struct to represent an user of some sort. It could be an user for a game, or a software to manage resources, it doesn’t mater. Notice that I use the create() method this time, to store a single User object in the program. Also notice that I use the destroy() method to free the memory used by this object at the end of the scope.\n\nconst std = @import(\"std\");\nconst User = struct {\n    id: usize,\n    name: []const u8,\n\n    pub fn init(id: usize, name: []const u8) User {\n        return .{ .id = id, .name = name };\n    }\n};\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const user = try allocator.create(User);\n    defer allocator.destroy(user);\n\n    user.* = User.init(0, \"Pedro\");\n}\n\n\n\n\n\nChen, Jenny, and Ruohao Guo. 2022. “Stack and Heap Memory.” Introduction to Data Structures and Algorithms with C++. https://courses.engr.illinois.edu/cs225/fa2022/resources/stack-heap/.\n\n\nSobeston. 2024. “Zig Guide.” https://zig.guide/.\n\n\nZig Software Foundation. 2024. “Language Reference.” Zig Software Foundation. https://ziglang.org/documentation/master/.",
     "crumbs": [
       "<span class='chapter-number'>3</span>  <span class='chapter-title'>Memory and Allocators</span>"
     ]
@@ -434,7 +434,7 @@
     "href": "Chapters/02-debugging.html",
     "title": "5  Debugging Zig applications",
     "section": "",
-    "text": "5.1 Print debugging\nWe begin with the classic and battle-tested print debugging strategy. The key advantage that debugging offers you is visibility. With print statements you can easily see what results and objects are being produced by your application.\nThat is the essence of print debugging. Is to use print expressions to see the values that are being generated by your program, and, as a result, get a much better understanding of how your program is behaving.\nMany programmers often resort to the print functions in Zig, such as the stdout.print(), or, the std.debug.print(), to get a better understanding of their programs. This is a known and old strategy that is very simple and effective, and it is better known within the programming community as print debugging. In Zig, you can print information to the stdout or stderr streams of your system.\nLet’s begin with stdout. First, you need to get access to the stdout, by calling the getStdOut() method, from the Zig Standard Library. This method returns a file descriptor object, and, through this object you can read/write to the stdout. I recommend you to check out all methods available in this object, by checking the page in the Zig Standard Library Official Reference for the type File1.\nFor our purpose here, which is to write something to the stdout, especially to debug our program, I recommend you to use the writer() method, which gives your a writer object. This writer object offers some helper methods to write stuff into the file descriptor object that represents the stdout stream. In special, the print() method.\nThe print() method from this writer object is a “print formatter” type of a function. In other words, this method works exactly like the printf() function from C, or, like println!() from Rust. In the first argument of the function, you specify a template string, and, in the second argument, you provide a list of values (or objects) that you want to insert into your template message.\nIdeally, the template string in the first argument should contain some format specifier. Each format specifier is matched to a value (or object) that you have listed in the second argument. So, if you provided 5 different objects in the second argument, then, the template string should contain 5 format specifiers, one for each object provided.\nEach format specifier is represented by a single letter, and you provide this format specifier inside a pair of curly braces. So, if you want to format your object using the string specifier (s), then, you can insert the text {s} in your template string. Here is a quick list of the most used format specifiers:\nThe code example below gives you an example of use of this print() method with the d format specifier.\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    _ = try stdout.print(\"Result: {d}\", .{result});\n}\n\nResult: 50\nIs important to emphasize that, the stdout.print() method, as you would expect, print your template string into the stdout stream of your system. However, you can also print your template string into the stderr stream if your prefer. All you need to do, is to replace the stdout.print() call with the function std.debug.print(). Like this:\nconst std = @import(\"std\");\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    std.debug.print(\"Result: {d}\\n\", .{result});\n}\nYou could also achieve the exact same result by getting a file descriptor object to stderr, then, creating a writer object to stderr, then, using the print() method of this writer object, like in the example below:\nconst std = @import(\"std\");\nconst stderr = std.io.getStdErr().writer();\n// some more lines ...\n_ = try stderr.print(\"Result: {d}\", .{result});",
+    "text": "5.1 Print debugging\nWe begin with the classic and battle-tested print debugging strategy. The key advantage that debugging offers you is visibility. With print statements you can easily see what results and objects are being produced by your application.\nThat is the essence of print debugging. Is to use print expressions to see the values that are being generated by your program, and, as a result, get a much better understanding of how your program is behaving.\nMany programmers often resort to the print functions in Zig, such as the stdout.print(), or, the std.debug.print(), to get a better understanding of their programs. This is a known and old strategy that is very simple and effective, and it is better known within the programming community as print debugging. In Zig, you can print information to the stdout or stderr streams of your system.\nLet’s begin with stdout. First, you need to get access to the stdout, by calling the getStdOut() method, from the Zig Standard Library. This method returns a file descriptor object, and, through this object you can read/write to the stdout. I recommend you to check out all methods available in this object, by checking the page in the Zig Standard Library Official Reference for the type File1.\nFor our purpose here, which is to write something to the stdout, especially to debug our program, I recommend you to use the writer() method, which gives your a writer object. This writer object offers some helper methods to write stuff into the file descriptor object that represents the stdout stream. In special, the print() method.\nThe print() method from this writer object is a “print formatter” type of a function. In other words, this method works exactly like the printf() function from C, or, like println!() from Rust. In the first argument of the function, you specify a template string, and, in the second argument, you provide a list of values (or objects) that you want to insert into your template message.\nIdeally, the template string in the first argument should contain some format specifier. Each format specifier is matched to a value (or object) that you have listed in the second argument. So, if you provided 5 different objects in the second argument, then, the template string should contain 5 format specifiers, one for each object provided.\nEach format specifier is represented by a single letter, and you provide this format specifier inside a pair of curly braces. So, if you want to format your object using the string specifier (s), then, you can insert the text {s} in your template string. Here is a quick list of the most used format specifiers:\nThe code example below gives you an example of use of this print() method with the d format specifier.\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    _ = try stdout.print(\"Result: {d}\", .{result});\n}\n\nResult: 50\nIs important to emphasize that, the stdout.print() method, as you would expect, print your template string into the stdout stream of your system. However, you can also print your template string into the stderr stream if your prefer. All you need to do, is to replace the stdout.print() call with the function std.debug.print(). Like this:\nconst std = @import(\"std\");\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    std.debug.print(\"Result: {d}\\n\", .{result});\n}\n\nResult: 50\nYou could also achieve the exact same result by getting a file descriptor object to stderr, then, creating a writer object to stderr, then, using the print() method of this writer object, like in the example below:\nconst std = @import(\"std\");\nconst stderr = std.io.getStdErr().writer();\n// some more lines ...\n_ = try stderr.print(\"Result: {d}\", .{result});",
     "crumbs": [
       "<span class='chapter-number'>5</span>  <span class='chapter-title'>Debugging Zig applications</span>"
     ]
@@ -634,7 +634,7 @@
     "href": "Chapters/03-unittests.html",
     "title": "8  Unit tests",
     "section": "",
-    "text": "8.1 Introducing the test block\nIn Zig, unit tests are written inside a test declaration, or, how I prefer to call it, inside a test block. Every test block is written by using the keyword test. You can optionally use a string literal to write a label, which is responsible for identifying the specific group of unit tests that you are writing inside this specific test block.\nIn the example below, we are testing if the sum of two objects (a and b) is equal to 4. The expect() function from the Zig Standard Library is a function that receives a logical test as input. If this logical test results in true, then, the test passes. But if it results in false, then, the test fails.\nYou can write any Zig code you want inside a test block. Part of this code might be some necessary commands to setup your testing environment, or just initializing some objects that you need to use in your unit tests.\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest \"testing simple sum\" {\n    const a: u8 = 2;\n    const b: u8 = 2;\n    try expect((a + b) == 4);\n}\nYou can have multiple test blocks written on the same Zig module. Also, you can mix test blocks with your source code, with no problems or consequences. If you mix test blocks with your normal source code, when you execute the build, build-exe, build-obj or build-lib commands from the zig compiler that we exposed at Section 1.2.4, these test blocks are automatically ignored by the compiler.\nIn other words, the zig compiler builds and execute your unit tests only when you ask it to. By default, the compiler always ignore test blocks written in your Zig modules. The compiler normally checks only if there are any syntax errors in these test blocks.\nIf you take a look at the source code for most of the files present in the Zig Standard Library1, you can see that the test blocks are written together with the normal source code of the library. You can see this for example, at the array_list module2. So, the standard that the Zig developers decided to adopt is to keep their unit tests together with the source code of the functionality that they are testing.\nEach programmer might have a different opinion on this. Some of them might prefer to keep unit tests separate from the actual source code of their application. If that is your case, you can simply create a separate tests folder in your project, and start writing Zig modules that contains only unit tests (as you would normally do on a Python project with pytest, for example), and everything will work fine. It boils down to which is your preference here.",
+    "text": "8.1 Introducing the test block\nIn Zig, unit tests are written inside a test declaration, or, how I prefer to call it, inside a test block. Every test block is written by using the keyword test. You can optionally use a string literal to write a label, which is responsible for identifying the specific group of unit tests that you are writing inside this specific test block.\nIn the example below, we are testing if the sum of two objects (a and b) is equal to 4. The expect() function from the Zig Standard Library is a function that receives a logical test as input. If this logical test results in true, then, the test passes. But if it results in false, then, the test fails.\nYou can write any Zig code you want inside a test block. Part of this code might be some necessary commands to setup your testing environment, or just initializing some objects that you need to use in your unit tests.\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest \"testing simple sum\" {\n    const a: u8 = 2;\n    const b: u8 = 2;\n    try expect((a + b) == 4);\n}\n\n1/1 file103bc24525048.test.testing simple sum...OK\n  KAll 1 tests passed.\nYou can have multiple test blocks written on the same Zig module. Also, you can mix test blocks with your source code, with no problems or consequences. If you mix test blocks with your normal source code, when you execute the build, build-exe, build-obj or build-lib commands from the zig compiler that we exposed at Section 1.2.4, these test blocks are automatically ignored by the compiler.\nIn other words, the zig compiler builds and execute your unit tests only when you ask it to. By default, the compiler always ignore test blocks written in your Zig modules. The compiler normally checks only if there are any syntax errors in these test blocks.\nIf you take a look at the source code for most of the files present in the Zig Standard Library1, you can see that the test blocks are written together with the normal source code of the library. You can see this for example, at the array_list module2. So, the standard that the Zig developers decided to adopt is to keep their unit tests together with the source code of the functionality that they are testing.\nEach programmer might have a different opinion on this. Some of them might prefer to keep unit tests separate from the actual source code of their application. If that is your case, you can simply create a separate tests folder in your project, and start writing Zig modules that contains only unit tests (as you would normally do on a Python project with pytest, for example), and everything will work fine. It boils down to which is your preference here.",
     "crumbs": [
       "<span class='chapter-number'>8</span>  <span class='chapter-title'>Unit tests</span>"
     ]
@@ -664,7 +664,7 @@
     "href": "Chapters/03-unittests.html#testing-errors",
     "title": "8  Unit tests",
     "section": "8.4 Testing errors",
-    "text": "8.4 Testing errors\nOne common style of unit tests are those that look for specific errors in your functions. In other words, you write a unit test that tries to assert if a specific function call returns any error, or a specific type of error.\nIn C++ you would normally write this style of unit tests using, for example, the functions REQUIRE_THROWS() or CHECK_THROWS() from the Catch2 test framework3. In the case of a Python project, you would probably use the raises() function from pytest4. While in Rust, you would probably use assert_eq!() in conjunction with Err().\nBut in Zig, we use the expectError() function, from the std.testing module. With this function, you can test if a specific function call returns the exact type of error that you expect it to return. To use this function, you first write try expectError(). Then, on the first argument, you provide the type of error that you are expecting from the function call. Then, on the second argument, you write the function call that you expect to fail.\nThe code example below demonstrates such type of unit test in Zig. Notice that, inside the function alloc_error() we are allocating 100 bytes of memory, or, an array of 100 elements, for the object ibuffer. However, in the test block, we are using the FixedBufferAllocator() allocator object, which is limited to 10 bytes of space, because the object buffer, which we provided to the allocator object, have only 10 bytes of space.\nThat is why, the alloc_error() function raises an OutOfMemory error on this case. Because this function is trying to allocate more space than the allocator object allows. So, in essence, we are testing for a specific type of error, which is OutOfMemory. If the alloc_error() function returns any other type of error, then, the expectError() function would make the entire test fail.\n\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst expectError = std.testing.expectError;\nfn alloc_error(allocator: Allocator) !void {\n    var ibuffer = try allocator.alloc(u8, 100);\n    defer allocator.free(ibuffer);\n    ibuffer[0] = 2;\n}\n\ntest \"testing error\" {\n    var buffer: [10]u8 = undefined;\n    var fba = std.heap.FixedBufferAllocator.init(&buffer);\n    const allocator = fba.allocator();\n    try expectError(error.OutOfMemory, alloc_error(allocator));\n}\n\n1/1 oom.test.testing error... OK\nAll 1 tests passed.",
+    "text": "8.4 Testing errors\nOne common style of unit tests are those that look for specific errors in your functions. In other words, you write a unit test that tries to assert if a specific function call returns any error, or a specific type of error.\nIn C++ you would normally write this style of unit tests using, for example, the functions REQUIRE_THROWS() or CHECK_THROWS() from the Catch2 test framework3. In the case of a Python project, you would probably use the raises() function from pytest4. While in Rust, you would probably use assert_eq!() in conjunction with Err().\nBut in Zig, we use the expectError() function, from the std.testing module. With this function, you can test if a specific function call returns the exact type of error that you expect it to return. To use this function, you first write try expectError(). Then, on the first argument, you provide the type of error that you are expecting from the function call. Then, on the second argument, you write the function call that you expect to fail.\nThe code example below demonstrates such type of unit test in Zig. Notice that, inside the function alloc_error() we are allocating 100 bytes of memory, or, an array of 100 elements, for the object ibuffer. However, in the test block, we are using the FixedBufferAllocator() allocator object, which is limited to 10 bytes of space, because the object buffer, which we provided to the allocator object, have only 10 bytes of space.\nThat is why, the alloc_error() function raises an OutOfMemory error on this case. Because this function is trying to allocate more space than the allocator object allows. So, in essence, we are testing for a specific type of error, which is OutOfMemory. If the alloc_error() function returns any other type of error, then, the expectError() function would make the entire test fail.\n\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst expectError = std.testing.expectError;\nfn alloc_error(allocator: Allocator) !void {\n    var ibuffer = try allocator.alloc(u8, 100);\n    defer allocator.free(ibuffer);\n    ibuffer[0] = 2;\n}\n\ntest \"testing error\" {\n    var buffer: [10]u8 = undefined;\n    var fba = std.heap.FixedBufferAllocator.init(&buffer);\n    const allocator = fba.allocator();\n    try expectError(error.OutOfMemory, alloc_error(allocator));\n}\n\n1/1 file103bc545495c8.test.testing error...OKAll 1\n  1 tests passed.\n\n\n1/1 oom.test.testing error... OK\nAll 1 tests passed.",
     "crumbs": [
       "<span class='chapter-number'>8</span>  <span class='chapter-title'>Unit tests</span>"
     ]
@@ -674,7 +674,7 @@
     "href": "Chapters/03-unittests.html#testing-simple-equalities",
     "title": "8  Unit tests",
     "section": "8.5 Testing simple equalities",
-    "text": "8.5 Testing simple equalities\nIn Zig, there are some different ways you can test for an equality. You already saw that we can use expect() with the logical operator == to essentially reproduce an equality test. But we also have some other helper functions that you should know about, especially expectEqual(), expectEqualSlices() and expectEqualStrings().\nThe expectEqual() function, as the name suggests, is a classic test equality function. It receives two objects as input. The first object is the value that you expect to be in the second object. While second object is the object you have, or, the object that your application produced as result. So, with expectEqual() you are essentially testing if the values stored inside these two objects are equal or not.\nYou can see in the example below that, the test performed by expectEqual() failed. Because the objects v1 and v2 contain different values in them.\n\nconst std = @import(\"std\");\ntest \"values are equal?\" {\n    const v1 = 15;\n    const v2 = 18;\n    try std.testing.expectEqual(v1, v2);\n}\n\n1/1 ve.test.values are equal?...\n    expected 15, found 18\n    FAIL (TestExpectedEqual)\nve.zig:5:5: test.values are equal? (test)\n    try std.testing.expectEqual(v1, v2);\n    ^\n0 passed; 0 skipped; 1 failed.\nAlthough useful, the expectEqual() function does not work with arrays. For testing if two arrays are equal, you should use the expectEqualSlices() function instead. This function have three arguments. First, you provide the data type contained in both arrays that you are trying to compare. While the second and third arguments corresponds to the array objects that you want to compare.\nIn the example below, we are using this function to test if two array objects (array1 and array2) are equal or not. Since they are in fact equal, the unit test passed with no errors.\n\nconst std = @import(\"std\");\ntest \"arrays are equal?\" {\n    const array1 = [3]u32{1, 2, 3};\n    const array2 = [3]u32{1, 2, 3};\n    try std.testing.expectEqualSlices(\n        u32, &array1, &array2\n    );\n}\n\n1/1 oom.test.arrays are equal?... OK\nAll 1 tests passed.\nAt last, you might also want to use the expectEqualStrings() function. As the name suggests, you can use this function to test if two strings are equal or not. Just provide the two string objects that you want to compare, as inputs to the function.\nIf the function finds any existing differences between the two strings, then, the function will raise an error, and also, print an error message that shows the exact difference between the two string objects provided, as the example below demonstrates:\n\nconst std = @import(\"std\");\ntest \"strings are equal?\" {\n    const str1 = \"hello, world!\";\n    const str2 = \"Hello, world!\";\n    try std.testing.expectEqualStrings(\n        str1, str2\n    );\n}\n\n1/1 t.test.strings are equal?... \n====== expected this output: =========\nhello, world!␃\n======== instead found this: =========\nHello, world!␃\n======================================\nFirst difference occurs on line 1:\nexpected:\nhello, world!\n^ ('\\x68')\nfound:\nHello, world!\n^ ('\\x48')",
+    "text": "8.5 Testing simple equalities\nIn Zig, there are some different ways you can test for an equality. You already saw that we can use expect() with the logical operator == to essentially reproduce an equality test. But we also have some other helper functions that you should know about, especially expectEqual(), expectEqualSlices() and expectEqualStrings().\nThe expectEqual() function, as the name suggests, is a classic test equality function. It receives two objects as input. The first object is the value that you expect to be in the second object. While second object is the object you have, or, the object that your application produced as result. So, with expectEqual() you are essentially testing if the values stored inside these two objects are equal or not.\nYou can see in the example below that, the test performed by expectEqual() failed. Because the objects v1 and v2 contain different values in them.\n\nconst std = @import(\"std\");\ntest \"values are equal?\" {\n    const v1 = 15;\n    const v2 = 18;\n    try std.testing.expectEqual(v1, v2);\n}\n\n1/1 ve.test.values are equal?...\n    expected 15, found 18\n    FAIL (TestExpectedEqual)\nve.zig:5:5: test.values are equal? (test)\n    try std.testing.expectEqual(v1, v2);\n    ^\n0 passed; 0 skipped; 1 failed.\nAlthough useful, the expectEqual() function does not work with arrays. For testing if two arrays are equal, you should use the expectEqualSlices() function instead. This function have three arguments. First, you provide the data type contained in both arrays that you are trying to compare. While the second and third arguments corresponds to the array objects that you want to compare.\nIn the example below, we are using this function to test if two array objects (array1 and array2) are equal or not. Since they are in fact equal, the unit test passed with no errors.\n\nconst std = @import(\"std\");\ntest \"arrays are equal?\" {\n    const array1 = [3]u32{1, 2, 3};\n    const array2 = [3]u32{1, 2, 3};\n    try std.testing.expectEqualSlices(\n        u32, &array1, &array2\n    );\n}\n\n1/1 file103bc78cf09de.test.arrays are equal?...OKA\n  All 1 tests passed.\n\n\n1/1 oom.test.arrays are equal?... OK\nAll 1 tests passed.\nAt last, you might also want to use the expectEqualStrings() function. As the name suggests, you can use this function to test if two strings are equal or not. Just provide the two string objects that you want to compare, as inputs to the function.\nIf the function finds any existing differences between the two strings, then, the function will raise an error, and also, print an error message that shows the exact difference between the two string objects provided, as the example below demonstrates:\n\nconst std = @import(\"std\");\ntest \"strings are equal?\" {\n    const str1 = \"hello, world!\";\n    const str2 = \"Hello, world!\";\n    try std.testing.expectEqualStrings(\n        str1, str2\n    );\n}\n\n1/1 t.test.strings are equal?... \n====== expected this output: =========\nhello, world!␃\n======== instead found this: =========\nHello, world!␃\n======================================\nFirst difference occurs on line 1:\nexpected:\nhello, world!\n^ ('\\x68')\nfound:\nHello, world!\n^ ('\\x48')",
     "crumbs": [
       "<span class='chapter-number'>8</span>  <span class='chapter-title'>Unit tests</span>"
     ]
@@ -834,7 +834,7 @@
     "href": "Chapters/09-error-handling.html#learning-more-about-errors-in-zig",
     "title": "10  Error handling and unions",
     "section": "",
-    "text": "t.zig:8:17: error: error set is discarded\nt.zig:8:17: note: consider using 'try', 'catch', or 'if'\n\n10.1.1 Returning errors from functions\nAs we described at Section 1.2.3, when we have a function that might return an error value, this function normally includes an exclamation mark (!) in its return type annotation. The presence of this exclamation mark indicates that this function might return an error value as result, and, the zig compiler forces you to always handle explicitly the case of this function returning an error value.\nTake a look at the print_name() function below. This function might return an error in the stdout.print() function call, and, as a consequence, its return type (!void) includes an exclamation mark in it.\n\nfn print_name() !void {\n    const stdout = std.getStdOut().writer();\n    try stdout.print(\"My name is Pedro!\", .{});\n}\n\nIn the example above, we are using the exclamation mark to tell the zig compiler that this function might return some error. But which error exactly is returned from this function? For now, we are not specifying a specific error value. We only known for now that some error value (whatever it is) might be returned.\nBut in fact, you can (if you want to) specify clearly which exact error values might be returned from this function. There are lot of examples of this in the Zig Standard Library. Take this fill() function from the http.Client module as an example. This function returns either a error value of type ReadError, or void.\n\npub fn fill(conn: *Connection) ReadError!void {\n    // The body of this function ...\n}\n\nThis idea of specifying the exact error values that you expect to be returned from the function is interesting. Because they automatically become some sort of documentation of your function, and also, it allows the zig compiler to perform some extra checks over your code. Because it can check if there is any other type of error value that is being generated inside your function, and, that it is not being accounted for in this return type annotation.\nAnyway, you can list the types of errors that can be returned from the function by listing them on the left side of the exclamation mark. While the valid values stay on the right side of the exclamation mark. So the syntax format become:\n&lt;error-value&gt;!&lt;valid-value&gt;\n\n\n10.1.2 Error sets\nBut what about when we have a single function that might return different types of errors? When you have such a function, you can list all of these different types of errors that can be returned from this function, through a structure in Zig that we call of an error set.\nAn error set is a special case of an union type. It is an union that contains error values in it. Not all programming languages have a notion of an “union object”. But in summary, an union is just a set of data types. Unions are used to allow an object to have multiple data types. For example, a union of x, y and z, means that an object can be either of type x, or type y or type z.\nWe are going to talk in more depth about unions at Section 10.3. But you can write an error set by writing the keyword error before a pair of curly braces, then you list the error values that can be returned from the function inside this pair of curly braces.\nTake the resolvePath() function below as an example, which comes from the introspect.zig module of the Zig Standard Library. We can see in its return type annotation, that this function return either: 1) a valid slice of u8 values ([]u8); or, 2) one of the three different types of error values listed inside the error set (OutOfMemory, Unexpected, etc.). This is an usage example of an error set.\n\npub fn resolvePath(\n    ally: mem.Allocator,\n    p: []const u8,\n) error{\n    OutOfMemory,\n    CurrentWorkingDirectoryUnlinked,\n    Unexpected,\n}![]u8 {\n    // The body of the function ...\n}\n\nThis is a valid way of annotating the return value of a Zig function. But, if you navigate through the modules that composes the Zig Standard Library, you will notice that, for the majority of cases, the programmers prefer to give a descriptive name to this error set, and then, use this name (or this “label”) of the error set in the return type annotation, instead of using the error set directly.\nWe can see that in the ReadError error set that we showed earlier in the fill() function, which is defined in the http.Client module. So yes, I presented the ReadError as if it was just a standard and single error value, but in fact, it is an error set defined in the http.Client module, and therefore, it actually represents a set of different error values that might happen inside the fill() function.\nTake a look at the ReadError definition reproduced below. Notice that we are grouping all of these different error values into a single object, and then, we use this object into the return type annotation of the function. Like the fill() function that we showed earlier, or, the readvDirect() function from the same module, which is reproduced below.\n\npub const ReadError = error{\n    TlsFailure,\n    TlsAlert,\n    ConnectionTimedOut,\n    ConnectionResetByPeer,\n    UnexpectedReadFailure,\n    EndOfStream,\n};\n// Some lines of code\npub fn readvDirect(\n        conn: *Connection,\n        buffers: []std.posix.iovec\n    ) ReadError!usize {\n    // The body of the function ...\n}\n\nSo, an error set is just a convenient way of grouping a set of possible error values into a single object, or a single type of an error value.\n\n\n10.1.3 Casting error values\nLet’s suppose you have two different error sets, named A and B. If error set A is a superset of error set B, then, you can cast (or coerce) error values from B into error values of A.\nError sets are just a set of error values. So, if the error set A contains all error values from the error set B, then A becomes a superset of B. You could also say that the error set B is a subset of error set A.\nThe example below demonstrates this idea. Because A contains all values from B, A is a superset of B. In math notation, we would say that \\(A \\supset B\\). As a consequence, we can give an error value from B as input to the cast() function, and, implicitly cast this input into the same error value, but from the A set.\n\nconst std = @import(\"std\");\nconst A = error{\n    ConnectionTimeoutError,\n    DatabaseNotFound,\n    OutOfMemory,\n    InvalidToken,\n};\nconst B = error {\n    OutOfMemory,\n};\n\nfn cast(err: B) A {\n    return err;\n}\n\ntest \"coerce error value\" {\n    const error_value = cast(B.OutOfMemory);\n    try std.testing.expect(\n        error_value == A.OutOfMemory\n    );\n}",
+    "text": "t.zig:8:17: error: error set is discarded\nt.zig:8:17: note: consider using 'try', 'catch', or 'if'\n\n10.1.1 Returning errors from functions\nAs we described at Section 1.2.3, when we have a function that might return an error value, this function normally includes an exclamation mark (!) in its return type annotation. The presence of this exclamation mark indicates that this function might return an error value as result, and, the zig compiler forces you to always handle explicitly the case of this function returning an error value.\nTake a look at the print_name() function below. This function might return an error in the stdout.print() function call, and, as a consequence, its return type (!void) includes an exclamation mark in it.\n\nfn print_name() !void {\n    const stdout = std.getStdOut().writer();\n    try stdout.print(\"My name is Pedro!\", .{});\n}\n\nIn the example above, we are using the exclamation mark to tell the zig compiler that this function might return some error. But which error exactly is returned from this function? For now, we are not specifying a specific error value. We only known for now that some error value (whatever it is) might be returned.\nBut in fact, you can (if you want to) specify clearly which exact error values might be returned from this function. There are lot of examples of this in the Zig Standard Library. Take this fill() function from the http.Client module as an example. This function returns either a error value of type ReadError, or void.\n\npub fn fill(conn: *Connection) ReadError!void {\n    // The body of this function ...\n}\n\nThis idea of specifying the exact error values that you expect to be returned from the function is interesting. Because they automatically become some sort of documentation of your function, and also, it allows the zig compiler to perform some extra checks over your code. Because it can check if there is any other type of error value that is being generated inside your function, and, that it is not being accounted for in this return type annotation.\nAnyway, you can list the types of errors that can be returned from the function by listing them on the left side of the exclamation mark. While the valid values stay on the right side of the exclamation mark. So the syntax format become:\n&lt;error-value&gt;!&lt;valid-value&gt;\n\n\n10.1.2 Error sets\nBut what about when we have a single function that might return different types of errors? When you have such a function, you can list all of these different types of errors that can be returned from this function, through a structure in Zig that we call of an error set.\nAn error set is a special case of an union type. It is an union that contains error values in it. Not all programming languages have a notion of an “union object”. But in summary, an union is just a set of data types. Unions are used to allow an object to have multiple data types. For example, a union of x, y and z, means that an object can be either of type x, or type y or type z.\nWe are going to talk in more depth about unions at Section 10.3. But you can write an error set by writing the keyword error before a pair of curly braces, then you list the error values that can be returned from the function inside this pair of curly braces.\nTake the resolvePath() function below as an example, which comes from the introspect.zig module of the Zig Standard Library. We can see in its return type annotation, that this function return either: 1) a valid slice of u8 values ([]u8); or, 2) one of the three different types of error values listed inside the error set (OutOfMemory, Unexpected, etc.). This is an usage example of an error set.\n\npub fn resolvePath(\n    ally: mem.Allocator,\n    p: []const u8,\n) error{\n    OutOfMemory,\n    CurrentWorkingDirectoryUnlinked,\n    Unexpected,\n}![]u8 {\n    // The body of the function ...\n}\n\nThis is a valid way of annotating the return value of a Zig function. But, if you navigate through the modules that composes the Zig Standard Library, you will notice that, for the majority of cases, the programmers prefer to give a descriptive name to this error set, and then, use this name (or this “label”) of the error set in the return type annotation, instead of using the error set directly.\nWe can see that in the ReadError error set that we showed earlier in the fill() function, which is defined in the http.Client module. So yes, I presented the ReadError as if it was just a standard and single error value, but in fact, it is an error set defined in the http.Client module, and therefore, it actually represents a set of different error values that might happen inside the fill() function.\nTake a look at the ReadError definition reproduced below. Notice that we are grouping all of these different error values into a single object, and then, we use this object into the return type annotation of the function. Like the fill() function that we showed earlier, or, the readvDirect() function from the same module, which is reproduced below.\n\npub const ReadError = error{\n    TlsFailure,\n    TlsAlert,\n    ConnectionTimedOut,\n    ConnectionResetByPeer,\n    UnexpectedReadFailure,\n    EndOfStream,\n};\n// Some lines of code\npub fn readvDirect(\n        conn: *Connection,\n        buffers: []std.posix.iovec\n    ) ReadError!usize {\n    // The body of the function ...\n}\n\nSo, an error set is just a convenient way of grouping a set of possible error values into a single object, or a single type of an error value.\n\n\n10.1.3 Casting error values\nLet’s suppose you have two different error sets, named A and B. If error set A is a superset of error set B, then, you can cast (or coerce) error values from B into error values of A.\nError sets are just a set of error values. So, if the error set A contains all error values from the error set B, then A becomes a superset of B. You could also say that the error set B is a subset of error set A.\nThe example below demonstrates this idea. Because A contains all values from B, A is a superset of B. In math notation, we would say that \\(A \\supset B\\). As a consequence, we can give an error value from B as input to the cast() function, and, implicitly cast this input into the same error value, but from the A set.\n\nconst std = @import(\"std\");\nconst A = error{\n    ConnectionTimeoutError,\n    DatabaseNotFound,\n    OutOfMemory,\n    InvalidToken,\n};\nconst B = error {\n    OutOfMemory,\n};\n\nfn cast(err: B) A {\n    return err;\n}\n\ntest \"coerce error value\" {\n    const error_value = cast(B.OutOfMemory);\n    try std.testing.expect(\n        error_value == A.OutOfMemory\n    );\n}\n\n1/1 file10459ffd0e21.test.coerce error value...OKA\n  All 1 tests passed.",
     "crumbs": [
       "<span class='chapter-number'>10</span>  <span class='chapter-title'>Error handling and unions</span>"
     ]
@@ -894,7 +894,7 @@
     "href": "Chapters/09-data-structures.html#sec-maps-hashtables",
     "title": "11  Data Structures",
     "section": "11.2 Maps or HashTables",
-    "text": "11.2 Maps or HashTables\nSome professionals know this type of data structure by different terms, like “map”, “hashmap” or “associative arrays”. But the most common term used is hashtable. Every programming language normally have some implementation of a hashtable in their standard libraries. Python have dict(), C++ have std::map and std::unordered_map, Rust have HashMap, Javascript have Object() and Map(), etc.\n\n11.2.1 What is a hashtable?\nA hashtable is a data structure based on key-value pairs. You provide a key and a value to this structure, then, the hashtable will store the input value at a location that can be identified by the input key that you provided. It does that by using an underlying array and a hash function. These two components are essential to how a hashtable works.\nUnder the hood, the hashtable contains an array. This array is where the values are stored, and the elements of this array are usually called of buckets. So the values that you provide to the hashtable are stored inside buckets, and you access each bucket by using an index.\nWhen you provide a key to a hashtable, it passes this key to the hash function. This hash function uses some sort of hashing algorithm to transform this key into an index. This index is actually an array index. It is a position in the underlying array of the hashtable. This is how a key identifies a specific position (or location) inside the hashtable structure.\nTherefore, you provide a key to the hashtable, and this key identifies a specific location inside the hashtable, then, the hashtable takes the input value that you provided, and stores this value in the location identified by this input key. You could say that the key maps to the value stored in the hashtable. You find the value, by using the key that identifies the location where the value is stored. The Figure 11.2 presents this process visually.\n\n\n\n\n\n\nFigure 11.2: A diagram of a Hashtable. Source: Wikipedia, the free encyclopedia.\n\n\n\nThe operation described in the previous paragraph is normally called an insertion operation. Because you are inserting new values into the hashtable. But there are other types of operations in hashtables such as delete and lookup. Delete is self describing, it is when you delete (or remove) a value from the hashtable. While lookup corresponds to when you look at a value that is stored in the hashtable, by using the key that identifies the location where this value is stored.\nSometimes, instead of storing the values directly, the underlying array of the hashtable might be an array of pointers, i.e. the buckets of the array stores pointers that points to the value, or also, may be an array of linked lists. These cases are common on hashtables that allows duplicate keys, or, in other words, on hashtables that effectively handle “collisions” that may arise from the hash function.\nDuplicate keys, or this “collision” thing that I’m talking about, is when you have two different keys that points to the same location (i.e. to the same index) in the underlying array of the hashtable. This might happen depending on the characteristics of the hash function that is being used in the hashtable. Some implementations of the hashtable will actively deal with collisions, meaning that, they will handle this case in some way. For example, the hashtable might transform all buckets into linked lists. Because with a linked list you can store multiple values into a single bucket.\nThere are different techniques to handle collisions in hashtables, which I will not describe in this book, because it is not our main scope here. But you can find a good description of some of the most common techniques at the Wikipedia page of hashtables (Wikipedia 2024).\n\n\n11.2.2 Hashtables in Zig\nThe Zig Standard Library provides different implementations of a hashtable. Each implementation have its own cons and pros, which we will discuss later on, and all of them are available through the std.hash_map module.\nThe HashMap struct is a general-purpose hashtable, which have very fast operations (lookup, insertion, delete), and also, quite high load factors for low memory usage. You can create and provide a context object to the HashMap constructor. This context object allows you to tailor the behaviour of the hashtable itself, because you can provide a hash function implementation to be used by the hashtable through this context object.\nBut let’s not worry about this context object now, because it is meant to be used by “experts in the field of hashtables”. Since we are most likely not experts in this field, we are going to take the easy way to create a hashtable. Which is by using the AutoHashMap() function.\nThis AutoHashMap() function is essentially a “create a hashtable object that uses the default settings” type of function. It automatically chooses a context object, and, therefore, a hash function implementation, for you. This function receives two data types as input, the first input is the data type of the keys that will be used in this hashtable, while the second input is the data type of the data that will be stored inside the hashtable, that is, the data type of the values to be stored.\nIn the example below, we are providing the data type u32 in the first argument, and u16 in the second argument of this function. This means that we are going to use u32 values as keys in this hashtable, while u16 values are the actual values that are going to be stored into this hashtable. At the end of this process, the hash_table object contains a HashMap object that uses the default settings and context.\n\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n    std.debug.print(\n        \"Value at key 50050: {d}\\n\",\n        .{hash_table.get(50050).?}\n    );\n\n    if (hash_table.remove(57709)) {\n        std.debug.print(\n            \"Value at key 57709 successfully removed!\\n\",\n            .{}\n        );\n    }\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n}\n\nN of values stored: 3\nValue at key 50050: 55\nValue at key 57709 successfully removed!\nN of values stored: 2\nYou can add/put new values into the hashtable by using the put() method. The first argument is the key to be used, and the second argument is the actual value that you want to store inside the hashtable. In the example below, we first add the value 89 using the key 54321, next, we add the value 55 using the key 50050, etc.\nNotice that we have used the method count() to see how many values are currently stored in the hashtable. After that, we also use the get() method to access (or look) at the value stored in the position identified by the key 500050. The output of this get() method is an optional value. This is why we use the ? method at the end to get the actual value.\nAlso notice that we can remove (or delete) values from the hashtable by using the remove() method. You provide the key that identifies the value that you want to delete, then, the method will delete this value and return a true value as output. This true value essentially tells us that the method successfully deleted the value.\nBut this delete operation might not be always successful. For example, you might provide the wrong key to this method. I mean, maybe you provide (either intentionally or unintentionally) a key that points to an empty bucket, i.e. a bucket that still doesn’t have a value in it. In this case, the remove() method would return a false value.\n\n\n11.2.3 Iterating through the hashtable\nIterating through the keys and values that are currently being stored in the hashtable is a very common necessity. You can do that in Zig by using an iterator object that can iterate through the elements of your hashtable object.\nThis iterator object works like any other iterator object that you would find in languages such as C++ and Rust. It is basically a pointer object that points to some value in the container, and has a next() method that you can use to navigate (or iterate) through the values in the container.\nYou can create such iterator object by using the iterator() method of the hashtable object. This method returns an iterator object, from which you can use the next() method in conjunction with a while loop to iterate through the elements of your hashtable. The next() method returns an optional Entry value, and therefore, you must unwrap this optional value to get the actual Entry value from which you can access the key and also the value identified by this key.\nWith this Entry value at hand, you can access the key of this current entry by using the key_ptr attribute and dereferencing the pointer that lives inside of it, while the value identified by this key is accessed through the value_ptr attribute instead, which is also a pointer to be dereferenced. The code example below demonstrates the use of these elements:\n\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n\n    var it = hash_table.iterator();\n    while (it.next()) |kv| {\n        // Access the current key\n        std.debug.print(\"Key: {d} | \", .{kv.key_ptr.*});\n        // Access the current value\n        std.debug.print(\"Value: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n\nKey: 54321 | Value: 89\nKey: 50050 | Value: 55\nKey: 57709 | Value: 41\nIf you want to iterate specifically through the values or the keys of your hashtable, you can create a key iterator or a value iterator object. These are also iterator objects, which have the same next() method that you can use to iterate through the hashtable.\nKey iterators are created from the keyIterator() method of your hashtable object, while value iterators are created from the valueIterator() method. All you have to do is to unwrap the value from the next() method and deference it directly to access the key or the value that you are iterating over. The code example below demonstrates the use of a key iterator, but you can replicate the same logic to a value iterator.\n\nvar kit = hash_table.keyIterator();\nwhile (kit.next()) |key| {\n    std.debug.print(\"Key: {d}\\n\", .{key.*});\n}\n\nKey: 54321\nKey: 50050\nKey: 57709\n\n\n11.2.4 The ArrayHashMap hashtable\nIf you need to iterate through the elements of your hashtable constantly, you might want to use the ArrayHashMap struct for your specific case, instead of going with the usual and general-purpose HashMap struct.\nThe ArrayHashMap struct creates a hashtable that is faster to iterate over. That is why this specific type of hashtable might be valuable to you. Some other properties of a ArrayHashMap hashtable are:\n\nthe order of insertion is preserved, i.e. the order of the values that you find while iterating through this hashtable is actually the order in which these values were inserted in the hashtable.\nthe key-value pairs are stored sequentially, one after another.\n\nYou can create an ArrayHashMap object by using, once again, a helper function that chooses automatically for you a hash function implementation. This is the AutoArrayHashMap() function, which works very similarly to the AutoHashMap() function that we presented at Section 11.2.2.\nYou provide two data types to this function. The data type of the keys that will be used in this hashtable, and the data type of the values that will be stored in this hashtable.\nAn ArrayHashMap object have essentially the exact same methods from the HashMap struct. So you can insert new values into the hashtable by using the put() method, and you can look (or get) a value from the hashtable by using the get() method. But the remove() method is not available in this specific type of hashtable.\nIn order to delete values from the hashtable, you would use the same methods that you find in an ArrayList object, i.e. a dynamic array. I presented these methods at Section 11.1.4, which are the swapRemove() and orderedRemove() methods. These methods have the same meaning here, or, the same effect that they have in an ArrayList object.\nThis means that, with swapRemove() you remove the value from the hashtable, but you do not preserve the order in which the values were inserted into the structure. While orderedRemove() is able to retain the order in which these values were inserted.\nBut instead of providing an index as input to swapRemove() or orderedRemove(), like I described at Section 11.1.4, these methods here in an ArrayHashMap take a key as input, like the remove() method from a HashMap object. If you want to provide an index as input, instead of a key, you should use the swapRemoveAt() and orderedRemoveAt() methods.\n\nvar hash_table = AutoArrayHashMap(u32, u16)\n    .init(allocator);\ndefer hash_table.deinit();\n\n\n\n11.2.5 The StringHashMap hashtable\nOne thing that you will notice in the other two types of hashtables that I have presented over the last sections, is that neither of them accepts a slice data type in their keys. What this means is that you cannot use a slice value to represent a key in these types of hashtable.\nThe most obvious consequence of this, is that you cannot use strings as keys in these hashtables. But it is extremely common to use strings as keys in hashtables.\nTake this very simple Javascript code snippet as an example. We are creating a simple hashtable object named people. Then, we add a new entry to this hashtable, which is identified by the string 'Pedro'. This string is the key in this case, while the object containing different personal information such as age, height and city, is the value to be stored in the hashtable.\nvar people = new Object();\npeople['Pedro'] = {\n    'age': 25,\n    'height': 1.67,\n    'city': 'Belo Horizonte'\n};\nThis pattern of using strings as keys is very common in all sorts of situations. That is why the Zig Standard Library offers a specific type of hashtable for this purpose, which is created through the StringHashMap() function. This function creates a hashtable that uses strings as keys. The only input of this function is the data type of the values that will be stored into this hashtable.\nIn the example below, I’m creating a hashtable to store the ages of different people. Each key in this hashtable is represented by the name of each person, while the value stored in the hashtable is the age of this person identified by the key.\nThat is why I provide the u8 data type (which is the data type used by the age values) as input to this StringHashMap() function. As the result, it creates a hashtable that uses string values as keys, and, that stores u8 values in it. Notice that an allocator object is provided at the init() method of the resulting object from the StringHashMap() function.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var ages = std.StringHashMap(u8).init(allocator);\n    defer ages.deinit();\n\n    try ages.put(\"Pedro\", 25);\n    try ages.put(\"Matheus\", 21);\n    try ages.put(\"Abgail\", 42);\n\n    var it = ages.iterator();\n    while (it.next()) |kv| {\n        std.debug.print(\"Key: {s} | \", .{kv.key_ptr.*});\n        std.debug.print(\"Age: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n\nKey: Pedro | Age: 25\nKey: Abgail | Age: 42\nKey: Matheus | Age: 21\n\n\n11.2.6 The StringArrayHashMap hashtable\nThe Zig Standard Library also provides a type of hashtable that mix the cons and pros of the StringHashMap and ArrayHashMap together. That is, a hashtable that uses strings as keys, but also have the advantages from ArrayHashMap. In other words, you can have a hashtable that is fast to iterate over, that preserves insertion order, and also, that uses strings as keys.\nYou can create such type of hashtable by using the StringArrayHashMap() function. This function accepts a data type as input, which is the data type of the values that are going to be stored inside this hashtable, in the same style as the function presented at Section 11.2.5.\nYou can insert new values into this hashtable by using the same put() method that we have discussed at Section 11.2.5. And you can also get values from the hashtable by using the same get() method. Like its ArrayHashMap brother, to delete values from this specific type of hashtable, we also use the orderedRemove() and swapRemove() methods, with the same effects that I have described at Section 11.2.4.\nIf we take the code example that was exposed at Section 11.2.5, we can achieve the exact same result with StringArrayHashMap():\n\nvar ages = std.StringArrayHashMap(u8).init(allocator);",
+    "text": "11.2 Maps or HashTables\nSome professionals know this type of data structure by different terms, like “map”, “hashmap” or “associative arrays”. But the most common term used is hashtable. Every programming language normally have some implementation of a hashtable in their standard libraries. Python have dict(), C++ have std::map and std::unordered_map, Rust have HashMap, Javascript have Object() and Map(), etc.\n\n11.2.1 What is a hashtable?\nA hashtable is a data structure based on key-value pairs. You provide a key and a value to this structure, then, the hashtable will store the input value at a location that can be identified by the input key that you provided. It does that by using an underlying array and a hash function. These two components are essential to how a hashtable works.\nUnder the hood, the hashtable contains an array. This array is where the values are stored, and the elements of this array are usually called of buckets. So the values that you provide to the hashtable are stored inside buckets, and you access each bucket by using an index.\nWhen you provide a key to a hashtable, it passes this key to the hash function. This hash function uses some sort of hashing algorithm to transform this key into an index. This index is actually an array index. It is a position in the underlying array of the hashtable. This is how a key identifies a specific position (or location) inside the hashtable structure.\nTherefore, you provide a key to the hashtable, and this key identifies a specific location inside the hashtable, then, the hashtable takes the input value that you provided, and stores this value in the location identified by this input key. You could say that the key maps to the value stored in the hashtable. You find the value, by using the key that identifies the location where the value is stored. The Figure 11.2 presents this process visually.\n\n\n\n\n\n\nFigure 11.2: A diagram of a Hashtable. Source: Wikipedia, the free encyclopedia.\n\n\n\nThe operation described in the previous paragraph is normally called an insertion operation. Because you are inserting new values into the hashtable. But there are other types of operations in hashtables such as delete and lookup. Delete is self describing, it is when you delete (or remove) a value from the hashtable. While lookup corresponds to when you look at a value that is stored in the hashtable, by using the key that identifies the location where this value is stored.\nSometimes, instead of storing the values directly, the underlying array of the hashtable might be an array of pointers, i.e. the buckets of the array stores pointers that points to the value, or also, may be an array of linked lists. These cases are common on hashtables that allows duplicate keys, or, in other words, on hashtables that effectively handle “collisions” that may arise from the hash function.\nDuplicate keys, or this “collision” thing that I’m talking about, is when you have two different keys that points to the same location (i.e. to the same index) in the underlying array of the hashtable. This might happen depending on the characteristics of the hash function that is being used in the hashtable. Some implementations of the hashtable will actively deal with collisions, meaning that, they will handle this case in some way. For example, the hashtable might transform all buckets into linked lists. Because with a linked list you can store multiple values into a single bucket.\nThere are different techniques to handle collisions in hashtables, which I will not describe in this book, because it is not our main scope here. But you can find a good description of some of the most common techniques at the Wikipedia page of hashtables (Wikipedia 2024).\n\n\n11.2.2 Hashtables in Zig\nThe Zig Standard Library provides different implementations of a hashtable. Each implementation have its own cons and pros, which we will discuss later on, and all of them are available through the std.hash_map module.\nThe HashMap struct is a general-purpose hashtable, which have very fast operations (lookup, insertion, delete), and also, quite high load factors for low memory usage. You can create and provide a context object to the HashMap constructor. This context object allows you to tailor the behaviour of the hashtable itself, because you can provide a hash function implementation to be used by the hashtable through this context object.\nBut let’s not worry about this context object now, because it is meant to be used by “experts in the field of hashtables”. Since we are most likely not experts in this field, we are going to take the easy way to create a hashtable. Which is by using the AutoHashMap() function.\nThis AutoHashMap() function is essentially a “create a hashtable object that uses the default settings” type of function. It automatically chooses a context object, and, therefore, a hash function implementation, for you. This function receives two data types as input, the first input is the data type of the keys that will be used in this hashtable, while the second input is the data type of the data that will be stored inside the hashtable, that is, the data type of the values to be stored.\nIn the example below, we are providing the data type u32 in the first argument, and u16 in the second argument of this function. This means that we are going to use u32 values as keys in this hashtable, while u16 values are the actual values that are going to be stored into this hashtable. At the end of this process, the hash_table object contains a HashMap object that uses the default settings and context.\n\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n    std.debug.print(\n        \"Value at key 50050: {d}\\n\",\n        .{hash_table.get(50050).?}\n    );\n\n    if (hash_table.remove(57709)) {\n        std.debug.print(\n            \"Value at key 57709 successfully removed!\\n\",\n            .{}\n        );\n    }\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n}\n\nN of values stored: 3\nValue at key 50050: 55\nValue at key 57709 successfully removed!\nN of values stored: 2\nYou can add/put new values into the hashtable by using the put() method. The first argument is the key to be used, and the second argument is the actual value that you want to store inside the hashtable. In the example below, we first add the value 89 using the key 54321, next, we add the value 55 using the key 50050, etc.\nNotice that we have used the method count() to see how many values are currently stored in the hashtable. After that, we also use the get() method to access (or look) at the value stored in the position identified by the key 500050. The output of this get() method is an optional value. This is why we use the ? method at the end to get the actual value.\nAlso notice that we can remove (or delete) values from the hashtable by using the remove() method. You provide the key that identifies the value that you want to delete, then, the method will delete this value and return a true value as output. This true value essentially tells us that the method successfully deleted the value.\nBut this delete operation might not be always successful. For example, you might provide the wrong key to this method. I mean, maybe you provide (either intentionally or unintentionally) a key that points to an empty bucket, i.e. a bucket that still doesn’t have a value in it. In this case, the remove() method would return a false value.\n\n\n11.2.3 Iterating through the hashtable\nIterating through the keys and values that are currently being stored in the hashtable is a very common necessity. You can do that in Zig by using an iterator object that can iterate through the elements of your hashtable object.\nThis iterator object works like any other iterator object that you would find in languages such as C++ and Rust. It is basically a pointer object that points to some value in the container, and has a next() method that you can use to navigate (or iterate) through the values in the container.\nYou can create such iterator object by using the iterator() method of the hashtable object. This method returns an iterator object, from which you can use the next() method in conjunction with a while loop to iterate through the elements of your hashtable. The next() method returns an optional Entry value, and therefore, you must unwrap this optional value to get the actual Entry value from which you can access the key and also the value identified by this key.\nWith this Entry value at hand, you can access the key of this current entry by using the key_ptr attribute and dereferencing the pointer that lives inside of it, while the value identified by this key is accessed through the value_ptr attribute instead, which is also a pointer to be dereferenced. The code example below demonstrates the use of these elements:\n\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n\n    var it = hash_table.iterator();\n    while (it.next()) |kv| {\n        // Access the current key\n        std.debug.print(\"Key: {d} | \", .{kv.key_ptr.*});\n        // Access the current value\n        std.debug.print(\"Value: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n\nKey: 54321 | Value: 89Key: 50050 | Value: 55Key: 5\n  57709 | Value: 41\n\n\nKey: 54321 | Value: 89\nKey: 50050 | Value: 55\nKey: 57709 | Value: 41\nIf you want to iterate specifically through the values or the keys of your hashtable, you can create a key iterator or a value iterator object. These are also iterator objects, which have the same next() method that you can use to iterate through the hashtable.\nKey iterators are created from the keyIterator() method of your hashtable object, while value iterators are created from the valueIterator() method. All you have to do is to unwrap the value from the next() method and deference it directly to access the key or the value that you are iterating over. The code example below demonstrates the use of a key iterator, but you can replicate the same logic to a value iterator.\n\nvar kit = hash_table.keyIterator();\nwhile (kit.next()) |key| {\n    std.debug.print(\"Key: {d}\\n\", .{key.*});\n}\n\nKey: 54321\nKey: 50050\nKey: 57709\n\n\n11.2.4 The ArrayHashMap hashtable\nIf you need to iterate through the elements of your hashtable constantly, you might want to use the ArrayHashMap struct for your specific case, instead of going with the usual and general-purpose HashMap struct.\nThe ArrayHashMap struct creates a hashtable that is faster to iterate over. That is why this specific type of hashtable might be valuable to you. Some other properties of a ArrayHashMap hashtable are:\n\nthe order of insertion is preserved, i.e. the order of the values that you find while iterating through this hashtable is actually the order in which these values were inserted in the hashtable.\nthe key-value pairs are stored sequentially, one after another.\n\nYou can create an ArrayHashMap object by using, once again, a helper function that chooses automatically for you a hash function implementation. This is the AutoArrayHashMap() function, which works very similarly to the AutoHashMap() function that we presented at Section 11.2.2.\nYou provide two data types to this function. The data type of the keys that will be used in this hashtable, and the data type of the values that will be stored in this hashtable.\nAn ArrayHashMap object have essentially the exact same methods from the HashMap struct. So you can insert new values into the hashtable by using the put() method, and you can look (or get) a value from the hashtable by using the get() method. But the remove() method is not available in this specific type of hashtable.\nIn order to delete values from the hashtable, you would use the same methods that you find in an ArrayList object, i.e. a dynamic array. I presented these methods at Section 11.1.4, which are the swapRemove() and orderedRemove() methods. These methods have the same meaning here, or, the same effect that they have in an ArrayList object.\nThis means that, with swapRemove() you remove the value from the hashtable, but you do not preserve the order in which the values were inserted into the structure. While orderedRemove() is able to retain the order in which these values were inserted.\nBut instead of providing an index as input to swapRemove() or orderedRemove(), like I described at Section 11.1.4, these methods here in an ArrayHashMap take a key as input, like the remove() method from a HashMap object. If you want to provide an index as input, instead of a key, you should use the swapRemoveAt() and orderedRemoveAt() methods.\n\nvar hash_table = AutoArrayHashMap(u32, u16)\n    .init(allocator);\ndefer hash_table.deinit();\n\n\n\n11.2.5 The StringHashMap hashtable\nOne thing that you will notice in the other two types of hashtables that I have presented over the last sections, is that neither of them accepts a slice data type in their keys. What this means is that you cannot use a slice value to represent a key in these types of hashtable.\nThe most obvious consequence of this, is that you cannot use strings as keys in these hashtables. But it is extremely common to use strings as keys in hashtables.\nTake this very simple Javascript code snippet as an example. We are creating a simple hashtable object named people. Then, we add a new entry to this hashtable, which is identified by the string 'Pedro'. This string is the key in this case, while the object containing different personal information such as age, height and city, is the value to be stored in the hashtable.\nvar people = new Object();\npeople['Pedro'] = {\n    'age': 25,\n    'height': 1.67,\n    'city': 'Belo Horizonte'\n};\nThis pattern of using strings as keys is very common in all sorts of situations. That is why the Zig Standard Library offers a specific type of hashtable for this purpose, which is created through the StringHashMap() function. This function creates a hashtable that uses strings as keys. The only input of this function is the data type of the values that will be stored into this hashtable.\nIn the example below, I’m creating a hashtable to store the ages of different people. Each key in this hashtable is represented by the name of each person, while the value stored in the hashtable is the age of this person identified by the key.\nThat is why I provide the u8 data type (which is the data type used by the age values) as input to this StringHashMap() function. As the result, it creates a hashtable that uses string values as keys, and, that stores u8 values in it. Notice that an allocator object is provided at the init() method of the resulting object from the StringHashMap() function.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var ages = std.StringHashMap(u8).init(allocator);\n    defer ages.deinit();\n\n    try ages.put(\"Pedro\", 25);\n    try ages.put(\"Matheus\", 21);\n    try ages.put(\"Abgail\", 42);\n\n    var it = ages.iterator();\n    while (it.next()) |kv| {\n        std.debug.print(\"Key: {s} | \", .{kv.key_ptr.*});\n        std.debug.print(\"Age: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n\nKey: Pedro | Age: 25\nKey: Abgail | Age: 42\nKey: Matheus | Age: 21\n\n\n11.2.6 The StringArrayHashMap hashtable\nThe Zig Standard Library also provides a type of hashtable that mix the cons and pros of the StringHashMap and ArrayHashMap together. That is, a hashtable that uses strings as keys, but also have the advantages from ArrayHashMap. In other words, you can have a hashtable that is fast to iterate over, that preserves insertion order, and also, that uses strings as keys.\nYou can create such type of hashtable by using the StringArrayHashMap() function. This function accepts a data type as input, which is the data type of the values that are going to be stored inside this hashtable, in the same style as the function presented at Section 11.2.5.\nYou can insert new values into this hashtable by using the same put() method that we have discussed at Section 11.2.5. And you can also get values from the hashtable by using the same get() method. Like its ArrayHashMap brother, to delete values from this specific type of hashtable, we also use the orderedRemove() and swapRemove() methods, with the same effects that I have described at Section 11.2.4.\nIf we take the code example that was exposed at Section 11.2.5, we can achieve the exact same result with StringArrayHashMap():\n\nvar ages = std.StringArrayHashMap(u8).init(allocator);",
     "crumbs": [
       "<span class='chapter-number'>11</span>  <span class='chapter-title'>Data Structures</span>"
     ]
@@ -954,7 +954,7 @@
     "href": "Chapters/10-stack-project.html#sec-comptime",
     "title": "12  Project 3 - Building a stack data structure",
     "section": "",
-    "text": "apply comptime on a function argument.\napply comptime on an object.\napply comptime on a block of expressions.\n\n\n12.1.1 Applying over a function argument\nWhen you apply the comptime keyword on a function argument, you are saying to the zig compiler that the value assigned to that particular function argument must be known at compile-time. We explained in details at Section 3.1.1 what exactly “value known at compile-time” means, so, in case you have doubts about this idea, come back to that section.\nNow let’s think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement to that particular function argument. If the programmer accidentally tries to give a value to this function argument that is not known at compile time, the zig compiler will notice this problem, and as a consequence, it will raise a compilation error saying that it cannot compile your program. Because you are providing a value that is “runtime known” to a function argument that must be “compile-time known”.\nTake a look at this very simple example below, where we define a twice() function, that simply doubles the input value named num. Notice that we use the comptime keyword before the name of the function argument. This keyword is marking the function argument num as a “comptime argument”.\nThat is a function argument whose value must be compile-time known. This is why the expression twice(5678) is valid, and no compilation errors are raised. Because the value 5678 is compile-time known, so this is the expected behaviour for this function.\n\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n\nBut what if we provide a number that is not compile-time known to this function? For example, we might provide a different input value to this function depending on the target OS of our compilation process. The code example below demonstrates such case.\nBecause the value of the object n is determined at runtime, we cannot provide this object as input to the twice() function. The zig compiler will not allow it, because we marked the num argument as a “comptime argument”. That is why the zig compiler raises the compile-time error exposed below:\n\nconst builtin = @import(\"builtin\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    var n: u32 = undefined;\n    if (builtin.target.os.tag == .windows) {\n        n = 1234;\n    } else {\n        n = 5678;\n    }\n    _ = twice(n);\n}\n\nt.zig:12:16: error: runtime-known argument passed to comptime parameter \nComptime arguments are frequently used on functions that return some sort of generic structure. In fact, comptime is the essence (or the basis) to make generics in Zig. We are going to talk more about generics at Section 12.2.\nFor now, let’s take a look at this code example from Seguin (2024). You can see that this IntArray() function have one argument named length. This argument is marked as comptime, and receives a value of type usize as input. So the value given to this argument must be compile-time known. We can also see that this function returns an array of i64 values as output.\n\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n\nNow, the key component of this function is the length argument. This argument is used to determine the size of the array that is produced by the function. Let’s think about the consequences of that. If the size of the array is dependent on the value assigned to the length argument, this means that the data type of the output of the function depends on the value of this length argument.\nLet this statement sink for a bit in your mind. As I described at Section 1.2.2, Zig is a strongly-typed language, especially on function declarations. So every time we write a function in Zig, we have to annotate the data type of the value returned by the function. But how can we do that, if this data type depends on the value given to the argument of the function?\nThink about this for a second. If length is equal to 3 for example, then, the return type of the function is [3]i64. But if length is equal to 40, then, the return type becomes [40]i64. At this point the zig compiler would be confused, and raise a compilation error, saying something like this:\n\nHey! You have annotated that this function should return a [3]i64 value, but I got a [40]i64 value instead! This doesn’t look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when the type keyword comes in. This type keyword is basically saying to the zig compiler that this function will return some data type as output, but it doesn’t know yet what exactly data type that is. We will talk more about this at Section 12.2.\n\n\n12.1.2 Applying over an expression\nWhen you apply the comptime keyword over an expression, then, it is guaranteed that the zig compiler will execute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time (e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the zig compiler will raise a compilation error.\nTake this example from the official documentation of Zig (Zig Software Foundation 2024). We are executing the same fibonacci() function both at runtime, and, at compile-time. The function is by default executed at runtime, but because we use the comptime keyword at the second “try expression”, this expression is executed at compile-time.\nThis might be a bit confusing for some people. Yes! When I say that this expression is executed at compile-time, I mean that this expression is compiled and executed while the zig compiler is compiling your Zig source code.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n\nA lot of your Zig source code might be potentially executed at compile-time, because the zig compiler can figure it out the output of some expressions. Especially if these expressions depends only at compile-time known values. We have talked about this at Section 3.1.1.\nBut when you use the comptime keyword on an expression, there is no “it might be executed at compile-time” anymore. With the comptime keyword you are ordering the zig compiler to execute this expression at compile-time. You are imposing this rule, it is guaranteed that the compiler will always execute it at compile-time. Or, at least, the compiler will try to execute it. If the compiler cannot execute the expression for whatever reason, the compiler will raise a compilation error.\n\n\n12.1.3 Applying over a block\nBlocks were described at Section 1.7. When you apply the comptime keyword over a block of expressions, you get essentially the same effect when you apply this keyword to a single expression. That is, the entire block of expressions is executed at compile-time by the zig compiler.\nIn the example below, we mark the block labeled of blk as a comptime block, and, therefore, the expressions inside this block are executed at compile-time.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}",
+    "text": "apply comptime on a function argument.\napply comptime on an object.\napply comptime on a block of expressions.\n\n\n12.1.1 Applying over a function argument\nWhen you apply the comptime keyword on a function argument, you are saying to the zig compiler that the value assigned to that particular function argument must be known at compile-time. We explained in details at Section 3.1.1 what exactly “value known at compile-time” means, so, in case you have doubts about this idea, come back to that section.\nNow let’s think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement to that particular function argument. If the programmer accidentally tries to give a value to this function argument that is not known at compile time, the zig compiler will notice this problem, and as a consequence, it will raise a compilation error saying that it cannot compile your program. Because you are providing a value that is “runtime known” to a function argument that must be “compile-time known”.\nTake a look at this very simple example below, where we define a twice() function, that simply doubles the input value named num. Notice that we use the comptime keyword before the name of the function argument. This keyword is marking the function argument num as a “comptime argument”.\nThat is a function argument whose value must be compile-time known. This is why the expression twice(5678) is valid, and no compilation errors are raised. Because the value 5678 is compile-time known, so this is the expected behaviour for this function.\n\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n\n1/1 file1054863994c6f.test.test comptime...OKAll 1\n  1 tests passed.\n\n\nBut what if we provide a number that is not compile-time known to this function? For example, we might provide a different input value to this function depending on the target OS of our compilation process. The code example below demonstrates such case.\nBecause the value of the object n is determined at runtime, we cannot provide this object as input to the twice() function. The zig compiler will not allow it, because we marked the num argument as a “comptime argument”. That is why the zig compiler raises the compile-time error exposed below:\n\nconst builtin = @import(\"builtin\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    var n: u32 = undefined;\n    if (builtin.target.os.tag == .windows) {\n        n = 1234;\n    } else {\n        n = 5678;\n    }\n    _ = twice(n);\n}\n\nt.zig:12:16: error: runtime-known argument passed to comptime parameter \nComptime arguments are frequently used on functions that return some sort of generic structure. In fact, comptime is the essence (or the basis) to make generics in Zig. We are going to talk more about generics at Section 12.2.\nFor now, let’s take a look at this code example from Seguin (2024). You can see that this IntArray() function have one argument named length. This argument is marked as comptime, and receives a value of type usize as input. So the value given to this argument must be compile-time known. We can also see that this function returns an array of i64 values as output.\n\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n\nNow, the key component of this function is the length argument. This argument is used to determine the size of the array that is produced by the function. Let’s think about the consequences of that. If the size of the array is dependent on the value assigned to the length argument, this means that the data type of the output of the function depends on the value of this length argument.\nLet this statement sink for a bit in your mind. As I described at Section 1.2.2, Zig is a strongly-typed language, especially on function declarations. So every time we write a function in Zig, we have to annotate the data type of the value returned by the function. But how can we do that, if this data type depends on the value given to the argument of the function?\nThink about this for a second. If length is equal to 3 for example, then, the return type of the function is [3]i64. But if length is equal to 40, then, the return type becomes [40]i64. At this point the zig compiler would be confused, and raise a compilation error, saying something like this:\n\nHey! You have annotated that this function should return a [3]i64 value, but I got a [40]i64 value instead! This doesn’t look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when the type keyword comes in. This type keyword is basically saying to the zig compiler that this function will return some data type as output, but it doesn’t know yet what exactly data type that is. We will talk more about this at Section 12.2.\n\n\n12.1.2 Applying over an expression\nWhen you apply the comptime keyword over an expression, then, it is guaranteed that the zig compiler will execute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time (e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the zig compiler will raise a compilation error.\nTake this example from the official documentation of Zig (Zig Software Foundation 2024). We are executing the same fibonacci() function both at runtime, and, at compile-time. The function is by default executed at runtime, but because we use the comptime keyword at the second “try expression”, this expression is executed at compile-time.\nThis might be a bit confusing for some people. Yes! When I say that this expression is executed at compile-time, I mean that this expression is compiled and executed while the zig compiler is compiling your Zig source code.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n\n1/1 file10548bb87337.test.fibonacci...OKAll 1 test\n  ts passed.\n\n\nA lot of your Zig source code might be potentially executed at compile-time, because the zig compiler can figure it out the output of some expressions. Especially if these expressions depends only at compile-time known values. We have talked about this at Section 3.1.1.\nBut when you use the comptime keyword on an expression, there is no “it might be executed at compile-time” anymore. With the comptime keyword you are ordering the zig compiler to execute this expression at compile-time. You are imposing this rule, it is guaranteed that the compiler will always execute it at compile-time. Or, at least, the compiler will try to execute it. If the compiler cannot execute the expression for whatever reason, the compiler will raise a compilation error.\n\n\n12.1.3 Applying over a block\nBlocks were described at Section 1.7. When you apply the comptime keyword over a block of expressions, you get essentially the same effect when you apply this keyword to a single expression. That is, the entire block of expressions is executed at compile-time by the zig compiler.\nIn the example below, we mark the block labeled of blk as a comptime block, and, therefore, the expressions inside this block are executed at compile-time.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n\n1/1 file105482dc0b880.test.fibonacci in a block...\n  .OKAll 1 tests passed.",
     "crumbs": [
       "<span class='chapter-number'>12</span>  <span class='chapter-title'>Project 3 - Building a stack data structure</span>"
     ]
@@ -964,7 +964,7 @@
     "href": "Chapters/10-stack-project.html#sec-generics",
     "title": "12  Project 3 - Building a stack data structure",
     "section": "12.2 Introducing Generics",
-    "text": "12.2 Introducing Generics\nFirst of all, what is a generic? Generic is the idea to allow a type (f64, u8, u32, bool, and also, user-defined types, like the User struct that we defined at Section 2.3) to be a parameter to methods, classes and interfaces (Geeks for Geeks 2024). In other words, a “generic” is a class (or a method) that can work with multiple data types.\nFor example, in Java, generics are created through the operator &lt;&gt;. With this operator, a Java class is capable of receiving a data type as input, and therefore, the class can fit its features according to this input data type. As another example, generics in C++ are supported through the concept of templates. Class templates in C++ are generics.\nIn Zig, generics are implemented through comptime. The comptime keyword allows us to collect a data type at compile time, and pass this data type as input to a piece of code.\n\n12.2.1 A generic function\nTake the max() function exposed below as a first example. This function is essentially a “generic function”. In this function, we have a comptime function argument named T. Notice that this T argument have a data type of type. Weird right? This type keyword is the “father of all types”, or, “the type of types” in Zig.\nBecause we have used this type keyword in the T argument, we are telling the zig compiler that this T argument will receive some data type as input. Also notice the use of the comptime keyword in this argument. As I described at Section 12.1, every time you use this keyword in a function argument, this means that the value of this argument must be known at compile-time. This makes sense, right? Because there is no data type that is not known at compile-time.\nThink about this. Every data type that you will ever write is always known at compile-time. Especially because data types are an essential information for the compiler to actually compile your source code. Having this in mind, makes sense to mark this argument as a comptime argument.\n\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a &gt; b) a else b;\n}\n\nAlso notice that the value of the T argument is actually used to define the data type of the other arguments in the function, a and b, and also at the return type annotation of the function. That is, the data type of these arguments (a and b), and, the return data type of the function itself, are determined by the input value given to the T argument.\nAs a result, we have a generic function that works with different data types. For example, I can provide u8 values to this max() function, and it will work as expected. But if I provide f64 values instead, it will also work as expected. Without a generic function, I would have to write a different max() function for each one of the data types that I wanted to use. This generic function provides a very useful shortcut for us.\n\nconst std = @import(\"std\");\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a &gt; b) a else b;\n}\ntest \"test max\" {\n    const n1 = max(u8, 4, 10);\n    std.debug.print(\"Max n1: {d}\\n\", .{n1});\n    const n2 = max(f64, 89.24, 64.001);\n    std.debug.print(\"Max n2: {d}\\n\", .{n2});\n}\n\nMax n1: 10\nMax n2: 89.24\n\n\n12.2.2 A generic data structure\nEvery data structure that you find in the Zig Standard Library (e.g. ArrayList, HashMap, etc.) is essentially a generic data structure. These data structures are generic in the sense that they work with any data type you want. You just say which is the data type of the values that are going to be stored in this data structure, and they just work as expected.\nA generic data structure in Zig is how you replicate a generic class from Java, or, a class template from C++. But you may quest yourself: how do we build a generic data structure in Zig?\nThe basic idea is to write a generic function that creates the data structure definition for the specific type we want. In other words, this generic function behaves as a “factory of data structures”. The generic function outputs the struct definition that defines this data structure for a specific data type.\nTo create such function, we need to add a comptime argument to this function that receives a data type as input. We already learned how to do this at the previous section (Section 12.2.1). I think the best way to demonstrate how to create a generic data structure is to actually write one. This where we go into our next small project in this book. This one is a very small project, which is to write a generic stack data structure.",
+    "text": "12.2 Introducing Generics\nFirst of all, what is a generic? Generic is the idea to allow a type (f64, u8, u32, bool, and also, user-defined types, like the User struct that we defined at Section 2.3) to be a parameter to methods, classes and interfaces (Geeks for Geeks 2024). In other words, a “generic” is a class (or a method) that can work with multiple data types.\nFor example, in Java, generics are created through the operator &lt;&gt;. With this operator, a Java class is capable of receiving a data type as input, and therefore, the class can fit its features according to this input data type. As another example, generics in C++ are supported through the concept of templates. Class templates in C++ are generics.\nIn Zig, generics are implemented through comptime. The comptime keyword allows us to collect a data type at compile time, and pass this data type as input to a piece of code.\n\n12.2.1 A generic function\nTake the max() function exposed below as a first example. This function is essentially a “generic function”. In this function, we have a comptime function argument named T. Notice that this T argument have a data type of type. Weird right? This type keyword is the “father of all types”, or, “the type of types” in Zig.\nBecause we have used this type keyword in the T argument, we are telling the zig compiler that this T argument will receive some data type as input. Also notice the use of the comptime keyword in this argument. As I described at Section 12.1, every time you use this keyword in a function argument, this means that the value of this argument must be known at compile-time. This makes sense, right? Because there is no data type that is not known at compile-time.\nThink about this. Every data type that you will ever write is always known at compile-time. Especially because data types are an essential information for the compiler to actually compile your source code. Having this in mind, makes sense to mark this argument as a comptime argument.\n\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a &gt; b) a else b;\n}\n\nAll 0 tests passed.\n\n\nAlso notice that the value of the T argument is actually used to define the data type of the other arguments in the function, a and b, and also at the return type annotation of the function. That is, the data type of these arguments (a and b), and, the return data type of the function itself, are determined by the input value given to the T argument.\nAs a result, we have a generic function that works with different data types. For example, I can provide u8 values to this max() function, and it will work as expected. But if I provide f64 values instead, it will also work as expected. Without a generic function, I would have to write a different max() function for each one of the data types that I wanted to use. This generic function provides a very useful shortcut for us.\n\nconst std = @import(\"std\");\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a &gt; b) a else b;\n}\ntest \"test max\" {\n    const n1 = max(u8, 4, 10);\n    std.debug.print(\"Max n1: {d}\\n\", .{n1});\n    const n2 = max(f64, 89.24, 64.001);\n    std.debug.print(\"Max n2: {d}\\n\", .{n2});\n}\n\n1/1 file105482071daf3.test.test max...Max n1: 10Ma\n  ax n2: 89.24OKAll 1 tests passed.\n\n\nMax n1: 10\nMax n2: 89.24\n\n\n12.2.2 A generic data structure\nEvery data structure that you find in the Zig Standard Library (e.g. ArrayList, HashMap, etc.) is essentially a generic data structure. These data structures are generic in the sense that they work with any data type you want. You just say which is the data type of the values that are going to be stored in this data structure, and they just work as expected.\nA generic data structure in Zig is how you replicate a generic class from Java, or, a class template from C++. But you may quest yourself: how do we build a generic data structure in Zig?\nThe basic idea is to write a generic function that creates the data structure definition for the specific type we want. In other words, this generic function behaves as a “factory of data structures”. The generic function outputs the struct definition that defines this data structure for a specific data type.\nTo create such function, we need to add a comptime argument to this function that receives a data type as input. We already learned how to do this at the previous section (Section 12.2.1). I think the best way to demonstrate how to create a generic data structure is to actually write one. This where we go into our next small project in this book. This one is a very small project, which is to write a generic stack data structure.",
     "crumbs": [
       "<span class='chapter-number'>12</span>  <span class='chapter-title'>Project 3 - Building a stack data structure</span>"
     ]
@@ -1244,7 +1244,7 @@
     "href": "Chapters/13-image-filter.html#applying-the-image-filter",
     "title": "15  Project 4 - Developing an image filter",
     "section": "15.5 Applying the image filter",
-    "text": "15.5 Applying the image filter\nNow that we have the data of each pixel in the image, we can focus on applying our image filter over these pixels. Remember, our objective here is to apply a grayscale filter over the image. A grayscale filter is a filter that transforms a colored image into a grayscale image.\nThere are different formulas and strategies to transform a colored image into a grayscale image. But all of these different strategies normally involve applying some math over the colors of each pixel. In this project, we are going to use the most general formula, which is exposed below. This formula considers \\(r\\) as the red of the pixel, \\(g\\) as the green, \\(b\\) as the blue, and \\(p'\\) as the linear luminance of the pixel.\n\\[\n    p' = (0.2126 \\times r) + (0.7152 \\times g) + (0.0722 \\times b)\n\\tag{15.1}\\]\nThis Equation 15.1 is the formula to calculate the linear luminance of a pixel. Is worth noting that this formula works only for images whose pixels are using the sRGB color space, which is the standard color space for the web. Thus, ideally, all images on the web should use this color space. Luckily, this is our case here, i.e. the pedro_pascal.png image is using this sRGB color space, and, as consequence, we can use the Equation 15.1. You can read more about this formula at the Wikipedia page for grayscale (Wikipedia 2024).\nThe apply_image_filter() function exposed below summarises the necessary steps to apply Equation 15.1 over the pixels in the image. We just apply this function over our buffer object that contains our pixel data, and, as result, the pixel data stored in this buffer object should now represent the grayscale version of our image.\n\nfn apply_image_filter(buffer:[]u8) !void {\n    const len = buffer.len;\n    const red_factor: f16 = 0.2126;\n    const green_factor: f16 = 0.7152;\n    const blue_factor: f16 = 0.0722;\n    var index: u64 = 0;\n    while (index &lt; (len - 4)) : (index += 4) {\n        const rf: f16 = @floatFromInt(buffer[index]);\n        const gf: f16 = @floatFromInt(buffer[index + 1]);\n        const bf: f16 = @floatFromInt(buffer[index + 2]);\n        const y_linear: f16 = (\n            (rf * red_factor) + (gf * green_factor)\n            + (bf * blue_factor)\n        );\n        buffer[index] = @intFromFloat(y_linear);\n        buffer[index + 1] = @intFromFloat(y_linear);\n        buffer[index + 2] = @intFromFloat(y_linear);\n    }\n}\n\ntry apply_image_filter(buffer[0..]);",
+    "text": "15.5 Applying the image filter\nNow that we have the data of each pixel in the image, we can focus on applying our image filter over these pixels. Remember, our objective here is to apply a grayscale filter over the image. A grayscale filter is a filter that transforms a colored image into a grayscale image.\nThere are different formulas and strategies to transform a colored image into a grayscale image. But all of these different strategies normally involve applying some math over the colors of each pixel. In this project, we are going to use the most general formula, which is exposed below. This formula considers \\(r\\) as the red of the pixel, \\(g\\) as the green, \\(b\\) as the blue, and \\(p'\\) as the linear luminance of the pixel.\n\\[\n    p' = (0.2126 \\times r) + (0.7152 \\times g) + (0.0722 \\times b)\n\\tag{15.1}\\]\nThis Equation 15.1 is the formula to calculate the linear luminance of a pixel. Is worth noting that this formula works only for images whose pixels are using the sRGB color space, which is the standard color space for the web. Thus, ideally, all images on the web should use this color space. Luckily, this is our case here, i.e. the pedro_pascal.png image is using this sRGB color space, and, as consequence, we can use the Equation 15.1. You can read more about this formula at the Wikipedia page for grayscale (Wikipedia 2024).\nThe apply_image_filter() function exposed below summarises the necessary steps to apply Equation 15.1 over the pixels in the image. We just apply this function over our buffer object that contains our pixel data, and, as result, the pixel data stored in this buffer object should now represent the grayscale version of our image.\n\nfn apply_image_filter(buffer:[]u8) !void {\n    const len = buffer.len;\n    const red_factor: f16 = 0.2126;\n    const green_factor: f16 = 0.7152;\n    const blue_factor: f16 = 0.0722;\n    var index: u64 = 0;\n    while (index &lt;= (len - 4)) : (index += 4) {\n        const rf: f16 = @floatFromInt(buffer[index]);\n        const gf: f16 = @floatFromInt(buffer[index + 1]);\n        const bf: f16 = @floatFromInt(buffer[index + 2]);\n        const y_linear: f16 = (\n            (rf * red_factor) + (gf * green_factor)\n            + (bf * blue_factor)\n        );\n        buffer[index] = @intFromFloat(y_linear);\n        buffer[index + 1] = @intFromFloat(y_linear);\n        buffer[index + 2] = @intFromFloat(y_linear);\n    }\n}\n\ntry apply_image_filter(buffer[0..]);",
     "crumbs": [
       "<span class='chapter-number'>15</span>  <span class='chapter-title'>Project 4 - Developing an image filter</span>"
     ]
diff --git a/zig_engine.R b/zig_engine.R
index 17ee7e09..d3831fc5 100644
--- a/zig_engine.R
+++ b/zig_engine.R
@@ -2,23 +2,26 @@ library(knitr)
 library(readr)
 library(stringr)
 
-find_in_path_ <- function() {
-  cat("[INFO]: Zig not found through `which`. Trying to find it through PATH...\n", file = stderr())
-  path <- Sys.getenv("PATH")
-  path_dirs <- str_split_1(path, ":")
-  for (dir in path_dirs) {
-    execs <- fs::dir_ls(dir, type = "file")
-    zig_found <- str_detect(execs, "/zig$")
-    if (any(zig_found)) {
-      message <- sprintf("Zig found at %s\n", execs[zig_found])
-      cat(message, file = stderr())
-      return(as.character(execs[zig_found]))
-    }
-  }
-  
-  return(NULL)
-}
-
+#' Find path to the Zig compiler in the current machine.
+#'
+#' This function is used to find the full path to the Zig compiler
+#' installed in the current machine that is trying to build the book.
+#'
+#' A search process is performed in two stages over the current machine
+#' to find the Zig compiler. First, the function tries to find the compiler
+#' by using the R inferface to the command-line `which` command.
+#'
+#' If the compiler is not found in the first stage, then, the function
+#' tries a new strategy in the second stage. In this stage, the function
+#' iterates through the directories listed in the `PATH` environment
+#' variable, and tries to find the Zig compiler in one of these directories.
+#' This strategy is much slower, but it is more garanteed to work.
+#'
+#' If the compiler is found, the function returns a string with the full path to the compiler.
+#' If the function does not find the Zig compiler in any of the two stages,
+#' an runtime error is raised by the R process.
+#'
+#' @return A string with the full path to the compiler installed in the current machine.
 find_zig_ <- function() {
   possible_paths <- c(
     "/mnt/c/Users/pedro/Documents/_Programs/zig-linux/zig",
@@ -31,7 +34,7 @@ find_zig_ <- function() {
       return(path)
     }
   }
-  
+
   path <- find_in_path_()
   if (is.null(path)) {
     stop("[ERROR]: Unable to find the zig compiler in your computer!")
@@ -40,14 +43,54 @@ find_zig_ <- function() {
 }
 
 
+find_in_path_ <- function() {
+  cat("[INFO]: Zig not found through `which`. Trying to find it through PATH...\n", file = stderr())
+  path <- Sys.getenv("PATH")
+  path_dirs <- str_split_1(path, ":")
+  for (dir in path_dirs) {
+    execs <- fs::dir_ls(dir, type = "file")
+    zig_found <- str_detect(execs, "/zig$")
+    if (any(zig_found)) {
+      message <- sprintf("Zig found at %s\n", execs[zig_found])
+      cat(message, file = stderr())
+      return(as.character(execs[zig_found]))
+    }
+  }
+
+  return(NULL)
+}
+
+
+# The full path to the Zig compiler is registered in the R process
+# inside the global option `zig_exe_path`. And you can retrieve the
+# value registered in this option with `getOption("zig_exe_path")`.
 options(zig_exe_path = find_zig_())
 options(width = 50)
 
 
 
 
-str_split_lines <- function(text, options) {
-  output_width <- getOption("width")
+#' Format Zig output.
+#'
+#' This function is used to format the output produced by the Zig
+#' code that was compiled and executed by the Zig compiler. More
+#' specifically, this function is used specially when the output
+#' is very long.
+#'
+#' If the output is very long, this can be cubersome and hard to
+#' follow/read in the book. Good strategies to deal with this problem
+#' are: 1) to split the output into multiple lines if it is too long;
+#' 2) or to truncate the output until a certain limit.
+#'
+#' This function performs one of these strategies depending on the
+#' width of the output, and the options that were setted/configured
+#' in the current code block.
+#'
+#' @param text The output to be formatted.
+#' @param options The list of code block options.
+#'
+#' @return A string containing the formatted output.
+format_output <- function(text, options) {
   if (length(text) == 0) {
     return(text)
   }
@@ -55,6 +98,7 @@ str_split_lines <- function(text, options) {
     text <- str_flatten(text, collapse = "")
   }
 
+  output_width <- getOption("width")
   n_chars <- str_length(text)
   if (n_chars <= output_width) {
     return(text)
@@ -82,105 +126,100 @@ str_split_lines <- function(text, options) {
   return(str_flatten(lines))
 }
 
-extract_delim_type <- function(lines) {
-  regex <- "^// (={4,}) ?([a-zA-Z]+)"
-  group_name <- str_extract(lines, regex, group = 2)
-  group_name <- group_name[!is.na(group_name)]
-  return(str_to_lower(group_name))
-}
-
-extract_delim_lines <- function(lines) {
-  regex <- "^// (={4,}) ?([a-zA-Z]+)"
-  line_index <- str_which(lines, regex)
-  return(line_index)
-}
-
-split_functions_from_var <- function(code) {
-  regex <- "^// (={4,})"
-  lines <- unlist(str_split(code, "\n"))
-  group_name <- extract_delim_type(lines)
-  delim_lines <- extract_delim_lines(lines)
-  results <- list(
-    vars = "",
-    structs = "",
-    funs = ""
-  )
-  if (length(delim_lines) == 0) {
-    results$vars <- code
-    return(results)
-  }
-
-  if (length(group_name) != length(delim_lines)) {
-    stop("Problem when generating auto main! Length of grouping names is different than the length of grouping indexes.")
-  }
-
-  last_index <- length(lines)
-  for (i in rev(seq_along(group_name))) {
-    type <- group_name[i]
-    index <- delim_lines[i]
-    lines_to_separate <- lines[index:last_index]
-    last_index <- index - 1L
-    if (str_detect(type, "struct")) {
-      results$structs <- str_c(lines_to_separate, collapse = "\n")
-    }
-    if (str_detect(type, "function")) {
-      results$funs <- str_c(lines_to_separate, collapse = "\n")
-    }
-    if (str_detect(type, "variable")) {
-      results$vars <- str_c(lines_to_separate, collapse = "\n")
-    }
-  }
-
-  return(results)
-}
-
-
 
 
+#' Auto generate main function.
+#'
+#' You provide some Zig code as input, and this function
+#' auto-generates a `main()` Zig function that encapsulates
+#' the input Zig code.
+#'
+#' This function is used when a code block in the book source code
+#' is marked with the `auto_main: true` option.
+#'
+#' @param code_without_main A string containing some Zig code to be
+#'     encapsulated inside a `main()` function.
+#' @return A string containing a `main()` function that encapsulates the
+#'     input Zig code.
 generate_main <- function(code_without_main) {
-  code_without_main <- split_functions_from_var(
-    code_without_main
-  )
+  code_without_main <- increase_indentation__(code_without_main)
   main_fmt <- c(
     "const std = @import(\"std\");\n",
     "const stdout = std.io.getStdOut().writer();\n",
     "pub fn main() !void {\n",
     "%s",
-    "\n}\n",
-    "\n%s\n",
-    "\n%s\n"
+    "\n}\n"
   )
-  main_fmt <- paste(main_fmt, sep = "", collapse = "\n")
+  main_fmt <- str_flatten(main_fmt, collapse = "\n")
   code_with_main <- sprintf(
     main_fmt,
-    code_without_main$vars,
-    code_without_main$structs,
-    code_without_main$funs
+    code_without_main
   )
   return(code_with_main)
 }
 
+increase_indentation__ <- function(code_without_main) {
+  lines <- unlist(str_split(code_without_main, "\n"))
+  for (i in seq_along(lines)) {
+    lines[i] <- str_flatten(c("    ", lines[i]))
+  }
 
-remove_delim_lines <- function(code) {
-  regex <- "^// (={4,})"
-  lines <- unlist(str_split(code, "\n"))
-  delim_lines <- str_which(lines, regex)
-  lines[delim_lines] <- ""
-  code_fixed <- str_c(lines, collapse = "\n")
-  return(str_trim(code_fixed))
+  return(str_c(lines, collapse = "\n", sep = ""))
 }
 
 
+#' Get `auto_main` option.
+#'
+#' This function is used to get the value of the `auto_main` code block option.
+#' The `auto_main` code block option is used to specify if the Zig code written
+#' in the current code block should (or should not) be encapsulated inside a
+#' `main()` function, before it get's sent to the Zig compiler to be compiled.
+#'
+#' If the user did not configured/setted this
+#' specific option in the current code block that is being analyzed,
+#' then, this function will automatically return `FALSE` by default.
+#' However, if the user did setted this option in the current code block,
+#' then, the function returns the value that the user provided in this option.
+#'
+#' @param options The list of code block options.
+#'
+#' @return A boolean value, indicating if the Zig code in the current code block
+#'     should (or should not) be encapsulated inside a `main()` function.
 get_auto_main <- function(options) {
-  if (length(options$auto_main) == 0L) {
+  if (length(options$auto_main) == 0 || is.null(options$auto_main)) {
     return(FALSE)
   }
 
   return(options$auto_main)
 }
 
+
+
+#' Get `build_type` option.
+#'
+#' This function is used to get the value of the `build_type` code block option.
+#' The `build_type` code block option is used to specify which command from the
+#' Zig compiler should be used to compile the Zig code that is written in the current
+#' code block.
+#'
+#' Possible values for this option are:
+#' - `"run"`: use `zig run` to compile and execute the Zig code.
+#' - `"lib"`: use `zig build-lib` to compile the Zig code.
+#' - `"test"`: use `zig test` to compile and execute the Zig code.
+#' - `"ast"`: use `zig ast-check` to check for syntax errors.
+#'
+#' If the user did not configured/setted this
+#' specific option in the current code block that is being analyzed,
+#' then, this function will automatically return `"run"` by default.
+#' However, if the user did setted this option in the current code block,
+#' then, the function returns the value that the user provided in this option.
+#'
+#' @param options The list of code block options.
+#'
+#' @return A string value, indicating which command from the Zig compiler should be
+#'     used to compile the Zig code that is written in the current code block.
 get_build_type <- function(options) {
-  if (length(options$build_type) == 0L) {
+  if (length(options$build_type) == 0 || is.null(options$build_type)) {
     return("run")
   }
 
@@ -189,58 +228,261 @@ get_build_type <- function(options) {
 
 
 
-knitr::knit_engines$set(zig = function(options) {
-  code <- paste(options$code, collapse = "\n")
+#' Zig knitr engine.
+#'
+#' This function is the engine responsible for processing, compiling and executing
+#' every single Zig code written in a code block across the book.
+#'
+#' @param options The list of code block options.
+#'
+#' @return The knitr engine output, which contains the output of the Zig code
+#'     (i.e. the output of the executable compiled from this Zig code).
+zig_engine <- function(options) {
+  code <- str_flatten(options$code, "\n")
   if (!options$eval) {
     return(knitr::engine_output(options, code, NULL))
   }
 
-  auto_main <- get_auto_main(options)
-  if (auto_main) {
-    code_to_execute <- generate_main(code)
-  } else {
-    code_to_execute <- code
-  }
-
   build_type <- get_build_type(options)
   if (build_type == "test") {
-    cmd_name <- "test"
+    output <- zig_test(code, options)
   } else if (build_type == "lib") {
-    cmd_name <- "build-lib"
+    output <- zig_build_lib(code, options)
+  } else if (build_type == "run") {
+    output <- zig_run(code, options)
+  } else if (build_type == "ast") {
+    zig_ast_check(code, options)
+    output <- NULL
   } else {
-    cmd_name <- "run"
+    msg <- sprintf("[ERROR]: Unsuported build type %s!", build_type)
+    stop(msg)
   }
 
+  output <- format_output(output, options)
+  return(knitr::engine_output(options, code, output))
+}
+
+
+
+#' Write a Zig file.
+#'
+#' This function is used to save/write some Zig source code
+#' into a Zig file (`*.zig`). More specifically, the input Zig source code
+#' is written into a temporary file into the operating system.
+#' In Windows for example, a temporary file is usually a file written
+#' inside the `AppData` system folder.
+#'
+#' When you restart the system all temporary files are automatically
+#' erased. This is why they are "temporary".
+#'
+#' @param zig_code The Zig source code to be written into the Zig file.
+#'
+#' @return A string with the full path to the temporary Zig file.
+write_zig <- function(zig_code) {
   temp_file <- tempfile(fileext = ".zig")
-  readr::write_file(code_to_execute, temp_file)
+  readr::write_file(zig_code, temp_file)
+  return(temp_file)
+}
+
+
+
+#' Compile and execute Zig code.
+#'
+#' This function is used only if the code block option `build_type` is equal to `"run"`.
+#' This function receives some Zig source code as input, and then, it writes this source code to
+#' a Zig file (`*.zig`), then, it compiles and executes this Zig file using the
+#' `zig run` command from the Zig compiler.
+#'
+#' @param zig_code The zig source code to be compiled.
+#' @param options The list of code block options.
+#'
+#' @return The knitr engine output, which contains the output of the Zig code
+#'     (i.e. the output of the executable compiled from this Zig code).
+zig_run <- function(zig_code, options) {
+  if (get_auto_main(options)) {
+    zig_code <- generate_main(zig_code)
+  }
+
+  file_path <- write_zig(zig_code)
+  output <- zig_compile_file(file_path, "run")
+  fs::file_delete(file_path)
+  return(output)
+}
+
+
+#' Compile Zig code as a static library.
+#'
+#' This function is used only if the code block option `build_type` is equal to `"lib"`.
+#' This function receives some Zig source code as input, and then, it writes this source code to
+#' a Zig file (`*.zig`), then, it compiles this Zig file using the
+#' `zig build-lib` command from the Zig compiler.
+#'
+#' @param zig_code The zig source code to be compiled.
+#' @param options The list of code block options.
+#'
+#' @return The knitr engine output. This engine output usually does not contain any sort
+#'     of output from the input Zig code per se, because the Zig code was compiled as a static library.
+#'     To really execute the code from this static library, we would need to create an executable
+#'     that links to this static library.
+zig_build_lib <- function(zig_code, options) {
+  if (get_auto_main(options)) {
+    zig_code <- generate_main(zig_code)
+  }
+
+  file_path <- write_zig(zig_code)
+  output <- zig_compile_file(file_path, "build-lib")
+  clean_lib_files()
+  fs::file_delete(file_path)
+  return(output)
+}
+
+
+#' Compile Zig code as a tests executable.
+#'
+#' This function is used only if the code block option `build_type` is equal to `"test"`.
+#' This function receives some Zig source code as input, and then, it writes this source code to
+#' a Zig file (`*.zig`), then, it compiles this Zig file using the
+#' `zig test` command from the Zig compiler.
+#'
+#' @param zig_code The zig source code to be compiled.
+#' @param options The list of code block options.
+#'
+#' @return The knitr engine output, which contains the output of the Zig code
+#'     (i.e. the output of the executable compiled from this Zig code).
+zig_test <- function(zig_code, options) {
+  file_path <- write_zig(zig_code)
+  output <- zig_compile_file(file_path, "test")
+  fs::file_delete(file_path)
+  return(output)
+}
+
+
+
+#' Check syntax of Zig code with ast-check.
+#'
+#' This function is normally used only on code blocks that are not evaluated
+#' (i.e. `eval: false`). This function receives some Zig source code as input,
+#' and then, it writes this source code to a Zig file (`*.zig`), then, it checks
+#' if the syntax of the source code in this file is correct, by using the
+#' `zig ast-check` command
+#'
+#' @param zig_code The zig source code to be checked.
+#' @param options The list of code block options.
+#'
+#' @return The knitr engine output, which contains the output of the Zig code
+#'     (i.e. the output of the executable compiled from this Zig code).
+zig_ast_check <- function(zig_code, options) {
+  if (get_auto_main(options)) {
+    zig_code <- generate_main(zig_code)
+  }
+
+  file_path <- write_zig(zig_code)
+  output <- zig_compile_file(file_path, "ast-check")
+  fs::file_delete(file_path)
+  return(output)
+}
+
+
+
+#' Compile a Zig file with the Zig compiler.
+#'
+#' This function is used to compile a Zig file, using the Zig compiler.
+#' In other words, this function takes a path to a Zig file (`*.zig`) as input,
+#' then, it runs a command from the Zig compiler to compile this Zig file.
+#'
+#' If this command from the Zig compiler runs succesfully, the function takes
+#' the result of this operation, and returns it to the caller. But, if this
+#' command does not run succesfully, then, the function stops the R process
+#' with an error report, that describes the Zig code that the Zig compiler
+#' attempted to compile, and also, the error message that was returned by the
+#' Zig compiler.
+#'
+#' @param file_path The full path to the Zig file to be compiled.
+#' @param zig_command The command from the Zig compiler to be used to
+#'     compile the Zig code in the current code block.
+#'
+#' @return A string with the output of the Zig compiler operation.
+zig_compile_file <- function(file_path, zig_command) {
   zig_cmd_path <- getOption("zig_exe_path")
-  out <- system2(
+  output <- system2(
     zig_cmd_path,
-    c(cmd_name, shQuote(temp_file)),
-    stdout = TRUE
+    c(zig_command, shQuote(file_path)),
+    stdout = TRUE,
+    stderr = TRUE
   )
-  if (exit_status_code(out) != 0L) {
-    code_report <- c(
-      "\n====== CODE EXECUTED ======",
-      "%s",
-      "===========================\n"
-    )
-    code_report <- str_c(code_report, collapse = "\n")
-    code_report <- sprintf(code_report, code_to_execute)
-    cat(code_report, file = stderr())
+  if (get_exit_status_code(output) != 0L) {
+    generate_error_report(file_path, output)
   }
-  fs::file_delete(temp_file)
+
+  return(output)
+}
+
+
+
+#' Get Zig compiler command.
+#'
+#' This function gets a build type as input, and returns the
+#' Zig compiler command that corresponds to this particular build type.
+#'
+#' @param build_type The build type, see `get_build_type()`.
+#'
+#' @return A string with the Zig compiler command.
+get_zig_compiler_command <- function(build_type) {
   if (build_type == "lib") {
-    clean_lib_files()
+    return("build-lib")
   }
 
+  return(build_type)
+}
+
 
-  out <- str_split_lines(out, options)
-  code <- remove_delim_lines(code)
-  knitr::engine_output(options, code, out)
-})
 
+#' Generate an error report.
+#'
+#' This function is used to generate a report with detailed information about
+#' a compilation error that was issued by the Zig compiler.
+#'
+#' @param file_path The full path to the Zig file to be compiled.
+#' @param output The output from the Zig compiler process.
+generate_error_report <- function(file_path, output) {
+  zig_code <- readr::read_file(file_path)
+  msg <- c(
+    "[ERROR]: An error was issued by the Zig compiler while trying ",
+    "to compile the Zig code block at ",
+    current_input(), ":", opts_current$get("label"), ".\n",
+    "[ERROR]: The Zig compiler returned the following error message: ",
+    output, "\n",
+    "[ERROR] The error was generated while trying to compile the ",
+    "following snippet of Zig code:\n"
+  )
+  msg <- str_flatten(msg)
 
+  code_report <- c(
+    "====== CODE COMPILED ============",
+    zig_code,
+    "=================================\n",
+    "[ERROR]: The output below is the backtrace from the R process:\n"
+  )
+  code_report <- str_c(
+    code_report,
+    collapse = "\n"
+  )
+
+  code_report <- str_c(msg, code_report, collapse = "")
+  stop(code_report)
+}
+
+
+
+#' Delete library files.
+#'
+#' If the Zig code was compiled as a library, using the
+#' `zig build-lib` command, then, some library files were generated
+#' during the compilation process, like library (`*.a`) and object files (`*.o`).
+#'
+#' However, these types of files are useless to the book context, and to the
+#' job we are performing here. Therefore, these files are automatically erased/deleted
+#' by the Zig knitr engine after the Zig code got compiled by the Zig compiler.
 clean_lib_files <- function() {
   obj_files <- fs::dir_ls(glob = "*.a")
   lib_files <- fs::dir_ls(glob = "*.o")
@@ -249,7 +491,15 @@ clean_lib_files <- function() {
 }
 
 
-exit_status_code <- function(output) {
+#' Get exit status code from the Zig compiler process.
+#'
+#' This function is used to get the exit status code that was
+#' issued by the Zig compiler process. This exit status code
+#' is a "bash exit status code" like from any other bash command.
+#'
+#' Normally, an exit status code equal to zero means "success",
+#' while status codes different than zero means some sort of "error".
+get_exit_status_code <- function(output) {
   status <- attr(output, "status")
   if (length(status) == 0L || is.null(status)) {
     return(0L)
@@ -257,3 +507,8 @@ exit_status_code <- function(output) {
 
   return(status)
 }
+
+
+
+# Registering the Zig engine in the current `knitr` process.
+knitr::knit_engines$set(zig = zig_engine)

From 6e6e31de10a07739d5191d44f731293a37ae64fa Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Wed, 4 Dec 2024 19:42:53 -0300
Subject: [PATCH 012/151] Fix duplicate code

---
 Chapters/02-debugging.qmd                     |   3 -
 Chapters/03-structs.qmd                       |   6 +-
 Chapters/05-pointers.qmd                      |   3 -
 Chapters/09-data-structures.qmd               |   6 +-
 Chapters/10-stack-project.qmd                 |   5 +-
 .../02-debugging/execute-results/html.json    |   8 +-
 .../03-structs/execute-results/html.json      |   4 +-
 .../05-pointers/execute-results/html.json     |   8 +-
 .../execute-results/html.json                 |   8 +-
 .../execute-results/html.json                 |   8 +-
 docs/Chapters/02-debugging.html               | 151 ++++-----
 docs/Chapters/03-structs.html                 | 320 +++++++++---------
 docs/Chapters/05-pointers.html                | 123 ++++---
 docs/Chapters/09-data-structures.html         | 174 +++++-----
 docs/Chapters/10-stack-project.html           | 213 ++++++------
 docs/search.json                              |  12 +-
 16 files changed, 519 insertions(+), 533 deletions(-)

diff --git a/Chapters/02-debugging.qmd b/Chapters/02-debugging.qmd
index c3c36752..7f3e147a 100644
--- a/Chapters/02-debugging.qmd
+++ b/Chapters/02-debugging.qmd
@@ -118,9 +118,6 @@ pub fn main() !void {
 }
 ```
 
-```
-Result: 50
-```
 
 You could also achieve the exact same result by getting a file descriptor object to `stderr`,
 then, creating a *writer* object to `stderr`, then, using the `print()` method of this
diff --git a/Chapters/03-structs.qmd b/Chapters/03-structs.qmd
index 6ef11ae4..04f035bf 100644
--- a/Chapters/03-structs.qmd
+++ b/Chapters/03-structs.qmd
@@ -310,9 +310,7 @@ its scope.
 
 ```{zig}
 #| auto_main: false
-#| build_type: "run"
-#| echo: true
-#| results: "hide"
+#| build_type: "lib"
 const std = @import("std");
 const stdout = std.io.getStdOut().writer();
 fn foo() !void {
@@ -684,7 +682,7 @@ By making it a pointer, we can finally alter the value of this function argument
 the body of the `add2()` function. You can see that the code example below compiles successfully.
 
 ```{zig}
-#| build_type: "run"
+#| build_type: "lib"
 #| auto_main: false
 const std = @import("std");
 fn add2(x: *u32) void {
diff --git a/Chapters/05-pointers.qmd b/Chapters/05-pointers.qmd
index de34ce2e..5658c4fc 100644
--- a/Chapters/05-pointers.qmd
+++ b/Chapters/05-pointers.qmd
@@ -63,9 +63,6 @@ const doubled = 2 * pointer.*;
 std.debug.print("{d}\n", .{doubled});
 ```
 
-```
-10
-```
 
 This syntax to dereference the pointer is nice. Because we can easily chain it with
 methods of the value pointed by the pointer. We can use the `User` struct that we have
diff --git a/Chapters/09-data-structures.qmd b/Chapters/09-data-structures.qmd
index 88286fdf..82d26f5b 100644
--- a/Chapters/09-data-structures.qmd
+++ b/Chapters/09-data-structures.qmd
@@ -207,7 +207,7 @@ style to the `pop()` method.
 
 ```{zig}
 #| auto_main: true
-#| eval: true
+#| build_type: "lib"
 var gpa = std.heap.GeneralPurposeAllocator(.{}){};
 const allocator = gpa.allocator();
 var buffer = try std.ArrayList(u8)
@@ -399,6 +399,7 @@ that uses the default settings and context.
 
 ```{zig}
 #| auto_main: false
+#| build_type: "lib"
 const std = @import("std");
 const AutoHashMap = std.hash_map.AutoHashMap;
 
@@ -490,7 +491,7 @@ The code example below demonstrates the use of these elements:
 
 ```{zig}
 #| auto_main: false
-#| build_type: "run"
+#| build_type: "lib"
 const std = @import("std");
 const AutoHashMap = std.hash_map.AutoHashMap;
 
@@ -644,6 +645,7 @@ resulting object from the `StringHashMap()` function.
 
 ```{zig}
 #| auto_main: false
+#| build_type: "lib"
 const std = @import("std");
 pub fn main() !void {
     var gpa = std.heap.GeneralPurposeAllocator(.{}){};
diff --git a/Chapters/10-stack-project.qmd b/Chapters/10-stack-project.qmd
index 0a4116f5..ada7535d 100644
--- a/Chapters/10-stack-project.qmd
+++ b/Chapters/10-stack-project.qmd
@@ -284,7 +284,7 @@ Having this in mind, makes sense to mark this argument as a comptime argument.
 
 ```{zig}
 #| auto_main: false
-#| build_type: "test"
+#| build_type: "lib"
 fn max(comptime T: type, a: T, b: T) T {
     return if (a > b) a else b;
 }
@@ -305,7 +305,7 @@ This generic function provides a very useful shortcut for us.
 
 ```{zig}
 #| auto_main: false
-#| build_type: "test"
+#| build_type: "lib"
 const std = @import("std");
 fn max(comptime T: type, a: T, b: T) T {
     return if (a > b) a else b;
@@ -324,7 +324,6 @@ Max n2: 89.24
 ```
 
 
-
 ### A generic data structure {#sec-generic-struct}
 
 Every data structure that you find in the Zig Standard Library (e.g. `ArrayList`, `HashMap`, etc.)
diff --git a/_freeze/Chapters/02-debugging/execute-results/html.json b/_freeze/Chapters/02-debugging/execute-results/html.json
index a656866e..dcd81837 100644
--- a/_freeze/Chapters/02-debugging/execute-results/html.json
+++ b/_freeze/Chapters/02-debugging/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "5bb29adee558edcbecbe21f328df9519",
+  "hash": "d955858e8c96c11c36427af044c591f0",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Debugging Zig applications\n\nBeing able to debug your applications is essential for any programmer who wants to\ndo serious programming in any language. That is why, in this chapter, we are going to talk about the\navailable strategies and tools to debug applications written in Zig.\n\n\n## Print debugging\n\nWe begin with the classic and battle-tested *print debugging* strategy.\nThe key advantage that debugging offers you is *visibility*.\nWith *print statements* you can easily see what results and objects\nare being produced by your application.\n\nThat is the essence of *print debugging*. Is to use\nprint expressions to see the values that are being generated by your program,\nand, as a result, get a much better understanding of how your program\nis behaving.\n\nMany programmers often resort to the print functions in Zig, such as the `stdout.print()`,\nor, the `std.debug.print()`, to get a better understanding of their programs.\nThis is a known and old strategy that is very simple and effective, and it is better known within\nthe programming community as *print debugging*.\nIn Zig, you can print information to the `stdout` or `stderr` streams of your system.\n\nLet's begin with `stdout`. First, you\nneed to get access to the `stdout`, by calling the `getStdOut()` method, from\nthe Zig Standard Library. This method returns a *file descriptor* object,\nand, through this object you can read/write to the `stdout`.\nI recommend you to check out all methods available in this object, by [checking the page in\nthe Zig Standard Library Official Reference for the type `File`](https://ziglang.org/documentation/master/std/#std.fs.File)[^zig-fiile-reference].\n\n[^zig-fiile-reference]: <https://ziglang.org/documentation/master/std/#std.fs.File>.\n\nFor our purpose here, which is to write something to the `stdout`, especially to debug our\nprogram, I recommend you to use the `writer()` method, which gives your a *writer* object.\nThis *writer* object offers some helper methods to write stuff into the file descriptor object\nthat represents the `stdout` stream. In special, the `print()` method.\n\n\nThe `print()` method from this *writer* object is a \"print formatter\" type of a function.\nIn other words, this method works exactly like the `printf()` function from C,\nor, like `println!()` from Rust.\nIn the first argument of the function, you specify a template string, and,\nin the second argument, you provide a list of values (or objects) that you want to insert\ninto your template message.\n\nIdeally, the template string in the first argument should contain some format specifier.\nEach format specifier is matched to a value (or object) that you have listed in the second argument.\nSo, if you provided 5 different objects in the second argument, then, the template string\nshould contain 5 format specifiers, one for each object provided.\n\nEach format specifier is represented by a single letter, and\nyou provide this format specifier inside a pair of curly braces. So, if you want to format\nyour object using the string specifier (`s`), then, you can insert the text `{s}` in your template string.\nHere is a quick list of the most used format specifiers:\n\n- `d`: for printing integers and floating-point numbers.\n- `c`: for printing characters.\n- `s`: for printing strings.\n- `p`: for printing memory addresses.\n- `x`: for printing hexadecimal values.\n- `any`: use any compatible format specifier (i.e. it automatically selects a format specifier for you).\n\nThe code example below gives you an example of use of this `print()` method\nwith the `d` format specifier.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    _ = try stdout.print(\"Result: {d}\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\n\n\nIs important to emphasize that, the `stdout.print()` method, as you would expect,\nprint your template string into the `stdout` stream of your system.\nHowever, you can also print your template string into the `stderr` stream\nif your prefer. All you need to do, is to replace the `stdout.print()`\ncall with the function `std.debug.print()`. Like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    std.debug.print(\"Result: {d}\\n\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\n\n\n```\nResult: 50\n```\n\nYou could also achieve the exact same result by getting a file descriptor object to `stderr`,\nthen, creating a *writer* object to `stderr`, then, using the `print()` method of this\n*writer* object, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stderr = std.io.getStdErr().writer();\n// some more lines ...\n_ = try stderr.print(\"Result: {d}\", .{result});\n```\n:::\n\n\n\n\n\n\n## Debugging through debuggers\n\nAlthough *print debugging* being a valid and very useful strategy,\nmost programmers prefer to use a debugger to debug their programs.\nSince Zig is a low-level language, you can use either GDB (GNU Debugger),\nor LLDB (LLVM Project Debugger) as your debugger.\n\nBoth debuggers can work with Zig code, and it's a matter of taste here.\nYou choose the debugger of your preference, and you work with it.\nIn this book, I will use LLDB as my debugger on the examples.\n\n\n### Compile your source code in debug mode {#sec-compile-debug-mode}\n\nIn order to debug your program through a debugger, you must compile\nyour source code in `Debug` mode. Because when you compile your\nsource code in other modes (such as `Release`), the compiler usually\nstrips out some essential information that is used by the debugger\nto read and track your program, like PDB (*Program Database*) files.\n\nBy compiling your source code in `Debug` mode, you ensure that the debugger\nwill find the necessary information in your program to debug it.\nBy default, the compiler uses the `Debug` mode when compiling your code.\nHaving this in mind, when you compile your program with the `build-exe`\ncommand (which was described at @sec-compile-code), if you don't specify\nan explicit mode through the `-O` command-line [^oargument]\nargument, then, the compiler will compile your code in `Debug` mode.\n\n[^oargument]: See <https://ziglang.org/documentation/master/#Debug>.\n\n\n### Let's debug a program\n\nAs an example, let's use LLDB to navigate and investigate the following\npiece of Zig code:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\nfn add_and_increment(a: u8, b: u8) u8 {\n    const sum = a + b;\n    const incremented = sum + 1;\n    return incremented;\n}\n\npub fn main() !void {\n    var n = add_and_increment(2, 3);\n    n = add_and_increment(n, n);\n    _ = try stdout.print(\"Result: {d}!\\n\", .{n});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 13!\n```\n\n\n:::\n:::\n\n\n\n\nThere is nothing wrong with this program. But it is\na good start for us. First, we need to compile\nthis program with the `zig build-exe` command.\nFor this example, suppose that I have compiled the above\nZig code into a binary executable called `add_program`.\n\n```bash\nzig build-exe add_program.zig\n```\n\nNow, we can start LLDB with `add_program`, like this:\n\n```bash\nlldb add_program\n```\n\nFrom now on, LLDB is started, and you can know that I'm\nexecuting LLDB commands by looking at the prefix `(lldb)`.\nIf something is prefixed with `(lldb)`, then you know\nthat it is a LLDB command.\n\nThe first thing I will do, is to set a breakpoint at\nthe `main()` function, by executing `b main`.\nAfter that, I just start the execution of the program\nwith `run`.\nYou can see in the output below, that the execution\nstopped at the first line in the function `main()`, as we expected.\n\n```bash\n(lldb) b main\nBreakpoint 1: where = debugging`debug1.main + 22\n    at debug1.zig:11:30, address = 0x00000000010341a6\n(lldb) run\nProcess 8654 launched: 'add_program' (x86_64)\nProcess 8654 stopped\n* thread #1, name = 'add_program',\n    stop reason = breakpoint 1.1 frame #0: 0x10341a6\n    add_program`debug1.main at add_program.zig:11:30\n   8   \t}\n   9   \t\n   10  \tpub fn main() !void {\n-> 11  \t    var n = add_and_increment(2, 3);\n   12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n```\n\nI can start navigating through the code, and checking the objects\nthat are being generated. If you are not familiar with the commands\navailable in LLDB, I recommend you to read the official documentation\nof the project[^lldb].\nYou can also look for cheat sheets, which quickly describes all commands\navailable for you[^lldb-quick-list].\n\n[^lldb]: <https://lldb.llvm.org/>\n[^lldb-quick-list]: <https://gist.github.com/ryanchang/a2f738f0c3cc6fbd71fa>.\n\nCurrently, we are in the first line at the `main()` function. In this line, we create\nthe `n` object, by executing the `add_and_increment()` function.\nTo execute the current line of code, and go to the next line, we can\nrun the `n` LLDB command. Let's execute this command.\n\nAfter we executed this line, we can also look at the value stored inside this `n` object\nby using the `p` LLDB command. The syntax for this command is `p <name-of-object>`.\n\nIf we take a look at the value stored in the `n` object (`p n`),\nnotice that it stores the hexadecimal value `0x06`, which\nis the number 6 in decimal. We can also see that, this value have a type `unsigned char`,\nwhich is an unsigned 8-bit integer.\nWe have talked already about this at @sec-zig-strings, that `u8` integers in Zig are equivalent\nto the C data type `unsigned char`.\n\n\n\n```bash\n(lldb) n\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step over frame #0: 0x10341ae\n    debugging`debug1.main at debug1.zig:12:26\n   9   \t\n   10  \tpub fn main() !void {\n   11  \t    var n = add_and_increment(2, 3);\n-> 12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n(lldb) p n\n(unsigned char) $1 = '\\x06'\n```\n\nNow, on the next line of code, we are executing the `add_and_increment()` function once again.\nWhy not step inside this function? Shall we? We can do that, by executing the `s` LLDB command.\nNotice in the example below that, after executing this command, we have entered into the context of the\n`add_and_increment()` function.\n\nAlso notice in the example below that, I have walked two more lines in the function's body, then,\nI execute the `frame variable` LLDB command, to see at once, the value stored in each of the variables\nthat were created inside the current scope.\n\nYou can see in the output below that, the object `sum` stores the value `\\f`,\nwhich represents the *form feed* character. This character in the ASCII table,\ncorresponds to the hexadecimal value `0x0C`, or, in decimal, the number 12.\nSo, this means that the result of the expression `a + b` executed at line\n5, resulted in the number 12.\n\n```bash\n(lldb) s\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step in frame #0: 0x10342de\n    debugging`debug1.add_and_increment(a='\\x02', b='\\x03')\n    at debug1.zig:4:39\n-> 4   \tfn add_and_increment(a: u8, b: u8) u8 {\n   5   \t    const sum = a + b;\n   6   \t    const incremented = sum + 1;\n   7   \t    return incremented;\n(lldb) n\n(lldb) n\n(lldb) frame variable\n(unsigned char) a = '\\x06'\n(unsigned char) b = '\\x06'\n(unsigned char) sum = '\\f'\n(unsigned char) incremented = '\\x06'\n```\n\n\n\n## How to investigate the data type of your objects\n\nSince Zig is a strongly-typed language, the data types associated with your objects\nare very important for your program. So, debugging the data types associated\nwith your objects might be important to understand bugs and errors in your program.\n\nWhen you walk through your program with a debugger, you can inspect the types of\nyour objects by simply printing them to the console, with the LLDB `p` command.\nBut you also have alternatives embedded in the language itself to access the data\ntypes of your objects.\n\nIn Zig, you can retrieve the data type of an object, by using the built-in function\n`@TypeOf()`. Just apply this function over the object, and you get access to \nthe data type of the object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst expect = std.testing.expect;\n\npub fn main() !void {\n    const number: i32 = 5;\n    try expect(@TypeOf(number) == i32);\n    try stdout.print(\"{any}\\n\", .{@TypeOf(number)});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ni32\n```\n\n\n:::\n:::\n\n\n\n\nThis function is similar to the `type()` built-in function from Python,\nor, the `typeof` operator in Javascript.\n\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Debugging Zig applications\n\nBeing able to debug your applications is essential for any programmer who wants to\ndo serious programming in any language. That is why, in this chapter, we are going to talk about the\navailable strategies and tools to debug applications written in Zig.\n\n\n## Print debugging\n\nWe begin with the classic and battle-tested *print debugging* strategy.\nThe key advantage that debugging offers you is *visibility*.\nWith *print statements* you can easily see what results and objects\nare being produced by your application.\n\nThat is the essence of *print debugging*. Is to use\nprint expressions to see the values that are being generated by your program,\nand, as a result, get a much better understanding of how your program\nis behaving.\n\nMany programmers often resort to the print functions in Zig, such as the `stdout.print()`,\nor, the `std.debug.print()`, to get a better understanding of their programs.\nThis is a known and old strategy that is very simple and effective, and it is better known within\nthe programming community as *print debugging*.\nIn Zig, you can print information to the `stdout` or `stderr` streams of your system.\n\nLet's begin with `stdout`. First, you\nneed to get access to the `stdout`, by calling the `getStdOut()` method, from\nthe Zig Standard Library. This method returns a *file descriptor* object,\nand, through this object you can read/write to the `stdout`.\nI recommend you to check out all methods available in this object, by [checking the page in\nthe Zig Standard Library Official Reference for the type `File`](https://ziglang.org/documentation/master/std/#std.fs.File)[^zig-fiile-reference].\n\n[^zig-fiile-reference]: <https://ziglang.org/documentation/master/std/#std.fs.File>.\n\nFor our purpose here, which is to write something to the `stdout`, especially to debug our\nprogram, I recommend you to use the `writer()` method, which gives your a *writer* object.\nThis *writer* object offers some helper methods to write stuff into the file descriptor object\nthat represents the `stdout` stream. In special, the `print()` method.\n\n\nThe `print()` method from this *writer* object is a \"print formatter\" type of a function.\nIn other words, this method works exactly like the `printf()` function from C,\nor, like `println!()` from Rust.\nIn the first argument of the function, you specify a template string, and,\nin the second argument, you provide a list of values (or objects) that you want to insert\ninto your template message.\n\nIdeally, the template string in the first argument should contain some format specifier.\nEach format specifier is matched to a value (or object) that you have listed in the second argument.\nSo, if you provided 5 different objects in the second argument, then, the template string\nshould contain 5 format specifiers, one for each object provided.\n\nEach format specifier is represented by a single letter, and\nyou provide this format specifier inside a pair of curly braces. So, if you want to format\nyour object using the string specifier (`s`), then, you can insert the text `{s}` in your template string.\nHere is a quick list of the most used format specifiers:\n\n- `d`: for printing integers and floating-point numbers.\n- `c`: for printing characters.\n- `s`: for printing strings.\n- `p`: for printing memory addresses.\n- `x`: for printing hexadecimal values.\n- `any`: use any compatible format specifier (i.e. it automatically selects a format specifier for you).\n\nThe code example below gives you an example of use of this `print()` method\nwith the `d` format specifier.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    _ = try stdout.print(\"Result: {d}\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\n\n\nIs important to emphasize that, the `stdout.print()` method, as you would expect,\nprint your template string into the `stdout` stream of your system.\nHowever, you can also print your template string into the `stderr` stream\nif your prefer. All you need to do, is to replace the `stdout.print()`\ncall with the function `std.debug.print()`. Like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    std.debug.print(\"Result: {d}\\n\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\n\n\n\nYou could also achieve the exact same result by getting a file descriptor object to `stderr`,\nthen, creating a *writer* object to `stderr`, then, using the `print()` method of this\n*writer* object, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stderr = std.io.getStdErr().writer();\n// some more lines ...\n_ = try stderr.print(\"Result: {d}\", .{result});\n```\n:::\n\n\n\n\n\n\n## Debugging through debuggers\n\nAlthough *print debugging* being a valid and very useful strategy,\nmost programmers prefer to use a debugger to debug their programs.\nSince Zig is a low-level language, you can use either GDB (GNU Debugger),\nor LLDB (LLVM Project Debugger) as your debugger.\n\nBoth debuggers can work with Zig code, and it's a matter of taste here.\nYou choose the debugger of your preference, and you work with it.\nIn this book, I will use LLDB as my debugger on the examples.\n\n\n### Compile your source code in debug mode {#sec-compile-debug-mode}\n\nIn order to debug your program through a debugger, you must compile\nyour source code in `Debug` mode. Because when you compile your\nsource code in other modes (such as `Release`), the compiler usually\nstrips out some essential information that is used by the debugger\nto read and track your program, like PDB (*Program Database*) files.\n\nBy compiling your source code in `Debug` mode, you ensure that the debugger\nwill find the necessary information in your program to debug it.\nBy default, the compiler uses the `Debug` mode when compiling your code.\nHaving this in mind, when you compile your program with the `build-exe`\ncommand (which was described at @sec-compile-code), if you don't specify\nan explicit mode through the `-O` command-line [^oargument]\nargument, then, the compiler will compile your code in `Debug` mode.\n\n[^oargument]: See <https://ziglang.org/documentation/master/#Debug>.\n\n\n### Let's debug a program\n\nAs an example, let's use LLDB to navigate and investigate the following\npiece of Zig code:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\nfn add_and_increment(a: u8, b: u8) u8 {\n    const sum = a + b;\n    const incremented = sum + 1;\n    return incremented;\n}\n\npub fn main() !void {\n    var n = add_and_increment(2, 3);\n    n = add_and_increment(n, n);\n    _ = try stdout.print(\"Result: {d}!\\n\", .{n});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 13!\n```\n\n\n:::\n:::\n\n\n\n\nThere is nothing wrong with this program. But it is\na good start for us. First, we need to compile\nthis program with the `zig build-exe` command.\nFor this example, suppose that I have compiled the above\nZig code into a binary executable called `add_program`.\n\n```bash\nzig build-exe add_program.zig\n```\n\nNow, we can start LLDB with `add_program`, like this:\n\n```bash\nlldb add_program\n```\n\nFrom now on, LLDB is started, and you can know that I'm\nexecuting LLDB commands by looking at the prefix `(lldb)`.\nIf something is prefixed with `(lldb)`, then you know\nthat it is a LLDB command.\n\nThe first thing I will do, is to set a breakpoint at\nthe `main()` function, by executing `b main`.\nAfter that, I just start the execution of the program\nwith `run`.\nYou can see in the output below, that the execution\nstopped at the first line in the function `main()`, as we expected.\n\n```bash\n(lldb) b main\nBreakpoint 1: where = debugging`debug1.main + 22\n    at debug1.zig:11:30, address = 0x00000000010341a6\n(lldb) run\nProcess 8654 launched: 'add_program' (x86_64)\nProcess 8654 stopped\n* thread #1, name = 'add_program',\n    stop reason = breakpoint 1.1 frame #0: 0x10341a6\n    add_program`debug1.main at add_program.zig:11:30\n   8   \t}\n   9   \t\n   10  \tpub fn main() !void {\n-> 11  \t    var n = add_and_increment(2, 3);\n   12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n```\n\nI can start navigating through the code, and checking the objects\nthat are being generated. If you are not familiar with the commands\navailable in LLDB, I recommend you to read the official documentation\nof the project[^lldb].\nYou can also look for cheat sheets, which quickly describes all commands\navailable for you[^lldb-quick-list].\n\n[^lldb]: <https://lldb.llvm.org/>\n[^lldb-quick-list]: <https://gist.github.com/ryanchang/a2f738f0c3cc6fbd71fa>.\n\nCurrently, we are in the first line at the `main()` function. In this line, we create\nthe `n` object, by executing the `add_and_increment()` function.\nTo execute the current line of code, and go to the next line, we can\nrun the `n` LLDB command. Let's execute this command.\n\nAfter we executed this line, we can also look at the value stored inside this `n` object\nby using the `p` LLDB command. The syntax for this command is `p <name-of-object>`.\n\nIf we take a look at the value stored in the `n` object (`p n`),\nnotice that it stores the hexadecimal value `0x06`, which\nis the number 6 in decimal. We can also see that, this value have a type `unsigned char`,\nwhich is an unsigned 8-bit integer.\nWe have talked already about this at @sec-zig-strings, that `u8` integers in Zig are equivalent\nto the C data type `unsigned char`.\n\n\n\n```bash\n(lldb) n\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step over frame #0: 0x10341ae\n    debugging`debug1.main at debug1.zig:12:26\n   9   \t\n   10  \tpub fn main() !void {\n   11  \t    var n = add_and_increment(2, 3);\n-> 12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n(lldb) p n\n(unsigned char) $1 = '\\x06'\n```\n\nNow, on the next line of code, we are executing the `add_and_increment()` function once again.\nWhy not step inside this function? Shall we? We can do that, by executing the `s` LLDB command.\nNotice in the example below that, after executing this command, we have entered into the context of the\n`add_and_increment()` function.\n\nAlso notice in the example below that, I have walked two more lines in the function's body, then,\nI execute the `frame variable` LLDB command, to see at once, the value stored in each of the variables\nthat were created inside the current scope.\n\nYou can see in the output below that, the object `sum` stores the value `\\f`,\nwhich represents the *form feed* character. This character in the ASCII table,\ncorresponds to the hexadecimal value `0x0C`, or, in decimal, the number 12.\nSo, this means that the result of the expression `a + b` executed at line\n5, resulted in the number 12.\n\n```bash\n(lldb) s\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step in frame #0: 0x10342de\n    debugging`debug1.add_and_increment(a='\\x02', b='\\x03')\n    at debug1.zig:4:39\n-> 4   \tfn add_and_increment(a: u8, b: u8) u8 {\n   5   \t    const sum = a + b;\n   6   \t    const incremented = sum + 1;\n   7   \t    return incremented;\n(lldb) n\n(lldb) n\n(lldb) frame variable\n(unsigned char) a = '\\x06'\n(unsigned char) b = '\\x06'\n(unsigned char) sum = '\\f'\n(unsigned char) incremented = '\\x06'\n```\n\n\n\n## How to investigate the data type of your objects\n\nSince Zig is a strongly-typed language, the data types associated with your objects\nare very important for your program. So, debugging the data types associated\nwith your objects might be important to understand bugs and errors in your program.\n\nWhen you walk through your program with a debugger, you can inspect the types of\nyour objects by simply printing them to the console, with the LLDB `p` command.\nBut you also have alternatives embedded in the language itself to access the data\ntypes of your objects.\n\nIn Zig, you can retrieve the data type of an object, by using the built-in function\n`@TypeOf()`. Just apply this function over the object, and you get access to \nthe data type of the object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst expect = std.testing.expect;\n\npub fn main() !void {\n    const number: i32 = 5;\n    try expect(@TypeOf(number) == i32);\n    try stdout.print(\"{any}\\n\", .{@TypeOf(number)});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ni32\n```\n\n\n:::\n:::\n\n\n\n\nThis function is similar to the `type()` built-in function from Python,\nor, the `typeof` operator in Javascript.\n\n",
+    "supporting": [
+      "02-debugging_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/03-structs/execute-results/html.json b/_freeze/Chapters/03-structs/execute-results/html.json
index 549083fc..04f37e1b 100644
--- a/_freeze/Chapters/03-structs/execute-results/html.json
+++ b/_freeze/Chapters/03-structs/execute-results/html.json
@@ -1,8 +1,8 @@
 {
-  "hash": "5d7f2c2e3cfbfb6754b90978cd0a4b89",
+  "hash": "cedb7b341aa333220e9f4f2918e4ea74",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Control flow, structs, modules and types\n\nWe have discussed a lot of Zig's syntax in the last chapter,\nespecially in @sec-root-file and @sec-main-file.\nBut we still need to discuss some other very important\nelements of the language. Elements that you will use constantly on your day-to-day\nroutine.\n\nWe begin this chapter by discussing the different keywords and structures\nin Zig related to control flow (e.g. loops and if statements).\nThen, we talk about structs and how they can be used to do some\nbasic Object-Oriented (OOP) patterns in Zig. We also talk about\ntype inference and type casting.\nFinally, we end this chapter by discussing modules, and how they relate\nto structs.\n\n\n\n## Control flow {#sec-zig-control-flow}\n\nSometimes, you need to make decisions in your program. Maybe you need to decide\nwhether or not to execute a specific piece of code. Or maybe,\nyou need to apply the same operation over a sequence of values. These kinds of tasks,\ninvolve using structures that are capable of changing the \"control flow\" of our program.\n\nIn computer science, the term \"control flow\" usually refers to the order in which expressions (or commands)\nare evaluated in a given language or program. But this term is also used to refer\nto structures that are capable of changing this \"evaluation order\" of the commands\nexecuted by a given language/program.\n\nThese structures are better known\nby a set of terms, such as: loops, if/else statements, switch statements, among others. So,\nloops and if/else statements are examples of structures that can change the \"control\nflow\" of our program. The keywords `continue` and `break` are also examples of symbols\nthat can change the order of evaluation, since they can move our program to the next iteration\nof a loop, or make the loop stop completely.\n\n\n### If/else statements\n\nAn if/else statement performs a \"conditional flow operation\".\nA conditional flow control (or choice control) allows you to execute\nor ignore a certain block of commands based on a logical condition.\nMany programmers and computer science professionals also use\nthe term \"branching\" in this case.\nIn essence, an if/else statement allow us to use the result of a logical test\nto decide whether or not to execute a given block of commands.\n\nIn Zig, we write if/else statements by using the keywords `if` and `else`.\nWe start with the `if` keyword followed by a logical test inside a pair\nof parentheses, followed by a pair of curly braces which contains the lines\nof code to be executed in case the logical test returns the value `true`.\n\nAfter that, you can optionally add an `else` statement. To do that, just add the `else`\nkeyword followed by a pair of curly braces, with the lines of code\nto executed in case the logical test defined at `if` returns `false`.\n\nIn the example below, we are testing if the object `x` contains a number\nthat is greater than 10. Judging by the output printed to the console,\nwe know that this logical test returned `false`. Because the output\nin the console is compatible with the line of code present in the\n`else` branch of the if/else statement.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x = 5;\nif (x > 10) {\n    try stdout.print(\n        \"x > 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x <= 10!\\n\", .{}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nx <= 10!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Switch statements {#sec-switch}\n\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust.\nAs you would expect, to write a switch statement in Zig we use the `switch` keyword.\nWe provide the value that we want to \"switch over\" inside a\npair of parentheses. Then, we list the possible combinations (or \"branches\")\ninside a pair of curly braces.\n\nLet's take a look at the code example below. You can see that\nI'm creating an enum type called `Role`. We talk more about enums in @sec-enum.\nBut in summary, this `Role` type is listing different types of roles in a fictitious\ncompany, like `SE` for Software Engineer, `DE` for Data Engineer, `PM` for Product Manager,\netc.\n\nNotice that we are using the value from the `role` object in the\nswitch statement, to discover which exact area we need to store in the `area` variable object.\nAlso notice that we are using type inference inside the switch statement, with the dot character,\nas we are going to describe in @sec-type-inference.\nThis makes the `zig` compiler infer the correct data type of the values (`PM`, `SE`, etc.) for us.\n\nAlso notice that, we are grouping multiple values in the same branch of the switch statement.\nWe just separate each possible value with a comma. For example, if `role` contains either `DE` or `DA`,\nthe `area` variable would contain the value `\"Data & Analytics\"`, instead of `\"Platform\"` or `\"Sales\"`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO => {\n            area = \"Platform\";\n        },\n        .DE, .DA => {\n            area = \"Data & Analytics\";\n        },\n        .KS => {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nPlatform\n```\n\n\n:::\n:::\n\n\n\n\n\n#### Switch statements must exhaust all possibilities\n\nOne very important aspect about switch statements in Zig\nis that they must exhaust all existing possibilities.\nIn other words, all possible values that could be found inside the `order`\nobject must be explicitly handled in this switch statement.\n\nSince the `role` object have type `Role`, the only possible values to\nbe found inside this object are `PM`, `SE`, `DPE`, `PO`, `DE`, `DA` and `KS`.\nThere are no other possible values to be stored in this `role` object.\nThus, the switch statements must have a combination (branch) for each one of these values.\nThis is what \"exhaust all existing possibilities\" means. The switch statement covers\nevery possible case.\n\nTherefore, you cannot write a switch statement in Zig, and leave an edge case\nwith no explicit action to be taken.\nThis is a similar behaviour to switch statements in Rust, which also have to\nhandle all possible cases.\n\n\n\n#### The else branch\n\nTake a look at the `dump_hex_fallible()` function below as an example. This function\ncomes from the Zig Standard Library. More precisely, from the\n[`debug.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/debug.zig)[^debug-mod].\nThere are multiple lines in this function, but I omitted them to focus solely on the\nswitch statement found in this function. Notice that this switch statement has four\npossible cases (i.e. four explicit branches). Also, notice that we used an `else` branch\nin this case.\n\nAn `else` branch in a switch statement works as the \"default branch\".\nWhenever you have multiple cases in your switch statement where\nyou want to apply the exact same action, you can use an `else` branch to do that.\n\n[^debug-mod]: <https://github.com/ziglang/zig/blob/master/lib/std/debug.zig>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' => try writer.writeAll(\"␊\"),\n        '\\r' => try writer.writeAll(\"␍\"),\n        '\\t' => try writer.writeAll(\"␉\"),\n        else => try writer.writeByte('.'),\n    }\n}\n```\n:::\n\n\n\n\nMany programmers would also use an `else` branch to handle a \"not supported\" case.\nThat is, a case that cannot be properly handled by your code, or, just a case that\nshould not be \"fixed\". Therefore, you can use an `else` branch to panic (or raise an error)\nin your program to stop the current execution.\n\nTake the code example below. We can see that, we are handling the cases\nfor the `level` object being either 1, 2, or 3. All other possible cases are not supported by default,\nand, as consequence, we raise a runtime error in such cases through the `@panic()` built-in function.\n\nAlso notice that, we are assigning the result of the switch statement to a new object called `category`.\nThis is another thing that you can do with switch statements in Zig. If a branch\noutputs a value as result, you can store the result value of the switch statement into\na new object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 => \"beginner\",\n    3 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n:::\n\n\n\n\n```\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n```\n\n\n\n#### Using ranges in switch\n\nFurthermore, you can also use ranges of values in switch statements.\nThat is, you can create a branch in your switch statement that is used\nwhenever the input value is within the specified range. These \"range expressions\"\nare created with the operator `...`. It is important\nto emphasize that the ranges created by this operator are\ninclusive on both ends.\n\nFor example, I could easily change the previous code example to support all\nlevels between 0 and 100. Like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 => \"beginner\",\n    26...75 => \"intermediary\",\n    76...100 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nbeginner\n```\n\n\n:::\n:::\n\n\n\n\nThis is neat, and it works with character ranges too. That is, I could\nsimply write `'a'...'z'`, to match any character value that is a\nlowercase letter, and it would work fine.\n\n\n#### Labeled switch statements\n\nIn @sec-blocks we have talked about labeling blocks, and also, about using these labels\nto return a value from the block. Well, from version 0.14.0 and onwards of the `zig` compiler,\nyou can also apply labels over switch statements, which makes it possible to almost implement a\n\"C `goto`\" like pattern.\n\nFor example, if you give the label `xsw` to a switch statement, you can use this\nlabel in conjunction with the `continue` keyword to go back to the beginning of the switch\nstatement. In the example below, the execution goes back to the beginning of the\nswitch statement two times, before ending at the `3` branch.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nxsw: switch (@as(u8, 1)) {\n    1 => {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 => continue :xsw 3,\n    3 => return,\n    4 => {},\n    else => {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n```\n:::\n\n\n\n\n\n### The `defer` keyword {#sec-defer}\n\nWith the `defer` keyword you can register an expression to be executed when you exit the current scope.\nTherefore, this keyword has a similar functionality as the `on.exit()` function from R.\nTake the `foo()` function below as an example. When we execute this `foo()` function, the expression\nthat prints the message \"Exiting function ...\" is getting executed only when the function exits\nits scope.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nAdding some numbers ...\nMultiplying ...\nExiting function ...\n```\n\nTherefore, we can use `defer` to declare an expression that is going to be executed\nwhen your code exits the current scope. Some programmers like to interpret the phrase \"exit of the current scope\"\nas \"the end of the current scope\". But this interpretation might not be entirely correct, depending\non what you consider as \"the end of the current scope\".\n\nI mean, what do you consider as **the end** of the current scope? Is it the closing curly bracket (`}`) of the scope?\nIs it when the last expression in the function get's executed? Is it when the function returns to the previous scope?\nEtc. For example, it would not be correct to interpret the \"exit of the current scope\" as the closing\ncurly bracket of the scope. Because the function might exit from an earlier position than this\nclosing curly bracket (e.g. an error value was generated at a previous line inside the function;\nthe function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\n\nNow, if you remember of what we have discussed in @sec-blocks, there are multiple structures in the language\nthat create their own separate scopes. For/while loops, if/else statements,\nfunctions, normal blocks, etc. This also affects the interpretation of `defer`.\nFor example, if you use `defer` inside a for loop, then, the given expression\nwill be executed everytime this specific for loop exits its own scope.\n\nBefore we continue, is worth emphasizing that the `defer` keyword is an \"unconditional defer\".\nWhich means that the given expression will be executed no matter how the code exits\nthe current scope. For example, your code might exit the current scope because of an error value\nbeing generated, or, because of a return statement, or, a break statement, etc.\n\n\n\n### The `errdefer` keyword {#sec-errdefer1}\n\nOn the previous section, we have discussed the `defer` keyword, which you can use to\nregister an expression to be executed at the exit of the current scope.\nBut this keyword has a brother, which is the `errdefer` keyword. While `defer`\nis an \"unconditional defer\", the `errdefer` keyword is a \"conditional defer\".\nWhich means that the given expression is executed only when you exit the current\nscope on a very specific circumstance.\n\nIn more details, the expression given to `errdefer` is executed only when an error occurs in the current scope.\nTherefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope\nin a normal situation, without errors, the expression given to `errdefer` is not executed.\n\nThis makes the `errdefer` keyword one of the many tools available in Zig for error handling.\nIn this section, we are more concerned with the control flow aspects around `errdefer`.\nBut we are going to discuss `errdefer` later as a error handling tool in @sec-errdefer2.\n\nThe code example below demonstrates three things:\n\n- that `defer` is an \"unconditional defer\", because the given expression get's executed regardless of how the function `foo()` exits its own scope.\n- that `errdefer` is executed because the function `foo()` returned an error value.\n- that `defer` and `errdefer` expressions are executed in a LIFO (*last in, first out*) order.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\nWhen I say that \"defer expressions\" are executed in a LIFO order, what I want to say is that\nthe last `defer` or `errdefer` expressions in the code are the first ones to be executed.\nYou could also interpret this as: \"defer expressions\" are executed from bottom to top, or,\nfrom last to first.\n\nTherefore, if I change the order of the `defer` and `errdefer` expressions, you will notice that\nthe value of `i` that get's printed to the console changes to 1. This doesn't mean that the\n`defer` expression was not executed in this case. This actually means that the `defer` expression\nwas executed only after the `errdefer` expression. The code example below demonstrates this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\n\n\n### For loops\n\nA loop allows you to execute the same lines of code multiple times,\nthus, creating a \"repetition space\" in the execution flow of your program.\nLoops are particularly useful when we want to replicate the same function\n(or the same set of commands) over different inputs.\n\nThere are different types of loops available in Zig. But the most\nessential of them all is probably the *for loop*. A for loop is\nused to apply the same piece of code over the elements of a slice, or, an array.\n\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from\nother languages. You start with the `for` keyword, then, you\nlist the items that you want to iterate\nover inside a pair of parentheses. Then, inside of a pair of pipes (`|`)\nyou should declare an identifier that will serve as your iterator, or,\nthe \"repetition index of the loop\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (items) |value| {\n    // code to execute\n}\n```\n:::\n\n\n\n\nTherefore, instead of using a `(value in items)` syntax,\nin Zig, for loops use the syntax `(items) |value|`. In the example\nbelow, you can see that we are looping through the items\nof the array stored at the object `name`, and printing to the\nconsole the decimal representation of each character in this array.\n\nIf we wanted, we could also iterate through a slice (or a portion) of\nthe array, instead of iterating through the entire array stored in the `name` object.\nJust use a range selector to select the section you want. For example,\nI could provide the expression `name[0..3]` to the for loop, to iterate\njust through the first 3 elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n80 | 101 | 100 | 114 | 111 | \n```\n\n\n:::\n:::\n\n\n\n\nIn the above example we are using the value itself of each\nelement in the array as our iterator. But there are many situations where\nwe need to use an index instead of the actual values of the items.\n\nYou can do that by providing a second set of items to iterate over.\nMore precisely, you provide the range selector `0..` to the for loop. So,\nyes, you can use two different iterators at the same time in a for\nloop in Zig.\n\nBut remember from @sec-assignments that, every object\nyou create in Zig must be used in some way. So if you declare two iterators\nin your for loop, you must use both iterators inside the for loop body.\nBut if you want to use just the index iterator, and not use the \"value iterator\",\nthen, you can discard the value iterator by maching the\nvalue items to the underscore character, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n:::\n\n\n\n\n```\n0 | 1 | 2 | 3 | 4 |\n```\n\n\n### While loops\n\nA while loop is created from the `while` keyword. A `for` loop\niterates through the items of an array, but a `while` loop\nwill loop continuously, and infinitely, until a logical test\n(specified by you) becomes false.\n\nYou start with the `while` keyword, then, you define a logical\nexpression inside a pair of parentheses, and the body of the\nloop is provided inside a pair of curly braces, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\nYou can also specify the increment expression to be used at the beginning of a while loop.\nTo do that, we write the increment expression inside a pair of parentheses after a colon character (`:`).\nThe code example below demonstrates this other pattern.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\n### Using `break` and `continue`\n\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using\nthe keywords `break` and `continue`, respectively. The `while` loop presented in the next code example is,\nat first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to `true`.\nBut what makes this `while` loop stop when the `i` object reaches the count\n10? It is the `break` keyword!\n\nInside the while loop, we have an if statement that is constantly checking if the `i` variable\nis equal to 10. Since we are incrementing the value of `i` at each iteration of the\nwhile loop, this `i` object will eventually be equal to 10, and when it is, the if statement\nwill execute the `break` expression, and, as a result, the execution of the while loop is stopped.\n\nNotice the use of the `expect()` function from the Zig Standard Library after the while loop.\nThis `expect()` function is an \"assert\" type of function.\nThis function checks if the logical test provided is equal to true. If so, the function do nothing.\nOtherwise (i.e. the logical test is equal to false), the function raises an assertion error.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nEverything worked!\n```\n\n\n:::\n:::\n\n\n\n\nSince this code example was executed successfully by the `zig` compiler,\nwithout raising any errors, we known that, after the execution of the while loop,\nthe `i` object is equal to 10. Because if it wasn't equal to 10, an error would have\nbeen raised by `expect()`.\n\nNow, in the next example, we have a use case for\nthe `continue` keyword. The if statement is constantly\nchecking if the current index is a multiple of 2. If\nit is, we jump to the next iteration of the loop.\nOtherwise, the loop just prints the current index to the console.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 3 | 5 | \n```\n\n\n:::\n:::\n\n\n\n\n\n\n## Function parameters are immutable {#sec-fun-pars}\n\nWe have already discussed a lot of the syntax behind function declarations in @sec-root-file and @sec-main-file.\nBut I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig.\nIn summary, function parameters are immutable in Zig.\n\nTake the code example below, where we declare a simple function that just tries to add\nsome amount to the input integer, and returns the result back. If you look closely\nat the body of this `add2()` function, you will notice that we try\nto save the result back into the `x` function argument.\n\nIn other words, this function not only uses the value that it received through the function argument\n`x`, but it also tries to change the value of this function argument, by assigning the addition result\ninto `x`. However, function arguments in Zig are immutable. You cannot change their values, or, you\ncannot assign values to them inside the body's function.\n\nThis is the reason why, the code example below does not compile successfully. If you try to compile\nthis code example, you will get a compile error message about \"trying to change the value of a\nimmutable (i.e. constant) object\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n\n\n```\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n```\n\n\n### A free optimization\n\nIf a function argument receives as input an object whose data type is\nany of the primitive types that we have listed in @sec-primitive-data-types,\nthis object is always passed by value to the function. In other words, this object\nis copied into the function stack frame.\n\nHowever, if the input object have a more complex data type, for example, it might\nbe a struct instance, or an array, or an union value, etc., in cases like that, the `zig` compiler\nwill take the liberty of deciding for you which strategy is best. Thus, the `zig` compiler will\npass your object to the function either by value, or by reference. The compiler will always\nchoose the strategy that is faster for you.\nThis optimization that you get for free is possible only because function arguments are\nimmutable in Zig.\n\n\n### How to overcome this barrier\n\nThere are some situations where you might need to change the value of your function argument\ndirectly inside the function's body. This happens more often when we are passing\nC structs as inputs to Zig functions.\n\nIn a situation like this, you can overcome this barrier by using a pointer. In other words,\ninstead of passing a value as input to the argument, you can pass a \"pointer to value\" instead.\nYou can change the value that the pointer points to, by dereferencing it.\n\nTherefore, if we take our previous `add2()` example, we can change the value of the\nfunction argument `x` inside the function's body by marking the `x` argument as a\n\"pointer to a `u32` value\" (i.e. `*u32` data type), instead of a `u32` value.\nBy making it a pointer, we can finally alter the value of this function argument directly inside\nthe body of the `add2()` function. You can see that the code example below compiles successfully.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 6\n```\n\n\n:::\n:::\n\n\n\n\n```\nResult: 6\n```\n\n\nEven in this code example above, the `x` argument is still immutable. Which means that the pointer itself is immutable.\nTherefore, you cannot change the memory address that it points to. However, you can dereference the pointer\nto access the value that it points to, and also, to change this value, if you need to.\n\n\n\n\n\n## Structs and OOP {#sec-structs-and-oop}\n\nZig is a language more closely related to C (which is a procedural language),\nthan it is to C++ or Java (which are object-oriented languages). Because of that, you do not\nhave advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or\nclass inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\n\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C.\nYou give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can\nalso register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object\nthat you create with this new type, will always have these methods available and associated with them.\n\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which\nis used to construct (or, to instantiate) every object of this particular class, and we also have\na destructor method (or a destructor function), which is the function responsible for destroying\nevery object of this class.\n\nIn Zig, we normally declare the constructor and the destructor methods\nof our structs, by declaring an `init()` and a `deinit()` methods inside the struct.\nThis is just a naming convention that you will find across the entire Zig Standard Library.\nSo, in Zig, the `init()` method of a struct is normally the constructor method of the class represented by this struct.\nWhile the `deinit()` method is the method used for destroying an existing instance of that struct.\n\nThe `init()` and `deinit()` methods are both used extensively in Zig code, and you will see both of\nthem being used when we talk about allocators in @sec-allocators.\nBut, as another example, let's build a simple `User` struct to represent a user of some sort of system.\n\nIf you look at the `User` struct below, you can see the `struct` keyword.\nNotice the data members of this struct: `id`, `name` and `email`. Every data member has its\ntype explicitly annotated, with the colon character (`:`) syntax that we described earlier in @sec-root-file.\nBut also notice that every line in the struct body that describes a data member, ends with a comma character (`,`).\nSo every time you declare a data member in your Zig code, always end the line with a comma character, instead\nof ending it with the traditional semicolon character (`;`).\n\nNext, we have registered an `init()` function as a method\nof this `User` struct. This `init()` method is the constructor method that we will use to instantiate\nevery new `User` object. That is why this `init()` function returns a new `User` object as result.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    pub fn init(id: u64,\n                name: []const u8,\n                email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    pub fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\npedro\n```\n\n\n:::\n:::\n\n\n\n\nThe `pub` keyword plays an important role in struct declarations, and OOP in Zig.\nEvery method that you declare in your struct that is marked with the keyword `pub`,\nbecomes a public method of this particular struct.\n\nSo every method that you create inside your struct, is, at first, a private method\nof that struct. Meaning that, this method can only be called from within this\nstruct. But, if you mark this method as public, with the keyword `pub`, then,\nyou can call the method directly from an instance of the `User` struct.\n\nIn other words, the functions marked by the keyword `pub`\nare members of the public API of that struct.\nFor example, if I did not mark the `print_name()` method as public,\nthen, I could not execute the line `u.print_name()`. Because I would\nnot be authorized to call this method directly in my code.\n\n\n\n### Anonymous struct literals {#sec-anonymous-struct-literals}\n\nYou can declare a struct object as a literal value. When we do that, we normally specify the\ndata type of this struct literal by writing its data type just before the opening curly brace.\nFor example, I could write a struct literal value of the type `User` that we have defined\nin the previous section like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n```\n:::\n\n\n\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a\nstruct literal, but not specify explicitly the type of this particular struct.\nAn anonymous struct is written by using the syntax `.{}`. So, we essentially\nreplaced the explicit type of the struct literal with a dot character (`.`).\n\nAs we described in @sec-type-inference, when you put a dot before a struct literal,\nthe type of this struct literal is automatically inferred by the `zig` compiler.\nIn essence, the `zig` compiler will look for some hint of what is the type of that struct.\nThis hint can be the type annotation of a function argument,\nor the return type annotation of the function that you are using, or the type annotation\nof an existing object.\nIf the compiler does find such type annotation, it will use this\ntype in your literal struct.\n\nAnonymous structs are very commonly used as inputs to function arguments in Zig.\nOne example that you have seen already constantly, is the `print()`\nfunction from the `stdout` object.\nThis function takes two arguments.\nThe first argument, is a template string, which should\ncontain string format specifiers in it, which tells how the values provided\nin the second argument should be printed into the message.\n\nWhile the second argument is a struct literal that lists the values\nto be printed into the template message specified in the first argument.\nYou normally want to use an anonymous struct literal here, so that the\n`zig` compiler do the job of specifying the type of this particular\nanonymous struct for you.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello, world!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Struct declarations must be constant\n\nTypes in Zig must be `const` or `comptime` (we are going to talk more about comptime in @sec-comptime).\nWhat this means is that you cannot create a new data type, and mark it as variable with the `var` keyword.\nSo struct declarations are always constant. You cannot declare a new struct type using the `var` keyword.\nIt must be `const`.\n\nIn the `Vec3` example below, this declaration is allowed because I'm using the `const` keyword\nto declare this new data type.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n```\n:::\n\n\n\n\n\n### The `self` method argument {#sec-self-arg}\n\nIn every language that have OOP, when we declare a method of some class or struct, we\nusually declare this method as a function that has a `self` argument.\nThis `self` argument is the reference to the object itself from which the method\nis being called from.\n\nIt is not mandatory to use this `self` argument. But why would you not use this `self` argument?\nThere is no reason to not use it. Because the only way to get access to the data stored in the\ndata members of your struct is to access them through this `self` argument.\nIf you don't need to use the data in the data members of your struct inside your method, you very likely don't need\na method. You can just declare this logic as a simple function, outside of your\nstruct declaration.\n\n\nTake the `Vec3` struct below. Inside this `Vec3` struct we declared a method named `distance()`.\nThis method calculates the distance between two `Vec3` objects, by following the distance\nformula in euclidean space. Notice that this `distance()` method takes two `Vec3` objects\nas input, `self` and `other`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n```\n:::\n\n\n\n\n\nThe `self` argument corresponds to the `Vec3` object from which this `distance()` method\nis being called from. While the `other` is a separate `Vec3` object that is given as input\nto this method. In the example below, the `self` argument corresponds to the object\n`v1`, because the `distance()` method is being called from the `v1` object,\nwhile the `other` argument corresponds to the object `v2`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n```\n:::\n\n\n\n\n```\nDistance: 3.3970575502926055\n```\n\n\n\n### About the struct state\n\nSometimes you don't need to care about the state of your struct object. Sometimes, you just need\nto instantiate and use the objects, without altering their state. You can notice that when you have methods\ninside your struct declaration that might use the values that are present in the data members, but they\ndo not alter the values in these data members of the struct in anyway.\n\nThe `Vec3` struct that was presented in @sec-self-arg is an example of that.\nThis struct have a single method named `distance()`, and this method does use the values\npresent in all three data members of the struct (`x`, `y` and `z`). But at the same time,\nthis method does not change the values of these data members at any point.\n\nAs a result of that, when we create `Vec3` objects we usually create them as\nconstant objects, like the `v1` and `v2` objects presented in @sec-self-arg.\nWe can create them as variable objects with the `var` keyword,\nif we want to. But because the methods of this `Vec3` struct do not change\nthe state of the objects in any point, it's unnecessary to mark them\nas variable objects.\n\nBut why? Why am I talking about this here? It's because the `self` argument\nin the methods is affected depending on whether the\nmethods present in a struct change or don't change the state of the object itself.\nMore specifically, when you have a method in a struct that changes the state\nof the object (i.e. change the value of a data member), the `self` argument\nin this method must be annotated in a different manner.\n\nAs I described in @sec-self-arg, the `self` argument in methods of\na struct is the argument that receives as input the object from which the method\nwas called from. We usually annotate this argument in the methods by writing `self`,\nfollowed by the colon character (`:`), and the data type of the struct to which\nthe method belongs to (e.g. `User`, `Vec3`, etc.).\n\nIf we take the `Vec3` struct that we defined in the previous section as an example,\nwe can see in the `distance()` method that this `self` argument is annotated as\n`self: Vec3`. Because the state of the `Vec3` object is never altered by this\nmethod.\n\nBut what if we do have a method that alters the state of the object, by altering the\nvalues of its data members, how should we annotate `self` in this instance? The answer is:\n\"we should annotate `self` as a pointer of `x`, instead of just `x`\".\nIn other words, you should annotate `self` as `self: *x`, instead of annotating it\nas `self: x`.\n\nIf we create a new method inside the `Vec3` object that, for example, expands the\nvector by multiplying its coordinates by a factor of two, then, we need to follow\nthis rule specified in the previous paragraph. The code example below demonstrates\nthis idea:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n```\n:::\n\n\n\n\nNotice in the code example above that we have added a new method\nto our `Vec3` struct named `twice()`. This method doubles the\ncoordinate values of our vector object. In the\ncase of the `twice()` method, we annotated the `self` argument as `*Vec3`,\nindicating that this argument receives a pointer (or a reference, if you prefer to call it this way)\nto a `Vec3` object as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n```\n:::\n\n\n\n\n```\nDoubled: 8.4\n```\n\n\n\nNow, if you change the `self` argument in this `twice()` method to `self: Vec3`, like in the\n`distance()` method, you will get the compiler error exposed below as result. Notice that this\nerror message is showing a line from the `twice()` method body,\nindicating that you cannot alter the value of the `x` data member.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n```\n:::\n\n\n\n\n```\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\n```\n\nThis error message indicates that the `x` data member belongs to a constant object,\nand, because of that, it cannot be changed. Ultimately, this error message\nis telling us that the `self` argument is constant.\n\nIf you take some time, and think hard about this error message, you will understand it.\nYou already have the tools to understand why we are getting this error message.\nWe have talked about it already in @sec-fun-pars.\nSo remember, every function argument is immutable in Zig, and `self`\nis no exception to this rule.\n\nIn this example, we marked the `v3` object as a variable object.\nBut this does not matter. Because it is not about the input object, it is about\nthe function argument.\n\nThe problem begins when we try to alter the value of `self` directly, which is a function argument,\nand, every function argument is immutable by default. You may ask yourself how can we overcome\nthis barrier, and once again, the solution was also discussed in @sec-fun-pars.\nWe overcome this barrier, by explicitly marking the `self` argument as a pointer.\n\n\n::: {.callout-note}\nIf a method of your `x` struct alters the state of the object, by\nchanging the value of any data member, then, remember to use `self: *x`,\ninstead of `self: x` in the function signature of this method.\n:::\n\n\nYou could also interpret the content discussed in this section as:\n\"if you need to alter the state of your `x` struct object in one of its methods,\nyou must explicitly pass the `x` struct object by reference to the `self` argument of this method\".\n\n\n\n## Type inference {#sec-type-inference}\n\nZig is a strongly typed language. But, there are some situations\nwhere you don't have to explicitly write the type of every single object in your source code,\nas you would expect from a traditional strongly typed language, such as C and C++.\n\nIn some situations, the `zig` compiler can use type inference to solve the data types for you, easing some of\nthe burden that you carry as a developer.\nThe most common way this happens is through function arguments that receive struct objects\nas input.\n\nIn general, type inference in Zig is done by using the dot character (`.`).\nEverytime you see a dot character written before a struct literal, or before an enum value, or something like that,\nyou know that this dot character is playing a special party in this place. More specifically, it is\ntelling the `zig` compiler something along the lines of: \"Hey! Can you infer the type of this\nvalue for me? Please!\". In other words, this dot character is playing a similar role as the `auto` keyword in C++.\n\nI gave you some examples of this in @sec-anonymous-struct-literals, where we used anonymous struct literals.\nAnonymous struct literals are, struct literals that use type inference to\ninfer the exact type of this particular struct literal.\nThis type inference is done by looking for some minimal hint of the correct data type to be used.\nYou could say that the `zig` compiler looks for any neighbouring type annotation that might tell it\nwhat the correct type would be.\n\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in @sec-switch).\nI also gave some other examples of type inference in @sec-switch, where we were inferring the data types of enum values listed inside\nof switch statements (e.g. `.DE`).\nBut as another example, take a look at this `fence()` function reproduced below,\nwhich comes from the [`atomic.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig)[^fence-fn]\nof the Zig Standard Library.\n\n[^fence-fn]: <https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig>.\n\nThere are a lot of things in this function that we haven't talked about yet, such as:\nwhat `comptime` means? `inline`? `extern`?\nLet's just ignore all of these things, and focus solely on the switch statement\nthat is inside this function.\n\nWe can see that this switch statement uses the `order` object as input. This `order`\nobject is one of the inputs of this `fence()` function, and we can see in the type annotation,\nthat this object is of type `AtomicOrder`. We can also see a bunch of values inside the\nswitch statements that begin with a dot character, such as `.release` and `.acquire`.\n\nBecause these weird values contain a dot character before them, we are asking the `zig`\ncompiler to infer the types of these values inside the switch statement. Then, the `zig`\ncompiler is looking into the current context where these values are being used, and it is\ntrying to infer the types of these values.\n\nSince they are being used inside a switch statement, the `zig` compiler looks into the type\nof the input object given to the switch statement, which is the `order` object in this case.\nBecause this object have type `AtomicOrder`, the `zig` compiler infers that these values\nare data members from this type `AtomicOrder`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic => @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire => tsan.__tsan_acquire(addr),\n            .release => tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst => {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n```\n:::\n\n\n\n\nThis is how basic type inference is done in Zig. If we didn't use the dot character before\nthe values inside this switch statement, then, we would be forced to explicitly write\nthe data types of these values. For example, instead of writing `.release` we would have to\nwrite `AtomicOrder.release`. We would have to do this for every single value\nin this switch statement, and this is a lot of work. That is why type inference\nis commonly used on switch statements in Zig.\n\n\n\n## Type casting {#sec-type-cast}\n\nIn this section, I want to discuss type casting (or, type conversion) with you.\nWe use type casting when we have an object of type \"x\", and we want to convert\nit into an object of type \"y\", i.e. we want to change the data type of the object.\n\nMost languages have a formal way to perform type casting. In Rust for example, we normally\nuse the keyword `as`, and in C, we normally use the type casting syntax, e.g. `(int) x`.\nIn Zig, we use the `@as()` built-in function to cast an object of type \"x\", into\nan object of type \"y\".\n\nThis `@as()` function is the preferred way to perform type conversion (or type casting)\nin Zig. Because it is explicit, and, it also performs the casting only if it\nis unambiguous and safe. To use this function, you just provide the target data type\nin the first argument, and, the object that you want cast as the second argument.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filefe9b6a29a64b.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\nThis is the general way to perform type casting in Zig. But remember, `@as()` works only when casting\nis unambiguous and safe, and there are situations where these assumptions do not hold. For example,\nwhen casting an integer value into a float value, or vice-versa, it is not clear to the compiler\nhow to perform this conversion safely.\n\nTherefore, we need to use specialized \"casting functions\" in such situations.\nFor example, if you want to cast an integer value into a float value, then, you\nshould use the `@floatFromInt()` function. In the inverse scenario, you should use\nthe `@intFromFloat()` function.\n\nIn these functions, you just provide the object that you want to\ncast as input. Then, the target data type of the \"type casting operation\" is determined by\nthe type annotation of the object where you are saving the results.\nIn the example below, we are casting the object `x` into a value of type `f32`,\nbecause the object `y`, which is where we are saving the results, is annotated\nas an object of type `f32`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filefe9b126af3c3.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\nAnother built-in function that is very useful when performing type casting operations is `@ptrCast()`.\nIn essence, we use the `@as()` built-in function when we want to explicit convert (or cast) a Zig value/object\nfrom a type \"x\" to a type \"y\", etc. However, pointers (we are going to discuss pointers\nin more depth in @sec-pointer) are a special type of object in Zig,\ni.e. they are treated differently from \"normal objects\".\n\nEverytime a pointer is involved in some \"type casting operation\" in Zig, the `@ptrCast()` function is used.\nThis function works similarly to `@floatFromInt()`.\nYou just provide the pointer object that you want to cast as input to this function, and the\ntarget data type is, once again, determined by the type annotation of the object where the results are being\nstored.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filefe9b7366fb7.test_0...OKAll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## Modules\n\nWe already talked about what modules are, and also, how to import other modules into\nyour current module via *import statements*. Every Zig module (i.e. a `.zig` file) that you write in your project\nis internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the\nZig Standard Library into our current module.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n```\n:::\n\n\n\n\nWhen we want to access the functions and objects from the standard library, we\nare basically accessing the data members of the struct stored in the `std`\nobject. That is why we use the same syntax that we use in normal structs, with the dot operator (`.`)\nto access the data members and methods of the struct.\n\nWhen this \"import statement\" get's executed, the result of this expression is a struct\nobject that contains the Zig Standard Library modules, global variables, functions, etc.\nAnd this struct object get's saved (or stored) inside the constant object named `std`.\n\n\nTake the [`thread_pool.zig` module from the project `zap`](https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig)[^thread]\nas an example. This module is written as if it was\na big struct. That is why we have a top-level and public `init()` method\nwritten in this module. The idea is that all top-level functions written in this\nmodule are methods from the struct, and all top-level objects and struct declarations\nare data members of this struct. The module is the struct itself.\n\n[^thread]: <https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig>\n\n\nSo you would import and use this module by doing something like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst ThreadPool = @import(\"thread_pool.zig\");\nconst num_cpus = std.Thread.getCpuCount()\n    catch @panic(\"failed to get cpu core count\");\nconst num_threads = std.math.cast(u16, num_cpus)\n    catch std.math.maxInt(u16);\nconst pool = ThreadPool.init(\n    .{ .max_threads = num_threads }\n);\n```\n:::\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Control flow, structs, modules and types\n\nWe have discussed a lot of Zig's syntax in the last chapter,\nespecially in @sec-root-file and @sec-main-file.\nBut we still need to discuss some other very important\nelements of the language. Elements that you will use constantly on your day-to-day\nroutine.\n\nWe begin this chapter by discussing the different keywords and structures\nin Zig related to control flow (e.g. loops and if statements).\nThen, we talk about structs and how they can be used to do some\nbasic Object-Oriented (OOP) patterns in Zig. We also talk about\ntype inference and type casting.\nFinally, we end this chapter by discussing modules, and how they relate\nto structs.\n\n\n\n## Control flow {#sec-zig-control-flow}\n\nSometimes, you need to make decisions in your program. Maybe you need to decide\nwhether or not to execute a specific piece of code. Or maybe,\nyou need to apply the same operation over a sequence of values. These kinds of tasks,\ninvolve using structures that are capable of changing the \"control flow\" of our program.\n\nIn computer science, the term \"control flow\" usually refers to the order in which expressions (or commands)\nare evaluated in a given language or program. But this term is also used to refer\nto structures that are capable of changing this \"evaluation order\" of the commands\nexecuted by a given language/program.\n\nThese structures are better known\nby a set of terms, such as: loops, if/else statements, switch statements, among others. So,\nloops and if/else statements are examples of structures that can change the \"control\nflow\" of our program. The keywords `continue` and `break` are also examples of symbols\nthat can change the order of evaluation, since they can move our program to the next iteration\nof a loop, or make the loop stop completely.\n\n\n### If/else statements\n\nAn if/else statement performs a \"conditional flow operation\".\nA conditional flow control (or choice control) allows you to execute\nor ignore a certain block of commands based on a logical condition.\nMany programmers and computer science professionals also use\nthe term \"branching\" in this case.\nIn essence, an if/else statement allow us to use the result of a logical test\nto decide whether or not to execute a given block of commands.\n\nIn Zig, we write if/else statements by using the keywords `if` and `else`.\nWe start with the `if` keyword followed by a logical test inside a pair\nof parentheses, followed by a pair of curly braces which contains the lines\nof code to be executed in case the logical test returns the value `true`.\n\nAfter that, you can optionally add an `else` statement. To do that, just add the `else`\nkeyword followed by a pair of curly braces, with the lines of code\nto executed in case the logical test defined at `if` returns `false`.\n\nIn the example below, we are testing if the object `x` contains a number\nthat is greater than 10. Judging by the output printed to the console,\nwe know that this logical test returned `false`. Because the output\nin the console is compatible with the line of code present in the\n`else` branch of the if/else statement.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x = 5;\nif (x > 10) {\n    try stdout.print(\n        \"x > 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x <= 10!\\n\", .{}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nx <= 10!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Switch statements {#sec-switch}\n\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust.\nAs you would expect, to write a switch statement in Zig we use the `switch` keyword.\nWe provide the value that we want to \"switch over\" inside a\npair of parentheses. Then, we list the possible combinations (or \"branches\")\ninside a pair of curly braces.\n\nLet's take a look at the code example below. You can see that\nI'm creating an enum type called `Role`. We talk more about enums in @sec-enum.\nBut in summary, this `Role` type is listing different types of roles in a fictitious\ncompany, like `SE` for Software Engineer, `DE` for Data Engineer, `PM` for Product Manager,\netc.\n\nNotice that we are using the value from the `role` object in the\nswitch statement, to discover which exact area we need to store in the `area` variable object.\nAlso notice that we are using type inference inside the switch statement, with the dot character,\nas we are going to describe in @sec-type-inference.\nThis makes the `zig` compiler infer the correct data type of the values (`PM`, `SE`, etc.) for us.\n\nAlso notice that, we are grouping multiple values in the same branch of the switch statement.\nWe just separate each possible value with a comma. For example, if `role` contains either `DE` or `DA`,\nthe `area` variable would contain the value `\"Data & Analytics\"`, instead of `\"Platform\"` or `\"Sales\"`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO => {\n            area = \"Platform\";\n        },\n        .DE, .DA => {\n            area = \"Data & Analytics\";\n        },\n        .KS => {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nPlatform\n```\n\n\n:::\n:::\n\n\n\n\n\n#### Switch statements must exhaust all possibilities\n\nOne very important aspect about switch statements in Zig\nis that they must exhaust all existing possibilities.\nIn other words, all possible values that could be found inside the `order`\nobject must be explicitly handled in this switch statement.\n\nSince the `role` object have type `Role`, the only possible values to\nbe found inside this object are `PM`, `SE`, `DPE`, `PO`, `DE`, `DA` and `KS`.\nThere are no other possible values to be stored in this `role` object.\nThus, the switch statements must have a combination (branch) for each one of these values.\nThis is what \"exhaust all existing possibilities\" means. The switch statement covers\nevery possible case.\n\nTherefore, you cannot write a switch statement in Zig, and leave an edge case\nwith no explicit action to be taken.\nThis is a similar behaviour to switch statements in Rust, which also have to\nhandle all possible cases.\n\n\n\n#### The else branch\n\nTake a look at the `dump_hex_fallible()` function below as an example. This function\ncomes from the Zig Standard Library. More precisely, from the\n[`debug.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/debug.zig)[^debug-mod].\nThere are multiple lines in this function, but I omitted them to focus solely on the\nswitch statement found in this function. Notice that this switch statement has four\npossible cases (i.e. four explicit branches). Also, notice that we used an `else` branch\nin this case.\n\nAn `else` branch in a switch statement works as the \"default branch\".\nWhenever you have multiple cases in your switch statement where\nyou want to apply the exact same action, you can use an `else` branch to do that.\n\n[^debug-mod]: <https://github.com/ziglang/zig/blob/master/lib/std/debug.zig>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' => try writer.writeAll(\"␊\"),\n        '\\r' => try writer.writeAll(\"␍\"),\n        '\\t' => try writer.writeAll(\"␉\"),\n        else => try writer.writeByte('.'),\n    }\n}\n```\n:::\n\n\n\n\nMany programmers would also use an `else` branch to handle a \"not supported\" case.\nThat is, a case that cannot be properly handled by your code, or, just a case that\nshould not be \"fixed\". Therefore, you can use an `else` branch to panic (or raise an error)\nin your program to stop the current execution.\n\nTake the code example below. We can see that, we are handling the cases\nfor the `level` object being either 1, 2, or 3. All other possible cases are not supported by default,\nand, as consequence, we raise a runtime error in such cases through the `@panic()` built-in function.\n\nAlso notice that, we are assigning the result of the switch statement to a new object called `category`.\nThis is another thing that you can do with switch statements in Zig. If a branch\noutputs a value as result, you can store the result value of the switch statement into\na new object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 => \"beginner\",\n    3 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n:::\n\n\n\n\n```\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n```\n\n\n\n#### Using ranges in switch\n\nFurthermore, you can also use ranges of values in switch statements.\nThat is, you can create a branch in your switch statement that is used\nwhenever the input value is within the specified range. These \"range expressions\"\nare created with the operator `...`. It is important\nto emphasize that the ranges created by this operator are\ninclusive on both ends.\n\nFor example, I could easily change the previous code example to support all\nlevels between 0 and 100. Like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 => \"beginner\",\n    26...75 => \"intermediary\",\n    76...100 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nbeginner\n```\n\n\n:::\n:::\n\n\n\n\nThis is neat, and it works with character ranges too. That is, I could\nsimply write `'a'...'z'`, to match any character value that is a\nlowercase letter, and it would work fine.\n\n\n#### Labeled switch statements\n\nIn @sec-blocks we have talked about labeling blocks, and also, about using these labels\nto return a value from the block. Well, from version 0.14.0 and onwards of the `zig` compiler,\nyou can also apply labels over switch statements, which makes it possible to almost implement a\n\"C `goto`\" like pattern.\n\nFor example, if you give the label `xsw` to a switch statement, you can use this\nlabel in conjunction with the `continue` keyword to go back to the beginning of the switch\nstatement. In the example below, the execution goes back to the beginning of the\nswitch statement two times, before ending at the `3` branch.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nxsw: switch (@as(u8, 1)) {\n    1 => {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 => continue :xsw 3,\n    3 => return,\n    4 => {},\n    else => {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n```\n:::\n\n\n\n\n\n### The `defer` keyword {#sec-defer}\n\nWith the `defer` keyword you can register an expression to be executed when you exit the current scope.\nTherefore, this keyword has a similar functionality as the `on.exit()` function from R.\nTake the `foo()` function below as an example. When we execute this `foo()` function, the expression\nthat prints the message \"Exiting function ...\" is getting executed only when the function exits\nits scope.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nAdding some numbers ...\nMultiplying ...\nExiting function ...\n```\n\nTherefore, we can use `defer` to declare an expression that is going to be executed\nwhen your code exits the current scope. Some programmers like to interpret the phrase \"exit of the current scope\"\nas \"the end of the current scope\". But this interpretation might not be entirely correct, depending\non what you consider as \"the end of the current scope\".\n\nI mean, what do you consider as **the end** of the current scope? Is it the closing curly bracket (`}`) of the scope?\nIs it when the last expression in the function get's executed? Is it when the function returns to the previous scope?\nEtc. For example, it would not be correct to interpret the \"exit of the current scope\" as the closing\ncurly bracket of the scope. Because the function might exit from an earlier position than this\nclosing curly bracket (e.g. an error value was generated at a previous line inside the function;\nthe function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\n\nNow, if you remember of what we have discussed in @sec-blocks, there are multiple structures in the language\nthat create their own separate scopes. For/while loops, if/else statements,\nfunctions, normal blocks, etc. This also affects the interpretation of `defer`.\nFor example, if you use `defer` inside a for loop, then, the given expression\nwill be executed everytime this specific for loop exits its own scope.\n\nBefore we continue, is worth emphasizing that the `defer` keyword is an \"unconditional defer\".\nWhich means that the given expression will be executed no matter how the code exits\nthe current scope. For example, your code might exit the current scope because of an error value\nbeing generated, or, because of a return statement, or, a break statement, etc.\n\n\n\n### The `errdefer` keyword {#sec-errdefer1}\n\nOn the previous section, we have discussed the `defer` keyword, which you can use to\nregister an expression to be executed at the exit of the current scope.\nBut this keyword has a brother, which is the `errdefer` keyword. While `defer`\nis an \"unconditional defer\", the `errdefer` keyword is a \"conditional defer\".\nWhich means that the given expression is executed only when you exit the current\nscope on a very specific circumstance.\n\nIn more details, the expression given to `errdefer` is executed only when an error occurs in the current scope.\nTherefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope\nin a normal situation, without errors, the expression given to `errdefer` is not executed.\n\nThis makes the `errdefer` keyword one of the many tools available in Zig for error handling.\nIn this section, we are more concerned with the control flow aspects around `errdefer`.\nBut we are going to discuss `errdefer` later as a error handling tool in @sec-errdefer2.\n\nThe code example below demonstrates three things:\n\n- that `defer` is an \"unconditional defer\", because the given expression get's executed regardless of how the function `foo()` exits its own scope.\n- that `errdefer` is executed because the function `foo()` returned an error value.\n- that `defer` and `errdefer` expressions are executed in a LIFO (*last in, first out*) order.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\nWhen I say that \"defer expressions\" are executed in a LIFO order, what I want to say is that\nthe last `defer` or `errdefer` expressions in the code are the first ones to be executed.\nYou could also interpret this as: \"defer expressions\" are executed from bottom to top, or,\nfrom last to first.\n\nTherefore, if I change the order of the `defer` and `errdefer` expressions, you will notice that\nthe value of `i` that get's printed to the console changes to 1. This doesn't mean that the\n`defer` expression was not executed in this case. This actually means that the `defer` expression\nwas executed only after the `errdefer` expression. The code example below demonstrates this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\n\n\n### For loops\n\nA loop allows you to execute the same lines of code multiple times,\nthus, creating a \"repetition space\" in the execution flow of your program.\nLoops are particularly useful when we want to replicate the same function\n(or the same set of commands) over different inputs.\n\nThere are different types of loops available in Zig. But the most\nessential of them all is probably the *for loop*. A for loop is\nused to apply the same piece of code over the elements of a slice, or, an array.\n\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from\nother languages. You start with the `for` keyword, then, you\nlist the items that you want to iterate\nover inside a pair of parentheses. Then, inside of a pair of pipes (`|`)\nyou should declare an identifier that will serve as your iterator, or,\nthe \"repetition index of the loop\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (items) |value| {\n    // code to execute\n}\n```\n:::\n\n\n\n\nTherefore, instead of using a `(value in items)` syntax,\nin Zig, for loops use the syntax `(items) |value|`. In the example\nbelow, you can see that we are looping through the items\nof the array stored at the object `name`, and printing to the\nconsole the decimal representation of each character in this array.\n\nIf we wanted, we could also iterate through a slice (or a portion) of\nthe array, instead of iterating through the entire array stored in the `name` object.\nJust use a range selector to select the section you want. For example,\nI could provide the expression `name[0..3]` to the for loop, to iterate\njust through the first 3 elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n80 | 101 | 100 | 114 | 111 | \n```\n\n\n:::\n:::\n\n\n\n\nIn the above example we are using the value itself of each\nelement in the array as our iterator. But there are many situations where\nwe need to use an index instead of the actual values of the items.\n\nYou can do that by providing a second set of items to iterate over.\nMore precisely, you provide the range selector `0..` to the for loop. So,\nyes, you can use two different iterators at the same time in a for\nloop in Zig.\n\nBut remember from @sec-assignments that, every object\nyou create in Zig must be used in some way. So if you declare two iterators\nin your for loop, you must use both iterators inside the for loop body.\nBut if you want to use just the index iterator, and not use the \"value iterator\",\nthen, you can discard the value iterator by maching the\nvalue items to the underscore character, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n:::\n\n\n\n\n```\n0 | 1 | 2 | 3 | 4 |\n```\n\n\n### While loops\n\nA while loop is created from the `while` keyword. A `for` loop\niterates through the items of an array, but a `while` loop\nwill loop continuously, and infinitely, until a logical test\n(specified by you) becomes false.\n\nYou start with the `while` keyword, then, you define a logical\nexpression inside a pair of parentheses, and the body of the\nloop is provided inside a pair of curly braces, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\nYou can also specify the increment expression to be used at the beginning of a while loop.\nTo do that, we write the increment expression inside a pair of parentheses after a colon character (`:`).\nThe code example below demonstrates this other pattern.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\n### Using `break` and `continue`\n\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using\nthe keywords `break` and `continue`, respectively. The `while` loop presented in the next code example is,\nat first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to `true`.\nBut what makes this `while` loop stop when the `i` object reaches the count\n10? It is the `break` keyword!\n\nInside the while loop, we have an if statement that is constantly checking if the `i` variable\nis equal to 10. Since we are incrementing the value of `i` at each iteration of the\nwhile loop, this `i` object will eventually be equal to 10, and when it is, the if statement\nwill execute the `break` expression, and, as a result, the execution of the while loop is stopped.\n\nNotice the use of the `expect()` function from the Zig Standard Library after the while loop.\nThis `expect()` function is an \"assert\" type of function.\nThis function checks if the logical test provided is equal to true. If so, the function do nothing.\nOtherwise (i.e. the logical test is equal to false), the function raises an assertion error.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nEverything worked!\n```\n\n\n:::\n:::\n\n\n\n\nSince this code example was executed successfully by the `zig` compiler,\nwithout raising any errors, we known that, after the execution of the while loop,\nthe `i` object is equal to 10. Because if it wasn't equal to 10, an error would have\nbeen raised by `expect()`.\n\nNow, in the next example, we have a use case for\nthe `continue` keyword. The if statement is constantly\nchecking if the current index is a multiple of 2. If\nit is, we jump to the next iteration of the loop.\nOtherwise, the loop just prints the current index to the console.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 3 | 5 | \n```\n\n\n:::\n:::\n\n\n\n\n\n\n## Function parameters are immutable {#sec-fun-pars}\n\nWe have already discussed a lot of the syntax behind function declarations in @sec-root-file and @sec-main-file.\nBut I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig.\nIn summary, function parameters are immutable in Zig.\n\nTake the code example below, where we declare a simple function that just tries to add\nsome amount to the input integer, and returns the result back. If you look closely\nat the body of this `add2()` function, you will notice that we try\nto save the result back into the `x` function argument.\n\nIn other words, this function not only uses the value that it received through the function argument\n`x`, but it also tries to change the value of this function argument, by assigning the addition result\ninto `x`. However, function arguments in Zig are immutable. You cannot change their values, or, you\ncannot assign values to them inside the body's function.\n\nThis is the reason why, the code example below does not compile successfully. If you try to compile\nthis code example, you will get a compile error message about \"trying to change the value of a\nimmutable (i.e. constant) object\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n\n\n```\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n```\n\n\n### A free optimization\n\nIf a function argument receives as input an object whose data type is\nany of the primitive types that we have listed in @sec-primitive-data-types,\nthis object is always passed by value to the function. In other words, this object\nis copied into the function stack frame.\n\nHowever, if the input object have a more complex data type, for example, it might\nbe a struct instance, or an array, or an union value, etc., in cases like that, the `zig` compiler\nwill take the liberty of deciding for you which strategy is best. Thus, the `zig` compiler will\npass your object to the function either by value, or by reference. The compiler will always\nchoose the strategy that is faster for you.\nThis optimization that you get for free is possible only because function arguments are\nimmutable in Zig.\n\n\n### How to overcome this barrier\n\nThere are some situations where you might need to change the value of your function argument\ndirectly inside the function's body. This happens more often when we are passing\nC structs as inputs to Zig functions.\n\nIn a situation like this, you can overcome this barrier by using a pointer. In other words,\ninstead of passing a value as input to the argument, you can pass a \"pointer to value\" instead.\nYou can change the value that the pointer points to, by dereferencing it.\n\nTherefore, if we take our previous `add2()` example, we can change the value of the\nfunction argument `x` inside the function's body by marking the `x` argument as a\n\"pointer to a `u32` value\" (i.e. `*u32` data type), instead of a `u32` value.\nBy making it a pointer, we can finally alter the value of this function argument directly inside\nthe body of the `add2()` function. You can see that the code example below compiles successfully.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n```\n:::\n\n\n\n\n```\nResult: 6\n```\n\n\nEven in this code example above, the `x` argument is still immutable. Which means that the pointer itself is immutable.\nTherefore, you cannot change the memory address that it points to. However, you can dereference the pointer\nto access the value that it points to, and also, to change this value, if you need to.\n\n\n\n\n\n## Structs and OOP {#sec-structs-and-oop}\n\nZig is a language more closely related to C (which is a procedural language),\nthan it is to C++ or Java (which are object-oriented languages). Because of that, you do not\nhave advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or\nclass inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\n\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C.\nYou give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can\nalso register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object\nthat you create with this new type, will always have these methods available and associated with them.\n\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which\nis used to construct (or, to instantiate) every object of this particular class, and we also have\na destructor method (or a destructor function), which is the function responsible for destroying\nevery object of this class.\n\nIn Zig, we normally declare the constructor and the destructor methods\nof our structs, by declaring an `init()` and a `deinit()` methods inside the struct.\nThis is just a naming convention that you will find across the entire Zig Standard Library.\nSo, in Zig, the `init()` method of a struct is normally the constructor method of the class represented by this struct.\nWhile the `deinit()` method is the method used for destroying an existing instance of that struct.\n\nThe `init()` and `deinit()` methods are both used extensively in Zig code, and you will see both of\nthem being used when we talk about allocators in @sec-allocators.\nBut, as another example, let's build a simple `User` struct to represent a user of some sort of system.\n\nIf you look at the `User` struct below, you can see the `struct` keyword.\nNotice the data members of this struct: `id`, `name` and `email`. Every data member has its\ntype explicitly annotated, with the colon character (`:`) syntax that we described earlier in @sec-root-file.\nBut also notice that every line in the struct body that describes a data member, ends with a comma character (`,`).\nSo every time you declare a data member in your Zig code, always end the line with a comma character, instead\nof ending it with the traditional semicolon character (`;`).\n\nNext, we have registered an `init()` function as a method\nof this `User` struct. This `init()` method is the constructor method that we will use to instantiate\nevery new `User` object. That is why this `init()` function returns a new `User` object as result.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    pub fn init(id: u64,\n                name: []const u8,\n                email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    pub fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\npedro\n```\n\n\n:::\n:::\n\n\n\n\nThe `pub` keyword plays an important role in struct declarations, and OOP in Zig.\nEvery method that you declare in your struct that is marked with the keyword `pub`,\nbecomes a public method of this particular struct.\n\nSo every method that you create inside your struct, is, at first, a private method\nof that struct. Meaning that, this method can only be called from within this\nstruct. But, if you mark this method as public, with the keyword `pub`, then,\nyou can call the method directly from an instance of the `User` struct.\n\nIn other words, the functions marked by the keyword `pub`\nare members of the public API of that struct.\nFor example, if I did not mark the `print_name()` method as public,\nthen, I could not execute the line `u.print_name()`. Because I would\nnot be authorized to call this method directly in my code.\n\n\n\n### Anonymous struct literals {#sec-anonymous-struct-literals}\n\nYou can declare a struct object as a literal value. When we do that, we normally specify the\ndata type of this struct literal by writing its data type just before the opening curly brace.\nFor example, I could write a struct literal value of the type `User` that we have defined\nin the previous section like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n```\n:::\n\n\n\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a\nstruct literal, but not specify explicitly the type of this particular struct.\nAn anonymous struct is written by using the syntax `.{}`. So, we essentially\nreplaced the explicit type of the struct literal with a dot character (`.`).\n\nAs we described in @sec-type-inference, when you put a dot before a struct literal,\nthe type of this struct literal is automatically inferred by the `zig` compiler.\nIn essence, the `zig` compiler will look for some hint of what is the type of that struct.\nThis hint can be the type annotation of a function argument,\nor the return type annotation of the function that you are using, or the type annotation\nof an existing object.\nIf the compiler does find such type annotation, it will use this\ntype in your literal struct.\n\nAnonymous structs are very commonly used as inputs to function arguments in Zig.\nOne example that you have seen already constantly, is the `print()`\nfunction from the `stdout` object.\nThis function takes two arguments.\nThe first argument, is a template string, which should\ncontain string format specifiers in it, which tells how the values provided\nin the second argument should be printed into the message.\n\nWhile the second argument is a struct literal that lists the values\nto be printed into the template message specified in the first argument.\nYou normally want to use an anonymous struct literal here, so that the\n`zig` compiler do the job of specifying the type of this particular\nanonymous struct for you.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello, world!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Struct declarations must be constant\n\nTypes in Zig must be `const` or `comptime` (we are going to talk more about comptime in @sec-comptime).\nWhat this means is that you cannot create a new data type, and mark it as variable with the `var` keyword.\nSo struct declarations are always constant. You cannot declare a new struct type using the `var` keyword.\nIt must be `const`.\n\nIn the `Vec3` example below, this declaration is allowed because I'm using the `const` keyword\nto declare this new data type.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n```\n:::\n\n\n\n\n\n### The `self` method argument {#sec-self-arg}\n\nIn every language that have OOP, when we declare a method of some class or struct, we\nusually declare this method as a function that has a `self` argument.\nThis `self` argument is the reference to the object itself from which the method\nis being called from.\n\nIt is not mandatory to use this `self` argument. But why would you not use this `self` argument?\nThere is no reason to not use it. Because the only way to get access to the data stored in the\ndata members of your struct is to access them through this `self` argument.\nIf you don't need to use the data in the data members of your struct inside your method, you very likely don't need\na method. You can just declare this logic as a simple function, outside of your\nstruct declaration.\n\n\nTake the `Vec3` struct below. Inside this `Vec3` struct we declared a method named `distance()`.\nThis method calculates the distance between two `Vec3` objects, by following the distance\nformula in euclidean space. Notice that this `distance()` method takes two `Vec3` objects\nas input, `self` and `other`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n```\n:::\n\n\n\n\n\nThe `self` argument corresponds to the `Vec3` object from which this `distance()` method\nis being called from. While the `other` is a separate `Vec3` object that is given as input\nto this method. In the example below, the `self` argument corresponds to the object\n`v1`, because the `distance()` method is being called from the `v1` object,\nwhile the `other` argument corresponds to the object `v2`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n```\n:::\n\n\n\n\n```\nDistance: 3.3970575502926055\n```\n\n\n\n### About the struct state\n\nSometimes you don't need to care about the state of your struct object. Sometimes, you just need\nto instantiate and use the objects, without altering their state. You can notice that when you have methods\ninside your struct declaration that might use the values that are present in the data members, but they\ndo not alter the values in these data members of the struct in anyway.\n\nThe `Vec3` struct that was presented in @sec-self-arg is an example of that.\nThis struct have a single method named `distance()`, and this method does use the values\npresent in all three data members of the struct (`x`, `y` and `z`). But at the same time,\nthis method does not change the values of these data members at any point.\n\nAs a result of that, when we create `Vec3` objects we usually create them as\nconstant objects, like the `v1` and `v2` objects presented in @sec-self-arg.\nWe can create them as variable objects with the `var` keyword,\nif we want to. But because the methods of this `Vec3` struct do not change\nthe state of the objects in any point, it's unnecessary to mark them\nas variable objects.\n\nBut why? Why am I talking about this here? It's because the `self` argument\nin the methods is affected depending on whether the\nmethods present in a struct change or don't change the state of the object itself.\nMore specifically, when you have a method in a struct that changes the state\nof the object (i.e. change the value of a data member), the `self` argument\nin this method must be annotated in a different manner.\n\nAs I described in @sec-self-arg, the `self` argument in methods of\na struct is the argument that receives as input the object from which the method\nwas called from. We usually annotate this argument in the methods by writing `self`,\nfollowed by the colon character (`:`), and the data type of the struct to which\nthe method belongs to (e.g. `User`, `Vec3`, etc.).\n\nIf we take the `Vec3` struct that we defined in the previous section as an example,\nwe can see in the `distance()` method that this `self` argument is annotated as\n`self: Vec3`. Because the state of the `Vec3` object is never altered by this\nmethod.\n\nBut what if we do have a method that alters the state of the object, by altering the\nvalues of its data members, how should we annotate `self` in this instance? The answer is:\n\"we should annotate `self` as a pointer of `x`, instead of just `x`\".\nIn other words, you should annotate `self` as `self: *x`, instead of annotating it\nas `self: x`.\n\nIf we create a new method inside the `Vec3` object that, for example, expands the\nvector by multiplying its coordinates by a factor of two, then, we need to follow\nthis rule specified in the previous paragraph. The code example below demonstrates\nthis idea:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n```\n:::\n\n\n\n\nNotice in the code example above that we have added a new method\nto our `Vec3` struct named `twice()`. This method doubles the\ncoordinate values of our vector object. In the\ncase of the `twice()` method, we annotated the `self` argument as `*Vec3`,\nindicating that this argument receives a pointer (or a reference, if you prefer to call it this way)\nto a `Vec3` object as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n```\n:::\n\n\n\n\n```\nDoubled: 8.4\n```\n\n\n\nNow, if you change the `self` argument in this `twice()` method to `self: Vec3`, like in the\n`distance()` method, you will get the compiler error exposed below as result. Notice that this\nerror message is showing a line from the `twice()` method body,\nindicating that you cannot alter the value of the `x` data member.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n```\n:::\n\n\n\n\n```\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\n```\n\nThis error message indicates that the `x` data member belongs to a constant object,\nand, because of that, it cannot be changed. Ultimately, this error message\nis telling us that the `self` argument is constant.\n\nIf you take some time, and think hard about this error message, you will understand it.\nYou already have the tools to understand why we are getting this error message.\nWe have talked about it already in @sec-fun-pars.\nSo remember, every function argument is immutable in Zig, and `self`\nis no exception to this rule.\n\nIn this example, we marked the `v3` object as a variable object.\nBut this does not matter. Because it is not about the input object, it is about\nthe function argument.\n\nThe problem begins when we try to alter the value of `self` directly, which is a function argument,\nand, every function argument is immutable by default. You may ask yourself how can we overcome\nthis barrier, and once again, the solution was also discussed in @sec-fun-pars.\nWe overcome this barrier, by explicitly marking the `self` argument as a pointer.\n\n\n::: {.callout-note}\nIf a method of your `x` struct alters the state of the object, by\nchanging the value of any data member, then, remember to use `self: *x`,\ninstead of `self: x` in the function signature of this method.\n:::\n\n\nYou could also interpret the content discussed in this section as:\n\"if you need to alter the state of your `x` struct object in one of its methods,\nyou must explicitly pass the `x` struct object by reference to the `self` argument of this method\".\n\n\n\n## Type inference {#sec-type-inference}\n\nZig is a strongly typed language. But, there are some situations\nwhere you don't have to explicitly write the type of every single object in your source code,\nas you would expect from a traditional strongly typed language, such as C and C++.\n\nIn some situations, the `zig` compiler can use type inference to solve the data types for you, easing some of\nthe burden that you carry as a developer.\nThe most common way this happens is through function arguments that receive struct objects\nas input.\n\nIn general, type inference in Zig is done by using the dot character (`.`).\nEverytime you see a dot character written before a struct literal, or before an enum value, or something like that,\nyou know that this dot character is playing a special party in this place. More specifically, it is\ntelling the `zig` compiler something along the lines of: \"Hey! Can you infer the type of this\nvalue for me? Please!\". In other words, this dot character is playing a similar role as the `auto` keyword in C++.\n\nI gave you some examples of this in @sec-anonymous-struct-literals, where we used anonymous struct literals.\nAnonymous struct literals are, struct literals that use type inference to\ninfer the exact type of this particular struct literal.\nThis type inference is done by looking for some minimal hint of the correct data type to be used.\nYou could say that the `zig` compiler looks for any neighbouring type annotation that might tell it\nwhat the correct type would be.\n\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in @sec-switch).\nI also gave some other examples of type inference in @sec-switch, where we were inferring the data types of enum values listed inside\nof switch statements (e.g. `.DE`).\nBut as another example, take a look at this `fence()` function reproduced below,\nwhich comes from the [`atomic.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig)[^fence-fn]\nof the Zig Standard Library.\n\n[^fence-fn]: <https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig>.\n\nThere are a lot of things in this function that we haven't talked about yet, such as:\nwhat `comptime` means? `inline`? `extern`?\nLet's just ignore all of these things, and focus solely on the switch statement\nthat is inside this function.\n\nWe can see that this switch statement uses the `order` object as input. This `order`\nobject is one of the inputs of this `fence()` function, and we can see in the type annotation,\nthat this object is of type `AtomicOrder`. We can also see a bunch of values inside the\nswitch statements that begin with a dot character, such as `.release` and `.acquire`.\n\nBecause these weird values contain a dot character before them, we are asking the `zig`\ncompiler to infer the types of these values inside the switch statement. Then, the `zig`\ncompiler is looking into the current context where these values are being used, and it is\ntrying to infer the types of these values.\n\nSince they are being used inside a switch statement, the `zig` compiler looks into the type\nof the input object given to the switch statement, which is the `order` object in this case.\nBecause this object have type `AtomicOrder`, the `zig` compiler infers that these values\nare data members from this type `AtomicOrder`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic => @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire => tsan.__tsan_acquire(addr),\n            .release => tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst => {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n```\n:::\n\n\n\n\nThis is how basic type inference is done in Zig. If we didn't use the dot character before\nthe values inside this switch statement, then, we would be forced to explicitly write\nthe data types of these values. For example, instead of writing `.release` we would have to\nwrite `AtomicOrder.release`. We would have to do this for every single value\nin this switch statement, and this is a lot of work. That is why type inference\nis commonly used on switch statements in Zig.\n\n\n\n## Type casting {#sec-type-cast}\n\nIn this section, I want to discuss type casting (or, type conversion) with you.\nWe use type casting when we have an object of type \"x\", and we want to convert\nit into an object of type \"y\", i.e. we want to change the data type of the object.\n\nMost languages have a formal way to perform type casting. In Rust for example, we normally\nuse the keyword `as`, and in C, we normally use the type casting syntax, e.g. `(int) x`.\nIn Zig, we use the `@as()` built-in function to cast an object of type \"x\", into\nan object of type \"y\".\n\nThis `@as()` function is the preferred way to perform type conversion (or type casting)\nin Zig. Because it is explicit, and, it also performs the casting only if it\nis unambiguous and safe. To use this function, you just provide the target data type\nin the first argument, and, the object that you want cast as the second argument.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file10b91234368fa.test_0...OKAll 1 tests passe\n  ed.\n```\n\n\n:::\n:::\n\n\n\n\nThis is the general way to perform type casting in Zig. But remember, `@as()` works only when casting\nis unambiguous and safe, and there are situations where these assumptions do not hold. For example,\nwhen casting an integer value into a float value, or vice-versa, it is not clear to the compiler\nhow to perform this conversion safely.\n\nTherefore, we need to use specialized \"casting functions\" in such situations.\nFor example, if you want to cast an integer value into a float value, then, you\nshould use the `@floatFromInt()` function. In the inverse scenario, you should use\nthe `@intFromFloat()` function.\n\nIn these functions, you just provide the object that you want to\ncast as input. Then, the target data type of the \"type casting operation\" is determined by\nthe type annotation of the object where you are saving the results.\nIn the example below, we are casting the object `x` into a value of type `f32`,\nbecause the object `y`, which is where we are saving the results, is annotated\nas an object of type `f32`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file10b9130ae9221.test_0...OKAll 1 tests passe\n  ed.\n```\n\n\n:::\n:::\n\n\n\n\nAnother built-in function that is very useful when performing type casting operations is `@ptrCast()`.\nIn essence, we use the `@as()` built-in function when we want to explicit convert (or cast) a Zig value/object\nfrom a type \"x\" to a type \"y\", etc. However, pointers (we are going to discuss pointers\nin more depth in @sec-pointer) are a special type of object in Zig,\ni.e. they are treated differently from \"normal objects\".\n\nEverytime a pointer is involved in some \"type casting operation\" in Zig, the `@ptrCast()` function is used.\nThis function works similarly to `@floatFromInt()`.\nYou just provide the pointer object that you want to cast as input to this function, and the\ntarget data type is, once again, determined by the type annotation of the object where the results are being\nstored.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file10b914c434861.test_0...OKAll 1 tests passe\n  ed.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## Modules\n\nWe already talked about what modules are, and also, how to import other modules into\nyour current module via *import statements*. Every Zig module (i.e. a `.zig` file) that you write in your project\nis internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the\nZig Standard Library into our current module.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n```\n:::\n\n\n\n\nWhen we want to access the functions and objects from the standard library, we\nare basically accessing the data members of the struct stored in the `std`\nobject. That is why we use the same syntax that we use in normal structs, with the dot operator (`.`)\nto access the data members and methods of the struct.\n\nWhen this \"import statement\" get's executed, the result of this expression is a struct\nobject that contains the Zig Standard Library modules, global variables, functions, etc.\nAnd this struct object get's saved (or stored) inside the constant object named `std`.\n\n\nTake the [`thread_pool.zig` module from the project `zap`](https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig)[^thread]\nas an example. This module is written as if it was\na big struct. That is why we have a top-level and public `init()` method\nwritten in this module. The idea is that all top-level functions written in this\nmodule are methods from the struct, and all top-level objects and struct declarations\nare data members of this struct. The module is the struct itself.\n\n[^thread]: <https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig>\n\n\nSo you would import and use this module by doing something like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst ThreadPool = @import(\"thread_pool.zig\");\nconst num_cpus = std.Thread.getCpuCount()\n    catch @panic(\"failed to get cpu core count\");\nconst num_threads = std.math.cast(u16, num_cpus)\n    catch std.math.maxInt(u16);\nconst pool = ThreadPool.init(\n    .{ .max_threads = num_threads }\n);\n```\n:::\n",
     "supporting": [
       "03-structs_files"
     ],
diff --git a/_freeze/Chapters/05-pointers/execute-results/html.json b/_freeze/Chapters/05-pointers/execute-results/html.json
index 45caa69d..0cdd4021 100644
--- a/_freeze/Chapters/05-pointers/execute-results/html.json
+++ b/_freeze/Chapters/05-pointers/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "cdc04b429a135bfc11ee404aac1b9919",
+  "hash": "9520ae65eeada418ccd4d4ca5f8b6f7a",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Pointers and Optionals {#sec-pointer}\n\nOn our next project we are going to build a HTTP server from scratch.\nBut in order to do that, we need to learn more about pointers and how they work in Zig.\nPointers in Zig are similar to pointers in C. But they come with some extra advantages in Zig.\n\nA pointer is an object that contains a memory address. This memory address is the address where\na particular value is stored in memory. It can be any value. Most of the times,\nit is a value that comes from another object (or variable) present in our code.\n\nIn the example below, I'm creating two objects (`number` and `pointer`).\nThe `pointer` object contains the memory address where the value of the `number` object\n(the number 5) is stored. So, that is a pointer in a nutshell. It is a memory\naddress that points to a particular existing value in the memory. You could\nalso say, that, the `pointer` object points to the memory address where the `number` object is\nstored.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number: u8 = 5;\nconst pointer = &number;\n_ = pointer;\n```\n:::\n\n\n\n\nWe create a pointer object in Zig by using the `&` operator. When you put this operator\nbefore the name of an existing object, you get the memory address of this object as result.\nWhen you store this memory address inside a new object, this new object becomes a pointer object.\nBecause it stores a memory address.\n\nPeople mostly use pointers as an alternative way to access a particular value.\nFor example, I can use the `pointer` object to access the value stored by\nthe `number` object. This operation of accessing the value that the\npointer \"points to\" is normally called of *dereferencing the pointer*.\nWe can dereference a pointer in Zig by using the `*` method of the pointer object. Like in the example\nbelow, where we take the number 5 pointed by the `pointer` object,\nand double it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number: u8 = 5;\nconst pointer = &number;\nconst doubled = 2 * pointer.*;\nstd.debug.print(\"{d}\\n\", .{doubled});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n10\n```\n\n\n:::\n:::\n\n\n\n\n```\n10\n```\n\nThis syntax to dereference the pointer is nice. Because we can easily chain it with\nmethods of the value pointed by the pointer. We can use the `User` struct that we have\ncreated at @sec-structs-and-oop as an example. If you comeback to that section,\nyou will see that this struct have a method named `print_name()`.\n\nSo, for example, if we have an user object, and a pointer that points to this user object,\nwe can use the pointer to access this user object, and, at the same time, call the method `print_name()`\non it, by chaining the dereference method (`*`) with the `print_name()` method. Like in the\nexample below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst u = User.init(1, \"pedro\", \"email@gmail.com\");\nconst pointer = &u;\ntry pointer.*.print_name();\n```\n:::\n\n\n\n\n```\npedro\n```\n\nWe can also use pointers to effectively alter the value of an object.\nFor example, I could use the `pointer` object to set\nthe value of the object `number` to 6, like in the example below.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n6\n```\n\n\n:::\n:::\n\n\n\n\n\nTherefore, as I mentioned earlier, people use pointers as an alternative way to access a particular value.\nAnd they use it especially when they do not want to \"move\" these values around. There are situations where,\nyou want to access a particular value in a different scope (i.e. a different location) of your code,\nbut you do not want to \"move\" this value to this new scope (or location) that you are in.\n\nThis matters especially if this value is big in size. Because if it is, then,\nmoving this value becomes an expensive operation to do.\nThe computer will have to spend a considerable amount of time\ncopying this value to this new location.\n\nTherefore, many programmers prefer to avoid this heavy operation of copying the value\nto the new location, by accessing this value through pointers.\nWe are going to talk more about this \"moving operation\" over the next sections.\nFor now, just keep in mind that avoiding this \"move operation\" is\none of main reasons why pointers are used in programming languages.\n\n\n\n\n\n## Constant objects vs variable objects {#sec-pointer-var}\n\nYou can have a pointer that points to a constant object, or, a pointer that points to a variable object.\nBut regardless of who this pointer is, a pointer **must always respect the characteristics of the object that it points to**.\nAs a consequence, if the pointer points to a constant object, then, you cannot use this pointer\nto change the value that it points to. Because it points to a value that is constant. As we discussed at @sec-assignments, you cannot\nchange a value that is constant.\n\nFor example, if I have a `number` object, which is constant, I cannot execute\nthe expression below where I'm trying to change the value of `number` to 6 through\nthe `pointer` object. As demonstrated below, when you try to do something\nlike that, you get a compile time error:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number = 5;\nconst pointer = &number;\npointer.* = 6;\n```\n:::\n\n\n\n\n```\np.zig:6:12: error: cannot assign to constant\n    pointer.* = 6;\n```\n\nIf I change the `number` object to be a variable object, by introducing the `var` keyword,\nthen, I can successfully change the value of this object through a pointer, as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n6\n```\n\n\n:::\n:::\n\n\n\n\nYou can see this relationship between \"constant versus variable\" on the data type of\nyour pointer object. In other words, the data type of a pointer object already gives you\nsome clues about whether the value that it points to is constant or not.\n\nWhen a pointer object points to a constant value, then, this pointer have a data type `*const T`,\nwhich means \"a pointer to a constant value of type `T`\".\nIn contrast, if the pointer points to a variable value, then, the type of the pointer is usually `*T`, which is\nsimply \"a pointer to a value of type `T`\".\nHence, whenever you see a pointer object whose data type is in the format `*const T`, then,\nyou know that you cannot use this pointer to change the value that it points to.\nBecause this pointer points to a constant value of type `T`.\n\n\nWe have talked about the value pointed by the pointer being constant or not,\nand the consequences that arises from it. But, what about the pointer object itself? I mean, what happens\nif the pointer object itself is constant or not? Think about it.\nWe can have a constant pointer that points to a constant value.\nBut we can also have a variable pointer that points to a constant value. And vice-versa.\n\nUntil this point, the `pointer` object was always constant,\nbut what this means for us? What is the consequence of the\n`pointer` object being constant? The consequence is that\nwe cannot change the pointer object, because it is constant. We can use the\npointer object in multiple ways, but we cannot change the\nmemory address that is inside this pointer object.\n\nHowever, if we mark the `pointer` object as a variable object,\nthen, we can change the memory address pointed by this `pointer` object.\nThe example below demonstrates that. Notice that the object pointed\nby the `pointer` object changes from `c1` to `c2`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c1: u8 = 5;\nconst c2: u8 = 6;\nvar pointer = &c1;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\npointer = &c2;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\n```\n:::\n\n\n\n\n```\n5\n6\n```\n\nThus, by setting the `pointer` object to a `var` or `const` object,\nyou specify if the memory address contained in this pointer object can change or not\nin your program. On the other side, you can change the value pointed by the pointer,\nif, and only if this value is stored in a variable object. If this value\nis in a constant object, then, you cannot change this value through a pointer.\n\n\n## Types of pointer\n\nIn Zig, there are two types of pointers [@zigdocs], which are:\n\n- single-item pointer (`*`);\n- many-item pointer (`[*]`);\n\n\nSingle-item pointer objects are objects whose data types are in the format `*T`.\nSo, for example, if an object have a data type `*u32`, it means that, this\nobject contains a single-item pointer that points to an unsigned 32-bit integer value.\nAs another example, if an object have type `*User`, then, it contains\na single-item pointer to an `User` value.\n\nIn contrast, many-item pointers are objects whose data types are in the format `[*]T`.\nNotice that the star symbol (`*`) is now inside a pair of brackets (`[]`). If the star\nsymbol is inside a pair of brackets, you know that this object is a many-item pointer.\n\nWhen you apply the `&` operator over an object, you will always get a single-item pointer.\nMany-item pointers are more of a \"internal type\" of the language, more closely\nrelated to slices. So, when you deliberately create a pointer with the `&` operator,\nyou always get a single-item pointer as result.\n\n\n\n## Pointer arithmetic\n\nPointer arithmetic is available in Zig, and they work the same way they work in C.\nWhen you have a pointer that points to an array, the pointer usually points to\nthe first element in the array, and you can use pointer arithmetic to\nadvance this pointer and access the other elements in the array.\n\n\nNotice in the example below, that initially, the `ptr` object was pointing\nto the first element in the array `ar`. But then, I started to walk through the array, by advancing\nthe pointer with simple pointer arithmetic.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [_]i32{1,2,3,4};\nvar ptr = &ar;\ntry stdout.print(\"{d}\\n\", .{ptr.*});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr.*});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr.*});\n```\n:::\n\n\n\n\n```\n1\n2\n3\n```\n\nAlthough you can create a pointer to an array like that, and\nstart to walk through this array by using pointer arithmetic,\nin Zig, we prefer to use slices, which were presented at @sec-arrays.\n\nBehind the hood, slices already are pointers,\nand they also come with the `len` property, which indicates\nhow many elements are in the slice. This is good because the `zig` compiler\ncan use it to check for potential buffer overflows, and other problems like that.\n\nAlso, you don't need to use pointer arithmetic to walk through the elements\nof a slice. You can simply use the `slice[index]` syntax to directly access\nany element you want in the slice.\nAs I mentioned at @sec-arrays, you can get a slice from an array by using\na range selector inside brackets. In the example below, I'm creating\na slice (`sl`) that covers the entire `ar` array. I can access any\nelement of `ar` from this slice, and, the slice itself already is a pointer\nbehind the hood.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [_]i32{1,2,3,4};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\n\n## Optionals and Optional Pointers\n\nLet's talk about optionals and how they relate to pointers in Zig.\nBy default, objects in Zig are **non-nullable**. This means that, in Zig,\nyou can safely assume that any object in your source code is not null.\n\nThis is a powerful feature of Zig when you compare it to the developer experience in C.\nBecause in C, any object can be null at any point, and, as consequence, a pointer in C\nmight point to a null value. This is a common source of undefined behaviour in C.\nWhen programmers work with pointers in C, they have to constantly check if\ntheir pointers are pointing to null values or not.\n\nIf for some reason, your Zig code produces a null value somewhere, and, this null\nvalue ends up in an object that is non-nullable, a runtime error is always\nraised by your Zig program. Take the program below as an example.\nThe `zig` compiler can see the `null` value at compile time, and, as result,\nit raises a compile time error. But, if a `null` value is raised during\nruntime, a runtime error is also raised by the Zig program, with a\n\"attempt to use null value\" message.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nnumber = null;\n```\n:::\n\n\n\n```\np5.zig:5:14: error: expected type 'u8',\n        found '@TypeOf(null)'\n    number = null;\n             ^~~~\n```\n\n\nYou don't get this type of safety in C.\nIn C, you don't get warnings or errors about null values being produced in your program.\nIf for some reason, your code produces a null value in C, most of the times, you end up getting a segmentation fault error\nas result, which can mean many things.\nThat is why programmers have to constantly check for null values in C.\n\nPointers in Zig are also, by default, **non-nullable**. This is another amazing\nfeature in Zig. So, you can safely assume that any pointer that you create in\nyour Zig code is pointing to a non-null value.\nTherefore, you don't have this heavy work of checking if the pointers you create\nin Zig are pointing to a null value.\n\n\n### What are optionals?\n\nOk, we know now that all objects are non-nullable by default in Zig.\nBut what if we actually need to use an object that might receive a null value?\nHere is where optionals come in.\n\nAn optional object in Zig is an object that can be null.\nTo mark an object as optional, we use the `?` operator. When you put\nthis `?` operator right before the data type of an object, you transform\nthis data type into an optional data type, and the object becomes an optional object.\n\nTake the snippet below as an example. We are creating a new variable object\ncalled `num`. This object have the data type `?i32`, which means that,\nthis object contains either a signed 32-bit integer (`i32`), or, a null value.\nBoth alternatives are valid values to the `num` object.\nThat is why, I can actually change the value of this object to null, and,\nno errors are raised by the `zig` compiler, as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: ?i32 = 5;\nnum = null;\n```\n:::\n\n\n\n\n### Optional pointers\n\nYou can also mark a pointer object as an optional pointer, meaning that,\nthis object contains either a null value, or, a pointer that points to a value.\nWhen you mark a pointer as optional, the data type of this pointer object\nbecomes `?*const T` or `?*T`, depending if the value pointed by the pointer\nis a constant value or not. The `?` identifies the object as optional, while\nthe `*` identifies it as a pointer object.\n\nIn the example below, we are creating a variable object named `num`, and an\noptional pointer object named `ptr`. Notice that the data type of the object\n`ptr` indicates that it is either a null value, or a pointer to an `i32` value.\nAlso, notice that the pointer object (`ptr`) can be marked as optional, even if\nthe object `num` is not optional.\n\nWhat this code tells us is that, the `num` variable will never contain a null value.\nThis variable will always contain a valid `i32` value. But in contrast, the `ptr` object might contain either a null\nvalue, or, a pointer to an `i32` value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: i32 = 5;\nvar ptr: ?*i32 = &num;\nptr = null;\nnum = 6;\n```\n:::\n\n\n\n\nBut what happens if we turn the table, and mark the `num` object as optional,\ninstead of the pointer object. If we do that, then, the pointer object is\nnot optional anymore. It would be a similar (although different) result. Because then, we would have\na pointer to an optional value. In other words, a pointer to a value that is either a\nnull value, or, a not-null value.\n\nIn the example below, we are recreating this idea. Now, the `ptr` object\nhave a data type of `*?i32`, instead of `?*i32`. Notice that the `*` symbol comes before of `?`\nthis time. So now, we have a pointer that points to a value that is either null\n, or, a signed 32-bit integer.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: ?i32 = 5;\n// ptr have type `*?i32`, instead of `?*i32`.\nconst ptr = &num;\n_ = ptr;\n```\n:::\n\n\n\n\n\n### Null handling in optionals {#sec-null-handling}\n\nWhen you have an optional object in your Zig code, you have to explicitly handle\nthe possibility of this object being null. It is like error-handling with `try` and `catch`.\nIn Zig you also have to handle null values like if they were a type of error.\n\nWe can do that, by using either:\n\n- an if statement, like you would do in C.\n- the `orelse` keyword.\n- unwrap the optional value with the `?` method.\n\nWhen you use an if statement, you use a pair of pipes\nto unwrap the optional value, and use this \"unwrapped object\"\ninside the if block.\nUsing the example below as a reference, if the object `num` is null,\nthen, the code inside the if statement is not executed. Otherwise,\nthe if statement will unwrap the object `num` into the `not_null_num`\nobject. This `not_null_num` object is guaranteed to be not null inside\nthe scope of the if statement.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst num: ?i32 = 5;\nif (num) |not_null_num| {\n    try stdout.print(\"{d}\\n\", .{not_null_num});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n5\n```\n\n\n:::\n:::\n\n\n\n\nNow, the `orelse` keyword behaves like a binary operator. You connect two expressions with this keyword.\nOn the left side of `orelse`, you provide the expression that might result\nin a null value, and on the right side of `orelse`, you provide another expression\nthat will not result in a null value.\n\nThe idea behind the `orelse` keyword is: if the expression on the left side\nresult in a not-null value, then, this not-null value is used. However,\nif this expression on the left side result in a null value, then, the value\nof the expression on the right side is used instead.\n\nLooking at the example below, since the `x` object is currently null, the\n`orelse` decided to use the alternative value, which is the number 15.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x: ?i32 = null;\nconst dbl = (x orelse 15) * 2;\ntry stdout.print(\"{d}\\n\", .{dbl});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n30\n```\n\n\n:::\n:::\n\n\n\n\nYou can use the if statement or the `orelse` keyword, when you want to\nsolve (or deal with) this null value. However, if there is no clear solution\nto this null value, and the most logic and sane path is to simply panic\nand raise a loud error in your program when this null value is encountered,\nyou can use the `?` method of your optional object.\n\nIn essence, when you use this `?` method, the optional object is unwrapped.\nIf a not-null value is found in the optional object, then, this not-null value is used.\nOtherwise, the `unreachable` keyword is used. You can read more about this\n[`unreacheable` keyword at the official documentation](https://ziglang.org/documentation/master/#unreachable)[^un-docs].\nBut in essence, when you build your Zig source code using the build modes `ReleaseSafe` or `Debug`, this\n`unreacheable` keyword causes the program to panic and raise an error during runtime,\nlike in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn return_null(n: i32) ?i32 {\n    if (n == 5) return null;\n    return n;\n}\n\npub fn main() !void {\n    const x: i32 = 5;\n    const y: ?i32 = return_null(x);\n    try stdout.print(\"{d}\\n\", .{y.?});\n}\n```\n:::\n\n\n\n\n```\nthread 12767 panic: attempt to use null value\np7.zig:12:34: 0x103419d in main (p7):\n    try stdout.print(\"{d}\\n\", .{y.?});\n                                 ^\n```\n\n\n[^un-docs]: <https://ziglang.org/documentation/master/#unreachable>.\n\n\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Pointers and Optionals {#sec-pointer}\n\nOn our next project we are going to build a HTTP server from scratch.\nBut in order to do that, we need to learn more about pointers and how they work in Zig.\nPointers in Zig are similar to pointers in C. But they come with some extra advantages in Zig.\n\nA pointer is an object that contains a memory address. This memory address is the address where\na particular value is stored in memory. It can be any value. Most of the times,\nit is a value that comes from another object (or variable) present in our code.\n\nIn the example below, I'm creating two objects (`number` and `pointer`).\nThe `pointer` object contains the memory address where the value of the `number` object\n(the number 5) is stored. So, that is a pointer in a nutshell. It is a memory\naddress that points to a particular existing value in the memory. You could\nalso say, that, the `pointer` object points to the memory address where the `number` object is\nstored.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number: u8 = 5;\nconst pointer = &number;\n_ = pointer;\n```\n:::\n\n\n\n\nWe create a pointer object in Zig by using the `&` operator. When you put this operator\nbefore the name of an existing object, you get the memory address of this object as result.\nWhen you store this memory address inside a new object, this new object becomes a pointer object.\nBecause it stores a memory address.\n\nPeople mostly use pointers as an alternative way to access a particular value.\nFor example, I can use the `pointer` object to access the value stored by\nthe `number` object. This operation of accessing the value that the\npointer \"points to\" is normally called of *dereferencing the pointer*.\nWe can dereference a pointer in Zig by using the `*` method of the pointer object. Like in the example\nbelow, where we take the number 5 pointed by the `pointer` object,\nand double it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number: u8 = 5;\nconst pointer = &number;\nconst doubled = 2 * pointer.*;\nstd.debug.print(\"{d}\\n\", .{doubled});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n10\n```\n\n\n:::\n:::\n\n\n\n\n\nThis syntax to dereference the pointer is nice. Because we can easily chain it with\nmethods of the value pointed by the pointer. We can use the `User` struct that we have\ncreated at @sec-structs-and-oop as an example. If you comeback to that section,\nyou will see that this struct have a method named `print_name()`.\n\nSo, for example, if we have an user object, and a pointer that points to this user object,\nwe can use the pointer to access this user object, and, at the same time, call the method `print_name()`\non it, by chaining the dereference method (`*`) with the `print_name()` method. Like in the\nexample below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst u = User.init(1, \"pedro\", \"email@gmail.com\");\nconst pointer = &u;\ntry pointer.*.print_name();\n```\n:::\n\n\n\n\n```\npedro\n```\n\nWe can also use pointers to effectively alter the value of an object.\nFor example, I could use the `pointer` object to set\nthe value of the object `number` to 6, like in the example below.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n6\n```\n\n\n:::\n:::\n\n\n\n\n\nTherefore, as I mentioned earlier, people use pointers as an alternative way to access a particular value.\nAnd they use it especially when they do not want to \"move\" these values around. There are situations where,\nyou want to access a particular value in a different scope (i.e. a different location) of your code,\nbut you do not want to \"move\" this value to this new scope (or location) that you are in.\n\nThis matters especially if this value is big in size. Because if it is, then,\nmoving this value becomes an expensive operation to do.\nThe computer will have to spend a considerable amount of time\ncopying this value to this new location.\n\nTherefore, many programmers prefer to avoid this heavy operation of copying the value\nto the new location, by accessing this value through pointers.\nWe are going to talk more about this \"moving operation\" over the next sections.\nFor now, just keep in mind that avoiding this \"move operation\" is\none of main reasons why pointers are used in programming languages.\n\n\n\n\n\n## Constant objects vs variable objects {#sec-pointer-var}\n\nYou can have a pointer that points to a constant object, or, a pointer that points to a variable object.\nBut regardless of who this pointer is, a pointer **must always respect the characteristics of the object that it points to**.\nAs a consequence, if the pointer points to a constant object, then, you cannot use this pointer\nto change the value that it points to. Because it points to a value that is constant. As we discussed at @sec-assignments, you cannot\nchange a value that is constant.\n\nFor example, if I have a `number` object, which is constant, I cannot execute\nthe expression below where I'm trying to change the value of `number` to 6 through\nthe `pointer` object. As demonstrated below, when you try to do something\nlike that, you get a compile time error:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number = 5;\nconst pointer = &number;\npointer.* = 6;\n```\n:::\n\n\n\n\n```\np.zig:6:12: error: cannot assign to constant\n    pointer.* = 6;\n```\n\nIf I change the `number` object to be a variable object, by introducing the `var` keyword,\nthen, I can successfully change the value of this object through a pointer, as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n6\n```\n\n\n:::\n:::\n\n\n\n\nYou can see this relationship between \"constant versus variable\" on the data type of\nyour pointer object. In other words, the data type of a pointer object already gives you\nsome clues about whether the value that it points to is constant or not.\n\nWhen a pointer object points to a constant value, then, this pointer have a data type `*const T`,\nwhich means \"a pointer to a constant value of type `T`\".\nIn contrast, if the pointer points to a variable value, then, the type of the pointer is usually `*T`, which is\nsimply \"a pointer to a value of type `T`\".\nHence, whenever you see a pointer object whose data type is in the format `*const T`, then,\nyou know that you cannot use this pointer to change the value that it points to.\nBecause this pointer points to a constant value of type `T`.\n\n\nWe have talked about the value pointed by the pointer being constant or not,\nand the consequences that arises from it. But, what about the pointer object itself? I mean, what happens\nif the pointer object itself is constant or not? Think about it.\nWe can have a constant pointer that points to a constant value.\nBut we can also have a variable pointer that points to a constant value. And vice-versa.\n\nUntil this point, the `pointer` object was always constant,\nbut what this means for us? What is the consequence of the\n`pointer` object being constant? The consequence is that\nwe cannot change the pointer object, because it is constant. We can use the\npointer object in multiple ways, but we cannot change the\nmemory address that is inside this pointer object.\n\nHowever, if we mark the `pointer` object as a variable object,\nthen, we can change the memory address pointed by this `pointer` object.\nThe example below demonstrates that. Notice that the object pointed\nby the `pointer` object changes from `c1` to `c2`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c1: u8 = 5;\nconst c2: u8 = 6;\nvar pointer = &c1;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\npointer = &c2;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\n```\n:::\n\n\n\n\n```\n5\n6\n```\n\nThus, by setting the `pointer` object to a `var` or `const` object,\nyou specify if the memory address contained in this pointer object can change or not\nin your program. On the other side, you can change the value pointed by the pointer,\nif, and only if this value is stored in a variable object. If this value\nis in a constant object, then, you cannot change this value through a pointer.\n\n\n## Types of pointer\n\nIn Zig, there are two types of pointers [@zigdocs], which are:\n\n- single-item pointer (`*`);\n- many-item pointer (`[*]`);\n\n\nSingle-item pointer objects are objects whose data types are in the format `*T`.\nSo, for example, if an object have a data type `*u32`, it means that, this\nobject contains a single-item pointer that points to an unsigned 32-bit integer value.\nAs another example, if an object have type `*User`, then, it contains\na single-item pointer to an `User` value.\n\nIn contrast, many-item pointers are objects whose data types are in the format `[*]T`.\nNotice that the star symbol (`*`) is now inside a pair of brackets (`[]`). If the star\nsymbol is inside a pair of brackets, you know that this object is a many-item pointer.\n\nWhen you apply the `&` operator over an object, you will always get a single-item pointer.\nMany-item pointers are more of a \"internal type\" of the language, more closely\nrelated to slices. So, when you deliberately create a pointer with the `&` operator,\nyou always get a single-item pointer as result.\n\n\n\n## Pointer arithmetic\n\nPointer arithmetic is available in Zig, and they work the same way they work in C.\nWhen you have a pointer that points to an array, the pointer usually points to\nthe first element in the array, and you can use pointer arithmetic to\nadvance this pointer and access the other elements in the array.\n\n\nNotice in the example below, that initially, the `ptr` object was pointing\nto the first element in the array `ar`. But then, I started to walk through the array, by advancing\nthe pointer with simple pointer arithmetic.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [_]i32{1,2,3,4};\nvar ptr = &ar;\ntry stdout.print(\"{d}\\n\", .{ptr.*});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr.*});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr.*});\n```\n:::\n\n\n\n\n```\n1\n2\n3\n```\n\nAlthough you can create a pointer to an array like that, and\nstart to walk through this array by using pointer arithmetic,\nin Zig, we prefer to use slices, which were presented at @sec-arrays.\n\nBehind the hood, slices already are pointers,\nand they also come with the `len` property, which indicates\nhow many elements are in the slice. This is good because the `zig` compiler\ncan use it to check for potential buffer overflows, and other problems like that.\n\nAlso, you don't need to use pointer arithmetic to walk through the elements\nof a slice. You can simply use the `slice[index]` syntax to directly access\nany element you want in the slice.\nAs I mentioned at @sec-arrays, you can get a slice from an array by using\na range selector inside brackets. In the example below, I'm creating\na slice (`sl`) that covers the entire `ar` array. I can access any\nelement of `ar` from this slice, and, the slice itself already is a pointer\nbehind the hood.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [_]i32{1,2,3,4};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\n\n## Optionals and Optional Pointers\n\nLet's talk about optionals and how they relate to pointers in Zig.\nBy default, objects in Zig are **non-nullable**. This means that, in Zig,\nyou can safely assume that any object in your source code is not null.\n\nThis is a powerful feature of Zig when you compare it to the developer experience in C.\nBecause in C, any object can be null at any point, and, as consequence, a pointer in C\nmight point to a null value. This is a common source of undefined behaviour in C.\nWhen programmers work with pointers in C, they have to constantly check if\ntheir pointers are pointing to null values or not.\n\nIf for some reason, your Zig code produces a null value somewhere, and, this null\nvalue ends up in an object that is non-nullable, a runtime error is always\nraised by your Zig program. Take the program below as an example.\nThe `zig` compiler can see the `null` value at compile time, and, as result,\nit raises a compile time error. But, if a `null` value is raised during\nruntime, a runtime error is also raised by the Zig program, with a\n\"attempt to use null value\" message.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nnumber = null;\n```\n:::\n\n\n\n```\np5.zig:5:14: error: expected type 'u8',\n        found '@TypeOf(null)'\n    number = null;\n             ^~~~\n```\n\n\nYou don't get this type of safety in C.\nIn C, you don't get warnings or errors about null values being produced in your program.\nIf for some reason, your code produces a null value in C, most of the times, you end up getting a segmentation fault error\nas result, which can mean many things.\nThat is why programmers have to constantly check for null values in C.\n\nPointers in Zig are also, by default, **non-nullable**. This is another amazing\nfeature in Zig. So, you can safely assume that any pointer that you create in\nyour Zig code is pointing to a non-null value.\nTherefore, you don't have this heavy work of checking if the pointers you create\nin Zig are pointing to a null value.\n\n\n### What are optionals?\n\nOk, we know now that all objects are non-nullable by default in Zig.\nBut what if we actually need to use an object that might receive a null value?\nHere is where optionals come in.\n\nAn optional object in Zig is an object that can be null.\nTo mark an object as optional, we use the `?` operator. When you put\nthis `?` operator right before the data type of an object, you transform\nthis data type into an optional data type, and the object becomes an optional object.\n\nTake the snippet below as an example. We are creating a new variable object\ncalled `num`. This object have the data type `?i32`, which means that,\nthis object contains either a signed 32-bit integer (`i32`), or, a null value.\nBoth alternatives are valid values to the `num` object.\nThat is why, I can actually change the value of this object to null, and,\nno errors are raised by the `zig` compiler, as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: ?i32 = 5;\nnum = null;\n```\n:::\n\n\n\n\n### Optional pointers\n\nYou can also mark a pointer object as an optional pointer, meaning that,\nthis object contains either a null value, or, a pointer that points to a value.\nWhen you mark a pointer as optional, the data type of this pointer object\nbecomes `?*const T` or `?*T`, depending if the value pointed by the pointer\nis a constant value or not. The `?` identifies the object as optional, while\nthe `*` identifies it as a pointer object.\n\nIn the example below, we are creating a variable object named `num`, and an\noptional pointer object named `ptr`. Notice that the data type of the object\n`ptr` indicates that it is either a null value, or a pointer to an `i32` value.\nAlso, notice that the pointer object (`ptr`) can be marked as optional, even if\nthe object `num` is not optional.\n\nWhat this code tells us is that, the `num` variable will never contain a null value.\nThis variable will always contain a valid `i32` value. But in contrast, the `ptr` object might contain either a null\nvalue, or, a pointer to an `i32` value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: i32 = 5;\nvar ptr: ?*i32 = &num;\nptr = null;\nnum = 6;\n```\n:::\n\n\n\n\nBut what happens if we turn the table, and mark the `num` object as optional,\ninstead of the pointer object. If we do that, then, the pointer object is\nnot optional anymore. It would be a similar (although different) result. Because then, we would have\na pointer to an optional value. In other words, a pointer to a value that is either a\nnull value, or, a not-null value.\n\nIn the example below, we are recreating this idea. Now, the `ptr` object\nhave a data type of `*?i32`, instead of `?*i32`. Notice that the `*` symbol comes before of `?`\nthis time. So now, we have a pointer that points to a value that is either null\n, or, a signed 32-bit integer.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: ?i32 = 5;\n// ptr have type `*?i32`, instead of `?*i32`.\nconst ptr = &num;\n_ = ptr;\n```\n:::\n\n\n\n\n\n### Null handling in optionals {#sec-null-handling}\n\nWhen you have an optional object in your Zig code, you have to explicitly handle\nthe possibility of this object being null. It is like error-handling with `try` and `catch`.\nIn Zig you also have to handle null values like if they were a type of error.\n\nWe can do that, by using either:\n\n- an if statement, like you would do in C.\n- the `orelse` keyword.\n- unwrap the optional value with the `?` method.\n\nWhen you use an if statement, you use a pair of pipes\nto unwrap the optional value, and use this \"unwrapped object\"\ninside the if block.\nUsing the example below as a reference, if the object `num` is null,\nthen, the code inside the if statement is not executed. Otherwise,\nthe if statement will unwrap the object `num` into the `not_null_num`\nobject. This `not_null_num` object is guaranteed to be not null inside\nthe scope of the if statement.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst num: ?i32 = 5;\nif (num) |not_null_num| {\n    try stdout.print(\"{d}\\n\", .{not_null_num});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n5\n```\n\n\n:::\n:::\n\n\n\n\nNow, the `orelse` keyword behaves like a binary operator. You connect two expressions with this keyword.\nOn the left side of `orelse`, you provide the expression that might result\nin a null value, and on the right side of `orelse`, you provide another expression\nthat will not result in a null value.\n\nThe idea behind the `orelse` keyword is: if the expression on the left side\nresult in a not-null value, then, this not-null value is used. However,\nif this expression on the left side result in a null value, then, the value\nof the expression on the right side is used instead.\n\nLooking at the example below, since the `x` object is currently null, the\n`orelse` decided to use the alternative value, which is the number 15.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x: ?i32 = null;\nconst dbl = (x orelse 15) * 2;\ntry stdout.print(\"{d}\\n\", .{dbl});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n30\n```\n\n\n:::\n:::\n\n\n\n\nYou can use the if statement or the `orelse` keyword, when you want to\nsolve (or deal with) this null value. However, if there is no clear solution\nto this null value, and the most logic and sane path is to simply panic\nand raise a loud error in your program when this null value is encountered,\nyou can use the `?` method of your optional object.\n\nIn essence, when you use this `?` method, the optional object is unwrapped.\nIf a not-null value is found in the optional object, then, this not-null value is used.\nOtherwise, the `unreachable` keyword is used. You can read more about this\n[`unreacheable` keyword at the official documentation](https://ziglang.org/documentation/master/#unreachable)[^un-docs].\nBut in essence, when you build your Zig source code using the build modes `ReleaseSafe` or `Debug`, this\n`unreacheable` keyword causes the program to panic and raise an error during runtime,\nlike in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn return_null(n: i32) ?i32 {\n    if (n == 5) return null;\n    return n;\n}\n\npub fn main() !void {\n    const x: i32 = 5;\n    const y: ?i32 = return_null(x);\n    try stdout.print(\"{d}\\n\", .{y.?});\n}\n```\n:::\n\n\n\n\n```\nthread 12767 panic: attempt to use null value\np7.zig:12:34: 0x103419d in main (p7):\n    try stdout.print(\"{d}\\n\", .{y.?});\n                                 ^\n```\n\n\n[^un-docs]: <https://ziglang.org/documentation/master/#unreachable>.\n\n\n",
+    "supporting": [
+      "05-pointers_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/09-data-structures/execute-results/html.json b/_freeze/Chapters/09-data-structures/execute-results/html.json
index 4675c1a3..d7ca70b5 100644
--- a/_freeze/Chapters/09-data-structures/execute-results/html.json
+++ b/_freeze/Chapters/09-data-structures/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "3788497b9fd5f45d000ca7f61478a997",
+  "hash": "cabd5fbe8584b5427f83c698f124df64",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Data Structures\n\nIn this chapter, I want to present the most common Data Structures that are available from\nthe Zig Standard Library, especially `ArrayList` and also `HashMap`. These are generic Data Structures\nthat you can use to store and control any type of data that is produced by your application.\n\n## Dynamic Arrays {#sec-dynamic-array}\n\nIn high level languages, arrays are usually dynamic. They can easily grow\nin size when they have to, and you don't need to worry about it.\nIn contrast, arrays in low level languages are usually static by default.\nThis is the reality of C, C++, Rust and also Zig. Static arrays were presented at\n@sec-arrays, but in this section, we are going to talk about dynamic arrays in Zig.\n\nDynamic arrays are simply arrays that can grow in size during the runtime\nof your program. Most low level languages have some implementation of\na dynamic array in their standard library. C++ have `std::vector`, Rust have `Vec`,\nand Zig have `std.ArrayList`.\n\nThe `std.ArrayList` struct provides a contiguous and growable array for you.\nIt works like any other dynamic array, it allocates a contiguous block of memory, and when this block have no space left,\n`ArrayList` allocates another contiguous and bigger block of memory, copies the\nelements to this new location, and erases (or frees) the previous block of memory.\n\n\n### Capacity vs Length\n\nWhen we talk about dynamic arrays, we usually have two similar concepts that\nare very essential to how a dynamic array works behind the hood.\nThese concepts are *capacity* and *length*. In some contexts, especially\nin C++, *length* is also called of *size*.\n\nAlthough they look similar, these concepts represent different things\nin the context of a dynamic array. *Capacity* is the number of items (or elements)\nthat your dynamic array can currently hold without the need to allocate more memory.\n\nIn contrast, the *length* refers to how many elements in the array\nare currently being used, or, in other words, how many elements in this array\nthat you have assigned a value to. Every dynamic array works around\na block of allocated memory, which represents an array with total capacity for $n$ elements.\nHowever, only a portion of these $n$ elements are being used most of the time. This portion\nof $n$ is the *length* of the array. So every time you append a new value\nto the array, you are incrementing its *length* by one.\n\nThis means that a dynamic array usually works with an extra margin, or, an extra space\nwhich is currently empty, but it is waiting and ready to be used. This \"extra space\"\nis essentially the difference between *capacity* and *length*. *Capacity* represents\nthe total number of elements that the array can hold without the need to re-allocate\nor re-expand the array, while the *length* represents how much of this capacity\nis currently being used to hold/store values.\n\n@fig-capacity-length presents this idea visually. Notice that, at first,\nthe capacity of the array is greater than the length of the array.\nSo, the dynamic array have extra space that is currently empty, but it\nis ready to receive a value to be stored.\n\n![Difference between capacity and length in a dynamic array](./../Figures/dynamic-array.png){#fig-capacity-length}\n\nWe can also see at @fig-capacity-length that, when *length* and *capacity* are equal, it means that the array have no space left.\nWe have reached the ceiling of our capacity, and because of that, if we want to store more values\nin this array, we need to expand it. We need to get a bigger space that can hold more values\nthan what we currently have.\n\nA dynamic array works by expanding the underlying array, whenever the *length* becomes equal\nto the *capacity* of the array. It basically allocates a new contiguous block of memory that is bigger\nthan the previous one, then, it copies all values that are currently being stored to this new\nlocation (i.e. this new block of memory), then, it frees the previous block of\nmemory. At the end of this process, the new underlying array have a bigger *capacity*, and, therefore,\nthe *length* becomes, once again, smaller than the *capacity* of the array.\n\nThis is the cycle of an dynamic array. Notice that, throughout this cycle, the *capacity* is always\neither equal to or higher than the *length* of the array. If youh have an `ArrayList` object (let's suppose\nyou named it `buffer`), you can check the current capacity of your array by accessing the `capacity`\nattribute of your `ArrayList` object, while the current *length* of it is available at the `items.len`\nattribute.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// Check capacity\nbuffer.capacity;\n// Check length\nbuffer.items.len;\n```\n:::\n\n\n\n\n\n### Creating an `ArrayList` object\n\nIn order to use `ArrayList`, you must provide an allocator object to it.\nRemember, Zig does not have a default memory allocator. And as I described at @sec-allocators, all memory\nallocations must be done by an allocator object that you define, that\nyou have control over. In our example here, I'm going to use\na general purpose allocator, but you can use any other allocator\nof your preference.\n\nWhen you initialize an `ArrayList` object, you must provide the data type of the elements of\nthe array. In other words, this defines the type of data that this array (or container) will\nstore. Therefore, if I provide the `u8` type to it, then, I will create a dynamic\narray of `u8` values. However, if I provide a struct that I have defined instead, like the struct `User`\nfrom @sec-structs-and-oop, then, a dynamic array of `User` values\nwill be created. In the example below, with the expression `ArrayList(u8)` we\nare creating a dynamic array of `u8` values.\n\nAfter you provide the data type of the elements of the array, you can initialize\nan `ArrayList` object by either using the `init()` or the `initCapacity()` methods.\nThe former method receives only the allocator object\nas input, while the latter method receives both the allocator object and a capacity number as inputs.\nWith the latter method, you not only initialize the struct, but you\nalso set the starting capacity of the allocated array.\n\nUsing the `initCapacity()` method is the preferred way to initialize your dynamic array.\nBecause reallocations, or, in other words, the process of expanding the capacity of the array,\nis always a high cost operation. You should take any possible opportunity to avoid reallocations in\nyour array. If you know how much space your array needs to occupy at the beginning,\nyou should always use `initCapacity()` to create your dynamic array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n```\n:::\n\n\n\n\n\nIn the example above, the `buffer` object starts as an array of 100 elements. If this\n`buffer` object needs to create more space to accomodate more elements during the runtime of your program, the `ArrayList`\ninternals will perform the necessary actions for you automatically.\nAlso notice the `deinit()` method being used to destroy the `buffer` object at the\nend of the current scope, by freeing all the memory that was allocated for the dynamic\narray stored in this `buffer` object.\n\n\n### Adding new elements to the array\n\nNow that we have created our dynamic array, we can start to use it. You can append (a.k.a \"add\")\nnew values to this array by using the `append()` method. This method works the same way\nas the `append()` method from a Python list, or, the `emplace_back()` method from `std::vector` of C++.\nYou provide a single value to this method, and the method appends this value to the array.\n\nYou can also use the `appendSlice()` method to append multiple values at once. You provide\na slice (slices were described at @sec-arrays) to this method, and the method adds all values present\nin this slice to your dynamic array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry buffer.append('H');\ntry buffer.append('e');\ntry buffer.append('l');\ntry buffer.append('l');\ntry buffer.append('o');\ntry buffer.appendSlice(\" World!\");\n```\n:::\n\n\n\n\n### Removing elements from the array {#sec-dynamic-array-remove}\n\nYou can use the `pop()` method to \"pop\" or remove\nthe last element in the array. Is worth noting that this method\ndo not change the capacity of the array. It just deletes or erases\nthe last value stored in the array.\n\nAlso, this method returns as result the value that got deleted. That is, you can\nuse this method to both get the last value in the array, and also, remove\nit from the array. It is a \"get and remove value\" type of method.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exclamation_mark = buffer.pop();\n```\n:::\n\n\n\n\nNow, if you want to remove specific elements from specific positions\nof your array, you can use the `orderedRemove()` method from your\n`ArrayList` object. With this method, you can provide an index as input,\nthen, the method will delete the value that is at this index in the array.\nYou are effectively reducing the *length* of the array everytime you execute\nan `orderedRemove()` operation.\n\nIn the example below, we first create an `ArrayList` object, and we fill it\nwith numbers. Then, we use `orderedRemove()` to remove the value at\nindex 3 in the array, two consecutive times.\n\nAlso, notice that we are assigning the result of `orderedRemove()` to the\nunderscore character. So we are discarding the result value of this method.\nThe `orderedRemove()` method returns the value that got deleted, in a similar\nstyle to the `pop()` method.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n\nfor (0..10) |i| {\n    const index: u8 = @intCast(i);\n    try buffer.append(index);\n}\n\nstd.debug.print(\n    \"{any}\\n\", .{buffer.items}\n);\n_ = buffer.orderedRemove(3);\n_ = buffer.orderedRemove(3);\n\nstd.debug.print(\"{any}\\n\", .{buffer.items});\nstd.debug.print(\"{any}\\n\", .{buffer.items.len});\n```\n:::\n\n\n\n\n```\n{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }\n{ 0, 1, 2, 5, 6, 7, 8, 9 }\n8\n```\n\nOne key characteristic about `orderedRemove()` is that it preserves the order\nof the values in the array. So, it deletes the value that you asked it to\nremove, but it also makes sure that the order of the values that remain in the array\nstay the same as before.\n\nNow, if you don't care about the order of the values, for example, maybe you want to treat\nyour dynamic array as a set of values, like the `std::unordered_set`\nstructure from C++, you can use the `swapRemove()` method instead. This method\nworks similarly to the `orderedRemove()` method. You give an index to this\nmethod, then, it deletes the value that is at this index in the array.\nBut this method does not preserve the original order of the values that remain\nin the array. As a result, `swapRemove()` is, in general, faster than `orderedRemove()`.\n\n\n### Inserting elements at specific indexes\n\nWhen you need to insert values in the middle of your array,\ninstead of just appending them to the end of the array, you need to use\nthe `insert()` and `insertSlice()` methods, instead of\nthe `append()` and `appendSlice()` methods.\n\nThese two methods work very similarly to `insert()` and `insert_range()`\nfrom the C++ `std::vector` class. You provide an index to these methods,\nand they insert the values that you provide at that index in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 10);\ndefer buffer.deinit();\n\ntry buffer.appendSlice(\"My Pedro\");\ntry buffer.insert(4, '3');\ntry buffer.insertSlice(2, \" name\");\nfor (buffer.items) |char| {\n    try stdout.print(\"{c}\", .{char});\n}\n```\n:::\n\n\n\n\n```\nMy name P3edro\n```\n\n\n### Conclusion\n\nIf you feel the lack of some other method, I recommend\nyou to read the [official documentation for the `ArrayListAligned`](https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned)[^zig-array2]\nstruct, which describes most of the methods available\nthrough the `ArrayList` object.\n\nYou will notice that there is a lot of other methods in this page that\nI did not described here, and I recommend you to explore these methods,\nand understand how they work.\n\n[^zig-array2]: <https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned>\n\n\n\n## Maps or HashTables {#sec-maps-hashtables}\n\nSome professionals know this type of data structure by different terms, like \"map\",\n\"hashmap\" or \"associative arrays\". But the most common term used is *hashtable*.\nEvery programming language normally have some implementation of a hashtable in their\nstandard libraries. Python have `dict()`, C++ have `std::map` and `std::unordered_map`, Rust\nhave `HashMap`, Javascript have `Object()` and `Map()`, etc.\n\n\n\n### What is a hashtable?\n\nA hashtable is a data structure based on key-value pairs.\nYou provide a key and a value to this structure, then, the hashtable will store\nthe input value at a location that can be identified by the input\nkey that you provided.\nIt does that by using an underlying array and a hash function.\nThese two components are essential to how a hashtable works.\n\nUnder the hood, the hashtable contains an array. This array is where the values\nare stored, and the elements of this array are usually called of *buckets*.\nSo the values that you provide to the hashtable are stored inside buckets,\nand you access each bucket by using an index.\n\nWhen you provide a key to a hashtable, it passes this key to the\nhash function. This hash function uses some sort of hashing algorithm to transform\nthis key into an index. This index is actually an array index. It is a position\nin the underlying array of the hashtable.\nThis is how a key identifies a specific position (or location) inside the hashtable\nstructure.\n\nTherefore, you provide a key to the hashtable, and this key identifies a specific location\ninside the hashtable, then, the hashtable takes the input value that you provided,\nand stores this value in the location identified by this input key.\nYou could say that the key maps to the value stored in the hashtable. You find\nthe value, by using the key that identifies the location where the value is stored.\nThe @fig-hashtable presents this process visually.\n\n\n![A diagram of a Hashtable. Source: Wikipedia, the free encyclopedia.](./../Figures/hashtable.svg){#fig-hashtable}\n\n\nThe operation described in the previous paragraph is normally called an *insertion* operation.\nBecause you are inserting new values into the hashtable.\nBut there are other types of operations in hashtables such as *delete* and *lookup*.\nDelete is self describing, it is when you delete (or remove) a value from the hashtable.\nWhile lookup corresponds to when you look at a value that is stored in\nthe hashtable, by using the key that identifies the location where this value is stored.\n\nSometimes, instead of storing the values directly, the underlying array of the hashtable might be an array of pointers,\ni.e. the buckets of the array stores pointers that points to the value,\nor also, may be an array of linked lists.\nThese cases are common on hashtables that allows duplicate keys, or, in other words,\non hashtables that effectively handle \"collisions\" that may arise from the hash function.\n\nDuplicate keys, or this \"collision\" thing that I'm talking about, is when you have two different keys\nthat points to the same location (i.e. to the same index)\nin the underlying array of the hashtable. This might happen depending on the characteristics of the hash function\nthat is being used in the hashtable. Some implementations of the hashtable will actively deal with collisions,\nmeaning that, they will handle this case in some way. For example, the hashtable\nmight transform all buckets into linked lists. Because with a linked list you can store\nmultiple values into a single bucket.\n\nThere are different techniques to handle collisions in hashtables, which I will not describe\nin this book, because it is not our main scope here. But you can find a good description of\nsome of the most common techniques at the Wikipedia page of hashtables [@wikipedia_hashtables].\n\n\n### Hashtables in Zig {#sec-hashmap}\n\nThe Zig Standard Library provides different implementations of a hashtable.\nEach implementation have its own cons and pros, which we will\ndiscuss later on, and all of them are available through the `std.hash_map` module.\n\nThe `HashMap` struct is a general-purpose hashtable,\nwhich have very fast operations (lookup, insertion, delete), and also,\nquite high load factors for low memory usage. You can create and provide a context object\nto the `HashMap` constructor. This context object allows you to tailor\nthe behaviour of the hashtable itself, because you can\nprovide a hash function implementation to be used by the hashtable\nthrough this context object.\n\nBut let's not worry about this context object now, because it is meant to be used\nby \"experts in the field of hashtables\". Since we are most likely not\nexperts in this field, we are going to take the easy way to create\na hashtable. Which is by using the `AutoHashMap()` function.\n\n\nThis `AutoHashMap()` function is essentially a \"create a hashtable object that uses the default settings\"\ntype of function. It automatically chooses a context object, and, therefore, a hash function implementation,\nfor you. This function receives two data types as input, the first input is the data type of the keys\nthat will be used in this hashtable, while the second input is the data type of the data that will be\nstored inside the hashtable, that is, the data type of the values to be stored.\n\nIn the example below, we are providing the data type `u32` in the first argument, and `u16` in the second argument of this\nfunction. This means that we are going to use `u32` values as keys in this hashtable, while `u16` values are the actual values\nthat are going to be stored into this hashtable.\nAt the end of this process, the `hash_table` object contains a `HashMap` object\nthat uses the default settings and context.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n    std.debug.print(\n        \"Value at key 50050: {d}\\n\",\n        .{hash_table.get(50050).?}\n    );\n\n    if (hash_table.remove(57709)) {\n        std.debug.print(\n            \"Value at key 57709 successfully removed!\\n\",\n            .{}\n        );\n    }\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n}\n```\n:::\n\n\n\n\n```\nN of values stored: 3\nValue at key 50050: 55\nValue at key 57709 successfully removed!\nN of values stored: 2\n```\n\nYou can add/put new values into the hashtable by using the `put()` method. The first argument\nis the key to be used, and the second argument is the actual value that you want to store inside\nthe hashtable. In the example below, we first add the value 89 using the key 54321, next, we add\nthe value 55 using the key 50050, etc.\n\nNotice that we have used the method `count()` to see how many values are currently stored in the\nhashtable. After that, we also use the `get()` method to access (or look) at the value stored in\nthe position identified by the key 500050. The output of this `get()` method is an optional value.\nThis is why we use the `?` method at the end to get the actual value.\n\nAlso notice that we can remove (or delete) values from the hashtable by using the `remove()` method.\nYou provide the key that identifies the value that you want to delete, then, the method will\ndelete this value and return a `true` value as output. This `true` value essentially tells us\nthat the method successfully deleted the value.\n\nBut this delete operation might not be always successful. For example, you might provide the wrong\nkey to this method. I mean, maybe you provide\n(either intentionally or unintentionally) a key that points to an empty bucket,\ni.e. a bucket that still doesn't have a value in it.\nIn this case, the `remove()` method would return a `false` value.\n\n\n\n### Iterating through the hashtable\n\nIterating through the keys and values that are currently being stored in\nthe hashtable is a very common necessity.\nYou can do that in Zig by using an iterator object that can iterate\nthrough the elements of your hashtable object.\n\nThis iterator object works like any other iterator object that you would\nfind in languages such as C++ and Rust. It is basically a pointer object\nthat points to some value in the container, and has a `next()` method\nthat you can use to navigate (or iterate) through the values in the\ncontainer.\n\nYou can create such iterator object by using the `iterator()` method of the hashtable object.\nThis method returns an iterator object, from which you can use the `next()` method in conjunction\nwith a while loop to iterate through the elements of your hashtable. The `next()` method returns an optional\n`Entry` value, and therefore, you must unwrap this optional value to get the actual `Entry` value\nfrom which you can access the key and also the value identified by this key.\n\nWith this `Entry` value at hand, you can access the key of this current entry by using the `key_ptr`\nattribute and dereferencing the pointer that lives inside of it, while the value identified by this\nkey is accessed through the `value_ptr` attribute instead, which is also a pointer to be dereferenced.\nThe code example below demonstrates the use of these elements:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n\n    var it = hash_table.iterator();\n    while (it.next()) |kv| {\n        // Access the current key\n        std.debug.print(\"Key: {d} | \", .{kv.key_ptr.*});\n        // Access the current value\n        std.debug.print(\"Value: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nKey: 54321 | Value: 89Key: 50050 | Value: 55Key: 5\n  57709 | Value: 41\n```\n\n\n:::\n:::\n\n\n\n\n```\nKey: 54321 | Value: 89\nKey: 50050 | Value: 55\nKey: 57709 | Value: 41\n```\n\n\nIf you want to iterate specifically through the values or the keys of your hashtable,\nyou can create a key iterator or a value iterator object. These are also iterator\nobjects, which have the same `next()` method that you can use to iterate through the\nhashtable.\n\nKey iterators are created from the `keyIterator()` method of your\nhashtable object, while value iterators are created from the `valueIterator()` method.\nAll you have to do is to unwrap the value from the `next()` method and deference it\ndirectly to access the key or the value that you are iterating over.\nThe code example below demonstrates the use of a key iterator,\nbut you can replicate the same logic to a value iterator.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar kit = hash_table.keyIterator();\nwhile (kit.next()) |key| {\n    std.debug.print(\"Key: {d}\\n\", .{key.*});\n}\n```\n:::\n\n\n\n\n```\nKey: 54321\nKey: 50050\nKey: 57709\n```\n\n\n### The `ArrayHashMap` hashtable {#sec-array-map}\n\nIf you need to iterate through the elements of your hashtable constantly,\nyou might want to use the `ArrayHashMap` struct for your specific case,\ninstead of going with the usual and general-purpose `HashMap` struct.\n\nThe `ArrayHashMap` struct creates a hashtable that is faster to iterate over.\nThat is why this specific type of hashtable might be valuable to you.\nSome other properties of a `ArrayHashMap` hashtable are:\n\n- the order of insertion is preserved, i.e. the order of the values that you find while iterating through this hashtable is actually the order in which these values were inserted in the hashtable.\n- the key-value pairs are stored sequentially, one after another.\n\n\nYou can create an `ArrayHashMap` object by using, once again, a helper function that\nchooses automatically for you a hash function implementation. This is the\n`AutoArrayHashMap()` function, which works very similarly to the `AutoHashMap()`\nfunction that we presented at @sec-hashmap.\n\nYou provide two data types to this function. The data type of the keys that will be\nused in this hashtable, and the data type of the values that will be stored in\nthis hashtable.\n\nAn `ArrayHashMap` object have essentially the exact same methods from the `HashMap` struct.\nSo you can insert new values into the hashtable by using the `put()` method, and you can look (or get)\na value from the hashtable by using the `get()` method. But the `remove()` method is not available\nin this specific type of hashtable.\n\nIn order to delete values from the hashtable, you would use the same methods that you find in\nan `ArrayList` object, i.e. a dynamic array. I presented these methods at @sec-dynamic-array-remove,\nwhich are the `swapRemove()` and `orderedRemove()` methods. These methods have the same meaning here, or,\nthe same effect that they have in an `ArrayList` object.\n\nThis means that, with `swapRemove()` you remove the value from the hashtable, but you do not preserve\nthe order in which the values were inserted into the structure. While `orderedRemove()` is able\nto retain the order in which these values were inserted.\n\nBut instead of providing an index as input to `swapRemove()` or `orderedRemove()`, like I described\nat @sec-dynamic-array-remove, these methods here in an `ArrayHashMap` take a key as input, like\nthe `remove()` method from a `HashMap` object. If you want to provide an index as input, instead\nof a key, you should use the `swapRemoveAt()` and `orderedRemoveAt()` methods.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar hash_table = AutoArrayHashMap(u32, u16)\n    .init(allocator);\ndefer hash_table.deinit();\n```\n:::\n\n\n\n\n\n\n### The `StringHashMap` hashtable {#sec-string-hash-map}\n\nOne thing that you will notice in the other two types of hashtables that I have\npresented over the last sections, is that neither of them accepts a slice data type\nin their keys.\nWhat this means is that you cannot use a slice value to represent a key in\nthese types of hashtable.\n\nThe most obvious consequence of this, is that you cannot use strings as keys\nin these hashtables. But it is extremely common to use strings as keys\nin hashtables.\n\nTake this very simple Javascript code snippet as an example. We are creating\na simple hashtable object named `people`. Then, we add a new entry to this\nhashtable, which is identified by the string `'Pedro'`. This string is the\nkey in this case, while the object containing different personal information such as\nage, height and city, is the value to be stored in the hashtable.\n\n```js\nvar people = new Object();\npeople['Pedro'] = {\n    'age': 25,\n    'height': 1.67,\n    'city': 'Belo Horizonte'\n};\n```\n\nThis pattern of using strings as keys is very common in\nall sorts of situations. That is why the Zig Standard Library offers a\nspecific type of hashtable for this purpose, which is created through the `StringHashMap()` function.\nThis function creates a hashtable that uses strings as keys. The only input of this\nfunction is the data type of the values that will be stored into this hashtable.\n\nIn the example below, I'm creating a hashtable to store the ages of different people.\nEach key in this hashtable is represented by the name of each person, while the value stored in the\nhashtable is the age of this person identified by the key.\n\nThat is why I provide the `u8` data type (which is the data type used by the age values) as input to this `StringHashMap()` function.\nAs the result, it creates a hashtable that uses string values as keys, and, that stores\n`u8` values in it. Notice that an allocator object is provided at the `init()` method of the\nresulting object from the `StringHashMap()` function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var ages = std.StringHashMap(u8).init(allocator);\n    defer ages.deinit();\n\n    try ages.put(\"Pedro\", 25);\n    try ages.put(\"Matheus\", 21);\n    try ages.put(\"Abgail\", 42);\n\n    var it = ages.iterator();\n    while (it.next()) |kv| {\n        std.debug.print(\"Key: {s} | \", .{kv.key_ptr.*});\n        std.debug.print(\"Age: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n:::\n\n\n\n\n```\nKey: Pedro | Age: 25\nKey: Abgail | Age: 42\nKey: Matheus | Age: 21\n```\n\n\n### The `StringArrayHashMap` hashtable\n\nThe Zig Standard Library also provides a type of hashtable that mix the cons and pros of the\n`StringHashMap` and `ArrayHashMap` together. That is, a hashtable\nthat uses strings as keys, but also have the advantages from `ArrayHashMap`.\nIn other words, you can have a hashtable that is fast to iterate over,\nthat preserves insertion order, and also, that uses strings as keys.\n\nYou can create such type of hashtable by using the `StringArrayHashMap()` function.\nThis function accepts a data type as input, which is the data type of the values that are\ngoing to be stored inside this hashtable, in the same style as the function presented\nat @sec-string-hash-map.\n\nYou can insert new values into this hashtable by using the same `put()` method that\nwe have discussed at @sec-string-hash-map. And you can also get values from the hashtable\nby using the same `get()` method.\nLike its `ArrayHashMap` brother, to delete values from this specific type of hashtable,\nwe also use the `orderedRemove()` and `swapRemove()` methods, with the same effects that\nI have described at @sec-array-map.\n\nIf we take the code example that was exposed at @sec-string-hash-map, we can\nachieve the exact same result with `StringArrayHashMap()`:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar ages = std.StringArrayHashMap(u8).init(allocator);\n```\n:::\n\n\n\n\n\n\n\n## Linked lists\n\nThe Zig Standard Library provides an implementation for both singly and doubly linked lists.\nA linked list is a linear data structure that looks like a chain, or, a rope.\nThe main advantage of this data structure is that you normally have very fast\ninsertion and deletion operations. But, as a disadvantage, iterating through\nthis data structure is usually not so fast as iterating through an array.\n\nThe idea behind a linked list is to build a structure that consists of a sequence of nodes\nconnected to each other by pointers. This means that linked lists are usually not contiguous\nin memory, because each node might be anywhere in memory. They do not need to be close to\none another.\n\nAt @fig-linked-list we can see a diagram of a singly linked list. We begin at the first node\n(which is usually called \"the head of the linked list\"). Then, from this\nfirst node we uncover the remaining nodes in the structure, by following the locations pointed\nby the pointers found in each node.\n\nEach node has two things in it. It has the value that is stored in the current node\n, and also, a pointer. This pointer points to the next node in the list. If this pointer\nis null, then, it means that we have reached the end of our linked list.\n\n![A diagram of a singly linked list.](./../Figures/linked-list.png){#fig-linked-list}\n\n\nAt @fig-linked-list2 we can see a diagram of a doubly linked list. The only thing that really\nchanges now is that every node in the linked list has both a pointer to the previous node,\nand, a pointer to the next node. So every node in a doubly linked list has two pointers in it. These are\nusually called the `prev` (for \"previous\") and the `next` (for \"next\") pointers of the node.\n\nIn the singly linked list example, we had only one single pointer in each node, and this singular\npointer was always pointing to the next node in the sequence. This means that singly linked lists\nnormally have only the `next` pointer in them.\n\n![A diagram of a doubly linked list.](./../Figures/doubly-linked-list.png){#fig-linked-list2}\n\n\nLinked lists are available in Zig through the functions `SinglyLinkedList()` and\n`DoublyLinkedList()`, for \"singly linked lists\" and \"doubly linked lists\", respectively. These functions are\nactually generic functions, which we are going to talk more about at @sec-generic-fun.\n\nFor now, just understand that, in order to create a linked list object,\nwe begin by providing a data type to these functions. This data type defines\nthe type of data that each node in this linked list will store. In the example below,\nwe are creating a singly linked list of `u32` values.\nSo each node in this linked list will store a `u32` value.\n\nBoth the `SinglyLinkedList()` and `DoublyLinkedList()` functions returns a type,\ni.e. a struct definition, as output. Therefore, the object `Lu32` is actually\na struct definition. It defines the type \"singly linked list of `u32` values\".\n\nNow that we have the definition of the struct, we need to instantiate a `Lu32` object.\nWe normally instantiate struct objects in Zig by using an `init()` method.\nBut in this case, we are instantiating the struct directly, by using an empty\n`struct` literal, in the expression `Lu32{}`.\n\nIn this example, we first create multiple node objects, and after we create them,\nwe start to insert and connect these nodes to build the linked list, using the\n`prepend()` and `insertAfter()` methods. Notice that the `prepend()` method\nis a method from the linked list object, while the `insertAfter()` is a method\npresent in the node objects.\n\nIn essence, the `prepend()` method inserts a node at the beginning of the linked\nlist. In other words, the node that you provide to this method, becomes the new\n\"head node\" of the linked list. It becomes the first node in the list (see @fig-linked-list).\n\nOn the other side, the `insertAfter()` method is used to basically connect two nodes together.\nWhen you provide a node to this method, it creates a pointer to this input node,\nand stores this pointer in the `next` attribute of the current node, from which the method was called from.\n\nBecause doubly linked lists have both a `next` and a `prev` attributes in each node\n(as described at @fig-linked-list2), a node object created from\na `DoublyLinkedList` object have both an `insertBefore()` (for `prev`)\nand an `insertAfter()` (for `next`) methods available.\n\nThus, if we have used a doubly linked list, we can use the `insertBefore()` method\nto store the pointer to the input node in the `prev` attribute. This would put the input\nnode as the \"previous node\", or, the node before the current node. In contrast, the `insertAfter()` method\nputs the pointer created to the input node in the `next` attribute of the current node,\nand as result, the input node becomes the \"next node\" of the current node.\n\nSince we are using a singly linked list in this example, we have only the `insertAfter()` method\navailable in the node objects that we create from our `Lu32` type.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SinglyLinkedList = std.SinglyLinkedList;\nconst Lu32 = SinglyLinkedList(u32);\n\npub fn main() !void {\n    var list = Lu32{};\n    var one = Lu32.Node{ .data = 1 };\n    var two = Lu32.Node{ .data = 2 };\n    var three = Lu32.Node{ .data = 3 };\n    var four = Lu32.Node{ .data = 4 };\n    var five = Lu32.Node{ .data = 5 };\n\n    list.prepend(&two); // {2}\n    two.insertAfter(&five); // {2, 5}\n    list.prepend(&one); // {1, 2, 5}\n    two.insertAfter(&three); // {1, 2, 3, 5}\n    three.insertAfter(&four); // {1, 2, 3, 4, 5}\n}\n```\n:::\n\n\n\n\n\nThere are other methods available from the linked list object, depending if this object is\na singly linked list or a doubly linked list, that might be very useful for you. You can find a\nsummary of them in the bullet points below:\n\n- `remove()` to remove a specific node from the linked list.\n- if singly linked list, `len()` to count how many nodes there is in the linked list.\n- if doubly linked list, checkout the `len` attribute to see how many nodes there is in the linked list.\n- if singly linked list, `popFirst()` to remove the first node (i.e. the \"head\") from the linked list.\n- if doubly linked list, `pop()` and `popFirst()` to remove the last and first nodes from the linked list, respectively.\n- if doubly linked list, `append()` to add a new node to end of the linked list (i.e. inverse of `prepend()`).\n\n\n\n## Multi array structure\n\nZig introduces a new data structure called `MultiArrayList()`. It is a different version of the dynamic array\nthat we have introduced at @sec-dynamic-array. The difference between this structure and the `ArrayList()`\nthat we know from @sec-dynamic-array, is that `MultiArrayList()` creates a separate dynamic array\nfor each field of the struct that you provide as input.\n\nConsider the following code example. We create a new custom struct called `Person`. This\nstruct contains three different data members, or, three different fields. As consequence,\nwhen we provide this `Person` data type as input to `MultiArrayList()`, this\ncreates a \"struct of three different arrays\" called `PersonArray`. In other words,\nthis `PersonArray` is a struct that contains three internal dynamic arrays in it.\nOne array for each field found in the `Person` struct definition.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Person = struct {\n    name: []const u8,\n    age: u8,\n    height: f32,\n};\nconst PersonArray = std.MultiArrayList(Person);\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var people = PersonArray{};\n    defer people.deinit(allocator);\n\n    try people.append(allocator, .{\n        .name = \"Auguste\", .age = 15, .height = 1.54\n    });\n    try people.append(allocator, .{\n        .name = \"Elena\", .age = 26, .height = 1.65\n    });\n    try people.append(allocator, .{\n        .name = \"Michael\", .age = 64, .height = 1.87\n    });\n}\n```\n:::\n\n\n\n\nIn other words, instead of creating an array of \"persons\", the `MultiArrayList()` function\ncreates a \"struct of arrays\". Each data member of this struct is a different array that stores\nthe values of a specific field from the `Person` values that were added (or, appended) to this \"struct of arrays\".\nOne important detail is that each of these separate internal arrays stored inside `PersonArray`\nare dynamic arrays. This means that these arrays can grow in capacity automatically as needed, to accomodate\nmore values.\n\nThe @fig-multi-array exposed below presents a diagram that describes the `PersonArray` struct\nthat we have created in the previous code example. Notice that the values of the data members\npresent in each of the three `Person` values that we have appended into the `PersonArray` object\n, are scattered across three different internal arrays of the `PersonArray` object.\n\n![A diagram of the `PersonArray` struct.](./../Figures/multi-array.png){#fig-multi-array}\n\nYou can easily access each of these arrays separately, and iterate over the values of each array.\nFor that, you will need to call the `items()` method from the `PersonArray` object, and provide as input\nto this method, the name of the field that you want to iterate over.\nIf you want to iterate through the `.age` array for example, then, you need to call `items(.age)` from\nthe `PersonArray` object, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (people.items(.age)) |*age| {\n    try stdout.print(\"Age: {d}\\n\", .{age.*});\n}\n```\n:::\n\n\n\n\n```\nAge: 15\nAge: 26\nAge: 64\n```\n\n\nIn the above example, we are iterating over the values of the `.age` array, or,\nthe internal array of the `PersonArray` object that contains the values of the `age`\ndata member from the `Person` values that were added to the multi array struct.\n\nIn this example we are calling the `items()` method directly from the `PersonArray`\nobject. However, it is recommended on most situations to call this `items()` method\nfrom a \"slice object\", which you can create from the `slice()` method.\nThe reason for this is that calling `items()` multiple times have better performance\nif you use a slice object.\n\nTherefore, if you are planning to access only one of the\ninternal arrays from your \"multi array struct\", it is fine to call `items()` directly\nfrom the multi array object. But if you need to access many of the internal arrays\nfrom your \"multi array struct\", then, you will likely need to call `items()` more\nthan once, and, in such circumstance, is better to call `items()` through a slice object.\nThe example below demonstrates the use of such object:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar slice = people.slice();\nfor (slice.items(.age)) |*age| {\n    age.* += 10;\n}\nfor (slice.items(.name), slice.items(.age)) |*n,*a| {\n    try stdout.print(\n        \"Name: {s}, Age: {d}\\n\", .{n.*, a.*}\n    );\n}\n```\n:::\n\n\n\n\n```\nName: Auguste, Age: 25\nName: Elena, Age: 36\nName: Michael, Age: 74\n```\n\n\n## Conclusion\n\nThere are many other data structures that I haven't presented here.\nBut you can check them out at the official Zig Standard Library documentation page.\nActually, when you get into the [homepage of the documentation](https://ziglang.org/documentation/master/std/#)[^home], the first thing\nthat appears to you in this page, is a list of types and data structures that\nare available in the Zig Standard Library.\nThere are some very specific data structures in this list, like a\n[`BoundedArray` struct](https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray)[^bounded]\n, but there is also some more general structures, such as a\n[`PriorityQueue` struct](https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue)[^priority].\n\n\n[^home]: <https://ziglang.org/documentation/master/std/#>\n[^priority]: <https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue>.\n[^bounded]: <https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray>\n\n\n\n\n\n\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Data Structures\n\nIn this chapter, I want to present the most common Data Structures that are available from\nthe Zig Standard Library, especially `ArrayList` and also `HashMap`. These are generic Data Structures\nthat you can use to store and control any type of data that is produced by your application.\n\n## Dynamic Arrays {#sec-dynamic-array}\n\nIn high level languages, arrays are usually dynamic. They can easily grow\nin size when they have to, and you don't need to worry about it.\nIn contrast, arrays in low level languages are usually static by default.\nThis is the reality of C, C++, Rust and also Zig. Static arrays were presented at\n@sec-arrays, but in this section, we are going to talk about dynamic arrays in Zig.\n\nDynamic arrays are simply arrays that can grow in size during the runtime\nof your program. Most low level languages have some implementation of\na dynamic array in their standard library. C++ have `std::vector`, Rust have `Vec`,\nand Zig have `std.ArrayList`.\n\nThe `std.ArrayList` struct provides a contiguous and growable array for you.\nIt works like any other dynamic array, it allocates a contiguous block of memory, and when this block have no space left,\n`ArrayList` allocates another contiguous and bigger block of memory, copies the\nelements to this new location, and erases (or frees) the previous block of memory.\n\n\n### Capacity vs Length\n\nWhen we talk about dynamic arrays, we usually have two similar concepts that\nare very essential to how a dynamic array works behind the hood.\nThese concepts are *capacity* and *length*. In some contexts, especially\nin C++, *length* is also called of *size*.\n\nAlthough they look similar, these concepts represent different things\nin the context of a dynamic array. *Capacity* is the number of items (or elements)\nthat your dynamic array can currently hold without the need to allocate more memory.\n\nIn contrast, the *length* refers to how many elements in the array\nare currently being used, or, in other words, how many elements in this array\nthat you have assigned a value to. Every dynamic array works around\na block of allocated memory, which represents an array with total capacity for $n$ elements.\nHowever, only a portion of these $n$ elements are being used most of the time. This portion\nof $n$ is the *length* of the array. So every time you append a new value\nto the array, you are incrementing its *length* by one.\n\nThis means that a dynamic array usually works with an extra margin, or, an extra space\nwhich is currently empty, but it is waiting and ready to be used. This \"extra space\"\nis essentially the difference between *capacity* and *length*. *Capacity* represents\nthe total number of elements that the array can hold without the need to re-allocate\nor re-expand the array, while the *length* represents how much of this capacity\nis currently being used to hold/store values.\n\n@fig-capacity-length presents this idea visually. Notice that, at first,\nthe capacity of the array is greater than the length of the array.\nSo, the dynamic array have extra space that is currently empty, but it\nis ready to receive a value to be stored.\n\n![Difference between capacity and length in a dynamic array](./../Figures/dynamic-array.png){#fig-capacity-length}\n\nWe can also see at @fig-capacity-length that, when *length* and *capacity* are equal, it means that the array have no space left.\nWe have reached the ceiling of our capacity, and because of that, if we want to store more values\nin this array, we need to expand it. We need to get a bigger space that can hold more values\nthan what we currently have.\n\nA dynamic array works by expanding the underlying array, whenever the *length* becomes equal\nto the *capacity* of the array. It basically allocates a new contiguous block of memory that is bigger\nthan the previous one, then, it copies all values that are currently being stored to this new\nlocation (i.e. this new block of memory), then, it frees the previous block of\nmemory. At the end of this process, the new underlying array have a bigger *capacity*, and, therefore,\nthe *length* becomes, once again, smaller than the *capacity* of the array.\n\nThis is the cycle of an dynamic array. Notice that, throughout this cycle, the *capacity* is always\neither equal to or higher than the *length* of the array. If youh have an `ArrayList` object (let's suppose\nyou named it `buffer`), you can check the current capacity of your array by accessing the `capacity`\nattribute of your `ArrayList` object, while the current *length* of it is available at the `items.len`\nattribute.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// Check capacity\nbuffer.capacity;\n// Check length\nbuffer.items.len;\n```\n:::\n\n\n\n\n\n### Creating an `ArrayList` object\n\nIn order to use `ArrayList`, you must provide an allocator object to it.\nRemember, Zig does not have a default memory allocator. And as I described at @sec-allocators, all memory\nallocations must be done by an allocator object that you define, that\nyou have control over. In our example here, I'm going to use\na general purpose allocator, but you can use any other allocator\nof your preference.\n\nWhen you initialize an `ArrayList` object, you must provide the data type of the elements of\nthe array. In other words, this defines the type of data that this array (or container) will\nstore. Therefore, if I provide the `u8` type to it, then, I will create a dynamic\narray of `u8` values. However, if I provide a struct that I have defined instead, like the struct `User`\nfrom @sec-structs-and-oop, then, a dynamic array of `User` values\nwill be created. In the example below, with the expression `ArrayList(u8)` we\nare creating a dynamic array of `u8` values.\n\nAfter you provide the data type of the elements of the array, you can initialize\nan `ArrayList` object by either using the `init()` or the `initCapacity()` methods.\nThe former method receives only the allocator object\nas input, while the latter method receives both the allocator object and a capacity number as inputs.\nWith the latter method, you not only initialize the struct, but you\nalso set the starting capacity of the allocated array.\n\nUsing the `initCapacity()` method is the preferred way to initialize your dynamic array.\nBecause reallocations, or, in other words, the process of expanding the capacity of the array,\nis always a high cost operation. You should take any possible opportunity to avoid reallocations in\nyour array. If you know how much space your array needs to occupy at the beginning,\nyou should always use `initCapacity()` to create your dynamic array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n```\n:::\n\n\n\n\n\nIn the example above, the `buffer` object starts as an array of 100 elements. If this\n`buffer` object needs to create more space to accomodate more elements during the runtime of your program, the `ArrayList`\ninternals will perform the necessary actions for you automatically.\nAlso notice the `deinit()` method being used to destroy the `buffer` object at the\nend of the current scope, by freeing all the memory that was allocated for the dynamic\narray stored in this `buffer` object.\n\n\n### Adding new elements to the array\n\nNow that we have created our dynamic array, we can start to use it. You can append (a.k.a \"add\")\nnew values to this array by using the `append()` method. This method works the same way\nas the `append()` method from a Python list, or, the `emplace_back()` method from `std::vector` of C++.\nYou provide a single value to this method, and the method appends this value to the array.\n\nYou can also use the `appendSlice()` method to append multiple values at once. You provide\na slice (slices were described at @sec-arrays) to this method, and the method adds all values present\nin this slice to your dynamic array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry buffer.append('H');\ntry buffer.append('e');\ntry buffer.append('l');\ntry buffer.append('l');\ntry buffer.append('o');\ntry buffer.appendSlice(\" World!\");\n```\n:::\n\n\n\n\n### Removing elements from the array {#sec-dynamic-array-remove}\n\nYou can use the `pop()` method to \"pop\" or remove\nthe last element in the array. Is worth noting that this method\ndo not change the capacity of the array. It just deletes or erases\nthe last value stored in the array.\n\nAlso, this method returns as result the value that got deleted. That is, you can\nuse this method to both get the last value in the array, and also, remove\nit from the array. It is a \"get and remove value\" type of method.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exclamation_mark = buffer.pop();\n```\n:::\n\n\n\n\nNow, if you want to remove specific elements from specific positions\nof your array, you can use the `orderedRemove()` method from your\n`ArrayList` object. With this method, you can provide an index as input,\nthen, the method will delete the value that is at this index in the array.\nYou are effectively reducing the *length* of the array everytime you execute\nan `orderedRemove()` operation.\n\nIn the example below, we first create an `ArrayList` object, and we fill it\nwith numbers. Then, we use `orderedRemove()` to remove the value at\nindex 3 in the array, two consecutive times.\n\nAlso, notice that we are assigning the result of `orderedRemove()` to the\nunderscore character. So we are discarding the result value of this method.\nThe `orderedRemove()` method returns the value that got deleted, in a similar\nstyle to the `pop()` method.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n\nfor (0..10) |i| {\n    const index: u8 = @intCast(i);\n    try buffer.append(index);\n}\n\nstd.debug.print(\n    \"{any}\\n\", .{buffer.items}\n);\n_ = buffer.orderedRemove(3);\n_ = buffer.orderedRemove(3);\n\nstd.debug.print(\"{any}\\n\", .{buffer.items});\nstd.debug.print(\"{any}\\n\", .{buffer.items.len});\n```\n:::\n\n\n\n\n```\n{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }\n{ 0, 1, 2, 5, 6, 7, 8, 9 }\n8\n```\n\nOne key characteristic about `orderedRemove()` is that it preserves the order\nof the values in the array. So, it deletes the value that you asked it to\nremove, but it also makes sure that the order of the values that remain in the array\nstay the same as before.\n\nNow, if you don't care about the order of the values, for example, maybe you want to treat\nyour dynamic array as a set of values, like the `std::unordered_set`\nstructure from C++, you can use the `swapRemove()` method instead. This method\nworks similarly to the `orderedRemove()` method. You give an index to this\nmethod, then, it deletes the value that is at this index in the array.\nBut this method does not preserve the original order of the values that remain\nin the array. As a result, `swapRemove()` is, in general, faster than `orderedRemove()`.\n\n\n### Inserting elements at specific indexes\n\nWhen you need to insert values in the middle of your array,\ninstead of just appending them to the end of the array, you need to use\nthe `insert()` and `insertSlice()` methods, instead of\nthe `append()` and `appendSlice()` methods.\n\nThese two methods work very similarly to `insert()` and `insert_range()`\nfrom the C++ `std::vector` class. You provide an index to these methods,\nand they insert the values that you provide at that index in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 10);\ndefer buffer.deinit();\n\ntry buffer.appendSlice(\"My Pedro\");\ntry buffer.insert(4, '3');\ntry buffer.insertSlice(2, \" name\");\nfor (buffer.items) |char| {\n    try stdout.print(\"{c}\", .{char});\n}\n```\n:::\n\n\n\n\n```\nMy name P3edro\n```\n\n\n### Conclusion\n\nIf you feel the lack of some other method, I recommend\nyou to read the [official documentation for the `ArrayListAligned`](https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned)[^zig-array2]\nstruct, which describes most of the methods available\nthrough the `ArrayList` object.\n\nYou will notice that there is a lot of other methods in this page that\nI did not described here, and I recommend you to explore these methods,\nand understand how they work.\n\n[^zig-array2]: <https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned>\n\n\n\n## Maps or HashTables {#sec-maps-hashtables}\n\nSome professionals know this type of data structure by different terms, like \"map\",\n\"hashmap\" or \"associative arrays\". But the most common term used is *hashtable*.\nEvery programming language normally have some implementation of a hashtable in their\nstandard libraries. Python have `dict()`, C++ have `std::map` and `std::unordered_map`, Rust\nhave `HashMap`, Javascript have `Object()` and `Map()`, etc.\n\n\n\n### What is a hashtable?\n\nA hashtable is a data structure based on key-value pairs.\nYou provide a key and a value to this structure, then, the hashtable will store\nthe input value at a location that can be identified by the input\nkey that you provided.\nIt does that by using an underlying array and a hash function.\nThese two components are essential to how a hashtable works.\n\nUnder the hood, the hashtable contains an array. This array is where the values\nare stored, and the elements of this array are usually called of *buckets*.\nSo the values that you provide to the hashtable are stored inside buckets,\nand you access each bucket by using an index.\n\nWhen you provide a key to a hashtable, it passes this key to the\nhash function. This hash function uses some sort of hashing algorithm to transform\nthis key into an index. This index is actually an array index. It is a position\nin the underlying array of the hashtable.\nThis is how a key identifies a specific position (or location) inside the hashtable\nstructure.\n\nTherefore, you provide a key to the hashtable, and this key identifies a specific location\ninside the hashtable, then, the hashtable takes the input value that you provided,\nand stores this value in the location identified by this input key.\nYou could say that the key maps to the value stored in the hashtable. You find\nthe value, by using the key that identifies the location where the value is stored.\nThe @fig-hashtable presents this process visually.\n\n\n![A diagram of a Hashtable. Source: Wikipedia, the free encyclopedia.](./../Figures/hashtable.svg){#fig-hashtable}\n\n\nThe operation described in the previous paragraph is normally called an *insertion* operation.\nBecause you are inserting new values into the hashtable.\nBut there are other types of operations in hashtables such as *delete* and *lookup*.\nDelete is self describing, it is when you delete (or remove) a value from the hashtable.\nWhile lookup corresponds to when you look at a value that is stored in\nthe hashtable, by using the key that identifies the location where this value is stored.\n\nSometimes, instead of storing the values directly, the underlying array of the hashtable might be an array of pointers,\ni.e. the buckets of the array stores pointers that points to the value,\nor also, may be an array of linked lists.\nThese cases are common on hashtables that allows duplicate keys, or, in other words,\non hashtables that effectively handle \"collisions\" that may arise from the hash function.\n\nDuplicate keys, or this \"collision\" thing that I'm talking about, is when you have two different keys\nthat points to the same location (i.e. to the same index)\nin the underlying array of the hashtable. This might happen depending on the characteristics of the hash function\nthat is being used in the hashtable. Some implementations of the hashtable will actively deal with collisions,\nmeaning that, they will handle this case in some way. For example, the hashtable\nmight transform all buckets into linked lists. Because with a linked list you can store\nmultiple values into a single bucket.\n\nThere are different techniques to handle collisions in hashtables, which I will not describe\nin this book, because it is not our main scope here. But you can find a good description of\nsome of the most common techniques at the Wikipedia page of hashtables [@wikipedia_hashtables].\n\n\n### Hashtables in Zig {#sec-hashmap}\n\nThe Zig Standard Library provides different implementations of a hashtable.\nEach implementation have its own cons and pros, which we will\ndiscuss later on, and all of them are available through the `std.hash_map` module.\n\nThe `HashMap` struct is a general-purpose hashtable,\nwhich have very fast operations (lookup, insertion, delete), and also,\nquite high load factors for low memory usage. You can create and provide a context object\nto the `HashMap` constructor. This context object allows you to tailor\nthe behaviour of the hashtable itself, because you can\nprovide a hash function implementation to be used by the hashtable\nthrough this context object.\n\nBut let's not worry about this context object now, because it is meant to be used\nby \"experts in the field of hashtables\". Since we are most likely not\nexperts in this field, we are going to take the easy way to create\na hashtable. Which is by using the `AutoHashMap()` function.\n\n\nThis `AutoHashMap()` function is essentially a \"create a hashtable object that uses the default settings\"\ntype of function. It automatically chooses a context object, and, therefore, a hash function implementation,\nfor you. This function receives two data types as input, the first input is the data type of the keys\nthat will be used in this hashtable, while the second input is the data type of the data that will be\nstored inside the hashtable, that is, the data type of the values to be stored.\n\nIn the example below, we are providing the data type `u32` in the first argument, and `u16` in the second argument of this\nfunction. This means that we are going to use `u32` values as keys in this hashtable, while `u16` values are the actual values\nthat are going to be stored into this hashtable.\nAt the end of this process, the `hash_table` object contains a `HashMap` object\nthat uses the default settings and context.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n    std.debug.print(\n        \"Value at key 50050: {d}\\n\",\n        .{hash_table.get(50050).?}\n    );\n\n    if (hash_table.remove(57709)) {\n        std.debug.print(\n            \"Value at key 57709 successfully removed!\\n\",\n            .{}\n        );\n    }\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n}\n```\n:::\n\n\n\n\n```\nN of values stored: 3\nValue at key 50050: 55\nValue at key 57709 successfully removed!\nN of values stored: 2\n```\n\nYou can add/put new values into the hashtable by using the `put()` method. The first argument\nis the key to be used, and the second argument is the actual value that you want to store inside\nthe hashtable. In the example below, we first add the value 89 using the key 54321, next, we add\nthe value 55 using the key 50050, etc.\n\nNotice that we have used the method `count()` to see how many values are currently stored in the\nhashtable. After that, we also use the `get()` method to access (or look) at the value stored in\nthe position identified by the key 500050. The output of this `get()` method is an optional value.\nThis is why we use the `?` method at the end to get the actual value.\n\nAlso notice that we can remove (or delete) values from the hashtable by using the `remove()` method.\nYou provide the key that identifies the value that you want to delete, then, the method will\ndelete this value and return a `true` value as output. This `true` value essentially tells us\nthat the method successfully deleted the value.\n\nBut this delete operation might not be always successful. For example, you might provide the wrong\nkey to this method. I mean, maybe you provide\n(either intentionally or unintentionally) a key that points to an empty bucket,\ni.e. a bucket that still doesn't have a value in it.\nIn this case, the `remove()` method would return a `false` value.\n\n\n\n### Iterating through the hashtable\n\nIterating through the keys and values that are currently being stored in\nthe hashtable is a very common necessity.\nYou can do that in Zig by using an iterator object that can iterate\nthrough the elements of your hashtable object.\n\nThis iterator object works like any other iterator object that you would\nfind in languages such as C++ and Rust. It is basically a pointer object\nthat points to some value in the container, and has a `next()` method\nthat you can use to navigate (or iterate) through the values in the\ncontainer.\n\nYou can create such iterator object by using the `iterator()` method of the hashtable object.\nThis method returns an iterator object, from which you can use the `next()` method in conjunction\nwith a while loop to iterate through the elements of your hashtable. The `next()` method returns an optional\n`Entry` value, and therefore, you must unwrap this optional value to get the actual `Entry` value\nfrom which you can access the key and also the value identified by this key.\n\nWith this `Entry` value at hand, you can access the key of this current entry by using the `key_ptr`\nattribute and dereferencing the pointer that lives inside of it, while the value identified by this\nkey is accessed through the `value_ptr` attribute instead, which is also a pointer to be dereferenced.\nThe code example below demonstrates the use of these elements:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n\n    var it = hash_table.iterator();\n    while (it.next()) |kv| {\n        // Access the current key\n        std.debug.print(\"Key: {d} | \", .{kv.key_ptr.*});\n        // Access the current value\n        std.debug.print(\"Value: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n:::\n\n\n\n\n```\nKey: 54321 | Value: 89\nKey: 50050 | Value: 55\nKey: 57709 | Value: 41\n```\n\n\nIf you want to iterate specifically through the values or the keys of your hashtable,\nyou can create a key iterator or a value iterator object. These are also iterator\nobjects, which have the same `next()` method that you can use to iterate through the\nhashtable.\n\nKey iterators are created from the `keyIterator()` method of your\nhashtable object, while value iterators are created from the `valueIterator()` method.\nAll you have to do is to unwrap the value from the `next()` method and deference it\ndirectly to access the key or the value that you are iterating over.\nThe code example below demonstrates the use of a key iterator,\nbut you can replicate the same logic to a value iterator.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar kit = hash_table.keyIterator();\nwhile (kit.next()) |key| {\n    std.debug.print(\"Key: {d}\\n\", .{key.*});\n}\n```\n:::\n\n\n\n\n```\nKey: 54321\nKey: 50050\nKey: 57709\n```\n\n\n### The `ArrayHashMap` hashtable {#sec-array-map}\n\nIf you need to iterate through the elements of your hashtable constantly,\nyou might want to use the `ArrayHashMap` struct for your specific case,\ninstead of going with the usual and general-purpose `HashMap` struct.\n\nThe `ArrayHashMap` struct creates a hashtable that is faster to iterate over.\nThat is why this specific type of hashtable might be valuable to you.\nSome other properties of a `ArrayHashMap` hashtable are:\n\n- the order of insertion is preserved, i.e. the order of the values that you find while iterating through this hashtable is actually the order in which these values were inserted in the hashtable.\n- the key-value pairs are stored sequentially, one after another.\n\n\nYou can create an `ArrayHashMap` object by using, once again, a helper function that\nchooses automatically for you a hash function implementation. This is the\n`AutoArrayHashMap()` function, which works very similarly to the `AutoHashMap()`\nfunction that we presented at @sec-hashmap.\n\nYou provide two data types to this function. The data type of the keys that will be\nused in this hashtable, and the data type of the values that will be stored in\nthis hashtable.\n\nAn `ArrayHashMap` object have essentially the exact same methods from the `HashMap` struct.\nSo you can insert new values into the hashtable by using the `put()` method, and you can look (or get)\na value from the hashtable by using the `get()` method. But the `remove()` method is not available\nin this specific type of hashtable.\n\nIn order to delete values from the hashtable, you would use the same methods that you find in\nan `ArrayList` object, i.e. a dynamic array. I presented these methods at @sec-dynamic-array-remove,\nwhich are the `swapRemove()` and `orderedRemove()` methods. These methods have the same meaning here, or,\nthe same effect that they have in an `ArrayList` object.\n\nThis means that, with `swapRemove()` you remove the value from the hashtable, but you do not preserve\nthe order in which the values were inserted into the structure. While `orderedRemove()` is able\nto retain the order in which these values were inserted.\n\nBut instead of providing an index as input to `swapRemove()` or `orderedRemove()`, like I described\nat @sec-dynamic-array-remove, these methods here in an `ArrayHashMap` take a key as input, like\nthe `remove()` method from a `HashMap` object. If you want to provide an index as input, instead\nof a key, you should use the `swapRemoveAt()` and `orderedRemoveAt()` methods.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar hash_table = AutoArrayHashMap(u32, u16)\n    .init(allocator);\ndefer hash_table.deinit();\n```\n:::\n\n\n\n\n\n\n### The `StringHashMap` hashtable {#sec-string-hash-map}\n\nOne thing that you will notice in the other two types of hashtables that I have\npresented over the last sections, is that neither of them accepts a slice data type\nin their keys.\nWhat this means is that you cannot use a slice value to represent a key in\nthese types of hashtable.\n\nThe most obvious consequence of this, is that you cannot use strings as keys\nin these hashtables. But it is extremely common to use strings as keys\nin hashtables.\n\nTake this very simple Javascript code snippet as an example. We are creating\na simple hashtable object named `people`. Then, we add a new entry to this\nhashtable, which is identified by the string `'Pedro'`. This string is the\nkey in this case, while the object containing different personal information such as\nage, height and city, is the value to be stored in the hashtable.\n\n```js\nvar people = new Object();\npeople['Pedro'] = {\n    'age': 25,\n    'height': 1.67,\n    'city': 'Belo Horizonte'\n};\n```\n\nThis pattern of using strings as keys is very common in\nall sorts of situations. That is why the Zig Standard Library offers a\nspecific type of hashtable for this purpose, which is created through the `StringHashMap()` function.\nThis function creates a hashtable that uses strings as keys. The only input of this\nfunction is the data type of the values that will be stored into this hashtable.\n\nIn the example below, I'm creating a hashtable to store the ages of different people.\nEach key in this hashtable is represented by the name of each person, while the value stored in the\nhashtable is the age of this person identified by the key.\n\nThat is why I provide the `u8` data type (which is the data type used by the age values) as input to this `StringHashMap()` function.\nAs the result, it creates a hashtable that uses string values as keys, and, that stores\n`u8` values in it. Notice that an allocator object is provided at the `init()` method of the\nresulting object from the `StringHashMap()` function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var ages = std.StringHashMap(u8).init(allocator);\n    defer ages.deinit();\n\n    try ages.put(\"Pedro\", 25);\n    try ages.put(\"Matheus\", 21);\n    try ages.put(\"Abgail\", 42);\n\n    var it = ages.iterator();\n    while (it.next()) |kv| {\n        std.debug.print(\"Key: {s} | \", .{kv.key_ptr.*});\n        std.debug.print(\"Age: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n:::\n\n\n\n\n```\nKey: Pedro | Age: 25\nKey: Abgail | Age: 42\nKey: Matheus | Age: 21\n```\n\n\n### The `StringArrayHashMap` hashtable\n\nThe Zig Standard Library also provides a type of hashtable that mix the cons and pros of the\n`StringHashMap` and `ArrayHashMap` together. That is, a hashtable\nthat uses strings as keys, but also have the advantages from `ArrayHashMap`.\nIn other words, you can have a hashtable that is fast to iterate over,\nthat preserves insertion order, and also, that uses strings as keys.\n\nYou can create such type of hashtable by using the `StringArrayHashMap()` function.\nThis function accepts a data type as input, which is the data type of the values that are\ngoing to be stored inside this hashtable, in the same style as the function presented\nat @sec-string-hash-map.\n\nYou can insert new values into this hashtable by using the same `put()` method that\nwe have discussed at @sec-string-hash-map. And you can also get values from the hashtable\nby using the same `get()` method.\nLike its `ArrayHashMap` brother, to delete values from this specific type of hashtable,\nwe also use the `orderedRemove()` and `swapRemove()` methods, with the same effects that\nI have described at @sec-array-map.\n\nIf we take the code example that was exposed at @sec-string-hash-map, we can\nachieve the exact same result with `StringArrayHashMap()`:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar ages = std.StringArrayHashMap(u8).init(allocator);\n```\n:::\n\n\n\n\n\n\n\n## Linked lists\n\nThe Zig Standard Library provides an implementation for both singly and doubly linked lists.\nA linked list is a linear data structure that looks like a chain, or, a rope.\nThe main advantage of this data structure is that you normally have very fast\ninsertion and deletion operations. But, as a disadvantage, iterating through\nthis data structure is usually not so fast as iterating through an array.\n\nThe idea behind a linked list is to build a structure that consists of a sequence of nodes\nconnected to each other by pointers. This means that linked lists are usually not contiguous\nin memory, because each node might be anywhere in memory. They do not need to be close to\none another.\n\nAt @fig-linked-list we can see a diagram of a singly linked list. We begin at the first node\n(which is usually called \"the head of the linked list\"). Then, from this\nfirst node we uncover the remaining nodes in the structure, by following the locations pointed\nby the pointers found in each node.\n\nEach node has two things in it. It has the value that is stored in the current node\n, and also, a pointer. This pointer points to the next node in the list. If this pointer\nis null, then, it means that we have reached the end of our linked list.\n\n![A diagram of a singly linked list.](./../Figures/linked-list.png){#fig-linked-list}\n\n\nAt @fig-linked-list2 we can see a diagram of a doubly linked list. The only thing that really\nchanges now is that every node in the linked list has both a pointer to the previous node,\nand, a pointer to the next node. So every node in a doubly linked list has two pointers in it. These are\nusually called the `prev` (for \"previous\") and the `next` (for \"next\") pointers of the node.\n\nIn the singly linked list example, we had only one single pointer in each node, and this singular\npointer was always pointing to the next node in the sequence. This means that singly linked lists\nnormally have only the `next` pointer in them.\n\n![A diagram of a doubly linked list.](./../Figures/doubly-linked-list.png){#fig-linked-list2}\n\n\nLinked lists are available in Zig through the functions `SinglyLinkedList()` and\n`DoublyLinkedList()`, for \"singly linked lists\" and \"doubly linked lists\", respectively. These functions are\nactually generic functions, which we are going to talk more about at @sec-generic-fun.\n\nFor now, just understand that, in order to create a linked list object,\nwe begin by providing a data type to these functions. This data type defines\nthe type of data that each node in this linked list will store. In the example below,\nwe are creating a singly linked list of `u32` values.\nSo each node in this linked list will store a `u32` value.\n\nBoth the `SinglyLinkedList()` and `DoublyLinkedList()` functions returns a type,\ni.e. a struct definition, as output. Therefore, the object `Lu32` is actually\na struct definition. It defines the type \"singly linked list of `u32` values\".\n\nNow that we have the definition of the struct, we need to instantiate a `Lu32` object.\nWe normally instantiate struct objects in Zig by using an `init()` method.\nBut in this case, we are instantiating the struct directly, by using an empty\n`struct` literal, in the expression `Lu32{}`.\n\nIn this example, we first create multiple node objects, and after we create them,\nwe start to insert and connect these nodes to build the linked list, using the\n`prepend()` and `insertAfter()` methods. Notice that the `prepend()` method\nis a method from the linked list object, while the `insertAfter()` is a method\npresent in the node objects.\n\nIn essence, the `prepend()` method inserts a node at the beginning of the linked\nlist. In other words, the node that you provide to this method, becomes the new\n\"head node\" of the linked list. It becomes the first node in the list (see @fig-linked-list).\n\nOn the other side, the `insertAfter()` method is used to basically connect two nodes together.\nWhen you provide a node to this method, it creates a pointer to this input node,\nand stores this pointer in the `next` attribute of the current node, from which the method was called from.\n\nBecause doubly linked lists have both a `next` and a `prev` attributes in each node\n(as described at @fig-linked-list2), a node object created from\na `DoublyLinkedList` object have both an `insertBefore()` (for `prev`)\nand an `insertAfter()` (for `next`) methods available.\n\nThus, if we have used a doubly linked list, we can use the `insertBefore()` method\nto store the pointer to the input node in the `prev` attribute. This would put the input\nnode as the \"previous node\", or, the node before the current node. In contrast, the `insertAfter()` method\nputs the pointer created to the input node in the `next` attribute of the current node,\nand as result, the input node becomes the \"next node\" of the current node.\n\nSince we are using a singly linked list in this example, we have only the `insertAfter()` method\navailable in the node objects that we create from our `Lu32` type.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SinglyLinkedList = std.SinglyLinkedList;\nconst Lu32 = SinglyLinkedList(u32);\n\npub fn main() !void {\n    var list = Lu32{};\n    var one = Lu32.Node{ .data = 1 };\n    var two = Lu32.Node{ .data = 2 };\n    var three = Lu32.Node{ .data = 3 };\n    var four = Lu32.Node{ .data = 4 };\n    var five = Lu32.Node{ .data = 5 };\n\n    list.prepend(&two); // {2}\n    two.insertAfter(&five); // {2, 5}\n    list.prepend(&one); // {1, 2, 5}\n    two.insertAfter(&three); // {1, 2, 3, 5}\n    three.insertAfter(&four); // {1, 2, 3, 4, 5}\n}\n```\n:::\n\n\n\n\n\nThere are other methods available from the linked list object, depending if this object is\na singly linked list or a doubly linked list, that might be very useful for you. You can find a\nsummary of them in the bullet points below:\n\n- `remove()` to remove a specific node from the linked list.\n- if singly linked list, `len()` to count how many nodes there is in the linked list.\n- if doubly linked list, checkout the `len` attribute to see how many nodes there is in the linked list.\n- if singly linked list, `popFirst()` to remove the first node (i.e. the \"head\") from the linked list.\n- if doubly linked list, `pop()` and `popFirst()` to remove the last and first nodes from the linked list, respectively.\n- if doubly linked list, `append()` to add a new node to end of the linked list (i.e. inverse of `prepend()`).\n\n\n\n## Multi array structure\n\nZig introduces a new data structure called `MultiArrayList()`. It is a different version of the dynamic array\nthat we have introduced at @sec-dynamic-array. The difference between this structure and the `ArrayList()`\nthat we know from @sec-dynamic-array, is that `MultiArrayList()` creates a separate dynamic array\nfor each field of the struct that you provide as input.\n\nConsider the following code example. We create a new custom struct called `Person`. This\nstruct contains three different data members, or, three different fields. As consequence,\nwhen we provide this `Person` data type as input to `MultiArrayList()`, this\ncreates a \"struct of three different arrays\" called `PersonArray`. In other words,\nthis `PersonArray` is a struct that contains three internal dynamic arrays in it.\nOne array for each field found in the `Person` struct definition.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Person = struct {\n    name: []const u8,\n    age: u8,\n    height: f32,\n};\nconst PersonArray = std.MultiArrayList(Person);\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var people = PersonArray{};\n    defer people.deinit(allocator);\n\n    try people.append(allocator, .{\n        .name = \"Auguste\", .age = 15, .height = 1.54\n    });\n    try people.append(allocator, .{\n        .name = \"Elena\", .age = 26, .height = 1.65\n    });\n    try people.append(allocator, .{\n        .name = \"Michael\", .age = 64, .height = 1.87\n    });\n}\n```\n:::\n\n\n\n\nIn other words, instead of creating an array of \"persons\", the `MultiArrayList()` function\ncreates a \"struct of arrays\". Each data member of this struct is a different array that stores\nthe values of a specific field from the `Person` values that were added (or, appended) to this \"struct of arrays\".\nOne important detail is that each of these separate internal arrays stored inside `PersonArray`\nare dynamic arrays. This means that these arrays can grow in capacity automatically as needed, to accomodate\nmore values.\n\nThe @fig-multi-array exposed below presents a diagram that describes the `PersonArray` struct\nthat we have created in the previous code example. Notice that the values of the data members\npresent in each of the three `Person` values that we have appended into the `PersonArray` object\n, are scattered across three different internal arrays of the `PersonArray` object.\n\n![A diagram of the `PersonArray` struct.](./../Figures/multi-array.png){#fig-multi-array}\n\nYou can easily access each of these arrays separately, and iterate over the values of each array.\nFor that, you will need to call the `items()` method from the `PersonArray` object, and provide as input\nto this method, the name of the field that you want to iterate over.\nIf you want to iterate through the `.age` array for example, then, you need to call `items(.age)` from\nthe `PersonArray` object, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (people.items(.age)) |*age| {\n    try stdout.print(\"Age: {d}\\n\", .{age.*});\n}\n```\n:::\n\n\n\n\n```\nAge: 15\nAge: 26\nAge: 64\n```\n\n\nIn the above example, we are iterating over the values of the `.age` array, or,\nthe internal array of the `PersonArray` object that contains the values of the `age`\ndata member from the `Person` values that were added to the multi array struct.\n\nIn this example we are calling the `items()` method directly from the `PersonArray`\nobject. However, it is recommended on most situations to call this `items()` method\nfrom a \"slice object\", which you can create from the `slice()` method.\nThe reason for this is that calling `items()` multiple times have better performance\nif you use a slice object.\n\nTherefore, if you are planning to access only one of the\ninternal arrays from your \"multi array struct\", it is fine to call `items()` directly\nfrom the multi array object. But if you need to access many of the internal arrays\nfrom your \"multi array struct\", then, you will likely need to call `items()` more\nthan once, and, in such circumstance, is better to call `items()` through a slice object.\nThe example below demonstrates the use of such object:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar slice = people.slice();\nfor (slice.items(.age)) |*age| {\n    age.* += 10;\n}\nfor (slice.items(.name), slice.items(.age)) |*n,*a| {\n    try stdout.print(\n        \"Name: {s}, Age: {d}\\n\", .{n.*, a.*}\n    );\n}\n```\n:::\n\n\n\n\n```\nName: Auguste, Age: 25\nName: Elena, Age: 36\nName: Michael, Age: 74\n```\n\n\n## Conclusion\n\nThere are many other data structures that I haven't presented here.\nBut you can check them out at the official Zig Standard Library documentation page.\nActually, when you get into the [homepage of the documentation](https://ziglang.org/documentation/master/std/#)[^home], the first thing\nthat appears to you in this page, is a list of types and data structures that\nare available in the Zig Standard Library.\nThere are some very specific data structures in this list, like a\n[`BoundedArray` struct](https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray)[^bounded]\n, but there is also some more general structures, such as a\n[`PriorityQueue` struct](https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue)[^priority].\n\n\n[^home]: <https://ziglang.org/documentation/master/std/#>\n[^priority]: <https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue>.\n[^bounded]: <https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray>\n\n\n\n\n\n\n",
+    "supporting": [
+      "09-data-structures_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/10-stack-project/execute-results/html.json b/_freeze/Chapters/10-stack-project/execute-results/html.json
index 8835df3a..45ec4bce 100644
--- a/_freeze/Chapters/10-stack-project/execute-results/html.json
+++ b/_freeze/Chapters/10-stack-project/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "aa5d168604f4fcb0ae811071177c31fe",
+  "hash": "0c651ab91f56f6b099ea4bfebc8882dd",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 3 - Building a stack data structure\n\nIn this chapter we are going to implement a stack data structure as our next small project\nin this book. Implementing basic data structures in any language is kind of a\n\"kindergarten task\" (if this term even exist) in computer science (CS), because\nwe normally learn and implement them in the first semesters of CS.\n\nBut this is actually good! Since this should be a very easy task, we don't need much to explain\nwhat a stack is, then, we can concentrate on what is really important here, which is learning\nhow the concept of \"generics\" is implemented in the Zig language, and how one of the key\nfeatures of Zig, which is comptime, works, and use the stack data structure to demonstrate\nthese concepts on the fly.\n\nBut before we get into building the stack data structure, we first need to understand\nwhat the `comptime` keyword does to your code, and after that, we also need to learn about\nhow generics work in Zig.\n\n\n## Understanding `comptime` in Zig {#sec-comptime}\n\nOne of the key features of Zig is `comptime`. This keyword introduces a whole\nnew concept and paradigm, that is tightly connected with the compilation process.\nAt @sec-compile-time we have described the importance and the role that \"compile-time versus runtime\"\nplays into Zig. At that section, we learned that the rules applied to a value/object change\na lot depending on whether this value is known at compile-time, or just at runtime.\n\nThe `comptime` keyword is strongly related to these two spaces in time (compile-time and runtime).\nLet's quickly recap the differences. Compile-time is the period of time when your\nZig source code is being compiled by the `zig` compiler, while the runtime is\nthe period of time when your Zig program is being executed, i.e. when we execute\nthe binary files that were generated by the `zig` compiler.\n\nThere are three ways in which you can apply the `comptime` keyword, which are:\n\n- apply `comptime` on a function argument.\n- apply `comptime` on an object.\n- apply `comptime` on a block of expressions.\n\n\n\n### Applying over a function argument\n\nWhen you apply the `comptime` keyword on a function argument, you are saying to the `zig` compiler\nthat the value assigned to that particular function argument must be known at compile-time.\nWe explained in details at @sec-compile-time what exactly \"value known at compile-time\" means, so,\nin case you have doubts about this idea, come back to that section.\n\nNow let's think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement\nto that particular function argument. If the programmer accidentally tries to give a value to this\nfunction argument that is not known at compile time, the `zig` compiler will notice this problem, and\nas a consequence, it will raise a compilation error saying that it cannot compile your program. Because\nyou are providing a value that is \"runtime known\" to a function argument that must be \"compile-time known\".\n\nTake a look at this very simple example below, where we define a `twice()` function, that simply\ndoubles the input value named `num`. Notice that we use the `comptime` keyword before the name\nof the function argument. This keyword is marking the function argument `num` as a \"comptime argument\".\n\nThat is a function argument whose value must be compile-time known. This is why the expression\n`twice(5678)` is valid, and no compilation errors are raised. Because the value `5678`\nis compile-time known, so this is the expected behaviour for this function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file1054863994c6f.test.test comptime...OKAll 1\n  1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\nBut what if we provide a number that is not compile-time known to this function?\nFor example, we might provide a different input value to this function depending\non the target OS of our compilation process. The code example below demonstrates such case.\n\nBecause the value of the object `n` is determined at runtime, we cannot provide this object\nas input to the `twice()` function. The `zig` compiler will not allow it, because we marked\nthe `num` argument as a \"comptime argument\". That is why the `zig` compiler raises\nthe compile-time error exposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    var n: u32 = undefined;\n    if (builtin.target.os.tag == .windows) {\n        n = 1234;\n    } else {\n        n = 5678;\n    }\n    _ = twice(n);\n}\n```\n:::\n\n\n\n\n```\nt.zig:12:16: error: runtime-known argument passed to comptime parameter \n```\n\nComptime arguments are frequently used on functions that return some sort\nof generic structure. In fact, `comptime` is the essence (or the basis) to make generics in Zig.\nWe are going to talk more about generics at @sec-generics.\n\nFor now, let's take a look at this code example from @karlseguin_generics. You\ncan see that this `IntArray()` function have one argument named `length`.\nThis argument is marked as comptime, and receives a value of type `usize` as input. So the value given to this argument\nmust be compile-time known.\nWe can also see that this function returns an array of `i64` values as output.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n```\n:::\n\n\n\n\nNow, the key component of this function is the `length` argument. This argument\nis used to determine the size of the array that is produced by the function. Let's\nthink about the consequences of that. If the size of the array is dependent on\nthe value assigned to the `length` argument, this means that the data type of the\noutput of the function depends on the value of this `length` argument.\n\nLet this statement sink for a bit in your mind. As I described at @sec-root-file,\nZig is a strongly-typed language, especially on function declarations.\nSo every time we write a function in Zig, we have to annotate the data type of\nthe value returned by the function. But how can we do that, if this data type\ndepends on the value given to the argument of the function?\n\nThink about this for a second. If `length` is equal to 3 for example, then, the\nreturn type of the function is `[3]i64`. But if `length` is equal to 40, then,\nthe return type becomes `[40]i64`. At this point the `zig` compiler would be confused,\nand raise a compilation error, saying something like this:\n\n> Hey! You have annotated that this function should return a `[3]i64` value, but I got a `[40]i64` value instead! This doesn't look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when\nthe `type` keyword comes in. This `type` keyword is basically saying to the\n`zig` compiler that this function will return some data type as output, but it doesn't know yet\nwhat exactly data type that is. We will talk more about this at @sec-generics.\n\n\n\n### Applying over an expression\n\nWhen you apply the `comptime` keyword over an expression, then, it is guaranteed that the `zig` compiler will\nexecute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time\n(e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the `zig` compiler\nwill raise a compilation error.\n\nTake this example from the official documentation of Zig [@zigdocs]. We\nare executing the same `fibonacci()` function both at runtime, and, at compile-time.\nThe function is by default executed at runtime, but because we use the `comptime`\nkeyword at the second \"try expression\", this expression is executed at compile-time.\n\nThis might be a bit confusing for some people. Yes! When I say that this expression\nis executed at compile-time, I mean that this expression is compiled and executed\nwhile the `zig` compiler is compiling your Zig source code.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file10548bb87337.test.fibonacci...OKAll 1 test\n  ts passed.\n```\n\n\n:::\n:::\n\n\n\n\nA lot of your Zig source code might be potentially executed at compile-time,\nbecause the `zig` compiler can figure it out the output of some expressions.\nEspecially if these expressions depends only at compile-time known values.\nWe have talked about this at @sec-compile-time.\n\nBut when you use the `comptime` keyword on an expression, there is no \"it might be executed\nat compile-time\" anymore. With the `comptime` keyword you are ordering the `zig` compiler\nto execute this expression at compile-time. You are imposing this rule, it is guaranteed\nthat the compiler will always execute it at compile-time. Or, at least, the compiler\nwill try to execute it. If the compiler cannot execute the expression for whatever reason,\nthe compiler will raise a compilation error.\n\n\n### Applying over a block\n\nBlocks were described at @sec-blocks. When you apply the `comptime` keyword over a\nblock of expressions, you get essentially the same effect when you apply this keyword to\na single expression. That is, the entire block of expressions is executed at\ncompile-time by the `zig` compiler.\n\nIn the example below, we mark the block labeled of `blk` as a comptime block,\nand, therefore, the expressions inside this block are executed at compile-time.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file105482dc0b880.test.fibonacci in a block...\n  .OKAll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## Introducing Generics {#sec-generics}\n\nFirst of all, what is a generic? Generic is the idea to allow a type\n(`f64`, `u8`, `u32`, `bool`, and also, user-defined types, like the `User` struct\nthat we defined at @sec-structs-and-oop) to be a parameter to methods, classes and\ninterfaces [@geeks_generics]. In other words, a \"generic\" is a class (or a method) that can work\nwith multiple data types.\n\nFor example, in Java, generics are created through the operator `<>`. With this operator,\na Java class is capable of receiving a data type as input, and therefore, the class can fit\nits features according to this input data type.\nAs another example, generics in C++ are supported through the concept of templates.\nClass templates in C++ are generics.\n\nIn Zig, generics are implemented through `comptime`. The `comptime` keyword\nallows us to collect a data type at compile time, and pass this data type as\ninput to a piece of code.\n\n\n### A generic function {#sec-generic-fun}\n\nTake the `max()` function exposed below as a first example.\nThis function is essentially a \"generic function\".\nIn this function, we have a comptime function argument named `T`.\nNotice that this `T` argument have a data type of `type`. Weird right? This `type` keyword is the\n\"father of all types\", or, \"the type of types\" in Zig.\n\nBecause we have used this `type` keyword in the `T` argument, we are telling\nthe `zig` compiler that this `T` argument will receive some data type as input.\nAlso notice the use of the `comptime` keyword in this argument.\nAs I described at @sec-comptime, every time you use this keyword in a function argument,\nthis means that the value of this argument must be known at compile-time.\nThis makes sense, right? Because there is no data type that is not known at compile-time.\n\nThink about this. Every data type that you will ever write is always\nknown at compile-time. Especially because data types are an essential\ninformation for the compiler to actually compile your source code.\nHaving this in mind, makes sense to mark this argument as a comptime argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nAll 0 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\nAlso notice that the value of the `T` argument is actually used\nto define the data type of the other arguments in the function, `a` and `b`, and also at the\nreturn type annotation of the function.\nThat is, the data type of these arguments (`a` and `b`), and, the return data type of the function itself,\nare determined by the input value given to the `T` argument.\n\nAs a result, we have a generic function that works with different data types.\nFor example, I can provide `u8` values to this `max()` function, and it will work as expected.\nBut if I provide `f64` values instead, it will also work as expected.\nWithout a generic function, I would have to write a different `max()` function\nfor each one of the data types that I wanted to use.\nThis generic function provides a very useful shortcut for us.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\ntest \"test max\" {\n    const n1 = max(u8, 4, 10);\n    std.debug.print(\"Max n1: {d}\\n\", .{n1});\n    const n2 = max(f64, 89.24, 64.001);\n    std.debug.print(\"Max n2: {d}\\n\", .{n2});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file105482071daf3.test.test max...Max n1: 10Ma\n  ax n2: 89.24OKAll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n```\nMax n1: 10\nMax n2: 89.24\n```\n\n\n\n### A generic data structure {#sec-generic-struct}\n\nEvery data structure that you find in the Zig Standard Library (e.g. `ArrayList`, `HashMap`, etc.)\nis essentially a generic data structure.\nThese data structures are generic in the sense that they work with any data type you want.\nYou just say which is the data type of the values that are going to be stored in this data\nstructure, and they just work as expected.\n\nA generic data structure in Zig is how you replicate a generic class from Java,\nor, a class template from C++. But you may quest yourself: how do we build a\ngeneric data structure in Zig?\n\nThe basic idea is to write a generic function that creates the data structure definition\nfor the specific type we want. In other words, this generic function behaves as a \"factory of data structures\".\nThe generic function outputs the `struct` definition that defines this data structure for a\nspecific data type.\n\nTo create such function, we need to add a comptime argument to this function that receives a data type\nas input. We already learned how to do this at the previous section (@sec-generic-fun).\nI think the best way to demonstrate how to create a generic data structure is to actually write one.\nThis where we go into our next small project in this book. This one is a very small project,\nwhich is to write a generic stack data structure.\n\n\n\n\n## What is a stack? {#sec-what-stack}\n\nA stack data structure is a structure that follows a LIFO (*last in, first out*) principle.\nOnly two operations are normally supported in a stack data structure, which are `push` and `pop`.\nThe `push` operation is used to add new values to the stack, while `pop` is used to remove\nvalues from the stack.\n\nWhen people try to explain how the stack data structure works, the most common analogy\nthat they use is a stack of plates. Imagine that you have a stack of plates,\nfor example, a stack of 10 plates in your table. Each plate represents a value that\nis currently stored in this stack.\n\nWe begin with a stack of 10 different values, or 10 different plates. Now, imagine that you want to\nadd a new plate (or a new value) to this stack, which translates to the `push` operation.\nYou would add this plate (or this value) by just putting the new plate\non the top of the stack. Then, you would increase the stack to 11 plates.\n\nBut how would you remove plates (or remove values) from this stack (a.k.a. the `pop` operation) ?\nTo do that, we would have to remove the plate on the top of the stack, and, as a result, we would\nhave, once again, 10 plates in the stack.\n\nThis demonstrates the LIFO concept, because the first plate in the stack, which is the plate\nin the bottom of the stack, is always the last plate to get out of the stack. Think about it. In order\nto remove this specific plate from the stack, we have to remove all plates in the\nstack. So every operation in the stack, either insertion or deletion, is always made at the top of the stack.\nThe @fig-stack below exposes this logic visually:\n\n![A diagram of a stack structure. Source: Wikipedia, the free encyclopedia.](./../Figures/lifo-stack.svg){#fig-stack}\n\n\n\n## Writing the stack data structure\n\nWe are going to write the stack data structure in two steps. First, we are going\nto implement a stack that can only store `u32` values. Then, after that, we are going\nto extend our implementation to make it generic, so that it works with any data type\nwe want.\n\nFirst, we need to decide how the values will be stored inside the stack. There are multiple\nways to implement the storage behind a stack structure. Some people prefer to use a doubly linked list,\nsome others prefer to use a dynamic array, etc. In this example we are going to use an array behind the hood,\nto store the values in the stack, which is the `items` data member of our `Stack` struct definition.\n\nAlso notice in our `Stack` struct that we have three other data members: `capacity`, `length` and `allocator`.\nThe `capacity` member contains the capacity of the underlying array that stores the values in the stack.\nThe `length` contains the number of values that are currently being stored in the stack.\nAnd the `allocator` contains the allocator object that will be used by the stack structure whenever it\nneeds to allocate more space for the values that are being stored.\n\nWe begin by defining an `init()` method of this struct, which is going to be\nresponsible for instantiating a `Stack` object. Notice that, inside this\n`init()` method, we start by allocating an array with the capacity specified\nin the `capacity` argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst Stack = struct {\n    items: []u32,\n    capacity: usize,\n    length: usize,\n    allocator: Allocator,\n\n    pub fn init(allocator: Allocator, capacity: usize) !Stack {\n        var buf = try allocator.alloc(u32, capacity);\n        return .{\n            .items = buf[0..],\n            .capacity = capacity,\n            .length = 0,\n            .allocator = allocator,\n        };\n    }\n};\n```\n:::\n\n\n\n\n\n### Implementing the `push` operation\n\nNow that we have written the basic logic to create a new `Stack` object,\nwe can start writing the logic responsible for performing a push operation.\nRemember, a push operation in a stack data structure is the operation\nresponsible for adding a new value to the stack.\n\nSo how can we add a new value to the `Stack` object that we have?\nThe `push()` function exposed below is a possible answer to this question.\nRemember from what we discussed at @sec-what-stack that values are always added to the top of the stack.\nThis means that this `push()` function must always find the element in the underlying array\nthat currently represents the top position of the stack, and then, add the input value there.\n\nFirst, we have an if statement in this function. This if statement is\nchecking whether we need to expand the underlying array to store\nthis new value that we are adding to the stack. In other words, maybe\nthe underlying array does not have enough capacity to store this new\nvalue, and, in this case, we need to expand our array to get the capacity that we need.\n\nSo, if the logical test in this if statement returns true, it means that the array\ndoes not have enough capacity, and we need to expand it before we store this new value.\nSo inside this if statement we are executing the necessary expressions to expand the underlying array.\nNotice that we use the allocator object to allocate a new array that is twice as bigger\nthan the current array (`self.capacity * 2`).\n\nAfter that, we use a different built-in function named `@memcpy()`. This built-in function\nis equivalent to the `memcpy()` function from the C Standard Library[^cmemcpy]. It is used to\ncopy the values from one block of memory to another block of memory. In other words,\nyou can use this function to copy the values from one array into another array.\n\n[^cmemcpy]: <https://www.tutorialspoint.com/c_standard_library/c_function_memcpy.htm>\n\nWe are using this `@memcpy()` built-in function to copy the values that are currently stored\nin the underlying array of the stack object (`self.items`) into our new and bigger array that\nwe have allocated (`new_buf`). After we execute this function, the `new_buf` contains a copy\nof the values that are present at `self.items`.\n\nNow that we have secured a copy of our current values in the `new_buf` object, we\ncan now free the memory currently allocated at `self.items`. After that, we just need\nto assign our new and bigger array to `self.items`. This is the sequence\nof steps necessary to expand our array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn push(self: *Stack, val: u32) !void {\n    if ((self.length + 1) > self.capacity) {\n        var new_buf = try self.allocator.alloc(\n            u32, self.capacity * 2\n        );\n        @memcpy(\n            new_buf[0..self.capacity], self.items\n        );\n        self.allocator.free(self.items);\n        self.items = new_buf;\n        self.capacity = self.capacity * 2;\n    }\n\n    self.items[self.length] = val;\n    self.length += 1;\n}\n```\n:::\n\n\n\n\nAfter we make sure that we have enough room to store this new value\nthat we are adding to the stack, all we have to do is to assign\nthis value to the top element in this stack, and, increase the\nvalue of the `length` attribute by one. We find the top element\nin the stack by using the `length` attribute.\n\n\n\n### Implementing the `pop` operation\n\nNow we can implement the pop operation of our stack object.\nThis is a much easier operation to implement, and the `pop()` method below summarises\nall the logic that is needed.\n\nWe just have to find the element in the underlying array that currently represents the top\nof the stack, and set this element to \"undefined\", to indicate that\nthis element is \"empty\". After that, we also need to decrease\nthe `length` attribute of the stack by one.\n\nIf the current length of the stack is zero, it means that there is\nno values being stored in the stack currently. So, in this case,\nwe could just return from the function and do nothing really.\nThis is what the if statement inside this function is checking for.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn pop(self: *Stack) void {\n    if (self.length == 0) return;\n\n    self.items[self.length - 1] = undefined;\n    self.length -= 1;\n}\n```\n:::\n\n\n\n\n\n\n### Implementing the `deinit` method\n\nWe have implemented the methods responsible for the two main operations\nassociated with the stack data structure, which is `pop()` and `push()`,\nand we also have implemented the method responsible for instantiating\na new `Stack` object, which is the `init()` method.\n\nBut now, we need to implement also the method responsible for destroying\na `Stack` object. In Zig, this task is commonly associated with the method\nnamed `deinit()`. Most struct objects in Zig have such method, and it\nis commonly nicknamed \"the destructor method\".\n\nIn theory, all we have to do to destroy the `Stack` object is to make\nsure that we free the allocated memory for the underlying array, using\nthe allocator object that is stored inside the `Stack` object.\nThis is what the `deinit()` method below is doing.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn deinit(self: *Stack) void {\n    self.allocator.free(self.items);\n}\n```\n:::\n\n\n\n\n\n\n\n## Making it generic\n\nNow that we have implemented the basic skeleton of our stack data structure,\nwe can now focus on discussing how can we make it generic. How can we make\nthis basic skeleton to work not only with `u32` values, but also, with any other\ndata type we want?\nFor example, we might need to create a stack object to store `User` values\nin it. How can we make this possible? The answer lies on the use of generics\nand `comptime`.\n\nAs I described at @sec-generic-struct, the basic idea is to write a generic\nfunction that returns a struct definition as output.\nIn theory, we do not need much to transform our `Stack` struct into a generic\ndata structure. All that we need to do is to transform the underlying array\nof the stack into a generic array.\n\nIn other words, this underlying array needs to be a \"chameleon\". It needs to adapt,\nand transform it into an array of any data type that we want. For example, if we need to create\na stack that will store `u8` values, then, this underlying array needs to be\na `u8` array (i.e. `[]u8`). But if we need to store `User` values instead, then,\nthis array needs to be a `User` array (i.e. `[]User`). Etc.\n\nWe do that by using a generic function. Because a generic function can receive a data type\nas input, and we can pass this data type to the struct definition of our `Stack` object.\nTherefore, we can use the generic function to create a `Stack` object that can store\nthe data type we want. If we want to create a stack structure that stores `User` values,\nwe pass the `User` data type to this generic function, and it will create for us\nthe struct definition that describes a `Stack` object that can store `User` values in it.\n\nLook at the code example below. I have omitted some parts of the `Stack` struct definition\nfor brevity reasons. However, if a specific part of our `Stack` struct is not exposed here\nin this example, then it is because this part did not change from the previous example.\nIt remains the same.\n\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn Stack(comptime T: type) type {\n    return struct {\n        items: []T,\n        capacity: usize,\n        length: usize,\n        allocator: Allocator,\n        const Self = @This();\n\n        pub fn init(allocator: Allocator,\n                    capacity: usize) !Stack(T) {\n            var buf = try allocator.alloc(T, capacity);\n            return .{\n                .items = buf[0..],\n                .capacity = capacity,\n                .length = 0,\n                .allocator = allocator,\n            };\n        }\n\n        pub fn push(self: *Self, val: T) !void {\n        // Truncate the rest of the struct\n    };\n}\n```\n:::\n\n\n\n\nNotice that we have created a function in this example named `Stack()`. This function\ntakes a type as input, and passes this type to the struct definition of our\n`Stack` object. The data member `items` is now, an array of type `T`, which is the\ndata type that we have provided as input to the function. The function argument\n`val` in the `push()` function is now a value of type `T` too.\n\nWe can just provide a data type to this function, and it will create a definition of a\n`Stack` object that can store values of the data type that we have provided. In the example below, we are creating\nthe definition of a\n`Stack` object that can store `u8` values in it. This definition is stored at the `Stacku8` object.\nThis `Stacku8` object becomes our new struct, it is the struct that we are going to use\nto create our `Stack` object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst Stacku8 = Stack(u8);\nvar stack = try Stacku8.init(allocator, 10);\ndefer stack.deinit();\ntry stack.push(1);\ntry stack.push(2);\ntry stack.push(3);\ntry stack.push(4);\ntry stack.push(5);\ntry stack.push(6);\n\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\"Stack capacity: {d}\\n\", .{stack.capacity});\n\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\n    \"Stack state: {any}\\n\",\n    .{stack.items[0..stack.length]}\n);\n```\n:::\n\n\n\n\n```\nStack len: 6\nStack capacity: 10\nStack len: 5\nStack len: 4\nStack state: { 1, 2, 3, 4, 0, 0, 0, 0, 0, 0 }\n```\n\nEvery generic data structure in the Zig Standard Library (`ArrayList`, `HashMap`, `SinlyLinkedList`, etc.)\nis implemented through this logic. They use a generic function to create the struct definition that can work\nwith the data type that you provided as input.\n\n\n\n\n## Conclusion\n\nThe full source code of the stack structure discussed in this chapter is freely available at the official\nrepository of this book. Just checkout the [`stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig)[^zig-stack]\nfor the `u32` version of our stack,\nand the [`generic_stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig)[^zig-stack2]\nfor the generic version, available inside the `ZigExamples` folder of the repository.\n\n\n[^zig-stack]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig>\n[^zig-stack2]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig>\n\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 3 - Building a stack data structure\n\nIn this chapter we are going to implement a stack data structure as our next small project\nin this book. Implementing basic data structures in any language is kind of a\n\"kindergarten task\" (if this term even exist) in computer science (CS), because\nwe normally learn and implement them in the first semesters of CS.\n\nBut this is actually good! Since this should be a very easy task, we don't need much to explain\nwhat a stack is, then, we can concentrate on what is really important here, which is learning\nhow the concept of \"generics\" is implemented in the Zig language, and how one of the key\nfeatures of Zig, which is comptime, works, and use the stack data structure to demonstrate\nthese concepts on the fly.\n\nBut before we get into building the stack data structure, we first need to understand\nwhat the `comptime` keyword does to your code, and after that, we also need to learn about\nhow generics work in Zig.\n\n\n## Understanding `comptime` in Zig {#sec-comptime}\n\nOne of the key features of Zig is `comptime`. This keyword introduces a whole\nnew concept and paradigm, that is tightly connected with the compilation process.\nAt @sec-compile-time we have described the importance and the role that \"compile-time versus runtime\"\nplays into Zig. At that section, we learned that the rules applied to a value/object change\na lot depending on whether this value is known at compile-time, or just at runtime.\n\nThe `comptime` keyword is strongly related to these two spaces in time (compile-time and runtime).\nLet's quickly recap the differences. Compile-time is the period of time when your\nZig source code is being compiled by the `zig` compiler, while the runtime is\nthe period of time when your Zig program is being executed, i.e. when we execute\nthe binary files that were generated by the `zig` compiler.\n\nThere are three ways in which you can apply the `comptime` keyword, which are:\n\n- apply `comptime` on a function argument.\n- apply `comptime` on an object.\n- apply `comptime` on a block of expressions.\n\n\n\n### Applying over a function argument\n\nWhen you apply the `comptime` keyword on a function argument, you are saying to the `zig` compiler\nthat the value assigned to that particular function argument must be known at compile-time.\nWe explained in details at @sec-compile-time what exactly \"value known at compile-time\" means, so,\nin case you have doubts about this idea, come back to that section.\n\nNow let's think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement\nto that particular function argument. If the programmer accidentally tries to give a value to this\nfunction argument that is not known at compile time, the `zig` compiler will notice this problem, and\nas a consequence, it will raise a compilation error saying that it cannot compile your program. Because\nyou are providing a value that is \"runtime known\" to a function argument that must be \"compile-time known\".\n\nTake a look at this very simple example below, where we define a `twice()` function, that simply\ndoubles the input value named `num`. Notice that we use the `comptime` keyword before the name\nof the function argument. This keyword is marking the function argument `num` as a \"comptime argument\".\n\nThat is a function argument whose value must be compile-time known. This is why the expression\n`twice(5678)` is valid, and no compilation errors are raised. Because the value `5678`\nis compile-time known, so this is the expected behaviour for this function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file1105a40478a9d.test.test comptime...OKAll 1\n  1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\nBut what if we provide a number that is not compile-time known to this function?\nFor example, we might provide a different input value to this function depending\non the target OS of our compilation process. The code example below demonstrates such case.\n\nBecause the value of the object `n` is determined at runtime, we cannot provide this object\nas input to the `twice()` function. The `zig` compiler will not allow it, because we marked\nthe `num` argument as a \"comptime argument\". That is why the `zig` compiler raises\nthe compile-time error exposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    var n: u32 = undefined;\n    if (builtin.target.os.tag == .windows) {\n        n = 1234;\n    } else {\n        n = 5678;\n    }\n    _ = twice(n);\n}\n```\n:::\n\n\n\n\n```\nt.zig:12:16: error: runtime-known argument passed to comptime parameter \n```\n\nComptime arguments are frequently used on functions that return some sort\nof generic structure. In fact, `comptime` is the essence (or the basis) to make generics in Zig.\nWe are going to talk more about generics at @sec-generics.\n\nFor now, let's take a look at this code example from @karlseguin_generics. You\ncan see that this `IntArray()` function have one argument named `length`.\nThis argument is marked as comptime, and receives a value of type `usize` as input. So the value given to this argument\nmust be compile-time known.\nWe can also see that this function returns an array of `i64` values as output.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n```\n:::\n\n\n\n\nNow, the key component of this function is the `length` argument. This argument\nis used to determine the size of the array that is produced by the function. Let's\nthink about the consequences of that. If the size of the array is dependent on\nthe value assigned to the `length` argument, this means that the data type of the\noutput of the function depends on the value of this `length` argument.\n\nLet this statement sink for a bit in your mind. As I described at @sec-root-file,\nZig is a strongly-typed language, especially on function declarations.\nSo every time we write a function in Zig, we have to annotate the data type of\nthe value returned by the function. But how can we do that, if this data type\ndepends on the value given to the argument of the function?\n\nThink about this for a second. If `length` is equal to 3 for example, then, the\nreturn type of the function is `[3]i64`. But if `length` is equal to 40, then,\nthe return type becomes `[40]i64`. At this point the `zig` compiler would be confused,\nand raise a compilation error, saying something like this:\n\n> Hey! You have annotated that this function should return a `[3]i64` value, but I got a `[40]i64` value instead! This doesn't look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when\nthe `type` keyword comes in. This `type` keyword is basically saying to the\n`zig` compiler that this function will return some data type as output, but it doesn't know yet\nwhat exactly data type that is. We will talk more about this at @sec-generics.\n\n\n\n### Applying over an expression\n\nWhen you apply the `comptime` keyword over an expression, then, it is guaranteed that the `zig` compiler will\nexecute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time\n(e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the `zig` compiler\nwill raise a compilation error.\n\nTake this example from the official documentation of Zig [@zigdocs]. We\nare executing the same `fibonacci()` function both at runtime, and, at compile-time.\nThe function is by default executed at runtime, but because we use the `comptime`\nkeyword at the second \"try expression\", this expression is executed at compile-time.\n\nThis might be a bit confusing for some people. Yes! When I say that this expression\nis executed at compile-time, I mean that this expression is compiled and executed\nwhile the `zig` compiler is compiling your Zig source code.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file1105a31c0f24f.test.fibonacci...OKAll 1 tes\n  sts passed.\n```\n\n\n:::\n:::\n\n\n\n\nA lot of your Zig source code might be potentially executed at compile-time,\nbecause the `zig` compiler can figure it out the output of some expressions.\nEspecially if these expressions depends only at compile-time known values.\nWe have talked about this at @sec-compile-time.\n\nBut when you use the `comptime` keyword on an expression, there is no \"it might be executed\nat compile-time\" anymore. With the `comptime` keyword you are ordering the `zig` compiler\nto execute this expression at compile-time. You are imposing this rule, it is guaranteed\nthat the compiler will always execute it at compile-time. Or, at least, the compiler\nwill try to execute it. If the compiler cannot execute the expression for whatever reason,\nthe compiler will raise a compilation error.\n\n\n### Applying over a block\n\nBlocks were described at @sec-blocks. When you apply the `comptime` keyword over a\nblock of expressions, you get essentially the same effect when you apply this keyword to\na single expression. That is, the entire block of expressions is executed at\ncompile-time by the `zig` compiler.\n\nIn the example below, we mark the block labeled of `blk` as a comptime block,\nand, therefore, the expressions inside this block are executed at compile-time.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file1105a37ca2b0d.test.fibonacci in a block...\n  .OKAll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## Introducing Generics {#sec-generics}\n\nFirst of all, what is a generic? Generic is the idea to allow a type\n(`f64`, `u8`, `u32`, `bool`, and also, user-defined types, like the `User` struct\nthat we defined at @sec-structs-and-oop) to be a parameter to methods, classes and\ninterfaces [@geeks_generics]. In other words, a \"generic\" is a class (or a method) that can work\nwith multiple data types.\n\nFor example, in Java, generics are created through the operator `<>`. With this operator,\na Java class is capable of receiving a data type as input, and therefore, the class can fit\nits features according to this input data type.\nAs another example, generics in C++ are supported through the concept of templates.\nClass templates in C++ are generics.\n\nIn Zig, generics are implemented through `comptime`. The `comptime` keyword\nallows us to collect a data type at compile time, and pass this data type as\ninput to a piece of code.\n\n\n### A generic function {#sec-generic-fun}\n\nTake the `max()` function exposed below as a first example.\nThis function is essentially a \"generic function\".\nIn this function, we have a comptime function argument named `T`.\nNotice that this `T` argument have a data type of `type`. Weird right? This `type` keyword is the\n\"father of all types\", or, \"the type of types\" in Zig.\n\nBecause we have used this `type` keyword in the `T` argument, we are telling\nthe `zig` compiler that this `T` argument will receive some data type as input.\nAlso notice the use of the `comptime` keyword in this argument.\nAs I described at @sec-comptime, every time you use this keyword in a function argument,\nthis means that the value of this argument must be known at compile-time.\nThis makes sense, right? Because there is no data type that is not known at compile-time.\n\nThink about this. Every data type that you will ever write is always\nknown at compile-time. Especially because data types are an essential\ninformation for the compiler to actually compile your source code.\nHaving this in mind, makes sense to mark this argument as a comptime argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\n```\n:::\n\n\n\n\nAlso notice that the value of the `T` argument is actually used\nto define the data type of the other arguments in the function, `a` and `b`, and also at the\nreturn type annotation of the function.\nThat is, the data type of these arguments (`a` and `b`), and, the return data type of the function itself,\nare determined by the input value given to the `T` argument.\n\nAs a result, we have a generic function that works with different data types.\nFor example, I can provide `u8` values to this `max()` function, and it will work as expected.\nBut if I provide `f64` values instead, it will also work as expected.\nWithout a generic function, I would have to write a different `max()` function\nfor each one of the data types that I wanted to use.\nThis generic function provides a very useful shortcut for us.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\ntest \"test max\" {\n    const n1 = max(u8, 4, 10);\n    std.debug.print(\"Max n1: {d}\\n\", .{n1});\n    const n2 = max(f64, 89.24, 64.001);\n    std.debug.print(\"Max n2: {d}\\n\", .{n2});\n}\n```\n:::\n\n\n\n\n```\nMax n1: 10\nMax n2: 89.24\n```\n\n\n### A generic data structure {#sec-generic-struct}\n\nEvery data structure that you find in the Zig Standard Library (e.g. `ArrayList`, `HashMap`, etc.)\nis essentially a generic data structure.\nThese data structures are generic in the sense that they work with any data type you want.\nYou just say which is the data type of the values that are going to be stored in this data\nstructure, and they just work as expected.\n\nA generic data structure in Zig is how you replicate a generic class from Java,\nor, a class template from C++. But you may quest yourself: how do we build a\ngeneric data structure in Zig?\n\nThe basic idea is to write a generic function that creates the data structure definition\nfor the specific type we want. In other words, this generic function behaves as a \"factory of data structures\".\nThe generic function outputs the `struct` definition that defines this data structure for a\nspecific data type.\n\nTo create such function, we need to add a comptime argument to this function that receives a data type\nas input. We already learned how to do this at the previous section (@sec-generic-fun).\nI think the best way to demonstrate how to create a generic data structure is to actually write one.\nThis where we go into our next small project in this book. This one is a very small project,\nwhich is to write a generic stack data structure.\n\n\n\n\n## What is a stack? {#sec-what-stack}\n\nA stack data structure is a structure that follows a LIFO (*last in, first out*) principle.\nOnly two operations are normally supported in a stack data structure, which are `push` and `pop`.\nThe `push` operation is used to add new values to the stack, while `pop` is used to remove\nvalues from the stack.\n\nWhen people try to explain how the stack data structure works, the most common analogy\nthat they use is a stack of plates. Imagine that you have a stack of plates,\nfor example, a stack of 10 plates in your table. Each plate represents a value that\nis currently stored in this stack.\n\nWe begin with a stack of 10 different values, or 10 different plates. Now, imagine that you want to\nadd a new plate (or a new value) to this stack, which translates to the `push` operation.\nYou would add this plate (or this value) by just putting the new plate\non the top of the stack. Then, you would increase the stack to 11 plates.\n\nBut how would you remove plates (or remove values) from this stack (a.k.a. the `pop` operation) ?\nTo do that, we would have to remove the plate on the top of the stack, and, as a result, we would\nhave, once again, 10 plates in the stack.\n\nThis demonstrates the LIFO concept, because the first plate in the stack, which is the plate\nin the bottom of the stack, is always the last plate to get out of the stack. Think about it. In order\nto remove this specific plate from the stack, we have to remove all plates in the\nstack. So every operation in the stack, either insertion or deletion, is always made at the top of the stack.\nThe @fig-stack below exposes this logic visually:\n\n![A diagram of a stack structure. Source: Wikipedia, the free encyclopedia.](./../Figures/lifo-stack.svg){#fig-stack}\n\n\n\n## Writing the stack data structure\n\nWe are going to write the stack data structure in two steps. First, we are going\nto implement a stack that can only store `u32` values. Then, after that, we are going\nto extend our implementation to make it generic, so that it works with any data type\nwe want.\n\nFirst, we need to decide how the values will be stored inside the stack. There are multiple\nways to implement the storage behind a stack structure. Some people prefer to use a doubly linked list,\nsome others prefer to use a dynamic array, etc. In this example we are going to use an array behind the hood,\nto store the values in the stack, which is the `items` data member of our `Stack` struct definition.\n\nAlso notice in our `Stack` struct that we have three other data members: `capacity`, `length` and `allocator`.\nThe `capacity` member contains the capacity of the underlying array that stores the values in the stack.\nThe `length` contains the number of values that are currently being stored in the stack.\nAnd the `allocator` contains the allocator object that will be used by the stack structure whenever it\nneeds to allocate more space for the values that are being stored.\n\nWe begin by defining an `init()` method of this struct, which is going to be\nresponsible for instantiating a `Stack` object. Notice that, inside this\n`init()` method, we start by allocating an array with the capacity specified\nin the `capacity` argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst Stack = struct {\n    items: []u32,\n    capacity: usize,\n    length: usize,\n    allocator: Allocator,\n\n    pub fn init(allocator: Allocator, capacity: usize) !Stack {\n        var buf = try allocator.alloc(u32, capacity);\n        return .{\n            .items = buf[0..],\n            .capacity = capacity,\n            .length = 0,\n            .allocator = allocator,\n        };\n    }\n};\n```\n:::\n\n\n\n\n\n### Implementing the `push` operation\n\nNow that we have written the basic logic to create a new `Stack` object,\nwe can start writing the logic responsible for performing a push operation.\nRemember, a push operation in a stack data structure is the operation\nresponsible for adding a new value to the stack.\n\nSo how can we add a new value to the `Stack` object that we have?\nThe `push()` function exposed below is a possible answer to this question.\nRemember from what we discussed at @sec-what-stack that values are always added to the top of the stack.\nThis means that this `push()` function must always find the element in the underlying array\nthat currently represents the top position of the stack, and then, add the input value there.\n\nFirst, we have an if statement in this function. This if statement is\nchecking whether we need to expand the underlying array to store\nthis new value that we are adding to the stack. In other words, maybe\nthe underlying array does not have enough capacity to store this new\nvalue, and, in this case, we need to expand our array to get the capacity that we need.\n\nSo, if the logical test in this if statement returns true, it means that the array\ndoes not have enough capacity, and we need to expand it before we store this new value.\nSo inside this if statement we are executing the necessary expressions to expand the underlying array.\nNotice that we use the allocator object to allocate a new array that is twice as bigger\nthan the current array (`self.capacity * 2`).\n\nAfter that, we use a different built-in function named `@memcpy()`. This built-in function\nis equivalent to the `memcpy()` function from the C Standard Library[^cmemcpy]. It is used to\ncopy the values from one block of memory to another block of memory. In other words,\nyou can use this function to copy the values from one array into another array.\n\n[^cmemcpy]: <https://www.tutorialspoint.com/c_standard_library/c_function_memcpy.htm>\n\nWe are using this `@memcpy()` built-in function to copy the values that are currently stored\nin the underlying array of the stack object (`self.items`) into our new and bigger array that\nwe have allocated (`new_buf`). After we execute this function, the `new_buf` contains a copy\nof the values that are present at `self.items`.\n\nNow that we have secured a copy of our current values in the `new_buf` object, we\ncan now free the memory currently allocated at `self.items`. After that, we just need\nto assign our new and bigger array to `self.items`. This is the sequence\nof steps necessary to expand our array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn push(self: *Stack, val: u32) !void {\n    if ((self.length + 1) > self.capacity) {\n        var new_buf = try self.allocator.alloc(\n            u32, self.capacity * 2\n        );\n        @memcpy(\n            new_buf[0..self.capacity], self.items\n        );\n        self.allocator.free(self.items);\n        self.items = new_buf;\n        self.capacity = self.capacity * 2;\n    }\n\n    self.items[self.length] = val;\n    self.length += 1;\n}\n```\n:::\n\n\n\n\nAfter we make sure that we have enough room to store this new value\nthat we are adding to the stack, all we have to do is to assign\nthis value to the top element in this stack, and, increase the\nvalue of the `length` attribute by one. We find the top element\nin the stack by using the `length` attribute.\n\n\n\n### Implementing the `pop` operation\n\nNow we can implement the pop operation of our stack object.\nThis is a much easier operation to implement, and the `pop()` method below summarises\nall the logic that is needed.\n\nWe just have to find the element in the underlying array that currently represents the top\nof the stack, and set this element to \"undefined\", to indicate that\nthis element is \"empty\". After that, we also need to decrease\nthe `length` attribute of the stack by one.\n\nIf the current length of the stack is zero, it means that there is\nno values being stored in the stack currently. So, in this case,\nwe could just return from the function and do nothing really.\nThis is what the if statement inside this function is checking for.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn pop(self: *Stack) void {\n    if (self.length == 0) return;\n\n    self.items[self.length - 1] = undefined;\n    self.length -= 1;\n}\n```\n:::\n\n\n\n\n\n\n### Implementing the `deinit` method\n\nWe have implemented the methods responsible for the two main operations\nassociated with the stack data structure, which is `pop()` and `push()`,\nand we also have implemented the method responsible for instantiating\na new `Stack` object, which is the `init()` method.\n\nBut now, we need to implement also the method responsible for destroying\na `Stack` object. In Zig, this task is commonly associated with the method\nnamed `deinit()`. Most struct objects in Zig have such method, and it\nis commonly nicknamed \"the destructor method\".\n\nIn theory, all we have to do to destroy the `Stack` object is to make\nsure that we free the allocated memory for the underlying array, using\nthe allocator object that is stored inside the `Stack` object.\nThis is what the `deinit()` method below is doing.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn deinit(self: *Stack) void {\n    self.allocator.free(self.items);\n}\n```\n:::\n\n\n\n\n\n\n\n## Making it generic\n\nNow that we have implemented the basic skeleton of our stack data structure,\nwe can now focus on discussing how can we make it generic. How can we make\nthis basic skeleton to work not only with `u32` values, but also, with any other\ndata type we want?\nFor example, we might need to create a stack object to store `User` values\nin it. How can we make this possible? The answer lies on the use of generics\nand `comptime`.\n\nAs I described at @sec-generic-struct, the basic idea is to write a generic\nfunction that returns a struct definition as output.\nIn theory, we do not need much to transform our `Stack` struct into a generic\ndata structure. All that we need to do is to transform the underlying array\nof the stack into a generic array.\n\nIn other words, this underlying array needs to be a \"chameleon\". It needs to adapt,\nand transform it into an array of any data type that we want. For example, if we need to create\na stack that will store `u8` values, then, this underlying array needs to be\na `u8` array (i.e. `[]u8`). But if we need to store `User` values instead, then,\nthis array needs to be a `User` array (i.e. `[]User`). Etc.\n\nWe do that by using a generic function. Because a generic function can receive a data type\nas input, and we can pass this data type to the struct definition of our `Stack` object.\nTherefore, we can use the generic function to create a `Stack` object that can store\nthe data type we want. If we want to create a stack structure that stores `User` values,\nwe pass the `User` data type to this generic function, and it will create for us\nthe struct definition that describes a `Stack` object that can store `User` values in it.\n\nLook at the code example below. I have omitted some parts of the `Stack` struct definition\nfor brevity reasons. However, if a specific part of our `Stack` struct is not exposed here\nin this example, then it is because this part did not change from the previous example.\nIt remains the same.\n\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn Stack(comptime T: type) type {\n    return struct {\n        items: []T,\n        capacity: usize,\n        length: usize,\n        allocator: Allocator,\n        const Self = @This();\n\n        pub fn init(allocator: Allocator,\n                    capacity: usize) !Stack(T) {\n            var buf = try allocator.alloc(T, capacity);\n            return .{\n                .items = buf[0..],\n                .capacity = capacity,\n                .length = 0,\n                .allocator = allocator,\n            };\n        }\n\n        pub fn push(self: *Self, val: T) !void {\n        // Truncate the rest of the struct\n    };\n}\n```\n:::\n\n\n\n\nNotice that we have created a function in this example named `Stack()`. This function\ntakes a type as input, and passes this type to the struct definition of our\n`Stack` object. The data member `items` is now, an array of type `T`, which is the\ndata type that we have provided as input to the function. The function argument\n`val` in the `push()` function is now a value of type `T` too.\n\nWe can just provide a data type to this function, and it will create a definition of a\n`Stack` object that can store values of the data type that we have provided. In the example below, we are creating\nthe definition of a\n`Stack` object that can store `u8` values in it. This definition is stored at the `Stacku8` object.\nThis `Stacku8` object becomes our new struct, it is the struct that we are going to use\nto create our `Stack` object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst Stacku8 = Stack(u8);\nvar stack = try Stacku8.init(allocator, 10);\ndefer stack.deinit();\ntry stack.push(1);\ntry stack.push(2);\ntry stack.push(3);\ntry stack.push(4);\ntry stack.push(5);\ntry stack.push(6);\n\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\"Stack capacity: {d}\\n\", .{stack.capacity});\n\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\n    \"Stack state: {any}\\n\",\n    .{stack.items[0..stack.length]}\n);\n```\n:::\n\n\n\n\n```\nStack len: 6\nStack capacity: 10\nStack len: 5\nStack len: 4\nStack state: { 1, 2, 3, 4, 0, 0, 0, 0, 0, 0 }\n```\n\nEvery generic data structure in the Zig Standard Library (`ArrayList`, `HashMap`, `SinlyLinkedList`, etc.)\nis implemented through this logic. They use a generic function to create the struct definition that can work\nwith the data type that you provided as input.\n\n\n\n\n## Conclusion\n\nThe full source code of the stack structure discussed in this chapter is freely available at the official\nrepository of this book. Just checkout the [`stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig)[^zig-stack]\nfor the `u32` version of our stack,\nand the [`generic_stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig)[^zig-stack2]\nfor the generic version, available inside the `ZigExamples` folder of the repository.\n\n\n[^zig-stack]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig>\n[^zig-stack2]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig>\n\n",
+    "supporting": [
+      "10-stack-project_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/docs/Chapters/02-debugging.html b/docs/Chapters/02-debugging.html
index 4463b19c..d6ff110e 100644
--- a/docs/Chapters/02-debugging.html
+++ b/docs/Chapters/02-debugging.html
@@ -360,13 +360,12 @@ <h2 data-number="5.1" class="anchored" data-anchor-id="print-debugging"><span cl
 <pre><code>Result: 50</code></pre>
 </div>
 </div>
-<pre><code>Result: 50</code></pre>
 <p>You could also achieve the exact same result by getting a file descriptor object to <code>stderr</code>, then, creating a <em>writer</em> object to <code>stderr</code>, then, using the <code>print()</code> method of this <em>writer</em> object, like in the example below:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb6"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb6-2"><a href="#cb6-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stderr = std.io.getStdErr().writer();</span>
-<span id="cb6-3"><a href="#cb6-3" aria-hidden="true" tabindex="-1"></a><span class="co">// some more lines ...</span></span>
-<span id="cb6-4"><a href="#cb6-4" aria-hidden="true" tabindex="-1"></a>_ = <span class="kw">try</span> stderr.print(<span class="st">"Result: {d}"</span>, .<span class="op">{</span>result<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb5"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stderr = std.io.getStdErr().writer();</span>
+<span id="cb5-3"><a href="#cb5-3" aria-hidden="true" tabindex="-1"></a><span class="co">// some more lines ...</span></span>
+<span id="cb5-4"><a href="#cb5-4" aria-hidden="true" tabindex="-1"></a>_ = <span class="kw">try</span> stderr.print(<span class="st">"Result: {d}"</span>, .<span class="op">{</span>result<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
 <section id="debugging-through-debuggers" class="level2" data-number="5.2">
@@ -382,83 +381,83 @@ <h3 data-number="5.2.1" class="anchored" data-anchor-id="sec-compile-debug-mode"
 <h3 data-number="5.2.2" class="anchored" data-anchor-id="lets-debug-a-program"><span class="header-section-number">5.2.2</span> Let’s debug a program</h3>
 <p>As an example, let’s use LLDB to navigate and investigate the following piece of Zig code:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb7"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb7-2"><a href="#cb7-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
-<span id="cb7-3"><a href="#cb7-3" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb7-4"><a href="#cb7-4" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> add_and_increment(a: <span class="dt">u8</span>, b: <span class="dt">u8</span>) <span class="dt">u8</span> <span class="op">{</span></span>
-<span id="cb7-5"><a href="#cb7-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> sum = a + b;</span>
-<span id="cb7-6"><a href="#cb7-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> incremented = sum + <span class="dv">1</span>;</span>
-<span id="cb7-7"><a href="#cb7-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> incremented;</span>
-<span id="cb7-8"><a href="#cb7-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
-<span id="cb7-9"><a href="#cb7-9" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb7-10"><a href="#cb7-10" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb7-11"><a href="#cb7-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> n = add_and_increment(<span class="dv">2</span>, <span class="dv">3</span>);</span>
-<span id="cb7-12"><a href="#cb7-12" aria-hidden="true" tabindex="-1"></a>    n = add_and_increment(n, n);</span>
-<span id="cb7-13"><a href="#cb7-13" aria-hidden="true" tabindex="-1"></a>    _ = <span class="kw">try</span> stdout.print(<span class="st">"Result: {d}!</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>n<span class="op">}</span>);</span>
-<span id="cb7-14"><a href="#cb7-14" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb6"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb6-2"><a href="#cb6-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
+<span id="cb6-3"><a href="#cb6-3" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb6-4"><a href="#cb6-4" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> add_and_increment(a: <span class="dt">u8</span>, b: <span class="dt">u8</span>) <span class="dt">u8</span> <span class="op">{</span></span>
+<span id="cb6-5"><a href="#cb6-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> sum = a + b;</span>
+<span id="cb6-6"><a href="#cb6-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> incremented = sum + <span class="dv">1</span>;</span>
+<span id="cb6-7"><a href="#cb6-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> incremented;</span>
+<span id="cb6-8"><a href="#cb6-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
+<span id="cb6-9"><a href="#cb6-9" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb6-10"><a href="#cb6-10" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb6-11"><a href="#cb6-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> n = add_and_increment(<span class="dv">2</span>, <span class="dv">3</span>);</span>
+<span id="cb6-12"><a href="#cb6-12" aria-hidden="true" tabindex="-1"></a>    n = add_and_increment(n, n);</span>
+<span id="cb6-13"><a href="#cb6-13" aria-hidden="true" tabindex="-1"></a>    _ = <span class="kw">try</span> stdout.print(<span class="st">"Result: {d}!</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>n<span class="op">}</span>);</span>
+<span id="cb6-14"><a href="#cb6-14" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>Result: 13!</code></pre>
 </div>
 </div>
 <p>There is nothing wrong with this program. But it is a good start for us. First, we need to compile this program with the <code>zig build-exe</code> command. For this example, suppose that I have compiled the above Zig code into a binary executable called <code>add_program</code>.</p>
-<div class="sourceCode" id="cb9"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb9-1"><a href="#cb9-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zig</span> build-exe add_program.zig</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode" id="cb8"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zig</span> build-exe add_program.zig</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <p>Now, we can start LLDB with <code>add_program</code>, like this:</p>
-<div class="sourceCode" id="cb10"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="ex">lldb</span> add_program</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode" id="cb9"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb9-1"><a href="#cb9-1" aria-hidden="true" tabindex="-1"></a><span class="ex">lldb</span> add_program</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <p>From now on, LLDB is started, and you can know that I’m executing LLDB commands by looking at the prefix <code>(lldb)</code>. If something is prefixed with <code>(lldb)</code>, then you know that it is a LLDB command.</p>
 <p>The first thing I will do, is to set a breakpoint at the <code>main()</code> function, by executing <code>b main</code>. After that, I just start the execution of the program with <code>run</code>. You can see in the output below, that the execution stopped at the first line in the function <code>main()</code>, as we expected.</p>
-<div class="sourceCode" id="cb11"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">b</span> main</span>
-<span id="cb11-2"><a href="#cb11-2" aria-hidden="true" tabindex="-1"></a><span class="ex">Breakpoint</span> 1: where = debugging<span class="kw">`</span><span class="ex">debug1.main</span> + 22</span>
-<span id="cb11-3"><a href="#cb11-3" aria-hidden="true" tabindex="-1"></a>    <span class="ex">at</span> debug1.zig:11:30, address = 0x00000000010341a6</span>
-<span id="cb11-4"><a href="#cb11-4" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">run</span></span>
-<span id="cb11-5"><a href="#cb11-5" aria-hidden="true" tabindex="-1"></a><span class="ex">Process</span> 8654 launched: <span class="st">'add_program'</span> <span class="er">(</span><span class="ex">x86_64</span><span class="kw">)</span></span>
-<span id="cb11-6"><a href="#cb11-6" aria-hidden="true" tabindex="-1"></a><span class="ex">Process</span> 8654 stopped</span>
-<span id="cb11-7"><a href="#cb11-7" aria-hidden="true" tabindex="-1"></a><span class="ex">*</span> thread <span class="co">#1, name = 'add_program',</span></span>
-<span id="cb11-8"><a href="#cb11-8" aria-hidden="true" tabindex="-1"></a>    <span class="ex">stop</span> reason = breakpoint 1.1 frame <span class="co">#0: 0x10341a6</span></span>
-<span id="cb11-9"><a href="#cb11-9" aria-hidden="true" tabindex="-1"></a>    <span class="ex">add_program</span><span class="kw">`</span>debug1.main at add_program.zig:11:30</span>
-<span id="cb11-10"><a href="#cb11-10" aria-hidden="true" tabindex="-1"></a>   <span class="ex">8</span>    }</span>
-<span id="cb11-11"><a href="#cb11-11" aria-hidden="true" tabindex="-1"></a>   <span class="ex">9</span>    </span>
-<span id="cb11-12"><a href="#cb11-12" aria-hidden="true" tabindex="-1"></a>   <span class="ex">10</span>   pub fn main<span class="er">(</span><span class="kw">)</span> <span class="ex">!void</span> {</span>
-<span id="cb11-13"><a href="#cb11-13" aria-hidden="true" tabindex="-1"></a><span class="ex">-</span><span class="op">&gt;</span> 11       var n = add_and_increment<span class="er">(</span><span class="ex">2,</span> 3<span class="kw">);</span></span>
-<span id="cb11-14"><a href="#cb11-14" aria-hidden="true" tabindex="-1"></a>   <span class="ex">12</span>       n = add_and_increment<span class="er">(</span><span class="ex">n,</span> n<span class="kw">);</span></span>
-<span id="cb11-15"><a href="#cb11-15" aria-hidden="true" tabindex="-1"></a>   <span class="ex">13</span>       try stdout.print<span class="er">(</span><span class="st">"Result: {d}!\n"</span><span class="ex">,</span> .{n}<span class="kw">);</span></span>
-<span id="cb11-16"><a href="#cb11-16" aria-hidden="true" tabindex="-1"></a>   <span class="ex">14</span>   }</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode" id="cb10"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">b</span> main</span>
+<span id="cb10-2"><a href="#cb10-2" aria-hidden="true" tabindex="-1"></a><span class="ex">Breakpoint</span> 1: where = debugging<span class="kw">`</span><span class="ex">debug1.main</span> + 22</span>
+<span id="cb10-3"><a href="#cb10-3" aria-hidden="true" tabindex="-1"></a>    <span class="ex">at</span> debug1.zig:11:30, address = 0x00000000010341a6</span>
+<span id="cb10-4"><a href="#cb10-4" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">run</span></span>
+<span id="cb10-5"><a href="#cb10-5" aria-hidden="true" tabindex="-1"></a><span class="ex">Process</span> 8654 launched: <span class="st">'add_program'</span> <span class="er">(</span><span class="ex">x86_64</span><span class="kw">)</span></span>
+<span id="cb10-6"><a href="#cb10-6" aria-hidden="true" tabindex="-1"></a><span class="ex">Process</span> 8654 stopped</span>
+<span id="cb10-7"><a href="#cb10-7" aria-hidden="true" tabindex="-1"></a><span class="ex">*</span> thread <span class="co">#1, name = 'add_program',</span></span>
+<span id="cb10-8"><a href="#cb10-8" aria-hidden="true" tabindex="-1"></a>    <span class="ex">stop</span> reason = breakpoint 1.1 frame <span class="co">#0: 0x10341a6</span></span>
+<span id="cb10-9"><a href="#cb10-9" aria-hidden="true" tabindex="-1"></a>    <span class="ex">add_program</span><span class="kw">`</span>debug1.main at add_program.zig:11:30</span>
+<span id="cb10-10"><a href="#cb10-10" aria-hidden="true" tabindex="-1"></a>   <span class="ex">8</span>    }</span>
+<span id="cb10-11"><a href="#cb10-11" aria-hidden="true" tabindex="-1"></a>   <span class="ex">9</span>    </span>
+<span id="cb10-12"><a href="#cb10-12" aria-hidden="true" tabindex="-1"></a>   <span class="ex">10</span>   pub fn main<span class="er">(</span><span class="kw">)</span> <span class="ex">!void</span> {</span>
+<span id="cb10-13"><a href="#cb10-13" aria-hidden="true" tabindex="-1"></a><span class="ex">-</span><span class="op">&gt;</span> 11       var n = add_and_increment<span class="er">(</span><span class="ex">2,</span> 3<span class="kw">);</span></span>
+<span id="cb10-14"><a href="#cb10-14" aria-hidden="true" tabindex="-1"></a>   <span class="ex">12</span>       n = add_and_increment<span class="er">(</span><span class="ex">n,</span> n<span class="kw">);</span></span>
+<span id="cb10-15"><a href="#cb10-15" aria-hidden="true" tabindex="-1"></a>   <span class="ex">13</span>       try stdout.print<span class="er">(</span><span class="st">"Result: {d}!\n"</span><span class="ex">,</span> .{n}<span class="kw">);</span></span>
+<span id="cb10-16"><a href="#cb10-16" aria-hidden="true" tabindex="-1"></a>   <span class="ex">14</span>   }</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <p>I can start navigating through the code, and checking the objects that are being generated. If you are not familiar with the commands available in LLDB, I recommend you to read the official documentation of the project<a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a>. You can also look for cheat sheets, which quickly describes all commands available for you<a href="#fn4" class="footnote-ref" id="fnref4" role="doc-noteref"><sup>4</sup></a>.</p>
 <p>Currently, we are in the first line at the <code>main()</code> function. In this line, we create the <code>n</code> object, by executing the <code>add_and_increment()</code> function. To execute the current line of code, and go to the next line, we can run the <code>n</code> LLDB command. Let’s execute this command.</p>
 <p>After we executed this line, we can also look at the value stored inside this <code>n</code> object by using the <code>p</code> LLDB command. The syntax for this command is <code>p &lt;name-of-object&gt;</code>.</p>
 <p>If we take a look at the value stored in the <code>n</code> object (<code>p n</code>), notice that it stores the hexadecimal value <code>0x06</code>, which is the number 6 in decimal. We can also see that, this value have a type <code>unsigned char</code>, which is an unsigned 8-bit integer. We have talked already about this at <a href="01-zig-weird.html#sec-zig-strings" class="quarto-xref"><span>Section 1.8</span></a>, that <code>u8</code> integers in Zig are equivalent to the C data type <code>unsigned char</code>.</p>
-<div class="sourceCode" id="cb12"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">n</span></span>
-<span id="cb12-2"><a href="#cb12-2" aria-hidden="true" tabindex="-1"></a><span class="ex">Process</span> 4798 stopped</span>
-<span id="cb12-3"><a href="#cb12-3" aria-hidden="true" tabindex="-1"></a><span class="ex">*</span> thread <span class="co">#1, name = 'debugging',</span></span>
-<span id="cb12-4"><a href="#cb12-4" aria-hidden="true" tabindex="-1"></a>    <span class="ex">stop</span> reason = step over frame <span class="co">#0: 0x10341ae</span></span>
-<span id="cb12-5"><a href="#cb12-5" aria-hidden="true" tabindex="-1"></a>    <span class="ex">debugging</span><span class="kw">`</span><span class="ex">debug1.main</span> at debug1.zig:12:26</span>
-<span id="cb12-6"><a href="#cb12-6" aria-hidden="true" tabindex="-1"></a>   <span class="ex">9</span>    </span>
-<span id="cb12-7"><a href="#cb12-7" aria-hidden="true" tabindex="-1"></a>   <span class="ex">10</span>   pub fn main<span class="er">(</span><span class="kw">)</span> <span class="ex">!void</span> {</span>
-<span id="cb12-8"><a href="#cb12-8" aria-hidden="true" tabindex="-1"></a>   <span class="ex">11</span>       var n = add_and_increment<span class="er">(</span><span class="ex">2,</span> 3<span class="kw">);</span></span>
-<span id="cb12-9"><a href="#cb12-9" aria-hidden="true" tabindex="-1"></a><span class="ex">-</span><span class="op">&gt;</span> 12       n = add_and_increment<span class="er">(</span><span class="ex">n,</span> n<span class="kw">);</span></span>
-<span id="cb12-10"><a href="#cb12-10" aria-hidden="true" tabindex="-1"></a>   <span class="ex">13</span>       try stdout.print<span class="er">(</span><span class="st">"Result: {d}!\n"</span><span class="ex">,</span> .{n}<span class="kw">);</span></span>
-<span id="cb12-11"><a href="#cb12-11" aria-hidden="true" tabindex="-1"></a>   <span class="ex">14</span>   }</span>
-<span id="cb12-12"><a href="#cb12-12" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">p</span> n</span>
-<span id="cb12-13"><a href="#cb12-13" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">unsigned</span> char<span class="kw">)</span> <span class="va">$1</span> = <span class="st">'\x06'</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode" id="cb11"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">n</span></span>
+<span id="cb11-2"><a href="#cb11-2" aria-hidden="true" tabindex="-1"></a><span class="ex">Process</span> 4798 stopped</span>
+<span id="cb11-3"><a href="#cb11-3" aria-hidden="true" tabindex="-1"></a><span class="ex">*</span> thread <span class="co">#1, name = 'debugging',</span></span>
+<span id="cb11-4"><a href="#cb11-4" aria-hidden="true" tabindex="-1"></a>    <span class="ex">stop</span> reason = step over frame <span class="co">#0: 0x10341ae</span></span>
+<span id="cb11-5"><a href="#cb11-5" aria-hidden="true" tabindex="-1"></a>    <span class="ex">debugging</span><span class="kw">`</span><span class="ex">debug1.main</span> at debug1.zig:12:26</span>
+<span id="cb11-6"><a href="#cb11-6" aria-hidden="true" tabindex="-1"></a>   <span class="ex">9</span>    </span>
+<span id="cb11-7"><a href="#cb11-7" aria-hidden="true" tabindex="-1"></a>   <span class="ex">10</span>   pub fn main<span class="er">(</span><span class="kw">)</span> <span class="ex">!void</span> {</span>
+<span id="cb11-8"><a href="#cb11-8" aria-hidden="true" tabindex="-1"></a>   <span class="ex">11</span>       var n = add_and_increment<span class="er">(</span><span class="ex">2,</span> 3<span class="kw">);</span></span>
+<span id="cb11-9"><a href="#cb11-9" aria-hidden="true" tabindex="-1"></a><span class="ex">-</span><span class="op">&gt;</span> 12       n = add_and_increment<span class="er">(</span><span class="ex">n,</span> n<span class="kw">);</span></span>
+<span id="cb11-10"><a href="#cb11-10" aria-hidden="true" tabindex="-1"></a>   <span class="ex">13</span>       try stdout.print<span class="er">(</span><span class="st">"Result: {d}!\n"</span><span class="ex">,</span> .{n}<span class="kw">);</span></span>
+<span id="cb11-11"><a href="#cb11-11" aria-hidden="true" tabindex="-1"></a>   <span class="ex">14</span>   }</span>
+<span id="cb11-12"><a href="#cb11-12" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">p</span> n</span>
+<span id="cb11-13"><a href="#cb11-13" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">unsigned</span> char<span class="kw">)</span> <span class="va">$1</span> = <span class="st">'\x06'</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <p>Now, on the next line of code, we are executing the <code>add_and_increment()</code> function once again. Why not step inside this function? Shall we? We can do that, by executing the <code>s</code> LLDB command. Notice in the example below that, after executing this command, we have entered into the context of the <code>add_and_increment()</code> function.</p>
 <p>Also notice in the example below that, I have walked two more lines in the function’s body, then, I execute the <code>frame variable</code> LLDB command, to see at once, the value stored in each of the variables that were created inside the current scope.</p>
 <p>You can see in the output below that, the object <code>sum</code> stores the value <code>\f</code>, which represents the <em>form feed</em> character. This character in the ASCII table, corresponds to the hexadecimal value <code>0x0C</code>, or, in decimal, the number 12. So, this means that the result of the expression <code>a + b</code> executed at line 5, resulted in the number 12.</p>
-<div class="sourceCode" id="cb13"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">s</span></span>
-<span id="cb13-2"><a href="#cb13-2" aria-hidden="true" tabindex="-1"></a><span class="ex">Process</span> 4798 stopped</span>
-<span id="cb13-3"><a href="#cb13-3" aria-hidden="true" tabindex="-1"></a><span class="ex">*</span> thread <span class="co">#1, name = 'debugging',</span></span>
-<span id="cb13-4"><a href="#cb13-4" aria-hidden="true" tabindex="-1"></a>    <span class="ex">stop</span> reason = step in frame <span class="co">#0: 0x10342de</span></span>
-<span id="cb13-5"><a href="#cb13-5" aria-hidden="true" tabindex="-1"></a>    <span class="ex">debugging</span><span class="kw">`</span><span class="ex">debug1.add_and_increment</span><span class="er">(</span><span class="va">a</span><span class="op">=</span><span class="st">'\x02'</span>, <span class="va">b</span><span class="op">=</span><span class="st">'\x03'</span><span class="kw">)</span></span>
-<span id="cb13-6"><a href="#cb13-6" aria-hidden="true" tabindex="-1"></a>    <span class="ex">at</span> debug1.zig:4:39</span>
-<span id="cb13-7"><a href="#cb13-7" aria-hidden="true" tabindex="-1"></a><span class="ex">-</span><span class="op">&gt;</span> 4    fn add_and_increment<span class="er">(</span><span class="ex">a:</span> u8, b: u8<span class="kw">)</span> <span class="ex">u8</span> {</span>
-<span id="cb13-8"><a href="#cb13-8" aria-hidden="true" tabindex="-1"></a>   <span class="ex">5</span>        const sum = a + b<span class="kw">;</span></span>
-<span id="cb13-9"><a href="#cb13-9" aria-hidden="true" tabindex="-1"></a>   <span class="ex">6</span>        const incremented = sum + 1<span class="kw">;</span></span>
-<span id="cb13-10"><a href="#cb13-10" aria-hidden="true" tabindex="-1"></a>   <span class="ex">7</span>        return incremented<span class="kw">;</span></span>
-<span id="cb13-11"><a href="#cb13-11" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">n</span></span>
-<span id="cb13-12"><a href="#cb13-12" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">n</span></span>
-<span id="cb13-13"><a href="#cb13-13" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">frame</span> variable</span>
-<span id="cb13-14"><a href="#cb13-14" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">unsigned</span> char<span class="kw">)</span> <span class="ex">a</span> = <span class="st">'\x06'</span></span>
-<span id="cb13-15"><a href="#cb13-15" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">unsigned</span> char<span class="kw">)</span> <span class="ex">b</span> = <span class="st">'\x06'</span></span>
-<span id="cb13-16"><a href="#cb13-16" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">unsigned</span> char<span class="kw">)</span> <span class="fu">sum</span> = <span class="st">'\f'</span></span>
-<span id="cb13-17"><a href="#cb13-17" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">unsigned</span> char<span class="kw">)</span> <span class="ex">incremented</span> = <span class="st">'\x06'</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode" id="cb12"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">s</span></span>
+<span id="cb12-2"><a href="#cb12-2" aria-hidden="true" tabindex="-1"></a><span class="ex">Process</span> 4798 stopped</span>
+<span id="cb12-3"><a href="#cb12-3" aria-hidden="true" tabindex="-1"></a><span class="ex">*</span> thread <span class="co">#1, name = 'debugging',</span></span>
+<span id="cb12-4"><a href="#cb12-4" aria-hidden="true" tabindex="-1"></a>    <span class="ex">stop</span> reason = step in frame <span class="co">#0: 0x10342de</span></span>
+<span id="cb12-5"><a href="#cb12-5" aria-hidden="true" tabindex="-1"></a>    <span class="ex">debugging</span><span class="kw">`</span><span class="ex">debug1.add_and_increment</span><span class="er">(</span><span class="va">a</span><span class="op">=</span><span class="st">'\x02'</span>, <span class="va">b</span><span class="op">=</span><span class="st">'\x03'</span><span class="kw">)</span></span>
+<span id="cb12-6"><a href="#cb12-6" aria-hidden="true" tabindex="-1"></a>    <span class="ex">at</span> debug1.zig:4:39</span>
+<span id="cb12-7"><a href="#cb12-7" aria-hidden="true" tabindex="-1"></a><span class="ex">-</span><span class="op">&gt;</span> 4    fn add_and_increment<span class="er">(</span><span class="ex">a:</span> u8, b: u8<span class="kw">)</span> <span class="ex">u8</span> {</span>
+<span id="cb12-8"><a href="#cb12-8" aria-hidden="true" tabindex="-1"></a>   <span class="ex">5</span>        const sum = a + b<span class="kw">;</span></span>
+<span id="cb12-9"><a href="#cb12-9" aria-hidden="true" tabindex="-1"></a>   <span class="ex">6</span>        const incremented = sum + 1<span class="kw">;</span></span>
+<span id="cb12-10"><a href="#cb12-10" aria-hidden="true" tabindex="-1"></a>   <span class="ex">7</span>        return incremented<span class="kw">;</span></span>
+<span id="cb12-11"><a href="#cb12-11" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">n</span></span>
+<span id="cb12-12"><a href="#cb12-12" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">n</span></span>
+<span id="cb12-13"><a href="#cb12-13" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">frame</span> variable</span>
+<span id="cb12-14"><a href="#cb12-14" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">unsigned</span> char<span class="kw">)</span> <span class="ex">a</span> = <span class="st">'\x06'</span></span>
+<span id="cb12-15"><a href="#cb12-15" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">unsigned</span> char<span class="kw">)</span> <span class="ex">b</span> = <span class="st">'\x06'</span></span>
+<span id="cb12-16"><a href="#cb12-16" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">unsigned</span> char<span class="kw">)</span> <span class="fu">sum</span> = <span class="st">'\f'</span></span>
+<span id="cb12-17"><a href="#cb12-17" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">unsigned</span> char<span class="kw">)</span> <span class="ex">incremented</span> = <span class="st">'\x06'</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </section>
 </section>
 <section id="how-to-investigate-the-data-type-of-your-objects" class="level2" data-number="5.3">
@@ -467,15 +466,15 @@ <h2 data-number="5.3" class="anchored" data-anchor-id="how-to-investigate-the-da
 <p>When you walk through your program with a debugger, you can inspect the types of your objects by simply printing them to the console, with the LLDB <code>p</code> command. But you also have alternatives embedded in the language itself to access the data types of your objects.</p>
 <p>In Zig, you can retrieve the data type of an object, by using the built-in function <code>@TypeOf()</code>. Just apply this function over the object, and you get access to the data type of the object.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb14"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb14-2"><a href="#cb14-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
-<span id="cb14-3"><a href="#cb14-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = std.testing.expect;</span>
-<span id="cb14-4"><a href="#cb14-4" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb14-5"><a href="#cb14-5" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb14-6"><a href="#cb14-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> number: <span class="dt">i32</span> = <span class="dv">5</span>;</span>
-<span id="cb14-7"><a href="#cb14-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(number) == <span class="dt">i32</span>);</span>
-<span id="cb14-8"><a href="#cb14-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"{any}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="bu">@TypeOf</span>(number)<span class="op">}</span>);</span>
-<span id="cb14-9"><a href="#cb14-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb13"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb13-2"><a href="#cb13-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
+<span id="cb13-3"><a href="#cb13-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = std.testing.expect;</span>
+<span id="cb13-4"><a href="#cb13-4" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb13-5"><a href="#cb13-5" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb13-6"><a href="#cb13-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> number: <span class="dt">i32</span> = <span class="dv">5</span>;</span>
+<span id="cb13-7"><a href="#cb13-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(number) == <span class="dt">i32</span>);</span>
+<span id="cb13-8"><a href="#cb13-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"{any}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="bu">@TypeOf</span>(number)<span class="op">}</span>);</span>
+<span id="cb13-9"><a href="#cb13-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>i32</code></pre>
 </div>
diff --git a/docs/Chapters/03-structs.html b/docs/Chapters/03-structs.html
index a469e292..19bc03c5 100644
--- a/docs/Chapters/03-structs.html
+++ b/docs/Chapters/03-structs.html
@@ -680,9 +680,6 @@ <h3 data-number="2.2.2" class="anchored" data-anchor-id="how-to-overcome-this-ba
 <span id="cb32-9"><a href="#cb32-9" aria-hidden="true" tabindex="-1"></a>    add2(&amp;x);</span>
 <span id="cb32-10"><a href="#cb32-10" aria-hidden="true" tabindex="-1"></a>    std.debug.print(<span class="st">"Result: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>x<span class="op">}</span>);</span>
 <span id="cb32-11"><a href="#cb32-11" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
-<div class="cell-output cell-output-stdout">
-<pre><code>Result: 6</code></pre>
-</div>
 </div>
 <pre><code>Result: 6</code></pre>
 <p>Even in this code example above, the <code>x</code> argument is still immutable. Which means that the pointer itself is immutable. Therefore, you cannot change the memory address that it points to. However, you can dereference the pointer to access the value that it points to, and also, to change this value, if you need to.</p>
@@ -698,33 +695,33 @@ <h2 data-number="2.3" class="anchored" data-anchor-id="sec-structs-and-oop"><spa
 <p>If you look at the <code>User</code> struct below, you can see the <code>struct</code> keyword. Notice the data members of this struct: <code>id</code>, <code>name</code> and <code>email</code>. Every data member has its type explicitly annotated, with the colon character (<code>:</code>) syntax that we described earlier in <a href="01-zig-weird.html#sec-root-file" class="quarto-xref"><span>Section 1.2.2</span></a>. But also notice that every line in the struct body that describes a data member, ends with a comma character (<code>,</code>). So every time you declare a data member in your Zig code, always end the line with a comma character, instead of ending it with the traditional semicolon character (<code>;</code>).</p>
 <p>Next, we have registered an <code>init()</code> function as a method of this <code>User</code> struct. This <code>init()</code> method is the constructor method that we will use to instantiate every new <code>User</code> object. That is why this <code>init()</code> function returns a new <code>User</code> object as result.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb35"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb35-1"><a href="#cb35-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb35-2"><a href="#cb35-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
-<span id="cb35-3"><a href="#cb35-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> User = <span class="kw">struct</span> <span class="op">{</span></span>
-<span id="cb35-4"><a href="#cb35-4" aria-hidden="true" tabindex="-1"></a>    id: <span class="dt">u64</span>,</span>
-<span id="cb35-5"><a href="#cb35-5" aria-hidden="true" tabindex="-1"></a>    name: []<span class="kw">const</span> <span class="dt">u8</span>,</span>
-<span id="cb35-6"><a href="#cb35-6" aria-hidden="true" tabindex="-1"></a>    email: []<span class="kw">const</span> <span class="dt">u8</span>,</span>
-<span id="cb35-7"><a href="#cb35-7" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb35-8"><a href="#cb35-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> init(id: <span class="dt">u64</span>,</span>
-<span id="cb35-9"><a href="#cb35-9" aria-hidden="true" tabindex="-1"></a>                name: []<span class="kw">const</span> <span class="dt">u8</span>,</span>
-<span id="cb35-10"><a href="#cb35-10" aria-hidden="true" tabindex="-1"></a>                email: []<span class="kw">const</span> <span class="dt">u8</span>) User <span class="op">{</span></span>
-<span id="cb35-11"><a href="#cb35-11" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb35-12"><a href="#cb35-12" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> User <span class="op">{</span></span>
-<span id="cb35-13"><a href="#cb35-13" aria-hidden="true" tabindex="-1"></a>            .id = id,</span>
-<span id="cb35-14"><a href="#cb35-14" aria-hidden="true" tabindex="-1"></a>            .name = name,</span>
-<span id="cb35-15"><a href="#cb35-15" aria-hidden="true" tabindex="-1"></a>            .email = email</span>
-<span id="cb35-16"><a href="#cb35-16" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span>;</span>
-<span id="cb35-17"><a href="#cb35-17" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb35-18"><a href="#cb35-18" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb35-19"><a href="#cb35-19" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> print_name(self: User) !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb35-20"><a href="#cb35-20" aria-hidden="true" tabindex="-1"></a>        <span class="kw">try</span> stdout.print(<span class="st">"{s}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>self.name<span class="op">}</span>);</span>
-<span id="cb35-21"><a href="#cb35-21" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb35-22"><a href="#cb35-22" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
-<span id="cb35-23"><a href="#cb35-23" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb35-24"><a href="#cb35-24" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb35-25"><a href="#cb35-25" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> u = User.init(<span class="dv">1</span>, <span class="st">"pedro"</span>, <span class="st">"email@gmail.com"</span>);</span>
-<span id="cb35-26"><a href="#cb35-26" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> u.print_name();</span>
-<span id="cb35-27"><a href="#cb35-27" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb34"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb34-1"><a href="#cb34-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb34-2"><a href="#cb34-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
+<span id="cb34-3"><a href="#cb34-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> User = <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb34-4"><a href="#cb34-4" aria-hidden="true" tabindex="-1"></a>    id: <span class="dt">u64</span>,</span>
+<span id="cb34-5"><a href="#cb34-5" aria-hidden="true" tabindex="-1"></a>    name: []<span class="kw">const</span> <span class="dt">u8</span>,</span>
+<span id="cb34-6"><a href="#cb34-6" aria-hidden="true" tabindex="-1"></a>    email: []<span class="kw">const</span> <span class="dt">u8</span>,</span>
+<span id="cb34-7"><a href="#cb34-7" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb34-8"><a href="#cb34-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> init(id: <span class="dt">u64</span>,</span>
+<span id="cb34-9"><a href="#cb34-9" aria-hidden="true" tabindex="-1"></a>                name: []<span class="kw">const</span> <span class="dt">u8</span>,</span>
+<span id="cb34-10"><a href="#cb34-10" aria-hidden="true" tabindex="-1"></a>                email: []<span class="kw">const</span> <span class="dt">u8</span>) User <span class="op">{</span></span>
+<span id="cb34-11"><a href="#cb34-11" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb34-12"><a href="#cb34-12" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> User <span class="op">{</span></span>
+<span id="cb34-13"><a href="#cb34-13" aria-hidden="true" tabindex="-1"></a>            .id = id,</span>
+<span id="cb34-14"><a href="#cb34-14" aria-hidden="true" tabindex="-1"></a>            .name = name,</span>
+<span id="cb34-15"><a href="#cb34-15" aria-hidden="true" tabindex="-1"></a>            .email = email</span>
+<span id="cb34-16"><a href="#cb34-16" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span>;</span>
+<span id="cb34-17"><a href="#cb34-17" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb34-18"><a href="#cb34-18" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb34-19"><a href="#cb34-19" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> print_name(self: User) !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb34-20"><a href="#cb34-20" aria-hidden="true" tabindex="-1"></a>        <span class="kw">try</span> stdout.print(<span class="st">"{s}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>self.name<span class="op">}</span>);</span>
+<span id="cb34-21"><a href="#cb34-21" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb34-22"><a href="#cb34-22" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
+<span id="cb34-23"><a href="#cb34-23" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb34-24"><a href="#cb34-24" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb34-25"><a href="#cb34-25" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> u = User.init(<span class="dv">1</span>, <span class="st">"pedro"</span>, <span class="st">"email@gmail.com"</span>);</span>
+<span id="cb34-26"><a href="#cb34-26" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> u.print_name();</span>
+<span id="cb34-27"><a href="#cb34-27" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>pedro</code></pre>
 </div>
@@ -736,23 +733,23 @@ <h2 data-number="2.3" class="anchored" data-anchor-id="sec-structs-and-oop"><spa
 <h3 data-number="2.3.1" class="anchored" data-anchor-id="sec-anonymous-struct-literals"><span class="header-section-number">2.3.1</span> Anonymous struct literals</h3>
 <p>You can declare a struct object as a literal value. When we do that, we normally specify the data type of this struct literal by writing its data type just before the opening curly brace. For example, I could write a struct literal value of the type <code>User</code> that we have defined in the previous section like this:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb37"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb37-1"><a href="#cb37-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> eu = User <span class="op">{</span></span>
-<span id="cb37-2"><a href="#cb37-2" aria-hidden="true" tabindex="-1"></a>    .id = <span class="dv">1</span>,</span>
-<span id="cb37-3"><a href="#cb37-3" aria-hidden="true" tabindex="-1"></a>    .name = <span class="st">"Pedro"</span>,</span>
-<span id="cb37-4"><a href="#cb37-4" aria-hidden="true" tabindex="-1"></a>    .email = <span class="st">"someemail@gmail.com"</span></span>
-<span id="cb37-5"><a href="#cb37-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
-<span id="cb37-6"><a href="#cb37-6" aria-hidden="true" tabindex="-1"></a>_ = eu;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb36"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb36-1"><a href="#cb36-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> eu = User <span class="op">{</span></span>
+<span id="cb36-2"><a href="#cb36-2" aria-hidden="true" tabindex="-1"></a>    .id = <span class="dv">1</span>,</span>
+<span id="cb36-3"><a href="#cb36-3" aria-hidden="true" tabindex="-1"></a>    .name = <span class="st">"Pedro"</span>,</span>
+<span id="cb36-4"><a href="#cb36-4" aria-hidden="true" tabindex="-1"></a>    .email = <span class="st">"someemail@gmail.com"</span></span>
+<span id="cb36-5"><a href="#cb36-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
+<span id="cb36-6"><a href="#cb36-6" aria-hidden="true" tabindex="-1"></a>_ = eu;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>However, in Zig, we can also write an anonymous struct literal. That is, you can write a struct literal, but not specify explicitly the type of this particular struct. An anonymous struct is written by using the syntax <code>.{}</code>. So, we essentially replaced the explicit type of the struct literal with a dot character (<code>.</code>).</p>
 <p>As we described in <a href="#sec-type-inference" class="quarto-xref"><span>Section 2.4</span></a>, when you put a dot before a struct literal, the type of this struct literal is automatically inferred by the <code>zig</code> compiler. In essence, the <code>zig</code> compiler will look for some hint of what is the type of that struct. This hint can be the type annotation of a function argument, or the return type annotation of the function that you are using, or the type annotation of an existing object. If the compiler does find such type annotation, it will use this type in your literal struct.</p>
 <p>Anonymous structs are very commonly used as inputs to function arguments in Zig. One example that you have seen already constantly, is the <code>print()</code> function from the <code>stdout</code> object. This function takes two arguments. The first argument, is a template string, which should contain string format specifiers in it, which tells how the values provided in the second argument should be printed into the message.</p>
 <p>While the second argument is a struct literal that lists the values to be printed into the template message specified in the first argument. You normally want to use an anonymous struct literal here, so that the <code>zig</code> compiler do the job of specifying the type of this particular anonymous struct for you.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb38"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb38-1"><a href="#cb38-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb38-2"><a href="#cb38-2" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb38-3"><a href="#cb38-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
-<span id="cb38-4"><a href="#cb38-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"Hello, {s}!</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="st">"world"</span><span class="op">}</span>);</span>
-<span id="cb38-5"><a href="#cb38-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb37"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb37-1"><a href="#cb37-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb37-2"><a href="#cb37-2" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb37-3"><a href="#cb37-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
+<span id="cb37-4"><a href="#cb37-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"Hello, {s}!</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="st">"world"</span><span class="op">}</span>);</span>
+<span id="cb37-5"><a href="#cb37-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>Hello, world!</code></pre>
 </div>
@@ -763,11 +760,11 @@ <h3 data-number="2.3.2" class="anchored" data-anchor-id="struct-declarations-mus
 <p>Types in Zig must be <code>const</code> or <code>comptime</code> (we are going to talk more about comptime in <a href="10-stack-project.html#sec-comptime" class="quarto-xref"><span>Section 12.1</span></a>). What this means is that you cannot create a new data type, and mark it as variable with the <code>var</code> keyword. So struct declarations are always constant. You cannot declare a new struct type using the <code>var</code> keyword. It must be <code>const</code>.</p>
 <p>In the <code>Vec3</code> example below, this declaration is allowed because I’m using the <code>const</code> keyword to declare this new data type.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb40"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb40-1"><a href="#cb40-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Vec3 = <span class="kw">struct</span> <span class="op">{</span></span>
-<span id="cb40-2"><a href="#cb40-2" aria-hidden="true" tabindex="-1"></a>    x: <span class="dt">f64</span>,</span>
-<span id="cb40-3"><a href="#cb40-3" aria-hidden="true" tabindex="-1"></a>    y: <span class="dt">f64</span>,</span>
-<span id="cb40-4"><a href="#cb40-4" aria-hidden="true" tabindex="-1"></a>    z: <span class="dt">f64</span>,</span>
-<span id="cb40-5"><a href="#cb40-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb39"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb39-1"><a href="#cb39-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Vec3 = <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb39-2"><a href="#cb39-2" aria-hidden="true" tabindex="-1"></a>    x: <span class="dt">f64</span>,</span>
+<span id="cb39-3"><a href="#cb39-3" aria-hidden="true" tabindex="-1"></a>    y: <span class="dt">f64</span>,</span>
+<span id="cb39-4"><a href="#cb39-4" aria-hidden="true" tabindex="-1"></a>    z: <span class="dt">f64</span>,</span>
+<span id="cb39-5"><a href="#cb39-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
 <section id="sec-self-arg" class="level3" data-number="2.3.3">
@@ -776,34 +773,34 @@ <h3 data-number="2.3.3" class="anchored" data-anchor-id="sec-self-arg"><span cla
 <p>It is not mandatory to use this <code>self</code> argument. But why would you not use this <code>self</code> argument? There is no reason to not use it. Because the only way to get access to the data stored in the data members of your struct is to access them through this <code>self</code> argument. If you don’t need to use the data in the data members of your struct inside your method, you very likely don’t need a method. You can just declare this logic as a simple function, outside of your struct declaration.</p>
 <p>Take the <code>Vec3</code> struct below. Inside this <code>Vec3</code> struct we declared a method named <code>distance()</code>. This method calculates the distance between two <code>Vec3</code> objects, by following the distance formula in euclidean space. Notice that this <code>distance()</code> method takes two <code>Vec3</code> objects as input, <code>self</code> and <code>other</code>.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb41"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb41-1"><a href="#cb41-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb41-2"><a href="#cb41-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> m = std.math;</span>
-<span id="cb41-3"><a href="#cb41-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Vec3 = <span class="kw">struct</span> <span class="op">{</span></span>
-<span id="cb41-4"><a href="#cb41-4" aria-hidden="true" tabindex="-1"></a>    x: <span class="dt">f64</span>,</span>
-<span id="cb41-5"><a href="#cb41-5" aria-hidden="true" tabindex="-1"></a>    y: <span class="dt">f64</span>,</span>
-<span id="cb41-6"><a href="#cb41-6" aria-hidden="true" tabindex="-1"></a>    z: <span class="dt">f64</span>,</span>
-<span id="cb41-7"><a href="#cb41-7" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb41-8"><a href="#cb41-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> distance(self: Vec3, other: Vec3) <span class="dt">f64</span> <span class="op">{</span></span>
-<span id="cb41-9"><a href="#cb41-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> xd = m.pow(<span class="dt">f64</span>, self.x - other.x, <span class="fl">2.0</span>);</span>
-<span id="cb41-10"><a href="#cb41-10" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> yd = m.pow(<span class="dt">f64</span>, self.y - other.y, <span class="fl">2.0</span>);</span>
-<span id="cb41-11"><a href="#cb41-11" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> zd = m.pow(<span class="dt">f64</span>, self.z - other.z, <span class="fl">2.0</span>);</span>
-<span id="cb41-12"><a href="#cb41-12" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> m.sqrt(xd + yd + zd);</span>
-<span id="cb41-13"><a href="#cb41-13" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb41-14"><a href="#cb41-14" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb40"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb40-1"><a href="#cb40-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb40-2"><a href="#cb40-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> m = std.math;</span>
+<span id="cb40-3"><a href="#cb40-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Vec3 = <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb40-4"><a href="#cb40-4" aria-hidden="true" tabindex="-1"></a>    x: <span class="dt">f64</span>,</span>
+<span id="cb40-5"><a href="#cb40-5" aria-hidden="true" tabindex="-1"></a>    y: <span class="dt">f64</span>,</span>
+<span id="cb40-6"><a href="#cb40-6" aria-hidden="true" tabindex="-1"></a>    z: <span class="dt">f64</span>,</span>
+<span id="cb40-7"><a href="#cb40-7" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb40-8"><a href="#cb40-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> distance(self: Vec3, other: Vec3) <span class="dt">f64</span> <span class="op">{</span></span>
+<span id="cb40-9"><a href="#cb40-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> xd = m.pow(<span class="dt">f64</span>, self.x - other.x, <span class="fl">2.0</span>);</span>
+<span id="cb40-10"><a href="#cb40-10" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> yd = m.pow(<span class="dt">f64</span>, self.y - other.y, <span class="fl">2.0</span>);</span>
+<span id="cb40-11"><a href="#cb40-11" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> zd = m.pow(<span class="dt">f64</span>, self.z - other.z, <span class="fl">2.0</span>);</span>
+<span id="cb40-12"><a href="#cb40-12" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> m.sqrt(xd + yd + zd);</span>
+<span id="cb40-13"><a href="#cb40-13" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb40-14"><a href="#cb40-14" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>The <code>self</code> argument corresponds to the <code>Vec3</code> object from which this <code>distance()</code> method is being called from. While the <code>other</code> is a separate <code>Vec3</code> object that is given as input to this method. In the example below, the <code>self</code> argument corresponds to the object <code>v1</code>, because the <code>distance()</code> method is being called from the <code>v1</code> object, while the <code>other</code> argument corresponds to the object <code>v2</code>.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb42"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb42-1"><a href="#cb42-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> v1 = Vec3 <span class="op">{</span></span>
-<span id="cb42-2"><a href="#cb42-2" aria-hidden="true" tabindex="-1"></a>    .x = <span class="fl">4.2</span>, .y = <span class="fl">2.4</span>, .z = <span class="fl">0.9</span></span>
-<span id="cb42-3"><a href="#cb42-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
-<span id="cb42-4"><a href="#cb42-4" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> v2 = Vec3 <span class="op">{</span></span>
-<span id="cb42-5"><a href="#cb42-5" aria-hidden="true" tabindex="-1"></a>    .x = <span class="fl">5.1</span>, .y = <span class="fl">5.6</span>, .z = <span class="fl">1.6</span></span>
-<span id="cb42-6"><a href="#cb42-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
-<span id="cb42-7"><a href="#cb42-7" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb42-8"><a href="#cb42-8" aria-hidden="true" tabindex="-1"></a>std.debug.print(</span>
-<span id="cb42-9"><a href="#cb42-9" aria-hidden="true" tabindex="-1"></a>    <span class="st">"Distance: {d}</span><span class="sc">\n</span><span class="st">"</span>,</span>
-<span id="cb42-10"><a href="#cb42-10" aria-hidden="true" tabindex="-1"></a>    .<span class="op">{</span>v1.distance(v2)<span class="op">}</span></span>
-<span id="cb42-11"><a href="#cb42-11" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb41"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb41-1"><a href="#cb41-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> v1 = Vec3 <span class="op">{</span></span>
+<span id="cb41-2"><a href="#cb41-2" aria-hidden="true" tabindex="-1"></a>    .x = <span class="fl">4.2</span>, .y = <span class="fl">2.4</span>, .z = <span class="fl">0.9</span></span>
+<span id="cb41-3"><a href="#cb41-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
+<span id="cb41-4"><a href="#cb41-4" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> v2 = Vec3 <span class="op">{</span></span>
+<span id="cb41-5"><a href="#cb41-5" aria-hidden="true" tabindex="-1"></a>    .x = <span class="fl">5.1</span>, .y = <span class="fl">5.6</span>, .z = <span class="fl">1.6</span></span>
+<span id="cb41-6"><a href="#cb41-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
+<span id="cb41-7"><a href="#cb41-7" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb41-8"><a href="#cb41-8" aria-hidden="true" tabindex="-1"></a>std.debug.print(</span>
+<span id="cb41-9"><a href="#cb41-9" aria-hidden="true" tabindex="-1"></a>    <span class="st">"Distance: {d}</span><span class="sc">\n</span><span class="st">"</span>,</span>
+<span id="cb41-10"><a href="#cb41-10" aria-hidden="true" tabindex="-1"></a>    .<span class="op">{</span>v1.distance(v2)<span class="op">}</span></span>
+<span id="cb41-11"><a href="#cb41-11" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Distance: 3.3970575502926055</code></pre>
 </section>
@@ -818,40 +815,40 @@ <h3 data-number="2.3.4" class="anchored" data-anchor-id="about-the-struct-state"
 <p>But what if we do have a method that alters the state of the object, by altering the values of its data members, how should we annotate <code>self</code> in this instance? The answer is: “we should annotate <code>self</code> as a pointer of <code>x</code>, instead of just <code>x</code>”. In other words, you should annotate <code>self</code> as <code>self: *x</code>, instead of annotating it as <code>self: x</code>.</p>
 <p>If we create a new method inside the <code>Vec3</code> object that, for example, expands the vector by multiplying its coordinates by a factor of two, then, we need to follow this rule specified in the previous paragraph. The code example below demonstrates this idea:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb44"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb44-1"><a href="#cb44-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb44-2"><a href="#cb44-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> m = std.math;</span>
-<span id="cb44-3"><a href="#cb44-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Vec3 = <span class="kw">struct</span> <span class="op">{</span></span>
-<span id="cb44-4"><a href="#cb44-4" aria-hidden="true" tabindex="-1"></a>    x: <span class="dt">f64</span>,</span>
-<span id="cb44-5"><a href="#cb44-5" aria-hidden="true" tabindex="-1"></a>    y: <span class="dt">f64</span>,</span>
-<span id="cb44-6"><a href="#cb44-6" aria-hidden="true" tabindex="-1"></a>    z: <span class="dt">f64</span>,</span>
-<span id="cb44-7"><a href="#cb44-7" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb44-8"><a href="#cb44-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> distance(self: Vec3, other: Vec3) <span class="dt">f64</span> <span class="op">{</span></span>
-<span id="cb44-9"><a href="#cb44-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> xd = m.pow(<span class="dt">f64</span>, self.x - other.x, <span class="fl">2.0</span>);</span>
-<span id="cb44-10"><a href="#cb44-10" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> yd = m.pow(<span class="dt">f64</span>, self.y - other.y, <span class="fl">2.0</span>);</span>
-<span id="cb44-11"><a href="#cb44-11" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> zd = m.pow(<span class="dt">f64</span>, self.z - other.z, <span class="fl">2.0</span>);</span>
-<span id="cb44-12"><a href="#cb44-12" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> m.sqrt(xd + yd + zd);</span>
-<span id="cb44-13"><a href="#cb44-13" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb44-14"><a href="#cb44-14" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb44-15"><a href="#cb44-15" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> twice(self: *Vec3) <span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb44-16"><a href="#cb44-16" aria-hidden="true" tabindex="-1"></a>        self.x = self.x * <span class="fl">2.0</span>;</span>
-<span id="cb44-17"><a href="#cb44-17" aria-hidden="true" tabindex="-1"></a>        self.y = self.y * <span class="fl">2.0</span>;</span>
-<span id="cb44-18"><a href="#cb44-18" aria-hidden="true" tabindex="-1"></a>        self.z = self.z * <span class="fl">2.0</span>;</span>
-<span id="cb44-19"><a href="#cb44-19" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb44-20"><a href="#cb44-20" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb43"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb43-1"><a href="#cb43-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb43-2"><a href="#cb43-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> m = std.math;</span>
+<span id="cb43-3"><a href="#cb43-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Vec3 = <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb43-4"><a href="#cb43-4" aria-hidden="true" tabindex="-1"></a>    x: <span class="dt">f64</span>,</span>
+<span id="cb43-5"><a href="#cb43-5" aria-hidden="true" tabindex="-1"></a>    y: <span class="dt">f64</span>,</span>
+<span id="cb43-6"><a href="#cb43-6" aria-hidden="true" tabindex="-1"></a>    z: <span class="dt">f64</span>,</span>
+<span id="cb43-7"><a href="#cb43-7" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb43-8"><a href="#cb43-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> distance(self: Vec3, other: Vec3) <span class="dt">f64</span> <span class="op">{</span></span>
+<span id="cb43-9"><a href="#cb43-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> xd = m.pow(<span class="dt">f64</span>, self.x - other.x, <span class="fl">2.0</span>);</span>
+<span id="cb43-10"><a href="#cb43-10" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> yd = m.pow(<span class="dt">f64</span>, self.y - other.y, <span class="fl">2.0</span>);</span>
+<span id="cb43-11"><a href="#cb43-11" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> zd = m.pow(<span class="dt">f64</span>, self.z - other.z, <span class="fl">2.0</span>);</span>
+<span id="cb43-12"><a href="#cb43-12" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> m.sqrt(xd + yd + zd);</span>
+<span id="cb43-13"><a href="#cb43-13" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb43-14"><a href="#cb43-14" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb43-15"><a href="#cb43-15" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> twice(self: *Vec3) <span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb43-16"><a href="#cb43-16" aria-hidden="true" tabindex="-1"></a>        self.x = self.x * <span class="fl">2.0</span>;</span>
+<span id="cb43-17"><a href="#cb43-17" aria-hidden="true" tabindex="-1"></a>        self.y = self.y * <span class="fl">2.0</span>;</span>
+<span id="cb43-18"><a href="#cb43-18" aria-hidden="true" tabindex="-1"></a>        self.z = self.z * <span class="fl">2.0</span>;</span>
+<span id="cb43-19"><a href="#cb43-19" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb43-20"><a href="#cb43-20" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>Notice in the code example above that we have added a new method to our <code>Vec3</code> struct named <code>twice()</code>. This method doubles the coordinate values of our vector object. In the case of the <code>twice()</code> method, we annotated the <code>self</code> argument as <code>*Vec3</code>, indicating that this argument receives a pointer (or a reference, if you prefer to call it this way) to a <code>Vec3</code> object as input.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb45"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb45-1"><a href="#cb45-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> v3 = Vec3 <span class="op">{</span></span>
-<span id="cb45-2"><a href="#cb45-2" aria-hidden="true" tabindex="-1"></a>    .x = <span class="fl">4.2</span>, .y = <span class="fl">2.4</span>, .z = <span class="fl">0.9</span></span>
-<span id="cb45-3"><a href="#cb45-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
-<span id="cb45-4"><a href="#cb45-4" aria-hidden="true" tabindex="-1"></a>v3.twice();</span>
-<span id="cb45-5"><a href="#cb45-5" aria-hidden="true" tabindex="-1"></a>std.debug.print(<span class="st">"Doubled: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>v3.x<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb44"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb44-1"><a href="#cb44-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> v3 = Vec3 <span class="op">{</span></span>
+<span id="cb44-2"><a href="#cb44-2" aria-hidden="true" tabindex="-1"></a>    .x = <span class="fl">4.2</span>, .y = <span class="fl">2.4</span>, .z = <span class="fl">0.9</span></span>
+<span id="cb44-3"><a href="#cb44-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
+<span id="cb44-4"><a href="#cb44-4" aria-hidden="true" tabindex="-1"></a>v3.twice();</span>
+<span id="cb44-5"><a href="#cb44-5" aria-hidden="true" tabindex="-1"></a>std.debug.print(<span class="st">"Doubled: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>v3.x<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Doubled: 8.4</code></pre>
 <p>Now, if you change the <code>self</code> argument in this <code>twice()</code> method to <code>self: Vec3</code>, like in the <code>distance()</code> method, you will get the compiler error exposed below as result. Notice that this error message is showing a line from the <code>twice()</code> method body, indicating that you cannot alter the value of the <code>x</code> data member.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb47"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb47-1"><a href="#cb47-1" aria-hidden="true" tabindex="-1"></a><span class="co">// If we change the function signature of double to:</span></span>
-<span id="cb47-2"><a href="#cb47-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> twice(self: Vec3) <span class="dt">void</span> <span class="op">{</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb46"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb46-1"><a href="#cb46-1" aria-hidden="true" tabindex="-1"></a><span class="co">// If we change the function signature of double to:</span></span>
+<span id="cb46-2"><a href="#cb46-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> twice(self: Vec3) <span class="dt">void</span> <span class="op">{</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>t.zig:16:13: error: cannot assign to constant
         self.x = self.x * 2.0;
@@ -888,31 +885,31 @@ <h2 data-number="2.4" class="anchored" data-anchor-id="sec-type-inference"><span
 <p>Because these weird values contain a dot character before them, we are asking the <code>zig</code> compiler to infer the types of these values inside the switch statement. Then, the <code>zig</code> compiler is looking into the current context where these values are being used, and it is trying to infer the types of these values.</p>
 <p>Since they are being used inside a switch statement, the <code>zig</code> compiler looks into the type of the input object given to the switch statement, which is the <code>order</code> object in this case. Because this object have type <code>AtomicOrder</code>, the <code>zig</code> compiler infers that these values are data members from this type <code>AtomicOrder</code>.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb49"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb49-1"><a href="#cb49-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">inline</span> <span class="kw">fn</span> fence(self: *Self, <span class="kw">comptime</span> order: AtomicOrder) <span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb49-2"><a href="#cb49-2" aria-hidden="true" tabindex="-1"></a>    <span class="co">// many lines of code ...</span></span>
-<span id="cb49-3"><a href="#cb49-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> (builtin.sanitize_thread) <span class="op">{</span></span>
-<span id="cb49-4"><a href="#cb49-4" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> tsan = <span class="kw">struct</span> <span class="op">{</span></span>
-<span id="cb49-5"><a href="#cb49-5" aria-hidden="true" tabindex="-1"></a>            <span class="kw">extern</span> <span class="st">"c"</span> <span class="kw">fn</span> __tsan_acquire(addr: *anyopaque) <span class="dt">void</span>;</span>
-<span id="cb49-6"><a href="#cb49-6" aria-hidden="true" tabindex="-1"></a>            <span class="kw">extern</span> <span class="st">"c"</span> <span class="kw">fn</span> __tsan_release(addr: *anyopaque) <span class="dt">void</span>;</span>
-<span id="cb49-7"><a href="#cb49-7" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span>;</span>
-<span id="cb49-8"><a href="#cb49-8" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb49-9"><a href="#cb49-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> addr: *anyopaque = self;</span>
-<span id="cb49-10"><a href="#cb49-10" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> <span class="kw">switch</span> (order) <span class="op">{</span></span>
-<span id="cb49-11"><a href="#cb49-11" aria-hidden="true" tabindex="-1"></a>            .unordered, .monotonic =&gt; <span class="bu">@compileError</span>(</span>
-<span id="cb49-12"><a href="#cb49-12" aria-hidden="true" tabindex="-1"></a>                <span class="bu">@tagName</span>(order)</span>
-<span id="cb49-13"><a href="#cb49-13" aria-hidden="true" tabindex="-1"></a>                ++ <span class="st">" only applies to atomic loads and stores"</span></span>
-<span id="cb49-14"><a href="#cb49-14" aria-hidden="true" tabindex="-1"></a>            ),</span>
-<span id="cb49-15"><a href="#cb49-15" aria-hidden="true" tabindex="-1"></a>            .acquire =&gt; tsan.__tsan_acquire(addr),</span>
-<span id="cb49-16"><a href="#cb49-16" aria-hidden="true" tabindex="-1"></a>            .release =&gt; tsan.__tsan_release(addr),</span>
-<span id="cb49-17"><a href="#cb49-17" aria-hidden="true" tabindex="-1"></a>            .acq_rel, .seq_cst =&gt; <span class="op">{</span></span>
-<span id="cb49-18"><a href="#cb49-18" aria-hidden="true" tabindex="-1"></a>                tsan.__tsan_acquire(addr);</span>
-<span id="cb49-19"><a href="#cb49-19" aria-hidden="true" tabindex="-1"></a>                tsan.__tsan_release(addr);</span>
-<span id="cb49-20"><a href="#cb49-20" aria-hidden="true" tabindex="-1"></a>            <span class="op">}</span>,</span>
-<span id="cb49-21"><a href="#cb49-21" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span>;</span>
-<span id="cb49-22"><a href="#cb49-22" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb49-23"><a href="#cb49-23" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb49-24"><a href="#cb49-24" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> <span class="bu">@fence</span>(order);</span>
-<span id="cb49-25"><a href="#cb49-25" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb48"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb48-1"><a href="#cb48-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">inline</span> <span class="kw">fn</span> fence(self: *Self, <span class="kw">comptime</span> order: AtomicOrder) <span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb48-2"><a href="#cb48-2" aria-hidden="true" tabindex="-1"></a>    <span class="co">// many lines of code ...</span></span>
+<span id="cb48-3"><a href="#cb48-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> (builtin.sanitize_thread) <span class="op">{</span></span>
+<span id="cb48-4"><a href="#cb48-4" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> tsan = <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb48-5"><a href="#cb48-5" aria-hidden="true" tabindex="-1"></a>            <span class="kw">extern</span> <span class="st">"c"</span> <span class="kw">fn</span> __tsan_acquire(addr: *anyopaque) <span class="dt">void</span>;</span>
+<span id="cb48-6"><a href="#cb48-6" aria-hidden="true" tabindex="-1"></a>            <span class="kw">extern</span> <span class="st">"c"</span> <span class="kw">fn</span> __tsan_release(addr: *anyopaque) <span class="dt">void</span>;</span>
+<span id="cb48-7"><a href="#cb48-7" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span>;</span>
+<span id="cb48-8"><a href="#cb48-8" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb48-9"><a href="#cb48-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> addr: *anyopaque = self;</span>
+<span id="cb48-10"><a href="#cb48-10" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> <span class="kw">switch</span> (order) <span class="op">{</span></span>
+<span id="cb48-11"><a href="#cb48-11" aria-hidden="true" tabindex="-1"></a>            .unordered, .monotonic =&gt; <span class="bu">@compileError</span>(</span>
+<span id="cb48-12"><a href="#cb48-12" aria-hidden="true" tabindex="-1"></a>                <span class="bu">@tagName</span>(order)</span>
+<span id="cb48-13"><a href="#cb48-13" aria-hidden="true" tabindex="-1"></a>                ++ <span class="st">" only applies to atomic loads and stores"</span></span>
+<span id="cb48-14"><a href="#cb48-14" aria-hidden="true" tabindex="-1"></a>            ),</span>
+<span id="cb48-15"><a href="#cb48-15" aria-hidden="true" tabindex="-1"></a>            .acquire =&gt; tsan.__tsan_acquire(addr),</span>
+<span id="cb48-16"><a href="#cb48-16" aria-hidden="true" tabindex="-1"></a>            .release =&gt; tsan.__tsan_release(addr),</span>
+<span id="cb48-17"><a href="#cb48-17" aria-hidden="true" tabindex="-1"></a>            .acq_rel, .seq_cst =&gt; <span class="op">{</span></span>
+<span id="cb48-18"><a href="#cb48-18" aria-hidden="true" tabindex="-1"></a>                tsan.__tsan_acquire(addr);</span>
+<span id="cb48-19"><a href="#cb48-19" aria-hidden="true" tabindex="-1"></a>                tsan.__tsan_release(addr);</span>
+<span id="cb48-20"><a href="#cb48-20" aria-hidden="true" tabindex="-1"></a>            <span class="op">}</span>,</span>
+<span id="cb48-21"><a href="#cb48-21" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span>;</span>
+<span id="cb48-22"><a href="#cb48-22" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb48-23"><a href="#cb48-23" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb48-24"><a href="#cb48-24" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> <span class="bu">@fence</span>(order);</span>
+<span id="cb48-25"><a href="#cb48-25" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>This is how basic type inference is done in Zig. If we didn’t use the dot character before the values inside this switch statement, then, we would be forced to explicitly write the data types of these values. For example, instead of writing <code>.release</code> we would have to write <code>AtomicOrder.release</code>. We would have to do this for every single value in this switch statement, and this is a lot of work. That is why type inference is commonly used on switch statements in Zig.</p>
 </section>
@@ -922,48 +919,49 @@ <h2 data-number="2.5" class="anchored" data-anchor-id="sec-type-cast"><span clas
 <p>Most languages have a formal way to perform type casting. In Rust for example, we normally use the keyword <code>as</code>, and in C, we normally use the type casting syntax, e.g.&nbsp;<code>(int) x</code>. In Zig, we use the <code>@as()</code> built-in function to cast an object of type “x”, into an object of type “y”.</p>
 <p>This <code>@as()</code> function is the preferred way to perform type conversion (or type casting) in Zig. Because it is explicit, and, it also performs the casting only if it is unambiguous and safe. To use this function, you just provide the target data type in the first argument, and, the object that you want cast as the second argument.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb50"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb50-1"><a href="#cb50-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb50-2"><a href="#cb50-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = std.testing.expect;</span>
-<span id="cb50-3"><a href="#cb50-3" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="op">{</span></span>
-<span id="cb50-4"><a href="#cb50-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> x: <span class="dt">usize</span> = <span class="dv">500</span>;</span>
-<span id="cb50-5"><a href="#cb50-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> y = <span class="bu">@as</span>(<span class="dt">u32</span>, x);</span>
-<span id="cb50-6"><a href="#cb50-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(y) == <span class="dt">u32</span>);</span>
-<span id="cb50-7"><a href="#cb50-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb49"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb49-1"><a href="#cb49-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb49-2"><a href="#cb49-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = std.testing.expect;</span>
+<span id="cb49-3"><a href="#cb49-3" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="op">{</span></span>
+<span id="cb49-4"><a href="#cb49-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> x: <span class="dt">usize</span> = <span class="dv">500</span>;</span>
+<span id="cb49-5"><a href="#cb49-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> y = <span class="bu">@as</span>(<span class="dt">u32</span>, x);</span>
+<span id="cb49-6"><a href="#cb49-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(y) == <span class="dt">u32</span>);</span>
+<span id="cb49-7"><a href="#cb49-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 filefe9b6a29a64b.test_0...OKAll 1 tests passed
-  d.</code></pre>
+<pre><code>1/1 file10b91234368fa.test_0...OKAll 1 tests passe
+  ed.</code></pre>
 </div>
 </div>
 <p>This is the general way to perform type casting in Zig. But remember, <code>@as()</code> works only when casting is unambiguous and safe, and there are situations where these assumptions do not hold. For example, when casting an integer value into a float value, or vice-versa, it is not clear to the compiler how to perform this conversion safely.</p>
 <p>Therefore, we need to use specialized “casting functions” in such situations. For example, if you want to cast an integer value into a float value, then, you should use the <code>@floatFromInt()</code> function. In the inverse scenario, you should use the <code>@intFromFloat()</code> function.</p>
 <p>In these functions, you just provide the object that you want to cast as input. Then, the target data type of the “type casting operation” is determined by the type annotation of the object where you are saving the results. In the example below, we are casting the object <code>x</code> into a value of type <code>f32</code>, because the object <code>y</code>, which is where we are saving the results, is annotated as an object of type <code>f32</code>.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb52"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb52-1"><a href="#cb52-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb52-2"><a href="#cb52-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = std.testing.expect;</span>
-<span id="cb52-3"><a href="#cb52-3" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="op">{</span></span>
-<span id="cb52-4"><a href="#cb52-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> x: <span class="dt">usize</span> = <span class="dv">565</span>;</span>
-<span id="cb52-5"><a href="#cb52-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> y: <span class="dt">f32</span> = <span class="bu">@floatFromInt</span>(x);</span>
-<span id="cb52-6"><a href="#cb52-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(y) == <span class="dt">f32</span>);</span>
-<span id="cb52-7"><a href="#cb52-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb51"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb51-1"><a href="#cb51-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb51-2"><a href="#cb51-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = std.testing.expect;</span>
+<span id="cb51-3"><a href="#cb51-3" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="op">{</span></span>
+<span id="cb51-4"><a href="#cb51-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> x: <span class="dt">usize</span> = <span class="dv">565</span>;</span>
+<span id="cb51-5"><a href="#cb51-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> y: <span class="dt">f32</span> = <span class="bu">@floatFromInt</span>(x);</span>
+<span id="cb51-6"><a href="#cb51-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(y) == <span class="dt">f32</span>);</span>
+<span id="cb51-7"><a href="#cb51-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 filefe9b126af3c3.test_0...OKAll 1 tests passed
-  d.</code></pre>
+<pre><code>1/1 file10b9130ae9221.test_0...OKAll 1 tests passe
+  ed.</code></pre>
 </div>
 </div>
 <p>Another built-in function that is very useful when performing type casting operations is <code>@ptrCast()</code>. In essence, we use the <code>@as()</code> built-in function when we want to explicit convert (or cast) a Zig value/object from a type “x” to a type “y”, etc. However, pointers (we are going to discuss pointers in more depth in <a href="05-pointers.html" class="quarto-xref"><span>Chapter 6</span></a>) are a special type of object in Zig, i.e.&nbsp;they are treated differently from “normal objects”.</p>
 <p>Everytime a pointer is involved in some “type casting operation” in Zig, the <code>@ptrCast()</code> function is used. This function works similarly to <code>@floatFromInt()</code>. You just provide the pointer object that you want to cast as input to this function, and the target data type is, once again, determined by the type annotation of the object where the results are being stored.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb54"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb54-1"><a href="#cb54-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb54-2"><a href="#cb54-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = std.testing.expect;</span>
-<span id="cb54-3"><a href="#cb54-3" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="op">{</span></span>
-<span id="cb54-4"><a href="#cb54-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> bytes <span class="kw">align</span>(<span class="bu">@alignOf</span>(<span class="dt">u32</span>)) = [_]<span class="dt">u8</span><span class="op">{</span></span>
-<span id="cb54-5"><a href="#cb54-5" aria-hidden="true" tabindex="-1"></a>        <span class="bn">0x12</span>, <span class="bn">0x12</span>, <span class="bn">0x12</span>, <span class="bn">0x12</span></span>
-<span id="cb54-6"><a href="#cb54-6" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>;</span>
-<span id="cb54-7"><a href="#cb54-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> u32_ptr: *<span class="kw">const</span> <span class="dt">u32</span> = <span class="bu">@ptrCast</span>(&amp;bytes);</span>
-<span id="cb54-8"><a href="#cb54-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(u32_ptr) == *<span class="kw">const</span> <span class="dt">u32</span>);</span>
-<span id="cb54-9"><a href="#cb54-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb53"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb53-1"><a href="#cb53-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb53-2"><a href="#cb53-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = std.testing.expect;</span>
+<span id="cb53-3"><a href="#cb53-3" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="op">{</span></span>
+<span id="cb53-4"><a href="#cb53-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> bytes <span class="kw">align</span>(<span class="bu">@alignOf</span>(<span class="dt">u32</span>)) = [_]<span class="dt">u8</span><span class="op">{</span></span>
+<span id="cb53-5"><a href="#cb53-5" aria-hidden="true" tabindex="-1"></a>        <span class="bn">0x12</span>, <span class="bn">0x12</span>, <span class="bn">0x12</span>, <span class="bn">0x12</span></span>
+<span id="cb53-6"><a href="#cb53-6" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>;</span>
+<span id="cb53-7"><a href="#cb53-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> u32_ptr: *<span class="kw">const</span> <span class="dt">u32</span> = <span class="bu">@ptrCast</span>(&amp;bytes);</span>
+<span id="cb53-8"><a href="#cb53-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(u32_ptr) == *<span class="kw">const</span> <span class="dt">u32</span>);</span>
+<span id="cb53-9"><a href="#cb53-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 filefe9b7366fb7.test_0...OKAll 1 tests passed.</code></pre>
+<pre><code>1/1 file10b914c434861.test_0...OKAll 1 tests passe
+  ed.</code></pre>
 </div>
 </div>
 </section>
@@ -971,22 +969,22 @@ <h2 data-number="2.5" class="anchored" data-anchor-id="sec-type-cast"><span clas
 <h2 data-number="2.6" class="anchored" data-anchor-id="modules"><span class="header-section-number">2.6</span> Modules</h2>
 <p>We already talked about what modules are, and also, how to import other modules into your current module via <em>import statements</em>. Every Zig module (i.e.&nbsp;a <code>.zig</code> file) that you write in your project is internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the Zig Standard Library into our current module.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb56"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb56-1"><a href="#cb56-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb55"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb55-1"><a href="#cb55-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>When we want to access the functions and objects from the standard library, we are basically accessing the data members of the struct stored in the <code>std</code> object. That is why we use the same syntax that we use in normal structs, with the dot operator (<code>.</code>) to access the data members and methods of the struct.</p>
 <p>When this “import statement” get’s executed, the result of this expression is a struct object that contains the Zig Standard Library modules, global variables, functions, etc. And this struct object get’s saved (or stored) inside the constant object named <code>std</code>.</p>
 <p>Take the <a href="https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig"><code>thread_pool.zig</code> module from the project <code>zap</code></a><a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a> as an example. This module is written as if it was a big struct. That is why we have a top-level and public <code>init()</code> method written in this module. The idea is that all top-level functions written in this module are methods from the struct, and all top-level objects and struct declarations are data members of this struct. The module is the struct itself.</p>
 <p>So you would import and use this module by doing something like this:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb57"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb57-1"><a href="#cb57-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb57-2"><a href="#cb57-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ThreadPool = <span class="bu">@import</span>(<span class="st">"thread_pool.zig"</span>);</span>
-<span id="cb57-3"><a href="#cb57-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> num_cpus = std.Thread.getCpuCount()</span>
-<span id="cb57-4"><a href="#cb57-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">catch</span> <span class="bu">@panic</span>(<span class="st">"failed to get cpu core count"</span>);</span>
-<span id="cb57-5"><a href="#cb57-5" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> num_threads = std.math.cast(<span class="dt">u16</span>, num_cpus)</span>
-<span id="cb57-6"><a href="#cb57-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">catch</span> std.math.maxInt(<span class="dt">u16</span>);</span>
-<span id="cb57-7"><a href="#cb57-7" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> pool = ThreadPool.init(</span>
-<span id="cb57-8"><a href="#cb57-8" aria-hidden="true" tabindex="-1"></a>    .<span class="op">{</span> .max_threads = num_threads <span class="op">}</span></span>
-<span id="cb57-9"><a href="#cb57-9" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb56"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb56-1"><a href="#cb56-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb56-2"><a href="#cb56-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ThreadPool = <span class="bu">@import</span>(<span class="st">"thread_pool.zig"</span>);</span>
+<span id="cb56-3"><a href="#cb56-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> num_cpus = std.Thread.getCpuCount()</span>
+<span id="cb56-4"><a href="#cb56-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">catch</span> <span class="bu">@panic</span>(<span class="st">"failed to get cpu core count"</span>);</span>
+<span id="cb56-5"><a href="#cb56-5" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> num_threads = std.math.cast(<span class="dt">u16</span>, num_cpus)</span>
+<span id="cb56-6"><a href="#cb56-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">catch</span> std.math.maxInt(<span class="dt">u16</span>);</span>
+<span id="cb56-7"><a href="#cb56-7" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> pool = ThreadPool.init(</span>
+<span id="cb56-8"><a href="#cb56-8" aria-hidden="true" tabindex="-1"></a>    .<span class="op">{</span> .max_threads = num_threads <span class="op">}</span></span>
+<span id="cb56-9"><a href="#cb56-9" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 
 
diff --git a/docs/Chapters/05-pointers.html b/docs/Chapters/05-pointers.html
index 98ebe8b1..d14f04a5 100644
--- a/docs/Chapters/05-pointers.html
+++ b/docs/Chapters/05-pointers.html
@@ -351,21 +351,20 @@ <h1 class="title"><span id="sec-pointer" class="quarto-section-identifier"><span
 <pre><code>10</code></pre>
 </div>
 </div>
-<pre><code>10</code></pre>
 <p>This syntax to dereference the pointer is nice. Because we can easily chain it with methods of the value pointed by the pointer. We can use the <code>User</code> struct that we have created at <a href="03-structs.html#sec-structs-and-oop" class="quarto-xref"><span>Section 2.3</span></a> as an example. If you comeback to that section, you will see that this struct have a method named <code>print_name()</code>.</p>
 <p>So, for example, if we have an user object, and a pointer that points to this user object, we can use the pointer to access this user object, and, at the same time, call the method <code>print_name()</code> on it, by chaining the dereference method (<code>*</code>) with the <code>print_name()</code> method. Like in the example below:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb5"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> u = User.init(<span class="dv">1</span>, <span class="st">"pedro"</span>, <span class="st">"email@gmail.com"</span>);</span>
-<span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> pointer = &amp;u;</span>
-<span id="cb5-3"><a href="#cb5-3" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> pointer.*.print_name();</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb4"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> u = User.init(<span class="dv">1</span>, <span class="st">"pedro"</span>, <span class="st">"email@gmail.com"</span>);</span>
+<span id="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> pointer = &amp;u;</span>
+<span id="cb4-3"><a href="#cb4-3" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> pointer.*.print_name();</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>pedro</code></pre>
 <p>We can also use pointers to effectively alter the value of an object. For example, I could use the <code>pointer</code> object to set the value of the object <code>number</code> to 6, like in the example below.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb7"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> number: <span class="dt">u8</span> = <span class="dv">5</span>;</span>
-<span id="cb7-2"><a href="#cb7-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> pointer = &amp;number;</span>
-<span id="cb7-3"><a href="#cb7-3" aria-hidden="true" tabindex="-1"></a>pointer.* = <span class="dv">6</span>;</span>
-<span id="cb7-4"><a href="#cb7-4" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>number<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb6"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> number: <span class="dt">u8</span> = <span class="dv">5</span>;</span>
+<span id="cb6-2"><a href="#cb6-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> pointer = &amp;number;</span>
+<span id="cb6-3"><a href="#cb6-3" aria-hidden="true" tabindex="-1"></a>pointer.* = <span class="dv">6</span>;</span>
+<span id="cb6-4"><a href="#cb6-4" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>number<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>6</code></pre>
 </div>
@@ -378,18 +377,18 @@ <h2 data-number="6.1" class="anchored" data-anchor-id="sec-pointer-var"><span cl
 <p>You can have a pointer that points to a constant object, or, a pointer that points to a variable object. But regardless of who this pointer is, a pointer <strong>must always respect the characteristics of the object that it points to</strong>. As a consequence, if the pointer points to a constant object, then, you cannot use this pointer to change the value that it points to. Because it points to a value that is constant. As we discussed at <a href="01-zig-weird.html#sec-assignments" class="quarto-xref"><span>Section 1.4</span></a>, you cannot change a value that is constant.</p>
 <p>For example, if I have a <code>number</code> object, which is constant, I cannot execute the expression below where I’m trying to change the value of <code>number</code> to 6 through the <code>pointer</code> object. As demonstrated below, when you try to do something like that, you get a compile time error:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb9"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb9-1"><a href="#cb9-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> number = <span class="dv">5</span>;</span>
-<span id="cb9-2"><a href="#cb9-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> pointer = &amp;number;</span>
-<span id="cb9-3"><a href="#cb9-3" aria-hidden="true" tabindex="-1"></a>pointer.* = <span class="dv">6</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb8"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> number = <span class="dv">5</span>;</span>
+<span id="cb8-2"><a href="#cb8-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> pointer = &amp;number;</span>
+<span id="cb8-3"><a href="#cb8-3" aria-hidden="true" tabindex="-1"></a>pointer.* = <span class="dv">6</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>p.zig:6:12: error: cannot assign to constant
     pointer.* = 6;</code></pre>
 <p>If I change the <code>number</code> object to be a variable object, by introducing the <code>var</code> keyword, then, I can successfully change the value of this object through a pointer, as demonstrated below:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb11"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> number: <span class="dt">u8</span> = <span class="dv">5</span>;</span>
-<span id="cb11-2"><a href="#cb11-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> pointer = &amp;number;</span>
-<span id="cb11-3"><a href="#cb11-3" aria-hidden="true" tabindex="-1"></a>pointer.* = <span class="dv">6</span>;</span>
-<span id="cb11-4"><a href="#cb11-4" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>number<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb10"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> number: <span class="dt">u8</span> = <span class="dv">5</span>;</span>
+<span id="cb10-2"><a href="#cb10-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> pointer = &amp;number;</span>
+<span id="cb10-3"><a href="#cb10-3" aria-hidden="true" tabindex="-1"></a>pointer.* = <span class="dv">6</span>;</span>
+<span id="cb10-4"><a href="#cb10-4" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>number<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>6</code></pre>
 </div>
@@ -400,12 +399,12 @@ <h2 data-number="6.1" class="anchored" data-anchor-id="sec-pointer-var"><span cl
 <p>Until this point, the <code>pointer</code> object was always constant, but what this means for us? What is the consequence of the <code>pointer</code> object being constant? The consequence is that we cannot change the pointer object, because it is constant. We can use the pointer object in multiple ways, but we cannot change the memory address that is inside this pointer object.</p>
 <p>However, if we mark the <code>pointer</code> object as a variable object, then, we can change the memory address pointed by this <code>pointer</code> object. The example below demonstrates that. Notice that the object pointed by the <code>pointer</code> object changes from <code>c1</code> to <code>c2</code>.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb13"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> c1: <span class="dt">u8</span> = <span class="dv">5</span>;</span>
-<span id="cb13-2"><a href="#cb13-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> c2: <span class="dt">u8</span> = <span class="dv">6</span>;</span>
-<span id="cb13-3"><a href="#cb13-3" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> pointer = &amp;c1;</span>
-<span id="cb13-4"><a href="#cb13-4" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>pointer.*<span class="op">}</span>);</span>
-<span id="cb13-5"><a href="#cb13-5" aria-hidden="true" tabindex="-1"></a>pointer = &amp;c2;</span>
-<span id="cb13-6"><a href="#cb13-6" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>pointer.*<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb12"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> c1: <span class="dt">u8</span> = <span class="dv">5</span>;</span>
+<span id="cb12-2"><a href="#cb12-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> c2: <span class="dt">u8</span> = <span class="dv">6</span>;</span>
+<span id="cb12-3"><a href="#cb12-3" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> pointer = &amp;c1;</span>
+<span id="cb12-4"><a href="#cb12-4" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>pointer.*<span class="op">}</span>);</span>
+<span id="cb12-5"><a href="#cb12-5" aria-hidden="true" tabindex="-1"></a>pointer = &amp;c2;</span>
+<span id="cb12-6"><a href="#cb12-6" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>pointer.*<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>5
 6</code></pre>
@@ -427,13 +426,13 @@ <h2 data-number="6.3" class="anchored" data-anchor-id="pointer-arithmetic"><span
 <p>Pointer arithmetic is available in Zig, and they work the same way they work in C. When you have a pointer that points to an array, the pointer usually points to the first element in the array, and you can use pointer arithmetic to advance this pointer and access the other elements in the array.</p>
 <p>Notice in the example below, that initially, the <code>ptr</code> object was pointing to the first element in the array <code>ar</code>. But then, I started to walk through the array, by advancing the pointer with simple pointer arithmetic.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb15"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb15-1"><a href="#cb15-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ar = [_]<span class="dt">i32</span><span class="op">{</span><span class="dv">1</span>,<span class="dv">2</span>,<span class="dv">3</span>,<span class="dv">4</span><span class="op">}</span>;</span>
-<span id="cb15-2"><a href="#cb15-2" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> ptr = &amp;ar;</span>
-<span id="cb15-3"><a href="#cb15-3" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>ptr.*<span class="op">}</span>);</span>
-<span id="cb15-4"><a href="#cb15-4" aria-hidden="true" tabindex="-1"></a>ptr += <span class="dv">1</span>;</span>
-<span id="cb15-5"><a href="#cb15-5" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>ptr.*<span class="op">}</span>);</span>
-<span id="cb15-6"><a href="#cb15-6" aria-hidden="true" tabindex="-1"></a>ptr += <span class="dv">1</span>;</span>
-<span id="cb15-7"><a href="#cb15-7" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>ptr.*<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb14"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ar = [_]<span class="dt">i32</span><span class="op">{</span><span class="dv">1</span>,<span class="dv">2</span>,<span class="dv">3</span>,<span class="dv">4</span><span class="op">}</span>;</span>
+<span id="cb14-2"><a href="#cb14-2" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> ptr = &amp;ar;</span>
+<span id="cb14-3"><a href="#cb14-3" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>ptr.*<span class="op">}</span>);</span>
+<span id="cb14-4"><a href="#cb14-4" aria-hidden="true" tabindex="-1"></a>ptr += <span class="dv">1</span>;</span>
+<span id="cb14-5"><a href="#cb14-5" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>ptr.*<span class="op">}</span>);</span>
+<span id="cb14-6"><a href="#cb14-6" aria-hidden="true" tabindex="-1"></a>ptr += <span class="dv">1</span>;</span>
+<span id="cb14-7"><a href="#cb14-7" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>ptr.*<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>1
 2
@@ -442,9 +441,9 @@ <h2 data-number="6.3" class="anchored" data-anchor-id="pointer-arithmetic"><span
 <p>Behind the hood, slices already are pointers, and they also come with the <code>len</code> property, which indicates how many elements are in the slice. This is good because the <code>zig</code> compiler can use it to check for potential buffer overflows, and other problems like that.</p>
 <p>Also, you don’t need to use pointer arithmetic to walk through the elements of a slice. You can simply use the <code>slice[index]</code> syntax to directly access any element you want in the slice. As I mentioned at <a href="01-zig-weird.html#sec-arrays" class="quarto-xref"><span>Section 1.6</span></a>, you can get a slice from an array by using a range selector inside brackets. In the example below, I’m creating a slice (<code>sl</code>) that covers the entire <code>ar</code> array. I can access any element of <code>ar</code> from this slice, and, the slice itself already is a pointer behind the hood.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb17"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ar = [_]<span class="dt">i32</span><span class="op">{</span><span class="dv">1</span>,<span class="dv">2</span>,<span class="dv">3</span>,<span class="dv">4</span><span class="op">}</span>;</span>
-<span id="cb17-2"><a href="#cb17-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> sl = ar[<span class="dv">0</span>..ar.len];</span>
-<span id="cb17-3"><a href="#cb17-3" aria-hidden="true" tabindex="-1"></a>_ = sl;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb16"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ar = [_]<span class="dt">i32</span><span class="op">{</span><span class="dv">1</span>,<span class="dv">2</span>,<span class="dv">3</span>,<span class="dv">4</span><span class="op">}</span>;</span>
+<span id="cb16-2"><a href="#cb16-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> sl = ar[<span class="dv">0</span>..ar.len];</span>
+<span id="cb16-3"><a href="#cb16-3" aria-hidden="true" tabindex="-1"></a>_ = sl;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
 <section id="optionals-and-optional-pointers" class="level2" data-number="6.4">
@@ -453,8 +452,8 @@ <h2 data-number="6.4" class="anchored" data-anchor-id="optionals-and-optional-po
 <p>This is a powerful feature of Zig when you compare it to the developer experience in C. Because in C, any object can be null at any point, and, as consequence, a pointer in C might point to a null value. This is a common source of undefined behaviour in C. When programmers work with pointers in C, they have to constantly check if their pointers are pointing to null values or not.</p>
 <p>If for some reason, your Zig code produces a null value somewhere, and, this null value ends up in an object that is non-nullable, a runtime error is always raised by your Zig program. Take the program below as an example. The <code>zig</code> compiler can see the <code>null</code> value at compile time, and, as result, it raises a compile time error. But, if a <code>null</code> value is raised during runtime, a runtime error is also raised by the Zig program, with a “attempt to use null value” message.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb18"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb18-1"><a href="#cb18-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> number: <span class="dt">u8</span> = <span class="dv">5</span>;</span>
-<span id="cb18-2"><a href="#cb18-2" aria-hidden="true" tabindex="-1"></a>number = <span class="cn">null</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb17"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> number: <span class="dt">u8</span> = <span class="dv">5</span>;</span>
+<span id="cb17-2"><a href="#cb17-2" aria-hidden="true" tabindex="-1"></a>number = <span class="cn">null</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>p5.zig:5:14: error: expected type 'u8',
         found '@TypeOf(null)'
@@ -468,8 +467,8 @@ <h3 data-number="6.4.1" class="anchored" data-anchor-id="what-are-optionals"><sp
 <p>An optional object in Zig is an object that can be null. To mark an object as optional, we use the <code>?</code> operator. When you put this <code>?</code> operator right before the data type of an object, you transform this data type into an optional data type, and the object becomes an optional object.</p>
 <p>Take the snippet below as an example. We are creating a new variable object called <code>num</code>. This object have the data type <code>?i32</code>, which means that, this object contains either a signed 32-bit integer (<code>i32</code>), or, a null value. Both alternatives are valid values to the <code>num</code> object. That is why, I can actually change the value of this object to null, and, no errors are raised by the <code>zig</code> compiler, as demonstrated below:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb20"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb20-1"><a href="#cb20-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> num: ?<span class="dt">i32</span> = <span class="dv">5</span>;</span>
-<span id="cb20-2"><a href="#cb20-2" aria-hidden="true" tabindex="-1"></a>num = <span class="cn">null</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb19"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb19-1"><a href="#cb19-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> num: ?<span class="dt">i32</span> = <span class="dv">5</span>;</span>
+<span id="cb19-2"><a href="#cb19-2" aria-hidden="true" tabindex="-1"></a>num = <span class="cn">null</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
 <section id="optional-pointers" class="level3" data-number="6.4.2">
@@ -478,18 +477,18 @@ <h3 data-number="6.4.2" class="anchored" data-anchor-id="optional-pointers"><spa
 <p>In the example below, we are creating a variable object named <code>num</code>, and an optional pointer object named <code>ptr</code>. Notice that the data type of the object <code>ptr</code> indicates that it is either a null value, or a pointer to an <code>i32</code> value. Also, notice that the pointer object (<code>ptr</code>) can be marked as optional, even if the object <code>num</code> is not optional.</p>
 <p>What this code tells us is that, the <code>num</code> variable will never contain a null value. This variable will always contain a valid <code>i32</code> value. But in contrast, the <code>ptr</code> object might contain either a null value, or, a pointer to an <code>i32</code> value.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb21"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb21-1"><a href="#cb21-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> num: <span class="dt">i32</span> = <span class="dv">5</span>;</span>
-<span id="cb21-2"><a href="#cb21-2" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> ptr: ?*<span class="dt">i32</span> = &amp;num;</span>
-<span id="cb21-3"><a href="#cb21-3" aria-hidden="true" tabindex="-1"></a>ptr = <span class="cn">null</span>;</span>
-<span id="cb21-4"><a href="#cb21-4" aria-hidden="true" tabindex="-1"></a>num = <span class="dv">6</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb20"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb20-1"><a href="#cb20-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> num: <span class="dt">i32</span> = <span class="dv">5</span>;</span>
+<span id="cb20-2"><a href="#cb20-2" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> ptr: ?*<span class="dt">i32</span> = &amp;num;</span>
+<span id="cb20-3"><a href="#cb20-3" aria-hidden="true" tabindex="-1"></a>ptr = <span class="cn">null</span>;</span>
+<span id="cb20-4"><a href="#cb20-4" aria-hidden="true" tabindex="-1"></a>num = <span class="dv">6</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>But what happens if we turn the table, and mark the <code>num</code> object as optional, instead of the pointer object. If we do that, then, the pointer object is not optional anymore. It would be a similar (although different) result. Because then, we would have a pointer to an optional value. In other words, a pointer to a value that is either a null value, or, a not-null value.</p>
 <p>In the example below, we are recreating this idea. Now, the <code>ptr</code> object have a data type of <code>*?i32</code>, instead of <code>?*i32</code>. Notice that the <code>*</code> symbol comes before of <code>?</code> this time. So now, we have a pointer that points to a value that is either null , or, a signed 32-bit integer.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb22"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb22-1"><a href="#cb22-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> num: ?<span class="dt">i32</span> = <span class="dv">5</span>;</span>
-<span id="cb22-2"><a href="#cb22-2" aria-hidden="true" tabindex="-1"></a><span class="co">// ptr have type `*?i32`, instead of `?*i32`.</span></span>
-<span id="cb22-3"><a href="#cb22-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ptr = &amp;num;</span>
-<span id="cb22-4"><a href="#cb22-4" aria-hidden="true" tabindex="-1"></a>_ = ptr;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb21"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb21-1"><a href="#cb21-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> num: ?<span class="dt">i32</span> = <span class="dv">5</span>;</span>
+<span id="cb21-2"><a href="#cb21-2" aria-hidden="true" tabindex="-1"></a><span class="co">// ptr have type `*?i32`, instead of `?*i32`.</span></span>
+<span id="cb21-3"><a href="#cb21-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ptr = &amp;num;</span>
+<span id="cb21-4"><a href="#cb21-4" aria-hidden="true" tabindex="-1"></a>_ = ptr;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
 <section id="sec-null-handling" class="level3" data-number="6.4.3">
@@ -503,10 +502,10 @@ <h3 data-number="6.4.3" class="anchored" data-anchor-id="sec-null-handling"><spa
 </ul>
 <p>When you use an if statement, you use a pair of pipes to unwrap the optional value, and use this “unwrapped object” inside the if block. Using the example below as a reference, if the object <code>num</code> is null, then, the code inside the if statement is not executed. Otherwise, the if statement will unwrap the object <code>num</code> into the <code>not_null_num</code> object. This <code>not_null_num</code> object is guaranteed to be not null inside the scope of the if statement.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb23"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb23-1"><a href="#cb23-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> num: ?<span class="dt">i32</span> = <span class="dv">5</span>;</span>
-<span id="cb23-2"><a href="#cb23-2" aria-hidden="true" tabindex="-1"></a><span class="kw">if</span> (num) |not_null_num| <span class="op">{</span></span>
-<span id="cb23-3"><a href="#cb23-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>not_null_num<span class="op">}</span>);</span>
-<span id="cb23-4"><a href="#cb23-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb22"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb22-1"><a href="#cb22-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> num: ?<span class="dt">i32</span> = <span class="dv">5</span>;</span>
+<span id="cb22-2"><a href="#cb22-2" aria-hidden="true" tabindex="-1"></a><span class="kw">if</span> (num) |not_null_num| <span class="op">{</span></span>
+<span id="cb22-3"><a href="#cb22-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>not_null_num<span class="op">}</span>);</span>
+<span id="cb22-4"><a href="#cb22-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>5</code></pre>
 </div>
@@ -515,9 +514,9 @@ <h3 data-number="6.4.3" class="anchored" data-anchor-id="sec-null-handling"><spa
 <p>The idea behind the <code>orelse</code> keyword is: if the expression on the left side result in a not-null value, then, this not-null value is used. However, if this expression on the left side result in a null value, then, the value of the expression on the right side is used instead.</p>
 <p>Looking at the example below, since the <code>x</code> object is currently null, the <code>orelse</code> decided to use the alternative value, which is the number 15.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb25"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb25-1"><a href="#cb25-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> x: ?<span class="dt">i32</span> = <span class="cn">null</span>;</span>
-<span id="cb25-2"><a href="#cb25-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> dbl = (x <span class="kw">orelse</span> <span class="dv">15</span>) * <span class="dv">2</span>;</span>
-<span id="cb25-3"><a href="#cb25-3" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>dbl<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb24"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb24-1"><a href="#cb24-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> x: ?<span class="dt">i32</span> = <span class="cn">null</span>;</span>
+<span id="cb24-2"><a href="#cb24-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> dbl = (x <span class="kw">orelse</span> <span class="dv">15</span>) * <span class="dv">2</span>;</span>
+<span id="cb24-3"><a href="#cb24-3" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>dbl<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>30</code></pre>
 </div>
@@ -525,18 +524,18 @@ <h3 data-number="6.4.3" class="anchored" data-anchor-id="sec-null-handling"><spa
 <p>You can use the if statement or the <code>orelse</code> keyword, when you want to solve (or deal with) this null value. However, if there is no clear solution to this null value, and the most logic and sane path is to simply panic and raise a loud error in your program when this null value is encountered, you can use the <code>?</code> method of your optional object.</p>
 <p>In essence, when you use this <code>?</code> method, the optional object is unwrapped. If a not-null value is found in the optional object, then, this not-null value is used. Otherwise, the <code>unreachable</code> keyword is used. You can read more about this <a href="https://ziglang.org/documentation/master/#unreachable"><code>unreacheable</code> keyword at the official documentation</a><a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>. But in essence, when you build your Zig source code using the build modes <code>ReleaseSafe</code> or <code>Debug</code>, this <code>unreacheable</code> keyword causes the program to panic and raise an error during runtime, like in the example below:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb27"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb27-1"><a href="#cb27-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb27-2"><a href="#cb27-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
-<span id="cb27-3"><a href="#cb27-3" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> return_null(n: <span class="dt">i32</span>) ?<span class="dt">i32</span> <span class="op">{</span></span>
-<span id="cb27-4"><a href="#cb27-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> (n == <span class="dv">5</span>) <span class="kw">return</span> <span class="cn">null</span>;</span>
-<span id="cb27-5"><a href="#cb27-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> n;</span>
-<span id="cb27-6"><a href="#cb27-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
-<span id="cb27-7"><a href="#cb27-7" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb27-8"><a href="#cb27-8" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb27-9"><a href="#cb27-9" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> x: <span class="dt">i32</span> = <span class="dv">5</span>;</span>
-<span id="cb27-10"><a href="#cb27-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> y: ?<span class="dt">i32</span> = return_null(x);</span>
-<span id="cb27-11"><a href="#cb27-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>y.?<span class="op">}</span>);</span>
-<span id="cb27-12"><a href="#cb27-12" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb26"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb26-1"><a href="#cb26-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb26-2"><a href="#cb26-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
+<span id="cb26-3"><a href="#cb26-3" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> return_null(n: <span class="dt">i32</span>) ?<span class="dt">i32</span> <span class="op">{</span></span>
+<span id="cb26-4"><a href="#cb26-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> (n == <span class="dv">5</span>) <span class="kw">return</span> <span class="cn">null</span>;</span>
+<span id="cb26-5"><a href="#cb26-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> n;</span>
+<span id="cb26-6"><a href="#cb26-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
+<span id="cb26-7"><a href="#cb26-7" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb26-8"><a href="#cb26-8" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb26-9"><a href="#cb26-9" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> x: <span class="dt">i32</span> = <span class="dv">5</span>;</span>
+<span id="cb26-10"><a href="#cb26-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> y: ?<span class="dt">i32</span> = return_null(x);</span>
+<span id="cb26-11"><a href="#cb26-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>y.?<span class="op">}</span>);</span>
+<span id="cb26-12"><a href="#cb26-12" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>thread 12767 panic: attempt to use null value
 p7.zig:12:34: 0x103419d in main (p7):
diff --git a/docs/Chapters/09-data-structures.html b/docs/Chapters/09-data-structures.html
index c556478d..75cbf5a3 100644
--- a/docs/Chapters/09-data-structures.html
+++ b/docs/Chapters/09-data-structures.html
@@ -599,10 +599,6 @@ <h3 data-number="11.2.3" class="anchored" data-anchor-id="iterating-through-the-
 <span id="cb11-19"><a href="#cb11-19" aria-hidden="true" tabindex="-1"></a>        std.debug.print(<span class="st">"Value: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>kv.value_ptr.*<span class="op">}</span>);</span>
 <span id="cb11-20"><a href="#cb11-20" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
 <span id="cb11-21"><a href="#cb11-21" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
-<div class="cell-output cell-output-stdout">
-<pre><code>Key: 54321 | Value: 89Key: 50050 | Value: 55Key: 5
-  57709 | Value: 41</code></pre>
-</div>
 </div>
 <pre><code>Key: 54321 | Value: 89
 Key: 50050 | Value: 55
@@ -610,10 +606,10 @@ <h3 data-number="11.2.3" class="anchored" data-anchor-id="iterating-through-the-
 <p>If you want to iterate specifically through the values or the keys of your hashtable, you can create a key iterator or a value iterator object. These are also iterator objects, which have the same <code>next()</code> method that you can use to iterate through the hashtable.</p>
 <p>Key iterators are created from the <code>keyIterator()</code> method of your hashtable object, while value iterators are created from the <code>valueIterator()</code> method. All you have to do is to unwrap the value from the <code>next()</code> method and deference it directly to access the key or the value that you are iterating over. The code example below demonstrates the use of a key iterator, but you can replicate the same logic to a value iterator.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb14"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> kit = hash_table.keyIterator();</span>
-<span id="cb14-2"><a href="#cb14-2" aria-hidden="true" tabindex="-1"></a><span class="kw">while</span> (kit.next()) |key| <span class="op">{</span></span>
-<span id="cb14-3"><a href="#cb14-3" aria-hidden="true" tabindex="-1"></a>    std.debug.print(<span class="st">"Key: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>key.*<span class="op">}</span>);</span>
-<span id="cb14-4"><a href="#cb14-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb13"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> kit = hash_table.keyIterator();</span>
+<span id="cb13-2"><a href="#cb13-2" aria-hidden="true" tabindex="-1"></a><span class="kw">while</span> (kit.next()) |key| <span class="op">{</span></span>
+<span id="cb13-3"><a href="#cb13-3" aria-hidden="true" tabindex="-1"></a>    std.debug.print(<span class="st">"Key: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>key.*<span class="op">}</span>);</span>
+<span id="cb13-4"><a href="#cb13-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Key: 54321
 Key: 50050
@@ -634,9 +630,9 @@ <h3 data-number="11.2.4" class="anchored" data-anchor-id="sec-array-map"><span c
 <p>This means that, with <code>swapRemove()</code> you remove the value from the hashtable, but you do not preserve the order in which the values were inserted into the structure. While <code>orderedRemove()</code> is able to retain the order in which these values were inserted.</p>
 <p>But instead of providing an index as input to <code>swapRemove()</code> or <code>orderedRemove()</code>, like I described at <a href="#sec-dynamic-array-remove" class="quarto-xref"><span>Section 11.1.4</span></a>, these methods here in an <code>ArrayHashMap</code> take a key as input, like the <code>remove()</code> method from a <code>HashMap</code> object. If you want to provide an index as input, instead of a key, you should use the <code>swapRemoveAt()</code> and <code>orderedRemoveAt()</code> methods.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb16"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> hash_table = AutoArrayHashMap(<span class="dt">u32</span>, <span class="dt">u16</span>)</span>
-<span id="cb16-2"><a href="#cb16-2" aria-hidden="true" tabindex="-1"></a>    .init(allocator);</span>
-<span id="cb16-3"><a href="#cb16-3" aria-hidden="true" tabindex="-1"></a><span class="kw">defer</span> hash_table.deinit();</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb15"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb15-1"><a href="#cb15-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> hash_table = AutoArrayHashMap(<span class="dt">u32</span>, <span class="dt">u16</span>)</span>
+<span id="cb15-2"><a href="#cb15-2" aria-hidden="true" tabindex="-1"></a>    .init(allocator);</span>
+<span id="cb15-3"><a href="#cb15-3" aria-hidden="true" tabindex="-1"></a><span class="kw">defer</span> hash_table.deinit();</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
 <section id="sec-string-hash-map" class="level3" data-number="11.2.5">
@@ -644,33 +640,33 @@ <h3 data-number="11.2.5" class="anchored" data-anchor-id="sec-string-hash-map"><
 <p>One thing that you will notice in the other two types of hashtables that I have presented over the last sections, is that neither of them accepts a slice data type in their keys. What this means is that you cannot use a slice value to represent a key in these types of hashtable.</p>
 <p>The most obvious consequence of this, is that you cannot use strings as keys in these hashtables. But it is extremely common to use strings as keys in hashtables.</p>
 <p>Take this very simple Javascript code snippet as an example. We are creating a simple hashtable object named <code>people</code>. Then, we add a new entry to this hashtable, which is identified by the string <code>'Pedro'</code>. This string is the key in this case, while the object containing different personal information such as age, height and city, is the value to be stored in the hashtable.</p>
-<div class="sourceCode" id="cb17"><pre class="sourceCode js code-with-copy"><code class="sourceCode javascript"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> people <span class="op">=</span> <span class="kw">new</span> <span class="bu">Object</span>()<span class="op">;</span></span>
-<span id="cb17-2"><a href="#cb17-2" aria-hidden="true" tabindex="-1"></a>people[<span class="st">'Pedro'</span>] <span class="op">=</span> {</span>
-<span id="cb17-3"><a href="#cb17-3" aria-hidden="true" tabindex="-1"></a>    <span class="st">'age'</span><span class="op">:</span> <span class="dv">25</span><span class="op">,</span></span>
-<span id="cb17-4"><a href="#cb17-4" aria-hidden="true" tabindex="-1"></a>    <span class="st">'height'</span><span class="op">:</span> <span class="fl">1.67</span><span class="op">,</span></span>
-<span id="cb17-5"><a href="#cb17-5" aria-hidden="true" tabindex="-1"></a>    <span class="st">'city'</span><span class="op">:</span> <span class="st">'Belo Horizonte'</span></span>
-<span id="cb17-6"><a href="#cb17-6" aria-hidden="true" tabindex="-1"></a>}<span class="op">;</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode" id="cb16"><pre class="sourceCode js code-with-copy"><code class="sourceCode javascript"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> people <span class="op">=</span> <span class="kw">new</span> <span class="bu">Object</span>()<span class="op">;</span></span>
+<span id="cb16-2"><a href="#cb16-2" aria-hidden="true" tabindex="-1"></a>people[<span class="st">'Pedro'</span>] <span class="op">=</span> {</span>
+<span id="cb16-3"><a href="#cb16-3" aria-hidden="true" tabindex="-1"></a>    <span class="st">'age'</span><span class="op">:</span> <span class="dv">25</span><span class="op">,</span></span>
+<span id="cb16-4"><a href="#cb16-4" aria-hidden="true" tabindex="-1"></a>    <span class="st">'height'</span><span class="op">:</span> <span class="fl">1.67</span><span class="op">,</span></span>
+<span id="cb16-5"><a href="#cb16-5" aria-hidden="true" tabindex="-1"></a>    <span class="st">'city'</span><span class="op">:</span> <span class="st">'Belo Horizonte'</span></span>
+<span id="cb16-6"><a href="#cb16-6" aria-hidden="true" tabindex="-1"></a>}<span class="op">;</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <p>This pattern of using strings as keys is very common in all sorts of situations. That is why the Zig Standard Library offers a specific type of hashtable for this purpose, which is created through the <code>StringHashMap()</code> function. This function creates a hashtable that uses strings as keys. The only input of this function is the data type of the values that will be stored into this hashtable.</p>
 <p>In the example below, I’m creating a hashtable to store the ages of different people. Each key in this hashtable is represented by the name of each person, while the value stored in the hashtable is the age of this person identified by the key.</p>
 <p>That is why I provide the <code>u8</code> data type (which is the data type used by the age values) as input to this <code>StringHashMap()</code> function. As the result, it creates a hashtable that uses string values as keys, and, that stores <code>u8</code> values in it. Notice that an allocator object is provided at the <code>init()</code> method of the resulting object from the <code>StringHashMap()</code> function.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb18"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb18-1"><a href="#cb18-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb18-2"><a href="#cb18-2" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb18-3"><a href="#cb18-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> gpa = std.heap.GeneralPurposeAllocator(.<span class="op">{}</span>)<span class="op">{}</span>;</span>
-<span id="cb18-4"><a href="#cb18-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> allocator = gpa.allocator();</span>
-<span id="cb18-5"><a href="#cb18-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> ages = std.StringHashMap(<span class="dt">u8</span>).init(allocator);</span>
-<span id="cb18-6"><a href="#cb18-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">defer</span> ages.deinit();</span>
-<span id="cb18-7"><a href="#cb18-7" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb18-8"><a href="#cb18-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> ages.put(<span class="st">"Pedro"</span>, <span class="dv">25</span>);</span>
-<span id="cb18-9"><a href="#cb18-9" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> ages.put(<span class="st">"Matheus"</span>, <span class="dv">21</span>);</span>
-<span id="cb18-10"><a href="#cb18-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> ages.put(<span class="st">"Abgail"</span>, <span class="dv">42</span>);</span>
-<span id="cb18-11"><a href="#cb18-11" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb18-12"><a href="#cb18-12" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> it = ages.iterator();</span>
-<span id="cb18-13"><a href="#cb18-13" aria-hidden="true" tabindex="-1"></a>    <span class="kw">while</span> (it.next()) |kv| <span class="op">{</span></span>
-<span id="cb18-14"><a href="#cb18-14" aria-hidden="true" tabindex="-1"></a>        std.debug.print(<span class="st">"Key: {s} | "</span>, .<span class="op">{</span>kv.key_ptr.*<span class="op">}</span>);</span>
-<span id="cb18-15"><a href="#cb18-15" aria-hidden="true" tabindex="-1"></a>        std.debug.print(<span class="st">"Age: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>kv.value_ptr.*<span class="op">}</span>);</span>
-<span id="cb18-16"><a href="#cb18-16" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb18-17"><a href="#cb18-17" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb17"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb17-2"><a href="#cb17-2" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb17-3"><a href="#cb17-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> gpa = std.heap.GeneralPurposeAllocator(.<span class="op">{}</span>)<span class="op">{}</span>;</span>
+<span id="cb17-4"><a href="#cb17-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> allocator = gpa.allocator();</span>
+<span id="cb17-5"><a href="#cb17-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> ages = std.StringHashMap(<span class="dt">u8</span>).init(allocator);</span>
+<span id="cb17-6"><a href="#cb17-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">defer</span> ages.deinit();</span>
+<span id="cb17-7"><a href="#cb17-7" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb17-8"><a href="#cb17-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> ages.put(<span class="st">"Pedro"</span>, <span class="dv">25</span>);</span>
+<span id="cb17-9"><a href="#cb17-9" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> ages.put(<span class="st">"Matheus"</span>, <span class="dv">21</span>);</span>
+<span id="cb17-10"><a href="#cb17-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> ages.put(<span class="st">"Abgail"</span>, <span class="dv">42</span>);</span>
+<span id="cb17-11"><a href="#cb17-11" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb17-12"><a href="#cb17-12" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> it = ages.iterator();</span>
+<span id="cb17-13"><a href="#cb17-13" aria-hidden="true" tabindex="-1"></a>    <span class="kw">while</span> (it.next()) |kv| <span class="op">{</span></span>
+<span id="cb17-14"><a href="#cb17-14" aria-hidden="true" tabindex="-1"></a>        std.debug.print(<span class="st">"Key: {s} | "</span>, .<span class="op">{</span>kv.key_ptr.*<span class="op">}</span>);</span>
+<span id="cb17-15"><a href="#cb17-15" aria-hidden="true" tabindex="-1"></a>        std.debug.print(<span class="st">"Age: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>kv.value_ptr.*<span class="op">}</span>);</span>
+<span id="cb17-16"><a href="#cb17-16" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb17-17"><a href="#cb17-17" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Key: Pedro | Age: 25
 Key: Abgail | Age: 42
@@ -683,7 +679,7 @@ <h3 data-number="11.2.6" class="anchored" data-anchor-id="the-stringarrayhashmap
 <p>You can insert new values into this hashtable by using the same <code>put()</code> method that we have discussed at <a href="#sec-string-hash-map" class="quarto-xref"><span>Section 11.2.5</span></a>. And you can also get values from the hashtable by using the same <code>get()</code> method. Like its <code>ArrayHashMap</code> brother, to delete values from this specific type of hashtable, we also use the <code>orderedRemove()</code> and <code>swapRemove()</code> methods, with the same effects that I have described at <a href="#sec-array-map" class="quarto-xref"><span>Section 11.2.4</span></a>.</p>
 <p>If we take the code example that was exposed at <a href="#sec-string-hash-map" class="quarto-xref"><span>Section 11.2.5</span></a>, we can achieve the exact same result with <code>StringArrayHashMap()</code>:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb20"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb20-1"><a href="#cb20-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> ages = std.StringArrayHashMap(<span class="dt">u8</span>).init(allocator);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb19"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb19-1"><a href="#cb19-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> ages = std.StringArrayHashMap(<span class="dt">u8</span>).init(allocator);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
 </section>
@@ -726,24 +722,24 @@ <h2 data-number="11.3" class="anchored" data-anchor-id="linked-lists"><span clas
 <p>Thus, if we have used a doubly linked list, we can use the <code>insertBefore()</code> method to store the pointer to the input node in the <code>prev</code> attribute. This would put the input node as the “previous node”, or, the node before the current node. In contrast, the <code>insertAfter()</code> method puts the pointer created to the input node in the <code>next</code> attribute of the current node, and as result, the input node becomes the “next node” of the current node.</p>
 <p>Since we are using a singly linked list in this example, we have only the <code>insertAfter()</code> method available in the node objects that we create from our <code>Lu32</code> type.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb21"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb21-1"><a href="#cb21-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb21-2"><a href="#cb21-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> SinglyLinkedList = std.SinglyLinkedList;</span>
-<span id="cb21-3"><a href="#cb21-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Lu32 = SinglyLinkedList(<span class="dt">u32</span>);</span>
-<span id="cb21-4"><a href="#cb21-4" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb21-5"><a href="#cb21-5" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb21-6"><a href="#cb21-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> list = Lu32<span class="op">{}</span>;</span>
-<span id="cb21-7"><a href="#cb21-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> one = Lu32.Node<span class="op">{</span> .data = <span class="dv">1</span> <span class="op">}</span>;</span>
-<span id="cb21-8"><a href="#cb21-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> two = Lu32.Node<span class="op">{</span> .data = <span class="dv">2</span> <span class="op">}</span>;</span>
-<span id="cb21-9"><a href="#cb21-9" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> three = Lu32.Node<span class="op">{</span> .data = <span class="dv">3</span> <span class="op">}</span>;</span>
-<span id="cb21-10"><a href="#cb21-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> four = Lu32.Node<span class="op">{</span> .data = <span class="dv">4</span> <span class="op">}</span>;</span>
-<span id="cb21-11"><a href="#cb21-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> five = Lu32.Node<span class="op">{</span> .data = <span class="dv">5</span> <span class="op">}</span>;</span>
-<span id="cb21-12"><a href="#cb21-12" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb21-13"><a href="#cb21-13" aria-hidden="true" tabindex="-1"></a>    list.prepend(&amp;two); <span class="co">// {2}</span></span>
-<span id="cb21-14"><a href="#cb21-14" aria-hidden="true" tabindex="-1"></a>    two.insertAfter(&amp;five); <span class="co">// {2, 5}</span></span>
-<span id="cb21-15"><a href="#cb21-15" aria-hidden="true" tabindex="-1"></a>    list.prepend(&amp;one); <span class="co">// {1, 2, 5}</span></span>
-<span id="cb21-16"><a href="#cb21-16" aria-hidden="true" tabindex="-1"></a>    two.insertAfter(&amp;three); <span class="co">// {1, 2, 3, 5}</span></span>
-<span id="cb21-17"><a href="#cb21-17" aria-hidden="true" tabindex="-1"></a>    three.insertAfter(&amp;four); <span class="co">// {1, 2, 3, 4, 5}</span></span>
-<span id="cb21-18"><a href="#cb21-18" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb20"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb20-1"><a href="#cb20-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb20-2"><a href="#cb20-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> SinglyLinkedList = std.SinglyLinkedList;</span>
+<span id="cb20-3"><a href="#cb20-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Lu32 = SinglyLinkedList(<span class="dt">u32</span>);</span>
+<span id="cb20-4"><a href="#cb20-4" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb20-5"><a href="#cb20-5" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb20-6"><a href="#cb20-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> list = Lu32<span class="op">{}</span>;</span>
+<span id="cb20-7"><a href="#cb20-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> one = Lu32.Node<span class="op">{</span> .data = <span class="dv">1</span> <span class="op">}</span>;</span>
+<span id="cb20-8"><a href="#cb20-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> two = Lu32.Node<span class="op">{</span> .data = <span class="dv">2</span> <span class="op">}</span>;</span>
+<span id="cb20-9"><a href="#cb20-9" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> three = Lu32.Node<span class="op">{</span> .data = <span class="dv">3</span> <span class="op">}</span>;</span>
+<span id="cb20-10"><a href="#cb20-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> four = Lu32.Node<span class="op">{</span> .data = <span class="dv">4</span> <span class="op">}</span>;</span>
+<span id="cb20-11"><a href="#cb20-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> five = Lu32.Node<span class="op">{</span> .data = <span class="dv">5</span> <span class="op">}</span>;</span>
+<span id="cb20-12"><a href="#cb20-12" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb20-13"><a href="#cb20-13" aria-hidden="true" tabindex="-1"></a>    list.prepend(&amp;two); <span class="co">// {2}</span></span>
+<span id="cb20-14"><a href="#cb20-14" aria-hidden="true" tabindex="-1"></a>    two.insertAfter(&amp;five); <span class="co">// {2, 5}</span></span>
+<span id="cb20-15"><a href="#cb20-15" aria-hidden="true" tabindex="-1"></a>    list.prepend(&amp;one); <span class="co">// {1, 2, 5}</span></span>
+<span id="cb20-16"><a href="#cb20-16" aria-hidden="true" tabindex="-1"></a>    two.insertAfter(&amp;three); <span class="co">// {1, 2, 3, 5}</span></span>
+<span id="cb20-17"><a href="#cb20-17" aria-hidden="true" tabindex="-1"></a>    three.insertAfter(&amp;four); <span class="co">// {1, 2, 3, 4, 5}</span></span>
+<span id="cb20-18"><a href="#cb20-18" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>There are other methods available from the linked list object, depending if this object is a singly linked list or a doubly linked list, that might be very useful for you. You can find a summary of them in the bullet points below:</p>
 <ul>
@@ -760,30 +756,30 @@ <h2 data-number="11.4" class="anchored" data-anchor-id="multi-array-structure"><
 <p>Zig introduces a new data structure called <code>MultiArrayList()</code>. It is a different version of the dynamic array that we have introduced at <a href="#sec-dynamic-array" class="quarto-xref"><span>Section 11.1</span></a>. The difference between this structure and the <code>ArrayList()</code> that we know from <a href="#sec-dynamic-array" class="quarto-xref"><span>Section 11.1</span></a>, is that <code>MultiArrayList()</code> creates a separate dynamic array for each field of the struct that you provide as input.</p>
 <p>Consider the following code example. We create a new custom struct called <code>Person</code>. This struct contains three different data members, or, three different fields. As consequence, when we provide this <code>Person</code> data type as input to <code>MultiArrayList()</code>, this creates a “struct of three different arrays” called <code>PersonArray</code>. In other words, this <code>PersonArray</code> is a struct that contains three internal dynamic arrays in it. One array for each field found in the <code>Person</code> struct definition.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb22"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb22-1"><a href="#cb22-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb22-2"><a href="#cb22-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Person = <span class="kw">struct</span> <span class="op">{</span></span>
-<span id="cb22-3"><a href="#cb22-3" aria-hidden="true" tabindex="-1"></a>    name: []<span class="kw">const</span> <span class="dt">u8</span>,</span>
-<span id="cb22-4"><a href="#cb22-4" aria-hidden="true" tabindex="-1"></a>    age: <span class="dt">u8</span>,</span>
-<span id="cb22-5"><a href="#cb22-5" aria-hidden="true" tabindex="-1"></a>    height: <span class="dt">f32</span>,</span>
-<span id="cb22-6"><a href="#cb22-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
-<span id="cb22-7"><a href="#cb22-7" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> PersonArray = std.MultiArrayList(Person);</span>
-<span id="cb22-8"><a href="#cb22-8" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb22-9"><a href="#cb22-9" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb22-10"><a href="#cb22-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> gpa = std.heap.GeneralPurposeAllocator(.<span class="op">{}</span>)<span class="op">{}</span>;</span>
-<span id="cb22-11"><a href="#cb22-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> allocator = gpa.allocator();</span>
-<span id="cb22-12"><a href="#cb22-12" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> people = PersonArray<span class="op">{}</span>;</span>
-<span id="cb22-13"><a href="#cb22-13" aria-hidden="true" tabindex="-1"></a>    <span class="kw">defer</span> people.deinit(allocator);</span>
-<span id="cb22-14"><a href="#cb22-14" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb22-15"><a href="#cb22-15" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
-<span id="cb22-16"><a href="#cb22-16" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Auguste"</span>, .age = <span class="dv">15</span>, .height = <span class="fl">1.54</span></span>
-<span id="cb22-17"><a href="#cb22-17" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
-<span id="cb22-18"><a href="#cb22-18" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
-<span id="cb22-19"><a href="#cb22-19" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Elena"</span>, .age = <span class="dv">26</span>, .height = <span class="fl">1.65</span></span>
-<span id="cb22-20"><a href="#cb22-20" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
-<span id="cb22-21"><a href="#cb22-21" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
-<span id="cb22-22"><a href="#cb22-22" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Michael"</span>, .age = <span class="dv">64</span>, .height = <span class="fl">1.87</span></span>
-<span id="cb22-23"><a href="#cb22-23" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
-<span id="cb22-24"><a href="#cb22-24" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb21"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb21-1"><a href="#cb21-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb21-2"><a href="#cb21-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Person = <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb21-3"><a href="#cb21-3" aria-hidden="true" tabindex="-1"></a>    name: []<span class="kw">const</span> <span class="dt">u8</span>,</span>
+<span id="cb21-4"><a href="#cb21-4" aria-hidden="true" tabindex="-1"></a>    age: <span class="dt">u8</span>,</span>
+<span id="cb21-5"><a href="#cb21-5" aria-hidden="true" tabindex="-1"></a>    height: <span class="dt">f32</span>,</span>
+<span id="cb21-6"><a href="#cb21-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
+<span id="cb21-7"><a href="#cb21-7" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> PersonArray = std.MultiArrayList(Person);</span>
+<span id="cb21-8"><a href="#cb21-8" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb21-9"><a href="#cb21-9" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb21-10"><a href="#cb21-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> gpa = std.heap.GeneralPurposeAllocator(.<span class="op">{}</span>)<span class="op">{}</span>;</span>
+<span id="cb21-11"><a href="#cb21-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> allocator = gpa.allocator();</span>
+<span id="cb21-12"><a href="#cb21-12" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> people = PersonArray<span class="op">{}</span>;</span>
+<span id="cb21-13"><a href="#cb21-13" aria-hidden="true" tabindex="-1"></a>    <span class="kw">defer</span> people.deinit(allocator);</span>
+<span id="cb21-14"><a href="#cb21-14" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb21-15"><a href="#cb21-15" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
+<span id="cb21-16"><a href="#cb21-16" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Auguste"</span>, .age = <span class="dv">15</span>, .height = <span class="fl">1.54</span></span>
+<span id="cb21-17"><a href="#cb21-17" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
+<span id="cb21-18"><a href="#cb21-18" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
+<span id="cb21-19"><a href="#cb21-19" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Elena"</span>, .age = <span class="dv">26</span>, .height = <span class="fl">1.65</span></span>
+<span id="cb21-20"><a href="#cb21-20" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
+<span id="cb21-21"><a href="#cb21-21" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
+<span id="cb21-22"><a href="#cb21-22" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Michael"</span>, .age = <span class="dv">64</span>, .height = <span class="fl">1.87</span></span>
+<span id="cb21-23"><a href="#cb21-23" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
+<span id="cb21-24"><a href="#cb21-24" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>In other words, instead of creating an array of “persons”, the <code>MultiArrayList()</code> function creates a “struct of arrays”. Each data member of this struct is a different array that stores the values of a specific field from the <code>Person</code> values that were added (or, appended) to this “struct of arrays”. One important detail is that each of these separate internal arrays stored inside <code>PersonArray</code> are dynamic arrays. This means that these arrays can grow in capacity automatically as needed, to accomodate more values.</p>
 <p>The <a href="#fig-multi-array" class="quarto-xref">Figure&nbsp;<span>11.5</span></a> exposed below presents a diagram that describes the <code>PersonArray</code> struct that we have created in the previous code example. Notice that the values of the data members present in each of the three <code>Person</code> values that we have appended into the <code>PersonArray</code> object , are scattered across three different internal arrays of the <code>PersonArray</code> object.</p>
@@ -799,9 +795,9 @@ <h2 data-number="11.4" class="anchored" data-anchor-id="multi-array-structure"><
 </div>
 <p>You can easily access each of these arrays separately, and iterate over the values of each array. For that, you will need to call the <code>items()</code> method from the <code>PersonArray</code> object, and provide as input to this method, the name of the field that you want to iterate over. If you want to iterate through the <code>.age</code> array for example, then, you need to call <code>items(.age)</code> from the <code>PersonArray</code> object, like in the example below:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb23"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb23-1"><a href="#cb23-1" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (people.items(.age)) |*age| <span class="op">{</span></span>
-<span id="cb23-2"><a href="#cb23-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"Age: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>age.*<span class="op">}</span>);</span>
-<span id="cb23-3"><a href="#cb23-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb22"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb22-1"><a href="#cb22-1" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (people.items(.age)) |*age| <span class="op">{</span></span>
+<span id="cb22-2"><a href="#cb22-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"Age: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>age.*<span class="op">}</span>);</span>
+<span id="cb22-3"><a href="#cb22-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Age: 15
 Age: 26
@@ -810,15 +806,15 @@ <h2 data-number="11.4" class="anchored" data-anchor-id="multi-array-structure"><
 <p>In this example we are calling the <code>items()</code> method directly from the <code>PersonArray</code> object. However, it is recommended on most situations to call this <code>items()</code> method from a “slice object”, which you can create from the <code>slice()</code> method. The reason for this is that calling <code>items()</code> multiple times have better performance if you use a slice object.</p>
 <p>Therefore, if you are planning to access only one of the internal arrays from your “multi array struct”, it is fine to call <code>items()</code> directly from the multi array object. But if you need to access many of the internal arrays from your “multi array struct”, then, you will likely need to call <code>items()</code> more than once, and, in such circumstance, is better to call <code>items()</code> through a slice object. The example below demonstrates the use of such object:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb25"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb25-1"><a href="#cb25-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> slice = people.slice();</span>
-<span id="cb25-2"><a href="#cb25-2" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (slice.items(.age)) |*age| <span class="op">{</span></span>
-<span id="cb25-3"><a href="#cb25-3" aria-hidden="true" tabindex="-1"></a>    age.* += <span class="dv">10</span>;</span>
-<span id="cb25-4"><a href="#cb25-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
-<span id="cb25-5"><a href="#cb25-5" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (slice.items(.name), slice.items(.age)) |*n,*a| <span class="op">{</span></span>
-<span id="cb25-6"><a href="#cb25-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(</span>
-<span id="cb25-7"><a href="#cb25-7" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Name: {s}, Age: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>n.*, a.*<span class="op">}</span></span>
-<span id="cb25-8"><a href="#cb25-8" aria-hidden="true" tabindex="-1"></a>    );</span>
-<span id="cb25-9"><a href="#cb25-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb24"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb24-1"><a href="#cb24-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> slice = people.slice();</span>
+<span id="cb24-2"><a href="#cb24-2" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (slice.items(.age)) |*age| <span class="op">{</span></span>
+<span id="cb24-3"><a href="#cb24-3" aria-hidden="true" tabindex="-1"></a>    age.* += <span class="dv">10</span>;</span>
+<span id="cb24-4"><a href="#cb24-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
+<span id="cb24-5"><a href="#cb24-5" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (slice.items(.name), slice.items(.age)) |*n,*a| <span class="op">{</span></span>
+<span id="cb24-6"><a href="#cb24-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(</span>
+<span id="cb24-7"><a href="#cb24-7" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Name: {s}, Age: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>n.*, a.*<span class="op">}</span></span>
+<span id="cb24-8"><a href="#cb24-8" aria-hidden="true" tabindex="-1"></a>    );</span>
+<span id="cb24-9"><a href="#cb24-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Name: Auguste, Age: 25
 Name: Elena, Age: 36
diff --git a/docs/Chapters/10-stack-project.html b/docs/Chapters/10-stack-project.html
index b19573e2..b81ac050 100644
--- a/docs/Chapters/10-stack-project.html
+++ b/docs/Chapters/10-stack-project.html
@@ -370,7 +370,7 @@ <h3 data-number="12.1.1" class="anchored" data-anchor-id="applying-over-a-functi
 <span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a>    _ = twice(<span class="dv">5678</span>);</span>
 <span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file1054863994c6f.test.test comptime...OKAll 1
+<pre><code>1/1 file1105a40478a9d.test.test comptime...OKAll 1
   1 tests passed.</code></pre>
 </div>
 </div>
@@ -426,8 +426,8 @@ <h3 data-number="12.1.2" class="anchored" data-anchor-id="applying-over-an-expre
 <span id="cb6-11"><a href="#cb6-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> <span class="kw">comptime</span> expect(fibonacci(<span class="dv">7</span>) == <span class="dv">13</span>);</span>
 <span id="cb6-12"><a href="#cb6-12" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file10548bb87337.test.fibonacci...OKAll 1 test
-  ts passed.</code></pre>
+<pre><code>1/1 file1105a31c0f24f.test.fibonacci...OKAll 1 tes
+  sts passed.</code></pre>
 </div>
 </div>
 <p>A lot of your Zig source code might be potentially executed at compile-time, because the <code>zig</code> compiler can figure it out the output of some expressions. Especially if these expressions depends only at compile-time known values. We have talked about this at <a href="01-memory.html#sec-compile-time" class="quarto-xref"><span>Section 3.1.1</span></a>.</p>
@@ -455,7 +455,7 @@ <h3 data-number="12.1.3" class="anchored" data-anchor-id="applying-over-a-block"
 <span id="cb8-15"><a href="#cb8-15" aria-hidden="true" tabindex="-1"></a>    _ = x;</span>
 <span id="cb8-16"><a href="#cb8-16" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file105482dc0b880.test.fibonacci in a block...
+<pre><code>1/1 file1105a37ca2b0d.test.fibonacci in a block...
   .OKAll 1 tests passed.</code></pre>
 </div>
 </div>
@@ -475,27 +475,20 @@ <h3 data-number="12.2.1" class="anchored" data-anchor-id="sec-generic-fun"><span
 <div class="sourceCode cell-code" id="cb10"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> max(<span class="kw">comptime</span> T: <span class="dt">type</span>, a: T, b: T) T <span class="op">{</span></span>
 <span id="cb10-2"><a href="#cb10-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> <span class="kw">if</span> (a &gt; b) a <span class="kw">else</span> b;</span>
 <span id="cb10-3"><a href="#cb10-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
-<div class="cell-output cell-output-stdout">
-<pre><code>All 0 tests passed.</code></pre>
-</div>
 </div>
 <p>Also notice that the value of the <code>T</code> argument is actually used to define the data type of the other arguments in the function, <code>a</code> and <code>b</code>, and also at the return type annotation of the function. That is, the data type of these arguments (<code>a</code> and <code>b</code>), and, the return data type of the function itself, are determined by the input value given to the <code>T</code> argument.</p>
 <p>As a result, we have a generic function that works with different data types. For example, I can provide <code>u8</code> values to this <code>max()</code> function, and it will work as expected. But if I provide <code>f64</code> values instead, it will also work as expected. Without a generic function, I would have to write a different <code>max()</code> function for each one of the data types that I wanted to use. This generic function provides a very useful shortcut for us.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb12"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb12-2"><a href="#cb12-2" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> max(<span class="kw">comptime</span> T: <span class="dt">type</span>, a: T, b: T) T <span class="op">{</span></span>
-<span id="cb12-3"><a href="#cb12-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> <span class="kw">if</span> (a &gt; b) a <span class="kw">else</span> b;</span>
-<span id="cb12-4"><a href="#cb12-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
-<span id="cb12-5"><a href="#cb12-5" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="st">"test max"</span> <span class="op">{</span></span>
-<span id="cb12-6"><a href="#cb12-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> n1 = max(<span class="dt">u8</span>, <span class="dv">4</span>, <span class="dv">10</span>);</span>
-<span id="cb12-7"><a href="#cb12-7" aria-hidden="true" tabindex="-1"></a>    std.debug.print(<span class="st">"Max n1: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>n1<span class="op">}</span>);</span>
-<span id="cb12-8"><a href="#cb12-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> n2 = max(<span class="dt">f64</span>, <span class="fl">89.24</span>, <span class="fl">64.001</span>);</span>
-<span id="cb12-9"><a href="#cb12-9" aria-hidden="true" tabindex="-1"></a>    std.debug.print(<span class="st">"Max n2: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>n2<span class="op">}</span>);</span>
-<span id="cb12-10"><a href="#cb12-10" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
-<div class="cell-output cell-output-stdout">
-<pre><code>1/1 file105482071daf3.test.test max...Max n1: 10Ma
-  ax n2: 89.24OKAll 1 tests passed.</code></pre>
-</div>
+<div class="sourceCode cell-code" id="cb11"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb11-2"><a href="#cb11-2" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> max(<span class="kw">comptime</span> T: <span class="dt">type</span>, a: T, b: T) T <span class="op">{</span></span>
+<span id="cb11-3"><a href="#cb11-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> <span class="kw">if</span> (a &gt; b) a <span class="kw">else</span> b;</span>
+<span id="cb11-4"><a href="#cb11-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
+<span id="cb11-5"><a href="#cb11-5" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="st">"test max"</span> <span class="op">{</span></span>
+<span id="cb11-6"><a href="#cb11-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> n1 = max(<span class="dt">u8</span>, <span class="dv">4</span>, <span class="dv">10</span>);</span>
+<span id="cb11-7"><a href="#cb11-7" aria-hidden="true" tabindex="-1"></a>    std.debug.print(<span class="st">"Max n1: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>n1<span class="op">}</span>);</span>
+<span id="cb11-8"><a href="#cb11-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> n2 = max(<span class="dt">f64</span>, <span class="fl">89.24</span>, <span class="fl">64.001</span>);</span>
+<span id="cb11-9"><a href="#cb11-9" aria-hidden="true" tabindex="-1"></a>    std.debug.print(<span class="st">"Max n2: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>n2<span class="op">}</span>);</span>
+<span id="cb11-10"><a href="#cb11-10" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Max n1: 10
 Max n2: 89.24</code></pre>
@@ -533,24 +526,24 @@ <h2 data-number="12.4" class="anchored" data-anchor-id="writing-the-stack-data-s
 <p>Also notice in our <code>Stack</code> struct that we have three other data members: <code>capacity</code>, <code>length</code> and <code>allocator</code>. The <code>capacity</code> member contains the capacity of the underlying array that stores the values in the stack. The <code>length</code> contains the number of values that are currently being stored in the stack. And the <code>allocator</code> contains the allocator object that will be used by the stack structure whenever it needs to allocate more space for the values that are being stored.</p>
 <p>We begin by defining an <code>init()</code> method of this struct, which is going to be responsible for instantiating a <code>Stack</code> object. Notice that, inside this <code>init()</code> method, we start by allocating an array with the capacity specified in the <code>capacity</code> argument.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb15"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb15-1"><a href="#cb15-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb15-2"><a href="#cb15-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Allocator = std.mem.Allocator;</span>
-<span id="cb15-3"><a href="#cb15-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Stack = <span class="kw">struct</span> <span class="op">{</span></span>
-<span id="cb15-4"><a href="#cb15-4" aria-hidden="true" tabindex="-1"></a>    items: []<span class="dt">u32</span>,</span>
-<span id="cb15-5"><a href="#cb15-5" aria-hidden="true" tabindex="-1"></a>    capacity: <span class="dt">usize</span>,</span>
-<span id="cb15-6"><a href="#cb15-6" aria-hidden="true" tabindex="-1"></a>    length: <span class="dt">usize</span>,</span>
-<span id="cb15-7"><a href="#cb15-7" aria-hidden="true" tabindex="-1"></a>    allocator: Allocator,</span>
-<span id="cb15-8"><a href="#cb15-8" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb15-9"><a href="#cb15-9" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> init(allocator: Allocator, capacity: <span class="dt">usize</span>) !Stack <span class="op">{</span></span>
-<span id="cb15-10"><a href="#cb15-10" aria-hidden="true" tabindex="-1"></a>        <span class="kw">var</span> buf = <span class="kw">try</span> allocator.alloc(<span class="dt">u32</span>, capacity);</span>
-<span id="cb15-11"><a href="#cb15-11" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> .<span class="op">{</span></span>
-<span id="cb15-12"><a href="#cb15-12" aria-hidden="true" tabindex="-1"></a>            .items = buf[<span class="dv">0</span>..],</span>
-<span id="cb15-13"><a href="#cb15-13" aria-hidden="true" tabindex="-1"></a>            .capacity = capacity,</span>
-<span id="cb15-14"><a href="#cb15-14" aria-hidden="true" tabindex="-1"></a>            .length = <span class="dv">0</span>,</span>
-<span id="cb15-15"><a href="#cb15-15" aria-hidden="true" tabindex="-1"></a>            .allocator = allocator,</span>
-<span id="cb15-16"><a href="#cb15-16" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span>;</span>
-<span id="cb15-17"><a href="#cb15-17" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb15-18"><a href="#cb15-18" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb13"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb13-2"><a href="#cb13-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Allocator = std.mem.Allocator;</span>
+<span id="cb13-3"><a href="#cb13-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Stack = <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb13-4"><a href="#cb13-4" aria-hidden="true" tabindex="-1"></a>    items: []<span class="dt">u32</span>,</span>
+<span id="cb13-5"><a href="#cb13-5" aria-hidden="true" tabindex="-1"></a>    capacity: <span class="dt">usize</span>,</span>
+<span id="cb13-6"><a href="#cb13-6" aria-hidden="true" tabindex="-1"></a>    length: <span class="dt">usize</span>,</span>
+<span id="cb13-7"><a href="#cb13-7" aria-hidden="true" tabindex="-1"></a>    allocator: Allocator,</span>
+<span id="cb13-8"><a href="#cb13-8" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb13-9"><a href="#cb13-9" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> init(allocator: Allocator, capacity: <span class="dt">usize</span>) !Stack <span class="op">{</span></span>
+<span id="cb13-10"><a href="#cb13-10" aria-hidden="true" tabindex="-1"></a>        <span class="kw">var</span> buf = <span class="kw">try</span> allocator.alloc(<span class="dt">u32</span>, capacity);</span>
+<span id="cb13-11"><a href="#cb13-11" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> .<span class="op">{</span></span>
+<span id="cb13-12"><a href="#cb13-12" aria-hidden="true" tabindex="-1"></a>            .items = buf[<span class="dv">0</span>..],</span>
+<span id="cb13-13"><a href="#cb13-13" aria-hidden="true" tabindex="-1"></a>            .capacity = capacity,</span>
+<span id="cb13-14"><a href="#cb13-14" aria-hidden="true" tabindex="-1"></a>            .length = <span class="dv">0</span>,</span>
+<span id="cb13-15"><a href="#cb13-15" aria-hidden="true" tabindex="-1"></a>            .allocator = allocator,</span>
+<span id="cb13-16"><a href="#cb13-16" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span>;</span>
+<span id="cb13-17"><a href="#cb13-17" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb13-18"><a href="#cb13-18" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <section id="implementing-the-push-operation" class="level3" data-number="12.4.1">
 <h3 data-number="12.4.1" class="anchored" data-anchor-id="implementing-the-push-operation"><span class="header-section-number">12.4.1</span> Implementing the <code>push</code> operation</h3>
@@ -562,22 +555,22 @@ <h3 data-number="12.4.1" class="anchored" data-anchor-id="implementing-the-push-
 <p>We are using this <code>@memcpy()</code> built-in function to copy the values that are currently stored in the underlying array of the stack object (<code>self.items</code>) into our new and bigger array that we have allocated (<code>new_buf</code>). After we execute this function, the <code>new_buf</code> contains a copy of the values that are present at <code>self.items</code>.</p>
 <p>Now that we have secured a copy of our current values in the <code>new_buf</code> object, we can now free the memory currently allocated at <code>self.items</code>. After that, we just need to assign our new and bigger array to <code>self.items</code>. This is the sequence of steps necessary to expand our array.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb16"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> push(self: *Stack, val: <span class="dt">u32</span>) !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb16-2"><a href="#cb16-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> ((self.length + <span class="dv">1</span>) &gt; self.capacity) <span class="op">{</span></span>
-<span id="cb16-3"><a href="#cb16-3" aria-hidden="true" tabindex="-1"></a>        <span class="kw">var</span> new_buf = <span class="kw">try</span> self.allocator.alloc(</span>
-<span id="cb16-4"><a href="#cb16-4" aria-hidden="true" tabindex="-1"></a>            <span class="dt">u32</span>, self.capacity * <span class="dv">2</span></span>
-<span id="cb16-5"><a href="#cb16-5" aria-hidden="true" tabindex="-1"></a>        );</span>
-<span id="cb16-6"><a href="#cb16-6" aria-hidden="true" tabindex="-1"></a>        <span class="bu">@memcpy</span>(</span>
-<span id="cb16-7"><a href="#cb16-7" aria-hidden="true" tabindex="-1"></a>            new_buf[<span class="dv">0</span>..self.capacity], self.items</span>
-<span id="cb16-8"><a href="#cb16-8" aria-hidden="true" tabindex="-1"></a>        );</span>
-<span id="cb16-9"><a href="#cb16-9" aria-hidden="true" tabindex="-1"></a>        self.allocator.free(self.items);</span>
-<span id="cb16-10"><a href="#cb16-10" aria-hidden="true" tabindex="-1"></a>        self.items = new_buf;</span>
-<span id="cb16-11"><a href="#cb16-11" aria-hidden="true" tabindex="-1"></a>        self.capacity = self.capacity * <span class="dv">2</span>;</span>
-<span id="cb16-12"><a href="#cb16-12" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb16-13"><a href="#cb16-13" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb16-14"><a href="#cb16-14" aria-hidden="true" tabindex="-1"></a>    self.items[self.length] = val;</span>
-<span id="cb16-15"><a href="#cb16-15" aria-hidden="true" tabindex="-1"></a>    self.length += <span class="dv">1</span>;</span>
-<span id="cb16-16"><a href="#cb16-16" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb14"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> push(self: *Stack, val: <span class="dt">u32</span>) !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb14-2"><a href="#cb14-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> ((self.length + <span class="dv">1</span>) &gt; self.capacity) <span class="op">{</span></span>
+<span id="cb14-3"><a href="#cb14-3" aria-hidden="true" tabindex="-1"></a>        <span class="kw">var</span> new_buf = <span class="kw">try</span> self.allocator.alloc(</span>
+<span id="cb14-4"><a href="#cb14-4" aria-hidden="true" tabindex="-1"></a>            <span class="dt">u32</span>, self.capacity * <span class="dv">2</span></span>
+<span id="cb14-5"><a href="#cb14-5" aria-hidden="true" tabindex="-1"></a>        );</span>
+<span id="cb14-6"><a href="#cb14-6" aria-hidden="true" tabindex="-1"></a>        <span class="bu">@memcpy</span>(</span>
+<span id="cb14-7"><a href="#cb14-7" aria-hidden="true" tabindex="-1"></a>            new_buf[<span class="dv">0</span>..self.capacity], self.items</span>
+<span id="cb14-8"><a href="#cb14-8" aria-hidden="true" tabindex="-1"></a>        );</span>
+<span id="cb14-9"><a href="#cb14-9" aria-hidden="true" tabindex="-1"></a>        self.allocator.free(self.items);</span>
+<span id="cb14-10"><a href="#cb14-10" aria-hidden="true" tabindex="-1"></a>        self.items = new_buf;</span>
+<span id="cb14-11"><a href="#cb14-11" aria-hidden="true" tabindex="-1"></a>        self.capacity = self.capacity * <span class="dv">2</span>;</span>
+<span id="cb14-12"><a href="#cb14-12" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb14-13"><a href="#cb14-13" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb14-14"><a href="#cb14-14" aria-hidden="true" tabindex="-1"></a>    self.items[self.length] = val;</span>
+<span id="cb14-15"><a href="#cb14-15" aria-hidden="true" tabindex="-1"></a>    self.length += <span class="dv">1</span>;</span>
+<span id="cb14-16"><a href="#cb14-16" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>After we make sure that we have enough room to store this new value that we are adding to the stack, all we have to do is to assign this value to the top element in this stack, and, increase the value of the <code>length</code> attribute by one. We find the top element in the stack by using the <code>length</code> attribute.</p>
 </section>
@@ -587,12 +580,12 @@ <h3 data-number="12.4.2" class="anchored" data-anchor-id="implementing-the-pop-o
 <p>We just have to find the element in the underlying array that currently represents the top of the stack, and set this element to “undefined”, to indicate that this element is “empty”. After that, we also need to decrease the <code>length</code> attribute of the stack by one.</p>
 <p>If the current length of the stack is zero, it means that there is no values being stored in the stack currently. So, in this case, we could just return from the function and do nothing really. This is what the if statement inside this function is checking for.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb17"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> pop(self: *Stack) <span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb17-2"><a href="#cb17-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> (self.length == <span class="dv">0</span>) <span class="kw">return</span>;</span>
-<span id="cb17-3"><a href="#cb17-3" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb17-4"><a href="#cb17-4" aria-hidden="true" tabindex="-1"></a>    self.items[self.length - <span class="dv">1</span>] = <span class="cn">undefined</span>;</span>
-<span id="cb17-5"><a href="#cb17-5" aria-hidden="true" tabindex="-1"></a>    self.length -= <span class="dv">1</span>;</span>
-<span id="cb17-6"><a href="#cb17-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb15"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb15-1"><a href="#cb15-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> pop(self: *Stack) <span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb15-2"><a href="#cb15-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> (self.length == <span class="dv">0</span>) <span class="kw">return</span>;</span>
+<span id="cb15-3"><a href="#cb15-3" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb15-4"><a href="#cb15-4" aria-hidden="true" tabindex="-1"></a>    self.items[self.length - <span class="dv">1</span>] = <span class="cn">undefined</span>;</span>
+<span id="cb15-5"><a href="#cb15-5" aria-hidden="true" tabindex="-1"></a>    self.length -= <span class="dv">1</span>;</span>
+<span id="cb15-6"><a href="#cb15-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
 <section id="implementing-the-deinit-method" class="level3" data-number="12.4.3">
@@ -601,9 +594,9 @@ <h3 data-number="12.4.3" class="anchored" data-anchor-id="implementing-the-deini
 <p>But now, we need to implement also the method responsible for destroying a <code>Stack</code> object. In Zig, this task is commonly associated with the method named <code>deinit()</code>. Most struct objects in Zig have such method, and it is commonly nicknamed “the destructor method”.</p>
 <p>In theory, all we have to do to destroy the <code>Stack</code> object is to make sure that we free the allocated memory for the underlying array, using the allocator object that is stored inside the <code>Stack</code> object. This is what the <code>deinit()</code> method below is doing.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb18"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb18-1"><a href="#cb18-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> deinit(self: *Stack) <span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb18-2"><a href="#cb18-2" aria-hidden="true" tabindex="-1"></a>    self.allocator.free(self.items);</span>
-<span id="cb18-3"><a href="#cb18-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb16"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> deinit(self: *Stack) <span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb16-2"><a href="#cb16-2" aria-hidden="true" tabindex="-1"></a>    self.allocator.free(self.items);</span>
+<span id="cb16-3"><a href="#cb16-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
 </section>
@@ -615,56 +608,56 @@ <h2 data-number="12.5" class="anchored" data-anchor-id="making-it-generic"><span
 <p>We do that by using a generic function. Because a generic function can receive a data type as input, and we can pass this data type to the struct definition of our <code>Stack</code> object. Therefore, we can use the generic function to create a <code>Stack</code> object that can store the data type we want. If we want to create a stack structure that stores <code>User</code> values, we pass the <code>User</code> data type to this generic function, and it will create for us the struct definition that describes a <code>Stack</code> object that can store <code>User</code> values in it.</p>
 <p>Look at the code example below. I have omitted some parts of the <code>Stack</code> struct definition for brevity reasons. However, if a specific part of our <code>Stack</code> struct is not exposed here in this example, then it is because this part did not change from the previous example. It remains the same.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb19"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb19-1"><a href="#cb19-1" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> Stack(<span class="kw">comptime</span> T: <span class="dt">type</span>) <span class="dt">type</span> <span class="op">{</span></span>
-<span id="cb19-2"><a href="#cb19-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> <span class="kw">struct</span> <span class="op">{</span></span>
-<span id="cb19-3"><a href="#cb19-3" aria-hidden="true" tabindex="-1"></a>        items: []T,</span>
-<span id="cb19-4"><a href="#cb19-4" aria-hidden="true" tabindex="-1"></a>        capacity: <span class="dt">usize</span>,</span>
-<span id="cb19-5"><a href="#cb19-5" aria-hidden="true" tabindex="-1"></a>        length: <span class="dt">usize</span>,</span>
-<span id="cb19-6"><a href="#cb19-6" aria-hidden="true" tabindex="-1"></a>        allocator: Allocator,</span>
-<span id="cb19-7"><a href="#cb19-7" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> Self = <span class="bu">@This</span>();</span>
-<span id="cb19-8"><a href="#cb19-8" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb19-9"><a href="#cb19-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">pub</span> <span class="kw">fn</span> init(allocator: Allocator,</span>
-<span id="cb19-10"><a href="#cb19-10" aria-hidden="true" tabindex="-1"></a>                    capacity: <span class="dt">usize</span>) !Stack(T) <span class="op">{</span></span>
-<span id="cb19-11"><a href="#cb19-11" aria-hidden="true" tabindex="-1"></a>            <span class="kw">var</span> buf = <span class="kw">try</span> allocator.alloc(T, capacity);</span>
-<span id="cb19-12"><a href="#cb19-12" aria-hidden="true" tabindex="-1"></a>            <span class="kw">return</span> .<span class="op">{</span></span>
-<span id="cb19-13"><a href="#cb19-13" aria-hidden="true" tabindex="-1"></a>                .items = buf[<span class="dv">0</span>..],</span>
-<span id="cb19-14"><a href="#cb19-14" aria-hidden="true" tabindex="-1"></a>                .capacity = capacity,</span>
-<span id="cb19-15"><a href="#cb19-15" aria-hidden="true" tabindex="-1"></a>                .length = <span class="dv">0</span>,</span>
-<span id="cb19-16"><a href="#cb19-16" aria-hidden="true" tabindex="-1"></a>                .allocator = allocator,</span>
-<span id="cb19-17"><a href="#cb19-17" aria-hidden="true" tabindex="-1"></a>            <span class="op">}</span>;</span>
-<span id="cb19-18"><a href="#cb19-18" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span></span>
-<span id="cb19-19"><a href="#cb19-19" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb19-20"><a href="#cb19-20" aria-hidden="true" tabindex="-1"></a>        <span class="kw">pub</span> <span class="kw">fn</span> push(self: *Self, val: T) !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb19-21"><a href="#cb19-21" aria-hidden="true" tabindex="-1"></a>        <span class="co">// Truncate the rest of the struct</span></span>
-<span id="cb19-22"><a href="#cb19-22" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>;</span>
-<span id="cb19-23"><a href="#cb19-23" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb17"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> Stack(<span class="kw">comptime</span> T: <span class="dt">type</span>) <span class="dt">type</span> <span class="op">{</span></span>
+<span id="cb17-2"><a href="#cb17-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb17-3"><a href="#cb17-3" aria-hidden="true" tabindex="-1"></a>        items: []T,</span>
+<span id="cb17-4"><a href="#cb17-4" aria-hidden="true" tabindex="-1"></a>        capacity: <span class="dt">usize</span>,</span>
+<span id="cb17-5"><a href="#cb17-5" aria-hidden="true" tabindex="-1"></a>        length: <span class="dt">usize</span>,</span>
+<span id="cb17-6"><a href="#cb17-6" aria-hidden="true" tabindex="-1"></a>        allocator: Allocator,</span>
+<span id="cb17-7"><a href="#cb17-7" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> Self = <span class="bu">@This</span>();</span>
+<span id="cb17-8"><a href="#cb17-8" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb17-9"><a href="#cb17-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">pub</span> <span class="kw">fn</span> init(allocator: Allocator,</span>
+<span id="cb17-10"><a href="#cb17-10" aria-hidden="true" tabindex="-1"></a>                    capacity: <span class="dt">usize</span>) !Stack(T) <span class="op">{</span></span>
+<span id="cb17-11"><a href="#cb17-11" aria-hidden="true" tabindex="-1"></a>            <span class="kw">var</span> buf = <span class="kw">try</span> allocator.alloc(T, capacity);</span>
+<span id="cb17-12"><a href="#cb17-12" aria-hidden="true" tabindex="-1"></a>            <span class="kw">return</span> .<span class="op">{</span></span>
+<span id="cb17-13"><a href="#cb17-13" aria-hidden="true" tabindex="-1"></a>                .items = buf[<span class="dv">0</span>..],</span>
+<span id="cb17-14"><a href="#cb17-14" aria-hidden="true" tabindex="-1"></a>                .capacity = capacity,</span>
+<span id="cb17-15"><a href="#cb17-15" aria-hidden="true" tabindex="-1"></a>                .length = <span class="dv">0</span>,</span>
+<span id="cb17-16"><a href="#cb17-16" aria-hidden="true" tabindex="-1"></a>                .allocator = allocator,</span>
+<span id="cb17-17"><a href="#cb17-17" aria-hidden="true" tabindex="-1"></a>            <span class="op">}</span>;</span>
+<span id="cb17-18"><a href="#cb17-18" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span></span>
+<span id="cb17-19"><a href="#cb17-19" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb17-20"><a href="#cb17-20" aria-hidden="true" tabindex="-1"></a>        <span class="kw">pub</span> <span class="kw">fn</span> push(self: *Self, val: T) !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb17-21"><a href="#cb17-21" aria-hidden="true" tabindex="-1"></a>        <span class="co">// Truncate the rest of the struct</span></span>
+<span id="cb17-22"><a href="#cb17-22" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>;</span>
+<span id="cb17-23"><a href="#cb17-23" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>Notice that we have created a function in this example named <code>Stack()</code>. This function takes a type as input, and passes this type to the struct definition of our <code>Stack</code> object. The data member <code>items</code> is now, an array of type <code>T</code>, which is the data type that we have provided as input to the function. The function argument <code>val</code> in the <code>push()</code> function is now a value of type <code>T</code> too.</p>
 <p>We can just provide a data type to this function, and it will create a definition of a <code>Stack</code> object that can store values of the data type that we have provided. In the example below, we are creating the definition of a <code>Stack</code> object that can store <code>u8</code> values in it. This definition is stored at the <code>Stacku8</code> object. This <code>Stacku8</code> object becomes our new struct, it is the struct that we are going to use to create our <code>Stack</code> object.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb20"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb20-1"><a href="#cb20-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> gpa = std.heap.GeneralPurposeAllocator(.<span class="op">{}</span>)<span class="op">{}</span>;</span>
-<span id="cb20-2"><a href="#cb20-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> allocator = gpa.allocator();</span>
-<span id="cb20-3"><a href="#cb20-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Stacku8 = Stack(<span class="dt">u8</span>);</span>
-<span id="cb20-4"><a href="#cb20-4" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> stack = <span class="kw">try</span> Stacku8.init(allocator, <span class="dv">10</span>);</span>
-<span id="cb20-5"><a href="#cb20-5" aria-hidden="true" tabindex="-1"></a><span class="kw">defer</span> stack.deinit();</span>
-<span id="cb20-6"><a href="#cb20-6" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stack.push(<span class="dv">1</span>);</span>
-<span id="cb20-7"><a href="#cb20-7" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stack.push(<span class="dv">2</span>);</span>
-<span id="cb20-8"><a href="#cb20-8" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stack.push(<span class="dv">3</span>);</span>
-<span id="cb20-9"><a href="#cb20-9" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stack.push(<span class="dv">4</span>);</span>
-<span id="cb20-10"><a href="#cb20-10" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stack.push(<span class="dv">5</span>);</span>
-<span id="cb20-11"><a href="#cb20-11" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stack.push(<span class="dv">6</span>);</span>
-<span id="cb20-12"><a href="#cb20-12" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb20-13"><a href="#cb20-13" aria-hidden="true" tabindex="-1"></a>std.debug.print(<span class="st">"Stack len: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>stack.length<span class="op">}</span>);</span>
-<span id="cb20-14"><a href="#cb20-14" aria-hidden="true" tabindex="-1"></a>std.debug.print(<span class="st">"Stack capacity: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>stack.capacity<span class="op">}</span>);</span>
-<span id="cb20-15"><a href="#cb20-15" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb20-16"><a href="#cb20-16" aria-hidden="true" tabindex="-1"></a>stack.pop();</span>
-<span id="cb20-17"><a href="#cb20-17" aria-hidden="true" tabindex="-1"></a>std.debug.print(<span class="st">"Stack len: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>stack.length<span class="op">}</span>);</span>
-<span id="cb20-18"><a href="#cb20-18" aria-hidden="true" tabindex="-1"></a>stack.pop();</span>
-<span id="cb20-19"><a href="#cb20-19" aria-hidden="true" tabindex="-1"></a>std.debug.print(<span class="st">"Stack len: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>stack.length<span class="op">}</span>);</span>
-<span id="cb20-20"><a href="#cb20-20" aria-hidden="true" tabindex="-1"></a>std.debug.print(</span>
-<span id="cb20-21"><a href="#cb20-21" aria-hidden="true" tabindex="-1"></a>    <span class="st">"Stack state: {any}</span><span class="sc">\n</span><span class="st">"</span>,</span>
-<span id="cb20-22"><a href="#cb20-22" aria-hidden="true" tabindex="-1"></a>    .<span class="op">{</span>stack.items[<span class="dv">0</span>..stack.length]<span class="op">}</span></span>
-<span id="cb20-23"><a href="#cb20-23" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb18"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb18-1"><a href="#cb18-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> gpa = std.heap.GeneralPurposeAllocator(.<span class="op">{}</span>)<span class="op">{}</span>;</span>
+<span id="cb18-2"><a href="#cb18-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> allocator = gpa.allocator();</span>
+<span id="cb18-3"><a href="#cb18-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Stacku8 = Stack(<span class="dt">u8</span>);</span>
+<span id="cb18-4"><a href="#cb18-4" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> stack = <span class="kw">try</span> Stacku8.init(allocator, <span class="dv">10</span>);</span>
+<span id="cb18-5"><a href="#cb18-5" aria-hidden="true" tabindex="-1"></a><span class="kw">defer</span> stack.deinit();</span>
+<span id="cb18-6"><a href="#cb18-6" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stack.push(<span class="dv">1</span>);</span>
+<span id="cb18-7"><a href="#cb18-7" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stack.push(<span class="dv">2</span>);</span>
+<span id="cb18-8"><a href="#cb18-8" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stack.push(<span class="dv">3</span>);</span>
+<span id="cb18-9"><a href="#cb18-9" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stack.push(<span class="dv">4</span>);</span>
+<span id="cb18-10"><a href="#cb18-10" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stack.push(<span class="dv">5</span>);</span>
+<span id="cb18-11"><a href="#cb18-11" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stack.push(<span class="dv">6</span>);</span>
+<span id="cb18-12"><a href="#cb18-12" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb18-13"><a href="#cb18-13" aria-hidden="true" tabindex="-1"></a>std.debug.print(<span class="st">"Stack len: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>stack.length<span class="op">}</span>);</span>
+<span id="cb18-14"><a href="#cb18-14" aria-hidden="true" tabindex="-1"></a>std.debug.print(<span class="st">"Stack capacity: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>stack.capacity<span class="op">}</span>);</span>
+<span id="cb18-15"><a href="#cb18-15" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb18-16"><a href="#cb18-16" aria-hidden="true" tabindex="-1"></a>stack.pop();</span>
+<span id="cb18-17"><a href="#cb18-17" aria-hidden="true" tabindex="-1"></a>std.debug.print(<span class="st">"Stack len: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>stack.length<span class="op">}</span>);</span>
+<span id="cb18-18"><a href="#cb18-18" aria-hidden="true" tabindex="-1"></a>stack.pop();</span>
+<span id="cb18-19"><a href="#cb18-19" aria-hidden="true" tabindex="-1"></a>std.debug.print(<span class="st">"Stack len: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>stack.length<span class="op">}</span>);</span>
+<span id="cb18-20"><a href="#cb18-20" aria-hidden="true" tabindex="-1"></a>std.debug.print(</span>
+<span id="cb18-21"><a href="#cb18-21" aria-hidden="true" tabindex="-1"></a>    <span class="st">"Stack state: {any}</span><span class="sc">\n</span><span class="st">"</span>,</span>
+<span id="cb18-22"><a href="#cb18-22" aria-hidden="true" tabindex="-1"></a>    .<span class="op">{</span>stack.items[<span class="dv">0</span>..stack.length]<span class="op">}</span></span>
+<span id="cb18-23"><a href="#cb18-23" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Stack len: 6
 Stack capacity: 10
diff --git a/docs/search.json b/docs/search.json
index 5ac48cc7..77f47fa2 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -244,7 +244,7 @@
     "href": "Chapters/03-structs.html#sec-fun-pars",
     "title": "2  Control flow, structs, modules and types",
     "section": "2.2 Function parameters are immutable",
-    "text": "2.2 Function parameters are immutable\nWe have already discussed a lot of the syntax behind function declarations in Section 1.2.2 and Section 1.2.3. But I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig. In summary, function parameters are immutable in Zig.\nTake the code example below, where we declare a simple function that just tries to add some amount to the input integer, and returns the result back. If you look closely at the body of this add2() function, you will notice that we try to save the result back into the x function argument.\nIn other words, this function not only uses the value that it received through the function argument x, but it also tries to change the value of this function argument, by assigning the addition result into x. However, function arguments in Zig are immutable. You cannot change their values, or, you cannot assign values to them inside the body’s function.\nThis is the reason why, the code example below does not compile successfully. If you try to compile this code example, you will get a compile error message about “trying to change the value of a immutable (i.e. constant) object”.\n\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n\n2.2.1 A free optimization\nIf a function argument receives as input an object whose data type is any of the primitive types that we have listed in Section 1.5, this object is always passed by value to the function. In other words, this object is copied into the function stack frame.\nHowever, if the input object have a more complex data type, for example, it might be a struct instance, or an array, or an union value, etc., in cases like that, the zig compiler will take the liberty of deciding for you which strategy is best. Thus, the zig compiler will pass your object to the function either by value, or by reference. The compiler will always choose the strategy that is faster for you. This optimization that you get for free is possible only because function arguments are immutable in Zig.\n\n\n2.2.2 How to overcome this barrier\nThere are some situations where you might need to change the value of your function argument directly inside the function’s body. This happens more often when we are passing C structs as inputs to Zig functions.\nIn a situation like this, you can overcome this barrier by using a pointer. In other words, instead of passing a value as input to the argument, you can pass a “pointer to value” instead. You can change the value that the pointer points to, by dereferencing it.\nTherefore, if we take our previous add2() example, we can change the value of the function argument x inside the function’s body by marking the x argument as a “pointer to a u32 value” (i.e. *u32 data type), instead of a u32 value. By making it a pointer, we can finally alter the value of this function argument directly inside the body of the add2() function. You can see that the code example below compiles successfully.\n\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n\nResult: 6\n\n\nResult: 6\nEven in this code example above, the x argument is still immutable. Which means that the pointer itself is immutable. Therefore, you cannot change the memory address that it points to. However, you can dereference the pointer to access the value that it points to, and also, to change this value, if you need to.",
+    "text": "2.2 Function parameters are immutable\nWe have already discussed a lot of the syntax behind function declarations in Section 1.2.2 and Section 1.2.3. But I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig. In summary, function parameters are immutable in Zig.\nTake the code example below, where we declare a simple function that just tries to add some amount to the input integer, and returns the result back. If you look closely at the body of this add2() function, you will notice that we try to save the result back into the x function argument.\nIn other words, this function not only uses the value that it received through the function argument x, but it also tries to change the value of this function argument, by assigning the addition result into x. However, function arguments in Zig are immutable. You cannot change their values, or, you cannot assign values to them inside the body’s function.\nThis is the reason why, the code example below does not compile successfully. If you try to compile this code example, you will get a compile error message about “trying to change the value of a immutable (i.e. constant) object”.\n\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n\n2.2.1 A free optimization\nIf a function argument receives as input an object whose data type is any of the primitive types that we have listed in Section 1.5, this object is always passed by value to the function. In other words, this object is copied into the function stack frame.\nHowever, if the input object have a more complex data type, for example, it might be a struct instance, or an array, or an union value, etc., in cases like that, the zig compiler will take the liberty of deciding for you which strategy is best. Thus, the zig compiler will pass your object to the function either by value, or by reference. The compiler will always choose the strategy that is faster for you. This optimization that you get for free is possible only because function arguments are immutable in Zig.\n\n\n2.2.2 How to overcome this barrier\nThere are some situations where you might need to change the value of your function argument directly inside the function’s body. This happens more often when we are passing C structs as inputs to Zig functions.\nIn a situation like this, you can overcome this barrier by using a pointer. In other words, instead of passing a value as input to the argument, you can pass a “pointer to value” instead. You can change the value that the pointer points to, by dereferencing it.\nTherefore, if we take our previous add2() example, we can change the value of the function argument x inside the function’s body by marking the x argument as a “pointer to a u32 value” (i.e. *u32 data type), instead of a u32 value. By making it a pointer, we can finally alter the value of this function argument directly inside the body of the add2() function. You can see that the code example below compiles successfully.\n\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n\nResult: 6\nEven in this code example above, the x argument is still immutable. Which means that the pointer itself is immutable. Therefore, you cannot change the memory address that it points to. However, you can dereference the pointer to access the value that it points to, and also, to change this value, if you need to.",
     "crumbs": [
       "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
     ]
@@ -274,7 +274,7 @@
     "href": "Chapters/03-structs.html#sec-type-cast",
     "title": "2  Control flow, structs, modules and types",
     "section": "2.5 Type casting",
-    "text": "2.5 Type casting\nIn this section, I want to discuss type casting (or, type conversion) with you. We use type casting when we have an object of type “x”, and we want to convert it into an object of type “y”, i.e. we want to change the data type of the object.\nMost languages have a formal way to perform type casting. In Rust for example, we normally use the keyword as, and in C, we normally use the type casting syntax, e.g. (int) x. In Zig, we use the @as() built-in function to cast an object of type “x”, into an object of type “y”.\nThis @as() function is the preferred way to perform type conversion (or type casting) in Zig. Because it is explicit, and, it also performs the casting only if it is unambiguous and safe. To use this function, you just provide the target data type in the first argument, and, the object that you want cast as the second argument.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n\n1/1 filefe9b6a29a64b.test_0...OKAll 1 tests passed\n  d.\n\n\nThis is the general way to perform type casting in Zig. But remember, @as() works only when casting is unambiguous and safe, and there are situations where these assumptions do not hold. For example, when casting an integer value into a float value, or vice-versa, it is not clear to the compiler how to perform this conversion safely.\nTherefore, we need to use specialized “casting functions” in such situations. For example, if you want to cast an integer value into a float value, then, you should use the @floatFromInt() function. In the inverse scenario, you should use the @intFromFloat() function.\nIn these functions, you just provide the object that you want to cast as input. Then, the target data type of the “type casting operation” is determined by the type annotation of the object where you are saving the results. In the example below, we are casting the object x into a value of type f32, because the object y, which is where we are saving the results, is annotated as an object of type f32.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n\n1/1 filefe9b126af3c3.test_0...OKAll 1 tests passed\n  d.\n\n\nAnother built-in function that is very useful when performing type casting operations is @ptrCast(). In essence, we use the @as() built-in function when we want to explicit convert (or cast) a Zig value/object from a type “x” to a type “y”, etc. However, pointers (we are going to discuss pointers in more depth in Chapter 6) are a special type of object in Zig, i.e. they are treated differently from “normal objects”.\nEverytime a pointer is involved in some “type casting operation” in Zig, the @ptrCast() function is used. This function works similarly to @floatFromInt(). You just provide the pointer object that you want to cast as input to this function, and the target data type is, once again, determined by the type annotation of the object where the results are being stored.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n\n1/1 filefe9b7366fb7.test_0...OKAll 1 tests passed.",
+    "text": "2.5 Type casting\nIn this section, I want to discuss type casting (or, type conversion) with you. We use type casting when we have an object of type “x”, and we want to convert it into an object of type “y”, i.e. we want to change the data type of the object.\nMost languages have a formal way to perform type casting. In Rust for example, we normally use the keyword as, and in C, we normally use the type casting syntax, e.g. (int) x. In Zig, we use the @as() built-in function to cast an object of type “x”, into an object of type “y”.\nThis @as() function is the preferred way to perform type conversion (or type casting) in Zig. Because it is explicit, and, it also performs the casting only if it is unambiguous and safe. To use this function, you just provide the target data type in the first argument, and, the object that you want cast as the second argument.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n\n1/1 file10b91234368fa.test_0...OKAll 1 tests passe\n  ed.\n\n\nThis is the general way to perform type casting in Zig. But remember, @as() works only when casting is unambiguous and safe, and there are situations where these assumptions do not hold. For example, when casting an integer value into a float value, or vice-versa, it is not clear to the compiler how to perform this conversion safely.\nTherefore, we need to use specialized “casting functions” in such situations. For example, if you want to cast an integer value into a float value, then, you should use the @floatFromInt() function. In the inverse scenario, you should use the @intFromFloat() function.\nIn these functions, you just provide the object that you want to cast as input. Then, the target data type of the “type casting operation” is determined by the type annotation of the object where you are saving the results. In the example below, we are casting the object x into a value of type f32, because the object y, which is where we are saving the results, is annotated as an object of type f32.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n\n1/1 file10b9130ae9221.test_0...OKAll 1 tests passe\n  ed.\n\n\nAnother built-in function that is very useful when performing type casting operations is @ptrCast(). In essence, we use the @as() built-in function when we want to explicit convert (or cast) a Zig value/object from a type “x” to a type “y”, etc. However, pointers (we are going to discuss pointers in more depth in Chapter 6) are a special type of object in Zig, i.e. they are treated differently from “normal objects”.\nEverytime a pointer is involved in some “type casting operation” in Zig, the @ptrCast() function is used. This function works similarly to @floatFromInt(). You just provide the pointer object that you want to cast as input to this function, and the target data type is, once again, determined by the type annotation of the object where the results are being stored.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n\n1/1 file10b914c434861.test_0...OKAll 1 tests passe\n  ed.",
     "crumbs": [
       "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
     ]
@@ -444,7 +444,7 @@
     "href": "Chapters/02-debugging.html#print-debugging",
     "title": "5  Debugging Zig applications",
     "section": "",
-    "text": "d: for printing integers and floating-point numbers.\nc: for printing characters.\ns: for printing strings.\np: for printing memory addresses.\nx: for printing hexadecimal values.\nany: use any compatible format specifier (i.e. it automatically selects a format specifier for you).\n\n\n\n\n\nResult: 50",
+    "text": "d: for printing integers and floating-point numbers.\nc: for printing characters.\ns: for printing strings.\np: for printing memory addresses.\nx: for printing hexadecimal values.\nany: use any compatible format specifier (i.e. it automatically selects a format specifier for you).",
     "crumbs": [
       "<span class='chapter-number'>5</span>  <span class='chapter-title'>Debugging Zig applications</span>"
     ]
@@ -894,7 +894,7 @@
     "href": "Chapters/09-data-structures.html#sec-maps-hashtables",
     "title": "11  Data Structures",
     "section": "11.2 Maps or HashTables",
-    "text": "11.2 Maps or HashTables\nSome professionals know this type of data structure by different terms, like “map”, “hashmap” or “associative arrays”. But the most common term used is hashtable. Every programming language normally have some implementation of a hashtable in their standard libraries. Python have dict(), C++ have std::map and std::unordered_map, Rust have HashMap, Javascript have Object() and Map(), etc.\n\n11.2.1 What is a hashtable?\nA hashtable is a data structure based on key-value pairs. You provide a key and a value to this structure, then, the hashtable will store the input value at a location that can be identified by the input key that you provided. It does that by using an underlying array and a hash function. These two components are essential to how a hashtable works.\nUnder the hood, the hashtable contains an array. This array is where the values are stored, and the elements of this array are usually called of buckets. So the values that you provide to the hashtable are stored inside buckets, and you access each bucket by using an index.\nWhen you provide a key to a hashtable, it passes this key to the hash function. This hash function uses some sort of hashing algorithm to transform this key into an index. This index is actually an array index. It is a position in the underlying array of the hashtable. This is how a key identifies a specific position (or location) inside the hashtable structure.\nTherefore, you provide a key to the hashtable, and this key identifies a specific location inside the hashtable, then, the hashtable takes the input value that you provided, and stores this value in the location identified by this input key. You could say that the key maps to the value stored in the hashtable. You find the value, by using the key that identifies the location where the value is stored. The Figure 11.2 presents this process visually.\n\n\n\n\n\n\nFigure 11.2: A diagram of a Hashtable. Source: Wikipedia, the free encyclopedia.\n\n\n\nThe operation described in the previous paragraph is normally called an insertion operation. Because you are inserting new values into the hashtable. But there are other types of operations in hashtables such as delete and lookup. Delete is self describing, it is when you delete (or remove) a value from the hashtable. While lookup corresponds to when you look at a value that is stored in the hashtable, by using the key that identifies the location where this value is stored.\nSometimes, instead of storing the values directly, the underlying array of the hashtable might be an array of pointers, i.e. the buckets of the array stores pointers that points to the value, or also, may be an array of linked lists. These cases are common on hashtables that allows duplicate keys, or, in other words, on hashtables that effectively handle “collisions” that may arise from the hash function.\nDuplicate keys, or this “collision” thing that I’m talking about, is when you have two different keys that points to the same location (i.e. to the same index) in the underlying array of the hashtable. This might happen depending on the characteristics of the hash function that is being used in the hashtable. Some implementations of the hashtable will actively deal with collisions, meaning that, they will handle this case in some way. For example, the hashtable might transform all buckets into linked lists. Because with a linked list you can store multiple values into a single bucket.\nThere are different techniques to handle collisions in hashtables, which I will not describe in this book, because it is not our main scope here. But you can find a good description of some of the most common techniques at the Wikipedia page of hashtables (Wikipedia 2024).\n\n\n11.2.2 Hashtables in Zig\nThe Zig Standard Library provides different implementations of a hashtable. Each implementation have its own cons and pros, which we will discuss later on, and all of them are available through the std.hash_map module.\nThe HashMap struct is a general-purpose hashtable, which have very fast operations (lookup, insertion, delete), and also, quite high load factors for low memory usage. You can create and provide a context object to the HashMap constructor. This context object allows you to tailor the behaviour of the hashtable itself, because you can provide a hash function implementation to be used by the hashtable through this context object.\nBut let’s not worry about this context object now, because it is meant to be used by “experts in the field of hashtables”. Since we are most likely not experts in this field, we are going to take the easy way to create a hashtable. Which is by using the AutoHashMap() function.\nThis AutoHashMap() function is essentially a “create a hashtable object that uses the default settings” type of function. It automatically chooses a context object, and, therefore, a hash function implementation, for you. This function receives two data types as input, the first input is the data type of the keys that will be used in this hashtable, while the second input is the data type of the data that will be stored inside the hashtable, that is, the data type of the values to be stored.\nIn the example below, we are providing the data type u32 in the first argument, and u16 in the second argument of this function. This means that we are going to use u32 values as keys in this hashtable, while u16 values are the actual values that are going to be stored into this hashtable. At the end of this process, the hash_table object contains a HashMap object that uses the default settings and context.\n\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n    std.debug.print(\n        \"Value at key 50050: {d}\\n\",\n        .{hash_table.get(50050).?}\n    );\n\n    if (hash_table.remove(57709)) {\n        std.debug.print(\n            \"Value at key 57709 successfully removed!\\n\",\n            .{}\n        );\n    }\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n}\n\nN of values stored: 3\nValue at key 50050: 55\nValue at key 57709 successfully removed!\nN of values stored: 2\nYou can add/put new values into the hashtable by using the put() method. The first argument is the key to be used, and the second argument is the actual value that you want to store inside the hashtable. In the example below, we first add the value 89 using the key 54321, next, we add the value 55 using the key 50050, etc.\nNotice that we have used the method count() to see how many values are currently stored in the hashtable. After that, we also use the get() method to access (or look) at the value stored in the position identified by the key 500050. The output of this get() method is an optional value. This is why we use the ? method at the end to get the actual value.\nAlso notice that we can remove (or delete) values from the hashtable by using the remove() method. You provide the key that identifies the value that you want to delete, then, the method will delete this value and return a true value as output. This true value essentially tells us that the method successfully deleted the value.\nBut this delete operation might not be always successful. For example, you might provide the wrong key to this method. I mean, maybe you provide (either intentionally or unintentionally) a key that points to an empty bucket, i.e. a bucket that still doesn’t have a value in it. In this case, the remove() method would return a false value.\n\n\n11.2.3 Iterating through the hashtable\nIterating through the keys and values that are currently being stored in the hashtable is a very common necessity. You can do that in Zig by using an iterator object that can iterate through the elements of your hashtable object.\nThis iterator object works like any other iterator object that you would find in languages such as C++ and Rust. It is basically a pointer object that points to some value in the container, and has a next() method that you can use to navigate (or iterate) through the values in the container.\nYou can create such iterator object by using the iterator() method of the hashtable object. This method returns an iterator object, from which you can use the next() method in conjunction with a while loop to iterate through the elements of your hashtable. The next() method returns an optional Entry value, and therefore, you must unwrap this optional value to get the actual Entry value from which you can access the key and also the value identified by this key.\nWith this Entry value at hand, you can access the key of this current entry by using the key_ptr attribute and dereferencing the pointer that lives inside of it, while the value identified by this key is accessed through the value_ptr attribute instead, which is also a pointer to be dereferenced. The code example below demonstrates the use of these elements:\n\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n\n    var it = hash_table.iterator();\n    while (it.next()) |kv| {\n        // Access the current key\n        std.debug.print(\"Key: {d} | \", .{kv.key_ptr.*});\n        // Access the current value\n        std.debug.print(\"Value: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n\nKey: 54321 | Value: 89Key: 50050 | Value: 55Key: 5\n  57709 | Value: 41\n\n\nKey: 54321 | Value: 89\nKey: 50050 | Value: 55\nKey: 57709 | Value: 41\nIf you want to iterate specifically through the values or the keys of your hashtable, you can create a key iterator or a value iterator object. These are also iterator objects, which have the same next() method that you can use to iterate through the hashtable.\nKey iterators are created from the keyIterator() method of your hashtable object, while value iterators are created from the valueIterator() method. All you have to do is to unwrap the value from the next() method and deference it directly to access the key or the value that you are iterating over. The code example below demonstrates the use of a key iterator, but you can replicate the same logic to a value iterator.\n\nvar kit = hash_table.keyIterator();\nwhile (kit.next()) |key| {\n    std.debug.print(\"Key: {d}\\n\", .{key.*});\n}\n\nKey: 54321\nKey: 50050\nKey: 57709\n\n\n11.2.4 The ArrayHashMap hashtable\nIf you need to iterate through the elements of your hashtable constantly, you might want to use the ArrayHashMap struct for your specific case, instead of going with the usual and general-purpose HashMap struct.\nThe ArrayHashMap struct creates a hashtable that is faster to iterate over. That is why this specific type of hashtable might be valuable to you. Some other properties of a ArrayHashMap hashtable are:\n\nthe order of insertion is preserved, i.e. the order of the values that you find while iterating through this hashtable is actually the order in which these values were inserted in the hashtable.\nthe key-value pairs are stored sequentially, one after another.\n\nYou can create an ArrayHashMap object by using, once again, a helper function that chooses automatically for you a hash function implementation. This is the AutoArrayHashMap() function, which works very similarly to the AutoHashMap() function that we presented at Section 11.2.2.\nYou provide two data types to this function. The data type of the keys that will be used in this hashtable, and the data type of the values that will be stored in this hashtable.\nAn ArrayHashMap object have essentially the exact same methods from the HashMap struct. So you can insert new values into the hashtable by using the put() method, and you can look (or get) a value from the hashtable by using the get() method. But the remove() method is not available in this specific type of hashtable.\nIn order to delete values from the hashtable, you would use the same methods that you find in an ArrayList object, i.e. a dynamic array. I presented these methods at Section 11.1.4, which are the swapRemove() and orderedRemove() methods. These methods have the same meaning here, or, the same effect that they have in an ArrayList object.\nThis means that, with swapRemove() you remove the value from the hashtable, but you do not preserve the order in which the values were inserted into the structure. While orderedRemove() is able to retain the order in which these values were inserted.\nBut instead of providing an index as input to swapRemove() or orderedRemove(), like I described at Section 11.1.4, these methods here in an ArrayHashMap take a key as input, like the remove() method from a HashMap object. If you want to provide an index as input, instead of a key, you should use the swapRemoveAt() and orderedRemoveAt() methods.\n\nvar hash_table = AutoArrayHashMap(u32, u16)\n    .init(allocator);\ndefer hash_table.deinit();\n\n\n\n11.2.5 The StringHashMap hashtable\nOne thing that you will notice in the other two types of hashtables that I have presented over the last sections, is that neither of them accepts a slice data type in their keys. What this means is that you cannot use a slice value to represent a key in these types of hashtable.\nThe most obvious consequence of this, is that you cannot use strings as keys in these hashtables. But it is extremely common to use strings as keys in hashtables.\nTake this very simple Javascript code snippet as an example. We are creating a simple hashtable object named people. Then, we add a new entry to this hashtable, which is identified by the string 'Pedro'. This string is the key in this case, while the object containing different personal information such as age, height and city, is the value to be stored in the hashtable.\nvar people = new Object();\npeople['Pedro'] = {\n    'age': 25,\n    'height': 1.67,\n    'city': 'Belo Horizonte'\n};\nThis pattern of using strings as keys is very common in all sorts of situations. That is why the Zig Standard Library offers a specific type of hashtable for this purpose, which is created through the StringHashMap() function. This function creates a hashtable that uses strings as keys. The only input of this function is the data type of the values that will be stored into this hashtable.\nIn the example below, I’m creating a hashtable to store the ages of different people. Each key in this hashtable is represented by the name of each person, while the value stored in the hashtable is the age of this person identified by the key.\nThat is why I provide the u8 data type (which is the data type used by the age values) as input to this StringHashMap() function. As the result, it creates a hashtable that uses string values as keys, and, that stores u8 values in it. Notice that an allocator object is provided at the init() method of the resulting object from the StringHashMap() function.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var ages = std.StringHashMap(u8).init(allocator);\n    defer ages.deinit();\n\n    try ages.put(\"Pedro\", 25);\n    try ages.put(\"Matheus\", 21);\n    try ages.put(\"Abgail\", 42);\n\n    var it = ages.iterator();\n    while (it.next()) |kv| {\n        std.debug.print(\"Key: {s} | \", .{kv.key_ptr.*});\n        std.debug.print(\"Age: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n\nKey: Pedro | Age: 25\nKey: Abgail | Age: 42\nKey: Matheus | Age: 21\n\n\n11.2.6 The StringArrayHashMap hashtable\nThe Zig Standard Library also provides a type of hashtable that mix the cons and pros of the StringHashMap and ArrayHashMap together. That is, a hashtable that uses strings as keys, but also have the advantages from ArrayHashMap. In other words, you can have a hashtable that is fast to iterate over, that preserves insertion order, and also, that uses strings as keys.\nYou can create such type of hashtable by using the StringArrayHashMap() function. This function accepts a data type as input, which is the data type of the values that are going to be stored inside this hashtable, in the same style as the function presented at Section 11.2.5.\nYou can insert new values into this hashtable by using the same put() method that we have discussed at Section 11.2.5. And you can also get values from the hashtable by using the same get() method. Like its ArrayHashMap brother, to delete values from this specific type of hashtable, we also use the orderedRemove() and swapRemove() methods, with the same effects that I have described at Section 11.2.4.\nIf we take the code example that was exposed at Section 11.2.5, we can achieve the exact same result with StringArrayHashMap():\n\nvar ages = std.StringArrayHashMap(u8).init(allocator);",
+    "text": "11.2 Maps or HashTables\nSome professionals know this type of data structure by different terms, like “map”, “hashmap” or “associative arrays”. But the most common term used is hashtable. Every programming language normally have some implementation of a hashtable in their standard libraries. Python have dict(), C++ have std::map and std::unordered_map, Rust have HashMap, Javascript have Object() and Map(), etc.\n\n11.2.1 What is a hashtable?\nA hashtable is a data structure based on key-value pairs. You provide a key and a value to this structure, then, the hashtable will store the input value at a location that can be identified by the input key that you provided. It does that by using an underlying array and a hash function. These two components are essential to how a hashtable works.\nUnder the hood, the hashtable contains an array. This array is where the values are stored, and the elements of this array are usually called of buckets. So the values that you provide to the hashtable are stored inside buckets, and you access each bucket by using an index.\nWhen you provide a key to a hashtable, it passes this key to the hash function. This hash function uses some sort of hashing algorithm to transform this key into an index. This index is actually an array index. It is a position in the underlying array of the hashtable. This is how a key identifies a specific position (or location) inside the hashtable structure.\nTherefore, you provide a key to the hashtable, and this key identifies a specific location inside the hashtable, then, the hashtable takes the input value that you provided, and stores this value in the location identified by this input key. You could say that the key maps to the value stored in the hashtable. You find the value, by using the key that identifies the location where the value is stored. The Figure 11.2 presents this process visually.\n\n\n\n\n\n\nFigure 11.2: A diagram of a Hashtable. Source: Wikipedia, the free encyclopedia.\n\n\n\nThe operation described in the previous paragraph is normally called an insertion operation. Because you are inserting new values into the hashtable. But there are other types of operations in hashtables such as delete and lookup. Delete is self describing, it is when you delete (or remove) a value from the hashtable. While lookup corresponds to when you look at a value that is stored in the hashtable, by using the key that identifies the location where this value is stored.\nSometimes, instead of storing the values directly, the underlying array of the hashtable might be an array of pointers, i.e. the buckets of the array stores pointers that points to the value, or also, may be an array of linked lists. These cases are common on hashtables that allows duplicate keys, or, in other words, on hashtables that effectively handle “collisions” that may arise from the hash function.\nDuplicate keys, or this “collision” thing that I’m talking about, is when you have two different keys that points to the same location (i.e. to the same index) in the underlying array of the hashtable. This might happen depending on the characteristics of the hash function that is being used in the hashtable. Some implementations of the hashtable will actively deal with collisions, meaning that, they will handle this case in some way. For example, the hashtable might transform all buckets into linked lists. Because with a linked list you can store multiple values into a single bucket.\nThere are different techniques to handle collisions in hashtables, which I will not describe in this book, because it is not our main scope here. But you can find a good description of some of the most common techniques at the Wikipedia page of hashtables (Wikipedia 2024).\n\n\n11.2.2 Hashtables in Zig\nThe Zig Standard Library provides different implementations of a hashtable. Each implementation have its own cons and pros, which we will discuss later on, and all of them are available through the std.hash_map module.\nThe HashMap struct is a general-purpose hashtable, which have very fast operations (lookup, insertion, delete), and also, quite high load factors for low memory usage. You can create and provide a context object to the HashMap constructor. This context object allows you to tailor the behaviour of the hashtable itself, because you can provide a hash function implementation to be used by the hashtable through this context object.\nBut let’s not worry about this context object now, because it is meant to be used by “experts in the field of hashtables”. Since we are most likely not experts in this field, we are going to take the easy way to create a hashtable. Which is by using the AutoHashMap() function.\nThis AutoHashMap() function is essentially a “create a hashtable object that uses the default settings” type of function. It automatically chooses a context object, and, therefore, a hash function implementation, for you. This function receives two data types as input, the first input is the data type of the keys that will be used in this hashtable, while the second input is the data type of the data that will be stored inside the hashtable, that is, the data type of the values to be stored.\nIn the example below, we are providing the data type u32 in the first argument, and u16 in the second argument of this function. This means that we are going to use u32 values as keys in this hashtable, while u16 values are the actual values that are going to be stored into this hashtable. At the end of this process, the hash_table object contains a HashMap object that uses the default settings and context.\n\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n    std.debug.print(\n        \"Value at key 50050: {d}\\n\",\n        .{hash_table.get(50050).?}\n    );\n\n    if (hash_table.remove(57709)) {\n        std.debug.print(\n            \"Value at key 57709 successfully removed!\\n\",\n            .{}\n        );\n    }\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n}\n\nN of values stored: 3\nValue at key 50050: 55\nValue at key 57709 successfully removed!\nN of values stored: 2\nYou can add/put new values into the hashtable by using the put() method. The first argument is the key to be used, and the second argument is the actual value that you want to store inside the hashtable. In the example below, we first add the value 89 using the key 54321, next, we add the value 55 using the key 50050, etc.\nNotice that we have used the method count() to see how many values are currently stored in the hashtable. After that, we also use the get() method to access (or look) at the value stored in the position identified by the key 500050. The output of this get() method is an optional value. This is why we use the ? method at the end to get the actual value.\nAlso notice that we can remove (or delete) values from the hashtable by using the remove() method. You provide the key that identifies the value that you want to delete, then, the method will delete this value and return a true value as output. This true value essentially tells us that the method successfully deleted the value.\nBut this delete operation might not be always successful. For example, you might provide the wrong key to this method. I mean, maybe you provide (either intentionally or unintentionally) a key that points to an empty bucket, i.e. a bucket that still doesn’t have a value in it. In this case, the remove() method would return a false value.\n\n\n11.2.3 Iterating through the hashtable\nIterating through the keys and values that are currently being stored in the hashtable is a very common necessity. You can do that in Zig by using an iterator object that can iterate through the elements of your hashtable object.\nThis iterator object works like any other iterator object that you would find in languages such as C++ and Rust. It is basically a pointer object that points to some value in the container, and has a next() method that you can use to navigate (or iterate) through the values in the container.\nYou can create such iterator object by using the iterator() method of the hashtable object. This method returns an iterator object, from which you can use the next() method in conjunction with a while loop to iterate through the elements of your hashtable. The next() method returns an optional Entry value, and therefore, you must unwrap this optional value to get the actual Entry value from which you can access the key and also the value identified by this key.\nWith this Entry value at hand, you can access the key of this current entry by using the key_ptr attribute and dereferencing the pointer that lives inside of it, while the value identified by this key is accessed through the value_ptr attribute instead, which is also a pointer to be dereferenced. The code example below demonstrates the use of these elements:\n\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n\n    var it = hash_table.iterator();\n    while (it.next()) |kv| {\n        // Access the current key\n        std.debug.print(\"Key: {d} | \", .{kv.key_ptr.*});\n        // Access the current value\n        std.debug.print(\"Value: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n\nKey: 54321 | Value: 89\nKey: 50050 | Value: 55\nKey: 57709 | Value: 41\nIf you want to iterate specifically through the values or the keys of your hashtable, you can create a key iterator or a value iterator object. These are also iterator objects, which have the same next() method that you can use to iterate through the hashtable.\nKey iterators are created from the keyIterator() method of your hashtable object, while value iterators are created from the valueIterator() method. All you have to do is to unwrap the value from the next() method and deference it directly to access the key or the value that you are iterating over. The code example below demonstrates the use of a key iterator, but you can replicate the same logic to a value iterator.\n\nvar kit = hash_table.keyIterator();\nwhile (kit.next()) |key| {\n    std.debug.print(\"Key: {d}\\n\", .{key.*});\n}\n\nKey: 54321\nKey: 50050\nKey: 57709\n\n\n11.2.4 The ArrayHashMap hashtable\nIf you need to iterate through the elements of your hashtable constantly, you might want to use the ArrayHashMap struct for your specific case, instead of going with the usual and general-purpose HashMap struct.\nThe ArrayHashMap struct creates a hashtable that is faster to iterate over. That is why this specific type of hashtable might be valuable to you. Some other properties of a ArrayHashMap hashtable are:\n\nthe order of insertion is preserved, i.e. the order of the values that you find while iterating through this hashtable is actually the order in which these values were inserted in the hashtable.\nthe key-value pairs are stored sequentially, one after another.\n\nYou can create an ArrayHashMap object by using, once again, a helper function that chooses automatically for you a hash function implementation. This is the AutoArrayHashMap() function, which works very similarly to the AutoHashMap() function that we presented at Section 11.2.2.\nYou provide two data types to this function. The data type of the keys that will be used in this hashtable, and the data type of the values that will be stored in this hashtable.\nAn ArrayHashMap object have essentially the exact same methods from the HashMap struct. So you can insert new values into the hashtable by using the put() method, and you can look (or get) a value from the hashtable by using the get() method. But the remove() method is not available in this specific type of hashtable.\nIn order to delete values from the hashtable, you would use the same methods that you find in an ArrayList object, i.e. a dynamic array. I presented these methods at Section 11.1.4, which are the swapRemove() and orderedRemove() methods. These methods have the same meaning here, or, the same effect that they have in an ArrayList object.\nThis means that, with swapRemove() you remove the value from the hashtable, but you do not preserve the order in which the values were inserted into the structure. While orderedRemove() is able to retain the order in which these values were inserted.\nBut instead of providing an index as input to swapRemove() or orderedRemove(), like I described at Section 11.1.4, these methods here in an ArrayHashMap take a key as input, like the remove() method from a HashMap object. If you want to provide an index as input, instead of a key, you should use the swapRemoveAt() and orderedRemoveAt() methods.\n\nvar hash_table = AutoArrayHashMap(u32, u16)\n    .init(allocator);\ndefer hash_table.deinit();\n\n\n\n11.2.5 The StringHashMap hashtable\nOne thing that you will notice in the other two types of hashtables that I have presented over the last sections, is that neither of them accepts a slice data type in their keys. What this means is that you cannot use a slice value to represent a key in these types of hashtable.\nThe most obvious consequence of this, is that you cannot use strings as keys in these hashtables. But it is extremely common to use strings as keys in hashtables.\nTake this very simple Javascript code snippet as an example. We are creating a simple hashtable object named people. Then, we add a new entry to this hashtable, which is identified by the string 'Pedro'. This string is the key in this case, while the object containing different personal information such as age, height and city, is the value to be stored in the hashtable.\nvar people = new Object();\npeople['Pedro'] = {\n    'age': 25,\n    'height': 1.67,\n    'city': 'Belo Horizonte'\n};\nThis pattern of using strings as keys is very common in all sorts of situations. That is why the Zig Standard Library offers a specific type of hashtable for this purpose, which is created through the StringHashMap() function. This function creates a hashtable that uses strings as keys. The only input of this function is the data type of the values that will be stored into this hashtable.\nIn the example below, I’m creating a hashtable to store the ages of different people. Each key in this hashtable is represented by the name of each person, while the value stored in the hashtable is the age of this person identified by the key.\nThat is why I provide the u8 data type (which is the data type used by the age values) as input to this StringHashMap() function. As the result, it creates a hashtable that uses string values as keys, and, that stores u8 values in it. Notice that an allocator object is provided at the init() method of the resulting object from the StringHashMap() function.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var ages = std.StringHashMap(u8).init(allocator);\n    defer ages.deinit();\n\n    try ages.put(\"Pedro\", 25);\n    try ages.put(\"Matheus\", 21);\n    try ages.put(\"Abgail\", 42);\n\n    var it = ages.iterator();\n    while (it.next()) |kv| {\n        std.debug.print(\"Key: {s} | \", .{kv.key_ptr.*});\n        std.debug.print(\"Age: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n\nKey: Pedro | Age: 25\nKey: Abgail | Age: 42\nKey: Matheus | Age: 21\n\n\n11.2.6 The StringArrayHashMap hashtable\nThe Zig Standard Library also provides a type of hashtable that mix the cons and pros of the StringHashMap and ArrayHashMap together. That is, a hashtable that uses strings as keys, but also have the advantages from ArrayHashMap. In other words, you can have a hashtable that is fast to iterate over, that preserves insertion order, and also, that uses strings as keys.\nYou can create such type of hashtable by using the StringArrayHashMap() function. This function accepts a data type as input, which is the data type of the values that are going to be stored inside this hashtable, in the same style as the function presented at Section 11.2.5.\nYou can insert new values into this hashtable by using the same put() method that we have discussed at Section 11.2.5. And you can also get values from the hashtable by using the same get() method. Like its ArrayHashMap brother, to delete values from this specific type of hashtable, we also use the orderedRemove() and swapRemove() methods, with the same effects that I have described at Section 11.2.4.\nIf we take the code example that was exposed at Section 11.2.5, we can achieve the exact same result with StringArrayHashMap():\n\nvar ages = std.StringArrayHashMap(u8).init(allocator);",
     "crumbs": [
       "<span class='chapter-number'>11</span>  <span class='chapter-title'>Data Structures</span>"
     ]
@@ -954,7 +954,7 @@
     "href": "Chapters/10-stack-project.html#sec-comptime",
     "title": "12  Project 3 - Building a stack data structure",
     "section": "",
-    "text": "apply comptime on a function argument.\napply comptime on an object.\napply comptime on a block of expressions.\n\n\n12.1.1 Applying over a function argument\nWhen you apply the comptime keyword on a function argument, you are saying to the zig compiler that the value assigned to that particular function argument must be known at compile-time. We explained in details at Section 3.1.1 what exactly “value known at compile-time” means, so, in case you have doubts about this idea, come back to that section.\nNow let’s think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement to that particular function argument. If the programmer accidentally tries to give a value to this function argument that is not known at compile time, the zig compiler will notice this problem, and as a consequence, it will raise a compilation error saying that it cannot compile your program. Because you are providing a value that is “runtime known” to a function argument that must be “compile-time known”.\nTake a look at this very simple example below, where we define a twice() function, that simply doubles the input value named num. Notice that we use the comptime keyword before the name of the function argument. This keyword is marking the function argument num as a “comptime argument”.\nThat is a function argument whose value must be compile-time known. This is why the expression twice(5678) is valid, and no compilation errors are raised. Because the value 5678 is compile-time known, so this is the expected behaviour for this function.\n\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n\n1/1 file1054863994c6f.test.test comptime...OKAll 1\n  1 tests passed.\n\n\nBut what if we provide a number that is not compile-time known to this function? For example, we might provide a different input value to this function depending on the target OS of our compilation process. The code example below demonstrates such case.\nBecause the value of the object n is determined at runtime, we cannot provide this object as input to the twice() function. The zig compiler will not allow it, because we marked the num argument as a “comptime argument”. That is why the zig compiler raises the compile-time error exposed below:\n\nconst builtin = @import(\"builtin\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    var n: u32 = undefined;\n    if (builtin.target.os.tag == .windows) {\n        n = 1234;\n    } else {\n        n = 5678;\n    }\n    _ = twice(n);\n}\n\nt.zig:12:16: error: runtime-known argument passed to comptime parameter \nComptime arguments are frequently used on functions that return some sort of generic structure. In fact, comptime is the essence (or the basis) to make generics in Zig. We are going to talk more about generics at Section 12.2.\nFor now, let’s take a look at this code example from Seguin (2024). You can see that this IntArray() function have one argument named length. This argument is marked as comptime, and receives a value of type usize as input. So the value given to this argument must be compile-time known. We can also see that this function returns an array of i64 values as output.\n\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n\nNow, the key component of this function is the length argument. This argument is used to determine the size of the array that is produced by the function. Let’s think about the consequences of that. If the size of the array is dependent on the value assigned to the length argument, this means that the data type of the output of the function depends on the value of this length argument.\nLet this statement sink for a bit in your mind. As I described at Section 1.2.2, Zig is a strongly-typed language, especially on function declarations. So every time we write a function in Zig, we have to annotate the data type of the value returned by the function. But how can we do that, if this data type depends on the value given to the argument of the function?\nThink about this for a second. If length is equal to 3 for example, then, the return type of the function is [3]i64. But if length is equal to 40, then, the return type becomes [40]i64. At this point the zig compiler would be confused, and raise a compilation error, saying something like this:\n\nHey! You have annotated that this function should return a [3]i64 value, but I got a [40]i64 value instead! This doesn’t look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when the type keyword comes in. This type keyword is basically saying to the zig compiler that this function will return some data type as output, but it doesn’t know yet what exactly data type that is. We will talk more about this at Section 12.2.\n\n\n12.1.2 Applying over an expression\nWhen you apply the comptime keyword over an expression, then, it is guaranteed that the zig compiler will execute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time (e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the zig compiler will raise a compilation error.\nTake this example from the official documentation of Zig (Zig Software Foundation 2024). We are executing the same fibonacci() function both at runtime, and, at compile-time. The function is by default executed at runtime, but because we use the comptime keyword at the second “try expression”, this expression is executed at compile-time.\nThis might be a bit confusing for some people. Yes! When I say that this expression is executed at compile-time, I mean that this expression is compiled and executed while the zig compiler is compiling your Zig source code.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n\n1/1 file10548bb87337.test.fibonacci...OKAll 1 test\n  ts passed.\n\n\nA lot of your Zig source code might be potentially executed at compile-time, because the zig compiler can figure it out the output of some expressions. Especially if these expressions depends only at compile-time known values. We have talked about this at Section 3.1.1.\nBut when you use the comptime keyword on an expression, there is no “it might be executed at compile-time” anymore. With the comptime keyword you are ordering the zig compiler to execute this expression at compile-time. You are imposing this rule, it is guaranteed that the compiler will always execute it at compile-time. Or, at least, the compiler will try to execute it. If the compiler cannot execute the expression for whatever reason, the compiler will raise a compilation error.\n\n\n12.1.3 Applying over a block\nBlocks were described at Section 1.7. When you apply the comptime keyword over a block of expressions, you get essentially the same effect when you apply this keyword to a single expression. That is, the entire block of expressions is executed at compile-time by the zig compiler.\nIn the example below, we mark the block labeled of blk as a comptime block, and, therefore, the expressions inside this block are executed at compile-time.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n\n1/1 file105482dc0b880.test.fibonacci in a block...\n  .OKAll 1 tests passed.",
+    "text": "apply comptime on a function argument.\napply comptime on an object.\napply comptime on a block of expressions.\n\n\n12.1.1 Applying over a function argument\nWhen you apply the comptime keyword on a function argument, you are saying to the zig compiler that the value assigned to that particular function argument must be known at compile-time. We explained in details at Section 3.1.1 what exactly “value known at compile-time” means, so, in case you have doubts about this idea, come back to that section.\nNow let’s think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement to that particular function argument. If the programmer accidentally tries to give a value to this function argument that is not known at compile time, the zig compiler will notice this problem, and as a consequence, it will raise a compilation error saying that it cannot compile your program. Because you are providing a value that is “runtime known” to a function argument that must be “compile-time known”.\nTake a look at this very simple example below, where we define a twice() function, that simply doubles the input value named num. Notice that we use the comptime keyword before the name of the function argument. This keyword is marking the function argument num as a “comptime argument”.\nThat is a function argument whose value must be compile-time known. This is why the expression twice(5678) is valid, and no compilation errors are raised. Because the value 5678 is compile-time known, so this is the expected behaviour for this function.\n\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n\n1/1 file1105a40478a9d.test.test comptime...OKAll 1\n  1 tests passed.\n\n\nBut what if we provide a number that is not compile-time known to this function? For example, we might provide a different input value to this function depending on the target OS of our compilation process. The code example below demonstrates such case.\nBecause the value of the object n is determined at runtime, we cannot provide this object as input to the twice() function. The zig compiler will not allow it, because we marked the num argument as a “comptime argument”. That is why the zig compiler raises the compile-time error exposed below:\n\nconst builtin = @import(\"builtin\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    var n: u32 = undefined;\n    if (builtin.target.os.tag == .windows) {\n        n = 1234;\n    } else {\n        n = 5678;\n    }\n    _ = twice(n);\n}\n\nt.zig:12:16: error: runtime-known argument passed to comptime parameter \nComptime arguments are frequently used on functions that return some sort of generic structure. In fact, comptime is the essence (or the basis) to make generics in Zig. We are going to talk more about generics at Section 12.2.\nFor now, let’s take a look at this code example from Seguin (2024). You can see that this IntArray() function have one argument named length. This argument is marked as comptime, and receives a value of type usize as input. So the value given to this argument must be compile-time known. We can also see that this function returns an array of i64 values as output.\n\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n\nNow, the key component of this function is the length argument. This argument is used to determine the size of the array that is produced by the function. Let’s think about the consequences of that. If the size of the array is dependent on the value assigned to the length argument, this means that the data type of the output of the function depends on the value of this length argument.\nLet this statement sink for a bit in your mind. As I described at Section 1.2.2, Zig is a strongly-typed language, especially on function declarations. So every time we write a function in Zig, we have to annotate the data type of the value returned by the function. But how can we do that, if this data type depends on the value given to the argument of the function?\nThink about this for a second. If length is equal to 3 for example, then, the return type of the function is [3]i64. But if length is equal to 40, then, the return type becomes [40]i64. At this point the zig compiler would be confused, and raise a compilation error, saying something like this:\n\nHey! You have annotated that this function should return a [3]i64 value, but I got a [40]i64 value instead! This doesn’t look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when the type keyword comes in. This type keyword is basically saying to the zig compiler that this function will return some data type as output, but it doesn’t know yet what exactly data type that is. We will talk more about this at Section 12.2.\n\n\n12.1.2 Applying over an expression\nWhen you apply the comptime keyword over an expression, then, it is guaranteed that the zig compiler will execute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time (e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the zig compiler will raise a compilation error.\nTake this example from the official documentation of Zig (Zig Software Foundation 2024). We are executing the same fibonacci() function both at runtime, and, at compile-time. The function is by default executed at runtime, but because we use the comptime keyword at the second “try expression”, this expression is executed at compile-time.\nThis might be a bit confusing for some people. Yes! When I say that this expression is executed at compile-time, I mean that this expression is compiled and executed while the zig compiler is compiling your Zig source code.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n\n1/1 file1105a31c0f24f.test.fibonacci...OKAll 1 tes\n  sts passed.\n\n\nA lot of your Zig source code might be potentially executed at compile-time, because the zig compiler can figure it out the output of some expressions. Especially if these expressions depends only at compile-time known values. We have talked about this at Section 3.1.1.\nBut when you use the comptime keyword on an expression, there is no “it might be executed at compile-time” anymore. With the comptime keyword you are ordering the zig compiler to execute this expression at compile-time. You are imposing this rule, it is guaranteed that the compiler will always execute it at compile-time. Or, at least, the compiler will try to execute it. If the compiler cannot execute the expression for whatever reason, the compiler will raise a compilation error.\n\n\n12.1.3 Applying over a block\nBlocks were described at Section 1.7. When you apply the comptime keyword over a block of expressions, you get essentially the same effect when you apply this keyword to a single expression. That is, the entire block of expressions is executed at compile-time by the zig compiler.\nIn the example below, we mark the block labeled of blk as a comptime block, and, therefore, the expressions inside this block are executed at compile-time.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n\n1/1 file1105a37ca2b0d.test.fibonacci in a block...\n  .OKAll 1 tests passed.",
     "crumbs": [
       "<span class='chapter-number'>12</span>  <span class='chapter-title'>Project 3 - Building a stack data structure</span>"
     ]
@@ -964,7 +964,7 @@
     "href": "Chapters/10-stack-project.html#sec-generics",
     "title": "12  Project 3 - Building a stack data structure",
     "section": "12.2 Introducing Generics",
-    "text": "12.2 Introducing Generics\nFirst of all, what is a generic? Generic is the idea to allow a type (f64, u8, u32, bool, and also, user-defined types, like the User struct that we defined at Section 2.3) to be a parameter to methods, classes and interfaces (Geeks for Geeks 2024). In other words, a “generic” is a class (or a method) that can work with multiple data types.\nFor example, in Java, generics are created through the operator &lt;&gt;. With this operator, a Java class is capable of receiving a data type as input, and therefore, the class can fit its features according to this input data type. As another example, generics in C++ are supported through the concept of templates. Class templates in C++ are generics.\nIn Zig, generics are implemented through comptime. The comptime keyword allows us to collect a data type at compile time, and pass this data type as input to a piece of code.\n\n12.2.1 A generic function\nTake the max() function exposed below as a first example. This function is essentially a “generic function”. In this function, we have a comptime function argument named T. Notice that this T argument have a data type of type. Weird right? This type keyword is the “father of all types”, or, “the type of types” in Zig.\nBecause we have used this type keyword in the T argument, we are telling the zig compiler that this T argument will receive some data type as input. Also notice the use of the comptime keyword in this argument. As I described at Section 12.1, every time you use this keyword in a function argument, this means that the value of this argument must be known at compile-time. This makes sense, right? Because there is no data type that is not known at compile-time.\nThink about this. Every data type that you will ever write is always known at compile-time. Especially because data types are an essential information for the compiler to actually compile your source code. Having this in mind, makes sense to mark this argument as a comptime argument.\n\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a &gt; b) a else b;\n}\n\nAll 0 tests passed.\n\n\nAlso notice that the value of the T argument is actually used to define the data type of the other arguments in the function, a and b, and also at the return type annotation of the function. That is, the data type of these arguments (a and b), and, the return data type of the function itself, are determined by the input value given to the T argument.\nAs a result, we have a generic function that works with different data types. For example, I can provide u8 values to this max() function, and it will work as expected. But if I provide f64 values instead, it will also work as expected. Without a generic function, I would have to write a different max() function for each one of the data types that I wanted to use. This generic function provides a very useful shortcut for us.\n\nconst std = @import(\"std\");\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a &gt; b) a else b;\n}\ntest \"test max\" {\n    const n1 = max(u8, 4, 10);\n    std.debug.print(\"Max n1: {d}\\n\", .{n1});\n    const n2 = max(f64, 89.24, 64.001);\n    std.debug.print(\"Max n2: {d}\\n\", .{n2});\n}\n\n1/1 file105482071daf3.test.test max...Max n1: 10Ma\n  ax n2: 89.24OKAll 1 tests passed.\n\n\nMax n1: 10\nMax n2: 89.24\n\n\n12.2.2 A generic data structure\nEvery data structure that you find in the Zig Standard Library (e.g. ArrayList, HashMap, etc.) is essentially a generic data structure. These data structures are generic in the sense that they work with any data type you want. You just say which is the data type of the values that are going to be stored in this data structure, and they just work as expected.\nA generic data structure in Zig is how you replicate a generic class from Java, or, a class template from C++. But you may quest yourself: how do we build a generic data structure in Zig?\nThe basic idea is to write a generic function that creates the data structure definition for the specific type we want. In other words, this generic function behaves as a “factory of data structures”. The generic function outputs the struct definition that defines this data structure for a specific data type.\nTo create such function, we need to add a comptime argument to this function that receives a data type as input. We already learned how to do this at the previous section (Section 12.2.1). I think the best way to demonstrate how to create a generic data structure is to actually write one. This where we go into our next small project in this book. This one is a very small project, which is to write a generic stack data structure.",
+    "text": "12.2 Introducing Generics\nFirst of all, what is a generic? Generic is the idea to allow a type (f64, u8, u32, bool, and also, user-defined types, like the User struct that we defined at Section 2.3) to be a parameter to methods, classes and interfaces (Geeks for Geeks 2024). In other words, a “generic” is a class (or a method) that can work with multiple data types.\nFor example, in Java, generics are created through the operator &lt;&gt;. With this operator, a Java class is capable of receiving a data type as input, and therefore, the class can fit its features according to this input data type. As another example, generics in C++ are supported through the concept of templates. Class templates in C++ are generics.\nIn Zig, generics are implemented through comptime. The comptime keyword allows us to collect a data type at compile time, and pass this data type as input to a piece of code.\n\n12.2.1 A generic function\nTake the max() function exposed below as a first example. This function is essentially a “generic function”. In this function, we have a comptime function argument named T. Notice that this T argument have a data type of type. Weird right? This type keyword is the “father of all types”, or, “the type of types” in Zig.\nBecause we have used this type keyword in the T argument, we are telling the zig compiler that this T argument will receive some data type as input. Also notice the use of the comptime keyword in this argument. As I described at Section 12.1, every time you use this keyword in a function argument, this means that the value of this argument must be known at compile-time. This makes sense, right? Because there is no data type that is not known at compile-time.\nThink about this. Every data type that you will ever write is always known at compile-time. Especially because data types are an essential information for the compiler to actually compile your source code. Having this in mind, makes sense to mark this argument as a comptime argument.\n\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a &gt; b) a else b;\n}\n\nAlso notice that the value of the T argument is actually used to define the data type of the other arguments in the function, a and b, and also at the return type annotation of the function. That is, the data type of these arguments (a and b), and, the return data type of the function itself, are determined by the input value given to the T argument.\nAs a result, we have a generic function that works with different data types. For example, I can provide u8 values to this max() function, and it will work as expected. But if I provide f64 values instead, it will also work as expected. Without a generic function, I would have to write a different max() function for each one of the data types that I wanted to use. This generic function provides a very useful shortcut for us.\n\nconst std = @import(\"std\");\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a &gt; b) a else b;\n}\ntest \"test max\" {\n    const n1 = max(u8, 4, 10);\n    std.debug.print(\"Max n1: {d}\\n\", .{n1});\n    const n2 = max(f64, 89.24, 64.001);\n    std.debug.print(\"Max n2: {d}\\n\", .{n2});\n}\n\nMax n1: 10\nMax n2: 89.24\n\n\n12.2.2 A generic data structure\nEvery data structure that you find in the Zig Standard Library (e.g. ArrayList, HashMap, etc.) is essentially a generic data structure. These data structures are generic in the sense that they work with any data type you want. You just say which is the data type of the values that are going to be stored in this data structure, and they just work as expected.\nA generic data structure in Zig is how you replicate a generic class from Java, or, a class template from C++. But you may quest yourself: how do we build a generic data structure in Zig?\nThe basic idea is to write a generic function that creates the data structure definition for the specific type we want. In other words, this generic function behaves as a “factory of data structures”. The generic function outputs the struct definition that defines this data structure for a specific data type.\nTo create such function, we need to add a comptime argument to this function that receives a data type as input. We already learned how to do this at the previous section (Section 12.2.1). I think the best way to demonstrate how to create a generic data structure is to actually write one. This where we go into our next small project in this book. This one is a very small project, which is to write a generic stack data structure.",
     "crumbs": [
       "<span class='chapter-number'>12</span>  <span class='chapter-title'>Project 3 - Building a stack data structure</span>"
     ]

From 1c02ee80c51c47f1cba78bdb231bd8d7e24bbac7 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Wed, 4 Dec 2024 19:46:22 -0300
Subject: [PATCH 013/151] Fix duplicate code

---
 Chapters/03-unittests.qmd | 9 ---------
 1 file changed, 9 deletions(-)

diff --git a/Chapters/03-unittests.qmd b/Chapters/03-unittests.qmd
index b694b779..56cfb051 100644
--- a/Chapters/03-unittests.qmd
+++ b/Chapters/03-unittests.qmd
@@ -230,10 +230,6 @@ test "testing error" {
 }
 ```
 
-```
-1/1 oom.test.testing error... OK
-All 1 tests passed.
-```
 
 
 
@@ -301,11 +297,6 @@ test "arrays are equal?" {
 }
 ```
 
-```
-1/1 oom.test.arrays are equal?... OK
-All 1 tests passed.
-```
-
 
 At last, you might also want to use the `expectEqualStrings()` function.
 As the name suggests, you can use this function to test if two strings

From 683a9f5be4b1d4aa99401fcf2c6ba29be0441710 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Thu, 5 Dec 2024 19:24:35 -0300
Subject: [PATCH 014/151] Update index in while loop

---
 ZigExamples/image_filter/src/image_filter.zig | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ZigExamples/image_filter/src/image_filter.zig b/ZigExamples/image_filter/src/image_filter.zig
index 95a2575e..63a9e283 100644
--- a/ZigExamples/image_filter/src/image_filter.zig
+++ b/ZigExamples/image_filter/src/image_filter.zig
@@ -103,7 +103,7 @@ fn apply_image_filter(image_data: *ImageData) !void {
     const green_factor: f16 = 0.7152;
     const blue_factor: f16 = 0.0722;
     var index: u64 = 0;
-    while (index <= (len - 4)) : (index += 4) {
+    while (index < len) : (index += 4) {
         const rf: f16 = @floatFromInt(image_data.data[index]);
         const gf: f16 = @floatFromInt(image_data.data[index + 1]);
         const bf: f16 = @floatFromInt(image_data.data[index + 2]);

From f7f2dd68f5ee2e514794a5c7e91d7057a5b02307 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Thu, 5 Dec 2024 19:26:50 -0300
Subject: [PATCH 015/151] Update index in while loop

---
 Chapters/13-image-filter.qmd                  |  2 +-
 .../03-unittests/execute-results/html.json    |  8 ++-
 .../13-image-filter/execute-results/html.json |  4 +-
 docs/Chapters/03-unittests.html               | 60 +++++++++----------
 docs/Chapters/13-image-filter.html            |  2 +-
 docs/index.html                               |  4 +-
 docs/search.json                              |  8 +--
 7 files changed, 43 insertions(+), 45 deletions(-)

diff --git a/Chapters/13-image-filter.qmd b/Chapters/13-image-filter.qmd
index 13037aab..66e83e96 100644
--- a/Chapters/13-image-filter.qmd
+++ b/Chapters/13-image-filter.qmd
@@ -522,7 +522,7 @@ fn apply_image_filter(buffer:[]u8) !void {
     const green_factor: f16 = 0.7152;
     const blue_factor: f16 = 0.0722;
     var index: u64 = 0;
-    while (index <= (len - 4)) : (index += 4) {
+    while (index < len) : (index += 4) {
         const rf: f16 = @floatFromInt(buffer[index]);
         const gf: f16 = @floatFromInt(buffer[index + 1]);
         const bf: f16 = @floatFromInt(buffer[index + 2]);
diff --git a/_freeze/Chapters/03-unittests/execute-results/html.json b/_freeze/Chapters/03-unittests/execute-results/html.json
index dbaf31eb..73102f4a 100644
--- a/_freeze/Chapters/03-unittests/execute-results/html.json
+++ b/_freeze/Chapters/03-unittests/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "8380b8e0995a3f1298d8bf31e661dba2",
+  "hash": "28d3cb0fae2775c98b5945221b3f555c",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Unit tests {#sec-unittests}\n\nIn this chapter, I want to dive in on how unit tests are done in\nZig. We are going to talk about what is the testing workflow in Zig, and\nalso, about the `test` command from the `zig` compiler.\n\n\n## Introducing the `test` block\n\nIn Zig, unit tests are written inside a `test` declaration, or, how I prefer to call it, inside a `test` block.\nEvery `test` block is written by using the keyword `test`.\nYou can optionally use a string literal to write a label, which is responsible for identifying\nthe specific group of unit tests that you are writing inside this specific `test` block.\n\nIn the example below, we are testing if the sum of two objects (`a` and `b`)\nis equal to 4. The `expect()` function from the Zig Standard Library\nis a function that receives a logical test as input. If this logical test\nresults in `true`, then, the test passes. But if it results\nin `false`, then, the test fails.\n\nYou can write any Zig code you want inside a `test` block.\nPart of this code might be some necessary commands to setup your testing\nenvironment, or just initializing some objects that you need to use\nin your unit tests.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest \"testing simple sum\" {\n    const a: u8 = 2;\n    const b: u8 = 2;\n    try expect((a + b) == 4);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file103bc24525048.test.testing simple sum...OK\n  KAll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\nYou can have multiple `test` blocks written on the same Zig module.\nAlso, you can mix `test` blocks with your source code, with no problems\nor consequences. If you mix `test` blocks with your normal source code,\nwhen you execute the `build`, `build-exe`, `build-obj` or `build-lib` commands from the\n`zig` compiler that we exposed at @sec-compile-code, these `test` blocks are automatically\nignored by the compiler.\n\nIn other words, the `zig` compiler builds and execute your unit tests only\nwhen you ask it to. By default, the compiler always ignore `test`\nblocks written in your Zig modules. The compiler normally checks only if\nthere are any syntax errors in these `test` blocks.\n\nIf you take a look at the source code for most of the files present in the\nZig Standard Library[^zig-std-lib], you can see that the `test` blocks\nare written together with the normal source code of the library.\nYou can see this for example, at the [`array_list` module](https://github.com/ziglang/zig/blob/master/lib/std/array_list.zig)[^zig-array].\nSo, the standard that the Zig developers decided to adopt\nis to keep their unit tests together with the source code\nof the functionality that they are testing.\n\nEach programmer might have a different opinion on this.\nSome of them might prefer to keep unit tests separate from the actual\nsource code of their application. If that is your case, you can\nsimply create a separate `tests` folder in your project, and\nstart writing Zig modules that contains only unit tests (as you would normally do\non a Python project with `pytest`, for example), and everything will work fine.\nIt boils down to which is your preference here.\n\n[^zig-std-lib]: <https://github.com/ziglang/zig/tree/master/lib/std>\n[^zig-array]: <https://github.com/ziglang/zig/blob/master/lib/std/array_list.zig>\n\n\n## How to run your tests\n\nIf the `zig` compiler ignores any `test` block by default, how can\nyou compile and run your unit tests? The answer is the `test` command from\nthe `zig` compiler. By running the `zig test` command, the compiler will\nfind every instance of a `test` block in your Zig modules, and, it will\ncompile and run the unit tests that you wrote.\n\n\n```bash\nzig test simple_sum.zig\n```\n\n```\n1/1 simple_sum.test.testing simple sum... OK\nAll 1 tests passed.\n```\n\n\n## Testing memory allocations\n\nOne of the advantages of Zig is that it offers great tools\nthat help us, programmers, to avoid (but also detect) memory problems, such as\nmemory leaks and double-frees. The `defer` keyword\nis especially helpful in this regard.\n\nWhen developing your source code, you, the programmer, is responsible for making\nsure that your code do not produce such problems. However,\nyou can also use a special type of an allocator object in Zig\nthat is capable of automatically detecting such problems for you.\nThis is the `std.testing.allocator` object.\nThis allocator object offers some basic memory safety detection\nfeatures, which are capable of detecting memory leaks.\n\nAs we described at @sec-heap, to allocate memory on the heap, you need\nto use an allocator object, and your functions that use these objects to allocate memory\non the heap, should receive an allocator object as one of its inputs.\nEvery memory on the heap that you allocate using these allocator objects,\nmust also be freed using this same allocator object.\n\nSo, if you want to test the memory allocations performed by your functions,\nand make sure that you don't have problems in these allocations, you can simply\nwrite unit tests for these functions, where you provide the\n`std.testing.allocator` object as input to these functions.\n\nLook at the example below, where I'm defining a function that clearly causes\na memory leak. Because we allocate memory, but, at the same time,\nwe do not free this allocated memory at any point. So, when the function\nreturns, we lose the reference to the `buffer` object, which contains\nthe allocated memory, and, as a result, we can no longer free this memory.\n\nNotice that, inside a `test` block I execute this function with\nthe `std.testing.allocator`. The allocator object was capable\nof looking deeper in our program, and detecting the memory leak. As a result,\nthis allocator object returns an error message of \"memory leaked\", and also,\na stack trace showing the exact point where the memory was leaked.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nfn some_memory_leak(allocator: Allocator) !void {\n    const buffer = try allocator.alloc(u32, 10);\n    _ = buffer;\n    // Return without freeing the\n    // allocated memory\n}\n\ntest \"memory leak\" {\n    const allocator = std.testing.allocator;\n    try some_memory_leak(allocator);\n}\n```\n:::\n\n\n\n\n```\nTest [1/1] leak_memory.test.memory leak...\n    [gpa] (err): memory address 0x7c1fddf39000 leaked: \n./ZigExamples/debugging/leak_memory.zig:4:39: 0x10395f2\n    const buffer = try allocator.alloc(u32, 10);\n                                      ^\n./ZigExamples/debugging/leak_memory.zig:12:25: 0x10398ea\n    try some_memory_leak(allocator);\n\n... more stack trace\n```\n\n\n## Testing errors\n\nOne common style of unit tests are those that look for\nspecific errors in your functions. In other words, you write\na unit test that tries to assert if a specific function call\nreturns any error, or a specific type of error.\n\nIn C++ you would normally write this style of unit tests using, for example,\nthe functions `REQUIRE_THROWS()` or `CHECK_THROWS()` from the [`Catch2` test framework](https://github.com/catchorg/Catch2/tree/devel)[^catch2].\nIn the case of a Python project, you would probably use the\n[`raises()` function from `pytest`](https://docs.pytest.org/en/7.1.x/reference/reference.html#pytest-raises)[^pytest].\nWhile in Rust, you would probably use `assert_eq!()` in conjunction with `Err()`.\n\n[^pytest]: <https://docs.pytest.org/en/7.1.x/reference/reference.html#pytest-raises>\n[^catch2]: <https://github.com/catchorg/Catch2/tree/devel>\n\n\nBut in Zig, we use the `expectError()` function, from the `std.testing` module.\nWith this function, you can test if a specific function call returns the exact\ntype of error that you expect it to return. To use this function, you first write\n`try expectError()`. Then, on the first argument, you provide the type of error that you\nare expecting from the function call. Then, on the second argument, you write\nthe function call that you expect to fail.\n\nThe code example below demonstrates such type of unit test in Zig.\nNotice that, inside the function `alloc_error()` we are allocating\n100 bytes of memory, or, an array of 100 elements, for the object `ibuffer`. However,\nin the `test` block, we are using the `FixedBufferAllocator()`\nallocator object, which is limited to 10 bytes of space, because\nthe object `buffer`, which we provided to the allocator object,\nhave only 10 bytes of space.\n\nThat is why, the `alloc_error()` function raises an `OutOfMemory` error\non this case.\nBecause this function is trying to allocate more space than the allocator\nobject allows.\nSo, in essence, we are testing for a specific type of error,\nwhich is `OutOfMemory`. If the `alloc_error()` function returns any other type of error,\nthen, the `expectError()` function would make the entire test fail.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst expectError = std.testing.expectError;\nfn alloc_error(allocator: Allocator) !void {\n    var ibuffer = try allocator.alloc(u8, 100);\n    defer allocator.free(ibuffer);\n    ibuffer[0] = 2;\n}\n\ntest \"testing error\" {\n    var buffer: [10]u8 = undefined;\n    var fba = std.heap.FixedBufferAllocator.init(&buffer);\n    const allocator = fba.allocator();\n    try expectError(error.OutOfMemory, alloc_error(allocator));\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file103bc545495c8.test.testing error...OKAll 1\n  1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n```\n1/1 oom.test.testing error... OK\nAll 1 tests passed.\n```\n\n\n\n## Testing simple equalities\n\nIn Zig, there are some different ways you can test for an equality.\nYou already saw that we can use `expect()` with the logical operator `==`\nto essentially reproduce an equality test. But we also have\nsome other helper functions that you should know about, especially\n`expectEqual()`, `expectEqualSlices()` and `expectEqualStrings()`.\n\n\nThe `expectEqual()` function, as the name suggests, is a classic\ntest equality function. It receives two objects as input. The first\nobject is the value that you expect to be in the second object.\nWhile second object is the object you have, or, the object that your application\nproduced as result. So, with `expectEqual()` you are essentially\ntesting if the values stored inside these two objects\nare equal or not.\n\nYou can see in the example below that, the test performed by\n`expectEqual()` failed. Because the objects `v1` and `v2` contain\ndifferent values in them.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"values are equal?\" {\n    const v1 = 15;\n    const v2 = 18;\n    try std.testing.expectEqual(v1, v2);\n}\n```\n:::\n\n\n\n\n```\n1/1 ve.test.values are equal?...\n    expected 15, found 18\n    FAIL (TestExpectedEqual)\nve.zig:5:5: test.values are equal? (test)\n    try std.testing.expectEqual(v1, v2);\n    ^\n0 passed; 0 skipped; 1 failed.\n```\n\n\nAlthough useful, the `expectEqual()` function does not work with arrays.\nFor testing if two arrays are equal, you should use the `expectEqualSlices()`\nfunction instead. This function have three arguments. First, you provide\nthe data type contained in both arrays that you are trying to compare.\nWhile the second and third arguments corresponds to the array objects that you want to compare.\n\nIn the example below, we are using this function to test if two array\nobjects (`array1` and `array2`) are equal or not. Since they\nare in fact equal, the unit test passed with no errors.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"arrays are equal?\" {\n    const array1 = [3]u32{1, 2, 3};\n    const array2 = [3]u32{1, 2, 3};\n    try std.testing.expectEqualSlices(\n        u32, &array1, &array2\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file103bc78cf09de.test.arrays are equal?...OKA\n  All 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n```\n1/1 oom.test.arrays are equal?... OK\nAll 1 tests passed.\n```\n\n\nAt last, you might also want to use the `expectEqualStrings()` function.\nAs the name suggests, you can use this function to test if two strings\nare equal or not. Just provide the two string objects that you want to compare,\nas inputs to the function.\n\nIf the function finds any existing differences between the two strings,\nthen, the function will raise an error, and also, print an error message\nthat shows the exact difference between the two string objects provided,\nas the example below demonstrates:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"strings are equal?\" {\n    const str1 = \"hello, world!\";\n    const str2 = \"Hello, world!\";\n    try std.testing.expectEqualStrings(\n        str1, str2\n    );\n}\n```\n:::\n\n\n\n\n```\n1/1 t.test.strings are equal?... \n====== expected this output: =========\nhello, world!␃\n======== instead found this: =========\nHello, world!␃\n======================================\nFirst difference occurs on line 1:\nexpected:\nhello, world!\n^ ('\\x68')\nfound:\nHello, world!\n^ ('\\x48')\n```\n\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Unit tests {#sec-unittests}\n\nIn this chapter, I want to dive in on how unit tests are done in\nZig. We are going to talk about what is the testing workflow in Zig, and\nalso, about the `test` command from the `zig` compiler.\n\n\n## Introducing the `test` block\n\nIn Zig, unit tests are written inside a `test` declaration, or, how I prefer to call it, inside a `test` block.\nEvery `test` block is written by using the keyword `test`.\nYou can optionally use a string literal to write a label, which is responsible for identifying\nthe specific group of unit tests that you are writing inside this specific `test` block.\n\nIn the example below, we are testing if the sum of two objects (`a` and `b`)\nis equal to 4. The `expect()` function from the Zig Standard Library\nis a function that receives a logical test as input. If this logical test\nresults in `true`, then, the test passes. But if it results\nin `false`, then, the test fails.\n\nYou can write any Zig code you want inside a `test` block.\nPart of this code might be some necessary commands to setup your testing\nenvironment, or just initializing some objects that you need to use\nin your unit tests.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest \"testing simple sum\" {\n    const a: u8 = 2;\n    const b: u8 = 2;\n    try expect((a + b) == 4);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file153713a3190e.test.testing simple sum...OKA\n  All 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\nYou can have multiple `test` blocks written on the same Zig module.\nAlso, you can mix `test` blocks with your source code, with no problems\nor consequences. If you mix `test` blocks with your normal source code,\nwhen you execute the `build`, `build-exe`, `build-obj` or `build-lib` commands from the\n`zig` compiler that we exposed at @sec-compile-code, these `test` blocks are automatically\nignored by the compiler.\n\nIn other words, the `zig` compiler builds and execute your unit tests only\nwhen you ask it to. By default, the compiler always ignore `test`\nblocks written in your Zig modules. The compiler normally checks only if\nthere are any syntax errors in these `test` blocks.\n\nIf you take a look at the source code for most of the files present in the\nZig Standard Library[^zig-std-lib], you can see that the `test` blocks\nare written together with the normal source code of the library.\nYou can see this for example, at the [`array_list` module](https://github.com/ziglang/zig/blob/master/lib/std/array_list.zig)[^zig-array].\nSo, the standard that the Zig developers decided to adopt\nis to keep their unit tests together with the source code\nof the functionality that they are testing.\n\nEach programmer might have a different opinion on this.\nSome of them might prefer to keep unit tests separate from the actual\nsource code of their application. If that is your case, you can\nsimply create a separate `tests` folder in your project, and\nstart writing Zig modules that contains only unit tests (as you would normally do\non a Python project with `pytest`, for example), and everything will work fine.\nIt boils down to which is your preference here.\n\n[^zig-std-lib]: <https://github.com/ziglang/zig/tree/master/lib/std>\n[^zig-array]: <https://github.com/ziglang/zig/blob/master/lib/std/array_list.zig>\n\n\n## How to run your tests\n\nIf the `zig` compiler ignores any `test` block by default, how can\nyou compile and run your unit tests? The answer is the `test` command from\nthe `zig` compiler. By running the `zig test` command, the compiler will\nfind every instance of a `test` block in your Zig modules, and, it will\ncompile and run the unit tests that you wrote.\n\n\n```bash\nzig test simple_sum.zig\n```\n\n```\n1/1 simple_sum.test.testing simple sum... OK\nAll 1 tests passed.\n```\n\n\n## Testing memory allocations\n\nOne of the advantages of Zig is that it offers great tools\nthat help us, programmers, to avoid (but also detect) memory problems, such as\nmemory leaks and double-frees. The `defer` keyword\nis especially helpful in this regard.\n\nWhen developing your source code, you, the programmer, is responsible for making\nsure that your code do not produce such problems. However,\nyou can also use a special type of an allocator object in Zig\nthat is capable of automatically detecting such problems for you.\nThis is the `std.testing.allocator` object.\nThis allocator object offers some basic memory safety detection\nfeatures, which are capable of detecting memory leaks.\n\nAs we described at @sec-heap, to allocate memory on the heap, you need\nto use an allocator object, and your functions that use these objects to allocate memory\non the heap, should receive an allocator object as one of its inputs.\nEvery memory on the heap that you allocate using these allocator objects,\nmust also be freed using this same allocator object.\n\nSo, if you want to test the memory allocations performed by your functions,\nand make sure that you don't have problems in these allocations, you can simply\nwrite unit tests for these functions, where you provide the\n`std.testing.allocator` object as input to these functions.\n\nLook at the example below, where I'm defining a function that clearly causes\na memory leak. Because we allocate memory, but, at the same time,\nwe do not free this allocated memory at any point. So, when the function\nreturns, we lose the reference to the `buffer` object, which contains\nthe allocated memory, and, as a result, we can no longer free this memory.\n\nNotice that, inside a `test` block I execute this function with\nthe `std.testing.allocator`. The allocator object was capable\nof looking deeper in our program, and detecting the memory leak. As a result,\nthis allocator object returns an error message of \"memory leaked\", and also,\na stack trace showing the exact point where the memory was leaked.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nfn some_memory_leak(allocator: Allocator) !void {\n    const buffer = try allocator.alloc(u32, 10);\n    _ = buffer;\n    // Return without freeing the\n    // allocated memory\n}\n\ntest \"memory leak\" {\n    const allocator = std.testing.allocator;\n    try some_memory_leak(allocator);\n}\n```\n:::\n\n\n\n\n```\nTest [1/1] leak_memory.test.memory leak...\n    [gpa] (err): memory address 0x7c1fddf39000 leaked: \n./ZigExamples/debugging/leak_memory.zig:4:39: 0x10395f2\n    const buffer = try allocator.alloc(u32, 10);\n                                      ^\n./ZigExamples/debugging/leak_memory.zig:12:25: 0x10398ea\n    try some_memory_leak(allocator);\n\n... more stack trace\n```\n\n\n## Testing errors\n\nOne common style of unit tests are those that look for\nspecific errors in your functions. In other words, you write\na unit test that tries to assert if a specific function call\nreturns any error, or a specific type of error.\n\nIn C++ you would normally write this style of unit tests using, for example,\nthe functions `REQUIRE_THROWS()` or `CHECK_THROWS()` from the [`Catch2` test framework](https://github.com/catchorg/Catch2/tree/devel)[^catch2].\nIn the case of a Python project, you would probably use the\n[`raises()` function from `pytest`](https://docs.pytest.org/en/7.1.x/reference/reference.html#pytest-raises)[^pytest].\nWhile in Rust, you would probably use `assert_eq!()` in conjunction with `Err()`.\n\n[^pytest]: <https://docs.pytest.org/en/7.1.x/reference/reference.html#pytest-raises>\n[^catch2]: <https://github.com/catchorg/Catch2/tree/devel>\n\n\nBut in Zig, we use the `expectError()` function, from the `std.testing` module.\nWith this function, you can test if a specific function call returns the exact\ntype of error that you expect it to return. To use this function, you first write\n`try expectError()`. Then, on the first argument, you provide the type of error that you\nare expecting from the function call. Then, on the second argument, you write\nthe function call that you expect to fail.\n\nThe code example below demonstrates such type of unit test in Zig.\nNotice that, inside the function `alloc_error()` we are allocating\n100 bytes of memory, or, an array of 100 elements, for the object `ibuffer`. However,\nin the `test` block, we are using the `FixedBufferAllocator()`\nallocator object, which is limited to 10 bytes of space, because\nthe object `buffer`, which we provided to the allocator object,\nhave only 10 bytes of space.\n\nThat is why, the `alloc_error()` function raises an `OutOfMemory` error\non this case.\nBecause this function is trying to allocate more space than the allocator\nobject allows.\nSo, in essence, we are testing for a specific type of error,\nwhich is `OutOfMemory`. If the `alloc_error()` function returns any other type of error,\nthen, the `expectError()` function would make the entire test fail.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst expectError = std.testing.expectError;\nfn alloc_error(allocator: Allocator) !void {\n    var ibuffer = try allocator.alloc(u8, 100);\n    defer allocator.free(ibuffer);\n    ibuffer[0] = 2;\n}\n\ntest \"testing error\" {\n    var buffer: [10]u8 = undefined;\n    var fba = std.heap.FixedBufferAllocator.init(&buffer);\n    const allocator = fba.allocator();\n    try expectError(error.OutOfMemory, alloc_error(allocator));\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file1537546f248.test.testing error...OKAll 1 t\n  tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n## Testing simple equalities\n\nIn Zig, there are some different ways you can test for an equality.\nYou already saw that we can use `expect()` with the logical operator `==`\nto essentially reproduce an equality test. But we also have\nsome other helper functions that you should know about, especially\n`expectEqual()`, `expectEqualSlices()` and `expectEqualStrings()`.\n\n\nThe `expectEqual()` function, as the name suggests, is a classic\ntest equality function. It receives two objects as input. The first\nobject is the value that you expect to be in the second object.\nWhile second object is the object you have, or, the object that your application\nproduced as result. So, with `expectEqual()` you are essentially\ntesting if the values stored inside these two objects\nare equal or not.\n\nYou can see in the example below that, the test performed by\n`expectEqual()` failed. Because the objects `v1` and `v2` contain\ndifferent values in them.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"values are equal?\" {\n    const v1 = 15;\n    const v2 = 18;\n    try std.testing.expectEqual(v1, v2);\n}\n```\n:::\n\n\n\n\n```\n1/1 ve.test.values are equal?...\n    expected 15, found 18\n    FAIL (TestExpectedEqual)\nve.zig:5:5: test.values are equal? (test)\n    try std.testing.expectEqual(v1, v2);\n    ^\n0 passed; 0 skipped; 1 failed.\n```\n\n\nAlthough useful, the `expectEqual()` function does not work with arrays.\nFor testing if two arrays are equal, you should use the `expectEqualSlices()`\nfunction instead. This function have three arguments. First, you provide\nthe data type contained in both arrays that you are trying to compare.\nWhile the second and third arguments corresponds to the array objects that you want to compare.\n\nIn the example below, we are using this function to test if two array\nobjects (`array1` and `array2`) are equal or not. Since they\nare in fact equal, the unit test passed with no errors.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"arrays are equal?\" {\n    const array1 = [3]u32{1, 2, 3};\n    const array2 = [3]u32{1, 2, 3};\n    try std.testing.expectEqualSlices(\n        u32, &array1, &array2\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file15377bbafb73.test.arrays are equal?...OKAl\n  ll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\nAt last, you might also want to use the `expectEqualStrings()` function.\nAs the name suggests, you can use this function to test if two strings\nare equal or not. Just provide the two string objects that you want to compare,\nas inputs to the function.\n\nIf the function finds any existing differences between the two strings,\nthen, the function will raise an error, and also, print an error message\nthat shows the exact difference between the two string objects provided,\nas the example below demonstrates:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"strings are equal?\" {\n    const str1 = \"hello, world!\";\n    const str2 = \"Hello, world!\";\n    try std.testing.expectEqualStrings(\n        str1, str2\n    );\n}\n```\n:::\n\n\n\n\n```\n1/1 t.test.strings are equal?... \n====== expected this output: =========\nhello, world!␃\n======== instead found this: =========\nHello, world!␃\n======================================\nFirst difference occurs on line 1:\nexpected:\nhello, world!\n^ ('\\x68')\nfound:\nHello, world!\n^ ('\\x48')\n```\n\n",
+    "supporting": [
+      "03-unittests_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/13-image-filter/execute-results/html.json b/_freeze/Chapters/13-image-filter/execute-results/html.json
index 60992ffa..94161bf3 100644
--- a/_freeze/Chapters/13-image-filter/execute-results/html.json
+++ b/_freeze/Chapters/13-image-filter/execute-results/html.json
@@ -1,8 +1,8 @@
 {
-  "hash": "57cac9850f9e50201803beaf886a66e8",
+  "hash": "913ef6c1f2a988d49f8b7ce026c813b6",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 4 - Developing an image filter\n\nIn this chapter we are going to build a new project. The objective of\nthis project is to write a program that applies a filter over an image.\nMore specifically, a \"grayscale filter\", which transforms\nany color image into a grayscale image.\n\nWe are going to use the image displayed at @fig-pascal in this project.\nIn other words, we want to transform this colored image into a grayscale image,\nby using our \"image filter program\" written in Zig.\n\n![A photo of the chilean-american actor Pedro Pascal. Source: Google Images.](../ZigExamples/image_filter/pedro_pascal.png){#fig-pascal}\n\nWe don't need to write a lot of code to build such \"image filter program\". However, we first need\nto understand how digital images work. That is why we begin this chapter\nby explaining the theory behind digital images and how colors are represented in modern computers.\nWe also give a brief explanation about the PNG (Portable Network Graphics) file format, which is the format used\nin the example images.\n\nAt the end of this chapter, we should have a full example of a program that takes the PNG image displayed at @fig-pascal\nas input, and writes a new image to the current working directory that is the grayscale version of this input image.\nThis grayscale version of @fig-pascal is exposed at @fig-pascal-gray.\nYou can find the full source code of this small project at the `ZigExamples/image_filter`\n[folder at the official repository of this book](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter)[^img-filter-folder].\n\n\n![The grayscale version of the photo.](../ZigExamples/image_filter/pedro_pascal_filter.png){#fig-pascal-gray}\n\n\n## How we see things? {#sec-eyes}\n\nIn this section, I want to briefly describe to you how we (humans) actually see things with our own eyes.\nI mean, how our eyes work? If you do have a very basic understanding of how our eyes work, you will understand\nmore easily how digital images are made. Because the techniques behind digital images\nwere developed by taking a lot of inspiration from how our human eyes work.\n\nYou can interpret a human eye as a light sensor, or, a light receptor. The eye receives some amount of light as input,\nand it interprets the colors that are present in this \"amount of light\".\nIf no amount of light hits the eye, then, the eye cannot extract color from it, and as result,\nwe end up seeing nothing, or, more precisely, we see complete blackness.\n\nTherefore, everything depends on light. What we actually see are the colors (blue, red, orange, green, purple, yellow, etc.) that\nare being reflected from the light that is hitting our eyes. **Light is the source of all colors!**\nThis is what Isaac Newton discovered on his famous prism experiment[^newton] in the 1660s.\n\n[^newton]: <https://library.si.edu/exhibition/color-in-a-new-light/science>\n\nInside our eyes, we have a specific type of cell called the \"cone cell\".\nOur eye have three different types, or, three different versions of these \"cone cells\".\nEach type of cone cell is very sensitive to a specific spectrum of the light. More specifically,\nto the spectrums that define the colors red, green and blue.\nSo, in summary, our eyes have specific types of cells that\nare highly sensitive to these three colors (red, green and blue).\n\nThese are the cells responsible for perceiving the color present in the light that hits our eyes.\nAs a result, our eyes perceives color as a mixture of these three colors (red, green and blue). By having an amount\nof each one of these three colors, and mixing them together, we can get any other visible color\nthat we want. So every color that we see is perceived as a specific mixture of blues, greens and reds,\nlike 30% of red, plus 20% of green, plus 50% of blue.\n\nWhen these cone cells perceive (or, detect) the colors that are found in the\nlight that is hitting our eyes, these cells produce electrical signals, which are sent to the brain.\nOur brain interprets these electrical signals, and use them to form the image that we are seeing\ninside our head.\n\nBased on what we have discussed here, the bullet points exposed below describes the sequence of events that\ncomposes this very simplified version of how our human eyes work:\n\n1. Light hits our eyes.\n1. The cone cells perceive the colors that are present in this light.\n1. Cone cells produce electrical signals that describes the colors that were perceived in the light.\n1. The electrical signals are sent to the brain.\n1. Brain interprets these signals, and form the image based on the colors identified by these electrical signals.\n\n\n## How digital images work? {#sec-digital-img}\n\nA digital image is a \"digital representation\" of an image that we see with our eyes.\nIn other words, a digital image is a \"digital representation\" of the colors that we see\nand perceive through the light.\nIn the digital world, we have two types of images, which are: vector images and raster images.\nVector images are not described here. So just remember that the content discussed here\n**is related solely to raster images**, and not vector images.\n\nA raster image is a type of digital image that is represented as a 2D (two dimensional) matrix\nof pixels. In other words, every raster image is basically a rectangle of pixels, and each pixel have a particular color.\nSo, a raster image is just a rectangle of pixels, and each of these pixels are displayed in the screen of your computer (or the screen\nof any other device, e.g. laptop, tablet, smartphone, etc.) as a color.\n\n@fig-raster demonstrates this idea. If you take any raster image, and you zoom into it very hard,\nyou will see the actual pixels of the image. JPEG, TIFF and PNG are file formats that are commonly\nused to store raster images.\n\n![Zooming over a raster image to see the pixels. Source: Google Images.](../Figures/imagem-raster.png){#fig-raster}\n\nThe more pixels the image has, the more information and detail we can include in the image.\nThe more accurate, sharp and pretty the image will look. This is why photographic cameras\nusually produce big raster images, with several megapixels of resolution, to include as much detail as possible into the final image.\nAs an example, a digital image with dimensions of 1920 pixels wide and 1080 pixels high, would be a image that\ncontains $1920 \\times 1080 = 2073600$ pixels in total. You could also say that the \"total area\" of the image is\nof 2073600 pixels, although the concept of \"area\" is not really used here in computer graphics.\n\nMost digital images we see in our modern world uses the RGB color model. RGB stands for (red, green and blue).\nSo the color of each pixel in these raster images are usually represented as a mixture of red, green and blue,\njust like in our eyes. That is, the color of each pixel is identified by a set of\nthree different integer values. Each integer value identifies the \"amount\" of each color (red, green and blue).\nFor example, the set `(199, 78, 70)` identifies a color that is more close to red. We have 199 of red, 78 of green,\nand 70 of blue. In contrast, the set `(129, 77, 250)` describes a color that is more close to purple. Et cetera.\n\n\n\n### Images are displayed from top to bottom\n\nThis is not a rule written in stone, but the big majority of digital images are displayed from top\nto bottom and left to right. Most computers screens also follow this pattern. So, the first pixels\nin the image are the ones that are at the top and left corner of the image. You can find a visual representation\nof this logic at @fig-img-display.\n\nAlso notice in @fig-img-display that, because a raster image is essentially a 2D matrix of pixels,\nthe image is organized into rows and columns of pixels. The columns are defined by the horizontal x axis,\nwhile the rows are defined by the vertical y axis.\n\nEach pixel (i.e. the gray rectangles) exposed at @fig-img-display contains a number inside of it.\nThese numbers are the indexes of the pixels. You can notice that the first pixels are in the top and left\ncorner, and also, that the indexes of these pixels \"grow to the sides\", or, in other words, they grow in the direction of the horizontal x axis.\nMost raster images are organized as rows of pixels. Thus, when these digital images are\ndisplayed, the screen display the first row of pixels, then, the second row, then, the third row, etc.\n\n![How the pixels of raster images are displayed.](./../Figures/image-display.png){#fig-img-display}\n\n\n\n\n\n\n### Representing the matrix of pixels in code {#sec-pixel-repr}\n\nOk, we know already that raster images are represented as 2D matrices of pixels.\nBut we do not have a notion of a 2D matrix in Zig. Actually, most low-level languages in general\n(Zig, C, Rust, etc.) do not have such notion.\nSo how can we represent such matrix of pixels in Zig, or any other low-level language?\nThe strategy that most programmers choose in this situation is to just use a normal 1D array to store the values of\nthis 2D matrix. In other words, you just create an normal 1D array, and store all values from both dimensions into this 1D array.\n\nAs an example, suppose we have a very small image of dimensions 4x3.\nSince a raster image is represented as a 2D matrix of pixels, and each pixel\nis represented by 3 \"unsigned 8-bit\" integer values, we have 12 pixels in\ntotal in this image, which are represented by $3 \\times 12 = 36$ integer values.\nTherefore, we need to create an array of 36 `u8` values to store this small image.\n\nThe reason why unsigned 8-bit integer (`u8`) values are used to represent the amounts of each color,\ninstead of any other integer type, is because they take the minimum amount of space as possible, or,\nthe minimum amount of bits as possible. Which helps to reduces the binary size of the image, i.e. the 2D matrix.\nAlso, they convey a good amount of precision and detail about the colors, even though they can represent\na relatively small range (from 0 to 255) of \"color amounts\".\n\nComing back to our initial example of a 4x3 image,\nthe `matrix` object exposed below could be an example of an 1D array that stores\nthe data that represents this 4x3 image.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst matrix = [_]u8{\n    201, 10, 25, 185, 65, 70,\n    65, 120, 110, 65, 120, 117,\n    98, 95, 12, 213, 26, 88,\n    143, 112, 65, 97, 99, 205,\n    234, 105, 56, 43, 44, 216,\n    45, 59, 243, 211, 209, 54,\n};\n```\n:::\n\n\n\n\nThe first three integer values in this array are the color amounts of the first pixel in the image.\nThe next three integers are the colors amounts for the second pixel.\nAnd the sequence goes on in this pattern. Having that in mind, the size of the array that stores\na raster image is usually a multiple of 3. In this case, the array have a size of 36.\n\nI mean, the size of the array is **usually** a multiple of 3, because in specific circumstances,\nit can also be a multiple of 4. This happens when a transparency amount is\nalso included into the raster image. In other words, there are some types of raster images\nthat uses a different color model, which is the RGBA (red, green, blue and alpha)\ncolor model. The \"alpha\" corresponds to an amount of transparency in the pixel.\nSo every pixel in a RGBA image is represented by a red, green, blue and alpha values.\n\nMost raster images uses the standard RGB model, so, for the most part, you will\nsee arrays sizes that are multiples of 3. But some images, especially the ones\nthat are stored in PNG files, might be using the RGBA model, and, therefore, are\nrepresented by an array whose size is a multiple of 4.\n\nIn our case here, the example image of our project (@fig-pascal) is a raster image\nstored in a PNG file, and this specific image is using the RGBA color model. Therefore,\neach pixel in the image is represented by 4 different integer values, and, as consequence,\nto store this image in our Zig code, we need to create an array whose size is a multiple of 4.\n\n\n## The PNG library that we are going to use\n\nLet's begin our project by focusing on writing the necessary Zig code to\nread the data from the PNG file. In other words, we want to read the PNG file exposed\nat @fig-pascal, and parse its data to extract the 2D matrix of pixels that represents the image.\n\nAs we have discussed at @sec-pixel-repr, the image that we are using as example here\nis a PNG file that uses the RGBA color model, and, therefore, each pixel of the image\nis represented by 4 integer values. You can download this image by visiting the `ZigExamples/image_filter`\n[folder at the official repository of this book](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter)[^img-filter-folder].\nYou can also find in this folder the complete source code of this small project that we\nare developing here.\n\n[^img-filter-folder]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter>\n\nThere are some C libraries available that we can use to read and parse PNG files.\nThe most famous and used of all is `libpng`, which is the \"official library\" for reading and writing\nPNG files. Although this library is available on most operating system, it is well known\nfor being complex and hard to use.\n\nThat is why, I'm going to use a more modern alternative here in this project, which is the `libspng` library.\nI choose to use this C library here, because it is much, much simpler to use than `libpng`,\nand it also offers very good performance for all operations. You can checkout the\n[official website of the library](https://libspng.org/)[^libspng]\nto know more about it. You will also find there some documentation that might help you to understand and\nfollow the code examples exposed here.\n\n[^libspng]: <https://libspng.org/>\n\n\nFirst of all, remember to build and install this `libspng` into your system. Because\nif you don't do this step, the `zig` compiler will not be able to find the files and resources of\nthis library in your computer, and link them with the Zig source code that we are writing together here.\nThere is good information about how to build and install the library at the\n[build section of the library documentation](https://libspng.org/docs/build/)[^lib-build].\n\n[^lib-build]: <https://libspng.org/docs/build/>\n\n\n\n\n## Reading the PNG file\n\nIn order to extract the pixel data from the PNG file, we need to read and decode the file.\nA PNG file is just a binary file written in the \"PNG format\". Luckily, the `libspng` library offers\na function called `spng_decode_image()` that does all this heavy work for us.\n\nNow, since `libspng` is a C library, most of the file and I/O operations in this library are made by using\na `FILE` C pointer. Because of that, is probably a better idea to use the `fopen()` C function\nto open our PNG file, instead of using the `openFile()` method that I introduced at @sec-filesystem.\nThat is why I'm importing the `stdio.h` C header in this project, and using the `fopen()` C function to open the file.\n\nIf you look at the snippet below, you can see that we are:\n\n1. opening the PNG file with `fopen()`.\n1. creating the `libspng` context with `spng_ctx_new()`.\n1. using `spng_set_png_file()` to specify the `FILE` object that reads the PNG file that we are going to use.\n\nEvery operation in `libspng` is made through a \"context object\". In our snippet below, this object is `ctx`.\nAlso, to perform an operation over a PNG file, we need to specify which exact PNG file we are referring to.\nThis is the job of `spng_set_png_file()`. We are using this function to specify the file descriptor\nobject that reads the PNG file that we want to use.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n    @cInclude(\"spng.h\");\n});\n\nconst path = \"pedro_pascal.png\";\nconst file_descriptor = c.fopen(path, \"rb\");\nif (file_descriptor == null) {\n    @panic(\"Could not open file!\");\n}\nconst ctx = c.spng_ctx_new(0) orelse unreachable;\n_ = c.spng_set_png_file(\n    ctx, @ptrCast(file_descriptor)\n);\n```\n:::\n\n\n\n\nBefore we continue, is important to emphasize the following: since we have opened the file with `fopen()`,\nwe have to remember to close the file at the end of the program, with `fclose()`.\nIn other words, after we have done everything that we wanted to do with the PNG file\n`pedro_pascal.png`, we need to close this file, by applying `fclose()` over the file descriptor object.\nWe could use also the `defer` keyword to help us in this task, if we want to.\nThis code snippet below demonstrates this step:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (c.fclose(file_descriptor) != 0) {\n    return error.CouldNotCloseFileDescriptor;\n}\n```\n:::\n\n\n\n\n\n\n\n### Reading the image header section\n\nNow, the context object `ctx` is aware of our PNG file `pedro_pascal.png`, because it has access to\na file descriptor object to this file. The first thing that we are going to do is to read the\n\"image header section\" of the PNG file. This \"image header section\" is the section\nof the file that contains some basic information about the PNG file, like, the bit depth of the pixel data\nof the image, the color model used in the file, the dimensions of the image (height and width in number of pixels),\netc.\n\nTo make things easier, I will encapsulate this \"read image header\" operation into a\nnice and small function called `get_image_header()`. All that this function needs to do\nis to call the `spng_get_ihdr()` function. This function from `libspng` is responsible\nfor reading the image header data, and storing it into a C struct named `spng_ihdr`.\nThus, an object of type `spng_ihdr` is a C struct that contains the data from the\nimage header section of the PNG file.\n\nSince this Zig function is receiving a C object (the `libspng` context object) as input, I marked\nthe function argument `ctx` as \"a pointer to the context object\" (`*c.spng_ctx`), following the recommendations\nthat we have discussed at @sec-pass-c-structs.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn get_image_header(ctx: *c.spng_ctx) !c.spng_ihdr {\n    var image_header: c.spng_ihdr = undefined;\n    if (c.spng_get_ihdr(ctx, &image_header) != 0) {\n        return error.CouldNotGetImageHeader;\n    }\n\n    return image_header;\n}\n\nvar image_header = try get_image_header(ctx);\n```\n:::\n\n\n\n\nAlso notice in this function, that I'm checking if the `spng_get_ihdr()` function call have\nreturned or not an integer value that is different than zero. Most functions from the\n`libspng` library return a code status as result, and the code status \"zero\" means\n\"success\". So any code status that is different than zero means that an error\noccurred while running `spng_get_ihdr()`. This is why I'm returning an error value from\nthe function in case the code status returned by the function is different than zero.\n\n\n### Allocating space for the pixel data\n\nBefore we read the pixel data from the PNG file, we need to allocate enough space to hold this data.\nBut in order to allocate such space, we first need to know how much space we need to allocate.\nThe dimensions of the image are obviously needed to calculate the size of this space. But there are\nother elements that also affect this number, such as the color model used in the image, the bit depth, and others.\n\nAnyway, all of this means that calculating the size of the space that we need, is not a simple task.\nThat is why the `libspng` library offers an utility function named\n`spng_decoded_image_size()` to calculate this size for us. Once again, I'm going\nto encapsulate the logic around this C function into a nice and small Zig function\nnamed `calc_output_size()`. You can see below that this function returns a nice\ninteger value as result, informing the size of the space that we need to allocate.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn calc_output_size(ctx: *c.spng_ctx) !u64 {\n    var output_size: u64 = 0;\n    const status = c.spng_decoded_image_size(\n        ctx, c.SPNG_FMT_RGBA8, &output_size\n    );\n    if (status != 0) {\n        return error.CouldNotCalcOutputSize;\n    }\n    return output_size;\n}\n```\n:::\n\n\n\n\n\n\nYou might quest yourself what the value `SPNG_FMT_RGBA8` means. This value is actually an enum\nvalue defined in the `spng.h` C header file. This enum is used to identify a \"PNG format\".\nMore precisely, it identifies a PNG file that uses the RGBA color model and 8 bit depth.\nSo, by providing this enum value as input to the `spng_decoded_image_size()` function,\nwe are saying to this function to calculate the size of the decoded pixel data, by considering\na PNG file that follows this \"RGBA color model with 8 bit depth\" format.\n\nHaving this function, we can use it in conjunction with an allocator object, to allocate an\narray of bytes (`u8` values) that is big enough to store the decoded pixel data of the image.\nNotice that I'm using `@memset()` to initialize the entire array to zero.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst output_size = try calc_output_size(ctx);\nvar buffer = try allocator.alloc(u8, output_size);\n@memset(buffer[0..], 0);\n```\n:::\n\n\n\n\n\n### Decoding the image data\n\nNow that we have the necessary space to store the decoded pixel data of the image,\nwe can start to actually decode and extract this pixel data from the image,\nby using the `spng_decode_image()` C function.\n\nThe `read_data_to_buffer()` Zig function exposed below summarises the necessary\nsteps to read this decoded pixel data, and store it into an input buffer.\nNotice that this function is encapsulating the logic around the `spng_decode_image()` function.\nAlso, we are using the `SPNG_FMT_RGBA8` enum value once again to inform the corresponding function,\nthat the PNG image being decoded, uses the RGBA color model and 8 bit depth.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn read_data_to_buffer(ctx: *c.spng_ctx, buffer: []u8) !void {\n    const status = c.spng_decode_image(\n        ctx,\n        buffer.ptr,\n        buffer.len,\n        c.SPNG_FMT_RGBA8,\n        0\n    );\n\n    if (status != 0) {\n        return error.CouldNotDecodeImage;\n    }\n}\n```\n:::\n\n\n\n\nHaving this function at hand, we can apply it over our context object, and also, over\nthe buffer object that we have allocated in the previous section to hold the decoded pixel data\nof the image:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry read_data_to_buffer(ctx, buffer[0..]);\n```\n:::\n\n\n\n\n\n### Looking at the pixel data\n\nNow that we have the pixel data stored in our \"buffer object\", we can take\na quick look at the bytes. In the example below, we are looking at the first\n12 bytes in the decoded pixel data.\n\nIf you take a close look at these values, you might notice that every 4 bytes\nin the sequence is 255. Which, coincidentally is the maximum possible integer value\nto be represented by a `u8` value. So, if the range from 0 to 255, which is the range\nof integer values that can be represented by an `u8` value, can be represented as a scale from 0% to 100%,\nthese 255 values are essentially 100% in that scale.\n\nIf you recall from @sec-pixel-repr, I have\ndescribed in that section that our `pedro_pascal.png` PNG file uses the RGBA color model,\nwhich adds an alpha (or transparency) byte to each pixel in the image.\nAs consequence, each pixel in the image is represented by 4 bytes. Since we are looking\nhere are the first 12 bytes in the image, it means that we are looking at the data from\nthe first $12 / 4 = 3$ pixels in the image.\n\nSo, based on how these first 12 bytes (or these 3 pixels) look, with these 255 values at every 4 bytes, we can say that is likely\nthat every pixel in the image have alpha (or transparency) setted to 100%. This might not be true,\nbut, is the most likely possibility. Also, if we look at the image itself, which if your recall is\nexposed at @fig-pascal, we can see that the transparency does not change across the image,\nwhich enforces this theory.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry stdout.print(\"{any}\\n\", .{buffer[0..12]});\n```\n:::\n\n\n\n\n```\n{\n    200, 194, 216, 255, 203, 197,\n    219, 255, 206, 200, 223, 255\n}\n```\n\n\nWe can see in the above result that the first pixel in this image have 200 of red, 194 of green, and 216 of blue.\nHow do I know the order in which the colors appears in the sequence? If you have not guessed that yet,\nis because of the acronym RGB. First RED, then GREEN, then BLUE. If we scale these integer values\naccording to our scale of 0% to 100% (0 to 255), we get 78% of red, 76% of green and 85% of blue.\n\n\n\n## Applying the image filter\n\nNow that we have the data of each pixel in the image, we can focus on applying our image\nfilter over these pixels. Remember, our objective here is to apply a grayscale filter over\nthe image. A grayscale filter is a filter that transforms a colored image into a grayscale image.\n\nThere are different formulas and strategies to transform a colored image into a grayscale image.\nBut all of these different strategies normally involve applying some math over the colors of each pixel.\nIn this project, we are going to use the most general formula, which is exposed below.\nThis formula considers $r$ as the red of the pixel, $g$ as the green, $b$ as the blue, and $p'$ as the\nlinear luminance of the pixel.\n\n$$\n    p' = (0.2126 \\times r) + (0.7152 \\times g) + (0.0722 \\times b)\n$${#eq-grayscale}\n\nThis @eq-grayscale is the formula to calculate the linear luminance of a pixel. Is worth noting that this formula\nworks only for images whose pixels are using the sRGB color space, which is the standard color space\nfor the web. Thus, ideally, all images on the web should use this color space. Luckily,\nthis is our case here, i.e. the `pedro_pascal.png` image is using this sRGB color space, and, as consequence,\nwe can use the @eq-grayscale. You can read more about this formula at the Wikipedia page for grayscale [@wiki_grayscale].\n\nThe `apply_image_filter()` function exposed below summarises the necessary steps to\napply @eq-grayscale over the pixels in the image. We just apply this function\nover our buffer object that contains our pixel data, and, as result, the pixel\ndata stored in this buffer object should now represent the grayscale version of our image.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn apply_image_filter(buffer:[]u8) !void {\n    const len = buffer.len;\n    const red_factor: f16 = 0.2126;\n    const green_factor: f16 = 0.7152;\n    const blue_factor: f16 = 0.0722;\n    var index: u64 = 0;\n    while (index <= (len - 4)) : (index += 4) {\n        const rf: f16 = @floatFromInt(buffer[index]);\n        const gf: f16 = @floatFromInt(buffer[index + 1]);\n        const bf: f16 = @floatFromInt(buffer[index + 2]);\n        const y_linear: f16 = (\n            (rf * red_factor) + (gf * green_factor)\n            + (bf * blue_factor)\n        );\n        buffer[index] = @intFromFloat(y_linear);\n        buffer[index + 1] = @intFromFloat(y_linear);\n        buffer[index + 2] = @intFromFloat(y_linear);\n    }\n}\n\ntry apply_image_filter(buffer[0..]);\n```\n:::\n\n\n\n\n\n\n## Saving the grayscale version of the image\n\nSince we have now the grayscale version of our image stored in our buffer object,\nwe need to encode this buffer object back into the \"PNG format\", and save the encoded data into\na new PNG file in our filesystem, so that we can access and see the grayscale version of our image\nthat was produced by our small program.\n\nTo do that, the `libspng` library help us once again by offering an \"encode data to PNG\" type of function,\nwhich is the `spng_encode_image()` function. But in order to \"encode data to PNG\" with `libspng`, we need\nto create a new context object. This new context object must use an \"encoder context\", which\nis identified by the enum value `SPNG_CTX_ENCODER`.\n\nThe `save_png()` function exposed below, summarises all the necessary steps to save the\ngrayscale version of our image into a new PNG file in the filesystem. By default, this\nfunction will save the grayscale image into a file named `pedro_pascal_filter.png` in the CWD.\n\nNotice in this code example that we are using the same image header object (`image_header`) that we have\ncollected previously with the `get_image_header()` function. Remember, this image header object\nis a C struct (`spng_ihdr`) that contains basic information about our PNG file, such as\nthe dimensions of the image, the color model used, etc.\n\nIf we wanted to save a very different image in this new PNG file, e.g. an image\nwith different dimensions, or, an image that uses a different color model, a different bit depth, etc.\nwe would have to create a new image header (`spng_ihdr`) object that describes the properties\nof this new image.\n\nBut we are essentially saving the same image that we have begin with here (the dimensions of\nthe image, the color model, etc. are all still the same). The only difference\nbetween the two images are the colors of the pixels, which are now \"shades of gray\".\nAs consequence, we can safely use the exact same image header data in this new PNG file.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn save_png(image_header: *c.spng_ihdr, buffer: []u8) !void {\n    const path = \"pedro_pascal_filter.png\";\n    const file_descriptor = c.fopen(path.ptr, \"wb\");\n    if (file_descriptor == null) {\n        return error.CouldNotOpenFile;\n    }\n    const ctx = (\n        c.spng_ctx_new(c.SPNG_CTX_ENCODER)\n        orelse unreachable\n    );\n    defer c.spng_ctx_free(ctx);\n    _ = c.spng_set_png_file(ctx, @ptrCast(file_descriptor));\n    _ = c.spng_set_ihdr(ctx, image_header);\n\n    const encode_status = c.spng_encode_image(\n        ctx,\n        buffer.ptr,\n        buffer.len,\n        c.SPNG_FMT_PNG,\n        c.SPNG_ENCODE_FINALIZE\n    );\n    if (encode_status != 0) {\n        return error.CouldNotEncodeImage;\n    }\n    if (c.fclose(file_descriptor) != 0) {\n        return error.CouldNotCloseFileDescriptor;\n    }\n}\n\ntry save_png(&image_header, buffer[0..]);\n```\n:::\n\n\n\n\nAfter we execute this `save_png()` function, we should have a new PNG file\ninside our CWD, named `pedro_pascal_filter.png`. If we open this PNG file,\nwe will see the same image exposed at @fig-pascal-gray.\n\n\n## Building our project\n\nNow that we have written the code, let's discuss how can we build/compile this project.\nTo do that, I'm going to create a `build.zig` file in the root directory of our project,\nand start writing the necessary code to compile the project, using the knowledge\nthat we have acquired from @sec-build-system.\n\n\nWe first create the build target for our executable file, that executes our\nZig code. Let's suppose that all of our Zig code was written into a Zig module\nnamed `image_filter.zig`. The `exe` object exposed in the build script below\ndescribes the build target for our executable file.\n\nSince we have used some C code from the `libspng` library in our Zig code,\nwe need to link our Zig code (which is in the `exe` build target) to both\nthe C Standard Library, and, to the `libspng` library. We do that, by calling\nthe `linkLibC()` and `linkSystemLibrary()` methods from our `exe` build target.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const target = b.standardTargetOptions(.{});\n    const optimize = b.standardOptimizeOption(.{});\n    const exe = b.addExecutable(.{\n        .name = \"image_filter\",\n        .root_source_file = b.path(\"src/image_filter.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n    exe.linkLibC();\n    // Link to libspng library:\n    exe.linkSystemLibrary(\"spng\");\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\nSince we are using the `linkSystemLibrary()` method, it means that the library\nfiles for `libspng` are searched in your system to be linked with the `exe` build target.\nIf you have not yet built and installed the `libspng` library into your system, this\nlinkage step will likely not work. Because it will not find the library files in your system.\n\nSo, just remember to install `libspng` in your system, if you want to build this project.\nHaving this build script above written, we can finally build our project by\nrunning the `zig build` command in the terminal.\n\n```bash\nzig build\n```\n\n\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 4 - Developing an image filter\n\nIn this chapter we are going to build a new project. The objective of\nthis project is to write a program that applies a filter over an image.\nMore specifically, a \"grayscale filter\", which transforms\nany color image into a grayscale image.\n\nWe are going to use the image displayed at @fig-pascal in this project.\nIn other words, we want to transform this colored image into a grayscale image,\nby using our \"image filter program\" written in Zig.\n\n![A photo of the chilean-american actor Pedro Pascal. Source: Google Images.](../ZigExamples/image_filter/pedro_pascal.png){#fig-pascal}\n\nWe don't need to write a lot of code to build such \"image filter program\". However, we first need\nto understand how digital images work. That is why we begin this chapter\nby explaining the theory behind digital images and how colors are represented in modern computers.\nWe also give a brief explanation about the PNG (Portable Network Graphics) file format, which is the format used\nin the example images.\n\nAt the end of this chapter, we should have a full example of a program that takes the PNG image displayed at @fig-pascal\nas input, and writes a new image to the current working directory that is the grayscale version of this input image.\nThis grayscale version of @fig-pascal is exposed at @fig-pascal-gray.\nYou can find the full source code of this small project at the `ZigExamples/image_filter`\n[folder at the official repository of this book](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter)[^img-filter-folder].\n\n\n![The grayscale version of the photo.](../ZigExamples/image_filter/pedro_pascal_filter.png){#fig-pascal-gray}\n\n\n## How we see things? {#sec-eyes}\n\nIn this section, I want to briefly describe to you how we (humans) actually see things with our own eyes.\nI mean, how our eyes work? If you do have a very basic understanding of how our eyes work, you will understand\nmore easily how digital images are made. Because the techniques behind digital images\nwere developed by taking a lot of inspiration from how our human eyes work.\n\nYou can interpret a human eye as a light sensor, or, a light receptor. The eye receives some amount of light as input,\nand it interprets the colors that are present in this \"amount of light\".\nIf no amount of light hits the eye, then, the eye cannot extract color from it, and as result,\nwe end up seeing nothing, or, more precisely, we see complete blackness.\n\nTherefore, everything depends on light. What we actually see are the colors (blue, red, orange, green, purple, yellow, etc.) that\nare being reflected from the light that is hitting our eyes. **Light is the source of all colors!**\nThis is what Isaac Newton discovered on his famous prism experiment[^newton] in the 1660s.\n\n[^newton]: <https://library.si.edu/exhibition/color-in-a-new-light/science>\n\nInside our eyes, we have a specific type of cell called the \"cone cell\".\nOur eye have three different types, or, three different versions of these \"cone cells\".\nEach type of cone cell is very sensitive to a specific spectrum of the light. More specifically,\nto the spectrums that define the colors red, green and blue.\nSo, in summary, our eyes have specific types of cells that\nare highly sensitive to these three colors (red, green and blue).\n\nThese are the cells responsible for perceiving the color present in the light that hits our eyes.\nAs a result, our eyes perceives color as a mixture of these three colors (red, green and blue). By having an amount\nof each one of these three colors, and mixing them together, we can get any other visible color\nthat we want. So every color that we see is perceived as a specific mixture of blues, greens and reds,\nlike 30% of red, plus 20% of green, plus 50% of blue.\n\nWhen these cone cells perceive (or, detect) the colors that are found in the\nlight that is hitting our eyes, these cells produce electrical signals, which are sent to the brain.\nOur brain interprets these electrical signals, and use them to form the image that we are seeing\ninside our head.\n\nBased on what we have discussed here, the bullet points exposed below describes the sequence of events that\ncomposes this very simplified version of how our human eyes work:\n\n1. Light hits our eyes.\n1. The cone cells perceive the colors that are present in this light.\n1. Cone cells produce electrical signals that describes the colors that were perceived in the light.\n1. The electrical signals are sent to the brain.\n1. Brain interprets these signals, and form the image based on the colors identified by these electrical signals.\n\n\n## How digital images work? {#sec-digital-img}\n\nA digital image is a \"digital representation\" of an image that we see with our eyes.\nIn other words, a digital image is a \"digital representation\" of the colors that we see\nand perceive through the light.\nIn the digital world, we have two types of images, which are: vector images and raster images.\nVector images are not described here. So just remember that the content discussed here\n**is related solely to raster images**, and not vector images.\n\nA raster image is a type of digital image that is represented as a 2D (two dimensional) matrix\nof pixels. In other words, every raster image is basically a rectangle of pixels, and each pixel have a particular color.\nSo, a raster image is just a rectangle of pixels, and each of these pixels are displayed in the screen of your computer (or the screen\nof any other device, e.g. laptop, tablet, smartphone, etc.) as a color.\n\n@fig-raster demonstrates this idea. If you take any raster image, and you zoom into it very hard,\nyou will see the actual pixels of the image. JPEG, TIFF and PNG are file formats that are commonly\nused to store raster images.\n\n![Zooming over a raster image to see the pixels. Source: Google Images.](../Figures/imagem-raster.png){#fig-raster}\n\nThe more pixels the image has, the more information and detail we can include in the image.\nThe more accurate, sharp and pretty the image will look. This is why photographic cameras\nusually produce big raster images, with several megapixels of resolution, to include as much detail as possible into the final image.\nAs an example, a digital image with dimensions of 1920 pixels wide and 1080 pixels high, would be a image that\ncontains $1920 \\times 1080 = 2073600$ pixels in total. You could also say that the \"total area\" of the image is\nof 2073600 pixels, although the concept of \"area\" is not really used here in computer graphics.\n\nMost digital images we see in our modern world uses the RGB color model. RGB stands for (red, green and blue).\nSo the color of each pixel in these raster images are usually represented as a mixture of red, green and blue,\njust like in our eyes. That is, the color of each pixel is identified by a set of\nthree different integer values. Each integer value identifies the \"amount\" of each color (red, green and blue).\nFor example, the set `(199, 78, 70)` identifies a color that is more close to red. We have 199 of red, 78 of green,\nand 70 of blue. In contrast, the set `(129, 77, 250)` describes a color that is more close to purple. Et cetera.\n\n\n\n### Images are displayed from top to bottom\n\nThis is not a rule written in stone, but the big majority of digital images are displayed from top\nto bottom and left to right. Most computers screens also follow this pattern. So, the first pixels\nin the image are the ones that are at the top and left corner of the image. You can find a visual representation\nof this logic at @fig-img-display.\n\nAlso notice in @fig-img-display that, because a raster image is essentially a 2D matrix of pixels,\nthe image is organized into rows and columns of pixels. The columns are defined by the horizontal x axis,\nwhile the rows are defined by the vertical y axis.\n\nEach pixel (i.e. the gray rectangles) exposed at @fig-img-display contains a number inside of it.\nThese numbers are the indexes of the pixels. You can notice that the first pixels are in the top and left\ncorner, and also, that the indexes of these pixels \"grow to the sides\", or, in other words, they grow in the direction of the horizontal x axis.\nMost raster images are organized as rows of pixels. Thus, when these digital images are\ndisplayed, the screen display the first row of pixels, then, the second row, then, the third row, etc.\n\n![How the pixels of raster images are displayed.](./../Figures/image-display.png){#fig-img-display}\n\n\n\n\n\n\n### Representing the matrix of pixels in code {#sec-pixel-repr}\n\nOk, we know already that raster images are represented as 2D matrices of pixels.\nBut we do not have a notion of a 2D matrix in Zig. Actually, most low-level languages in general\n(Zig, C, Rust, etc.) do not have such notion.\nSo how can we represent such matrix of pixels in Zig, or any other low-level language?\nThe strategy that most programmers choose in this situation is to just use a normal 1D array to store the values of\nthis 2D matrix. In other words, you just create an normal 1D array, and store all values from both dimensions into this 1D array.\n\nAs an example, suppose we have a very small image of dimensions 4x3.\nSince a raster image is represented as a 2D matrix of pixels, and each pixel\nis represented by 3 \"unsigned 8-bit\" integer values, we have 12 pixels in\ntotal in this image, which are represented by $3 \\times 12 = 36$ integer values.\nTherefore, we need to create an array of 36 `u8` values to store this small image.\n\nThe reason why unsigned 8-bit integer (`u8`) values are used to represent the amounts of each color,\ninstead of any other integer type, is because they take the minimum amount of space as possible, or,\nthe minimum amount of bits as possible. Which helps to reduces the binary size of the image, i.e. the 2D matrix.\nAlso, they convey a good amount of precision and detail about the colors, even though they can represent\na relatively small range (from 0 to 255) of \"color amounts\".\n\nComing back to our initial example of a 4x3 image,\nthe `matrix` object exposed below could be an example of an 1D array that stores\nthe data that represents this 4x3 image.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst matrix = [_]u8{\n    201, 10, 25, 185, 65, 70,\n    65, 120, 110, 65, 120, 117,\n    98, 95, 12, 213, 26, 88,\n    143, 112, 65, 97, 99, 205,\n    234, 105, 56, 43, 44, 216,\n    45, 59, 243, 211, 209, 54,\n};\n```\n:::\n\n\n\n\nThe first three integer values in this array are the color amounts of the first pixel in the image.\nThe next three integers are the colors amounts for the second pixel.\nAnd the sequence goes on in this pattern. Having that in mind, the size of the array that stores\na raster image is usually a multiple of 3. In this case, the array have a size of 36.\n\nI mean, the size of the array is **usually** a multiple of 3, because in specific circumstances,\nit can also be a multiple of 4. This happens when a transparency amount is\nalso included into the raster image. In other words, there are some types of raster images\nthat uses a different color model, which is the RGBA (red, green, blue and alpha)\ncolor model. The \"alpha\" corresponds to an amount of transparency in the pixel.\nSo every pixel in a RGBA image is represented by a red, green, blue and alpha values.\n\nMost raster images uses the standard RGB model, so, for the most part, you will\nsee arrays sizes that are multiples of 3. But some images, especially the ones\nthat are stored in PNG files, might be using the RGBA model, and, therefore, are\nrepresented by an array whose size is a multiple of 4.\n\nIn our case here, the example image of our project (@fig-pascal) is a raster image\nstored in a PNG file, and this specific image is using the RGBA color model. Therefore,\neach pixel in the image is represented by 4 different integer values, and, as consequence,\nto store this image in our Zig code, we need to create an array whose size is a multiple of 4.\n\n\n## The PNG library that we are going to use\n\nLet's begin our project by focusing on writing the necessary Zig code to\nread the data from the PNG file. In other words, we want to read the PNG file exposed\nat @fig-pascal, and parse its data to extract the 2D matrix of pixels that represents the image.\n\nAs we have discussed at @sec-pixel-repr, the image that we are using as example here\nis a PNG file that uses the RGBA color model, and, therefore, each pixel of the image\nis represented by 4 integer values. You can download this image by visiting the `ZigExamples/image_filter`\n[folder at the official repository of this book](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter)[^img-filter-folder].\nYou can also find in this folder the complete source code of this small project that we\nare developing here.\n\n[^img-filter-folder]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter>\n\nThere are some C libraries available that we can use to read and parse PNG files.\nThe most famous and used of all is `libpng`, which is the \"official library\" for reading and writing\nPNG files. Although this library is available on most operating system, it is well known\nfor being complex and hard to use.\n\nThat is why, I'm going to use a more modern alternative here in this project, which is the `libspng` library.\nI choose to use this C library here, because it is much, much simpler to use than `libpng`,\nand it also offers very good performance for all operations. You can checkout the\n[official website of the library](https://libspng.org/)[^libspng]\nto know more about it. You will also find there some documentation that might help you to understand and\nfollow the code examples exposed here.\n\n[^libspng]: <https://libspng.org/>\n\n\nFirst of all, remember to build and install this `libspng` into your system. Because\nif you don't do this step, the `zig` compiler will not be able to find the files and resources of\nthis library in your computer, and link them with the Zig source code that we are writing together here.\nThere is good information about how to build and install the library at the\n[build section of the library documentation](https://libspng.org/docs/build/)[^lib-build].\n\n[^lib-build]: <https://libspng.org/docs/build/>\n\n\n\n\n## Reading the PNG file\n\nIn order to extract the pixel data from the PNG file, we need to read and decode the file.\nA PNG file is just a binary file written in the \"PNG format\". Luckily, the `libspng` library offers\na function called `spng_decode_image()` that does all this heavy work for us.\n\nNow, since `libspng` is a C library, most of the file and I/O operations in this library are made by using\na `FILE` C pointer. Because of that, is probably a better idea to use the `fopen()` C function\nto open our PNG file, instead of using the `openFile()` method that I introduced at @sec-filesystem.\nThat is why I'm importing the `stdio.h` C header in this project, and using the `fopen()` C function to open the file.\n\nIf you look at the snippet below, you can see that we are:\n\n1. opening the PNG file with `fopen()`.\n1. creating the `libspng` context with `spng_ctx_new()`.\n1. using `spng_set_png_file()` to specify the `FILE` object that reads the PNG file that we are going to use.\n\nEvery operation in `libspng` is made through a \"context object\". In our snippet below, this object is `ctx`.\nAlso, to perform an operation over a PNG file, we need to specify which exact PNG file we are referring to.\nThis is the job of `spng_set_png_file()`. We are using this function to specify the file descriptor\nobject that reads the PNG file that we want to use.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n    @cInclude(\"spng.h\");\n});\n\nconst path = \"pedro_pascal.png\";\nconst file_descriptor = c.fopen(path, \"rb\");\nif (file_descriptor == null) {\n    @panic(\"Could not open file!\");\n}\nconst ctx = c.spng_ctx_new(0) orelse unreachable;\n_ = c.spng_set_png_file(\n    ctx, @ptrCast(file_descriptor)\n);\n```\n:::\n\n\n\n\nBefore we continue, is important to emphasize the following: since we have opened the file with `fopen()`,\nwe have to remember to close the file at the end of the program, with `fclose()`.\nIn other words, after we have done everything that we wanted to do with the PNG file\n`pedro_pascal.png`, we need to close this file, by applying `fclose()` over the file descriptor object.\nWe could use also the `defer` keyword to help us in this task, if we want to.\nThis code snippet below demonstrates this step:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (c.fclose(file_descriptor) != 0) {\n    return error.CouldNotCloseFileDescriptor;\n}\n```\n:::\n\n\n\n\n\n\n\n### Reading the image header section\n\nNow, the context object `ctx` is aware of our PNG file `pedro_pascal.png`, because it has access to\na file descriptor object to this file. The first thing that we are going to do is to read the\n\"image header section\" of the PNG file. This \"image header section\" is the section\nof the file that contains some basic information about the PNG file, like, the bit depth of the pixel data\nof the image, the color model used in the file, the dimensions of the image (height and width in number of pixels),\netc.\n\nTo make things easier, I will encapsulate this \"read image header\" operation into a\nnice and small function called `get_image_header()`. All that this function needs to do\nis to call the `spng_get_ihdr()` function. This function from `libspng` is responsible\nfor reading the image header data, and storing it into a C struct named `spng_ihdr`.\nThus, an object of type `spng_ihdr` is a C struct that contains the data from the\nimage header section of the PNG file.\n\nSince this Zig function is receiving a C object (the `libspng` context object) as input, I marked\nthe function argument `ctx` as \"a pointer to the context object\" (`*c.spng_ctx`), following the recommendations\nthat we have discussed at @sec-pass-c-structs.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn get_image_header(ctx: *c.spng_ctx) !c.spng_ihdr {\n    var image_header: c.spng_ihdr = undefined;\n    if (c.spng_get_ihdr(ctx, &image_header) != 0) {\n        return error.CouldNotGetImageHeader;\n    }\n\n    return image_header;\n}\n\nvar image_header = try get_image_header(ctx);\n```\n:::\n\n\n\n\nAlso notice in this function, that I'm checking if the `spng_get_ihdr()` function call have\nreturned or not an integer value that is different than zero. Most functions from the\n`libspng` library return a code status as result, and the code status \"zero\" means\n\"success\". So any code status that is different than zero means that an error\noccurred while running `spng_get_ihdr()`. This is why I'm returning an error value from\nthe function in case the code status returned by the function is different than zero.\n\n\n### Allocating space for the pixel data\n\nBefore we read the pixel data from the PNG file, we need to allocate enough space to hold this data.\nBut in order to allocate such space, we first need to know how much space we need to allocate.\nThe dimensions of the image are obviously needed to calculate the size of this space. But there are\nother elements that also affect this number, such as the color model used in the image, the bit depth, and others.\n\nAnyway, all of this means that calculating the size of the space that we need, is not a simple task.\nThat is why the `libspng` library offers an utility function named\n`spng_decoded_image_size()` to calculate this size for us. Once again, I'm going\nto encapsulate the logic around this C function into a nice and small Zig function\nnamed `calc_output_size()`. You can see below that this function returns a nice\ninteger value as result, informing the size of the space that we need to allocate.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn calc_output_size(ctx: *c.spng_ctx) !u64 {\n    var output_size: u64 = 0;\n    const status = c.spng_decoded_image_size(\n        ctx, c.SPNG_FMT_RGBA8, &output_size\n    );\n    if (status != 0) {\n        return error.CouldNotCalcOutputSize;\n    }\n    return output_size;\n}\n```\n:::\n\n\n\n\n\n\nYou might quest yourself what the value `SPNG_FMT_RGBA8` means. This value is actually an enum\nvalue defined in the `spng.h` C header file. This enum is used to identify a \"PNG format\".\nMore precisely, it identifies a PNG file that uses the RGBA color model and 8 bit depth.\nSo, by providing this enum value as input to the `spng_decoded_image_size()` function,\nwe are saying to this function to calculate the size of the decoded pixel data, by considering\na PNG file that follows this \"RGBA color model with 8 bit depth\" format.\n\nHaving this function, we can use it in conjunction with an allocator object, to allocate an\narray of bytes (`u8` values) that is big enough to store the decoded pixel data of the image.\nNotice that I'm using `@memset()` to initialize the entire array to zero.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst output_size = try calc_output_size(ctx);\nvar buffer = try allocator.alloc(u8, output_size);\n@memset(buffer[0..], 0);\n```\n:::\n\n\n\n\n\n### Decoding the image data\n\nNow that we have the necessary space to store the decoded pixel data of the image,\nwe can start to actually decode and extract this pixel data from the image,\nby using the `spng_decode_image()` C function.\n\nThe `read_data_to_buffer()` Zig function exposed below summarises the necessary\nsteps to read this decoded pixel data, and store it into an input buffer.\nNotice that this function is encapsulating the logic around the `spng_decode_image()` function.\nAlso, we are using the `SPNG_FMT_RGBA8` enum value once again to inform the corresponding function,\nthat the PNG image being decoded, uses the RGBA color model and 8 bit depth.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn read_data_to_buffer(ctx: *c.spng_ctx, buffer: []u8) !void {\n    const status = c.spng_decode_image(\n        ctx,\n        buffer.ptr,\n        buffer.len,\n        c.SPNG_FMT_RGBA8,\n        0\n    );\n\n    if (status != 0) {\n        return error.CouldNotDecodeImage;\n    }\n}\n```\n:::\n\n\n\n\nHaving this function at hand, we can apply it over our context object, and also, over\nthe buffer object that we have allocated in the previous section to hold the decoded pixel data\nof the image:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry read_data_to_buffer(ctx, buffer[0..]);\n```\n:::\n\n\n\n\n\n### Looking at the pixel data\n\nNow that we have the pixel data stored in our \"buffer object\", we can take\na quick look at the bytes. In the example below, we are looking at the first\n12 bytes in the decoded pixel data.\n\nIf you take a close look at these values, you might notice that every 4 bytes\nin the sequence is 255. Which, coincidentally is the maximum possible integer value\nto be represented by a `u8` value. So, if the range from 0 to 255, which is the range\nof integer values that can be represented by an `u8` value, can be represented as a scale from 0% to 100%,\nthese 255 values are essentially 100% in that scale.\n\nIf you recall from @sec-pixel-repr, I have\ndescribed in that section that our `pedro_pascal.png` PNG file uses the RGBA color model,\nwhich adds an alpha (or transparency) byte to each pixel in the image.\nAs consequence, each pixel in the image is represented by 4 bytes. Since we are looking\nhere are the first 12 bytes in the image, it means that we are looking at the data from\nthe first $12 / 4 = 3$ pixels in the image.\n\nSo, based on how these first 12 bytes (or these 3 pixels) look, with these 255 values at every 4 bytes, we can say that is likely\nthat every pixel in the image have alpha (or transparency) setted to 100%. This might not be true,\nbut, is the most likely possibility. Also, if we look at the image itself, which if your recall is\nexposed at @fig-pascal, we can see that the transparency does not change across the image,\nwhich enforces this theory.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry stdout.print(\"{any}\\n\", .{buffer[0..12]});\n```\n:::\n\n\n\n\n```\n{\n    200, 194, 216, 255, 203, 197,\n    219, 255, 206, 200, 223, 255\n}\n```\n\n\nWe can see in the above result that the first pixel in this image have 200 of red, 194 of green, and 216 of blue.\nHow do I know the order in which the colors appears in the sequence? If you have not guessed that yet,\nis because of the acronym RGB. First RED, then GREEN, then BLUE. If we scale these integer values\naccording to our scale of 0% to 100% (0 to 255), we get 78% of red, 76% of green and 85% of blue.\n\n\n\n## Applying the image filter\n\nNow that we have the data of each pixel in the image, we can focus on applying our image\nfilter over these pixels. Remember, our objective here is to apply a grayscale filter over\nthe image. A grayscale filter is a filter that transforms a colored image into a grayscale image.\n\nThere are different formulas and strategies to transform a colored image into a grayscale image.\nBut all of these different strategies normally involve applying some math over the colors of each pixel.\nIn this project, we are going to use the most general formula, which is exposed below.\nThis formula considers $r$ as the red of the pixel, $g$ as the green, $b$ as the blue, and $p'$ as the\nlinear luminance of the pixel.\n\n$$\n    p' = (0.2126 \\times r) + (0.7152 \\times g) + (0.0722 \\times b)\n$${#eq-grayscale}\n\nThis @eq-grayscale is the formula to calculate the linear luminance of a pixel. Is worth noting that this formula\nworks only for images whose pixels are using the sRGB color space, which is the standard color space\nfor the web. Thus, ideally, all images on the web should use this color space. Luckily,\nthis is our case here, i.e. the `pedro_pascal.png` image is using this sRGB color space, and, as consequence,\nwe can use the @eq-grayscale. You can read more about this formula at the Wikipedia page for grayscale [@wiki_grayscale].\n\nThe `apply_image_filter()` function exposed below summarises the necessary steps to\napply @eq-grayscale over the pixels in the image. We just apply this function\nover our buffer object that contains our pixel data, and, as result, the pixel\ndata stored in this buffer object should now represent the grayscale version of our image.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn apply_image_filter(buffer:[]u8) !void {\n    const len = buffer.len;\n    const red_factor: f16 = 0.2126;\n    const green_factor: f16 = 0.7152;\n    const blue_factor: f16 = 0.0722;\n    var index: u64 = 0;\n    while (index < len) : (index += 4) {\n        const rf: f16 = @floatFromInt(buffer[index]);\n        const gf: f16 = @floatFromInt(buffer[index + 1]);\n        const bf: f16 = @floatFromInt(buffer[index + 2]);\n        const y_linear: f16 = (\n            (rf * red_factor) + (gf * green_factor)\n            + (bf * blue_factor)\n        );\n        buffer[index] = @intFromFloat(y_linear);\n        buffer[index + 1] = @intFromFloat(y_linear);\n        buffer[index + 2] = @intFromFloat(y_linear);\n    }\n}\n\ntry apply_image_filter(buffer[0..]);\n```\n:::\n\n\n\n\n\n\n## Saving the grayscale version of the image\n\nSince we have now the grayscale version of our image stored in our buffer object,\nwe need to encode this buffer object back into the \"PNG format\", and save the encoded data into\na new PNG file in our filesystem, so that we can access and see the grayscale version of our image\nthat was produced by our small program.\n\nTo do that, the `libspng` library help us once again by offering an \"encode data to PNG\" type of function,\nwhich is the `spng_encode_image()` function. But in order to \"encode data to PNG\" with `libspng`, we need\nto create a new context object. This new context object must use an \"encoder context\", which\nis identified by the enum value `SPNG_CTX_ENCODER`.\n\nThe `save_png()` function exposed below, summarises all the necessary steps to save the\ngrayscale version of our image into a new PNG file in the filesystem. By default, this\nfunction will save the grayscale image into a file named `pedro_pascal_filter.png` in the CWD.\n\nNotice in this code example that we are using the same image header object (`image_header`) that we have\ncollected previously with the `get_image_header()` function. Remember, this image header object\nis a C struct (`spng_ihdr`) that contains basic information about our PNG file, such as\nthe dimensions of the image, the color model used, etc.\n\nIf we wanted to save a very different image in this new PNG file, e.g. an image\nwith different dimensions, or, an image that uses a different color model, a different bit depth, etc.\nwe would have to create a new image header (`spng_ihdr`) object that describes the properties\nof this new image.\n\nBut we are essentially saving the same image that we have begin with here (the dimensions of\nthe image, the color model, etc. are all still the same). The only difference\nbetween the two images are the colors of the pixels, which are now \"shades of gray\".\nAs consequence, we can safely use the exact same image header data in this new PNG file.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn save_png(image_header: *c.spng_ihdr, buffer: []u8) !void {\n    const path = \"pedro_pascal_filter.png\";\n    const file_descriptor = c.fopen(path.ptr, \"wb\");\n    if (file_descriptor == null) {\n        return error.CouldNotOpenFile;\n    }\n    const ctx = (\n        c.spng_ctx_new(c.SPNG_CTX_ENCODER)\n        orelse unreachable\n    );\n    defer c.spng_ctx_free(ctx);\n    _ = c.spng_set_png_file(ctx, @ptrCast(file_descriptor));\n    _ = c.spng_set_ihdr(ctx, image_header);\n\n    const encode_status = c.spng_encode_image(\n        ctx,\n        buffer.ptr,\n        buffer.len,\n        c.SPNG_FMT_PNG,\n        c.SPNG_ENCODE_FINALIZE\n    );\n    if (encode_status != 0) {\n        return error.CouldNotEncodeImage;\n    }\n    if (c.fclose(file_descriptor) != 0) {\n        return error.CouldNotCloseFileDescriptor;\n    }\n}\n\ntry save_png(&image_header, buffer[0..]);\n```\n:::\n\n\n\n\nAfter we execute this `save_png()` function, we should have a new PNG file\ninside our CWD, named `pedro_pascal_filter.png`. If we open this PNG file,\nwe will see the same image exposed at @fig-pascal-gray.\n\n\n## Building our project\n\nNow that we have written the code, let's discuss how can we build/compile this project.\nTo do that, I'm going to create a `build.zig` file in the root directory of our project,\nand start writing the necessary code to compile the project, using the knowledge\nthat we have acquired from @sec-build-system.\n\n\nWe first create the build target for our executable file, that executes our\nZig code. Let's suppose that all of our Zig code was written into a Zig module\nnamed `image_filter.zig`. The `exe` object exposed in the build script below\ndescribes the build target for our executable file.\n\nSince we have used some C code from the `libspng` library in our Zig code,\nwe need to link our Zig code (which is in the `exe` build target) to both\nthe C Standard Library, and, to the `libspng` library. We do that, by calling\nthe `linkLibC()` and `linkSystemLibrary()` methods from our `exe` build target.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const target = b.standardTargetOptions(.{});\n    const optimize = b.standardOptimizeOption(.{});\n    const exe = b.addExecutable(.{\n        .name = \"image_filter\",\n        .root_source_file = b.path(\"src/image_filter.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n    exe.linkLibC();\n    // Link to libspng library:\n    exe.linkSystemLibrary(\"spng\");\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\nSince we are using the `linkSystemLibrary()` method, it means that the library\nfiles for `libspng` are searched in your system to be linked with the `exe` build target.\nIf you have not yet built and installed the `libspng` library into your system, this\nlinkage step will likely not work. Because it will not find the library files in your system.\n\nSo, just remember to install `libspng` in your system, if you want to build this project.\nHaving this build script above written, we can finally build our project by\nrunning the `zig build` command in the terminal.\n\n```bash\nzig build\n```\n\n\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
diff --git a/docs/Chapters/03-unittests.html b/docs/Chapters/03-unittests.html
index 0d3e2651..e7ddd754 100644
--- a/docs/Chapters/03-unittests.html
+++ b/docs/Chapters/03-unittests.html
@@ -323,8 +323,8 @@ <h2 data-number="8.1" class="anchored" data-anchor-id="introducing-the-test-bloc
 <span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect((a + b) == <span class="dv">4</span>);</span>
 <span id="cb1-7"><a href="#cb1-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file103bc24525048.test.testing simple sum...OK
-  KAll 1 tests passed.</code></pre>
+<pre><code>1/1 file153713a3190e.test.testing simple sum...OKA
+  All 1 tests passed.</code></pre>
 </div>
 </div>
 <p>You can have multiple <code>test</code> blocks written on the same Zig module. Also, you can mix <code>test</code> blocks with your source code, with no problems or consequences. If you mix <code>test</code> blocks with your normal source code, when you execute the <code>build</code>, <code>build-exe</code>, <code>build-obj</code> or <code>build-lib</code> commands from the <code>zig</code> compiler that we exposed at <a href="01-zig-weird.html#sec-compile-code" class="quarto-xref"><span>Section 1.2.4</span></a>, these <code>test</code> blocks are automatically ignored by the compiler.</p>
@@ -396,12 +396,10 @@ <h2 data-number="8.4" class="anchored" data-anchor-id="testing-errors"><span cla
 <span id="cb7-14"><a href="#cb7-14" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expectError(<span class="kw">error</span>.OutOfMemory, alloc_error(allocator));</span>
 <span id="cb7-15"><a href="#cb7-15" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file103bc545495c8.test.testing error...OKAll 1
-  1 tests passed.</code></pre>
+<pre><code>1/1 file1537546f248.test.testing error...OKAll 1 t
+  tests passed.</code></pre>
 </div>
 </div>
-<pre><code>1/1 oom.test.testing error... OK
-All 1 tests passed.</code></pre>
 </section>
 <section id="testing-simple-equalities" class="level2" data-number="8.5">
 <h2 data-number="8.5" class="anchored" data-anchor-id="testing-simple-equalities"><span class="header-section-number">8.5</span> Testing simple equalities</h2>
@@ -409,12 +407,12 @@ <h2 data-number="8.5" class="anchored" data-anchor-id="testing-simple-equalities
 <p>The <code>expectEqual()</code> function, as the name suggests, is a classic test equality function. It receives two objects as input. The first object is the value that you expect to be in the second object. While second object is the object you have, or, the object that your application produced as result. So, with <code>expectEqual()</code> you are essentially testing if the values stored inside these two objects are equal or not.</p>
 <p>You can see in the example below that, the test performed by <code>expectEqual()</code> failed. Because the objects <code>v1</code> and <code>v2</code> contain different values in them.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb10"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb10-2"><a href="#cb10-2" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="st">"values are equal?"</span> <span class="op">{</span></span>
-<span id="cb10-3"><a href="#cb10-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> v1 = <span class="dv">15</span>;</span>
-<span id="cb10-4"><a href="#cb10-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> v2 = <span class="dv">18</span>;</span>
-<span id="cb10-5"><a href="#cb10-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> std.testing.expectEqual(v1, v2);</span>
-<span id="cb10-6"><a href="#cb10-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb9"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb9-1"><a href="#cb9-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb9-2"><a href="#cb9-2" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="st">"values are equal?"</span> <span class="op">{</span></span>
+<span id="cb9-3"><a href="#cb9-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> v1 = <span class="dv">15</span>;</span>
+<span id="cb9-4"><a href="#cb9-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> v2 = <span class="dv">18</span>;</span>
+<span id="cb9-5"><a href="#cb9-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> std.testing.expectEqual(v1, v2);</span>
+<span id="cb9-6"><a href="#cb9-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>1/1 ve.test.values are equal?...
     expected 15, found 18
@@ -426,32 +424,30 @@ <h2 data-number="8.5" class="anchored" data-anchor-id="testing-simple-equalities
 <p>Although useful, the <code>expectEqual()</code> function does not work with arrays. For testing if two arrays are equal, you should use the <code>expectEqualSlices()</code> function instead. This function have three arguments. First, you provide the data type contained in both arrays that you are trying to compare. While the second and third arguments corresponds to the array objects that you want to compare.</p>
 <p>In the example below, we are using this function to test if two array objects (<code>array1</code> and <code>array2</code>) are equal or not. Since they are in fact equal, the unit test passed with no errors.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb12"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb12-2"><a href="#cb12-2" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="st">"arrays are equal?"</span> <span class="op">{</span></span>
-<span id="cb12-3"><a href="#cb12-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> array1 = [<span class="dv">3</span>]<span class="dt">u32</span><span class="op">{</span><span class="dv">1</span>, <span class="dv">2</span>, <span class="dv">3</span><span class="op">}</span>;</span>
-<span id="cb12-4"><a href="#cb12-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> array2 = [<span class="dv">3</span>]<span class="dt">u32</span><span class="op">{</span><span class="dv">1</span>, <span class="dv">2</span>, <span class="dv">3</span><span class="op">}</span>;</span>
-<span id="cb12-5"><a href="#cb12-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> std.testing.expectEqualSlices(</span>
-<span id="cb12-6"><a href="#cb12-6" aria-hidden="true" tabindex="-1"></a>        <span class="dt">u32</span>, &amp;array1, &amp;array2</span>
-<span id="cb12-7"><a href="#cb12-7" aria-hidden="true" tabindex="-1"></a>    );</span>
-<span id="cb12-8"><a href="#cb12-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb11"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb11-2"><a href="#cb11-2" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="st">"arrays are equal?"</span> <span class="op">{</span></span>
+<span id="cb11-3"><a href="#cb11-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> array1 = [<span class="dv">3</span>]<span class="dt">u32</span><span class="op">{</span><span class="dv">1</span>, <span class="dv">2</span>, <span class="dv">3</span><span class="op">}</span>;</span>
+<span id="cb11-4"><a href="#cb11-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> array2 = [<span class="dv">3</span>]<span class="dt">u32</span><span class="op">{</span><span class="dv">1</span>, <span class="dv">2</span>, <span class="dv">3</span><span class="op">}</span>;</span>
+<span id="cb11-5"><a href="#cb11-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> std.testing.expectEqualSlices(</span>
+<span id="cb11-6"><a href="#cb11-6" aria-hidden="true" tabindex="-1"></a>        <span class="dt">u32</span>, &amp;array1, &amp;array2</span>
+<span id="cb11-7"><a href="#cb11-7" aria-hidden="true" tabindex="-1"></a>    );</span>
+<span id="cb11-8"><a href="#cb11-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file103bc78cf09de.test.arrays are equal?...OKA
-  All 1 tests passed.</code></pre>
+<pre><code>1/1 file15377bbafb73.test.arrays are equal?...OKAl
+  ll 1 tests passed.</code></pre>
 </div>
 </div>
-<pre><code>1/1 oom.test.arrays are equal?... OK
-All 1 tests passed.</code></pre>
 <p>At last, you might also want to use the <code>expectEqualStrings()</code> function. As the name suggests, you can use this function to test if two strings are equal or not. Just provide the two string objects that you want to compare, as inputs to the function.</p>
 <p>If the function finds any existing differences between the two strings, then, the function will raise an error, and also, print an error message that shows the exact difference between the two string objects provided, as the example below demonstrates:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb15"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb15-1"><a href="#cb15-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb15-2"><a href="#cb15-2" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="st">"strings are equal?"</span> <span class="op">{</span></span>
-<span id="cb15-3"><a href="#cb15-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> str1 = <span class="st">"hello, world!"</span>;</span>
-<span id="cb15-4"><a href="#cb15-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> str2 = <span class="st">"Hello, world!"</span>;</span>
-<span id="cb15-5"><a href="#cb15-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> std.testing.expectEqualStrings(</span>
-<span id="cb15-6"><a href="#cb15-6" aria-hidden="true" tabindex="-1"></a>        str1, str2</span>
-<span id="cb15-7"><a href="#cb15-7" aria-hidden="true" tabindex="-1"></a>    );</span>
-<span id="cb15-8"><a href="#cb15-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb13"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb13-2"><a href="#cb13-2" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="st">"strings are equal?"</span> <span class="op">{</span></span>
+<span id="cb13-3"><a href="#cb13-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> str1 = <span class="st">"hello, world!"</span>;</span>
+<span id="cb13-4"><a href="#cb13-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> str2 = <span class="st">"Hello, world!"</span>;</span>
+<span id="cb13-5"><a href="#cb13-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> std.testing.expectEqualStrings(</span>
+<span id="cb13-6"><a href="#cb13-6" aria-hidden="true" tabindex="-1"></a>        str1, str2</span>
+<span id="cb13-7"><a href="#cb13-7" aria-hidden="true" tabindex="-1"></a>    );</span>
+<span id="cb13-8"><a href="#cb13-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>1/1 t.test.strings are equal?... 
 ====== expected this output: =========
diff --git a/docs/Chapters/13-image-filter.html b/docs/Chapters/13-image-filter.html
index af1fa84c..58efbfaa 100644
--- a/docs/Chapters/13-image-filter.html
+++ b/docs/Chapters/13-image-filter.html
@@ -606,7 +606,7 @@ <h2 data-number="15.5" class="anchored" data-anchor-id="applying-the-image-filte
 <span id="cb11-4"><a href="#cb11-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> green_factor: <span class="dt">f16</span> = <span class="fl">0.7152</span>;</span>
 <span id="cb11-5"><a href="#cb11-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> blue_factor: <span class="dt">f16</span> = <span class="fl">0.0722</span>;</span>
 <span id="cb11-6"><a href="#cb11-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> index: <span class="dt">u64</span> = <span class="dv">0</span>;</span>
-<span id="cb11-7"><a href="#cb11-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">while</span> (index &lt;= (len - <span class="dv">4</span>)) : (index += <span class="dv">4</span>) <span class="op">{</span></span>
+<span id="cb11-7"><a href="#cb11-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">while</span> (index &lt; len) : (index += <span class="dv">4</span>) <span class="op">{</span></span>
 <span id="cb11-8"><a href="#cb11-8" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> rf: <span class="dt">f16</span> = <span class="bu">@floatFromInt</span>(buffer[index]);</span>
 <span id="cb11-9"><a href="#cb11-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> gf: <span class="dt">f16</span> = <span class="bu">@floatFromInt</span>(buffer[index + <span class="dv">1</span>]);</span>
 <span id="cb11-10"><a href="#cb11-10" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> bf: <span class="dt">f16</span> = <span class="bu">@floatFromInt</span>(buffer[index + <span class="dv">2</span>]);</span>
diff --git a/docs/index.html b/docs/index.html
index 2f9822ba..6ba96909 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -7,7 +7,7 @@
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 <meta name="author" content="Pedro Duarte Faria">
-<meta name="dcterms.date" content="2024-12-04">
+<meta name="dcterms.date" content="2024-12-05">
 
 <title>Introduction to Zig</title>
 <style>
@@ -287,7 +287,7 @@ <h1 class="title">Introduction to Zig</h1>
     <div>
     <div class="quarto-title-meta-heading">Published</div>
     <div class="quarto-title-meta-contents">
-      <p class="date">December 4, 2024</p>
+      <p class="date">December 5, 2024</p>
     </div>
   </div>
   
diff --git a/docs/search.json b/docs/search.json
index 77f47fa2..64d6d24a 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -634,7 +634,7 @@
     "href": "Chapters/03-unittests.html",
     "title": "8  Unit tests",
     "section": "",
-    "text": "8.1 Introducing the test block\nIn Zig, unit tests are written inside a test declaration, or, how I prefer to call it, inside a test block. Every test block is written by using the keyword test. You can optionally use a string literal to write a label, which is responsible for identifying the specific group of unit tests that you are writing inside this specific test block.\nIn the example below, we are testing if the sum of two objects (a and b) is equal to 4. The expect() function from the Zig Standard Library is a function that receives a logical test as input. If this logical test results in true, then, the test passes. But if it results in false, then, the test fails.\nYou can write any Zig code you want inside a test block. Part of this code might be some necessary commands to setup your testing environment, or just initializing some objects that you need to use in your unit tests.\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest \"testing simple sum\" {\n    const a: u8 = 2;\n    const b: u8 = 2;\n    try expect((a + b) == 4);\n}\n\n1/1 file103bc24525048.test.testing simple sum...OK\n  KAll 1 tests passed.\nYou can have multiple test blocks written on the same Zig module. Also, you can mix test blocks with your source code, with no problems or consequences. If you mix test blocks with your normal source code, when you execute the build, build-exe, build-obj or build-lib commands from the zig compiler that we exposed at Section 1.2.4, these test blocks are automatically ignored by the compiler.\nIn other words, the zig compiler builds and execute your unit tests only when you ask it to. By default, the compiler always ignore test blocks written in your Zig modules. The compiler normally checks only if there are any syntax errors in these test blocks.\nIf you take a look at the source code for most of the files present in the Zig Standard Library1, you can see that the test blocks are written together with the normal source code of the library. You can see this for example, at the array_list module2. So, the standard that the Zig developers decided to adopt is to keep their unit tests together with the source code of the functionality that they are testing.\nEach programmer might have a different opinion on this. Some of them might prefer to keep unit tests separate from the actual source code of their application. If that is your case, you can simply create a separate tests folder in your project, and start writing Zig modules that contains only unit tests (as you would normally do on a Python project with pytest, for example), and everything will work fine. It boils down to which is your preference here.",
+    "text": "8.1 Introducing the test block\nIn Zig, unit tests are written inside a test declaration, or, how I prefer to call it, inside a test block. Every test block is written by using the keyword test. You can optionally use a string literal to write a label, which is responsible for identifying the specific group of unit tests that you are writing inside this specific test block.\nIn the example below, we are testing if the sum of two objects (a and b) is equal to 4. The expect() function from the Zig Standard Library is a function that receives a logical test as input. If this logical test results in true, then, the test passes. But if it results in false, then, the test fails.\nYou can write any Zig code you want inside a test block. Part of this code might be some necessary commands to setup your testing environment, or just initializing some objects that you need to use in your unit tests.\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest \"testing simple sum\" {\n    const a: u8 = 2;\n    const b: u8 = 2;\n    try expect((a + b) == 4);\n}\n\n1/1 file153713a3190e.test.testing simple sum...OKA\n  All 1 tests passed.\nYou can have multiple test blocks written on the same Zig module. Also, you can mix test blocks with your source code, with no problems or consequences. If you mix test blocks with your normal source code, when you execute the build, build-exe, build-obj or build-lib commands from the zig compiler that we exposed at Section 1.2.4, these test blocks are automatically ignored by the compiler.\nIn other words, the zig compiler builds and execute your unit tests only when you ask it to. By default, the compiler always ignore test blocks written in your Zig modules. The compiler normally checks only if there are any syntax errors in these test blocks.\nIf you take a look at the source code for most of the files present in the Zig Standard Library1, you can see that the test blocks are written together with the normal source code of the library. You can see this for example, at the array_list module2. So, the standard that the Zig developers decided to adopt is to keep their unit tests together with the source code of the functionality that they are testing.\nEach programmer might have a different opinion on this. Some of them might prefer to keep unit tests separate from the actual source code of their application. If that is your case, you can simply create a separate tests folder in your project, and start writing Zig modules that contains only unit tests (as you would normally do on a Python project with pytest, for example), and everything will work fine. It boils down to which is your preference here.",
     "crumbs": [
       "<span class='chapter-number'>8</span>  <span class='chapter-title'>Unit tests</span>"
     ]
@@ -664,7 +664,7 @@
     "href": "Chapters/03-unittests.html#testing-errors",
     "title": "8  Unit tests",
     "section": "8.4 Testing errors",
-    "text": "8.4 Testing errors\nOne common style of unit tests are those that look for specific errors in your functions. In other words, you write a unit test that tries to assert if a specific function call returns any error, or a specific type of error.\nIn C++ you would normally write this style of unit tests using, for example, the functions REQUIRE_THROWS() or CHECK_THROWS() from the Catch2 test framework3. In the case of a Python project, you would probably use the raises() function from pytest4. While in Rust, you would probably use assert_eq!() in conjunction with Err().\nBut in Zig, we use the expectError() function, from the std.testing module. With this function, you can test if a specific function call returns the exact type of error that you expect it to return. To use this function, you first write try expectError(). Then, on the first argument, you provide the type of error that you are expecting from the function call. Then, on the second argument, you write the function call that you expect to fail.\nThe code example below demonstrates such type of unit test in Zig. Notice that, inside the function alloc_error() we are allocating 100 bytes of memory, or, an array of 100 elements, for the object ibuffer. However, in the test block, we are using the FixedBufferAllocator() allocator object, which is limited to 10 bytes of space, because the object buffer, which we provided to the allocator object, have only 10 bytes of space.\nThat is why, the alloc_error() function raises an OutOfMemory error on this case. Because this function is trying to allocate more space than the allocator object allows. So, in essence, we are testing for a specific type of error, which is OutOfMemory. If the alloc_error() function returns any other type of error, then, the expectError() function would make the entire test fail.\n\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst expectError = std.testing.expectError;\nfn alloc_error(allocator: Allocator) !void {\n    var ibuffer = try allocator.alloc(u8, 100);\n    defer allocator.free(ibuffer);\n    ibuffer[0] = 2;\n}\n\ntest \"testing error\" {\n    var buffer: [10]u8 = undefined;\n    var fba = std.heap.FixedBufferAllocator.init(&buffer);\n    const allocator = fba.allocator();\n    try expectError(error.OutOfMemory, alloc_error(allocator));\n}\n\n1/1 file103bc545495c8.test.testing error...OKAll 1\n  1 tests passed.\n\n\n1/1 oom.test.testing error... OK\nAll 1 tests passed.",
+    "text": "8.4 Testing errors\nOne common style of unit tests are those that look for specific errors in your functions. In other words, you write a unit test that tries to assert if a specific function call returns any error, or a specific type of error.\nIn C++ you would normally write this style of unit tests using, for example, the functions REQUIRE_THROWS() or CHECK_THROWS() from the Catch2 test framework3. In the case of a Python project, you would probably use the raises() function from pytest4. While in Rust, you would probably use assert_eq!() in conjunction with Err().\nBut in Zig, we use the expectError() function, from the std.testing module. With this function, you can test if a specific function call returns the exact type of error that you expect it to return. To use this function, you first write try expectError(). Then, on the first argument, you provide the type of error that you are expecting from the function call. Then, on the second argument, you write the function call that you expect to fail.\nThe code example below demonstrates such type of unit test in Zig. Notice that, inside the function alloc_error() we are allocating 100 bytes of memory, or, an array of 100 elements, for the object ibuffer. However, in the test block, we are using the FixedBufferAllocator() allocator object, which is limited to 10 bytes of space, because the object buffer, which we provided to the allocator object, have only 10 bytes of space.\nThat is why, the alloc_error() function raises an OutOfMemory error on this case. Because this function is trying to allocate more space than the allocator object allows. So, in essence, we are testing for a specific type of error, which is OutOfMemory. If the alloc_error() function returns any other type of error, then, the expectError() function would make the entire test fail.\n\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst expectError = std.testing.expectError;\nfn alloc_error(allocator: Allocator) !void {\n    var ibuffer = try allocator.alloc(u8, 100);\n    defer allocator.free(ibuffer);\n    ibuffer[0] = 2;\n}\n\ntest \"testing error\" {\n    var buffer: [10]u8 = undefined;\n    var fba = std.heap.FixedBufferAllocator.init(&buffer);\n    const allocator = fba.allocator();\n    try expectError(error.OutOfMemory, alloc_error(allocator));\n}\n\n1/1 file1537546f248.test.testing error...OKAll 1 t\n  tests passed.",
     "crumbs": [
       "<span class='chapter-number'>8</span>  <span class='chapter-title'>Unit tests</span>"
     ]
@@ -674,7 +674,7 @@
     "href": "Chapters/03-unittests.html#testing-simple-equalities",
     "title": "8  Unit tests",
     "section": "8.5 Testing simple equalities",
-    "text": "8.5 Testing simple equalities\nIn Zig, there are some different ways you can test for an equality. You already saw that we can use expect() with the logical operator == to essentially reproduce an equality test. But we also have some other helper functions that you should know about, especially expectEqual(), expectEqualSlices() and expectEqualStrings().\nThe expectEqual() function, as the name suggests, is a classic test equality function. It receives two objects as input. The first object is the value that you expect to be in the second object. While second object is the object you have, or, the object that your application produced as result. So, with expectEqual() you are essentially testing if the values stored inside these two objects are equal or not.\nYou can see in the example below that, the test performed by expectEqual() failed. Because the objects v1 and v2 contain different values in them.\n\nconst std = @import(\"std\");\ntest \"values are equal?\" {\n    const v1 = 15;\n    const v2 = 18;\n    try std.testing.expectEqual(v1, v2);\n}\n\n1/1 ve.test.values are equal?...\n    expected 15, found 18\n    FAIL (TestExpectedEqual)\nve.zig:5:5: test.values are equal? (test)\n    try std.testing.expectEqual(v1, v2);\n    ^\n0 passed; 0 skipped; 1 failed.\nAlthough useful, the expectEqual() function does not work with arrays. For testing if two arrays are equal, you should use the expectEqualSlices() function instead. This function have three arguments. First, you provide the data type contained in both arrays that you are trying to compare. While the second and third arguments corresponds to the array objects that you want to compare.\nIn the example below, we are using this function to test if two array objects (array1 and array2) are equal or not. Since they are in fact equal, the unit test passed with no errors.\n\nconst std = @import(\"std\");\ntest \"arrays are equal?\" {\n    const array1 = [3]u32{1, 2, 3};\n    const array2 = [3]u32{1, 2, 3};\n    try std.testing.expectEqualSlices(\n        u32, &array1, &array2\n    );\n}\n\n1/1 file103bc78cf09de.test.arrays are equal?...OKA\n  All 1 tests passed.\n\n\n1/1 oom.test.arrays are equal?... OK\nAll 1 tests passed.\nAt last, you might also want to use the expectEqualStrings() function. As the name suggests, you can use this function to test if two strings are equal or not. Just provide the two string objects that you want to compare, as inputs to the function.\nIf the function finds any existing differences between the two strings, then, the function will raise an error, and also, print an error message that shows the exact difference between the two string objects provided, as the example below demonstrates:\n\nconst std = @import(\"std\");\ntest \"strings are equal?\" {\n    const str1 = \"hello, world!\";\n    const str2 = \"Hello, world!\";\n    try std.testing.expectEqualStrings(\n        str1, str2\n    );\n}\n\n1/1 t.test.strings are equal?... \n====== expected this output: =========\nhello, world!␃\n======== instead found this: =========\nHello, world!␃\n======================================\nFirst difference occurs on line 1:\nexpected:\nhello, world!\n^ ('\\x68')\nfound:\nHello, world!\n^ ('\\x48')",
+    "text": "8.5 Testing simple equalities\nIn Zig, there are some different ways you can test for an equality. You already saw that we can use expect() with the logical operator == to essentially reproduce an equality test. But we also have some other helper functions that you should know about, especially expectEqual(), expectEqualSlices() and expectEqualStrings().\nThe expectEqual() function, as the name suggests, is a classic test equality function. It receives two objects as input. The first object is the value that you expect to be in the second object. While second object is the object you have, or, the object that your application produced as result. So, with expectEqual() you are essentially testing if the values stored inside these two objects are equal or not.\nYou can see in the example below that, the test performed by expectEqual() failed. Because the objects v1 and v2 contain different values in them.\n\nconst std = @import(\"std\");\ntest \"values are equal?\" {\n    const v1 = 15;\n    const v2 = 18;\n    try std.testing.expectEqual(v1, v2);\n}\n\n1/1 ve.test.values are equal?...\n    expected 15, found 18\n    FAIL (TestExpectedEqual)\nve.zig:5:5: test.values are equal? (test)\n    try std.testing.expectEqual(v1, v2);\n    ^\n0 passed; 0 skipped; 1 failed.\nAlthough useful, the expectEqual() function does not work with arrays. For testing if two arrays are equal, you should use the expectEqualSlices() function instead. This function have three arguments. First, you provide the data type contained in both arrays that you are trying to compare. While the second and third arguments corresponds to the array objects that you want to compare.\nIn the example below, we are using this function to test if two array objects (array1 and array2) are equal or not. Since they are in fact equal, the unit test passed with no errors.\n\nconst std = @import(\"std\");\ntest \"arrays are equal?\" {\n    const array1 = [3]u32{1, 2, 3};\n    const array2 = [3]u32{1, 2, 3};\n    try std.testing.expectEqualSlices(\n        u32, &array1, &array2\n    );\n}\n\n1/1 file15377bbafb73.test.arrays are equal?...OKAl\n  ll 1 tests passed.\n\n\nAt last, you might also want to use the expectEqualStrings() function. As the name suggests, you can use this function to test if two strings are equal or not. Just provide the two string objects that you want to compare, as inputs to the function.\nIf the function finds any existing differences between the two strings, then, the function will raise an error, and also, print an error message that shows the exact difference between the two string objects provided, as the example below demonstrates:\n\nconst std = @import(\"std\");\ntest \"strings are equal?\" {\n    const str1 = \"hello, world!\";\n    const str2 = \"Hello, world!\";\n    try std.testing.expectEqualStrings(\n        str1, str2\n    );\n}\n\n1/1 t.test.strings are equal?... \n====== expected this output: =========\nhello, world!␃\n======== instead found this: =========\nHello, world!␃\n======================================\nFirst difference occurs on line 1:\nexpected:\nhello, world!\n^ ('\\x68')\nfound:\nHello, world!\n^ ('\\x48')",
     "crumbs": [
       "<span class='chapter-number'>8</span>  <span class='chapter-title'>Unit tests</span>"
     ]
@@ -1244,7 +1244,7 @@
     "href": "Chapters/13-image-filter.html#applying-the-image-filter",
     "title": "15  Project 4 - Developing an image filter",
     "section": "15.5 Applying the image filter",
-    "text": "15.5 Applying the image filter\nNow that we have the data of each pixel in the image, we can focus on applying our image filter over these pixels. Remember, our objective here is to apply a grayscale filter over the image. A grayscale filter is a filter that transforms a colored image into a grayscale image.\nThere are different formulas and strategies to transform a colored image into a grayscale image. But all of these different strategies normally involve applying some math over the colors of each pixel. In this project, we are going to use the most general formula, which is exposed below. This formula considers \\(r\\) as the red of the pixel, \\(g\\) as the green, \\(b\\) as the blue, and \\(p'\\) as the linear luminance of the pixel.\n\\[\n    p' = (0.2126 \\times r) + (0.7152 \\times g) + (0.0722 \\times b)\n\\tag{15.1}\\]\nThis Equation 15.1 is the formula to calculate the linear luminance of a pixel. Is worth noting that this formula works only for images whose pixels are using the sRGB color space, which is the standard color space for the web. Thus, ideally, all images on the web should use this color space. Luckily, this is our case here, i.e. the pedro_pascal.png image is using this sRGB color space, and, as consequence, we can use the Equation 15.1. You can read more about this formula at the Wikipedia page for grayscale (Wikipedia 2024).\nThe apply_image_filter() function exposed below summarises the necessary steps to apply Equation 15.1 over the pixels in the image. We just apply this function over our buffer object that contains our pixel data, and, as result, the pixel data stored in this buffer object should now represent the grayscale version of our image.\n\nfn apply_image_filter(buffer:[]u8) !void {\n    const len = buffer.len;\n    const red_factor: f16 = 0.2126;\n    const green_factor: f16 = 0.7152;\n    const blue_factor: f16 = 0.0722;\n    var index: u64 = 0;\n    while (index &lt;= (len - 4)) : (index += 4) {\n        const rf: f16 = @floatFromInt(buffer[index]);\n        const gf: f16 = @floatFromInt(buffer[index + 1]);\n        const bf: f16 = @floatFromInt(buffer[index + 2]);\n        const y_linear: f16 = (\n            (rf * red_factor) + (gf * green_factor)\n            + (bf * blue_factor)\n        );\n        buffer[index] = @intFromFloat(y_linear);\n        buffer[index + 1] = @intFromFloat(y_linear);\n        buffer[index + 2] = @intFromFloat(y_linear);\n    }\n}\n\ntry apply_image_filter(buffer[0..]);",
+    "text": "15.5 Applying the image filter\nNow that we have the data of each pixel in the image, we can focus on applying our image filter over these pixels. Remember, our objective here is to apply a grayscale filter over the image. A grayscale filter is a filter that transforms a colored image into a grayscale image.\nThere are different formulas and strategies to transform a colored image into a grayscale image. But all of these different strategies normally involve applying some math over the colors of each pixel. In this project, we are going to use the most general formula, which is exposed below. This formula considers \\(r\\) as the red of the pixel, \\(g\\) as the green, \\(b\\) as the blue, and \\(p'\\) as the linear luminance of the pixel.\n\\[\n    p' = (0.2126 \\times r) + (0.7152 \\times g) + (0.0722 \\times b)\n\\tag{15.1}\\]\nThis Equation 15.1 is the formula to calculate the linear luminance of a pixel. Is worth noting that this formula works only for images whose pixels are using the sRGB color space, which is the standard color space for the web. Thus, ideally, all images on the web should use this color space. Luckily, this is our case here, i.e. the pedro_pascal.png image is using this sRGB color space, and, as consequence, we can use the Equation 15.1. You can read more about this formula at the Wikipedia page for grayscale (Wikipedia 2024).\nThe apply_image_filter() function exposed below summarises the necessary steps to apply Equation 15.1 over the pixels in the image. We just apply this function over our buffer object that contains our pixel data, and, as result, the pixel data stored in this buffer object should now represent the grayscale version of our image.\n\nfn apply_image_filter(buffer:[]u8) !void {\n    const len = buffer.len;\n    const red_factor: f16 = 0.2126;\n    const green_factor: f16 = 0.7152;\n    const blue_factor: f16 = 0.0722;\n    var index: u64 = 0;\n    while (index &lt; len) : (index += 4) {\n        const rf: f16 = @floatFromInt(buffer[index]);\n        const gf: f16 = @floatFromInt(buffer[index + 1]);\n        const bf: f16 = @floatFromInt(buffer[index + 2]);\n        const y_linear: f16 = (\n            (rf * red_factor) + (gf * green_factor)\n            + (bf * blue_factor)\n        );\n        buffer[index] = @intFromFloat(y_linear);\n        buffer[index + 1] = @intFromFloat(y_linear);\n        buffer[index + 2] = @intFromFloat(y_linear);\n    }\n}\n\ntry apply_image_filter(buffer[0..]);",
     "crumbs": [
       "<span class='chapter-number'>15</span>  <span class='chapter-title'>Project 4 - Developing an image filter</span>"
     ]

From 97b5a349aaa55c81caf8a687ecc00b2c892d5254 Mon Sep 17 00:00:00 2001
From: Santiago Fernandez <santif@gmail.com>
Date: Mon, 9 Dec 2024 21:29:35 +0000
Subject: [PATCH 016/151] Add devcontainer configuration

This commit introduces a new devcontainer configuration file (.devcontainer/devcontainer.json) that sets up a Debian-based development environment. The configuration includes features for Quarto CLI, R Rig, and Zig, along with a post-creation command to install necessary packages and dependencies.
---
 .devcontainer/devcontainer.json | 12 ++++++++++++
 1 file changed, 12 insertions(+)
 create mode 100644 .devcontainer/devcontainer.json

diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
new file mode 100644
index 00000000..6717914a
--- /dev/null
+++ b/.devcontainer/devcontainer.json
@@ -0,0 +1,12 @@
+{
+	"name": "Debian",
+	"image": "mcr.microsoft.com/devcontainers/base:bullseye",
+
+	"features": {
+		"ghcr.io/rocker-org/devcontainer-features/quarto-cli:1": {},
+		"ghcr.io/rocker-org/devcontainer-features/r-rig:1": {},
+		"ghcr.io/devcontainers-extra/features/zig:1": {}
+	},
+
+	"postCreateCommand": "sudo apt-get update && sudo apt-get install -y librsvg2-bin && Rscript dependencies.R && Rscript -e \"install.packages('tinytex'); tinytex::install_tinytex()\""
+}

From c4fa49fc92d86fcf51952ed08f8acfd8fb505df9 Mon Sep 17 00:00:00 2001
From: Pedro Faria <69123925+pedropark99@users.noreply.github.com>
Date: Tue, 17 Dec 2024 10:58:08 -0300
Subject: [PATCH 017/151] Update README.md

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index f4a1b2b7..6fcfbd62 100644
--- a/README.md
+++ b/README.md
@@ -55,7 +55,7 @@ If you do have a Revolut account, you can scan the following QR code:
 
 ## About this book
 
-This an open (i.e. it is open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),
+This is an open (i.e. it is open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),
 which is a new general purpose, and low-level programming language for building optimal and robust software.
 
 Official repository of the book: <https://github.com/pedropark99/zig-book>.

From 19e64365e33aa0ef72bfb1ea1257ae6a8ea297c5 Mon Sep 17 00:00:00 2001
From: Pedro Faria <69123925+pedropark99@users.noreply.github.com>
Date: Mon, 30 Dec 2024 13:36:02 -0300
Subject: [PATCH 018/151] Update 07-build-system.qmd

---
 Chapters/07-build-system.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/07-build-system.qmd b/Chapters/07-build-system.qmd
index ca8aa669..e7c4c65a 100644
--- a/Chapters/07-build-system.qmd
+++ b/Chapters/07-build-system.qmd
@@ -167,7 +167,7 @@ from the `Build` struct, to define a path in the `root_source_file` option.
 
 ```{zig}
 #| eval: false
-exe = b.addExecutable(.{
+const exe = b.addExecutable(.{
     .name = "hello",
     .root_source_file = b.path("hello.zig"),
     .target = b.host,

From 5f323266a8d9d5e08a749d6e9797c242232884ab Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Fri, 10 Jan 2025 14:26:35 -0300
Subject: [PATCH 019/151] Recompile book with fixed code example

---
 .../Chapters/07-build-system/execute-results/html.json    | 8 +++++---
 docs/Chapters/07-build-system.html                        | 2 +-
 docs/index.html                                           | 4 ++--
 docs/search.json                                          | 2 +-
 4 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/_freeze/Chapters/07-build-system/execute-results/html.json b/_freeze/Chapters/07-build-system/execute-results/html.json
index c55ec51f..cb50222a 100644
--- a/_freeze/Chapters/07-build-system/execute-results/html.json
+++ b/_freeze/Chapters/07-build-system/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "a611e399df4867dc622a55e0bcaf00ba",
+  "hash": "a1b79257fb194da6246ef8c44be69c2f",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Build System {#sec-build-system}\n\n\nIn this chapter, we are going to talk about the build system, and how an entire project\nis built in Zig.\nOne key advantage of Zig is that it includes a build system embedded in the language itself.\nThis is great, because then you do not have to depend on an external system, separated\nfrom the compiler, to build your code.\n\n\nYou can find a good description of Zig's build system\non the [article entitled \"Build System\"](https://ziglang.org/learn/build-system/#user-provided-options)[^zig-art1]\nfrom the official Zig's website.\nWe also have the excellent [series of posts written by Felix](https://zig.news/xq/zig-build-explained-part-1-59lf)[^felix].\nHence, this chapter represents an extra resource for you to consult and rely on.\n\n[^felix]: <https://zig.news/xq/zig-build-explained-part-1-59lf>\n[^zig-art1]: <https://ziglang.org/learn/build-system/#user-provided-options>\n\nBuilding code is one of the things that Zig is best at. One thing that is particularly\ndifficult in C/C++ and even in Rust, is to cross-compile source code to multiple targets\n(e.g. multiple computer architectures and operational systems),\nand the `zig` compiler is known for being one of the best existing pieces of software\nfor this particular task.\n\n\n\n\n## How source code is built?\n\nWe already have talked about the challenges of building source code in low-level languages\nat @sec-project-files. As we described at that section, programmers invented Build Systems\nto surpass these challenges on the process of building source code in low-level languages.\n\nLow-level languages uses a compiler to compile (or to build) your source code into binary instructions.\nIn C and C++, we normally use compilers like `gcc`, `g++` or `clang` to compile\nour C and C++ source code into these instructions.\nEvery language have its own compiler, and this is no different in Zig.\n\nIn Zig, we have the `zig` compiler to compile our Zig source code into\nbinary instructions that can be executed by our computer.\nIn Zig, the compilation (or the build) process involves\nthe following components:\n\n- The Zig modules that contains your source code;\n- Library files (either a dynamic library or a static library);\n- Compiler flags that tailors the build process to your needs.\n\nThese are the things that you need to connect together in order to build your\nsource code in Zig. In C and C++, you would have an extra component, which are the header files of\nthe libraries that you are using. But header files do not exist in Zig, so, you only need\nto care about them if you are linking your Zig source code with a C library.\nIf that is not your case, you can forget about it.\n\nYour build process is usually organized in a build script. In Zig, we normally\nwrite this build script into a Zig module in the root directory of our project,\nnamed as `build.zig`. You write this build script, then, when you run it, your project\nget's built into binary files that you can use and distribute to your users.\n\nThis build script is normally organized around *target objects*. A target is simply\nsomething to be built, or, in other words, it's something that you want the `zig` compiler\nto build for you. This concept of \"targets\" is present in most Build Systems,\nespecially in CMake[^cmake].\n\n[^cmake]: <https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html>\n\nThere are four types of target objects that you can build in Zig, which are:\n\n- An executable (e.g. a `.exe` file on Windows).\n- A shared library (e.g. a `.so` file in Linux or a `.dll` file on Windows).\n- A static library (e.g. a `.a` file in Linux or a `.lib` file on Windows).\n- An executable file that executes only unit tests (or, a \"unit tests executable\").\n\nWe are going to talk more about these target objects at @sec-targets.\n\n\n\n## The `build()` function {#sec-build-fun}\n\nA build script in Zig always contains a public (and top-level) `build()` function declared.\nIt is like the `main()` function on the main Zig module of your project, that we discussed at @sec-main-file.\nBut instead of creating the entrypoint to your code, this `build()` function is the entrypoint to the build process.\n\nThis `build()` function should accept a pointer to a `Build` object as input, and it should use this \"build object\" to perform\nthe necessary steps to build your project. The return type of this function is always `void`,\nand this `Build` struct comes directly from the Zig Standard Library (`std.Build`). So, you can \naccess this struct by just importing the Zig Standard Library into your `build.zig` module.\n\nJust as a very simple example, here you can see the source code necessary to build\nan executable file from the `hello.zig` Zig module.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"hello.zig\"),\n        .target = b.host,\n    });\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\nYou can define and use other functions and objects in this build script. You can also import\nother Zig modules as you would normally do in any other module of your project.\nThe only real requirement for this build script, is to have a public and top-level\n`build()` function defined, that accepts a pointer to a `Build` struct as input.\n\n\n## Target objects {#sec-targets}\n\nAs we described over the previous sections, a build script is composed around target objects.\nEach target object is normally a binary file (or an output) that you want to get from the build process. You can list\nmultiple target objects in your build script, so that the build process generates multiple\nbinary files for you at once.\n\nFor example, maybe you are a developer working in a cross-platform application,\nand, because this application is cross-platform, you probably need to release\nbinary files of your software for each OS supported by your application to your end users.\nThus, you can define a different target object in your build script\nfor each OS (Windows, Linux, etc.) where you want to publish your software.\nThis will make the `zig` compiler to build your project to multiple target OS's at once.\nThe Zig Build System official documentation have a [great code example that demonstrates this strategy](https://ziglang.org/learn/build-system/#handy-examples)[^zig-ex].\n\n[^zig-ex]: <https://ziglang.org/learn/build-system/#handy-examples>\n\n\nA target object is created by the following methods of the `Build` struct that we introduced\nat @sec-build-fun:\n\n- `addExecutable()` creates an executable file;\n- `addSharedLibrary()` creates a shared library file;\n- `addStaticLibrary()` creates a static library file;\n- `addTest()` creates an executable file that executes unit tests.\n\n\nThese functions are methods from the `Build` struct that you receive\nas input of the `build()` function. All of them, create as output\na `Compile` object, which represents a target object to be compiled\nby the `zig` compiler. All of these functions accept a similar struct literal as input.\nThis struct literal defines three essential specs about this target object that you are building:\n`name`, `target` and `root_source_file`.\n\nWe have already seen these three options being used on the previous example,\nwhere we used the `addExecutable()` method to create an executable target object.\nThis example is reproduced below. Notice the use of the `path()` method\nfrom the `Build` struct, to define a path in the `root_source_file` option.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nexe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n```\n:::\n\n\n\n\nThe `name` option specify the name that you want to give to the binary file defined\nby this target object. So, in this example, we are building an executable file named `hello`.\nIs common to set this `name` option to the name of your project.\n\n\nFurthermore, the `target` option specify the target computer architecture (or the target operational system) of this\nbinary file. For example, if you want this target object to run on a Windows machine\nthat uses a `x86_64` architecture, you can set this `target` option to `x86_64-windows-gnu` for example.\nThis will make the `zig` compiler to compile the project to run on a `x86_64` Windows machine.\nYou can see the full list of architectures and OS's that the `zig` compiler supports by running\nthe `zig targets` command in the terminal.\n\nNow, if you are building the project to run on the current machine\nthat you are using to run this build script, you can set this `target`\noption to the `host` method of the `Build` object, like we did in the example above.\nThis `host` method identifies the current machine where you are\ncurrently running the `zig` compiler.\n\n\nAt last, the `root_source_file` option specifies the root Zig module of your project.\nThat is the Zig module that contains the entrypoint to your application (i.e. the `main()` function), or, the main API of your library.\nThis also means that, all the Zig modules that compose your project are automatically discovered\nfrom the import statements you have inside this \"root source file\".\nThe `zig` compiler can detect when a Zig module depends on the other through the import statements,\nand, as a result, it can discover the entire map of Zig modules used in your project.\n\nThis is handy, and it is different from what happens in other build systems.\nIn CMake for example, you have to explicitly list the paths to all source files that you want to\ninclude in your build process. This is probably a symptom of the \"lack of conditional\ncompilation\" in the C and C++ compilers. Since they lack this feature, you have\nto explicitly choose which source files should be sent to the C/C++ compiler, because not\nevery C/C++ code is portable or supported in every operational system, and, therefore,\nwould cause a compilation error in the C/C++ compiler.\n\n\nNow, one important detail about the build process is that, you have to **explicitly\ninstall the target objects that you create in your build script**, by using the\n`installArtifact()` method of the `Build` struct.\n\nEverytime you invoke the build process of your project, by calling the `build` command\nof the `zig` compiler, a new directory named `zig-out` is created in the root\ndirectory of your project. This new directory contains the outputs of the build process,\nthat is, the binary files built from your source code.\n\nWhat the `installArtifact()` method do is to install (or copy) the built target objects\nthat you defined to this `zig-out` directory.\nThis means that, if you do not\ninstall the target objects you define in your build script, these target objects are\nessentially discarded at the end of the build process.\n\nFor example, you might be building a project that uses a third party library that is built\ntogether with the project. So, when you build your project, you would need first, to\nbuild the third party library, and then, you link it with the source code of your project.\nSo, in this case, we have two binary files that are generated in the build process (the executable file of your project, and the third party library).\nBut only one is of interest, which is the executable file of our project.\nWe can discard the binary file of the third party library, by simply not installing it\ninto this `zig-out` directory.\n\nThis `installArtifact()` method is pretty straightforward. Just remember to apply it to every\ntarget object that you want to save into the `zig-out` directory, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nexe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n## Setting the build mode\n\nWe have talked about the three essential options that are set when you create a new target object.\nBut there is also a fourth option that you can use to set the build mode of this target object,\nwhich is the `optimize` option.\nThis option is called this way, because the build modes in Zig are treated more of\nan \"optimization vs safety\" problem. So optimization plays an important role here.\nDon't worry, I'm going back to this question very soon.\n\nIn Zig, we have four build modes (which are listed below). Each one of these build modes offer\ndifferent advantages and characteristics. As we described at @sec-compile-debug-mode, the `zig` compiler\nuses the `Debug` build mode by default, when you don't explicitly choose a build mode.\n\n- `Debug`, mode that produces and includes debugging information in the output of the build process (i.e. the binary file defined by the target object);\n- `ReleaseSmall`, mode that tries to produce a binary file that is small in size;\n- `ReleaseFast`, mode that tries to optimize your code, in order to produce a binary file that is as fast as possible;\n- `ReleaseSafe`, mode that tries to make your code as safe as possible, by including safeguards when possible.\n\nSo, when you build your project, you can set the build mode of your target object to `ReleaseFast` for example, which will tell\nthe `zig` compiler to apply important optimizations in your code. This creates a binary file\nthat simply runs faster on most contexts, because it contains a more optimized version of your code.\nHowever, as a result, we often lose some safety features in our code.\nBecause some safety checks are removed from the final binary file,\nwhich makes your code run faster, but in a less safe manner.\n\nThis choice depends on your current priorities. If you are building a cryptography or banking system, you might\nprefer to prioritize safety in your code, so, you would choose the `ReleaseSafe` build mode, which is a little\nslower to run, but much more secure, because it includes all possible runtime safety checks in the binary file\nbuilt in the build process. In the other hand, if you are writing a game for example, you might prefer to prioritize performance\nover safety, by using the `ReleaseFast` build mode, so that your users can experience faster frame rates in your game.\n\nIn the example below, we are creating the same target object that we have used on previous examples.\nBut this time, we are specifying the build mode of this target object to the `ReleaseSafe` mode.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .optimize = .ReleaseSafe\n});\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n## Setting the version of your build\n\nEverytime you build a target object in your build script, you can assign a version\nnumber to this specific build, following a semantic versioning framework.\nYou can find more about semantic versioning by visiting the [Semantic Versioning website](https://semver.org/)[^semver].\nAnyway, in Zig, you can specify the version of your build, by providing a `SemanticVersion` struct to\nthe `version` option, like in the example below:\n\n\n[^semver]: <https://semver.org/>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .version = .{\n        .major = 2, .minor = 9, .patch = 7\n    }\n});\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n## Detecting the OS in your build script {#sec-detect-os}\n\nIs very common in Build Systems to use different options, or, to include different modules, or,\nto link against different libraries depending on the Operational System (OS)\nthat you are targeting in the build process.\n\nIn Zig, you can detect the target OS of the build process, by looking\nat the `os.tag` inside the `builtin` module from the Zig library.\nIn the example below, we are using an if statement to run some\narbitrary code when the target of the build process is a\nWindows system.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nif (builtin.target.os.tag == .windows) {\n    // Code that runs only when the target of\n    // the compilation process is Windows.\n}\n```\n:::\n\n\n\n\n\n## Adding a run step to your build process\n\nOne thing that is neat in Rust is that you can compile and run your\nsource code with one single command (`cargo run`) from the Rust compiler.\nWe saw at @sec-compile-run-code how can we perform a similar job in Zig, by\nbuilding and running our Zig source code through the `run` command from the `zig` compiler.\n\nBut how can we, at the same time, build and run the binary file specified by a target object in our\nbuild script?\nThe answer is by including a \"run artifact\" in our build script.\nA run artifact is created through the `addRunArtifact()` method from the `Build` struct.\nWe simply provide as input to this function the target object that describes the binary file that we\nwant to execute. As a result, this function creates a run artifact that is capable of executing\nthis binary file.\n\nIn the example below, we are defining an executable binary file named `hello`,\nand we use this `addRunArtifact()` method to create a run artifact that will execute\nthis `hello` executable file.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"src/hello.zig\"),\n    .target = b.host\n});\nb.installArtifact(exe);\nconst run_arti = b.addRunArtifact(exe);\n```\n:::\n\n\n\n\nNow that we have created this run artifact, we need to include it in\nthe build process. We do that by declaring a new step in our build\nscript to call this artifact, through the `step()` method of the `Build`\nstruct.\n\nWe can give any name we want to this step, but, for our\ncontext here, I'm going to name this step as \"run\".\nAlso, I give it a brief description to this step (\"Run the project\").\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst run_step = b.step(\n    \"run\", \"Run the project\"\n);\n```\n:::\n\n\n\n\n\nNow that we have declared this \"run step\" we need to tell Zig that\nthis \"run step\" depends on the run artifact.\nIn other words, a run artifact always depends on a \"step\" to effectively be executed.\nBy creating this dependency\nwe finally stablish the necessary commands to build and run the executable file\nfrom the build script.\n\nWe can establish a dependency between the run step and the run artifact\nby using the `dependsOn()` method from the run step. So, we first\ncreate the run step, and then, we link it with the run artifact, by\nusing this `dependsOn()` method from the run step.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nrun_step.dependOn(&run_arti.step);\n```\n:::\n\n\n\n\nThe entire source code of this specific build script that\nwe wrote, piece by piece, in this section, is\navailable in the `build_and_run.zig` module. You can\nsee this module by\n[visiting the official repository of this book](https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig)\n[^module-src].\n\n\n[^module-src]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig>\n\nWhen you declare a new step in your build script, this step\nbecomes available through the `build` command in the `zig` compiler.\nYou can actually see this step by running `zig build --help` in the terminal, like\nin the example below, where we can see that this new \"run\"\nstep that we declared in the build script appeared in the output.\n\n```bash\nzig build --help\n```\n\n```\nSteps:\n  ...\n  run   Run the project\n  ...\n```\n\nNow, everything that we need to is to\ncall this \"run\" step that we created in our build script. We\ncall it by using the name that we gave to this step\nafter the `build` command from the `zig` compiler.\nThis will cause the compiler to build our executable file\nand execute it at the same time.\n\n```bash\nzig build run\n```\n\n## Build unit tests in your project\n\nWe have talked at length about writing unit tests in Zig at @sec-unittests,\nand we also have talked about how to execute these unit tests through\nthe `test` command of the `zig` compiler. However,\nas we did with the `run` command on the previous section, we also might want to\ninclude some commands in our build script to also build and execute the unit tests in our project.\n\nSo, once again, we are going to discuss how a specific built-in command from the `zig` compiler,\n(in this case, the `test` command) can be used in a build script in Zig.\nHere is where a \"test target object\" comes into play.\nAs was described at @sec-targets, we can create a test target object by using the `addTest()` method of\nthe `Build` struct. The first thing that we need to do is to\ndeclare a test target object in our build script.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst test_exe = b.addTest(.{\n    .name = \"unit_tests\",\n    .root_source_file = b.path(\"src/main.zig\"),\n    .target = b.host,\n});\nb.installArtifact(test_exe);\n```\n:::\n\n\n\n\n\nA test target object essentially selects all `test` blocks in all Zig modules\nacross your project, and builds only the source code present inside\nthese `test` blocks in your project. As a result, this target object\ncreates an executable file that contains only the source code present\nin all of these `test` blocks (i.e. the unit tests) in your project.\n\nPerfect! Now that we have declared this test target object, an executable file\nnamed `unit_tests` is built by the `zig` compiler when we trigger the build\nscript with the `build` command. After the build\nprocess is finished, we can simply execute this `unit_tests` executable\nin the terminal.\n\nHowever, if you remember the previous section, we already learned\nhow can we create a run step in our build script, to execute an executable file\nbuilt by the build script.\n\nSo, we could simply add a run step in our build script to run these unit tests\nfrom a single command in the `zig` compiler, to make our lifes easier.\nIn the example below, we demonstrate the commands to\nregister a new build step called \"tests\" in our build script\nto run these unit tests.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst run_arti = b.addRunArtifact(test_exe);\nconst run_step = b.step(\"tests\", \"Run unit tests\");\nrun_step.dependOn(&run_arti.step);\n```\n:::\n\n\n\n\nNow that we registered this new build step, we can trigger it by calling the command below\nin the terminal. You can also checkout the complete source\ncode for this specific build script at the `build_tests.zig` module at the\n[official repository of this book](https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig)\n[^module-src2].\n\n\n[^module-src2]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig>\n\n\n```bash\nzig build tests\n```\n\n\n## Tailoring your build process with user-provided options\n\nSometimes, you want to make a build script that is customizable by the user\nof your project. You can do that by creating user-provided options in\nyour build script. We create an user-provided option by using the\n`option()` method from the `Build` struct.\n\nWith this method, we create a \"build option\" which can be passed\nto the `build.zig` script at the command line. The user have the power of setting\nthis option at the `build` command from the\n`zig` compiler. In other words, each build option that we create\nbecomes a new command line argument that is accessible through the `build` command\nof the compiler.\n\nThese \"user-provided options\" are set by using the prefix `-D` in the command line.\nFor example, if we declare an option named `use_zlib`, that receives a boolean value which\nindicates if we should link our source code to `zlib` or not, we can set the value\nof this option in the command line with `-Duse_zlib`. The code example below\ndemonstrates this idea:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const use_zlib = b.option(\n        bool,\n        \"use_zlib\",\n        \"Should link to zlib?\"\n    ) orelse false;\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"example.zig\"),\n        .target = b.host,\n    });\n    if (use_zlib) {\n        exe.linkSystemLibrary(\"zlib\");\n    }\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\n```bash\nzig build -Duse_zlib=false\n```\n\n\n## Linking to external libraries\n\n\nOne essential part of every build process is the linking stage.\nThis stage is responsible for combining the multiple object files\nthat represent your code, into a single executable file. It also links\nthis executable file to external libraries, if you use any in your code.\n\nIn Zig, we have two notions of a \"library\", which are: 1) a system's library;\n2) a local library. A system's library is just a library that already is installed\nin your system. While a local library is a library that belongs to the current\nproject. Is a library that is present in your project directory, and\nthat you are building together with your project source code.\n\nThe basic difference between the two, is that a system's library is already\nbuilt and installed in your system, supposedly, and all you need to do\nis to link your source code to this library to start using it.\nWe do that by using the `linkSystemLibrary()` method from a\n`Compile` object. This method accepts the name of the library\nin a string as input. Remember from @sec-targets that a `Compile` object\nis a target object that you declare in your build script.\n\nWhen you link a particular target object with a system's library,\nthe `zig` compiler will use `pkg-config` to find where\nare the binary files and also the header files of this library\nin your system.\nWhen it finds these files, the linker present in the `zig` compiler\nwill link your object files with the files of this library to\nproduce a single binary file for you.\n\nIn the example below, we are creating an executable file named `image_filter`,\nand, we are linking this executable file to the C Standard Library with the\nmethod `linkLibC()`, but we also are linking this executable file to the\nC library `libpng` that is currently installed in my system.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"image_filter\",\n        .root_source_file = b.path(\"src/main.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n    exe.linkLibC();\n    exe.linkSystemLibrary(\"png\");\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\nIf you are linking with a C library in your project, is generally a good idea\nto also link your code with the C Standard Library. Because is very likely\nthat this C library uses some functionality of the C Standard Library at some point.\nThe same goes to C++ libraries. So, if you are linking with\nC++ libraries, is a good idea to link your project with the C++\nStandard Library by using the `linkLibCpp()` method.\n\nOn the order side, when you want to link with a local library,\nyou should use the `linkLibrary()` method of a `Compile` object.\nThis method expects to receive another `Compile` object as input.\nThat is, another target object defined in your build script,\nusing either the `addStaticLibrary()` or `addSharedLibrary()` methods\nwhich defines a library to be built.\n\nAs we discussed earlier, a local library is a library\nthat is local to your project, and that is being built together\nwith your project. So, you need to create a target object in your build script\nto build this local library. Then, you link the target objects of interest in your project,\nwith this target object that identifies this local library.\n\nTake a look at this example extracted from the build script of the [`libxev` library](https://github.com/mitchellh/libxev/tree/main)[^libxev2].\nYou can see in this snippet that\nwe are declaring a shared library file, from the `c_api.zig`\nmodule. Then, later in the build script, we declare an\nexecutable file named `\"dynamic-binding-test\"`, which\nlinks to this shared library that we defined earlier\nin the script.\n\n[^libxev2]: <https://github.com/mitchellh/libxev/tree/main>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst optimize = b.standardOptimizeOption(.{});\nconst target = b.standardTargetOptions(.{});\n\nconst dynamic_lib = b.addSharedLibrary(.{\n    .name = dynamic_lib_name,\n    .root_source_file = b.path(\"src/c_api.zig\"),\n    .target = target,\n    .optimize = optimize,\n});\nb.installArtifact(dynamic_lib);\n// ... more lines in the script\nconst dynamic_binding_test = b.addExecutable(.{\n    .name = \"dynamic-binding-test\",\n    .target = target,\n    .optimize = optimize,\n});\ndynamic_binding_test.linkLibrary(dynamic_lib);\n```\n:::\n\n\n\n\n\n\n## Building C code {#sec-building-c-code}\n\nThe `zig` compiler comes with a C compiler embedded in it. In other words,\nyou can use the `zig` compiler to build C projects. This C compiler is available\nthrough the `cc` command of the `zig` compiler.\n\nAs an example, let's use the famous [FreeType library](https://freetype.org/)[^freetype].\nFreeType is one of the most widely used pieces of software in the world.\nIt is a C library designed to produce high-quality fonts. But it is also\nheavily used in the industry to natively render text and fonts\nin the screen of your computer.\n\nIn this section, we are going to write a build script, piece by piece, that is capable\nof building the FreeType project from source.\nYou can find the source code of this build script on the\n[`freetype-zig` repository](https://github.com/pedropark99/freetype-zig/tree/main)[^freetype-zig]\navailable at GitHub.\n\n[^freetype]: <https://freetype.org/>\n[^freetype-zig]: <https://github.com/pedropark99/freetype-zig/tree/main>\n\nAfter you download the source code of FreeType from the official website[^freetype],\nyou can start writing the `build.zig` module. We begin by defining the target object\nthat defines the binary file that we want to compile.\n\nAs an example, I will build the project as a static library file using the `addStaticLibrary()` method\nto create the target object.\nAlso, since FreeType is a C library, I will also link the library\nagainst `libc` through the `linkLibC()` method, to guarantee that any use\nof the C Standard Library is covered in the compilation process.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst target = b.standardTargetOptions(.{});\nconst opti = b.standardOptimizeOption(.{});\nconst lib = b.addStaticLibrary(.{\n    .name = \"freetype\",\n    .optimize = opti,\n    .target = target,\n});\nlib.linkLibC();\n```\n:::\n\n\n\n\n### Creating C compiler flags\n\nCompiler flags are also known as \"compiler options\" by many programmers,\nor also, as \"command options\" in the GCC official documentation.\nIt's fair to also call them as the \"command-line arguments\" of the C compiler.\nIn general, we use compiler flags to turn on (or turn off) some features from the compiler,\nor to tweak the compilation process to fit the needs of our project.\n\nIn build scripts written in Zig, we normally list the C compiler flags to be used in the compilation process\nin a simple array, like in the example below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c_flags = [_][]const u8{\n    \"-Wall\",\n    \"-Wextra\",\n    \"-Werror\",\n};\n```\n:::\n\n\n\n\nIn theory, there is nothing stopping you from using this array to add \"include paths\" (with the `-I` flag)\nor \"library paths\" (with the `-L` flag) to the compilation process. But there are formal ways in Zig to\nadd these types of paths in the compilation process. Both are discussed at @sec-include-paths\nand @sec-library-paths.\n\nAnyway, in Zig, we add C flags to the build process together with the C files that we want to compile, by using the\n`addCSourceFile()` and `addCSourceFiles()` methods. In the example above, we have just declared\nthe C flags that we want to use. But we haven't added them to the build process yet.\nTo do that, we also need to list the C files to be compiled.\n\n### Listing your C files\n\nThe C files that contains \"cross-platform\" source code are listed in the `c_source_files`\nobject below. These are the C files that are included by default in every platform\nsupported by the FreeType library. Now, since the amount of C files in the FreeType library is big,\nI have omitted the rest of the files in the code example below, for brevity purposes.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c_source_files = [_][]const u8{\n    \"src/autofit/autofit.c\",\n    \"src/base/ftbase.c\",\n    // ... and many other C files.\n};\n```\n:::\n\n\n\n\nNow, in addition to \"cross-platform\" source code, we also have some C files in the FreeType project\nthat are platform-specific, meaning that, they contain source code that can only be compiled in specific platforms,\nand, as a result, they are only included in the build process on these specific target platforms.\nThe objects that list these C files are exposed in the code example below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst windows_c_source_files = [_][]const u8{\n    \"builds/windows/ftdebug.c\",\n    \"builds/windows/ftsystem.c\"\n};\nconst linux_c_source_files = [_][]const u8{\n    \"src/base/ftsystem.c\",\n    \"src/base/ftdebug.c\"\n};\n```\n:::\n\n\n\n\nNow that we declared both the files that we want to include and the C compiler flags to be used,\nwe can add them to the target object that describes the FreeType library, by using the\n`addCSourceFile()` and `addCSourceFiles()` methods.\n\nBoth of these functions are methods from a `Compile` object (i.e. a target object).\nThe `addCSourceFile()` method is capable of adding a single C file to the target object,\nwhile the `addCSourceFiles()` method is used to add multiple C files in a single command.\nYou might prefer to use `addCSourceFile()` when you need to use different compiler flags\non specific C files in your project. But, if you can use the same compiler flags\nacross all C files, then, you will probably find `addCSourceFiles()` a better choice.\n\nNotice that we are using the `addCSourceFiles()` method in the example below,\nto add both the C files and the C compiler flags. Also notice that we\nare using the `os.tag` that we learned about at @sec-detect-os, to add the platform-specific\nC files.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nlib.addCSourceFiles(\n    &c_source_files, &c_flags\n);\n\nswitch (builtin.target.os.tag) {\n    .windows => {\n        lib.addCSourceFiles(\n            &windows_c_source_files,\n            &c_flags\n        );\n    },\n    .linux => {\n        lib.addCSourceFiles(\n            &linux_c_source_files,\n            &c_flags\n        );\n    },\n    else => {},\n}\n```\n:::\n\n\n\n\n\n### Defining C Macros\n\nC Macros are an essential part of the C programming language,\nand they are commonly defined through the `-D` flag from a C compiler.\nIn Zig, you can define a C Macro to be used in your build process\nby using the `defineCMacro()` method from the target object that\ndefines the binary file that you are building.\n\nIn the example below, we are using the `lib` object that we have defined\non the previous sections to define some C Macros used by the FreeType project\nin the compilation process. These C Macros specify if FreeType\nshould (or should not) include functionalities from different\nexternal libraries.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nlib.defineCMacro(\"FT_DISABLE_ZLIB\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_PNG\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_HARFBUZZ\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BZIP2\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BROTLI\", \"TRUE\");\nlib.defineCMacro(\"FT2_BUILD_LIBRARY\", \"TRUE\");\n```\n:::\n\n\n\n\n\n### Adding library paths {#sec-library-paths}\n\nLibrary paths are paths in your computer where the C compiler will look (or search) for\nlibrary files to link against your source code. In other words, when you use a library in your\nC source code, and you ask the C compiler to link your source code against this library,\nthe C compiler will search for the binary files of this library across the paths listed\nin this \"library paths\" set.\n\nThese paths are platform specific, and, by default, the C compiler starts by looking at a\npre-defined set of places in your computer. But you can add more paths (or more places)\nto this list. For example, you may have a library installed in a non-conventional place of your\ncomputer, and you can make the C compiler \"see\" this \"non-conventional place\" by adding this path\nto this list of pre-defined paths.\n\nIn Zig, you can add more paths to this set by using the `addLibraryPath()` method from your target object.\nFirst, you defined a `LazyPath` object, containing the path you want to add, then,\nyou provide this object as input to the `addLibraryPath()` method, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst lib_path: std.Build.LazyPath = .{\n    .cwd_relative = \"/usr/local/lib/\"\n};\nlib.addLibraryPath(lib_path);\n```\n:::\n\n\n\n\n\n\n\n### Adding include paths {#sec-include-paths}\n\nThe preprocessor search path is a popular concept from the\nC community, but it is also known by many C programmers as \"include paths\", because\nthe paths in this \"search path\" relate to the `#include` statements found in the C files.\n\nInclude paths are similar to library paths. They are a set of pre-defined places in your computer where\nthe C compiler will look for files during the compilation process. But instead of looking for\nlibrary files, the include paths are places where the compiler looks for header files included\nin your C source code.\nThis is why many C programmers prefer to call these paths as the \"preprocessor search path\".\nBecause header files are processed during the preprocessor stage of the compilation\nprocess.\n\nSo, every header file that you include in your C source code, through a `#include` statements needs to\nbe found somewhere, and the C compiler will search for this header file across the paths listed in this \"include paths\" set.\nInclude paths are added to the compilation process through the `-I` flag.\n\nIn Zig, you can add new paths to this pre-defined set of paths, by using the `addIncludePath()` method\nfrom your target object. This method also accepts a `LazyPath` object as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst inc_path: std.Build.LazyPath = .{\n    .path = \"./include\"\n};\nlib.addIncludePath(inc_path);\n```\n:::\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Build System {#sec-build-system}\n\n\nIn this chapter, we are going to talk about the build system, and how an entire project\nis built in Zig.\nOne key advantage of Zig is that it includes a build system embedded in the language itself.\nThis is great, because then you do not have to depend on an external system, separated\nfrom the compiler, to build your code.\n\n\nYou can find a good description of Zig's build system\non the [article entitled \"Build System\"](https://ziglang.org/learn/build-system/#user-provided-options)[^zig-art1]\nfrom the official Zig's website.\nWe also have the excellent [series of posts written by Felix](https://zig.news/xq/zig-build-explained-part-1-59lf)[^felix].\nHence, this chapter represents an extra resource for you to consult and rely on.\n\n[^felix]: <https://zig.news/xq/zig-build-explained-part-1-59lf>\n[^zig-art1]: <https://ziglang.org/learn/build-system/#user-provided-options>\n\nBuilding code is one of the things that Zig is best at. One thing that is particularly\ndifficult in C/C++ and even in Rust, is to cross-compile source code to multiple targets\n(e.g. multiple computer architectures and operational systems),\nand the `zig` compiler is known for being one of the best existing pieces of software\nfor this particular task.\n\n\n\n\n## How source code is built?\n\nWe already have talked about the challenges of building source code in low-level languages\nat @sec-project-files. As we described at that section, programmers invented Build Systems\nto surpass these challenges on the process of building source code in low-level languages.\n\nLow-level languages uses a compiler to compile (or to build) your source code into binary instructions.\nIn C and C++, we normally use compilers like `gcc`, `g++` or `clang` to compile\nour C and C++ source code into these instructions.\nEvery language have its own compiler, and this is no different in Zig.\n\nIn Zig, we have the `zig` compiler to compile our Zig source code into\nbinary instructions that can be executed by our computer.\nIn Zig, the compilation (or the build) process involves\nthe following components:\n\n- The Zig modules that contains your source code;\n- Library files (either a dynamic library or a static library);\n- Compiler flags that tailors the build process to your needs.\n\nThese are the things that you need to connect together in order to build your\nsource code in Zig. In C and C++, you would have an extra component, which are the header files of\nthe libraries that you are using. But header files do not exist in Zig, so, you only need\nto care about them if you are linking your Zig source code with a C library.\nIf that is not your case, you can forget about it.\n\nYour build process is usually organized in a build script. In Zig, we normally\nwrite this build script into a Zig module in the root directory of our project,\nnamed as `build.zig`. You write this build script, then, when you run it, your project\nget's built into binary files that you can use and distribute to your users.\n\nThis build script is normally organized around *target objects*. A target is simply\nsomething to be built, or, in other words, it's something that you want the `zig` compiler\nto build for you. This concept of \"targets\" is present in most Build Systems,\nespecially in CMake[^cmake].\n\n[^cmake]: <https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html>\n\nThere are four types of target objects that you can build in Zig, which are:\n\n- An executable (e.g. a `.exe` file on Windows).\n- A shared library (e.g. a `.so` file in Linux or a `.dll` file on Windows).\n- A static library (e.g. a `.a` file in Linux or a `.lib` file on Windows).\n- An executable file that executes only unit tests (or, a \"unit tests executable\").\n\nWe are going to talk more about these target objects at @sec-targets.\n\n\n\n## The `build()` function {#sec-build-fun}\n\nA build script in Zig always contains a public (and top-level) `build()` function declared.\nIt is like the `main()` function on the main Zig module of your project, that we discussed at @sec-main-file.\nBut instead of creating the entrypoint to your code, this `build()` function is the entrypoint to the build process.\n\nThis `build()` function should accept a pointer to a `Build` object as input, and it should use this \"build object\" to perform\nthe necessary steps to build your project. The return type of this function is always `void`,\nand this `Build` struct comes directly from the Zig Standard Library (`std.Build`). So, you can \naccess this struct by just importing the Zig Standard Library into your `build.zig` module.\n\nJust as a very simple example, here you can see the source code necessary to build\nan executable file from the `hello.zig` Zig module.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"hello.zig\"),\n        .target = b.host,\n    });\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\nYou can define and use other functions and objects in this build script. You can also import\nother Zig modules as you would normally do in any other module of your project.\nThe only real requirement for this build script, is to have a public and top-level\n`build()` function defined, that accepts a pointer to a `Build` struct as input.\n\n\n## Target objects {#sec-targets}\n\nAs we described over the previous sections, a build script is composed around target objects.\nEach target object is normally a binary file (or an output) that you want to get from the build process. You can list\nmultiple target objects in your build script, so that the build process generates multiple\nbinary files for you at once.\n\nFor example, maybe you are a developer working in a cross-platform application,\nand, because this application is cross-platform, you probably need to release\nbinary files of your software for each OS supported by your application to your end users.\nThus, you can define a different target object in your build script\nfor each OS (Windows, Linux, etc.) where you want to publish your software.\nThis will make the `zig` compiler to build your project to multiple target OS's at once.\nThe Zig Build System official documentation have a [great code example that demonstrates this strategy](https://ziglang.org/learn/build-system/#handy-examples)[^zig-ex].\n\n[^zig-ex]: <https://ziglang.org/learn/build-system/#handy-examples>\n\n\nA target object is created by the following methods of the `Build` struct that we introduced\nat @sec-build-fun:\n\n- `addExecutable()` creates an executable file;\n- `addSharedLibrary()` creates a shared library file;\n- `addStaticLibrary()` creates a static library file;\n- `addTest()` creates an executable file that executes unit tests.\n\n\nThese functions are methods from the `Build` struct that you receive\nas input of the `build()` function. All of them, create as output\na `Compile` object, which represents a target object to be compiled\nby the `zig` compiler. All of these functions accept a similar struct literal as input.\nThis struct literal defines three essential specs about this target object that you are building:\n`name`, `target` and `root_source_file`.\n\nWe have already seen these three options being used on the previous example,\nwhere we used the `addExecutable()` method to create an executable target object.\nThis example is reproduced below. Notice the use of the `path()` method\nfrom the `Build` struct, to define a path in the `root_source_file` option.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n```\n:::\n\n\n\n\nThe `name` option specify the name that you want to give to the binary file defined\nby this target object. So, in this example, we are building an executable file named `hello`.\nIs common to set this `name` option to the name of your project.\n\n\nFurthermore, the `target` option specify the target computer architecture (or the target operational system) of this\nbinary file. For example, if you want this target object to run on a Windows machine\nthat uses a `x86_64` architecture, you can set this `target` option to `x86_64-windows-gnu` for example.\nThis will make the `zig` compiler to compile the project to run on a `x86_64` Windows machine.\nYou can see the full list of architectures and OS's that the `zig` compiler supports by running\nthe `zig targets` command in the terminal.\n\nNow, if you are building the project to run on the current machine\nthat you are using to run this build script, you can set this `target`\noption to the `host` method of the `Build` object, like we did in the example above.\nThis `host` method identifies the current machine where you are\ncurrently running the `zig` compiler.\n\n\nAt last, the `root_source_file` option specifies the root Zig module of your project.\nThat is the Zig module that contains the entrypoint to your application (i.e. the `main()` function), or, the main API of your library.\nThis also means that, all the Zig modules that compose your project are automatically discovered\nfrom the import statements you have inside this \"root source file\".\nThe `zig` compiler can detect when a Zig module depends on the other through the import statements,\nand, as a result, it can discover the entire map of Zig modules used in your project.\n\nThis is handy, and it is different from what happens in other build systems.\nIn CMake for example, you have to explicitly list the paths to all source files that you want to\ninclude in your build process. This is probably a symptom of the \"lack of conditional\ncompilation\" in the C and C++ compilers. Since they lack this feature, you have\nto explicitly choose which source files should be sent to the C/C++ compiler, because not\nevery C/C++ code is portable or supported in every operational system, and, therefore,\nwould cause a compilation error in the C/C++ compiler.\n\n\nNow, one important detail about the build process is that, you have to **explicitly\ninstall the target objects that you create in your build script**, by using the\n`installArtifact()` method of the `Build` struct.\n\nEverytime you invoke the build process of your project, by calling the `build` command\nof the `zig` compiler, a new directory named `zig-out` is created in the root\ndirectory of your project. This new directory contains the outputs of the build process,\nthat is, the binary files built from your source code.\n\nWhat the `installArtifact()` method do is to install (or copy) the built target objects\nthat you defined to this `zig-out` directory.\nThis means that, if you do not\ninstall the target objects you define in your build script, these target objects are\nessentially discarded at the end of the build process.\n\nFor example, you might be building a project that uses a third party library that is built\ntogether with the project. So, when you build your project, you would need first, to\nbuild the third party library, and then, you link it with the source code of your project.\nSo, in this case, we have two binary files that are generated in the build process (the executable file of your project, and the third party library).\nBut only one is of interest, which is the executable file of our project.\nWe can discard the binary file of the third party library, by simply not installing it\ninto this `zig-out` directory.\n\nThis `installArtifact()` method is pretty straightforward. Just remember to apply it to every\ntarget object that you want to save into the `zig-out` directory, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nexe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n## Setting the build mode\n\nWe have talked about the three essential options that are set when you create a new target object.\nBut there is also a fourth option that you can use to set the build mode of this target object,\nwhich is the `optimize` option.\nThis option is called this way, because the build modes in Zig are treated more of\nan \"optimization vs safety\" problem. So optimization plays an important role here.\nDon't worry, I'm going back to this question very soon.\n\nIn Zig, we have four build modes (which are listed below). Each one of these build modes offer\ndifferent advantages and characteristics. As we described at @sec-compile-debug-mode, the `zig` compiler\nuses the `Debug` build mode by default, when you don't explicitly choose a build mode.\n\n- `Debug`, mode that produces and includes debugging information in the output of the build process (i.e. the binary file defined by the target object);\n- `ReleaseSmall`, mode that tries to produce a binary file that is small in size;\n- `ReleaseFast`, mode that tries to optimize your code, in order to produce a binary file that is as fast as possible;\n- `ReleaseSafe`, mode that tries to make your code as safe as possible, by including safeguards when possible.\n\nSo, when you build your project, you can set the build mode of your target object to `ReleaseFast` for example, which will tell\nthe `zig` compiler to apply important optimizations in your code. This creates a binary file\nthat simply runs faster on most contexts, because it contains a more optimized version of your code.\nHowever, as a result, we often lose some safety features in our code.\nBecause some safety checks are removed from the final binary file,\nwhich makes your code run faster, but in a less safe manner.\n\nThis choice depends on your current priorities. If you are building a cryptography or banking system, you might\nprefer to prioritize safety in your code, so, you would choose the `ReleaseSafe` build mode, which is a little\nslower to run, but much more secure, because it includes all possible runtime safety checks in the binary file\nbuilt in the build process. In the other hand, if you are writing a game for example, you might prefer to prioritize performance\nover safety, by using the `ReleaseFast` build mode, so that your users can experience faster frame rates in your game.\n\nIn the example below, we are creating the same target object that we have used on previous examples.\nBut this time, we are specifying the build mode of this target object to the `ReleaseSafe` mode.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .optimize = .ReleaseSafe\n});\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n## Setting the version of your build\n\nEverytime you build a target object in your build script, you can assign a version\nnumber to this specific build, following a semantic versioning framework.\nYou can find more about semantic versioning by visiting the [Semantic Versioning website](https://semver.org/)[^semver].\nAnyway, in Zig, you can specify the version of your build, by providing a `SemanticVersion` struct to\nthe `version` option, like in the example below:\n\n\n[^semver]: <https://semver.org/>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .version = .{\n        .major = 2, .minor = 9, .patch = 7\n    }\n});\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n## Detecting the OS in your build script {#sec-detect-os}\n\nIs very common in Build Systems to use different options, or, to include different modules, or,\nto link against different libraries depending on the Operational System (OS)\nthat you are targeting in the build process.\n\nIn Zig, you can detect the target OS of the build process, by looking\nat the `os.tag` inside the `builtin` module from the Zig library.\nIn the example below, we are using an if statement to run some\narbitrary code when the target of the build process is a\nWindows system.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nif (builtin.target.os.tag == .windows) {\n    // Code that runs only when the target of\n    // the compilation process is Windows.\n}\n```\n:::\n\n\n\n\n\n## Adding a run step to your build process\n\nOne thing that is neat in Rust is that you can compile and run your\nsource code with one single command (`cargo run`) from the Rust compiler.\nWe saw at @sec-compile-run-code how can we perform a similar job in Zig, by\nbuilding and running our Zig source code through the `run` command from the `zig` compiler.\n\nBut how can we, at the same time, build and run the binary file specified by a target object in our\nbuild script?\nThe answer is by including a \"run artifact\" in our build script.\nA run artifact is created through the `addRunArtifact()` method from the `Build` struct.\nWe simply provide as input to this function the target object that describes the binary file that we\nwant to execute. As a result, this function creates a run artifact that is capable of executing\nthis binary file.\n\nIn the example below, we are defining an executable binary file named `hello`,\nand we use this `addRunArtifact()` method to create a run artifact that will execute\nthis `hello` executable file.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"src/hello.zig\"),\n    .target = b.host\n});\nb.installArtifact(exe);\nconst run_arti = b.addRunArtifact(exe);\n```\n:::\n\n\n\n\nNow that we have created this run artifact, we need to include it in\nthe build process. We do that by declaring a new step in our build\nscript to call this artifact, through the `step()` method of the `Build`\nstruct.\n\nWe can give any name we want to this step, but, for our\ncontext here, I'm going to name this step as \"run\".\nAlso, I give it a brief description to this step (\"Run the project\").\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst run_step = b.step(\n    \"run\", \"Run the project\"\n);\n```\n:::\n\n\n\n\n\nNow that we have declared this \"run step\" we need to tell Zig that\nthis \"run step\" depends on the run artifact.\nIn other words, a run artifact always depends on a \"step\" to effectively be executed.\nBy creating this dependency\nwe finally stablish the necessary commands to build and run the executable file\nfrom the build script.\n\nWe can establish a dependency between the run step and the run artifact\nby using the `dependsOn()` method from the run step. So, we first\ncreate the run step, and then, we link it with the run artifact, by\nusing this `dependsOn()` method from the run step.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nrun_step.dependOn(&run_arti.step);\n```\n:::\n\n\n\n\nThe entire source code of this specific build script that\nwe wrote, piece by piece, in this section, is\navailable in the `build_and_run.zig` module. You can\nsee this module by\n[visiting the official repository of this book](https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig)\n[^module-src].\n\n\n[^module-src]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig>\n\nWhen you declare a new step in your build script, this step\nbecomes available through the `build` command in the `zig` compiler.\nYou can actually see this step by running `zig build --help` in the terminal, like\nin the example below, where we can see that this new \"run\"\nstep that we declared in the build script appeared in the output.\n\n```bash\nzig build --help\n```\n\n```\nSteps:\n  ...\n  run   Run the project\n  ...\n```\n\nNow, everything that we need to is to\ncall this \"run\" step that we created in our build script. We\ncall it by using the name that we gave to this step\nafter the `build` command from the `zig` compiler.\nThis will cause the compiler to build our executable file\nand execute it at the same time.\n\n```bash\nzig build run\n```\n\n## Build unit tests in your project\n\nWe have talked at length about writing unit tests in Zig at @sec-unittests,\nand we also have talked about how to execute these unit tests through\nthe `test` command of the `zig` compiler. However,\nas we did with the `run` command on the previous section, we also might want to\ninclude some commands in our build script to also build and execute the unit tests in our project.\n\nSo, once again, we are going to discuss how a specific built-in command from the `zig` compiler,\n(in this case, the `test` command) can be used in a build script in Zig.\nHere is where a \"test target object\" comes into play.\nAs was described at @sec-targets, we can create a test target object by using the `addTest()` method of\nthe `Build` struct. The first thing that we need to do is to\ndeclare a test target object in our build script.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst test_exe = b.addTest(.{\n    .name = \"unit_tests\",\n    .root_source_file = b.path(\"src/main.zig\"),\n    .target = b.host,\n});\nb.installArtifact(test_exe);\n```\n:::\n\n\n\n\n\nA test target object essentially selects all `test` blocks in all Zig modules\nacross your project, and builds only the source code present inside\nthese `test` blocks in your project. As a result, this target object\ncreates an executable file that contains only the source code present\nin all of these `test` blocks (i.e. the unit tests) in your project.\n\nPerfect! Now that we have declared this test target object, an executable file\nnamed `unit_tests` is built by the `zig` compiler when we trigger the build\nscript with the `build` command. After the build\nprocess is finished, we can simply execute this `unit_tests` executable\nin the terminal.\n\nHowever, if you remember the previous section, we already learned\nhow can we create a run step in our build script, to execute an executable file\nbuilt by the build script.\n\nSo, we could simply add a run step in our build script to run these unit tests\nfrom a single command in the `zig` compiler, to make our lifes easier.\nIn the example below, we demonstrate the commands to\nregister a new build step called \"tests\" in our build script\nto run these unit tests.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst run_arti = b.addRunArtifact(test_exe);\nconst run_step = b.step(\"tests\", \"Run unit tests\");\nrun_step.dependOn(&run_arti.step);\n```\n:::\n\n\n\n\nNow that we registered this new build step, we can trigger it by calling the command below\nin the terminal. You can also checkout the complete source\ncode for this specific build script at the `build_tests.zig` module at the\n[official repository of this book](https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig)\n[^module-src2].\n\n\n[^module-src2]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig>\n\n\n```bash\nzig build tests\n```\n\n\n## Tailoring your build process with user-provided options\n\nSometimes, you want to make a build script that is customizable by the user\nof your project. You can do that by creating user-provided options in\nyour build script. We create an user-provided option by using the\n`option()` method from the `Build` struct.\n\nWith this method, we create a \"build option\" which can be passed\nto the `build.zig` script at the command line. The user have the power of setting\nthis option at the `build` command from the\n`zig` compiler. In other words, each build option that we create\nbecomes a new command line argument that is accessible through the `build` command\nof the compiler.\n\nThese \"user-provided options\" are set by using the prefix `-D` in the command line.\nFor example, if we declare an option named `use_zlib`, that receives a boolean value which\nindicates if we should link our source code to `zlib` or not, we can set the value\nof this option in the command line with `-Duse_zlib`. The code example below\ndemonstrates this idea:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const use_zlib = b.option(\n        bool,\n        \"use_zlib\",\n        \"Should link to zlib?\"\n    ) orelse false;\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"example.zig\"),\n        .target = b.host,\n    });\n    if (use_zlib) {\n        exe.linkSystemLibrary(\"zlib\");\n    }\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\n```bash\nzig build -Duse_zlib=false\n```\n\n\n## Linking to external libraries\n\n\nOne essential part of every build process is the linking stage.\nThis stage is responsible for combining the multiple object files\nthat represent your code, into a single executable file. It also links\nthis executable file to external libraries, if you use any in your code.\n\nIn Zig, we have two notions of a \"library\", which are: 1) a system's library;\n2) a local library. A system's library is just a library that already is installed\nin your system. While a local library is a library that belongs to the current\nproject. Is a library that is present in your project directory, and\nthat you are building together with your project source code.\n\nThe basic difference between the two, is that a system's library is already\nbuilt and installed in your system, supposedly, and all you need to do\nis to link your source code to this library to start using it.\nWe do that by using the `linkSystemLibrary()` method from a\n`Compile` object. This method accepts the name of the library\nin a string as input. Remember from @sec-targets that a `Compile` object\nis a target object that you declare in your build script.\n\nWhen you link a particular target object with a system's library,\nthe `zig` compiler will use `pkg-config` to find where\nare the binary files and also the header files of this library\nin your system.\nWhen it finds these files, the linker present in the `zig` compiler\nwill link your object files with the files of this library to\nproduce a single binary file for you.\n\nIn the example below, we are creating an executable file named `image_filter`,\nand, we are linking this executable file to the C Standard Library with the\nmethod `linkLibC()`, but we also are linking this executable file to the\nC library `libpng` that is currently installed in my system.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"image_filter\",\n        .root_source_file = b.path(\"src/main.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n    exe.linkLibC();\n    exe.linkSystemLibrary(\"png\");\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\nIf you are linking with a C library in your project, is generally a good idea\nto also link your code with the C Standard Library. Because is very likely\nthat this C library uses some functionality of the C Standard Library at some point.\nThe same goes to C++ libraries. So, if you are linking with\nC++ libraries, is a good idea to link your project with the C++\nStandard Library by using the `linkLibCpp()` method.\n\nOn the order side, when you want to link with a local library,\nyou should use the `linkLibrary()` method of a `Compile` object.\nThis method expects to receive another `Compile` object as input.\nThat is, another target object defined in your build script,\nusing either the `addStaticLibrary()` or `addSharedLibrary()` methods\nwhich defines a library to be built.\n\nAs we discussed earlier, a local library is a library\nthat is local to your project, and that is being built together\nwith your project. So, you need to create a target object in your build script\nto build this local library. Then, you link the target objects of interest in your project,\nwith this target object that identifies this local library.\n\nTake a look at this example extracted from the build script of the [`libxev` library](https://github.com/mitchellh/libxev/tree/main)[^libxev2].\nYou can see in this snippet that\nwe are declaring a shared library file, from the `c_api.zig`\nmodule. Then, later in the build script, we declare an\nexecutable file named `\"dynamic-binding-test\"`, which\nlinks to this shared library that we defined earlier\nin the script.\n\n[^libxev2]: <https://github.com/mitchellh/libxev/tree/main>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst optimize = b.standardOptimizeOption(.{});\nconst target = b.standardTargetOptions(.{});\n\nconst dynamic_lib = b.addSharedLibrary(.{\n    .name = dynamic_lib_name,\n    .root_source_file = b.path(\"src/c_api.zig\"),\n    .target = target,\n    .optimize = optimize,\n});\nb.installArtifact(dynamic_lib);\n// ... more lines in the script\nconst dynamic_binding_test = b.addExecutable(.{\n    .name = \"dynamic-binding-test\",\n    .target = target,\n    .optimize = optimize,\n});\ndynamic_binding_test.linkLibrary(dynamic_lib);\n```\n:::\n\n\n\n\n\n\n## Building C code {#sec-building-c-code}\n\nThe `zig` compiler comes with a C compiler embedded in it. In other words,\nyou can use the `zig` compiler to build C projects. This C compiler is available\nthrough the `cc` command of the `zig` compiler.\n\nAs an example, let's use the famous [FreeType library](https://freetype.org/)[^freetype].\nFreeType is one of the most widely used pieces of software in the world.\nIt is a C library designed to produce high-quality fonts. But it is also\nheavily used in the industry to natively render text and fonts\nin the screen of your computer.\n\nIn this section, we are going to write a build script, piece by piece, that is capable\nof building the FreeType project from source.\nYou can find the source code of this build script on the\n[`freetype-zig` repository](https://github.com/pedropark99/freetype-zig/tree/main)[^freetype-zig]\navailable at GitHub.\n\n[^freetype]: <https://freetype.org/>\n[^freetype-zig]: <https://github.com/pedropark99/freetype-zig/tree/main>\n\nAfter you download the source code of FreeType from the official website[^freetype],\nyou can start writing the `build.zig` module. We begin by defining the target object\nthat defines the binary file that we want to compile.\n\nAs an example, I will build the project as a static library file using the `addStaticLibrary()` method\nto create the target object.\nAlso, since FreeType is a C library, I will also link the library\nagainst `libc` through the `linkLibC()` method, to guarantee that any use\nof the C Standard Library is covered in the compilation process.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst target = b.standardTargetOptions(.{});\nconst opti = b.standardOptimizeOption(.{});\nconst lib = b.addStaticLibrary(.{\n    .name = \"freetype\",\n    .optimize = opti,\n    .target = target,\n});\nlib.linkLibC();\n```\n:::\n\n\n\n\n### Creating C compiler flags\n\nCompiler flags are also known as \"compiler options\" by many programmers,\nor also, as \"command options\" in the GCC official documentation.\nIt's fair to also call them as the \"command-line arguments\" of the C compiler.\nIn general, we use compiler flags to turn on (or turn off) some features from the compiler,\nor to tweak the compilation process to fit the needs of our project.\n\nIn build scripts written in Zig, we normally list the C compiler flags to be used in the compilation process\nin a simple array, like in the example below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c_flags = [_][]const u8{\n    \"-Wall\",\n    \"-Wextra\",\n    \"-Werror\",\n};\n```\n:::\n\n\n\n\nIn theory, there is nothing stopping you from using this array to add \"include paths\" (with the `-I` flag)\nor \"library paths\" (with the `-L` flag) to the compilation process. But there are formal ways in Zig to\nadd these types of paths in the compilation process. Both are discussed at @sec-include-paths\nand @sec-library-paths.\n\nAnyway, in Zig, we add C flags to the build process together with the C files that we want to compile, by using the\n`addCSourceFile()` and `addCSourceFiles()` methods. In the example above, we have just declared\nthe C flags that we want to use. But we haven't added them to the build process yet.\nTo do that, we also need to list the C files to be compiled.\n\n### Listing your C files\n\nThe C files that contains \"cross-platform\" source code are listed in the `c_source_files`\nobject below. These are the C files that are included by default in every platform\nsupported by the FreeType library. Now, since the amount of C files in the FreeType library is big,\nI have omitted the rest of the files in the code example below, for brevity purposes.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c_source_files = [_][]const u8{\n    \"src/autofit/autofit.c\",\n    \"src/base/ftbase.c\",\n    // ... and many other C files.\n};\n```\n:::\n\n\n\n\nNow, in addition to \"cross-platform\" source code, we also have some C files in the FreeType project\nthat are platform-specific, meaning that, they contain source code that can only be compiled in specific platforms,\nand, as a result, they are only included in the build process on these specific target platforms.\nThe objects that list these C files are exposed in the code example below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst windows_c_source_files = [_][]const u8{\n    \"builds/windows/ftdebug.c\",\n    \"builds/windows/ftsystem.c\"\n};\nconst linux_c_source_files = [_][]const u8{\n    \"src/base/ftsystem.c\",\n    \"src/base/ftdebug.c\"\n};\n```\n:::\n\n\n\n\nNow that we declared both the files that we want to include and the C compiler flags to be used,\nwe can add them to the target object that describes the FreeType library, by using the\n`addCSourceFile()` and `addCSourceFiles()` methods.\n\nBoth of these functions are methods from a `Compile` object (i.e. a target object).\nThe `addCSourceFile()` method is capable of adding a single C file to the target object,\nwhile the `addCSourceFiles()` method is used to add multiple C files in a single command.\nYou might prefer to use `addCSourceFile()` when you need to use different compiler flags\non specific C files in your project. But, if you can use the same compiler flags\nacross all C files, then, you will probably find `addCSourceFiles()` a better choice.\n\nNotice that we are using the `addCSourceFiles()` method in the example below,\nto add both the C files and the C compiler flags. Also notice that we\nare using the `os.tag` that we learned about at @sec-detect-os, to add the platform-specific\nC files.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nlib.addCSourceFiles(\n    &c_source_files, &c_flags\n);\n\nswitch (builtin.target.os.tag) {\n    .windows => {\n        lib.addCSourceFiles(\n            &windows_c_source_files,\n            &c_flags\n        );\n    },\n    .linux => {\n        lib.addCSourceFiles(\n            &linux_c_source_files,\n            &c_flags\n        );\n    },\n    else => {},\n}\n```\n:::\n\n\n\n\n\n### Defining C Macros\n\nC Macros are an essential part of the C programming language,\nand they are commonly defined through the `-D` flag from a C compiler.\nIn Zig, you can define a C Macro to be used in your build process\nby using the `defineCMacro()` method from the target object that\ndefines the binary file that you are building.\n\nIn the example below, we are using the `lib` object that we have defined\non the previous sections to define some C Macros used by the FreeType project\nin the compilation process. These C Macros specify if FreeType\nshould (or should not) include functionalities from different\nexternal libraries.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nlib.defineCMacro(\"FT_DISABLE_ZLIB\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_PNG\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_HARFBUZZ\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BZIP2\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BROTLI\", \"TRUE\");\nlib.defineCMacro(\"FT2_BUILD_LIBRARY\", \"TRUE\");\n```\n:::\n\n\n\n\n\n### Adding library paths {#sec-library-paths}\n\nLibrary paths are paths in your computer where the C compiler will look (or search) for\nlibrary files to link against your source code. In other words, when you use a library in your\nC source code, and you ask the C compiler to link your source code against this library,\nthe C compiler will search for the binary files of this library across the paths listed\nin this \"library paths\" set.\n\nThese paths are platform specific, and, by default, the C compiler starts by looking at a\npre-defined set of places in your computer. But you can add more paths (or more places)\nto this list. For example, you may have a library installed in a non-conventional place of your\ncomputer, and you can make the C compiler \"see\" this \"non-conventional place\" by adding this path\nto this list of pre-defined paths.\n\nIn Zig, you can add more paths to this set by using the `addLibraryPath()` method from your target object.\nFirst, you defined a `LazyPath` object, containing the path you want to add, then,\nyou provide this object as input to the `addLibraryPath()` method, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst lib_path: std.Build.LazyPath = .{\n    .cwd_relative = \"/usr/local/lib/\"\n};\nlib.addLibraryPath(lib_path);\n```\n:::\n\n\n\n\n\n\n\n### Adding include paths {#sec-include-paths}\n\nThe preprocessor search path is a popular concept from the\nC community, but it is also known by many C programmers as \"include paths\", because\nthe paths in this \"search path\" relate to the `#include` statements found in the C files.\n\nInclude paths are similar to library paths. They are a set of pre-defined places in your computer where\nthe C compiler will look for files during the compilation process. But instead of looking for\nlibrary files, the include paths are places where the compiler looks for header files included\nin your C source code.\nThis is why many C programmers prefer to call these paths as the \"preprocessor search path\".\nBecause header files are processed during the preprocessor stage of the compilation\nprocess.\n\nSo, every header file that you include in your C source code, through a `#include` statements needs to\nbe found somewhere, and the C compiler will search for this header file across the paths listed in this \"include paths\" set.\nInclude paths are added to the compilation process through the `-I` flag.\n\nIn Zig, you can add new paths to this pre-defined set of paths, by using the `addIncludePath()` method\nfrom your target object. This method also accepts a `LazyPath` object as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst inc_path: std.Build.LazyPath = .{\n    .path = \"./include\"\n};\nlib.addIncludePath(inc_path);\n```\n:::\n",
+    "supporting": [
+      "07-build-system_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/docs/Chapters/07-build-system.html b/docs/Chapters/07-build-system.html
index 6c705bc6..196ebac6 100644
--- a/docs/Chapters/07-build-system.html
+++ b/docs/Chapters/07-build-system.html
@@ -378,7 +378,7 @@ <h2 data-number="9.3" class="anchored" data-anchor-id="sec-targets"><span class=
 <p>These functions are methods from the <code>Build</code> struct that you receive as input of the <code>build()</code> function. All of them, create as output a <code>Compile</code> object, which represents a target object to be compiled by the <code>zig</code> compiler. All of these functions accept a similar struct literal as input. This struct literal defines three essential specs about this target object that you are building: <code>name</code>, <code>target</code> and <code>root_source_file</code>.</p>
 <p>We have already seen these three options being used on the previous example, where we used the <code>addExecutable()</code> method to create an executable target object. This example is reproduced below. Notice the use of the <code>path()</code> method from the <code>Build</code> struct, to define a path in the <code>root_source_file</code> option.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb2"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a>exe = b.addExecutable(.<span class="op">{</span></span>
+<div class="sourceCode cell-code" id="cb2"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> exe = b.addExecutable(.<span class="op">{</span></span>
 <span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a>    .name = <span class="st">"hello"</span>,</span>
 <span id="cb2-3"><a href="#cb2-3" aria-hidden="true" tabindex="-1"></a>    .root_source_file = b.path(<span class="st">"hello.zig"</span>),</span>
 <span id="cb2-4"><a href="#cb2-4" aria-hidden="true" tabindex="-1"></a>    .target = b.host,</span>
diff --git a/docs/index.html b/docs/index.html
index 6ba96909..2857af7e 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -7,7 +7,7 @@
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 <meta name="author" content="Pedro Duarte Faria">
-<meta name="dcterms.date" content="2024-12-05">
+<meta name="dcterms.date" content="2025-01-10">
 
 <title>Introduction to Zig</title>
 <style>
@@ -287,7 +287,7 @@ <h1 class="title">Introduction to Zig</h1>
     <div>
     <div class="quarto-title-meta-heading">Published</div>
     <div class="quarto-title-meta-contents">
-      <p class="date">December 5, 2024</p>
+      <p class="date">January 10, 2025</p>
     </div>
   </div>
   
diff --git a/docs/search.json b/docs/search.json
index 64d6d24a..d8cb3ea3 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -724,7 +724,7 @@
     "href": "Chapters/07-build-system.html#sec-targets",
     "title": "9  Build System",
     "section": "9.3 Target objects",
-    "text": "9.3 Target objects\nAs we described over the previous sections, a build script is composed around target objects. Each target object is normally a binary file (or an output) that you want to get from the build process. You can list multiple target objects in your build script, so that the build process generates multiple binary files for you at once.\nFor example, maybe you are a developer working in a cross-platform application, and, because this application is cross-platform, you probably need to release binary files of your software for each OS supported by your application to your end users. Thus, you can define a different target object in your build script for each OS (Windows, Linux, etc.) where you want to publish your software. This will make the zig compiler to build your project to multiple target OS’s at once. The Zig Build System official documentation have a great code example that demonstrates this strategy4.\nA target object is created by the following methods of the Build struct that we introduced at Section 9.2:\n\naddExecutable() creates an executable file;\naddSharedLibrary() creates a shared library file;\naddStaticLibrary() creates a static library file;\naddTest() creates an executable file that executes unit tests.\n\nThese functions are methods from the Build struct that you receive as input of the build() function. All of them, create as output a Compile object, which represents a target object to be compiled by the zig compiler. All of these functions accept a similar struct literal as input. This struct literal defines three essential specs about this target object that you are building: name, target and root_source_file.\nWe have already seen these three options being used on the previous example, where we used the addExecutable() method to create an executable target object. This example is reproduced below. Notice the use of the path() method from the Build struct, to define a path in the root_source_file option.\n\nexe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nThe name option specify the name that you want to give to the binary file defined by this target object. So, in this example, we are building an executable file named hello. Is common to set this name option to the name of your project.\nFurthermore, the target option specify the target computer architecture (or the target operational system) of this binary file. For example, if you want this target object to run on a Windows machine that uses a x86_64 architecture, you can set this target option to x86_64-windows-gnu for example. This will make the zig compiler to compile the project to run on a x86_64 Windows machine. You can see the full list of architectures and OS’s that the zig compiler supports by running the zig targets command in the terminal.\nNow, if you are building the project to run on the current machine that you are using to run this build script, you can set this target option to the host method of the Build object, like we did in the example above. This host method identifies the current machine where you are currently running the zig compiler.\nAt last, the root_source_file option specifies the root Zig module of your project. That is the Zig module that contains the entrypoint to your application (i.e. the main() function), or, the main API of your library. This also means that, all the Zig modules that compose your project are automatically discovered from the import statements you have inside this “root source file”. The zig compiler can detect when a Zig module depends on the other through the import statements, and, as a result, it can discover the entire map of Zig modules used in your project.\nThis is handy, and it is different from what happens in other build systems. In CMake for example, you have to explicitly list the paths to all source files that you want to include in your build process. This is probably a symptom of the “lack of conditional compilation” in the C and C++ compilers. Since they lack this feature, you have to explicitly choose which source files should be sent to the C/C++ compiler, because not every C/C++ code is portable or supported in every operational system, and, therefore, would cause a compilation error in the C/C++ compiler.\nNow, one important detail about the build process is that, you have to explicitly install the target objects that you create in your build script, by using the installArtifact() method of the Build struct.\nEverytime you invoke the build process of your project, by calling the build command of the zig compiler, a new directory named zig-out is created in the root directory of your project. This new directory contains the outputs of the build process, that is, the binary files built from your source code.\nWhat the installArtifact() method do is to install (or copy) the built target objects that you defined to this zig-out directory. This means that, if you do not install the target objects you define in your build script, these target objects are essentially discarded at the end of the build process.\nFor example, you might be building a project that uses a third party library that is built together with the project. So, when you build your project, you would need first, to build the third party library, and then, you link it with the source code of your project. So, in this case, we have two binary files that are generated in the build process (the executable file of your project, and the third party library). But only one is of interest, which is the executable file of our project. We can discard the binary file of the third party library, by simply not installing it into this zig-out directory.\nThis installArtifact() method is pretty straightforward. Just remember to apply it to every target object that you want to save into the zig-out directory, like in the example below:\n\nexe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nb.installArtifact(exe);",
+    "text": "9.3 Target objects\nAs we described over the previous sections, a build script is composed around target objects. Each target object is normally a binary file (or an output) that you want to get from the build process. You can list multiple target objects in your build script, so that the build process generates multiple binary files for you at once.\nFor example, maybe you are a developer working in a cross-platform application, and, because this application is cross-platform, you probably need to release binary files of your software for each OS supported by your application to your end users. Thus, you can define a different target object in your build script for each OS (Windows, Linux, etc.) where you want to publish your software. This will make the zig compiler to build your project to multiple target OS’s at once. The Zig Build System official documentation have a great code example that demonstrates this strategy4.\nA target object is created by the following methods of the Build struct that we introduced at Section 9.2:\n\naddExecutable() creates an executable file;\naddSharedLibrary() creates a shared library file;\naddStaticLibrary() creates a static library file;\naddTest() creates an executable file that executes unit tests.\n\nThese functions are methods from the Build struct that you receive as input of the build() function. All of them, create as output a Compile object, which represents a target object to be compiled by the zig compiler. All of these functions accept a similar struct literal as input. This struct literal defines three essential specs about this target object that you are building: name, target and root_source_file.\nWe have already seen these three options being used on the previous example, where we used the addExecutable() method to create an executable target object. This example is reproduced below. Notice the use of the path() method from the Build struct, to define a path in the root_source_file option.\n\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nThe name option specify the name that you want to give to the binary file defined by this target object. So, in this example, we are building an executable file named hello. Is common to set this name option to the name of your project.\nFurthermore, the target option specify the target computer architecture (or the target operational system) of this binary file. For example, if you want this target object to run on a Windows machine that uses a x86_64 architecture, you can set this target option to x86_64-windows-gnu for example. This will make the zig compiler to compile the project to run on a x86_64 Windows machine. You can see the full list of architectures and OS’s that the zig compiler supports by running the zig targets command in the terminal.\nNow, if you are building the project to run on the current machine that you are using to run this build script, you can set this target option to the host method of the Build object, like we did in the example above. This host method identifies the current machine where you are currently running the zig compiler.\nAt last, the root_source_file option specifies the root Zig module of your project. That is the Zig module that contains the entrypoint to your application (i.e. the main() function), or, the main API of your library. This also means that, all the Zig modules that compose your project are automatically discovered from the import statements you have inside this “root source file”. The zig compiler can detect when a Zig module depends on the other through the import statements, and, as a result, it can discover the entire map of Zig modules used in your project.\nThis is handy, and it is different from what happens in other build systems. In CMake for example, you have to explicitly list the paths to all source files that you want to include in your build process. This is probably a symptom of the “lack of conditional compilation” in the C and C++ compilers. Since they lack this feature, you have to explicitly choose which source files should be sent to the C/C++ compiler, because not every C/C++ code is portable or supported in every operational system, and, therefore, would cause a compilation error in the C/C++ compiler.\nNow, one important detail about the build process is that, you have to explicitly install the target objects that you create in your build script, by using the installArtifact() method of the Build struct.\nEverytime you invoke the build process of your project, by calling the build command of the zig compiler, a new directory named zig-out is created in the root directory of your project. This new directory contains the outputs of the build process, that is, the binary files built from your source code.\nWhat the installArtifact() method do is to install (or copy) the built target objects that you defined to this zig-out directory. This means that, if you do not install the target objects you define in your build script, these target objects are essentially discarded at the end of the build process.\nFor example, you might be building a project that uses a third party library that is built together with the project. So, when you build your project, you would need first, to build the third party library, and then, you link it with the source code of your project. So, in this case, we have two binary files that are generated in the build process (the executable file of your project, and the third party library). But only one is of interest, which is the executable file of our project. We can discard the binary file of the third party library, by simply not installing it into this zig-out directory.\nThis installArtifact() method is pretty straightforward. Just remember to apply it to every target object that you want to save into the zig-out directory, like in the example below:\n\nexe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nb.installArtifact(exe);",
     "crumbs": [
       "<span class='chapter-number'>9</span>  <span class='chapter-title'>Build System</span>"
     ]

From 342cae3fdfd317a7fadf205565eaa02a2755a644 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sat, 11 Jan 2025 07:29:25 -0300
Subject: [PATCH 020/151] Recompile book with fixed code example

---
 Chapters/07-build-system.qmd                              | 2 +-
 .../Chapters/07-build-system/execute-results/html.json    | 8 +++-----
 docs/Chapters/07-build-system.html                        | 2 +-
 docs/search.json                                          | 2 +-
 4 files changed, 6 insertions(+), 8 deletions(-)

diff --git a/Chapters/07-build-system.qmd b/Chapters/07-build-system.qmd
index e7c4c65a..e94ba900 100644
--- a/Chapters/07-build-system.qmd
+++ b/Chapters/07-build-system.qmd
@@ -238,7 +238,7 @@ target object that you want to save into the `zig-out` directory, like in the ex
 
 ```{zig}
 #| eval: false
-exe = b.addExecutable(.{
+const exe = b.addExecutable(.{
     .name = "hello",
     .root_source_file = b.path("hello.zig"),
     .target = b.host,
diff --git a/_freeze/Chapters/07-build-system/execute-results/html.json b/_freeze/Chapters/07-build-system/execute-results/html.json
index cb50222a..19ef21c9 100644
--- a/_freeze/Chapters/07-build-system/execute-results/html.json
+++ b/_freeze/Chapters/07-build-system/execute-results/html.json
@@ -1,11 +1,9 @@
 {
-  "hash": "a1b79257fb194da6246ef8c44be69c2f",
+  "hash": "e85c074257bd60ecabd542a9aec94925",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Build System {#sec-build-system}\n\n\nIn this chapter, we are going to talk about the build system, and how an entire project\nis built in Zig.\nOne key advantage of Zig is that it includes a build system embedded in the language itself.\nThis is great, because then you do not have to depend on an external system, separated\nfrom the compiler, to build your code.\n\n\nYou can find a good description of Zig's build system\non the [article entitled \"Build System\"](https://ziglang.org/learn/build-system/#user-provided-options)[^zig-art1]\nfrom the official Zig's website.\nWe also have the excellent [series of posts written by Felix](https://zig.news/xq/zig-build-explained-part-1-59lf)[^felix].\nHence, this chapter represents an extra resource for you to consult and rely on.\n\n[^felix]: <https://zig.news/xq/zig-build-explained-part-1-59lf>\n[^zig-art1]: <https://ziglang.org/learn/build-system/#user-provided-options>\n\nBuilding code is one of the things that Zig is best at. One thing that is particularly\ndifficult in C/C++ and even in Rust, is to cross-compile source code to multiple targets\n(e.g. multiple computer architectures and operational systems),\nand the `zig` compiler is known for being one of the best existing pieces of software\nfor this particular task.\n\n\n\n\n## How source code is built?\n\nWe already have talked about the challenges of building source code in low-level languages\nat @sec-project-files. As we described at that section, programmers invented Build Systems\nto surpass these challenges on the process of building source code in low-level languages.\n\nLow-level languages uses a compiler to compile (or to build) your source code into binary instructions.\nIn C and C++, we normally use compilers like `gcc`, `g++` or `clang` to compile\nour C and C++ source code into these instructions.\nEvery language have its own compiler, and this is no different in Zig.\n\nIn Zig, we have the `zig` compiler to compile our Zig source code into\nbinary instructions that can be executed by our computer.\nIn Zig, the compilation (or the build) process involves\nthe following components:\n\n- The Zig modules that contains your source code;\n- Library files (either a dynamic library or a static library);\n- Compiler flags that tailors the build process to your needs.\n\nThese are the things that you need to connect together in order to build your\nsource code in Zig. In C and C++, you would have an extra component, which are the header files of\nthe libraries that you are using. But header files do not exist in Zig, so, you only need\nto care about them if you are linking your Zig source code with a C library.\nIf that is not your case, you can forget about it.\n\nYour build process is usually organized in a build script. In Zig, we normally\nwrite this build script into a Zig module in the root directory of our project,\nnamed as `build.zig`. You write this build script, then, when you run it, your project\nget's built into binary files that you can use and distribute to your users.\n\nThis build script is normally organized around *target objects*. A target is simply\nsomething to be built, or, in other words, it's something that you want the `zig` compiler\nto build for you. This concept of \"targets\" is present in most Build Systems,\nespecially in CMake[^cmake].\n\n[^cmake]: <https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html>\n\nThere are four types of target objects that you can build in Zig, which are:\n\n- An executable (e.g. a `.exe` file on Windows).\n- A shared library (e.g. a `.so` file in Linux or a `.dll` file on Windows).\n- A static library (e.g. a `.a` file in Linux or a `.lib` file on Windows).\n- An executable file that executes only unit tests (or, a \"unit tests executable\").\n\nWe are going to talk more about these target objects at @sec-targets.\n\n\n\n## The `build()` function {#sec-build-fun}\n\nA build script in Zig always contains a public (and top-level) `build()` function declared.\nIt is like the `main()` function on the main Zig module of your project, that we discussed at @sec-main-file.\nBut instead of creating the entrypoint to your code, this `build()` function is the entrypoint to the build process.\n\nThis `build()` function should accept a pointer to a `Build` object as input, and it should use this \"build object\" to perform\nthe necessary steps to build your project. The return type of this function is always `void`,\nand this `Build` struct comes directly from the Zig Standard Library (`std.Build`). So, you can \naccess this struct by just importing the Zig Standard Library into your `build.zig` module.\n\nJust as a very simple example, here you can see the source code necessary to build\nan executable file from the `hello.zig` Zig module.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"hello.zig\"),\n        .target = b.host,\n    });\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\nYou can define and use other functions and objects in this build script. You can also import\nother Zig modules as you would normally do in any other module of your project.\nThe only real requirement for this build script, is to have a public and top-level\n`build()` function defined, that accepts a pointer to a `Build` struct as input.\n\n\n## Target objects {#sec-targets}\n\nAs we described over the previous sections, a build script is composed around target objects.\nEach target object is normally a binary file (or an output) that you want to get from the build process. You can list\nmultiple target objects in your build script, so that the build process generates multiple\nbinary files for you at once.\n\nFor example, maybe you are a developer working in a cross-platform application,\nand, because this application is cross-platform, you probably need to release\nbinary files of your software for each OS supported by your application to your end users.\nThus, you can define a different target object in your build script\nfor each OS (Windows, Linux, etc.) where you want to publish your software.\nThis will make the `zig` compiler to build your project to multiple target OS's at once.\nThe Zig Build System official documentation have a [great code example that demonstrates this strategy](https://ziglang.org/learn/build-system/#handy-examples)[^zig-ex].\n\n[^zig-ex]: <https://ziglang.org/learn/build-system/#handy-examples>\n\n\nA target object is created by the following methods of the `Build` struct that we introduced\nat @sec-build-fun:\n\n- `addExecutable()` creates an executable file;\n- `addSharedLibrary()` creates a shared library file;\n- `addStaticLibrary()` creates a static library file;\n- `addTest()` creates an executable file that executes unit tests.\n\n\nThese functions are methods from the `Build` struct that you receive\nas input of the `build()` function. All of them, create as output\na `Compile` object, which represents a target object to be compiled\nby the `zig` compiler. All of these functions accept a similar struct literal as input.\nThis struct literal defines three essential specs about this target object that you are building:\n`name`, `target` and `root_source_file`.\n\nWe have already seen these three options being used on the previous example,\nwhere we used the `addExecutable()` method to create an executable target object.\nThis example is reproduced below. Notice the use of the `path()` method\nfrom the `Build` struct, to define a path in the `root_source_file` option.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n```\n:::\n\n\n\n\nThe `name` option specify the name that you want to give to the binary file defined\nby this target object. So, in this example, we are building an executable file named `hello`.\nIs common to set this `name` option to the name of your project.\n\n\nFurthermore, the `target` option specify the target computer architecture (or the target operational system) of this\nbinary file. For example, if you want this target object to run on a Windows machine\nthat uses a `x86_64` architecture, you can set this `target` option to `x86_64-windows-gnu` for example.\nThis will make the `zig` compiler to compile the project to run on a `x86_64` Windows machine.\nYou can see the full list of architectures and OS's that the `zig` compiler supports by running\nthe `zig targets` command in the terminal.\n\nNow, if you are building the project to run on the current machine\nthat you are using to run this build script, you can set this `target`\noption to the `host` method of the `Build` object, like we did in the example above.\nThis `host` method identifies the current machine where you are\ncurrently running the `zig` compiler.\n\n\nAt last, the `root_source_file` option specifies the root Zig module of your project.\nThat is the Zig module that contains the entrypoint to your application (i.e. the `main()` function), or, the main API of your library.\nThis also means that, all the Zig modules that compose your project are automatically discovered\nfrom the import statements you have inside this \"root source file\".\nThe `zig` compiler can detect when a Zig module depends on the other through the import statements,\nand, as a result, it can discover the entire map of Zig modules used in your project.\n\nThis is handy, and it is different from what happens in other build systems.\nIn CMake for example, you have to explicitly list the paths to all source files that you want to\ninclude in your build process. This is probably a symptom of the \"lack of conditional\ncompilation\" in the C and C++ compilers. Since they lack this feature, you have\nto explicitly choose which source files should be sent to the C/C++ compiler, because not\nevery C/C++ code is portable or supported in every operational system, and, therefore,\nwould cause a compilation error in the C/C++ compiler.\n\n\nNow, one important detail about the build process is that, you have to **explicitly\ninstall the target objects that you create in your build script**, by using the\n`installArtifact()` method of the `Build` struct.\n\nEverytime you invoke the build process of your project, by calling the `build` command\nof the `zig` compiler, a new directory named `zig-out` is created in the root\ndirectory of your project. This new directory contains the outputs of the build process,\nthat is, the binary files built from your source code.\n\nWhat the `installArtifact()` method do is to install (or copy) the built target objects\nthat you defined to this `zig-out` directory.\nThis means that, if you do not\ninstall the target objects you define in your build script, these target objects are\nessentially discarded at the end of the build process.\n\nFor example, you might be building a project that uses a third party library that is built\ntogether with the project. So, when you build your project, you would need first, to\nbuild the third party library, and then, you link it with the source code of your project.\nSo, in this case, we have two binary files that are generated in the build process (the executable file of your project, and the third party library).\nBut only one is of interest, which is the executable file of our project.\nWe can discard the binary file of the third party library, by simply not installing it\ninto this `zig-out` directory.\n\nThis `installArtifact()` method is pretty straightforward. Just remember to apply it to every\ntarget object that you want to save into the `zig-out` directory, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nexe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n## Setting the build mode\n\nWe have talked about the three essential options that are set when you create a new target object.\nBut there is also a fourth option that you can use to set the build mode of this target object,\nwhich is the `optimize` option.\nThis option is called this way, because the build modes in Zig are treated more of\nan \"optimization vs safety\" problem. So optimization plays an important role here.\nDon't worry, I'm going back to this question very soon.\n\nIn Zig, we have four build modes (which are listed below). Each one of these build modes offer\ndifferent advantages and characteristics. As we described at @sec-compile-debug-mode, the `zig` compiler\nuses the `Debug` build mode by default, when you don't explicitly choose a build mode.\n\n- `Debug`, mode that produces and includes debugging information in the output of the build process (i.e. the binary file defined by the target object);\n- `ReleaseSmall`, mode that tries to produce a binary file that is small in size;\n- `ReleaseFast`, mode that tries to optimize your code, in order to produce a binary file that is as fast as possible;\n- `ReleaseSafe`, mode that tries to make your code as safe as possible, by including safeguards when possible.\n\nSo, when you build your project, you can set the build mode of your target object to `ReleaseFast` for example, which will tell\nthe `zig` compiler to apply important optimizations in your code. This creates a binary file\nthat simply runs faster on most contexts, because it contains a more optimized version of your code.\nHowever, as a result, we often lose some safety features in our code.\nBecause some safety checks are removed from the final binary file,\nwhich makes your code run faster, but in a less safe manner.\n\nThis choice depends on your current priorities. If you are building a cryptography or banking system, you might\nprefer to prioritize safety in your code, so, you would choose the `ReleaseSafe` build mode, which is a little\nslower to run, but much more secure, because it includes all possible runtime safety checks in the binary file\nbuilt in the build process. In the other hand, if you are writing a game for example, you might prefer to prioritize performance\nover safety, by using the `ReleaseFast` build mode, so that your users can experience faster frame rates in your game.\n\nIn the example below, we are creating the same target object that we have used on previous examples.\nBut this time, we are specifying the build mode of this target object to the `ReleaseSafe` mode.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .optimize = .ReleaseSafe\n});\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n## Setting the version of your build\n\nEverytime you build a target object in your build script, you can assign a version\nnumber to this specific build, following a semantic versioning framework.\nYou can find more about semantic versioning by visiting the [Semantic Versioning website](https://semver.org/)[^semver].\nAnyway, in Zig, you can specify the version of your build, by providing a `SemanticVersion` struct to\nthe `version` option, like in the example below:\n\n\n[^semver]: <https://semver.org/>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .version = .{\n        .major = 2, .minor = 9, .patch = 7\n    }\n});\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n## Detecting the OS in your build script {#sec-detect-os}\n\nIs very common in Build Systems to use different options, or, to include different modules, or,\nto link against different libraries depending on the Operational System (OS)\nthat you are targeting in the build process.\n\nIn Zig, you can detect the target OS of the build process, by looking\nat the `os.tag` inside the `builtin` module from the Zig library.\nIn the example below, we are using an if statement to run some\narbitrary code when the target of the build process is a\nWindows system.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nif (builtin.target.os.tag == .windows) {\n    // Code that runs only when the target of\n    // the compilation process is Windows.\n}\n```\n:::\n\n\n\n\n\n## Adding a run step to your build process\n\nOne thing that is neat in Rust is that you can compile and run your\nsource code with one single command (`cargo run`) from the Rust compiler.\nWe saw at @sec-compile-run-code how can we perform a similar job in Zig, by\nbuilding and running our Zig source code through the `run` command from the `zig` compiler.\n\nBut how can we, at the same time, build and run the binary file specified by a target object in our\nbuild script?\nThe answer is by including a \"run artifact\" in our build script.\nA run artifact is created through the `addRunArtifact()` method from the `Build` struct.\nWe simply provide as input to this function the target object that describes the binary file that we\nwant to execute. As a result, this function creates a run artifact that is capable of executing\nthis binary file.\n\nIn the example below, we are defining an executable binary file named `hello`,\nand we use this `addRunArtifact()` method to create a run artifact that will execute\nthis `hello` executable file.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"src/hello.zig\"),\n    .target = b.host\n});\nb.installArtifact(exe);\nconst run_arti = b.addRunArtifact(exe);\n```\n:::\n\n\n\n\nNow that we have created this run artifact, we need to include it in\nthe build process. We do that by declaring a new step in our build\nscript to call this artifact, through the `step()` method of the `Build`\nstruct.\n\nWe can give any name we want to this step, but, for our\ncontext here, I'm going to name this step as \"run\".\nAlso, I give it a brief description to this step (\"Run the project\").\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst run_step = b.step(\n    \"run\", \"Run the project\"\n);\n```\n:::\n\n\n\n\n\nNow that we have declared this \"run step\" we need to tell Zig that\nthis \"run step\" depends on the run artifact.\nIn other words, a run artifact always depends on a \"step\" to effectively be executed.\nBy creating this dependency\nwe finally stablish the necessary commands to build and run the executable file\nfrom the build script.\n\nWe can establish a dependency between the run step and the run artifact\nby using the `dependsOn()` method from the run step. So, we first\ncreate the run step, and then, we link it with the run artifact, by\nusing this `dependsOn()` method from the run step.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nrun_step.dependOn(&run_arti.step);\n```\n:::\n\n\n\n\nThe entire source code of this specific build script that\nwe wrote, piece by piece, in this section, is\navailable in the `build_and_run.zig` module. You can\nsee this module by\n[visiting the official repository of this book](https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig)\n[^module-src].\n\n\n[^module-src]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig>\n\nWhen you declare a new step in your build script, this step\nbecomes available through the `build` command in the `zig` compiler.\nYou can actually see this step by running `zig build --help` in the terminal, like\nin the example below, where we can see that this new \"run\"\nstep that we declared in the build script appeared in the output.\n\n```bash\nzig build --help\n```\n\n```\nSteps:\n  ...\n  run   Run the project\n  ...\n```\n\nNow, everything that we need to is to\ncall this \"run\" step that we created in our build script. We\ncall it by using the name that we gave to this step\nafter the `build` command from the `zig` compiler.\nThis will cause the compiler to build our executable file\nand execute it at the same time.\n\n```bash\nzig build run\n```\n\n## Build unit tests in your project\n\nWe have talked at length about writing unit tests in Zig at @sec-unittests,\nand we also have talked about how to execute these unit tests through\nthe `test` command of the `zig` compiler. However,\nas we did with the `run` command on the previous section, we also might want to\ninclude some commands in our build script to also build and execute the unit tests in our project.\n\nSo, once again, we are going to discuss how a specific built-in command from the `zig` compiler,\n(in this case, the `test` command) can be used in a build script in Zig.\nHere is where a \"test target object\" comes into play.\nAs was described at @sec-targets, we can create a test target object by using the `addTest()` method of\nthe `Build` struct. The first thing that we need to do is to\ndeclare a test target object in our build script.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst test_exe = b.addTest(.{\n    .name = \"unit_tests\",\n    .root_source_file = b.path(\"src/main.zig\"),\n    .target = b.host,\n});\nb.installArtifact(test_exe);\n```\n:::\n\n\n\n\n\nA test target object essentially selects all `test` blocks in all Zig modules\nacross your project, and builds only the source code present inside\nthese `test` blocks in your project. As a result, this target object\ncreates an executable file that contains only the source code present\nin all of these `test` blocks (i.e. the unit tests) in your project.\n\nPerfect! Now that we have declared this test target object, an executable file\nnamed `unit_tests` is built by the `zig` compiler when we trigger the build\nscript with the `build` command. After the build\nprocess is finished, we can simply execute this `unit_tests` executable\nin the terminal.\n\nHowever, if you remember the previous section, we already learned\nhow can we create a run step in our build script, to execute an executable file\nbuilt by the build script.\n\nSo, we could simply add a run step in our build script to run these unit tests\nfrom a single command in the `zig` compiler, to make our lifes easier.\nIn the example below, we demonstrate the commands to\nregister a new build step called \"tests\" in our build script\nto run these unit tests.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst run_arti = b.addRunArtifact(test_exe);\nconst run_step = b.step(\"tests\", \"Run unit tests\");\nrun_step.dependOn(&run_arti.step);\n```\n:::\n\n\n\n\nNow that we registered this new build step, we can trigger it by calling the command below\nin the terminal. You can also checkout the complete source\ncode for this specific build script at the `build_tests.zig` module at the\n[official repository of this book](https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig)\n[^module-src2].\n\n\n[^module-src2]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig>\n\n\n```bash\nzig build tests\n```\n\n\n## Tailoring your build process with user-provided options\n\nSometimes, you want to make a build script that is customizable by the user\nof your project. You can do that by creating user-provided options in\nyour build script. We create an user-provided option by using the\n`option()` method from the `Build` struct.\n\nWith this method, we create a \"build option\" which can be passed\nto the `build.zig` script at the command line. The user have the power of setting\nthis option at the `build` command from the\n`zig` compiler. In other words, each build option that we create\nbecomes a new command line argument that is accessible through the `build` command\nof the compiler.\n\nThese \"user-provided options\" are set by using the prefix `-D` in the command line.\nFor example, if we declare an option named `use_zlib`, that receives a boolean value which\nindicates if we should link our source code to `zlib` or not, we can set the value\nof this option in the command line with `-Duse_zlib`. The code example below\ndemonstrates this idea:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const use_zlib = b.option(\n        bool,\n        \"use_zlib\",\n        \"Should link to zlib?\"\n    ) orelse false;\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"example.zig\"),\n        .target = b.host,\n    });\n    if (use_zlib) {\n        exe.linkSystemLibrary(\"zlib\");\n    }\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\n```bash\nzig build -Duse_zlib=false\n```\n\n\n## Linking to external libraries\n\n\nOne essential part of every build process is the linking stage.\nThis stage is responsible for combining the multiple object files\nthat represent your code, into a single executable file. It also links\nthis executable file to external libraries, if you use any in your code.\n\nIn Zig, we have two notions of a \"library\", which are: 1) a system's library;\n2) a local library. A system's library is just a library that already is installed\nin your system. While a local library is a library that belongs to the current\nproject. Is a library that is present in your project directory, and\nthat you are building together with your project source code.\n\nThe basic difference between the two, is that a system's library is already\nbuilt and installed in your system, supposedly, and all you need to do\nis to link your source code to this library to start using it.\nWe do that by using the `linkSystemLibrary()` method from a\n`Compile` object. This method accepts the name of the library\nin a string as input. Remember from @sec-targets that a `Compile` object\nis a target object that you declare in your build script.\n\nWhen you link a particular target object with a system's library,\nthe `zig` compiler will use `pkg-config` to find where\nare the binary files and also the header files of this library\nin your system.\nWhen it finds these files, the linker present in the `zig` compiler\nwill link your object files with the files of this library to\nproduce a single binary file for you.\n\nIn the example below, we are creating an executable file named `image_filter`,\nand, we are linking this executable file to the C Standard Library with the\nmethod `linkLibC()`, but we also are linking this executable file to the\nC library `libpng` that is currently installed in my system.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"image_filter\",\n        .root_source_file = b.path(\"src/main.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n    exe.linkLibC();\n    exe.linkSystemLibrary(\"png\");\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\nIf you are linking with a C library in your project, is generally a good idea\nto also link your code with the C Standard Library. Because is very likely\nthat this C library uses some functionality of the C Standard Library at some point.\nThe same goes to C++ libraries. So, if you are linking with\nC++ libraries, is a good idea to link your project with the C++\nStandard Library by using the `linkLibCpp()` method.\n\nOn the order side, when you want to link with a local library,\nyou should use the `linkLibrary()` method of a `Compile` object.\nThis method expects to receive another `Compile` object as input.\nThat is, another target object defined in your build script,\nusing either the `addStaticLibrary()` or `addSharedLibrary()` methods\nwhich defines a library to be built.\n\nAs we discussed earlier, a local library is a library\nthat is local to your project, and that is being built together\nwith your project. So, you need to create a target object in your build script\nto build this local library. Then, you link the target objects of interest in your project,\nwith this target object that identifies this local library.\n\nTake a look at this example extracted from the build script of the [`libxev` library](https://github.com/mitchellh/libxev/tree/main)[^libxev2].\nYou can see in this snippet that\nwe are declaring a shared library file, from the `c_api.zig`\nmodule. Then, later in the build script, we declare an\nexecutable file named `\"dynamic-binding-test\"`, which\nlinks to this shared library that we defined earlier\nin the script.\n\n[^libxev2]: <https://github.com/mitchellh/libxev/tree/main>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst optimize = b.standardOptimizeOption(.{});\nconst target = b.standardTargetOptions(.{});\n\nconst dynamic_lib = b.addSharedLibrary(.{\n    .name = dynamic_lib_name,\n    .root_source_file = b.path(\"src/c_api.zig\"),\n    .target = target,\n    .optimize = optimize,\n});\nb.installArtifact(dynamic_lib);\n// ... more lines in the script\nconst dynamic_binding_test = b.addExecutable(.{\n    .name = \"dynamic-binding-test\",\n    .target = target,\n    .optimize = optimize,\n});\ndynamic_binding_test.linkLibrary(dynamic_lib);\n```\n:::\n\n\n\n\n\n\n## Building C code {#sec-building-c-code}\n\nThe `zig` compiler comes with a C compiler embedded in it. In other words,\nyou can use the `zig` compiler to build C projects. This C compiler is available\nthrough the `cc` command of the `zig` compiler.\n\nAs an example, let's use the famous [FreeType library](https://freetype.org/)[^freetype].\nFreeType is one of the most widely used pieces of software in the world.\nIt is a C library designed to produce high-quality fonts. But it is also\nheavily used in the industry to natively render text and fonts\nin the screen of your computer.\n\nIn this section, we are going to write a build script, piece by piece, that is capable\nof building the FreeType project from source.\nYou can find the source code of this build script on the\n[`freetype-zig` repository](https://github.com/pedropark99/freetype-zig/tree/main)[^freetype-zig]\navailable at GitHub.\n\n[^freetype]: <https://freetype.org/>\n[^freetype-zig]: <https://github.com/pedropark99/freetype-zig/tree/main>\n\nAfter you download the source code of FreeType from the official website[^freetype],\nyou can start writing the `build.zig` module. We begin by defining the target object\nthat defines the binary file that we want to compile.\n\nAs an example, I will build the project as a static library file using the `addStaticLibrary()` method\nto create the target object.\nAlso, since FreeType is a C library, I will also link the library\nagainst `libc` through the `linkLibC()` method, to guarantee that any use\nof the C Standard Library is covered in the compilation process.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst target = b.standardTargetOptions(.{});\nconst opti = b.standardOptimizeOption(.{});\nconst lib = b.addStaticLibrary(.{\n    .name = \"freetype\",\n    .optimize = opti,\n    .target = target,\n});\nlib.linkLibC();\n```\n:::\n\n\n\n\n### Creating C compiler flags\n\nCompiler flags are also known as \"compiler options\" by many programmers,\nor also, as \"command options\" in the GCC official documentation.\nIt's fair to also call them as the \"command-line arguments\" of the C compiler.\nIn general, we use compiler flags to turn on (or turn off) some features from the compiler,\nor to tweak the compilation process to fit the needs of our project.\n\nIn build scripts written in Zig, we normally list the C compiler flags to be used in the compilation process\nin a simple array, like in the example below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c_flags = [_][]const u8{\n    \"-Wall\",\n    \"-Wextra\",\n    \"-Werror\",\n};\n```\n:::\n\n\n\n\nIn theory, there is nothing stopping you from using this array to add \"include paths\" (with the `-I` flag)\nor \"library paths\" (with the `-L` flag) to the compilation process. But there are formal ways in Zig to\nadd these types of paths in the compilation process. Both are discussed at @sec-include-paths\nand @sec-library-paths.\n\nAnyway, in Zig, we add C flags to the build process together with the C files that we want to compile, by using the\n`addCSourceFile()` and `addCSourceFiles()` methods. In the example above, we have just declared\nthe C flags that we want to use. But we haven't added them to the build process yet.\nTo do that, we also need to list the C files to be compiled.\n\n### Listing your C files\n\nThe C files that contains \"cross-platform\" source code are listed in the `c_source_files`\nobject below. These are the C files that are included by default in every platform\nsupported by the FreeType library. Now, since the amount of C files in the FreeType library is big,\nI have omitted the rest of the files in the code example below, for brevity purposes.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c_source_files = [_][]const u8{\n    \"src/autofit/autofit.c\",\n    \"src/base/ftbase.c\",\n    // ... and many other C files.\n};\n```\n:::\n\n\n\n\nNow, in addition to \"cross-platform\" source code, we also have some C files in the FreeType project\nthat are platform-specific, meaning that, they contain source code that can only be compiled in specific platforms,\nand, as a result, they are only included in the build process on these specific target platforms.\nThe objects that list these C files are exposed in the code example below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst windows_c_source_files = [_][]const u8{\n    \"builds/windows/ftdebug.c\",\n    \"builds/windows/ftsystem.c\"\n};\nconst linux_c_source_files = [_][]const u8{\n    \"src/base/ftsystem.c\",\n    \"src/base/ftdebug.c\"\n};\n```\n:::\n\n\n\n\nNow that we declared both the files that we want to include and the C compiler flags to be used,\nwe can add them to the target object that describes the FreeType library, by using the\n`addCSourceFile()` and `addCSourceFiles()` methods.\n\nBoth of these functions are methods from a `Compile` object (i.e. a target object).\nThe `addCSourceFile()` method is capable of adding a single C file to the target object,\nwhile the `addCSourceFiles()` method is used to add multiple C files in a single command.\nYou might prefer to use `addCSourceFile()` when you need to use different compiler flags\non specific C files in your project. But, if you can use the same compiler flags\nacross all C files, then, you will probably find `addCSourceFiles()` a better choice.\n\nNotice that we are using the `addCSourceFiles()` method in the example below,\nto add both the C files and the C compiler flags. Also notice that we\nare using the `os.tag` that we learned about at @sec-detect-os, to add the platform-specific\nC files.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nlib.addCSourceFiles(\n    &c_source_files, &c_flags\n);\n\nswitch (builtin.target.os.tag) {\n    .windows => {\n        lib.addCSourceFiles(\n            &windows_c_source_files,\n            &c_flags\n        );\n    },\n    .linux => {\n        lib.addCSourceFiles(\n            &linux_c_source_files,\n            &c_flags\n        );\n    },\n    else => {},\n}\n```\n:::\n\n\n\n\n\n### Defining C Macros\n\nC Macros are an essential part of the C programming language,\nand they are commonly defined through the `-D` flag from a C compiler.\nIn Zig, you can define a C Macro to be used in your build process\nby using the `defineCMacro()` method from the target object that\ndefines the binary file that you are building.\n\nIn the example below, we are using the `lib` object that we have defined\non the previous sections to define some C Macros used by the FreeType project\nin the compilation process. These C Macros specify if FreeType\nshould (or should not) include functionalities from different\nexternal libraries.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nlib.defineCMacro(\"FT_DISABLE_ZLIB\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_PNG\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_HARFBUZZ\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BZIP2\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BROTLI\", \"TRUE\");\nlib.defineCMacro(\"FT2_BUILD_LIBRARY\", \"TRUE\");\n```\n:::\n\n\n\n\n\n### Adding library paths {#sec-library-paths}\n\nLibrary paths are paths in your computer where the C compiler will look (or search) for\nlibrary files to link against your source code. In other words, when you use a library in your\nC source code, and you ask the C compiler to link your source code against this library,\nthe C compiler will search for the binary files of this library across the paths listed\nin this \"library paths\" set.\n\nThese paths are platform specific, and, by default, the C compiler starts by looking at a\npre-defined set of places in your computer. But you can add more paths (or more places)\nto this list. For example, you may have a library installed in a non-conventional place of your\ncomputer, and you can make the C compiler \"see\" this \"non-conventional place\" by adding this path\nto this list of pre-defined paths.\n\nIn Zig, you can add more paths to this set by using the `addLibraryPath()` method from your target object.\nFirst, you defined a `LazyPath` object, containing the path you want to add, then,\nyou provide this object as input to the `addLibraryPath()` method, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst lib_path: std.Build.LazyPath = .{\n    .cwd_relative = \"/usr/local/lib/\"\n};\nlib.addLibraryPath(lib_path);\n```\n:::\n\n\n\n\n\n\n\n### Adding include paths {#sec-include-paths}\n\nThe preprocessor search path is a popular concept from the\nC community, but it is also known by many C programmers as \"include paths\", because\nthe paths in this \"search path\" relate to the `#include` statements found in the C files.\n\nInclude paths are similar to library paths. They are a set of pre-defined places in your computer where\nthe C compiler will look for files during the compilation process. But instead of looking for\nlibrary files, the include paths are places where the compiler looks for header files included\nin your C source code.\nThis is why many C programmers prefer to call these paths as the \"preprocessor search path\".\nBecause header files are processed during the preprocessor stage of the compilation\nprocess.\n\nSo, every header file that you include in your C source code, through a `#include` statements needs to\nbe found somewhere, and the C compiler will search for this header file across the paths listed in this \"include paths\" set.\nInclude paths are added to the compilation process through the `-I` flag.\n\nIn Zig, you can add new paths to this pre-defined set of paths, by using the `addIncludePath()` method\nfrom your target object. This method also accepts a `LazyPath` object as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst inc_path: std.Build.LazyPath = .{\n    .path = \"./include\"\n};\nlib.addIncludePath(inc_path);\n```\n:::\n",
-    "supporting": [
-      "07-build-system_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n\n# Build System {#sec-build-system}\n\n\nIn this chapter, we are going to talk about the build system, and how an entire project\nis built in Zig.\nOne key advantage of Zig is that it includes a build system embedded in the language itself.\nThis is great, because then you do not have to depend on an external system, separated\nfrom the compiler, to build your code.\n\n\nYou can find a good description of Zig's build system\non the [article entitled \"Build System\"](https://ziglang.org/learn/build-system/#user-provided-options)[^zig-art1]\nfrom the official Zig's website.\nWe also have the excellent [series of posts written by Felix](https://zig.news/xq/zig-build-explained-part-1-59lf)[^felix].\nHence, this chapter represents an extra resource for you to consult and rely on.\n\n[^felix]: <https://zig.news/xq/zig-build-explained-part-1-59lf>\n[^zig-art1]: <https://ziglang.org/learn/build-system/#user-provided-options>\n\nBuilding code is one of the things that Zig is best at. One thing that is particularly\ndifficult in C/C++ and even in Rust, is to cross-compile source code to multiple targets\n(e.g. multiple computer architectures and operational systems),\nand the `zig` compiler is known for being one of the best existing pieces of software\nfor this particular task.\n\n\n\n\n## How source code is built?\n\nWe already have talked about the challenges of building source code in low-level languages\nat @sec-project-files. As we described at that section, programmers invented Build Systems\nto surpass these challenges on the process of building source code in low-level languages.\n\nLow-level languages uses a compiler to compile (or to build) your source code into binary instructions.\nIn C and C++, we normally use compilers like `gcc`, `g++` or `clang` to compile\nour C and C++ source code into these instructions.\nEvery language have its own compiler, and this is no different in Zig.\n\nIn Zig, we have the `zig` compiler to compile our Zig source code into\nbinary instructions that can be executed by our computer.\nIn Zig, the compilation (or the build) process involves\nthe following components:\n\n- The Zig modules that contains your source code;\n- Library files (either a dynamic library or a static library);\n- Compiler flags that tailors the build process to your needs.\n\nThese are the things that you need to connect together in order to build your\nsource code in Zig. In C and C++, you would have an extra component, which are the header files of\nthe libraries that you are using. But header files do not exist in Zig, so, you only need\nto care about them if you are linking your Zig source code with a C library.\nIf that is not your case, you can forget about it.\n\nYour build process is usually organized in a build script. In Zig, we normally\nwrite this build script into a Zig module in the root directory of our project,\nnamed as `build.zig`. You write this build script, then, when you run it, your project\nget's built into binary files that you can use and distribute to your users.\n\nThis build script is normally organized around *target objects*. A target is simply\nsomething to be built, or, in other words, it's something that you want the `zig` compiler\nto build for you. This concept of \"targets\" is present in most Build Systems,\nespecially in CMake[^cmake].\n\n[^cmake]: <https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html>\n\nThere are four types of target objects that you can build in Zig, which are:\n\n- An executable (e.g. a `.exe` file on Windows).\n- A shared library (e.g. a `.so` file in Linux or a `.dll` file on Windows).\n- A static library (e.g. a `.a` file in Linux or a `.lib` file on Windows).\n- An executable file that executes only unit tests (or, a \"unit tests executable\").\n\nWe are going to talk more about these target objects at @sec-targets.\n\n\n\n## The `build()` function {#sec-build-fun}\n\nA build script in Zig always contains a public (and top-level) `build()` function declared.\nIt is like the `main()` function on the main Zig module of your project, that we discussed at @sec-main-file.\nBut instead of creating the entrypoint to your code, this `build()` function is the entrypoint to the build process.\n\nThis `build()` function should accept a pointer to a `Build` object as input, and it should use this \"build object\" to perform\nthe necessary steps to build your project. The return type of this function is always `void`,\nand this `Build` struct comes directly from the Zig Standard Library (`std.Build`). So, you can \naccess this struct by just importing the Zig Standard Library into your `build.zig` module.\n\nJust as a very simple example, here you can see the source code necessary to build\nan executable file from the `hello.zig` Zig module.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"hello.zig\"),\n        .target = b.host,\n    });\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\n\nYou can define and use other functions and objects in this build script. You can also import\nother Zig modules as you would normally do in any other module of your project.\nThe only real requirement for this build script, is to have a public and top-level\n`build()` function defined, that accepts a pointer to a `Build` struct as input.\n\n\n## Target objects {#sec-targets}\n\nAs we described over the previous sections, a build script is composed around target objects.\nEach target object is normally a binary file (or an output) that you want to get from the build process. You can list\nmultiple target objects in your build script, so that the build process generates multiple\nbinary files for you at once.\n\nFor example, maybe you are a developer working in a cross-platform application,\nand, because this application is cross-platform, you probably need to release\nbinary files of your software for each OS supported by your application to your end users.\nThus, you can define a different target object in your build script\nfor each OS (Windows, Linux, etc.) where you want to publish your software.\nThis will make the `zig` compiler to build your project to multiple target OS's at once.\nThe Zig Build System official documentation have a [great code example that demonstrates this strategy](https://ziglang.org/learn/build-system/#handy-examples)[^zig-ex].\n\n[^zig-ex]: <https://ziglang.org/learn/build-system/#handy-examples>\n\n\nA target object is created by the following methods of the `Build` struct that we introduced\nat @sec-build-fun:\n\n- `addExecutable()` creates an executable file;\n- `addSharedLibrary()` creates a shared library file;\n- `addStaticLibrary()` creates a static library file;\n- `addTest()` creates an executable file that executes unit tests.\n\n\nThese functions are methods from the `Build` struct that you receive\nas input of the `build()` function. All of them, create as output\na `Compile` object, which represents a target object to be compiled\nby the `zig` compiler. All of these functions accept a similar struct literal as input.\nThis struct literal defines three essential specs about this target object that you are building:\n`name`, `target` and `root_source_file`.\n\nWe have already seen these three options being used on the previous example,\nwhere we used the `addExecutable()` method to create an executable target object.\nThis example is reproduced below. Notice the use of the `path()` method\nfrom the `Build` struct, to define a path in the `root_source_file` option.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n```\n:::\n\n\n\n\n\nThe `name` option specify the name that you want to give to the binary file defined\nby this target object. So, in this example, we are building an executable file named `hello`.\nIs common to set this `name` option to the name of your project.\n\n\nFurthermore, the `target` option specify the target computer architecture (or the target operational system) of this\nbinary file. For example, if you want this target object to run on a Windows machine\nthat uses a `x86_64` architecture, you can set this `target` option to `x86_64-windows-gnu` for example.\nThis will make the `zig` compiler to compile the project to run on a `x86_64` Windows machine.\nYou can see the full list of architectures and OS's that the `zig` compiler supports by running\nthe `zig targets` command in the terminal.\n\nNow, if you are building the project to run on the current machine\nthat you are using to run this build script, you can set this `target`\noption to the `host` method of the `Build` object, like we did in the example above.\nThis `host` method identifies the current machine where you are\ncurrently running the `zig` compiler.\n\n\nAt last, the `root_source_file` option specifies the root Zig module of your project.\nThat is the Zig module that contains the entrypoint to your application (i.e. the `main()` function), or, the main API of your library.\nThis also means that, all the Zig modules that compose your project are automatically discovered\nfrom the import statements you have inside this \"root source file\".\nThe `zig` compiler can detect when a Zig module depends on the other through the import statements,\nand, as a result, it can discover the entire map of Zig modules used in your project.\n\nThis is handy, and it is different from what happens in other build systems.\nIn CMake for example, you have to explicitly list the paths to all source files that you want to\ninclude in your build process. This is probably a symptom of the \"lack of conditional\ncompilation\" in the C and C++ compilers. Since they lack this feature, you have\nto explicitly choose which source files should be sent to the C/C++ compiler, because not\nevery C/C++ code is portable or supported in every operational system, and, therefore,\nwould cause a compilation error in the C/C++ compiler.\n\n\nNow, one important detail about the build process is that, you have to **explicitly\ninstall the target objects that you create in your build script**, by using the\n`installArtifact()` method of the `Build` struct.\n\nEverytime you invoke the build process of your project, by calling the `build` command\nof the `zig` compiler, a new directory named `zig-out` is created in the root\ndirectory of your project. This new directory contains the outputs of the build process,\nthat is, the binary files built from your source code.\n\nWhat the `installArtifact()` method do is to install (or copy) the built target objects\nthat you defined to this `zig-out` directory.\nThis means that, if you do not\ninstall the target objects you define in your build script, these target objects are\nessentially discarded at the end of the build process.\n\nFor example, you might be building a project that uses a third party library that is built\ntogether with the project. So, when you build your project, you would need first, to\nbuild the third party library, and then, you link it with the source code of your project.\nSo, in this case, we have two binary files that are generated in the build process (the executable file of your project, and the third party library).\nBut only one is of interest, which is the executable file of our project.\nWe can discard the binary file of the third party library, by simply not installing it\ninto this `zig-out` directory.\n\nThis `installArtifact()` method is pretty straightforward. Just remember to apply it to every\ntarget object that you want to save into the `zig-out` directory, like in the example below:\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n\n## Setting the build mode\n\nWe have talked about the three essential options that are set when you create a new target object.\nBut there is also a fourth option that you can use to set the build mode of this target object,\nwhich is the `optimize` option.\nThis option is called this way, because the build modes in Zig are treated more of\nan \"optimization vs safety\" problem. So optimization plays an important role here.\nDon't worry, I'm going back to this question very soon.\n\nIn Zig, we have four build modes (which are listed below). Each one of these build modes offer\ndifferent advantages and characteristics. As we described at @sec-compile-debug-mode, the `zig` compiler\nuses the `Debug` build mode by default, when you don't explicitly choose a build mode.\n\n- `Debug`, mode that produces and includes debugging information in the output of the build process (i.e. the binary file defined by the target object);\n- `ReleaseSmall`, mode that tries to produce a binary file that is small in size;\n- `ReleaseFast`, mode that tries to optimize your code, in order to produce a binary file that is as fast as possible;\n- `ReleaseSafe`, mode that tries to make your code as safe as possible, by including safeguards when possible.\n\nSo, when you build your project, you can set the build mode of your target object to `ReleaseFast` for example, which will tell\nthe `zig` compiler to apply important optimizations in your code. This creates a binary file\nthat simply runs faster on most contexts, because it contains a more optimized version of your code.\nHowever, as a result, we often lose some safety features in our code.\nBecause some safety checks are removed from the final binary file,\nwhich makes your code run faster, but in a less safe manner.\n\nThis choice depends on your current priorities. If you are building a cryptography or banking system, you might\nprefer to prioritize safety in your code, so, you would choose the `ReleaseSafe` build mode, which is a little\nslower to run, but much more secure, because it includes all possible runtime safety checks in the binary file\nbuilt in the build process. In the other hand, if you are writing a game for example, you might prefer to prioritize performance\nover safety, by using the `ReleaseFast` build mode, so that your users can experience faster frame rates in your game.\n\nIn the example below, we are creating the same target object that we have used on previous examples.\nBut this time, we are specifying the build mode of this target object to the `ReleaseSafe` mode.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .optimize = .ReleaseSafe\n});\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n\n## Setting the version of your build\n\nEverytime you build a target object in your build script, you can assign a version\nnumber to this specific build, following a semantic versioning framework.\nYou can find more about semantic versioning by visiting the [Semantic Versioning website](https://semver.org/)[^semver].\nAnyway, in Zig, you can specify the version of your build, by providing a `SemanticVersion` struct to\nthe `version` option, like in the example below:\n\n\n[^semver]: <https://semver.org/>\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .version = .{\n        .major = 2, .minor = 9, .patch = 7\n    }\n});\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n\n## Detecting the OS in your build script {#sec-detect-os}\n\nIs very common in Build Systems to use different options, or, to include different modules, or,\nto link against different libraries depending on the Operational System (OS)\nthat you are targeting in the build process.\n\nIn Zig, you can detect the target OS of the build process, by looking\nat the `os.tag` inside the `builtin` module from the Zig library.\nIn the example below, we are using an if statement to run some\narbitrary code when the target of the build process is a\nWindows system.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nif (builtin.target.os.tag == .windows) {\n    // Code that runs only when the target of\n    // the compilation process is Windows.\n}\n```\n:::\n\n\n\n\n\n\n## Adding a run step to your build process\n\nOne thing that is neat in Rust is that you can compile and run your\nsource code with one single command (`cargo run`) from the Rust compiler.\nWe saw at @sec-compile-run-code how can we perform a similar job in Zig, by\nbuilding and running our Zig source code through the `run` command from the `zig` compiler.\n\nBut how can we, at the same time, build and run the binary file specified by a target object in our\nbuild script?\nThe answer is by including a \"run artifact\" in our build script.\nA run artifact is created through the `addRunArtifact()` method from the `Build` struct.\nWe simply provide as input to this function the target object that describes the binary file that we\nwant to execute. As a result, this function creates a run artifact that is capable of executing\nthis binary file.\n\nIn the example below, we are defining an executable binary file named `hello`,\nand we use this `addRunArtifact()` method to create a run artifact that will execute\nthis `hello` executable file.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"src/hello.zig\"),\n    .target = b.host\n});\nb.installArtifact(exe);\nconst run_arti = b.addRunArtifact(exe);\n```\n:::\n\n\n\n\n\nNow that we have created this run artifact, we need to include it in\nthe build process. We do that by declaring a new step in our build\nscript to call this artifact, through the `step()` method of the `Build`\nstruct.\n\nWe can give any name we want to this step, but, for our\ncontext here, I'm going to name this step as \"run\".\nAlso, I give it a brief description to this step (\"Run the project\").\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst run_step = b.step(\n    \"run\", \"Run the project\"\n);\n```\n:::\n\n\n\n\n\n\nNow that we have declared this \"run step\" we need to tell Zig that\nthis \"run step\" depends on the run artifact.\nIn other words, a run artifact always depends on a \"step\" to effectively be executed.\nBy creating this dependency\nwe finally stablish the necessary commands to build and run the executable file\nfrom the build script.\n\nWe can establish a dependency between the run step and the run artifact\nby using the `dependsOn()` method from the run step. So, we first\ncreate the run step, and then, we link it with the run artifact, by\nusing this `dependsOn()` method from the run step.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nrun_step.dependOn(&run_arti.step);\n```\n:::\n\n\n\n\n\nThe entire source code of this specific build script that\nwe wrote, piece by piece, in this section, is\navailable in the `build_and_run.zig` module. You can\nsee this module by\n[visiting the official repository of this book](https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig)\n[^module-src].\n\n\n[^module-src]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig>\n\nWhen you declare a new step in your build script, this step\nbecomes available through the `build` command in the `zig` compiler.\nYou can actually see this step by running `zig build --help` in the terminal, like\nin the example below, where we can see that this new \"run\"\nstep that we declared in the build script appeared in the output.\n\n```bash\nzig build --help\n```\n\n```\nSteps:\n  ...\n  run   Run the project\n  ...\n```\n\nNow, everything that we need to is to\ncall this \"run\" step that we created in our build script. We\ncall it by using the name that we gave to this step\nafter the `build` command from the `zig` compiler.\nThis will cause the compiler to build our executable file\nand execute it at the same time.\n\n```bash\nzig build run\n```\n\n## Build unit tests in your project\n\nWe have talked at length about writing unit tests in Zig at @sec-unittests,\nand we also have talked about how to execute these unit tests through\nthe `test` command of the `zig` compiler. However,\nas we did with the `run` command on the previous section, we also might want to\ninclude some commands in our build script to also build and execute the unit tests in our project.\n\nSo, once again, we are going to discuss how a specific built-in command from the `zig` compiler,\n(in this case, the `test` command) can be used in a build script in Zig.\nHere is where a \"test target object\" comes into play.\nAs was described at @sec-targets, we can create a test target object by using the `addTest()` method of\nthe `Build` struct. The first thing that we need to do is to\ndeclare a test target object in our build script.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst test_exe = b.addTest(.{\n    .name = \"unit_tests\",\n    .root_source_file = b.path(\"src/main.zig\"),\n    .target = b.host,\n});\nb.installArtifact(test_exe);\n```\n:::\n\n\n\n\n\n\nA test target object essentially selects all `test` blocks in all Zig modules\nacross your project, and builds only the source code present inside\nthese `test` blocks in your project. As a result, this target object\ncreates an executable file that contains only the source code present\nin all of these `test` blocks (i.e. the unit tests) in your project.\n\nPerfect! Now that we have declared this test target object, an executable file\nnamed `unit_tests` is built by the `zig` compiler when we trigger the build\nscript with the `build` command. After the build\nprocess is finished, we can simply execute this `unit_tests` executable\nin the terminal.\n\nHowever, if you remember the previous section, we already learned\nhow can we create a run step in our build script, to execute an executable file\nbuilt by the build script.\n\nSo, we could simply add a run step in our build script to run these unit tests\nfrom a single command in the `zig` compiler, to make our lifes easier.\nIn the example below, we demonstrate the commands to\nregister a new build step called \"tests\" in our build script\nto run these unit tests.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst run_arti = b.addRunArtifact(test_exe);\nconst run_step = b.step(\"tests\", \"Run unit tests\");\nrun_step.dependOn(&run_arti.step);\n```\n:::\n\n\n\n\n\nNow that we registered this new build step, we can trigger it by calling the command below\nin the terminal. You can also checkout the complete source\ncode for this specific build script at the `build_tests.zig` module at the\n[official repository of this book](https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig)\n[^module-src2].\n\n\n[^module-src2]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig>\n\n\n```bash\nzig build tests\n```\n\n\n## Tailoring your build process with user-provided options\n\nSometimes, you want to make a build script that is customizable by the user\nof your project. You can do that by creating user-provided options in\nyour build script. We create an user-provided option by using the\n`option()` method from the `Build` struct.\n\nWith this method, we create a \"build option\" which can be passed\nto the `build.zig` script at the command line. The user have the power of setting\nthis option at the `build` command from the\n`zig` compiler. In other words, each build option that we create\nbecomes a new command line argument that is accessible through the `build` command\nof the compiler.\n\nThese \"user-provided options\" are set by using the prefix `-D` in the command line.\nFor example, if we declare an option named `use_zlib`, that receives a boolean value which\nindicates if we should link our source code to `zlib` or not, we can set the value\nof this option in the command line with `-Duse_zlib`. The code example below\ndemonstrates this idea:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const use_zlib = b.option(\n        bool,\n        \"use_zlib\",\n        \"Should link to zlib?\"\n    ) orelse false;\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"example.zig\"),\n        .target = b.host,\n    });\n    if (use_zlib) {\n        exe.linkSystemLibrary(\"zlib\");\n    }\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\n\n```bash\nzig build -Duse_zlib=false\n```\n\n\n## Linking to external libraries\n\n\nOne essential part of every build process is the linking stage.\nThis stage is responsible for combining the multiple object files\nthat represent your code, into a single executable file. It also links\nthis executable file to external libraries, if you use any in your code.\n\nIn Zig, we have two notions of a \"library\", which are: 1) a system's library;\n2) a local library. A system's library is just a library that already is installed\nin your system. While a local library is a library that belongs to the current\nproject. Is a library that is present in your project directory, and\nthat you are building together with your project source code.\n\nThe basic difference between the two, is that a system's library is already\nbuilt and installed in your system, supposedly, and all you need to do\nis to link your source code to this library to start using it.\nWe do that by using the `linkSystemLibrary()` method from a\n`Compile` object. This method accepts the name of the library\nin a string as input. Remember from @sec-targets that a `Compile` object\nis a target object that you declare in your build script.\n\nWhen you link a particular target object with a system's library,\nthe `zig` compiler will use `pkg-config` to find where\nare the binary files and also the header files of this library\nin your system.\nWhen it finds these files, the linker present in the `zig` compiler\nwill link your object files with the files of this library to\nproduce a single binary file for you.\n\nIn the example below, we are creating an executable file named `image_filter`,\nand, we are linking this executable file to the C Standard Library with the\nmethod `linkLibC()`, but we also are linking this executable file to the\nC library `libpng` that is currently installed in my system.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"image_filter\",\n        .root_source_file = b.path(\"src/main.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n    exe.linkLibC();\n    exe.linkSystemLibrary(\"png\");\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\n\nIf you are linking with a C library in your project, is generally a good idea\nto also link your code with the C Standard Library. Because is very likely\nthat this C library uses some functionality of the C Standard Library at some point.\nThe same goes to C++ libraries. So, if you are linking with\nC++ libraries, is a good idea to link your project with the C++\nStandard Library by using the `linkLibCpp()` method.\n\nOn the order side, when you want to link with a local library,\nyou should use the `linkLibrary()` method of a `Compile` object.\nThis method expects to receive another `Compile` object as input.\nThat is, another target object defined in your build script,\nusing either the `addStaticLibrary()` or `addSharedLibrary()` methods\nwhich defines a library to be built.\n\nAs we discussed earlier, a local library is a library\nthat is local to your project, and that is being built together\nwith your project. So, you need to create a target object in your build script\nto build this local library. Then, you link the target objects of interest in your project,\nwith this target object that identifies this local library.\n\nTake a look at this example extracted from the build script of the [`libxev` library](https://github.com/mitchellh/libxev/tree/main)[^libxev2].\nYou can see in this snippet that\nwe are declaring a shared library file, from the `c_api.zig`\nmodule. Then, later in the build script, we declare an\nexecutable file named `\"dynamic-binding-test\"`, which\nlinks to this shared library that we defined earlier\nin the script.\n\n[^libxev2]: <https://github.com/mitchellh/libxev/tree/main>\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst optimize = b.standardOptimizeOption(.{});\nconst target = b.standardTargetOptions(.{});\n\nconst dynamic_lib = b.addSharedLibrary(.{\n    .name = dynamic_lib_name,\n    .root_source_file = b.path(\"src/c_api.zig\"),\n    .target = target,\n    .optimize = optimize,\n});\nb.installArtifact(dynamic_lib);\n// ... more lines in the script\nconst dynamic_binding_test = b.addExecutable(.{\n    .name = \"dynamic-binding-test\",\n    .target = target,\n    .optimize = optimize,\n});\ndynamic_binding_test.linkLibrary(dynamic_lib);\n```\n:::\n\n\n\n\n\n\n\n## Building C code {#sec-building-c-code}\n\nThe `zig` compiler comes with a C compiler embedded in it. In other words,\nyou can use the `zig` compiler to build C projects. This C compiler is available\nthrough the `cc` command of the `zig` compiler.\n\nAs an example, let's use the famous [FreeType library](https://freetype.org/)[^freetype].\nFreeType is one of the most widely used pieces of software in the world.\nIt is a C library designed to produce high-quality fonts. But it is also\nheavily used in the industry to natively render text and fonts\nin the screen of your computer.\n\nIn this section, we are going to write a build script, piece by piece, that is capable\nof building the FreeType project from source.\nYou can find the source code of this build script on the\n[`freetype-zig` repository](https://github.com/pedropark99/freetype-zig/tree/main)[^freetype-zig]\navailable at GitHub.\n\n[^freetype]: <https://freetype.org/>\n[^freetype-zig]: <https://github.com/pedropark99/freetype-zig/tree/main>\n\nAfter you download the source code of FreeType from the official website[^freetype],\nyou can start writing the `build.zig` module. We begin by defining the target object\nthat defines the binary file that we want to compile.\n\nAs an example, I will build the project as a static library file using the `addStaticLibrary()` method\nto create the target object.\nAlso, since FreeType is a C library, I will also link the library\nagainst `libc` through the `linkLibC()` method, to guarantee that any use\nof the C Standard Library is covered in the compilation process.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst target = b.standardTargetOptions(.{});\nconst opti = b.standardOptimizeOption(.{});\nconst lib = b.addStaticLibrary(.{\n    .name = \"freetype\",\n    .optimize = opti,\n    .target = target,\n});\nlib.linkLibC();\n```\n:::\n\n\n\n\n\n### Creating C compiler flags\n\nCompiler flags are also known as \"compiler options\" by many programmers,\nor also, as \"command options\" in the GCC official documentation.\nIt's fair to also call them as the \"command-line arguments\" of the C compiler.\nIn general, we use compiler flags to turn on (or turn off) some features from the compiler,\nor to tweak the compilation process to fit the needs of our project.\n\nIn build scripts written in Zig, we normally list the C compiler flags to be used in the compilation process\nin a simple array, like in the example below.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c_flags = [_][]const u8{\n    \"-Wall\",\n    \"-Wextra\",\n    \"-Werror\",\n};\n```\n:::\n\n\n\n\n\nIn theory, there is nothing stopping you from using this array to add \"include paths\" (with the `-I` flag)\nor \"library paths\" (with the `-L` flag) to the compilation process. But there are formal ways in Zig to\nadd these types of paths in the compilation process. Both are discussed at @sec-include-paths\nand @sec-library-paths.\n\nAnyway, in Zig, we add C flags to the build process together with the C files that we want to compile, by using the\n`addCSourceFile()` and `addCSourceFiles()` methods. In the example above, we have just declared\nthe C flags that we want to use. But we haven't added them to the build process yet.\nTo do that, we also need to list the C files to be compiled.\n\n### Listing your C files\n\nThe C files that contains \"cross-platform\" source code are listed in the `c_source_files`\nobject below. These are the C files that are included by default in every platform\nsupported by the FreeType library. Now, since the amount of C files in the FreeType library is big,\nI have omitted the rest of the files in the code example below, for brevity purposes.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c_source_files = [_][]const u8{\n    \"src/autofit/autofit.c\",\n    \"src/base/ftbase.c\",\n    // ... and many other C files.\n};\n```\n:::\n\n\n\n\n\nNow, in addition to \"cross-platform\" source code, we also have some C files in the FreeType project\nthat are platform-specific, meaning that, they contain source code that can only be compiled in specific platforms,\nand, as a result, they are only included in the build process on these specific target platforms.\nThe objects that list these C files are exposed in the code example below.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst windows_c_source_files = [_][]const u8{\n    \"builds/windows/ftdebug.c\",\n    \"builds/windows/ftsystem.c\"\n};\nconst linux_c_source_files = [_][]const u8{\n    \"src/base/ftsystem.c\",\n    \"src/base/ftdebug.c\"\n};\n```\n:::\n\n\n\n\n\nNow that we declared both the files that we want to include and the C compiler flags to be used,\nwe can add them to the target object that describes the FreeType library, by using the\n`addCSourceFile()` and `addCSourceFiles()` methods.\n\nBoth of these functions are methods from a `Compile` object (i.e. a target object).\nThe `addCSourceFile()` method is capable of adding a single C file to the target object,\nwhile the `addCSourceFiles()` method is used to add multiple C files in a single command.\nYou might prefer to use `addCSourceFile()` when you need to use different compiler flags\non specific C files in your project. But, if you can use the same compiler flags\nacross all C files, then, you will probably find `addCSourceFiles()` a better choice.\n\nNotice that we are using the `addCSourceFiles()` method in the example below,\nto add both the C files and the C compiler flags. Also notice that we\nare using the `os.tag` that we learned about at @sec-detect-os, to add the platform-specific\nC files.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nlib.addCSourceFiles(\n    &c_source_files, &c_flags\n);\n\nswitch (builtin.target.os.tag) {\n    .windows => {\n        lib.addCSourceFiles(\n            &windows_c_source_files,\n            &c_flags\n        );\n    },\n    .linux => {\n        lib.addCSourceFiles(\n            &linux_c_source_files,\n            &c_flags\n        );\n    },\n    else => {},\n}\n```\n:::\n\n\n\n\n\n\n### Defining C Macros\n\nC Macros are an essential part of the C programming language,\nand they are commonly defined through the `-D` flag from a C compiler.\nIn Zig, you can define a C Macro to be used in your build process\nby using the `defineCMacro()` method from the target object that\ndefines the binary file that you are building.\n\nIn the example below, we are using the `lib` object that we have defined\non the previous sections to define some C Macros used by the FreeType project\nin the compilation process. These C Macros specify if FreeType\nshould (or should not) include functionalities from different\nexternal libraries.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nlib.defineCMacro(\"FT_DISABLE_ZLIB\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_PNG\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_HARFBUZZ\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BZIP2\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BROTLI\", \"TRUE\");\nlib.defineCMacro(\"FT2_BUILD_LIBRARY\", \"TRUE\");\n```\n:::\n\n\n\n\n\n\n### Adding library paths {#sec-library-paths}\n\nLibrary paths are paths in your computer where the C compiler will look (or search) for\nlibrary files to link against your source code. In other words, when you use a library in your\nC source code, and you ask the C compiler to link your source code against this library,\nthe C compiler will search for the binary files of this library across the paths listed\nin this \"library paths\" set.\n\nThese paths are platform specific, and, by default, the C compiler starts by looking at a\npre-defined set of places in your computer. But you can add more paths (or more places)\nto this list. For example, you may have a library installed in a non-conventional place of your\ncomputer, and you can make the C compiler \"see\" this \"non-conventional place\" by adding this path\nto this list of pre-defined paths.\n\nIn Zig, you can add more paths to this set by using the `addLibraryPath()` method from your target object.\nFirst, you defined a `LazyPath` object, containing the path you want to add, then,\nyou provide this object as input to the `addLibraryPath()` method, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst lib_path: std.Build.LazyPath = .{\n    .cwd_relative = \"/usr/local/lib/\"\n};\nlib.addLibraryPath(lib_path);\n```\n:::\n\n\n\n\n\n\n\n\n### Adding include paths {#sec-include-paths}\n\nThe preprocessor search path is a popular concept from the\nC community, but it is also known by many C programmers as \"include paths\", because\nthe paths in this \"search path\" relate to the `#include` statements found in the C files.\n\nInclude paths are similar to library paths. They are a set of pre-defined places in your computer where\nthe C compiler will look for files during the compilation process. But instead of looking for\nlibrary files, the include paths are places where the compiler looks for header files included\nin your C source code.\nThis is why many C programmers prefer to call these paths as the \"preprocessor search path\".\nBecause header files are processed during the preprocessor stage of the compilation\nprocess.\n\nSo, every header file that you include in your C source code, through a `#include` statements needs to\nbe found somewhere, and the C compiler will search for this header file across the paths listed in this \"include paths\" set.\nInclude paths are added to the compilation process through the `-I` flag.\n\nIn Zig, you can add new paths to this pre-defined set of paths, by using the `addIncludePath()` method\nfrom your target object. This method also accepts a `LazyPath` object as input.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst inc_path: std.Build.LazyPath = .{\n    .path = \"./include\"\n};\nlib.addIncludePath(inc_path);\n```\n:::\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/docs/Chapters/07-build-system.html b/docs/Chapters/07-build-system.html
index 196ebac6..9a4626a8 100644
--- a/docs/Chapters/07-build-system.html
+++ b/docs/Chapters/07-build-system.html
@@ -395,7 +395,7 @@ <h2 data-number="9.3" class="anchored" data-anchor-id="sec-targets"><span class=
 <p>For example, you might be building a project that uses a third party library that is built together with the project. So, when you build your project, you would need first, to build the third party library, and then, you link it with the source code of your project. So, in this case, we have two binary files that are generated in the build process (the executable file of your project, and the third party library). But only one is of interest, which is the executable file of our project. We can discard the binary file of the third party library, by simply not installing it into this <code>zig-out</code> directory.</p>
 <p>This <code>installArtifact()</code> method is pretty straightforward. Just remember to apply it to every target object that you want to save into the <code>zig-out</code> directory, like in the example below:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb3"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a>exe = b.addExecutable(.<span class="op">{</span></span>
+<div class="sourceCode cell-code" id="cb3"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> exe = b.addExecutable(.<span class="op">{</span></span>
 <span id="cb3-2"><a href="#cb3-2" aria-hidden="true" tabindex="-1"></a>    .name = <span class="st">"hello"</span>,</span>
 <span id="cb3-3"><a href="#cb3-3" aria-hidden="true" tabindex="-1"></a>    .root_source_file = b.path(<span class="st">"hello.zig"</span>),</span>
 <span id="cb3-4"><a href="#cb3-4" aria-hidden="true" tabindex="-1"></a>    .target = b.host,</span>
diff --git a/docs/search.json b/docs/search.json
index d8cb3ea3..d8974a02 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -724,7 +724,7 @@
     "href": "Chapters/07-build-system.html#sec-targets",
     "title": "9  Build System",
     "section": "9.3 Target objects",
-    "text": "9.3 Target objects\nAs we described over the previous sections, a build script is composed around target objects. Each target object is normally a binary file (or an output) that you want to get from the build process. You can list multiple target objects in your build script, so that the build process generates multiple binary files for you at once.\nFor example, maybe you are a developer working in a cross-platform application, and, because this application is cross-platform, you probably need to release binary files of your software for each OS supported by your application to your end users. Thus, you can define a different target object in your build script for each OS (Windows, Linux, etc.) where you want to publish your software. This will make the zig compiler to build your project to multiple target OS’s at once. The Zig Build System official documentation have a great code example that demonstrates this strategy4.\nA target object is created by the following methods of the Build struct that we introduced at Section 9.2:\n\naddExecutable() creates an executable file;\naddSharedLibrary() creates a shared library file;\naddStaticLibrary() creates a static library file;\naddTest() creates an executable file that executes unit tests.\n\nThese functions are methods from the Build struct that you receive as input of the build() function. All of them, create as output a Compile object, which represents a target object to be compiled by the zig compiler. All of these functions accept a similar struct literal as input. This struct literal defines three essential specs about this target object that you are building: name, target and root_source_file.\nWe have already seen these three options being used on the previous example, where we used the addExecutable() method to create an executable target object. This example is reproduced below. Notice the use of the path() method from the Build struct, to define a path in the root_source_file option.\n\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nThe name option specify the name that you want to give to the binary file defined by this target object. So, in this example, we are building an executable file named hello. Is common to set this name option to the name of your project.\nFurthermore, the target option specify the target computer architecture (or the target operational system) of this binary file. For example, if you want this target object to run on a Windows machine that uses a x86_64 architecture, you can set this target option to x86_64-windows-gnu for example. This will make the zig compiler to compile the project to run on a x86_64 Windows machine. You can see the full list of architectures and OS’s that the zig compiler supports by running the zig targets command in the terminal.\nNow, if you are building the project to run on the current machine that you are using to run this build script, you can set this target option to the host method of the Build object, like we did in the example above. This host method identifies the current machine where you are currently running the zig compiler.\nAt last, the root_source_file option specifies the root Zig module of your project. That is the Zig module that contains the entrypoint to your application (i.e. the main() function), or, the main API of your library. This also means that, all the Zig modules that compose your project are automatically discovered from the import statements you have inside this “root source file”. The zig compiler can detect when a Zig module depends on the other through the import statements, and, as a result, it can discover the entire map of Zig modules used in your project.\nThis is handy, and it is different from what happens in other build systems. In CMake for example, you have to explicitly list the paths to all source files that you want to include in your build process. This is probably a symptom of the “lack of conditional compilation” in the C and C++ compilers. Since they lack this feature, you have to explicitly choose which source files should be sent to the C/C++ compiler, because not every C/C++ code is portable or supported in every operational system, and, therefore, would cause a compilation error in the C/C++ compiler.\nNow, one important detail about the build process is that, you have to explicitly install the target objects that you create in your build script, by using the installArtifact() method of the Build struct.\nEverytime you invoke the build process of your project, by calling the build command of the zig compiler, a new directory named zig-out is created in the root directory of your project. This new directory contains the outputs of the build process, that is, the binary files built from your source code.\nWhat the installArtifact() method do is to install (or copy) the built target objects that you defined to this zig-out directory. This means that, if you do not install the target objects you define in your build script, these target objects are essentially discarded at the end of the build process.\nFor example, you might be building a project that uses a third party library that is built together with the project. So, when you build your project, you would need first, to build the third party library, and then, you link it with the source code of your project. So, in this case, we have two binary files that are generated in the build process (the executable file of your project, and the third party library). But only one is of interest, which is the executable file of our project. We can discard the binary file of the third party library, by simply not installing it into this zig-out directory.\nThis installArtifact() method is pretty straightforward. Just remember to apply it to every target object that you want to save into the zig-out directory, like in the example below:\n\nexe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nb.installArtifact(exe);",
+    "text": "9.3 Target objects\nAs we described over the previous sections, a build script is composed around target objects. Each target object is normally a binary file (or an output) that you want to get from the build process. You can list multiple target objects in your build script, so that the build process generates multiple binary files for you at once.\nFor example, maybe you are a developer working in a cross-platform application, and, because this application is cross-platform, you probably need to release binary files of your software for each OS supported by your application to your end users. Thus, you can define a different target object in your build script for each OS (Windows, Linux, etc.) where you want to publish your software. This will make the zig compiler to build your project to multiple target OS’s at once. The Zig Build System official documentation have a great code example that demonstrates this strategy4.\nA target object is created by the following methods of the Build struct that we introduced at Section 9.2:\n\naddExecutable() creates an executable file;\naddSharedLibrary() creates a shared library file;\naddStaticLibrary() creates a static library file;\naddTest() creates an executable file that executes unit tests.\n\nThese functions are methods from the Build struct that you receive as input of the build() function. All of them, create as output a Compile object, which represents a target object to be compiled by the zig compiler. All of these functions accept a similar struct literal as input. This struct literal defines three essential specs about this target object that you are building: name, target and root_source_file.\nWe have already seen these three options being used on the previous example, where we used the addExecutable() method to create an executable target object. This example is reproduced below. Notice the use of the path() method from the Build struct, to define a path in the root_source_file option.\n\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nThe name option specify the name that you want to give to the binary file defined by this target object. So, in this example, we are building an executable file named hello. Is common to set this name option to the name of your project.\nFurthermore, the target option specify the target computer architecture (or the target operational system) of this binary file. For example, if you want this target object to run on a Windows machine that uses a x86_64 architecture, you can set this target option to x86_64-windows-gnu for example. This will make the zig compiler to compile the project to run on a x86_64 Windows machine. You can see the full list of architectures and OS’s that the zig compiler supports by running the zig targets command in the terminal.\nNow, if you are building the project to run on the current machine that you are using to run this build script, you can set this target option to the host method of the Build object, like we did in the example above. This host method identifies the current machine where you are currently running the zig compiler.\nAt last, the root_source_file option specifies the root Zig module of your project. That is the Zig module that contains the entrypoint to your application (i.e. the main() function), or, the main API of your library. This also means that, all the Zig modules that compose your project are automatically discovered from the import statements you have inside this “root source file”. The zig compiler can detect when a Zig module depends on the other through the import statements, and, as a result, it can discover the entire map of Zig modules used in your project.\nThis is handy, and it is different from what happens in other build systems. In CMake for example, you have to explicitly list the paths to all source files that you want to include in your build process. This is probably a symptom of the “lack of conditional compilation” in the C and C++ compilers. Since they lack this feature, you have to explicitly choose which source files should be sent to the C/C++ compiler, because not every C/C++ code is portable or supported in every operational system, and, therefore, would cause a compilation error in the C/C++ compiler.\nNow, one important detail about the build process is that, you have to explicitly install the target objects that you create in your build script, by using the installArtifact() method of the Build struct.\nEverytime you invoke the build process of your project, by calling the build command of the zig compiler, a new directory named zig-out is created in the root directory of your project. This new directory contains the outputs of the build process, that is, the binary files built from your source code.\nWhat the installArtifact() method do is to install (or copy) the built target objects that you defined to this zig-out directory. This means that, if you do not install the target objects you define in your build script, these target objects are essentially discarded at the end of the build process.\nFor example, you might be building a project that uses a third party library that is built together with the project. So, when you build your project, you would need first, to build the third party library, and then, you link it with the source code of your project. So, in this case, we have two binary files that are generated in the build process (the executable file of your project, and the third party library). But only one is of interest, which is the executable file of our project. We can discard the binary file of the third party library, by simply not installing it into this zig-out directory.\nThis installArtifact() method is pretty straightforward. Just remember to apply it to every target object that you want to save into the zig-out directory, like in the example below:\n\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nb.installArtifact(exe);",
     "crumbs": [
       "<span class='chapter-number'>9</span>  <span class='chapter-title'>Build System</span>"
     ]

From 70773ccfbbb1252378c4ade41c3debe820ad540b Mon Sep 17 00:00:00 2001
From: Tommaso Ricci <zorgatone@gmail.com>
Date: Tue, 21 Jan 2025 12:24:44 +0100
Subject: [PATCH 021/151] Fix wrong character

---
 Chapters/01-zig-weird.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index 6acd1bb5..53918135 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -122,7 +122,7 @@ tree .
 1 directory, 4 files
 ```
 
-The `ìnit` command also creates two additional files in our working directory:
+The `init` command also creates two additional files in our working directory:
 `build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.
 This script is executed when you call the `build` command from the `zig` compiler.
 In other words, this file contain Zig code that executes the necessary steps to build the entire project.

From 1dbb6570dad114e0055ad7ff24cdd1487b0637d0 Mon Sep 17 00:00:00 2001
From: Matt Wilbur <wilburm@gmail.com>
Date: Fri, 24 Jan 2025 19:23:17 -0500
Subject: [PATCH 022/151] Suggestions for small corrections

---
 Chapters/03-structs.qmd | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Chapters/03-structs.qmd b/Chapters/03-structs.qmd
index 04f035bf..15d11fe4 100644
--- a/Chapters/03-structs.qmd
+++ b/Chapters/03-structs.qmd
@@ -152,10 +152,10 @@ pub fn main() !void {
 
 One very important aspect about switch statements in Zig
 is that they must exhaust all existing possibilities.
-In other words, all possible values that could be found inside the `order`
+In other words, all possible values that could be found inside the `role`
 object must be explicitly handled in this switch statement.
 
-Since the `role` object have type `Role`, the only possible values to
+Since the `role` object has type `Role`, the only possible values to
 be found inside this object are `PM`, `SE`, `DPE`, `PO`, `DE`, `DA` and `KS`.
 There are no other possible values to be stored in this `role` object.
 Thus, the switch statements must have a combination (branch) for each one of these values.

From 4dee3b75366bee09efba4e7b14fe9eb438cd9899 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Thu, 30 Jan 2025 11:24:47 -0400
Subject: [PATCH 023/151] fix: change compiles to compile

---
 Chapters/01-zig-weird.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index 6acd1bb5..cf67996c 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -605,7 +605,7 @@ keyword `var` in Zig is similar to using the keywords `let mut` in Rust.
 
 In the code example below, we are creating a new constant object called `age`.
 This object stores a number representing the age of someone. However, this code example
-does not compiles successfully. Because on the next line of code, we are trying to change the value
+does not compile successfully. Because on the next line of code, we are trying to change the value
 of the object `age` to 25.
 
 The `zig` compiler detects that we are trying to change

From 370e4e3f6718baf3cc8094191fe5f7290c8f6cd6 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Thu, 30 Jan 2025 12:03:56 -0400
Subject: [PATCH 024/151] fix: add subject before 'is'

---
 Chapters/01-zig-weird.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index cf67996c..96111d04 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -1211,7 +1211,7 @@ But one key difference between a Zig string literal and a C string, is that Zig
 the string inside the object itself. In the case of a string literal value, this length is stored in the
 data type of the value (i.e. the `n` variable in `[n:0]u8`). While, in a string object, the length is stored
 in the `len` attribute of the slice that represents the string object. This small detail makes your code safer,
-because is much easier for the Zig compiler to check if you are trying to access an element that is
+because it is much easier for the Zig compiler to check if you are trying to access an element that is
 "out of bounds", i.e. if your trying to access memory that does not belong to you.
 
 To achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.

From 62ab366b90e2d5830e853ef76fe1b65906ac4fd2 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Thu, 30 Jan 2025 12:59:26 -0400
Subject: [PATCH 025/151] fix: change obligates to obligate

---
 Chapters/01-zig-weird.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index 96111d04..7b38c2bb 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -1548,7 +1548,7 @@ In contrast, the Zig language is not a memory safe language by default.
 There are some memory safety features that you get for free in Zig,
 especially in arrays and pointer objects. But there are other tools
 offered by the language, that are not used by default.
-In other words, the `zig` compiler does not obligates you to use such tools.
+In other words, the `zig` compiler does not obligate you to use such tools.
 
 The tools listed below are related to memory safety. That is, they help you to achieve
 memory safety in your Zig code:

From 221542dac3b5453b2c83159678f23dcb511010ae Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Thu, 30 Jan 2025 16:23:26 -0400
Subject: [PATCH 026/151] fix: remove apostrophe

---
 Chapters/03-structs.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/03-structs.qmd b/Chapters/03-structs.qmd
index 04f035bf..c90adc48 100644
--- a/Chapters/03-structs.qmd
+++ b/Chapters/03-structs.qmd
@@ -340,7 +340,7 @@ as "the end of the current scope". But this interpretation might not be entirely
 on what you consider as "the end of the current scope".
 
 I mean, what do you consider as **the end** of the current scope? Is it the closing curly bracket (`}`) of the scope?
-Is it when the last expression in the function get's executed? Is it when the function returns to the previous scope?
+Is it when the last expression in the function gets executed? Is it when the function returns to the previous scope?
 Etc. For example, it would not be correct to interpret the "exit of the current scope" as the closing
 curly bracket of the scope. Because the function might exit from an earlier position than this
 closing curly bracket (e.g. an error value was generated at a previous line inside the function;

From 45f021e6bae45fa35cc4340a33007306a5b3af03 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Thu, 30 Jan 2025 17:50:22 -0400
Subject: [PATCH 027/151] fix: change 'is' to 'are'

---
 Chapters/03-structs.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/03-structs.qmd b/Chapters/03-structs.qmd
index c90adc48..7db5b54c 100644
--- a/Chapters/03-structs.qmd
+++ b/Chapters/03-structs.qmd
@@ -967,7 +967,7 @@ the state of the objects in any point, it's unnecessary to mark them
 as variable objects.
 
 But why? Why am I talking about this here? It's because the `self` argument
-in the methods is affected depending on whether the
+in the methods are affected depending on whether the
 methods present in a struct change or don't change the state of the object itself.
 More specifically, when you have a method in a struct that changes the state
 of the object (i.e. change the value of a data member), the `self` argument

From cbca053dd834f94c9098b94d4a18a8463f386b73 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Thu, 30 Jan 2025 17:51:12 -0400
Subject: [PATCH 028/151] fix: update change to changes for consistency

---
 Chapters/03-structs.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/03-structs.qmd b/Chapters/03-structs.qmd
index 7db5b54c..d448a486 100644
--- a/Chapters/03-structs.qmd
+++ b/Chapters/03-structs.qmd
@@ -970,7 +970,7 @@ But why? Why am I talking about this here? It's because the `self` argument
 in the methods are affected depending on whether the
 methods present in a struct change or don't change the state of the object itself.
 More specifically, when you have a method in a struct that changes the state
-of the object (i.e. change the value of a data member), the `self` argument
+of the object (i.e. changes the value of a data member), the `self` argument
 in this method must be annotated in a different manner.
 
 As I described in @sec-self-arg, the `self` argument in methods of

From ea44de377dc60ee3f8de751d458a5568ff2acb91 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Thu, 30 Jan 2025 20:18:52 -0400
Subject: [PATCH 029/151] fix: change party to part

---
 Chapters/03-structs.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/03-structs.qmd b/Chapters/03-structs.qmd
index d448a486..ba8b440f 100644
--- a/Chapters/03-structs.qmd
+++ b/Chapters/03-structs.qmd
@@ -1105,7 +1105,7 @@ as input.
 
 In general, type inference in Zig is done by using the dot character (`.`).
 Everytime you see a dot character written before a struct literal, or before an enum value, or something like that,
-you know that this dot character is playing a special party in this place. More specifically, it is
+you know that this dot character is playing a special part in this place. More specifically, it is
 telling the `zig` compiler something along the lines of: "Hey! Can you infer the type of this
 value for me? Please!". In other words, this dot character is playing a similar role as the `auto` keyword in C++.
 

From 294248f8b74bb5e99bff5a0600befbd4c23b72c5 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Thu, 30 Jan 2025 22:10:14 -0300
Subject: [PATCH 030/151] Add fixes

---
 Chapters/01-zig-weird.qmd                     |  79 ++++++++-----
 Chapters/07-build-system.qmd                  |   6 +-
 Chapters/12-file-op.qmd                       |   6 +-
 ZigExamples/zig-basics/return-integer.zig     |   3 +
 .../01-zig-weird/execute-results/html.json    |   8 +-
 .../07-build-system/execute-results/html.json |   8 +-
 .../12-file-op/execute-results/html.json      |   8 +-
 _freeze/index/execute-results/html.json       |   8 +-
 docs/Chapters/01-zig-weird.html               | 104 +++++++++---------
 docs/Chapters/07-build-system.html            |   6 +-
 docs/Chapters/12-file-op.html                 |   4 +-
 docs/index.html                               |  12 +-
 docs/search.json                              |  22 ++--
 index.qmd                                     |  11 +-
 14 files changed, 160 insertions(+), 125 deletions(-)
 create mode 100644 ZigExamples/zig-basics/return-integer.zig

diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index 6acd1bb5..d7778730 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -159,13 +159,29 @@ So, everything you need to build a complex Zig project is the
 [^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.
 
 
-The second generated file (`build.zig.zon`) is the Zig package manager configuration file,
-where you can list and manage the dependencies of your project. Yes, Zig has
-a package manager (like `pip` in Python, `cargo` in Rust, or `npm` in Javascript) called Zon,
-and this `build.zig.zon` file is similar to the `package.json` file
-in Javascript projects, or, the `Pipfile` file in Python projects,
-or the `Cargo.toml` file in Rust projects.
-
+The second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe
+your project, and also, declare a set of dependencies of your project that you want to fetch from the internet.
+In other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.
+
+One possible way to include an external Zig library in your project, is to manually build
+and install the library in your system, and just link your source code
+with the library at the build step of your project.
+
+However, if this external Zig library is available on GitHub for example,
+and it has a valid `build.zig.zon` file in root folder of the project,
+which describes the project, you can easily include this library in
+your project by simply listing this external library in your `build.zig.zon` file.
+
+In other words, this `build.zig.zon` file works similarly to the `package.json`
+file in Javascript projects, or the `Pipfile` file in Python projects,
+or the `Cargo.toml` file in Rust projects. You can read more about this
+specific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and
+you can also see the expected schema for this `build.zig.zon` file
+in a documentation file inside the official repository of Zig[^zig-zon-schema].
+
+[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>
+[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>
+[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>
 
 ### The file `root.zig` {#sec-root-file}
 
@@ -239,18 +255,22 @@ A lot of the elements we saw in `root.zig` are also present in `main.zig`.
 But there are some other elements that we haven't seen yet, so let's dive in.
 
 First, look at the return type of the `main()` function in this file.
-We can see a small change. The return
-type of the function (`void`) is accompanied by an exclamation mark (`!`).
-This exclamation mark tells us that this `main()` function
-might return an error.
+We can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).
+This exclamation mark tells us that this `main()` function might return an error.
+
+Is worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),
+or an unsigned 8-bit integer (`u8`) value, or an error. In other words, you can write your `main()` function in Zig
+to return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,
+which returns an integer value that usually serves as a "status code" for the process.
 
-In this example, the `main()` function can either return `void` or return an error.
-This is an interesting feature of Zig. If you write a function and something inside of
-the body of this function might return an error then you are forced to:
+In this example, the return type annotation of `main()` indicates that this function can either
+return nothing (`void`), or return an error. This exclamation mark in the return type annotation
+is an interesting and powerful feature of Zig. In summary, if you write a function and something inside
+the body of this function might return an error, then, you are forced to:
 
 - either add the exclamation mark to the return type of the function and make it clear that
-this function might return an error
-- explicitly handle this error inside the function
+this function might return an error.
+- explicitly handle this error inside the function.
 
 In most programming languages, we normally handle (or deal with) an error through
 a *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work
@@ -262,9 +282,10 @@ In Zig, we use the `try` keyword to execute an expression that might return an e
 which, in this example, is the `stdout.print()` expression.
 
 In essence, the `try` keyword executes the expression `stdout.print()`. If this expression
-returns a valid value, then, the `try` keyword does nothing. It only passes the value forward.
-But if the expression does return an error, then, the `try` keyword just unwrap the error value,
-and return this error from the function and also prints the current stack trace to `stderr`.
+returns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.
+It is like if this `try` keyword was never there. However, if the expression does return an error, then,
+the `try` keyword will unwrap the error value, then, it returns this error from the function
+and also prints the current stack trace to `stderr`.
 
 This might sound weird to you if you come from a high-level language. Because in
 high-level languages, such as Python, if an error occurs somewhere, this error is automatically
@@ -284,17 +305,15 @@ pub fn main() !void {
 ```
 
 Another thing that you might have noticed in this code example, is that
-the `main()` function is marked with the `pub` keyword.
-It marks the `main()` function as a *public function* from this module.
-
-Every function in your Zig module is by default private to this Zig module and can only be called from within the module.
+the `main()` function is marked with the `pub` keyword. It marks the `main()`
+function as a *public function* from this module. Every function in your Zig
+module is by default private to this Zig module and can only be called from within the module.
 Unless, you explicitly mark this function as a public function with the `pub` keyword.
-This means that the `pub` keyword in Zig does essentially the opposite of what the `static` keyword
-do in C/C++.
 
-By making a function "public" you allow other Zig modules to access and call it.
-A calling Zig module imports the module with the `@import()`
-built-in. That makes all public functions from the imported module visible.
+If you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword
+do in C/C++. By making a function "public" you allow other Zig modules to access and call this function.
+A calling Zig module imports another module by using the `@import()` built-in function, which makes
+all public functions from the imported module visible to the calling Zig module.
 
 
 ### Compiling your source code {#sec-compile-code}
@@ -365,7 +384,7 @@ Hello, world!
 ### Important note for Windows users
 
 First of all, this is a Windows-specific thing, and, therefore, does not apply to other
-operational systems, such as Linux and MacOs. In summary, if you have a piece of Zig code that
+operating systems, such as Linux and macOs. In summary, if you have a piece of Zig code that
 includes some global variables whose initialization rely on runtime resources, then,
 you might have some troubles while trying to compile this Zig code on Windows.
 
@@ -1525,7 +1544,7 @@ exploited, by ensuring memory safety for example. But this is not enough
 to achieve "true safety" territory.
 
 Because even if you write your program in a "safe language", hackers can still
-exploit failures in the operational system where your program is running (e.g. maybe the
+exploit failures in the operating system where your program is running (e.g. maybe the
 system where your code is running has a "backdoor exploit" that can still
 affect your code in unexpected ways), or also, they can exploit the features
 from the architecture of your computer. A recently found exploit
diff --git a/Chapters/07-build-system.qmd b/Chapters/07-build-system.qmd
index e94ba900..6bced377 100644
--- a/Chapters/07-build-system.qmd
+++ b/Chapters/07-build-system.qmd
@@ -37,7 +37,7 @@ Hence, this chapter represents an extra resource for you to consult and rely on.
 
 Building code is one of the things that Zig is best at. One thing that is particularly
 difficult in C/C++ and even in Rust, is to cross-compile source code to multiple targets
-(e.g. multiple computer architectures and operational systems),
+(e.g. multiple computer architectures and operating systems),
 and the `zig` compiler is known for being one of the best existing pieces of software
 for this particular task.
 
@@ -179,7 +179,7 @@ by this target object. So, in this example, we are building an executable file n
 Is common to set this `name` option to the name of your project.
 
 
-Furthermore, the `target` option specify the target computer architecture (or the target operational system) of this
+Furthermore, the `target` option specify the target computer architecture (or the target operating system) of this
 binary file. For example, if you want this target object to run on a Windows machine
 that uses a `x86_64` architecture, you can set this `target` option to `x86_64-windows-gnu` for example.
 This will make the `zig` compiler to compile the project to run on a `x86_64` Windows machine.
@@ -205,7 +205,7 @@ In CMake for example, you have to explicitly list the paths to all source files
 include in your build process. This is probably a symptom of the "lack of conditional
 compilation" in the C and C++ compilers. Since they lack this feature, you have
 to explicitly choose which source files should be sent to the C/C++ compiler, because not
-every C/C++ code is portable or supported in every operational system, and, therefore,
+every C/C++ code is portable or supported in every operating system, and, therefore,
 would cause a compilation error in the C/C++ compiler.
 
 
diff --git a/Chapters/12-file-op.qmd b/Chapters/12-file-op.qmd
index 6e8236e4..0a880e28 100644
--- a/Chapters/12-file-op.qmd
+++ b/Chapters/12-file-op.qmd
@@ -62,7 +62,7 @@ Furthermore, OS's also normally create a dedicated channel for exchanging error
 are usually sent to. These are the messages that are normally displayed in red-like or orange-like colors
 into your terminal.
 
-Normally, every OS (e.g. Windows, MacOS, Linux, etc.) creates a dedicated and separate set of
+Normally, every OS (e.g. Windows, macOS, Linux, etc.) creates a dedicated and separate set of
 *standard output*, *standard error* and *standard input* channels for every single program (or process) that runs in your computer.
 This means that every program you write have a dedicated `stdin`, `stderr` and `stdout` that are separate
 from the `stdin`, `stderr` and `stdout` of other programs and processes that are currently running.
@@ -469,9 +469,9 @@ that you are referring to. This type of path is called absolute, because it poin
 That is, there is no other existing location on your computer that corresponds to this path. It is an unique identifier.
 
 In Windows, an absolute path is a path that starts with a hard disk identifier (e.g. `C:/Users/pedro`).
-On the other hand, absolute paths in Linux and MacOS, are paths that start with a forward slash character (e.g. `/usr/local/bin`).
+On the other hand, absolute paths in Linux and macOS, are paths that start with a forward slash character (e.g. `/usr/local/bin`).
 Notice that a path is composed by "segments". Each segment is connected to each other by a slash character (`\` or `/`).
-On Windows, the backward slash (`\`) is normally used to connect the path segments. While on Linux and MacOS, the forward
+On Windows, the backward slash (`\`) is normally used to connect the path segments. While on Linux and macOS, the forward
 slash (`/`) is the character used to connect path segments.
 
 A relative path is a path that start at the CWD. In other words, a relative path is
diff --git a/ZigExamples/zig-basics/return-integer.zig b/ZigExamples/zig-basics/return-integer.zig
new file mode 100644
index 00000000..9038077c
--- /dev/null
+++ b/ZigExamples/zig-basics/return-integer.zig
@@ -0,0 +1,3 @@
+pub fn main() u8 {
+    return 0;
+}
diff --git a/_freeze/Chapters/01-zig-weird/execute-results/html.json b/_freeze/Chapters/01-zig-weird/execute-results/html.json
index 9f589e01..e1ca16e1 100644
--- a/_freeze/Chapters/01-zig-weird/execute-results/html.json
+++ b/_freeze/Chapters/01-zig-weird/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "ac000692a82a7bd85e0b2c4d90fd55b3",
+  "hash": "dcb8e27545ba3d418f25136ae98cf023",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\nlanguage, it is still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. They really make it sometimes hard to debug\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscures the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that get's compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e. it is where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `ìnit` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contain Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nTherefore, Zig contains a native build system in it, and\nwe can use this build system to write small scripts in Zig,\nwhich describes the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is the Zig package manager configuration file,\nwhere you can list and manage the dependencies of your project. Yes, Zig has\na package manager (like `pip` in Python, `cargo` in Rust, or `npm` in Javascript) called Zon,\nand this `build.zig.zon` file is similar to the `package.json` file\nin Javascript projects, or, the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects.\n\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e. creating new objects)\nare made in Zig. You can create a new object in Zig by using the following syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). At @sec-assignments we talk more about objects in general.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that at @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return\ntype of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function\nmight return an error.\n\nIn this example, the `main()` function can either return `void` or return an error.\nThis is an interesting feature of Zig. If you write a function and something inside of\nthe body of this function might return an error then you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error\n- explicitly handle this error inside the function\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does nothing. It only passes the value forward.\nBut if the expression does return an error, then, the `try` keyword just unwrap the error value,\nand return this error from the function and also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword.\nIt marks the `main()` function as a *public function* from this module.\n\nEvery function in your Zig module is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\nThis means that the `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++.\n\nBy making a function \"public\" you allow other Zig modules to access and call it.\nA calling Zig module imports the module with the `@import()`\nbuilt-in. That makes all public functions from the imported module visible.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portale C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nOn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperational systems, such as Linux and MacOs. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e. the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. Thus, if you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith a \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, operations like accessing the `stdout` (or opening a file) on Windows\ndepends on resources that are available only at *runtime* (you will learn more about compile-time\nversus runtime at @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword at @sec-comptime.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation at a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues \n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described at @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig latter in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig? \nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar in our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentations.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It is a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (at YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e. identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compiles successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nIn contrast, if you use `var`, then, the object created is a variable object.\nWith `var` you can declare this object in your source code, and then,\nchange the value of this object how many times you want over future points\nin your source code.\n\nSo, using the same code example exposed above, if I change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it is an \"variable object\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIs important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code use this object while it is uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object. \n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e. if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to an special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It is discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also get's discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e. the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\n\nIs worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array. \n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it is a slice that\naccess all elements in the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" at @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth at @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially at @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned at @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e. the start and the end of this range)\nis known at compile-time, the slice object that get's created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nat @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that get's created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e. a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can \ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n```\n:::\n\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat get's created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, the `slice` object have a runtime known range, because the end index of the range\nis not known at compile time. In other words, the size of the array at `buffer` is not known\nat compile time. When we execute this program, the size of the array might be 10, or, it might be 12\ndepending on where we execute it. Therefore, we don't know at compile time if\nthe slice object have a range of size 10, or, a range of size 12.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e. a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented at @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e. `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIs worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e. the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause is much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e. if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it is a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIs important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operational system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligates you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig at @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers at @sec-root-file and especially at @sec-assignments.\n- How strings work in Zig at @sec-zig-strings.\n- How to use arrays and slices at @sec-arrays.\n- How to import functionality from other Zig modules at @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* at @sec-structs-and-oop.\n- Basic control flow syntax at @sec-zig-control-flow.\n- Enums at @sec-enum;\n- Pointers and Optionals at @sec-pointer;\n- Error handling with `try` and `catch` at @sec-error-handling;\n- Unit tests at @sec-unittests;\n- Vectors at @sec-vectors-simd;\n- Build System at @sec-build-system;\n\n\n\n\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\nlanguage, it is still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. They really make it sometimes hard to debug\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscures the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that get's compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e. it is where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `ìnit` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contain Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nTherefore, Zig contains a native build system in it, and\nwe can use this build system to write small scripts in Zig,\nwhich describes the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e. creating new objects)\nare made in Zig. You can create a new object in Zig by using the following syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). At @sec-assignments we talk more about objects in general.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that at @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIs worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value, or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt is like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portale C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nOn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOs. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e. the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. Thus, if you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith a \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, operations like accessing the `stdout` (or opening a file) on Windows\ndepends on resources that are available only at *runtime* (you will learn more about compile-time\nversus runtime at @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword at @sec-comptime.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation at a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues \n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described at @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig latter in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig? \nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar in our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentations.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It is a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (at YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e. identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compiles successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nIn contrast, if you use `var`, then, the object created is a variable object.\nWith `var` you can declare this object in your source code, and then,\nchange the value of this object how many times you want over future points\nin your source code.\n\nSo, using the same code example exposed above, if I change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it is an \"variable object\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIs important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code use this object while it is uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object. \n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e. if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to an special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It is discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also get's discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e. the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\nIs worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array. \n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it is a slice that\naccess all elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" at @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth at @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially at @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned at @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e. the start and the end of this range)\nis known at compile-time, the slice object that get's created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nat @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that get's created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e. a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can \ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n```\n:::\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat get's created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, the `slice` object have a runtime known range, because the end index of the range\nis not known at compile time. In other words, the size of the array at `buffer` is not known\nat compile time. When we execute this program, the size of the array might be 10, or, it might be 12\ndepending on where we execute it. Therefore, we don't know at compile time if\nthe slice object have a range of size 10, or, a range of size 12.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e. a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented at @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e. `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIs worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e. the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause is much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e. if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it is a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIs important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligates you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig at @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers at @sec-root-file and especially at @sec-assignments.\n- How strings work in Zig at @sec-zig-strings.\n- How to use arrays and slices at @sec-arrays.\n- How to import functionality from other Zig modules at @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* at @sec-structs-and-oop.\n- Basic control flow syntax at @sec-zig-control-flow.\n- Enums at @sec-enum;\n- Pointers and Optionals at @sec-pointer;\n- Error handling with `try` and `catch` at @sec-error-handling;\n- Unit tests at @sec-unittests;\n- Vectors at @sec-vectors-simd;\n- Build System at @sec-build-system;\n\n\n\n\n",
+    "supporting": [
+      "01-zig-weird_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/07-build-system/execute-results/html.json b/_freeze/Chapters/07-build-system/execute-results/html.json
index 19ef21c9..5205e5b4 100644
--- a/_freeze/Chapters/07-build-system/execute-results/html.json
+++ b/_freeze/Chapters/07-build-system/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "e85c074257bd60ecabd542a9aec94925",
+  "hash": "0bac007aec8b6fa9d1efa7b682df4b7b",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n\n# Build System {#sec-build-system}\n\n\nIn this chapter, we are going to talk about the build system, and how an entire project\nis built in Zig.\nOne key advantage of Zig is that it includes a build system embedded in the language itself.\nThis is great, because then you do not have to depend on an external system, separated\nfrom the compiler, to build your code.\n\n\nYou can find a good description of Zig's build system\non the [article entitled \"Build System\"](https://ziglang.org/learn/build-system/#user-provided-options)[^zig-art1]\nfrom the official Zig's website.\nWe also have the excellent [series of posts written by Felix](https://zig.news/xq/zig-build-explained-part-1-59lf)[^felix].\nHence, this chapter represents an extra resource for you to consult and rely on.\n\n[^felix]: <https://zig.news/xq/zig-build-explained-part-1-59lf>\n[^zig-art1]: <https://ziglang.org/learn/build-system/#user-provided-options>\n\nBuilding code is one of the things that Zig is best at. One thing that is particularly\ndifficult in C/C++ and even in Rust, is to cross-compile source code to multiple targets\n(e.g. multiple computer architectures and operational systems),\nand the `zig` compiler is known for being one of the best existing pieces of software\nfor this particular task.\n\n\n\n\n## How source code is built?\n\nWe already have talked about the challenges of building source code in low-level languages\nat @sec-project-files. As we described at that section, programmers invented Build Systems\nto surpass these challenges on the process of building source code in low-level languages.\n\nLow-level languages uses a compiler to compile (or to build) your source code into binary instructions.\nIn C and C++, we normally use compilers like `gcc`, `g++` or `clang` to compile\nour C and C++ source code into these instructions.\nEvery language have its own compiler, and this is no different in Zig.\n\nIn Zig, we have the `zig` compiler to compile our Zig source code into\nbinary instructions that can be executed by our computer.\nIn Zig, the compilation (or the build) process involves\nthe following components:\n\n- The Zig modules that contains your source code;\n- Library files (either a dynamic library or a static library);\n- Compiler flags that tailors the build process to your needs.\n\nThese are the things that you need to connect together in order to build your\nsource code in Zig. In C and C++, you would have an extra component, which are the header files of\nthe libraries that you are using. But header files do not exist in Zig, so, you only need\nto care about them if you are linking your Zig source code with a C library.\nIf that is not your case, you can forget about it.\n\nYour build process is usually organized in a build script. In Zig, we normally\nwrite this build script into a Zig module in the root directory of our project,\nnamed as `build.zig`. You write this build script, then, when you run it, your project\nget's built into binary files that you can use and distribute to your users.\n\nThis build script is normally organized around *target objects*. A target is simply\nsomething to be built, or, in other words, it's something that you want the `zig` compiler\nto build for you. This concept of \"targets\" is present in most Build Systems,\nespecially in CMake[^cmake].\n\n[^cmake]: <https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html>\n\nThere are four types of target objects that you can build in Zig, which are:\n\n- An executable (e.g. a `.exe` file on Windows).\n- A shared library (e.g. a `.so` file in Linux or a `.dll` file on Windows).\n- A static library (e.g. a `.a` file in Linux or a `.lib` file on Windows).\n- An executable file that executes only unit tests (or, a \"unit tests executable\").\n\nWe are going to talk more about these target objects at @sec-targets.\n\n\n\n## The `build()` function {#sec-build-fun}\n\nA build script in Zig always contains a public (and top-level) `build()` function declared.\nIt is like the `main()` function on the main Zig module of your project, that we discussed at @sec-main-file.\nBut instead of creating the entrypoint to your code, this `build()` function is the entrypoint to the build process.\n\nThis `build()` function should accept a pointer to a `Build` object as input, and it should use this \"build object\" to perform\nthe necessary steps to build your project. The return type of this function is always `void`,\nand this `Build` struct comes directly from the Zig Standard Library (`std.Build`). So, you can \naccess this struct by just importing the Zig Standard Library into your `build.zig` module.\n\nJust as a very simple example, here you can see the source code necessary to build\nan executable file from the `hello.zig` Zig module.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"hello.zig\"),\n        .target = b.host,\n    });\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\n\nYou can define and use other functions and objects in this build script. You can also import\nother Zig modules as you would normally do in any other module of your project.\nThe only real requirement for this build script, is to have a public and top-level\n`build()` function defined, that accepts a pointer to a `Build` struct as input.\n\n\n## Target objects {#sec-targets}\n\nAs we described over the previous sections, a build script is composed around target objects.\nEach target object is normally a binary file (or an output) that you want to get from the build process. You can list\nmultiple target objects in your build script, so that the build process generates multiple\nbinary files for you at once.\n\nFor example, maybe you are a developer working in a cross-platform application,\nand, because this application is cross-platform, you probably need to release\nbinary files of your software for each OS supported by your application to your end users.\nThus, you can define a different target object in your build script\nfor each OS (Windows, Linux, etc.) where you want to publish your software.\nThis will make the `zig` compiler to build your project to multiple target OS's at once.\nThe Zig Build System official documentation have a [great code example that demonstrates this strategy](https://ziglang.org/learn/build-system/#handy-examples)[^zig-ex].\n\n[^zig-ex]: <https://ziglang.org/learn/build-system/#handy-examples>\n\n\nA target object is created by the following methods of the `Build` struct that we introduced\nat @sec-build-fun:\n\n- `addExecutable()` creates an executable file;\n- `addSharedLibrary()` creates a shared library file;\n- `addStaticLibrary()` creates a static library file;\n- `addTest()` creates an executable file that executes unit tests.\n\n\nThese functions are methods from the `Build` struct that you receive\nas input of the `build()` function. All of them, create as output\na `Compile` object, which represents a target object to be compiled\nby the `zig` compiler. All of these functions accept a similar struct literal as input.\nThis struct literal defines three essential specs about this target object that you are building:\n`name`, `target` and `root_source_file`.\n\nWe have already seen these three options being used on the previous example,\nwhere we used the `addExecutable()` method to create an executable target object.\nThis example is reproduced below. Notice the use of the `path()` method\nfrom the `Build` struct, to define a path in the `root_source_file` option.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n```\n:::\n\n\n\n\n\nThe `name` option specify the name that you want to give to the binary file defined\nby this target object. So, in this example, we are building an executable file named `hello`.\nIs common to set this `name` option to the name of your project.\n\n\nFurthermore, the `target` option specify the target computer architecture (or the target operational system) of this\nbinary file. For example, if you want this target object to run on a Windows machine\nthat uses a `x86_64` architecture, you can set this `target` option to `x86_64-windows-gnu` for example.\nThis will make the `zig` compiler to compile the project to run on a `x86_64` Windows machine.\nYou can see the full list of architectures and OS's that the `zig` compiler supports by running\nthe `zig targets` command in the terminal.\n\nNow, if you are building the project to run on the current machine\nthat you are using to run this build script, you can set this `target`\noption to the `host` method of the `Build` object, like we did in the example above.\nThis `host` method identifies the current machine where you are\ncurrently running the `zig` compiler.\n\n\nAt last, the `root_source_file` option specifies the root Zig module of your project.\nThat is the Zig module that contains the entrypoint to your application (i.e. the `main()` function), or, the main API of your library.\nThis also means that, all the Zig modules that compose your project are automatically discovered\nfrom the import statements you have inside this \"root source file\".\nThe `zig` compiler can detect when a Zig module depends on the other through the import statements,\nand, as a result, it can discover the entire map of Zig modules used in your project.\n\nThis is handy, and it is different from what happens in other build systems.\nIn CMake for example, you have to explicitly list the paths to all source files that you want to\ninclude in your build process. This is probably a symptom of the \"lack of conditional\ncompilation\" in the C and C++ compilers. Since they lack this feature, you have\nto explicitly choose which source files should be sent to the C/C++ compiler, because not\nevery C/C++ code is portable or supported in every operational system, and, therefore,\nwould cause a compilation error in the C/C++ compiler.\n\n\nNow, one important detail about the build process is that, you have to **explicitly\ninstall the target objects that you create in your build script**, by using the\n`installArtifact()` method of the `Build` struct.\n\nEverytime you invoke the build process of your project, by calling the `build` command\nof the `zig` compiler, a new directory named `zig-out` is created in the root\ndirectory of your project. This new directory contains the outputs of the build process,\nthat is, the binary files built from your source code.\n\nWhat the `installArtifact()` method do is to install (or copy) the built target objects\nthat you defined to this `zig-out` directory.\nThis means that, if you do not\ninstall the target objects you define in your build script, these target objects are\nessentially discarded at the end of the build process.\n\nFor example, you might be building a project that uses a third party library that is built\ntogether with the project. So, when you build your project, you would need first, to\nbuild the third party library, and then, you link it with the source code of your project.\nSo, in this case, we have two binary files that are generated in the build process (the executable file of your project, and the third party library).\nBut only one is of interest, which is the executable file of our project.\nWe can discard the binary file of the third party library, by simply not installing it\ninto this `zig-out` directory.\n\nThis `installArtifact()` method is pretty straightforward. Just remember to apply it to every\ntarget object that you want to save into the `zig-out` directory, like in the example below:\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n\n## Setting the build mode\n\nWe have talked about the three essential options that are set when you create a new target object.\nBut there is also a fourth option that you can use to set the build mode of this target object,\nwhich is the `optimize` option.\nThis option is called this way, because the build modes in Zig are treated more of\nan \"optimization vs safety\" problem. So optimization plays an important role here.\nDon't worry, I'm going back to this question very soon.\n\nIn Zig, we have four build modes (which are listed below). Each one of these build modes offer\ndifferent advantages and characteristics. As we described at @sec-compile-debug-mode, the `zig` compiler\nuses the `Debug` build mode by default, when you don't explicitly choose a build mode.\n\n- `Debug`, mode that produces and includes debugging information in the output of the build process (i.e. the binary file defined by the target object);\n- `ReleaseSmall`, mode that tries to produce a binary file that is small in size;\n- `ReleaseFast`, mode that tries to optimize your code, in order to produce a binary file that is as fast as possible;\n- `ReleaseSafe`, mode that tries to make your code as safe as possible, by including safeguards when possible.\n\nSo, when you build your project, you can set the build mode of your target object to `ReleaseFast` for example, which will tell\nthe `zig` compiler to apply important optimizations in your code. This creates a binary file\nthat simply runs faster on most contexts, because it contains a more optimized version of your code.\nHowever, as a result, we often lose some safety features in our code.\nBecause some safety checks are removed from the final binary file,\nwhich makes your code run faster, but in a less safe manner.\n\nThis choice depends on your current priorities. If you are building a cryptography or banking system, you might\nprefer to prioritize safety in your code, so, you would choose the `ReleaseSafe` build mode, which is a little\nslower to run, but much more secure, because it includes all possible runtime safety checks in the binary file\nbuilt in the build process. In the other hand, if you are writing a game for example, you might prefer to prioritize performance\nover safety, by using the `ReleaseFast` build mode, so that your users can experience faster frame rates in your game.\n\nIn the example below, we are creating the same target object that we have used on previous examples.\nBut this time, we are specifying the build mode of this target object to the `ReleaseSafe` mode.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .optimize = .ReleaseSafe\n});\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n\n## Setting the version of your build\n\nEverytime you build a target object in your build script, you can assign a version\nnumber to this specific build, following a semantic versioning framework.\nYou can find more about semantic versioning by visiting the [Semantic Versioning website](https://semver.org/)[^semver].\nAnyway, in Zig, you can specify the version of your build, by providing a `SemanticVersion` struct to\nthe `version` option, like in the example below:\n\n\n[^semver]: <https://semver.org/>\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .version = .{\n        .major = 2, .minor = 9, .patch = 7\n    }\n});\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n\n## Detecting the OS in your build script {#sec-detect-os}\n\nIs very common in Build Systems to use different options, or, to include different modules, or,\nto link against different libraries depending on the Operational System (OS)\nthat you are targeting in the build process.\n\nIn Zig, you can detect the target OS of the build process, by looking\nat the `os.tag` inside the `builtin` module from the Zig library.\nIn the example below, we are using an if statement to run some\narbitrary code when the target of the build process is a\nWindows system.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nif (builtin.target.os.tag == .windows) {\n    // Code that runs only when the target of\n    // the compilation process is Windows.\n}\n```\n:::\n\n\n\n\n\n\n## Adding a run step to your build process\n\nOne thing that is neat in Rust is that you can compile and run your\nsource code with one single command (`cargo run`) from the Rust compiler.\nWe saw at @sec-compile-run-code how can we perform a similar job in Zig, by\nbuilding and running our Zig source code through the `run` command from the `zig` compiler.\n\nBut how can we, at the same time, build and run the binary file specified by a target object in our\nbuild script?\nThe answer is by including a \"run artifact\" in our build script.\nA run artifact is created through the `addRunArtifact()` method from the `Build` struct.\nWe simply provide as input to this function the target object that describes the binary file that we\nwant to execute. As a result, this function creates a run artifact that is capable of executing\nthis binary file.\n\nIn the example below, we are defining an executable binary file named `hello`,\nand we use this `addRunArtifact()` method to create a run artifact that will execute\nthis `hello` executable file.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"src/hello.zig\"),\n    .target = b.host\n});\nb.installArtifact(exe);\nconst run_arti = b.addRunArtifact(exe);\n```\n:::\n\n\n\n\n\nNow that we have created this run artifact, we need to include it in\nthe build process. We do that by declaring a new step in our build\nscript to call this artifact, through the `step()` method of the `Build`\nstruct.\n\nWe can give any name we want to this step, but, for our\ncontext here, I'm going to name this step as \"run\".\nAlso, I give it a brief description to this step (\"Run the project\").\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst run_step = b.step(\n    \"run\", \"Run the project\"\n);\n```\n:::\n\n\n\n\n\n\nNow that we have declared this \"run step\" we need to tell Zig that\nthis \"run step\" depends on the run artifact.\nIn other words, a run artifact always depends on a \"step\" to effectively be executed.\nBy creating this dependency\nwe finally stablish the necessary commands to build and run the executable file\nfrom the build script.\n\nWe can establish a dependency between the run step and the run artifact\nby using the `dependsOn()` method from the run step. So, we first\ncreate the run step, and then, we link it with the run artifact, by\nusing this `dependsOn()` method from the run step.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nrun_step.dependOn(&run_arti.step);\n```\n:::\n\n\n\n\n\nThe entire source code of this specific build script that\nwe wrote, piece by piece, in this section, is\navailable in the `build_and_run.zig` module. You can\nsee this module by\n[visiting the official repository of this book](https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig)\n[^module-src].\n\n\n[^module-src]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig>\n\nWhen you declare a new step in your build script, this step\nbecomes available through the `build` command in the `zig` compiler.\nYou can actually see this step by running `zig build --help` in the terminal, like\nin the example below, where we can see that this new \"run\"\nstep that we declared in the build script appeared in the output.\n\n```bash\nzig build --help\n```\n\n```\nSteps:\n  ...\n  run   Run the project\n  ...\n```\n\nNow, everything that we need to is to\ncall this \"run\" step that we created in our build script. We\ncall it by using the name that we gave to this step\nafter the `build` command from the `zig` compiler.\nThis will cause the compiler to build our executable file\nand execute it at the same time.\n\n```bash\nzig build run\n```\n\n## Build unit tests in your project\n\nWe have talked at length about writing unit tests in Zig at @sec-unittests,\nand we also have talked about how to execute these unit tests through\nthe `test` command of the `zig` compiler. However,\nas we did with the `run` command on the previous section, we also might want to\ninclude some commands in our build script to also build and execute the unit tests in our project.\n\nSo, once again, we are going to discuss how a specific built-in command from the `zig` compiler,\n(in this case, the `test` command) can be used in a build script in Zig.\nHere is where a \"test target object\" comes into play.\nAs was described at @sec-targets, we can create a test target object by using the `addTest()` method of\nthe `Build` struct. The first thing that we need to do is to\ndeclare a test target object in our build script.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst test_exe = b.addTest(.{\n    .name = \"unit_tests\",\n    .root_source_file = b.path(\"src/main.zig\"),\n    .target = b.host,\n});\nb.installArtifact(test_exe);\n```\n:::\n\n\n\n\n\n\nA test target object essentially selects all `test` blocks in all Zig modules\nacross your project, and builds only the source code present inside\nthese `test` blocks in your project. As a result, this target object\ncreates an executable file that contains only the source code present\nin all of these `test` blocks (i.e. the unit tests) in your project.\n\nPerfect! Now that we have declared this test target object, an executable file\nnamed `unit_tests` is built by the `zig` compiler when we trigger the build\nscript with the `build` command. After the build\nprocess is finished, we can simply execute this `unit_tests` executable\nin the terminal.\n\nHowever, if you remember the previous section, we already learned\nhow can we create a run step in our build script, to execute an executable file\nbuilt by the build script.\n\nSo, we could simply add a run step in our build script to run these unit tests\nfrom a single command in the `zig` compiler, to make our lifes easier.\nIn the example below, we demonstrate the commands to\nregister a new build step called \"tests\" in our build script\nto run these unit tests.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst run_arti = b.addRunArtifact(test_exe);\nconst run_step = b.step(\"tests\", \"Run unit tests\");\nrun_step.dependOn(&run_arti.step);\n```\n:::\n\n\n\n\n\nNow that we registered this new build step, we can trigger it by calling the command below\nin the terminal. You can also checkout the complete source\ncode for this specific build script at the `build_tests.zig` module at the\n[official repository of this book](https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig)\n[^module-src2].\n\n\n[^module-src2]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig>\n\n\n```bash\nzig build tests\n```\n\n\n## Tailoring your build process with user-provided options\n\nSometimes, you want to make a build script that is customizable by the user\nof your project. You can do that by creating user-provided options in\nyour build script. We create an user-provided option by using the\n`option()` method from the `Build` struct.\n\nWith this method, we create a \"build option\" which can be passed\nto the `build.zig` script at the command line. The user have the power of setting\nthis option at the `build` command from the\n`zig` compiler. In other words, each build option that we create\nbecomes a new command line argument that is accessible through the `build` command\nof the compiler.\n\nThese \"user-provided options\" are set by using the prefix `-D` in the command line.\nFor example, if we declare an option named `use_zlib`, that receives a boolean value which\nindicates if we should link our source code to `zlib` or not, we can set the value\nof this option in the command line with `-Duse_zlib`. The code example below\ndemonstrates this idea:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const use_zlib = b.option(\n        bool,\n        \"use_zlib\",\n        \"Should link to zlib?\"\n    ) orelse false;\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"example.zig\"),\n        .target = b.host,\n    });\n    if (use_zlib) {\n        exe.linkSystemLibrary(\"zlib\");\n    }\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\n\n```bash\nzig build -Duse_zlib=false\n```\n\n\n## Linking to external libraries\n\n\nOne essential part of every build process is the linking stage.\nThis stage is responsible for combining the multiple object files\nthat represent your code, into a single executable file. It also links\nthis executable file to external libraries, if you use any in your code.\n\nIn Zig, we have two notions of a \"library\", which are: 1) a system's library;\n2) a local library. A system's library is just a library that already is installed\nin your system. While a local library is a library that belongs to the current\nproject. Is a library that is present in your project directory, and\nthat you are building together with your project source code.\n\nThe basic difference between the two, is that a system's library is already\nbuilt and installed in your system, supposedly, and all you need to do\nis to link your source code to this library to start using it.\nWe do that by using the `linkSystemLibrary()` method from a\n`Compile` object. This method accepts the name of the library\nin a string as input. Remember from @sec-targets that a `Compile` object\nis a target object that you declare in your build script.\n\nWhen you link a particular target object with a system's library,\nthe `zig` compiler will use `pkg-config` to find where\nare the binary files and also the header files of this library\nin your system.\nWhen it finds these files, the linker present in the `zig` compiler\nwill link your object files with the files of this library to\nproduce a single binary file for you.\n\nIn the example below, we are creating an executable file named `image_filter`,\nand, we are linking this executable file to the C Standard Library with the\nmethod `linkLibC()`, but we also are linking this executable file to the\nC library `libpng` that is currently installed in my system.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"image_filter\",\n        .root_source_file = b.path(\"src/main.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n    exe.linkLibC();\n    exe.linkSystemLibrary(\"png\");\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\n\nIf you are linking with a C library in your project, is generally a good idea\nto also link your code with the C Standard Library. Because is very likely\nthat this C library uses some functionality of the C Standard Library at some point.\nThe same goes to C++ libraries. So, if you are linking with\nC++ libraries, is a good idea to link your project with the C++\nStandard Library by using the `linkLibCpp()` method.\n\nOn the order side, when you want to link with a local library,\nyou should use the `linkLibrary()` method of a `Compile` object.\nThis method expects to receive another `Compile` object as input.\nThat is, another target object defined in your build script,\nusing either the `addStaticLibrary()` or `addSharedLibrary()` methods\nwhich defines a library to be built.\n\nAs we discussed earlier, a local library is a library\nthat is local to your project, and that is being built together\nwith your project. So, you need to create a target object in your build script\nto build this local library. Then, you link the target objects of interest in your project,\nwith this target object that identifies this local library.\n\nTake a look at this example extracted from the build script of the [`libxev` library](https://github.com/mitchellh/libxev/tree/main)[^libxev2].\nYou can see in this snippet that\nwe are declaring a shared library file, from the `c_api.zig`\nmodule. Then, later in the build script, we declare an\nexecutable file named `\"dynamic-binding-test\"`, which\nlinks to this shared library that we defined earlier\nin the script.\n\n[^libxev2]: <https://github.com/mitchellh/libxev/tree/main>\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst optimize = b.standardOptimizeOption(.{});\nconst target = b.standardTargetOptions(.{});\n\nconst dynamic_lib = b.addSharedLibrary(.{\n    .name = dynamic_lib_name,\n    .root_source_file = b.path(\"src/c_api.zig\"),\n    .target = target,\n    .optimize = optimize,\n});\nb.installArtifact(dynamic_lib);\n// ... more lines in the script\nconst dynamic_binding_test = b.addExecutable(.{\n    .name = \"dynamic-binding-test\",\n    .target = target,\n    .optimize = optimize,\n});\ndynamic_binding_test.linkLibrary(dynamic_lib);\n```\n:::\n\n\n\n\n\n\n\n## Building C code {#sec-building-c-code}\n\nThe `zig` compiler comes with a C compiler embedded in it. In other words,\nyou can use the `zig` compiler to build C projects. This C compiler is available\nthrough the `cc` command of the `zig` compiler.\n\nAs an example, let's use the famous [FreeType library](https://freetype.org/)[^freetype].\nFreeType is one of the most widely used pieces of software in the world.\nIt is a C library designed to produce high-quality fonts. But it is also\nheavily used in the industry to natively render text and fonts\nin the screen of your computer.\n\nIn this section, we are going to write a build script, piece by piece, that is capable\nof building the FreeType project from source.\nYou can find the source code of this build script on the\n[`freetype-zig` repository](https://github.com/pedropark99/freetype-zig/tree/main)[^freetype-zig]\navailable at GitHub.\n\n[^freetype]: <https://freetype.org/>\n[^freetype-zig]: <https://github.com/pedropark99/freetype-zig/tree/main>\n\nAfter you download the source code of FreeType from the official website[^freetype],\nyou can start writing the `build.zig` module. We begin by defining the target object\nthat defines the binary file that we want to compile.\n\nAs an example, I will build the project as a static library file using the `addStaticLibrary()` method\nto create the target object.\nAlso, since FreeType is a C library, I will also link the library\nagainst `libc` through the `linkLibC()` method, to guarantee that any use\nof the C Standard Library is covered in the compilation process.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst target = b.standardTargetOptions(.{});\nconst opti = b.standardOptimizeOption(.{});\nconst lib = b.addStaticLibrary(.{\n    .name = \"freetype\",\n    .optimize = opti,\n    .target = target,\n});\nlib.linkLibC();\n```\n:::\n\n\n\n\n\n### Creating C compiler flags\n\nCompiler flags are also known as \"compiler options\" by many programmers,\nor also, as \"command options\" in the GCC official documentation.\nIt's fair to also call them as the \"command-line arguments\" of the C compiler.\nIn general, we use compiler flags to turn on (or turn off) some features from the compiler,\nor to tweak the compilation process to fit the needs of our project.\n\nIn build scripts written in Zig, we normally list the C compiler flags to be used in the compilation process\nin a simple array, like in the example below.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c_flags = [_][]const u8{\n    \"-Wall\",\n    \"-Wextra\",\n    \"-Werror\",\n};\n```\n:::\n\n\n\n\n\nIn theory, there is nothing stopping you from using this array to add \"include paths\" (with the `-I` flag)\nor \"library paths\" (with the `-L` flag) to the compilation process. But there are formal ways in Zig to\nadd these types of paths in the compilation process. Both are discussed at @sec-include-paths\nand @sec-library-paths.\n\nAnyway, in Zig, we add C flags to the build process together with the C files that we want to compile, by using the\n`addCSourceFile()` and `addCSourceFiles()` methods. In the example above, we have just declared\nthe C flags that we want to use. But we haven't added them to the build process yet.\nTo do that, we also need to list the C files to be compiled.\n\n### Listing your C files\n\nThe C files that contains \"cross-platform\" source code are listed in the `c_source_files`\nobject below. These are the C files that are included by default in every platform\nsupported by the FreeType library. Now, since the amount of C files in the FreeType library is big,\nI have omitted the rest of the files in the code example below, for brevity purposes.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c_source_files = [_][]const u8{\n    \"src/autofit/autofit.c\",\n    \"src/base/ftbase.c\",\n    // ... and many other C files.\n};\n```\n:::\n\n\n\n\n\nNow, in addition to \"cross-platform\" source code, we also have some C files in the FreeType project\nthat are platform-specific, meaning that, they contain source code that can only be compiled in specific platforms,\nand, as a result, they are only included in the build process on these specific target platforms.\nThe objects that list these C files are exposed in the code example below.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst windows_c_source_files = [_][]const u8{\n    \"builds/windows/ftdebug.c\",\n    \"builds/windows/ftsystem.c\"\n};\nconst linux_c_source_files = [_][]const u8{\n    \"src/base/ftsystem.c\",\n    \"src/base/ftdebug.c\"\n};\n```\n:::\n\n\n\n\n\nNow that we declared both the files that we want to include and the C compiler flags to be used,\nwe can add them to the target object that describes the FreeType library, by using the\n`addCSourceFile()` and `addCSourceFiles()` methods.\n\nBoth of these functions are methods from a `Compile` object (i.e. a target object).\nThe `addCSourceFile()` method is capable of adding a single C file to the target object,\nwhile the `addCSourceFiles()` method is used to add multiple C files in a single command.\nYou might prefer to use `addCSourceFile()` when you need to use different compiler flags\non specific C files in your project. But, if you can use the same compiler flags\nacross all C files, then, you will probably find `addCSourceFiles()` a better choice.\n\nNotice that we are using the `addCSourceFiles()` method in the example below,\nto add both the C files and the C compiler flags. Also notice that we\nare using the `os.tag` that we learned about at @sec-detect-os, to add the platform-specific\nC files.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nlib.addCSourceFiles(\n    &c_source_files, &c_flags\n);\n\nswitch (builtin.target.os.tag) {\n    .windows => {\n        lib.addCSourceFiles(\n            &windows_c_source_files,\n            &c_flags\n        );\n    },\n    .linux => {\n        lib.addCSourceFiles(\n            &linux_c_source_files,\n            &c_flags\n        );\n    },\n    else => {},\n}\n```\n:::\n\n\n\n\n\n\n### Defining C Macros\n\nC Macros are an essential part of the C programming language,\nand they are commonly defined through the `-D` flag from a C compiler.\nIn Zig, you can define a C Macro to be used in your build process\nby using the `defineCMacro()` method from the target object that\ndefines the binary file that you are building.\n\nIn the example below, we are using the `lib` object that we have defined\non the previous sections to define some C Macros used by the FreeType project\nin the compilation process. These C Macros specify if FreeType\nshould (or should not) include functionalities from different\nexternal libraries.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nlib.defineCMacro(\"FT_DISABLE_ZLIB\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_PNG\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_HARFBUZZ\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BZIP2\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BROTLI\", \"TRUE\");\nlib.defineCMacro(\"FT2_BUILD_LIBRARY\", \"TRUE\");\n```\n:::\n\n\n\n\n\n\n### Adding library paths {#sec-library-paths}\n\nLibrary paths are paths in your computer where the C compiler will look (or search) for\nlibrary files to link against your source code. In other words, when you use a library in your\nC source code, and you ask the C compiler to link your source code against this library,\nthe C compiler will search for the binary files of this library across the paths listed\nin this \"library paths\" set.\n\nThese paths are platform specific, and, by default, the C compiler starts by looking at a\npre-defined set of places in your computer. But you can add more paths (or more places)\nto this list. For example, you may have a library installed in a non-conventional place of your\ncomputer, and you can make the C compiler \"see\" this \"non-conventional place\" by adding this path\nto this list of pre-defined paths.\n\nIn Zig, you can add more paths to this set by using the `addLibraryPath()` method from your target object.\nFirst, you defined a `LazyPath` object, containing the path you want to add, then,\nyou provide this object as input to the `addLibraryPath()` method, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst lib_path: std.Build.LazyPath = .{\n    .cwd_relative = \"/usr/local/lib/\"\n};\nlib.addLibraryPath(lib_path);\n```\n:::\n\n\n\n\n\n\n\n\n### Adding include paths {#sec-include-paths}\n\nThe preprocessor search path is a popular concept from the\nC community, but it is also known by many C programmers as \"include paths\", because\nthe paths in this \"search path\" relate to the `#include` statements found in the C files.\n\nInclude paths are similar to library paths. They are a set of pre-defined places in your computer where\nthe C compiler will look for files during the compilation process. But instead of looking for\nlibrary files, the include paths are places where the compiler looks for header files included\nin your C source code.\nThis is why many C programmers prefer to call these paths as the \"preprocessor search path\".\nBecause header files are processed during the preprocessor stage of the compilation\nprocess.\n\nSo, every header file that you include in your C source code, through a `#include` statements needs to\nbe found somewhere, and the C compiler will search for this header file across the paths listed in this \"include paths\" set.\nInclude paths are added to the compilation process through the `-I` flag.\n\nIn Zig, you can add new paths to this pre-defined set of paths, by using the `addIncludePath()` method\nfrom your target object. This method also accepts a `LazyPath` object as input.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst inc_path: std.Build.LazyPath = .{\n    .path = \"./include\"\n};\nlib.addIncludePath(inc_path);\n```\n:::\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Build System {#sec-build-system}\n\n\nIn this chapter, we are going to talk about the build system, and how an entire project\nis built in Zig.\nOne key advantage of Zig is that it includes a build system embedded in the language itself.\nThis is great, because then you do not have to depend on an external system, separated\nfrom the compiler, to build your code.\n\n\nYou can find a good description of Zig's build system\non the [article entitled \"Build System\"](https://ziglang.org/learn/build-system/#user-provided-options)[^zig-art1]\nfrom the official Zig's website.\nWe also have the excellent [series of posts written by Felix](https://zig.news/xq/zig-build-explained-part-1-59lf)[^felix].\nHence, this chapter represents an extra resource for you to consult and rely on.\n\n[^felix]: <https://zig.news/xq/zig-build-explained-part-1-59lf>\n[^zig-art1]: <https://ziglang.org/learn/build-system/#user-provided-options>\n\nBuilding code is one of the things that Zig is best at. One thing that is particularly\ndifficult in C/C++ and even in Rust, is to cross-compile source code to multiple targets\n(e.g. multiple computer architectures and operating systems),\nand the `zig` compiler is known for being one of the best existing pieces of software\nfor this particular task.\n\n\n\n\n## How source code is built?\n\nWe already have talked about the challenges of building source code in low-level languages\nat @sec-project-files. As we described at that section, programmers invented Build Systems\nto surpass these challenges on the process of building source code in low-level languages.\n\nLow-level languages uses a compiler to compile (or to build) your source code into binary instructions.\nIn C and C++, we normally use compilers like `gcc`, `g++` or `clang` to compile\nour C and C++ source code into these instructions.\nEvery language have its own compiler, and this is no different in Zig.\n\nIn Zig, we have the `zig` compiler to compile our Zig source code into\nbinary instructions that can be executed by our computer.\nIn Zig, the compilation (or the build) process involves\nthe following components:\n\n- The Zig modules that contains your source code;\n- Library files (either a dynamic library or a static library);\n- Compiler flags that tailors the build process to your needs.\n\nThese are the things that you need to connect together in order to build your\nsource code in Zig. In C and C++, you would have an extra component, which are the header files of\nthe libraries that you are using. But header files do not exist in Zig, so, you only need\nto care about them if you are linking your Zig source code with a C library.\nIf that is not your case, you can forget about it.\n\nYour build process is usually organized in a build script. In Zig, we normally\nwrite this build script into a Zig module in the root directory of our project,\nnamed as `build.zig`. You write this build script, then, when you run it, your project\nget's built into binary files that you can use and distribute to your users.\n\nThis build script is normally organized around *target objects*. A target is simply\nsomething to be built, or, in other words, it's something that you want the `zig` compiler\nto build for you. This concept of \"targets\" is present in most Build Systems,\nespecially in CMake[^cmake].\n\n[^cmake]: <https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html>\n\nThere are four types of target objects that you can build in Zig, which are:\n\n- An executable (e.g. a `.exe` file on Windows).\n- A shared library (e.g. a `.so` file in Linux or a `.dll` file on Windows).\n- A static library (e.g. a `.a` file in Linux or a `.lib` file on Windows).\n- An executable file that executes only unit tests (or, a \"unit tests executable\").\n\nWe are going to talk more about these target objects at @sec-targets.\n\n\n\n## The `build()` function {#sec-build-fun}\n\nA build script in Zig always contains a public (and top-level) `build()` function declared.\nIt is like the `main()` function on the main Zig module of your project, that we discussed at @sec-main-file.\nBut instead of creating the entrypoint to your code, this `build()` function is the entrypoint to the build process.\n\nThis `build()` function should accept a pointer to a `Build` object as input, and it should use this \"build object\" to perform\nthe necessary steps to build your project. The return type of this function is always `void`,\nand this `Build` struct comes directly from the Zig Standard Library (`std.Build`). So, you can \naccess this struct by just importing the Zig Standard Library into your `build.zig` module.\n\nJust as a very simple example, here you can see the source code necessary to build\nan executable file from the `hello.zig` Zig module.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"hello.zig\"),\n        .target = b.host,\n    });\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\nYou can define and use other functions and objects in this build script. You can also import\nother Zig modules as you would normally do in any other module of your project.\nThe only real requirement for this build script, is to have a public and top-level\n`build()` function defined, that accepts a pointer to a `Build` struct as input.\n\n\n## Target objects {#sec-targets}\n\nAs we described over the previous sections, a build script is composed around target objects.\nEach target object is normally a binary file (or an output) that you want to get from the build process. You can list\nmultiple target objects in your build script, so that the build process generates multiple\nbinary files for you at once.\n\nFor example, maybe you are a developer working in a cross-platform application,\nand, because this application is cross-platform, you probably need to release\nbinary files of your software for each OS supported by your application to your end users.\nThus, you can define a different target object in your build script\nfor each OS (Windows, Linux, etc.) where you want to publish your software.\nThis will make the `zig` compiler to build your project to multiple target OS's at once.\nThe Zig Build System official documentation have a [great code example that demonstrates this strategy](https://ziglang.org/learn/build-system/#handy-examples)[^zig-ex].\n\n[^zig-ex]: <https://ziglang.org/learn/build-system/#handy-examples>\n\n\nA target object is created by the following methods of the `Build` struct that we introduced\nat @sec-build-fun:\n\n- `addExecutable()` creates an executable file;\n- `addSharedLibrary()` creates a shared library file;\n- `addStaticLibrary()` creates a static library file;\n- `addTest()` creates an executable file that executes unit tests.\n\n\nThese functions are methods from the `Build` struct that you receive\nas input of the `build()` function. All of them, create as output\na `Compile` object, which represents a target object to be compiled\nby the `zig` compiler. All of these functions accept a similar struct literal as input.\nThis struct literal defines three essential specs about this target object that you are building:\n`name`, `target` and `root_source_file`.\n\nWe have already seen these three options being used on the previous example,\nwhere we used the `addExecutable()` method to create an executable target object.\nThis example is reproduced below. Notice the use of the `path()` method\nfrom the `Build` struct, to define a path in the `root_source_file` option.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n```\n:::\n\n\n\n\nThe `name` option specify the name that you want to give to the binary file defined\nby this target object. So, in this example, we are building an executable file named `hello`.\nIs common to set this `name` option to the name of your project.\n\n\nFurthermore, the `target` option specify the target computer architecture (or the target operating system) of this\nbinary file. For example, if you want this target object to run on a Windows machine\nthat uses a `x86_64` architecture, you can set this `target` option to `x86_64-windows-gnu` for example.\nThis will make the `zig` compiler to compile the project to run on a `x86_64` Windows machine.\nYou can see the full list of architectures and OS's that the `zig` compiler supports by running\nthe `zig targets` command in the terminal.\n\nNow, if you are building the project to run on the current machine\nthat you are using to run this build script, you can set this `target`\noption to the `host` method of the `Build` object, like we did in the example above.\nThis `host` method identifies the current machine where you are\ncurrently running the `zig` compiler.\n\n\nAt last, the `root_source_file` option specifies the root Zig module of your project.\nThat is the Zig module that contains the entrypoint to your application (i.e. the `main()` function), or, the main API of your library.\nThis also means that, all the Zig modules that compose your project are automatically discovered\nfrom the import statements you have inside this \"root source file\".\nThe `zig` compiler can detect when a Zig module depends on the other through the import statements,\nand, as a result, it can discover the entire map of Zig modules used in your project.\n\nThis is handy, and it is different from what happens in other build systems.\nIn CMake for example, you have to explicitly list the paths to all source files that you want to\ninclude in your build process. This is probably a symptom of the \"lack of conditional\ncompilation\" in the C and C++ compilers. Since they lack this feature, you have\nto explicitly choose which source files should be sent to the C/C++ compiler, because not\nevery C/C++ code is portable or supported in every operating system, and, therefore,\nwould cause a compilation error in the C/C++ compiler.\n\n\nNow, one important detail about the build process is that, you have to **explicitly\ninstall the target objects that you create in your build script**, by using the\n`installArtifact()` method of the `Build` struct.\n\nEverytime you invoke the build process of your project, by calling the `build` command\nof the `zig` compiler, a new directory named `zig-out` is created in the root\ndirectory of your project. This new directory contains the outputs of the build process,\nthat is, the binary files built from your source code.\n\nWhat the `installArtifact()` method do is to install (or copy) the built target objects\nthat you defined to this `zig-out` directory.\nThis means that, if you do not\ninstall the target objects you define in your build script, these target objects are\nessentially discarded at the end of the build process.\n\nFor example, you might be building a project that uses a third party library that is built\ntogether with the project. So, when you build your project, you would need first, to\nbuild the third party library, and then, you link it with the source code of your project.\nSo, in this case, we have two binary files that are generated in the build process (the executable file of your project, and the third party library).\nBut only one is of interest, which is the executable file of our project.\nWe can discard the binary file of the third party library, by simply not installing it\ninto this `zig-out` directory.\n\nThis `installArtifact()` method is pretty straightforward. Just remember to apply it to every\ntarget object that you want to save into the `zig-out` directory, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n## Setting the build mode\n\nWe have talked about the three essential options that are set when you create a new target object.\nBut there is also a fourth option that you can use to set the build mode of this target object,\nwhich is the `optimize` option.\nThis option is called this way, because the build modes in Zig are treated more of\nan \"optimization vs safety\" problem. So optimization plays an important role here.\nDon't worry, I'm going back to this question very soon.\n\nIn Zig, we have four build modes (which are listed below). Each one of these build modes offer\ndifferent advantages and characteristics. As we described at @sec-compile-debug-mode, the `zig` compiler\nuses the `Debug` build mode by default, when you don't explicitly choose a build mode.\n\n- `Debug`, mode that produces and includes debugging information in the output of the build process (i.e. the binary file defined by the target object);\n- `ReleaseSmall`, mode that tries to produce a binary file that is small in size;\n- `ReleaseFast`, mode that tries to optimize your code, in order to produce a binary file that is as fast as possible;\n- `ReleaseSafe`, mode that tries to make your code as safe as possible, by including safeguards when possible.\n\nSo, when you build your project, you can set the build mode of your target object to `ReleaseFast` for example, which will tell\nthe `zig` compiler to apply important optimizations in your code. This creates a binary file\nthat simply runs faster on most contexts, because it contains a more optimized version of your code.\nHowever, as a result, we often lose some safety features in our code.\nBecause some safety checks are removed from the final binary file,\nwhich makes your code run faster, but in a less safe manner.\n\nThis choice depends on your current priorities. If you are building a cryptography or banking system, you might\nprefer to prioritize safety in your code, so, you would choose the `ReleaseSafe` build mode, which is a little\nslower to run, but much more secure, because it includes all possible runtime safety checks in the binary file\nbuilt in the build process. In the other hand, if you are writing a game for example, you might prefer to prioritize performance\nover safety, by using the `ReleaseFast` build mode, so that your users can experience faster frame rates in your game.\n\nIn the example below, we are creating the same target object that we have used on previous examples.\nBut this time, we are specifying the build mode of this target object to the `ReleaseSafe` mode.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .optimize = .ReleaseSafe\n});\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n## Setting the version of your build\n\nEverytime you build a target object in your build script, you can assign a version\nnumber to this specific build, following a semantic versioning framework.\nYou can find more about semantic versioning by visiting the [Semantic Versioning website](https://semver.org/)[^semver].\nAnyway, in Zig, you can specify the version of your build, by providing a `SemanticVersion` struct to\nthe `version` option, like in the example below:\n\n\n[^semver]: <https://semver.org/>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .version = .{\n        .major = 2, .minor = 9, .patch = 7\n    }\n});\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n## Detecting the OS in your build script {#sec-detect-os}\n\nIs very common in Build Systems to use different options, or, to include different modules, or,\nto link against different libraries depending on the Operational System (OS)\nthat you are targeting in the build process.\n\nIn Zig, you can detect the target OS of the build process, by looking\nat the `os.tag` inside the `builtin` module from the Zig library.\nIn the example below, we are using an if statement to run some\narbitrary code when the target of the build process is a\nWindows system.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nif (builtin.target.os.tag == .windows) {\n    // Code that runs only when the target of\n    // the compilation process is Windows.\n}\n```\n:::\n\n\n\n\n\n## Adding a run step to your build process\n\nOne thing that is neat in Rust is that you can compile and run your\nsource code with one single command (`cargo run`) from the Rust compiler.\nWe saw at @sec-compile-run-code how can we perform a similar job in Zig, by\nbuilding and running our Zig source code through the `run` command from the `zig` compiler.\n\nBut how can we, at the same time, build and run the binary file specified by a target object in our\nbuild script?\nThe answer is by including a \"run artifact\" in our build script.\nA run artifact is created through the `addRunArtifact()` method from the `Build` struct.\nWe simply provide as input to this function the target object that describes the binary file that we\nwant to execute. As a result, this function creates a run artifact that is capable of executing\nthis binary file.\n\nIn the example below, we are defining an executable binary file named `hello`,\nand we use this `addRunArtifact()` method to create a run artifact that will execute\nthis `hello` executable file.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"src/hello.zig\"),\n    .target = b.host\n});\nb.installArtifact(exe);\nconst run_arti = b.addRunArtifact(exe);\n```\n:::\n\n\n\n\nNow that we have created this run artifact, we need to include it in\nthe build process. We do that by declaring a new step in our build\nscript to call this artifact, through the `step()` method of the `Build`\nstruct.\n\nWe can give any name we want to this step, but, for our\ncontext here, I'm going to name this step as \"run\".\nAlso, I give it a brief description to this step (\"Run the project\").\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst run_step = b.step(\n    \"run\", \"Run the project\"\n);\n```\n:::\n\n\n\n\n\nNow that we have declared this \"run step\" we need to tell Zig that\nthis \"run step\" depends on the run artifact.\nIn other words, a run artifact always depends on a \"step\" to effectively be executed.\nBy creating this dependency\nwe finally stablish the necessary commands to build and run the executable file\nfrom the build script.\n\nWe can establish a dependency between the run step and the run artifact\nby using the `dependsOn()` method from the run step. So, we first\ncreate the run step, and then, we link it with the run artifact, by\nusing this `dependsOn()` method from the run step.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nrun_step.dependOn(&run_arti.step);\n```\n:::\n\n\n\n\nThe entire source code of this specific build script that\nwe wrote, piece by piece, in this section, is\navailable in the `build_and_run.zig` module. You can\nsee this module by\n[visiting the official repository of this book](https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig)\n[^module-src].\n\n\n[^module-src]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig>\n\nWhen you declare a new step in your build script, this step\nbecomes available through the `build` command in the `zig` compiler.\nYou can actually see this step by running `zig build --help` in the terminal, like\nin the example below, where we can see that this new \"run\"\nstep that we declared in the build script appeared in the output.\n\n```bash\nzig build --help\n```\n\n```\nSteps:\n  ...\n  run   Run the project\n  ...\n```\n\nNow, everything that we need to is to\ncall this \"run\" step that we created in our build script. We\ncall it by using the name that we gave to this step\nafter the `build` command from the `zig` compiler.\nThis will cause the compiler to build our executable file\nand execute it at the same time.\n\n```bash\nzig build run\n```\n\n## Build unit tests in your project\n\nWe have talked at length about writing unit tests in Zig at @sec-unittests,\nand we also have talked about how to execute these unit tests through\nthe `test` command of the `zig` compiler. However,\nas we did with the `run` command on the previous section, we also might want to\ninclude some commands in our build script to also build and execute the unit tests in our project.\n\nSo, once again, we are going to discuss how a specific built-in command from the `zig` compiler,\n(in this case, the `test` command) can be used in a build script in Zig.\nHere is where a \"test target object\" comes into play.\nAs was described at @sec-targets, we can create a test target object by using the `addTest()` method of\nthe `Build` struct. The first thing that we need to do is to\ndeclare a test target object in our build script.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst test_exe = b.addTest(.{\n    .name = \"unit_tests\",\n    .root_source_file = b.path(\"src/main.zig\"),\n    .target = b.host,\n});\nb.installArtifact(test_exe);\n```\n:::\n\n\n\n\n\nA test target object essentially selects all `test` blocks in all Zig modules\nacross your project, and builds only the source code present inside\nthese `test` blocks in your project. As a result, this target object\ncreates an executable file that contains only the source code present\nin all of these `test` blocks (i.e. the unit tests) in your project.\n\nPerfect! Now that we have declared this test target object, an executable file\nnamed `unit_tests` is built by the `zig` compiler when we trigger the build\nscript with the `build` command. After the build\nprocess is finished, we can simply execute this `unit_tests` executable\nin the terminal.\n\nHowever, if you remember the previous section, we already learned\nhow can we create a run step in our build script, to execute an executable file\nbuilt by the build script.\n\nSo, we could simply add a run step in our build script to run these unit tests\nfrom a single command in the `zig` compiler, to make our lifes easier.\nIn the example below, we demonstrate the commands to\nregister a new build step called \"tests\" in our build script\nto run these unit tests.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst run_arti = b.addRunArtifact(test_exe);\nconst run_step = b.step(\"tests\", \"Run unit tests\");\nrun_step.dependOn(&run_arti.step);\n```\n:::\n\n\n\n\nNow that we registered this new build step, we can trigger it by calling the command below\nin the terminal. You can also checkout the complete source\ncode for this specific build script at the `build_tests.zig` module at the\n[official repository of this book](https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig)\n[^module-src2].\n\n\n[^module-src2]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig>\n\n\n```bash\nzig build tests\n```\n\n\n## Tailoring your build process with user-provided options\n\nSometimes, you want to make a build script that is customizable by the user\nof your project. You can do that by creating user-provided options in\nyour build script. We create an user-provided option by using the\n`option()` method from the `Build` struct.\n\nWith this method, we create a \"build option\" which can be passed\nto the `build.zig` script at the command line. The user have the power of setting\nthis option at the `build` command from the\n`zig` compiler. In other words, each build option that we create\nbecomes a new command line argument that is accessible through the `build` command\nof the compiler.\n\nThese \"user-provided options\" are set by using the prefix `-D` in the command line.\nFor example, if we declare an option named `use_zlib`, that receives a boolean value which\nindicates if we should link our source code to `zlib` or not, we can set the value\nof this option in the command line with `-Duse_zlib`. The code example below\ndemonstrates this idea:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const use_zlib = b.option(\n        bool,\n        \"use_zlib\",\n        \"Should link to zlib?\"\n    ) orelse false;\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"example.zig\"),\n        .target = b.host,\n    });\n    if (use_zlib) {\n        exe.linkSystemLibrary(\"zlib\");\n    }\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\n```bash\nzig build -Duse_zlib=false\n```\n\n\n## Linking to external libraries\n\n\nOne essential part of every build process is the linking stage.\nThis stage is responsible for combining the multiple object files\nthat represent your code, into a single executable file. It also links\nthis executable file to external libraries, if you use any in your code.\n\nIn Zig, we have two notions of a \"library\", which are: 1) a system's library;\n2) a local library. A system's library is just a library that already is installed\nin your system. While a local library is a library that belongs to the current\nproject. Is a library that is present in your project directory, and\nthat you are building together with your project source code.\n\nThe basic difference between the two, is that a system's library is already\nbuilt and installed in your system, supposedly, and all you need to do\nis to link your source code to this library to start using it.\nWe do that by using the `linkSystemLibrary()` method from a\n`Compile` object. This method accepts the name of the library\nin a string as input. Remember from @sec-targets that a `Compile` object\nis a target object that you declare in your build script.\n\nWhen you link a particular target object with a system's library,\nthe `zig` compiler will use `pkg-config` to find where\nare the binary files and also the header files of this library\nin your system.\nWhen it finds these files, the linker present in the `zig` compiler\nwill link your object files with the files of this library to\nproduce a single binary file for you.\n\nIn the example below, we are creating an executable file named `image_filter`,\nand, we are linking this executable file to the C Standard Library with the\nmethod `linkLibC()`, but we also are linking this executable file to the\nC library `libpng` that is currently installed in my system.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"image_filter\",\n        .root_source_file = b.path(\"src/main.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n    exe.linkLibC();\n    exe.linkSystemLibrary(\"png\");\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\nIf you are linking with a C library in your project, is generally a good idea\nto also link your code with the C Standard Library. Because is very likely\nthat this C library uses some functionality of the C Standard Library at some point.\nThe same goes to C++ libraries. So, if you are linking with\nC++ libraries, is a good idea to link your project with the C++\nStandard Library by using the `linkLibCpp()` method.\n\nOn the order side, when you want to link with a local library,\nyou should use the `linkLibrary()` method of a `Compile` object.\nThis method expects to receive another `Compile` object as input.\nThat is, another target object defined in your build script,\nusing either the `addStaticLibrary()` or `addSharedLibrary()` methods\nwhich defines a library to be built.\n\nAs we discussed earlier, a local library is a library\nthat is local to your project, and that is being built together\nwith your project. So, you need to create a target object in your build script\nto build this local library. Then, you link the target objects of interest in your project,\nwith this target object that identifies this local library.\n\nTake a look at this example extracted from the build script of the [`libxev` library](https://github.com/mitchellh/libxev/tree/main)[^libxev2].\nYou can see in this snippet that\nwe are declaring a shared library file, from the `c_api.zig`\nmodule. Then, later in the build script, we declare an\nexecutable file named `\"dynamic-binding-test\"`, which\nlinks to this shared library that we defined earlier\nin the script.\n\n[^libxev2]: <https://github.com/mitchellh/libxev/tree/main>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst optimize = b.standardOptimizeOption(.{});\nconst target = b.standardTargetOptions(.{});\n\nconst dynamic_lib = b.addSharedLibrary(.{\n    .name = dynamic_lib_name,\n    .root_source_file = b.path(\"src/c_api.zig\"),\n    .target = target,\n    .optimize = optimize,\n});\nb.installArtifact(dynamic_lib);\n// ... more lines in the script\nconst dynamic_binding_test = b.addExecutable(.{\n    .name = \"dynamic-binding-test\",\n    .target = target,\n    .optimize = optimize,\n});\ndynamic_binding_test.linkLibrary(dynamic_lib);\n```\n:::\n\n\n\n\n\n\n## Building C code {#sec-building-c-code}\n\nThe `zig` compiler comes with a C compiler embedded in it. In other words,\nyou can use the `zig` compiler to build C projects. This C compiler is available\nthrough the `cc` command of the `zig` compiler.\n\nAs an example, let's use the famous [FreeType library](https://freetype.org/)[^freetype].\nFreeType is one of the most widely used pieces of software in the world.\nIt is a C library designed to produce high-quality fonts. But it is also\nheavily used in the industry to natively render text and fonts\nin the screen of your computer.\n\nIn this section, we are going to write a build script, piece by piece, that is capable\nof building the FreeType project from source.\nYou can find the source code of this build script on the\n[`freetype-zig` repository](https://github.com/pedropark99/freetype-zig/tree/main)[^freetype-zig]\navailable at GitHub.\n\n[^freetype]: <https://freetype.org/>\n[^freetype-zig]: <https://github.com/pedropark99/freetype-zig/tree/main>\n\nAfter you download the source code of FreeType from the official website[^freetype],\nyou can start writing the `build.zig` module. We begin by defining the target object\nthat defines the binary file that we want to compile.\n\nAs an example, I will build the project as a static library file using the `addStaticLibrary()` method\nto create the target object.\nAlso, since FreeType is a C library, I will also link the library\nagainst `libc` through the `linkLibC()` method, to guarantee that any use\nof the C Standard Library is covered in the compilation process.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst target = b.standardTargetOptions(.{});\nconst opti = b.standardOptimizeOption(.{});\nconst lib = b.addStaticLibrary(.{\n    .name = \"freetype\",\n    .optimize = opti,\n    .target = target,\n});\nlib.linkLibC();\n```\n:::\n\n\n\n\n### Creating C compiler flags\n\nCompiler flags are also known as \"compiler options\" by many programmers,\nor also, as \"command options\" in the GCC official documentation.\nIt's fair to also call them as the \"command-line arguments\" of the C compiler.\nIn general, we use compiler flags to turn on (or turn off) some features from the compiler,\nor to tweak the compilation process to fit the needs of our project.\n\nIn build scripts written in Zig, we normally list the C compiler flags to be used in the compilation process\nin a simple array, like in the example below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c_flags = [_][]const u8{\n    \"-Wall\",\n    \"-Wextra\",\n    \"-Werror\",\n};\n```\n:::\n\n\n\n\nIn theory, there is nothing stopping you from using this array to add \"include paths\" (with the `-I` flag)\nor \"library paths\" (with the `-L` flag) to the compilation process. But there are formal ways in Zig to\nadd these types of paths in the compilation process. Both are discussed at @sec-include-paths\nand @sec-library-paths.\n\nAnyway, in Zig, we add C flags to the build process together with the C files that we want to compile, by using the\n`addCSourceFile()` and `addCSourceFiles()` methods. In the example above, we have just declared\nthe C flags that we want to use. But we haven't added them to the build process yet.\nTo do that, we also need to list the C files to be compiled.\n\n### Listing your C files\n\nThe C files that contains \"cross-platform\" source code are listed in the `c_source_files`\nobject below. These are the C files that are included by default in every platform\nsupported by the FreeType library. Now, since the amount of C files in the FreeType library is big,\nI have omitted the rest of the files in the code example below, for brevity purposes.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c_source_files = [_][]const u8{\n    \"src/autofit/autofit.c\",\n    \"src/base/ftbase.c\",\n    // ... and many other C files.\n};\n```\n:::\n\n\n\n\nNow, in addition to \"cross-platform\" source code, we also have some C files in the FreeType project\nthat are platform-specific, meaning that, they contain source code that can only be compiled in specific platforms,\nand, as a result, they are only included in the build process on these specific target platforms.\nThe objects that list these C files are exposed in the code example below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst windows_c_source_files = [_][]const u8{\n    \"builds/windows/ftdebug.c\",\n    \"builds/windows/ftsystem.c\"\n};\nconst linux_c_source_files = [_][]const u8{\n    \"src/base/ftsystem.c\",\n    \"src/base/ftdebug.c\"\n};\n```\n:::\n\n\n\n\nNow that we declared both the files that we want to include and the C compiler flags to be used,\nwe can add them to the target object that describes the FreeType library, by using the\n`addCSourceFile()` and `addCSourceFiles()` methods.\n\nBoth of these functions are methods from a `Compile` object (i.e. a target object).\nThe `addCSourceFile()` method is capable of adding a single C file to the target object,\nwhile the `addCSourceFiles()` method is used to add multiple C files in a single command.\nYou might prefer to use `addCSourceFile()` when you need to use different compiler flags\non specific C files in your project. But, if you can use the same compiler flags\nacross all C files, then, you will probably find `addCSourceFiles()` a better choice.\n\nNotice that we are using the `addCSourceFiles()` method in the example below,\nto add both the C files and the C compiler flags. Also notice that we\nare using the `os.tag` that we learned about at @sec-detect-os, to add the platform-specific\nC files.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nlib.addCSourceFiles(\n    &c_source_files, &c_flags\n);\n\nswitch (builtin.target.os.tag) {\n    .windows => {\n        lib.addCSourceFiles(\n            &windows_c_source_files,\n            &c_flags\n        );\n    },\n    .linux => {\n        lib.addCSourceFiles(\n            &linux_c_source_files,\n            &c_flags\n        );\n    },\n    else => {},\n}\n```\n:::\n\n\n\n\n\n### Defining C Macros\n\nC Macros are an essential part of the C programming language,\nand they are commonly defined through the `-D` flag from a C compiler.\nIn Zig, you can define a C Macro to be used in your build process\nby using the `defineCMacro()` method from the target object that\ndefines the binary file that you are building.\n\nIn the example below, we are using the `lib` object that we have defined\non the previous sections to define some C Macros used by the FreeType project\nin the compilation process. These C Macros specify if FreeType\nshould (or should not) include functionalities from different\nexternal libraries.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nlib.defineCMacro(\"FT_DISABLE_ZLIB\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_PNG\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_HARFBUZZ\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BZIP2\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BROTLI\", \"TRUE\");\nlib.defineCMacro(\"FT2_BUILD_LIBRARY\", \"TRUE\");\n```\n:::\n\n\n\n\n\n### Adding library paths {#sec-library-paths}\n\nLibrary paths are paths in your computer where the C compiler will look (or search) for\nlibrary files to link against your source code. In other words, when you use a library in your\nC source code, and you ask the C compiler to link your source code against this library,\nthe C compiler will search for the binary files of this library across the paths listed\nin this \"library paths\" set.\n\nThese paths are platform specific, and, by default, the C compiler starts by looking at a\npre-defined set of places in your computer. But you can add more paths (or more places)\nto this list. For example, you may have a library installed in a non-conventional place of your\ncomputer, and you can make the C compiler \"see\" this \"non-conventional place\" by adding this path\nto this list of pre-defined paths.\n\nIn Zig, you can add more paths to this set by using the `addLibraryPath()` method from your target object.\nFirst, you defined a `LazyPath` object, containing the path you want to add, then,\nyou provide this object as input to the `addLibraryPath()` method, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst lib_path: std.Build.LazyPath = .{\n    .cwd_relative = \"/usr/local/lib/\"\n};\nlib.addLibraryPath(lib_path);\n```\n:::\n\n\n\n\n\n\n\n### Adding include paths {#sec-include-paths}\n\nThe preprocessor search path is a popular concept from the\nC community, but it is also known by many C programmers as \"include paths\", because\nthe paths in this \"search path\" relate to the `#include` statements found in the C files.\n\nInclude paths are similar to library paths. They are a set of pre-defined places in your computer where\nthe C compiler will look for files during the compilation process. But instead of looking for\nlibrary files, the include paths are places where the compiler looks for header files included\nin your C source code.\nThis is why many C programmers prefer to call these paths as the \"preprocessor search path\".\nBecause header files are processed during the preprocessor stage of the compilation\nprocess.\n\nSo, every header file that you include in your C source code, through a `#include` statements needs to\nbe found somewhere, and the C compiler will search for this header file across the paths listed in this \"include paths\" set.\nInclude paths are added to the compilation process through the `-I` flag.\n\nIn Zig, you can add new paths to this pre-defined set of paths, by using the `addIncludePath()` method\nfrom your target object. This method also accepts a `LazyPath` object as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst inc_path: std.Build.LazyPath = .{\n    .path = \"./include\"\n};\nlib.addIncludePath(inc_path);\n```\n:::\n",
+    "supporting": [
+      "07-build-system_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/12-file-op/execute-results/html.json b/_freeze/Chapters/12-file-op/execute-results/html.json
index db6b2f0f..d1200279 100644
--- a/_freeze/Chapters/12-file-op/execute-results/html.json
+++ b/_freeze/Chapters/12-file-op/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "4a1606d6f27df37d37adcaaa5fcd5bd8",
+  "hash": "e7a97064b2b87b0c0d58e245144e133b",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n\n# Filesystem and Input/Output (IO) {#sec-filesystem}\n\nIn this chapter we are going to discuss how to use the cross-platform structs and functions\nfrom the Zig Standard Library that can execute filesystem operations. Most of these functions and structs\ncomes from the `std.fs` module.\n\nWe are also going to talk about Input/Output (also known as IO) operations in Zig. Most of\nthese operations are made by using the structs and functions from `std.io` module, which defines\nfile descriptors for the *standard channels* of your system (`stdout` and `stdin`), and also,\nfunctions to create and use I/O streams.\n\n\n## Input/Output basics {#sec-io-basics}\n\nIf you have some experience in a high-level language, you have certainly used\nthese input and output functionalities before in this language. In other words, you certainly have\nbeen in a situation where you needed to sent some output to the user, or, to receive an input\nfrom the user.\n\nFor example, in Python we can receive some input from the user by using the `input()` built-in\nfunction. But we can also print (or \"show\") some output to the user by using the `print()`\nbuilt-in function. So yes, if you have programmed before in Python, you certainly have\nused these functions once before.\n\nBut do you know how these functions relate back to your operating system (OS)? How exactly\nthey are interacting with the resources of your OS to receive or sent some input/output.\nIn essence, these input/output functions from high-level languages are just abstractions\nover the *standard output* and *standard input* channels of your operating system.\n\nThis means that we receive an input, or send some output, through the operating system.\nIt is the OS that makes the bridge between the user and your program. Your program\ndoes not have a direct access to the user. It is the OS that intermediates every\nmessage exchanged between your program and the user.\n\nThe *standard output* and *standard input* channels of your OS are commonly known as the\n`stdout` and `stdin` channels of your OS, respectively. In some contexts, they are also\ncalled the *standard output device* and the *standard input device*. As the name suggests,\nthe *standard output* is the channel through which output flows, while the *standard input*\nis the channel in which input flows.\n\nFurthermore, OS's also normally create a dedicated channel for exchanging error messages, which is known as the\n*standard error* channel, or, the `stderr` channel. This is the channel to which error and warning messages\nare usually sent to. These are the messages that are normally displayed in red-like or orange-like colors\ninto your terminal.\n\nNormally, every OS (e.g. Windows, MacOS, Linux, etc.) creates a dedicated and separate set of\n*standard output*, *standard error* and *standard input* channels for every single program (or process) that runs in your computer.\nThis means that every program you write have a dedicated `stdin`, `stderr` and `stdout` that are separate\nfrom the `stdin`, `stderr` and `stdout` of other programs and processes that are currently running.\n\nThis is a behaviour from your OS. This does not come from the programming language that you are using.\nBecause as I sad earlier, input and output in programming languages, especially\nin high-level ones, are just a simple abstraction over the `stdin`, `stderr` and `stdout` from your current OS.\nThat is, your OS is the intermediary between every input/output operation made in your program,\nregardless of the programming language that you are using.\n\n\n### The writer and reader pattern {#sec-writer-reader}\n\nIn Zig, there is a pattern around input/output (IO). I (the author of this book) don't know if there\nis an official name for this pattern. But here, in this book, I will call it the \"writer and reader pattern\".\nIn essence, every IO operation in Zig is made through either a `GenericReader` or a `GenericWriter` object[^gen-zig].\n\nThese two data types come from the `std.io` module of the Zig Standard Library. As their names suggests, a\n`GenericReader` is an object that offers tools to read data from \"something\" (or \"somewhere\"), while a `GenericWriter`\noffers tools to write data into this \"something\". This \"something\" might be different things: like a\nfile that exists in your filesystem; or, it might be a network socket in your system[^sock]; or,\na continuous stream of data, like a standard input device from your system, that might be constantly\nreceiving new data from users, or, as another example, a live chat in a game that is constantly\nreceiving and displaying new messages from the players of the game.\n\n[^gen-zig]: Previously, these objects were known as the `Reader` and `Writer` objects.\n[^sock]: The socket objects that we have created at @sec-create-socket, are examples of network sockets.\n\nSo, if you want to **read** data from something, or somewhere, it means that you need to use a `GenericReader` object.\nBut if you need instead, to **write** data into this \"something\", then, you need to use a `GenericWriter` object instead.\nBoth of these objects are normally created from a file descriptor object. More specifically, through the `writer()` and `reader()`\nmethods of this file descriptor object. If you are not familiar with this type of object, go to the next section.\n\nEvery `GenericWriter` object have methods like `print()`, which allows you to write/send a formatted string\n(i.e. this formatted string is like a `f` string in Python, or, similar to the `printf()` C function)\ninto the \"something\" (file, socket, stream, etc.) that you are using. It also have a `writeAll()` method, which allows you to\nwrite a string, or, an array of bytes into the \"something\".\n\nLikewise, every `GenericReader` object have methods like `readAll()`, which allows you to read the\ndata from the \"something\" (file, socket, stream, etc.) until it fills a particular array (i.e. a \"buffer\") object.\nIn other words, if you provide an array object of 300 `u8` values to `readAll()`, then, this method attempts to read 300 bytes\nof data from the \"something\", and it stores them into the array object that you have provided.\n\nWe also have other methods, like the `readAtLeast()` method, which allows you to specify how\nmany bytes exactly you want to read from the \"something\". In more details, if you give the\nnumber $n$ as input to this method, then, it will attempt to read at least $n$ bytes of data\nfrom the \"something\". The \"something\" might have less than $n$ bytes of data available for you\nto read, so, it is not guaranteed that you will get precisely $n$ bytes as result.\n\nAnother useful method is `readUntilDelimiterOrEof()`. In this method, you specify a \"delimiter character\".\nThe idea is that this function will attempt to read as many bytes of data as possible from the \"something\",\nuntil it encounters the end of the stream, or, it encounters the \"delimiter character\" that you have specified.\n\nIf you don't know exactly how many bytes will come from the \"something\", you may find the `readAllAlloc()` method\nuseful. In essence, you provide an allocator object to this method, so that it can allocate more space if needed.\nAs consequence, this method will try to read all bytes of the \"something\", and, if it runs out of space at some point\nduring the \"reading process\", it uses the allocator object to allocate more space to continue reading the bytes.\nAs result, this method returns a slice to the array object containing all the bytes read.\n\nThis is just a quick description of the methods present in these types of objects. But I recommend you\nto read the official docs, both for\n[`GenericWriter`](https://ziglang.org/documentation/master/std/#std.io.GenericWriter)[^gen-write] and\n[`GenericReader`](https://ziglang.org/documentation/master/std/#std.io.GenericReader)[^gen-read].\nI also think it is a good idea to read the source code of the modules in the Zig Standard Library\nthat defines the methods present in these objects, which are the\n[`Reader.zig`](https://github.com/ziglang/zig/blob/master/lib/std/io/Reader.zig)[^mod-read]\nand [`Writer.zig`]()[^mod-write].\n\n[^gen-read]: <https://ziglang.org/documentation/master/std/#std.io.GenericReader>.\n[^gen-write]: <https://ziglang.org/documentation/master/std/#std.io.GenericWriter>.\n[^mod-read]: <https://github.com/ziglang/zig/blob/master/lib/std/io/Reader.zig>.\n[^mod-write]: <https://github.com/ziglang/zig/blob/master/lib/std/io/Writer.zig>.\n\n\n\n### Introducing file descriptors {#sec-file-descriptor}\n\nA \"file descriptor\" object is a core component behind every IO operation that is made in any operating system (OS).\nSuch object is an identifier for a particular input/output (IO) resource from your OS [@wiki_file_descriptor].\nIt describes and identifies this particular resource. An IO resource might be:\n\n- an existing file in your filesystem.\n- an existing network socket.\n- other types of stream channels.\n- a pipeline (or just \"pipe\") in your terminal[^pipes].\n\n[^pipes]: A pipeline is a mechanism for inter-process communication, or, inter-process IO. You could also interpret a pipeline as a \"set of processes that are chained together, through the standard input/output devices of the system\". At Linux for example, a pipeline is created inside a terminal, by connecting two or more terminal commands with the \"pipe\" character (`|`).\n\nFrom the bullet points listed above, we know that although the term \"file\" is present,\na \"file descriptor\" might describe something more than just a file.\nThis concept of a \"file descriptor\" comes from the Portable Operating System Interface (POSIX) API,\nwhich is a set of standards that guide how operating systems across the world should be implemented,\nto maintain compatibility between them.\n\nA file descriptor not only identifies the input/output resource that you are using to receive or send some data,\nbut it also describes where this resource is, and also, which IO mode this resource is currently using.\nFor example, this IO resource might be using only the \"read\" IO mode, which means that this resource\nis open to \"read operations\", while \"write operations\" are not authorized.\nThese IO modes are essentially the modes that you provide to the argument `mode`\nfrom the `fopen()` C function, and also, from the `open()` Python built-in function.\n\nIn C, a \"file descriptor\" is a `FILE` pointer, but, in Zig, a file descriptor is a `File` object.\nThis data type (`File`) is described in the `std.fs` module of the Zig Standard Library.\nWe normally don't create a `File` object directly in our Zig code. Instead, we normally get such object as result when we\nopen an IO resource. In other words, we normally ask our OS to open a particular IO resource for us,\nand, if the OS do open successfully this IO resource, the OS normally handles back to us\na file descriptor to this particular IO resource.\n\nSo you usually get a `File` object by using functions and methods from the Zig Standard Library\nthat asks the OS to open some IO resource, like the `openFile()` method that opens a file in the\nfilesystem. The `net.Stream` object that we have created at @sec-create-socket is also a type of\nfile descriptor object.\n\n\n### The *standard output*\n\nYou already saw across this book, how can we access and use specifically the `stdout` in Zig\nto send some output to the user.\nFor that, we use the `getStdOut()` function from the `std.io` module. This function returns\na file descriptor that describes the `stdout` channel of your current OS. Through this file\ndescriptor object, we can read from or write stuff to the `stdout` of our program.\n\nAlthough we can read stuff recorded into the `stdout` channel, we normally only\nwrite to (or \"print\") stuff into this channel. The reason is very similar to what we discussed at\n@sec-read-http-message, when we were discussing what \"reading from\" versus \"writing to\" the connection\nobject from our small HTTP Server project would mean.\n\nWhen we write stuff into a channel, we are essentially sending data to the other end of this channel.\nIn contrast, when we read stuff from this channel, we are essentially reading the data that was sent\nthrough this channel. Since the `stdout` is a channel to send output to the user, the key verb here\nis **send**. We want to send something to someone, and, as consequence, we want to **write** something\ninto some channel.\n\nThat is why, when we use `getStdOut()`, most of the times, we also use the `writer()` method from the `stdout` file descriptor,\nto get access to a writer object that we can use to write stuff into this `stdout` channel.\nMore specifically, this `writer()` method returns a `GenericWriter` object. One of the\nmain methods of this `GenericWriter` object is the `print()` method that we have used\nbefore to write (or \"print\") a formatted string into the `stdout` channel.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    try stdout.writeAll(\n        \"This message was written into stdout.\\n\"\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nThis message was written into stdout.\n```\n\n\n:::\n:::\n\n\n\n\n\n\nThis `GenericWriter` object is like any other generic writer object that you would normally get from a file descriptor object.\nSo, the same methods from a generic writer object that you would use while writing files to the filesystem for example, you could also\nuse them here, from the file descriptor object of `stdout`, and vice-versa.\n\n\n### The *standard input*\n\nYou can access the *standard input* (i.e. `stdin`) in Zig by using the `getStdIn()` function from the `std.io` module.\nLike its brother (`getStdOut()`), this function also returns a file descriptor object that describes the `stdin` channel\nof your OS.\n\nBecause we want to receive some input from the user, the key verb here becomes **receive**, and, as consequence,\nwe usually want to **read** data from the `stdin` channel, instead of writing data into it. So, we normally use\nthe `reader()` method of the file descriptor object returned by `getStdIn()`, to get access to a `GenericReader`\nobject that we can use to read data from `stdin`.\n\nIn the example below, we are creating a small buffer capable of holding 20 characters. Then, we try to read\nthe data from the `stdin` with the `readUntilDelimiterOrEof()` method, and save this data into the `buffer` object.\nAlso notice that we are reading the data from the `stdin` until we hit a new line character (`'\\n'`).\n\nIf you execute this program, you will notice that it stops the execution, ands start to wait indefinitely\nfor some input from the user. In other words, you need to type your name into the terminal, and then, you press Enter to\nsend your name to `stdin`. After you send your name to `stdin`, the program reads this input, and continues with the execution,\nby printing the given name to `stdout`. In the example below, I typed my name (Pedro) into the terminal, and then, pressed Enter.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst stdin = std.io.getStdIn().reader();\npub fn main() !void {\n    try stdout.writeAll(\"Type your name\\n\");\n    var buffer: [20]u8 = undefined;\n    @memset(buffer[0..], 0);\n    _ = try stdin.readUntilDelimiterOrEof(buffer[0..], '\\n');\n    try stdout.print(\"Your name is: {s}\\n\", .{buffer});\n}\n```\n:::\n\n\n\n\n```\nType your name\nYour name is: Pedro\n\n```\n\n\n### The *standard error*\n\nThe *standard error* (a.k.a. the `stderr`) works exactly the same as `stdout` and `stdin`.\nYou just call the `getStdErr()` function from the `std.io` module, and you get the file descriptor to `stderr`.\nIdeally, you should write only error or warning messages to `stderr`, because this is\nthe purpose of this channel.\n\n\n\n\n\n## Buffered IO\n\nAs we described at @sec-io-basics, input/output (IO) operations are made directly by the operating system.\nIt is the OS that manages the IO resource that you want to use for your IO operations.\nThe consequence of this fact is that IO operations are heavily based on system calls (i.e. calling the operating system directly).\n\nJust to be clear, there is nothing particularly wrong with system calls. We use them all the time on\nany serious codebase written in any low-level programming language. However, system calls are\nalways orders of magnitude slower than many different types of operations.\n\nSo is perfectly fine to use a system call once in a while. But when these system calls are used often,\nyou can clearly notice most of the time the loss of performance in your application. So, the good rule of thumbs\nis to use a system call only when it is needed, and also, only in infrequent situations, to reduce\nthe number of system calls performed to a minimum.\n\n\n### Understanding how buffered IO works\n\nBuffered IO is a strategy to achieve better performance. It is used to reduce the number of system calls made by IO operations, and, as\nconsequence, achieve a much higher performance. At @fig-unbuffered-io and @fig-buffered-io you can find two different diagrams\nwhich presents the difference between read operations performed in an unbuffered IO environment versus a buffered IO environment.\n\nTo give a better context to these diagrams, let's suppose that we have a text file that contains the famous Lorem ipsum text[^lorem]\nin our filesystem. Let's also suppose that these diagrams at @fig-unbuffered-io and @fig-buffered-io\nare showing the read operations that we are performing to read the Lorem ipsum text from this text file.\nThe first thing you will notice when looking at these diagrams, is that in an unbuffered environment\nthe read operations leads to many system calls.\nMore precisely, in the diagram exposed at @fig-unbuffered-io we get one system call per each byte that we read from the text file.\nOn the other hand, at @fig-buffered-io we have only one system call at the very beginning.\n\nWhen we use a buffered IO system, at the first read operation we perform, instead of sending one single byte directly\nto our program, the OS first sends a chunk of bytes from the file to a buffer object (i.e. an array).\nThis chunk of bytes are cached/stored inside this buffer object.\n\nTherefore, from now on, for every new read operation that you perform, instead of making a new system call to ask\nfor the next byte in the file to the OS, this read operation is redirected to the buffer object, that have\nthis next byte already cached and ready to go.\n\n\n[^lorem]: <https://www.lipsum.com/>.\n\n\n![Unbuffered IO](./../Figures/unbuffered-io.png){#fig-unbuffered-io width=60%}\n\n![Buffered IO](./../Figures/buffered-io.png){#fig-buffered-io}\n\n\n\nThis is the basic logic behind buffered IO systems. The size of the buffer object depends on multiple factors. But it is usually\nequal to the size of a full page of memory (4096 bytes). If we follow this logic, then, the OS reads the first 4096 bytes\nof the file and caches it into the buffer object. As long as your program does not consume all of these 4096 bytes from the buffer,\nyou will not create new system calls.\n\nHowever, as soon as you consume all of these 4096 bytes from the buffer, it means that there is no bytes left in the buffer.\nIn this situation, a new system call is made to ask the OS to send the next 4096 bytes in the file, and once again,\nthese bytes are cached into the buffer object, and the cycle starts once again.\n\n\n### Buffered IO across different languages\n\nIO operations made through a `FILE` pointer in C are buffered\nby default, so, at least in C, you don't need to worry about this subject. But in contrast, IO operations in both Rust and Zig are not\nbuffered depending on which functions from the standard libraries that you are using.\n\nFor example, in Rust, buffered IO is implemented through the `BufReader` and `BufWriter` structs, while in Zig, it is implemented\nthrough the `BufferedReader` and `BufferedWriter` structs.\nSo any IO operation that you perform through the `GenericWriter` and `GenericReader` objects\nthat I presented at @sec-writer-reader are not buffered, which means that these objects\nmight create a lot of system calls depending on the situation.\n\n\n### Using buffered IO in Zig\n\nUsing buffered IO in Zig is actually very easy. All you have to do is to just\ngive the `GenericWriter` object to the `bufferedWriter()` function, or, to give the `GenericReader`\nobject to the `bufferedReader()` function. These functions come from the `std.io` module,\nand they will construct the `BufferedWriter` or `BufferedReader` object for you.\n\nAfter you create this new `BufferedWriter` or `BufferedReader` object, you can call the `writer()`\nor `reader()` method of this new object, to get access to a new (and buffered) generic reader or\ngeneric writer.\n\nLet's describe the process once again. Every time that you have a file descriptor object, you first get the generic writer or generic reader\nobject from it, by calling the `writer()` or `reader()` methods of this file descriptor object.\nThen, you provide this generic writer or generic reader to the `bufferedWriter()` or `bufferedReader()`\nfunction, which creates a new `BufferedWriter` or `BufferedReader` object. Then, you call\nthe `writer()` or `reader()` methods of this buffered writer or buffered reader object,\nwhich gives you access to a generic writer or a generic reader object that is buffered.\n\nTake this program as an example. This program is demonstrating the process exposed at @fig-buffered-io.\nWe are simply opening a text file that contains the Lorem ipsum text, and then, we create a buffered IO reader object\nat `bufreader`, and we use this `bufreader` object to read the contents of this file into a buffer object, then,\nwe end the program by printing this buffer to `stdout`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar file = try std.fs.cwd().openFile(\n    \"ZigExamples/file-io/lorem.txt\", .{}\n);\ndefer file.close();\nvar buffered = std.io.bufferedReader(file.reader());\nvar bufreader = buffered.reader();\n\nvar buffer: [1000]u8 = undefined;\n@memset(buffer[0..], 0);\n\n_ = try bufreader.readUntilDelimiterOrEof(\n    buffer[0..], '\\n'\n);\ntry stdout.print(\"{s}\\n\", .{buffer});\n```\n:::\n\n\n\n\n```\nLorem ipsum dolor sit amet, consectetur\nadipiscing elit. Sed tincidunt erat sed nulla ornare, nec\naliquet ex laoreet. Ut nec rhoncus nunc. Integer magna metus,\nultrices eleifend porttitor ut, finibus ut tortor. Maecenas\nsapien justo, finibus tincidunt dictum ac, semper et lectus.\nVivamus molestie egestas orci ac viverra. Pellentesque nec\narcu facilisis, euismod eros eu, sodales nisl. Ut egestas\nsagittis arcu, in accumsan sapien rhoncus sit amet. Aenean\nneque lectus, imperdiet ac lobortis a, ullamcorper sed massa.\nNullam porttitor porttitor erat nec dapibus. Ut vel dui nec\nnulla vulputate molestie eget non nunc. Ut commodo luctus ipsum,\nin finibus libero feugiat eget. Etiam vel ante at urna tincidunt\nposuere sit amet ut felis. Maecenas finibus suscipit tristique.\nDonec viverra non sapien id suscipit.\n```\n\nDespite being a buffered IO reader, this `bufreader` object is similar to any other `GenericReader` object,\nand have the exact same methods. So, although these two types of objects perform very different IO operations,\nthey have the same interface, so you, the programmer, can interchangeably use them\nwithout the need to change anything in your source code.\nSo a buffered IO reader or a buffered IO writer objects have the same methods than its generic and unbuffered brothers,\ni.e. the generic reader and generic writer objects that I presented at @sec-writer-reader.\n\n::: {.callout-tip}\nIn general, you should always use a buffered IO reader or a buffered IO writer object to perform\nIO operations in Zig. Because they deliver better performance to your IO operations.\n:::\n\n\n## Filesystem basics\n\nNow that we have discussed the basics around Input/Output operations in Zig, we need to\ntalk about the basics around filesystems, which is another core part of any operating system.\nAlso, filesystems are related to input/output, because the files that we store and create in our\ncomputer are considered an IO resource, as we described at @sec-file-descriptor.\n\n\n### The concept of current working directory (CWD)\n\nThe working directory is the folder on your computer where you are currently rooted at.\nIn other words, it is the folder that your program is currently looking at.\nTherefore, whenever you are executing a program, this program is always working with\na specific folder on your computer. It is always in this folder that the program will initially\nlook for the files you require, and it is also in this folder that the program\nwill initially save all the files you ask it to save.\n\nThe working directory is determined by the folder from which you invoke your program\nin the terminal. In other words, if you are in the terminal of your OS, and you\nexecute a binary file (i.e. a program) from this terminal, the folder to which your terminal\nis pointing at is the current working directory of your program that is being executed.\n\nAt @fig-cwd we have an example of me executing a program from the terminal. We are executing\nthe program outputted by the `zig` compiler by compiling the Zig module named `hello.zig`.\nThe CWD in this case is the `zig-book` folder. In other words, while the `hello.zig` program\nis executing, it will be looking at the `zig-book` folder, and any file operation that we perform\ninside this program, will be using this `zig-book` folder as the \"starting point\", or, as the \"central focus\".\n\n![Executing a program from the terminal](./../Figures/cwd.png){#fig-cwd}\n\nJust because we are rooted inside a particular folder (in the case of @fig-cwd, the `zig-book` folder) of our computer,\nit doesn't mean that we cannot access or write resources in other locations of our computer.\nThe current working directory (CWD) mechanism just defines where your program will look first\nfor the files you ask for. This does not prevent you from accessing files that are located\nelsewhere on your computer. However, to access any file that is in a folder other than your\ncurrent working directory, you must provide a path to that file or folder.\n\n\n### The concept of paths\n\nA path is essentially a location. It points to a location in your filesystem. We use\npaths to describe the location of files and folders in our computer.\nOne important aspect about paths is that they are always written inside strings,\ni.e. they are always provided as text values.\n\nThere are two types of paths that you can provide to any program in any OS: a relative path, or an absolute path.\nAbsolute paths are paths that start at the root of your filesystem, and go all the way to the file name or the specific folder\nthat you are referring to. This type of path is called absolute, because it points to an unique and absolute location on your computer.\nThat is, there is no other existing location on your computer that corresponds to this path. It is an unique identifier.\n\nIn Windows, an absolute path is a path that starts with a hard disk identifier (e.g. `C:/Users/pedro`).\nOn the other hand, absolute paths in Linux and MacOS, are paths that start with a forward slash character (e.g. `/usr/local/bin`).\nNotice that a path is composed by \"segments\". Each segment is connected to each other by a slash character (`\\` or `/`).\nOn Windows, the backward slash (`\\`) is normally used to connect the path segments. While on Linux and MacOS, the forward\nslash (`/`) is the character used to connect path segments.\n\nA relative path is a path that start at the CWD. In other words, a relative path is\n\"relative to the CWD\". The path used to access the `hello.zig` file at @fig-cwd is an example of a relative path. This path\nis reproduced below. This path begins at the CWD, which in the context of @fig-cwd, is the `zig-book` folder,\nthen, it goes to the `ZigExamples` folder, then, into `zig-basics`, then, to the `hello.zig` file.\n\n```\nZigExamples/zig-basics/hello_world.zig\n```\n\n\n### Path wildcards\n\nWhen providing paths, especially relative paths, you have the option of using a *wildcard*.\nThere are two commonly used *wildcards* in paths, which are \"one period\" (.) and \"two periods\" (..).\nIn other words, these two specific characters have special meanings when used in paths,\nand can be used on any operating system (Mac, Windows, Linux, etc.). That is, they\nare \"cross platform\".\n\nThe \"one period\" represents an alias for the current directory.\nThis means that the relative paths `\"./Course/Data/covid.csv\"` and `\"Course/Data/covid.csv\"` are equivalent.\nOn the other hand, the \"two periods\" refers to the previous directory.\nFor example, the path `\"Course/..\"` is equivalent to the path `\".\"`, that is, the current working directory.\n\nTherefore, the path `\"Course/..\"` refers to the folder before the `Course` folder.\nAs another example, the path `\"src/writexml/../xml.cpp\"` refers to the file `xml.cpp`\nthat is inside the folder before the `writexml` folder, which in this example is the `src` folder.\nTherefore, this path is equivalent to `\"src/xml.cpp\"`.\n\n\n\n\n## The CWD handler\n\nIn Zig, filesystem operations are usually made through a directory handler object.\nA directory handler in Zig is an object of type `Dir`, which is an object that describes\na particular folder in the filesystem of our computer.\nYou normally create a `Dir` object, by calling the `std.fs.cwd()` function.\nThis function returns a `Dir` object that points to (or, that describes) the\ncurrent working directory (CWD).\n\nThrough this `Dir` object, you can create new files, or modify, or read existing ones that are\ninside your CWD. In other words, a `Dir` object is the main entrypoint in Zig to perform\nmultiple types of filesystem operations.\nIn the example below, we are creating this `Dir` object, and storing it\ninside the `cwd` object. Although we are not using this object at this code example,\nwe are going to use it a lot over the next examples.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\n_ = cwd;\n```\n:::\n\n\n\n\n\n\n\n\n\n\n\n## File operations\n\n### Creating files {#sec-creating-files}\n\nWe create new files by using the `createFile()` method from the `Dir` object.\nJust provide the name of the file that you want to create, and this function will\ndo the necessary steps to create such file. You can also provide a relative path to this function,\nand it will create the file by following this path, which is relative to the CWD.\n\nThis function might return an error, so, you should use `try`, `catch`, or any of the other methods presented\nat @sec-error-handling to handle the possible error. But if everything goes well,\nthis `createFile()` method returns a file descriptor object (i.e. a `File` object) as result,\nthrough which you can add content to the file with the IO operations that I presented before.\n\nTake this code example below. In this example, we are creating a new text file\nnamed `foo.txt`. If the function `createFile()` succeeds, the object named `file` will contain a file descriptor\nobject, which we can use to write (or add) new content to the file, like we do in this example, by using\na buffered writer object to write a new line of text to the file.\n\nNow, a quick note, when we create a file descriptor object in C, by using a C function like `fopen()`, we must always close the file\nat the end of our program, or, as soon as we complete all operations that we wanted to perform\non the file. In Zig, this is no different. So everytime we create a new file, this file remains\n\"open\", waiting for some operation to be performed. As soon as we are done with it, we always have\nto close this file, to free the resources associated with it.\nIn Zig, we do this by calling the method `close()` from the file descriptor object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.createFile(\"foo.txt\", .{});\n// Don't forget to close the file at the end.\ndefer file.close();\n// Do things with the file ...\nvar fw = file.writer();\n_ = try fw.writeAll(\n    \"Writing this line to the file\\n\"\n);\n```\n:::\n\n\n\n\n\nSo, in this example we not only have created a file into the filesystem,\nbut we also wrote some data into this file, using the file descriptor object\nreturned by `createFile()`. If the file that you are trying to create\nalready exists in your filesystem, this `createFile()` call will\noverwrite the contents of the file, or, in other words, it will\nin erase all the contents of the existing file.\n\nIf you don't want this to happen, meaning, that you don't want to overwrite\nthe contents of the existing file, but you want to write data to this file anyway\n(i.e. you want to append data to the file), you should use the `openFile()`\nmethod from the `Dir` object.\n\nAnother important aspect about `createFile()` is that this method creates a file\nthat is not open to read operations by default. It means that you cannot read this file.\nYou are not allowed to.\nSo for example, you might want to write some stuff into this file at the beginning of the execution\nof your program. Then, at a future point in your program you might need to read what you\nwrote in this file. If you try to read data from this file, you will likely\nget a `NotOpenForReading` error as result.\n\n\nBut how can you overcome this barrier? How can you create a file that is open\nto read operations? All you have to do, is to set the `read` flag to true\nin the second argument of `createFile()`. When you set this flag to true,\nthen the file get's create with \"read permissions\", and, as consequence,\na program like this one below becomes valid:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.createFile(\n    \"foo.txt\",\n    .{ .read = true }\n);\ndefer file.close();\n\nvar fw = file.writer();\n_ = try fw.writeAll(\"We are going to read this line\\n\");\n\nvar buffer: [300]u8 = undefined;\n@memset(buffer[0..], 0);\ntry file.seekTo(0);\nvar fr = file.reader();\n_ = try fr.readAll(buffer[0..]);\ntry stdout.print(\"{s}\\n\", .{buffer});\n```\n:::\n\n\n\n\n\n```\nWe are going to read this line\n```\n\n\nIf you are not familiar with position indicators, you might not recognize the method\n`seekTo()`. If that is your case, do not worry,\nwe are going to talk more about this method at @sec-indicators. But essentially\nthis method is moving the position indicator back to the beginning of the file,\nso that we can read the contents of the file from the beginning.\n\n\n### Opening files and appending data to it\n\nOpening files is easy. Just use the `openFile()` method instead of `createFile()`.\nIn the first argument of `openFile()` you provide the path to the file that\nyou want to open. Then, on the second argument you provide the flags (or, the options)\nthat dictates how the file is opened.\n\nYou can see the full list of options for `openFile()` by visiting the documentation for\n[`OpenFlags`](https://ziglang.org/documentation/master/std/#std.fs.File.OpenFlags)[^oflags].\nBut the main flag that you will most certainly use is the `mode` flag.\nThis flag specifies the IO mode that the file will be using when it get's opened.\nThere are three IO modes, or, three values that you can provide to this flag, which are:\n\n- `read_only`, allows only read operations on the file. All write operations are blocked.\n- `write_only`, allows only write operations on the file. All read operations are blocked. \n- `read_write`, allows both write and read operations on the file.\n\n[^oflags]: <https://ziglang.org/documentation/master/std/#std.fs.File.OpenFlags>\n\nThese modes are similar to the modes that you provide to the `mode` argument of the\n`open()` Python built-in function[^py-open], or, the `mode` argument of the\n`fopen()` C function[^c-open].\nIn the code example below, we are opening the `foo.txt` text file with a `write_only` mode,\nand appending a new line of text to the end of the file. We use `seekFromEnd()` this time\nto guarantee that we are going to append the text to the end of the file. Once again, methods\nsuch as `seekFromEnd()` are described in more depth at @sec-indicators.\n\n[^py-open]: <https://docs.python.org/3/tutorial/inputoutput.html#reading-and-writing-files>\n[^c-open]: <https://www.tutorialspoint.com/c_standard_library/c_function_fopen.htm>\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.openFile(\n    \"foo.txt\", .{ .mode = .write_only }\n);\ndefer file.close();\ntry file.seekFromEnd(0);\nvar fw = file.writer();\n_ = try fw.writeAll(\"Some random text to write\\n\");\n```\n:::\n\n\n\n\n\n### Deleting files\n\nSometimes, we just need to delete/remove the files that we have.\nTo do that, we use the `deleteFile()` method. You just provide the path of the\nfile that you want to delete, and this method will try to delete the file located\nat this path.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.deleteFile(\"foo.txt\");\n```\n:::\n\n\n\n\n### Copying files\n\nTo copy existing files, we use the `copyFile()` method. The first argument in this method\nis the path to the file that you want to copy. The second argument is a `Dir` object, i.e. a directory handler,\nmore specifically, a `Dir` object that points to the folder in your computer where you want to\ncopy the file to. The third argument is the new path of the file, or, in other words, the new location\nof the file. The fourth argument is the options (or flags) to be used in the copy operation.\n\nThe `Dir` object that you provide as input to this method will be used to copy the file to\nthe new location. You may create this `Dir` object before calling the `copyFile()` method.\nMaybe you are planning to copy the file to a completely different location in your computer,\nso it might be worth to create a directory handler to that location. But if you are copying the\nfile to a subfolder of your CWD, then, you can just simply pass the CWD handler to this argument.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.copyFile(\n    \"foo.txt\",\n    cwd,\n    \"ZigExamples/file-io/foo.txt\",\n    .{}\n);\n```\n:::\n\n\n\n\n\n### Read the docs!\n\nThere are some other useful methods for file operations available at `Dir` objects,\nsuch as the `writeFile()` method, but I recommend you to read the docs for the\n[`Dir` type](https://ziglang.org/documentation/master/std/#std.fs.Dir)[^zig-dir]\nto explore the other available methods, since I already talked too much about them.\n\n\n[^zig-dir]: <https://ziglang.org/documentation/master/std/#std.fs.Dir>\n\n\n\n\n## Position indicators {#sec-indicators}\n\nA position indicator is like a type of cursor, or, an index. This \"index\" identifies the current\nlocation in the file (or, in the data stream) that the file descriptor object that you have\nis currently looking at.\nWhen you create a file descriptor, the position indicator starts at the beginning of the file,\nor, at the beginning of the stream. When you read from or write into the file (or socket, or data stream, etc.)\ndescribed by this file descriptor object, you end up moving the position indicator.\n\nIn other words, any IO operation have a common side effect, which is to move the position indicator.\nFor example, suppose that we have a file of 300 bytes total in size. If you\nread 100 bytes from the file, then, the position indicator moves 100 bytes forward. If you try\nto write 50 bytes into this same file, these 50 bytes will be written from the current\nposition indicated by the position indicator. Since the indicator is at a 100 bytes forward from\nthe beginning of the file, these 50 bytes would be written in the middle of the file.\n\nThis is why we have used the `seekTo()` method at the last code example presented at @sec-creating-files.\nWe have used this method to move the position indicator back to the beginning of the file, which\nwould make sure that we would write the text that we wanted to write from the beginning of the file,\ninstead of writing it from the middle of the file. Because before the write operation, we had\nperformed a read operation, which means that the position indicator was moved in this read operation.\n\nThe position indicators of a file descriptor object can be changed (or altered) by using the\n\"seek\" methods from this file descriptor, which are: `seekTo()`, `seekFromEnd()` and `seekBy()`.\nThese methods have the same effect, or, the same responsibility that the\n[`fseek()`](https://en.cppreference.com/w/c/io/fseek)[^c-fseek] C function.\n\n[^c-fseek]: <https://en.cppreference.com/w/c/io/fseek>\n\n\nConsidering that `offset` refers to the index that you provide as input to these \"seek\" methods,\nthe bullet points below summarises what is the effect of each of these methods.\nAs a quick note, in the case of `seekFromEnd()` and `seekBy()`, the `offset` provided can be either a\npositive or a negative index.\n\n- `seekTo()` will move the position indicator to the location that is `offset` bytes from the beginning of the file.\n- `seekFromEnd()` will move the position indicator to the location that is `offset` bytes from the end of the file.\n- `seekBy()` will move the position indicator to the location that is `offset` bytes from the current position in the file.\n\n\n\n\n\n\n\n## Directory operations\n\n### Iterating through the files in a directory\n\nOne of the most classic tasks related to filesystem is to be able\nto iterate through the existing files in a directory. To iterate over the\nfiles in a directory, we need to create an iterator object.\n\nYou can produce such iterator object by using either the `iterate()` or `walk()` methods\nof a `Dir` object. Both methods return an iterator object as output, which you can advance by using the\n`next()` method. The difference between these methods, is that `iterate()` returns a non-recursive iterator,\nwhile `walk()` does. It means that the iterator returned by `walk()` will not only iterate through\nthe files available in the current directory, but also, through the files from any subdirectory found\ninside the current directory.\n\nIn the example below, we are displaying the names of the files stored inside the\ndirectory `ZigExamples/file-io`. Notice that we had to open this directory through\nthe `openDir()` function. Also notice that we provided the flag `iterate` in the\nsecond argument of `openDir()`. This flag is important, because without this flag,\nwe would not be allowed to iterate through the files in this directory.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst dir = try cwd.openDir(\n    \"ZigExamples/file-io/\",\n    .{ .iterate = true }\n);\nvar it = dir.iterate();\nwhile (try it.next()) |entry| {\n    try stdout.print(\n        \"File name: {s}\\n\",\n        .{entry.name}\n    );\n}\n```\n:::\n\n\n\n\n```\nFile name: create_file_and_write_toit.zig\nFile name: create_file.zig\nFile name: lorem.txt\nFile name: iterate.zig\nFile name: delete_file.zig\nFile name: append_to_file.zig\nFile name: user_input.zig\nFile name: foo.txt\nFile name: create_file_and_read.zig\nFile name: buff_io.zig\nFile name: copy_file.zig\n```\n\n\n### Creating new directories\n\nThere are two methods that are important when it comes to\ncreating directories, which are `makeDir()` and `makePath()`.\nThe difference between these two methods is that `makeDir()` can\nonly create one single directory in the current directory in each call,\nwhile `makePath()` is capable of recursively create subdirectories in the same call.\n\n\nThis is why the name of this method is \"make path\". It will create as many\nsubdirectories as necessary to create the path that you provided as input.\nSo, if you provide the path `\"sub1/sub2/sub3\"` as input to this method,\nit will create three different subdirectories, `sub1`, `sub2` and `sub3`,\nwithin the same function call. In contrast, if you provided such path\nas input to `makeDir()`, you would likely get an error as result, since\nthis method can only create a single subdirectory.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.makeDir(\"src\");\ntry cwd.makePath(\"src/decoders/jpg/\");\n```\n:::\n\n\n\n\n### Deleting directories\n\nTo delete a directory, just provide the path to the directory that you want to delete\nas input to the `deleteDir()` method from a `Dir` object. In the example below,\nwe are deleting the `src` directory that we have just created in the previous example.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.deleteDir(\"src\");\n```\n:::\n\n\n\n\n\n## Conclusion\n\nIn this chapter, I have described how to perform in Zig the most common filesystem and IO operations.\nBut you might feel the lack of some other, less common, operation in this chapter, such as: how to rename files,\nor how to open a directory, or how to create symbolic links, or how to use `access()` to test if a particular\npath exists in your computer. But for all of these less common tasks, I recommend you to read\nthe documentation of the [`Dir` type](https://ziglang.org/documentation/master/std/#std.fs.Dir)[^zig-dir]\n, since you can find a good description of these cases there.\n\n\n\n\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n\n# Filesystem and Input/Output (IO) {#sec-filesystem}\n\nIn this chapter we are going to discuss how to use the cross-platform structs and functions\nfrom the Zig Standard Library that can execute filesystem operations. Most of these functions and structs\ncomes from the `std.fs` module.\n\nWe are also going to talk about Input/Output (also known as IO) operations in Zig. Most of\nthese operations are made by using the structs and functions from `std.io` module, which defines\nfile descriptors for the *standard channels* of your system (`stdout` and `stdin`), and also,\nfunctions to create and use I/O streams.\n\n\n## Input/Output basics {#sec-io-basics}\n\nIf you have some experience in a high-level language, you have certainly used\nthese input and output functionalities before in this language. In other words, you certainly have\nbeen in a situation where you needed to sent some output to the user, or, to receive an input\nfrom the user.\n\nFor example, in Python we can receive some input from the user by using the `input()` built-in\nfunction. But we can also print (or \"show\") some output to the user by using the `print()`\nbuilt-in function. So yes, if you have programmed before in Python, you certainly have\nused these functions once before.\n\nBut do you know how these functions relate back to your operating system (OS)? How exactly\nthey are interacting with the resources of your OS to receive or sent some input/output.\nIn essence, these input/output functions from high-level languages are just abstractions\nover the *standard output* and *standard input* channels of your operating system.\n\nThis means that we receive an input, or send some output, through the operating system.\nIt is the OS that makes the bridge between the user and your program. Your program\ndoes not have a direct access to the user. It is the OS that intermediates every\nmessage exchanged between your program and the user.\n\nThe *standard output* and *standard input* channels of your OS are commonly known as the\n`stdout` and `stdin` channels of your OS, respectively. In some contexts, they are also\ncalled the *standard output device* and the *standard input device*. As the name suggests,\nthe *standard output* is the channel through which output flows, while the *standard input*\nis the channel in which input flows.\n\nFurthermore, OS's also normally create a dedicated channel for exchanging error messages, which is known as the\n*standard error* channel, or, the `stderr` channel. This is the channel to which error and warning messages\nare usually sent to. These are the messages that are normally displayed in red-like or orange-like colors\ninto your terminal.\n\nNormally, every OS (e.g. Windows, macOS, Linux, etc.) creates a dedicated and separate set of\n*standard output*, *standard error* and *standard input* channels for every single program (or process) that runs in your computer.\nThis means that every program you write have a dedicated `stdin`, `stderr` and `stdout` that are separate\nfrom the `stdin`, `stderr` and `stdout` of other programs and processes that are currently running.\n\nThis is a behaviour from your OS. This does not come from the programming language that you are using.\nBecause as I sad earlier, input and output in programming languages, especially\nin high-level ones, are just a simple abstraction over the `stdin`, `stderr` and `stdout` from your current OS.\nThat is, your OS is the intermediary between every input/output operation made in your program,\nregardless of the programming language that you are using.\n\n\n### The writer and reader pattern {#sec-writer-reader}\n\nIn Zig, there is a pattern around input/output (IO). I (the author of this book) don't know if there\nis an official name for this pattern. But here, in this book, I will call it the \"writer and reader pattern\".\nIn essence, every IO operation in Zig is made through either a `GenericReader` or a `GenericWriter` object[^gen-zig].\n\nThese two data types come from the `std.io` module of the Zig Standard Library. As their names suggests, a\n`GenericReader` is an object that offers tools to read data from \"something\" (or \"somewhere\"), while a `GenericWriter`\noffers tools to write data into this \"something\". This \"something\" might be different things: like a\nfile that exists in your filesystem; or, it might be a network socket in your system[^sock]; or,\na continuous stream of data, like a standard input device from your system, that might be constantly\nreceiving new data from users, or, as another example, a live chat in a game that is constantly\nreceiving and displaying new messages from the players of the game.\n\n[^gen-zig]: Previously, these objects were known as the `Reader` and `Writer` objects.\n[^sock]: The socket objects that we have created at @sec-create-socket, are examples of network sockets.\n\nSo, if you want to **read** data from something, or somewhere, it means that you need to use a `GenericReader` object.\nBut if you need instead, to **write** data into this \"something\", then, you need to use a `GenericWriter` object instead.\nBoth of these objects are normally created from a file descriptor object. More specifically, through the `writer()` and `reader()`\nmethods of this file descriptor object. If you are not familiar with this type of object, go to the next section.\n\nEvery `GenericWriter` object have methods like `print()`, which allows you to write/send a formatted string\n(i.e. this formatted string is like a `f` string in Python, or, similar to the `printf()` C function)\ninto the \"something\" (file, socket, stream, etc.) that you are using. It also have a `writeAll()` method, which allows you to\nwrite a string, or, an array of bytes into the \"something\".\n\nLikewise, every `GenericReader` object have methods like `readAll()`, which allows you to read the\ndata from the \"something\" (file, socket, stream, etc.) until it fills a particular array (i.e. a \"buffer\") object.\nIn other words, if you provide an array object of 300 `u8` values to `readAll()`, then, this method attempts to read 300 bytes\nof data from the \"something\", and it stores them into the array object that you have provided.\n\nWe also have other methods, like the `readAtLeast()` method, which allows you to specify how\nmany bytes exactly you want to read from the \"something\". In more details, if you give the\nnumber $n$ as input to this method, then, it will attempt to read at least $n$ bytes of data\nfrom the \"something\". The \"something\" might have less than $n$ bytes of data available for you\nto read, so, it is not guaranteed that you will get precisely $n$ bytes as result.\n\nAnother useful method is `readUntilDelimiterOrEof()`. In this method, you specify a \"delimiter character\".\nThe idea is that this function will attempt to read as many bytes of data as possible from the \"something\",\nuntil it encounters the end of the stream, or, it encounters the \"delimiter character\" that you have specified.\n\nIf you don't know exactly how many bytes will come from the \"something\", you may find the `readAllAlloc()` method\nuseful. In essence, you provide an allocator object to this method, so that it can allocate more space if needed.\nAs consequence, this method will try to read all bytes of the \"something\", and, if it runs out of space at some point\nduring the \"reading process\", it uses the allocator object to allocate more space to continue reading the bytes.\nAs result, this method returns a slice to the array object containing all the bytes read.\n\nThis is just a quick description of the methods present in these types of objects. But I recommend you\nto read the official docs, both for\n[`GenericWriter`](https://ziglang.org/documentation/master/std/#std.io.GenericWriter)[^gen-write] and\n[`GenericReader`](https://ziglang.org/documentation/master/std/#std.io.GenericReader)[^gen-read].\nI also think it is a good idea to read the source code of the modules in the Zig Standard Library\nthat defines the methods present in these objects, which are the\n[`Reader.zig`](https://github.com/ziglang/zig/blob/master/lib/std/io/Reader.zig)[^mod-read]\nand [`Writer.zig`]()[^mod-write].\n\n[^gen-read]: <https://ziglang.org/documentation/master/std/#std.io.GenericReader>.\n[^gen-write]: <https://ziglang.org/documentation/master/std/#std.io.GenericWriter>.\n[^mod-read]: <https://github.com/ziglang/zig/blob/master/lib/std/io/Reader.zig>.\n[^mod-write]: <https://github.com/ziglang/zig/blob/master/lib/std/io/Writer.zig>.\n\n\n\n### Introducing file descriptors {#sec-file-descriptor}\n\nA \"file descriptor\" object is a core component behind every IO operation that is made in any operating system (OS).\nSuch object is an identifier for a particular input/output (IO) resource from your OS [@wiki_file_descriptor].\nIt describes and identifies this particular resource. An IO resource might be:\n\n- an existing file in your filesystem.\n- an existing network socket.\n- other types of stream channels.\n- a pipeline (or just \"pipe\") in your terminal[^pipes].\n\n[^pipes]: A pipeline is a mechanism for inter-process communication, or, inter-process IO. You could also interpret a pipeline as a \"set of processes that are chained together, through the standard input/output devices of the system\". At Linux for example, a pipeline is created inside a terminal, by connecting two or more terminal commands with the \"pipe\" character (`|`).\n\nFrom the bullet points listed above, we know that although the term \"file\" is present,\na \"file descriptor\" might describe something more than just a file.\nThis concept of a \"file descriptor\" comes from the Portable Operating System Interface (POSIX) API,\nwhich is a set of standards that guide how operating systems across the world should be implemented,\nto maintain compatibility between them.\n\nA file descriptor not only identifies the input/output resource that you are using to receive or send some data,\nbut it also describes where this resource is, and also, which IO mode this resource is currently using.\nFor example, this IO resource might be using only the \"read\" IO mode, which means that this resource\nis open to \"read operations\", while \"write operations\" are not authorized.\nThese IO modes are essentially the modes that you provide to the argument `mode`\nfrom the `fopen()` C function, and also, from the `open()` Python built-in function.\n\nIn C, a \"file descriptor\" is a `FILE` pointer, but, in Zig, a file descriptor is a `File` object.\nThis data type (`File`) is described in the `std.fs` module of the Zig Standard Library.\nWe normally don't create a `File` object directly in our Zig code. Instead, we normally get such object as result when we\nopen an IO resource. In other words, we normally ask our OS to open a particular IO resource for us,\nand, if the OS do open successfully this IO resource, the OS normally handles back to us\na file descriptor to this particular IO resource.\n\nSo you usually get a `File` object by using functions and methods from the Zig Standard Library\nthat asks the OS to open some IO resource, like the `openFile()` method that opens a file in the\nfilesystem. The `net.Stream` object that we have created at @sec-create-socket is also a type of\nfile descriptor object.\n\n\n### The *standard output*\n\nYou already saw across this book, how can we access and use specifically the `stdout` in Zig\nto send some output to the user.\nFor that, we use the `getStdOut()` function from the `std.io` module. This function returns\na file descriptor that describes the `stdout` channel of your current OS. Through this file\ndescriptor object, we can read from or write stuff to the `stdout` of our program.\n\nAlthough we can read stuff recorded into the `stdout` channel, we normally only\nwrite to (or \"print\") stuff into this channel. The reason is very similar to what we discussed at\n@sec-read-http-message, when we were discussing what \"reading from\" versus \"writing to\" the connection\nobject from our small HTTP Server project would mean.\n\nWhen we write stuff into a channel, we are essentially sending data to the other end of this channel.\nIn contrast, when we read stuff from this channel, we are essentially reading the data that was sent\nthrough this channel. Since the `stdout` is a channel to send output to the user, the key verb here\nis **send**. We want to send something to someone, and, as consequence, we want to **write** something\ninto some channel.\n\nThat is why, when we use `getStdOut()`, most of the times, we also use the `writer()` method from the `stdout` file descriptor,\nto get access to a writer object that we can use to write stuff into this `stdout` channel.\nMore specifically, this `writer()` method returns a `GenericWriter` object. One of the\nmain methods of this `GenericWriter` object is the `print()` method that we have used\nbefore to write (or \"print\") a formatted string into the `stdout` channel.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    try stdout.writeAll(\n        \"This message was written into stdout.\\n\"\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nThis message was written into stdout.\n```\n\n\n:::\n:::\n\n\n\n\n\n\nThis `GenericWriter` object is like any other generic writer object that you would normally get from a file descriptor object.\nSo, the same methods from a generic writer object that you would use while writing files to the filesystem for example, you could also\nuse them here, from the file descriptor object of `stdout`, and vice-versa.\n\n\n### The *standard input*\n\nYou can access the *standard input* (i.e. `stdin`) in Zig by using the `getStdIn()` function from the `std.io` module.\nLike its brother (`getStdOut()`), this function also returns a file descriptor object that describes the `stdin` channel\nof your OS.\n\nBecause we want to receive some input from the user, the key verb here becomes **receive**, and, as consequence,\nwe usually want to **read** data from the `stdin` channel, instead of writing data into it. So, we normally use\nthe `reader()` method of the file descriptor object returned by `getStdIn()`, to get access to a `GenericReader`\nobject that we can use to read data from `stdin`.\n\nIn the example below, we are creating a small buffer capable of holding 20 characters. Then, we try to read\nthe data from the `stdin` with the `readUntilDelimiterOrEof()` method, and save this data into the `buffer` object.\nAlso notice that we are reading the data from the `stdin` until we hit a new line character (`'\\n'`).\n\nIf you execute this program, you will notice that it stops the execution, ands start to wait indefinitely\nfor some input from the user. In other words, you need to type your name into the terminal, and then, you press Enter to\nsend your name to `stdin`. After you send your name to `stdin`, the program reads this input, and continues with the execution,\nby printing the given name to `stdout`. In the example below, I typed my name (Pedro) into the terminal, and then, pressed Enter.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst stdin = std.io.getStdIn().reader();\npub fn main() !void {\n    try stdout.writeAll(\"Type your name\\n\");\n    var buffer: [20]u8 = undefined;\n    @memset(buffer[0..], 0);\n    _ = try stdin.readUntilDelimiterOrEof(buffer[0..], '\\n');\n    try stdout.print(\"Your name is: {s}\\n\", .{buffer});\n}\n```\n:::\n\n\n\n\n```\nType your name\nYour name is: Pedro\n\n```\n\n\n### The *standard error*\n\nThe *standard error* (a.k.a. the `stderr`) works exactly the same as `stdout` and `stdin`.\nYou just call the `getStdErr()` function from the `std.io` module, and you get the file descriptor to `stderr`.\nIdeally, you should write only error or warning messages to `stderr`, because this is\nthe purpose of this channel.\n\n\n\n\n\n## Buffered IO\n\nAs we described at @sec-io-basics, input/output (IO) operations are made directly by the operating system.\nIt is the OS that manages the IO resource that you want to use for your IO operations.\nThe consequence of this fact is that IO operations are heavily based on system calls (i.e. calling the operating system directly).\n\nJust to be clear, there is nothing particularly wrong with system calls. We use them all the time on\nany serious codebase written in any low-level programming language. However, system calls are\nalways orders of magnitude slower than many different types of operations.\n\nSo is perfectly fine to use a system call once in a while. But when these system calls are used often,\nyou can clearly notice most of the time the loss of performance in your application. So, the good rule of thumbs\nis to use a system call only when it is needed, and also, only in infrequent situations, to reduce\nthe number of system calls performed to a minimum.\n\n\n### Understanding how buffered IO works\n\nBuffered IO is a strategy to achieve better performance. It is used to reduce the number of system calls made by IO operations, and, as\nconsequence, achieve a much higher performance. At @fig-unbuffered-io and @fig-buffered-io you can find two different diagrams\nwhich presents the difference between read operations performed in an unbuffered IO environment versus a buffered IO environment.\n\nTo give a better context to these diagrams, let's suppose that we have a text file that contains the famous Lorem ipsum text[^lorem]\nin our filesystem. Let's also suppose that these diagrams at @fig-unbuffered-io and @fig-buffered-io\nare showing the read operations that we are performing to read the Lorem ipsum text from this text file.\nThe first thing you will notice when looking at these diagrams, is that in an unbuffered environment\nthe read operations leads to many system calls.\nMore precisely, in the diagram exposed at @fig-unbuffered-io we get one system call per each byte that we read from the text file.\nOn the other hand, at @fig-buffered-io we have only one system call at the very beginning.\n\nWhen we use a buffered IO system, at the first read operation we perform, instead of sending one single byte directly\nto our program, the OS first sends a chunk of bytes from the file to a buffer object (i.e. an array).\nThis chunk of bytes are cached/stored inside this buffer object.\n\nTherefore, from now on, for every new read operation that you perform, instead of making a new system call to ask\nfor the next byte in the file to the OS, this read operation is redirected to the buffer object, that have\nthis next byte already cached and ready to go.\n\n\n[^lorem]: <https://www.lipsum.com/>.\n\n\n![Unbuffered IO](./../Figures/unbuffered-io.png){#fig-unbuffered-io width=60%}\n\n![Buffered IO](./../Figures/buffered-io.png){#fig-buffered-io}\n\n\n\nThis is the basic logic behind buffered IO systems. The size of the buffer object depends on multiple factors. But it is usually\nequal to the size of a full page of memory (4096 bytes). If we follow this logic, then, the OS reads the first 4096 bytes\nof the file and caches it into the buffer object. As long as your program does not consume all of these 4096 bytes from the buffer,\nyou will not create new system calls.\n\nHowever, as soon as you consume all of these 4096 bytes from the buffer, it means that there is no bytes left in the buffer.\nIn this situation, a new system call is made to ask the OS to send the next 4096 bytes in the file, and once again,\nthese bytes are cached into the buffer object, and the cycle starts once again.\n\n\n### Buffered IO across different languages\n\nIO operations made through a `FILE` pointer in C are buffered\nby default, so, at least in C, you don't need to worry about this subject. But in contrast, IO operations in both Rust and Zig are not\nbuffered depending on which functions from the standard libraries that you are using.\n\nFor example, in Rust, buffered IO is implemented through the `BufReader` and `BufWriter` structs, while in Zig, it is implemented\nthrough the `BufferedReader` and `BufferedWriter` structs.\nSo any IO operation that you perform through the `GenericWriter` and `GenericReader` objects\nthat I presented at @sec-writer-reader are not buffered, which means that these objects\nmight create a lot of system calls depending on the situation.\n\n\n### Using buffered IO in Zig\n\nUsing buffered IO in Zig is actually very easy. All you have to do is to just\ngive the `GenericWriter` object to the `bufferedWriter()` function, or, to give the `GenericReader`\nobject to the `bufferedReader()` function. These functions come from the `std.io` module,\nand they will construct the `BufferedWriter` or `BufferedReader` object for you.\n\nAfter you create this new `BufferedWriter` or `BufferedReader` object, you can call the `writer()`\nor `reader()` method of this new object, to get access to a new (and buffered) generic reader or\ngeneric writer.\n\nLet's describe the process once again. Every time that you have a file descriptor object, you first get the generic writer or generic reader\nobject from it, by calling the `writer()` or `reader()` methods of this file descriptor object.\nThen, you provide this generic writer or generic reader to the `bufferedWriter()` or `bufferedReader()`\nfunction, which creates a new `BufferedWriter` or `BufferedReader` object. Then, you call\nthe `writer()` or `reader()` methods of this buffered writer or buffered reader object,\nwhich gives you access to a generic writer or a generic reader object that is buffered.\n\nTake this program as an example. This program is demonstrating the process exposed at @fig-buffered-io.\nWe are simply opening a text file that contains the Lorem ipsum text, and then, we create a buffered IO reader object\nat `bufreader`, and we use this `bufreader` object to read the contents of this file into a buffer object, then,\nwe end the program by printing this buffer to `stdout`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar file = try std.fs.cwd().openFile(\n    \"ZigExamples/file-io/lorem.txt\", .{}\n);\ndefer file.close();\nvar buffered = std.io.bufferedReader(file.reader());\nvar bufreader = buffered.reader();\n\nvar buffer: [1000]u8 = undefined;\n@memset(buffer[0..], 0);\n\n_ = try bufreader.readUntilDelimiterOrEof(\n    buffer[0..], '\\n'\n);\ntry stdout.print(\"{s}\\n\", .{buffer});\n```\n:::\n\n\n\n\n```\nLorem ipsum dolor sit amet, consectetur\nadipiscing elit. Sed tincidunt erat sed nulla ornare, nec\naliquet ex laoreet. Ut nec rhoncus nunc. Integer magna metus,\nultrices eleifend porttitor ut, finibus ut tortor. Maecenas\nsapien justo, finibus tincidunt dictum ac, semper et lectus.\nVivamus molestie egestas orci ac viverra. Pellentesque nec\narcu facilisis, euismod eros eu, sodales nisl. Ut egestas\nsagittis arcu, in accumsan sapien rhoncus sit amet. Aenean\nneque lectus, imperdiet ac lobortis a, ullamcorper sed massa.\nNullam porttitor porttitor erat nec dapibus. Ut vel dui nec\nnulla vulputate molestie eget non nunc. Ut commodo luctus ipsum,\nin finibus libero feugiat eget. Etiam vel ante at urna tincidunt\nposuere sit amet ut felis. Maecenas finibus suscipit tristique.\nDonec viverra non sapien id suscipit.\n```\n\nDespite being a buffered IO reader, this `bufreader` object is similar to any other `GenericReader` object,\nand have the exact same methods. So, although these two types of objects perform very different IO operations,\nthey have the same interface, so you, the programmer, can interchangeably use them\nwithout the need to change anything in your source code.\nSo a buffered IO reader or a buffered IO writer objects have the same methods than its generic and unbuffered brothers,\ni.e. the generic reader and generic writer objects that I presented at @sec-writer-reader.\n\n::: {.callout-tip}\nIn general, you should always use a buffered IO reader or a buffered IO writer object to perform\nIO operations in Zig. Because they deliver better performance to your IO operations.\n:::\n\n\n## Filesystem basics\n\nNow that we have discussed the basics around Input/Output operations in Zig, we need to\ntalk about the basics around filesystems, which is another core part of any operating system.\nAlso, filesystems are related to input/output, because the files that we store and create in our\ncomputer are considered an IO resource, as we described at @sec-file-descriptor.\n\n\n### The concept of current working directory (CWD)\n\nThe working directory is the folder on your computer where you are currently rooted at.\nIn other words, it is the folder that your program is currently looking at.\nTherefore, whenever you are executing a program, this program is always working with\na specific folder on your computer. It is always in this folder that the program will initially\nlook for the files you require, and it is also in this folder that the program\nwill initially save all the files you ask it to save.\n\nThe working directory is determined by the folder from which you invoke your program\nin the terminal. In other words, if you are in the terminal of your OS, and you\nexecute a binary file (i.e. a program) from this terminal, the folder to which your terminal\nis pointing at is the current working directory of your program that is being executed.\n\nAt @fig-cwd we have an example of me executing a program from the terminal. We are executing\nthe program outputted by the `zig` compiler by compiling the Zig module named `hello.zig`.\nThe CWD in this case is the `zig-book` folder. In other words, while the `hello.zig` program\nis executing, it will be looking at the `zig-book` folder, and any file operation that we perform\ninside this program, will be using this `zig-book` folder as the \"starting point\", or, as the \"central focus\".\n\n![Executing a program from the terminal](./../Figures/cwd.png){#fig-cwd}\n\nJust because we are rooted inside a particular folder (in the case of @fig-cwd, the `zig-book` folder) of our computer,\nit doesn't mean that we cannot access or write resources in other locations of our computer.\nThe current working directory (CWD) mechanism just defines where your program will look first\nfor the files you ask for. This does not prevent you from accessing files that are located\nelsewhere on your computer. However, to access any file that is in a folder other than your\ncurrent working directory, you must provide a path to that file or folder.\n\n\n### The concept of paths\n\nA path is essentially a location. It points to a location in your filesystem. We use\npaths to describe the location of files and folders in our computer.\nOne important aspect about paths is that they are always written inside strings,\ni.e. they are always provided as text values.\n\nThere are two types of paths that you can provide to any program in any OS: a relative path, or an absolute path.\nAbsolute paths are paths that start at the root of your filesystem, and go all the way to the file name or the specific folder\nthat you are referring to. This type of path is called absolute, because it points to an unique and absolute location on your computer.\nThat is, there is no other existing location on your computer that corresponds to this path. It is an unique identifier.\n\nIn Windows, an absolute path is a path that starts with a hard disk identifier (e.g. `C:/Users/pedro`).\nOn the other hand, absolute paths in Linux and macOS, are paths that start with a forward slash character (e.g. `/usr/local/bin`).\nNotice that a path is composed by \"segments\". Each segment is connected to each other by a slash character (`\\` or `/`).\nOn Windows, the backward slash (`\\`) is normally used to connect the path segments. While on Linux and macOS, the forward\nslash (`/`) is the character used to connect path segments.\n\nA relative path is a path that start at the CWD. In other words, a relative path is\n\"relative to the CWD\". The path used to access the `hello.zig` file at @fig-cwd is an example of a relative path. This path\nis reproduced below. This path begins at the CWD, which in the context of @fig-cwd, is the `zig-book` folder,\nthen, it goes to the `ZigExamples` folder, then, into `zig-basics`, then, to the `hello.zig` file.\n\n```\nZigExamples/zig-basics/hello_world.zig\n```\n\n\n### Path wildcards\n\nWhen providing paths, especially relative paths, you have the option of using a *wildcard*.\nThere are two commonly used *wildcards* in paths, which are \"one period\" (.) and \"two periods\" (..).\nIn other words, these two specific characters have special meanings when used in paths,\nand can be used on any operating system (Mac, Windows, Linux, etc.). That is, they\nare \"cross platform\".\n\nThe \"one period\" represents an alias for the current directory.\nThis means that the relative paths `\"./Course/Data/covid.csv\"` and `\"Course/Data/covid.csv\"` are equivalent.\nOn the other hand, the \"two periods\" refers to the previous directory.\nFor example, the path `\"Course/..\"` is equivalent to the path `\".\"`, that is, the current working directory.\n\nTherefore, the path `\"Course/..\"` refers to the folder before the `Course` folder.\nAs another example, the path `\"src/writexml/../xml.cpp\"` refers to the file `xml.cpp`\nthat is inside the folder before the `writexml` folder, which in this example is the `src` folder.\nTherefore, this path is equivalent to `\"src/xml.cpp\"`.\n\n\n\n\n## The CWD handler\n\nIn Zig, filesystem operations are usually made through a directory handler object.\nA directory handler in Zig is an object of type `Dir`, which is an object that describes\na particular folder in the filesystem of our computer.\nYou normally create a `Dir` object, by calling the `std.fs.cwd()` function.\nThis function returns a `Dir` object that points to (or, that describes) the\ncurrent working directory (CWD).\n\nThrough this `Dir` object, you can create new files, or modify, or read existing ones that are\ninside your CWD. In other words, a `Dir` object is the main entrypoint in Zig to perform\nmultiple types of filesystem operations.\nIn the example below, we are creating this `Dir` object, and storing it\ninside the `cwd` object. Although we are not using this object at this code example,\nwe are going to use it a lot over the next examples.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\n_ = cwd;\n```\n:::\n\n\n\n\n\n\n\n\n\n\n\n## File operations\n\n### Creating files {#sec-creating-files}\n\nWe create new files by using the `createFile()` method from the `Dir` object.\nJust provide the name of the file that you want to create, and this function will\ndo the necessary steps to create such file. You can also provide a relative path to this function,\nand it will create the file by following this path, which is relative to the CWD.\n\nThis function might return an error, so, you should use `try`, `catch`, or any of the other methods presented\nat @sec-error-handling to handle the possible error. But if everything goes well,\nthis `createFile()` method returns a file descriptor object (i.e. a `File` object) as result,\nthrough which you can add content to the file with the IO operations that I presented before.\n\nTake this code example below. In this example, we are creating a new text file\nnamed `foo.txt`. If the function `createFile()` succeeds, the object named `file` will contain a file descriptor\nobject, which we can use to write (or add) new content to the file, like we do in this example, by using\na buffered writer object to write a new line of text to the file.\n\nNow, a quick note, when we create a file descriptor object in C, by using a C function like `fopen()`, we must always close the file\nat the end of our program, or, as soon as we complete all operations that we wanted to perform\non the file. In Zig, this is no different. So everytime we create a new file, this file remains\n\"open\", waiting for some operation to be performed. As soon as we are done with it, we always have\nto close this file, to free the resources associated with it.\nIn Zig, we do this by calling the method `close()` from the file descriptor object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.createFile(\"foo.txt\", .{});\n// Don't forget to close the file at the end.\ndefer file.close();\n// Do things with the file ...\nvar fw = file.writer();\n_ = try fw.writeAll(\n    \"Writing this line to the file\\n\"\n);\n```\n:::\n\n\n\n\n\nSo, in this example we not only have created a file into the filesystem,\nbut we also wrote some data into this file, using the file descriptor object\nreturned by `createFile()`. If the file that you are trying to create\nalready exists in your filesystem, this `createFile()` call will\noverwrite the contents of the file, or, in other words, it will\nin erase all the contents of the existing file.\n\nIf you don't want this to happen, meaning, that you don't want to overwrite\nthe contents of the existing file, but you want to write data to this file anyway\n(i.e. you want to append data to the file), you should use the `openFile()`\nmethod from the `Dir` object.\n\nAnother important aspect about `createFile()` is that this method creates a file\nthat is not open to read operations by default. It means that you cannot read this file.\nYou are not allowed to.\nSo for example, you might want to write some stuff into this file at the beginning of the execution\nof your program. Then, at a future point in your program you might need to read what you\nwrote in this file. If you try to read data from this file, you will likely\nget a `NotOpenForReading` error as result.\n\n\nBut how can you overcome this barrier? How can you create a file that is open\nto read operations? All you have to do, is to set the `read` flag to true\nin the second argument of `createFile()`. When you set this flag to true,\nthen the file get's create with \"read permissions\", and, as consequence,\na program like this one below becomes valid:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.createFile(\n    \"foo.txt\",\n    .{ .read = true }\n);\ndefer file.close();\n\nvar fw = file.writer();\n_ = try fw.writeAll(\"We are going to read this line\\n\");\n\nvar buffer: [300]u8 = undefined;\n@memset(buffer[0..], 0);\ntry file.seekTo(0);\nvar fr = file.reader();\n_ = try fr.readAll(buffer[0..]);\ntry stdout.print(\"{s}\\n\", .{buffer});\n```\n:::\n\n\n\n\n\n```\nWe are going to read this line\n```\n\n\nIf you are not familiar with position indicators, you might not recognize the method\n`seekTo()`. If that is your case, do not worry,\nwe are going to talk more about this method at @sec-indicators. But essentially\nthis method is moving the position indicator back to the beginning of the file,\nso that we can read the contents of the file from the beginning.\n\n\n### Opening files and appending data to it\n\nOpening files is easy. Just use the `openFile()` method instead of `createFile()`.\nIn the first argument of `openFile()` you provide the path to the file that\nyou want to open. Then, on the second argument you provide the flags (or, the options)\nthat dictates how the file is opened.\n\nYou can see the full list of options for `openFile()` by visiting the documentation for\n[`OpenFlags`](https://ziglang.org/documentation/master/std/#std.fs.File.OpenFlags)[^oflags].\nBut the main flag that you will most certainly use is the `mode` flag.\nThis flag specifies the IO mode that the file will be using when it get's opened.\nThere are three IO modes, or, three values that you can provide to this flag, which are:\n\n- `read_only`, allows only read operations on the file. All write operations are blocked.\n- `write_only`, allows only write operations on the file. All read operations are blocked. \n- `read_write`, allows both write and read operations on the file.\n\n[^oflags]: <https://ziglang.org/documentation/master/std/#std.fs.File.OpenFlags>\n\nThese modes are similar to the modes that you provide to the `mode` argument of the\n`open()` Python built-in function[^py-open], or, the `mode` argument of the\n`fopen()` C function[^c-open].\nIn the code example below, we are opening the `foo.txt` text file with a `write_only` mode,\nand appending a new line of text to the end of the file. We use `seekFromEnd()` this time\nto guarantee that we are going to append the text to the end of the file. Once again, methods\nsuch as `seekFromEnd()` are described in more depth at @sec-indicators.\n\n[^py-open]: <https://docs.python.org/3/tutorial/inputoutput.html#reading-and-writing-files>\n[^c-open]: <https://www.tutorialspoint.com/c_standard_library/c_function_fopen.htm>\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.openFile(\n    \"foo.txt\", .{ .mode = .write_only }\n);\ndefer file.close();\ntry file.seekFromEnd(0);\nvar fw = file.writer();\n_ = try fw.writeAll(\"Some random text to write\\n\");\n```\n:::\n\n\n\n\n\n### Deleting files\n\nSometimes, we just need to delete/remove the files that we have.\nTo do that, we use the `deleteFile()` method. You just provide the path of the\nfile that you want to delete, and this method will try to delete the file located\nat this path.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.deleteFile(\"foo.txt\");\n```\n:::\n\n\n\n\n### Copying files\n\nTo copy existing files, we use the `copyFile()` method. The first argument in this method\nis the path to the file that you want to copy. The second argument is a `Dir` object, i.e. a directory handler,\nmore specifically, a `Dir` object that points to the folder in your computer where you want to\ncopy the file to. The third argument is the new path of the file, or, in other words, the new location\nof the file. The fourth argument is the options (or flags) to be used in the copy operation.\n\nThe `Dir` object that you provide as input to this method will be used to copy the file to\nthe new location. You may create this `Dir` object before calling the `copyFile()` method.\nMaybe you are planning to copy the file to a completely different location in your computer,\nso it might be worth to create a directory handler to that location. But if you are copying the\nfile to a subfolder of your CWD, then, you can just simply pass the CWD handler to this argument.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.copyFile(\n    \"foo.txt\",\n    cwd,\n    \"ZigExamples/file-io/foo.txt\",\n    .{}\n);\n```\n:::\n\n\n\n\n\n### Read the docs!\n\nThere are some other useful methods for file operations available at `Dir` objects,\nsuch as the `writeFile()` method, but I recommend you to read the docs for the\n[`Dir` type](https://ziglang.org/documentation/master/std/#std.fs.Dir)[^zig-dir]\nto explore the other available methods, since I already talked too much about them.\n\n\n[^zig-dir]: <https://ziglang.org/documentation/master/std/#std.fs.Dir>\n\n\n\n\n## Position indicators {#sec-indicators}\n\nA position indicator is like a type of cursor, or, an index. This \"index\" identifies the current\nlocation in the file (or, in the data stream) that the file descriptor object that you have\nis currently looking at.\nWhen you create a file descriptor, the position indicator starts at the beginning of the file,\nor, at the beginning of the stream. When you read from or write into the file (or socket, or data stream, etc.)\ndescribed by this file descriptor object, you end up moving the position indicator.\n\nIn other words, any IO operation have a common side effect, which is to move the position indicator.\nFor example, suppose that we have a file of 300 bytes total in size. If you\nread 100 bytes from the file, then, the position indicator moves 100 bytes forward. If you try\nto write 50 bytes into this same file, these 50 bytes will be written from the current\nposition indicated by the position indicator. Since the indicator is at a 100 bytes forward from\nthe beginning of the file, these 50 bytes would be written in the middle of the file.\n\nThis is why we have used the `seekTo()` method at the last code example presented at @sec-creating-files.\nWe have used this method to move the position indicator back to the beginning of the file, which\nwould make sure that we would write the text that we wanted to write from the beginning of the file,\ninstead of writing it from the middle of the file. Because before the write operation, we had\nperformed a read operation, which means that the position indicator was moved in this read operation.\n\nThe position indicators of a file descriptor object can be changed (or altered) by using the\n\"seek\" methods from this file descriptor, which are: `seekTo()`, `seekFromEnd()` and `seekBy()`.\nThese methods have the same effect, or, the same responsibility that the\n[`fseek()`](https://en.cppreference.com/w/c/io/fseek)[^c-fseek] C function.\n\n[^c-fseek]: <https://en.cppreference.com/w/c/io/fseek>\n\n\nConsidering that `offset` refers to the index that you provide as input to these \"seek\" methods,\nthe bullet points below summarises what is the effect of each of these methods.\nAs a quick note, in the case of `seekFromEnd()` and `seekBy()`, the `offset` provided can be either a\npositive or a negative index.\n\n- `seekTo()` will move the position indicator to the location that is `offset` bytes from the beginning of the file.\n- `seekFromEnd()` will move the position indicator to the location that is `offset` bytes from the end of the file.\n- `seekBy()` will move the position indicator to the location that is `offset` bytes from the current position in the file.\n\n\n\n\n\n\n\n## Directory operations\n\n### Iterating through the files in a directory\n\nOne of the most classic tasks related to filesystem is to be able\nto iterate through the existing files in a directory. To iterate over the\nfiles in a directory, we need to create an iterator object.\n\nYou can produce such iterator object by using either the `iterate()` or `walk()` methods\nof a `Dir` object. Both methods return an iterator object as output, which you can advance by using the\n`next()` method. The difference between these methods, is that `iterate()` returns a non-recursive iterator,\nwhile `walk()` does. It means that the iterator returned by `walk()` will not only iterate through\nthe files available in the current directory, but also, through the files from any subdirectory found\ninside the current directory.\n\nIn the example below, we are displaying the names of the files stored inside the\ndirectory `ZigExamples/file-io`. Notice that we had to open this directory through\nthe `openDir()` function. Also notice that we provided the flag `iterate` in the\nsecond argument of `openDir()`. This flag is important, because without this flag,\nwe would not be allowed to iterate through the files in this directory.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst dir = try cwd.openDir(\n    \"ZigExamples/file-io/\",\n    .{ .iterate = true }\n);\nvar it = dir.iterate();\nwhile (try it.next()) |entry| {\n    try stdout.print(\n        \"File name: {s}\\n\",\n        .{entry.name}\n    );\n}\n```\n:::\n\n\n\n\n```\nFile name: create_file_and_write_toit.zig\nFile name: create_file.zig\nFile name: lorem.txt\nFile name: iterate.zig\nFile name: delete_file.zig\nFile name: append_to_file.zig\nFile name: user_input.zig\nFile name: foo.txt\nFile name: create_file_and_read.zig\nFile name: buff_io.zig\nFile name: copy_file.zig\n```\n\n\n### Creating new directories\n\nThere are two methods that are important when it comes to\ncreating directories, which are `makeDir()` and `makePath()`.\nThe difference between these two methods is that `makeDir()` can\nonly create one single directory in the current directory in each call,\nwhile `makePath()` is capable of recursively create subdirectories in the same call.\n\n\nThis is why the name of this method is \"make path\". It will create as many\nsubdirectories as necessary to create the path that you provided as input.\nSo, if you provide the path `\"sub1/sub2/sub3\"` as input to this method,\nit will create three different subdirectories, `sub1`, `sub2` and `sub3`,\nwithin the same function call. In contrast, if you provided such path\nas input to `makeDir()`, you would likely get an error as result, since\nthis method can only create a single subdirectory.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.makeDir(\"src\");\ntry cwd.makePath(\"src/decoders/jpg/\");\n```\n:::\n\n\n\n\n### Deleting directories\n\nTo delete a directory, just provide the path to the directory that you want to delete\nas input to the `deleteDir()` method from a `Dir` object. In the example below,\nwe are deleting the `src` directory that we have just created in the previous example.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.deleteDir(\"src\");\n```\n:::\n\n\n\n\n\n## Conclusion\n\nIn this chapter, I have described how to perform in Zig the most common filesystem and IO operations.\nBut you might feel the lack of some other, less common, operation in this chapter, such as: how to rename files,\nor how to open a directory, or how to create symbolic links, or how to use `access()` to test if a particular\npath exists in your computer. But for all of these less common tasks, I recommend you to read\nthe documentation of the [`Dir` type](https://ziglang.org/documentation/master/std/#std.fs.Dir)[^zig-dir]\n, since you can find a good description of these cases there.\n\n\n\n\n",
+    "supporting": [
+      "12-file-op_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/index/execute-results/html.json b/_freeze/index/execute-results/html.json
index 0d36ad04..542a03cc 100644
--- a/_freeze/index/execute-results/html.json
+++ b/_freeze/index/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "0d9977ad882089aad1460aa86ce0e48e",
+  "hash": "7eedbe34469c0f2c200651bc420da095",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy an eBook or a physical copy\nof the book on Amazon:\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e. it is open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria have a bachelor degree in Economics from Federal University of Ouro Preto - Brazil.\nCurrently, he is a Data Platform Engineer at [Blip](https://www.blip.ai/en/)[^blip], and\nan Associate Developer for Apache Spark 3.0 certified by Databricks.\n\n[^blip]: <https://www.blip.ai/en/>\n\n\nThe author have more than 4 years of experience in the data industry. Developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nbrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer that loves to\nlearn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2024 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n\n- System version: Linux, 6.8.0-49-generic, NA, x86_64.\n- Zig version: 0.14.0-dev.2371+c013f45ad.\n- Quarto version: 1.5.57.\n\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang)\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy an eBook or a physical copy\nof the book on Amazon:\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e. it is open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.\nCurrently, he is a Data Platform Engineer at [Blip](https://www.blip.ai/en/)[^blip], and\na Databricks Certified Associate Developer for Apache Spark 3.0.\n\n[^blip]: <https://www.blip.ai/en/>\n\n\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nBrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer who loves to learn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2024 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n\n- System version: Linux, 6.8.0-52-generic, NA, x86_64.\n- Zig version: 0.14.0-dev.2371+c013f45ad.\n- Quarto version: 1.5.57.\n\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang)\n",
+    "supporting": [
+      "index_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/docs/Chapters/01-zig-weird.html b/docs/Chapters/01-zig-weird.html
index ac94c65e..b091a3de 100644
--- a/docs/Chapters/01-zig-weird.html
+++ b/docs/Chapters/01-zig-weird.html
@@ -405,11 +405,14 @@ <h3 data-number="1.2.1" class="anchored" data-anchor-id="sec-project-files"><spa
 <p>Examples of build systems are CMake, GNU Make, GNU Autoconf and Ninja, which are used to build complex C and C++ projects. With these systems, you can write scripts, which are called “build scripts”. They simply are scripts that describes the necessary steps to compile/build your project.</p>
 <p>However, these are separate tools, that do not belong to C/C++ compilers, like <code>gcc</code> or <code>clang</code>. As a result, in C/C++ projects, you have not only to install and manage your C/C++ compilers, but you also have to install and manage these build systems separately.</p>
 <p>In Zig, we don’t need to use a separate set of tools to build our projects, because a build system is embedded inside the language itself. Therefore, Zig contains a native build system in it, and we can use this build system to write small scripts in Zig, which describes the necessary steps to build/compile our Zig project<a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>. So, everything you need to build a complex Zig project is the <code>zig</code> compiler, and nothing more.</p>
-<p>The second generated file (<code>build.zig.zon</code>) is the Zig package manager configuration file, where you can list and manage the dependencies of your project. Yes, Zig has a package manager (like <code>pip</code> in Python, <code>cargo</code> in Rust, or <code>npm</code> in Javascript) called Zon, and this <code>build.zig.zon</code> file is similar to the <code>package.json</code> file in Javascript projects, or, the <code>Pipfile</code> file in Python projects, or the <code>Cargo.toml</code> file in Rust projects.</p>
+<p>The second generated file (<code>build.zig.zon</code>) is a JSON-like file, in which you can describe your project, and also, declare a set of dependencies of your project that you want to fetch from the internet. In other words, you can use this <code>build.zig.zon</code> file to include a list of external libraries in your project.</p>
+<p>One possible way to include an external Zig library in your project, is to manually build and install the library in your system, and just link your source code with the library at the build step of your project.</p>
+<p>However, if this external Zig library is available on GitHub for example, and it has a valid <code>build.zig.zon</code> file in root folder of the project, which describes the project, you can easily include this library in your project by simply listing this external library in your <code>build.zig.zon</code> file.</p>
+<p>In other words, this <code>build.zig.zon</code> file works similarly to the <code>package.json</code> file in Javascript projects, or the <code>Pipfile</code> file in Python projects, or the <code>Cargo.toml</code> file in Rust projects. You can read more about this specific file in a couple of articles on the internet<a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a><a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a>, and you can also see the expected schema for this <code>build.zig.zon</code> file in a documentation file inside the official repository of Zig<a href="#fn4" class="footnote-ref" id="fnref4" role="doc-noteref"><sup>4</sup></a>.</p>
 </section>
 <section id="sec-root-file" class="level3" data-number="1.2.2">
 <h3 data-number="1.2.2" class="anchored" data-anchor-id="sec-root-file"><span class="header-section-number">1.2.2</span> The file <code>root.zig</code></h3>
-<p>Let’s take a look into the <code>root.zig</code> file. You might have noticed that every line of code with an expression ends with a semicolon (<code>;</code>). This follows the syntax of a C-family programming language<a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a>.</p>
+<p>Let’s take a look into the <code>root.zig</code> file. You might have noticed that every line of code with an expression ends with a semicolon (<code>;</code>). This follows the syntax of a C-family programming language<a href="#fn5" class="footnote-ref" id="fnref5" role="doc-noteref"><sup>5</sup></a>.</p>
 <p>Also, notice the <code>@import()</code> call at the first line. We use this built-in function to import functionality from other Zig modules into our current module. This <code>@import()</code> function works similarly to the <code>#include</code> pre-processor in C or C++, or, to the <code>import</code> statement in Python or Javascript code. In this example, we are importing the <code>std</code> module, which gives you access to the Zig Standard Library.</p>
 <p>In this <code>root.zig</code> file, we can also see how assignments (i.e.&nbsp;creating new objects) are made in Zig. You can create a new object in Zig by using the following syntax <code>(const|var) name = value;</code>. In the example below, we are creating two constant objects (<code>std</code> and <code>testing</code>). At <a href="#sec-assignments" class="quarto-xref"><span>Section 1.4</span></a> we talk more about objects in general.</p>
 <div class="cell">
@@ -430,14 +433,15 @@ <h3 data-number="1.2.2" class="anchored" data-anchor-id="sec-root-file"><span cl
 <h3 data-number="1.2.3" class="anchored" data-anchor-id="sec-main-file"><span class="header-section-number">1.2.3</span> The <code>main.zig</code> file</h3>
 <p>Now that we have learned a lot about Zig’s syntax from the <code>root.zig</code> file, let’s take a look at the <code>main.zig</code> file. A lot of the elements we saw in <code>root.zig</code> are also present in <code>main.zig</code>. But there are some other elements that we haven’t seen yet, so let’s dive in.</p>
 <p>First, look at the return type of the <code>main()</code> function in this file. We can see a small change. The return type of the function (<code>void</code>) is accompanied by an exclamation mark (<code>!</code>). This exclamation mark tells us that this <code>main()</code> function might return an error.</p>
-<p>In this example, the <code>main()</code> function can either return <code>void</code> or return an error. This is an interesting feature of Zig. If you write a function and something inside of the body of this function might return an error then you are forced to:</p>
+<p>Is worth noting that, a <code>main()</code> function in Zig is allowed to return nothing (<code>void</code>), or an unsigned 8-bit integer (<code>u8</code>) value, or an error. In other words, you can write your <code>main()</code> function in Zig to return essentially nothing (<code>void</code>), or, if you prefer, you can also write a more C-like <code>main()</code> function, which returns an integer value that usually serves as a “status code” for the process.</p>
+<p>In this example, the return type annotation of <code>main()</code> indicates that this function can either return nothing (<code>void</code>), or return an error. This exclamation mark in the return type annotation is an interesting and powerful feature of Zig. In summary, if you write a function and something inside the body of this function might return an error, then, you are forced to:</p>
 <ul>
-<li>either add the exclamation mark to the return type of the function and make it clear that this function might return an error</li>
-<li>explicitly handle this error inside the function</li>
+<li>either add the exclamation mark to the return type of the function and make it clear that this function might return an error.</li>
+<li>explicitly handle this error inside the function.</li>
 </ul>
 <p>In most programming languages, we normally handle (or deal with) an error through a <em>try catch</em> pattern. Zig does have both <code>try</code> and <code>catch</code> keywords. But they work a little differently than what you’re probably used to in other languages.</p>
 <p>If we look at the <code>main()</code> function below, you can see that we do have a <code>try</code> keyword on the 5th line. But we do not have a <code>catch</code> keyword in this code. In Zig, we use the <code>try</code> keyword to execute an expression that might return an error, which, in this example, is the <code>stdout.print()</code> expression.</p>
-<p>In essence, the <code>try</code> keyword executes the expression <code>stdout.print()</code>. If this expression returns a valid value, then, the <code>try</code> keyword does nothing. It only passes the value forward. But if the expression does return an error, then, the <code>try</code> keyword just unwrap the error value, and return this error from the function and also prints the current stack trace to <code>stderr</code>.</p>
+<p>In essence, the <code>try</code> keyword executes the expression <code>stdout.print()</code>. If this expression returns a valid value, then, the <code>try</code> keyword does absolutely nothing. It only passes the value forward. It is like if this <code>try</code> keyword was never there. However, if the expression does return an error, then, the <code>try</code> keyword will unwrap the error value, then, it returns this error from the function and also prints the current stack trace to <code>stderr</code>.</p>
 <p>This might sound weird to you if you come from a high-level language. Because in high-level languages, such as Python, if an error occurs somewhere, this error is automatically returned and the execution of your program will automatically stop even if you don’t want to stop the execution. You are obligated to face the error.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb6"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
@@ -447,9 +451,8 @@ <h3 data-number="1.2.3" class="anchored" data-anchor-id="sec-main-file"><span cl
 <span id="cb6-5"><a href="#cb6-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"Hello, {s}!</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="st">"world"</span><span class="op">}</span>);</span>
 <span id="cb6-6"><a href="#cb6-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>Another thing that you might have noticed in this code example, is that the <code>main()</code> function is marked with the <code>pub</code> keyword. It marks the <code>main()</code> function as a <em>public function</em> from this module.</p>
-<p>Every function in your Zig module is by default private to this Zig module and can only be called from within the module. Unless, you explicitly mark this function as a public function with the <code>pub</code> keyword. This means that the <code>pub</code> keyword in Zig does essentially the opposite of what the <code>static</code> keyword do in C/C++.</p>
-<p>By making a function “public” you allow other Zig modules to access and call it. A calling Zig module imports the module with the <code>@import()</code> built-in. That makes all public functions from the imported module visible.</p>
+<p>Another thing that you might have noticed in this code example, is that the <code>main()</code> function is marked with the <code>pub</code> keyword. It marks the <code>main()</code> function as a <em>public function</em> from this module. Every function in your Zig module is by default private to this Zig module and can only be called from within the module. Unless, you explicitly mark this function as a public function with the <code>pub</code> keyword.</p>
+<p>If you think about it, this <code>pub</code> keyword in Zig does essentially the opposite of what the <code>static</code> keyword do in C/C++. By making a function “public” you allow other Zig modules to access and call this function. A calling Zig module imports another module by using the <code>@import()</code> built-in function, which makes all public functions from the imported module visible to the calling Zig module.</p>
 </section>
 <section id="sec-compile-code" class="level3" data-number="1.2.4">
 <h3 data-number="1.2.4" class="anchored" data-anchor-id="sec-compile-code"><span class="header-section-number">1.2.4</span> Compiling your source code</h3>
@@ -473,7 +476,7 @@ <h3 data-number="1.2.5" class="anchored" data-anchor-id="sec-compile-run-code"><
 </section>
 <section id="important-note-for-windows-users" class="level3" data-number="1.2.6">
 <h3 data-number="1.2.6" class="anchored" data-anchor-id="important-note-for-windows-users"><span class="header-section-number">1.2.6</span> Important note for Windows users</h3>
-<p>First of all, this is a Windows-specific thing, and, therefore, does not apply to other operational systems, such as Linux and MacOs. In summary, if you have a piece of Zig code that includes some global variables whose initialization rely on runtime resources, then, you might have some troubles while trying to compile this Zig code on Windows.</p>
+<p>First of all, this is a Windows-specific thing, and, therefore, does not apply to other operating systems, such as Linux and macOs. In summary, if you have a piece of Zig code that includes some global variables whose initialization rely on runtime resources, then, you might have some troubles while trying to compile this Zig code on Windows.</p>
 <p>An example of that is accessing the <code>stdout</code> (i.e.&nbsp;the <em>standard output</em> of your system), which is usually done in Zig by using the expression <code>std.io.getStdOut()</code>. Thus, if you use this expression to instantiate a global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows, with a “unable to evaluate comptime expression” error message.</p>
 <p>This failure in the compilation process happens because all global variables in Zig are initialized at <em>compile-time</em>. However, operations like accessing the <code>stdout</code> (or opening a file) on Windows depends on resources that are available only at <em>runtime</em> (you will learn more about compile-time versus runtime at <a href="01-memory.html#sec-compile-time" class="quarto-xref"><span>Section 3.1.1</span></a>).</p>
 <p>For example, if you try to compile this code example on Windows, you will likely get the error message exposed below:</p>
@@ -501,7 +504,7 @@ <h3 data-number="1.2.6" class="anchored" data-anchor-id="important-note-for-wind
 <span id="cb16-6"><a href="#cb16-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Hello</code></pre>
-<p>You can read more details about this Windows-specific limitation at a couple of GitHub issues opened at the official Zig repository. More specifically, the issues 17186 <a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a> and 19864 <a href="#fn4" class="footnote-ref" id="fnref4" role="doc-noteref"><sup>4</sup></a>.</p>
+<p>You can read more details about this Windows-specific limitation at a couple of GitHub issues opened at the official Zig repository. More specifically, the issues 17186 <a href="#fn6" class="footnote-ref" id="fnref6" role="doc-noteref"><sup>6</sup></a> and 19864 <a href="#fn7" class="footnote-ref" id="fnref7" role="doc-noteref"><sup>7</sup></a>.</p>
 </section>
 <section id="sec-compile-project" class="level3" data-number="1.2.7">
 <h3 data-number="1.2.7" class="anchored" data-anchor-id="sec-compile-project"><span class="header-section-number">1.2.7</span> Compiling the entire project</h3>
@@ -526,17 +529,17 @@ <h2 data-number="1.3" class="anchored" data-anchor-id="how-to-learn-zig"><span c
 <li>Discord, Slack, Telegram, and others: <a href="https://github.com/ziglang/zig/wiki/Community" class="uri">https://github.com/ziglang/zig/wiki/Community</a>;</li>
 </ul>
 <p>Now, one of the best ways to learn Zig is to simply read Zig code. Try to read Zig code often, and things will become more clear. A C/C++ programmer would also probably give you this same tip. Because this strategy really works!</p>
-<p>Now, where can you find Zig code to read? I personally think that, the best way of reading Zig code is to read the source code of the Zig Standard Library. The Zig Standard Library is available at the <a href="https://github.com/ziglang/zig/tree/master/lib/std"><code>lib/std</code> folder</a><a href="#fn5" class="footnote-ref" id="fnref5" role="doc-noteref"><sup>5</sup></a> on the official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.</p>
+<p>Now, where can you find Zig code to read? I personally think that, the best way of reading Zig code is to read the source code of the Zig Standard Library. The Zig Standard Library is available at the <a href="https://github.com/ziglang/zig/tree/master/lib/std"><code>lib/std</code> folder</a><a href="#fn8" class="footnote-ref" id="fnref8" role="doc-noteref"><sup>8</sup></a> on the official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.</p>
 <p>Also, a great alternative is to read code from other large Zig codebases, such as:</p>
 <ol type="1">
-<li>the <a href="https://github.com/oven-sh/bun">Javascript runtime Bun</a><a href="#fn6" class="footnote-ref" id="fnref6" role="doc-noteref"><sup>6</sup></a>.</li>
-<li>the <a href="https://github.com/hexops/mach">game engine Mach</a><a href="#fn7" class="footnote-ref" id="fnref7" role="doc-noteref"><sup>7</sup></a>.</li>
-<li>a <a href="https://github.com/cgbur/llama2.zig/tree/main">LLama 2 LLM model implementation in Zig</a><a href="#fn8" class="footnote-ref" id="fnref8" role="doc-noteref"><sup>8</sup></a>.</li>
-<li>the <a href="https://github.com/tigerbeetle/tigerbeetle">financial transactions database <code>tigerbeetle</code></a><a href="#fn9" class="footnote-ref" id="fnref9" role="doc-noteref"><sup>9</sup></a>.</li>
-<li>the <a href="https://github.com/Hejsil/zig-clap">command-line arguments parser <code>zig-clap</code></a><a href="#fn10" class="footnote-ref" id="fnref10" role="doc-noteref"><sup>10</sup></a>.</li>
-<li>the <a href="https://github.com/capy-ui/capy">UI framework <code>capy</code></a><a href="#fn11" class="footnote-ref" id="fnref11" role="doc-noteref"><sup>11</sup></a>.</li>
-<li>the <a href="https://github.com/zigtools/zls">Language Protocol implementation for Zig, <code>zls</code></a><a href="#fn12" class="footnote-ref" id="fnref12" role="doc-noteref"><sup>12</sup></a>.</li>
-<li>the <a href="https://github.com/mitchellh/libxev">event-loop library <code>libxev</code></a><a href="#fn13" class="footnote-ref" id="fnref13" role="doc-noteref"><sup>13</sup></a>.</li>
+<li>the <a href="https://github.com/oven-sh/bun">Javascript runtime Bun</a><a href="#fn9" class="footnote-ref" id="fnref9" role="doc-noteref"><sup>9</sup></a>.</li>
+<li>the <a href="https://github.com/hexops/mach">game engine Mach</a><a href="#fn10" class="footnote-ref" id="fnref10" role="doc-noteref"><sup>10</sup></a>.</li>
+<li>a <a href="https://github.com/cgbur/llama2.zig/tree/main">LLama 2 LLM model implementation in Zig</a><a href="#fn11" class="footnote-ref" id="fnref11" role="doc-noteref"><sup>11</sup></a>.</li>
+<li>the <a href="https://github.com/tigerbeetle/tigerbeetle">financial transactions database <code>tigerbeetle</code></a><a href="#fn12" class="footnote-ref" id="fnref12" role="doc-noteref"><sup>12</sup></a>.</li>
+<li>the <a href="https://github.com/Hejsil/zig-clap">command-line arguments parser <code>zig-clap</code></a><a href="#fn13" class="footnote-ref" id="fnref13" role="doc-noteref"><sup>13</sup></a>.</li>
+<li>the <a href="https://github.com/capy-ui/capy">UI framework <code>capy</code></a><a href="#fn14" class="footnote-ref" id="fnref14" role="doc-noteref"><sup>14</sup></a>.</li>
+<li>the <a href="https://github.com/zigtools/zls">Language Protocol implementation for Zig, <code>zls</code></a><a href="#fn15" class="footnote-ref" id="fnref15" role="doc-noteref"><sup>15</sup></a>.</li>
+<li>the <a href="https://github.com/mitchellh/libxev">event-loop library <code>libxev</code></a><a href="#fn16" class="footnote-ref" id="fnref16" role="doc-noteref"><sup>16</sup></a>.</li>
 </ol>
 <p>All these assets are available on GitHub, and this is great, because we can use the GitHub search bar in our advantage, to find Zig code that fits our description. For example, you can always include <code>lang:Zig</code> in the GitHub search bar when you are searching for a particular pattern. This will limit the search to only Zig modules.</p>
 <p>Also, a great alternative is to consult online resources and documentations. Here is a quick list of resources that I personally use from time to time to learn more about the language each day:</p>
@@ -549,9 +552,9 @@ <h2 data-number="1.3" class="anchored" data-anchor-id="how-to-learn-zig"><span c
 <li>Read the code written by one of the Zig core team members: <a href="https://github.com/kubkon" class="uri">https://github.com/kubkon</a>;</li>
 <li>Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <a href="https://www.youtube.com/@ZigSHOWTIME/videos" class="uri">https://www.youtube.com/@ZigSHOWTIME/videos</a>;</li>
 </ul>
-<p>Another great strategy to learn Zig, or honestly, to learn any language you want, is to practice it by solving exercises. For example, there is a famous repository in the Zig community called <a href="https://ziglings.org">Ziglings</a><a href="#fn14" class="footnote-ref" id="fnref14" role="doc-noteref"><sup>14</sup></a> , which contains more than 100 small exercises that you can solve. It is a repository of tiny programs written in Zig that are currently broken, and your responsibility is to fix these programs, and make them work again.</p>
-<p>A famous tech YouTuber known as <em>The Primeagen</em> also posted some videos (at YouTube) where he solves these exercises from Ziglings. The first video is named <a href="https://www.youtube.com/watch?v=OPuztQfM3Fg&amp;t=2524s&amp;ab_channel=TheVimeagen">“Trying Zig Part 1”</a><a href="#fn15" class="footnote-ref" id="fnref15" role="doc-noteref"><sup>15</sup></a>.</p>
-<p>Another great alternative, is to solve the <a href="https://adventofcode.com/">Advent of Code exercises</a><a href="#fn16" class="footnote-ref" id="fnref16" role="doc-noteref"><sup>16</sup></a>. There are people that already took the time to learn and solve the exercises, and they posted their solutions on GitHub as well, so, in case you need some resource to compare while solving the exercises, you can look at these two repositories:</p>
+<p>Another great strategy to learn Zig, or honestly, to learn any language you want, is to practice it by solving exercises. For example, there is a famous repository in the Zig community called <a href="https://ziglings.org">Ziglings</a><a href="#fn17" class="footnote-ref" id="fnref17" role="doc-noteref"><sup>17</sup></a> , which contains more than 100 small exercises that you can solve. It is a repository of tiny programs written in Zig that are currently broken, and your responsibility is to fix these programs, and make them work again.</p>
+<p>A famous tech YouTuber known as <em>The Primeagen</em> also posted some videos (at YouTube) where he solves these exercises from Ziglings. The first video is named <a href="https://www.youtube.com/watch?v=OPuztQfM3Fg&amp;t=2524s&amp;ab_channel=TheVimeagen">“Trying Zig Part 1”</a><a href="#fn18" class="footnote-ref" id="fnref18" role="doc-noteref"><sup>18</sup></a>.</p>
+<p>Another great alternative, is to solve the <a href="https://adventofcode.com/">Advent of Code exercises</a><a href="#fn19" class="footnote-ref" id="fnref19" role="doc-noteref"><sup>19</sup></a>. There are people that already took the time to learn and solve the exercises, and they posted their solutions on GitHub as well, so, in case you need some resource to compare while solving the exercises, you can look at these two repositories:</p>
 <ul>
 <li><a href="https://github.com/SpexGuy/Zig-AoC-Template" class="uri">https://github.com/SpexGuy/Zig-AoC-Template</a>;</li>
 <li><a href="https://github.com/fjebaker/advent-of-code-2022" class="uri">https://github.com/fjebaker/advent-of-code-2022</a>;</li>
@@ -644,7 +647,7 @@ <h3 data-number="1.4.4" class="anchored" data-anchor-id="you-must-mutate-every-v
 </section>
 <section id="sec-primitive-data-types" class="level2" data-number="1.5">
 <h2 data-number="1.5" class="anchored" data-anchor-id="sec-primitive-data-types"><span class="header-section-number">1.5</span> Primitive Data Types</h2>
-<p>Zig have many different primitive data types available for you to use. You can see the full list of available data types at the official <a href="https://ziglang.org/documentation/master/#Primitive-Types">Language Reference page</a><a href="#fn17" class="footnote-ref" id="fnref17" role="doc-noteref"><sup>17</sup></a>.</p>
+<p>Zig have many different primitive data types available for you to use. You can see the full list of available data types at the official <a href="https://ziglang.org/documentation/master/#Primitive-Types">Language Reference page</a><a href="#fn20" class="footnote-ref" id="fnref20" role="doc-noteref"><sup>20</sup></a>.</p>
 <p>But here is a quick list:</p>
 <ul>
 <li>Unsigned integers: <code>u8</code>, 8-bit integer; <code>u16</code>, 16-bit integer; <code>u32</code>, 32-bit integer; <code>u64</code>, 64-bit integer; <code>u128</code>, 128-bit integer.</li>
@@ -817,7 +820,7 @@ <h2 data-number="1.8" class="anchored" data-anchor-id="sec-zig-strings"><span cl
 <span id="cb48-3"><a href="#cb48-3" aria-hidden="true" tabindex="-1"></a><span class="co">// This is a string object:</span></span>
 <span id="cb48-4"><a href="#cb48-4" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> object: []<span class="kw">const</span> <span class="dt">u8</span> = <span class="st">"A string object"</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>Zig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every sequence of bytes you’re working with, but is not really Zig’s job to fix the encoding of your strings (you can use <a href="https://www.gnu.org/software/libiconv/"><code>iconv</code></a><a href="#fn18" class="footnote-ref" id="fnref18" role="doc-noteref"><sup>18</sup></a> for that). Today, most of the text in our modern world, especially on the web, should be UTF-8 encoded. So if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.</p>
+<p>Zig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every sequence of bytes you’re working with, but is not really Zig’s job to fix the encoding of your strings (you can use <a href="https://www.gnu.org/software/libiconv/"><code>iconv</code></a><a href="#fn21" class="footnote-ref" id="fnref21" role="doc-noteref"><sup>21</sup></a> for that). Today, most of the text in our modern world, especially on the web, should be UTF-8 encoded. So if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.</p>
 <p>Let’s take for example the word “Hello”. In UTF-8, this sequence of characters (H, e, l, l, o) is represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this sequence is <code>0x48</code>, <code>0x65</code>, <code>0x6C</code>, <code>0x6C</code>, <code>0x6F</code>. So if I take this sequence of hexadecimal values, and ask Zig to print this sequence of bytes as a sequence of characters (i.e.&nbsp;a string), then, the text “Hello” will be printed into the terminal:</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb49"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb49-1"><a href="#cb49-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
@@ -831,7 +834,7 @@ <h2 data-number="1.8" class="anchored" data-anchor-id="sec-zig-strings"><span cl
 <pre><code>Hello</code></pre>
 </div>
 </div>
-<p>If you want to see the actual bytes that represents a string in Zig, you can use a <code>for</code> loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal value to the terminal. You do that by using a <code>print()</code> statement with the <code>X</code> formatting specifier, like you would normally do with the <a href="https://cplusplus.com/reference/cstdio/printf/"><code>printf()</code> function</a><a href="#fn19" class="footnote-ref" id="fnref19" role="doc-noteref"><sup>19</sup></a> in C.</p>
+<p>If you want to see the actual bytes that represents a string in Zig, you can use a <code>for</code> loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal value to the terminal. You do that by using a <code>print()</code> statement with the <code>X</code> formatting specifier, like you would normally do with the <a href="https://cplusplus.com/reference/cstdio/printf/"><code>printf()</code> function</a><a href="#fn22" class="footnote-ref" id="fnref22" role="doc-noteref"><sup>22</sup></a> in C.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb51"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb51-1"><a href="#cb51-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb51-2"><a href="#cb51-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
@@ -1027,9 +1030,9 @@ <h3 data-number="1.8.4" class="anchored" data-anchor-id="sec-strings-useful-funs
 <h2 data-number="1.9" class="anchored" data-anchor-id="safety-in-zig"><span class="header-section-number">1.9</span> Safety in Zig</h2>
 <p>A general trend in modern low-level programming languages is safety. As our modern world becomes more interconnected with technology and computers, the data produced by all of this technology becomes one of the most important (and also, one of the most dangerous) assets that we have.</p>
 <p>This is probably the main reason why modern low-level programming languages have been giving great attention to safety, especially memory safety, because memory corruption is still the main target for hackers to exploit. The reality is that we don’t have an easy solution for this problem. For now, we only have techniques and strategies that mitigates these problems.</p>
-<p>As Richard Feldman explains on his <a href="https://www.youtube.com/watch?v=jIZpKpLCOiU&amp;ab_channel=GOTOConferences">most recent GOTO conference talk</a><a href="#fn20" class="footnote-ref" id="fnref20" role="doc-noteref"><sup>20</sup></a> , we haven’t figured it out yet a way to achieve <strong>true safety in technology</strong>. In other words, we haven’t found a way to build software that won’t be exploited with 100% certainty. We can greatly reduce the risks of our software being exploited, by ensuring memory safety for example. But this is not enough to achieve “true safety” territory.</p>
-<p>Because even if you write your program in a “safe language”, hackers can still exploit failures in the operational system where your program is running (e.g.&nbsp;maybe the system where your code is running has a “backdoor exploit” that can still affect your code in unexpected ways), or also, they can exploit the features from the architecture of your computer. A recently found exploit that involves memory invalidation through a feature of “memory tags” present in ARM chips is an example of that <span class="citation" data-cites="exploit1">(<a href="../references.html#ref-exploit1" role="doc-biblioref">Kim et al. 2024</a>)</span>.</p>
-<p>The question is: what have Zig and other languages been doing to mitigate this problem? If we take Rust as an example, Rust is, for the most part<a href="#fn21" class="footnote-ref" id="fnref21" role="doc-noteref"><sup>21</sup></a>, a memory safe language by enforcing specific rules to the developer. In other words, the key feature of Rust, the <em>borrow checker</em>, forces you to follow a specific logic when you are writing your Rust code, and the Rust compiler will always complain everytime you try to go out of this pattern.</p>
+<p>As Richard Feldman explains on his <a href="https://www.youtube.com/watch?v=jIZpKpLCOiU&amp;ab_channel=GOTOConferences">most recent GOTO conference talk</a><a href="#fn23" class="footnote-ref" id="fnref23" role="doc-noteref"><sup>23</sup></a> , we haven’t figured it out yet a way to achieve <strong>true safety in technology</strong>. In other words, we haven’t found a way to build software that won’t be exploited with 100% certainty. We can greatly reduce the risks of our software being exploited, by ensuring memory safety for example. But this is not enough to achieve “true safety” territory.</p>
+<p>Because even if you write your program in a “safe language”, hackers can still exploit failures in the operating system where your program is running (e.g.&nbsp;maybe the system where your code is running has a “backdoor exploit” that can still affect your code in unexpected ways), or also, they can exploit the features from the architecture of your computer. A recently found exploit that involves memory invalidation through a feature of “memory tags” present in ARM chips is an example of that <span class="citation" data-cites="exploit1">(<a href="../references.html#ref-exploit1" role="doc-biblioref">Kim et al. 2024</a>)</span>.</p>
+<p>The question is: what have Zig and other languages been doing to mitigate this problem? If we take Rust as an example, Rust is, for the most part<a href="#fn24" class="footnote-ref" id="fnref24" role="doc-noteref"><sup>24</sup></a>, a memory safe language by enforcing specific rules to the developer. In other words, the key feature of Rust, the <em>borrow checker</em>, forces you to follow a specific logic when you are writing your Rust code, and the Rust compiler will always complain everytime you try to go out of this pattern.</p>
 <p>In contrast, the Zig language is not a memory safe language by default. There are some memory safety features that you get for free in Zig, especially in arrays and pointer objects. But there are other tools offered by the language, that are not used by default. In other words, the <code>zig</code> compiler does not obligates you to use such tools.</p>
 <p>The tools listed below are related to memory safety. That is, they help you to achieve memory safety in your Zig code:</p>
 <ul>
@@ -1082,26 +1085,29 @@ <h2 data-number="1.10" class="anchored" data-anchor-id="other-parts-of-zig"><spa
 <hr>
 <ol>
 <li id="fn1"><p><a href="https://ziglang.org/learn/overview/#zig-build-system" class="uri">https://ziglang.org/learn/overview/#zig-build-system</a>.<a href="#fnref1" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn2"><p><a href="https://en.wikipedia.org/wiki/List_of_C-family_programming_languages" class="uri">https://en.wikipedia.org/wiki/List_of_C-family_programming_languages</a><a href="#fnref2" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn3"><p><a href="https://github.com/ziglang/zig/issues/17186" class="uri">https://github.com/ziglang/zig/issues/17186</a><a href="#fnref3" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn4"><p><a href="https://github.com/ziglang/zig/issues/19864" class="uri">https://github.com/ziglang/zig/issues/19864</a><a href="#fnref4" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn5"><p><a href="https://github.com/ziglang/zig/tree/master/lib/std" class="uri">https://github.com/ziglang/zig/tree/master/lib/std</a><a href="#fnref5" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn6"><p><a href="https://github.com/oven-sh/bun" class="uri">https://github.com/oven-sh/bun</a>.<a href="#fnref6" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn7"><p><a href="https://github.com/hexops/mach" class="uri">https://github.com/hexops/mach</a><a href="#fnref7" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn8"><p><a href="https://github.com/cgbur/llama2.zig/tree/main" class="uri">https://github.com/cgbur/llama2.zig/tree/main</a><a href="#fnref8" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn9"><p><a href="https://github.com/tigerbeetle/tigerbeetle" class="uri">https://github.com/tigerbeetle/tigerbeetle</a><a href="#fnref9" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn10"><p><a href="https://github.com/Hejsil/zig-clap" class="uri">https://github.com/Hejsil/zig-clap</a><a href="#fnref10" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn11"><p><a href="https://github.com/capy-ui/capy" class="uri">https://github.com/capy-ui/capy</a><a href="#fnref11" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn12"><p><a href="https://github.com/zigtools/zls" class="uri">https://github.com/zigtools/zls</a><a href="#fnref12" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn13"><p><a href="https://github.com/mitchellh/libxev" class="uri">https://github.com/mitchellh/libxev</a><a href="#fnref13" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn14"><p><a href="https://ziglings.org" class="uri">https://ziglings.org</a>.<a href="#fnref14" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn15"><p><a href="https://www.youtube.com/watch?v=OPuztQfM3Fg&amp;t=2524s&amp;ab_channel=TheVimeagen" class="uri">https://www.youtube.com/watch?v=OPuztQfM3Fg&amp;t=2524s&amp;ab_channel=TheVimeagen</a>.<a href="#fnref15" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn16"><p><a href="https://adventofcode.com/" class="uri">https://adventofcode.com/</a><a href="#fnref16" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn17"><p><a href="https://ziglang.org/documentation/master/#Primitive-Types" class="uri">https://ziglang.org/documentation/master/#Primitive-Types</a>.<a href="#fnref17" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn18"><p><a href="https://www.gnu.org/software/libiconv/" class="uri">https://www.gnu.org/software/libiconv/</a><a href="#fnref18" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn19"><p><a href="https://cplusplus.com/reference/cstdio/printf/" class="uri">https://cplusplus.com/reference/cstdio/printf/</a><a href="#fnref19" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn20"><p><a href="https://www.youtube.com/watch?v=jIZpKpLCOiU&amp;ab_channel=GOTOConferences" class="uri">https://www.youtube.com/watch?v=jIZpKpLCOiU&amp;ab_channel=GOTOConferences</a><a href="#fnref20" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn21"><p>Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (<em>foreign function interface</em>), which disables the borrow-checker features through the <code>unsafe</code> keyword.<a href="#fnref21" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn2"><p><a href="https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e" class="uri">https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e</a><a href="#fnref2" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn3"><p><a href="https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1" class="uri">https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1</a><a href="#fnref3" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn4"><p><a href="https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md" class="uri">https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md</a><a href="#fnref4" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn5"><p><a href="https://en.wikipedia.org/wiki/List_of_C-family_programming_languages" class="uri">https://en.wikipedia.org/wiki/List_of_C-family_programming_languages</a><a href="#fnref5" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn6"><p><a href="https://github.com/ziglang/zig/issues/17186" class="uri">https://github.com/ziglang/zig/issues/17186</a><a href="#fnref6" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn7"><p><a href="https://github.com/ziglang/zig/issues/19864" class="uri">https://github.com/ziglang/zig/issues/19864</a><a href="#fnref7" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn8"><p><a href="https://github.com/ziglang/zig/tree/master/lib/std" class="uri">https://github.com/ziglang/zig/tree/master/lib/std</a><a href="#fnref8" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn9"><p><a href="https://github.com/oven-sh/bun" class="uri">https://github.com/oven-sh/bun</a>.<a href="#fnref9" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn10"><p><a href="https://github.com/hexops/mach" class="uri">https://github.com/hexops/mach</a><a href="#fnref10" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn11"><p><a href="https://github.com/cgbur/llama2.zig/tree/main" class="uri">https://github.com/cgbur/llama2.zig/tree/main</a><a href="#fnref11" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn12"><p><a href="https://github.com/tigerbeetle/tigerbeetle" class="uri">https://github.com/tigerbeetle/tigerbeetle</a><a href="#fnref12" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn13"><p><a href="https://github.com/Hejsil/zig-clap" class="uri">https://github.com/Hejsil/zig-clap</a><a href="#fnref13" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn14"><p><a href="https://github.com/capy-ui/capy" class="uri">https://github.com/capy-ui/capy</a><a href="#fnref14" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn15"><p><a href="https://github.com/zigtools/zls" class="uri">https://github.com/zigtools/zls</a><a href="#fnref15" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn16"><p><a href="https://github.com/mitchellh/libxev" class="uri">https://github.com/mitchellh/libxev</a><a href="#fnref16" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn17"><p><a href="https://ziglings.org" class="uri">https://ziglings.org</a>.<a href="#fnref17" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn18"><p><a href="https://www.youtube.com/watch?v=OPuztQfM3Fg&amp;t=2524s&amp;ab_channel=TheVimeagen" class="uri">https://www.youtube.com/watch?v=OPuztQfM3Fg&amp;t=2524s&amp;ab_channel=TheVimeagen</a>.<a href="#fnref18" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn19"><p><a href="https://adventofcode.com/" class="uri">https://adventofcode.com/</a><a href="#fnref19" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn20"><p><a href="https://ziglang.org/documentation/master/#Primitive-Types" class="uri">https://ziglang.org/documentation/master/#Primitive-Types</a>.<a href="#fnref20" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn21"><p><a href="https://www.gnu.org/software/libiconv/" class="uri">https://www.gnu.org/software/libiconv/</a><a href="#fnref21" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn22"><p><a href="https://cplusplus.com/reference/cstdio/printf/" class="uri">https://cplusplus.com/reference/cstdio/printf/</a><a href="#fnref22" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn23"><p><a href="https://www.youtube.com/watch?v=jIZpKpLCOiU&amp;ab_channel=GOTOConferences" class="uri">https://www.youtube.com/watch?v=jIZpKpLCOiU&amp;ab_channel=GOTOConferences</a><a href="#fnref23" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn24"><p>Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (<em>foreign function interface</em>), which disables the borrow-checker features through the <code>unsafe</code> keyword.<a href="#fnref24" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
 </ol>
 </section>
 
diff --git a/docs/Chapters/07-build-system.html b/docs/Chapters/07-build-system.html
index 9a4626a8..1ea868f0 100644
--- a/docs/Chapters/07-build-system.html
+++ b/docs/Chapters/07-build-system.html
@@ -323,7 +323,7 @@ <h1 class="title"><span id="sec-build-system" class="quarto-section-identifier">
 
 <p>In this chapter, we are going to talk about the build system, and how an entire project is built in Zig. One key advantage of Zig is that it includes a build system embedded in the language itself. This is great, because then you do not have to depend on an external system, separated from the compiler, to build your code.</p>
 <p>You can find a good description of Zig’s build system on the <a href="https://ziglang.org/learn/build-system/#user-provided-options">article entitled “Build System”</a><a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a> from the official Zig’s website. We also have the excellent <a href="https://zig.news/xq/zig-build-explained-part-1-59lf">series of posts written by Felix</a><a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a>. Hence, this chapter represents an extra resource for you to consult and rely on.</p>
-<p>Building code is one of the things that Zig is best at. One thing that is particularly difficult in C/C++ and even in Rust, is to cross-compile source code to multiple targets (e.g.&nbsp;multiple computer architectures and operational systems), and the <code>zig</code> compiler is known for being one of the best existing pieces of software for this particular task.</p>
+<p>Building code is one of the things that Zig is best at. One thing that is particularly difficult in C/C++ and even in Rust, is to cross-compile source code to multiple targets (e.g.&nbsp;multiple computer architectures and operating systems), and the <code>zig</code> compiler is known for being one of the best existing pieces of software for this particular task.</p>
 <section id="how-source-code-is-built" class="level2" data-number="9.1">
 <h2 data-number="9.1" class="anchored" data-anchor-id="how-source-code-is-built"><span class="header-section-number">9.1</span> How source code is built?</h2>
 <p>We already have talked about the challenges of building source code in low-level languages at <a href="01-zig-weird.html#sec-project-files" class="quarto-xref"><span>Section 1.2.1</span></a>. As we described at that section, programmers invented Build Systems to surpass these challenges on the process of building source code in low-level languages.</p>
@@ -385,10 +385,10 @@ <h2 data-number="9.3" class="anchored" data-anchor-id="sec-targets"><span class=
 <span id="cb2-5"><a href="#cb2-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>The <code>name</code> option specify the name that you want to give to the binary file defined by this target object. So, in this example, we are building an executable file named <code>hello</code>. Is common to set this <code>name</code> option to the name of your project.</p>
-<p>Furthermore, the <code>target</code> option specify the target computer architecture (or the target operational system) of this binary file. For example, if you want this target object to run on a Windows machine that uses a <code>x86_64</code> architecture, you can set this <code>target</code> option to <code>x86_64-windows-gnu</code> for example. This will make the <code>zig</code> compiler to compile the project to run on a <code>x86_64</code> Windows machine. You can see the full list of architectures and OS’s that the <code>zig</code> compiler supports by running the <code>zig targets</code> command in the terminal.</p>
+<p>Furthermore, the <code>target</code> option specify the target computer architecture (or the target operating system) of this binary file. For example, if you want this target object to run on a Windows machine that uses a <code>x86_64</code> architecture, you can set this <code>target</code> option to <code>x86_64-windows-gnu</code> for example. This will make the <code>zig</code> compiler to compile the project to run on a <code>x86_64</code> Windows machine. You can see the full list of architectures and OS’s that the <code>zig</code> compiler supports by running the <code>zig targets</code> command in the terminal.</p>
 <p>Now, if you are building the project to run on the current machine that you are using to run this build script, you can set this <code>target</code> option to the <code>host</code> method of the <code>Build</code> object, like we did in the example above. This <code>host</code> method identifies the current machine where you are currently running the <code>zig</code> compiler.</p>
 <p>At last, the <code>root_source_file</code> option specifies the root Zig module of your project. That is the Zig module that contains the entrypoint to your application (i.e.&nbsp;the <code>main()</code> function), or, the main API of your library. This also means that, all the Zig modules that compose your project are automatically discovered from the import statements you have inside this “root source file”. The <code>zig</code> compiler can detect when a Zig module depends on the other through the import statements, and, as a result, it can discover the entire map of Zig modules used in your project.</p>
-<p>This is handy, and it is different from what happens in other build systems. In CMake for example, you have to explicitly list the paths to all source files that you want to include in your build process. This is probably a symptom of the “lack of conditional compilation” in the C and C++ compilers. Since they lack this feature, you have to explicitly choose which source files should be sent to the C/C++ compiler, because not every C/C++ code is portable or supported in every operational system, and, therefore, would cause a compilation error in the C/C++ compiler.</p>
+<p>This is handy, and it is different from what happens in other build systems. In CMake for example, you have to explicitly list the paths to all source files that you want to include in your build process. This is probably a symptom of the “lack of conditional compilation” in the C and C++ compilers. Since they lack this feature, you have to explicitly choose which source files should be sent to the C/C++ compiler, because not every C/C++ code is portable or supported in every operating system, and, therefore, would cause a compilation error in the C/C++ compiler.</p>
 <p>Now, one important detail about the build process is that, you have to <strong>explicitly install the target objects that you create in your build script</strong>, by using the <code>installArtifact()</code> method of the <code>Build</code> struct.</p>
 <p>Everytime you invoke the build process of your project, by calling the <code>build</code> command of the <code>zig</code> compiler, a new directory named <code>zig-out</code> is created in the root directory of your project. This new directory contains the outputs of the build process, that is, the binary files built from your source code.</p>
 <p>What the <code>installArtifact()</code> method do is to install (or copy) the built target objects that you defined to this <code>zig-out</code> directory. This means that, if you do not install the target objects you define in your build script, these target objects are essentially discarded at the end of the build process.</p>
diff --git a/docs/Chapters/12-file-op.html b/docs/Chapters/12-file-op.html
index 07269fb0..e00c2578 100644
--- a/docs/Chapters/12-file-op.html
+++ b/docs/Chapters/12-file-op.html
@@ -399,7 +399,7 @@ <h2 data-number="13.1" class="anchored" data-anchor-id="sec-io-basics"><span cla
 <p>This means that we receive an input, or send some output, through the operating system. It is the OS that makes the bridge between the user and your program. Your program does not have a direct access to the user. It is the OS that intermediates every message exchanged between your program and the user.</p>
 <p>The <em>standard output</em> and <em>standard input</em> channels of your OS are commonly known as the <code>stdout</code> and <code>stdin</code> channels of your OS, respectively. In some contexts, they are also called the <em>standard output device</em> and the <em>standard input device</em>. As the name suggests, the <em>standard output</em> is the channel through which output flows, while the <em>standard input</em> is the channel in which input flows.</p>
 <p>Furthermore, OS’s also normally create a dedicated channel for exchanging error messages, which is known as the <em>standard error</em> channel, or, the <code>stderr</code> channel. This is the channel to which error and warning messages are usually sent to. These are the messages that are normally displayed in red-like or orange-like colors into your terminal.</p>
-<p>Normally, every OS (e.g.&nbsp;Windows, MacOS, Linux, etc.) creates a dedicated and separate set of <em>standard output</em>, <em>standard error</em> and <em>standard input</em> channels for every single program (or process) that runs in your computer. This means that every program you write have a dedicated <code>stdin</code>, <code>stderr</code> and <code>stdout</code> that are separate from the <code>stdin</code>, <code>stderr</code> and <code>stdout</code> of other programs and processes that are currently running.</p>
+<p>Normally, every OS (e.g.&nbsp;Windows, macOS, Linux, etc.) creates a dedicated and separate set of <em>standard output</em>, <em>standard error</em> and <em>standard input</em> channels for every single program (or process) that runs in your computer. This means that every program you write have a dedicated <code>stdin</code>, <code>stderr</code> and <code>stdout</code> that are separate from the <code>stdin</code>, <code>stderr</code> and <code>stdout</code> of other programs and processes that are currently running.</p>
 <p>This is a behaviour from your OS. This does not come from the programming language that you are using. Because as I sad earlier, input and output in programming languages, especially in high-level ones, are just a simple abstraction over the <code>stdin</code>, <code>stderr</code> and <code>stdout</code> from your current OS. That is, your OS is the intermediary between every input/output operation made in your program, regardless of the programming language that you are using.</p>
 <section id="sec-writer-reader" class="level3" data-number="13.1.1">
 <h3 data-number="13.1.1" class="anchored" data-anchor-id="sec-writer-reader"><span class="header-section-number">13.1.1</span> The writer and reader pattern</h3>
@@ -589,7 +589,7 @@ <h3 data-number="13.3.1" class="anchored" data-anchor-id="the-concept-of-current
 <h3 data-number="13.3.2" class="anchored" data-anchor-id="the-concept-of-paths"><span class="header-section-number">13.3.2</span> The concept of paths</h3>
 <p>A path is essentially a location. It points to a location in your filesystem. We use paths to describe the location of files and folders in our computer. One important aspect about paths is that they are always written inside strings, i.e.&nbsp;they are always provided as text values.</p>
 <p>There are two types of paths that you can provide to any program in any OS: a relative path, or an absolute path. Absolute paths are paths that start at the root of your filesystem, and go all the way to the file name or the specific folder that you are referring to. This type of path is called absolute, because it points to an unique and absolute location on your computer. That is, there is no other existing location on your computer that corresponds to this path. It is an unique identifier.</p>
-<p>In Windows, an absolute path is a path that starts with a hard disk identifier (e.g.&nbsp;<code>C:/Users/pedro</code>). On the other hand, absolute paths in Linux and MacOS, are paths that start with a forward slash character (e.g.&nbsp;<code>/usr/local/bin</code>). Notice that a path is composed by “segments”. Each segment is connected to each other by a slash character (<code>\</code> or <code>/</code>). On Windows, the backward slash (<code>\</code>) is normally used to connect the path segments. While on Linux and MacOS, the forward slash (<code>/</code>) is the character used to connect path segments.</p>
+<p>In Windows, an absolute path is a path that starts with a hard disk identifier (e.g.&nbsp;<code>C:/Users/pedro</code>). On the other hand, absolute paths in Linux and macOS, are paths that start with a forward slash character (e.g.&nbsp;<code>/usr/local/bin</code>). Notice that a path is composed by “segments”. Each segment is connected to each other by a slash character (<code>\</code> or <code>/</code>). On Windows, the backward slash (<code>\</code>) is normally used to connect the path segments. While on Linux and macOS, the forward slash (<code>/</code>) is the character used to connect path segments.</p>
 <p>A relative path is a path that start at the CWD. In other words, a relative path is “relative to the CWD”. The path used to access the <code>hello.zig</code> file at <a href="#fig-cwd" class="quarto-xref">Figure&nbsp;<span>13.3</span></a> is an example of a relative path. This path is reproduced below. This path begins at the CWD, which in the context of <a href="#fig-cwd" class="quarto-xref">Figure&nbsp;<span>13.3</span></a>, is the <code>zig-book</code> folder, then, it goes to the <code>ZigExamples</code> folder, then, into <code>zig-basics</code>, then, to the <code>hello.zig</code> file.</p>
 <pre><code>ZigExamples/zig-basics/hello_world.zig</code></pre>
 </section>
diff --git a/docs/index.html b/docs/index.html
index 2857af7e..ac188123 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -7,7 +7,7 @@
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 <meta name="author" content="Pedro Duarte Faria">
-<meta name="dcterms.date" content="2025-01-10">
+<meta name="dcterms.date" content="2025-01-30">
 
 <title>Introduction to Zig</title>
 <style>
@@ -287,7 +287,7 @@ <h1 class="title">Introduction to Zig</h1>
     <div>
     <div class="quarto-title-meta-heading">Published</div>
     <div class="quarto-title-meta-contents">
-      <p class="date">January 10, 2025</p>
+      <p class="date">January 30, 2025</p>
     </div>
   </div>
   
@@ -394,9 +394,9 @@ <h2 class="unnumbered anchored" data-anchor-id="about-this-book">About this book
 </section>
 <section id="about-the-author" class="level2 unnumbered">
 <h2 class="unnumbered anchored" data-anchor-id="about-the-author">About the author</h2>
-<p>Pedro Duarte Faria have a bachelor degree in Economics from Federal University of Ouro Preto - Brazil. Currently, he is a Data Platform Engineer at <a href="https://www.blip.ai/en/">Blip</a><a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>, and an Associate Developer for Apache Spark 3.0 certified by Databricks.</p>
-<p>The author have more than 4 years of experience in the data industry. Developing data products, pipelines, reports and analysis for research institutions and some of the largest companies in the brazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.</p>
-<p>But Pedro is also a passionate software developer that loves to learn and teach about programming. Although Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several lectures and courses about it, inside graduate centers (such as PPEA-UFOP<a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a>), in addition to federal and state organizations (such as FJP-MG<a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a>).</p>
+<p>Pedro Duarte Faria has a bachelor’s degree in Economics from the Federal University of Ouro Preto - Brazil. Currently, he is a Data Platform Engineer at <a href="https://www.blip.ai/en/">Blip</a><a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>, and a Databricks Certified Associate Developer for Apache Spark 3.0.</p>
+<p>The author has more than 4 years of experience in the data industry, developing data products, pipelines, reports and analysis for research institutions and some of the largest companies in the Brazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.</p>
+<p>But Pedro is also a passionate software developer who loves to learn and teach about programming. Although Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several lectures and courses about it, inside graduate centers (such as PPEA-UFOP<a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a>), in addition to federal and state organizations (such as FJP-MG<a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a>).</p>
 <p>Personal Website: <a href="https://pedro-faria.netlify.app/" class="uri">https://pedro-faria.netlify.app/</a></p>
 <p>Linkedin: <a href="https://www.linkedin.com/in/pedro-faria-a68140209/" class="uri">https://www.linkedin.com/in/pedro-faria-a68140209/</a></p>
 <p>Mastodon: <a href="https://fosstodon.org/@pedropark99">@pedropark99@fosstodon.org</a></p>
@@ -411,7 +411,7 @@ <h2 class="unnumbered anchored" data-anchor-id="license">License</h2>
 <h2 class="unnumbered anchored" data-anchor-id="book-compilation-metadata">Book compilation metadata</h2>
 <p>This book was compiled using the following versions of <a href="https://ziglang.org">Zig</a> and <a href="https://quarto.org">Quarto</a>:</p>
 <ul>
-<li>System version: Linux, 6.8.0-49-generic, NA, x86_64.</li>
+<li>System version: Linux, 6.8.0-52-generic, NA, x86_64.</li>
 <li>Zig version: 0.14.0-dev.2371+c013f45ad.</li>
 <li>Quarto version: 1.5.57.</li>
 </ul>
diff --git a/docs/search.json b/docs/search.json
index d8974a02..dde3ce1a 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -34,7 +34,7 @@
     "href": "index.html#about-the-author",
     "title": "Introduction to Zig",
     "section": "About the author",
-    "text": "About the author\nPedro Duarte Faria have a bachelor degree in Economics from Federal University of Ouro Preto - Brazil. Currently, he is a Data Platform Engineer at Blip1, and an Associate Developer for Apache Spark 3.0 certified by Databricks.\nThe author have more than 4 years of experience in the data industry. Developing data products, pipelines, reports and analysis for research institutions and some of the largest companies in the brazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\nBut Pedro is also a passionate software developer that loves to learn and teach about programming. Although Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several lectures and courses about it, inside graduate centers (such as PPEA-UFOP2), in addition to federal and state organizations (such as FJP-MG3).\nPersonal Website: https://pedro-faria.netlify.app/\nLinkedin: https://www.linkedin.com/in/pedro-faria-a68140209/\nMastodon: @pedropark99@fosstodon.org\nTwitter (X): @PedroPark9",
+    "text": "About the author\nPedro Duarte Faria has a bachelor’s degree in Economics from the Federal University of Ouro Preto - Brazil. Currently, he is a Data Platform Engineer at Blip1, and a Databricks Certified Associate Developer for Apache Spark 3.0.\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines, reports and analysis for research institutions and some of the largest companies in the Brazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\nBut Pedro is also a passionate software developer who loves to learn and teach about programming. Although Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several lectures and courses about it, inside graduate centers (such as PPEA-UFOP2), in addition to federal and state organizations (such as FJP-MG3).\nPersonal Website: https://pedro-faria.netlify.app/\nLinkedin: https://www.linkedin.com/in/pedro-faria-a68140209/\nMastodon: @pedropark99@fosstodon.org\nTwitter (X): @PedroPark9",
     "crumbs": [
       "Welcome"
     ]
@@ -54,7 +54,7 @@
     "href": "index.html#book-compilation-metadata",
     "title": "Introduction to Zig",
     "section": "Book compilation metadata",
-    "text": "Book compilation metadata\nThis book was compiled using the following versions of Zig and Quarto:\n\nSystem version: Linux, 6.8.0-49-generic, NA, x86_64.\nZig version: 0.14.0-dev.2371+c013f45ad.\nQuarto version: 1.5.57.",
+    "text": "Book compilation metadata\nThis book was compiled using the following versions of Zig and Quarto:\n\nSystem version: Linux, 6.8.0-52-generic, NA, x86_64.\nZig version: 0.14.0-dev.2371+c013f45ad.\nQuarto version: 1.5.57.",
     "crumbs": [
       "Welcome"
     ]
@@ -124,7 +124,7 @@
     "href": "Chapters/01-zig-weird.html#hello-world-in-zig",
     "title": "1  Introducing Zig",
     "section": "1.2 Hello world in Zig",
-    "text": "1.2 Hello world in Zig\nWe begin our journey in Zig by creating a small “Hello World” program. To start a new Zig project in your computer, you simply call the init command from the zig compiler. Just create a new directory in your computer, then, init a new Zig project inside this directory, like this:\nmkdir hello_world\ncd hello_world\nzig init\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n\n1.2.1 Understanding the project files\nAfter you run the init command from the zig compiler, some new files are created inside of your current directory. First, a “source” (src) directory is created, containing two files, main.zig and root.zig. Each .zig file is a separate Zig module, which is simply a text file that contains some Zig code.\nBy convention, the main.zig module is where your main function lives. Thus, if you are building an executable program in Zig, you need to declare a main() function, which represents the entrypoint of your program, i.e. it is where the execution of your program begins.\nHowever, if you are building a library (instead of an executable program), then, the normal procedure is to delete this main.zig file and start with the root.zig module. By convention, the root.zig module is the root source file of your library.\ntree .\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\nThe ìnit command also creates two additional files in our working directory: build.zig and build.zig.zon. The first file (build.zig) represents a build script written in Zig. This script is executed when you call the build command from the zig compiler. In other words, this file contain Zig code that executes the necessary steps to build the entire project.\nLow-level languages normally use a compiler to build your source code into binary executables or binary libraries. Nevertheless, this process of compiling your source code and building binary executables or binary libraries from it, became a real challenge in the programming world, once the projects became bigger and bigger. As a result, programmers created “build systems”, which are a second set of tools designed to make this process of compiling and building complex projects, easier.\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja, which are used to build complex C and C++ projects. With these systems, you can write scripts, which are called “build scripts”. They simply are scripts that describes the necessary steps to compile/build your project.\nHowever, these are separate tools, that do not belong to C/C++ compilers, like gcc or clang. As a result, in C/C++ projects, you have not only to install and manage your C/C++ compilers, but you also have to install and manage these build systems separately.\nIn Zig, we don’t need to use a separate set of tools to build our projects, because a build system is embedded inside the language itself. Therefore, Zig contains a native build system in it, and we can use this build system to write small scripts in Zig, which describes the necessary steps to build/compile our Zig project1. So, everything you need to build a complex Zig project is the zig compiler, and nothing more.\nThe second generated file (build.zig.zon) is the Zig package manager configuration file, where you can list and manage the dependencies of your project. Yes, Zig has a package manager (like pip in Python, cargo in Rust, or npm in Javascript) called Zon, and this build.zig.zon file is similar to the package.json file in Javascript projects, or, the Pipfile file in Python projects, or the Cargo.toml file in Rust projects.\n\n\n1.2.2 The file root.zig\nLet’s take a look into the root.zig file. You might have noticed that every line of code with an expression ends with a semicolon (;). This follows the syntax of a C-family programming language2.\nAlso, notice the @import() call at the first line. We use this built-in function to import functionality from other Zig modules into our current module. This @import() function works similarly to the #include pre-processor in C or C++, or, to the import statement in Python or Javascript code. In this example, we are importing the std module, which gives you access to the Zig Standard Library.\nIn this root.zig file, we can also see how assignments (i.e. creating new objects) are made in Zig. You can create a new object in Zig by using the following syntax (const|var) name = value;. In the example below, we are creating two constant objects (std and testing). At Section 1.4 we talk more about objects in general.\n\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n\nFunctions in Zig are declared using the fn keyword. In this root.zig module, we are declaring a function called add(), which has two arguments named a and b. The function returns an integer of the type i32 as result.\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit the type of an object in your code, if this type can be inferred by the zig compiler (we talk more about that at Section 2.4). But there are other situations where you do need to be explicit. For example, you do have to explicitly specify the type of each function argument, and also, the return type of every function that you create in Zig.\nWe specify the type of an object or a function argument in Zig by using a colon character (:) followed by the type after the name of this object/function argument. With the expressions a: i32 and b: i32, we know that both a and b arguments have type i32, which is a signed 32 bit integer. In this part, the syntax in Zig is identical to the syntax in Rust, which also specifies types by using the colon character.\nLastly, we have the return type of the function at the end of the line, before we open the curly braces to start writing the function’s body. In the example above, this type is also a signed 32 bit integer (i32) value.\nNotice that we also have an export keyword before the function declaration. This keyword is similar to the extern keyword in C. It exposes the function to make it available in the library API. Therefore, if you are writing a library for other people to use, you have to expose the functions you write in the public API of this library by using this export keyword. If we removed the export keyword from the add() function declaration, then, this function would be no longer exposed in the library object built by the zig compiler.\n\n\n1.2.3 The main.zig file\nNow that we have learned a lot about Zig’s syntax from the root.zig file, let’s take a look at the main.zig file. A lot of the elements we saw in root.zig are also present in main.zig. But there are some other elements that we haven’t seen yet, so let’s dive in.\nFirst, look at the return type of the main() function in this file. We can see a small change. The return type of the function (void) is accompanied by an exclamation mark (!). This exclamation mark tells us that this main() function might return an error.\nIn this example, the main() function can either return void or return an error. This is an interesting feature of Zig. If you write a function and something inside of the body of this function might return an error then you are forced to:\n\neither add the exclamation mark to the return type of the function and make it clear that this function might return an error\nexplicitly handle this error inside the function\n\nIn most programming languages, we normally handle (or deal with) an error through a try catch pattern. Zig does have both try and catch keywords. But they work a little differently than what you’re probably used to in other languages.\nIf we look at the main() function below, you can see that we do have a try keyword on the 5th line. But we do not have a catch keyword in this code. In Zig, we use the try keyword to execute an expression that might return an error, which, in this example, is the stdout.print() expression.\nIn essence, the try keyword executes the expression stdout.print(). If this expression returns a valid value, then, the try keyword does nothing. It only passes the value forward. But if the expression does return an error, then, the try keyword just unwrap the error value, and return this error from the function and also prints the current stack trace to stderr.\nThis might sound weird to you if you come from a high-level language. Because in high-level languages, such as Python, if an error occurs somewhere, this error is automatically returned and the execution of your program will automatically stop even if you don’t want to stop the execution. You are obligated to face the error.\n\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n\nAnother thing that you might have noticed in this code example, is that the main() function is marked with the pub keyword. It marks the main() function as a public function from this module.\nEvery function in your Zig module is by default private to this Zig module and can only be called from within the module. Unless, you explicitly mark this function as a public function with the pub keyword. This means that the pub keyword in Zig does essentially the opposite of what the static keyword do in C/C++.\nBy making a function “public” you allow other Zig modules to access and call it. A calling Zig module imports the module with the @import() built-in. That makes all public functions from the imported module visible.\n\n\n1.2.4 Compiling your source code\nYou can compile your Zig modules into a binary executable by running the build-exe command from the zig compiler. You simply list all the Zig modules that you want to build after the build-exe command, separated by spaces. In the example below, we are compiling the module main.zig.\nzig build-exe src/main.zig\nSince we are building an executable, the zig compiler will look for a main() function declared in any of the files that you list after the build-exe command. If the compiler does not find a main() function declared somewhere, a compilation error will be raised, warning about this mistake.\nThe zig compiler also offers a build-lib and build-obj commands, which work the exact same way as the build-exe command. The only difference is that, they compile your Zig modules into a portale C ABI library, or, into object files, respectively.\nIn the case of the build-exe command, a binary executable file is created by the zig compiler in the root directory of your project. If we take a look now at the contents of our current directory, with a simple ls command, we can see the binary file called main that was created by the compiler.\nls\nbuild.zig  build.zig.zon  main  src\nIf I execute this binary executable, I get the “Hello World” message in the terminal , as we expected.\n./main\nHello, world!\n\n\n1.2.5 Compile and execute at the same time\nOn the previous section, I presented the zig build-exe command, which compiles Zig modules into an executable file. However, this means that, in order to execute the executable file, we have to run two different commands. First, the zig build-exe command, and then, we call the executable file created by the compiler.\nBut what if we wanted to perform these two steps, all at once, in a single command? We can do that by using the zig run command.\nzig run src/main.zig\nHello, world!\n\n\n1.2.6 Important note for Windows users\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other operational systems, such as Linux and MacOs. In summary, if you have a piece of Zig code that includes some global variables whose initialization rely on runtime resources, then, you might have some troubles while trying to compile this Zig code on Windows.\nAn example of that is accessing the stdout (i.e. the standard output of your system), which is usually done in Zig by using the expression std.io.getStdOut(). Thus, if you use this expression to instantiate a global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows, with a “unable to evaluate comptime expression” error message.\nThis failure in the compilation process happens because all global variables in Zig are initialized at compile-time. However, operations like accessing the stdout (or opening a file) on Windows depends on resources that are available only at runtime (you will learn more about compile-time versus runtime at Section 3.1.1).\nFor example, if you try to compile this code example on Windows, you will likely get the error message exposed below:\n\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\nTo avoid this problem on Windows, we need to force the zig compiler to instantiate this stdout object only at runtime, instead of instantiating it at compile-time. We can achieve that by simply moving the expression to a function body.\nThis solves the problem because all expressions that are inside a function body in Zig are evaluated only at runtime, unless you use the comptime keyword explicitly to change this behaviour. You will learn more about this comptime keyword at Section 12.1.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nHello\nYou can read more details about this Windows-specific limitation at a couple of GitHub issues opened at the official Zig repository. More specifically, the issues 17186 3 and 19864 4.\n\n\n1.2.7 Compiling the entire project\nJust as I described at Section 1.2.1, as our project grows in size and complexity, we usually prefer to organize the compilation and build process of the project into a build script, using some sort of “build system”.\nIn other words, as our project grows in size and complexity, the build-exe, build-lib and build-obj commands become harder to use directly. Because then, we start to list multiple and multiple modules at the same time. We also start to add built-in compilation flags to customize the build process for our needs, etc. It becomes a lot of work to write the necessary commands by hand.\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, Makefile or configure scripts to organize this process. However, in Zig, we have a native build system in the language itself. So, we can write build scripts in Zig to compile and build Zig projects. Then, all we need to do, is to call the zig build command to build our project.\nSo, when you execute the zig build command, the zig compiler will search for a Zig module named build.zig inside your current directory, which should be your build script, containing the necessary code to compile and build your project. If the compiler does find this build.zig file in your directory, then, the compiler will essentially execute a zig run command over this build.zig file, to compile and execute this build script, which in turn, will compile and build your entire project.\nzig build\nAfter you execute this “build project” command, a zig-out directory is created in the root of your project directory, where you can find the binary executables and libraries created from your Zig modules accordingly to the build commands that you specified at build.zig. We will talk more about the build system in Zig latter in this book.\nIn the example below, I’m executing the binary executable named hello_world that was generated by the compiler after the zig build command.\n./zig-out/bin/hello_world\nHello, world!",
+    "text": "1.2 Hello world in Zig\nWe begin our journey in Zig by creating a small “Hello World” program. To start a new Zig project in your computer, you simply call the init command from the zig compiler. Just create a new directory in your computer, then, init a new Zig project inside this directory, like this:\nmkdir hello_world\ncd hello_world\nzig init\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n\n1.2.1 Understanding the project files\nAfter you run the init command from the zig compiler, some new files are created inside of your current directory. First, a “source” (src) directory is created, containing two files, main.zig and root.zig. Each .zig file is a separate Zig module, which is simply a text file that contains some Zig code.\nBy convention, the main.zig module is where your main function lives. Thus, if you are building an executable program in Zig, you need to declare a main() function, which represents the entrypoint of your program, i.e. it is where the execution of your program begins.\nHowever, if you are building a library (instead of an executable program), then, the normal procedure is to delete this main.zig file and start with the root.zig module. By convention, the root.zig module is the root source file of your library.\ntree .\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\nThe ìnit command also creates two additional files in our working directory: build.zig and build.zig.zon. The first file (build.zig) represents a build script written in Zig. This script is executed when you call the build command from the zig compiler. In other words, this file contain Zig code that executes the necessary steps to build the entire project.\nLow-level languages normally use a compiler to build your source code into binary executables or binary libraries. Nevertheless, this process of compiling your source code and building binary executables or binary libraries from it, became a real challenge in the programming world, once the projects became bigger and bigger. As a result, programmers created “build systems”, which are a second set of tools designed to make this process of compiling and building complex projects, easier.\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja, which are used to build complex C and C++ projects. With these systems, you can write scripts, which are called “build scripts”. They simply are scripts that describes the necessary steps to compile/build your project.\nHowever, these are separate tools, that do not belong to C/C++ compilers, like gcc or clang. As a result, in C/C++ projects, you have not only to install and manage your C/C++ compilers, but you also have to install and manage these build systems separately.\nIn Zig, we don’t need to use a separate set of tools to build our projects, because a build system is embedded inside the language itself. Therefore, Zig contains a native build system in it, and we can use this build system to write small scripts in Zig, which describes the necessary steps to build/compile our Zig project1. So, everything you need to build a complex Zig project is the zig compiler, and nothing more.\nThe second generated file (build.zig.zon) is a JSON-like file, in which you can describe your project, and also, declare a set of dependencies of your project that you want to fetch from the internet. In other words, you can use this build.zig.zon file to include a list of external libraries in your project.\nOne possible way to include an external Zig library in your project, is to manually build and install the library in your system, and just link your source code with the library at the build step of your project.\nHowever, if this external Zig library is available on GitHub for example, and it has a valid build.zig.zon file in root folder of the project, which describes the project, you can easily include this library in your project by simply listing this external library in your build.zig.zon file.\nIn other words, this build.zig.zon file works similarly to the package.json file in Javascript projects, or the Pipfile file in Python projects, or the Cargo.toml file in Rust projects. You can read more about this specific file in a couple of articles on the internet23, and you can also see the expected schema for this build.zig.zon file in a documentation file inside the official repository of Zig4.\n\n\n1.2.2 The file root.zig\nLet’s take a look into the root.zig file. You might have noticed that every line of code with an expression ends with a semicolon (;). This follows the syntax of a C-family programming language5.\nAlso, notice the @import() call at the first line. We use this built-in function to import functionality from other Zig modules into our current module. This @import() function works similarly to the #include pre-processor in C or C++, or, to the import statement in Python or Javascript code. In this example, we are importing the std module, which gives you access to the Zig Standard Library.\nIn this root.zig file, we can also see how assignments (i.e. creating new objects) are made in Zig. You can create a new object in Zig by using the following syntax (const|var) name = value;. In the example below, we are creating two constant objects (std and testing). At Section 1.4 we talk more about objects in general.\n\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n\nFunctions in Zig are declared using the fn keyword. In this root.zig module, we are declaring a function called add(), which has two arguments named a and b. The function returns an integer of the type i32 as result.\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit the type of an object in your code, if this type can be inferred by the zig compiler (we talk more about that at Section 2.4). But there are other situations where you do need to be explicit. For example, you do have to explicitly specify the type of each function argument, and also, the return type of every function that you create in Zig.\nWe specify the type of an object or a function argument in Zig by using a colon character (:) followed by the type after the name of this object/function argument. With the expressions a: i32 and b: i32, we know that both a and b arguments have type i32, which is a signed 32 bit integer. In this part, the syntax in Zig is identical to the syntax in Rust, which also specifies types by using the colon character.\nLastly, we have the return type of the function at the end of the line, before we open the curly braces to start writing the function’s body. In the example above, this type is also a signed 32 bit integer (i32) value.\nNotice that we also have an export keyword before the function declaration. This keyword is similar to the extern keyword in C. It exposes the function to make it available in the library API. Therefore, if you are writing a library for other people to use, you have to expose the functions you write in the public API of this library by using this export keyword. If we removed the export keyword from the add() function declaration, then, this function would be no longer exposed in the library object built by the zig compiler.\n\n\n1.2.3 The main.zig file\nNow that we have learned a lot about Zig’s syntax from the root.zig file, let’s take a look at the main.zig file. A lot of the elements we saw in root.zig are also present in main.zig. But there are some other elements that we haven’t seen yet, so let’s dive in.\nFirst, look at the return type of the main() function in this file. We can see a small change. The return type of the function (void) is accompanied by an exclamation mark (!). This exclamation mark tells us that this main() function might return an error.\nIs worth noting that, a main() function in Zig is allowed to return nothing (void), or an unsigned 8-bit integer (u8) value, or an error. In other words, you can write your main() function in Zig to return essentially nothing (void), or, if you prefer, you can also write a more C-like main() function, which returns an integer value that usually serves as a “status code” for the process.\nIn this example, the return type annotation of main() indicates that this function can either return nothing (void), or return an error. This exclamation mark in the return type annotation is an interesting and powerful feature of Zig. In summary, if you write a function and something inside the body of this function might return an error, then, you are forced to:\n\neither add the exclamation mark to the return type of the function and make it clear that this function might return an error.\nexplicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through a try catch pattern. Zig does have both try and catch keywords. But they work a little differently than what you’re probably used to in other languages.\nIf we look at the main() function below, you can see that we do have a try keyword on the 5th line. But we do not have a catch keyword in this code. In Zig, we use the try keyword to execute an expression that might return an error, which, in this example, is the stdout.print() expression.\nIn essence, the try keyword executes the expression stdout.print(). If this expression returns a valid value, then, the try keyword does absolutely nothing. It only passes the value forward. It is like if this try keyword was never there. However, if the expression does return an error, then, the try keyword will unwrap the error value, then, it returns this error from the function and also prints the current stack trace to stderr.\nThis might sound weird to you if you come from a high-level language. Because in high-level languages, such as Python, if an error occurs somewhere, this error is automatically returned and the execution of your program will automatically stop even if you don’t want to stop the execution. You are obligated to face the error.\n\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n\nAnother thing that you might have noticed in this code example, is that the main() function is marked with the pub keyword. It marks the main() function as a public function from this module. Every function in your Zig module is by default private to this Zig module and can only be called from within the module. Unless, you explicitly mark this function as a public function with the pub keyword.\nIf you think about it, this pub keyword in Zig does essentially the opposite of what the static keyword do in C/C++. By making a function “public” you allow other Zig modules to access and call this function. A calling Zig module imports another module by using the @import() built-in function, which makes all public functions from the imported module visible to the calling Zig module.\n\n\n1.2.4 Compiling your source code\nYou can compile your Zig modules into a binary executable by running the build-exe command from the zig compiler. You simply list all the Zig modules that you want to build after the build-exe command, separated by spaces. In the example below, we are compiling the module main.zig.\nzig build-exe src/main.zig\nSince we are building an executable, the zig compiler will look for a main() function declared in any of the files that you list after the build-exe command. If the compiler does not find a main() function declared somewhere, a compilation error will be raised, warning about this mistake.\nThe zig compiler also offers a build-lib and build-obj commands, which work the exact same way as the build-exe command. The only difference is that, they compile your Zig modules into a portale C ABI library, or, into object files, respectively.\nIn the case of the build-exe command, a binary executable file is created by the zig compiler in the root directory of your project. If we take a look now at the contents of our current directory, with a simple ls command, we can see the binary file called main that was created by the compiler.\nls\nbuild.zig  build.zig.zon  main  src\nIf I execute this binary executable, I get the “Hello World” message in the terminal , as we expected.\n./main\nHello, world!\n\n\n1.2.5 Compile and execute at the same time\nOn the previous section, I presented the zig build-exe command, which compiles Zig modules into an executable file. However, this means that, in order to execute the executable file, we have to run two different commands. First, the zig build-exe command, and then, we call the executable file created by the compiler.\nBut what if we wanted to perform these two steps, all at once, in a single command? We can do that by using the zig run command.\nzig run src/main.zig\nHello, world!\n\n\n1.2.6 Important note for Windows users\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other operating systems, such as Linux and macOs. In summary, if you have a piece of Zig code that includes some global variables whose initialization rely on runtime resources, then, you might have some troubles while trying to compile this Zig code on Windows.\nAn example of that is accessing the stdout (i.e. the standard output of your system), which is usually done in Zig by using the expression std.io.getStdOut(). Thus, if you use this expression to instantiate a global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows, with a “unable to evaluate comptime expression” error message.\nThis failure in the compilation process happens because all global variables in Zig are initialized at compile-time. However, operations like accessing the stdout (or opening a file) on Windows depends on resources that are available only at runtime (you will learn more about compile-time versus runtime at Section 3.1.1).\nFor example, if you try to compile this code example on Windows, you will likely get the error message exposed below:\n\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\nTo avoid this problem on Windows, we need to force the zig compiler to instantiate this stdout object only at runtime, instead of instantiating it at compile-time. We can achieve that by simply moving the expression to a function body.\nThis solves the problem because all expressions that are inside a function body in Zig are evaluated only at runtime, unless you use the comptime keyword explicitly to change this behaviour. You will learn more about this comptime keyword at Section 12.1.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nHello\nYou can read more details about this Windows-specific limitation at a couple of GitHub issues opened at the official Zig repository. More specifically, the issues 17186 6 and 19864 7.\n\n\n1.2.7 Compiling the entire project\nJust as I described at Section 1.2.1, as our project grows in size and complexity, we usually prefer to organize the compilation and build process of the project into a build script, using some sort of “build system”.\nIn other words, as our project grows in size and complexity, the build-exe, build-lib and build-obj commands become harder to use directly. Because then, we start to list multiple and multiple modules at the same time. We also start to add built-in compilation flags to customize the build process for our needs, etc. It becomes a lot of work to write the necessary commands by hand.\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, Makefile or configure scripts to organize this process. However, in Zig, we have a native build system in the language itself. So, we can write build scripts in Zig to compile and build Zig projects. Then, all we need to do, is to call the zig build command to build our project.\nSo, when you execute the zig build command, the zig compiler will search for a Zig module named build.zig inside your current directory, which should be your build script, containing the necessary code to compile and build your project. If the compiler does find this build.zig file in your directory, then, the compiler will essentially execute a zig run command over this build.zig file, to compile and execute this build script, which in turn, will compile and build your entire project.\nzig build\nAfter you execute this “build project” command, a zig-out directory is created in the root of your project directory, where you can find the binary executables and libraries created from your Zig modules accordingly to the build commands that you specified at build.zig. We will talk more about the build system in Zig latter in this book.\nIn the example below, I’m executing the binary executable named hello_world that was generated by the compiler after the zig build command.\n./zig-out/bin/hello_world\nHello, world!",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -134,7 +134,7 @@
     "href": "Chapters/01-zig-weird.html#how-to-learn-zig",
     "title": "1  Introducing Zig",
     "section": "1.3 How to learn Zig?",
-    "text": "1.3 How to learn Zig?\nWhat are the best strategies to learn Zig? First of all, of course this book will help you a lot on your journey through Zig. But you will also need some extra resources if you want to be really good at Zig.\nAs a first tip, you can join a community with Zig programmers to get some help , when you need it:\n\nReddit forum: https://www.reddit.com/r/Zig/;\nZiggit community: https://ziggit.dev/;\nDiscord, Slack, Telegram, and others: https://github.com/ziglang/zig/wiki/Community;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try to read Zig code often, and things will become more clear. A C/C++ programmer would also probably give you this same tip. Because this strategy really works!\nNow, where can you find Zig code to read? I personally think that, the best way of reading Zig code is to read the source code of the Zig Standard Library. The Zig Standard Library is available at the lib/std folder5 on the official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\nAlso, a great alternative is to read code from other large Zig codebases, such as:\n\nthe Javascript runtime Bun6.\nthe game engine Mach7.\na LLama 2 LLM model implementation in Zig8.\nthe financial transactions database tigerbeetle9.\nthe command-line arguments parser zig-clap10.\nthe UI framework capy11.\nthe Language Protocol implementation for Zig, zls12.\nthe event-loop library libxev13.\n\nAll these assets are available on GitHub, and this is great, because we can use the GitHub search bar in our advantage, to find Zig code that fits our description. For example, you can always include lang:Zig in the GitHub search bar when you are searching for a particular pattern. This will limit the search to only Zig modules.\nAlso, a great alternative is to consult online resources and documentations. Here is a quick list of resources that I personally use from time to time to learn more about the language each day:\n\nZig Language Reference: https://ziglang.org/documentation/master/;\nZig Standard Library Reference: https://ziglang.org/documentation/master/std/;\nZig Guide: https://zig.guide/;\nKarl Seguin Blog: https://www.openmymind.net/;\nZig News: https://zig.news/;\nRead the code written by one of the Zig core team members: https://github.com/kubkon;\nSome livecoding sessions are transmitted in the Zig Showtime Youtube Channel: https://www.youtube.com/@ZigSHOWTIME/videos;\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want, is to practice it by solving exercises. For example, there is a famous repository in the Zig community called Ziglings14 , which contains more than 100 small exercises that you can solve. It is a repository of tiny programs written in Zig that are currently broken, and your responsibility is to fix these programs, and make them work again.\nA famous tech YouTuber known as The Primeagen also posted some videos (at YouTube) where he solves these exercises from Ziglings. The first video is named “Trying Zig Part 1”15.\nAnother great alternative, is to solve the Advent of Code exercises16. There are people that already took the time to learn and solve the exercises, and they posted their solutions on GitHub as well, so, in case you need some resource to compare while solving the exercises, you can look at these two repositories:\n\nhttps://github.com/SpexGuy/Zig-AoC-Template;\nhttps://github.com/fjebaker/advent-of-code-2022;",
+    "text": "1.3 How to learn Zig?\nWhat are the best strategies to learn Zig? First of all, of course this book will help you a lot on your journey through Zig. But you will also need some extra resources if you want to be really good at Zig.\nAs a first tip, you can join a community with Zig programmers to get some help , when you need it:\n\nReddit forum: https://www.reddit.com/r/Zig/;\nZiggit community: https://ziggit.dev/;\nDiscord, Slack, Telegram, and others: https://github.com/ziglang/zig/wiki/Community;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try to read Zig code often, and things will become more clear. A C/C++ programmer would also probably give you this same tip. Because this strategy really works!\nNow, where can you find Zig code to read? I personally think that, the best way of reading Zig code is to read the source code of the Zig Standard Library. The Zig Standard Library is available at the lib/std folder8 on the official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\nAlso, a great alternative is to read code from other large Zig codebases, such as:\n\nthe Javascript runtime Bun9.\nthe game engine Mach10.\na LLama 2 LLM model implementation in Zig11.\nthe financial transactions database tigerbeetle12.\nthe command-line arguments parser zig-clap13.\nthe UI framework capy14.\nthe Language Protocol implementation for Zig, zls15.\nthe event-loop library libxev16.\n\nAll these assets are available on GitHub, and this is great, because we can use the GitHub search bar in our advantage, to find Zig code that fits our description. For example, you can always include lang:Zig in the GitHub search bar when you are searching for a particular pattern. This will limit the search to only Zig modules.\nAlso, a great alternative is to consult online resources and documentations. Here is a quick list of resources that I personally use from time to time to learn more about the language each day:\n\nZig Language Reference: https://ziglang.org/documentation/master/;\nZig Standard Library Reference: https://ziglang.org/documentation/master/std/;\nZig Guide: https://zig.guide/;\nKarl Seguin Blog: https://www.openmymind.net/;\nZig News: https://zig.news/;\nRead the code written by one of the Zig core team members: https://github.com/kubkon;\nSome livecoding sessions are transmitted in the Zig Showtime Youtube Channel: https://www.youtube.com/@ZigSHOWTIME/videos;\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want, is to practice it by solving exercises. For example, there is a famous repository in the Zig community called Ziglings17 , which contains more than 100 small exercises that you can solve. It is a repository of tiny programs written in Zig that are currently broken, and your responsibility is to fix these programs, and make them work again.\nA famous tech YouTuber known as The Primeagen also posted some videos (at YouTube) where he solves these exercises from Ziglings. The first video is named “Trying Zig Part 1”18.\nAnother great alternative, is to solve the Advent of Code exercises19. There are people that already took the time to learn and solve the exercises, and they posted their solutions on GitHub as well, so, in case you need some resource to compare while solving the exercises, you can look at these two repositories:\n\nhttps://github.com/SpexGuy/Zig-AoC-Template;\nhttps://github.com/fjebaker/advent-of-code-2022;",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -154,7 +154,7 @@
     "href": "Chapters/01-zig-weird.html#sec-primitive-data-types",
     "title": "1  Introducing Zig",
     "section": "1.5 Primitive Data Types",
-    "text": "1.5 Primitive Data Types\nZig have many different primitive data types available for you to use. You can see the full list of available data types at the official Language Reference page17.\nBut here is a quick list:\n\nUnsigned integers: u8, 8-bit integer; u16, 16-bit integer; u32, 32-bit integer; u64, 64-bit integer; u128, 128-bit integer.\nSigned integers: i8, 8-bit integer; i16, 16-bit integer; i32, 32-bit integer; i64, 64-bit integer; i128, 128-bit integer.\nFloat number: f16, 16-bit floating point; f32, 32-bit floating point; f64, 64-bit floating point; f128, 128-bit floating point;\nBoolean: bool, represents true or false values.\nC ABI compatible types: c_long, c_char, c_short, c_ushort, c_int, c_uint, and many others.\nPointer sized integers: isize and usize.",
+    "text": "1.5 Primitive Data Types\nZig have many different primitive data types available for you to use. You can see the full list of available data types at the official Language Reference page20.\nBut here is a quick list:\n\nUnsigned integers: u8, 8-bit integer; u16, 16-bit integer; u32, 32-bit integer; u64, 64-bit integer; u128, 128-bit integer.\nSigned integers: i8, 8-bit integer; i16, 16-bit integer; i32, 32-bit integer; i64, 64-bit integer; i128, 128-bit integer.\nFloat number: f16, 16-bit floating point; f32, 32-bit floating point; f64, 64-bit floating point; f128, 128-bit floating point;\nBoolean: bool, represents true or false values.\nC ABI compatible types: c_long, c_char, c_short, c_ushort, c_int, c_uint, and many others.\nPointer sized integers: isize and usize.",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -184,7 +184,7 @@
     "href": "Chapters/01-zig-weird.html#sec-zig-strings",
     "title": "1  Introducing Zig",
     "section": "1.8 How strings work in Zig?",
-    "text": "1.8 How strings work in Zig?\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (Chapter 4). But in order for us to build such a thing, we need to get a better understanding on how strings work in Zig. So let’s discuss this specific aspect of Zig.\nIn summary, there are two types of string values that you care about in Zig, which are:\n\nString literal values.\nString objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string). But in Zig, a string literal value also embeds the length of the string into the data type of the value itself. Therefore, a string literal value have a data type in the format *const [n:0]u8. The n in the data type indicates the size of the string.\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes, or, in other words, a slice of u8 values (slices were presented at Section 1.6). Thus, a string object have a data type of []u8 or []const u8, depending if the string object is marked as constant with const, or as variable with var.\nBecause a string object is essentially a slice, it means that a string object always contains two things: a pointer to an array of bytes (i.e. u8 values) that represents the string value; and also, a length value, which specifies the size of the slice, or, how many elements there is in the slice. Is worth to emphasize that the array of bytes in a string object is not null-terminated, like in a string literal value.\n\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every sequence of bytes you’re working with, but is not really Zig’s job to fix the encoding of your strings (you can use iconv18 for that). Today, most of the text in our modern world, especially on the web, should be UTF-8 encoded. So if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\nLet’s take for example the word “Hello”. In UTF-8, this sequence of characters (H, e, l, l, o) is represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this sequence is 0x48, 0x65, 0x6C, 0x6C, 0x6F. So if I take this sequence of hexadecimal values, and ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then, the text “Hello” will be printed into the terminal:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n\nHello\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use a for loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal value to the terminal. You do that by using a print() statement with the X formatting specifier, like you would normally do with the printf() function19 in C.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n\n\n\n1.8.1 Strings in C\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well. In more details, string values in C are treated internally as an array of arbitrary bytes, and this array is also null-terminated.\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of the string inside the object itself. In the case of a string literal value, this length is stored in the data type of the value (i.e. the n variable in [n:0]u8). While, in a string object, the length is stored in the len attribute of the slice that represents the string object. This small detail makes your code safer, because is much easier for the Zig compiler to check if you are trying to access an element that is “out of bounds”, i.e. if your trying to access memory that does not belong to you.\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless. So getting this kind of safety is not automatic and much harder to do in C. For example, if you want to track the length of your string throughout your program in C, then, you first need to loop through the array of bytes that represents this string, and find the null element ('\\0') position to discover where exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\nTo do that, you would need something like this in C. In this example, the C string stored in the object array is 25 bytes long:\n\n#include &lt;stdio.h&gt;\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n\nNumber of elements in the array: 25\nYou don’t have this kind of work in Zig. Because the length of the string is always present and accessible. In a string object for example, you can easily access the length of the string through the len attribute. As an example, the string_object object below is 43 bytes long:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n\n43\n\n\n\n\n1.8.2 A better look at the object type\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the @TypeOf() function. If we look at the type of the simple_array object below, you will find that this object is an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type i32 in Zig. That is what an object of type [4]i32 is.\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a constant pointer (hence the *const annotation) to an array of 16 elements (or 16 bytes). Each element is a single byte (more precisely, an unsigned 8 bit integer - u8), that is why we have the [16:0]u8 portion of the type below. In other words, the string literal value exposed below is 16 bytes long.\nNow, if we create an pointer to the simple_array object, then, we get a constant pointer to an array of 4 elements (*const [4]i32), which is very similar to the type of the string literal value. This demonstrates that a string literal value in Zig is already a pointer to a null-terminated array of bytes.\nFurthermore, if we take a look at the type of the string_obj object, you will see that it is a slice object (hence the [] portion of the type) to a sequence of constant u8 values (hence the const u8 portion of the type).\n\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n\n\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n\n\n1.8.3 Byte vs unicode points\nIs important to point out that each byte in the array is not necessarily a single character. This fact arises from the difference between a single byte and a single unicode point.\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in the string. For example, the character “H” is stored in UTF-8 as the decimal number 72. This means that the number 72 is the unicode point for the character “H”. Each possible character that can appear in a UTF-8 encoded string have its own unicode point.\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point) 570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which is 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why, the unicode point 570 is actually stored inside the computer’s memory as the bytes C8 BA.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n\nBytes that represents the string object: C8 BA \n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together to represent the number 570. That is why the relationship between bytes and unicode points is not always 1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds to a single unicode point.\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the bytes that represents that string, and not through the characters of that string. In the Ⱥ example above, the for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a consequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because the number of bytes will be equal to the number of characters in that string. In other words, in this specific situation, the relationship between bytes and unicode points is 1 to 1.\nBut on the other side, if your string contains other types of letters… for example, you might be working with text data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent your UTF-8 string will likely be much higher than the number of characters in that string.\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the std.unicode.Utf8View struct to create an iterator that iterates through the unicode points of your string.\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in this string is represented by three bytes. But the for loop iterates four times, one iteration for each character/unicode point in this string:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n\n\n1.8.4 Some useful functions for strings\nIn this section, I just want to quickly describe some functions from the Zig Standard Library that are very useful to use when working with strings. Most notably:\n\nstd.mem.eql(): to compare if two strings are equal.\nstd.mem.splitScalar(): to split a string into an array of substrings given a delimiter value.\nstd.mem.splitSequence(): to split a string into an array of substrings given a substring delimiter.\nstd.mem.startsWith(): to check if string starts with substring.\nstd.mem.endsWith(): to check if string ends with substring.\nstd.mem.trim(): to remove specific values from both start and end of the string.\nstd.mem.concat(): to concatenate strings together.\nstd.mem.count(): to count the occurrences of substring in the string.\nstd.mem.replace(): to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the mem module of the Zig Standard Library. This module contains multiple functions and methods that are useful to work with memory and sequences of bytes in general.\nThe eql() function is used to check if two arrays of data are equal or not. Since strings are just arbitrary arrays of bytes, we can use this function to compare two strings together. This function returns a boolean value indicating if the two strings are equal or not. The first argument of this function is the data type of the elements of the arrays that are being compared.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n\ntrue\n\n\nThe splitScalar() and splitSequence() functions are useful to split a string into multiple fragments, like the split() method from Python strings. The difference between these two methods is that the splitScalar() uses a single character as the separator to split the string, while splitSequence() uses a sequence of characters (a.k.a. a substring) as the separator. There is a practical example of these functions later in the book.\nThe startsWith() and endsWith() functions are pretty straightforward. They return a boolean value indicating if the string (or, more precisely, if the array of data) begins (startsWith) or ends (endsWith) with the sequence provided.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n\ntrue\n\n\nThe concat() function, as the name suggests, concatenate two or more strings together. Because the process of concatenating the strings involves allocating enough space to accomodate all the strings together, this concat() function receives an allocator object as input.\n\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n\nAs you can imagine, the replace() function is used to replace substrings in a string by another substring. This function works very similarly to the replace() method from Python strings. Therefore, you provide a substring to search, and every time that the replace() function finds this substring within the input string, it replaces this substring with the “replacement substring” that you provided as input.\nIn the example below, we are taking the input string “Hello”, and replacing all occurrences of the substring “el” inside this input string with “34”, and saving the results inside the buffer object. As result, the replace() function returns an usize value that indicates how many replacements were performed.\n\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n\nNew string: H34lo\nN of replacements: 1",
+    "text": "1.8 How strings work in Zig?\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (Chapter 4). But in order for us to build such a thing, we need to get a better understanding on how strings work in Zig. So let’s discuss this specific aspect of Zig.\nIn summary, there are two types of string values that you care about in Zig, which are:\n\nString literal values.\nString objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string). But in Zig, a string literal value also embeds the length of the string into the data type of the value itself. Therefore, a string literal value have a data type in the format *const [n:0]u8. The n in the data type indicates the size of the string.\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes, or, in other words, a slice of u8 values (slices were presented at Section 1.6). Thus, a string object have a data type of []u8 or []const u8, depending if the string object is marked as constant with const, or as variable with var.\nBecause a string object is essentially a slice, it means that a string object always contains two things: a pointer to an array of bytes (i.e. u8 values) that represents the string value; and also, a length value, which specifies the size of the slice, or, how many elements there is in the slice. Is worth to emphasize that the array of bytes in a string object is not null-terminated, like in a string literal value.\n\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every sequence of bytes you’re working with, but is not really Zig’s job to fix the encoding of your strings (you can use iconv21 for that). Today, most of the text in our modern world, especially on the web, should be UTF-8 encoded. So if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\nLet’s take for example the word “Hello”. In UTF-8, this sequence of characters (H, e, l, l, o) is represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this sequence is 0x48, 0x65, 0x6C, 0x6C, 0x6F. So if I take this sequence of hexadecimal values, and ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then, the text “Hello” will be printed into the terminal:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n\nHello\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use a for loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal value to the terminal. You do that by using a print() statement with the X formatting specifier, like you would normally do with the printf() function22 in C.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n\n\n\n1.8.1 Strings in C\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well. In more details, string values in C are treated internally as an array of arbitrary bytes, and this array is also null-terminated.\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of the string inside the object itself. In the case of a string literal value, this length is stored in the data type of the value (i.e. the n variable in [n:0]u8). While, in a string object, the length is stored in the len attribute of the slice that represents the string object. This small detail makes your code safer, because is much easier for the Zig compiler to check if you are trying to access an element that is “out of bounds”, i.e. if your trying to access memory that does not belong to you.\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless. So getting this kind of safety is not automatic and much harder to do in C. For example, if you want to track the length of your string throughout your program in C, then, you first need to loop through the array of bytes that represents this string, and find the null element ('\\0') position to discover where exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\nTo do that, you would need something like this in C. In this example, the C string stored in the object array is 25 bytes long:\n\n#include &lt;stdio.h&gt;\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n\nNumber of elements in the array: 25\nYou don’t have this kind of work in Zig. Because the length of the string is always present and accessible. In a string object for example, you can easily access the length of the string through the len attribute. As an example, the string_object object below is 43 bytes long:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n\n43\n\n\n\n\n1.8.2 A better look at the object type\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the @TypeOf() function. If we look at the type of the simple_array object below, you will find that this object is an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type i32 in Zig. That is what an object of type [4]i32 is.\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a constant pointer (hence the *const annotation) to an array of 16 elements (or 16 bytes). Each element is a single byte (more precisely, an unsigned 8 bit integer - u8), that is why we have the [16:0]u8 portion of the type below. In other words, the string literal value exposed below is 16 bytes long.\nNow, if we create an pointer to the simple_array object, then, we get a constant pointer to an array of 4 elements (*const [4]i32), which is very similar to the type of the string literal value. This demonstrates that a string literal value in Zig is already a pointer to a null-terminated array of bytes.\nFurthermore, if we take a look at the type of the string_obj object, you will see that it is a slice object (hence the [] portion of the type) to a sequence of constant u8 values (hence the const u8 portion of the type).\n\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n\n\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n\n\n1.8.3 Byte vs unicode points\nIs important to point out that each byte in the array is not necessarily a single character. This fact arises from the difference between a single byte and a single unicode point.\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in the string. For example, the character “H” is stored in UTF-8 as the decimal number 72. This means that the number 72 is the unicode point for the character “H”. Each possible character that can appear in a UTF-8 encoded string have its own unicode point.\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point) 570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which is 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why, the unicode point 570 is actually stored inside the computer’s memory as the bytes C8 BA.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n\nBytes that represents the string object: C8 BA \n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together to represent the number 570. That is why the relationship between bytes and unicode points is not always 1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds to a single unicode point.\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the bytes that represents that string, and not through the characters of that string. In the Ⱥ example above, the for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a consequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because the number of bytes will be equal to the number of characters in that string. In other words, in this specific situation, the relationship between bytes and unicode points is 1 to 1.\nBut on the other side, if your string contains other types of letters… for example, you might be working with text data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent your UTF-8 string will likely be much higher than the number of characters in that string.\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the std.unicode.Utf8View struct to create an iterator that iterates through the unicode points of your string.\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in this string is represented by three bytes. But the for loop iterates four times, one iteration for each character/unicode point in this string:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n\n\n1.8.4 Some useful functions for strings\nIn this section, I just want to quickly describe some functions from the Zig Standard Library that are very useful to use when working with strings. Most notably:\n\nstd.mem.eql(): to compare if two strings are equal.\nstd.mem.splitScalar(): to split a string into an array of substrings given a delimiter value.\nstd.mem.splitSequence(): to split a string into an array of substrings given a substring delimiter.\nstd.mem.startsWith(): to check if string starts with substring.\nstd.mem.endsWith(): to check if string ends with substring.\nstd.mem.trim(): to remove specific values from both start and end of the string.\nstd.mem.concat(): to concatenate strings together.\nstd.mem.count(): to count the occurrences of substring in the string.\nstd.mem.replace(): to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the mem module of the Zig Standard Library. This module contains multiple functions and methods that are useful to work with memory and sequences of bytes in general.\nThe eql() function is used to check if two arrays of data are equal or not. Since strings are just arbitrary arrays of bytes, we can use this function to compare two strings together. This function returns a boolean value indicating if the two strings are equal or not. The first argument of this function is the data type of the elements of the arrays that are being compared.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n\ntrue\n\n\nThe splitScalar() and splitSequence() functions are useful to split a string into multiple fragments, like the split() method from Python strings. The difference between these two methods is that the splitScalar() uses a single character as the separator to split the string, while splitSequence() uses a sequence of characters (a.k.a. a substring) as the separator. There is a practical example of these functions later in the book.\nThe startsWith() and endsWith() functions are pretty straightforward. They return a boolean value indicating if the string (or, more precisely, if the array of data) begins (startsWith) or ends (endsWith) with the sequence provided.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n\ntrue\n\n\nThe concat() function, as the name suggests, concatenate two or more strings together. Because the process of concatenating the strings involves allocating enough space to accomodate all the strings together, this concat() function receives an allocator object as input.\n\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n\nAs you can imagine, the replace() function is used to replace substrings in a string by another substring. This function works very similarly to the replace() method from Python strings. Therefore, you provide a substring to search, and every time that the replace() function finds this substring within the input string, it replaces this substring with the “replacement substring” that you provided as input.\nIn the example below, we are taking the input string “Hello”, and replacing all occurrences of the substring “el” inside this input string with “34”, and saving the results inside the buffer object. As result, the replace() function returns an usize value that indicates how many replacements were performed.\n\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n\nNew string: H34lo\nN of replacements: 1",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -194,7 +194,7 @@
     "href": "Chapters/01-zig-weird.html#safety-in-zig",
     "title": "1  Introducing Zig",
     "section": "1.9 Safety in Zig",
-    "text": "1.9 Safety in Zig\nA general trend in modern low-level programming languages is safety. As our modern world becomes more interconnected with technology and computers, the data produced by all of this technology becomes one of the most important (and also, one of the most dangerous) assets that we have.\nThis is probably the main reason why modern low-level programming languages have been giving great attention to safety, especially memory safety, because memory corruption is still the main target for hackers to exploit. The reality is that we don’t have an easy solution for this problem. For now, we only have techniques and strategies that mitigates these problems.\nAs Richard Feldman explains on his most recent GOTO conference talk20 , we haven’t figured it out yet a way to achieve true safety in technology. In other words, we haven’t found a way to build software that won’t be exploited with 100% certainty. We can greatly reduce the risks of our software being exploited, by ensuring memory safety for example. But this is not enough to achieve “true safety” territory.\nBecause even if you write your program in a “safe language”, hackers can still exploit failures in the operational system where your program is running (e.g. maybe the system where your code is running has a “backdoor exploit” that can still affect your code in unexpected ways), or also, they can exploit the features from the architecture of your computer. A recently found exploit that involves memory invalidation through a feature of “memory tags” present in ARM chips is an example of that (Kim et al. 2024).\nThe question is: what have Zig and other languages been doing to mitigate this problem? If we take Rust as an example, Rust is, for the most part21, a memory safe language by enforcing specific rules to the developer. In other words, the key feature of Rust, the borrow checker, forces you to follow a specific logic when you are writing your Rust code, and the Rust compiler will always complain everytime you try to go out of this pattern.\nIn contrast, the Zig language is not a memory safe language by default. There are some memory safety features that you get for free in Zig, especially in arrays and pointer objects. But there are other tools offered by the language, that are not used by default. In other words, the zig compiler does not obligates you to use such tools.\nThe tools listed below are related to memory safety. That is, they help you to achieve memory safety in your Zig code:\n\ndefer allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, “use after free”, and also “double-free” problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\nerrdefer helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\npointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\nZig offers some native types of allocators (called “testing allocators”) that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\narrays and slices in Zig have their lengths embedded in the object itself, which makes the zig compiler very effective on detecting “index out-of-range” type of errors, and avoiding buffer overflows.\n\nDespite these features that Zig offers that are related to memory safety issues, the language also has some rules that help you to achieve another type of safety, which is more related to program logic safety. These rules are:\n\npointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\nswitch statements must exaust all possible options.\nthe zig compiler forces you to handle every possible error in your program.",
+    "text": "1.9 Safety in Zig\nA general trend in modern low-level programming languages is safety. As our modern world becomes more interconnected with technology and computers, the data produced by all of this technology becomes one of the most important (and also, one of the most dangerous) assets that we have.\nThis is probably the main reason why modern low-level programming languages have been giving great attention to safety, especially memory safety, because memory corruption is still the main target for hackers to exploit. The reality is that we don’t have an easy solution for this problem. For now, we only have techniques and strategies that mitigates these problems.\nAs Richard Feldman explains on his most recent GOTO conference talk23 , we haven’t figured it out yet a way to achieve true safety in technology. In other words, we haven’t found a way to build software that won’t be exploited with 100% certainty. We can greatly reduce the risks of our software being exploited, by ensuring memory safety for example. But this is not enough to achieve “true safety” territory.\nBecause even if you write your program in a “safe language”, hackers can still exploit failures in the operating system where your program is running (e.g. maybe the system where your code is running has a “backdoor exploit” that can still affect your code in unexpected ways), or also, they can exploit the features from the architecture of your computer. A recently found exploit that involves memory invalidation through a feature of “memory tags” present in ARM chips is an example of that (Kim et al. 2024).\nThe question is: what have Zig and other languages been doing to mitigate this problem? If we take Rust as an example, Rust is, for the most part24, a memory safe language by enforcing specific rules to the developer. In other words, the key feature of Rust, the borrow checker, forces you to follow a specific logic when you are writing your Rust code, and the Rust compiler will always complain everytime you try to go out of this pattern.\nIn contrast, the Zig language is not a memory safe language by default. There are some memory safety features that you get for free in Zig, especially in arrays and pointer objects. But there are other tools offered by the language, that are not used by default. In other words, the zig compiler does not obligates you to use such tools.\nThe tools listed below are related to memory safety. That is, they help you to achieve memory safety in your Zig code:\n\ndefer allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, “use after free”, and also “double-free” problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\nerrdefer helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\npointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\nZig offers some native types of allocators (called “testing allocators”) that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\narrays and slices in Zig have their lengths embedded in the object itself, which makes the zig compiler very effective on detecting “index out-of-range” type of errors, and avoiding buffer overflows.\n\nDespite these features that Zig offers that are related to memory safety issues, the language also has some rules that help you to achieve another type of safety, which is more related to program logic safety. These rules are:\n\npointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\nswitch statements must exaust all possible options.\nthe zig compiler forces you to handle every possible error in your program.",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -214,7 +214,7 @@
     "href": "Chapters/01-zig-weird.html#footnotes",
     "title": "1  Introducing Zig",
     "section": "",
-    "text": "https://ziglang.org/learn/overview/#zig-build-system.↩︎\nhttps://en.wikipedia.org/wiki/List_of_C-family_programming_languages↩︎\nhttps://github.com/ziglang/zig/issues/17186↩︎\nhttps://github.com/ziglang/zig/issues/19864↩︎\nhttps://github.com/ziglang/zig/tree/master/lib/std↩︎\nhttps://github.com/oven-sh/bun.↩︎\nhttps://github.com/hexops/mach↩︎\nhttps://github.com/cgbur/llama2.zig/tree/main↩︎\nhttps://github.com/tigerbeetle/tigerbeetle↩︎\nhttps://github.com/Hejsil/zig-clap↩︎\nhttps://github.com/capy-ui/capy↩︎\nhttps://github.com/zigtools/zls↩︎\nhttps://github.com/mitchellh/libxev↩︎\nhttps://ziglings.org.↩︎\nhttps://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen.↩︎\nhttps://adventofcode.com/↩︎\nhttps://ziglang.org/documentation/master/#Primitive-Types.↩︎\nhttps://www.gnu.org/software/libiconv/↩︎\nhttps://cplusplus.com/reference/cstdio/printf/↩︎\nhttps://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences↩︎\nActually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (foreign function interface), which disables the borrow-checker features through the unsafe keyword.↩︎",
+    "text": "https://ziglang.org/learn/overview/#zig-build-system.↩︎\nhttps://zig.news/edyu/zig-package-manager-wtf-is-zon-558e↩︎\nhttps://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1↩︎\nhttps://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md↩︎\nhttps://en.wikipedia.org/wiki/List_of_C-family_programming_languages↩︎\nhttps://github.com/ziglang/zig/issues/17186↩︎\nhttps://github.com/ziglang/zig/issues/19864↩︎\nhttps://github.com/ziglang/zig/tree/master/lib/std↩︎\nhttps://github.com/oven-sh/bun.↩︎\nhttps://github.com/hexops/mach↩︎\nhttps://github.com/cgbur/llama2.zig/tree/main↩︎\nhttps://github.com/tigerbeetle/tigerbeetle↩︎\nhttps://github.com/Hejsil/zig-clap↩︎\nhttps://github.com/capy-ui/capy↩︎\nhttps://github.com/zigtools/zls↩︎\nhttps://github.com/mitchellh/libxev↩︎\nhttps://ziglings.org.↩︎\nhttps://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen.↩︎\nhttps://adventofcode.com/↩︎\nhttps://ziglang.org/documentation/master/#Primitive-Types.↩︎\nhttps://www.gnu.org/software/libiconv/↩︎\nhttps://cplusplus.com/reference/cstdio/printf/↩︎\nhttps://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences↩︎\nActually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (foreign function interface), which disables the borrow-checker features through the unsafe keyword.↩︎",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -724,7 +724,7 @@
     "href": "Chapters/07-build-system.html#sec-targets",
     "title": "9  Build System",
     "section": "9.3 Target objects",
-    "text": "9.3 Target objects\nAs we described over the previous sections, a build script is composed around target objects. Each target object is normally a binary file (or an output) that you want to get from the build process. You can list multiple target objects in your build script, so that the build process generates multiple binary files for you at once.\nFor example, maybe you are a developer working in a cross-platform application, and, because this application is cross-platform, you probably need to release binary files of your software for each OS supported by your application to your end users. Thus, you can define a different target object in your build script for each OS (Windows, Linux, etc.) where you want to publish your software. This will make the zig compiler to build your project to multiple target OS’s at once. The Zig Build System official documentation have a great code example that demonstrates this strategy4.\nA target object is created by the following methods of the Build struct that we introduced at Section 9.2:\n\naddExecutable() creates an executable file;\naddSharedLibrary() creates a shared library file;\naddStaticLibrary() creates a static library file;\naddTest() creates an executable file that executes unit tests.\n\nThese functions are methods from the Build struct that you receive as input of the build() function. All of them, create as output a Compile object, which represents a target object to be compiled by the zig compiler. All of these functions accept a similar struct literal as input. This struct literal defines three essential specs about this target object that you are building: name, target and root_source_file.\nWe have already seen these three options being used on the previous example, where we used the addExecutable() method to create an executable target object. This example is reproduced below. Notice the use of the path() method from the Build struct, to define a path in the root_source_file option.\n\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nThe name option specify the name that you want to give to the binary file defined by this target object. So, in this example, we are building an executable file named hello. Is common to set this name option to the name of your project.\nFurthermore, the target option specify the target computer architecture (or the target operational system) of this binary file. For example, if you want this target object to run on a Windows machine that uses a x86_64 architecture, you can set this target option to x86_64-windows-gnu for example. This will make the zig compiler to compile the project to run on a x86_64 Windows machine. You can see the full list of architectures and OS’s that the zig compiler supports by running the zig targets command in the terminal.\nNow, if you are building the project to run on the current machine that you are using to run this build script, you can set this target option to the host method of the Build object, like we did in the example above. This host method identifies the current machine where you are currently running the zig compiler.\nAt last, the root_source_file option specifies the root Zig module of your project. That is the Zig module that contains the entrypoint to your application (i.e. the main() function), or, the main API of your library. This also means that, all the Zig modules that compose your project are automatically discovered from the import statements you have inside this “root source file”. The zig compiler can detect when a Zig module depends on the other through the import statements, and, as a result, it can discover the entire map of Zig modules used in your project.\nThis is handy, and it is different from what happens in other build systems. In CMake for example, you have to explicitly list the paths to all source files that you want to include in your build process. This is probably a symptom of the “lack of conditional compilation” in the C and C++ compilers. Since they lack this feature, you have to explicitly choose which source files should be sent to the C/C++ compiler, because not every C/C++ code is portable or supported in every operational system, and, therefore, would cause a compilation error in the C/C++ compiler.\nNow, one important detail about the build process is that, you have to explicitly install the target objects that you create in your build script, by using the installArtifact() method of the Build struct.\nEverytime you invoke the build process of your project, by calling the build command of the zig compiler, a new directory named zig-out is created in the root directory of your project. This new directory contains the outputs of the build process, that is, the binary files built from your source code.\nWhat the installArtifact() method do is to install (or copy) the built target objects that you defined to this zig-out directory. This means that, if you do not install the target objects you define in your build script, these target objects are essentially discarded at the end of the build process.\nFor example, you might be building a project that uses a third party library that is built together with the project. So, when you build your project, you would need first, to build the third party library, and then, you link it with the source code of your project. So, in this case, we have two binary files that are generated in the build process (the executable file of your project, and the third party library). But only one is of interest, which is the executable file of our project. We can discard the binary file of the third party library, by simply not installing it into this zig-out directory.\nThis installArtifact() method is pretty straightforward. Just remember to apply it to every target object that you want to save into the zig-out directory, like in the example below:\n\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nb.installArtifact(exe);",
+    "text": "9.3 Target objects\nAs we described over the previous sections, a build script is composed around target objects. Each target object is normally a binary file (or an output) that you want to get from the build process. You can list multiple target objects in your build script, so that the build process generates multiple binary files for you at once.\nFor example, maybe you are a developer working in a cross-platform application, and, because this application is cross-platform, you probably need to release binary files of your software for each OS supported by your application to your end users. Thus, you can define a different target object in your build script for each OS (Windows, Linux, etc.) where you want to publish your software. This will make the zig compiler to build your project to multiple target OS’s at once. The Zig Build System official documentation have a great code example that demonstrates this strategy4.\nA target object is created by the following methods of the Build struct that we introduced at Section 9.2:\n\naddExecutable() creates an executable file;\naddSharedLibrary() creates a shared library file;\naddStaticLibrary() creates a static library file;\naddTest() creates an executable file that executes unit tests.\n\nThese functions are methods from the Build struct that you receive as input of the build() function. All of them, create as output a Compile object, which represents a target object to be compiled by the zig compiler. All of these functions accept a similar struct literal as input. This struct literal defines three essential specs about this target object that you are building: name, target and root_source_file.\nWe have already seen these three options being used on the previous example, where we used the addExecutable() method to create an executable target object. This example is reproduced below. Notice the use of the path() method from the Build struct, to define a path in the root_source_file option.\n\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nThe name option specify the name that you want to give to the binary file defined by this target object. So, in this example, we are building an executable file named hello. Is common to set this name option to the name of your project.\nFurthermore, the target option specify the target computer architecture (or the target operating system) of this binary file. For example, if you want this target object to run on a Windows machine that uses a x86_64 architecture, you can set this target option to x86_64-windows-gnu for example. This will make the zig compiler to compile the project to run on a x86_64 Windows machine. You can see the full list of architectures and OS’s that the zig compiler supports by running the zig targets command in the terminal.\nNow, if you are building the project to run on the current machine that you are using to run this build script, you can set this target option to the host method of the Build object, like we did in the example above. This host method identifies the current machine where you are currently running the zig compiler.\nAt last, the root_source_file option specifies the root Zig module of your project. That is the Zig module that contains the entrypoint to your application (i.e. the main() function), or, the main API of your library. This also means that, all the Zig modules that compose your project are automatically discovered from the import statements you have inside this “root source file”. The zig compiler can detect when a Zig module depends on the other through the import statements, and, as a result, it can discover the entire map of Zig modules used in your project.\nThis is handy, and it is different from what happens in other build systems. In CMake for example, you have to explicitly list the paths to all source files that you want to include in your build process. This is probably a symptom of the “lack of conditional compilation” in the C and C++ compilers. Since they lack this feature, you have to explicitly choose which source files should be sent to the C/C++ compiler, because not every C/C++ code is portable or supported in every operating system, and, therefore, would cause a compilation error in the C/C++ compiler.\nNow, one important detail about the build process is that, you have to explicitly install the target objects that you create in your build script, by using the installArtifact() method of the Build struct.\nEverytime you invoke the build process of your project, by calling the build command of the zig compiler, a new directory named zig-out is created in the root directory of your project. This new directory contains the outputs of the build process, that is, the binary files built from your source code.\nWhat the installArtifact() method do is to install (or copy) the built target objects that you defined to this zig-out directory. This means that, if you do not install the target objects you define in your build script, these target objects are essentially discarded at the end of the build process.\nFor example, you might be building a project that uses a third party library that is built together with the project. So, when you build your project, you would need first, to build the third party library, and then, you link it with the source code of your project. So, in this case, we have two binary files that are generated in the build process (the executable file of your project, and the third party library). But only one is of interest, which is the executable file of our project. We can discard the binary file of the third party library, by simply not installing it into this zig-out directory.\nThis installArtifact() method is pretty straightforward. Just remember to apply it to every target object that you want to save into the zig-out directory, like in the example below:\n\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nb.installArtifact(exe);",
     "crumbs": [
       "<span class='chapter-number'>9</span>  <span class='chapter-title'>Build System</span>"
     ]
@@ -1024,7 +1024,7 @@
     "href": "Chapters/12-file-op.html",
     "title": "13  Filesystem and Input/Output (IO)",
     "section": "",
-    "text": "13.1 Input/Output basics\nIf you have some experience in a high-level language, you have certainly used these input and output functionalities before in this language. In other words, you certainly have been in a situation where you needed to sent some output to the user, or, to receive an input from the user.\nFor example, in Python we can receive some input from the user by using the input() built-in function. But we can also print (or “show”) some output to the user by using the print() built-in function. So yes, if you have programmed before in Python, you certainly have used these functions once before.\nBut do you know how these functions relate back to your operating system (OS)? How exactly they are interacting with the resources of your OS to receive or sent some input/output. In essence, these input/output functions from high-level languages are just abstractions over the standard output and standard input channels of your operating system.\nThis means that we receive an input, or send some output, through the operating system. It is the OS that makes the bridge between the user and your program. Your program does not have a direct access to the user. It is the OS that intermediates every message exchanged between your program and the user.\nThe standard output and standard input channels of your OS are commonly known as the stdout and stdin channels of your OS, respectively. In some contexts, they are also called the standard output device and the standard input device. As the name suggests, the standard output is the channel through which output flows, while the standard input is the channel in which input flows.\nFurthermore, OS’s also normally create a dedicated channel for exchanging error messages, which is known as the standard error channel, or, the stderr channel. This is the channel to which error and warning messages are usually sent to. These are the messages that are normally displayed in red-like or orange-like colors into your terminal.\nNormally, every OS (e.g. Windows, MacOS, Linux, etc.) creates a dedicated and separate set of standard output, standard error and standard input channels for every single program (or process) that runs in your computer. This means that every program you write have a dedicated stdin, stderr and stdout that are separate from the stdin, stderr and stdout of other programs and processes that are currently running.\nThis is a behaviour from your OS. This does not come from the programming language that you are using. Because as I sad earlier, input and output in programming languages, especially in high-level ones, are just a simple abstraction over the stdin, stderr and stdout from your current OS. That is, your OS is the intermediary between every input/output operation made in your program, regardless of the programming language that you are using.",
+    "text": "13.1 Input/Output basics\nIf you have some experience in a high-level language, you have certainly used these input and output functionalities before in this language. In other words, you certainly have been in a situation where you needed to sent some output to the user, or, to receive an input from the user.\nFor example, in Python we can receive some input from the user by using the input() built-in function. But we can also print (or “show”) some output to the user by using the print() built-in function. So yes, if you have programmed before in Python, you certainly have used these functions once before.\nBut do you know how these functions relate back to your operating system (OS)? How exactly they are interacting with the resources of your OS to receive or sent some input/output. In essence, these input/output functions from high-level languages are just abstractions over the standard output and standard input channels of your operating system.\nThis means that we receive an input, or send some output, through the operating system. It is the OS that makes the bridge between the user and your program. Your program does not have a direct access to the user. It is the OS that intermediates every message exchanged between your program and the user.\nThe standard output and standard input channels of your OS are commonly known as the stdout and stdin channels of your OS, respectively. In some contexts, they are also called the standard output device and the standard input device. As the name suggests, the standard output is the channel through which output flows, while the standard input is the channel in which input flows.\nFurthermore, OS’s also normally create a dedicated channel for exchanging error messages, which is known as the standard error channel, or, the stderr channel. This is the channel to which error and warning messages are usually sent to. These are the messages that are normally displayed in red-like or orange-like colors into your terminal.\nNormally, every OS (e.g. Windows, macOS, Linux, etc.) creates a dedicated and separate set of standard output, standard error and standard input channels for every single program (or process) that runs in your computer. This means that every program you write have a dedicated stdin, stderr and stdout that are separate from the stdin, stderr and stdout of other programs and processes that are currently running.\nThis is a behaviour from your OS. This does not come from the programming language that you are using. Because as I sad earlier, input and output in programming languages, especially in high-level ones, are just a simple abstraction over the stdin, stderr and stdout from your current OS. That is, your OS is the intermediary between every input/output operation made in your program, regardless of the programming language that you are using.",
     "crumbs": [
       "<span class='chapter-number'>13</span>  <span class='chapter-title'>Filesystem and Input/Output (IO)</span>"
     ]
@@ -1054,7 +1054,7 @@
     "href": "Chapters/12-file-op.html#filesystem-basics",
     "title": "13  Filesystem and Input/Output (IO)",
     "section": "13.3 Filesystem basics",
-    "text": "13.3 Filesystem basics\nNow that we have discussed the basics around Input/Output operations in Zig, we need to talk about the basics around filesystems, which is another core part of any operating system. Also, filesystems are related to input/output, because the files that we store and create in our computer are considered an IO resource, as we described at Section 13.1.2.\n\n13.3.1 The concept of current working directory (CWD)\nThe working directory is the folder on your computer where you are currently rooted at. In other words, it is the folder that your program is currently looking at. Therefore, whenever you are executing a program, this program is always working with a specific folder on your computer. It is always in this folder that the program will initially look for the files you require, and it is also in this folder that the program will initially save all the files you ask it to save.\nThe working directory is determined by the folder from which you invoke your program in the terminal. In other words, if you are in the terminal of your OS, and you execute a binary file (i.e. a program) from this terminal, the folder to which your terminal is pointing at is the current working directory of your program that is being executed.\nAt Figure 13.3 we have an example of me executing a program from the terminal. We are executing the program outputted by the zig compiler by compiling the Zig module named hello.zig. The CWD in this case is the zig-book folder. In other words, while the hello.zig program is executing, it will be looking at the zig-book folder, and any file operation that we perform inside this program, will be using this zig-book folder as the “starting point”, or, as the “central focus”.\n\n\n\n\n\n\nFigure 13.3: Executing a program from the terminal\n\n\n\nJust because we are rooted inside a particular folder (in the case of Figure 13.3, the zig-book folder) of our computer, it doesn’t mean that we cannot access or write resources in other locations of our computer. The current working directory (CWD) mechanism just defines where your program will look first for the files you ask for. This does not prevent you from accessing files that are located elsewhere on your computer. However, to access any file that is in a folder other than your current working directory, you must provide a path to that file or folder.\n\n\n13.3.2 The concept of paths\nA path is essentially a location. It points to a location in your filesystem. We use paths to describe the location of files and folders in our computer. One important aspect about paths is that they are always written inside strings, i.e. they are always provided as text values.\nThere are two types of paths that you can provide to any program in any OS: a relative path, or an absolute path. Absolute paths are paths that start at the root of your filesystem, and go all the way to the file name or the specific folder that you are referring to. This type of path is called absolute, because it points to an unique and absolute location on your computer. That is, there is no other existing location on your computer that corresponds to this path. It is an unique identifier.\nIn Windows, an absolute path is a path that starts with a hard disk identifier (e.g. C:/Users/pedro). On the other hand, absolute paths in Linux and MacOS, are paths that start with a forward slash character (e.g. /usr/local/bin). Notice that a path is composed by “segments”. Each segment is connected to each other by a slash character (\\ or /). On Windows, the backward slash (\\) is normally used to connect the path segments. While on Linux and MacOS, the forward slash (/) is the character used to connect path segments.\nA relative path is a path that start at the CWD. In other words, a relative path is “relative to the CWD”. The path used to access the hello.zig file at Figure 13.3 is an example of a relative path. This path is reproduced below. This path begins at the CWD, which in the context of Figure 13.3, is the zig-book folder, then, it goes to the ZigExamples folder, then, into zig-basics, then, to the hello.zig file.\nZigExamples/zig-basics/hello_world.zig\n\n\n13.3.3 Path wildcards\nWhen providing paths, especially relative paths, you have the option of using a wildcard. There are two commonly used wildcards in paths, which are “one period” (.) and “two periods” (..). In other words, these two specific characters have special meanings when used in paths, and can be used on any operating system (Mac, Windows, Linux, etc.). That is, they are “cross platform”.\nThe “one period” represents an alias for the current directory. This means that the relative paths \"./Course/Data/covid.csv\" and \"Course/Data/covid.csv\" are equivalent. On the other hand, the “two periods” refers to the previous directory. For example, the path \"Course/..\" is equivalent to the path \".\", that is, the current working directory.\nTherefore, the path \"Course/..\" refers to the folder before the Course folder. As another example, the path \"src/writexml/../xml.cpp\" refers to the file xml.cpp that is inside the folder before the writexml folder, which in this example is the src folder. Therefore, this path is equivalent to \"src/xml.cpp\".",
+    "text": "13.3 Filesystem basics\nNow that we have discussed the basics around Input/Output operations in Zig, we need to talk about the basics around filesystems, which is another core part of any operating system. Also, filesystems are related to input/output, because the files that we store and create in our computer are considered an IO resource, as we described at Section 13.1.2.\n\n13.3.1 The concept of current working directory (CWD)\nThe working directory is the folder on your computer where you are currently rooted at. In other words, it is the folder that your program is currently looking at. Therefore, whenever you are executing a program, this program is always working with a specific folder on your computer. It is always in this folder that the program will initially look for the files you require, and it is also in this folder that the program will initially save all the files you ask it to save.\nThe working directory is determined by the folder from which you invoke your program in the terminal. In other words, if you are in the terminal of your OS, and you execute a binary file (i.e. a program) from this terminal, the folder to which your terminal is pointing at is the current working directory of your program that is being executed.\nAt Figure 13.3 we have an example of me executing a program from the terminal. We are executing the program outputted by the zig compiler by compiling the Zig module named hello.zig. The CWD in this case is the zig-book folder. In other words, while the hello.zig program is executing, it will be looking at the zig-book folder, and any file operation that we perform inside this program, will be using this zig-book folder as the “starting point”, or, as the “central focus”.\n\n\n\n\n\n\nFigure 13.3: Executing a program from the terminal\n\n\n\nJust because we are rooted inside a particular folder (in the case of Figure 13.3, the zig-book folder) of our computer, it doesn’t mean that we cannot access or write resources in other locations of our computer. The current working directory (CWD) mechanism just defines where your program will look first for the files you ask for. This does not prevent you from accessing files that are located elsewhere on your computer. However, to access any file that is in a folder other than your current working directory, you must provide a path to that file or folder.\n\n\n13.3.2 The concept of paths\nA path is essentially a location. It points to a location in your filesystem. We use paths to describe the location of files and folders in our computer. One important aspect about paths is that they are always written inside strings, i.e. they are always provided as text values.\nThere are two types of paths that you can provide to any program in any OS: a relative path, or an absolute path. Absolute paths are paths that start at the root of your filesystem, and go all the way to the file name or the specific folder that you are referring to. This type of path is called absolute, because it points to an unique and absolute location on your computer. That is, there is no other existing location on your computer that corresponds to this path. It is an unique identifier.\nIn Windows, an absolute path is a path that starts with a hard disk identifier (e.g. C:/Users/pedro). On the other hand, absolute paths in Linux and macOS, are paths that start with a forward slash character (e.g. /usr/local/bin). Notice that a path is composed by “segments”. Each segment is connected to each other by a slash character (\\ or /). On Windows, the backward slash (\\) is normally used to connect the path segments. While on Linux and macOS, the forward slash (/) is the character used to connect path segments.\nA relative path is a path that start at the CWD. In other words, a relative path is “relative to the CWD”. The path used to access the hello.zig file at Figure 13.3 is an example of a relative path. This path is reproduced below. This path begins at the CWD, which in the context of Figure 13.3, is the zig-book folder, then, it goes to the ZigExamples folder, then, into zig-basics, then, to the hello.zig file.\nZigExamples/zig-basics/hello_world.zig\n\n\n13.3.3 Path wildcards\nWhen providing paths, especially relative paths, you have the option of using a wildcard. There are two commonly used wildcards in paths, which are “one period” (.) and “two periods” (..). In other words, these two specific characters have special meanings when used in paths, and can be used on any operating system (Mac, Windows, Linux, etc.). That is, they are “cross platform”.\nThe “one period” represents an alias for the current directory. This means that the relative paths \"./Course/Data/covid.csv\" and \"Course/Data/covid.csv\" are equivalent. On the other hand, the “two periods” refers to the previous directory. For example, the path \"Course/..\" is equivalent to the path \".\", that is, the current working directory.\nTherefore, the path \"Course/..\" refers to the folder before the Course folder. As another example, the path \"src/writexml/../xml.cpp\" refers to the file xml.cpp that is inside the folder before the writexml folder, which in this example is the src folder. Therefore, this path is equivalent to \"src/xml.cpp\".",
     "crumbs": [
       "<span class='chapter-number'>13</span>  <span class='chapter-title'>Filesystem and Input/Output (IO)</span>"
     ]
diff --git a/index.qmd b/index.qmd
index 079089b7..3a98532b 100644
--- a/index.qmd
+++ b/index.qmd
@@ -91,19 +91,18 @@ As you work through the book, you will learn:
 
 ## About the author {.unnumbered}
 
-Pedro Duarte Faria have a bachelor degree in Economics from Federal University of Ouro Preto - Brazil.
+Pedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.
 Currently, he is a Data Platform Engineer at [Blip](https://www.blip.ai/en/)[^blip], and
-an Associate Developer for Apache Spark 3.0 certified by Databricks.
+a Databricks Certified Associate Developer for Apache Spark 3.0.
 
 [^blip]: <https://www.blip.ai/en/>
 
 
-The author have more than 4 years of experience in the data industry. Developing data products, pipelines,
+The author has more than 4 years of experience in the data industry, developing data products, pipelines,
 reports and analysis for research institutions and some of the largest companies in the
-brazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.
+Brazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.
 
-But Pedro is also a passionate software developer that loves to
-learn and teach about programming.
+But Pedro is also a passionate software developer who loves to learn and teach about programming.
 Although Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several
 lectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),
 in addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).

From d92113ac38025882b49481f70fc0995c546187bc Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Thu, 30 Jan 2025 22:14:33 -0300
Subject: [PATCH 031/151] Add footnote

---
 Chapters/01-zig-weird.qmd                     |  4 +-
 .../01-zig-weird/execute-results/html.json    |  8 +-
 docs/Chapters/01-zig-weird.html               | 77 ++++++++++---------
 docs/search.json                              | 12 +--
 4 files changed, 51 insertions(+), 50 deletions(-)

diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index d7778730..0f449586 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -259,10 +259,12 @@ We can see a small change. The return type of the function (`void`) is accompani
 This exclamation mark tells us that this `main()` function might return an error.
 
 Is worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),
-or an unsigned 8-bit integer (`u8`) value, or an error. In other words, you can write your `main()` function in Zig
+or an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig
 to return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,
 which returns an integer value that usually serves as a "status code" for the process.
 
+[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>
+
 In this example, the return type annotation of `main()` indicates that this function can either
 return nothing (`void`), or return an error. This exclamation mark in the return type annotation
 is an interesting and powerful feature of Zig. In summary, if you write a function and something inside
diff --git a/_freeze/Chapters/01-zig-weird/execute-results/html.json b/_freeze/Chapters/01-zig-weird/execute-results/html.json
index e1ca16e1..11a7f613 100644
--- a/_freeze/Chapters/01-zig-weird/execute-results/html.json
+++ b/_freeze/Chapters/01-zig-weird/execute-results/html.json
@@ -1,11 +1,9 @@
 {
-  "hash": "dcb8e27545ba3d418f25136ae98cf023",
+  "hash": "3e66c278de9f34fb70ff9abb53f3d4ce",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\nlanguage, it is still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. They really make it sometimes hard to debug\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscures the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that get's compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e. it is where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `ìnit` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contain Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nTherefore, Zig contains a native build system in it, and\nwe can use this build system to write small scripts in Zig,\nwhich describes the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e. creating new objects)\nare made in Zig. You can create a new object in Zig by using the following syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). At @sec-assignments we talk more about objects in general.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that at @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIs worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value, or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt is like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portale C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nOn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOs. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e. the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. Thus, if you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith a \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, operations like accessing the `stdout` (or opening a file) on Windows\ndepends on resources that are available only at *runtime* (you will learn more about compile-time\nversus runtime at @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword at @sec-comptime.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation at a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues \n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described at @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig latter in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig? \nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar in our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentations.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It is a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (at YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e. identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compiles successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nIn contrast, if you use `var`, then, the object created is a variable object.\nWith `var` you can declare this object in your source code, and then,\nchange the value of this object how many times you want over future points\nin your source code.\n\nSo, using the same code example exposed above, if I change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it is an \"variable object\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIs important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code use this object while it is uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object. \n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e. if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to an special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It is discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also get's discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e. the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\nIs worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array. \n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it is a slice that\naccess all elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" at @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth at @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially at @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned at @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e. the start and the end of this range)\nis known at compile-time, the slice object that get's created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nat @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that get's created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e. a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can \ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n```\n:::\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat get's created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, the `slice` object have a runtime known range, because the end index of the range\nis not known at compile time. In other words, the size of the array at `buffer` is not known\nat compile time. When we execute this program, the size of the array might be 10, or, it might be 12\ndepending on where we execute it. Therefore, we don't know at compile time if\nthe slice object have a range of size 10, or, a range of size 12.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e. a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented at @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e. `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIs worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e. the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause is much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e. if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it is a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIs important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligates you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig at @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers at @sec-root-file and especially at @sec-assignments.\n- How strings work in Zig at @sec-zig-strings.\n- How to use arrays and slices at @sec-arrays.\n- How to import functionality from other Zig modules at @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* at @sec-structs-and-oop.\n- Basic control flow syntax at @sec-zig-control-flow.\n- Enums at @sec-enum;\n- Pointers and Optionals at @sec-pointer;\n- Error handling with `try` and `catch` at @sec-error-handling;\n- Unit tests at @sec-unittests;\n- Vectors at @sec-vectors-simd;\n- Build System at @sec-build-system;\n\n\n\n\n",
-    "supporting": [
-      "01-zig-weird_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\nlanguage, it is still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. They really make it sometimes hard to debug\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscures the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that get's compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e. it is where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `ìnit` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contain Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nTherefore, Zig contains a native build system in it, and\nwe can use this build system to write small scripts in Zig,\nwhich describes the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e. creating new objects)\nare made in Zig. You can create a new object in Zig by using the following syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). At @sec-assignments we talk more about objects in general.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that at @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIs worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt is like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portale C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nOn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOs. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e. the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. Thus, if you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith a \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, operations like accessing the `stdout` (or opening a file) on Windows\ndepends on resources that are available only at *runtime* (you will learn more about compile-time\nversus runtime at @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword at @sec-comptime.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation at a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues \n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described at @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig latter in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig? \nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar in our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentations.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It is a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (at YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e. identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compiles successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nIn contrast, if you use `var`, then, the object created is a variable object.\nWith `var` you can declare this object in your source code, and then,\nchange the value of this object how many times you want over future points\nin your source code.\n\nSo, using the same code example exposed above, if I change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it is an \"variable object\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIs important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code use this object while it is uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object. \n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e. if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to an special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It is discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also get's discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e. the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\n\nIs worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array. \n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it is a slice that\naccess all elements in the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" at @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth at @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially at @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned at @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e. the start and the end of this range)\nis known at compile-time, the slice object that get's created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nat @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that get's created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e. a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can \ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n```\n:::\n\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat get's created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, the `slice` object have a runtime known range, because the end index of the range\nis not known at compile time. In other words, the size of the array at `buffer` is not known\nat compile time. When we execute this program, the size of the array might be 10, or, it might be 12\ndepending on where we execute it. Therefore, we don't know at compile time if\nthe slice object have a range of size 10, or, a range of size 12.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e. a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented at @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e. `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIs worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e. the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause is much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e. if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it is a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIs important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligates you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig at @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers at @sec-root-file and especially at @sec-assignments.\n- How strings work in Zig at @sec-zig-strings.\n- How to use arrays and slices at @sec-arrays.\n- How to import functionality from other Zig modules at @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* at @sec-structs-and-oop.\n- Basic control flow syntax at @sec-zig-control-flow.\n- Enums at @sec-enum;\n- Pointers and Optionals at @sec-pointer;\n- Error handling with `try` and `catch` at @sec-error-handling;\n- Unit tests at @sec-unittests;\n- Vectors at @sec-vectors-simd;\n- Build System at @sec-build-system;\n\n\n\n\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/docs/Chapters/01-zig-weird.html b/docs/Chapters/01-zig-weird.html
index b091a3de..2f44cd2d 100644
--- a/docs/Chapters/01-zig-weird.html
+++ b/docs/Chapters/01-zig-weird.html
@@ -433,7 +433,7 @@ <h3 data-number="1.2.2" class="anchored" data-anchor-id="sec-root-file"><span cl
 <h3 data-number="1.2.3" class="anchored" data-anchor-id="sec-main-file"><span class="header-section-number">1.2.3</span> The <code>main.zig</code> file</h3>
 <p>Now that we have learned a lot about Zig’s syntax from the <code>root.zig</code> file, let’s take a look at the <code>main.zig</code> file. A lot of the elements we saw in <code>root.zig</code> are also present in <code>main.zig</code>. But there are some other elements that we haven’t seen yet, so let’s dive in.</p>
 <p>First, look at the return type of the <code>main()</code> function in this file. We can see a small change. The return type of the function (<code>void</code>) is accompanied by an exclamation mark (<code>!</code>). This exclamation mark tells us that this <code>main()</code> function might return an error.</p>
-<p>Is worth noting that, a <code>main()</code> function in Zig is allowed to return nothing (<code>void</code>), or an unsigned 8-bit integer (<code>u8</code>) value, or an error. In other words, you can write your <code>main()</code> function in Zig to return essentially nothing (<code>void</code>), or, if you prefer, you can also write a more C-like <code>main()</code> function, which returns an integer value that usually serves as a “status code” for the process.</p>
+<p>Is worth noting that, a <code>main()</code> function in Zig is allowed to return nothing (<code>void</code>), or an unsigned 8-bit integer (<code>u8</code>) value<a href="#fn6" class="footnote-ref" id="fnref6" role="doc-noteref"><sup>6</sup></a>, or an error. In other words, you can write your <code>main()</code> function in Zig to return essentially nothing (<code>void</code>), or, if you prefer, you can also write a more C-like <code>main()</code> function, which returns an integer value that usually serves as a “status code” for the process.</p>
 <p>In this example, the return type annotation of <code>main()</code> indicates that this function can either return nothing (<code>void</code>), or return an error. This exclamation mark in the return type annotation is an interesting and powerful feature of Zig. In summary, if you write a function and something inside the body of this function might return an error, then, you are forced to:</p>
 <ul>
 <li>either add the exclamation mark to the return type of the function and make it clear that this function might return an error.</li>
@@ -504,7 +504,7 @@ <h3 data-number="1.2.6" class="anchored" data-anchor-id="important-note-for-wind
 <span id="cb16-6"><a href="#cb16-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Hello</code></pre>
-<p>You can read more details about this Windows-specific limitation at a couple of GitHub issues opened at the official Zig repository. More specifically, the issues 17186 <a href="#fn6" class="footnote-ref" id="fnref6" role="doc-noteref"><sup>6</sup></a> and 19864 <a href="#fn7" class="footnote-ref" id="fnref7" role="doc-noteref"><sup>7</sup></a>.</p>
+<p>You can read more details about this Windows-specific limitation at a couple of GitHub issues opened at the official Zig repository. More specifically, the issues 17186 <a href="#fn7" class="footnote-ref" id="fnref7" role="doc-noteref"><sup>7</sup></a> and 19864 <a href="#fn8" class="footnote-ref" id="fnref8" role="doc-noteref"><sup>8</sup></a>.</p>
 </section>
 <section id="sec-compile-project" class="level3" data-number="1.2.7">
 <h3 data-number="1.2.7" class="anchored" data-anchor-id="sec-compile-project"><span class="header-section-number">1.2.7</span> Compiling the entire project</h3>
@@ -529,17 +529,17 @@ <h2 data-number="1.3" class="anchored" data-anchor-id="how-to-learn-zig"><span c
 <li>Discord, Slack, Telegram, and others: <a href="https://github.com/ziglang/zig/wiki/Community" class="uri">https://github.com/ziglang/zig/wiki/Community</a>;</li>
 </ul>
 <p>Now, one of the best ways to learn Zig is to simply read Zig code. Try to read Zig code often, and things will become more clear. A C/C++ programmer would also probably give you this same tip. Because this strategy really works!</p>
-<p>Now, where can you find Zig code to read? I personally think that, the best way of reading Zig code is to read the source code of the Zig Standard Library. The Zig Standard Library is available at the <a href="https://github.com/ziglang/zig/tree/master/lib/std"><code>lib/std</code> folder</a><a href="#fn8" class="footnote-ref" id="fnref8" role="doc-noteref"><sup>8</sup></a> on the official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.</p>
+<p>Now, where can you find Zig code to read? I personally think that, the best way of reading Zig code is to read the source code of the Zig Standard Library. The Zig Standard Library is available at the <a href="https://github.com/ziglang/zig/tree/master/lib/std"><code>lib/std</code> folder</a><a href="#fn9" class="footnote-ref" id="fnref9" role="doc-noteref"><sup>9</sup></a> on the official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.</p>
 <p>Also, a great alternative is to read code from other large Zig codebases, such as:</p>
 <ol type="1">
-<li>the <a href="https://github.com/oven-sh/bun">Javascript runtime Bun</a><a href="#fn9" class="footnote-ref" id="fnref9" role="doc-noteref"><sup>9</sup></a>.</li>
-<li>the <a href="https://github.com/hexops/mach">game engine Mach</a><a href="#fn10" class="footnote-ref" id="fnref10" role="doc-noteref"><sup>10</sup></a>.</li>
-<li>a <a href="https://github.com/cgbur/llama2.zig/tree/main">LLama 2 LLM model implementation in Zig</a><a href="#fn11" class="footnote-ref" id="fnref11" role="doc-noteref"><sup>11</sup></a>.</li>
-<li>the <a href="https://github.com/tigerbeetle/tigerbeetle">financial transactions database <code>tigerbeetle</code></a><a href="#fn12" class="footnote-ref" id="fnref12" role="doc-noteref"><sup>12</sup></a>.</li>
-<li>the <a href="https://github.com/Hejsil/zig-clap">command-line arguments parser <code>zig-clap</code></a><a href="#fn13" class="footnote-ref" id="fnref13" role="doc-noteref"><sup>13</sup></a>.</li>
-<li>the <a href="https://github.com/capy-ui/capy">UI framework <code>capy</code></a><a href="#fn14" class="footnote-ref" id="fnref14" role="doc-noteref"><sup>14</sup></a>.</li>
-<li>the <a href="https://github.com/zigtools/zls">Language Protocol implementation for Zig, <code>zls</code></a><a href="#fn15" class="footnote-ref" id="fnref15" role="doc-noteref"><sup>15</sup></a>.</li>
-<li>the <a href="https://github.com/mitchellh/libxev">event-loop library <code>libxev</code></a><a href="#fn16" class="footnote-ref" id="fnref16" role="doc-noteref"><sup>16</sup></a>.</li>
+<li>the <a href="https://github.com/oven-sh/bun">Javascript runtime Bun</a><a href="#fn10" class="footnote-ref" id="fnref10" role="doc-noteref"><sup>10</sup></a>.</li>
+<li>the <a href="https://github.com/hexops/mach">game engine Mach</a><a href="#fn11" class="footnote-ref" id="fnref11" role="doc-noteref"><sup>11</sup></a>.</li>
+<li>a <a href="https://github.com/cgbur/llama2.zig/tree/main">LLama 2 LLM model implementation in Zig</a><a href="#fn12" class="footnote-ref" id="fnref12" role="doc-noteref"><sup>12</sup></a>.</li>
+<li>the <a href="https://github.com/tigerbeetle/tigerbeetle">financial transactions database <code>tigerbeetle</code></a><a href="#fn13" class="footnote-ref" id="fnref13" role="doc-noteref"><sup>13</sup></a>.</li>
+<li>the <a href="https://github.com/Hejsil/zig-clap">command-line arguments parser <code>zig-clap</code></a><a href="#fn14" class="footnote-ref" id="fnref14" role="doc-noteref"><sup>14</sup></a>.</li>
+<li>the <a href="https://github.com/capy-ui/capy">UI framework <code>capy</code></a><a href="#fn15" class="footnote-ref" id="fnref15" role="doc-noteref"><sup>15</sup></a>.</li>
+<li>the <a href="https://github.com/zigtools/zls">Language Protocol implementation for Zig, <code>zls</code></a><a href="#fn16" class="footnote-ref" id="fnref16" role="doc-noteref"><sup>16</sup></a>.</li>
+<li>the <a href="https://github.com/mitchellh/libxev">event-loop library <code>libxev</code></a><a href="#fn17" class="footnote-ref" id="fnref17" role="doc-noteref"><sup>17</sup></a>.</li>
 </ol>
 <p>All these assets are available on GitHub, and this is great, because we can use the GitHub search bar in our advantage, to find Zig code that fits our description. For example, you can always include <code>lang:Zig</code> in the GitHub search bar when you are searching for a particular pattern. This will limit the search to only Zig modules.</p>
 <p>Also, a great alternative is to consult online resources and documentations. Here is a quick list of resources that I personally use from time to time to learn more about the language each day:</p>
@@ -552,9 +552,9 @@ <h2 data-number="1.3" class="anchored" data-anchor-id="how-to-learn-zig"><span c
 <li>Read the code written by one of the Zig core team members: <a href="https://github.com/kubkon" class="uri">https://github.com/kubkon</a>;</li>
 <li>Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <a href="https://www.youtube.com/@ZigSHOWTIME/videos" class="uri">https://www.youtube.com/@ZigSHOWTIME/videos</a>;</li>
 </ul>
-<p>Another great strategy to learn Zig, or honestly, to learn any language you want, is to practice it by solving exercises. For example, there is a famous repository in the Zig community called <a href="https://ziglings.org">Ziglings</a><a href="#fn17" class="footnote-ref" id="fnref17" role="doc-noteref"><sup>17</sup></a> , which contains more than 100 small exercises that you can solve. It is a repository of tiny programs written in Zig that are currently broken, and your responsibility is to fix these programs, and make them work again.</p>
-<p>A famous tech YouTuber known as <em>The Primeagen</em> also posted some videos (at YouTube) where he solves these exercises from Ziglings. The first video is named <a href="https://www.youtube.com/watch?v=OPuztQfM3Fg&amp;t=2524s&amp;ab_channel=TheVimeagen">“Trying Zig Part 1”</a><a href="#fn18" class="footnote-ref" id="fnref18" role="doc-noteref"><sup>18</sup></a>.</p>
-<p>Another great alternative, is to solve the <a href="https://adventofcode.com/">Advent of Code exercises</a><a href="#fn19" class="footnote-ref" id="fnref19" role="doc-noteref"><sup>19</sup></a>. There are people that already took the time to learn and solve the exercises, and they posted their solutions on GitHub as well, so, in case you need some resource to compare while solving the exercises, you can look at these two repositories:</p>
+<p>Another great strategy to learn Zig, or honestly, to learn any language you want, is to practice it by solving exercises. For example, there is a famous repository in the Zig community called <a href="https://ziglings.org">Ziglings</a><a href="#fn18" class="footnote-ref" id="fnref18" role="doc-noteref"><sup>18</sup></a> , which contains more than 100 small exercises that you can solve. It is a repository of tiny programs written in Zig that are currently broken, and your responsibility is to fix these programs, and make them work again.</p>
+<p>A famous tech YouTuber known as <em>The Primeagen</em> also posted some videos (at YouTube) where he solves these exercises from Ziglings. The first video is named <a href="https://www.youtube.com/watch?v=OPuztQfM3Fg&amp;t=2524s&amp;ab_channel=TheVimeagen">“Trying Zig Part 1”</a><a href="#fn19" class="footnote-ref" id="fnref19" role="doc-noteref"><sup>19</sup></a>.</p>
+<p>Another great alternative, is to solve the <a href="https://adventofcode.com/">Advent of Code exercises</a><a href="#fn20" class="footnote-ref" id="fnref20" role="doc-noteref"><sup>20</sup></a>. There are people that already took the time to learn and solve the exercises, and they posted their solutions on GitHub as well, so, in case you need some resource to compare while solving the exercises, you can look at these two repositories:</p>
 <ul>
 <li><a href="https://github.com/SpexGuy/Zig-AoC-Template" class="uri">https://github.com/SpexGuy/Zig-AoC-Template</a>;</li>
 <li><a href="https://github.com/fjebaker/advent-of-code-2022" class="uri">https://github.com/fjebaker/advent-of-code-2022</a>;</li>
@@ -647,7 +647,7 @@ <h3 data-number="1.4.4" class="anchored" data-anchor-id="you-must-mutate-every-v
 </section>
 <section id="sec-primitive-data-types" class="level2" data-number="1.5">
 <h2 data-number="1.5" class="anchored" data-anchor-id="sec-primitive-data-types"><span class="header-section-number">1.5</span> Primitive Data Types</h2>
-<p>Zig have many different primitive data types available for you to use. You can see the full list of available data types at the official <a href="https://ziglang.org/documentation/master/#Primitive-Types">Language Reference page</a><a href="#fn20" class="footnote-ref" id="fnref20" role="doc-noteref"><sup>20</sup></a>.</p>
+<p>Zig have many different primitive data types available for you to use. You can see the full list of available data types at the official <a href="https://ziglang.org/documentation/master/#Primitive-Types">Language Reference page</a><a href="#fn21" class="footnote-ref" id="fnref21" role="doc-noteref"><sup>21</sup></a>.</p>
 <p>But here is a quick list:</p>
 <ul>
 <li>Unsigned integers: <code>u8</code>, 8-bit integer; <code>u16</code>, 16-bit integer; <code>u32</code>, 32-bit integer; <code>u64</code>, 64-bit integer; <code>u128</code>, 128-bit integer.</li>
@@ -820,7 +820,7 @@ <h2 data-number="1.8" class="anchored" data-anchor-id="sec-zig-strings"><span cl
 <span id="cb48-3"><a href="#cb48-3" aria-hidden="true" tabindex="-1"></a><span class="co">// This is a string object:</span></span>
 <span id="cb48-4"><a href="#cb48-4" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> object: []<span class="kw">const</span> <span class="dt">u8</span> = <span class="st">"A string object"</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>Zig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every sequence of bytes you’re working with, but is not really Zig’s job to fix the encoding of your strings (you can use <a href="https://www.gnu.org/software/libiconv/"><code>iconv</code></a><a href="#fn21" class="footnote-ref" id="fnref21" role="doc-noteref"><sup>21</sup></a> for that). Today, most of the text in our modern world, especially on the web, should be UTF-8 encoded. So if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.</p>
+<p>Zig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every sequence of bytes you’re working with, but is not really Zig’s job to fix the encoding of your strings (you can use <a href="https://www.gnu.org/software/libiconv/"><code>iconv</code></a><a href="#fn22" class="footnote-ref" id="fnref22" role="doc-noteref"><sup>22</sup></a> for that). Today, most of the text in our modern world, especially on the web, should be UTF-8 encoded. So if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.</p>
 <p>Let’s take for example the word “Hello”. In UTF-8, this sequence of characters (H, e, l, l, o) is represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this sequence is <code>0x48</code>, <code>0x65</code>, <code>0x6C</code>, <code>0x6C</code>, <code>0x6F</code>. So if I take this sequence of hexadecimal values, and ask Zig to print this sequence of bytes as a sequence of characters (i.e.&nbsp;a string), then, the text “Hello” will be printed into the terminal:</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb49"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb49-1"><a href="#cb49-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
@@ -834,7 +834,7 @@ <h2 data-number="1.8" class="anchored" data-anchor-id="sec-zig-strings"><span cl
 <pre><code>Hello</code></pre>
 </div>
 </div>
-<p>If you want to see the actual bytes that represents a string in Zig, you can use a <code>for</code> loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal value to the terminal. You do that by using a <code>print()</code> statement with the <code>X</code> formatting specifier, like you would normally do with the <a href="https://cplusplus.com/reference/cstdio/printf/"><code>printf()</code> function</a><a href="#fn22" class="footnote-ref" id="fnref22" role="doc-noteref"><sup>22</sup></a> in C.</p>
+<p>If you want to see the actual bytes that represents a string in Zig, you can use a <code>for</code> loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal value to the terminal. You do that by using a <code>print()</code> statement with the <code>X</code> formatting specifier, like you would normally do with the <a href="https://cplusplus.com/reference/cstdio/printf/"><code>printf()</code> function</a><a href="#fn23" class="footnote-ref" id="fnref23" role="doc-noteref"><sup>23</sup></a> in C.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb51"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb51-1"><a href="#cb51-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb51-2"><a href="#cb51-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
@@ -1030,9 +1030,9 @@ <h3 data-number="1.8.4" class="anchored" data-anchor-id="sec-strings-useful-funs
 <h2 data-number="1.9" class="anchored" data-anchor-id="safety-in-zig"><span class="header-section-number">1.9</span> Safety in Zig</h2>
 <p>A general trend in modern low-level programming languages is safety. As our modern world becomes more interconnected with technology and computers, the data produced by all of this technology becomes one of the most important (and also, one of the most dangerous) assets that we have.</p>
 <p>This is probably the main reason why modern low-level programming languages have been giving great attention to safety, especially memory safety, because memory corruption is still the main target for hackers to exploit. The reality is that we don’t have an easy solution for this problem. For now, we only have techniques and strategies that mitigates these problems.</p>
-<p>As Richard Feldman explains on his <a href="https://www.youtube.com/watch?v=jIZpKpLCOiU&amp;ab_channel=GOTOConferences">most recent GOTO conference talk</a><a href="#fn23" class="footnote-ref" id="fnref23" role="doc-noteref"><sup>23</sup></a> , we haven’t figured it out yet a way to achieve <strong>true safety in technology</strong>. In other words, we haven’t found a way to build software that won’t be exploited with 100% certainty. We can greatly reduce the risks of our software being exploited, by ensuring memory safety for example. But this is not enough to achieve “true safety” territory.</p>
+<p>As Richard Feldman explains on his <a href="https://www.youtube.com/watch?v=jIZpKpLCOiU&amp;ab_channel=GOTOConferences">most recent GOTO conference talk</a><a href="#fn24" class="footnote-ref" id="fnref24" role="doc-noteref"><sup>24</sup></a> , we haven’t figured it out yet a way to achieve <strong>true safety in technology</strong>. In other words, we haven’t found a way to build software that won’t be exploited with 100% certainty. We can greatly reduce the risks of our software being exploited, by ensuring memory safety for example. But this is not enough to achieve “true safety” territory.</p>
 <p>Because even if you write your program in a “safe language”, hackers can still exploit failures in the operating system where your program is running (e.g.&nbsp;maybe the system where your code is running has a “backdoor exploit” that can still affect your code in unexpected ways), or also, they can exploit the features from the architecture of your computer. A recently found exploit that involves memory invalidation through a feature of “memory tags” present in ARM chips is an example of that <span class="citation" data-cites="exploit1">(<a href="../references.html#ref-exploit1" role="doc-biblioref">Kim et al. 2024</a>)</span>.</p>
-<p>The question is: what have Zig and other languages been doing to mitigate this problem? If we take Rust as an example, Rust is, for the most part<a href="#fn24" class="footnote-ref" id="fnref24" role="doc-noteref"><sup>24</sup></a>, a memory safe language by enforcing specific rules to the developer. In other words, the key feature of Rust, the <em>borrow checker</em>, forces you to follow a specific logic when you are writing your Rust code, and the Rust compiler will always complain everytime you try to go out of this pattern.</p>
+<p>The question is: what have Zig and other languages been doing to mitigate this problem? If we take Rust as an example, Rust is, for the most part<a href="#fn25" class="footnote-ref" id="fnref25" role="doc-noteref"><sup>25</sup></a>, a memory safe language by enforcing specific rules to the developer. In other words, the key feature of Rust, the <em>borrow checker</em>, forces you to follow a specific logic when you are writing your Rust code, and the Rust compiler will always complain everytime you try to go out of this pattern.</p>
 <p>In contrast, the Zig language is not a memory safe language by default. There are some memory safety features that you get for free in Zig, especially in arrays and pointer objects. But there are other tools offered by the language, that are not used by default. In other words, the <code>zig</code> compiler does not obligates you to use such tools.</p>
 <p>The tools listed below are related to memory safety. That is, they help you to achieve memory safety in your Zig code:</p>
 <ul>
@@ -1089,25 +1089,26 @@ <h2 data-number="1.10" class="anchored" data-anchor-id="other-parts-of-zig"><spa
 <li id="fn3"><p><a href="https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1" class="uri">https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1</a><a href="#fnref3" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
 <li id="fn4"><p><a href="https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md" class="uri">https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md</a><a href="#fnref4" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
 <li id="fn5"><p><a href="https://en.wikipedia.org/wiki/List_of_C-family_programming_languages" class="uri">https://en.wikipedia.org/wiki/List_of_C-family_programming_languages</a><a href="#fnref5" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn6"><p><a href="https://github.com/ziglang/zig/issues/17186" class="uri">https://github.com/ziglang/zig/issues/17186</a><a href="#fnref6" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn7"><p><a href="https://github.com/ziglang/zig/issues/19864" class="uri">https://github.com/ziglang/zig/issues/19864</a><a href="#fnref7" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn8"><p><a href="https://github.com/ziglang/zig/tree/master/lib/std" class="uri">https://github.com/ziglang/zig/tree/master/lib/std</a><a href="#fnref8" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn9"><p><a href="https://github.com/oven-sh/bun" class="uri">https://github.com/oven-sh/bun</a>.<a href="#fnref9" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn10"><p><a href="https://github.com/hexops/mach" class="uri">https://github.com/hexops/mach</a><a href="#fnref10" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn11"><p><a href="https://github.com/cgbur/llama2.zig/tree/main" class="uri">https://github.com/cgbur/llama2.zig/tree/main</a><a href="#fnref11" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn12"><p><a href="https://github.com/tigerbeetle/tigerbeetle" class="uri">https://github.com/tigerbeetle/tigerbeetle</a><a href="#fnref12" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn13"><p><a href="https://github.com/Hejsil/zig-clap" class="uri">https://github.com/Hejsil/zig-clap</a><a href="#fnref13" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn14"><p><a href="https://github.com/capy-ui/capy" class="uri">https://github.com/capy-ui/capy</a><a href="#fnref14" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn15"><p><a href="https://github.com/zigtools/zls" class="uri">https://github.com/zigtools/zls</a><a href="#fnref15" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn16"><p><a href="https://github.com/mitchellh/libxev" class="uri">https://github.com/mitchellh/libxev</a><a href="#fnref16" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn17"><p><a href="https://ziglings.org" class="uri">https://ziglings.org</a>.<a href="#fnref17" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn18"><p><a href="https://www.youtube.com/watch?v=OPuztQfM3Fg&amp;t=2524s&amp;ab_channel=TheVimeagen" class="uri">https://www.youtube.com/watch?v=OPuztQfM3Fg&amp;t=2524s&amp;ab_channel=TheVimeagen</a>.<a href="#fnref18" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn19"><p><a href="https://adventofcode.com/" class="uri">https://adventofcode.com/</a><a href="#fnref19" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn20"><p><a href="https://ziglang.org/documentation/master/#Primitive-Types" class="uri">https://ziglang.org/documentation/master/#Primitive-Types</a>.<a href="#fnref20" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn21"><p><a href="https://www.gnu.org/software/libiconv/" class="uri">https://www.gnu.org/software/libiconv/</a><a href="#fnref21" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn22"><p><a href="https://cplusplus.com/reference/cstdio/printf/" class="uri">https://cplusplus.com/reference/cstdio/printf/</a><a href="#fnref22" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn23"><p><a href="https://www.youtube.com/watch?v=jIZpKpLCOiU&amp;ab_channel=GOTOConferences" class="uri">https://www.youtube.com/watch?v=jIZpKpLCOiU&amp;ab_channel=GOTOConferences</a><a href="#fnref23" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn24"><p>Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (<em>foreign function interface</em>), which disables the borrow-checker features through the <code>unsafe</code> keyword.<a href="#fnref24" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn6"><p>You can see an example of a <code>main()</code> function that returns an <code>u8</code> value in the <code>return-integer.zig</code> file, <a href="https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig" class="uri">https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig</a><a href="#fnref6" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn7"><p><a href="https://github.com/ziglang/zig/issues/17186" class="uri">https://github.com/ziglang/zig/issues/17186</a><a href="#fnref7" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn8"><p><a href="https://github.com/ziglang/zig/issues/19864" class="uri">https://github.com/ziglang/zig/issues/19864</a><a href="#fnref8" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn9"><p><a href="https://github.com/ziglang/zig/tree/master/lib/std" class="uri">https://github.com/ziglang/zig/tree/master/lib/std</a><a href="#fnref9" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn10"><p><a href="https://github.com/oven-sh/bun" class="uri">https://github.com/oven-sh/bun</a>.<a href="#fnref10" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn11"><p><a href="https://github.com/hexops/mach" class="uri">https://github.com/hexops/mach</a><a href="#fnref11" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn12"><p><a href="https://github.com/cgbur/llama2.zig/tree/main" class="uri">https://github.com/cgbur/llama2.zig/tree/main</a><a href="#fnref12" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn13"><p><a href="https://github.com/tigerbeetle/tigerbeetle" class="uri">https://github.com/tigerbeetle/tigerbeetle</a><a href="#fnref13" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn14"><p><a href="https://github.com/Hejsil/zig-clap" class="uri">https://github.com/Hejsil/zig-clap</a><a href="#fnref14" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn15"><p><a href="https://github.com/capy-ui/capy" class="uri">https://github.com/capy-ui/capy</a><a href="#fnref15" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn16"><p><a href="https://github.com/zigtools/zls" class="uri">https://github.com/zigtools/zls</a><a href="#fnref16" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn17"><p><a href="https://github.com/mitchellh/libxev" class="uri">https://github.com/mitchellh/libxev</a><a href="#fnref17" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn18"><p><a href="https://ziglings.org" class="uri">https://ziglings.org</a>.<a href="#fnref18" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn19"><p><a href="https://www.youtube.com/watch?v=OPuztQfM3Fg&amp;t=2524s&amp;ab_channel=TheVimeagen" class="uri">https://www.youtube.com/watch?v=OPuztQfM3Fg&amp;t=2524s&amp;ab_channel=TheVimeagen</a>.<a href="#fnref19" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn20"><p><a href="https://adventofcode.com/" class="uri">https://adventofcode.com/</a><a href="#fnref20" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn21"><p><a href="https://ziglang.org/documentation/master/#Primitive-Types" class="uri">https://ziglang.org/documentation/master/#Primitive-Types</a>.<a href="#fnref21" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn22"><p><a href="https://www.gnu.org/software/libiconv/" class="uri">https://www.gnu.org/software/libiconv/</a><a href="#fnref22" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn23"><p><a href="https://cplusplus.com/reference/cstdio/printf/" class="uri">https://cplusplus.com/reference/cstdio/printf/</a><a href="#fnref23" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn24"><p><a href="https://www.youtube.com/watch?v=jIZpKpLCOiU&amp;ab_channel=GOTOConferences" class="uri">https://www.youtube.com/watch?v=jIZpKpLCOiU&amp;ab_channel=GOTOConferences</a><a href="#fnref24" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn25"><p>Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (<em>foreign function interface</em>), which disables the borrow-checker features through the <code>unsafe</code> keyword.<a href="#fnref25" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
 </ol>
 </section>
 
diff --git a/docs/search.json b/docs/search.json
index dde3ce1a..7c847548 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -124,7 +124,7 @@
     "href": "Chapters/01-zig-weird.html#hello-world-in-zig",
     "title": "1  Introducing Zig",
     "section": "1.2 Hello world in Zig",
-    "text": "1.2 Hello world in Zig\nWe begin our journey in Zig by creating a small “Hello World” program. To start a new Zig project in your computer, you simply call the init command from the zig compiler. Just create a new directory in your computer, then, init a new Zig project inside this directory, like this:\nmkdir hello_world\ncd hello_world\nzig init\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n\n1.2.1 Understanding the project files\nAfter you run the init command from the zig compiler, some new files are created inside of your current directory. First, a “source” (src) directory is created, containing two files, main.zig and root.zig. Each .zig file is a separate Zig module, which is simply a text file that contains some Zig code.\nBy convention, the main.zig module is where your main function lives. Thus, if you are building an executable program in Zig, you need to declare a main() function, which represents the entrypoint of your program, i.e. it is where the execution of your program begins.\nHowever, if you are building a library (instead of an executable program), then, the normal procedure is to delete this main.zig file and start with the root.zig module. By convention, the root.zig module is the root source file of your library.\ntree .\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\nThe ìnit command also creates two additional files in our working directory: build.zig and build.zig.zon. The first file (build.zig) represents a build script written in Zig. This script is executed when you call the build command from the zig compiler. In other words, this file contain Zig code that executes the necessary steps to build the entire project.\nLow-level languages normally use a compiler to build your source code into binary executables or binary libraries. Nevertheless, this process of compiling your source code and building binary executables or binary libraries from it, became a real challenge in the programming world, once the projects became bigger and bigger. As a result, programmers created “build systems”, which are a second set of tools designed to make this process of compiling and building complex projects, easier.\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja, which are used to build complex C and C++ projects. With these systems, you can write scripts, which are called “build scripts”. They simply are scripts that describes the necessary steps to compile/build your project.\nHowever, these are separate tools, that do not belong to C/C++ compilers, like gcc or clang. As a result, in C/C++ projects, you have not only to install and manage your C/C++ compilers, but you also have to install and manage these build systems separately.\nIn Zig, we don’t need to use a separate set of tools to build our projects, because a build system is embedded inside the language itself. Therefore, Zig contains a native build system in it, and we can use this build system to write small scripts in Zig, which describes the necessary steps to build/compile our Zig project1. So, everything you need to build a complex Zig project is the zig compiler, and nothing more.\nThe second generated file (build.zig.zon) is a JSON-like file, in which you can describe your project, and also, declare a set of dependencies of your project that you want to fetch from the internet. In other words, you can use this build.zig.zon file to include a list of external libraries in your project.\nOne possible way to include an external Zig library in your project, is to manually build and install the library in your system, and just link your source code with the library at the build step of your project.\nHowever, if this external Zig library is available on GitHub for example, and it has a valid build.zig.zon file in root folder of the project, which describes the project, you can easily include this library in your project by simply listing this external library in your build.zig.zon file.\nIn other words, this build.zig.zon file works similarly to the package.json file in Javascript projects, or the Pipfile file in Python projects, or the Cargo.toml file in Rust projects. You can read more about this specific file in a couple of articles on the internet23, and you can also see the expected schema for this build.zig.zon file in a documentation file inside the official repository of Zig4.\n\n\n1.2.2 The file root.zig\nLet’s take a look into the root.zig file. You might have noticed that every line of code with an expression ends with a semicolon (;). This follows the syntax of a C-family programming language5.\nAlso, notice the @import() call at the first line. We use this built-in function to import functionality from other Zig modules into our current module. This @import() function works similarly to the #include pre-processor in C or C++, or, to the import statement in Python or Javascript code. In this example, we are importing the std module, which gives you access to the Zig Standard Library.\nIn this root.zig file, we can also see how assignments (i.e. creating new objects) are made in Zig. You can create a new object in Zig by using the following syntax (const|var) name = value;. In the example below, we are creating two constant objects (std and testing). At Section 1.4 we talk more about objects in general.\n\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n\nFunctions in Zig are declared using the fn keyword. In this root.zig module, we are declaring a function called add(), which has two arguments named a and b. The function returns an integer of the type i32 as result.\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit the type of an object in your code, if this type can be inferred by the zig compiler (we talk more about that at Section 2.4). But there are other situations where you do need to be explicit. For example, you do have to explicitly specify the type of each function argument, and also, the return type of every function that you create in Zig.\nWe specify the type of an object or a function argument in Zig by using a colon character (:) followed by the type after the name of this object/function argument. With the expressions a: i32 and b: i32, we know that both a and b arguments have type i32, which is a signed 32 bit integer. In this part, the syntax in Zig is identical to the syntax in Rust, which also specifies types by using the colon character.\nLastly, we have the return type of the function at the end of the line, before we open the curly braces to start writing the function’s body. In the example above, this type is also a signed 32 bit integer (i32) value.\nNotice that we also have an export keyword before the function declaration. This keyword is similar to the extern keyword in C. It exposes the function to make it available in the library API. Therefore, if you are writing a library for other people to use, you have to expose the functions you write in the public API of this library by using this export keyword. If we removed the export keyword from the add() function declaration, then, this function would be no longer exposed in the library object built by the zig compiler.\n\n\n1.2.3 The main.zig file\nNow that we have learned a lot about Zig’s syntax from the root.zig file, let’s take a look at the main.zig file. A lot of the elements we saw in root.zig are also present in main.zig. But there are some other elements that we haven’t seen yet, so let’s dive in.\nFirst, look at the return type of the main() function in this file. We can see a small change. The return type of the function (void) is accompanied by an exclamation mark (!). This exclamation mark tells us that this main() function might return an error.\nIs worth noting that, a main() function in Zig is allowed to return nothing (void), or an unsigned 8-bit integer (u8) value, or an error. In other words, you can write your main() function in Zig to return essentially nothing (void), or, if you prefer, you can also write a more C-like main() function, which returns an integer value that usually serves as a “status code” for the process.\nIn this example, the return type annotation of main() indicates that this function can either return nothing (void), or return an error. This exclamation mark in the return type annotation is an interesting and powerful feature of Zig. In summary, if you write a function and something inside the body of this function might return an error, then, you are forced to:\n\neither add the exclamation mark to the return type of the function and make it clear that this function might return an error.\nexplicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through a try catch pattern. Zig does have both try and catch keywords. But they work a little differently than what you’re probably used to in other languages.\nIf we look at the main() function below, you can see that we do have a try keyword on the 5th line. But we do not have a catch keyword in this code. In Zig, we use the try keyword to execute an expression that might return an error, which, in this example, is the stdout.print() expression.\nIn essence, the try keyword executes the expression stdout.print(). If this expression returns a valid value, then, the try keyword does absolutely nothing. It only passes the value forward. It is like if this try keyword was never there. However, if the expression does return an error, then, the try keyword will unwrap the error value, then, it returns this error from the function and also prints the current stack trace to stderr.\nThis might sound weird to you if you come from a high-level language. Because in high-level languages, such as Python, if an error occurs somewhere, this error is automatically returned and the execution of your program will automatically stop even if you don’t want to stop the execution. You are obligated to face the error.\n\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n\nAnother thing that you might have noticed in this code example, is that the main() function is marked with the pub keyword. It marks the main() function as a public function from this module. Every function in your Zig module is by default private to this Zig module and can only be called from within the module. Unless, you explicitly mark this function as a public function with the pub keyword.\nIf you think about it, this pub keyword in Zig does essentially the opposite of what the static keyword do in C/C++. By making a function “public” you allow other Zig modules to access and call this function. A calling Zig module imports another module by using the @import() built-in function, which makes all public functions from the imported module visible to the calling Zig module.\n\n\n1.2.4 Compiling your source code\nYou can compile your Zig modules into a binary executable by running the build-exe command from the zig compiler. You simply list all the Zig modules that you want to build after the build-exe command, separated by spaces. In the example below, we are compiling the module main.zig.\nzig build-exe src/main.zig\nSince we are building an executable, the zig compiler will look for a main() function declared in any of the files that you list after the build-exe command. If the compiler does not find a main() function declared somewhere, a compilation error will be raised, warning about this mistake.\nThe zig compiler also offers a build-lib and build-obj commands, which work the exact same way as the build-exe command. The only difference is that, they compile your Zig modules into a portale C ABI library, or, into object files, respectively.\nIn the case of the build-exe command, a binary executable file is created by the zig compiler in the root directory of your project. If we take a look now at the contents of our current directory, with a simple ls command, we can see the binary file called main that was created by the compiler.\nls\nbuild.zig  build.zig.zon  main  src\nIf I execute this binary executable, I get the “Hello World” message in the terminal , as we expected.\n./main\nHello, world!\n\n\n1.2.5 Compile and execute at the same time\nOn the previous section, I presented the zig build-exe command, which compiles Zig modules into an executable file. However, this means that, in order to execute the executable file, we have to run two different commands. First, the zig build-exe command, and then, we call the executable file created by the compiler.\nBut what if we wanted to perform these two steps, all at once, in a single command? We can do that by using the zig run command.\nzig run src/main.zig\nHello, world!\n\n\n1.2.6 Important note for Windows users\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other operating systems, such as Linux and macOs. In summary, if you have a piece of Zig code that includes some global variables whose initialization rely on runtime resources, then, you might have some troubles while trying to compile this Zig code on Windows.\nAn example of that is accessing the stdout (i.e. the standard output of your system), which is usually done in Zig by using the expression std.io.getStdOut(). Thus, if you use this expression to instantiate a global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows, with a “unable to evaluate comptime expression” error message.\nThis failure in the compilation process happens because all global variables in Zig are initialized at compile-time. However, operations like accessing the stdout (or opening a file) on Windows depends on resources that are available only at runtime (you will learn more about compile-time versus runtime at Section 3.1.1).\nFor example, if you try to compile this code example on Windows, you will likely get the error message exposed below:\n\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\nTo avoid this problem on Windows, we need to force the zig compiler to instantiate this stdout object only at runtime, instead of instantiating it at compile-time. We can achieve that by simply moving the expression to a function body.\nThis solves the problem because all expressions that are inside a function body in Zig are evaluated only at runtime, unless you use the comptime keyword explicitly to change this behaviour. You will learn more about this comptime keyword at Section 12.1.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nHello\nYou can read more details about this Windows-specific limitation at a couple of GitHub issues opened at the official Zig repository. More specifically, the issues 17186 6 and 19864 7.\n\n\n1.2.7 Compiling the entire project\nJust as I described at Section 1.2.1, as our project grows in size and complexity, we usually prefer to organize the compilation and build process of the project into a build script, using some sort of “build system”.\nIn other words, as our project grows in size and complexity, the build-exe, build-lib and build-obj commands become harder to use directly. Because then, we start to list multiple and multiple modules at the same time. We also start to add built-in compilation flags to customize the build process for our needs, etc. It becomes a lot of work to write the necessary commands by hand.\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, Makefile or configure scripts to organize this process. However, in Zig, we have a native build system in the language itself. So, we can write build scripts in Zig to compile and build Zig projects. Then, all we need to do, is to call the zig build command to build our project.\nSo, when you execute the zig build command, the zig compiler will search for a Zig module named build.zig inside your current directory, which should be your build script, containing the necessary code to compile and build your project. If the compiler does find this build.zig file in your directory, then, the compiler will essentially execute a zig run command over this build.zig file, to compile and execute this build script, which in turn, will compile and build your entire project.\nzig build\nAfter you execute this “build project” command, a zig-out directory is created in the root of your project directory, where you can find the binary executables and libraries created from your Zig modules accordingly to the build commands that you specified at build.zig. We will talk more about the build system in Zig latter in this book.\nIn the example below, I’m executing the binary executable named hello_world that was generated by the compiler after the zig build command.\n./zig-out/bin/hello_world\nHello, world!",
+    "text": "1.2 Hello world in Zig\nWe begin our journey in Zig by creating a small “Hello World” program. To start a new Zig project in your computer, you simply call the init command from the zig compiler. Just create a new directory in your computer, then, init a new Zig project inside this directory, like this:\nmkdir hello_world\ncd hello_world\nzig init\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n\n1.2.1 Understanding the project files\nAfter you run the init command from the zig compiler, some new files are created inside of your current directory. First, a “source” (src) directory is created, containing two files, main.zig and root.zig. Each .zig file is a separate Zig module, which is simply a text file that contains some Zig code.\nBy convention, the main.zig module is where your main function lives. Thus, if you are building an executable program in Zig, you need to declare a main() function, which represents the entrypoint of your program, i.e. it is where the execution of your program begins.\nHowever, if you are building a library (instead of an executable program), then, the normal procedure is to delete this main.zig file and start with the root.zig module. By convention, the root.zig module is the root source file of your library.\ntree .\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\nThe ìnit command also creates two additional files in our working directory: build.zig and build.zig.zon. The first file (build.zig) represents a build script written in Zig. This script is executed when you call the build command from the zig compiler. In other words, this file contain Zig code that executes the necessary steps to build the entire project.\nLow-level languages normally use a compiler to build your source code into binary executables or binary libraries. Nevertheless, this process of compiling your source code and building binary executables or binary libraries from it, became a real challenge in the programming world, once the projects became bigger and bigger. As a result, programmers created “build systems”, which are a second set of tools designed to make this process of compiling and building complex projects, easier.\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja, which are used to build complex C and C++ projects. With these systems, you can write scripts, which are called “build scripts”. They simply are scripts that describes the necessary steps to compile/build your project.\nHowever, these are separate tools, that do not belong to C/C++ compilers, like gcc or clang. As a result, in C/C++ projects, you have not only to install and manage your C/C++ compilers, but you also have to install and manage these build systems separately.\nIn Zig, we don’t need to use a separate set of tools to build our projects, because a build system is embedded inside the language itself. Therefore, Zig contains a native build system in it, and we can use this build system to write small scripts in Zig, which describes the necessary steps to build/compile our Zig project1. So, everything you need to build a complex Zig project is the zig compiler, and nothing more.\nThe second generated file (build.zig.zon) is a JSON-like file, in which you can describe your project, and also, declare a set of dependencies of your project that you want to fetch from the internet. In other words, you can use this build.zig.zon file to include a list of external libraries in your project.\nOne possible way to include an external Zig library in your project, is to manually build and install the library in your system, and just link your source code with the library at the build step of your project.\nHowever, if this external Zig library is available on GitHub for example, and it has a valid build.zig.zon file in root folder of the project, which describes the project, you can easily include this library in your project by simply listing this external library in your build.zig.zon file.\nIn other words, this build.zig.zon file works similarly to the package.json file in Javascript projects, or the Pipfile file in Python projects, or the Cargo.toml file in Rust projects. You can read more about this specific file in a couple of articles on the internet23, and you can also see the expected schema for this build.zig.zon file in a documentation file inside the official repository of Zig4.\n\n\n1.2.2 The file root.zig\nLet’s take a look into the root.zig file. You might have noticed that every line of code with an expression ends with a semicolon (;). This follows the syntax of a C-family programming language5.\nAlso, notice the @import() call at the first line. We use this built-in function to import functionality from other Zig modules into our current module. This @import() function works similarly to the #include pre-processor in C or C++, or, to the import statement in Python or Javascript code. In this example, we are importing the std module, which gives you access to the Zig Standard Library.\nIn this root.zig file, we can also see how assignments (i.e. creating new objects) are made in Zig. You can create a new object in Zig by using the following syntax (const|var) name = value;. In the example below, we are creating two constant objects (std and testing). At Section 1.4 we talk more about objects in general.\n\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n\nFunctions in Zig are declared using the fn keyword. In this root.zig module, we are declaring a function called add(), which has two arguments named a and b. The function returns an integer of the type i32 as result.\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit the type of an object in your code, if this type can be inferred by the zig compiler (we talk more about that at Section 2.4). But there are other situations where you do need to be explicit. For example, you do have to explicitly specify the type of each function argument, and also, the return type of every function that you create in Zig.\nWe specify the type of an object or a function argument in Zig by using a colon character (:) followed by the type after the name of this object/function argument. With the expressions a: i32 and b: i32, we know that both a and b arguments have type i32, which is a signed 32 bit integer. In this part, the syntax in Zig is identical to the syntax in Rust, which also specifies types by using the colon character.\nLastly, we have the return type of the function at the end of the line, before we open the curly braces to start writing the function’s body. In the example above, this type is also a signed 32 bit integer (i32) value.\nNotice that we also have an export keyword before the function declaration. This keyword is similar to the extern keyword in C. It exposes the function to make it available in the library API. Therefore, if you are writing a library for other people to use, you have to expose the functions you write in the public API of this library by using this export keyword. If we removed the export keyword from the add() function declaration, then, this function would be no longer exposed in the library object built by the zig compiler.\n\n\n1.2.3 The main.zig file\nNow that we have learned a lot about Zig’s syntax from the root.zig file, let’s take a look at the main.zig file. A lot of the elements we saw in root.zig are also present in main.zig. But there are some other elements that we haven’t seen yet, so let’s dive in.\nFirst, look at the return type of the main() function in this file. We can see a small change. The return type of the function (void) is accompanied by an exclamation mark (!). This exclamation mark tells us that this main() function might return an error.\nIs worth noting that, a main() function in Zig is allowed to return nothing (void), or an unsigned 8-bit integer (u8) value6, or an error. In other words, you can write your main() function in Zig to return essentially nothing (void), or, if you prefer, you can also write a more C-like main() function, which returns an integer value that usually serves as a “status code” for the process.\nIn this example, the return type annotation of main() indicates that this function can either return nothing (void), or return an error. This exclamation mark in the return type annotation is an interesting and powerful feature of Zig. In summary, if you write a function and something inside the body of this function might return an error, then, you are forced to:\n\neither add the exclamation mark to the return type of the function and make it clear that this function might return an error.\nexplicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through a try catch pattern. Zig does have both try and catch keywords. But they work a little differently than what you’re probably used to in other languages.\nIf we look at the main() function below, you can see that we do have a try keyword on the 5th line. But we do not have a catch keyword in this code. In Zig, we use the try keyword to execute an expression that might return an error, which, in this example, is the stdout.print() expression.\nIn essence, the try keyword executes the expression stdout.print(). If this expression returns a valid value, then, the try keyword does absolutely nothing. It only passes the value forward. It is like if this try keyword was never there. However, if the expression does return an error, then, the try keyword will unwrap the error value, then, it returns this error from the function and also prints the current stack trace to stderr.\nThis might sound weird to you if you come from a high-level language. Because in high-level languages, such as Python, if an error occurs somewhere, this error is automatically returned and the execution of your program will automatically stop even if you don’t want to stop the execution. You are obligated to face the error.\n\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n\nAnother thing that you might have noticed in this code example, is that the main() function is marked with the pub keyword. It marks the main() function as a public function from this module. Every function in your Zig module is by default private to this Zig module and can only be called from within the module. Unless, you explicitly mark this function as a public function with the pub keyword.\nIf you think about it, this pub keyword in Zig does essentially the opposite of what the static keyword do in C/C++. By making a function “public” you allow other Zig modules to access and call this function. A calling Zig module imports another module by using the @import() built-in function, which makes all public functions from the imported module visible to the calling Zig module.\n\n\n1.2.4 Compiling your source code\nYou can compile your Zig modules into a binary executable by running the build-exe command from the zig compiler. You simply list all the Zig modules that you want to build after the build-exe command, separated by spaces. In the example below, we are compiling the module main.zig.\nzig build-exe src/main.zig\nSince we are building an executable, the zig compiler will look for a main() function declared in any of the files that you list after the build-exe command. If the compiler does not find a main() function declared somewhere, a compilation error will be raised, warning about this mistake.\nThe zig compiler also offers a build-lib and build-obj commands, which work the exact same way as the build-exe command. The only difference is that, they compile your Zig modules into a portale C ABI library, or, into object files, respectively.\nIn the case of the build-exe command, a binary executable file is created by the zig compiler in the root directory of your project. If we take a look now at the contents of our current directory, with a simple ls command, we can see the binary file called main that was created by the compiler.\nls\nbuild.zig  build.zig.zon  main  src\nIf I execute this binary executable, I get the “Hello World” message in the terminal , as we expected.\n./main\nHello, world!\n\n\n1.2.5 Compile and execute at the same time\nOn the previous section, I presented the zig build-exe command, which compiles Zig modules into an executable file. However, this means that, in order to execute the executable file, we have to run two different commands. First, the zig build-exe command, and then, we call the executable file created by the compiler.\nBut what if we wanted to perform these two steps, all at once, in a single command? We can do that by using the zig run command.\nzig run src/main.zig\nHello, world!\n\n\n1.2.6 Important note for Windows users\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other operating systems, such as Linux and macOs. In summary, if you have a piece of Zig code that includes some global variables whose initialization rely on runtime resources, then, you might have some troubles while trying to compile this Zig code on Windows.\nAn example of that is accessing the stdout (i.e. the standard output of your system), which is usually done in Zig by using the expression std.io.getStdOut(). Thus, if you use this expression to instantiate a global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows, with a “unable to evaluate comptime expression” error message.\nThis failure in the compilation process happens because all global variables in Zig are initialized at compile-time. However, operations like accessing the stdout (or opening a file) on Windows depends on resources that are available only at runtime (you will learn more about compile-time versus runtime at Section 3.1.1).\nFor example, if you try to compile this code example on Windows, you will likely get the error message exposed below:\n\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\nTo avoid this problem on Windows, we need to force the zig compiler to instantiate this stdout object only at runtime, instead of instantiating it at compile-time. We can achieve that by simply moving the expression to a function body.\nThis solves the problem because all expressions that are inside a function body in Zig are evaluated only at runtime, unless you use the comptime keyword explicitly to change this behaviour. You will learn more about this comptime keyword at Section 12.1.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nHello\nYou can read more details about this Windows-specific limitation at a couple of GitHub issues opened at the official Zig repository. More specifically, the issues 17186 7 and 19864 8.\n\n\n1.2.7 Compiling the entire project\nJust as I described at Section 1.2.1, as our project grows in size and complexity, we usually prefer to organize the compilation and build process of the project into a build script, using some sort of “build system”.\nIn other words, as our project grows in size and complexity, the build-exe, build-lib and build-obj commands become harder to use directly. Because then, we start to list multiple and multiple modules at the same time. We also start to add built-in compilation flags to customize the build process for our needs, etc. It becomes a lot of work to write the necessary commands by hand.\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, Makefile or configure scripts to organize this process. However, in Zig, we have a native build system in the language itself. So, we can write build scripts in Zig to compile and build Zig projects. Then, all we need to do, is to call the zig build command to build our project.\nSo, when you execute the zig build command, the zig compiler will search for a Zig module named build.zig inside your current directory, which should be your build script, containing the necessary code to compile and build your project. If the compiler does find this build.zig file in your directory, then, the compiler will essentially execute a zig run command over this build.zig file, to compile and execute this build script, which in turn, will compile and build your entire project.\nzig build\nAfter you execute this “build project” command, a zig-out directory is created in the root of your project directory, where you can find the binary executables and libraries created from your Zig modules accordingly to the build commands that you specified at build.zig. We will talk more about the build system in Zig latter in this book.\nIn the example below, I’m executing the binary executable named hello_world that was generated by the compiler after the zig build command.\n./zig-out/bin/hello_world\nHello, world!",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -134,7 +134,7 @@
     "href": "Chapters/01-zig-weird.html#how-to-learn-zig",
     "title": "1  Introducing Zig",
     "section": "1.3 How to learn Zig?",
-    "text": "1.3 How to learn Zig?\nWhat are the best strategies to learn Zig? First of all, of course this book will help you a lot on your journey through Zig. But you will also need some extra resources if you want to be really good at Zig.\nAs a first tip, you can join a community with Zig programmers to get some help , when you need it:\n\nReddit forum: https://www.reddit.com/r/Zig/;\nZiggit community: https://ziggit.dev/;\nDiscord, Slack, Telegram, and others: https://github.com/ziglang/zig/wiki/Community;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try to read Zig code often, and things will become more clear. A C/C++ programmer would also probably give you this same tip. Because this strategy really works!\nNow, where can you find Zig code to read? I personally think that, the best way of reading Zig code is to read the source code of the Zig Standard Library. The Zig Standard Library is available at the lib/std folder8 on the official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\nAlso, a great alternative is to read code from other large Zig codebases, such as:\n\nthe Javascript runtime Bun9.\nthe game engine Mach10.\na LLama 2 LLM model implementation in Zig11.\nthe financial transactions database tigerbeetle12.\nthe command-line arguments parser zig-clap13.\nthe UI framework capy14.\nthe Language Protocol implementation for Zig, zls15.\nthe event-loop library libxev16.\n\nAll these assets are available on GitHub, and this is great, because we can use the GitHub search bar in our advantage, to find Zig code that fits our description. For example, you can always include lang:Zig in the GitHub search bar when you are searching for a particular pattern. This will limit the search to only Zig modules.\nAlso, a great alternative is to consult online resources and documentations. Here is a quick list of resources that I personally use from time to time to learn more about the language each day:\n\nZig Language Reference: https://ziglang.org/documentation/master/;\nZig Standard Library Reference: https://ziglang.org/documentation/master/std/;\nZig Guide: https://zig.guide/;\nKarl Seguin Blog: https://www.openmymind.net/;\nZig News: https://zig.news/;\nRead the code written by one of the Zig core team members: https://github.com/kubkon;\nSome livecoding sessions are transmitted in the Zig Showtime Youtube Channel: https://www.youtube.com/@ZigSHOWTIME/videos;\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want, is to practice it by solving exercises. For example, there is a famous repository in the Zig community called Ziglings17 , which contains more than 100 small exercises that you can solve. It is a repository of tiny programs written in Zig that are currently broken, and your responsibility is to fix these programs, and make them work again.\nA famous tech YouTuber known as The Primeagen also posted some videos (at YouTube) where he solves these exercises from Ziglings. The first video is named “Trying Zig Part 1”18.\nAnother great alternative, is to solve the Advent of Code exercises19. There are people that already took the time to learn and solve the exercises, and they posted their solutions on GitHub as well, so, in case you need some resource to compare while solving the exercises, you can look at these two repositories:\n\nhttps://github.com/SpexGuy/Zig-AoC-Template;\nhttps://github.com/fjebaker/advent-of-code-2022;",
+    "text": "1.3 How to learn Zig?\nWhat are the best strategies to learn Zig? First of all, of course this book will help you a lot on your journey through Zig. But you will also need some extra resources if you want to be really good at Zig.\nAs a first tip, you can join a community with Zig programmers to get some help , when you need it:\n\nReddit forum: https://www.reddit.com/r/Zig/;\nZiggit community: https://ziggit.dev/;\nDiscord, Slack, Telegram, and others: https://github.com/ziglang/zig/wiki/Community;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try to read Zig code often, and things will become more clear. A C/C++ programmer would also probably give you this same tip. Because this strategy really works!\nNow, where can you find Zig code to read? I personally think that, the best way of reading Zig code is to read the source code of the Zig Standard Library. The Zig Standard Library is available at the lib/std folder9 on the official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\nAlso, a great alternative is to read code from other large Zig codebases, such as:\n\nthe Javascript runtime Bun10.\nthe game engine Mach11.\na LLama 2 LLM model implementation in Zig12.\nthe financial transactions database tigerbeetle13.\nthe command-line arguments parser zig-clap14.\nthe UI framework capy15.\nthe Language Protocol implementation for Zig, zls16.\nthe event-loop library libxev17.\n\nAll these assets are available on GitHub, and this is great, because we can use the GitHub search bar in our advantage, to find Zig code that fits our description. For example, you can always include lang:Zig in the GitHub search bar when you are searching for a particular pattern. This will limit the search to only Zig modules.\nAlso, a great alternative is to consult online resources and documentations. Here is a quick list of resources that I personally use from time to time to learn more about the language each day:\n\nZig Language Reference: https://ziglang.org/documentation/master/;\nZig Standard Library Reference: https://ziglang.org/documentation/master/std/;\nZig Guide: https://zig.guide/;\nKarl Seguin Blog: https://www.openmymind.net/;\nZig News: https://zig.news/;\nRead the code written by one of the Zig core team members: https://github.com/kubkon;\nSome livecoding sessions are transmitted in the Zig Showtime Youtube Channel: https://www.youtube.com/@ZigSHOWTIME/videos;\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want, is to practice it by solving exercises. For example, there is a famous repository in the Zig community called Ziglings18 , which contains more than 100 small exercises that you can solve. It is a repository of tiny programs written in Zig that are currently broken, and your responsibility is to fix these programs, and make them work again.\nA famous tech YouTuber known as The Primeagen also posted some videos (at YouTube) where he solves these exercises from Ziglings. The first video is named “Trying Zig Part 1”19.\nAnother great alternative, is to solve the Advent of Code exercises20. There are people that already took the time to learn and solve the exercises, and they posted their solutions on GitHub as well, so, in case you need some resource to compare while solving the exercises, you can look at these two repositories:\n\nhttps://github.com/SpexGuy/Zig-AoC-Template;\nhttps://github.com/fjebaker/advent-of-code-2022;",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -154,7 +154,7 @@
     "href": "Chapters/01-zig-weird.html#sec-primitive-data-types",
     "title": "1  Introducing Zig",
     "section": "1.5 Primitive Data Types",
-    "text": "1.5 Primitive Data Types\nZig have many different primitive data types available for you to use. You can see the full list of available data types at the official Language Reference page20.\nBut here is a quick list:\n\nUnsigned integers: u8, 8-bit integer; u16, 16-bit integer; u32, 32-bit integer; u64, 64-bit integer; u128, 128-bit integer.\nSigned integers: i8, 8-bit integer; i16, 16-bit integer; i32, 32-bit integer; i64, 64-bit integer; i128, 128-bit integer.\nFloat number: f16, 16-bit floating point; f32, 32-bit floating point; f64, 64-bit floating point; f128, 128-bit floating point;\nBoolean: bool, represents true or false values.\nC ABI compatible types: c_long, c_char, c_short, c_ushort, c_int, c_uint, and many others.\nPointer sized integers: isize and usize.",
+    "text": "1.5 Primitive Data Types\nZig have many different primitive data types available for you to use. You can see the full list of available data types at the official Language Reference page21.\nBut here is a quick list:\n\nUnsigned integers: u8, 8-bit integer; u16, 16-bit integer; u32, 32-bit integer; u64, 64-bit integer; u128, 128-bit integer.\nSigned integers: i8, 8-bit integer; i16, 16-bit integer; i32, 32-bit integer; i64, 64-bit integer; i128, 128-bit integer.\nFloat number: f16, 16-bit floating point; f32, 32-bit floating point; f64, 64-bit floating point; f128, 128-bit floating point;\nBoolean: bool, represents true or false values.\nC ABI compatible types: c_long, c_char, c_short, c_ushort, c_int, c_uint, and many others.\nPointer sized integers: isize and usize.",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -184,7 +184,7 @@
     "href": "Chapters/01-zig-weird.html#sec-zig-strings",
     "title": "1  Introducing Zig",
     "section": "1.8 How strings work in Zig?",
-    "text": "1.8 How strings work in Zig?\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (Chapter 4). But in order for us to build such a thing, we need to get a better understanding on how strings work in Zig. So let’s discuss this specific aspect of Zig.\nIn summary, there are two types of string values that you care about in Zig, which are:\n\nString literal values.\nString objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string). But in Zig, a string literal value also embeds the length of the string into the data type of the value itself. Therefore, a string literal value have a data type in the format *const [n:0]u8. The n in the data type indicates the size of the string.\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes, or, in other words, a slice of u8 values (slices were presented at Section 1.6). Thus, a string object have a data type of []u8 or []const u8, depending if the string object is marked as constant with const, or as variable with var.\nBecause a string object is essentially a slice, it means that a string object always contains two things: a pointer to an array of bytes (i.e. u8 values) that represents the string value; and also, a length value, which specifies the size of the slice, or, how many elements there is in the slice. Is worth to emphasize that the array of bytes in a string object is not null-terminated, like in a string literal value.\n\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every sequence of bytes you’re working with, but is not really Zig’s job to fix the encoding of your strings (you can use iconv21 for that). Today, most of the text in our modern world, especially on the web, should be UTF-8 encoded. So if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\nLet’s take for example the word “Hello”. In UTF-8, this sequence of characters (H, e, l, l, o) is represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this sequence is 0x48, 0x65, 0x6C, 0x6C, 0x6F. So if I take this sequence of hexadecimal values, and ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then, the text “Hello” will be printed into the terminal:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n\nHello\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use a for loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal value to the terminal. You do that by using a print() statement with the X formatting specifier, like you would normally do with the printf() function22 in C.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n\n\n\n1.8.1 Strings in C\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well. In more details, string values in C are treated internally as an array of arbitrary bytes, and this array is also null-terminated.\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of the string inside the object itself. In the case of a string literal value, this length is stored in the data type of the value (i.e. the n variable in [n:0]u8). While, in a string object, the length is stored in the len attribute of the slice that represents the string object. This small detail makes your code safer, because is much easier for the Zig compiler to check if you are trying to access an element that is “out of bounds”, i.e. if your trying to access memory that does not belong to you.\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless. So getting this kind of safety is not automatic and much harder to do in C. For example, if you want to track the length of your string throughout your program in C, then, you first need to loop through the array of bytes that represents this string, and find the null element ('\\0') position to discover where exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\nTo do that, you would need something like this in C. In this example, the C string stored in the object array is 25 bytes long:\n\n#include &lt;stdio.h&gt;\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n\nNumber of elements in the array: 25\nYou don’t have this kind of work in Zig. Because the length of the string is always present and accessible. In a string object for example, you can easily access the length of the string through the len attribute. As an example, the string_object object below is 43 bytes long:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n\n43\n\n\n\n\n1.8.2 A better look at the object type\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the @TypeOf() function. If we look at the type of the simple_array object below, you will find that this object is an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type i32 in Zig. That is what an object of type [4]i32 is.\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a constant pointer (hence the *const annotation) to an array of 16 elements (or 16 bytes). Each element is a single byte (more precisely, an unsigned 8 bit integer - u8), that is why we have the [16:0]u8 portion of the type below. In other words, the string literal value exposed below is 16 bytes long.\nNow, if we create an pointer to the simple_array object, then, we get a constant pointer to an array of 4 elements (*const [4]i32), which is very similar to the type of the string literal value. This demonstrates that a string literal value in Zig is already a pointer to a null-terminated array of bytes.\nFurthermore, if we take a look at the type of the string_obj object, you will see that it is a slice object (hence the [] portion of the type) to a sequence of constant u8 values (hence the const u8 portion of the type).\n\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n\n\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n\n\n1.8.3 Byte vs unicode points\nIs important to point out that each byte in the array is not necessarily a single character. This fact arises from the difference between a single byte and a single unicode point.\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in the string. For example, the character “H” is stored in UTF-8 as the decimal number 72. This means that the number 72 is the unicode point for the character “H”. Each possible character that can appear in a UTF-8 encoded string have its own unicode point.\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point) 570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which is 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why, the unicode point 570 is actually stored inside the computer’s memory as the bytes C8 BA.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n\nBytes that represents the string object: C8 BA \n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together to represent the number 570. That is why the relationship between bytes and unicode points is not always 1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds to a single unicode point.\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the bytes that represents that string, and not through the characters of that string. In the Ⱥ example above, the for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a consequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because the number of bytes will be equal to the number of characters in that string. In other words, in this specific situation, the relationship between bytes and unicode points is 1 to 1.\nBut on the other side, if your string contains other types of letters… for example, you might be working with text data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent your UTF-8 string will likely be much higher than the number of characters in that string.\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the std.unicode.Utf8View struct to create an iterator that iterates through the unicode points of your string.\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in this string is represented by three bytes. But the for loop iterates four times, one iteration for each character/unicode point in this string:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n\n\n1.8.4 Some useful functions for strings\nIn this section, I just want to quickly describe some functions from the Zig Standard Library that are very useful to use when working with strings. Most notably:\n\nstd.mem.eql(): to compare if two strings are equal.\nstd.mem.splitScalar(): to split a string into an array of substrings given a delimiter value.\nstd.mem.splitSequence(): to split a string into an array of substrings given a substring delimiter.\nstd.mem.startsWith(): to check if string starts with substring.\nstd.mem.endsWith(): to check if string ends with substring.\nstd.mem.trim(): to remove specific values from both start and end of the string.\nstd.mem.concat(): to concatenate strings together.\nstd.mem.count(): to count the occurrences of substring in the string.\nstd.mem.replace(): to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the mem module of the Zig Standard Library. This module contains multiple functions and methods that are useful to work with memory and sequences of bytes in general.\nThe eql() function is used to check if two arrays of data are equal or not. Since strings are just arbitrary arrays of bytes, we can use this function to compare two strings together. This function returns a boolean value indicating if the two strings are equal or not. The first argument of this function is the data type of the elements of the arrays that are being compared.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n\ntrue\n\n\nThe splitScalar() and splitSequence() functions are useful to split a string into multiple fragments, like the split() method from Python strings. The difference between these two methods is that the splitScalar() uses a single character as the separator to split the string, while splitSequence() uses a sequence of characters (a.k.a. a substring) as the separator. There is a practical example of these functions later in the book.\nThe startsWith() and endsWith() functions are pretty straightforward. They return a boolean value indicating if the string (or, more precisely, if the array of data) begins (startsWith) or ends (endsWith) with the sequence provided.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n\ntrue\n\n\nThe concat() function, as the name suggests, concatenate two or more strings together. Because the process of concatenating the strings involves allocating enough space to accomodate all the strings together, this concat() function receives an allocator object as input.\n\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n\nAs you can imagine, the replace() function is used to replace substrings in a string by another substring. This function works very similarly to the replace() method from Python strings. Therefore, you provide a substring to search, and every time that the replace() function finds this substring within the input string, it replaces this substring with the “replacement substring” that you provided as input.\nIn the example below, we are taking the input string “Hello”, and replacing all occurrences of the substring “el” inside this input string with “34”, and saving the results inside the buffer object. As result, the replace() function returns an usize value that indicates how many replacements were performed.\n\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n\nNew string: H34lo\nN of replacements: 1",
+    "text": "1.8 How strings work in Zig?\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (Chapter 4). But in order for us to build such a thing, we need to get a better understanding on how strings work in Zig. So let’s discuss this specific aspect of Zig.\nIn summary, there are two types of string values that you care about in Zig, which are:\n\nString literal values.\nString objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string). But in Zig, a string literal value also embeds the length of the string into the data type of the value itself. Therefore, a string literal value have a data type in the format *const [n:0]u8. The n in the data type indicates the size of the string.\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes, or, in other words, a slice of u8 values (slices were presented at Section 1.6). Thus, a string object have a data type of []u8 or []const u8, depending if the string object is marked as constant with const, or as variable with var.\nBecause a string object is essentially a slice, it means that a string object always contains two things: a pointer to an array of bytes (i.e. u8 values) that represents the string value; and also, a length value, which specifies the size of the slice, or, how many elements there is in the slice. Is worth to emphasize that the array of bytes in a string object is not null-terminated, like in a string literal value.\n\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every sequence of bytes you’re working with, but is not really Zig’s job to fix the encoding of your strings (you can use iconv22 for that). Today, most of the text in our modern world, especially on the web, should be UTF-8 encoded. So if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\nLet’s take for example the word “Hello”. In UTF-8, this sequence of characters (H, e, l, l, o) is represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this sequence is 0x48, 0x65, 0x6C, 0x6C, 0x6F. So if I take this sequence of hexadecimal values, and ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then, the text “Hello” will be printed into the terminal:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n\nHello\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use a for loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal value to the terminal. You do that by using a print() statement with the X formatting specifier, like you would normally do with the printf() function23 in C.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n\n\n\n1.8.1 Strings in C\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well. In more details, string values in C are treated internally as an array of arbitrary bytes, and this array is also null-terminated.\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of the string inside the object itself. In the case of a string literal value, this length is stored in the data type of the value (i.e. the n variable in [n:0]u8). While, in a string object, the length is stored in the len attribute of the slice that represents the string object. This small detail makes your code safer, because is much easier for the Zig compiler to check if you are trying to access an element that is “out of bounds”, i.e. if your trying to access memory that does not belong to you.\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless. So getting this kind of safety is not automatic and much harder to do in C. For example, if you want to track the length of your string throughout your program in C, then, you first need to loop through the array of bytes that represents this string, and find the null element ('\\0') position to discover where exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\nTo do that, you would need something like this in C. In this example, the C string stored in the object array is 25 bytes long:\n\n#include &lt;stdio.h&gt;\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n\nNumber of elements in the array: 25\nYou don’t have this kind of work in Zig. Because the length of the string is always present and accessible. In a string object for example, you can easily access the length of the string through the len attribute. As an example, the string_object object below is 43 bytes long:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n\n43\n\n\n\n\n1.8.2 A better look at the object type\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the @TypeOf() function. If we look at the type of the simple_array object below, you will find that this object is an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type i32 in Zig. That is what an object of type [4]i32 is.\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a constant pointer (hence the *const annotation) to an array of 16 elements (or 16 bytes). Each element is a single byte (more precisely, an unsigned 8 bit integer - u8), that is why we have the [16:0]u8 portion of the type below. In other words, the string literal value exposed below is 16 bytes long.\nNow, if we create an pointer to the simple_array object, then, we get a constant pointer to an array of 4 elements (*const [4]i32), which is very similar to the type of the string literal value. This demonstrates that a string literal value in Zig is already a pointer to a null-terminated array of bytes.\nFurthermore, if we take a look at the type of the string_obj object, you will see that it is a slice object (hence the [] portion of the type) to a sequence of constant u8 values (hence the const u8 portion of the type).\n\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n\n\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n\n\n1.8.3 Byte vs unicode points\nIs important to point out that each byte in the array is not necessarily a single character. This fact arises from the difference between a single byte and a single unicode point.\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in the string. For example, the character “H” is stored in UTF-8 as the decimal number 72. This means that the number 72 is the unicode point for the character “H”. Each possible character that can appear in a UTF-8 encoded string have its own unicode point.\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point) 570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which is 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why, the unicode point 570 is actually stored inside the computer’s memory as the bytes C8 BA.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n\nBytes that represents the string object: C8 BA \n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together to represent the number 570. That is why the relationship between bytes and unicode points is not always 1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds to a single unicode point.\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the bytes that represents that string, and not through the characters of that string. In the Ⱥ example above, the for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a consequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because the number of bytes will be equal to the number of characters in that string. In other words, in this specific situation, the relationship between bytes and unicode points is 1 to 1.\nBut on the other side, if your string contains other types of letters… for example, you might be working with text data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent your UTF-8 string will likely be much higher than the number of characters in that string.\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the std.unicode.Utf8View struct to create an iterator that iterates through the unicode points of your string.\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in this string is represented by three bytes. But the for loop iterates four times, one iteration for each character/unicode point in this string:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n\n\n1.8.4 Some useful functions for strings\nIn this section, I just want to quickly describe some functions from the Zig Standard Library that are very useful to use when working with strings. Most notably:\n\nstd.mem.eql(): to compare if two strings are equal.\nstd.mem.splitScalar(): to split a string into an array of substrings given a delimiter value.\nstd.mem.splitSequence(): to split a string into an array of substrings given a substring delimiter.\nstd.mem.startsWith(): to check if string starts with substring.\nstd.mem.endsWith(): to check if string ends with substring.\nstd.mem.trim(): to remove specific values from both start and end of the string.\nstd.mem.concat(): to concatenate strings together.\nstd.mem.count(): to count the occurrences of substring in the string.\nstd.mem.replace(): to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the mem module of the Zig Standard Library. This module contains multiple functions and methods that are useful to work with memory and sequences of bytes in general.\nThe eql() function is used to check if two arrays of data are equal or not. Since strings are just arbitrary arrays of bytes, we can use this function to compare two strings together. This function returns a boolean value indicating if the two strings are equal or not. The first argument of this function is the data type of the elements of the arrays that are being compared.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n\ntrue\n\n\nThe splitScalar() and splitSequence() functions are useful to split a string into multiple fragments, like the split() method from Python strings. The difference between these two methods is that the splitScalar() uses a single character as the separator to split the string, while splitSequence() uses a sequence of characters (a.k.a. a substring) as the separator. There is a practical example of these functions later in the book.\nThe startsWith() and endsWith() functions are pretty straightforward. They return a boolean value indicating if the string (or, more precisely, if the array of data) begins (startsWith) or ends (endsWith) with the sequence provided.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n\ntrue\n\n\nThe concat() function, as the name suggests, concatenate two or more strings together. Because the process of concatenating the strings involves allocating enough space to accomodate all the strings together, this concat() function receives an allocator object as input.\n\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n\nAs you can imagine, the replace() function is used to replace substrings in a string by another substring. This function works very similarly to the replace() method from Python strings. Therefore, you provide a substring to search, and every time that the replace() function finds this substring within the input string, it replaces this substring with the “replacement substring” that you provided as input.\nIn the example below, we are taking the input string “Hello”, and replacing all occurrences of the substring “el” inside this input string with “34”, and saving the results inside the buffer object. As result, the replace() function returns an usize value that indicates how many replacements were performed.\n\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n\nNew string: H34lo\nN of replacements: 1",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -194,7 +194,7 @@
     "href": "Chapters/01-zig-weird.html#safety-in-zig",
     "title": "1  Introducing Zig",
     "section": "1.9 Safety in Zig",
-    "text": "1.9 Safety in Zig\nA general trend in modern low-level programming languages is safety. As our modern world becomes more interconnected with technology and computers, the data produced by all of this technology becomes one of the most important (and also, one of the most dangerous) assets that we have.\nThis is probably the main reason why modern low-level programming languages have been giving great attention to safety, especially memory safety, because memory corruption is still the main target for hackers to exploit. The reality is that we don’t have an easy solution for this problem. For now, we only have techniques and strategies that mitigates these problems.\nAs Richard Feldman explains on his most recent GOTO conference talk23 , we haven’t figured it out yet a way to achieve true safety in technology. In other words, we haven’t found a way to build software that won’t be exploited with 100% certainty. We can greatly reduce the risks of our software being exploited, by ensuring memory safety for example. But this is not enough to achieve “true safety” territory.\nBecause even if you write your program in a “safe language”, hackers can still exploit failures in the operating system where your program is running (e.g. maybe the system where your code is running has a “backdoor exploit” that can still affect your code in unexpected ways), or also, they can exploit the features from the architecture of your computer. A recently found exploit that involves memory invalidation through a feature of “memory tags” present in ARM chips is an example of that (Kim et al. 2024).\nThe question is: what have Zig and other languages been doing to mitigate this problem? If we take Rust as an example, Rust is, for the most part24, a memory safe language by enforcing specific rules to the developer. In other words, the key feature of Rust, the borrow checker, forces you to follow a specific logic when you are writing your Rust code, and the Rust compiler will always complain everytime you try to go out of this pattern.\nIn contrast, the Zig language is not a memory safe language by default. There are some memory safety features that you get for free in Zig, especially in arrays and pointer objects. But there are other tools offered by the language, that are not used by default. In other words, the zig compiler does not obligates you to use such tools.\nThe tools listed below are related to memory safety. That is, they help you to achieve memory safety in your Zig code:\n\ndefer allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, “use after free”, and also “double-free” problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\nerrdefer helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\npointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\nZig offers some native types of allocators (called “testing allocators”) that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\narrays and slices in Zig have their lengths embedded in the object itself, which makes the zig compiler very effective on detecting “index out-of-range” type of errors, and avoiding buffer overflows.\n\nDespite these features that Zig offers that are related to memory safety issues, the language also has some rules that help you to achieve another type of safety, which is more related to program logic safety. These rules are:\n\npointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\nswitch statements must exaust all possible options.\nthe zig compiler forces you to handle every possible error in your program.",
+    "text": "1.9 Safety in Zig\nA general trend in modern low-level programming languages is safety. As our modern world becomes more interconnected with technology and computers, the data produced by all of this technology becomes one of the most important (and also, one of the most dangerous) assets that we have.\nThis is probably the main reason why modern low-level programming languages have been giving great attention to safety, especially memory safety, because memory corruption is still the main target for hackers to exploit. The reality is that we don’t have an easy solution for this problem. For now, we only have techniques and strategies that mitigates these problems.\nAs Richard Feldman explains on his most recent GOTO conference talk24 , we haven’t figured it out yet a way to achieve true safety in technology. In other words, we haven’t found a way to build software that won’t be exploited with 100% certainty. We can greatly reduce the risks of our software being exploited, by ensuring memory safety for example. But this is not enough to achieve “true safety” territory.\nBecause even if you write your program in a “safe language”, hackers can still exploit failures in the operating system where your program is running (e.g. maybe the system where your code is running has a “backdoor exploit” that can still affect your code in unexpected ways), or also, they can exploit the features from the architecture of your computer. A recently found exploit that involves memory invalidation through a feature of “memory tags” present in ARM chips is an example of that (Kim et al. 2024).\nThe question is: what have Zig and other languages been doing to mitigate this problem? If we take Rust as an example, Rust is, for the most part25, a memory safe language by enforcing specific rules to the developer. In other words, the key feature of Rust, the borrow checker, forces you to follow a specific logic when you are writing your Rust code, and the Rust compiler will always complain everytime you try to go out of this pattern.\nIn contrast, the Zig language is not a memory safe language by default. There are some memory safety features that you get for free in Zig, especially in arrays and pointer objects. But there are other tools offered by the language, that are not used by default. In other words, the zig compiler does not obligates you to use such tools.\nThe tools listed below are related to memory safety. That is, they help you to achieve memory safety in your Zig code:\n\ndefer allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, “use after free”, and also “double-free” problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\nerrdefer helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\npointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\nZig offers some native types of allocators (called “testing allocators”) that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\narrays and slices in Zig have their lengths embedded in the object itself, which makes the zig compiler very effective on detecting “index out-of-range” type of errors, and avoiding buffer overflows.\n\nDespite these features that Zig offers that are related to memory safety issues, the language also has some rules that help you to achieve another type of safety, which is more related to program logic safety. These rules are:\n\npointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\nswitch statements must exaust all possible options.\nthe zig compiler forces you to handle every possible error in your program.",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -214,7 +214,7 @@
     "href": "Chapters/01-zig-weird.html#footnotes",
     "title": "1  Introducing Zig",
     "section": "",
-    "text": "https://ziglang.org/learn/overview/#zig-build-system.↩︎\nhttps://zig.news/edyu/zig-package-manager-wtf-is-zon-558e↩︎\nhttps://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1↩︎\nhttps://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md↩︎\nhttps://en.wikipedia.org/wiki/List_of_C-family_programming_languages↩︎\nhttps://github.com/ziglang/zig/issues/17186↩︎\nhttps://github.com/ziglang/zig/issues/19864↩︎\nhttps://github.com/ziglang/zig/tree/master/lib/std↩︎\nhttps://github.com/oven-sh/bun.↩︎\nhttps://github.com/hexops/mach↩︎\nhttps://github.com/cgbur/llama2.zig/tree/main↩︎\nhttps://github.com/tigerbeetle/tigerbeetle↩︎\nhttps://github.com/Hejsil/zig-clap↩︎\nhttps://github.com/capy-ui/capy↩︎\nhttps://github.com/zigtools/zls↩︎\nhttps://github.com/mitchellh/libxev↩︎\nhttps://ziglings.org.↩︎\nhttps://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen.↩︎\nhttps://adventofcode.com/↩︎\nhttps://ziglang.org/documentation/master/#Primitive-Types.↩︎\nhttps://www.gnu.org/software/libiconv/↩︎\nhttps://cplusplus.com/reference/cstdio/printf/↩︎\nhttps://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences↩︎\nActually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (foreign function interface), which disables the borrow-checker features through the unsafe keyword.↩︎",
+    "text": "https://ziglang.org/learn/overview/#zig-build-system.↩︎\nhttps://zig.news/edyu/zig-package-manager-wtf-is-zon-558e↩︎\nhttps://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1↩︎\nhttps://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md↩︎\nhttps://en.wikipedia.org/wiki/List_of_C-family_programming_languages↩︎\nYou can see an example of a main() function that returns an u8 value in the return-integer.zig file, https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig↩︎\nhttps://github.com/ziglang/zig/issues/17186↩︎\nhttps://github.com/ziglang/zig/issues/19864↩︎\nhttps://github.com/ziglang/zig/tree/master/lib/std↩︎\nhttps://github.com/oven-sh/bun.↩︎\nhttps://github.com/hexops/mach↩︎\nhttps://github.com/cgbur/llama2.zig/tree/main↩︎\nhttps://github.com/tigerbeetle/tigerbeetle↩︎\nhttps://github.com/Hejsil/zig-clap↩︎\nhttps://github.com/capy-ui/capy↩︎\nhttps://github.com/zigtools/zls↩︎\nhttps://github.com/mitchellh/libxev↩︎\nhttps://ziglings.org.↩︎\nhttps://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen.↩︎\nhttps://adventofcode.com/↩︎\nhttps://ziglang.org/documentation/master/#Primitive-Types.↩︎\nhttps://www.gnu.org/software/libiconv/↩︎\nhttps://cplusplus.com/reference/cstdio/printf/↩︎\nhttps://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences↩︎\nActually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (foreign function interface), which disables the borrow-checker features through the unsafe keyword.↩︎",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]

From d0cb20613014072d77e4bbf99e1c403fa88f7ffd Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Thu, 30 Jan 2025 22:35:05 -0300
Subject: [PATCH 032/151] Add more contributors to list

---
 _freeze/index/execute-results/html.json | 6 ++----
 contributors.txt                        | 5 +++++
 docs/index.html                         | 2 +-
 docs/search.json                        | 2 +-
 4 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/_freeze/index/execute-results/html.json b/_freeze/index/execute-results/html.json
index 542a03cc..45e16fd5 100644
--- a/_freeze/index/execute-results/html.json
+++ b/_freeze/index/execute-results/html.json
@@ -2,10 +2,8 @@
   "hash": "7eedbe34469c0f2c200651bc420da095",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy an eBook or a physical copy\nof the book on Amazon:\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e. it is open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.\nCurrently, he is a Data Platform Engineer at [Blip](https://www.blip.ai/en/)[^blip], and\na Databricks Certified Associate Developer for Apache Spark 3.0.\n\n[^blip]: <https://www.blip.ai/en/>\n\n\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nBrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer who loves to learn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2024 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n\n- System version: Linux, 6.8.0-52-generic, NA, x86_64.\n- Zig version: 0.14.0-dev.2371+c013f45ad.\n- Quarto version: 1.5.57.\n\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang)\n",
-    "supporting": [
-      "index_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy an eBook or a physical copy\nof the book on Amazon:\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e. it is open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.\nCurrently, he is a Data Platform Engineer at [Blip](https://www.blip.ai/en/)[^blip], and\na Databricks Certified Associate Developer for Apache Spark 3.0.\n\n[^blip]: <https://www.blip.ai/en/>\n\n\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nBrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer who loves to learn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2024 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n\n\n- System version: Linux, 6.8.0-52-generic, NA, x86_64.\n- Zig version: 0.14.0-dev.2371+c013f45ad.\n- Quarto version: 1.5.57.\n\n\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang), Tommaso Ricci (\\@Zorgatone), Primo Sabatini (\\@primos63), Santiago Fernandez (\\@santif), Hamza Wahed (\\@HamzaWahed), mwilbur (\\@mwilbur)\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/contributors.txt b/contributors.txt
index 18cad9e2..6bcf75bc 100644
--- a/contributors.txt
+++ b/contributors.txt
@@ -12,3 +12,8 @@ Bruno,@PoorlyDefinedBehaviour
 Ilia Choly,@icholy
 Korri Katti,@KorryKatti
 Vedang Manerikar,@vedang
+Tommaso Ricci,@Zorgatone
+Primo Sabatini,@primos63
+Santiago Fernandez,@santif
+Hamza Wahed,@HamzaWahed
+mwilbur,@mwilbur
diff --git a/docs/index.html b/docs/index.html
index ac188123..bb4d7134 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -439,7 +439,7 @@ <h2 class="unnumbered anchored" data-anchor-id="corresponding-author-and-maintai
 <section id="acknowledgments" class="level2 unnumbered">
 <h2 class="unnumbered anchored" data-anchor-id="acknowledgments">Acknowledgments</h2>
 <p>This book is also a product of many conversations and exchanges that we had with different people from the Zig community. I (Pedro Duarte Faria) am incredibly grateful for these conversations, and also, for some direct contributions that we had. Below we have a list of the people involved (name of the person with their usename in GitHub):</p>
-<p>Calin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang)</p>
+<p>Calin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang), Tommaso Ricci (@Zorgatone), Primo Sabatini (@primos63), Santiago Fernandez (@santif), Hamza Wahed (@HamzaWahed), mwilbur (@mwilbur)</p>
 
 
 </section>
diff --git a/docs/search.json b/docs/search.json
index 7c847548..82133e70 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -84,7 +84,7 @@
     "href": "index.html#acknowledgments",
     "title": "Introduction to Zig",
     "section": "Acknowledgments",
-    "text": "Acknowledgments\nThis book is also a product of many conversations and exchanges that we had with different people from the Zig community. I (Pedro Duarte Faria) am incredibly grateful for these conversations, and also, for some direct contributions that we had. Below we have a list of the people involved (name of the person with their usename in GitHub):\nCalin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang)",
+    "text": "Acknowledgments\nThis book is also a product of many conversations and exchanges that we had with different people from the Zig community. I (Pedro Duarte Faria) am incredibly grateful for these conversations, and also, for some direct contributions that we had. Below we have a list of the people involved (name of the person with their usename in GitHub):\nCalin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang), Tommaso Ricci (@Zorgatone), Primo Sabatini (@primos63), Santiago Fernandez (@santif), Hamza Wahed (@HamzaWahed), mwilbur (@mwilbur)",
     "crumbs": [
       "Welcome"
     ]

From afc69bd483d8fe72af8d2626655c4354226bdc52 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Thu, 30 Jan 2025 23:43:51 -0300
Subject: [PATCH 033/151] Recompile book with changes

---
 .../01-zig-weird/execute-results/html.json       |  8 +++++---
 .../03-structs/execute-results/html.json         |  4 ++--
 docs/Chapters/01-zig-weird.html                  |  8 ++++----
 docs/Chapters/03-structs.html                    | 16 ++++++++--------
 docs/search.json                                 | 12 ++++++------
 5 files changed, 25 insertions(+), 23 deletions(-)

diff --git a/_freeze/Chapters/01-zig-weird/execute-results/html.json b/_freeze/Chapters/01-zig-weird/execute-results/html.json
index 11a7f613..28800571 100644
--- a/_freeze/Chapters/01-zig-weird/execute-results/html.json
+++ b/_freeze/Chapters/01-zig-weird/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "3e66c278de9f34fb70ff9abb53f3d4ce",
+  "hash": "507166385ff85ccf512b153b7c107291",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\nlanguage, it is still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. They really make it sometimes hard to debug\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscures the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that get's compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e. it is where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `ìnit` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contain Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nTherefore, Zig contains a native build system in it, and\nwe can use this build system to write small scripts in Zig,\nwhich describes the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e. creating new objects)\nare made in Zig. You can create a new object in Zig by using the following syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). At @sec-assignments we talk more about objects in general.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that at @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIs worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt is like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portale C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nOn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOs. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e. the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. Thus, if you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith a \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, operations like accessing the `stdout` (or opening a file) on Windows\ndepends on resources that are available only at *runtime* (you will learn more about compile-time\nversus runtime at @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword at @sec-comptime.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation at a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues \n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described at @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig latter in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig? \nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar in our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentations.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It is a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (at YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e. identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compiles successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nIn contrast, if you use `var`, then, the object created is a variable object.\nWith `var` you can declare this object in your source code, and then,\nchange the value of this object how many times you want over future points\nin your source code.\n\nSo, using the same code example exposed above, if I change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it is an \"variable object\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIs important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code use this object while it is uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object. \n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e. if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to an special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It is discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also get's discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e. the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\n\nIs worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array. \n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it is a slice that\naccess all elements in the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" at @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth at @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially at @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned at @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e. the start and the end of this range)\nis known at compile-time, the slice object that get's created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nat @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that get's created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e. a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can \ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n```\n:::\n\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat get's created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, the `slice` object have a runtime known range, because the end index of the range\nis not known at compile time. In other words, the size of the array at `buffer` is not known\nat compile time. When we execute this program, the size of the array might be 10, or, it might be 12\ndepending on where we execute it. Therefore, we don't know at compile time if\nthe slice object have a range of size 10, or, a range of size 12.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e. a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented at @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e. `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIs worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e. the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause is much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e. if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it is a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIs important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligates you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig at @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers at @sec-root-file and especially at @sec-assignments.\n- How strings work in Zig at @sec-zig-strings.\n- How to use arrays and slices at @sec-arrays.\n- How to import functionality from other Zig modules at @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* at @sec-structs-and-oop.\n- Basic control flow syntax at @sec-zig-control-flow.\n- Enums at @sec-enum;\n- Pointers and Optionals at @sec-pointer;\n- Error handling with `try` and `catch` at @sec-error-handling;\n- Unit tests at @sec-unittests;\n- Vectors at @sec-vectors-simd;\n- Build System at @sec-build-system;\n\n\n\n\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\nlanguage, it is still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. They really make it sometimes hard to debug\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscures the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that get's compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e. it is where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contain Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nTherefore, Zig contains a native build system in it, and\nwe can use this build system to write small scripts in Zig,\nwhich describes the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e. creating new objects)\nare made in Zig. You can create a new object in Zig by using the following syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). At @sec-assignments we talk more about objects in general.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that at @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIs worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt is like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portale C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nOn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOs. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e. the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. Thus, if you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith a \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, operations like accessing the `stdout` (or opening a file) on Windows\ndepends on resources that are available only at *runtime* (you will learn more about compile-time\nversus runtime at @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword at @sec-comptime.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation at a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues \n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described at @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig latter in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig? \nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar in our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentations.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It is a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (at YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e. identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nIn contrast, if you use `var`, then, the object created is a variable object.\nWith `var` you can declare this object in your source code, and then,\nchange the value of this object how many times you want over future points\nin your source code.\n\nSo, using the same code example exposed above, if I change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it is an \"variable object\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIs important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code use this object while it is uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object. \n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e. if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to an special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It is discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also get's discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e. the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\nIs worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array. \n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it is a slice that\naccess all elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" at @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth at @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially at @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned at @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e. the start and the end of this range)\nis known at compile-time, the slice object that get's created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nat @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that get's created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e. a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can \ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n```\n:::\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat get's created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, the `slice` object have a runtime known range, because the end index of the range\nis not known at compile time. In other words, the size of the array at `buffer` is not known\nat compile time. When we execute this program, the size of the array might be 10, or, it might be 12\ndepending on where we execute it. Therefore, we don't know at compile time if\nthe slice object have a range of size 10, or, a range of size 12.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e. a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented at @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e. `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIs worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e. the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause it is much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e. if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it is a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIs important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig at @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers at @sec-root-file and especially at @sec-assignments.\n- How strings work in Zig at @sec-zig-strings.\n- How to use arrays and slices at @sec-arrays.\n- How to import functionality from other Zig modules at @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* at @sec-structs-and-oop.\n- Basic control flow syntax at @sec-zig-control-flow.\n- Enums at @sec-enum;\n- Pointers and Optionals at @sec-pointer;\n- Error handling with `try` and `catch` at @sec-error-handling;\n- Unit tests at @sec-unittests;\n- Vectors at @sec-vectors-simd;\n- Build System at @sec-build-system;\n\n\n\n\n",
+    "supporting": [
+      "01-zig-weird_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/03-structs/execute-results/html.json b/_freeze/Chapters/03-structs/execute-results/html.json
index 04f37e1b..fb55828f 100644
--- a/_freeze/Chapters/03-structs/execute-results/html.json
+++ b/_freeze/Chapters/03-structs/execute-results/html.json
@@ -1,8 +1,8 @@
 {
-  "hash": "cedb7b341aa333220e9f4f2918e4ea74",
+  "hash": "75a34188e80fdc2dce5441514f1bc59a",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Control flow, structs, modules and types\n\nWe have discussed a lot of Zig's syntax in the last chapter,\nespecially in @sec-root-file and @sec-main-file.\nBut we still need to discuss some other very important\nelements of the language. Elements that you will use constantly on your day-to-day\nroutine.\n\nWe begin this chapter by discussing the different keywords and structures\nin Zig related to control flow (e.g. loops and if statements).\nThen, we talk about structs and how they can be used to do some\nbasic Object-Oriented (OOP) patterns in Zig. We also talk about\ntype inference and type casting.\nFinally, we end this chapter by discussing modules, and how they relate\nto structs.\n\n\n\n## Control flow {#sec-zig-control-flow}\n\nSometimes, you need to make decisions in your program. Maybe you need to decide\nwhether or not to execute a specific piece of code. Or maybe,\nyou need to apply the same operation over a sequence of values. These kinds of tasks,\ninvolve using structures that are capable of changing the \"control flow\" of our program.\n\nIn computer science, the term \"control flow\" usually refers to the order in which expressions (or commands)\nare evaluated in a given language or program. But this term is also used to refer\nto structures that are capable of changing this \"evaluation order\" of the commands\nexecuted by a given language/program.\n\nThese structures are better known\nby a set of terms, such as: loops, if/else statements, switch statements, among others. So,\nloops and if/else statements are examples of structures that can change the \"control\nflow\" of our program. The keywords `continue` and `break` are also examples of symbols\nthat can change the order of evaluation, since they can move our program to the next iteration\nof a loop, or make the loop stop completely.\n\n\n### If/else statements\n\nAn if/else statement performs a \"conditional flow operation\".\nA conditional flow control (or choice control) allows you to execute\nor ignore a certain block of commands based on a logical condition.\nMany programmers and computer science professionals also use\nthe term \"branching\" in this case.\nIn essence, an if/else statement allow us to use the result of a logical test\nto decide whether or not to execute a given block of commands.\n\nIn Zig, we write if/else statements by using the keywords `if` and `else`.\nWe start with the `if` keyword followed by a logical test inside a pair\nof parentheses, followed by a pair of curly braces which contains the lines\nof code to be executed in case the logical test returns the value `true`.\n\nAfter that, you can optionally add an `else` statement. To do that, just add the `else`\nkeyword followed by a pair of curly braces, with the lines of code\nto executed in case the logical test defined at `if` returns `false`.\n\nIn the example below, we are testing if the object `x` contains a number\nthat is greater than 10. Judging by the output printed to the console,\nwe know that this logical test returned `false`. Because the output\nin the console is compatible with the line of code present in the\n`else` branch of the if/else statement.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x = 5;\nif (x > 10) {\n    try stdout.print(\n        \"x > 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x <= 10!\\n\", .{}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nx <= 10!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Switch statements {#sec-switch}\n\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust.\nAs you would expect, to write a switch statement in Zig we use the `switch` keyword.\nWe provide the value that we want to \"switch over\" inside a\npair of parentheses. Then, we list the possible combinations (or \"branches\")\ninside a pair of curly braces.\n\nLet's take a look at the code example below. You can see that\nI'm creating an enum type called `Role`. We talk more about enums in @sec-enum.\nBut in summary, this `Role` type is listing different types of roles in a fictitious\ncompany, like `SE` for Software Engineer, `DE` for Data Engineer, `PM` for Product Manager,\netc.\n\nNotice that we are using the value from the `role` object in the\nswitch statement, to discover which exact area we need to store in the `area` variable object.\nAlso notice that we are using type inference inside the switch statement, with the dot character,\nas we are going to describe in @sec-type-inference.\nThis makes the `zig` compiler infer the correct data type of the values (`PM`, `SE`, etc.) for us.\n\nAlso notice that, we are grouping multiple values in the same branch of the switch statement.\nWe just separate each possible value with a comma. For example, if `role` contains either `DE` or `DA`,\nthe `area` variable would contain the value `\"Data & Analytics\"`, instead of `\"Platform\"` or `\"Sales\"`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO => {\n            area = \"Platform\";\n        },\n        .DE, .DA => {\n            area = \"Data & Analytics\";\n        },\n        .KS => {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nPlatform\n```\n\n\n:::\n:::\n\n\n\n\n\n#### Switch statements must exhaust all possibilities\n\nOne very important aspect about switch statements in Zig\nis that they must exhaust all existing possibilities.\nIn other words, all possible values that could be found inside the `order`\nobject must be explicitly handled in this switch statement.\n\nSince the `role` object have type `Role`, the only possible values to\nbe found inside this object are `PM`, `SE`, `DPE`, `PO`, `DE`, `DA` and `KS`.\nThere are no other possible values to be stored in this `role` object.\nThus, the switch statements must have a combination (branch) for each one of these values.\nThis is what \"exhaust all existing possibilities\" means. The switch statement covers\nevery possible case.\n\nTherefore, you cannot write a switch statement in Zig, and leave an edge case\nwith no explicit action to be taken.\nThis is a similar behaviour to switch statements in Rust, which also have to\nhandle all possible cases.\n\n\n\n#### The else branch\n\nTake a look at the `dump_hex_fallible()` function below as an example. This function\ncomes from the Zig Standard Library. More precisely, from the\n[`debug.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/debug.zig)[^debug-mod].\nThere are multiple lines in this function, but I omitted them to focus solely on the\nswitch statement found in this function. Notice that this switch statement has four\npossible cases (i.e. four explicit branches). Also, notice that we used an `else` branch\nin this case.\n\nAn `else` branch in a switch statement works as the \"default branch\".\nWhenever you have multiple cases in your switch statement where\nyou want to apply the exact same action, you can use an `else` branch to do that.\n\n[^debug-mod]: <https://github.com/ziglang/zig/blob/master/lib/std/debug.zig>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' => try writer.writeAll(\"␊\"),\n        '\\r' => try writer.writeAll(\"␍\"),\n        '\\t' => try writer.writeAll(\"␉\"),\n        else => try writer.writeByte('.'),\n    }\n}\n```\n:::\n\n\n\n\nMany programmers would also use an `else` branch to handle a \"not supported\" case.\nThat is, a case that cannot be properly handled by your code, or, just a case that\nshould not be \"fixed\". Therefore, you can use an `else` branch to panic (or raise an error)\nin your program to stop the current execution.\n\nTake the code example below. We can see that, we are handling the cases\nfor the `level` object being either 1, 2, or 3. All other possible cases are not supported by default,\nand, as consequence, we raise a runtime error in such cases through the `@panic()` built-in function.\n\nAlso notice that, we are assigning the result of the switch statement to a new object called `category`.\nThis is another thing that you can do with switch statements in Zig. If a branch\noutputs a value as result, you can store the result value of the switch statement into\na new object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 => \"beginner\",\n    3 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n:::\n\n\n\n\n```\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n```\n\n\n\n#### Using ranges in switch\n\nFurthermore, you can also use ranges of values in switch statements.\nThat is, you can create a branch in your switch statement that is used\nwhenever the input value is within the specified range. These \"range expressions\"\nare created with the operator `...`. It is important\nto emphasize that the ranges created by this operator are\ninclusive on both ends.\n\nFor example, I could easily change the previous code example to support all\nlevels between 0 and 100. Like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 => \"beginner\",\n    26...75 => \"intermediary\",\n    76...100 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nbeginner\n```\n\n\n:::\n:::\n\n\n\n\nThis is neat, and it works with character ranges too. That is, I could\nsimply write `'a'...'z'`, to match any character value that is a\nlowercase letter, and it would work fine.\n\n\n#### Labeled switch statements\n\nIn @sec-blocks we have talked about labeling blocks, and also, about using these labels\nto return a value from the block. Well, from version 0.14.0 and onwards of the `zig` compiler,\nyou can also apply labels over switch statements, which makes it possible to almost implement a\n\"C `goto`\" like pattern.\n\nFor example, if you give the label `xsw` to a switch statement, you can use this\nlabel in conjunction with the `continue` keyword to go back to the beginning of the switch\nstatement. In the example below, the execution goes back to the beginning of the\nswitch statement two times, before ending at the `3` branch.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nxsw: switch (@as(u8, 1)) {\n    1 => {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 => continue :xsw 3,\n    3 => return,\n    4 => {},\n    else => {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n```\n:::\n\n\n\n\n\n### The `defer` keyword {#sec-defer}\n\nWith the `defer` keyword you can register an expression to be executed when you exit the current scope.\nTherefore, this keyword has a similar functionality as the `on.exit()` function from R.\nTake the `foo()` function below as an example. When we execute this `foo()` function, the expression\nthat prints the message \"Exiting function ...\" is getting executed only when the function exits\nits scope.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nAdding some numbers ...\nMultiplying ...\nExiting function ...\n```\n\nTherefore, we can use `defer` to declare an expression that is going to be executed\nwhen your code exits the current scope. Some programmers like to interpret the phrase \"exit of the current scope\"\nas \"the end of the current scope\". But this interpretation might not be entirely correct, depending\non what you consider as \"the end of the current scope\".\n\nI mean, what do you consider as **the end** of the current scope? Is it the closing curly bracket (`}`) of the scope?\nIs it when the last expression in the function get's executed? Is it when the function returns to the previous scope?\nEtc. For example, it would not be correct to interpret the \"exit of the current scope\" as the closing\ncurly bracket of the scope. Because the function might exit from an earlier position than this\nclosing curly bracket (e.g. an error value was generated at a previous line inside the function;\nthe function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\n\nNow, if you remember of what we have discussed in @sec-blocks, there are multiple structures in the language\nthat create their own separate scopes. For/while loops, if/else statements,\nfunctions, normal blocks, etc. This also affects the interpretation of `defer`.\nFor example, if you use `defer` inside a for loop, then, the given expression\nwill be executed everytime this specific for loop exits its own scope.\n\nBefore we continue, is worth emphasizing that the `defer` keyword is an \"unconditional defer\".\nWhich means that the given expression will be executed no matter how the code exits\nthe current scope. For example, your code might exit the current scope because of an error value\nbeing generated, or, because of a return statement, or, a break statement, etc.\n\n\n\n### The `errdefer` keyword {#sec-errdefer1}\n\nOn the previous section, we have discussed the `defer` keyword, which you can use to\nregister an expression to be executed at the exit of the current scope.\nBut this keyword has a brother, which is the `errdefer` keyword. While `defer`\nis an \"unconditional defer\", the `errdefer` keyword is a \"conditional defer\".\nWhich means that the given expression is executed only when you exit the current\nscope on a very specific circumstance.\n\nIn more details, the expression given to `errdefer` is executed only when an error occurs in the current scope.\nTherefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope\nin a normal situation, without errors, the expression given to `errdefer` is not executed.\n\nThis makes the `errdefer` keyword one of the many tools available in Zig for error handling.\nIn this section, we are more concerned with the control flow aspects around `errdefer`.\nBut we are going to discuss `errdefer` later as a error handling tool in @sec-errdefer2.\n\nThe code example below demonstrates three things:\n\n- that `defer` is an \"unconditional defer\", because the given expression get's executed regardless of how the function `foo()` exits its own scope.\n- that `errdefer` is executed because the function `foo()` returned an error value.\n- that `defer` and `errdefer` expressions are executed in a LIFO (*last in, first out*) order.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\nWhen I say that \"defer expressions\" are executed in a LIFO order, what I want to say is that\nthe last `defer` or `errdefer` expressions in the code are the first ones to be executed.\nYou could also interpret this as: \"defer expressions\" are executed from bottom to top, or,\nfrom last to first.\n\nTherefore, if I change the order of the `defer` and `errdefer` expressions, you will notice that\nthe value of `i` that get's printed to the console changes to 1. This doesn't mean that the\n`defer` expression was not executed in this case. This actually means that the `defer` expression\nwas executed only after the `errdefer` expression. The code example below demonstrates this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\n\n\n### For loops\n\nA loop allows you to execute the same lines of code multiple times,\nthus, creating a \"repetition space\" in the execution flow of your program.\nLoops are particularly useful when we want to replicate the same function\n(or the same set of commands) over different inputs.\n\nThere are different types of loops available in Zig. But the most\nessential of them all is probably the *for loop*. A for loop is\nused to apply the same piece of code over the elements of a slice, or, an array.\n\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from\nother languages. You start with the `for` keyword, then, you\nlist the items that you want to iterate\nover inside a pair of parentheses. Then, inside of a pair of pipes (`|`)\nyou should declare an identifier that will serve as your iterator, or,\nthe \"repetition index of the loop\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (items) |value| {\n    // code to execute\n}\n```\n:::\n\n\n\n\nTherefore, instead of using a `(value in items)` syntax,\nin Zig, for loops use the syntax `(items) |value|`. In the example\nbelow, you can see that we are looping through the items\nof the array stored at the object `name`, and printing to the\nconsole the decimal representation of each character in this array.\n\nIf we wanted, we could also iterate through a slice (or a portion) of\nthe array, instead of iterating through the entire array stored in the `name` object.\nJust use a range selector to select the section you want. For example,\nI could provide the expression `name[0..3]` to the for loop, to iterate\njust through the first 3 elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n80 | 101 | 100 | 114 | 111 | \n```\n\n\n:::\n:::\n\n\n\n\nIn the above example we are using the value itself of each\nelement in the array as our iterator. But there are many situations where\nwe need to use an index instead of the actual values of the items.\n\nYou can do that by providing a second set of items to iterate over.\nMore precisely, you provide the range selector `0..` to the for loop. So,\nyes, you can use two different iterators at the same time in a for\nloop in Zig.\n\nBut remember from @sec-assignments that, every object\nyou create in Zig must be used in some way. So if you declare two iterators\nin your for loop, you must use both iterators inside the for loop body.\nBut if you want to use just the index iterator, and not use the \"value iterator\",\nthen, you can discard the value iterator by maching the\nvalue items to the underscore character, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n:::\n\n\n\n\n```\n0 | 1 | 2 | 3 | 4 |\n```\n\n\n### While loops\n\nA while loop is created from the `while` keyword. A `for` loop\niterates through the items of an array, but a `while` loop\nwill loop continuously, and infinitely, until a logical test\n(specified by you) becomes false.\n\nYou start with the `while` keyword, then, you define a logical\nexpression inside a pair of parentheses, and the body of the\nloop is provided inside a pair of curly braces, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\nYou can also specify the increment expression to be used at the beginning of a while loop.\nTo do that, we write the increment expression inside a pair of parentheses after a colon character (`:`).\nThe code example below demonstrates this other pattern.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\n### Using `break` and `continue`\n\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using\nthe keywords `break` and `continue`, respectively. The `while` loop presented in the next code example is,\nat first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to `true`.\nBut what makes this `while` loop stop when the `i` object reaches the count\n10? It is the `break` keyword!\n\nInside the while loop, we have an if statement that is constantly checking if the `i` variable\nis equal to 10. Since we are incrementing the value of `i` at each iteration of the\nwhile loop, this `i` object will eventually be equal to 10, and when it is, the if statement\nwill execute the `break` expression, and, as a result, the execution of the while loop is stopped.\n\nNotice the use of the `expect()` function from the Zig Standard Library after the while loop.\nThis `expect()` function is an \"assert\" type of function.\nThis function checks if the logical test provided is equal to true. If so, the function do nothing.\nOtherwise (i.e. the logical test is equal to false), the function raises an assertion error.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nEverything worked!\n```\n\n\n:::\n:::\n\n\n\n\nSince this code example was executed successfully by the `zig` compiler,\nwithout raising any errors, we known that, after the execution of the while loop,\nthe `i` object is equal to 10. Because if it wasn't equal to 10, an error would have\nbeen raised by `expect()`.\n\nNow, in the next example, we have a use case for\nthe `continue` keyword. The if statement is constantly\nchecking if the current index is a multiple of 2. If\nit is, we jump to the next iteration of the loop.\nOtherwise, the loop just prints the current index to the console.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 3 | 5 | \n```\n\n\n:::\n:::\n\n\n\n\n\n\n## Function parameters are immutable {#sec-fun-pars}\n\nWe have already discussed a lot of the syntax behind function declarations in @sec-root-file and @sec-main-file.\nBut I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig.\nIn summary, function parameters are immutable in Zig.\n\nTake the code example below, where we declare a simple function that just tries to add\nsome amount to the input integer, and returns the result back. If you look closely\nat the body of this `add2()` function, you will notice that we try\nto save the result back into the `x` function argument.\n\nIn other words, this function not only uses the value that it received through the function argument\n`x`, but it also tries to change the value of this function argument, by assigning the addition result\ninto `x`. However, function arguments in Zig are immutable. You cannot change their values, or, you\ncannot assign values to them inside the body's function.\n\nThis is the reason why, the code example below does not compile successfully. If you try to compile\nthis code example, you will get a compile error message about \"trying to change the value of a\nimmutable (i.e. constant) object\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n\n\n```\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n```\n\n\n### A free optimization\n\nIf a function argument receives as input an object whose data type is\nany of the primitive types that we have listed in @sec-primitive-data-types,\nthis object is always passed by value to the function. In other words, this object\nis copied into the function stack frame.\n\nHowever, if the input object have a more complex data type, for example, it might\nbe a struct instance, or an array, or an union value, etc., in cases like that, the `zig` compiler\nwill take the liberty of deciding for you which strategy is best. Thus, the `zig` compiler will\npass your object to the function either by value, or by reference. The compiler will always\nchoose the strategy that is faster for you.\nThis optimization that you get for free is possible only because function arguments are\nimmutable in Zig.\n\n\n### How to overcome this barrier\n\nThere are some situations where you might need to change the value of your function argument\ndirectly inside the function's body. This happens more often when we are passing\nC structs as inputs to Zig functions.\n\nIn a situation like this, you can overcome this barrier by using a pointer. In other words,\ninstead of passing a value as input to the argument, you can pass a \"pointer to value\" instead.\nYou can change the value that the pointer points to, by dereferencing it.\n\nTherefore, if we take our previous `add2()` example, we can change the value of the\nfunction argument `x` inside the function's body by marking the `x` argument as a\n\"pointer to a `u32` value\" (i.e. `*u32` data type), instead of a `u32` value.\nBy making it a pointer, we can finally alter the value of this function argument directly inside\nthe body of the `add2()` function. You can see that the code example below compiles successfully.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n```\n:::\n\n\n\n\n```\nResult: 6\n```\n\n\nEven in this code example above, the `x` argument is still immutable. Which means that the pointer itself is immutable.\nTherefore, you cannot change the memory address that it points to. However, you can dereference the pointer\nto access the value that it points to, and also, to change this value, if you need to.\n\n\n\n\n\n## Structs and OOP {#sec-structs-and-oop}\n\nZig is a language more closely related to C (which is a procedural language),\nthan it is to C++ or Java (which are object-oriented languages). Because of that, you do not\nhave advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or\nclass inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\n\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C.\nYou give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can\nalso register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object\nthat you create with this new type, will always have these methods available and associated with them.\n\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which\nis used to construct (or, to instantiate) every object of this particular class, and we also have\na destructor method (or a destructor function), which is the function responsible for destroying\nevery object of this class.\n\nIn Zig, we normally declare the constructor and the destructor methods\nof our structs, by declaring an `init()` and a `deinit()` methods inside the struct.\nThis is just a naming convention that you will find across the entire Zig Standard Library.\nSo, in Zig, the `init()` method of a struct is normally the constructor method of the class represented by this struct.\nWhile the `deinit()` method is the method used for destroying an existing instance of that struct.\n\nThe `init()` and `deinit()` methods are both used extensively in Zig code, and you will see both of\nthem being used when we talk about allocators in @sec-allocators.\nBut, as another example, let's build a simple `User` struct to represent a user of some sort of system.\n\nIf you look at the `User` struct below, you can see the `struct` keyword.\nNotice the data members of this struct: `id`, `name` and `email`. Every data member has its\ntype explicitly annotated, with the colon character (`:`) syntax that we described earlier in @sec-root-file.\nBut also notice that every line in the struct body that describes a data member, ends with a comma character (`,`).\nSo every time you declare a data member in your Zig code, always end the line with a comma character, instead\nof ending it with the traditional semicolon character (`;`).\n\nNext, we have registered an `init()` function as a method\nof this `User` struct. This `init()` method is the constructor method that we will use to instantiate\nevery new `User` object. That is why this `init()` function returns a new `User` object as result.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    pub fn init(id: u64,\n                name: []const u8,\n                email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    pub fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\npedro\n```\n\n\n:::\n:::\n\n\n\n\nThe `pub` keyword plays an important role in struct declarations, and OOP in Zig.\nEvery method that you declare in your struct that is marked with the keyword `pub`,\nbecomes a public method of this particular struct.\n\nSo every method that you create inside your struct, is, at first, a private method\nof that struct. Meaning that, this method can only be called from within this\nstruct. But, if you mark this method as public, with the keyword `pub`, then,\nyou can call the method directly from an instance of the `User` struct.\n\nIn other words, the functions marked by the keyword `pub`\nare members of the public API of that struct.\nFor example, if I did not mark the `print_name()` method as public,\nthen, I could not execute the line `u.print_name()`. Because I would\nnot be authorized to call this method directly in my code.\n\n\n\n### Anonymous struct literals {#sec-anonymous-struct-literals}\n\nYou can declare a struct object as a literal value. When we do that, we normally specify the\ndata type of this struct literal by writing its data type just before the opening curly brace.\nFor example, I could write a struct literal value of the type `User` that we have defined\nin the previous section like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n```\n:::\n\n\n\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a\nstruct literal, but not specify explicitly the type of this particular struct.\nAn anonymous struct is written by using the syntax `.{}`. So, we essentially\nreplaced the explicit type of the struct literal with a dot character (`.`).\n\nAs we described in @sec-type-inference, when you put a dot before a struct literal,\nthe type of this struct literal is automatically inferred by the `zig` compiler.\nIn essence, the `zig` compiler will look for some hint of what is the type of that struct.\nThis hint can be the type annotation of a function argument,\nor the return type annotation of the function that you are using, or the type annotation\nof an existing object.\nIf the compiler does find such type annotation, it will use this\ntype in your literal struct.\n\nAnonymous structs are very commonly used as inputs to function arguments in Zig.\nOne example that you have seen already constantly, is the `print()`\nfunction from the `stdout` object.\nThis function takes two arguments.\nThe first argument, is a template string, which should\ncontain string format specifiers in it, which tells how the values provided\nin the second argument should be printed into the message.\n\nWhile the second argument is a struct literal that lists the values\nto be printed into the template message specified in the first argument.\nYou normally want to use an anonymous struct literal here, so that the\n`zig` compiler do the job of specifying the type of this particular\nanonymous struct for you.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello, world!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Struct declarations must be constant\n\nTypes in Zig must be `const` or `comptime` (we are going to talk more about comptime in @sec-comptime).\nWhat this means is that you cannot create a new data type, and mark it as variable with the `var` keyword.\nSo struct declarations are always constant. You cannot declare a new struct type using the `var` keyword.\nIt must be `const`.\n\nIn the `Vec3` example below, this declaration is allowed because I'm using the `const` keyword\nto declare this new data type.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n```\n:::\n\n\n\n\n\n### The `self` method argument {#sec-self-arg}\n\nIn every language that have OOP, when we declare a method of some class or struct, we\nusually declare this method as a function that has a `self` argument.\nThis `self` argument is the reference to the object itself from which the method\nis being called from.\n\nIt is not mandatory to use this `self` argument. But why would you not use this `self` argument?\nThere is no reason to not use it. Because the only way to get access to the data stored in the\ndata members of your struct is to access them through this `self` argument.\nIf you don't need to use the data in the data members of your struct inside your method, you very likely don't need\na method. You can just declare this logic as a simple function, outside of your\nstruct declaration.\n\n\nTake the `Vec3` struct below. Inside this `Vec3` struct we declared a method named `distance()`.\nThis method calculates the distance between two `Vec3` objects, by following the distance\nformula in euclidean space. Notice that this `distance()` method takes two `Vec3` objects\nas input, `self` and `other`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n```\n:::\n\n\n\n\n\nThe `self` argument corresponds to the `Vec3` object from which this `distance()` method\nis being called from. While the `other` is a separate `Vec3` object that is given as input\nto this method. In the example below, the `self` argument corresponds to the object\n`v1`, because the `distance()` method is being called from the `v1` object,\nwhile the `other` argument corresponds to the object `v2`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n```\n:::\n\n\n\n\n```\nDistance: 3.3970575502926055\n```\n\n\n\n### About the struct state\n\nSometimes you don't need to care about the state of your struct object. Sometimes, you just need\nto instantiate and use the objects, without altering their state. You can notice that when you have methods\ninside your struct declaration that might use the values that are present in the data members, but they\ndo not alter the values in these data members of the struct in anyway.\n\nThe `Vec3` struct that was presented in @sec-self-arg is an example of that.\nThis struct have a single method named `distance()`, and this method does use the values\npresent in all three data members of the struct (`x`, `y` and `z`). But at the same time,\nthis method does not change the values of these data members at any point.\n\nAs a result of that, when we create `Vec3` objects we usually create them as\nconstant objects, like the `v1` and `v2` objects presented in @sec-self-arg.\nWe can create them as variable objects with the `var` keyword,\nif we want to. But because the methods of this `Vec3` struct do not change\nthe state of the objects in any point, it's unnecessary to mark them\nas variable objects.\n\nBut why? Why am I talking about this here? It's because the `self` argument\nin the methods is affected depending on whether the\nmethods present in a struct change or don't change the state of the object itself.\nMore specifically, when you have a method in a struct that changes the state\nof the object (i.e. change the value of a data member), the `self` argument\nin this method must be annotated in a different manner.\n\nAs I described in @sec-self-arg, the `self` argument in methods of\na struct is the argument that receives as input the object from which the method\nwas called from. We usually annotate this argument in the methods by writing `self`,\nfollowed by the colon character (`:`), and the data type of the struct to which\nthe method belongs to (e.g. `User`, `Vec3`, etc.).\n\nIf we take the `Vec3` struct that we defined in the previous section as an example,\nwe can see in the `distance()` method that this `self` argument is annotated as\n`self: Vec3`. Because the state of the `Vec3` object is never altered by this\nmethod.\n\nBut what if we do have a method that alters the state of the object, by altering the\nvalues of its data members, how should we annotate `self` in this instance? The answer is:\n\"we should annotate `self` as a pointer of `x`, instead of just `x`\".\nIn other words, you should annotate `self` as `self: *x`, instead of annotating it\nas `self: x`.\n\nIf we create a new method inside the `Vec3` object that, for example, expands the\nvector by multiplying its coordinates by a factor of two, then, we need to follow\nthis rule specified in the previous paragraph. The code example below demonstrates\nthis idea:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n```\n:::\n\n\n\n\nNotice in the code example above that we have added a new method\nto our `Vec3` struct named `twice()`. This method doubles the\ncoordinate values of our vector object. In the\ncase of the `twice()` method, we annotated the `self` argument as `*Vec3`,\nindicating that this argument receives a pointer (or a reference, if you prefer to call it this way)\nto a `Vec3` object as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n```\n:::\n\n\n\n\n```\nDoubled: 8.4\n```\n\n\n\nNow, if you change the `self` argument in this `twice()` method to `self: Vec3`, like in the\n`distance()` method, you will get the compiler error exposed below as result. Notice that this\nerror message is showing a line from the `twice()` method body,\nindicating that you cannot alter the value of the `x` data member.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n```\n:::\n\n\n\n\n```\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\n```\n\nThis error message indicates that the `x` data member belongs to a constant object,\nand, because of that, it cannot be changed. Ultimately, this error message\nis telling us that the `self` argument is constant.\n\nIf you take some time, and think hard about this error message, you will understand it.\nYou already have the tools to understand why we are getting this error message.\nWe have talked about it already in @sec-fun-pars.\nSo remember, every function argument is immutable in Zig, and `self`\nis no exception to this rule.\n\nIn this example, we marked the `v3` object as a variable object.\nBut this does not matter. Because it is not about the input object, it is about\nthe function argument.\n\nThe problem begins when we try to alter the value of `self` directly, which is a function argument,\nand, every function argument is immutable by default. You may ask yourself how can we overcome\nthis barrier, and once again, the solution was also discussed in @sec-fun-pars.\nWe overcome this barrier, by explicitly marking the `self` argument as a pointer.\n\n\n::: {.callout-note}\nIf a method of your `x` struct alters the state of the object, by\nchanging the value of any data member, then, remember to use `self: *x`,\ninstead of `self: x` in the function signature of this method.\n:::\n\n\nYou could also interpret the content discussed in this section as:\n\"if you need to alter the state of your `x` struct object in one of its methods,\nyou must explicitly pass the `x` struct object by reference to the `self` argument of this method\".\n\n\n\n## Type inference {#sec-type-inference}\n\nZig is a strongly typed language. But, there are some situations\nwhere you don't have to explicitly write the type of every single object in your source code,\nas you would expect from a traditional strongly typed language, such as C and C++.\n\nIn some situations, the `zig` compiler can use type inference to solve the data types for you, easing some of\nthe burden that you carry as a developer.\nThe most common way this happens is through function arguments that receive struct objects\nas input.\n\nIn general, type inference in Zig is done by using the dot character (`.`).\nEverytime you see a dot character written before a struct literal, or before an enum value, or something like that,\nyou know that this dot character is playing a special party in this place. More specifically, it is\ntelling the `zig` compiler something along the lines of: \"Hey! Can you infer the type of this\nvalue for me? Please!\". In other words, this dot character is playing a similar role as the `auto` keyword in C++.\n\nI gave you some examples of this in @sec-anonymous-struct-literals, where we used anonymous struct literals.\nAnonymous struct literals are, struct literals that use type inference to\ninfer the exact type of this particular struct literal.\nThis type inference is done by looking for some minimal hint of the correct data type to be used.\nYou could say that the `zig` compiler looks for any neighbouring type annotation that might tell it\nwhat the correct type would be.\n\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in @sec-switch).\nI also gave some other examples of type inference in @sec-switch, where we were inferring the data types of enum values listed inside\nof switch statements (e.g. `.DE`).\nBut as another example, take a look at this `fence()` function reproduced below,\nwhich comes from the [`atomic.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig)[^fence-fn]\nof the Zig Standard Library.\n\n[^fence-fn]: <https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig>.\n\nThere are a lot of things in this function that we haven't talked about yet, such as:\nwhat `comptime` means? `inline`? `extern`?\nLet's just ignore all of these things, and focus solely on the switch statement\nthat is inside this function.\n\nWe can see that this switch statement uses the `order` object as input. This `order`\nobject is one of the inputs of this `fence()` function, and we can see in the type annotation,\nthat this object is of type `AtomicOrder`. We can also see a bunch of values inside the\nswitch statements that begin with a dot character, such as `.release` and `.acquire`.\n\nBecause these weird values contain a dot character before them, we are asking the `zig`\ncompiler to infer the types of these values inside the switch statement. Then, the `zig`\ncompiler is looking into the current context where these values are being used, and it is\ntrying to infer the types of these values.\n\nSince they are being used inside a switch statement, the `zig` compiler looks into the type\nof the input object given to the switch statement, which is the `order` object in this case.\nBecause this object have type `AtomicOrder`, the `zig` compiler infers that these values\nare data members from this type `AtomicOrder`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic => @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire => tsan.__tsan_acquire(addr),\n            .release => tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst => {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n```\n:::\n\n\n\n\nThis is how basic type inference is done in Zig. If we didn't use the dot character before\nthe values inside this switch statement, then, we would be forced to explicitly write\nthe data types of these values. For example, instead of writing `.release` we would have to\nwrite `AtomicOrder.release`. We would have to do this for every single value\nin this switch statement, and this is a lot of work. That is why type inference\nis commonly used on switch statements in Zig.\n\n\n\n## Type casting {#sec-type-cast}\n\nIn this section, I want to discuss type casting (or, type conversion) with you.\nWe use type casting when we have an object of type \"x\", and we want to convert\nit into an object of type \"y\", i.e. we want to change the data type of the object.\n\nMost languages have a formal way to perform type casting. In Rust for example, we normally\nuse the keyword `as`, and in C, we normally use the type casting syntax, e.g. `(int) x`.\nIn Zig, we use the `@as()` built-in function to cast an object of type \"x\", into\nan object of type \"y\".\n\nThis `@as()` function is the preferred way to perform type conversion (or type casting)\nin Zig. Because it is explicit, and, it also performs the casting only if it\nis unambiguous and safe. To use this function, you just provide the target data type\nin the first argument, and, the object that you want cast as the second argument.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file10b91234368fa.test_0...OKAll 1 tests passe\n  ed.\n```\n\n\n:::\n:::\n\n\n\n\nThis is the general way to perform type casting in Zig. But remember, `@as()` works only when casting\nis unambiguous and safe, and there are situations where these assumptions do not hold. For example,\nwhen casting an integer value into a float value, or vice-versa, it is not clear to the compiler\nhow to perform this conversion safely.\n\nTherefore, we need to use specialized \"casting functions\" in such situations.\nFor example, if you want to cast an integer value into a float value, then, you\nshould use the `@floatFromInt()` function. In the inverse scenario, you should use\nthe `@intFromFloat()` function.\n\nIn these functions, you just provide the object that you want to\ncast as input. Then, the target data type of the \"type casting operation\" is determined by\nthe type annotation of the object where you are saving the results.\nIn the example below, we are casting the object `x` into a value of type `f32`,\nbecause the object `y`, which is where we are saving the results, is annotated\nas an object of type `f32`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file10b9130ae9221.test_0...OKAll 1 tests passe\n  ed.\n```\n\n\n:::\n:::\n\n\n\n\nAnother built-in function that is very useful when performing type casting operations is `@ptrCast()`.\nIn essence, we use the `@as()` built-in function when we want to explicit convert (or cast) a Zig value/object\nfrom a type \"x\" to a type \"y\", etc. However, pointers (we are going to discuss pointers\nin more depth in @sec-pointer) are a special type of object in Zig,\ni.e. they are treated differently from \"normal objects\".\n\nEverytime a pointer is involved in some \"type casting operation\" in Zig, the `@ptrCast()` function is used.\nThis function works similarly to `@floatFromInt()`.\nYou just provide the pointer object that you want to cast as input to this function, and the\ntarget data type is, once again, determined by the type annotation of the object where the results are being\nstored.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file10b914c434861.test_0...OKAll 1 tests passe\n  ed.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## Modules\n\nWe already talked about what modules are, and also, how to import other modules into\nyour current module via *import statements*. Every Zig module (i.e. a `.zig` file) that you write in your project\nis internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the\nZig Standard Library into our current module.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n```\n:::\n\n\n\n\nWhen we want to access the functions and objects from the standard library, we\nare basically accessing the data members of the struct stored in the `std`\nobject. That is why we use the same syntax that we use in normal structs, with the dot operator (`.`)\nto access the data members and methods of the struct.\n\nWhen this \"import statement\" get's executed, the result of this expression is a struct\nobject that contains the Zig Standard Library modules, global variables, functions, etc.\nAnd this struct object get's saved (or stored) inside the constant object named `std`.\n\n\nTake the [`thread_pool.zig` module from the project `zap`](https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig)[^thread]\nas an example. This module is written as if it was\na big struct. That is why we have a top-level and public `init()` method\nwritten in this module. The idea is that all top-level functions written in this\nmodule are methods from the struct, and all top-level objects and struct declarations\nare data members of this struct. The module is the struct itself.\n\n[^thread]: <https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig>\n\n\nSo you would import and use this module by doing something like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst ThreadPool = @import(\"thread_pool.zig\");\nconst num_cpus = std.Thread.getCpuCount()\n    catch @panic(\"failed to get cpu core count\");\nconst num_threads = std.math.cast(u16, num_cpus)\n    catch std.math.maxInt(u16);\nconst pool = ThreadPool.init(\n    .{ .max_threads = num_threads }\n);\n```\n:::\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Control flow, structs, modules and types\n\nWe have discussed a lot of Zig's syntax in the last chapter,\nespecially in @sec-root-file and @sec-main-file.\nBut we still need to discuss some other very important\nelements of the language. Elements that you will use constantly on your day-to-day\nroutine.\n\nWe begin this chapter by discussing the different keywords and structures\nin Zig related to control flow (e.g. loops and if statements).\nThen, we talk about structs and how they can be used to do some\nbasic Object-Oriented (OOP) patterns in Zig. We also talk about\ntype inference and type casting.\nFinally, we end this chapter by discussing modules, and how they relate\nto structs.\n\n\n\n## Control flow {#sec-zig-control-flow}\n\nSometimes, you need to make decisions in your program. Maybe you need to decide\nwhether or not to execute a specific piece of code. Or maybe,\nyou need to apply the same operation over a sequence of values. These kinds of tasks,\ninvolve using structures that are capable of changing the \"control flow\" of our program.\n\nIn computer science, the term \"control flow\" usually refers to the order in which expressions (or commands)\nare evaluated in a given language or program. But this term is also used to refer\nto structures that are capable of changing this \"evaluation order\" of the commands\nexecuted by a given language/program.\n\nThese structures are better known\nby a set of terms, such as: loops, if/else statements, switch statements, among others. So,\nloops and if/else statements are examples of structures that can change the \"control\nflow\" of our program. The keywords `continue` and `break` are also examples of symbols\nthat can change the order of evaluation, since they can move our program to the next iteration\nof a loop, or make the loop stop completely.\n\n\n### If/else statements\n\nAn if/else statement performs a \"conditional flow operation\".\nA conditional flow control (or choice control) allows you to execute\nor ignore a certain block of commands based on a logical condition.\nMany programmers and computer science professionals also use\nthe term \"branching\" in this case.\nIn essence, an if/else statement allow us to use the result of a logical test\nto decide whether or not to execute a given block of commands.\n\nIn Zig, we write if/else statements by using the keywords `if` and `else`.\nWe start with the `if` keyword followed by a logical test inside a pair\nof parentheses, followed by a pair of curly braces which contains the lines\nof code to be executed in case the logical test returns the value `true`.\n\nAfter that, you can optionally add an `else` statement. To do that, just add the `else`\nkeyword followed by a pair of curly braces, with the lines of code\nto executed in case the logical test defined at `if` returns `false`.\n\nIn the example below, we are testing if the object `x` contains a number\nthat is greater than 10. Judging by the output printed to the console,\nwe know that this logical test returned `false`. Because the output\nin the console is compatible with the line of code present in the\n`else` branch of the if/else statement.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x = 5;\nif (x > 10) {\n    try stdout.print(\n        \"x > 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x <= 10!\\n\", .{}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nx <= 10!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Switch statements {#sec-switch}\n\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust.\nAs you would expect, to write a switch statement in Zig we use the `switch` keyword.\nWe provide the value that we want to \"switch over\" inside a\npair of parentheses. Then, we list the possible combinations (or \"branches\")\ninside a pair of curly braces.\n\nLet's take a look at the code example below. You can see that\nI'm creating an enum type called `Role`. We talk more about enums in @sec-enum.\nBut in summary, this `Role` type is listing different types of roles in a fictitious\ncompany, like `SE` for Software Engineer, `DE` for Data Engineer, `PM` for Product Manager,\netc.\n\nNotice that we are using the value from the `role` object in the\nswitch statement, to discover which exact area we need to store in the `area` variable object.\nAlso notice that we are using type inference inside the switch statement, with the dot character,\nas we are going to describe in @sec-type-inference.\nThis makes the `zig` compiler infer the correct data type of the values (`PM`, `SE`, etc.) for us.\n\nAlso notice that, we are grouping multiple values in the same branch of the switch statement.\nWe just separate each possible value with a comma. For example, if `role` contains either `DE` or `DA`,\nthe `area` variable would contain the value `\"Data & Analytics\"`, instead of `\"Platform\"` or `\"Sales\"`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO => {\n            area = \"Platform\";\n        },\n        .DE, .DA => {\n            area = \"Data & Analytics\";\n        },\n        .KS => {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nPlatform\n```\n\n\n:::\n:::\n\n\n\n\n\n#### Switch statements must exhaust all possibilities\n\nOne very important aspect about switch statements in Zig\nis that they must exhaust all existing possibilities.\nIn other words, all possible values that could be found inside the `role`\nobject must be explicitly handled in this switch statement.\n\nSince the `role` object has type `Role`, the only possible values to\nbe found inside this object are `PM`, `SE`, `DPE`, `PO`, `DE`, `DA` and `KS`.\nThere are no other possible values to be stored in this `role` object.\nThus, the switch statements must have a combination (branch) for each one of these values.\nThis is what \"exhaust all existing possibilities\" means. The switch statement covers\nevery possible case.\n\nTherefore, you cannot write a switch statement in Zig, and leave an edge case\nwith no explicit action to be taken.\nThis is a similar behaviour to switch statements in Rust, which also have to\nhandle all possible cases.\n\n\n\n#### The else branch\n\nTake a look at the `dump_hex_fallible()` function below as an example. This function\ncomes from the Zig Standard Library. More precisely, from the\n[`debug.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/debug.zig)[^debug-mod].\nThere are multiple lines in this function, but I omitted them to focus solely on the\nswitch statement found in this function. Notice that this switch statement has four\npossible cases (i.e. four explicit branches). Also, notice that we used an `else` branch\nin this case.\n\nAn `else` branch in a switch statement works as the \"default branch\".\nWhenever you have multiple cases in your switch statement where\nyou want to apply the exact same action, you can use an `else` branch to do that.\n\n[^debug-mod]: <https://github.com/ziglang/zig/blob/master/lib/std/debug.zig>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' => try writer.writeAll(\"␊\"),\n        '\\r' => try writer.writeAll(\"␍\"),\n        '\\t' => try writer.writeAll(\"␉\"),\n        else => try writer.writeByte('.'),\n    }\n}\n```\n:::\n\n\n\n\nMany programmers would also use an `else` branch to handle a \"not supported\" case.\nThat is, a case that cannot be properly handled by your code, or, just a case that\nshould not be \"fixed\". Therefore, you can use an `else` branch to panic (or raise an error)\nin your program to stop the current execution.\n\nTake the code example below. We can see that, we are handling the cases\nfor the `level` object being either 1, 2, or 3. All other possible cases are not supported by default,\nand, as consequence, we raise a runtime error in such cases through the `@panic()` built-in function.\n\nAlso notice that, we are assigning the result of the switch statement to a new object called `category`.\nThis is another thing that you can do with switch statements in Zig. If a branch\noutputs a value as result, you can store the result value of the switch statement into\na new object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 => \"beginner\",\n    3 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n:::\n\n\n\n\n```\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n```\n\n\n\n#### Using ranges in switch\n\nFurthermore, you can also use ranges of values in switch statements.\nThat is, you can create a branch in your switch statement that is used\nwhenever the input value is within the specified range. These \"range expressions\"\nare created with the operator `...`. It is important\nto emphasize that the ranges created by this operator are\ninclusive on both ends.\n\nFor example, I could easily change the previous code example to support all\nlevels between 0 and 100. Like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 => \"beginner\",\n    26...75 => \"intermediary\",\n    76...100 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nbeginner\n```\n\n\n:::\n:::\n\n\n\n\nThis is neat, and it works with character ranges too. That is, I could\nsimply write `'a'...'z'`, to match any character value that is a\nlowercase letter, and it would work fine.\n\n\n#### Labeled switch statements\n\nIn @sec-blocks we have talked about labeling blocks, and also, about using these labels\nto return a value from the block. Well, from version 0.14.0 and onwards of the `zig` compiler,\nyou can also apply labels over switch statements, which makes it possible to almost implement a\n\"C `goto`\" like pattern.\n\nFor example, if you give the label `xsw` to a switch statement, you can use this\nlabel in conjunction with the `continue` keyword to go back to the beginning of the switch\nstatement. In the example below, the execution goes back to the beginning of the\nswitch statement two times, before ending at the `3` branch.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nxsw: switch (@as(u8, 1)) {\n    1 => {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 => continue :xsw 3,\n    3 => return,\n    4 => {},\n    else => {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n```\n:::\n\n\n\n\n\n### The `defer` keyword {#sec-defer}\n\nWith the `defer` keyword you can register an expression to be executed when you exit the current scope.\nTherefore, this keyword has a similar functionality as the `on.exit()` function from R.\nTake the `foo()` function below as an example. When we execute this `foo()` function, the expression\nthat prints the message \"Exiting function ...\" is getting executed only when the function exits\nits scope.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nAdding some numbers ...\nMultiplying ...\nExiting function ...\n```\n\nTherefore, we can use `defer` to declare an expression that is going to be executed\nwhen your code exits the current scope. Some programmers like to interpret the phrase \"exit of the current scope\"\nas \"the end of the current scope\". But this interpretation might not be entirely correct, depending\non what you consider as \"the end of the current scope\".\n\nI mean, what do you consider as **the end** of the current scope? Is it the closing curly bracket (`}`) of the scope?\nIs it when the last expression in the function get's executed? Is it when the function returns to the previous scope?\nEtc. For example, it would not be correct to interpret the \"exit of the current scope\" as the closing\ncurly bracket of the scope. Because the function might exit from an earlier position than this\nclosing curly bracket (e.g. an error value was generated at a previous line inside the function;\nthe function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\n\nNow, if you remember of what we have discussed in @sec-blocks, there are multiple structures in the language\nthat create their own separate scopes. For/while loops, if/else statements,\nfunctions, normal blocks, etc. This also affects the interpretation of `defer`.\nFor example, if you use `defer` inside a for loop, then, the given expression\nwill be executed everytime this specific for loop exits its own scope.\n\nBefore we continue, is worth emphasizing that the `defer` keyword is an \"unconditional defer\".\nWhich means that the given expression will be executed no matter how the code exits\nthe current scope. For example, your code might exit the current scope because of an error value\nbeing generated, or, because of a return statement, or, a break statement, etc.\n\n\n\n### The `errdefer` keyword {#sec-errdefer1}\n\nOn the previous section, we have discussed the `defer` keyword, which you can use to\nregister an expression to be executed at the exit of the current scope.\nBut this keyword has a brother, which is the `errdefer` keyword. While `defer`\nis an \"unconditional defer\", the `errdefer` keyword is a \"conditional defer\".\nWhich means that the given expression is executed only when you exit the current\nscope on a very specific circumstance.\n\nIn more details, the expression given to `errdefer` is executed only when an error occurs in the current scope.\nTherefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope\nin a normal situation, without errors, the expression given to `errdefer` is not executed.\n\nThis makes the `errdefer` keyword one of the many tools available in Zig for error handling.\nIn this section, we are more concerned with the control flow aspects around `errdefer`.\nBut we are going to discuss `errdefer` later as a error handling tool in @sec-errdefer2.\n\nThe code example below demonstrates three things:\n\n- that `defer` is an \"unconditional defer\", because the given expression get's executed regardless of how the function `foo()` exits its own scope.\n- that `errdefer` is executed because the function `foo()` returned an error value.\n- that `defer` and `errdefer` expressions are executed in a LIFO (*last in, first out*) order.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\nWhen I say that \"defer expressions\" are executed in a LIFO order, what I want to say is that\nthe last `defer` or `errdefer` expressions in the code are the first ones to be executed.\nYou could also interpret this as: \"defer expressions\" are executed from bottom to top, or,\nfrom last to first.\n\nTherefore, if I change the order of the `defer` and `errdefer` expressions, you will notice that\nthe value of `i` that get's printed to the console changes to 1. This doesn't mean that the\n`defer` expression was not executed in this case. This actually means that the `defer` expression\nwas executed only after the `errdefer` expression. The code example below demonstrates this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\n\n\n### For loops\n\nA loop allows you to execute the same lines of code multiple times,\nthus, creating a \"repetition space\" in the execution flow of your program.\nLoops are particularly useful when we want to replicate the same function\n(or the same set of commands) over different inputs.\n\nThere are different types of loops available in Zig. But the most\nessential of them all is probably the *for loop*. A for loop is\nused to apply the same piece of code over the elements of a slice, or, an array.\n\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from\nother languages. You start with the `for` keyword, then, you\nlist the items that you want to iterate\nover inside a pair of parentheses. Then, inside of a pair of pipes (`|`)\nyou should declare an identifier that will serve as your iterator, or,\nthe \"repetition index of the loop\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (items) |value| {\n    // code to execute\n}\n```\n:::\n\n\n\n\nTherefore, instead of using a `(value in items)` syntax,\nin Zig, for loops use the syntax `(items) |value|`. In the example\nbelow, you can see that we are looping through the items\nof the array stored at the object `name`, and printing to the\nconsole the decimal representation of each character in this array.\n\nIf we wanted, we could also iterate through a slice (or a portion) of\nthe array, instead of iterating through the entire array stored in the `name` object.\nJust use a range selector to select the section you want. For example,\nI could provide the expression `name[0..3]` to the for loop, to iterate\njust through the first 3 elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n80 | 101 | 100 | 114 | 111 | \n```\n\n\n:::\n:::\n\n\n\n\nIn the above example we are using the value itself of each\nelement in the array as our iterator. But there are many situations where\nwe need to use an index instead of the actual values of the items.\n\nYou can do that by providing a second set of items to iterate over.\nMore precisely, you provide the range selector `0..` to the for loop. So,\nyes, you can use two different iterators at the same time in a for\nloop in Zig.\n\nBut remember from @sec-assignments that, every object\nyou create in Zig must be used in some way. So if you declare two iterators\nin your for loop, you must use both iterators inside the for loop body.\nBut if you want to use just the index iterator, and not use the \"value iterator\",\nthen, you can discard the value iterator by maching the\nvalue items to the underscore character, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n:::\n\n\n\n\n```\n0 | 1 | 2 | 3 | 4 |\n```\n\n\n### While loops\n\nA while loop is created from the `while` keyword. A `for` loop\niterates through the items of an array, but a `while` loop\nwill loop continuously, and infinitely, until a logical test\n(specified by you) becomes false.\n\nYou start with the `while` keyword, then, you define a logical\nexpression inside a pair of parentheses, and the body of the\nloop is provided inside a pair of curly braces, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\nYou can also specify the increment expression to be used at the beginning of a while loop.\nTo do that, we write the increment expression inside a pair of parentheses after a colon character (`:`).\nThe code example below demonstrates this other pattern.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\n### Using `break` and `continue`\n\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using\nthe keywords `break` and `continue`, respectively. The `while` loop presented in the next code example is,\nat first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to `true`.\nBut what makes this `while` loop stop when the `i` object reaches the count\n10? It is the `break` keyword!\n\nInside the while loop, we have an if statement that is constantly checking if the `i` variable\nis equal to 10. Since we are incrementing the value of `i` at each iteration of the\nwhile loop, this `i` object will eventually be equal to 10, and when it is, the if statement\nwill execute the `break` expression, and, as a result, the execution of the while loop is stopped.\n\nNotice the use of the `expect()` function from the Zig Standard Library after the while loop.\nThis `expect()` function is an \"assert\" type of function.\nThis function checks if the logical test provided is equal to true. If so, the function do nothing.\nOtherwise (i.e. the logical test is equal to false), the function raises an assertion error.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nEverything worked!\n```\n\n\n:::\n:::\n\n\n\n\nSince this code example was executed successfully by the `zig` compiler,\nwithout raising any errors, we known that, after the execution of the while loop,\nthe `i` object is equal to 10. Because if it wasn't equal to 10, an error would have\nbeen raised by `expect()`.\n\nNow, in the next example, we have a use case for\nthe `continue` keyword. The if statement is constantly\nchecking if the current index is a multiple of 2. If\nit is, we jump to the next iteration of the loop.\nOtherwise, the loop just prints the current index to the console.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 3 | 5 | \n```\n\n\n:::\n:::\n\n\n\n\n\n\n## Function parameters are immutable {#sec-fun-pars}\n\nWe have already discussed a lot of the syntax behind function declarations in @sec-root-file and @sec-main-file.\nBut I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig.\nIn summary, function parameters are immutable in Zig.\n\nTake the code example below, where we declare a simple function that just tries to add\nsome amount to the input integer, and returns the result back. If you look closely\nat the body of this `add2()` function, you will notice that we try\nto save the result back into the `x` function argument.\n\nIn other words, this function not only uses the value that it received through the function argument\n`x`, but it also tries to change the value of this function argument, by assigning the addition result\ninto `x`. However, function arguments in Zig are immutable. You cannot change their values, or, you\ncannot assign values to them inside the body's function.\n\nThis is the reason why, the code example below does not compile successfully. If you try to compile\nthis code example, you will get a compile error message about \"trying to change the value of a\nimmutable (i.e. constant) object\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n\n\n```\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n```\n\n\n### A free optimization\n\nIf a function argument receives as input an object whose data type is\nany of the primitive types that we have listed in @sec-primitive-data-types,\nthis object is always passed by value to the function. In other words, this object\nis copied into the function stack frame.\n\nHowever, if the input object have a more complex data type, for example, it might\nbe a struct instance, or an array, or an union value, etc., in cases like that, the `zig` compiler\nwill take the liberty of deciding for you which strategy is best. Thus, the `zig` compiler will\npass your object to the function either by value, or by reference. The compiler will always\nchoose the strategy that is faster for you.\nThis optimization that you get for free is possible only because function arguments are\nimmutable in Zig.\n\n\n### How to overcome this barrier\n\nThere are some situations where you might need to change the value of your function argument\ndirectly inside the function's body. This happens more often when we are passing\nC structs as inputs to Zig functions.\n\nIn a situation like this, you can overcome this barrier by using a pointer. In other words,\ninstead of passing a value as input to the argument, you can pass a \"pointer to value\" instead.\nYou can change the value that the pointer points to, by dereferencing it.\n\nTherefore, if we take our previous `add2()` example, we can change the value of the\nfunction argument `x` inside the function's body by marking the `x` argument as a\n\"pointer to a `u32` value\" (i.e. `*u32` data type), instead of a `u32` value.\nBy making it a pointer, we can finally alter the value of this function argument directly inside\nthe body of the `add2()` function. You can see that the code example below compiles successfully.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n```\n:::\n\n\n\n\n```\nResult: 6\n```\n\n\nEven in this code example above, the `x` argument is still immutable. Which means that the pointer itself is immutable.\nTherefore, you cannot change the memory address that it points to. However, you can dereference the pointer\nto access the value that it points to, and also, to change this value, if you need to.\n\n\n\n\n\n## Structs and OOP {#sec-structs-and-oop}\n\nZig is a language more closely related to C (which is a procedural language),\nthan it is to C++ or Java (which are object-oriented languages). Because of that, you do not\nhave advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or\nclass inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\n\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C.\nYou give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can\nalso register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object\nthat you create with this new type, will always have these methods available and associated with them.\n\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which\nis used to construct (or, to instantiate) every object of this particular class, and we also have\na destructor method (or a destructor function), which is the function responsible for destroying\nevery object of this class.\n\nIn Zig, we normally declare the constructor and the destructor methods\nof our structs, by declaring an `init()` and a `deinit()` methods inside the struct.\nThis is just a naming convention that you will find across the entire Zig Standard Library.\nSo, in Zig, the `init()` method of a struct is normally the constructor method of the class represented by this struct.\nWhile the `deinit()` method is the method used for destroying an existing instance of that struct.\n\nThe `init()` and `deinit()` methods are both used extensively in Zig code, and you will see both of\nthem being used when we talk about allocators in @sec-allocators.\nBut, as another example, let's build a simple `User` struct to represent a user of some sort of system.\n\nIf you look at the `User` struct below, you can see the `struct` keyword.\nNotice the data members of this struct: `id`, `name` and `email`. Every data member has its\ntype explicitly annotated, with the colon character (`:`) syntax that we described earlier in @sec-root-file.\nBut also notice that every line in the struct body that describes a data member, ends with a comma character (`,`).\nSo every time you declare a data member in your Zig code, always end the line with a comma character, instead\nof ending it with the traditional semicolon character (`;`).\n\nNext, we have registered an `init()` function as a method\nof this `User` struct. This `init()` method is the constructor method that we will use to instantiate\nevery new `User` object. That is why this `init()` function returns a new `User` object as result.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    pub fn init(id: u64,\n                name: []const u8,\n                email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    pub fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\npedro\n```\n\n\n:::\n:::\n\n\n\n\nThe `pub` keyword plays an important role in struct declarations, and OOP in Zig.\nEvery method that you declare in your struct that is marked with the keyword `pub`,\nbecomes a public method of this particular struct.\n\nSo every method that you create inside your struct, is, at first, a private method\nof that struct. Meaning that, this method can only be called from within this\nstruct. But, if you mark this method as public, with the keyword `pub`, then,\nyou can call the method directly from an instance of the `User` struct.\n\nIn other words, the functions marked by the keyword `pub`\nare members of the public API of that struct.\nFor example, if I did not mark the `print_name()` method as public,\nthen, I could not execute the line `u.print_name()`. Because I would\nnot be authorized to call this method directly in my code.\n\n\n\n### Anonymous struct literals {#sec-anonymous-struct-literals}\n\nYou can declare a struct object as a literal value. When we do that, we normally specify the\ndata type of this struct literal by writing its data type just before the opening curly brace.\nFor example, I could write a struct literal value of the type `User` that we have defined\nin the previous section like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n```\n:::\n\n\n\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a\nstruct literal, but not specify explicitly the type of this particular struct.\nAn anonymous struct is written by using the syntax `.{}`. So, we essentially\nreplaced the explicit type of the struct literal with a dot character (`.`).\n\nAs we described in @sec-type-inference, when you put a dot before a struct literal,\nthe type of this struct literal is automatically inferred by the `zig` compiler.\nIn essence, the `zig` compiler will look for some hint of what is the type of that struct.\nThis hint can be the type annotation of a function argument,\nor the return type annotation of the function that you are using, or the type annotation\nof an existing object.\nIf the compiler does find such type annotation, it will use this\ntype in your literal struct.\n\nAnonymous structs are very commonly used as inputs to function arguments in Zig.\nOne example that you have seen already constantly, is the `print()`\nfunction from the `stdout` object.\nThis function takes two arguments.\nThe first argument, is a template string, which should\ncontain string format specifiers in it, which tells how the values provided\nin the second argument should be printed into the message.\n\nWhile the second argument is a struct literal that lists the values\nto be printed into the template message specified in the first argument.\nYou normally want to use an anonymous struct literal here, so that the\n`zig` compiler do the job of specifying the type of this particular\nanonymous struct for you.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello, world!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Struct declarations must be constant\n\nTypes in Zig must be `const` or `comptime` (we are going to talk more about comptime in @sec-comptime).\nWhat this means is that you cannot create a new data type, and mark it as variable with the `var` keyword.\nSo struct declarations are always constant. You cannot declare a new struct type using the `var` keyword.\nIt must be `const`.\n\nIn the `Vec3` example below, this declaration is allowed because I'm using the `const` keyword\nto declare this new data type.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n```\n:::\n\n\n\n\n\n### The `self` method argument {#sec-self-arg}\n\nIn every language that have OOP, when we declare a method of some class or struct, we\nusually declare this method as a function that has a `self` argument.\nThis `self` argument is the reference to the object itself from which the method\nis being called from.\n\nIt is not mandatory to use this `self` argument. But why would you not use this `self` argument?\nThere is no reason to not use it. Because the only way to get access to the data stored in the\ndata members of your struct is to access them through this `self` argument.\nIf you don't need to use the data in the data members of your struct inside your method, you very likely don't need\na method. You can just declare this logic as a simple function, outside of your\nstruct declaration.\n\n\nTake the `Vec3` struct below. Inside this `Vec3` struct we declared a method named `distance()`.\nThis method calculates the distance between two `Vec3` objects, by following the distance\nformula in euclidean space. Notice that this `distance()` method takes two `Vec3` objects\nas input, `self` and `other`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n```\n:::\n\n\n\n\n\nThe `self` argument corresponds to the `Vec3` object from which this `distance()` method\nis being called from. While the `other` is a separate `Vec3` object that is given as input\nto this method. In the example below, the `self` argument corresponds to the object\n`v1`, because the `distance()` method is being called from the `v1` object,\nwhile the `other` argument corresponds to the object `v2`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n```\n:::\n\n\n\n\n```\nDistance: 3.3970575502926055\n```\n\n\n\n### About the struct state\n\nSometimes you don't need to care about the state of your struct object. Sometimes, you just need\nto instantiate and use the objects, without altering their state. You can notice that when you have methods\ninside your struct declaration that might use the values that are present in the data members, but they\ndo not alter the values in these data members of the struct in anyway.\n\nThe `Vec3` struct that was presented in @sec-self-arg is an example of that.\nThis struct have a single method named `distance()`, and this method does use the values\npresent in all three data members of the struct (`x`, `y` and `z`). But at the same time,\nthis method does not change the values of these data members at any point.\n\nAs a result of that, when we create `Vec3` objects we usually create them as\nconstant objects, like the `v1` and `v2` objects presented in @sec-self-arg.\nWe can create them as variable objects with the `var` keyword,\nif we want to. But because the methods of this `Vec3` struct do not change\nthe state of the objects in any point, it's unnecessary to mark them\nas variable objects.\n\nBut why? Why am I talking about this here? It's because the `self` argument\nin the methods is affected depending on whether the\nmethods present in a struct change or don't change the state of the object itself.\nMore specifically, when you have a method in a struct that changes the state\nof the object (i.e. change the value of a data member), the `self` argument\nin this method must be annotated in a different manner.\n\nAs I described in @sec-self-arg, the `self` argument in methods of\na struct is the argument that receives as input the object from which the method\nwas called from. We usually annotate this argument in the methods by writing `self`,\nfollowed by the colon character (`:`), and the data type of the struct to which\nthe method belongs to (e.g. `User`, `Vec3`, etc.).\n\nIf we take the `Vec3` struct that we defined in the previous section as an example,\nwe can see in the `distance()` method that this `self` argument is annotated as\n`self: Vec3`. Because the state of the `Vec3` object is never altered by this\nmethod.\n\nBut what if we do have a method that alters the state of the object, by altering the\nvalues of its data members, how should we annotate `self` in this instance? The answer is:\n\"we should annotate `self` as a pointer of `x`, instead of just `x`\".\nIn other words, you should annotate `self` as `self: *x`, instead of annotating it\nas `self: x`.\n\nIf we create a new method inside the `Vec3` object that, for example, expands the\nvector by multiplying its coordinates by a factor of two, then, we need to follow\nthis rule specified in the previous paragraph. The code example below demonstrates\nthis idea:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n```\n:::\n\n\n\n\nNotice in the code example above that we have added a new method\nto our `Vec3` struct named `twice()`. This method doubles the\ncoordinate values of our vector object. In the\ncase of the `twice()` method, we annotated the `self` argument as `*Vec3`,\nindicating that this argument receives a pointer (or a reference, if you prefer to call it this way)\nto a `Vec3` object as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n```\n:::\n\n\n\n\n```\nDoubled: 8.4\n```\n\n\n\nNow, if you change the `self` argument in this `twice()` method to `self: Vec3`, like in the\n`distance()` method, you will get the compiler error exposed below as result. Notice that this\nerror message is showing a line from the `twice()` method body,\nindicating that you cannot alter the value of the `x` data member.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n```\n:::\n\n\n\n\n```\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\n```\n\nThis error message indicates that the `x` data member belongs to a constant object,\nand, because of that, it cannot be changed. Ultimately, this error message\nis telling us that the `self` argument is constant.\n\nIf you take some time, and think hard about this error message, you will understand it.\nYou already have the tools to understand why we are getting this error message.\nWe have talked about it already in @sec-fun-pars.\nSo remember, every function argument is immutable in Zig, and `self`\nis no exception to this rule.\n\nIn this example, we marked the `v3` object as a variable object.\nBut this does not matter. Because it is not about the input object, it is about\nthe function argument.\n\nThe problem begins when we try to alter the value of `self` directly, which is a function argument,\nand, every function argument is immutable by default. You may ask yourself how can we overcome\nthis barrier, and once again, the solution was also discussed in @sec-fun-pars.\nWe overcome this barrier, by explicitly marking the `self` argument as a pointer.\n\n\n::: {.callout-note}\nIf a method of your `x` struct alters the state of the object, by\nchanging the value of any data member, then, remember to use `self: *x`,\ninstead of `self: x` in the function signature of this method.\n:::\n\n\nYou could also interpret the content discussed in this section as:\n\"if you need to alter the state of your `x` struct object in one of its methods,\nyou must explicitly pass the `x` struct object by reference to the `self` argument of this method\".\n\n\n\n## Type inference {#sec-type-inference}\n\nZig is a strongly typed language. But, there are some situations\nwhere you don't have to explicitly write the type of every single object in your source code,\nas you would expect from a traditional strongly typed language, such as C and C++.\n\nIn some situations, the `zig` compiler can use type inference to solve the data types for you, easing some of\nthe burden that you carry as a developer.\nThe most common way this happens is through function arguments that receive struct objects\nas input.\n\nIn general, type inference in Zig is done by using the dot character (`.`).\nEverytime you see a dot character written before a struct literal, or before an enum value, or something like that,\nyou know that this dot character is playing a special party in this place. More specifically, it is\ntelling the `zig` compiler something along the lines of: \"Hey! Can you infer the type of this\nvalue for me? Please!\". In other words, this dot character is playing a similar role as the `auto` keyword in C++.\n\nI gave you some examples of this in @sec-anonymous-struct-literals, where we used anonymous struct literals.\nAnonymous struct literals are, struct literals that use type inference to\ninfer the exact type of this particular struct literal.\nThis type inference is done by looking for some minimal hint of the correct data type to be used.\nYou could say that the `zig` compiler looks for any neighbouring type annotation that might tell it\nwhat the correct type would be.\n\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in @sec-switch).\nI also gave some other examples of type inference in @sec-switch, where we were inferring the data types of enum values listed inside\nof switch statements (e.g. `.DE`).\nBut as another example, take a look at this `fence()` function reproduced below,\nwhich comes from the [`atomic.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig)[^fence-fn]\nof the Zig Standard Library.\n\n[^fence-fn]: <https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig>.\n\nThere are a lot of things in this function that we haven't talked about yet, such as:\nwhat `comptime` means? `inline`? `extern`?\nLet's just ignore all of these things, and focus solely on the switch statement\nthat is inside this function.\n\nWe can see that this switch statement uses the `order` object as input. This `order`\nobject is one of the inputs of this `fence()` function, and we can see in the type annotation,\nthat this object is of type `AtomicOrder`. We can also see a bunch of values inside the\nswitch statements that begin with a dot character, such as `.release` and `.acquire`.\n\nBecause these weird values contain a dot character before them, we are asking the `zig`\ncompiler to infer the types of these values inside the switch statement. Then, the `zig`\ncompiler is looking into the current context where these values are being used, and it is\ntrying to infer the types of these values.\n\nSince they are being used inside a switch statement, the `zig` compiler looks into the type\nof the input object given to the switch statement, which is the `order` object in this case.\nBecause this object have type `AtomicOrder`, the `zig` compiler infers that these values\nare data members from this type `AtomicOrder`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic => @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire => tsan.__tsan_acquire(addr),\n            .release => tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst => {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n```\n:::\n\n\n\n\nThis is how basic type inference is done in Zig. If we didn't use the dot character before\nthe values inside this switch statement, then, we would be forced to explicitly write\nthe data types of these values. For example, instead of writing `.release` we would have to\nwrite `AtomicOrder.release`. We would have to do this for every single value\nin this switch statement, and this is a lot of work. That is why type inference\nis commonly used on switch statements in Zig.\n\n\n\n## Type casting {#sec-type-cast}\n\nIn this section, I want to discuss type casting (or, type conversion) with you.\nWe use type casting when we have an object of type \"x\", and we want to convert\nit into an object of type \"y\", i.e. we want to change the data type of the object.\n\nMost languages have a formal way to perform type casting. In Rust for example, we normally\nuse the keyword `as`, and in C, we normally use the type casting syntax, e.g. `(int) x`.\nIn Zig, we use the `@as()` built-in function to cast an object of type \"x\", into\nan object of type \"y\".\n\nThis `@as()` function is the preferred way to perform type conversion (or type casting)\nin Zig. Because it is explicit, and, it also performs the casting only if it\nis unambiguous and safe. To use this function, you just provide the target data type\nin the first argument, and, the object that you want cast as the second argument.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filecdc41797a754.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\nThis is the general way to perform type casting in Zig. But remember, `@as()` works only when casting\nis unambiguous and safe, and there are situations where these assumptions do not hold. For example,\nwhen casting an integer value into a float value, or vice-versa, it is not clear to the compiler\nhow to perform this conversion safely.\n\nTherefore, we need to use specialized \"casting functions\" in such situations.\nFor example, if you want to cast an integer value into a float value, then, you\nshould use the `@floatFromInt()` function. In the inverse scenario, you should use\nthe `@intFromFloat()` function.\n\nIn these functions, you just provide the object that you want to\ncast as input. Then, the target data type of the \"type casting operation\" is determined by\nthe type annotation of the object where you are saving the results.\nIn the example below, we are casting the object `x` into a value of type `f32`,\nbecause the object `y`, which is where we are saving the results, is annotated\nas an object of type `f32`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filecdc428638149.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\nAnother built-in function that is very useful when performing type casting operations is `@ptrCast()`.\nIn essence, we use the `@as()` built-in function when we want to explicit convert (or cast) a Zig value/object\nfrom a type \"x\" to a type \"y\", etc. However, pointers (we are going to discuss pointers\nin more depth in @sec-pointer) are a special type of object in Zig,\ni.e. they are treated differently from \"normal objects\".\n\nEverytime a pointer is involved in some \"type casting operation\" in Zig, the `@ptrCast()` function is used.\nThis function works similarly to `@floatFromInt()`.\nYou just provide the pointer object that you want to cast as input to this function, and the\ntarget data type is, once again, determined by the type annotation of the object where the results are being\nstored.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filecdc46f71cc03.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## Modules\n\nWe already talked about what modules are, and also, how to import other modules into\nyour current module via *import statements*. Every Zig module (i.e. a `.zig` file) that you write in your project\nis internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the\nZig Standard Library into our current module.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n```\n:::\n\n\n\n\nWhen we want to access the functions and objects from the standard library, we\nare basically accessing the data members of the struct stored in the `std`\nobject. That is why we use the same syntax that we use in normal structs, with the dot operator (`.`)\nto access the data members and methods of the struct.\n\nWhen this \"import statement\" get's executed, the result of this expression is a struct\nobject that contains the Zig Standard Library modules, global variables, functions, etc.\nAnd this struct object get's saved (or stored) inside the constant object named `std`.\n\n\nTake the [`thread_pool.zig` module from the project `zap`](https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig)[^thread]\nas an example. This module is written as if it was\na big struct. That is why we have a top-level and public `init()` method\nwritten in this module. The idea is that all top-level functions written in this\nmodule are methods from the struct, and all top-level objects and struct declarations\nare data members of this struct. The module is the struct itself.\n\n[^thread]: <https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig>\n\n\nSo you would import and use this module by doing something like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst ThreadPool = @import(\"thread_pool.zig\");\nconst num_cpus = std.Thread.getCpuCount()\n    catch @panic(\"failed to get cpu core count\");\nconst num_threads = std.math.cast(u16, num_cpus)\n    catch std.math.maxInt(u16);\nconst pool = ThreadPool.init(\n    .{ .max_threads = num_threads }\n);\n```\n:::\n",
     "supporting": [
       "03-structs_files"
     ],
diff --git a/docs/Chapters/01-zig-weird.html b/docs/Chapters/01-zig-weird.html
index 2f44cd2d..f7360c5b 100644
--- a/docs/Chapters/01-zig-weird.html
+++ b/docs/Chapters/01-zig-weird.html
@@ -400,7 +400,7 @@ <h3 data-number="1.2.1" class="anchored" data-anchor-id="sec-project-files"><spa
     └── root.zig
 
 1 directory, 4 files</code></pre>
-<p>The <code>ìnit</code> command also creates two additional files in our working directory: <code>build.zig</code> and <code>build.zig.zon</code>. The first file (<code>build.zig</code>) represents a build script written in Zig. This script is executed when you call the <code>build</code> command from the <code>zig</code> compiler. In other words, this file contain Zig code that executes the necessary steps to build the entire project.</p>
+<p>The <code>init</code> command also creates two additional files in our working directory: <code>build.zig</code> and <code>build.zig.zon</code>. The first file (<code>build.zig</code>) represents a build script written in Zig. This script is executed when you call the <code>build</code> command from the <code>zig</code> compiler. In other words, this file contain Zig code that executes the necessary steps to build the entire project.</p>
 <p>Low-level languages normally use a compiler to build your source code into binary executables or binary libraries. Nevertheless, this process of compiling your source code and building binary executables or binary libraries from it, became a real challenge in the programming world, once the projects became bigger and bigger. As a result, programmers created “build systems”, which are a second set of tools designed to make this process of compiling and building complex projects, easier.</p>
 <p>Examples of build systems are CMake, GNU Make, GNU Autoconf and Ninja, which are used to build complex C and C++ projects. With these systems, you can write scripts, which are called “build scripts”. They simply are scripts that describes the necessary steps to compile/build your project.</p>
 <p>However, these are separate tools, that do not belong to C/C++ compilers, like <code>gcc</code> or <code>clang</code>. As a result, in C/C++ projects, you have not only to install and manage your C/C++ compilers, but you also have to install and manage these build systems separately.</p>
@@ -567,7 +567,7 @@ <h2 data-number="1.4" class="anchored" data-anchor-id="sec-assignments"><span cl
 <p>On the other side, if you use <code>var</code>, then, you are creating a variable (or mutable) object. You can change the value of this object as many times you want. Using the keyword <code>var</code> in Zig is similar to using the keywords <code>let mut</code> in Rust.</p>
 <section id="constant-objects-vs-variable-objects" class="level3" data-number="1.4.1">
 <h3 data-number="1.4.1" class="anchored" data-anchor-id="constant-objects-vs-variable-objects"><span class="header-section-number">1.4.1</span> Constant objects vs variable objects</h3>
-<p>In the code example below, we are creating a new constant object called <code>age</code>. This object stores a number representing the age of someone. However, this code example does not compiles successfully. Because on the next line of code, we are trying to change the value of the object <code>age</code> to 25.</p>
+<p>In the code example below, we are creating a new constant object called <code>age</code>. This object stores a number representing the age of someone. However, this code example does not compile successfully. Because on the next line of code, we are trying to change the value of the object <code>age</code> to 25.</p>
 <p>The <code>zig</code> compiler detects that we are trying to change the value of an object/identifier that is constant, and because of that, the compiler will raise a compilation error, warning us about the mistake.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb21"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb21-1"><a href="#cb21-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> age = <span class="dv">24</span>;</span>
@@ -854,7 +854,7 @@ <h2 data-number="1.8" class="anchored" data-anchor-id="sec-zig-strings"><span cl
 <section id="strings-in-c" class="level3" data-number="1.8.1">
 <h3 data-number="1.8.1" class="anchored" data-anchor-id="strings-in-c"><span class="header-section-number">1.8.1</span> Strings in C</h3>
 <p>At first glance, a string literal value in Zig looks very similar to how C treats strings as well. In more details, string values in C are treated internally as an array of arbitrary bytes, and this array is also null-terminated.</p>
-<p>But one key difference between a Zig string literal and a C string, is that Zig also stores the length of the string inside the object itself. In the case of a string literal value, this length is stored in the data type of the value (i.e.&nbsp;the <code>n</code> variable in <code>[n:0]u8</code>). While, in a string object, the length is stored in the <code>len</code> attribute of the slice that represents the string object. This small detail makes your code safer, because is much easier for the Zig compiler to check if you are trying to access an element that is “out of bounds”, i.e.&nbsp;if your trying to access memory that does not belong to you.</p>
+<p>But one key difference between a Zig string literal and a C string, is that Zig also stores the length of the string inside the object itself. In the case of a string literal value, this length is stored in the data type of the value (i.e.&nbsp;the <code>n</code> variable in <code>[n:0]u8</code>). While, in a string object, the length is stored in the <code>len</code> attribute of the slice that represents the string object. This small detail makes your code safer, because it is much easier for the Zig compiler to check if you are trying to access an element that is “out of bounds”, i.e.&nbsp;if your trying to access memory that does not belong to you.</p>
 <p>To achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless. So getting this kind of safety is not automatic and much harder to do in C. For example, if you want to track the length of your string throughout your program in C, then, you first need to loop through the array of bytes that represents this string, and find the null element (<code>'\0'</code>) position to discover where exactly the array ends, or, in other words, to find how much elements the array of bytes contain.</p>
 <p>To do that, you would need something like this in C. In this example, the C string stored in the object <code>array</code> is 25 bytes long:</p>
 <div class="cell">
@@ -1033,7 +1033,7 @@ <h2 data-number="1.9" class="anchored" data-anchor-id="safety-in-zig"><span clas
 <p>As Richard Feldman explains on his <a href="https://www.youtube.com/watch?v=jIZpKpLCOiU&amp;ab_channel=GOTOConferences">most recent GOTO conference talk</a><a href="#fn24" class="footnote-ref" id="fnref24" role="doc-noteref"><sup>24</sup></a> , we haven’t figured it out yet a way to achieve <strong>true safety in technology</strong>. In other words, we haven’t found a way to build software that won’t be exploited with 100% certainty. We can greatly reduce the risks of our software being exploited, by ensuring memory safety for example. But this is not enough to achieve “true safety” territory.</p>
 <p>Because even if you write your program in a “safe language”, hackers can still exploit failures in the operating system where your program is running (e.g.&nbsp;maybe the system where your code is running has a “backdoor exploit” that can still affect your code in unexpected ways), or also, they can exploit the features from the architecture of your computer. A recently found exploit that involves memory invalidation through a feature of “memory tags” present in ARM chips is an example of that <span class="citation" data-cites="exploit1">(<a href="../references.html#ref-exploit1" role="doc-biblioref">Kim et al. 2024</a>)</span>.</p>
 <p>The question is: what have Zig and other languages been doing to mitigate this problem? If we take Rust as an example, Rust is, for the most part<a href="#fn25" class="footnote-ref" id="fnref25" role="doc-noteref"><sup>25</sup></a>, a memory safe language by enforcing specific rules to the developer. In other words, the key feature of Rust, the <em>borrow checker</em>, forces you to follow a specific logic when you are writing your Rust code, and the Rust compiler will always complain everytime you try to go out of this pattern.</p>
-<p>In contrast, the Zig language is not a memory safe language by default. There are some memory safety features that you get for free in Zig, especially in arrays and pointer objects. But there are other tools offered by the language, that are not used by default. In other words, the <code>zig</code> compiler does not obligates you to use such tools.</p>
+<p>In contrast, the Zig language is not a memory safe language by default. There are some memory safety features that you get for free in Zig, especially in arrays and pointer objects. But there are other tools offered by the language, that are not used by default. In other words, the <code>zig</code> compiler does not obligate you to use such tools.</p>
 <p>The tools listed below are related to memory safety. That is, they help you to achieve memory safety in your Zig code:</p>
 <ul>
 <li><code>defer</code> allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, “use after free”, and also “double-free” problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.</li>
diff --git a/docs/Chapters/03-structs.html b/docs/Chapters/03-structs.html
index 19bc03c5..bcf6dd8f 100644
--- a/docs/Chapters/03-structs.html
+++ b/docs/Chapters/03-structs.html
@@ -392,8 +392,8 @@ <h3 data-number="2.1.2" class="anchored" data-anchor-id="sec-switch"><span class
 </div>
 <section id="switch-statements-must-exhaust-all-possibilities" class="level4" data-number="2.1.2.1">
 <h4 data-number="2.1.2.1" class="anchored" data-anchor-id="switch-statements-must-exhaust-all-possibilities"><span class="header-section-number">2.1.2.1</span> Switch statements must exhaust all possibilities</h4>
-<p>One very important aspect about switch statements in Zig is that they must exhaust all existing possibilities. In other words, all possible values that could be found inside the <code>order</code> object must be explicitly handled in this switch statement.</p>
-<p>Since the <code>role</code> object have type <code>Role</code>, the only possible values to be found inside this object are <code>PM</code>, <code>SE</code>, <code>DPE</code>, <code>PO</code>, <code>DE</code>, <code>DA</code> and <code>KS</code>. There are no other possible values to be stored in this <code>role</code> object. Thus, the switch statements must have a combination (branch) for each one of these values. This is what “exhaust all existing possibilities” means. The switch statement covers every possible case.</p>
+<p>One very important aspect about switch statements in Zig is that they must exhaust all existing possibilities. In other words, all possible values that could be found inside the <code>role</code> object must be explicitly handled in this switch statement.</p>
+<p>Since the <code>role</code> object has type <code>Role</code>, the only possible values to be found inside this object are <code>PM</code>, <code>SE</code>, <code>DPE</code>, <code>PO</code>, <code>DE</code>, <code>DA</code> and <code>KS</code>. There are no other possible values to be stored in this <code>role</code> object. Thus, the switch statements must have a combination (branch) for each one of these values. This is what “exhaust all existing possibilities” means. The switch statement covers every possible case.</p>
 <p>Therefore, you cannot write a switch statement in Zig, and leave an edge case with no explicit action to be taken. This is a similar behaviour to switch statements in Rust, which also have to handle all possible cases.</p>
 </section>
 <section id="the-else-branch" class="level4" data-number="2.1.2.2">
@@ -927,8 +927,8 @@ <h2 data-number="2.5" class="anchored" data-anchor-id="sec-type-cast"><span clas
 <span id="cb49-6"><a href="#cb49-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(y) == <span class="dt">u32</span>);</span>
 <span id="cb49-7"><a href="#cb49-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file10b91234368fa.test_0...OKAll 1 tests passe
-  ed.</code></pre>
+<pre><code>1/1 filecdc41797a754.test_0...OKAll 1 tests passed
+  d.</code></pre>
 </div>
 </div>
 <p>This is the general way to perform type casting in Zig. But remember, <code>@as()</code> works only when casting is unambiguous and safe, and there are situations where these assumptions do not hold. For example, when casting an integer value into a float value, or vice-versa, it is not clear to the compiler how to perform this conversion safely.</p>
@@ -943,8 +943,8 @@ <h2 data-number="2.5" class="anchored" data-anchor-id="sec-type-cast"><span clas
 <span id="cb51-6"><a href="#cb51-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(y) == <span class="dt">f32</span>);</span>
 <span id="cb51-7"><a href="#cb51-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file10b9130ae9221.test_0...OKAll 1 tests passe
-  ed.</code></pre>
+<pre><code>1/1 filecdc428638149.test_0...OKAll 1 tests passed
+  d.</code></pre>
 </div>
 </div>
 <p>Another built-in function that is very useful when performing type casting operations is <code>@ptrCast()</code>. In essence, we use the <code>@as()</code> built-in function when we want to explicit convert (or cast) a Zig value/object from a type “x” to a type “y”, etc. However, pointers (we are going to discuss pointers in more depth in <a href="05-pointers.html" class="quarto-xref"><span>Chapter 6</span></a>) are a special type of object in Zig, i.e.&nbsp;they are treated differently from “normal objects”.</p>
@@ -960,8 +960,8 @@ <h2 data-number="2.5" class="anchored" data-anchor-id="sec-type-cast"><span clas
 <span id="cb53-8"><a href="#cb53-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(u32_ptr) == *<span class="kw">const</span> <span class="dt">u32</span>);</span>
 <span id="cb53-9"><a href="#cb53-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file10b914c434861.test_0...OKAll 1 tests passe
-  ed.</code></pre>
+<pre><code>1/1 filecdc46f71cc03.test_0...OKAll 1 tests passed
+  d.</code></pre>
 </div>
 </div>
 </section>
diff --git a/docs/search.json b/docs/search.json
index 82133e70..9d8728f7 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -124,7 +124,7 @@
     "href": "Chapters/01-zig-weird.html#hello-world-in-zig",
     "title": "1  Introducing Zig",
     "section": "1.2 Hello world in Zig",
-    "text": "1.2 Hello world in Zig\nWe begin our journey in Zig by creating a small “Hello World” program. To start a new Zig project in your computer, you simply call the init command from the zig compiler. Just create a new directory in your computer, then, init a new Zig project inside this directory, like this:\nmkdir hello_world\ncd hello_world\nzig init\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n\n1.2.1 Understanding the project files\nAfter you run the init command from the zig compiler, some new files are created inside of your current directory. First, a “source” (src) directory is created, containing two files, main.zig and root.zig. Each .zig file is a separate Zig module, which is simply a text file that contains some Zig code.\nBy convention, the main.zig module is where your main function lives. Thus, if you are building an executable program in Zig, you need to declare a main() function, which represents the entrypoint of your program, i.e. it is where the execution of your program begins.\nHowever, if you are building a library (instead of an executable program), then, the normal procedure is to delete this main.zig file and start with the root.zig module. By convention, the root.zig module is the root source file of your library.\ntree .\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\nThe ìnit command also creates two additional files in our working directory: build.zig and build.zig.zon. The first file (build.zig) represents a build script written in Zig. This script is executed when you call the build command from the zig compiler. In other words, this file contain Zig code that executes the necessary steps to build the entire project.\nLow-level languages normally use a compiler to build your source code into binary executables or binary libraries. Nevertheless, this process of compiling your source code and building binary executables or binary libraries from it, became a real challenge in the programming world, once the projects became bigger and bigger. As a result, programmers created “build systems”, which are a second set of tools designed to make this process of compiling and building complex projects, easier.\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja, which are used to build complex C and C++ projects. With these systems, you can write scripts, which are called “build scripts”. They simply are scripts that describes the necessary steps to compile/build your project.\nHowever, these are separate tools, that do not belong to C/C++ compilers, like gcc or clang. As a result, in C/C++ projects, you have not only to install and manage your C/C++ compilers, but you also have to install and manage these build systems separately.\nIn Zig, we don’t need to use a separate set of tools to build our projects, because a build system is embedded inside the language itself. Therefore, Zig contains a native build system in it, and we can use this build system to write small scripts in Zig, which describes the necessary steps to build/compile our Zig project1. So, everything you need to build a complex Zig project is the zig compiler, and nothing more.\nThe second generated file (build.zig.zon) is a JSON-like file, in which you can describe your project, and also, declare a set of dependencies of your project that you want to fetch from the internet. In other words, you can use this build.zig.zon file to include a list of external libraries in your project.\nOne possible way to include an external Zig library in your project, is to manually build and install the library in your system, and just link your source code with the library at the build step of your project.\nHowever, if this external Zig library is available on GitHub for example, and it has a valid build.zig.zon file in root folder of the project, which describes the project, you can easily include this library in your project by simply listing this external library in your build.zig.zon file.\nIn other words, this build.zig.zon file works similarly to the package.json file in Javascript projects, or the Pipfile file in Python projects, or the Cargo.toml file in Rust projects. You can read more about this specific file in a couple of articles on the internet23, and you can also see the expected schema for this build.zig.zon file in a documentation file inside the official repository of Zig4.\n\n\n1.2.2 The file root.zig\nLet’s take a look into the root.zig file. You might have noticed that every line of code with an expression ends with a semicolon (;). This follows the syntax of a C-family programming language5.\nAlso, notice the @import() call at the first line. We use this built-in function to import functionality from other Zig modules into our current module. This @import() function works similarly to the #include pre-processor in C or C++, or, to the import statement in Python or Javascript code. In this example, we are importing the std module, which gives you access to the Zig Standard Library.\nIn this root.zig file, we can also see how assignments (i.e. creating new objects) are made in Zig. You can create a new object in Zig by using the following syntax (const|var) name = value;. In the example below, we are creating two constant objects (std and testing). At Section 1.4 we talk more about objects in general.\n\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n\nFunctions in Zig are declared using the fn keyword. In this root.zig module, we are declaring a function called add(), which has two arguments named a and b. The function returns an integer of the type i32 as result.\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit the type of an object in your code, if this type can be inferred by the zig compiler (we talk more about that at Section 2.4). But there are other situations where you do need to be explicit. For example, you do have to explicitly specify the type of each function argument, and also, the return type of every function that you create in Zig.\nWe specify the type of an object or a function argument in Zig by using a colon character (:) followed by the type after the name of this object/function argument. With the expressions a: i32 and b: i32, we know that both a and b arguments have type i32, which is a signed 32 bit integer. In this part, the syntax in Zig is identical to the syntax in Rust, which also specifies types by using the colon character.\nLastly, we have the return type of the function at the end of the line, before we open the curly braces to start writing the function’s body. In the example above, this type is also a signed 32 bit integer (i32) value.\nNotice that we also have an export keyword before the function declaration. This keyword is similar to the extern keyword in C. It exposes the function to make it available in the library API. Therefore, if you are writing a library for other people to use, you have to expose the functions you write in the public API of this library by using this export keyword. If we removed the export keyword from the add() function declaration, then, this function would be no longer exposed in the library object built by the zig compiler.\n\n\n1.2.3 The main.zig file\nNow that we have learned a lot about Zig’s syntax from the root.zig file, let’s take a look at the main.zig file. A lot of the elements we saw in root.zig are also present in main.zig. But there are some other elements that we haven’t seen yet, so let’s dive in.\nFirst, look at the return type of the main() function in this file. We can see a small change. The return type of the function (void) is accompanied by an exclamation mark (!). This exclamation mark tells us that this main() function might return an error.\nIs worth noting that, a main() function in Zig is allowed to return nothing (void), or an unsigned 8-bit integer (u8) value6, or an error. In other words, you can write your main() function in Zig to return essentially nothing (void), or, if you prefer, you can also write a more C-like main() function, which returns an integer value that usually serves as a “status code” for the process.\nIn this example, the return type annotation of main() indicates that this function can either return nothing (void), or return an error. This exclamation mark in the return type annotation is an interesting and powerful feature of Zig. In summary, if you write a function and something inside the body of this function might return an error, then, you are forced to:\n\neither add the exclamation mark to the return type of the function and make it clear that this function might return an error.\nexplicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through a try catch pattern. Zig does have both try and catch keywords. But they work a little differently than what you’re probably used to in other languages.\nIf we look at the main() function below, you can see that we do have a try keyword on the 5th line. But we do not have a catch keyword in this code. In Zig, we use the try keyword to execute an expression that might return an error, which, in this example, is the stdout.print() expression.\nIn essence, the try keyword executes the expression stdout.print(). If this expression returns a valid value, then, the try keyword does absolutely nothing. It only passes the value forward. It is like if this try keyword was never there. However, if the expression does return an error, then, the try keyword will unwrap the error value, then, it returns this error from the function and also prints the current stack trace to stderr.\nThis might sound weird to you if you come from a high-level language. Because in high-level languages, such as Python, if an error occurs somewhere, this error is automatically returned and the execution of your program will automatically stop even if you don’t want to stop the execution. You are obligated to face the error.\n\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n\nAnother thing that you might have noticed in this code example, is that the main() function is marked with the pub keyword. It marks the main() function as a public function from this module. Every function in your Zig module is by default private to this Zig module and can only be called from within the module. Unless, you explicitly mark this function as a public function with the pub keyword.\nIf you think about it, this pub keyword in Zig does essentially the opposite of what the static keyword do in C/C++. By making a function “public” you allow other Zig modules to access and call this function. A calling Zig module imports another module by using the @import() built-in function, which makes all public functions from the imported module visible to the calling Zig module.\n\n\n1.2.4 Compiling your source code\nYou can compile your Zig modules into a binary executable by running the build-exe command from the zig compiler. You simply list all the Zig modules that you want to build after the build-exe command, separated by spaces. In the example below, we are compiling the module main.zig.\nzig build-exe src/main.zig\nSince we are building an executable, the zig compiler will look for a main() function declared in any of the files that you list after the build-exe command. If the compiler does not find a main() function declared somewhere, a compilation error will be raised, warning about this mistake.\nThe zig compiler also offers a build-lib and build-obj commands, which work the exact same way as the build-exe command. The only difference is that, they compile your Zig modules into a portale C ABI library, or, into object files, respectively.\nIn the case of the build-exe command, a binary executable file is created by the zig compiler in the root directory of your project. If we take a look now at the contents of our current directory, with a simple ls command, we can see the binary file called main that was created by the compiler.\nls\nbuild.zig  build.zig.zon  main  src\nIf I execute this binary executable, I get the “Hello World” message in the terminal , as we expected.\n./main\nHello, world!\n\n\n1.2.5 Compile and execute at the same time\nOn the previous section, I presented the zig build-exe command, which compiles Zig modules into an executable file. However, this means that, in order to execute the executable file, we have to run two different commands. First, the zig build-exe command, and then, we call the executable file created by the compiler.\nBut what if we wanted to perform these two steps, all at once, in a single command? We can do that by using the zig run command.\nzig run src/main.zig\nHello, world!\n\n\n1.2.6 Important note for Windows users\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other operating systems, such as Linux and macOs. In summary, if you have a piece of Zig code that includes some global variables whose initialization rely on runtime resources, then, you might have some troubles while trying to compile this Zig code on Windows.\nAn example of that is accessing the stdout (i.e. the standard output of your system), which is usually done in Zig by using the expression std.io.getStdOut(). Thus, if you use this expression to instantiate a global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows, with a “unable to evaluate comptime expression” error message.\nThis failure in the compilation process happens because all global variables in Zig are initialized at compile-time. However, operations like accessing the stdout (or opening a file) on Windows depends on resources that are available only at runtime (you will learn more about compile-time versus runtime at Section 3.1.1).\nFor example, if you try to compile this code example on Windows, you will likely get the error message exposed below:\n\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\nTo avoid this problem on Windows, we need to force the zig compiler to instantiate this stdout object only at runtime, instead of instantiating it at compile-time. We can achieve that by simply moving the expression to a function body.\nThis solves the problem because all expressions that are inside a function body in Zig are evaluated only at runtime, unless you use the comptime keyword explicitly to change this behaviour. You will learn more about this comptime keyword at Section 12.1.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nHello\nYou can read more details about this Windows-specific limitation at a couple of GitHub issues opened at the official Zig repository. More specifically, the issues 17186 7 and 19864 8.\n\n\n1.2.7 Compiling the entire project\nJust as I described at Section 1.2.1, as our project grows in size and complexity, we usually prefer to organize the compilation and build process of the project into a build script, using some sort of “build system”.\nIn other words, as our project grows in size and complexity, the build-exe, build-lib and build-obj commands become harder to use directly. Because then, we start to list multiple and multiple modules at the same time. We also start to add built-in compilation flags to customize the build process for our needs, etc. It becomes a lot of work to write the necessary commands by hand.\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, Makefile or configure scripts to organize this process. However, in Zig, we have a native build system in the language itself. So, we can write build scripts in Zig to compile and build Zig projects. Then, all we need to do, is to call the zig build command to build our project.\nSo, when you execute the zig build command, the zig compiler will search for a Zig module named build.zig inside your current directory, which should be your build script, containing the necessary code to compile and build your project. If the compiler does find this build.zig file in your directory, then, the compiler will essentially execute a zig run command over this build.zig file, to compile and execute this build script, which in turn, will compile and build your entire project.\nzig build\nAfter you execute this “build project” command, a zig-out directory is created in the root of your project directory, where you can find the binary executables and libraries created from your Zig modules accordingly to the build commands that you specified at build.zig. We will talk more about the build system in Zig latter in this book.\nIn the example below, I’m executing the binary executable named hello_world that was generated by the compiler after the zig build command.\n./zig-out/bin/hello_world\nHello, world!",
+    "text": "1.2 Hello world in Zig\nWe begin our journey in Zig by creating a small “Hello World” program. To start a new Zig project in your computer, you simply call the init command from the zig compiler. Just create a new directory in your computer, then, init a new Zig project inside this directory, like this:\nmkdir hello_world\ncd hello_world\nzig init\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n\n1.2.1 Understanding the project files\nAfter you run the init command from the zig compiler, some new files are created inside of your current directory. First, a “source” (src) directory is created, containing two files, main.zig and root.zig. Each .zig file is a separate Zig module, which is simply a text file that contains some Zig code.\nBy convention, the main.zig module is where your main function lives. Thus, if you are building an executable program in Zig, you need to declare a main() function, which represents the entrypoint of your program, i.e. it is where the execution of your program begins.\nHowever, if you are building a library (instead of an executable program), then, the normal procedure is to delete this main.zig file and start with the root.zig module. By convention, the root.zig module is the root source file of your library.\ntree .\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\nThe init command also creates two additional files in our working directory: build.zig and build.zig.zon. The first file (build.zig) represents a build script written in Zig. This script is executed when you call the build command from the zig compiler. In other words, this file contain Zig code that executes the necessary steps to build the entire project.\nLow-level languages normally use a compiler to build your source code into binary executables or binary libraries. Nevertheless, this process of compiling your source code and building binary executables or binary libraries from it, became a real challenge in the programming world, once the projects became bigger and bigger. As a result, programmers created “build systems”, which are a second set of tools designed to make this process of compiling and building complex projects, easier.\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja, which are used to build complex C and C++ projects. With these systems, you can write scripts, which are called “build scripts”. They simply are scripts that describes the necessary steps to compile/build your project.\nHowever, these are separate tools, that do not belong to C/C++ compilers, like gcc or clang. As a result, in C/C++ projects, you have not only to install and manage your C/C++ compilers, but you also have to install and manage these build systems separately.\nIn Zig, we don’t need to use a separate set of tools to build our projects, because a build system is embedded inside the language itself. Therefore, Zig contains a native build system in it, and we can use this build system to write small scripts in Zig, which describes the necessary steps to build/compile our Zig project1. So, everything you need to build a complex Zig project is the zig compiler, and nothing more.\nThe second generated file (build.zig.zon) is a JSON-like file, in which you can describe your project, and also, declare a set of dependencies of your project that you want to fetch from the internet. In other words, you can use this build.zig.zon file to include a list of external libraries in your project.\nOne possible way to include an external Zig library in your project, is to manually build and install the library in your system, and just link your source code with the library at the build step of your project.\nHowever, if this external Zig library is available on GitHub for example, and it has a valid build.zig.zon file in root folder of the project, which describes the project, you can easily include this library in your project by simply listing this external library in your build.zig.zon file.\nIn other words, this build.zig.zon file works similarly to the package.json file in Javascript projects, or the Pipfile file in Python projects, or the Cargo.toml file in Rust projects. You can read more about this specific file in a couple of articles on the internet23, and you can also see the expected schema for this build.zig.zon file in a documentation file inside the official repository of Zig4.\n\n\n1.2.2 The file root.zig\nLet’s take a look into the root.zig file. You might have noticed that every line of code with an expression ends with a semicolon (;). This follows the syntax of a C-family programming language5.\nAlso, notice the @import() call at the first line. We use this built-in function to import functionality from other Zig modules into our current module. This @import() function works similarly to the #include pre-processor in C or C++, or, to the import statement in Python or Javascript code. In this example, we are importing the std module, which gives you access to the Zig Standard Library.\nIn this root.zig file, we can also see how assignments (i.e. creating new objects) are made in Zig. You can create a new object in Zig by using the following syntax (const|var) name = value;. In the example below, we are creating two constant objects (std and testing). At Section 1.4 we talk more about objects in general.\n\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n\nFunctions in Zig are declared using the fn keyword. In this root.zig module, we are declaring a function called add(), which has two arguments named a and b. The function returns an integer of the type i32 as result.\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit the type of an object in your code, if this type can be inferred by the zig compiler (we talk more about that at Section 2.4). But there are other situations where you do need to be explicit. For example, you do have to explicitly specify the type of each function argument, and also, the return type of every function that you create in Zig.\nWe specify the type of an object or a function argument in Zig by using a colon character (:) followed by the type after the name of this object/function argument. With the expressions a: i32 and b: i32, we know that both a and b arguments have type i32, which is a signed 32 bit integer. In this part, the syntax in Zig is identical to the syntax in Rust, which also specifies types by using the colon character.\nLastly, we have the return type of the function at the end of the line, before we open the curly braces to start writing the function’s body. In the example above, this type is also a signed 32 bit integer (i32) value.\nNotice that we also have an export keyword before the function declaration. This keyword is similar to the extern keyword in C. It exposes the function to make it available in the library API. Therefore, if you are writing a library for other people to use, you have to expose the functions you write in the public API of this library by using this export keyword. If we removed the export keyword from the add() function declaration, then, this function would be no longer exposed in the library object built by the zig compiler.\n\n\n1.2.3 The main.zig file\nNow that we have learned a lot about Zig’s syntax from the root.zig file, let’s take a look at the main.zig file. A lot of the elements we saw in root.zig are also present in main.zig. But there are some other elements that we haven’t seen yet, so let’s dive in.\nFirst, look at the return type of the main() function in this file. We can see a small change. The return type of the function (void) is accompanied by an exclamation mark (!). This exclamation mark tells us that this main() function might return an error.\nIs worth noting that, a main() function in Zig is allowed to return nothing (void), or an unsigned 8-bit integer (u8) value6, or an error. In other words, you can write your main() function in Zig to return essentially nothing (void), or, if you prefer, you can also write a more C-like main() function, which returns an integer value that usually serves as a “status code” for the process.\nIn this example, the return type annotation of main() indicates that this function can either return nothing (void), or return an error. This exclamation mark in the return type annotation is an interesting and powerful feature of Zig. In summary, if you write a function and something inside the body of this function might return an error, then, you are forced to:\n\neither add the exclamation mark to the return type of the function and make it clear that this function might return an error.\nexplicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through a try catch pattern. Zig does have both try and catch keywords. But they work a little differently than what you’re probably used to in other languages.\nIf we look at the main() function below, you can see that we do have a try keyword on the 5th line. But we do not have a catch keyword in this code. In Zig, we use the try keyword to execute an expression that might return an error, which, in this example, is the stdout.print() expression.\nIn essence, the try keyword executes the expression stdout.print(). If this expression returns a valid value, then, the try keyword does absolutely nothing. It only passes the value forward. It is like if this try keyword was never there. However, if the expression does return an error, then, the try keyword will unwrap the error value, then, it returns this error from the function and also prints the current stack trace to stderr.\nThis might sound weird to you if you come from a high-level language. Because in high-level languages, such as Python, if an error occurs somewhere, this error is automatically returned and the execution of your program will automatically stop even if you don’t want to stop the execution. You are obligated to face the error.\n\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n\nAnother thing that you might have noticed in this code example, is that the main() function is marked with the pub keyword. It marks the main() function as a public function from this module. Every function in your Zig module is by default private to this Zig module and can only be called from within the module. Unless, you explicitly mark this function as a public function with the pub keyword.\nIf you think about it, this pub keyword in Zig does essentially the opposite of what the static keyword do in C/C++. By making a function “public” you allow other Zig modules to access and call this function. A calling Zig module imports another module by using the @import() built-in function, which makes all public functions from the imported module visible to the calling Zig module.\n\n\n1.2.4 Compiling your source code\nYou can compile your Zig modules into a binary executable by running the build-exe command from the zig compiler. You simply list all the Zig modules that you want to build after the build-exe command, separated by spaces. In the example below, we are compiling the module main.zig.\nzig build-exe src/main.zig\nSince we are building an executable, the zig compiler will look for a main() function declared in any of the files that you list after the build-exe command. If the compiler does not find a main() function declared somewhere, a compilation error will be raised, warning about this mistake.\nThe zig compiler also offers a build-lib and build-obj commands, which work the exact same way as the build-exe command. The only difference is that, they compile your Zig modules into a portale C ABI library, or, into object files, respectively.\nIn the case of the build-exe command, a binary executable file is created by the zig compiler in the root directory of your project. If we take a look now at the contents of our current directory, with a simple ls command, we can see the binary file called main that was created by the compiler.\nls\nbuild.zig  build.zig.zon  main  src\nIf I execute this binary executable, I get the “Hello World” message in the terminal , as we expected.\n./main\nHello, world!\n\n\n1.2.5 Compile and execute at the same time\nOn the previous section, I presented the zig build-exe command, which compiles Zig modules into an executable file. However, this means that, in order to execute the executable file, we have to run two different commands. First, the zig build-exe command, and then, we call the executable file created by the compiler.\nBut what if we wanted to perform these two steps, all at once, in a single command? We can do that by using the zig run command.\nzig run src/main.zig\nHello, world!\n\n\n1.2.6 Important note for Windows users\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other operating systems, such as Linux and macOs. In summary, if you have a piece of Zig code that includes some global variables whose initialization rely on runtime resources, then, you might have some troubles while trying to compile this Zig code on Windows.\nAn example of that is accessing the stdout (i.e. the standard output of your system), which is usually done in Zig by using the expression std.io.getStdOut(). Thus, if you use this expression to instantiate a global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows, with a “unable to evaluate comptime expression” error message.\nThis failure in the compilation process happens because all global variables in Zig are initialized at compile-time. However, operations like accessing the stdout (or opening a file) on Windows depends on resources that are available only at runtime (you will learn more about compile-time versus runtime at Section 3.1.1).\nFor example, if you try to compile this code example on Windows, you will likely get the error message exposed below:\n\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\nTo avoid this problem on Windows, we need to force the zig compiler to instantiate this stdout object only at runtime, instead of instantiating it at compile-time. We can achieve that by simply moving the expression to a function body.\nThis solves the problem because all expressions that are inside a function body in Zig are evaluated only at runtime, unless you use the comptime keyword explicitly to change this behaviour. You will learn more about this comptime keyword at Section 12.1.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nHello\nYou can read more details about this Windows-specific limitation at a couple of GitHub issues opened at the official Zig repository. More specifically, the issues 17186 7 and 19864 8.\n\n\n1.2.7 Compiling the entire project\nJust as I described at Section 1.2.1, as our project grows in size and complexity, we usually prefer to organize the compilation and build process of the project into a build script, using some sort of “build system”.\nIn other words, as our project grows in size and complexity, the build-exe, build-lib and build-obj commands become harder to use directly. Because then, we start to list multiple and multiple modules at the same time. We also start to add built-in compilation flags to customize the build process for our needs, etc. It becomes a lot of work to write the necessary commands by hand.\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, Makefile or configure scripts to organize this process. However, in Zig, we have a native build system in the language itself. So, we can write build scripts in Zig to compile and build Zig projects. Then, all we need to do, is to call the zig build command to build our project.\nSo, when you execute the zig build command, the zig compiler will search for a Zig module named build.zig inside your current directory, which should be your build script, containing the necessary code to compile and build your project. If the compiler does find this build.zig file in your directory, then, the compiler will essentially execute a zig run command over this build.zig file, to compile and execute this build script, which in turn, will compile and build your entire project.\nzig build\nAfter you execute this “build project” command, a zig-out directory is created in the root of your project directory, where you can find the binary executables and libraries created from your Zig modules accordingly to the build commands that you specified at build.zig. We will talk more about the build system in Zig latter in this book.\nIn the example below, I’m executing the binary executable named hello_world that was generated by the compiler after the zig build command.\n./zig-out/bin/hello_world\nHello, world!",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -144,7 +144,7 @@
     "href": "Chapters/01-zig-weird.html#sec-assignments",
     "title": "1  Introducing Zig",
     "section": "1.4 Creating new objects in Zig (i.e. identifiers)",
-    "text": "1.4 Creating new objects in Zig (i.e. identifiers)\nLet’s talk more about objects in Zig. Readers that have past experience with other programming languages might know this concept through a different name, such as: “variable” or “identifier”. In this book, I choose to use the term “object” to refer to this concept.\nTo create a new object (or a new “identifier”) in Zig, we use the keywords const or var. These keywords specify if the object that you are creating is mutable or not. If you use const, then the object you are creating is a constant (or immutable) object, which means that once you declare this object, you can no longer change the value stored inside this object.\nOn the other side, if you use var, then, you are creating a variable (or mutable) object. You can change the value of this object as many times you want. Using the keyword var in Zig is similar to using the keywords let mut in Rust.\n\n1.4.1 Constant objects vs variable objects\nIn the code example below, we are creating a new constant object called age. This object stores a number representing the age of someone. However, this code example does not compiles successfully. Because on the next line of code, we are trying to change the value of the object age to 25.\nThe zig compiler detects that we are trying to change the value of an object/identifier that is constant, and because of that, the compiler will raise a compilation error, warning us about the mistake.\n\nconst age = 24;\n// The line below is not valid!\nage = 25;\n\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\nIn contrast, if you use var, then, the object created is a variable object. With var you can declare this object in your source code, and then, change the value of this object how many times you want over future points in your source code.\nSo, using the same code example exposed above, if I change the declaration of the age object to use the var keyword, then, the program gets compiled successfully. Because now, the zig compiler detects that we are changing the value of an object that allows this behaviour, because it is an “variable object”.\n\nvar age: u8 = 24;\nage = 25;\n\n\n\n1.4.2 Declaring without an initial value\nBy default, when you declare a new object in Zig, you must give it an initial value. In other words, this means that we have to declare, and, at the same time, initialize every object we create in our source code.\nOn the other hand, you can, in fact, declare a new object in your source code, and not give it an explicit value. But we need to use a special keyword for that, which is the undefined keyword.\nIs important to emphasize that, you should avoid using undefined as much as possible. Because when you use this keyword, you leave your object uninitialized, and, as a consequence, if for some reason, your code use this object while it is uninitialized, then, you will definitely have undefined behaviour and major bugs in your program.\nIn the example below, I’m declaring the age object again. But this time, I do not give it an initial value. The variable is only initialized at the second line of code, where I store the number 25 in this object.\n\nvar age: u8 = undefined;\nage = 25;\n\nHaving these points in mind, just remember that you should avoid as much as possible to use undefined in your code. Always declare and initialize your objects. Because this gives you much more safety in your program. But in case you really need to declare an object without initializing it… the undefined keyword is the way to do it in Zig.\n\n\n1.4.3 There is no such thing as unused objects\nEvery object (being constant or variable) that you declare in Zig must be used in some way. You can give this object to a function call, as a function argument, or, you can use it in another expression to calculate the value of another object, or, you can call a method that belongs to this particular object.\nIt doesn’t matter in which way you use it. As long as you use it. If you try to break this rule, i.e. if your try to declare a object, but not use it, the zig compiler will not compile your Zig source code, and it will issue a error message warning that you have unused objects in your code.\nLet’s demonstrate this with an example. In the source code below, we declare a constant object called age. If you try to compile a simple Zig program with this line of code below, the compiler will return an error as demonstrated below:\n\nconst age = 15;\n\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\nEverytime you declare a new object in Zig, you have two choices:\n\nyou either use the value of this object;\nor you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign this object to an special character in Zig, which is the underscore (_). When you assign an object to a underscore, like in the example below, the zig compiler will automatically discard the value of this particular object.\nYou can see in the example below that, this time, the compiler did not complain about any “unused constant”, and successfully compiled our source code.\n\n// It compiles!\nconst age = 15;\n_ = age;\n\nNow, remember, everytime you assign a particular object to the underscore, this object is essentially destroyed. It is discarded by the compiler. This means that you can no longer use this object further in your code. It doesn’t exist anymore.\nSo if you try to use the constant age in the example below, after we discarded it, you will get a loud error message from the compiler (talking about a “pointless discard”) warning you about this mistake.\n\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n\nt.zig:7:5: error: pointless discard\n    of local constant\nThis same rule applies to variable objects. Every variable object must also be used in some way. And if you assign a variable object to the underscore, this object also get’s discarded, and you can no longer use this object.\n\n\n1.4.4 You must mutate every variable objects\nEvery variable object that you create in your source code must be mutated at some point. In other words, if you declare an object as a variable object, with the keyword var, and you do not change the value of this object at some point in the future, the zig compiler will detect this, and it will raise an error warning you about this mistake.\nThe concept behind this is that every object you create in Zig should be preferably a constant object, unless you really need an object whose value will change during the execution of your program.\nSo, if I try to declare a variable object such as where_i_live below, and I do not change the value of this object in some way, the zig compiler raises an error message with the phrase “variable is never mutated”.\n\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'",
+    "text": "1.4 Creating new objects in Zig (i.e. identifiers)\nLet’s talk more about objects in Zig. Readers that have past experience with other programming languages might know this concept through a different name, such as: “variable” or “identifier”. In this book, I choose to use the term “object” to refer to this concept.\nTo create a new object (or a new “identifier”) in Zig, we use the keywords const or var. These keywords specify if the object that you are creating is mutable or not. If you use const, then the object you are creating is a constant (or immutable) object, which means that once you declare this object, you can no longer change the value stored inside this object.\nOn the other side, if you use var, then, you are creating a variable (or mutable) object. You can change the value of this object as many times you want. Using the keyword var in Zig is similar to using the keywords let mut in Rust.\n\n1.4.1 Constant objects vs variable objects\nIn the code example below, we are creating a new constant object called age. This object stores a number representing the age of someone. However, this code example does not compile successfully. Because on the next line of code, we are trying to change the value of the object age to 25.\nThe zig compiler detects that we are trying to change the value of an object/identifier that is constant, and because of that, the compiler will raise a compilation error, warning us about the mistake.\n\nconst age = 24;\n// The line below is not valid!\nage = 25;\n\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\nIn contrast, if you use var, then, the object created is a variable object. With var you can declare this object in your source code, and then, change the value of this object how many times you want over future points in your source code.\nSo, using the same code example exposed above, if I change the declaration of the age object to use the var keyword, then, the program gets compiled successfully. Because now, the zig compiler detects that we are changing the value of an object that allows this behaviour, because it is an “variable object”.\n\nvar age: u8 = 24;\nage = 25;\n\n\n\n1.4.2 Declaring without an initial value\nBy default, when you declare a new object in Zig, you must give it an initial value. In other words, this means that we have to declare, and, at the same time, initialize every object we create in our source code.\nOn the other hand, you can, in fact, declare a new object in your source code, and not give it an explicit value. But we need to use a special keyword for that, which is the undefined keyword.\nIs important to emphasize that, you should avoid using undefined as much as possible. Because when you use this keyword, you leave your object uninitialized, and, as a consequence, if for some reason, your code use this object while it is uninitialized, then, you will definitely have undefined behaviour and major bugs in your program.\nIn the example below, I’m declaring the age object again. But this time, I do not give it an initial value. The variable is only initialized at the second line of code, where I store the number 25 in this object.\n\nvar age: u8 = undefined;\nage = 25;\n\nHaving these points in mind, just remember that you should avoid as much as possible to use undefined in your code. Always declare and initialize your objects. Because this gives you much more safety in your program. But in case you really need to declare an object without initializing it… the undefined keyword is the way to do it in Zig.\n\n\n1.4.3 There is no such thing as unused objects\nEvery object (being constant or variable) that you declare in Zig must be used in some way. You can give this object to a function call, as a function argument, or, you can use it in another expression to calculate the value of another object, or, you can call a method that belongs to this particular object.\nIt doesn’t matter in which way you use it. As long as you use it. If you try to break this rule, i.e. if your try to declare a object, but not use it, the zig compiler will not compile your Zig source code, and it will issue a error message warning that you have unused objects in your code.\nLet’s demonstrate this with an example. In the source code below, we declare a constant object called age. If you try to compile a simple Zig program with this line of code below, the compiler will return an error as demonstrated below:\n\nconst age = 15;\n\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\nEverytime you declare a new object in Zig, you have two choices:\n\nyou either use the value of this object;\nor you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign this object to an special character in Zig, which is the underscore (_). When you assign an object to a underscore, like in the example below, the zig compiler will automatically discard the value of this particular object.\nYou can see in the example below that, this time, the compiler did not complain about any “unused constant”, and successfully compiled our source code.\n\n// It compiles!\nconst age = 15;\n_ = age;\n\nNow, remember, everytime you assign a particular object to the underscore, this object is essentially destroyed. It is discarded by the compiler. This means that you can no longer use this object further in your code. It doesn’t exist anymore.\nSo if you try to use the constant age in the example below, after we discarded it, you will get a loud error message from the compiler (talking about a “pointless discard”) warning you about this mistake.\n\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n\nt.zig:7:5: error: pointless discard\n    of local constant\nThis same rule applies to variable objects. Every variable object must also be used in some way. And if you assign a variable object to the underscore, this object also get’s discarded, and you can no longer use this object.\n\n\n1.4.4 You must mutate every variable objects\nEvery variable object that you create in your source code must be mutated at some point. In other words, if you declare an object as a variable object, with the keyword var, and you do not change the value of this object at some point in the future, the zig compiler will detect this, and it will raise an error warning you about this mistake.\nThe concept behind this is that every object you create in Zig should be preferably a constant object, unless you really need an object whose value will change during the execution of your program.\nSo, if I try to declare a variable object such as where_i_live below, and I do not change the value of this object in some way, the zig compiler raises an error message with the phrase “variable is never mutated”.\n\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -184,7 +184,7 @@
     "href": "Chapters/01-zig-weird.html#sec-zig-strings",
     "title": "1  Introducing Zig",
     "section": "1.8 How strings work in Zig?",
-    "text": "1.8 How strings work in Zig?\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (Chapter 4). But in order for us to build such a thing, we need to get a better understanding on how strings work in Zig. So let’s discuss this specific aspect of Zig.\nIn summary, there are two types of string values that you care about in Zig, which are:\n\nString literal values.\nString objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string). But in Zig, a string literal value also embeds the length of the string into the data type of the value itself. Therefore, a string literal value have a data type in the format *const [n:0]u8. The n in the data type indicates the size of the string.\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes, or, in other words, a slice of u8 values (slices were presented at Section 1.6). Thus, a string object have a data type of []u8 or []const u8, depending if the string object is marked as constant with const, or as variable with var.\nBecause a string object is essentially a slice, it means that a string object always contains two things: a pointer to an array of bytes (i.e. u8 values) that represents the string value; and also, a length value, which specifies the size of the slice, or, how many elements there is in the slice. Is worth to emphasize that the array of bytes in a string object is not null-terminated, like in a string literal value.\n\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every sequence of bytes you’re working with, but is not really Zig’s job to fix the encoding of your strings (you can use iconv22 for that). Today, most of the text in our modern world, especially on the web, should be UTF-8 encoded. So if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\nLet’s take for example the word “Hello”. In UTF-8, this sequence of characters (H, e, l, l, o) is represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this sequence is 0x48, 0x65, 0x6C, 0x6C, 0x6F. So if I take this sequence of hexadecimal values, and ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then, the text “Hello” will be printed into the terminal:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n\nHello\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use a for loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal value to the terminal. You do that by using a print() statement with the X formatting specifier, like you would normally do with the printf() function23 in C.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n\n\n\n1.8.1 Strings in C\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well. In more details, string values in C are treated internally as an array of arbitrary bytes, and this array is also null-terminated.\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of the string inside the object itself. In the case of a string literal value, this length is stored in the data type of the value (i.e. the n variable in [n:0]u8). While, in a string object, the length is stored in the len attribute of the slice that represents the string object. This small detail makes your code safer, because is much easier for the Zig compiler to check if you are trying to access an element that is “out of bounds”, i.e. if your trying to access memory that does not belong to you.\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless. So getting this kind of safety is not automatic and much harder to do in C. For example, if you want to track the length of your string throughout your program in C, then, you first need to loop through the array of bytes that represents this string, and find the null element ('\\0') position to discover where exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\nTo do that, you would need something like this in C. In this example, the C string stored in the object array is 25 bytes long:\n\n#include &lt;stdio.h&gt;\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n\nNumber of elements in the array: 25\nYou don’t have this kind of work in Zig. Because the length of the string is always present and accessible. In a string object for example, you can easily access the length of the string through the len attribute. As an example, the string_object object below is 43 bytes long:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n\n43\n\n\n\n\n1.8.2 A better look at the object type\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the @TypeOf() function. If we look at the type of the simple_array object below, you will find that this object is an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type i32 in Zig. That is what an object of type [4]i32 is.\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a constant pointer (hence the *const annotation) to an array of 16 elements (or 16 bytes). Each element is a single byte (more precisely, an unsigned 8 bit integer - u8), that is why we have the [16:0]u8 portion of the type below. In other words, the string literal value exposed below is 16 bytes long.\nNow, if we create an pointer to the simple_array object, then, we get a constant pointer to an array of 4 elements (*const [4]i32), which is very similar to the type of the string literal value. This demonstrates that a string literal value in Zig is already a pointer to a null-terminated array of bytes.\nFurthermore, if we take a look at the type of the string_obj object, you will see that it is a slice object (hence the [] portion of the type) to a sequence of constant u8 values (hence the const u8 portion of the type).\n\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n\n\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n\n\n1.8.3 Byte vs unicode points\nIs important to point out that each byte in the array is not necessarily a single character. This fact arises from the difference between a single byte and a single unicode point.\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in the string. For example, the character “H” is stored in UTF-8 as the decimal number 72. This means that the number 72 is the unicode point for the character “H”. Each possible character that can appear in a UTF-8 encoded string have its own unicode point.\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point) 570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which is 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why, the unicode point 570 is actually stored inside the computer’s memory as the bytes C8 BA.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n\nBytes that represents the string object: C8 BA \n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together to represent the number 570. That is why the relationship between bytes and unicode points is not always 1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds to a single unicode point.\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the bytes that represents that string, and not through the characters of that string. In the Ⱥ example above, the for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a consequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because the number of bytes will be equal to the number of characters in that string. In other words, in this specific situation, the relationship between bytes and unicode points is 1 to 1.\nBut on the other side, if your string contains other types of letters… for example, you might be working with text data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent your UTF-8 string will likely be much higher than the number of characters in that string.\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the std.unicode.Utf8View struct to create an iterator that iterates through the unicode points of your string.\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in this string is represented by three bytes. But the for loop iterates four times, one iteration for each character/unicode point in this string:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n\n\n1.8.4 Some useful functions for strings\nIn this section, I just want to quickly describe some functions from the Zig Standard Library that are very useful to use when working with strings. Most notably:\n\nstd.mem.eql(): to compare if two strings are equal.\nstd.mem.splitScalar(): to split a string into an array of substrings given a delimiter value.\nstd.mem.splitSequence(): to split a string into an array of substrings given a substring delimiter.\nstd.mem.startsWith(): to check if string starts with substring.\nstd.mem.endsWith(): to check if string ends with substring.\nstd.mem.trim(): to remove specific values from both start and end of the string.\nstd.mem.concat(): to concatenate strings together.\nstd.mem.count(): to count the occurrences of substring in the string.\nstd.mem.replace(): to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the mem module of the Zig Standard Library. This module contains multiple functions and methods that are useful to work with memory and sequences of bytes in general.\nThe eql() function is used to check if two arrays of data are equal or not. Since strings are just arbitrary arrays of bytes, we can use this function to compare two strings together. This function returns a boolean value indicating if the two strings are equal or not. The first argument of this function is the data type of the elements of the arrays that are being compared.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n\ntrue\n\n\nThe splitScalar() and splitSequence() functions are useful to split a string into multiple fragments, like the split() method from Python strings. The difference between these two methods is that the splitScalar() uses a single character as the separator to split the string, while splitSequence() uses a sequence of characters (a.k.a. a substring) as the separator. There is a practical example of these functions later in the book.\nThe startsWith() and endsWith() functions are pretty straightforward. They return a boolean value indicating if the string (or, more precisely, if the array of data) begins (startsWith) or ends (endsWith) with the sequence provided.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n\ntrue\n\n\nThe concat() function, as the name suggests, concatenate two or more strings together. Because the process of concatenating the strings involves allocating enough space to accomodate all the strings together, this concat() function receives an allocator object as input.\n\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n\nAs you can imagine, the replace() function is used to replace substrings in a string by another substring. This function works very similarly to the replace() method from Python strings. Therefore, you provide a substring to search, and every time that the replace() function finds this substring within the input string, it replaces this substring with the “replacement substring” that you provided as input.\nIn the example below, we are taking the input string “Hello”, and replacing all occurrences of the substring “el” inside this input string with “34”, and saving the results inside the buffer object. As result, the replace() function returns an usize value that indicates how many replacements were performed.\n\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n\nNew string: H34lo\nN of replacements: 1",
+    "text": "1.8 How strings work in Zig?\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (Chapter 4). But in order for us to build such a thing, we need to get a better understanding on how strings work in Zig. So let’s discuss this specific aspect of Zig.\nIn summary, there are two types of string values that you care about in Zig, which are:\n\nString literal values.\nString objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string). But in Zig, a string literal value also embeds the length of the string into the data type of the value itself. Therefore, a string literal value have a data type in the format *const [n:0]u8. The n in the data type indicates the size of the string.\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes, or, in other words, a slice of u8 values (slices were presented at Section 1.6). Thus, a string object have a data type of []u8 or []const u8, depending if the string object is marked as constant with const, or as variable with var.\nBecause a string object is essentially a slice, it means that a string object always contains two things: a pointer to an array of bytes (i.e. u8 values) that represents the string value; and also, a length value, which specifies the size of the slice, or, how many elements there is in the slice. Is worth to emphasize that the array of bytes in a string object is not null-terminated, like in a string literal value.\n\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every sequence of bytes you’re working with, but is not really Zig’s job to fix the encoding of your strings (you can use iconv22 for that). Today, most of the text in our modern world, especially on the web, should be UTF-8 encoded. So if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\nLet’s take for example the word “Hello”. In UTF-8, this sequence of characters (H, e, l, l, o) is represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this sequence is 0x48, 0x65, 0x6C, 0x6C, 0x6F. So if I take this sequence of hexadecimal values, and ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then, the text “Hello” will be printed into the terminal:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n\nHello\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use a for loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal value to the terminal. You do that by using a print() statement with the X formatting specifier, like you would normally do with the printf() function23 in C.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n\n\n\n1.8.1 Strings in C\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well. In more details, string values in C are treated internally as an array of arbitrary bytes, and this array is also null-terminated.\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of the string inside the object itself. In the case of a string literal value, this length is stored in the data type of the value (i.e. the n variable in [n:0]u8). While, in a string object, the length is stored in the len attribute of the slice that represents the string object. This small detail makes your code safer, because it is much easier for the Zig compiler to check if you are trying to access an element that is “out of bounds”, i.e. if your trying to access memory that does not belong to you.\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless. So getting this kind of safety is not automatic and much harder to do in C. For example, if you want to track the length of your string throughout your program in C, then, you first need to loop through the array of bytes that represents this string, and find the null element ('\\0') position to discover where exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\nTo do that, you would need something like this in C. In this example, the C string stored in the object array is 25 bytes long:\n\n#include &lt;stdio.h&gt;\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n\nNumber of elements in the array: 25\nYou don’t have this kind of work in Zig. Because the length of the string is always present and accessible. In a string object for example, you can easily access the length of the string through the len attribute. As an example, the string_object object below is 43 bytes long:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n\n43\n\n\n\n\n1.8.2 A better look at the object type\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the @TypeOf() function. If we look at the type of the simple_array object below, you will find that this object is an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type i32 in Zig. That is what an object of type [4]i32 is.\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a constant pointer (hence the *const annotation) to an array of 16 elements (or 16 bytes). Each element is a single byte (more precisely, an unsigned 8 bit integer - u8), that is why we have the [16:0]u8 portion of the type below. In other words, the string literal value exposed below is 16 bytes long.\nNow, if we create an pointer to the simple_array object, then, we get a constant pointer to an array of 4 elements (*const [4]i32), which is very similar to the type of the string literal value. This demonstrates that a string literal value in Zig is already a pointer to a null-terminated array of bytes.\nFurthermore, if we take a look at the type of the string_obj object, you will see that it is a slice object (hence the [] portion of the type) to a sequence of constant u8 values (hence the const u8 portion of the type).\n\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n\n\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n\n\n1.8.3 Byte vs unicode points\nIs important to point out that each byte in the array is not necessarily a single character. This fact arises from the difference between a single byte and a single unicode point.\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in the string. For example, the character “H” is stored in UTF-8 as the decimal number 72. This means that the number 72 is the unicode point for the character “H”. Each possible character that can appear in a UTF-8 encoded string have its own unicode point.\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point) 570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which is 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why, the unicode point 570 is actually stored inside the computer’s memory as the bytes C8 BA.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n\nBytes that represents the string object: C8 BA \n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together to represent the number 570. That is why the relationship between bytes and unicode points is not always 1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds to a single unicode point.\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the bytes that represents that string, and not through the characters of that string. In the Ⱥ example above, the for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a consequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because the number of bytes will be equal to the number of characters in that string. In other words, in this specific situation, the relationship between bytes and unicode points is 1 to 1.\nBut on the other side, if your string contains other types of letters… for example, you might be working with text data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent your UTF-8 string will likely be much higher than the number of characters in that string.\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the std.unicode.Utf8View struct to create an iterator that iterates through the unicode points of your string.\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in this string is represented by three bytes. But the for loop iterates four times, one iteration for each character/unicode point in this string:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n\n\n1.8.4 Some useful functions for strings\nIn this section, I just want to quickly describe some functions from the Zig Standard Library that are very useful to use when working with strings. Most notably:\n\nstd.mem.eql(): to compare if two strings are equal.\nstd.mem.splitScalar(): to split a string into an array of substrings given a delimiter value.\nstd.mem.splitSequence(): to split a string into an array of substrings given a substring delimiter.\nstd.mem.startsWith(): to check if string starts with substring.\nstd.mem.endsWith(): to check if string ends with substring.\nstd.mem.trim(): to remove specific values from both start and end of the string.\nstd.mem.concat(): to concatenate strings together.\nstd.mem.count(): to count the occurrences of substring in the string.\nstd.mem.replace(): to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the mem module of the Zig Standard Library. This module contains multiple functions and methods that are useful to work with memory and sequences of bytes in general.\nThe eql() function is used to check if two arrays of data are equal or not. Since strings are just arbitrary arrays of bytes, we can use this function to compare two strings together. This function returns a boolean value indicating if the two strings are equal or not. The first argument of this function is the data type of the elements of the arrays that are being compared.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n\ntrue\n\n\nThe splitScalar() and splitSequence() functions are useful to split a string into multiple fragments, like the split() method from Python strings. The difference between these two methods is that the splitScalar() uses a single character as the separator to split the string, while splitSequence() uses a sequence of characters (a.k.a. a substring) as the separator. There is a practical example of these functions later in the book.\nThe startsWith() and endsWith() functions are pretty straightforward. They return a boolean value indicating if the string (or, more precisely, if the array of data) begins (startsWith) or ends (endsWith) with the sequence provided.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n\ntrue\n\n\nThe concat() function, as the name suggests, concatenate two or more strings together. Because the process of concatenating the strings involves allocating enough space to accomodate all the strings together, this concat() function receives an allocator object as input.\n\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n\nAs you can imagine, the replace() function is used to replace substrings in a string by another substring. This function works very similarly to the replace() method from Python strings. Therefore, you provide a substring to search, and every time that the replace() function finds this substring within the input string, it replaces this substring with the “replacement substring” that you provided as input.\nIn the example below, we are taking the input string “Hello”, and replacing all occurrences of the substring “el” inside this input string with “34”, and saving the results inside the buffer object. As result, the replace() function returns an usize value that indicates how many replacements were performed.\n\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n\nNew string: H34lo\nN of replacements: 1",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -194,7 +194,7 @@
     "href": "Chapters/01-zig-weird.html#safety-in-zig",
     "title": "1  Introducing Zig",
     "section": "1.9 Safety in Zig",
-    "text": "1.9 Safety in Zig\nA general trend in modern low-level programming languages is safety. As our modern world becomes more interconnected with technology and computers, the data produced by all of this technology becomes one of the most important (and also, one of the most dangerous) assets that we have.\nThis is probably the main reason why modern low-level programming languages have been giving great attention to safety, especially memory safety, because memory corruption is still the main target for hackers to exploit. The reality is that we don’t have an easy solution for this problem. For now, we only have techniques and strategies that mitigates these problems.\nAs Richard Feldman explains on his most recent GOTO conference talk24 , we haven’t figured it out yet a way to achieve true safety in technology. In other words, we haven’t found a way to build software that won’t be exploited with 100% certainty. We can greatly reduce the risks of our software being exploited, by ensuring memory safety for example. But this is not enough to achieve “true safety” territory.\nBecause even if you write your program in a “safe language”, hackers can still exploit failures in the operating system where your program is running (e.g. maybe the system where your code is running has a “backdoor exploit” that can still affect your code in unexpected ways), or also, they can exploit the features from the architecture of your computer. A recently found exploit that involves memory invalidation through a feature of “memory tags” present in ARM chips is an example of that (Kim et al. 2024).\nThe question is: what have Zig and other languages been doing to mitigate this problem? If we take Rust as an example, Rust is, for the most part25, a memory safe language by enforcing specific rules to the developer. In other words, the key feature of Rust, the borrow checker, forces you to follow a specific logic when you are writing your Rust code, and the Rust compiler will always complain everytime you try to go out of this pattern.\nIn contrast, the Zig language is not a memory safe language by default. There are some memory safety features that you get for free in Zig, especially in arrays and pointer objects. But there are other tools offered by the language, that are not used by default. In other words, the zig compiler does not obligates you to use such tools.\nThe tools listed below are related to memory safety. That is, they help you to achieve memory safety in your Zig code:\n\ndefer allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, “use after free”, and also “double-free” problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\nerrdefer helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\npointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\nZig offers some native types of allocators (called “testing allocators”) that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\narrays and slices in Zig have their lengths embedded in the object itself, which makes the zig compiler very effective on detecting “index out-of-range” type of errors, and avoiding buffer overflows.\n\nDespite these features that Zig offers that are related to memory safety issues, the language also has some rules that help you to achieve another type of safety, which is more related to program logic safety. These rules are:\n\npointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\nswitch statements must exaust all possible options.\nthe zig compiler forces you to handle every possible error in your program.",
+    "text": "1.9 Safety in Zig\nA general trend in modern low-level programming languages is safety. As our modern world becomes more interconnected with technology and computers, the data produced by all of this technology becomes one of the most important (and also, one of the most dangerous) assets that we have.\nThis is probably the main reason why modern low-level programming languages have been giving great attention to safety, especially memory safety, because memory corruption is still the main target for hackers to exploit. The reality is that we don’t have an easy solution for this problem. For now, we only have techniques and strategies that mitigates these problems.\nAs Richard Feldman explains on his most recent GOTO conference talk24 , we haven’t figured it out yet a way to achieve true safety in technology. In other words, we haven’t found a way to build software that won’t be exploited with 100% certainty. We can greatly reduce the risks of our software being exploited, by ensuring memory safety for example. But this is not enough to achieve “true safety” territory.\nBecause even if you write your program in a “safe language”, hackers can still exploit failures in the operating system where your program is running (e.g. maybe the system where your code is running has a “backdoor exploit” that can still affect your code in unexpected ways), or also, they can exploit the features from the architecture of your computer. A recently found exploit that involves memory invalidation through a feature of “memory tags” present in ARM chips is an example of that (Kim et al. 2024).\nThe question is: what have Zig and other languages been doing to mitigate this problem? If we take Rust as an example, Rust is, for the most part25, a memory safe language by enforcing specific rules to the developer. In other words, the key feature of Rust, the borrow checker, forces you to follow a specific logic when you are writing your Rust code, and the Rust compiler will always complain everytime you try to go out of this pattern.\nIn contrast, the Zig language is not a memory safe language by default. There are some memory safety features that you get for free in Zig, especially in arrays and pointer objects. But there are other tools offered by the language, that are not used by default. In other words, the zig compiler does not obligate you to use such tools.\nThe tools listed below are related to memory safety. That is, they help you to achieve memory safety in your Zig code:\n\ndefer allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, “use after free”, and also “double-free” problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\nerrdefer helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\npointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\nZig offers some native types of allocators (called “testing allocators”) that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\narrays and slices in Zig have their lengths embedded in the object itself, which makes the zig compiler very effective on detecting “index out-of-range” type of errors, and avoiding buffer overflows.\n\nDespite these features that Zig offers that are related to memory safety issues, the language also has some rules that help you to achieve another type of safety, which is more related to program logic safety. These rules are:\n\npointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\nswitch statements must exaust all possible options.\nthe zig compiler forces you to handle every possible error in your program.",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -234,7 +234,7 @@
     "href": "Chapters/03-structs.html#sec-zig-control-flow",
     "title": "2  Control flow, structs, modules and types",
     "section": "",
-    "text": "2.1.1 If/else statements\nAn if/else statement performs a “conditional flow operation”. A conditional flow control (or choice control) allows you to execute or ignore a certain block of commands based on a logical condition. Many programmers and computer science professionals also use the term “branching” in this case. In essence, an if/else statement allow us to use the result of a logical test to decide whether or not to execute a given block of commands.\nIn Zig, we write if/else statements by using the keywords if and else. We start with the if keyword followed by a logical test inside a pair of parentheses, followed by a pair of curly braces which contains the lines of code to be executed in case the logical test returns the value true.\nAfter that, you can optionally add an else statement. To do that, just add the else keyword followed by a pair of curly braces, with the lines of code to executed in case the logical test defined at if returns false.\nIn the example below, we are testing if the object x contains a number that is greater than 10. Judging by the output printed to the console, we know that this logical test returned false. Because the output in the console is compatible with the line of code present in the else branch of the if/else statement.\n\nconst x = 5;\nif (x &gt; 10) {\n    try stdout.print(\n        \"x &gt; 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x &lt;= 10!\\n\", .{}\n    );\n}\n\nx &lt;= 10!\n\n\n\n\n2.1.2 Switch statements\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust. As you would expect, to write a switch statement in Zig we use the switch keyword. We provide the value that we want to “switch over” inside a pair of parentheses. Then, we list the possible combinations (or “branches”) inside a pair of curly braces.\nLet’s take a look at the code example below. You can see that I’m creating an enum type called Role. We talk more about enums in Section 7.6. But in summary, this Role type is listing different types of roles in a fictitious company, like SE for Software Engineer, DE for Data Engineer, PM for Product Manager, etc.\nNotice that we are using the value from the role object in the switch statement, to discover which exact area we need to store in the area variable object. Also notice that we are using type inference inside the switch statement, with the dot character, as we are going to describe in Section 2.4. This makes the zig compiler infer the correct data type of the values (PM, SE, etc.) for us.\nAlso notice that, we are grouping multiple values in the same branch of the switch statement. We just separate each possible value with a comma. For example, if role contains either DE or DA, the area variable would contain the value \"Data & Analytics\", instead of \"Platform\" or \"Sales\".\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO =&gt; {\n            area = \"Platform\";\n        },\n        .DE, .DA =&gt; {\n            area = \"Data & Analytics\";\n        },\n        .KS =&gt; {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n\nPlatform\n\n\n\n2.1.2.1 Switch statements must exhaust all possibilities\nOne very important aspect about switch statements in Zig is that they must exhaust all existing possibilities. In other words, all possible values that could be found inside the order object must be explicitly handled in this switch statement.\nSince the role object have type Role, the only possible values to be found inside this object are PM, SE, DPE, PO, DE, DA and KS. There are no other possible values to be stored in this role object. Thus, the switch statements must have a combination (branch) for each one of these values. This is what “exhaust all existing possibilities” means. The switch statement covers every possible case.\nTherefore, you cannot write a switch statement in Zig, and leave an edge case with no explicit action to be taken. This is a similar behaviour to switch statements in Rust, which also have to handle all possible cases.\n\n\n2.1.2.2 The else branch\nTake a look at the dump_hex_fallible() function below as an example. This function comes from the Zig Standard Library. More precisely, from the debug.zig module1. There are multiple lines in this function, but I omitted them to focus solely on the switch statement found in this function. Notice that this switch statement has four possible cases (i.e. four explicit branches). Also, notice that we used an else branch in this case.\nAn else branch in a switch statement works as the “default branch”. Whenever you have multiple cases in your switch statement where you want to apply the exact same action, you can use an else branch to do that.\n\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' =&gt; try writer.writeAll(\"␊\"),\n        '\\r' =&gt; try writer.writeAll(\"␍\"),\n        '\\t' =&gt; try writer.writeAll(\"␉\"),\n        else =&gt; try writer.writeByte('.'),\n    }\n}\n\nMany programmers would also use an else branch to handle a “not supported” case. That is, a case that cannot be properly handled by your code, or, just a case that should not be “fixed”. Therefore, you can use an else branch to panic (or raise an error) in your program to stop the current execution.\nTake the code example below. We can see that, we are handling the cases for the level object being either 1, 2, or 3. All other possible cases are not supported by default, and, as consequence, we raise a runtime error in such cases through the @panic() built-in function.\nAlso notice that, we are assigning the result of the switch statement to a new object called category. This is another thing that you can do with switch statements in Zig. If a branch outputs a value as result, you can store the result value of the switch statement into a new object.\n\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 =&gt; \"beginner\",\n    3 =&gt; \"professional\",\n    else =&gt; {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n\n\n2.1.2.3 Using ranges in switch\nFurthermore, you can also use ranges of values in switch statements. That is, you can create a branch in your switch statement that is used whenever the input value is within the specified range. These “range expressions” are created with the operator .... It is important to emphasize that the ranges created by this operator are inclusive on both ends.\nFor example, I could easily change the previous code example to support all levels between 0 and 100. Like this:\n\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 =&gt; \"beginner\",\n    26...75 =&gt; \"intermediary\",\n    76...100 =&gt; \"professional\",\n    else =&gt; {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n\nbeginner\n\n\nThis is neat, and it works with character ranges too. That is, I could simply write 'a'...'z', to match any character value that is a lowercase letter, and it would work fine.\n\n\n2.1.2.4 Labeled switch statements\nIn Section 1.7 we have talked about labeling blocks, and also, about using these labels to return a value from the block. Well, from version 0.14.0 and onwards of the zig compiler, you can also apply labels over switch statements, which makes it possible to almost implement a “C goto” like pattern.\nFor example, if you give the label xsw to a switch statement, you can use this label in conjunction with the continue keyword to go back to the beginning of the switch statement. In the example below, the execution goes back to the beginning of the switch statement two times, before ending at the 3 branch.\n\nxsw: switch (@as(u8, 1)) {\n    1 =&gt; {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 =&gt; continue :xsw 3,\n    3 =&gt; return,\n    4 =&gt; {},\n    else =&gt; {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n\n\n\n\n2.1.3 The defer keyword\nWith the defer keyword you can register an expression to be executed when you exit the current scope. Therefore, this keyword has a similar functionality as the on.exit() function from R. Take the foo() function below as an example. When we execute this foo() function, the expression that prints the message “Exiting function …” is getting executed only when the function exits its scope.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n\nAdding some numbers ...\nMultiplying ...\nExiting function ...\nTherefore, we can use defer to declare an expression that is going to be executed when your code exits the current scope. Some programmers like to interpret the phrase “exit of the current scope” as “the end of the current scope”. But this interpretation might not be entirely correct, depending on what you consider as “the end of the current scope”.\nI mean, what do you consider as the end of the current scope? Is it the closing curly bracket (}) of the scope? Is it when the last expression in the function get’s executed? Is it when the function returns to the previous scope? Etc. For example, it would not be correct to interpret the “exit of the current scope” as the closing curly bracket of the scope. Because the function might exit from an earlier position than this closing curly bracket (e.g. an error value was generated at a previous line inside the function; the function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\nNow, if you remember of what we have discussed in Section 1.7, there are multiple structures in the language that create their own separate scopes. For/while loops, if/else statements, functions, normal blocks, etc. This also affects the interpretation of defer. For example, if you use defer inside a for loop, then, the given expression will be executed everytime this specific for loop exits its own scope.\nBefore we continue, is worth emphasizing that the defer keyword is an “unconditional defer”. Which means that the given expression will be executed no matter how the code exits the current scope. For example, your code might exit the current scope because of an error value being generated, or, because of a return statement, or, a break statement, etc.\n\n\n2.1.4 The errdefer keyword\nOn the previous section, we have discussed the defer keyword, which you can use to register an expression to be executed at the exit of the current scope. But this keyword has a brother, which is the errdefer keyword. While defer is an “unconditional defer”, the errdefer keyword is a “conditional defer”. Which means that the given expression is executed only when you exit the current scope on a very specific circumstance.\nIn more details, the expression given to errdefer is executed only when an error occurs in the current scope. Therefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope in a normal situation, without errors, the expression given to errdefer is not executed.\nThis makes the errdefer keyword one of the many tools available in Zig for error handling. In this section, we are more concerned with the control flow aspects around errdefer. But we are going to discuss errdefer later as a error handling tool in Section 10.2.4.\nThe code example below demonstrates three things:\n\nthat defer is an “unconditional defer”, because the given expression get’s executed regardless of how the function foo() exits its own scope.\nthat errdefer is executed because the function foo() returned an error value.\nthat defer and errdefer expressions are executed in a LIFO (last in, first out) order.\n\n\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\nWhen I say that “defer expressions” are executed in a LIFO order, what I want to say is that the last defer or errdefer expressions in the code are the first ones to be executed. You could also interpret this as: “defer expressions” are executed from bottom to top, or, from last to first.\nTherefore, if I change the order of the defer and errdefer expressions, you will notice that the value of i that get’s printed to the console changes to 1. This doesn’t mean that the defer expression was not executed in this case. This actually means that the defer expression was executed only after the errdefer expression. The code example below demonstrates this:\n\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n\n\n2.1.5 For loops\nA loop allows you to execute the same lines of code multiple times, thus, creating a “repetition space” in the execution flow of your program. Loops are particularly useful when we want to replicate the same function (or the same set of commands) over different inputs.\nThere are different types of loops available in Zig. But the most essential of them all is probably the for loop. A for loop is used to apply the same piece of code over the elements of a slice, or, an array.\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from other languages. You start with the for keyword, then, you list the items that you want to iterate over inside a pair of parentheses. Then, inside of a pair of pipes (|) you should declare an identifier that will serve as your iterator, or, the “repetition index of the loop”.\n\nfor (items) |value| {\n    // code to execute\n}\n\nTherefore, instead of using a (value in items) syntax, in Zig, for loops use the syntax (items) |value|. In the example below, you can see that we are looping through the items of the array stored at the object name, and printing to the console the decimal representation of each character in this array.\nIf we wanted, we could also iterate through a slice (or a portion) of the array, instead of iterating through the entire array stored in the name object. Just use a range selector to select the section you want. For example, I could provide the expression name[0..3] to the for loop, to iterate just through the first 3 elements in the array.\n\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n\n80 | 101 | 100 | 114 | 111 | \n\n\nIn the above example we are using the value itself of each element in the array as our iterator. But there are many situations where we need to use an index instead of the actual values of the items.\nYou can do that by providing a second set of items to iterate over. More precisely, you provide the range selector 0.. to the for loop. So, yes, you can use two different iterators at the same time in a for loop in Zig.\nBut remember from Section 1.4 that, every object you create in Zig must be used in some way. So if you declare two iterators in your for loop, you must use both iterators inside the for loop body. But if you want to use just the index iterator, and not use the “value iterator”, then, you can discard the value iterator by maching the value items to the underscore character, like in the example below:\n\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n\n0 | 1 | 2 | 3 | 4 |\n\n\n2.1.6 While loops\nA while loop is created from the while keyword. A for loop iterates through the items of an array, but a while loop will loop continuously, and infinitely, until a logical test (specified by you) becomes false.\nYou start with the while keyword, then, you define a logical expression inside a pair of parentheses, and the body of the loop is provided inside a pair of curly braces, like in the example below:\n\nvar i: u8 = 1;\nwhile (i &lt; 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n\n1 | 2 | 3 | 4 | \n\n\nYou can also specify the increment expression to be used at the beginning of a while loop. To do that, we write the increment expression inside a pair of parentheses after a colon character (:). The code example below demonstrates this other pattern.\n\nvar i: u8 = 1;\nwhile (i &lt; 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n\n1 | 2 | 3 | 4 | \n\n\n\n\n2.1.7 Using break and continue\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using the keywords break and continue, respectively. The while loop presented in the next code example is, at first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to true. But what makes this while loop stop when the i object reaches the count 10? It is the break keyword!\nInside the while loop, we have an if statement that is constantly checking if the i variable is equal to 10. Since we are incrementing the value of i at each iteration of the while loop, this i object will eventually be equal to 10, and when it is, the if statement will execute the break expression, and, as a result, the execution of the while loop is stopped.\nNotice the use of the expect() function from the Zig Standard Library after the while loop. This expect() function is an “assert” type of function. This function checks if the logical test provided is equal to true. If so, the function do nothing. Otherwise (i.e. the logical test is equal to false), the function raises an assertion error.\n\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n\nEverything worked!\n\n\nSince this code example was executed successfully by the zig compiler, without raising any errors, we known that, after the execution of the while loop, the i object is equal to 10. Because if it wasn’t equal to 10, an error would have been raised by expect().\nNow, in the next example, we have a use case for the continue keyword. The if statement is constantly checking if the current index is a multiple of 2. If it is, we jump to the next iteration of the loop. Otherwise, the loop just prints the current index to the console.\n\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n\n1 | 3 | 5 |",
+    "text": "2.1.1 If/else statements\nAn if/else statement performs a “conditional flow operation”. A conditional flow control (or choice control) allows you to execute or ignore a certain block of commands based on a logical condition. Many programmers and computer science professionals also use the term “branching” in this case. In essence, an if/else statement allow us to use the result of a logical test to decide whether or not to execute a given block of commands.\nIn Zig, we write if/else statements by using the keywords if and else. We start with the if keyword followed by a logical test inside a pair of parentheses, followed by a pair of curly braces which contains the lines of code to be executed in case the logical test returns the value true.\nAfter that, you can optionally add an else statement. To do that, just add the else keyword followed by a pair of curly braces, with the lines of code to executed in case the logical test defined at if returns false.\nIn the example below, we are testing if the object x contains a number that is greater than 10. Judging by the output printed to the console, we know that this logical test returned false. Because the output in the console is compatible with the line of code present in the else branch of the if/else statement.\n\nconst x = 5;\nif (x &gt; 10) {\n    try stdout.print(\n        \"x &gt; 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x &lt;= 10!\\n\", .{}\n    );\n}\n\nx &lt;= 10!\n\n\n\n\n2.1.2 Switch statements\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust. As you would expect, to write a switch statement in Zig we use the switch keyword. We provide the value that we want to “switch over” inside a pair of parentheses. Then, we list the possible combinations (or “branches”) inside a pair of curly braces.\nLet’s take a look at the code example below. You can see that I’m creating an enum type called Role. We talk more about enums in Section 7.6. But in summary, this Role type is listing different types of roles in a fictitious company, like SE for Software Engineer, DE for Data Engineer, PM for Product Manager, etc.\nNotice that we are using the value from the role object in the switch statement, to discover which exact area we need to store in the area variable object. Also notice that we are using type inference inside the switch statement, with the dot character, as we are going to describe in Section 2.4. This makes the zig compiler infer the correct data type of the values (PM, SE, etc.) for us.\nAlso notice that, we are grouping multiple values in the same branch of the switch statement. We just separate each possible value with a comma. For example, if role contains either DE or DA, the area variable would contain the value \"Data & Analytics\", instead of \"Platform\" or \"Sales\".\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO =&gt; {\n            area = \"Platform\";\n        },\n        .DE, .DA =&gt; {\n            area = \"Data & Analytics\";\n        },\n        .KS =&gt; {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n\nPlatform\n\n\n\n2.1.2.1 Switch statements must exhaust all possibilities\nOne very important aspect about switch statements in Zig is that they must exhaust all existing possibilities. In other words, all possible values that could be found inside the role object must be explicitly handled in this switch statement.\nSince the role object has type Role, the only possible values to be found inside this object are PM, SE, DPE, PO, DE, DA and KS. There are no other possible values to be stored in this role object. Thus, the switch statements must have a combination (branch) for each one of these values. This is what “exhaust all existing possibilities” means. The switch statement covers every possible case.\nTherefore, you cannot write a switch statement in Zig, and leave an edge case with no explicit action to be taken. This is a similar behaviour to switch statements in Rust, which also have to handle all possible cases.\n\n\n2.1.2.2 The else branch\nTake a look at the dump_hex_fallible() function below as an example. This function comes from the Zig Standard Library. More precisely, from the debug.zig module1. There are multiple lines in this function, but I omitted them to focus solely on the switch statement found in this function. Notice that this switch statement has four possible cases (i.e. four explicit branches). Also, notice that we used an else branch in this case.\nAn else branch in a switch statement works as the “default branch”. Whenever you have multiple cases in your switch statement where you want to apply the exact same action, you can use an else branch to do that.\n\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' =&gt; try writer.writeAll(\"␊\"),\n        '\\r' =&gt; try writer.writeAll(\"␍\"),\n        '\\t' =&gt; try writer.writeAll(\"␉\"),\n        else =&gt; try writer.writeByte('.'),\n    }\n}\n\nMany programmers would also use an else branch to handle a “not supported” case. That is, a case that cannot be properly handled by your code, or, just a case that should not be “fixed”. Therefore, you can use an else branch to panic (or raise an error) in your program to stop the current execution.\nTake the code example below. We can see that, we are handling the cases for the level object being either 1, 2, or 3. All other possible cases are not supported by default, and, as consequence, we raise a runtime error in such cases through the @panic() built-in function.\nAlso notice that, we are assigning the result of the switch statement to a new object called category. This is another thing that you can do with switch statements in Zig. If a branch outputs a value as result, you can store the result value of the switch statement into a new object.\n\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 =&gt; \"beginner\",\n    3 =&gt; \"professional\",\n    else =&gt; {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n\n\n2.1.2.3 Using ranges in switch\nFurthermore, you can also use ranges of values in switch statements. That is, you can create a branch in your switch statement that is used whenever the input value is within the specified range. These “range expressions” are created with the operator .... It is important to emphasize that the ranges created by this operator are inclusive on both ends.\nFor example, I could easily change the previous code example to support all levels between 0 and 100. Like this:\n\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 =&gt; \"beginner\",\n    26...75 =&gt; \"intermediary\",\n    76...100 =&gt; \"professional\",\n    else =&gt; {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n\nbeginner\n\n\nThis is neat, and it works with character ranges too. That is, I could simply write 'a'...'z', to match any character value that is a lowercase letter, and it would work fine.\n\n\n2.1.2.4 Labeled switch statements\nIn Section 1.7 we have talked about labeling blocks, and also, about using these labels to return a value from the block. Well, from version 0.14.0 and onwards of the zig compiler, you can also apply labels over switch statements, which makes it possible to almost implement a “C goto” like pattern.\nFor example, if you give the label xsw to a switch statement, you can use this label in conjunction with the continue keyword to go back to the beginning of the switch statement. In the example below, the execution goes back to the beginning of the switch statement two times, before ending at the 3 branch.\n\nxsw: switch (@as(u8, 1)) {\n    1 =&gt; {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 =&gt; continue :xsw 3,\n    3 =&gt; return,\n    4 =&gt; {},\n    else =&gt; {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n\n\n\n\n2.1.3 The defer keyword\nWith the defer keyword you can register an expression to be executed when you exit the current scope. Therefore, this keyword has a similar functionality as the on.exit() function from R. Take the foo() function below as an example. When we execute this foo() function, the expression that prints the message “Exiting function …” is getting executed only when the function exits its scope.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n\nAdding some numbers ...\nMultiplying ...\nExiting function ...\nTherefore, we can use defer to declare an expression that is going to be executed when your code exits the current scope. Some programmers like to interpret the phrase “exit of the current scope” as “the end of the current scope”. But this interpretation might not be entirely correct, depending on what you consider as “the end of the current scope”.\nI mean, what do you consider as the end of the current scope? Is it the closing curly bracket (}) of the scope? Is it when the last expression in the function get’s executed? Is it when the function returns to the previous scope? Etc. For example, it would not be correct to interpret the “exit of the current scope” as the closing curly bracket of the scope. Because the function might exit from an earlier position than this closing curly bracket (e.g. an error value was generated at a previous line inside the function; the function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\nNow, if you remember of what we have discussed in Section 1.7, there are multiple structures in the language that create their own separate scopes. For/while loops, if/else statements, functions, normal blocks, etc. This also affects the interpretation of defer. For example, if you use defer inside a for loop, then, the given expression will be executed everytime this specific for loop exits its own scope.\nBefore we continue, is worth emphasizing that the defer keyword is an “unconditional defer”. Which means that the given expression will be executed no matter how the code exits the current scope. For example, your code might exit the current scope because of an error value being generated, or, because of a return statement, or, a break statement, etc.\n\n\n2.1.4 The errdefer keyword\nOn the previous section, we have discussed the defer keyword, which you can use to register an expression to be executed at the exit of the current scope. But this keyword has a brother, which is the errdefer keyword. While defer is an “unconditional defer”, the errdefer keyword is a “conditional defer”. Which means that the given expression is executed only when you exit the current scope on a very specific circumstance.\nIn more details, the expression given to errdefer is executed only when an error occurs in the current scope. Therefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope in a normal situation, without errors, the expression given to errdefer is not executed.\nThis makes the errdefer keyword one of the many tools available in Zig for error handling. In this section, we are more concerned with the control flow aspects around errdefer. But we are going to discuss errdefer later as a error handling tool in Section 10.2.4.\nThe code example below demonstrates three things:\n\nthat defer is an “unconditional defer”, because the given expression get’s executed regardless of how the function foo() exits its own scope.\nthat errdefer is executed because the function foo() returned an error value.\nthat defer and errdefer expressions are executed in a LIFO (last in, first out) order.\n\n\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\nWhen I say that “defer expressions” are executed in a LIFO order, what I want to say is that the last defer or errdefer expressions in the code are the first ones to be executed. You could also interpret this as: “defer expressions” are executed from bottom to top, or, from last to first.\nTherefore, if I change the order of the defer and errdefer expressions, you will notice that the value of i that get’s printed to the console changes to 1. This doesn’t mean that the defer expression was not executed in this case. This actually means that the defer expression was executed only after the errdefer expression. The code example below demonstrates this:\n\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n\n\n2.1.5 For loops\nA loop allows you to execute the same lines of code multiple times, thus, creating a “repetition space” in the execution flow of your program. Loops are particularly useful when we want to replicate the same function (or the same set of commands) over different inputs.\nThere are different types of loops available in Zig. But the most essential of them all is probably the for loop. A for loop is used to apply the same piece of code over the elements of a slice, or, an array.\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from other languages. You start with the for keyword, then, you list the items that you want to iterate over inside a pair of parentheses. Then, inside of a pair of pipes (|) you should declare an identifier that will serve as your iterator, or, the “repetition index of the loop”.\n\nfor (items) |value| {\n    // code to execute\n}\n\nTherefore, instead of using a (value in items) syntax, in Zig, for loops use the syntax (items) |value|. In the example below, you can see that we are looping through the items of the array stored at the object name, and printing to the console the decimal representation of each character in this array.\nIf we wanted, we could also iterate through a slice (or a portion) of the array, instead of iterating through the entire array stored in the name object. Just use a range selector to select the section you want. For example, I could provide the expression name[0..3] to the for loop, to iterate just through the first 3 elements in the array.\n\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n\n80 | 101 | 100 | 114 | 111 | \n\n\nIn the above example we are using the value itself of each element in the array as our iterator. But there are many situations where we need to use an index instead of the actual values of the items.\nYou can do that by providing a second set of items to iterate over. More precisely, you provide the range selector 0.. to the for loop. So, yes, you can use two different iterators at the same time in a for loop in Zig.\nBut remember from Section 1.4 that, every object you create in Zig must be used in some way. So if you declare two iterators in your for loop, you must use both iterators inside the for loop body. But if you want to use just the index iterator, and not use the “value iterator”, then, you can discard the value iterator by maching the value items to the underscore character, like in the example below:\n\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n\n0 | 1 | 2 | 3 | 4 |\n\n\n2.1.6 While loops\nA while loop is created from the while keyword. A for loop iterates through the items of an array, but a while loop will loop continuously, and infinitely, until a logical test (specified by you) becomes false.\nYou start with the while keyword, then, you define a logical expression inside a pair of parentheses, and the body of the loop is provided inside a pair of curly braces, like in the example below:\n\nvar i: u8 = 1;\nwhile (i &lt; 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n\n1 | 2 | 3 | 4 | \n\n\nYou can also specify the increment expression to be used at the beginning of a while loop. To do that, we write the increment expression inside a pair of parentheses after a colon character (:). The code example below demonstrates this other pattern.\n\nvar i: u8 = 1;\nwhile (i &lt; 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n\n1 | 2 | 3 | 4 | \n\n\n\n\n2.1.7 Using break and continue\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using the keywords break and continue, respectively. The while loop presented in the next code example is, at first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to true. But what makes this while loop stop when the i object reaches the count 10? It is the break keyword!\nInside the while loop, we have an if statement that is constantly checking if the i variable is equal to 10. Since we are incrementing the value of i at each iteration of the while loop, this i object will eventually be equal to 10, and when it is, the if statement will execute the break expression, and, as a result, the execution of the while loop is stopped.\nNotice the use of the expect() function from the Zig Standard Library after the while loop. This expect() function is an “assert” type of function. This function checks if the logical test provided is equal to true. If so, the function do nothing. Otherwise (i.e. the logical test is equal to false), the function raises an assertion error.\n\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n\nEverything worked!\n\n\nSince this code example was executed successfully by the zig compiler, without raising any errors, we known that, after the execution of the while loop, the i object is equal to 10. Because if it wasn’t equal to 10, an error would have been raised by expect().\nNow, in the next example, we have a use case for the continue keyword. The if statement is constantly checking if the current index is a multiple of 2. If it is, we jump to the next iteration of the loop. Otherwise, the loop just prints the current index to the console.\n\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n\n1 | 3 | 5 |",
     "crumbs": [
       "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
     ]
@@ -274,7 +274,7 @@
     "href": "Chapters/03-structs.html#sec-type-cast",
     "title": "2  Control flow, structs, modules and types",
     "section": "2.5 Type casting",
-    "text": "2.5 Type casting\nIn this section, I want to discuss type casting (or, type conversion) with you. We use type casting when we have an object of type “x”, and we want to convert it into an object of type “y”, i.e. we want to change the data type of the object.\nMost languages have a formal way to perform type casting. In Rust for example, we normally use the keyword as, and in C, we normally use the type casting syntax, e.g. (int) x. In Zig, we use the @as() built-in function to cast an object of type “x”, into an object of type “y”.\nThis @as() function is the preferred way to perform type conversion (or type casting) in Zig. Because it is explicit, and, it also performs the casting only if it is unambiguous and safe. To use this function, you just provide the target data type in the first argument, and, the object that you want cast as the second argument.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n\n1/1 file10b91234368fa.test_0...OKAll 1 tests passe\n  ed.\n\n\nThis is the general way to perform type casting in Zig. But remember, @as() works only when casting is unambiguous and safe, and there are situations where these assumptions do not hold. For example, when casting an integer value into a float value, or vice-versa, it is not clear to the compiler how to perform this conversion safely.\nTherefore, we need to use specialized “casting functions” in such situations. For example, if you want to cast an integer value into a float value, then, you should use the @floatFromInt() function. In the inverse scenario, you should use the @intFromFloat() function.\nIn these functions, you just provide the object that you want to cast as input. Then, the target data type of the “type casting operation” is determined by the type annotation of the object where you are saving the results. In the example below, we are casting the object x into a value of type f32, because the object y, which is where we are saving the results, is annotated as an object of type f32.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n\n1/1 file10b9130ae9221.test_0...OKAll 1 tests passe\n  ed.\n\n\nAnother built-in function that is very useful when performing type casting operations is @ptrCast(). In essence, we use the @as() built-in function when we want to explicit convert (or cast) a Zig value/object from a type “x” to a type “y”, etc. However, pointers (we are going to discuss pointers in more depth in Chapter 6) are a special type of object in Zig, i.e. they are treated differently from “normal objects”.\nEverytime a pointer is involved in some “type casting operation” in Zig, the @ptrCast() function is used. This function works similarly to @floatFromInt(). You just provide the pointer object that you want to cast as input to this function, and the target data type is, once again, determined by the type annotation of the object where the results are being stored.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n\n1/1 file10b914c434861.test_0...OKAll 1 tests passe\n  ed.",
+    "text": "2.5 Type casting\nIn this section, I want to discuss type casting (or, type conversion) with you. We use type casting when we have an object of type “x”, and we want to convert it into an object of type “y”, i.e. we want to change the data type of the object.\nMost languages have a formal way to perform type casting. In Rust for example, we normally use the keyword as, and in C, we normally use the type casting syntax, e.g. (int) x. In Zig, we use the @as() built-in function to cast an object of type “x”, into an object of type “y”.\nThis @as() function is the preferred way to perform type conversion (or type casting) in Zig. Because it is explicit, and, it also performs the casting only if it is unambiguous and safe. To use this function, you just provide the target data type in the first argument, and, the object that you want cast as the second argument.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n\n1/1 filecdc41797a754.test_0...OKAll 1 tests passed\n  d.\n\n\nThis is the general way to perform type casting in Zig. But remember, @as() works only when casting is unambiguous and safe, and there are situations where these assumptions do not hold. For example, when casting an integer value into a float value, or vice-versa, it is not clear to the compiler how to perform this conversion safely.\nTherefore, we need to use specialized “casting functions” in such situations. For example, if you want to cast an integer value into a float value, then, you should use the @floatFromInt() function. In the inverse scenario, you should use the @intFromFloat() function.\nIn these functions, you just provide the object that you want to cast as input. Then, the target data type of the “type casting operation” is determined by the type annotation of the object where you are saving the results. In the example below, we are casting the object x into a value of type f32, because the object y, which is where we are saving the results, is annotated as an object of type f32.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n\n1/1 filecdc428638149.test_0...OKAll 1 tests passed\n  d.\n\n\nAnother built-in function that is very useful when performing type casting operations is @ptrCast(). In essence, we use the @as() built-in function when we want to explicit convert (or cast) a Zig value/object from a type “x” to a type “y”, etc. However, pointers (we are going to discuss pointers in more depth in Chapter 6) are a special type of object in Zig, i.e. they are treated differently from “normal objects”.\nEverytime a pointer is involved in some “type casting operation” in Zig, the @ptrCast() function is used. This function works similarly to @floatFromInt(). You just provide the pointer object that you want to cast as input to this function, and the target data type is, once again, determined by the type annotation of the object where the results are being stored.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n\n1/1 filecdc46f71cc03.test_0...OKAll 1 tests passed\n  d.",
     "crumbs": [
       "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
     ]

From 91ebf325e129c8bc4666aab2b336cf3b6007b191 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Fri, 31 Jan 2025 08:37:05 -0400
Subject: [PATCH 034/151] fix: change his to its

---
 Chapters/01-memory.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/01-memory.qmd b/Chapters/01-memory.qmd
index 0c4de856..c2d329a5 100644
--- a/Chapters/01-memory.qmd
+++ b/Chapters/01-memory.qmd
@@ -121,7 +121,7 @@ For example, the function `input_length()` contains an argument named `input`, w
 It is impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length
 of this particular argument. Because it is an array that do not have a fixed size specified explicitly in the argument type annotation.
 
-So, we know that this `input` argument will be an array of `u8` integers. But we do not know at compile-time, its value, and neither his size.
+So, we know that this `input` argument will be an array of `u8` integers. But we do not know at compile-time, its value, and neither its size.
 This information is known only at runtime, which is the period of time when you program is executed.
 As a consequence, the value of the expression `input.len` is also known only at runtime.
 This is an intrinsic characteristic of any function. Just remember that the value of function arguments is usually not "compile-time known".

From c30ce1c4e62a6b498eae7ff62b7276f61063f758 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Fri, 31 Jan 2025 08:43:29 -0400
Subject: [PATCH 035/151] fix: remove apostrophe

---
 Chapters/01-memory.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/01-memory.qmd b/Chapters/01-memory.qmd
index c2d329a5..8d3678f7 100644
--- a/Chapters/01-memory.qmd
+++ b/Chapters/01-memory.qmd
@@ -151,7 +151,7 @@ It simply exists in your program.
 
 ### Stack vs Heap
 
-If you are familiar with system's programming, or just low-level programming in general, you
+If you are familiar with systems programming, or just low-level programming in general, you
 probably have heard of the "duel" between Stack vs Heap. These are two different types of memory,
 or different memory spaces, which are both available in Zig.
 

From a62e7a1ee12cac32f046cddfa7c8cde126eeff62 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Fri, 31 Jan 2025 08:49:19 -0400
Subject: [PATCH 036/151] fix: change have to has

---
 Chapters/01-memory.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/01-memory.qmd b/Chapters/01-memory.qmd
index 8d3678f7..fd8870d0 100644
--- a/Chapters/01-memory.qmd
+++ b/Chapters/01-memory.qmd
@@ -242,7 +242,7 @@ freed/destroyed at the end of the function scope.
 :::
 
 
-This same logic applies to any other special structure in Zig that have its own scope by surrounding
+This same logic applies to any other special structure in Zig that has its own scope by surrounding
 it with curly braces (`{}`).
 For loops, while loops, if else statements, etc. For example, if you declare any local
 object in the scope of a for loop, this local object is accessible only within the scope

From f152e22ee31d23abdfe05f0d6627101203548669 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Fri, 31 Jan 2025 08:53:14 -0400
Subject: [PATCH 037/151] fix: change very to well

---
 Chapters/01-memory.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/01-memory.qmd b/Chapters/01-memory.qmd
index fd8870d0..91c90b57 100644
--- a/Chapters/01-memory.qmd
+++ b/Chapters/01-memory.qmd
@@ -314,7 +314,7 @@ pub fn main() !void {
 }
 ```
 
-This "invalid pointer to stack variable" problem is very known across many programming language communities.
+This "invalid pointer to stack variable" problem is well known across many programming language communities.
 If you try to do the same thing, for example, in a C or C++ program (i.e. returning an address to
 a local object stored in the stack), you would also get undefined behaviour
 in the program.

From 4301b0d69a98b2819dabd6efcb824e52dddd5bde Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Fri, 31 Jan 2025 08:56:52 -0400
Subject: [PATCH 038/151] fix: refine wording

---
 Chapters/01-memory.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/01-memory.qmd b/Chapters/01-memory.qmd
index 91c90b57..597b0073 100644
--- a/Chapters/01-memory.qmd
+++ b/Chapters/01-memory.qmd
@@ -327,7 +327,7 @@ is destroyed at the end of its scope.
 :::
 
 But what if you really need to use this local object in some way after your function returns?
-How can you do this? The answer is: "in the same you would do if this was a C or C++ program. By returning
+How can you do this? The answer is: "in the same way you would do if this were a C or C++ program. By returning
 an address to an object stored in the heap". The heap memory has a much more flexible lifecycle,
 and allows you to get a valid pointer to a local object of a function that already returned
 from its scope.

From 49bafcdf09be8e6ebef6a3a2759717decda4e028 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Fri, 31 Jan 2025 09:00:01 -0400
Subject: [PATCH 039/151] fix: change sentence to reduce 'or' usage

---
 Chapters/01-memory.qmd | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Chapters/01-memory.qmd b/Chapters/01-memory.qmd
index 597b0073..aff78342 100644
--- a/Chapters/01-memory.qmd
+++ b/Chapters/01-memory.qmd
@@ -346,8 +346,8 @@ In summary, a server is a type of application that runs for long periods of time
 and that serves (or "deals with") any incoming request that reaches this particular server.
 
 The heap is a good choice for this type of system, mainly because the server does not know upfront
-how many requests it will receive from users, while it is active. It could be one single request,
-or, 5 thousand requests, or, it could also be zero requests.
+how many requests it will receive from users, while it is active. It could be a single request,
+5 thousand requests, or even zero requests.
 The server needs to have the ability to allocate and manage its memory according to how many requests it receives.
 
 Another key difference between the stack and the heap, is that the heap is a type

From d50c9da4afe091a91d09e9c59c4fa3b0b35030b7 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Fri, 31 Jan 2025 09:05:19 -0400
Subject: [PATCH 040/151] fix: change 'he' to 'it'

---
 Chapters/01-memory.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/01-memory.qmd b/Chapters/01-memory.qmd
index aff78342..9fa7a376 100644
--- a/Chapters/01-memory.qmd
+++ b/Chapters/01-memory.qmd
@@ -386,7 +386,7 @@ object you declare is stored:
 1. every constant object (`const`) whose value **is known at compile-time** is also stored in the global data section.
 1. every object (constant or not) whose length/size **is known at compile time** is stored in the stack space for the current scope.
 1. if an object is created with the method `alloc()` or `create()` of an allocator object, this object is stored in the memory space used by this particular allocator object. Most of allocators available in Zig use the heap memory, so, this object is likely stored in the heap (`FixedBufferAllocator()` is an exception to that).
-1. the heap can only be accessed through allocators. If your object was not created through the `alloc()` or `create()` methods of an allocator object, then, he is most certainly not an object stored in the heap.
+1. the heap can only be accessed through allocators. If your object was not created through the `alloc()` or `create()` methods of an allocator object, then, it is most certainly not an object stored in the heap.
 
 
 ## Stack overflows {#sec-stack-overflow}

From d474f213d92cd92299568d02746edc39e9e76c91 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Fri, 31 Jan 2025 09:07:57 -0400
Subject: [PATCH 041/151] fix grammar in overflow explanation

---
 Chapters/01-memory.qmd | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Chapters/01-memory.qmd b/Chapters/01-memory.qmd
index 9fa7a376..97c8ac9d 100644
--- a/Chapters/01-memory.qmd
+++ b/Chapters/01-memory.qmd
@@ -405,8 +405,8 @@ a *stack overflow* happens, and your program just crashes as a result of that. I
 you attempt to use more space than is available on the stack.
 
 This type of problem is very similar to a *buffer overflow*, i.e. you are trying to use more space
-than is available in the "buffer object". However, a stack overflow always cause your program to crash,
-while a buffer overflow not always cause your program to crash (although it often does).
+than is available in the "buffer object". However, a stack overflow always causes your program to crash,
+while a buffer overflow does not always cause your program to crash (although it often does).
 
 You can see an example of a stack overflow in the example below. We are trying to allocate a very big array of `u64` values
 on the stack. You can see below that this program does not run succesfully, because it crashed

From b941732945a3118bfae7286b8c527ce4b990c397 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Fri, 31 Jan 2025 09:09:27 -0400
Subject: [PATCH 042/151] fix: correct spelling of 'successfully' in error
 message explanation

---
 Chapters/01-memory.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/01-memory.qmd b/Chapters/01-memory.qmd
index 97c8ac9d..f7cc8ca8 100644
--- a/Chapters/01-memory.qmd
+++ b/Chapters/01-memory.qmd
@@ -409,7 +409,7 @@ than is available in the "buffer object". However, a stack overflow always cause
 while a buffer overflow does not always cause your program to crash (although it often does).
 
 You can see an example of a stack overflow in the example below. We are trying to allocate a very big array of `u64` values
-on the stack. You can see below that this program does not run succesfully, because it crashed
+on the stack. You can see below that this program does not run successfully, because it crashed
 with a "segmentation fault" error message.
 
 ```{zig}

From 7c9ad9545ef250f8228ef002877341ecf23139bd Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Fri, 31 Jan 2025 09:16:04 -0400
Subject: [PATCH 043/151] fix: add 'a' before 'new string'

---
 Chapters/01-memory.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/01-memory.qmd b/Chapters/01-memory.qmd
index f7cc8ca8..852a1bdb 100644
--- a/Chapters/01-memory.qmd
+++ b/Chapters/01-memory.qmd
@@ -450,7 +450,7 @@ sure that this function/operator will allocate some memory during its execution.
 
 An example is the `allocPrint()` function from the Zig Standard Library. With this function, you can
 write a new string using format specifiers. So, this function is, for example, very similar to the function `sprintf()` in C.
-In order to write such new string, the `allocPrint()` function needs to allocate some memory to store the
+In order to write such a new string, the `allocPrint()` function needs to allocate some memory to store the
 output string.
 
 That is why, the first argument of this function is an allocator object that you, the user/programmer, gives

From 4da4cbaca835d0cdc8e4c062ba99d01002382960 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Fri, 31 Jan 2025 09:21:41 -0400
Subject: [PATCH 044/151] fix: change 'have' to 'has'

---
 Chapters/01-memory.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/01-memory.qmd b/Chapters/01-memory.qmd
index 852a1bdb..e4368ef1 100644
--- a/Chapters/01-memory.qmd
+++ b/Chapters/01-memory.qmd
@@ -497,7 +497,7 @@ but you don't need to change the function calls to the methods that do the memor
 
 As we described at @sec-stack, everytime you make a function call in Zig,
 a space in the stack is reserved for this function call. But the stack
-has a key limitation which is: every object stored in the stack have a
+has a key limitation which is: every object stored in the stack has a
 known fixed length.
 
 But in reality, there are two very common instances where this "fixed length limitation" of the stack is a deal braker:

From c576540d86543de691866e52d948488ef7708251 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Fri, 31 Jan 2025 09:26:19 -0400
Subject: [PATCH 045/151] fix: grammar in sentence about stack suitability

---
 Chapters/01-memory.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/01-memory.qmd b/Chapters/01-memory.qmd
index e4368ef1..464b4c5b 100644
--- a/Chapters/01-memory.qmd
+++ b/Chapters/01-memory.qmd
@@ -511,7 +511,7 @@ stack. However, if this object is stored in the heap, then, you can return a poi
 end of the function. Because you (the programmer) control the lifetime of any heap memory that you allocate. You decide
 when this memory gets destroyed/freed.
 
-These are common situations where the stack is not good for.
+These are common situations for which the stack is not good. 
 That is why you need a different memory management strategy to
 store these objects inside your function. You need to use
 a memory type that can grow together with your objects, or that you

From bca98a7f6006249adb93b6cdc2e56997440b552d Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Fri, 31 Jan 2025 10:23:46 -0400
Subject: [PATCH 046/151] fix: change 'an' to 'a'

---
 Chapters/01-memory.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/01-memory.qmd b/Chapters/01-memory.qmd
index 464b4c5b..1cd29bd9 100644
--- a/Chapters/01-memory.qmd
+++ b/Chapters/01-memory.qmd
@@ -760,7 +760,7 @@ should use `alloc()` and `free()`. But if you need to store just a single item,
 then, the `create()` and `destroy()` methods are ideal for you.
 
 In the example below, I'm defining a struct to represent an user of some sort.
-It could be an user for a game, or a software to manage resources, it doesn't mater.
+It could be a user for a game, or software to manage resources, it doesn't mater.
 Notice that I use the `create()` method this time, to store a single `User` object
 in the program. Also notice that I use the `destroy()` method to free the memory
 used by this object at the end of the scope.

From 3656ee4f9225338775946041c4ac9c1c09c2dd96 Mon Sep 17 00:00:00 2001
From: loveholly <b.wen@aftership.com>
Date: Sun, 2 Feb 2025 11:24:33 +0800
Subject: [PATCH 047/151] Grammar issue

---
 docs/Chapters/01-zig-weird.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/Chapters/01-zig-weird.html b/docs/Chapters/01-zig-weird.html
index f7360c5b..f46d6fd0 100644
--- a/docs/Chapters/01-zig-weird.html
+++ b/docs/Chapters/01-zig-weird.html
@@ -612,7 +612,7 @@ <h3 data-number="1.4.3" class="anchored" data-anchor-id="there-is-no-such-thing-
 <li>you either use the value of this object;</li>
 <li>or you explicitly discard the value of the object;</li>
 </ol>
-<p>To explicitly discard the value of any object (constant or variable), all you need to do is to assign this object to an special character in Zig, which is the underscore (<code>_</code>). When you assign an object to a underscore, like in the example below, the <code>zig</code> compiler will automatically discard the value of this particular object.</p>
+<p>To explicitly discard the value of any object (constant or variable), all you need to do is to assign this object to a special character in Zig, which is the underscore (<code>_</code>). When you assign an object to a underscore, like in the example below, the <code>zig</code> compiler will automatically discard the value of this particular object.</p>
 <p>You can see in the example below that, this time, the compiler did not complain about any “unused constant”, and successfully compiled our source code.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb27"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb27-1"><a href="#cb27-1" aria-hidden="true" tabindex="-1"></a><span class="co">// It compiles!</span></span>

From c5ca497a8a3ba7fb13ea88e0dc1d6de551adfca8 Mon Sep 17 00:00:00 2001
From: Dima Budaragin <d.budaragin+dev@gmail.com>
Date: Sun, 2 Feb 2025 18:48:48 +0000
Subject: [PATCH 048/151] fix typos

---
 Chapters/01-zig-weird.qmd | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index f0983bf4..5af2822f 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -335,7 +335,7 @@ compilation error will be raised, warning about this mistake.
 
 The `zig` compiler also offers a `build-lib` and `build-obj` commands, which work
 the exact same way as the `build-exe` command. The only difference is that, they compile your
-Zig modules into a portale C ABI library, or, into object files, respectively.
+Zig modules into a portable C ABI library, or, into object files, respectively.
 
 In the case of the `build-exe` command, a binary executable file is created by the `zig`
 compiler in the root directory of your project.
@@ -364,7 +364,7 @@ Hello, world!
 
 ### Compile and execute at the same time {#sec-compile-run-code}
 
-On the previous section, I presented the `zig build-exe` command, which
+In the previous section, I presented the `zig build-exe` command, which
 compiles Zig modules into an executable file. However, this means that,
 in order to execute the executable file, we have to run two different commands.
 First, the `zig build-exe` command, and then, we call the executable file
@@ -386,7 +386,7 @@ Hello, world!
 ### Important note for Windows users
 
 First of all, this is a Windows-specific thing, and, therefore, does not apply to other
-operating systems, such as Linux and macOs. In summary, if you have a piece of Zig code that
+operating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that
 includes some global variables whose initialization rely on runtime resources, then,
 you might have some troubles while trying to compile this Zig code on Windows.
 
@@ -458,7 +458,7 @@ GitHub issues opened at the official Zig repository. More specifically, the issu
 
 ### Compiling the entire project {#sec-compile-project}
 
-Just as I described at @sec-project-files, as our project grows in size and
+Just as I described in @sec-project-files, as our project grows in size and
 complexity, we usually prefer to organize the compilation and build process
 of the project into a build script, using some sort of "build system".
 
@@ -493,7 +493,7 @@ After you execute this "build project" command, a `zig-out` directory
 is created in the root of your project directory, where you can find
 the binary executables and libraries created from your Zig modules
 accordingly to the build commands that you specified at `build.zig`.
-We will talk more about the build system in Zig latter in this book.
+We will talk more about the build system in Zig later in this book.
 
 In the example below, I'm executing the binary executable
 named `hello_world` that was generated by the compiler after the
@@ -554,14 +554,14 @@ codebases, such as:
 [^bunjs]: <https://github.com/oven-sh/bun>.
 
 All these assets are available on GitHub,
-and this is great, because we can use the GitHub search bar in our advantage,
+and this is great, because we can use the GitHub search bar to our advantage,
 to find Zig code that fits our description.
 For example, you can always include `lang:Zig` in the GitHub search bar when you
 are searching for a particular pattern. This will limit the search to only Zig modules.
 
 [^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>
 
-Also, a great alternative is to consult online resources and documentations.
+Also, a great alternative is to consult online resources and documentation.
 Here is a quick list of resources that I personally use from time to time to learn
 more about the language each day:
 
@@ -583,7 +583,7 @@ fix these programs, and make them work again.
 
 [^ziglings]: <https://ziglings.org>.
 
-A famous tech YouTuber known as *The Primeagen* also posted some videos (at YouTube)
+A famous tech YouTuber known as *The Primeagen* also posted some videos (on YouTube)
 where he solves these exercises from Ziglings. The first video is named
 ["Trying Zig Part 1"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].
 

From 254d9b1169bf4b1f643c457fcb0f5a005f4b63c7 Mon Sep 17 00:00:00 2001
From: Alexander Alekhin <sphrand@gmail.com>
Date: Wed, 5 Feb 2025 20:22:08 +0300
Subject: [PATCH 049/151] fix errors in code samples

---
 Chapters/01-base64.qmd    |  9 ++++-----
 Chapters/01-memory.qmd    |  6 +++---
 Chapters/02-debugging.qmd | 12 ++++++------
 3 files changed, 13 insertions(+), 14 deletions(-)

diff --git a/Chapters/01-base64.qmd b/Chapters/01-base64.qmd
index d883696c..fabfc797 100644
--- a/Chapters/01-base64.qmd
+++ b/Chapters/01-base64.qmd
@@ -115,7 +115,7 @@ const Base64 = struct {
         };
     }
 
-    pub fn _char_at(self: Base64, index: u8) u8 {
+    pub fn _char_at(self: Base64, index: usize) u8 {
         return self._table[index];
     }
 };
@@ -175,7 +175,7 @@ to fill the space that it needs. That is why at @fig-base64-algo1, on the third
 2 extra zeros were added to fill the gap in this group.
 
 When we have a 6-bit group that is not completely full, like the third group, extra zeros
-are added to fill the gap. But what about when an entire 6-bit group is empty, or, it 
+are added to fill the gap. But what about when an entire 6-bit group is empty, or, it
 simply doesn't exist? This is the case of the fourth 6-bit group exposed at
 @fig-base64-algo1.
 
@@ -682,10 +682,9 @@ fn _char_index(self: Base64, char: u8) u8 {
         return 64;
     var index: u8 = 0;
     for (0..63) |i| {
-        if (self._char_at(i) == char) {
-            index = i;
+        if (self._char_at(i) == char)
             break;
-        }
+        index += 1;
     }
 
     return index;
diff --git a/Chapters/01-memory.qmd b/Chapters/01-memory.qmd
index 0c4de856..94ce0ecb 100644
--- a/Chapters/01-memory.qmd
+++ b/Chapters/01-memory.qmd
@@ -177,7 +177,7 @@ a dynamic memory space, which can grow or shrink to fit the size of your objects
 
 ### Stack {#sec-stack}
 
-The stack is a type of memory that uses the power of the *stack data structure*, hence the name. 
+The stack is a type of memory that uses the power of the *stack data structure*, hence the name.
 A "stack" is a type of *data structure* that uses a "last in, first out" (LIFO) mechanism to store the values
 you give it to. I imagine you are familiar with this data structure.
 But, if you are not, the [Wikipedia page](https://en.wikipedia.org/wiki/Stack_(abstract_data_type))[^wiki-stack]
@@ -263,7 +263,7 @@ for (0..a.len) |i| {
 // Trying to use an object that was
 // declared in the for loop scope,
 // and that does not exist anymore.
-std.debug.print("{d}\n", index);
+std.debug.print("{d}\n", .{index});
 ```
 
 
@@ -520,7 +520,7 @@ The heap fits this description.
 
 Allocating memory on the heap is commonly known as dynamic memory management. As the objects you create grow in size
 during the execution of your program, you grow the amount of memory
-you have by allocating more memory in the heap to store these objects. 
+you have by allocating more memory in the heap to store these objects.
 And you do that in Zig, by using an allocator object.
 
 
diff --git a/Chapters/02-debugging.qmd b/Chapters/02-debugging.qmd
index 7f3e147a..6329bdea 100644
--- a/Chapters/02-debugging.qmd
+++ b/Chapters/02-debugging.qmd
@@ -94,7 +94,7 @@ fn add(x: u8, y: u8) u8 {
 
 pub fn main() !void {
     const result = add(34, 16);
-    _ = try stdout.print("Result: {d}", .{result});
+    try stdout.print("Result: {d}", .{result});
 }
 ```
 
@@ -128,7 +128,7 @@ then, creating a *writer* object to `stderr`, then, using the `print()` method o
 const std = @import("std");
 const stderr = std.io.getStdErr().writer();
 // some more lines ...
-_ = try stderr.print("Result: {d}", .{result});
+try stderr.print("Result: {d}", .{result});
 ```
 
 
@@ -184,7 +184,7 @@ fn add_and_increment(a: u8, b: u8) u8 {
 pub fn main() !void {
     var n = add_and_increment(2, 3);
     n = add_and_increment(n, n);
-    _ = try stdout.print("Result: {d}!\n", .{n});
+    try stdout.print("Result: {d}!\n", .{n});
 }
 ```
 
@@ -227,7 +227,7 @@ Process 8654 stopped
     stop reason = breakpoint 1.1 frame #0: 0x10341a6
     add_program`debug1.main at add_program.zig:11:30
    8   	}
-   9   	
+   9
    10  	pub fn main() !void {
 -> 11  	    var n = add_and_increment(2, 3);
    12  	    n = add_and_increment(n, n);
@@ -268,7 +268,7 @@ Process 4798 stopped
 * thread #1, name = 'debugging',
     stop reason = step over frame #0: 0x10341ae
     debugging`debug1.main at debug1.zig:12:26
-   9   	
+   9
    10  	pub fn main() !void {
    11  	    var n = add_and_increment(2, 3);
 -> 12  	    n = add_and_increment(n, n);
@@ -327,7 +327,7 @@ But you also have alternatives embedded in the language itself to access the dat
 types of your objects.
 
 In Zig, you can retrieve the data type of an object, by using the built-in function
-`@TypeOf()`. Just apply this function over the object, and you get access to 
+`@TypeOf()`. Just apply this function over the object, and you get access to
 the data type of the object.
 
 ```{zig}

From 85ced25486d2d882b9f5ff8255db8319cbdef685 Mon Sep 17 00:00:00 2001
From: jorge-j1m <68088000+jorge-j1m@users.noreply.github.com>
Date: Fri, 7 Feb 2025 23:58:53 -0500
Subject: [PATCH 050/151] Fix typo in Chapter 1

---
 Chapters/01-zig-weird.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index f0983bf4..298c6f45 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -335,7 +335,7 @@ compilation error will be raised, warning about this mistake.
 
 The `zig` compiler also offers a `build-lib` and `build-obj` commands, which work
 the exact same way as the `build-exe` command. The only difference is that, they compile your
-Zig modules into a portale C ABI library, or, into object files, respectively.
+Zig modules into a portable C ABI library, or, into object files, respectively.
 
 In the case of the `build-exe` command, a binary executable file is created by the `zig`
 compiler in the root directory of your project.

From 37048ebd85bef14d534c5fa7dbb4efb410386c0b Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Sat, 8 Feb 2025 21:43:03 -0400
Subject: [PATCH 051/151] fix: change your to you

---
 Chapters/02-debugging.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/02-debugging.qmd b/Chapters/02-debugging.qmd
index 7f3e147a..b4946bfc 100644
--- a/Chapters/02-debugging.qmd
+++ b/Chapters/02-debugging.qmd
@@ -51,7 +51,7 @@ the Zig Standard Library Official Reference for the type `File`](https://ziglang
 [^zig-fiile-reference]: <https://ziglang.org/documentation/master/std/#std.fs.File>.
 
 For our purpose here, which is to write something to the `stdout`, especially to debug our
-program, I recommend you to use the `writer()` method, which gives your a *writer* object.
+program, I recommend you to use the `writer()` method, which gives you a *writer* object.
 This *writer* object offers some helper methods to write stuff into the file descriptor object
 that represents the `stdout` stream. In special, the `print()` method.
 

From f27eb4791c87113095573337a9e8e9928afb9405 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Sat, 8 Feb 2025 22:02:58 -0400
Subject: [PATCH 052/151] fix: change print to prints

---
 Chapters/02-debugging.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/02-debugging.qmd b/Chapters/02-debugging.qmd
index b4946bfc..cf8614ee 100644
--- a/Chapters/02-debugging.qmd
+++ b/Chapters/02-debugging.qmd
@@ -99,7 +99,7 @@ pub fn main() !void {
 ```
 
 Is important to emphasize that, the `stdout.print()` method, as you would expect,
-print your template string into the `stdout` stream of your system.
+prints your template string into the `stdout` stream of your system.
 However, you can also print your template string into the `stderr` stream
 if your prefer. All you need to do, is to replace the `stdout.print()`
 call with the function `std.debug.print()`. Like this:

From c6bdd042915772118a08e4edd9de9a26016db156 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Sat, 8 Feb 2025 22:04:41 -0400
Subject: [PATCH 053/151] fix: Add a subject to the sentence

---
 Chapters/02-debugging.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/02-debugging.qmd b/Chapters/02-debugging.qmd
index cf8614ee..e5940da3 100644
--- a/Chapters/02-debugging.qmd
+++ b/Chapters/02-debugging.qmd
@@ -98,7 +98,7 @@ pub fn main() !void {
 }
 ```
 
-Is important to emphasize that, the `stdout.print()` method, as you would expect,
+It is important to emphasize that, the `stdout.print()` method, as you would expect,
 prints your template string into the `stdout` stream of your system.
 However, you can also print your template string into the `stderr` stream
 if your prefer. All you need to do, is to replace the `stdout.print()`

From f81cb7130288c1b390efcfd3a2a6efebb2ca13f5 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Sat, 8 Feb 2025 22:13:30 -0400
Subject: [PATCH 054/151] fix: change being to is

---
 Chapters/02-debugging.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/02-debugging.qmd b/Chapters/02-debugging.qmd
index e5940da3..811d5fe3 100644
--- a/Chapters/02-debugging.qmd
+++ b/Chapters/02-debugging.qmd
@@ -135,7 +135,7 @@ _ = try stderr.print("Result: {d}", .{result});
 
 ## Debugging through debuggers
 
-Although *print debugging* being a valid and very useful strategy,
+Although *print debugging* is a valid and very useful strategy,
 most programmers prefer to use a debugger to debug their programs.
 Since Zig is a low-level language, you can use either GDB (GNU Debugger),
 or LLDB (LLVM Project Debugger) as your debugger.

From 77b6549487fa89fba69671cecec2744aac999402 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Sat, 8 Feb 2025 22:26:29 -0400
Subject: [PATCH 055/151] fix: grammar in sentence

---
 Chapters/02-debugging.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/02-debugging.qmd b/Chapters/02-debugging.qmd
index 811d5fe3..1fddaa70 100644
--- a/Chapters/02-debugging.qmd
+++ b/Chapters/02-debugging.qmd
@@ -255,7 +255,7 @@ by using the `p` LLDB command. The syntax for this command is `p <name-of-object
 
 If we take a look at the value stored in the `n` object (`p n`),
 notice that it stores the hexadecimal value `0x06`, which
-is the number 6 in decimal. We can also see that, this value have a type `unsigned char`,
+is the number 6 in decimal. We can also see that this value has a type of `unsigned char`,
 which is an unsigned 8-bit integer.
 We have talked already about this at @sec-zig-strings, that `u8` integers in Zig are equivalent
 to the C data type `unsigned char`.

From 2b7b42ed94279ff16eb95120fca1f40d127a916d Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sun, 9 Feb 2025 10:50:46 -0300
Subject: [PATCH 056/151] Recompile book with changes

---
 _freeze/Chapters/01-zig-weird/execute-results/html.json | 8 +++-----
 docs/Chapters/01-zig-weird.html                         | 2 +-
 docs/search.json                                        | 2 +-
 3 files changed, 5 insertions(+), 7 deletions(-)

diff --git a/_freeze/Chapters/01-zig-weird/execute-results/html.json b/_freeze/Chapters/01-zig-weird/execute-results/html.json
index 28800571..49b461d6 100644
--- a/_freeze/Chapters/01-zig-weird/execute-results/html.json
+++ b/_freeze/Chapters/01-zig-weird/execute-results/html.json
@@ -1,11 +1,9 @@
 {
-  "hash": "507166385ff85ccf512b153b7c107291",
+  "hash": "4ab2f8387f13b3772b2eb726e8e611b5",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\nlanguage, it is still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. They really make it sometimes hard to debug\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscures the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that get's compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e. it is where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contain Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nTherefore, Zig contains a native build system in it, and\nwe can use this build system to write small scripts in Zig,\nwhich describes the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e. creating new objects)\nare made in Zig. You can create a new object in Zig by using the following syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). At @sec-assignments we talk more about objects in general.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that at @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIs worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt is like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portale C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nOn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOs. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e. the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. Thus, if you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith a \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, operations like accessing the `stdout` (or opening a file) on Windows\ndepends on resources that are available only at *runtime* (you will learn more about compile-time\nversus runtime at @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword at @sec-comptime.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation at a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues \n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described at @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig latter in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig? \nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar in our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentations.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It is a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (at YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e. identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nIn contrast, if you use `var`, then, the object created is a variable object.\nWith `var` you can declare this object in your source code, and then,\nchange the value of this object how many times you want over future points\nin your source code.\n\nSo, using the same code example exposed above, if I change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it is an \"variable object\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIs important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code use this object while it is uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object. \n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e. if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to an special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It is discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also get's discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e. the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\nIs worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array. \n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it is a slice that\naccess all elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" at @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth at @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially at @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned at @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e. the start and the end of this range)\nis known at compile-time, the slice object that get's created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nat @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that get's created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e. a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can \ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n```\n:::\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat get's created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, the `slice` object have a runtime known range, because the end index of the range\nis not known at compile time. In other words, the size of the array at `buffer` is not known\nat compile time. When we execute this program, the size of the array might be 10, or, it might be 12\ndepending on where we execute it. Therefore, we don't know at compile time if\nthe slice object have a range of size 10, or, a range of size 12.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e. a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented at @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e. `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIs worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e. the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause it is much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e. if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it is a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIs important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig at @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers at @sec-root-file and especially at @sec-assignments.\n- How strings work in Zig at @sec-zig-strings.\n- How to use arrays and slices at @sec-arrays.\n- How to import functionality from other Zig modules at @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* at @sec-structs-and-oop.\n- Basic control flow syntax at @sec-zig-control-flow.\n- Enums at @sec-enum;\n- Pointers and Optionals at @sec-pointer;\n- Error handling with `try` and `catch` at @sec-error-handling;\n- Unit tests at @sec-unittests;\n- Vectors at @sec-vectors-simd;\n- Build System at @sec-build-system;\n\n\n\n\n",
-    "supporting": [
-      "01-zig-weird_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\nlanguage, it is still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. They really make it sometimes hard to debug\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscures the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that get's compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e. it is where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contain Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nTherefore, Zig contains a native build system in it, and\nwe can use this build system to write small scripts in Zig,\nwhich describes the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e. creating new objects)\nare made in Zig. You can create a new object in Zig by using the following syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). At @sec-assignments we talk more about objects in general.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that at @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIs worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt is like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portable C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nOn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOs. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e. the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. Thus, if you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith a \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, operations like accessing the `stdout` (or opening a file) on Windows\ndepends on resources that are available only at *runtime* (you will learn more about compile-time\nversus runtime at @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword at @sec-comptime.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation at a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues \n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described at @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig latter in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig? \nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar in our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentations.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It is a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (at YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e. identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nIn contrast, if you use `var`, then, the object created is a variable object.\nWith `var` you can declare this object in your source code, and then,\nchange the value of this object how many times you want over future points\nin your source code.\n\nSo, using the same code example exposed above, if I change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it is an \"variable object\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIs important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code use this object while it is uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object. \n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e. if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to an special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It is discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also get's discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e. the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\n\nIs worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array. \n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it is a slice that\naccess all elements in the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" at @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth at @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially at @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned at @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e. the start and the end of this range)\nis known at compile-time, the slice object that get's created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nat @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that get's created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e. a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can \ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n```\n:::\n\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat get's created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, the `slice` object have a runtime known range, because the end index of the range\nis not known at compile time. In other words, the size of the array at `buffer` is not known\nat compile time. When we execute this program, the size of the array might be 10, or, it might be 12\ndepending on where we execute it. Therefore, we don't know at compile time if\nthe slice object have a range of size 10, or, a range of size 12.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e. a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented at @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e. `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIs worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e. the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause it is much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e. if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it is a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIs important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig at @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers at @sec-root-file and especially at @sec-assignments.\n- How strings work in Zig at @sec-zig-strings.\n- How to use arrays and slices at @sec-arrays.\n- How to import functionality from other Zig modules at @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* at @sec-structs-and-oop.\n- Basic control flow syntax at @sec-zig-control-flow.\n- Enums at @sec-enum;\n- Pointers and Optionals at @sec-pointer;\n- Error handling with `try` and `catch` at @sec-error-handling;\n- Unit tests at @sec-unittests;\n- Vectors at @sec-vectors-simd;\n- Build System at @sec-build-system;\n\n\n\n\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/docs/Chapters/01-zig-weird.html b/docs/Chapters/01-zig-weird.html
index f7360c5b..ff08a55e 100644
--- a/docs/Chapters/01-zig-weird.html
+++ b/docs/Chapters/01-zig-weird.html
@@ -459,7 +459,7 @@ <h3 data-number="1.2.4" class="anchored" data-anchor-id="sec-compile-code"><span
 <p>You can compile your Zig modules into a binary executable by running the <code>build-exe</code> command from the <code>zig</code> compiler. You simply list all the Zig modules that you want to build after the <code>build-exe</code> command, separated by spaces. In the example below, we are compiling the module <code>main.zig</code>.</p>
 <div class="sourceCode" id="cb7"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zig</span> build-exe src/main.zig</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <p>Since we are building an executable, the <code>zig</code> compiler will look for a <code>main()</code> function declared in any of the files that you list after the <code>build-exe</code> command. If the compiler does not find a <code>main()</code> function declared somewhere, a compilation error will be raised, warning about this mistake.</p>
-<p>The <code>zig</code> compiler also offers a <code>build-lib</code> and <code>build-obj</code> commands, which work the exact same way as the <code>build-exe</code> command. The only difference is that, they compile your Zig modules into a portale C ABI library, or, into object files, respectively.</p>
+<p>The <code>zig</code> compiler also offers a <code>build-lib</code> and <code>build-obj</code> commands, which work the exact same way as the <code>build-exe</code> command. The only difference is that, they compile your Zig modules into a portable C ABI library, or, into object files, respectively.</p>
 <p>In the case of the <code>build-exe</code> command, a binary executable file is created by the <code>zig</code> compiler in the root directory of your project. If we take a look now at the contents of our current directory, with a simple <code>ls</code> command, we can see the binary file called <code>main</code> that was created by the compiler.</p>
 <div class="sourceCode" id="cb8"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a><span class="fu">ls</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <pre><code>build.zig  build.zig.zon  main  src</code></pre>
diff --git a/docs/search.json b/docs/search.json
index 9d8728f7..e3d46f3e 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -124,7 +124,7 @@
     "href": "Chapters/01-zig-weird.html#hello-world-in-zig",
     "title": "1  Introducing Zig",
     "section": "1.2 Hello world in Zig",
-    "text": "1.2 Hello world in Zig\nWe begin our journey in Zig by creating a small “Hello World” program. To start a new Zig project in your computer, you simply call the init command from the zig compiler. Just create a new directory in your computer, then, init a new Zig project inside this directory, like this:\nmkdir hello_world\ncd hello_world\nzig init\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n\n1.2.1 Understanding the project files\nAfter you run the init command from the zig compiler, some new files are created inside of your current directory. First, a “source” (src) directory is created, containing two files, main.zig and root.zig. Each .zig file is a separate Zig module, which is simply a text file that contains some Zig code.\nBy convention, the main.zig module is where your main function lives. Thus, if you are building an executable program in Zig, you need to declare a main() function, which represents the entrypoint of your program, i.e. it is where the execution of your program begins.\nHowever, if you are building a library (instead of an executable program), then, the normal procedure is to delete this main.zig file and start with the root.zig module. By convention, the root.zig module is the root source file of your library.\ntree .\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\nThe init command also creates two additional files in our working directory: build.zig and build.zig.zon. The first file (build.zig) represents a build script written in Zig. This script is executed when you call the build command from the zig compiler. In other words, this file contain Zig code that executes the necessary steps to build the entire project.\nLow-level languages normally use a compiler to build your source code into binary executables or binary libraries. Nevertheless, this process of compiling your source code and building binary executables or binary libraries from it, became a real challenge in the programming world, once the projects became bigger and bigger. As a result, programmers created “build systems”, which are a second set of tools designed to make this process of compiling and building complex projects, easier.\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja, which are used to build complex C and C++ projects. With these systems, you can write scripts, which are called “build scripts”. They simply are scripts that describes the necessary steps to compile/build your project.\nHowever, these are separate tools, that do not belong to C/C++ compilers, like gcc or clang. As a result, in C/C++ projects, you have not only to install and manage your C/C++ compilers, but you also have to install and manage these build systems separately.\nIn Zig, we don’t need to use a separate set of tools to build our projects, because a build system is embedded inside the language itself. Therefore, Zig contains a native build system in it, and we can use this build system to write small scripts in Zig, which describes the necessary steps to build/compile our Zig project1. So, everything you need to build a complex Zig project is the zig compiler, and nothing more.\nThe second generated file (build.zig.zon) is a JSON-like file, in which you can describe your project, and also, declare a set of dependencies of your project that you want to fetch from the internet. In other words, you can use this build.zig.zon file to include a list of external libraries in your project.\nOne possible way to include an external Zig library in your project, is to manually build and install the library in your system, and just link your source code with the library at the build step of your project.\nHowever, if this external Zig library is available on GitHub for example, and it has a valid build.zig.zon file in root folder of the project, which describes the project, you can easily include this library in your project by simply listing this external library in your build.zig.zon file.\nIn other words, this build.zig.zon file works similarly to the package.json file in Javascript projects, or the Pipfile file in Python projects, or the Cargo.toml file in Rust projects. You can read more about this specific file in a couple of articles on the internet23, and you can also see the expected schema for this build.zig.zon file in a documentation file inside the official repository of Zig4.\n\n\n1.2.2 The file root.zig\nLet’s take a look into the root.zig file. You might have noticed that every line of code with an expression ends with a semicolon (;). This follows the syntax of a C-family programming language5.\nAlso, notice the @import() call at the first line. We use this built-in function to import functionality from other Zig modules into our current module. This @import() function works similarly to the #include pre-processor in C or C++, or, to the import statement in Python or Javascript code. In this example, we are importing the std module, which gives you access to the Zig Standard Library.\nIn this root.zig file, we can also see how assignments (i.e. creating new objects) are made in Zig. You can create a new object in Zig by using the following syntax (const|var) name = value;. In the example below, we are creating two constant objects (std and testing). At Section 1.4 we talk more about objects in general.\n\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n\nFunctions in Zig are declared using the fn keyword. In this root.zig module, we are declaring a function called add(), which has two arguments named a and b. The function returns an integer of the type i32 as result.\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit the type of an object in your code, if this type can be inferred by the zig compiler (we talk more about that at Section 2.4). But there are other situations where you do need to be explicit. For example, you do have to explicitly specify the type of each function argument, and also, the return type of every function that you create in Zig.\nWe specify the type of an object or a function argument in Zig by using a colon character (:) followed by the type after the name of this object/function argument. With the expressions a: i32 and b: i32, we know that both a and b arguments have type i32, which is a signed 32 bit integer. In this part, the syntax in Zig is identical to the syntax in Rust, which also specifies types by using the colon character.\nLastly, we have the return type of the function at the end of the line, before we open the curly braces to start writing the function’s body. In the example above, this type is also a signed 32 bit integer (i32) value.\nNotice that we also have an export keyword before the function declaration. This keyword is similar to the extern keyword in C. It exposes the function to make it available in the library API. Therefore, if you are writing a library for other people to use, you have to expose the functions you write in the public API of this library by using this export keyword. If we removed the export keyword from the add() function declaration, then, this function would be no longer exposed in the library object built by the zig compiler.\n\n\n1.2.3 The main.zig file\nNow that we have learned a lot about Zig’s syntax from the root.zig file, let’s take a look at the main.zig file. A lot of the elements we saw in root.zig are also present in main.zig. But there are some other elements that we haven’t seen yet, so let’s dive in.\nFirst, look at the return type of the main() function in this file. We can see a small change. The return type of the function (void) is accompanied by an exclamation mark (!). This exclamation mark tells us that this main() function might return an error.\nIs worth noting that, a main() function in Zig is allowed to return nothing (void), or an unsigned 8-bit integer (u8) value6, or an error. In other words, you can write your main() function in Zig to return essentially nothing (void), or, if you prefer, you can also write a more C-like main() function, which returns an integer value that usually serves as a “status code” for the process.\nIn this example, the return type annotation of main() indicates that this function can either return nothing (void), or return an error. This exclamation mark in the return type annotation is an interesting and powerful feature of Zig. In summary, if you write a function and something inside the body of this function might return an error, then, you are forced to:\n\neither add the exclamation mark to the return type of the function and make it clear that this function might return an error.\nexplicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through a try catch pattern. Zig does have both try and catch keywords. But they work a little differently than what you’re probably used to in other languages.\nIf we look at the main() function below, you can see that we do have a try keyword on the 5th line. But we do not have a catch keyword in this code. In Zig, we use the try keyword to execute an expression that might return an error, which, in this example, is the stdout.print() expression.\nIn essence, the try keyword executes the expression stdout.print(). If this expression returns a valid value, then, the try keyword does absolutely nothing. It only passes the value forward. It is like if this try keyword was never there. However, if the expression does return an error, then, the try keyword will unwrap the error value, then, it returns this error from the function and also prints the current stack trace to stderr.\nThis might sound weird to you if you come from a high-level language. Because in high-level languages, such as Python, if an error occurs somewhere, this error is automatically returned and the execution of your program will automatically stop even if you don’t want to stop the execution. You are obligated to face the error.\n\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n\nAnother thing that you might have noticed in this code example, is that the main() function is marked with the pub keyword. It marks the main() function as a public function from this module. Every function in your Zig module is by default private to this Zig module and can only be called from within the module. Unless, you explicitly mark this function as a public function with the pub keyword.\nIf you think about it, this pub keyword in Zig does essentially the opposite of what the static keyword do in C/C++. By making a function “public” you allow other Zig modules to access and call this function. A calling Zig module imports another module by using the @import() built-in function, which makes all public functions from the imported module visible to the calling Zig module.\n\n\n1.2.4 Compiling your source code\nYou can compile your Zig modules into a binary executable by running the build-exe command from the zig compiler. You simply list all the Zig modules that you want to build after the build-exe command, separated by spaces. In the example below, we are compiling the module main.zig.\nzig build-exe src/main.zig\nSince we are building an executable, the zig compiler will look for a main() function declared in any of the files that you list after the build-exe command. If the compiler does not find a main() function declared somewhere, a compilation error will be raised, warning about this mistake.\nThe zig compiler also offers a build-lib and build-obj commands, which work the exact same way as the build-exe command. The only difference is that, they compile your Zig modules into a portale C ABI library, or, into object files, respectively.\nIn the case of the build-exe command, a binary executable file is created by the zig compiler in the root directory of your project. If we take a look now at the contents of our current directory, with a simple ls command, we can see the binary file called main that was created by the compiler.\nls\nbuild.zig  build.zig.zon  main  src\nIf I execute this binary executable, I get the “Hello World” message in the terminal , as we expected.\n./main\nHello, world!\n\n\n1.2.5 Compile and execute at the same time\nOn the previous section, I presented the zig build-exe command, which compiles Zig modules into an executable file. However, this means that, in order to execute the executable file, we have to run two different commands. First, the zig build-exe command, and then, we call the executable file created by the compiler.\nBut what if we wanted to perform these two steps, all at once, in a single command? We can do that by using the zig run command.\nzig run src/main.zig\nHello, world!\n\n\n1.2.6 Important note for Windows users\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other operating systems, such as Linux and macOs. In summary, if you have a piece of Zig code that includes some global variables whose initialization rely on runtime resources, then, you might have some troubles while trying to compile this Zig code on Windows.\nAn example of that is accessing the stdout (i.e. the standard output of your system), which is usually done in Zig by using the expression std.io.getStdOut(). Thus, if you use this expression to instantiate a global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows, with a “unable to evaluate comptime expression” error message.\nThis failure in the compilation process happens because all global variables in Zig are initialized at compile-time. However, operations like accessing the stdout (or opening a file) on Windows depends on resources that are available only at runtime (you will learn more about compile-time versus runtime at Section 3.1.1).\nFor example, if you try to compile this code example on Windows, you will likely get the error message exposed below:\n\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\nTo avoid this problem on Windows, we need to force the zig compiler to instantiate this stdout object only at runtime, instead of instantiating it at compile-time. We can achieve that by simply moving the expression to a function body.\nThis solves the problem because all expressions that are inside a function body in Zig are evaluated only at runtime, unless you use the comptime keyword explicitly to change this behaviour. You will learn more about this comptime keyword at Section 12.1.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nHello\nYou can read more details about this Windows-specific limitation at a couple of GitHub issues opened at the official Zig repository. More specifically, the issues 17186 7 and 19864 8.\n\n\n1.2.7 Compiling the entire project\nJust as I described at Section 1.2.1, as our project grows in size and complexity, we usually prefer to organize the compilation and build process of the project into a build script, using some sort of “build system”.\nIn other words, as our project grows in size and complexity, the build-exe, build-lib and build-obj commands become harder to use directly. Because then, we start to list multiple and multiple modules at the same time. We also start to add built-in compilation flags to customize the build process for our needs, etc. It becomes a lot of work to write the necessary commands by hand.\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, Makefile or configure scripts to organize this process. However, in Zig, we have a native build system in the language itself. So, we can write build scripts in Zig to compile and build Zig projects. Then, all we need to do, is to call the zig build command to build our project.\nSo, when you execute the zig build command, the zig compiler will search for a Zig module named build.zig inside your current directory, which should be your build script, containing the necessary code to compile and build your project. If the compiler does find this build.zig file in your directory, then, the compiler will essentially execute a zig run command over this build.zig file, to compile and execute this build script, which in turn, will compile and build your entire project.\nzig build\nAfter you execute this “build project” command, a zig-out directory is created in the root of your project directory, where you can find the binary executables and libraries created from your Zig modules accordingly to the build commands that you specified at build.zig. We will talk more about the build system in Zig latter in this book.\nIn the example below, I’m executing the binary executable named hello_world that was generated by the compiler after the zig build command.\n./zig-out/bin/hello_world\nHello, world!",
+    "text": "1.2 Hello world in Zig\nWe begin our journey in Zig by creating a small “Hello World” program. To start a new Zig project in your computer, you simply call the init command from the zig compiler. Just create a new directory in your computer, then, init a new Zig project inside this directory, like this:\nmkdir hello_world\ncd hello_world\nzig init\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n\n1.2.1 Understanding the project files\nAfter you run the init command from the zig compiler, some new files are created inside of your current directory. First, a “source” (src) directory is created, containing two files, main.zig and root.zig. Each .zig file is a separate Zig module, which is simply a text file that contains some Zig code.\nBy convention, the main.zig module is where your main function lives. Thus, if you are building an executable program in Zig, you need to declare a main() function, which represents the entrypoint of your program, i.e. it is where the execution of your program begins.\nHowever, if you are building a library (instead of an executable program), then, the normal procedure is to delete this main.zig file and start with the root.zig module. By convention, the root.zig module is the root source file of your library.\ntree .\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\nThe init command also creates two additional files in our working directory: build.zig and build.zig.zon. The first file (build.zig) represents a build script written in Zig. This script is executed when you call the build command from the zig compiler. In other words, this file contain Zig code that executes the necessary steps to build the entire project.\nLow-level languages normally use a compiler to build your source code into binary executables or binary libraries. Nevertheless, this process of compiling your source code and building binary executables or binary libraries from it, became a real challenge in the programming world, once the projects became bigger and bigger. As a result, programmers created “build systems”, which are a second set of tools designed to make this process of compiling and building complex projects, easier.\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja, which are used to build complex C and C++ projects. With these systems, you can write scripts, which are called “build scripts”. They simply are scripts that describes the necessary steps to compile/build your project.\nHowever, these are separate tools, that do not belong to C/C++ compilers, like gcc or clang. As a result, in C/C++ projects, you have not only to install and manage your C/C++ compilers, but you also have to install and manage these build systems separately.\nIn Zig, we don’t need to use a separate set of tools to build our projects, because a build system is embedded inside the language itself. Therefore, Zig contains a native build system in it, and we can use this build system to write small scripts in Zig, which describes the necessary steps to build/compile our Zig project1. So, everything you need to build a complex Zig project is the zig compiler, and nothing more.\nThe second generated file (build.zig.zon) is a JSON-like file, in which you can describe your project, and also, declare a set of dependencies of your project that you want to fetch from the internet. In other words, you can use this build.zig.zon file to include a list of external libraries in your project.\nOne possible way to include an external Zig library in your project, is to manually build and install the library in your system, and just link your source code with the library at the build step of your project.\nHowever, if this external Zig library is available on GitHub for example, and it has a valid build.zig.zon file in root folder of the project, which describes the project, you can easily include this library in your project by simply listing this external library in your build.zig.zon file.\nIn other words, this build.zig.zon file works similarly to the package.json file in Javascript projects, or the Pipfile file in Python projects, or the Cargo.toml file in Rust projects. You can read more about this specific file in a couple of articles on the internet23, and you can also see the expected schema for this build.zig.zon file in a documentation file inside the official repository of Zig4.\n\n\n1.2.2 The file root.zig\nLet’s take a look into the root.zig file. You might have noticed that every line of code with an expression ends with a semicolon (;). This follows the syntax of a C-family programming language5.\nAlso, notice the @import() call at the first line. We use this built-in function to import functionality from other Zig modules into our current module. This @import() function works similarly to the #include pre-processor in C or C++, or, to the import statement in Python or Javascript code. In this example, we are importing the std module, which gives you access to the Zig Standard Library.\nIn this root.zig file, we can also see how assignments (i.e. creating new objects) are made in Zig. You can create a new object in Zig by using the following syntax (const|var) name = value;. In the example below, we are creating two constant objects (std and testing). At Section 1.4 we talk more about objects in general.\n\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n\nFunctions in Zig are declared using the fn keyword. In this root.zig module, we are declaring a function called add(), which has two arguments named a and b. The function returns an integer of the type i32 as result.\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit the type of an object in your code, if this type can be inferred by the zig compiler (we talk more about that at Section 2.4). But there are other situations where you do need to be explicit. For example, you do have to explicitly specify the type of each function argument, and also, the return type of every function that you create in Zig.\nWe specify the type of an object or a function argument in Zig by using a colon character (:) followed by the type after the name of this object/function argument. With the expressions a: i32 and b: i32, we know that both a and b arguments have type i32, which is a signed 32 bit integer. In this part, the syntax in Zig is identical to the syntax in Rust, which also specifies types by using the colon character.\nLastly, we have the return type of the function at the end of the line, before we open the curly braces to start writing the function’s body. In the example above, this type is also a signed 32 bit integer (i32) value.\nNotice that we also have an export keyword before the function declaration. This keyword is similar to the extern keyword in C. It exposes the function to make it available in the library API. Therefore, if you are writing a library for other people to use, you have to expose the functions you write in the public API of this library by using this export keyword. If we removed the export keyword from the add() function declaration, then, this function would be no longer exposed in the library object built by the zig compiler.\n\n\n1.2.3 The main.zig file\nNow that we have learned a lot about Zig’s syntax from the root.zig file, let’s take a look at the main.zig file. A lot of the elements we saw in root.zig are also present in main.zig. But there are some other elements that we haven’t seen yet, so let’s dive in.\nFirst, look at the return type of the main() function in this file. We can see a small change. The return type of the function (void) is accompanied by an exclamation mark (!). This exclamation mark tells us that this main() function might return an error.\nIs worth noting that, a main() function in Zig is allowed to return nothing (void), or an unsigned 8-bit integer (u8) value6, or an error. In other words, you can write your main() function in Zig to return essentially nothing (void), or, if you prefer, you can also write a more C-like main() function, which returns an integer value that usually serves as a “status code” for the process.\nIn this example, the return type annotation of main() indicates that this function can either return nothing (void), or return an error. This exclamation mark in the return type annotation is an interesting and powerful feature of Zig. In summary, if you write a function and something inside the body of this function might return an error, then, you are forced to:\n\neither add the exclamation mark to the return type of the function and make it clear that this function might return an error.\nexplicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through a try catch pattern. Zig does have both try and catch keywords. But they work a little differently than what you’re probably used to in other languages.\nIf we look at the main() function below, you can see that we do have a try keyword on the 5th line. But we do not have a catch keyword in this code. In Zig, we use the try keyword to execute an expression that might return an error, which, in this example, is the stdout.print() expression.\nIn essence, the try keyword executes the expression stdout.print(). If this expression returns a valid value, then, the try keyword does absolutely nothing. It only passes the value forward. It is like if this try keyword was never there. However, if the expression does return an error, then, the try keyword will unwrap the error value, then, it returns this error from the function and also prints the current stack trace to stderr.\nThis might sound weird to you if you come from a high-level language. Because in high-level languages, such as Python, if an error occurs somewhere, this error is automatically returned and the execution of your program will automatically stop even if you don’t want to stop the execution. You are obligated to face the error.\n\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n\nAnother thing that you might have noticed in this code example, is that the main() function is marked with the pub keyword. It marks the main() function as a public function from this module. Every function in your Zig module is by default private to this Zig module and can only be called from within the module. Unless, you explicitly mark this function as a public function with the pub keyword.\nIf you think about it, this pub keyword in Zig does essentially the opposite of what the static keyword do in C/C++. By making a function “public” you allow other Zig modules to access and call this function. A calling Zig module imports another module by using the @import() built-in function, which makes all public functions from the imported module visible to the calling Zig module.\n\n\n1.2.4 Compiling your source code\nYou can compile your Zig modules into a binary executable by running the build-exe command from the zig compiler. You simply list all the Zig modules that you want to build after the build-exe command, separated by spaces. In the example below, we are compiling the module main.zig.\nzig build-exe src/main.zig\nSince we are building an executable, the zig compiler will look for a main() function declared in any of the files that you list after the build-exe command. If the compiler does not find a main() function declared somewhere, a compilation error will be raised, warning about this mistake.\nThe zig compiler also offers a build-lib and build-obj commands, which work the exact same way as the build-exe command. The only difference is that, they compile your Zig modules into a portable C ABI library, or, into object files, respectively.\nIn the case of the build-exe command, a binary executable file is created by the zig compiler in the root directory of your project. If we take a look now at the contents of our current directory, with a simple ls command, we can see the binary file called main that was created by the compiler.\nls\nbuild.zig  build.zig.zon  main  src\nIf I execute this binary executable, I get the “Hello World” message in the terminal , as we expected.\n./main\nHello, world!\n\n\n1.2.5 Compile and execute at the same time\nOn the previous section, I presented the zig build-exe command, which compiles Zig modules into an executable file. However, this means that, in order to execute the executable file, we have to run two different commands. First, the zig build-exe command, and then, we call the executable file created by the compiler.\nBut what if we wanted to perform these two steps, all at once, in a single command? We can do that by using the zig run command.\nzig run src/main.zig\nHello, world!\n\n\n1.2.6 Important note for Windows users\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other operating systems, such as Linux and macOs. In summary, if you have a piece of Zig code that includes some global variables whose initialization rely on runtime resources, then, you might have some troubles while trying to compile this Zig code on Windows.\nAn example of that is accessing the stdout (i.e. the standard output of your system), which is usually done in Zig by using the expression std.io.getStdOut(). Thus, if you use this expression to instantiate a global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows, with a “unable to evaluate comptime expression” error message.\nThis failure in the compilation process happens because all global variables in Zig are initialized at compile-time. However, operations like accessing the stdout (or opening a file) on Windows depends on resources that are available only at runtime (you will learn more about compile-time versus runtime at Section 3.1.1).\nFor example, if you try to compile this code example on Windows, you will likely get the error message exposed below:\n\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\nTo avoid this problem on Windows, we need to force the zig compiler to instantiate this stdout object only at runtime, instead of instantiating it at compile-time. We can achieve that by simply moving the expression to a function body.\nThis solves the problem because all expressions that are inside a function body in Zig are evaluated only at runtime, unless you use the comptime keyword explicitly to change this behaviour. You will learn more about this comptime keyword at Section 12.1.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nHello\nYou can read more details about this Windows-specific limitation at a couple of GitHub issues opened at the official Zig repository. More specifically, the issues 17186 7 and 19864 8.\n\n\n1.2.7 Compiling the entire project\nJust as I described at Section 1.2.1, as our project grows in size and complexity, we usually prefer to organize the compilation and build process of the project into a build script, using some sort of “build system”.\nIn other words, as our project grows in size and complexity, the build-exe, build-lib and build-obj commands become harder to use directly. Because then, we start to list multiple and multiple modules at the same time. We also start to add built-in compilation flags to customize the build process for our needs, etc. It becomes a lot of work to write the necessary commands by hand.\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, Makefile or configure scripts to organize this process. However, in Zig, we have a native build system in the language itself. So, we can write build scripts in Zig to compile and build Zig projects. Then, all we need to do, is to call the zig build command to build our project.\nSo, when you execute the zig build command, the zig compiler will search for a Zig module named build.zig inside your current directory, which should be your build script, containing the necessary code to compile and build your project. If the compiler does find this build.zig file in your directory, then, the compiler will essentially execute a zig run command over this build.zig file, to compile and execute this build script, which in turn, will compile and build your entire project.\nzig build\nAfter you execute this “build project” command, a zig-out directory is created in the root of your project directory, where you can find the binary executables and libraries created from your Zig modules accordingly to the build commands that you specified at build.zig. We will talk more about the build system in Zig latter in this book.\nIn the example below, I’m executing the binary executable named hello_world that was generated by the compiler after the zig build command.\n./zig-out/bin/hello_world\nHello, world!",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]

From 9ad203426c28a152275997bcba50fa72b3250231 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sun, 9 Feb 2025 10:51:50 -0300
Subject: [PATCH 057/151] Add change to QMD file

---
 Chapters/01-zig-weird.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index f0983bf4..12b677e5 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -731,7 +731,7 @@ Everytime you declare a new object in Zig, you have two choices:
 1. or you explicitly discard the value of the object;
 
 To explicitly discard the value of any object (constant or variable), all you need to do is to assign
-this object to an special character in Zig, which is the underscore (`_`).
+this object to a special character in Zig, which is the underscore (`_`).
 When you assign an object to a underscore, like in the example below, the `zig` compiler will automatically
 discard the value of this particular object.
 

From ba6c7bf1bcb6c7a0357fe79d3adc521567d8c30d Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sun, 9 Feb 2025 10:53:11 -0300
Subject: [PATCH 058/151] Recompile book with changes

---
 _freeze/Chapters/01-zig-weird/execute-results/html.json | 8 +++-----
 docs/search.json                                        | 2 +-
 2 files changed, 4 insertions(+), 6 deletions(-)

diff --git a/_freeze/Chapters/01-zig-weird/execute-results/html.json b/_freeze/Chapters/01-zig-weird/execute-results/html.json
index 28800571..3f48d096 100644
--- a/_freeze/Chapters/01-zig-weird/execute-results/html.json
+++ b/_freeze/Chapters/01-zig-weird/execute-results/html.json
@@ -1,11 +1,9 @@
 {
-  "hash": "507166385ff85ccf512b153b7c107291",
+  "hash": "5041be02baff66bca29c690e3dfbfd7c",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\nlanguage, it is still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. They really make it sometimes hard to debug\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscures the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that get's compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e. it is where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contain Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nTherefore, Zig contains a native build system in it, and\nwe can use this build system to write small scripts in Zig,\nwhich describes the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e. creating new objects)\nare made in Zig. You can create a new object in Zig by using the following syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). At @sec-assignments we talk more about objects in general.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that at @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIs worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt is like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portale C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nOn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOs. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e. the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. Thus, if you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith a \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, operations like accessing the `stdout` (or opening a file) on Windows\ndepends on resources that are available only at *runtime* (you will learn more about compile-time\nversus runtime at @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword at @sec-comptime.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation at a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues \n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described at @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig latter in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig? \nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar in our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentations.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It is a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (at YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e. identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nIn contrast, if you use `var`, then, the object created is a variable object.\nWith `var` you can declare this object in your source code, and then,\nchange the value of this object how many times you want over future points\nin your source code.\n\nSo, using the same code example exposed above, if I change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it is an \"variable object\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIs important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code use this object while it is uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object. \n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e. if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to an special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It is discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also get's discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e. the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\nIs worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array. \n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it is a slice that\naccess all elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" at @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth at @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially at @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned at @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e. the start and the end of this range)\nis known at compile-time, the slice object that get's created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nat @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that get's created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e. a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can \ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n```\n:::\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat get's created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, the `slice` object have a runtime known range, because the end index of the range\nis not known at compile time. In other words, the size of the array at `buffer` is not known\nat compile time. When we execute this program, the size of the array might be 10, or, it might be 12\ndepending on where we execute it. Therefore, we don't know at compile time if\nthe slice object have a range of size 10, or, a range of size 12.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e. a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented at @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e. `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIs worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e. the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause it is much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e. if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it is a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIs important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig at @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers at @sec-root-file and especially at @sec-assignments.\n- How strings work in Zig at @sec-zig-strings.\n- How to use arrays and slices at @sec-arrays.\n- How to import functionality from other Zig modules at @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* at @sec-structs-and-oop.\n- Basic control flow syntax at @sec-zig-control-flow.\n- Enums at @sec-enum;\n- Pointers and Optionals at @sec-pointer;\n- Error handling with `try` and `catch` at @sec-error-handling;\n- Unit tests at @sec-unittests;\n- Vectors at @sec-vectors-simd;\n- Build System at @sec-build-system;\n\n\n\n\n",
-    "supporting": [
-      "01-zig-weird_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\nlanguage, it is still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. They really make it sometimes hard to debug\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscures the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that get's compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e. it is where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contain Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nTherefore, Zig contains a native build system in it, and\nwe can use this build system to write small scripts in Zig,\nwhich describes the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e. creating new objects)\nare made in Zig. You can create a new object in Zig by using the following syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). At @sec-assignments we talk more about objects in general.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that at @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIs worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt is like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portale C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nOn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOs. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e. the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. Thus, if you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith a \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, operations like accessing the `stdout` (or opening a file) on Windows\ndepends on resources that are available only at *runtime* (you will learn more about compile-time\nversus runtime at @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword at @sec-comptime.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation at a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues \n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described at @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig latter in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig? \nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar in our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentations.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It is a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (at YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e. identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nIn contrast, if you use `var`, then, the object created is a variable object.\nWith `var` you can declare this object in your source code, and then,\nchange the value of this object how many times you want over future points\nin your source code.\n\nSo, using the same code example exposed above, if I change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it is an \"variable object\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIs important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code use this object while it is uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object. \n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e. if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to a special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It is discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also get's discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e. the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\n\nIs worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array. \n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it is a slice that\naccess all elements in the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" at @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth at @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially at @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned at @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e. the start and the end of this range)\nis known at compile-time, the slice object that get's created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nat @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that get's created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e. a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can \ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n```\n:::\n\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat get's created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, the `slice` object have a runtime known range, because the end index of the range\nis not known at compile time. In other words, the size of the array at `buffer` is not known\nat compile time. When we execute this program, the size of the array might be 10, or, it might be 12\ndepending on where we execute it. Therefore, we don't know at compile time if\nthe slice object have a range of size 10, or, a range of size 12.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e. a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented at @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e. `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIs worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e. the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause it is much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e. if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it is a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIs important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig at @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers at @sec-root-file and especially at @sec-assignments.\n- How strings work in Zig at @sec-zig-strings.\n- How to use arrays and slices at @sec-arrays.\n- How to import functionality from other Zig modules at @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* at @sec-structs-and-oop.\n- Basic control flow syntax at @sec-zig-control-flow.\n- Enums at @sec-enum;\n- Pointers and Optionals at @sec-pointer;\n- Error handling with `try` and `catch` at @sec-error-handling;\n- Unit tests at @sec-unittests;\n- Vectors at @sec-vectors-simd;\n- Build System at @sec-build-system;\n\n\n\n\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/docs/search.json b/docs/search.json
index 9d8728f7..805ce92a 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -144,7 +144,7 @@
     "href": "Chapters/01-zig-weird.html#sec-assignments",
     "title": "1  Introducing Zig",
     "section": "1.4 Creating new objects in Zig (i.e. identifiers)",
-    "text": "1.4 Creating new objects in Zig (i.e. identifiers)\nLet’s talk more about objects in Zig. Readers that have past experience with other programming languages might know this concept through a different name, such as: “variable” or “identifier”. In this book, I choose to use the term “object” to refer to this concept.\nTo create a new object (or a new “identifier”) in Zig, we use the keywords const or var. These keywords specify if the object that you are creating is mutable or not. If you use const, then the object you are creating is a constant (or immutable) object, which means that once you declare this object, you can no longer change the value stored inside this object.\nOn the other side, if you use var, then, you are creating a variable (or mutable) object. You can change the value of this object as many times you want. Using the keyword var in Zig is similar to using the keywords let mut in Rust.\n\n1.4.1 Constant objects vs variable objects\nIn the code example below, we are creating a new constant object called age. This object stores a number representing the age of someone. However, this code example does not compile successfully. Because on the next line of code, we are trying to change the value of the object age to 25.\nThe zig compiler detects that we are trying to change the value of an object/identifier that is constant, and because of that, the compiler will raise a compilation error, warning us about the mistake.\n\nconst age = 24;\n// The line below is not valid!\nage = 25;\n\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\nIn contrast, if you use var, then, the object created is a variable object. With var you can declare this object in your source code, and then, change the value of this object how many times you want over future points in your source code.\nSo, using the same code example exposed above, if I change the declaration of the age object to use the var keyword, then, the program gets compiled successfully. Because now, the zig compiler detects that we are changing the value of an object that allows this behaviour, because it is an “variable object”.\n\nvar age: u8 = 24;\nage = 25;\n\n\n\n1.4.2 Declaring without an initial value\nBy default, when you declare a new object in Zig, you must give it an initial value. In other words, this means that we have to declare, and, at the same time, initialize every object we create in our source code.\nOn the other hand, you can, in fact, declare a new object in your source code, and not give it an explicit value. But we need to use a special keyword for that, which is the undefined keyword.\nIs important to emphasize that, you should avoid using undefined as much as possible. Because when you use this keyword, you leave your object uninitialized, and, as a consequence, if for some reason, your code use this object while it is uninitialized, then, you will definitely have undefined behaviour and major bugs in your program.\nIn the example below, I’m declaring the age object again. But this time, I do not give it an initial value. The variable is only initialized at the second line of code, where I store the number 25 in this object.\n\nvar age: u8 = undefined;\nage = 25;\n\nHaving these points in mind, just remember that you should avoid as much as possible to use undefined in your code. Always declare and initialize your objects. Because this gives you much more safety in your program. But in case you really need to declare an object without initializing it… the undefined keyword is the way to do it in Zig.\n\n\n1.4.3 There is no such thing as unused objects\nEvery object (being constant or variable) that you declare in Zig must be used in some way. You can give this object to a function call, as a function argument, or, you can use it in another expression to calculate the value of another object, or, you can call a method that belongs to this particular object.\nIt doesn’t matter in which way you use it. As long as you use it. If you try to break this rule, i.e. if your try to declare a object, but not use it, the zig compiler will not compile your Zig source code, and it will issue a error message warning that you have unused objects in your code.\nLet’s demonstrate this with an example. In the source code below, we declare a constant object called age. If you try to compile a simple Zig program with this line of code below, the compiler will return an error as demonstrated below:\n\nconst age = 15;\n\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\nEverytime you declare a new object in Zig, you have two choices:\n\nyou either use the value of this object;\nor you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign this object to an special character in Zig, which is the underscore (_). When you assign an object to a underscore, like in the example below, the zig compiler will automatically discard the value of this particular object.\nYou can see in the example below that, this time, the compiler did not complain about any “unused constant”, and successfully compiled our source code.\n\n// It compiles!\nconst age = 15;\n_ = age;\n\nNow, remember, everytime you assign a particular object to the underscore, this object is essentially destroyed. It is discarded by the compiler. This means that you can no longer use this object further in your code. It doesn’t exist anymore.\nSo if you try to use the constant age in the example below, after we discarded it, you will get a loud error message from the compiler (talking about a “pointless discard”) warning you about this mistake.\n\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n\nt.zig:7:5: error: pointless discard\n    of local constant\nThis same rule applies to variable objects. Every variable object must also be used in some way. And if you assign a variable object to the underscore, this object also get’s discarded, and you can no longer use this object.\n\n\n1.4.4 You must mutate every variable objects\nEvery variable object that you create in your source code must be mutated at some point. In other words, if you declare an object as a variable object, with the keyword var, and you do not change the value of this object at some point in the future, the zig compiler will detect this, and it will raise an error warning you about this mistake.\nThe concept behind this is that every object you create in Zig should be preferably a constant object, unless you really need an object whose value will change during the execution of your program.\nSo, if I try to declare a variable object such as where_i_live below, and I do not change the value of this object in some way, the zig compiler raises an error message with the phrase “variable is never mutated”.\n\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'",
+    "text": "1.4 Creating new objects in Zig (i.e. identifiers)\nLet’s talk more about objects in Zig. Readers that have past experience with other programming languages might know this concept through a different name, such as: “variable” or “identifier”. In this book, I choose to use the term “object” to refer to this concept.\nTo create a new object (or a new “identifier”) in Zig, we use the keywords const or var. These keywords specify if the object that you are creating is mutable or not. If you use const, then the object you are creating is a constant (or immutable) object, which means that once you declare this object, you can no longer change the value stored inside this object.\nOn the other side, if you use var, then, you are creating a variable (or mutable) object. You can change the value of this object as many times you want. Using the keyword var in Zig is similar to using the keywords let mut in Rust.\n\n1.4.1 Constant objects vs variable objects\nIn the code example below, we are creating a new constant object called age. This object stores a number representing the age of someone. However, this code example does not compile successfully. Because on the next line of code, we are trying to change the value of the object age to 25.\nThe zig compiler detects that we are trying to change the value of an object/identifier that is constant, and because of that, the compiler will raise a compilation error, warning us about the mistake.\n\nconst age = 24;\n// The line below is not valid!\nage = 25;\n\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\nIn contrast, if you use var, then, the object created is a variable object. With var you can declare this object in your source code, and then, change the value of this object how many times you want over future points in your source code.\nSo, using the same code example exposed above, if I change the declaration of the age object to use the var keyword, then, the program gets compiled successfully. Because now, the zig compiler detects that we are changing the value of an object that allows this behaviour, because it is an “variable object”.\n\nvar age: u8 = 24;\nage = 25;\n\n\n\n1.4.2 Declaring without an initial value\nBy default, when you declare a new object in Zig, you must give it an initial value. In other words, this means that we have to declare, and, at the same time, initialize every object we create in our source code.\nOn the other hand, you can, in fact, declare a new object in your source code, and not give it an explicit value. But we need to use a special keyword for that, which is the undefined keyword.\nIs important to emphasize that, you should avoid using undefined as much as possible. Because when you use this keyword, you leave your object uninitialized, and, as a consequence, if for some reason, your code use this object while it is uninitialized, then, you will definitely have undefined behaviour and major bugs in your program.\nIn the example below, I’m declaring the age object again. But this time, I do not give it an initial value. The variable is only initialized at the second line of code, where I store the number 25 in this object.\n\nvar age: u8 = undefined;\nage = 25;\n\nHaving these points in mind, just remember that you should avoid as much as possible to use undefined in your code. Always declare and initialize your objects. Because this gives you much more safety in your program. But in case you really need to declare an object without initializing it… the undefined keyword is the way to do it in Zig.\n\n\n1.4.3 There is no such thing as unused objects\nEvery object (being constant or variable) that you declare in Zig must be used in some way. You can give this object to a function call, as a function argument, or, you can use it in another expression to calculate the value of another object, or, you can call a method that belongs to this particular object.\nIt doesn’t matter in which way you use it. As long as you use it. If you try to break this rule, i.e. if your try to declare a object, but not use it, the zig compiler will not compile your Zig source code, and it will issue a error message warning that you have unused objects in your code.\nLet’s demonstrate this with an example. In the source code below, we declare a constant object called age. If you try to compile a simple Zig program with this line of code below, the compiler will return an error as demonstrated below:\n\nconst age = 15;\n\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\nEverytime you declare a new object in Zig, you have two choices:\n\nyou either use the value of this object;\nor you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign this object to a special character in Zig, which is the underscore (_). When you assign an object to a underscore, like in the example below, the zig compiler will automatically discard the value of this particular object.\nYou can see in the example below that, this time, the compiler did not complain about any “unused constant”, and successfully compiled our source code.\n\n// It compiles!\nconst age = 15;\n_ = age;\n\nNow, remember, everytime you assign a particular object to the underscore, this object is essentially destroyed. It is discarded by the compiler. This means that you can no longer use this object further in your code. It doesn’t exist anymore.\nSo if you try to use the constant age in the example below, after we discarded it, you will get a loud error message from the compiler (talking about a “pointless discard”) warning you about this mistake.\n\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n\nt.zig:7:5: error: pointless discard\n    of local constant\nThis same rule applies to variable objects. Every variable object must also be used in some way. And if you assign a variable object to the underscore, this object also get’s discarded, and you can no longer use this object.\n\n\n1.4.4 You must mutate every variable objects\nEvery variable object that you create in your source code must be mutated at some point. In other words, if you declare an object as a variable object, with the keyword var, and you do not change the value of this object at some point in the future, the zig compiler will detect this, and it will raise an error warning you about this mistake.\nThe concept behind this is that every object you create in Zig should be preferably a constant object, unless you really need an object whose value will change during the execution of your program.\nSo, if I try to declare a variable object such as where_i_live below, and I do not change the value of this object in some way, the zig compiler raises an error message with the phrase “variable is never mutated”.\n\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]

From b9d4b94598b9645e161f2ace6d73cfc0026d8752 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sun, 9 Feb 2025 10:58:34 -0300
Subject: [PATCH 059/151] Recompile book with changes

---
 .../01-zig-weird/execute-results/html.json         |  4 ++--
 docs/Chapters/01-zig-weird.html                    | 14 +++++++-------
 docs/search.json                                   |  4 ++--
 3 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/_freeze/Chapters/01-zig-weird/execute-results/html.json b/_freeze/Chapters/01-zig-weird/execute-results/html.json
index 3f48d096..1238c4cd 100644
--- a/_freeze/Chapters/01-zig-weird/execute-results/html.json
+++ b/_freeze/Chapters/01-zig-weird/execute-results/html.json
@@ -1,8 +1,8 @@
 {
-  "hash": "5041be02baff66bca29c690e3dfbfd7c",
+  "hash": "8ffa4a01e784b723e1aaf1806367c53c",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\nlanguage, it is still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. They really make it sometimes hard to debug\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscures the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that get's compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e. it is where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contain Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nTherefore, Zig contains a native build system in it, and\nwe can use this build system to write small scripts in Zig,\nwhich describes the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e. creating new objects)\nare made in Zig. You can create a new object in Zig by using the following syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). At @sec-assignments we talk more about objects in general.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that at @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIs worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt is like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portale C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nOn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOs. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e. the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. Thus, if you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith a \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, operations like accessing the `stdout` (or opening a file) on Windows\ndepends on resources that are available only at *runtime* (you will learn more about compile-time\nversus runtime at @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword at @sec-comptime.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation at a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues \n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described at @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig latter in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig? \nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar in our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentations.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It is a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (at YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e. identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nIn contrast, if you use `var`, then, the object created is a variable object.\nWith `var` you can declare this object in your source code, and then,\nchange the value of this object how many times you want over future points\nin your source code.\n\nSo, using the same code example exposed above, if I change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it is an \"variable object\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIs important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code use this object while it is uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object. \n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e. if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to a special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It is discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also get's discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e. the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\n\nIs worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array. \n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it is a slice that\naccess all elements in the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" at @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth at @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially at @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned at @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e. the start and the end of this range)\nis known at compile-time, the slice object that get's created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nat @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that get's created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e. a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can \ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n```\n:::\n\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat get's created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, the `slice` object have a runtime known range, because the end index of the range\nis not known at compile time. In other words, the size of the array at `buffer` is not known\nat compile time. When we execute this program, the size of the array might be 10, or, it might be 12\ndepending on where we execute it. Therefore, we don't know at compile time if\nthe slice object have a range of size 10, or, a range of size 12.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e. a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented at @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e. `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIs worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e. the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause it is much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e. if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it is a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIs important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig at @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers at @sec-root-file and especially at @sec-assignments.\n- How strings work in Zig at @sec-zig-strings.\n- How to use arrays and slices at @sec-arrays.\n- How to import functionality from other Zig modules at @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* at @sec-structs-and-oop.\n- Basic control flow syntax at @sec-zig-control-flow.\n- Enums at @sec-enum;\n- Pointers and Optionals at @sec-pointer;\n- Error handling with `try` and `catch` at @sec-error-handling;\n- Unit tests at @sec-unittests;\n- Vectors at @sec-vectors-simd;\n- Build System at @sec-build-system;\n\n\n\n\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\nlanguage, it is still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. They really make it sometimes hard to debug\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscures the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that get's compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e. it is where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contain Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nTherefore, Zig contains a native build system in it, and\nwe can use this build system to write small scripts in Zig,\nwhich describes the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e. creating new objects)\nare made in Zig. You can create a new object in Zig by using the following syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). At @sec-assignments we talk more about objects in general.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that at @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIs worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt is like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portable C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nIn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e. the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. Thus, if you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith a \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, operations like accessing the `stdout` (or opening a file) on Windows\ndepends on resources that are available only at *runtime* (you will learn more about compile-time\nversus runtime at @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword at @sec-comptime.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation at a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues \n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described in @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig later in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig? \nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar to our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentation.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It is a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (on YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e. identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nIn contrast, if you use `var`, then, the object created is a variable object.\nWith `var` you can declare this object in your source code, and then,\nchange the value of this object how many times you want over future points\nin your source code.\n\nSo, using the same code example exposed above, if I change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it is an \"variable object\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIs important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code use this object while it is uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object. \n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e. if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to a special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It is discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also get's discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e. the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\n\nIs worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array. \n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it is a slice that\naccess all elements in the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" at @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth at @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially at @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned at @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e. the start and the end of this range)\nis known at compile-time, the slice object that get's created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nat @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that get's created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e. a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can \ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n```\n:::\n\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat get's created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, the `slice` object have a runtime known range, because the end index of the range\nis not known at compile time. In other words, the size of the array at `buffer` is not known\nat compile time. When we execute this program, the size of the array might be 10, or, it might be 12\ndepending on where we execute it. Therefore, we don't know at compile time if\nthe slice object have a range of size 10, or, a range of size 12.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e. a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented at @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e. `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIs worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e. the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause it is much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e. if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it is a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIs important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig at @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers at @sec-root-file and especially at @sec-assignments.\n- How strings work in Zig at @sec-zig-strings.\n- How to use arrays and slices at @sec-arrays.\n- How to import functionality from other Zig modules at @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* at @sec-structs-and-oop.\n- Basic control flow syntax at @sec-zig-control-flow.\n- Enums at @sec-enum;\n- Pointers and Optionals at @sec-pointer;\n- Error handling with `try` and `catch` at @sec-error-handling;\n- Unit tests at @sec-unittests;\n- Vectors at @sec-vectors-simd;\n- Build System at @sec-build-system;\n\n\n\n\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
diff --git a/docs/Chapters/01-zig-weird.html b/docs/Chapters/01-zig-weird.html
index 1bd1fbd3..fed40272 100644
--- a/docs/Chapters/01-zig-weird.html
+++ b/docs/Chapters/01-zig-weird.html
@@ -469,14 +469,14 @@ <h3 data-number="1.2.4" class="anchored" data-anchor-id="sec-compile-code"><span
 </section>
 <section id="sec-compile-run-code" class="level3" data-number="1.2.5">
 <h3 data-number="1.2.5" class="anchored" data-anchor-id="sec-compile-run-code"><span class="header-section-number">1.2.5</span> Compile and execute at the same time</h3>
-<p>On the previous section, I presented the <code>zig build-exe</code> command, which compiles Zig modules into an executable file. However, this means that, in order to execute the executable file, we have to run two different commands. First, the <code>zig build-exe</code> command, and then, we call the executable file created by the compiler.</p>
+<p>In the previous section, I presented the <code>zig build-exe</code> command, which compiles Zig modules into an executable file. However, this means that, in order to execute the executable file, we have to run two different commands. First, the <code>zig build-exe</code> command, and then, we call the executable file created by the compiler.</p>
 <p>But what if we wanted to perform these two steps, all at once, in a single command? We can do that by using the <code>zig run</code> command.</p>
 <div class="sourceCode" id="cb12"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zig</span> run src/main.zig</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <pre><code>Hello, world!</code></pre>
 </section>
 <section id="important-note-for-windows-users" class="level3" data-number="1.2.6">
 <h3 data-number="1.2.6" class="anchored" data-anchor-id="important-note-for-windows-users"><span class="header-section-number">1.2.6</span> Important note for Windows users</h3>
-<p>First of all, this is a Windows-specific thing, and, therefore, does not apply to other operating systems, such as Linux and macOs. In summary, if you have a piece of Zig code that includes some global variables whose initialization rely on runtime resources, then, you might have some troubles while trying to compile this Zig code on Windows.</p>
+<p>First of all, this is a Windows-specific thing, and, therefore, does not apply to other operating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that includes some global variables whose initialization rely on runtime resources, then, you might have some troubles while trying to compile this Zig code on Windows.</p>
 <p>An example of that is accessing the <code>stdout</code> (i.e.&nbsp;the <em>standard output</em> of your system), which is usually done in Zig by using the expression <code>std.io.getStdOut()</code>. Thus, if you use this expression to instantiate a global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows, with a “unable to evaluate comptime expression” error message.</p>
 <p>This failure in the compilation process happens because all global variables in Zig are initialized at <em>compile-time</em>. However, operations like accessing the <code>stdout</code> (or opening a file) on Windows depends on resources that are available only at <em>runtime</em> (you will learn more about compile-time versus runtime at <a href="01-memory.html#sec-compile-time" class="quarto-xref"><span>Section 3.1.1</span></a>).</p>
 <p>For example, if you try to compile this code example on Windows, you will likely get the error message exposed below:</p>
@@ -508,12 +508,12 @@ <h3 data-number="1.2.6" class="anchored" data-anchor-id="important-note-for-wind
 </section>
 <section id="sec-compile-project" class="level3" data-number="1.2.7">
 <h3 data-number="1.2.7" class="anchored" data-anchor-id="sec-compile-project"><span class="header-section-number">1.2.7</span> Compiling the entire project</h3>
-<p>Just as I described at <a href="#sec-project-files" class="quarto-xref"><span>Section 1.2.1</span></a>, as our project grows in size and complexity, we usually prefer to organize the compilation and build process of the project into a build script, using some sort of “build system”.</p>
+<p>Just as I described in <a href="#sec-project-files" class="quarto-xref"><span>Section 1.2.1</span></a>, as our project grows in size and complexity, we usually prefer to organize the compilation and build process of the project into a build script, using some sort of “build system”.</p>
 <p>In other words, as our project grows in size and complexity, the <code>build-exe</code>, <code>build-lib</code> and <code>build-obj</code> commands become harder to use directly. Because then, we start to list multiple and multiple modules at the same time. We also start to add built-in compilation flags to customize the build process for our needs, etc. It becomes a lot of work to write the necessary commands by hand.</p>
 <p>In C/C++ projects, programmers normally opt to use CMake, Ninja, <code>Makefile</code> or <code>configure</code> scripts to organize this process. However, in Zig, we have a native build system in the language itself. So, we can write build scripts in Zig to compile and build Zig projects. Then, all we need to do, is to call the <code>zig build</code> command to build our project.</p>
 <p>So, when you execute the <code>zig build</code> command, the <code>zig</code> compiler will search for a Zig module named <code>build.zig</code> inside your current directory, which should be your build script, containing the necessary code to compile and build your project. If the compiler does find this <code>build.zig</code> file in your directory, then, the compiler will essentially execute a <code>zig run</code> command over this <code>build.zig</code> file, to compile and execute this build script, which in turn, will compile and build your entire project.</p>
 <div class="sourceCode" id="cb18"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb18-1"><a href="#cb18-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zig</span> build</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
-<p>After you execute this “build project” command, a <code>zig-out</code> directory is created in the root of your project directory, where you can find the binary executables and libraries created from your Zig modules accordingly to the build commands that you specified at <code>build.zig</code>. We will talk more about the build system in Zig latter in this book.</p>
+<p>After you execute this “build project” command, a <code>zig-out</code> directory is created in the root of your project directory, where you can find the binary executables and libraries created from your Zig modules accordingly to the build commands that you specified at <code>build.zig</code>. We will talk more about the build system in Zig later in this book.</p>
 <p>In the example below, I’m executing the binary executable named <code>hello_world</code> that was generated by the compiler after the <code>zig build</code> command.</p>
 <div class="sourceCode" id="cb19"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb19-1"><a href="#cb19-1" aria-hidden="true" tabindex="-1"></a><span class="ex">./zig-out/bin/hello_world</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <pre><code>Hello, world!</code></pre>
@@ -541,8 +541,8 @@ <h2 data-number="1.3" class="anchored" data-anchor-id="how-to-learn-zig"><span c
 <li>the <a href="https://github.com/zigtools/zls">Language Protocol implementation for Zig, <code>zls</code></a><a href="#fn16" class="footnote-ref" id="fnref16" role="doc-noteref"><sup>16</sup></a>.</li>
 <li>the <a href="https://github.com/mitchellh/libxev">event-loop library <code>libxev</code></a><a href="#fn17" class="footnote-ref" id="fnref17" role="doc-noteref"><sup>17</sup></a>.</li>
 </ol>
-<p>All these assets are available on GitHub, and this is great, because we can use the GitHub search bar in our advantage, to find Zig code that fits our description. For example, you can always include <code>lang:Zig</code> in the GitHub search bar when you are searching for a particular pattern. This will limit the search to only Zig modules.</p>
-<p>Also, a great alternative is to consult online resources and documentations. Here is a quick list of resources that I personally use from time to time to learn more about the language each day:</p>
+<p>All these assets are available on GitHub, and this is great, because we can use the GitHub search bar to our advantage, to find Zig code that fits our description. For example, you can always include <code>lang:Zig</code> in the GitHub search bar when you are searching for a particular pattern. This will limit the search to only Zig modules.</p>
+<p>Also, a great alternative is to consult online resources and documentation. Here is a quick list of resources that I personally use from time to time to learn more about the language each day:</p>
 <ul>
 <li>Zig Language Reference: <a href="https://ziglang.org/documentation/master/" class="uri">https://ziglang.org/documentation/master/</a>;</li>
 <li>Zig Standard Library Reference: <a href="https://ziglang.org/documentation/master/std/" class="uri">https://ziglang.org/documentation/master/std/</a>;</li>
@@ -553,7 +553,7 @@ <h2 data-number="1.3" class="anchored" data-anchor-id="how-to-learn-zig"><span c
 <li>Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <a href="https://www.youtube.com/@ZigSHOWTIME/videos" class="uri">https://www.youtube.com/@ZigSHOWTIME/videos</a>;</li>
 </ul>
 <p>Another great strategy to learn Zig, or honestly, to learn any language you want, is to practice it by solving exercises. For example, there is a famous repository in the Zig community called <a href="https://ziglings.org">Ziglings</a><a href="#fn18" class="footnote-ref" id="fnref18" role="doc-noteref"><sup>18</sup></a> , which contains more than 100 small exercises that you can solve. It is a repository of tiny programs written in Zig that are currently broken, and your responsibility is to fix these programs, and make them work again.</p>
-<p>A famous tech YouTuber known as <em>The Primeagen</em> also posted some videos (at YouTube) where he solves these exercises from Ziglings. The first video is named <a href="https://www.youtube.com/watch?v=OPuztQfM3Fg&amp;t=2524s&amp;ab_channel=TheVimeagen">“Trying Zig Part 1”</a><a href="#fn19" class="footnote-ref" id="fnref19" role="doc-noteref"><sup>19</sup></a>.</p>
+<p>A famous tech YouTuber known as <em>The Primeagen</em> also posted some videos (on YouTube) where he solves these exercises from Ziglings. The first video is named <a href="https://www.youtube.com/watch?v=OPuztQfM3Fg&amp;t=2524s&amp;ab_channel=TheVimeagen">“Trying Zig Part 1”</a><a href="#fn19" class="footnote-ref" id="fnref19" role="doc-noteref"><sup>19</sup></a>.</p>
 <p>Another great alternative, is to solve the <a href="https://adventofcode.com/">Advent of Code exercises</a><a href="#fn20" class="footnote-ref" id="fnref20" role="doc-noteref"><sup>20</sup></a>. There are people that already took the time to learn and solve the exercises, and they posted their solutions on GitHub as well, so, in case you need some resource to compare while solving the exercises, you can look at these two repositories:</p>
 <ul>
 <li><a href="https://github.com/SpexGuy/Zig-AoC-Template" class="uri">https://github.com/SpexGuy/Zig-AoC-Template</a>;</li>
diff --git a/docs/search.json b/docs/search.json
index 160e2623..09d33825 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -124,7 +124,7 @@
     "href": "Chapters/01-zig-weird.html#hello-world-in-zig",
     "title": "1  Introducing Zig",
     "section": "1.2 Hello world in Zig",
-    "text": "1.2 Hello world in Zig\nWe begin our journey in Zig by creating a small “Hello World” program. To start a new Zig project in your computer, you simply call the init command from the zig compiler. Just create a new directory in your computer, then, init a new Zig project inside this directory, like this:\nmkdir hello_world\ncd hello_world\nzig init\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n\n1.2.1 Understanding the project files\nAfter you run the init command from the zig compiler, some new files are created inside of your current directory. First, a “source” (src) directory is created, containing two files, main.zig and root.zig. Each .zig file is a separate Zig module, which is simply a text file that contains some Zig code.\nBy convention, the main.zig module is where your main function lives. Thus, if you are building an executable program in Zig, you need to declare a main() function, which represents the entrypoint of your program, i.e. it is where the execution of your program begins.\nHowever, if you are building a library (instead of an executable program), then, the normal procedure is to delete this main.zig file and start with the root.zig module. By convention, the root.zig module is the root source file of your library.\ntree .\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\nThe init command also creates two additional files in our working directory: build.zig and build.zig.zon. The first file (build.zig) represents a build script written in Zig. This script is executed when you call the build command from the zig compiler. In other words, this file contain Zig code that executes the necessary steps to build the entire project.\nLow-level languages normally use a compiler to build your source code into binary executables or binary libraries. Nevertheless, this process of compiling your source code and building binary executables or binary libraries from it, became a real challenge in the programming world, once the projects became bigger and bigger. As a result, programmers created “build systems”, which are a second set of tools designed to make this process of compiling and building complex projects, easier.\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja, which are used to build complex C and C++ projects. With these systems, you can write scripts, which are called “build scripts”. They simply are scripts that describes the necessary steps to compile/build your project.\nHowever, these are separate tools, that do not belong to C/C++ compilers, like gcc or clang. As a result, in C/C++ projects, you have not only to install and manage your C/C++ compilers, but you also have to install and manage these build systems separately.\nIn Zig, we don’t need to use a separate set of tools to build our projects, because a build system is embedded inside the language itself. Therefore, Zig contains a native build system in it, and we can use this build system to write small scripts in Zig, which describes the necessary steps to build/compile our Zig project1. So, everything you need to build a complex Zig project is the zig compiler, and nothing more.\nThe second generated file (build.zig.zon) is a JSON-like file, in which you can describe your project, and also, declare a set of dependencies of your project that you want to fetch from the internet. In other words, you can use this build.zig.zon file to include a list of external libraries in your project.\nOne possible way to include an external Zig library in your project, is to manually build and install the library in your system, and just link your source code with the library at the build step of your project.\nHowever, if this external Zig library is available on GitHub for example, and it has a valid build.zig.zon file in root folder of the project, which describes the project, you can easily include this library in your project by simply listing this external library in your build.zig.zon file.\nIn other words, this build.zig.zon file works similarly to the package.json file in Javascript projects, or the Pipfile file in Python projects, or the Cargo.toml file in Rust projects. You can read more about this specific file in a couple of articles on the internet23, and you can also see the expected schema for this build.zig.zon file in a documentation file inside the official repository of Zig4.\n\n\n1.2.2 The file root.zig\nLet’s take a look into the root.zig file. You might have noticed that every line of code with an expression ends with a semicolon (;). This follows the syntax of a C-family programming language5.\nAlso, notice the @import() call at the first line. We use this built-in function to import functionality from other Zig modules into our current module. This @import() function works similarly to the #include pre-processor in C or C++, or, to the import statement in Python or Javascript code. In this example, we are importing the std module, which gives you access to the Zig Standard Library.\nIn this root.zig file, we can also see how assignments (i.e. creating new objects) are made in Zig. You can create a new object in Zig by using the following syntax (const|var) name = value;. In the example below, we are creating two constant objects (std and testing). At Section 1.4 we talk more about objects in general.\n\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n\nFunctions in Zig are declared using the fn keyword. In this root.zig module, we are declaring a function called add(), which has two arguments named a and b. The function returns an integer of the type i32 as result.\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit the type of an object in your code, if this type can be inferred by the zig compiler (we talk more about that at Section 2.4). But there are other situations where you do need to be explicit. For example, you do have to explicitly specify the type of each function argument, and also, the return type of every function that you create in Zig.\nWe specify the type of an object or a function argument in Zig by using a colon character (:) followed by the type after the name of this object/function argument. With the expressions a: i32 and b: i32, we know that both a and b arguments have type i32, which is a signed 32 bit integer. In this part, the syntax in Zig is identical to the syntax in Rust, which also specifies types by using the colon character.\nLastly, we have the return type of the function at the end of the line, before we open the curly braces to start writing the function’s body. In the example above, this type is also a signed 32 bit integer (i32) value.\nNotice that we also have an export keyword before the function declaration. This keyword is similar to the extern keyword in C. It exposes the function to make it available in the library API. Therefore, if you are writing a library for other people to use, you have to expose the functions you write in the public API of this library by using this export keyword. If we removed the export keyword from the add() function declaration, then, this function would be no longer exposed in the library object built by the zig compiler.\n\n\n1.2.3 The main.zig file\nNow that we have learned a lot about Zig’s syntax from the root.zig file, let’s take a look at the main.zig file. A lot of the elements we saw in root.zig are also present in main.zig. But there are some other elements that we haven’t seen yet, so let’s dive in.\nFirst, look at the return type of the main() function in this file. We can see a small change. The return type of the function (void) is accompanied by an exclamation mark (!). This exclamation mark tells us that this main() function might return an error.\nIs worth noting that, a main() function in Zig is allowed to return nothing (void), or an unsigned 8-bit integer (u8) value6, or an error. In other words, you can write your main() function in Zig to return essentially nothing (void), or, if you prefer, you can also write a more C-like main() function, which returns an integer value that usually serves as a “status code” for the process.\nIn this example, the return type annotation of main() indicates that this function can either return nothing (void), or return an error. This exclamation mark in the return type annotation is an interesting and powerful feature of Zig. In summary, if you write a function and something inside the body of this function might return an error, then, you are forced to:\n\neither add the exclamation mark to the return type of the function and make it clear that this function might return an error.\nexplicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through a try catch pattern. Zig does have both try and catch keywords. But they work a little differently than what you’re probably used to in other languages.\nIf we look at the main() function below, you can see that we do have a try keyword on the 5th line. But we do not have a catch keyword in this code. In Zig, we use the try keyword to execute an expression that might return an error, which, in this example, is the stdout.print() expression.\nIn essence, the try keyword executes the expression stdout.print(). If this expression returns a valid value, then, the try keyword does absolutely nothing. It only passes the value forward. It is like if this try keyword was never there. However, if the expression does return an error, then, the try keyword will unwrap the error value, then, it returns this error from the function and also prints the current stack trace to stderr.\nThis might sound weird to you if you come from a high-level language. Because in high-level languages, such as Python, if an error occurs somewhere, this error is automatically returned and the execution of your program will automatically stop even if you don’t want to stop the execution. You are obligated to face the error.\n\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n\nAnother thing that you might have noticed in this code example, is that the main() function is marked with the pub keyword. It marks the main() function as a public function from this module. Every function in your Zig module is by default private to this Zig module and can only be called from within the module. Unless, you explicitly mark this function as a public function with the pub keyword.\nIf you think about it, this pub keyword in Zig does essentially the opposite of what the static keyword do in C/C++. By making a function “public” you allow other Zig modules to access and call this function. A calling Zig module imports another module by using the @import() built-in function, which makes all public functions from the imported module visible to the calling Zig module.\n\n\n1.2.4 Compiling your source code\nYou can compile your Zig modules into a binary executable by running the build-exe command from the zig compiler. You simply list all the Zig modules that you want to build after the build-exe command, separated by spaces. In the example below, we are compiling the module main.zig.\nzig build-exe src/main.zig\nSince we are building an executable, the zig compiler will look for a main() function declared in any of the files that you list after the build-exe command. If the compiler does not find a main() function declared somewhere, a compilation error will be raised, warning about this mistake.\nThe zig compiler also offers a build-lib and build-obj commands, which work the exact same way as the build-exe command. The only difference is that, they compile your Zig modules into a portable C ABI library, or, into object files, respectively.\nIn the case of the build-exe command, a binary executable file is created by the zig compiler in the root directory of your project. If we take a look now at the contents of our current directory, with a simple ls command, we can see the binary file called main that was created by the compiler.\nls\nbuild.zig  build.zig.zon  main  src\nIf I execute this binary executable, I get the “Hello World” message in the terminal , as we expected.\n./main\nHello, world!\n\n\n1.2.5 Compile and execute at the same time\nOn the previous section, I presented the zig build-exe command, which compiles Zig modules into an executable file. However, this means that, in order to execute the executable file, we have to run two different commands. First, the zig build-exe command, and then, we call the executable file created by the compiler.\nBut what if we wanted to perform these two steps, all at once, in a single command? We can do that by using the zig run command.\nzig run src/main.zig\nHello, world!\n\n\n1.2.6 Important note for Windows users\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other operating systems, such as Linux and macOs. In summary, if you have a piece of Zig code that includes some global variables whose initialization rely on runtime resources, then, you might have some troubles while trying to compile this Zig code on Windows.\nAn example of that is accessing the stdout (i.e. the standard output of your system), which is usually done in Zig by using the expression std.io.getStdOut(). Thus, if you use this expression to instantiate a global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows, with a “unable to evaluate comptime expression” error message.\nThis failure in the compilation process happens because all global variables in Zig are initialized at compile-time. However, operations like accessing the stdout (or opening a file) on Windows depends on resources that are available only at runtime (you will learn more about compile-time versus runtime at Section 3.1.1).\nFor example, if you try to compile this code example on Windows, you will likely get the error message exposed below:\n\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\nTo avoid this problem on Windows, we need to force the zig compiler to instantiate this stdout object only at runtime, instead of instantiating it at compile-time. We can achieve that by simply moving the expression to a function body.\nThis solves the problem because all expressions that are inside a function body in Zig are evaluated only at runtime, unless you use the comptime keyword explicitly to change this behaviour. You will learn more about this comptime keyword at Section 12.1.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nHello\nYou can read more details about this Windows-specific limitation at a couple of GitHub issues opened at the official Zig repository. More specifically, the issues 17186 7 and 19864 8.\n\n\n1.2.7 Compiling the entire project\nJust as I described at Section 1.2.1, as our project grows in size and complexity, we usually prefer to organize the compilation and build process of the project into a build script, using some sort of “build system”.\nIn other words, as our project grows in size and complexity, the build-exe, build-lib and build-obj commands become harder to use directly. Because then, we start to list multiple and multiple modules at the same time. We also start to add built-in compilation flags to customize the build process for our needs, etc. It becomes a lot of work to write the necessary commands by hand.\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, Makefile or configure scripts to organize this process. However, in Zig, we have a native build system in the language itself. So, we can write build scripts in Zig to compile and build Zig projects. Then, all we need to do, is to call the zig build command to build our project.\nSo, when you execute the zig build command, the zig compiler will search for a Zig module named build.zig inside your current directory, which should be your build script, containing the necessary code to compile and build your project. If the compiler does find this build.zig file in your directory, then, the compiler will essentially execute a zig run command over this build.zig file, to compile and execute this build script, which in turn, will compile and build your entire project.\nzig build\nAfter you execute this “build project” command, a zig-out directory is created in the root of your project directory, where you can find the binary executables and libraries created from your Zig modules accordingly to the build commands that you specified at build.zig. We will talk more about the build system in Zig latter in this book.\nIn the example below, I’m executing the binary executable named hello_world that was generated by the compiler after the zig build command.\n./zig-out/bin/hello_world\nHello, world!",
+    "text": "1.2 Hello world in Zig\nWe begin our journey in Zig by creating a small “Hello World” program. To start a new Zig project in your computer, you simply call the init command from the zig compiler. Just create a new directory in your computer, then, init a new Zig project inside this directory, like this:\nmkdir hello_world\ncd hello_world\nzig init\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n\n1.2.1 Understanding the project files\nAfter you run the init command from the zig compiler, some new files are created inside of your current directory. First, a “source” (src) directory is created, containing two files, main.zig and root.zig. Each .zig file is a separate Zig module, which is simply a text file that contains some Zig code.\nBy convention, the main.zig module is where your main function lives. Thus, if you are building an executable program in Zig, you need to declare a main() function, which represents the entrypoint of your program, i.e. it is where the execution of your program begins.\nHowever, if you are building a library (instead of an executable program), then, the normal procedure is to delete this main.zig file and start with the root.zig module. By convention, the root.zig module is the root source file of your library.\ntree .\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\nThe init command also creates two additional files in our working directory: build.zig and build.zig.zon. The first file (build.zig) represents a build script written in Zig. This script is executed when you call the build command from the zig compiler. In other words, this file contain Zig code that executes the necessary steps to build the entire project.\nLow-level languages normally use a compiler to build your source code into binary executables or binary libraries. Nevertheless, this process of compiling your source code and building binary executables or binary libraries from it, became a real challenge in the programming world, once the projects became bigger and bigger. As a result, programmers created “build systems”, which are a second set of tools designed to make this process of compiling and building complex projects, easier.\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja, which are used to build complex C and C++ projects. With these systems, you can write scripts, which are called “build scripts”. They simply are scripts that describes the necessary steps to compile/build your project.\nHowever, these are separate tools, that do not belong to C/C++ compilers, like gcc or clang. As a result, in C/C++ projects, you have not only to install and manage your C/C++ compilers, but you also have to install and manage these build systems separately.\nIn Zig, we don’t need to use a separate set of tools to build our projects, because a build system is embedded inside the language itself. Therefore, Zig contains a native build system in it, and we can use this build system to write small scripts in Zig, which describes the necessary steps to build/compile our Zig project1. So, everything you need to build a complex Zig project is the zig compiler, and nothing more.\nThe second generated file (build.zig.zon) is a JSON-like file, in which you can describe your project, and also, declare a set of dependencies of your project that you want to fetch from the internet. In other words, you can use this build.zig.zon file to include a list of external libraries in your project.\nOne possible way to include an external Zig library in your project, is to manually build and install the library in your system, and just link your source code with the library at the build step of your project.\nHowever, if this external Zig library is available on GitHub for example, and it has a valid build.zig.zon file in root folder of the project, which describes the project, you can easily include this library in your project by simply listing this external library in your build.zig.zon file.\nIn other words, this build.zig.zon file works similarly to the package.json file in Javascript projects, or the Pipfile file in Python projects, or the Cargo.toml file in Rust projects. You can read more about this specific file in a couple of articles on the internet23, and you can also see the expected schema for this build.zig.zon file in a documentation file inside the official repository of Zig4.\n\n\n1.2.2 The file root.zig\nLet’s take a look into the root.zig file. You might have noticed that every line of code with an expression ends with a semicolon (;). This follows the syntax of a C-family programming language5.\nAlso, notice the @import() call at the first line. We use this built-in function to import functionality from other Zig modules into our current module. This @import() function works similarly to the #include pre-processor in C or C++, or, to the import statement in Python or Javascript code. In this example, we are importing the std module, which gives you access to the Zig Standard Library.\nIn this root.zig file, we can also see how assignments (i.e. creating new objects) are made in Zig. You can create a new object in Zig by using the following syntax (const|var) name = value;. In the example below, we are creating two constant objects (std and testing). At Section 1.4 we talk more about objects in general.\n\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n\nFunctions in Zig are declared using the fn keyword. In this root.zig module, we are declaring a function called add(), which has two arguments named a and b. The function returns an integer of the type i32 as result.\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit the type of an object in your code, if this type can be inferred by the zig compiler (we talk more about that at Section 2.4). But there are other situations where you do need to be explicit. For example, you do have to explicitly specify the type of each function argument, and also, the return type of every function that you create in Zig.\nWe specify the type of an object or a function argument in Zig by using a colon character (:) followed by the type after the name of this object/function argument. With the expressions a: i32 and b: i32, we know that both a and b arguments have type i32, which is a signed 32 bit integer. In this part, the syntax in Zig is identical to the syntax in Rust, which also specifies types by using the colon character.\nLastly, we have the return type of the function at the end of the line, before we open the curly braces to start writing the function’s body. In the example above, this type is also a signed 32 bit integer (i32) value.\nNotice that we also have an export keyword before the function declaration. This keyword is similar to the extern keyword in C. It exposes the function to make it available in the library API. Therefore, if you are writing a library for other people to use, you have to expose the functions you write in the public API of this library by using this export keyword. If we removed the export keyword from the add() function declaration, then, this function would be no longer exposed in the library object built by the zig compiler.\n\n\n1.2.3 The main.zig file\nNow that we have learned a lot about Zig’s syntax from the root.zig file, let’s take a look at the main.zig file. A lot of the elements we saw in root.zig are also present in main.zig. But there are some other elements that we haven’t seen yet, so let’s dive in.\nFirst, look at the return type of the main() function in this file. We can see a small change. The return type of the function (void) is accompanied by an exclamation mark (!). This exclamation mark tells us that this main() function might return an error.\nIs worth noting that, a main() function in Zig is allowed to return nothing (void), or an unsigned 8-bit integer (u8) value6, or an error. In other words, you can write your main() function in Zig to return essentially nothing (void), or, if you prefer, you can also write a more C-like main() function, which returns an integer value that usually serves as a “status code” for the process.\nIn this example, the return type annotation of main() indicates that this function can either return nothing (void), or return an error. This exclamation mark in the return type annotation is an interesting and powerful feature of Zig. In summary, if you write a function and something inside the body of this function might return an error, then, you are forced to:\n\neither add the exclamation mark to the return type of the function and make it clear that this function might return an error.\nexplicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through a try catch pattern. Zig does have both try and catch keywords. But they work a little differently than what you’re probably used to in other languages.\nIf we look at the main() function below, you can see that we do have a try keyword on the 5th line. But we do not have a catch keyword in this code. In Zig, we use the try keyword to execute an expression that might return an error, which, in this example, is the stdout.print() expression.\nIn essence, the try keyword executes the expression stdout.print(). If this expression returns a valid value, then, the try keyword does absolutely nothing. It only passes the value forward. It is like if this try keyword was never there. However, if the expression does return an error, then, the try keyword will unwrap the error value, then, it returns this error from the function and also prints the current stack trace to stderr.\nThis might sound weird to you if you come from a high-level language. Because in high-level languages, such as Python, if an error occurs somewhere, this error is automatically returned and the execution of your program will automatically stop even if you don’t want to stop the execution. You are obligated to face the error.\n\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n\nAnother thing that you might have noticed in this code example, is that the main() function is marked with the pub keyword. It marks the main() function as a public function from this module. Every function in your Zig module is by default private to this Zig module and can only be called from within the module. Unless, you explicitly mark this function as a public function with the pub keyword.\nIf you think about it, this pub keyword in Zig does essentially the opposite of what the static keyword do in C/C++. By making a function “public” you allow other Zig modules to access and call this function. A calling Zig module imports another module by using the @import() built-in function, which makes all public functions from the imported module visible to the calling Zig module.\n\n\n1.2.4 Compiling your source code\nYou can compile your Zig modules into a binary executable by running the build-exe command from the zig compiler. You simply list all the Zig modules that you want to build after the build-exe command, separated by spaces. In the example below, we are compiling the module main.zig.\nzig build-exe src/main.zig\nSince we are building an executable, the zig compiler will look for a main() function declared in any of the files that you list after the build-exe command. If the compiler does not find a main() function declared somewhere, a compilation error will be raised, warning about this mistake.\nThe zig compiler also offers a build-lib and build-obj commands, which work the exact same way as the build-exe command. The only difference is that, they compile your Zig modules into a portable C ABI library, or, into object files, respectively.\nIn the case of the build-exe command, a binary executable file is created by the zig compiler in the root directory of your project. If we take a look now at the contents of our current directory, with a simple ls command, we can see the binary file called main that was created by the compiler.\nls\nbuild.zig  build.zig.zon  main  src\nIf I execute this binary executable, I get the “Hello World” message in the terminal , as we expected.\n./main\nHello, world!\n\n\n1.2.5 Compile and execute at the same time\nIn the previous section, I presented the zig build-exe command, which compiles Zig modules into an executable file. However, this means that, in order to execute the executable file, we have to run two different commands. First, the zig build-exe command, and then, we call the executable file created by the compiler.\nBut what if we wanted to perform these two steps, all at once, in a single command? We can do that by using the zig run command.\nzig run src/main.zig\nHello, world!\n\n\n1.2.6 Important note for Windows users\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other operating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that includes some global variables whose initialization rely on runtime resources, then, you might have some troubles while trying to compile this Zig code on Windows.\nAn example of that is accessing the stdout (i.e. the standard output of your system), which is usually done in Zig by using the expression std.io.getStdOut(). Thus, if you use this expression to instantiate a global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows, with a “unable to evaluate comptime expression” error message.\nThis failure in the compilation process happens because all global variables in Zig are initialized at compile-time. However, operations like accessing the stdout (or opening a file) on Windows depends on resources that are available only at runtime (you will learn more about compile-time versus runtime at Section 3.1.1).\nFor example, if you try to compile this code example on Windows, you will likely get the error message exposed below:\n\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\nTo avoid this problem on Windows, we need to force the zig compiler to instantiate this stdout object only at runtime, instead of instantiating it at compile-time. We can achieve that by simply moving the expression to a function body.\nThis solves the problem because all expressions that are inside a function body in Zig are evaluated only at runtime, unless you use the comptime keyword explicitly to change this behaviour. You will learn more about this comptime keyword at Section 12.1.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nHello\nYou can read more details about this Windows-specific limitation at a couple of GitHub issues opened at the official Zig repository. More specifically, the issues 17186 7 and 19864 8.\n\n\n1.2.7 Compiling the entire project\nJust as I described in Section 1.2.1, as our project grows in size and complexity, we usually prefer to organize the compilation and build process of the project into a build script, using some sort of “build system”.\nIn other words, as our project grows in size and complexity, the build-exe, build-lib and build-obj commands become harder to use directly. Because then, we start to list multiple and multiple modules at the same time. We also start to add built-in compilation flags to customize the build process for our needs, etc. It becomes a lot of work to write the necessary commands by hand.\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, Makefile or configure scripts to organize this process. However, in Zig, we have a native build system in the language itself. So, we can write build scripts in Zig to compile and build Zig projects. Then, all we need to do, is to call the zig build command to build our project.\nSo, when you execute the zig build command, the zig compiler will search for a Zig module named build.zig inside your current directory, which should be your build script, containing the necessary code to compile and build your project. If the compiler does find this build.zig file in your directory, then, the compiler will essentially execute a zig run command over this build.zig file, to compile and execute this build script, which in turn, will compile and build your entire project.\nzig build\nAfter you execute this “build project” command, a zig-out directory is created in the root of your project directory, where you can find the binary executables and libraries created from your Zig modules accordingly to the build commands that you specified at build.zig. We will talk more about the build system in Zig later in this book.\nIn the example below, I’m executing the binary executable named hello_world that was generated by the compiler after the zig build command.\n./zig-out/bin/hello_world\nHello, world!",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -134,7 +134,7 @@
     "href": "Chapters/01-zig-weird.html#how-to-learn-zig",
     "title": "1  Introducing Zig",
     "section": "1.3 How to learn Zig?",
-    "text": "1.3 How to learn Zig?\nWhat are the best strategies to learn Zig? First of all, of course this book will help you a lot on your journey through Zig. But you will also need some extra resources if you want to be really good at Zig.\nAs a first tip, you can join a community with Zig programmers to get some help , when you need it:\n\nReddit forum: https://www.reddit.com/r/Zig/;\nZiggit community: https://ziggit.dev/;\nDiscord, Slack, Telegram, and others: https://github.com/ziglang/zig/wiki/Community;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try to read Zig code often, and things will become more clear. A C/C++ programmer would also probably give you this same tip. Because this strategy really works!\nNow, where can you find Zig code to read? I personally think that, the best way of reading Zig code is to read the source code of the Zig Standard Library. The Zig Standard Library is available at the lib/std folder9 on the official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\nAlso, a great alternative is to read code from other large Zig codebases, such as:\n\nthe Javascript runtime Bun10.\nthe game engine Mach11.\na LLama 2 LLM model implementation in Zig12.\nthe financial transactions database tigerbeetle13.\nthe command-line arguments parser zig-clap14.\nthe UI framework capy15.\nthe Language Protocol implementation for Zig, zls16.\nthe event-loop library libxev17.\n\nAll these assets are available on GitHub, and this is great, because we can use the GitHub search bar in our advantage, to find Zig code that fits our description. For example, you can always include lang:Zig in the GitHub search bar when you are searching for a particular pattern. This will limit the search to only Zig modules.\nAlso, a great alternative is to consult online resources and documentations. Here is a quick list of resources that I personally use from time to time to learn more about the language each day:\n\nZig Language Reference: https://ziglang.org/documentation/master/;\nZig Standard Library Reference: https://ziglang.org/documentation/master/std/;\nZig Guide: https://zig.guide/;\nKarl Seguin Blog: https://www.openmymind.net/;\nZig News: https://zig.news/;\nRead the code written by one of the Zig core team members: https://github.com/kubkon;\nSome livecoding sessions are transmitted in the Zig Showtime Youtube Channel: https://www.youtube.com/@ZigSHOWTIME/videos;\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want, is to practice it by solving exercises. For example, there is a famous repository in the Zig community called Ziglings18 , which contains more than 100 small exercises that you can solve. It is a repository of tiny programs written in Zig that are currently broken, and your responsibility is to fix these programs, and make them work again.\nA famous tech YouTuber known as The Primeagen also posted some videos (at YouTube) where he solves these exercises from Ziglings. The first video is named “Trying Zig Part 1”19.\nAnother great alternative, is to solve the Advent of Code exercises20. There are people that already took the time to learn and solve the exercises, and they posted their solutions on GitHub as well, so, in case you need some resource to compare while solving the exercises, you can look at these two repositories:\n\nhttps://github.com/SpexGuy/Zig-AoC-Template;\nhttps://github.com/fjebaker/advent-of-code-2022;",
+    "text": "1.3 How to learn Zig?\nWhat are the best strategies to learn Zig? First of all, of course this book will help you a lot on your journey through Zig. But you will also need some extra resources if you want to be really good at Zig.\nAs a first tip, you can join a community with Zig programmers to get some help , when you need it:\n\nReddit forum: https://www.reddit.com/r/Zig/;\nZiggit community: https://ziggit.dev/;\nDiscord, Slack, Telegram, and others: https://github.com/ziglang/zig/wiki/Community;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try to read Zig code often, and things will become more clear. A C/C++ programmer would also probably give you this same tip. Because this strategy really works!\nNow, where can you find Zig code to read? I personally think that, the best way of reading Zig code is to read the source code of the Zig Standard Library. The Zig Standard Library is available at the lib/std folder9 on the official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\nAlso, a great alternative is to read code from other large Zig codebases, such as:\n\nthe Javascript runtime Bun10.\nthe game engine Mach11.\na LLama 2 LLM model implementation in Zig12.\nthe financial transactions database tigerbeetle13.\nthe command-line arguments parser zig-clap14.\nthe UI framework capy15.\nthe Language Protocol implementation for Zig, zls16.\nthe event-loop library libxev17.\n\nAll these assets are available on GitHub, and this is great, because we can use the GitHub search bar to our advantage, to find Zig code that fits our description. For example, you can always include lang:Zig in the GitHub search bar when you are searching for a particular pattern. This will limit the search to only Zig modules.\nAlso, a great alternative is to consult online resources and documentation. Here is a quick list of resources that I personally use from time to time to learn more about the language each day:\n\nZig Language Reference: https://ziglang.org/documentation/master/;\nZig Standard Library Reference: https://ziglang.org/documentation/master/std/;\nZig Guide: https://zig.guide/;\nKarl Seguin Blog: https://www.openmymind.net/;\nZig News: https://zig.news/;\nRead the code written by one of the Zig core team members: https://github.com/kubkon;\nSome livecoding sessions are transmitted in the Zig Showtime Youtube Channel: https://www.youtube.com/@ZigSHOWTIME/videos;\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want, is to practice it by solving exercises. For example, there is a famous repository in the Zig community called Ziglings18 , which contains more than 100 small exercises that you can solve. It is a repository of tiny programs written in Zig that are currently broken, and your responsibility is to fix these programs, and make them work again.\nA famous tech YouTuber known as The Primeagen also posted some videos (on YouTube) where he solves these exercises from Ziglings. The first video is named “Trying Zig Part 1”19.\nAnother great alternative, is to solve the Advent of Code exercises20. There are people that already took the time to learn and solve the exercises, and they posted their solutions on GitHub as well, so, in case you need some resource to compare while solving the exercises, you can look at these two repositories:\n\nhttps://github.com/SpexGuy/Zig-AoC-Template;\nhttps://github.com/fjebaker/advent-of-code-2022;",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]

From cf894390924eb48cb38015bd1219ae07d0edca41 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sun, 9 Feb 2025 11:10:52 -0300
Subject: [PATCH 060/151] Update contributors list

---
 .../01-memory/execute-results/html.json       |  8 +++---
 .../02-debugging/execute-results/html.json    |  4 +--
 .../03-structs/execute-results/html.json      |  4 +--
 _freeze/index/execute-results/html.json       |  2 +-
 contributors.txt                              |  2 ++
 docs/Chapters/01-memory.html                  | 26 +++++++++----------
 docs/Chapters/02-debugging.html               |  8 +++---
 docs/Chapters/03-structs.html                 | 13 +++++-----
 docs/index.html                               |  8 +++---
 docs/search.json                              | 22 ++++++++--------
 10 files changed, 50 insertions(+), 47 deletions(-)

diff --git a/_freeze/Chapters/01-memory/execute-results/html.json b/_freeze/Chapters/01-memory/execute-results/html.json
index 29ccbc27..10d58cd7 100644
--- a/_freeze/Chapters/01-memory/execute-results/html.json
+++ b/_freeze/Chapters/01-memory/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "0a086161bb0eedee4b92cc3e013bd2f2",
+  "hash": "fb71dc5e7458622bbc561ed2983d0bb1",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Memory and Allocators\n\n\nIn this chapter, we will talk about memory. How does Zig control memory? What\ncommon tools are used? Are there any important aspects that make memory\ndifferent/special in Zig? You will find the answers here.\n\nComputers fundamentally rely on memory to function. This memory acts as a temporary storage\nspace for the data and values generated during computations. Without memory, the core\nconcepts of \"variables\" and \"objects\" in programming languages would be impossible.\n\n\n\n\n## Memory spaces\n\nEvery object that you create in your Zig source code needs to be stored somewhere,\nin your computer's memory. Depending on where and how you define your object, Zig\nwill use a different \"memory space\", or a different\ntype of memory to store this object.\n\nEach type of memory normally serves for different purposes.\nIn Zig, there are 3 types of memory (or 3 different memory spaces) that we care about. They are:\n\n- Global data register (or the \"global data section\");\n- Stack;\n- Heap;\n\n\n### Compile-time known versus runtime known {#sec-compile-time}\n\nOne strategy that Zig uses to decide where it will store each object that you declare, is by looking\nat the value of this particular object. More specifically, by investigating if this value is\nknown at \"compile-time\" or at \"runtime\".\n\nWhen you write a program in Zig, the values of some of the objects that you write in your program are *known\nat compile time*. Meaning that, when you compile your Zig source code, during the compilation process,\nthe `zig` compiler can figure out the exact value of a particular object\nthat exists in your source code.\nKnowing the length (or the size) of each object is also important. So the length (or the size) of each object that you write in your program is,\nin some cases, *known at compile time*.\n\nThe `zig` compiler cares more about knowing the length (or the size) of a particular object\n, than to know its actual value. But, if the `zig` compiler knows the value of the object, then, it\nautomatically knows the size of this object. Because it can simply calculate the\nsize of the object by looking at the size of the value.\n\nTherefore, the priority for the `zig` compiler is to discover the size of each object in your source code.\nIf the value of the object in question is known at compile-time, then, the `zig` compiler\nautomatically knows the size/length of this object. But if the value of this object is not\nknown at compile-time, then, the size of this object is only known at compile-time if,\nand only if, the type of this object has a known fixed size.\n\nIn order for a type to have a known fixed size, this type must have data members whose size is fixed.\nIf this type includes, for example, a variable sized array in it, then, this type does not have a known\nfixed size. Because this array can have any size at runtime\n(i.e. it can be an array of 2 elements, or 50 elements, or 1 thousand elements, etc.).\n\nFor example, a string object, which internally is an array of constant u8 values (`[]const u8`)\nhas a variable size. It can be a string object with 100 or 500 characters in it. If we do not\nknow at compile-time, which exact string will be stored inside this string object, then, we cannot calculate\nthe size of this string object at compile-time. So, any type, or any struct declaration that you make, that\nincludes a string data member that does not have an explicit fixed size, makes this type, or this\nnew struct that you are declaring, a type that does not have a known fixed size at compile-time.\n\nIn contrast, if the type of this struct that you are declaring, includes a data member that is an array,\nbut this array has a known fixed size, like `[60]u8` (which declares an array of 60 `u8` values), then,\nthis type, or, this struct that you are declaring, becomes a type with a known fixed size at compile-time.\nAnd because of that, in this case, the `zig` compiler does not need to know at compile-time the exact value of\nany object of this type. Since the compiler can find the necessary size to store this object by\nlooking at the size of its type.\n\n\nLet's look at an example. In the source code below, we have two constant objects (`name` and `array`) declared.\nBecause the values of these particular objects are written down, in the source code itself (`\"Pedro\"`\nand the number sequence from 1 to 4), the `zig` compiler can easily discover the values of these constant\nobjects (`name` and `array`) during the compilation process.\nThis is what \"known at compile time\" means. It refers to any object that you have in your Zig source code\nwhose value can be identified at compile time.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn input_length(input: []const u8) usize {\n    const n = input.len;\n    return n;\n}\n\npub fn main() !void {\n    const name = \"Pedro\";\n    const array = [_]u8{1, 2, 3, 4};\n    _ = name; _ = array;\n}\n```\n:::\n\n\n\n\n\nThe other side of the spectrum are objects whose values are not known at compile time.\nFunction arguments are a classic example of this. Because the value of each function\nargument depends on the value that you assign to this particular argument,\nwhen you call the function.\n\nFor example, the function `input_length()` contains an argument named `input`, which is an array of constant `u8` integers (`[]const u8`).\nIt is impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length\nof this particular argument. Because it is an array that do not have a fixed size specified explicitly in the argument type annotation.\n\nSo, we know that this `input` argument will be an array of `u8` integers. But we do not know at compile-time, its value, and neither his size.\nThis information is known only at runtime, which is the period of time when you program is executed.\nAs a consequence, the value of the expression `input.len` is also known only at runtime.\nThis is an intrinsic characteristic of any function. Just remember that the value of function arguments is usually not \"compile-time known\".\n\nHowever, as I mentioned earlier, what really matters to the compiler is to know the size of the object\nat compile-time, and not necessarily its value. So, although we don't know the value of the object `n`, which is the result of the expression\n`input.len`, at compile-time, we do know its size. Because the expression `input.len` always returns a value of type `usize`,\nand the type `usize` has a known fixed size.\n\n\n\n### Global data register\n\nThe global data register is a specific section of the executable of your Zig program, that is responsible\nfor storing any value that is known at compile time.\n\nEvery constant object whose value is known at compile time that you declare in your source code,\nis stored in the global data register. Also, every literal value that you write in your source code,\nsuch as the string `\"this is a string\"`, or the integer `10`, or a boolean value such as `true`,\nis also stored in the global data register.\n\nHonestly, you don't need to care much about this memory space. Because you can't control it,\nyou can't deliberately access it or use it for your own purposes.\nAlso, this memory space does not affect the logic of your program.\nIt simply exists in your program.\n\n\n### Stack vs Heap\n\nIf you are familiar with system's programming, or just low-level programming in general, you\nprobably have heard of the \"duel\" between Stack vs Heap. These are two different types of memory,\nor different memory spaces, which are both available in Zig.\n\nThese two types of memory don't actually duel with\neach other. This is a common mistake that beginners have, when seeing \"x vs y\" styles of\ntabloid headlines. These two types of memory are actually complementary to each other.\nSo, in almost every Zig program that you ever write, you will likely use a combination of both.\nI will describe each memory space in detail over the next sections. But for now, I just want to\nstablish the main difference between these two types of memory.\n\nIn essence, the stack memory is normally used to store values whose length is fixed and known\nat compile time. In contrast, the heap memory is a *dynamic* type of memory space, meaning that, it is\nused to store values whose length might grow during the execution (runtime) of your program [@jenny2022].\n\nLengths that grow during runtime are intrinsically associated with \"runtime known\" type of values.\nIn other words, if you have an object whose length might grow during runtime, then, the length\nof this object becomes not known at compile time. If the length is not known at compile-time,\nthe value of this object also becomes not known at compile-time.\nThese types of objects should be stored in the heap memory space, which is\na dynamic memory space, which can grow or shrink to fit the size of your objects.\n\n\n\n### Stack {#sec-stack}\n\nThe stack is a type of memory that uses the power of the *stack data structure*, hence the name. \nA \"stack\" is a type of *data structure* that uses a \"last in, first out\" (LIFO) mechanism to store the values\nyou give it to. I imagine you are familiar with this data structure.\nBut, if you are not, the [Wikipedia page](https://en.wikipedia.org/wiki/Stack_(abstract_data_type))[^wiki-stack]\n, or, the [Geeks For Geeks page](https://www.geeksforgeeks.org/stack-data-structure/)[^geek-stack] are both\nexcellent and easy resources to fully understand how this data structure works.\n\n[^wiki-stack]: <https://en.wikipedia.org/wiki/Stack_(abstract_data_type)>\n[^geek-stack]: <https://www.geeksforgeeks.org/stack-data-structure/>\n\nSo, the stack memory space is a type of memory that stores values using a stack data structure.\nIt adds and removes values from the memory by following a \"last in, first out\" (LIFO) principle.\n\nEvery time you make a function call in Zig, an amount of space in the stack is\nreserved for this particular function call [@jenny2022; @zigdocs].\nThe value of each function argument given to the function in this function call is stored in this\nstack space. Also, every local object that you declare inside the function scope is\nusually stored in this same stack space.\n\n\nLooking at the example below, the object `result` is a local object declared inside the scope of the `add()`\nfunction. Because of that, this object is stored inside the stack space reserved for the `add()` function.\nThe `r` object (which is declared outside of the `add()` function scope) is also stored in the stack.\nBut since it is declared in the \"outer\" scope, this object is stored in the\nstack space that belongs to this outer scope.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn add(x: u8, y: u8) u8 {\n    const result = x + y;\n    return result;\n}\n\npub fn main() !void {\n    const r = add(5, 27);\n    _ = r;\n}\n```\n:::\n\n\n\n\n\n\nSo, any object that you declare inside the scope of a function is always stored inside\nthe space that was reserved for that particular function in the stack memory. This\nalso counts for any object declared inside the scope of your `main()` function for example.\nAs you would expect, in this case, they\nare stored inside the stack space reserved for the `main()` function.\n\nOne very important detail about the stack memory is that **it frees itself automatically**.\nThis is very important, remember that. When objects are stored in the stack memory,\nyou don't have the work (or the responsibility) of freeing/destroying these objects.\nBecause they will be automatically destroyed once the stack space is freed at the end of the function scope.\n\nSo, once the function call returns (or ends, if you prefer to call it this way)\nthe space that was reserved in the stack is destroyed, and all of the objects that were in that space goes away with it.\nThis mechanism exists because this space, and the objects within it, are not necessary anymore,\nsince the function \"finished its business\".\nUsing the `add()` function that we exposed above as an example, it means that the object `result` is automatically\ndestroyed once the function returns.\n\n::: {.callout-important}\nLocal objects that are stored in the stack space of a function are automatically\nfreed/destroyed at the end of the function scope.\n:::\n\n\nThis same logic applies to any other special structure in Zig that have its own scope by surrounding\nit with curly braces (`{}`).\nFor loops, while loops, if else statements, etc. For example, if you declare any local\nobject in the scope of a for loop, this local object is accessible only within the scope\nof this particular for loop. Because once the scope of this for loop ends, the space in the stack\nreserved for this for loop is freed.\nThe example below demonstrates this idea.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This does not compile successfully!\nconst a = [_]u8{0, 1, 2, 3, 4};\nfor (0..a.len) |i| {\n    const index = i;\n    _ = index;\n}\n// Trying to use an object that was\n// declared in the for loop scope,\n// and that does not exist anymore.\nstd.debug.print(\"{d}\\n\", index);\n```\n:::\n\n\n\n\n\n\n\nOne important consequence of this mechanism is that, once the function returns, you can no longer access any memory\naddress that was inside the space in the stack reserved for this particular function. Because this space was\ndestroyed. This means that, if this local object is stored in the stack,\nyou cannot make a function that **returns a pointer to this object**.\n\nThink about that for a second. If all local objects in the stack are destroyed at the end of the function scope, why\nwould you even consider returning a pointer to one of these objects? This pointer is at best,\ninvalid, or, more likely, \"undefined\".\n\nConclusion, it is totally fine to write a function that returns the local object\nitself as result, because then, you return the value of that object as the result.\nBut, if this local object is stored in the stack, you should never write a function\nthat returns a pointer to this local object. Because the memory address pointed by the pointer\nno longer exists.\n\n\nSo, using again the `add()` function as an example, if you rewrite this function so that it\nreturns a pointer to the local object `result`, the `zig` compiler will actually compile\nyour program, with no warnings or errors. At first glance, it looks that this is good code\nthat works as expected. But this is a lie!\n\nIf you try to take a look at the value inside of the `r` object,\nor, if you try to use this `r` object in another expression\nor function call, then, you would have undefined behaviour, and major\nbugs in your program [@zigdocs, see \"Lifetime and Ownership\"[^life] and \"Undefined Behaviour\"[^undef] sections].\n\n[^life]: <https://ziglang.org/documentation/master/#Lifetime-and-Ownership>\n[^undef]: <https://ziglang.org/documentation/master/#Undefined-Behavior>\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn add(x: u8, y: u8) *const u8 {\n    const result = x + y;\n    return &result;\n}\n\npub fn main() !void {\n    // This code compiles successfully. But it has\n    // undefined behaviour. Never do this!!!\n    // The `r` object is undefined!\n    const r = add(5, 27); _ = r;\n}\n```\n:::\n\n\n\n\n\nThis \"invalid pointer to stack variable\" problem is very known across many programming language communities.\nIf you try to do the same thing, for example, in a C or C++ program (i.e. returning an address to\na local object stored in the stack), you would also get undefined behaviour\nin the program.\n\n::: {.callout-important}\nIf a local object in your function is stored in the stack, you should never\nreturn a pointer to this local object from the function. Because\nthis pointer will always become undefined after the function returns, since the stack space of the function\nis destroyed at the end of its scope.\n:::\n\nBut what if you really need to use this local object in some way after your function returns?\nHow can you do this? The answer is: \"in the same you would do if this was a C or C++ program. By returning\nan address to an object stored in the heap\". The heap memory has a much more flexible lifecycle,\nand allows you to get a valid pointer to a local object of a function that already returned\nfrom its scope.\n\n\n### Heap {#sec-heap}\n\nOne important limitation of the stack, is that, only objects whose length/size is known at compile-time can be\nstored in it. In contrast, the heap is a much more dynamic\n(and flexible) type of memory. It is the perfect type of memory to use\nfor objects whose size/length might grow during the execution of your program.\n\nVirtually any application that behaves as a server is a classic use case of the heap.\nA HTTP server, a SSH server, a DNS server, a LSP server, ... any type of server.\nIn summary, a server is a type of application that runs for long periods of time,\nand that serves (or \"deals with\") any incoming request that reaches this particular server.\n\nThe heap is a good choice for this type of system, mainly because the server does not know upfront\nhow many requests it will receive from users, while it is active. It could be one single request,\nor, 5 thousand requests, or, it could also be zero requests.\nThe server needs to have the ability to allocate and manage its memory according to how many requests it receives.\n\nAnother key difference between the stack and the heap, is that the heap is a type\nof memory that you, the programmer, have complete control over. This makes the heap a\nmore flexible type of memory, but it also makes it harder to work with. Because you,\nthe programmer, is responsible for managing everything related to it. Including where the memory is allocated,\nhow much memory is allocated, and where this memory is freed.\n\n> Unlike stack memory, heap memory is allocated explicitly by programmers and it won’t be deallocated until it is explicitly freed [@jenny2022].\n\nTo store an object in the heap, you, the programmer, needs to explicitly tells Zig to do so,\nby using an allocator to allocate some space in the heap. At @sec-allocators, I will present how you can use allocators to allocate memory\nin Zig.\n\n::: {.callout-important}\nEvery memory you allocate in the heap needs to be explicitly freed by you, the programmer.\n:::\n\nThe majority of allocators in Zig do allocate memory on the heap. But some exceptions to this rule are\n`ArenaAllocator()` and `FixedBufferAllocator()`. The `ArenaAllocator()` is a special\ntype of allocator that works in conjunction with a second type of allocator.\nOn the other side, the `FixedBufferAllocator()` is an allocator that works based on\nbuffer objects created on the stack. This means that the `FixedBufferAllocator()` makes\nallocations only on the stack.\n\n\n\n\n### Summary\n\nAfter discussing all of these boring details, we can quickly recap what we learned.\nIn summary, the Zig compiler will use the following rules to decide where each\nobject you declare is stored:\n\n1. every literal value (such as `\"this is string\"`, `10`, or `true`) is stored in the global data section.\n1. every constant object (`const`) whose value **is known at compile-time** is also stored in the global data section.\n1. every object (constant or not) whose length/size **is known at compile time** is stored in the stack space for the current scope.\n1. if an object is created with the method `alloc()` or `create()` of an allocator object, this object is stored in the memory space used by this particular allocator object. Most of allocators available in Zig use the heap memory, so, this object is likely stored in the heap (`FixedBufferAllocator()` is an exception to that).\n1. the heap can only be accessed through allocators. If your object was not created through the `alloc()` or `create()` methods of an allocator object, then, he is most certainly not an object stored in the heap.\n\n\n## Stack overflows {#sec-stack-overflow}\n\nAllocating memory on the stack is generally faster than allocating it on the heap.\nBut this better performance comes with many restrictions. We have already discussed\nmany of these restrictions of the stack at @sec-stack. But there is one more important\nlimitation that I want to talk about, which is the size of the stack itself.\n\nThe stack is limited in size. This size varies from computer to computer, and it depends on\na lot of things (the computer architecture, the operating system, etc.). Nevertheless, this size is usually\nnot that big. This is why we normally use the stack to store only temporary and small objects in memory.\n\nIn essence, if you try to make an allocation on the stack, that is so big that exceeds the stack size limit,\na *stack overflow* happens, and your program just crashes as a result of that. In other words, a stack overflow happens when\nyou attempt to use more space than is available on the stack.\n\nThis type of problem is very similar to a *buffer overflow*, i.e. you are trying to use more space\nthan is available in the \"buffer object\". However, a stack overflow always cause your program to crash,\nwhile a buffer overflow not always cause your program to crash (although it often does).\n\nYou can see an example of a stack overflow in the example below. We are trying to allocate a very big array of `u64` values\non the stack. You can see below that this program does not run succesfully, because it crashed\nwith a \"segmentation fault\" error message.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar very_big_alloc: [1000 * 1000 * 24]u64 = undefined;\n@memset(very_big_alloc[0..], 0);\n```\n:::\n\n\n\n\n\n```\nSegmentation fault (core dumped)\n```\n\nThis segmentation fault error is a result of the stack overflow that was caused by the big\nmemory allocation made on the stack, to store the `very_big_alloc` object.\nThis is why very big objects are usually stored on the heap, instead of the stack.\n\n\n\n## Allocators {#sec-allocators}\n\nOne key aspect about Zig, is that there are \"no hidden-memory allocations\" in Zig.\nWhat that really means, is that \"no allocations happen behind your back in the standard library\" [@zigguide].\n\nThis is a known problem, especially in C++. Because in C++, there are some operators that do allocate\nmemory behind the scene, and there is no way for you to know that, until you actually read the\nsource code of these operators, and find the memory allocation calls.\nMany programmers find this behaviour annoying and hard to keep track of.\n\nBut, in Zig, if a function, an operator, or anything from the standard library\nneeds to allocate some memory during its execution, then, this function/operator needs to receive (as input) an allocator\nprovided by the user, to actually be able to allocate the memory it needs.\n\nThis creates a clear distinction between functions that \"do not\" from those that \"actually do\"\nallocate memory. Just look at the arguments of this function.\nIf a function, or operator, has an allocator object as one of its inputs/arguments, then, you know for\nsure that this function/operator will allocate some memory during its execution.\n\nAn example is the `allocPrint()` function from the Zig Standard Library. With this function, you can\nwrite a new string using format specifiers. So, this function is, for example, very similar to the function `sprintf()` in C.\nIn order to write such new string, the `allocPrint()` function needs to allocate some memory to store the\noutput string.\n\nThat is why, the first argument of this function is an allocator object that you, the user/programmer, gives\nas input to the function. In the example below, I am using the `GeneralPurposeAllocator()` as my allocator\nobject. But I could easily use any other type of allocator object from the Zig Standard Library.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst name = \"Pedro\";\nconst output = try std.fmt.allocPrint(\n    allocator,\n    \"Hello {s}!!!\",\n    .{name}\n);\ntry stdout.print(\"{s}\\n\", .{output});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello Pedro!!!\n```\n\n\n:::\n:::\n\n\n\n\n\n\nYou get a lot of control over where and how much memory this function can allocate.\nBecause it is you, the user/programmer, that provides the allocator for the function to use.\nThis makes \"total control\" over memory management easier to achieve in Zig.\n\n### What are allocators?\n\nAllocators in Zig are objects that you can use to allocate memory for your program.\nThey are similar to the memory allocating functions in C, like `malloc()` and `calloc()`.\nSo, if you need to use more memory than you initially have, during the execution of your program, you can simply ask\nfor more memory by using an allocator object.\n\nZig offers different types of allocators, and they are usually available through the `std.heap` module of\nthe standard library. Thus, just import the Zig Standard Library into your Zig module (with `@import(\"std\")`), and you can start\nusing these allocators in your code.\n\nFurthermore, every allocator object is built on top of the `Allocator` interface in Zig.\nThis means that, every allocator object you find in Zig must have the methods `alloc()`,\n`create()`, `free()` and `destroy()`. So, you can change the type of allocator you are using,\nbut you don't need to change the function calls to the methods that do the memory allocation\n(and the free memory operations) for your program.\n\n### Why you need an allocator?\n\nAs we described at @sec-stack, everytime you make a function call in Zig,\na space in the stack is reserved for this function call. But the stack\nhas a key limitation which is: every object stored in the stack have a\nknown fixed length.\n\nBut in reality, there are two very common instances where this \"fixed length limitation\" of the stack is a deal braker:\n\n1. the objects that you create inside your function might grow in size during the execution of the function.\n1. sometimes, it is impossible to know upfront how many inputs you will receive, or how big this input will be.\n\nAlso, there is another instance where you might want to use an allocator, which is when you want to write a function that returns a pointer\nto a local object. As I described at @sec-stack, you cannot do that if this local object is stored in the\nstack. However, if this object is stored in the heap, then, you can return a pointer to this object at the\nend of the function. Because you (the programmer) control the lifetime of any heap memory that you allocate. You decide\nwhen this memory gets destroyed/freed.\n\nThese are common situations where the stack is not good for.\nThat is why you need a different memory management strategy to\nstore these objects inside your function. You need to use\na memory type that can grow together with your objects, or that you\ncan control the lifetime of this memory.\nThe heap fits this description.\n\nAllocating memory on the heap is commonly known as dynamic memory management. As the objects you create grow in size\nduring the execution of your program, you grow the amount of memory\nyou have by allocating more memory in the heap to store these objects. \nAnd you do that in Zig, by using an allocator object.\n\n\n### The different types of allocators\n\n\nAt the moment of the writing of this book, in Zig, we have 6 different\nallocators available in the standard library:\n\n- `GeneralPurposeAllocator()`.\n- `page_allocator()`.\n- `FixedBufferAllocator()` and `ThreadSafeFixedBufferAllocator()`.\n- `ArenaAllocator()`.\n- `c_allocator()` (requires you to link to libc).\n\n\nEach allocator has its own perks and limitations. All allocators, except `FixedBufferAllocator()` and `ArenaAllocator()`,\nare allocators that use the heap memory. So any memory that you allocate with\nthese allocators, will be placed in the heap.\n\n### General-purpose allocators\n\nThe `GeneralPurposeAllocator()`, as the name suggests, is a \"general purpose\" allocator. You can use it for every type\nof task. In the example below, I'm allocating enough space to store a single integer in the object `some_number`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const some_number = try allocator.create(u32);\n    defer allocator.destroy(some_number);\n\n    some_number.* = @as(u32, 45);\n}\n```\n:::\n\n\n\n\n\n\nWhile useful, you might want to use the `c_allocator()`, which is a alias to the C standard allocator `malloc()`. So, yes, you can use\n`malloc()` in Zig if you want to. Just use the `c_allocator()` from the Zig standard library. However,\nif you do use `c_allocator()`, you must link to Libc when compiling your source code with the\n`zig` compiler, by including the flag `-lc` in your compilation process.\nIf you do not link your source code to Libc, Zig will not be able to find the\n`malloc()` implementation in your system.\n\n### Page allocator\n\nThe `page_allocator()` is an allocator that allocates full pages of memory in the heap. In other words,\nevery time you allocate memory with `page_allocator()`, a full page of memory in the heap is allocated,\ninstead of just a small piece of it.\n\nThe size of this page depends on the system you are using.\nMost systems use a page size of 4KB in the heap, so, that is the amount of memory that is normally\nallocated in each call by `page_allocator()`. That is why, `page_allocator()` is considered a\nfast, but also \"wasteful\" allocator in Zig. Because it allocates a big amount of memory\nin each call, and you most likely will not need that much memory in your program.\n\n### Buffer allocators\n\nThe `FixedBufferAllocator()` and `ThreadSafeFixedBufferAllocator()` are allocator objects that\nwork with a fixed sized buffer object at the back. In other words, they use a fixed sized buffer\nobject as the basis for the memory. When you ask these allocator objects to allocate some memory for you,\nthey are essentially reserving some amount of space inside this fixed sized buffer object for you to use.\n\nThis means that, in order to use these allocators, you must first create a buffer object in your code,\nand then, give this buffer object as an input to these allocators.\n\nThis also means that, these allocator objects can allocate memory both in the stack or in the heap.\nEverything depends on where the buffer object that you provide lives. If this buffer object lives\nin the stack, then, the memory allocated is \"stack-based\". But if it lives on the heap, then,\nthe memory allocated is \"heap-based\".\n\n\nIn the example below, I'm creating a `buffer` object on the stack that is 10 elements long.\nNotice that I give this `buffer` object to the `FixedBufferAllocator()` constructor.\nNow, because this `buffer` object is 10 elements long, this means that I am limited to this space.\nI cannot allocate more than 10 elements with this allocator object. If I try to\nallocate more than that, the `alloc()` method will return an `OutOfMemory` error value.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar buffer: [10]u8 = undefined;\nfor (0..buffer.len) |i| {\n    buffer[i] = 0; // Initialize to zero\n}\n\nvar fba = std.heap.FixedBufferAllocator.init(&buffer);\nconst allocator = fba.allocator();\nconst input = try allocator.alloc(u8, 5);\ndefer allocator.free(input);\n```\n:::\n\n\n\n\n\nRemember, the memory allocated by these allocator objects can be either from\nthe stack, or, from the heap. It all depends on where the buffer object that you provide lives.\nIn the above example, the `buffer` object lives in the stack, and, therefore, the memory allocated\nis based in the stack. But what if it was based on the heap?\n\nAs we described at @sec-stack-overflow, one of the main reasons why you would use the heap,\ninstead of the stack, is to allocate huge amounts of space to store very big objects.\nThus, let's suppose you wanted to use a very big buffer object as the basis for your\nallocator objects. You would have to allocate this very big buffer object on the heap.\nThe example below demonstrates this case.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst heap = std.heap.page_allocator;\nconst memory_buffer = try heap.alloc(\n    u8, 100 * 1024 * 1024 // 100 MB memory\n);\ndefer heap.free(memory_buffer);\nvar fba = std.heap.FixedBufferAllocator.init(\n    memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst input = try allocator.alloc(u8, 1000);\ndefer allocator.free(input);\n```\n:::\n\n\n\n\n\n\n\n### Arena allocator {#sec-arena-allocator}\n\nThe `ArenaAllocator()` is an allocator object that takes a child allocator as input. The idea behind the `ArenaAllocator()` in Zig\nis similar to the concept of \"arenas\" in the programming language Go[^go-arena]. It is an allocator object that allows you\nto allocate memory as many times you want, but free all memory only once.\nIn other words, if you have, for example, called 5 times the method `alloc()` of an `ArenaAllocator()` object, you can\nfree all the memory you allocated over these 5 calls at once, by simply calling the `deinit()` method of the same `ArenaAllocator()` object.\n\n[^go-arena]: <https://go.dev/src/arena/arena.go>\n\nIf you give, for example, a `GeneralPurposeAllocator()` object as input to the `ArenaAllocator()` constructor, like in the example below, then, the allocations\nyou perform with `alloc()` will actually be made with the underlying object `GeneralPurposeAllocator()` that was passed.\nSo, with an arena allocator, any new memory you ask for is allocated by the child allocator. The only thing that an arena allocator\nreally does is help you to free all the memory you allocated multiple times with just a single command. In the example\nbelow, I called `alloc()` 3 times. So, if I did not use an arena allocator, then, I would need to call\n`free()` 3 times to free all the allocated memory.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nvar aa = std.heap.ArenaAllocator.init(gpa.allocator());\ndefer aa.deinit();\nconst allocator = aa.allocator();\n\nconst in1 = try allocator.alloc(u8, 5);\nconst in2 = try allocator.alloc(u8, 10);\nconst in3 = try allocator.alloc(u8, 15);\n_ = in1; _ = in2; _ = in3;\n```\n:::\n\n\n\n\n\n\n\n### The `alloc()` and `free()` methods\n\nIn the code example below, we are accessing the `stdin`, which is\nthe standard input channel, to receive an input from the\nuser. We read the input given by the user with the `readUntilDelimiterOrEof()`\nmethod.\n\nNow, after reading the input of the user, we need to store this input somewhere in\nour program. That is why I use an allocator in this example. I use it to allocate some\namount of memory to store this input given by the user. More specifically, the method `alloc()`\nof the allocator object is used to allocate an array capable of storing 50 `u8` values.\n\nNotice that this `alloc()` method receives two inputs. The first one, is a type.\nThis defines what type of values the allocated array will store. In the example\nbelow, we are allocating an array of unsigned 8-bit integers (`u8`). But\nyou can create an array to store any type of value you want. Next, on the second argument, we\ndefine the size of the allocated array, by specifying how many elements\nthis array will contain. In the case below, we are allocating an array of 50 elements.\n\nAt @sec-zig-strings we described that strings in Zig are simply arrays of characters.\nEach character is represented by a `u8` value. So, this means that the array that\nwas allocated in the object `input` is capable of storing a string that is\n50-characters long.\n\nSo, in essence, the expression `var input: [50]u8 = undefined` would create\nan array for 50 `u8` values in the stack of the current scope. But, you\ncan allocate the same array in the heap by using the expression `var input = try allocator.alloc(u8, 50)`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdin = std.io.getStdIn();\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var input = try allocator.alloc(u8, 50);\n    defer allocator.free(input);\n    for (0..input.len) |i| {\n        input[i] = 0; // initialize all fields to zero.\n    }\n    // read user input\n    const input_reader = stdin.reader();\n    _ = try input_reader.readUntilDelimiterOrEof(\n        input,\n        '\\n'\n    );\n    std.debug.print(\"{s}\\n\", .{input});\n}\n```\n:::\n\n\n\n\n\nAlso, notice that in this example, we use the `defer` keyword (which I described at @sec-defer) to run a small\npiece of code at the end of the current scope, which is the expression `allocator.free(input)`.\nWhen you execute this expression, the allocator will free the memory that it allocated\nfor the `input` object.\n\nWe have talked about this at @sec-heap. You **should always** explicitly free any memory that you allocate\nusing an allocator! You do that by using the `free()` method of the same allocator object you\nused to allocate this memory. The `defer` keyword is used in this example only to help us execute\nthis free operation at the end of the current scope.\n\n\n### The `create()` and `destroy()` methods\n\nWith the `alloc()` and `free()` methods, you can allocate memory to store multiple elements\nat once. In other words, with these methods, we always allocate an array to store multiple elements at once.\nBut what if you need enough space to store just a single item? Should you\nallocate an array of a single element through `alloc()`?\n\nThe answer is no! In this case,\nyou should use the `create()` method of the allocator object.\nEvery allocator object offers the `create()` and `destroy()` methods,\nwhich are used to allocate and free memory for a single item, respectively.\n\nSo, in essence, if you want to allocate memory to store an array of elements, you\nshould use `alloc()` and `free()`. But if you need to store just a single item,\nthen, the `create()` and `destroy()` methods are ideal for you.\n\nIn the example below, I'm defining a struct to represent an user of some sort.\nIt could be an user for a game, or a software to manage resources, it doesn't mater.\nNotice that I use the `create()` method this time, to store a single `User` object\nin the program. Also notice that I use the `destroy()` method to free the memory\nused by this object at the end of the scope.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst User = struct {\n    id: usize,\n    name: []const u8,\n\n    pub fn init(id: usize, name: []const u8) User {\n        return .{ .id = id, .name = name };\n    }\n};\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const user = try allocator.create(User);\n    defer allocator.destroy(user);\n\n    user.* = User.init(0, \"Pedro\");\n}\n```\n:::\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Memory and Allocators\n\n\nIn this chapter, we will talk about memory. How does Zig control memory? What\ncommon tools are used? Are there any important aspects that make memory\ndifferent/special in Zig? You will find the answers here.\n\nComputers fundamentally rely on memory to function. This memory acts as a temporary storage\nspace for the data and values generated during computations. Without memory, the core\nconcepts of \"variables\" and \"objects\" in programming languages would be impossible.\n\n\n\n\n## Memory spaces\n\nEvery object that you create in your Zig source code needs to be stored somewhere,\nin your computer's memory. Depending on where and how you define your object, Zig\nwill use a different \"memory space\", or a different\ntype of memory to store this object.\n\nEach type of memory normally serves for different purposes.\nIn Zig, there are 3 types of memory (or 3 different memory spaces) that we care about. They are:\n\n- Global data register (or the \"global data section\");\n- Stack;\n- Heap;\n\n\n### Compile-time known versus runtime known {#sec-compile-time}\n\nOne strategy that Zig uses to decide where it will store each object that you declare, is by looking\nat the value of this particular object. More specifically, by investigating if this value is\nknown at \"compile-time\" or at \"runtime\".\n\nWhen you write a program in Zig, the values of some of the objects that you write in your program are *known\nat compile time*. Meaning that, when you compile your Zig source code, during the compilation process,\nthe `zig` compiler can figure out the exact value of a particular object\nthat exists in your source code.\nKnowing the length (or the size) of each object is also important. So the length (or the size) of each object that you write in your program is,\nin some cases, *known at compile time*.\n\nThe `zig` compiler cares more about knowing the length (or the size) of a particular object\n, than to know its actual value. But, if the `zig` compiler knows the value of the object, then, it\nautomatically knows the size of this object. Because it can simply calculate the\nsize of the object by looking at the size of the value.\n\nTherefore, the priority for the `zig` compiler is to discover the size of each object in your source code.\nIf the value of the object in question is known at compile-time, then, the `zig` compiler\nautomatically knows the size/length of this object. But if the value of this object is not\nknown at compile-time, then, the size of this object is only known at compile-time if,\nand only if, the type of this object has a known fixed size.\n\nIn order for a type to have a known fixed size, this type must have data members whose size is fixed.\nIf this type includes, for example, a variable sized array in it, then, this type does not have a known\nfixed size. Because this array can have any size at runtime\n(i.e. it can be an array of 2 elements, or 50 elements, or 1 thousand elements, etc.).\n\nFor example, a string object, which internally is an array of constant u8 values (`[]const u8`)\nhas a variable size. It can be a string object with 100 or 500 characters in it. If we do not\nknow at compile-time, which exact string will be stored inside this string object, then, we cannot calculate\nthe size of this string object at compile-time. So, any type, or any struct declaration that you make, that\nincludes a string data member that does not have an explicit fixed size, makes this type, or this\nnew struct that you are declaring, a type that does not have a known fixed size at compile-time.\n\nIn contrast, if the type of this struct that you are declaring, includes a data member that is an array,\nbut this array has a known fixed size, like `[60]u8` (which declares an array of 60 `u8` values), then,\nthis type, or, this struct that you are declaring, becomes a type with a known fixed size at compile-time.\nAnd because of that, in this case, the `zig` compiler does not need to know at compile-time the exact value of\nany object of this type. Since the compiler can find the necessary size to store this object by\nlooking at the size of its type.\n\n\nLet's look at an example. In the source code below, we have two constant objects (`name` and `array`) declared.\nBecause the values of these particular objects are written down, in the source code itself (`\"Pedro\"`\nand the number sequence from 1 to 4), the `zig` compiler can easily discover the values of these constant\nobjects (`name` and `array`) during the compilation process.\nThis is what \"known at compile time\" means. It refers to any object that you have in your Zig source code\nwhose value can be identified at compile time.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn input_length(input: []const u8) usize {\n    const n = input.len;\n    return n;\n}\n\npub fn main() !void {\n    const name = \"Pedro\";\n    const array = [_]u8{1, 2, 3, 4};\n    _ = name; _ = array;\n}\n```\n:::\n\n\n\n\nThe other side of the spectrum are objects whose values are not known at compile time.\nFunction arguments are a classic example of this. Because the value of each function\nargument depends on the value that you assign to this particular argument,\nwhen you call the function.\n\nFor example, the function `input_length()` contains an argument named `input`, which is an array of constant `u8` integers (`[]const u8`).\nIt is impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length\nof this particular argument. Because it is an array that do not have a fixed size specified explicitly in the argument type annotation.\n\nSo, we know that this `input` argument will be an array of `u8` integers. But we do not know at compile-time, its value, and neither its size.\nThis information is known only at runtime, which is the period of time when you program is executed.\nAs a consequence, the value of the expression `input.len` is also known only at runtime.\nThis is an intrinsic characteristic of any function. Just remember that the value of function arguments is usually not \"compile-time known\".\n\nHowever, as I mentioned earlier, what really matters to the compiler is to know the size of the object\nat compile-time, and not necessarily its value. So, although we don't know the value of the object `n`, which is the result of the expression\n`input.len`, at compile-time, we do know its size. Because the expression `input.len` always returns a value of type `usize`,\nand the type `usize` has a known fixed size.\n\n\n\n### Global data register\n\nThe global data register is a specific section of the executable of your Zig program, that is responsible\nfor storing any value that is known at compile time.\n\nEvery constant object whose value is known at compile time that you declare in your source code,\nis stored in the global data register. Also, every literal value that you write in your source code,\nsuch as the string `\"this is a string\"`, or the integer `10`, or a boolean value such as `true`,\nis also stored in the global data register.\n\nHonestly, you don't need to care much about this memory space. Because you can't control it,\nyou can't deliberately access it or use it for your own purposes.\nAlso, this memory space does not affect the logic of your program.\nIt simply exists in your program.\n\n\n### Stack vs Heap\n\nIf you are familiar with systems programming, or just low-level programming in general, you\nprobably have heard of the \"duel\" between Stack vs Heap. These are two different types of memory,\nor different memory spaces, which are both available in Zig.\n\nThese two types of memory don't actually duel with\neach other. This is a common mistake that beginners have, when seeing \"x vs y\" styles of\ntabloid headlines. These two types of memory are actually complementary to each other.\nSo, in almost every Zig program that you ever write, you will likely use a combination of both.\nI will describe each memory space in detail over the next sections. But for now, I just want to\nstablish the main difference between these two types of memory.\n\nIn essence, the stack memory is normally used to store values whose length is fixed and known\nat compile time. In contrast, the heap memory is a *dynamic* type of memory space, meaning that, it is\nused to store values whose length might grow during the execution (runtime) of your program [@jenny2022].\n\nLengths that grow during runtime are intrinsically associated with \"runtime known\" type of values.\nIn other words, if you have an object whose length might grow during runtime, then, the length\nof this object becomes not known at compile time. If the length is not known at compile-time,\nthe value of this object also becomes not known at compile-time.\nThese types of objects should be stored in the heap memory space, which is\na dynamic memory space, which can grow or shrink to fit the size of your objects.\n\n\n\n### Stack {#sec-stack}\n\nThe stack is a type of memory that uses the power of the *stack data structure*, hence the name. \nA \"stack\" is a type of *data structure* that uses a \"last in, first out\" (LIFO) mechanism to store the values\nyou give it to. I imagine you are familiar with this data structure.\nBut, if you are not, the [Wikipedia page](https://en.wikipedia.org/wiki/Stack_(abstract_data_type))[^wiki-stack]\n, or, the [Geeks For Geeks page](https://www.geeksforgeeks.org/stack-data-structure/)[^geek-stack] are both\nexcellent and easy resources to fully understand how this data structure works.\n\n[^wiki-stack]: <https://en.wikipedia.org/wiki/Stack_(abstract_data_type)>\n[^geek-stack]: <https://www.geeksforgeeks.org/stack-data-structure/>\n\nSo, the stack memory space is a type of memory that stores values using a stack data structure.\nIt adds and removes values from the memory by following a \"last in, first out\" (LIFO) principle.\n\nEvery time you make a function call in Zig, an amount of space in the stack is\nreserved for this particular function call [@jenny2022; @zigdocs].\nThe value of each function argument given to the function in this function call is stored in this\nstack space. Also, every local object that you declare inside the function scope is\nusually stored in this same stack space.\n\n\nLooking at the example below, the object `result` is a local object declared inside the scope of the `add()`\nfunction. Because of that, this object is stored inside the stack space reserved for the `add()` function.\nThe `r` object (which is declared outside of the `add()` function scope) is also stored in the stack.\nBut since it is declared in the \"outer\" scope, this object is stored in the\nstack space that belongs to this outer scope.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn add(x: u8, y: u8) u8 {\n    const result = x + y;\n    return result;\n}\n\npub fn main() !void {\n    const r = add(5, 27);\n    _ = r;\n}\n```\n:::\n\n\n\n\n\nSo, any object that you declare inside the scope of a function is always stored inside\nthe space that was reserved for that particular function in the stack memory. This\nalso counts for any object declared inside the scope of your `main()` function for example.\nAs you would expect, in this case, they\nare stored inside the stack space reserved for the `main()` function.\n\nOne very important detail about the stack memory is that **it frees itself automatically**.\nThis is very important, remember that. When objects are stored in the stack memory,\nyou don't have the work (or the responsibility) of freeing/destroying these objects.\nBecause they will be automatically destroyed once the stack space is freed at the end of the function scope.\n\nSo, once the function call returns (or ends, if you prefer to call it this way)\nthe space that was reserved in the stack is destroyed, and all of the objects that were in that space goes away with it.\nThis mechanism exists because this space, and the objects within it, are not necessary anymore,\nsince the function \"finished its business\".\nUsing the `add()` function that we exposed above as an example, it means that the object `result` is automatically\ndestroyed once the function returns.\n\n::: {.callout-important}\nLocal objects that are stored in the stack space of a function are automatically\nfreed/destroyed at the end of the function scope.\n:::\n\n\nThis same logic applies to any other special structure in Zig that has its own scope by surrounding\nit with curly braces (`{}`).\nFor loops, while loops, if else statements, etc. For example, if you declare any local\nobject in the scope of a for loop, this local object is accessible only within the scope\nof this particular for loop. Because once the scope of this for loop ends, the space in the stack\nreserved for this for loop is freed.\nThe example below demonstrates this idea.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This does not compile successfully!\nconst a = [_]u8{0, 1, 2, 3, 4};\nfor (0..a.len) |i| {\n    const index = i;\n    _ = index;\n}\n// Trying to use an object that was\n// declared in the for loop scope,\n// and that does not exist anymore.\nstd.debug.print(\"{d}\\n\", index);\n```\n:::\n\n\n\n\n\n\nOne important consequence of this mechanism is that, once the function returns, you can no longer access any memory\naddress that was inside the space in the stack reserved for this particular function. Because this space was\ndestroyed. This means that, if this local object is stored in the stack,\nyou cannot make a function that **returns a pointer to this object**.\n\nThink about that for a second. If all local objects in the stack are destroyed at the end of the function scope, why\nwould you even consider returning a pointer to one of these objects? This pointer is at best,\ninvalid, or, more likely, \"undefined\".\n\nConclusion, it is totally fine to write a function that returns the local object\nitself as result, because then, you return the value of that object as the result.\nBut, if this local object is stored in the stack, you should never write a function\nthat returns a pointer to this local object. Because the memory address pointed by the pointer\nno longer exists.\n\n\nSo, using again the `add()` function as an example, if you rewrite this function so that it\nreturns a pointer to the local object `result`, the `zig` compiler will actually compile\nyour program, with no warnings or errors. At first glance, it looks that this is good code\nthat works as expected. But this is a lie!\n\nIf you try to take a look at the value inside of the `r` object,\nor, if you try to use this `r` object in another expression\nor function call, then, you would have undefined behaviour, and major\nbugs in your program [@zigdocs, see \"Lifetime and Ownership\"[^life] and \"Undefined Behaviour\"[^undef] sections].\n\n[^life]: <https://ziglang.org/documentation/master/#Lifetime-and-Ownership>\n[^undef]: <https://ziglang.org/documentation/master/#Undefined-Behavior>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn add(x: u8, y: u8) *const u8 {\n    const result = x + y;\n    return &result;\n}\n\npub fn main() !void {\n    // This code compiles successfully. But it has\n    // undefined behaviour. Never do this!!!\n    // The `r` object is undefined!\n    const r = add(5, 27); _ = r;\n}\n```\n:::\n\n\n\n\nThis \"invalid pointer to stack variable\" problem is well known across many programming language communities.\nIf you try to do the same thing, for example, in a C or C++ program (i.e. returning an address to\na local object stored in the stack), you would also get undefined behaviour\nin the program.\n\n::: {.callout-important}\nIf a local object in your function is stored in the stack, you should never\nreturn a pointer to this local object from the function. Because\nthis pointer will always become undefined after the function returns, since the stack space of the function\nis destroyed at the end of its scope.\n:::\n\nBut what if you really need to use this local object in some way after your function returns?\nHow can you do this? The answer is: \"in the same way you would do if this were a C or C++ program. By returning\nan address to an object stored in the heap\". The heap memory has a much more flexible lifecycle,\nand allows you to get a valid pointer to a local object of a function that already returned\nfrom its scope.\n\n\n### Heap {#sec-heap}\n\nOne important limitation of the stack, is that, only objects whose length/size is known at compile-time can be\nstored in it. In contrast, the heap is a much more dynamic\n(and flexible) type of memory. It is the perfect type of memory to use\nfor objects whose size/length might grow during the execution of your program.\n\nVirtually any application that behaves as a server is a classic use case of the heap.\nA HTTP server, a SSH server, a DNS server, a LSP server, ... any type of server.\nIn summary, a server is a type of application that runs for long periods of time,\nand that serves (or \"deals with\") any incoming request that reaches this particular server.\n\nThe heap is a good choice for this type of system, mainly because the server does not know upfront\nhow many requests it will receive from users, while it is active. It could be a single request,\n5 thousand requests, or even zero requests.\nThe server needs to have the ability to allocate and manage its memory according to how many requests it receives.\n\nAnother key difference between the stack and the heap, is that the heap is a type\nof memory that you, the programmer, have complete control over. This makes the heap a\nmore flexible type of memory, but it also makes it harder to work with. Because you,\nthe programmer, is responsible for managing everything related to it. Including where the memory is allocated,\nhow much memory is allocated, and where this memory is freed.\n\n> Unlike stack memory, heap memory is allocated explicitly by programmers and it won’t be deallocated until it is explicitly freed [@jenny2022].\n\nTo store an object in the heap, you, the programmer, needs to explicitly tells Zig to do so,\nby using an allocator to allocate some space in the heap. At @sec-allocators, I will present how you can use allocators to allocate memory\nin Zig.\n\n::: {.callout-important}\nEvery memory you allocate in the heap needs to be explicitly freed by you, the programmer.\n:::\n\nThe majority of allocators in Zig do allocate memory on the heap. But some exceptions to this rule are\n`ArenaAllocator()` and `FixedBufferAllocator()`. The `ArenaAllocator()` is a special\ntype of allocator that works in conjunction with a second type of allocator.\nOn the other side, the `FixedBufferAllocator()` is an allocator that works based on\nbuffer objects created on the stack. This means that the `FixedBufferAllocator()` makes\nallocations only on the stack.\n\n\n\n\n### Summary\n\nAfter discussing all of these boring details, we can quickly recap what we learned.\nIn summary, the Zig compiler will use the following rules to decide where each\nobject you declare is stored:\n\n1. every literal value (such as `\"this is string\"`, `10`, or `true`) is stored in the global data section.\n1. every constant object (`const`) whose value **is known at compile-time** is also stored in the global data section.\n1. every object (constant or not) whose length/size **is known at compile time** is stored in the stack space for the current scope.\n1. if an object is created with the method `alloc()` or `create()` of an allocator object, this object is stored in the memory space used by this particular allocator object. Most of allocators available in Zig use the heap memory, so, this object is likely stored in the heap (`FixedBufferAllocator()` is an exception to that).\n1. the heap can only be accessed through allocators. If your object was not created through the `alloc()` or `create()` methods of an allocator object, then, it is most certainly not an object stored in the heap.\n\n\n## Stack overflows {#sec-stack-overflow}\n\nAllocating memory on the stack is generally faster than allocating it on the heap.\nBut this better performance comes with many restrictions. We have already discussed\nmany of these restrictions of the stack at @sec-stack. But there is one more important\nlimitation that I want to talk about, which is the size of the stack itself.\n\nThe stack is limited in size. This size varies from computer to computer, and it depends on\na lot of things (the computer architecture, the operating system, etc.). Nevertheless, this size is usually\nnot that big. This is why we normally use the stack to store only temporary and small objects in memory.\n\nIn essence, if you try to make an allocation on the stack, that is so big that exceeds the stack size limit,\na *stack overflow* happens, and your program just crashes as a result of that. In other words, a stack overflow happens when\nyou attempt to use more space than is available on the stack.\n\nThis type of problem is very similar to a *buffer overflow*, i.e. you are trying to use more space\nthan is available in the \"buffer object\". However, a stack overflow always causes your program to crash,\nwhile a buffer overflow does not always cause your program to crash (although it often does).\n\nYou can see an example of a stack overflow in the example below. We are trying to allocate a very big array of `u64` values\non the stack. You can see below that this program does not run successfully, because it crashed\nwith a \"segmentation fault\" error message.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar very_big_alloc: [1000 * 1000 * 24]u64 = undefined;\n@memset(very_big_alloc[0..], 0);\n```\n:::\n\n\n\n\n```\nSegmentation fault (core dumped)\n```\n\nThis segmentation fault error is a result of the stack overflow that was caused by the big\nmemory allocation made on the stack, to store the `very_big_alloc` object.\nThis is why very big objects are usually stored on the heap, instead of the stack.\n\n\n\n## Allocators {#sec-allocators}\n\nOne key aspect about Zig, is that there are \"no hidden-memory allocations\" in Zig.\nWhat that really means, is that \"no allocations happen behind your back in the standard library\" [@zigguide].\n\nThis is a known problem, especially in C++. Because in C++, there are some operators that do allocate\nmemory behind the scene, and there is no way for you to know that, until you actually read the\nsource code of these operators, and find the memory allocation calls.\nMany programmers find this behaviour annoying and hard to keep track of.\n\nBut, in Zig, if a function, an operator, or anything from the standard library\nneeds to allocate some memory during its execution, then, this function/operator needs to receive (as input) an allocator\nprovided by the user, to actually be able to allocate the memory it needs.\n\nThis creates a clear distinction between functions that \"do not\" from those that \"actually do\"\nallocate memory. Just look at the arguments of this function.\nIf a function, or operator, has an allocator object as one of its inputs/arguments, then, you know for\nsure that this function/operator will allocate some memory during its execution.\n\nAn example is the `allocPrint()` function from the Zig Standard Library. With this function, you can\nwrite a new string using format specifiers. So, this function is, for example, very similar to the function `sprintf()` in C.\nIn order to write such a new string, the `allocPrint()` function needs to allocate some memory to store the\noutput string.\n\nThat is why, the first argument of this function is an allocator object that you, the user/programmer, gives\nas input to the function. In the example below, I am using the `GeneralPurposeAllocator()` as my allocator\nobject. But I could easily use any other type of allocator object from the Zig Standard Library.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst name = \"Pedro\";\nconst output = try std.fmt.allocPrint(\n    allocator,\n    \"Hello {s}!!!\",\n    .{name}\n);\ntry stdout.print(\"{s}\\n\", .{output});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello Pedro!!!\n```\n\n\n:::\n:::\n\n\n\n\n\nYou get a lot of control over where and how much memory this function can allocate.\nBecause it is you, the user/programmer, that provides the allocator for the function to use.\nThis makes \"total control\" over memory management easier to achieve in Zig.\n\n### What are allocators?\n\nAllocators in Zig are objects that you can use to allocate memory for your program.\nThey are similar to the memory allocating functions in C, like `malloc()` and `calloc()`.\nSo, if you need to use more memory than you initially have, during the execution of your program, you can simply ask\nfor more memory by using an allocator object.\n\nZig offers different types of allocators, and they are usually available through the `std.heap` module of\nthe standard library. Thus, just import the Zig Standard Library into your Zig module (with `@import(\"std\")`), and you can start\nusing these allocators in your code.\n\nFurthermore, every allocator object is built on top of the `Allocator` interface in Zig.\nThis means that, every allocator object you find in Zig must have the methods `alloc()`,\n`create()`, `free()` and `destroy()`. So, you can change the type of allocator you are using,\nbut you don't need to change the function calls to the methods that do the memory allocation\n(and the free memory operations) for your program.\n\n### Why you need an allocator?\n\nAs we described at @sec-stack, everytime you make a function call in Zig,\na space in the stack is reserved for this function call. But the stack\nhas a key limitation which is: every object stored in the stack has a\nknown fixed length.\n\nBut in reality, there are two very common instances where this \"fixed length limitation\" of the stack is a deal braker:\n\n1. the objects that you create inside your function might grow in size during the execution of the function.\n1. sometimes, it is impossible to know upfront how many inputs you will receive, or how big this input will be.\n\nAlso, there is another instance where you might want to use an allocator, which is when you want to write a function that returns a pointer\nto a local object. As I described at @sec-stack, you cannot do that if this local object is stored in the\nstack. However, if this object is stored in the heap, then, you can return a pointer to this object at the\nend of the function. Because you (the programmer) control the lifetime of any heap memory that you allocate. You decide\nwhen this memory gets destroyed/freed.\n\nThese are common situations for which the stack is not good. \nThat is why you need a different memory management strategy to\nstore these objects inside your function. You need to use\na memory type that can grow together with your objects, or that you\ncan control the lifetime of this memory.\nThe heap fits this description.\n\nAllocating memory on the heap is commonly known as dynamic memory management. As the objects you create grow in size\nduring the execution of your program, you grow the amount of memory\nyou have by allocating more memory in the heap to store these objects. \nAnd you do that in Zig, by using an allocator object.\n\n\n### The different types of allocators\n\n\nAt the moment of the writing of this book, in Zig, we have 6 different\nallocators available in the standard library:\n\n- `GeneralPurposeAllocator()`.\n- `page_allocator()`.\n- `FixedBufferAllocator()` and `ThreadSafeFixedBufferAllocator()`.\n- `ArenaAllocator()`.\n- `c_allocator()` (requires you to link to libc).\n\n\nEach allocator has its own perks and limitations. All allocators, except `FixedBufferAllocator()` and `ArenaAllocator()`,\nare allocators that use the heap memory. So any memory that you allocate with\nthese allocators, will be placed in the heap.\n\n### General-purpose allocators\n\nThe `GeneralPurposeAllocator()`, as the name suggests, is a \"general purpose\" allocator. You can use it for every type\nof task. In the example below, I'm allocating enough space to store a single integer in the object `some_number`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const some_number = try allocator.create(u32);\n    defer allocator.destroy(some_number);\n\n    some_number.* = @as(u32, 45);\n}\n```\n:::\n\n\n\n\n\nWhile useful, you might want to use the `c_allocator()`, which is a alias to the C standard allocator `malloc()`. So, yes, you can use\n`malloc()` in Zig if you want to. Just use the `c_allocator()` from the Zig standard library. However,\nif you do use `c_allocator()`, you must link to Libc when compiling your source code with the\n`zig` compiler, by including the flag `-lc` in your compilation process.\nIf you do not link your source code to Libc, Zig will not be able to find the\n`malloc()` implementation in your system.\n\n### Page allocator\n\nThe `page_allocator()` is an allocator that allocates full pages of memory in the heap. In other words,\nevery time you allocate memory with `page_allocator()`, a full page of memory in the heap is allocated,\ninstead of just a small piece of it.\n\nThe size of this page depends on the system you are using.\nMost systems use a page size of 4KB in the heap, so, that is the amount of memory that is normally\nallocated in each call by `page_allocator()`. That is why, `page_allocator()` is considered a\nfast, but also \"wasteful\" allocator in Zig. Because it allocates a big amount of memory\nin each call, and you most likely will not need that much memory in your program.\n\n### Buffer allocators\n\nThe `FixedBufferAllocator()` and `ThreadSafeFixedBufferAllocator()` are allocator objects that\nwork with a fixed sized buffer object at the back. In other words, they use a fixed sized buffer\nobject as the basis for the memory. When you ask these allocator objects to allocate some memory for you,\nthey are essentially reserving some amount of space inside this fixed sized buffer object for you to use.\n\nThis means that, in order to use these allocators, you must first create a buffer object in your code,\nand then, give this buffer object as an input to these allocators.\n\nThis also means that, these allocator objects can allocate memory both in the stack or in the heap.\nEverything depends on where the buffer object that you provide lives. If this buffer object lives\nin the stack, then, the memory allocated is \"stack-based\". But if it lives on the heap, then,\nthe memory allocated is \"heap-based\".\n\n\nIn the example below, I'm creating a `buffer` object on the stack that is 10 elements long.\nNotice that I give this `buffer` object to the `FixedBufferAllocator()` constructor.\nNow, because this `buffer` object is 10 elements long, this means that I am limited to this space.\nI cannot allocate more than 10 elements with this allocator object. If I try to\nallocate more than that, the `alloc()` method will return an `OutOfMemory` error value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar buffer: [10]u8 = undefined;\nfor (0..buffer.len) |i| {\n    buffer[i] = 0; // Initialize to zero\n}\n\nvar fba = std.heap.FixedBufferAllocator.init(&buffer);\nconst allocator = fba.allocator();\nconst input = try allocator.alloc(u8, 5);\ndefer allocator.free(input);\n```\n:::\n\n\n\n\nRemember, the memory allocated by these allocator objects can be either from\nthe stack, or, from the heap. It all depends on where the buffer object that you provide lives.\nIn the above example, the `buffer` object lives in the stack, and, therefore, the memory allocated\nis based in the stack. But what if it was based on the heap?\n\nAs we described at @sec-stack-overflow, one of the main reasons why you would use the heap,\ninstead of the stack, is to allocate huge amounts of space to store very big objects.\nThus, let's suppose you wanted to use a very big buffer object as the basis for your\nallocator objects. You would have to allocate this very big buffer object on the heap.\nThe example below demonstrates this case.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst heap = std.heap.page_allocator;\nconst memory_buffer = try heap.alloc(\n    u8, 100 * 1024 * 1024 // 100 MB memory\n);\ndefer heap.free(memory_buffer);\nvar fba = std.heap.FixedBufferAllocator.init(\n    memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst input = try allocator.alloc(u8, 1000);\ndefer allocator.free(input);\n```\n:::\n\n\n\n\n\n\n### Arena allocator {#sec-arena-allocator}\n\nThe `ArenaAllocator()` is an allocator object that takes a child allocator as input. The idea behind the `ArenaAllocator()` in Zig\nis similar to the concept of \"arenas\" in the programming language Go[^go-arena]. It is an allocator object that allows you\nto allocate memory as many times you want, but free all memory only once.\nIn other words, if you have, for example, called 5 times the method `alloc()` of an `ArenaAllocator()` object, you can\nfree all the memory you allocated over these 5 calls at once, by simply calling the `deinit()` method of the same `ArenaAllocator()` object.\n\n[^go-arena]: <https://go.dev/src/arena/arena.go>\n\nIf you give, for example, a `GeneralPurposeAllocator()` object as input to the `ArenaAllocator()` constructor, like in the example below, then, the allocations\nyou perform with `alloc()` will actually be made with the underlying object `GeneralPurposeAllocator()` that was passed.\nSo, with an arena allocator, any new memory you ask for is allocated by the child allocator. The only thing that an arena allocator\nreally does is help you to free all the memory you allocated multiple times with just a single command. In the example\nbelow, I called `alloc()` 3 times. So, if I did not use an arena allocator, then, I would need to call\n`free()` 3 times to free all the allocated memory.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nvar aa = std.heap.ArenaAllocator.init(gpa.allocator());\ndefer aa.deinit();\nconst allocator = aa.allocator();\n\nconst in1 = try allocator.alloc(u8, 5);\nconst in2 = try allocator.alloc(u8, 10);\nconst in3 = try allocator.alloc(u8, 15);\n_ = in1; _ = in2; _ = in3;\n```\n:::\n\n\n\n\n\n\n### The `alloc()` and `free()` methods\n\nIn the code example below, we are accessing the `stdin`, which is\nthe standard input channel, to receive an input from the\nuser. We read the input given by the user with the `readUntilDelimiterOrEof()`\nmethod.\n\nNow, after reading the input of the user, we need to store this input somewhere in\nour program. That is why I use an allocator in this example. I use it to allocate some\namount of memory to store this input given by the user. More specifically, the method `alloc()`\nof the allocator object is used to allocate an array capable of storing 50 `u8` values.\n\nNotice that this `alloc()` method receives two inputs. The first one, is a type.\nThis defines what type of values the allocated array will store. In the example\nbelow, we are allocating an array of unsigned 8-bit integers (`u8`). But\nyou can create an array to store any type of value you want. Next, on the second argument, we\ndefine the size of the allocated array, by specifying how many elements\nthis array will contain. In the case below, we are allocating an array of 50 elements.\n\nAt @sec-zig-strings we described that strings in Zig are simply arrays of characters.\nEach character is represented by a `u8` value. So, this means that the array that\nwas allocated in the object `input` is capable of storing a string that is\n50-characters long.\n\nSo, in essence, the expression `var input: [50]u8 = undefined` would create\nan array for 50 `u8` values in the stack of the current scope. But, you\ncan allocate the same array in the heap by using the expression `var input = try allocator.alloc(u8, 50)`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdin = std.io.getStdIn();\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var input = try allocator.alloc(u8, 50);\n    defer allocator.free(input);\n    for (0..input.len) |i| {\n        input[i] = 0; // initialize all fields to zero.\n    }\n    // read user input\n    const input_reader = stdin.reader();\n    _ = try input_reader.readUntilDelimiterOrEof(\n        input,\n        '\\n'\n    );\n    std.debug.print(\"{s}\\n\", .{input});\n}\n```\n:::\n\n\n\n\nAlso, notice that in this example, we use the `defer` keyword (which I described at @sec-defer) to run a small\npiece of code at the end of the current scope, which is the expression `allocator.free(input)`.\nWhen you execute this expression, the allocator will free the memory that it allocated\nfor the `input` object.\n\nWe have talked about this at @sec-heap. You **should always** explicitly free any memory that you allocate\nusing an allocator! You do that by using the `free()` method of the same allocator object you\nused to allocate this memory. The `defer` keyword is used in this example only to help us execute\nthis free operation at the end of the current scope.\n\n\n### The `create()` and `destroy()` methods\n\nWith the `alloc()` and `free()` methods, you can allocate memory to store multiple elements\nat once. In other words, with these methods, we always allocate an array to store multiple elements at once.\nBut what if you need enough space to store just a single item? Should you\nallocate an array of a single element through `alloc()`?\n\nThe answer is no! In this case,\nyou should use the `create()` method of the allocator object.\nEvery allocator object offers the `create()` and `destroy()` methods,\nwhich are used to allocate and free memory for a single item, respectively.\n\nSo, in essence, if you want to allocate memory to store an array of elements, you\nshould use `alloc()` and `free()`. But if you need to store just a single item,\nthen, the `create()` and `destroy()` methods are ideal for you.\n\nIn the example below, I'm defining a struct to represent an user of some sort.\nIt could be a user for a game, or software to manage resources, it doesn't mater.\nNotice that I use the `create()` method this time, to store a single `User` object\nin the program. Also notice that I use the `destroy()` method to free the memory\nused by this object at the end of the scope.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst User = struct {\n    id: usize,\n    name: []const u8,\n\n    pub fn init(id: usize, name: []const u8) User {\n        return .{ .id = id, .name = name };\n    }\n};\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const user = try allocator.create(User);\n    defer allocator.destroy(user);\n\n    user.* = User.init(0, \"Pedro\");\n}\n```\n:::\n",
+    "supporting": [
+      "01-memory_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/02-debugging/execute-results/html.json b/_freeze/Chapters/02-debugging/execute-results/html.json
index dcd81837..09ed5640 100644
--- a/_freeze/Chapters/02-debugging/execute-results/html.json
+++ b/_freeze/Chapters/02-debugging/execute-results/html.json
@@ -1,8 +1,8 @@
 {
-  "hash": "d955858e8c96c11c36427af044c591f0",
+  "hash": "8b14f21d35335dfe950f1e6461a7c890",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Debugging Zig applications\n\nBeing able to debug your applications is essential for any programmer who wants to\ndo serious programming in any language. That is why, in this chapter, we are going to talk about the\navailable strategies and tools to debug applications written in Zig.\n\n\n## Print debugging\n\nWe begin with the classic and battle-tested *print debugging* strategy.\nThe key advantage that debugging offers you is *visibility*.\nWith *print statements* you can easily see what results and objects\nare being produced by your application.\n\nThat is the essence of *print debugging*. Is to use\nprint expressions to see the values that are being generated by your program,\nand, as a result, get a much better understanding of how your program\nis behaving.\n\nMany programmers often resort to the print functions in Zig, such as the `stdout.print()`,\nor, the `std.debug.print()`, to get a better understanding of their programs.\nThis is a known and old strategy that is very simple and effective, and it is better known within\nthe programming community as *print debugging*.\nIn Zig, you can print information to the `stdout` or `stderr` streams of your system.\n\nLet's begin with `stdout`. First, you\nneed to get access to the `stdout`, by calling the `getStdOut()` method, from\nthe Zig Standard Library. This method returns a *file descriptor* object,\nand, through this object you can read/write to the `stdout`.\nI recommend you to check out all methods available in this object, by [checking the page in\nthe Zig Standard Library Official Reference for the type `File`](https://ziglang.org/documentation/master/std/#std.fs.File)[^zig-fiile-reference].\n\n[^zig-fiile-reference]: <https://ziglang.org/documentation/master/std/#std.fs.File>.\n\nFor our purpose here, which is to write something to the `stdout`, especially to debug our\nprogram, I recommend you to use the `writer()` method, which gives your a *writer* object.\nThis *writer* object offers some helper methods to write stuff into the file descriptor object\nthat represents the `stdout` stream. In special, the `print()` method.\n\n\nThe `print()` method from this *writer* object is a \"print formatter\" type of a function.\nIn other words, this method works exactly like the `printf()` function from C,\nor, like `println!()` from Rust.\nIn the first argument of the function, you specify a template string, and,\nin the second argument, you provide a list of values (or objects) that you want to insert\ninto your template message.\n\nIdeally, the template string in the first argument should contain some format specifier.\nEach format specifier is matched to a value (or object) that you have listed in the second argument.\nSo, if you provided 5 different objects in the second argument, then, the template string\nshould contain 5 format specifiers, one for each object provided.\n\nEach format specifier is represented by a single letter, and\nyou provide this format specifier inside a pair of curly braces. So, if you want to format\nyour object using the string specifier (`s`), then, you can insert the text `{s}` in your template string.\nHere is a quick list of the most used format specifiers:\n\n- `d`: for printing integers and floating-point numbers.\n- `c`: for printing characters.\n- `s`: for printing strings.\n- `p`: for printing memory addresses.\n- `x`: for printing hexadecimal values.\n- `any`: use any compatible format specifier (i.e. it automatically selects a format specifier for you).\n\nThe code example below gives you an example of use of this `print()` method\nwith the `d` format specifier.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    _ = try stdout.print(\"Result: {d}\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\n\n\nIs important to emphasize that, the `stdout.print()` method, as you would expect,\nprint your template string into the `stdout` stream of your system.\nHowever, you can also print your template string into the `stderr` stream\nif your prefer. All you need to do, is to replace the `stdout.print()`\ncall with the function `std.debug.print()`. Like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    std.debug.print(\"Result: {d}\\n\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\n\n\n\nYou could also achieve the exact same result by getting a file descriptor object to `stderr`,\nthen, creating a *writer* object to `stderr`, then, using the `print()` method of this\n*writer* object, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stderr = std.io.getStdErr().writer();\n// some more lines ...\n_ = try stderr.print(\"Result: {d}\", .{result});\n```\n:::\n\n\n\n\n\n\n## Debugging through debuggers\n\nAlthough *print debugging* being a valid and very useful strategy,\nmost programmers prefer to use a debugger to debug their programs.\nSince Zig is a low-level language, you can use either GDB (GNU Debugger),\nor LLDB (LLVM Project Debugger) as your debugger.\n\nBoth debuggers can work with Zig code, and it's a matter of taste here.\nYou choose the debugger of your preference, and you work with it.\nIn this book, I will use LLDB as my debugger on the examples.\n\n\n### Compile your source code in debug mode {#sec-compile-debug-mode}\n\nIn order to debug your program through a debugger, you must compile\nyour source code in `Debug` mode. Because when you compile your\nsource code in other modes (such as `Release`), the compiler usually\nstrips out some essential information that is used by the debugger\nto read and track your program, like PDB (*Program Database*) files.\n\nBy compiling your source code in `Debug` mode, you ensure that the debugger\nwill find the necessary information in your program to debug it.\nBy default, the compiler uses the `Debug` mode when compiling your code.\nHaving this in mind, when you compile your program with the `build-exe`\ncommand (which was described at @sec-compile-code), if you don't specify\nan explicit mode through the `-O` command-line [^oargument]\nargument, then, the compiler will compile your code in `Debug` mode.\n\n[^oargument]: See <https://ziglang.org/documentation/master/#Debug>.\n\n\n### Let's debug a program\n\nAs an example, let's use LLDB to navigate and investigate the following\npiece of Zig code:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\nfn add_and_increment(a: u8, b: u8) u8 {\n    const sum = a + b;\n    const incremented = sum + 1;\n    return incremented;\n}\n\npub fn main() !void {\n    var n = add_and_increment(2, 3);\n    n = add_and_increment(n, n);\n    _ = try stdout.print(\"Result: {d}!\\n\", .{n});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 13!\n```\n\n\n:::\n:::\n\n\n\n\nThere is nothing wrong with this program. But it is\na good start for us. First, we need to compile\nthis program with the `zig build-exe` command.\nFor this example, suppose that I have compiled the above\nZig code into a binary executable called `add_program`.\n\n```bash\nzig build-exe add_program.zig\n```\n\nNow, we can start LLDB with `add_program`, like this:\n\n```bash\nlldb add_program\n```\n\nFrom now on, LLDB is started, and you can know that I'm\nexecuting LLDB commands by looking at the prefix `(lldb)`.\nIf something is prefixed with `(lldb)`, then you know\nthat it is a LLDB command.\n\nThe first thing I will do, is to set a breakpoint at\nthe `main()` function, by executing `b main`.\nAfter that, I just start the execution of the program\nwith `run`.\nYou can see in the output below, that the execution\nstopped at the first line in the function `main()`, as we expected.\n\n```bash\n(lldb) b main\nBreakpoint 1: where = debugging`debug1.main + 22\n    at debug1.zig:11:30, address = 0x00000000010341a6\n(lldb) run\nProcess 8654 launched: 'add_program' (x86_64)\nProcess 8654 stopped\n* thread #1, name = 'add_program',\n    stop reason = breakpoint 1.1 frame #0: 0x10341a6\n    add_program`debug1.main at add_program.zig:11:30\n   8   \t}\n   9   \t\n   10  \tpub fn main() !void {\n-> 11  \t    var n = add_and_increment(2, 3);\n   12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n```\n\nI can start navigating through the code, and checking the objects\nthat are being generated. If you are not familiar with the commands\navailable in LLDB, I recommend you to read the official documentation\nof the project[^lldb].\nYou can also look for cheat sheets, which quickly describes all commands\navailable for you[^lldb-quick-list].\n\n[^lldb]: <https://lldb.llvm.org/>\n[^lldb-quick-list]: <https://gist.github.com/ryanchang/a2f738f0c3cc6fbd71fa>.\n\nCurrently, we are in the first line at the `main()` function. In this line, we create\nthe `n` object, by executing the `add_and_increment()` function.\nTo execute the current line of code, and go to the next line, we can\nrun the `n` LLDB command. Let's execute this command.\n\nAfter we executed this line, we can also look at the value stored inside this `n` object\nby using the `p` LLDB command. The syntax for this command is `p <name-of-object>`.\n\nIf we take a look at the value stored in the `n` object (`p n`),\nnotice that it stores the hexadecimal value `0x06`, which\nis the number 6 in decimal. We can also see that, this value have a type `unsigned char`,\nwhich is an unsigned 8-bit integer.\nWe have talked already about this at @sec-zig-strings, that `u8` integers in Zig are equivalent\nto the C data type `unsigned char`.\n\n\n\n```bash\n(lldb) n\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step over frame #0: 0x10341ae\n    debugging`debug1.main at debug1.zig:12:26\n   9   \t\n   10  \tpub fn main() !void {\n   11  \t    var n = add_and_increment(2, 3);\n-> 12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n(lldb) p n\n(unsigned char) $1 = '\\x06'\n```\n\nNow, on the next line of code, we are executing the `add_and_increment()` function once again.\nWhy not step inside this function? Shall we? We can do that, by executing the `s` LLDB command.\nNotice in the example below that, after executing this command, we have entered into the context of the\n`add_and_increment()` function.\n\nAlso notice in the example below that, I have walked two more lines in the function's body, then,\nI execute the `frame variable` LLDB command, to see at once, the value stored in each of the variables\nthat were created inside the current scope.\n\nYou can see in the output below that, the object `sum` stores the value `\\f`,\nwhich represents the *form feed* character. This character in the ASCII table,\ncorresponds to the hexadecimal value `0x0C`, or, in decimal, the number 12.\nSo, this means that the result of the expression `a + b` executed at line\n5, resulted in the number 12.\n\n```bash\n(lldb) s\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step in frame #0: 0x10342de\n    debugging`debug1.add_and_increment(a='\\x02', b='\\x03')\n    at debug1.zig:4:39\n-> 4   \tfn add_and_increment(a: u8, b: u8) u8 {\n   5   \t    const sum = a + b;\n   6   \t    const incremented = sum + 1;\n   7   \t    return incremented;\n(lldb) n\n(lldb) n\n(lldb) frame variable\n(unsigned char) a = '\\x06'\n(unsigned char) b = '\\x06'\n(unsigned char) sum = '\\f'\n(unsigned char) incremented = '\\x06'\n```\n\n\n\n## How to investigate the data type of your objects\n\nSince Zig is a strongly-typed language, the data types associated with your objects\nare very important for your program. So, debugging the data types associated\nwith your objects might be important to understand bugs and errors in your program.\n\nWhen you walk through your program with a debugger, you can inspect the types of\nyour objects by simply printing them to the console, with the LLDB `p` command.\nBut you also have alternatives embedded in the language itself to access the data\ntypes of your objects.\n\nIn Zig, you can retrieve the data type of an object, by using the built-in function\n`@TypeOf()`. Just apply this function over the object, and you get access to \nthe data type of the object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst expect = std.testing.expect;\n\npub fn main() !void {\n    const number: i32 = 5;\n    try expect(@TypeOf(number) == i32);\n    try stdout.print(\"{any}\\n\", .{@TypeOf(number)});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ni32\n```\n\n\n:::\n:::\n\n\n\n\nThis function is similar to the `type()` built-in function from Python,\nor, the `typeof` operator in Javascript.\n\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Debugging Zig applications\n\nBeing able to debug your applications is essential for any programmer who wants to\ndo serious programming in any language. That is why, in this chapter, we are going to talk about the\navailable strategies and tools to debug applications written in Zig.\n\n\n## Print debugging\n\nWe begin with the classic and battle-tested *print debugging* strategy.\nThe key advantage that debugging offers you is *visibility*.\nWith *print statements* you can easily see what results and objects\nare being produced by your application.\n\nThat is the essence of *print debugging*. Is to use\nprint expressions to see the values that are being generated by your program,\nand, as a result, get a much better understanding of how your program\nis behaving.\n\nMany programmers often resort to the print functions in Zig, such as the `stdout.print()`,\nor, the `std.debug.print()`, to get a better understanding of their programs.\nThis is a known and old strategy that is very simple and effective, and it is better known within\nthe programming community as *print debugging*.\nIn Zig, you can print information to the `stdout` or `stderr` streams of your system.\n\nLet's begin with `stdout`. First, you\nneed to get access to the `stdout`, by calling the `getStdOut()` method, from\nthe Zig Standard Library. This method returns a *file descriptor* object,\nand, through this object you can read/write to the `stdout`.\nI recommend you to check out all methods available in this object, by [checking the page in\nthe Zig Standard Library Official Reference for the type `File`](https://ziglang.org/documentation/master/std/#std.fs.File)[^zig-fiile-reference].\n\n[^zig-fiile-reference]: <https://ziglang.org/documentation/master/std/#std.fs.File>.\n\nFor our purpose here, which is to write something to the `stdout`, especially to debug our\nprogram, I recommend you to use the `writer()` method, which gives you a *writer* object.\nThis *writer* object offers some helper methods to write stuff into the file descriptor object\nthat represents the `stdout` stream. In special, the `print()` method.\n\n\nThe `print()` method from this *writer* object is a \"print formatter\" type of a function.\nIn other words, this method works exactly like the `printf()` function from C,\nor, like `println!()` from Rust.\nIn the first argument of the function, you specify a template string, and,\nin the second argument, you provide a list of values (or objects) that you want to insert\ninto your template message.\n\nIdeally, the template string in the first argument should contain some format specifier.\nEach format specifier is matched to a value (or object) that you have listed in the second argument.\nSo, if you provided 5 different objects in the second argument, then, the template string\nshould contain 5 format specifiers, one for each object provided.\n\nEach format specifier is represented by a single letter, and\nyou provide this format specifier inside a pair of curly braces. So, if you want to format\nyour object using the string specifier (`s`), then, you can insert the text `{s}` in your template string.\nHere is a quick list of the most used format specifiers:\n\n- `d`: for printing integers and floating-point numbers.\n- `c`: for printing characters.\n- `s`: for printing strings.\n- `p`: for printing memory addresses.\n- `x`: for printing hexadecimal values.\n- `any`: use any compatible format specifier (i.e. it automatically selects a format specifier for you).\n\nThe code example below gives you an example of use of this `print()` method\nwith the `d` format specifier.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    _ = try stdout.print(\"Result: {d}\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\n\n\nIt is important to emphasize that, the `stdout.print()` method, as you would expect,\nprints your template string into the `stdout` stream of your system.\nHowever, you can also print your template string into the `stderr` stream\nif your prefer. All you need to do, is to replace the `stdout.print()`\ncall with the function `std.debug.print()`. Like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    std.debug.print(\"Result: {d}\\n\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\n\n\n\nYou could also achieve the exact same result by getting a file descriptor object to `stderr`,\nthen, creating a *writer* object to `stderr`, then, using the `print()` method of this\n*writer* object, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stderr = std.io.getStdErr().writer();\n// some more lines ...\n_ = try stderr.print(\"Result: {d}\", .{result});\n```\n:::\n\n\n\n\n\n\n## Debugging through debuggers\n\nAlthough *print debugging* is a valid and very useful strategy,\nmost programmers prefer to use a debugger to debug their programs.\nSince Zig is a low-level language, you can use either GDB (GNU Debugger),\nor LLDB (LLVM Project Debugger) as your debugger.\n\nBoth debuggers can work with Zig code, and it's a matter of taste here.\nYou choose the debugger of your preference, and you work with it.\nIn this book, I will use LLDB as my debugger on the examples.\n\n\n### Compile your source code in debug mode {#sec-compile-debug-mode}\n\nIn order to debug your program through a debugger, you must compile\nyour source code in `Debug` mode. Because when you compile your\nsource code in other modes (such as `Release`), the compiler usually\nstrips out some essential information that is used by the debugger\nto read and track your program, like PDB (*Program Database*) files.\n\nBy compiling your source code in `Debug` mode, you ensure that the debugger\nwill find the necessary information in your program to debug it.\nBy default, the compiler uses the `Debug` mode when compiling your code.\nHaving this in mind, when you compile your program with the `build-exe`\ncommand (which was described at @sec-compile-code), if you don't specify\nan explicit mode through the `-O` command-line [^oargument]\nargument, then, the compiler will compile your code in `Debug` mode.\n\n[^oargument]: See <https://ziglang.org/documentation/master/#Debug>.\n\n\n### Let's debug a program\n\nAs an example, let's use LLDB to navigate and investigate the following\npiece of Zig code:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\nfn add_and_increment(a: u8, b: u8) u8 {\n    const sum = a + b;\n    const incremented = sum + 1;\n    return incremented;\n}\n\npub fn main() !void {\n    var n = add_and_increment(2, 3);\n    n = add_and_increment(n, n);\n    _ = try stdout.print(\"Result: {d}!\\n\", .{n});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 13!\n```\n\n\n:::\n:::\n\n\n\n\nThere is nothing wrong with this program. But it is\na good start for us. First, we need to compile\nthis program with the `zig build-exe` command.\nFor this example, suppose that I have compiled the above\nZig code into a binary executable called `add_program`.\n\n```bash\nzig build-exe add_program.zig\n```\n\nNow, we can start LLDB with `add_program`, like this:\n\n```bash\nlldb add_program\n```\n\nFrom now on, LLDB is started, and you can know that I'm\nexecuting LLDB commands by looking at the prefix `(lldb)`.\nIf something is prefixed with `(lldb)`, then you know\nthat it is a LLDB command.\n\nThe first thing I will do, is to set a breakpoint at\nthe `main()` function, by executing `b main`.\nAfter that, I just start the execution of the program\nwith `run`.\nYou can see in the output below, that the execution\nstopped at the first line in the function `main()`, as we expected.\n\n```bash\n(lldb) b main\nBreakpoint 1: where = debugging`debug1.main + 22\n    at debug1.zig:11:30, address = 0x00000000010341a6\n(lldb) run\nProcess 8654 launched: 'add_program' (x86_64)\nProcess 8654 stopped\n* thread #1, name = 'add_program',\n    stop reason = breakpoint 1.1 frame #0: 0x10341a6\n    add_program`debug1.main at add_program.zig:11:30\n   8   \t}\n   9   \t\n   10  \tpub fn main() !void {\n-> 11  \t    var n = add_and_increment(2, 3);\n   12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n```\n\nI can start navigating through the code, and checking the objects\nthat are being generated. If you are not familiar with the commands\navailable in LLDB, I recommend you to read the official documentation\nof the project[^lldb].\nYou can also look for cheat sheets, which quickly describes all commands\navailable for you[^lldb-quick-list].\n\n[^lldb]: <https://lldb.llvm.org/>\n[^lldb-quick-list]: <https://gist.github.com/ryanchang/a2f738f0c3cc6fbd71fa>.\n\nCurrently, we are in the first line at the `main()` function. In this line, we create\nthe `n` object, by executing the `add_and_increment()` function.\nTo execute the current line of code, and go to the next line, we can\nrun the `n` LLDB command. Let's execute this command.\n\nAfter we executed this line, we can also look at the value stored inside this `n` object\nby using the `p` LLDB command. The syntax for this command is `p <name-of-object>`.\n\nIf we take a look at the value stored in the `n` object (`p n`),\nnotice that it stores the hexadecimal value `0x06`, which\nis the number 6 in decimal. We can also see that this value has a type of `unsigned char`,\nwhich is an unsigned 8-bit integer.\nWe have talked already about this at @sec-zig-strings, that `u8` integers in Zig are equivalent\nto the C data type `unsigned char`.\n\n\n\n```bash\n(lldb) n\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step over frame #0: 0x10341ae\n    debugging`debug1.main at debug1.zig:12:26\n   9   \t\n   10  \tpub fn main() !void {\n   11  \t    var n = add_and_increment(2, 3);\n-> 12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n(lldb) p n\n(unsigned char) $1 = '\\x06'\n```\n\nNow, on the next line of code, we are executing the `add_and_increment()` function once again.\nWhy not step inside this function? Shall we? We can do that, by executing the `s` LLDB command.\nNotice in the example below that, after executing this command, we have entered into the context of the\n`add_and_increment()` function.\n\nAlso notice in the example below that, I have walked two more lines in the function's body, then,\nI execute the `frame variable` LLDB command, to see at once, the value stored in each of the variables\nthat were created inside the current scope.\n\nYou can see in the output below that, the object `sum` stores the value `\\f`,\nwhich represents the *form feed* character. This character in the ASCII table,\ncorresponds to the hexadecimal value `0x0C`, or, in decimal, the number 12.\nSo, this means that the result of the expression `a + b` executed at line\n5, resulted in the number 12.\n\n```bash\n(lldb) s\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step in frame #0: 0x10342de\n    debugging`debug1.add_and_increment(a='\\x02', b='\\x03')\n    at debug1.zig:4:39\n-> 4   \tfn add_and_increment(a: u8, b: u8) u8 {\n   5   \t    const sum = a + b;\n   6   \t    const incremented = sum + 1;\n   7   \t    return incremented;\n(lldb) n\n(lldb) n\n(lldb) frame variable\n(unsigned char) a = '\\x06'\n(unsigned char) b = '\\x06'\n(unsigned char) sum = '\\f'\n(unsigned char) incremented = '\\x06'\n```\n\n\n\n## How to investigate the data type of your objects\n\nSince Zig is a strongly-typed language, the data types associated with your objects\nare very important for your program. So, debugging the data types associated\nwith your objects might be important to understand bugs and errors in your program.\n\nWhen you walk through your program with a debugger, you can inspect the types of\nyour objects by simply printing them to the console, with the LLDB `p` command.\nBut you also have alternatives embedded in the language itself to access the data\ntypes of your objects.\n\nIn Zig, you can retrieve the data type of an object, by using the built-in function\n`@TypeOf()`. Just apply this function over the object, and you get access to \nthe data type of the object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst expect = std.testing.expect;\n\npub fn main() !void {\n    const number: i32 = 5;\n    try expect(@TypeOf(number) == i32);\n    try stdout.print(\"{any}\\n\", .{@TypeOf(number)});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ni32\n```\n\n\n:::\n:::\n\n\n\n\nThis function is similar to the `type()` built-in function from Python,\nor, the `typeof` operator in Javascript.\n\n",
     "supporting": [
       "02-debugging_files"
     ],
diff --git a/_freeze/Chapters/03-structs/execute-results/html.json b/_freeze/Chapters/03-structs/execute-results/html.json
index fb55828f..543363c1 100644
--- a/_freeze/Chapters/03-structs/execute-results/html.json
+++ b/_freeze/Chapters/03-structs/execute-results/html.json
@@ -1,8 +1,8 @@
 {
-  "hash": "75a34188e80fdc2dce5441514f1bc59a",
+  "hash": "ddf3054f897e82f090f3aa7c5890ec78",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Control flow, structs, modules and types\n\nWe have discussed a lot of Zig's syntax in the last chapter,\nespecially in @sec-root-file and @sec-main-file.\nBut we still need to discuss some other very important\nelements of the language. Elements that you will use constantly on your day-to-day\nroutine.\n\nWe begin this chapter by discussing the different keywords and structures\nin Zig related to control flow (e.g. loops and if statements).\nThen, we talk about structs and how they can be used to do some\nbasic Object-Oriented (OOP) patterns in Zig. We also talk about\ntype inference and type casting.\nFinally, we end this chapter by discussing modules, and how they relate\nto structs.\n\n\n\n## Control flow {#sec-zig-control-flow}\n\nSometimes, you need to make decisions in your program. Maybe you need to decide\nwhether or not to execute a specific piece of code. Or maybe,\nyou need to apply the same operation over a sequence of values. These kinds of tasks,\ninvolve using structures that are capable of changing the \"control flow\" of our program.\n\nIn computer science, the term \"control flow\" usually refers to the order in which expressions (or commands)\nare evaluated in a given language or program. But this term is also used to refer\nto structures that are capable of changing this \"evaluation order\" of the commands\nexecuted by a given language/program.\n\nThese structures are better known\nby a set of terms, such as: loops, if/else statements, switch statements, among others. So,\nloops and if/else statements are examples of structures that can change the \"control\nflow\" of our program. The keywords `continue` and `break` are also examples of symbols\nthat can change the order of evaluation, since they can move our program to the next iteration\nof a loop, or make the loop stop completely.\n\n\n### If/else statements\n\nAn if/else statement performs a \"conditional flow operation\".\nA conditional flow control (or choice control) allows you to execute\nor ignore a certain block of commands based on a logical condition.\nMany programmers and computer science professionals also use\nthe term \"branching\" in this case.\nIn essence, an if/else statement allow us to use the result of a logical test\nto decide whether or not to execute a given block of commands.\n\nIn Zig, we write if/else statements by using the keywords `if` and `else`.\nWe start with the `if` keyword followed by a logical test inside a pair\nof parentheses, followed by a pair of curly braces which contains the lines\nof code to be executed in case the logical test returns the value `true`.\n\nAfter that, you can optionally add an `else` statement. To do that, just add the `else`\nkeyword followed by a pair of curly braces, with the lines of code\nto executed in case the logical test defined at `if` returns `false`.\n\nIn the example below, we are testing if the object `x` contains a number\nthat is greater than 10. Judging by the output printed to the console,\nwe know that this logical test returned `false`. Because the output\nin the console is compatible with the line of code present in the\n`else` branch of the if/else statement.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x = 5;\nif (x > 10) {\n    try stdout.print(\n        \"x > 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x <= 10!\\n\", .{}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nx <= 10!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Switch statements {#sec-switch}\n\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust.\nAs you would expect, to write a switch statement in Zig we use the `switch` keyword.\nWe provide the value that we want to \"switch over\" inside a\npair of parentheses. Then, we list the possible combinations (or \"branches\")\ninside a pair of curly braces.\n\nLet's take a look at the code example below. You can see that\nI'm creating an enum type called `Role`. We talk more about enums in @sec-enum.\nBut in summary, this `Role` type is listing different types of roles in a fictitious\ncompany, like `SE` for Software Engineer, `DE` for Data Engineer, `PM` for Product Manager,\netc.\n\nNotice that we are using the value from the `role` object in the\nswitch statement, to discover which exact area we need to store in the `area` variable object.\nAlso notice that we are using type inference inside the switch statement, with the dot character,\nas we are going to describe in @sec-type-inference.\nThis makes the `zig` compiler infer the correct data type of the values (`PM`, `SE`, etc.) for us.\n\nAlso notice that, we are grouping multiple values in the same branch of the switch statement.\nWe just separate each possible value with a comma. For example, if `role` contains either `DE` or `DA`,\nthe `area` variable would contain the value `\"Data & Analytics\"`, instead of `\"Platform\"` or `\"Sales\"`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO => {\n            area = \"Platform\";\n        },\n        .DE, .DA => {\n            area = \"Data & Analytics\";\n        },\n        .KS => {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nPlatform\n```\n\n\n:::\n:::\n\n\n\n\n\n#### Switch statements must exhaust all possibilities\n\nOne very important aspect about switch statements in Zig\nis that they must exhaust all existing possibilities.\nIn other words, all possible values that could be found inside the `role`\nobject must be explicitly handled in this switch statement.\n\nSince the `role` object has type `Role`, the only possible values to\nbe found inside this object are `PM`, `SE`, `DPE`, `PO`, `DE`, `DA` and `KS`.\nThere are no other possible values to be stored in this `role` object.\nThus, the switch statements must have a combination (branch) for each one of these values.\nThis is what \"exhaust all existing possibilities\" means. The switch statement covers\nevery possible case.\n\nTherefore, you cannot write a switch statement in Zig, and leave an edge case\nwith no explicit action to be taken.\nThis is a similar behaviour to switch statements in Rust, which also have to\nhandle all possible cases.\n\n\n\n#### The else branch\n\nTake a look at the `dump_hex_fallible()` function below as an example. This function\ncomes from the Zig Standard Library. More precisely, from the\n[`debug.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/debug.zig)[^debug-mod].\nThere are multiple lines in this function, but I omitted them to focus solely on the\nswitch statement found in this function. Notice that this switch statement has four\npossible cases (i.e. four explicit branches). Also, notice that we used an `else` branch\nin this case.\n\nAn `else` branch in a switch statement works as the \"default branch\".\nWhenever you have multiple cases in your switch statement where\nyou want to apply the exact same action, you can use an `else` branch to do that.\n\n[^debug-mod]: <https://github.com/ziglang/zig/blob/master/lib/std/debug.zig>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' => try writer.writeAll(\"␊\"),\n        '\\r' => try writer.writeAll(\"␍\"),\n        '\\t' => try writer.writeAll(\"␉\"),\n        else => try writer.writeByte('.'),\n    }\n}\n```\n:::\n\n\n\n\nMany programmers would also use an `else` branch to handle a \"not supported\" case.\nThat is, a case that cannot be properly handled by your code, or, just a case that\nshould not be \"fixed\". Therefore, you can use an `else` branch to panic (or raise an error)\nin your program to stop the current execution.\n\nTake the code example below. We can see that, we are handling the cases\nfor the `level` object being either 1, 2, or 3. All other possible cases are not supported by default,\nand, as consequence, we raise a runtime error in such cases through the `@panic()` built-in function.\n\nAlso notice that, we are assigning the result of the switch statement to a new object called `category`.\nThis is another thing that you can do with switch statements in Zig. If a branch\noutputs a value as result, you can store the result value of the switch statement into\na new object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 => \"beginner\",\n    3 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n:::\n\n\n\n\n```\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n```\n\n\n\n#### Using ranges in switch\n\nFurthermore, you can also use ranges of values in switch statements.\nThat is, you can create a branch in your switch statement that is used\nwhenever the input value is within the specified range. These \"range expressions\"\nare created with the operator `...`. It is important\nto emphasize that the ranges created by this operator are\ninclusive on both ends.\n\nFor example, I could easily change the previous code example to support all\nlevels between 0 and 100. Like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 => \"beginner\",\n    26...75 => \"intermediary\",\n    76...100 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nbeginner\n```\n\n\n:::\n:::\n\n\n\n\nThis is neat, and it works with character ranges too. That is, I could\nsimply write `'a'...'z'`, to match any character value that is a\nlowercase letter, and it would work fine.\n\n\n#### Labeled switch statements\n\nIn @sec-blocks we have talked about labeling blocks, and also, about using these labels\nto return a value from the block. Well, from version 0.14.0 and onwards of the `zig` compiler,\nyou can also apply labels over switch statements, which makes it possible to almost implement a\n\"C `goto`\" like pattern.\n\nFor example, if you give the label `xsw` to a switch statement, you can use this\nlabel in conjunction with the `continue` keyword to go back to the beginning of the switch\nstatement. In the example below, the execution goes back to the beginning of the\nswitch statement two times, before ending at the `3` branch.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nxsw: switch (@as(u8, 1)) {\n    1 => {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 => continue :xsw 3,\n    3 => return,\n    4 => {},\n    else => {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n```\n:::\n\n\n\n\n\n### The `defer` keyword {#sec-defer}\n\nWith the `defer` keyword you can register an expression to be executed when you exit the current scope.\nTherefore, this keyword has a similar functionality as the `on.exit()` function from R.\nTake the `foo()` function below as an example. When we execute this `foo()` function, the expression\nthat prints the message \"Exiting function ...\" is getting executed only when the function exits\nits scope.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nAdding some numbers ...\nMultiplying ...\nExiting function ...\n```\n\nTherefore, we can use `defer` to declare an expression that is going to be executed\nwhen your code exits the current scope. Some programmers like to interpret the phrase \"exit of the current scope\"\nas \"the end of the current scope\". But this interpretation might not be entirely correct, depending\non what you consider as \"the end of the current scope\".\n\nI mean, what do you consider as **the end** of the current scope? Is it the closing curly bracket (`}`) of the scope?\nIs it when the last expression in the function get's executed? Is it when the function returns to the previous scope?\nEtc. For example, it would not be correct to interpret the \"exit of the current scope\" as the closing\ncurly bracket of the scope. Because the function might exit from an earlier position than this\nclosing curly bracket (e.g. an error value was generated at a previous line inside the function;\nthe function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\n\nNow, if you remember of what we have discussed in @sec-blocks, there are multiple structures in the language\nthat create their own separate scopes. For/while loops, if/else statements,\nfunctions, normal blocks, etc. This also affects the interpretation of `defer`.\nFor example, if you use `defer` inside a for loop, then, the given expression\nwill be executed everytime this specific for loop exits its own scope.\n\nBefore we continue, is worth emphasizing that the `defer` keyword is an \"unconditional defer\".\nWhich means that the given expression will be executed no matter how the code exits\nthe current scope. For example, your code might exit the current scope because of an error value\nbeing generated, or, because of a return statement, or, a break statement, etc.\n\n\n\n### The `errdefer` keyword {#sec-errdefer1}\n\nOn the previous section, we have discussed the `defer` keyword, which you can use to\nregister an expression to be executed at the exit of the current scope.\nBut this keyword has a brother, which is the `errdefer` keyword. While `defer`\nis an \"unconditional defer\", the `errdefer` keyword is a \"conditional defer\".\nWhich means that the given expression is executed only when you exit the current\nscope on a very specific circumstance.\n\nIn more details, the expression given to `errdefer` is executed only when an error occurs in the current scope.\nTherefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope\nin a normal situation, without errors, the expression given to `errdefer` is not executed.\n\nThis makes the `errdefer` keyword one of the many tools available in Zig for error handling.\nIn this section, we are more concerned with the control flow aspects around `errdefer`.\nBut we are going to discuss `errdefer` later as a error handling tool in @sec-errdefer2.\n\nThe code example below demonstrates three things:\n\n- that `defer` is an \"unconditional defer\", because the given expression get's executed regardless of how the function `foo()` exits its own scope.\n- that `errdefer` is executed because the function `foo()` returned an error value.\n- that `defer` and `errdefer` expressions are executed in a LIFO (*last in, first out*) order.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\nWhen I say that \"defer expressions\" are executed in a LIFO order, what I want to say is that\nthe last `defer` or `errdefer` expressions in the code are the first ones to be executed.\nYou could also interpret this as: \"defer expressions\" are executed from bottom to top, or,\nfrom last to first.\n\nTherefore, if I change the order of the `defer` and `errdefer` expressions, you will notice that\nthe value of `i` that get's printed to the console changes to 1. This doesn't mean that the\n`defer` expression was not executed in this case. This actually means that the `defer` expression\nwas executed only after the `errdefer` expression. The code example below demonstrates this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\n\n\n### For loops\n\nA loop allows you to execute the same lines of code multiple times,\nthus, creating a \"repetition space\" in the execution flow of your program.\nLoops are particularly useful when we want to replicate the same function\n(or the same set of commands) over different inputs.\n\nThere are different types of loops available in Zig. But the most\nessential of them all is probably the *for loop*. A for loop is\nused to apply the same piece of code over the elements of a slice, or, an array.\n\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from\nother languages. You start with the `for` keyword, then, you\nlist the items that you want to iterate\nover inside a pair of parentheses. Then, inside of a pair of pipes (`|`)\nyou should declare an identifier that will serve as your iterator, or,\nthe \"repetition index of the loop\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (items) |value| {\n    // code to execute\n}\n```\n:::\n\n\n\n\nTherefore, instead of using a `(value in items)` syntax,\nin Zig, for loops use the syntax `(items) |value|`. In the example\nbelow, you can see that we are looping through the items\nof the array stored at the object `name`, and printing to the\nconsole the decimal representation of each character in this array.\n\nIf we wanted, we could also iterate through a slice (or a portion) of\nthe array, instead of iterating through the entire array stored in the `name` object.\nJust use a range selector to select the section you want. For example,\nI could provide the expression `name[0..3]` to the for loop, to iterate\njust through the first 3 elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n80 | 101 | 100 | 114 | 111 | \n```\n\n\n:::\n:::\n\n\n\n\nIn the above example we are using the value itself of each\nelement in the array as our iterator. But there are many situations where\nwe need to use an index instead of the actual values of the items.\n\nYou can do that by providing a second set of items to iterate over.\nMore precisely, you provide the range selector `0..` to the for loop. So,\nyes, you can use two different iterators at the same time in a for\nloop in Zig.\n\nBut remember from @sec-assignments that, every object\nyou create in Zig must be used in some way. So if you declare two iterators\nin your for loop, you must use both iterators inside the for loop body.\nBut if you want to use just the index iterator, and not use the \"value iterator\",\nthen, you can discard the value iterator by maching the\nvalue items to the underscore character, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n:::\n\n\n\n\n```\n0 | 1 | 2 | 3 | 4 |\n```\n\n\n### While loops\n\nA while loop is created from the `while` keyword. A `for` loop\niterates through the items of an array, but a `while` loop\nwill loop continuously, and infinitely, until a logical test\n(specified by you) becomes false.\n\nYou start with the `while` keyword, then, you define a logical\nexpression inside a pair of parentheses, and the body of the\nloop is provided inside a pair of curly braces, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\nYou can also specify the increment expression to be used at the beginning of a while loop.\nTo do that, we write the increment expression inside a pair of parentheses after a colon character (`:`).\nThe code example below demonstrates this other pattern.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\n### Using `break` and `continue`\n\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using\nthe keywords `break` and `continue`, respectively. The `while` loop presented in the next code example is,\nat first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to `true`.\nBut what makes this `while` loop stop when the `i` object reaches the count\n10? It is the `break` keyword!\n\nInside the while loop, we have an if statement that is constantly checking if the `i` variable\nis equal to 10. Since we are incrementing the value of `i` at each iteration of the\nwhile loop, this `i` object will eventually be equal to 10, and when it is, the if statement\nwill execute the `break` expression, and, as a result, the execution of the while loop is stopped.\n\nNotice the use of the `expect()` function from the Zig Standard Library after the while loop.\nThis `expect()` function is an \"assert\" type of function.\nThis function checks if the logical test provided is equal to true. If so, the function do nothing.\nOtherwise (i.e. the logical test is equal to false), the function raises an assertion error.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nEverything worked!\n```\n\n\n:::\n:::\n\n\n\n\nSince this code example was executed successfully by the `zig` compiler,\nwithout raising any errors, we known that, after the execution of the while loop,\nthe `i` object is equal to 10. Because if it wasn't equal to 10, an error would have\nbeen raised by `expect()`.\n\nNow, in the next example, we have a use case for\nthe `continue` keyword. The if statement is constantly\nchecking if the current index is a multiple of 2. If\nit is, we jump to the next iteration of the loop.\nOtherwise, the loop just prints the current index to the console.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 3 | 5 | \n```\n\n\n:::\n:::\n\n\n\n\n\n\n## Function parameters are immutable {#sec-fun-pars}\n\nWe have already discussed a lot of the syntax behind function declarations in @sec-root-file and @sec-main-file.\nBut I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig.\nIn summary, function parameters are immutable in Zig.\n\nTake the code example below, where we declare a simple function that just tries to add\nsome amount to the input integer, and returns the result back. If you look closely\nat the body of this `add2()` function, you will notice that we try\nto save the result back into the `x` function argument.\n\nIn other words, this function not only uses the value that it received through the function argument\n`x`, but it also tries to change the value of this function argument, by assigning the addition result\ninto `x`. However, function arguments in Zig are immutable. You cannot change their values, or, you\ncannot assign values to them inside the body's function.\n\nThis is the reason why, the code example below does not compile successfully. If you try to compile\nthis code example, you will get a compile error message about \"trying to change the value of a\nimmutable (i.e. constant) object\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n\n\n```\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n```\n\n\n### A free optimization\n\nIf a function argument receives as input an object whose data type is\nany of the primitive types that we have listed in @sec-primitive-data-types,\nthis object is always passed by value to the function. In other words, this object\nis copied into the function stack frame.\n\nHowever, if the input object have a more complex data type, for example, it might\nbe a struct instance, or an array, or an union value, etc., in cases like that, the `zig` compiler\nwill take the liberty of deciding for you which strategy is best. Thus, the `zig` compiler will\npass your object to the function either by value, or by reference. The compiler will always\nchoose the strategy that is faster for you.\nThis optimization that you get for free is possible only because function arguments are\nimmutable in Zig.\n\n\n### How to overcome this barrier\n\nThere are some situations where you might need to change the value of your function argument\ndirectly inside the function's body. This happens more often when we are passing\nC structs as inputs to Zig functions.\n\nIn a situation like this, you can overcome this barrier by using a pointer. In other words,\ninstead of passing a value as input to the argument, you can pass a \"pointer to value\" instead.\nYou can change the value that the pointer points to, by dereferencing it.\n\nTherefore, if we take our previous `add2()` example, we can change the value of the\nfunction argument `x` inside the function's body by marking the `x` argument as a\n\"pointer to a `u32` value\" (i.e. `*u32` data type), instead of a `u32` value.\nBy making it a pointer, we can finally alter the value of this function argument directly inside\nthe body of the `add2()` function. You can see that the code example below compiles successfully.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n```\n:::\n\n\n\n\n```\nResult: 6\n```\n\n\nEven in this code example above, the `x` argument is still immutable. Which means that the pointer itself is immutable.\nTherefore, you cannot change the memory address that it points to. However, you can dereference the pointer\nto access the value that it points to, and also, to change this value, if you need to.\n\n\n\n\n\n## Structs and OOP {#sec-structs-and-oop}\n\nZig is a language more closely related to C (which is a procedural language),\nthan it is to C++ or Java (which are object-oriented languages). Because of that, you do not\nhave advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or\nclass inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\n\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C.\nYou give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can\nalso register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object\nthat you create with this new type, will always have these methods available and associated with them.\n\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which\nis used to construct (or, to instantiate) every object of this particular class, and we also have\na destructor method (or a destructor function), which is the function responsible for destroying\nevery object of this class.\n\nIn Zig, we normally declare the constructor and the destructor methods\nof our structs, by declaring an `init()` and a `deinit()` methods inside the struct.\nThis is just a naming convention that you will find across the entire Zig Standard Library.\nSo, in Zig, the `init()` method of a struct is normally the constructor method of the class represented by this struct.\nWhile the `deinit()` method is the method used for destroying an existing instance of that struct.\n\nThe `init()` and `deinit()` methods are both used extensively in Zig code, and you will see both of\nthem being used when we talk about allocators in @sec-allocators.\nBut, as another example, let's build a simple `User` struct to represent a user of some sort of system.\n\nIf you look at the `User` struct below, you can see the `struct` keyword.\nNotice the data members of this struct: `id`, `name` and `email`. Every data member has its\ntype explicitly annotated, with the colon character (`:`) syntax that we described earlier in @sec-root-file.\nBut also notice that every line in the struct body that describes a data member, ends with a comma character (`,`).\nSo every time you declare a data member in your Zig code, always end the line with a comma character, instead\nof ending it with the traditional semicolon character (`;`).\n\nNext, we have registered an `init()` function as a method\nof this `User` struct. This `init()` method is the constructor method that we will use to instantiate\nevery new `User` object. That is why this `init()` function returns a new `User` object as result.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    pub fn init(id: u64,\n                name: []const u8,\n                email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    pub fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\npedro\n```\n\n\n:::\n:::\n\n\n\n\nThe `pub` keyword plays an important role in struct declarations, and OOP in Zig.\nEvery method that you declare in your struct that is marked with the keyword `pub`,\nbecomes a public method of this particular struct.\n\nSo every method that you create inside your struct, is, at first, a private method\nof that struct. Meaning that, this method can only be called from within this\nstruct. But, if you mark this method as public, with the keyword `pub`, then,\nyou can call the method directly from an instance of the `User` struct.\n\nIn other words, the functions marked by the keyword `pub`\nare members of the public API of that struct.\nFor example, if I did not mark the `print_name()` method as public,\nthen, I could not execute the line `u.print_name()`. Because I would\nnot be authorized to call this method directly in my code.\n\n\n\n### Anonymous struct literals {#sec-anonymous-struct-literals}\n\nYou can declare a struct object as a literal value. When we do that, we normally specify the\ndata type of this struct literal by writing its data type just before the opening curly brace.\nFor example, I could write a struct literal value of the type `User` that we have defined\nin the previous section like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n```\n:::\n\n\n\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a\nstruct literal, but not specify explicitly the type of this particular struct.\nAn anonymous struct is written by using the syntax `.{}`. So, we essentially\nreplaced the explicit type of the struct literal with a dot character (`.`).\n\nAs we described in @sec-type-inference, when you put a dot before a struct literal,\nthe type of this struct literal is automatically inferred by the `zig` compiler.\nIn essence, the `zig` compiler will look for some hint of what is the type of that struct.\nThis hint can be the type annotation of a function argument,\nor the return type annotation of the function that you are using, or the type annotation\nof an existing object.\nIf the compiler does find such type annotation, it will use this\ntype in your literal struct.\n\nAnonymous structs are very commonly used as inputs to function arguments in Zig.\nOne example that you have seen already constantly, is the `print()`\nfunction from the `stdout` object.\nThis function takes two arguments.\nThe first argument, is a template string, which should\ncontain string format specifiers in it, which tells how the values provided\nin the second argument should be printed into the message.\n\nWhile the second argument is a struct literal that lists the values\nto be printed into the template message specified in the first argument.\nYou normally want to use an anonymous struct literal here, so that the\n`zig` compiler do the job of specifying the type of this particular\nanonymous struct for you.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello, world!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Struct declarations must be constant\n\nTypes in Zig must be `const` or `comptime` (we are going to talk more about comptime in @sec-comptime).\nWhat this means is that you cannot create a new data type, and mark it as variable with the `var` keyword.\nSo struct declarations are always constant. You cannot declare a new struct type using the `var` keyword.\nIt must be `const`.\n\nIn the `Vec3` example below, this declaration is allowed because I'm using the `const` keyword\nto declare this new data type.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n```\n:::\n\n\n\n\n\n### The `self` method argument {#sec-self-arg}\n\nIn every language that have OOP, when we declare a method of some class or struct, we\nusually declare this method as a function that has a `self` argument.\nThis `self` argument is the reference to the object itself from which the method\nis being called from.\n\nIt is not mandatory to use this `self` argument. But why would you not use this `self` argument?\nThere is no reason to not use it. Because the only way to get access to the data stored in the\ndata members of your struct is to access them through this `self` argument.\nIf you don't need to use the data in the data members of your struct inside your method, you very likely don't need\na method. You can just declare this logic as a simple function, outside of your\nstruct declaration.\n\n\nTake the `Vec3` struct below. Inside this `Vec3` struct we declared a method named `distance()`.\nThis method calculates the distance between two `Vec3` objects, by following the distance\nformula in euclidean space. Notice that this `distance()` method takes two `Vec3` objects\nas input, `self` and `other`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n```\n:::\n\n\n\n\n\nThe `self` argument corresponds to the `Vec3` object from which this `distance()` method\nis being called from. While the `other` is a separate `Vec3` object that is given as input\nto this method. In the example below, the `self` argument corresponds to the object\n`v1`, because the `distance()` method is being called from the `v1` object,\nwhile the `other` argument corresponds to the object `v2`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n```\n:::\n\n\n\n\n```\nDistance: 3.3970575502926055\n```\n\n\n\n### About the struct state\n\nSometimes you don't need to care about the state of your struct object. Sometimes, you just need\nto instantiate and use the objects, without altering their state. You can notice that when you have methods\ninside your struct declaration that might use the values that are present in the data members, but they\ndo not alter the values in these data members of the struct in anyway.\n\nThe `Vec3` struct that was presented in @sec-self-arg is an example of that.\nThis struct have a single method named `distance()`, and this method does use the values\npresent in all three data members of the struct (`x`, `y` and `z`). But at the same time,\nthis method does not change the values of these data members at any point.\n\nAs a result of that, when we create `Vec3` objects we usually create them as\nconstant objects, like the `v1` and `v2` objects presented in @sec-self-arg.\nWe can create them as variable objects with the `var` keyword,\nif we want to. But because the methods of this `Vec3` struct do not change\nthe state of the objects in any point, it's unnecessary to mark them\nas variable objects.\n\nBut why? Why am I talking about this here? It's because the `self` argument\nin the methods is affected depending on whether the\nmethods present in a struct change or don't change the state of the object itself.\nMore specifically, when you have a method in a struct that changes the state\nof the object (i.e. change the value of a data member), the `self` argument\nin this method must be annotated in a different manner.\n\nAs I described in @sec-self-arg, the `self` argument in methods of\na struct is the argument that receives as input the object from which the method\nwas called from. We usually annotate this argument in the methods by writing `self`,\nfollowed by the colon character (`:`), and the data type of the struct to which\nthe method belongs to (e.g. `User`, `Vec3`, etc.).\n\nIf we take the `Vec3` struct that we defined in the previous section as an example,\nwe can see in the `distance()` method that this `self` argument is annotated as\n`self: Vec3`. Because the state of the `Vec3` object is never altered by this\nmethod.\n\nBut what if we do have a method that alters the state of the object, by altering the\nvalues of its data members, how should we annotate `self` in this instance? The answer is:\n\"we should annotate `self` as a pointer of `x`, instead of just `x`\".\nIn other words, you should annotate `self` as `self: *x`, instead of annotating it\nas `self: x`.\n\nIf we create a new method inside the `Vec3` object that, for example, expands the\nvector by multiplying its coordinates by a factor of two, then, we need to follow\nthis rule specified in the previous paragraph. The code example below demonstrates\nthis idea:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n```\n:::\n\n\n\n\nNotice in the code example above that we have added a new method\nto our `Vec3` struct named `twice()`. This method doubles the\ncoordinate values of our vector object. In the\ncase of the `twice()` method, we annotated the `self` argument as `*Vec3`,\nindicating that this argument receives a pointer (or a reference, if you prefer to call it this way)\nto a `Vec3` object as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n```\n:::\n\n\n\n\n```\nDoubled: 8.4\n```\n\n\n\nNow, if you change the `self` argument in this `twice()` method to `self: Vec3`, like in the\n`distance()` method, you will get the compiler error exposed below as result. Notice that this\nerror message is showing a line from the `twice()` method body,\nindicating that you cannot alter the value of the `x` data member.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n```\n:::\n\n\n\n\n```\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\n```\n\nThis error message indicates that the `x` data member belongs to a constant object,\nand, because of that, it cannot be changed. Ultimately, this error message\nis telling us that the `self` argument is constant.\n\nIf you take some time, and think hard about this error message, you will understand it.\nYou already have the tools to understand why we are getting this error message.\nWe have talked about it already in @sec-fun-pars.\nSo remember, every function argument is immutable in Zig, and `self`\nis no exception to this rule.\n\nIn this example, we marked the `v3` object as a variable object.\nBut this does not matter. Because it is not about the input object, it is about\nthe function argument.\n\nThe problem begins when we try to alter the value of `self` directly, which is a function argument,\nand, every function argument is immutable by default. You may ask yourself how can we overcome\nthis barrier, and once again, the solution was also discussed in @sec-fun-pars.\nWe overcome this barrier, by explicitly marking the `self` argument as a pointer.\n\n\n::: {.callout-note}\nIf a method of your `x` struct alters the state of the object, by\nchanging the value of any data member, then, remember to use `self: *x`,\ninstead of `self: x` in the function signature of this method.\n:::\n\n\nYou could also interpret the content discussed in this section as:\n\"if you need to alter the state of your `x` struct object in one of its methods,\nyou must explicitly pass the `x` struct object by reference to the `self` argument of this method\".\n\n\n\n## Type inference {#sec-type-inference}\n\nZig is a strongly typed language. But, there are some situations\nwhere you don't have to explicitly write the type of every single object in your source code,\nas you would expect from a traditional strongly typed language, such as C and C++.\n\nIn some situations, the `zig` compiler can use type inference to solve the data types for you, easing some of\nthe burden that you carry as a developer.\nThe most common way this happens is through function arguments that receive struct objects\nas input.\n\nIn general, type inference in Zig is done by using the dot character (`.`).\nEverytime you see a dot character written before a struct literal, or before an enum value, or something like that,\nyou know that this dot character is playing a special party in this place. More specifically, it is\ntelling the `zig` compiler something along the lines of: \"Hey! Can you infer the type of this\nvalue for me? Please!\". In other words, this dot character is playing a similar role as the `auto` keyword in C++.\n\nI gave you some examples of this in @sec-anonymous-struct-literals, where we used anonymous struct literals.\nAnonymous struct literals are, struct literals that use type inference to\ninfer the exact type of this particular struct literal.\nThis type inference is done by looking for some minimal hint of the correct data type to be used.\nYou could say that the `zig` compiler looks for any neighbouring type annotation that might tell it\nwhat the correct type would be.\n\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in @sec-switch).\nI also gave some other examples of type inference in @sec-switch, where we were inferring the data types of enum values listed inside\nof switch statements (e.g. `.DE`).\nBut as another example, take a look at this `fence()` function reproduced below,\nwhich comes from the [`atomic.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig)[^fence-fn]\nof the Zig Standard Library.\n\n[^fence-fn]: <https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig>.\n\nThere are a lot of things in this function that we haven't talked about yet, such as:\nwhat `comptime` means? `inline`? `extern`?\nLet's just ignore all of these things, and focus solely on the switch statement\nthat is inside this function.\n\nWe can see that this switch statement uses the `order` object as input. This `order`\nobject is one of the inputs of this `fence()` function, and we can see in the type annotation,\nthat this object is of type `AtomicOrder`. We can also see a bunch of values inside the\nswitch statements that begin with a dot character, such as `.release` and `.acquire`.\n\nBecause these weird values contain a dot character before them, we are asking the `zig`\ncompiler to infer the types of these values inside the switch statement. Then, the `zig`\ncompiler is looking into the current context where these values are being used, and it is\ntrying to infer the types of these values.\n\nSince they are being used inside a switch statement, the `zig` compiler looks into the type\nof the input object given to the switch statement, which is the `order` object in this case.\nBecause this object have type `AtomicOrder`, the `zig` compiler infers that these values\nare data members from this type `AtomicOrder`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic => @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire => tsan.__tsan_acquire(addr),\n            .release => tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst => {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n```\n:::\n\n\n\n\nThis is how basic type inference is done in Zig. If we didn't use the dot character before\nthe values inside this switch statement, then, we would be forced to explicitly write\nthe data types of these values. For example, instead of writing `.release` we would have to\nwrite `AtomicOrder.release`. We would have to do this for every single value\nin this switch statement, and this is a lot of work. That is why type inference\nis commonly used on switch statements in Zig.\n\n\n\n## Type casting {#sec-type-cast}\n\nIn this section, I want to discuss type casting (or, type conversion) with you.\nWe use type casting when we have an object of type \"x\", and we want to convert\nit into an object of type \"y\", i.e. we want to change the data type of the object.\n\nMost languages have a formal way to perform type casting. In Rust for example, we normally\nuse the keyword `as`, and in C, we normally use the type casting syntax, e.g. `(int) x`.\nIn Zig, we use the `@as()` built-in function to cast an object of type \"x\", into\nan object of type \"y\".\n\nThis `@as()` function is the preferred way to perform type conversion (or type casting)\nin Zig. Because it is explicit, and, it also performs the casting only if it\nis unambiguous and safe. To use this function, you just provide the target data type\nin the first argument, and, the object that you want cast as the second argument.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filecdc41797a754.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\nThis is the general way to perform type casting in Zig. But remember, `@as()` works only when casting\nis unambiguous and safe, and there are situations where these assumptions do not hold. For example,\nwhen casting an integer value into a float value, or vice-versa, it is not clear to the compiler\nhow to perform this conversion safely.\n\nTherefore, we need to use specialized \"casting functions\" in such situations.\nFor example, if you want to cast an integer value into a float value, then, you\nshould use the `@floatFromInt()` function. In the inverse scenario, you should use\nthe `@intFromFloat()` function.\n\nIn these functions, you just provide the object that you want to\ncast as input. Then, the target data type of the \"type casting operation\" is determined by\nthe type annotation of the object where you are saving the results.\nIn the example below, we are casting the object `x` into a value of type `f32`,\nbecause the object `y`, which is where we are saving the results, is annotated\nas an object of type `f32`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filecdc428638149.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\nAnother built-in function that is very useful when performing type casting operations is `@ptrCast()`.\nIn essence, we use the `@as()` built-in function when we want to explicit convert (or cast) a Zig value/object\nfrom a type \"x\" to a type \"y\", etc. However, pointers (we are going to discuss pointers\nin more depth in @sec-pointer) are a special type of object in Zig,\ni.e. they are treated differently from \"normal objects\".\n\nEverytime a pointer is involved in some \"type casting operation\" in Zig, the `@ptrCast()` function is used.\nThis function works similarly to `@floatFromInt()`.\nYou just provide the pointer object that you want to cast as input to this function, and the\ntarget data type is, once again, determined by the type annotation of the object where the results are being\nstored.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filecdc46f71cc03.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## Modules\n\nWe already talked about what modules are, and also, how to import other modules into\nyour current module via *import statements*. Every Zig module (i.e. a `.zig` file) that you write in your project\nis internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the\nZig Standard Library into our current module.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n```\n:::\n\n\n\n\nWhen we want to access the functions and objects from the standard library, we\nare basically accessing the data members of the struct stored in the `std`\nobject. That is why we use the same syntax that we use in normal structs, with the dot operator (`.`)\nto access the data members and methods of the struct.\n\nWhen this \"import statement\" get's executed, the result of this expression is a struct\nobject that contains the Zig Standard Library modules, global variables, functions, etc.\nAnd this struct object get's saved (or stored) inside the constant object named `std`.\n\n\nTake the [`thread_pool.zig` module from the project `zap`](https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig)[^thread]\nas an example. This module is written as if it was\na big struct. That is why we have a top-level and public `init()` method\nwritten in this module. The idea is that all top-level functions written in this\nmodule are methods from the struct, and all top-level objects and struct declarations\nare data members of this struct. The module is the struct itself.\n\n[^thread]: <https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig>\n\n\nSo you would import and use this module by doing something like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst ThreadPool = @import(\"thread_pool.zig\");\nconst num_cpus = std.Thread.getCpuCount()\n    catch @panic(\"failed to get cpu core count\");\nconst num_threads = std.math.cast(u16, num_cpus)\n    catch std.math.maxInt(u16);\nconst pool = ThreadPool.init(\n    .{ .max_threads = num_threads }\n);\n```\n:::\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Control flow, structs, modules and types\n\nWe have discussed a lot of Zig's syntax in the last chapter,\nespecially in @sec-root-file and @sec-main-file.\nBut we still need to discuss some other very important\nelements of the language. Elements that you will use constantly on your day-to-day\nroutine.\n\nWe begin this chapter by discussing the different keywords and structures\nin Zig related to control flow (e.g. loops and if statements).\nThen, we talk about structs and how they can be used to do some\nbasic Object-Oriented (OOP) patterns in Zig. We also talk about\ntype inference and type casting.\nFinally, we end this chapter by discussing modules, and how they relate\nto structs.\n\n\n\n## Control flow {#sec-zig-control-flow}\n\nSometimes, you need to make decisions in your program. Maybe you need to decide\nwhether or not to execute a specific piece of code. Or maybe,\nyou need to apply the same operation over a sequence of values. These kinds of tasks,\ninvolve using structures that are capable of changing the \"control flow\" of our program.\n\nIn computer science, the term \"control flow\" usually refers to the order in which expressions (or commands)\nare evaluated in a given language or program. But this term is also used to refer\nto structures that are capable of changing this \"evaluation order\" of the commands\nexecuted by a given language/program.\n\nThese structures are better known\nby a set of terms, such as: loops, if/else statements, switch statements, among others. So,\nloops and if/else statements are examples of structures that can change the \"control\nflow\" of our program. The keywords `continue` and `break` are also examples of symbols\nthat can change the order of evaluation, since they can move our program to the next iteration\nof a loop, or make the loop stop completely.\n\n\n### If/else statements\n\nAn if/else statement performs a \"conditional flow operation\".\nA conditional flow control (or choice control) allows you to execute\nor ignore a certain block of commands based on a logical condition.\nMany programmers and computer science professionals also use\nthe term \"branching\" in this case.\nIn essence, an if/else statement allow us to use the result of a logical test\nto decide whether or not to execute a given block of commands.\n\nIn Zig, we write if/else statements by using the keywords `if` and `else`.\nWe start with the `if` keyword followed by a logical test inside a pair\nof parentheses, followed by a pair of curly braces which contains the lines\nof code to be executed in case the logical test returns the value `true`.\n\nAfter that, you can optionally add an `else` statement. To do that, just add the `else`\nkeyword followed by a pair of curly braces, with the lines of code\nto executed in case the logical test defined at `if` returns `false`.\n\nIn the example below, we are testing if the object `x` contains a number\nthat is greater than 10. Judging by the output printed to the console,\nwe know that this logical test returned `false`. Because the output\nin the console is compatible with the line of code present in the\n`else` branch of the if/else statement.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x = 5;\nif (x > 10) {\n    try stdout.print(\n        \"x > 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x <= 10!\\n\", .{}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nx <= 10!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Switch statements {#sec-switch}\n\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust.\nAs you would expect, to write a switch statement in Zig we use the `switch` keyword.\nWe provide the value that we want to \"switch over\" inside a\npair of parentheses. Then, we list the possible combinations (or \"branches\")\ninside a pair of curly braces.\n\nLet's take a look at the code example below. You can see that\nI'm creating an enum type called `Role`. We talk more about enums in @sec-enum.\nBut in summary, this `Role` type is listing different types of roles in a fictitious\ncompany, like `SE` for Software Engineer, `DE` for Data Engineer, `PM` for Product Manager,\netc.\n\nNotice that we are using the value from the `role` object in the\nswitch statement, to discover which exact area we need to store in the `area` variable object.\nAlso notice that we are using type inference inside the switch statement, with the dot character,\nas we are going to describe in @sec-type-inference.\nThis makes the `zig` compiler infer the correct data type of the values (`PM`, `SE`, etc.) for us.\n\nAlso notice that, we are grouping multiple values in the same branch of the switch statement.\nWe just separate each possible value with a comma. For example, if `role` contains either `DE` or `DA`,\nthe `area` variable would contain the value `\"Data & Analytics\"`, instead of `\"Platform\"` or `\"Sales\"`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO => {\n            area = \"Platform\";\n        },\n        .DE, .DA => {\n            area = \"Data & Analytics\";\n        },\n        .KS => {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nPlatform\n```\n\n\n:::\n:::\n\n\n\n\n\n#### Switch statements must exhaust all possibilities\n\nOne very important aspect about switch statements in Zig\nis that they must exhaust all existing possibilities.\nIn other words, all possible values that could be found inside the `role`\nobject must be explicitly handled in this switch statement.\n\nSince the `role` object has type `Role`, the only possible values to\nbe found inside this object are `PM`, `SE`, `DPE`, `PO`, `DE`, `DA` and `KS`.\nThere are no other possible values to be stored in this `role` object.\nThus, the switch statements must have a combination (branch) for each one of these values.\nThis is what \"exhaust all existing possibilities\" means. The switch statement covers\nevery possible case.\n\nTherefore, you cannot write a switch statement in Zig, and leave an edge case\nwith no explicit action to be taken.\nThis is a similar behaviour to switch statements in Rust, which also have to\nhandle all possible cases.\n\n\n\n#### The else branch\n\nTake a look at the `dump_hex_fallible()` function below as an example. This function\ncomes from the Zig Standard Library. More precisely, from the\n[`debug.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/debug.zig)[^debug-mod].\nThere are multiple lines in this function, but I omitted them to focus solely on the\nswitch statement found in this function. Notice that this switch statement has four\npossible cases (i.e. four explicit branches). Also, notice that we used an `else` branch\nin this case.\n\nAn `else` branch in a switch statement works as the \"default branch\".\nWhenever you have multiple cases in your switch statement where\nyou want to apply the exact same action, you can use an `else` branch to do that.\n\n[^debug-mod]: <https://github.com/ziglang/zig/blob/master/lib/std/debug.zig>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' => try writer.writeAll(\"␊\"),\n        '\\r' => try writer.writeAll(\"␍\"),\n        '\\t' => try writer.writeAll(\"␉\"),\n        else => try writer.writeByte('.'),\n    }\n}\n```\n:::\n\n\n\n\nMany programmers would also use an `else` branch to handle a \"not supported\" case.\nThat is, a case that cannot be properly handled by your code, or, just a case that\nshould not be \"fixed\". Therefore, you can use an `else` branch to panic (or raise an error)\nin your program to stop the current execution.\n\nTake the code example below. We can see that, we are handling the cases\nfor the `level` object being either 1, 2, or 3. All other possible cases are not supported by default,\nand, as consequence, we raise a runtime error in such cases through the `@panic()` built-in function.\n\nAlso notice that, we are assigning the result of the switch statement to a new object called `category`.\nThis is another thing that you can do with switch statements in Zig. If a branch\noutputs a value as result, you can store the result value of the switch statement into\na new object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 => \"beginner\",\n    3 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n:::\n\n\n\n\n```\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n```\n\n\n\n#### Using ranges in switch\n\nFurthermore, you can also use ranges of values in switch statements.\nThat is, you can create a branch in your switch statement that is used\nwhenever the input value is within the specified range. These \"range expressions\"\nare created with the operator `...`. It is important\nto emphasize that the ranges created by this operator are\ninclusive on both ends.\n\nFor example, I could easily change the previous code example to support all\nlevels between 0 and 100. Like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 => \"beginner\",\n    26...75 => \"intermediary\",\n    76...100 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nbeginner\n```\n\n\n:::\n:::\n\n\n\n\nThis is neat, and it works with character ranges too. That is, I could\nsimply write `'a'...'z'`, to match any character value that is a\nlowercase letter, and it would work fine.\n\n\n#### Labeled switch statements\n\nIn @sec-blocks we have talked about labeling blocks, and also, about using these labels\nto return a value from the block. Well, from version 0.14.0 and onwards of the `zig` compiler,\nyou can also apply labels over switch statements, which makes it possible to almost implement a\n\"C `goto`\" like pattern.\n\nFor example, if you give the label `xsw` to a switch statement, you can use this\nlabel in conjunction with the `continue` keyword to go back to the beginning of the switch\nstatement. In the example below, the execution goes back to the beginning of the\nswitch statement two times, before ending at the `3` branch.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nxsw: switch (@as(u8, 1)) {\n    1 => {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 => continue :xsw 3,\n    3 => return,\n    4 => {},\n    else => {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n```\n:::\n\n\n\n\n\n### The `defer` keyword {#sec-defer}\n\nWith the `defer` keyword you can register an expression to be executed when you exit the current scope.\nTherefore, this keyword has a similar functionality as the `on.exit()` function from R.\nTake the `foo()` function below as an example. When we execute this `foo()` function, the expression\nthat prints the message \"Exiting function ...\" is getting executed only when the function exits\nits scope.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nAdding some numbers ...\nMultiplying ...\nExiting function ...\n```\n\nTherefore, we can use `defer` to declare an expression that is going to be executed\nwhen your code exits the current scope. Some programmers like to interpret the phrase \"exit of the current scope\"\nas \"the end of the current scope\". But this interpretation might not be entirely correct, depending\non what you consider as \"the end of the current scope\".\n\nI mean, what do you consider as **the end** of the current scope? Is it the closing curly bracket (`}`) of the scope?\nIs it when the last expression in the function gets executed? Is it when the function returns to the previous scope?\nEtc. For example, it would not be correct to interpret the \"exit of the current scope\" as the closing\ncurly bracket of the scope. Because the function might exit from an earlier position than this\nclosing curly bracket (e.g. an error value was generated at a previous line inside the function;\nthe function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\n\nNow, if you remember of what we have discussed in @sec-blocks, there are multiple structures in the language\nthat create their own separate scopes. For/while loops, if/else statements,\nfunctions, normal blocks, etc. This also affects the interpretation of `defer`.\nFor example, if you use `defer` inside a for loop, then, the given expression\nwill be executed everytime this specific for loop exits its own scope.\n\nBefore we continue, is worth emphasizing that the `defer` keyword is an \"unconditional defer\".\nWhich means that the given expression will be executed no matter how the code exits\nthe current scope. For example, your code might exit the current scope because of an error value\nbeing generated, or, because of a return statement, or, a break statement, etc.\n\n\n\n### The `errdefer` keyword {#sec-errdefer1}\n\nOn the previous section, we have discussed the `defer` keyword, which you can use to\nregister an expression to be executed at the exit of the current scope.\nBut this keyword has a brother, which is the `errdefer` keyword. While `defer`\nis an \"unconditional defer\", the `errdefer` keyword is a \"conditional defer\".\nWhich means that the given expression is executed only when you exit the current\nscope on a very specific circumstance.\n\nIn more details, the expression given to `errdefer` is executed only when an error occurs in the current scope.\nTherefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope\nin a normal situation, without errors, the expression given to `errdefer` is not executed.\n\nThis makes the `errdefer` keyword one of the many tools available in Zig for error handling.\nIn this section, we are more concerned with the control flow aspects around `errdefer`.\nBut we are going to discuss `errdefer` later as a error handling tool in @sec-errdefer2.\n\nThe code example below demonstrates three things:\n\n- that `defer` is an \"unconditional defer\", because the given expression get's executed regardless of how the function `foo()` exits its own scope.\n- that `errdefer` is executed because the function `foo()` returned an error value.\n- that `defer` and `errdefer` expressions are executed in a LIFO (*last in, first out*) order.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\nWhen I say that \"defer expressions\" are executed in a LIFO order, what I want to say is that\nthe last `defer` or `errdefer` expressions in the code are the first ones to be executed.\nYou could also interpret this as: \"defer expressions\" are executed from bottom to top, or,\nfrom last to first.\n\nTherefore, if I change the order of the `defer` and `errdefer` expressions, you will notice that\nthe value of `i` that get's printed to the console changes to 1. This doesn't mean that the\n`defer` expression was not executed in this case. This actually means that the `defer` expression\nwas executed only after the `errdefer` expression. The code example below demonstrates this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\n\n\n### For loops\n\nA loop allows you to execute the same lines of code multiple times,\nthus, creating a \"repetition space\" in the execution flow of your program.\nLoops are particularly useful when we want to replicate the same function\n(or the same set of commands) over different inputs.\n\nThere are different types of loops available in Zig. But the most\nessential of them all is probably the *for loop*. A for loop is\nused to apply the same piece of code over the elements of a slice, or, an array.\n\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from\nother languages. You start with the `for` keyword, then, you\nlist the items that you want to iterate\nover inside a pair of parentheses. Then, inside of a pair of pipes (`|`)\nyou should declare an identifier that will serve as your iterator, or,\nthe \"repetition index of the loop\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (items) |value| {\n    // code to execute\n}\n```\n:::\n\n\n\n\nTherefore, instead of using a `(value in items)` syntax,\nin Zig, for loops use the syntax `(items) |value|`. In the example\nbelow, you can see that we are looping through the items\nof the array stored at the object `name`, and printing to the\nconsole the decimal representation of each character in this array.\n\nIf we wanted, we could also iterate through a slice (or a portion) of\nthe array, instead of iterating through the entire array stored in the `name` object.\nJust use a range selector to select the section you want. For example,\nI could provide the expression `name[0..3]` to the for loop, to iterate\njust through the first 3 elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n80 | 101 | 100 | 114 | 111 | \n```\n\n\n:::\n:::\n\n\n\n\nIn the above example we are using the value itself of each\nelement in the array as our iterator. But there are many situations where\nwe need to use an index instead of the actual values of the items.\n\nYou can do that by providing a second set of items to iterate over.\nMore precisely, you provide the range selector `0..` to the for loop. So,\nyes, you can use two different iterators at the same time in a for\nloop in Zig.\n\nBut remember from @sec-assignments that, every object\nyou create in Zig must be used in some way. So if you declare two iterators\nin your for loop, you must use both iterators inside the for loop body.\nBut if you want to use just the index iterator, and not use the \"value iterator\",\nthen, you can discard the value iterator by maching the\nvalue items to the underscore character, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n:::\n\n\n\n\n```\n0 | 1 | 2 | 3 | 4 |\n```\n\n\n### While loops\n\nA while loop is created from the `while` keyword. A `for` loop\niterates through the items of an array, but a `while` loop\nwill loop continuously, and infinitely, until a logical test\n(specified by you) becomes false.\n\nYou start with the `while` keyword, then, you define a logical\nexpression inside a pair of parentheses, and the body of the\nloop is provided inside a pair of curly braces, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\nYou can also specify the increment expression to be used at the beginning of a while loop.\nTo do that, we write the increment expression inside a pair of parentheses after a colon character (`:`).\nThe code example below demonstrates this other pattern.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\n### Using `break` and `continue`\n\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using\nthe keywords `break` and `continue`, respectively. The `while` loop presented in the next code example is,\nat first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to `true`.\nBut what makes this `while` loop stop when the `i` object reaches the count\n10? It is the `break` keyword!\n\nInside the while loop, we have an if statement that is constantly checking if the `i` variable\nis equal to 10. Since we are incrementing the value of `i` at each iteration of the\nwhile loop, this `i` object will eventually be equal to 10, and when it is, the if statement\nwill execute the `break` expression, and, as a result, the execution of the while loop is stopped.\n\nNotice the use of the `expect()` function from the Zig Standard Library after the while loop.\nThis `expect()` function is an \"assert\" type of function.\nThis function checks if the logical test provided is equal to true. If so, the function do nothing.\nOtherwise (i.e. the logical test is equal to false), the function raises an assertion error.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nEverything worked!\n```\n\n\n:::\n:::\n\n\n\n\nSince this code example was executed successfully by the `zig` compiler,\nwithout raising any errors, we known that, after the execution of the while loop,\nthe `i` object is equal to 10. Because if it wasn't equal to 10, an error would have\nbeen raised by `expect()`.\n\nNow, in the next example, we have a use case for\nthe `continue` keyword. The if statement is constantly\nchecking if the current index is a multiple of 2. If\nit is, we jump to the next iteration of the loop.\nOtherwise, the loop just prints the current index to the console.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 3 | 5 | \n```\n\n\n:::\n:::\n\n\n\n\n\n\n## Function parameters are immutable {#sec-fun-pars}\n\nWe have already discussed a lot of the syntax behind function declarations in @sec-root-file and @sec-main-file.\nBut I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig.\nIn summary, function parameters are immutable in Zig.\n\nTake the code example below, where we declare a simple function that just tries to add\nsome amount to the input integer, and returns the result back. If you look closely\nat the body of this `add2()` function, you will notice that we try\nto save the result back into the `x` function argument.\n\nIn other words, this function not only uses the value that it received through the function argument\n`x`, but it also tries to change the value of this function argument, by assigning the addition result\ninto `x`. However, function arguments in Zig are immutable. You cannot change their values, or, you\ncannot assign values to them inside the body's function.\n\nThis is the reason why, the code example below does not compile successfully. If you try to compile\nthis code example, you will get a compile error message about \"trying to change the value of a\nimmutable (i.e. constant) object\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n\n\n```\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n```\n\n\n### A free optimization\n\nIf a function argument receives as input an object whose data type is\nany of the primitive types that we have listed in @sec-primitive-data-types,\nthis object is always passed by value to the function. In other words, this object\nis copied into the function stack frame.\n\nHowever, if the input object have a more complex data type, for example, it might\nbe a struct instance, or an array, or an union value, etc., in cases like that, the `zig` compiler\nwill take the liberty of deciding for you which strategy is best. Thus, the `zig` compiler will\npass your object to the function either by value, or by reference. The compiler will always\nchoose the strategy that is faster for you.\nThis optimization that you get for free is possible only because function arguments are\nimmutable in Zig.\n\n\n### How to overcome this barrier\n\nThere are some situations where you might need to change the value of your function argument\ndirectly inside the function's body. This happens more often when we are passing\nC structs as inputs to Zig functions.\n\nIn a situation like this, you can overcome this barrier by using a pointer. In other words,\ninstead of passing a value as input to the argument, you can pass a \"pointer to value\" instead.\nYou can change the value that the pointer points to, by dereferencing it.\n\nTherefore, if we take our previous `add2()` example, we can change the value of the\nfunction argument `x` inside the function's body by marking the `x` argument as a\n\"pointer to a `u32` value\" (i.e. `*u32` data type), instead of a `u32` value.\nBy making it a pointer, we can finally alter the value of this function argument directly inside\nthe body of the `add2()` function. You can see that the code example below compiles successfully.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n```\n:::\n\n\n\n\n```\nResult: 6\n```\n\n\nEven in this code example above, the `x` argument is still immutable. Which means that the pointer itself is immutable.\nTherefore, you cannot change the memory address that it points to. However, you can dereference the pointer\nto access the value that it points to, and also, to change this value, if you need to.\n\n\n\n\n\n## Structs and OOP {#sec-structs-and-oop}\n\nZig is a language more closely related to C (which is a procedural language),\nthan it is to C++ or Java (which are object-oriented languages). Because of that, you do not\nhave advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or\nclass inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\n\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C.\nYou give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can\nalso register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object\nthat you create with this new type, will always have these methods available and associated with them.\n\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which\nis used to construct (or, to instantiate) every object of this particular class, and we also have\na destructor method (or a destructor function), which is the function responsible for destroying\nevery object of this class.\n\nIn Zig, we normally declare the constructor and the destructor methods\nof our structs, by declaring an `init()` and a `deinit()` methods inside the struct.\nThis is just a naming convention that you will find across the entire Zig Standard Library.\nSo, in Zig, the `init()` method of a struct is normally the constructor method of the class represented by this struct.\nWhile the `deinit()` method is the method used for destroying an existing instance of that struct.\n\nThe `init()` and `deinit()` methods are both used extensively in Zig code, and you will see both of\nthem being used when we talk about allocators in @sec-allocators.\nBut, as another example, let's build a simple `User` struct to represent a user of some sort of system.\n\nIf you look at the `User` struct below, you can see the `struct` keyword.\nNotice the data members of this struct: `id`, `name` and `email`. Every data member has its\ntype explicitly annotated, with the colon character (`:`) syntax that we described earlier in @sec-root-file.\nBut also notice that every line in the struct body that describes a data member, ends with a comma character (`,`).\nSo every time you declare a data member in your Zig code, always end the line with a comma character, instead\nof ending it with the traditional semicolon character (`;`).\n\nNext, we have registered an `init()` function as a method\nof this `User` struct. This `init()` method is the constructor method that we will use to instantiate\nevery new `User` object. That is why this `init()` function returns a new `User` object as result.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    pub fn init(id: u64,\n                name: []const u8,\n                email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    pub fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\npedro\n```\n\n\n:::\n:::\n\n\n\n\nThe `pub` keyword plays an important role in struct declarations, and OOP in Zig.\nEvery method that you declare in your struct that is marked with the keyword `pub`,\nbecomes a public method of this particular struct.\n\nSo every method that you create inside your struct, is, at first, a private method\nof that struct. Meaning that, this method can only be called from within this\nstruct. But, if you mark this method as public, with the keyword `pub`, then,\nyou can call the method directly from an instance of the `User` struct.\n\nIn other words, the functions marked by the keyword `pub`\nare members of the public API of that struct.\nFor example, if I did not mark the `print_name()` method as public,\nthen, I could not execute the line `u.print_name()`. Because I would\nnot be authorized to call this method directly in my code.\n\n\n\n### Anonymous struct literals {#sec-anonymous-struct-literals}\n\nYou can declare a struct object as a literal value. When we do that, we normally specify the\ndata type of this struct literal by writing its data type just before the opening curly brace.\nFor example, I could write a struct literal value of the type `User` that we have defined\nin the previous section like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n```\n:::\n\n\n\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a\nstruct literal, but not specify explicitly the type of this particular struct.\nAn anonymous struct is written by using the syntax `.{}`. So, we essentially\nreplaced the explicit type of the struct literal with a dot character (`.`).\n\nAs we described in @sec-type-inference, when you put a dot before a struct literal,\nthe type of this struct literal is automatically inferred by the `zig` compiler.\nIn essence, the `zig` compiler will look for some hint of what is the type of that struct.\nThis hint can be the type annotation of a function argument,\nor the return type annotation of the function that you are using, or the type annotation\nof an existing object.\nIf the compiler does find such type annotation, it will use this\ntype in your literal struct.\n\nAnonymous structs are very commonly used as inputs to function arguments in Zig.\nOne example that you have seen already constantly, is the `print()`\nfunction from the `stdout` object.\nThis function takes two arguments.\nThe first argument, is a template string, which should\ncontain string format specifiers in it, which tells how the values provided\nin the second argument should be printed into the message.\n\nWhile the second argument is a struct literal that lists the values\nto be printed into the template message specified in the first argument.\nYou normally want to use an anonymous struct literal here, so that the\n`zig` compiler do the job of specifying the type of this particular\nanonymous struct for you.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello, world!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Struct declarations must be constant\n\nTypes in Zig must be `const` or `comptime` (we are going to talk more about comptime in @sec-comptime).\nWhat this means is that you cannot create a new data type, and mark it as variable with the `var` keyword.\nSo struct declarations are always constant. You cannot declare a new struct type using the `var` keyword.\nIt must be `const`.\n\nIn the `Vec3` example below, this declaration is allowed because I'm using the `const` keyword\nto declare this new data type.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n```\n:::\n\n\n\n\n\n### The `self` method argument {#sec-self-arg}\n\nIn every language that have OOP, when we declare a method of some class or struct, we\nusually declare this method as a function that has a `self` argument.\nThis `self` argument is the reference to the object itself from which the method\nis being called from.\n\nIt is not mandatory to use this `self` argument. But why would you not use this `self` argument?\nThere is no reason to not use it. Because the only way to get access to the data stored in the\ndata members of your struct is to access them through this `self` argument.\nIf you don't need to use the data in the data members of your struct inside your method, you very likely don't need\na method. You can just declare this logic as a simple function, outside of your\nstruct declaration.\n\n\nTake the `Vec3` struct below. Inside this `Vec3` struct we declared a method named `distance()`.\nThis method calculates the distance between two `Vec3` objects, by following the distance\nformula in euclidean space. Notice that this `distance()` method takes two `Vec3` objects\nas input, `self` and `other`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n```\n:::\n\n\n\n\n\nThe `self` argument corresponds to the `Vec3` object from which this `distance()` method\nis being called from. While the `other` is a separate `Vec3` object that is given as input\nto this method. In the example below, the `self` argument corresponds to the object\n`v1`, because the `distance()` method is being called from the `v1` object,\nwhile the `other` argument corresponds to the object `v2`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n```\n:::\n\n\n\n\n```\nDistance: 3.3970575502926055\n```\n\n\n\n### About the struct state\n\nSometimes you don't need to care about the state of your struct object. Sometimes, you just need\nto instantiate and use the objects, without altering their state. You can notice that when you have methods\ninside your struct declaration that might use the values that are present in the data members, but they\ndo not alter the values in these data members of the struct in anyway.\n\nThe `Vec3` struct that was presented in @sec-self-arg is an example of that.\nThis struct have a single method named `distance()`, and this method does use the values\npresent in all three data members of the struct (`x`, `y` and `z`). But at the same time,\nthis method does not change the values of these data members at any point.\n\nAs a result of that, when we create `Vec3` objects we usually create them as\nconstant objects, like the `v1` and `v2` objects presented in @sec-self-arg.\nWe can create them as variable objects with the `var` keyword,\nif we want to. But because the methods of this `Vec3` struct do not change\nthe state of the objects in any point, it's unnecessary to mark them\nas variable objects.\n\nBut why? Why am I talking about this here? It's because the `self` argument\nin the methods are affected depending on whether the\nmethods present in a struct change or don't change the state of the object itself.\nMore specifically, when you have a method in a struct that changes the state\nof the object (i.e. changes the value of a data member), the `self` argument\nin this method must be annotated in a different manner.\n\nAs I described in @sec-self-arg, the `self` argument in methods of\na struct is the argument that receives as input the object from which the method\nwas called from. We usually annotate this argument in the methods by writing `self`,\nfollowed by the colon character (`:`), and the data type of the struct to which\nthe method belongs to (e.g. `User`, `Vec3`, etc.).\n\nIf we take the `Vec3` struct that we defined in the previous section as an example,\nwe can see in the `distance()` method that this `self` argument is annotated as\n`self: Vec3`. Because the state of the `Vec3` object is never altered by this\nmethod.\n\nBut what if we do have a method that alters the state of the object, by altering the\nvalues of its data members, how should we annotate `self` in this instance? The answer is:\n\"we should annotate `self` as a pointer of `x`, instead of just `x`\".\nIn other words, you should annotate `self` as `self: *x`, instead of annotating it\nas `self: x`.\n\nIf we create a new method inside the `Vec3` object that, for example, expands the\nvector by multiplying its coordinates by a factor of two, then, we need to follow\nthis rule specified in the previous paragraph. The code example below demonstrates\nthis idea:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n```\n:::\n\n\n\n\nNotice in the code example above that we have added a new method\nto our `Vec3` struct named `twice()`. This method doubles the\ncoordinate values of our vector object. In the\ncase of the `twice()` method, we annotated the `self` argument as `*Vec3`,\nindicating that this argument receives a pointer (or a reference, if you prefer to call it this way)\nto a `Vec3` object as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n```\n:::\n\n\n\n\n```\nDoubled: 8.4\n```\n\n\n\nNow, if you change the `self` argument in this `twice()` method to `self: Vec3`, like in the\n`distance()` method, you will get the compiler error exposed below as result. Notice that this\nerror message is showing a line from the `twice()` method body,\nindicating that you cannot alter the value of the `x` data member.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n```\n:::\n\n\n\n\n```\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\n```\n\nThis error message indicates that the `x` data member belongs to a constant object,\nand, because of that, it cannot be changed. Ultimately, this error message\nis telling us that the `self` argument is constant.\n\nIf you take some time, and think hard about this error message, you will understand it.\nYou already have the tools to understand why we are getting this error message.\nWe have talked about it already in @sec-fun-pars.\nSo remember, every function argument is immutable in Zig, and `self`\nis no exception to this rule.\n\nIn this example, we marked the `v3` object as a variable object.\nBut this does not matter. Because it is not about the input object, it is about\nthe function argument.\n\nThe problem begins when we try to alter the value of `self` directly, which is a function argument,\nand, every function argument is immutable by default. You may ask yourself how can we overcome\nthis barrier, and once again, the solution was also discussed in @sec-fun-pars.\nWe overcome this barrier, by explicitly marking the `self` argument as a pointer.\n\n\n::: {.callout-note}\nIf a method of your `x` struct alters the state of the object, by\nchanging the value of any data member, then, remember to use `self: *x`,\ninstead of `self: x` in the function signature of this method.\n:::\n\n\nYou could also interpret the content discussed in this section as:\n\"if you need to alter the state of your `x` struct object in one of its methods,\nyou must explicitly pass the `x` struct object by reference to the `self` argument of this method\".\n\n\n\n## Type inference {#sec-type-inference}\n\nZig is a strongly typed language. But, there are some situations\nwhere you don't have to explicitly write the type of every single object in your source code,\nas you would expect from a traditional strongly typed language, such as C and C++.\n\nIn some situations, the `zig` compiler can use type inference to solve the data types for you, easing some of\nthe burden that you carry as a developer.\nThe most common way this happens is through function arguments that receive struct objects\nas input.\n\nIn general, type inference in Zig is done by using the dot character (`.`).\nEverytime you see a dot character written before a struct literal, or before an enum value, or something like that,\nyou know that this dot character is playing a special part in this place. More specifically, it is\ntelling the `zig` compiler something along the lines of: \"Hey! Can you infer the type of this\nvalue for me? Please!\". In other words, this dot character is playing a similar role as the `auto` keyword in C++.\n\nI gave you some examples of this in @sec-anonymous-struct-literals, where we used anonymous struct literals.\nAnonymous struct literals are, struct literals that use type inference to\ninfer the exact type of this particular struct literal.\nThis type inference is done by looking for some minimal hint of the correct data type to be used.\nYou could say that the `zig` compiler looks for any neighbouring type annotation that might tell it\nwhat the correct type would be.\n\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in @sec-switch).\nI also gave some other examples of type inference in @sec-switch, where we were inferring the data types of enum values listed inside\nof switch statements (e.g. `.DE`).\nBut as another example, take a look at this `fence()` function reproduced below,\nwhich comes from the [`atomic.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig)[^fence-fn]\nof the Zig Standard Library.\n\n[^fence-fn]: <https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig>.\n\nThere are a lot of things in this function that we haven't talked about yet, such as:\nwhat `comptime` means? `inline`? `extern`?\nLet's just ignore all of these things, and focus solely on the switch statement\nthat is inside this function.\n\nWe can see that this switch statement uses the `order` object as input. This `order`\nobject is one of the inputs of this `fence()` function, and we can see in the type annotation,\nthat this object is of type `AtomicOrder`. We can also see a bunch of values inside the\nswitch statements that begin with a dot character, such as `.release` and `.acquire`.\n\nBecause these weird values contain a dot character before them, we are asking the `zig`\ncompiler to infer the types of these values inside the switch statement. Then, the `zig`\ncompiler is looking into the current context where these values are being used, and it is\ntrying to infer the types of these values.\n\nSince they are being used inside a switch statement, the `zig` compiler looks into the type\nof the input object given to the switch statement, which is the `order` object in this case.\nBecause this object have type `AtomicOrder`, the `zig` compiler infers that these values\nare data members from this type `AtomicOrder`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic => @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire => tsan.__tsan_acquire(addr),\n            .release => tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst => {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n```\n:::\n\n\n\n\nThis is how basic type inference is done in Zig. If we didn't use the dot character before\nthe values inside this switch statement, then, we would be forced to explicitly write\nthe data types of these values. For example, instead of writing `.release` we would have to\nwrite `AtomicOrder.release`. We would have to do this for every single value\nin this switch statement, and this is a lot of work. That is why type inference\nis commonly used on switch statements in Zig.\n\n\n\n## Type casting {#sec-type-cast}\n\nIn this section, I want to discuss type casting (or, type conversion) with you.\nWe use type casting when we have an object of type \"x\", and we want to convert\nit into an object of type \"y\", i.e. we want to change the data type of the object.\n\nMost languages have a formal way to perform type casting. In Rust for example, we normally\nuse the keyword `as`, and in C, we normally use the type casting syntax, e.g. `(int) x`.\nIn Zig, we use the `@as()` built-in function to cast an object of type \"x\", into\nan object of type \"y\".\n\nThis `@as()` function is the preferred way to perform type conversion (or type casting)\nin Zig. Because it is explicit, and, it also performs the casting only if it\nis unambiguous and safe. To use this function, you just provide the target data type\nin the first argument, and, the object that you want cast as the second argument.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file2ed34a8fc96.test_0...OKAll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\nThis is the general way to perform type casting in Zig. But remember, `@as()` works only when casting\nis unambiguous and safe, and there are situations where these assumptions do not hold. For example,\nwhen casting an integer value into a float value, or vice-versa, it is not clear to the compiler\nhow to perform this conversion safely.\n\nTherefore, we need to use specialized \"casting functions\" in such situations.\nFor example, if you want to cast an integer value into a float value, then, you\nshould use the `@floatFromInt()` function. In the inverse scenario, you should use\nthe `@intFromFloat()` function.\n\nIn these functions, you just provide the object that you want to\ncast as input. Then, the target data type of the \"type casting operation\" is determined by\nthe type annotation of the object where you are saving the results.\nIn the example below, we are casting the object `x` into a value of type `f32`,\nbecause the object `y`, which is where we are saving the results, is annotated\nas an object of type `f32`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file2ed34bfb9fa5.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\nAnother built-in function that is very useful when performing type casting operations is `@ptrCast()`.\nIn essence, we use the `@as()` built-in function when we want to explicit convert (or cast) a Zig value/object\nfrom a type \"x\" to a type \"y\", etc. However, pointers (we are going to discuss pointers\nin more depth in @sec-pointer) are a special type of object in Zig,\ni.e. they are treated differently from \"normal objects\".\n\nEverytime a pointer is involved in some \"type casting operation\" in Zig, the `@ptrCast()` function is used.\nThis function works similarly to `@floatFromInt()`.\nYou just provide the pointer object that you want to cast as input to this function, and the\ntarget data type is, once again, determined by the type annotation of the object where the results are being\nstored.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file2ed324328e1f.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## Modules\n\nWe already talked about what modules are, and also, how to import other modules into\nyour current module via *import statements*. Every Zig module (i.e. a `.zig` file) that you write in your project\nis internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the\nZig Standard Library into our current module.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n```\n:::\n\n\n\n\nWhen we want to access the functions and objects from the standard library, we\nare basically accessing the data members of the struct stored in the `std`\nobject. That is why we use the same syntax that we use in normal structs, with the dot operator (`.`)\nto access the data members and methods of the struct.\n\nWhen this \"import statement\" get's executed, the result of this expression is a struct\nobject that contains the Zig Standard Library modules, global variables, functions, etc.\nAnd this struct object get's saved (or stored) inside the constant object named `std`.\n\n\nTake the [`thread_pool.zig` module from the project `zap`](https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig)[^thread]\nas an example. This module is written as if it was\na big struct. That is why we have a top-level and public `init()` method\nwritten in this module. The idea is that all top-level functions written in this\nmodule are methods from the struct, and all top-level objects and struct declarations\nare data members of this struct. The module is the struct itself.\n\n[^thread]: <https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig>\n\n\nSo you would import and use this module by doing something like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst ThreadPool = @import(\"thread_pool.zig\");\nconst num_cpus = std.Thread.getCpuCount()\n    catch @panic(\"failed to get cpu core count\");\nconst num_threads = std.math.cast(u16, num_cpus)\n    catch std.math.maxInt(u16);\nconst pool = ThreadPool.init(\n    .{ .max_threads = num_threads }\n);\n```\n:::\n",
     "supporting": [
       "03-structs_files"
     ],
diff --git a/_freeze/index/execute-results/html.json b/_freeze/index/execute-results/html.json
index 45e16fd5..2f1af68f 100644
--- a/_freeze/index/execute-results/html.json
+++ b/_freeze/index/execute-results/html.json
@@ -2,7 +2,7 @@
   "hash": "7eedbe34469c0f2c200651bc420da095",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy an eBook or a physical copy\nof the book on Amazon:\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e. it is open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.\nCurrently, he is a Data Platform Engineer at [Blip](https://www.blip.ai/en/)[^blip], and\na Databricks Certified Associate Developer for Apache Spark 3.0.\n\n[^blip]: <https://www.blip.ai/en/>\n\n\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nBrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer who loves to learn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2024 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n\n\n- System version: Linux, 6.8.0-52-generic, NA, x86_64.\n- Zig version: 0.14.0-dev.2371+c013f45ad.\n- Quarto version: 1.5.57.\n\n\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang), Tommaso Ricci (\\@Zorgatone), Primo Sabatini (\\@primos63), Santiago Fernandez (\\@santif), Hamza Wahed (\\@HamzaWahed), mwilbur (\\@mwilbur)\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy an eBook or a physical copy\nof the book on Amazon:\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e. it is open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.\nCurrently, he is a Data Platform Engineer at [Blip](https://www.blip.ai/en/)[^blip], and\na Databricks Certified Associate Developer for Apache Spark 3.0.\n\n[^blip]: <https://www.blip.ai/en/>\n\n\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nBrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer who loves to learn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2024 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n\n- System version: Linux, 6.8.0-52-generic, NA, x86_64.\n- Zig version: 0.14.0-dev.3046+08d661fcf.\n- Quarto version: 1.5.57.\n\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang), Tommaso Ricci (\\@Zorgatone), Primo Sabatini (\\@primos63), Santiago Fernandez (\\@santif), Hamza Wahed (\\@HamzaWahed), mwilbur (\\@mwilbur), Dima Budaragin (\\@dbud), Jorge Jímenez (\\@jorge-j1m)\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
diff --git a/contributors.txt b/contributors.txt
index 6bcf75bc..1c2abddf 100644
--- a/contributors.txt
+++ b/contributors.txt
@@ -17,3 +17,5 @@ Primo Sabatini,@primos63
 Santiago Fernandez,@santif
 Hamza Wahed,@HamzaWahed
 mwilbur,@mwilbur
+Dima Budaragin,@dbud
+Jorge Jímenez,@jorge-j1m
diff --git a/docs/Chapters/01-memory.html b/docs/Chapters/01-memory.html
index 0e748f6f..12fad0b6 100644
--- a/docs/Chapters/01-memory.html
+++ b/docs/Chapters/01-memory.html
@@ -380,7 +380,7 @@ <h3 data-number="3.1.1" class="anchored" data-anchor-id="sec-compile-time"><span
 </div>
 <p>The other side of the spectrum are objects whose values are not known at compile time. Function arguments are a classic example of this. Because the value of each function argument depends on the value that you assign to this particular argument, when you call the function.</p>
 <p>For example, the function <code>input_length()</code> contains an argument named <code>input</code>, which is an array of constant <code>u8</code> integers (<code>[]const u8</code>). It is impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length of this particular argument. Because it is an array that do not have a fixed size specified explicitly in the argument type annotation.</p>
-<p>So, we know that this <code>input</code> argument will be an array of <code>u8</code> integers. But we do not know at compile-time, its value, and neither his size. This information is known only at runtime, which is the period of time when you program is executed. As a consequence, the value of the expression <code>input.len</code> is also known only at runtime. This is an intrinsic characteristic of any function. Just remember that the value of function arguments is usually not “compile-time known”.</p>
+<p>So, we know that this <code>input</code> argument will be an array of <code>u8</code> integers. But we do not know at compile-time, its value, and neither its size. This information is known only at runtime, which is the period of time when you program is executed. As a consequence, the value of the expression <code>input.len</code> is also known only at runtime. This is an intrinsic characteristic of any function. Just remember that the value of function arguments is usually not “compile-time known”.</p>
 <p>However, as I mentioned earlier, what really matters to the compiler is to know the size of the object at compile-time, and not necessarily its value. So, although we don’t know the value of the object <code>n</code>, which is the result of the expression <code>input.len</code>, at compile-time, we do know its size. Because the expression <code>input.len</code> always returns a value of type <code>usize</code>, and the type <code>usize</code> has a known fixed size.</p>
 </section>
 <section id="global-data-register" class="level3" data-number="3.1.2">
@@ -391,7 +391,7 @@ <h3 data-number="3.1.2" class="anchored" data-anchor-id="global-data-register"><
 </section>
 <section id="stack-vs-heap" class="level3" data-number="3.1.3">
 <h3 data-number="3.1.3" class="anchored" data-anchor-id="stack-vs-heap"><span class="header-section-number">3.1.3</span> Stack vs Heap</h3>
-<p>If you are familiar with system’s programming, or just low-level programming in general, you probably have heard of the “duel” between Stack vs Heap. These are two different types of memory, or different memory spaces, which are both available in Zig.</p>
+<p>If you are familiar with systems programming, or just low-level programming in general, you probably have heard of the “duel” between Stack vs Heap. These are two different types of memory, or different memory spaces, which are both available in Zig.</p>
 <p>These two types of memory don’t actually duel with each other. This is a common mistake that beginners have, when seeing “x vs y” styles of tabloid headlines. These two types of memory are actually complementary to each other. So, in almost every Zig program that you ever write, you will likely use a combination of both. I will describe each memory space in detail over the next sections. But for now, I just want to stablish the main difference between these two types of memory.</p>
 <p>In essence, the stack memory is normally used to store values whose length is fixed and known at compile time. In contrast, the heap memory is a <em>dynamic</em> type of memory space, meaning that, it is used to store values whose length might grow during the execution (runtime) of your program <span class="citation" data-cites="jenny2022">(<a href="../references.html#ref-jenny2022" role="doc-biblioref">Chen and Guo 2022</a>)</span>.</p>
 <p>Lengths that grow during runtime are intrinsically associated with “runtime known” type of values. In other words, if you have an object whose length might grow during runtime, then, the length of this object becomes not known at compile time. If the length is not known at compile-time, the value of this object also becomes not known at compile-time. These types of objects should be stored in the heap memory space, which is a dynamic memory space, which can grow or shrink to fit the size of your objects.</p>
@@ -429,7 +429,7 @@ <h3 data-number="3.1.4" class="anchored" data-anchor-id="sec-stack"><span class=
 <p>Local objects that are stored in the stack space of a function are automatically freed/destroyed at the end of the function scope.</p>
 </div>
 </div>
-<p>This same logic applies to any other special structure in Zig that have its own scope by surrounding it with curly braces (<code>{}</code>). For loops, while loops, if else statements, etc. For example, if you declare any local object in the scope of a for loop, this local object is accessible only within the scope of this particular for loop. Because once the scope of this for loop ends, the space in the stack reserved for this for loop is freed. The example below demonstrates this idea.</p>
+<p>This same logic applies to any other special structure in Zig that has its own scope by surrounding it with curly braces (<code>{}</code>). For loops, while loops, if else statements, etc. For example, if you declare any local object in the scope of a for loop, this local object is accessible only within the scope of this particular for loop. Because once the scope of this for loop ends, the space in the stack reserved for this for loop is freed. The example below demonstrates this idea.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb3"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="co">// This does not compile successfully!</span></span>
 <span id="cb3-2"><a href="#cb3-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> a = [_]<span class="dt">u8</span><span class="op">{</span><span class="dv">0</span>, <span class="dv">1</span>, <span class="dv">2</span>, <span class="dv">3</span>, <span class="dv">4</span><span class="op">}</span>;</span>
@@ -460,7 +460,7 @@ <h3 data-number="3.1.4" class="anchored" data-anchor-id="sec-stack"><span class=
 <span id="cb4-10"><a href="#cb4-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> r = add(<span class="dv">5</span>, <span class="dv">27</span>); _ = r;</span>
 <span id="cb4-11"><a href="#cb4-11" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>This “invalid pointer to stack variable” problem is very known across many programming language communities. If you try to do the same thing, for example, in a C or C++ program (i.e.&nbsp;returning an address to a local object stored in the stack), you would also get undefined behaviour in the program.</p>
+<p>This “invalid pointer to stack variable” problem is well known across many programming language communities. If you try to do the same thing, for example, in a C or C++ program (i.e.&nbsp;returning an address to a local object stored in the stack), you would also get undefined behaviour in the program.</p>
 <div class="callout callout-style-default callout-important callout-titled">
 <div class="callout-header d-flex align-content-center">
 <div class="callout-icon-container">
@@ -474,13 +474,13 @@ <h3 data-number="3.1.4" class="anchored" data-anchor-id="sec-stack"><span class=
 <p>If a local object in your function is stored in the stack, you should never return a pointer to this local object from the function. Because this pointer will always become undefined after the function returns, since the stack space of the function is destroyed at the end of its scope.</p>
 </div>
 </div>
-<p>But what if you really need to use this local object in some way after your function returns? How can you do this? The answer is: “in the same you would do if this was a C or C++ program. By returning an address to an object stored in the heap”. The heap memory has a much more flexible lifecycle, and allows you to get a valid pointer to a local object of a function that already returned from its scope.</p>
+<p>But what if you really need to use this local object in some way after your function returns? How can you do this? The answer is: “in the same way you would do if this were a C or C++ program. By returning an address to an object stored in the heap”. The heap memory has a much more flexible lifecycle, and allows you to get a valid pointer to a local object of a function that already returned from its scope.</p>
 </section>
 <section id="sec-heap" class="level3" data-number="3.1.5">
 <h3 data-number="3.1.5" class="anchored" data-anchor-id="sec-heap"><span class="header-section-number">3.1.5</span> Heap</h3>
 <p>One important limitation of the stack, is that, only objects whose length/size is known at compile-time can be stored in it. In contrast, the heap is a much more dynamic (and flexible) type of memory. It is the perfect type of memory to use for objects whose size/length might grow during the execution of your program.</p>
 <p>Virtually any application that behaves as a server is a classic use case of the heap. A HTTP server, a SSH server, a DNS server, a LSP server, … any type of server. In summary, a server is a type of application that runs for long periods of time, and that serves (or “deals with”) any incoming request that reaches this particular server.</p>
-<p>The heap is a good choice for this type of system, mainly because the server does not know upfront how many requests it will receive from users, while it is active. It could be one single request, or, 5 thousand requests, or, it could also be zero requests. The server needs to have the ability to allocate and manage its memory according to how many requests it receives.</p>
+<p>The heap is a good choice for this type of system, mainly because the server does not know upfront how many requests it will receive from users, while it is active. It could be a single request, 5 thousand requests, or even zero requests. The server needs to have the ability to allocate and manage its memory according to how many requests it receives.</p>
 <p>Another key difference between the stack and the heap, is that the heap is a type of memory that you, the programmer, have complete control over. This makes the heap a more flexible type of memory, but it also makes it harder to work with. Because you, the programmer, is responsible for managing everything related to it. Including where the memory is allocated, how much memory is allocated, and where this memory is freed.</p>
 <blockquote class="blockquote">
 <p>Unlike stack memory, heap memory is allocated explicitly by programmers and it won’t be deallocated until it is explicitly freed <span class="citation" data-cites="jenny2022">(<a href="../references.html#ref-jenny2022" role="doc-biblioref">Chen and Guo 2022</a>)</span>.</p>
@@ -509,7 +509,7 @@ <h3 data-number="3.1.6" class="anchored" data-anchor-id="summary"><span class="h
 <li>every constant object (<code>const</code>) whose value <strong>is known at compile-time</strong> is also stored in the global data section.</li>
 <li>every object (constant or not) whose length/size <strong>is known at compile time</strong> is stored in the stack space for the current scope.</li>
 <li>if an object is created with the method <code>alloc()</code> or <code>create()</code> of an allocator object, this object is stored in the memory space used by this particular allocator object. Most of allocators available in Zig use the heap memory, so, this object is likely stored in the heap (<code>FixedBufferAllocator()</code> is an exception to that).</li>
-<li>the heap can only be accessed through allocators. If your object was not created through the <code>alloc()</code> or <code>create()</code> methods of an allocator object, then, he is most certainly not an object stored in the heap.</li>
+<li>the heap can only be accessed through allocators. If your object was not created through the <code>alloc()</code> or <code>create()</code> methods of an allocator object, then, it is most certainly not an object stored in the heap.</li>
 </ol>
 </section>
 </section>
@@ -518,8 +518,8 @@ <h2 data-number="3.2" class="anchored" data-anchor-id="sec-stack-overflow"><span
 <p>Allocating memory on the stack is generally faster than allocating it on the heap. But this better performance comes with many restrictions. We have already discussed many of these restrictions of the stack at <a href="#sec-stack" class="quarto-xref"><span>Section 3.1.4</span></a>. But there is one more important limitation that I want to talk about, which is the size of the stack itself.</p>
 <p>The stack is limited in size. This size varies from computer to computer, and it depends on a lot of things (the computer architecture, the operating system, etc.). Nevertheless, this size is usually not that big. This is why we normally use the stack to store only temporary and small objects in memory.</p>
 <p>In essence, if you try to make an allocation on the stack, that is so big that exceeds the stack size limit, a <em>stack overflow</em> happens, and your program just crashes as a result of that. In other words, a stack overflow happens when you attempt to use more space than is available on the stack.</p>
-<p>This type of problem is very similar to a <em>buffer overflow</em>, i.e.&nbsp;you are trying to use more space than is available in the “buffer object”. However, a stack overflow always cause your program to crash, while a buffer overflow not always cause your program to crash (although it often does).</p>
-<p>You can see an example of a stack overflow in the example below. We are trying to allocate a very big array of <code>u64</code> values on the stack. You can see below that this program does not run succesfully, because it crashed with a “segmentation fault” error message.</p>
+<p>This type of problem is very similar to a <em>buffer overflow</em>, i.e.&nbsp;you are trying to use more space than is available in the “buffer object”. However, a stack overflow always causes your program to crash, while a buffer overflow does not always cause your program to crash (although it often does).</p>
+<p>You can see an example of a stack overflow in the example below. We are trying to allocate a very big array of <code>u64</code> values on the stack. You can see below that this program does not run successfully, because it crashed with a “segmentation fault” error message.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb5"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> very_big_alloc: [<span class="dv">1000</span> * <span class="dv">1000</span> * <span class="dv">24</span>]<span class="dt">u64</span> = <span class="cn">undefined</span>;</span>
 <span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a><span class="bu">@memset</span>(very_big_alloc[<span class="dv">0</span>..], <span class="dv">0</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
@@ -533,7 +533,7 @@ <h2 data-number="3.3" class="anchored" data-anchor-id="sec-allocators"><span cla
 <p>This is a known problem, especially in C++. Because in C++, there are some operators that do allocate memory behind the scene, and there is no way for you to know that, until you actually read the source code of these operators, and find the memory allocation calls. Many programmers find this behaviour annoying and hard to keep track of.</p>
 <p>But, in Zig, if a function, an operator, or anything from the standard library needs to allocate some memory during its execution, then, this function/operator needs to receive (as input) an allocator provided by the user, to actually be able to allocate the memory it needs.</p>
 <p>This creates a clear distinction between functions that “do not” from those that “actually do” allocate memory. Just look at the arguments of this function. If a function, or operator, has an allocator object as one of its inputs/arguments, then, you know for sure that this function/operator will allocate some memory during its execution.</p>
-<p>An example is the <code>allocPrint()</code> function from the Zig Standard Library. With this function, you can write a new string using format specifiers. So, this function is, for example, very similar to the function <code>sprintf()</code> in C. In order to write such new string, the <code>allocPrint()</code> function needs to allocate some memory to store the output string.</p>
+<p>An example is the <code>allocPrint()</code> function from the Zig Standard Library. With this function, you can write a new string using format specifiers. So, this function is, for example, very similar to the function <code>sprintf()</code> in C. In order to write such a new string, the <code>allocPrint()</code> function needs to allocate some memory to store the output string.</p>
 <p>That is why, the first argument of this function is an allocator object that you, the user/programmer, gives as input to the function. In the example below, I am using the <code>GeneralPurposeAllocator()</code> as my allocator object. But I could easily use any other type of allocator object from the Zig Standard Library.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb7"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> gpa = std.heap.GeneralPurposeAllocator(.<span class="op">{}</span>)<span class="op">{}</span>;</span>
@@ -558,14 +558,14 @@ <h3 data-number="3.3.1" class="anchored" data-anchor-id="what-are-allocators"><s
 </section>
 <section id="why-you-need-an-allocator" class="level3" data-number="3.3.2">
 <h3 data-number="3.3.2" class="anchored" data-anchor-id="why-you-need-an-allocator"><span class="header-section-number">3.3.2</span> Why you need an allocator?</h3>
-<p>As we described at <a href="#sec-stack" class="quarto-xref"><span>Section 3.1.4</span></a>, everytime you make a function call in Zig, a space in the stack is reserved for this function call. But the stack has a key limitation which is: every object stored in the stack have a known fixed length.</p>
+<p>As we described at <a href="#sec-stack" class="quarto-xref"><span>Section 3.1.4</span></a>, everytime you make a function call in Zig, a space in the stack is reserved for this function call. But the stack has a key limitation which is: every object stored in the stack has a known fixed length.</p>
 <p>But in reality, there are two very common instances where this “fixed length limitation” of the stack is a deal braker:</p>
 <ol type="1">
 <li>the objects that you create inside your function might grow in size during the execution of the function.</li>
 <li>sometimes, it is impossible to know upfront how many inputs you will receive, or how big this input will be.</li>
 </ol>
 <p>Also, there is another instance where you might want to use an allocator, which is when you want to write a function that returns a pointer to a local object. As I described at <a href="#sec-stack" class="quarto-xref"><span>Section 3.1.4</span></a>, you cannot do that if this local object is stored in the stack. However, if this object is stored in the heap, then, you can return a pointer to this object at the end of the function. Because you (the programmer) control the lifetime of any heap memory that you allocate. You decide when this memory gets destroyed/freed.</p>
-<p>These are common situations where the stack is not good for. That is why you need a different memory management strategy to store these objects inside your function. You need to use a memory type that can grow together with your objects, or that you can control the lifetime of this memory. The heap fits this description.</p>
+<p>These are common situations for which the stack is not good. That is why you need a different memory management strategy to store these objects inside your function. You need to use a memory type that can grow together with your objects, or that you can control the lifetime of this memory. The heap fits this description.</p>
 <p>Allocating memory on the heap is commonly known as dynamic memory management. As the objects you create grow in size during the execution of your program, you grow the amount of memory you have by allocating more memory in the heap to store these objects. And you do that in Zig, by using an allocator object.</p>
 </section>
 <section id="the-different-types-of-allocators" class="level3" data-number="3.3.3">
@@ -688,7 +688,7 @@ <h3 data-number="3.3.9" class="anchored" data-anchor-id="the-create-and-destroy-
 <p>With the <code>alloc()</code> and <code>free()</code> methods, you can allocate memory to store multiple elements at once. In other words, with these methods, we always allocate an array to store multiple elements at once. But what if you need enough space to store just a single item? Should you allocate an array of a single element through <code>alloc()</code>?</p>
 <p>The answer is no! In this case, you should use the <code>create()</code> method of the allocator object. Every allocator object offers the <code>create()</code> and <code>destroy()</code> methods, which are used to allocate and free memory for a single item, respectively.</p>
 <p>So, in essence, if you want to allocate memory to store an array of elements, you should use <code>alloc()</code> and <code>free()</code>. But if you need to store just a single item, then, the <code>create()</code> and <code>destroy()</code> methods are ideal for you.</p>
-<p>In the example below, I’m defining a struct to represent an user of some sort. It could be an user for a game, or a software to manage resources, it doesn’t mater. Notice that I use the <code>create()</code> method this time, to store a single <code>User</code> object in the program. Also notice that I use the <code>destroy()</code> method to free the memory used by this object at the end of the scope.</p>
+<p>In the example below, I’m defining a struct to represent an user of some sort. It could be a user for a game, or software to manage resources, it doesn’t mater. Notice that I use the <code>create()</code> method this time, to store a single <code>User</code> object in the program. Also notice that I use the <code>destroy()</code> method to free the memory used by this object at the end of the scope.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb14"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb14-2"><a href="#cb14-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> User = <span class="kw">struct</span> <span class="op">{</span></span>
diff --git a/docs/Chapters/02-debugging.html b/docs/Chapters/02-debugging.html
index d6ff110e..c79707b7 100644
--- a/docs/Chapters/02-debugging.html
+++ b/docs/Chapters/02-debugging.html
@@ -317,7 +317,7 @@ <h2 data-number="5.1" class="anchored" data-anchor-id="print-debugging"><span cl
 <p>That is the essence of <em>print debugging</em>. Is to use print expressions to see the values that are being generated by your program, and, as a result, get a much better understanding of how your program is behaving.</p>
 <p>Many programmers often resort to the print functions in Zig, such as the <code>stdout.print()</code>, or, the <code>std.debug.print()</code>, to get a better understanding of their programs. This is a known and old strategy that is very simple and effective, and it is better known within the programming community as <em>print debugging</em>. In Zig, you can print information to the <code>stdout</code> or <code>stderr</code> streams of your system.</p>
 <p>Let’s begin with <code>stdout</code>. First, you need to get access to the <code>stdout</code>, by calling the <code>getStdOut()</code> method, from the Zig Standard Library. This method returns a <em>file descriptor</em> object, and, through this object you can read/write to the <code>stdout</code>. I recommend you to check out all methods available in this object, by <a href="https://ziglang.org/documentation/master/std/#std.fs.File">checking the page in the Zig Standard Library Official Reference for the type <code>File</code></a><a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>.</p>
-<p>For our purpose here, which is to write something to the <code>stdout</code>, especially to debug our program, I recommend you to use the <code>writer()</code> method, which gives your a <em>writer</em> object. This <em>writer</em> object offers some helper methods to write stuff into the file descriptor object that represents the <code>stdout</code> stream. In special, the <code>print()</code> method.</p>
+<p>For our purpose here, which is to write something to the <code>stdout</code>, especially to debug our program, I recommend you to use the <code>writer()</code> method, which gives you a <em>writer</em> object. This <em>writer</em> object offers some helper methods to write stuff into the file descriptor object that represents the <code>stdout</code> stream. In special, the <code>print()</code> method.</p>
 <p>The <code>print()</code> method from this <em>writer</em> object is a “print formatter” type of a function. In other words, this method works exactly like the <code>printf()</code> function from C, or, like <code>println!()</code> from Rust. In the first argument of the function, you specify a template string, and, in the second argument, you provide a list of values (or objects) that you want to insert into your template message.</p>
 <p>Ideally, the template string in the first argument should contain some format specifier. Each format specifier is matched to a value (or object) that you have listed in the second argument. So, if you provided 5 different objects in the second argument, then, the template string should contain 5 format specifiers, one for each object provided.</p>
 <p>Each format specifier is represented by a single letter, and you provide this format specifier inside a pair of curly braces. So, if you want to format your object using the string specifier (<code>s</code>), then, you can insert the text <code>{s}</code> in your template string. Here is a quick list of the most used format specifiers:</p>
@@ -345,7 +345,7 @@ <h2 data-number="5.1" class="anchored" data-anchor-id="print-debugging"><span cl
 <pre><code>Result: 50</code></pre>
 </div>
 </div>
-<p>Is important to emphasize that, the <code>stdout.print()</code> method, as you would expect, print your template string into the <code>stdout</code> stream of your system. However, you can also print your template string into the <code>stderr</code> stream if your prefer. All you need to do, is to replace the <code>stdout.print()</code> call with the function <code>std.debug.print()</code>. Like this:</p>
+<p>It is important to emphasize that, the <code>stdout.print()</code> method, as you would expect, prints your template string into the <code>stdout</code> stream of your system. However, you can also print your template string into the <code>stderr</code> stream if your prefer. All you need to do, is to replace the <code>stdout.print()</code> call with the function <code>std.debug.print()</code>. Like this:</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb3"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb3-2"><a href="#cb3-2" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> add(x: <span class="dt">u8</span>, y: <span class="dt">u8</span>) <span class="dt">u8</span> <span class="op">{</span></span>
@@ -370,7 +370,7 @@ <h2 data-number="5.1" class="anchored" data-anchor-id="print-debugging"><span cl
 </section>
 <section id="debugging-through-debuggers" class="level2" data-number="5.2">
 <h2 data-number="5.2" class="anchored" data-anchor-id="debugging-through-debuggers"><span class="header-section-number">5.2</span> Debugging through debuggers</h2>
-<p>Although <em>print debugging</em> being a valid and very useful strategy, most programmers prefer to use a debugger to debug their programs. Since Zig is a low-level language, you can use either GDB (GNU Debugger), or LLDB (LLVM Project Debugger) as your debugger.</p>
+<p>Although <em>print debugging</em> is a valid and very useful strategy, most programmers prefer to use a debugger to debug their programs. Since Zig is a low-level language, you can use either GDB (GNU Debugger), or LLDB (LLVM Project Debugger) as your debugger.</p>
 <p>Both debuggers can work with Zig code, and it’s a matter of taste here. You choose the debugger of your preference, and you work with it. In this book, I will use LLDB as my debugger on the examples.</p>
 <section id="sec-compile-debug-mode" class="level3" data-number="5.2.1">
 <h3 data-number="5.2.1" class="anchored" data-anchor-id="sec-compile-debug-mode"><span class="header-section-number">5.2.1</span> Compile your source code in debug mode</h3>
@@ -424,7 +424,7 @@ <h3 data-number="5.2.2" class="anchored" data-anchor-id="lets-debug-a-program"><
 <p>I can start navigating through the code, and checking the objects that are being generated. If you are not familiar with the commands available in LLDB, I recommend you to read the official documentation of the project<a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a>. You can also look for cheat sheets, which quickly describes all commands available for you<a href="#fn4" class="footnote-ref" id="fnref4" role="doc-noteref"><sup>4</sup></a>.</p>
 <p>Currently, we are in the first line at the <code>main()</code> function. In this line, we create the <code>n</code> object, by executing the <code>add_and_increment()</code> function. To execute the current line of code, and go to the next line, we can run the <code>n</code> LLDB command. Let’s execute this command.</p>
 <p>After we executed this line, we can also look at the value stored inside this <code>n</code> object by using the <code>p</code> LLDB command. The syntax for this command is <code>p &lt;name-of-object&gt;</code>.</p>
-<p>If we take a look at the value stored in the <code>n</code> object (<code>p n</code>), notice that it stores the hexadecimal value <code>0x06</code>, which is the number 6 in decimal. We can also see that, this value have a type <code>unsigned char</code>, which is an unsigned 8-bit integer. We have talked already about this at <a href="01-zig-weird.html#sec-zig-strings" class="quarto-xref"><span>Section 1.8</span></a>, that <code>u8</code> integers in Zig are equivalent to the C data type <code>unsigned char</code>.</p>
+<p>If we take a look at the value stored in the <code>n</code> object (<code>p n</code>), notice that it stores the hexadecimal value <code>0x06</code>, which is the number 6 in decimal. We can also see that this value has a type of <code>unsigned char</code>, which is an unsigned 8-bit integer. We have talked already about this at <a href="01-zig-weird.html#sec-zig-strings" class="quarto-xref"><span>Section 1.8</span></a>, that <code>u8</code> integers in Zig are equivalent to the C data type <code>unsigned char</code>.</p>
 <div class="sourceCode" id="cb11"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">n</span></span>
 <span id="cb11-2"><a href="#cb11-2" aria-hidden="true" tabindex="-1"></a><span class="ex">Process</span> 4798 stopped</span>
 <span id="cb11-3"><a href="#cb11-3" aria-hidden="true" tabindex="-1"></a><span class="ex">*</span> thread <span class="co">#1, name = 'debugging',</span></span>
diff --git a/docs/Chapters/03-structs.html b/docs/Chapters/03-structs.html
index bcf6dd8f..69a800e7 100644
--- a/docs/Chapters/03-structs.html
+++ b/docs/Chapters/03-structs.html
@@ -497,7 +497,7 @@ <h3 data-number="2.1.3" class="anchored" data-anchor-id="sec-defer"><span class=
 Multiplying ...
 Exiting function ...</code></pre>
 <p>Therefore, we can use <code>defer</code> to declare an expression that is going to be executed when your code exits the current scope. Some programmers like to interpret the phrase “exit of the current scope” as “the end of the current scope”. But this interpretation might not be entirely correct, depending on what you consider as “the end of the current scope”.</p>
-<p>I mean, what do you consider as <strong>the end</strong> of the current scope? Is it the closing curly bracket (<code>}</code>) of the scope? Is it when the last expression in the function get’s executed? Is it when the function returns to the previous scope? Etc. For example, it would not be correct to interpret the “exit of the current scope” as the closing curly bracket of the scope. Because the function might exit from an earlier position than this closing curly bracket (e.g.&nbsp;an error value was generated at a previous line inside the function; the function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.</p>
+<p>I mean, what do you consider as <strong>the end</strong> of the current scope? Is it the closing curly bracket (<code>}</code>) of the scope? Is it when the last expression in the function gets executed? Is it when the function returns to the previous scope? Etc. For example, it would not be correct to interpret the “exit of the current scope” as the closing curly bracket of the scope. Because the function might exit from an earlier position than this closing curly bracket (e.g.&nbsp;an error value was generated at a previous line inside the function; the function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.</p>
 <p>Now, if you remember of what we have discussed in <a href="01-zig-weird.html#sec-blocks" class="quarto-xref"><span>Section 1.7</span></a>, there are multiple structures in the language that create their own separate scopes. For/while loops, if/else statements, functions, normal blocks, etc. This also affects the interpretation of <code>defer</code>. For example, if you use <code>defer</code> inside a for loop, then, the given expression will be executed everytime this specific for loop exits its own scope.</p>
 <p>Before we continue, is worth emphasizing that the <code>defer</code> keyword is an “unconditional defer”. Which means that the given expression will be executed no matter how the code exits the current scope. For example, your code might exit the current scope because of an error value being generated, or, because of a return statement, or, a break statement, etc.</p>
 </section>
@@ -809,7 +809,7 @@ <h3 data-number="2.3.4" class="anchored" data-anchor-id="about-the-struct-state"
 <p>Sometimes you don’t need to care about the state of your struct object. Sometimes, you just need to instantiate and use the objects, without altering their state. You can notice that when you have methods inside your struct declaration that might use the values that are present in the data members, but they do not alter the values in these data members of the struct in anyway.</p>
 <p>The <code>Vec3</code> struct that was presented in <a href="#sec-self-arg" class="quarto-xref"><span>Section 2.3.3</span></a> is an example of that. This struct have a single method named <code>distance()</code>, and this method does use the values present in all three data members of the struct (<code>x</code>, <code>y</code> and <code>z</code>). But at the same time, this method does not change the values of these data members at any point.</p>
 <p>As a result of that, when we create <code>Vec3</code> objects we usually create them as constant objects, like the <code>v1</code> and <code>v2</code> objects presented in <a href="#sec-self-arg" class="quarto-xref"><span>Section 2.3.3</span></a>. We can create them as variable objects with the <code>var</code> keyword, if we want to. But because the methods of this <code>Vec3</code> struct do not change the state of the objects in any point, it’s unnecessary to mark them as variable objects.</p>
-<p>But why? Why am I talking about this here? It’s because the <code>self</code> argument in the methods is affected depending on whether the methods present in a struct change or don’t change the state of the object itself. More specifically, when you have a method in a struct that changes the state of the object (i.e.&nbsp;change the value of a data member), the <code>self</code> argument in this method must be annotated in a different manner.</p>
+<p>But why? Why am I talking about this here? It’s because the <code>self</code> argument in the methods are affected depending on whether the methods present in a struct change or don’t change the state of the object itself. More specifically, when you have a method in a struct that changes the state of the object (i.e.&nbsp;changes the value of a data member), the <code>self</code> argument in this method must be annotated in a different manner.</p>
 <p>As I described in <a href="#sec-self-arg" class="quarto-xref"><span>Section 2.3.3</span></a>, the <code>self</code> argument in methods of a struct is the argument that receives as input the object from which the method was called from. We usually annotate this argument in the methods by writing <code>self</code>, followed by the colon character (<code>:</code>), and the data type of the struct to which the method belongs to (e.g.&nbsp;<code>User</code>, <code>Vec3</code>, etc.).</p>
 <p>If we take the <code>Vec3</code> struct that we defined in the previous section as an example, we can see in the <code>distance()</code> method that this <code>self</code> argument is annotated as <code>self: Vec3</code>. Because the state of the <code>Vec3</code> object is never altered by this method.</p>
 <p>But what if we do have a method that alters the state of the object, by altering the values of its data members, how should we annotate <code>self</code> in this instance? The answer is: “we should annotate <code>self</code> as a pointer of <code>x</code>, instead of just <code>x</code>”. In other words, you should annotate <code>self</code> as <code>self: *x</code>, instead of annotating it as <code>self: x</code>.</p>
@@ -877,7 +877,7 @@ <h3 data-number="2.3.4" class="anchored" data-anchor-id="about-the-struct-state"
 <h2 data-number="2.4" class="anchored" data-anchor-id="sec-type-inference"><span class="header-section-number">2.4</span> Type inference</h2>
 <p>Zig is a strongly typed language. But, there are some situations where you don’t have to explicitly write the type of every single object in your source code, as you would expect from a traditional strongly typed language, such as C and C++.</p>
 <p>In some situations, the <code>zig</code> compiler can use type inference to solve the data types for you, easing some of the burden that you carry as a developer. The most common way this happens is through function arguments that receive struct objects as input.</p>
-<p>In general, type inference in Zig is done by using the dot character (<code>.</code>). Everytime you see a dot character written before a struct literal, or before an enum value, or something like that, you know that this dot character is playing a special party in this place. More specifically, it is telling the <code>zig</code> compiler something along the lines of: “Hey! Can you infer the type of this value for me? Please!”. In other words, this dot character is playing a similar role as the <code>auto</code> keyword in C++.</p>
+<p>In general, type inference in Zig is done by using the dot character (<code>.</code>). Everytime you see a dot character written before a struct literal, or before an enum value, or something like that, you know that this dot character is playing a special part in this place. More specifically, it is telling the <code>zig</code> compiler something along the lines of: “Hey! Can you infer the type of this value for me? Please!”. In other words, this dot character is playing a similar role as the <code>auto</code> keyword in C++.</p>
 <p>I gave you some examples of this in <a href="#sec-anonymous-struct-literals" class="quarto-xref"><span>Section 2.3.1</span></a>, where we used anonymous struct literals. Anonymous struct literals are, struct literals that use type inference to infer the exact type of this particular struct literal. This type inference is done by looking for some minimal hint of the correct data type to be used. You could say that the <code>zig</code> compiler looks for any neighbouring type annotation that might tell it what the correct type would be.</p>
 <p>Another common place where we use type inference in Zig is at switch statements (which we talked about in <a href="#sec-switch" class="quarto-xref"><span>Section 2.1.2</span></a>). I also gave some other examples of type inference in <a href="#sec-switch" class="quarto-xref"><span>Section 2.1.2</span></a>, where we were inferring the data types of enum values listed inside of switch statements (e.g.&nbsp;<code>.DE</code>). But as another example, take a look at this <code>fence()</code> function reproduced below, which comes from the <a href="https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig"><code>atomic.zig</code> module</a><a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a> of the Zig Standard Library.</p>
 <p>There are a lot of things in this function that we haven’t talked about yet, such as: what <code>comptime</code> means? <code>inline</code>? <code>extern</code>? Let’s just ignore all of these things, and focus solely on the switch statement that is inside this function.</p>
@@ -927,8 +927,7 @@ <h2 data-number="2.5" class="anchored" data-anchor-id="sec-type-cast"><span clas
 <span id="cb49-6"><a href="#cb49-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(y) == <span class="dt">u32</span>);</span>
 <span id="cb49-7"><a href="#cb49-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 filecdc41797a754.test_0...OKAll 1 tests passed
-  d.</code></pre>
+<pre><code>1/1 file2ed34a8fc96.test_0...OKAll 1 tests passed.</code></pre>
 </div>
 </div>
 <p>This is the general way to perform type casting in Zig. But remember, <code>@as()</code> works only when casting is unambiguous and safe, and there are situations where these assumptions do not hold. For example, when casting an integer value into a float value, or vice-versa, it is not clear to the compiler how to perform this conversion safely.</p>
@@ -943,7 +942,7 @@ <h2 data-number="2.5" class="anchored" data-anchor-id="sec-type-cast"><span clas
 <span id="cb51-6"><a href="#cb51-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(y) == <span class="dt">f32</span>);</span>
 <span id="cb51-7"><a href="#cb51-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 filecdc428638149.test_0...OKAll 1 tests passed
+<pre><code>1/1 file2ed34bfb9fa5.test_0...OKAll 1 tests passed
   d.</code></pre>
 </div>
 </div>
@@ -960,7 +959,7 @@ <h2 data-number="2.5" class="anchored" data-anchor-id="sec-type-cast"><span clas
 <span id="cb53-8"><a href="#cb53-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(u32_ptr) == *<span class="kw">const</span> <span class="dt">u32</span>);</span>
 <span id="cb53-9"><a href="#cb53-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 filecdc46f71cc03.test_0...OKAll 1 tests passed
+<pre><code>1/1 file2ed324328e1f.test_0...OKAll 1 tests passed
   d.</code></pre>
 </div>
 </div>
diff --git a/docs/index.html b/docs/index.html
index bb4d7134..de82ec20 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -7,7 +7,7 @@
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 <meta name="author" content="Pedro Duarte Faria">
-<meta name="dcterms.date" content="2025-01-30">
+<meta name="dcterms.date" content="2025-02-09">
 
 <title>Introduction to Zig</title>
 <style>
@@ -287,7 +287,7 @@ <h1 class="title">Introduction to Zig</h1>
     <div>
     <div class="quarto-title-meta-heading">Published</div>
     <div class="quarto-title-meta-contents">
-      <p class="date">January 30, 2025</p>
+      <p class="date">February 9, 2025</p>
     </div>
   </div>
   
@@ -412,7 +412,7 @@ <h2 class="unnumbered anchored" data-anchor-id="book-compilation-metadata">Book
 <p>This book was compiled using the following versions of <a href="https://ziglang.org">Zig</a> and <a href="https://quarto.org">Quarto</a>:</p>
 <ul>
 <li>System version: Linux, 6.8.0-52-generic, NA, x86_64.</li>
-<li>Zig version: 0.14.0-dev.2371+c013f45ad.</li>
+<li>Zig version: 0.14.0-dev.3046+08d661fcf.</li>
 <li>Quarto version: 1.5.57.</li>
 </ul>
 </section>
@@ -439,7 +439,7 @@ <h2 class="unnumbered anchored" data-anchor-id="corresponding-author-and-maintai
 <section id="acknowledgments" class="level2 unnumbered">
 <h2 class="unnumbered anchored" data-anchor-id="acknowledgments">Acknowledgments</h2>
 <p>This book is also a product of many conversations and exchanges that we had with different people from the Zig community. I (Pedro Duarte Faria) am incredibly grateful for these conversations, and also, for some direct contributions that we had. Below we have a list of the people involved (name of the person with their usename in GitHub):</p>
-<p>Calin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang), Tommaso Ricci (@Zorgatone), Primo Sabatini (@primos63), Santiago Fernandez (@santif), Hamza Wahed (@HamzaWahed), mwilbur (@mwilbur)</p>
+<p>Calin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang), Tommaso Ricci (@Zorgatone), Primo Sabatini (@primos63), Santiago Fernandez (@santif), Hamza Wahed (@HamzaWahed), mwilbur (@mwilbur), Dima Budaragin (@dbud), Jorge Jímenez (@jorge-j1m)</p>
 
 
 </section>
diff --git a/docs/search.json b/docs/search.json
index 09d33825..79957177 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -54,7 +54,7 @@
     "href": "index.html#book-compilation-metadata",
     "title": "Introduction to Zig",
     "section": "Book compilation metadata",
-    "text": "Book compilation metadata\nThis book was compiled using the following versions of Zig and Quarto:\n\nSystem version: Linux, 6.8.0-52-generic, NA, x86_64.\nZig version: 0.14.0-dev.2371+c013f45ad.\nQuarto version: 1.5.57.",
+    "text": "Book compilation metadata\nThis book was compiled using the following versions of Zig and Quarto:\n\nSystem version: Linux, 6.8.0-52-generic, NA, x86_64.\nZig version: 0.14.0-dev.3046+08d661fcf.\nQuarto version: 1.5.57.",
     "crumbs": [
       "Welcome"
     ]
@@ -84,7 +84,7 @@
     "href": "index.html#acknowledgments",
     "title": "Introduction to Zig",
     "section": "Acknowledgments",
-    "text": "Acknowledgments\nThis book is also a product of many conversations and exchanges that we had with different people from the Zig community. I (Pedro Duarte Faria) am incredibly grateful for these conversations, and also, for some direct contributions that we had. Below we have a list of the people involved (name of the person with their usename in GitHub):\nCalin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang), Tommaso Ricci (@Zorgatone), Primo Sabatini (@primos63), Santiago Fernandez (@santif), Hamza Wahed (@HamzaWahed), mwilbur (@mwilbur)",
+    "text": "Acknowledgments\nThis book is also a product of many conversations and exchanges that we had with different people from the Zig community. I (Pedro Duarte Faria) am incredibly grateful for these conversations, and also, for some direct contributions that we had. Below we have a list of the people involved (name of the person with their usename in GitHub):\nCalin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang), Tommaso Ricci (@Zorgatone), Primo Sabatini (@primos63), Santiago Fernandez (@santif), Hamza Wahed (@HamzaWahed), mwilbur (@mwilbur), Dima Budaragin (@dbud), Jorge Jímenez (@jorge-j1m)",
     "crumbs": [
       "Welcome"
     ]
@@ -234,7 +234,7 @@
     "href": "Chapters/03-structs.html#sec-zig-control-flow",
     "title": "2  Control flow, structs, modules and types",
     "section": "",
-    "text": "2.1.1 If/else statements\nAn if/else statement performs a “conditional flow operation”. A conditional flow control (or choice control) allows you to execute or ignore a certain block of commands based on a logical condition. Many programmers and computer science professionals also use the term “branching” in this case. In essence, an if/else statement allow us to use the result of a logical test to decide whether or not to execute a given block of commands.\nIn Zig, we write if/else statements by using the keywords if and else. We start with the if keyword followed by a logical test inside a pair of parentheses, followed by a pair of curly braces which contains the lines of code to be executed in case the logical test returns the value true.\nAfter that, you can optionally add an else statement. To do that, just add the else keyword followed by a pair of curly braces, with the lines of code to executed in case the logical test defined at if returns false.\nIn the example below, we are testing if the object x contains a number that is greater than 10. Judging by the output printed to the console, we know that this logical test returned false. Because the output in the console is compatible with the line of code present in the else branch of the if/else statement.\n\nconst x = 5;\nif (x &gt; 10) {\n    try stdout.print(\n        \"x &gt; 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x &lt;= 10!\\n\", .{}\n    );\n}\n\nx &lt;= 10!\n\n\n\n\n2.1.2 Switch statements\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust. As you would expect, to write a switch statement in Zig we use the switch keyword. We provide the value that we want to “switch over” inside a pair of parentheses. Then, we list the possible combinations (or “branches”) inside a pair of curly braces.\nLet’s take a look at the code example below. You can see that I’m creating an enum type called Role. We talk more about enums in Section 7.6. But in summary, this Role type is listing different types of roles in a fictitious company, like SE for Software Engineer, DE for Data Engineer, PM for Product Manager, etc.\nNotice that we are using the value from the role object in the switch statement, to discover which exact area we need to store in the area variable object. Also notice that we are using type inference inside the switch statement, with the dot character, as we are going to describe in Section 2.4. This makes the zig compiler infer the correct data type of the values (PM, SE, etc.) for us.\nAlso notice that, we are grouping multiple values in the same branch of the switch statement. We just separate each possible value with a comma. For example, if role contains either DE or DA, the area variable would contain the value \"Data & Analytics\", instead of \"Platform\" or \"Sales\".\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO =&gt; {\n            area = \"Platform\";\n        },\n        .DE, .DA =&gt; {\n            area = \"Data & Analytics\";\n        },\n        .KS =&gt; {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n\nPlatform\n\n\n\n2.1.2.1 Switch statements must exhaust all possibilities\nOne very important aspect about switch statements in Zig is that they must exhaust all existing possibilities. In other words, all possible values that could be found inside the role object must be explicitly handled in this switch statement.\nSince the role object has type Role, the only possible values to be found inside this object are PM, SE, DPE, PO, DE, DA and KS. There are no other possible values to be stored in this role object. Thus, the switch statements must have a combination (branch) for each one of these values. This is what “exhaust all existing possibilities” means. The switch statement covers every possible case.\nTherefore, you cannot write a switch statement in Zig, and leave an edge case with no explicit action to be taken. This is a similar behaviour to switch statements in Rust, which also have to handle all possible cases.\n\n\n2.1.2.2 The else branch\nTake a look at the dump_hex_fallible() function below as an example. This function comes from the Zig Standard Library. More precisely, from the debug.zig module1. There are multiple lines in this function, but I omitted them to focus solely on the switch statement found in this function. Notice that this switch statement has four possible cases (i.e. four explicit branches). Also, notice that we used an else branch in this case.\nAn else branch in a switch statement works as the “default branch”. Whenever you have multiple cases in your switch statement where you want to apply the exact same action, you can use an else branch to do that.\n\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' =&gt; try writer.writeAll(\"␊\"),\n        '\\r' =&gt; try writer.writeAll(\"␍\"),\n        '\\t' =&gt; try writer.writeAll(\"␉\"),\n        else =&gt; try writer.writeByte('.'),\n    }\n}\n\nMany programmers would also use an else branch to handle a “not supported” case. That is, a case that cannot be properly handled by your code, or, just a case that should not be “fixed”. Therefore, you can use an else branch to panic (or raise an error) in your program to stop the current execution.\nTake the code example below. We can see that, we are handling the cases for the level object being either 1, 2, or 3. All other possible cases are not supported by default, and, as consequence, we raise a runtime error in such cases through the @panic() built-in function.\nAlso notice that, we are assigning the result of the switch statement to a new object called category. This is another thing that you can do with switch statements in Zig. If a branch outputs a value as result, you can store the result value of the switch statement into a new object.\n\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 =&gt; \"beginner\",\n    3 =&gt; \"professional\",\n    else =&gt; {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n\n\n2.1.2.3 Using ranges in switch\nFurthermore, you can also use ranges of values in switch statements. That is, you can create a branch in your switch statement that is used whenever the input value is within the specified range. These “range expressions” are created with the operator .... It is important to emphasize that the ranges created by this operator are inclusive on both ends.\nFor example, I could easily change the previous code example to support all levels between 0 and 100. Like this:\n\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 =&gt; \"beginner\",\n    26...75 =&gt; \"intermediary\",\n    76...100 =&gt; \"professional\",\n    else =&gt; {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n\nbeginner\n\n\nThis is neat, and it works with character ranges too. That is, I could simply write 'a'...'z', to match any character value that is a lowercase letter, and it would work fine.\n\n\n2.1.2.4 Labeled switch statements\nIn Section 1.7 we have talked about labeling blocks, and also, about using these labels to return a value from the block. Well, from version 0.14.0 and onwards of the zig compiler, you can also apply labels over switch statements, which makes it possible to almost implement a “C goto” like pattern.\nFor example, if you give the label xsw to a switch statement, you can use this label in conjunction with the continue keyword to go back to the beginning of the switch statement. In the example below, the execution goes back to the beginning of the switch statement two times, before ending at the 3 branch.\n\nxsw: switch (@as(u8, 1)) {\n    1 =&gt; {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 =&gt; continue :xsw 3,\n    3 =&gt; return,\n    4 =&gt; {},\n    else =&gt; {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n\n\n\n\n2.1.3 The defer keyword\nWith the defer keyword you can register an expression to be executed when you exit the current scope. Therefore, this keyword has a similar functionality as the on.exit() function from R. Take the foo() function below as an example. When we execute this foo() function, the expression that prints the message “Exiting function …” is getting executed only when the function exits its scope.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n\nAdding some numbers ...\nMultiplying ...\nExiting function ...\nTherefore, we can use defer to declare an expression that is going to be executed when your code exits the current scope. Some programmers like to interpret the phrase “exit of the current scope” as “the end of the current scope”. But this interpretation might not be entirely correct, depending on what you consider as “the end of the current scope”.\nI mean, what do you consider as the end of the current scope? Is it the closing curly bracket (}) of the scope? Is it when the last expression in the function get’s executed? Is it when the function returns to the previous scope? Etc. For example, it would not be correct to interpret the “exit of the current scope” as the closing curly bracket of the scope. Because the function might exit from an earlier position than this closing curly bracket (e.g. an error value was generated at a previous line inside the function; the function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\nNow, if you remember of what we have discussed in Section 1.7, there are multiple structures in the language that create their own separate scopes. For/while loops, if/else statements, functions, normal blocks, etc. This also affects the interpretation of defer. For example, if you use defer inside a for loop, then, the given expression will be executed everytime this specific for loop exits its own scope.\nBefore we continue, is worth emphasizing that the defer keyword is an “unconditional defer”. Which means that the given expression will be executed no matter how the code exits the current scope. For example, your code might exit the current scope because of an error value being generated, or, because of a return statement, or, a break statement, etc.\n\n\n2.1.4 The errdefer keyword\nOn the previous section, we have discussed the defer keyword, which you can use to register an expression to be executed at the exit of the current scope. But this keyword has a brother, which is the errdefer keyword. While defer is an “unconditional defer”, the errdefer keyword is a “conditional defer”. Which means that the given expression is executed only when you exit the current scope on a very specific circumstance.\nIn more details, the expression given to errdefer is executed only when an error occurs in the current scope. Therefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope in a normal situation, without errors, the expression given to errdefer is not executed.\nThis makes the errdefer keyword one of the many tools available in Zig for error handling. In this section, we are more concerned with the control flow aspects around errdefer. But we are going to discuss errdefer later as a error handling tool in Section 10.2.4.\nThe code example below demonstrates three things:\n\nthat defer is an “unconditional defer”, because the given expression get’s executed regardless of how the function foo() exits its own scope.\nthat errdefer is executed because the function foo() returned an error value.\nthat defer and errdefer expressions are executed in a LIFO (last in, first out) order.\n\n\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\nWhen I say that “defer expressions” are executed in a LIFO order, what I want to say is that the last defer or errdefer expressions in the code are the first ones to be executed. You could also interpret this as: “defer expressions” are executed from bottom to top, or, from last to first.\nTherefore, if I change the order of the defer and errdefer expressions, you will notice that the value of i that get’s printed to the console changes to 1. This doesn’t mean that the defer expression was not executed in this case. This actually means that the defer expression was executed only after the errdefer expression. The code example below demonstrates this:\n\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n\n\n2.1.5 For loops\nA loop allows you to execute the same lines of code multiple times, thus, creating a “repetition space” in the execution flow of your program. Loops are particularly useful when we want to replicate the same function (or the same set of commands) over different inputs.\nThere are different types of loops available in Zig. But the most essential of them all is probably the for loop. A for loop is used to apply the same piece of code over the elements of a slice, or, an array.\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from other languages. You start with the for keyword, then, you list the items that you want to iterate over inside a pair of parentheses. Then, inside of a pair of pipes (|) you should declare an identifier that will serve as your iterator, or, the “repetition index of the loop”.\n\nfor (items) |value| {\n    // code to execute\n}\n\nTherefore, instead of using a (value in items) syntax, in Zig, for loops use the syntax (items) |value|. In the example below, you can see that we are looping through the items of the array stored at the object name, and printing to the console the decimal representation of each character in this array.\nIf we wanted, we could also iterate through a slice (or a portion) of the array, instead of iterating through the entire array stored in the name object. Just use a range selector to select the section you want. For example, I could provide the expression name[0..3] to the for loop, to iterate just through the first 3 elements in the array.\n\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n\n80 | 101 | 100 | 114 | 111 | \n\n\nIn the above example we are using the value itself of each element in the array as our iterator. But there are many situations where we need to use an index instead of the actual values of the items.\nYou can do that by providing a second set of items to iterate over. More precisely, you provide the range selector 0.. to the for loop. So, yes, you can use two different iterators at the same time in a for loop in Zig.\nBut remember from Section 1.4 that, every object you create in Zig must be used in some way. So if you declare two iterators in your for loop, you must use both iterators inside the for loop body. But if you want to use just the index iterator, and not use the “value iterator”, then, you can discard the value iterator by maching the value items to the underscore character, like in the example below:\n\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n\n0 | 1 | 2 | 3 | 4 |\n\n\n2.1.6 While loops\nA while loop is created from the while keyword. A for loop iterates through the items of an array, but a while loop will loop continuously, and infinitely, until a logical test (specified by you) becomes false.\nYou start with the while keyword, then, you define a logical expression inside a pair of parentheses, and the body of the loop is provided inside a pair of curly braces, like in the example below:\n\nvar i: u8 = 1;\nwhile (i &lt; 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n\n1 | 2 | 3 | 4 | \n\n\nYou can also specify the increment expression to be used at the beginning of a while loop. To do that, we write the increment expression inside a pair of parentheses after a colon character (:). The code example below demonstrates this other pattern.\n\nvar i: u8 = 1;\nwhile (i &lt; 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n\n1 | 2 | 3 | 4 | \n\n\n\n\n2.1.7 Using break and continue\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using the keywords break and continue, respectively. The while loop presented in the next code example is, at first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to true. But what makes this while loop stop when the i object reaches the count 10? It is the break keyword!\nInside the while loop, we have an if statement that is constantly checking if the i variable is equal to 10. Since we are incrementing the value of i at each iteration of the while loop, this i object will eventually be equal to 10, and when it is, the if statement will execute the break expression, and, as a result, the execution of the while loop is stopped.\nNotice the use of the expect() function from the Zig Standard Library after the while loop. This expect() function is an “assert” type of function. This function checks if the logical test provided is equal to true. If so, the function do nothing. Otherwise (i.e. the logical test is equal to false), the function raises an assertion error.\n\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n\nEverything worked!\n\n\nSince this code example was executed successfully by the zig compiler, without raising any errors, we known that, after the execution of the while loop, the i object is equal to 10. Because if it wasn’t equal to 10, an error would have been raised by expect().\nNow, in the next example, we have a use case for the continue keyword. The if statement is constantly checking if the current index is a multiple of 2. If it is, we jump to the next iteration of the loop. Otherwise, the loop just prints the current index to the console.\n\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n\n1 | 3 | 5 |",
+    "text": "2.1.1 If/else statements\nAn if/else statement performs a “conditional flow operation”. A conditional flow control (or choice control) allows you to execute or ignore a certain block of commands based on a logical condition. Many programmers and computer science professionals also use the term “branching” in this case. In essence, an if/else statement allow us to use the result of a logical test to decide whether or not to execute a given block of commands.\nIn Zig, we write if/else statements by using the keywords if and else. We start with the if keyword followed by a logical test inside a pair of parentheses, followed by a pair of curly braces which contains the lines of code to be executed in case the logical test returns the value true.\nAfter that, you can optionally add an else statement. To do that, just add the else keyword followed by a pair of curly braces, with the lines of code to executed in case the logical test defined at if returns false.\nIn the example below, we are testing if the object x contains a number that is greater than 10. Judging by the output printed to the console, we know that this logical test returned false. Because the output in the console is compatible with the line of code present in the else branch of the if/else statement.\n\nconst x = 5;\nif (x &gt; 10) {\n    try stdout.print(\n        \"x &gt; 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x &lt;= 10!\\n\", .{}\n    );\n}\n\nx &lt;= 10!\n\n\n\n\n2.1.2 Switch statements\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust. As you would expect, to write a switch statement in Zig we use the switch keyword. We provide the value that we want to “switch over” inside a pair of parentheses. Then, we list the possible combinations (or “branches”) inside a pair of curly braces.\nLet’s take a look at the code example below. You can see that I’m creating an enum type called Role. We talk more about enums in Section 7.6. But in summary, this Role type is listing different types of roles in a fictitious company, like SE for Software Engineer, DE for Data Engineer, PM for Product Manager, etc.\nNotice that we are using the value from the role object in the switch statement, to discover which exact area we need to store in the area variable object. Also notice that we are using type inference inside the switch statement, with the dot character, as we are going to describe in Section 2.4. This makes the zig compiler infer the correct data type of the values (PM, SE, etc.) for us.\nAlso notice that, we are grouping multiple values in the same branch of the switch statement. We just separate each possible value with a comma. For example, if role contains either DE or DA, the area variable would contain the value \"Data & Analytics\", instead of \"Platform\" or \"Sales\".\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO =&gt; {\n            area = \"Platform\";\n        },\n        .DE, .DA =&gt; {\n            area = \"Data & Analytics\";\n        },\n        .KS =&gt; {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n\nPlatform\n\n\n\n2.1.2.1 Switch statements must exhaust all possibilities\nOne very important aspect about switch statements in Zig is that they must exhaust all existing possibilities. In other words, all possible values that could be found inside the role object must be explicitly handled in this switch statement.\nSince the role object has type Role, the only possible values to be found inside this object are PM, SE, DPE, PO, DE, DA and KS. There are no other possible values to be stored in this role object. Thus, the switch statements must have a combination (branch) for each one of these values. This is what “exhaust all existing possibilities” means. The switch statement covers every possible case.\nTherefore, you cannot write a switch statement in Zig, and leave an edge case with no explicit action to be taken. This is a similar behaviour to switch statements in Rust, which also have to handle all possible cases.\n\n\n2.1.2.2 The else branch\nTake a look at the dump_hex_fallible() function below as an example. This function comes from the Zig Standard Library. More precisely, from the debug.zig module1. There are multiple lines in this function, but I omitted them to focus solely on the switch statement found in this function. Notice that this switch statement has four possible cases (i.e. four explicit branches). Also, notice that we used an else branch in this case.\nAn else branch in a switch statement works as the “default branch”. Whenever you have multiple cases in your switch statement where you want to apply the exact same action, you can use an else branch to do that.\n\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' =&gt; try writer.writeAll(\"␊\"),\n        '\\r' =&gt; try writer.writeAll(\"␍\"),\n        '\\t' =&gt; try writer.writeAll(\"␉\"),\n        else =&gt; try writer.writeByte('.'),\n    }\n}\n\nMany programmers would also use an else branch to handle a “not supported” case. That is, a case that cannot be properly handled by your code, or, just a case that should not be “fixed”. Therefore, you can use an else branch to panic (or raise an error) in your program to stop the current execution.\nTake the code example below. We can see that, we are handling the cases for the level object being either 1, 2, or 3. All other possible cases are not supported by default, and, as consequence, we raise a runtime error in such cases through the @panic() built-in function.\nAlso notice that, we are assigning the result of the switch statement to a new object called category. This is another thing that you can do with switch statements in Zig. If a branch outputs a value as result, you can store the result value of the switch statement into a new object.\n\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 =&gt; \"beginner\",\n    3 =&gt; \"professional\",\n    else =&gt; {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n\n\n2.1.2.3 Using ranges in switch\nFurthermore, you can also use ranges of values in switch statements. That is, you can create a branch in your switch statement that is used whenever the input value is within the specified range. These “range expressions” are created with the operator .... It is important to emphasize that the ranges created by this operator are inclusive on both ends.\nFor example, I could easily change the previous code example to support all levels between 0 and 100. Like this:\n\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 =&gt; \"beginner\",\n    26...75 =&gt; \"intermediary\",\n    76...100 =&gt; \"professional\",\n    else =&gt; {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n\nbeginner\n\n\nThis is neat, and it works with character ranges too. That is, I could simply write 'a'...'z', to match any character value that is a lowercase letter, and it would work fine.\n\n\n2.1.2.4 Labeled switch statements\nIn Section 1.7 we have talked about labeling blocks, and also, about using these labels to return a value from the block. Well, from version 0.14.0 and onwards of the zig compiler, you can also apply labels over switch statements, which makes it possible to almost implement a “C goto” like pattern.\nFor example, if you give the label xsw to a switch statement, you can use this label in conjunction with the continue keyword to go back to the beginning of the switch statement. In the example below, the execution goes back to the beginning of the switch statement two times, before ending at the 3 branch.\n\nxsw: switch (@as(u8, 1)) {\n    1 =&gt; {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 =&gt; continue :xsw 3,\n    3 =&gt; return,\n    4 =&gt; {},\n    else =&gt; {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n\n\n\n\n2.1.3 The defer keyword\nWith the defer keyword you can register an expression to be executed when you exit the current scope. Therefore, this keyword has a similar functionality as the on.exit() function from R. Take the foo() function below as an example. When we execute this foo() function, the expression that prints the message “Exiting function …” is getting executed only when the function exits its scope.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n\nAdding some numbers ...\nMultiplying ...\nExiting function ...\nTherefore, we can use defer to declare an expression that is going to be executed when your code exits the current scope. Some programmers like to interpret the phrase “exit of the current scope” as “the end of the current scope”. But this interpretation might not be entirely correct, depending on what you consider as “the end of the current scope”.\nI mean, what do you consider as the end of the current scope? Is it the closing curly bracket (}) of the scope? Is it when the last expression in the function gets executed? Is it when the function returns to the previous scope? Etc. For example, it would not be correct to interpret the “exit of the current scope” as the closing curly bracket of the scope. Because the function might exit from an earlier position than this closing curly bracket (e.g. an error value was generated at a previous line inside the function; the function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\nNow, if you remember of what we have discussed in Section 1.7, there are multiple structures in the language that create their own separate scopes. For/while loops, if/else statements, functions, normal blocks, etc. This also affects the interpretation of defer. For example, if you use defer inside a for loop, then, the given expression will be executed everytime this specific for loop exits its own scope.\nBefore we continue, is worth emphasizing that the defer keyword is an “unconditional defer”. Which means that the given expression will be executed no matter how the code exits the current scope. For example, your code might exit the current scope because of an error value being generated, or, because of a return statement, or, a break statement, etc.\n\n\n2.1.4 The errdefer keyword\nOn the previous section, we have discussed the defer keyword, which you can use to register an expression to be executed at the exit of the current scope. But this keyword has a brother, which is the errdefer keyword. While defer is an “unconditional defer”, the errdefer keyword is a “conditional defer”. Which means that the given expression is executed only when you exit the current scope on a very specific circumstance.\nIn more details, the expression given to errdefer is executed only when an error occurs in the current scope. Therefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope in a normal situation, without errors, the expression given to errdefer is not executed.\nThis makes the errdefer keyword one of the many tools available in Zig for error handling. In this section, we are more concerned with the control flow aspects around errdefer. But we are going to discuss errdefer later as a error handling tool in Section 10.2.4.\nThe code example below demonstrates three things:\n\nthat defer is an “unconditional defer”, because the given expression get’s executed regardless of how the function foo() exits its own scope.\nthat errdefer is executed because the function foo() returned an error value.\nthat defer and errdefer expressions are executed in a LIFO (last in, first out) order.\n\n\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\nWhen I say that “defer expressions” are executed in a LIFO order, what I want to say is that the last defer or errdefer expressions in the code are the first ones to be executed. You could also interpret this as: “defer expressions” are executed from bottom to top, or, from last to first.\nTherefore, if I change the order of the defer and errdefer expressions, you will notice that the value of i that get’s printed to the console changes to 1. This doesn’t mean that the defer expression was not executed in this case. This actually means that the defer expression was executed only after the errdefer expression. The code example below demonstrates this:\n\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n\n\n2.1.5 For loops\nA loop allows you to execute the same lines of code multiple times, thus, creating a “repetition space” in the execution flow of your program. Loops are particularly useful when we want to replicate the same function (or the same set of commands) over different inputs.\nThere are different types of loops available in Zig. But the most essential of them all is probably the for loop. A for loop is used to apply the same piece of code over the elements of a slice, or, an array.\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from other languages. You start with the for keyword, then, you list the items that you want to iterate over inside a pair of parentheses. Then, inside of a pair of pipes (|) you should declare an identifier that will serve as your iterator, or, the “repetition index of the loop”.\n\nfor (items) |value| {\n    // code to execute\n}\n\nTherefore, instead of using a (value in items) syntax, in Zig, for loops use the syntax (items) |value|. In the example below, you can see that we are looping through the items of the array stored at the object name, and printing to the console the decimal representation of each character in this array.\nIf we wanted, we could also iterate through a slice (or a portion) of the array, instead of iterating through the entire array stored in the name object. Just use a range selector to select the section you want. For example, I could provide the expression name[0..3] to the for loop, to iterate just through the first 3 elements in the array.\n\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n\n80 | 101 | 100 | 114 | 111 | \n\n\nIn the above example we are using the value itself of each element in the array as our iterator. But there are many situations where we need to use an index instead of the actual values of the items.\nYou can do that by providing a second set of items to iterate over. More precisely, you provide the range selector 0.. to the for loop. So, yes, you can use two different iterators at the same time in a for loop in Zig.\nBut remember from Section 1.4 that, every object you create in Zig must be used in some way. So if you declare two iterators in your for loop, you must use both iterators inside the for loop body. But if you want to use just the index iterator, and not use the “value iterator”, then, you can discard the value iterator by maching the value items to the underscore character, like in the example below:\n\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n\n0 | 1 | 2 | 3 | 4 |\n\n\n2.1.6 While loops\nA while loop is created from the while keyword. A for loop iterates through the items of an array, but a while loop will loop continuously, and infinitely, until a logical test (specified by you) becomes false.\nYou start with the while keyword, then, you define a logical expression inside a pair of parentheses, and the body of the loop is provided inside a pair of curly braces, like in the example below:\n\nvar i: u8 = 1;\nwhile (i &lt; 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n\n1 | 2 | 3 | 4 | \n\n\nYou can also specify the increment expression to be used at the beginning of a while loop. To do that, we write the increment expression inside a pair of parentheses after a colon character (:). The code example below demonstrates this other pattern.\n\nvar i: u8 = 1;\nwhile (i &lt; 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n\n1 | 2 | 3 | 4 | \n\n\n\n\n2.1.7 Using break and continue\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using the keywords break and continue, respectively. The while loop presented in the next code example is, at first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to true. But what makes this while loop stop when the i object reaches the count 10? It is the break keyword!\nInside the while loop, we have an if statement that is constantly checking if the i variable is equal to 10. Since we are incrementing the value of i at each iteration of the while loop, this i object will eventually be equal to 10, and when it is, the if statement will execute the break expression, and, as a result, the execution of the while loop is stopped.\nNotice the use of the expect() function from the Zig Standard Library after the while loop. This expect() function is an “assert” type of function. This function checks if the logical test provided is equal to true. If so, the function do nothing. Otherwise (i.e. the logical test is equal to false), the function raises an assertion error.\n\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n\nEverything worked!\n\n\nSince this code example was executed successfully by the zig compiler, without raising any errors, we known that, after the execution of the while loop, the i object is equal to 10. Because if it wasn’t equal to 10, an error would have been raised by expect().\nNow, in the next example, we have a use case for the continue keyword. The if statement is constantly checking if the current index is a multiple of 2. If it is, we jump to the next iteration of the loop. Otherwise, the loop just prints the current index to the console.\n\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n\n1 | 3 | 5 |",
     "crumbs": [
       "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
     ]
@@ -254,7 +254,7 @@
     "href": "Chapters/03-structs.html#sec-structs-and-oop",
     "title": "2  Control flow, structs, modules and types",
     "section": "2.3 Structs and OOP",
-    "text": "2.3 Structs and OOP\nZig is a language more closely related to C (which is a procedural language), than it is to C++ or Java (which are object-oriented languages). Because of that, you do not have advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or class inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C. You give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can also register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object that you create with this new type, will always have these methods available and associated with them.\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which is used to construct (or, to instantiate) every object of this particular class, and we also have a destructor method (or a destructor function), which is the function responsible for destroying every object of this class.\nIn Zig, we normally declare the constructor and the destructor methods of our structs, by declaring an init() and a deinit() methods inside the struct. This is just a naming convention that you will find across the entire Zig Standard Library. So, in Zig, the init() method of a struct is normally the constructor method of the class represented by this struct. While the deinit() method is the method used for destroying an existing instance of that struct.\nThe init() and deinit() methods are both used extensively in Zig code, and you will see both of them being used when we talk about allocators in Section 3.3. But, as another example, let’s build a simple User struct to represent a user of some sort of system.\nIf you look at the User struct below, you can see the struct keyword. Notice the data members of this struct: id, name and email. Every data member has its type explicitly annotated, with the colon character (:) syntax that we described earlier in Section 1.2.2. But also notice that every line in the struct body that describes a data member, ends with a comma character (,). So every time you declare a data member in your Zig code, always end the line with a comma character, instead of ending it with the traditional semicolon character (;).\nNext, we have registered an init() function as a method of this User struct. This init() method is the constructor method that we will use to instantiate every new User object. That is why this init() function returns a new User object as result.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    pub fn init(id: u64,\n                name: []const u8,\n                email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    pub fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n\npedro\n\n\nThe pub keyword plays an important role in struct declarations, and OOP in Zig. Every method that you declare in your struct that is marked with the keyword pub, becomes a public method of this particular struct.\nSo every method that you create inside your struct, is, at first, a private method of that struct. Meaning that, this method can only be called from within this struct. But, if you mark this method as public, with the keyword pub, then, you can call the method directly from an instance of the User struct.\nIn other words, the functions marked by the keyword pub are members of the public API of that struct. For example, if I did not mark the print_name() method as public, then, I could not execute the line u.print_name(). Because I would not be authorized to call this method directly in my code.\n\n2.3.1 Anonymous struct literals\nYou can declare a struct object as a literal value. When we do that, we normally specify the data type of this struct literal by writing its data type just before the opening curly brace. For example, I could write a struct literal value of the type User that we have defined in the previous section like this:\n\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a struct literal, but not specify explicitly the type of this particular struct. An anonymous struct is written by using the syntax .{}. So, we essentially replaced the explicit type of the struct literal with a dot character (.).\nAs we described in Section 2.4, when you put a dot before a struct literal, the type of this struct literal is automatically inferred by the zig compiler. In essence, the zig compiler will look for some hint of what is the type of that struct. This hint can be the type annotation of a function argument, or the return type annotation of the function that you are using, or the type annotation of an existing object. If the compiler does find such type annotation, it will use this type in your literal struct.\nAnonymous structs are very commonly used as inputs to function arguments in Zig. One example that you have seen already constantly, is the print() function from the stdout object. This function takes two arguments. The first argument, is a template string, which should contain string format specifiers in it, which tells how the values provided in the second argument should be printed into the message.\nWhile the second argument is a struct literal that lists the values to be printed into the template message specified in the first argument. You normally want to use an anonymous struct literal here, so that the zig compiler do the job of specifying the type of this particular anonymous struct for you.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n\nHello, world!\n\n\n\n\n2.3.2 Struct declarations must be constant\nTypes in Zig must be const or comptime (we are going to talk more about comptime in Section 12.1). What this means is that you cannot create a new data type, and mark it as variable with the var keyword. So struct declarations are always constant. You cannot declare a new struct type using the var keyword. It must be const.\nIn the Vec3 example below, this declaration is allowed because I’m using the const keyword to declare this new data type.\n\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n\n\n\n2.3.3 The self method argument\nIn every language that have OOP, when we declare a method of some class or struct, we usually declare this method as a function that has a self argument. This self argument is the reference to the object itself from which the method is being called from.\nIt is not mandatory to use this self argument. But why would you not use this self argument? There is no reason to not use it. Because the only way to get access to the data stored in the data members of your struct is to access them through this self argument. If you don’t need to use the data in the data members of your struct inside your method, you very likely don’t need a method. You can just declare this logic as a simple function, outside of your struct declaration.\nTake the Vec3 struct below. Inside this Vec3 struct we declared a method named distance(). This method calculates the distance between two Vec3 objects, by following the distance formula in euclidean space. Notice that this distance() method takes two Vec3 objects as input, self and other.\n\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n\nThe self argument corresponds to the Vec3 object from which this distance() method is being called from. While the other is a separate Vec3 object that is given as input to this method. In the example below, the self argument corresponds to the object v1, because the distance() method is being called from the v1 object, while the other argument corresponds to the object v2.\n\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n\nDistance: 3.3970575502926055\n\n\n2.3.4 About the struct state\nSometimes you don’t need to care about the state of your struct object. Sometimes, you just need to instantiate and use the objects, without altering their state. You can notice that when you have methods inside your struct declaration that might use the values that are present in the data members, but they do not alter the values in these data members of the struct in anyway.\nThe Vec3 struct that was presented in Section 2.3.3 is an example of that. This struct have a single method named distance(), and this method does use the values present in all three data members of the struct (x, y and z). But at the same time, this method does not change the values of these data members at any point.\nAs a result of that, when we create Vec3 objects we usually create them as constant objects, like the v1 and v2 objects presented in Section 2.3.3. We can create them as variable objects with the var keyword, if we want to. But because the methods of this Vec3 struct do not change the state of the objects in any point, it’s unnecessary to mark them as variable objects.\nBut why? Why am I talking about this here? It’s because the self argument in the methods is affected depending on whether the methods present in a struct change or don’t change the state of the object itself. More specifically, when you have a method in a struct that changes the state of the object (i.e. change the value of a data member), the self argument in this method must be annotated in a different manner.\nAs I described in Section 2.3.3, the self argument in methods of a struct is the argument that receives as input the object from which the method was called from. We usually annotate this argument in the methods by writing self, followed by the colon character (:), and the data type of the struct to which the method belongs to (e.g. User, Vec3, etc.).\nIf we take the Vec3 struct that we defined in the previous section as an example, we can see in the distance() method that this self argument is annotated as self: Vec3. Because the state of the Vec3 object is never altered by this method.\nBut what if we do have a method that alters the state of the object, by altering the values of its data members, how should we annotate self in this instance? The answer is: “we should annotate self as a pointer of x, instead of just x”. In other words, you should annotate self as self: *x, instead of annotating it as self: x.\nIf we create a new method inside the Vec3 object that, for example, expands the vector by multiplying its coordinates by a factor of two, then, we need to follow this rule specified in the previous paragraph. The code example below demonstrates this idea:\n\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n\nNotice in the code example above that we have added a new method to our Vec3 struct named twice(). This method doubles the coordinate values of our vector object. In the case of the twice() method, we annotated the self argument as *Vec3, indicating that this argument receives a pointer (or a reference, if you prefer to call it this way) to a Vec3 object as input.\n\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n\nDoubled: 8.4\nNow, if you change the self argument in this twice() method to self: Vec3, like in the distance() method, you will get the compiler error exposed below as result. Notice that this error message is showing a line from the twice() method body, indicating that you cannot alter the value of the x data member.\n\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\nThis error message indicates that the x data member belongs to a constant object, and, because of that, it cannot be changed. Ultimately, this error message is telling us that the self argument is constant.\nIf you take some time, and think hard about this error message, you will understand it. You already have the tools to understand why we are getting this error message. We have talked about it already in Section 2.2. So remember, every function argument is immutable in Zig, and self is no exception to this rule.\nIn this example, we marked the v3 object as a variable object. But this does not matter. Because it is not about the input object, it is about the function argument.\nThe problem begins when we try to alter the value of self directly, which is a function argument, and, every function argument is immutable by default. You may ask yourself how can we overcome this barrier, and once again, the solution was also discussed in Section 2.2. We overcome this barrier, by explicitly marking the self argument as a pointer.\n\n\n\n\n\n\nNote\n\n\n\nIf a method of your x struct alters the state of the object, by changing the value of any data member, then, remember to use self: *x, instead of self: x in the function signature of this method.\n\n\nYou could also interpret the content discussed in this section as: “if you need to alter the state of your x struct object in one of its methods, you must explicitly pass the x struct object by reference to the self argument of this method”.",
+    "text": "2.3 Structs and OOP\nZig is a language more closely related to C (which is a procedural language), than it is to C++ or Java (which are object-oriented languages). Because of that, you do not have advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or class inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C. You give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can also register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object that you create with this new type, will always have these methods available and associated with them.\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which is used to construct (or, to instantiate) every object of this particular class, and we also have a destructor method (or a destructor function), which is the function responsible for destroying every object of this class.\nIn Zig, we normally declare the constructor and the destructor methods of our structs, by declaring an init() and a deinit() methods inside the struct. This is just a naming convention that you will find across the entire Zig Standard Library. So, in Zig, the init() method of a struct is normally the constructor method of the class represented by this struct. While the deinit() method is the method used for destroying an existing instance of that struct.\nThe init() and deinit() methods are both used extensively in Zig code, and you will see both of them being used when we talk about allocators in Section 3.3. But, as another example, let’s build a simple User struct to represent a user of some sort of system.\nIf you look at the User struct below, you can see the struct keyword. Notice the data members of this struct: id, name and email. Every data member has its type explicitly annotated, with the colon character (:) syntax that we described earlier in Section 1.2.2. But also notice that every line in the struct body that describes a data member, ends with a comma character (,). So every time you declare a data member in your Zig code, always end the line with a comma character, instead of ending it with the traditional semicolon character (;).\nNext, we have registered an init() function as a method of this User struct. This init() method is the constructor method that we will use to instantiate every new User object. That is why this init() function returns a new User object as result.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    pub fn init(id: u64,\n                name: []const u8,\n                email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    pub fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n\npedro\n\n\nThe pub keyword plays an important role in struct declarations, and OOP in Zig. Every method that you declare in your struct that is marked with the keyword pub, becomes a public method of this particular struct.\nSo every method that you create inside your struct, is, at first, a private method of that struct. Meaning that, this method can only be called from within this struct. But, if you mark this method as public, with the keyword pub, then, you can call the method directly from an instance of the User struct.\nIn other words, the functions marked by the keyword pub are members of the public API of that struct. For example, if I did not mark the print_name() method as public, then, I could not execute the line u.print_name(). Because I would not be authorized to call this method directly in my code.\n\n2.3.1 Anonymous struct literals\nYou can declare a struct object as a literal value. When we do that, we normally specify the data type of this struct literal by writing its data type just before the opening curly brace. For example, I could write a struct literal value of the type User that we have defined in the previous section like this:\n\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a struct literal, but not specify explicitly the type of this particular struct. An anonymous struct is written by using the syntax .{}. So, we essentially replaced the explicit type of the struct literal with a dot character (.).\nAs we described in Section 2.4, when you put a dot before a struct literal, the type of this struct literal is automatically inferred by the zig compiler. In essence, the zig compiler will look for some hint of what is the type of that struct. This hint can be the type annotation of a function argument, or the return type annotation of the function that you are using, or the type annotation of an existing object. If the compiler does find such type annotation, it will use this type in your literal struct.\nAnonymous structs are very commonly used as inputs to function arguments in Zig. One example that you have seen already constantly, is the print() function from the stdout object. This function takes two arguments. The first argument, is a template string, which should contain string format specifiers in it, which tells how the values provided in the second argument should be printed into the message.\nWhile the second argument is a struct literal that lists the values to be printed into the template message specified in the first argument. You normally want to use an anonymous struct literal here, so that the zig compiler do the job of specifying the type of this particular anonymous struct for you.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n\nHello, world!\n\n\n\n\n2.3.2 Struct declarations must be constant\nTypes in Zig must be const or comptime (we are going to talk more about comptime in Section 12.1). What this means is that you cannot create a new data type, and mark it as variable with the var keyword. So struct declarations are always constant. You cannot declare a new struct type using the var keyword. It must be const.\nIn the Vec3 example below, this declaration is allowed because I’m using the const keyword to declare this new data type.\n\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n\n\n\n2.3.3 The self method argument\nIn every language that have OOP, when we declare a method of some class or struct, we usually declare this method as a function that has a self argument. This self argument is the reference to the object itself from which the method is being called from.\nIt is not mandatory to use this self argument. But why would you not use this self argument? There is no reason to not use it. Because the only way to get access to the data stored in the data members of your struct is to access them through this self argument. If you don’t need to use the data in the data members of your struct inside your method, you very likely don’t need a method. You can just declare this logic as a simple function, outside of your struct declaration.\nTake the Vec3 struct below. Inside this Vec3 struct we declared a method named distance(). This method calculates the distance between two Vec3 objects, by following the distance formula in euclidean space. Notice that this distance() method takes two Vec3 objects as input, self and other.\n\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n\nThe self argument corresponds to the Vec3 object from which this distance() method is being called from. While the other is a separate Vec3 object that is given as input to this method. In the example below, the self argument corresponds to the object v1, because the distance() method is being called from the v1 object, while the other argument corresponds to the object v2.\n\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n\nDistance: 3.3970575502926055\n\n\n2.3.4 About the struct state\nSometimes you don’t need to care about the state of your struct object. Sometimes, you just need to instantiate and use the objects, without altering their state. You can notice that when you have methods inside your struct declaration that might use the values that are present in the data members, but they do not alter the values in these data members of the struct in anyway.\nThe Vec3 struct that was presented in Section 2.3.3 is an example of that. This struct have a single method named distance(), and this method does use the values present in all three data members of the struct (x, y and z). But at the same time, this method does not change the values of these data members at any point.\nAs a result of that, when we create Vec3 objects we usually create them as constant objects, like the v1 and v2 objects presented in Section 2.3.3. We can create them as variable objects with the var keyword, if we want to. But because the methods of this Vec3 struct do not change the state of the objects in any point, it’s unnecessary to mark them as variable objects.\nBut why? Why am I talking about this here? It’s because the self argument in the methods are affected depending on whether the methods present in a struct change or don’t change the state of the object itself. More specifically, when you have a method in a struct that changes the state of the object (i.e. changes the value of a data member), the self argument in this method must be annotated in a different manner.\nAs I described in Section 2.3.3, the self argument in methods of a struct is the argument that receives as input the object from which the method was called from. We usually annotate this argument in the methods by writing self, followed by the colon character (:), and the data type of the struct to which the method belongs to (e.g. User, Vec3, etc.).\nIf we take the Vec3 struct that we defined in the previous section as an example, we can see in the distance() method that this self argument is annotated as self: Vec3. Because the state of the Vec3 object is never altered by this method.\nBut what if we do have a method that alters the state of the object, by altering the values of its data members, how should we annotate self in this instance? The answer is: “we should annotate self as a pointer of x, instead of just x”. In other words, you should annotate self as self: *x, instead of annotating it as self: x.\nIf we create a new method inside the Vec3 object that, for example, expands the vector by multiplying its coordinates by a factor of two, then, we need to follow this rule specified in the previous paragraph. The code example below demonstrates this idea:\n\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n\nNotice in the code example above that we have added a new method to our Vec3 struct named twice(). This method doubles the coordinate values of our vector object. In the case of the twice() method, we annotated the self argument as *Vec3, indicating that this argument receives a pointer (or a reference, if you prefer to call it this way) to a Vec3 object as input.\n\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n\nDoubled: 8.4\nNow, if you change the self argument in this twice() method to self: Vec3, like in the distance() method, you will get the compiler error exposed below as result. Notice that this error message is showing a line from the twice() method body, indicating that you cannot alter the value of the x data member.\n\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\nThis error message indicates that the x data member belongs to a constant object, and, because of that, it cannot be changed. Ultimately, this error message is telling us that the self argument is constant.\nIf you take some time, and think hard about this error message, you will understand it. You already have the tools to understand why we are getting this error message. We have talked about it already in Section 2.2. So remember, every function argument is immutable in Zig, and self is no exception to this rule.\nIn this example, we marked the v3 object as a variable object. But this does not matter. Because it is not about the input object, it is about the function argument.\nThe problem begins when we try to alter the value of self directly, which is a function argument, and, every function argument is immutable by default. You may ask yourself how can we overcome this barrier, and once again, the solution was also discussed in Section 2.2. We overcome this barrier, by explicitly marking the self argument as a pointer.\n\n\n\n\n\n\nNote\n\n\n\nIf a method of your x struct alters the state of the object, by changing the value of any data member, then, remember to use self: *x, instead of self: x in the function signature of this method.\n\n\nYou could also interpret the content discussed in this section as: “if you need to alter the state of your x struct object in one of its methods, you must explicitly pass the x struct object by reference to the self argument of this method”.",
     "crumbs": [
       "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
     ]
@@ -264,7 +264,7 @@
     "href": "Chapters/03-structs.html#sec-type-inference",
     "title": "2  Control flow, structs, modules and types",
     "section": "2.4 Type inference",
-    "text": "2.4 Type inference\nZig is a strongly typed language. But, there are some situations where you don’t have to explicitly write the type of every single object in your source code, as you would expect from a traditional strongly typed language, such as C and C++.\nIn some situations, the zig compiler can use type inference to solve the data types for you, easing some of the burden that you carry as a developer. The most common way this happens is through function arguments that receive struct objects as input.\nIn general, type inference in Zig is done by using the dot character (.). Everytime you see a dot character written before a struct literal, or before an enum value, or something like that, you know that this dot character is playing a special party in this place. More specifically, it is telling the zig compiler something along the lines of: “Hey! Can you infer the type of this value for me? Please!”. In other words, this dot character is playing a similar role as the auto keyword in C++.\nI gave you some examples of this in Section 2.3.1, where we used anonymous struct literals. Anonymous struct literals are, struct literals that use type inference to infer the exact type of this particular struct literal. This type inference is done by looking for some minimal hint of the correct data type to be used. You could say that the zig compiler looks for any neighbouring type annotation that might tell it what the correct type would be.\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in Section 2.1.2). I also gave some other examples of type inference in Section 2.1.2, where we were inferring the data types of enum values listed inside of switch statements (e.g. .DE). But as another example, take a look at this fence() function reproduced below, which comes from the atomic.zig module2 of the Zig Standard Library.\nThere are a lot of things in this function that we haven’t talked about yet, such as: what comptime means? inline? extern? Let’s just ignore all of these things, and focus solely on the switch statement that is inside this function.\nWe can see that this switch statement uses the order object as input. This order object is one of the inputs of this fence() function, and we can see in the type annotation, that this object is of type AtomicOrder. We can also see a bunch of values inside the switch statements that begin with a dot character, such as .release and .acquire.\nBecause these weird values contain a dot character before them, we are asking the zig compiler to infer the types of these values inside the switch statement. Then, the zig compiler is looking into the current context where these values are being used, and it is trying to infer the types of these values.\nSince they are being used inside a switch statement, the zig compiler looks into the type of the input object given to the switch statement, which is the order object in this case. Because this object have type AtomicOrder, the zig compiler infers that these values are data members from this type AtomicOrder.\n\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic =&gt; @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire =&gt; tsan.__tsan_acquire(addr),\n            .release =&gt; tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst =&gt; {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n\nThis is how basic type inference is done in Zig. If we didn’t use the dot character before the values inside this switch statement, then, we would be forced to explicitly write the data types of these values. For example, instead of writing .release we would have to write AtomicOrder.release. We would have to do this for every single value in this switch statement, and this is a lot of work. That is why type inference is commonly used on switch statements in Zig.",
+    "text": "2.4 Type inference\nZig is a strongly typed language. But, there are some situations where you don’t have to explicitly write the type of every single object in your source code, as you would expect from a traditional strongly typed language, such as C and C++.\nIn some situations, the zig compiler can use type inference to solve the data types for you, easing some of the burden that you carry as a developer. The most common way this happens is through function arguments that receive struct objects as input.\nIn general, type inference in Zig is done by using the dot character (.). Everytime you see a dot character written before a struct literal, or before an enum value, or something like that, you know that this dot character is playing a special part in this place. More specifically, it is telling the zig compiler something along the lines of: “Hey! Can you infer the type of this value for me? Please!”. In other words, this dot character is playing a similar role as the auto keyword in C++.\nI gave you some examples of this in Section 2.3.1, where we used anonymous struct literals. Anonymous struct literals are, struct literals that use type inference to infer the exact type of this particular struct literal. This type inference is done by looking for some minimal hint of the correct data type to be used. You could say that the zig compiler looks for any neighbouring type annotation that might tell it what the correct type would be.\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in Section 2.1.2). I also gave some other examples of type inference in Section 2.1.2, where we were inferring the data types of enum values listed inside of switch statements (e.g. .DE). But as another example, take a look at this fence() function reproduced below, which comes from the atomic.zig module2 of the Zig Standard Library.\nThere are a lot of things in this function that we haven’t talked about yet, such as: what comptime means? inline? extern? Let’s just ignore all of these things, and focus solely on the switch statement that is inside this function.\nWe can see that this switch statement uses the order object as input. This order object is one of the inputs of this fence() function, and we can see in the type annotation, that this object is of type AtomicOrder. We can also see a bunch of values inside the switch statements that begin with a dot character, such as .release and .acquire.\nBecause these weird values contain a dot character before them, we are asking the zig compiler to infer the types of these values inside the switch statement. Then, the zig compiler is looking into the current context where these values are being used, and it is trying to infer the types of these values.\nSince they are being used inside a switch statement, the zig compiler looks into the type of the input object given to the switch statement, which is the order object in this case. Because this object have type AtomicOrder, the zig compiler infers that these values are data members from this type AtomicOrder.\n\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic =&gt; @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire =&gt; tsan.__tsan_acquire(addr),\n            .release =&gt; tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst =&gt; {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n\nThis is how basic type inference is done in Zig. If we didn’t use the dot character before the values inside this switch statement, then, we would be forced to explicitly write the data types of these values. For example, instead of writing .release we would have to write AtomicOrder.release. We would have to do this for every single value in this switch statement, and this is a lot of work. That is why type inference is commonly used on switch statements in Zig.",
     "crumbs": [
       "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
     ]
@@ -274,7 +274,7 @@
     "href": "Chapters/03-structs.html#sec-type-cast",
     "title": "2  Control flow, structs, modules and types",
     "section": "2.5 Type casting",
-    "text": "2.5 Type casting\nIn this section, I want to discuss type casting (or, type conversion) with you. We use type casting when we have an object of type “x”, and we want to convert it into an object of type “y”, i.e. we want to change the data type of the object.\nMost languages have a formal way to perform type casting. In Rust for example, we normally use the keyword as, and in C, we normally use the type casting syntax, e.g. (int) x. In Zig, we use the @as() built-in function to cast an object of type “x”, into an object of type “y”.\nThis @as() function is the preferred way to perform type conversion (or type casting) in Zig. Because it is explicit, and, it also performs the casting only if it is unambiguous and safe. To use this function, you just provide the target data type in the first argument, and, the object that you want cast as the second argument.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n\n1/1 filecdc41797a754.test_0...OKAll 1 tests passed\n  d.\n\n\nThis is the general way to perform type casting in Zig. But remember, @as() works only when casting is unambiguous and safe, and there are situations where these assumptions do not hold. For example, when casting an integer value into a float value, or vice-versa, it is not clear to the compiler how to perform this conversion safely.\nTherefore, we need to use specialized “casting functions” in such situations. For example, if you want to cast an integer value into a float value, then, you should use the @floatFromInt() function. In the inverse scenario, you should use the @intFromFloat() function.\nIn these functions, you just provide the object that you want to cast as input. Then, the target data type of the “type casting operation” is determined by the type annotation of the object where you are saving the results. In the example below, we are casting the object x into a value of type f32, because the object y, which is where we are saving the results, is annotated as an object of type f32.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n\n1/1 filecdc428638149.test_0...OKAll 1 tests passed\n  d.\n\n\nAnother built-in function that is very useful when performing type casting operations is @ptrCast(). In essence, we use the @as() built-in function when we want to explicit convert (or cast) a Zig value/object from a type “x” to a type “y”, etc. However, pointers (we are going to discuss pointers in more depth in Chapter 6) are a special type of object in Zig, i.e. they are treated differently from “normal objects”.\nEverytime a pointer is involved in some “type casting operation” in Zig, the @ptrCast() function is used. This function works similarly to @floatFromInt(). You just provide the pointer object that you want to cast as input to this function, and the target data type is, once again, determined by the type annotation of the object where the results are being stored.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n\n1/1 filecdc46f71cc03.test_0...OKAll 1 tests passed\n  d.",
+    "text": "2.5 Type casting\nIn this section, I want to discuss type casting (or, type conversion) with you. We use type casting when we have an object of type “x”, and we want to convert it into an object of type “y”, i.e. we want to change the data type of the object.\nMost languages have a formal way to perform type casting. In Rust for example, we normally use the keyword as, and in C, we normally use the type casting syntax, e.g. (int) x. In Zig, we use the @as() built-in function to cast an object of type “x”, into an object of type “y”.\nThis @as() function is the preferred way to perform type conversion (or type casting) in Zig. Because it is explicit, and, it also performs the casting only if it is unambiguous and safe. To use this function, you just provide the target data type in the first argument, and, the object that you want cast as the second argument.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n\n1/1 file2ed34a8fc96.test_0...OKAll 1 tests passed.\n\n\nThis is the general way to perform type casting in Zig. But remember, @as() works only when casting is unambiguous and safe, and there are situations where these assumptions do not hold. For example, when casting an integer value into a float value, or vice-versa, it is not clear to the compiler how to perform this conversion safely.\nTherefore, we need to use specialized “casting functions” in such situations. For example, if you want to cast an integer value into a float value, then, you should use the @floatFromInt() function. In the inverse scenario, you should use the @intFromFloat() function.\nIn these functions, you just provide the object that you want to cast as input. Then, the target data type of the “type casting operation” is determined by the type annotation of the object where you are saving the results. In the example below, we are casting the object x into a value of type f32, because the object y, which is where we are saving the results, is annotated as an object of type f32.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n\n1/1 file2ed34bfb9fa5.test_0...OKAll 1 tests passed\n  d.\n\n\nAnother built-in function that is very useful when performing type casting operations is @ptrCast(). In essence, we use the @as() built-in function when we want to explicit convert (or cast) a Zig value/object from a type “x” to a type “y”, etc. However, pointers (we are going to discuss pointers in more depth in Chapter 6) are a special type of object in Zig, i.e. they are treated differently from “normal objects”.\nEverytime a pointer is involved in some “type casting operation” in Zig, the @ptrCast() function is used. This function works similarly to @floatFromInt(). You just provide the pointer object that you want to cast as input to this function, and the target data type is, once again, determined by the type annotation of the object where the results are being stored.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n\n1/1 file2ed324328e1f.test_0...OKAll 1 tests passed\n  d.",
     "crumbs": [
       "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
     ]
@@ -314,7 +314,7 @@
     "href": "Chapters/01-memory.html#memory-spaces",
     "title": "3  Memory and Allocators",
     "section": "",
-    "text": "Global data register (or the “global data section”);\nStack;\nHeap;\n\n\n3.1.1 Compile-time known versus runtime known\nOne strategy that Zig uses to decide where it will store each object that you declare, is by looking at the value of this particular object. More specifically, by investigating if this value is known at “compile-time” or at “runtime”.\nWhen you write a program in Zig, the values of some of the objects that you write in your program are known at compile time. Meaning that, when you compile your Zig source code, during the compilation process, the zig compiler can figure out the exact value of a particular object that exists in your source code. Knowing the length (or the size) of each object is also important. So the length (or the size) of each object that you write in your program is, in some cases, known at compile time.\nThe zig compiler cares more about knowing the length (or the size) of a particular object , than to know its actual value. But, if the zig compiler knows the value of the object, then, it automatically knows the size of this object. Because it can simply calculate the size of the object by looking at the size of the value.\nTherefore, the priority for the zig compiler is to discover the size of each object in your source code. If the value of the object in question is known at compile-time, then, the zig compiler automatically knows the size/length of this object. But if the value of this object is not known at compile-time, then, the size of this object is only known at compile-time if, and only if, the type of this object has a known fixed size.\nIn order for a type to have a known fixed size, this type must have data members whose size is fixed. If this type includes, for example, a variable sized array in it, then, this type does not have a known fixed size. Because this array can have any size at runtime (i.e. it can be an array of 2 elements, or 50 elements, or 1 thousand elements, etc.).\nFor example, a string object, which internally is an array of constant u8 values ([]const u8) has a variable size. It can be a string object with 100 or 500 characters in it. If we do not know at compile-time, which exact string will be stored inside this string object, then, we cannot calculate the size of this string object at compile-time. So, any type, or any struct declaration that you make, that includes a string data member that does not have an explicit fixed size, makes this type, or this new struct that you are declaring, a type that does not have a known fixed size at compile-time.\nIn contrast, if the type of this struct that you are declaring, includes a data member that is an array, but this array has a known fixed size, like [60]u8 (which declares an array of 60 u8 values), then, this type, or, this struct that you are declaring, becomes a type with a known fixed size at compile-time. And because of that, in this case, the zig compiler does not need to know at compile-time the exact value of any object of this type. Since the compiler can find the necessary size to store this object by looking at the size of its type.\nLet’s look at an example. In the source code below, we have two constant objects (name and array) declared. Because the values of these particular objects are written down, in the source code itself (\"Pedro\" and the number sequence from 1 to 4), the zig compiler can easily discover the values of these constant objects (name and array) during the compilation process. This is what “known at compile time” means. It refers to any object that you have in your Zig source code whose value can be identified at compile time.\n\nfn input_length(input: []const u8) usize {\n    const n = input.len;\n    return n;\n}\n\npub fn main() !void {\n    const name = \"Pedro\";\n    const array = [_]u8{1, 2, 3, 4};\n    _ = name; _ = array;\n}\n\nThe other side of the spectrum are objects whose values are not known at compile time. Function arguments are a classic example of this. Because the value of each function argument depends on the value that you assign to this particular argument, when you call the function.\nFor example, the function input_length() contains an argument named input, which is an array of constant u8 integers ([]const u8). It is impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length of this particular argument. Because it is an array that do not have a fixed size specified explicitly in the argument type annotation.\nSo, we know that this input argument will be an array of u8 integers. But we do not know at compile-time, its value, and neither his size. This information is known only at runtime, which is the period of time when you program is executed. As a consequence, the value of the expression input.len is also known only at runtime. This is an intrinsic characteristic of any function. Just remember that the value of function arguments is usually not “compile-time known”.\nHowever, as I mentioned earlier, what really matters to the compiler is to know the size of the object at compile-time, and not necessarily its value. So, although we don’t know the value of the object n, which is the result of the expression input.len, at compile-time, we do know its size. Because the expression input.len always returns a value of type usize, and the type usize has a known fixed size.\n\n\n3.1.2 Global data register\nThe global data register is a specific section of the executable of your Zig program, that is responsible for storing any value that is known at compile time.\nEvery constant object whose value is known at compile time that you declare in your source code, is stored in the global data register. Also, every literal value that you write in your source code, such as the string \"this is a string\", or the integer 10, or a boolean value such as true, is also stored in the global data register.\nHonestly, you don’t need to care much about this memory space. Because you can’t control it, you can’t deliberately access it or use it for your own purposes. Also, this memory space does not affect the logic of your program. It simply exists in your program.\n\n\n3.1.3 Stack vs Heap\nIf you are familiar with system’s programming, or just low-level programming in general, you probably have heard of the “duel” between Stack vs Heap. These are two different types of memory, or different memory spaces, which are both available in Zig.\nThese two types of memory don’t actually duel with each other. This is a common mistake that beginners have, when seeing “x vs y” styles of tabloid headlines. These two types of memory are actually complementary to each other. So, in almost every Zig program that you ever write, you will likely use a combination of both. I will describe each memory space in detail over the next sections. But for now, I just want to stablish the main difference between these two types of memory.\nIn essence, the stack memory is normally used to store values whose length is fixed and known at compile time. In contrast, the heap memory is a dynamic type of memory space, meaning that, it is used to store values whose length might grow during the execution (runtime) of your program (Chen and Guo 2022).\nLengths that grow during runtime are intrinsically associated with “runtime known” type of values. In other words, if you have an object whose length might grow during runtime, then, the length of this object becomes not known at compile time. If the length is not known at compile-time, the value of this object also becomes not known at compile-time. These types of objects should be stored in the heap memory space, which is a dynamic memory space, which can grow or shrink to fit the size of your objects.\n\n\n3.1.4 Stack\nThe stack is a type of memory that uses the power of the stack data structure, hence the name. A “stack” is a type of data structure that uses a “last in, first out” (LIFO) mechanism to store the values you give it to. I imagine you are familiar with this data structure. But, if you are not, the Wikipedia page1 , or, the Geeks For Geeks page2 are both excellent and easy resources to fully understand how this data structure works.\nSo, the stack memory space is a type of memory that stores values using a stack data structure. It adds and removes values from the memory by following a “last in, first out” (LIFO) principle.\nEvery time you make a function call in Zig, an amount of space in the stack is reserved for this particular function call (Chen and Guo 2022; Zig Software Foundation 2024). The value of each function argument given to the function in this function call is stored in this stack space. Also, every local object that you declare inside the function scope is usually stored in this same stack space.\nLooking at the example below, the object result is a local object declared inside the scope of the add() function. Because of that, this object is stored inside the stack space reserved for the add() function. The r object (which is declared outside of the add() function scope) is also stored in the stack. But since it is declared in the “outer” scope, this object is stored in the stack space that belongs to this outer scope.\n\nfn add(x: u8, y: u8) u8 {\n    const result = x + y;\n    return result;\n}\n\npub fn main() !void {\n    const r = add(5, 27);\n    _ = r;\n}\n\nSo, any object that you declare inside the scope of a function is always stored inside the space that was reserved for that particular function in the stack memory. This also counts for any object declared inside the scope of your main() function for example. As you would expect, in this case, they are stored inside the stack space reserved for the main() function.\nOne very important detail about the stack memory is that it frees itself automatically. This is very important, remember that. When objects are stored in the stack memory, you don’t have the work (or the responsibility) of freeing/destroying these objects. Because they will be automatically destroyed once the stack space is freed at the end of the function scope.\nSo, once the function call returns (or ends, if you prefer to call it this way) the space that was reserved in the stack is destroyed, and all of the objects that were in that space goes away with it. This mechanism exists because this space, and the objects within it, are not necessary anymore, since the function “finished its business”. Using the add() function that we exposed above as an example, it means that the object result is automatically destroyed once the function returns.\n\n\n\n\n\n\nImportant\n\n\n\nLocal objects that are stored in the stack space of a function are automatically freed/destroyed at the end of the function scope.\n\n\nThis same logic applies to any other special structure in Zig that have its own scope by surrounding it with curly braces ({}). For loops, while loops, if else statements, etc. For example, if you declare any local object in the scope of a for loop, this local object is accessible only within the scope of this particular for loop. Because once the scope of this for loop ends, the space in the stack reserved for this for loop is freed. The example below demonstrates this idea.\n\n// This does not compile successfully!\nconst a = [_]u8{0, 1, 2, 3, 4};\nfor (0..a.len) |i| {\n    const index = i;\n    _ = index;\n}\n// Trying to use an object that was\n// declared in the for loop scope,\n// and that does not exist anymore.\nstd.debug.print(\"{d}\\n\", index);\n\nOne important consequence of this mechanism is that, once the function returns, you can no longer access any memory address that was inside the space in the stack reserved for this particular function. Because this space was destroyed. This means that, if this local object is stored in the stack, you cannot make a function that returns a pointer to this object.\nThink about that for a second. If all local objects in the stack are destroyed at the end of the function scope, why would you even consider returning a pointer to one of these objects? This pointer is at best, invalid, or, more likely, “undefined”.\nConclusion, it is totally fine to write a function that returns the local object itself as result, because then, you return the value of that object as the result. But, if this local object is stored in the stack, you should never write a function that returns a pointer to this local object. Because the memory address pointed by the pointer no longer exists.\nSo, using again the add() function as an example, if you rewrite this function so that it returns a pointer to the local object result, the zig compiler will actually compile your program, with no warnings or errors. At first glance, it looks that this is good code that works as expected. But this is a lie!\nIf you try to take a look at the value inside of the r object, or, if you try to use this r object in another expression or function call, then, you would have undefined behaviour, and major bugs in your program (Zig Software Foundation 2024, see “Lifetime and Ownership”3 and “Undefined Behaviour”4 sections).\n\nfn add(x: u8, y: u8) *const u8 {\n    const result = x + y;\n    return &result;\n}\n\npub fn main() !void {\n    // This code compiles successfully. But it has\n    // undefined behaviour. Never do this!!!\n    // The `r` object is undefined!\n    const r = add(5, 27); _ = r;\n}\n\nThis “invalid pointer to stack variable” problem is very known across many programming language communities. If you try to do the same thing, for example, in a C or C++ program (i.e. returning an address to a local object stored in the stack), you would also get undefined behaviour in the program.\n\n\n\n\n\n\nImportant\n\n\n\nIf a local object in your function is stored in the stack, you should never return a pointer to this local object from the function. Because this pointer will always become undefined after the function returns, since the stack space of the function is destroyed at the end of its scope.\n\n\nBut what if you really need to use this local object in some way after your function returns? How can you do this? The answer is: “in the same you would do if this was a C or C++ program. By returning an address to an object stored in the heap”. The heap memory has a much more flexible lifecycle, and allows you to get a valid pointer to a local object of a function that already returned from its scope.\n\n\n3.1.5 Heap\nOne important limitation of the stack, is that, only objects whose length/size is known at compile-time can be stored in it. In contrast, the heap is a much more dynamic (and flexible) type of memory. It is the perfect type of memory to use for objects whose size/length might grow during the execution of your program.\nVirtually any application that behaves as a server is a classic use case of the heap. A HTTP server, a SSH server, a DNS server, a LSP server, … any type of server. In summary, a server is a type of application that runs for long periods of time, and that serves (or “deals with”) any incoming request that reaches this particular server.\nThe heap is a good choice for this type of system, mainly because the server does not know upfront how many requests it will receive from users, while it is active. It could be one single request, or, 5 thousand requests, or, it could also be zero requests. The server needs to have the ability to allocate and manage its memory according to how many requests it receives.\nAnother key difference between the stack and the heap, is that the heap is a type of memory that you, the programmer, have complete control over. This makes the heap a more flexible type of memory, but it also makes it harder to work with. Because you, the programmer, is responsible for managing everything related to it. Including where the memory is allocated, how much memory is allocated, and where this memory is freed.\n\nUnlike stack memory, heap memory is allocated explicitly by programmers and it won’t be deallocated until it is explicitly freed (Chen and Guo 2022).\n\nTo store an object in the heap, you, the programmer, needs to explicitly tells Zig to do so, by using an allocator to allocate some space in the heap. At Section 3.3, I will present how you can use allocators to allocate memory in Zig.\n\n\n\n\n\n\nImportant\n\n\n\nEvery memory you allocate in the heap needs to be explicitly freed by you, the programmer.\n\n\nThe majority of allocators in Zig do allocate memory on the heap. But some exceptions to this rule are ArenaAllocator() and FixedBufferAllocator(). The ArenaAllocator() is a special type of allocator that works in conjunction with a second type of allocator. On the other side, the FixedBufferAllocator() is an allocator that works based on buffer objects created on the stack. This means that the FixedBufferAllocator() makes allocations only on the stack.\n\n\n3.1.6 Summary\nAfter discussing all of these boring details, we can quickly recap what we learned. In summary, the Zig compiler will use the following rules to decide where each object you declare is stored:\n\nevery literal value (such as \"this is string\", 10, or true) is stored in the global data section.\nevery constant object (const) whose value is known at compile-time is also stored in the global data section.\nevery object (constant or not) whose length/size is known at compile time is stored in the stack space for the current scope.\nif an object is created with the method alloc() or create() of an allocator object, this object is stored in the memory space used by this particular allocator object. Most of allocators available in Zig use the heap memory, so, this object is likely stored in the heap (FixedBufferAllocator() is an exception to that).\nthe heap can only be accessed through allocators. If your object was not created through the alloc() or create() methods of an allocator object, then, he is most certainly not an object stored in the heap.",
+    "text": "Global data register (or the “global data section”);\nStack;\nHeap;\n\n\n3.1.1 Compile-time known versus runtime known\nOne strategy that Zig uses to decide where it will store each object that you declare, is by looking at the value of this particular object. More specifically, by investigating if this value is known at “compile-time” or at “runtime”.\nWhen you write a program in Zig, the values of some of the objects that you write in your program are known at compile time. Meaning that, when you compile your Zig source code, during the compilation process, the zig compiler can figure out the exact value of a particular object that exists in your source code. Knowing the length (or the size) of each object is also important. So the length (or the size) of each object that you write in your program is, in some cases, known at compile time.\nThe zig compiler cares more about knowing the length (or the size) of a particular object , than to know its actual value. But, if the zig compiler knows the value of the object, then, it automatically knows the size of this object. Because it can simply calculate the size of the object by looking at the size of the value.\nTherefore, the priority for the zig compiler is to discover the size of each object in your source code. If the value of the object in question is known at compile-time, then, the zig compiler automatically knows the size/length of this object. But if the value of this object is not known at compile-time, then, the size of this object is only known at compile-time if, and only if, the type of this object has a known fixed size.\nIn order for a type to have a known fixed size, this type must have data members whose size is fixed. If this type includes, for example, a variable sized array in it, then, this type does not have a known fixed size. Because this array can have any size at runtime (i.e. it can be an array of 2 elements, or 50 elements, or 1 thousand elements, etc.).\nFor example, a string object, which internally is an array of constant u8 values ([]const u8) has a variable size. It can be a string object with 100 or 500 characters in it. If we do not know at compile-time, which exact string will be stored inside this string object, then, we cannot calculate the size of this string object at compile-time. So, any type, or any struct declaration that you make, that includes a string data member that does not have an explicit fixed size, makes this type, or this new struct that you are declaring, a type that does not have a known fixed size at compile-time.\nIn contrast, if the type of this struct that you are declaring, includes a data member that is an array, but this array has a known fixed size, like [60]u8 (which declares an array of 60 u8 values), then, this type, or, this struct that you are declaring, becomes a type with a known fixed size at compile-time. And because of that, in this case, the zig compiler does not need to know at compile-time the exact value of any object of this type. Since the compiler can find the necessary size to store this object by looking at the size of its type.\nLet’s look at an example. In the source code below, we have two constant objects (name and array) declared. Because the values of these particular objects are written down, in the source code itself (\"Pedro\" and the number sequence from 1 to 4), the zig compiler can easily discover the values of these constant objects (name and array) during the compilation process. This is what “known at compile time” means. It refers to any object that you have in your Zig source code whose value can be identified at compile time.\n\nfn input_length(input: []const u8) usize {\n    const n = input.len;\n    return n;\n}\n\npub fn main() !void {\n    const name = \"Pedro\";\n    const array = [_]u8{1, 2, 3, 4};\n    _ = name; _ = array;\n}\n\nThe other side of the spectrum are objects whose values are not known at compile time. Function arguments are a classic example of this. Because the value of each function argument depends on the value that you assign to this particular argument, when you call the function.\nFor example, the function input_length() contains an argument named input, which is an array of constant u8 integers ([]const u8). It is impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length of this particular argument. Because it is an array that do not have a fixed size specified explicitly in the argument type annotation.\nSo, we know that this input argument will be an array of u8 integers. But we do not know at compile-time, its value, and neither its size. This information is known only at runtime, which is the period of time when you program is executed. As a consequence, the value of the expression input.len is also known only at runtime. This is an intrinsic characteristic of any function. Just remember that the value of function arguments is usually not “compile-time known”.\nHowever, as I mentioned earlier, what really matters to the compiler is to know the size of the object at compile-time, and not necessarily its value. So, although we don’t know the value of the object n, which is the result of the expression input.len, at compile-time, we do know its size. Because the expression input.len always returns a value of type usize, and the type usize has a known fixed size.\n\n\n3.1.2 Global data register\nThe global data register is a specific section of the executable of your Zig program, that is responsible for storing any value that is known at compile time.\nEvery constant object whose value is known at compile time that you declare in your source code, is stored in the global data register. Also, every literal value that you write in your source code, such as the string \"this is a string\", or the integer 10, or a boolean value such as true, is also stored in the global data register.\nHonestly, you don’t need to care much about this memory space. Because you can’t control it, you can’t deliberately access it or use it for your own purposes. Also, this memory space does not affect the logic of your program. It simply exists in your program.\n\n\n3.1.3 Stack vs Heap\nIf you are familiar with systems programming, or just low-level programming in general, you probably have heard of the “duel” between Stack vs Heap. These are two different types of memory, or different memory spaces, which are both available in Zig.\nThese two types of memory don’t actually duel with each other. This is a common mistake that beginners have, when seeing “x vs y” styles of tabloid headlines. These two types of memory are actually complementary to each other. So, in almost every Zig program that you ever write, you will likely use a combination of both. I will describe each memory space in detail over the next sections. But for now, I just want to stablish the main difference between these two types of memory.\nIn essence, the stack memory is normally used to store values whose length is fixed and known at compile time. In contrast, the heap memory is a dynamic type of memory space, meaning that, it is used to store values whose length might grow during the execution (runtime) of your program (Chen and Guo 2022).\nLengths that grow during runtime are intrinsically associated with “runtime known” type of values. In other words, if you have an object whose length might grow during runtime, then, the length of this object becomes not known at compile time. If the length is not known at compile-time, the value of this object also becomes not known at compile-time. These types of objects should be stored in the heap memory space, which is a dynamic memory space, which can grow or shrink to fit the size of your objects.\n\n\n3.1.4 Stack\nThe stack is a type of memory that uses the power of the stack data structure, hence the name. A “stack” is a type of data structure that uses a “last in, first out” (LIFO) mechanism to store the values you give it to. I imagine you are familiar with this data structure. But, if you are not, the Wikipedia page1 , or, the Geeks For Geeks page2 are both excellent and easy resources to fully understand how this data structure works.\nSo, the stack memory space is a type of memory that stores values using a stack data structure. It adds and removes values from the memory by following a “last in, first out” (LIFO) principle.\nEvery time you make a function call in Zig, an amount of space in the stack is reserved for this particular function call (Chen and Guo 2022; Zig Software Foundation 2024). The value of each function argument given to the function in this function call is stored in this stack space. Also, every local object that you declare inside the function scope is usually stored in this same stack space.\nLooking at the example below, the object result is a local object declared inside the scope of the add() function. Because of that, this object is stored inside the stack space reserved for the add() function. The r object (which is declared outside of the add() function scope) is also stored in the stack. But since it is declared in the “outer” scope, this object is stored in the stack space that belongs to this outer scope.\n\nfn add(x: u8, y: u8) u8 {\n    const result = x + y;\n    return result;\n}\n\npub fn main() !void {\n    const r = add(5, 27);\n    _ = r;\n}\n\nSo, any object that you declare inside the scope of a function is always stored inside the space that was reserved for that particular function in the stack memory. This also counts for any object declared inside the scope of your main() function for example. As you would expect, in this case, they are stored inside the stack space reserved for the main() function.\nOne very important detail about the stack memory is that it frees itself automatically. This is very important, remember that. When objects are stored in the stack memory, you don’t have the work (or the responsibility) of freeing/destroying these objects. Because they will be automatically destroyed once the stack space is freed at the end of the function scope.\nSo, once the function call returns (or ends, if you prefer to call it this way) the space that was reserved in the stack is destroyed, and all of the objects that were in that space goes away with it. This mechanism exists because this space, and the objects within it, are not necessary anymore, since the function “finished its business”. Using the add() function that we exposed above as an example, it means that the object result is automatically destroyed once the function returns.\n\n\n\n\n\n\nImportant\n\n\n\nLocal objects that are stored in the stack space of a function are automatically freed/destroyed at the end of the function scope.\n\n\nThis same logic applies to any other special structure in Zig that has its own scope by surrounding it with curly braces ({}). For loops, while loops, if else statements, etc. For example, if you declare any local object in the scope of a for loop, this local object is accessible only within the scope of this particular for loop. Because once the scope of this for loop ends, the space in the stack reserved for this for loop is freed. The example below demonstrates this idea.\n\n// This does not compile successfully!\nconst a = [_]u8{0, 1, 2, 3, 4};\nfor (0..a.len) |i| {\n    const index = i;\n    _ = index;\n}\n// Trying to use an object that was\n// declared in the for loop scope,\n// and that does not exist anymore.\nstd.debug.print(\"{d}\\n\", index);\n\nOne important consequence of this mechanism is that, once the function returns, you can no longer access any memory address that was inside the space in the stack reserved for this particular function. Because this space was destroyed. This means that, if this local object is stored in the stack, you cannot make a function that returns a pointer to this object.\nThink about that for a second. If all local objects in the stack are destroyed at the end of the function scope, why would you even consider returning a pointer to one of these objects? This pointer is at best, invalid, or, more likely, “undefined”.\nConclusion, it is totally fine to write a function that returns the local object itself as result, because then, you return the value of that object as the result. But, if this local object is stored in the stack, you should never write a function that returns a pointer to this local object. Because the memory address pointed by the pointer no longer exists.\nSo, using again the add() function as an example, if you rewrite this function so that it returns a pointer to the local object result, the zig compiler will actually compile your program, with no warnings or errors. At first glance, it looks that this is good code that works as expected. But this is a lie!\nIf you try to take a look at the value inside of the r object, or, if you try to use this r object in another expression or function call, then, you would have undefined behaviour, and major bugs in your program (Zig Software Foundation 2024, see “Lifetime and Ownership”3 and “Undefined Behaviour”4 sections).\n\nfn add(x: u8, y: u8) *const u8 {\n    const result = x + y;\n    return &result;\n}\n\npub fn main() !void {\n    // This code compiles successfully. But it has\n    // undefined behaviour. Never do this!!!\n    // The `r` object is undefined!\n    const r = add(5, 27); _ = r;\n}\n\nThis “invalid pointer to stack variable” problem is well known across many programming language communities. If you try to do the same thing, for example, in a C or C++ program (i.e. returning an address to a local object stored in the stack), you would also get undefined behaviour in the program.\n\n\n\n\n\n\nImportant\n\n\n\nIf a local object in your function is stored in the stack, you should never return a pointer to this local object from the function. Because this pointer will always become undefined after the function returns, since the stack space of the function is destroyed at the end of its scope.\n\n\nBut what if you really need to use this local object in some way after your function returns? How can you do this? The answer is: “in the same way you would do if this were a C or C++ program. By returning an address to an object stored in the heap”. The heap memory has a much more flexible lifecycle, and allows you to get a valid pointer to a local object of a function that already returned from its scope.\n\n\n3.1.5 Heap\nOne important limitation of the stack, is that, only objects whose length/size is known at compile-time can be stored in it. In contrast, the heap is a much more dynamic (and flexible) type of memory. It is the perfect type of memory to use for objects whose size/length might grow during the execution of your program.\nVirtually any application that behaves as a server is a classic use case of the heap. A HTTP server, a SSH server, a DNS server, a LSP server, … any type of server. In summary, a server is a type of application that runs for long periods of time, and that serves (or “deals with”) any incoming request that reaches this particular server.\nThe heap is a good choice for this type of system, mainly because the server does not know upfront how many requests it will receive from users, while it is active. It could be a single request, 5 thousand requests, or even zero requests. The server needs to have the ability to allocate and manage its memory according to how many requests it receives.\nAnother key difference between the stack and the heap, is that the heap is a type of memory that you, the programmer, have complete control over. This makes the heap a more flexible type of memory, but it also makes it harder to work with. Because you, the programmer, is responsible for managing everything related to it. Including where the memory is allocated, how much memory is allocated, and where this memory is freed.\n\nUnlike stack memory, heap memory is allocated explicitly by programmers and it won’t be deallocated until it is explicitly freed (Chen and Guo 2022).\n\nTo store an object in the heap, you, the programmer, needs to explicitly tells Zig to do so, by using an allocator to allocate some space in the heap. At Section 3.3, I will present how you can use allocators to allocate memory in Zig.\n\n\n\n\n\n\nImportant\n\n\n\nEvery memory you allocate in the heap needs to be explicitly freed by you, the programmer.\n\n\nThe majority of allocators in Zig do allocate memory on the heap. But some exceptions to this rule are ArenaAllocator() and FixedBufferAllocator(). The ArenaAllocator() is a special type of allocator that works in conjunction with a second type of allocator. On the other side, the FixedBufferAllocator() is an allocator that works based on buffer objects created on the stack. This means that the FixedBufferAllocator() makes allocations only on the stack.\n\n\n3.1.6 Summary\nAfter discussing all of these boring details, we can quickly recap what we learned. In summary, the Zig compiler will use the following rules to decide where each object you declare is stored:\n\nevery literal value (such as \"this is string\", 10, or true) is stored in the global data section.\nevery constant object (const) whose value is known at compile-time is also stored in the global data section.\nevery object (constant or not) whose length/size is known at compile time is stored in the stack space for the current scope.\nif an object is created with the method alloc() or create() of an allocator object, this object is stored in the memory space used by this particular allocator object. Most of allocators available in Zig use the heap memory, so, this object is likely stored in the heap (FixedBufferAllocator() is an exception to that).\nthe heap can only be accessed through allocators. If your object was not created through the alloc() or create() methods of an allocator object, then, it is most certainly not an object stored in the heap.",
     "crumbs": [
       "<span class='chapter-number'>3</span>  <span class='chapter-title'>Memory and Allocators</span>"
     ]
@@ -324,7 +324,7 @@
     "href": "Chapters/01-memory.html#sec-stack-overflow",
     "title": "3  Memory and Allocators",
     "section": "3.2 Stack overflows",
-    "text": "3.2 Stack overflows\nAllocating memory on the stack is generally faster than allocating it on the heap. But this better performance comes with many restrictions. We have already discussed many of these restrictions of the stack at Section 3.1.4. But there is one more important limitation that I want to talk about, which is the size of the stack itself.\nThe stack is limited in size. This size varies from computer to computer, and it depends on a lot of things (the computer architecture, the operating system, etc.). Nevertheless, this size is usually not that big. This is why we normally use the stack to store only temporary and small objects in memory.\nIn essence, if you try to make an allocation on the stack, that is so big that exceeds the stack size limit, a stack overflow happens, and your program just crashes as a result of that. In other words, a stack overflow happens when you attempt to use more space than is available on the stack.\nThis type of problem is very similar to a buffer overflow, i.e. you are trying to use more space than is available in the “buffer object”. However, a stack overflow always cause your program to crash, while a buffer overflow not always cause your program to crash (although it often does).\nYou can see an example of a stack overflow in the example below. We are trying to allocate a very big array of u64 values on the stack. You can see below that this program does not run succesfully, because it crashed with a “segmentation fault” error message.\n\nvar very_big_alloc: [1000 * 1000 * 24]u64 = undefined;\n@memset(very_big_alloc[0..], 0);\n\nSegmentation fault (core dumped)\nThis segmentation fault error is a result of the stack overflow that was caused by the big memory allocation made on the stack, to store the very_big_alloc object. This is why very big objects are usually stored on the heap, instead of the stack.",
+    "text": "3.2 Stack overflows\nAllocating memory on the stack is generally faster than allocating it on the heap. But this better performance comes with many restrictions. We have already discussed many of these restrictions of the stack at Section 3.1.4. But there is one more important limitation that I want to talk about, which is the size of the stack itself.\nThe stack is limited in size. This size varies from computer to computer, and it depends on a lot of things (the computer architecture, the operating system, etc.). Nevertheless, this size is usually not that big. This is why we normally use the stack to store only temporary and small objects in memory.\nIn essence, if you try to make an allocation on the stack, that is so big that exceeds the stack size limit, a stack overflow happens, and your program just crashes as a result of that. In other words, a stack overflow happens when you attempt to use more space than is available on the stack.\nThis type of problem is very similar to a buffer overflow, i.e. you are trying to use more space than is available in the “buffer object”. However, a stack overflow always causes your program to crash, while a buffer overflow does not always cause your program to crash (although it often does).\nYou can see an example of a stack overflow in the example below. We are trying to allocate a very big array of u64 values on the stack. You can see below that this program does not run successfully, because it crashed with a “segmentation fault” error message.\n\nvar very_big_alloc: [1000 * 1000 * 24]u64 = undefined;\n@memset(very_big_alloc[0..], 0);\n\nSegmentation fault (core dumped)\nThis segmentation fault error is a result of the stack overflow that was caused by the big memory allocation made on the stack, to store the very_big_alloc object. This is why very big objects are usually stored on the heap, instead of the stack.",
     "crumbs": [
       "<span class='chapter-number'>3</span>  <span class='chapter-title'>Memory and Allocators</span>"
     ]
@@ -334,7 +334,7 @@
     "href": "Chapters/01-memory.html#sec-allocators",
     "title": "3  Memory and Allocators",
     "section": "3.3 Allocators",
-    "text": "3.3 Allocators\nOne key aspect about Zig, is that there are “no hidden-memory allocations” in Zig. What that really means, is that “no allocations happen behind your back in the standard library” (Sobeston 2024).\nThis is a known problem, especially in C++. Because in C++, there are some operators that do allocate memory behind the scene, and there is no way for you to know that, until you actually read the source code of these operators, and find the memory allocation calls. Many programmers find this behaviour annoying and hard to keep track of.\nBut, in Zig, if a function, an operator, or anything from the standard library needs to allocate some memory during its execution, then, this function/operator needs to receive (as input) an allocator provided by the user, to actually be able to allocate the memory it needs.\nThis creates a clear distinction between functions that “do not” from those that “actually do” allocate memory. Just look at the arguments of this function. If a function, or operator, has an allocator object as one of its inputs/arguments, then, you know for sure that this function/operator will allocate some memory during its execution.\nAn example is the allocPrint() function from the Zig Standard Library. With this function, you can write a new string using format specifiers. So, this function is, for example, very similar to the function sprintf() in C. In order to write such new string, the allocPrint() function needs to allocate some memory to store the output string.\nThat is why, the first argument of this function is an allocator object that you, the user/programmer, gives as input to the function. In the example below, I am using the GeneralPurposeAllocator() as my allocator object. But I could easily use any other type of allocator object from the Zig Standard Library.\n\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst name = \"Pedro\";\nconst output = try std.fmt.allocPrint(\n    allocator,\n    \"Hello {s}!!!\",\n    .{name}\n);\ntry stdout.print(\"{s}\\n\", .{output});\n\nHello Pedro!!!\n\n\nYou get a lot of control over where and how much memory this function can allocate. Because it is you, the user/programmer, that provides the allocator for the function to use. This makes “total control” over memory management easier to achieve in Zig.\n\n3.3.1 What are allocators?\nAllocators in Zig are objects that you can use to allocate memory for your program. They are similar to the memory allocating functions in C, like malloc() and calloc(). So, if you need to use more memory than you initially have, during the execution of your program, you can simply ask for more memory by using an allocator object.\nZig offers different types of allocators, and they are usually available through the std.heap module of the standard library. Thus, just import the Zig Standard Library into your Zig module (with @import(\"std\")), and you can start using these allocators in your code.\nFurthermore, every allocator object is built on top of the Allocator interface in Zig. This means that, every allocator object you find in Zig must have the methods alloc(), create(), free() and destroy(). So, you can change the type of allocator you are using, but you don’t need to change the function calls to the methods that do the memory allocation (and the free memory operations) for your program.\n\n\n3.3.2 Why you need an allocator?\nAs we described at Section 3.1.4, everytime you make a function call in Zig, a space in the stack is reserved for this function call. But the stack has a key limitation which is: every object stored in the stack have a known fixed length.\nBut in reality, there are two very common instances where this “fixed length limitation” of the stack is a deal braker:\n\nthe objects that you create inside your function might grow in size during the execution of the function.\nsometimes, it is impossible to know upfront how many inputs you will receive, or how big this input will be.\n\nAlso, there is another instance where you might want to use an allocator, which is when you want to write a function that returns a pointer to a local object. As I described at Section 3.1.4, you cannot do that if this local object is stored in the stack. However, if this object is stored in the heap, then, you can return a pointer to this object at the end of the function. Because you (the programmer) control the lifetime of any heap memory that you allocate. You decide when this memory gets destroyed/freed.\nThese are common situations where the stack is not good for. That is why you need a different memory management strategy to store these objects inside your function. You need to use a memory type that can grow together with your objects, or that you can control the lifetime of this memory. The heap fits this description.\nAllocating memory on the heap is commonly known as dynamic memory management. As the objects you create grow in size during the execution of your program, you grow the amount of memory you have by allocating more memory in the heap to store these objects. And you do that in Zig, by using an allocator object.\n\n\n3.3.3 The different types of allocators\nAt the moment of the writing of this book, in Zig, we have 6 different allocators available in the standard library:\n\nGeneralPurposeAllocator().\npage_allocator().\nFixedBufferAllocator() and ThreadSafeFixedBufferAllocator().\nArenaAllocator().\nc_allocator() (requires you to link to libc).\n\nEach allocator has its own perks and limitations. All allocators, except FixedBufferAllocator() and ArenaAllocator(), are allocators that use the heap memory. So any memory that you allocate with these allocators, will be placed in the heap.\n\n\n3.3.4 General-purpose allocators\nThe GeneralPurposeAllocator(), as the name suggests, is a “general purpose” allocator. You can use it for every type of task. In the example below, I’m allocating enough space to store a single integer in the object some_number.\n\nconst std = @import(\"std\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const some_number = try allocator.create(u32);\n    defer allocator.destroy(some_number);\n\n    some_number.* = @as(u32, 45);\n}\n\nWhile useful, you might want to use the c_allocator(), which is a alias to the C standard allocator malloc(). So, yes, you can use malloc() in Zig if you want to. Just use the c_allocator() from the Zig standard library. However, if you do use c_allocator(), you must link to Libc when compiling your source code with the zig compiler, by including the flag -lc in your compilation process. If you do not link your source code to Libc, Zig will not be able to find the malloc() implementation in your system.\n\n\n3.3.5 Page allocator\nThe page_allocator() is an allocator that allocates full pages of memory in the heap. In other words, every time you allocate memory with page_allocator(), a full page of memory in the heap is allocated, instead of just a small piece of it.\nThe size of this page depends on the system you are using. Most systems use a page size of 4KB in the heap, so, that is the amount of memory that is normally allocated in each call by page_allocator(). That is why, page_allocator() is considered a fast, but also “wasteful” allocator in Zig. Because it allocates a big amount of memory in each call, and you most likely will not need that much memory in your program.\n\n\n3.3.6 Buffer allocators\nThe FixedBufferAllocator() and ThreadSafeFixedBufferAllocator() are allocator objects that work with a fixed sized buffer object at the back. In other words, they use a fixed sized buffer object as the basis for the memory. When you ask these allocator objects to allocate some memory for you, they are essentially reserving some amount of space inside this fixed sized buffer object for you to use.\nThis means that, in order to use these allocators, you must first create a buffer object in your code, and then, give this buffer object as an input to these allocators.\nThis also means that, these allocator objects can allocate memory both in the stack or in the heap. Everything depends on where the buffer object that you provide lives. If this buffer object lives in the stack, then, the memory allocated is “stack-based”. But if it lives on the heap, then, the memory allocated is “heap-based”.\nIn the example below, I’m creating a buffer object on the stack that is 10 elements long. Notice that I give this buffer object to the FixedBufferAllocator() constructor. Now, because this buffer object is 10 elements long, this means that I am limited to this space. I cannot allocate more than 10 elements with this allocator object. If I try to allocate more than that, the alloc() method will return an OutOfMemory error value.\n\nvar buffer: [10]u8 = undefined;\nfor (0..buffer.len) |i| {\n    buffer[i] = 0; // Initialize to zero\n}\n\nvar fba = std.heap.FixedBufferAllocator.init(&buffer);\nconst allocator = fba.allocator();\nconst input = try allocator.alloc(u8, 5);\ndefer allocator.free(input);\n\nRemember, the memory allocated by these allocator objects can be either from the stack, or, from the heap. It all depends on where the buffer object that you provide lives. In the above example, the buffer object lives in the stack, and, therefore, the memory allocated is based in the stack. But what if it was based on the heap?\nAs we described at Section 3.2, one of the main reasons why you would use the heap, instead of the stack, is to allocate huge amounts of space to store very big objects. Thus, let’s suppose you wanted to use a very big buffer object as the basis for your allocator objects. You would have to allocate this very big buffer object on the heap. The example below demonstrates this case.\n\nconst heap = std.heap.page_allocator;\nconst memory_buffer = try heap.alloc(\n    u8, 100 * 1024 * 1024 // 100 MB memory\n);\ndefer heap.free(memory_buffer);\nvar fba = std.heap.FixedBufferAllocator.init(\n    memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst input = try allocator.alloc(u8, 1000);\ndefer allocator.free(input);\n\n\n\n3.3.7 Arena allocator\nThe ArenaAllocator() is an allocator object that takes a child allocator as input. The idea behind the ArenaAllocator() in Zig is similar to the concept of “arenas” in the programming language Go5. It is an allocator object that allows you to allocate memory as many times you want, but free all memory only once. In other words, if you have, for example, called 5 times the method alloc() of an ArenaAllocator() object, you can free all the memory you allocated over these 5 calls at once, by simply calling the deinit() method of the same ArenaAllocator() object.\nIf you give, for example, a GeneralPurposeAllocator() object as input to the ArenaAllocator() constructor, like in the example below, then, the allocations you perform with alloc() will actually be made with the underlying object GeneralPurposeAllocator() that was passed. So, with an arena allocator, any new memory you ask for is allocated by the child allocator. The only thing that an arena allocator really does is help you to free all the memory you allocated multiple times with just a single command. In the example below, I called alloc() 3 times. So, if I did not use an arena allocator, then, I would need to call free() 3 times to free all the allocated memory.\n\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nvar aa = std.heap.ArenaAllocator.init(gpa.allocator());\ndefer aa.deinit();\nconst allocator = aa.allocator();\n\nconst in1 = try allocator.alloc(u8, 5);\nconst in2 = try allocator.alloc(u8, 10);\nconst in3 = try allocator.alloc(u8, 15);\n_ = in1; _ = in2; _ = in3;\n\n\n\n3.3.8 The alloc() and free() methods\nIn the code example below, we are accessing the stdin, which is the standard input channel, to receive an input from the user. We read the input given by the user with the readUntilDelimiterOrEof() method.\nNow, after reading the input of the user, we need to store this input somewhere in our program. That is why I use an allocator in this example. I use it to allocate some amount of memory to store this input given by the user. More specifically, the method alloc() of the allocator object is used to allocate an array capable of storing 50 u8 values.\nNotice that this alloc() method receives two inputs. The first one, is a type. This defines what type of values the allocated array will store. In the example below, we are allocating an array of unsigned 8-bit integers (u8). But you can create an array to store any type of value you want. Next, on the second argument, we define the size of the allocated array, by specifying how many elements this array will contain. In the case below, we are allocating an array of 50 elements.\nAt Section 1.8 we described that strings in Zig are simply arrays of characters. Each character is represented by a u8 value. So, this means that the array that was allocated in the object input is capable of storing a string that is 50-characters long.\nSo, in essence, the expression var input: [50]u8 = undefined would create an array for 50 u8 values in the stack of the current scope. But, you can allocate the same array in the heap by using the expression var input = try allocator.alloc(u8, 50).\n\nconst std = @import(\"std\");\nconst stdin = std.io.getStdIn();\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var input = try allocator.alloc(u8, 50);\n    defer allocator.free(input);\n    for (0..input.len) |i| {\n        input[i] = 0; // initialize all fields to zero.\n    }\n    // read user input\n    const input_reader = stdin.reader();\n    _ = try input_reader.readUntilDelimiterOrEof(\n        input,\n        '\\n'\n    );\n    std.debug.print(\"{s}\\n\", .{input});\n}\n\nAlso, notice that in this example, we use the defer keyword (which I described at Section 2.1.3) to run a small piece of code at the end of the current scope, which is the expression allocator.free(input). When you execute this expression, the allocator will free the memory that it allocated for the input object.\nWe have talked about this at Section 3.1.5. You should always explicitly free any memory that you allocate using an allocator! You do that by using the free() method of the same allocator object you used to allocate this memory. The defer keyword is used in this example only to help us execute this free operation at the end of the current scope.\n\n\n3.3.9 The create() and destroy() methods\nWith the alloc() and free() methods, you can allocate memory to store multiple elements at once. In other words, with these methods, we always allocate an array to store multiple elements at once. But what if you need enough space to store just a single item? Should you allocate an array of a single element through alloc()?\nThe answer is no! In this case, you should use the create() method of the allocator object. Every allocator object offers the create() and destroy() methods, which are used to allocate and free memory for a single item, respectively.\nSo, in essence, if you want to allocate memory to store an array of elements, you should use alloc() and free(). But if you need to store just a single item, then, the create() and destroy() methods are ideal for you.\nIn the example below, I’m defining a struct to represent an user of some sort. It could be an user for a game, or a software to manage resources, it doesn’t mater. Notice that I use the create() method this time, to store a single User object in the program. Also notice that I use the destroy() method to free the memory used by this object at the end of the scope.\n\nconst std = @import(\"std\");\nconst User = struct {\n    id: usize,\n    name: []const u8,\n\n    pub fn init(id: usize, name: []const u8) User {\n        return .{ .id = id, .name = name };\n    }\n};\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const user = try allocator.create(User);\n    defer allocator.destroy(user);\n\n    user.* = User.init(0, \"Pedro\");\n}\n\n\n\n\n\nChen, Jenny, and Ruohao Guo. 2022. “Stack and Heap Memory.” Introduction to Data Structures and Algorithms with C++. https://courses.engr.illinois.edu/cs225/fa2022/resources/stack-heap/.\n\n\nSobeston. 2024. “Zig Guide.” https://zig.guide/.\n\n\nZig Software Foundation. 2024. “Language Reference.” Zig Software Foundation. https://ziglang.org/documentation/master/.",
+    "text": "3.3 Allocators\nOne key aspect about Zig, is that there are “no hidden-memory allocations” in Zig. What that really means, is that “no allocations happen behind your back in the standard library” (Sobeston 2024).\nThis is a known problem, especially in C++. Because in C++, there are some operators that do allocate memory behind the scene, and there is no way for you to know that, until you actually read the source code of these operators, and find the memory allocation calls. Many programmers find this behaviour annoying and hard to keep track of.\nBut, in Zig, if a function, an operator, or anything from the standard library needs to allocate some memory during its execution, then, this function/operator needs to receive (as input) an allocator provided by the user, to actually be able to allocate the memory it needs.\nThis creates a clear distinction between functions that “do not” from those that “actually do” allocate memory. Just look at the arguments of this function. If a function, or operator, has an allocator object as one of its inputs/arguments, then, you know for sure that this function/operator will allocate some memory during its execution.\nAn example is the allocPrint() function from the Zig Standard Library. With this function, you can write a new string using format specifiers. So, this function is, for example, very similar to the function sprintf() in C. In order to write such a new string, the allocPrint() function needs to allocate some memory to store the output string.\nThat is why, the first argument of this function is an allocator object that you, the user/programmer, gives as input to the function. In the example below, I am using the GeneralPurposeAllocator() as my allocator object. But I could easily use any other type of allocator object from the Zig Standard Library.\n\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst name = \"Pedro\";\nconst output = try std.fmt.allocPrint(\n    allocator,\n    \"Hello {s}!!!\",\n    .{name}\n);\ntry stdout.print(\"{s}\\n\", .{output});\n\nHello Pedro!!!\n\n\nYou get a lot of control over where and how much memory this function can allocate. Because it is you, the user/programmer, that provides the allocator for the function to use. This makes “total control” over memory management easier to achieve in Zig.\n\n3.3.1 What are allocators?\nAllocators in Zig are objects that you can use to allocate memory for your program. They are similar to the memory allocating functions in C, like malloc() and calloc(). So, if you need to use more memory than you initially have, during the execution of your program, you can simply ask for more memory by using an allocator object.\nZig offers different types of allocators, and they are usually available through the std.heap module of the standard library. Thus, just import the Zig Standard Library into your Zig module (with @import(\"std\")), and you can start using these allocators in your code.\nFurthermore, every allocator object is built on top of the Allocator interface in Zig. This means that, every allocator object you find in Zig must have the methods alloc(), create(), free() and destroy(). So, you can change the type of allocator you are using, but you don’t need to change the function calls to the methods that do the memory allocation (and the free memory operations) for your program.\n\n\n3.3.2 Why you need an allocator?\nAs we described at Section 3.1.4, everytime you make a function call in Zig, a space in the stack is reserved for this function call. But the stack has a key limitation which is: every object stored in the stack has a known fixed length.\nBut in reality, there are two very common instances where this “fixed length limitation” of the stack is a deal braker:\n\nthe objects that you create inside your function might grow in size during the execution of the function.\nsometimes, it is impossible to know upfront how many inputs you will receive, or how big this input will be.\n\nAlso, there is another instance where you might want to use an allocator, which is when you want to write a function that returns a pointer to a local object. As I described at Section 3.1.4, you cannot do that if this local object is stored in the stack. However, if this object is stored in the heap, then, you can return a pointer to this object at the end of the function. Because you (the programmer) control the lifetime of any heap memory that you allocate. You decide when this memory gets destroyed/freed.\nThese are common situations for which the stack is not good. That is why you need a different memory management strategy to store these objects inside your function. You need to use a memory type that can grow together with your objects, or that you can control the lifetime of this memory. The heap fits this description.\nAllocating memory on the heap is commonly known as dynamic memory management. As the objects you create grow in size during the execution of your program, you grow the amount of memory you have by allocating more memory in the heap to store these objects. And you do that in Zig, by using an allocator object.\n\n\n3.3.3 The different types of allocators\nAt the moment of the writing of this book, in Zig, we have 6 different allocators available in the standard library:\n\nGeneralPurposeAllocator().\npage_allocator().\nFixedBufferAllocator() and ThreadSafeFixedBufferAllocator().\nArenaAllocator().\nc_allocator() (requires you to link to libc).\n\nEach allocator has its own perks and limitations. All allocators, except FixedBufferAllocator() and ArenaAllocator(), are allocators that use the heap memory. So any memory that you allocate with these allocators, will be placed in the heap.\n\n\n3.3.4 General-purpose allocators\nThe GeneralPurposeAllocator(), as the name suggests, is a “general purpose” allocator. You can use it for every type of task. In the example below, I’m allocating enough space to store a single integer in the object some_number.\n\nconst std = @import(\"std\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const some_number = try allocator.create(u32);\n    defer allocator.destroy(some_number);\n\n    some_number.* = @as(u32, 45);\n}\n\nWhile useful, you might want to use the c_allocator(), which is a alias to the C standard allocator malloc(). So, yes, you can use malloc() in Zig if you want to. Just use the c_allocator() from the Zig standard library. However, if you do use c_allocator(), you must link to Libc when compiling your source code with the zig compiler, by including the flag -lc in your compilation process. If you do not link your source code to Libc, Zig will not be able to find the malloc() implementation in your system.\n\n\n3.3.5 Page allocator\nThe page_allocator() is an allocator that allocates full pages of memory in the heap. In other words, every time you allocate memory with page_allocator(), a full page of memory in the heap is allocated, instead of just a small piece of it.\nThe size of this page depends on the system you are using. Most systems use a page size of 4KB in the heap, so, that is the amount of memory that is normally allocated in each call by page_allocator(). That is why, page_allocator() is considered a fast, but also “wasteful” allocator in Zig. Because it allocates a big amount of memory in each call, and you most likely will not need that much memory in your program.\n\n\n3.3.6 Buffer allocators\nThe FixedBufferAllocator() and ThreadSafeFixedBufferAllocator() are allocator objects that work with a fixed sized buffer object at the back. In other words, they use a fixed sized buffer object as the basis for the memory. When you ask these allocator objects to allocate some memory for you, they are essentially reserving some amount of space inside this fixed sized buffer object for you to use.\nThis means that, in order to use these allocators, you must first create a buffer object in your code, and then, give this buffer object as an input to these allocators.\nThis also means that, these allocator objects can allocate memory both in the stack or in the heap. Everything depends on where the buffer object that you provide lives. If this buffer object lives in the stack, then, the memory allocated is “stack-based”. But if it lives on the heap, then, the memory allocated is “heap-based”.\nIn the example below, I’m creating a buffer object on the stack that is 10 elements long. Notice that I give this buffer object to the FixedBufferAllocator() constructor. Now, because this buffer object is 10 elements long, this means that I am limited to this space. I cannot allocate more than 10 elements with this allocator object. If I try to allocate more than that, the alloc() method will return an OutOfMemory error value.\n\nvar buffer: [10]u8 = undefined;\nfor (0..buffer.len) |i| {\n    buffer[i] = 0; // Initialize to zero\n}\n\nvar fba = std.heap.FixedBufferAllocator.init(&buffer);\nconst allocator = fba.allocator();\nconst input = try allocator.alloc(u8, 5);\ndefer allocator.free(input);\n\nRemember, the memory allocated by these allocator objects can be either from the stack, or, from the heap. It all depends on where the buffer object that you provide lives. In the above example, the buffer object lives in the stack, and, therefore, the memory allocated is based in the stack. But what if it was based on the heap?\nAs we described at Section 3.2, one of the main reasons why you would use the heap, instead of the stack, is to allocate huge amounts of space to store very big objects. Thus, let’s suppose you wanted to use a very big buffer object as the basis for your allocator objects. You would have to allocate this very big buffer object on the heap. The example below demonstrates this case.\n\nconst heap = std.heap.page_allocator;\nconst memory_buffer = try heap.alloc(\n    u8, 100 * 1024 * 1024 // 100 MB memory\n);\ndefer heap.free(memory_buffer);\nvar fba = std.heap.FixedBufferAllocator.init(\n    memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst input = try allocator.alloc(u8, 1000);\ndefer allocator.free(input);\n\n\n\n3.3.7 Arena allocator\nThe ArenaAllocator() is an allocator object that takes a child allocator as input. The idea behind the ArenaAllocator() in Zig is similar to the concept of “arenas” in the programming language Go5. It is an allocator object that allows you to allocate memory as many times you want, but free all memory only once. In other words, if you have, for example, called 5 times the method alloc() of an ArenaAllocator() object, you can free all the memory you allocated over these 5 calls at once, by simply calling the deinit() method of the same ArenaAllocator() object.\nIf you give, for example, a GeneralPurposeAllocator() object as input to the ArenaAllocator() constructor, like in the example below, then, the allocations you perform with alloc() will actually be made with the underlying object GeneralPurposeAllocator() that was passed. So, with an arena allocator, any new memory you ask for is allocated by the child allocator. The only thing that an arena allocator really does is help you to free all the memory you allocated multiple times with just a single command. In the example below, I called alloc() 3 times. So, if I did not use an arena allocator, then, I would need to call free() 3 times to free all the allocated memory.\n\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nvar aa = std.heap.ArenaAllocator.init(gpa.allocator());\ndefer aa.deinit();\nconst allocator = aa.allocator();\n\nconst in1 = try allocator.alloc(u8, 5);\nconst in2 = try allocator.alloc(u8, 10);\nconst in3 = try allocator.alloc(u8, 15);\n_ = in1; _ = in2; _ = in3;\n\n\n\n3.3.8 The alloc() and free() methods\nIn the code example below, we are accessing the stdin, which is the standard input channel, to receive an input from the user. We read the input given by the user with the readUntilDelimiterOrEof() method.\nNow, after reading the input of the user, we need to store this input somewhere in our program. That is why I use an allocator in this example. I use it to allocate some amount of memory to store this input given by the user. More specifically, the method alloc() of the allocator object is used to allocate an array capable of storing 50 u8 values.\nNotice that this alloc() method receives two inputs. The first one, is a type. This defines what type of values the allocated array will store. In the example below, we are allocating an array of unsigned 8-bit integers (u8). But you can create an array to store any type of value you want. Next, on the second argument, we define the size of the allocated array, by specifying how many elements this array will contain. In the case below, we are allocating an array of 50 elements.\nAt Section 1.8 we described that strings in Zig are simply arrays of characters. Each character is represented by a u8 value. So, this means that the array that was allocated in the object input is capable of storing a string that is 50-characters long.\nSo, in essence, the expression var input: [50]u8 = undefined would create an array for 50 u8 values in the stack of the current scope. But, you can allocate the same array in the heap by using the expression var input = try allocator.alloc(u8, 50).\n\nconst std = @import(\"std\");\nconst stdin = std.io.getStdIn();\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var input = try allocator.alloc(u8, 50);\n    defer allocator.free(input);\n    for (0..input.len) |i| {\n        input[i] = 0; // initialize all fields to zero.\n    }\n    // read user input\n    const input_reader = stdin.reader();\n    _ = try input_reader.readUntilDelimiterOrEof(\n        input,\n        '\\n'\n    );\n    std.debug.print(\"{s}\\n\", .{input});\n}\n\nAlso, notice that in this example, we use the defer keyword (which I described at Section 2.1.3) to run a small piece of code at the end of the current scope, which is the expression allocator.free(input). When you execute this expression, the allocator will free the memory that it allocated for the input object.\nWe have talked about this at Section 3.1.5. You should always explicitly free any memory that you allocate using an allocator! You do that by using the free() method of the same allocator object you used to allocate this memory. The defer keyword is used in this example only to help us execute this free operation at the end of the current scope.\n\n\n3.3.9 The create() and destroy() methods\nWith the alloc() and free() methods, you can allocate memory to store multiple elements at once. In other words, with these methods, we always allocate an array to store multiple elements at once. But what if you need enough space to store just a single item? Should you allocate an array of a single element through alloc()?\nThe answer is no! In this case, you should use the create() method of the allocator object. Every allocator object offers the create() and destroy() methods, which are used to allocate and free memory for a single item, respectively.\nSo, in essence, if you want to allocate memory to store an array of elements, you should use alloc() and free(). But if you need to store just a single item, then, the create() and destroy() methods are ideal for you.\nIn the example below, I’m defining a struct to represent an user of some sort. It could be a user for a game, or software to manage resources, it doesn’t mater. Notice that I use the create() method this time, to store a single User object in the program. Also notice that I use the destroy() method to free the memory used by this object at the end of the scope.\n\nconst std = @import(\"std\");\nconst User = struct {\n    id: usize,\n    name: []const u8,\n\n    pub fn init(id: usize, name: []const u8) User {\n        return .{ .id = id, .name = name };\n    }\n};\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const user = try allocator.create(User);\n    defer allocator.destroy(user);\n\n    user.* = User.init(0, \"Pedro\");\n}\n\n\n\n\n\nChen, Jenny, and Ruohao Guo. 2022. “Stack and Heap Memory.” Introduction to Data Structures and Algorithms with C++. https://courses.engr.illinois.edu/cs225/fa2022/resources/stack-heap/.\n\n\nSobeston. 2024. “Zig Guide.” https://zig.guide/.\n\n\nZig Software Foundation. 2024. “Language Reference.” Zig Software Foundation. https://ziglang.org/documentation/master/.",
     "crumbs": [
       "<span class='chapter-number'>3</span>  <span class='chapter-title'>Memory and Allocators</span>"
     ]
@@ -434,7 +434,7 @@
     "href": "Chapters/02-debugging.html",
     "title": "5  Debugging Zig applications",
     "section": "",
-    "text": "5.1 Print debugging\nWe begin with the classic and battle-tested print debugging strategy. The key advantage that debugging offers you is visibility. With print statements you can easily see what results and objects are being produced by your application.\nThat is the essence of print debugging. Is to use print expressions to see the values that are being generated by your program, and, as a result, get a much better understanding of how your program is behaving.\nMany programmers often resort to the print functions in Zig, such as the stdout.print(), or, the std.debug.print(), to get a better understanding of their programs. This is a known and old strategy that is very simple and effective, and it is better known within the programming community as print debugging. In Zig, you can print information to the stdout or stderr streams of your system.\nLet’s begin with stdout. First, you need to get access to the stdout, by calling the getStdOut() method, from the Zig Standard Library. This method returns a file descriptor object, and, through this object you can read/write to the stdout. I recommend you to check out all methods available in this object, by checking the page in the Zig Standard Library Official Reference for the type File1.\nFor our purpose here, which is to write something to the stdout, especially to debug our program, I recommend you to use the writer() method, which gives your a writer object. This writer object offers some helper methods to write stuff into the file descriptor object that represents the stdout stream. In special, the print() method.\nThe print() method from this writer object is a “print formatter” type of a function. In other words, this method works exactly like the printf() function from C, or, like println!() from Rust. In the first argument of the function, you specify a template string, and, in the second argument, you provide a list of values (or objects) that you want to insert into your template message.\nIdeally, the template string in the first argument should contain some format specifier. Each format specifier is matched to a value (or object) that you have listed in the second argument. So, if you provided 5 different objects in the second argument, then, the template string should contain 5 format specifiers, one for each object provided.\nEach format specifier is represented by a single letter, and you provide this format specifier inside a pair of curly braces. So, if you want to format your object using the string specifier (s), then, you can insert the text {s} in your template string. Here is a quick list of the most used format specifiers:\nThe code example below gives you an example of use of this print() method with the d format specifier.\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    _ = try stdout.print(\"Result: {d}\", .{result});\n}\n\nResult: 50\nIs important to emphasize that, the stdout.print() method, as you would expect, print your template string into the stdout stream of your system. However, you can also print your template string into the stderr stream if your prefer. All you need to do, is to replace the stdout.print() call with the function std.debug.print(). Like this:\nconst std = @import(\"std\");\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    std.debug.print(\"Result: {d}\\n\", .{result});\n}\n\nResult: 50\nYou could also achieve the exact same result by getting a file descriptor object to stderr, then, creating a writer object to stderr, then, using the print() method of this writer object, like in the example below:\nconst std = @import(\"std\");\nconst stderr = std.io.getStdErr().writer();\n// some more lines ...\n_ = try stderr.print(\"Result: {d}\", .{result});",
+    "text": "5.1 Print debugging\nWe begin with the classic and battle-tested print debugging strategy. The key advantage that debugging offers you is visibility. With print statements you can easily see what results and objects are being produced by your application.\nThat is the essence of print debugging. Is to use print expressions to see the values that are being generated by your program, and, as a result, get a much better understanding of how your program is behaving.\nMany programmers often resort to the print functions in Zig, such as the stdout.print(), or, the std.debug.print(), to get a better understanding of their programs. This is a known and old strategy that is very simple and effective, and it is better known within the programming community as print debugging. In Zig, you can print information to the stdout or stderr streams of your system.\nLet’s begin with stdout. First, you need to get access to the stdout, by calling the getStdOut() method, from the Zig Standard Library. This method returns a file descriptor object, and, through this object you can read/write to the stdout. I recommend you to check out all methods available in this object, by checking the page in the Zig Standard Library Official Reference for the type File1.\nFor our purpose here, which is to write something to the stdout, especially to debug our program, I recommend you to use the writer() method, which gives you a writer object. This writer object offers some helper methods to write stuff into the file descriptor object that represents the stdout stream. In special, the print() method.\nThe print() method from this writer object is a “print formatter” type of a function. In other words, this method works exactly like the printf() function from C, or, like println!() from Rust. In the first argument of the function, you specify a template string, and, in the second argument, you provide a list of values (or objects) that you want to insert into your template message.\nIdeally, the template string in the first argument should contain some format specifier. Each format specifier is matched to a value (or object) that you have listed in the second argument. So, if you provided 5 different objects in the second argument, then, the template string should contain 5 format specifiers, one for each object provided.\nEach format specifier is represented by a single letter, and you provide this format specifier inside a pair of curly braces. So, if you want to format your object using the string specifier (s), then, you can insert the text {s} in your template string. Here is a quick list of the most used format specifiers:\nThe code example below gives you an example of use of this print() method with the d format specifier.\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    _ = try stdout.print(\"Result: {d}\", .{result});\n}\n\nResult: 50\nIt is important to emphasize that, the stdout.print() method, as you would expect, prints your template string into the stdout stream of your system. However, you can also print your template string into the stderr stream if your prefer. All you need to do, is to replace the stdout.print() call with the function std.debug.print(). Like this:\nconst std = @import(\"std\");\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    std.debug.print(\"Result: {d}\\n\", .{result});\n}\n\nResult: 50\nYou could also achieve the exact same result by getting a file descriptor object to stderr, then, creating a writer object to stderr, then, using the print() method of this writer object, like in the example below:\nconst std = @import(\"std\");\nconst stderr = std.io.getStdErr().writer();\n// some more lines ...\n_ = try stderr.print(\"Result: {d}\", .{result});",
     "crumbs": [
       "<span class='chapter-number'>5</span>  <span class='chapter-title'>Debugging Zig applications</span>"
     ]
@@ -454,7 +454,7 @@
     "href": "Chapters/02-debugging.html#debugging-through-debuggers",
     "title": "5  Debugging Zig applications",
     "section": "5.2 Debugging through debuggers",
-    "text": "5.2 Debugging through debuggers\nAlthough print debugging being a valid and very useful strategy, most programmers prefer to use a debugger to debug their programs. Since Zig is a low-level language, you can use either GDB (GNU Debugger), or LLDB (LLVM Project Debugger) as your debugger.\nBoth debuggers can work with Zig code, and it’s a matter of taste here. You choose the debugger of your preference, and you work with it. In this book, I will use LLDB as my debugger on the examples.\n\n5.2.1 Compile your source code in debug mode\nIn order to debug your program through a debugger, you must compile your source code in Debug mode. Because when you compile your source code in other modes (such as Release), the compiler usually strips out some essential information that is used by the debugger to read and track your program, like PDB (Program Database) files.\nBy compiling your source code in Debug mode, you ensure that the debugger will find the necessary information in your program to debug it. By default, the compiler uses the Debug mode when compiling your code. Having this in mind, when you compile your program with the build-exe command (which was described at Section 1.2.4), if you don’t specify an explicit mode through the -O command-line 2 argument, then, the compiler will compile your code in Debug mode.\n\n\n5.2.2 Let’s debug a program\nAs an example, let’s use LLDB to navigate and investigate the following piece of Zig code:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\nfn add_and_increment(a: u8, b: u8) u8 {\n    const sum = a + b;\n    const incremented = sum + 1;\n    return incremented;\n}\n\npub fn main() !void {\n    var n = add_and_increment(2, 3);\n    n = add_and_increment(n, n);\n    _ = try stdout.print(\"Result: {d}!\\n\", .{n});\n}\n\nResult: 13!\n\n\nThere is nothing wrong with this program. But it is a good start for us. First, we need to compile this program with the zig build-exe command. For this example, suppose that I have compiled the above Zig code into a binary executable called add_program.\nzig build-exe add_program.zig\nNow, we can start LLDB with add_program, like this:\nlldb add_program\nFrom now on, LLDB is started, and you can know that I’m executing LLDB commands by looking at the prefix (lldb). If something is prefixed with (lldb), then you know that it is a LLDB command.\nThe first thing I will do, is to set a breakpoint at the main() function, by executing b main. After that, I just start the execution of the program with run. You can see in the output below, that the execution stopped at the first line in the function main(), as we expected.\n(lldb) b main\nBreakpoint 1: where = debugging`debug1.main + 22\n    at debug1.zig:11:30, address = 0x00000000010341a6\n(lldb) run\nProcess 8654 launched: 'add_program' (x86_64)\nProcess 8654 stopped\n* thread #1, name = 'add_program',\n    stop reason = breakpoint 1.1 frame #0: 0x10341a6\n    add_program`debug1.main at add_program.zig:11:30\n   8    }\n   9    \n   10   pub fn main() !void {\n-&gt; 11       var n = add_and_increment(2, 3);\n   12       n = add_and_increment(n, n);\n   13       try stdout.print(\"Result: {d}!\\n\", .{n});\n   14   }\nI can start navigating through the code, and checking the objects that are being generated. If you are not familiar with the commands available in LLDB, I recommend you to read the official documentation of the project3. You can also look for cheat sheets, which quickly describes all commands available for you4.\nCurrently, we are in the first line at the main() function. In this line, we create the n object, by executing the add_and_increment() function. To execute the current line of code, and go to the next line, we can run the n LLDB command. Let’s execute this command.\nAfter we executed this line, we can also look at the value stored inside this n object by using the p LLDB command. The syntax for this command is p &lt;name-of-object&gt;.\nIf we take a look at the value stored in the n object (p n), notice that it stores the hexadecimal value 0x06, which is the number 6 in decimal. We can also see that, this value have a type unsigned char, which is an unsigned 8-bit integer. We have talked already about this at Section 1.8, that u8 integers in Zig are equivalent to the C data type unsigned char.\n(lldb) n\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step over frame #0: 0x10341ae\n    debugging`debug1.main at debug1.zig:12:26\n   9    \n   10   pub fn main() !void {\n   11       var n = add_and_increment(2, 3);\n-&gt; 12       n = add_and_increment(n, n);\n   13       try stdout.print(\"Result: {d}!\\n\", .{n});\n   14   }\n(lldb) p n\n(unsigned char) $1 = '\\x06'\nNow, on the next line of code, we are executing the add_and_increment() function once again. Why not step inside this function? Shall we? We can do that, by executing the s LLDB command. Notice in the example below that, after executing this command, we have entered into the context of the add_and_increment() function.\nAlso notice in the example below that, I have walked two more lines in the function’s body, then, I execute the frame variable LLDB command, to see at once, the value stored in each of the variables that were created inside the current scope.\nYou can see in the output below that, the object sum stores the value \\f, which represents the form feed character. This character in the ASCII table, corresponds to the hexadecimal value 0x0C, or, in decimal, the number 12. So, this means that the result of the expression a + b executed at line 5, resulted in the number 12.\n(lldb) s\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step in frame #0: 0x10342de\n    debugging`debug1.add_and_increment(a='\\x02', b='\\x03')\n    at debug1.zig:4:39\n-&gt; 4    fn add_and_increment(a: u8, b: u8) u8 {\n   5        const sum = a + b;\n   6        const incremented = sum + 1;\n   7        return incremented;\n(lldb) n\n(lldb) n\n(lldb) frame variable\n(unsigned char) a = '\\x06'\n(unsigned char) b = '\\x06'\n(unsigned char) sum = '\\f'\n(unsigned char) incremented = '\\x06'",
+    "text": "5.2 Debugging through debuggers\nAlthough print debugging is a valid and very useful strategy, most programmers prefer to use a debugger to debug their programs. Since Zig is a low-level language, you can use either GDB (GNU Debugger), or LLDB (LLVM Project Debugger) as your debugger.\nBoth debuggers can work with Zig code, and it’s a matter of taste here. You choose the debugger of your preference, and you work with it. In this book, I will use LLDB as my debugger on the examples.\n\n5.2.1 Compile your source code in debug mode\nIn order to debug your program through a debugger, you must compile your source code in Debug mode. Because when you compile your source code in other modes (such as Release), the compiler usually strips out some essential information that is used by the debugger to read and track your program, like PDB (Program Database) files.\nBy compiling your source code in Debug mode, you ensure that the debugger will find the necessary information in your program to debug it. By default, the compiler uses the Debug mode when compiling your code. Having this in mind, when you compile your program with the build-exe command (which was described at Section 1.2.4), if you don’t specify an explicit mode through the -O command-line 2 argument, then, the compiler will compile your code in Debug mode.\n\n\n5.2.2 Let’s debug a program\nAs an example, let’s use LLDB to navigate and investigate the following piece of Zig code:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\nfn add_and_increment(a: u8, b: u8) u8 {\n    const sum = a + b;\n    const incremented = sum + 1;\n    return incremented;\n}\n\npub fn main() !void {\n    var n = add_and_increment(2, 3);\n    n = add_and_increment(n, n);\n    _ = try stdout.print(\"Result: {d}!\\n\", .{n});\n}\n\nResult: 13!\n\n\nThere is nothing wrong with this program. But it is a good start for us. First, we need to compile this program with the zig build-exe command. For this example, suppose that I have compiled the above Zig code into a binary executable called add_program.\nzig build-exe add_program.zig\nNow, we can start LLDB with add_program, like this:\nlldb add_program\nFrom now on, LLDB is started, and you can know that I’m executing LLDB commands by looking at the prefix (lldb). If something is prefixed with (lldb), then you know that it is a LLDB command.\nThe first thing I will do, is to set a breakpoint at the main() function, by executing b main. After that, I just start the execution of the program with run. You can see in the output below, that the execution stopped at the first line in the function main(), as we expected.\n(lldb) b main\nBreakpoint 1: where = debugging`debug1.main + 22\n    at debug1.zig:11:30, address = 0x00000000010341a6\n(lldb) run\nProcess 8654 launched: 'add_program' (x86_64)\nProcess 8654 stopped\n* thread #1, name = 'add_program',\n    stop reason = breakpoint 1.1 frame #0: 0x10341a6\n    add_program`debug1.main at add_program.zig:11:30\n   8    }\n   9    \n   10   pub fn main() !void {\n-&gt; 11       var n = add_and_increment(2, 3);\n   12       n = add_and_increment(n, n);\n   13       try stdout.print(\"Result: {d}!\\n\", .{n});\n   14   }\nI can start navigating through the code, and checking the objects that are being generated. If you are not familiar with the commands available in LLDB, I recommend you to read the official documentation of the project3. You can also look for cheat sheets, which quickly describes all commands available for you4.\nCurrently, we are in the first line at the main() function. In this line, we create the n object, by executing the add_and_increment() function. To execute the current line of code, and go to the next line, we can run the n LLDB command. Let’s execute this command.\nAfter we executed this line, we can also look at the value stored inside this n object by using the p LLDB command. The syntax for this command is p &lt;name-of-object&gt;.\nIf we take a look at the value stored in the n object (p n), notice that it stores the hexadecimal value 0x06, which is the number 6 in decimal. We can also see that this value has a type of unsigned char, which is an unsigned 8-bit integer. We have talked already about this at Section 1.8, that u8 integers in Zig are equivalent to the C data type unsigned char.\n(lldb) n\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step over frame #0: 0x10341ae\n    debugging`debug1.main at debug1.zig:12:26\n   9    \n   10   pub fn main() !void {\n   11       var n = add_and_increment(2, 3);\n-&gt; 12       n = add_and_increment(n, n);\n   13       try stdout.print(\"Result: {d}!\\n\", .{n});\n   14   }\n(lldb) p n\n(unsigned char) $1 = '\\x06'\nNow, on the next line of code, we are executing the add_and_increment() function once again. Why not step inside this function? Shall we? We can do that, by executing the s LLDB command. Notice in the example below that, after executing this command, we have entered into the context of the add_and_increment() function.\nAlso notice in the example below that, I have walked two more lines in the function’s body, then, I execute the frame variable LLDB command, to see at once, the value stored in each of the variables that were created inside the current scope.\nYou can see in the output below that, the object sum stores the value \\f, which represents the form feed character. This character in the ASCII table, corresponds to the hexadecimal value 0x0C, or, in decimal, the number 12. So, this means that the result of the expression a + b executed at line 5, resulted in the number 12.\n(lldb) s\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step in frame #0: 0x10342de\n    debugging`debug1.add_and_increment(a='\\x02', b='\\x03')\n    at debug1.zig:4:39\n-&gt; 4    fn add_and_increment(a: u8, b: u8) u8 {\n   5        const sum = a + b;\n   6        const incremented = sum + 1;\n   7        return incremented;\n(lldb) n\n(lldb) n\n(lldb) frame variable\n(unsigned char) a = '\\x06'\n(unsigned char) b = '\\x06'\n(unsigned char) sum = '\\f'\n(unsigned char) incremented = '\\x06'",
     "crumbs": [
       "<span class='chapter-number'>5</span>  <span class='chapter-title'>Debugging Zig applications</span>"
     ]

From dd977a769ebef9654cbf03df4df72178ba5f88e2 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sun, 9 Feb 2025 11:18:52 -0300
Subject: [PATCH 061/151] Recompile book with changes

---
 .../01-base64/execute-results/html.json         |  8 +++++---
 .../01-memory/execute-results/html.json         |  8 +++++---
 .../02-debugging/execute-results/html.json      |  4 ++--
 docs/Chapters/01-base64.html                    | 17 ++++++++---------
 docs/Chapters/01-memory.html                    |  2 +-
 docs/Chapters/02-debugging.html                 | 10 +++++-----
 docs/index.html                                 |  4 ++--
 docs/search.json                                | 10 +++++-----
 8 files changed, 33 insertions(+), 30 deletions(-)

diff --git a/_freeze/Chapters/01-base64/execute-results/html.json b/_freeze/Chapters/01-base64/execute-results/html.json
index 74060eb2..0965e634 100644
--- a/_freeze/Chapters/01-base64/execute-results/html.json
+++ b/_freeze/Chapters/01-base64/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "7e395d899a89c8cedf16f71d8a8f8835",
+  "hash": "225506bc4affdcc5aaf897c63caf73a4",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 1 - Building a base64 encoder/decoder {#sec-base64}\n\nAs our first small project, I want to implement a base64 encoder/decoder with you.\nBase64 is an encoding system which translates binary data to text.\nA big chunk of the web uses base64 to deliver binary data to systems\nthat can only read text data.\n\nThe most common example of a modern use case for base64 is essentially any email system,\nlike GMail, Outlook, etc. Because email systems normally use\nthe Simple Mail Transfer Protocol (SMTP), which is a web protocol\nthat supports only text data. So, if you need, for any reason, to\nsend a binary file (like for example, a PDF, or an Excel file) as\nan attachment in your email, these binary files are normally\nconverted to base64, before they are included in the SMTP message.\nSo, the base64 encoding is largely used in these email systems to include\nbinary data into the SMTP message.\n\n\n\n\n\n\n## How the base64 algorithm work?\n\nBut how exactly does the algorithm behind the base64 encoding work? Let's discuss that. First, I will\nexplain the base64 scale, which is the 64-character scale that is the basis for\nthe base64 encoding system.\n\nAfter that, I explain the algorithm behind a base64 encoder, which is the part of the algorithm that is responsible for encoding messages\ninto the base64 encoding system. Then, after that, I explain the algorithm behind a base64 decoder, which is\nthe part of the algorithm that is responsible for translating base64 messages back into their original meaning.\n\nIf you are unsure about the differences between an \"encoder\" and a \"decoder\",\ntake a look at @sec-encode-vs-decode.\n\n\n### The base64 scale {#sec-base64-scale}\n\nThe base64 encoding system is based on a scale that goes from 0 to 63 (hence the name).\nEach index in this scale is represented by a character (it is a scale of 64 characters).\nSo, in order to convert some binary data, to the base64 encoding, we need to convert each binary number to the corresponding\ncharacter in this \"scale of 64 characters\".\n\nThe base64 scale starts with all ASCII uppercase letters (A to Z) which represents\nthe first 25 indexes in this scale (0 to 25). After that, we have all ASCII lowercase letters\n(a to z), which represents the range 26 to 51 in the scale. After that, we\nhave the one digit numbers (0 to 9), which represents the indexes from 52 to 61 in the scale.\nFinally, the last two indexes in the scale (62 and 63) are represented by the characters `+` and `/`,\nrespectively.\n\nThese are the 64 characters that compose the base64 scale. The equal sign character (`=`) is not part of the scale itself,\nbut it is a special character in the base64 encoding system. This character is used solely as a suffix, to mark the end of the character sequence,\nor, to mark the end of meaningful characters in the sequence.\n\nThe bullet points below summarises the base64 scale:\n\n- range 0 to 25 is represented by: ASCII uppercase letters `-> [A-Z]`;\n- range 26 to 51 is represented by: ASCII lowercase letters `-> [a-z]`;\n- range 52 to 61 is represented by: one digit numbers `-> [0-9]`;\n- index 62 and 63 are represented by the characters `+` and `/`, respectively;\n- the character `=` represents the end of meaningful characters in the sequence;\n\n\n\n\n### Creating the scale as a lookup table {#sec-base64-table}\n\nThe best way to represent this scale in code, is to represent it as a *lookup table*.\nLookup tables are a classic strategy in computer science to speed up calculations. The basic idea\nis to replace a runtime calculation (which can take a long time to be done) with a basic array indexing\noperation.\n\nInstead of calculating the results everytime you need them, you calculate all possible results at once, and then, you store them in an array\n(which behaves lake a \"table\"). Then, every time you need to use one of the characters in the base64 scale, instead of\nusing many resources to calculate the exact character to be used, you simply retrieve this character\nfrom the array where you stored all the possible characters in the base64 scale.\nWe retrieve the character that we need directly from memory.\n\nWe can start building a Zig struct to store our base64 decoder/encoder logic.\nWe start with the `Base64` struct below. For now, we only have one single data member in this\nstruct, i.e. the member `_table`, which represents our lookup table. We also have an `init()` method,\nto create a new instance of a `Base64` object, and, a `_char_at()` method, which is a\n\"get character at index $x$\" type of function.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Base64 = struct {\n    _table: *const [64]u8,\n\n    pub fn init() Base64 {\n        const upper = \"ABCDEFGHIJKLMNOPQRSTUVWXYZ\";\n        const lower = \"abcdefghijklmnopqrstuvwxyz\";\n        const numbers_symb = \"0123456789+/\";\n        return Base64{\n            ._table = upper ++ lower ++ numbers_symb,\n        };\n    }\n\n    pub fn _char_at(self: Base64, index: u8) u8 {\n        return self._table[index];\n    }\n};\n```\n:::\n\n\n\n\n\nIn other words, the `_char_at()` method is responsible for getting the character in the lookup\ntable (i.e. the `_table` struct data member) that corresponds to a particular index in the\n\"base64 scale\". So, in the example below, we know that the character that corresponds to the\nindex 28 in the \"base64 scale\" is the character \"c\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst base64 = Base64.init();\ntry stdout.print(\n    \"Character at index 28: {c}\\n\",\n    .{base64._char_at(28)}\n);\n```\n:::\n\n\n\n\n```\nCharacter at index 28: c\n```\n\n\n\n### A base64 encoder {#sec-base64-encoder-algo}\n\nThe algorithm behind a base64 encoder usually works on a window of 3 bytes. Because each byte has\n8 bits, so, 3 bytes forms a set of $8 \\times 3 = 24$ bits. This is desirable for the base64 algorithm, because\n24 bits is divisible by 6, which forms $24 / 6 = 4$ groups of 6 bits each.\n\nTherefore, the base64 algorithm works by converting 3 bytes at a time\ninto 4 characters from the base64 scale. It keeps iterating through the input string,\n3 bytes at a time, and converting them into the base64 scale, producing 4 characters\nper iteration. It keeps iterating, and producing these \"new characters\"\nuntil it hits the end of the input string.\n\nNow, you may think, what if you have a particular string that have a number of bytes\nthat is not divisible by 3? What happens? For example, if you have a string\nthat contains only two characters/bytes, such as \"Hi\". How the\nalgorithm would behave in such situation? You find the answer at @fig-base64-algo1.\nYou can see at @fig-base64-algo1 that the string \"Hi\", when converted to base64,\nbecomes the string \"SGk=\":\n\n![The logic behind a base64 encoder](./../Figures/base64-encoder-flow.png){#fig-base64-algo1}\n\nTaking the string \"Hi\" as an example, we have 2 bytes, or, 16 bits in total. So, we lack a full byte (8 bits)\nto complete the window of 24 bits that the base64 algorithm likes to work on. The first thing that\nthe algorithm does, is to check how to divide the input bytes into groups of 6 bits.\n\nIf the algorithm notices that there is a group of 6 bits that, have some bits in it, but, at the same time, it is not full\n(in other words, $0 < nbits < 6$, being $nbits$ the number of bits), meaning that, it lacks\nsome bits to fill the 6-bits requirement, the algorithm simply add extra zeros in this group\nto fill the space that it needs. That is why at @fig-base64-algo1, on the third group after the 6-bit transformation,\n2 extra zeros were added to fill the gap in this group.\n\nWhen we have a 6-bit group that is not completely full, like the third group, extra zeros\nare added to fill the gap. But what about when an entire 6-bit group is empty, or, it \nsimply doesn't exist? This is the case of the fourth 6-bit group exposed at\n@fig-base64-algo1.\n\nThis fourth group is necessary, because the algorithm works on 4 groups of 6 bits.\nBut the input string does not have enough bytes to create a fourth 6-bit group.\nEvery time this happens, where an entire group of 6 bits is empty,\nthis group becomes a \"padding group\". Every \"padding group\" is mapped to\nthe character `=` (equal sign), which represents \"null\", or, the end\nof meaningful characters in the sequence. Hence, everytime that the algorithm produces a\n\"padding group\", this group is automatically mapped to `=`.\n\nAs another example, if you give the string \"0\" as input to a base64 encoder, this string is\ntranslated into the base64 sequence \"MA==\".\nThe character \"0\" is, in binary, the sequence `00110000`[^zero-note]. So, with the 6-bit transformation\nexposed at @fig-base64-algo1, this single character would produce these two 6-bit groups: `001100`, `000000`.\nThe remaining two 6-bit groups become \"padding groups\". That is why the last\ntwo characters in the output sequence (MA==) are `==`.\n\n\n[^zero-note]: Notice that, the character \"0\" is different than the actual number 0, which is simply zero in binary.\n\n### A base64 decoder {#sec-base64-decoder-algo}\n\nThe algorithm behind a base64 decoder is essentially the inverse process of a base64 encoder.\nA base64 decoder needs to translate base64 messages back into their original meaning,\ni.e. into the original sequence of binary data.\n\nA base64 decoder usually works on a window of 4 bytes. Because it wants to convert these 4 bytes\nback into the original sequence of 3 bytes, that was converted into 4 groups of 6 bits by the\nbase64 encoder. Remember, in a base64 decoder we are essentially reverting the process made\nby the base64 encoder.\n\nEach byte in the input string (the base64 encoded string) normally contributes to re-create\ntwo different bytes in the output (the original binary data).\nIn other words, each byte that comes out of a base64 decoder is created by transforming merging two different\nbytes in the input together. You can visualize this relationship at @fig-base64-algo2:\n\n![The logic behind a base64 decoder](./../Figures/base64-decoder-flow.png){#fig-base64-algo2}\n\nThe exact transformations, or, the exact steps applied to each byte from the input to transform them\ninto the bytes of the output, are a bit tricky to visualize in a figure like this. Because of that, I have\nsummarized these transformations as \"Some bit shifting and additions ...\" in the figure. These transformations\nwill be described in depth later.\n\nBesides that, if you look again at @fig-base64-algo2, you will notice that the character `=` was completely\nignored by the algorithm. Remember, this is just a special character that marks the end of meaningful characters\nin the base64 sequence. So, every `=` character in a base64 encoded sequence should be ignored by a base64 decoder.\n\n\n## Difference between encode and decode {#sec-encode-vs-decode}\n\nIf you don't have any previous experience with base64, you might not understand the differences\nbetween \"encode\" and \"decode\". Essentially, the terms \"encode\" and \"decode\" here\nhave the exact same meaning as they have in the field of encryption (i.e. they mean the same thing as \"encode\" and \"decode\" in hashing\nalgorithms, like the MD5 algorithm).\n\nThus, \"encode\" means that we want to encode, or, in other words, we want to translate some message into\nthe base64 encoding system. We want to produce the sequence of base64 characters that represent this\noriginal message in the base64 encoding system.\n\nIn contrast, \"decode\" represents the inverse process.\nWe want to decode, or, in other words, translate a base64 message back to its original content.\nSo, in this process we get a sequence of base64 characters as input, and produce as output,\nthe binary data that is represented by this sequence of base64 characters.\n\nAny base64 library is normally composed of these two parts: 1) the encoder, which is a function that encodes\n(i.e. it converts) any sequence of binary data into a sequence of base64 characters; 2) the decoder, which is a function\nthat converts a sequence of base64 characters back into the original sequence of binary data.\n\n\n\n## Calculating the size of the output {#sec-base64-length-out}\n\nOne task that we need to do is to calculate how much space we need to reserve for the\noutput, both of the encoder and decoder. This is simple math, and can be done easily in Zig\nbecause every array has its length (its number of elements) easily accesible by consulting\nthe `.len` property of the array.\n\nFor the encoder, the logic is the following: for each 3 bytes that we find in the input,\n4 new bytes are created in the output. So, we take the number of bytes in the input, divide it\nby 3, use a ceiling function, then, we multiply the result by 4. That way, we get the total\nnumber of bytes that will be produced by the encoder in its output.\n\nThe `_calc_encode_length()` function below encapsulates this logic.\nInside this function, we take the length of the input array,\nwe divide it by 3, and apply a ceil operation over the result by using the\n`divCeil()` function from the Zig Standard Library. Lastly, we multiply\nthe end result by 4 to get the answer we need.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_encode_length(input: []const u8) !usize {\n    if (input.len < 3) {\n        const n_output: usize = 4;\n        return n_output;\n    }\n    const n_output: usize = try std.math.divCeil(\n        usize, input.len, 3\n    );\n    return n_output * 4;\n}\n```\n:::\n\n\n\n\n\nAlso, you might have notice that, if the input length is less than 3 bytes, then, the output length of the encoder is\nalways 4 bytes. This is the case for every input with less than 3 bytes, because, as I described at @sec-base64-encoder-algo,\nthe algorithm always produces enough \"padding-groups\" in the end result, to complete the 4 bytes window.\n\nNow, for the decoder, we just need to apply the inverse logic: for each 4 bytes in the input, 3 bytes\nwill be produced in the output of the decoder. I mean, this is roughly true, because we also need to\ntake the `=` character into account, which is always ignored by the decoder, as we described at @sec-base64-decoder-algo, and,\nat @fig-base64-algo2. But we can ignore this fact for now, just to keep things simple.\n\nThe function `_calc_decode_length()` exposed below summarizes this logic that we described. It is very similar\nto the function `_calc_encode_length()`. Only the division part is twisted, and also, in the special\ncase where we have less than 4 bytes in the input to work on. Also notice that this time, we apply\na floor operation over the output of the division, by using the `divFloor()`\nfunction (instead of a ceiling operation with `divCeil()`).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_decode_length(input: []const u8) !usize {\n    if (input.len < 4) {\n        const n_output: usize = 3;\n        return n_output;\n    }\n    const n_output: usize = try std.math.divFloor(\n        usize, input.len, 4\n    );\n    return n_output * 3;\n}\n```\n:::\n\n\n\n\n\n## Building the encoder logic {#sec-encoder-logic}\n\nIn this section, we can start building the logic behind the `encode()` function, which\nwill be responsible for encoding messages into the base64 encoding system.\nIf you are an anxious person, and you want to see now the full source code of the implementation\nfor this base64 encoder/decoder, you can find it at the `ZigExamples` folder in the official repository of\nthis book[^zig-base64-algo].\n\n[^zig-base64-algo]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/base64/base64_basic.zig>.\n\n\n\n### The 6-bit transformation {#sec-6bit-transf}\n\nThe 6-bit transformation presented at @fig-base64-algo1 is the core part of the base64 encoder algorithm.\nBy understanding how this transformation is made in code, the rest of the algorithm becomes much simpler\nto comprehend.\n\nIn essence, this 6-bit transformation is made with the help of bitwise operators.\nBitwise operators are essential to any type of low-level operation that is done at the bit-level. For the specific case of the base64 algorithm,\nthe operators *bif shift to the left* (`<<`), *bit shift to the right* (`>>`), and the *bitwise and* (`&`) are used. They\nare the core solution for the 6-bit transformation.\n\nThere are 3 different scenarios that we need to take into account in this transformation. First, is the perfect scenario,\nwhere we have the perfect window of 3 bytes to work on. Second, we have the scenario where we have a window of only\ntwo bytes to work with. And last, we have the scenario where we have a window of one single byte.\n\nIn each of these 3 scenarios, the 6-bit transformation works a bit differently. To make the explanation\neasier, I will use the variable `output` to refer to the bytes in the output of the base64 encoder,\nand the variable `input` to refer to the bytes in the input of the encoder.\n\n\nSo, if you have the perfect window of 3 bytes, these are steps for the 6-bit transformation:\n\n1. `output[0]` is produced by moving the bits from `input[0]` two positions to the right.\n1. `output[1]` is produced by summing two components. First, take the last two bits from `input[0]`, then, move them four positions to the left. Second, move the bits from `input[1]` four positions to the right. Sum these two components.\n1. `output[2]` is produced by summing two components. First, take the last four bits from `input[1]`, then, move them two positions to the left. Second, move the bits from `input[2]` six positions to the right. Sum these two components.\n1. `output[3]` is produced by taking the last six bits from `input[2]`.\n\n\nThis is the perfect scenario, where we have a full window of 3 bytes to work on.\nJust to make things as clear as possible, the @fig-encoder-bitshift demonstrates visually how\nthe step 2 mentioned above works. So the 2nd byte in the `output` of the encoder, is made by taking the 1st byte (dark purple)\nand the 2nd byte (orange) from the input. You can see that, at the end of the process, we get a new\nbyte that contains the last 2 bits from the 1st byte in the `input`, and the first 4 bits\nfrom the 2nd byte in the `input`.\n\n![How the 2nd byte in the output of the encoder is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input.](../Figures/base64-encoder-bit-shift.png){#fig-encoder-bitshift}\n\nOn the other hand, we must be prepared for the instances where we do not have the perfect window of 3 bytes.\nIf you have a window of 2 bytes, then, the steps 3 and 4, which produces the bytes `output[2]` and `output[3]`, change a little bit,\nand they become:\n\n- `output[2]` is produced by taking the last 4 bits from `input[1]`, then, move them two positions to the left.\n- `output[3]` is the character `'='`.\n\n\nFinally, if you have a window of a single byte, then, the steps 2 to 4, which produces the bytes `output[1]`, `output[2]` and `output[3]` change,\nbecoming:\n\n- `output[1]` is produced by taking the last two bits from `input[0]`, then, move them four positions to the left.\n- `output[2]` and `output[3]` are the character `=`.\n\n\nIf these bullet points were a bit confusing for you, you may find the @tbl-transf-6bit more intuitive.\nThis table unifies all this logic into a simple table. Notice that\nthis table also provides the exact expression in Zig that creates the corresponding\nbyte in the output.\n\n\n::: {#tbl-transf-6bit}\n\n| Number of bytes in the window | Byte index in the output | In code                                    |\n|-------------------------------|--------------------------|--------------------------------------------|\n| 3                             | 0                        | input[0] >> 2                              |\n| 3                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 3                             | 2                        | ((input[1] & 0x0f) << 2) + (input[2] >> 6) |\n| 3                             | 3                        | input[2] & 0x3f                            |\n| 2                             | 0                        | input[0] >> 2                              |\n| 2                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 2                             | 2                        | ((input[1] & 0x0f) << 2)                   |\n| 2                             | 3                        | '='                                        |\n| 1                             | 0                        | input[0] >> 2                              |\n| 1                             | 1                        | ((input[0] & 0x03) << 4)                   |\n| 1                             | 2                        | '='                                        |\n| 1                             | 3                        | '='                                        |\n\n: How the 6-bit transformation translates into code in different window settings.\n\n:::\n\n\n\n\n\n\n### Bit-shifting in Zig\n\nBit-shifting in Zig works similarly to bit-shifting in C.\nAll bitwise operators that exist in C are available in Zig.\nHere, in the base64 encoder algorithm, they are essential\nto produce the result we want.\n\nFor those who are not familiar with these operators, they are\noperators that operates at the bit-level of your values.\nThis means that these operators takes the bits that form the value\nyou have, and change them in some way. This ultimately also changes\nthe value itself, because the binary representation of this value\nchanges.\n\nWe have already seen at @fig-encoder-bitshift the effect produced by a bit-shift.\nBut let's use the first byte in the output of the base64 encoder as another example of what\nbit-shifting means. This is the easiest byte of the 4 bytes in the output\nto build. Because we only need to move the bits from the first byte in the input two positions to the right,\nwith the *bit shift to the right* (`>>`) operator.\n\nIf we take the string \"Hi\" that we used at @fig-base64-algo1 as an example, the first byte in\nthis string is \"H\", which is the sequence `01001000` in binary.\nIf we move the bits of this byte, two places to the right, we get the sequence `00010010` as result.\nThis binary sequence is the value `18` in decimal, and also, the value `0x12` in hexadecimal.\nNotice that the first 6 bits of \"H\" were moved to the end of the byte.\nWith this operation, we get the first byte of the output.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const input = \"Hi\";\n    try stdout.print(\"{d}\\n\", .{input[0] >> 2});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n18\n```\n\n\n:::\n:::\n\n\n\n\nIf you recall @fig-base64-algo1, the first byte present in the output should\nbe equivalent to the 6-bit group `010010`. Although being visually different, the\nsequences `010010` and `00010010` are semantically equal. They mean the same thing.\nThey both represent the number 18 in decimal, and the value `0x12` in hexadecimal.\n\nSo, don't take the \"6-bit group\" factor so seriously. We do not need necessarily to\nget a 6-bit sequence as result. As long as the meaning of the 8-bit sequence we get is the same\nof the 6-bit sequence, we are in the clear.\n\n\n\n### Selecting specific bits with the `&` operator\n\nIf you comeback to @sec-6bit-transf, you will see that, in order to produce\nthe second and third bytes in the output, we need to select specific\nbits from the first and second bytes in the input string. But how\ncan we do that? The answer relies on the *bitwise and* (`&`) operator.\n\nThe @fig-encoder-bitshift already showed you what effect this `&` operator\nproduces in the bits of its operands. But let's make a clear description of it.\n\nIn summary, the `&` operator performs a logical conjunction operation\nbetween the bits of its operands. In more details, the operator `&`\ncompares each bit of the first operand to the corresponding bit of the second operand.\nIf both bits are 1, the corresponding result bit is set to 1.\nOtherwise, the corresponding result bit is set to 0 [@microsoftbitwiseand].\n\nSo, if we apply this operator to the binary sequences `1000100` and `00001101`\nthe result of this operation is the binary sequence `00000100`. Because only\nat the sixth position in both binary sequences we had a 1 value. So any\nposition where we do not have both binary sequences setted to 1, we get\na 0 bit in the resulting binary sequence.\n\nWe lose information about the original bit values\nfrom both sequences in this case. Because we no longer know\nif this 0 bit in the resulting binary sequence was produced by\ncombining 0 with 0, or 1 with 0, or 0 with 1.\n\nAs an example, suppose you have the binary sequence `10010111`, which is the number 151 in decimal. How\ncan we get a new binary sequence which contains only the third and\nfourth bits of this sequence?\n\nWe just need to combine this sequence with `00110000` (is `0x30` in hexadecimal) using the `&` operator.\nNotice that only the third and fourth positions in this binary sequence is setted to 1. As a consequence, only the\nthird and fourth values of both binary sequences are potentially preserved in the output. All the remaining positions\nare setted to zero in the output sequence, which is `00010000` (is the number 16 in decimal).\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const bits = 0b10010111;\n    try stdout.print(\"{d}\\n\", .{bits & 0b00110000});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n16\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Allocating space for the output\n\nAs I described at @sec-stack, to store an object in the stack,\nthis object needs to have a known and fixed length at compile-time. This is an important\nlimitation for our base64 encoder/decoder case. Because the size of\nthe output (from both the encoder and decoder) depends\ndirectly on the size of the input.\n\nHaving this in mind, we cannot know at compile time which is\nthe size of the output for both the encoder and decoder.\nSo, if we can't know the size of the output at compile time,\nthis means that we cannot store the output for both the encoder\nand decoder in the stack.\n\nConsequently, we need to store this output on the heap,\nand, as I commented at @sec-heap, we can only\nstore objects in the heap by using allocator objects.\nSo, one the arguments to both the `encode()` and `decode()`\nfunctions, needs to be an allocator object, because\nwe know for sure that, at some point inside the body of these\nfunctions, we need to allocate space on the heap to\nstore the output of these functions.\n\nThat is why, both the `encode()` and `decode()` functions that I\npresent in this book, have an argument called `allocator`,\nwhich receives a allocator object as input, identified by\nthe type `std.mem.Allocator` from the Zig Standard Library.\n\n\n\n### Writing the `encode()` function\n\nNow that we have a basic understanding on how the bitwise operators work, and how\nexactly they help us to achieve the result we want to achieve. We can now encapsulate\nall the logic that we have described at @fig-base64-algo1 and @tbl-transf-6bit into a nice\nfunction that we can add to our `Base64` struct definition, that we started at @sec-base64-table.\n\nYou can find the `encode()` function below. Notice that the first argument of this function,\nis the `Base64` struct itself. Therefore, this argument clearly signals\nthat this function is a method from the `Base64` struct.\n\nBecause the `encode()` function itself is fairly long,\nI intentionally omitted the `Base64` struct definition in this source code,\njust for brevity reasons. So, just remember that this function is a public function (or a public method) from the\n`Base64` struct.\n\nFurthermore, this `encode()` function has two other arguments:\n\n1. `input` is the input sequence of characters that you want to encode in base64;\n1. `allocator` is an allocator object to use in the necessary memory allocations.\n\nI described everything you need to know about allocator objects at @sec-allocators.\nSo, if you are not familiar with them, I highly recommend you to comeback to\nthat section, and read it.\nBy looking at the `encode()` function, you will see that we use this\nallocator object to allocate enough memory to store the output of\nthe encoding process.\n\nThe main for loop in the function is responsible for iterating through the entire input string.\nIn every iteration, we use a `count` variable to count how many iterations we had at the\nmoment. When `count` reaches 3, then, we try to encode the 3 characters (or bytes) that we have accumulated\nin the temporary buffer object (`buf`).\n\nAfter encoding these 3 characters and storing the result in the `output` variable, we reset\nthe `count` variable to zero, and start to count again on the next iteration of the loop.\nIf the loop hits the end of the string, and, the `count` variable is less than 3, then, it means that\nthe temporary buffer contains the last 1 or 2 bytes from the input.\nThat is why we have two `if` statements after the for loop. To deal which each possible case.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn encode(self: Base64,\n              allocator: std.mem.Allocator,\n              input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n\n    const n_out = try _calc_encode_length(input);\n    var out = try allocator.alloc(u8, n_out);\n    var buf = [3]u8{ 0, 0, 0 };\n    var count: u8 = 0;\n    var iout: u64 = 0;\n\n    for (input, 0..) |_, i| {\n        buf[count] = input[i];\n        count += 1;\n        if (count == 3) {\n            out[iout] = self._char_at(buf[0] >> 2);\n            out[iout + 1] = self._char_at(\n                ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n            );\n            out[iout + 2] = self._char_at(\n                ((buf[1] & 0x0f) << 2) + (buf[2] >> 6)\n            );\n            out[iout + 3] = self._char_at(buf[2] & 0x3f);\n            iout += 4;\n            count = 0;\n        }\n    }\n\n    if (count == 1) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            (buf[0] & 0x03) << 4\n        );\n        out[iout + 2] = '=';\n        out[iout + 3] = '=';\n    }\n\n    if (count == 2) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n        );\n        out[iout + 2] = self._char_at(\n            (buf[1] & 0x0f) << 2\n        );\n        out[iout + 3] = '=';\n        iout += 4;\n    }\n\n    return out;\n}\n```\n:::\n\n\n\n\n\n\n## Building the decoder logic {#sec-decoder-logic}\n\nNow, we can focus on writing the base64 decoder logic. Remember from @fig-base64-algo2 that,\na base64 decoder does the inverse process of an encoder. So, all we need to do, is to\nwrite a `decode()` function that performs the inverse process that I exposed at @sec-encoder-logic.\n\n\n### Mapping base64 characters to their indexes {#sec-map-base64-index}\n\nOne thing that we need to do, in order to decode a base64-encoded message, is to calculate\nthe index in the base64 scale of every base64 character that we encounter in the decoder input.\n\nIn other words, the decoder receives as input, a sequence of base64 characters. We need\nto translate this sequence of characters into a sequence of indexes. These indexes\nare the index of each character in the base64 scale. This way, we get the value/byte\nthat was calculated in the 6-bit transformation step of the encoder process.\n\nThere are probably better/faster ways to calculate this, especially using a \"divide and conquer\"\ntype of strategy. But for now, I am satisfied with a simple and \"brute force\" type of strategy.\nThe `_char_index()` function below contains this strategy.\n\nWe are essentially looping through the *lookup table* with the base64 scale,\nand comparing the character we got with each character in the base64 scale.\nIf these characters match, then, we return the index of this character in the\nbase64 scale as the result.\n\nNotice that, if the input character is `'='`, the function returns the index 64, which is\n\"out of range\" in the scale. But, as I described at @sec-base64-scale,\nthe character `'='` does not belong to the base64 scale itself.\nIt is a special and meaningless character in base64.\n\nAlso notice that this `_char_index()` function is a method from our `Base64` struct,\nbecause of the `self` argument. Again, I have omitted the `Base64` struct definition in this example\nfor brevity reasons.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn _char_index(self: Base64, char: u8) u8 {\n    if (char == '=')\n        return 64;\n    var index: u8 = 0;\n    for (0..63) |i| {\n        if (self._char_at(i) == char) {\n            index = i;\n            break;\n        }\n    }\n\n    return index;\n}\n```\n:::\n\n\n\n\n\n\n### The 6-bit transformation\n\nOnce again, the core part of the algorithm is the 6-bit transformation.\nIf we understand the necessary steps to perform this transformation, the rest\nof the algorithm becomes much easier.\n\nFirst of all, before we actually go to the 6-bit transformation,\nwe need to make sure that we use `_char_index()` to convert the sequence of base64 characters\ninto a sequence of indexes. So the snippet below is important for the job that will be done.\nThe result of `_char_index()` is stored in a temporary buffer, and this temporary buffer\nis what we are going to use in the 6-bit transformation, instead of the actual `input` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (0..input.len) |i| {\n    buf[i] = self._char_index(input[i]);\n}\n```\n:::\n\n\n\n\nNow, instead of producing 4 bytes (or 4 characters) as output per each window of 3 characters in the input,\na base64 decoder produces 3 bytes (or 3 characters) as output per each window of 4 characters in the input.\nOnce again, is the inverse process.\n\nSo, the steps to produce the 3 bytes in the output are:\n\n1. `output[0]` is produced by summing two components. First, move the bits from `buf[0]` two positions to the left. Second, move the bits from `buf[1]` 4 positions to the right. Then, sum these two components.\n1. `output[1]` is produced by summing two components. First, move the bits from `buf[1]` four positions to the left. Second, move the bits from `buf[2]` 2 positions to the right. Then, sum these two components.\n1. `output[2]` is produced by summing two components. First, move the bits from `buf[2]` six positions to the left. Then, you sum the result with `buf[3]`.\n\n\nBefore we continue, let's try to visualize how these transformations make the original bytes that we had\nbefore the encoding process. First, think back to the 6-bit transformation performed by the encoder exposed at @sec-encoder-logic.\nThe first byte in the output of the encoder is produced by moving the bits in the first byte of the input two positions to the right.\n\nIf for example the first byte in the input of the encoder was the sequence `ABCDEFGH`, then, the first byte in the output of the encoder would be\n`00ABCDEF` (this sequence would be the first byte in the input of the decoder). Now, if the second byte in the input of the encoder was the sequence\n`IJKLMNOP`, then, the second byte in the encoder output would be `00GHIJKL` (as we demonstrated at @fig-encoder-bitshift).\n\nHence, if the sequences `00ABCDEF` and `00GHIJKL` are the first and second bytes, respectively, in the input of the decoder, the\n@fig-decoder-bitshift demonstrates visually how these two bytes are transformed into the first byte of the output of the decoder.\nNotice that the output byte is the sequence `ABCDEFGH`, which is the original byte from the input of the encoder.\n\n![How the 1st byte in the decoder output is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input](../Figures/base64-decoder-bit-shift.png){#fig-decoder-bitshift}\n\nThe @tbl-6bit-decode presents how the three steps described earlier translate into Zig code:\n\n\n\n::: {#tbl-6bit-decode}\n\n| Byte index in the output | In code                       |\n|--------------------------|-------------------------------|\n| 0                        | (buf[0] << 2) + (buf[1] >> 4) |\n| 1                        | (buf[1] << 4) + (buf[2] >> 2) |\n| 2                        | (buf[2] << 6) + buf[3]        |\n\n: The necessary steps for the 6-transformation in the decode process.\n\n\n:::\n\n\n\n\n\n\n\n### Writing the `decode()` function\n\nThe `decode()` function below contains the entire decoding process.\nWe first calculate the size of the output, with\n`_calc_decode_length()`, then, we allocate enough memory for this output with\nthe allocator object.\n\nThree temporary variables are created: 1) `count`, to hold the window count\nin each iteration of the for loop; 2) `iout`, to hold the current index in the output;\n3) `buf`, which is the temporary buffer that holds the base64 indexes to be\nconverted through the 6-bit transformation.\n\nThen, in each iteration of the for loop we fill the temporary buffer with the current\nwindow of bytes. When `count` hits the number 4, then, we have a full window of\nindexes in `buf` to be converted, and then, we apply the 6-bit transformation\nover the temporary buffer.\n\nNotice that we check if the indexes 2 and 3 in the temporary buffer are the number 64, which, if you recall\nfrom @sec-map-base64-index, is when the `_calc_index()` function receives a `'='` character\nas input. So, if these indexes are equal to the number 64, the `decode()` function knows\nthat it can simply ignore these indexes. They are not converted because, as I described before,\nthe character `'='` has no meaning, despite being the end of meaningful characters in the sequence.\nSo we can safely ignore them when they appear in the sequence.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn decode(self: Base64,\n          allocator: std.mem.Allocator,\n          input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n    const n_output = try _calc_decode_length(input);\n    var output = try allocator.alloc(u8, n_output);\n    var count: u8 = 0;\n    var iout: u64 = 0;\n    var buf = [4]u8{ 0, 0, 0, 0 };\n\n    for (0..input.len) |i| {\n        buf[count] = self._char_index(input[i]);\n        count += 1;\n        if (count == 4) {\n            output[iout] = (buf[0] << 2) + (buf[1] >> 4);\n            if (buf[2] != 64) {\n                output[iout + 1] = (buf[1] << 4) + (buf[2] >> 2);\n            }\n            if (buf[3] != 64) {\n                output[iout + 2] = (buf[2] << 6) + buf[3];\n            }\n            iout += 3;\n            count = 0;\n        }\n    }\n\n    return output;\n}\n```\n:::\n\n\n\n\n\n## The end result\n\nNow that we have both `decode()` and `encode()` implemented. We have a fully functioning\nbase64 encoder/decoder implemented in Zig. Here is an usage example of our\n`Base64` struct with the `encode()` and `decode()` methods that we have implemented.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar memory_buffer: [1000]u8 = undefined;\nvar fba = std.heap.FixedBufferAllocator.init(\n    &memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst text = \"Testing some more shit\";\nconst etext = \"VGVzdGluZyBzb21lIG1vcmUgc2hpdA==\";\nconst base64 = Base64.init();\nconst encoded_text = try base64.encode(\n    allocator, text\n);\nconst decoded_text = try base64.decode(\n    allocator, etext\n);\ntry stdout.print(\n    \"Encoded text: {s}\\n\", .{encoded_text}\n);\ntry stdout.print(\n    \"Decoded text: {s}\\n\", .{decoded_text}\n);\n```\n:::\n\n\n\n\n```\nEncoded text: VGVzdGluZyBzb21lIG1vcmUgc2hpdA==\nDecoded text: Testing some more shit\n```\n\nYou can also see the full source code at once, by visiting the official repository of this book[^repo].\nMore precisely inside the `ZigExamples` folder[^zig-base64-algo].\n\n[^repo]: <https://github.com/pedropark99/zig-book>\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 1 - Building a base64 encoder/decoder {#sec-base64}\n\nAs our first small project, I want to implement a base64 encoder/decoder with you.\nBase64 is an encoding system which translates binary data to text.\nA big chunk of the web uses base64 to deliver binary data to systems\nthat can only read text data.\n\nThe most common example of a modern use case for base64 is essentially any email system,\nlike GMail, Outlook, etc. Because email systems normally use\nthe Simple Mail Transfer Protocol (SMTP), which is a web protocol\nthat supports only text data. So, if you need, for any reason, to\nsend a binary file (like for example, a PDF, or an Excel file) as\nan attachment in your email, these binary files are normally\nconverted to base64, before they are included in the SMTP message.\nSo, the base64 encoding is largely used in these email systems to include\nbinary data into the SMTP message.\n\n\n\n\n\n\n## How the base64 algorithm work?\n\nBut how exactly does the algorithm behind the base64 encoding work? Let's discuss that. First, I will\nexplain the base64 scale, which is the 64-character scale that is the basis for\nthe base64 encoding system.\n\nAfter that, I explain the algorithm behind a base64 encoder, which is the part of the algorithm that is responsible for encoding messages\ninto the base64 encoding system. Then, after that, I explain the algorithm behind a base64 decoder, which is\nthe part of the algorithm that is responsible for translating base64 messages back into their original meaning.\n\nIf you are unsure about the differences between an \"encoder\" and a \"decoder\",\ntake a look at @sec-encode-vs-decode.\n\n\n### The base64 scale {#sec-base64-scale}\n\nThe base64 encoding system is based on a scale that goes from 0 to 63 (hence the name).\nEach index in this scale is represented by a character (it is a scale of 64 characters).\nSo, in order to convert some binary data, to the base64 encoding, we need to convert each binary number to the corresponding\ncharacter in this \"scale of 64 characters\".\n\nThe base64 scale starts with all ASCII uppercase letters (A to Z) which represents\nthe first 25 indexes in this scale (0 to 25). After that, we have all ASCII lowercase letters\n(a to z), which represents the range 26 to 51 in the scale. After that, we\nhave the one digit numbers (0 to 9), which represents the indexes from 52 to 61 in the scale.\nFinally, the last two indexes in the scale (62 and 63) are represented by the characters `+` and `/`,\nrespectively.\n\nThese are the 64 characters that compose the base64 scale. The equal sign character (`=`) is not part of the scale itself,\nbut it is a special character in the base64 encoding system. This character is used solely as a suffix, to mark the end of the character sequence,\nor, to mark the end of meaningful characters in the sequence.\n\nThe bullet points below summarises the base64 scale:\n\n- range 0 to 25 is represented by: ASCII uppercase letters `-> [A-Z]`;\n- range 26 to 51 is represented by: ASCII lowercase letters `-> [a-z]`;\n- range 52 to 61 is represented by: one digit numbers `-> [0-9]`;\n- index 62 and 63 are represented by the characters `+` and `/`, respectively;\n- the character `=` represents the end of meaningful characters in the sequence;\n\n\n\n\n### Creating the scale as a lookup table {#sec-base64-table}\n\nThe best way to represent this scale in code, is to represent it as a *lookup table*.\nLookup tables are a classic strategy in computer science to speed up calculations. The basic idea\nis to replace a runtime calculation (which can take a long time to be done) with a basic array indexing\noperation.\n\nInstead of calculating the results everytime you need them, you calculate all possible results at once, and then, you store them in an array\n(which behaves lake a \"table\"). Then, every time you need to use one of the characters in the base64 scale, instead of\nusing many resources to calculate the exact character to be used, you simply retrieve this character\nfrom the array where you stored all the possible characters in the base64 scale.\nWe retrieve the character that we need directly from memory.\n\nWe can start building a Zig struct to store our base64 decoder/encoder logic.\nWe start with the `Base64` struct below. For now, we only have one single data member in this\nstruct, i.e. the member `_table`, which represents our lookup table. We also have an `init()` method,\nto create a new instance of a `Base64` object, and, a `_char_at()` method, which is a\n\"get character at index $x$\" type of function.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Base64 = struct {\n    _table: *const [64]u8,\n\n    pub fn init() Base64 {\n        const upper = \"ABCDEFGHIJKLMNOPQRSTUVWXYZ\";\n        const lower = \"abcdefghijklmnopqrstuvwxyz\";\n        const numbers_symb = \"0123456789+/\";\n        return Base64{\n            ._table = upper ++ lower ++ numbers_symb,\n        };\n    }\n\n    pub fn _char_at(self: Base64, index: usize) u8 {\n        return self._table[index];\n    }\n};\n```\n:::\n\n\n\n\n\nIn other words, the `_char_at()` method is responsible for getting the character in the lookup\ntable (i.e. the `_table` struct data member) that corresponds to a particular index in the\n\"base64 scale\". So, in the example below, we know that the character that corresponds to the\nindex 28 in the \"base64 scale\" is the character \"c\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst base64 = Base64.init();\ntry stdout.print(\n    \"Character at index 28: {c}\\n\",\n    .{base64._char_at(28)}\n);\n```\n:::\n\n\n\n\n```\nCharacter at index 28: c\n```\n\n\n\n### A base64 encoder {#sec-base64-encoder-algo}\n\nThe algorithm behind a base64 encoder usually works on a window of 3 bytes. Because each byte has\n8 bits, so, 3 bytes forms a set of $8 \\times 3 = 24$ bits. This is desirable for the base64 algorithm, because\n24 bits is divisible by 6, which forms $24 / 6 = 4$ groups of 6 bits each.\n\nTherefore, the base64 algorithm works by converting 3 bytes at a time\ninto 4 characters from the base64 scale. It keeps iterating through the input string,\n3 bytes at a time, and converting them into the base64 scale, producing 4 characters\nper iteration. It keeps iterating, and producing these \"new characters\"\nuntil it hits the end of the input string.\n\nNow, you may think, what if you have a particular string that have a number of bytes\nthat is not divisible by 3? What happens? For example, if you have a string\nthat contains only two characters/bytes, such as \"Hi\". How the\nalgorithm would behave in such situation? You find the answer at @fig-base64-algo1.\nYou can see at @fig-base64-algo1 that the string \"Hi\", when converted to base64,\nbecomes the string \"SGk=\":\n\n![The logic behind a base64 encoder](./../Figures/base64-encoder-flow.png){#fig-base64-algo1}\n\nTaking the string \"Hi\" as an example, we have 2 bytes, or, 16 bits in total. So, we lack a full byte (8 bits)\nto complete the window of 24 bits that the base64 algorithm likes to work on. The first thing that\nthe algorithm does, is to check how to divide the input bytes into groups of 6 bits.\n\nIf the algorithm notices that there is a group of 6 bits that, have some bits in it, but, at the same time, it is not full\n(in other words, $0 < nbits < 6$, being $nbits$ the number of bits), meaning that, it lacks\nsome bits to fill the 6-bits requirement, the algorithm simply add extra zeros in this group\nto fill the space that it needs. That is why at @fig-base64-algo1, on the third group after the 6-bit transformation,\n2 extra zeros were added to fill the gap in this group.\n\nWhen we have a 6-bit group that is not completely full, like the third group, extra zeros\nare added to fill the gap. But what about when an entire 6-bit group is empty, or, it\nsimply doesn't exist? This is the case of the fourth 6-bit group exposed at\n@fig-base64-algo1.\n\nThis fourth group is necessary, because the algorithm works on 4 groups of 6 bits.\nBut the input string does not have enough bytes to create a fourth 6-bit group.\nEvery time this happens, where an entire group of 6 bits is empty,\nthis group becomes a \"padding group\". Every \"padding group\" is mapped to\nthe character `=` (equal sign), which represents \"null\", or, the end\nof meaningful characters in the sequence. Hence, everytime that the algorithm produces a\n\"padding group\", this group is automatically mapped to `=`.\n\nAs another example, if you give the string \"0\" as input to a base64 encoder, this string is\ntranslated into the base64 sequence \"MA==\".\nThe character \"0\" is, in binary, the sequence `00110000`[^zero-note]. So, with the 6-bit transformation\nexposed at @fig-base64-algo1, this single character would produce these two 6-bit groups: `001100`, `000000`.\nThe remaining two 6-bit groups become \"padding groups\". That is why the last\ntwo characters in the output sequence (MA==) are `==`.\n\n\n[^zero-note]: Notice that, the character \"0\" is different than the actual number 0, which is simply zero in binary.\n\n### A base64 decoder {#sec-base64-decoder-algo}\n\nThe algorithm behind a base64 decoder is essentially the inverse process of a base64 encoder.\nA base64 decoder needs to translate base64 messages back into their original meaning,\ni.e. into the original sequence of binary data.\n\nA base64 decoder usually works on a window of 4 bytes. Because it wants to convert these 4 bytes\nback into the original sequence of 3 bytes, that was converted into 4 groups of 6 bits by the\nbase64 encoder. Remember, in a base64 decoder we are essentially reverting the process made\nby the base64 encoder.\n\nEach byte in the input string (the base64 encoded string) normally contributes to re-create\ntwo different bytes in the output (the original binary data).\nIn other words, each byte that comes out of a base64 decoder is created by transforming merging two different\nbytes in the input together. You can visualize this relationship at @fig-base64-algo2:\n\n![The logic behind a base64 decoder](./../Figures/base64-decoder-flow.png){#fig-base64-algo2}\n\nThe exact transformations, or, the exact steps applied to each byte from the input to transform them\ninto the bytes of the output, are a bit tricky to visualize in a figure like this. Because of that, I have\nsummarized these transformations as \"Some bit shifting and additions ...\" in the figure. These transformations\nwill be described in depth later.\n\nBesides that, if you look again at @fig-base64-algo2, you will notice that the character `=` was completely\nignored by the algorithm. Remember, this is just a special character that marks the end of meaningful characters\nin the base64 sequence. So, every `=` character in a base64 encoded sequence should be ignored by a base64 decoder.\n\n\n## Difference between encode and decode {#sec-encode-vs-decode}\n\nIf you don't have any previous experience with base64, you might not understand the differences\nbetween \"encode\" and \"decode\". Essentially, the terms \"encode\" and \"decode\" here\nhave the exact same meaning as they have in the field of encryption (i.e. they mean the same thing as \"encode\" and \"decode\" in hashing\nalgorithms, like the MD5 algorithm).\n\nThus, \"encode\" means that we want to encode, or, in other words, we want to translate some message into\nthe base64 encoding system. We want to produce the sequence of base64 characters that represent this\noriginal message in the base64 encoding system.\n\nIn contrast, \"decode\" represents the inverse process.\nWe want to decode, or, in other words, translate a base64 message back to its original content.\nSo, in this process we get a sequence of base64 characters as input, and produce as output,\nthe binary data that is represented by this sequence of base64 characters.\n\nAny base64 library is normally composed of these two parts: 1) the encoder, which is a function that encodes\n(i.e. it converts) any sequence of binary data into a sequence of base64 characters; 2) the decoder, which is a function\nthat converts a sequence of base64 characters back into the original sequence of binary data.\n\n\n\n## Calculating the size of the output {#sec-base64-length-out}\n\nOne task that we need to do is to calculate how much space we need to reserve for the\noutput, both of the encoder and decoder. This is simple math, and can be done easily in Zig\nbecause every array has its length (its number of elements) easily accesible by consulting\nthe `.len` property of the array.\n\nFor the encoder, the logic is the following: for each 3 bytes that we find in the input,\n4 new bytes are created in the output. So, we take the number of bytes in the input, divide it\nby 3, use a ceiling function, then, we multiply the result by 4. That way, we get the total\nnumber of bytes that will be produced by the encoder in its output.\n\nThe `_calc_encode_length()` function below encapsulates this logic.\nInside this function, we take the length of the input array,\nwe divide it by 3, and apply a ceil operation over the result by using the\n`divCeil()` function from the Zig Standard Library. Lastly, we multiply\nthe end result by 4 to get the answer we need.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_encode_length(input: []const u8) !usize {\n    if (input.len < 3) {\n        const n_output: usize = 4;\n        return n_output;\n    }\n    const n_output: usize = try std.math.divCeil(\n        usize, input.len, 3\n    );\n    return n_output * 4;\n}\n```\n:::\n\n\n\n\n\nAlso, you might have notice that, if the input length is less than 3 bytes, then, the output length of the encoder is\nalways 4 bytes. This is the case for every input with less than 3 bytes, because, as I described at @sec-base64-encoder-algo,\nthe algorithm always produces enough \"padding-groups\" in the end result, to complete the 4 bytes window.\n\nNow, for the decoder, we just need to apply the inverse logic: for each 4 bytes in the input, 3 bytes\nwill be produced in the output of the decoder. I mean, this is roughly true, because we also need to\ntake the `=` character into account, which is always ignored by the decoder, as we described at @sec-base64-decoder-algo, and,\nat @fig-base64-algo2. But we can ignore this fact for now, just to keep things simple.\n\nThe function `_calc_decode_length()` exposed below summarizes this logic that we described. It is very similar\nto the function `_calc_encode_length()`. Only the division part is twisted, and also, in the special\ncase where we have less than 4 bytes in the input to work on. Also notice that this time, we apply\na floor operation over the output of the division, by using the `divFloor()`\nfunction (instead of a ceiling operation with `divCeil()`).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_decode_length(input: []const u8) !usize {\n    if (input.len < 4) {\n        const n_output: usize = 3;\n        return n_output;\n    }\n    const n_output: usize = try std.math.divFloor(\n        usize, input.len, 4\n    );\n    return n_output * 3;\n}\n```\n:::\n\n\n\n\n\n## Building the encoder logic {#sec-encoder-logic}\n\nIn this section, we can start building the logic behind the `encode()` function, which\nwill be responsible for encoding messages into the base64 encoding system.\nIf you are an anxious person, and you want to see now the full source code of the implementation\nfor this base64 encoder/decoder, you can find it at the `ZigExamples` folder in the official repository of\nthis book[^zig-base64-algo].\n\n[^zig-base64-algo]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/base64/base64_basic.zig>.\n\n\n\n### The 6-bit transformation {#sec-6bit-transf}\n\nThe 6-bit transformation presented at @fig-base64-algo1 is the core part of the base64 encoder algorithm.\nBy understanding how this transformation is made in code, the rest of the algorithm becomes much simpler\nto comprehend.\n\nIn essence, this 6-bit transformation is made with the help of bitwise operators.\nBitwise operators are essential to any type of low-level operation that is done at the bit-level. For the specific case of the base64 algorithm,\nthe operators *bif shift to the left* (`<<`), *bit shift to the right* (`>>`), and the *bitwise and* (`&`) are used. They\nare the core solution for the 6-bit transformation.\n\nThere are 3 different scenarios that we need to take into account in this transformation. First, is the perfect scenario,\nwhere we have the perfect window of 3 bytes to work on. Second, we have the scenario where we have a window of only\ntwo bytes to work with. And last, we have the scenario where we have a window of one single byte.\n\nIn each of these 3 scenarios, the 6-bit transformation works a bit differently. To make the explanation\neasier, I will use the variable `output` to refer to the bytes in the output of the base64 encoder,\nand the variable `input` to refer to the bytes in the input of the encoder.\n\n\nSo, if you have the perfect window of 3 bytes, these are steps for the 6-bit transformation:\n\n1. `output[0]` is produced by moving the bits from `input[0]` two positions to the right.\n1. `output[1]` is produced by summing two components. First, take the last two bits from `input[0]`, then, move them four positions to the left. Second, move the bits from `input[1]` four positions to the right. Sum these two components.\n1. `output[2]` is produced by summing two components. First, take the last four bits from `input[1]`, then, move them two positions to the left. Second, move the bits from `input[2]` six positions to the right. Sum these two components.\n1. `output[3]` is produced by taking the last six bits from `input[2]`.\n\n\nThis is the perfect scenario, where we have a full window of 3 bytes to work on.\nJust to make things as clear as possible, the @fig-encoder-bitshift demonstrates visually how\nthe step 2 mentioned above works. So the 2nd byte in the `output` of the encoder, is made by taking the 1st byte (dark purple)\nand the 2nd byte (orange) from the input. You can see that, at the end of the process, we get a new\nbyte that contains the last 2 bits from the 1st byte in the `input`, and the first 4 bits\nfrom the 2nd byte in the `input`.\n\n![How the 2nd byte in the output of the encoder is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input.](../Figures/base64-encoder-bit-shift.png){#fig-encoder-bitshift}\n\nOn the other hand, we must be prepared for the instances where we do not have the perfect window of 3 bytes.\nIf you have a window of 2 bytes, then, the steps 3 and 4, which produces the bytes `output[2]` and `output[3]`, change a little bit,\nand they become:\n\n- `output[2]` is produced by taking the last 4 bits from `input[1]`, then, move them two positions to the left.\n- `output[3]` is the character `'='`.\n\n\nFinally, if you have a window of a single byte, then, the steps 2 to 4, which produces the bytes `output[1]`, `output[2]` and `output[3]` change,\nbecoming:\n\n- `output[1]` is produced by taking the last two bits from `input[0]`, then, move them four positions to the left.\n- `output[2]` and `output[3]` are the character `=`.\n\n\nIf these bullet points were a bit confusing for you, you may find the @tbl-transf-6bit more intuitive.\nThis table unifies all this logic into a simple table. Notice that\nthis table also provides the exact expression in Zig that creates the corresponding\nbyte in the output.\n\n\n::: {#tbl-transf-6bit}\n\n| Number of bytes in the window | Byte index in the output | In code                                    |\n|-------------------------------|--------------------------|--------------------------------------------|\n| 3                             | 0                        | input[0] >> 2                              |\n| 3                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 3                             | 2                        | ((input[1] & 0x0f) << 2) + (input[2] >> 6) |\n| 3                             | 3                        | input[2] & 0x3f                            |\n| 2                             | 0                        | input[0] >> 2                              |\n| 2                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 2                             | 2                        | ((input[1] & 0x0f) << 2)                   |\n| 2                             | 3                        | '='                                        |\n| 1                             | 0                        | input[0] >> 2                              |\n| 1                             | 1                        | ((input[0] & 0x03) << 4)                   |\n| 1                             | 2                        | '='                                        |\n| 1                             | 3                        | '='                                        |\n\n: How the 6-bit transformation translates into code in different window settings.\n\n:::\n\n\n\n\n\n\n### Bit-shifting in Zig\n\nBit-shifting in Zig works similarly to bit-shifting in C.\nAll bitwise operators that exist in C are available in Zig.\nHere, in the base64 encoder algorithm, they are essential\nto produce the result we want.\n\nFor those who are not familiar with these operators, they are\noperators that operates at the bit-level of your values.\nThis means that these operators takes the bits that form the value\nyou have, and change them in some way. This ultimately also changes\nthe value itself, because the binary representation of this value\nchanges.\n\nWe have already seen at @fig-encoder-bitshift the effect produced by a bit-shift.\nBut let's use the first byte in the output of the base64 encoder as another example of what\nbit-shifting means. This is the easiest byte of the 4 bytes in the output\nto build. Because we only need to move the bits from the first byte in the input two positions to the right,\nwith the *bit shift to the right* (`>>`) operator.\n\nIf we take the string \"Hi\" that we used at @fig-base64-algo1 as an example, the first byte in\nthis string is \"H\", which is the sequence `01001000` in binary.\nIf we move the bits of this byte, two places to the right, we get the sequence `00010010` as result.\nThis binary sequence is the value `18` in decimal, and also, the value `0x12` in hexadecimal.\nNotice that the first 6 bits of \"H\" were moved to the end of the byte.\nWith this operation, we get the first byte of the output.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const input = \"Hi\";\n    try stdout.print(\"{d}\\n\", .{input[0] >> 2});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n18\n```\n\n\n:::\n:::\n\n\n\n\nIf you recall @fig-base64-algo1, the first byte present in the output should\nbe equivalent to the 6-bit group `010010`. Although being visually different, the\nsequences `010010` and `00010010` are semantically equal. They mean the same thing.\nThey both represent the number 18 in decimal, and the value `0x12` in hexadecimal.\n\nSo, don't take the \"6-bit group\" factor so seriously. We do not need necessarily to\nget a 6-bit sequence as result. As long as the meaning of the 8-bit sequence we get is the same\nof the 6-bit sequence, we are in the clear.\n\n\n\n### Selecting specific bits with the `&` operator\n\nIf you comeback to @sec-6bit-transf, you will see that, in order to produce\nthe second and third bytes in the output, we need to select specific\nbits from the first and second bytes in the input string. But how\ncan we do that? The answer relies on the *bitwise and* (`&`) operator.\n\nThe @fig-encoder-bitshift already showed you what effect this `&` operator\nproduces in the bits of its operands. But let's make a clear description of it.\n\nIn summary, the `&` operator performs a logical conjunction operation\nbetween the bits of its operands. In more details, the operator `&`\ncompares each bit of the first operand to the corresponding bit of the second operand.\nIf both bits are 1, the corresponding result bit is set to 1.\nOtherwise, the corresponding result bit is set to 0 [@microsoftbitwiseand].\n\nSo, if we apply this operator to the binary sequences `1000100` and `00001101`\nthe result of this operation is the binary sequence `00000100`. Because only\nat the sixth position in both binary sequences we had a 1 value. So any\nposition where we do not have both binary sequences setted to 1, we get\na 0 bit in the resulting binary sequence.\n\nWe lose information about the original bit values\nfrom both sequences in this case. Because we no longer know\nif this 0 bit in the resulting binary sequence was produced by\ncombining 0 with 0, or 1 with 0, or 0 with 1.\n\nAs an example, suppose you have the binary sequence `10010111`, which is the number 151 in decimal. How\ncan we get a new binary sequence which contains only the third and\nfourth bits of this sequence?\n\nWe just need to combine this sequence with `00110000` (is `0x30` in hexadecimal) using the `&` operator.\nNotice that only the third and fourth positions in this binary sequence is setted to 1. As a consequence, only the\nthird and fourth values of both binary sequences are potentially preserved in the output. All the remaining positions\nare setted to zero in the output sequence, which is `00010000` (is the number 16 in decimal).\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const bits = 0b10010111;\n    try stdout.print(\"{d}\\n\", .{bits & 0b00110000});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n16\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Allocating space for the output\n\nAs I described at @sec-stack, to store an object in the stack,\nthis object needs to have a known and fixed length at compile-time. This is an important\nlimitation for our base64 encoder/decoder case. Because the size of\nthe output (from both the encoder and decoder) depends\ndirectly on the size of the input.\n\nHaving this in mind, we cannot know at compile time which is\nthe size of the output for both the encoder and decoder.\nSo, if we can't know the size of the output at compile time,\nthis means that we cannot store the output for both the encoder\nand decoder in the stack.\n\nConsequently, we need to store this output on the heap,\nand, as I commented at @sec-heap, we can only\nstore objects in the heap by using allocator objects.\nSo, one the arguments to both the `encode()` and `decode()`\nfunctions, needs to be an allocator object, because\nwe know for sure that, at some point inside the body of these\nfunctions, we need to allocate space on the heap to\nstore the output of these functions.\n\nThat is why, both the `encode()` and `decode()` functions that I\npresent in this book, have an argument called `allocator`,\nwhich receives a allocator object as input, identified by\nthe type `std.mem.Allocator` from the Zig Standard Library.\n\n\n\n### Writing the `encode()` function\n\nNow that we have a basic understanding on how the bitwise operators work, and how\nexactly they help us to achieve the result we want to achieve. We can now encapsulate\nall the logic that we have described at @fig-base64-algo1 and @tbl-transf-6bit into a nice\nfunction that we can add to our `Base64` struct definition, that we started at @sec-base64-table.\n\nYou can find the `encode()` function below. Notice that the first argument of this function,\nis the `Base64` struct itself. Therefore, this argument clearly signals\nthat this function is a method from the `Base64` struct.\n\nBecause the `encode()` function itself is fairly long,\nI intentionally omitted the `Base64` struct definition in this source code,\njust for brevity reasons. So, just remember that this function is a public function (or a public method) from the\n`Base64` struct.\n\nFurthermore, this `encode()` function has two other arguments:\n\n1. `input` is the input sequence of characters that you want to encode in base64;\n1. `allocator` is an allocator object to use in the necessary memory allocations.\n\nI described everything you need to know about allocator objects at @sec-allocators.\nSo, if you are not familiar with them, I highly recommend you to comeback to\nthat section, and read it.\nBy looking at the `encode()` function, you will see that we use this\nallocator object to allocate enough memory to store the output of\nthe encoding process.\n\nThe main for loop in the function is responsible for iterating through the entire input string.\nIn every iteration, we use a `count` variable to count how many iterations we had at the\nmoment. When `count` reaches 3, then, we try to encode the 3 characters (or bytes) that we have accumulated\nin the temporary buffer object (`buf`).\n\nAfter encoding these 3 characters and storing the result in the `output` variable, we reset\nthe `count` variable to zero, and start to count again on the next iteration of the loop.\nIf the loop hits the end of the string, and, the `count` variable is less than 3, then, it means that\nthe temporary buffer contains the last 1 or 2 bytes from the input.\nThat is why we have two `if` statements after the for loop. To deal which each possible case.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn encode(self: Base64,\n              allocator: std.mem.Allocator,\n              input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n\n    const n_out = try _calc_encode_length(input);\n    var out = try allocator.alloc(u8, n_out);\n    var buf = [3]u8{ 0, 0, 0 };\n    var count: u8 = 0;\n    var iout: u64 = 0;\n\n    for (input, 0..) |_, i| {\n        buf[count] = input[i];\n        count += 1;\n        if (count == 3) {\n            out[iout] = self._char_at(buf[0] >> 2);\n            out[iout + 1] = self._char_at(\n                ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n            );\n            out[iout + 2] = self._char_at(\n                ((buf[1] & 0x0f) << 2) + (buf[2] >> 6)\n            );\n            out[iout + 3] = self._char_at(buf[2] & 0x3f);\n            iout += 4;\n            count = 0;\n        }\n    }\n\n    if (count == 1) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            (buf[0] & 0x03) << 4\n        );\n        out[iout + 2] = '=';\n        out[iout + 3] = '=';\n    }\n\n    if (count == 2) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n        );\n        out[iout + 2] = self._char_at(\n            (buf[1] & 0x0f) << 2\n        );\n        out[iout + 3] = '=';\n        iout += 4;\n    }\n\n    return out;\n}\n```\n:::\n\n\n\n\n\n\n## Building the decoder logic {#sec-decoder-logic}\n\nNow, we can focus on writing the base64 decoder logic. Remember from @fig-base64-algo2 that,\na base64 decoder does the inverse process of an encoder. So, all we need to do, is to\nwrite a `decode()` function that performs the inverse process that I exposed at @sec-encoder-logic.\n\n\n### Mapping base64 characters to their indexes {#sec-map-base64-index}\n\nOne thing that we need to do, in order to decode a base64-encoded message, is to calculate\nthe index in the base64 scale of every base64 character that we encounter in the decoder input.\n\nIn other words, the decoder receives as input, a sequence of base64 characters. We need\nto translate this sequence of characters into a sequence of indexes. These indexes\nare the index of each character in the base64 scale. This way, we get the value/byte\nthat was calculated in the 6-bit transformation step of the encoder process.\n\nThere are probably better/faster ways to calculate this, especially using a \"divide and conquer\"\ntype of strategy. But for now, I am satisfied with a simple and \"brute force\" type of strategy.\nThe `_char_index()` function below contains this strategy.\n\nWe are essentially looping through the *lookup table* with the base64 scale,\nand comparing the character we got with each character in the base64 scale.\nIf these characters match, then, we return the index of this character in the\nbase64 scale as the result.\n\nNotice that, if the input character is `'='`, the function returns the index 64, which is\n\"out of range\" in the scale. But, as I described at @sec-base64-scale,\nthe character `'='` does not belong to the base64 scale itself.\nIt is a special and meaningless character in base64.\n\nAlso notice that this `_char_index()` function is a method from our `Base64` struct,\nbecause of the `self` argument. Again, I have omitted the `Base64` struct definition in this example\nfor brevity reasons.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn _char_index(self: Base64, char: u8) u8 {\n    if (char == '=')\n        return 64;\n    var index: u8 = 0;\n    for (0..63) |i| {\n        if (self._char_at(i) == char)\n            break;\n        index += 1;\n    }\n\n    return index;\n}\n```\n:::\n\n\n\n\n\n\n### The 6-bit transformation\n\nOnce again, the core part of the algorithm is the 6-bit transformation.\nIf we understand the necessary steps to perform this transformation, the rest\nof the algorithm becomes much easier.\n\nFirst of all, before we actually go to the 6-bit transformation,\nwe need to make sure that we use `_char_index()` to convert the sequence of base64 characters\ninto a sequence of indexes. So the snippet below is important for the job that will be done.\nThe result of `_char_index()` is stored in a temporary buffer, and this temporary buffer\nis what we are going to use in the 6-bit transformation, instead of the actual `input` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (0..input.len) |i| {\n    buf[i] = self._char_index(input[i]);\n}\n```\n:::\n\n\n\n\nNow, instead of producing 4 bytes (or 4 characters) as output per each window of 3 characters in the input,\na base64 decoder produces 3 bytes (or 3 characters) as output per each window of 4 characters in the input.\nOnce again, is the inverse process.\n\nSo, the steps to produce the 3 bytes in the output are:\n\n1. `output[0]` is produced by summing two components. First, move the bits from `buf[0]` two positions to the left. Second, move the bits from `buf[1]` 4 positions to the right. Then, sum these two components.\n1. `output[1]` is produced by summing two components. First, move the bits from `buf[1]` four positions to the left. Second, move the bits from `buf[2]` 2 positions to the right. Then, sum these two components.\n1. `output[2]` is produced by summing two components. First, move the bits from `buf[2]` six positions to the left. Then, you sum the result with `buf[3]`.\n\n\nBefore we continue, let's try to visualize how these transformations make the original bytes that we had\nbefore the encoding process. First, think back to the 6-bit transformation performed by the encoder exposed at @sec-encoder-logic.\nThe first byte in the output of the encoder is produced by moving the bits in the first byte of the input two positions to the right.\n\nIf for example the first byte in the input of the encoder was the sequence `ABCDEFGH`, then, the first byte in the output of the encoder would be\n`00ABCDEF` (this sequence would be the first byte in the input of the decoder). Now, if the second byte in the input of the encoder was the sequence\n`IJKLMNOP`, then, the second byte in the encoder output would be `00GHIJKL` (as we demonstrated at @fig-encoder-bitshift).\n\nHence, if the sequences `00ABCDEF` and `00GHIJKL` are the first and second bytes, respectively, in the input of the decoder, the\n@fig-decoder-bitshift demonstrates visually how these two bytes are transformed into the first byte of the output of the decoder.\nNotice that the output byte is the sequence `ABCDEFGH`, which is the original byte from the input of the encoder.\n\n![How the 1st byte in the decoder output is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input](../Figures/base64-decoder-bit-shift.png){#fig-decoder-bitshift}\n\nThe @tbl-6bit-decode presents how the three steps described earlier translate into Zig code:\n\n\n\n::: {#tbl-6bit-decode}\n\n| Byte index in the output | In code                       |\n|--------------------------|-------------------------------|\n| 0                        | (buf[0] << 2) + (buf[1] >> 4) |\n| 1                        | (buf[1] << 4) + (buf[2] >> 2) |\n| 2                        | (buf[2] << 6) + buf[3]        |\n\n: The necessary steps for the 6-transformation in the decode process.\n\n\n:::\n\n\n\n\n\n\n\n### Writing the `decode()` function\n\nThe `decode()` function below contains the entire decoding process.\nWe first calculate the size of the output, with\n`_calc_decode_length()`, then, we allocate enough memory for this output with\nthe allocator object.\n\nThree temporary variables are created: 1) `count`, to hold the window count\nin each iteration of the for loop; 2) `iout`, to hold the current index in the output;\n3) `buf`, which is the temporary buffer that holds the base64 indexes to be\nconverted through the 6-bit transformation.\n\nThen, in each iteration of the for loop we fill the temporary buffer with the current\nwindow of bytes. When `count` hits the number 4, then, we have a full window of\nindexes in `buf` to be converted, and then, we apply the 6-bit transformation\nover the temporary buffer.\n\nNotice that we check if the indexes 2 and 3 in the temporary buffer are the number 64, which, if you recall\nfrom @sec-map-base64-index, is when the `_calc_index()` function receives a `'='` character\nas input. So, if these indexes are equal to the number 64, the `decode()` function knows\nthat it can simply ignore these indexes. They are not converted because, as I described before,\nthe character `'='` has no meaning, despite being the end of meaningful characters in the sequence.\nSo we can safely ignore them when they appear in the sequence.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn decode(self: Base64,\n          allocator: std.mem.Allocator,\n          input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n    const n_output = try _calc_decode_length(input);\n    var output = try allocator.alloc(u8, n_output);\n    var count: u8 = 0;\n    var iout: u64 = 0;\n    var buf = [4]u8{ 0, 0, 0, 0 };\n\n    for (0..input.len) |i| {\n        buf[count] = self._char_index(input[i]);\n        count += 1;\n        if (count == 4) {\n            output[iout] = (buf[0] << 2) + (buf[1] >> 4);\n            if (buf[2] != 64) {\n                output[iout + 1] = (buf[1] << 4) + (buf[2] >> 2);\n            }\n            if (buf[3] != 64) {\n                output[iout + 2] = (buf[2] << 6) + buf[3];\n            }\n            iout += 3;\n            count = 0;\n        }\n    }\n\n    return output;\n}\n```\n:::\n\n\n\n\n\n## The end result\n\nNow that we have both `decode()` and `encode()` implemented. We have a fully functioning\nbase64 encoder/decoder implemented in Zig. Here is an usage example of our\n`Base64` struct with the `encode()` and `decode()` methods that we have implemented.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar memory_buffer: [1000]u8 = undefined;\nvar fba = std.heap.FixedBufferAllocator.init(\n    &memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst text = \"Testing some more shit\";\nconst etext = \"VGVzdGluZyBzb21lIG1vcmUgc2hpdA==\";\nconst base64 = Base64.init();\nconst encoded_text = try base64.encode(\n    allocator, text\n);\nconst decoded_text = try base64.decode(\n    allocator, etext\n);\ntry stdout.print(\n    \"Encoded text: {s}\\n\", .{encoded_text}\n);\ntry stdout.print(\n    \"Decoded text: {s}\\n\", .{decoded_text}\n);\n```\n:::\n\n\n\n\n```\nEncoded text: VGVzdGluZyBzb21lIG1vcmUgc2hpdA==\nDecoded text: Testing some more shit\n```\n\nYou can also see the full source code at once, by visiting the official repository of this book[^repo].\nMore precisely inside the `ZigExamples` folder[^zig-base64-algo].\n\n[^repo]: <https://github.com/pedropark99/zig-book>\n",
+    "supporting": [
+      "01-base64_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/01-memory/execute-results/html.json b/_freeze/Chapters/01-memory/execute-results/html.json
index 29ccbc27..261517a0 100644
--- a/_freeze/Chapters/01-memory/execute-results/html.json
+++ b/_freeze/Chapters/01-memory/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "0a086161bb0eedee4b92cc3e013bd2f2",
+  "hash": "9dd26d21ce5237efcdc6a86592378fde",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Memory and Allocators\n\n\nIn this chapter, we will talk about memory. How does Zig control memory? What\ncommon tools are used? Are there any important aspects that make memory\ndifferent/special in Zig? You will find the answers here.\n\nComputers fundamentally rely on memory to function. This memory acts as a temporary storage\nspace for the data and values generated during computations. Without memory, the core\nconcepts of \"variables\" and \"objects\" in programming languages would be impossible.\n\n\n\n\n## Memory spaces\n\nEvery object that you create in your Zig source code needs to be stored somewhere,\nin your computer's memory. Depending on where and how you define your object, Zig\nwill use a different \"memory space\", or a different\ntype of memory to store this object.\n\nEach type of memory normally serves for different purposes.\nIn Zig, there are 3 types of memory (or 3 different memory spaces) that we care about. They are:\n\n- Global data register (or the \"global data section\");\n- Stack;\n- Heap;\n\n\n### Compile-time known versus runtime known {#sec-compile-time}\n\nOne strategy that Zig uses to decide where it will store each object that you declare, is by looking\nat the value of this particular object. More specifically, by investigating if this value is\nknown at \"compile-time\" or at \"runtime\".\n\nWhen you write a program in Zig, the values of some of the objects that you write in your program are *known\nat compile time*. Meaning that, when you compile your Zig source code, during the compilation process,\nthe `zig` compiler can figure out the exact value of a particular object\nthat exists in your source code.\nKnowing the length (or the size) of each object is also important. So the length (or the size) of each object that you write in your program is,\nin some cases, *known at compile time*.\n\nThe `zig` compiler cares more about knowing the length (or the size) of a particular object\n, than to know its actual value. But, if the `zig` compiler knows the value of the object, then, it\nautomatically knows the size of this object. Because it can simply calculate the\nsize of the object by looking at the size of the value.\n\nTherefore, the priority for the `zig` compiler is to discover the size of each object in your source code.\nIf the value of the object in question is known at compile-time, then, the `zig` compiler\nautomatically knows the size/length of this object. But if the value of this object is not\nknown at compile-time, then, the size of this object is only known at compile-time if,\nand only if, the type of this object has a known fixed size.\n\nIn order for a type to have a known fixed size, this type must have data members whose size is fixed.\nIf this type includes, for example, a variable sized array in it, then, this type does not have a known\nfixed size. Because this array can have any size at runtime\n(i.e. it can be an array of 2 elements, or 50 elements, or 1 thousand elements, etc.).\n\nFor example, a string object, which internally is an array of constant u8 values (`[]const u8`)\nhas a variable size. It can be a string object with 100 or 500 characters in it. If we do not\nknow at compile-time, which exact string will be stored inside this string object, then, we cannot calculate\nthe size of this string object at compile-time. So, any type, or any struct declaration that you make, that\nincludes a string data member that does not have an explicit fixed size, makes this type, or this\nnew struct that you are declaring, a type that does not have a known fixed size at compile-time.\n\nIn contrast, if the type of this struct that you are declaring, includes a data member that is an array,\nbut this array has a known fixed size, like `[60]u8` (which declares an array of 60 `u8` values), then,\nthis type, or, this struct that you are declaring, becomes a type with a known fixed size at compile-time.\nAnd because of that, in this case, the `zig` compiler does not need to know at compile-time the exact value of\nany object of this type. Since the compiler can find the necessary size to store this object by\nlooking at the size of its type.\n\n\nLet's look at an example. In the source code below, we have two constant objects (`name` and `array`) declared.\nBecause the values of these particular objects are written down, in the source code itself (`\"Pedro\"`\nand the number sequence from 1 to 4), the `zig` compiler can easily discover the values of these constant\nobjects (`name` and `array`) during the compilation process.\nThis is what \"known at compile time\" means. It refers to any object that you have in your Zig source code\nwhose value can be identified at compile time.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn input_length(input: []const u8) usize {\n    const n = input.len;\n    return n;\n}\n\npub fn main() !void {\n    const name = \"Pedro\";\n    const array = [_]u8{1, 2, 3, 4};\n    _ = name; _ = array;\n}\n```\n:::\n\n\n\n\n\nThe other side of the spectrum are objects whose values are not known at compile time.\nFunction arguments are a classic example of this. Because the value of each function\nargument depends on the value that you assign to this particular argument,\nwhen you call the function.\n\nFor example, the function `input_length()` contains an argument named `input`, which is an array of constant `u8` integers (`[]const u8`).\nIt is impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length\nof this particular argument. Because it is an array that do not have a fixed size specified explicitly in the argument type annotation.\n\nSo, we know that this `input` argument will be an array of `u8` integers. But we do not know at compile-time, its value, and neither his size.\nThis information is known only at runtime, which is the period of time when you program is executed.\nAs a consequence, the value of the expression `input.len` is also known only at runtime.\nThis is an intrinsic characteristic of any function. Just remember that the value of function arguments is usually not \"compile-time known\".\n\nHowever, as I mentioned earlier, what really matters to the compiler is to know the size of the object\nat compile-time, and not necessarily its value. So, although we don't know the value of the object `n`, which is the result of the expression\n`input.len`, at compile-time, we do know its size. Because the expression `input.len` always returns a value of type `usize`,\nand the type `usize` has a known fixed size.\n\n\n\n### Global data register\n\nThe global data register is a specific section of the executable of your Zig program, that is responsible\nfor storing any value that is known at compile time.\n\nEvery constant object whose value is known at compile time that you declare in your source code,\nis stored in the global data register. Also, every literal value that you write in your source code,\nsuch as the string `\"this is a string\"`, or the integer `10`, or a boolean value such as `true`,\nis also stored in the global data register.\n\nHonestly, you don't need to care much about this memory space. Because you can't control it,\nyou can't deliberately access it or use it for your own purposes.\nAlso, this memory space does not affect the logic of your program.\nIt simply exists in your program.\n\n\n### Stack vs Heap\n\nIf you are familiar with system's programming, or just low-level programming in general, you\nprobably have heard of the \"duel\" between Stack vs Heap. These are two different types of memory,\nor different memory spaces, which are both available in Zig.\n\nThese two types of memory don't actually duel with\neach other. This is a common mistake that beginners have, when seeing \"x vs y\" styles of\ntabloid headlines. These two types of memory are actually complementary to each other.\nSo, in almost every Zig program that you ever write, you will likely use a combination of both.\nI will describe each memory space in detail over the next sections. But for now, I just want to\nstablish the main difference between these two types of memory.\n\nIn essence, the stack memory is normally used to store values whose length is fixed and known\nat compile time. In contrast, the heap memory is a *dynamic* type of memory space, meaning that, it is\nused to store values whose length might grow during the execution (runtime) of your program [@jenny2022].\n\nLengths that grow during runtime are intrinsically associated with \"runtime known\" type of values.\nIn other words, if you have an object whose length might grow during runtime, then, the length\nof this object becomes not known at compile time. If the length is not known at compile-time,\nthe value of this object also becomes not known at compile-time.\nThese types of objects should be stored in the heap memory space, which is\na dynamic memory space, which can grow or shrink to fit the size of your objects.\n\n\n\n### Stack {#sec-stack}\n\nThe stack is a type of memory that uses the power of the *stack data structure*, hence the name. \nA \"stack\" is a type of *data structure* that uses a \"last in, first out\" (LIFO) mechanism to store the values\nyou give it to. I imagine you are familiar with this data structure.\nBut, if you are not, the [Wikipedia page](https://en.wikipedia.org/wiki/Stack_(abstract_data_type))[^wiki-stack]\n, or, the [Geeks For Geeks page](https://www.geeksforgeeks.org/stack-data-structure/)[^geek-stack] are both\nexcellent and easy resources to fully understand how this data structure works.\n\n[^wiki-stack]: <https://en.wikipedia.org/wiki/Stack_(abstract_data_type)>\n[^geek-stack]: <https://www.geeksforgeeks.org/stack-data-structure/>\n\nSo, the stack memory space is a type of memory that stores values using a stack data structure.\nIt adds and removes values from the memory by following a \"last in, first out\" (LIFO) principle.\n\nEvery time you make a function call in Zig, an amount of space in the stack is\nreserved for this particular function call [@jenny2022; @zigdocs].\nThe value of each function argument given to the function in this function call is stored in this\nstack space. Also, every local object that you declare inside the function scope is\nusually stored in this same stack space.\n\n\nLooking at the example below, the object `result` is a local object declared inside the scope of the `add()`\nfunction. Because of that, this object is stored inside the stack space reserved for the `add()` function.\nThe `r` object (which is declared outside of the `add()` function scope) is also stored in the stack.\nBut since it is declared in the \"outer\" scope, this object is stored in the\nstack space that belongs to this outer scope.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn add(x: u8, y: u8) u8 {\n    const result = x + y;\n    return result;\n}\n\npub fn main() !void {\n    const r = add(5, 27);\n    _ = r;\n}\n```\n:::\n\n\n\n\n\n\nSo, any object that you declare inside the scope of a function is always stored inside\nthe space that was reserved for that particular function in the stack memory. This\nalso counts for any object declared inside the scope of your `main()` function for example.\nAs you would expect, in this case, they\nare stored inside the stack space reserved for the `main()` function.\n\nOne very important detail about the stack memory is that **it frees itself automatically**.\nThis is very important, remember that. When objects are stored in the stack memory,\nyou don't have the work (or the responsibility) of freeing/destroying these objects.\nBecause they will be automatically destroyed once the stack space is freed at the end of the function scope.\n\nSo, once the function call returns (or ends, if you prefer to call it this way)\nthe space that was reserved in the stack is destroyed, and all of the objects that were in that space goes away with it.\nThis mechanism exists because this space, and the objects within it, are not necessary anymore,\nsince the function \"finished its business\".\nUsing the `add()` function that we exposed above as an example, it means that the object `result` is automatically\ndestroyed once the function returns.\n\n::: {.callout-important}\nLocal objects that are stored in the stack space of a function are automatically\nfreed/destroyed at the end of the function scope.\n:::\n\n\nThis same logic applies to any other special structure in Zig that have its own scope by surrounding\nit with curly braces (`{}`).\nFor loops, while loops, if else statements, etc. For example, if you declare any local\nobject in the scope of a for loop, this local object is accessible only within the scope\nof this particular for loop. Because once the scope of this for loop ends, the space in the stack\nreserved for this for loop is freed.\nThe example below demonstrates this idea.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This does not compile successfully!\nconst a = [_]u8{0, 1, 2, 3, 4};\nfor (0..a.len) |i| {\n    const index = i;\n    _ = index;\n}\n// Trying to use an object that was\n// declared in the for loop scope,\n// and that does not exist anymore.\nstd.debug.print(\"{d}\\n\", index);\n```\n:::\n\n\n\n\n\n\n\nOne important consequence of this mechanism is that, once the function returns, you can no longer access any memory\naddress that was inside the space in the stack reserved for this particular function. Because this space was\ndestroyed. This means that, if this local object is stored in the stack,\nyou cannot make a function that **returns a pointer to this object**.\n\nThink about that for a second. If all local objects in the stack are destroyed at the end of the function scope, why\nwould you even consider returning a pointer to one of these objects? This pointer is at best,\ninvalid, or, more likely, \"undefined\".\n\nConclusion, it is totally fine to write a function that returns the local object\nitself as result, because then, you return the value of that object as the result.\nBut, if this local object is stored in the stack, you should never write a function\nthat returns a pointer to this local object. Because the memory address pointed by the pointer\nno longer exists.\n\n\nSo, using again the `add()` function as an example, if you rewrite this function so that it\nreturns a pointer to the local object `result`, the `zig` compiler will actually compile\nyour program, with no warnings or errors. At first glance, it looks that this is good code\nthat works as expected. But this is a lie!\n\nIf you try to take a look at the value inside of the `r` object,\nor, if you try to use this `r` object in another expression\nor function call, then, you would have undefined behaviour, and major\nbugs in your program [@zigdocs, see \"Lifetime and Ownership\"[^life] and \"Undefined Behaviour\"[^undef] sections].\n\n[^life]: <https://ziglang.org/documentation/master/#Lifetime-and-Ownership>\n[^undef]: <https://ziglang.org/documentation/master/#Undefined-Behavior>\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn add(x: u8, y: u8) *const u8 {\n    const result = x + y;\n    return &result;\n}\n\npub fn main() !void {\n    // This code compiles successfully. But it has\n    // undefined behaviour. Never do this!!!\n    // The `r` object is undefined!\n    const r = add(5, 27); _ = r;\n}\n```\n:::\n\n\n\n\n\nThis \"invalid pointer to stack variable\" problem is very known across many programming language communities.\nIf you try to do the same thing, for example, in a C or C++ program (i.e. returning an address to\na local object stored in the stack), you would also get undefined behaviour\nin the program.\n\n::: {.callout-important}\nIf a local object in your function is stored in the stack, you should never\nreturn a pointer to this local object from the function. Because\nthis pointer will always become undefined after the function returns, since the stack space of the function\nis destroyed at the end of its scope.\n:::\n\nBut what if you really need to use this local object in some way after your function returns?\nHow can you do this? The answer is: \"in the same you would do if this was a C or C++ program. By returning\nan address to an object stored in the heap\". The heap memory has a much more flexible lifecycle,\nand allows you to get a valid pointer to a local object of a function that already returned\nfrom its scope.\n\n\n### Heap {#sec-heap}\n\nOne important limitation of the stack, is that, only objects whose length/size is known at compile-time can be\nstored in it. In contrast, the heap is a much more dynamic\n(and flexible) type of memory. It is the perfect type of memory to use\nfor objects whose size/length might grow during the execution of your program.\n\nVirtually any application that behaves as a server is a classic use case of the heap.\nA HTTP server, a SSH server, a DNS server, a LSP server, ... any type of server.\nIn summary, a server is a type of application that runs for long periods of time,\nand that serves (or \"deals with\") any incoming request that reaches this particular server.\n\nThe heap is a good choice for this type of system, mainly because the server does not know upfront\nhow many requests it will receive from users, while it is active. It could be one single request,\nor, 5 thousand requests, or, it could also be zero requests.\nThe server needs to have the ability to allocate and manage its memory according to how many requests it receives.\n\nAnother key difference between the stack and the heap, is that the heap is a type\nof memory that you, the programmer, have complete control over. This makes the heap a\nmore flexible type of memory, but it also makes it harder to work with. Because you,\nthe programmer, is responsible for managing everything related to it. Including where the memory is allocated,\nhow much memory is allocated, and where this memory is freed.\n\n> Unlike stack memory, heap memory is allocated explicitly by programmers and it won’t be deallocated until it is explicitly freed [@jenny2022].\n\nTo store an object in the heap, you, the programmer, needs to explicitly tells Zig to do so,\nby using an allocator to allocate some space in the heap. At @sec-allocators, I will present how you can use allocators to allocate memory\nin Zig.\n\n::: {.callout-important}\nEvery memory you allocate in the heap needs to be explicitly freed by you, the programmer.\n:::\n\nThe majority of allocators in Zig do allocate memory on the heap. But some exceptions to this rule are\n`ArenaAllocator()` and `FixedBufferAllocator()`. The `ArenaAllocator()` is a special\ntype of allocator that works in conjunction with a second type of allocator.\nOn the other side, the `FixedBufferAllocator()` is an allocator that works based on\nbuffer objects created on the stack. This means that the `FixedBufferAllocator()` makes\nallocations only on the stack.\n\n\n\n\n### Summary\n\nAfter discussing all of these boring details, we can quickly recap what we learned.\nIn summary, the Zig compiler will use the following rules to decide where each\nobject you declare is stored:\n\n1. every literal value (such as `\"this is string\"`, `10`, or `true`) is stored in the global data section.\n1. every constant object (`const`) whose value **is known at compile-time** is also stored in the global data section.\n1. every object (constant or not) whose length/size **is known at compile time** is stored in the stack space for the current scope.\n1. if an object is created with the method `alloc()` or `create()` of an allocator object, this object is stored in the memory space used by this particular allocator object. Most of allocators available in Zig use the heap memory, so, this object is likely stored in the heap (`FixedBufferAllocator()` is an exception to that).\n1. the heap can only be accessed through allocators. If your object was not created through the `alloc()` or `create()` methods of an allocator object, then, he is most certainly not an object stored in the heap.\n\n\n## Stack overflows {#sec-stack-overflow}\n\nAllocating memory on the stack is generally faster than allocating it on the heap.\nBut this better performance comes with many restrictions. We have already discussed\nmany of these restrictions of the stack at @sec-stack. But there is one more important\nlimitation that I want to talk about, which is the size of the stack itself.\n\nThe stack is limited in size. This size varies from computer to computer, and it depends on\na lot of things (the computer architecture, the operating system, etc.). Nevertheless, this size is usually\nnot that big. This is why we normally use the stack to store only temporary and small objects in memory.\n\nIn essence, if you try to make an allocation on the stack, that is so big that exceeds the stack size limit,\na *stack overflow* happens, and your program just crashes as a result of that. In other words, a stack overflow happens when\nyou attempt to use more space than is available on the stack.\n\nThis type of problem is very similar to a *buffer overflow*, i.e. you are trying to use more space\nthan is available in the \"buffer object\". However, a stack overflow always cause your program to crash,\nwhile a buffer overflow not always cause your program to crash (although it often does).\n\nYou can see an example of a stack overflow in the example below. We are trying to allocate a very big array of `u64` values\non the stack. You can see below that this program does not run succesfully, because it crashed\nwith a \"segmentation fault\" error message.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar very_big_alloc: [1000 * 1000 * 24]u64 = undefined;\n@memset(very_big_alloc[0..], 0);\n```\n:::\n\n\n\n\n\n```\nSegmentation fault (core dumped)\n```\n\nThis segmentation fault error is a result of the stack overflow that was caused by the big\nmemory allocation made on the stack, to store the `very_big_alloc` object.\nThis is why very big objects are usually stored on the heap, instead of the stack.\n\n\n\n## Allocators {#sec-allocators}\n\nOne key aspect about Zig, is that there are \"no hidden-memory allocations\" in Zig.\nWhat that really means, is that \"no allocations happen behind your back in the standard library\" [@zigguide].\n\nThis is a known problem, especially in C++. Because in C++, there are some operators that do allocate\nmemory behind the scene, and there is no way for you to know that, until you actually read the\nsource code of these operators, and find the memory allocation calls.\nMany programmers find this behaviour annoying and hard to keep track of.\n\nBut, in Zig, if a function, an operator, or anything from the standard library\nneeds to allocate some memory during its execution, then, this function/operator needs to receive (as input) an allocator\nprovided by the user, to actually be able to allocate the memory it needs.\n\nThis creates a clear distinction between functions that \"do not\" from those that \"actually do\"\nallocate memory. Just look at the arguments of this function.\nIf a function, or operator, has an allocator object as one of its inputs/arguments, then, you know for\nsure that this function/operator will allocate some memory during its execution.\n\nAn example is the `allocPrint()` function from the Zig Standard Library. With this function, you can\nwrite a new string using format specifiers. So, this function is, for example, very similar to the function `sprintf()` in C.\nIn order to write such new string, the `allocPrint()` function needs to allocate some memory to store the\noutput string.\n\nThat is why, the first argument of this function is an allocator object that you, the user/programmer, gives\nas input to the function. In the example below, I am using the `GeneralPurposeAllocator()` as my allocator\nobject. But I could easily use any other type of allocator object from the Zig Standard Library.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst name = \"Pedro\";\nconst output = try std.fmt.allocPrint(\n    allocator,\n    \"Hello {s}!!!\",\n    .{name}\n);\ntry stdout.print(\"{s}\\n\", .{output});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello Pedro!!!\n```\n\n\n:::\n:::\n\n\n\n\n\n\nYou get a lot of control over where and how much memory this function can allocate.\nBecause it is you, the user/programmer, that provides the allocator for the function to use.\nThis makes \"total control\" over memory management easier to achieve in Zig.\n\n### What are allocators?\n\nAllocators in Zig are objects that you can use to allocate memory for your program.\nThey are similar to the memory allocating functions in C, like `malloc()` and `calloc()`.\nSo, if you need to use more memory than you initially have, during the execution of your program, you can simply ask\nfor more memory by using an allocator object.\n\nZig offers different types of allocators, and they are usually available through the `std.heap` module of\nthe standard library. Thus, just import the Zig Standard Library into your Zig module (with `@import(\"std\")`), and you can start\nusing these allocators in your code.\n\nFurthermore, every allocator object is built on top of the `Allocator` interface in Zig.\nThis means that, every allocator object you find in Zig must have the methods `alloc()`,\n`create()`, `free()` and `destroy()`. So, you can change the type of allocator you are using,\nbut you don't need to change the function calls to the methods that do the memory allocation\n(and the free memory operations) for your program.\n\n### Why you need an allocator?\n\nAs we described at @sec-stack, everytime you make a function call in Zig,\na space in the stack is reserved for this function call. But the stack\nhas a key limitation which is: every object stored in the stack have a\nknown fixed length.\n\nBut in reality, there are two very common instances where this \"fixed length limitation\" of the stack is a deal braker:\n\n1. the objects that you create inside your function might grow in size during the execution of the function.\n1. sometimes, it is impossible to know upfront how many inputs you will receive, or how big this input will be.\n\nAlso, there is another instance where you might want to use an allocator, which is when you want to write a function that returns a pointer\nto a local object. As I described at @sec-stack, you cannot do that if this local object is stored in the\nstack. However, if this object is stored in the heap, then, you can return a pointer to this object at the\nend of the function. Because you (the programmer) control the lifetime of any heap memory that you allocate. You decide\nwhen this memory gets destroyed/freed.\n\nThese are common situations where the stack is not good for.\nThat is why you need a different memory management strategy to\nstore these objects inside your function. You need to use\na memory type that can grow together with your objects, or that you\ncan control the lifetime of this memory.\nThe heap fits this description.\n\nAllocating memory on the heap is commonly known as dynamic memory management. As the objects you create grow in size\nduring the execution of your program, you grow the amount of memory\nyou have by allocating more memory in the heap to store these objects. \nAnd you do that in Zig, by using an allocator object.\n\n\n### The different types of allocators\n\n\nAt the moment of the writing of this book, in Zig, we have 6 different\nallocators available in the standard library:\n\n- `GeneralPurposeAllocator()`.\n- `page_allocator()`.\n- `FixedBufferAllocator()` and `ThreadSafeFixedBufferAllocator()`.\n- `ArenaAllocator()`.\n- `c_allocator()` (requires you to link to libc).\n\n\nEach allocator has its own perks and limitations. All allocators, except `FixedBufferAllocator()` and `ArenaAllocator()`,\nare allocators that use the heap memory. So any memory that you allocate with\nthese allocators, will be placed in the heap.\n\n### General-purpose allocators\n\nThe `GeneralPurposeAllocator()`, as the name suggests, is a \"general purpose\" allocator. You can use it for every type\nof task. In the example below, I'm allocating enough space to store a single integer in the object `some_number`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const some_number = try allocator.create(u32);\n    defer allocator.destroy(some_number);\n\n    some_number.* = @as(u32, 45);\n}\n```\n:::\n\n\n\n\n\n\nWhile useful, you might want to use the `c_allocator()`, which is a alias to the C standard allocator `malloc()`. So, yes, you can use\n`malloc()` in Zig if you want to. Just use the `c_allocator()` from the Zig standard library. However,\nif you do use `c_allocator()`, you must link to Libc when compiling your source code with the\n`zig` compiler, by including the flag `-lc` in your compilation process.\nIf you do not link your source code to Libc, Zig will not be able to find the\n`malloc()` implementation in your system.\n\n### Page allocator\n\nThe `page_allocator()` is an allocator that allocates full pages of memory in the heap. In other words,\nevery time you allocate memory with `page_allocator()`, a full page of memory in the heap is allocated,\ninstead of just a small piece of it.\n\nThe size of this page depends on the system you are using.\nMost systems use a page size of 4KB in the heap, so, that is the amount of memory that is normally\nallocated in each call by `page_allocator()`. That is why, `page_allocator()` is considered a\nfast, but also \"wasteful\" allocator in Zig. Because it allocates a big amount of memory\nin each call, and you most likely will not need that much memory in your program.\n\n### Buffer allocators\n\nThe `FixedBufferAllocator()` and `ThreadSafeFixedBufferAllocator()` are allocator objects that\nwork with a fixed sized buffer object at the back. In other words, they use a fixed sized buffer\nobject as the basis for the memory. When you ask these allocator objects to allocate some memory for you,\nthey are essentially reserving some amount of space inside this fixed sized buffer object for you to use.\n\nThis means that, in order to use these allocators, you must first create a buffer object in your code,\nand then, give this buffer object as an input to these allocators.\n\nThis also means that, these allocator objects can allocate memory both in the stack or in the heap.\nEverything depends on where the buffer object that you provide lives. If this buffer object lives\nin the stack, then, the memory allocated is \"stack-based\". But if it lives on the heap, then,\nthe memory allocated is \"heap-based\".\n\n\nIn the example below, I'm creating a `buffer` object on the stack that is 10 elements long.\nNotice that I give this `buffer` object to the `FixedBufferAllocator()` constructor.\nNow, because this `buffer` object is 10 elements long, this means that I am limited to this space.\nI cannot allocate more than 10 elements with this allocator object. If I try to\nallocate more than that, the `alloc()` method will return an `OutOfMemory` error value.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar buffer: [10]u8 = undefined;\nfor (0..buffer.len) |i| {\n    buffer[i] = 0; // Initialize to zero\n}\n\nvar fba = std.heap.FixedBufferAllocator.init(&buffer);\nconst allocator = fba.allocator();\nconst input = try allocator.alloc(u8, 5);\ndefer allocator.free(input);\n```\n:::\n\n\n\n\n\nRemember, the memory allocated by these allocator objects can be either from\nthe stack, or, from the heap. It all depends on where the buffer object that you provide lives.\nIn the above example, the `buffer` object lives in the stack, and, therefore, the memory allocated\nis based in the stack. But what if it was based on the heap?\n\nAs we described at @sec-stack-overflow, one of the main reasons why you would use the heap,\ninstead of the stack, is to allocate huge amounts of space to store very big objects.\nThus, let's suppose you wanted to use a very big buffer object as the basis for your\nallocator objects. You would have to allocate this very big buffer object on the heap.\nThe example below demonstrates this case.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst heap = std.heap.page_allocator;\nconst memory_buffer = try heap.alloc(\n    u8, 100 * 1024 * 1024 // 100 MB memory\n);\ndefer heap.free(memory_buffer);\nvar fba = std.heap.FixedBufferAllocator.init(\n    memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst input = try allocator.alloc(u8, 1000);\ndefer allocator.free(input);\n```\n:::\n\n\n\n\n\n\n\n### Arena allocator {#sec-arena-allocator}\n\nThe `ArenaAllocator()` is an allocator object that takes a child allocator as input. The idea behind the `ArenaAllocator()` in Zig\nis similar to the concept of \"arenas\" in the programming language Go[^go-arena]. It is an allocator object that allows you\nto allocate memory as many times you want, but free all memory only once.\nIn other words, if you have, for example, called 5 times the method `alloc()` of an `ArenaAllocator()` object, you can\nfree all the memory you allocated over these 5 calls at once, by simply calling the `deinit()` method of the same `ArenaAllocator()` object.\n\n[^go-arena]: <https://go.dev/src/arena/arena.go>\n\nIf you give, for example, a `GeneralPurposeAllocator()` object as input to the `ArenaAllocator()` constructor, like in the example below, then, the allocations\nyou perform with `alloc()` will actually be made with the underlying object `GeneralPurposeAllocator()` that was passed.\nSo, with an arena allocator, any new memory you ask for is allocated by the child allocator. The only thing that an arena allocator\nreally does is help you to free all the memory you allocated multiple times with just a single command. In the example\nbelow, I called `alloc()` 3 times. So, if I did not use an arena allocator, then, I would need to call\n`free()` 3 times to free all the allocated memory.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nvar aa = std.heap.ArenaAllocator.init(gpa.allocator());\ndefer aa.deinit();\nconst allocator = aa.allocator();\n\nconst in1 = try allocator.alloc(u8, 5);\nconst in2 = try allocator.alloc(u8, 10);\nconst in3 = try allocator.alloc(u8, 15);\n_ = in1; _ = in2; _ = in3;\n```\n:::\n\n\n\n\n\n\n\n### The `alloc()` and `free()` methods\n\nIn the code example below, we are accessing the `stdin`, which is\nthe standard input channel, to receive an input from the\nuser. We read the input given by the user with the `readUntilDelimiterOrEof()`\nmethod.\n\nNow, after reading the input of the user, we need to store this input somewhere in\nour program. That is why I use an allocator in this example. I use it to allocate some\namount of memory to store this input given by the user. More specifically, the method `alloc()`\nof the allocator object is used to allocate an array capable of storing 50 `u8` values.\n\nNotice that this `alloc()` method receives two inputs. The first one, is a type.\nThis defines what type of values the allocated array will store. In the example\nbelow, we are allocating an array of unsigned 8-bit integers (`u8`). But\nyou can create an array to store any type of value you want. Next, on the second argument, we\ndefine the size of the allocated array, by specifying how many elements\nthis array will contain. In the case below, we are allocating an array of 50 elements.\n\nAt @sec-zig-strings we described that strings in Zig are simply arrays of characters.\nEach character is represented by a `u8` value. So, this means that the array that\nwas allocated in the object `input` is capable of storing a string that is\n50-characters long.\n\nSo, in essence, the expression `var input: [50]u8 = undefined` would create\nan array for 50 `u8` values in the stack of the current scope. But, you\ncan allocate the same array in the heap by using the expression `var input = try allocator.alloc(u8, 50)`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdin = std.io.getStdIn();\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var input = try allocator.alloc(u8, 50);\n    defer allocator.free(input);\n    for (0..input.len) |i| {\n        input[i] = 0; // initialize all fields to zero.\n    }\n    // read user input\n    const input_reader = stdin.reader();\n    _ = try input_reader.readUntilDelimiterOrEof(\n        input,\n        '\\n'\n    );\n    std.debug.print(\"{s}\\n\", .{input});\n}\n```\n:::\n\n\n\n\n\nAlso, notice that in this example, we use the `defer` keyword (which I described at @sec-defer) to run a small\npiece of code at the end of the current scope, which is the expression `allocator.free(input)`.\nWhen you execute this expression, the allocator will free the memory that it allocated\nfor the `input` object.\n\nWe have talked about this at @sec-heap. You **should always** explicitly free any memory that you allocate\nusing an allocator! You do that by using the `free()` method of the same allocator object you\nused to allocate this memory. The `defer` keyword is used in this example only to help us execute\nthis free operation at the end of the current scope.\n\n\n### The `create()` and `destroy()` methods\n\nWith the `alloc()` and `free()` methods, you can allocate memory to store multiple elements\nat once. In other words, with these methods, we always allocate an array to store multiple elements at once.\nBut what if you need enough space to store just a single item? Should you\nallocate an array of a single element through `alloc()`?\n\nThe answer is no! In this case,\nyou should use the `create()` method of the allocator object.\nEvery allocator object offers the `create()` and `destroy()` methods,\nwhich are used to allocate and free memory for a single item, respectively.\n\nSo, in essence, if you want to allocate memory to store an array of elements, you\nshould use `alloc()` and `free()`. But if you need to store just a single item,\nthen, the `create()` and `destroy()` methods are ideal for you.\n\nIn the example below, I'm defining a struct to represent an user of some sort.\nIt could be an user for a game, or a software to manage resources, it doesn't mater.\nNotice that I use the `create()` method this time, to store a single `User` object\nin the program. Also notice that I use the `destroy()` method to free the memory\nused by this object at the end of the scope.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst User = struct {\n    id: usize,\n    name: []const u8,\n\n    pub fn init(id: usize, name: []const u8) User {\n        return .{ .id = id, .name = name };\n    }\n};\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const user = try allocator.create(User);\n    defer allocator.destroy(user);\n\n    user.* = User.init(0, \"Pedro\");\n}\n```\n:::\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Memory and Allocators\n\n\nIn this chapter, we will talk about memory. How does Zig control memory? What\ncommon tools are used? Are there any important aspects that make memory\ndifferent/special in Zig? You will find the answers here.\n\nComputers fundamentally rely on memory to function. This memory acts as a temporary storage\nspace for the data and values generated during computations. Without memory, the core\nconcepts of \"variables\" and \"objects\" in programming languages would be impossible.\n\n\n\n\n## Memory spaces\n\nEvery object that you create in your Zig source code needs to be stored somewhere,\nin your computer's memory. Depending on where and how you define your object, Zig\nwill use a different \"memory space\", or a different\ntype of memory to store this object.\n\nEach type of memory normally serves for different purposes.\nIn Zig, there are 3 types of memory (or 3 different memory spaces) that we care about. They are:\n\n- Global data register (or the \"global data section\");\n- Stack;\n- Heap;\n\n\n### Compile-time known versus runtime known {#sec-compile-time}\n\nOne strategy that Zig uses to decide where it will store each object that you declare, is by looking\nat the value of this particular object. More specifically, by investigating if this value is\nknown at \"compile-time\" or at \"runtime\".\n\nWhen you write a program in Zig, the values of some of the objects that you write in your program are *known\nat compile time*. Meaning that, when you compile your Zig source code, during the compilation process,\nthe `zig` compiler can figure out the exact value of a particular object\nthat exists in your source code.\nKnowing the length (or the size) of each object is also important. So the length (or the size) of each object that you write in your program is,\nin some cases, *known at compile time*.\n\nThe `zig` compiler cares more about knowing the length (or the size) of a particular object\n, than to know its actual value. But, if the `zig` compiler knows the value of the object, then, it\nautomatically knows the size of this object. Because it can simply calculate the\nsize of the object by looking at the size of the value.\n\nTherefore, the priority for the `zig` compiler is to discover the size of each object in your source code.\nIf the value of the object in question is known at compile-time, then, the `zig` compiler\nautomatically knows the size/length of this object. But if the value of this object is not\nknown at compile-time, then, the size of this object is only known at compile-time if,\nand only if, the type of this object has a known fixed size.\n\nIn order for a type to have a known fixed size, this type must have data members whose size is fixed.\nIf this type includes, for example, a variable sized array in it, then, this type does not have a known\nfixed size. Because this array can have any size at runtime\n(i.e. it can be an array of 2 elements, or 50 elements, or 1 thousand elements, etc.).\n\nFor example, a string object, which internally is an array of constant u8 values (`[]const u8`)\nhas a variable size. It can be a string object with 100 or 500 characters in it. If we do not\nknow at compile-time, which exact string will be stored inside this string object, then, we cannot calculate\nthe size of this string object at compile-time. So, any type, or any struct declaration that you make, that\nincludes a string data member that does not have an explicit fixed size, makes this type, or this\nnew struct that you are declaring, a type that does not have a known fixed size at compile-time.\n\nIn contrast, if the type of this struct that you are declaring, includes a data member that is an array,\nbut this array has a known fixed size, like `[60]u8` (which declares an array of 60 `u8` values), then,\nthis type, or, this struct that you are declaring, becomes a type with a known fixed size at compile-time.\nAnd because of that, in this case, the `zig` compiler does not need to know at compile-time the exact value of\nany object of this type. Since the compiler can find the necessary size to store this object by\nlooking at the size of its type.\n\n\nLet's look at an example. In the source code below, we have two constant objects (`name` and `array`) declared.\nBecause the values of these particular objects are written down, in the source code itself (`\"Pedro\"`\nand the number sequence from 1 to 4), the `zig` compiler can easily discover the values of these constant\nobjects (`name` and `array`) during the compilation process.\nThis is what \"known at compile time\" means. It refers to any object that you have in your Zig source code\nwhose value can be identified at compile time.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn input_length(input: []const u8) usize {\n    const n = input.len;\n    return n;\n}\n\npub fn main() !void {\n    const name = \"Pedro\";\n    const array = [_]u8{1, 2, 3, 4};\n    _ = name; _ = array;\n}\n```\n:::\n\n\n\n\nThe other side of the spectrum are objects whose values are not known at compile time.\nFunction arguments are a classic example of this. Because the value of each function\nargument depends on the value that you assign to this particular argument,\nwhen you call the function.\n\nFor example, the function `input_length()` contains an argument named `input`, which is an array of constant `u8` integers (`[]const u8`).\nIt is impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length\nof this particular argument. Because it is an array that do not have a fixed size specified explicitly in the argument type annotation.\n\nSo, we know that this `input` argument will be an array of `u8` integers. But we do not know at compile-time, its value, and neither his size.\nThis information is known only at runtime, which is the period of time when you program is executed.\nAs a consequence, the value of the expression `input.len` is also known only at runtime.\nThis is an intrinsic characteristic of any function. Just remember that the value of function arguments is usually not \"compile-time known\".\n\nHowever, as I mentioned earlier, what really matters to the compiler is to know the size of the object\nat compile-time, and not necessarily its value. So, although we don't know the value of the object `n`, which is the result of the expression\n`input.len`, at compile-time, we do know its size. Because the expression `input.len` always returns a value of type `usize`,\nand the type `usize` has a known fixed size.\n\n\n\n### Global data register\n\nThe global data register is a specific section of the executable of your Zig program, that is responsible\nfor storing any value that is known at compile time.\n\nEvery constant object whose value is known at compile time that you declare in your source code,\nis stored in the global data register. Also, every literal value that you write in your source code,\nsuch as the string `\"this is a string\"`, or the integer `10`, or a boolean value such as `true`,\nis also stored in the global data register.\n\nHonestly, you don't need to care much about this memory space. Because you can't control it,\nyou can't deliberately access it or use it for your own purposes.\nAlso, this memory space does not affect the logic of your program.\nIt simply exists in your program.\n\n\n### Stack vs Heap\n\nIf you are familiar with system's programming, or just low-level programming in general, you\nprobably have heard of the \"duel\" between Stack vs Heap. These are two different types of memory,\nor different memory spaces, which are both available in Zig.\n\nThese two types of memory don't actually duel with\neach other. This is a common mistake that beginners have, when seeing \"x vs y\" styles of\ntabloid headlines. These two types of memory are actually complementary to each other.\nSo, in almost every Zig program that you ever write, you will likely use a combination of both.\nI will describe each memory space in detail over the next sections. But for now, I just want to\nstablish the main difference between these two types of memory.\n\nIn essence, the stack memory is normally used to store values whose length is fixed and known\nat compile time. In contrast, the heap memory is a *dynamic* type of memory space, meaning that, it is\nused to store values whose length might grow during the execution (runtime) of your program [@jenny2022].\n\nLengths that grow during runtime are intrinsically associated with \"runtime known\" type of values.\nIn other words, if you have an object whose length might grow during runtime, then, the length\nof this object becomes not known at compile time. If the length is not known at compile-time,\nthe value of this object also becomes not known at compile-time.\nThese types of objects should be stored in the heap memory space, which is\na dynamic memory space, which can grow or shrink to fit the size of your objects.\n\n\n\n### Stack {#sec-stack}\n\nThe stack is a type of memory that uses the power of the *stack data structure*, hence the name.\nA \"stack\" is a type of *data structure* that uses a \"last in, first out\" (LIFO) mechanism to store the values\nyou give it to. I imagine you are familiar with this data structure.\nBut, if you are not, the [Wikipedia page](https://en.wikipedia.org/wiki/Stack_(abstract_data_type))[^wiki-stack]\n, or, the [Geeks For Geeks page](https://www.geeksforgeeks.org/stack-data-structure/)[^geek-stack] are both\nexcellent and easy resources to fully understand how this data structure works.\n\n[^wiki-stack]: <https://en.wikipedia.org/wiki/Stack_(abstract_data_type)>\n[^geek-stack]: <https://www.geeksforgeeks.org/stack-data-structure/>\n\nSo, the stack memory space is a type of memory that stores values using a stack data structure.\nIt adds and removes values from the memory by following a \"last in, first out\" (LIFO) principle.\n\nEvery time you make a function call in Zig, an amount of space in the stack is\nreserved for this particular function call [@jenny2022; @zigdocs].\nThe value of each function argument given to the function in this function call is stored in this\nstack space. Also, every local object that you declare inside the function scope is\nusually stored in this same stack space.\n\n\nLooking at the example below, the object `result` is a local object declared inside the scope of the `add()`\nfunction. Because of that, this object is stored inside the stack space reserved for the `add()` function.\nThe `r` object (which is declared outside of the `add()` function scope) is also stored in the stack.\nBut since it is declared in the \"outer\" scope, this object is stored in the\nstack space that belongs to this outer scope.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn add(x: u8, y: u8) u8 {\n    const result = x + y;\n    return result;\n}\n\npub fn main() !void {\n    const r = add(5, 27);\n    _ = r;\n}\n```\n:::\n\n\n\n\n\nSo, any object that you declare inside the scope of a function is always stored inside\nthe space that was reserved for that particular function in the stack memory. This\nalso counts for any object declared inside the scope of your `main()` function for example.\nAs you would expect, in this case, they\nare stored inside the stack space reserved for the `main()` function.\n\nOne very important detail about the stack memory is that **it frees itself automatically**.\nThis is very important, remember that. When objects are stored in the stack memory,\nyou don't have the work (or the responsibility) of freeing/destroying these objects.\nBecause they will be automatically destroyed once the stack space is freed at the end of the function scope.\n\nSo, once the function call returns (or ends, if you prefer to call it this way)\nthe space that was reserved in the stack is destroyed, and all of the objects that were in that space goes away with it.\nThis mechanism exists because this space, and the objects within it, are not necessary anymore,\nsince the function \"finished its business\".\nUsing the `add()` function that we exposed above as an example, it means that the object `result` is automatically\ndestroyed once the function returns.\n\n::: {.callout-important}\nLocal objects that are stored in the stack space of a function are automatically\nfreed/destroyed at the end of the function scope.\n:::\n\n\nThis same logic applies to any other special structure in Zig that have its own scope by surrounding\nit with curly braces (`{}`).\nFor loops, while loops, if else statements, etc. For example, if you declare any local\nobject in the scope of a for loop, this local object is accessible only within the scope\nof this particular for loop. Because once the scope of this for loop ends, the space in the stack\nreserved for this for loop is freed.\nThe example below demonstrates this idea.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This does not compile successfully!\nconst a = [_]u8{0, 1, 2, 3, 4};\nfor (0..a.len) |i| {\n    const index = i;\n    _ = index;\n}\n// Trying to use an object that was\n// declared in the for loop scope,\n// and that does not exist anymore.\nstd.debug.print(\"{d}\\n\", .{index});\n```\n:::\n\n\n\n\n\n\nOne important consequence of this mechanism is that, once the function returns, you can no longer access any memory\naddress that was inside the space in the stack reserved for this particular function. Because this space was\ndestroyed. This means that, if this local object is stored in the stack,\nyou cannot make a function that **returns a pointer to this object**.\n\nThink about that for a second. If all local objects in the stack are destroyed at the end of the function scope, why\nwould you even consider returning a pointer to one of these objects? This pointer is at best,\ninvalid, or, more likely, \"undefined\".\n\nConclusion, it is totally fine to write a function that returns the local object\nitself as result, because then, you return the value of that object as the result.\nBut, if this local object is stored in the stack, you should never write a function\nthat returns a pointer to this local object. Because the memory address pointed by the pointer\nno longer exists.\n\n\nSo, using again the `add()` function as an example, if you rewrite this function so that it\nreturns a pointer to the local object `result`, the `zig` compiler will actually compile\nyour program, with no warnings or errors. At first glance, it looks that this is good code\nthat works as expected. But this is a lie!\n\nIf you try to take a look at the value inside of the `r` object,\nor, if you try to use this `r` object in another expression\nor function call, then, you would have undefined behaviour, and major\nbugs in your program [@zigdocs, see \"Lifetime and Ownership\"[^life] and \"Undefined Behaviour\"[^undef] sections].\n\n[^life]: <https://ziglang.org/documentation/master/#Lifetime-and-Ownership>\n[^undef]: <https://ziglang.org/documentation/master/#Undefined-Behavior>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn add(x: u8, y: u8) *const u8 {\n    const result = x + y;\n    return &result;\n}\n\npub fn main() !void {\n    // This code compiles successfully. But it has\n    // undefined behaviour. Never do this!!!\n    // The `r` object is undefined!\n    const r = add(5, 27); _ = r;\n}\n```\n:::\n\n\n\n\nThis \"invalid pointer to stack variable\" problem is very known across many programming language communities.\nIf you try to do the same thing, for example, in a C or C++ program (i.e. returning an address to\na local object stored in the stack), you would also get undefined behaviour\nin the program.\n\n::: {.callout-important}\nIf a local object in your function is stored in the stack, you should never\nreturn a pointer to this local object from the function. Because\nthis pointer will always become undefined after the function returns, since the stack space of the function\nis destroyed at the end of its scope.\n:::\n\nBut what if you really need to use this local object in some way after your function returns?\nHow can you do this? The answer is: \"in the same you would do if this was a C or C++ program. By returning\nan address to an object stored in the heap\". The heap memory has a much more flexible lifecycle,\nand allows you to get a valid pointer to a local object of a function that already returned\nfrom its scope.\n\n\n### Heap {#sec-heap}\n\nOne important limitation of the stack, is that, only objects whose length/size is known at compile-time can be\nstored in it. In contrast, the heap is a much more dynamic\n(and flexible) type of memory. It is the perfect type of memory to use\nfor objects whose size/length might grow during the execution of your program.\n\nVirtually any application that behaves as a server is a classic use case of the heap.\nA HTTP server, a SSH server, a DNS server, a LSP server, ... any type of server.\nIn summary, a server is a type of application that runs for long periods of time,\nand that serves (or \"deals with\") any incoming request that reaches this particular server.\n\nThe heap is a good choice for this type of system, mainly because the server does not know upfront\nhow many requests it will receive from users, while it is active. It could be one single request,\nor, 5 thousand requests, or, it could also be zero requests.\nThe server needs to have the ability to allocate and manage its memory according to how many requests it receives.\n\nAnother key difference between the stack and the heap, is that the heap is a type\nof memory that you, the programmer, have complete control over. This makes the heap a\nmore flexible type of memory, but it also makes it harder to work with. Because you,\nthe programmer, is responsible for managing everything related to it. Including where the memory is allocated,\nhow much memory is allocated, and where this memory is freed.\n\n> Unlike stack memory, heap memory is allocated explicitly by programmers and it won’t be deallocated until it is explicitly freed [@jenny2022].\n\nTo store an object in the heap, you, the programmer, needs to explicitly tells Zig to do so,\nby using an allocator to allocate some space in the heap. At @sec-allocators, I will present how you can use allocators to allocate memory\nin Zig.\n\n::: {.callout-important}\nEvery memory you allocate in the heap needs to be explicitly freed by you, the programmer.\n:::\n\nThe majority of allocators in Zig do allocate memory on the heap. But some exceptions to this rule are\n`ArenaAllocator()` and `FixedBufferAllocator()`. The `ArenaAllocator()` is a special\ntype of allocator that works in conjunction with a second type of allocator.\nOn the other side, the `FixedBufferAllocator()` is an allocator that works based on\nbuffer objects created on the stack. This means that the `FixedBufferAllocator()` makes\nallocations only on the stack.\n\n\n\n\n### Summary\n\nAfter discussing all of these boring details, we can quickly recap what we learned.\nIn summary, the Zig compiler will use the following rules to decide where each\nobject you declare is stored:\n\n1. every literal value (such as `\"this is string\"`, `10`, or `true`) is stored in the global data section.\n1. every constant object (`const`) whose value **is known at compile-time** is also stored in the global data section.\n1. every object (constant or not) whose length/size **is known at compile time** is stored in the stack space for the current scope.\n1. if an object is created with the method `alloc()` or `create()` of an allocator object, this object is stored in the memory space used by this particular allocator object. Most of allocators available in Zig use the heap memory, so, this object is likely stored in the heap (`FixedBufferAllocator()` is an exception to that).\n1. the heap can only be accessed through allocators. If your object was not created through the `alloc()` or `create()` methods of an allocator object, then, he is most certainly not an object stored in the heap.\n\n\n## Stack overflows {#sec-stack-overflow}\n\nAllocating memory on the stack is generally faster than allocating it on the heap.\nBut this better performance comes with many restrictions. We have already discussed\nmany of these restrictions of the stack at @sec-stack. But there is one more important\nlimitation that I want to talk about, which is the size of the stack itself.\n\nThe stack is limited in size. This size varies from computer to computer, and it depends on\na lot of things (the computer architecture, the operating system, etc.). Nevertheless, this size is usually\nnot that big. This is why we normally use the stack to store only temporary and small objects in memory.\n\nIn essence, if you try to make an allocation on the stack, that is so big that exceeds the stack size limit,\na *stack overflow* happens, and your program just crashes as a result of that. In other words, a stack overflow happens when\nyou attempt to use more space than is available on the stack.\n\nThis type of problem is very similar to a *buffer overflow*, i.e. you are trying to use more space\nthan is available in the \"buffer object\". However, a stack overflow always cause your program to crash,\nwhile a buffer overflow not always cause your program to crash (although it often does).\n\nYou can see an example of a stack overflow in the example below. We are trying to allocate a very big array of `u64` values\non the stack. You can see below that this program does not run succesfully, because it crashed\nwith a \"segmentation fault\" error message.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar very_big_alloc: [1000 * 1000 * 24]u64 = undefined;\n@memset(very_big_alloc[0..], 0);\n```\n:::\n\n\n\n\n```\nSegmentation fault (core dumped)\n```\n\nThis segmentation fault error is a result of the stack overflow that was caused by the big\nmemory allocation made on the stack, to store the `very_big_alloc` object.\nThis is why very big objects are usually stored on the heap, instead of the stack.\n\n\n\n## Allocators {#sec-allocators}\n\nOne key aspect about Zig, is that there are \"no hidden-memory allocations\" in Zig.\nWhat that really means, is that \"no allocations happen behind your back in the standard library\" [@zigguide].\n\nThis is a known problem, especially in C++. Because in C++, there are some operators that do allocate\nmemory behind the scene, and there is no way for you to know that, until you actually read the\nsource code of these operators, and find the memory allocation calls.\nMany programmers find this behaviour annoying and hard to keep track of.\n\nBut, in Zig, if a function, an operator, or anything from the standard library\nneeds to allocate some memory during its execution, then, this function/operator needs to receive (as input) an allocator\nprovided by the user, to actually be able to allocate the memory it needs.\n\nThis creates a clear distinction between functions that \"do not\" from those that \"actually do\"\nallocate memory. Just look at the arguments of this function.\nIf a function, or operator, has an allocator object as one of its inputs/arguments, then, you know for\nsure that this function/operator will allocate some memory during its execution.\n\nAn example is the `allocPrint()` function from the Zig Standard Library. With this function, you can\nwrite a new string using format specifiers. So, this function is, for example, very similar to the function `sprintf()` in C.\nIn order to write such new string, the `allocPrint()` function needs to allocate some memory to store the\noutput string.\n\nThat is why, the first argument of this function is an allocator object that you, the user/programmer, gives\nas input to the function. In the example below, I am using the `GeneralPurposeAllocator()` as my allocator\nobject. But I could easily use any other type of allocator object from the Zig Standard Library.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst name = \"Pedro\";\nconst output = try std.fmt.allocPrint(\n    allocator,\n    \"Hello {s}!!!\",\n    .{name}\n);\ntry stdout.print(\"{s}\\n\", .{output});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello Pedro!!!\n```\n\n\n:::\n:::\n\n\n\n\n\nYou get a lot of control over where and how much memory this function can allocate.\nBecause it is you, the user/programmer, that provides the allocator for the function to use.\nThis makes \"total control\" over memory management easier to achieve in Zig.\n\n### What are allocators?\n\nAllocators in Zig are objects that you can use to allocate memory for your program.\nThey are similar to the memory allocating functions in C, like `malloc()` and `calloc()`.\nSo, if you need to use more memory than you initially have, during the execution of your program, you can simply ask\nfor more memory by using an allocator object.\n\nZig offers different types of allocators, and they are usually available through the `std.heap` module of\nthe standard library. Thus, just import the Zig Standard Library into your Zig module (with `@import(\"std\")`), and you can start\nusing these allocators in your code.\n\nFurthermore, every allocator object is built on top of the `Allocator` interface in Zig.\nThis means that, every allocator object you find in Zig must have the methods `alloc()`,\n`create()`, `free()` and `destroy()`. So, you can change the type of allocator you are using,\nbut you don't need to change the function calls to the methods that do the memory allocation\n(and the free memory operations) for your program.\n\n### Why you need an allocator?\n\nAs we described at @sec-stack, everytime you make a function call in Zig,\na space in the stack is reserved for this function call. But the stack\nhas a key limitation which is: every object stored in the stack have a\nknown fixed length.\n\nBut in reality, there are two very common instances where this \"fixed length limitation\" of the stack is a deal braker:\n\n1. the objects that you create inside your function might grow in size during the execution of the function.\n1. sometimes, it is impossible to know upfront how many inputs you will receive, or how big this input will be.\n\nAlso, there is another instance where you might want to use an allocator, which is when you want to write a function that returns a pointer\nto a local object. As I described at @sec-stack, you cannot do that if this local object is stored in the\nstack. However, if this object is stored in the heap, then, you can return a pointer to this object at the\nend of the function. Because you (the programmer) control the lifetime of any heap memory that you allocate. You decide\nwhen this memory gets destroyed/freed.\n\nThese are common situations where the stack is not good for.\nThat is why you need a different memory management strategy to\nstore these objects inside your function. You need to use\na memory type that can grow together with your objects, or that you\ncan control the lifetime of this memory.\nThe heap fits this description.\n\nAllocating memory on the heap is commonly known as dynamic memory management. As the objects you create grow in size\nduring the execution of your program, you grow the amount of memory\nyou have by allocating more memory in the heap to store these objects.\nAnd you do that in Zig, by using an allocator object.\n\n\n### The different types of allocators\n\n\nAt the moment of the writing of this book, in Zig, we have 6 different\nallocators available in the standard library:\n\n- `GeneralPurposeAllocator()`.\n- `page_allocator()`.\n- `FixedBufferAllocator()` and `ThreadSafeFixedBufferAllocator()`.\n- `ArenaAllocator()`.\n- `c_allocator()` (requires you to link to libc).\n\n\nEach allocator has its own perks and limitations. All allocators, except `FixedBufferAllocator()` and `ArenaAllocator()`,\nare allocators that use the heap memory. So any memory that you allocate with\nthese allocators, will be placed in the heap.\n\n### General-purpose allocators\n\nThe `GeneralPurposeAllocator()`, as the name suggests, is a \"general purpose\" allocator. You can use it for every type\nof task. In the example below, I'm allocating enough space to store a single integer in the object `some_number`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const some_number = try allocator.create(u32);\n    defer allocator.destroy(some_number);\n\n    some_number.* = @as(u32, 45);\n}\n```\n:::\n\n\n\n\n\nWhile useful, you might want to use the `c_allocator()`, which is a alias to the C standard allocator `malloc()`. So, yes, you can use\n`malloc()` in Zig if you want to. Just use the `c_allocator()` from the Zig standard library. However,\nif you do use `c_allocator()`, you must link to Libc when compiling your source code with the\n`zig` compiler, by including the flag `-lc` in your compilation process.\nIf you do not link your source code to Libc, Zig will not be able to find the\n`malloc()` implementation in your system.\n\n### Page allocator\n\nThe `page_allocator()` is an allocator that allocates full pages of memory in the heap. In other words,\nevery time you allocate memory with `page_allocator()`, a full page of memory in the heap is allocated,\ninstead of just a small piece of it.\n\nThe size of this page depends on the system you are using.\nMost systems use a page size of 4KB in the heap, so, that is the amount of memory that is normally\nallocated in each call by `page_allocator()`. That is why, `page_allocator()` is considered a\nfast, but also \"wasteful\" allocator in Zig. Because it allocates a big amount of memory\nin each call, and you most likely will not need that much memory in your program.\n\n### Buffer allocators\n\nThe `FixedBufferAllocator()` and `ThreadSafeFixedBufferAllocator()` are allocator objects that\nwork with a fixed sized buffer object at the back. In other words, they use a fixed sized buffer\nobject as the basis for the memory. When you ask these allocator objects to allocate some memory for you,\nthey are essentially reserving some amount of space inside this fixed sized buffer object for you to use.\n\nThis means that, in order to use these allocators, you must first create a buffer object in your code,\nand then, give this buffer object as an input to these allocators.\n\nThis also means that, these allocator objects can allocate memory both in the stack or in the heap.\nEverything depends on where the buffer object that you provide lives. If this buffer object lives\nin the stack, then, the memory allocated is \"stack-based\". But if it lives on the heap, then,\nthe memory allocated is \"heap-based\".\n\n\nIn the example below, I'm creating a `buffer` object on the stack that is 10 elements long.\nNotice that I give this `buffer` object to the `FixedBufferAllocator()` constructor.\nNow, because this `buffer` object is 10 elements long, this means that I am limited to this space.\nI cannot allocate more than 10 elements with this allocator object. If I try to\nallocate more than that, the `alloc()` method will return an `OutOfMemory` error value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar buffer: [10]u8 = undefined;\nfor (0..buffer.len) |i| {\n    buffer[i] = 0; // Initialize to zero\n}\n\nvar fba = std.heap.FixedBufferAllocator.init(&buffer);\nconst allocator = fba.allocator();\nconst input = try allocator.alloc(u8, 5);\ndefer allocator.free(input);\n```\n:::\n\n\n\n\nRemember, the memory allocated by these allocator objects can be either from\nthe stack, or, from the heap. It all depends on where the buffer object that you provide lives.\nIn the above example, the `buffer` object lives in the stack, and, therefore, the memory allocated\nis based in the stack. But what if it was based on the heap?\n\nAs we described at @sec-stack-overflow, one of the main reasons why you would use the heap,\ninstead of the stack, is to allocate huge amounts of space to store very big objects.\nThus, let's suppose you wanted to use a very big buffer object as the basis for your\nallocator objects. You would have to allocate this very big buffer object on the heap.\nThe example below demonstrates this case.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst heap = std.heap.page_allocator;\nconst memory_buffer = try heap.alloc(\n    u8, 100 * 1024 * 1024 // 100 MB memory\n);\ndefer heap.free(memory_buffer);\nvar fba = std.heap.FixedBufferAllocator.init(\n    memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst input = try allocator.alloc(u8, 1000);\ndefer allocator.free(input);\n```\n:::\n\n\n\n\n\n\n### Arena allocator {#sec-arena-allocator}\n\nThe `ArenaAllocator()` is an allocator object that takes a child allocator as input. The idea behind the `ArenaAllocator()` in Zig\nis similar to the concept of \"arenas\" in the programming language Go[^go-arena]. It is an allocator object that allows you\nto allocate memory as many times you want, but free all memory only once.\nIn other words, if you have, for example, called 5 times the method `alloc()` of an `ArenaAllocator()` object, you can\nfree all the memory you allocated over these 5 calls at once, by simply calling the `deinit()` method of the same `ArenaAllocator()` object.\n\n[^go-arena]: <https://go.dev/src/arena/arena.go>\n\nIf you give, for example, a `GeneralPurposeAllocator()` object as input to the `ArenaAllocator()` constructor, like in the example below, then, the allocations\nyou perform with `alloc()` will actually be made with the underlying object `GeneralPurposeAllocator()` that was passed.\nSo, with an arena allocator, any new memory you ask for is allocated by the child allocator. The only thing that an arena allocator\nreally does is help you to free all the memory you allocated multiple times with just a single command. In the example\nbelow, I called `alloc()` 3 times. So, if I did not use an arena allocator, then, I would need to call\n`free()` 3 times to free all the allocated memory.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nvar aa = std.heap.ArenaAllocator.init(gpa.allocator());\ndefer aa.deinit();\nconst allocator = aa.allocator();\n\nconst in1 = try allocator.alloc(u8, 5);\nconst in2 = try allocator.alloc(u8, 10);\nconst in3 = try allocator.alloc(u8, 15);\n_ = in1; _ = in2; _ = in3;\n```\n:::\n\n\n\n\n\n\n### The `alloc()` and `free()` methods\n\nIn the code example below, we are accessing the `stdin`, which is\nthe standard input channel, to receive an input from the\nuser. We read the input given by the user with the `readUntilDelimiterOrEof()`\nmethod.\n\nNow, after reading the input of the user, we need to store this input somewhere in\nour program. That is why I use an allocator in this example. I use it to allocate some\namount of memory to store this input given by the user. More specifically, the method `alloc()`\nof the allocator object is used to allocate an array capable of storing 50 `u8` values.\n\nNotice that this `alloc()` method receives two inputs. The first one, is a type.\nThis defines what type of values the allocated array will store. In the example\nbelow, we are allocating an array of unsigned 8-bit integers (`u8`). But\nyou can create an array to store any type of value you want. Next, on the second argument, we\ndefine the size of the allocated array, by specifying how many elements\nthis array will contain. In the case below, we are allocating an array of 50 elements.\n\nAt @sec-zig-strings we described that strings in Zig are simply arrays of characters.\nEach character is represented by a `u8` value. So, this means that the array that\nwas allocated in the object `input` is capable of storing a string that is\n50-characters long.\n\nSo, in essence, the expression `var input: [50]u8 = undefined` would create\nan array for 50 `u8` values in the stack of the current scope. But, you\ncan allocate the same array in the heap by using the expression `var input = try allocator.alloc(u8, 50)`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdin = std.io.getStdIn();\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var input = try allocator.alloc(u8, 50);\n    defer allocator.free(input);\n    for (0..input.len) |i| {\n        input[i] = 0; // initialize all fields to zero.\n    }\n    // read user input\n    const input_reader = stdin.reader();\n    _ = try input_reader.readUntilDelimiterOrEof(\n        input,\n        '\\n'\n    );\n    std.debug.print(\"{s}\\n\", .{input});\n}\n```\n:::\n\n\n\n\nAlso, notice that in this example, we use the `defer` keyword (which I described at @sec-defer) to run a small\npiece of code at the end of the current scope, which is the expression `allocator.free(input)`.\nWhen you execute this expression, the allocator will free the memory that it allocated\nfor the `input` object.\n\nWe have talked about this at @sec-heap. You **should always** explicitly free any memory that you allocate\nusing an allocator! You do that by using the `free()` method of the same allocator object you\nused to allocate this memory. The `defer` keyword is used in this example only to help us execute\nthis free operation at the end of the current scope.\n\n\n### The `create()` and `destroy()` methods\n\nWith the `alloc()` and `free()` methods, you can allocate memory to store multiple elements\nat once. In other words, with these methods, we always allocate an array to store multiple elements at once.\nBut what if you need enough space to store just a single item? Should you\nallocate an array of a single element through `alloc()`?\n\nThe answer is no! In this case,\nyou should use the `create()` method of the allocator object.\nEvery allocator object offers the `create()` and `destroy()` methods,\nwhich are used to allocate and free memory for a single item, respectively.\n\nSo, in essence, if you want to allocate memory to store an array of elements, you\nshould use `alloc()` and `free()`. But if you need to store just a single item,\nthen, the `create()` and `destroy()` methods are ideal for you.\n\nIn the example below, I'm defining a struct to represent an user of some sort.\nIt could be an user for a game, or a software to manage resources, it doesn't mater.\nNotice that I use the `create()` method this time, to store a single `User` object\nin the program. Also notice that I use the `destroy()` method to free the memory\nused by this object at the end of the scope.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst User = struct {\n    id: usize,\n    name: []const u8,\n\n    pub fn init(id: usize, name: []const u8) User {\n        return .{ .id = id, .name = name };\n    }\n};\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const user = try allocator.create(User);\n    defer allocator.destroy(user);\n\n    user.* = User.init(0, \"Pedro\");\n}\n```\n:::\n",
+    "supporting": [
+      "01-memory_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/02-debugging/execute-results/html.json b/_freeze/Chapters/02-debugging/execute-results/html.json
index dcd81837..84d21f6f 100644
--- a/_freeze/Chapters/02-debugging/execute-results/html.json
+++ b/_freeze/Chapters/02-debugging/execute-results/html.json
@@ -1,8 +1,8 @@
 {
-  "hash": "d955858e8c96c11c36427af044c591f0",
+  "hash": "bcdaca2a35184fc7c695d2616783b520",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Debugging Zig applications\n\nBeing able to debug your applications is essential for any programmer who wants to\ndo serious programming in any language. That is why, in this chapter, we are going to talk about the\navailable strategies and tools to debug applications written in Zig.\n\n\n## Print debugging\n\nWe begin with the classic and battle-tested *print debugging* strategy.\nThe key advantage that debugging offers you is *visibility*.\nWith *print statements* you can easily see what results and objects\nare being produced by your application.\n\nThat is the essence of *print debugging*. Is to use\nprint expressions to see the values that are being generated by your program,\nand, as a result, get a much better understanding of how your program\nis behaving.\n\nMany programmers often resort to the print functions in Zig, such as the `stdout.print()`,\nor, the `std.debug.print()`, to get a better understanding of their programs.\nThis is a known and old strategy that is very simple and effective, and it is better known within\nthe programming community as *print debugging*.\nIn Zig, you can print information to the `stdout` or `stderr` streams of your system.\n\nLet's begin with `stdout`. First, you\nneed to get access to the `stdout`, by calling the `getStdOut()` method, from\nthe Zig Standard Library. This method returns a *file descriptor* object,\nand, through this object you can read/write to the `stdout`.\nI recommend you to check out all methods available in this object, by [checking the page in\nthe Zig Standard Library Official Reference for the type `File`](https://ziglang.org/documentation/master/std/#std.fs.File)[^zig-fiile-reference].\n\n[^zig-fiile-reference]: <https://ziglang.org/documentation/master/std/#std.fs.File>.\n\nFor our purpose here, which is to write something to the `stdout`, especially to debug our\nprogram, I recommend you to use the `writer()` method, which gives your a *writer* object.\nThis *writer* object offers some helper methods to write stuff into the file descriptor object\nthat represents the `stdout` stream. In special, the `print()` method.\n\n\nThe `print()` method from this *writer* object is a \"print formatter\" type of a function.\nIn other words, this method works exactly like the `printf()` function from C,\nor, like `println!()` from Rust.\nIn the first argument of the function, you specify a template string, and,\nin the second argument, you provide a list of values (or objects) that you want to insert\ninto your template message.\n\nIdeally, the template string in the first argument should contain some format specifier.\nEach format specifier is matched to a value (or object) that you have listed in the second argument.\nSo, if you provided 5 different objects in the second argument, then, the template string\nshould contain 5 format specifiers, one for each object provided.\n\nEach format specifier is represented by a single letter, and\nyou provide this format specifier inside a pair of curly braces. So, if you want to format\nyour object using the string specifier (`s`), then, you can insert the text `{s}` in your template string.\nHere is a quick list of the most used format specifiers:\n\n- `d`: for printing integers and floating-point numbers.\n- `c`: for printing characters.\n- `s`: for printing strings.\n- `p`: for printing memory addresses.\n- `x`: for printing hexadecimal values.\n- `any`: use any compatible format specifier (i.e. it automatically selects a format specifier for you).\n\nThe code example below gives you an example of use of this `print()` method\nwith the `d` format specifier.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    _ = try stdout.print(\"Result: {d}\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\n\n\nIs important to emphasize that, the `stdout.print()` method, as you would expect,\nprint your template string into the `stdout` stream of your system.\nHowever, you can also print your template string into the `stderr` stream\nif your prefer. All you need to do, is to replace the `stdout.print()`\ncall with the function `std.debug.print()`. Like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    std.debug.print(\"Result: {d}\\n\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\n\n\n\nYou could also achieve the exact same result by getting a file descriptor object to `stderr`,\nthen, creating a *writer* object to `stderr`, then, using the `print()` method of this\n*writer* object, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stderr = std.io.getStdErr().writer();\n// some more lines ...\n_ = try stderr.print(\"Result: {d}\", .{result});\n```\n:::\n\n\n\n\n\n\n## Debugging through debuggers\n\nAlthough *print debugging* being a valid and very useful strategy,\nmost programmers prefer to use a debugger to debug their programs.\nSince Zig is a low-level language, you can use either GDB (GNU Debugger),\nor LLDB (LLVM Project Debugger) as your debugger.\n\nBoth debuggers can work with Zig code, and it's a matter of taste here.\nYou choose the debugger of your preference, and you work with it.\nIn this book, I will use LLDB as my debugger on the examples.\n\n\n### Compile your source code in debug mode {#sec-compile-debug-mode}\n\nIn order to debug your program through a debugger, you must compile\nyour source code in `Debug` mode. Because when you compile your\nsource code in other modes (such as `Release`), the compiler usually\nstrips out some essential information that is used by the debugger\nto read and track your program, like PDB (*Program Database*) files.\n\nBy compiling your source code in `Debug` mode, you ensure that the debugger\nwill find the necessary information in your program to debug it.\nBy default, the compiler uses the `Debug` mode when compiling your code.\nHaving this in mind, when you compile your program with the `build-exe`\ncommand (which was described at @sec-compile-code), if you don't specify\nan explicit mode through the `-O` command-line [^oargument]\nargument, then, the compiler will compile your code in `Debug` mode.\n\n[^oargument]: See <https://ziglang.org/documentation/master/#Debug>.\n\n\n### Let's debug a program\n\nAs an example, let's use LLDB to navigate and investigate the following\npiece of Zig code:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\nfn add_and_increment(a: u8, b: u8) u8 {\n    const sum = a + b;\n    const incremented = sum + 1;\n    return incremented;\n}\n\npub fn main() !void {\n    var n = add_and_increment(2, 3);\n    n = add_and_increment(n, n);\n    _ = try stdout.print(\"Result: {d}!\\n\", .{n});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 13!\n```\n\n\n:::\n:::\n\n\n\n\nThere is nothing wrong with this program. But it is\na good start for us. First, we need to compile\nthis program with the `zig build-exe` command.\nFor this example, suppose that I have compiled the above\nZig code into a binary executable called `add_program`.\n\n```bash\nzig build-exe add_program.zig\n```\n\nNow, we can start LLDB with `add_program`, like this:\n\n```bash\nlldb add_program\n```\n\nFrom now on, LLDB is started, and you can know that I'm\nexecuting LLDB commands by looking at the prefix `(lldb)`.\nIf something is prefixed with `(lldb)`, then you know\nthat it is a LLDB command.\n\nThe first thing I will do, is to set a breakpoint at\nthe `main()` function, by executing `b main`.\nAfter that, I just start the execution of the program\nwith `run`.\nYou can see in the output below, that the execution\nstopped at the first line in the function `main()`, as we expected.\n\n```bash\n(lldb) b main\nBreakpoint 1: where = debugging`debug1.main + 22\n    at debug1.zig:11:30, address = 0x00000000010341a6\n(lldb) run\nProcess 8654 launched: 'add_program' (x86_64)\nProcess 8654 stopped\n* thread #1, name = 'add_program',\n    stop reason = breakpoint 1.1 frame #0: 0x10341a6\n    add_program`debug1.main at add_program.zig:11:30\n   8   \t}\n   9   \t\n   10  \tpub fn main() !void {\n-> 11  \t    var n = add_and_increment(2, 3);\n   12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n```\n\nI can start navigating through the code, and checking the objects\nthat are being generated. If you are not familiar with the commands\navailable in LLDB, I recommend you to read the official documentation\nof the project[^lldb].\nYou can also look for cheat sheets, which quickly describes all commands\navailable for you[^lldb-quick-list].\n\n[^lldb]: <https://lldb.llvm.org/>\n[^lldb-quick-list]: <https://gist.github.com/ryanchang/a2f738f0c3cc6fbd71fa>.\n\nCurrently, we are in the first line at the `main()` function. In this line, we create\nthe `n` object, by executing the `add_and_increment()` function.\nTo execute the current line of code, and go to the next line, we can\nrun the `n` LLDB command. Let's execute this command.\n\nAfter we executed this line, we can also look at the value stored inside this `n` object\nby using the `p` LLDB command. The syntax for this command is `p <name-of-object>`.\n\nIf we take a look at the value stored in the `n` object (`p n`),\nnotice that it stores the hexadecimal value `0x06`, which\nis the number 6 in decimal. We can also see that, this value have a type `unsigned char`,\nwhich is an unsigned 8-bit integer.\nWe have talked already about this at @sec-zig-strings, that `u8` integers in Zig are equivalent\nto the C data type `unsigned char`.\n\n\n\n```bash\n(lldb) n\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step over frame #0: 0x10341ae\n    debugging`debug1.main at debug1.zig:12:26\n   9   \t\n   10  \tpub fn main() !void {\n   11  \t    var n = add_and_increment(2, 3);\n-> 12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n(lldb) p n\n(unsigned char) $1 = '\\x06'\n```\n\nNow, on the next line of code, we are executing the `add_and_increment()` function once again.\nWhy not step inside this function? Shall we? We can do that, by executing the `s` LLDB command.\nNotice in the example below that, after executing this command, we have entered into the context of the\n`add_and_increment()` function.\n\nAlso notice in the example below that, I have walked two more lines in the function's body, then,\nI execute the `frame variable` LLDB command, to see at once, the value stored in each of the variables\nthat were created inside the current scope.\n\nYou can see in the output below that, the object `sum` stores the value `\\f`,\nwhich represents the *form feed* character. This character in the ASCII table,\ncorresponds to the hexadecimal value `0x0C`, or, in decimal, the number 12.\nSo, this means that the result of the expression `a + b` executed at line\n5, resulted in the number 12.\n\n```bash\n(lldb) s\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step in frame #0: 0x10342de\n    debugging`debug1.add_and_increment(a='\\x02', b='\\x03')\n    at debug1.zig:4:39\n-> 4   \tfn add_and_increment(a: u8, b: u8) u8 {\n   5   \t    const sum = a + b;\n   6   \t    const incremented = sum + 1;\n   7   \t    return incremented;\n(lldb) n\n(lldb) n\n(lldb) frame variable\n(unsigned char) a = '\\x06'\n(unsigned char) b = '\\x06'\n(unsigned char) sum = '\\f'\n(unsigned char) incremented = '\\x06'\n```\n\n\n\n## How to investigate the data type of your objects\n\nSince Zig is a strongly-typed language, the data types associated with your objects\nare very important for your program. So, debugging the data types associated\nwith your objects might be important to understand bugs and errors in your program.\n\nWhen you walk through your program with a debugger, you can inspect the types of\nyour objects by simply printing them to the console, with the LLDB `p` command.\nBut you also have alternatives embedded in the language itself to access the data\ntypes of your objects.\n\nIn Zig, you can retrieve the data type of an object, by using the built-in function\n`@TypeOf()`. Just apply this function over the object, and you get access to \nthe data type of the object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst expect = std.testing.expect;\n\npub fn main() !void {\n    const number: i32 = 5;\n    try expect(@TypeOf(number) == i32);\n    try stdout.print(\"{any}\\n\", .{@TypeOf(number)});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ni32\n```\n\n\n:::\n:::\n\n\n\n\nThis function is similar to the `type()` built-in function from Python,\nor, the `typeof` operator in Javascript.\n\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Debugging Zig applications\n\nBeing able to debug your applications is essential for any programmer who wants to\ndo serious programming in any language. That is why, in this chapter, we are going to talk about the\navailable strategies and tools to debug applications written in Zig.\n\n\n## Print debugging\n\nWe begin with the classic and battle-tested *print debugging* strategy.\nThe key advantage that debugging offers you is *visibility*.\nWith *print statements* you can easily see what results and objects\nare being produced by your application.\n\nThat is the essence of *print debugging*. Is to use\nprint expressions to see the values that are being generated by your program,\nand, as a result, get a much better understanding of how your program\nis behaving.\n\nMany programmers often resort to the print functions in Zig, such as the `stdout.print()`,\nor, the `std.debug.print()`, to get a better understanding of their programs.\nThis is a known and old strategy that is very simple and effective, and it is better known within\nthe programming community as *print debugging*.\nIn Zig, you can print information to the `stdout` or `stderr` streams of your system.\n\nLet's begin with `stdout`. First, you\nneed to get access to the `stdout`, by calling the `getStdOut()` method, from\nthe Zig Standard Library. This method returns a *file descriptor* object,\nand, through this object you can read/write to the `stdout`.\nI recommend you to check out all methods available in this object, by [checking the page in\nthe Zig Standard Library Official Reference for the type `File`](https://ziglang.org/documentation/master/std/#std.fs.File)[^zig-fiile-reference].\n\n[^zig-fiile-reference]: <https://ziglang.org/documentation/master/std/#std.fs.File>.\n\nFor our purpose here, which is to write something to the `stdout`, especially to debug our\nprogram, I recommend you to use the `writer()` method, which gives your a *writer* object.\nThis *writer* object offers some helper methods to write stuff into the file descriptor object\nthat represents the `stdout` stream. In special, the `print()` method.\n\n\nThe `print()` method from this *writer* object is a \"print formatter\" type of a function.\nIn other words, this method works exactly like the `printf()` function from C,\nor, like `println!()` from Rust.\nIn the first argument of the function, you specify a template string, and,\nin the second argument, you provide a list of values (or objects) that you want to insert\ninto your template message.\n\nIdeally, the template string in the first argument should contain some format specifier.\nEach format specifier is matched to a value (or object) that you have listed in the second argument.\nSo, if you provided 5 different objects in the second argument, then, the template string\nshould contain 5 format specifiers, one for each object provided.\n\nEach format specifier is represented by a single letter, and\nyou provide this format specifier inside a pair of curly braces. So, if you want to format\nyour object using the string specifier (`s`), then, you can insert the text `{s}` in your template string.\nHere is a quick list of the most used format specifiers:\n\n- `d`: for printing integers and floating-point numbers.\n- `c`: for printing characters.\n- `s`: for printing strings.\n- `p`: for printing memory addresses.\n- `x`: for printing hexadecimal values.\n- `any`: use any compatible format specifier (i.e. it automatically selects a format specifier for you).\n\nThe code example below gives you an example of use of this `print()` method\nwith the `d` format specifier.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    try stdout.print(\"Result: {d}\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\n\n\nIs important to emphasize that, the `stdout.print()` method, as you would expect,\nprint your template string into the `stdout` stream of your system.\nHowever, you can also print your template string into the `stderr` stream\nif your prefer. All you need to do, is to replace the `stdout.print()`\ncall with the function `std.debug.print()`. Like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    std.debug.print(\"Result: {d}\\n\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\n\n\n\nYou could also achieve the exact same result by getting a file descriptor object to `stderr`,\nthen, creating a *writer* object to `stderr`, then, using the `print()` method of this\n*writer* object, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stderr = std.io.getStdErr().writer();\n// some more lines ...\ntry stderr.print(\"Result: {d}\", .{result});\n```\n:::\n\n\n\n\n\n\n## Debugging through debuggers\n\nAlthough *print debugging* being a valid and very useful strategy,\nmost programmers prefer to use a debugger to debug their programs.\nSince Zig is a low-level language, you can use either GDB (GNU Debugger),\nor LLDB (LLVM Project Debugger) as your debugger.\n\nBoth debuggers can work with Zig code, and it's a matter of taste here.\nYou choose the debugger of your preference, and you work with it.\nIn this book, I will use LLDB as my debugger on the examples.\n\n\n### Compile your source code in debug mode {#sec-compile-debug-mode}\n\nIn order to debug your program through a debugger, you must compile\nyour source code in `Debug` mode. Because when you compile your\nsource code in other modes (such as `Release`), the compiler usually\nstrips out some essential information that is used by the debugger\nto read and track your program, like PDB (*Program Database*) files.\n\nBy compiling your source code in `Debug` mode, you ensure that the debugger\nwill find the necessary information in your program to debug it.\nBy default, the compiler uses the `Debug` mode when compiling your code.\nHaving this in mind, when you compile your program with the `build-exe`\ncommand (which was described at @sec-compile-code), if you don't specify\nan explicit mode through the `-O` command-line [^oargument]\nargument, then, the compiler will compile your code in `Debug` mode.\n\n[^oargument]: See <https://ziglang.org/documentation/master/#Debug>.\n\n\n### Let's debug a program\n\nAs an example, let's use LLDB to navigate and investigate the following\npiece of Zig code:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\nfn add_and_increment(a: u8, b: u8) u8 {\n    const sum = a + b;\n    const incremented = sum + 1;\n    return incremented;\n}\n\npub fn main() !void {\n    var n = add_and_increment(2, 3);\n    n = add_and_increment(n, n);\n    try stdout.print(\"Result: {d}!\\n\", .{n});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 13!\n```\n\n\n:::\n:::\n\n\n\n\nThere is nothing wrong with this program. But it is\na good start for us. First, we need to compile\nthis program with the `zig build-exe` command.\nFor this example, suppose that I have compiled the above\nZig code into a binary executable called `add_program`.\n\n```bash\nzig build-exe add_program.zig\n```\n\nNow, we can start LLDB with `add_program`, like this:\n\n```bash\nlldb add_program\n```\n\nFrom now on, LLDB is started, and you can know that I'm\nexecuting LLDB commands by looking at the prefix `(lldb)`.\nIf something is prefixed with `(lldb)`, then you know\nthat it is a LLDB command.\n\nThe first thing I will do, is to set a breakpoint at\nthe `main()` function, by executing `b main`.\nAfter that, I just start the execution of the program\nwith `run`.\nYou can see in the output below, that the execution\nstopped at the first line in the function `main()`, as we expected.\n\n```bash\n(lldb) b main\nBreakpoint 1: where = debugging`debug1.main + 22\n    at debug1.zig:11:30, address = 0x00000000010341a6\n(lldb) run\nProcess 8654 launched: 'add_program' (x86_64)\nProcess 8654 stopped\n* thread #1, name = 'add_program',\n    stop reason = breakpoint 1.1 frame #0: 0x10341a6\n    add_program`debug1.main at add_program.zig:11:30\n   8   \t}\n   9\n   10  \tpub fn main() !void {\n-> 11  \t    var n = add_and_increment(2, 3);\n   12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n```\n\nI can start navigating through the code, and checking the objects\nthat are being generated. If you are not familiar with the commands\navailable in LLDB, I recommend you to read the official documentation\nof the project[^lldb].\nYou can also look for cheat sheets, which quickly describes all commands\navailable for you[^lldb-quick-list].\n\n[^lldb]: <https://lldb.llvm.org/>\n[^lldb-quick-list]: <https://gist.github.com/ryanchang/a2f738f0c3cc6fbd71fa>.\n\nCurrently, we are in the first line at the `main()` function. In this line, we create\nthe `n` object, by executing the `add_and_increment()` function.\nTo execute the current line of code, and go to the next line, we can\nrun the `n` LLDB command. Let's execute this command.\n\nAfter we executed this line, we can also look at the value stored inside this `n` object\nby using the `p` LLDB command. The syntax for this command is `p <name-of-object>`.\n\nIf we take a look at the value stored in the `n` object (`p n`),\nnotice that it stores the hexadecimal value `0x06`, which\nis the number 6 in decimal. We can also see that, this value have a type `unsigned char`,\nwhich is an unsigned 8-bit integer.\nWe have talked already about this at @sec-zig-strings, that `u8` integers in Zig are equivalent\nto the C data type `unsigned char`.\n\n\n\n```bash\n(lldb) n\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step over frame #0: 0x10341ae\n    debugging`debug1.main at debug1.zig:12:26\n   9\n   10  \tpub fn main() !void {\n   11  \t    var n = add_and_increment(2, 3);\n-> 12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n(lldb) p n\n(unsigned char) $1 = '\\x06'\n```\n\nNow, on the next line of code, we are executing the `add_and_increment()` function once again.\nWhy not step inside this function? Shall we? We can do that, by executing the `s` LLDB command.\nNotice in the example below that, after executing this command, we have entered into the context of the\n`add_and_increment()` function.\n\nAlso notice in the example below that, I have walked two more lines in the function's body, then,\nI execute the `frame variable` LLDB command, to see at once, the value stored in each of the variables\nthat were created inside the current scope.\n\nYou can see in the output below that, the object `sum` stores the value `\\f`,\nwhich represents the *form feed* character. This character in the ASCII table,\ncorresponds to the hexadecimal value `0x0C`, or, in decimal, the number 12.\nSo, this means that the result of the expression `a + b` executed at line\n5, resulted in the number 12.\n\n```bash\n(lldb) s\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step in frame #0: 0x10342de\n    debugging`debug1.add_and_increment(a='\\x02', b='\\x03')\n    at debug1.zig:4:39\n-> 4   \tfn add_and_increment(a: u8, b: u8) u8 {\n   5   \t    const sum = a + b;\n   6   \t    const incremented = sum + 1;\n   7   \t    return incremented;\n(lldb) n\n(lldb) n\n(lldb) frame variable\n(unsigned char) a = '\\x06'\n(unsigned char) b = '\\x06'\n(unsigned char) sum = '\\f'\n(unsigned char) incremented = '\\x06'\n```\n\n\n\n## How to investigate the data type of your objects\n\nSince Zig is a strongly-typed language, the data types associated with your objects\nare very important for your program. So, debugging the data types associated\nwith your objects might be important to understand bugs and errors in your program.\n\nWhen you walk through your program with a debugger, you can inspect the types of\nyour objects by simply printing them to the console, with the LLDB `p` command.\nBut you also have alternatives embedded in the language itself to access the data\ntypes of your objects.\n\nIn Zig, you can retrieve the data type of an object, by using the built-in function\n`@TypeOf()`. Just apply this function over the object, and you get access to\nthe data type of the object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst expect = std.testing.expect;\n\npub fn main() !void {\n    const number: i32 = 5;\n    try expect(@TypeOf(number) == i32);\n    try stdout.print(\"{any}\\n\", .{@TypeOf(number)});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ni32\n```\n\n\n:::\n:::\n\n\n\n\nThis function is similar to the `type()` built-in function from Python,\nor, the `typeof` operator in Javascript.\n\n",
     "supporting": [
       "02-debugging_files"
     ],
diff --git a/docs/Chapters/01-base64.html b/docs/Chapters/01-base64.html
index 7cff1ea1..36bf226d 100644
--- a/docs/Chapters/01-base64.html
+++ b/docs/Chapters/01-base64.html
@@ -415,7 +415,7 @@ <h3 data-number="4.1.2" class="anchored" data-anchor-id="sec-base64-table"><span
 <span id="cb1-10"><a href="#cb1-10" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span>;</span>
 <span id="cb1-11"><a href="#cb1-11" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
 <span id="cb1-12"><a href="#cb1-12" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb1-13"><a href="#cb1-13" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> _char_at(self: Base64, index: <span class="dt">u8</span>) <span class="dt">u8</span> <span class="op">{</span></span>
+<span id="cb1-13"><a href="#cb1-13" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> _char_at(self: Base64, index: <span class="dt">usize</span>) <span class="dt">u8</span> <span class="op">{</span></span>
 <span id="cb1-14"><a href="#cb1-14" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> self._table[index];</span>
 <span id="cb1-15"><a href="#cb1-15" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
 <span id="cb1-16"><a href="#cb1-16" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
@@ -772,14 +772,13 @@ <h3 data-number="4.5.1" class="anchored" data-anchor-id="sec-map-base64-index"><
 <span id="cb11-3"><a href="#cb11-3" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> <span class="dv">64</span>;</span>
 <span id="cb11-4"><a href="#cb11-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> index: <span class="dt">u8</span> = <span class="dv">0</span>;</span>
 <span id="cb11-5"><a href="#cb11-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">for</span> (<span class="dv">0</span>..<span class="dv">63</span>) |i| <span class="op">{</span></span>
-<span id="cb11-6"><a href="#cb11-6" aria-hidden="true" tabindex="-1"></a>        <span class="kw">if</span> (self._char_at(i) == char) <span class="op">{</span></span>
-<span id="cb11-7"><a href="#cb11-7" aria-hidden="true" tabindex="-1"></a>            index = i;</span>
-<span id="cb11-8"><a href="#cb11-8" aria-hidden="true" tabindex="-1"></a>            <span class="kw">break</span>;</span>
-<span id="cb11-9"><a href="#cb11-9" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span></span>
-<span id="cb11-10"><a href="#cb11-10" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb11-11"><a href="#cb11-11" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb11-12"><a href="#cb11-12" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> index;</span>
-<span id="cb11-13"><a href="#cb11-13" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<span id="cb11-6"><a href="#cb11-6" aria-hidden="true" tabindex="-1"></a>        <span class="kw">if</span> (self._char_at(i) == char)</span>
+<span id="cb11-7"><a href="#cb11-7" aria-hidden="true" tabindex="-1"></a>            <span class="kw">break</span>;</span>
+<span id="cb11-8"><a href="#cb11-8" aria-hidden="true" tabindex="-1"></a>        index += <span class="dv">1</span>;</span>
+<span id="cb11-9"><a href="#cb11-9" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb11-10"><a href="#cb11-10" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb11-11"><a href="#cb11-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> index;</span>
+<span id="cb11-12"><a href="#cb11-12" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
 <section id="the-6-bit-transformation" class="level3" data-number="4.5.2">
diff --git a/docs/Chapters/01-memory.html b/docs/Chapters/01-memory.html
index 0e748f6f..5e2f100b 100644
--- a/docs/Chapters/01-memory.html
+++ b/docs/Chapters/01-memory.html
@@ -440,7 +440,7 @@ <h3 data-number="3.1.4" class="anchored" data-anchor-id="sec-stack"><span class=
 <span id="cb3-7"><a href="#cb3-7" aria-hidden="true" tabindex="-1"></a><span class="co">// Trying to use an object that was</span></span>
 <span id="cb3-8"><a href="#cb3-8" aria-hidden="true" tabindex="-1"></a><span class="co">// declared in the for loop scope,</span></span>
 <span id="cb3-9"><a href="#cb3-9" aria-hidden="true" tabindex="-1"></a><span class="co">// and that does not exist anymore.</span></span>
-<span id="cb3-10"><a href="#cb3-10" aria-hidden="true" tabindex="-1"></a>std.debug.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, index);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<span id="cb3-10"><a href="#cb3-10" aria-hidden="true" tabindex="-1"></a>std.debug.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>index<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>One important consequence of this mechanism is that, once the function returns, you can no longer access any memory address that was inside the space in the stack reserved for this particular function. Because this space was destroyed. This means that, if this local object is stored in the stack, you cannot make a function that <strong>returns a pointer to this object</strong>.</p>
 <p>Think about that for a second. If all local objects in the stack are destroyed at the end of the function scope, why would you even consider returning a pointer to one of these objects? This pointer is at best, invalid, or, more likely, “undefined”.</p>
diff --git a/docs/Chapters/02-debugging.html b/docs/Chapters/02-debugging.html
index d6ff110e..f2430f71 100644
--- a/docs/Chapters/02-debugging.html
+++ b/docs/Chapters/02-debugging.html
@@ -339,7 +339,7 @@ <h2 data-number="5.1" class="anchored" data-anchor-id="print-debugging"><span cl
 <span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a></span>
 <span id="cb1-7"><a href="#cb1-7" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
 <span id="cb1-8"><a href="#cb1-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> result = add(<span class="dv">34</span>, <span class="dv">16</span>);</span>
-<span id="cb1-9"><a href="#cb1-9" aria-hidden="true" tabindex="-1"></a>    _ = <span class="kw">try</span> stdout.print(<span class="st">"Result: {d}"</span>, .<span class="op">{</span>result<span class="op">}</span>);</span>
+<span id="cb1-9"><a href="#cb1-9" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"Result: {d}"</span>, .<span class="op">{</span>result<span class="op">}</span>);</span>
 <span id="cb1-10"><a href="#cb1-10" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>Result: 50</code></pre>
@@ -365,7 +365,7 @@ <h2 data-number="5.1" class="anchored" data-anchor-id="print-debugging"><span cl
 <div class="sourceCode cell-code" id="cb5"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stderr = std.io.getStdErr().writer();</span>
 <span id="cb5-3"><a href="#cb5-3" aria-hidden="true" tabindex="-1"></a><span class="co">// some more lines ...</span></span>
-<span id="cb5-4"><a href="#cb5-4" aria-hidden="true" tabindex="-1"></a>_ = <span class="kw">try</span> stderr.print(<span class="st">"Result: {d}"</span>, .<span class="op">{</span>result<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<span id="cb5-4"><a href="#cb5-4" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stderr.print(<span class="st">"Result: {d}"</span>, .<span class="op">{</span>result<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
 <section id="debugging-through-debuggers" class="level2" data-number="5.2">
@@ -393,7 +393,7 @@ <h3 data-number="5.2.2" class="anchored" data-anchor-id="lets-debug-a-program"><
 <span id="cb6-10"><a href="#cb6-10" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
 <span id="cb6-11"><a href="#cb6-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> n = add_and_increment(<span class="dv">2</span>, <span class="dv">3</span>);</span>
 <span id="cb6-12"><a href="#cb6-12" aria-hidden="true" tabindex="-1"></a>    n = add_and_increment(n, n);</span>
-<span id="cb6-13"><a href="#cb6-13" aria-hidden="true" tabindex="-1"></a>    _ = <span class="kw">try</span> stdout.print(<span class="st">"Result: {d}!</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>n<span class="op">}</span>);</span>
+<span id="cb6-13"><a href="#cb6-13" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"Result: {d}!</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>n<span class="op">}</span>);</span>
 <span id="cb6-14"><a href="#cb6-14" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>Result: 13!</code></pre>
@@ -415,7 +415,7 @@ <h3 data-number="5.2.2" class="anchored" data-anchor-id="lets-debug-a-program"><
 <span id="cb10-8"><a href="#cb10-8" aria-hidden="true" tabindex="-1"></a>    <span class="ex">stop</span> reason = breakpoint 1.1 frame <span class="co">#0: 0x10341a6</span></span>
 <span id="cb10-9"><a href="#cb10-9" aria-hidden="true" tabindex="-1"></a>    <span class="ex">add_program</span><span class="kw">`</span>debug1.main at add_program.zig:11:30</span>
 <span id="cb10-10"><a href="#cb10-10" aria-hidden="true" tabindex="-1"></a>   <span class="ex">8</span>    }</span>
-<span id="cb10-11"><a href="#cb10-11" aria-hidden="true" tabindex="-1"></a>   <span class="ex">9</span>    </span>
+<span id="cb10-11"><a href="#cb10-11" aria-hidden="true" tabindex="-1"></a>   <span class="ex">9</span></span>
 <span id="cb10-12"><a href="#cb10-12" aria-hidden="true" tabindex="-1"></a>   <span class="ex">10</span>   pub fn main<span class="er">(</span><span class="kw">)</span> <span class="ex">!void</span> {</span>
 <span id="cb10-13"><a href="#cb10-13" aria-hidden="true" tabindex="-1"></a><span class="ex">-</span><span class="op">&gt;</span> 11       var n = add_and_increment<span class="er">(</span><span class="ex">2,</span> 3<span class="kw">);</span></span>
 <span id="cb10-14"><a href="#cb10-14" aria-hidden="true" tabindex="-1"></a>   <span class="ex">12</span>       n = add_and_increment<span class="er">(</span><span class="ex">n,</span> n<span class="kw">);</span></span>
@@ -430,7 +430,7 @@ <h3 data-number="5.2.2" class="anchored" data-anchor-id="lets-debug-a-program"><
 <span id="cb11-3"><a href="#cb11-3" aria-hidden="true" tabindex="-1"></a><span class="ex">*</span> thread <span class="co">#1, name = 'debugging',</span></span>
 <span id="cb11-4"><a href="#cb11-4" aria-hidden="true" tabindex="-1"></a>    <span class="ex">stop</span> reason = step over frame <span class="co">#0: 0x10341ae</span></span>
 <span id="cb11-5"><a href="#cb11-5" aria-hidden="true" tabindex="-1"></a>    <span class="ex">debugging</span><span class="kw">`</span><span class="ex">debug1.main</span> at debug1.zig:12:26</span>
-<span id="cb11-6"><a href="#cb11-6" aria-hidden="true" tabindex="-1"></a>   <span class="ex">9</span>    </span>
+<span id="cb11-6"><a href="#cb11-6" aria-hidden="true" tabindex="-1"></a>   <span class="ex">9</span></span>
 <span id="cb11-7"><a href="#cb11-7" aria-hidden="true" tabindex="-1"></a>   <span class="ex">10</span>   pub fn main<span class="er">(</span><span class="kw">)</span> <span class="ex">!void</span> {</span>
 <span id="cb11-8"><a href="#cb11-8" aria-hidden="true" tabindex="-1"></a>   <span class="ex">11</span>       var n = add_and_increment<span class="er">(</span><span class="ex">2,</span> 3<span class="kw">);</span></span>
 <span id="cb11-9"><a href="#cb11-9" aria-hidden="true" tabindex="-1"></a><span class="ex">-</span><span class="op">&gt;</span> 12       n = add_and_increment<span class="er">(</span><span class="ex">n,</span> n<span class="kw">);</span></span>
diff --git a/docs/index.html b/docs/index.html
index bb4d7134..e3ebec2b 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -7,7 +7,7 @@
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 <meta name="author" content="Pedro Duarte Faria">
-<meta name="dcterms.date" content="2025-01-30">
+<meta name="dcterms.date" content="2025-02-09">
 
 <title>Introduction to Zig</title>
 <style>
@@ -287,7 +287,7 @@ <h1 class="title">Introduction to Zig</h1>
     <div>
     <div class="quarto-title-meta-heading">Published</div>
     <div class="quarto-title-meta-contents">
-      <p class="date">January 30, 2025</p>
+      <p class="date">February 9, 2025</p>
     </div>
   </div>
   
diff --git a/docs/search.json b/docs/search.json
index 9d8728f7..89f77604 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -314,7 +314,7 @@
     "href": "Chapters/01-memory.html#memory-spaces",
     "title": "3  Memory and Allocators",
     "section": "",
-    "text": "Global data register (or the “global data section”);\nStack;\nHeap;\n\n\n3.1.1 Compile-time known versus runtime known\nOne strategy that Zig uses to decide where it will store each object that you declare, is by looking at the value of this particular object. More specifically, by investigating if this value is known at “compile-time” or at “runtime”.\nWhen you write a program in Zig, the values of some of the objects that you write in your program are known at compile time. Meaning that, when you compile your Zig source code, during the compilation process, the zig compiler can figure out the exact value of a particular object that exists in your source code. Knowing the length (or the size) of each object is also important. So the length (or the size) of each object that you write in your program is, in some cases, known at compile time.\nThe zig compiler cares more about knowing the length (or the size) of a particular object , than to know its actual value. But, if the zig compiler knows the value of the object, then, it automatically knows the size of this object. Because it can simply calculate the size of the object by looking at the size of the value.\nTherefore, the priority for the zig compiler is to discover the size of each object in your source code. If the value of the object in question is known at compile-time, then, the zig compiler automatically knows the size/length of this object. But if the value of this object is not known at compile-time, then, the size of this object is only known at compile-time if, and only if, the type of this object has a known fixed size.\nIn order for a type to have a known fixed size, this type must have data members whose size is fixed. If this type includes, for example, a variable sized array in it, then, this type does not have a known fixed size. Because this array can have any size at runtime (i.e. it can be an array of 2 elements, or 50 elements, or 1 thousand elements, etc.).\nFor example, a string object, which internally is an array of constant u8 values ([]const u8) has a variable size. It can be a string object with 100 or 500 characters in it. If we do not know at compile-time, which exact string will be stored inside this string object, then, we cannot calculate the size of this string object at compile-time. So, any type, or any struct declaration that you make, that includes a string data member that does not have an explicit fixed size, makes this type, or this new struct that you are declaring, a type that does not have a known fixed size at compile-time.\nIn contrast, if the type of this struct that you are declaring, includes a data member that is an array, but this array has a known fixed size, like [60]u8 (which declares an array of 60 u8 values), then, this type, or, this struct that you are declaring, becomes a type with a known fixed size at compile-time. And because of that, in this case, the zig compiler does not need to know at compile-time the exact value of any object of this type. Since the compiler can find the necessary size to store this object by looking at the size of its type.\nLet’s look at an example. In the source code below, we have two constant objects (name and array) declared. Because the values of these particular objects are written down, in the source code itself (\"Pedro\" and the number sequence from 1 to 4), the zig compiler can easily discover the values of these constant objects (name and array) during the compilation process. This is what “known at compile time” means. It refers to any object that you have in your Zig source code whose value can be identified at compile time.\n\nfn input_length(input: []const u8) usize {\n    const n = input.len;\n    return n;\n}\n\npub fn main() !void {\n    const name = \"Pedro\";\n    const array = [_]u8{1, 2, 3, 4};\n    _ = name; _ = array;\n}\n\nThe other side of the spectrum are objects whose values are not known at compile time. Function arguments are a classic example of this. Because the value of each function argument depends on the value that you assign to this particular argument, when you call the function.\nFor example, the function input_length() contains an argument named input, which is an array of constant u8 integers ([]const u8). It is impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length of this particular argument. Because it is an array that do not have a fixed size specified explicitly in the argument type annotation.\nSo, we know that this input argument will be an array of u8 integers. But we do not know at compile-time, its value, and neither his size. This information is known only at runtime, which is the period of time when you program is executed. As a consequence, the value of the expression input.len is also known only at runtime. This is an intrinsic characteristic of any function. Just remember that the value of function arguments is usually not “compile-time known”.\nHowever, as I mentioned earlier, what really matters to the compiler is to know the size of the object at compile-time, and not necessarily its value. So, although we don’t know the value of the object n, which is the result of the expression input.len, at compile-time, we do know its size. Because the expression input.len always returns a value of type usize, and the type usize has a known fixed size.\n\n\n3.1.2 Global data register\nThe global data register is a specific section of the executable of your Zig program, that is responsible for storing any value that is known at compile time.\nEvery constant object whose value is known at compile time that you declare in your source code, is stored in the global data register. Also, every literal value that you write in your source code, such as the string \"this is a string\", or the integer 10, or a boolean value such as true, is also stored in the global data register.\nHonestly, you don’t need to care much about this memory space. Because you can’t control it, you can’t deliberately access it or use it for your own purposes. Also, this memory space does not affect the logic of your program. It simply exists in your program.\n\n\n3.1.3 Stack vs Heap\nIf you are familiar with system’s programming, or just low-level programming in general, you probably have heard of the “duel” between Stack vs Heap. These are two different types of memory, or different memory spaces, which are both available in Zig.\nThese two types of memory don’t actually duel with each other. This is a common mistake that beginners have, when seeing “x vs y” styles of tabloid headlines. These two types of memory are actually complementary to each other. So, in almost every Zig program that you ever write, you will likely use a combination of both. I will describe each memory space in detail over the next sections. But for now, I just want to stablish the main difference between these two types of memory.\nIn essence, the stack memory is normally used to store values whose length is fixed and known at compile time. In contrast, the heap memory is a dynamic type of memory space, meaning that, it is used to store values whose length might grow during the execution (runtime) of your program (Chen and Guo 2022).\nLengths that grow during runtime are intrinsically associated with “runtime known” type of values. In other words, if you have an object whose length might grow during runtime, then, the length of this object becomes not known at compile time. If the length is not known at compile-time, the value of this object also becomes not known at compile-time. These types of objects should be stored in the heap memory space, which is a dynamic memory space, which can grow or shrink to fit the size of your objects.\n\n\n3.1.4 Stack\nThe stack is a type of memory that uses the power of the stack data structure, hence the name. A “stack” is a type of data structure that uses a “last in, first out” (LIFO) mechanism to store the values you give it to. I imagine you are familiar with this data structure. But, if you are not, the Wikipedia page1 , or, the Geeks For Geeks page2 are both excellent and easy resources to fully understand how this data structure works.\nSo, the stack memory space is a type of memory that stores values using a stack data structure. It adds and removes values from the memory by following a “last in, first out” (LIFO) principle.\nEvery time you make a function call in Zig, an amount of space in the stack is reserved for this particular function call (Chen and Guo 2022; Zig Software Foundation 2024). The value of each function argument given to the function in this function call is stored in this stack space. Also, every local object that you declare inside the function scope is usually stored in this same stack space.\nLooking at the example below, the object result is a local object declared inside the scope of the add() function. Because of that, this object is stored inside the stack space reserved for the add() function. The r object (which is declared outside of the add() function scope) is also stored in the stack. But since it is declared in the “outer” scope, this object is stored in the stack space that belongs to this outer scope.\n\nfn add(x: u8, y: u8) u8 {\n    const result = x + y;\n    return result;\n}\n\npub fn main() !void {\n    const r = add(5, 27);\n    _ = r;\n}\n\nSo, any object that you declare inside the scope of a function is always stored inside the space that was reserved for that particular function in the stack memory. This also counts for any object declared inside the scope of your main() function for example. As you would expect, in this case, they are stored inside the stack space reserved for the main() function.\nOne very important detail about the stack memory is that it frees itself automatically. This is very important, remember that. When objects are stored in the stack memory, you don’t have the work (or the responsibility) of freeing/destroying these objects. Because they will be automatically destroyed once the stack space is freed at the end of the function scope.\nSo, once the function call returns (or ends, if you prefer to call it this way) the space that was reserved in the stack is destroyed, and all of the objects that were in that space goes away with it. This mechanism exists because this space, and the objects within it, are not necessary anymore, since the function “finished its business”. Using the add() function that we exposed above as an example, it means that the object result is automatically destroyed once the function returns.\n\n\n\n\n\n\nImportant\n\n\n\nLocal objects that are stored in the stack space of a function are automatically freed/destroyed at the end of the function scope.\n\n\nThis same logic applies to any other special structure in Zig that have its own scope by surrounding it with curly braces ({}). For loops, while loops, if else statements, etc. For example, if you declare any local object in the scope of a for loop, this local object is accessible only within the scope of this particular for loop. Because once the scope of this for loop ends, the space in the stack reserved for this for loop is freed. The example below demonstrates this idea.\n\n// This does not compile successfully!\nconst a = [_]u8{0, 1, 2, 3, 4};\nfor (0..a.len) |i| {\n    const index = i;\n    _ = index;\n}\n// Trying to use an object that was\n// declared in the for loop scope,\n// and that does not exist anymore.\nstd.debug.print(\"{d}\\n\", index);\n\nOne important consequence of this mechanism is that, once the function returns, you can no longer access any memory address that was inside the space in the stack reserved for this particular function. Because this space was destroyed. This means that, if this local object is stored in the stack, you cannot make a function that returns a pointer to this object.\nThink about that for a second. If all local objects in the stack are destroyed at the end of the function scope, why would you even consider returning a pointer to one of these objects? This pointer is at best, invalid, or, more likely, “undefined”.\nConclusion, it is totally fine to write a function that returns the local object itself as result, because then, you return the value of that object as the result. But, if this local object is stored in the stack, you should never write a function that returns a pointer to this local object. Because the memory address pointed by the pointer no longer exists.\nSo, using again the add() function as an example, if you rewrite this function so that it returns a pointer to the local object result, the zig compiler will actually compile your program, with no warnings or errors. At first glance, it looks that this is good code that works as expected. But this is a lie!\nIf you try to take a look at the value inside of the r object, or, if you try to use this r object in another expression or function call, then, you would have undefined behaviour, and major bugs in your program (Zig Software Foundation 2024, see “Lifetime and Ownership”3 and “Undefined Behaviour”4 sections).\n\nfn add(x: u8, y: u8) *const u8 {\n    const result = x + y;\n    return &result;\n}\n\npub fn main() !void {\n    // This code compiles successfully. But it has\n    // undefined behaviour. Never do this!!!\n    // The `r` object is undefined!\n    const r = add(5, 27); _ = r;\n}\n\nThis “invalid pointer to stack variable” problem is very known across many programming language communities. If you try to do the same thing, for example, in a C or C++ program (i.e. returning an address to a local object stored in the stack), you would also get undefined behaviour in the program.\n\n\n\n\n\n\nImportant\n\n\n\nIf a local object in your function is stored in the stack, you should never return a pointer to this local object from the function. Because this pointer will always become undefined after the function returns, since the stack space of the function is destroyed at the end of its scope.\n\n\nBut what if you really need to use this local object in some way after your function returns? How can you do this? The answer is: “in the same you would do if this was a C or C++ program. By returning an address to an object stored in the heap”. The heap memory has a much more flexible lifecycle, and allows you to get a valid pointer to a local object of a function that already returned from its scope.\n\n\n3.1.5 Heap\nOne important limitation of the stack, is that, only objects whose length/size is known at compile-time can be stored in it. In contrast, the heap is a much more dynamic (and flexible) type of memory. It is the perfect type of memory to use for objects whose size/length might grow during the execution of your program.\nVirtually any application that behaves as a server is a classic use case of the heap. A HTTP server, a SSH server, a DNS server, a LSP server, … any type of server. In summary, a server is a type of application that runs for long periods of time, and that serves (or “deals with”) any incoming request that reaches this particular server.\nThe heap is a good choice for this type of system, mainly because the server does not know upfront how many requests it will receive from users, while it is active. It could be one single request, or, 5 thousand requests, or, it could also be zero requests. The server needs to have the ability to allocate and manage its memory according to how many requests it receives.\nAnother key difference between the stack and the heap, is that the heap is a type of memory that you, the programmer, have complete control over. This makes the heap a more flexible type of memory, but it also makes it harder to work with. Because you, the programmer, is responsible for managing everything related to it. Including where the memory is allocated, how much memory is allocated, and where this memory is freed.\n\nUnlike stack memory, heap memory is allocated explicitly by programmers and it won’t be deallocated until it is explicitly freed (Chen and Guo 2022).\n\nTo store an object in the heap, you, the programmer, needs to explicitly tells Zig to do so, by using an allocator to allocate some space in the heap. At Section 3.3, I will present how you can use allocators to allocate memory in Zig.\n\n\n\n\n\n\nImportant\n\n\n\nEvery memory you allocate in the heap needs to be explicitly freed by you, the programmer.\n\n\nThe majority of allocators in Zig do allocate memory on the heap. But some exceptions to this rule are ArenaAllocator() and FixedBufferAllocator(). The ArenaAllocator() is a special type of allocator that works in conjunction with a second type of allocator. On the other side, the FixedBufferAllocator() is an allocator that works based on buffer objects created on the stack. This means that the FixedBufferAllocator() makes allocations only on the stack.\n\n\n3.1.6 Summary\nAfter discussing all of these boring details, we can quickly recap what we learned. In summary, the Zig compiler will use the following rules to decide where each object you declare is stored:\n\nevery literal value (such as \"this is string\", 10, or true) is stored in the global data section.\nevery constant object (const) whose value is known at compile-time is also stored in the global data section.\nevery object (constant or not) whose length/size is known at compile time is stored in the stack space for the current scope.\nif an object is created with the method alloc() or create() of an allocator object, this object is stored in the memory space used by this particular allocator object. Most of allocators available in Zig use the heap memory, so, this object is likely stored in the heap (FixedBufferAllocator() is an exception to that).\nthe heap can only be accessed through allocators. If your object was not created through the alloc() or create() methods of an allocator object, then, he is most certainly not an object stored in the heap.",
+    "text": "Global data register (or the “global data section”);\nStack;\nHeap;\n\n\n3.1.1 Compile-time known versus runtime known\nOne strategy that Zig uses to decide where it will store each object that you declare, is by looking at the value of this particular object. More specifically, by investigating if this value is known at “compile-time” or at “runtime”.\nWhen you write a program in Zig, the values of some of the objects that you write in your program are known at compile time. Meaning that, when you compile your Zig source code, during the compilation process, the zig compiler can figure out the exact value of a particular object that exists in your source code. Knowing the length (or the size) of each object is also important. So the length (or the size) of each object that you write in your program is, in some cases, known at compile time.\nThe zig compiler cares more about knowing the length (or the size) of a particular object , than to know its actual value. But, if the zig compiler knows the value of the object, then, it automatically knows the size of this object. Because it can simply calculate the size of the object by looking at the size of the value.\nTherefore, the priority for the zig compiler is to discover the size of each object in your source code. If the value of the object in question is known at compile-time, then, the zig compiler automatically knows the size/length of this object. But if the value of this object is not known at compile-time, then, the size of this object is only known at compile-time if, and only if, the type of this object has a known fixed size.\nIn order for a type to have a known fixed size, this type must have data members whose size is fixed. If this type includes, for example, a variable sized array in it, then, this type does not have a known fixed size. Because this array can have any size at runtime (i.e. it can be an array of 2 elements, or 50 elements, or 1 thousand elements, etc.).\nFor example, a string object, which internally is an array of constant u8 values ([]const u8) has a variable size. It can be a string object with 100 or 500 characters in it. If we do not know at compile-time, which exact string will be stored inside this string object, then, we cannot calculate the size of this string object at compile-time. So, any type, or any struct declaration that you make, that includes a string data member that does not have an explicit fixed size, makes this type, or this new struct that you are declaring, a type that does not have a known fixed size at compile-time.\nIn contrast, if the type of this struct that you are declaring, includes a data member that is an array, but this array has a known fixed size, like [60]u8 (which declares an array of 60 u8 values), then, this type, or, this struct that you are declaring, becomes a type with a known fixed size at compile-time. And because of that, in this case, the zig compiler does not need to know at compile-time the exact value of any object of this type. Since the compiler can find the necessary size to store this object by looking at the size of its type.\nLet’s look at an example. In the source code below, we have two constant objects (name and array) declared. Because the values of these particular objects are written down, in the source code itself (\"Pedro\" and the number sequence from 1 to 4), the zig compiler can easily discover the values of these constant objects (name and array) during the compilation process. This is what “known at compile time” means. It refers to any object that you have in your Zig source code whose value can be identified at compile time.\n\nfn input_length(input: []const u8) usize {\n    const n = input.len;\n    return n;\n}\n\npub fn main() !void {\n    const name = \"Pedro\";\n    const array = [_]u8{1, 2, 3, 4};\n    _ = name; _ = array;\n}\n\nThe other side of the spectrum are objects whose values are not known at compile time. Function arguments are a classic example of this. Because the value of each function argument depends on the value that you assign to this particular argument, when you call the function.\nFor example, the function input_length() contains an argument named input, which is an array of constant u8 integers ([]const u8). It is impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length of this particular argument. Because it is an array that do not have a fixed size specified explicitly in the argument type annotation.\nSo, we know that this input argument will be an array of u8 integers. But we do not know at compile-time, its value, and neither his size. This information is known only at runtime, which is the period of time when you program is executed. As a consequence, the value of the expression input.len is also known only at runtime. This is an intrinsic characteristic of any function. Just remember that the value of function arguments is usually not “compile-time known”.\nHowever, as I mentioned earlier, what really matters to the compiler is to know the size of the object at compile-time, and not necessarily its value. So, although we don’t know the value of the object n, which is the result of the expression input.len, at compile-time, we do know its size. Because the expression input.len always returns a value of type usize, and the type usize has a known fixed size.\n\n\n3.1.2 Global data register\nThe global data register is a specific section of the executable of your Zig program, that is responsible for storing any value that is known at compile time.\nEvery constant object whose value is known at compile time that you declare in your source code, is stored in the global data register. Also, every literal value that you write in your source code, such as the string \"this is a string\", or the integer 10, or a boolean value such as true, is also stored in the global data register.\nHonestly, you don’t need to care much about this memory space. Because you can’t control it, you can’t deliberately access it or use it for your own purposes. Also, this memory space does not affect the logic of your program. It simply exists in your program.\n\n\n3.1.3 Stack vs Heap\nIf you are familiar with system’s programming, or just low-level programming in general, you probably have heard of the “duel” between Stack vs Heap. These are two different types of memory, or different memory spaces, which are both available in Zig.\nThese two types of memory don’t actually duel with each other. This is a common mistake that beginners have, when seeing “x vs y” styles of tabloid headlines. These two types of memory are actually complementary to each other. So, in almost every Zig program that you ever write, you will likely use a combination of both. I will describe each memory space in detail over the next sections. But for now, I just want to stablish the main difference between these two types of memory.\nIn essence, the stack memory is normally used to store values whose length is fixed and known at compile time. In contrast, the heap memory is a dynamic type of memory space, meaning that, it is used to store values whose length might grow during the execution (runtime) of your program (Chen and Guo 2022).\nLengths that grow during runtime are intrinsically associated with “runtime known” type of values. In other words, if you have an object whose length might grow during runtime, then, the length of this object becomes not known at compile time. If the length is not known at compile-time, the value of this object also becomes not known at compile-time. These types of objects should be stored in the heap memory space, which is a dynamic memory space, which can grow or shrink to fit the size of your objects.\n\n\n3.1.4 Stack\nThe stack is a type of memory that uses the power of the stack data structure, hence the name. A “stack” is a type of data structure that uses a “last in, first out” (LIFO) mechanism to store the values you give it to. I imagine you are familiar with this data structure. But, if you are not, the Wikipedia page1 , or, the Geeks For Geeks page2 are both excellent and easy resources to fully understand how this data structure works.\nSo, the stack memory space is a type of memory that stores values using a stack data structure. It adds and removes values from the memory by following a “last in, first out” (LIFO) principle.\nEvery time you make a function call in Zig, an amount of space in the stack is reserved for this particular function call (Chen and Guo 2022; Zig Software Foundation 2024). The value of each function argument given to the function in this function call is stored in this stack space. Also, every local object that you declare inside the function scope is usually stored in this same stack space.\nLooking at the example below, the object result is a local object declared inside the scope of the add() function. Because of that, this object is stored inside the stack space reserved for the add() function. The r object (which is declared outside of the add() function scope) is also stored in the stack. But since it is declared in the “outer” scope, this object is stored in the stack space that belongs to this outer scope.\n\nfn add(x: u8, y: u8) u8 {\n    const result = x + y;\n    return result;\n}\n\npub fn main() !void {\n    const r = add(5, 27);\n    _ = r;\n}\n\nSo, any object that you declare inside the scope of a function is always stored inside the space that was reserved for that particular function in the stack memory. This also counts for any object declared inside the scope of your main() function for example. As you would expect, in this case, they are stored inside the stack space reserved for the main() function.\nOne very important detail about the stack memory is that it frees itself automatically. This is very important, remember that. When objects are stored in the stack memory, you don’t have the work (or the responsibility) of freeing/destroying these objects. Because they will be automatically destroyed once the stack space is freed at the end of the function scope.\nSo, once the function call returns (or ends, if you prefer to call it this way) the space that was reserved in the stack is destroyed, and all of the objects that were in that space goes away with it. This mechanism exists because this space, and the objects within it, are not necessary anymore, since the function “finished its business”. Using the add() function that we exposed above as an example, it means that the object result is automatically destroyed once the function returns.\n\n\n\n\n\n\nImportant\n\n\n\nLocal objects that are stored in the stack space of a function are automatically freed/destroyed at the end of the function scope.\n\n\nThis same logic applies to any other special structure in Zig that have its own scope by surrounding it with curly braces ({}). For loops, while loops, if else statements, etc. For example, if you declare any local object in the scope of a for loop, this local object is accessible only within the scope of this particular for loop. Because once the scope of this for loop ends, the space in the stack reserved for this for loop is freed. The example below demonstrates this idea.\n\n// This does not compile successfully!\nconst a = [_]u8{0, 1, 2, 3, 4};\nfor (0..a.len) |i| {\n    const index = i;\n    _ = index;\n}\n// Trying to use an object that was\n// declared in the for loop scope,\n// and that does not exist anymore.\nstd.debug.print(\"{d}\\n\", .{index});\n\nOne important consequence of this mechanism is that, once the function returns, you can no longer access any memory address that was inside the space in the stack reserved for this particular function. Because this space was destroyed. This means that, if this local object is stored in the stack, you cannot make a function that returns a pointer to this object.\nThink about that for a second. If all local objects in the stack are destroyed at the end of the function scope, why would you even consider returning a pointer to one of these objects? This pointer is at best, invalid, or, more likely, “undefined”.\nConclusion, it is totally fine to write a function that returns the local object itself as result, because then, you return the value of that object as the result. But, if this local object is stored in the stack, you should never write a function that returns a pointer to this local object. Because the memory address pointed by the pointer no longer exists.\nSo, using again the add() function as an example, if you rewrite this function so that it returns a pointer to the local object result, the zig compiler will actually compile your program, with no warnings or errors. At first glance, it looks that this is good code that works as expected. But this is a lie!\nIf you try to take a look at the value inside of the r object, or, if you try to use this r object in another expression or function call, then, you would have undefined behaviour, and major bugs in your program (Zig Software Foundation 2024, see “Lifetime and Ownership”3 and “Undefined Behaviour”4 sections).\n\nfn add(x: u8, y: u8) *const u8 {\n    const result = x + y;\n    return &result;\n}\n\npub fn main() !void {\n    // This code compiles successfully. But it has\n    // undefined behaviour. Never do this!!!\n    // The `r` object is undefined!\n    const r = add(5, 27); _ = r;\n}\n\nThis “invalid pointer to stack variable” problem is very known across many programming language communities. If you try to do the same thing, for example, in a C or C++ program (i.e. returning an address to a local object stored in the stack), you would also get undefined behaviour in the program.\n\n\n\n\n\n\nImportant\n\n\n\nIf a local object in your function is stored in the stack, you should never return a pointer to this local object from the function. Because this pointer will always become undefined after the function returns, since the stack space of the function is destroyed at the end of its scope.\n\n\nBut what if you really need to use this local object in some way after your function returns? How can you do this? The answer is: “in the same you would do if this was a C or C++ program. By returning an address to an object stored in the heap”. The heap memory has a much more flexible lifecycle, and allows you to get a valid pointer to a local object of a function that already returned from its scope.\n\n\n3.1.5 Heap\nOne important limitation of the stack, is that, only objects whose length/size is known at compile-time can be stored in it. In contrast, the heap is a much more dynamic (and flexible) type of memory. It is the perfect type of memory to use for objects whose size/length might grow during the execution of your program.\nVirtually any application that behaves as a server is a classic use case of the heap. A HTTP server, a SSH server, a DNS server, a LSP server, … any type of server. In summary, a server is a type of application that runs for long periods of time, and that serves (or “deals with”) any incoming request that reaches this particular server.\nThe heap is a good choice for this type of system, mainly because the server does not know upfront how many requests it will receive from users, while it is active. It could be one single request, or, 5 thousand requests, or, it could also be zero requests. The server needs to have the ability to allocate and manage its memory according to how many requests it receives.\nAnother key difference between the stack and the heap, is that the heap is a type of memory that you, the programmer, have complete control over. This makes the heap a more flexible type of memory, but it also makes it harder to work with. Because you, the programmer, is responsible for managing everything related to it. Including where the memory is allocated, how much memory is allocated, and where this memory is freed.\n\nUnlike stack memory, heap memory is allocated explicitly by programmers and it won’t be deallocated until it is explicitly freed (Chen and Guo 2022).\n\nTo store an object in the heap, you, the programmer, needs to explicitly tells Zig to do so, by using an allocator to allocate some space in the heap. At Section 3.3, I will present how you can use allocators to allocate memory in Zig.\n\n\n\n\n\n\nImportant\n\n\n\nEvery memory you allocate in the heap needs to be explicitly freed by you, the programmer.\n\n\nThe majority of allocators in Zig do allocate memory on the heap. But some exceptions to this rule are ArenaAllocator() and FixedBufferAllocator(). The ArenaAllocator() is a special type of allocator that works in conjunction with a second type of allocator. On the other side, the FixedBufferAllocator() is an allocator that works based on buffer objects created on the stack. This means that the FixedBufferAllocator() makes allocations only on the stack.\n\n\n3.1.6 Summary\nAfter discussing all of these boring details, we can quickly recap what we learned. In summary, the Zig compiler will use the following rules to decide where each object you declare is stored:\n\nevery literal value (such as \"this is string\", 10, or true) is stored in the global data section.\nevery constant object (const) whose value is known at compile-time is also stored in the global data section.\nevery object (constant or not) whose length/size is known at compile time is stored in the stack space for the current scope.\nif an object is created with the method alloc() or create() of an allocator object, this object is stored in the memory space used by this particular allocator object. Most of allocators available in Zig use the heap memory, so, this object is likely stored in the heap (FixedBufferAllocator() is an exception to that).\nthe heap can only be accessed through allocators. If your object was not created through the alloc() or create() methods of an allocator object, then, he is most certainly not an object stored in the heap.",
     "crumbs": [
       "<span class='chapter-number'>3</span>  <span class='chapter-title'>Memory and Allocators</span>"
     ]
@@ -364,7 +364,7 @@
     "href": "Chapters/01-base64.html#how-the-base64-algorithm-work",
     "title": "4  Project 1 - Building a base64 encoder/decoder",
     "section": "",
-    "text": "4.1.1 The base64 scale\nThe base64 encoding system is based on a scale that goes from 0 to 63 (hence the name). Each index in this scale is represented by a character (it is a scale of 64 characters). So, in order to convert some binary data, to the base64 encoding, we need to convert each binary number to the corresponding character in this “scale of 64 characters”.\nThe base64 scale starts with all ASCII uppercase letters (A to Z) which represents the first 25 indexes in this scale (0 to 25). After that, we have all ASCII lowercase letters (a to z), which represents the range 26 to 51 in the scale. After that, we have the one digit numbers (0 to 9), which represents the indexes from 52 to 61 in the scale. Finally, the last two indexes in the scale (62 and 63) are represented by the characters + and /, respectively.\nThese are the 64 characters that compose the base64 scale. The equal sign character (=) is not part of the scale itself, but it is a special character in the base64 encoding system. This character is used solely as a suffix, to mark the end of the character sequence, or, to mark the end of meaningful characters in the sequence.\nThe bullet points below summarises the base64 scale:\n\nrange 0 to 25 is represented by: ASCII uppercase letters -&gt; [A-Z];\nrange 26 to 51 is represented by: ASCII lowercase letters -&gt; [a-z];\nrange 52 to 61 is represented by: one digit numbers -&gt; [0-9];\nindex 62 and 63 are represented by the characters + and /, respectively;\nthe character = represents the end of meaningful characters in the sequence;\n\n\n\n4.1.2 Creating the scale as a lookup table\nThe best way to represent this scale in code, is to represent it as a lookup table. Lookup tables are a classic strategy in computer science to speed up calculations. The basic idea is to replace a runtime calculation (which can take a long time to be done) with a basic array indexing operation.\nInstead of calculating the results everytime you need them, you calculate all possible results at once, and then, you store them in an array (which behaves lake a “table”). Then, every time you need to use one of the characters in the base64 scale, instead of using many resources to calculate the exact character to be used, you simply retrieve this character from the array where you stored all the possible characters in the base64 scale. We retrieve the character that we need directly from memory.\nWe can start building a Zig struct to store our base64 decoder/encoder logic. We start with the Base64 struct below. For now, we only have one single data member in this struct, i.e. the member _table, which represents our lookup table. We also have an init() method, to create a new instance of a Base64 object, and, a _char_at() method, which is a “get character at index \\(x\\)” type of function.\n\nconst Base64 = struct {\n    _table: *const [64]u8,\n\n    pub fn init() Base64 {\n        const upper = \"ABCDEFGHIJKLMNOPQRSTUVWXYZ\";\n        const lower = \"abcdefghijklmnopqrstuvwxyz\";\n        const numbers_symb = \"0123456789+/\";\n        return Base64{\n            ._table = upper ++ lower ++ numbers_symb,\n        };\n    }\n\n    pub fn _char_at(self: Base64, index: u8) u8 {\n        return self._table[index];\n    }\n};\n\nIn other words, the _char_at() method is responsible for getting the character in the lookup table (i.e. the _table struct data member) that corresponds to a particular index in the “base64 scale”. So, in the example below, we know that the character that corresponds to the index 28 in the “base64 scale” is the character “c”.\n\nconst base64 = Base64.init();\ntry stdout.print(\n    \"Character at index 28: {c}\\n\",\n    .{base64._char_at(28)}\n);\n\nCharacter at index 28: c\n\n\n4.1.3 A base64 encoder\nThe algorithm behind a base64 encoder usually works on a window of 3 bytes. Because each byte has 8 bits, so, 3 bytes forms a set of \\(8 \\times 3 = 24\\) bits. This is desirable for the base64 algorithm, because 24 bits is divisible by 6, which forms \\(24 / 6 = 4\\) groups of 6 bits each.\nTherefore, the base64 algorithm works by converting 3 bytes at a time into 4 characters from the base64 scale. It keeps iterating through the input string, 3 bytes at a time, and converting them into the base64 scale, producing 4 characters per iteration. It keeps iterating, and producing these “new characters” until it hits the end of the input string.\nNow, you may think, what if you have a particular string that have a number of bytes that is not divisible by 3? What happens? For example, if you have a string that contains only two characters/bytes, such as “Hi”. How the algorithm would behave in such situation? You find the answer at Figure 4.1. You can see at Figure 4.1 that the string “Hi”, when converted to base64, becomes the string “SGk=”:\n\n\n\n\n\n\nFigure 4.1: The logic behind a base64 encoder\n\n\n\nTaking the string “Hi” as an example, we have 2 bytes, or, 16 bits in total. So, we lack a full byte (8 bits) to complete the window of 24 bits that the base64 algorithm likes to work on. The first thing that the algorithm does, is to check how to divide the input bytes into groups of 6 bits.\nIf the algorithm notices that there is a group of 6 bits that, have some bits in it, but, at the same time, it is not full (in other words, \\(0 &lt; nbits &lt; 6\\), being \\(nbits\\) the number of bits), meaning that, it lacks some bits to fill the 6-bits requirement, the algorithm simply add extra zeros in this group to fill the space that it needs. That is why at Figure 4.1, on the third group after the 6-bit transformation, 2 extra zeros were added to fill the gap in this group.\nWhen we have a 6-bit group that is not completely full, like the third group, extra zeros are added to fill the gap. But what about when an entire 6-bit group is empty, or, it simply doesn’t exist? This is the case of the fourth 6-bit group exposed at Figure 4.1.\nThis fourth group is necessary, because the algorithm works on 4 groups of 6 bits. But the input string does not have enough bytes to create a fourth 6-bit group. Every time this happens, where an entire group of 6 bits is empty, this group becomes a “padding group”. Every “padding group” is mapped to the character = (equal sign), which represents “null”, or, the end of meaningful characters in the sequence. Hence, everytime that the algorithm produces a “padding group”, this group is automatically mapped to =.\nAs another example, if you give the string “0” as input to a base64 encoder, this string is translated into the base64 sequence “MA==”. The character “0” is, in binary, the sequence 001100001. So, with the 6-bit transformation exposed at Figure 4.1, this single character would produce these two 6-bit groups: 001100, 000000. The remaining two 6-bit groups become “padding groups”. That is why the last two characters in the output sequence (MA==) are ==.\n\n\n4.1.4 A base64 decoder\nThe algorithm behind a base64 decoder is essentially the inverse process of a base64 encoder. A base64 decoder needs to translate base64 messages back into their original meaning, i.e. into the original sequence of binary data.\nA base64 decoder usually works on a window of 4 bytes. Because it wants to convert these 4 bytes back into the original sequence of 3 bytes, that was converted into 4 groups of 6 bits by the base64 encoder. Remember, in a base64 decoder we are essentially reverting the process made by the base64 encoder.\nEach byte in the input string (the base64 encoded string) normally contributes to re-create two different bytes in the output (the original binary data). In other words, each byte that comes out of a base64 decoder is created by transforming merging two different bytes in the input together. You can visualize this relationship at Figure 4.2:\n\n\n\n\n\n\nFigure 4.2: The logic behind a base64 decoder\n\n\n\nThe exact transformations, or, the exact steps applied to each byte from the input to transform them into the bytes of the output, are a bit tricky to visualize in a figure like this. Because of that, I have summarized these transformations as “Some bit shifting and additions …” in the figure. These transformations will be described in depth later.\nBesides that, if you look again at Figure 4.2, you will notice that the character = was completely ignored by the algorithm. Remember, this is just a special character that marks the end of meaningful characters in the base64 sequence. So, every = character in a base64 encoded sequence should be ignored by a base64 decoder.",
+    "text": "4.1.1 The base64 scale\nThe base64 encoding system is based on a scale that goes from 0 to 63 (hence the name). Each index in this scale is represented by a character (it is a scale of 64 characters). So, in order to convert some binary data, to the base64 encoding, we need to convert each binary number to the corresponding character in this “scale of 64 characters”.\nThe base64 scale starts with all ASCII uppercase letters (A to Z) which represents the first 25 indexes in this scale (0 to 25). After that, we have all ASCII lowercase letters (a to z), which represents the range 26 to 51 in the scale. After that, we have the one digit numbers (0 to 9), which represents the indexes from 52 to 61 in the scale. Finally, the last two indexes in the scale (62 and 63) are represented by the characters + and /, respectively.\nThese are the 64 characters that compose the base64 scale. The equal sign character (=) is not part of the scale itself, but it is a special character in the base64 encoding system. This character is used solely as a suffix, to mark the end of the character sequence, or, to mark the end of meaningful characters in the sequence.\nThe bullet points below summarises the base64 scale:\n\nrange 0 to 25 is represented by: ASCII uppercase letters -&gt; [A-Z];\nrange 26 to 51 is represented by: ASCII lowercase letters -&gt; [a-z];\nrange 52 to 61 is represented by: one digit numbers -&gt; [0-9];\nindex 62 and 63 are represented by the characters + and /, respectively;\nthe character = represents the end of meaningful characters in the sequence;\n\n\n\n4.1.2 Creating the scale as a lookup table\nThe best way to represent this scale in code, is to represent it as a lookup table. Lookup tables are a classic strategy in computer science to speed up calculations. The basic idea is to replace a runtime calculation (which can take a long time to be done) with a basic array indexing operation.\nInstead of calculating the results everytime you need them, you calculate all possible results at once, and then, you store them in an array (which behaves lake a “table”). Then, every time you need to use one of the characters in the base64 scale, instead of using many resources to calculate the exact character to be used, you simply retrieve this character from the array where you stored all the possible characters in the base64 scale. We retrieve the character that we need directly from memory.\nWe can start building a Zig struct to store our base64 decoder/encoder logic. We start with the Base64 struct below. For now, we only have one single data member in this struct, i.e. the member _table, which represents our lookup table. We also have an init() method, to create a new instance of a Base64 object, and, a _char_at() method, which is a “get character at index \\(x\\)” type of function.\n\nconst Base64 = struct {\n    _table: *const [64]u8,\n\n    pub fn init() Base64 {\n        const upper = \"ABCDEFGHIJKLMNOPQRSTUVWXYZ\";\n        const lower = \"abcdefghijklmnopqrstuvwxyz\";\n        const numbers_symb = \"0123456789+/\";\n        return Base64{\n            ._table = upper ++ lower ++ numbers_symb,\n        };\n    }\n\n    pub fn _char_at(self: Base64, index: usize) u8 {\n        return self._table[index];\n    }\n};\n\nIn other words, the _char_at() method is responsible for getting the character in the lookup table (i.e. the _table struct data member) that corresponds to a particular index in the “base64 scale”. So, in the example below, we know that the character that corresponds to the index 28 in the “base64 scale” is the character “c”.\n\nconst base64 = Base64.init();\ntry stdout.print(\n    \"Character at index 28: {c}\\n\",\n    .{base64._char_at(28)}\n);\n\nCharacter at index 28: c\n\n\n4.1.3 A base64 encoder\nThe algorithm behind a base64 encoder usually works on a window of 3 bytes. Because each byte has 8 bits, so, 3 bytes forms a set of \\(8 \\times 3 = 24\\) bits. This is desirable for the base64 algorithm, because 24 bits is divisible by 6, which forms \\(24 / 6 = 4\\) groups of 6 bits each.\nTherefore, the base64 algorithm works by converting 3 bytes at a time into 4 characters from the base64 scale. It keeps iterating through the input string, 3 bytes at a time, and converting them into the base64 scale, producing 4 characters per iteration. It keeps iterating, and producing these “new characters” until it hits the end of the input string.\nNow, you may think, what if you have a particular string that have a number of bytes that is not divisible by 3? What happens? For example, if you have a string that contains only two characters/bytes, such as “Hi”. How the algorithm would behave in such situation? You find the answer at Figure 4.1. You can see at Figure 4.1 that the string “Hi”, when converted to base64, becomes the string “SGk=”:\n\n\n\n\n\n\nFigure 4.1: The logic behind a base64 encoder\n\n\n\nTaking the string “Hi” as an example, we have 2 bytes, or, 16 bits in total. So, we lack a full byte (8 bits) to complete the window of 24 bits that the base64 algorithm likes to work on. The first thing that the algorithm does, is to check how to divide the input bytes into groups of 6 bits.\nIf the algorithm notices that there is a group of 6 bits that, have some bits in it, but, at the same time, it is not full (in other words, \\(0 &lt; nbits &lt; 6\\), being \\(nbits\\) the number of bits), meaning that, it lacks some bits to fill the 6-bits requirement, the algorithm simply add extra zeros in this group to fill the space that it needs. That is why at Figure 4.1, on the third group after the 6-bit transformation, 2 extra zeros were added to fill the gap in this group.\nWhen we have a 6-bit group that is not completely full, like the third group, extra zeros are added to fill the gap. But what about when an entire 6-bit group is empty, or, it simply doesn’t exist? This is the case of the fourth 6-bit group exposed at Figure 4.1.\nThis fourth group is necessary, because the algorithm works on 4 groups of 6 bits. But the input string does not have enough bytes to create a fourth 6-bit group. Every time this happens, where an entire group of 6 bits is empty, this group becomes a “padding group”. Every “padding group” is mapped to the character = (equal sign), which represents “null”, or, the end of meaningful characters in the sequence. Hence, everytime that the algorithm produces a “padding group”, this group is automatically mapped to =.\nAs another example, if you give the string “0” as input to a base64 encoder, this string is translated into the base64 sequence “MA==”. The character “0” is, in binary, the sequence 001100001. So, with the 6-bit transformation exposed at Figure 4.1, this single character would produce these two 6-bit groups: 001100, 000000. The remaining two 6-bit groups become “padding groups”. That is why the last two characters in the output sequence (MA==) are ==.\n\n\n4.1.4 A base64 decoder\nThe algorithm behind a base64 decoder is essentially the inverse process of a base64 encoder. A base64 decoder needs to translate base64 messages back into their original meaning, i.e. into the original sequence of binary data.\nA base64 decoder usually works on a window of 4 bytes. Because it wants to convert these 4 bytes back into the original sequence of 3 bytes, that was converted into 4 groups of 6 bits by the base64 encoder. Remember, in a base64 decoder we are essentially reverting the process made by the base64 encoder.\nEach byte in the input string (the base64 encoded string) normally contributes to re-create two different bytes in the output (the original binary data). In other words, each byte that comes out of a base64 decoder is created by transforming merging two different bytes in the input together. You can visualize this relationship at Figure 4.2:\n\n\n\n\n\n\nFigure 4.2: The logic behind a base64 decoder\n\n\n\nThe exact transformations, or, the exact steps applied to each byte from the input to transform them into the bytes of the output, are a bit tricky to visualize in a figure like this. Because of that, I have summarized these transformations as “Some bit shifting and additions …” in the figure. These transformations will be described in depth later.\nBesides that, if you look again at Figure 4.2, you will notice that the character = was completely ignored by the algorithm. Remember, this is just a special character that marks the end of meaningful characters in the base64 sequence. So, every = character in a base64 encoded sequence should be ignored by a base64 decoder.",
     "crumbs": [
       "<span class='chapter-number'>4</span>  <span class='chapter-title'>Project 1 - Building a base64 encoder/decoder</span>"
     ]
@@ -404,7 +404,7 @@
     "href": "Chapters/01-base64.html#sec-decoder-logic",
     "title": "4  Project 1 - Building a base64 encoder/decoder",
     "section": "4.5 Building the decoder logic",
-    "text": "4.5 Building the decoder logic\nNow, we can focus on writing the base64 decoder logic. Remember from Figure 4.2 that, a base64 decoder does the inverse process of an encoder. So, all we need to do, is to write a decode() function that performs the inverse process that I exposed at Section 4.4.\n\n4.5.1 Mapping base64 characters to their indexes\nOne thing that we need to do, in order to decode a base64-encoded message, is to calculate the index in the base64 scale of every base64 character that we encounter in the decoder input.\nIn other words, the decoder receives as input, a sequence of base64 characters. We need to translate this sequence of characters into a sequence of indexes. These indexes are the index of each character in the base64 scale. This way, we get the value/byte that was calculated in the 6-bit transformation step of the encoder process.\nThere are probably better/faster ways to calculate this, especially using a “divide and conquer” type of strategy. But for now, I am satisfied with a simple and “brute force” type of strategy. The _char_index() function below contains this strategy.\nWe are essentially looping through the lookup table with the base64 scale, and comparing the character we got with each character in the base64 scale. If these characters match, then, we return the index of this character in the base64 scale as the result.\nNotice that, if the input character is '=', the function returns the index 64, which is “out of range” in the scale. But, as I described at Section 4.1.1, the character '=' does not belong to the base64 scale itself. It is a special and meaningless character in base64.\nAlso notice that this _char_index() function is a method from our Base64 struct, because of the self argument. Again, I have omitted the Base64 struct definition in this example for brevity reasons.\n\nfn _char_index(self: Base64, char: u8) u8 {\n    if (char == '=')\n        return 64;\n    var index: u8 = 0;\n    for (0..63) |i| {\n        if (self._char_at(i) == char) {\n            index = i;\n            break;\n        }\n    }\n\n    return index;\n}\n\n\n\n4.5.2 The 6-bit transformation\nOnce again, the core part of the algorithm is the 6-bit transformation. If we understand the necessary steps to perform this transformation, the rest of the algorithm becomes much easier.\nFirst of all, before we actually go to the 6-bit transformation, we need to make sure that we use _char_index() to convert the sequence of base64 characters into a sequence of indexes. So the snippet below is important for the job that will be done. The result of _char_index() is stored in a temporary buffer, and this temporary buffer is what we are going to use in the 6-bit transformation, instead of the actual input object.\n\nfor (0..input.len) |i| {\n    buf[i] = self._char_index(input[i]);\n}\n\nNow, instead of producing 4 bytes (or 4 characters) as output per each window of 3 characters in the input, a base64 decoder produces 3 bytes (or 3 characters) as output per each window of 4 characters in the input. Once again, is the inverse process.\nSo, the steps to produce the 3 bytes in the output are:\n\noutput[0] is produced by summing two components. First, move the bits from buf[0] two positions to the left. Second, move the bits from buf[1] 4 positions to the right. Then, sum these two components.\noutput[1] is produced by summing two components. First, move the bits from buf[1] four positions to the left. Second, move the bits from buf[2] 2 positions to the right. Then, sum these two components.\noutput[2] is produced by summing two components. First, move the bits from buf[2] six positions to the left. Then, you sum the result with buf[3].\n\nBefore we continue, let’s try to visualize how these transformations make the original bytes that we had before the encoding process. First, think back to the 6-bit transformation performed by the encoder exposed at Section 4.4. The first byte in the output of the encoder is produced by moving the bits in the first byte of the input two positions to the right.\nIf for example the first byte in the input of the encoder was the sequence ABCDEFGH, then, the first byte in the output of the encoder would be 00ABCDEF (this sequence would be the first byte in the input of the decoder). Now, if the second byte in the input of the encoder was the sequence IJKLMNOP, then, the second byte in the encoder output would be 00GHIJKL (as we demonstrated at Figure 4.3).\nHence, if the sequences 00ABCDEF and 00GHIJKL are the first and second bytes, respectively, in the input of the decoder, the Figure 4.4 demonstrates visually how these two bytes are transformed into the first byte of the output of the decoder. Notice that the output byte is the sequence ABCDEFGH, which is the original byte from the input of the encoder.\n\n\n\n\n\n\nFigure 4.4: How the 1st byte in the decoder output is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input\n\n\n\nThe Table 4.2 presents how the three steps described earlier translate into Zig code:\n\n\n\nTable 4.2: The necessary steps for the 6-transformation in the decode process.\n\n\n\n\n\nByte index in the output\nIn code\n\n\n\n\n0\n(buf[0] &lt;&lt; 2) + (buf[1] &gt;&gt; 4)\n\n\n1\n(buf[1] &lt;&lt; 4) + (buf[2] &gt;&gt; 2)\n\n\n2\n(buf[2] &lt;&lt; 6) + buf[3]\n\n\n\n\n\n\n\n\n4.5.3 Writing the decode() function\nThe decode() function below contains the entire decoding process. We first calculate the size of the output, with _calc_decode_length(), then, we allocate enough memory for this output with the allocator object.\nThree temporary variables are created: 1) count, to hold the window count in each iteration of the for loop; 2) iout, to hold the current index in the output; 3) buf, which is the temporary buffer that holds the base64 indexes to be converted through the 6-bit transformation.\nThen, in each iteration of the for loop we fill the temporary buffer with the current window of bytes. When count hits the number 4, then, we have a full window of indexes in buf to be converted, and then, we apply the 6-bit transformation over the temporary buffer.\nNotice that we check if the indexes 2 and 3 in the temporary buffer are the number 64, which, if you recall from Section 4.5.1, is when the _calc_index() function receives a '=' character as input. So, if these indexes are equal to the number 64, the decode() function knows that it can simply ignore these indexes. They are not converted because, as I described before, the character '=' has no meaning, despite being the end of meaningful characters in the sequence. So we can safely ignore them when they appear in the sequence.\n\nfn decode(self: Base64,\n          allocator: std.mem.Allocator,\n          input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n    const n_output = try _calc_decode_length(input);\n    var output = try allocator.alloc(u8, n_output);\n    var count: u8 = 0;\n    var iout: u64 = 0;\n    var buf = [4]u8{ 0, 0, 0, 0 };\n\n    for (0..input.len) |i| {\n        buf[count] = self._char_index(input[i]);\n        count += 1;\n        if (count == 4) {\n            output[iout] = (buf[0] &lt;&lt; 2) + (buf[1] &gt;&gt; 4);\n            if (buf[2] != 64) {\n                output[iout + 1] = (buf[1] &lt;&lt; 4) + (buf[2] &gt;&gt; 2);\n            }\n            if (buf[3] != 64) {\n                output[iout + 2] = (buf[2] &lt;&lt; 6) + buf[3];\n            }\n            iout += 3;\n            count = 0;\n        }\n    }\n\n    return output;\n}",
+    "text": "4.5 Building the decoder logic\nNow, we can focus on writing the base64 decoder logic. Remember from Figure 4.2 that, a base64 decoder does the inverse process of an encoder. So, all we need to do, is to write a decode() function that performs the inverse process that I exposed at Section 4.4.\n\n4.5.1 Mapping base64 characters to their indexes\nOne thing that we need to do, in order to decode a base64-encoded message, is to calculate the index in the base64 scale of every base64 character that we encounter in the decoder input.\nIn other words, the decoder receives as input, a sequence of base64 characters. We need to translate this sequence of characters into a sequence of indexes. These indexes are the index of each character in the base64 scale. This way, we get the value/byte that was calculated in the 6-bit transformation step of the encoder process.\nThere are probably better/faster ways to calculate this, especially using a “divide and conquer” type of strategy. But for now, I am satisfied with a simple and “brute force” type of strategy. The _char_index() function below contains this strategy.\nWe are essentially looping through the lookup table with the base64 scale, and comparing the character we got with each character in the base64 scale. If these characters match, then, we return the index of this character in the base64 scale as the result.\nNotice that, if the input character is '=', the function returns the index 64, which is “out of range” in the scale. But, as I described at Section 4.1.1, the character '=' does not belong to the base64 scale itself. It is a special and meaningless character in base64.\nAlso notice that this _char_index() function is a method from our Base64 struct, because of the self argument. Again, I have omitted the Base64 struct definition in this example for brevity reasons.\n\nfn _char_index(self: Base64, char: u8) u8 {\n    if (char == '=')\n        return 64;\n    var index: u8 = 0;\n    for (0..63) |i| {\n        if (self._char_at(i) == char)\n            break;\n        index += 1;\n    }\n\n    return index;\n}\n\n\n\n4.5.2 The 6-bit transformation\nOnce again, the core part of the algorithm is the 6-bit transformation. If we understand the necessary steps to perform this transformation, the rest of the algorithm becomes much easier.\nFirst of all, before we actually go to the 6-bit transformation, we need to make sure that we use _char_index() to convert the sequence of base64 characters into a sequence of indexes. So the snippet below is important for the job that will be done. The result of _char_index() is stored in a temporary buffer, and this temporary buffer is what we are going to use in the 6-bit transformation, instead of the actual input object.\n\nfor (0..input.len) |i| {\n    buf[i] = self._char_index(input[i]);\n}\n\nNow, instead of producing 4 bytes (or 4 characters) as output per each window of 3 characters in the input, a base64 decoder produces 3 bytes (or 3 characters) as output per each window of 4 characters in the input. Once again, is the inverse process.\nSo, the steps to produce the 3 bytes in the output are:\n\noutput[0] is produced by summing two components. First, move the bits from buf[0] two positions to the left. Second, move the bits from buf[1] 4 positions to the right. Then, sum these two components.\noutput[1] is produced by summing two components. First, move the bits from buf[1] four positions to the left. Second, move the bits from buf[2] 2 positions to the right. Then, sum these two components.\noutput[2] is produced by summing two components. First, move the bits from buf[2] six positions to the left. Then, you sum the result with buf[3].\n\nBefore we continue, let’s try to visualize how these transformations make the original bytes that we had before the encoding process. First, think back to the 6-bit transformation performed by the encoder exposed at Section 4.4. The first byte in the output of the encoder is produced by moving the bits in the first byte of the input two positions to the right.\nIf for example the first byte in the input of the encoder was the sequence ABCDEFGH, then, the first byte in the output of the encoder would be 00ABCDEF (this sequence would be the first byte in the input of the decoder). Now, if the second byte in the input of the encoder was the sequence IJKLMNOP, then, the second byte in the encoder output would be 00GHIJKL (as we demonstrated at Figure 4.3).\nHence, if the sequences 00ABCDEF and 00GHIJKL are the first and second bytes, respectively, in the input of the decoder, the Figure 4.4 demonstrates visually how these two bytes are transformed into the first byte of the output of the decoder. Notice that the output byte is the sequence ABCDEFGH, which is the original byte from the input of the encoder.\n\n\n\n\n\n\nFigure 4.4: How the 1st byte in the decoder output is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input\n\n\n\nThe Table 4.2 presents how the three steps described earlier translate into Zig code:\n\n\n\nTable 4.2: The necessary steps for the 6-transformation in the decode process.\n\n\n\n\n\nByte index in the output\nIn code\n\n\n\n\n0\n(buf[0] &lt;&lt; 2) + (buf[1] &gt;&gt; 4)\n\n\n1\n(buf[1] &lt;&lt; 4) + (buf[2] &gt;&gt; 2)\n\n\n2\n(buf[2] &lt;&lt; 6) + buf[3]\n\n\n\n\n\n\n\n\n4.5.3 Writing the decode() function\nThe decode() function below contains the entire decoding process. We first calculate the size of the output, with _calc_decode_length(), then, we allocate enough memory for this output with the allocator object.\nThree temporary variables are created: 1) count, to hold the window count in each iteration of the for loop; 2) iout, to hold the current index in the output; 3) buf, which is the temporary buffer that holds the base64 indexes to be converted through the 6-bit transformation.\nThen, in each iteration of the for loop we fill the temporary buffer with the current window of bytes. When count hits the number 4, then, we have a full window of indexes in buf to be converted, and then, we apply the 6-bit transformation over the temporary buffer.\nNotice that we check if the indexes 2 and 3 in the temporary buffer are the number 64, which, if you recall from Section 4.5.1, is when the _calc_index() function receives a '=' character as input. So, if these indexes are equal to the number 64, the decode() function knows that it can simply ignore these indexes. They are not converted because, as I described before, the character '=' has no meaning, despite being the end of meaningful characters in the sequence. So we can safely ignore them when they appear in the sequence.\n\nfn decode(self: Base64,\n          allocator: std.mem.Allocator,\n          input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n    const n_output = try _calc_decode_length(input);\n    var output = try allocator.alloc(u8, n_output);\n    var count: u8 = 0;\n    var iout: u64 = 0;\n    var buf = [4]u8{ 0, 0, 0, 0 };\n\n    for (0..input.len) |i| {\n        buf[count] = self._char_index(input[i]);\n        count += 1;\n        if (count == 4) {\n            output[iout] = (buf[0] &lt;&lt; 2) + (buf[1] &gt;&gt; 4);\n            if (buf[2] != 64) {\n                output[iout + 1] = (buf[1] &lt;&lt; 4) + (buf[2] &gt;&gt; 2);\n            }\n            if (buf[3] != 64) {\n                output[iout + 2] = (buf[2] &lt;&lt; 6) + buf[3];\n            }\n            iout += 3;\n            count = 0;\n        }\n    }\n\n    return output;\n}",
     "crumbs": [
       "<span class='chapter-number'>4</span>  <span class='chapter-title'>Project 1 - Building a base64 encoder/decoder</span>"
     ]
@@ -434,7 +434,7 @@
     "href": "Chapters/02-debugging.html",
     "title": "5  Debugging Zig applications",
     "section": "",
-    "text": "5.1 Print debugging\nWe begin with the classic and battle-tested print debugging strategy. The key advantage that debugging offers you is visibility. With print statements you can easily see what results and objects are being produced by your application.\nThat is the essence of print debugging. Is to use print expressions to see the values that are being generated by your program, and, as a result, get a much better understanding of how your program is behaving.\nMany programmers often resort to the print functions in Zig, such as the stdout.print(), or, the std.debug.print(), to get a better understanding of their programs. This is a known and old strategy that is very simple and effective, and it is better known within the programming community as print debugging. In Zig, you can print information to the stdout or stderr streams of your system.\nLet’s begin with stdout. First, you need to get access to the stdout, by calling the getStdOut() method, from the Zig Standard Library. This method returns a file descriptor object, and, through this object you can read/write to the stdout. I recommend you to check out all methods available in this object, by checking the page in the Zig Standard Library Official Reference for the type File1.\nFor our purpose here, which is to write something to the stdout, especially to debug our program, I recommend you to use the writer() method, which gives your a writer object. This writer object offers some helper methods to write stuff into the file descriptor object that represents the stdout stream. In special, the print() method.\nThe print() method from this writer object is a “print formatter” type of a function. In other words, this method works exactly like the printf() function from C, or, like println!() from Rust. In the first argument of the function, you specify a template string, and, in the second argument, you provide a list of values (or objects) that you want to insert into your template message.\nIdeally, the template string in the first argument should contain some format specifier. Each format specifier is matched to a value (or object) that you have listed in the second argument. So, if you provided 5 different objects in the second argument, then, the template string should contain 5 format specifiers, one for each object provided.\nEach format specifier is represented by a single letter, and you provide this format specifier inside a pair of curly braces. So, if you want to format your object using the string specifier (s), then, you can insert the text {s} in your template string. Here is a quick list of the most used format specifiers:\nThe code example below gives you an example of use of this print() method with the d format specifier.\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    _ = try stdout.print(\"Result: {d}\", .{result});\n}\n\nResult: 50\nIs important to emphasize that, the stdout.print() method, as you would expect, print your template string into the stdout stream of your system. However, you can also print your template string into the stderr stream if your prefer. All you need to do, is to replace the stdout.print() call with the function std.debug.print(). Like this:\nconst std = @import(\"std\");\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    std.debug.print(\"Result: {d}\\n\", .{result});\n}\n\nResult: 50\nYou could also achieve the exact same result by getting a file descriptor object to stderr, then, creating a writer object to stderr, then, using the print() method of this writer object, like in the example below:\nconst std = @import(\"std\");\nconst stderr = std.io.getStdErr().writer();\n// some more lines ...\n_ = try stderr.print(\"Result: {d}\", .{result});",
+    "text": "5.1 Print debugging\nWe begin with the classic and battle-tested print debugging strategy. The key advantage that debugging offers you is visibility. With print statements you can easily see what results and objects are being produced by your application.\nThat is the essence of print debugging. Is to use print expressions to see the values that are being generated by your program, and, as a result, get a much better understanding of how your program is behaving.\nMany programmers often resort to the print functions in Zig, such as the stdout.print(), or, the std.debug.print(), to get a better understanding of their programs. This is a known and old strategy that is very simple and effective, and it is better known within the programming community as print debugging. In Zig, you can print information to the stdout or stderr streams of your system.\nLet’s begin with stdout. First, you need to get access to the stdout, by calling the getStdOut() method, from the Zig Standard Library. This method returns a file descriptor object, and, through this object you can read/write to the stdout. I recommend you to check out all methods available in this object, by checking the page in the Zig Standard Library Official Reference for the type File1.\nFor our purpose here, which is to write something to the stdout, especially to debug our program, I recommend you to use the writer() method, which gives your a writer object. This writer object offers some helper methods to write stuff into the file descriptor object that represents the stdout stream. In special, the print() method.\nThe print() method from this writer object is a “print formatter” type of a function. In other words, this method works exactly like the printf() function from C, or, like println!() from Rust. In the first argument of the function, you specify a template string, and, in the second argument, you provide a list of values (or objects) that you want to insert into your template message.\nIdeally, the template string in the first argument should contain some format specifier. Each format specifier is matched to a value (or object) that you have listed in the second argument. So, if you provided 5 different objects in the second argument, then, the template string should contain 5 format specifiers, one for each object provided.\nEach format specifier is represented by a single letter, and you provide this format specifier inside a pair of curly braces. So, if you want to format your object using the string specifier (s), then, you can insert the text {s} in your template string. Here is a quick list of the most used format specifiers:\nThe code example below gives you an example of use of this print() method with the d format specifier.\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    try stdout.print(\"Result: {d}\", .{result});\n}\n\nResult: 50\nIs important to emphasize that, the stdout.print() method, as you would expect, print your template string into the stdout stream of your system. However, you can also print your template string into the stderr stream if your prefer. All you need to do, is to replace the stdout.print() call with the function std.debug.print(). Like this:\nconst std = @import(\"std\");\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    std.debug.print(\"Result: {d}\\n\", .{result});\n}\n\nResult: 50\nYou could also achieve the exact same result by getting a file descriptor object to stderr, then, creating a writer object to stderr, then, using the print() method of this writer object, like in the example below:\nconst std = @import(\"std\");\nconst stderr = std.io.getStdErr().writer();\n// some more lines ...\ntry stderr.print(\"Result: {d}\", .{result});",
     "crumbs": [
       "<span class='chapter-number'>5</span>  <span class='chapter-title'>Debugging Zig applications</span>"
     ]
@@ -454,7 +454,7 @@
     "href": "Chapters/02-debugging.html#debugging-through-debuggers",
     "title": "5  Debugging Zig applications",
     "section": "5.2 Debugging through debuggers",
-    "text": "5.2 Debugging through debuggers\nAlthough print debugging being a valid and very useful strategy, most programmers prefer to use a debugger to debug their programs. Since Zig is a low-level language, you can use either GDB (GNU Debugger), or LLDB (LLVM Project Debugger) as your debugger.\nBoth debuggers can work with Zig code, and it’s a matter of taste here. You choose the debugger of your preference, and you work with it. In this book, I will use LLDB as my debugger on the examples.\n\n5.2.1 Compile your source code in debug mode\nIn order to debug your program through a debugger, you must compile your source code in Debug mode. Because when you compile your source code in other modes (such as Release), the compiler usually strips out some essential information that is used by the debugger to read and track your program, like PDB (Program Database) files.\nBy compiling your source code in Debug mode, you ensure that the debugger will find the necessary information in your program to debug it. By default, the compiler uses the Debug mode when compiling your code. Having this in mind, when you compile your program with the build-exe command (which was described at Section 1.2.4), if you don’t specify an explicit mode through the -O command-line 2 argument, then, the compiler will compile your code in Debug mode.\n\n\n5.2.2 Let’s debug a program\nAs an example, let’s use LLDB to navigate and investigate the following piece of Zig code:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\nfn add_and_increment(a: u8, b: u8) u8 {\n    const sum = a + b;\n    const incremented = sum + 1;\n    return incremented;\n}\n\npub fn main() !void {\n    var n = add_and_increment(2, 3);\n    n = add_and_increment(n, n);\n    _ = try stdout.print(\"Result: {d}!\\n\", .{n});\n}\n\nResult: 13!\n\n\nThere is nothing wrong with this program. But it is a good start for us. First, we need to compile this program with the zig build-exe command. For this example, suppose that I have compiled the above Zig code into a binary executable called add_program.\nzig build-exe add_program.zig\nNow, we can start LLDB with add_program, like this:\nlldb add_program\nFrom now on, LLDB is started, and you can know that I’m executing LLDB commands by looking at the prefix (lldb). If something is prefixed with (lldb), then you know that it is a LLDB command.\nThe first thing I will do, is to set a breakpoint at the main() function, by executing b main. After that, I just start the execution of the program with run. You can see in the output below, that the execution stopped at the first line in the function main(), as we expected.\n(lldb) b main\nBreakpoint 1: where = debugging`debug1.main + 22\n    at debug1.zig:11:30, address = 0x00000000010341a6\n(lldb) run\nProcess 8654 launched: 'add_program' (x86_64)\nProcess 8654 stopped\n* thread #1, name = 'add_program',\n    stop reason = breakpoint 1.1 frame #0: 0x10341a6\n    add_program`debug1.main at add_program.zig:11:30\n   8    }\n   9    \n   10   pub fn main() !void {\n-&gt; 11       var n = add_and_increment(2, 3);\n   12       n = add_and_increment(n, n);\n   13       try stdout.print(\"Result: {d}!\\n\", .{n});\n   14   }\nI can start navigating through the code, and checking the objects that are being generated. If you are not familiar with the commands available in LLDB, I recommend you to read the official documentation of the project3. You can also look for cheat sheets, which quickly describes all commands available for you4.\nCurrently, we are in the first line at the main() function. In this line, we create the n object, by executing the add_and_increment() function. To execute the current line of code, and go to the next line, we can run the n LLDB command. Let’s execute this command.\nAfter we executed this line, we can also look at the value stored inside this n object by using the p LLDB command. The syntax for this command is p &lt;name-of-object&gt;.\nIf we take a look at the value stored in the n object (p n), notice that it stores the hexadecimal value 0x06, which is the number 6 in decimal. We can also see that, this value have a type unsigned char, which is an unsigned 8-bit integer. We have talked already about this at Section 1.8, that u8 integers in Zig are equivalent to the C data type unsigned char.\n(lldb) n\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step over frame #0: 0x10341ae\n    debugging`debug1.main at debug1.zig:12:26\n   9    \n   10   pub fn main() !void {\n   11       var n = add_and_increment(2, 3);\n-&gt; 12       n = add_and_increment(n, n);\n   13       try stdout.print(\"Result: {d}!\\n\", .{n});\n   14   }\n(lldb) p n\n(unsigned char) $1 = '\\x06'\nNow, on the next line of code, we are executing the add_and_increment() function once again. Why not step inside this function? Shall we? We can do that, by executing the s LLDB command. Notice in the example below that, after executing this command, we have entered into the context of the add_and_increment() function.\nAlso notice in the example below that, I have walked two more lines in the function’s body, then, I execute the frame variable LLDB command, to see at once, the value stored in each of the variables that were created inside the current scope.\nYou can see in the output below that, the object sum stores the value \\f, which represents the form feed character. This character in the ASCII table, corresponds to the hexadecimal value 0x0C, or, in decimal, the number 12. So, this means that the result of the expression a + b executed at line 5, resulted in the number 12.\n(lldb) s\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step in frame #0: 0x10342de\n    debugging`debug1.add_and_increment(a='\\x02', b='\\x03')\n    at debug1.zig:4:39\n-&gt; 4    fn add_and_increment(a: u8, b: u8) u8 {\n   5        const sum = a + b;\n   6        const incremented = sum + 1;\n   7        return incremented;\n(lldb) n\n(lldb) n\n(lldb) frame variable\n(unsigned char) a = '\\x06'\n(unsigned char) b = '\\x06'\n(unsigned char) sum = '\\f'\n(unsigned char) incremented = '\\x06'",
+    "text": "5.2 Debugging through debuggers\nAlthough print debugging being a valid and very useful strategy, most programmers prefer to use a debugger to debug their programs. Since Zig is a low-level language, you can use either GDB (GNU Debugger), or LLDB (LLVM Project Debugger) as your debugger.\nBoth debuggers can work with Zig code, and it’s a matter of taste here. You choose the debugger of your preference, and you work with it. In this book, I will use LLDB as my debugger on the examples.\n\n5.2.1 Compile your source code in debug mode\nIn order to debug your program through a debugger, you must compile your source code in Debug mode. Because when you compile your source code in other modes (such as Release), the compiler usually strips out some essential information that is used by the debugger to read and track your program, like PDB (Program Database) files.\nBy compiling your source code in Debug mode, you ensure that the debugger will find the necessary information in your program to debug it. By default, the compiler uses the Debug mode when compiling your code. Having this in mind, when you compile your program with the build-exe command (which was described at Section 1.2.4), if you don’t specify an explicit mode through the -O command-line 2 argument, then, the compiler will compile your code in Debug mode.\n\n\n5.2.2 Let’s debug a program\nAs an example, let’s use LLDB to navigate and investigate the following piece of Zig code:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\nfn add_and_increment(a: u8, b: u8) u8 {\n    const sum = a + b;\n    const incremented = sum + 1;\n    return incremented;\n}\n\npub fn main() !void {\n    var n = add_and_increment(2, 3);\n    n = add_and_increment(n, n);\n    try stdout.print(\"Result: {d}!\\n\", .{n});\n}\n\nResult: 13!\n\n\nThere is nothing wrong with this program. But it is a good start for us. First, we need to compile this program with the zig build-exe command. For this example, suppose that I have compiled the above Zig code into a binary executable called add_program.\nzig build-exe add_program.zig\nNow, we can start LLDB with add_program, like this:\nlldb add_program\nFrom now on, LLDB is started, and you can know that I’m executing LLDB commands by looking at the prefix (lldb). If something is prefixed with (lldb), then you know that it is a LLDB command.\nThe first thing I will do, is to set a breakpoint at the main() function, by executing b main. After that, I just start the execution of the program with run. You can see in the output below, that the execution stopped at the first line in the function main(), as we expected.\n(lldb) b main\nBreakpoint 1: where = debugging`debug1.main + 22\n    at debug1.zig:11:30, address = 0x00000000010341a6\n(lldb) run\nProcess 8654 launched: 'add_program' (x86_64)\nProcess 8654 stopped\n* thread #1, name = 'add_program',\n    stop reason = breakpoint 1.1 frame #0: 0x10341a6\n    add_program`debug1.main at add_program.zig:11:30\n   8    }\n   9\n   10   pub fn main() !void {\n-&gt; 11       var n = add_and_increment(2, 3);\n   12       n = add_and_increment(n, n);\n   13       try stdout.print(\"Result: {d}!\\n\", .{n});\n   14   }\nI can start navigating through the code, and checking the objects that are being generated. If you are not familiar with the commands available in LLDB, I recommend you to read the official documentation of the project3. You can also look for cheat sheets, which quickly describes all commands available for you4.\nCurrently, we are in the first line at the main() function. In this line, we create the n object, by executing the add_and_increment() function. To execute the current line of code, and go to the next line, we can run the n LLDB command. Let’s execute this command.\nAfter we executed this line, we can also look at the value stored inside this n object by using the p LLDB command. The syntax for this command is p &lt;name-of-object&gt;.\nIf we take a look at the value stored in the n object (p n), notice that it stores the hexadecimal value 0x06, which is the number 6 in decimal. We can also see that, this value have a type unsigned char, which is an unsigned 8-bit integer. We have talked already about this at Section 1.8, that u8 integers in Zig are equivalent to the C data type unsigned char.\n(lldb) n\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step over frame #0: 0x10341ae\n    debugging`debug1.main at debug1.zig:12:26\n   9\n   10   pub fn main() !void {\n   11       var n = add_and_increment(2, 3);\n-&gt; 12       n = add_and_increment(n, n);\n   13       try stdout.print(\"Result: {d}!\\n\", .{n});\n   14   }\n(lldb) p n\n(unsigned char) $1 = '\\x06'\nNow, on the next line of code, we are executing the add_and_increment() function once again. Why not step inside this function? Shall we? We can do that, by executing the s LLDB command. Notice in the example below that, after executing this command, we have entered into the context of the add_and_increment() function.\nAlso notice in the example below that, I have walked two more lines in the function’s body, then, I execute the frame variable LLDB command, to see at once, the value stored in each of the variables that were created inside the current scope.\nYou can see in the output below that, the object sum stores the value \\f, which represents the form feed character. This character in the ASCII table, corresponds to the hexadecimal value 0x0C, or, in decimal, the number 12. So, this means that the result of the expression a + b executed at line 5, resulted in the number 12.\n(lldb) s\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step in frame #0: 0x10342de\n    debugging`debug1.add_and_increment(a='\\x02', b='\\x03')\n    at debug1.zig:4:39\n-&gt; 4    fn add_and_increment(a: u8, b: u8) u8 {\n   5        const sum = a + b;\n   6        const incremented = sum + 1;\n   7        return incremented;\n(lldb) n\n(lldb) n\n(lldb) frame variable\n(unsigned char) a = '\\x06'\n(unsigned char) b = '\\x06'\n(unsigned char) sum = '\\f'\n(unsigned char) incremented = '\\x06'",
     "crumbs": [
       "<span class='chapter-number'>5</span>  <span class='chapter-title'>Debugging Zig applications</span>"
     ]

From 6c3d4a962830ada93ec573f14364fc2ec227f979 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sun, 9 Feb 2025 11:22:48 -0300
Subject: [PATCH 062/151] Recreate files

---
 .../01-memory/execute-results/html.json       |   15 +
 .../02-debugging/execute-results/html.json    |   15 +
 docs/search.json                              | 1432 +++++++++++++++++
 3 files changed, 1462 insertions(+)
 create mode 100644 _freeze/Chapters/01-memory/execute-results/html.json
 create mode 100644 _freeze/Chapters/02-debugging/execute-results/html.json
 create mode 100644 docs/search.json

diff --git a/_freeze/Chapters/01-memory/execute-results/html.json b/_freeze/Chapters/01-memory/execute-results/html.json
new file mode 100644
index 00000000..eec3bc03
--- /dev/null
+++ b/_freeze/Chapters/01-memory/execute-results/html.json
@@ -0,0 +1,15 @@
+{
+  "hash": "6d9a92b4e90ed5229b91d3e433ba3d4c",
+  "result": {
+    "engine": "knitr",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Memory and Allocators\n\n\nIn this chapter, we will talk about memory. How does Zig control memory? What\ncommon tools are used? Are there any important aspects that make memory\ndifferent/special in Zig? You will find the answers here.\n\nComputers fundamentally rely on memory to function. This memory acts as a temporary storage\nspace for the data and values generated during computations. Without memory, the core\nconcepts of \"variables\" and \"objects\" in programming languages would be impossible.\n\n\n\n\n## Memory spaces\n\nEvery object that you create in your Zig source code needs to be stored somewhere,\nin your computer's memory. Depending on where and how you define your object, Zig\nwill use a different \"memory space\", or a different\ntype of memory to store this object.\n\nEach type of memory normally serves for different purposes.\nIn Zig, there are 3 types of memory (or 3 different memory spaces) that we care about. They are:\n\n- Global data register (or the \"global data section\");\n- Stack;\n- Heap;\n\n\n### Compile-time known versus runtime known {#sec-compile-time}\n\nOne strategy that Zig uses to decide where it will store each object that you declare, is by looking\nat the value of this particular object. More specifically, by investigating if this value is\nknown at \"compile-time\" or at \"runtime\".\n\nWhen you write a program in Zig, the values of some of the objects that you write in your program are *known\nat compile time*. Meaning that, when you compile your Zig source code, during the compilation process,\nthe `zig` compiler can figure out the exact value of a particular object\nthat exists in your source code.\nKnowing the length (or the size) of each object is also important. So the length (or the size) of each object that you write in your program is,\nin some cases, *known at compile time*.\n\nThe `zig` compiler cares more about knowing the length (or the size) of a particular object\n, than to know its actual value. But, if the `zig` compiler knows the value of the object, then, it\nautomatically knows the size of this object. Because it can simply calculate the\nsize of the object by looking at the size of the value.\n\nTherefore, the priority for the `zig` compiler is to discover the size of each object in your source code.\nIf the value of the object in question is known at compile-time, then, the `zig` compiler\nautomatically knows the size/length of this object. But if the value of this object is not\nknown at compile-time, then, the size of this object is only known at compile-time if,\nand only if, the type of this object has a known fixed size.\n\nIn order for a type to have a known fixed size, this type must have data members whose size is fixed.\nIf this type includes, for example, a variable sized array in it, then, this type does not have a known\nfixed size. Because this array can have any size at runtime\n(i.e. it can be an array of 2 elements, or 50 elements, or 1 thousand elements, etc.).\n\nFor example, a string object, which internally is an array of constant u8 values (`[]const u8`)\nhas a variable size. It can be a string object with 100 or 500 characters in it. If we do not\nknow at compile-time, which exact string will be stored inside this string object, then, we cannot calculate\nthe size of this string object at compile-time. So, any type, or any struct declaration that you make, that\nincludes a string data member that does not have an explicit fixed size, makes this type, or this\nnew struct that you are declaring, a type that does not have a known fixed size at compile-time.\n\nIn contrast, if the type of this struct that you are declaring, includes a data member that is an array,\nbut this array has a known fixed size, like `[60]u8` (which declares an array of 60 `u8` values), then,\nthis type, or, this struct that you are declaring, becomes a type with a known fixed size at compile-time.\nAnd because of that, in this case, the `zig` compiler does not need to know at compile-time the exact value of\nany object of this type. Since the compiler can find the necessary size to store this object by\nlooking at the size of its type.\n\n\nLet's look at an example. In the source code below, we have two constant objects (`name` and `array`) declared.\nBecause the values of these particular objects are written down, in the source code itself (`\"Pedro\"`\nand the number sequence from 1 to 4), the `zig` compiler can easily discover the values of these constant\nobjects (`name` and `array`) during the compilation process.\nThis is what \"known at compile time\" means. It refers to any object that you have in your Zig source code\nwhose value can be identified at compile time.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn input_length(input: []const u8) usize {\n    const n = input.len;\n    return n;\n}\n\npub fn main() !void {\n    const name = \"Pedro\";\n    const array = [_]u8{1, 2, 3, 4};\n    _ = name; _ = array;\n}\n```\n:::\n\n\n\n\nThe other side of the spectrum are objects whose values are not known at compile time.\nFunction arguments are a classic example of this. Because the value of each function\nargument depends on the value that you assign to this particular argument,\nwhen you call the function.\n\nFor example, the function `input_length()` contains an argument named `input`, which is an array of constant `u8` integers (`[]const u8`).\nIt is impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length\nof this particular argument. Because it is an array that do not have a fixed size specified explicitly in the argument type annotation.\n\nSo, we know that this `input` argument will be an array of `u8` integers. But we do not know at compile-time, its value, and neither its size.\nThis information is known only at runtime, which is the period of time when you program is executed.\nAs a consequence, the value of the expression `input.len` is also known only at runtime.\nThis is an intrinsic characteristic of any function. Just remember that the value of function arguments is usually not \"compile-time known\".\n\nHowever, as I mentioned earlier, what really matters to the compiler is to know the size of the object\nat compile-time, and not necessarily its value. So, although we don't know the value of the object `n`, which is the result of the expression\n`input.len`, at compile-time, we do know its size. Because the expression `input.len` always returns a value of type `usize`,\nand the type `usize` has a known fixed size.\n\n\n\n### Global data register\n\nThe global data register is a specific section of the executable of your Zig program, that is responsible\nfor storing any value that is known at compile time.\n\nEvery constant object whose value is known at compile time that you declare in your source code,\nis stored in the global data register. Also, every literal value that you write in your source code,\nsuch as the string `\"this is a string\"`, or the integer `10`, or a boolean value such as `true`,\nis also stored in the global data register.\n\nHonestly, you don't need to care much about this memory space. Because you can't control it,\nyou can't deliberately access it or use it for your own purposes.\nAlso, this memory space does not affect the logic of your program.\nIt simply exists in your program.\n\n\n### Stack vs Heap\n\nIf you are familiar with systems programming, or just low-level programming in general, you\nprobably have heard of the \"duel\" between Stack vs Heap. These are two different types of memory,\nor different memory spaces, which are both available in Zig.\n\nThese two types of memory don't actually duel with\neach other. This is a common mistake that beginners have, when seeing \"x vs y\" styles of\ntabloid headlines. These two types of memory are actually complementary to each other.\nSo, in almost every Zig program that you ever write, you will likely use a combination of both.\nI will describe each memory space in detail over the next sections. But for now, I just want to\nstablish the main difference between these two types of memory.\n\nIn essence, the stack memory is normally used to store values whose length is fixed and known\nat compile time. In contrast, the heap memory is a *dynamic* type of memory space, meaning that, it is\nused to store values whose length might grow during the execution (runtime) of your program [@jenny2022].\n\nLengths that grow during runtime are intrinsically associated with \"runtime known\" type of values.\nIn other words, if you have an object whose length might grow during runtime, then, the length\nof this object becomes not known at compile time. If the length is not known at compile-time,\nthe value of this object also becomes not known at compile-time.\nThese types of objects should be stored in the heap memory space, which is\na dynamic memory space, which can grow or shrink to fit the size of your objects.\n\n\n\n### Stack {#sec-stack}\n\nThe stack is a type of memory that uses the power of the *stack data structure*, hence the name.\nA \"stack\" is a type of *data structure* that uses a \"last in, first out\" (LIFO) mechanism to store the values\nyou give it to. I imagine you are familiar with this data structure.\nBut, if you are not, the [Wikipedia page](https://en.wikipedia.org/wiki/Stack_(abstract_data_type))[^wiki-stack]\n, or, the [Geeks For Geeks page](https://www.geeksforgeeks.org/stack-data-structure/)[^geek-stack] are both\nexcellent and easy resources to fully understand how this data structure works.\n\n[^wiki-stack]: <https://en.wikipedia.org/wiki/Stack_(abstract_data_type)>\n[^geek-stack]: <https://www.geeksforgeeks.org/stack-data-structure/>\n\nSo, the stack memory space is a type of memory that stores values using a stack data structure.\nIt adds and removes values from the memory by following a \"last in, first out\" (LIFO) principle.\n\nEvery time you make a function call in Zig, an amount of space in the stack is\nreserved for this particular function call [@jenny2022; @zigdocs].\nThe value of each function argument given to the function in this function call is stored in this\nstack space. Also, every local object that you declare inside the function scope is\nusually stored in this same stack space.\n\n\nLooking at the example below, the object `result` is a local object declared inside the scope of the `add()`\nfunction. Because of that, this object is stored inside the stack space reserved for the `add()` function.\nThe `r` object (which is declared outside of the `add()` function scope) is also stored in the stack.\nBut since it is declared in the \"outer\" scope, this object is stored in the\nstack space that belongs to this outer scope.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn add(x: u8, y: u8) u8 {\n    const result = x + y;\n    return result;\n}\n\npub fn main() !void {\n    const r = add(5, 27);\n    _ = r;\n}\n```\n:::\n\n\n\n\n\nSo, any object that you declare inside the scope of a function is always stored inside\nthe space that was reserved for that particular function in the stack memory. This\nalso counts for any object declared inside the scope of your `main()` function for example.\nAs you would expect, in this case, they\nare stored inside the stack space reserved for the `main()` function.\n\nOne very important detail about the stack memory is that **it frees itself automatically**.\nThis is very important, remember that. When objects are stored in the stack memory,\nyou don't have the work (or the responsibility) of freeing/destroying these objects.\nBecause they will be automatically destroyed once the stack space is freed at the end of the function scope.\n\nSo, once the function call returns (or ends, if you prefer to call it this way)\nthe space that was reserved in the stack is destroyed, and all of the objects that were in that space goes away with it.\nThis mechanism exists because this space, and the objects within it, are not necessary anymore,\nsince the function \"finished its business\".\nUsing the `add()` function that we exposed above as an example, it means that the object `result` is automatically\ndestroyed once the function returns.\n\n::: {.callout-important}\nLocal objects that are stored in the stack space of a function are automatically\nfreed/destroyed at the end of the function scope.\n:::\n\n\nThis same logic applies to any other special structure in Zig that has its own scope by surrounding\nit with curly braces (`{}`).\nFor loops, while loops, if else statements, etc. For example, if you declare any local\nobject in the scope of a for loop, this local object is accessible only within the scope\nof this particular for loop. Because once the scope of this for loop ends, the space in the stack\nreserved for this for loop is freed.\nThe example below demonstrates this idea.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This does not compile successfully!\nconst a = [_]u8{0, 1, 2, 3, 4};\nfor (0..a.len) |i| {\n    const index = i;\n    _ = index;\n}\n// Trying to use an object that was\n// declared in the for loop scope,\n// and that does not exist anymore.\nstd.debug.print(\"{d}\\n\", .{index});\n```\n:::\n\n\n\n\n\n\nOne important consequence of this mechanism is that, once the function returns, you can no longer access any memory\naddress that was inside the space in the stack reserved for this particular function. Because this space was\ndestroyed. This means that, if this local object is stored in the stack,\nyou cannot make a function that **returns a pointer to this object**.\n\nThink about that for a second. If all local objects in the stack are destroyed at the end of the function scope, why\nwould you even consider returning a pointer to one of these objects? This pointer is at best,\ninvalid, or, more likely, \"undefined\".\n\nConclusion, it is totally fine to write a function that returns the local object\nitself as result, because then, you return the value of that object as the result.\nBut, if this local object is stored in the stack, you should never write a function\nthat returns a pointer to this local object. Because the memory address pointed by the pointer\nno longer exists.\n\n\nSo, using again the `add()` function as an example, if you rewrite this function so that it\nreturns a pointer to the local object `result`, the `zig` compiler will actually compile\nyour program, with no warnings or errors. At first glance, it looks that this is good code\nthat works as expected. But this is a lie!\n\nIf you try to take a look at the value inside of the `r` object,\nor, if you try to use this `r` object in another expression\nor function call, then, you would have undefined behaviour, and major\nbugs in your program [@zigdocs, see \"Lifetime and Ownership\"[^life] and \"Undefined Behaviour\"[^undef] sections].\n\n[^life]: <https://ziglang.org/documentation/master/#Lifetime-and-Ownership>\n[^undef]: <https://ziglang.org/documentation/master/#Undefined-Behavior>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn add(x: u8, y: u8) *const u8 {\n    const result = x + y;\n    return &result;\n}\n\npub fn main() !void {\n    // This code compiles successfully. But it has\n    // undefined behaviour. Never do this!!!\n    // The `r` object is undefined!\n    const r = add(5, 27); _ = r;\n}\n```\n:::\n\n\n\n\nThis \"invalid pointer to stack variable\" problem is well known across many programming language communities.\nIf you try to do the same thing, for example, in a C or C++ program (i.e. returning an address to\na local object stored in the stack), you would also get undefined behaviour\nin the program.\n\n::: {.callout-important}\nIf a local object in your function is stored in the stack, you should never\nreturn a pointer to this local object from the function. Because\nthis pointer will always become undefined after the function returns, since the stack space of the function\nis destroyed at the end of its scope.\n:::\n\nBut what if you really need to use this local object in some way after your function returns?\nHow can you do this? The answer is: \"in the same way you would do if this were a C or C++ program. By returning\nan address to an object stored in the heap\". The heap memory has a much more flexible lifecycle,\nand allows you to get a valid pointer to a local object of a function that already returned\nfrom its scope.\n\n\n### Heap {#sec-heap}\n\nOne important limitation of the stack, is that, only objects whose length/size is known at compile-time can be\nstored in it. In contrast, the heap is a much more dynamic\n(and flexible) type of memory. It is the perfect type of memory to use\nfor objects whose size/length might grow during the execution of your program.\n\nVirtually any application that behaves as a server is a classic use case of the heap.\nA HTTP server, a SSH server, a DNS server, a LSP server, ... any type of server.\nIn summary, a server is a type of application that runs for long periods of time,\nand that serves (or \"deals with\") any incoming request that reaches this particular server.\n\nThe heap is a good choice for this type of system, mainly because the server does not know upfront\nhow many requests it will receive from users, while it is active. It could be a single request,\n5 thousand requests, or even zero requests.\nThe server needs to have the ability to allocate and manage its memory according to how many requests it receives.\n\nAnother key difference between the stack and the heap, is that the heap is a type\nof memory that you, the programmer, have complete control over. This makes the heap a\nmore flexible type of memory, but it also makes it harder to work with. Because you,\nthe programmer, is responsible for managing everything related to it. Including where the memory is allocated,\nhow much memory is allocated, and where this memory is freed.\n\n> Unlike stack memory, heap memory is allocated explicitly by programmers and it won’t be deallocated until it is explicitly freed [@jenny2022].\n\nTo store an object in the heap, you, the programmer, needs to explicitly tells Zig to do so,\nby using an allocator to allocate some space in the heap. At @sec-allocators, I will present how you can use allocators to allocate memory\nin Zig.\n\n::: {.callout-important}\nEvery memory you allocate in the heap needs to be explicitly freed by you, the programmer.\n:::\n\nThe majority of allocators in Zig do allocate memory on the heap. But some exceptions to this rule are\n`ArenaAllocator()` and `FixedBufferAllocator()`. The `ArenaAllocator()` is a special\ntype of allocator that works in conjunction with a second type of allocator.\nOn the other side, the `FixedBufferAllocator()` is an allocator that works based on\nbuffer objects created on the stack. This means that the `FixedBufferAllocator()` makes\nallocations only on the stack.\n\n\n\n\n### Summary\n\nAfter discussing all of these boring details, we can quickly recap what we learned.\nIn summary, the Zig compiler will use the following rules to decide where each\nobject you declare is stored:\n\n1. every literal value (such as `\"this is string\"`, `10`, or `true`) is stored in the global data section.\n1. every constant object (`const`) whose value **is known at compile-time** is also stored in the global data section.\n1. every object (constant or not) whose length/size **is known at compile time** is stored in the stack space for the current scope.\n1. if an object is created with the method `alloc()` or `create()` of an allocator object, this object is stored in the memory space used by this particular allocator object. Most of allocators available in Zig use the heap memory, so, this object is likely stored in the heap (`FixedBufferAllocator()` is an exception to that).\n1. the heap can only be accessed through allocators. If your object was not created through the `alloc()` or `create()` methods of an allocator object, then, it is most certainly not an object stored in the heap.\n\n\n## Stack overflows {#sec-stack-overflow}\n\nAllocating memory on the stack is generally faster than allocating it on the heap.\nBut this better performance comes with many restrictions. We have already discussed\nmany of these restrictions of the stack at @sec-stack. But there is one more important\nlimitation that I want to talk about, which is the size of the stack itself.\n\nThe stack is limited in size. This size varies from computer to computer, and it depends on\na lot of things (the computer architecture, the operating system, etc.). Nevertheless, this size is usually\nnot that big. This is why we normally use the stack to store only temporary and small objects in memory.\n\nIn essence, if you try to make an allocation on the stack, that is so big that exceeds the stack size limit,\na *stack overflow* happens, and your program just crashes as a result of that. In other words, a stack overflow happens when\nyou attempt to use more space than is available on the stack.\n\nThis type of problem is very similar to a *buffer overflow*, i.e. you are trying to use more space\nthan is available in the \"buffer object\". However, a stack overflow always causes your program to crash,\nwhile a buffer overflow does not always cause your program to crash (although it often does).\n\nYou can see an example of a stack overflow in the example below. We are trying to allocate a very big array of `u64` values\non the stack. You can see below that this program does not run successfully, because it crashed\nwith a \"segmentation fault\" error message.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar very_big_alloc: [1000 * 1000 * 24]u64 = undefined;\n@memset(very_big_alloc[0..], 0);\n```\n:::\n\n\n\n\n```\nSegmentation fault (core dumped)\n```\n\nThis segmentation fault error is a result of the stack overflow that was caused by the big\nmemory allocation made on the stack, to store the `very_big_alloc` object.\nThis is why very big objects are usually stored on the heap, instead of the stack.\n\n\n\n## Allocators {#sec-allocators}\n\nOne key aspect about Zig, is that there are \"no hidden-memory allocations\" in Zig.\nWhat that really means, is that \"no allocations happen behind your back in the standard library\" [@zigguide].\n\nThis is a known problem, especially in C++. Because in C++, there are some operators that do allocate\nmemory behind the scene, and there is no way for you to know that, until you actually read the\nsource code of these operators, and find the memory allocation calls.\nMany programmers find this behaviour annoying and hard to keep track of.\n\nBut, in Zig, if a function, an operator, or anything from the standard library\nneeds to allocate some memory during its execution, then, this function/operator needs to receive (as input) an allocator\nprovided by the user, to actually be able to allocate the memory it needs.\n\nThis creates a clear distinction between functions that \"do not\" from those that \"actually do\"\nallocate memory. Just look at the arguments of this function.\nIf a function, or operator, has an allocator object as one of its inputs/arguments, then, you know for\nsure that this function/operator will allocate some memory during its execution.\n\nAn example is the `allocPrint()` function from the Zig Standard Library. With this function, you can\nwrite a new string using format specifiers. So, this function is, for example, very similar to the function `sprintf()` in C.\nIn order to write such a new string, the `allocPrint()` function needs to allocate some memory to store the\noutput string.\n\nThat is why, the first argument of this function is an allocator object that you, the user/programmer, gives\nas input to the function. In the example below, I am using the `GeneralPurposeAllocator()` as my allocator\nobject. But I could easily use any other type of allocator object from the Zig Standard Library.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst name = \"Pedro\";\nconst output = try std.fmt.allocPrint(\n    allocator,\n    \"Hello {s}!!!\",\n    .{name}\n);\ntry stdout.print(\"{s}\\n\", .{output});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello Pedro!!!\n```\n\n\n:::\n:::\n\n\n\n\n\nYou get a lot of control over where and how much memory this function can allocate.\nBecause it is you, the user/programmer, that provides the allocator for the function to use.\nThis makes \"total control\" over memory management easier to achieve in Zig.\n\n### What are allocators?\n\nAllocators in Zig are objects that you can use to allocate memory for your program.\nThey are similar to the memory allocating functions in C, like `malloc()` and `calloc()`.\nSo, if you need to use more memory than you initially have, during the execution of your program, you can simply ask\nfor more memory by using an allocator object.\n\nZig offers different types of allocators, and they are usually available through the `std.heap` module of\nthe standard library. Thus, just import the Zig Standard Library into your Zig module (with `@import(\"std\")`), and you can start\nusing these allocators in your code.\n\nFurthermore, every allocator object is built on top of the `Allocator` interface in Zig.\nThis means that, every allocator object you find in Zig must have the methods `alloc()`,\n`create()`, `free()` and `destroy()`. So, you can change the type of allocator you are using,\nbut you don't need to change the function calls to the methods that do the memory allocation\n(and the free memory operations) for your program.\n\n### Why you need an allocator?\n\nAs we described at @sec-stack, everytime you make a function call in Zig,\na space in the stack is reserved for this function call. But the stack\nhas a key limitation which is: every object stored in the stack has a\nknown fixed length.\n\nBut in reality, there are two very common instances where this \"fixed length limitation\" of the stack is a deal braker:\n\n1. the objects that you create inside your function might grow in size during the execution of the function.\n1. sometimes, it is impossible to know upfront how many inputs you will receive, or how big this input will be.\n\nAlso, there is another instance where you might want to use an allocator, which is when you want to write a function that returns a pointer\nto a local object. As I described at @sec-stack, you cannot do that if this local object is stored in the\nstack. However, if this object is stored in the heap, then, you can return a pointer to this object at the\nend of the function. Because you (the programmer) control the lifetime of any heap memory that you allocate. You decide\nwhen this memory gets destroyed/freed.\n\nThese are common situations for which the stack is not good. \nThat is why you need a different memory management strategy to\nstore these objects inside your function. You need to use\na memory type that can grow together with your objects, or that you\ncan control the lifetime of this memory.\nThe heap fits this description.\n\nAllocating memory on the heap is commonly known as dynamic memory management. As the objects you create grow in size\nduring the execution of your program, you grow the amount of memory\nyou have by allocating more memory in the heap to store these objects.\nAnd you do that in Zig, by using an allocator object.\n\n\n### The different types of allocators\n\n\nAt the moment of the writing of this book, in Zig, we have 6 different\nallocators available in the standard library:\n\n- `GeneralPurposeAllocator()`.\n- `page_allocator()`.\n- `FixedBufferAllocator()` and `ThreadSafeFixedBufferAllocator()`.\n- `ArenaAllocator()`.\n- `c_allocator()` (requires you to link to libc).\n\n\nEach allocator has its own perks and limitations. All allocators, except `FixedBufferAllocator()` and `ArenaAllocator()`,\nare allocators that use the heap memory. So any memory that you allocate with\nthese allocators, will be placed in the heap.\n\n### General-purpose allocators\n\nThe `GeneralPurposeAllocator()`, as the name suggests, is a \"general purpose\" allocator. You can use it for every type\nof task. In the example below, I'm allocating enough space to store a single integer in the object `some_number`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const some_number = try allocator.create(u32);\n    defer allocator.destroy(some_number);\n\n    some_number.* = @as(u32, 45);\n}\n```\n:::\n\n\n\n\n\nWhile useful, you might want to use the `c_allocator()`, which is a alias to the C standard allocator `malloc()`. So, yes, you can use\n`malloc()` in Zig if you want to. Just use the `c_allocator()` from the Zig standard library. However,\nif you do use `c_allocator()`, you must link to Libc when compiling your source code with the\n`zig` compiler, by including the flag `-lc` in your compilation process.\nIf you do not link your source code to Libc, Zig will not be able to find the\n`malloc()` implementation in your system.\n\n### Page allocator\n\nThe `page_allocator()` is an allocator that allocates full pages of memory in the heap. In other words,\nevery time you allocate memory with `page_allocator()`, a full page of memory in the heap is allocated,\ninstead of just a small piece of it.\n\nThe size of this page depends on the system you are using.\nMost systems use a page size of 4KB in the heap, so, that is the amount of memory that is normally\nallocated in each call by `page_allocator()`. That is why, `page_allocator()` is considered a\nfast, but also \"wasteful\" allocator in Zig. Because it allocates a big amount of memory\nin each call, and you most likely will not need that much memory in your program.\n\n### Buffer allocators\n\nThe `FixedBufferAllocator()` and `ThreadSafeFixedBufferAllocator()` are allocator objects that\nwork with a fixed sized buffer object at the back. In other words, they use a fixed sized buffer\nobject as the basis for the memory. When you ask these allocator objects to allocate some memory for you,\nthey are essentially reserving some amount of space inside this fixed sized buffer object for you to use.\n\nThis means that, in order to use these allocators, you must first create a buffer object in your code,\nand then, give this buffer object as an input to these allocators.\n\nThis also means that, these allocator objects can allocate memory both in the stack or in the heap.\nEverything depends on where the buffer object that you provide lives. If this buffer object lives\nin the stack, then, the memory allocated is \"stack-based\". But if it lives on the heap, then,\nthe memory allocated is \"heap-based\".\n\n\nIn the example below, I'm creating a `buffer` object on the stack that is 10 elements long.\nNotice that I give this `buffer` object to the `FixedBufferAllocator()` constructor.\nNow, because this `buffer` object is 10 elements long, this means that I am limited to this space.\nI cannot allocate more than 10 elements with this allocator object. If I try to\nallocate more than that, the `alloc()` method will return an `OutOfMemory` error value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar buffer: [10]u8 = undefined;\nfor (0..buffer.len) |i| {\n    buffer[i] = 0; // Initialize to zero\n}\n\nvar fba = std.heap.FixedBufferAllocator.init(&buffer);\nconst allocator = fba.allocator();\nconst input = try allocator.alloc(u8, 5);\ndefer allocator.free(input);\n```\n:::\n\n\n\n\nRemember, the memory allocated by these allocator objects can be either from\nthe stack, or, from the heap. It all depends on where the buffer object that you provide lives.\nIn the above example, the `buffer` object lives in the stack, and, therefore, the memory allocated\nis based in the stack. But what if it was based on the heap?\n\nAs we described at @sec-stack-overflow, one of the main reasons why you would use the heap,\ninstead of the stack, is to allocate huge amounts of space to store very big objects.\nThus, let's suppose you wanted to use a very big buffer object as the basis for your\nallocator objects. You would have to allocate this very big buffer object on the heap.\nThe example below demonstrates this case.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst heap = std.heap.page_allocator;\nconst memory_buffer = try heap.alloc(\n    u8, 100 * 1024 * 1024 // 100 MB memory\n);\ndefer heap.free(memory_buffer);\nvar fba = std.heap.FixedBufferAllocator.init(\n    memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst input = try allocator.alloc(u8, 1000);\ndefer allocator.free(input);\n```\n:::\n\n\n\n\n\n\n### Arena allocator {#sec-arena-allocator}\n\nThe `ArenaAllocator()` is an allocator object that takes a child allocator as input. The idea behind the `ArenaAllocator()` in Zig\nis similar to the concept of \"arenas\" in the programming language Go[^go-arena]. It is an allocator object that allows you\nto allocate memory as many times you want, but free all memory only once.\nIn other words, if you have, for example, called 5 times the method `alloc()` of an `ArenaAllocator()` object, you can\nfree all the memory you allocated over these 5 calls at once, by simply calling the `deinit()` method of the same `ArenaAllocator()` object.\n\n[^go-arena]: <https://go.dev/src/arena/arena.go>\n\nIf you give, for example, a `GeneralPurposeAllocator()` object as input to the `ArenaAllocator()` constructor, like in the example below, then, the allocations\nyou perform with `alloc()` will actually be made with the underlying object `GeneralPurposeAllocator()` that was passed.\nSo, with an arena allocator, any new memory you ask for is allocated by the child allocator. The only thing that an arena allocator\nreally does is help you to free all the memory you allocated multiple times with just a single command. In the example\nbelow, I called `alloc()` 3 times. So, if I did not use an arena allocator, then, I would need to call\n`free()` 3 times to free all the allocated memory.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nvar aa = std.heap.ArenaAllocator.init(gpa.allocator());\ndefer aa.deinit();\nconst allocator = aa.allocator();\n\nconst in1 = try allocator.alloc(u8, 5);\nconst in2 = try allocator.alloc(u8, 10);\nconst in3 = try allocator.alloc(u8, 15);\n_ = in1; _ = in2; _ = in3;\n```\n:::\n\n\n\n\n\n\n### The `alloc()` and `free()` methods\n\nIn the code example below, we are accessing the `stdin`, which is\nthe standard input channel, to receive an input from the\nuser. We read the input given by the user with the `readUntilDelimiterOrEof()`\nmethod.\n\nNow, after reading the input of the user, we need to store this input somewhere in\nour program. That is why I use an allocator in this example. I use it to allocate some\namount of memory to store this input given by the user. More specifically, the method `alloc()`\nof the allocator object is used to allocate an array capable of storing 50 `u8` values.\n\nNotice that this `alloc()` method receives two inputs. The first one, is a type.\nThis defines what type of values the allocated array will store. In the example\nbelow, we are allocating an array of unsigned 8-bit integers (`u8`). But\nyou can create an array to store any type of value you want. Next, on the second argument, we\ndefine the size of the allocated array, by specifying how many elements\nthis array will contain. In the case below, we are allocating an array of 50 elements.\n\nAt @sec-zig-strings we described that strings in Zig are simply arrays of characters.\nEach character is represented by a `u8` value. So, this means that the array that\nwas allocated in the object `input` is capable of storing a string that is\n50-characters long.\n\nSo, in essence, the expression `var input: [50]u8 = undefined` would create\nan array for 50 `u8` values in the stack of the current scope. But, you\ncan allocate the same array in the heap by using the expression `var input = try allocator.alloc(u8, 50)`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdin = std.io.getStdIn();\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var input = try allocator.alloc(u8, 50);\n    defer allocator.free(input);\n    for (0..input.len) |i| {\n        input[i] = 0; // initialize all fields to zero.\n    }\n    // read user input\n    const input_reader = stdin.reader();\n    _ = try input_reader.readUntilDelimiterOrEof(\n        input,\n        '\\n'\n    );\n    std.debug.print(\"{s}\\n\", .{input});\n}\n```\n:::\n\n\n\n\nAlso, notice that in this example, we use the `defer` keyword (which I described at @sec-defer) to run a small\npiece of code at the end of the current scope, which is the expression `allocator.free(input)`.\nWhen you execute this expression, the allocator will free the memory that it allocated\nfor the `input` object.\n\nWe have talked about this at @sec-heap. You **should always** explicitly free any memory that you allocate\nusing an allocator! You do that by using the `free()` method of the same allocator object you\nused to allocate this memory. The `defer` keyword is used in this example only to help us execute\nthis free operation at the end of the current scope.\n\n\n### The `create()` and `destroy()` methods\n\nWith the `alloc()` and `free()` methods, you can allocate memory to store multiple elements\nat once. In other words, with these methods, we always allocate an array to store multiple elements at once.\nBut what if you need enough space to store just a single item? Should you\nallocate an array of a single element through `alloc()`?\n\nThe answer is no! In this case,\nyou should use the `create()` method of the allocator object.\nEvery allocator object offers the `create()` and `destroy()` methods,\nwhich are used to allocate and free memory for a single item, respectively.\n\nSo, in essence, if you want to allocate memory to store an array of elements, you\nshould use `alloc()` and `free()`. But if you need to store just a single item,\nthen, the `create()` and `destroy()` methods are ideal for you.\n\nIn the example below, I'm defining a struct to represent an user of some sort.\nIt could be a user for a game, or software to manage resources, it doesn't mater.\nNotice that I use the `create()` method this time, to store a single `User` object\nin the program. Also notice that I use the `destroy()` method to free the memory\nused by this object at the end of the scope.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst User = struct {\n    id: usize,\n    name: []const u8,\n\n    pub fn init(id: usize, name: []const u8) User {\n        return .{ .id = id, .name = name };\n    }\n};\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const user = try allocator.create(User);\n    defer allocator.destroy(user);\n\n    user.* = User.init(0, \"Pedro\");\n}\n```\n:::\n",
+    "supporting": [],
+    "filters": [
+      "rmarkdown/pagebreak.lua"
+    ],
+    "includes": {},
+    "engineDependencies": {},
+    "preserve": {},
+    "postProcess": true
+  }
+}
\ No newline at end of file
diff --git a/_freeze/Chapters/02-debugging/execute-results/html.json b/_freeze/Chapters/02-debugging/execute-results/html.json
new file mode 100644
index 00000000..5b18dbcb
--- /dev/null
+++ b/_freeze/Chapters/02-debugging/execute-results/html.json
@@ -0,0 +1,15 @@
+{
+  "hash": "81acc8dfbc423fbdea18f9b7f8f1ea18",
+  "result": {
+    "engine": "knitr",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Debugging Zig applications\n\nBeing able to debug your applications is essential for any programmer who wants to\ndo serious programming in any language. That is why, in this chapter, we are going to talk about the\navailable strategies and tools to debug applications written in Zig.\n\n\n## Print debugging\n\nWe begin with the classic and battle-tested *print debugging* strategy.\nThe key advantage that debugging offers you is *visibility*.\nWith *print statements* you can easily see what results and objects\nare being produced by your application.\n\nThat is the essence of *print debugging*. Is to use\nprint expressions to see the values that are being generated by your program,\nand, as a result, get a much better understanding of how your program\nis behaving.\n\nMany programmers often resort to the print functions in Zig, such as the `stdout.print()`,\nor, the `std.debug.print()`, to get a better understanding of their programs.\nThis is a known and old strategy that is very simple and effective, and it is better known within\nthe programming community as *print debugging*.\nIn Zig, you can print information to the `stdout` or `stderr` streams of your system.\n\nLet's begin with `stdout`. First, you\nneed to get access to the `stdout`, by calling the `getStdOut()` method, from\nthe Zig Standard Library. This method returns a *file descriptor* object,\nand, through this object you can read/write to the `stdout`.\nI recommend you to check out all methods available in this object, by [checking the page in\nthe Zig Standard Library Official Reference for the type `File`](https://ziglang.org/documentation/master/std/#std.fs.File)[^zig-fiile-reference].\n\n[^zig-fiile-reference]: <https://ziglang.org/documentation/master/std/#std.fs.File>.\n\nFor our purpose here, which is to write something to the `stdout`, especially to debug our\nprogram, I recommend you to use the `writer()` method, which gives you a *writer* object.\nThis *writer* object offers some helper methods to write stuff into the file descriptor object\nthat represents the `stdout` stream. In special, the `print()` method.\n\n\nThe `print()` method from this *writer* object is a \"print formatter\" type of a function.\nIn other words, this method works exactly like the `printf()` function from C,\nor, like `println!()` from Rust.\nIn the first argument of the function, you specify a template string, and,\nin the second argument, you provide a list of values (or objects) that you want to insert\ninto your template message.\n\nIdeally, the template string in the first argument should contain some format specifier.\nEach format specifier is matched to a value (or object) that you have listed in the second argument.\nSo, if you provided 5 different objects in the second argument, then, the template string\nshould contain 5 format specifiers, one for each object provided.\n\nEach format specifier is represented by a single letter, and\nyou provide this format specifier inside a pair of curly braces. So, if you want to format\nyour object using the string specifier (`s`), then, you can insert the text `{s}` in your template string.\nHere is a quick list of the most used format specifiers:\n\n- `d`: for printing integers and floating-point numbers.\n- `c`: for printing characters.\n- `s`: for printing strings.\n- `p`: for printing memory addresses.\n- `x`: for printing hexadecimal values.\n- `any`: use any compatible format specifier (i.e. it automatically selects a format specifier for you).\n\nThe code example below gives you an example of use of this `print()` method\nwith the `d` format specifier.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    try stdout.print(\"Result: {d}\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\n\n\nIt is important to emphasize that, the `stdout.print()` method, as you would expect,\nprints your template string into the `stdout` stream of your system.\nHowever, you can also print your template string into the `stderr` stream\nif your prefer. All you need to do, is to replace the `stdout.print()`\ncall with the function `std.debug.print()`. Like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    std.debug.print(\"Result: {d}\\n\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\n\n\n\nYou could also achieve the exact same result by getting a file descriptor object to `stderr`,\nthen, creating a *writer* object to `stderr`, then, using the `print()` method of this\n*writer* object, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stderr = std.io.getStdErr().writer();\n// some more lines ...\ntry stderr.print(\"Result: {d}\", .{result});\n```\n:::\n\n\n\n\n\n\n## Debugging through debuggers\n\nAlthough *print debugging* is a valid and very useful strategy,\nmost programmers prefer to use a debugger to debug their programs.\nSince Zig is a low-level language, you can use either GDB (GNU Debugger),\nor LLDB (LLVM Project Debugger) as your debugger.\n\nBoth debuggers can work with Zig code, and it's a matter of taste here.\nYou choose the debugger of your preference, and you work with it.\nIn this book, I will use LLDB as my debugger on the examples.\n\n\n### Compile your source code in debug mode {#sec-compile-debug-mode}\n\nIn order to debug your program through a debugger, you must compile\nyour source code in `Debug` mode. Because when you compile your\nsource code in other modes (such as `Release`), the compiler usually\nstrips out some essential information that is used by the debugger\nto read and track your program, like PDB (*Program Database*) files.\n\nBy compiling your source code in `Debug` mode, you ensure that the debugger\nwill find the necessary information in your program to debug it.\nBy default, the compiler uses the `Debug` mode when compiling your code.\nHaving this in mind, when you compile your program with the `build-exe`\ncommand (which was described at @sec-compile-code), if you don't specify\nan explicit mode through the `-O` command-line [^oargument]\nargument, then, the compiler will compile your code in `Debug` mode.\n\n[^oargument]: See <https://ziglang.org/documentation/master/#Debug>.\n\n\n### Let's debug a program\n\nAs an example, let's use LLDB to navigate and investigate the following\npiece of Zig code:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\nfn add_and_increment(a: u8, b: u8) u8 {\n    const sum = a + b;\n    const incremented = sum + 1;\n    return incremented;\n}\n\npub fn main() !void {\n    var n = add_and_increment(2, 3);\n    n = add_and_increment(n, n);\n    try stdout.print(\"Result: {d}!\\n\", .{n});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 13!\n```\n\n\n:::\n:::\n\n\n\n\nThere is nothing wrong with this program. But it is\na good start for us. First, we need to compile\nthis program with the `zig build-exe` command.\nFor this example, suppose that I have compiled the above\nZig code into a binary executable called `add_program`.\n\n```bash\nzig build-exe add_program.zig\n```\n\nNow, we can start LLDB with `add_program`, like this:\n\n```bash\nlldb add_program\n```\n\nFrom now on, LLDB is started, and you can know that I'm\nexecuting LLDB commands by looking at the prefix `(lldb)`.\nIf something is prefixed with `(lldb)`, then you know\nthat it is a LLDB command.\n\nThe first thing I will do, is to set a breakpoint at\nthe `main()` function, by executing `b main`.\nAfter that, I just start the execution of the program\nwith `run`.\nYou can see in the output below, that the execution\nstopped at the first line in the function `main()`, as we expected.\n\n```bash\n(lldb) b main\nBreakpoint 1: where = debugging`debug1.main + 22\n    at debug1.zig:11:30, address = 0x00000000010341a6\n(lldb) run\nProcess 8654 launched: 'add_program' (x86_64)\nProcess 8654 stopped\n* thread #1, name = 'add_program',\n    stop reason = breakpoint 1.1 frame #0: 0x10341a6\n    add_program`debug1.main at add_program.zig:11:30\n   8   \t}\n   9\n   10  \tpub fn main() !void {\n-> 11  \t    var n = add_and_increment(2, 3);\n   12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n```\n\nI can start navigating through the code, and checking the objects\nthat are being generated. If you are not familiar with the commands\navailable in LLDB, I recommend you to read the official documentation\nof the project[^lldb].\nYou can also look for cheat sheets, which quickly describes all commands\navailable for you[^lldb-quick-list].\n\n[^lldb]: <https://lldb.llvm.org/>\n[^lldb-quick-list]: <https://gist.github.com/ryanchang/a2f738f0c3cc6fbd71fa>.\n\nCurrently, we are in the first line at the `main()` function. In this line, we create\nthe `n` object, by executing the `add_and_increment()` function.\nTo execute the current line of code, and go to the next line, we can\nrun the `n` LLDB command. Let's execute this command.\n\nAfter we executed this line, we can also look at the value stored inside this `n` object\nby using the `p` LLDB command. The syntax for this command is `p <name-of-object>`.\n\nIf we take a look at the value stored in the `n` object (`p n`),\nnotice that it stores the hexadecimal value `0x06`, which\nis the number 6 in decimal. We can also see that this value has a type of `unsigned char`,\nwhich is an unsigned 8-bit integer.\nWe have talked already about this at @sec-zig-strings, that `u8` integers in Zig are equivalent\nto the C data type `unsigned char`.\n\n\n\n```bash\n(lldb) n\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step over frame #0: 0x10341ae\n    debugging`debug1.main at debug1.zig:12:26\n   9\n   10  \tpub fn main() !void {\n   11  \t    var n = add_and_increment(2, 3);\n-> 12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n(lldb) p n\n(unsigned char) $1 = '\\x06'\n```\n\nNow, on the next line of code, we are executing the `add_and_increment()` function once again.\nWhy not step inside this function? Shall we? We can do that, by executing the `s` LLDB command.\nNotice in the example below that, after executing this command, we have entered into the context of the\n`add_and_increment()` function.\n\nAlso notice in the example below that, I have walked two more lines in the function's body, then,\nI execute the `frame variable` LLDB command, to see at once, the value stored in each of the variables\nthat were created inside the current scope.\n\nYou can see in the output below that, the object `sum` stores the value `\\f`,\nwhich represents the *form feed* character. This character in the ASCII table,\ncorresponds to the hexadecimal value `0x0C`, or, in decimal, the number 12.\nSo, this means that the result of the expression `a + b` executed at line\n5, resulted in the number 12.\n\n```bash\n(lldb) s\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step in frame #0: 0x10342de\n    debugging`debug1.add_and_increment(a='\\x02', b='\\x03')\n    at debug1.zig:4:39\n-> 4   \tfn add_and_increment(a: u8, b: u8) u8 {\n   5   \t    const sum = a + b;\n   6   \t    const incremented = sum + 1;\n   7   \t    return incremented;\n(lldb) n\n(lldb) n\n(lldb) frame variable\n(unsigned char) a = '\\x06'\n(unsigned char) b = '\\x06'\n(unsigned char) sum = '\\f'\n(unsigned char) incremented = '\\x06'\n```\n\n\n\n## How to investigate the data type of your objects\n\nSince Zig is a strongly-typed language, the data types associated with your objects\nare very important for your program. So, debugging the data types associated\nwith your objects might be important to understand bugs and errors in your program.\n\nWhen you walk through your program with a debugger, you can inspect the types of\nyour objects by simply printing them to the console, with the LLDB `p` command.\nBut you also have alternatives embedded in the language itself to access the data\ntypes of your objects.\n\nIn Zig, you can retrieve the data type of an object, by using the built-in function\n`@TypeOf()`. Just apply this function over the object, and you get access to\nthe data type of the object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst expect = std.testing.expect;\n\npub fn main() !void {\n    const number: i32 = 5;\n    try expect(@TypeOf(number) == i32);\n    try stdout.print(\"{any}\\n\", .{@TypeOf(number)});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ni32\n```\n\n\n:::\n:::\n\n\n\n\nThis function is similar to the `type()` built-in function from Python,\nor, the `typeof` operator in Javascript.\n\n",
+    "supporting": [],
+    "filters": [
+      "rmarkdown/pagebreak.lua"
+    ],
+    "includes": {},
+    "engineDependencies": {},
+    "preserve": {},
+    "postProcess": true
+  }
+}
\ No newline at end of file
diff --git a/docs/search.json b/docs/search.json
new file mode 100644
index 00000000..3c57d704
--- /dev/null
+++ b/docs/search.json
@@ -0,0 +1,1432 @@
+[
+  {
+    "objectID": "index.html",
+    "href": "index.html",
+    "title": "Introduction to Zig",
+    "section": "",
+    "text": "Welcome\nWelcome! This is the initial page for the “Open Access” HTML version of the book “Introduction to Zig: a project-based book”, written by Pedro Duarte Faria. This is an open book that provides an introduction to the Zig programming language, which is a new general-purpose, and low-level language for building robust and optimal software.",
+    "crumbs": [
+      "Welcome"
+    ]
+  },
+  {
+    "objectID": "index.html#support-the-project",
+    "href": "index.html#support-the-project",
+    "title": "Introduction to Zig",
+    "section": "Support the project!",
+    "text": "Support the project!\nIf you like this project, and you want to support it, you can buy an eBook or a physical copy of the book on Amazon:\n\n  Buy the book on Amazon!  \n\nSending donations directly\nYou can also donate some amount directly to the author of the project via:\n\nPayPal Donation.\nRevolut.\n\nThese are good ways to support directly the author of the project, which helps to foster more contents like this, and it makes possible for the author to keep writing helpful tools and materials for the community.\n\n\nPayPal\n\n  Donate via PayPal 💵  \n\n\nRevolut\nYou can send money via Swift Payment with the following bank and Swift details:\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\nIf you do have a Revolut account, you can scan the following QR code:\n\n  Revolut QR Code 💵",
+    "crumbs": [
+      "Welcome"
+    ]
+  },
+  {
+    "objectID": "index.html#about-this-book",
+    "href": "index.html#about-this-book",
+    "title": "Introduction to Zig",
+    "section": "About this book",
+    "text": "About this book\nThis an open (i.e. it is open-source), technical and introductory book for the Zig programming language, which is a new general purpose, and low-level programming language for building optimal and robust software.\nOfficial repository of the book: https://github.com/pedropark99/zig-book.\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small and simple projects (in a similar style to the famous “Python Crash Course” book from Eric Matthes). Some of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\nAs you work through the book, you will learn:\n\nThe syntax of the language, and how it compares to C, C++ and Rust.\nData structures, memory allocators, filesystem and I/O.\nOptionals as a new paradigm to handle nullability.\nHow to test and debug a Zig application.\nErrors as values, and how to handle them.\nHow to build C and Zig code with the build system that is embedded into the language.\nZig interoperability with C.\nParallelism with threads and SIMD.\nAnd more.",
+    "crumbs": [
+      "Welcome"
+    ]
+  },
+  {
+    "objectID": "index.html#about-the-author",
+    "href": "index.html#about-the-author",
+    "title": "Introduction to Zig",
+    "section": "About the author",
+    "text": "About the author\nPedro Duarte Faria has a bachelor’s degree in Economics from the Federal University of Ouro Preto - Brazil. Currently, he is a Data Platform Engineer at Blip1, and a Databricks Certified Associate Developer for Apache Spark 3.0.\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines, reports and analysis for research institutions and some of the largest companies in the Brazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\nBut Pedro is also a passionate software developer who loves to learn and teach about programming. Although Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several lectures and courses about it, inside graduate centers (such as PPEA-UFOP2), in addition to federal and state organizations (such as FJP-MG3).\nPersonal Website: https://pedro-faria.netlify.app/\nLinkedin: https://www.linkedin.com/in/pedro-faria-a68140209/\nMastodon: @pedropark99@fosstodon.org\nTwitter (X): @PedroPark9",
+    "crumbs": [
+      "Welcome"
+    ]
+  },
+  {
+    "objectID": "index.html#license",
+    "href": "index.html#license",
+    "title": "Introduction to Zig",
+    "section": "License",
+    "text": "License\nCopyright © 2024 Pedro Duarte Faria. This book is licensed by the CC-BY 4.0 Creative Commons Attribution 4.0 International Public License4.",
+    "crumbs": [
+      "Welcome"
+    ]
+  },
+  {
+    "objectID": "index.html#book-compilation-metadata",
+    "href": "index.html#book-compilation-metadata",
+    "title": "Introduction to Zig",
+    "section": "Book compilation metadata",
+    "text": "Book compilation metadata\nThis book was compiled using the following versions of Zig and Quarto:\n\nSystem version: Linux, 6.8.0-52-generic, NA, x86_64.\nZig version: 0.14.0-dev.3046+08d661fcf.\nQuarto version: 1.5.57.",
+    "crumbs": [
+      "Welcome"
+    ]
+  },
+  {
+    "objectID": "index.html#book-citation",
+    "href": "index.html#book-citation",
+    "title": "Introduction to Zig",
+    "section": "Book citation",
+    "text": "Book citation\nYou can use the following BibTex entry to cite this book:\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}",
+    "crumbs": [
+      "Welcome"
+    ]
+  },
+  {
+    "objectID": "index.html#corresponding-author-and-maintainer",
+    "href": "index.html#corresponding-author-and-maintainer",
+    "title": "Introduction to Zig",
+    "section": "Corresponding author and maintainer",
+    "text": "Corresponding author and maintainer\nPedro Duarte Faria\nContact: pedropark99@gmail.com\nPersonal website: https://pedro-faria.netlify.app/",
+    "crumbs": [
+      "Welcome"
+    ]
+  },
+  {
+    "objectID": "index.html#acknowledgments",
+    "href": "index.html#acknowledgments",
+    "title": "Introduction to Zig",
+    "section": "Acknowledgments",
+    "text": "Acknowledgments\nThis book is also a product of many conversations and exchanges that we had with different people from the Zig community. I (Pedro Duarte Faria) am incredibly grateful for these conversations, and also, for some direct contributions that we had. Below we have a list of the people involved (name of the person with their usename in GitHub):\nCalin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang), Tommaso Ricci (@Zorgatone), Primo Sabatini (@primos63), Santiago Fernandez (@santif), Hamza Wahed (@HamzaWahed), mwilbur (@mwilbur), Dima Budaragin (@dbud), Jorge Jímenez (@jorge-j1m)",
+    "crumbs": [
+      "Welcome"
+    ]
+  },
+  {
+    "objectID": "index.html#footnotes",
+    "href": "index.html#footnotes",
+    "title": "Introduction to Zig",
+    "section": "",
+    "text": "https://www.blip.ai/en/↩︎\nhttps://ppea.ufop.br/↩︎\nhttp://fjp.mg.gov.br/↩︎\nhttps://creativecommons.org/licenses/by/4.0/↩︎",
+    "crumbs": [
+      "Welcome"
+    ]
+  },
+  {
+    "objectID": "Chapters/01-zig-weird.html",
+    "href": "Chapters/01-zig-weird.html",
+    "title": "1  Introducing Zig",
+    "section": "",
+    "text": "1.1 What is Zig?\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of Zig as a modern and better version of C.\nIn the author’s personal interpretation, Zig is tightly connected with “less is more”. Instead of trying to become a modern language by adding more and more features, many of the core improvements that Zig brings to the table are actually about removing annoying behaviours/features from C and C++. In other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour. As a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\nThis philosophy becomes clear with the following phrase from the official website of Zig:\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language, with tons of features, and also, there are lots of different “flavors of C++”. These elements are what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction. Zig is a very simple language, more closely related to other simple languages such as C and Go.\nThe phrase above is still important for C programmers too. Because, even C being a simple language, it is still hard sometimes to read and understand C code. For example, pre-processor macros in C are a frequent source of confusion. They really make it sometimes hard to debug C programs. Because macros are essentially a second language embedded in C that obscures your C code. With macros, you are no longer 100% sure about which pieces of the code are being sent to the compiler, i.e. they obscures the actual source code that you wrote.\nYou don’t have macros in Zig. In Zig, the code you write, is the actual code that get’s compiled by the compiler. You also don’t have a hidden control flow happening behind the scenes. And, you also don’t have functions or operators from the standard library that make hidden memory allocations behind your back.\nBy being a simpler language, Zig becomes much more clear and easier to read/write, but at the same time, it also achieves a much more robust state, with more consistent behaviour in edge situations. Once again, less is more.",
+    "crumbs": [
+      "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/01-zig-weird.html#what-is-zig",
+    "href": "Chapters/01-zig-weird.html#what-is-zig",
+    "title": "1  Introducing Zig",
+    "section": "",
+    "text": "“Focus on debugging your application rather than debugging your programming language knowledge”.",
+    "crumbs": [
+      "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/01-zig-weird.html#hello-world-in-zig",
+    "href": "Chapters/01-zig-weird.html#hello-world-in-zig",
+    "title": "1  Introducing Zig",
+    "section": "1.2 Hello world in Zig",
+    "text": "1.2 Hello world in Zig\nWe begin our journey in Zig by creating a small “Hello World” program. To start a new Zig project in your computer, you simply call the init command from the zig compiler. Just create a new directory in your computer, then, init a new Zig project inside this directory, like this:\nmkdir hello_world\ncd hello_world\nzig init\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n\n1.2.1 Understanding the project files\nAfter you run the init command from the zig compiler, some new files are created inside of your current directory. First, a “source” (src) directory is created, containing two files, main.zig and root.zig. Each .zig file is a separate Zig module, which is simply a text file that contains some Zig code.\nBy convention, the main.zig module is where your main function lives. Thus, if you are building an executable program in Zig, you need to declare a main() function, which represents the entrypoint of your program, i.e. it is where the execution of your program begins.\nHowever, if you are building a library (instead of an executable program), then, the normal procedure is to delete this main.zig file and start with the root.zig module. By convention, the root.zig module is the root source file of your library.\ntree .\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\nThe init command also creates two additional files in our working directory: build.zig and build.zig.zon. The first file (build.zig) represents a build script written in Zig. This script is executed when you call the build command from the zig compiler. In other words, this file contain Zig code that executes the necessary steps to build the entire project.\nLow-level languages normally use a compiler to build your source code into binary executables or binary libraries. Nevertheless, this process of compiling your source code and building binary executables or binary libraries from it, became a real challenge in the programming world, once the projects became bigger and bigger. As a result, programmers created “build systems”, which are a second set of tools designed to make this process of compiling and building complex projects, easier.\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja, which are used to build complex C and C++ projects. With these systems, you can write scripts, which are called “build scripts”. They simply are scripts that describes the necessary steps to compile/build your project.\nHowever, these are separate tools, that do not belong to C/C++ compilers, like gcc or clang. As a result, in C/C++ projects, you have not only to install and manage your C/C++ compilers, but you also have to install and manage these build systems separately.\nIn Zig, we don’t need to use a separate set of tools to build our projects, because a build system is embedded inside the language itself. Therefore, Zig contains a native build system in it, and we can use this build system to write small scripts in Zig, which describes the necessary steps to build/compile our Zig project1. So, everything you need to build a complex Zig project is the zig compiler, and nothing more.\nThe second generated file (build.zig.zon) is a JSON-like file, in which you can describe your project, and also, declare a set of dependencies of your project that you want to fetch from the internet. In other words, you can use this build.zig.zon file to include a list of external libraries in your project.\nOne possible way to include an external Zig library in your project, is to manually build and install the library in your system, and just link your source code with the library at the build step of your project.\nHowever, if this external Zig library is available on GitHub for example, and it has a valid build.zig.zon file in root folder of the project, which describes the project, you can easily include this library in your project by simply listing this external library in your build.zig.zon file.\nIn other words, this build.zig.zon file works similarly to the package.json file in Javascript projects, or the Pipfile file in Python projects, or the Cargo.toml file in Rust projects. You can read more about this specific file in a couple of articles on the internet23, and you can also see the expected schema for this build.zig.zon file in a documentation file inside the official repository of Zig4.\n\n\n1.2.2 The file root.zig\nLet’s take a look into the root.zig file. You might have noticed that every line of code with an expression ends with a semicolon (;). This follows the syntax of a C-family programming language5.\nAlso, notice the @import() call at the first line. We use this built-in function to import functionality from other Zig modules into our current module. This @import() function works similarly to the #include pre-processor in C or C++, or, to the import statement in Python or Javascript code. In this example, we are importing the std module, which gives you access to the Zig Standard Library.\nIn this root.zig file, we can also see how assignments (i.e. creating new objects) are made in Zig. You can create a new object in Zig by using the following syntax (const|var) name = value;. In the example below, we are creating two constant objects (std and testing). At Section 1.4 we talk more about objects in general.\n\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n\nFunctions in Zig are declared using the fn keyword. In this root.zig module, we are declaring a function called add(), which has two arguments named a and b. The function returns an integer of the type i32 as result.\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit the type of an object in your code, if this type can be inferred by the zig compiler (we talk more about that at Section 2.4). But there are other situations where you do need to be explicit. For example, you do have to explicitly specify the type of each function argument, and also, the return type of every function that you create in Zig.\nWe specify the type of an object or a function argument in Zig by using a colon character (:) followed by the type after the name of this object/function argument. With the expressions a: i32 and b: i32, we know that both a and b arguments have type i32, which is a signed 32 bit integer. In this part, the syntax in Zig is identical to the syntax in Rust, which also specifies types by using the colon character.\nLastly, we have the return type of the function at the end of the line, before we open the curly braces to start writing the function’s body. In the example above, this type is also a signed 32 bit integer (i32) value.\nNotice that we also have an export keyword before the function declaration. This keyword is similar to the extern keyword in C. It exposes the function to make it available in the library API. Therefore, if you are writing a library for other people to use, you have to expose the functions you write in the public API of this library by using this export keyword. If we removed the export keyword from the add() function declaration, then, this function would be no longer exposed in the library object built by the zig compiler.\n\n\n1.2.3 The main.zig file\nNow that we have learned a lot about Zig’s syntax from the root.zig file, let’s take a look at the main.zig file. A lot of the elements we saw in root.zig are also present in main.zig. But there are some other elements that we haven’t seen yet, so let’s dive in.\nFirst, look at the return type of the main() function in this file. We can see a small change. The return type of the function (void) is accompanied by an exclamation mark (!). This exclamation mark tells us that this main() function might return an error.\nIs worth noting that, a main() function in Zig is allowed to return nothing (void), or an unsigned 8-bit integer (u8) value6, or an error. In other words, you can write your main() function in Zig to return essentially nothing (void), or, if you prefer, you can also write a more C-like main() function, which returns an integer value that usually serves as a “status code” for the process.\nIn this example, the return type annotation of main() indicates that this function can either return nothing (void), or return an error. This exclamation mark in the return type annotation is an interesting and powerful feature of Zig. In summary, if you write a function and something inside the body of this function might return an error, then, you are forced to:\n\neither add the exclamation mark to the return type of the function and make it clear that this function might return an error.\nexplicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through a try catch pattern. Zig does have both try and catch keywords. But they work a little differently than what you’re probably used to in other languages.\nIf we look at the main() function below, you can see that we do have a try keyword on the 5th line. But we do not have a catch keyword in this code. In Zig, we use the try keyword to execute an expression that might return an error, which, in this example, is the stdout.print() expression.\nIn essence, the try keyword executes the expression stdout.print(). If this expression returns a valid value, then, the try keyword does absolutely nothing. It only passes the value forward. It is like if this try keyword was never there. However, if the expression does return an error, then, the try keyword will unwrap the error value, then, it returns this error from the function and also prints the current stack trace to stderr.\nThis might sound weird to you if you come from a high-level language. Because in high-level languages, such as Python, if an error occurs somewhere, this error is automatically returned and the execution of your program will automatically stop even if you don’t want to stop the execution. You are obligated to face the error.\n\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n\nAnother thing that you might have noticed in this code example, is that the main() function is marked with the pub keyword. It marks the main() function as a public function from this module. Every function in your Zig module is by default private to this Zig module and can only be called from within the module. Unless, you explicitly mark this function as a public function with the pub keyword.\nIf you think about it, this pub keyword in Zig does essentially the opposite of what the static keyword do in C/C++. By making a function “public” you allow other Zig modules to access and call this function. A calling Zig module imports another module by using the @import() built-in function, which makes all public functions from the imported module visible to the calling Zig module.\n\n\n1.2.4 Compiling your source code\nYou can compile your Zig modules into a binary executable by running the build-exe command from the zig compiler. You simply list all the Zig modules that you want to build after the build-exe command, separated by spaces. In the example below, we are compiling the module main.zig.\nzig build-exe src/main.zig\nSince we are building an executable, the zig compiler will look for a main() function declared in any of the files that you list after the build-exe command. If the compiler does not find a main() function declared somewhere, a compilation error will be raised, warning about this mistake.\nThe zig compiler also offers a build-lib and build-obj commands, which work the exact same way as the build-exe command. The only difference is that, they compile your Zig modules into a portable C ABI library, or, into object files, respectively.\nIn the case of the build-exe command, a binary executable file is created by the zig compiler in the root directory of your project. If we take a look now at the contents of our current directory, with a simple ls command, we can see the binary file called main that was created by the compiler.\nls\nbuild.zig  build.zig.zon  main  src\nIf I execute this binary executable, I get the “Hello World” message in the terminal , as we expected.\n./main\nHello, world!\n\n\n1.2.5 Compile and execute at the same time\nIn the previous section, I presented the zig build-exe command, which compiles Zig modules into an executable file. However, this means that, in order to execute the executable file, we have to run two different commands. First, the zig build-exe command, and then, we call the executable file created by the compiler.\nBut what if we wanted to perform these two steps, all at once, in a single command? We can do that by using the zig run command.\nzig run src/main.zig\nHello, world!\n\n\n1.2.6 Important note for Windows users\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other operating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that includes some global variables whose initialization rely on runtime resources, then, you might have some troubles while trying to compile this Zig code on Windows.\nAn example of that is accessing the stdout (i.e. the standard output of your system), which is usually done in Zig by using the expression std.io.getStdOut(). Thus, if you use this expression to instantiate a global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows, with a “unable to evaluate comptime expression” error message.\nThis failure in the compilation process happens because all global variables in Zig are initialized at compile-time. However, operations like accessing the stdout (or opening a file) on Windows depends on resources that are available only at runtime (you will learn more about compile-time versus runtime at Section 3.1.1).\nFor example, if you try to compile this code example on Windows, you will likely get the error message exposed below:\n\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\nTo avoid this problem on Windows, we need to force the zig compiler to instantiate this stdout object only at runtime, instead of instantiating it at compile-time. We can achieve that by simply moving the expression to a function body.\nThis solves the problem because all expressions that are inside a function body in Zig are evaluated only at runtime, unless you use the comptime keyword explicitly to change this behaviour. You will learn more about this comptime keyword at Section 12.1.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nHello\nYou can read more details about this Windows-specific limitation at a couple of GitHub issues opened at the official Zig repository. More specifically, the issues 17186 7 and 19864 8.\n\n\n1.2.7 Compiling the entire project\nJust as I described in Section 1.2.1, as our project grows in size and complexity, we usually prefer to organize the compilation and build process of the project into a build script, using some sort of “build system”.\nIn other words, as our project grows in size and complexity, the build-exe, build-lib and build-obj commands become harder to use directly. Because then, we start to list multiple and multiple modules at the same time. We also start to add built-in compilation flags to customize the build process for our needs, etc. It becomes a lot of work to write the necessary commands by hand.\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, Makefile or configure scripts to organize this process. However, in Zig, we have a native build system in the language itself. So, we can write build scripts in Zig to compile and build Zig projects. Then, all we need to do, is to call the zig build command to build our project.\nSo, when you execute the zig build command, the zig compiler will search for a Zig module named build.zig inside your current directory, which should be your build script, containing the necessary code to compile and build your project. If the compiler does find this build.zig file in your directory, then, the compiler will essentially execute a zig run command over this build.zig file, to compile and execute this build script, which in turn, will compile and build your entire project.\nzig build\nAfter you execute this “build project” command, a zig-out directory is created in the root of your project directory, where you can find the binary executables and libraries created from your Zig modules accordingly to the build commands that you specified at build.zig. We will talk more about the build system in Zig later in this book.\nIn the example below, I’m executing the binary executable named hello_world that was generated by the compiler after the zig build command.\n./zig-out/bin/hello_world\nHello, world!",
+    "crumbs": [
+      "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/01-zig-weird.html#how-to-learn-zig",
+    "href": "Chapters/01-zig-weird.html#how-to-learn-zig",
+    "title": "1  Introducing Zig",
+    "section": "1.3 How to learn Zig?",
+    "text": "1.3 How to learn Zig?\nWhat are the best strategies to learn Zig? First of all, of course this book will help you a lot on your journey through Zig. But you will also need some extra resources if you want to be really good at Zig.\nAs a first tip, you can join a community with Zig programmers to get some help , when you need it:\n\nReddit forum: https://www.reddit.com/r/Zig/;\nZiggit community: https://ziggit.dev/;\nDiscord, Slack, Telegram, and others: https://github.com/ziglang/zig/wiki/Community;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try to read Zig code often, and things will become more clear. A C/C++ programmer would also probably give you this same tip. Because this strategy really works!\nNow, where can you find Zig code to read? I personally think that, the best way of reading Zig code is to read the source code of the Zig Standard Library. The Zig Standard Library is available at the lib/std folder9 on the official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\nAlso, a great alternative is to read code from other large Zig codebases, such as:\n\nthe Javascript runtime Bun10.\nthe game engine Mach11.\na LLama 2 LLM model implementation in Zig12.\nthe financial transactions database tigerbeetle13.\nthe command-line arguments parser zig-clap14.\nthe UI framework capy15.\nthe Language Protocol implementation for Zig, zls16.\nthe event-loop library libxev17.\n\nAll these assets are available on GitHub, and this is great, because we can use the GitHub search bar to our advantage, to find Zig code that fits our description. For example, you can always include lang:Zig in the GitHub search bar when you are searching for a particular pattern. This will limit the search to only Zig modules.\nAlso, a great alternative is to consult online resources and documentation. Here is a quick list of resources that I personally use from time to time to learn more about the language each day:\n\nZig Language Reference: https://ziglang.org/documentation/master/;\nZig Standard Library Reference: https://ziglang.org/documentation/master/std/;\nZig Guide: https://zig.guide/;\nKarl Seguin Blog: https://www.openmymind.net/;\nZig News: https://zig.news/;\nRead the code written by one of the Zig core team members: https://github.com/kubkon;\nSome livecoding sessions are transmitted in the Zig Showtime Youtube Channel: https://www.youtube.com/@ZigSHOWTIME/videos;\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want, is to practice it by solving exercises. For example, there is a famous repository in the Zig community called Ziglings18 , which contains more than 100 small exercises that you can solve. It is a repository of tiny programs written in Zig that are currently broken, and your responsibility is to fix these programs, and make them work again.\nA famous tech YouTuber known as The Primeagen also posted some videos (on YouTube) where he solves these exercises from Ziglings. The first video is named “Trying Zig Part 1”19.\nAnother great alternative, is to solve the Advent of Code exercises20. There are people that already took the time to learn and solve the exercises, and they posted their solutions on GitHub as well, so, in case you need some resource to compare while solving the exercises, you can look at these two repositories:\n\nhttps://github.com/SpexGuy/Zig-AoC-Template;\nhttps://github.com/fjebaker/advent-of-code-2022;",
+    "crumbs": [
+      "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/01-zig-weird.html#sec-assignments",
+    "href": "Chapters/01-zig-weird.html#sec-assignments",
+    "title": "1  Introducing Zig",
+    "section": "1.4 Creating new objects in Zig (i.e. identifiers)",
+    "text": "1.4 Creating new objects in Zig (i.e. identifiers)\nLet’s talk more about objects in Zig. Readers that have past experience with other programming languages might know this concept through a different name, such as: “variable” or “identifier”. In this book, I choose to use the term “object” to refer to this concept.\nTo create a new object (or a new “identifier”) in Zig, we use the keywords const or var. These keywords specify if the object that you are creating is mutable or not. If you use const, then the object you are creating is a constant (or immutable) object, which means that once you declare this object, you can no longer change the value stored inside this object.\nOn the other side, if you use var, then, you are creating a variable (or mutable) object. You can change the value of this object as many times you want. Using the keyword var in Zig is similar to using the keywords let mut in Rust.\n\n1.4.1 Constant objects vs variable objects\nIn the code example below, we are creating a new constant object called age. This object stores a number representing the age of someone. However, this code example does not compile successfully. Because on the next line of code, we are trying to change the value of the object age to 25.\nThe zig compiler detects that we are trying to change the value of an object/identifier that is constant, and because of that, the compiler will raise a compilation error, warning us about the mistake.\n\nconst age = 24;\n// The line below is not valid!\nage = 25;\n\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\nIn contrast, if you use var, then, the object created is a variable object. With var you can declare this object in your source code, and then, change the value of this object how many times you want over future points in your source code.\nSo, using the same code example exposed above, if I change the declaration of the age object to use the var keyword, then, the program gets compiled successfully. Because now, the zig compiler detects that we are changing the value of an object that allows this behaviour, because it is an “variable object”.\n\nvar age: u8 = 24;\nage = 25;\n\n\n\n1.4.2 Declaring without an initial value\nBy default, when you declare a new object in Zig, you must give it an initial value. In other words, this means that we have to declare, and, at the same time, initialize every object we create in our source code.\nOn the other hand, you can, in fact, declare a new object in your source code, and not give it an explicit value. But we need to use a special keyword for that, which is the undefined keyword.\nIs important to emphasize that, you should avoid using undefined as much as possible. Because when you use this keyword, you leave your object uninitialized, and, as a consequence, if for some reason, your code use this object while it is uninitialized, then, you will definitely have undefined behaviour and major bugs in your program.\nIn the example below, I’m declaring the age object again. But this time, I do not give it an initial value. The variable is only initialized at the second line of code, where I store the number 25 in this object.\n\nvar age: u8 = undefined;\nage = 25;\n\nHaving these points in mind, just remember that you should avoid as much as possible to use undefined in your code. Always declare and initialize your objects. Because this gives you much more safety in your program. But in case you really need to declare an object without initializing it… the undefined keyword is the way to do it in Zig.\n\n\n1.4.3 There is no such thing as unused objects\nEvery object (being constant or variable) that you declare in Zig must be used in some way. You can give this object to a function call, as a function argument, or, you can use it in another expression to calculate the value of another object, or, you can call a method that belongs to this particular object.\nIt doesn’t matter in which way you use it. As long as you use it. If you try to break this rule, i.e. if your try to declare a object, but not use it, the zig compiler will not compile your Zig source code, and it will issue a error message warning that you have unused objects in your code.\nLet’s demonstrate this with an example. In the source code below, we declare a constant object called age. If you try to compile a simple Zig program with this line of code below, the compiler will return an error as demonstrated below:\n\nconst age = 15;\n\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\nEverytime you declare a new object in Zig, you have two choices:\n\nyou either use the value of this object;\nor you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign this object to a special character in Zig, which is the underscore (_). When you assign an object to a underscore, like in the example below, the zig compiler will automatically discard the value of this particular object.\nYou can see in the example below that, this time, the compiler did not complain about any “unused constant”, and successfully compiled our source code.\n\n// It compiles!\nconst age = 15;\n_ = age;\n\nNow, remember, everytime you assign a particular object to the underscore, this object is essentially destroyed. It is discarded by the compiler. This means that you can no longer use this object further in your code. It doesn’t exist anymore.\nSo if you try to use the constant age in the example below, after we discarded it, you will get a loud error message from the compiler (talking about a “pointless discard”) warning you about this mistake.\n\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n\nt.zig:7:5: error: pointless discard\n    of local constant\nThis same rule applies to variable objects. Every variable object must also be used in some way. And if you assign a variable object to the underscore, this object also get’s discarded, and you can no longer use this object.\n\n\n1.4.4 You must mutate every variable objects\nEvery variable object that you create in your source code must be mutated at some point. In other words, if you declare an object as a variable object, with the keyword var, and you do not change the value of this object at some point in the future, the zig compiler will detect this, and it will raise an error warning you about this mistake.\nThe concept behind this is that every object you create in Zig should be preferably a constant object, unless you really need an object whose value will change during the execution of your program.\nSo, if I try to declare a variable object such as where_i_live below, and I do not change the value of this object in some way, the zig compiler raises an error message with the phrase “variable is never mutated”.\n\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'",
+    "crumbs": [
+      "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/01-zig-weird.html#sec-primitive-data-types",
+    "href": "Chapters/01-zig-weird.html#sec-primitive-data-types",
+    "title": "1  Introducing Zig",
+    "section": "1.5 Primitive Data Types",
+    "text": "1.5 Primitive Data Types\nZig have many different primitive data types available for you to use. You can see the full list of available data types at the official Language Reference page21.\nBut here is a quick list:\n\nUnsigned integers: u8, 8-bit integer; u16, 16-bit integer; u32, 32-bit integer; u64, 64-bit integer; u128, 128-bit integer.\nSigned integers: i8, 8-bit integer; i16, 16-bit integer; i32, 32-bit integer; i64, 64-bit integer; i128, 128-bit integer.\nFloat number: f16, 16-bit floating point; f32, 32-bit floating point; f64, 64-bit floating point; f128, 128-bit floating point;\nBoolean: bool, represents true or false values.\nC ABI compatible types: c_long, c_char, c_short, c_ushort, c_int, c_uint, and many others.\nPointer sized integers: isize and usize.",
+    "crumbs": [
+      "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/01-zig-weird.html#sec-arrays",
+    "href": "Chapters/01-zig-weird.html#sec-arrays",
+    "title": "1  Introducing Zig",
+    "section": "1.6 Arrays",
+    "text": "1.6 Arrays\nYou create arrays in Zig by using a syntax that resembles the C syntax. First, you specify the size of the array (i.e. the number of elements that will be stored in the array) you want to create inside a pair of brackets.\nThen, you specify the data type of the elements that will be stored inside this array. All elements present in an array in Zig must have the same data type. For example, you cannot mix elements of type f32 with elements of type i32 in the same array.\nAfter that, you simply list the values that you want to store in this array inside a pair of curly braces. In the example below, I am creating two constant objects that contain different arrays. The first object contains an array of 4 integer values, while the second object, an array of 3 floating point values.\nNow, you should notice that in the object ls, I am not explicitly specifying the size of the array inside of the brackets. Instead of using a literal value (like the value 4 that I used in the ns object), I am using the special character underscore (_). This syntax tells the zig compiler to fill this field with the number of elements listed inside of the curly braces. So, this syntax [_] is for lazy (or smart) programmers who leave the job of counting how many elements there are in the curly braces for the compiler.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n\nIs worth noting that these are static arrays, meaning that they cannot grow in size. Once you declare your array, you cannot change the size of it. This is very common in low level languages. Because low level languages normally wants to give you (the programmer) full control over memory, and the way in which arrays are expanded is tightly related to memory management.\n\n1.6.1 Selecting elements of the array\nOne very common activity is to select specific portions of an array you have in your source code. In Zig, you can select a specific element from your array, by simply providing the index of this particular element inside brackets after the object name. In the example below, I am selecting the third element from the ns array. Notice that Zig is a “zero-index” based language, like C, C++, Rust, Python, and many other languages.\n\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n\n12\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a range selector. Some programmers also call these selectors of “slice selectors”, and they also exist in Rust, and have the exact same syntax as in Zig. Anyway, a range selector is a special expression in Zig that defines a range of indexes, and it have the syntax start..end.\nIn the example below, at the second line of code, the sl object stores a slice (or a portion) of the ns array. More precisely, the elements at index 1 and 2 in the ns array.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n\nWhen you use the start..end syntax, the “end tail” of the range selector is non-inclusive, meaning that, the index at the end is not included in the range that is selected from the array. Therefore, the syntax start..end actually means start..end - 1 in practice.\nYou can for example, create a slice that goes from the first to the last elements of the array, by using ar[0..ar.len] syntax In other words, it is a slice that access all elements in the array.\n\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n\nYou can also use the syntax start.. in your range selector. Which tells the zig compiler to select the portion of the array that begins at the start index until the last element of the array. In the example below, we are selecting the range from index 1 until the end of the array.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n\n\n\n1.6.2 More on slices\nAs we discussed before, in Zig, you can select specific portions of an existing array. This is called slicing in Zig (Sobeston 2024), because when you select a portion of an array, you are creating a slice object from that array.\nA slice object is essentially a pointer object accompanied by a length number. The pointer object points to the first element in the slice, and the length number tells the zig compiler how many elements there are in this slice.\n\nSlices can be thought of as a pair of [*]T (the pointer to the data) and a usize (the element count) (Sobeston 2024).\n\nThrough the pointer contained inside the slice you can access the elements (or values) that are inside this range (or portion) that you selected from the original array. But the length number (which you can access through the len property of your slice object) is the really big improvement (over C arrays for example) that Zig brings to the table here.\nBecause with this length number the zig compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice, or, if you are causing any buffer overflow problems. In the example below, we access the len property of the slice sl, which tells us that this slice have 2 elements in it.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n\n2\n\n\n\n\n1.6.3 Array operators\nThere are two array operators available in Zig that are very useful. The array concatenation operator (++), and the array multiplication operator (**). As the name suggests, these are array operators.\nOne important detail about these two operators is that they work only when both operands have a size (or “length”) that is compile-time known. We are going to talk more about the differences between “compile-time known” and “runtime known” at Section 3.1.1. But for now, keep this information in mind, that you cannot use these operators in every situation.\nIn summary, the ++ operator creates a new array that is the concatenation, of both arrays provided as operands. So, the expression a ++ b produces a new array which contains all the elements from arrays a and b.\n\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n\n{ 1, 2, 3, 4, 5 }\n\n\nThis ++ operator is particularly useful to concatenate strings together. Strings in Zig are described in depth at Section 1.8. In summary, a string object in Zig is essentially an arrays of bytes. So, you can use this array concatenation operator to effectively concatenate strings together.\nIn contrast, the ** operator is used to replicate an array multiple times. In other words, the expression a ** 3 creates a new array which contains the elements of the array a repeated 3 times.\n\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n\n{ 1, 2, 3, 1, 2, 3 }\n\n\n\n\n1.6.4 Runtime versus compile-time known length in slices\nWe are going to talk a lot about the differences between compile-time known and runtime known across this book, especially at Section 3.1.1. But the basic idea is that a thing is compile-time known, when we know everything (the value, the attributes and the characteristics) about this thing at compile-time. In contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime. Therefore, we don’t know the value of this thing at compile-time, only at runtime.\nWe have learned at Section 1.6.1 that slices are created by using a range selector, which represents a range of indexes. When this “range of indexes” (i.e. the start and the end of this range) is known at compile-time, the slice object that get’s created is actually, under the hood, just a single-item pointer to an array.\nYou don’t need to precisely understand what that means now. We are going to talk a lot about pointers at Chapter 6. For now, just understand that, when the range of indexes is known at compile-time, the slice that get’s created is just a pointer to an array, accompanied by a length value that tells the size of the slice.\nIf you have a slice object like this, i.e. a slice that has a compile-time known range, you can use common pointer operations over this slice object. For example, you can dereference the pointer of this slice, by using the .* method, like you would do on a normal pointer object.\n\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object that get’s created is not a pointer anymore, and, thus, it does not support pointer operations. For example, maybe the start index is known at compile time, but the end index is not. In such case, the range of the slice becomes runtime known only.\nIn the example below, the slice object have a runtime known range, because the end index of the range is not known at compile time. In other words, the size of the array at buffer is not known at compile time. When we execute this program, the size of the array might be 10, or, it might be 12 depending on where we execute it. Therefore, we don’t know at compile time if the slice object have a range of size 10, or, a range of size 12.\n\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}",
+    "crumbs": [
+      "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/01-zig-weird.html#sec-blocks",
+    "href": "Chapters/01-zig-weird.html#sec-blocks",
+    "title": "1  Introducing Zig",
+    "section": "1.7 Blocks and scopes",
+    "text": "1.7 Blocks and scopes\nBlocks are created in Zig by a pair of curly braces. A block is just a group of expressions (or statements) contained inside of a pair of curly braces. All of these expressions that are contained inside of this pair of curly braces belongs to the same scope.\nIn other words, a block just delimits a scope in your code. The objects that you define inside the same block belongs to the same scope, and, therefore, are accessible from within this scope. At the same time, these objects are not accessible outside of this scope. So, you could also say that blocks are used to limit the scope of the objects that you create in your source code. In less technical terms, blocks are used to specify where in your source code you can access whatever object you have in your source code.\nSo, a block is just a group of expressions contained inside a pair of curly braces. And every block have its own scope separated from the others. The body of a function is a classic example of a block. If statements, for and while loops (and any other structure in the language that uses the pair of curly braces) are also examples of blocks.\nThis means that, every if statement, or for loop, etc., that you create in your source code have its own separate scope. That is why you can’t access the objects that you defined inside of your for loop (or if statement) in an outer scope, i.e. a scope outside of the for loop. Because you are trying to access an object that belongs to a scope that is different than your current scope.\nYou can create blocks within blocks, with multiple levels of nesting. You can also (if you want to) give a label to a particular block, with the colon character (:). Just write label: before you open the pair of curly braces that delimits your block. When you label a block in Zig, you can use the break keyword to return a value from this block, like as if it was a function’s body. You just write the break keyword, followed by the block label in the format :label, and the expression that defines the value that you want to return.\nLike in the example below, where we are returning the value from the y object from the block add_one, and saving the result inside the x object.\n\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n\nHey!",
+    "crumbs": [
+      "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/01-zig-weird.html#sec-zig-strings",
+    "href": "Chapters/01-zig-weird.html#sec-zig-strings",
+    "title": "1  Introducing Zig",
+    "section": "1.8 How strings work in Zig?",
+    "text": "1.8 How strings work in Zig?\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (Chapter 4). But in order for us to build such a thing, we need to get a better understanding on how strings work in Zig. So let’s discuss this specific aspect of Zig.\nIn summary, there are two types of string values that you care about in Zig, which are:\n\nString literal values.\nString objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string). But in Zig, a string literal value also embeds the length of the string into the data type of the value itself. Therefore, a string literal value have a data type in the format *const [n:0]u8. The n in the data type indicates the size of the string.\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes, or, in other words, a slice of u8 values (slices were presented at Section 1.6). Thus, a string object have a data type of []u8 or []const u8, depending if the string object is marked as constant with const, or as variable with var.\nBecause a string object is essentially a slice, it means that a string object always contains two things: a pointer to an array of bytes (i.e. u8 values) that represents the string value; and also, a length value, which specifies the size of the slice, or, how many elements there is in the slice. Is worth to emphasize that the array of bytes in a string object is not null-terminated, like in a string literal value.\n\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every sequence of bytes you’re working with, but is not really Zig’s job to fix the encoding of your strings (you can use iconv22 for that). Today, most of the text in our modern world, especially on the web, should be UTF-8 encoded. So if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\nLet’s take for example the word “Hello”. In UTF-8, this sequence of characters (H, e, l, l, o) is represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this sequence is 0x48, 0x65, 0x6C, 0x6C, 0x6F. So if I take this sequence of hexadecimal values, and ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then, the text “Hello” will be printed into the terminal:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n\nHello\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use a for loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal value to the terminal. You do that by using a print() statement with the X formatting specifier, like you would normally do with the printf() function23 in C.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n\n\n\n1.8.1 Strings in C\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well. In more details, string values in C are treated internally as an array of arbitrary bytes, and this array is also null-terminated.\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of the string inside the object itself. In the case of a string literal value, this length is stored in the data type of the value (i.e. the n variable in [n:0]u8). While, in a string object, the length is stored in the len attribute of the slice that represents the string object. This small detail makes your code safer, because it is much easier for the Zig compiler to check if you are trying to access an element that is “out of bounds”, i.e. if your trying to access memory that does not belong to you.\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless. So getting this kind of safety is not automatic and much harder to do in C. For example, if you want to track the length of your string throughout your program in C, then, you first need to loop through the array of bytes that represents this string, and find the null element ('\\0') position to discover where exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\nTo do that, you would need something like this in C. In this example, the C string stored in the object array is 25 bytes long:\n\n#include &lt;stdio.h&gt;\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n\nNumber of elements in the array: 25\nYou don’t have this kind of work in Zig. Because the length of the string is always present and accessible. In a string object for example, you can easily access the length of the string through the len attribute. As an example, the string_object object below is 43 bytes long:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n\n43\n\n\n\n\n1.8.2 A better look at the object type\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the @TypeOf() function. If we look at the type of the simple_array object below, you will find that this object is an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type i32 in Zig. That is what an object of type [4]i32 is.\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a constant pointer (hence the *const annotation) to an array of 16 elements (or 16 bytes). Each element is a single byte (more precisely, an unsigned 8 bit integer - u8), that is why we have the [16:0]u8 portion of the type below. In other words, the string literal value exposed below is 16 bytes long.\nNow, if we create an pointer to the simple_array object, then, we get a constant pointer to an array of 4 elements (*const [4]i32), which is very similar to the type of the string literal value. This demonstrates that a string literal value in Zig is already a pointer to a null-terminated array of bytes.\nFurthermore, if we take a look at the type of the string_obj object, you will see that it is a slice object (hence the [] portion of the type) to a sequence of constant u8 values (hence the const u8 portion of the type).\n\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n\n\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n\n\n1.8.3 Byte vs unicode points\nIs important to point out that each byte in the array is not necessarily a single character. This fact arises from the difference between a single byte and a single unicode point.\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in the string. For example, the character “H” is stored in UTF-8 as the decimal number 72. This means that the number 72 is the unicode point for the character “H”. Each possible character that can appear in a UTF-8 encoded string have its own unicode point.\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point) 570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which is 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why, the unicode point 570 is actually stored inside the computer’s memory as the bytes C8 BA.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n\nBytes that represents the string object: C8 BA \n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together to represent the number 570. That is why the relationship between bytes and unicode points is not always 1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds to a single unicode point.\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the bytes that represents that string, and not through the characters of that string. In the Ⱥ example above, the for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a consequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because the number of bytes will be equal to the number of characters in that string. In other words, in this specific situation, the relationship between bytes and unicode points is 1 to 1.\nBut on the other side, if your string contains other types of letters… for example, you might be working with text data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent your UTF-8 string will likely be much higher than the number of characters in that string.\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the std.unicode.Utf8View struct to create an iterator that iterates through the unicode points of your string.\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in this string is represented by three bytes. But the for loop iterates four times, one iteration for each character/unicode point in this string:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n\n\n1.8.4 Some useful functions for strings\nIn this section, I just want to quickly describe some functions from the Zig Standard Library that are very useful to use when working with strings. Most notably:\n\nstd.mem.eql(): to compare if two strings are equal.\nstd.mem.splitScalar(): to split a string into an array of substrings given a delimiter value.\nstd.mem.splitSequence(): to split a string into an array of substrings given a substring delimiter.\nstd.mem.startsWith(): to check if string starts with substring.\nstd.mem.endsWith(): to check if string ends with substring.\nstd.mem.trim(): to remove specific values from both start and end of the string.\nstd.mem.concat(): to concatenate strings together.\nstd.mem.count(): to count the occurrences of substring in the string.\nstd.mem.replace(): to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the mem module of the Zig Standard Library. This module contains multiple functions and methods that are useful to work with memory and sequences of bytes in general.\nThe eql() function is used to check if two arrays of data are equal or not. Since strings are just arbitrary arrays of bytes, we can use this function to compare two strings together. This function returns a boolean value indicating if the two strings are equal or not. The first argument of this function is the data type of the elements of the arrays that are being compared.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n\ntrue\n\n\nThe splitScalar() and splitSequence() functions are useful to split a string into multiple fragments, like the split() method from Python strings. The difference between these two methods is that the splitScalar() uses a single character as the separator to split the string, while splitSequence() uses a sequence of characters (a.k.a. a substring) as the separator. There is a practical example of these functions later in the book.\nThe startsWith() and endsWith() functions are pretty straightforward. They return a boolean value indicating if the string (or, more precisely, if the array of data) begins (startsWith) or ends (endsWith) with the sequence provided.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n\ntrue\n\n\nThe concat() function, as the name suggests, concatenate two or more strings together. Because the process of concatenating the strings involves allocating enough space to accomodate all the strings together, this concat() function receives an allocator object as input.\n\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n\nAs you can imagine, the replace() function is used to replace substrings in a string by another substring. This function works very similarly to the replace() method from Python strings. Therefore, you provide a substring to search, and every time that the replace() function finds this substring within the input string, it replaces this substring with the “replacement substring” that you provided as input.\nIn the example below, we are taking the input string “Hello”, and replacing all occurrences of the substring “el” inside this input string with “34”, and saving the results inside the buffer object. As result, the replace() function returns an usize value that indicates how many replacements were performed.\n\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n\nNew string: H34lo\nN of replacements: 1",
+    "crumbs": [
+      "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/01-zig-weird.html#safety-in-zig",
+    "href": "Chapters/01-zig-weird.html#safety-in-zig",
+    "title": "1  Introducing Zig",
+    "section": "1.9 Safety in Zig",
+    "text": "1.9 Safety in Zig\nA general trend in modern low-level programming languages is safety. As our modern world becomes more interconnected with technology and computers, the data produced by all of this technology becomes one of the most important (and also, one of the most dangerous) assets that we have.\nThis is probably the main reason why modern low-level programming languages have been giving great attention to safety, especially memory safety, because memory corruption is still the main target for hackers to exploit. The reality is that we don’t have an easy solution for this problem. For now, we only have techniques and strategies that mitigates these problems.\nAs Richard Feldman explains on his most recent GOTO conference talk24 , we haven’t figured it out yet a way to achieve true safety in technology. In other words, we haven’t found a way to build software that won’t be exploited with 100% certainty. We can greatly reduce the risks of our software being exploited, by ensuring memory safety for example. But this is not enough to achieve “true safety” territory.\nBecause even if you write your program in a “safe language”, hackers can still exploit failures in the operating system where your program is running (e.g. maybe the system where your code is running has a “backdoor exploit” that can still affect your code in unexpected ways), or also, they can exploit the features from the architecture of your computer. A recently found exploit that involves memory invalidation through a feature of “memory tags” present in ARM chips is an example of that (Kim et al. 2024).\nThe question is: what have Zig and other languages been doing to mitigate this problem? If we take Rust as an example, Rust is, for the most part25, a memory safe language by enforcing specific rules to the developer. In other words, the key feature of Rust, the borrow checker, forces you to follow a specific logic when you are writing your Rust code, and the Rust compiler will always complain everytime you try to go out of this pattern.\nIn contrast, the Zig language is not a memory safe language by default. There are some memory safety features that you get for free in Zig, especially in arrays and pointer objects. But there are other tools offered by the language, that are not used by default. In other words, the zig compiler does not obligate you to use such tools.\nThe tools listed below are related to memory safety. That is, they help you to achieve memory safety in your Zig code:\n\ndefer allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, “use after free”, and also “double-free” problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\nerrdefer helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\npointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\nZig offers some native types of allocators (called “testing allocators”) that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\narrays and slices in Zig have their lengths embedded in the object itself, which makes the zig compiler very effective on detecting “index out-of-range” type of errors, and avoiding buffer overflows.\n\nDespite these features that Zig offers that are related to memory safety issues, the language also has some rules that help you to achieve another type of safety, which is more related to program logic safety. These rules are:\n\npointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\nswitch statements must exaust all possible options.\nthe zig compiler forces you to handle every possible error in your program.",
+    "crumbs": [
+      "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/01-zig-weird.html#other-parts-of-zig",
+    "href": "Chapters/01-zig-weird.html#other-parts-of-zig",
+    "title": "1  Introducing Zig",
+    "section": "1.10 Other parts of Zig",
+    "text": "1.10 Other parts of Zig\nWe already learned a lot about Zig’s syntax, and also, some pretty technical details about it. Just as a quick recap:\n\nWe talked about how functions are written in Zig at Section 1.2.2 and Section 1.2.3.\nHow to create new objects/identifiers at Section 1.2.2 and especially at Section 1.4.\nHow strings work in Zig at Section 1.8.\nHow to use arrays and slices at Section 1.6.\nHow to import functionality from other Zig modules at Section 1.2.2.\n\nBut, for now, this amount of knowledge is enough for us to continue with this book. Later, over the next chapters we will still talk more about other parts of Zig’s syntax that are also equally important. Such as:\n\nHow Object-Oriented programming can be done in Zig through struct declarations at Section 2.3.\nBasic control flow syntax at Section 2.1.\nEnums at Section 7.6;\nPointers and Optionals at Chapter 6;\nError handling with try and catch at Chapter 10;\nUnit tests at Chapter 8;\nVectors at Chapter 17;\nBuild System at Chapter 9;\n\n\n\n\n\nKim, Juhee, Jinbum Park, Sihyeon Roh, Jaeyoung Chung, Youngjoo Lee, Taesoo Kim, and Byoungyoung Lee. 2024. “TikTag: Breaking ARM’s Memory Tagging Extension with Speculative Execution.” https://arxiv.org/abs/2406.08719.\n\n\nSobeston. 2024. “Zig Guide.” https://zig.guide/.",
+    "crumbs": [
+      "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/01-zig-weird.html#footnotes",
+    "href": "Chapters/01-zig-weird.html#footnotes",
+    "title": "1  Introducing Zig",
+    "section": "",
+    "text": "https://ziglang.org/learn/overview/#zig-build-system.↩︎\nhttps://zig.news/edyu/zig-package-manager-wtf-is-zon-558e↩︎\nhttps://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1↩︎\nhttps://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md↩︎\nhttps://en.wikipedia.org/wiki/List_of_C-family_programming_languages↩︎\nYou can see an example of a main() function that returns an u8 value in the return-integer.zig file, https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig↩︎\nhttps://github.com/ziglang/zig/issues/17186↩︎\nhttps://github.com/ziglang/zig/issues/19864↩︎\nhttps://github.com/ziglang/zig/tree/master/lib/std↩︎\nhttps://github.com/oven-sh/bun.↩︎\nhttps://github.com/hexops/mach↩︎\nhttps://github.com/cgbur/llama2.zig/tree/main↩︎\nhttps://github.com/tigerbeetle/tigerbeetle↩︎\nhttps://github.com/Hejsil/zig-clap↩︎\nhttps://github.com/capy-ui/capy↩︎\nhttps://github.com/zigtools/zls↩︎\nhttps://github.com/mitchellh/libxev↩︎\nhttps://ziglings.org.↩︎\nhttps://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen.↩︎\nhttps://adventofcode.com/↩︎\nhttps://ziglang.org/documentation/master/#Primitive-Types.↩︎\nhttps://www.gnu.org/software/libiconv/↩︎\nhttps://cplusplus.com/reference/cstdio/printf/↩︎\nhttps://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences↩︎\nActually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (foreign function interface), which disables the borrow-checker features through the unsafe keyword.↩︎",
+    "crumbs": [
+      "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/03-structs.html",
+    "href": "Chapters/03-structs.html",
+    "title": "2  Control flow, structs, modules and types",
+    "section": "",
+    "text": "2.1 Control flow\nSometimes, you need to make decisions in your program. Maybe you need to decide whether or not to execute a specific piece of code. Or maybe, you need to apply the same operation over a sequence of values. These kinds of tasks, involve using structures that are capable of changing the “control flow” of our program.\nIn computer science, the term “control flow” usually refers to the order in which expressions (or commands) are evaluated in a given language or program. But this term is also used to refer to structures that are capable of changing this “evaluation order” of the commands executed by a given language/program.\nThese structures are better known by a set of terms, such as: loops, if/else statements, switch statements, among others. So, loops and if/else statements are examples of structures that can change the “control flow” of our program. The keywords continue and break are also examples of symbols that can change the order of evaluation, since they can move our program to the next iteration of a loop, or make the loop stop completely.",
+    "crumbs": [
+      "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/03-structs.html#sec-zig-control-flow",
+    "href": "Chapters/03-structs.html#sec-zig-control-flow",
+    "title": "2  Control flow, structs, modules and types",
+    "section": "",
+    "text": "2.1.1 If/else statements\nAn if/else statement performs a “conditional flow operation”. A conditional flow control (or choice control) allows you to execute or ignore a certain block of commands based on a logical condition. Many programmers and computer science professionals also use the term “branching” in this case. In essence, an if/else statement allow us to use the result of a logical test to decide whether or not to execute a given block of commands.\nIn Zig, we write if/else statements by using the keywords if and else. We start with the if keyword followed by a logical test inside a pair of parentheses, followed by a pair of curly braces which contains the lines of code to be executed in case the logical test returns the value true.\nAfter that, you can optionally add an else statement. To do that, just add the else keyword followed by a pair of curly braces, with the lines of code to executed in case the logical test defined at if returns false.\nIn the example below, we are testing if the object x contains a number that is greater than 10. Judging by the output printed to the console, we know that this logical test returned false. Because the output in the console is compatible with the line of code present in the else branch of the if/else statement.\n\nconst x = 5;\nif (x &gt; 10) {\n    try stdout.print(\n        \"x &gt; 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x &lt;= 10!\\n\", .{}\n    );\n}\n\nx &lt;= 10!\n\n\n\n\n2.1.2 Switch statements\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust. As you would expect, to write a switch statement in Zig we use the switch keyword. We provide the value that we want to “switch over” inside a pair of parentheses. Then, we list the possible combinations (or “branches”) inside a pair of curly braces.\nLet’s take a look at the code example below. You can see that I’m creating an enum type called Role. We talk more about enums in Section 7.6. But in summary, this Role type is listing different types of roles in a fictitious company, like SE for Software Engineer, DE for Data Engineer, PM for Product Manager, etc.\nNotice that we are using the value from the role object in the switch statement, to discover which exact area we need to store in the area variable object. Also notice that we are using type inference inside the switch statement, with the dot character, as we are going to describe in Section 2.4. This makes the zig compiler infer the correct data type of the values (PM, SE, etc.) for us.\nAlso notice that, we are grouping multiple values in the same branch of the switch statement. We just separate each possible value with a comma. For example, if role contains either DE or DA, the area variable would contain the value \"Data & Analytics\", instead of \"Platform\" or \"Sales\".\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO =&gt; {\n            area = \"Platform\";\n        },\n        .DE, .DA =&gt; {\n            area = \"Data & Analytics\";\n        },\n        .KS =&gt; {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n\nPlatform\n\n\n\n2.1.2.1 Switch statements must exhaust all possibilities\nOne very important aspect about switch statements in Zig is that they must exhaust all existing possibilities. In other words, all possible values that could be found inside the role object must be explicitly handled in this switch statement.\nSince the role object has type Role, the only possible values to be found inside this object are PM, SE, DPE, PO, DE, DA and KS. There are no other possible values to be stored in this role object. Thus, the switch statements must have a combination (branch) for each one of these values. This is what “exhaust all existing possibilities” means. The switch statement covers every possible case.\nTherefore, you cannot write a switch statement in Zig, and leave an edge case with no explicit action to be taken. This is a similar behaviour to switch statements in Rust, which also have to handle all possible cases.\n\n\n2.1.2.2 The else branch\nTake a look at the dump_hex_fallible() function below as an example. This function comes from the Zig Standard Library. More precisely, from the debug.zig module1. There are multiple lines in this function, but I omitted them to focus solely on the switch statement found in this function. Notice that this switch statement has four possible cases (i.e. four explicit branches). Also, notice that we used an else branch in this case.\nAn else branch in a switch statement works as the “default branch”. Whenever you have multiple cases in your switch statement where you want to apply the exact same action, you can use an else branch to do that.\n\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' =&gt; try writer.writeAll(\"␊\"),\n        '\\r' =&gt; try writer.writeAll(\"␍\"),\n        '\\t' =&gt; try writer.writeAll(\"␉\"),\n        else =&gt; try writer.writeByte('.'),\n    }\n}\n\nMany programmers would also use an else branch to handle a “not supported” case. That is, a case that cannot be properly handled by your code, or, just a case that should not be “fixed”. Therefore, you can use an else branch to panic (or raise an error) in your program to stop the current execution.\nTake the code example below. We can see that, we are handling the cases for the level object being either 1, 2, or 3. All other possible cases are not supported by default, and, as consequence, we raise a runtime error in such cases through the @panic() built-in function.\nAlso notice that, we are assigning the result of the switch statement to a new object called category. This is another thing that you can do with switch statements in Zig. If a branch outputs a value as result, you can store the result value of the switch statement into a new object.\n\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 =&gt; \"beginner\",\n    3 =&gt; \"professional\",\n    else =&gt; {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n\n\n2.1.2.3 Using ranges in switch\nFurthermore, you can also use ranges of values in switch statements. That is, you can create a branch in your switch statement that is used whenever the input value is within the specified range. These “range expressions” are created with the operator .... It is important to emphasize that the ranges created by this operator are inclusive on both ends.\nFor example, I could easily change the previous code example to support all levels between 0 and 100. Like this:\n\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 =&gt; \"beginner\",\n    26...75 =&gt; \"intermediary\",\n    76...100 =&gt; \"professional\",\n    else =&gt; {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n\nbeginner\n\n\nThis is neat, and it works with character ranges too. That is, I could simply write 'a'...'z', to match any character value that is a lowercase letter, and it would work fine.\n\n\n2.1.2.4 Labeled switch statements\nIn Section 1.7 we have talked about labeling blocks, and also, about using these labels to return a value from the block. Well, from version 0.14.0 and onwards of the zig compiler, you can also apply labels over switch statements, which makes it possible to almost implement a “C goto” like pattern.\nFor example, if you give the label xsw to a switch statement, you can use this label in conjunction with the continue keyword to go back to the beginning of the switch statement. In the example below, the execution goes back to the beginning of the switch statement two times, before ending at the 3 branch.\n\nxsw: switch (@as(u8, 1)) {\n    1 =&gt; {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 =&gt; continue :xsw 3,\n    3 =&gt; return,\n    4 =&gt; {},\n    else =&gt; {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n\n\n\n\n2.1.3 The defer keyword\nWith the defer keyword you can register an expression to be executed when you exit the current scope. Therefore, this keyword has a similar functionality as the on.exit() function from R. Take the foo() function below as an example. When we execute this foo() function, the expression that prints the message “Exiting function …” is getting executed only when the function exits its scope.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n\nAdding some numbers ...\nMultiplying ...\nExiting function ...\nTherefore, we can use defer to declare an expression that is going to be executed when your code exits the current scope. Some programmers like to interpret the phrase “exit of the current scope” as “the end of the current scope”. But this interpretation might not be entirely correct, depending on what you consider as “the end of the current scope”.\nI mean, what do you consider as the end of the current scope? Is it the closing curly bracket (}) of the scope? Is it when the last expression in the function gets executed? Is it when the function returns to the previous scope? Etc. For example, it would not be correct to interpret the “exit of the current scope” as the closing curly bracket of the scope. Because the function might exit from an earlier position than this closing curly bracket (e.g. an error value was generated at a previous line inside the function; the function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\nNow, if you remember of what we have discussed in Section 1.7, there are multiple structures in the language that create their own separate scopes. For/while loops, if/else statements, functions, normal blocks, etc. This also affects the interpretation of defer. For example, if you use defer inside a for loop, then, the given expression will be executed everytime this specific for loop exits its own scope.\nBefore we continue, is worth emphasizing that the defer keyword is an “unconditional defer”. Which means that the given expression will be executed no matter how the code exits the current scope. For example, your code might exit the current scope because of an error value being generated, or, because of a return statement, or, a break statement, etc.\n\n\n2.1.4 The errdefer keyword\nOn the previous section, we have discussed the defer keyword, which you can use to register an expression to be executed at the exit of the current scope. But this keyword has a brother, which is the errdefer keyword. While defer is an “unconditional defer”, the errdefer keyword is a “conditional defer”. Which means that the given expression is executed only when you exit the current scope on a very specific circumstance.\nIn more details, the expression given to errdefer is executed only when an error occurs in the current scope. Therefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope in a normal situation, without errors, the expression given to errdefer is not executed.\nThis makes the errdefer keyword one of the many tools available in Zig for error handling. In this section, we are more concerned with the control flow aspects around errdefer. But we are going to discuss errdefer later as a error handling tool in Section 10.2.4.\nThe code example below demonstrates three things:\n\nthat defer is an “unconditional defer”, because the given expression get’s executed regardless of how the function foo() exits its own scope.\nthat errdefer is executed because the function foo() returned an error value.\nthat defer and errdefer expressions are executed in a LIFO (last in, first out) order.\n\n\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\nWhen I say that “defer expressions” are executed in a LIFO order, what I want to say is that the last defer or errdefer expressions in the code are the first ones to be executed. You could also interpret this as: “defer expressions” are executed from bottom to top, or, from last to first.\nTherefore, if I change the order of the defer and errdefer expressions, you will notice that the value of i that get’s printed to the console changes to 1. This doesn’t mean that the defer expression was not executed in this case. This actually means that the defer expression was executed only after the errdefer expression. The code example below demonstrates this:\n\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n\n\n2.1.5 For loops\nA loop allows you to execute the same lines of code multiple times, thus, creating a “repetition space” in the execution flow of your program. Loops are particularly useful when we want to replicate the same function (or the same set of commands) over different inputs.\nThere are different types of loops available in Zig. But the most essential of them all is probably the for loop. A for loop is used to apply the same piece of code over the elements of a slice, or, an array.\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from other languages. You start with the for keyword, then, you list the items that you want to iterate over inside a pair of parentheses. Then, inside of a pair of pipes (|) you should declare an identifier that will serve as your iterator, or, the “repetition index of the loop”.\n\nfor (items) |value| {\n    // code to execute\n}\n\nTherefore, instead of using a (value in items) syntax, in Zig, for loops use the syntax (items) |value|. In the example below, you can see that we are looping through the items of the array stored at the object name, and printing to the console the decimal representation of each character in this array.\nIf we wanted, we could also iterate through a slice (or a portion) of the array, instead of iterating through the entire array stored in the name object. Just use a range selector to select the section you want. For example, I could provide the expression name[0..3] to the for loop, to iterate just through the first 3 elements in the array.\n\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n\n80 | 101 | 100 | 114 | 111 | \n\n\nIn the above example we are using the value itself of each element in the array as our iterator. But there are many situations where we need to use an index instead of the actual values of the items.\nYou can do that by providing a second set of items to iterate over. More precisely, you provide the range selector 0.. to the for loop. So, yes, you can use two different iterators at the same time in a for loop in Zig.\nBut remember from Section 1.4 that, every object you create in Zig must be used in some way. So if you declare two iterators in your for loop, you must use both iterators inside the for loop body. But if you want to use just the index iterator, and not use the “value iterator”, then, you can discard the value iterator by maching the value items to the underscore character, like in the example below:\n\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n\n0 | 1 | 2 | 3 | 4 |\n\n\n2.1.6 While loops\nA while loop is created from the while keyword. A for loop iterates through the items of an array, but a while loop will loop continuously, and infinitely, until a logical test (specified by you) becomes false.\nYou start with the while keyword, then, you define a logical expression inside a pair of parentheses, and the body of the loop is provided inside a pair of curly braces, like in the example below:\n\nvar i: u8 = 1;\nwhile (i &lt; 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n\n1 | 2 | 3 | 4 | \n\n\nYou can also specify the increment expression to be used at the beginning of a while loop. To do that, we write the increment expression inside a pair of parentheses after a colon character (:). The code example below demonstrates this other pattern.\n\nvar i: u8 = 1;\nwhile (i &lt; 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n\n1 | 2 | 3 | 4 | \n\n\n\n\n2.1.7 Using break and continue\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using the keywords break and continue, respectively. The while loop presented in the next code example is, at first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to true. But what makes this while loop stop when the i object reaches the count 10? It is the break keyword!\nInside the while loop, we have an if statement that is constantly checking if the i variable is equal to 10. Since we are incrementing the value of i at each iteration of the while loop, this i object will eventually be equal to 10, and when it is, the if statement will execute the break expression, and, as a result, the execution of the while loop is stopped.\nNotice the use of the expect() function from the Zig Standard Library after the while loop. This expect() function is an “assert” type of function. This function checks if the logical test provided is equal to true. If so, the function do nothing. Otherwise (i.e. the logical test is equal to false), the function raises an assertion error.\n\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n\nEverything worked!\n\n\nSince this code example was executed successfully by the zig compiler, without raising any errors, we known that, after the execution of the while loop, the i object is equal to 10. Because if it wasn’t equal to 10, an error would have been raised by expect().\nNow, in the next example, we have a use case for the continue keyword. The if statement is constantly checking if the current index is a multiple of 2. If it is, we jump to the next iteration of the loop. Otherwise, the loop just prints the current index to the console.\n\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n\n1 | 3 | 5 |",
+    "crumbs": [
+      "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/03-structs.html#sec-fun-pars",
+    "href": "Chapters/03-structs.html#sec-fun-pars",
+    "title": "2  Control flow, structs, modules and types",
+    "section": "2.2 Function parameters are immutable",
+    "text": "2.2 Function parameters are immutable\nWe have already discussed a lot of the syntax behind function declarations in Section 1.2.2 and Section 1.2.3. But I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig. In summary, function parameters are immutable in Zig.\nTake the code example below, where we declare a simple function that just tries to add some amount to the input integer, and returns the result back. If you look closely at the body of this add2() function, you will notice that we try to save the result back into the x function argument.\nIn other words, this function not only uses the value that it received through the function argument x, but it also tries to change the value of this function argument, by assigning the addition result into x. However, function arguments in Zig are immutable. You cannot change their values, or, you cannot assign values to them inside the body’s function.\nThis is the reason why, the code example below does not compile successfully. If you try to compile this code example, you will get a compile error message about “trying to change the value of a immutable (i.e. constant) object”.\n\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n\n2.2.1 A free optimization\nIf a function argument receives as input an object whose data type is any of the primitive types that we have listed in Section 1.5, this object is always passed by value to the function. In other words, this object is copied into the function stack frame.\nHowever, if the input object have a more complex data type, for example, it might be a struct instance, or an array, or an union value, etc., in cases like that, the zig compiler will take the liberty of deciding for you which strategy is best. Thus, the zig compiler will pass your object to the function either by value, or by reference. The compiler will always choose the strategy that is faster for you. This optimization that you get for free is possible only because function arguments are immutable in Zig.\n\n\n2.2.2 How to overcome this barrier\nThere are some situations where you might need to change the value of your function argument directly inside the function’s body. This happens more often when we are passing C structs as inputs to Zig functions.\nIn a situation like this, you can overcome this barrier by using a pointer. In other words, instead of passing a value as input to the argument, you can pass a “pointer to value” instead. You can change the value that the pointer points to, by dereferencing it.\nTherefore, if we take our previous add2() example, we can change the value of the function argument x inside the function’s body by marking the x argument as a “pointer to a u32 value” (i.e. *u32 data type), instead of a u32 value. By making it a pointer, we can finally alter the value of this function argument directly inside the body of the add2() function. You can see that the code example below compiles successfully.\n\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n\nResult: 6\nEven in this code example above, the x argument is still immutable. Which means that the pointer itself is immutable. Therefore, you cannot change the memory address that it points to. However, you can dereference the pointer to access the value that it points to, and also, to change this value, if you need to.",
+    "crumbs": [
+      "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/03-structs.html#sec-structs-and-oop",
+    "href": "Chapters/03-structs.html#sec-structs-and-oop",
+    "title": "2  Control flow, structs, modules and types",
+    "section": "2.3 Structs and OOP",
+    "text": "2.3 Structs and OOP\nZig is a language more closely related to C (which is a procedural language), than it is to C++ or Java (which are object-oriented languages). Because of that, you do not have advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or class inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C. You give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can also register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object that you create with this new type, will always have these methods available and associated with them.\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which is used to construct (or, to instantiate) every object of this particular class, and we also have a destructor method (or a destructor function), which is the function responsible for destroying every object of this class.\nIn Zig, we normally declare the constructor and the destructor methods of our structs, by declaring an init() and a deinit() methods inside the struct. This is just a naming convention that you will find across the entire Zig Standard Library. So, in Zig, the init() method of a struct is normally the constructor method of the class represented by this struct. While the deinit() method is the method used for destroying an existing instance of that struct.\nThe init() and deinit() methods are both used extensively in Zig code, and you will see both of them being used when we talk about allocators in Section 3.3. But, as another example, let’s build a simple User struct to represent a user of some sort of system.\nIf you look at the User struct below, you can see the struct keyword. Notice the data members of this struct: id, name and email. Every data member has its type explicitly annotated, with the colon character (:) syntax that we described earlier in Section 1.2.2. But also notice that every line in the struct body that describes a data member, ends with a comma character (,). So every time you declare a data member in your Zig code, always end the line with a comma character, instead of ending it with the traditional semicolon character (;).\nNext, we have registered an init() function as a method of this User struct. This init() method is the constructor method that we will use to instantiate every new User object. That is why this init() function returns a new User object as result.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    pub fn init(id: u64,\n                name: []const u8,\n                email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    pub fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n\npedro\n\n\nThe pub keyword plays an important role in struct declarations, and OOP in Zig. Every method that you declare in your struct that is marked with the keyword pub, becomes a public method of this particular struct.\nSo every method that you create inside your struct, is, at first, a private method of that struct. Meaning that, this method can only be called from within this struct. But, if you mark this method as public, with the keyword pub, then, you can call the method directly from an instance of the User struct.\nIn other words, the functions marked by the keyword pub are members of the public API of that struct. For example, if I did not mark the print_name() method as public, then, I could not execute the line u.print_name(). Because I would not be authorized to call this method directly in my code.\n\n2.3.1 Anonymous struct literals\nYou can declare a struct object as a literal value. When we do that, we normally specify the data type of this struct literal by writing its data type just before the opening curly brace. For example, I could write a struct literal value of the type User that we have defined in the previous section like this:\n\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a struct literal, but not specify explicitly the type of this particular struct. An anonymous struct is written by using the syntax .{}. So, we essentially replaced the explicit type of the struct literal with a dot character (.).\nAs we described in Section 2.4, when you put a dot before a struct literal, the type of this struct literal is automatically inferred by the zig compiler. In essence, the zig compiler will look for some hint of what is the type of that struct. This hint can be the type annotation of a function argument, or the return type annotation of the function that you are using, or the type annotation of an existing object. If the compiler does find such type annotation, it will use this type in your literal struct.\nAnonymous structs are very commonly used as inputs to function arguments in Zig. One example that you have seen already constantly, is the print() function from the stdout object. This function takes two arguments. The first argument, is a template string, which should contain string format specifiers in it, which tells how the values provided in the second argument should be printed into the message.\nWhile the second argument is a struct literal that lists the values to be printed into the template message specified in the first argument. You normally want to use an anonymous struct literal here, so that the zig compiler do the job of specifying the type of this particular anonymous struct for you.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n\nHello, world!\n\n\n\n\n2.3.2 Struct declarations must be constant\nTypes in Zig must be const or comptime (we are going to talk more about comptime in Section 12.1). What this means is that you cannot create a new data type, and mark it as variable with the var keyword. So struct declarations are always constant. You cannot declare a new struct type using the var keyword. It must be const.\nIn the Vec3 example below, this declaration is allowed because I’m using the const keyword to declare this new data type.\n\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n\n\n\n2.3.3 The self method argument\nIn every language that have OOP, when we declare a method of some class or struct, we usually declare this method as a function that has a self argument. This self argument is the reference to the object itself from which the method is being called from.\nIt is not mandatory to use this self argument. But why would you not use this self argument? There is no reason to not use it. Because the only way to get access to the data stored in the data members of your struct is to access them through this self argument. If you don’t need to use the data in the data members of your struct inside your method, you very likely don’t need a method. You can just declare this logic as a simple function, outside of your struct declaration.\nTake the Vec3 struct below. Inside this Vec3 struct we declared a method named distance(). This method calculates the distance between two Vec3 objects, by following the distance formula in euclidean space. Notice that this distance() method takes two Vec3 objects as input, self and other.\n\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n\nThe self argument corresponds to the Vec3 object from which this distance() method is being called from. While the other is a separate Vec3 object that is given as input to this method. In the example below, the self argument corresponds to the object v1, because the distance() method is being called from the v1 object, while the other argument corresponds to the object v2.\n\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n\nDistance: 3.3970575502926055\n\n\n2.3.4 About the struct state\nSometimes you don’t need to care about the state of your struct object. Sometimes, you just need to instantiate and use the objects, without altering their state. You can notice that when you have methods inside your struct declaration that might use the values that are present in the data members, but they do not alter the values in these data members of the struct in anyway.\nThe Vec3 struct that was presented in Section 2.3.3 is an example of that. This struct have a single method named distance(), and this method does use the values present in all three data members of the struct (x, y and z). But at the same time, this method does not change the values of these data members at any point.\nAs a result of that, when we create Vec3 objects we usually create them as constant objects, like the v1 and v2 objects presented in Section 2.3.3. We can create them as variable objects with the var keyword, if we want to. But because the methods of this Vec3 struct do not change the state of the objects in any point, it’s unnecessary to mark them as variable objects.\nBut why? Why am I talking about this here? It’s because the self argument in the methods are affected depending on whether the methods present in a struct change or don’t change the state of the object itself. More specifically, when you have a method in a struct that changes the state of the object (i.e. changes the value of a data member), the self argument in this method must be annotated in a different manner.\nAs I described in Section 2.3.3, the self argument in methods of a struct is the argument that receives as input the object from which the method was called from. We usually annotate this argument in the methods by writing self, followed by the colon character (:), and the data type of the struct to which the method belongs to (e.g. User, Vec3, etc.).\nIf we take the Vec3 struct that we defined in the previous section as an example, we can see in the distance() method that this self argument is annotated as self: Vec3. Because the state of the Vec3 object is never altered by this method.\nBut what if we do have a method that alters the state of the object, by altering the values of its data members, how should we annotate self in this instance? The answer is: “we should annotate self as a pointer of x, instead of just x”. In other words, you should annotate self as self: *x, instead of annotating it as self: x.\nIf we create a new method inside the Vec3 object that, for example, expands the vector by multiplying its coordinates by a factor of two, then, we need to follow this rule specified in the previous paragraph. The code example below demonstrates this idea:\n\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n\nNotice in the code example above that we have added a new method to our Vec3 struct named twice(). This method doubles the coordinate values of our vector object. In the case of the twice() method, we annotated the self argument as *Vec3, indicating that this argument receives a pointer (or a reference, if you prefer to call it this way) to a Vec3 object as input.\n\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n\nDoubled: 8.4\nNow, if you change the self argument in this twice() method to self: Vec3, like in the distance() method, you will get the compiler error exposed below as result. Notice that this error message is showing a line from the twice() method body, indicating that you cannot alter the value of the x data member.\n\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\nThis error message indicates that the x data member belongs to a constant object, and, because of that, it cannot be changed. Ultimately, this error message is telling us that the self argument is constant.\nIf you take some time, and think hard about this error message, you will understand it. You already have the tools to understand why we are getting this error message. We have talked about it already in Section 2.2. So remember, every function argument is immutable in Zig, and self is no exception to this rule.\nIn this example, we marked the v3 object as a variable object. But this does not matter. Because it is not about the input object, it is about the function argument.\nThe problem begins when we try to alter the value of self directly, which is a function argument, and, every function argument is immutable by default. You may ask yourself how can we overcome this barrier, and once again, the solution was also discussed in Section 2.2. We overcome this barrier, by explicitly marking the self argument as a pointer.\n\n\n\n\n\n\nNote\n\n\n\nIf a method of your x struct alters the state of the object, by changing the value of any data member, then, remember to use self: *x, instead of self: x in the function signature of this method.\n\n\nYou could also interpret the content discussed in this section as: “if you need to alter the state of your x struct object in one of its methods, you must explicitly pass the x struct object by reference to the self argument of this method”.",
+    "crumbs": [
+      "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/03-structs.html#sec-type-inference",
+    "href": "Chapters/03-structs.html#sec-type-inference",
+    "title": "2  Control flow, structs, modules and types",
+    "section": "2.4 Type inference",
+    "text": "2.4 Type inference\nZig is a strongly typed language. But, there are some situations where you don’t have to explicitly write the type of every single object in your source code, as you would expect from a traditional strongly typed language, such as C and C++.\nIn some situations, the zig compiler can use type inference to solve the data types for you, easing some of the burden that you carry as a developer. The most common way this happens is through function arguments that receive struct objects as input.\nIn general, type inference in Zig is done by using the dot character (.). Everytime you see a dot character written before a struct literal, or before an enum value, or something like that, you know that this dot character is playing a special part in this place. More specifically, it is telling the zig compiler something along the lines of: “Hey! Can you infer the type of this value for me? Please!”. In other words, this dot character is playing a similar role as the auto keyword in C++.\nI gave you some examples of this in Section 2.3.1, where we used anonymous struct literals. Anonymous struct literals are, struct literals that use type inference to infer the exact type of this particular struct literal. This type inference is done by looking for some minimal hint of the correct data type to be used. You could say that the zig compiler looks for any neighbouring type annotation that might tell it what the correct type would be.\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in Section 2.1.2). I also gave some other examples of type inference in Section 2.1.2, where we were inferring the data types of enum values listed inside of switch statements (e.g. .DE). But as another example, take a look at this fence() function reproduced below, which comes from the atomic.zig module2 of the Zig Standard Library.\nThere are a lot of things in this function that we haven’t talked about yet, such as: what comptime means? inline? extern? Let’s just ignore all of these things, and focus solely on the switch statement that is inside this function.\nWe can see that this switch statement uses the order object as input. This order object is one of the inputs of this fence() function, and we can see in the type annotation, that this object is of type AtomicOrder. We can also see a bunch of values inside the switch statements that begin with a dot character, such as .release and .acquire.\nBecause these weird values contain a dot character before them, we are asking the zig compiler to infer the types of these values inside the switch statement. Then, the zig compiler is looking into the current context where these values are being used, and it is trying to infer the types of these values.\nSince they are being used inside a switch statement, the zig compiler looks into the type of the input object given to the switch statement, which is the order object in this case. Because this object have type AtomicOrder, the zig compiler infers that these values are data members from this type AtomicOrder.\n\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic =&gt; @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire =&gt; tsan.__tsan_acquire(addr),\n            .release =&gt; tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst =&gt; {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n\nThis is how basic type inference is done in Zig. If we didn’t use the dot character before the values inside this switch statement, then, we would be forced to explicitly write the data types of these values. For example, instead of writing .release we would have to write AtomicOrder.release. We would have to do this for every single value in this switch statement, and this is a lot of work. That is why type inference is commonly used on switch statements in Zig.",
+    "crumbs": [
+      "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/03-structs.html#sec-type-cast",
+    "href": "Chapters/03-structs.html#sec-type-cast",
+    "title": "2  Control flow, structs, modules and types",
+    "section": "2.5 Type casting",
+    "text": "2.5 Type casting\nIn this section, I want to discuss type casting (or, type conversion) with you. We use type casting when we have an object of type “x”, and we want to convert it into an object of type “y”, i.e. we want to change the data type of the object.\nMost languages have a formal way to perform type casting. In Rust for example, we normally use the keyword as, and in C, we normally use the type casting syntax, e.g. (int) x. In Zig, we use the @as() built-in function to cast an object of type “x”, into an object of type “y”.\nThis @as() function is the preferred way to perform type conversion (or type casting) in Zig. Because it is explicit, and, it also performs the casting only if it is unambiguous and safe. To use this function, you just provide the target data type in the first argument, and, the object that you want cast as the second argument.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n\n1/1 file2ed34a8fc96.test_0...OKAll 1 tests passed.\n\n\nThis is the general way to perform type casting in Zig. But remember, @as() works only when casting is unambiguous and safe, and there are situations where these assumptions do not hold. For example, when casting an integer value into a float value, or vice-versa, it is not clear to the compiler how to perform this conversion safely.\nTherefore, we need to use specialized “casting functions” in such situations. For example, if you want to cast an integer value into a float value, then, you should use the @floatFromInt() function. In the inverse scenario, you should use the @intFromFloat() function.\nIn these functions, you just provide the object that you want to cast as input. Then, the target data type of the “type casting operation” is determined by the type annotation of the object where you are saving the results. In the example below, we are casting the object x into a value of type f32, because the object y, which is where we are saving the results, is annotated as an object of type f32.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n\n1/1 file2ed34bfb9fa5.test_0...OKAll 1 tests passed\n  d.\n\n\nAnother built-in function that is very useful when performing type casting operations is @ptrCast(). In essence, we use the @as() built-in function when we want to explicit convert (or cast) a Zig value/object from a type “x” to a type “y”, etc. However, pointers (we are going to discuss pointers in more depth in Chapter 6) are a special type of object in Zig, i.e. they are treated differently from “normal objects”.\nEverytime a pointer is involved in some “type casting operation” in Zig, the @ptrCast() function is used. This function works similarly to @floatFromInt(). You just provide the pointer object that you want to cast as input to this function, and the target data type is, once again, determined by the type annotation of the object where the results are being stored.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n\n1/1 file2ed324328e1f.test_0...OKAll 1 tests passed\n  d.",
+    "crumbs": [
+      "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/03-structs.html#modules",
+    "href": "Chapters/03-structs.html#modules",
+    "title": "2  Control flow, structs, modules and types",
+    "section": "2.6 Modules",
+    "text": "2.6 Modules\nWe already talked about what modules are, and also, how to import other modules into your current module via import statements. Every Zig module (i.e. a .zig file) that you write in your project is internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the Zig Standard Library into our current module.\n\nconst std = @import(\"std\");\n\nWhen we want to access the functions and objects from the standard library, we are basically accessing the data members of the struct stored in the std object. That is why we use the same syntax that we use in normal structs, with the dot operator (.) to access the data members and methods of the struct.\nWhen this “import statement” get’s executed, the result of this expression is a struct object that contains the Zig Standard Library modules, global variables, functions, etc. And this struct object get’s saved (or stored) inside the constant object named std.\nTake the thread_pool.zig module from the project zap3 as an example. This module is written as if it was a big struct. That is why we have a top-level and public init() method written in this module. The idea is that all top-level functions written in this module are methods from the struct, and all top-level objects and struct declarations are data members of this struct. The module is the struct itself.\nSo you would import and use this module by doing something like this:\n\nconst std = @import(\"std\");\nconst ThreadPool = @import(\"thread_pool.zig\");\nconst num_cpus = std.Thread.getCpuCount()\n    catch @panic(\"failed to get cpu core count\");\nconst num_threads = std.math.cast(u16, num_cpus)\n    catch std.math.maxInt(u16);\nconst pool = ThreadPool.init(\n    .{ .max_threads = num_threads }\n);",
+    "crumbs": [
+      "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/03-structs.html#footnotes",
+    "href": "Chapters/03-structs.html#footnotes",
+    "title": "2  Control flow, structs, modules and types",
+    "section": "",
+    "text": "https://github.com/ziglang/zig/blob/master/lib/std/debug.zig↩︎\nhttps://github.com/ziglang/zig/blob/master/lib/std/atomic.zig.↩︎\nhttps://github.com/kprotty/zap/blob/blog/src/thread_pool.zig↩︎",
+    "crumbs": [
+      "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/01-memory.html",
+    "href": "Chapters/01-memory.html",
+    "title": "3  Memory and Allocators",
+    "section": "",
+    "text": "3.1 Memory spaces\nEvery object that you create in your Zig source code needs to be stored somewhere, in your computer’s memory. Depending on where and how you define your object, Zig will use a different “memory space”, or a different type of memory to store this object.\nEach type of memory normally serves for different purposes. In Zig, there are 3 types of memory (or 3 different memory spaces) that we care about. They are:",
+    "crumbs": [
+      "<span class='chapter-number'>3</span>  <span class='chapter-title'>Memory and Allocators</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/01-memory.html#memory-spaces",
+    "href": "Chapters/01-memory.html#memory-spaces",
+    "title": "3  Memory and Allocators",
+    "section": "",
+    "text": "Global data register (or the “global data section”);\nStack;\nHeap;\n\n\n3.1.1 Compile-time known versus runtime known\nOne strategy that Zig uses to decide where it will store each object that you declare, is by looking at the value of this particular object. More specifically, by investigating if this value is known at “compile-time” or at “runtime”.\nWhen you write a program in Zig, the values of some of the objects that you write in your program are known at compile time. Meaning that, when you compile your Zig source code, during the compilation process, the zig compiler can figure out the exact value of a particular object that exists in your source code. Knowing the length (or the size) of each object is also important. So the length (or the size) of each object that you write in your program is, in some cases, known at compile time.\nThe zig compiler cares more about knowing the length (or the size) of a particular object , than to know its actual value. But, if the zig compiler knows the value of the object, then, it automatically knows the size of this object. Because it can simply calculate the size of the object by looking at the size of the value.\nTherefore, the priority for the zig compiler is to discover the size of each object in your source code. If the value of the object in question is known at compile-time, then, the zig compiler automatically knows the size/length of this object. But if the value of this object is not known at compile-time, then, the size of this object is only known at compile-time if, and only if, the type of this object has a known fixed size.\nIn order for a type to have a known fixed size, this type must have data members whose size is fixed. If this type includes, for example, a variable sized array in it, then, this type does not have a known fixed size. Because this array can have any size at runtime (i.e. it can be an array of 2 elements, or 50 elements, or 1 thousand elements, etc.).\nFor example, a string object, which internally is an array of constant u8 values ([]const u8) has a variable size. It can be a string object with 100 or 500 characters in it. If we do not know at compile-time, which exact string will be stored inside this string object, then, we cannot calculate the size of this string object at compile-time. So, any type, or any struct declaration that you make, that includes a string data member that does not have an explicit fixed size, makes this type, or this new struct that you are declaring, a type that does not have a known fixed size at compile-time.\nIn contrast, if the type of this struct that you are declaring, includes a data member that is an array, but this array has a known fixed size, like [60]u8 (which declares an array of 60 u8 values), then, this type, or, this struct that you are declaring, becomes a type with a known fixed size at compile-time. And because of that, in this case, the zig compiler does not need to know at compile-time the exact value of any object of this type. Since the compiler can find the necessary size to store this object by looking at the size of its type.\nLet’s look at an example. In the source code below, we have two constant objects (name and array) declared. Because the values of these particular objects are written down, in the source code itself (\"Pedro\" and the number sequence from 1 to 4), the zig compiler can easily discover the values of these constant objects (name and array) during the compilation process. This is what “known at compile time” means. It refers to any object that you have in your Zig source code whose value can be identified at compile time.\n\nfn input_length(input: []const u8) usize {\n    const n = input.len;\n    return n;\n}\n\npub fn main() !void {\n    const name = \"Pedro\";\n    const array = [_]u8{1, 2, 3, 4};\n    _ = name; _ = array;\n}\n\nThe other side of the spectrum are objects whose values are not known at compile time. Function arguments are a classic example of this. Because the value of each function argument depends on the value that you assign to this particular argument, when you call the function.\nFor example, the function input_length() contains an argument named input, which is an array of constant u8 integers ([]const u8). It is impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length of this particular argument. Because it is an array that do not have a fixed size specified explicitly in the argument type annotation.\nSo, we know that this input argument will be an array of u8 integers. But we do not know at compile-time, its value, and neither its size. This information is known only at runtime, which is the period of time when you program is executed. As a consequence, the value of the expression input.len is also known only at runtime. This is an intrinsic characteristic of any function. Just remember that the value of function arguments is usually not “compile-time known”.\nHowever, as I mentioned earlier, what really matters to the compiler is to know the size of the object at compile-time, and not necessarily its value. So, although we don’t know the value of the object n, which is the result of the expression input.len, at compile-time, we do know its size. Because the expression input.len always returns a value of type usize, and the type usize has a known fixed size.\n\n\n3.1.2 Global data register\nThe global data register is a specific section of the executable of your Zig program, that is responsible for storing any value that is known at compile time.\nEvery constant object whose value is known at compile time that you declare in your source code, is stored in the global data register. Also, every literal value that you write in your source code, such as the string \"this is a string\", or the integer 10, or a boolean value such as true, is also stored in the global data register.\nHonestly, you don’t need to care much about this memory space. Because you can’t control it, you can’t deliberately access it or use it for your own purposes. Also, this memory space does not affect the logic of your program. It simply exists in your program.\n\n\n3.1.3 Stack vs Heap\nIf you are familiar with systems programming, or just low-level programming in general, you probably have heard of the “duel” between Stack vs Heap. These are two different types of memory, or different memory spaces, which are both available in Zig.\nThese two types of memory don’t actually duel with each other. This is a common mistake that beginners have, when seeing “x vs y” styles of tabloid headlines. These two types of memory are actually complementary to each other. So, in almost every Zig program that you ever write, you will likely use a combination of both. I will describe each memory space in detail over the next sections. But for now, I just want to stablish the main difference between these two types of memory.\nIn essence, the stack memory is normally used to store values whose length is fixed and known at compile time. In contrast, the heap memory is a dynamic type of memory space, meaning that, it is used to store values whose length might grow during the execution (runtime) of your program (Chen and Guo 2022).\nLengths that grow during runtime are intrinsically associated with “runtime known” type of values. In other words, if you have an object whose length might grow during runtime, then, the length of this object becomes not known at compile time. If the length is not known at compile-time, the value of this object also becomes not known at compile-time. These types of objects should be stored in the heap memory space, which is a dynamic memory space, which can grow or shrink to fit the size of your objects.\n\n\n3.1.4 Stack\nThe stack is a type of memory that uses the power of the stack data structure, hence the name. A “stack” is a type of data structure that uses a “last in, first out” (LIFO) mechanism to store the values you give it to. I imagine you are familiar with this data structure. But, if you are not, the Wikipedia page1 , or, the Geeks For Geeks page2 are both excellent and easy resources to fully understand how this data structure works.\nSo, the stack memory space is a type of memory that stores values using a stack data structure. It adds and removes values from the memory by following a “last in, first out” (LIFO) principle.\nEvery time you make a function call in Zig, an amount of space in the stack is reserved for this particular function call (Chen and Guo 2022; Zig Software Foundation 2024). The value of each function argument given to the function in this function call is stored in this stack space. Also, every local object that you declare inside the function scope is usually stored in this same stack space.\nLooking at the example below, the object result is a local object declared inside the scope of the add() function. Because of that, this object is stored inside the stack space reserved for the add() function. The r object (which is declared outside of the add() function scope) is also stored in the stack. But since it is declared in the “outer” scope, this object is stored in the stack space that belongs to this outer scope.\n\nfn add(x: u8, y: u8) u8 {\n    const result = x + y;\n    return result;\n}\n\npub fn main() !void {\n    const r = add(5, 27);\n    _ = r;\n}\n\nSo, any object that you declare inside the scope of a function is always stored inside the space that was reserved for that particular function in the stack memory. This also counts for any object declared inside the scope of your main() function for example. As you would expect, in this case, they are stored inside the stack space reserved for the main() function.\nOne very important detail about the stack memory is that it frees itself automatically. This is very important, remember that. When objects are stored in the stack memory, you don’t have the work (or the responsibility) of freeing/destroying these objects. Because they will be automatically destroyed once the stack space is freed at the end of the function scope.\nSo, once the function call returns (or ends, if you prefer to call it this way) the space that was reserved in the stack is destroyed, and all of the objects that were in that space goes away with it. This mechanism exists because this space, and the objects within it, are not necessary anymore, since the function “finished its business”. Using the add() function that we exposed above as an example, it means that the object result is automatically destroyed once the function returns.\n\n\n\n\n\n\nImportant\n\n\n\nLocal objects that are stored in the stack space of a function are automatically freed/destroyed at the end of the function scope.\n\n\nThis same logic applies to any other special structure in Zig that has its own scope by surrounding it with curly braces ({}). For loops, while loops, if else statements, etc. For example, if you declare any local object in the scope of a for loop, this local object is accessible only within the scope of this particular for loop. Because once the scope of this for loop ends, the space in the stack reserved for this for loop is freed. The example below demonstrates this idea.\n\n// This does not compile successfully!\nconst a = [_]u8{0, 1, 2, 3, 4};\nfor (0..a.len) |i| {\n    const index = i;\n    _ = index;\n}\n// Trying to use an object that was\n// declared in the for loop scope,\n// and that does not exist anymore.\nstd.debug.print(\"{d}\\n\", .{index});\n\nOne important consequence of this mechanism is that, once the function returns, you can no longer access any memory address that was inside the space in the stack reserved for this particular function. Because this space was destroyed. This means that, if this local object is stored in the stack, you cannot make a function that returns a pointer to this object.\nThink about that for a second. If all local objects in the stack are destroyed at the end of the function scope, why would you even consider returning a pointer to one of these objects? This pointer is at best, invalid, or, more likely, “undefined”.\nConclusion, it is totally fine to write a function that returns the local object itself as result, because then, you return the value of that object as the result. But, if this local object is stored in the stack, you should never write a function that returns a pointer to this local object. Because the memory address pointed by the pointer no longer exists.\nSo, using again the add() function as an example, if you rewrite this function so that it returns a pointer to the local object result, the zig compiler will actually compile your program, with no warnings or errors. At first glance, it looks that this is good code that works as expected. But this is a lie!\nIf you try to take a look at the value inside of the r object, or, if you try to use this r object in another expression or function call, then, you would have undefined behaviour, and major bugs in your program (Zig Software Foundation 2024, see “Lifetime and Ownership”3 and “Undefined Behaviour”4 sections).\n\nfn add(x: u8, y: u8) *const u8 {\n    const result = x + y;\n    return &result;\n}\n\npub fn main() !void {\n    // This code compiles successfully. But it has\n    // undefined behaviour. Never do this!!!\n    // The `r` object is undefined!\n    const r = add(5, 27); _ = r;\n}\n\nThis “invalid pointer to stack variable” problem is well known across many programming language communities. If you try to do the same thing, for example, in a C or C++ program (i.e. returning an address to a local object stored in the stack), you would also get undefined behaviour in the program.\n\n\n\n\n\n\nImportant\n\n\n\nIf a local object in your function is stored in the stack, you should never return a pointer to this local object from the function. Because this pointer will always become undefined after the function returns, since the stack space of the function is destroyed at the end of its scope.\n\n\nBut what if you really need to use this local object in some way after your function returns? How can you do this? The answer is: “in the same way you would do if this were a C or C++ program. By returning an address to an object stored in the heap”. The heap memory has a much more flexible lifecycle, and allows you to get a valid pointer to a local object of a function that already returned from its scope.\n\n\n3.1.5 Heap\nOne important limitation of the stack, is that, only objects whose length/size is known at compile-time can be stored in it. In contrast, the heap is a much more dynamic (and flexible) type of memory. It is the perfect type of memory to use for objects whose size/length might grow during the execution of your program.\nVirtually any application that behaves as a server is a classic use case of the heap. A HTTP server, a SSH server, a DNS server, a LSP server, … any type of server. In summary, a server is a type of application that runs for long periods of time, and that serves (or “deals with”) any incoming request that reaches this particular server.\nThe heap is a good choice for this type of system, mainly because the server does not know upfront how many requests it will receive from users, while it is active. It could be a single request, 5 thousand requests, or even zero requests. The server needs to have the ability to allocate and manage its memory according to how many requests it receives.\nAnother key difference between the stack and the heap, is that the heap is a type of memory that you, the programmer, have complete control over. This makes the heap a more flexible type of memory, but it also makes it harder to work with. Because you, the programmer, is responsible for managing everything related to it. Including where the memory is allocated, how much memory is allocated, and where this memory is freed.\n\nUnlike stack memory, heap memory is allocated explicitly by programmers and it won’t be deallocated until it is explicitly freed (Chen and Guo 2022).\n\nTo store an object in the heap, you, the programmer, needs to explicitly tells Zig to do so, by using an allocator to allocate some space in the heap. At Section 3.3, I will present how you can use allocators to allocate memory in Zig.\n\n\n\n\n\n\nImportant\n\n\n\nEvery memory you allocate in the heap needs to be explicitly freed by you, the programmer.\n\n\nThe majority of allocators in Zig do allocate memory on the heap. But some exceptions to this rule are ArenaAllocator() and FixedBufferAllocator(). The ArenaAllocator() is a special type of allocator that works in conjunction with a second type of allocator. On the other side, the FixedBufferAllocator() is an allocator that works based on buffer objects created on the stack. This means that the FixedBufferAllocator() makes allocations only on the stack.\n\n\n3.1.6 Summary\nAfter discussing all of these boring details, we can quickly recap what we learned. In summary, the Zig compiler will use the following rules to decide where each object you declare is stored:\n\nevery literal value (such as \"this is string\", 10, or true) is stored in the global data section.\nevery constant object (const) whose value is known at compile-time is also stored in the global data section.\nevery object (constant or not) whose length/size is known at compile time is stored in the stack space for the current scope.\nif an object is created with the method alloc() or create() of an allocator object, this object is stored in the memory space used by this particular allocator object. Most of allocators available in Zig use the heap memory, so, this object is likely stored in the heap (FixedBufferAllocator() is an exception to that).\nthe heap can only be accessed through allocators. If your object was not created through the alloc() or create() methods of an allocator object, then, it is most certainly not an object stored in the heap.",
+    "crumbs": [
+      "<span class='chapter-number'>3</span>  <span class='chapter-title'>Memory and Allocators</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/01-memory.html#sec-stack-overflow",
+    "href": "Chapters/01-memory.html#sec-stack-overflow",
+    "title": "3  Memory and Allocators",
+    "section": "3.2 Stack overflows",
+    "text": "3.2 Stack overflows\nAllocating memory on the stack is generally faster than allocating it on the heap. But this better performance comes with many restrictions. We have already discussed many of these restrictions of the stack at Section 3.1.4. But there is one more important limitation that I want to talk about, which is the size of the stack itself.\nThe stack is limited in size. This size varies from computer to computer, and it depends on a lot of things (the computer architecture, the operating system, etc.). Nevertheless, this size is usually not that big. This is why we normally use the stack to store only temporary and small objects in memory.\nIn essence, if you try to make an allocation on the stack, that is so big that exceeds the stack size limit, a stack overflow happens, and your program just crashes as a result of that. In other words, a stack overflow happens when you attempt to use more space than is available on the stack.\nThis type of problem is very similar to a buffer overflow, i.e. you are trying to use more space than is available in the “buffer object”. However, a stack overflow always causes your program to crash, while a buffer overflow does not always cause your program to crash (although it often does).\nYou can see an example of a stack overflow in the example below. We are trying to allocate a very big array of u64 values on the stack. You can see below that this program does not run successfully, because it crashed with a “segmentation fault” error message.\n\nvar very_big_alloc: [1000 * 1000 * 24]u64 = undefined;\n@memset(very_big_alloc[0..], 0);\n\nSegmentation fault (core dumped)\nThis segmentation fault error is a result of the stack overflow that was caused by the big memory allocation made on the stack, to store the very_big_alloc object. This is why very big objects are usually stored on the heap, instead of the stack.",
+    "crumbs": [
+      "<span class='chapter-number'>3</span>  <span class='chapter-title'>Memory and Allocators</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/01-memory.html#sec-allocators",
+    "href": "Chapters/01-memory.html#sec-allocators",
+    "title": "3  Memory and Allocators",
+    "section": "3.3 Allocators",
+    "text": "3.3 Allocators\nOne key aspect about Zig, is that there are “no hidden-memory allocations” in Zig. What that really means, is that “no allocations happen behind your back in the standard library” (Sobeston 2024).\nThis is a known problem, especially in C++. Because in C++, there are some operators that do allocate memory behind the scene, and there is no way for you to know that, until you actually read the source code of these operators, and find the memory allocation calls. Many programmers find this behaviour annoying and hard to keep track of.\nBut, in Zig, if a function, an operator, or anything from the standard library needs to allocate some memory during its execution, then, this function/operator needs to receive (as input) an allocator provided by the user, to actually be able to allocate the memory it needs.\nThis creates a clear distinction between functions that “do not” from those that “actually do” allocate memory. Just look at the arguments of this function. If a function, or operator, has an allocator object as one of its inputs/arguments, then, you know for sure that this function/operator will allocate some memory during its execution.\nAn example is the allocPrint() function from the Zig Standard Library. With this function, you can write a new string using format specifiers. So, this function is, for example, very similar to the function sprintf() in C. In order to write such a new string, the allocPrint() function needs to allocate some memory to store the output string.\nThat is why, the first argument of this function is an allocator object that you, the user/programmer, gives as input to the function. In the example below, I am using the GeneralPurposeAllocator() as my allocator object. But I could easily use any other type of allocator object from the Zig Standard Library.\n\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst name = \"Pedro\";\nconst output = try std.fmt.allocPrint(\n    allocator,\n    \"Hello {s}!!!\",\n    .{name}\n);\ntry stdout.print(\"{s}\\n\", .{output});\n\nHello Pedro!!!\n\n\nYou get a lot of control over where and how much memory this function can allocate. Because it is you, the user/programmer, that provides the allocator for the function to use. This makes “total control” over memory management easier to achieve in Zig.\n\n3.3.1 What are allocators?\nAllocators in Zig are objects that you can use to allocate memory for your program. They are similar to the memory allocating functions in C, like malloc() and calloc(). So, if you need to use more memory than you initially have, during the execution of your program, you can simply ask for more memory by using an allocator object.\nZig offers different types of allocators, and they are usually available through the std.heap module of the standard library. Thus, just import the Zig Standard Library into your Zig module (with @import(\"std\")), and you can start using these allocators in your code.\nFurthermore, every allocator object is built on top of the Allocator interface in Zig. This means that, every allocator object you find in Zig must have the methods alloc(), create(), free() and destroy(). So, you can change the type of allocator you are using, but you don’t need to change the function calls to the methods that do the memory allocation (and the free memory operations) for your program.\n\n\n3.3.2 Why you need an allocator?\nAs we described at Section 3.1.4, everytime you make a function call in Zig, a space in the stack is reserved for this function call. But the stack has a key limitation which is: every object stored in the stack has a known fixed length.\nBut in reality, there are two very common instances where this “fixed length limitation” of the stack is a deal braker:\n\nthe objects that you create inside your function might grow in size during the execution of the function.\nsometimes, it is impossible to know upfront how many inputs you will receive, or how big this input will be.\n\nAlso, there is another instance where you might want to use an allocator, which is when you want to write a function that returns a pointer to a local object. As I described at Section 3.1.4, you cannot do that if this local object is stored in the stack. However, if this object is stored in the heap, then, you can return a pointer to this object at the end of the function. Because you (the programmer) control the lifetime of any heap memory that you allocate. You decide when this memory gets destroyed/freed.\nThese are common situations for which the stack is not good. That is why you need a different memory management strategy to store these objects inside your function. You need to use a memory type that can grow together with your objects, or that you can control the lifetime of this memory. The heap fits this description.\nAllocating memory on the heap is commonly known as dynamic memory management. As the objects you create grow in size during the execution of your program, you grow the amount of memory you have by allocating more memory in the heap to store these objects. And you do that in Zig, by using an allocator object.\n\n\n3.3.3 The different types of allocators\nAt the moment of the writing of this book, in Zig, we have 6 different allocators available in the standard library:\n\nGeneralPurposeAllocator().\npage_allocator().\nFixedBufferAllocator() and ThreadSafeFixedBufferAllocator().\nArenaAllocator().\nc_allocator() (requires you to link to libc).\n\nEach allocator has its own perks and limitations. All allocators, except FixedBufferAllocator() and ArenaAllocator(), are allocators that use the heap memory. So any memory that you allocate with these allocators, will be placed in the heap.\n\n\n3.3.4 General-purpose allocators\nThe GeneralPurposeAllocator(), as the name suggests, is a “general purpose” allocator. You can use it for every type of task. In the example below, I’m allocating enough space to store a single integer in the object some_number.\n\nconst std = @import(\"std\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const some_number = try allocator.create(u32);\n    defer allocator.destroy(some_number);\n\n    some_number.* = @as(u32, 45);\n}\n\nWhile useful, you might want to use the c_allocator(), which is a alias to the C standard allocator malloc(). So, yes, you can use malloc() in Zig if you want to. Just use the c_allocator() from the Zig standard library. However, if you do use c_allocator(), you must link to Libc when compiling your source code with the zig compiler, by including the flag -lc in your compilation process. If you do not link your source code to Libc, Zig will not be able to find the malloc() implementation in your system.\n\n\n3.3.5 Page allocator\nThe page_allocator() is an allocator that allocates full pages of memory in the heap. In other words, every time you allocate memory with page_allocator(), a full page of memory in the heap is allocated, instead of just a small piece of it.\nThe size of this page depends on the system you are using. Most systems use a page size of 4KB in the heap, so, that is the amount of memory that is normally allocated in each call by page_allocator(). That is why, page_allocator() is considered a fast, but also “wasteful” allocator in Zig. Because it allocates a big amount of memory in each call, and you most likely will not need that much memory in your program.\n\n\n3.3.6 Buffer allocators\nThe FixedBufferAllocator() and ThreadSafeFixedBufferAllocator() are allocator objects that work with a fixed sized buffer object at the back. In other words, they use a fixed sized buffer object as the basis for the memory. When you ask these allocator objects to allocate some memory for you, they are essentially reserving some amount of space inside this fixed sized buffer object for you to use.\nThis means that, in order to use these allocators, you must first create a buffer object in your code, and then, give this buffer object as an input to these allocators.\nThis also means that, these allocator objects can allocate memory both in the stack or in the heap. Everything depends on where the buffer object that you provide lives. If this buffer object lives in the stack, then, the memory allocated is “stack-based”. But if it lives on the heap, then, the memory allocated is “heap-based”.\nIn the example below, I’m creating a buffer object on the stack that is 10 elements long. Notice that I give this buffer object to the FixedBufferAllocator() constructor. Now, because this buffer object is 10 elements long, this means that I am limited to this space. I cannot allocate more than 10 elements with this allocator object. If I try to allocate more than that, the alloc() method will return an OutOfMemory error value.\n\nvar buffer: [10]u8 = undefined;\nfor (0..buffer.len) |i| {\n    buffer[i] = 0; // Initialize to zero\n}\n\nvar fba = std.heap.FixedBufferAllocator.init(&buffer);\nconst allocator = fba.allocator();\nconst input = try allocator.alloc(u8, 5);\ndefer allocator.free(input);\n\nRemember, the memory allocated by these allocator objects can be either from the stack, or, from the heap. It all depends on where the buffer object that you provide lives. In the above example, the buffer object lives in the stack, and, therefore, the memory allocated is based in the stack. But what if it was based on the heap?\nAs we described at Section 3.2, one of the main reasons why you would use the heap, instead of the stack, is to allocate huge amounts of space to store very big objects. Thus, let’s suppose you wanted to use a very big buffer object as the basis for your allocator objects. You would have to allocate this very big buffer object on the heap. The example below demonstrates this case.\n\nconst heap = std.heap.page_allocator;\nconst memory_buffer = try heap.alloc(\n    u8, 100 * 1024 * 1024 // 100 MB memory\n);\ndefer heap.free(memory_buffer);\nvar fba = std.heap.FixedBufferAllocator.init(\n    memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst input = try allocator.alloc(u8, 1000);\ndefer allocator.free(input);\n\n\n\n3.3.7 Arena allocator\nThe ArenaAllocator() is an allocator object that takes a child allocator as input. The idea behind the ArenaAllocator() in Zig is similar to the concept of “arenas” in the programming language Go5. It is an allocator object that allows you to allocate memory as many times you want, but free all memory only once. In other words, if you have, for example, called 5 times the method alloc() of an ArenaAllocator() object, you can free all the memory you allocated over these 5 calls at once, by simply calling the deinit() method of the same ArenaAllocator() object.\nIf you give, for example, a GeneralPurposeAllocator() object as input to the ArenaAllocator() constructor, like in the example below, then, the allocations you perform with alloc() will actually be made with the underlying object GeneralPurposeAllocator() that was passed. So, with an arena allocator, any new memory you ask for is allocated by the child allocator. The only thing that an arena allocator really does is help you to free all the memory you allocated multiple times with just a single command. In the example below, I called alloc() 3 times. So, if I did not use an arena allocator, then, I would need to call free() 3 times to free all the allocated memory.\n\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nvar aa = std.heap.ArenaAllocator.init(gpa.allocator());\ndefer aa.deinit();\nconst allocator = aa.allocator();\n\nconst in1 = try allocator.alloc(u8, 5);\nconst in2 = try allocator.alloc(u8, 10);\nconst in3 = try allocator.alloc(u8, 15);\n_ = in1; _ = in2; _ = in3;\n\n\n\n3.3.8 The alloc() and free() methods\nIn the code example below, we are accessing the stdin, which is the standard input channel, to receive an input from the user. We read the input given by the user with the readUntilDelimiterOrEof() method.\nNow, after reading the input of the user, we need to store this input somewhere in our program. That is why I use an allocator in this example. I use it to allocate some amount of memory to store this input given by the user. More specifically, the method alloc() of the allocator object is used to allocate an array capable of storing 50 u8 values.\nNotice that this alloc() method receives two inputs. The first one, is a type. This defines what type of values the allocated array will store. In the example below, we are allocating an array of unsigned 8-bit integers (u8). But you can create an array to store any type of value you want. Next, on the second argument, we define the size of the allocated array, by specifying how many elements this array will contain. In the case below, we are allocating an array of 50 elements.\nAt Section 1.8 we described that strings in Zig are simply arrays of characters. Each character is represented by a u8 value. So, this means that the array that was allocated in the object input is capable of storing a string that is 50-characters long.\nSo, in essence, the expression var input: [50]u8 = undefined would create an array for 50 u8 values in the stack of the current scope. But, you can allocate the same array in the heap by using the expression var input = try allocator.alloc(u8, 50).\n\nconst std = @import(\"std\");\nconst stdin = std.io.getStdIn();\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var input = try allocator.alloc(u8, 50);\n    defer allocator.free(input);\n    for (0..input.len) |i| {\n        input[i] = 0; // initialize all fields to zero.\n    }\n    // read user input\n    const input_reader = stdin.reader();\n    _ = try input_reader.readUntilDelimiterOrEof(\n        input,\n        '\\n'\n    );\n    std.debug.print(\"{s}\\n\", .{input});\n}\n\nAlso, notice that in this example, we use the defer keyword (which I described at Section 2.1.3) to run a small piece of code at the end of the current scope, which is the expression allocator.free(input). When you execute this expression, the allocator will free the memory that it allocated for the input object.\nWe have talked about this at Section 3.1.5. You should always explicitly free any memory that you allocate using an allocator! You do that by using the free() method of the same allocator object you used to allocate this memory. The defer keyword is used in this example only to help us execute this free operation at the end of the current scope.\n\n\n3.3.9 The create() and destroy() methods\nWith the alloc() and free() methods, you can allocate memory to store multiple elements at once. In other words, with these methods, we always allocate an array to store multiple elements at once. But what if you need enough space to store just a single item? Should you allocate an array of a single element through alloc()?\nThe answer is no! In this case, you should use the create() method of the allocator object. Every allocator object offers the create() and destroy() methods, which are used to allocate and free memory for a single item, respectively.\nSo, in essence, if you want to allocate memory to store an array of elements, you should use alloc() and free(). But if you need to store just a single item, then, the create() and destroy() methods are ideal for you.\nIn the example below, I’m defining a struct to represent an user of some sort. It could be a user for a game, or software to manage resources, it doesn’t mater. Notice that I use the create() method this time, to store a single User object in the program. Also notice that I use the destroy() method to free the memory used by this object at the end of the scope.\n\nconst std = @import(\"std\");\nconst User = struct {\n    id: usize,\n    name: []const u8,\n\n    pub fn init(id: usize, name: []const u8) User {\n        return .{ .id = id, .name = name };\n    }\n};\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const user = try allocator.create(User);\n    defer allocator.destroy(user);\n\n    user.* = User.init(0, \"Pedro\");\n}\n\n\n\n\n\nChen, Jenny, and Ruohao Guo. 2022. “Stack and Heap Memory.” Introduction to Data Structures and Algorithms with C++. https://courses.engr.illinois.edu/cs225/fa2022/resources/stack-heap/.\n\n\nSobeston. 2024. “Zig Guide.” https://zig.guide/.\n\n\nZig Software Foundation. 2024. “Language Reference.” Zig Software Foundation. https://ziglang.org/documentation/master/.",
+    "crumbs": [
+      "<span class='chapter-number'>3</span>  <span class='chapter-title'>Memory and Allocators</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/01-memory.html#footnotes",
+    "href": "Chapters/01-memory.html#footnotes",
+    "title": "3  Memory and Allocators",
+    "section": "",
+    "text": "https://en.wikipedia.org/wiki/Stack_(abstract_data_type)↩︎\nhttps://www.geeksforgeeks.org/stack-data-structure/↩︎\nhttps://ziglang.org/documentation/master/#Lifetime-and-Ownership↩︎\nhttps://ziglang.org/documentation/master/#Undefined-Behavior↩︎\nhttps://go.dev/src/arena/arena.go↩︎",
+    "crumbs": [
+      "<span class='chapter-number'>3</span>  <span class='chapter-title'>Memory and Allocators</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/01-base64.html",
+    "href": "Chapters/01-base64.html",
+    "title": "4  Project 1 - Building a base64 encoder/decoder",
+    "section": "",
+    "text": "4.1 How the base64 algorithm work?\nBut how exactly does the algorithm behind the base64 encoding work? Let’s discuss that. First, I will explain the base64 scale, which is the 64-character scale that is the basis for the base64 encoding system.\nAfter that, I explain the algorithm behind a base64 encoder, which is the part of the algorithm that is responsible for encoding messages into the base64 encoding system. Then, after that, I explain the algorithm behind a base64 decoder, which is the part of the algorithm that is responsible for translating base64 messages back into their original meaning.\nIf you are unsure about the differences between an “encoder” and a “decoder”, take a look at Section 4.2.",
+    "crumbs": [
+      "<span class='chapter-number'>4</span>  <span class='chapter-title'>Project 1 - Building a base64 encoder/decoder</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/01-base64.html#how-the-base64-algorithm-work",
+    "href": "Chapters/01-base64.html#how-the-base64-algorithm-work",
+    "title": "4  Project 1 - Building a base64 encoder/decoder",
+    "section": "",
+    "text": "4.1.1 The base64 scale\nThe base64 encoding system is based on a scale that goes from 0 to 63 (hence the name). Each index in this scale is represented by a character (it is a scale of 64 characters). So, in order to convert some binary data, to the base64 encoding, we need to convert each binary number to the corresponding character in this “scale of 64 characters”.\nThe base64 scale starts with all ASCII uppercase letters (A to Z) which represents the first 25 indexes in this scale (0 to 25). After that, we have all ASCII lowercase letters (a to z), which represents the range 26 to 51 in the scale. After that, we have the one digit numbers (0 to 9), which represents the indexes from 52 to 61 in the scale. Finally, the last two indexes in the scale (62 and 63) are represented by the characters + and /, respectively.\nThese are the 64 characters that compose the base64 scale. The equal sign character (=) is not part of the scale itself, but it is a special character in the base64 encoding system. This character is used solely as a suffix, to mark the end of the character sequence, or, to mark the end of meaningful characters in the sequence.\nThe bullet points below summarises the base64 scale:\n\nrange 0 to 25 is represented by: ASCII uppercase letters -&gt; [A-Z];\nrange 26 to 51 is represented by: ASCII lowercase letters -&gt; [a-z];\nrange 52 to 61 is represented by: one digit numbers -&gt; [0-9];\nindex 62 and 63 are represented by the characters + and /, respectively;\nthe character = represents the end of meaningful characters in the sequence;\n\n\n\n4.1.2 Creating the scale as a lookup table\nThe best way to represent this scale in code, is to represent it as a lookup table. Lookup tables are a classic strategy in computer science to speed up calculations. The basic idea is to replace a runtime calculation (which can take a long time to be done) with a basic array indexing operation.\nInstead of calculating the results everytime you need them, you calculate all possible results at once, and then, you store them in an array (which behaves lake a “table”). Then, every time you need to use one of the characters in the base64 scale, instead of using many resources to calculate the exact character to be used, you simply retrieve this character from the array where you stored all the possible characters in the base64 scale. We retrieve the character that we need directly from memory.\nWe can start building a Zig struct to store our base64 decoder/encoder logic. We start with the Base64 struct below. For now, we only have one single data member in this struct, i.e. the member _table, which represents our lookup table. We also have an init() method, to create a new instance of a Base64 object, and, a _char_at() method, which is a “get character at index \\(x\\)” type of function.\n\nconst Base64 = struct {\n    _table: *const [64]u8,\n\n    pub fn init() Base64 {\n        const upper = \"ABCDEFGHIJKLMNOPQRSTUVWXYZ\";\n        const lower = \"abcdefghijklmnopqrstuvwxyz\";\n        const numbers_symb = \"0123456789+/\";\n        return Base64{\n            ._table = upper ++ lower ++ numbers_symb,\n        };\n    }\n\n    pub fn _char_at(self: Base64, index: usize) u8 {\n        return self._table[index];\n    }\n};\n\nIn other words, the _char_at() method is responsible for getting the character in the lookup table (i.e. the _table struct data member) that corresponds to a particular index in the “base64 scale”. So, in the example below, we know that the character that corresponds to the index 28 in the “base64 scale” is the character “c”.\n\nconst base64 = Base64.init();\ntry stdout.print(\n    \"Character at index 28: {c}\\n\",\n    .{base64._char_at(28)}\n);\n\nCharacter at index 28: c\n\n\n4.1.3 A base64 encoder\nThe algorithm behind a base64 encoder usually works on a window of 3 bytes. Because each byte has 8 bits, so, 3 bytes forms a set of \\(8 \\times 3 = 24\\) bits. This is desirable for the base64 algorithm, because 24 bits is divisible by 6, which forms \\(24 / 6 = 4\\) groups of 6 bits each.\nTherefore, the base64 algorithm works by converting 3 bytes at a time into 4 characters from the base64 scale. It keeps iterating through the input string, 3 bytes at a time, and converting them into the base64 scale, producing 4 characters per iteration. It keeps iterating, and producing these “new characters” until it hits the end of the input string.\nNow, you may think, what if you have a particular string that have a number of bytes that is not divisible by 3? What happens? For example, if you have a string that contains only two characters/bytes, such as “Hi”. How the algorithm would behave in such situation? You find the answer at Figure 4.1. You can see at Figure 4.1 that the string “Hi”, when converted to base64, becomes the string “SGk=”:\n\n\n\n\n\n\nFigure 4.1: The logic behind a base64 encoder\n\n\n\nTaking the string “Hi” as an example, we have 2 bytes, or, 16 bits in total. So, we lack a full byte (8 bits) to complete the window of 24 bits that the base64 algorithm likes to work on. The first thing that the algorithm does, is to check how to divide the input bytes into groups of 6 bits.\nIf the algorithm notices that there is a group of 6 bits that, have some bits in it, but, at the same time, it is not full (in other words, \\(0 &lt; nbits &lt; 6\\), being \\(nbits\\) the number of bits), meaning that, it lacks some bits to fill the 6-bits requirement, the algorithm simply add extra zeros in this group to fill the space that it needs. That is why at Figure 4.1, on the third group after the 6-bit transformation, 2 extra zeros were added to fill the gap in this group.\nWhen we have a 6-bit group that is not completely full, like the third group, extra zeros are added to fill the gap. But what about when an entire 6-bit group is empty, or, it simply doesn’t exist? This is the case of the fourth 6-bit group exposed at Figure 4.1.\nThis fourth group is necessary, because the algorithm works on 4 groups of 6 bits. But the input string does not have enough bytes to create a fourth 6-bit group. Every time this happens, where an entire group of 6 bits is empty, this group becomes a “padding group”. Every “padding group” is mapped to the character = (equal sign), which represents “null”, or, the end of meaningful characters in the sequence. Hence, everytime that the algorithm produces a “padding group”, this group is automatically mapped to =.\nAs another example, if you give the string “0” as input to a base64 encoder, this string is translated into the base64 sequence “MA==”. The character “0” is, in binary, the sequence 001100001. So, with the 6-bit transformation exposed at Figure 4.1, this single character would produce these two 6-bit groups: 001100, 000000. The remaining two 6-bit groups become “padding groups”. That is why the last two characters in the output sequence (MA==) are ==.\n\n\n4.1.4 A base64 decoder\nThe algorithm behind a base64 decoder is essentially the inverse process of a base64 encoder. A base64 decoder needs to translate base64 messages back into their original meaning, i.e. into the original sequence of binary data.\nA base64 decoder usually works on a window of 4 bytes. Because it wants to convert these 4 bytes back into the original sequence of 3 bytes, that was converted into 4 groups of 6 bits by the base64 encoder. Remember, in a base64 decoder we are essentially reverting the process made by the base64 encoder.\nEach byte in the input string (the base64 encoded string) normally contributes to re-create two different bytes in the output (the original binary data). In other words, each byte that comes out of a base64 decoder is created by transforming merging two different bytes in the input together. You can visualize this relationship at Figure 4.2:\n\n\n\n\n\n\nFigure 4.2: The logic behind a base64 decoder\n\n\n\nThe exact transformations, or, the exact steps applied to each byte from the input to transform them into the bytes of the output, are a bit tricky to visualize in a figure like this. Because of that, I have summarized these transformations as “Some bit shifting and additions …” in the figure. These transformations will be described in depth later.\nBesides that, if you look again at Figure 4.2, you will notice that the character = was completely ignored by the algorithm. Remember, this is just a special character that marks the end of meaningful characters in the base64 sequence. So, every = character in a base64 encoded sequence should be ignored by a base64 decoder.",
+    "crumbs": [
+      "<span class='chapter-number'>4</span>  <span class='chapter-title'>Project 1 - Building a base64 encoder/decoder</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/01-base64.html#sec-encode-vs-decode",
+    "href": "Chapters/01-base64.html#sec-encode-vs-decode",
+    "title": "4  Project 1 - Building a base64 encoder/decoder",
+    "section": "4.2 Difference between encode and decode",
+    "text": "4.2 Difference between encode and decode\nIf you don’t have any previous experience with base64, you might not understand the differences between “encode” and “decode”. Essentially, the terms “encode” and “decode” here have the exact same meaning as they have in the field of encryption (i.e. they mean the same thing as “encode” and “decode” in hashing algorithms, like the MD5 algorithm).\nThus, “encode” means that we want to encode, or, in other words, we want to translate some message into the base64 encoding system. We want to produce the sequence of base64 characters that represent this original message in the base64 encoding system.\nIn contrast, “decode” represents the inverse process. We want to decode, or, in other words, translate a base64 message back to its original content. So, in this process we get a sequence of base64 characters as input, and produce as output, the binary data that is represented by this sequence of base64 characters.\nAny base64 library is normally composed of these two parts: 1) the encoder, which is a function that encodes (i.e. it converts) any sequence of binary data into a sequence of base64 characters; 2) the decoder, which is a function that converts a sequence of base64 characters back into the original sequence of binary data.",
+    "crumbs": [
+      "<span class='chapter-number'>4</span>  <span class='chapter-title'>Project 1 - Building a base64 encoder/decoder</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/01-base64.html#sec-base64-length-out",
+    "href": "Chapters/01-base64.html#sec-base64-length-out",
+    "title": "4  Project 1 - Building a base64 encoder/decoder",
+    "section": "4.3 Calculating the size of the output",
+    "text": "4.3 Calculating the size of the output\nOne task that we need to do is to calculate how much space we need to reserve for the output, both of the encoder and decoder. This is simple math, and can be done easily in Zig because every array has its length (its number of elements) easily accesible by consulting the .len property of the array.\nFor the encoder, the logic is the following: for each 3 bytes that we find in the input, 4 new bytes are created in the output. So, we take the number of bytes in the input, divide it by 3, use a ceiling function, then, we multiply the result by 4. That way, we get the total number of bytes that will be produced by the encoder in its output.\nThe _calc_encode_length() function below encapsulates this logic. Inside this function, we take the length of the input array, we divide it by 3, and apply a ceil operation over the result by using the divCeil() function from the Zig Standard Library. Lastly, we multiply the end result by 4 to get the answer we need.\n\nconst std = @import(\"std\");\nfn _calc_encode_length(input: []const u8) !usize {\n    if (input.len &lt; 3) {\n        const n_output: usize = 4;\n        return n_output;\n    }\n    const n_output: usize = try std.math.divCeil(\n        usize, input.len, 3\n    );\n    return n_output * 4;\n}\n\nAlso, you might have notice that, if the input length is less than 3 bytes, then, the output length of the encoder is always 4 bytes. This is the case for every input with less than 3 bytes, because, as I described at Section 4.1.3, the algorithm always produces enough “padding-groups” in the end result, to complete the 4 bytes window.\nNow, for the decoder, we just need to apply the inverse logic: for each 4 bytes in the input, 3 bytes will be produced in the output of the decoder. I mean, this is roughly true, because we also need to take the = character into account, which is always ignored by the decoder, as we described at Section 4.1.4, and, at Figure 4.2. But we can ignore this fact for now, just to keep things simple.\nThe function _calc_decode_length() exposed below summarizes this logic that we described. It is very similar to the function _calc_encode_length(). Only the division part is twisted, and also, in the special case where we have less than 4 bytes in the input to work on. Also notice that this time, we apply a floor operation over the output of the division, by using the divFloor() function (instead of a ceiling operation with divCeil()).\n\nconst std = @import(\"std\");\nfn _calc_decode_length(input: []const u8) !usize {\n    if (input.len &lt; 4) {\n        const n_output: usize = 3;\n        return n_output;\n    }\n    const n_output: usize = try std.math.divFloor(\n        usize, input.len, 4\n    );\n    return n_output * 3;\n}",
+    "crumbs": [
+      "<span class='chapter-number'>4</span>  <span class='chapter-title'>Project 1 - Building a base64 encoder/decoder</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/01-base64.html#sec-encoder-logic",
+    "href": "Chapters/01-base64.html#sec-encoder-logic",
+    "title": "4  Project 1 - Building a base64 encoder/decoder",
+    "section": "4.4 Building the encoder logic",
+    "text": "4.4 Building the encoder logic\nIn this section, we can start building the logic behind the encode() function, which will be responsible for encoding messages into the base64 encoding system. If you are an anxious person, and you want to see now the full source code of the implementation for this base64 encoder/decoder, you can find it at the ZigExamples folder in the official repository of this book2.\n\n4.4.1 The 6-bit transformation\nThe 6-bit transformation presented at Figure 4.1 is the core part of the base64 encoder algorithm. By understanding how this transformation is made in code, the rest of the algorithm becomes much simpler to comprehend.\nIn essence, this 6-bit transformation is made with the help of bitwise operators. Bitwise operators are essential to any type of low-level operation that is done at the bit-level. For the specific case of the base64 algorithm, the operators bif shift to the left (&lt;&lt;), bit shift to the right (&gt;&gt;), and the bitwise and (&) are used. They are the core solution for the 6-bit transformation.\nThere are 3 different scenarios that we need to take into account in this transformation. First, is the perfect scenario, where we have the perfect window of 3 bytes to work on. Second, we have the scenario where we have a window of only two bytes to work with. And last, we have the scenario where we have a window of one single byte.\nIn each of these 3 scenarios, the 6-bit transformation works a bit differently. To make the explanation easier, I will use the variable output to refer to the bytes in the output of the base64 encoder, and the variable input to refer to the bytes in the input of the encoder.\nSo, if you have the perfect window of 3 bytes, these are steps for the 6-bit transformation:\n\noutput[0] is produced by moving the bits from input[0] two positions to the right.\noutput[1] is produced by summing two components. First, take the last two bits from input[0], then, move them four positions to the left. Second, move the bits from input[1] four positions to the right. Sum these two components.\noutput[2] is produced by summing two components. First, take the last four bits from input[1], then, move them two positions to the left. Second, move the bits from input[2] six positions to the right. Sum these two components.\noutput[3] is produced by taking the last six bits from input[2].\n\nThis is the perfect scenario, where we have a full window of 3 bytes to work on. Just to make things as clear as possible, the Figure 4.3 demonstrates visually how the step 2 mentioned above works. So the 2nd byte in the output of the encoder, is made by taking the 1st byte (dark purple) and the 2nd byte (orange) from the input. You can see that, at the end of the process, we get a new byte that contains the last 2 bits from the 1st byte in the input, and the first 4 bits from the 2nd byte in the input.\n\n\n\n\n\n\nFigure 4.3: How the 2nd byte in the output of the encoder is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input.\n\n\n\nOn the other hand, we must be prepared for the instances where we do not have the perfect window of 3 bytes. If you have a window of 2 bytes, then, the steps 3 and 4, which produces the bytes output[2] and output[3], change a little bit, and they become:\n\noutput[2] is produced by taking the last 4 bits from input[1], then, move them two positions to the left.\noutput[3] is the character '='.\n\nFinally, if you have a window of a single byte, then, the steps 2 to 4, which produces the bytes output[1], output[2] and output[3] change, becoming:\n\noutput[1] is produced by taking the last two bits from input[0], then, move them four positions to the left.\noutput[2] and output[3] are the character =.\n\nIf these bullet points were a bit confusing for you, you may find the Table 4.1 more intuitive. This table unifies all this logic into a simple table. Notice that this table also provides the exact expression in Zig that creates the corresponding byte in the output.\n\n\n\nTable 4.1: How the 6-bit transformation translates into code in different window settings.\n\n\n\n\n\n\n\n\n\n\nNumber of bytes in the window\nByte index in the output\nIn code\n\n\n\n\n3\n0\ninput[0] &gt;&gt; 2\n\n\n3\n1\n((input[0] & 0x03) &lt;&lt; 4) + (input[1] &gt;&gt; 4)\n\n\n3\n2\n((input[1] & 0x0f) &lt;&lt; 2) + (input[2] &gt;&gt; 6)\n\n\n3\n3\ninput[2] & 0x3f\n\n\n2\n0\ninput[0] &gt;&gt; 2\n\n\n2\n1\n((input[0] & 0x03) &lt;&lt; 4) + (input[1] &gt;&gt; 4)\n\n\n2\n2\n((input[1] & 0x0f) &lt;&lt; 2)\n\n\n2\n3\n‘=’\n\n\n1\n0\ninput[0] &gt;&gt; 2\n\n\n1\n1\n((input[0] & 0x03) &lt;&lt; 4)\n\n\n1\n2\n‘=’\n\n\n1\n3\n‘=’\n\n\n\n\n\n\n\n\n4.4.2 Bit-shifting in Zig\nBit-shifting in Zig works similarly to bit-shifting in C. All bitwise operators that exist in C are available in Zig. Here, in the base64 encoder algorithm, they are essential to produce the result we want.\nFor those who are not familiar with these operators, they are operators that operates at the bit-level of your values. This means that these operators takes the bits that form the value you have, and change them in some way. This ultimately also changes the value itself, because the binary representation of this value changes.\nWe have already seen at Figure 4.3 the effect produced by a bit-shift. But let’s use the first byte in the output of the base64 encoder as another example of what bit-shifting means. This is the easiest byte of the 4 bytes in the output to build. Because we only need to move the bits from the first byte in the input two positions to the right, with the bit shift to the right (&gt;&gt;) operator.\nIf we take the string “Hi” that we used at Figure 4.1 as an example, the first byte in this string is “H”, which is the sequence 01001000 in binary. If we move the bits of this byte, two places to the right, we get the sequence 00010010 as result. This binary sequence is the value 18 in decimal, and also, the value 0x12 in hexadecimal. Notice that the first 6 bits of “H” were moved to the end of the byte. With this operation, we get the first byte of the output.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const input = \"Hi\";\n    try stdout.print(\"{d}\\n\", .{input[0] &gt;&gt; 2});\n}\n\n18\n\n\nIf you recall Figure 4.1, the first byte present in the output should be equivalent to the 6-bit group 010010. Although being visually different, the sequences 010010 and 00010010 are semantically equal. They mean the same thing. They both represent the number 18 in decimal, and the value 0x12 in hexadecimal.\nSo, don’t take the “6-bit group” factor so seriously. We do not need necessarily to get a 6-bit sequence as result. As long as the meaning of the 8-bit sequence we get is the same of the 6-bit sequence, we are in the clear.\n\n\n4.4.3 Selecting specific bits with the & operator\nIf you comeback to Section 4.4.1, you will see that, in order to produce the second and third bytes in the output, we need to select specific bits from the first and second bytes in the input string. But how can we do that? The answer relies on the bitwise and (&) operator.\nThe Figure 4.3 already showed you what effect this & operator produces in the bits of its operands. But let’s make a clear description of it.\nIn summary, the & operator performs a logical conjunction operation between the bits of its operands. In more details, the operator & compares each bit of the first operand to the corresponding bit of the second operand. If both bits are 1, the corresponding result bit is set to 1. Otherwise, the corresponding result bit is set to 0 (Microsoft 2021).\nSo, if we apply this operator to the binary sequences 1000100 and 00001101 the result of this operation is the binary sequence 00000100. Because only at the sixth position in both binary sequences we had a 1 value. So any position where we do not have both binary sequences setted to 1, we get a 0 bit in the resulting binary sequence.\nWe lose information about the original bit values from both sequences in this case. Because we no longer know if this 0 bit in the resulting binary sequence was produced by combining 0 with 0, or 1 with 0, or 0 with 1.\nAs an example, suppose you have the binary sequence 10010111, which is the number 151 in decimal. How can we get a new binary sequence which contains only the third and fourth bits of this sequence?\nWe just need to combine this sequence with 00110000 (is 0x30 in hexadecimal) using the & operator. Notice that only the third and fourth positions in this binary sequence is setted to 1. As a consequence, only the third and fourth values of both binary sequences are potentially preserved in the output. All the remaining positions are setted to zero in the output sequence, which is 00010000 (is the number 16 in decimal).\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const bits = 0b10010111;\n    try stdout.print(\"{d}\\n\", .{bits & 0b00110000});\n}\n\n16\n\n\n\n\n4.4.4 Allocating space for the output\nAs I described at Section 3.1.4, to store an object in the stack, this object needs to have a known and fixed length at compile-time. This is an important limitation for our base64 encoder/decoder case. Because the size of the output (from both the encoder and decoder) depends directly on the size of the input.\nHaving this in mind, we cannot know at compile time which is the size of the output for both the encoder and decoder. So, if we can’t know the size of the output at compile time, this means that we cannot store the output for both the encoder and decoder in the stack.\nConsequently, we need to store this output on the heap, and, as I commented at Section 3.1.5, we can only store objects in the heap by using allocator objects. So, one the arguments to both the encode() and decode() functions, needs to be an allocator object, because we know for sure that, at some point inside the body of these functions, we need to allocate space on the heap to store the output of these functions.\nThat is why, both the encode() and decode() functions that I present in this book, have an argument called allocator, which receives a allocator object as input, identified by the type std.mem.Allocator from the Zig Standard Library.\n\n\n4.4.5 Writing the encode() function\nNow that we have a basic understanding on how the bitwise operators work, and how exactly they help us to achieve the result we want to achieve. We can now encapsulate all the logic that we have described at Figure 4.1 and Table 4.1 into a nice function that we can add to our Base64 struct definition, that we started at Section 4.1.2.\nYou can find the encode() function below. Notice that the first argument of this function, is the Base64 struct itself. Therefore, this argument clearly signals that this function is a method from the Base64 struct.\nBecause the encode() function itself is fairly long, I intentionally omitted the Base64 struct definition in this source code, just for brevity reasons. So, just remember that this function is a public function (or a public method) from the Base64 struct.\nFurthermore, this encode() function has two other arguments:\n\ninput is the input sequence of characters that you want to encode in base64;\nallocator is an allocator object to use in the necessary memory allocations.\n\nI described everything you need to know about allocator objects at Section 3.3. So, if you are not familiar with them, I highly recommend you to comeback to that section, and read it. By looking at the encode() function, you will see that we use this allocator object to allocate enough memory to store the output of the encoding process.\nThe main for loop in the function is responsible for iterating through the entire input string. In every iteration, we use a count variable to count how many iterations we had at the moment. When count reaches 3, then, we try to encode the 3 characters (or bytes) that we have accumulated in the temporary buffer object (buf).\nAfter encoding these 3 characters and storing the result in the output variable, we reset the count variable to zero, and start to count again on the next iteration of the loop. If the loop hits the end of the string, and, the count variable is less than 3, then, it means that the temporary buffer contains the last 1 or 2 bytes from the input. That is why we have two if statements after the for loop. To deal which each possible case.\n\npub fn encode(self: Base64,\n              allocator: std.mem.Allocator,\n              input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n\n    const n_out = try _calc_encode_length(input);\n    var out = try allocator.alloc(u8, n_out);\n    var buf = [3]u8{ 0, 0, 0 };\n    var count: u8 = 0;\n    var iout: u64 = 0;\n\n    for (input, 0..) |_, i| {\n        buf[count] = input[i];\n        count += 1;\n        if (count == 3) {\n            out[iout] = self._char_at(buf[0] &gt;&gt; 2);\n            out[iout + 1] = self._char_at(\n                ((buf[0] & 0x03) &lt;&lt; 4) + (buf[1] &gt;&gt; 4)\n            );\n            out[iout + 2] = self._char_at(\n                ((buf[1] & 0x0f) &lt;&lt; 2) + (buf[2] &gt;&gt; 6)\n            );\n            out[iout + 3] = self._char_at(buf[2] & 0x3f);\n            iout += 4;\n            count = 0;\n        }\n    }\n\n    if (count == 1) {\n        out[iout] = self._char_at(buf[0] &gt;&gt; 2);\n        out[iout + 1] = self._char_at(\n            (buf[0] & 0x03) &lt;&lt; 4\n        );\n        out[iout + 2] = '=';\n        out[iout + 3] = '=';\n    }\n\n    if (count == 2) {\n        out[iout] = self._char_at(buf[0] &gt;&gt; 2);\n        out[iout + 1] = self._char_at(\n            ((buf[0] & 0x03) &lt;&lt; 4) + (buf[1] &gt;&gt; 4)\n        );\n        out[iout + 2] = self._char_at(\n            (buf[1] & 0x0f) &lt;&lt; 2\n        );\n        out[iout + 3] = '=';\n        iout += 4;\n    }\n\n    return out;\n}",
+    "crumbs": [
+      "<span class='chapter-number'>4</span>  <span class='chapter-title'>Project 1 - Building a base64 encoder/decoder</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/01-base64.html#sec-decoder-logic",
+    "href": "Chapters/01-base64.html#sec-decoder-logic",
+    "title": "4  Project 1 - Building a base64 encoder/decoder",
+    "section": "4.5 Building the decoder logic",
+    "text": "4.5 Building the decoder logic\nNow, we can focus on writing the base64 decoder logic. Remember from Figure 4.2 that, a base64 decoder does the inverse process of an encoder. So, all we need to do, is to write a decode() function that performs the inverse process that I exposed at Section 4.4.\n\n4.5.1 Mapping base64 characters to their indexes\nOne thing that we need to do, in order to decode a base64-encoded message, is to calculate the index in the base64 scale of every base64 character that we encounter in the decoder input.\nIn other words, the decoder receives as input, a sequence of base64 characters. We need to translate this sequence of characters into a sequence of indexes. These indexes are the index of each character in the base64 scale. This way, we get the value/byte that was calculated in the 6-bit transformation step of the encoder process.\nThere are probably better/faster ways to calculate this, especially using a “divide and conquer” type of strategy. But for now, I am satisfied with a simple and “brute force” type of strategy. The _char_index() function below contains this strategy.\nWe are essentially looping through the lookup table with the base64 scale, and comparing the character we got with each character in the base64 scale. If these characters match, then, we return the index of this character in the base64 scale as the result.\nNotice that, if the input character is '=', the function returns the index 64, which is “out of range” in the scale. But, as I described at Section 4.1.1, the character '=' does not belong to the base64 scale itself. It is a special and meaningless character in base64.\nAlso notice that this _char_index() function is a method from our Base64 struct, because of the self argument. Again, I have omitted the Base64 struct definition in this example for brevity reasons.\n\nfn _char_index(self: Base64, char: u8) u8 {\n    if (char == '=')\n        return 64;\n    var index: u8 = 0;\n    for (0..63) |i| {\n        if (self._char_at(i) == char)\n            break;\n        index += 1;\n    }\n\n    return index;\n}\n\n\n\n4.5.2 The 6-bit transformation\nOnce again, the core part of the algorithm is the 6-bit transformation. If we understand the necessary steps to perform this transformation, the rest of the algorithm becomes much easier.\nFirst of all, before we actually go to the 6-bit transformation, we need to make sure that we use _char_index() to convert the sequence of base64 characters into a sequence of indexes. So the snippet below is important for the job that will be done. The result of _char_index() is stored in a temporary buffer, and this temporary buffer is what we are going to use in the 6-bit transformation, instead of the actual input object.\n\nfor (0..input.len) |i| {\n    buf[i] = self._char_index(input[i]);\n}\n\nNow, instead of producing 4 bytes (or 4 characters) as output per each window of 3 characters in the input, a base64 decoder produces 3 bytes (or 3 characters) as output per each window of 4 characters in the input. Once again, is the inverse process.\nSo, the steps to produce the 3 bytes in the output are:\n\noutput[0] is produced by summing two components. First, move the bits from buf[0] two positions to the left. Second, move the bits from buf[1] 4 positions to the right. Then, sum these two components.\noutput[1] is produced by summing two components. First, move the bits from buf[1] four positions to the left. Second, move the bits from buf[2] 2 positions to the right. Then, sum these two components.\noutput[2] is produced by summing two components. First, move the bits from buf[2] six positions to the left. Then, you sum the result with buf[3].\n\nBefore we continue, let’s try to visualize how these transformations make the original bytes that we had before the encoding process. First, think back to the 6-bit transformation performed by the encoder exposed at Section 4.4. The first byte in the output of the encoder is produced by moving the bits in the first byte of the input two positions to the right.\nIf for example the first byte in the input of the encoder was the sequence ABCDEFGH, then, the first byte in the output of the encoder would be 00ABCDEF (this sequence would be the first byte in the input of the decoder). Now, if the second byte in the input of the encoder was the sequence IJKLMNOP, then, the second byte in the encoder output would be 00GHIJKL (as we demonstrated at Figure 4.3).\nHence, if the sequences 00ABCDEF and 00GHIJKL are the first and second bytes, respectively, in the input of the decoder, the Figure 4.4 demonstrates visually how these two bytes are transformed into the first byte of the output of the decoder. Notice that the output byte is the sequence ABCDEFGH, which is the original byte from the input of the encoder.\n\n\n\n\n\n\nFigure 4.4: How the 1st byte in the decoder output is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input\n\n\n\nThe Table 4.2 presents how the three steps described earlier translate into Zig code:\n\n\n\nTable 4.2: The necessary steps for the 6-transformation in the decode process.\n\n\n\n\n\nByte index in the output\nIn code\n\n\n\n\n0\n(buf[0] &lt;&lt; 2) + (buf[1] &gt;&gt; 4)\n\n\n1\n(buf[1] &lt;&lt; 4) + (buf[2] &gt;&gt; 2)\n\n\n2\n(buf[2] &lt;&lt; 6) + buf[3]\n\n\n\n\n\n\n\n\n4.5.3 Writing the decode() function\nThe decode() function below contains the entire decoding process. We first calculate the size of the output, with _calc_decode_length(), then, we allocate enough memory for this output with the allocator object.\nThree temporary variables are created: 1) count, to hold the window count in each iteration of the for loop; 2) iout, to hold the current index in the output; 3) buf, which is the temporary buffer that holds the base64 indexes to be converted through the 6-bit transformation.\nThen, in each iteration of the for loop we fill the temporary buffer with the current window of bytes. When count hits the number 4, then, we have a full window of indexes in buf to be converted, and then, we apply the 6-bit transformation over the temporary buffer.\nNotice that we check if the indexes 2 and 3 in the temporary buffer are the number 64, which, if you recall from Section 4.5.1, is when the _calc_index() function receives a '=' character as input. So, if these indexes are equal to the number 64, the decode() function knows that it can simply ignore these indexes. They are not converted because, as I described before, the character '=' has no meaning, despite being the end of meaningful characters in the sequence. So we can safely ignore them when they appear in the sequence.\n\nfn decode(self: Base64,\n          allocator: std.mem.Allocator,\n          input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n    const n_output = try _calc_decode_length(input);\n    var output = try allocator.alloc(u8, n_output);\n    var count: u8 = 0;\n    var iout: u64 = 0;\n    var buf = [4]u8{ 0, 0, 0, 0 };\n\n    for (0..input.len) |i| {\n        buf[count] = self._char_index(input[i]);\n        count += 1;\n        if (count == 4) {\n            output[iout] = (buf[0] &lt;&lt; 2) + (buf[1] &gt;&gt; 4);\n            if (buf[2] != 64) {\n                output[iout + 1] = (buf[1] &lt;&lt; 4) + (buf[2] &gt;&gt; 2);\n            }\n            if (buf[3] != 64) {\n                output[iout + 2] = (buf[2] &lt;&lt; 6) + buf[3];\n            }\n            iout += 3;\n            count = 0;\n        }\n    }\n\n    return output;\n}",
+    "crumbs": [
+      "<span class='chapter-number'>4</span>  <span class='chapter-title'>Project 1 - Building a base64 encoder/decoder</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/01-base64.html#the-end-result",
+    "href": "Chapters/01-base64.html#the-end-result",
+    "title": "4  Project 1 - Building a base64 encoder/decoder",
+    "section": "4.6 The end result",
+    "text": "4.6 The end result\nNow that we have both decode() and encode() implemented. We have a fully functioning base64 encoder/decoder implemented in Zig. Here is an usage example of our Base64 struct with the encode() and decode() methods that we have implemented.\n\nvar memory_buffer: [1000]u8 = undefined;\nvar fba = std.heap.FixedBufferAllocator.init(\n    &memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst text = \"Testing some more shit\";\nconst etext = \"VGVzdGluZyBzb21lIG1vcmUgc2hpdA==\";\nconst base64 = Base64.init();\nconst encoded_text = try base64.encode(\n    allocator, text\n);\nconst decoded_text = try base64.decode(\n    allocator, etext\n);\ntry stdout.print(\n    \"Encoded text: {s}\\n\", .{encoded_text}\n);\ntry stdout.print(\n    \"Decoded text: {s}\\n\", .{decoded_text}\n);\n\nEncoded text: VGVzdGluZyBzb21lIG1vcmUgc2hpdA==\nDecoded text: Testing some more shit\nYou can also see the full source code at once, by visiting the official repository of this book3. More precisely inside the ZigExamples folder4.\n\n\n\n\nMicrosoft. 2021. “Bitwise AND Operator: &.” Microsoft Learn. https://learn.microsoft.com/en-us/cpp/cpp/bitwise-and-operator-amp?view=msvc-170.",
+    "crumbs": [
+      "<span class='chapter-number'>4</span>  <span class='chapter-title'>Project 1 - Building a base64 encoder/decoder</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/01-base64.html#footnotes",
+    "href": "Chapters/01-base64.html#footnotes",
+    "title": "4  Project 1 - Building a base64 encoder/decoder",
+    "section": "",
+    "text": "Notice that, the character “0” is different than the actual number 0, which is simply zero in binary.↩︎\nhttps://github.com/pedropark99/zig-book/blob/main/ZigExamples/base64/base64_basic.zig.↩︎\nhttps://github.com/pedropark99/zig-book↩︎\nhttps://github.com/pedropark99/zig-book/blob/main/ZigExamples/base64/base64_basic.zig.↩︎",
+    "crumbs": [
+      "<span class='chapter-number'>4</span>  <span class='chapter-title'>Project 1 - Building a base64 encoder/decoder</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/02-debugging.html",
+    "href": "Chapters/02-debugging.html",
+    "title": "5  Debugging Zig applications",
+    "section": "",
+    "text": "5.1 Print debugging\nWe begin with the classic and battle-tested print debugging strategy. The key advantage that debugging offers you is visibility. With print statements you can easily see what results and objects are being produced by your application.\nThat is the essence of print debugging. Is to use print expressions to see the values that are being generated by your program, and, as a result, get a much better understanding of how your program is behaving.\nMany programmers often resort to the print functions in Zig, such as the stdout.print(), or, the std.debug.print(), to get a better understanding of their programs. This is a known and old strategy that is very simple and effective, and it is better known within the programming community as print debugging. In Zig, you can print information to the stdout or stderr streams of your system.\nLet’s begin with stdout. First, you need to get access to the stdout, by calling the getStdOut() method, from the Zig Standard Library. This method returns a file descriptor object, and, through this object you can read/write to the stdout. I recommend you to check out all methods available in this object, by checking the page in the Zig Standard Library Official Reference for the type File1.\nFor our purpose here, which is to write something to the stdout, especially to debug our program, I recommend you to use the writer() method, which gives you a writer object. This writer object offers some helper methods to write stuff into the file descriptor object that represents the stdout stream. In special, the print() method.\nThe print() method from this writer object is a “print formatter” type of a function. In other words, this method works exactly like the printf() function from C, or, like println!() from Rust. In the first argument of the function, you specify a template string, and, in the second argument, you provide a list of values (or objects) that you want to insert into your template message.\nIdeally, the template string in the first argument should contain some format specifier. Each format specifier is matched to a value (or object) that you have listed in the second argument. So, if you provided 5 different objects in the second argument, then, the template string should contain 5 format specifiers, one for each object provided.\nEach format specifier is represented by a single letter, and you provide this format specifier inside a pair of curly braces. So, if you want to format your object using the string specifier (s), then, you can insert the text {s} in your template string. Here is a quick list of the most used format specifiers:\nThe code example below gives you an example of use of this print() method with the d format specifier.\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    try stdout.print(\"Result: {d}\", .{result});\n}\n\nResult: 50\nIt is important to emphasize that, the stdout.print() method, as you would expect, prints your template string into the stdout stream of your system. However, you can also print your template string into the stderr stream if your prefer. All you need to do, is to replace the stdout.print() call with the function std.debug.print(). Like this:\nconst std = @import(\"std\");\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    std.debug.print(\"Result: {d}\\n\", .{result});\n}\n\nResult: 50\nYou could also achieve the exact same result by getting a file descriptor object to stderr, then, creating a writer object to stderr, then, using the print() method of this writer object, like in the example below:\nconst std = @import(\"std\");\nconst stderr = std.io.getStdErr().writer();\n// some more lines ...\ntry stderr.print(\"Result: {d}\", .{result});",
+    "crumbs": [
+      "<span class='chapter-number'>5</span>  <span class='chapter-title'>Debugging Zig applications</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/02-debugging.html#print-debugging",
+    "href": "Chapters/02-debugging.html#print-debugging",
+    "title": "5  Debugging Zig applications",
+    "section": "",
+    "text": "d: for printing integers and floating-point numbers.\nc: for printing characters.\ns: for printing strings.\np: for printing memory addresses.\nx: for printing hexadecimal values.\nany: use any compatible format specifier (i.e. it automatically selects a format specifier for you).",
+    "crumbs": [
+      "<span class='chapter-number'>5</span>  <span class='chapter-title'>Debugging Zig applications</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/02-debugging.html#debugging-through-debuggers",
+    "href": "Chapters/02-debugging.html#debugging-through-debuggers",
+    "title": "5  Debugging Zig applications",
+    "section": "5.2 Debugging through debuggers",
+    "text": "5.2 Debugging through debuggers\nAlthough print debugging is a valid and very useful strategy, most programmers prefer to use a debugger to debug their programs. Since Zig is a low-level language, you can use either GDB (GNU Debugger), or LLDB (LLVM Project Debugger) as your debugger.\nBoth debuggers can work with Zig code, and it’s a matter of taste here. You choose the debugger of your preference, and you work with it. In this book, I will use LLDB as my debugger on the examples.\n\n5.2.1 Compile your source code in debug mode\nIn order to debug your program through a debugger, you must compile your source code in Debug mode. Because when you compile your source code in other modes (such as Release), the compiler usually strips out some essential information that is used by the debugger to read and track your program, like PDB (Program Database) files.\nBy compiling your source code in Debug mode, you ensure that the debugger will find the necessary information in your program to debug it. By default, the compiler uses the Debug mode when compiling your code. Having this in mind, when you compile your program with the build-exe command (which was described at Section 1.2.4), if you don’t specify an explicit mode through the -O command-line 2 argument, then, the compiler will compile your code in Debug mode.\n\n\n5.2.2 Let’s debug a program\nAs an example, let’s use LLDB to navigate and investigate the following piece of Zig code:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\nfn add_and_increment(a: u8, b: u8) u8 {\n    const sum = a + b;\n    const incremented = sum + 1;\n    return incremented;\n}\n\npub fn main() !void {\n    var n = add_and_increment(2, 3);\n    n = add_and_increment(n, n);\n    try stdout.print(\"Result: {d}!\\n\", .{n});\n}\n\nResult: 13!\n\n\nThere is nothing wrong with this program. But it is a good start for us. First, we need to compile this program with the zig build-exe command. For this example, suppose that I have compiled the above Zig code into a binary executable called add_program.\nzig build-exe add_program.zig\nNow, we can start LLDB with add_program, like this:\nlldb add_program\nFrom now on, LLDB is started, and you can know that I’m executing LLDB commands by looking at the prefix (lldb). If something is prefixed with (lldb), then you know that it is a LLDB command.\nThe first thing I will do, is to set a breakpoint at the main() function, by executing b main. After that, I just start the execution of the program with run. You can see in the output below, that the execution stopped at the first line in the function main(), as we expected.\n(lldb) b main\nBreakpoint 1: where = debugging`debug1.main + 22\n    at debug1.zig:11:30, address = 0x00000000010341a6\n(lldb) run\nProcess 8654 launched: 'add_program' (x86_64)\nProcess 8654 stopped\n* thread #1, name = 'add_program',\n    stop reason = breakpoint 1.1 frame #0: 0x10341a6\n    add_program`debug1.main at add_program.zig:11:30\n   8    }\n   9\n   10   pub fn main() !void {\n-&gt; 11       var n = add_and_increment(2, 3);\n   12       n = add_and_increment(n, n);\n   13       try stdout.print(\"Result: {d}!\\n\", .{n});\n   14   }\nI can start navigating through the code, and checking the objects that are being generated. If you are not familiar with the commands available in LLDB, I recommend you to read the official documentation of the project3. You can also look for cheat sheets, which quickly describes all commands available for you4.\nCurrently, we are in the first line at the main() function. In this line, we create the n object, by executing the add_and_increment() function. To execute the current line of code, and go to the next line, we can run the n LLDB command. Let’s execute this command.\nAfter we executed this line, we can also look at the value stored inside this n object by using the p LLDB command. The syntax for this command is p &lt;name-of-object&gt;.\nIf we take a look at the value stored in the n object (p n), notice that it stores the hexadecimal value 0x06, which is the number 6 in decimal. We can also see that this value has a type of unsigned char, which is an unsigned 8-bit integer. We have talked already about this at Section 1.8, that u8 integers in Zig are equivalent to the C data type unsigned char.\n(lldb) n\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step over frame #0: 0x10341ae\n    debugging`debug1.main at debug1.zig:12:26\n   9\n   10   pub fn main() !void {\n   11       var n = add_and_increment(2, 3);\n-&gt; 12       n = add_and_increment(n, n);\n   13       try stdout.print(\"Result: {d}!\\n\", .{n});\n   14   }\n(lldb) p n\n(unsigned char) $1 = '\\x06'\nNow, on the next line of code, we are executing the add_and_increment() function once again. Why not step inside this function? Shall we? We can do that, by executing the s LLDB command. Notice in the example below that, after executing this command, we have entered into the context of the add_and_increment() function.\nAlso notice in the example below that, I have walked two more lines in the function’s body, then, I execute the frame variable LLDB command, to see at once, the value stored in each of the variables that were created inside the current scope.\nYou can see in the output below that, the object sum stores the value \\f, which represents the form feed character. This character in the ASCII table, corresponds to the hexadecimal value 0x0C, or, in decimal, the number 12. So, this means that the result of the expression a + b executed at line 5, resulted in the number 12.\n(lldb) s\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step in frame #0: 0x10342de\n    debugging`debug1.add_and_increment(a='\\x02', b='\\x03')\n    at debug1.zig:4:39\n-&gt; 4    fn add_and_increment(a: u8, b: u8) u8 {\n   5        const sum = a + b;\n   6        const incremented = sum + 1;\n   7        return incremented;\n(lldb) n\n(lldb) n\n(lldb) frame variable\n(unsigned char) a = '\\x06'\n(unsigned char) b = '\\x06'\n(unsigned char) sum = '\\f'\n(unsigned char) incremented = '\\x06'",
+    "crumbs": [
+      "<span class='chapter-number'>5</span>  <span class='chapter-title'>Debugging Zig applications</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/02-debugging.html#how-to-investigate-the-data-type-of-your-objects",
+    "href": "Chapters/02-debugging.html#how-to-investigate-the-data-type-of-your-objects",
+    "title": "5  Debugging Zig applications",
+    "section": "5.3 How to investigate the data type of your objects",
+    "text": "5.3 How to investigate the data type of your objects\nSince Zig is a strongly-typed language, the data types associated with your objects are very important for your program. So, debugging the data types associated with your objects might be important to understand bugs and errors in your program.\nWhen you walk through your program with a debugger, you can inspect the types of your objects by simply printing them to the console, with the LLDB p command. But you also have alternatives embedded in the language itself to access the data types of your objects.\nIn Zig, you can retrieve the data type of an object, by using the built-in function @TypeOf(). Just apply this function over the object, and you get access to the data type of the object.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst expect = std.testing.expect;\n\npub fn main() !void {\n    const number: i32 = 5;\n    try expect(@TypeOf(number) == i32);\n    try stdout.print(\"{any}\\n\", .{@TypeOf(number)});\n}\n\ni32\n\n\nThis function is similar to the type() built-in function from Python, or, the typeof operator in Javascript.",
+    "crumbs": [
+      "<span class='chapter-number'>5</span>  <span class='chapter-title'>Debugging Zig applications</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/02-debugging.html#footnotes",
+    "href": "Chapters/02-debugging.html#footnotes",
+    "title": "5  Debugging Zig applications",
+    "section": "",
+    "text": "https://ziglang.org/documentation/master/std/#std.fs.File.↩︎\nSee https://ziglang.org/documentation/master/#Debug.↩︎\nhttps://lldb.llvm.org/↩︎\nhttps://gist.github.com/ryanchang/a2f738f0c3cc6fbd71fa.↩︎",
+    "crumbs": [
+      "<span class='chapter-number'>5</span>  <span class='chapter-title'>Debugging Zig applications</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/05-pointers.html",
+    "href": "Chapters/05-pointers.html",
+    "title": "6  Pointers and Optionals",
+    "section": "",
+    "text": "6.1 Constant objects vs variable objects\nYou can have a pointer that points to a constant object, or, a pointer that points to a variable object. But regardless of who this pointer is, a pointer must always respect the characteristics of the object that it points to. As a consequence, if the pointer points to a constant object, then, you cannot use this pointer to change the value that it points to. Because it points to a value that is constant. As we discussed at Section 1.4, you cannot change a value that is constant.\nFor example, if I have a number object, which is constant, I cannot execute the expression below where I’m trying to change the value of number to 6 through the pointer object. As demonstrated below, when you try to do something like that, you get a compile time error:\nconst number = 5;\nconst pointer = &number;\npointer.* = 6;\nIf I change the number object to be a variable object, by introducing the var keyword, then, I can successfully change the value of this object through a pointer, as demonstrated below:\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n\n6\nYou can see this relationship between “constant versus variable” on the data type of your pointer object. In other words, the data type of a pointer object already gives you some clues about whether the value that it points to is constant or not.\nWhen a pointer object points to a constant value, then, this pointer have a data type *const T, which means “a pointer to a constant value of type T”. In contrast, if the pointer points to a variable value, then, the type of the pointer is usually *T, which is simply “a pointer to a value of type T”. Hence, whenever you see a pointer object whose data type is in the format *const T, then, you know that you cannot use this pointer to change the value that it points to. Because this pointer points to a constant value of type T.\nWe have talked about the value pointed by the pointer being constant or not, and the consequences that arises from it. But, what about the pointer object itself? I mean, what happens if the pointer object itself is constant or not? Think about it. We can have a constant pointer that points to a constant value. But we can also have a variable pointer that points to a constant value. And vice-versa.\nUntil this point, the pointer object was always constant, but what this means for us? What is the consequence of the pointer object being constant? The consequence is that we cannot change the pointer object, because it is constant. We can use the pointer object in multiple ways, but we cannot change the memory address that is inside this pointer object.\nHowever, if we mark the pointer object as a variable object, then, we can change the memory address pointed by this pointer object. The example below demonstrates that. Notice that the object pointed by the pointer object changes from c1 to c2.\nconst c1: u8 = 5;\nconst c2: u8 = 6;\nvar pointer = &c1;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\npointer = &c2;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\nThus, by setting the pointer object to a var or const object, you specify if the memory address contained in this pointer object can change or not in your program. On the other side, you can change the value pointed by the pointer, if, and only if this value is stored in a variable object. If this value is in a constant object, then, you cannot change this value through a pointer.",
+    "crumbs": [
+      "<span class='chapter-number'>6</span>  <span class='chapter-title'>Pointers and Optionals</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/05-pointers.html#sec-pointer-var",
+    "href": "Chapters/05-pointers.html#sec-pointer-var",
+    "title": "6  Pointers and Optionals",
+    "section": "",
+    "text": "p.zig:6:12: error: cannot assign to constant\n    pointer.* = 6;\n\n\n\n\n\n\n\n\n5\n6",
+    "crumbs": [
+      "<span class='chapter-number'>6</span>  <span class='chapter-title'>Pointers and Optionals</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/05-pointers.html#types-of-pointer",
+    "href": "Chapters/05-pointers.html#types-of-pointer",
+    "title": "6  Pointers and Optionals",
+    "section": "6.2 Types of pointer",
+    "text": "6.2 Types of pointer\nIn Zig, there are two types of pointers (Zig Software Foundation 2024), which are:\n\nsingle-item pointer (*);\nmany-item pointer ([*]);\n\nSingle-item pointer objects are objects whose data types are in the format *T. So, for example, if an object have a data type *u32, it means that, this object contains a single-item pointer that points to an unsigned 32-bit integer value. As another example, if an object have type *User, then, it contains a single-item pointer to an User value.\nIn contrast, many-item pointers are objects whose data types are in the format [*]T. Notice that the star symbol (*) is now inside a pair of brackets ([]). If the star symbol is inside a pair of brackets, you know that this object is a many-item pointer.\nWhen you apply the & operator over an object, you will always get a single-item pointer. Many-item pointers are more of a “internal type” of the language, more closely related to slices. So, when you deliberately create a pointer with the & operator, you always get a single-item pointer as result.",
+    "crumbs": [
+      "<span class='chapter-number'>6</span>  <span class='chapter-title'>Pointers and Optionals</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/05-pointers.html#pointer-arithmetic",
+    "href": "Chapters/05-pointers.html#pointer-arithmetic",
+    "title": "6  Pointers and Optionals",
+    "section": "6.3 Pointer arithmetic",
+    "text": "6.3 Pointer arithmetic\nPointer arithmetic is available in Zig, and they work the same way they work in C. When you have a pointer that points to an array, the pointer usually points to the first element in the array, and you can use pointer arithmetic to advance this pointer and access the other elements in the array.\nNotice in the example below, that initially, the ptr object was pointing to the first element in the array ar. But then, I started to walk through the array, by advancing the pointer with simple pointer arithmetic.\n\nconst ar = [_]i32{1,2,3,4};\nvar ptr = &ar;\ntry stdout.print(\"{d}\\n\", .{ptr.*});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr.*});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr.*});\n\n1\n2\n3\nAlthough you can create a pointer to an array like that, and start to walk through this array by using pointer arithmetic, in Zig, we prefer to use slices, which were presented at Section 1.6.\nBehind the hood, slices already are pointers, and they also come with the len property, which indicates how many elements are in the slice. This is good because the zig compiler can use it to check for potential buffer overflows, and other problems like that.\nAlso, you don’t need to use pointer arithmetic to walk through the elements of a slice. You can simply use the slice[index] syntax to directly access any element you want in the slice. As I mentioned at Section 1.6, you can get a slice from an array by using a range selector inside brackets. In the example below, I’m creating a slice (sl) that covers the entire ar array. I can access any element of ar from this slice, and, the slice itself already is a pointer behind the hood.\n\nconst ar = [_]i32{1,2,3,4};\nconst sl = ar[0..ar.len];\n_ = sl;",
+    "crumbs": [
+      "<span class='chapter-number'>6</span>  <span class='chapter-title'>Pointers and Optionals</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/05-pointers.html#optionals-and-optional-pointers",
+    "href": "Chapters/05-pointers.html#optionals-and-optional-pointers",
+    "title": "6  Pointers and Optionals",
+    "section": "6.4 Optionals and Optional Pointers",
+    "text": "6.4 Optionals and Optional Pointers\nLet’s talk about optionals and how they relate to pointers in Zig. By default, objects in Zig are non-nullable. This means that, in Zig, you can safely assume that any object in your source code is not null.\nThis is a powerful feature of Zig when you compare it to the developer experience in C. Because in C, any object can be null at any point, and, as consequence, a pointer in C might point to a null value. This is a common source of undefined behaviour in C. When programmers work with pointers in C, they have to constantly check if their pointers are pointing to null values or not.\nIf for some reason, your Zig code produces a null value somewhere, and, this null value ends up in an object that is non-nullable, a runtime error is always raised by your Zig program. Take the program below as an example. The zig compiler can see the null value at compile time, and, as result, it raises a compile time error. But, if a null value is raised during runtime, a runtime error is also raised by the Zig program, with a “attempt to use null value” message.\n\nvar number: u8 = 5;\nnumber = null;\n\np5.zig:5:14: error: expected type 'u8',\n        found '@TypeOf(null)'\n    number = null;\n             ^~~~\nYou don’t get this type of safety in C. In C, you don’t get warnings or errors about null values being produced in your program. If for some reason, your code produces a null value in C, most of the times, you end up getting a segmentation fault error as result, which can mean many things. That is why programmers have to constantly check for null values in C.\nPointers in Zig are also, by default, non-nullable. This is another amazing feature in Zig. So, you can safely assume that any pointer that you create in your Zig code is pointing to a non-null value. Therefore, you don’t have this heavy work of checking if the pointers you create in Zig are pointing to a null value.\n\n6.4.1 What are optionals?\nOk, we know now that all objects are non-nullable by default in Zig. But what if we actually need to use an object that might receive a null value? Here is where optionals come in.\nAn optional object in Zig is an object that can be null. To mark an object as optional, we use the ? operator. When you put this ? operator right before the data type of an object, you transform this data type into an optional data type, and the object becomes an optional object.\nTake the snippet below as an example. We are creating a new variable object called num. This object have the data type ?i32, which means that, this object contains either a signed 32-bit integer (i32), or, a null value. Both alternatives are valid values to the num object. That is why, I can actually change the value of this object to null, and, no errors are raised by the zig compiler, as demonstrated below:\n\nvar num: ?i32 = 5;\nnum = null;\n\n\n\n6.4.2 Optional pointers\nYou can also mark a pointer object as an optional pointer, meaning that, this object contains either a null value, or, a pointer that points to a value. When you mark a pointer as optional, the data type of this pointer object becomes ?*const T or ?*T, depending if the value pointed by the pointer is a constant value or not. The ? identifies the object as optional, while the * identifies it as a pointer object.\nIn the example below, we are creating a variable object named num, and an optional pointer object named ptr. Notice that the data type of the object ptr indicates that it is either a null value, or a pointer to an i32 value. Also, notice that the pointer object (ptr) can be marked as optional, even if the object num is not optional.\nWhat this code tells us is that, the num variable will never contain a null value. This variable will always contain a valid i32 value. But in contrast, the ptr object might contain either a null value, or, a pointer to an i32 value.\n\nvar num: i32 = 5;\nvar ptr: ?*i32 = &num;\nptr = null;\nnum = 6;\n\nBut what happens if we turn the table, and mark the num object as optional, instead of the pointer object. If we do that, then, the pointer object is not optional anymore. It would be a similar (although different) result. Because then, we would have a pointer to an optional value. In other words, a pointer to a value that is either a null value, or, a not-null value.\nIn the example below, we are recreating this idea. Now, the ptr object have a data type of *?i32, instead of ?*i32. Notice that the * symbol comes before of ? this time. So now, we have a pointer that points to a value that is either null , or, a signed 32-bit integer.\n\nvar num: ?i32 = 5;\n// ptr have type `*?i32`, instead of `?*i32`.\nconst ptr = &num;\n_ = ptr;\n\n\n\n6.4.3 Null handling in optionals\nWhen you have an optional object in your Zig code, you have to explicitly handle the possibility of this object being null. It is like error-handling with try and catch. In Zig you also have to handle null values like if they were a type of error.\nWe can do that, by using either:\n\nan if statement, like you would do in C.\nthe orelse keyword.\nunwrap the optional value with the ? method.\n\nWhen you use an if statement, you use a pair of pipes to unwrap the optional value, and use this “unwrapped object” inside the if block. Using the example below as a reference, if the object num is null, then, the code inside the if statement is not executed. Otherwise, the if statement will unwrap the object num into the not_null_num object. This not_null_num object is guaranteed to be not null inside the scope of the if statement.\n\nconst num: ?i32 = 5;\nif (num) |not_null_num| {\n    try stdout.print(\"{d}\\n\", .{not_null_num});\n}\n\n5\n\n\nNow, the orelse keyword behaves like a binary operator. You connect two expressions with this keyword. On the left side of orelse, you provide the expression that might result in a null value, and on the right side of orelse, you provide another expression that will not result in a null value.\nThe idea behind the orelse keyword is: if the expression on the left side result in a not-null value, then, this not-null value is used. However, if this expression on the left side result in a null value, then, the value of the expression on the right side is used instead.\nLooking at the example below, since the x object is currently null, the orelse decided to use the alternative value, which is the number 15.\n\nconst x: ?i32 = null;\nconst dbl = (x orelse 15) * 2;\ntry stdout.print(\"{d}\\n\", .{dbl});\n\n30\n\n\nYou can use the if statement or the orelse keyword, when you want to solve (or deal with) this null value. However, if there is no clear solution to this null value, and the most logic and sane path is to simply panic and raise a loud error in your program when this null value is encountered, you can use the ? method of your optional object.\nIn essence, when you use this ? method, the optional object is unwrapped. If a not-null value is found in the optional object, then, this not-null value is used. Otherwise, the unreachable keyword is used. You can read more about this unreacheable keyword at the official documentation1. But in essence, when you build your Zig source code using the build modes ReleaseSafe or Debug, this unreacheable keyword causes the program to panic and raise an error during runtime, like in the example below:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn return_null(n: i32) ?i32 {\n    if (n == 5) return null;\n    return n;\n}\n\npub fn main() !void {\n    const x: i32 = 5;\n    const y: ?i32 = return_null(x);\n    try stdout.print(\"{d}\\n\", .{y.?});\n}\n\nthread 12767 panic: attempt to use null value\np7.zig:12:34: 0x103419d in main (p7):\n    try stdout.print(\"{d}\\n\", .{y.?});\n                                 ^\n\n\n\n\nZig Software Foundation. 2024. “Language Reference.” Zig Software Foundation. https://ziglang.org/documentation/master/.",
+    "crumbs": [
+      "<span class='chapter-number'>6</span>  <span class='chapter-title'>Pointers and Optionals</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/05-pointers.html#footnotes",
+    "href": "Chapters/05-pointers.html#footnotes",
+    "title": "6  Pointers and Optionals",
+    "section": "",
+    "text": "https://ziglang.org/documentation/master/#unreachable.↩︎",
+    "crumbs": [
+      "<span class='chapter-number'>6</span>  <span class='chapter-title'>Pointers and Optionals</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/04-http-server.html",
+    "href": "Chapters/04-http-server.html",
+    "title": "7  Project 2 - Building a HTTP Server from scratch",
+    "section": "",
+    "text": "7.1 What is a HTTP Server?\nFirst of all, what is a HTTP Server? A HTTP server, as any other type of server, is essentially a program that runs indefinitely, on an infinite loop, waiting for incoming connections from clients. Once the server receives an incoming connection, it will accept this connection, and it will send messages back-and-forth to the client through this connection.\nBut the messages that are transmitted inside this connection are in a specific format. They are HTTP messages (i.e. messages that use the HTTP Protocol specification). The HTTP Protocol is the backbone of the modern web. The world wide web as we know it today, would not exist without the HTTP Protocol.\nSo, Web servers (which is just a fancy name to HTTP Servers) are servers that exchange HTTP messages with clients. And these HTTP servers and the HTTP Protocol specification are essential to the operation of the world wide web today.\nThat is the whole picture of the process. Again, we have two subjects involved here, a server (which is a program that is running indefinitely, waiting to receive incoming connections), and a client (which is someone that wants to connect to the server, and exchange HTTP messages with it).\nYou may find the material about the HTTP Protocol available at the Mozilla MDN Docs1 , a great resource for you to also look at. It gives you a great overview on how HTTP works, and what role the server plays in this matter.",
+    "crumbs": [
+      "<span class='chapter-number'>7</span>  <span class='chapter-title'>Project 2 - Building a HTTP Server from scratch</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/04-http-server.html#sec-how-http-works",
+    "href": "Chapters/04-http-server.html#sec-how-http-works",
+    "title": "7  Project 2 - Building a HTTP Server from scratch",
+    "section": "7.2 How a HTTP Server works?",
+    "text": "7.2 How a HTTP Server works?\nImagine a HTTP Server as if it were the receptionist of a large hotel. In a hotel, you have a reception, and inside that reception there is a receptionist waiting for customers to arrive. A HTTP Server is essentially a receptionist that is indefinitely waiting for new customers (or, in the context of HTTP, new clients) to arrive in the hotel.\nWhen a customer arrives at the hotel, that customer starts a conversation with the receptionist. He tells the receptionist how many days he wants to stay at the hotel. Then, the receptionist search for an available apartment. If there is an available apartment at the moment, the customer pays the hotel fees, then, he gets the keys to the apartment, and then, he goes to the apartment to rest.\nAfter this entire process of dealing with the customer (searching for available apartments, receiving payment, handing over the keys), the receptionist goes back to what he was doing earlier, which is to wait. Wait for new customers to arrive.\nThat is, in a nutshell, what a HTTP Server do. It waits for clients to connect to the server. When a client attempts to connect to the server, the server accepts this connection, and it starts to exchange messages with the client through this connection. The first message that happens inside this connection is always a message from the client to the server. This message is called the HTTP Request.\nThis HTTP Request is a HTTP message that contains what the client wants from the server. It is literally a request. The client that connected to the server is asking this server to do something for him.\nThere are different “types of request” that a client can send to a HTTP Server. But the most basic type of request, is when a client ask to the HTTP Server to serve (i.e. to send) some specific web page (which is a HTML file) to him. When you type google.com in your web browser, you are essentially sending a HTTP Request to Google’s HTTP servers. This request is asking these servers to send the Google webpage to you.\nNonetheless, when the server receives this first message, the HTTP Request, it analyzes this request, to understand: who the client is? What he wants the server to do? This client has provided all the necessary information to perform the action that he asked? Etc.\nOnce the server understands what the client wants, he simply perform the action that was requested, and, to finish the whole process, the server sends back a HTTP message to the client, informing if the action performed was successful or not, and, at last, the server ends (or closes) the connection with the client.\nThis last HTTP message sent from the server to the client, is called the HTTP Response. Because the server is responding to the action that was requested by the client. The main objective of this response message is let the client know if the action requested was successful or not, before the server closes the connection.",
+    "crumbs": [
+      "<span class='chapter-number'>7</span>  <span class='chapter-title'>Project 2 - Building a HTTP Server from scratch</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/04-http-server.html#sec-http-how-impl",
+    "href": "Chapters/04-http-server.html#sec-http-how-impl",
+    "title": "7  Project 2 - Building a HTTP Server from scratch",
+    "section": "7.3 How a HTTP server is normally implemented?",
+    "text": "7.3 How a HTTP server is normally implemented?\nLet’s use the C language as an example. There are many materials teaching how to write a simple HTTP server in C code, like Yu (2023), or Weerasiri (2023), or Meehan (2021). Having this in mind, I will not show C code examples here, because you can find them on the internet. But I will describe the theory behind the necessary steps to create such HTTP server in C.\nIn essence, we normally implement a HTTP server in C by using WebSocket technology, which involves the following steps:\n\nCreate a socket object.\nBind a name (or more specifically, an address) to this socket object.\nMake this socket object to start listening and waiting for incoming connections.\nWhen a connection arrive, we accept this connection, and we exchange the HTTP messages (HTTP Request and HTTP Response).\nThen, we simply close this connection.\n\nA socket object is essentially a channel of communication. You are creating a channel where people can send messages through. When you create a socket object, this object is not binded to any particular address. This means that with this object you have a representation of a channel of communication in your hands. But this channel is not currently available, or, it is not currently accessible, because it do not have a known address where you can find it.\nThat is what the “bind” operation do. It binds a name (or more specifically, an address) to this socket object, or, this channel of communication, so that it becomes available, or, accessible through this address. While the “listen” operation makes the socket object to listen for incoming connections in this address. In other words, the “listen” operation makes the socket to wait for incoming connections. currently Now, when a client actually attempts to connect to the server through the socket address that we have specified, in order to establish this connection with the client, the socket object needs to accept this incoming connection. Thus, when we accept an incoming connection, the client and the server become connected to each other, and they can start reading or writing messages into this established connection.\nAfter we receive the HTTP Request from the client, analyze it, and send the HTTP Response to the client, we can then close the connection, and end this communication.",
+    "crumbs": [
+      "<span class='chapter-number'>7</span>  <span class='chapter-title'>Project 2 - Building a HTTP Server from scratch</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/04-http-server.html#implementing-the-server---part-1",
+    "href": "Chapters/04-http-server.html#implementing-the-server---part-1",
+    "title": "7  Project 2 - Building a HTTP Server from scratch",
+    "section": "7.4 Implementing the server - Part 1",
+    "text": "7.4 Implementing the server - Part 1\n\n7.4.1 Creating the socket object\nLet’s begin with creating the socket object for our server. Just to make things shorter, I will create this socket object in a separate Zig module. I will name it config.zig.\nIn Zig, we can create a web socket using the std.posix.socket() function, from the Zig Standard Library. As I mentioned earlier at Section 7.3, every socket object that we create represents a communication channel, and we need to bind this channel to a specific address. An “address” is defined as an IP address, or, more specifically, an IPv4 address2. Every IPv4 address is composed by two components. The first component is the host, which is a sequence of 4 numbers separated by dot characters (.) that identifies the machine used. While the second component is a port number, which identifies the specific door, or, the specific port to use in the host machine.\nThe sequence of 4 numbers (i.e. the host) identifies the machine (i.e. the computer itself) where this socket will live in. Every computer normally have multiple “doors” available inside of him, because this allows the computer to receive and work with multiple connections at the same time. He simply use a single door for each connection. So the port number, is essentially a number that identifies the specific door in the computer that will be responsible for receiving the connection. That is, it identifies the “door” in the computer that the socket will use to receive incoming connections.\nTo make things simpler, I will use an IP address that identifies our current machine in this example. This means that, our socket object will reside on the same computer that we are currently using (this is also known as the “localhost”) to write this Zig source code.\nBy convention, the IP address that identifies the “localhost”, which is the current machine we are using, is the IP 127.0.0.1. So, that is the IP address we are going to use in our server. I can declare it in Zig by using an array of 4 integers, like this:\n\nconst localhost = [4]u8{ 127, 0, 0, 1 };\n_ = localhost;\n\nNow, we need to decide which port number to use. By convention, there are some port numbers that are reserved, meaning that, we cannot use them for our own purposes, like the port 22 (which is normally used for SSH connections). For TCP connections, which is our case here, a port number is a 16-bit unsigned integer (type u16 in Zig), thus ranging from 0 to 65535 (Wikipedia 2024). So, we can choose a number from 0 to 65535 for our port number. In the example of this book, I will use the port number 3490 (just a random number).\nNow that we have these two informations at hand, I can finally create our socket object, using the std.posix.socket() function. First, we use the host and the port number to create an Address object, with the std.net.Address.initIp4() function, like in the example below. After that, I use this address object inside the socket() function to create our socket object.\nThe Socket struct defined below summarizes all the logic behind this process. In this struct, we have two data members, which are: 1) the address object; 2) and a stream object, which is the object we will use to read and write the messages into any connection we establish.\nNotice that, inside the constructor method of this struct, when we create the socket object, we are using the IPROTO.TCP property as an input to tell the function to create a socket for TCP connections.\n\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\nconst net = @import(\"std\").net;\n\npub const Socket = struct {\n    _address: std.net.Address,\n    _stream: std.net.Stream,\n\n    pub fn init() !Socket {\n        const host = [4]u8{ 127, 0, 0, 1 };\n        const port = 3490;\n        const addr = net.Address.initIp4(host, port);\n        const socket = try std.posix.socket(\n            addr.any.family,\n            std.posix.SOCK.STREAM,\n            std.posix.IPPROTO.TCP\n        );\n        const stream = net.Stream{ .handle = socket };\n        return Socket{ ._address = addr, ._stream = stream };\n    }\n};\n\n\n\n7.4.2 Listening and receiving connections\nRemember that we stored the Socket struct declaration that we built at Section 7.4.1 inside a Zig module named config.zig. This is why I imported this module into our main module (main.zig) in the example below, as the SocketConf object, to access the Socket struct.\nOnce we created our socket object, we can focus now on making this socket object listen and receive new incoming connections. We do that, by calling the listen() method from the Address object that is contained inside the socket object, and then, we call the accept() method over the result.\nThe listen() method from the Address object produces a server object, which is an object that will stay open and running indefinitely, waiting to receive an incoming connection. Therefore, if you try to run the code example below, by calling the run command from the zig compiler, you will notice that the programs keeps running indefinitely, without a clear end.\nThis happens, because the program is waiting for something to happen. It is waiting for someone to try to connect to the address (http://127.0.0.1:3490) where the server is running and listening for incoming connections. This is what the listen() method do, it makes the socket to be active waiting for someone to connect.\nOn the other side, the accept() method is the function that establishes the connection when someone tries to connect to the socket. This means that, the accept() method returns a new connection object as a result. And you can use this connection object to read or write messages from or to the client. For now, we are not doing anything with this connection object. But we are going to use it on the next section.\n\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n    _ = connection;\n}\n\nThis code example allows one single connection. In other words, the server will wait for one incoming connection, and as soon as the server is done with this first connection that it establishes, the program ends, and the server stops.\nThis is not the norm on the real world. Most people that write a HTTP server like this, usually put the accept() method inside a while (infinite) loop, where if a connection is created with accept(), a new thread of execution is created to deal with this new connection and the client. That is, real-world examples of HTTP Servers normally rely on parallel computing to work.\nWith this design, the server simply accepts the connection, and the whole process of dealing with the client, and receiving the HTTP Request, and sending the HTTP Response, all of this is done in the background, on a separate execution thread.\nSo, as soon as the server accepts the connection, and creates the separate thread, the server goes back to what he was doing earlier, which is to wait indefinitely for a new connection to accept. Having this in mind, the code example exposed above, is a server that serves only a single client. Because the program terminates as soon as the connection is accepted.\n\n\n7.4.3 Reading the message from the client\nNow that we have a connection established, i.e. the connection object that we created through the accept() function, we can now use this connection object to read any messages that the client send to our server. But we can also use it to send messages back to the client.\nThe basic idea is, if we write any data into this connection object, then, we are sending data to the client, and if we read the data present in this connection object, then, we are reading any data that the client sent to us, through this connection object. So, just have this logic in mind. “Read” is for reading messages from the client, and “write” is to send a message to the client.\nRemember from Section 7.2 that, the first thing that we need to do is to read the HTTP Request sent by the client to our server. Because it is the first message that happens inside the established connection, and, as a consequence, it is the first thing that we need to deal with.\nThat is why, I’m going to create a new Zig module in this small project, named request.zig to keep all functions related to the HTTP Request together. Then, I will create a new function named read_request() that will use our connection object to read the message sent by the client, which is the HTTP Request.\n\nconst std = @import(\"std\");\nconst Connection = std.net.Server.Connection;\npub fn read_request(conn: Connection,\n                    buffer: []u8) !void {\n    const reader = conn.stream.reader();\n    _ = try reader.read(buffer);\n}\n\nThis function accepts a slice object which behaves as a buffer. The read_request() function reads the message sent into the connection object, and saves this message into this buffer object that we have provided as input.\nNotice that I’m using the connection object that we created to read the message from the client. I first access the reader object that lives inside the connection object. Then, I call the read() method of this reader object to effectively read and save the data sent by the client into the buffer object that we created earlier. I’m discarding the return value of the read() method, by assigning it to the underscore character (_), because this return value is not useful for us right now.",
+    "crumbs": [
+      "<span class='chapter-number'>7</span>  <span class='chapter-title'>Project 2 - Building a HTTP Server from scratch</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/04-http-server.html#looking-at-the-current-state-of-the-program",
+    "href": "Chapters/04-http-server.html#looking-at-the-current-state-of-the-program",
+    "title": "7  Project 2 - Building a HTTP Server from scratch",
+    "section": "7.5 Looking at the current state of the program",
+    "text": "7.5 Looking at the current state of the program\nI think now is a good time to see how our program is currently working. Shall we? So, the first thing I will do is to update the main.zig module in our small Zig project, so that the main() function call this new read_request() function that we have just created. I will also add a print statement at the end of the main() function, just so that you can see what the HTTP Request that we have just loaded into the buffer object looks like.\nAlso, I’m creating the buffer object in the main() function, which will be responsible for storing the message sent by the client, and, I’m also using a for loop to initialize all fields of this buffer object to the number zero. This is important to make sure that we don’t have uninitialized memory in this object. Because uninitialized memory may cause undefined behaviour in our program.\nSince the read_request() function should receive as input the buffer object as a slice object ([]u8), I am using the syntax array[0..array.len] to get access to a slice of this buffer object.\n\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    _ = try Request.read_request(\n        connection, buffer[0..buffer.len]\n    );\n    try stdout.print(\"{s}\\n\", .{buffer});\n}\n\nNow, I’m going to execute this program, with the run command from the zig compiler. But remember, as we sad earlier, as soon as I execute this program, it will hang indefinitely, because the program is waiting for a client trying to connect to the server.\nMore specifically, the program will pause at the line with the accept() call. As soon as a client try to connect to the server, then, the execution will “unpause”, and the accept() function will finally be executed to create the connection object that we need, and the remaining of the program will run.\nYou can see that at Figure 7.1. The message Server Addr: 127.0.0.1:3490 is printed to the console, and the program is now waiting for an incoming connection.\n\n\n\n\n\n\nFigure 7.1: A screenshot of running the program\n\n\n\nWe can finally try to connect to this server, and there are several ways we can do this. For example, we could use the following Python script:\nimport requests\nrequests.get(\"http://127.0.0.1:3490\")\nOr, we could also open any web browser of our preference, and type the URL localhost:3490. OBS: localhost is the same thing as the IP 127.0.0.1. When you press enter, and your web browser go to this address, first, the browser will probably print a message saying that “this page isn’t working”, and, then, it will probably change to a new message saying that “the site can’t be reached”.\nYou get these “error messages” in the web browser, because it got no response back from the server. In other words, when the web browser connected to our server, it did send the HTTP Request through the established connection. Then, the web browser was expecting to receive a HTTP Response back, but it got no response from the server (we didn’t implemented the HTTP Response logic yet).\nBut that is okay. We have achieved the result that we wanted for now, which is to connect to the server, and see the HTTP Request that was sent by the web browser (or by the Python script) to the server.\nIf you comeback to the console that you left open when you have executed the program, you will see that the program finished its execution, and, a new message is printed in the console, which is the actual HTTP Request message that was sent by the web browser to the server. You can see this message at Figure 7.2.\n\n\n\n\n\n\nFigure 7.2: A screenshot of the HTTP Request sent by the web browser",
+    "crumbs": [
+      "<span class='chapter-number'>7</span>  <span class='chapter-title'>Project 2 - Building a HTTP Server from scratch</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/04-http-server.html#sec-enum",
+    "href": "Chapters/04-http-server.html#sec-enum",
+    "title": "7  Project 2 - Building a HTTP Server from scratch",
+    "section": "7.6 Learning about Enums in Zig",
+    "text": "7.6 Learning about Enums in Zig\nEnums structures are available in Zig through the enum keyword. An enum (short for “enumeration”) is a special structure that represents a group of constant values. So, if you have a variable which can assume a short and known set of values, you might want to associate this variable to an enum structure, to make sure that this variable only assumes a value from this set.\nA classic example for enums are primary colors. If for some reason, your program needs to represent one of the primary colors, you can create an enum that represents one of these colors. In the example below, we are creating the enum PrimaryColorRGB, which represents a primary color from the RGB color system. By using this enum, I am guaranteed that the acolor object for example, will contain one of these three values: RED, GREEN or BLUE.\n\nconst PrimaryColorRGB = enum {\n    RED, GREEN, BLUE\n};\nconst acolor = PrimaryColorRGB.RED;\n_ = acolor;\n\nIf for some reason, my code tries to save in acolor, a value that is not in this set, I will get an error message warning me that a value such as “MAGENTA” do not exist inside the PrimaryColorRGB enum. Then I can easily fix my mistake.\n\nconst acolor = PrimaryColorRGB.MAGENTA;\n\ne1.zig:5:36: error: enum 'PrimaryColorRGB' has\n        no member named 'MAGENTA':\n    const acolor = PrimaryColorRGB.MAGENTA;\n                                   ^~~~~~~\nBehind the hood, enums in Zig work the same way that enums work in C. Each enum value is essentially represented as an integer. The first value in the set is represented as zero, then, the second value is one, … etc.\nOne thing that we are going to learn on the next section is that enums can have methods in them. Wait… What? This is amazing! Yes, enums in Zig are similar to structs, and they can have private and public methods inside them.",
+    "crumbs": [
+      "<span class='chapter-number'>7</span>  <span class='chapter-title'>Project 2 - Building a HTTP Server from scratch</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/04-http-server.html#implementing-the-server---part-2",
+    "href": "Chapters/04-http-server.html#implementing-the-server---part-2",
+    "title": "7  Project 2 - Building a HTTP Server from scratch",
+    "section": "7.7 Implementing the server - Part 2",
+    "text": "7.7 Implementing the server - Part 2\nNow, on this section, I want to focus on parsing the HTTP Request that we received from the client. However, to effectively parse a HTTP Request message, we first need to understand its structure. In summary, a HTTP Request is a text message that is divided into 3 different sections (or parts):\n\nThe top-level header indicating the method of the HTTP Request, the URI, and the HTTP version used in the message.\nA list of HTTP Headers.\nThe body of the HTTP Request.\n\n\n7.7.1 The top-level header\nThe first line of text in a HTTP Request always come with the three most essential information about the request. These three key attributes of the HTTP Request are separated by a simple space in this first line of the request. The first information is the HTTP method that is being used in the request, second, we have the URI to which this HTTP Request is being sent to, and third, we have the version of the HTTP protocol that is being used in this HTTP Request.\nIn the snippet below, you can find an example of this first line in a HTTP Request. First, we have the HTTP method of this request (GET). Many programmers refer to the URI component (/users/list) as the “API endpoint” to which the HTTP Request is being sent to. In the context of this specific request, since it is a GET request, you could also say that the URI component is the path to the resource we want to access, or, the path to the document (or the file) that we want to retrieve from the server.\nGET /users/list HTTP/1.1\nAlso, notice that this HTTP Request is using the version 1.1 of the HTTP protocol, which is the most popular version of the protocol used in the web.\n\n\n7.7.2 The list of HTTP headers\nMost HTTP Requests also include a section of HTTP Headers, which is just a list of attributes or key-value pairs associated with this particular request. This section always comes right after the “top-level header” of the request.\nFor our purpose in this chapter, which is to build a simple HTTP Server, we are going to ignore this section of the HTTP Request, for simplicity. But most HTTP servers that exist in the wild parses and use these HTTP headers to change the way that the server responds to the request sent by the client.\nFor example, many requests we encounter in the real-world comes with a HTTP header called Accept. In this header, we find a list of MIME types3. This list indicates the file formats that the client can read, or parse, or interpret. In other words, you also interpret this header as the client saying the following phrase to the server: “Hey! Look, I can read only HTML documents, so please, send me back a document that is in a HTML format.”.\nIf the HTTP server can read and use this Accept header, then, the server can identify which is the best file format for the document to be sent to the client. Maybe the HTTP server have the same document in multiple formats, for example, in JSON, in XML, in HTML and in PDF, but the client can only understand documents in the HTML format. That is the purpose of this Accept header.\n\n\n7.7.3 The body\nThe body comes after the list of HTTP headers, and it is an optional section of the HTTP Request, meaning that, not all HTTP Request will come with a body in it. For example, every HTTP Request that uses the GET method usually do not come with a body.\nBecause a GET request is used to request data, instead of sending it to the server. So, the body section is more related to the POST method, which is a method that involves sending data to the server, to be processed and stored.\nSince we are going to support only the GET method in this project, it means that we also do not need to care about the body of the request.\n\n\n7.7.4 Creating the HTTP Method enum\nEvery HTTP Request comes with a explicit method. The method used in a HTTP Request is identified by one these words:\n\nGET;\nPOST;\nOPTIONS;\nPATCH;\nDELETE;\nand some other methods.\n\nEach HTTP method is used for a specific type of task. The POST method for example is normally used to post some data into the destination. In other words, it is used to send some data to the HTTP server, so that it can be processed and stored by the server.\nAs another example, the GET method is normally used to get content from the server. In other words, we use this method whenever we want the server to send some content back to us. It can be any type of content. It can be a web page, a document file, or some data in a JSON format.\nWhen a client sends a POST HTTP Request, the HTTP Response sent by the server normally have the sole purpose of letting the client know if the server processed and stored the data successfully. In contrast, when the server receives a GET HTTP Request, then, the server sends the content that the client asked for in the HTTP Response itself. This demonstrates that the method associated with the HTTP Request changes a lot on the dynamics and the roles that each party plays in the whole process.\nSince the HTTP method of the HTTP Request is identified by this very small and specific set of words, it would be interesting to create an enum structure to represent a HTTP method. This way, we can easily check if the HTTP Request we receive from the client is a HTTP method that we currently support in our small HTTP server project.\nThe Method structure below represents this enumeration. Notice that, for now, only the GET HTTP method is included in this enumeration. Because, for the purpose of this chapter, I want to implement only the GET HTTP method. That is why I am not including the other HTTP methods in this enumeration.\n\npub const Method = enum {\n    GET\n};\n\nNow, I think we should add two methods to this enum structure. One method is is_supported(), which will be a function that returns a boolean value, indicating if the input HTTP method is supported or not by our HTTP Server. The other is init(), which is a constructor function that takes a string as input, and tries to convert it into a Method value.\nBut in order to build these functions, I will use a functionality from the Zig Standard Library, called StaticStringMap(). This function allows us to create a simple map from strings to enum values. In other words, we can use this map structure to map a string to the respective enum value. To some extent, this specific structure from the standard library works almost like a “hashtable” structure, and it is optimized for small sets of words, or, small sets of keys, which is our case here. We are going to talk more about hashtables in Zig at Section 11.2.\nTo use this “static string map” structure, you have to import it from the std.static_string_map module of the Zig Standard Library. Just to make things shorter and easier to type, I am going to import this function through a different and shorter name (Map).\nWith Map() imported, we can just apply this function over the enum structure that we are going to use in the resulting map. In our case here, it is the Method enum structure that we declared at the last code example. Then, I call the initComptime() method with the map, i.e. the list of key-value pairs that we are going to use.\nYou can see in the example below that I wrote this map using multiple anonymous struct literals. Inside the first (or “top-level”) struct literal, we have a list (or a sequence) of struct literals. Each struct literal in this list represents a separate key-value pair. The first element (or the key) in each key-value pair should always be a string value. While the second element should be a value from the enum structure that you have used inside the Map() function.\n\nconst Map = std.static_string_map.StaticStringMap;\nconst MethodMap = Map(Method).initComptime(.{\n    .{ \"GET\", Method.GET },\n});\n\nTherefore, the MethodMap object is basically a std::map object from C++, or, a dict object from Python. You can retrieve (or get) the enum value that corresponds to a particular key, by using the get() method from the map object. This method returns an optional value, so, the get() method might result in a null value.\nWe can use this in our advantage to detect if a particular HTTP method is supported or not in our HTTP server. Because, if the get() method returns null, it means that it did not found the method that we provided inside the MethodMap object, and, as a consequence, this method is not supported by our HTTP server.\nThe init() method below, takes a string value as input, and then, it simply passes this string value to the get() method of our MethodMap object. As consequence, we should get the enum value that corresponds to this input string.\nNotice in the example below that, the init() method returns either an error (which might happen if the ? method returns unreacheable, checkout Section 6.4.3 for more details) or a Method object as result. Since GET is currently the only value in our Method enum structure, it means that, the init() method will most likely return the value Method.GET as result.\nAlso notice that, in the is_supported() method, we are using the optional value returned by the get() method from our MethodMap object. The if statement unwraps the optional value returned by this method, and returns true in case this optional value is a not-null value. Otherwise, it simply returns false.\n\npub const Method = enum {\n    GET,\n    pub fn init(text: []const u8) !Method {\n        return MethodMap.get(text).?;\n    }\n    pub fn is_supported(m: []const u8) bool {\n        const method = MethodMap.get(m);\n        if (method) |_| {\n            return true;\n        }\n        return false;\n    }\n};\n\n\n\n7.7.5 Writing the parse request function\nNow that we created the enum that represents our HTTP method, we should start to write the function responsible for actually parsing the HTTP Request.\nThe first thing we can do, is to write a struct to represent the HTTP Request. Take the Request struct below as an example. It contains the three essential information from the “top-level” header (i.e. the first line) in the HTTP Request.\n\nconst Request = struct {\n    method: Method,\n    version: []const u8,\n    uri: []const u8,\n    pub fn init(method: Method,\n                uri: []const u8,\n                version: []const u8) Request {\n        return Request{\n            .method = method,\n            .uri = uri,\n            .version = version,\n        };\n    }\n};\n\nThe parse_request() function should receive a string as input. This input string contains the entire HTTP Request message, and the parsing function should read and understand the individual parts of this message.\nNow, remember that for the purpose of this chapter, we care only about the first line in this message, which contains the “top-level header”, or, the three essential attributes about the HTTP Request, which are the HTTP method used, the URI and the HTTP version.\nNotice that I use the function indexOfScalar() in parse_request(). This function from the Zig Standard Library returns the first index where the scalar value that we provide happens in a string. In this case, I’m looking at the first occurrence of the new line character (\\n). Because once again, we care only about the first line in the HTTP Request message. This is the line where we have the three information that we want to parse (version of HTTP, the HTTP method and the URI).\nTherefore, we are using this indexOfScalar() function to limit our parsing process to the first line in the message. Is also worth mentioning that, the indexOfScalar() function returns an optional value. That is why I use the orelse keyword to provide an alternative value, in case the value returned by the function is a null value.\nSince each of these three attributes are separated by a simple space, we could use the function splitScalar() from the Zig Standard Library to split the input string into sections by looking for every position that appears a simple space. In other words, this splitScalar() function is equivalent to the split() method in Python, or, the std::getline() function from C++, or the strtok() function in C.\nWhen you use this splitScalar() function, you get an iterator as the result. This iterator have a next() method that you can use to advance the iterator to the next position, or, to the next section of the splitted string. Note that, when you use next(), the method not only advances the iterator, but it also returns a slice to the current section of the splitted string as result.\nNow, if you want to get a slice to the current section of the splitted string, but not advance the iterator to the next position, you can use the peek() method. Both next() and peek() methods return an optional value, that is why I use the ? method to unwrap these optional values.\n\npub fn parse_request(text: []u8) Request {\n    const line_index = std.mem.indexOfScalar(\n        u8, text, '\\n'\n    ) orelse text.len;\n    var iterator = std.mem.splitScalar(\n        u8, text[0..line_index], ' '\n    );\n    const method = try Method.init(iterator.next().?);\n    const uri = iterator.next().?;\n    const version = iterator.next().?;\n    const request = Request.init(method, uri, version);\n    return request;\n}\n\nAs I described at Section 1.8, strings in Zig are simply arrays of bytes in the language. So, you will find lots of excellent utility functions to work directly with strings inside this mem module from the Zig Standard Library. We have described some of these useful utility functions already at Section 1.8.4.\n\n\n7.7.6 Using the parse request function\nNow that we wrote the function responsible for parsing the HTTP Request, we can add the function call to parse_request() in the main() function of our program.\nAfter that, is a good idea to test once again the state of our program. I execute this program again with the run command from the zig compiler, then, I use my web browser to connect once again to the server through the URL localhost:3490, and finally, the end result of our Request object is printed to the console.\nA quick observation, since I have used the any format specifier in the print statement, the data members version and uri of the Request struct were printed as raw integer values. String data being printed as integer values is common in Zig, and remember, these integer values are just the decimal representation of the bytes that form the string in question.\nIn the result below, the sequence of decimal values 72, 84, 84, 80, 47, 49, 46, 49, and 13, are the bytes that form the text “HTTP/1.1”. And the integer 47, is the decimal value of the character /, which represents our URI in this request.\n\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    try Request.read_request(\n        connection, buffer[0..buffer.len]\n    );\n    const request = Request.parse_request(\n        buffer[0..buffer.len]\n    );\n    try stdout.print(\"{any}\\n\", .{request});\n}\n\nrequest.Request{\n    .method = request.Method.GET,\n    .version = {72, 84, 84, 80, 47, 49, 46, 49, 13},\n    .uri = {47}\n}\n\n\n7.7.7 Sending the HTTP Response to the client\nIn this last part, we are going to write the logic responsible for sending the HTTP Response from the server to the client. To make things simple, the server in this project will send just a simple web page containing the text “Hello world”.\nFirst, I create a new Zig module in the project, named response.zig. In this module, I will declare just two functions. Each function corresponds to a specific status code in the HTTP Response. The send_200() function will send a HTTP Response with status code 200 (which means “Success”) to the client. While the send_404() function sends a response with status code 404 (which means “Not found”).\nThis is definitely not the most ergonomic and adequate way of handling the HTTP Response, but it works for our case here. We are just building toy projects in this book after all, therefore, the source code that we write do not need to be perfect. It just needs to work!\n\nconst std = @import(\"std\");\nconst Connection = std.net.Server.Connection;\npub fn send_200(conn: Connection) !void {\n    const message = (\n        \"HTTP/1.1 200 OK\\nContent-Length: 48\"\n        ++ \"\\nContent-Type: text/html\\n\"\n        ++ \"Connection: Closed\\n\\n&lt;html&gt;&lt;body&gt;\"\n        ++ \"&lt;h1&gt;Hello, World!&lt;/h1&gt;&lt;/body&gt;&lt;/html&gt;\"\n    );\n    _ = try conn.stream.write(message);\n}\n\npub fn send_404(conn: Connection) !void {\n    const message = (\n        \"HTTP/1.1 404 Not Found\\nContent-Length: 50\"\n        ++ \"\\nContent-Type: text/html\\n\"\n        ++ \"Connection: Closed\\n\\n&lt;html&gt;&lt;body&gt;\"\n        ++ \"&lt;h1&gt;File not found!&lt;/h1&gt;&lt;/body&gt;&lt;/html&gt;\"\n    );\n    _ = try conn.stream.write(message);\n}\n\nNotice that both functions receives the connection object as input, and use the write() method to write the HTTP Response message directly into this communication channel. As result, the party in the other side of the connection (i.e. the client), will receive such message.\nMost real-world HTTP Servers will have a single function (or a single struct) to effectively handle the response. It gets the HTTP Request already parsed as input, and then, it tries to build the HTTP Response bit by bit, before the function sends it over the connection.\nWe would also have a specialized struct to represent a HTTP Response, and a lot of methods that would be used to build each part or component of the response object. Take the Response struct created by the Javascript runtime Bun as an example. You can find this struct in the response.zig module4 in their GitHub project.",
+    "crumbs": [
+      "<span class='chapter-number'>7</span>  <span class='chapter-title'>Project 2 - Building a HTTP Server from scratch</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/04-http-server.html#the-end-result",
+    "href": "Chapters/04-http-server.html#the-end-result",
+    "title": "7  Project 2 - Building a HTTP Server from scratch",
+    "section": "7.8 The end result",
+    "text": "7.8 The end result\nWe can now, update once again our main() function to incorporate our new functions from the response.zig module. First, I need to import this module into our main.zig module, then, I add the function calls to send_200() and send_404().\nNotice that I’m using if statements to decide which “response function” to call, based especially on the URI present in the HTTP Request. If the user asked for a content (or a document) that is not present in our server, we should respond with a 404 status code. But since we have just a simple HTTP server, with no real documents to send, we can just check if the URI is the root path (/) or not to decide which function to call.\nAlso, notice that I’m using the function std.mem.eql() from the Zig Standard Library to check if the string from uri is equal or not the string \"/\". We have described this function already at Section 1.8.4, so, comeback to that section if you are not familiar yet with this function.\n\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst Response = @import(\"response.zig\");\nconst Method = Request.Method;\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    try Request.read_request(connection, buffer[0..buffer.len]);\n    const request = Request.parse_request(\n        buffer[0..buffer.len]\n    );\n    if (request.method == Method.GET) {\n        if (std.mem.eql(u8, request.uri, \"/\")) {\n            try Response.send_200(connection);\n        } else {\n            try Response.send_404(connection);\n        }\n    }\n}\n\nNow that we adjusted our main() function, I can now execute our program, and see the effects of these last changes. First, I execute the program once again, with the run command of the zig compiler. The program will hang, waiting for a client to connect.\nThen, I open my web browser, and try to connect to the server again, using the URL localhost:3490. This time, instead of getting some sort of an error message from the browser, you will get the message “Hello World” printed into your web browser. Because this time, the server sended the HTTP Response successfully to the web browser, as demonstrated by Figure 7.3.\n\n\n\n\n\n\nFigure 7.3: The Hello World message sent in the HTTP Response\n\n\n\n\n\n\n\nMeehan, Eric. 2021. “Creating a Web Server from Scratch in c.” Youtube. https://www.youtube.com/watch?v=gk6NL1pZi1M&ab_channel=EricOMeehan.\n\n\nWeerasiri, Nipun Chamikara. 2023. “A Simple Web Server Written in c.” Medium. https://medium.com/@nipunweerasiri/a-simple-web-server-written-in-c-cf7445002e6.\n\n\nWikipedia. 2024. “Port (Computer Networking).” Wikipedia. https://en.wikipedia.org/wiki/Port_(computer_networking).\n\n\nYu, Jeffrey. 2023. “How i Built a Simple HTTP Server from Scratch Using c.” DEV Community. https://dev.to/jeffreythecoder/how-i-built-a-simple-http-server-from-scratch-using-c-739.",
+    "crumbs": [
+      "<span class='chapter-number'>7</span>  <span class='chapter-title'>Project 2 - Building a HTTP Server from scratch</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/04-http-server.html#footnotes",
+    "href": "Chapters/04-http-server.html#footnotes",
+    "title": "7  Project 2 - Building a HTTP Server from scratch",
+    "section": "",
+    "text": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview.↩︎\nIt can be also an IPv6 address. But normally, we use a IPv4 address for that.↩︎\nhttps://en.wikipedia.org/wiki/Media_type.↩︎\nhttps://github.com/oven-sh/bun/blob/main/src/bun.js/webcore/response.zig.↩︎",
+    "crumbs": [
+      "<span class='chapter-number'>7</span>  <span class='chapter-title'>Project 2 - Building a HTTP Server from scratch</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/03-unittests.html",
+    "href": "Chapters/03-unittests.html",
+    "title": "8  Unit tests",
+    "section": "",
+    "text": "8.1 Introducing the test block\nIn Zig, unit tests are written inside a test declaration, or, how I prefer to call it, inside a test block. Every test block is written by using the keyword test. You can optionally use a string literal to write a label, which is responsible for identifying the specific group of unit tests that you are writing inside this specific test block.\nIn the example below, we are testing if the sum of two objects (a and b) is equal to 4. The expect() function from the Zig Standard Library is a function that receives a logical test as input. If this logical test results in true, then, the test passes. But if it results in false, then, the test fails.\nYou can write any Zig code you want inside a test block. Part of this code might be some necessary commands to setup your testing environment, or just initializing some objects that you need to use in your unit tests.\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest \"testing simple sum\" {\n    const a: u8 = 2;\n    const b: u8 = 2;\n    try expect((a + b) == 4);\n}\n\n1/1 file153713a3190e.test.testing simple sum...OKA\n  All 1 tests passed.\nYou can have multiple test blocks written on the same Zig module. Also, you can mix test blocks with your source code, with no problems or consequences. If you mix test blocks with your normal source code, when you execute the build, build-exe, build-obj or build-lib commands from the zig compiler that we exposed at Section 1.2.4, these test blocks are automatically ignored by the compiler.\nIn other words, the zig compiler builds and execute your unit tests only when you ask it to. By default, the compiler always ignore test blocks written in your Zig modules. The compiler normally checks only if there are any syntax errors in these test blocks.\nIf you take a look at the source code for most of the files present in the Zig Standard Library1, you can see that the test blocks are written together with the normal source code of the library. You can see this for example, at the array_list module2. So, the standard that the Zig developers decided to adopt is to keep their unit tests together with the source code of the functionality that they are testing.\nEach programmer might have a different opinion on this. Some of them might prefer to keep unit tests separate from the actual source code of their application. If that is your case, you can simply create a separate tests folder in your project, and start writing Zig modules that contains only unit tests (as you would normally do on a Python project with pytest, for example), and everything will work fine. It boils down to which is your preference here.",
+    "crumbs": [
+      "<span class='chapter-number'>8</span>  <span class='chapter-title'>Unit tests</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/03-unittests.html#how-to-run-your-tests",
+    "href": "Chapters/03-unittests.html#how-to-run-your-tests",
+    "title": "8  Unit tests",
+    "section": "8.2 How to run your tests",
+    "text": "8.2 How to run your tests\nIf the zig compiler ignores any test block by default, how can you compile and run your unit tests? The answer is the test command from the zig compiler. By running the zig test command, the compiler will find every instance of a test block in your Zig modules, and, it will compile and run the unit tests that you wrote.\nzig test simple_sum.zig\n1/1 simple_sum.test.testing simple sum... OK\nAll 1 tests passed.",
+    "crumbs": [
+      "<span class='chapter-number'>8</span>  <span class='chapter-title'>Unit tests</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/03-unittests.html#testing-memory-allocations",
+    "href": "Chapters/03-unittests.html#testing-memory-allocations",
+    "title": "8  Unit tests",
+    "section": "8.3 Testing memory allocations",
+    "text": "8.3 Testing memory allocations\nOne of the advantages of Zig is that it offers great tools that help us, programmers, to avoid (but also detect) memory problems, such as memory leaks and double-frees. The defer keyword is especially helpful in this regard.\nWhen developing your source code, you, the programmer, is responsible for making sure that your code do not produce such problems. However, you can also use a special type of an allocator object in Zig that is capable of automatically detecting such problems for you. This is the std.testing.allocator object. This allocator object offers some basic memory safety detection features, which are capable of detecting memory leaks.\nAs we described at Section 3.1.5, to allocate memory on the heap, you need to use an allocator object, and your functions that use these objects to allocate memory on the heap, should receive an allocator object as one of its inputs. Every memory on the heap that you allocate using these allocator objects, must also be freed using this same allocator object.\nSo, if you want to test the memory allocations performed by your functions, and make sure that you don’t have problems in these allocations, you can simply write unit tests for these functions, where you provide the std.testing.allocator object as input to these functions.\nLook at the example below, where I’m defining a function that clearly causes a memory leak. Because we allocate memory, but, at the same time, we do not free this allocated memory at any point. So, when the function returns, we lose the reference to the buffer object, which contains the allocated memory, and, as a result, we can no longer free this memory.\nNotice that, inside a test block I execute this function with the std.testing.allocator. The allocator object was capable of looking deeper in our program, and detecting the memory leak. As a result, this allocator object returns an error message of “memory leaked”, and also, a stack trace showing the exact point where the memory was leaked.\n\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nfn some_memory_leak(allocator: Allocator) !void {\n    const buffer = try allocator.alloc(u32, 10);\n    _ = buffer;\n    // Return without freeing the\n    // allocated memory\n}\n\ntest \"memory leak\" {\n    const allocator = std.testing.allocator;\n    try some_memory_leak(allocator);\n}\n\nTest [1/1] leak_memory.test.memory leak...\n    [gpa] (err): memory address 0x7c1fddf39000 leaked: \n./ZigExamples/debugging/leak_memory.zig:4:39: 0x10395f2\n    const buffer = try allocator.alloc(u32, 10);\n                                      ^\n./ZigExamples/debugging/leak_memory.zig:12:25: 0x10398ea\n    try some_memory_leak(allocator);\n\n... more stack trace",
+    "crumbs": [
+      "<span class='chapter-number'>8</span>  <span class='chapter-title'>Unit tests</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/03-unittests.html#testing-errors",
+    "href": "Chapters/03-unittests.html#testing-errors",
+    "title": "8  Unit tests",
+    "section": "8.4 Testing errors",
+    "text": "8.4 Testing errors\nOne common style of unit tests are those that look for specific errors in your functions. In other words, you write a unit test that tries to assert if a specific function call returns any error, or a specific type of error.\nIn C++ you would normally write this style of unit tests using, for example, the functions REQUIRE_THROWS() or CHECK_THROWS() from the Catch2 test framework3. In the case of a Python project, you would probably use the raises() function from pytest4. While in Rust, you would probably use assert_eq!() in conjunction with Err().\nBut in Zig, we use the expectError() function, from the std.testing module. With this function, you can test if a specific function call returns the exact type of error that you expect it to return. To use this function, you first write try expectError(). Then, on the first argument, you provide the type of error that you are expecting from the function call. Then, on the second argument, you write the function call that you expect to fail.\nThe code example below demonstrates such type of unit test in Zig. Notice that, inside the function alloc_error() we are allocating 100 bytes of memory, or, an array of 100 elements, for the object ibuffer. However, in the test block, we are using the FixedBufferAllocator() allocator object, which is limited to 10 bytes of space, because the object buffer, which we provided to the allocator object, have only 10 bytes of space.\nThat is why, the alloc_error() function raises an OutOfMemory error on this case. Because this function is trying to allocate more space than the allocator object allows. So, in essence, we are testing for a specific type of error, which is OutOfMemory. If the alloc_error() function returns any other type of error, then, the expectError() function would make the entire test fail.\n\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst expectError = std.testing.expectError;\nfn alloc_error(allocator: Allocator) !void {\n    var ibuffer = try allocator.alloc(u8, 100);\n    defer allocator.free(ibuffer);\n    ibuffer[0] = 2;\n}\n\ntest \"testing error\" {\n    var buffer: [10]u8 = undefined;\n    var fba = std.heap.FixedBufferAllocator.init(&buffer);\n    const allocator = fba.allocator();\n    try expectError(error.OutOfMemory, alloc_error(allocator));\n}\n\n1/1 file1537546f248.test.testing error...OKAll 1 t\n  tests passed.",
+    "crumbs": [
+      "<span class='chapter-number'>8</span>  <span class='chapter-title'>Unit tests</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/03-unittests.html#testing-simple-equalities",
+    "href": "Chapters/03-unittests.html#testing-simple-equalities",
+    "title": "8  Unit tests",
+    "section": "8.5 Testing simple equalities",
+    "text": "8.5 Testing simple equalities\nIn Zig, there are some different ways you can test for an equality. You already saw that we can use expect() with the logical operator == to essentially reproduce an equality test. But we also have some other helper functions that you should know about, especially expectEqual(), expectEqualSlices() and expectEqualStrings().\nThe expectEqual() function, as the name suggests, is a classic test equality function. It receives two objects as input. The first object is the value that you expect to be in the second object. While second object is the object you have, or, the object that your application produced as result. So, with expectEqual() you are essentially testing if the values stored inside these two objects are equal or not.\nYou can see in the example below that, the test performed by expectEqual() failed. Because the objects v1 and v2 contain different values in them.\n\nconst std = @import(\"std\");\ntest \"values are equal?\" {\n    const v1 = 15;\n    const v2 = 18;\n    try std.testing.expectEqual(v1, v2);\n}\n\n1/1 ve.test.values are equal?...\n    expected 15, found 18\n    FAIL (TestExpectedEqual)\nve.zig:5:5: test.values are equal? (test)\n    try std.testing.expectEqual(v1, v2);\n    ^\n0 passed; 0 skipped; 1 failed.\nAlthough useful, the expectEqual() function does not work with arrays. For testing if two arrays are equal, you should use the expectEqualSlices() function instead. This function have three arguments. First, you provide the data type contained in both arrays that you are trying to compare. While the second and third arguments corresponds to the array objects that you want to compare.\nIn the example below, we are using this function to test if two array objects (array1 and array2) are equal or not. Since they are in fact equal, the unit test passed with no errors.\n\nconst std = @import(\"std\");\ntest \"arrays are equal?\" {\n    const array1 = [3]u32{1, 2, 3};\n    const array2 = [3]u32{1, 2, 3};\n    try std.testing.expectEqualSlices(\n        u32, &array1, &array2\n    );\n}\n\n1/1 file15377bbafb73.test.arrays are equal?...OKAl\n  ll 1 tests passed.\n\n\nAt last, you might also want to use the expectEqualStrings() function. As the name suggests, you can use this function to test if two strings are equal or not. Just provide the two string objects that you want to compare, as inputs to the function.\nIf the function finds any existing differences between the two strings, then, the function will raise an error, and also, print an error message that shows the exact difference between the two string objects provided, as the example below demonstrates:\n\nconst std = @import(\"std\");\ntest \"strings are equal?\" {\n    const str1 = \"hello, world!\";\n    const str2 = \"Hello, world!\";\n    try std.testing.expectEqualStrings(\n        str1, str2\n    );\n}\n\n1/1 t.test.strings are equal?... \n====== expected this output: =========\nhello, world!␃\n======== instead found this: =========\nHello, world!␃\n======================================\nFirst difference occurs on line 1:\nexpected:\nhello, world!\n^ ('\\x68')\nfound:\nHello, world!\n^ ('\\x48')",
+    "crumbs": [
+      "<span class='chapter-number'>8</span>  <span class='chapter-title'>Unit tests</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/03-unittests.html#footnotes",
+    "href": "Chapters/03-unittests.html#footnotes",
+    "title": "8  Unit tests",
+    "section": "",
+    "text": "https://github.com/ziglang/zig/tree/master/lib/std↩︎\nhttps://github.com/ziglang/zig/blob/master/lib/std/array_list.zig↩︎\nhttps://github.com/catchorg/Catch2/tree/devel↩︎\nhttps://docs.pytest.org/en/7.1.x/reference/reference.html#pytest-raises↩︎",
+    "crumbs": [
+      "<span class='chapter-number'>8</span>  <span class='chapter-title'>Unit tests</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/07-build-system.html",
+    "href": "Chapters/07-build-system.html",
+    "title": "9  Build System",
+    "section": "",
+    "text": "9.1 How source code is built?\nWe already have talked about the challenges of building source code in low-level languages at Section 1.2.1. As we described at that section, programmers invented Build Systems to surpass these challenges on the process of building source code in low-level languages.\nLow-level languages uses a compiler to compile (or to build) your source code into binary instructions. In C and C++, we normally use compilers like gcc, g++ or clang to compile our C and C++ source code into these instructions. Every language have its own compiler, and this is no different in Zig.\nIn Zig, we have the zig compiler to compile our Zig source code into binary instructions that can be executed by our computer. In Zig, the compilation (or the build) process involves the following components:\nThese are the things that you need to connect together in order to build your source code in Zig. In C and C++, you would have an extra component, which are the header files of the libraries that you are using. But header files do not exist in Zig, so, you only need to care about them if you are linking your Zig source code with a C library. If that is not your case, you can forget about it.\nYour build process is usually organized in a build script. In Zig, we normally write this build script into a Zig module in the root directory of our project, named as build.zig. You write this build script, then, when you run it, your project get’s built into binary files that you can use and distribute to your users.\nThis build script is normally organized around target objects. A target is simply something to be built, or, in other words, it’s something that you want the zig compiler to build for you. This concept of “targets” is present in most Build Systems, especially in CMake3.\nThere are four types of target objects that you can build in Zig, which are:\nWe are going to talk more about these target objects at Section 9.3.",
+    "crumbs": [
+      "<span class='chapter-number'>9</span>  <span class='chapter-title'>Build System</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/07-build-system.html#how-source-code-is-built",
+    "href": "Chapters/07-build-system.html#how-source-code-is-built",
+    "title": "9  Build System",
+    "section": "",
+    "text": "The Zig modules that contains your source code;\nLibrary files (either a dynamic library or a static library);\nCompiler flags that tailors the build process to your needs.\n\n\n\n\n\n\nAn executable (e.g. a .exe file on Windows).\nA shared library (e.g. a .so file in Linux or a .dll file on Windows).\nA static library (e.g. a .a file in Linux or a .lib file on Windows).\nAn executable file that executes only unit tests (or, a “unit tests executable”).",
+    "crumbs": [
+      "<span class='chapter-number'>9</span>  <span class='chapter-title'>Build System</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/07-build-system.html#sec-build-fun",
+    "href": "Chapters/07-build-system.html#sec-build-fun",
+    "title": "9  Build System",
+    "section": "9.2 The build() function",
+    "text": "9.2 The build() function\nA build script in Zig always contains a public (and top-level) build() function declared. It is like the main() function on the main Zig module of your project, that we discussed at Section 1.2.3. But instead of creating the entrypoint to your code, this build() function is the entrypoint to the build process.\nThis build() function should accept a pointer to a Build object as input, and it should use this “build object” to perform the necessary steps to build your project. The return type of this function is always void, and this Build struct comes directly from the Zig Standard Library (std.Build). So, you can access this struct by just importing the Zig Standard Library into your build.zig module.\nJust as a very simple example, here you can see the source code necessary to build an executable file from the hello.zig Zig module.\n\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"hello.zig\"),\n        .target = b.host,\n    });\n    b.installArtifact(exe);\n}\n\nYou can define and use other functions and objects in this build script. You can also import other Zig modules as you would normally do in any other module of your project. The only real requirement for this build script, is to have a public and top-level build() function defined, that accepts a pointer to a Build struct as input.",
+    "crumbs": [
+      "<span class='chapter-number'>9</span>  <span class='chapter-title'>Build System</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/07-build-system.html#sec-targets",
+    "href": "Chapters/07-build-system.html#sec-targets",
+    "title": "9  Build System",
+    "section": "9.3 Target objects",
+    "text": "9.3 Target objects\nAs we described over the previous sections, a build script is composed around target objects. Each target object is normally a binary file (or an output) that you want to get from the build process. You can list multiple target objects in your build script, so that the build process generates multiple binary files for you at once.\nFor example, maybe you are a developer working in a cross-platform application, and, because this application is cross-platform, you probably need to release binary files of your software for each OS supported by your application to your end users. Thus, you can define a different target object in your build script for each OS (Windows, Linux, etc.) where you want to publish your software. This will make the zig compiler to build your project to multiple target OS’s at once. The Zig Build System official documentation have a great code example that demonstrates this strategy4.\nA target object is created by the following methods of the Build struct that we introduced at Section 9.2:\n\naddExecutable() creates an executable file;\naddSharedLibrary() creates a shared library file;\naddStaticLibrary() creates a static library file;\naddTest() creates an executable file that executes unit tests.\n\nThese functions are methods from the Build struct that you receive as input of the build() function. All of them, create as output a Compile object, which represents a target object to be compiled by the zig compiler. All of these functions accept a similar struct literal as input. This struct literal defines three essential specs about this target object that you are building: name, target and root_source_file.\nWe have already seen these three options being used on the previous example, where we used the addExecutable() method to create an executable target object. This example is reproduced below. Notice the use of the path() method from the Build struct, to define a path in the root_source_file option.\n\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nThe name option specify the name that you want to give to the binary file defined by this target object. So, in this example, we are building an executable file named hello. Is common to set this name option to the name of your project.\nFurthermore, the target option specify the target computer architecture (or the target operating system) of this binary file. For example, if you want this target object to run on a Windows machine that uses a x86_64 architecture, you can set this target option to x86_64-windows-gnu for example. This will make the zig compiler to compile the project to run on a x86_64 Windows machine. You can see the full list of architectures and OS’s that the zig compiler supports by running the zig targets command in the terminal.\nNow, if you are building the project to run on the current machine that you are using to run this build script, you can set this target option to the host method of the Build object, like we did in the example above. This host method identifies the current machine where you are currently running the zig compiler.\nAt last, the root_source_file option specifies the root Zig module of your project. That is the Zig module that contains the entrypoint to your application (i.e. the main() function), or, the main API of your library. This also means that, all the Zig modules that compose your project are automatically discovered from the import statements you have inside this “root source file”. The zig compiler can detect when a Zig module depends on the other through the import statements, and, as a result, it can discover the entire map of Zig modules used in your project.\nThis is handy, and it is different from what happens in other build systems. In CMake for example, you have to explicitly list the paths to all source files that you want to include in your build process. This is probably a symptom of the “lack of conditional compilation” in the C and C++ compilers. Since they lack this feature, you have to explicitly choose which source files should be sent to the C/C++ compiler, because not every C/C++ code is portable or supported in every operating system, and, therefore, would cause a compilation error in the C/C++ compiler.\nNow, one important detail about the build process is that, you have to explicitly install the target objects that you create in your build script, by using the installArtifact() method of the Build struct.\nEverytime you invoke the build process of your project, by calling the build command of the zig compiler, a new directory named zig-out is created in the root directory of your project. This new directory contains the outputs of the build process, that is, the binary files built from your source code.\nWhat the installArtifact() method do is to install (or copy) the built target objects that you defined to this zig-out directory. This means that, if you do not install the target objects you define in your build script, these target objects are essentially discarded at the end of the build process.\nFor example, you might be building a project that uses a third party library that is built together with the project. So, when you build your project, you would need first, to build the third party library, and then, you link it with the source code of your project. So, in this case, we have two binary files that are generated in the build process (the executable file of your project, and the third party library). But only one is of interest, which is the executable file of our project. We can discard the binary file of the third party library, by simply not installing it into this zig-out directory.\nThis installArtifact() method is pretty straightforward. Just remember to apply it to every target object that you want to save into the zig-out directory, like in the example below:\n\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nb.installArtifact(exe);",
+    "crumbs": [
+      "<span class='chapter-number'>9</span>  <span class='chapter-title'>Build System</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/07-build-system.html#setting-the-build-mode",
+    "href": "Chapters/07-build-system.html#setting-the-build-mode",
+    "title": "9  Build System",
+    "section": "9.4 Setting the build mode",
+    "text": "9.4 Setting the build mode\nWe have talked about the three essential options that are set when you create a new target object. But there is also a fourth option that you can use to set the build mode of this target object, which is the optimize option. This option is called this way, because the build modes in Zig are treated more of an “optimization vs safety” problem. So optimization plays an important role here. Don’t worry, I’m going back to this question very soon.\nIn Zig, we have four build modes (which are listed below). Each one of these build modes offer different advantages and characteristics. As we described at Section 5.2.1, the zig compiler uses the Debug build mode by default, when you don’t explicitly choose a build mode.\n\nDebug, mode that produces and includes debugging information in the output of the build process (i.e. the binary file defined by the target object);\nReleaseSmall, mode that tries to produce a binary file that is small in size;\nReleaseFast, mode that tries to optimize your code, in order to produce a binary file that is as fast as possible;\nReleaseSafe, mode that tries to make your code as safe as possible, by including safeguards when possible.\n\nSo, when you build your project, you can set the build mode of your target object to ReleaseFast for example, which will tell the zig compiler to apply important optimizations in your code. This creates a binary file that simply runs faster on most contexts, because it contains a more optimized version of your code. However, as a result, we often lose some safety features in our code. Because some safety checks are removed from the final binary file, which makes your code run faster, but in a less safe manner.\nThis choice depends on your current priorities. If you are building a cryptography or banking system, you might prefer to prioritize safety in your code, so, you would choose the ReleaseSafe build mode, which is a little slower to run, but much more secure, because it includes all possible runtime safety checks in the binary file built in the build process. In the other hand, if you are writing a game for example, you might prefer to prioritize performance over safety, by using the ReleaseFast build mode, so that your users can experience faster frame rates in your game.\nIn the example below, we are creating the same target object that we have used on previous examples. But this time, we are specifying the build mode of this target object to the ReleaseSafe mode.\n\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .optimize = .ReleaseSafe\n});\nb.installArtifact(exe);",
+    "crumbs": [
+      "<span class='chapter-number'>9</span>  <span class='chapter-title'>Build System</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/07-build-system.html#setting-the-version-of-your-build",
+    "href": "Chapters/07-build-system.html#setting-the-version-of-your-build",
+    "title": "9  Build System",
+    "section": "9.5 Setting the version of your build",
+    "text": "9.5 Setting the version of your build\nEverytime you build a target object in your build script, you can assign a version number to this specific build, following a semantic versioning framework. You can find more about semantic versioning by visiting the Semantic Versioning website5. Anyway, in Zig, you can specify the version of your build, by providing a SemanticVersion struct to the version option, like in the example below:\n\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .version = .{\n        .major = 2, .minor = 9, .patch = 7\n    }\n});\nb.installArtifact(exe);",
+    "crumbs": [
+      "<span class='chapter-number'>9</span>  <span class='chapter-title'>Build System</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/07-build-system.html#sec-detect-os",
+    "href": "Chapters/07-build-system.html#sec-detect-os",
+    "title": "9  Build System",
+    "section": "9.6 Detecting the OS in your build script",
+    "text": "9.6 Detecting the OS in your build script\nIs very common in Build Systems to use different options, or, to include different modules, or, to link against different libraries depending on the Operational System (OS) that you are targeting in the build process.\nIn Zig, you can detect the target OS of the build process, by looking at the os.tag inside the builtin module from the Zig library. In the example below, we are using an if statement to run some arbitrary code when the target of the build process is a Windows system.\n\nconst builtin = @import(\"builtin\");\nif (builtin.target.os.tag == .windows) {\n    // Code that runs only when the target of\n    // the compilation process is Windows.\n}",
+    "crumbs": [
+      "<span class='chapter-number'>9</span>  <span class='chapter-title'>Build System</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/07-build-system.html#adding-a-run-step-to-your-build-process",
+    "href": "Chapters/07-build-system.html#adding-a-run-step-to-your-build-process",
+    "title": "9  Build System",
+    "section": "9.7 Adding a run step to your build process",
+    "text": "9.7 Adding a run step to your build process\nOne thing that is neat in Rust is that you can compile and run your source code with one single command (cargo run) from the Rust compiler. We saw at Section 1.2.5 how can we perform a similar job in Zig, by building and running our Zig source code through the run command from the zig compiler.\nBut how can we, at the same time, build and run the binary file specified by a target object in our build script? The answer is by including a “run artifact” in our build script. A run artifact is created through the addRunArtifact() method from the Build struct. We simply provide as input to this function the target object that describes the binary file that we want to execute. As a result, this function creates a run artifact that is capable of executing this binary file.\nIn the example below, we are defining an executable binary file named hello, and we use this addRunArtifact() method to create a run artifact that will execute this hello executable file.\n\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"src/hello.zig\"),\n    .target = b.host\n});\nb.installArtifact(exe);\nconst run_arti = b.addRunArtifact(exe);\n\nNow that we have created this run artifact, we need to include it in the build process. We do that by declaring a new step in our build script to call this artifact, through the step() method of the Build struct.\nWe can give any name we want to this step, but, for our context here, I’m going to name this step as “run”. Also, I give it a brief description to this step (“Run the project”).\n\nconst run_step = b.step(\n    \"run\", \"Run the project\"\n);\n\nNow that we have declared this “run step” we need to tell Zig that this “run step” depends on the run artifact. In other words, a run artifact always depends on a “step” to effectively be executed. By creating this dependency we finally stablish the necessary commands to build and run the executable file from the build script.\nWe can establish a dependency between the run step and the run artifact by using the dependsOn() method from the run step. So, we first create the run step, and then, we link it with the run artifact, by using this dependsOn() method from the run step.\n\nrun_step.dependOn(&run_arti.step);\n\nThe entire source code of this specific build script that we wrote, piece by piece, in this section, is available in the build_and_run.zig module. You can see this module by visiting the official repository of this book 6.\nWhen you declare a new step in your build script, this step becomes available through the build command in the zig compiler. You can actually see this step by running zig build --help in the terminal, like in the example below, where we can see that this new “run” step that we declared in the build script appeared in the output.\nzig build --help\nSteps:\n  ...\n  run   Run the project\n  ...\nNow, everything that we need to is to call this “run” step that we created in our build script. We call it by using the name that we gave to this step after the build command from the zig compiler. This will cause the compiler to build our executable file and execute it at the same time.\nzig build run",
+    "crumbs": [
+      "<span class='chapter-number'>9</span>  <span class='chapter-title'>Build System</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/07-build-system.html#build-unit-tests-in-your-project",
+    "href": "Chapters/07-build-system.html#build-unit-tests-in-your-project",
+    "title": "9  Build System",
+    "section": "9.8 Build unit tests in your project",
+    "text": "9.8 Build unit tests in your project\nWe have talked at length about writing unit tests in Zig at Chapter 8, and we also have talked about how to execute these unit tests through the test command of the zig compiler. However, as we did with the run command on the previous section, we also might want to include some commands in our build script to also build and execute the unit tests in our project.\nSo, once again, we are going to discuss how a specific built-in command from the zig compiler, (in this case, the test command) can be used in a build script in Zig. Here is where a “test target object” comes into play. As was described at Section 9.3, we can create a test target object by using the addTest() method of the Build struct. The first thing that we need to do is to declare a test target object in our build script.\n\nconst test_exe = b.addTest(.{\n    .name = \"unit_tests\",\n    .root_source_file = b.path(\"src/main.zig\"),\n    .target = b.host,\n});\nb.installArtifact(test_exe);\n\nA test target object essentially selects all test blocks in all Zig modules across your project, and builds only the source code present inside these test blocks in your project. As a result, this target object creates an executable file that contains only the source code present in all of these test blocks (i.e. the unit tests) in your project.\nPerfect! Now that we have declared this test target object, an executable file named unit_tests is built by the zig compiler when we trigger the build script with the build command. After the build process is finished, we can simply execute this unit_tests executable in the terminal.\nHowever, if you remember the previous section, we already learned how can we create a run step in our build script, to execute an executable file built by the build script.\nSo, we could simply add a run step in our build script to run these unit tests from a single command in the zig compiler, to make our lifes easier. In the example below, we demonstrate the commands to register a new build step called “tests” in our build script to run these unit tests.\n\nconst run_arti = b.addRunArtifact(test_exe);\nconst run_step = b.step(\"tests\", \"Run unit tests\");\nrun_step.dependOn(&run_arti.step);\n\nNow that we registered this new build step, we can trigger it by calling the command below in the terminal. You can also checkout the complete source code for this specific build script at the build_tests.zig module at the official repository of this book 7.\nzig build tests",
+    "crumbs": [
+      "<span class='chapter-number'>9</span>  <span class='chapter-title'>Build System</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/07-build-system.html#tailoring-your-build-process-with-user-provided-options",
+    "href": "Chapters/07-build-system.html#tailoring-your-build-process-with-user-provided-options",
+    "title": "9  Build System",
+    "section": "9.9 Tailoring your build process with user-provided options",
+    "text": "9.9 Tailoring your build process with user-provided options\nSometimes, you want to make a build script that is customizable by the user of your project. You can do that by creating user-provided options in your build script. We create an user-provided option by using the option() method from the Build struct.\nWith this method, we create a “build option” which can be passed to the build.zig script at the command line. The user have the power of setting this option at the build command from the zig compiler. In other words, each build option that we create becomes a new command line argument that is accessible through the build command of the compiler.\nThese “user-provided options” are set by using the prefix -D in the command line. For example, if we declare an option named use_zlib, that receives a boolean value which indicates if we should link our source code to zlib or not, we can set the value of this option in the command line with -Duse_zlib. The code example below demonstrates this idea:\n\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const use_zlib = b.option(\n        bool,\n        \"use_zlib\",\n        \"Should link to zlib?\"\n    ) orelse false;\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"example.zig\"),\n        .target = b.host,\n    });\n    if (use_zlib) {\n        exe.linkSystemLibrary(\"zlib\");\n    }\n    b.installArtifact(exe);\n}\n\nzig build -Duse_zlib=false",
+    "crumbs": [
+      "<span class='chapter-number'>9</span>  <span class='chapter-title'>Build System</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/07-build-system.html#linking-to-external-libraries",
+    "href": "Chapters/07-build-system.html#linking-to-external-libraries",
+    "title": "9  Build System",
+    "section": "9.10 Linking to external libraries",
+    "text": "9.10 Linking to external libraries\nOne essential part of every build process is the linking stage. This stage is responsible for combining the multiple object files that represent your code, into a single executable file. It also links this executable file to external libraries, if you use any in your code.\nIn Zig, we have two notions of a “library”, which are: 1) a system’s library; 2) a local library. A system’s library is just a library that already is installed in your system. While a local library is a library that belongs to the current project. Is a library that is present in your project directory, and that you are building together with your project source code.\nThe basic difference between the two, is that a system’s library is already built and installed in your system, supposedly, and all you need to do is to link your source code to this library to start using it. We do that by using the linkSystemLibrary() method from a Compile object. This method accepts the name of the library in a string as input. Remember from Section 9.3 that a Compile object is a target object that you declare in your build script.\nWhen you link a particular target object with a system’s library, the zig compiler will use pkg-config to find where are the binary files and also the header files of this library in your system. When it finds these files, the linker present in the zig compiler will link your object files with the files of this library to produce a single binary file for you.\nIn the example below, we are creating an executable file named image_filter, and, we are linking this executable file to the C Standard Library with the method linkLibC(), but we also are linking this executable file to the C library libpng that is currently installed in my system.\n\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"image_filter\",\n        .root_source_file = b.path(\"src/main.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n    exe.linkLibC();\n    exe.linkSystemLibrary(\"png\");\n    b.installArtifact(exe);\n}\n\nIf you are linking with a C library in your project, is generally a good idea to also link your code with the C Standard Library. Because is very likely that this C library uses some functionality of the C Standard Library at some point. The same goes to C++ libraries. So, if you are linking with C++ libraries, is a good idea to link your project with the C++ Standard Library by using the linkLibCpp() method.\nOn the order side, when you want to link with a local library, you should use the linkLibrary() method of a Compile object. This method expects to receive another Compile object as input. That is, another target object defined in your build script, using either the addStaticLibrary() or addSharedLibrary() methods which defines a library to be built.\nAs we discussed earlier, a local library is a library that is local to your project, and that is being built together with your project. So, you need to create a target object in your build script to build this local library. Then, you link the target objects of interest in your project, with this target object that identifies this local library.\nTake a look at this example extracted from the build script of the libxev library8. You can see in this snippet that we are declaring a shared library file, from the c_api.zig module. Then, later in the build script, we declare an executable file named \"dynamic-binding-test\", which links to this shared library that we defined earlier in the script.\n\nconst optimize = b.standardOptimizeOption(.{});\nconst target = b.standardTargetOptions(.{});\n\nconst dynamic_lib = b.addSharedLibrary(.{\n    .name = dynamic_lib_name,\n    .root_source_file = b.path(\"src/c_api.zig\"),\n    .target = target,\n    .optimize = optimize,\n});\nb.installArtifact(dynamic_lib);\n// ... more lines in the script\nconst dynamic_binding_test = b.addExecutable(.{\n    .name = \"dynamic-binding-test\",\n    .target = target,\n    .optimize = optimize,\n});\ndynamic_binding_test.linkLibrary(dynamic_lib);",
+    "crumbs": [
+      "<span class='chapter-number'>9</span>  <span class='chapter-title'>Build System</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/07-build-system.html#sec-building-c-code",
+    "href": "Chapters/07-build-system.html#sec-building-c-code",
+    "title": "9  Build System",
+    "section": "9.11 Building C code",
+    "text": "9.11 Building C code\nThe zig compiler comes with a C compiler embedded in it. In other words, you can use the zig compiler to build C projects. This C compiler is available through the cc command of the zig compiler.\nAs an example, let’s use the famous FreeType library9. FreeType is one of the most widely used pieces of software in the world. It is a C library designed to produce high-quality fonts. But it is also heavily used in the industry to natively render text and fonts in the screen of your computer.\nIn this section, we are going to write a build script, piece by piece, that is capable of building the FreeType project from source. You can find the source code of this build script on the freetype-zig repository10 available at GitHub.\nAfter you download the source code of FreeType from the official website11, you can start writing the build.zig module. We begin by defining the target object that defines the binary file that we want to compile.\nAs an example, I will build the project as a static library file using the addStaticLibrary() method to create the target object. Also, since FreeType is a C library, I will also link the library against libc through the linkLibC() method, to guarantee that any use of the C Standard Library is covered in the compilation process.\n\nconst target = b.standardTargetOptions(.{});\nconst opti = b.standardOptimizeOption(.{});\nconst lib = b.addStaticLibrary(.{\n    .name = \"freetype\",\n    .optimize = opti,\n    .target = target,\n});\nlib.linkLibC();\n\n\n9.11.1 Creating C compiler flags\nCompiler flags are also known as “compiler options” by many programmers, or also, as “command options” in the GCC official documentation. It’s fair to also call them as the “command-line arguments” of the C compiler. In general, we use compiler flags to turn on (or turn off) some features from the compiler, or to tweak the compilation process to fit the needs of our project.\nIn build scripts written in Zig, we normally list the C compiler flags to be used in the compilation process in a simple array, like in the example below.\n\nconst c_flags = [_][]const u8{\n    \"-Wall\",\n    \"-Wextra\",\n    \"-Werror\",\n};\n\nIn theory, there is nothing stopping you from using this array to add “include paths” (with the -I flag) or “library paths” (with the -L flag) to the compilation process. But there are formal ways in Zig to add these types of paths in the compilation process. Both are discussed at Section 9.11.5 and Section 9.11.4.\nAnyway, in Zig, we add C flags to the build process together with the C files that we want to compile, by using the addCSourceFile() and addCSourceFiles() methods. In the example above, we have just declared the C flags that we want to use. But we haven’t added them to the build process yet. To do that, we also need to list the C files to be compiled.\n\n\n9.11.2 Listing your C files\nThe C files that contains “cross-platform” source code are listed in the c_source_files object below. These are the C files that are included by default in every platform supported by the FreeType library. Now, since the amount of C files in the FreeType library is big, I have omitted the rest of the files in the code example below, for brevity purposes.\n\nconst c_source_files = [_][]const u8{\n    \"src/autofit/autofit.c\",\n    \"src/base/ftbase.c\",\n    // ... and many other C files.\n};\n\nNow, in addition to “cross-platform” source code, we also have some C files in the FreeType project that are platform-specific, meaning that, they contain source code that can only be compiled in specific platforms, and, as a result, they are only included in the build process on these specific target platforms. The objects that list these C files are exposed in the code example below.\n\nconst windows_c_source_files = [_][]const u8{\n    \"builds/windows/ftdebug.c\",\n    \"builds/windows/ftsystem.c\"\n};\nconst linux_c_source_files = [_][]const u8{\n    \"src/base/ftsystem.c\",\n    \"src/base/ftdebug.c\"\n};\n\nNow that we declared both the files that we want to include and the C compiler flags to be used, we can add them to the target object that describes the FreeType library, by using the addCSourceFile() and addCSourceFiles() methods.\nBoth of these functions are methods from a Compile object (i.e. a target object). The addCSourceFile() method is capable of adding a single C file to the target object, while the addCSourceFiles() method is used to add multiple C files in a single command. You might prefer to use addCSourceFile() when you need to use different compiler flags on specific C files in your project. But, if you can use the same compiler flags across all C files, then, you will probably find addCSourceFiles() a better choice.\nNotice that we are using the addCSourceFiles() method in the example below, to add both the C files and the C compiler flags. Also notice that we are using the os.tag that we learned about at Section 9.6, to add the platform-specific C files.\n\nconst builtin = @import(\"builtin\");\nlib.addCSourceFiles(\n    &c_source_files, &c_flags\n);\n\nswitch (builtin.target.os.tag) {\n    .windows =&gt; {\n        lib.addCSourceFiles(\n            &windows_c_source_files,\n            &c_flags\n        );\n    },\n    .linux =&gt; {\n        lib.addCSourceFiles(\n            &linux_c_source_files,\n            &c_flags\n        );\n    },\n    else =&gt; {},\n}\n\n\n\n9.11.3 Defining C Macros\nC Macros are an essential part of the C programming language, and they are commonly defined through the -D flag from a C compiler. In Zig, you can define a C Macro to be used in your build process by using the defineCMacro() method from the target object that defines the binary file that you are building.\nIn the example below, we are using the lib object that we have defined on the previous sections to define some C Macros used by the FreeType project in the compilation process. These C Macros specify if FreeType should (or should not) include functionalities from different external libraries.\n\nlib.defineCMacro(\"FT_DISABLE_ZLIB\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_PNG\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_HARFBUZZ\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BZIP2\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BROTLI\", \"TRUE\");\nlib.defineCMacro(\"FT2_BUILD_LIBRARY\", \"TRUE\");\n\n\n\n9.11.4 Adding library paths\nLibrary paths are paths in your computer where the C compiler will look (or search) for library files to link against your source code. In other words, when you use a library in your C source code, and you ask the C compiler to link your source code against this library, the C compiler will search for the binary files of this library across the paths listed in this “library paths” set.\nThese paths are platform specific, and, by default, the C compiler starts by looking at a pre-defined set of places in your computer. But you can add more paths (or more places) to this list. For example, you may have a library installed in a non-conventional place of your computer, and you can make the C compiler “see” this “non-conventional place” by adding this path to this list of pre-defined paths.\nIn Zig, you can add more paths to this set by using the addLibraryPath() method from your target object. First, you defined a LazyPath object, containing the path you want to add, then, you provide this object as input to the addLibraryPath() method, like in the example below:\n\nconst lib_path: std.Build.LazyPath = .{\n    .cwd_relative = \"/usr/local/lib/\"\n};\nlib.addLibraryPath(lib_path);\n\n\n\n9.11.5 Adding include paths\nThe preprocessor search path is a popular concept from the C community, but it is also known by many C programmers as “include paths”, because the paths in this “search path” relate to the #include statements found in the C files.\nInclude paths are similar to library paths. They are a set of pre-defined places in your computer where the C compiler will look for files during the compilation process. But instead of looking for library files, the include paths are places where the compiler looks for header files included in your C source code. This is why many C programmers prefer to call these paths as the “preprocessor search path”. Because header files are processed during the preprocessor stage of the compilation process.\nSo, every header file that you include in your C source code, through a #include statements needs to be found somewhere, and the C compiler will search for this header file across the paths listed in this “include paths” set. Include paths are added to the compilation process through the -I flag.\nIn Zig, you can add new paths to this pre-defined set of paths, by using the addIncludePath() method from your target object. This method also accepts a LazyPath object as input.\n\nconst inc_path: std.Build.LazyPath = .{\n    .path = \"./include\"\n};\nlib.addIncludePath(inc_path);",
+    "crumbs": [
+      "<span class='chapter-number'>9</span>  <span class='chapter-title'>Build System</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/07-build-system.html#footnotes",
+    "href": "Chapters/07-build-system.html#footnotes",
+    "title": "9  Build System",
+    "section": "",
+    "text": "https://ziglang.org/learn/build-system/#user-provided-options↩︎\nhttps://zig.news/xq/zig-build-explained-part-1-59lf↩︎\nhttps://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html↩︎\nhttps://ziglang.org/learn/build-system/#handy-examples↩︎\nhttps://semver.org/↩︎\nhttps://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig↩︎\nhttps://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig↩︎\nhttps://github.com/mitchellh/libxev/tree/main↩︎\nhttps://freetype.org/↩︎\nhttps://github.com/pedropark99/freetype-zig/tree/main↩︎\nhttps://freetype.org/↩︎",
+    "crumbs": [
+      "<span class='chapter-number'>9</span>  <span class='chapter-title'>Build System</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/09-error-handling.html",
+    "href": "Chapters/09-error-handling.html",
+    "title": "10  Error handling and unions",
+    "section": "",
+    "text": "10.1 Learning more about errors in Zig\nBefore we get into how error handling is done, we need to learn more about what errors are in Zig. An error is actually a value in Zig (Zig Software Foundation 2024a). In other words, when an error occurs inside your Zig program, it means that somewhere in your Zig codebase, an error value is being generated. An error value is similar to any integer value that you create in your Zig code. You can take an error value and pass it as input to a function, and you can also cast (or coerce) it into a different type of an error value.\nThis have some similarities with exceptions in C++ and Python. Because in C++ and Python, when an exception happens inside a try block, you can use a catch block (in C++) or an except block (in Python) to capture the exception produced in the try block, and pass it to functions as an input.\nHowever, error values in Zig are treated very differently than exceptions. First, you cannot ignore error values in your Zig code. Meaning that, if an error value appears somewhere in your source code, this error value must be explicitly handled in some way. This also means that you cannot discard error values by assigning them to an underscore, as you could do with normal values and objects.\nTake the source code below as an example. Here we are trying to open a file that does not exist in my computer, and as a result, an obvious error value of FileNotFound is returned from the openFile() function. But because I’m assigning the result of this function to an underscore, I end up trying to discard an error value.\nThe zig compiler detects this mistake, and raises a compile error telling me that I’m trying to discard an error value. It also adds a note message that suggests the use of try, catch or an if statement to explicitly handle this error value This note is reinforcing that every possible error value must be explicitly handled in Zig.\nconst dir = std.fs.cwd();\n_ = dir.openFile(\"doesnt_exist.txt\", .{});",
+    "crumbs": [
+      "<span class='chapter-number'>10</span>  <span class='chapter-title'>Error handling and unions</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/09-error-handling.html#learning-more-about-errors-in-zig",
+    "href": "Chapters/09-error-handling.html#learning-more-about-errors-in-zig",
+    "title": "10  Error handling and unions",
+    "section": "",
+    "text": "t.zig:8:17: error: error set is discarded\nt.zig:8:17: note: consider using 'try', 'catch', or 'if'\n\n10.1.1 Returning errors from functions\nAs we described at Section 1.2.3, when we have a function that might return an error value, this function normally includes an exclamation mark (!) in its return type annotation. The presence of this exclamation mark indicates that this function might return an error value as result, and, the zig compiler forces you to always handle explicitly the case of this function returning an error value.\nTake a look at the print_name() function below. This function might return an error in the stdout.print() function call, and, as a consequence, its return type (!void) includes an exclamation mark in it.\n\nfn print_name() !void {\n    const stdout = std.getStdOut().writer();\n    try stdout.print(\"My name is Pedro!\", .{});\n}\n\nIn the example above, we are using the exclamation mark to tell the zig compiler that this function might return some error. But which error exactly is returned from this function? For now, we are not specifying a specific error value. We only known for now that some error value (whatever it is) might be returned.\nBut in fact, you can (if you want to) specify clearly which exact error values might be returned from this function. There are lot of examples of this in the Zig Standard Library. Take this fill() function from the http.Client module as an example. This function returns either a error value of type ReadError, or void.\n\npub fn fill(conn: *Connection) ReadError!void {\n    // The body of this function ...\n}\n\nThis idea of specifying the exact error values that you expect to be returned from the function is interesting. Because they automatically become some sort of documentation of your function, and also, it allows the zig compiler to perform some extra checks over your code. Because it can check if there is any other type of error value that is being generated inside your function, and, that it is not being accounted for in this return type annotation.\nAnyway, you can list the types of errors that can be returned from the function by listing them on the left side of the exclamation mark. While the valid values stay on the right side of the exclamation mark. So the syntax format become:\n&lt;error-value&gt;!&lt;valid-value&gt;\n\n\n10.1.2 Error sets\nBut what about when we have a single function that might return different types of errors? When you have such a function, you can list all of these different types of errors that can be returned from this function, through a structure in Zig that we call of an error set.\nAn error set is a special case of an union type. It is an union that contains error values in it. Not all programming languages have a notion of an “union object”. But in summary, an union is just a set of data types. Unions are used to allow an object to have multiple data types. For example, a union of x, y and z, means that an object can be either of type x, or type y or type z.\nWe are going to talk in more depth about unions at Section 10.3. But you can write an error set by writing the keyword error before a pair of curly braces, then you list the error values that can be returned from the function inside this pair of curly braces.\nTake the resolvePath() function below as an example, which comes from the introspect.zig module of the Zig Standard Library. We can see in its return type annotation, that this function return either: 1) a valid slice of u8 values ([]u8); or, 2) one of the three different types of error values listed inside the error set (OutOfMemory, Unexpected, etc.). This is an usage example of an error set.\n\npub fn resolvePath(\n    ally: mem.Allocator,\n    p: []const u8,\n) error{\n    OutOfMemory,\n    CurrentWorkingDirectoryUnlinked,\n    Unexpected,\n}![]u8 {\n    // The body of the function ...\n}\n\nThis is a valid way of annotating the return value of a Zig function. But, if you navigate through the modules that composes the Zig Standard Library, you will notice that, for the majority of cases, the programmers prefer to give a descriptive name to this error set, and then, use this name (or this “label”) of the error set in the return type annotation, instead of using the error set directly.\nWe can see that in the ReadError error set that we showed earlier in the fill() function, which is defined in the http.Client module. So yes, I presented the ReadError as if it was just a standard and single error value, but in fact, it is an error set defined in the http.Client module, and therefore, it actually represents a set of different error values that might happen inside the fill() function.\nTake a look at the ReadError definition reproduced below. Notice that we are grouping all of these different error values into a single object, and then, we use this object into the return type annotation of the function. Like the fill() function that we showed earlier, or, the readvDirect() function from the same module, which is reproduced below.\n\npub const ReadError = error{\n    TlsFailure,\n    TlsAlert,\n    ConnectionTimedOut,\n    ConnectionResetByPeer,\n    UnexpectedReadFailure,\n    EndOfStream,\n};\n// Some lines of code\npub fn readvDirect(\n        conn: *Connection,\n        buffers: []std.posix.iovec\n    ) ReadError!usize {\n    // The body of the function ...\n}\n\nSo, an error set is just a convenient way of grouping a set of possible error values into a single object, or a single type of an error value.\n\n\n10.1.3 Casting error values\nLet’s suppose you have two different error sets, named A and B. If error set A is a superset of error set B, then, you can cast (or coerce) error values from B into error values of A.\nError sets are just a set of error values. So, if the error set A contains all error values from the error set B, then A becomes a superset of B. You could also say that the error set B is a subset of error set A.\nThe example below demonstrates this idea. Because A contains all values from B, A is a superset of B. In math notation, we would say that \\(A \\supset B\\). As a consequence, we can give an error value from B as input to the cast() function, and, implicitly cast this input into the same error value, but from the A set.\n\nconst std = @import(\"std\");\nconst A = error{\n    ConnectionTimeoutError,\n    DatabaseNotFound,\n    OutOfMemory,\n    InvalidToken,\n};\nconst B = error {\n    OutOfMemory,\n};\n\nfn cast(err: B) A {\n    return err;\n}\n\ntest \"coerce error value\" {\n    const error_value = cast(B.OutOfMemory);\n    try std.testing.expect(\n        error_value == A.OutOfMemory\n    );\n}\n\n1/1 file10459ffd0e21.test.coerce error value...OKA\n  All 1 tests passed.",
+    "crumbs": [
+      "<span class='chapter-number'>10</span>  <span class='chapter-title'>Error handling and unions</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/09-error-handling.html#how-to-handle-errors",
+    "href": "Chapters/09-error-handling.html#how-to-handle-errors",
+    "title": "10  Error handling and unions",
+    "section": "10.2 How to handle errors",
+    "text": "10.2 How to handle errors\nNow that we learned more about what errors are in Zig, let’s discuss the available strategies to handle these errors, which are:\n\ntry keyword;\ncatch keyword;\nan if statement;\nerrdefer keyword;\n\n\n10.2.1 What try means?\nAs I described over the previous sections, when we say that an expression might return an error, we are basically referring to an expression that have a return type in the format !T. The ! indicates that this expression returns either an error value, or a value of type T.\nAt Section 1.2.3, I presented the try keyword and where to use it. But I did not talked about what exactly this keyword does to your code, or, in other words, I have not explained yet what try means in your code.\nIn essence, when you use the try keyword in an expression, you are telling the zig compiler the following: “Hey! Execute this expression for me, and, if this expression return an error, please, return this error for me and stop the execution of my program. But if this expression return a valid value, then, return this value, and move on”.\nIn other words, the try keyword is essentially, a strategy to enter in panic mode, and stop the execution of your program in case an error occurs. With the try keyword, you are telling the zig compiler, that stopping the execution of your program is the most reasonable strategy to take if an error occurs in that particular expression.\n\n\n10.2.2 The catch keyword\nOk, now that we understand properly what try means, let’s discuss catch now. One important detail here, is that you can use try or catch to handle your errors, but you cannot use try and catch together. In other words, try and catch are different and completely separate strategies in the Zig language.\nThis is uncommon, and different than what happens in other languages. Most programming languages that adopts the try catch pattern (such as C++, R, Python, Javascript, etc.), normally use these two keywords together to form the complete logic to properly handle the errors. Anyway, Zig tries a different approach in the try catch pattern.\nSo, we learned already about what try means, and we also known that both try and catch should be used alone, separate from each other. But what exactly catch do in Zig? With catch, we can construct a block of logic to handle the error value, in case it happens in the current expression.\nLook at the code example below. Once again, we go back to the previous example where we were trying to open a file that doesn’t exist in my computer, but this time, I use catch to actually implement a logic to handle the error, instead of just stopping the execution right away.\nMore specifically, in this example, I’m using a logger object to record some logs into the system, before I return the error, and stop the execution of the program. For example, this could be some part of the codebase of a complex system that I do not have full control over, and I want to record these logs before the program crashes, so that I can debug it later (e.g. maybe I cannot compile the full program, and properly debug it with a debugger. So, these logs might be a valid strategy to surpass this barrier).\n\nconst dir = std.fs.cwd();\nconst file = dir.openFile(\n    \"doesnt_exist.txt\", .{}\n) catch |err| {\n    logger.record_context();\n    logger.log_error(err);\n    return err;\n};\n\nTherefore, we use catch to create a block of expressions that will handle the error. I can return the error value from this block of expressions, like I did in the above example, which, will make the program enter in panic mode, and, stop the execution. But I could also, return a valid value from this block of code, which would be stored in the file object.\nNotice that, instead of writing the keyword before the expression that might return the error, like we do with try, we write catch after the expression. We can open the pair of pipes (|), which captures the error value returned by the expression, and makes this error value available in the scope of the catch block as the object named err. In other words, because I wrote |err| in the code, I can access the error value returned by the expression, by using the err object.\nAlthough this being the most common use of catch, you can also use this keyword to handle the error in a “default value” style. That is, if the expression returns an error, we use the default value instead. Otherwise, we use the valid value returned by the expression.\nThe Zig official language reference, provides a great example of this “default value” strategy with catch. This example is reproduced below. Notice that we are trying to parse some unsigned integer from a string object named str. In other words, this function is trying to transform an object of type []const u8 (i.e. an array of characters, a string, etc.) into an object of type u64.\nBut this parsing process done by the function parseU64() may fail, resulting in a runtime error. The catch keyword used in this example provides an alternative value (13) to be used in case this parseU64() function raises an error. So, the expression below essentially means: “Hey! Please, parse this string into a u64 for me, and store the results into the object number. But, if an error occurs, then, use the value 13 instead”.\n\nconst number = parseU64(str, 10) catch 13;\n\nSo, at the end of this process, the object number will contain either a u64 integer that was parsed successfully from the input string str, or, if an error occurs in the parsing process, it will contain the u64 value 13 that was provided by the catch keyword as the “default”, or, the “alternative” value.\n\n\n10.2.3 Using if statements\nNow, you can also use if statements to handle errors in your Zig code. In the example below, I’m reproducing the previous example, where we try to parse an integer value from an input string with a function named parseU64().\nWe execute the expression inside the “if”. If this expression returns an error value, the “if branch” (or, the “true branch”) of the if statement is not executed. But if this expression returns a valid value instead, then, this value is unwrapped into the number object.\nThis means that, if the parseU64() expression returns a valid value, this value becomes available inside the scope of this “if branch” (i.e. the “true branch”) through the object that we listed inside the pair of pipe character (|), which is the object number.\nIf an error occurs, we can use an “else branch” (or the “false branch”) of the if statement to handle the error. In the example below, we are using the else in the if statement to unwrap the error value (that was returned by parseU64()) into the err object, and handle the error.\n\nif (parseU64(str, 10)) |number| {\n    // do something with `number` here\n} else |err| {\n    // handle the error value.\n}\n\nNow, if the expression that you are executing returns different types of error values, and you want to take a different action in each of these types of error values, the try and catch keywords, and the if statement strategy, becomes limited.\nFor this type of situation, the official documentation of the language suggests the use of a switch statement together with an if statement (Zig Software Foundation 2024b). The basic idea is, to use the if statement to execute the expression, and use the “else branch” to pass the error value to a switch statement, where you define a different action for each type of error value that might be returned by the expression executed in the if statement.\nThe example below demonstrates this idea. We first try to add (or register) a set of tasks to a queue. If this “registration process” occurs well, we then try to distribute these tasks across the workers of our system. But if this “registration process” returns an error value, we then use a switch statement in the “else branch” to handle each possible error value.\n\nif (add_tasks_to_queue(&queue, tasks)) |_| {\n    distribute_tasks(&queue);\n} else |err| switch (err) {\n    error.InvalidTaskName =&gt; {\n        // do something\n    },\n    error.TimeoutTooBig =&gt; {\n        // do something\n    },\n    error.QueueNotFound =&gt; {\n        // do something\n    },\n    // and all the other error options ...\n}\n\n\n\n10.2.4 The errdefer keyword\nA common pattern in C programs in general, is to clean resources when an error occurs during the execution of the program. In other words, one common way to handle errors, is to perform “cleanup actions” before we exit our program. This guarantees that a runtime error does not make our program to leak resources of the system.\nThe errdefer keyword is a tool to perform such “cleanup actions” in hostile situations. This keyword is commonly used to clean (or to free) allocated resources, before the execution of our program get’s stopped because of an error value being generated.\nThe basic idea is to provide an expression to the errdefer keyword. Then, errdefer executes this expression if, and only if, an error occurs during the execution of the current scope. In the example below, we are using an allocator object (that we have presented at Section 3.3) to create a new User object. If we are successful in creating and registering this new user, this create_user() function will return this new User object as its return value.\nHowever, if for some reason, an error value is generated by some expression that is after the errdefer line, for example, in the db.add(user) expression, the expression registered by errdefer get’s executed before the error value is returned from the function, and before the program enters in panic mode and stops the current execution.\n\nfn create_user(db: Database, allocator: Allocator) !User {\n    const user = try allocator.create(User);\n    errdefer allocator.destroy(user);\n\n    // Register new user in the Database.\n    _ = try db.register_user(user);\n    return user;\n}\n\nBy using errdefer to destroy the user object that we have just created, we guarantee that the memory allocated for this user object get’s freed, before the execution of the program stops. Because if the expression try db.add(user) returns an error value, the execution of our program stops, and we lose all references and control over the memory that we have allocated for the user object. As a result, if we do not free the memory associated with the user object before the program stops, we cannot free this memory anymore. We simply lose our chance to do the right thing. That is why errdefer is essential in this situation.\nJust to state clearly the differences between defer and errdefer (which I described at Section 2.1.3 and Section 2.1.4), it might be worth to discuss the subject a bit further. You might still have the question “why use errdefer if we can use defer instead?” in your mind.\nAlthough being similar, the key difference between errdefer and defer keyword is when the provided expression get’s executed. The defer keyword always execute the provided expression at the end of the current scope, no matter how your code exits this scope. In contrast, errdefer executes the provided expression only when an error occurs in the current scope.\nThis becomes important if a resource that you allocate in the current scope get’s freed later in your code, in a different scope. The create_user() functions is an example of this. If you think closely about this function, you will notice that this function returns the user object as the result.\nIn other words, the allocated memory for the user object does not get freed inside the create_user() function, if it returns successfully. So, if an error does not occur inside this function, the user object is returned from the function, and probably, the code that runs after this create_user() function will be responsible for freeing the memory of the user object.\nBut what if an error occurs inside the create_user() function? What happens then? This would mean that the execution of your code would stop in this create_user() function, and, as a consequence, the code that runs after this create_user() function would simply not run, and, as a result, the memory of the user object would not be freed before your program stops.\nThis is the perfect scenario for errdefer. We use this keyword to guarantee that our program will free the allocated memory for the user object, even if an error occurs inside the create_user() function.\nIf you allocate and free some memory for an object inside the same scope, then, just use defer and be happy, i.e. errdefer have no use for you in such situation. But if you allocate some memory in a scope A, but you only free this memory later, in a scope B for example, then, errdefer becomes useful to avoid leaking memory in sketchy situations.",
+    "crumbs": [
+      "<span class='chapter-number'>10</span>  <span class='chapter-title'>Error handling and unions</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/09-error-handling.html#sec-unions",
+    "href": "Chapters/09-error-handling.html#sec-unions",
+    "title": "10  Error handling and unions",
+    "section": "10.3 Union type in Zig",
+    "text": "10.3 Union type in Zig\nAn union type defines a set of types that an object can be. It is like a list of options. Each option is a type that an object can assume. Therefore, unions in Zig have the same meaning, or, the same role as unions in C. They are used for the same purpose. You could also say that unions in Zig produces a similar effect to using typing.Union in Python1.\nFor example, you might be creating an API that sends data to a data lake, hosted in some private cloud infrastructure. Suppose you have created different structs in your codebase, to store the necessary information that you need, in order to connect to the services of each mainstream data lake service (Amazon S3, Azure Blob, etc.).\nNow, suppose you also have a function named send_event() that receives an event as input, and, a target data lake, and it sends the input event to the data lake specified in the target data lake argument. But this target data lake could be any of the three mainstream data lakes services (Amazon S3, Azure Blob, etc.). Here is where an union can help you.\nThe union LakeTarget defined below allows the lake_target argument of send_event() to be either an object of type AzureBlob, or type AmazonS3, or type GoogleGCP. This union allows the send_event() function to receive an object of any of these three types as input in the lake_target argument.\nRemember that each of these three types (AmazonS3, GoogleGCP and AzureBlob) are separate structs that we have defined in our source code. So, at first glance, they are separate data types in our source code. But is the union keyword that unifies them into a single data type called LakeTarget.\n\nconst LakeTarget = union {\n    azure: AzureBlob,\n    amazon: AmazonS3,\n    google: GoogleGCP,\n};\n\nfn send_event(\n    event: Event,\n    lake_target: LakeTarget\n) bool {\n    // body of the function ...\n}\n\nAn union definition is composed by a list of data members. Each data member is of a specific data type. In the example above, the LakeTarget union have three data members (azure, amazon, google). When you instantiate an object that uses an union type, you can only use one of its data members in this instantiation.\nYou could also interpret this as: only one data member of an union type can be activated at a time, the other data members remain deactivated and unaccessible. For example, if you create a LakeTarget object that uses the azure data member, you can no longer use or access the data members google or amazon. It is like if these other data members didn’t exist at all in the LakeTarget type.\nYou can see this logic in the example below. Notice that, we first instantiate the union object using the azure data member. As a result, this target object contains only the azure data member inside of it. Only this data member is active in this object. That is why the last line in this code example is invalid. Because we are trying to instantiate the data member google, which is currently inactive for this target object, and as a result, the program enters in panic mode warning us about this mistake through a loud error message.\n\nvar target = LakeTarget {\n    .azure = AzureBlob.init()\n};\n// Only the `azure` data member exist inside\n// the `target` object, and, as a result, this\n// line below is invalid:\ntarget.google = GoogleGCP.init();\n\nthread 2177312 panic: access of union field 'google' while\n    field 'azure' is active:\n    target.google = GoogleGCP.init();\n          ^\nSo, when you instantiate an union object, you must choose one of the data types (or, one of the data members) listed in the union type. In the example above, I choose to use the azure data member, and, as a result, all other data members were automatically deactivated, and you can no longer use them after you instantiate the object.\nYou can activate another data member by completely redefining the entire enum object. In the example below, I initially use the azure data member. But then, I redefine the target object to use a new LakeTarget object, which uses the google data member.\n\nvar target = LakeTarget {\n    .azure = AzureBlob.init()\n};\ntarget = LakeTarget {\n    .google = GoogleGCP.init()\n};\n\nA curious fact about union types, is that, at first, you cannot use them in switch statements (which were presented at Section 2.1.2). In other words, if you have an object of type LakeTarget for example, you cannot give this object as input to a switch statement.\nBut what if you really need to do so? What if you actually need to provide an “union object” to a switch statement? The answer to this question relies on another special type in Zig, which are the tagged unions. To create a tagged union, all you have to do is to add an enum type into your union declaration.\nAs an example of a tagged union in Zig, take the Registry type exposed below. This type comes from the grammar.zig module2 from the Zig repository. This union type lists different types of registries. But notice this time, the use of (enum) after the union keyword. This is what makes this union type a tagged union. By being a tagged union, an object of this Registry type can be used as input in a switch statement. This is all you have to do. Just add (enum) to your union declaration, and you can use it in switch statements.\n\npub const Registry = union(enum) {\n    core: CoreRegistry,\n    extension: ExtensionRegistry,\n};\n\n\n\n\n\nZig Software Foundation. 2024a. “In-Depth Overview.” Zig Software Foundation. https://ziglang.org/learn/overview/.\n\n\n———. 2024b. “Language Reference.” Zig Software Foundation. https://ziglang.org/documentation/master/.",
+    "crumbs": [
+      "<span class='chapter-number'>10</span>  <span class='chapter-title'>Error handling and unions</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/09-error-handling.html#footnotes",
+    "href": "Chapters/09-error-handling.html#footnotes",
+    "title": "10  Error handling and unions",
+    "section": "",
+    "text": "https://docs.python.org/3/library/typing.html#typing.Union↩︎\nhttps://github.com/ziglang/zig/blob/30b4a87db711c368853b3eff8e214ab681810ef9/tools/spirv/grammar.zig.↩︎",
+    "crumbs": [
+      "<span class='chapter-number'>10</span>  <span class='chapter-title'>Error handling and unions</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/09-data-structures.html",
+    "href": "Chapters/09-data-structures.html",
+    "title": "11  Data Structures",
+    "section": "",
+    "text": "11.1 Dynamic Arrays\nIn high level languages, arrays are usually dynamic. They can easily grow in size when they have to, and you don’t need to worry about it. In contrast, arrays in low level languages are usually static by default. This is the reality of C, C++, Rust and also Zig. Static arrays were presented at Section 1.6, but in this section, we are going to talk about dynamic arrays in Zig.\nDynamic arrays are simply arrays that can grow in size during the runtime of your program. Most low level languages have some implementation of a dynamic array in their standard library. C++ have std::vector, Rust have Vec, and Zig have std.ArrayList.\nThe std.ArrayList struct provides a contiguous and growable array for you. It works like any other dynamic array, it allocates a contiguous block of memory, and when this block have no space left, ArrayList allocates another contiguous and bigger block of memory, copies the elements to this new location, and erases (or frees) the previous block of memory.",
+    "crumbs": [
+      "<span class='chapter-number'>11</span>  <span class='chapter-title'>Data Structures</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/09-data-structures.html#sec-dynamic-array",
+    "href": "Chapters/09-data-structures.html#sec-dynamic-array",
+    "title": "11  Data Structures",
+    "section": "",
+    "text": "11.1.1 Capacity vs Length\nWhen we talk about dynamic arrays, we usually have two similar concepts that are very essential to how a dynamic array works behind the hood. These concepts are capacity and length. In some contexts, especially in C++, length is also called of size.\nAlthough they look similar, these concepts represent different things in the context of a dynamic array. Capacity is the number of items (or elements) that your dynamic array can currently hold without the need to allocate more memory.\nIn contrast, the length refers to how many elements in the array are currently being used, or, in other words, how many elements in this array that you have assigned a value to. Every dynamic array works around a block of allocated memory, which represents an array with total capacity for \\(n\\) elements. However, only a portion of these \\(n\\) elements are being used most of the time. This portion of \\(n\\) is the length of the array. So every time you append a new value to the array, you are incrementing its length by one.\nThis means that a dynamic array usually works with an extra margin, or, an extra space which is currently empty, but it is waiting and ready to be used. This “extra space” is essentially the difference between capacity and length. Capacity represents the total number of elements that the array can hold without the need to re-allocate or re-expand the array, while the length represents how much of this capacity is currently being used to hold/store values.\nFigure 11.1 presents this idea visually. Notice that, at first, the capacity of the array is greater than the length of the array. So, the dynamic array have extra space that is currently empty, but it is ready to receive a value to be stored.\n\n\n\n\n\n\nFigure 11.1: Difference between capacity and length in a dynamic array\n\n\n\nWe can also see at Figure 11.1 that, when length and capacity are equal, it means that the array have no space left. We have reached the ceiling of our capacity, and because of that, if we want to store more values in this array, we need to expand it. We need to get a bigger space that can hold more values than what we currently have.\nA dynamic array works by expanding the underlying array, whenever the length becomes equal to the capacity of the array. It basically allocates a new contiguous block of memory that is bigger than the previous one, then, it copies all values that are currently being stored to this new location (i.e. this new block of memory), then, it frees the previous block of memory. At the end of this process, the new underlying array have a bigger capacity, and, therefore, the length becomes, once again, smaller than the capacity of the array.\nThis is the cycle of an dynamic array. Notice that, throughout this cycle, the capacity is always either equal to or higher than the length of the array. If youh have an ArrayList object (let’s suppose you named it buffer), you can check the current capacity of your array by accessing the capacity attribute of your ArrayList object, while the current length of it is available at the items.len attribute.\n\n// Check capacity\nbuffer.capacity;\n// Check length\nbuffer.items.len;\n\n\n\n11.1.2 Creating an ArrayList object\nIn order to use ArrayList, you must provide an allocator object to it. Remember, Zig does not have a default memory allocator. And as I described at Section 3.3, all memory allocations must be done by an allocator object that you define, that you have control over. In our example here, I’m going to use a general purpose allocator, but you can use any other allocator of your preference.\nWhen you initialize an ArrayList object, you must provide the data type of the elements of the array. In other words, this defines the type of data that this array (or container) will store. Therefore, if I provide the u8 type to it, then, I will create a dynamic array of u8 values. However, if I provide a struct that I have defined instead, like the struct User from Section 2.3, then, a dynamic array of User values will be created. In the example below, with the expression ArrayList(u8) we are creating a dynamic array of u8 values.\nAfter you provide the data type of the elements of the array, you can initialize an ArrayList object by either using the init() or the initCapacity() methods. The former method receives only the allocator object as input, while the latter method receives both the allocator object and a capacity number as inputs. With the latter method, you not only initialize the struct, but you also set the starting capacity of the allocated array.\nUsing the initCapacity() method is the preferred way to initialize your dynamic array. Because reallocations, or, in other words, the process of expanding the capacity of the array, is always a high cost operation. You should take any possible opportunity to avoid reallocations in your array. If you know how much space your array needs to occupy at the beginning, you should always use initCapacity() to create your dynamic array.\n\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n\nIn the example above, the buffer object starts as an array of 100 elements. If this buffer object needs to create more space to accomodate more elements during the runtime of your program, the ArrayList internals will perform the necessary actions for you automatically. Also notice the deinit() method being used to destroy the buffer object at the end of the current scope, by freeing all the memory that was allocated for the dynamic array stored in this buffer object.\n\n\n11.1.3 Adding new elements to the array\nNow that we have created our dynamic array, we can start to use it. You can append (a.k.a “add”) new values to this array by using the append() method. This method works the same way as the append() method from a Python list, or, the emplace_back() method from std::vector of C++. You provide a single value to this method, and the method appends this value to the array.\nYou can also use the appendSlice() method to append multiple values at once. You provide a slice (slices were described at Section 1.6) to this method, and the method adds all values present in this slice to your dynamic array.\n\ntry buffer.append('H');\ntry buffer.append('e');\ntry buffer.append('l');\ntry buffer.append('l');\ntry buffer.append('o');\ntry buffer.appendSlice(\" World!\");\n\n\n\n11.1.4 Removing elements from the array\nYou can use the pop() method to “pop” or remove the last element in the array. Is worth noting that this method do not change the capacity of the array. It just deletes or erases the last value stored in the array.\nAlso, this method returns as result the value that got deleted. That is, you can use this method to both get the last value in the array, and also, remove it from the array. It is a “get and remove value” type of method.\n\nconst exclamation_mark = buffer.pop();\n\nNow, if you want to remove specific elements from specific positions of your array, you can use the orderedRemove() method from your ArrayList object. With this method, you can provide an index as input, then, the method will delete the value that is at this index in the array. You are effectively reducing the length of the array everytime you execute an orderedRemove() operation.\nIn the example below, we first create an ArrayList object, and we fill it with numbers. Then, we use orderedRemove() to remove the value at index 3 in the array, two consecutive times.\nAlso, notice that we are assigning the result of orderedRemove() to the underscore character. So we are discarding the result value of this method. The orderedRemove() method returns the value that got deleted, in a similar style to the pop() method.\n\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n\nfor (0..10) |i| {\n    const index: u8 = @intCast(i);\n    try buffer.append(index);\n}\n\nstd.debug.print(\n    \"{any}\\n\", .{buffer.items}\n);\n_ = buffer.orderedRemove(3);\n_ = buffer.orderedRemove(3);\n\nstd.debug.print(\"{any}\\n\", .{buffer.items});\nstd.debug.print(\"{any}\\n\", .{buffer.items.len});\n\n{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }\n{ 0, 1, 2, 5, 6, 7, 8, 9 }\n8\nOne key characteristic about orderedRemove() is that it preserves the order of the values in the array. So, it deletes the value that you asked it to remove, but it also makes sure that the order of the values that remain in the array stay the same as before.\nNow, if you don’t care about the order of the values, for example, maybe you want to treat your dynamic array as a set of values, like the std::unordered_set structure from C++, you can use the swapRemove() method instead. This method works similarly to the orderedRemove() method. You give an index to this method, then, it deletes the value that is at this index in the array. But this method does not preserve the original order of the values that remain in the array. As a result, swapRemove() is, in general, faster than orderedRemove().\n\n\n11.1.5 Inserting elements at specific indexes\nWhen you need to insert values in the middle of your array, instead of just appending them to the end of the array, you need to use the insert() and insertSlice() methods, instead of the append() and appendSlice() methods.\nThese two methods work very similarly to insert() and insert_range() from the C++ std::vector class. You provide an index to these methods, and they insert the values that you provide at that index in the array.\n\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 10);\ndefer buffer.deinit();\n\ntry buffer.appendSlice(\"My Pedro\");\ntry buffer.insert(4, '3');\ntry buffer.insertSlice(2, \" name\");\nfor (buffer.items) |char| {\n    try stdout.print(\"{c}\", .{char});\n}\n\nMy name P3edro\n\n\n11.1.6 Conclusion\nIf you feel the lack of some other method, I recommend you to read the official documentation for the ArrayListAligned1 struct, which describes most of the methods available through the ArrayList object.\nYou will notice that there is a lot of other methods in this page that I did not described here, and I recommend you to explore these methods, and understand how they work.",
+    "crumbs": [
+      "<span class='chapter-number'>11</span>  <span class='chapter-title'>Data Structures</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/09-data-structures.html#sec-maps-hashtables",
+    "href": "Chapters/09-data-structures.html#sec-maps-hashtables",
+    "title": "11  Data Structures",
+    "section": "11.2 Maps or HashTables",
+    "text": "11.2 Maps or HashTables\nSome professionals know this type of data structure by different terms, like “map”, “hashmap” or “associative arrays”. But the most common term used is hashtable. Every programming language normally have some implementation of a hashtable in their standard libraries. Python have dict(), C++ have std::map and std::unordered_map, Rust have HashMap, Javascript have Object() and Map(), etc.\n\n11.2.1 What is a hashtable?\nA hashtable is a data structure based on key-value pairs. You provide a key and a value to this structure, then, the hashtable will store the input value at a location that can be identified by the input key that you provided. It does that by using an underlying array and a hash function. These two components are essential to how a hashtable works.\nUnder the hood, the hashtable contains an array. This array is where the values are stored, and the elements of this array are usually called of buckets. So the values that you provide to the hashtable are stored inside buckets, and you access each bucket by using an index.\nWhen you provide a key to a hashtable, it passes this key to the hash function. This hash function uses some sort of hashing algorithm to transform this key into an index. This index is actually an array index. It is a position in the underlying array of the hashtable. This is how a key identifies a specific position (or location) inside the hashtable structure.\nTherefore, you provide a key to the hashtable, and this key identifies a specific location inside the hashtable, then, the hashtable takes the input value that you provided, and stores this value in the location identified by this input key. You could say that the key maps to the value stored in the hashtable. You find the value, by using the key that identifies the location where the value is stored. The Figure 11.2 presents this process visually.\n\n\n\n\n\n\nFigure 11.2: A diagram of a Hashtable. Source: Wikipedia, the free encyclopedia.\n\n\n\nThe operation described in the previous paragraph is normally called an insertion operation. Because you are inserting new values into the hashtable. But there are other types of operations in hashtables such as delete and lookup. Delete is self describing, it is when you delete (or remove) a value from the hashtable. While lookup corresponds to when you look at a value that is stored in the hashtable, by using the key that identifies the location where this value is stored.\nSometimes, instead of storing the values directly, the underlying array of the hashtable might be an array of pointers, i.e. the buckets of the array stores pointers that points to the value, or also, may be an array of linked lists. These cases are common on hashtables that allows duplicate keys, or, in other words, on hashtables that effectively handle “collisions” that may arise from the hash function.\nDuplicate keys, or this “collision” thing that I’m talking about, is when you have two different keys that points to the same location (i.e. to the same index) in the underlying array of the hashtable. This might happen depending on the characteristics of the hash function that is being used in the hashtable. Some implementations of the hashtable will actively deal with collisions, meaning that, they will handle this case in some way. For example, the hashtable might transform all buckets into linked lists. Because with a linked list you can store multiple values into a single bucket.\nThere are different techniques to handle collisions in hashtables, which I will not describe in this book, because it is not our main scope here. But you can find a good description of some of the most common techniques at the Wikipedia page of hashtables (Wikipedia 2024).\n\n\n11.2.2 Hashtables in Zig\nThe Zig Standard Library provides different implementations of a hashtable. Each implementation have its own cons and pros, which we will discuss later on, and all of them are available through the std.hash_map module.\nThe HashMap struct is a general-purpose hashtable, which have very fast operations (lookup, insertion, delete), and also, quite high load factors for low memory usage. You can create and provide a context object to the HashMap constructor. This context object allows you to tailor the behaviour of the hashtable itself, because you can provide a hash function implementation to be used by the hashtable through this context object.\nBut let’s not worry about this context object now, because it is meant to be used by “experts in the field of hashtables”. Since we are most likely not experts in this field, we are going to take the easy way to create a hashtable. Which is by using the AutoHashMap() function.\nThis AutoHashMap() function is essentially a “create a hashtable object that uses the default settings” type of function. It automatically chooses a context object, and, therefore, a hash function implementation, for you. This function receives two data types as input, the first input is the data type of the keys that will be used in this hashtable, while the second input is the data type of the data that will be stored inside the hashtable, that is, the data type of the values to be stored.\nIn the example below, we are providing the data type u32 in the first argument, and u16 in the second argument of this function. This means that we are going to use u32 values as keys in this hashtable, while u16 values are the actual values that are going to be stored into this hashtable. At the end of this process, the hash_table object contains a HashMap object that uses the default settings and context.\n\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n    std.debug.print(\n        \"Value at key 50050: {d}\\n\",\n        .{hash_table.get(50050).?}\n    );\n\n    if (hash_table.remove(57709)) {\n        std.debug.print(\n            \"Value at key 57709 successfully removed!\\n\",\n            .{}\n        );\n    }\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n}\n\nN of values stored: 3\nValue at key 50050: 55\nValue at key 57709 successfully removed!\nN of values stored: 2\nYou can add/put new values into the hashtable by using the put() method. The first argument is the key to be used, and the second argument is the actual value that you want to store inside the hashtable. In the example below, we first add the value 89 using the key 54321, next, we add the value 55 using the key 50050, etc.\nNotice that we have used the method count() to see how many values are currently stored in the hashtable. After that, we also use the get() method to access (or look) at the value stored in the position identified by the key 500050. The output of this get() method is an optional value. This is why we use the ? method at the end to get the actual value.\nAlso notice that we can remove (or delete) values from the hashtable by using the remove() method. You provide the key that identifies the value that you want to delete, then, the method will delete this value and return a true value as output. This true value essentially tells us that the method successfully deleted the value.\nBut this delete operation might not be always successful. For example, you might provide the wrong key to this method. I mean, maybe you provide (either intentionally or unintentionally) a key that points to an empty bucket, i.e. a bucket that still doesn’t have a value in it. In this case, the remove() method would return a false value.\n\n\n11.2.3 Iterating through the hashtable\nIterating through the keys and values that are currently being stored in the hashtable is a very common necessity. You can do that in Zig by using an iterator object that can iterate through the elements of your hashtable object.\nThis iterator object works like any other iterator object that you would find in languages such as C++ and Rust. It is basically a pointer object that points to some value in the container, and has a next() method that you can use to navigate (or iterate) through the values in the container.\nYou can create such iterator object by using the iterator() method of the hashtable object. This method returns an iterator object, from which you can use the next() method in conjunction with a while loop to iterate through the elements of your hashtable. The next() method returns an optional Entry value, and therefore, you must unwrap this optional value to get the actual Entry value from which you can access the key and also the value identified by this key.\nWith this Entry value at hand, you can access the key of this current entry by using the key_ptr attribute and dereferencing the pointer that lives inside of it, while the value identified by this key is accessed through the value_ptr attribute instead, which is also a pointer to be dereferenced. The code example below demonstrates the use of these elements:\n\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n\n    var it = hash_table.iterator();\n    while (it.next()) |kv| {\n        // Access the current key\n        std.debug.print(\"Key: {d} | \", .{kv.key_ptr.*});\n        // Access the current value\n        std.debug.print(\"Value: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n\nKey: 54321 | Value: 89\nKey: 50050 | Value: 55\nKey: 57709 | Value: 41\nIf you want to iterate specifically through the values or the keys of your hashtable, you can create a key iterator or a value iterator object. These are also iterator objects, which have the same next() method that you can use to iterate through the hashtable.\nKey iterators are created from the keyIterator() method of your hashtable object, while value iterators are created from the valueIterator() method. All you have to do is to unwrap the value from the next() method and deference it directly to access the key or the value that you are iterating over. The code example below demonstrates the use of a key iterator, but you can replicate the same logic to a value iterator.\n\nvar kit = hash_table.keyIterator();\nwhile (kit.next()) |key| {\n    std.debug.print(\"Key: {d}\\n\", .{key.*});\n}\n\nKey: 54321\nKey: 50050\nKey: 57709\n\n\n11.2.4 The ArrayHashMap hashtable\nIf you need to iterate through the elements of your hashtable constantly, you might want to use the ArrayHashMap struct for your specific case, instead of going with the usual and general-purpose HashMap struct.\nThe ArrayHashMap struct creates a hashtable that is faster to iterate over. That is why this specific type of hashtable might be valuable to you. Some other properties of a ArrayHashMap hashtable are:\n\nthe order of insertion is preserved, i.e. the order of the values that you find while iterating through this hashtable is actually the order in which these values were inserted in the hashtable.\nthe key-value pairs are stored sequentially, one after another.\n\nYou can create an ArrayHashMap object by using, once again, a helper function that chooses automatically for you a hash function implementation. This is the AutoArrayHashMap() function, which works very similarly to the AutoHashMap() function that we presented at Section 11.2.2.\nYou provide two data types to this function. The data type of the keys that will be used in this hashtable, and the data type of the values that will be stored in this hashtable.\nAn ArrayHashMap object have essentially the exact same methods from the HashMap struct. So you can insert new values into the hashtable by using the put() method, and you can look (or get) a value from the hashtable by using the get() method. But the remove() method is not available in this specific type of hashtable.\nIn order to delete values from the hashtable, you would use the same methods that you find in an ArrayList object, i.e. a dynamic array. I presented these methods at Section 11.1.4, which are the swapRemove() and orderedRemove() methods. These methods have the same meaning here, or, the same effect that they have in an ArrayList object.\nThis means that, with swapRemove() you remove the value from the hashtable, but you do not preserve the order in which the values were inserted into the structure. While orderedRemove() is able to retain the order in which these values were inserted.\nBut instead of providing an index as input to swapRemove() or orderedRemove(), like I described at Section 11.1.4, these methods here in an ArrayHashMap take a key as input, like the remove() method from a HashMap object. If you want to provide an index as input, instead of a key, you should use the swapRemoveAt() and orderedRemoveAt() methods.\n\nvar hash_table = AutoArrayHashMap(u32, u16)\n    .init(allocator);\ndefer hash_table.deinit();\n\n\n\n11.2.5 The StringHashMap hashtable\nOne thing that you will notice in the other two types of hashtables that I have presented over the last sections, is that neither of them accepts a slice data type in their keys. What this means is that you cannot use a slice value to represent a key in these types of hashtable.\nThe most obvious consequence of this, is that you cannot use strings as keys in these hashtables. But it is extremely common to use strings as keys in hashtables.\nTake this very simple Javascript code snippet as an example. We are creating a simple hashtable object named people. Then, we add a new entry to this hashtable, which is identified by the string 'Pedro'. This string is the key in this case, while the object containing different personal information such as age, height and city, is the value to be stored in the hashtable.\nvar people = new Object();\npeople['Pedro'] = {\n    'age': 25,\n    'height': 1.67,\n    'city': 'Belo Horizonte'\n};\nThis pattern of using strings as keys is very common in all sorts of situations. That is why the Zig Standard Library offers a specific type of hashtable for this purpose, which is created through the StringHashMap() function. This function creates a hashtable that uses strings as keys. The only input of this function is the data type of the values that will be stored into this hashtable.\nIn the example below, I’m creating a hashtable to store the ages of different people. Each key in this hashtable is represented by the name of each person, while the value stored in the hashtable is the age of this person identified by the key.\nThat is why I provide the u8 data type (which is the data type used by the age values) as input to this StringHashMap() function. As the result, it creates a hashtable that uses string values as keys, and, that stores u8 values in it. Notice that an allocator object is provided at the init() method of the resulting object from the StringHashMap() function.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var ages = std.StringHashMap(u8).init(allocator);\n    defer ages.deinit();\n\n    try ages.put(\"Pedro\", 25);\n    try ages.put(\"Matheus\", 21);\n    try ages.put(\"Abgail\", 42);\n\n    var it = ages.iterator();\n    while (it.next()) |kv| {\n        std.debug.print(\"Key: {s} | \", .{kv.key_ptr.*});\n        std.debug.print(\"Age: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n\nKey: Pedro | Age: 25\nKey: Abgail | Age: 42\nKey: Matheus | Age: 21\n\n\n11.2.6 The StringArrayHashMap hashtable\nThe Zig Standard Library also provides a type of hashtable that mix the cons and pros of the StringHashMap and ArrayHashMap together. That is, a hashtable that uses strings as keys, but also have the advantages from ArrayHashMap. In other words, you can have a hashtable that is fast to iterate over, that preserves insertion order, and also, that uses strings as keys.\nYou can create such type of hashtable by using the StringArrayHashMap() function. This function accepts a data type as input, which is the data type of the values that are going to be stored inside this hashtable, in the same style as the function presented at Section 11.2.5.\nYou can insert new values into this hashtable by using the same put() method that we have discussed at Section 11.2.5. And you can also get values from the hashtable by using the same get() method. Like its ArrayHashMap brother, to delete values from this specific type of hashtable, we also use the orderedRemove() and swapRemove() methods, with the same effects that I have described at Section 11.2.4.\nIf we take the code example that was exposed at Section 11.2.5, we can achieve the exact same result with StringArrayHashMap():\n\nvar ages = std.StringArrayHashMap(u8).init(allocator);",
+    "crumbs": [
+      "<span class='chapter-number'>11</span>  <span class='chapter-title'>Data Structures</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/09-data-structures.html#linked-lists",
+    "href": "Chapters/09-data-structures.html#linked-lists",
+    "title": "11  Data Structures",
+    "section": "11.3 Linked lists",
+    "text": "11.3 Linked lists\nThe Zig Standard Library provides an implementation for both singly and doubly linked lists. A linked list is a linear data structure that looks like a chain, or, a rope. The main advantage of this data structure is that you normally have very fast insertion and deletion operations. But, as a disadvantage, iterating through this data structure is usually not so fast as iterating through an array.\nThe idea behind a linked list is to build a structure that consists of a sequence of nodes connected to each other by pointers. This means that linked lists are usually not contiguous in memory, because each node might be anywhere in memory. They do not need to be close to one another.\nAt Figure 11.3 we can see a diagram of a singly linked list. We begin at the first node (which is usually called “the head of the linked list”). Then, from this first node we uncover the remaining nodes in the structure, by following the locations pointed by the pointers found in each node.\nEach node has two things in it. It has the value that is stored in the current node , and also, a pointer. This pointer points to the next node in the list. If this pointer is null, then, it means that we have reached the end of our linked list.\n\n\n\n\n\n\nFigure 11.3: A diagram of a singly linked list.\n\n\n\nAt Figure 11.4 we can see a diagram of a doubly linked list. The only thing that really changes now is that every node in the linked list has both a pointer to the previous node, and, a pointer to the next node. So every node in a doubly linked list has two pointers in it. These are usually called the prev (for “previous”) and the next (for “next”) pointers of the node.\nIn the singly linked list example, we had only one single pointer in each node, and this singular pointer was always pointing to the next node in the sequence. This means that singly linked lists normally have only the next pointer in them.\n\n\n\n\n\n\nFigure 11.4: A diagram of a doubly linked list.\n\n\n\nLinked lists are available in Zig through the functions SinglyLinkedList() and DoublyLinkedList(), for “singly linked lists” and “doubly linked lists”, respectively. These functions are actually generic functions, which we are going to talk more about at Section 12.2.1.\nFor now, just understand that, in order to create a linked list object, we begin by providing a data type to these functions. This data type defines the type of data that each node in this linked list will store. In the example below, we are creating a singly linked list of u32 values. So each node in this linked list will store a u32 value.\nBoth the SinglyLinkedList() and DoublyLinkedList() functions returns a type, i.e. a struct definition, as output. Therefore, the object Lu32 is actually a struct definition. It defines the type “singly linked list of u32 values”.\nNow that we have the definition of the struct, we need to instantiate a Lu32 object. We normally instantiate struct objects in Zig by using an init() method. But in this case, we are instantiating the struct directly, by using an empty struct literal, in the expression Lu32{}.\nIn this example, we first create multiple node objects, and after we create them, we start to insert and connect these nodes to build the linked list, using the prepend() and insertAfter() methods. Notice that the prepend() method is a method from the linked list object, while the insertAfter() is a method present in the node objects.\nIn essence, the prepend() method inserts a node at the beginning of the linked list. In other words, the node that you provide to this method, becomes the new “head node” of the linked list. It becomes the first node in the list (see Figure 11.3).\nOn the other side, the insertAfter() method is used to basically connect two nodes together. When you provide a node to this method, it creates a pointer to this input node, and stores this pointer in the next attribute of the current node, from which the method was called from.\nBecause doubly linked lists have both a next and a prev attributes in each node (as described at Figure 11.4), a node object created from a DoublyLinkedList object have both an insertBefore() (for prev) and an insertAfter() (for next) methods available.\nThus, if we have used a doubly linked list, we can use the insertBefore() method to store the pointer to the input node in the prev attribute. This would put the input node as the “previous node”, or, the node before the current node. In contrast, the insertAfter() method puts the pointer created to the input node in the next attribute of the current node, and as result, the input node becomes the “next node” of the current node.\nSince we are using a singly linked list in this example, we have only the insertAfter() method available in the node objects that we create from our Lu32 type.\n\nconst std = @import(\"std\");\nconst SinglyLinkedList = std.SinglyLinkedList;\nconst Lu32 = SinglyLinkedList(u32);\n\npub fn main() !void {\n    var list = Lu32{};\n    var one = Lu32.Node{ .data = 1 };\n    var two = Lu32.Node{ .data = 2 };\n    var three = Lu32.Node{ .data = 3 };\n    var four = Lu32.Node{ .data = 4 };\n    var five = Lu32.Node{ .data = 5 };\n\n    list.prepend(&two); // {2}\n    two.insertAfter(&five); // {2, 5}\n    list.prepend(&one); // {1, 2, 5}\n    two.insertAfter(&three); // {1, 2, 3, 5}\n    three.insertAfter(&four); // {1, 2, 3, 4, 5}\n}\n\nThere are other methods available from the linked list object, depending if this object is a singly linked list or a doubly linked list, that might be very useful for you. You can find a summary of them in the bullet points below:\n\nremove() to remove a specific node from the linked list.\nif singly linked list, len() to count how many nodes there is in the linked list.\nif doubly linked list, checkout the len attribute to see how many nodes there is in the linked list.\nif singly linked list, popFirst() to remove the first node (i.e. the “head”) from the linked list.\nif doubly linked list, pop() and popFirst() to remove the last and first nodes from the linked list, respectively.\nif doubly linked list, append() to add a new node to end of the linked list (i.e. inverse of prepend()).",
+    "crumbs": [
+      "<span class='chapter-number'>11</span>  <span class='chapter-title'>Data Structures</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/09-data-structures.html#multi-array-structure",
+    "href": "Chapters/09-data-structures.html#multi-array-structure",
+    "title": "11  Data Structures",
+    "section": "11.4 Multi array structure",
+    "text": "11.4 Multi array structure\nZig introduces a new data structure called MultiArrayList(). It is a different version of the dynamic array that we have introduced at Section 11.1. The difference between this structure and the ArrayList() that we know from Section 11.1, is that MultiArrayList() creates a separate dynamic array for each field of the struct that you provide as input.\nConsider the following code example. We create a new custom struct called Person. This struct contains three different data members, or, three different fields. As consequence, when we provide this Person data type as input to MultiArrayList(), this creates a “struct of three different arrays” called PersonArray. In other words, this PersonArray is a struct that contains three internal dynamic arrays in it. One array for each field found in the Person struct definition.\n\nconst std = @import(\"std\");\nconst Person = struct {\n    name: []const u8,\n    age: u8,\n    height: f32,\n};\nconst PersonArray = std.MultiArrayList(Person);\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var people = PersonArray{};\n    defer people.deinit(allocator);\n\n    try people.append(allocator, .{\n        .name = \"Auguste\", .age = 15, .height = 1.54\n    });\n    try people.append(allocator, .{\n        .name = \"Elena\", .age = 26, .height = 1.65\n    });\n    try people.append(allocator, .{\n        .name = \"Michael\", .age = 64, .height = 1.87\n    });\n}\n\nIn other words, instead of creating an array of “persons”, the MultiArrayList() function creates a “struct of arrays”. Each data member of this struct is a different array that stores the values of a specific field from the Person values that were added (or, appended) to this “struct of arrays”. One important detail is that each of these separate internal arrays stored inside PersonArray are dynamic arrays. This means that these arrays can grow in capacity automatically as needed, to accomodate more values.\nThe Figure 11.5 exposed below presents a diagram that describes the PersonArray struct that we have created in the previous code example. Notice that the values of the data members present in each of the three Person values that we have appended into the PersonArray object , are scattered across three different internal arrays of the PersonArray object.\n\n\n\n\n\n\nFigure 11.5: A diagram of the PersonArray struct.\n\n\n\nYou can easily access each of these arrays separately, and iterate over the values of each array. For that, you will need to call the items() method from the PersonArray object, and provide as input to this method, the name of the field that you want to iterate over. If you want to iterate through the .age array for example, then, you need to call items(.age) from the PersonArray object, like in the example below:\n\nfor (people.items(.age)) |*age| {\n    try stdout.print(\"Age: {d}\\n\", .{age.*});\n}\n\nAge: 15\nAge: 26\nAge: 64\nIn the above example, we are iterating over the values of the .age array, or, the internal array of the PersonArray object that contains the values of the age data member from the Person values that were added to the multi array struct.\nIn this example we are calling the items() method directly from the PersonArray object. However, it is recommended on most situations to call this items() method from a “slice object”, which you can create from the slice() method. The reason for this is that calling items() multiple times have better performance if you use a slice object.\nTherefore, if you are planning to access only one of the internal arrays from your “multi array struct”, it is fine to call items() directly from the multi array object. But if you need to access many of the internal arrays from your “multi array struct”, then, you will likely need to call items() more than once, and, in such circumstance, is better to call items() through a slice object. The example below demonstrates the use of such object:\n\nvar slice = people.slice();\nfor (slice.items(.age)) |*age| {\n    age.* += 10;\n}\nfor (slice.items(.name), slice.items(.age)) |*n,*a| {\n    try stdout.print(\n        \"Name: {s}, Age: {d}\\n\", .{n.*, a.*}\n    );\n}\n\nName: Auguste, Age: 25\nName: Elena, Age: 36\nName: Michael, Age: 74",
+    "crumbs": [
+      "<span class='chapter-number'>11</span>  <span class='chapter-title'>Data Structures</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/09-data-structures.html#conclusion-1",
+    "href": "Chapters/09-data-structures.html#conclusion-1",
+    "title": "11  Data Structures",
+    "section": "11.5 Conclusion",
+    "text": "11.5 Conclusion\nThere are many other data structures that I haven’t presented here. But you can check them out at the official Zig Standard Library documentation page. Actually, when you get into the homepage of the documentation2, the first thing that appears to you in this page, is a list of types and data structures that are available in the Zig Standard Library. There are some very specific data structures in this list, like a BoundedArray struct3 , but there is also some more general structures, such as a PriorityQueue struct4.\n\n\n\n\nWikipedia. 2024. “Hash Tables.” Wikipedia. https://en.wikipedia.org/wiki/Hash_table.",
+    "crumbs": [
+      "<span class='chapter-number'>11</span>  <span class='chapter-title'>Data Structures</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/09-data-structures.html#footnotes",
+    "href": "Chapters/09-data-structures.html#footnotes",
+    "title": "11  Data Structures",
+    "section": "",
+    "text": "https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned↩︎\nhttps://ziglang.org/documentation/master/std/#↩︎\nhttps://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray↩︎\nhttps://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue.↩︎",
+    "crumbs": [
+      "<span class='chapter-number'>11</span>  <span class='chapter-title'>Data Structures</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/10-stack-project.html",
+    "href": "Chapters/10-stack-project.html",
+    "title": "12  Project 3 - Building a stack data structure",
+    "section": "",
+    "text": "12.1 Understanding comptime in Zig\nOne of the key features of Zig is comptime. This keyword introduces a whole new concept and paradigm, that is tightly connected with the compilation process. At Section 3.1.1 we have described the importance and the role that “compile-time versus runtime” plays into Zig. At that section, we learned that the rules applied to a value/object change a lot depending on whether this value is known at compile-time, or just at runtime.\nThe comptime keyword is strongly related to these two spaces in time (compile-time and runtime). Let’s quickly recap the differences. Compile-time is the period of time when your Zig source code is being compiled by the zig compiler, while the runtime is the period of time when your Zig program is being executed, i.e. when we execute the binary files that were generated by the zig compiler.\nThere are three ways in which you can apply the comptime keyword, which are:",
+    "crumbs": [
+      "<span class='chapter-number'>12</span>  <span class='chapter-title'>Project 3 - Building a stack data structure</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/10-stack-project.html#sec-comptime",
+    "href": "Chapters/10-stack-project.html#sec-comptime",
+    "title": "12  Project 3 - Building a stack data structure",
+    "section": "",
+    "text": "apply comptime on a function argument.\napply comptime on an object.\napply comptime on a block of expressions.\n\n\n12.1.1 Applying over a function argument\nWhen you apply the comptime keyword on a function argument, you are saying to the zig compiler that the value assigned to that particular function argument must be known at compile-time. We explained in details at Section 3.1.1 what exactly “value known at compile-time” means, so, in case you have doubts about this idea, come back to that section.\nNow let’s think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement to that particular function argument. If the programmer accidentally tries to give a value to this function argument that is not known at compile time, the zig compiler will notice this problem, and as a consequence, it will raise a compilation error saying that it cannot compile your program. Because you are providing a value that is “runtime known” to a function argument that must be “compile-time known”.\nTake a look at this very simple example below, where we define a twice() function, that simply doubles the input value named num. Notice that we use the comptime keyword before the name of the function argument. This keyword is marking the function argument num as a “comptime argument”.\nThat is a function argument whose value must be compile-time known. This is why the expression twice(5678) is valid, and no compilation errors are raised. Because the value 5678 is compile-time known, so this is the expected behaviour for this function.\n\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n\n1/1 file1105a40478a9d.test.test comptime...OKAll 1\n  1 tests passed.\n\n\nBut what if we provide a number that is not compile-time known to this function? For example, we might provide a different input value to this function depending on the target OS of our compilation process. The code example below demonstrates such case.\nBecause the value of the object n is determined at runtime, we cannot provide this object as input to the twice() function. The zig compiler will not allow it, because we marked the num argument as a “comptime argument”. That is why the zig compiler raises the compile-time error exposed below:\n\nconst builtin = @import(\"builtin\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    var n: u32 = undefined;\n    if (builtin.target.os.tag == .windows) {\n        n = 1234;\n    } else {\n        n = 5678;\n    }\n    _ = twice(n);\n}\n\nt.zig:12:16: error: runtime-known argument passed to comptime parameter \nComptime arguments are frequently used on functions that return some sort of generic structure. In fact, comptime is the essence (or the basis) to make generics in Zig. We are going to talk more about generics at Section 12.2.\nFor now, let’s take a look at this code example from Seguin (2024). You can see that this IntArray() function have one argument named length. This argument is marked as comptime, and receives a value of type usize as input. So the value given to this argument must be compile-time known. We can also see that this function returns an array of i64 values as output.\n\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n\nNow, the key component of this function is the length argument. This argument is used to determine the size of the array that is produced by the function. Let’s think about the consequences of that. If the size of the array is dependent on the value assigned to the length argument, this means that the data type of the output of the function depends on the value of this length argument.\nLet this statement sink for a bit in your mind. As I described at Section 1.2.2, Zig is a strongly-typed language, especially on function declarations. So every time we write a function in Zig, we have to annotate the data type of the value returned by the function. But how can we do that, if this data type depends on the value given to the argument of the function?\nThink about this for a second. If length is equal to 3 for example, then, the return type of the function is [3]i64. But if length is equal to 40, then, the return type becomes [40]i64. At this point the zig compiler would be confused, and raise a compilation error, saying something like this:\n\nHey! You have annotated that this function should return a [3]i64 value, but I got a [40]i64 value instead! This doesn’t look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when the type keyword comes in. This type keyword is basically saying to the zig compiler that this function will return some data type as output, but it doesn’t know yet what exactly data type that is. We will talk more about this at Section 12.2.\n\n\n12.1.2 Applying over an expression\nWhen you apply the comptime keyword over an expression, then, it is guaranteed that the zig compiler will execute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time (e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the zig compiler will raise a compilation error.\nTake this example from the official documentation of Zig (Zig Software Foundation 2024). We are executing the same fibonacci() function both at runtime, and, at compile-time. The function is by default executed at runtime, but because we use the comptime keyword at the second “try expression”, this expression is executed at compile-time.\nThis might be a bit confusing for some people. Yes! When I say that this expression is executed at compile-time, I mean that this expression is compiled and executed while the zig compiler is compiling your Zig source code.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n\n1/1 file1105a31c0f24f.test.fibonacci...OKAll 1 tes\n  sts passed.\n\n\nA lot of your Zig source code might be potentially executed at compile-time, because the zig compiler can figure it out the output of some expressions. Especially if these expressions depends only at compile-time known values. We have talked about this at Section 3.1.1.\nBut when you use the comptime keyword on an expression, there is no “it might be executed at compile-time” anymore. With the comptime keyword you are ordering the zig compiler to execute this expression at compile-time. You are imposing this rule, it is guaranteed that the compiler will always execute it at compile-time. Or, at least, the compiler will try to execute it. If the compiler cannot execute the expression for whatever reason, the compiler will raise a compilation error.\n\n\n12.1.3 Applying over a block\nBlocks were described at Section 1.7. When you apply the comptime keyword over a block of expressions, you get essentially the same effect when you apply this keyword to a single expression. That is, the entire block of expressions is executed at compile-time by the zig compiler.\nIn the example below, we mark the block labeled of blk as a comptime block, and, therefore, the expressions inside this block are executed at compile-time.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n\n1/1 file1105a37ca2b0d.test.fibonacci in a block...\n  .OKAll 1 tests passed.",
+    "crumbs": [
+      "<span class='chapter-number'>12</span>  <span class='chapter-title'>Project 3 - Building a stack data structure</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/10-stack-project.html#sec-generics",
+    "href": "Chapters/10-stack-project.html#sec-generics",
+    "title": "12  Project 3 - Building a stack data structure",
+    "section": "12.2 Introducing Generics",
+    "text": "12.2 Introducing Generics\nFirst of all, what is a generic? Generic is the idea to allow a type (f64, u8, u32, bool, and also, user-defined types, like the User struct that we defined at Section 2.3) to be a parameter to methods, classes and interfaces (Geeks for Geeks 2024). In other words, a “generic” is a class (or a method) that can work with multiple data types.\nFor example, in Java, generics are created through the operator &lt;&gt;. With this operator, a Java class is capable of receiving a data type as input, and therefore, the class can fit its features according to this input data type. As another example, generics in C++ are supported through the concept of templates. Class templates in C++ are generics.\nIn Zig, generics are implemented through comptime. The comptime keyword allows us to collect a data type at compile time, and pass this data type as input to a piece of code.\n\n12.2.1 A generic function\nTake the max() function exposed below as a first example. This function is essentially a “generic function”. In this function, we have a comptime function argument named T. Notice that this T argument have a data type of type. Weird right? This type keyword is the “father of all types”, or, “the type of types” in Zig.\nBecause we have used this type keyword in the T argument, we are telling the zig compiler that this T argument will receive some data type as input. Also notice the use of the comptime keyword in this argument. As I described at Section 12.1, every time you use this keyword in a function argument, this means that the value of this argument must be known at compile-time. This makes sense, right? Because there is no data type that is not known at compile-time.\nThink about this. Every data type that you will ever write is always known at compile-time. Especially because data types are an essential information for the compiler to actually compile your source code. Having this in mind, makes sense to mark this argument as a comptime argument.\n\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a &gt; b) a else b;\n}\n\nAlso notice that the value of the T argument is actually used to define the data type of the other arguments in the function, a and b, and also at the return type annotation of the function. That is, the data type of these arguments (a and b), and, the return data type of the function itself, are determined by the input value given to the T argument.\nAs a result, we have a generic function that works with different data types. For example, I can provide u8 values to this max() function, and it will work as expected. But if I provide f64 values instead, it will also work as expected. Without a generic function, I would have to write a different max() function for each one of the data types that I wanted to use. This generic function provides a very useful shortcut for us.\n\nconst std = @import(\"std\");\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a &gt; b) a else b;\n}\ntest \"test max\" {\n    const n1 = max(u8, 4, 10);\n    std.debug.print(\"Max n1: {d}\\n\", .{n1});\n    const n2 = max(f64, 89.24, 64.001);\n    std.debug.print(\"Max n2: {d}\\n\", .{n2});\n}\n\nMax n1: 10\nMax n2: 89.24\n\n\n12.2.2 A generic data structure\nEvery data structure that you find in the Zig Standard Library (e.g. ArrayList, HashMap, etc.) is essentially a generic data structure. These data structures are generic in the sense that they work with any data type you want. You just say which is the data type of the values that are going to be stored in this data structure, and they just work as expected.\nA generic data structure in Zig is how you replicate a generic class from Java, or, a class template from C++. But you may quest yourself: how do we build a generic data structure in Zig?\nThe basic idea is to write a generic function that creates the data structure definition for the specific type we want. In other words, this generic function behaves as a “factory of data structures”. The generic function outputs the struct definition that defines this data structure for a specific data type.\nTo create such function, we need to add a comptime argument to this function that receives a data type as input. We already learned how to do this at the previous section (Section 12.2.1). I think the best way to demonstrate how to create a generic data structure is to actually write one. This where we go into our next small project in this book. This one is a very small project, which is to write a generic stack data structure.",
+    "crumbs": [
+      "<span class='chapter-number'>12</span>  <span class='chapter-title'>Project 3 - Building a stack data structure</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/10-stack-project.html#sec-what-stack",
+    "href": "Chapters/10-stack-project.html#sec-what-stack",
+    "title": "12  Project 3 - Building a stack data structure",
+    "section": "12.3 What is a stack?",
+    "text": "12.3 What is a stack?\nA stack data structure is a structure that follows a LIFO (last in, first out) principle. Only two operations are normally supported in a stack data structure, which are push and pop. The push operation is used to add new values to the stack, while pop is used to remove values from the stack.\nWhen people try to explain how the stack data structure works, the most common analogy that they use is a stack of plates. Imagine that you have a stack of plates, for example, a stack of 10 plates in your table. Each plate represents a value that is currently stored in this stack.\nWe begin with a stack of 10 different values, or 10 different plates. Now, imagine that you want to add a new plate (or a new value) to this stack, which translates to the push operation. You would add this plate (or this value) by just putting the new plate on the top of the stack. Then, you would increase the stack to 11 plates.\nBut how would you remove plates (or remove values) from this stack (a.k.a. the pop operation) ? To do that, we would have to remove the plate on the top of the stack, and, as a result, we would have, once again, 10 plates in the stack.\nThis demonstrates the LIFO concept, because the first plate in the stack, which is the plate in the bottom of the stack, is always the last plate to get out of the stack. Think about it. In order to remove this specific plate from the stack, we have to remove all plates in the stack. So every operation in the stack, either insertion or deletion, is always made at the top of the stack. The Figure 12.1 below exposes this logic visually:\n\n\n\n\n\n\nFigure 12.1: A diagram of a stack structure. Source: Wikipedia, the free encyclopedia.",
+    "crumbs": [
+      "<span class='chapter-number'>12</span>  <span class='chapter-title'>Project 3 - Building a stack data structure</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/10-stack-project.html#writing-the-stack-data-structure",
+    "href": "Chapters/10-stack-project.html#writing-the-stack-data-structure",
+    "title": "12  Project 3 - Building a stack data structure",
+    "section": "12.4 Writing the stack data structure",
+    "text": "12.4 Writing the stack data structure\nWe are going to write the stack data structure in two steps. First, we are going to implement a stack that can only store u32 values. Then, after that, we are going to extend our implementation to make it generic, so that it works with any data type we want.\nFirst, we need to decide how the values will be stored inside the stack. There are multiple ways to implement the storage behind a stack structure. Some people prefer to use a doubly linked list, some others prefer to use a dynamic array, etc. In this example we are going to use an array behind the hood, to store the values in the stack, which is the items data member of our Stack struct definition.\nAlso notice in our Stack struct that we have three other data members: capacity, length and allocator. The capacity member contains the capacity of the underlying array that stores the values in the stack. The length contains the number of values that are currently being stored in the stack. And the allocator contains the allocator object that will be used by the stack structure whenever it needs to allocate more space for the values that are being stored.\nWe begin by defining an init() method of this struct, which is going to be responsible for instantiating a Stack object. Notice that, inside this init() method, we start by allocating an array with the capacity specified in the capacity argument.\n\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst Stack = struct {\n    items: []u32,\n    capacity: usize,\n    length: usize,\n    allocator: Allocator,\n\n    pub fn init(allocator: Allocator, capacity: usize) !Stack {\n        var buf = try allocator.alloc(u32, capacity);\n        return .{\n            .items = buf[0..],\n            .capacity = capacity,\n            .length = 0,\n            .allocator = allocator,\n        };\n    }\n};\n\n\n12.4.1 Implementing the push operation\nNow that we have written the basic logic to create a new Stack object, we can start writing the logic responsible for performing a push operation. Remember, a push operation in a stack data structure is the operation responsible for adding a new value to the stack.\nSo how can we add a new value to the Stack object that we have? The push() function exposed below is a possible answer to this question. Remember from what we discussed at Section 12.3 that values are always added to the top of the stack. This means that this push() function must always find the element in the underlying array that currently represents the top position of the stack, and then, add the input value there.\nFirst, we have an if statement in this function. This if statement is checking whether we need to expand the underlying array to store this new value that we are adding to the stack. In other words, maybe the underlying array does not have enough capacity to store this new value, and, in this case, we need to expand our array to get the capacity that we need.\nSo, if the logical test in this if statement returns true, it means that the array does not have enough capacity, and we need to expand it before we store this new value. So inside this if statement we are executing the necessary expressions to expand the underlying array. Notice that we use the allocator object to allocate a new array that is twice as bigger than the current array (self.capacity * 2).\nAfter that, we use a different built-in function named @memcpy(). This built-in function is equivalent to the memcpy() function from the C Standard Library1. It is used to copy the values from one block of memory to another block of memory. In other words, you can use this function to copy the values from one array into another array.\nWe are using this @memcpy() built-in function to copy the values that are currently stored in the underlying array of the stack object (self.items) into our new and bigger array that we have allocated (new_buf). After we execute this function, the new_buf contains a copy of the values that are present at self.items.\nNow that we have secured a copy of our current values in the new_buf object, we can now free the memory currently allocated at self.items. After that, we just need to assign our new and bigger array to self.items. This is the sequence of steps necessary to expand our array.\n\npub fn push(self: *Stack, val: u32) !void {\n    if ((self.length + 1) &gt; self.capacity) {\n        var new_buf = try self.allocator.alloc(\n            u32, self.capacity * 2\n        );\n        @memcpy(\n            new_buf[0..self.capacity], self.items\n        );\n        self.allocator.free(self.items);\n        self.items = new_buf;\n        self.capacity = self.capacity * 2;\n    }\n\n    self.items[self.length] = val;\n    self.length += 1;\n}\n\nAfter we make sure that we have enough room to store this new value that we are adding to the stack, all we have to do is to assign this value to the top element in this stack, and, increase the value of the length attribute by one. We find the top element in the stack by using the length attribute.\n\n\n12.4.2 Implementing the pop operation\nNow we can implement the pop operation of our stack object. This is a much easier operation to implement, and the pop() method below summarises all the logic that is needed.\nWe just have to find the element in the underlying array that currently represents the top of the stack, and set this element to “undefined”, to indicate that this element is “empty”. After that, we also need to decrease the length attribute of the stack by one.\nIf the current length of the stack is zero, it means that there is no values being stored in the stack currently. So, in this case, we could just return from the function and do nothing really. This is what the if statement inside this function is checking for.\n\npub fn pop(self: *Stack) void {\n    if (self.length == 0) return;\n\n    self.items[self.length - 1] = undefined;\n    self.length -= 1;\n}\n\n\n\n12.4.3 Implementing the deinit method\nWe have implemented the methods responsible for the two main operations associated with the stack data structure, which is pop() and push(), and we also have implemented the method responsible for instantiating a new Stack object, which is the init() method.\nBut now, we need to implement also the method responsible for destroying a Stack object. In Zig, this task is commonly associated with the method named deinit(). Most struct objects in Zig have such method, and it is commonly nicknamed “the destructor method”.\nIn theory, all we have to do to destroy the Stack object is to make sure that we free the allocated memory for the underlying array, using the allocator object that is stored inside the Stack object. This is what the deinit() method below is doing.\n\npub fn deinit(self: *Stack) void {\n    self.allocator.free(self.items);\n}",
+    "crumbs": [
+      "<span class='chapter-number'>12</span>  <span class='chapter-title'>Project 3 - Building a stack data structure</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/10-stack-project.html#making-it-generic",
+    "href": "Chapters/10-stack-project.html#making-it-generic",
+    "title": "12  Project 3 - Building a stack data structure",
+    "section": "12.5 Making it generic",
+    "text": "12.5 Making it generic\nNow that we have implemented the basic skeleton of our stack data structure, we can now focus on discussing how can we make it generic. How can we make this basic skeleton to work not only with u32 values, but also, with any other data type we want? For example, we might need to create a stack object to store User values in it. How can we make this possible? The answer lies on the use of generics and comptime.\nAs I described at Section 12.2.2, the basic idea is to write a generic function that returns a struct definition as output. In theory, we do not need much to transform our Stack struct into a generic data structure. All that we need to do is to transform the underlying array of the stack into a generic array.\nIn other words, this underlying array needs to be a “chameleon”. It needs to adapt, and transform it into an array of any data type that we want. For example, if we need to create a stack that will store u8 values, then, this underlying array needs to be a u8 array (i.e. []u8). But if we need to store User values instead, then, this array needs to be a User array (i.e. []User). Etc.\nWe do that by using a generic function. Because a generic function can receive a data type as input, and we can pass this data type to the struct definition of our Stack object. Therefore, we can use the generic function to create a Stack object that can store the data type we want. If we want to create a stack structure that stores User values, we pass the User data type to this generic function, and it will create for us the struct definition that describes a Stack object that can store User values in it.\nLook at the code example below. I have omitted some parts of the Stack struct definition for brevity reasons. However, if a specific part of our Stack struct is not exposed here in this example, then it is because this part did not change from the previous example. It remains the same.\n\nfn Stack(comptime T: type) type {\n    return struct {\n        items: []T,\n        capacity: usize,\n        length: usize,\n        allocator: Allocator,\n        const Self = @This();\n\n        pub fn init(allocator: Allocator,\n                    capacity: usize) !Stack(T) {\n            var buf = try allocator.alloc(T, capacity);\n            return .{\n                .items = buf[0..],\n                .capacity = capacity,\n                .length = 0,\n                .allocator = allocator,\n            };\n        }\n\n        pub fn push(self: *Self, val: T) !void {\n        // Truncate the rest of the struct\n    };\n}\n\nNotice that we have created a function in this example named Stack(). This function takes a type as input, and passes this type to the struct definition of our Stack object. The data member items is now, an array of type T, which is the data type that we have provided as input to the function. The function argument val in the push() function is now a value of type T too.\nWe can just provide a data type to this function, and it will create a definition of a Stack object that can store values of the data type that we have provided. In the example below, we are creating the definition of a Stack object that can store u8 values in it. This definition is stored at the Stacku8 object. This Stacku8 object becomes our new struct, it is the struct that we are going to use to create our Stack object.\n\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst Stacku8 = Stack(u8);\nvar stack = try Stacku8.init(allocator, 10);\ndefer stack.deinit();\ntry stack.push(1);\ntry stack.push(2);\ntry stack.push(3);\ntry stack.push(4);\ntry stack.push(5);\ntry stack.push(6);\n\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\"Stack capacity: {d}\\n\", .{stack.capacity});\n\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\n    \"Stack state: {any}\\n\",\n    .{stack.items[0..stack.length]}\n);\n\nStack len: 6\nStack capacity: 10\nStack len: 5\nStack len: 4\nStack state: { 1, 2, 3, 4, 0, 0, 0, 0, 0, 0 }\nEvery generic data structure in the Zig Standard Library (ArrayList, HashMap, SinlyLinkedList, etc.) is implemented through this logic. They use a generic function to create the struct definition that can work with the data type that you provided as input.",
+    "crumbs": [
+      "<span class='chapter-number'>12</span>  <span class='chapter-title'>Project 3 - Building a stack data structure</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/10-stack-project.html#conclusion",
+    "href": "Chapters/10-stack-project.html#conclusion",
+    "title": "12  Project 3 - Building a stack data structure",
+    "section": "12.6 Conclusion",
+    "text": "12.6 Conclusion\nThe full source code of the stack structure discussed in this chapter is freely available at the official repository of this book. Just checkout the stack.zig2 for the u32 version of our stack, and the generic_stack.zig3 for the generic version, available inside the ZigExamples folder of the repository.\n\n\n\n\nGeeks for Geeks. 2024. “Generics in c++.” Geeks for Geeks. https://www.geeksforgeeks.org/generics-in-c/.\n\n\nSeguin, Karl. 2024. “Generics.” https://www.openmymind.net/learning_zig/generics/.\n\n\nZig Software Foundation. 2024. “Language Reference.” Zig Software Foundation. https://ziglang.org/documentation/master/.",
+    "crumbs": [
+      "<span class='chapter-number'>12</span>  <span class='chapter-title'>Project 3 - Building a stack data structure</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/10-stack-project.html#footnotes",
+    "href": "Chapters/10-stack-project.html#footnotes",
+    "title": "12  Project 3 - Building a stack data structure",
+    "section": "",
+    "text": "https://www.tutorialspoint.com/c_standard_library/c_function_memcpy.htm↩︎\nhttps://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig↩︎\nhttps://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig↩︎",
+    "crumbs": [
+      "<span class='chapter-number'>12</span>  <span class='chapter-title'>Project 3 - Building a stack data structure</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/12-file-op.html",
+    "href": "Chapters/12-file-op.html",
+    "title": "13  Filesystem and Input/Output (IO)",
+    "section": "",
+    "text": "13.1 Input/Output basics\nIf you have some experience in a high-level language, you have certainly used these input and output functionalities before in this language. In other words, you certainly have been in a situation where you needed to sent some output to the user, or, to receive an input from the user.\nFor example, in Python we can receive some input from the user by using the input() built-in function. But we can also print (or “show”) some output to the user by using the print() built-in function. So yes, if you have programmed before in Python, you certainly have used these functions once before.\nBut do you know how these functions relate back to your operating system (OS)? How exactly they are interacting with the resources of your OS to receive or sent some input/output. In essence, these input/output functions from high-level languages are just abstractions over the standard output and standard input channels of your operating system.\nThis means that we receive an input, or send some output, through the operating system. It is the OS that makes the bridge between the user and your program. Your program does not have a direct access to the user. It is the OS that intermediates every message exchanged between your program and the user.\nThe standard output and standard input channels of your OS are commonly known as the stdout and stdin channels of your OS, respectively. In some contexts, they are also called the standard output device and the standard input device. As the name suggests, the standard output is the channel through which output flows, while the standard input is the channel in which input flows.\nFurthermore, OS’s also normally create a dedicated channel for exchanging error messages, which is known as the standard error channel, or, the stderr channel. This is the channel to which error and warning messages are usually sent to. These are the messages that are normally displayed in red-like or orange-like colors into your terminal.\nNormally, every OS (e.g. Windows, macOS, Linux, etc.) creates a dedicated and separate set of standard output, standard error and standard input channels for every single program (or process) that runs in your computer. This means that every program you write have a dedicated stdin, stderr and stdout that are separate from the stdin, stderr and stdout of other programs and processes that are currently running.\nThis is a behaviour from your OS. This does not come from the programming language that you are using. Because as I sad earlier, input and output in programming languages, especially in high-level ones, are just a simple abstraction over the stdin, stderr and stdout from your current OS. That is, your OS is the intermediary between every input/output operation made in your program, regardless of the programming language that you are using.",
+    "crumbs": [
+      "<span class='chapter-number'>13</span>  <span class='chapter-title'>Filesystem and Input/Output (IO)</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/12-file-op.html#sec-io-basics",
+    "href": "Chapters/12-file-op.html#sec-io-basics",
+    "title": "13  Filesystem and Input/Output (IO)",
+    "section": "",
+    "text": "13.1.1 The writer and reader pattern\nIn Zig, there is a pattern around input/output (IO). I (the author of this book) don’t know if there is an official name for this pattern. But here, in this book, I will call it the “writer and reader pattern”. In essence, every IO operation in Zig is made through either a GenericReader or a GenericWriter object1.\nThese two data types come from the std.io module of the Zig Standard Library. As their names suggests, a GenericReader is an object that offers tools to read data from “something” (or “somewhere”), while a GenericWriter offers tools to write data into this “something”. This “something” might be different things: like a file that exists in your filesystem; or, it might be a network socket in your system2; or, a continuous stream of data, like a standard input device from your system, that might be constantly receiving new data from users, or, as another example, a live chat in a game that is constantly receiving and displaying new messages from the players of the game.\nSo, if you want to read data from something, or somewhere, it means that you need to use a GenericReader object. But if you need instead, to write data into this “something”, then, you need to use a GenericWriter object instead. Both of these objects are normally created from a file descriptor object. More specifically, through the writer() and reader() methods of this file descriptor object. If you are not familiar with this type of object, go to the next section.\nEvery GenericWriter object have methods like print(), which allows you to write/send a formatted string (i.e. this formatted string is like a f string in Python, or, similar to the printf() C function) into the “something” (file, socket, stream, etc.) that you are using. It also have a writeAll() method, which allows you to write a string, or, an array of bytes into the “something”.\nLikewise, every GenericReader object have methods like readAll(), which allows you to read the data from the “something” (file, socket, stream, etc.) until it fills a particular array (i.e. a “buffer”) object. In other words, if you provide an array object of 300 u8 values to readAll(), then, this method attempts to read 300 bytes of data from the “something”, and it stores them into the array object that you have provided.\nWe also have other methods, like the readAtLeast() method, which allows you to specify how many bytes exactly you want to read from the “something”. In more details, if you give the number \\(n\\) as input to this method, then, it will attempt to read at least \\(n\\) bytes of data from the “something”. The “something” might have less than \\(n\\) bytes of data available for you to read, so, it is not guaranteed that you will get precisely \\(n\\) bytes as result.\nAnother useful method is readUntilDelimiterOrEof(). In this method, you specify a “delimiter character”. The idea is that this function will attempt to read as many bytes of data as possible from the “something”, until it encounters the end of the stream, or, it encounters the “delimiter character” that you have specified.\nIf you don’t know exactly how many bytes will come from the “something”, you may find the readAllAlloc() method useful. In essence, you provide an allocator object to this method, so that it can allocate more space if needed. As consequence, this method will try to read all bytes of the “something”, and, if it runs out of space at some point during the “reading process”, it uses the allocator object to allocate more space to continue reading the bytes. As result, this method returns a slice to the array object containing all the bytes read.\nThis is just a quick description of the methods present in these types of objects. But I recommend you to read the official docs, both for GenericWriter3 and GenericReader4. I also think it is a good idea to read the source code of the modules in the Zig Standard Library that defines the methods present in these objects, which are the Reader.zig5 and Writer.zig6.\n\n\n13.1.2 Introducing file descriptors\nA “file descriptor” object is a core component behind every IO operation that is made in any operating system (OS). Such object is an identifier for a particular input/output (IO) resource from your OS (Wikipedia 2024). It describes and identifies this particular resource. An IO resource might be:\n\nan existing file in your filesystem.\nan existing network socket.\nother types of stream channels.\na pipeline (or just “pipe”) in your terminal7.\n\nFrom the bullet points listed above, we know that although the term “file” is present, a “file descriptor” might describe something more than just a file. This concept of a “file descriptor” comes from the Portable Operating System Interface (POSIX) API, which is a set of standards that guide how operating systems across the world should be implemented, to maintain compatibility between them.\nA file descriptor not only identifies the input/output resource that you are using to receive or send some data, but it also describes where this resource is, and also, which IO mode this resource is currently using. For example, this IO resource might be using only the “read” IO mode, which means that this resource is open to “read operations”, while “write operations” are not authorized. These IO modes are essentially the modes that you provide to the argument mode from the fopen() C function, and also, from the open() Python built-in function.\nIn C, a “file descriptor” is a FILE pointer, but, in Zig, a file descriptor is a File object. This data type (File) is described in the std.fs module of the Zig Standard Library. We normally don’t create a File object directly in our Zig code. Instead, we normally get such object as result when we open an IO resource. In other words, we normally ask our OS to open a particular IO resource for us, and, if the OS do open successfully this IO resource, the OS normally handles back to us a file descriptor to this particular IO resource.\nSo you usually get a File object by using functions and methods from the Zig Standard Library that asks the OS to open some IO resource, like the openFile() method that opens a file in the filesystem. The net.Stream object that we have created at Section 7.4.1 is also a type of file descriptor object.\n\n\n13.1.3 The standard output\nYou already saw across this book, how can we access and use specifically the stdout in Zig to send some output to the user. For that, we use the getStdOut() function from the std.io module. This function returns a file descriptor that describes the stdout channel of your current OS. Through this file descriptor object, we can read from or write stuff to the stdout of our program.\nAlthough we can read stuff recorded into the stdout channel, we normally only write to (or “print”) stuff into this channel. The reason is very similar to what we discussed at Section 7.4.3, when we were discussing what “reading from” versus “writing to” the connection object from our small HTTP Server project would mean.\nWhen we write stuff into a channel, we are essentially sending data to the other end of this channel. In contrast, when we read stuff from this channel, we are essentially reading the data that was sent through this channel. Since the stdout is a channel to send output to the user, the key verb here is send. We want to send something to someone, and, as consequence, we want to write something into some channel.\nThat is why, when we use getStdOut(), most of the times, we also use the writer() method from the stdout file descriptor, to get access to a writer object that we can use to write stuff into this stdout channel. More specifically, this writer() method returns a GenericWriter object. One of the main methods of this GenericWriter object is the print() method that we have used before to write (or “print”) a formatted string into the stdout channel.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    try stdout.writeAll(\n        \"This message was written into stdout.\\n\"\n    );\n}\n\nThis message was written into stdout.\n\n\nThis GenericWriter object is like any other generic writer object that you would normally get from a file descriptor object. So, the same methods from a generic writer object that you would use while writing files to the filesystem for example, you could also use them here, from the file descriptor object of stdout, and vice-versa.\n\n\n13.1.4 The standard input\nYou can access the standard input (i.e. stdin) in Zig by using the getStdIn() function from the std.io module. Like its brother (getStdOut()), this function also returns a file descriptor object that describes the stdin channel of your OS.\nBecause we want to receive some input from the user, the key verb here becomes receive, and, as consequence, we usually want to read data from the stdin channel, instead of writing data into it. So, we normally use the reader() method of the file descriptor object returned by getStdIn(), to get access to a GenericReader object that we can use to read data from stdin.\nIn the example below, we are creating a small buffer capable of holding 20 characters. Then, we try to read the data from the stdin with the readUntilDelimiterOrEof() method, and save this data into the buffer object. Also notice that we are reading the data from the stdin until we hit a new line character ('\\n').\nIf you execute this program, you will notice that it stops the execution, ands start to wait indefinitely for some input from the user. In other words, you need to type your name into the terminal, and then, you press Enter to send your name to stdin. After you send your name to stdin, the program reads this input, and continues with the execution, by printing the given name to stdout. In the example below, I typed my name (Pedro) into the terminal, and then, pressed Enter.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst stdin = std.io.getStdIn().reader();\npub fn main() !void {\n    try stdout.writeAll(\"Type your name\\n\");\n    var buffer: [20]u8 = undefined;\n    @memset(buffer[0..], 0);\n    _ = try stdin.readUntilDelimiterOrEof(buffer[0..], '\\n');\n    try stdout.print(\"Your name is: {s}\\n\", .{buffer});\n}\n\nType your name\nYour name is: Pedro\n\n\n\n13.1.5 The standard error\nThe standard error (a.k.a. the stderr) works exactly the same as stdout and stdin. You just call the getStdErr() function from the std.io module, and you get the file descriptor to stderr. Ideally, you should write only error or warning messages to stderr, because this is the purpose of this channel.",
+    "crumbs": [
+      "<span class='chapter-number'>13</span>  <span class='chapter-title'>Filesystem and Input/Output (IO)</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/12-file-op.html#buffered-io",
+    "href": "Chapters/12-file-op.html#buffered-io",
+    "title": "13  Filesystem and Input/Output (IO)",
+    "section": "13.2 Buffered IO",
+    "text": "13.2 Buffered IO\nAs we described at Section 13.1, input/output (IO) operations are made directly by the operating system. It is the OS that manages the IO resource that you want to use for your IO operations. The consequence of this fact is that IO operations are heavily based on system calls (i.e. calling the operating system directly).\nJust to be clear, there is nothing particularly wrong with system calls. We use them all the time on any serious codebase written in any low-level programming language. However, system calls are always orders of magnitude slower than many different types of operations.\nSo is perfectly fine to use a system call once in a while. But when these system calls are used often, you can clearly notice most of the time the loss of performance in your application. So, the good rule of thumbs is to use a system call only when it is needed, and also, only in infrequent situations, to reduce the number of system calls performed to a minimum.\n\n13.2.1 Understanding how buffered IO works\nBuffered IO is a strategy to achieve better performance. It is used to reduce the number of system calls made by IO operations, and, as consequence, achieve a much higher performance. At Figure 13.1 and Figure 13.2 you can find two different diagrams which presents the difference between read operations performed in an unbuffered IO environment versus a buffered IO environment.\nTo give a better context to these diagrams, let’s suppose that we have a text file that contains the famous Lorem ipsum text8 in our filesystem. Let’s also suppose that these diagrams at Figure 13.1 and Figure 13.2 are showing the read operations that we are performing to read the Lorem ipsum text from this text file. The first thing you will notice when looking at these diagrams, is that in an unbuffered environment the read operations leads to many system calls. More precisely, in the diagram exposed at Figure 13.1 we get one system call per each byte that we read from the text file. On the other hand, at Figure 13.2 we have only one system call at the very beginning.\nWhen we use a buffered IO system, at the first read operation we perform, instead of sending one single byte directly to our program, the OS first sends a chunk of bytes from the file to a buffer object (i.e. an array). This chunk of bytes are cached/stored inside this buffer object.\nTherefore, from now on, for every new read operation that you perform, instead of making a new system call to ask for the next byte in the file to the OS, this read operation is redirected to the buffer object, that have this next byte already cached and ready to go.\n\n\n\n\n\n\nFigure 13.1: Unbuffered IO\n\n\n\n\n\n\n\n\n\nFigure 13.2: Buffered IO\n\n\n\nThis is the basic logic behind buffered IO systems. The size of the buffer object depends on multiple factors. But it is usually equal to the size of a full page of memory (4096 bytes). If we follow this logic, then, the OS reads the first 4096 bytes of the file and caches it into the buffer object. As long as your program does not consume all of these 4096 bytes from the buffer, you will not create new system calls.\nHowever, as soon as you consume all of these 4096 bytes from the buffer, it means that there is no bytes left in the buffer. In this situation, a new system call is made to ask the OS to send the next 4096 bytes in the file, and once again, these bytes are cached into the buffer object, and the cycle starts once again.\n\n\n13.2.2 Buffered IO across different languages\nIO operations made through a FILE pointer in C are buffered by default, so, at least in C, you don’t need to worry about this subject. But in contrast, IO operations in both Rust and Zig are not buffered depending on which functions from the standard libraries that you are using.\nFor example, in Rust, buffered IO is implemented through the BufReader and BufWriter structs, while in Zig, it is implemented through the BufferedReader and BufferedWriter structs. So any IO operation that you perform through the GenericWriter and GenericReader objects that I presented at Section 13.1.1 are not buffered, which means that these objects might create a lot of system calls depending on the situation.\n\n\n13.2.3 Using buffered IO in Zig\nUsing buffered IO in Zig is actually very easy. All you have to do is to just give the GenericWriter object to the bufferedWriter() function, or, to give the GenericReader object to the bufferedReader() function. These functions come from the std.io module, and they will construct the BufferedWriter or BufferedReader object for you.\nAfter you create this new BufferedWriter or BufferedReader object, you can call the writer() or reader() method of this new object, to get access to a new (and buffered) generic reader or generic writer.\nLet’s describe the process once again. Every time that you have a file descriptor object, you first get the generic writer or generic reader object from it, by calling the writer() or reader() methods of this file descriptor object. Then, you provide this generic writer or generic reader to the bufferedWriter() or bufferedReader() function, which creates a new BufferedWriter or BufferedReader object. Then, you call the writer() or reader() methods of this buffered writer or buffered reader object, which gives you access to a generic writer or a generic reader object that is buffered.\nTake this program as an example. This program is demonstrating the process exposed at Figure 13.2. We are simply opening a text file that contains the Lorem ipsum text, and then, we create a buffered IO reader object at bufreader, and we use this bufreader object to read the contents of this file into a buffer object, then, we end the program by printing this buffer to stdout.\n\nvar file = try std.fs.cwd().openFile(\n    \"ZigExamples/file-io/lorem.txt\", .{}\n);\ndefer file.close();\nvar buffered = std.io.bufferedReader(file.reader());\nvar bufreader = buffered.reader();\n\nvar buffer: [1000]u8 = undefined;\n@memset(buffer[0..], 0);\n\n_ = try bufreader.readUntilDelimiterOrEof(\n    buffer[0..], '\\n'\n);\ntry stdout.print(\"{s}\\n\", .{buffer});\n\nLorem ipsum dolor sit amet, consectetur\nadipiscing elit. Sed tincidunt erat sed nulla ornare, nec\naliquet ex laoreet. Ut nec rhoncus nunc. Integer magna metus,\nultrices eleifend porttitor ut, finibus ut tortor. Maecenas\nsapien justo, finibus tincidunt dictum ac, semper et lectus.\nVivamus molestie egestas orci ac viverra. Pellentesque nec\narcu facilisis, euismod eros eu, sodales nisl. Ut egestas\nsagittis arcu, in accumsan sapien rhoncus sit amet. Aenean\nneque lectus, imperdiet ac lobortis a, ullamcorper sed massa.\nNullam porttitor porttitor erat nec dapibus. Ut vel dui nec\nnulla vulputate molestie eget non nunc. Ut commodo luctus ipsum,\nin finibus libero feugiat eget. Etiam vel ante at urna tincidunt\nposuere sit amet ut felis. Maecenas finibus suscipit tristique.\nDonec viverra non sapien id suscipit.\nDespite being a buffered IO reader, this bufreader object is similar to any other GenericReader object, and have the exact same methods. So, although these two types of objects perform very different IO operations, they have the same interface, so you, the programmer, can interchangeably use them without the need to change anything in your source code. So a buffered IO reader or a buffered IO writer objects have the same methods than its generic and unbuffered brothers, i.e. the generic reader and generic writer objects that I presented at Section 13.1.1.\n\n\n\n\n\n\nTip\n\n\n\nIn general, you should always use a buffered IO reader or a buffered IO writer object to perform IO operations in Zig. Because they deliver better performance to your IO operations.",
+    "crumbs": [
+      "<span class='chapter-number'>13</span>  <span class='chapter-title'>Filesystem and Input/Output (IO)</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/12-file-op.html#filesystem-basics",
+    "href": "Chapters/12-file-op.html#filesystem-basics",
+    "title": "13  Filesystem and Input/Output (IO)",
+    "section": "13.3 Filesystem basics",
+    "text": "13.3 Filesystem basics\nNow that we have discussed the basics around Input/Output operations in Zig, we need to talk about the basics around filesystems, which is another core part of any operating system. Also, filesystems are related to input/output, because the files that we store and create in our computer are considered an IO resource, as we described at Section 13.1.2.\n\n13.3.1 The concept of current working directory (CWD)\nThe working directory is the folder on your computer where you are currently rooted at. In other words, it is the folder that your program is currently looking at. Therefore, whenever you are executing a program, this program is always working with a specific folder on your computer. It is always in this folder that the program will initially look for the files you require, and it is also in this folder that the program will initially save all the files you ask it to save.\nThe working directory is determined by the folder from which you invoke your program in the terminal. In other words, if you are in the terminal of your OS, and you execute a binary file (i.e. a program) from this terminal, the folder to which your terminal is pointing at is the current working directory of your program that is being executed.\nAt Figure 13.3 we have an example of me executing a program from the terminal. We are executing the program outputted by the zig compiler by compiling the Zig module named hello.zig. The CWD in this case is the zig-book folder. In other words, while the hello.zig program is executing, it will be looking at the zig-book folder, and any file operation that we perform inside this program, will be using this zig-book folder as the “starting point”, or, as the “central focus”.\n\n\n\n\n\n\nFigure 13.3: Executing a program from the terminal\n\n\n\nJust because we are rooted inside a particular folder (in the case of Figure 13.3, the zig-book folder) of our computer, it doesn’t mean that we cannot access or write resources in other locations of our computer. The current working directory (CWD) mechanism just defines where your program will look first for the files you ask for. This does not prevent you from accessing files that are located elsewhere on your computer. However, to access any file that is in a folder other than your current working directory, you must provide a path to that file or folder.\n\n\n13.3.2 The concept of paths\nA path is essentially a location. It points to a location in your filesystem. We use paths to describe the location of files and folders in our computer. One important aspect about paths is that they are always written inside strings, i.e. they are always provided as text values.\nThere are two types of paths that you can provide to any program in any OS: a relative path, or an absolute path. Absolute paths are paths that start at the root of your filesystem, and go all the way to the file name or the specific folder that you are referring to. This type of path is called absolute, because it points to an unique and absolute location on your computer. That is, there is no other existing location on your computer that corresponds to this path. It is an unique identifier.\nIn Windows, an absolute path is a path that starts with a hard disk identifier (e.g. C:/Users/pedro). On the other hand, absolute paths in Linux and macOS, are paths that start with a forward slash character (e.g. /usr/local/bin). Notice that a path is composed by “segments”. Each segment is connected to each other by a slash character (\\ or /). On Windows, the backward slash (\\) is normally used to connect the path segments. While on Linux and macOS, the forward slash (/) is the character used to connect path segments.\nA relative path is a path that start at the CWD. In other words, a relative path is “relative to the CWD”. The path used to access the hello.zig file at Figure 13.3 is an example of a relative path. This path is reproduced below. This path begins at the CWD, which in the context of Figure 13.3, is the zig-book folder, then, it goes to the ZigExamples folder, then, into zig-basics, then, to the hello.zig file.\nZigExamples/zig-basics/hello_world.zig\n\n\n13.3.3 Path wildcards\nWhen providing paths, especially relative paths, you have the option of using a wildcard. There are two commonly used wildcards in paths, which are “one period” (.) and “two periods” (..). In other words, these two specific characters have special meanings when used in paths, and can be used on any operating system (Mac, Windows, Linux, etc.). That is, they are “cross platform”.\nThe “one period” represents an alias for the current directory. This means that the relative paths \"./Course/Data/covid.csv\" and \"Course/Data/covid.csv\" are equivalent. On the other hand, the “two periods” refers to the previous directory. For example, the path \"Course/..\" is equivalent to the path \".\", that is, the current working directory.\nTherefore, the path \"Course/..\" refers to the folder before the Course folder. As another example, the path \"src/writexml/../xml.cpp\" refers to the file xml.cpp that is inside the folder before the writexml folder, which in this example is the src folder. Therefore, this path is equivalent to \"src/xml.cpp\".",
+    "crumbs": [
+      "<span class='chapter-number'>13</span>  <span class='chapter-title'>Filesystem and Input/Output (IO)</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/12-file-op.html#the-cwd-handler",
+    "href": "Chapters/12-file-op.html#the-cwd-handler",
+    "title": "13  Filesystem and Input/Output (IO)",
+    "section": "13.4 The CWD handler",
+    "text": "13.4 The CWD handler\nIn Zig, filesystem operations are usually made through a directory handler object. A directory handler in Zig is an object of type Dir, which is an object that describes a particular folder in the filesystem of our computer. You normally create a Dir object, by calling the std.fs.cwd() function. This function returns a Dir object that points to (or, that describes) the current working directory (CWD).\nThrough this Dir object, you can create new files, or modify, or read existing ones that are inside your CWD. In other words, a Dir object is the main entrypoint in Zig to perform multiple types of filesystem operations. In the example below, we are creating this Dir object, and storing it inside the cwd object. Although we are not using this object at this code example, we are going to use it a lot over the next examples.\n\nconst cwd = std.fs.cwd();\n_ = cwd;",
+    "crumbs": [
+      "<span class='chapter-number'>13</span>  <span class='chapter-title'>Filesystem and Input/Output (IO)</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/12-file-op.html#file-operations",
+    "href": "Chapters/12-file-op.html#file-operations",
+    "title": "13  Filesystem and Input/Output (IO)",
+    "section": "13.5 File operations",
+    "text": "13.5 File operations\n\n13.5.1 Creating files\nWe create new files by using the createFile() method from the Dir object. Just provide the name of the file that you want to create, and this function will do the necessary steps to create such file. You can also provide a relative path to this function, and it will create the file by following this path, which is relative to the CWD.\nThis function might return an error, so, you should use try, catch, or any of the other methods presented at Chapter 10 to handle the possible error. But if everything goes well, this createFile() method returns a file descriptor object (i.e. a File object) as result, through which you can add content to the file with the IO operations that I presented before.\nTake this code example below. In this example, we are creating a new text file named foo.txt. If the function createFile() succeeds, the object named file will contain a file descriptor object, which we can use to write (or add) new content to the file, like we do in this example, by using a buffered writer object to write a new line of text to the file.\nNow, a quick note, when we create a file descriptor object in C, by using a C function like fopen(), we must always close the file at the end of our program, or, as soon as we complete all operations that we wanted to perform on the file. In Zig, this is no different. So everytime we create a new file, this file remains “open”, waiting for some operation to be performed. As soon as we are done with it, we always have to close this file, to free the resources associated with it. In Zig, we do this by calling the method close() from the file descriptor object.\n\nconst cwd = std.fs.cwd();\nconst file = try cwd.createFile(\"foo.txt\", .{});\n// Don't forget to close the file at the end.\ndefer file.close();\n// Do things with the file ...\nvar fw = file.writer();\n_ = try fw.writeAll(\n    \"Writing this line to the file\\n\"\n);\n\nSo, in this example we not only have created a file into the filesystem, but we also wrote some data into this file, using the file descriptor object returned by createFile(). If the file that you are trying to create already exists in your filesystem, this createFile() call will overwrite the contents of the file, or, in other words, it will in erase all the contents of the existing file.\nIf you don’t want this to happen, meaning, that you don’t want to overwrite the contents of the existing file, but you want to write data to this file anyway (i.e. you want to append data to the file), you should use the openFile() method from the Dir object.\nAnother important aspect about createFile() is that this method creates a file that is not open to read operations by default. It means that you cannot read this file. You are not allowed to. So for example, you might want to write some stuff into this file at the beginning of the execution of your program. Then, at a future point in your program you might need to read what you wrote in this file. If you try to read data from this file, you will likely get a NotOpenForReading error as result.\nBut how can you overcome this barrier? How can you create a file that is open to read operations? All you have to do, is to set the read flag to true in the second argument of createFile(). When you set this flag to true, then the file get’s create with “read permissions”, and, as consequence, a program like this one below becomes valid:\n\nconst cwd = std.fs.cwd();\nconst file = try cwd.createFile(\n    \"foo.txt\",\n    .{ .read = true }\n);\ndefer file.close();\n\nvar fw = file.writer();\n_ = try fw.writeAll(\"We are going to read this line\\n\");\n\nvar buffer: [300]u8 = undefined;\n@memset(buffer[0..], 0);\ntry file.seekTo(0);\nvar fr = file.reader();\n_ = try fr.readAll(buffer[0..]);\ntry stdout.print(\"{s}\\n\", .{buffer});\n\nWe are going to read this line\nIf you are not familiar with position indicators, you might not recognize the method seekTo(). If that is your case, do not worry, we are going to talk more about this method at Section 13.6. But essentially this method is moving the position indicator back to the beginning of the file, so that we can read the contents of the file from the beginning.\n\n\n13.5.2 Opening files and appending data to it\nOpening files is easy. Just use the openFile() method instead of createFile(). In the first argument of openFile() you provide the path to the file that you want to open. Then, on the second argument you provide the flags (or, the options) that dictates how the file is opened.\nYou can see the full list of options for openFile() by visiting the documentation for OpenFlags9. But the main flag that you will most certainly use is the mode flag. This flag specifies the IO mode that the file will be using when it get’s opened. There are three IO modes, or, three values that you can provide to this flag, which are:\n\nread_only, allows only read operations on the file. All write operations are blocked.\nwrite_only, allows only write operations on the file. All read operations are blocked.\nread_write, allows both write and read operations on the file.\n\nThese modes are similar to the modes that you provide to the mode argument of the open() Python built-in function10, or, the mode argument of the fopen() C function11. In the code example below, we are opening the foo.txt text file with a write_only mode, and appending a new line of text to the end of the file. We use seekFromEnd() this time to guarantee that we are going to append the text to the end of the file. Once again, methods such as seekFromEnd() are described in more depth at Section 13.6.\n\nconst cwd = std.fs.cwd();\nconst file = try cwd.openFile(\n    \"foo.txt\", .{ .mode = .write_only }\n);\ndefer file.close();\ntry file.seekFromEnd(0);\nvar fw = file.writer();\n_ = try fw.writeAll(\"Some random text to write\\n\");\n\n\n\n13.5.3 Deleting files\nSometimes, we just need to delete/remove the files that we have. To do that, we use the deleteFile() method. You just provide the path of the file that you want to delete, and this method will try to delete the file located at this path.\n\nconst cwd = std.fs.cwd();\ntry cwd.deleteFile(\"foo.txt\");\n\n\n\n13.5.4 Copying files\nTo copy existing files, we use the copyFile() method. The first argument in this method is the path to the file that you want to copy. The second argument is a Dir object, i.e. a directory handler, more specifically, a Dir object that points to the folder in your computer where you want to copy the file to. The third argument is the new path of the file, or, in other words, the new location of the file. The fourth argument is the options (or flags) to be used in the copy operation.\nThe Dir object that you provide as input to this method will be used to copy the file to the new location. You may create this Dir object before calling the copyFile() method. Maybe you are planning to copy the file to a completely different location in your computer, so it might be worth to create a directory handler to that location. But if you are copying the file to a subfolder of your CWD, then, you can just simply pass the CWD handler to this argument.\n\nconst cwd = std.fs.cwd();\ntry cwd.copyFile(\n    \"foo.txt\",\n    cwd,\n    \"ZigExamples/file-io/foo.txt\",\n    .{}\n);\n\n\n\n13.5.5 Read the docs!\nThere are some other useful methods for file operations available at Dir objects, such as the writeFile() method, but I recommend you to read the docs for the Dir type12 to explore the other available methods, since I already talked too much about them.",
+    "crumbs": [
+      "<span class='chapter-number'>13</span>  <span class='chapter-title'>Filesystem and Input/Output (IO)</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/12-file-op.html#sec-indicators",
+    "href": "Chapters/12-file-op.html#sec-indicators",
+    "title": "13  Filesystem and Input/Output (IO)",
+    "section": "13.6 Position indicators",
+    "text": "13.6 Position indicators\nA position indicator is like a type of cursor, or, an index. This “index” identifies the current location in the file (or, in the data stream) that the file descriptor object that you have is currently looking at. When you create a file descriptor, the position indicator starts at the beginning of the file, or, at the beginning of the stream. When you read from or write into the file (or socket, or data stream, etc.) described by this file descriptor object, you end up moving the position indicator.\nIn other words, any IO operation have a common side effect, which is to move the position indicator. For example, suppose that we have a file of 300 bytes total in size. If you read 100 bytes from the file, then, the position indicator moves 100 bytes forward. If you try to write 50 bytes into this same file, these 50 bytes will be written from the current position indicated by the position indicator. Since the indicator is at a 100 bytes forward from the beginning of the file, these 50 bytes would be written in the middle of the file.\nThis is why we have used the seekTo() method at the last code example presented at Section 13.5.1. We have used this method to move the position indicator back to the beginning of the file, which would make sure that we would write the text that we wanted to write from the beginning of the file, instead of writing it from the middle of the file. Because before the write operation, we had performed a read operation, which means that the position indicator was moved in this read operation.\nThe position indicators of a file descriptor object can be changed (or altered) by using the “seek” methods from this file descriptor, which are: seekTo(), seekFromEnd() and seekBy(). These methods have the same effect, or, the same responsibility that the fseek()13 C function.\nConsidering that offset refers to the index that you provide as input to these “seek” methods, the bullet points below summarises what is the effect of each of these methods. As a quick note, in the case of seekFromEnd() and seekBy(), the offset provided can be either a positive or a negative index.\n\nseekTo() will move the position indicator to the location that is offset bytes from the beginning of the file.\nseekFromEnd() will move the position indicator to the location that is offset bytes from the end of the file.\nseekBy() will move the position indicator to the location that is offset bytes from the current position in the file.",
+    "crumbs": [
+      "<span class='chapter-number'>13</span>  <span class='chapter-title'>Filesystem and Input/Output (IO)</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/12-file-op.html#directory-operations",
+    "href": "Chapters/12-file-op.html#directory-operations",
+    "title": "13  Filesystem and Input/Output (IO)",
+    "section": "13.7 Directory operations",
+    "text": "13.7 Directory operations\n\n13.7.1 Iterating through the files in a directory\nOne of the most classic tasks related to filesystem is to be able to iterate through the existing files in a directory. To iterate over the files in a directory, we need to create an iterator object.\nYou can produce such iterator object by using either the iterate() or walk() methods of a Dir object. Both methods return an iterator object as output, which you can advance by using the next() method. The difference between these methods, is that iterate() returns a non-recursive iterator, while walk() does. It means that the iterator returned by walk() will not only iterate through the files available in the current directory, but also, through the files from any subdirectory found inside the current directory.\nIn the example below, we are displaying the names of the files stored inside the directory ZigExamples/file-io. Notice that we had to open this directory through the openDir() function. Also notice that we provided the flag iterate in the second argument of openDir(). This flag is important, because without this flag, we would not be allowed to iterate through the files in this directory.\n\nconst cwd = std.fs.cwd();\nconst dir = try cwd.openDir(\n    \"ZigExamples/file-io/\",\n    .{ .iterate = true }\n);\nvar it = dir.iterate();\nwhile (try it.next()) |entry| {\n    try stdout.print(\n        \"File name: {s}\\n\",\n        .{entry.name}\n    );\n}\n\nFile name: create_file_and_write_toit.zig\nFile name: create_file.zig\nFile name: lorem.txt\nFile name: iterate.zig\nFile name: delete_file.zig\nFile name: append_to_file.zig\nFile name: user_input.zig\nFile name: foo.txt\nFile name: create_file_and_read.zig\nFile name: buff_io.zig\nFile name: copy_file.zig\n\n\n13.7.2 Creating new directories\nThere are two methods that are important when it comes to creating directories, which are makeDir() and makePath(). The difference between these two methods is that makeDir() can only create one single directory in the current directory in each call, while makePath() is capable of recursively create subdirectories in the same call.\nThis is why the name of this method is “make path”. It will create as many subdirectories as necessary to create the path that you provided as input. So, if you provide the path \"sub1/sub2/sub3\" as input to this method, it will create three different subdirectories, sub1, sub2 and sub3, within the same function call. In contrast, if you provided such path as input to makeDir(), you would likely get an error as result, since this method can only create a single subdirectory.\n\nconst cwd = std.fs.cwd();\ntry cwd.makeDir(\"src\");\ntry cwd.makePath(\"src/decoders/jpg/\");\n\n\n\n13.7.3 Deleting directories\nTo delete a directory, just provide the path to the directory that you want to delete as input to the deleteDir() method from a Dir object. In the example below, we are deleting the src directory that we have just created in the previous example.\n\nconst cwd = std.fs.cwd();\ntry cwd.deleteDir(\"src\");",
+    "crumbs": [
+      "<span class='chapter-number'>13</span>  <span class='chapter-title'>Filesystem and Input/Output (IO)</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/12-file-op.html#conclusion",
+    "href": "Chapters/12-file-op.html#conclusion",
+    "title": "13  Filesystem and Input/Output (IO)",
+    "section": "13.8 Conclusion",
+    "text": "13.8 Conclusion\nIn this chapter, I have described how to perform in Zig the most common filesystem and IO operations. But you might feel the lack of some other, less common, operation in this chapter, such as: how to rename files, or how to open a directory, or how to create symbolic links, or how to use access() to test if a particular path exists in your computer. But for all of these less common tasks, I recommend you to read the documentation of the Dir type14 , since you can find a good description of these cases there.\n\n\n\n\nWikipedia. 2024. “File Descriptor.” Wikipedia. https://en.wikipedia.org/wiki/File_descriptor.",
+    "crumbs": [
+      "<span class='chapter-number'>13</span>  <span class='chapter-title'>Filesystem and Input/Output (IO)</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/12-file-op.html#footnotes",
+    "href": "Chapters/12-file-op.html#footnotes",
+    "title": "13  Filesystem and Input/Output (IO)",
+    "section": "",
+    "text": "Previously, these objects were known as the Reader and Writer objects.↩︎\nThe socket objects that we have created at Section 7.4.1, are examples of network sockets.↩︎\nhttps://ziglang.org/documentation/master/std/#std.io.GenericWriter.↩︎\nhttps://ziglang.org/documentation/master/std/#std.io.GenericReader.↩︎\nhttps://github.com/ziglang/zig/blob/master/lib/std/io/Reader.zig.↩︎\nhttps://github.com/ziglang/zig/blob/master/lib/std/io/Writer.zig.↩︎\nA pipeline is a mechanism for inter-process communication, or, inter-process IO. You could also interpret a pipeline as a “set of processes that are chained together, through the standard input/output devices of the system”. At Linux for example, a pipeline is created inside a terminal, by connecting two or more terminal commands with the “pipe” character (|).↩︎\nhttps://www.lipsum.com/.↩︎\nhttps://ziglang.org/documentation/master/std/#std.fs.File.OpenFlags↩︎\nhttps://docs.python.org/3/tutorial/inputoutput.html#reading-and-writing-files↩︎\nhttps://www.tutorialspoint.com/c_standard_library/c_function_fopen.htm↩︎\nhttps://ziglang.org/documentation/master/std/#std.fs.Dir↩︎\nhttps://en.cppreference.com/w/c/io/fseek↩︎\nhttps://ziglang.org/documentation/master/std/#std.fs.Dir↩︎",
+    "crumbs": [
+      "<span class='chapter-number'>13</span>  <span class='chapter-title'>Filesystem and Input/Output (IO)</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/14-zig-c-interop.html",
+    "href": "Chapters/14-zig-c-interop.html",
+    "title": "14  Zig interoperability with C",
+    "section": "",
+    "text": "14.1 How to call C code from Zig\nInteroperability with C is not something new. Most high-level programming languages have FFI (foreign function interfaces), which can be used to call C code. For example, Python have Cython, R have .Call(), Javascript have ccall(), etc. But Zig integrates with C in a deeper level, which affects not only the way that C code get’s called, but also, how this C code is compiled and incorporated into your Zig project.\nIn summary, Zig have great interoperability with C. If you want to call any C code from Zig, you have to perform the following steps:",
+    "crumbs": [
+      "<span class='chapter-number'>14</span>  <span class='chapter-title'>Zig interoperability with C</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/14-zig-c-interop.html#how-to-call-c-code-from-zig",
+    "href": "Chapters/14-zig-c-interop.html#how-to-call-c-code-from-zig",
+    "title": "14  Zig interoperability with C",
+    "section": "",
+    "text": "import a C header file into your Zig code.\nlink your Zig code with the C library.\n\n\n14.1.1 Strategies to import C header files\nUsing C code in Zig always involves performing the two steps cited above. However, when we talk specifically about the first step listed above, there are currently two different ways to perform this first step, which are:\n\ntranslating the C header file into Zig code, through the zig translate-c command, and then, import and use the translated Zig code.\nimporting the C header file directly into your Zig module through the @cImport() built-in function.\n\nIf you are not familiar with translate-c, this is a subcommand inside the zig compiler that takes C files as input, and outputs the Zig representation of the C code present in these C files. In other words, this subcommand works like a transpiler. It takes C code, and translates it into the equivalent Zig code.\nI think it would be ok to interpret translate-c as a tool to generate Zig bindings to C code, similarly to the rust-bindgen1 tool, which generates Rust FFI bindings to C code. But that would not be a precise interpretation of translate-c. The idea behind this tool is to really translate the C code into Zig code.\nNow, on a surface level, @cImport() versus translate-c might seem like two completely different strategies. But in fact, they are effectively the exact same strategy. Because, under the hood, the @cImport() built-in function is just a shortcut to translate-c. Both tools use the same “C to Zig” translation functionality. So when you use @cImport(), you are essentially asking the zig compiler to translate the C header file into Zig code, then, to import this Zig code into your current Zig module.\nAt the present moment, there is an accepted proposal at the Zig project, to move @cImport() to the Zig build system2. If this proposal is completed, then, the “use @cImport()” strategy would be transformed into “call a translate C function in your Zig build script”. So, the step of translating the C code into Zig code would be moved to the build script of your Zig project, and you would only need to import the translated Zig code into your Zig module to start calling C code from Zig.\nIf you think about this proposal for a minute, you will understand that this is actually a small change. I mean, the logic is the same, and the steps are still essentially the same. The only difference is that one of the steps will be moved to the build script of your Zig project.\n\n\n14.1.2 Linking Zig code with a C library\nRegardless of which of the two strategies from the previous section you choose, if you want to call C code from Zig, you must link your Zig code with the C library that contains the C code that you want to call.\nIn other words, everytime you use some C code in your Zig code, you introduce a dependency in your build process. This should come as no surprise to anyone that have any experience with C and C++. Because this is no different in C. Everytime you use a C library in your C code, you also have to build and link your C code with this C library that you are using.\nWhen we use a C library in our Zig code, the zig compiler needs to access the definition of the C functions that are being called in your Zig code. The C header file of this library provides the declarations of these C functions, but not their definitions. So, in order to access these definitions, the zig compiler needs to build your Zig code and link it with the C library during the build process.\nAs we discussed across the Chapter 9, there are different strategies to link something with a library. This might involve building the C library first, and then, linking it with the Zig code. Or, it could also involve just the linking step, if this C library is already built and installed in your system. Anyway, if you have doubts about this, comeback to Chapter 9.",
+    "crumbs": [
+      "<span class='chapter-number'>14</span>  <span class='chapter-title'>Zig interoperability with C</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/14-zig-c-interop.html#sec-import-c-header",
+    "href": "Chapters/14-zig-c-interop.html#sec-import-c-header",
+    "title": "14  Zig interoperability with C",
+    "section": "14.2 Importing C header files",
+    "text": "14.2 Importing C header files\nAt Section 14.1.1, we have described that, currently, there are two different paths that you can take to import a C header file into your Zig modules, translate-c or @cImport(). This section describes each strategy separately in more details.\n\n14.2.1 Strategy 1: using translate-c\nWhen we choose this strategy, we first need to use the translate-c tool to translate the C header files that we want to use into Zig code. For example, suppose we wanted to use the fopen() C function from the stdio.h C header file. We can translate the stdio.h C header file through the bash command below:\nzig translate-c /usr/include/stdio.h \\\n    -lc -I/usr/include \\\n    -D_NO_CRT_STDIO_INLINE=1 &gt; c.zig \\\nNotice that, in this bash command, we are passing the necessary compiler flags (-D to define macros, -l to link libraries, -I to add an “include path”) to compile and use the stdio.h header file. Also notice that we are saving the results of the translation process inside a Zig module called c.zig.\nTherefore, after running this command, all we have to do is to import this c.zig module, and start calling the C functions that you want to call from it. The example below demonstrates that. Is important to remember what we’ve discussed at Section 14.1.2. In order to compile this example you have to link this code with libc, by passing the flag -lc to the zig compiler.\n\nconst c = @import(\"c.zig\");\npub fn main() !void {\n    const x: f32 = 1772.94122;\n    _ = c.printf(\"%.3f\\n\", x);\n}\n\n1772.941\n\n\n14.2.2 Strategy 2: using @cImport()\nTo import a C header file into our Zig code, we can use the built-in functions @cInclude() and @cImport(). Inside the @cImport() function, we open a block (with a pair of curly braces). Inside this block we can (if we need to) include multiple @cDefine() calls to define C macros when including this specific C header file. But for the most part, you will probably need to use just a single call inside this block, which is a call to @cInclude().\nThis @cInclude() function is equivalent to the #include statement in C. You provide the name of the C header that you want to include as input to this @cInclude() function, then, in conjunction with @cImport(), it will perform the necessary steps to include this C header file into your Zig code.\nYou should bind the result of @cImport() to a constant object, pretty much like you would do with @import(). You just assign the result to a constant object in your Zig code, and, as consequence, all C functions, C structs, C macros, etc. that are defined inside the C header files will be available through this constant object.\nLook at the code example below, where we are importing the Standard I/O C Library (stdio.h), and calling the printf()3 C function. Notice that we have also used in this example the C function powf()4, which comes from the C Math Library (math.h). In order to compile this example, you have to link this Zig code with both the C Standard Library and the C Math Library, by passing the flags -lc and -lm to the zig compiler.\n\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n    @cInclude(\"math.h\");\n});\n\npub fn main() !void {\n    const x: f32 = 15.2;\n    const y = c.powf(x, @as(f32, 2.6));\n    _ = c.printf(\"%.3f\\n\", y);\n}\n\n1182.478",
+    "crumbs": [
+      "<span class='chapter-number'>14</span>  <span class='chapter-title'>Zig interoperability with C</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/14-zig-c-interop.html#sec-zig-obj-to-c",
+    "href": "Chapters/14-zig-c-interop.html#sec-zig-obj-to-c",
+    "title": "14  Zig interoperability with C",
+    "section": "14.3 About passing Zig values to C functions",
+    "text": "14.3 About passing Zig values to C functions\nZig objects have some intrinsic differences between their C equivalents. Probably the most noticeable one is the difference between C strings and Zig strings, which I described at Section 1.8. Zig strings are objects that contains both an array of arbitrary bytes and a length value. On the other hand, a C string is usually just a pointer to a null-terminated array of arbitrary bytes.\nBecause of these intrinsic differences, in some specific cases, you cannot pass Zig objects directly as inputs to C functions before you convert them into C compatible values. However, in some other cases, you are allowed to pass Zig objects and Zig literal values directly as inputs to C functions, and everything will work just fine, because the zig compiler will handle everything for you.\nSo we have two different scenarios being described here. Let’s call them “auto-conversion” and “need-conversion”. The “auto-conversion” scenario is when the zig compiler handles everything for you, and automatically convert your Zig objects/values into C compatible values. In contrast, the “need-conversion” scenario is when you, the programmer, have the responsibility of converting that Zig object into a C compatible value, before passing it to C code.\nThere is also a third scenario that is not being described here, which is when you create a C object, or, a C struct, or a C compatible value in your Zig code, and you pass this C object/value as input to a C function in your Zig code. This scenario will be described later at Section 14.4. In this section, we are focused on the scenarios where we are passing Zig objects/values to C code, instead of C objects/values being passed to C code.\n\n14.3.1 The “auto-conversion” scenario\nAn “auto-conversion” scenario is when the zig compiler automatically converts our Zig objects into C compatible values for us. This specific scenario happens mostly in two instances:\n\nwith string literal values;\nwith any of the primitive data types that were introduced at Section 1.5.\n\nWhen we think about the second instance described above, the zig compiler does automatically convert any of the primitive data types into their C equivalents, because the compiler knows how to properly convert a i16 into a signed short, or, a u8 into a unsigned char, etc. Now, when we think about string literal values, they can be automatically converted into C strings as well, especially because the zig compiler does not forces a specific Zig data type into a string literal at first glance, unless you store this string literal into a Zig object, and explicitly annotate the data type of this object.\nThus, with string literal values, the zig compiler have more freedom to infer which is the appropriate data type to be used in each situation. You could say that the string literal value “inherits its data type” depending on the context that it is used. Most of the times, this data type is going to be the type that we commonly associate with Zig strings ([]const u8). But it might be a different type depending on the situation. When the zig compiler detects that you are providing a string literal value as input to some C function, the compiler automatically interprets this string literal as a C string value.\nAs an example, look at the code exposed below. Here we are using the fopen() C function to simply open and close a file. If you do not know how this fopen() function works in C, it takes two C strings as input. But in this code example below, we are passing some string literals written in our Zig code directly as inputs to this fopen() C function.\nIn other words, we are not doing any conversion from a Zig string to a C string. We are just passing the Zig string literals directly as inputs to the C function. And it works just fine! Because the compiler interprets the string \"foo.txt\" as a C string given the current context.\n\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n});\n\npub fn main() !void {\n    const file = c.fopen(\"foo.txt\", \"rb\");\n    if (file == null) {\n        @panic(\"Could not open file!\");\n    }\n    if (c.fclose(file) != 0) {\n        return error.CouldNotCloseFileDescriptor;\n    }\n}\n\nLet’s make some experiments, by writing the same code in different manners, and we see how this affects the program. As a starting point, let’s store the \"foo.txt\" string inside a Zig object, like the path object below, and then, we pass this Zig object as input to the fopen() C function.\nIf we do this, the program still compiles and runs successfully. Notice that I have omitted most of the code in this example below. This is just for brevity reasons, because the remainder of the program is still the same. The only difference between this example and the previous one is just these two lines exposed below.\n\n    const path = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n\nNow, what happens if you give an explicit data type to the path object? Well, if I force the zig compiler to interpret this path object as a Zig string object, by annotating the path object with the data type []const u8, then, I actually get a compile error as demonstrated below. We get this compile error because now I’m forcing the zig compiler to interpret path as a Zig string object.\nAccording to the error message, the fopen() C function was expecting to receive an input value of type [*c]const u8 (C string) instead of a value of type []const u8 (Zig string). In more details, the type [*c]const u8 is actually the Zig type representation of a C string. The [*c] portion of this type identifies a C pointer. So, this Zig type essentially means: a C pointer to an array ([*c]) of constant bytes (const u8).\n\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n\nt.zig:2:7 error: expected type '[*c]const u8', found '[]const u8':\n    const file = c.fopen(path, \"rb\");\n                         ^~~~\nTherefore, when we talk exclusively about string literal values, as long as you don’t give an explicit data type to these string literal values, the zig compiler should be capable of automatically converting them into C strings as needed.\nBut what about using one of the primitive data types that were introduced at Section 1.5? Let’s take code exposed below as an example of that. Here, we are giving some float literal values as input to the C function powf(). Notice that this code example compiles and runs successfully.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst cmath = @cImport({\n    @cInclude(\"math.h\");\n});\n\npub fn main() !void {\n    const y = cmath.powf(15.68, 2.32);\n    try stdout.print(\"{d}\\n\", .{y});\n}\n\n593.2023\nOnce again, because the zig compiler does not associate a specific data type with the literal values 15.68 and 2.32 at first glance, the compiler can automatically convert these values into their C float (or double) equivalents, before it passes to the powf() C function. Now, even if I give an explicit Zig data type to these literal values, by storing them into a Zig object, and explicit annotating the type of these objects, the code still compiles and runs successfully.\n\n    const x: f32 = 15.68;\n    const y = cmath.powf(x, 2.32);\n    // The remainder of the program\n\n593.2023\n\n\n14.3.2 The “need-conversion” scenario\nA “need-conversion” scenario is when we need to manually convert our Zig objects into C compatible values before passing them as input to C functions. You will fall in this scenario, when passing Zig string objects to C functions.\nWe have already seen this specific circumstance in the last fopen() example, which is reproduced below. You can see in this example, that we have given an explicit Zig data type ([]const u8) to our path object, and, as a consequence of that, we have forced the zig compiler to see this path object, as a Zig string object. Therefore, we need now to manually convert this path object into a C string before we pass it to fopen().\n\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n\nt.zig:10:26: error: expected type '[*c]const u8', found '[]const u8'\n    const file = c.fopen(path, \"rb\");\n                         ^~~~\nThere are different ways to convert a Zig string object into a C string. One way to solve this problem is to provide the pointer to the underlying array of bytes, instead of providing the Zig object directly as input. You can access this pointer by using the ptr property of the Zig string object.\nThe code example below demonstrates this strategy. Notice that, by giving the pointer to the underlying array in path through the ptr property, we get no compile errors as result while using the fopen() C function.\n\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path.ptr, \"rb\");\n    // Remainder of the program\n\nThis strategy works because this pointer to the underlying array found in the ptr property, is semantically identical to a C pointer to an array of bytes, i.e. a C object of type *unsigned char. This is why this option also solves the problem of converting the Zig string into a C string.\nAnother option is to explicitly convert the Zig string object into a C pointer by using the built-in function @ptrCast(). With this function we can convert an object of type []const u8 into an object of type [*c]const u8. As I described at the previous section, the [*c] portion of the type means that it is a C pointer. This strategy is not-recommended. But it is useful to demonstrate the use of @ptrCast().\nYou may recall of @as() and @ptrCast() from Section 2.5. Just as a recap, the @as() built-in function is used to explicitly convert (or cast) a Zig value from a type “x” into a value of type “y”. But in our case here, we are converting a pointer object. Everytime a pointer is involved in some “type casting operation” in Zig, the @ptrCast() function is involved.\nIn the example below, we are using this function to cast our path object into a C pointer to an array of bytes. Then, we pass this C pointer as input to the fopen() function. Notice that this code example compiles successfully with no errors.\n\n    const path: []const u8 = \"foo.txt\";\n    const c_path: [*c]const u8 = @ptrCast(path);\n    const file = c.fopen(c_path, \"rb\");\n    // Remainder of the program",
+    "crumbs": [
+      "<span class='chapter-number'>14</span>  <span class='chapter-title'>Zig interoperability with C</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/14-zig-c-interop.html#sec-c-inputs",
+    "href": "Chapters/14-zig-c-interop.html#sec-c-inputs",
+    "title": "14  Zig interoperability with C",
+    "section": "14.4 Creating C objects in Zig",
+    "text": "14.4 Creating C objects in Zig\nCreating C objects, or, in other words, creating instances of C structs in your Zig code is actually something quite easy to do. You first need to import the C header file (like I described at Section 14.2) that defines the C struct that you are trying to instantiate in your Zig code. After that, you can just create a new object in your Zig code, and annotate it with the data type of the C struct.\nFor example, suppose we have a C header file called user.h, and that this header file is declaring a new struct named User. This C header file is exposed below:\n#include &lt;stdint.h&gt;\n\ntypedef struct {\n    uint64_t id;\n    char* name;\n} User;\nThis User C struct have two distinct fields, or two struct members, named id and name. The field id is an unsigned 64-bit integer value, while the field name is just a standard C string. Now, suppose that I want to create an instance of this User struct in my Zig code. I can do that by importing this user.h header file into my Zig code, and creating a new object with type User. These steps are reproduced in the code example below.\nNotice that I have used the keyword undefined in this example. This allows me to create the new_user object without the need to provide an initial value to the object. As consequence, the underlying memory associated with this new_user object is uninitialized, i.e. the memory is currently populated with “garbage” values. Thus, this expression have the exact same effect of the expression User new_user; in C, which means “declare a new object named new_user of type User”.\nIs our responsibility to properly initialize this memory associated with this new_user object, by assigning valid values to the members (or the fields) of the C struct. In the example below, I’m assigning the integer 1 to the member id. I am also saving the string \"pedropark99\" into the member name. Notice in this example that I manually add the null character (zero byte) to the end of the allocated array for this string. This null character marks the end of the array in C.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst c = @cImport({\n    @cInclude(\"user.h\");\n});\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n\n    var new_user: c.User = undefined;\n    new_user.id = 1;\n    var user_name = try allocator.alloc(u8, 12);\n    defer allocator.free(user_name);\n    @memcpy(user_name[0..(user_name.len - 1)], \"pedropark99\");\n    user_name[user_name.len - 1] = 0;\n    new_user.name = user_name.ptr;\n}\n\nSo, in this example above, we are manually initializing each field of the C struct. We could say that, in this instance, we are “manually instantiating the C struct object”. However, when we use C libraries in our Zig code, we rarely need to manually instantiate the C structs like that. Only because C libraries usually provide a “constructor function” in their public APIs. As consequence, we normally rely on these constructor functions to properly initialize the C structs, and the struct fields for us.\nFor example, consider the Harfbuzz C library. This a text shaping C library, and it works around a “buffer object”, or, more specifically, an instance of the C struct hb_buffer_t. Therefore, we need to create an instance of this C struct if we want to use this C library. Luckily, this library offers the function hb_buffer_create(), which we can use to create such object. So the Zig code necessary to create such object would probably look something like this:\n\nconst c = @cImport({\n    @cInclude(\"hb.h\");\n});\nvar buf: c.hb_buffer_t = c.hb_buffer_create();\n// Do stuff with the \"buffer object\"\n\nTherefore, we do not need to manually create an instance of the C struct hb_buffer_t here, and manually assign valid values to each field in this C struct. Because the constructor function hb_buffer_create() is doing this heavy job for us.\nSince this buf object, and also, the new_user object from previous examples, are instances of C structs, these objects are by themselves C compatible values. They are C objects defined in our Zig code. As consequence, you can freely pass these objects as input to any C function that expects to receive this type of C struct as input. You do not need to use any special syntax, or, to convert them in any special manner to use them in C code. This is how we create and use C objects in our Zig code.",
+    "crumbs": [
+      "<span class='chapter-number'>14</span>  <span class='chapter-title'>Zig interoperability with C</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/14-zig-c-interop.html#sec-pass-c-structs",
+    "href": "Chapters/14-zig-c-interop.html#sec-pass-c-structs",
+    "title": "14  Zig interoperability with C",
+    "section": "14.5 Passing C structs across Zig functions",
+    "text": "14.5 Passing C structs across Zig functions\nNow that we have learned how to create/declare C objects in our Zig code, we need to learn how to pass these C objects as inputs to Zig functions. As I described at Section 14.4, we can freely pass these C objects as inputs to C code that we call from our Zig code. But what about passing these C objects to Zig functions?\nIn essence, this specific case requires one small adjustment in the Zig function declaration. All you need to do, is to make sure that you pass your C object by reference to the function, instead of passing it by value. To do that, you have to annotate the data type of the function argument that is receiving this C object as “a pointer to the C struct”, instead of annotating it as “an instance of the C struct”.\nLet’s consider the C struct User from the user.h C header file that we have used at Section 14.4. Now, consider that we want to create a Zig function that sets the value of the id field in this C struct, like the set_user_id() function declared below. Notice that the user argument in this function is annotated as a pointer (*) to a c.User object.\nTherefore, all you have to do when passing C objects to Zig functions, is to add * to the data type of the function argument that is receiving the C object. This will make sure that the C object is passed by reference to the function.\nBecause we have transformed the function argument into a pointer, everytime that you have to access the value pointed by this input pointer inside the function body, for whatever reason (e.g. you want to read, update, or delete this value), you have to dereference the pointer with the .* syntax that we learned from Chapter 6. Notice that the set_user_id() function is using this syntax to alter the value in the id field of the User struct pointed by the input pointer.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst c = @cImport({\n    @cInclude(\"user.h\");\n});\nfn set_user_id(id: u64, user: *c.User) void {\n    user.*.id = id;\n}\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n\n    var new_user: c.User = undefined;\n    new_user.id = 1;\n    var user_name = try allocator.alloc(u8, 12);\n    defer allocator.free(user_name);\n    @memcpy(user_name[0..(user_name.len - 1)], \"pedropark99\");\n    user_name[user_name.len - 1] = 0;\n    new_user.name = user_name.ptr;\n\n    set_user_id(25, &new_user);\n    try stdout.print(\"New ID: {any}\\n\", .{new_user.id});\n}\n\nNew ID: 25",
+    "crumbs": [
+      "<span class='chapter-number'>14</span>  <span class='chapter-title'>Zig interoperability with C</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/14-zig-c-interop.html#footnotes",
+    "href": "Chapters/14-zig-c-interop.html#footnotes",
+    "title": "14  Zig interoperability with C",
+    "section": "",
+    "text": "https://github.com/rust-lang/rust-bindgen↩︎\nhttps://github.com/ziglang/zig/issues/20630↩︎\nhttps://cplusplus.com/reference/cstdio/printf/↩︎\nhttps://en.cppreference.com/w/c/numeric/math/pow↩︎",
+    "crumbs": [
+      "<span class='chapter-number'>14</span>  <span class='chapter-title'>Zig interoperability with C</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/13-image-filter.html",
+    "href": "Chapters/13-image-filter.html",
+    "title": "15  Project 4 - Developing an image filter",
+    "section": "",
+    "text": "15.1 How we see things?\nIn this section, I want to briefly describe to you how we (humans) actually see things with our own eyes. I mean, how our eyes work? If you do have a very basic understanding of how our eyes work, you will understand more easily how digital images are made. Because the techniques behind digital images were developed by taking a lot of inspiration from how our human eyes work.\nYou can interpret a human eye as a light sensor, or, a light receptor. The eye receives some amount of light as input, and it interprets the colors that are present in this “amount of light”. If no amount of light hits the eye, then, the eye cannot extract color from it, and as result, we end up seeing nothing, or, more precisely, we see complete blackness.\nTherefore, everything depends on light. What we actually see are the colors (blue, red, orange, green, purple, yellow, etc.) that are being reflected from the light that is hitting our eyes. Light is the source of all colors! This is what Isaac Newton discovered on his famous prism experiment2 in the 1660s.\nInside our eyes, we have a specific type of cell called the “cone cell”. Our eye have three different types, or, three different versions of these “cone cells”. Each type of cone cell is very sensitive to a specific spectrum of the light. More specifically, to the spectrums that define the colors red, green and blue. So, in summary, our eyes have specific types of cells that are highly sensitive to these three colors (red, green and blue).\nThese are the cells responsible for perceiving the color present in the light that hits our eyes. As a result, our eyes perceives color as a mixture of these three colors (red, green and blue). By having an amount of each one of these three colors, and mixing them together, we can get any other visible color that we want. So every color that we see is perceived as a specific mixture of blues, greens and reds, like 30% of red, plus 20% of green, plus 50% of blue.\nWhen these cone cells perceive (or, detect) the colors that are found in the light that is hitting our eyes, these cells produce electrical signals, which are sent to the brain. Our brain interprets these electrical signals, and use them to form the image that we are seeing inside our head.\nBased on what we have discussed here, the bullet points exposed below describes the sequence of events that composes this very simplified version of how our human eyes work:",
+    "crumbs": [
+      "<span class='chapter-number'>15</span>  <span class='chapter-title'>Project 4 - Developing an image filter</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/13-image-filter.html#sec-eyes",
+    "href": "Chapters/13-image-filter.html#sec-eyes",
+    "title": "15  Project 4 - Developing an image filter",
+    "section": "",
+    "text": "Light hits our eyes.\nThe cone cells perceive the colors that are present in this light.\nCone cells produce electrical signals that describes the colors that were perceived in the light.\nThe electrical signals are sent to the brain.\nBrain interprets these signals, and form the image based on the colors identified by these electrical signals.",
+    "crumbs": [
+      "<span class='chapter-number'>15</span>  <span class='chapter-title'>Project 4 - Developing an image filter</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/13-image-filter.html#sec-digital-img",
+    "href": "Chapters/13-image-filter.html#sec-digital-img",
+    "title": "15  Project 4 - Developing an image filter",
+    "section": "15.2 How digital images work?",
+    "text": "15.2 How digital images work?\nA digital image is a “digital representation” of an image that we see with our eyes. In other words, a digital image is a “digital representation” of the colors that we see and perceive through the light. In the digital world, we have two types of images, which are: vector images and raster images. Vector images are not described here. So just remember that the content discussed here is related solely to raster images, and not vector images.\nA raster image is a type of digital image that is represented as a 2D (two dimensional) matrix of pixels. In other words, every raster image is basically a rectangle of pixels, and each pixel have a particular color. So, a raster image is just a rectangle of pixels, and each of these pixels are displayed in the screen of your computer (or the screen of any other device, e.g. laptop, tablet, smartphone, etc.) as a color.\nFigure 15.3 demonstrates this idea. If you take any raster image, and you zoom into it very hard, you will see the actual pixels of the image. JPEG, TIFF and PNG are file formats that are commonly used to store raster images.\n\n\n\n\n\n\nFigure 15.3: Zooming over a raster image to see the pixels. Source: Google Images.\n\n\n\nThe more pixels the image has, the more information and detail we can include in the image. The more accurate, sharp and pretty the image will look. This is why photographic cameras usually produce big raster images, with several megapixels of resolution, to include as much detail as possible into the final image. As an example, a digital image with dimensions of 1920 pixels wide and 1080 pixels high, would be a image that contains \\(1920 \\times 1080 = 2073600\\) pixels in total. You could also say that the “total area” of the image is of 2073600 pixels, although the concept of “area” is not really used here in computer graphics.\nMost digital images we see in our modern world uses the RGB color model. RGB stands for (red, green and blue). So the color of each pixel in these raster images are usually represented as a mixture of red, green and blue, just like in our eyes. That is, the color of each pixel is identified by a set of three different integer values. Each integer value identifies the “amount” of each color (red, green and blue). For example, the set (199, 78, 70) identifies a color that is more close to red. We have 199 of red, 78 of green, and 70 of blue. In contrast, the set (129, 77, 250) describes a color that is more close to purple. Et cetera.\n\n15.2.1 Images are displayed from top to bottom\nThis is not a rule written in stone, but the big majority of digital images are displayed from top to bottom and left to right. Most computers screens also follow this pattern. So, the first pixels in the image are the ones that are at the top and left corner of the image. You can find a visual representation of this logic at Figure 15.4.\nAlso notice in Figure 15.4 that, because a raster image is essentially a 2D matrix of pixels, the image is organized into rows and columns of pixels. The columns are defined by the horizontal x axis, while the rows are defined by the vertical y axis.\nEach pixel (i.e. the gray rectangles) exposed at Figure 15.4 contains a number inside of it. These numbers are the indexes of the pixels. You can notice that the first pixels are in the top and left corner, and also, that the indexes of these pixels “grow to the sides”, or, in other words, they grow in the direction of the horizontal x axis. Most raster images are organized as rows of pixels. Thus, when these digital images are displayed, the screen display the first row of pixels, then, the second row, then, the third row, etc.\n\n\n\n\n\n\nFigure 15.4: How the pixels of raster images are displayed.\n\n\n\n\n\n15.2.2 Representing the matrix of pixels in code\nOk, we know already that raster images are represented as 2D matrices of pixels. But we do not have a notion of a 2D matrix in Zig. Actually, most low-level languages in general (Zig, C, Rust, etc.) do not have such notion. So how can we represent such matrix of pixels in Zig, or any other low-level language? The strategy that most programmers choose in this situation is to just use a normal 1D array to store the values of this 2D matrix. In other words, you just create an normal 1D array, and store all values from both dimensions into this 1D array.\nAs an example, suppose we have a very small image of dimensions 4x3. Since a raster image is represented as a 2D matrix of pixels, and each pixel is represented by 3 “unsigned 8-bit” integer values, we have 12 pixels in total in this image, which are represented by \\(3 \\times 12 = 36\\) integer values. Therefore, we need to create an array of 36 u8 values to store this small image.\nThe reason why unsigned 8-bit integer (u8) values are used to represent the amounts of each color, instead of any other integer type, is because they take the minimum amount of space as possible, or, the minimum amount of bits as possible. Which helps to reduces the binary size of the image, i.e. the 2D matrix. Also, they convey a good amount of precision and detail about the colors, even though they can represent a relatively small range (from 0 to 255) of “color amounts”.\nComing back to our initial example of a 4x3 image, the matrix object exposed below could be an example of an 1D array that stores the data that represents this 4x3 image.\n\nconst matrix = [_]u8{\n    201, 10, 25, 185, 65, 70,\n    65, 120, 110, 65, 120, 117,\n    98, 95, 12, 213, 26, 88,\n    143, 112, 65, 97, 99, 205,\n    234, 105, 56, 43, 44, 216,\n    45, 59, 243, 211, 209, 54,\n};\n\nThe first three integer values in this array are the color amounts of the first pixel in the image. The next three integers are the colors amounts for the second pixel. And the sequence goes on in this pattern. Having that in mind, the size of the array that stores a raster image is usually a multiple of 3. In this case, the array have a size of 36.\nI mean, the size of the array is usually a multiple of 3, because in specific circumstances, it can also be a multiple of 4. This happens when a transparency amount is also included into the raster image. In other words, there are some types of raster images that uses a different color model, which is the RGBA (red, green, blue and alpha) color model. The “alpha” corresponds to an amount of transparency in the pixel. So every pixel in a RGBA image is represented by a red, green, blue and alpha values.\nMost raster images uses the standard RGB model, so, for the most part, you will see arrays sizes that are multiples of 3. But some images, especially the ones that are stored in PNG files, might be using the RGBA model, and, therefore, are represented by an array whose size is a multiple of 4.\nIn our case here, the example image of our project (Figure 15.1) is a raster image stored in a PNG file, and this specific image is using the RGBA color model. Therefore, each pixel in the image is represented by 4 different integer values, and, as consequence, to store this image in our Zig code, we need to create an array whose size is a multiple of 4.",
+    "crumbs": [
+      "<span class='chapter-number'>15</span>  <span class='chapter-title'>Project 4 - Developing an image filter</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/13-image-filter.html#the-png-library-that-we-are-going-to-use",
+    "href": "Chapters/13-image-filter.html#the-png-library-that-we-are-going-to-use",
+    "title": "15  Project 4 - Developing an image filter",
+    "section": "15.3 The PNG library that we are going to use",
+    "text": "15.3 The PNG library that we are going to use\nLet’s begin our project by focusing on writing the necessary Zig code to read the data from the PNG file. In other words, we want to read the PNG file exposed at Figure 15.1, and parse its data to extract the 2D matrix of pixels that represents the image.\nAs we have discussed at Section 15.2.2, the image that we are using as example here is a PNG file that uses the RGBA color model, and, therefore, each pixel of the image is represented by 4 integer values. You can download this image by visiting the ZigExamples/image_filter folder at the official repository of this book3. You can also find in this folder the complete source code of this small project that we are developing here.\nThere are some C libraries available that we can use to read and parse PNG files. The most famous and used of all is libpng, which is the “official library” for reading and writing PNG files. Although this library is available on most operating system, it is well known for being complex and hard to use.\nThat is why, I’m going to use a more modern alternative here in this project, which is the libspng library. I choose to use this C library here, because it is much, much simpler to use than libpng, and it also offers very good performance for all operations. You can checkout the official website of the library4 to know more about it. You will also find there some documentation that might help you to understand and follow the code examples exposed here.\nFirst of all, remember to build and install this libspng into your system. Because if you don’t do this step, the zig compiler will not be able to find the files and resources of this library in your computer, and link them with the Zig source code that we are writing together here. There is good information about how to build and install the library at the build section of the library documentation5.",
+    "crumbs": [
+      "<span class='chapter-number'>15</span>  <span class='chapter-title'>Project 4 - Developing an image filter</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/13-image-filter.html#reading-the-png-file",
+    "href": "Chapters/13-image-filter.html#reading-the-png-file",
+    "title": "15  Project 4 - Developing an image filter",
+    "section": "15.4 Reading the PNG file",
+    "text": "15.4 Reading the PNG file\nIn order to extract the pixel data from the PNG file, we need to read and decode the file. A PNG file is just a binary file written in the “PNG format”. Luckily, the libspng library offers a function called spng_decode_image() that does all this heavy work for us.\nNow, since libspng is a C library, most of the file and I/O operations in this library are made by using a FILE C pointer. Because of that, is probably a better idea to use the fopen() C function to open our PNG file, instead of using the openFile() method that I introduced at Chapter 13. That is why I’m importing the stdio.h C header in this project, and using the fopen() C function to open the file.\nIf you look at the snippet below, you can see that we are:\n\nopening the PNG file with fopen().\ncreating the libspng context with spng_ctx_new().\nusing spng_set_png_file() to specify the FILE object that reads the PNG file that we are going to use.\n\nEvery operation in libspng is made through a “context object”. In our snippet below, this object is ctx. Also, to perform an operation over a PNG file, we need to specify which exact PNG file we are referring to. This is the job of spng_set_png_file(). We are using this function to specify the file descriptor object that reads the PNG file that we want to use.\n\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n    @cInclude(\"spng.h\");\n});\n\nconst path = \"pedro_pascal.png\";\nconst file_descriptor = c.fopen(path, \"rb\");\nif (file_descriptor == null) {\n    @panic(\"Could not open file!\");\n}\nconst ctx = c.spng_ctx_new(0) orelse unreachable;\n_ = c.spng_set_png_file(\n    ctx, @ptrCast(file_descriptor)\n);\n\nBefore we continue, is important to emphasize the following: since we have opened the file with fopen(), we have to remember to close the file at the end of the program, with fclose(). In other words, after we have done everything that we wanted to do with the PNG file pedro_pascal.png, we need to close this file, by applying fclose() over the file descriptor object. We could use also the defer keyword to help us in this task, if we want to. This code snippet below demonstrates this step:\n\nif (c.fclose(file_descriptor) != 0) {\n    return error.CouldNotCloseFileDescriptor;\n}\n\n\n15.4.1 Reading the image header section\nNow, the context object ctx is aware of our PNG file pedro_pascal.png, because it has access to a file descriptor object to this file. The first thing that we are going to do is to read the “image header section” of the PNG file. This “image header section” is the section of the file that contains some basic information about the PNG file, like, the bit depth of the pixel data of the image, the color model used in the file, the dimensions of the image (height and width in number of pixels), etc.\nTo make things easier, I will encapsulate this “read image header” operation into a nice and small function called get_image_header(). All that this function needs to do is to call the spng_get_ihdr() function. This function from libspng is responsible for reading the image header data, and storing it into a C struct named spng_ihdr. Thus, an object of type spng_ihdr is a C struct that contains the data from the image header section of the PNG file.\nSince this Zig function is receiving a C object (the libspng context object) as input, I marked the function argument ctx as “a pointer to the context object” (*c.spng_ctx), following the recommendations that we have discussed at Section 14.5.\n\nfn get_image_header(ctx: *c.spng_ctx) !c.spng_ihdr {\n    var image_header: c.spng_ihdr = undefined;\n    if (c.spng_get_ihdr(ctx, &image_header) != 0) {\n        return error.CouldNotGetImageHeader;\n    }\n\n    return image_header;\n}\n\nvar image_header = try get_image_header(ctx);\n\nAlso notice in this function, that I’m checking if the spng_get_ihdr() function call have returned or not an integer value that is different than zero. Most functions from the libspng library return a code status as result, and the code status “zero” means “success”. So any code status that is different than zero means that an error occurred while running spng_get_ihdr(). This is why I’m returning an error value from the function in case the code status returned by the function is different than zero.\n\n\n15.4.2 Allocating space for the pixel data\nBefore we read the pixel data from the PNG file, we need to allocate enough space to hold this data. But in order to allocate such space, we first need to know how much space we need to allocate. The dimensions of the image are obviously needed to calculate the size of this space. But there are other elements that also affect this number, such as the color model used in the image, the bit depth, and others.\nAnyway, all of this means that calculating the size of the space that we need, is not a simple task. That is why the libspng library offers an utility function named spng_decoded_image_size() to calculate this size for us. Once again, I’m going to encapsulate the logic around this C function into a nice and small Zig function named calc_output_size(). You can see below that this function returns a nice integer value as result, informing the size of the space that we need to allocate.\n\nfn calc_output_size(ctx: *c.spng_ctx) !u64 {\n    var output_size: u64 = 0;\n    const status = c.spng_decoded_image_size(\n        ctx, c.SPNG_FMT_RGBA8, &output_size\n    );\n    if (status != 0) {\n        return error.CouldNotCalcOutputSize;\n    }\n    return output_size;\n}\n\nYou might quest yourself what the value SPNG_FMT_RGBA8 means. This value is actually an enum value defined in the spng.h C header file. This enum is used to identify a “PNG format”. More precisely, it identifies a PNG file that uses the RGBA color model and 8 bit depth. So, by providing this enum value as input to the spng_decoded_image_size() function, we are saying to this function to calculate the size of the decoded pixel data, by considering a PNG file that follows this “RGBA color model with 8 bit depth” format.\nHaving this function, we can use it in conjunction with an allocator object, to allocate an array of bytes (u8 values) that is big enough to store the decoded pixel data of the image. Notice that I’m using @memset() to initialize the entire array to zero.\n\nconst output_size = try calc_output_size(ctx);\nvar buffer = try allocator.alloc(u8, output_size);\n@memset(buffer[0..], 0);\n\n\n\n15.4.3 Decoding the image data\nNow that we have the necessary space to store the decoded pixel data of the image, we can start to actually decode and extract this pixel data from the image, by using the spng_decode_image() C function.\nThe read_data_to_buffer() Zig function exposed below summarises the necessary steps to read this decoded pixel data, and store it into an input buffer. Notice that this function is encapsulating the logic around the spng_decode_image() function. Also, we are using the SPNG_FMT_RGBA8 enum value once again to inform the corresponding function, that the PNG image being decoded, uses the RGBA color model and 8 bit depth.\n\nfn read_data_to_buffer(ctx: *c.spng_ctx, buffer: []u8) !void {\n    const status = c.spng_decode_image(\n        ctx,\n        buffer.ptr,\n        buffer.len,\n        c.SPNG_FMT_RGBA8,\n        0\n    );\n\n    if (status != 0) {\n        return error.CouldNotDecodeImage;\n    }\n}\n\nHaving this function at hand, we can apply it over our context object, and also, over the buffer object that we have allocated in the previous section to hold the decoded pixel data of the image:\n\ntry read_data_to_buffer(ctx, buffer[0..]);\n\n\n\n15.4.4 Looking at the pixel data\nNow that we have the pixel data stored in our “buffer object”, we can take a quick look at the bytes. In the example below, we are looking at the first 12 bytes in the decoded pixel data.\nIf you take a close look at these values, you might notice that every 4 bytes in the sequence is 255. Which, coincidentally is the maximum possible integer value to be represented by a u8 value. So, if the range from 0 to 255, which is the range of integer values that can be represented by an u8 value, can be represented as a scale from 0% to 100%, these 255 values are essentially 100% in that scale.\nIf you recall from Section 15.2.2, I have described in that section that our pedro_pascal.png PNG file uses the RGBA color model, which adds an alpha (or transparency) byte to each pixel in the image. As consequence, each pixel in the image is represented by 4 bytes. Since we are looking here are the first 12 bytes in the image, it means that we are looking at the data from the first \\(12 / 4 = 3\\) pixels in the image.\nSo, based on how these first 12 bytes (or these 3 pixels) look, with these 255 values at every 4 bytes, we can say that is likely that every pixel in the image have alpha (or transparency) setted to 100%. This might not be true, but, is the most likely possibility. Also, if we look at the image itself, which if your recall is exposed at Figure 15.1, we can see that the transparency does not change across the image, which enforces this theory.\n\ntry stdout.print(\"{any}\\n\", .{buffer[0..12]});\n\n{\n    200, 194, 216, 255, 203, 197,\n    219, 255, 206, 200, 223, 255\n}\nWe can see in the above result that the first pixel in this image have 200 of red, 194 of green, and 216 of blue. How do I know the order in which the colors appears in the sequence? If you have not guessed that yet, is because of the acronym RGB. First RED, then GREEN, then BLUE. If we scale these integer values according to our scale of 0% to 100% (0 to 255), we get 78% of red, 76% of green and 85% of blue.",
+    "crumbs": [
+      "<span class='chapter-number'>15</span>  <span class='chapter-title'>Project 4 - Developing an image filter</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/13-image-filter.html#applying-the-image-filter",
+    "href": "Chapters/13-image-filter.html#applying-the-image-filter",
+    "title": "15  Project 4 - Developing an image filter",
+    "section": "15.5 Applying the image filter",
+    "text": "15.5 Applying the image filter\nNow that we have the data of each pixel in the image, we can focus on applying our image filter over these pixels. Remember, our objective here is to apply a grayscale filter over the image. A grayscale filter is a filter that transforms a colored image into a grayscale image.\nThere are different formulas and strategies to transform a colored image into a grayscale image. But all of these different strategies normally involve applying some math over the colors of each pixel. In this project, we are going to use the most general formula, which is exposed below. This formula considers \\(r\\) as the red of the pixel, \\(g\\) as the green, \\(b\\) as the blue, and \\(p'\\) as the linear luminance of the pixel.\n\\[\n    p' = (0.2126 \\times r) + (0.7152 \\times g) + (0.0722 \\times b)\n\\tag{15.1}\\]\nThis Equation 15.1 is the formula to calculate the linear luminance of a pixel. Is worth noting that this formula works only for images whose pixels are using the sRGB color space, which is the standard color space for the web. Thus, ideally, all images on the web should use this color space. Luckily, this is our case here, i.e. the pedro_pascal.png image is using this sRGB color space, and, as consequence, we can use the Equation 15.1. You can read more about this formula at the Wikipedia page for grayscale (Wikipedia 2024).\nThe apply_image_filter() function exposed below summarises the necessary steps to apply Equation 15.1 over the pixels in the image. We just apply this function over our buffer object that contains our pixel data, and, as result, the pixel data stored in this buffer object should now represent the grayscale version of our image.\n\nfn apply_image_filter(buffer:[]u8) !void {\n    const len = buffer.len;\n    const red_factor: f16 = 0.2126;\n    const green_factor: f16 = 0.7152;\n    const blue_factor: f16 = 0.0722;\n    var index: u64 = 0;\n    while (index &lt; len) : (index += 4) {\n        const rf: f16 = @floatFromInt(buffer[index]);\n        const gf: f16 = @floatFromInt(buffer[index + 1]);\n        const bf: f16 = @floatFromInt(buffer[index + 2]);\n        const y_linear: f16 = (\n            (rf * red_factor) + (gf * green_factor)\n            + (bf * blue_factor)\n        );\n        buffer[index] = @intFromFloat(y_linear);\n        buffer[index + 1] = @intFromFloat(y_linear);\n        buffer[index + 2] = @intFromFloat(y_linear);\n    }\n}\n\ntry apply_image_filter(buffer[0..]);",
+    "crumbs": [
+      "<span class='chapter-number'>15</span>  <span class='chapter-title'>Project 4 - Developing an image filter</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/13-image-filter.html#saving-the-grayscale-version-of-the-image",
+    "href": "Chapters/13-image-filter.html#saving-the-grayscale-version-of-the-image",
+    "title": "15  Project 4 - Developing an image filter",
+    "section": "15.6 Saving the grayscale version of the image",
+    "text": "15.6 Saving the grayscale version of the image\nSince we have now the grayscale version of our image stored in our buffer object, we need to encode this buffer object back into the “PNG format”, and save the encoded data into a new PNG file in our filesystem, so that we can access and see the grayscale version of our image that was produced by our small program.\nTo do that, the libspng library help us once again by offering an “encode data to PNG” type of function, which is the spng_encode_image() function. But in order to “encode data to PNG” with libspng, we need to create a new context object. This new context object must use an “encoder context”, which is identified by the enum value SPNG_CTX_ENCODER.\nThe save_png() function exposed below, summarises all the necessary steps to save the grayscale version of our image into a new PNG file in the filesystem. By default, this function will save the grayscale image into a file named pedro_pascal_filter.png in the CWD.\nNotice in this code example that we are using the same image header object (image_header) that we have collected previously with the get_image_header() function. Remember, this image header object is a C struct (spng_ihdr) that contains basic information about our PNG file, such as the dimensions of the image, the color model used, etc.\nIf we wanted to save a very different image in this new PNG file, e.g. an image with different dimensions, or, an image that uses a different color model, a different bit depth, etc. we would have to create a new image header (spng_ihdr) object that describes the properties of this new image.\nBut we are essentially saving the same image that we have begin with here (the dimensions of the image, the color model, etc. are all still the same). The only difference between the two images are the colors of the pixels, which are now “shades of gray”. As consequence, we can safely use the exact same image header data in this new PNG file.\n\nfn save_png(image_header: *c.spng_ihdr, buffer: []u8) !void {\n    const path = \"pedro_pascal_filter.png\";\n    const file_descriptor = c.fopen(path.ptr, \"wb\");\n    if (file_descriptor == null) {\n        return error.CouldNotOpenFile;\n    }\n    const ctx = (\n        c.spng_ctx_new(c.SPNG_CTX_ENCODER)\n        orelse unreachable\n    );\n    defer c.spng_ctx_free(ctx);\n    _ = c.spng_set_png_file(ctx, @ptrCast(file_descriptor));\n    _ = c.spng_set_ihdr(ctx, image_header);\n\n    const encode_status = c.spng_encode_image(\n        ctx,\n        buffer.ptr,\n        buffer.len,\n        c.SPNG_FMT_PNG,\n        c.SPNG_ENCODE_FINALIZE\n    );\n    if (encode_status != 0) {\n        return error.CouldNotEncodeImage;\n    }\n    if (c.fclose(file_descriptor) != 0) {\n        return error.CouldNotCloseFileDescriptor;\n    }\n}\n\ntry save_png(&image_header, buffer[0..]);\n\nAfter we execute this save_png() function, we should have a new PNG file inside our CWD, named pedro_pascal_filter.png. If we open this PNG file, we will see the same image exposed at Figure 15.2.",
+    "crumbs": [
+      "<span class='chapter-number'>15</span>  <span class='chapter-title'>Project 4 - Developing an image filter</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/13-image-filter.html#building-our-project",
+    "href": "Chapters/13-image-filter.html#building-our-project",
+    "title": "15  Project 4 - Developing an image filter",
+    "section": "15.7 Building our project",
+    "text": "15.7 Building our project\nNow that we have written the code, let’s discuss how can we build/compile this project. To do that, I’m going to create a build.zig file in the root directory of our project, and start writing the necessary code to compile the project, using the knowledge that we have acquired from Chapter 9.\nWe first create the build target for our executable file, that executes our Zig code. Let’s suppose that all of our Zig code was written into a Zig module named image_filter.zig. The exe object exposed in the build script below describes the build target for our executable file.\nSince we have used some C code from the libspng library in our Zig code, we need to link our Zig code (which is in the exe build target) to both the C Standard Library, and, to the libspng library. We do that, by calling the linkLibC() and linkSystemLibrary() methods from our exe build target.\n\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const target = b.standardTargetOptions(.{});\n    const optimize = b.standardOptimizeOption(.{});\n    const exe = b.addExecutable(.{\n        .name = \"image_filter\",\n        .root_source_file = b.path(\"src/image_filter.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n    exe.linkLibC();\n    // Link to libspng library:\n    exe.linkSystemLibrary(\"spng\");\n    b.installArtifact(exe);\n}\n\nSince we are using the linkSystemLibrary() method, it means that the library files for libspng are searched in your system to be linked with the exe build target. If you have not yet built and installed the libspng library into your system, this linkage step will likely not work. Because it will not find the library files in your system.\nSo, just remember to install libspng in your system, if you want to build this project. Having this build script above written, we can finally build our project by running the zig build command in the terminal.\nzig build\n\n\n\n\nWikipedia. 2024. “Grayscale.” Wikipedia. https://en.wikipedia.org/wiki/Grayscale.",
+    "crumbs": [
+      "<span class='chapter-number'>15</span>  <span class='chapter-title'>Project 4 - Developing an image filter</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/13-image-filter.html#footnotes",
+    "href": "Chapters/13-image-filter.html#footnotes",
+    "title": "15  Project 4 - Developing an image filter",
+    "section": "",
+    "text": "https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter↩︎\nhttps://library.si.edu/exhibition/color-in-a-new-light/science↩︎\nhttps://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter↩︎\nhttps://libspng.org/↩︎\nhttps://libspng.org/docs/build/↩︎",
+    "crumbs": [
+      "<span class='chapter-number'>15</span>  <span class='chapter-title'>Project 4 - Developing an image filter</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/14-threads.html",
+    "href": "Chapters/14-threads.html",
+    "title": "16  Introducing threads and parallelism in Zig",
+    "section": "",
+    "text": "16.1 What are threads?\nA thread is basically a separate context of execution. We use threads to introduce parallelism into our program, which in most cases, makes the program run faster, because we have multiple tasks being performed at the same time, parallel to each other.\nPrograms are normally single-threaded by default. Which means that each program usually runs on a single thread, or, a single context of execution. When we have only one thread running, we have no parallelism. And when we don’t have parallelism, the commands are executed sequentially, that is, only one command is executed at a time, one after another. By creating multiple threads inside our program, we start to execute multiple commands at the same time.\nPrograms that create multiple threads are very common on the wild. Because many different types of applications are well suited for parallelism. Good examples are video and photo-editing applications (e.g. Adobe Photoshop or DaVinci Resolve), games (e.g. The Witcher 3), and also web browsers (e.g. Google Chrome, Firefox, Microsoft Edge, etc). For example, in web browsers, threads are normally used to implement tabs. The tabs in a web browsers usually run as separate threads in the main process of the web browser. That is, each new tab that you open in your web browser, usually runs on a separate thread of execution.\nBy running each tab in a separate thread, we allow all open tabs in the browser to run at the same time, and independently from each other. For example, you might have YouTube, or Spotify, currently opened in a tab, and you are listening to some podcast in that tab, while, at the same time, you are working in another tab, writing an essay on Google Docs. Even if you are not looking into the YouTube tab, you can still hear the podcast only because this YouTube tab is running in parallel with the other tab where Google Docs is running.\nWithout threads, the other alternative would be to run each tab as a completely separate process in your computer. But that would be a bad choice, because just a few tabs would already consume too much power and resources from your computer. In other words, is very expensive to create a completely new process, compared to creating a new thread of execution. Also, the chances of you experiencing lag and overhead while using the browser would be significant. Threads are faster to create, and they also consume much, much less resources from the computer, especially because they share some resources with the main process.\nTherefore, is the use of threads in modern web browsers that allows you to hear the podcast at the same time while you are writing something on Google Docs. Without threads, a web browser would probably be limited to just one single tab.\nThreads are also well-suited for anything that involves serving requests or orders. Because serving a request takes time, and usually involves a lot of “waiting time”. In other words, we spend a lot of time in idle, waiting for something to complete. For example, consider a restaurant. Serving orders in a restaurant usually involves the following steps:\nIf you think about the bullet points above, you will notice that one big moment of waiting time is present in this whole process, which is while the food is being cooked inside the kitchen. While the food is being prepped, both the waiter and the client itself are waiting for the food to be ready and delivered.\nIf we write a program to represent this restaurant, more specifically, a single-threaded program, then, this program would be very inefficient. Because the program would stay in idle, waiting for a considerable amount of time on the “check if food is ready” step. Consider the code snippet exposed below that could potentially represent such program.\nThe problem with this program is the while loop. This program will spend a lot of time waiting on the while loop, doing nothing more than just checking if the food is ready. This is a waste of time. Instead of waiting for something to happen, the waiter could just send the order to the kitchen, and just move on, and continue with receiving more orders from other clients, and sending more orders to the kitchen, instead of doing nothing and waiting for the food to be ready.\nconst order = Order.init(\"Pizza Margherita\", n = 1);\nconst waiter = Waiter.init();\nwaiter.receive_order(order);\nwaiter.ask_kitchen_to_cook();\nvar food_not_ready = true;\nwhile (food_not_ready) {\n    food_not_ready = waiter.is_food_ready();\n}\nconst food = waiter.get_food_from_kitchen();\nwaiter.send_food_to_client(food);\nThis is why threads would be a great fit for this program. We could use threads to free the waiters from their “waiting duties”, so they can go on with their other tasks, and receive more orders. Take a look at the next example, where I have re-written the above program into a different program that uses threads to cook and deliver the orders.\nYou can see in this program that when a waiter receives a new order from a client, this waiter executes the send_order() function. The only thing that this function does is to create a new thread and detaches it. Since creating a thread is a very fast operation, this send_order() function returns almost immediately, so the waiter spends almost no time worrying about the order, and just move on and tries to get the next order from the clients.\nInside the new thread created, the order get’s cooked by a chef, and when the food is ready, it is delivered to the client’s table.\nfn cook_and_deliver_order(order: *Order) void {\n    const chef = Chef.init();\n    const food = chef.cook(order.*);\n    chef.deliver_food(food);\n}\nfn send_order(order: Order) void {\n    const cook_thread = Thread.spawn(\n        .{}, cook_and_deliver_order, .{&order}\n    );\n    cook_thread.detach();\n}\n\nconst waiter = Waiter.init();\nwhile (true) {\n    const order = waiter.get_new_order();\n    if (order) {\n        send_order(order);\n    }\n}",
+    "crumbs": [
+      "<span class='chapter-number'>16</span>  <span class='chapter-title'>Introducing threads and parallelism in Zig</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/14-threads.html#sec-what-thread",
+    "href": "Chapters/14-threads.html#sec-what-thread",
+    "title": "16  Introducing threads and parallelism in Zig",
+    "section": "",
+    "text": "receive order from the client.\npass the order to the kitchen, and wait for the food to be cooked.\nstart cooking the food in the kitchen.\nwhen the food is fully cooked deliver this food to the client.",
+    "crumbs": [
+      "<span class='chapter-number'>16</span>  <span class='chapter-title'>Introducing threads and parallelism in Zig</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/14-threads.html#threads-versus-processes",
+    "href": "Chapters/14-threads.html#threads-versus-processes",
+    "title": "16  Introducing threads and parallelism in Zig",
+    "section": "16.2 Threads versus processes",
+    "text": "16.2 Threads versus processes\nWhen we run a program, this program is executed as a process in the operating system. This is a one to one relationship, each program or application that you execute is a separate process in the operating system. But each program, or each process, can create and contain multiple threads inside of it. Therefore, processes and threads have a one to many relationship.\nThis also means that every thread that we create is always associated with a particular process in our computer. In other words, a thread is always a subset (or a children) of an existing process. All threads share some of the resources associated with the process from which they were created. And because threads share resources with the process, they are very good for making communication between tasks easier.\nFor example, suppose that you were developing a big and complex application that would be much simpler if you could split it in two, and make these two separate pieces talk with each other. Some programmers opt to effectively write these two pieces of the codebase as two completely separate programs, and then, they use IPC (inter-process communication) to make these two separate programs/processes talk to each other, and make them work together.\nHowever, some programmers find IPC hard to deal with, and, as consequence, they prefer to write one piece of the codebase as the “main part of the program”, or, as the part of the code that runs as the process in the operating system, while the other piece of the codebase is written as a task to be executed in a new thread. A process and a thread can easily comunicate with each other through both control flow, and also, through data, because they share and have access to the same standard file descriptors (stdout, stdin, stderr), and also to the same memory space on the heap and global data section.\nIn more details, each thread that you create have a separate stack frame reserved just for that thread, which essentially means that each local object that you create inside this thread, is local to that thread, i.e. the other threads cannot see this local object. Unless this object that you have created is an object that lives on the heap. In other words, if the memory associated with this object is on the heap, then, the other threads can potentially access this object.\nTherefore, objects that are stored in the stack are local to the thread where they were created. But objects that are stored on the heap are potentially accessible to other threads. All of this means that, each thread have its own separate stack frame, but, at the same time, all threads share the same heap, the same standard file descriptors (which means that they share the same stdout, stdin, stderr), and the same global data section in the program.",
+    "crumbs": [
+      "<span class='chapter-number'>16</span>  <span class='chapter-title'>Introducing threads and parallelism in Zig</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/14-threads.html#creating-a-thread",
+    "href": "Chapters/14-threads.html#creating-a-thread",
+    "title": "16  Introducing threads and parallelism in Zig",
+    "section": "16.3 Creating a thread",
+    "text": "16.3 Creating a thread\nWe create new threads in Zig, by first, importing the Thread struct into our current Zig module, and then, calling the spawn() method of this struct, which creates (or, “spawns”) a new thread of execution from our current process. This method have three arguments, which are, respectively:\n\na SpawnConfig object, which contains configurations for the spawn process.\nthe name of the function that is going to be executed (or, that is going to be “called”) inside this new thread.\na list of arguments (or inputs) to be passed to the function provided in the second argument.\n\nWith these three arguments, you can control how the thread get’s created, and also, specify which work (or “tasks”) will be performed inside this new thread. A thread is just a separate context of execution, and we usually create new threads in our code, because we want to perform some work inside this new context of execution. And we specify which exact work, or, which exact steps that are going to be performed inside this context, by providing the name of a function on the second argument of the spawn() method.\nThus, when this new thread get’s created, this function that you provided as input to the spawn() method get’s called, or, get’s executed inside this new thread. You can control the arguments, or, the inputs that are passed to this function when it get’s called, by providing a list of arguments (or a list of inputs) on the third argument of the spawn() method. These arguments are passed to the function in the same order that they are provided to spawn().\nFurthermore, the SpawnConfig is a struct object with only two possible fields, or, two possible members, that you can set to tailor the spawn behaviour. These fields are:\n\nstack_size: you can provide an usize value to specify the size (in bytes) of the thread’s stack frame. By default, this value is: \\(16 \\times 1024 \\times 1024\\).\nallocator: you can provide an allocator object to be used when allocating memory for the thread.\n\nTo use one of these two fields (or, “configs”) you just have to create a new object of type SpawnConfig, and provide this object as input to the spawn() method. But, if you are not interested in using one of these configs, and you are ok with using just the defaults, you can just provide an anonymous struct literal (.{}) in the place of this SpawnConfig argument.\nAs our first, and very simple example, consider the code exposed below. Inside the same program, you can create multiple threads of execution if you want to. But, in this first example, we are creating just a single thread of execution, because we call spawn() only once.\nAlso, notice in this example that we are executing the function do_some_work() inside the new thread. Since this function receives no inputs, because it has no arguments, we have passed an empty list in this instance, or, more precisely, an empty and anonymous struct (.{}) in the third argument of spawn().\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Thread = std.Thread;\nfn do_some_work() !void {\n    _ = try stdout.write(\"Starting the work.\\n\");\n    std.time.sleep(100 * std.time.ns_per_ms);\n    _ = try stdout.write(\"Finishing the work.\\n\");\n}\n\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, do_some_work, .{});\n    thread.join();\n}\n\nStarting the work.Finishing the work.\n\n\nNotice the use of try when calling the spawn() method. This means that this method can return an error in some circumstances. One circumstance in particular is when you attempt to create a new thread, when you have already created too much (i.e. you have exceeded the quota of concurrent threads in your system).\nBut, if the new thread is successfully created, the spawn() method returns a handler object (which is just an object of type Thread) to this new thread. You can use this handler object to effectively control all aspects of the thread.\nWhen the thread get’s created, the function that you provided as input to spawn() get’s invoked (i.e. get’s called) to start the execution on this new thread. In other words, everytime you call spawn(), not only a new thread get’s created, but also, the “start work button” of this thread get’s automatically pressed. So the work being performed in this thread starts at the moment that the thread is created. This is similar to how pthread_create() from the pthreads library in C works, which also starts the execution at the moment that the thread get’s created.",
+    "crumbs": [
+      "<span class='chapter-number'>16</span>  <span class='chapter-title'>Introducing threads and parallelism in Zig</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/14-threads.html#returning-from-a-thread",
+    "href": "Chapters/14-threads.html#returning-from-a-thread",
+    "title": "16  Introducing threads and parallelism in Zig",
+    "section": "16.4 Returning from a thread",
+    "text": "16.4 Returning from a thread\nWe have learned on the previous section that the execution of the thread starts at the moment that the thread get’s created. Now, we will learn how to “join” or “detach” a thread in Zig. “Join” and “detach” are operations that control how the thread returns to the main thread, or, to the main process in our program.\nWe perform these operations by using the methods join() and detach() from the thread handler object. Every thread that you create can be marked as either joinable or detached (Linux man-pages 2024). You can turn a thread into a detached thread by calling the detach() method from the thread handler object. But if you call the join() method instead, then, this thread becomes a joinable thread.\nA thread cannot be both joinable and detached. Which in general means that you cannot call both join() and detach() on the same thread. But a thread must be one of the two, meaning that, you should always call either join() or detach() over a thread. If you don’t call one of these two methods over your thread, you introduce undefined behaviour into your program, which is described at Section 16.9.2.\nNow, let’s describe what each of these two methods do to your thread.\n\n16.4.1 Joining a thread\nWhen you join a thread, you are essentially saying: “Hey! Could you please wait for the thread to finish, before you continue with your execution?”. For example, if we comeback to our first and simpliest example of a thread in Zig, in that example we have created a single thread inside the main() function of our program, and just called join() over this thread at the end. This section of the code example is reproduced below.\nBecause we are joining this new thread inside the main()’s scope, it means that the execution of the main() function is temporarily stopped, to wait for the execution of the thread to finish. That is, the execution of main() stops temporarily at the line where join() get’s called, and it will continue only after the thread has finished its tasks.\n\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, do_some_work, .{});\n    thread.join();\n}\n\nBecause we have joined this new thread inside the main() scope, we have a guarantee that this new thread will finish before the end of the execution of main(). Because it is guaranteed that main() will wait for the thread to finish its tasks.\nIn the example above, there are no more expressions after the join() call. We just have the end of the main()’s scope, and, therefore, the execution of our program just ends after the thread finishes its tasks, since there is nothing more to do. But what if we had more stuff to do after the join call?\nTo demonstrate this other possibility, consider the next example exposed below. Here, we create a print_id() function, that just receives an id as input, and prints it to stdout. In this example, we are creating two new threads, one after another. Then, we join the first thread, then, we wait for two whole seconds, then, at last, we join the second thread.\nThe idea behind this example is that the last join() call is executed only after the first thread finishes its task (i.e. the first join() call), and also, after the two seconds of delay. If you compile and run this example, you will notice that most messages are quickly printed to stdout, i.e. they appear almost instantly on your screen. However, the last message (“Joining thread 2”) takes around 2 seconds to appear in the screen.\n\nfn print_id(id: *const u8) !void {\n    try stdout.print(\"Thread ID: {d}\\n\", .{id.*});\n}\n\npub fn main() !void {\n    const id1: u8 = 1;\n    const id2: u8 = 2;\n    const thread1 = try Thread.spawn(.{}, print_id, .{&id1});\n    const thread2 = try Thread.spawn(.{}, print_id, .{&id2});\n\n    _ = try stdout.write(\"Joining thread 1\\n\");\n    thread1.join();\n    std.time.sleep(2 * std.time.ns_per_s);\n    _ = try stdout.write(\"Joining thread 2\\n\");\n    thread2.join();\n}\n\nThread ID: Joining thread 1\n1\nThread ID: 2\nJoining thread 2\nThis demonstrates that both threads finish their work (i.e. printing the IDs) very fast, before the two seconds of delay end. Because of that, the last join() call returns pretty much instantly. Because when this last join() call happens, the second thread have already finished its task.\nNow, if you compile and run this example, you will also notice that, in some cases, the messages intertwine with each other. In other words, you might see the message “Joining thread 1” inserted in the middle of the message “Thread 1”, or vice-versa. This happens because:\n\nthe threads are executing basically at the same time as the main process of the program (i.e. the main() function).\nthe threads share the same stdout from the main process of the program, which means that the messages that the threads produce are sent to exact same place as the messages produced by the main process.\n\nBoth of these points were described previously at Section 16.1. So the messages might get intertwined because they are being produced and sent to the same stdout roughly at the same time. Anyway, when you call join() over a thread, the current process will wait for the thread to finish before it continues, and, when the thread does finishes its task, the resources associated with this thread are automatically freed, and, the current process continues with its execution.\n\n\n16.4.2 Detaching a thread\nWhen you detach a thread, the resources associated with this thread are automatically released back to the system, without the need for another thread to join with this terminated thread.\nIn other words, when you call detach() over a thread it’s like when your children becomes adults, i.e. they become independent from you. A detached thread frees itself, and when this thread finishes its tasks, it does not report the results back to you. Thus, you normally mark a thread as detached when you don’t need to use the return value of the thread, or, when you don’t care about when exactly the thread finishes its job, i.e. the thread solves everything by itself.\nTake the code example below. We create a new thread, detach it, and then, we just print a final message before we end our program. We use the same print_id() function that we have used over the previous examples.\n\nfn print_id(id: *const u8) !void {\n    try stdout.print(\"Thread ID: {d}\\n\", .{id.*});\n}\n\npub fn main() !void {\n    const id1: u8 = 1;\n    const thread1 = try Thread.spawn(.{}, print_id, .{&id1});\n    thread1.detach();\n    _ = try stdout.write(\"Finish main\\n\");\n}\n\nFinish main\nNow, if you look closely at the output of this code example, you will notice that only the final message in main was printed to the console. The message that was supposed to be printed by print_id() did not appear in the console. Why? Is because the main process of our program has finished first, before the thread was able to say anything.\nAnd that is perfectly ok behaviour, because the thread was detached, so, it was able to free itself, without the need to wait for the main process. If you ask main to sleep (or “wait”) for some extra nanoseconds, before it ends, you will likely see the message printed by print_id(), because you give enough time for the thread to finish before the main process ends.",
+    "crumbs": [
+      "<span class='chapter-number'>16</span>  <span class='chapter-title'>Introducing threads and parallelism in Zig</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/14-threads.html#thread-pools",
+    "href": "Chapters/14-threads.html#thread-pools",
+    "title": "16  Introducing threads and parallelism in Zig",
+    "section": "16.5 Thread pools",
+    "text": "16.5 Thread pools\nThread pools is a very popular programming pattern, which is used especially on servers and daemons processes. A thread pool is just a set of threads, or, a “pool” of threads. Many programmers like to use this pattern, because it makes easier to manage and use multiple threads in your program, instead of manually creating the threads when you need them.\nAlso, using thread pools might increase performance as well in your program, especially if your program is constantly creating threads to perform short-lived tasks. In such instance, a thread pool might cause an increase in performance because you do not have be constantly creating and destroying threads all the time, so you don’t face a lot of the overhead involved in this constant process of creating and destroying threads.\nThe main idea behind a thread pool is to have a set of threads already created and ready to perform tasks at all times. You create a set of threads at the moment that your program starts, and keep these threads alive while your program runs. Each of these threads will be either performing a task, or, waiting for a task to be assigned. Every time a new task emerges in your program, this task is added to a “queue of tasks”, and the moment that a thread becomes available and ready to perform a new task, this thread takes the next task from the “queue of tasks”, and it simply performs the task.\nThe Zig Standard Library offers a thread pool implementation on the std.Thread.Pool struct. You create a new instance of a Pool object by providing a Pool.Options object as input to the init() method of this struct. A Pool.Options object, is a struct object that contains configurations for the pool of threads. The most important settings in this struct object are the members n_jobs and allocator. As the name suggests, the member allocator should receive an allocator object, while the member n_jobs specifies the number of threads to be created and maintained in this pool.\nConsider the example exposed below, that demonstrates how can we create a new thread pool object. Here, we create a Pool.Options object that contains a general purpose allocator object, and also, the n_jobs member was set to 4, which means that the thread pool will create and use 4 threads.\nAlso notice that the pool object was initially set to undefined. This allow us to initially declare the thread pool object, but not properly instantiate the underlying memory of the object. You have to initially declare your thread pool object by using undefined like this, because the init() method of Pool needs to have an initial pointer to properly instantiate the object.\nSo, just remember to create your thread pool object by using undefined, and then, after that, you call the init() method over the object. You should also not forget to call the deinit() method over the thread pool object, once you are done with it, to release the resources allocated for the thread pool. Otherwise, you will have a memory leak in your program.\n\nconst std = @import(\"std\");\nconst Pool = std.Thread.Pool;\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const opt = Pool.Options{\n        .n_jobs = 4,\n        .allocator = allocator,\n    };\n    var pool: Pool = undefined;\n    _ = try pool.init(opt);\n    defer pool.deinit();\n}\n\nNow that we know how to create Pool objects, we have to understand how to assign tasks to be executed by the threads in this pool object. To assign a task to be performed by a thread, we need to call the spawn() method from the thread pool object.\nThis spawn() method works identical to the spawn() method from the Thread object. The method have almost the same arguments as the previous one, more precisely, we don’t have to provide a SpawnConfig object in this case. But instead of creating a new thread, this spawn() method from the thread pool object just register a new task in the internal “queue of tasks” to be performed, and any available thread in the pool will get this task, and it will simply perform the task.\nIn the example below, we are using our previous print_id() function once again. But you may notice that the print_id() function is a little different this time, because now we are using catch instead of try in the print() call. Currently, the Pool struct only supports functions that don’t return errors as tasks. Thus, when assigning tasks to threads in a thread pool, is essential to use functions that don’t return errors. That is why we are using catch here, so that the print_id() function don’t return an error.\n\nfn print_id(id: *const u8) void {\n    _ = stdout.print(\"Thread ID: {d}\\n\", .{id.*})\n        catch void;\n}\nconst id1: u8 = 1;\nconst id2: u8 = 2;\ntry pool.spawn(print_id, .{&id1});\ntry pool.spawn(print_id, .{&id2});\n\nThis limitation should probably not exist, and, in fact, it is already on the radar of the Zig team to fix this issue, and it is being tracked on an open issue1. So, if you do need to provide a function that might return an error as the task to be performed by the threads in the thread pool, then, you are either limited to:\n\nimplementing your own thread pool that does not have this limitation.\nwait for the Zig team to actually fix this issue.",
+    "crumbs": [
+      "<span class='chapter-number'>16</span>  <span class='chapter-title'>Introducing threads and parallelism in Zig</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/14-threads.html#mutexes",
+    "href": "Chapters/14-threads.html#mutexes",
+    "title": "16  Introducing threads and parallelism in Zig",
+    "section": "16.6 Mutexes",
+    "text": "16.6 Mutexes\nMutexes are a classic component of every thread library. In essence, a mutex is a Mutually Exclusive Flag, and this flag acts like a type of “lock”, or as a gate keeper to a particular section of your code. Mutexes are related to thread synchronization, more specifically, they prevent you from having some classic race conditions in your program, and, therefore, major bugs and undefined behaviour that are usually difficult to track and understand.\nThe main idea behind a mutex is to help us to control the execution of a particular section of the code, and to prevent two or more threads from executing this particular section of the code at the same time. Many programmers like to compare a mutex to a bathroom door (which usually have a lock). When a thread locks its own mutex object, it is like if the bathroom door was locked, and, therefore, the other people (in this case, the other threads) that wants to use the same bathroom at the same time have to be patient, and simply wait for the other person (or the other thread) to unlock the door and get out of the bathroom.\nSome other programmers also like to explain mutexes by using the analogy of “each person will have their turn to speak”. This is the analogy used on the Multithreading Code video from the Computerphile project2. Imagine if you are in a conversation circle. There is a moderator in this circle, which is the person that decides who have the right to speak at that particular moment. The moderator gives a green card (or some sort of an authorization card) to the person that is going to speak, and, as a result, everyone else must be silent and hear this person that has the green card. When the person finishes talking, it gives the green card back to the moderator, and the moderator decides who is going to talk next, and delivers the green card to that person. And the cycle goes on like this.\nA mutex acts like the moderator in this conversation circle. The mutex authorizes one single thread to execute a specific section of the code, and it also blocks the other threads from executing this same section of the code. If these other threads want to execute this same piece of the code, they are forced to wait for the the authorized thread to finish first. When the authorized thread finishes executing this code, the mutex authorizes the next thread to execute this code, and the other threads are still blocked. Therefore, a mutex is like a moderator that does a “each thread will have their turn to execute this section of the code” type of control.\nMutexes are especially used to prevent data race problems from happening. A data race problem happens when two or more threads are trying to read from or write to the same shared object at the same time. So, when you have an object that is shared will all threads, and, you want to avoid two or more threads from accessing this same object at the same time, you can use a mutex to lock the part of the code that access this specific object. When a thread tries to run this code that is locked by a mutex, this thread stops its execution, and patiently waits for this section of the codebase to be unlocked to continue.\nNotice that mutexes are normally used to lock areas of the codebase that access/modify data that is shared with all threads, i.e. objects that are either stored in the global data section, or, in the heap space of your program. So mutexes are not normally used on areas of the codebase that access/modify objects that are local to the thread.\n\n16.6.1 Critical section\nCritical section is a concept commonly associated with mutexes and thread synchronization. In essence, a critical section is the section of the program that a thread access/modify a shared resource (i.e. an object, a file descriptor, something that all threads have access to). In other words, a critical section is the section of the program where race conditions might happen, and, therefore, where undefined behaviour can be introduced into the program.\nWhen we use mutexes in our program, the critical section defines the area of the codebase that we want to lock. So we normally lock the mutex object at the beginning of the critical section, and then, we unlock it at the end of the critical section. The two bullet points exposed below comes from the “Critical Section” article from GeekFromGeeks, and they summarise well the role that a critical section plays in the thread synchronization problem (Geeks for Geeks 2024).\n\nThe critical section must be executed as an atomic operation, which means that once one thread or process has entered the critical section, all other threads or processes must wait until the executing thread or process exits the critical section. The purpose of synchronization mechanisms is to ensure that only one thread or process can execute the critical section at a time.\nThe concept of a critical section is central to synchronization in computer systems, as it is necessary to ensure that multiple threads or processes can execute concurrently without interfering with each other. Various synchronization mechanisms such as semaphores, mutexes, monitors, and condition variables are used to implement critical sections and ensure that shared resources are accessed in a mutually exclusive manner.\n\n\n\n16.6.2 Atomic operations\nYou will also see the term “atomic operation” a lot when reading about threads, race conditions and mutexes. In summary, an operation is categorized as “atomic”, when there is no way to happen a context switch in the middle of this operation. In other words, this operation is always done from beginning to end, without interruptions of another process or operation in the middle of its execution phase.\nNot many operations today are atomic. But why atomic operations matters here? Is because data races (which is a type of a race condition) cannot happen on operations that are atomic. So if a particular line in your code performs an atomic operation, then, this line will never suffer from a data race problem. Therefore, programmers sometimes use an atomic operation to protect themselves from data race problems in their code.\nWhen you have an operation that is compiled into just one single assembly instruction, this operation might be atomic, because it is just one assembly instruction. But this is not guaranteed. This is usually true for old CPU architectures (such as x86). But nowadays, most assembly instructions in modern CPU architectures turn into multiple micro-tasks, which inherently makes the operation not atomic anymore, even though it has just one single assembly instruction.\nThe Zig Standard Library offers some atomic functionality at the std.atomic module. In this module, you will find a public and generic function called Value(). With this function we create an “atomic object”, which is a value that contains some native atomic operations, most notably, a load() and a fetchAdd() operation. If you have experience with multithreading in C++, you probably have recognized this pattern. So yes, this generic “atomic object” in Zig is essentially identical to the template struct std::atomic from the C++ Standard Library. Is important to emphasize that only primitive data types (i.e. the types presented at Section 1.5) are supported by these atomic operations in Zig.\n\n\n16.6.3 Data races and race conditions\nTo understand why mutexes are used, we need to understand better the problem that they seek to solve, which can be summarized into data races problems. A data race problem is a type of a race condition, which happens when one thread is accessing a particular memory location (i.e. a particular shared object) at the same time that another thread is trying to write/save new data into this same memory location (i.e. the same shared object).\nWe can simply define a race condition as any type of bug in your program that is based on a “who get’s there first” problem. A data race problem is a type of a race condition, because it occurs when two or more parties are trying to read and write into the same memory location at the same time, and, therefore, the end result of this operation depends completely on who get’s to this memory location first. As consequence, a program that have a data race problem will likely produce a different result each time that we execute it.\nThus, race conditions produce undefined behaviour and unpredictability because the program produces a different answer in each time that a different person get’s to the target location first than the others. And we have no easy way to either predict or control who is getting to this target location first. In other words, in each execution of your program, you get a different answer, because a different person, or, a different function, or, a different part of the code is finishing its tasks first than the others.\nAs an example, consider the code snippet exposed below. In this example, we create a global counter variable, and we also create an increment() function, whose job is to just increment this global counter variable in a for loop.\nSince the for loop iterates 1 hundred thousand times, and, we create two separate threads in this code example, what number do you expect to see in the final message printed to stdout? The answer should be 2 hundred thousand. Right? Well, in theory, this program was supposed to print 2 hundred thousand at the end, but in practice, every time that I execute this program I get a different answer.\nIn the example exposed below, you can see that this time the end result was 117254, instead of the expected 200000. The second time I have executed this program, I got the number 108592 as result. So the end result of this program is varying, but it never gets to the expected 200000 that we want.\n\n// Global counter variable\nvar counter: usize = 0;\n// Function to increment the counter\nfn increment() void {\n    for (0..100000) |_| {\n        counter += 1;\n    }\n}\n\npub fn main() !void {\n    const thr1 = try Thread.spawn(.{}, increment, .{});\n    const thr2 = try Thread.spawn(.{}, increment, .{});\n    thr1.join();\n    thr2.join();\n    try stdout.print(\"Couter value: {d}\\n\", .{counter});\n}\n\nCouter value: 117254\nWhy this is happening? The answer is: because this program contains a data race problem. This program would print the correct number 200000, if, and only if the first thread finishes its tasks before the second thread starts to execute. But that is very unlikely to happen. Because the process of creating the thread is too fast, and therefore, both threads starts to execute roughly at the same time. If you change this code to add some nanoseconds of sleep between the first and the second calls to spawn(), you will increase the chances of the program producing the “correct result”.\nSo the data race problem happens, because both threads are reading and writing to the same memory location at roughly the same time. In this example, each thread is essentially performing three basic operations at each iteration of the for loop, which are:\n\nreading the current value of count.\nincrementing this value by 1.\nwriting the result back into count.\n\nIdeally, a thread B should read the value of count, only after the other thread A has finished writing the incremented value back into the count object. Therefore, in the ideal scenario, which is demonstrated at Table 16.1, the threads should work in sync with each other. But the reality is that these threads are out of sync, and because of that, they suffer from a data race problem, which is demonstrated at Table 16.2.\nNotice that, in the data race scenario (Table 16.2), the read performed by a thread B happens before the write operation of thread A, and that ultimately leads to wrong results at the end of the program. Because when the thread B reads the value from the count variable, the thread A is still processing the initial value from count, and it did not write the new and incremented value into count yet. So what happens is that thread B ends up reading the same initial value (the “old” value) from count, instead of reading the new and incremented version of this value that would be calculated by thread A.\n\n\n\nTable 16.1: An ideal scenario for two threads incrementing the same integer value\n\n\n\n\n\nThread 1\nThread 2\nInteger value\n\n\n\n\nread value\n\n0\n\n\nincrement\n\n1\n\n\nwrite value\n\n1\n\n\n\nread value\n1\n\n\n\nincrement\n2\n\n\n\nwrite value\n2\n\n\n\n\n\n\n\n\n\nTable 16.2: A data race scenario when two threads are incrementing the same integer value\n\n\n\n\n\nThread 1\nThread 2\nInteger value\n\n\n\n\nread value\n\n0\n\n\n\nread value\n0\n\n\nincrement\n\n1\n\n\n\nincrement\n1\n\n\nwrite value\n\n1\n\n\n\nwrite value\n1\n\n\n\n\n\n\nIf you think about these diagrams exposed in form of tables, you will notice that they relate back to our discussion of atomic operations at Section 16.6.2. Remember, atomic operations are operations that the CPU executes from beginning to end, without interruptions from other threads or processes. So, the scenario exposed at Table 16.1 do not suffer from a data race, because the operations performed by thread A are not interrupted in the middle by the operations from thread B.\nIf we also think about the discussion of critical section from Section 16.6.1, we can identify the section that representes the critical section of the program, which is the section that is vulnerable to data race conditions. In this example, the critical section of the program is the line where we increment the counter variable (counter += 1). So, ideally, we want to use a mutex, and lock right before this line, and then, unlock right after this line.\n\n\n16.6.4 Using mutexes in Zig\nNow that we know the problem that mutexes seek to solve, we can learn how to use them in Zig. Mutexes in Zig are available through the std.Thread.Mutex struct from the Zig Standard Library. If we take the same code example from the previous example, and improve it with mutexes, to solve our data race problem, we get the code example exposed below.\nNotice that we had this time to alter the increment() function to receive a pointer to the Mutex object as input. All that we need to do, to make this program safe against data race problems, is to call the lock() method at the beginning of the critical section, and then, call unlock() at the end of the critical section. Notice that the output of this program is now the correct number of 200000.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Thread = std.Thread;\nconst Mutex = std.Thread.Mutex;\nvar counter: usize = 0;\nfn increment(mutex: *Mutex) void {\n    for (0..100000) |_| {\n        mutex.lock();\n        counter += 1;\n        mutex.unlock();\n    }\n}\n\npub fn main() !void {\n    var mutex: Mutex = .{};\n    const thr1 = try Thread.spawn(.{}, increment, .{&mutex});\n    const thr2 = try Thread.spawn(.{}, increment, .{&mutex});\n    thr1.join();\n    thr2.join();\n    try stdout.print(\"Couter value: {d}\\n\", .{counter});\n}\n\nCouter value: 200000",
+    "crumbs": [
+      "<span class='chapter-number'>16</span>  <span class='chapter-title'>Introducing threads and parallelism in Zig</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/14-threads.html#readwrite-locks",
+    "href": "Chapters/14-threads.html#readwrite-locks",
+    "title": "16  Introducing threads and parallelism in Zig",
+    "section": "16.7 Read/Write locks",
+    "text": "16.7 Read/Write locks\nMutexes are normally used when is always not safe to have two or more threads running the same piece of code at the same time. In contrast, read/write locks are normally used in situations where you have a mixture of scenarios, i.e. there are some pieces of the codebase that are safe to run in parallel, and other pieces that are not safe.\nFor example, suppose that you have multiple threads that uses the same shared file in the filesystem to store some configurations, or, statistics. If two or more threads try to read the data from this same file at the same time, nothing bad happens. So this part of the codebase is perfectly safe to be executed in parallel, with multiple threads reading the same file at the same time.\nHowever, if two or more threads try to write data into this same file at the same time, then, we cause some race conditions problems. So this other part of the codebase is not safe to be executed in parallel. More specifically, a thread might end up writing data in the middle of the data written by the other thread. This process of two or more threads writing to the same location, might lead to data corruption. This specific situation is usually called of a torn write.\nThus, what we can extract from this example is that there is certain types of operations that causes a race condition, but there are also, other types of operations that do not cause a race condition problem. You could also say that, there are types of operations that are susceptible to race condition problems, and there are other types of operations that are not.\nA read/write lock is a type of lock that acknowledges the existance of this specific scenario, and you can use this type of lock to control which parts of the codebase are safe to run in parallel, and which parts are not safe.\n\n16.7.1 Exclusive lock vs shared lock\nTherefore, a read/write lock is a little different from a mutex. Because a mutex is always an exclusive lock, meaning that, only one thread is allowed to execute at all times. With an exclusive lock, the other threads are always “excluded”, i.e. they are always blocked from executing. But in a read/write lock, the other threads might be authorized to run at the same time, depending on the type of lock that they acquire.\nWe have two types of locks in a read/write lock, which are: an exclusive lock and a shared lock. An exclusive lock works exactly the same as a mutex, while a shared lock is a lock that does not block the other threads from running at the same time. In the pthreads C library, read/write locks are available through the pthread_rwlock_t C struct. With this C struct, you can create:\n\na “write lock”, which corresponds to an exclusive lock.\na “read lock”, which corresponds to a shared lock.\n\nThe terminology might be a little different compared to Zig. But the meaning is still the same. Therefore, just remember this relationship, write locks are exclusive locks, while read locks are shared locks.\nWhen a thread tries to acquire a read lock (i.e. a shared lock), this thread get’s the shared lock if, and only if another thread does not currently holds a write lock (i.e. an exclusive lock), and also, if there are no other threads that are already in the queue, waiting for their turn to acquire a write lock. In other words, the thread in the queue have attempted to get a write lock earlier, but this thread was blocked because there was another thread running that already had a write lock. As consequence, this thread is on the queue to get a write lock, and it’s currently waiting for the other thread with a write lock to finish its execution.\nWhen a thread tries to acquire a read lock, but it fails in acquiring this read lock, either because there is a thread with a write lock already running, or, because there is a thread in the queue to get a write lock, the execution of this thread is instantly blocked, i.e. paused. This thread will indefinitely attempt to get the read lock, and its execution will be unblocked (or unpaused) only after this thread successfully acquires the read lock.\nIf you think deeply about this dynamic between read locks versus write locks, you might notice that a read lock is basically a safety mechanism. More specifically, it is a way for us to allow a particular thread to run together with the other threads, only when it’s safe to. In other words, if there is currently a thread with a write lock running, then, it is very likely not safe for the thread that is trying to acquire the read lock to run now. As consequence, the read lock protects this thread from running into dangerous waters, and patiently waits for the “write lock” thread to finishes its tasks before it continues.\nOn the other hand, if there are only “read lock” (i.e. “shared lock”) threads currently running (i.e. not a single “write lock” thread currently exists), then, is perfectly safe for this thread that is acquiring the read lock to run in parallel with the other threads. As a result, the read lock just allows for this thread to run together with the other threads.\nThus, by using read locks (shared locks) in conjunction with write locks (exclusive locks), we can control which regions or sections of our multithreaded code is safe to have parallelism, and which sections are not safe to have parallelism.\n\n\n16.7.2 Using read/write locks in Zig\nThe Zig Standard Library supports read/write locks through the std.Thread.RwLock module. If you want to a particular thread to acquire a shared lock (i.e. a read lock), you should call the lockShared() method from the RwLock object. But, if you want for this thread to acquire an exclusive lock (i.e. a write lock) instead, then, you should call the lock() method from the RwLock object.\nAs with mutexes, we also have to unlock the shared or exclusive locks that we acquire through a read/write lock object, once we are at the end of our “critical section”. If you have acquired an exclusive lock, then, you unlock this exclusive lock by calling the unlock() method from the read/write lock object. In contrast, if you have acquired a shared lock instead, then, call unlockShared() to unlock this shared lock.\nAs a simple example, the snippet exposed below creates three separate threads responsible for reading the current value in a counter object, and it also creates another thread, responsible for writing new data into the counter object (incrementing it, more specifically).\n\nvar counter: u32 = 0;\nfn reader(lock: *RwLock) !void {\n    while (true) {\n        lock.lockShared();\n        const v: u32 = counter;\n        try stdout.print(\"{d}\", .{v});\n        lock.unlockShared();\n        std.time.sleep(2 * std.time.ns_per_s);\n    }\n}\nfn writer(lock: *RwLock) void {\n    while (true) {\n        lock.lock();\n        counter += 1;\n        lock.unlock();\n        std.time.sleep(2 * std.time.ns_per_s);\n    }\n}\n\npub fn main() !void {\n    var lock: RwLock = .{};\n    const thr1 = try Thread.spawn(.{}, reader, .{&lock});\n    const thr2 = try Thread.spawn(.{}, reader, .{&lock});\n    const thr3 = try Thread.spawn(.{}, reader, .{&lock});\n    const wthread = try Thread.spawn(.{}, writer, .{&lock});\n\n    thr1.join();\n    thr2.join();\n    thr3.join();\n    wthread.join();\n}",
+    "crumbs": [
+      "<span class='chapter-number'>16</span>  <span class='chapter-title'>Introducing threads and parallelism in Zig</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/14-threads.html#yielding-a-thread",
+    "href": "Chapters/14-threads.html#yielding-a-thread",
+    "title": "16  Introducing threads and parallelism in Zig",
+    "section": "16.8 Yielding a thread",
+    "text": "16.8 Yielding a thread\nThe Thread struct supports yielding through the yield() method. Yielding a thread means that the execution of the thread is temporarily stopped, and the thread comes back to the end of the queue of priority of the scheduler from your operating system.\nThat is, when you yield a thread, you are essentially saying the following to your OS: “Hey! Could you please stop executing this thread for now, and comeback to continue it later?”. You could also interpret this yield operation as: “Could you please deprioritize this thread, to focus on doing other things instead?”. So this yield operation is also a way for you to stop a particular thread, so that you can work and prioritize other threads instead.\nIs important to say that, yielding a thread is a “not so common” thread operation these days. In other words, not many programmers use yielding in production, simply because is hard to use this operation and make it work properly, and also, there are better alternatives. Most programmers prefer to use join() instead. In fact, most of the times, when you see somebody using this “yield” operation in some code example, they are mostly using it to help them debug race conditions in their applications. That is, this “yield” operation is mostly used as a debug tool nowadays.\nAnyway, if you want to yield a thread, just call the yield() method from it, like this:\n\nthread.yield();",
+    "crumbs": [
+      "<span class='chapter-number'>16</span>  <span class='chapter-title'>Introducing threads and parallelism in Zig</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/14-threads.html#common-problems-in-threads",
+    "href": "Chapters/14-threads.html#common-problems-in-threads",
+    "title": "16  Introducing threads and parallelism in Zig",
+    "section": "16.9 Common problems in threads",
+    "text": "16.9 Common problems in threads\n\n16.9.1 Deadlocks\nA deadlock occurs when two or more threads are blocked forever, waiting for each other to release a resource. This usually happens when multiple locks are involved, and the order of acquiring them is not well managed.\nThe code example below demonstrates a deadlock situation. We have two different threads that execute two different functions (work1() and work2()) in this example. And we also have two separate mutexes. If you compile and run this code example, you will notice that the program just runs indefinitely, without ending.\nWhen we look into the first thread, which executes the work1() function, we can notice that this function acquires the mut1 lock first. Because this is the first operation that is executed inside this thread, which is the first thread created in the program. After that, the function sleeps for 1 second, to simulate some type of work, and then, the function tries to acquire the mut2 lock.\nOn the other hand, when we look into the second thread, which executes the work2() function, we can see that this function acquires the mut2 lock first. Because when this thread get’s created and it tries to acquire this mut2 lock, the first thread is still sleeping on that “sleep 1 second” line. After acquiring mut2, the work2() function also sleeps for 1 second, to simulate some type of work, and then, the function tries to acquire the mut1 lock.\nThis creates a deadlock situation, because after the “sleep for 1 second” line in both threads, the thread 1 is trying to acquire the mut2 lock, but this lock is currently being used by thread 2. However, at this moment, the thread 2 is also trying to acquire the mut1 lock, which is currently being used by thread 1. Therefore, both threads end up waiting for ever. Waiting for their peer to free the lock that they want to acquire.\n\nvar mut1: Mutex = .{}; var mut2: Mutex = .{};\nfn work1() !void {\n    mut1.lock();\n    std.time.sleep(1 * std.time.ns_per_s);\n    mut2.lock();\n    _ = try stdout.write(\"Doing some work 1\\n\");\n    mut2.unlock(); mut1.unlock();\n}\n\nfn work2() !void {\n    mut2.lock();\n    std.time.sleep(1 * std.time.ns_per_s);\n    mut1.lock();\n    _ = try stdout.write(\"Doing some work 1\\n\");\n    mut1.unlock(); mut2.unlock();\n}\n\npub fn main() !void {\n    const thr1 = try Thread.spawn(.{}, work1, .{});\n    const thr2 = try Thread.spawn(.{}, work2, .{});\n    thr1.join();\n    thr2.join();\n}\n\n\n\n16.9.2 Not calling join() or detach()\nWhen you do not call either join() or detach() over a thread, then, this thread becomes a “zombie thread”, because it does not have a clear “return point”. You could also interpret this as: “nobody is properly responsible for managing the thread”. When we don’t establish if a thread is either joinable or detached, nobody becomes responsible for dealing with the return value of this thread, and also, nobody becomes responsible for clearing (or freeing) the resources associated with this thread.\nYou don’t want to be in this situation, so remember to always use join() or detach() on the threads that you create. When you don’t use one of these methods, we lose control over the thread, and its resources are never freed (i.e. you have leaked resources in the system).\n\n\n16.9.3 Cancelling or killing a particular thread\nWhen we think about the pthreads C library, there is a possible way to asynchronously kill or cancel a thread, which is by sending a SIGTERM signal to the thread through the pthread_kill() function. But canceling a thread like this is bad. Is dangerously bad. As consequence, the Zig implementation of threads does not have a similar function, or, a similar way to asynchronously cancel or kill a thread.\nTherefore, if you want to cancel a thread in the middle of its execution in Zig, then, one good strategy that you can take is to use control flow in conjunction with join(). More specifically, you can design your thread around a while loop, that is constantly checking if the thread should continue running. If is time to cancel the thread, we could make the while loop break, and join the thread with the main thread by calling join().\nThe code example below demonstrates to some extent this strategy. Here, we are using control flow to break the while loop, and exit the thread earlier than what we have initially planned to. This example also demonstrates how can we use atomic objects in Zig with the Value() generic function that we have mentioned at Section 16.6.2.\n\nconst std = @import(\"std\");\nconst Thread = std.Thread;\nconst stdout = std.io.getStdOut().writer();\nvar running = std.atomic.Value(bool).init(true);\nvar counter: u64 = 0;\nfn do_more_work() void {\n    std.time.sleep(2 * std.time.ns_per_s);\n}\nfn work() !void {\n    while (running.load(.monotonic)) {\n        for (0..10000) |_| { counter += 1; }\n        if (counter &lt; 15000) {\n            _ = try stdout.write(\n                \"Time to cancel the thread.\\n\"\n            );\n            running.store(false, .monotonic);\n        } else {\n            _ = try stdout.write(\"Time to do more work.\\n\");\n            do_more_work();\n            running.store(false, .monotonic);\n        }\n    }\n}\n\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, work, .{});\n    thread.join();\n}\n\nTime to cancel the thread.\n\n\n\n\n\n\nGeeks for Geeks. 2024. “Critical Section.” Geeks for Geeks. https://www.geeksforgeeks.org/g-fact-70/.\n\n\nLinux man-pages. 2024. “Pthread_create(3) — Linux Manual Page.” https://man7.org/linux/man-pages/man3/pthread_create.3.html.",
+    "crumbs": [
+      "<span class='chapter-number'>16</span>  <span class='chapter-title'>Introducing threads and parallelism in Zig</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/14-threads.html#footnotes",
+    "href": "Chapters/14-threads.html#footnotes",
+    "title": "16  Introducing threads and parallelism in Zig",
+    "section": "",
+    "text": "https://github.com/ziglang/zig/issues/18810↩︎\nhttps://www.youtube.com/watch?v=7ENFeb-J75k&ab_channel=Computerphile↩︎",
+    "crumbs": [
+      "<span class='chapter-number'>16</span>  <span class='chapter-title'>Introducing threads and parallelism in Zig</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/15-vectors.html",
+    "href": "Chapters/15-vectors.html",
+    "title": "17  Introducing Vectors and SIMD",
+    "section": "",
+    "text": "17.1 What is SIMD?\nSIMD (Single Instruction/Multiple Data) is a group of operations that are widely used on video/audio editing programs, and also in graphics applications. SIMD is not a new technology, but the massive use of SIMD on normal desktop computers is somewhat recent. In the old days, SIMD was only used on “supercomputer models”.\nMost modern CPU models (from AMD, Intel, etc.) these days (either in a desktop or in a notebook model) have support for SIMD operations. So, if you have a very old CPU model installed in your computer, then, is possible that you have no support for SIMD operations in your computer.\nWhy people have started using SIMD on their software? The answer is performance. But what SIMD precisely do to achieve better performance? Well, in essence, SIMD operations are a different strategy to get parallel computing in your program, and therefore, make faster calculations.\nThe basic idea behind SIMD is to have a single instruction that operates over multiple data at the same time. When you perform a normal scalar operation, like for example, four add instructions, each addition is performed separately, one after another. But with SIMD, these four add instructions are translated into a single instruction, and, as consequence, the four additions are performed in parallel, at the same time.\nCurrently, the zig compiler allows you to apply the following group of operators on vector objects. When you apply one of these operators on vector objects, SIMD is used to make the calculations, and, therefore, these operators are applied element-wise and in parallel by default.",
+    "crumbs": [
+      "<span class='chapter-number'>17</span>  <span class='chapter-title'>Introducing Vectors and SIMD</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/15-vectors.html#what-is-simd",
+    "href": "Chapters/15-vectors.html#what-is-simd",
+    "title": "17  Introducing Vectors and SIMD",
+    "section": "",
+    "text": "Arithmetic (+, -, /, *, @divFloor(), @sqrt(), @ceil(), @log(), etc.).\nBitwise operators (&gt;&gt;, &lt;&lt;, &, |, ~, etc.).\nComparison operators (&lt;, &gt;, ==, etc.).",
+    "crumbs": [
+      "<span class='chapter-number'>17</span>  <span class='chapter-title'>Introducing Vectors and SIMD</span>"
+    ]
+  },
+  {
+    "objectID": "Chapters/15-vectors.html#sec-what-vectors",
+    "href": "Chapters/15-vectors.html#sec-what-vectors",
+    "title": "17  Introducing Vectors and SIMD",
+    "section": "17.2 Vectors",
+    "text": "17.2 Vectors\nA SIMD operation is usually performed through a SIMD intrinsic, which is just a fancy name for a function that performs a SIMD operation. These SIMD intrinsics (or “SIMD functions”) always operate over a special type of object, which are called “vectors”. So, in order to use SIMD, you have to create a “vector object”.\nA vector object is usually a fixed-sized block of 128 bits (16 bytes). As consequence, most vectors that you find in the wild are essentially arrays that contains 2 values of 8 bytes each, or, 4 values of 4 bytes each, or, 8 values of 2 bytes each, etc. However, different CPU models may have different extensions (or, “implementations”) of SIMD, which may offer more types of vector objects that are bigger in size (256 bits or 512 bits) to accomodate more data into a single vector object.\nYou can create a new vector object in Zig by using the @Vector() built-in function. Inside this function, you specify the vector length (number of elements in the vector), and the data type of the elements of the vector. Only primitive data types are supported in these vector objects. In the example below, I’m creating two vector objects (v1 and v2) of 4 elements of type u32 each.\nAlso notice in the example below, that a third vector object (v3) is created from the sum of the previous two vector objects (v1 plus v2). Therefore, math operations over vector objects take place element-wise by default, because the same operation (in this case, addition) is transformed into a single instruction that is replicated in parallel, across all elements of the vectors.\n\nconst v1 = @Vector(4, u32){4, 12, 37, 9};\nconst v2 = @Vector(4, u32){10, 22, 5, 12};\nconst v3 = v1 + v2;\ntry stdout.print(\"{any}\\n\", .{v3});\n\n{ 14, 34, 42, 21 }\n\n\nThis is how SIMD introduces more performance in your program. Instead of using a for loop to iterate through the elements of v1 and v2, and adding them together, one element at a time, we enjoy the benefits of SIMD, which performs all 4 additions in parallel, at the same time.\nTherefore, the @Vector structure is essentially the Zig representation of SIMD vector objects. The elements on these vector objects will be operated in parallel, if, and only if your current CPU model supports SIMD operations. If your CPU model does not have support for SIMD, then, the @Vector structure will likely produce a similar performance from a “for loop solution”.\n\n17.2.1 Transforming arrays into vectors\nThere are different ways to transform a normal array into a vector object. You can either use implicit conversion (which is when you assign the array to a vector object directly), or, use slices to create a vector object from a normal array.\nIn the example below, we are implicitly converting the array a1 into a vector object (v1) of length 4. We first explicitly annotate the data type of the vector object, and then, we assign the array object to this vector object.\nAlso notice in the example below, that a second vector object (v2) is also created by taking a slice of the array object (a1), and then, storing the pointer to this slice (.*) into this vector object.\n\nconst a1 = [4]u32{4, 12, 37, 9};\nconst v1: @Vector(4, u32) = a1;\nconst v2: @Vector(2, u32) = a1[1..3].*;\n_ = v1; _ = v2;\n\nIs worth emphasizing that only arrays and slices whose sizes are compile-time known can be transformed into vectors. Vectors in general are structures that work only with compile-time known sizes. Therefore, if you have an array whose size is runtime known, then, you first need to copy it into an array with a compile-time known size, before transforming it into a vector.\n\n\n17.2.2 The @splat() function\nYou can use the @splat() built-in function to create a vector object that is filled with the same value across all of its elements. This function was created to offer a quick and easy way to directly convert a scalar value (a.k.a. a single value, like a single character, or a single integer, etc.) into a vector object.\nThus, we can use @splat() to convert a single value, like the integer 16 into a vector object of length 1. But we can also use this function to convert the same integer 16 into a vector object of length 10, that is filled with 10 16 values. The example below demonstrates this idea.\n\nconst v1: @Vector(10, u32) = @splat(16);\ntry stdout.print(\"{any}\\n\", .{v1});\n\n{ 16, 16, 16, 16, 16, 16, 16, 16, 16, 16 }\n\n\n\n\n17.2.3 Careful with vectors that are too big\nAs I described at Section 17.2, each vector object is usually a small block of 128, 256 or 512 bits. This means that a vector object is usually small in size, and when you try to go in the opposite direction, by creating a vector object that is very big in size (i.e. sizes that are close to \\(2^{20}\\)), you usually end up with crashes and loud errors from the compiler.\nFor example, if you try to compile the program below, you will likely face segmentation faults, or, LLVM errors during the build process. Just be careful to not create vector objects that are too big in size.\n\nconst v1: @Vector(1000000, u32) = @splat(16);\n_ = v1;\n\nSegmentation fault (core dumped)",
+    "crumbs": [
+      "<span class='chapter-number'>17</span>  <span class='chapter-title'>Introducing Vectors and SIMD</span>"
+    ]
+  },
+  {
+    "objectID": "references.html",
+    "href": "references.html",
+    "title": "References",
+    "section": "",
+    "text": "Chen, Jenny, and Ruohao Guo. 2022. “Stack and Heap Memory.”\nIntroduction to Data Structures and Algorithms with C++. https://courses.engr.illinois.edu/cs225/fa2022/resources/stack-heap/.\n\n\nGeeks for Geeks. 2024a. “Critical Section.” Geeks for\nGeeks. https://www.geeksforgeeks.org/g-fact-70/.\n\n\n———. 2024b. “Generics in c++.” Geeks for\nGeeks. https://www.geeksforgeeks.org/generics-in-c/.\n\n\nKim, Juhee, Jinbum Park, Sihyeon Roh, Jaeyoung Chung, Youngjoo Lee,\nTaesoo Kim, and Byoungyoung Lee. 2024. “TikTag: Breaking ARM’s\nMemory Tagging Extension with Speculative Execution.” https://arxiv.org/abs/2406.08719.\n\n\nLinux man-pages. 2024. “Pthread_create(3) — Linux Manual\nPage.” https://man7.org/linux/man-pages/man3/pthread_create.3.html.\n\n\nMeehan, Eric. 2021. “Creating a Web Server from Scratch in\nc.” Youtube. https://www.youtube.com/watch?v=gk6NL1pZi1M&ab_channel=EricOMeehan.\n\n\nMicrosoft. 2021. “Bitwise AND Operator: &.” Microsoft\nLearn. https://learn.microsoft.com/en-us/cpp/cpp/bitwise-and-operator-amp?view=msvc-170.\n\n\nSeguin, Karl. 2024. “Generics.” https://www.openmymind.net/learning_zig/generics/.\n\n\nSobeston. 2024. “Zig Guide.” https://zig.guide/.\n\n\nWeerasiri, Nipun Chamikara. 2023. “A Simple Web Server Written in\nc.” Medium. https://medium.com/@nipunweerasiri/a-simple-web-server-written-in-c-cf7445002e6.\n\n\nWikipedia. 2024a. “File Descriptor.” Wikipedia. https://en.wikipedia.org/wiki/File_descriptor.\n\n\n———. 2024b. “Grayscale.” Wikipedia. https://en.wikipedia.org/wiki/Grayscale.\n\n\n———. 2024c. “Hash Tables.” Wikipedia. https://en.wikipedia.org/wiki/Hash_table.\n\n\n———. 2024d. “Port (Computer Networking).” Wikipedia. https://en.wikipedia.org/wiki/Port_(computer_networking).\n\n\nYu, Jeffrey. 2023. “How i Built a Simple HTTP Server from Scratch\nUsing c.” DEV Community. https://dev.to/jeffreythecoder/how-i-built-a-simple-http-server-from-scratch-using-c-739.\n\n\nZig Software Foundation. 2024a. “In-Depth Overview.” Zig\nSoftware Foundation. https://ziglang.org/learn/overview/.\n\n\n———. 2024b. “Language Reference.” Zig Software Foundation.\nhttps://ziglang.org/documentation/master/.",
+    "crumbs": [
+      "References"
+    ]
+  }
+]
\ No newline at end of file

From f0078b98a391533a56b76bd591cb8c2c53eb87fc Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sun, 9 Feb 2025 11:24:19 -0300
Subject: [PATCH 063/151] Update contributors list

---
 _freeze/index/execute-results/html.json | 2 +-
 contributors.txt                        | 1 +
 docs/index.html                         | 2 +-
 docs/search.json                        | 2 +-
 4 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/_freeze/index/execute-results/html.json b/_freeze/index/execute-results/html.json
index 2f1af68f..d4a35b63 100644
--- a/_freeze/index/execute-results/html.json
+++ b/_freeze/index/execute-results/html.json
@@ -2,7 +2,7 @@
   "hash": "7eedbe34469c0f2c200651bc420da095",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy an eBook or a physical copy\nof the book on Amazon:\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e. it is open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.\nCurrently, he is a Data Platform Engineer at [Blip](https://www.blip.ai/en/)[^blip], and\na Databricks Certified Associate Developer for Apache Spark 3.0.\n\n[^blip]: <https://www.blip.ai/en/>\n\n\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nBrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer who loves to learn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2024 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n\n- System version: Linux, 6.8.0-52-generic, NA, x86_64.\n- Zig version: 0.14.0-dev.3046+08d661fcf.\n- Quarto version: 1.5.57.\n\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang), Tommaso Ricci (\\@Zorgatone), Primo Sabatini (\\@primos63), Santiago Fernandez (\\@santif), Hamza Wahed (\\@HamzaWahed), mwilbur (\\@mwilbur), Dima Budaragin (\\@dbud), Jorge Jímenez (\\@jorge-j1m)\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy an eBook or a physical copy\nof the book on Amazon:\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e. it is open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.\nCurrently, he is a Data Platform Engineer at [Blip](https://www.blip.ai/en/)[^blip], and\na Databricks Certified Associate Developer for Apache Spark 3.0.\n\n[^blip]: <https://www.blip.ai/en/>\n\n\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nBrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer who loves to learn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2024 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n\n- System version: Linux, 6.8.0-52-generic, NA, x86_64.\n- Zig version: 0.14.0-dev.3046+08d661fcf.\n- Quarto version: 1.5.57.\n\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang), Tommaso Ricci (\\@Zorgatone), Primo Sabatini (\\@primos63), Santiago Fernandez (\\@santif), Hamza Wahed (\\@HamzaWahed), mwilbur (\\@mwilbur), Dima Budaragin (\\@dbud), Jorge Jímenez (\\@jorge-j1m), Alexander (\\@alexwheezy)\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
diff --git a/contributors.txt b/contributors.txt
index 1c2abddf..80300af6 100644
--- a/contributors.txt
+++ b/contributors.txt
@@ -19,3 +19,4 @@ Hamza Wahed,@HamzaWahed
 mwilbur,@mwilbur
 Dima Budaragin,@dbud
 Jorge Jímenez,@jorge-j1m
+Alexander,@alexwheezy
diff --git a/docs/index.html b/docs/index.html
index de82ec20..f53295df 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -439,7 +439,7 @@ <h2 class="unnumbered anchored" data-anchor-id="corresponding-author-and-maintai
 <section id="acknowledgments" class="level2 unnumbered">
 <h2 class="unnumbered anchored" data-anchor-id="acknowledgments">Acknowledgments</h2>
 <p>This book is also a product of many conversations and exchanges that we had with different people from the Zig community. I (Pedro Duarte Faria) am incredibly grateful for these conversations, and also, for some direct contributions that we had. Below we have a list of the people involved (name of the person with their usename in GitHub):</p>
-<p>Calin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang), Tommaso Ricci (@Zorgatone), Primo Sabatini (@primos63), Santiago Fernandez (@santif), Hamza Wahed (@HamzaWahed), mwilbur (@mwilbur), Dima Budaragin (@dbud), Jorge Jímenez (@jorge-j1m)</p>
+<p>Calin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang), Tommaso Ricci (@Zorgatone), Primo Sabatini (@primos63), Santiago Fernandez (@santif), Hamza Wahed (@HamzaWahed), mwilbur (@mwilbur), Dima Budaragin (@dbud), Jorge Jímenez (@jorge-j1m), Alexander (@alexwheezy)</p>
 
 
 </section>
diff --git a/docs/search.json b/docs/search.json
index 3c57d704..1999409e 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -84,7 +84,7 @@
     "href": "index.html#acknowledgments",
     "title": "Introduction to Zig",
     "section": "Acknowledgments",
-    "text": "Acknowledgments\nThis book is also a product of many conversations and exchanges that we had with different people from the Zig community. I (Pedro Duarte Faria) am incredibly grateful for these conversations, and also, for some direct contributions that we had. Below we have a list of the people involved (name of the person with their usename in GitHub):\nCalin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang), Tommaso Ricci (@Zorgatone), Primo Sabatini (@primos63), Santiago Fernandez (@santif), Hamza Wahed (@HamzaWahed), mwilbur (@mwilbur), Dima Budaragin (@dbud), Jorge Jímenez (@jorge-j1m)",
+    "text": "Acknowledgments\nThis book is also a product of many conversations and exchanges that we had with different people from the Zig community. I (Pedro Duarte Faria) am incredibly grateful for these conversations, and also, for some direct contributions that we had. Below we have a list of the people involved (name of the person with their usename in GitHub):\nCalin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang), Tommaso Ricci (@Zorgatone), Primo Sabatini (@primos63), Santiago Fernandez (@santif), Hamza Wahed (@HamzaWahed), mwilbur (@mwilbur), Dima Budaragin (@dbud), Jorge Jímenez (@jorge-j1m), Alexander (@alexwheezy)",
     "crumbs": [
       "Welcome"
     ]

From 9ea48cdba5768a585cf83adf2fdad249fdaa2a92 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sun, 9 Feb 2025 12:05:24 -0300
Subject: [PATCH 064/151] Fix code example

---
 Chapters/05-pointers.qmd                          | 15 +++++++++------
 .../05-pointers/execute-results/html.json         |  8 +++-----
 docs/Chapters/05-pointers.html                    | 10 +++++-----
 docs/search.json                                  |  2 +-
 4 files changed, 18 insertions(+), 17 deletions(-)

diff --git a/Chapters/05-pointers.qmd b/Chapters/05-pointers.qmd
index 5658c4fc..3e2d8dc1 100644
--- a/Chapters/05-pointers.qmd
+++ b/Chapters/05-pointers.qmd
@@ -249,14 +249,17 @@ to the first element in the array `ar`. But then, I started to walk through the
 the pointer with simple pointer arithmetic.
 
 ```{zig}
-#| eval: false
-const ar = [_]i32{1,2,3,4};
-var ptr = &ar;
-try stdout.print("{d}\n", .{ptr.*});
+#| eval: true
+#| auto_main: true
+#| build_type: "run"
+#| results: "hide"
+const ar = [_]i32{ 1, 2, 3, 4 };
+var ptr: [*]const i32 = &ar;
+try stdout.print("{d}\n", .{ptr[0]});
 ptr += 1;
-try stdout.print("{d}\n", .{ptr.*});
+try stdout.print("{d}\n", .{ptr[0]});
 ptr += 1;
-try stdout.print("{d}\n", .{ptr.*});
+try stdout.print("{d}\n", .{ptr[0]});
 ```
 
 ```
diff --git a/_freeze/Chapters/05-pointers/execute-results/html.json b/_freeze/Chapters/05-pointers/execute-results/html.json
index 0cdd4021..bce4789c 100644
--- a/_freeze/Chapters/05-pointers/execute-results/html.json
+++ b/_freeze/Chapters/05-pointers/execute-results/html.json
@@ -1,11 +1,9 @@
 {
-  "hash": "9520ae65eeada418ccd4d4ca5f8b6f7a",
+  "hash": "8fdb1694a88afd9b81c337b29ec84c86",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Pointers and Optionals {#sec-pointer}\n\nOn our next project we are going to build a HTTP server from scratch.\nBut in order to do that, we need to learn more about pointers and how they work in Zig.\nPointers in Zig are similar to pointers in C. But they come with some extra advantages in Zig.\n\nA pointer is an object that contains a memory address. This memory address is the address where\na particular value is stored in memory. It can be any value. Most of the times,\nit is a value that comes from another object (or variable) present in our code.\n\nIn the example below, I'm creating two objects (`number` and `pointer`).\nThe `pointer` object contains the memory address where the value of the `number` object\n(the number 5) is stored. So, that is a pointer in a nutshell. It is a memory\naddress that points to a particular existing value in the memory. You could\nalso say, that, the `pointer` object points to the memory address where the `number` object is\nstored.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number: u8 = 5;\nconst pointer = &number;\n_ = pointer;\n```\n:::\n\n\n\n\nWe create a pointer object in Zig by using the `&` operator. When you put this operator\nbefore the name of an existing object, you get the memory address of this object as result.\nWhen you store this memory address inside a new object, this new object becomes a pointer object.\nBecause it stores a memory address.\n\nPeople mostly use pointers as an alternative way to access a particular value.\nFor example, I can use the `pointer` object to access the value stored by\nthe `number` object. This operation of accessing the value that the\npointer \"points to\" is normally called of *dereferencing the pointer*.\nWe can dereference a pointer in Zig by using the `*` method of the pointer object. Like in the example\nbelow, where we take the number 5 pointed by the `pointer` object,\nand double it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number: u8 = 5;\nconst pointer = &number;\nconst doubled = 2 * pointer.*;\nstd.debug.print(\"{d}\\n\", .{doubled});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n10\n```\n\n\n:::\n:::\n\n\n\n\n\nThis syntax to dereference the pointer is nice. Because we can easily chain it with\nmethods of the value pointed by the pointer. We can use the `User` struct that we have\ncreated at @sec-structs-and-oop as an example. If you comeback to that section,\nyou will see that this struct have a method named `print_name()`.\n\nSo, for example, if we have an user object, and a pointer that points to this user object,\nwe can use the pointer to access this user object, and, at the same time, call the method `print_name()`\non it, by chaining the dereference method (`*`) with the `print_name()` method. Like in the\nexample below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst u = User.init(1, \"pedro\", \"email@gmail.com\");\nconst pointer = &u;\ntry pointer.*.print_name();\n```\n:::\n\n\n\n\n```\npedro\n```\n\nWe can also use pointers to effectively alter the value of an object.\nFor example, I could use the `pointer` object to set\nthe value of the object `number` to 6, like in the example below.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n6\n```\n\n\n:::\n:::\n\n\n\n\n\nTherefore, as I mentioned earlier, people use pointers as an alternative way to access a particular value.\nAnd they use it especially when they do not want to \"move\" these values around. There are situations where,\nyou want to access a particular value in a different scope (i.e. a different location) of your code,\nbut you do not want to \"move\" this value to this new scope (or location) that you are in.\n\nThis matters especially if this value is big in size. Because if it is, then,\nmoving this value becomes an expensive operation to do.\nThe computer will have to spend a considerable amount of time\ncopying this value to this new location.\n\nTherefore, many programmers prefer to avoid this heavy operation of copying the value\nto the new location, by accessing this value through pointers.\nWe are going to talk more about this \"moving operation\" over the next sections.\nFor now, just keep in mind that avoiding this \"move operation\" is\none of main reasons why pointers are used in programming languages.\n\n\n\n\n\n## Constant objects vs variable objects {#sec-pointer-var}\n\nYou can have a pointer that points to a constant object, or, a pointer that points to a variable object.\nBut regardless of who this pointer is, a pointer **must always respect the characteristics of the object that it points to**.\nAs a consequence, if the pointer points to a constant object, then, you cannot use this pointer\nto change the value that it points to. Because it points to a value that is constant. As we discussed at @sec-assignments, you cannot\nchange a value that is constant.\n\nFor example, if I have a `number` object, which is constant, I cannot execute\nthe expression below where I'm trying to change the value of `number` to 6 through\nthe `pointer` object. As demonstrated below, when you try to do something\nlike that, you get a compile time error:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number = 5;\nconst pointer = &number;\npointer.* = 6;\n```\n:::\n\n\n\n\n```\np.zig:6:12: error: cannot assign to constant\n    pointer.* = 6;\n```\n\nIf I change the `number` object to be a variable object, by introducing the `var` keyword,\nthen, I can successfully change the value of this object through a pointer, as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n6\n```\n\n\n:::\n:::\n\n\n\n\nYou can see this relationship between \"constant versus variable\" on the data type of\nyour pointer object. In other words, the data type of a pointer object already gives you\nsome clues about whether the value that it points to is constant or not.\n\nWhen a pointer object points to a constant value, then, this pointer have a data type `*const T`,\nwhich means \"a pointer to a constant value of type `T`\".\nIn contrast, if the pointer points to a variable value, then, the type of the pointer is usually `*T`, which is\nsimply \"a pointer to a value of type `T`\".\nHence, whenever you see a pointer object whose data type is in the format `*const T`, then,\nyou know that you cannot use this pointer to change the value that it points to.\nBecause this pointer points to a constant value of type `T`.\n\n\nWe have talked about the value pointed by the pointer being constant or not,\nand the consequences that arises from it. But, what about the pointer object itself? I mean, what happens\nif the pointer object itself is constant or not? Think about it.\nWe can have a constant pointer that points to a constant value.\nBut we can also have a variable pointer that points to a constant value. And vice-versa.\n\nUntil this point, the `pointer` object was always constant,\nbut what this means for us? What is the consequence of the\n`pointer` object being constant? The consequence is that\nwe cannot change the pointer object, because it is constant. We can use the\npointer object in multiple ways, but we cannot change the\nmemory address that is inside this pointer object.\n\nHowever, if we mark the `pointer` object as a variable object,\nthen, we can change the memory address pointed by this `pointer` object.\nThe example below demonstrates that. Notice that the object pointed\nby the `pointer` object changes from `c1` to `c2`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c1: u8 = 5;\nconst c2: u8 = 6;\nvar pointer = &c1;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\npointer = &c2;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\n```\n:::\n\n\n\n\n```\n5\n6\n```\n\nThus, by setting the `pointer` object to a `var` or `const` object,\nyou specify if the memory address contained in this pointer object can change or not\nin your program. On the other side, you can change the value pointed by the pointer,\nif, and only if this value is stored in a variable object. If this value\nis in a constant object, then, you cannot change this value through a pointer.\n\n\n## Types of pointer\n\nIn Zig, there are two types of pointers [@zigdocs], which are:\n\n- single-item pointer (`*`);\n- many-item pointer (`[*]`);\n\n\nSingle-item pointer objects are objects whose data types are in the format `*T`.\nSo, for example, if an object have a data type `*u32`, it means that, this\nobject contains a single-item pointer that points to an unsigned 32-bit integer value.\nAs another example, if an object have type `*User`, then, it contains\na single-item pointer to an `User` value.\n\nIn contrast, many-item pointers are objects whose data types are in the format `[*]T`.\nNotice that the star symbol (`*`) is now inside a pair of brackets (`[]`). If the star\nsymbol is inside a pair of brackets, you know that this object is a many-item pointer.\n\nWhen you apply the `&` operator over an object, you will always get a single-item pointer.\nMany-item pointers are more of a \"internal type\" of the language, more closely\nrelated to slices. So, when you deliberately create a pointer with the `&` operator,\nyou always get a single-item pointer as result.\n\n\n\n## Pointer arithmetic\n\nPointer arithmetic is available in Zig, and they work the same way they work in C.\nWhen you have a pointer that points to an array, the pointer usually points to\nthe first element in the array, and you can use pointer arithmetic to\nadvance this pointer and access the other elements in the array.\n\n\nNotice in the example below, that initially, the `ptr` object was pointing\nto the first element in the array `ar`. But then, I started to walk through the array, by advancing\nthe pointer with simple pointer arithmetic.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [_]i32{1,2,3,4};\nvar ptr = &ar;\ntry stdout.print(\"{d}\\n\", .{ptr.*});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr.*});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr.*});\n```\n:::\n\n\n\n\n```\n1\n2\n3\n```\n\nAlthough you can create a pointer to an array like that, and\nstart to walk through this array by using pointer arithmetic,\nin Zig, we prefer to use slices, which were presented at @sec-arrays.\n\nBehind the hood, slices already are pointers,\nand they also come with the `len` property, which indicates\nhow many elements are in the slice. This is good because the `zig` compiler\ncan use it to check for potential buffer overflows, and other problems like that.\n\nAlso, you don't need to use pointer arithmetic to walk through the elements\nof a slice. You can simply use the `slice[index]` syntax to directly access\nany element you want in the slice.\nAs I mentioned at @sec-arrays, you can get a slice from an array by using\na range selector inside brackets. In the example below, I'm creating\na slice (`sl`) that covers the entire `ar` array. I can access any\nelement of `ar` from this slice, and, the slice itself already is a pointer\nbehind the hood.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [_]i32{1,2,3,4};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\n\n## Optionals and Optional Pointers\n\nLet's talk about optionals and how they relate to pointers in Zig.\nBy default, objects in Zig are **non-nullable**. This means that, in Zig,\nyou can safely assume that any object in your source code is not null.\n\nThis is a powerful feature of Zig when you compare it to the developer experience in C.\nBecause in C, any object can be null at any point, and, as consequence, a pointer in C\nmight point to a null value. This is a common source of undefined behaviour in C.\nWhen programmers work with pointers in C, they have to constantly check if\ntheir pointers are pointing to null values or not.\n\nIf for some reason, your Zig code produces a null value somewhere, and, this null\nvalue ends up in an object that is non-nullable, a runtime error is always\nraised by your Zig program. Take the program below as an example.\nThe `zig` compiler can see the `null` value at compile time, and, as result,\nit raises a compile time error. But, if a `null` value is raised during\nruntime, a runtime error is also raised by the Zig program, with a\n\"attempt to use null value\" message.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nnumber = null;\n```\n:::\n\n\n\n```\np5.zig:5:14: error: expected type 'u8',\n        found '@TypeOf(null)'\n    number = null;\n             ^~~~\n```\n\n\nYou don't get this type of safety in C.\nIn C, you don't get warnings or errors about null values being produced in your program.\nIf for some reason, your code produces a null value in C, most of the times, you end up getting a segmentation fault error\nas result, which can mean many things.\nThat is why programmers have to constantly check for null values in C.\n\nPointers in Zig are also, by default, **non-nullable**. This is another amazing\nfeature in Zig. So, you can safely assume that any pointer that you create in\nyour Zig code is pointing to a non-null value.\nTherefore, you don't have this heavy work of checking if the pointers you create\nin Zig are pointing to a null value.\n\n\n### What are optionals?\n\nOk, we know now that all objects are non-nullable by default in Zig.\nBut what if we actually need to use an object that might receive a null value?\nHere is where optionals come in.\n\nAn optional object in Zig is an object that can be null.\nTo mark an object as optional, we use the `?` operator. When you put\nthis `?` operator right before the data type of an object, you transform\nthis data type into an optional data type, and the object becomes an optional object.\n\nTake the snippet below as an example. We are creating a new variable object\ncalled `num`. This object have the data type `?i32`, which means that,\nthis object contains either a signed 32-bit integer (`i32`), or, a null value.\nBoth alternatives are valid values to the `num` object.\nThat is why, I can actually change the value of this object to null, and,\nno errors are raised by the `zig` compiler, as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: ?i32 = 5;\nnum = null;\n```\n:::\n\n\n\n\n### Optional pointers\n\nYou can also mark a pointer object as an optional pointer, meaning that,\nthis object contains either a null value, or, a pointer that points to a value.\nWhen you mark a pointer as optional, the data type of this pointer object\nbecomes `?*const T` or `?*T`, depending if the value pointed by the pointer\nis a constant value or not. The `?` identifies the object as optional, while\nthe `*` identifies it as a pointer object.\n\nIn the example below, we are creating a variable object named `num`, and an\noptional pointer object named `ptr`. Notice that the data type of the object\n`ptr` indicates that it is either a null value, or a pointer to an `i32` value.\nAlso, notice that the pointer object (`ptr`) can be marked as optional, even if\nthe object `num` is not optional.\n\nWhat this code tells us is that, the `num` variable will never contain a null value.\nThis variable will always contain a valid `i32` value. But in contrast, the `ptr` object might contain either a null\nvalue, or, a pointer to an `i32` value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: i32 = 5;\nvar ptr: ?*i32 = &num;\nptr = null;\nnum = 6;\n```\n:::\n\n\n\n\nBut what happens if we turn the table, and mark the `num` object as optional,\ninstead of the pointer object. If we do that, then, the pointer object is\nnot optional anymore. It would be a similar (although different) result. Because then, we would have\na pointer to an optional value. In other words, a pointer to a value that is either a\nnull value, or, a not-null value.\n\nIn the example below, we are recreating this idea. Now, the `ptr` object\nhave a data type of `*?i32`, instead of `?*i32`. Notice that the `*` symbol comes before of `?`\nthis time. So now, we have a pointer that points to a value that is either null\n, or, a signed 32-bit integer.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: ?i32 = 5;\n// ptr have type `*?i32`, instead of `?*i32`.\nconst ptr = &num;\n_ = ptr;\n```\n:::\n\n\n\n\n\n### Null handling in optionals {#sec-null-handling}\n\nWhen you have an optional object in your Zig code, you have to explicitly handle\nthe possibility of this object being null. It is like error-handling with `try` and `catch`.\nIn Zig you also have to handle null values like if they were a type of error.\n\nWe can do that, by using either:\n\n- an if statement, like you would do in C.\n- the `orelse` keyword.\n- unwrap the optional value with the `?` method.\n\nWhen you use an if statement, you use a pair of pipes\nto unwrap the optional value, and use this \"unwrapped object\"\ninside the if block.\nUsing the example below as a reference, if the object `num` is null,\nthen, the code inside the if statement is not executed. Otherwise,\nthe if statement will unwrap the object `num` into the `not_null_num`\nobject. This `not_null_num` object is guaranteed to be not null inside\nthe scope of the if statement.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst num: ?i32 = 5;\nif (num) |not_null_num| {\n    try stdout.print(\"{d}\\n\", .{not_null_num});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n5\n```\n\n\n:::\n:::\n\n\n\n\nNow, the `orelse` keyword behaves like a binary operator. You connect two expressions with this keyword.\nOn the left side of `orelse`, you provide the expression that might result\nin a null value, and on the right side of `orelse`, you provide another expression\nthat will not result in a null value.\n\nThe idea behind the `orelse` keyword is: if the expression on the left side\nresult in a not-null value, then, this not-null value is used. However,\nif this expression on the left side result in a null value, then, the value\nof the expression on the right side is used instead.\n\nLooking at the example below, since the `x` object is currently null, the\n`orelse` decided to use the alternative value, which is the number 15.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x: ?i32 = null;\nconst dbl = (x orelse 15) * 2;\ntry stdout.print(\"{d}\\n\", .{dbl});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n30\n```\n\n\n:::\n:::\n\n\n\n\nYou can use the if statement or the `orelse` keyword, when you want to\nsolve (or deal with) this null value. However, if there is no clear solution\nto this null value, and the most logic and sane path is to simply panic\nand raise a loud error in your program when this null value is encountered,\nyou can use the `?` method of your optional object.\n\nIn essence, when you use this `?` method, the optional object is unwrapped.\nIf a not-null value is found in the optional object, then, this not-null value is used.\nOtherwise, the `unreachable` keyword is used. You can read more about this\n[`unreacheable` keyword at the official documentation](https://ziglang.org/documentation/master/#unreachable)[^un-docs].\nBut in essence, when you build your Zig source code using the build modes `ReleaseSafe` or `Debug`, this\n`unreacheable` keyword causes the program to panic and raise an error during runtime,\nlike in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn return_null(n: i32) ?i32 {\n    if (n == 5) return null;\n    return n;\n}\n\npub fn main() !void {\n    const x: i32 = 5;\n    const y: ?i32 = return_null(x);\n    try stdout.print(\"{d}\\n\", .{y.?});\n}\n```\n:::\n\n\n\n\n```\nthread 12767 panic: attempt to use null value\np7.zig:12:34: 0x103419d in main (p7):\n    try stdout.print(\"{d}\\n\", .{y.?});\n                                 ^\n```\n\n\n[^un-docs]: <https://ziglang.org/documentation/master/#unreachable>.\n\n\n",
-    "supporting": [
-      "05-pointers_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Pointers and Optionals {#sec-pointer}\n\nOn our next project we are going to build a HTTP server from scratch.\nBut in order to do that, we need to learn more about pointers and how they work in Zig.\nPointers in Zig are similar to pointers in C. But they come with some extra advantages in Zig.\n\nA pointer is an object that contains a memory address. This memory address is the address where\na particular value is stored in memory. It can be any value. Most of the times,\nit is a value that comes from another object (or variable) present in our code.\n\nIn the example below, I'm creating two objects (`number` and `pointer`).\nThe `pointer` object contains the memory address where the value of the `number` object\n(the number 5) is stored. So, that is a pointer in a nutshell. It is a memory\naddress that points to a particular existing value in the memory. You could\nalso say, that, the `pointer` object points to the memory address where the `number` object is\nstored.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number: u8 = 5;\nconst pointer = &number;\n_ = pointer;\n```\n:::\n\n\n\n\n\nWe create a pointer object in Zig by using the `&` operator. When you put this operator\nbefore the name of an existing object, you get the memory address of this object as result.\nWhen you store this memory address inside a new object, this new object becomes a pointer object.\nBecause it stores a memory address.\n\nPeople mostly use pointers as an alternative way to access a particular value.\nFor example, I can use the `pointer` object to access the value stored by\nthe `number` object. This operation of accessing the value that the\npointer \"points to\" is normally called of *dereferencing the pointer*.\nWe can dereference a pointer in Zig by using the `*` method of the pointer object. Like in the example\nbelow, where we take the number 5 pointed by the `pointer` object,\nand double it.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number: u8 = 5;\nconst pointer = &number;\nconst doubled = 2 * pointer.*;\nstd.debug.print(\"{d}\\n\", .{doubled});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n10\n```\n\n\n:::\n:::\n\n\n\n\n\n\nThis syntax to dereference the pointer is nice. Because we can easily chain it with\nmethods of the value pointed by the pointer. We can use the `User` struct that we have\ncreated at @sec-structs-and-oop as an example. If you comeback to that section,\nyou will see that this struct have a method named `print_name()`.\n\nSo, for example, if we have an user object, and a pointer that points to this user object,\nwe can use the pointer to access this user object, and, at the same time, call the method `print_name()`\non it, by chaining the dereference method (`*`) with the `print_name()` method. Like in the\nexample below:\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst u = User.init(1, \"pedro\", \"email@gmail.com\");\nconst pointer = &u;\ntry pointer.*.print_name();\n```\n:::\n\n\n\n\n\n```\npedro\n```\n\nWe can also use pointers to effectively alter the value of an object.\nFor example, I could use the `pointer` object to set\nthe value of the object `number` to 6, like in the example below.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n6\n```\n\n\n:::\n:::\n\n\n\n\n\n\nTherefore, as I mentioned earlier, people use pointers as an alternative way to access a particular value.\nAnd they use it especially when they do not want to \"move\" these values around. There are situations where,\nyou want to access a particular value in a different scope (i.e. a different location) of your code,\nbut you do not want to \"move\" this value to this new scope (or location) that you are in.\n\nThis matters especially if this value is big in size. Because if it is, then,\nmoving this value becomes an expensive operation to do.\nThe computer will have to spend a considerable amount of time\ncopying this value to this new location.\n\nTherefore, many programmers prefer to avoid this heavy operation of copying the value\nto the new location, by accessing this value through pointers.\nWe are going to talk more about this \"moving operation\" over the next sections.\nFor now, just keep in mind that avoiding this \"move operation\" is\none of main reasons why pointers are used in programming languages.\n\n\n\n\n\n## Constant objects vs variable objects {#sec-pointer-var}\n\nYou can have a pointer that points to a constant object, or, a pointer that points to a variable object.\nBut regardless of who this pointer is, a pointer **must always respect the characteristics of the object that it points to**.\nAs a consequence, if the pointer points to a constant object, then, you cannot use this pointer\nto change the value that it points to. Because it points to a value that is constant. As we discussed at @sec-assignments, you cannot\nchange a value that is constant.\n\nFor example, if I have a `number` object, which is constant, I cannot execute\nthe expression below where I'm trying to change the value of `number` to 6 through\nthe `pointer` object. As demonstrated below, when you try to do something\nlike that, you get a compile time error:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number = 5;\nconst pointer = &number;\npointer.* = 6;\n```\n:::\n\n\n\n\n\n```\np.zig:6:12: error: cannot assign to constant\n    pointer.* = 6;\n```\n\nIf I change the `number` object to be a variable object, by introducing the `var` keyword,\nthen, I can successfully change the value of this object through a pointer, as demonstrated below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n6\n```\n\n\n:::\n:::\n\n\n\n\n\nYou can see this relationship between \"constant versus variable\" on the data type of\nyour pointer object. In other words, the data type of a pointer object already gives you\nsome clues about whether the value that it points to is constant or not.\n\nWhen a pointer object points to a constant value, then, this pointer have a data type `*const T`,\nwhich means \"a pointer to a constant value of type `T`\".\nIn contrast, if the pointer points to a variable value, then, the type of the pointer is usually `*T`, which is\nsimply \"a pointer to a value of type `T`\".\nHence, whenever you see a pointer object whose data type is in the format `*const T`, then,\nyou know that you cannot use this pointer to change the value that it points to.\nBecause this pointer points to a constant value of type `T`.\n\n\nWe have talked about the value pointed by the pointer being constant or not,\nand the consequences that arises from it. But, what about the pointer object itself? I mean, what happens\nif the pointer object itself is constant or not? Think about it.\nWe can have a constant pointer that points to a constant value.\nBut we can also have a variable pointer that points to a constant value. And vice-versa.\n\nUntil this point, the `pointer` object was always constant,\nbut what this means for us? What is the consequence of the\n`pointer` object being constant? The consequence is that\nwe cannot change the pointer object, because it is constant. We can use the\npointer object in multiple ways, but we cannot change the\nmemory address that is inside this pointer object.\n\nHowever, if we mark the `pointer` object as a variable object,\nthen, we can change the memory address pointed by this `pointer` object.\nThe example below demonstrates that. Notice that the object pointed\nby the `pointer` object changes from `c1` to `c2`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c1: u8 = 5;\nconst c2: u8 = 6;\nvar pointer = &c1;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\npointer = &c2;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\n```\n:::\n\n\n\n\n\n```\n5\n6\n```\n\nThus, by setting the `pointer` object to a `var` or `const` object,\nyou specify if the memory address contained in this pointer object can change or not\nin your program. On the other side, you can change the value pointed by the pointer,\nif, and only if this value is stored in a variable object. If this value\nis in a constant object, then, you cannot change this value through a pointer.\n\n\n## Types of pointer\n\nIn Zig, there are two types of pointers [@zigdocs], which are:\n\n- single-item pointer (`*`);\n- many-item pointer (`[*]`);\n\n\nSingle-item pointer objects are objects whose data types are in the format `*T`.\nSo, for example, if an object have a data type `*u32`, it means that, this\nobject contains a single-item pointer that points to an unsigned 32-bit integer value.\nAs another example, if an object have type `*User`, then, it contains\na single-item pointer to an `User` value.\n\nIn contrast, many-item pointers are objects whose data types are in the format `[*]T`.\nNotice that the star symbol (`*`) is now inside a pair of brackets (`[]`). If the star\nsymbol is inside a pair of brackets, you know that this object is a many-item pointer.\n\nWhen you apply the `&` operator over an object, you will always get a single-item pointer.\nMany-item pointers are more of a \"internal type\" of the language, more closely\nrelated to slices. So, when you deliberately create a pointer with the `&` operator,\nyou always get a single-item pointer as result.\n\n\n\n## Pointer arithmetic\n\nPointer arithmetic is available in Zig, and they work the same way they work in C.\nWhen you have a pointer that points to an array, the pointer usually points to\nthe first element in the array, and you can use pointer arithmetic to\nadvance this pointer and access the other elements in the array.\n\n\nNotice in the example below, that initially, the `ptr` object was pointing\nto the first element in the array `ar`. But then, I started to walk through the array, by advancing\nthe pointer with simple pointer arithmetic.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [_]i32{ 1, 2, 3, 4 };\nvar ptr: [*]const i32 = &ar;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\n```\n:::\n\n\n\n\n\n```\n1\n2\n3\n```\n\nAlthough you can create a pointer to an array like that, and\nstart to walk through this array by using pointer arithmetic,\nin Zig, we prefer to use slices, which were presented at @sec-arrays.\n\nBehind the hood, slices already are pointers,\nand they also come with the `len` property, which indicates\nhow many elements are in the slice. This is good because the `zig` compiler\ncan use it to check for potential buffer overflows, and other problems like that.\n\nAlso, you don't need to use pointer arithmetic to walk through the elements\nof a slice. You can simply use the `slice[index]` syntax to directly access\nany element you want in the slice.\nAs I mentioned at @sec-arrays, you can get a slice from an array by using\na range selector inside brackets. In the example below, I'm creating\na slice (`sl`) that covers the entire `ar` array. I can access any\nelement of `ar` from this slice, and, the slice itself already is a pointer\nbehind the hood.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [_]i32{1,2,3,4};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\n\n\n## Optionals and Optional Pointers\n\nLet's talk about optionals and how they relate to pointers in Zig.\nBy default, objects in Zig are **non-nullable**. This means that, in Zig,\nyou can safely assume that any object in your source code is not null.\n\nThis is a powerful feature of Zig when you compare it to the developer experience in C.\nBecause in C, any object can be null at any point, and, as consequence, a pointer in C\nmight point to a null value. This is a common source of undefined behaviour in C.\nWhen programmers work with pointers in C, they have to constantly check if\ntheir pointers are pointing to null values or not.\n\nIf for some reason, your Zig code produces a null value somewhere, and, this null\nvalue ends up in an object that is non-nullable, a runtime error is always\nraised by your Zig program. Take the program below as an example.\nThe `zig` compiler can see the `null` value at compile time, and, as result,\nit raises a compile time error. But, if a `null` value is raised during\nruntime, a runtime error is also raised by the Zig program, with a\n\"attempt to use null value\" message.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nnumber = null;\n```\n:::\n\n\n\n\n```\np5.zig:5:14: error: expected type 'u8',\n        found '@TypeOf(null)'\n    number = null;\n             ^~~~\n```\n\n\nYou don't get this type of safety in C.\nIn C, you don't get warnings or errors about null values being produced in your program.\nIf for some reason, your code produces a null value in C, most of the times, you end up getting a segmentation fault error\nas result, which can mean many things.\nThat is why programmers have to constantly check for null values in C.\n\nPointers in Zig are also, by default, **non-nullable**. This is another amazing\nfeature in Zig. So, you can safely assume that any pointer that you create in\nyour Zig code is pointing to a non-null value.\nTherefore, you don't have this heavy work of checking if the pointers you create\nin Zig are pointing to a null value.\n\n\n### What are optionals?\n\nOk, we know now that all objects are non-nullable by default in Zig.\nBut what if we actually need to use an object that might receive a null value?\nHere is where optionals come in.\n\nAn optional object in Zig is an object that can be null.\nTo mark an object as optional, we use the `?` operator. When you put\nthis `?` operator right before the data type of an object, you transform\nthis data type into an optional data type, and the object becomes an optional object.\n\nTake the snippet below as an example. We are creating a new variable object\ncalled `num`. This object have the data type `?i32`, which means that,\nthis object contains either a signed 32-bit integer (`i32`), or, a null value.\nBoth alternatives are valid values to the `num` object.\nThat is why, I can actually change the value of this object to null, and,\nno errors are raised by the `zig` compiler, as demonstrated below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: ?i32 = 5;\nnum = null;\n```\n:::\n\n\n\n\n\n### Optional pointers\n\nYou can also mark a pointer object as an optional pointer, meaning that,\nthis object contains either a null value, or, a pointer that points to a value.\nWhen you mark a pointer as optional, the data type of this pointer object\nbecomes `?*const T` or `?*T`, depending if the value pointed by the pointer\nis a constant value or not. The `?` identifies the object as optional, while\nthe `*` identifies it as a pointer object.\n\nIn the example below, we are creating a variable object named `num`, and an\noptional pointer object named `ptr`. Notice that the data type of the object\n`ptr` indicates that it is either a null value, or a pointer to an `i32` value.\nAlso, notice that the pointer object (`ptr`) can be marked as optional, even if\nthe object `num` is not optional.\n\nWhat this code tells us is that, the `num` variable will never contain a null value.\nThis variable will always contain a valid `i32` value. But in contrast, the `ptr` object might contain either a null\nvalue, or, a pointer to an `i32` value.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: i32 = 5;\nvar ptr: ?*i32 = &num;\nptr = null;\nnum = 6;\n```\n:::\n\n\n\n\n\nBut what happens if we turn the table, and mark the `num` object as optional,\ninstead of the pointer object. If we do that, then, the pointer object is\nnot optional anymore. It would be a similar (although different) result. Because then, we would have\na pointer to an optional value. In other words, a pointer to a value that is either a\nnull value, or, a not-null value.\n\nIn the example below, we are recreating this idea. Now, the `ptr` object\nhave a data type of `*?i32`, instead of `?*i32`. Notice that the `*` symbol comes before of `?`\nthis time. So now, we have a pointer that points to a value that is either null\n, or, a signed 32-bit integer.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: ?i32 = 5;\n// ptr have type `*?i32`, instead of `?*i32`.\nconst ptr = &num;\n_ = ptr;\n```\n:::\n\n\n\n\n\n\n### Null handling in optionals {#sec-null-handling}\n\nWhen you have an optional object in your Zig code, you have to explicitly handle\nthe possibility of this object being null. It is like error-handling with `try` and `catch`.\nIn Zig you also have to handle null values like if they were a type of error.\n\nWe can do that, by using either:\n\n- an if statement, like you would do in C.\n- the `orelse` keyword.\n- unwrap the optional value with the `?` method.\n\nWhen you use an if statement, you use a pair of pipes\nto unwrap the optional value, and use this \"unwrapped object\"\ninside the if block.\nUsing the example below as a reference, if the object `num` is null,\nthen, the code inside the if statement is not executed. Otherwise,\nthe if statement will unwrap the object `num` into the `not_null_num`\nobject. This `not_null_num` object is guaranteed to be not null inside\nthe scope of the if statement.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst num: ?i32 = 5;\nif (num) |not_null_num| {\n    try stdout.print(\"{d}\\n\", .{not_null_num});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n5\n```\n\n\n:::\n:::\n\n\n\n\n\nNow, the `orelse` keyword behaves like a binary operator. You connect two expressions with this keyword.\nOn the left side of `orelse`, you provide the expression that might result\nin a null value, and on the right side of `orelse`, you provide another expression\nthat will not result in a null value.\n\nThe idea behind the `orelse` keyword is: if the expression on the left side\nresult in a not-null value, then, this not-null value is used. However,\nif this expression on the left side result in a null value, then, the value\nof the expression on the right side is used instead.\n\nLooking at the example below, since the `x` object is currently null, the\n`orelse` decided to use the alternative value, which is the number 15.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x: ?i32 = null;\nconst dbl = (x orelse 15) * 2;\ntry stdout.print(\"{d}\\n\", .{dbl});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n30\n```\n\n\n:::\n:::\n\n\n\n\n\nYou can use the if statement or the `orelse` keyword, when you want to\nsolve (or deal with) this null value. However, if there is no clear solution\nto this null value, and the most logic and sane path is to simply panic\nand raise a loud error in your program when this null value is encountered,\nyou can use the `?` method of your optional object.\n\nIn essence, when you use this `?` method, the optional object is unwrapped.\nIf a not-null value is found in the optional object, then, this not-null value is used.\nOtherwise, the `unreachable` keyword is used. You can read more about this\n[`unreacheable` keyword at the official documentation](https://ziglang.org/documentation/master/#unreachable)[^un-docs].\nBut in essence, when you build your Zig source code using the build modes `ReleaseSafe` or `Debug`, this\n`unreacheable` keyword causes the program to panic and raise an error during runtime,\nlike in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn return_null(n: i32) ?i32 {\n    if (n == 5) return null;\n    return n;\n}\n\npub fn main() !void {\n    const x: i32 = 5;\n    const y: ?i32 = return_null(x);\n    try stdout.print(\"{d}\\n\", .{y.?});\n}\n```\n:::\n\n\n\n\n\n```\nthread 12767 panic: attempt to use null value\np7.zig:12:34: 0x103419d in main (p7):\n    try stdout.print(\"{d}\\n\", .{y.?});\n                                 ^\n```\n\n\n[^un-docs]: <https://ziglang.org/documentation/master/#unreachable>.\n\n\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/docs/Chapters/05-pointers.html b/docs/Chapters/05-pointers.html
index d14f04a5..1bc398f2 100644
--- a/docs/Chapters/05-pointers.html
+++ b/docs/Chapters/05-pointers.html
@@ -426,13 +426,13 @@ <h2 data-number="6.3" class="anchored" data-anchor-id="pointer-arithmetic"><span
 <p>Pointer arithmetic is available in Zig, and they work the same way they work in C. When you have a pointer that points to an array, the pointer usually points to the first element in the array, and you can use pointer arithmetic to advance this pointer and access the other elements in the array.</p>
 <p>Notice in the example below, that initially, the <code>ptr</code> object was pointing to the first element in the array <code>ar</code>. But then, I started to walk through the array, by advancing the pointer with simple pointer arithmetic.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb14"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ar = [_]<span class="dt">i32</span><span class="op">{</span><span class="dv">1</span>,<span class="dv">2</span>,<span class="dv">3</span>,<span class="dv">4</span><span class="op">}</span>;</span>
-<span id="cb14-2"><a href="#cb14-2" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> ptr = &amp;ar;</span>
-<span id="cb14-3"><a href="#cb14-3" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>ptr.*<span class="op">}</span>);</span>
+<div class="sourceCode cell-code" id="cb14"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ar = [_]<span class="dt">i32</span><span class="op">{</span> <span class="dv">1</span>, <span class="dv">2</span>, <span class="dv">3</span>, <span class="dv">4</span> <span class="op">}</span>;</span>
+<span id="cb14-2"><a href="#cb14-2" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> ptr: [*]<span class="kw">const</span> <span class="dt">i32</span> = &amp;ar;</span>
+<span id="cb14-3"><a href="#cb14-3" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>ptr[<span class="dv">0</span>]<span class="op">}</span>);</span>
 <span id="cb14-4"><a href="#cb14-4" aria-hidden="true" tabindex="-1"></a>ptr += <span class="dv">1</span>;</span>
-<span id="cb14-5"><a href="#cb14-5" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>ptr.*<span class="op">}</span>);</span>
+<span id="cb14-5"><a href="#cb14-5" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>ptr[<span class="dv">0</span>]<span class="op">}</span>);</span>
 <span id="cb14-6"><a href="#cb14-6" aria-hidden="true" tabindex="-1"></a>ptr += <span class="dv">1</span>;</span>
-<span id="cb14-7"><a href="#cb14-7" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>ptr.*<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<span id="cb14-7"><a href="#cb14-7" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>ptr[<span class="dv">0</span>]<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>1
 2
diff --git a/docs/search.json b/docs/search.json
index 1999409e..d9730825 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -514,7 +514,7 @@
     "href": "Chapters/05-pointers.html#pointer-arithmetic",
     "title": "6  Pointers and Optionals",
     "section": "6.3 Pointer arithmetic",
-    "text": "6.3 Pointer arithmetic\nPointer arithmetic is available in Zig, and they work the same way they work in C. When you have a pointer that points to an array, the pointer usually points to the first element in the array, and you can use pointer arithmetic to advance this pointer and access the other elements in the array.\nNotice in the example below, that initially, the ptr object was pointing to the first element in the array ar. But then, I started to walk through the array, by advancing the pointer with simple pointer arithmetic.\n\nconst ar = [_]i32{1,2,3,4};\nvar ptr = &ar;\ntry stdout.print(\"{d}\\n\", .{ptr.*});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr.*});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr.*});\n\n1\n2\n3\nAlthough you can create a pointer to an array like that, and start to walk through this array by using pointer arithmetic, in Zig, we prefer to use slices, which were presented at Section 1.6.\nBehind the hood, slices already are pointers, and they also come with the len property, which indicates how many elements are in the slice. This is good because the zig compiler can use it to check for potential buffer overflows, and other problems like that.\nAlso, you don’t need to use pointer arithmetic to walk through the elements of a slice. You can simply use the slice[index] syntax to directly access any element you want in the slice. As I mentioned at Section 1.6, you can get a slice from an array by using a range selector inside brackets. In the example below, I’m creating a slice (sl) that covers the entire ar array. I can access any element of ar from this slice, and, the slice itself already is a pointer behind the hood.\n\nconst ar = [_]i32{1,2,3,4};\nconst sl = ar[0..ar.len];\n_ = sl;",
+    "text": "6.3 Pointer arithmetic\nPointer arithmetic is available in Zig, and they work the same way they work in C. When you have a pointer that points to an array, the pointer usually points to the first element in the array, and you can use pointer arithmetic to advance this pointer and access the other elements in the array.\nNotice in the example below, that initially, the ptr object was pointing to the first element in the array ar. But then, I started to walk through the array, by advancing the pointer with simple pointer arithmetic.\n\nconst ar = [_]i32{ 1, 2, 3, 4 };\nvar ptr: [*]const i32 = &ar;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\n\n1\n2\n3\nAlthough you can create a pointer to an array like that, and start to walk through this array by using pointer arithmetic, in Zig, we prefer to use slices, which were presented at Section 1.6.\nBehind the hood, slices already are pointers, and they also come with the len property, which indicates how many elements are in the slice. This is good because the zig compiler can use it to check for potential buffer overflows, and other problems like that.\nAlso, you don’t need to use pointer arithmetic to walk through the elements of a slice. You can simply use the slice[index] syntax to directly access any element you want in the slice. As I mentioned at Section 1.6, you can get a slice from an array by using a range selector inside brackets. In the example below, I’m creating a slice (sl) that covers the entire ar array. I can access any element of ar from this slice, and, the slice itself already is a pointer behind the hood.\n\nconst ar = [_]i32{1,2,3,4};\nconst sl = ar[0..ar.len];\n_ = sl;",
     "crumbs": [
       "<span class='chapter-number'>6</span>  <span class='chapter-title'>Pointers and Optionals</span>"
     ]

From e2491f6907bf9049a7445eea128d67af10ef0372 Mon Sep 17 00:00:00 2001
From: Niklas Johansson <raphexion@gmail.com>
Date: Fri, 14 Feb 2025 08:41:11 +0100
Subject: [PATCH 065/151] fix: Remove unnecessary swear word

While reading the physical book I came across an unnecessary swear word.
Personally, I am not against swear words but this one felt unnecessary
and makes the book feel less professional.

I updated both the string and base64 encoding.

Thank you for writing this book.

I assign the copyright of this contribution to Pedro Duarte Faria.
---
 Chapters/01-base64.qmd | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Chapters/01-base64.qmd b/Chapters/01-base64.qmd
index fabfc797..962f63bb 100644
--- a/Chapters/01-base64.qmd
+++ b/Chapters/01-base64.qmd
@@ -834,8 +834,8 @@ var fba = std.heap.FixedBufferAllocator.init(
 );
 const allocator = fba.allocator();
 
-const text = "Testing some more shit";
-const etext = "VGVzdGluZyBzb21lIG1vcmUgc2hpdA==";
+const text = "Testing some more stuff";
+const etext = "VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=";
 const base64 = Base64.init();
 const encoded_text = try base64.encode(
     allocator, text
@@ -852,8 +852,8 @@ try stdout.print(
 ```
 
 ```
-Encoded text: VGVzdGluZyBzb21lIG1vcmUgc2hpdA==
-Decoded text: Testing some more shit
+Encoded text: VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=
+Decoded text: Testing some more stuff
 ```
 
 You can also see the full source code at once, by visiting the official repository of this book[^repo].

From 139721f72172e219e769fc9b87bb0f662ca87f22 Mon Sep 17 00:00:00 2001
From: Maarten Coppens <maarten.coppens@skedia.io>
Date: Sat, 15 Feb 2025 11:39:01 +0100
Subject: [PATCH 066/151] Update 01-zig-weird.qmd

fix typo
---
 Chapters/01-zig-weird.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index 125bdad3..1a1afa74 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -58,7 +58,7 @@ C are a frequent source of confusion. They really make it sometimes hard to debu
 C programs. Because macros are essentially a second language embedded in C that obscures
 your C code. With macros, you are no longer 100% sure about which pieces
 of the code are being sent to the compiler, i.e.
-they obscures the actual source code that you wrote.
+they obscure the actual source code that you wrote.
 
 You don't have macros in Zig. In Zig, the code you write, is the actual code that get's compiled by the compiler.
 You also don't have a hidden control flow happening behind the scenes. And, you also

From 2294c2d9fef7b4d29898c45117b2ea548b00ae52 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sat, 15 Feb 2025 20:11:12 -0300
Subject: [PATCH 067/151] Recompile book with changes

---
 _freeze/Chapters/01-base64/execute-results/html.json    | 4 ++--
 _freeze/Chapters/01-zig-weird/execute-results/html.json | 8 +++++---
 docs/Chapters/01-base64.html                            | 8 ++++----
 docs/Chapters/01-zig-weird.html                         | 2 +-
 docs/index.html                                         | 4 ++--
 docs/search.json                                        | 4 ++--
 6 files changed, 16 insertions(+), 14 deletions(-)

diff --git a/_freeze/Chapters/01-base64/execute-results/html.json b/_freeze/Chapters/01-base64/execute-results/html.json
index 0965e634..9eb2b631 100644
--- a/_freeze/Chapters/01-base64/execute-results/html.json
+++ b/_freeze/Chapters/01-base64/execute-results/html.json
@@ -1,8 +1,8 @@
 {
-  "hash": "225506bc4affdcc5aaf897c63caf73a4",
+  "hash": "f1304b563ed8036a5bbeaa9b658cfdf0",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 1 - Building a base64 encoder/decoder {#sec-base64}\n\nAs our first small project, I want to implement a base64 encoder/decoder with you.\nBase64 is an encoding system which translates binary data to text.\nA big chunk of the web uses base64 to deliver binary data to systems\nthat can only read text data.\n\nThe most common example of a modern use case for base64 is essentially any email system,\nlike GMail, Outlook, etc. Because email systems normally use\nthe Simple Mail Transfer Protocol (SMTP), which is a web protocol\nthat supports only text data. So, if you need, for any reason, to\nsend a binary file (like for example, a PDF, or an Excel file) as\nan attachment in your email, these binary files are normally\nconverted to base64, before they are included in the SMTP message.\nSo, the base64 encoding is largely used in these email systems to include\nbinary data into the SMTP message.\n\n\n\n\n\n\n## How the base64 algorithm work?\n\nBut how exactly does the algorithm behind the base64 encoding work? Let's discuss that. First, I will\nexplain the base64 scale, which is the 64-character scale that is the basis for\nthe base64 encoding system.\n\nAfter that, I explain the algorithm behind a base64 encoder, which is the part of the algorithm that is responsible for encoding messages\ninto the base64 encoding system. Then, after that, I explain the algorithm behind a base64 decoder, which is\nthe part of the algorithm that is responsible for translating base64 messages back into their original meaning.\n\nIf you are unsure about the differences between an \"encoder\" and a \"decoder\",\ntake a look at @sec-encode-vs-decode.\n\n\n### The base64 scale {#sec-base64-scale}\n\nThe base64 encoding system is based on a scale that goes from 0 to 63 (hence the name).\nEach index in this scale is represented by a character (it is a scale of 64 characters).\nSo, in order to convert some binary data, to the base64 encoding, we need to convert each binary number to the corresponding\ncharacter in this \"scale of 64 characters\".\n\nThe base64 scale starts with all ASCII uppercase letters (A to Z) which represents\nthe first 25 indexes in this scale (0 to 25). After that, we have all ASCII lowercase letters\n(a to z), which represents the range 26 to 51 in the scale. After that, we\nhave the one digit numbers (0 to 9), which represents the indexes from 52 to 61 in the scale.\nFinally, the last two indexes in the scale (62 and 63) are represented by the characters `+` and `/`,\nrespectively.\n\nThese are the 64 characters that compose the base64 scale. The equal sign character (`=`) is not part of the scale itself,\nbut it is a special character in the base64 encoding system. This character is used solely as a suffix, to mark the end of the character sequence,\nor, to mark the end of meaningful characters in the sequence.\n\nThe bullet points below summarises the base64 scale:\n\n- range 0 to 25 is represented by: ASCII uppercase letters `-> [A-Z]`;\n- range 26 to 51 is represented by: ASCII lowercase letters `-> [a-z]`;\n- range 52 to 61 is represented by: one digit numbers `-> [0-9]`;\n- index 62 and 63 are represented by the characters `+` and `/`, respectively;\n- the character `=` represents the end of meaningful characters in the sequence;\n\n\n\n\n### Creating the scale as a lookup table {#sec-base64-table}\n\nThe best way to represent this scale in code, is to represent it as a *lookup table*.\nLookup tables are a classic strategy in computer science to speed up calculations. The basic idea\nis to replace a runtime calculation (which can take a long time to be done) with a basic array indexing\noperation.\n\nInstead of calculating the results everytime you need them, you calculate all possible results at once, and then, you store them in an array\n(which behaves lake a \"table\"). Then, every time you need to use one of the characters in the base64 scale, instead of\nusing many resources to calculate the exact character to be used, you simply retrieve this character\nfrom the array where you stored all the possible characters in the base64 scale.\nWe retrieve the character that we need directly from memory.\n\nWe can start building a Zig struct to store our base64 decoder/encoder logic.\nWe start with the `Base64` struct below. For now, we only have one single data member in this\nstruct, i.e. the member `_table`, which represents our lookup table. We also have an `init()` method,\nto create a new instance of a `Base64` object, and, a `_char_at()` method, which is a\n\"get character at index $x$\" type of function.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Base64 = struct {\n    _table: *const [64]u8,\n\n    pub fn init() Base64 {\n        const upper = \"ABCDEFGHIJKLMNOPQRSTUVWXYZ\";\n        const lower = \"abcdefghijklmnopqrstuvwxyz\";\n        const numbers_symb = \"0123456789+/\";\n        return Base64{\n            ._table = upper ++ lower ++ numbers_symb,\n        };\n    }\n\n    pub fn _char_at(self: Base64, index: usize) u8 {\n        return self._table[index];\n    }\n};\n```\n:::\n\n\n\n\n\nIn other words, the `_char_at()` method is responsible for getting the character in the lookup\ntable (i.e. the `_table` struct data member) that corresponds to a particular index in the\n\"base64 scale\". So, in the example below, we know that the character that corresponds to the\nindex 28 in the \"base64 scale\" is the character \"c\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst base64 = Base64.init();\ntry stdout.print(\n    \"Character at index 28: {c}\\n\",\n    .{base64._char_at(28)}\n);\n```\n:::\n\n\n\n\n```\nCharacter at index 28: c\n```\n\n\n\n### A base64 encoder {#sec-base64-encoder-algo}\n\nThe algorithm behind a base64 encoder usually works on a window of 3 bytes. Because each byte has\n8 bits, so, 3 bytes forms a set of $8 \\times 3 = 24$ bits. This is desirable for the base64 algorithm, because\n24 bits is divisible by 6, which forms $24 / 6 = 4$ groups of 6 bits each.\n\nTherefore, the base64 algorithm works by converting 3 bytes at a time\ninto 4 characters from the base64 scale. It keeps iterating through the input string,\n3 bytes at a time, and converting them into the base64 scale, producing 4 characters\nper iteration. It keeps iterating, and producing these \"new characters\"\nuntil it hits the end of the input string.\n\nNow, you may think, what if you have a particular string that have a number of bytes\nthat is not divisible by 3? What happens? For example, if you have a string\nthat contains only two characters/bytes, such as \"Hi\". How the\nalgorithm would behave in such situation? You find the answer at @fig-base64-algo1.\nYou can see at @fig-base64-algo1 that the string \"Hi\", when converted to base64,\nbecomes the string \"SGk=\":\n\n![The logic behind a base64 encoder](./../Figures/base64-encoder-flow.png){#fig-base64-algo1}\n\nTaking the string \"Hi\" as an example, we have 2 bytes, or, 16 bits in total. So, we lack a full byte (8 bits)\nto complete the window of 24 bits that the base64 algorithm likes to work on. The first thing that\nthe algorithm does, is to check how to divide the input bytes into groups of 6 bits.\n\nIf the algorithm notices that there is a group of 6 bits that, have some bits in it, but, at the same time, it is not full\n(in other words, $0 < nbits < 6$, being $nbits$ the number of bits), meaning that, it lacks\nsome bits to fill the 6-bits requirement, the algorithm simply add extra zeros in this group\nto fill the space that it needs. That is why at @fig-base64-algo1, on the third group after the 6-bit transformation,\n2 extra zeros were added to fill the gap in this group.\n\nWhen we have a 6-bit group that is not completely full, like the third group, extra zeros\nare added to fill the gap. But what about when an entire 6-bit group is empty, or, it\nsimply doesn't exist? This is the case of the fourth 6-bit group exposed at\n@fig-base64-algo1.\n\nThis fourth group is necessary, because the algorithm works on 4 groups of 6 bits.\nBut the input string does not have enough bytes to create a fourth 6-bit group.\nEvery time this happens, where an entire group of 6 bits is empty,\nthis group becomes a \"padding group\". Every \"padding group\" is mapped to\nthe character `=` (equal sign), which represents \"null\", or, the end\nof meaningful characters in the sequence. Hence, everytime that the algorithm produces a\n\"padding group\", this group is automatically mapped to `=`.\n\nAs another example, if you give the string \"0\" as input to a base64 encoder, this string is\ntranslated into the base64 sequence \"MA==\".\nThe character \"0\" is, in binary, the sequence `00110000`[^zero-note]. So, with the 6-bit transformation\nexposed at @fig-base64-algo1, this single character would produce these two 6-bit groups: `001100`, `000000`.\nThe remaining two 6-bit groups become \"padding groups\". That is why the last\ntwo characters in the output sequence (MA==) are `==`.\n\n\n[^zero-note]: Notice that, the character \"0\" is different than the actual number 0, which is simply zero in binary.\n\n### A base64 decoder {#sec-base64-decoder-algo}\n\nThe algorithm behind a base64 decoder is essentially the inverse process of a base64 encoder.\nA base64 decoder needs to translate base64 messages back into their original meaning,\ni.e. into the original sequence of binary data.\n\nA base64 decoder usually works on a window of 4 bytes. Because it wants to convert these 4 bytes\nback into the original sequence of 3 bytes, that was converted into 4 groups of 6 bits by the\nbase64 encoder. Remember, in a base64 decoder we are essentially reverting the process made\nby the base64 encoder.\n\nEach byte in the input string (the base64 encoded string) normally contributes to re-create\ntwo different bytes in the output (the original binary data).\nIn other words, each byte that comes out of a base64 decoder is created by transforming merging two different\nbytes in the input together. You can visualize this relationship at @fig-base64-algo2:\n\n![The logic behind a base64 decoder](./../Figures/base64-decoder-flow.png){#fig-base64-algo2}\n\nThe exact transformations, or, the exact steps applied to each byte from the input to transform them\ninto the bytes of the output, are a bit tricky to visualize in a figure like this. Because of that, I have\nsummarized these transformations as \"Some bit shifting and additions ...\" in the figure. These transformations\nwill be described in depth later.\n\nBesides that, if you look again at @fig-base64-algo2, you will notice that the character `=` was completely\nignored by the algorithm. Remember, this is just a special character that marks the end of meaningful characters\nin the base64 sequence. So, every `=` character in a base64 encoded sequence should be ignored by a base64 decoder.\n\n\n## Difference between encode and decode {#sec-encode-vs-decode}\n\nIf you don't have any previous experience with base64, you might not understand the differences\nbetween \"encode\" and \"decode\". Essentially, the terms \"encode\" and \"decode\" here\nhave the exact same meaning as they have in the field of encryption (i.e. they mean the same thing as \"encode\" and \"decode\" in hashing\nalgorithms, like the MD5 algorithm).\n\nThus, \"encode\" means that we want to encode, or, in other words, we want to translate some message into\nthe base64 encoding system. We want to produce the sequence of base64 characters that represent this\noriginal message in the base64 encoding system.\n\nIn contrast, \"decode\" represents the inverse process.\nWe want to decode, or, in other words, translate a base64 message back to its original content.\nSo, in this process we get a sequence of base64 characters as input, and produce as output,\nthe binary data that is represented by this sequence of base64 characters.\n\nAny base64 library is normally composed of these two parts: 1) the encoder, which is a function that encodes\n(i.e. it converts) any sequence of binary data into a sequence of base64 characters; 2) the decoder, which is a function\nthat converts a sequence of base64 characters back into the original sequence of binary data.\n\n\n\n## Calculating the size of the output {#sec-base64-length-out}\n\nOne task that we need to do is to calculate how much space we need to reserve for the\noutput, both of the encoder and decoder. This is simple math, and can be done easily in Zig\nbecause every array has its length (its number of elements) easily accesible by consulting\nthe `.len` property of the array.\n\nFor the encoder, the logic is the following: for each 3 bytes that we find in the input,\n4 new bytes are created in the output. So, we take the number of bytes in the input, divide it\nby 3, use a ceiling function, then, we multiply the result by 4. That way, we get the total\nnumber of bytes that will be produced by the encoder in its output.\n\nThe `_calc_encode_length()` function below encapsulates this logic.\nInside this function, we take the length of the input array,\nwe divide it by 3, and apply a ceil operation over the result by using the\n`divCeil()` function from the Zig Standard Library. Lastly, we multiply\nthe end result by 4 to get the answer we need.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_encode_length(input: []const u8) !usize {\n    if (input.len < 3) {\n        const n_output: usize = 4;\n        return n_output;\n    }\n    const n_output: usize = try std.math.divCeil(\n        usize, input.len, 3\n    );\n    return n_output * 4;\n}\n```\n:::\n\n\n\n\n\nAlso, you might have notice that, if the input length is less than 3 bytes, then, the output length of the encoder is\nalways 4 bytes. This is the case for every input with less than 3 bytes, because, as I described at @sec-base64-encoder-algo,\nthe algorithm always produces enough \"padding-groups\" in the end result, to complete the 4 bytes window.\n\nNow, for the decoder, we just need to apply the inverse logic: for each 4 bytes in the input, 3 bytes\nwill be produced in the output of the decoder. I mean, this is roughly true, because we also need to\ntake the `=` character into account, which is always ignored by the decoder, as we described at @sec-base64-decoder-algo, and,\nat @fig-base64-algo2. But we can ignore this fact for now, just to keep things simple.\n\nThe function `_calc_decode_length()` exposed below summarizes this logic that we described. It is very similar\nto the function `_calc_encode_length()`. Only the division part is twisted, and also, in the special\ncase where we have less than 4 bytes in the input to work on. Also notice that this time, we apply\na floor operation over the output of the division, by using the `divFloor()`\nfunction (instead of a ceiling operation with `divCeil()`).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_decode_length(input: []const u8) !usize {\n    if (input.len < 4) {\n        const n_output: usize = 3;\n        return n_output;\n    }\n    const n_output: usize = try std.math.divFloor(\n        usize, input.len, 4\n    );\n    return n_output * 3;\n}\n```\n:::\n\n\n\n\n\n## Building the encoder logic {#sec-encoder-logic}\n\nIn this section, we can start building the logic behind the `encode()` function, which\nwill be responsible for encoding messages into the base64 encoding system.\nIf you are an anxious person, and you want to see now the full source code of the implementation\nfor this base64 encoder/decoder, you can find it at the `ZigExamples` folder in the official repository of\nthis book[^zig-base64-algo].\n\n[^zig-base64-algo]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/base64/base64_basic.zig>.\n\n\n\n### The 6-bit transformation {#sec-6bit-transf}\n\nThe 6-bit transformation presented at @fig-base64-algo1 is the core part of the base64 encoder algorithm.\nBy understanding how this transformation is made in code, the rest of the algorithm becomes much simpler\nto comprehend.\n\nIn essence, this 6-bit transformation is made with the help of bitwise operators.\nBitwise operators are essential to any type of low-level operation that is done at the bit-level. For the specific case of the base64 algorithm,\nthe operators *bif shift to the left* (`<<`), *bit shift to the right* (`>>`), and the *bitwise and* (`&`) are used. They\nare the core solution for the 6-bit transformation.\n\nThere are 3 different scenarios that we need to take into account in this transformation. First, is the perfect scenario,\nwhere we have the perfect window of 3 bytes to work on. Second, we have the scenario where we have a window of only\ntwo bytes to work with. And last, we have the scenario where we have a window of one single byte.\n\nIn each of these 3 scenarios, the 6-bit transformation works a bit differently. To make the explanation\neasier, I will use the variable `output` to refer to the bytes in the output of the base64 encoder,\nand the variable `input` to refer to the bytes in the input of the encoder.\n\n\nSo, if you have the perfect window of 3 bytes, these are steps for the 6-bit transformation:\n\n1. `output[0]` is produced by moving the bits from `input[0]` two positions to the right.\n1. `output[1]` is produced by summing two components. First, take the last two bits from `input[0]`, then, move them four positions to the left. Second, move the bits from `input[1]` four positions to the right. Sum these two components.\n1. `output[2]` is produced by summing two components. First, take the last four bits from `input[1]`, then, move them two positions to the left. Second, move the bits from `input[2]` six positions to the right. Sum these two components.\n1. `output[3]` is produced by taking the last six bits from `input[2]`.\n\n\nThis is the perfect scenario, where we have a full window of 3 bytes to work on.\nJust to make things as clear as possible, the @fig-encoder-bitshift demonstrates visually how\nthe step 2 mentioned above works. So the 2nd byte in the `output` of the encoder, is made by taking the 1st byte (dark purple)\nand the 2nd byte (orange) from the input. You can see that, at the end of the process, we get a new\nbyte that contains the last 2 bits from the 1st byte in the `input`, and the first 4 bits\nfrom the 2nd byte in the `input`.\n\n![How the 2nd byte in the output of the encoder is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input.](../Figures/base64-encoder-bit-shift.png){#fig-encoder-bitshift}\n\nOn the other hand, we must be prepared for the instances where we do not have the perfect window of 3 bytes.\nIf you have a window of 2 bytes, then, the steps 3 and 4, which produces the bytes `output[2]` and `output[3]`, change a little bit,\nand they become:\n\n- `output[2]` is produced by taking the last 4 bits from `input[1]`, then, move them two positions to the left.\n- `output[3]` is the character `'='`.\n\n\nFinally, if you have a window of a single byte, then, the steps 2 to 4, which produces the bytes `output[1]`, `output[2]` and `output[3]` change,\nbecoming:\n\n- `output[1]` is produced by taking the last two bits from `input[0]`, then, move them four positions to the left.\n- `output[2]` and `output[3]` are the character `=`.\n\n\nIf these bullet points were a bit confusing for you, you may find the @tbl-transf-6bit more intuitive.\nThis table unifies all this logic into a simple table. Notice that\nthis table also provides the exact expression in Zig that creates the corresponding\nbyte in the output.\n\n\n::: {#tbl-transf-6bit}\n\n| Number of bytes in the window | Byte index in the output | In code                                    |\n|-------------------------------|--------------------------|--------------------------------------------|\n| 3                             | 0                        | input[0] >> 2                              |\n| 3                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 3                             | 2                        | ((input[1] & 0x0f) << 2) + (input[2] >> 6) |\n| 3                             | 3                        | input[2] & 0x3f                            |\n| 2                             | 0                        | input[0] >> 2                              |\n| 2                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 2                             | 2                        | ((input[1] & 0x0f) << 2)                   |\n| 2                             | 3                        | '='                                        |\n| 1                             | 0                        | input[0] >> 2                              |\n| 1                             | 1                        | ((input[0] & 0x03) << 4)                   |\n| 1                             | 2                        | '='                                        |\n| 1                             | 3                        | '='                                        |\n\n: How the 6-bit transformation translates into code in different window settings.\n\n:::\n\n\n\n\n\n\n### Bit-shifting in Zig\n\nBit-shifting in Zig works similarly to bit-shifting in C.\nAll bitwise operators that exist in C are available in Zig.\nHere, in the base64 encoder algorithm, they are essential\nto produce the result we want.\n\nFor those who are not familiar with these operators, they are\noperators that operates at the bit-level of your values.\nThis means that these operators takes the bits that form the value\nyou have, and change them in some way. This ultimately also changes\nthe value itself, because the binary representation of this value\nchanges.\n\nWe have already seen at @fig-encoder-bitshift the effect produced by a bit-shift.\nBut let's use the first byte in the output of the base64 encoder as another example of what\nbit-shifting means. This is the easiest byte of the 4 bytes in the output\nto build. Because we only need to move the bits from the first byte in the input two positions to the right,\nwith the *bit shift to the right* (`>>`) operator.\n\nIf we take the string \"Hi\" that we used at @fig-base64-algo1 as an example, the first byte in\nthis string is \"H\", which is the sequence `01001000` in binary.\nIf we move the bits of this byte, two places to the right, we get the sequence `00010010` as result.\nThis binary sequence is the value `18` in decimal, and also, the value `0x12` in hexadecimal.\nNotice that the first 6 bits of \"H\" were moved to the end of the byte.\nWith this operation, we get the first byte of the output.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const input = \"Hi\";\n    try stdout.print(\"{d}\\n\", .{input[0] >> 2});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n18\n```\n\n\n:::\n:::\n\n\n\n\nIf you recall @fig-base64-algo1, the first byte present in the output should\nbe equivalent to the 6-bit group `010010`. Although being visually different, the\nsequences `010010` and `00010010` are semantically equal. They mean the same thing.\nThey both represent the number 18 in decimal, and the value `0x12` in hexadecimal.\n\nSo, don't take the \"6-bit group\" factor so seriously. We do not need necessarily to\nget a 6-bit sequence as result. As long as the meaning of the 8-bit sequence we get is the same\nof the 6-bit sequence, we are in the clear.\n\n\n\n### Selecting specific bits with the `&` operator\n\nIf you comeback to @sec-6bit-transf, you will see that, in order to produce\nthe second and third bytes in the output, we need to select specific\nbits from the first and second bytes in the input string. But how\ncan we do that? The answer relies on the *bitwise and* (`&`) operator.\n\nThe @fig-encoder-bitshift already showed you what effect this `&` operator\nproduces in the bits of its operands. But let's make a clear description of it.\n\nIn summary, the `&` operator performs a logical conjunction operation\nbetween the bits of its operands. In more details, the operator `&`\ncompares each bit of the first operand to the corresponding bit of the second operand.\nIf both bits are 1, the corresponding result bit is set to 1.\nOtherwise, the corresponding result bit is set to 0 [@microsoftbitwiseand].\n\nSo, if we apply this operator to the binary sequences `1000100` and `00001101`\nthe result of this operation is the binary sequence `00000100`. Because only\nat the sixth position in both binary sequences we had a 1 value. So any\nposition where we do not have both binary sequences setted to 1, we get\na 0 bit in the resulting binary sequence.\n\nWe lose information about the original bit values\nfrom both sequences in this case. Because we no longer know\nif this 0 bit in the resulting binary sequence was produced by\ncombining 0 with 0, or 1 with 0, or 0 with 1.\n\nAs an example, suppose you have the binary sequence `10010111`, which is the number 151 in decimal. How\ncan we get a new binary sequence which contains only the third and\nfourth bits of this sequence?\n\nWe just need to combine this sequence with `00110000` (is `0x30` in hexadecimal) using the `&` operator.\nNotice that only the third and fourth positions in this binary sequence is setted to 1. As a consequence, only the\nthird and fourth values of both binary sequences are potentially preserved in the output. All the remaining positions\nare setted to zero in the output sequence, which is `00010000` (is the number 16 in decimal).\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const bits = 0b10010111;\n    try stdout.print(\"{d}\\n\", .{bits & 0b00110000});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n16\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Allocating space for the output\n\nAs I described at @sec-stack, to store an object in the stack,\nthis object needs to have a known and fixed length at compile-time. This is an important\nlimitation for our base64 encoder/decoder case. Because the size of\nthe output (from both the encoder and decoder) depends\ndirectly on the size of the input.\n\nHaving this in mind, we cannot know at compile time which is\nthe size of the output for both the encoder and decoder.\nSo, if we can't know the size of the output at compile time,\nthis means that we cannot store the output for both the encoder\nand decoder in the stack.\n\nConsequently, we need to store this output on the heap,\nand, as I commented at @sec-heap, we can only\nstore objects in the heap by using allocator objects.\nSo, one the arguments to both the `encode()` and `decode()`\nfunctions, needs to be an allocator object, because\nwe know for sure that, at some point inside the body of these\nfunctions, we need to allocate space on the heap to\nstore the output of these functions.\n\nThat is why, both the `encode()` and `decode()` functions that I\npresent in this book, have an argument called `allocator`,\nwhich receives a allocator object as input, identified by\nthe type `std.mem.Allocator` from the Zig Standard Library.\n\n\n\n### Writing the `encode()` function\n\nNow that we have a basic understanding on how the bitwise operators work, and how\nexactly they help us to achieve the result we want to achieve. We can now encapsulate\nall the logic that we have described at @fig-base64-algo1 and @tbl-transf-6bit into a nice\nfunction that we can add to our `Base64` struct definition, that we started at @sec-base64-table.\n\nYou can find the `encode()` function below. Notice that the first argument of this function,\nis the `Base64` struct itself. Therefore, this argument clearly signals\nthat this function is a method from the `Base64` struct.\n\nBecause the `encode()` function itself is fairly long,\nI intentionally omitted the `Base64` struct definition in this source code,\njust for brevity reasons. So, just remember that this function is a public function (or a public method) from the\n`Base64` struct.\n\nFurthermore, this `encode()` function has two other arguments:\n\n1. `input` is the input sequence of characters that you want to encode in base64;\n1. `allocator` is an allocator object to use in the necessary memory allocations.\n\nI described everything you need to know about allocator objects at @sec-allocators.\nSo, if you are not familiar with them, I highly recommend you to comeback to\nthat section, and read it.\nBy looking at the `encode()` function, you will see that we use this\nallocator object to allocate enough memory to store the output of\nthe encoding process.\n\nThe main for loop in the function is responsible for iterating through the entire input string.\nIn every iteration, we use a `count` variable to count how many iterations we had at the\nmoment. When `count` reaches 3, then, we try to encode the 3 characters (or bytes) that we have accumulated\nin the temporary buffer object (`buf`).\n\nAfter encoding these 3 characters and storing the result in the `output` variable, we reset\nthe `count` variable to zero, and start to count again on the next iteration of the loop.\nIf the loop hits the end of the string, and, the `count` variable is less than 3, then, it means that\nthe temporary buffer contains the last 1 or 2 bytes from the input.\nThat is why we have two `if` statements after the for loop. To deal which each possible case.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn encode(self: Base64,\n              allocator: std.mem.Allocator,\n              input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n\n    const n_out = try _calc_encode_length(input);\n    var out = try allocator.alloc(u8, n_out);\n    var buf = [3]u8{ 0, 0, 0 };\n    var count: u8 = 0;\n    var iout: u64 = 0;\n\n    for (input, 0..) |_, i| {\n        buf[count] = input[i];\n        count += 1;\n        if (count == 3) {\n            out[iout] = self._char_at(buf[0] >> 2);\n            out[iout + 1] = self._char_at(\n                ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n            );\n            out[iout + 2] = self._char_at(\n                ((buf[1] & 0x0f) << 2) + (buf[2] >> 6)\n            );\n            out[iout + 3] = self._char_at(buf[2] & 0x3f);\n            iout += 4;\n            count = 0;\n        }\n    }\n\n    if (count == 1) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            (buf[0] & 0x03) << 4\n        );\n        out[iout + 2] = '=';\n        out[iout + 3] = '=';\n    }\n\n    if (count == 2) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n        );\n        out[iout + 2] = self._char_at(\n            (buf[1] & 0x0f) << 2\n        );\n        out[iout + 3] = '=';\n        iout += 4;\n    }\n\n    return out;\n}\n```\n:::\n\n\n\n\n\n\n## Building the decoder logic {#sec-decoder-logic}\n\nNow, we can focus on writing the base64 decoder logic. Remember from @fig-base64-algo2 that,\na base64 decoder does the inverse process of an encoder. So, all we need to do, is to\nwrite a `decode()` function that performs the inverse process that I exposed at @sec-encoder-logic.\n\n\n### Mapping base64 characters to their indexes {#sec-map-base64-index}\n\nOne thing that we need to do, in order to decode a base64-encoded message, is to calculate\nthe index in the base64 scale of every base64 character that we encounter in the decoder input.\n\nIn other words, the decoder receives as input, a sequence of base64 characters. We need\nto translate this sequence of characters into a sequence of indexes. These indexes\nare the index of each character in the base64 scale. This way, we get the value/byte\nthat was calculated in the 6-bit transformation step of the encoder process.\n\nThere are probably better/faster ways to calculate this, especially using a \"divide and conquer\"\ntype of strategy. But for now, I am satisfied with a simple and \"brute force\" type of strategy.\nThe `_char_index()` function below contains this strategy.\n\nWe are essentially looping through the *lookup table* with the base64 scale,\nand comparing the character we got with each character in the base64 scale.\nIf these characters match, then, we return the index of this character in the\nbase64 scale as the result.\n\nNotice that, if the input character is `'='`, the function returns the index 64, which is\n\"out of range\" in the scale. But, as I described at @sec-base64-scale,\nthe character `'='` does not belong to the base64 scale itself.\nIt is a special and meaningless character in base64.\n\nAlso notice that this `_char_index()` function is a method from our `Base64` struct,\nbecause of the `self` argument. Again, I have omitted the `Base64` struct definition in this example\nfor brevity reasons.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn _char_index(self: Base64, char: u8) u8 {\n    if (char == '=')\n        return 64;\n    var index: u8 = 0;\n    for (0..63) |i| {\n        if (self._char_at(i) == char)\n            break;\n        index += 1;\n    }\n\n    return index;\n}\n```\n:::\n\n\n\n\n\n\n### The 6-bit transformation\n\nOnce again, the core part of the algorithm is the 6-bit transformation.\nIf we understand the necessary steps to perform this transformation, the rest\nof the algorithm becomes much easier.\n\nFirst of all, before we actually go to the 6-bit transformation,\nwe need to make sure that we use `_char_index()` to convert the sequence of base64 characters\ninto a sequence of indexes. So the snippet below is important for the job that will be done.\nThe result of `_char_index()` is stored in a temporary buffer, and this temporary buffer\nis what we are going to use in the 6-bit transformation, instead of the actual `input` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (0..input.len) |i| {\n    buf[i] = self._char_index(input[i]);\n}\n```\n:::\n\n\n\n\nNow, instead of producing 4 bytes (or 4 characters) as output per each window of 3 characters in the input,\na base64 decoder produces 3 bytes (or 3 characters) as output per each window of 4 characters in the input.\nOnce again, is the inverse process.\n\nSo, the steps to produce the 3 bytes in the output are:\n\n1. `output[0]` is produced by summing two components. First, move the bits from `buf[0]` two positions to the left. Second, move the bits from `buf[1]` 4 positions to the right. Then, sum these two components.\n1. `output[1]` is produced by summing two components. First, move the bits from `buf[1]` four positions to the left. Second, move the bits from `buf[2]` 2 positions to the right. Then, sum these two components.\n1. `output[2]` is produced by summing two components. First, move the bits from `buf[2]` six positions to the left. Then, you sum the result with `buf[3]`.\n\n\nBefore we continue, let's try to visualize how these transformations make the original bytes that we had\nbefore the encoding process. First, think back to the 6-bit transformation performed by the encoder exposed at @sec-encoder-logic.\nThe first byte in the output of the encoder is produced by moving the bits in the first byte of the input two positions to the right.\n\nIf for example the first byte in the input of the encoder was the sequence `ABCDEFGH`, then, the first byte in the output of the encoder would be\n`00ABCDEF` (this sequence would be the first byte in the input of the decoder). Now, if the second byte in the input of the encoder was the sequence\n`IJKLMNOP`, then, the second byte in the encoder output would be `00GHIJKL` (as we demonstrated at @fig-encoder-bitshift).\n\nHence, if the sequences `00ABCDEF` and `00GHIJKL` are the first and second bytes, respectively, in the input of the decoder, the\n@fig-decoder-bitshift demonstrates visually how these two bytes are transformed into the first byte of the output of the decoder.\nNotice that the output byte is the sequence `ABCDEFGH`, which is the original byte from the input of the encoder.\n\n![How the 1st byte in the decoder output is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input](../Figures/base64-decoder-bit-shift.png){#fig-decoder-bitshift}\n\nThe @tbl-6bit-decode presents how the three steps described earlier translate into Zig code:\n\n\n\n::: {#tbl-6bit-decode}\n\n| Byte index in the output | In code                       |\n|--------------------------|-------------------------------|\n| 0                        | (buf[0] << 2) + (buf[1] >> 4) |\n| 1                        | (buf[1] << 4) + (buf[2] >> 2) |\n| 2                        | (buf[2] << 6) + buf[3]        |\n\n: The necessary steps for the 6-transformation in the decode process.\n\n\n:::\n\n\n\n\n\n\n\n### Writing the `decode()` function\n\nThe `decode()` function below contains the entire decoding process.\nWe first calculate the size of the output, with\n`_calc_decode_length()`, then, we allocate enough memory for this output with\nthe allocator object.\n\nThree temporary variables are created: 1) `count`, to hold the window count\nin each iteration of the for loop; 2) `iout`, to hold the current index in the output;\n3) `buf`, which is the temporary buffer that holds the base64 indexes to be\nconverted through the 6-bit transformation.\n\nThen, in each iteration of the for loop we fill the temporary buffer with the current\nwindow of bytes. When `count` hits the number 4, then, we have a full window of\nindexes in `buf` to be converted, and then, we apply the 6-bit transformation\nover the temporary buffer.\n\nNotice that we check if the indexes 2 and 3 in the temporary buffer are the number 64, which, if you recall\nfrom @sec-map-base64-index, is when the `_calc_index()` function receives a `'='` character\nas input. So, if these indexes are equal to the number 64, the `decode()` function knows\nthat it can simply ignore these indexes. They are not converted because, as I described before,\nthe character `'='` has no meaning, despite being the end of meaningful characters in the sequence.\nSo we can safely ignore them when they appear in the sequence.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn decode(self: Base64,\n          allocator: std.mem.Allocator,\n          input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n    const n_output = try _calc_decode_length(input);\n    var output = try allocator.alloc(u8, n_output);\n    var count: u8 = 0;\n    var iout: u64 = 0;\n    var buf = [4]u8{ 0, 0, 0, 0 };\n\n    for (0..input.len) |i| {\n        buf[count] = self._char_index(input[i]);\n        count += 1;\n        if (count == 4) {\n            output[iout] = (buf[0] << 2) + (buf[1] >> 4);\n            if (buf[2] != 64) {\n                output[iout + 1] = (buf[1] << 4) + (buf[2] >> 2);\n            }\n            if (buf[3] != 64) {\n                output[iout + 2] = (buf[2] << 6) + buf[3];\n            }\n            iout += 3;\n            count = 0;\n        }\n    }\n\n    return output;\n}\n```\n:::\n\n\n\n\n\n## The end result\n\nNow that we have both `decode()` and `encode()` implemented. We have a fully functioning\nbase64 encoder/decoder implemented in Zig. Here is an usage example of our\n`Base64` struct with the `encode()` and `decode()` methods that we have implemented.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar memory_buffer: [1000]u8 = undefined;\nvar fba = std.heap.FixedBufferAllocator.init(\n    &memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst text = \"Testing some more shit\";\nconst etext = \"VGVzdGluZyBzb21lIG1vcmUgc2hpdA==\";\nconst base64 = Base64.init();\nconst encoded_text = try base64.encode(\n    allocator, text\n);\nconst decoded_text = try base64.decode(\n    allocator, etext\n);\ntry stdout.print(\n    \"Encoded text: {s}\\n\", .{encoded_text}\n);\ntry stdout.print(\n    \"Decoded text: {s}\\n\", .{decoded_text}\n);\n```\n:::\n\n\n\n\n```\nEncoded text: VGVzdGluZyBzb21lIG1vcmUgc2hpdA==\nDecoded text: Testing some more shit\n```\n\nYou can also see the full source code at once, by visiting the official repository of this book[^repo].\nMore precisely inside the `ZigExamples` folder[^zig-base64-algo].\n\n[^repo]: <https://github.com/pedropark99/zig-book>\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 1 - Building a base64 encoder/decoder {#sec-base64}\n\nAs our first small project, I want to implement a base64 encoder/decoder with you.\nBase64 is an encoding system which translates binary data to text.\nA big chunk of the web uses base64 to deliver binary data to systems\nthat can only read text data.\n\nThe most common example of a modern use case for base64 is essentially any email system,\nlike GMail, Outlook, etc. Because email systems normally use\nthe Simple Mail Transfer Protocol (SMTP), which is a web protocol\nthat supports only text data. So, if you need, for any reason, to\nsend a binary file (like for example, a PDF, or an Excel file) as\nan attachment in your email, these binary files are normally\nconverted to base64, before they are included in the SMTP message.\nSo, the base64 encoding is largely used in these email systems to include\nbinary data into the SMTP message.\n\n\n\n\n\n\n## How the base64 algorithm work?\n\nBut how exactly does the algorithm behind the base64 encoding work? Let's discuss that. First, I will\nexplain the base64 scale, which is the 64-character scale that is the basis for\nthe base64 encoding system.\n\nAfter that, I explain the algorithm behind a base64 encoder, which is the part of the algorithm that is responsible for encoding messages\ninto the base64 encoding system. Then, after that, I explain the algorithm behind a base64 decoder, which is\nthe part of the algorithm that is responsible for translating base64 messages back into their original meaning.\n\nIf you are unsure about the differences between an \"encoder\" and a \"decoder\",\ntake a look at @sec-encode-vs-decode.\n\n\n### The base64 scale {#sec-base64-scale}\n\nThe base64 encoding system is based on a scale that goes from 0 to 63 (hence the name).\nEach index in this scale is represented by a character (it is a scale of 64 characters).\nSo, in order to convert some binary data, to the base64 encoding, we need to convert each binary number to the corresponding\ncharacter in this \"scale of 64 characters\".\n\nThe base64 scale starts with all ASCII uppercase letters (A to Z) which represents\nthe first 25 indexes in this scale (0 to 25). After that, we have all ASCII lowercase letters\n(a to z), which represents the range 26 to 51 in the scale. After that, we\nhave the one digit numbers (0 to 9), which represents the indexes from 52 to 61 in the scale.\nFinally, the last two indexes in the scale (62 and 63) are represented by the characters `+` and `/`,\nrespectively.\n\nThese are the 64 characters that compose the base64 scale. The equal sign character (`=`) is not part of the scale itself,\nbut it is a special character in the base64 encoding system. This character is used solely as a suffix, to mark the end of the character sequence,\nor, to mark the end of meaningful characters in the sequence.\n\nThe bullet points below summarises the base64 scale:\n\n- range 0 to 25 is represented by: ASCII uppercase letters `-> [A-Z]`;\n- range 26 to 51 is represented by: ASCII lowercase letters `-> [a-z]`;\n- range 52 to 61 is represented by: one digit numbers `-> [0-9]`;\n- index 62 and 63 are represented by the characters `+` and `/`, respectively;\n- the character `=` represents the end of meaningful characters in the sequence;\n\n\n\n\n### Creating the scale as a lookup table {#sec-base64-table}\n\nThe best way to represent this scale in code, is to represent it as a *lookup table*.\nLookup tables are a classic strategy in computer science to speed up calculations. The basic idea\nis to replace a runtime calculation (which can take a long time to be done) with a basic array indexing\noperation.\n\nInstead of calculating the results everytime you need them, you calculate all possible results at once, and then, you store them in an array\n(which behaves lake a \"table\"). Then, every time you need to use one of the characters in the base64 scale, instead of\nusing many resources to calculate the exact character to be used, you simply retrieve this character\nfrom the array where you stored all the possible characters in the base64 scale.\nWe retrieve the character that we need directly from memory.\n\nWe can start building a Zig struct to store our base64 decoder/encoder logic.\nWe start with the `Base64` struct below. For now, we only have one single data member in this\nstruct, i.e. the member `_table`, which represents our lookup table. We also have an `init()` method,\nto create a new instance of a `Base64` object, and, a `_char_at()` method, which is a\n\"get character at index $x$\" type of function.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Base64 = struct {\n    _table: *const [64]u8,\n\n    pub fn init() Base64 {\n        const upper = \"ABCDEFGHIJKLMNOPQRSTUVWXYZ\";\n        const lower = \"abcdefghijklmnopqrstuvwxyz\";\n        const numbers_symb = \"0123456789+/\";\n        return Base64{\n            ._table = upper ++ lower ++ numbers_symb,\n        };\n    }\n\n    pub fn _char_at(self: Base64, index: usize) u8 {\n        return self._table[index];\n    }\n};\n```\n:::\n\n\n\n\n\nIn other words, the `_char_at()` method is responsible for getting the character in the lookup\ntable (i.e. the `_table` struct data member) that corresponds to a particular index in the\n\"base64 scale\". So, in the example below, we know that the character that corresponds to the\nindex 28 in the \"base64 scale\" is the character \"c\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst base64 = Base64.init();\ntry stdout.print(\n    \"Character at index 28: {c}\\n\",\n    .{base64._char_at(28)}\n);\n```\n:::\n\n\n\n\n```\nCharacter at index 28: c\n```\n\n\n\n### A base64 encoder {#sec-base64-encoder-algo}\n\nThe algorithm behind a base64 encoder usually works on a window of 3 bytes. Because each byte has\n8 bits, so, 3 bytes forms a set of $8 \\times 3 = 24$ bits. This is desirable for the base64 algorithm, because\n24 bits is divisible by 6, which forms $24 / 6 = 4$ groups of 6 bits each.\n\nTherefore, the base64 algorithm works by converting 3 bytes at a time\ninto 4 characters from the base64 scale. It keeps iterating through the input string,\n3 bytes at a time, and converting them into the base64 scale, producing 4 characters\nper iteration. It keeps iterating, and producing these \"new characters\"\nuntil it hits the end of the input string.\n\nNow, you may think, what if you have a particular string that have a number of bytes\nthat is not divisible by 3? What happens? For example, if you have a string\nthat contains only two characters/bytes, such as \"Hi\". How the\nalgorithm would behave in such situation? You find the answer at @fig-base64-algo1.\nYou can see at @fig-base64-algo1 that the string \"Hi\", when converted to base64,\nbecomes the string \"SGk=\":\n\n![The logic behind a base64 encoder](./../Figures/base64-encoder-flow.png){#fig-base64-algo1}\n\nTaking the string \"Hi\" as an example, we have 2 bytes, or, 16 bits in total. So, we lack a full byte (8 bits)\nto complete the window of 24 bits that the base64 algorithm likes to work on. The first thing that\nthe algorithm does, is to check how to divide the input bytes into groups of 6 bits.\n\nIf the algorithm notices that there is a group of 6 bits that, have some bits in it, but, at the same time, it is not full\n(in other words, $0 < nbits < 6$, being $nbits$ the number of bits), meaning that, it lacks\nsome bits to fill the 6-bits requirement, the algorithm simply add extra zeros in this group\nto fill the space that it needs. That is why at @fig-base64-algo1, on the third group after the 6-bit transformation,\n2 extra zeros were added to fill the gap in this group.\n\nWhen we have a 6-bit group that is not completely full, like the third group, extra zeros\nare added to fill the gap. But what about when an entire 6-bit group is empty, or, it\nsimply doesn't exist? This is the case of the fourth 6-bit group exposed at\n@fig-base64-algo1.\n\nThis fourth group is necessary, because the algorithm works on 4 groups of 6 bits.\nBut the input string does not have enough bytes to create a fourth 6-bit group.\nEvery time this happens, where an entire group of 6 bits is empty,\nthis group becomes a \"padding group\". Every \"padding group\" is mapped to\nthe character `=` (equal sign), which represents \"null\", or, the end\nof meaningful characters in the sequence. Hence, everytime that the algorithm produces a\n\"padding group\", this group is automatically mapped to `=`.\n\nAs another example, if you give the string \"0\" as input to a base64 encoder, this string is\ntranslated into the base64 sequence \"MA==\".\nThe character \"0\" is, in binary, the sequence `00110000`[^zero-note]. So, with the 6-bit transformation\nexposed at @fig-base64-algo1, this single character would produce these two 6-bit groups: `001100`, `000000`.\nThe remaining two 6-bit groups become \"padding groups\". That is why the last\ntwo characters in the output sequence (MA==) are `==`.\n\n\n[^zero-note]: Notice that, the character \"0\" is different than the actual number 0, which is simply zero in binary.\n\n### A base64 decoder {#sec-base64-decoder-algo}\n\nThe algorithm behind a base64 decoder is essentially the inverse process of a base64 encoder.\nA base64 decoder needs to translate base64 messages back into their original meaning,\ni.e. into the original sequence of binary data.\n\nA base64 decoder usually works on a window of 4 bytes. Because it wants to convert these 4 bytes\nback into the original sequence of 3 bytes, that was converted into 4 groups of 6 bits by the\nbase64 encoder. Remember, in a base64 decoder we are essentially reverting the process made\nby the base64 encoder.\n\nEach byte in the input string (the base64 encoded string) normally contributes to re-create\ntwo different bytes in the output (the original binary data).\nIn other words, each byte that comes out of a base64 decoder is created by transforming merging two different\nbytes in the input together. You can visualize this relationship at @fig-base64-algo2:\n\n![The logic behind a base64 decoder](./../Figures/base64-decoder-flow.png){#fig-base64-algo2}\n\nThe exact transformations, or, the exact steps applied to each byte from the input to transform them\ninto the bytes of the output, are a bit tricky to visualize in a figure like this. Because of that, I have\nsummarized these transformations as \"Some bit shifting and additions ...\" in the figure. These transformations\nwill be described in depth later.\n\nBesides that, if you look again at @fig-base64-algo2, you will notice that the character `=` was completely\nignored by the algorithm. Remember, this is just a special character that marks the end of meaningful characters\nin the base64 sequence. So, every `=` character in a base64 encoded sequence should be ignored by a base64 decoder.\n\n\n## Difference between encode and decode {#sec-encode-vs-decode}\n\nIf you don't have any previous experience with base64, you might not understand the differences\nbetween \"encode\" and \"decode\". Essentially, the terms \"encode\" and \"decode\" here\nhave the exact same meaning as they have in the field of encryption (i.e. they mean the same thing as \"encode\" and \"decode\" in hashing\nalgorithms, like the MD5 algorithm).\n\nThus, \"encode\" means that we want to encode, or, in other words, we want to translate some message into\nthe base64 encoding system. We want to produce the sequence of base64 characters that represent this\noriginal message in the base64 encoding system.\n\nIn contrast, \"decode\" represents the inverse process.\nWe want to decode, or, in other words, translate a base64 message back to its original content.\nSo, in this process we get a sequence of base64 characters as input, and produce as output,\nthe binary data that is represented by this sequence of base64 characters.\n\nAny base64 library is normally composed of these two parts: 1) the encoder, which is a function that encodes\n(i.e. it converts) any sequence of binary data into a sequence of base64 characters; 2) the decoder, which is a function\nthat converts a sequence of base64 characters back into the original sequence of binary data.\n\n\n\n## Calculating the size of the output {#sec-base64-length-out}\n\nOne task that we need to do is to calculate how much space we need to reserve for the\noutput, both of the encoder and decoder. This is simple math, and can be done easily in Zig\nbecause every array has its length (its number of elements) easily accesible by consulting\nthe `.len` property of the array.\n\nFor the encoder, the logic is the following: for each 3 bytes that we find in the input,\n4 new bytes are created in the output. So, we take the number of bytes in the input, divide it\nby 3, use a ceiling function, then, we multiply the result by 4. That way, we get the total\nnumber of bytes that will be produced by the encoder in its output.\n\nThe `_calc_encode_length()` function below encapsulates this logic.\nInside this function, we take the length of the input array,\nwe divide it by 3, and apply a ceil operation over the result by using the\n`divCeil()` function from the Zig Standard Library. Lastly, we multiply\nthe end result by 4 to get the answer we need.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_encode_length(input: []const u8) !usize {\n    if (input.len < 3) {\n        const n_output: usize = 4;\n        return n_output;\n    }\n    const n_output: usize = try std.math.divCeil(\n        usize, input.len, 3\n    );\n    return n_output * 4;\n}\n```\n:::\n\n\n\n\n\nAlso, you might have notice that, if the input length is less than 3 bytes, then, the output length of the encoder is\nalways 4 bytes. This is the case for every input with less than 3 bytes, because, as I described at @sec-base64-encoder-algo,\nthe algorithm always produces enough \"padding-groups\" in the end result, to complete the 4 bytes window.\n\nNow, for the decoder, we just need to apply the inverse logic: for each 4 bytes in the input, 3 bytes\nwill be produced in the output of the decoder. I mean, this is roughly true, because we also need to\ntake the `=` character into account, which is always ignored by the decoder, as we described at @sec-base64-decoder-algo, and,\nat @fig-base64-algo2. But we can ignore this fact for now, just to keep things simple.\n\nThe function `_calc_decode_length()` exposed below summarizes this logic that we described. It is very similar\nto the function `_calc_encode_length()`. Only the division part is twisted, and also, in the special\ncase where we have less than 4 bytes in the input to work on. Also notice that this time, we apply\na floor operation over the output of the division, by using the `divFloor()`\nfunction (instead of a ceiling operation with `divCeil()`).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_decode_length(input: []const u8) !usize {\n    if (input.len < 4) {\n        const n_output: usize = 3;\n        return n_output;\n    }\n    const n_output: usize = try std.math.divFloor(\n        usize, input.len, 4\n    );\n    return n_output * 3;\n}\n```\n:::\n\n\n\n\n\n## Building the encoder logic {#sec-encoder-logic}\n\nIn this section, we can start building the logic behind the `encode()` function, which\nwill be responsible for encoding messages into the base64 encoding system.\nIf you are an anxious person, and you want to see now the full source code of the implementation\nfor this base64 encoder/decoder, you can find it at the `ZigExamples` folder in the official repository of\nthis book[^zig-base64-algo].\n\n[^zig-base64-algo]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/base64/base64_basic.zig>.\n\n\n\n### The 6-bit transformation {#sec-6bit-transf}\n\nThe 6-bit transformation presented at @fig-base64-algo1 is the core part of the base64 encoder algorithm.\nBy understanding how this transformation is made in code, the rest of the algorithm becomes much simpler\nto comprehend.\n\nIn essence, this 6-bit transformation is made with the help of bitwise operators.\nBitwise operators are essential to any type of low-level operation that is done at the bit-level. For the specific case of the base64 algorithm,\nthe operators *bif shift to the left* (`<<`), *bit shift to the right* (`>>`), and the *bitwise and* (`&`) are used. They\nare the core solution for the 6-bit transformation.\n\nThere are 3 different scenarios that we need to take into account in this transformation. First, is the perfect scenario,\nwhere we have the perfect window of 3 bytes to work on. Second, we have the scenario where we have a window of only\ntwo bytes to work with. And last, we have the scenario where we have a window of one single byte.\n\nIn each of these 3 scenarios, the 6-bit transformation works a bit differently. To make the explanation\neasier, I will use the variable `output` to refer to the bytes in the output of the base64 encoder,\nand the variable `input` to refer to the bytes in the input of the encoder.\n\n\nSo, if you have the perfect window of 3 bytes, these are steps for the 6-bit transformation:\n\n1. `output[0]` is produced by moving the bits from `input[0]` two positions to the right.\n1. `output[1]` is produced by summing two components. First, take the last two bits from `input[0]`, then, move them four positions to the left. Second, move the bits from `input[1]` four positions to the right. Sum these two components.\n1. `output[2]` is produced by summing two components. First, take the last four bits from `input[1]`, then, move them two positions to the left. Second, move the bits from `input[2]` six positions to the right. Sum these two components.\n1. `output[3]` is produced by taking the last six bits from `input[2]`.\n\n\nThis is the perfect scenario, where we have a full window of 3 bytes to work on.\nJust to make things as clear as possible, the @fig-encoder-bitshift demonstrates visually how\nthe step 2 mentioned above works. So the 2nd byte in the `output` of the encoder, is made by taking the 1st byte (dark purple)\nand the 2nd byte (orange) from the input. You can see that, at the end of the process, we get a new\nbyte that contains the last 2 bits from the 1st byte in the `input`, and the first 4 bits\nfrom the 2nd byte in the `input`.\n\n![How the 2nd byte in the output of the encoder is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input.](../Figures/base64-encoder-bit-shift.png){#fig-encoder-bitshift}\n\nOn the other hand, we must be prepared for the instances where we do not have the perfect window of 3 bytes.\nIf you have a window of 2 bytes, then, the steps 3 and 4, which produces the bytes `output[2]` and `output[3]`, change a little bit,\nand they become:\n\n- `output[2]` is produced by taking the last 4 bits from `input[1]`, then, move them two positions to the left.\n- `output[3]` is the character `'='`.\n\n\nFinally, if you have a window of a single byte, then, the steps 2 to 4, which produces the bytes `output[1]`, `output[2]` and `output[3]` change,\nbecoming:\n\n- `output[1]` is produced by taking the last two bits from `input[0]`, then, move them four positions to the left.\n- `output[2]` and `output[3]` are the character `=`.\n\n\nIf these bullet points were a bit confusing for you, you may find the @tbl-transf-6bit more intuitive.\nThis table unifies all this logic into a simple table. Notice that\nthis table also provides the exact expression in Zig that creates the corresponding\nbyte in the output.\n\n\n::: {#tbl-transf-6bit}\n\n| Number of bytes in the window | Byte index in the output | In code                                    |\n|-------------------------------|--------------------------|--------------------------------------------|\n| 3                             | 0                        | input[0] >> 2                              |\n| 3                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 3                             | 2                        | ((input[1] & 0x0f) << 2) + (input[2] >> 6) |\n| 3                             | 3                        | input[2] & 0x3f                            |\n| 2                             | 0                        | input[0] >> 2                              |\n| 2                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 2                             | 2                        | ((input[1] & 0x0f) << 2)                   |\n| 2                             | 3                        | '='                                        |\n| 1                             | 0                        | input[0] >> 2                              |\n| 1                             | 1                        | ((input[0] & 0x03) << 4)                   |\n| 1                             | 2                        | '='                                        |\n| 1                             | 3                        | '='                                        |\n\n: How the 6-bit transformation translates into code in different window settings.\n\n:::\n\n\n\n\n\n\n### Bit-shifting in Zig\n\nBit-shifting in Zig works similarly to bit-shifting in C.\nAll bitwise operators that exist in C are available in Zig.\nHere, in the base64 encoder algorithm, they are essential\nto produce the result we want.\n\nFor those who are not familiar with these operators, they are\noperators that operates at the bit-level of your values.\nThis means that these operators takes the bits that form the value\nyou have, and change them in some way. This ultimately also changes\nthe value itself, because the binary representation of this value\nchanges.\n\nWe have already seen at @fig-encoder-bitshift the effect produced by a bit-shift.\nBut let's use the first byte in the output of the base64 encoder as another example of what\nbit-shifting means. This is the easiest byte of the 4 bytes in the output\nto build. Because we only need to move the bits from the first byte in the input two positions to the right,\nwith the *bit shift to the right* (`>>`) operator.\n\nIf we take the string \"Hi\" that we used at @fig-base64-algo1 as an example, the first byte in\nthis string is \"H\", which is the sequence `01001000` in binary.\nIf we move the bits of this byte, two places to the right, we get the sequence `00010010` as result.\nThis binary sequence is the value `18` in decimal, and also, the value `0x12` in hexadecimal.\nNotice that the first 6 bits of \"H\" were moved to the end of the byte.\nWith this operation, we get the first byte of the output.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const input = \"Hi\";\n    try stdout.print(\"{d}\\n\", .{input[0] >> 2});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n18\n```\n\n\n:::\n:::\n\n\n\n\nIf you recall @fig-base64-algo1, the first byte present in the output should\nbe equivalent to the 6-bit group `010010`. Although being visually different, the\nsequences `010010` and `00010010` are semantically equal. They mean the same thing.\nThey both represent the number 18 in decimal, and the value `0x12` in hexadecimal.\n\nSo, don't take the \"6-bit group\" factor so seriously. We do not need necessarily to\nget a 6-bit sequence as result. As long as the meaning of the 8-bit sequence we get is the same\nof the 6-bit sequence, we are in the clear.\n\n\n\n### Selecting specific bits with the `&` operator\n\nIf you comeback to @sec-6bit-transf, you will see that, in order to produce\nthe second and third bytes in the output, we need to select specific\nbits from the first and second bytes in the input string. But how\ncan we do that? The answer relies on the *bitwise and* (`&`) operator.\n\nThe @fig-encoder-bitshift already showed you what effect this `&` operator\nproduces in the bits of its operands. But let's make a clear description of it.\n\nIn summary, the `&` operator performs a logical conjunction operation\nbetween the bits of its operands. In more details, the operator `&`\ncompares each bit of the first operand to the corresponding bit of the second operand.\nIf both bits are 1, the corresponding result bit is set to 1.\nOtherwise, the corresponding result bit is set to 0 [@microsoftbitwiseand].\n\nSo, if we apply this operator to the binary sequences `1000100` and `00001101`\nthe result of this operation is the binary sequence `00000100`. Because only\nat the sixth position in both binary sequences we had a 1 value. So any\nposition where we do not have both binary sequences setted to 1, we get\na 0 bit in the resulting binary sequence.\n\nWe lose information about the original bit values\nfrom both sequences in this case. Because we no longer know\nif this 0 bit in the resulting binary sequence was produced by\ncombining 0 with 0, or 1 with 0, or 0 with 1.\n\nAs an example, suppose you have the binary sequence `10010111`, which is the number 151 in decimal. How\ncan we get a new binary sequence which contains only the third and\nfourth bits of this sequence?\n\nWe just need to combine this sequence with `00110000` (is `0x30` in hexadecimal) using the `&` operator.\nNotice that only the third and fourth positions in this binary sequence is setted to 1. As a consequence, only the\nthird and fourth values of both binary sequences are potentially preserved in the output. All the remaining positions\nare setted to zero in the output sequence, which is `00010000` (is the number 16 in decimal).\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const bits = 0b10010111;\n    try stdout.print(\"{d}\\n\", .{bits & 0b00110000});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n16\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Allocating space for the output\n\nAs I described at @sec-stack, to store an object in the stack,\nthis object needs to have a known and fixed length at compile-time. This is an important\nlimitation for our base64 encoder/decoder case. Because the size of\nthe output (from both the encoder and decoder) depends\ndirectly on the size of the input.\n\nHaving this in mind, we cannot know at compile time which is\nthe size of the output for both the encoder and decoder.\nSo, if we can't know the size of the output at compile time,\nthis means that we cannot store the output for both the encoder\nand decoder in the stack.\n\nConsequently, we need to store this output on the heap,\nand, as I commented at @sec-heap, we can only\nstore objects in the heap by using allocator objects.\nSo, one the arguments to both the `encode()` and `decode()`\nfunctions, needs to be an allocator object, because\nwe know for sure that, at some point inside the body of these\nfunctions, we need to allocate space on the heap to\nstore the output of these functions.\n\nThat is why, both the `encode()` and `decode()` functions that I\npresent in this book, have an argument called `allocator`,\nwhich receives a allocator object as input, identified by\nthe type `std.mem.Allocator` from the Zig Standard Library.\n\n\n\n### Writing the `encode()` function\n\nNow that we have a basic understanding on how the bitwise operators work, and how\nexactly they help us to achieve the result we want to achieve. We can now encapsulate\nall the logic that we have described at @fig-base64-algo1 and @tbl-transf-6bit into a nice\nfunction that we can add to our `Base64` struct definition, that we started at @sec-base64-table.\n\nYou can find the `encode()` function below. Notice that the first argument of this function,\nis the `Base64` struct itself. Therefore, this argument clearly signals\nthat this function is a method from the `Base64` struct.\n\nBecause the `encode()` function itself is fairly long,\nI intentionally omitted the `Base64` struct definition in this source code,\njust for brevity reasons. So, just remember that this function is a public function (or a public method) from the\n`Base64` struct.\n\nFurthermore, this `encode()` function has two other arguments:\n\n1. `input` is the input sequence of characters that you want to encode in base64;\n1. `allocator` is an allocator object to use in the necessary memory allocations.\n\nI described everything you need to know about allocator objects at @sec-allocators.\nSo, if you are not familiar with them, I highly recommend you to comeback to\nthat section, and read it.\nBy looking at the `encode()` function, you will see that we use this\nallocator object to allocate enough memory to store the output of\nthe encoding process.\n\nThe main for loop in the function is responsible for iterating through the entire input string.\nIn every iteration, we use a `count` variable to count how many iterations we had at the\nmoment. When `count` reaches 3, then, we try to encode the 3 characters (or bytes) that we have accumulated\nin the temporary buffer object (`buf`).\n\nAfter encoding these 3 characters and storing the result in the `output` variable, we reset\nthe `count` variable to zero, and start to count again on the next iteration of the loop.\nIf the loop hits the end of the string, and, the `count` variable is less than 3, then, it means that\nthe temporary buffer contains the last 1 or 2 bytes from the input.\nThat is why we have two `if` statements after the for loop. To deal which each possible case.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn encode(self: Base64,\n              allocator: std.mem.Allocator,\n              input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n\n    const n_out = try _calc_encode_length(input);\n    var out = try allocator.alloc(u8, n_out);\n    var buf = [3]u8{ 0, 0, 0 };\n    var count: u8 = 0;\n    var iout: u64 = 0;\n\n    for (input, 0..) |_, i| {\n        buf[count] = input[i];\n        count += 1;\n        if (count == 3) {\n            out[iout] = self._char_at(buf[0] >> 2);\n            out[iout + 1] = self._char_at(\n                ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n            );\n            out[iout + 2] = self._char_at(\n                ((buf[1] & 0x0f) << 2) + (buf[2] >> 6)\n            );\n            out[iout + 3] = self._char_at(buf[2] & 0x3f);\n            iout += 4;\n            count = 0;\n        }\n    }\n\n    if (count == 1) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            (buf[0] & 0x03) << 4\n        );\n        out[iout + 2] = '=';\n        out[iout + 3] = '=';\n    }\n\n    if (count == 2) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n        );\n        out[iout + 2] = self._char_at(\n            (buf[1] & 0x0f) << 2\n        );\n        out[iout + 3] = '=';\n        iout += 4;\n    }\n\n    return out;\n}\n```\n:::\n\n\n\n\n\n\n## Building the decoder logic {#sec-decoder-logic}\n\nNow, we can focus on writing the base64 decoder logic. Remember from @fig-base64-algo2 that,\na base64 decoder does the inverse process of an encoder. So, all we need to do, is to\nwrite a `decode()` function that performs the inverse process that I exposed at @sec-encoder-logic.\n\n\n### Mapping base64 characters to their indexes {#sec-map-base64-index}\n\nOne thing that we need to do, in order to decode a base64-encoded message, is to calculate\nthe index in the base64 scale of every base64 character that we encounter in the decoder input.\n\nIn other words, the decoder receives as input, a sequence of base64 characters. We need\nto translate this sequence of characters into a sequence of indexes. These indexes\nare the index of each character in the base64 scale. This way, we get the value/byte\nthat was calculated in the 6-bit transformation step of the encoder process.\n\nThere are probably better/faster ways to calculate this, especially using a \"divide and conquer\"\ntype of strategy. But for now, I am satisfied with a simple and \"brute force\" type of strategy.\nThe `_char_index()` function below contains this strategy.\n\nWe are essentially looping through the *lookup table* with the base64 scale,\nand comparing the character we got with each character in the base64 scale.\nIf these characters match, then, we return the index of this character in the\nbase64 scale as the result.\n\nNotice that, if the input character is `'='`, the function returns the index 64, which is\n\"out of range\" in the scale. But, as I described at @sec-base64-scale,\nthe character `'='` does not belong to the base64 scale itself.\nIt is a special and meaningless character in base64.\n\nAlso notice that this `_char_index()` function is a method from our `Base64` struct,\nbecause of the `self` argument. Again, I have omitted the `Base64` struct definition in this example\nfor brevity reasons.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn _char_index(self: Base64, char: u8) u8 {\n    if (char == '=')\n        return 64;\n    var index: u8 = 0;\n    for (0..63) |i| {\n        if (self._char_at(i) == char)\n            break;\n        index += 1;\n    }\n\n    return index;\n}\n```\n:::\n\n\n\n\n\n\n### The 6-bit transformation\n\nOnce again, the core part of the algorithm is the 6-bit transformation.\nIf we understand the necessary steps to perform this transformation, the rest\nof the algorithm becomes much easier.\n\nFirst of all, before we actually go to the 6-bit transformation,\nwe need to make sure that we use `_char_index()` to convert the sequence of base64 characters\ninto a sequence of indexes. So the snippet below is important for the job that will be done.\nThe result of `_char_index()` is stored in a temporary buffer, and this temporary buffer\nis what we are going to use in the 6-bit transformation, instead of the actual `input` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (0..input.len) |i| {\n    buf[i] = self._char_index(input[i]);\n}\n```\n:::\n\n\n\n\nNow, instead of producing 4 bytes (or 4 characters) as output per each window of 3 characters in the input,\na base64 decoder produces 3 bytes (or 3 characters) as output per each window of 4 characters in the input.\nOnce again, is the inverse process.\n\nSo, the steps to produce the 3 bytes in the output are:\n\n1. `output[0]` is produced by summing two components. First, move the bits from `buf[0]` two positions to the left. Second, move the bits from `buf[1]` 4 positions to the right. Then, sum these two components.\n1. `output[1]` is produced by summing two components. First, move the bits from `buf[1]` four positions to the left. Second, move the bits from `buf[2]` 2 positions to the right. Then, sum these two components.\n1. `output[2]` is produced by summing two components. First, move the bits from `buf[2]` six positions to the left. Then, you sum the result with `buf[3]`.\n\n\nBefore we continue, let's try to visualize how these transformations make the original bytes that we had\nbefore the encoding process. First, think back to the 6-bit transformation performed by the encoder exposed at @sec-encoder-logic.\nThe first byte in the output of the encoder is produced by moving the bits in the first byte of the input two positions to the right.\n\nIf for example the first byte in the input of the encoder was the sequence `ABCDEFGH`, then, the first byte in the output of the encoder would be\n`00ABCDEF` (this sequence would be the first byte in the input of the decoder). Now, if the second byte in the input of the encoder was the sequence\n`IJKLMNOP`, then, the second byte in the encoder output would be `00GHIJKL` (as we demonstrated at @fig-encoder-bitshift).\n\nHence, if the sequences `00ABCDEF` and `00GHIJKL` are the first and second bytes, respectively, in the input of the decoder, the\n@fig-decoder-bitshift demonstrates visually how these two bytes are transformed into the first byte of the output of the decoder.\nNotice that the output byte is the sequence `ABCDEFGH`, which is the original byte from the input of the encoder.\n\n![How the 1st byte in the decoder output is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input](../Figures/base64-decoder-bit-shift.png){#fig-decoder-bitshift}\n\nThe @tbl-6bit-decode presents how the three steps described earlier translate into Zig code:\n\n\n\n::: {#tbl-6bit-decode}\n\n| Byte index in the output | In code                       |\n|--------------------------|-------------------------------|\n| 0                        | (buf[0] << 2) + (buf[1] >> 4) |\n| 1                        | (buf[1] << 4) + (buf[2] >> 2) |\n| 2                        | (buf[2] << 6) + buf[3]        |\n\n: The necessary steps for the 6-transformation in the decode process.\n\n\n:::\n\n\n\n\n\n\n\n### Writing the `decode()` function\n\nThe `decode()` function below contains the entire decoding process.\nWe first calculate the size of the output, with\n`_calc_decode_length()`, then, we allocate enough memory for this output with\nthe allocator object.\n\nThree temporary variables are created: 1) `count`, to hold the window count\nin each iteration of the for loop; 2) `iout`, to hold the current index in the output;\n3) `buf`, which is the temporary buffer that holds the base64 indexes to be\nconverted through the 6-bit transformation.\n\nThen, in each iteration of the for loop we fill the temporary buffer with the current\nwindow of bytes. When `count` hits the number 4, then, we have a full window of\nindexes in `buf` to be converted, and then, we apply the 6-bit transformation\nover the temporary buffer.\n\nNotice that we check if the indexes 2 and 3 in the temporary buffer are the number 64, which, if you recall\nfrom @sec-map-base64-index, is when the `_calc_index()` function receives a `'='` character\nas input. So, if these indexes are equal to the number 64, the `decode()` function knows\nthat it can simply ignore these indexes. They are not converted because, as I described before,\nthe character `'='` has no meaning, despite being the end of meaningful characters in the sequence.\nSo we can safely ignore them when they appear in the sequence.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn decode(self: Base64,\n          allocator: std.mem.Allocator,\n          input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n    const n_output = try _calc_decode_length(input);\n    var output = try allocator.alloc(u8, n_output);\n    var count: u8 = 0;\n    var iout: u64 = 0;\n    var buf = [4]u8{ 0, 0, 0, 0 };\n\n    for (0..input.len) |i| {\n        buf[count] = self._char_index(input[i]);\n        count += 1;\n        if (count == 4) {\n            output[iout] = (buf[0] << 2) + (buf[1] >> 4);\n            if (buf[2] != 64) {\n                output[iout + 1] = (buf[1] << 4) + (buf[2] >> 2);\n            }\n            if (buf[3] != 64) {\n                output[iout + 2] = (buf[2] << 6) + buf[3];\n            }\n            iout += 3;\n            count = 0;\n        }\n    }\n\n    return output;\n}\n```\n:::\n\n\n\n\n\n## The end result\n\nNow that we have both `decode()` and `encode()` implemented. We have a fully functioning\nbase64 encoder/decoder implemented in Zig. Here is an usage example of our\n`Base64` struct with the `encode()` and `decode()` methods that we have implemented.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar memory_buffer: [1000]u8 = undefined;\nvar fba = std.heap.FixedBufferAllocator.init(\n    &memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst text = \"Testing some more stuff\";\nconst etext = \"VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=\";\nconst base64 = Base64.init();\nconst encoded_text = try base64.encode(\n    allocator, text\n);\nconst decoded_text = try base64.decode(\n    allocator, etext\n);\ntry stdout.print(\n    \"Encoded text: {s}\\n\", .{encoded_text}\n);\ntry stdout.print(\n    \"Decoded text: {s}\\n\", .{decoded_text}\n);\n```\n:::\n\n\n\n\n```\nEncoded text: VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=\nDecoded text: Testing some more stuff\n```\n\nYou can also see the full source code at once, by visiting the official repository of this book[^repo].\nMore precisely inside the `ZigExamples` folder[^zig-base64-algo].\n\n[^repo]: <https://github.com/pedropark99/zig-book>\n",
     "supporting": [
       "01-base64_files"
     ],
diff --git a/_freeze/Chapters/01-zig-weird/execute-results/html.json b/_freeze/Chapters/01-zig-weird/execute-results/html.json
index 1238c4cd..f1342fff 100644
--- a/_freeze/Chapters/01-zig-weird/execute-results/html.json
+++ b/_freeze/Chapters/01-zig-weird/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "8ffa4a01e784b723e1aaf1806367c53c",
+  "hash": "ba740c33772422f50c73c140fef90a2d",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\nlanguage, it is still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. They really make it sometimes hard to debug\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscures the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that get's compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e. it is where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contain Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nTherefore, Zig contains a native build system in it, and\nwe can use this build system to write small scripts in Zig,\nwhich describes the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e. creating new objects)\nare made in Zig. You can create a new object in Zig by using the following syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). At @sec-assignments we talk more about objects in general.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that at @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIs worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt is like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portable C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nIn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e. the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. Thus, if you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith a \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, operations like accessing the `stdout` (or opening a file) on Windows\ndepends on resources that are available only at *runtime* (you will learn more about compile-time\nversus runtime at @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword at @sec-comptime.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation at a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues \n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described in @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig later in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig? \nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar to our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentation.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It is a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (on YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e. identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nIn contrast, if you use `var`, then, the object created is a variable object.\nWith `var` you can declare this object in your source code, and then,\nchange the value of this object how many times you want over future points\nin your source code.\n\nSo, using the same code example exposed above, if I change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it is an \"variable object\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIs important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code use this object while it is uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object. \n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e. if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to a special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It is discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also get's discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e. the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\n\nIs worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array. \n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it is a slice that\naccess all elements in the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" at @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth at @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially at @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned at @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e. the start and the end of this range)\nis known at compile-time, the slice object that get's created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nat @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that get's created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e. a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can \ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n```\n:::\n\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat get's created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, the `slice` object have a runtime known range, because the end index of the range\nis not known at compile time. In other words, the size of the array at `buffer` is not known\nat compile time. When we execute this program, the size of the array might be 10, or, it might be 12\ndepending on where we execute it. Therefore, we don't know at compile time if\nthe slice object have a range of size 10, or, a range of size 12.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e. a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented at @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e. `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIs worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e. the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause it is much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e. if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it is a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIs important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig at @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers at @sec-root-file and especially at @sec-assignments.\n- How strings work in Zig at @sec-zig-strings.\n- How to use arrays and slices at @sec-arrays.\n- How to import functionality from other Zig modules at @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* at @sec-structs-and-oop.\n- Basic control flow syntax at @sec-zig-control-flow.\n- Enums at @sec-enum;\n- Pointers and Optionals at @sec-pointer;\n- Error handling with `try` and `catch` at @sec-error-handling;\n- Unit tests at @sec-unittests;\n- Vectors at @sec-vectors-simd;\n- Build System at @sec-build-system;\n\n\n\n\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\nlanguage, it is still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. They really make it sometimes hard to debug\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscure the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that get's compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e. it is where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contain Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nTherefore, Zig contains a native build system in it, and\nwe can use this build system to write small scripts in Zig,\nwhich describes the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e. creating new objects)\nare made in Zig. You can create a new object in Zig by using the following syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). At @sec-assignments we talk more about objects in general.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that at @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIs worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt is like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portable C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nIn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e. the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. Thus, if you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith a \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, operations like accessing the `stdout` (or opening a file) on Windows\ndepends on resources that are available only at *runtime* (you will learn more about compile-time\nversus runtime at @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword at @sec-comptime.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation at a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues \n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described in @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig later in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig? \nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar to our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentation.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It is a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (on YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e. identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nIn contrast, if you use `var`, then, the object created is a variable object.\nWith `var` you can declare this object in your source code, and then,\nchange the value of this object how many times you want over future points\nin your source code.\n\nSo, using the same code example exposed above, if I change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it is an \"variable object\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIs important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code use this object while it is uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object. \n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e. if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to a special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It is discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also get's discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e. the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\nIs worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array. \n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it is a slice that\naccess all elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" at @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth at @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially at @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned at @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e. the start and the end of this range)\nis known at compile-time, the slice object that get's created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nat @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that get's created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e. a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can \ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n```\n:::\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat get's created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, the `slice` object have a runtime known range, because the end index of the range\nis not known at compile time. In other words, the size of the array at `buffer` is not known\nat compile time. When we execute this program, the size of the array might be 10, or, it might be 12\ndepending on where we execute it. Therefore, we don't know at compile time if\nthe slice object have a range of size 10, or, a range of size 12.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e. a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented at @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e. `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIs worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e. the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause it is much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e. if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it is a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIs important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig at @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers at @sec-root-file and especially at @sec-assignments.\n- How strings work in Zig at @sec-zig-strings.\n- How to use arrays and slices at @sec-arrays.\n- How to import functionality from other Zig modules at @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* at @sec-structs-and-oop.\n- Basic control flow syntax at @sec-zig-control-flow.\n- Enums at @sec-enum;\n- Pointers and Optionals at @sec-pointer;\n- Error handling with `try` and `catch` at @sec-error-handling;\n- Unit tests at @sec-unittests;\n- Vectors at @sec-vectors-simd;\n- Build System at @sec-build-system;\n\n\n\n\n",
+    "supporting": [
+      "01-zig-weird_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/docs/Chapters/01-base64.html b/docs/Chapters/01-base64.html
index 36bf226d..9e6d25c9 100644
--- a/docs/Chapters/01-base64.html
+++ b/docs/Chapters/01-base64.html
@@ -894,8 +894,8 @@ <h2 data-number="4.6" class="anchored" data-anchor-id="the-end-result"><span cla
 <span id="cb14-4"><a href="#cb14-4" aria-hidden="true" tabindex="-1"></a>);</span>
 <span id="cb14-5"><a href="#cb14-5" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> allocator = fba.allocator();</span>
 <span id="cb14-6"><a href="#cb14-6" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb14-7"><a href="#cb14-7" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> text = <span class="st">"Testing some more shit"</span>;</span>
-<span id="cb14-8"><a href="#cb14-8" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> etext = <span class="st">"VGVzdGluZyBzb21lIG1vcmUgc2hpdA=="</span>;</span>
+<span id="cb14-7"><a href="#cb14-7" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> text = <span class="st">"Testing some more stuff"</span>;</span>
+<span id="cb14-8"><a href="#cb14-8" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> etext = <span class="st">"VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY="</span>;</span>
 <span id="cb14-9"><a href="#cb14-9" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> base64 = Base64.init();</span>
 <span id="cb14-10"><a href="#cb14-10" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> encoded_text = <span class="kw">try</span> base64.encode(</span>
 <span id="cb14-11"><a href="#cb14-11" aria-hidden="true" tabindex="-1"></a>    allocator, text</span>
@@ -910,8 +910,8 @@ <h2 data-number="4.6" class="anchored" data-anchor-id="the-end-result"><span cla
 <span id="cb14-20"><a href="#cb14-20" aria-hidden="true" tabindex="-1"></a>    <span class="st">"Decoded text: {s}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>decoded_text<span class="op">}</span></span>
 <span id="cb14-21"><a href="#cb14-21" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<pre><code>Encoded text: VGVzdGluZyBzb21lIG1vcmUgc2hpdA==
-Decoded text: Testing some more shit</code></pre>
+<pre><code>Encoded text: VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=
+Decoded text: Testing some more stuff</code></pre>
 <p>You can also see the full source code at once, by visiting the official repository of this book<a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a>. More precisely inside the <code>ZigExamples</code> folder<a href="#fn4" class="footnote-ref" id="fnref4" role="doc-noteref"><sup>4</sup></a>.</p>
 
 
diff --git a/docs/Chapters/01-zig-weird.html b/docs/Chapters/01-zig-weird.html
index fed40272..1f772abb 100644
--- a/docs/Chapters/01-zig-weird.html
+++ b/docs/Chapters/01-zig-weird.html
@@ -371,7 +371,7 @@ <h2 data-number="1.1" class="anchored" data-anchor-id="what-is-zig"><span class=
 <p>“Focus on debugging your application rather than debugging your programming language knowledge”.</p>
 </blockquote>
 <p>This phrase is specially true for C++ programmers. Because C++ is a gigantic language, with tons of features, and also, there are lots of different “flavors of C++”. These elements are what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction. Zig is a very simple language, more closely related to other simple languages such as C and Go.</p>
-<p>The phrase above is still important for C programmers too. Because, even C being a simple language, it is still hard sometimes to read and understand C code. For example, pre-processor macros in C are a frequent source of confusion. They really make it sometimes hard to debug C programs. Because macros are essentially a second language embedded in C that obscures your C code. With macros, you are no longer 100% sure about which pieces of the code are being sent to the compiler, i.e. they obscures the actual source code that you wrote.</p>
+<p>The phrase above is still important for C programmers too. Because, even C being a simple language, it is still hard sometimes to read and understand C code. For example, pre-processor macros in C are a frequent source of confusion. They really make it sometimes hard to debug C programs. Because macros are essentially a second language embedded in C that obscures your C code. With macros, you are no longer 100% sure about which pieces of the code are being sent to the compiler, i.e. they obscure the actual source code that you wrote.</p>
 <p>You don’t have macros in Zig. In Zig, the code you write, is the actual code that get’s compiled by the compiler. You also don’t have a hidden control flow happening behind the scenes. And, you also don’t have functions or operators from the standard library that make hidden memory allocations behind your back.</p>
 <p>By being a simpler language, Zig becomes much more clear and easier to read/write, but at the same time, it also achieves a much more robust state, with more consistent behaviour in edge situations. Once again, less is more.</p>
 </section>
diff --git a/docs/index.html b/docs/index.html
index f53295df..6bce244a 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -7,7 +7,7 @@
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 <meta name="author" content="Pedro Duarte Faria">
-<meta name="dcterms.date" content="2025-02-09">
+<meta name="dcterms.date" content="2025-02-15">
 
 <title>Introduction to Zig</title>
 <style>
@@ -287,7 +287,7 @@ <h1 class="title">Introduction to Zig</h1>
     <div>
     <div class="quarto-title-meta-heading">Published</div>
     <div class="quarto-title-meta-contents">
-      <p class="date">February 9, 2025</p>
+      <p class="date">February 15, 2025</p>
     </div>
   </div>
   
diff --git a/docs/search.json b/docs/search.json
index d9730825..c0ff4a2f 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -104,7 +104,7 @@
     "href": "Chapters/01-zig-weird.html",
     "title": "1  Introducing Zig",
     "section": "",
-    "text": "1.1 What is Zig?\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of Zig as a modern and better version of C.\nIn the author’s personal interpretation, Zig is tightly connected with “less is more”. Instead of trying to become a modern language by adding more and more features, many of the core improvements that Zig brings to the table are actually about removing annoying behaviours/features from C and C++. In other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour. As a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\nThis philosophy becomes clear with the following phrase from the official website of Zig:\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language, with tons of features, and also, there are lots of different “flavors of C++”. These elements are what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction. Zig is a very simple language, more closely related to other simple languages such as C and Go.\nThe phrase above is still important for C programmers too. Because, even C being a simple language, it is still hard sometimes to read and understand C code. For example, pre-processor macros in C are a frequent source of confusion. They really make it sometimes hard to debug C programs. Because macros are essentially a second language embedded in C that obscures your C code. With macros, you are no longer 100% sure about which pieces of the code are being sent to the compiler, i.e. they obscures the actual source code that you wrote.\nYou don’t have macros in Zig. In Zig, the code you write, is the actual code that get’s compiled by the compiler. You also don’t have a hidden control flow happening behind the scenes. And, you also don’t have functions or operators from the standard library that make hidden memory allocations behind your back.\nBy being a simpler language, Zig becomes much more clear and easier to read/write, but at the same time, it also achieves a much more robust state, with more consistent behaviour in edge situations. Once again, less is more.",
+    "text": "1.1 What is Zig?\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of Zig as a modern and better version of C.\nIn the author’s personal interpretation, Zig is tightly connected with “less is more”. Instead of trying to become a modern language by adding more and more features, many of the core improvements that Zig brings to the table are actually about removing annoying behaviours/features from C and C++. In other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour. As a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\nThis philosophy becomes clear with the following phrase from the official website of Zig:\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language, with tons of features, and also, there are lots of different “flavors of C++”. These elements are what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction. Zig is a very simple language, more closely related to other simple languages such as C and Go.\nThe phrase above is still important for C programmers too. Because, even C being a simple language, it is still hard sometimes to read and understand C code. For example, pre-processor macros in C are a frequent source of confusion. They really make it sometimes hard to debug C programs. Because macros are essentially a second language embedded in C that obscures your C code. With macros, you are no longer 100% sure about which pieces of the code are being sent to the compiler, i.e. they obscure the actual source code that you wrote.\nYou don’t have macros in Zig. In Zig, the code you write, is the actual code that get’s compiled by the compiler. You also don’t have a hidden control flow happening behind the scenes. And, you also don’t have functions or operators from the standard library that make hidden memory allocations behind your back.\nBy being a simpler language, Zig becomes much more clear and easier to read/write, but at the same time, it also achieves a much more robust state, with more consistent behaviour in edge situations. Once again, less is more.",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -414,7 +414,7 @@
     "href": "Chapters/01-base64.html#the-end-result",
     "title": "4  Project 1 - Building a base64 encoder/decoder",
     "section": "4.6 The end result",
-    "text": "4.6 The end result\nNow that we have both decode() and encode() implemented. We have a fully functioning base64 encoder/decoder implemented in Zig. Here is an usage example of our Base64 struct with the encode() and decode() methods that we have implemented.\n\nvar memory_buffer: [1000]u8 = undefined;\nvar fba = std.heap.FixedBufferAllocator.init(\n    &memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst text = \"Testing some more shit\";\nconst etext = \"VGVzdGluZyBzb21lIG1vcmUgc2hpdA==\";\nconst base64 = Base64.init();\nconst encoded_text = try base64.encode(\n    allocator, text\n);\nconst decoded_text = try base64.decode(\n    allocator, etext\n);\ntry stdout.print(\n    \"Encoded text: {s}\\n\", .{encoded_text}\n);\ntry stdout.print(\n    \"Decoded text: {s}\\n\", .{decoded_text}\n);\n\nEncoded text: VGVzdGluZyBzb21lIG1vcmUgc2hpdA==\nDecoded text: Testing some more shit\nYou can also see the full source code at once, by visiting the official repository of this book3. More precisely inside the ZigExamples folder4.\n\n\n\n\nMicrosoft. 2021. “Bitwise AND Operator: &.” Microsoft Learn. https://learn.microsoft.com/en-us/cpp/cpp/bitwise-and-operator-amp?view=msvc-170.",
+    "text": "4.6 The end result\nNow that we have both decode() and encode() implemented. We have a fully functioning base64 encoder/decoder implemented in Zig. Here is an usage example of our Base64 struct with the encode() and decode() methods that we have implemented.\n\nvar memory_buffer: [1000]u8 = undefined;\nvar fba = std.heap.FixedBufferAllocator.init(\n    &memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst text = \"Testing some more stuff\";\nconst etext = \"VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=\";\nconst base64 = Base64.init();\nconst encoded_text = try base64.encode(\n    allocator, text\n);\nconst decoded_text = try base64.decode(\n    allocator, etext\n);\ntry stdout.print(\n    \"Encoded text: {s}\\n\", .{encoded_text}\n);\ntry stdout.print(\n    \"Decoded text: {s}\\n\", .{decoded_text}\n);\n\nEncoded text: VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=\nDecoded text: Testing some more stuff\nYou can also see the full source code at once, by visiting the official repository of this book3. More precisely inside the ZigExamples folder4.\n\n\n\n\nMicrosoft. 2021. “Bitwise AND Operator: &.” Microsoft Learn. https://learn.microsoft.com/en-us/cpp/cpp/bitwise-and-operator-amp?view=msvc-170.",
     "crumbs": [
       "<span class='chapter-number'>4</span>  <span class='chapter-title'>Project 1 - Building a base64 encoder/decoder</span>"
     ]

From eb100894be31b9df93fbe71731607d50f310adb3 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sat, 15 Feb 2025 20:19:54 -0300
Subject: [PATCH 068/151] Update contributors

---
 _freeze/index/execute-results/html.json | 2 +-
 contributors.txt                        | 2 ++
 docs/index.html                         | 2 +-
 docs/search.json                        | 2 +-
 4 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/_freeze/index/execute-results/html.json b/_freeze/index/execute-results/html.json
index d4a35b63..1ab70c08 100644
--- a/_freeze/index/execute-results/html.json
+++ b/_freeze/index/execute-results/html.json
@@ -2,7 +2,7 @@
   "hash": "7eedbe34469c0f2c200651bc420da095",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy an eBook or a physical copy\nof the book on Amazon:\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e. it is open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.\nCurrently, he is a Data Platform Engineer at [Blip](https://www.blip.ai/en/)[^blip], and\na Databricks Certified Associate Developer for Apache Spark 3.0.\n\n[^blip]: <https://www.blip.ai/en/>\n\n\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nBrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer who loves to learn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2024 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n\n- System version: Linux, 6.8.0-52-generic, NA, x86_64.\n- Zig version: 0.14.0-dev.3046+08d661fcf.\n- Quarto version: 1.5.57.\n\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang), Tommaso Ricci (\\@Zorgatone), Primo Sabatini (\\@primos63), Santiago Fernandez (\\@santif), Hamza Wahed (\\@HamzaWahed), mwilbur (\\@mwilbur), Dima Budaragin (\\@dbud), Jorge Jímenez (\\@jorge-j1m), Alexander (\\@alexwheezy)\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy an eBook or a physical copy\nof the book on Amazon:\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e. it is open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.\nCurrently, he is a Data Platform Engineer at [Blip](https://www.blip.ai/en/)[^blip], and\na Databricks Certified Associate Developer for Apache Spark 3.0.\n\n[^blip]: <https://www.blip.ai/en/>\n\n\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nBrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer who loves to learn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2024 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n\n- System version: Linux, 6.8.0-52-generic, NA, x86_64.\n- Zig version: 0.14.0-dev.3046+08d661fcf.\n- Quarto version: 1.5.57.\n\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang), Tommaso Ricci (\\@Zorgatone), Primo Sabatini (\\@primos63), Santiago Fernandez (\\@santif), Hamza Wahed (\\@HamzaWahed), mwilbur (\\@mwilbur), Dima Budaragin (\\@dbud), Jorge Jímenez (\\@jorge-j1m), Alexander (\\@alexwheezy), Maarten Coopens (\\@maarteNNNN), Niklas Johansson (\\@Raphexion)\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
diff --git a/contributors.txt b/contributors.txt
index 80300af6..d3b64d0c 100644
--- a/contributors.txt
+++ b/contributors.txt
@@ -20,3 +20,5 @@ mwilbur,@mwilbur
 Dima Budaragin,@dbud
 Jorge Jímenez,@jorge-j1m
 Alexander,@alexwheezy
+Maarten Coopens,@maarteNNNN
+Niklas Johansson,@Raphexion
diff --git a/docs/index.html b/docs/index.html
index 6bce244a..a51518de 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -439,7 +439,7 @@ <h2 class="unnumbered anchored" data-anchor-id="corresponding-author-and-maintai
 <section id="acknowledgments" class="level2 unnumbered">
 <h2 class="unnumbered anchored" data-anchor-id="acknowledgments">Acknowledgments</h2>
 <p>This book is also a product of many conversations and exchanges that we had with different people from the Zig community. I (Pedro Duarte Faria) am incredibly grateful for these conversations, and also, for some direct contributions that we had. Below we have a list of the people involved (name of the person with their usename in GitHub):</p>
-<p>Calin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang), Tommaso Ricci (@Zorgatone), Primo Sabatini (@primos63), Santiago Fernandez (@santif), Hamza Wahed (@HamzaWahed), mwilbur (@mwilbur), Dima Budaragin (@dbud), Jorge Jímenez (@jorge-j1m), Alexander (@alexwheezy)</p>
+<p>Calin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang), Tommaso Ricci (@Zorgatone), Primo Sabatini (@primos63), Santiago Fernandez (@santif), Hamza Wahed (@HamzaWahed), mwilbur (@mwilbur), Dima Budaragin (@dbud), Jorge Jímenez (@jorge-j1m), Alexander (@alexwheezy), Maarten Coopens (@maarteNNNN), Niklas Johansson (@Raphexion)</p>
 
 
 </section>
diff --git a/docs/search.json b/docs/search.json
index c0ff4a2f..80f3c7a2 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -84,7 +84,7 @@
     "href": "index.html#acknowledgments",
     "title": "Introduction to Zig",
     "section": "Acknowledgments",
-    "text": "Acknowledgments\nThis book is also a product of many conversations and exchanges that we had with different people from the Zig community. I (Pedro Duarte Faria) am incredibly grateful for these conversations, and also, for some direct contributions that we had. Below we have a list of the people involved (name of the person with their usename in GitHub):\nCalin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang), Tommaso Ricci (@Zorgatone), Primo Sabatini (@primos63), Santiago Fernandez (@santif), Hamza Wahed (@HamzaWahed), mwilbur (@mwilbur), Dima Budaragin (@dbud), Jorge Jímenez (@jorge-j1m), Alexander (@alexwheezy)",
+    "text": "Acknowledgments\nThis book is also a product of many conversations and exchanges that we had with different people from the Zig community. I (Pedro Duarte Faria) am incredibly grateful for these conversations, and also, for some direct contributions that we had. Below we have a list of the people involved (name of the person with their usename in GitHub):\nCalin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang), Tommaso Ricci (@Zorgatone), Primo Sabatini (@primos63), Santiago Fernandez (@santif), Hamza Wahed (@HamzaWahed), mwilbur (@mwilbur), Dima Budaragin (@dbud), Jorge Jímenez (@jorge-j1m), Alexander (@alexwheezy), Maarten Coopens (@maarteNNNN), Niklas Johansson (@Raphexion)",
     "crumbs": [
       "Welcome"
     ]

From 5fe95a7450fc424adfe786fea80de53de8de160b Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sun, 16 Feb 2025 17:14:19 -0300
Subject: [PATCH 069/151] Add leanpub link

---
 Assets/leanpub-button.html              |  21 +++++++++++++++
 Cover/cover-art.svg                     |  25 +++++++++---------
 Cover/cover-artv4.png                   | Bin 0 -> 577665 bytes
 README.md                               |   7 ++---
 _freeze/index/execute-results/html.json |   8 +++---
 _quarto.yml                             |   3 ++-
 docs/Cover/cover-artv3.png              | Bin 1030663 -> 0 bytes
 docs/Cover/cover-artv4.png              | Bin 0 -> 577665 bytes
 docs/index.html                         |  33 +++++++++++++++++-------
 docs/search.json                        |   6 ++---
 index.qmd                               |  17 +++++++-----
 11 files changed, 81 insertions(+), 39 deletions(-)
 create mode 100644 Assets/leanpub-button.html
 create mode 100644 Cover/cover-artv4.png
 delete mode 100644 docs/Cover/cover-artv3.png
 create mode 100644 docs/Cover/cover-artv4.png

diff --git a/Assets/leanpub-button.html b/Assets/leanpub-button.html
new file mode 100644
index 00000000..c063da7f
--- /dev/null
+++ b/Assets/leanpub-button.html
@@ -0,0 +1,21 @@
+<style>
+  .btn {
+    border-radius: 5px;
+    background-color: #4f73e8;
+    border: #4f73e8;
+    opacity: 1;
+    transition: 0.3s;
+  }
+
+  .btn:hover {
+    background-color: #2144b6;
+    border: #2144b6;
+  }
+</style>
+
+
+<a href="https://leanpub.com/introductiontozigaproject-basedbook">
+    <button class="btn btn-primary" type="button">
+	Buy the book on Leanpub!
+    </button>
+</a>
diff --git a/Cover/cover-art.svg b/Cover/cover-art.svg
index a91b5b5b..100bfc3e 100644
--- a/Cover/cover-art.svg
+++ b/Cover/cover-art.svg
@@ -27,9 +27,9 @@
      inkscape:pagecheckerboard="0"
      inkscape:deskcolor="#d1d1d1"
      inkscape:document-units="mm"
-     inkscape:zoom="0.5"
-     inkscape:cx="491"
-     inkscape:cy="366"
+     inkscape:zoom="0.70710678"
+     inkscape:cx="388.20162"
+     inkscape:cy="524.67323"
      inkscape:window-width="1920"
      inkscape:window-height="1011"
      inkscape:window-x="0"
@@ -268,13 +268,13 @@
        sodipodi:insensitive="true"><tspan
          x="65.783203"
          y="1022.7852"
-         id="tspan11"><tspan
+         id="tspan3"><tspan
            dx="0 0 0 0 0 0 0 0 0 0 0 0 2.9999924 -3 0 3"
            style="font-weight:bold;-inkscape-font-specification:'EB Garamond Bold'"
-           id="tspan9">Introduction to </tspan><tspan
+           id="tspan1">Introduction to </tspan><tspan
            dx="-3"
            style="font-weight:bold;-inkscape-font-specification:'EB Garamond Bold';fill:#f76c49"
-           id="tspan10">Zig</tspan></tspan></text><text
+           id="tspan2">Zig</tspan></tspan></text><text
        xml:space="preserve"
        transform="matrix(0.26458333,0,0,0.26458333,-7.1052353,-15.90338)"
        id="text3"
@@ -283,7 +283,7 @@
        sodipodi:insensitive="true"><tspan
          x="106.14844"
          y="233.97399"
-         id="tspan12">a project-based book</tspan></text><text
+         id="tspan4">a project-based book</tspan></text><text
        xml:space="preserve"
        transform="matrix(0.26458333,0,0,0.26458333,3.2970976,-29.259623)"
        id="text1"
@@ -292,20 +292,19 @@
        sodipodi:insensitive="true"><tspan
          x="65.783203"
          y="992.89696"
-         id="tspan14"><tspan
+         id="tspan6"><tspan
            style="font-family:'Roboto Condensed';-inkscape-font-specification:'Roboto Condensed, '"
-           id="tspan13">PEDRO DUARTE FARIA</tspan></tspan></text><text
+           id="tspan5">PEDRO DUARTE FARIA</tspan></tspan></text><text
        xml:space="preserve"
        transform="matrix(0.26458333,0,0,0.26458333,3.0998276,-39.170904)"
        id="text1-3"
        style="font-size:32px;line-height:normal;font-family:'EB Garamond';-inkscape-font-specification:'EB Garamond, Normal';text-decoration-color:#000000;word-spacing:0px;white-space:pre;shape-inside:url(#rect1-0-5);display:inline;fill:#6eb095;fill-opacity:1;stroke:#ffffff;stroke-width:0;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1"
-       inkscape:label="edition"
-       sodipodi:insensitive="true"><tspan
+       inkscape:label="edition"><tspan
          x="65.783203"
          y="997.67905"
-         id="tspan16"><tspan
+         id="tspan8"><tspan
            style="font-family:'Roboto Condensed';-inkscape-font-specification:'Roboto Condensed, '"
-           id="tspan15">1st. edition</tspan></tspan></text><g
+           id="tspan7">2nd. edition</tspan></tspan></text><g
        id="g5"
        inkscape:label="arte"
        clip-path="url(#clipPath6)"><image
diff --git a/Cover/cover-artv4.png b/Cover/cover-artv4.png
new file mode 100644
index 0000000000000000000000000000000000000000..fd19809a8a6abb36015fbeba00bb46bd5338d7e1
GIT binary patch
literal 577665
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

literal 0
HcmV?d00001

diff --git a/README.md b/README.md
index 6fcfbd62..cf953f91 100644
--- a/README.md
+++ b/README.md
@@ -13,10 +13,11 @@ the Zig compiler to compile and run the Zig code examples.
 
 ## Support the project!
 
-If you like this project, and you want to support it, you can buy an eBook or a physical copy
-of the book on Amazon:
+If you like this project, and you want to support it, you can buy a PDF, eBook or a physical copy
+of the book, either at Amazon, or at Leanpub:
 
-<https://www.amazon.com/dp/B0DJYMDRLP>
+- Amazon: <https://www.amazon.com/dp/B0DJYMDRLP>
+- Leanpub: <https://leanpub.com/introductiontozigaproject-basedbook>
 
 ### Sending donations directly
 
diff --git a/_freeze/index/execute-results/html.json b/_freeze/index/execute-results/html.json
index 1ab70c08..94307194 100644
--- a/_freeze/index/execute-results/html.json
+++ b/_freeze/index/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "7eedbe34469c0f2c200651bc420da095",
+  "hash": "9747d27d8e8f5fadf3da395f3899d9d8",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy an eBook or a physical copy\nof the book on Amazon:\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e. it is open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.\nCurrently, he is a Data Platform Engineer at [Blip](https://www.blip.ai/en/)[^blip], and\na Databricks Certified Associate Developer for Apache Spark 3.0.\n\n[^blip]: <https://www.blip.ai/en/>\n\n\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nBrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer who loves to learn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2024 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n\n- System version: Linux, 6.8.0-52-generic, NA, x86_64.\n- Zig version: 0.14.0-dev.3046+08d661fcf.\n- Quarto version: 1.5.57.\n\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang), Tommaso Ricci (\\@Zorgatone), Primo Sabatini (\\@primos63), Santiago Fernandez (\\@santif), Hamza Wahed (\\@HamzaWahed), mwilbur (\\@mwilbur), Dima Budaragin (\\@dbud), Jorge Jímenez (\\@jorge-j1m), Alexander (\\@alexwheezy), Maarten Coopens (\\@maarteNNNN), Niklas Johansson (\\@Raphexion)\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy a PDF, eBook or a physical copy\nof the book, either at Amazon, or at Leanpub:\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://leanpub.com/introductiontozigaproject-basedbook\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Leanpub!\n    </button>\n</a>\n\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e. it is open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.\nCurrently, he is a Data Platform Engineer at [Blip](https://www.blip.ai/en/)[^blip], and\na Databricks Certified Associate Developer for Apache Spark 3.0.\n\n[^blip]: <https://www.blip.ai/en/>\n\n\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nBrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer who loves to learn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2025 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n\n- System version: Linux, 6.8.0-52-generic, NA, x86_64.\n- Zig version: 0.14.0-dev.3046+08d661fcf.\n- Quarto version: 1.5.57.\n\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2025,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {February},\n    edition = {2},\n    year = {2025},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang), Tommaso Ricci (\\@Zorgatone), Primo Sabatini (\\@primos63), Santiago Fernandez (\\@santif), Hamza Wahed (\\@HamzaWahed), mwilbur (\\@mwilbur), Dima Budaragin (\\@dbud), Jorge Jímenez (\\@jorge-j1m), Alexander (\\@alexwheezy), Maarten Coopens (\\@maarteNNNN), Niklas Johansson (\\@Raphexion)\n",
+    "supporting": [
+      "index_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_quarto.yml b/_quarto.yml
index 64a60b8d..b3066403 100644
--- a/_quarto.yml
+++ b/_quarto.yml
@@ -6,9 +6,10 @@ book:
   title: "Introduction to Zig"
   subtitle: "a project-based book"
   author: "Pedro Duarte Faria"
+  edition: 2
   date: "today"
   google-analytics: "G-6CHJXK4CEV"
-  cover-image: "Cover/cover-artv3.png"
+  cover-image: "Cover/cover-artv4.png"
   chapters:
     - index.qmd
     - Chapters/01-zig-weird.qmd
diff --git a/docs/Cover/cover-artv3.png b/docs/Cover/cover-artv3.png
deleted file mode 100644
index c9f280288cc1592df80159b50c7a6bca22f2131b..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 1030663
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%0DD$AQOn=>-gMg;D5ctO$bz%f<2#2`-aGnVzpn#
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%0DAR@qKS#7Q3ov$z))c
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%0DrybHM`B+VS!
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
W#OhKOtH+e5tf8WNv*d=|!~X|Wi-rsU

diff --git a/docs/Cover/cover-artv4.png b/docs/Cover/cover-artv4.png
new file mode 100644
index 0000000000000000000000000000000000000000..fd19809a8a6abb36015fbeba00bb46bd5338d7e1
GIT binary patch
literal 577665
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

literal 0
HcmV?d00001

diff --git a/docs/index.html b/docs/index.html
index a51518de..1a7ce185 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -7,7 +7,7 @@
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 <meta name="author" content="Pedro Duarte Faria">
-<meta name="dcterms.date" content="2025-02-15">
+<meta name="dcterms.date" content="2025-02-16">
 
 <title>Introduction to Zig</title>
 <style>
@@ -287,7 +287,7 @@ <h1 class="title">Introduction to Zig</h1>
     <div>
     <div class="quarto-title-meta-heading">Published</div>
     <div class="quarto-title-meta-contents">
-      <p class="date">February 15, 2025</p>
+      <p class="date">February 16, 2025</p>
     </div>
   </div>
   
@@ -301,11 +301,11 @@ <h1 class="title">Introduction to Zig</h1>
 
 
 <section id="welcome" class="level1 unnumbered">
-<h1 class="unnumbered">Welcome</h1><p><img src="Cover/cover-artv3.png" title="Introduction to Zig" class="quarto-cover-image img-fluid"></p>
+<h1 class="unnumbered">Welcome</h1><p><img src="Cover/cover-artv4.png" title="Introduction to Zig" class="quarto-cover-image img-fluid"></p>
 <p>Welcome! This is the initial page for the “Open Access” HTML version of the book “Introduction to Zig: a project-based book”, written by <a href="https://pedro-faria.netlify.app/">Pedro Duarte Faria</a>. This is an open book that provides an introduction to the <a href="https://ziglang.org/">Zig programming language</a>, which is a new general-purpose, and low-level language for building robust and optimal software.</p>
 <section id="support-the-project" class="level2 unnumbered">
 <h2 class="unnumbered anchored" data-anchor-id="support-the-project">Support the project!</h2>
-<p>If you like this project, and you want to support it, you can buy an eBook or a physical copy of the book on Amazon:</p>
+<p>If you like this project, and you want to support it, you can buy a PDF, eBook or a physical copy of the book, either at Amazon, or at Leanpub:</p>
 <style>
   .btn {
     border-radius: 5px;
@@ -321,6 +321,21 @@ <h2 class="unnumbered anchored" data-anchor-id="support-the-project">Support the
   }
 </style>
 <p><a href="https://www.amazon.com/dp/B0DJYMDRLP"> <button class="btn btn-primary" type="button"> Buy the book on Amazon! </button> </a></p>
+<style>
+  .btn {
+    border-radius: 5px;
+    background-color: #4f73e8;
+    border: #4f73e8;
+    opacity: 1;
+    transition: 0.3s;
+  }
+
+  .btn:hover {
+    background-color: #2144b6;
+    border: #2144b6;
+  }
+</style>
+<p><a href="https://leanpub.com/introductiontozigaproject-basedbook"> <button class="btn btn-primary" type="button"> Buy the book on Leanpub! </button> </a></p>
 <section id="sending-donations-directly" class="level3">
 <h3 class="anchored" data-anchor-id="sending-donations-directly">Sending donations directly</h3>
 <p>You can also donate some amount directly to the author of the project via:</p>
@@ -404,7 +419,7 @@ <h2 class="unnumbered anchored" data-anchor-id="about-the-author">About the auth
 </section>
 <section id="license" class="level2 unnumbered">
 <h2 class="unnumbered anchored" data-anchor-id="license">License</h2>
-<p>Copyright © 2024 Pedro Duarte Faria. This book is licensed by the <a href="https://creativecommons.org/licenses/by/4.0/">CC-BY 4.0 Creative Commons Attribution 4.0 International Public License</a><a href="#fn4" class="footnote-ref" id="fnref4" role="doc-noteref"><sup>4</sup></a>.</p>
+<p>Copyright © 2025 Pedro Duarte Faria. This book is licensed by the <a href="https://creativecommons.org/licenses/by/4.0/">CC-BY 4.0 Creative Commons Attribution 4.0 International Public License</a><a href="#fn4" class="footnote-ref" id="fnref4" role="doc-noteref"><sup>4</sup></a>.</p>
 <p><img src="Figures/creative-commoms-88x31.png" class="img-fluid" width="88"></p>
 </section>
 <section id="book-compilation-metadata" class="level2 unnumbered">
@@ -419,13 +434,13 @@ <h2 class="unnumbered anchored" data-anchor-id="book-compilation-metadata">Book
 <section id="book-citation" class="level2 unnumbered">
 <h2 class="unnumbered anchored" data-anchor-id="book-citation">Book citation</h2>
 <p>You can use the following BibTex entry to cite this book:</p>
-<pre><code>@book{pedro2024,
+<pre><code>@book{pedro2025,
     author = {Pedro Duarte Faria},
     title = {Introduction to Zig},
     subtitle = {a project-based book},
-    month = {October},
-    edition = {1},
-    year = {2024},
+    month = {February},
+    edition = {2},
+    year = {2025},
     address = {Belo Horizonte},
     url = {https://github.com/pedropark99/zig-book}
 }</code></pre>
diff --git a/docs/search.json b/docs/search.json
index 80f3c7a2..a0dbe2a7 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -14,7 +14,7 @@
     "href": "index.html#support-the-project",
     "title": "Introduction to Zig",
     "section": "Support the project!",
-    "text": "Support the project!\nIf you like this project, and you want to support it, you can buy an eBook or a physical copy of the book on Amazon:\n\n  Buy the book on Amazon!  \n\nSending donations directly\nYou can also donate some amount directly to the author of the project via:\n\nPayPal Donation.\nRevolut.\n\nThese are good ways to support directly the author of the project, which helps to foster more contents like this, and it makes possible for the author to keep writing helpful tools and materials for the community.\n\n\nPayPal\n\n  Donate via PayPal 💵  \n\n\nRevolut\nYou can send money via Swift Payment with the following bank and Swift details:\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\nIf you do have a Revolut account, you can scan the following QR code:\n\n  Revolut QR Code 💵",
+    "text": "Support the project!\nIf you like this project, and you want to support it, you can buy a PDF, eBook or a physical copy of the book, either at Amazon, or at Leanpub:\n\n  Buy the book on Amazon!  \n\n  Buy the book on Leanpub!  \n\nSending donations directly\nYou can also donate some amount directly to the author of the project via:\n\nPayPal Donation.\nRevolut.\n\nThese are good ways to support directly the author of the project, which helps to foster more contents like this, and it makes possible for the author to keep writing helpful tools and materials for the community.\n\n\nPayPal\n\n  Donate via PayPal 💵  \n\n\nRevolut\nYou can send money via Swift Payment with the following bank and Swift details:\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\nIf you do have a Revolut account, you can scan the following QR code:\n\n  Revolut QR Code 💵",
     "crumbs": [
       "Welcome"
     ]
@@ -44,7 +44,7 @@
     "href": "index.html#license",
     "title": "Introduction to Zig",
     "section": "License",
-    "text": "License\nCopyright © 2024 Pedro Duarte Faria. This book is licensed by the CC-BY 4.0 Creative Commons Attribution 4.0 International Public License4.",
+    "text": "License\nCopyright © 2025 Pedro Duarte Faria. This book is licensed by the CC-BY 4.0 Creative Commons Attribution 4.0 International Public License4.",
     "crumbs": [
       "Welcome"
     ]
@@ -64,7 +64,7 @@
     "href": "index.html#book-citation",
     "title": "Introduction to Zig",
     "section": "Book citation",
-    "text": "Book citation\nYou can use the following BibTex entry to cite this book:\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}",
+    "text": "Book citation\nYou can use the following BibTex entry to cite this book:\n@book{pedro2025,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {February},\n    edition = {2},\n    year = {2025},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}",
     "crumbs": [
       "Welcome"
     ]
diff --git a/index.qmd b/index.qmd
index 3a98532b..cbe7ef75 100644
--- a/index.qmd
+++ b/index.qmd
@@ -26,11 +26,14 @@ which is a new general-purpose, and low-level language for building robust and o
 
 ## Support the project! {.unnumbered}
 
-If you like this project, and you want to support it, you can buy an eBook or a physical copy
-of the book on Amazon:
+If you like this project, and you want to support it, you can buy a PDF, eBook or a physical copy
+of the book, either at Amazon, or at Leanpub:
 
 {{< include ./Assets/button.html >}}
 
+{{< include ./Assets/leanpub-button.html >}}
+
+
 ### Sending donations directly
 
 You can also donate some amount directly to the author of the project via:
@@ -118,7 +121,7 @@ Twitter (X): [\@PedroPark9](https://twitter.com/PedroPark9)
 
 ## License {.unnumbered}
 
-Copyright © 2024 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].
+Copyright © 2025 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].
 
 [^cc-license]: <https://creativecommons.org/licenses/by/4.0/>
 
@@ -140,13 +143,13 @@ source("./Scripts/zig-quarto-versions.R")
 You can use the following BibTex entry to cite this book:
 
 ```
-@book{pedro2024,
+@book{pedro2025,
     author = {Pedro Duarte Faria},
     title = {Introduction to Zig},
     subtitle = {a project-based book},
-    month = {October},
-    edition = {1},
-    year = {2024},
+    month = {February},
+    edition = {2},
+    year = {2025},
     address = {Belo Horizonte},
     url = {https://github.com/pedropark99/zig-book}
 }

From e91a2de7a7eb7293940e50b466ca239ab49aa683 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sun, 16 Feb 2025 17:48:26 -0300
Subject: [PATCH 070/151] Recompile entire book

---
 Cover/cover-artv4.jpg                          | Bin 0 -> 513494 bytes
 .../01-base64/execute-results/html.json        |   4 +---
 .../01-zig-weird/execute-results/html.json     |   4 +---
 .../03-structs/execute-results/html.json       |   6 ++----
 .../03-unittests/execute-results/html.json     |   6 ++----
 .../05-pointers/execute-results/html.json      |   2 +-
 .../07-build-system/execute-results/html.json  |   4 +---
 .../execute-results/html.json                  |   4 +---
 .../execute-results/html.json                  |   2 +-
 .../10-stack-project/execute-results/html.json |   6 ++----
 .../12-file-op/execute-results/html.json       |   4 +---
 _freeze/index/execute-results/html.json        |   4 +---
 docs/Chapters/03-structs.html                  |   7 ++++---
 docs/Chapters/03-unittests.html                |   8 ++++----
 docs/Chapters/09-error-handling.html           |   2 +-
 docs/Chapters/10-stack-project.html            |  12 ++++++------
 docs/search.json                               |  12 ++++++------
 17 files changed, 35 insertions(+), 52 deletions(-)
 create mode 100644 Cover/cover-artv4.jpg

diff --git a/Cover/cover-artv4.jpg b/Cover/cover-artv4.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..4754914c2b1c855b08ea5e375a5421d3203c8af4
GIT binary patch
literal 513494
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%0A0BzUR;*!
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%0AUm2Y7|H;_)#!w{nctn0T<<-J}
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

literal 0
HcmV?d00001

diff --git a/_freeze/Chapters/01-base64/execute-results/html.json b/_freeze/Chapters/01-base64/execute-results/html.json
index 9eb2b631..7a805424 100644
--- a/_freeze/Chapters/01-base64/execute-results/html.json
+++ b/_freeze/Chapters/01-base64/execute-results/html.json
@@ -3,9 +3,7 @@
   "result": {
     "engine": "knitr",
     "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 1 - Building a base64 encoder/decoder {#sec-base64}\n\nAs our first small project, I want to implement a base64 encoder/decoder with you.\nBase64 is an encoding system which translates binary data to text.\nA big chunk of the web uses base64 to deliver binary data to systems\nthat can only read text data.\n\nThe most common example of a modern use case for base64 is essentially any email system,\nlike GMail, Outlook, etc. Because email systems normally use\nthe Simple Mail Transfer Protocol (SMTP), which is a web protocol\nthat supports only text data. So, if you need, for any reason, to\nsend a binary file (like for example, a PDF, or an Excel file) as\nan attachment in your email, these binary files are normally\nconverted to base64, before they are included in the SMTP message.\nSo, the base64 encoding is largely used in these email systems to include\nbinary data into the SMTP message.\n\n\n\n\n\n\n## How the base64 algorithm work?\n\nBut how exactly does the algorithm behind the base64 encoding work? Let's discuss that. First, I will\nexplain the base64 scale, which is the 64-character scale that is the basis for\nthe base64 encoding system.\n\nAfter that, I explain the algorithm behind a base64 encoder, which is the part of the algorithm that is responsible for encoding messages\ninto the base64 encoding system. Then, after that, I explain the algorithm behind a base64 decoder, which is\nthe part of the algorithm that is responsible for translating base64 messages back into their original meaning.\n\nIf you are unsure about the differences between an \"encoder\" and a \"decoder\",\ntake a look at @sec-encode-vs-decode.\n\n\n### The base64 scale {#sec-base64-scale}\n\nThe base64 encoding system is based on a scale that goes from 0 to 63 (hence the name).\nEach index in this scale is represented by a character (it is a scale of 64 characters).\nSo, in order to convert some binary data, to the base64 encoding, we need to convert each binary number to the corresponding\ncharacter in this \"scale of 64 characters\".\n\nThe base64 scale starts with all ASCII uppercase letters (A to Z) which represents\nthe first 25 indexes in this scale (0 to 25). After that, we have all ASCII lowercase letters\n(a to z), which represents the range 26 to 51 in the scale. After that, we\nhave the one digit numbers (0 to 9), which represents the indexes from 52 to 61 in the scale.\nFinally, the last two indexes in the scale (62 and 63) are represented by the characters `+` and `/`,\nrespectively.\n\nThese are the 64 characters that compose the base64 scale. The equal sign character (`=`) is not part of the scale itself,\nbut it is a special character in the base64 encoding system. This character is used solely as a suffix, to mark the end of the character sequence,\nor, to mark the end of meaningful characters in the sequence.\n\nThe bullet points below summarises the base64 scale:\n\n- range 0 to 25 is represented by: ASCII uppercase letters `-> [A-Z]`;\n- range 26 to 51 is represented by: ASCII lowercase letters `-> [a-z]`;\n- range 52 to 61 is represented by: one digit numbers `-> [0-9]`;\n- index 62 and 63 are represented by the characters `+` and `/`, respectively;\n- the character `=` represents the end of meaningful characters in the sequence;\n\n\n\n\n### Creating the scale as a lookup table {#sec-base64-table}\n\nThe best way to represent this scale in code, is to represent it as a *lookup table*.\nLookup tables are a classic strategy in computer science to speed up calculations. The basic idea\nis to replace a runtime calculation (which can take a long time to be done) with a basic array indexing\noperation.\n\nInstead of calculating the results everytime you need them, you calculate all possible results at once, and then, you store them in an array\n(which behaves lake a \"table\"). Then, every time you need to use one of the characters in the base64 scale, instead of\nusing many resources to calculate the exact character to be used, you simply retrieve this character\nfrom the array where you stored all the possible characters in the base64 scale.\nWe retrieve the character that we need directly from memory.\n\nWe can start building a Zig struct to store our base64 decoder/encoder logic.\nWe start with the `Base64` struct below. For now, we only have one single data member in this\nstruct, i.e. the member `_table`, which represents our lookup table. We also have an `init()` method,\nto create a new instance of a `Base64` object, and, a `_char_at()` method, which is a\n\"get character at index $x$\" type of function.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Base64 = struct {\n    _table: *const [64]u8,\n\n    pub fn init() Base64 {\n        const upper = \"ABCDEFGHIJKLMNOPQRSTUVWXYZ\";\n        const lower = \"abcdefghijklmnopqrstuvwxyz\";\n        const numbers_symb = \"0123456789+/\";\n        return Base64{\n            ._table = upper ++ lower ++ numbers_symb,\n        };\n    }\n\n    pub fn _char_at(self: Base64, index: usize) u8 {\n        return self._table[index];\n    }\n};\n```\n:::\n\n\n\n\n\nIn other words, the `_char_at()` method is responsible for getting the character in the lookup\ntable (i.e. the `_table` struct data member) that corresponds to a particular index in the\n\"base64 scale\". So, in the example below, we know that the character that corresponds to the\nindex 28 in the \"base64 scale\" is the character \"c\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst base64 = Base64.init();\ntry stdout.print(\n    \"Character at index 28: {c}\\n\",\n    .{base64._char_at(28)}\n);\n```\n:::\n\n\n\n\n```\nCharacter at index 28: c\n```\n\n\n\n### A base64 encoder {#sec-base64-encoder-algo}\n\nThe algorithm behind a base64 encoder usually works on a window of 3 bytes. Because each byte has\n8 bits, so, 3 bytes forms a set of $8 \\times 3 = 24$ bits. This is desirable for the base64 algorithm, because\n24 bits is divisible by 6, which forms $24 / 6 = 4$ groups of 6 bits each.\n\nTherefore, the base64 algorithm works by converting 3 bytes at a time\ninto 4 characters from the base64 scale. It keeps iterating through the input string,\n3 bytes at a time, and converting them into the base64 scale, producing 4 characters\nper iteration. It keeps iterating, and producing these \"new characters\"\nuntil it hits the end of the input string.\n\nNow, you may think, what if you have a particular string that have a number of bytes\nthat is not divisible by 3? What happens? For example, if you have a string\nthat contains only two characters/bytes, such as \"Hi\". How the\nalgorithm would behave in such situation? You find the answer at @fig-base64-algo1.\nYou can see at @fig-base64-algo1 that the string \"Hi\", when converted to base64,\nbecomes the string \"SGk=\":\n\n![The logic behind a base64 encoder](./../Figures/base64-encoder-flow.png){#fig-base64-algo1}\n\nTaking the string \"Hi\" as an example, we have 2 bytes, or, 16 bits in total. So, we lack a full byte (8 bits)\nto complete the window of 24 bits that the base64 algorithm likes to work on. The first thing that\nthe algorithm does, is to check how to divide the input bytes into groups of 6 bits.\n\nIf the algorithm notices that there is a group of 6 bits that, have some bits in it, but, at the same time, it is not full\n(in other words, $0 < nbits < 6$, being $nbits$ the number of bits), meaning that, it lacks\nsome bits to fill the 6-bits requirement, the algorithm simply add extra zeros in this group\nto fill the space that it needs. That is why at @fig-base64-algo1, on the third group after the 6-bit transformation,\n2 extra zeros were added to fill the gap in this group.\n\nWhen we have a 6-bit group that is not completely full, like the third group, extra zeros\nare added to fill the gap. But what about when an entire 6-bit group is empty, or, it\nsimply doesn't exist? This is the case of the fourth 6-bit group exposed at\n@fig-base64-algo1.\n\nThis fourth group is necessary, because the algorithm works on 4 groups of 6 bits.\nBut the input string does not have enough bytes to create a fourth 6-bit group.\nEvery time this happens, where an entire group of 6 bits is empty,\nthis group becomes a \"padding group\". Every \"padding group\" is mapped to\nthe character `=` (equal sign), which represents \"null\", or, the end\nof meaningful characters in the sequence. Hence, everytime that the algorithm produces a\n\"padding group\", this group is automatically mapped to `=`.\n\nAs another example, if you give the string \"0\" as input to a base64 encoder, this string is\ntranslated into the base64 sequence \"MA==\".\nThe character \"0\" is, in binary, the sequence `00110000`[^zero-note]. So, with the 6-bit transformation\nexposed at @fig-base64-algo1, this single character would produce these two 6-bit groups: `001100`, `000000`.\nThe remaining two 6-bit groups become \"padding groups\". That is why the last\ntwo characters in the output sequence (MA==) are `==`.\n\n\n[^zero-note]: Notice that, the character \"0\" is different than the actual number 0, which is simply zero in binary.\n\n### A base64 decoder {#sec-base64-decoder-algo}\n\nThe algorithm behind a base64 decoder is essentially the inverse process of a base64 encoder.\nA base64 decoder needs to translate base64 messages back into their original meaning,\ni.e. into the original sequence of binary data.\n\nA base64 decoder usually works on a window of 4 bytes. Because it wants to convert these 4 bytes\nback into the original sequence of 3 bytes, that was converted into 4 groups of 6 bits by the\nbase64 encoder. Remember, in a base64 decoder we are essentially reverting the process made\nby the base64 encoder.\n\nEach byte in the input string (the base64 encoded string) normally contributes to re-create\ntwo different bytes in the output (the original binary data).\nIn other words, each byte that comes out of a base64 decoder is created by transforming merging two different\nbytes in the input together. You can visualize this relationship at @fig-base64-algo2:\n\n![The logic behind a base64 decoder](./../Figures/base64-decoder-flow.png){#fig-base64-algo2}\n\nThe exact transformations, or, the exact steps applied to each byte from the input to transform them\ninto the bytes of the output, are a bit tricky to visualize in a figure like this. Because of that, I have\nsummarized these transformations as \"Some bit shifting and additions ...\" in the figure. These transformations\nwill be described in depth later.\n\nBesides that, if you look again at @fig-base64-algo2, you will notice that the character `=` was completely\nignored by the algorithm. Remember, this is just a special character that marks the end of meaningful characters\nin the base64 sequence. So, every `=` character in a base64 encoded sequence should be ignored by a base64 decoder.\n\n\n## Difference between encode and decode {#sec-encode-vs-decode}\n\nIf you don't have any previous experience with base64, you might not understand the differences\nbetween \"encode\" and \"decode\". Essentially, the terms \"encode\" and \"decode\" here\nhave the exact same meaning as they have in the field of encryption (i.e. they mean the same thing as \"encode\" and \"decode\" in hashing\nalgorithms, like the MD5 algorithm).\n\nThus, \"encode\" means that we want to encode, or, in other words, we want to translate some message into\nthe base64 encoding system. We want to produce the sequence of base64 characters that represent this\noriginal message in the base64 encoding system.\n\nIn contrast, \"decode\" represents the inverse process.\nWe want to decode, or, in other words, translate a base64 message back to its original content.\nSo, in this process we get a sequence of base64 characters as input, and produce as output,\nthe binary data that is represented by this sequence of base64 characters.\n\nAny base64 library is normally composed of these two parts: 1) the encoder, which is a function that encodes\n(i.e. it converts) any sequence of binary data into a sequence of base64 characters; 2) the decoder, which is a function\nthat converts a sequence of base64 characters back into the original sequence of binary data.\n\n\n\n## Calculating the size of the output {#sec-base64-length-out}\n\nOne task that we need to do is to calculate how much space we need to reserve for the\noutput, both of the encoder and decoder. This is simple math, and can be done easily in Zig\nbecause every array has its length (its number of elements) easily accesible by consulting\nthe `.len` property of the array.\n\nFor the encoder, the logic is the following: for each 3 bytes that we find in the input,\n4 new bytes are created in the output. So, we take the number of bytes in the input, divide it\nby 3, use a ceiling function, then, we multiply the result by 4. That way, we get the total\nnumber of bytes that will be produced by the encoder in its output.\n\nThe `_calc_encode_length()` function below encapsulates this logic.\nInside this function, we take the length of the input array,\nwe divide it by 3, and apply a ceil operation over the result by using the\n`divCeil()` function from the Zig Standard Library. Lastly, we multiply\nthe end result by 4 to get the answer we need.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_encode_length(input: []const u8) !usize {\n    if (input.len < 3) {\n        const n_output: usize = 4;\n        return n_output;\n    }\n    const n_output: usize = try std.math.divCeil(\n        usize, input.len, 3\n    );\n    return n_output * 4;\n}\n```\n:::\n\n\n\n\n\nAlso, you might have notice that, if the input length is less than 3 bytes, then, the output length of the encoder is\nalways 4 bytes. This is the case for every input with less than 3 bytes, because, as I described at @sec-base64-encoder-algo,\nthe algorithm always produces enough \"padding-groups\" in the end result, to complete the 4 bytes window.\n\nNow, for the decoder, we just need to apply the inverse logic: for each 4 bytes in the input, 3 bytes\nwill be produced in the output of the decoder. I mean, this is roughly true, because we also need to\ntake the `=` character into account, which is always ignored by the decoder, as we described at @sec-base64-decoder-algo, and,\nat @fig-base64-algo2. But we can ignore this fact for now, just to keep things simple.\n\nThe function `_calc_decode_length()` exposed below summarizes this logic that we described. It is very similar\nto the function `_calc_encode_length()`. Only the division part is twisted, and also, in the special\ncase where we have less than 4 bytes in the input to work on. Also notice that this time, we apply\na floor operation over the output of the division, by using the `divFloor()`\nfunction (instead of a ceiling operation with `divCeil()`).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_decode_length(input: []const u8) !usize {\n    if (input.len < 4) {\n        const n_output: usize = 3;\n        return n_output;\n    }\n    const n_output: usize = try std.math.divFloor(\n        usize, input.len, 4\n    );\n    return n_output * 3;\n}\n```\n:::\n\n\n\n\n\n## Building the encoder logic {#sec-encoder-logic}\n\nIn this section, we can start building the logic behind the `encode()` function, which\nwill be responsible for encoding messages into the base64 encoding system.\nIf you are an anxious person, and you want to see now the full source code of the implementation\nfor this base64 encoder/decoder, you can find it at the `ZigExamples` folder in the official repository of\nthis book[^zig-base64-algo].\n\n[^zig-base64-algo]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/base64/base64_basic.zig>.\n\n\n\n### The 6-bit transformation {#sec-6bit-transf}\n\nThe 6-bit transformation presented at @fig-base64-algo1 is the core part of the base64 encoder algorithm.\nBy understanding how this transformation is made in code, the rest of the algorithm becomes much simpler\nto comprehend.\n\nIn essence, this 6-bit transformation is made with the help of bitwise operators.\nBitwise operators are essential to any type of low-level operation that is done at the bit-level. For the specific case of the base64 algorithm,\nthe operators *bif shift to the left* (`<<`), *bit shift to the right* (`>>`), and the *bitwise and* (`&`) are used. They\nare the core solution for the 6-bit transformation.\n\nThere are 3 different scenarios that we need to take into account in this transformation. First, is the perfect scenario,\nwhere we have the perfect window of 3 bytes to work on. Second, we have the scenario where we have a window of only\ntwo bytes to work with. And last, we have the scenario where we have a window of one single byte.\n\nIn each of these 3 scenarios, the 6-bit transformation works a bit differently. To make the explanation\neasier, I will use the variable `output` to refer to the bytes in the output of the base64 encoder,\nand the variable `input` to refer to the bytes in the input of the encoder.\n\n\nSo, if you have the perfect window of 3 bytes, these are steps for the 6-bit transformation:\n\n1. `output[0]` is produced by moving the bits from `input[0]` two positions to the right.\n1. `output[1]` is produced by summing two components. First, take the last two bits from `input[0]`, then, move them four positions to the left. Second, move the bits from `input[1]` four positions to the right. Sum these two components.\n1. `output[2]` is produced by summing two components. First, take the last four bits from `input[1]`, then, move them two positions to the left. Second, move the bits from `input[2]` six positions to the right. Sum these two components.\n1. `output[3]` is produced by taking the last six bits from `input[2]`.\n\n\nThis is the perfect scenario, where we have a full window of 3 bytes to work on.\nJust to make things as clear as possible, the @fig-encoder-bitshift demonstrates visually how\nthe step 2 mentioned above works. So the 2nd byte in the `output` of the encoder, is made by taking the 1st byte (dark purple)\nand the 2nd byte (orange) from the input. You can see that, at the end of the process, we get a new\nbyte that contains the last 2 bits from the 1st byte in the `input`, and the first 4 bits\nfrom the 2nd byte in the `input`.\n\n![How the 2nd byte in the output of the encoder is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input.](../Figures/base64-encoder-bit-shift.png){#fig-encoder-bitshift}\n\nOn the other hand, we must be prepared for the instances where we do not have the perfect window of 3 bytes.\nIf you have a window of 2 bytes, then, the steps 3 and 4, which produces the bytes `output[2]` and `output[3]`, change a little bit,\nand they become:\n\n- `output[2]` is produced by taking the last 4 bits from `input[1]`, then, move them two positions to the left.\n- `output[3]` is the character `'='`.\n\n\nFinally, if you have a window of a single byte, then, the steps 2 to 4, which produces the bytes `output[1]`, `output[2]` and `output[3]` change,\nbecoming:\n\n- `output[1]` is produced by taking the last two bits from `input[0]`, then, move them four positions to the left.\n- `output[2]` and `output[3]` are the character `=`.\n\n\nIf these bullet points were a bit confusing for you, you may find the @tbl-transf-6bit more intuitive.\nThis table unifies all this logic into a simple table. Notice that\nthis table also provides the exact expression in Zig that creates the corresponding\nbyte in the output.\n\n\n::: {#tbl-transf-6bit}\n\n| Number of bytes in the window | Byte index in the output | In code                                    |\n|-------------------------------|--------------------------|--------------------------------------------|\n| 3                             | 0                        | input[0] >> 2                              |\n| 3                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 3                             | 2                        | ((input[1] & 0x0f) << 2) + (input[2] >> 6) |\n| 3                             | 3                        | input[2] & 0x3f                            |\n| 2                             | 0                        | input[0] >> 2                              |\n| 2                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 2                             | 2                        | ((input[1] & 0x0f) << 2)                   |\n| 2                             | 3                        | '='                                        |\n| 1                             | 0                        | input[0] >> 2                              |\n| 1                             | 1                        | ((input[0] & 0x03) << 4)                   |\n| 1                             | 2                        | '='                                        |\n| 1                             | 3                        | '='                                        |\n\n: How the 6-bit transformation translates into code in different window settings.\n\n:::\n\n\n\n\n\n\n### Bit-shifting in Zig\n\nBit-shifting in Zig works similarly to bit-shifting in C.\nAll bitwise operators that exist in C are available in Zig.\nHere, in the base64 encoder algorithm, they are essential\nto produce the result we want.\n\nFor those who are not familiar with these operators, they are\noperators that operates at the bit-level of your values.\nThis means that these operators takes the bits that form the value\nyou have, and change them in some way. This ultimately also changes\nthe value itself, because the binary representation of this value\nchanges.\n\nWe have already seen at @fig-encoder-bitshift the effect produced by a bit-shift.\nBut let's use the first byte in the output of the base64 encoder as another example of what\nbit-shifting means. This is the easiest byte of the 4 bytes in the output\nto build. Because we only need to move the bits from the first byte in the input two positions to the right,\nwith the *bit shift to the right* (`>>`) operator.\n\nIf we take the string \"Hi\" that we used at @fig-base64-algo1 as an example, the first byte in\nthis string is \"H\", which is the sequence `01001000` in binary.\nIf we move the bits of this byte, two places to the right, we get the sequence `00010010` as result.\nThis binary sequence is the value `18` in decimal, and also, the value `0x12` in hexadecimal.\nNotice that the first 6 bits of \"H\" were moved to the end of the byte.\nWith this operation, we get the first byte of the output.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const input = \"Hi\";\n    try stdout.print(\"{d}\\n\", .{input[0] >> 2});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n18\n```\n\n\n:::\n:::\n\n\n\n\nIf you recall @fig-base64-algo1, the first byte present in the output should\nbe equivalent to the 6-bit group `010010`. Although being visually different, the\nsequences `010010` and `00010010` are semantically equal. They mean the same thing.\nThey both represent the number 18 in decimal, and the value `0x12` in hexadecimal.\n\nSo, don't take the \"6-bit group\" factor so seriously. We do not need necessarily to\nget a 6-bit sequence as result. As long as the meaning of the 8-bit sequence we get is the same\nof the 6-bit sequence, we are in the clear.\n\n\n\n### Selecting specific bits with the `&` operator\n\nIf you comeback to @sec-6bit-transf, you will see that, in order to produce\nthe second and third bytes in the output, we need to select specific\nbits from the first and second bytes in the input string. But how\ncan we do that? The answer relies on the *bitwise and* (`&`) operator.\n\nThe @fig-encoder-bitshift already showed you what effect this `&` operator\nproduces in the bits of its operands. But let's make a clear description of it.\n\nIn summary, the `&` operator performs a logical conjunction operation\nbetween the bits of its operands. In more details, the operator `&`\ncompares each bit of the first operand to the corresponding bit of the second operand.\nIf both bits are 1, the corresponding result bit is set to 1.\nOtherwise, the corresponding result bit is set to 0 [@microsoftbitwiseand].\n\nSo, if we apply this operator to the binary sequences `1000100` and `00001101`\nthe result of this operation is the binary sequence `00000100`. Because only\nat the sixth position in both binary sequences we had a 1 value. So any\nposition where we do not have both binary sequences setted to 1, we get\na 0 bit in the resulting binary sequence.\n\nWe lose information about the original bit values\nfrom both sequences in this case. Because we no longer know\nif this 0 bit in the resulting binary sequence was produced by\ncombining 0 with 0, or 1 with 0, or 0 with 1.\n\nAs an example, suppose you have the binary sequence `10010111`, which is the number 151 in decimal. How\ncan we get a new binary sequence which contains only the third and\nfourth bits of this sequence?\n\nWe just need to combine this sequence with `00110000` (is `0x30` in hexadecimal) using the `&` operator.\nNotice that only the third and fourth positions in this binary sequence is setted to 1. As a consequence, only the\nthird and fourth values of both binary sequences are potentially preserved in the output. All the remaining positions\nare setted to zero in the output sequence, which is `00010000` (is the number 16 in decimal).\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const bits = 0b10010111;\n    try stdout.print(\"{d}\\n\", .{bits & 0b00110000});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n16\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Allocating space for the output\n\nAs I described at @sec-stack, to store an object in the stack,\nthis object needs to have a known and fixed length at compile-time. This is an important\nlimitation for our base64 encoder/decoder case. Because the size of\nthe output (from both the encoder and decoder) depends\ndirectly on the size of the input.\n\nHaving this in mind, we cannot know at compile time which is\nthe size of the output for both the encoder and decoder.\nSo, if we can't know the size of the output at compile time,\nthis means that we cannot store the output for both the encoder\nand decoder in the stack.\n\nConsequently, we need to store this output on the heap,\nand, as I commented at @sec-heap, we can only\nstore objects in the heap by using allocator objects.\nSo, one the arguments to both the `encode()` and `decode()`\nfunctions, needs to be an allocator object, because\nwe know for sure that, at some point inside the body of these\nfunctions, we need to allocate space on the heap to\nstore the output of these functions.\n\nThat is why, both the `encode()` and `decode()` functions that I\npresent in this book, have an argument called `allocator`,\nwhich receives a allocator object as input, identified by\nthe type `std.mem.Allocator` from the Zig Standard Library.\n\n\n\n### Writing the `encode()` function\n\nNow that we have a basic understanding on how the bitwise operators work, and how\nexactly they help us to achieve the result we want to achieve. We can now encapsulate\nall the logic that we have described at @fig-base64-algo1 and @tbl-transf-6bit into a nice\nfunction that we can add to our `Base64` struct definition, that we started at @sec-base64-table.\n\nYou can find the `encode()` function below. Notice that the first argument of this function,\nis the `Base64` struct itself. Therefore, this argument clearly signals\nthat this function is a method from the `Base64` struct.\n\nBecause the `encode()` function itself is fairly long,\nI intentionally omitted the `Base64` struct definition in this source code,\njust for brevity reasons. So, just remember that this function is a public function (or a public method) from the\n`Base64` struct.\n\nFurthermore, this `encode()` function has two other arguments:\n\n1. `input` is the input sequence of characters that you want to encode in base64;\n1. `allocator` is an allocator object to use in the necessary memory allocations.\n\nI described everything you need to know about allocator objects at @sec-allocators.\nSo, if you are not familiar with them, I highly recommend you to comeback to\nthat section, and read it.\nBy looking at the `encode()` function, you will see that we use this\nallocator object to allocate enough memory to store the output of\nthe encoding process.\n\nThe main for loop in the function is responsible for iterating through the entire input string.\nIn every iteration, we use a `count` variable to count how many iterations we had at the\nmoment. When `count` reaches 3, then, we try to encode the 3 characters (or bytes) that we have accumulated\nin the temporary buffer object (`buf`).\n\nAfter encoding these 3 characters and storing the result in the `output` variable, we reset\nthe `count` variable to zero, and start to count again on the next iteration of the loop.\nIf the loop hits the end of the string, and, the `count` variable is less than 3, then, it means that\nthe temporary buffer contains the last 1 or 2 bytes from the input.\nThat is why we have two `if` statements after the for loop. To deal which each possible case.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn encode(self: Base64,\n              allocator: std.mem.Allocator,\n              input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n\n    const n_out = try _calc_encode_length(input);\n    var out = try allocator.alloc(u8, n_out);\n    var buf = [3]u8{ 0, 0, 0 };\n    var count: u8 = 0;\n    var iout: u64 = 0;\n\n    for (input, 0..) |_, i| {\n        buf[count] = input[i];\n        count += 1;\n        if (count == 3) {\n            out[iout] = self._char_at(buf[0] >> 2);\n            out[iout + 1] = self._char_at(\n                ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n            );\n            out[iout + 2] = self._char_at(\n                ((buf[1] & 0x0f) << 2) + (buf[2] >> 6)\n            );\n            out[iout + 3] = self._char_at(buf[2] & 0x3f);\n            iout += 4;\n            count = 0;\n        }\n    }\n\n    if (count == 1) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            (buf[0] & 0x03) << 4\n        );\n        out[iout + 2] = '=';\n        out[iout + 3] = '=';\n    }\n\n    if (count == 2) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n        );\n        out[iout + 2] = self._char_at(\n            (buf[1] & 0x0f) << 2\n        );\n        out[iout + 3] = '=';\n        iout += 4;\n    }\n\n    return out;\n}\n```\n:::\n\n\n\n\n\n\n## Building the decoder logic {#sec-decoder-logic}\n\nNow, we can focus on writing the base64 decoder logic. Remember from @fig-base64-algo2 that,\na base64 decoder does the inverse process of an encoder. So, all we need to do, is to\nwrite a `decode()` function that performs the inverse process that I exposed at @sec-encoder-logic.\n\n\n### Mapping base64 characters to their indexes {#sec-map-base64-index}\n\nOne thing that we need to do, in order to decode a base64-encoded message, is to calculate\nthe index in the base64 scale of every base64 character that we encounter in the decoder input.\n\nIn other words, the decoder receives as input, a sequence of base64 characters. We need\nto translate this sequence of characters into a sequence of indexes. These indexes\nare the index of each character in the base64 scale. This way, we get the value/byte\nthat was calculated in the 6-bit transformation step of the encoder process.\n\nThere are probably better/faster ways to calculate this, especially using a \"divide and conquer\"\ntype of strategy. But for now, I am satisfied with a simple and \"brute force\" type of strategy.\nThe `_char_index()` function below contains this strategy.\n\nWe are essentially looping through the *lookup table* with the base64 scale,\nand comparing the character we got with each character in the base64 scale.\nIf these characters match, then, we return the index of this character in the\nbase64 scale as the result.\n\nNotice that, if the input character is `'='`, the function returns the index 64, which is\n\"out of range\" in the scale. But, as I described at @sec-base64-scale,\nthe character `'='` does not belong to the base64 scale itself.\nIt is a special and meaningless character in base64.\n\nAlso notice that this `_char_index()` function is a method from our `Base64` struct,\nbecause of the `self` argument. Again, I have omitted the `Base64` struct definition in this example\nfor brevity reasons.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn _char_index(self: Base64, char: u8) u8 {\n    if (char == '=')\n        return 64;\n    var index: u8 = 0;\n    for (0..63) |i| {\n        if (self._char_at(i) == char)\n            break;\n        index += 1;\n    }\n\n    return index;\n}\n```\n:::\n\n\n\n\n\n\n### The 6-bit transformation\n\nOnce again, the core part of the algorithm is the 6-bit transformation.\nIf we understand the necessary steps to perform this transformation, the rest\nof the algorithm becomes much easier.\n\nFirst of all, before we actually go to the 6-bit transformation,\nwe need to make sure that we use `_char_index()` to convert the sequence of base64 characters\ninto a sequence of indexes. So the snippet below is important for the job that will be done.\nThe result of `_char_index()` is stored in a temporary buffer, and this temporary buffer\nis what we are going to use in the 6-bit transformation, instead of the actual `input` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (0..input.len) |i| {\n    buf[i] = self._char_index(input[i]);\n}\n```\n:::\n\n\n\n\nNow, instead of producing 4 bytes (or 4 characters) as output per each window of 3 characters in the input,\na base64 decoder produces 3 bytes (or 3 characters) as output per each window of 4 characters in the input.\nOnce again, is the inverse process.\n\nSo, the steps to produce the 3 bytes in the output are:\n\n1. `output[0]` is produced by summing two components. First, move the bits from `buf[0]` two positions to the left. Second, move the bits from `buf[1]` 4 positions to the right. Then, sum these two components.\n1. `output[1]` is produced by summing two components. First, move the bits from `buf[1]` four positions to the left. Second, move the bits from `buf[2]` 2 positions to the right. Then, sum these two components.\n1. `output[2]` is produced by summing two components. First, move the bits from `buf[2]` six positions to the left. Then, you sum the result with `buf[3]`.\n\n\nBefore we continue, let's try to visualize how these transformations make the original bytes that we had\nbefore the encoding process. First, think back to the 6-bit transformation performed by the encoder exposed at @sec-encoder-logic.\nThe first byte in the output of the encoder is produced by moving the bits in the first byte of the input two positions to the right.\n\nIf for example the first byte in the input of the encoder was the sequence `ABCDEFGH`, then, the first byte in the output of the encoder would be\n`00ABCDEF` (this sequence would be the first byte in the input of the decoder). Now, if the second byte in the input of the encoder was the sequence\n`IJKLMNOP`, then, the second byte in the encoder output would be `00GHIJKL` (as we demonstrated at @fig-encoder-bitshift).\n\nHence, if the sequences `00ABCDEF` and `00GHIJKL` are the first and second bytes, respectively, in the input of the decoder, the\n@fig-decoder-bitshift demonstrates visually how these two bytes are transformed into the first byte of the output of the decoder.\nNotice that the output byte is the sequence `ABCDEFGH`, which is the original byte from the input of the encoder.\n\n![How the 1st byte in the decoder output is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input](../Figures/base64-decoder-bit-shift.png){#fig-decoder-bitshift}\n\nThe @tbl-6bit-decode presents how the three steps described earlier translate into Zig code:\n\n\n\n::: {#tbl-6bit-decode}\n\n| Byte index in the output | In code                       |\n|--------------------------|-------------------------------|\n| 0                        | (buf[0] << 2) + (buf[1] >> 4) |\n| 1                        | (buf[1] << 4) + (buf[2] >> 2) |\n| 2                        | (buf[2] << 6) + buf[3]        |\n\n: The necessary steps for the 6-transformation in the decode process.\n\n\n:::\n\n\n\n\n\n\n\n### Writing the `decode()` function\n\nThe `decode()` function below contains the entire decoding process.\nWe first calculate the size of the output, with\n`_calc_decode_length()`, then, we allocate enough memory for this output with\nthe allocator object.\n\nThree temporary variables are created: 1) `count`, to hold the window count\nin each iteration of the for loop; 2) `iout`, to hold the current index in the output;\n3) `buf`, which is the temporary buffer that holds the base64 indexes to be\nconverted through the 6-bit transformation.\n\nThen, in each iteration of the for loop we fill the temporary buffer with the current\nwindow of bytes. When `count` hits the number 4, then, we have a full window of\nindexes in `buf` to be converted, and then, we apply the 6-bit transformation\nover the temporary buffer.\n\nNotice that we check if the indexes 2 and 3 in the temporary buffer are the number 64, which, if you recall\nfrom @sec-map-base64-index, is when the `_calc_index()` function receives a `'='` character\nas input. So, if these indexes are equal to the number 64, the `decode()` function knows\nthat it can simply ignore these indexes. They are not converted because, as I described before,\nthe character `'='` has no meaning, despite being the end of meaningful characters in the sequence.\nSo we can safely ignore them when they appear in the sequence.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn decode(self: Base64,\n          allocator: std.mem.Allocator,\n          input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n    const n_output = try _calc_decode_length(input);\n    var output = try allocator.alloc(u8, n_output);\n    var count: u8 = 0;\n    var iout: u64 = 0;\n    var buf = [4]u8{ 0, 0, 0, 0 };\n\n    for (0..input.len) |i| {\n        buf[count] = self._char_index(input[i]);\n        count += 1;\n        if (count == 4) {\n            output[iout] = (buf[0] << 2) + (buf[1] >> 4);\n            if (buf[2] != 64) {\n                output[iout + 1] = (buf[1] << 4) + (buf[2] >> 2);\n            }\n            if (buf[3] != 64) {\n                output[iout + 2] = (buf[2] << 6) + buf[3];\n            }\n            iout += 3;\n            count = 0;\n        }\n    }\n\n    return output;\n}\n```\n:::\n\n\n\n\n\n## The end result\n\nNow that we have both `decode()` and `encode()` implemented. We have a fully functioning\nbase64 encoder/decoder implemented in Zig. Here is an usage example of our\n`Base64` struct with the `encode()` and `decode()` methods that we have implemented.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar memory_buffer: [1000]u8 = undefined;\nvar fba = std.heap.FixedBufferAllocator.init(\n    &memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst text = \"Testing some more stuff\";\nconst etext = \"VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=\";\nconst base64 = Base64.init();\nconst encoded_text = try base64.encode(\n    allocator, text\n);\nconst decoded_text = try base64.decode(\n    allocator, etext\n);\ntry stdout.print(\n    \"Encoded text: {s}\\n\", .{encoded_text}\n);\ntry stdout.print(\n    \"Decoded text: {s}\\n\", .{decoded_text}\n);\n```\n:::\n\n\n\n\n```\nEncoded text: VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=\nDecoded text: Testing some more stuff\n```\n\nYou can also see the full source code at once, by visiting the official repository of this book[^repo].\nMore precisely inside the `ZigExamples` folder[^zig-base64-algo].\n\n[^repo]: <https://github.com/pedropark99/zig-book>\n",
-    "supporting": [
-      "01-base64_files"
-    ],
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/01-zig-weird/execute-results/html.json b/_freeze/Chapters/01-zig-weird/execute-results/html.json
index f1342fff..7f926500 100644
--- a/_freeze/Chapters/01-zig-weird/execute-results/html.json
+++ b/_freeze/Chapters/01-zig-weird/execute-results/html.json
@@ -3,9 +3,7 @@
   "result": {
     "engine": "knitr",
     "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\nlanguage, it is still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. They really make it sometimes hard to debug\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscure the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that get's compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e. it is where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contain Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nTherefore, Zig contains a native build system in it, and\nwe can use this build system to write small scripts in Zig,\nwhich describes the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e. creating new objects)\nare made in Zig. You can create a new object in Zig by using the following syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). At @sec-assignments we talk more about objects in general.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that at @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIs worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt is like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portable C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nIn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e. the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. Thus, if you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith a \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, operations like accessing the `stdout` (or opening a file) on Windows\ndepends on resources that are available only at *runtime* (you will learn more about compile-time\nversus runtime at @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword at @sec-comptime.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation at a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues \n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described in @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig later in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig? \nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar to our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentation.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It is a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (on YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e. identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nIn contrast, if you use `var`, then, the object created is a variable object.\nWith `var` you can declare this object in your source code, and then,\nchange the value of this object how many times you want over future points\nin your source code.\n\nSo, using the same code example exposed above, if I change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it is an \"variable object\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIs important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code use this object while it is uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object. \n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e. if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to a special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It is discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also get's discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e. the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\nIs worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array. \n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it is a slice that\naccess all elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" at @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth at @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially at @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned at @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e. the start and the end of this range)\nis known at compile-time, the slice object that get's created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nat @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that get's created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e. a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can \ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n```\n:::\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat get's created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, the `slice` object have a runtime known range, because the end index of the range\nis not known at compile time. In other words, the size of the array at `buffer` is not known\nat compile time. When we execute this program, the size of the array might be 10, or, it might be 12\ndepending on where we execute it. Therefore, we don't know at compile time if\nthe slice object have a range of size 10, or, a range of size 12.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e. a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented at @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e. `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIs worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e. the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause it is much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e. if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it is a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIs important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig at @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers at @sec-root-file and especially at @sec-assignments.\n- How strings work in Zig at @sec-zig-strings.\n- How to use arrays and slices at @sec-arrays.\n- How to import functionality from other Zig modules at @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* at @sec-structs-and-oop.\n- Basic control flow syntax at @sec-zig-control-flow.\n- Enums at @sec-enum;\n- Pointers and Optionals at @sec-pointer;\n- Error handling with `try` and `catch` at @sec-error-handling;\n- Unit tests at @sec-unittests;\n- Vectors at @sec-vectors-simd;\n- Build System at @sec-build-system;\n\n\n\n\n",
-    "supporting": [
-      "01-zig-weird_files"
-    ],
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/03-structs/execute-results/html.json b/_freeze/Chapters/03-structs/execute-results/html.json
index 543363c1..2629908d 100644
--- a/_freeze/Chapters/03-structs/execute-results/html.json
+++ b/_freeze/Chapters/03-structs/execute-results/html.json
@@ -2,10 +2,8 @@
   "hash": "ddf3054f897e82f090f3aa7c5890ec78",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Control flow, structs, modules and types\n\nWe have discussed a lot of Zig's syntax in the last chapter,\nespecially in @sec-root-file and @sec-main-file.\nBut we still need to discuss some other very important\nelements of the language. Elements that you will use constantly on your day-to-day\nroutine.\n\nWe begin this chapter by discussing the different keywords and structures\nin Zig related to control flow (e.g. loops and if statements).\nThen, we talk about structs and how they can be used to do some\nbasic Object-Oriented (OOP) patterns in Zig. We also talk about\ntype inference and type casting.\nFinally, we end this chapter by discussing modules, and how they relate\nto structs.\n\n\n\n## Control flow {#sec-zig-control-flow}\n\nSometimes, you need to make decisions in your program. Maybe you need to decide\nwhether or not to execute a specific piece of code. Or maybe,\nyou need to apply the same operation over a sequence of values. These kinds of tasks,\ninvolve using structures that are capable of changing the \"control flow\" of our program.\n\nIn computer science, the term \"control flow\" usually refers to the order in which expressions (or commands)\nare evaluated in a given language or program. But this term is also used to refer\nto structures that are capable of changing this \"evaluation order\" of the commands\nexecuted by a given language/program.\n\nThese structures are better known\nby a set of terms, such as: loops, if/else statements, switch statements, among others. So,\nloops and if/else statements are examples of structures that can change the \"control\nflow\" of our program. The keywords `continue` and `break` are also examples of symbols\nthat can change the order of evaluation, since they can move our program to the next iteration\nof a loop, or make the loop stop completely.\n\n\n### If/else statements\n\nAn if/else statement performs a \"conditional flow operation\".\nA conditional flow control (or choice control) allows you to execute\nor ignore a certain block of commands based on a logical condition.\nMany programmers and computer science professionals also use\nthe term \"branching\" in this case.\nIn essence, an if/else statement allow us to use the result of a logical test\nto decide whether or not to execute a given block of commands.\n\nIn Zig, we write if/else statements by using the keywords `if` and `else`.\nWe start with the `if` keyword followed by a logical test inside a pair\nof parentheses, followed by a pair of curly braces which contains the lines\nof code to be executed in case the logical test returns the value `true`.\n\nAfter that, you can optionally add an `else` statement. To do that, just add the `else`\nkeyword followed by a pair of curly braces, with the lines of code\nto executed in case the logical test defined at `if` returns `false`.\n\nIn the example below, we are testing if the object `x` contains a number\nthat is greater than 10. Judging by the output printed to the console,\nwe know that this logical test returned `false`. Because the output\nin the console is compatible with the line of code present in the\n`else` branch of the if/else statement.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x = 5;\nif (x > 10) {\n    try stdout.print(\n        \"x > 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x <= 10!\\n\", .{}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nx <= 10!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Switch statements {#sec-switch}\n\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust.\nAs you would expect, to write a switch statement in Zig we use the `switch` keyword.\nWe provide the value that we want to \"switch over\" inside a\npair of parentheses. Then, we list the possible combinations (or \"branches\")\ninside a pair of curly braces.\n\nLet's take a look at the code example below. You can see that\nI'm creating an enum type called `Role`. We talk more about enums in @sec-enum.\nBut in summary, this `Role` type is listing different types of roles in a fictitious\ncompany, like `SE` for Software Engineer, `DE` for Data Engineer, `PM` for Product Manager,\netc.\n\nNotice that we are using the value from the `role` object in the\nswitch statement, to discover which exact area we need to store in the `area` variable object.\nAlso notice that we are using type inference inside the switch statement, with the dot character,\nas we are going to describe in @sec-type-inference.\nThis makes the `zig` compiler infer the correct data type of the values (`PM`, `SE`, etc.) for us.\n\nAlso notice that, we are grouping multiple values in the same branch of the switch statement.\nWe just separate each possible value with a comma. For example, if `role` contains either `DE` or `DA`,\nthe `area` variable would contain the value `\"Data & Analytics\"`, instead of `\"Platform\"` or `\"Sales\"`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO => {\n            area = \"Platform\";\n        },\n        .DE, .DA => {\n            area = \"Data & Analytics\";\n        },\n        .KS => {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nPlatform\n```\n\n\n:::\n:::\n\n\n\n\n\n#### Switch statements must exhaust all possibilities\n\nOne very important aspect about switch statements in Zig\nis that they must exhaust all existing possibilities.\nIn other words, all possible values that could be found inside the `role`\nobject must be explicitly handled in this switch statement.\n\nSince the `role` object has type `Role`, the only possible values to\nbe found inside this object are `PM`, `SE`, `DPE`, `PO`, `DE`, `DA` and `KS`.\nThere are no other possible values to be stored in this `role` object.\nThus, the switch statements must have a combination (branch) for each one of these values.\nThis is what \"exhaust all existing possibilities\" means. The switch statement covers\nevery possible case.\n\nTherefore, you cannot write a switch statement in Zig, and leave an edge case\nwith no explicit action to be taken.\nThis is a similar behaviour to switch statements in Rust, which also have to\nhandle all possible cases.\n\n\n\n#### The else branch\n\nTake a look at the `dump_hex_fallible()` function below as an example. This function\ncomes from the Zig Standard Library. More precisely, from the\n[`debug.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/debug.zig)[^debug-mod].\nThere are multiple lines in this function, but I omitted them to focus solely on the\nswitch statement found in this function. Notice that this switch statement has four\npossible cases (i.e. four explicit branches). Also, notice that we used an `else` branch\nin this case.\n\nAn `else` branch in a switch statement works as the \"default branch\".\nWhenever you have multiple cases in your switch statement where\nyou want to apply the exact same action, you can use an `else` branch to do that.\n\n[^debug-mod]: <https://github.com/ziglang/zig/blob/master/lib/std/debug.zig>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' => try writer.writeAll(\"␊\"),\n        '\\r' => try writer.writeAll(\"␍\"),\n        '\\t' => try writer.writeAll(\"␉\"),\n        else => try writer.writeByte('.'),\n    }\n}\n```\n:::\n\n\n\n\nMany programmers would also use an `else` branch to handle a \"not supported\" case.\nThat is, a case that cannot be properly handled by your code, or, just a case that\nshould not be \"fixed\". Therefore, you can use an `else` branch to panic (or raise an error)\nin your program to stop the current execution.\n\nTake the code example below. We can see that, we are handling the cases\nfor the `level` object being either 1, 2, or 3. All other possible cases are not supported by default,\nand, as consequence, we raise a runtime error in such cases through the `@panic()` built-in function.\n\nAlso notice that, we are assigning the result of the switch statement to a new object called `category`.\nThis is another thing that you can do with switch statements in Zig. If a branch\noutputs a value as result, you can store the result value of the switch statement into\na new object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 => \"beginner\",\n    3 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n:::\n\n\n\n\n```\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n```\n\n\n\n#### Using ranges in switch\n\nFurthermore, you can also use ranges of values in switch statements.\nThat is, you can create a branch in your switch statement that is used\nwhenever the input value is within the specified range. These \"range expressions\"\nare created with the operator `...`. It is important\nto emphasize that the ranges created by this operator are\ninclusive on both ends.\n\nFor example, I could easily change the previous code example to support all\nlevels between 0 and 100. Like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 => \"beginner\",\n    26...75 => \"intermediary\",\n    76...100 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nbeginner\n```\n\n\n:::\n:::\n\n\n\n\nThis is neat, and it works with character ranges too. That is, I could\nsimply write `'a'...'z'`, to match any character value that is a\nlowercase letter, and it would work fine.\n\n\n#### Labeled switch statements\n\nIn @sec-blocks we have talked about labeling blocks, and also, about using these labels\nto return a value from the block. Well, from version 0.14.0 and onwards of the `zig` compiler,\nyou can also apply labels over switch statements, which makes it possible to almost implement a\n\"C `goto`\" like pattern.\n\nFor example, if you give the label `xsw` to a switch statement, you can use this\nlabel in conjunction with the `continue` keyword to go back to the beginning of the switch\nstatement. In the example below, the execution goes back to the beginning of the\nswitch statement two times, before ending at the `3` branch.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nxsw: switch (@as(u8, 1)) {\n    1 => {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 => continue :xsw 3,\n    3 => return,\n    4 => {},\n    else => {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n```\n:::\n\n\n\n\n\n### The `defer` keyword {#sec-defer}\n\nWith the `defer` keyword you can register an expression to be executed when you exit the current scope.\nTherefore, this keyword has a similar functionality as the `on.exit()` function from R.\nTake the `foo()` function below as an example. When we execute this `foo()` function, the expression\nthat prints the message \"Exiting function ...\" is getting executed only when the function exits\nits scope.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nAdding some numbers ...\nMultiplying ...\nExiting function ...\n```\n\nTherefore, we can use `defer` to declare an expression that is going to be executed\nwhen your code exits the current scope. Some programmers like to interpret the phrase \"exit of the current scope\"\nas \"the end of the current scope\". But this interpretation might not be entirely correct, depending\non what you consider as \"the end of the current scope\".\n\nI mean, what do you consider as **the end** of the current scope? Is it the closing curly bracket (`}`) of the scope?\nIs it when the last expression in the function gets executed? Is it when the function returns to the previous scope?\nEtc. For example, it would not be correct to interpret the \"exit of the current scope\" as the closing\ncurly bracket of the scope. Because the function might exit from an earlier position than this\nclosing curly bracket (e.g. an error value was generated at a previous line inside the function;\nthe function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\n\nNow, if you remember of what we have discussed in @sec-blocks, there are multiple structures in the language\nthat create their own separate scopes. For/while loops, if/else statements,\nfunctions, normal blocks, etc. This also affects the interpretation of `defer`.\nFor example, if you use `defer` inside a for loop, then, the given expression\nwill be executed everytime this specific for loop exits its own scope.\n\nBefore we continue, is worth emphasizing that the `defer` keyword is an \"unconditional defer\".\nWhich means that the given expression will be executed no matter how the code exits\nthe current scope. For example, your code might exit the current scope because of an error value\nbeing generated, or, because of a return statement, or, a break statement, etc.\n\n\n\n### The `errdefer` keyword {#sec-errdefer1}\n\nOn the previous section, we have discussed the `defer` keyword, which you can use to\nregister an expression to be executed at the exit of the current scope.\nBut this keyword has a brother, which is the `errdefer` keyword. While `defer`\nis an \"unconditional defer\", the `errdefer` keyword is a \"conditional defer\".\nWhich means that the given expression is executed only when you exit the current\nscope on a very specific circumstance.\n\nIn more details, the expression given to `errdefer` is executed only when an error occurs in the current scope.\nTherefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope\nin a normal situation, without errors, the expression given to `errdefer` is not executed.\n\nThis makes the `errdefer` keyword one of the many tools available in Zig for error handling.\nIn this section, we are more concerned with the control flow aspects around `errdefer`.\nBut we are going to discuss `errdefer` later as a error handling tool in @sec-errdefer2.\n\nThe code example below demonstrates three things:\n\n- that `defer` is an \"unconditional defer\", because the given expression get's executed regardless of how the function `foo()` exits its own scope.\n- that `errdefer` is executed because the function `foo()` returned an error value.\n- that `defer` and `errdefer` expressions are executed in a LIFO (*last in, first out*) order.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\nWhen I say that \"defer expressions\" are executed in a LIFO order, what I want to say is that\nthe last `defer` or `errdefer` expressions in the code are the first ones to be executed.\nYou could also interpret this as: \"defer expressions\" are executed from bottom to top, or,\nfrom last to first.\n\nTherefore, if I change the order of the `defer` and `errdefer` expressions, you will notice that\nthe value of `i` that get's printed to the console changes to 1. This doesn't mean that the\n`defer` expression was not executed in this case. This actually means that the `defer` expression\nwas executed only after the `errdefer` expression. The code example below demonstrates this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\n\n\n### For loops\n\nA loop allows you to execute the same lines of code multiple times,\nthus, creating a \"repetition space\" in the execution flow of your program.\nLoops are particularly useful when we want to replicate the same function\n(or the same set of commands) over different inputs.\n\nThere are different types of loops available in Zig. But the most\nessential of them all is probably the *for loop*. A for loop is\nused to apply the same piece of code over the elements of a slice, or, an array.\n\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from\nother languages. You start with the `for` keyword, then, you\nlist the items that you want to iterate\nover inside a pair of parentheses. Then, inside of a pair of pipes (`|`)\nyou should declare an identifier that will serve as your iterator, or,\nthe \"repetition index of the loop\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (items) |value| {\n    // code to execute\n}\n```\n:::\n\n\n\n\nTherefore, instead of using a `(value in items)` syntax,\nin Zig, for loops use the syntax `(items) |value|`. In the example\nbelow, you can see that we are looping through the items\nof the array stored at the object `name`, and printing to the\nconsole the decimal representation of each character in this array.\n\nIf we wanted, we could also iterate through a slice (or a portion) of\nthe array, instead of iterating through the entire array stored in the `name` object.\nJust use a range selector to select the section you want. For example,\nI could provide the expression `name[0..3]` to the for loop, to iterate\njust through the first 3 elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n80 | 101 | 100 | 114 | 111 | \n```\n\n\n:::\n:::\n\n\n\n\nIn the above example we are using the value itself of each\nelement in the array as our iterator. But there are many situations where\nwe need to use an index instead of the actual values of the items.\n\nYou can do that by providing a second set of items to iterate over.\nMore precisely, you provide the range selector `0..` to the for loop. So,\nyes, you can use two different iterators at the same time in a for\nloop in Zig.\n\nBut remember from @sec-assignments that, every object\nyou create in Zig must be used in some way. So if you declare two iterators\nin your for loop, you must use both iterators inside the for loop body.\nBut if you want to use just the index iterator, and not use the \"value iterator\",\nthen, you can discard the value iterator by maching the\nvalue items to the underscore character, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n:::\n\n\n\n\n```\n0 | 1 | 2 | 3 | 4 |\n```\n\n\n### While loops\n\nA while loop is created from the `while` keyword. A `for` loop\niterates through the items of an array, but a `while` loop\nwill loop continuously, and infinitely, until a logical test\n(specified by you) becomes false.\n\nYou start with the `while` keyword, then, you define a logical\nexpression inside a pair of parentheses, and the body of the\nloop is provided inside a pair of curly braces, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\nYou can also specify the increment expression to be used at the beginning of a while loop.\nTo do that, we write the increment expression inside a pair of parentheses after a colon character (`:`).\nThe code example below demonstrates this other pattern.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\n### Using `break` and `continue`\n\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using\nthe keywords `break` and `continue`, respectively. The `while` loop presented in the next code example is,\nat first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to `true`.\nBut what makes this `while` loop stop when the `i` object reaches the count\n10? It is the `break` keyword!\n\nInside the while loop, we have an if statement that is constantly checking if the `i` variable\nis equal to 10. Since we are incrementing the value of `i` at each iteration of the\nwhile loop, this `i` object will eventually be equal to 10, and when it is, the if statement\nwill execute the `break` expression, and, as a result, the execution of the while loop is stopped.\n\nNotice the use of the `expect()` function from the Zig Standard Library after the while loop.\nThis `expect()` function is an \"assert\" type of function.\nThis function checks if the logical test provided is equal to true. If so, the function do nothing.\nOtherwise (i.e. the logical test is equal to false), the function raises an assertion error.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nEverything worked!\n```\n\n\n:::\n:::\n\n\n\n\nSince this code example was executed successfully by the `zig` compiler,\nwithout raising any errors, we known that, after the execution of the while loop,\nthe `i` object is equal to 10. Because if it wasn't equal to 10, an error would have\nbeen raised by `expect()`.\n\nNow, in the next example, we have a use case for\nthe `continue` keyword. The if statement is constantly\nchecking if the current index is a multiple of 2. If\nit is, we jump to the next iteration of the loop.\nOtherwise, the loop just prints the current index to the console.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 3 | 5 | \n```\n\n\n:::\n:::\n\n\n\n\n\n\n## Function parameters are immutable {#sec-fun-pars}\n\nWe have already discussed a lot of the syntax behind function declarations in @sec-root-file and @sec-main-file.\nBut I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig.\nIn summary, function parameters are immutable in Zig.\n\nTake the code example below, where we declare a simple function that just tries to add\nsome amount to the input integer, and returns the result back. If you look closely\nat the body of this `add2()` function, you will notice that we try\nto save the result back into the `x` function argument.\n\nIn other words, this function not only uses the value that it received through the function argument\n`x`, but it also tries to change the value of this function argument, by assigning the addition result\ninto `x`. However, function arguments in Zig are immutable. You cannot change their values, or, you\ncannot assign values to them inside the body's function.\n\nThis is the reason why, the code example below does not compile successfully. If you try to compile\nthis code example, you will get a compile error message about \"trying to change the value of a\nimmutable (i.e. constant) object\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n\n\n```\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n```\n\n\n### A free optimization\n\nIf a function argument receives as input an object whose data type is\nany of the primitive types that we have listed in @sec-primitive-data-types,\nthis object is always passed by value to the function. In other words, this object\nis copied into the function stack frame.\n\nHowever, if the input object have a more complex data type, for example, it might\nbe a struct instance, or an array, or an union value, etc., in cases like that, the `zig` compiler\nwill take the liberty of deciding for you which strategy is best. Thus, the `zig` compiler will\npass your object to the function either by value, or by reference. The compiler will always\nchoose the strategy that is faster for you.\nThis optimization that you get for free is possible only because function arguments are\nimmutable in Zig.\n\n\n### How to overcome this barrier\n\nThere are some situations where you might need to change the value of your function argument\ndirectly inside the function's body. This happens more often when we are passing\nC structs as inputs to Zig functions.\n\nIn a situation like this, you can overcome this barrier by using a pointer. In other words,\ninstead of passing a value as input to the argument, you can pass a \"pointer to value\" instead.\nYou can change the value that the pointer points to, by dereferencing it.\n\nTherefore, if we take our previous `add2()` example, we can change the value of the\nfunction argument `x` inside the function's body by marking the `x` argument as a\n\"pointer to a `u32` value\" (i.e. `*u32` data type), instead of a `u32` value.\nBy making it a pointer, we can finally alter the value of this function argument directly inside\nthe body of the `add2()` function. You can see that the code example below compiles successfully.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n```\n:::\n\n\n\n\n```\nResult: 6\n```\n\n\nEven in this code example above, the `x` argument is still immutable. Which means that the pointer itself is immutable.\nTherefore, you cannot change the memory address that it points to. However, you can dereference the pointer\nto access the value that it points to, and also, to change this value, if you need to.\n\n\n\n\n\n## Structs and OOP {#sec-structs-and-oop}\n\nZig is a language more closely related to C (which is a procedural language),\nthan it is to C++ or Java (which are object-oriented languages). Because of that, you do not\nhave advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or\nclass inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\n\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C.\nYou give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can\nalso register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object\nthat you create with this new type, will always have these methods available and associated with them.\n\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which\nis used to construct (or, to instantiate) every object of this particular class, and we also have\na destructor method (or a destructor function), which is the function responsible for destroying\nevery object of this class.\n\nIn Zig, we normally declare the constructor and the destructor methods\nof our structs, by declaring an `init()` and a `deinit()` methods inside the struct.\nThis is just a naming convention that you will find across the entire Zig Standard Library.\nSo, in Zig, the `init()` method of a struct is normally the constructor method of the class represented by this struct.\nWhile the `deinit()` method is the method used for destroying an existing instance of that struct.\n\nThe `init()` and `deinit()` methods are both used extensively in Zig code, and you will see both of\nthem being used when we talk about allocators in @sec-allocators.\nBut, as another example, let's build a simple `User` struct to represent a user of some sort of system.\n\nIf you look at the `User` struct below, you can see the `struct` keyword.\nNotice the data members of this struct: `id`, `name` and `email`. Every data member has its\ntype explicitly annotated, with the colon character (`:`) syntax that we described earlier in @sec-root-file.\nBut also notice that every line in the struct body that describes a data member, ends with a comma character (`,`).\nSo every time you declare a data member in your Zig code, always end the line with a comma character, instead\nof ending it with the traditional semicolon character (`;`).\n\nNext, we have registered an `init()` function as a method\nof this `User` struct. This `init()` method is the constructor method that we will use to instantiate\nevery new `User` object. That is why this `init()` function returns a new `User` object as result.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    pub fn init(id: u64,\n                name: []const u8,\n                email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    pub fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\npedro\n```\n\n\n:::\n:::\n\n\n\n\nThe `pub` keyword plays an important role in struct declarations, and OOP in Zig.\nEvery method that you declare in your struct that is marked with the keyword `pub`,\nbecomes a public method of this particular struct.\n\nSo every method that you create inside your struct, is, at first, a private method\nof that struct. Meaning that, this method can only be called from within this\nstruct. But, if you mark this method as public, with the keyword `pub`, then,\nyou can call the method directly from an instance of the `User` struct.\n\nIn other words, the functions marked by the keyword `pub`\nare members of the public API of that struct.\nFor example, if I did not mark the `print_name()` method as public,\nthen, I could not execute the line `u.print_name()`. Because I would\nnot be authorized to call this method directly in my code.\n\n\n\n### Anonymous struct literals {#sec-anonymous-struct-literals}\n\nYou can declare a struct object as a literal value. When we do that, we normally specify the\ndata type of this struct literal by writing its data type just before the opening curly brace.\nFor example, I could write a struct literal value of the type `User` that we have defined\nin the previous section like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n```\n:::\n\n\n\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a\nstruct literal, but not specify explicitly the type of this particular struct.\nAn anonymous struct is written by using the syntax `.{}`. So, we essentially\nreplaced the explicit type of the struct literal with a dot character (`.`).\n\nAs we described in @sec-type-inference, when you put a dot before a struct literal,\nthe type of this struct literal is automatically inferred by the `zig` compiler.\nIn essence, the `zig` compiler will look for some hint of what is the type of that struct.\nThis hint can be the type annotation of a function argument,\nor the return type annotation of the function that you are using, or the type annotation\nof an existing object.\nIf the compiler does find such type annotation, it will use this\ntype in your literal struct.\n\nAnonymous structs are very commonly used as inputs to function arguments in Zig.\nOne example that you have seen already constantly, is the `print()`\nfunction from the `stdout` object.\nThis function takes two arguments.\nThe first argument, is a template string, which should\ncontain string format specifiers in it, which tells how the values provided\nin the second argument should be printed into the message.\n\nWhile the second argument is a struct literal that lists the values\nto be printed into the template message specified in the first argument.\nYou normally want to use an anonymous struct literal here, so that the\n`zig` compiler do the job of specifying the type of this particular\nanonymous struct for you.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello, world!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Struct declarations must be constant\n\nTypes in Zig must be `const` or `comptime` (we are going to talk more about comptime in @sec-comptime).\nWhat this means is that you cannot create a new data type, and mark it as variable with the `var` keyword.\nSo struct declarations are always constant. You cannot declare a new struct type using the `var` keyword.\nIt must be `const`.\n\nIn the `Vec3` example below, this declaration is allowed because I'm using the `const` keyword\nto declare this new data type.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n```\n:::\n\n\n\n\n\n### The `self` method argument {#sec-self-arg}\n\nIn every language that have OOP, when we declare a method of some class or struct, we\nusually declare this method as a function that has a `self` argument.\nThis `self` argument is the reference to the object itself from which the method\nis being called from.\n\nIt is not mandatory to use this `self` argument. But why would you not use this `self` argument?\nThere is no reason to not use it. Because the only way to get access to the data stored in the\ndata members of your struct is to access them through this `self` argument.\nIf you don't need to use the data in the data members of your struct inside your method, you very likely don't need\na method. You can just declare this logic as a simple function, outside of your\nstruct declaration.\n\n\nTake the `Vec3` struct below. Inside this `Vec3` struct we declared a method named `distance()`.\nThis method calculates the distance between two `Vec3` objects, by following the distance\nformula in euclidean space. Notice that this `distance()` method takes two `Vec3` objects\nas input, `self` and `other`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n```\n:::\n\n\n\n\n\nThe `self` argument corresponds to the `Vec3` object from which this `distance()` method\nis being called from. While the `other` is a separate `Vec3` object that is given as input\nto this method. In the example below, the `self` argument corresponds to the object\n`v1`, because the `distance()` method is being called from the `v1` object,\nwhile the `other` argument corresponds to the object `v2`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n```\n:::\n\n\n\n\n```\nDistance: 3.3970575502926055\n```\n\n\n\n### About the struct state\n\nSometimes you don't need to care about the state of your struct object. Sometimes, you just need\nto instantiate and use the objects, without altering their state. You can notice that when you have methods\ninside your struct declaration that might use the values that are present in the data members, but they\ndo not alter the values in these data members of the struct in anyway.\n\nThe `Vec3` struct that was presented in @sec-self-arg is an example of that.\nThis struct have a single method named `distance()`, and this method does use the values\npresent in all three data members of the struct (`x`, `y` and `z`). But at the same time,\nthis method does not change the values of these data members at any point.\n\nAs a result of that, when we create `Vec3` objects we usually create them as\nconstant objects, like the `v1` and `v2` objects presented in @sec-self-arg.\nWe can create them as variable objects with the `var` keyword,\nif we want to. But because the methods of this `Vec3` struct do not change\nthe state of the objects in any point, it's unnecessary to mark them\nas variable objects.\n\nBut why? Why am I talking about this here? It's because the `self` argument\nin the methods are affected depending on whether the\nmethods present in a struct change or don't change the state of the object itself.\nMore specifically, when you have a method in a struct that changes the state\nof the object (i.e. changes the value of a data member), the `self` argument\nin this method must be annotated in a different manner.\n\nAs I described in @sec-self-arg, the `self` argument in methods of\na struct is the argument that receives as input the object from which the method\nwas called from. We usually annotate this argument in the methods by writing `self`,\nfollowed by the colon character (`:`), and the data type of the struct to which\nthe method belongs to (e.g. `User`, `Vec3`, etc.).\n\nIf we take the `Vec3` struct that we defined in the previous section as an example,\nwe can see in the `distance()` method that this `self` argument is annotated as\n`self: Vec3`. Because the state of the `Vec3` object is never altered by this\nmethod.\n\nBut what if we do have a method that alters the state of the object, by altering the\nvalues of its data members, how should we annotate `self` in this instance? The answer is:\n\"we should annotate `self` as a pointer of `x`, instead of just `x`\".\nIn other words, you should annotate `self` as `self: *x`, instead of annotating it\nas `self: x`.\n\nIf we create a new method inside the `Vec3` object that, for example, expands the\nvector by multiplying its coordinates by a factor of two, then, we need to follow\nthis rule specified in the previous paragraph. The code example below demonstrates\nthis idea:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n```\n:::\n\n\n\n\nNotice in the code example above that we have added a new method\nto our `Vec3` struct named `twice()`. This method doubles the\ncoordinate values of our vector object. In the\ncase of the `twice()` method, we annotated the `self` argument as `*Vec3`,\nindicating that this argument receives a pointer (or a reference, if you prefer to call it this way)\nto a `Vec3` object as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n```\n:::\n\n\n\n\n```\nDoubled: 8.4\n```\n\n\n\nNow, if you change the `self` argument in this `twice()` method to `self: Vec3`, like in the\n`distance()` method, you will get the compiler error exposed below as result. Notice that this\nerror message is showing a line from the `twice()` method body,\nindicating that you cannot alter the value of the `x` data member.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n```\n:::\n\n\n\n\n```\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\n```\n\nThis error message indicates that the `x` data member belongs to a constant object,\nand, because of that, it cannot be changed. Ultimately, this error message\nis telling us that the `self` argument is constant.\n\nIf you take some time, and think hard about this error message, you will understand it.\nYou already have the tools to understand why we are getting this error message.\nWe have talked about it already in @sec-fun-pars.\nSo remember, every function argument is immutable in Zig, and `self`\nis no exception to this rule.\n\nIn this example, we marked the `v3` object as a variable object.\nBut this does not matter. Because it is not about the input object, it is about\nthe function argument.\n\nThe problem begins when we try to alter the value of `self` directly, which is a function argument,\nand, every function argument is immutable by default. You may ask yourself how can we overcome\nthis barrier, and once again, the solution was also discussed in @sec-fun-pars.\nWe overcome this barrier, by explicitly marking the `self` argument as a pointer.\n\n\n::: {.callout-note}\nIf a method of your `x` struct alters the state of the object, by\nchanging the value of any data member, then, remember to use `self: *x`,\ninstead of `self: x` in the function signature of this method.\n:::\n\n\nYou could also interpret the content discussed in this section as:\n\"if you need to alter the state of your `x` struct object in one of its methods,\nyou must explicitly pass the `x` struct object by reference to the `self` argument of this method\".\n\n\n\n## Type inference {#sec-type-inference}\n\nZig is a strongly typed language. But, there are some situations\nwhere you don't have to explicitly write the type of every single object in your source code,\nas you would expect from a traditional strongly typed language, such as C and C++.\n\nIn some situations, the `zig` compiler can use type inference to solve the data types for you, easing some of\nthe burden that you carry as a developer.\nThe most common way this happens is through function arguments that receive struct objects\nas input.\n\nIn general, type inference in Zig is done by using the dot character (`.`).\nEverytime you see a dot character written before a struct literal, or before an enum value, or something like that,\nyou know that this dot character is playing a special part in this place. More specifically, it is\ntelling the `zig` compiler something along the lines of: \"Hey! Can you infer the type of this\nvalue for me? Please!\". In other words, this dot character is playing a similar role as the `auto` keyword in C++.\n\nI gave you some examples of this in @sec-anonymous-struct-literals, where we used anonymous struct literals.\nAnonymous struct literals are, struct literals that use type inference to\ninfer the exact type of this particular struct literal.\nThis type inference is done by looking for some minimal hint of the correct data type to be used.\nYou could say that the `zig` compiler looks for any neighbouring type annotation that might tell it\nwhat the correct type would be.\n\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in @sec-switch).\nI also gave some other examples of type inference in @sec-switch, where we were inferring the data types of enum values listed inside\nof switch statements (e.g. `.DE`).\nBut as another example, take a look at this `fence()` function reproduced below,\nwhich comes from the [`atomic.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig)[^fence-fn]\nof the Zig Standard Library.\n\n[^fence-fn]: <https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig>.\n\nThere are a lot of things in this function that we haven't talked about yet, such as:\nwhat `comptime` means? `inline`? `extern`?\nLet's just ignore all of these things, and focus solely on the switch statement\nthat is inside this function.\n\nWe can see that this switch statement uses the `order` object as input. This `order`\nobject is one of the inputs of this `fence()` function, and we can see in the type annotation,\nthat this object is of type `AtomicOrder`. We can also see a bunch of values inside the\nswitch statements that begin with a dot character, such as `.release` and `.acquire`.\n\nBecause these weird values contain a dot character before them, we are asking the `zig`\ncompiler to infer the types of these values inside the switch statement. Then, the `zig`\ncompiler is looking into the current context where these values are being used, and it is\ntrying to infer the types of these values.\n\nSince they are being used inside a switch statement, the `zig` compiler looks into the type\nof the input object given to the switch statement, which is the `order` object in this case.\nBecause this object have type `AtomicOrder`, the `zig` compiler infers that these values\nare data members from this type `AtomicOrder`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic => @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire => tsan.__tsan_acquire(addr),\n            .release => tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst => {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n```\n:::\n\n\n\n\nThis is how basic type inference is done in Zig. If we didn't use the dot character before\nthe values inside this switch statement, then, we would be forced to explicitly write\nthe data types of these values. For example, instead of writing `.release` we would have to\nwrite `AtomicOrder.release`. We would have to do this for every single value\nin this switch statement, and this is a lot of work. That is why type inference\nis commonly used on switch statements in Zig.\n\n\n\n## Type casting {#sec-type-cast}\n\nIn this section, I want to discuss type casting (or, type conversion) with you.\nWe use type casting when we have an object of type \"x\", and we want to convert\nit into an object of type \"y\", i.e. we want to change the data type of the object.\n\nMost languages have a formal way to perform type casting. In Rust for example, we normally\nuse the keyword `as`, and in C, we normally use the type casting syntax, e.g. `(int) x`.\nIn Zig, we use the `@as()` built-in function to cast an object of type \"x\", into\nan object of type \"y\".\n\nThis `@as()` function is the preferred way to perform type conversion (or type casting)\nin Zig. Because it is explicit, and, it also performs the casting only if it\nis unambiguous and safe. To use this function, you just provide the target data type\nin the first argument, and, the object that you want cast as the second argument.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file2ed34a8fc96.test_0...OKAll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\nThis is the general way to perform type casting in Zig. But remember, `@as()` works only when casting\nis unambiguous and safe, and there are situations where these assumptions do not hold. For example,\nwhen casting an integer value into a float value, or vice-versa, it is not clear to the compiler\nhow to perform this conversion safely.\n\nTherefore, we need to use specialized \"casting functions\" in such situations.\nFor example, if you want to cast an integer value into a float value, then, you\nshould use the `@floatFromInt()` function. In the inverse scenario, you should use\nthe `@intFromFloat()` function.\n\nIn these functions, you just provide the object that you want to\ncast as input. Then, the target data type of the \"type casting operation\" is determined by\nthe type annotation of the object where you are saving the results.\nIn the example below, we are casting the object `x` into a value of type `f32`,\nbecause the object `y`, which is where we are saving the results, is annotated\nas an object of type `f32`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file2ed34bfb9fa5.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\nAnother built-in function that is very useful when performing type casting operations is `@ptrCast()`.\nIn essence, we use the `@as()` built-in function when we want to explicit convert (or cast) a Zig value/object\nfrom a type \"x\" to a type \"y\", etc. However, pointers (we are going to discuss pointers\nin more depth in @sec-pointer) are a special type of object in Zig,\ni.e. they are treated differently from \"normal objects\".\n\nEverytime a pointer is involved in some \"type casting operation\" in Zig, the `@ptrCast()` function is used.\nThis function works similarly to `@floatFromInt()`.\nYou just provide the pointer object that you want to cast as input to this function, and the\ntarget data type is, once again, determined by the type annotation of the object where the results are being\nstored.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file2ed324328e1f.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## Modules\n\nWe already talked about what modules are, and also, how to import other modules into\nyour current module via *import statements*. Every Zig module (i.e. a `.zig` file) that you write in your project\nis internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the\nZig Standard Library into our current module.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n```\n:::\n\n\n\n\nWhen we want to access the functions and objects from the standard library, we\nare basically accessing the data members of the struct stored in the `std`\nobject. That is why we use the same syntax that we use in normal structs, with the dot operator (`.`)\nto access the data members and methods of the struct.\n\nWhen this \"import statement\" get's executed, the result of this expression is a struct\nobject that contains the Zig Standard Library modules, global variables, functions, etc.\nAnd this struct object get's saved (or stored) inside the constant object named `std`.\n\n\nTake the [`thread_pool.zig` module from the project `zap`](https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig)[^thread]\nas an example. This module is written as if it was\na big struct. That is why we have a top-level and public `init()` method\nwritten in this module. The idea is that all top-level functions written in this\nmodule are methods from the struct, and all top-level objects and struct declarations\nare data members of this struct. The module is the struct itself.\n\n[^thread]: <https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig>\n\n\nSo you would import and use this module by doing something like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst ThreadPool = @import(\"thread_pool.zig\");\nconst num_cpus = std.Thread.getCpuCount()\n    catch @panic(\"failed to get cpu core count\");\nconst num_threads = std.math.cast(u16, num_cpus)\n    catch std.math.maxInt(u16);\nconst pool = ThreadPool.init(\n    .{ .max_threads = num_threads }\n);\n```\n:::\n",
-    "supporting": [
-      "03-structs_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Control flow, structs, modules and types\n\nWe have discussed a lot of Zig's syntax in the last chapter,\nespecially in @sec-root-file and @sec-main-file.\nBut we still need to discuss some other very important\nelements of the language. Elements that you will use constantly on your day-to-day\nroutine.\n\nWe begin this chapter by discussing the different keywords and structures\nin Zig related to control flow (e.g. loops and if statements).\nThen, we talk about structs and how they can be used to do some\nbasic Object-Oriented (OOP) patterns in Zig. We also talk about\ntype inference and type casting.\nFinally, we end this chapter by discussing modules, and how they relate\nto structs.\n\n\n\n## Control flow {#sec-zig-control-flow}\n\nSometimes, you need to make decisions in your program. Maybe you need to decide\nwhether or not to execute a specific piece of code. Or maybe,\nyou need to apply the same operation over a sequence of values. These kinds of tasks,\ninvolve using structures that are capable of changing the \"control flow\" of our program.\n\nIn computer science, the term \"control flow\" usually refers to the order in which expressions (or commands)\nare evaluated in a given language or program. But this term is also used to refer\nto structures that are capable of changing this \"evaluation order\" of the commands\nexecuted by a given language/program.\n\nThese structures are better known\nby a set of terms, such as: loops, if/else statements, switch statements, among others. So,\nloops and if/else statements are examples of structures that can change the \"control\nflow\" of our program. The keywords `continue` and `break` are also examples of symbols\nthat can change the order of evaluation, since they can move our program to the next iteration\nof a loop, or make the loop stop completely.\n\n\n### If/else statements\n\nAn if/else statement performs a \"conditional flow operation\".\nA conditional flow control (or choice control) allows you to execute\nor ignore a certain block of commands based on a logical condition.\nMany programmers and computer science professionals also use\nthe term \"branching\" in this case.\nIn essence, an if/else statement allow us to use the result of a logical test\nto decide whether or not to execute a given block of commands.\n\nIn Zig, we write if/else statements by using the keywords `if` and `else`.\nWe start with the `if` keyword followed by a logical test inside a pair\nof parentheses, followed by a pair of curly braces which contains the lines\nof code to be executed in case the logical test returns the value `true`.\n\nAfter that, you can optionally add an `else` statement. To do that, just add the `else`\nkeyword followed by a pair of curly braces, with the lines of code\nto executed in case the logical test defined at `if` returns `false`.\n\nIn the example below, we are testing if the object `x` contains a number\nthat is greater than 10. Judging by the output printed to the console,\nwe know that this logical test returned `false`. Because the output\nin the console is compatible with the line of code present in the\n`else` branch of the if/else statement.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x = 5;\nif (x > 10) {\n    try stdout.print(\n        \"x > 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x <= 10!\\n\", .{}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nx <= 10!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Switch statements {#sec-switch}\n\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust.\nAs you would expect, to write a switch statement in Zig we use the `switch` keyword.\nWe provide the value that we want to \"switch over\" inside a\npair of parentheses. Then, we list the possible combinations (or \"branches\")\ninside a pair of curly braces.\n\nLet's take a look at the code example below. You can see that\nI'm creating an enum type called `Role`. We talk more about enums in @sec-enum.\nBut in summary, this `Role` type is listing different types of roles in a fictitious\ncompany, like `SE` for Software Engineer, `DE` for Data Engineer, `PM` for Product Manager,\netc.\n\nNotice that we are using the value from the `role` object in the\nswitch statement, to discover which exact area we need to store in the `area` variable object.\nAlso notice that we are using type inference inside the switch statement, with the dot character,\nas we are going to describe in @sec-type-inference.\nThis makes the `zig` compiler infer the correct data type of the values (`PM`, `SE`, etc.) for us.\n\nAlso notice that, we are grouping multiple values in the same branch of the switch statement.\nWe just separate each possible value with a comma. For example, if `role` contains either `DE` or `DA`,\nthe `area` variable would contain the value `\"Data & Analytics\"`, instead of `\"Platform\"` or `\"Sales\"`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO => {\n            area = \"Platform\";\n        },\n        .DE, .DA => {\n            area = \"Data & Analytics\";\n        },\n        .KS => {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nPlatform\n```\n\n\n:::\n:::\n\n\n\n\n\n#### Switch statements must exhaust all possibilities\n\nOne very important aspect about switch statements in Zig\nis that they must exhaust all existing possibilities.\nIn other words, all possible values that could be found inside the `role`\nobject must be explicitly handled in this switch statement.\n\nSince the `role` object has type `Role`, the only possible values to\nbe found inside this object are `PM`, `SE`, `DPE`, `PO`, `DE`, `DA` and `KS`.\nThere are no other possible values to be stored in this `role` object.\nThus, the switch statements must have a combination (branch) for each one of these values.\nThis is what \"exhaust all existing possibilities\" means. The switch statement covers\nevery possible case.\n\nTherefore, you cannot write a switch statement in Zig, and leave an edge case\nwith no explicit action to be taken.\nThis is a similar behaviour to switch statements in Rust, which also have to\nhandle all possible cases.\n\n\n\n#### The else branch\n\nTake a look at the `dump_hex_fallible()` function below as an example. This function\ncomes from the Zig Standard Library. More precisely, from the\n[`debug.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/debug.zig)[^debug-mod].\nThere are multiple lines in this function, but I omitted them to focus solely on the\nswitch statement found in this function. Notice that this switch statement has four\npossible cases (i.e. four explicit branches). Also, notice that we used an `else` branch\nin this case.\n\nAn `else` branch in a switch statement works as the \"default branch\".\nWhenever you have multiple cases in your switch statement where\nyou want to apply the exact same action, you can use an `else` branch to do that.\n\n[^debug-mod]: <https://github.com/ziglang/zig/blob/master/lib/std/debug.zig>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' => try writer.writeAll(\"␊\"),\n        '\\r' => try writer.writeAll(\"␍\"),\n        '\\t' => try writer.writeAll(\"␉\"),\n        else => try writer.writeByte('.'),\n    }\n}\n```\n:::\n\n\n\n\nMany programmers would also use an `else` branch to handle a \"not supported\" case.\nThat is, a case that cannot be properly handled by your code, or, just a case that\nshould not be \"fixed\". Therefore, you can use an `else` branch to panic (or raise an error)\nin your program to stop the current execution.\n\nTake the code example below. We can see that, we are handling the cases\nfor the `level` object being either 1, 2, or 3. All other possible cases are not supported by default,\nand, as consequence, we raise a runtime error in such cases through the `@panic()` built-in function.\n\nAlso notice that, we are assigning the result of the switch statement to a new object called `category`.\nThis is another thing that you can do with switch statements in Zig. If a branch\noutputs a value as result, you can store the result value of the switch statement into\na new object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 => \"beginner\",\n    3 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n:::\n\n\n\n\n```\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n```\n\n\n\n#### Using ranges in switch\n\nFurthermore, you can also use ranges of values in switch statements.\nThat is, you can create a branch in your switch statement that is used\nwhenever the input value is within the specified range. These \"range expressions\"\nare created with the operator `...`. It is important\nto emphasize that the ranges created by this operator are\ninclusive on both ends.\n\nFor example, I could easily change the previous code example to support all\nlevels between 0 and 100. Like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 => \"beginner\",\n    26...75 => \"intermediary\",\n    76...100 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nbeginner\n```\n\n\n:::\n:::\n\n\n\n\nThis is neat, and it works with character ranges too. That is, I could\nsimply write `'a'...'z'`, to match any character value that is a\nlowercase letter, and it would work fine.\n\n\n#### Labeled switch statements\n\nIn @sec-blocks we have talked about labeling blocks, and also, about using these labels\nto return a value from the block. Well, from version 0.14.0 and onwards of the `zig` compiler,\nyou can also apply labels over switch statements, which makes it possible to almost implement a\n\"C `goto`\" like pattern.\n\nFor example, if you give the label `xsw` to a switch statement, you can use this\nlabel in conjunction with the `continue` keyword to go back to the beginning of the switch\nstatement. In the example below, the execution goes back to the beginning of the\nswitch statement two times, before ending at the `3` branch.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nxsw: switch (@as(u8, 1)) {\n    1 => {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 => continue :xsw 3,\n    3 => return,\n    4 => {},\n    else => {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n```\n:::\n\n\n\n\n\n### The `defer` keyword {#sec-defer}\n\nWith the `defer` keyword you can register an expression to be executed when you exit the current scope.\nTherefore, this keyword has a similar functionality as the `on.exit()` function from R.\nTake the `foo()` function below as an example. When we execute this `foo()` function, the expression\nthat prints the message \"Exiting function ...\" is getting executed only when the function exits\nits scope.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nAdding some numbers ...\nMultiplying ...\nExiting function ...\n```\n\nTherefore, we can use `defer` to declare an expression that is going to be executed\nwhen your code exits the current scope. Some programmers like to interpret the phrase \"exit of the current scope\"\nas \"the end of the current scope\". But this interpretation might not be entirely correct, depending\non what you consider as \"the end of the current scope\".\n\nI mean, what do you consider as **the end** of the current scope? Is it the closing curly bracket (`}`) of the scope?\nIs it when the last expression in the function gets executed? Is it when the function returns to the previous scope?\nEtc. For example, it would not be correct to interpret the \"exit of the current scope\" as the closing\ncurly bracket of the scope. Because the function might exit from an earlier position than this\nclosing curly bracket (e.g. an error value was generated at a previous line inside the function;\nthe function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\n\nNow, if you remember of what we have discussed in @sec-blocks, there are multiple structures in the language\nthat create their own separate scopes. For/while loops, if/else statements,\nfunctions, normal blocks, etc. This also affects the interpretation of `defer`.\nFor example, if you use `defer` inside a for loop, then, the given expression\nwill be executed everytime this specific for loop exits its own scope.\n\nBefore we continue, is worth emphasizing that the `defer` keyword is an \"unconditional defer\".\nWhich means that the given expression will be executed no matter how the code exits\nthe current scope. For example, your code might exit the current scope because of an error value\nbeing generated, or, because of a return statement, or, a break statement, etc.\n\n\n\n### The `errdefer` keyword {#sec-errdefer1}\n\nOn the previous section, we have discussed the `defer` keyword, which you can use to\nregister an expression to be executed at the exit of the current scope.\nBut this keyword has a brother, which is the `errdefer` keyword. While `defer`\nis an \"unconditional defer\", the `errdefer` keyword is a \"conditional defer\".\nWhich means that the given expression is executed only when you exit the current\nscope on a very specific circumstance.\n\nIn more details, the expression given to `errdefer` is executed only when an error occurs in the current scope.\nTherefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope\nin a normal situation, without errors, the expression given to `errdefer` is not executed.\n\nThis makes the `errdefer` keyword one of the many tools available in Zig for error handling.\nIn this section, we are more concerned with the control flow aspects around `errdefer`.\nBut we are going to discuss `errdefer` later as a error handling tool in @sec-errdefer2.\n\nThe code example below demonstrates three things:\n\n- that `defer` is an \"unconditional defer\", because the given expression get's executed regardless of how the function `foo()` exits its own scope.\n- that `errdefer` is executed because the function `foo()` returned an error value.\n- that `defer` and `errdefer` expressions are executed in a LIFO (*last in, first out*) order.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\nWhen I say that \"defer expressions\" are executed in a LIFO order, what I want to say is that\nthe last `defer` or `errdefer` expressions in the code are the first ones to be executed.\nYou could also interpret this as: \"defer expressions\" are executed from bottom to top, or,\nfrom last to first.\n\nTherefore, if I change the order of the `defer` and `errdefer` expressions, you will notice that\nthe value of `i` that get's printed to the console changes to 1. This doesn't mean that the\n`defer` expression was not executed in this case. This actually means that the `defer` expression\nwas executed only after the `errdefer` expression. The code example below demonstrates this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\n\n\n### For loops\n\nA loop allows you to execute the same lines of code multiple times,\nthus, creating a \"repetition space\" in the execution flow of your program.\nLoops are particularly useful when we want to replicate the same function\n(or the same set of commands) over different inputs.\n\nThere are different types of loops available in Zig. But the most\nessential of them all is probably the *for loop*. A for loop is\nused to apply the same piece of code over the elements of a slice, or, an array.\n\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from\nother languages. You start with the `for` keyword, then, you\nlist the items that you want to iterate\nover inside a pair of parentheses. Then, inside of a pair of pipes (`|`)\nyou should declare an identifier that will serve as your iterator, or,\nthe \"repetition index of the loop\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (items) |value| {\n    // code to execute\n}\n```\n:::\n\n\n\n\nTherefore, instead of using a `(value in items)` syntax,\nin Zig, for loops use the syntax `(items) |value|`. In the example\nbelow, you can see that we are looping through the items\nof the array stored at the object `name`, and printing to the\nconsole the decimal representation of each character in this array.\n\nIf we wanted, we could also iterate through a slice (or a portion) of\nthe array, instead of iterating through the entire array stored in the `name` object.\nJust use a range selector to select the section you want. For example,\nI could provide the expression `name[0..3]` to the for loop, to iterate\njust through the first 3 elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n80 | 101 | 100 | 114 | 111 | \n```\n\n\n:::\n:::\n\n\n\n\nIn the above example we are using the value itself of each\nelement in the array as our iterator. But there are many situations where\nwe need to use an index instead of the actual values of the items.\n\nYou can do that by providing a second set of items to iterate over.\nMore precisely, you provide the range selector `0..` to the for loop. So,\nyes, you can use two different iterators at the same time in a for\nloop in Zig.\n\nBut remember from @sec-assignments that, every object\nyou create in Zig must be used in some way. So if you declare two iterators\nin your for loop, you must use both iterators inside the for loop body.\nBut if you want to use just the index iterator, and not use the \"value iterator\",\nthen, you can discard the value iterator by maching the\nvalue items to the underscore character, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n:::\n\n\n\n\n```\n0 | 1 | 2 | 3 | 4 |\n```\n\n\n### While loops\n\nA while loop is created from the `while` keyword. A `for` loop\niterates through the items of an array, but a `while` loop\nwill loop continuously, and infinitely, until a logical test\n(specified by you) becomes false.\n\nYou start with the `while` keyword, then, you define a logical\nexpression inside a pair of parentheses, and the body of the\nloop is provided inside a pair of curly braces, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\nYou can also specify the increment expression to be used at the beginning of a while loop.\nTo do that, we write the increment expression inside a pair of parentheses after a colon character (`:`).\nThe code example below demonstrates this other pattern.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\n### Using `break` and `continue`\n\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using\nthe keywords `break` and `continue`, respectively. The `while` loop presented in the next code example is,\nat first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to `true`.\nBut what makes this `while` loop stop when the `i` object reaches the count\n10? It is the `break` keyword!\n\nInside the while loop, we have an if statement that is constantly checking if the `i` variable\nis equal to 10. Since we are incrementing the value of `i` at each iteration of the\nwhile loop, this `i` object will eventually be equal to 10, and when it is, the if statement\nwill execute the `break` expression, and, as a result, the execution of the while loop is stopped.\n\nNotice the use of the `expect()` function from the Zig Standard Library after the while loop.\nThis `expect()` function is an \"assert\" type of function.\nThis function checks if the logical test provided is equal to true. If so, the function do nothing.\nOtherwise (i.e. the logical test is equal to false), the function raises an assertion error.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nEverything worked!\n```\n\n\n:::\n:::\n\n\n\n\nSince this code example was executed successfully by the `zig` compiler,\nwithout raising any errors, we known that, after the execution of the while loop,\nthe `i` object is equal to 10. Because if it wasn't equal to 10, an error would have\nbeen raised by `expect()`.\n\nNow, in the next example, we have a use case for\nthe `continue` keyword. The if statement is constantly\nchecking if the current index is a multiple of 2. If\nit is, we jump to the next iteration of the loop.\nOtherwise, the loop just prints the current index to the console.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 3 | 5 | \n```\n\n\n:::\n:::\n\n\n\n\n\n\n## Function parameters are immutable {#sec-fun-pars}\n\nWe have already discussed a lot of the syntax behind function declarations in @sec-root-file and @sec-main-file.\nBut I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig.\nIn summary, function parameters are immutable in Zig.\n\nTake the code example below, where we declare a simple function that just tries to add\nsome amount to the input integer, and returns the result back. If you look closely\nat the body of this `add2()` function, you will notice that we try\nto save the result back into the `x` function argument.\n\nIn other words, this function not only uses the value that it received through the function argument\n`x`, but it also tries to change the value of this function argument, by assigning the addition result\ninto `x`. However, function arguments in Zig are immutable. You cannot change their values, or, you\ncannot assign values to them inside the body's function.\n\nThis is the reason why, the code example below does not compile successfully. If you try to compile\nthis code example, you will get a compile error message about \"trying to change the value of a\nimmutable (i.e. constant) object\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n\n\n```\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n```\n\n\n### A free optimization\n\nIf a function argument receives as input an object whose data type is\nany of the primitive types that we have listed in @sec-primitive-data-types,\nthis object is always passed by value to the function. In other words, this object\nis copied into the function stack frame.\n\nHowever, if the input object have a more complex data type, for example, it might\nbe a struct instance, or an array, or an union value, etc., in cases like that, the `zig` compiler\nwill take the liberty of deciding for you which strategy is best. Thus, the `zig` compiler will\npass your object to the function either by value, or by reference. The compiler will always\nchoose the strategy that is faster for you.\nThis optimization that you get for free is possible only because function arguments are\nimmutable in Zig.\n\n\n### How to overcome this barrier\n\nThere are some situations where you might need to change the value of your function argument\ndirectly inside the function's body. This happens more often when we are passing\nC structs as inputs to Zig functions.\n\nIn a situation like this, you can overcome this barrier by using a pointer. In other words,\ninstead of passing a value as input to the argument, you can pass a \"pointer to value\" instead.\nYou can change the value that the pointer points to, by dereferencing it.\n\nTherefore, if we take our previous `add2()` example, we can change the value of the\nfunction argument `x` inside the function's body by marking the `x` argument as a\n\"pointer to a `u32` value\" (i.e. `*u32` data type), instead of a `u32` value.\nBy making it a pointer, we can finally alter the value of this function argument directly inside\nthe body of the `add2()` function. You can see that the code example below compiles successfully.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n```\n:::\n\n\n\n\n```\nResult: 6\n```\n\n\nEven in this code example above, the `x` argument is still immutable. Which means that the pointer itself is immutable.\nTherefore, you cannot change the memory address that it points to. However, you can dereference the pointer\nto access the value that it points to, and also, to change this value, if you need to.\n\n\n\n\n\n## Structs and OOP {#sec-structs-and-oop}\n\nZig is a language more closely related to C (which is a procedural language),\nthan it is to C++ or Java (which are object-oriented languages). Because of that, you do not\nhave advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or\nclass inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\n\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C.\nYou give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can\nalso register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object\nthat you create with this new type, will always have these methods available and associated with them.\n\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which\nis used to construct (or, to instantiate) every object of this particular class, and we also have\na destructor method (or a destructor function), which is the function responsible for destroying\nevery object of this class.\n\nIn Zig, we normally declare the constructor and the destructor methods\nof our structs, by declaring an `init()` and a `deinit()` methods inside the struct.\nThis is just a naming convention that you will find across the entire Zig Standard Library.\nSo, in Zig, the `init()` method of a struct is normally the constructor method of the class represented by this struct.\nWhile the `deinit()` method is the method used for destroying an existing instance of that struct.\n\nThe `init()` and `deinit()` methods are both used extensively in Zig code, and you will see both of\nthem being used when we talk about allocators in @sec-allocators.\nBut, as another example, let's build a simple `User` struct to represent a user of some sort of system.\n\nIf you look at the `User` struct below, you can see the `struct` keyword.\nNotice the data members of this struct: `id`, `name` and `email`. Every data member has its\ntype explicitly annotated, with the colon character (`:`) syntax that we described earlier in @sec-root-file.\nBut also notice that every line in the struct body that describes a data member, ends with a comma character (`,`).\nSo every time you declare a data member in your Zig code, always end the line with a comma character, instead\nof ending it with the traditional semicolon character (`;`).\n\nNext, we have registered an `init()` function as a method\nof this `User` struct. This `init()` method is the constructor method that we will use to instantiate\nevery new `User` object. That is why this `init()` function returns a new `User` object as result.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    pub fn init(id: u64,\n                name: []const u8,\n                email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    pub fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\npedro\n```\n\n\n:::\n:::\n\n\n\n\nThe `pub` keyword plays an important role in struct declarations, and OOP in Zig.\nEvery method that you declare in your struct that is marked with the keyword `pub`,\nbecomes a public method of this particular struct.\n\nSo every method that you create inside your struct, is, at first, a private method\nof that struct. Meaning that, this method can only be called from within this\nstruct. But, if you mark this method as public, with the keyword `pub`, then,\nyou can call the method directly from an instance of the `User` struct.\n\nIn other words, the functions marked by the keyword `pub`\nare members of the public API of that struct.\nFor example, if I did not mark the `print_name()` method as public,\nthen, I could not execute the line `u.print_name()`. Because I would\nnot be authorized to call this method directly in my code.\n\n\n\n### Anonymous struct literals {#sec-anonymous-struct-literals}\n\nYou can declare a struct object as a literal value. When we do that, we normally specify the\ndata type of this struct literal by writing its data type just before the opening curly brace.\nFor example, I could write a struct literal value of the type `User` that we have defined\nin the previous section like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n```\n:::\n\n\n\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a\nstruct literal, but not specify explicitly the type of this particular struct.\nAn anonymous struct is written by using the syntax `.{}`. So, we essentially\nreplaced the explicit type of the struct literal with a dot character (`.`).\n\nAs we described in @sec-type-inference, when you put a dot before a struct literal,\nthe type of this struct literal is automatically inferred by the `zig` compiler.\nIn essence, the `zig` compiler will look for some hint of what is the type of that struct.\nThis hint can be the type annotation of a function argument,\nor the return type annotation of the function that you are using, or the type annotation\nof an existing object.\nIf the compiler does find such type annotation, it will use this\ntype in your literal struct.\n\nAnonymous structs are very commonly used as inputs to function arguments in Zig.\nOne example that you have seen already constantly, is the `print()`\nfunction from the `stdout` object.\nThis function takes two arguments.\nThe first argument, is a template string, which should\ncontain string format specifiers in it, which tells how the values provided\nin the second argument should be printed into the message.\n\nWhile the second argument is a struct literal that lists the values\nto be printed into the template message specified in the first argument.\nYou normally want to use an anonymous struct literal here, so that the\n`zig` compiler do the job of specifying the type of this particular\nanonymous struct for you.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello, world!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Struct declarations must be constant\n\nTypes in Zig must be `const` or `comptime` (we are going to talk more about comptime in @sec-comptime).\nWhat this means is that you cannot create a new data type, and mark it as variable with the `var` keyword.\nSo struct declarations are always constant. You cannot declare a new struct type using the `var` keyword.\nIt must be `const`.\n\nIn the `Vec3` example below, this declaration is allowed because I'm using the `const` keyword\nto declare this new data type.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n```\n:::\n\n\n\n\n\n### The `self` method argument {#sec-self-arg}\n\nIn every language that have OOP, when we declare a method of some class or struct, we\nusually declare this method as a function that has a `self` argument.\nThis `self` argument is the reference to the object itself from which the method\nis being called from.\n\nIt is not mandatory to use this `self` argument. But why would you not use this `self` argument?\nThere is no reason to not use it. Because the only way to get access to the data stored in the\ndata members of your struct is to access them through this `self` argument.\nIf you don't need to use the data in the data members of your struct inside your method, you very likely don't need\na method. You can just declare this logic as a simple function, outside of your\nstruct declaration.\n\n\nTake the `Vec3` struct below. Inside this `Vec3` struct we declared a method named `distance()`.\nThis method calculates the distance between two `Vec3` objects, by following the distance\nformula in euclidean space. Notice that this `distance()` method takes two `Vec3` objects\nas input, `self` and `other`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n```\n:::\n\n\n\n\n\nThe `self` argument corresponds to the `Vec3` object from which this `distance()` method\nis being called from. While the `other` is a separate `Vec3` object that is given as input\nto this method. In the example below, the `self` argument corresponds to the object\n`v1`, because the `distance()` method is being called from the `v1` object,\nwhile the `other` argument corresponds to the object `v2`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n```\n:::\n\n\n\n\n```\nDistance: 3.3970575502926055\n```\n\n\n\n### About the struct state\n\nSometimes you don't need to care about the state of your struct object. Sometimes, you just need\nto instantiate and use the objects, without altering their state. You can notice that when you have methods\ninside your struct declaration that might use the values that are present in the data members, but they\ndo not alter the values in these data members of the struct in anyway.\n\nThe `Vec3` struct that was presented in @sec-self-arg is an example of that.\nThis struct have a single method named `distance()`, and this method does use the values\npresent in all three data members of the struct (`x`, `y` and `z`). But at the same time,\nthis method does not change the values of these data members at any point.\n\nAs a result of that, when we create `Vec3` objects we usually create them as\nconstant objects, like the `v1` and `v2` objects presented in @sec-self-arg.\nWe can create them as variable objects with the `var` keyword,\nif we want to. But because the methods of this `Vec3` struct do not change\nthe state of the objects in any point, it's unnecessary to mark them\nas variable objects.\n\nBut why? Why am I talking about this here? It's because the `self` argument\nin the methods are affected depending on whether the\nmethods present in a struct change or don't change the state of the object itself.\nMore specifically, when you have a method in a struct that changes the state\nof the object (i.e. changes the value of a data member), the `self` argument\nin this method must be annotated in a different manner.\n\nAs I described in @sec-self-arg, the `self` argument in methods of\na struct is the argument that receives as input the object from which the method\nwas called from. We usually annotate this argument in the methods by writing `self`,\nfollowed by the colon character (`:`), and the data type of the struct to which\nthe method belongs to (e.g. `User`, `Vec3`, etc.).\n\nIf we take the `Vec3` struct that we defined in the previous section as an example,\nwe can see in the `distance()` method that this `self` argument is annotated as\n`self: Vec3`. Because the state of the `Vec3` object is never altered by this\nmethod.\n\nBut what if we do have a method that alters the state of the object, by altering the\nvalues of its data members, how should we annotate `self` in this instance? The answer is:\n\"we should annotate `self` as a pointer of `x`, instead of just `x`\".\nIn other words, you should annotate `self` as `self: *x`, instead of annotating it\nas `self: x`.\n\nIf we create a new method inside the `Vec3` object that, for example, expands the\nvector by multiplying its coordinates by a factor of two, then, we need to follow\nthis rule specified in the previous paragraph. The code example below demonstrates\nthis idea:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n```\n:::\n\n\n\n\nNotice in the code example above that we have added a new method\nto our `Vec3` struct named `twice()`. This method doubles the\ncoordinate values of our vector object. In the\ncase of the `twice()` method, we annotated the `self` argument as `*Vec3`,\nindicating that this argument receives a pointer (or a reference, if you prefer to call it this way)\nto a `Vec3` object as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n```\n:::\n\n\n\n\n```\nDoubled: 8.4\n```\n\n\n\nNow, if you change the `self` argument in this `twice()` method to `self: Vec3`, like in the\n`distance()` method, you will get the compiler error exposed below as result. Notice that this\nerror message is showing a line from the `twice()` method body,\nindicating that you cannot alter the value of the `x` data member.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n```\n:::\n\n\n\n\n```\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\n```\n\nThis error message indicates that the `x` data member belongs to a constant object,\nand, because of that, it cannot be changed. Ultimately, this error message\nis telling us that the `self` argument is constant.\n\nIf you take some time, and think hard about this error message, you will understand it.\nYou already have the tools to understand why we are getting this error message.\nWe have talked about it already in @sec-fun-pars.\nSo remember, every function argument is immutable in Zig, and `self`\nis no exception to this rule.\n\nIn this example, we marked the `v3` object as a variable object.\nBut this does not matter. Because it is not about the input object, it is about\nthe function argument.\n\nThe problem begins when we try to alter the value of `self` directly, which is a function argument,\nand, every function argument is immutable by default. You may ask yourself how can we overcome\nthis barrier, and once again, the solution was also discussed in @sec-fun-pars.\nWe overcome this barrier, by explicitly marking the `self` argument as a pointer.\n\n\n::: {.callout-note}\nIf a method of your `x` struct alters the state of the object, by\nchanging the value of any data member, then, remember to use `self: *x`,\ninstead of `self: x` in the function signature of this method.\n:::\n\n\nYou could also interpret the content discussed in this section as:\n\"if you need to alter the state of your `x` struct object in one of its methods,\nyou must explicitly pass the `x` struct object by reference to the `self` argument of this method\".\n\n\n\n## Type inference {#sec-type-inference}\n\nZig is a strongly typed language. But, there are some situations\nwhere you don't have to explicitly write the type of every single object in your source code,\nas you would expect from a traditional strongly typed language, such as C and C++.\n\nIn some situations, the `zig` compiler can use type inference to solve the data types for you, easing some of\nthe burden that you carry as a developer.\nThe most common way this happens is through function arguments that receive struct objects\nas input.\n\nIn general, type inference in Zig is done by using the dot character (`.`).\nEverytime you see a dot character written before a struct literal, or before an enum value, or something like that,\nyou know that this dot character is playing a special part in this place. More specifically, it is\ntelling the `zig` compiler something along the lines of: \"Hey! Can you infer the type of this\nvalue for me? Please!\". In other words, this dot character is playing a similar role as the `auto` keyword in C++.\n\nI gave you some examples of this in @sec-anonymous-struct-literals, where we used anonymous struct literals.\nAnonymous struct literals are, struct literals that use type inference to\ninfer the exact type of this particular struct literal.\nThis type inference is done by looking for some minimal hint of the correct data type to be used.\nYou could say that the `zig` compiler looks for any neighbouring type annotation that might tell it\nwhat the correct type would be.\n\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in @sec-switch).\nI also gave some other examples of type inference in @sec-switch, where we were inferring the data types of enum values listed inside\nof switch statements (e.g. `.DE`).\nBut as another example, take a look at this `fence()` function reproduced below,\nwhich comes from the [`atomic.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig)[^fence-fn]\nof the Zig Standard Library.\n\n[^fence-fn]: <https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig>.\n\nThere are a lot of things in this function that we haven't talked about yet, such as:\nwhat `comptime` means? `inline`? `extern`?\nLet's just ignore all of these things, and focus solely on the switch statement\nthat is inside this function.\n\nWe can see that this switch statement uses the `order` object as input. This `order`\nobject is one of the inputs of this `fence()` function, and we can see in the type annotation,\nthat this object is of type `AtomicOrder`. We can also see a bunch of values inside the\nswitch statements that begin with a dot character, such as `.release` and `.acquire`.\n\nBecause these weird values contain a dot character before them, we are asking the `zig`\ncompiler to infer the types of these values inside the switch statement. Then, the `zig`\ncompiler is looking into the current context where these values are being used, and it is\ntrying to infer the types of these values.\n\nSince they are being used inside a switch statement, the `zig` compiler looks into the type\nof the input object given to the switch statement, which is the `order` object in this case.\nBecause this object have type `AtomicOrder`, the `zig` compiler infers that these values\nare data members from this type `AtomicOrder`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic => @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire => tsan.__tsan_acquire(addr),\n            .release => tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst => {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n```\n:::\n\n\n\n\nThis is how basic type inference is done in Zig. If we didn't use the dot character before\nthe values inside this switch statement, then, we would be forced to explicitly write\nthe data types of these values. For example, instead of writing `.release` we would have to\nwrite `AtomicOrder.release`. We would have to do this for every single value\nin this switch statement, and this is a lot of work. That is why type inference\nis commonly used on switch statements in Zig.\n\n\n\n## Type casting {#sec-type-cast}\n\nIn this section, I want to discuss type casting (or, type conversion) with you.\nWe use type casting when we have an object of type \"x\", and we want to convert\nit into an object of type \"y\", i.e. we want to change the data type of the object.\n\nMost languages have a formal way to perform type casting. In Rust for example, we normally\nuse the keyword `as`, and in C, we normally use the type casting syntax, e.g. `(int) x`.\nIn Zig, we use the `@as()` built-in function to cast an object of type \"x\", into\nan object of type \"y\".\n\nThis `@as()` function is the preferred way to perform type conversion (or type casting)\nin Zig. Because it is explicit, and, it also performs the casting only if it\nis unambiguous and safe. To use this function, you just provide the target data type\nin the first argument, and, the object that you want cast as the second argument.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file9f8940318094.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\nThis is the general way to perform type casting in Zig. But remember, `@as()` works only when casting\nis unambiguous and safe, and there are situations where these assumptions do not hold. For example,\nwhen casting an integer value into a float value, or vice-versa, it is not clear to the compiler\nhow to perform this conversion safely.\n\nTherefore, we need to use specialized \"casting functions\" in such situations.\nFor example, if you want to cast an integer value into a float value, then, you\nshould use the `@floatFromInt()` function. In the inverse scenario, you should use\nthe `@intFromFloat()` function.\n\nIn these functions, you just provide the object that you want to\ncast as input. Then, the target data type of the \"type casting operation\" is determined by\nthe type annotation of the object where you are saving the results.\nIn the example below, we are casting the object `x` into a value of type `f32`,\nbecause the object `y`, which is where we are saving the results, is annotated\nas an object of type `f32`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file9f8954828844.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\nAnother built-in function that is very useful when performing type casting operations is `@ptrCast()`.\nIn essence, we use the `@as()` built-in function when we want to explicit convert (or cast) a Zig value/object\nfrom a type \"x\" to a type \"y\", etc. However, pointers (we are going to discuss pointers\nin more depth in @sec-pointer) are a special type of object in Zig,\ni.e. they are treated differently from \"normal objects\".\n\nEverytime a pointer is involved in some \"type casting operation\" in Zig, the `@ptrCast()` function is used.\nThis function works similarly to `@floatFromInt()`.\nYou just provide the pointer object that you want to cast as input to this function, and the\ntarget data type is, once again, determined by the type annotation of the object where the results are being\nstored.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file9f8944ca02e1.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## Modules\n\nWe already talked about what modules are, and also, how to import other modules into\nyour current module via *import statements*. Every Zig module (i.e. a `.zig` file) that you write in your project\nis internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the\nZig Standard Library into our current module.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n```\n:::\n\n\n\n\nWhen we want to access the functions and objects from the standard library, we\nare basically accessing the data members of the struct stored in the `std`\nobject. That is why we use the same syntax that we use in normal structs, with the dot operator (`.`)\nto access the data members and methods of the struct.\n\nWhen this \"import statement\" get's executed, the result of this expression is a struct\nobject that contains the Zig Standard Library modules, global variables, functions, etc.\nAnd this struct object get's saved (or stored) inside the constant object named `std`.\n\n\nTake the [`thread_pool.zig` module from the project `zap`](https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig)[^thread]\nas an example. This module is written as if it was\na big struct. That is why we have a top-level and public `init()` method\nwritten in this module. The idea is that all top-level functions written in this\nmodule are methods from the struct, and all top-level objects and struct declarations\nare data members of this struct. The module is the struct itself.\n\n[^thread]: <https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig>\n\n\nSo you would import and use this module by doing something like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst ThreadPool = @import(\"thread_pool.zig\");\nconst num_cpus = std.Thread.getCpuCount()\n    catch @panic(\"failed to get cpu core count\");\nconst num_threads = std.math.cast(u16, num_cpus)\n    catch std.math.maxInt(u16);\nconst pool = ThreadPool.init(\n    .{ .max_threads = num_threads }\n);\n```\n:::\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/03-unittests/execute-results/html.json b/_freeze/Chapters/03-unittests/execute-results/html.json
index 73102f4a..37cb076d 100644
--- a/_freeze/Chapters/03-unittests/execute-results/html.json
+++ b/_freeze/Chapters/03-unittests/execute-results/html.json
@@ -2,10 +2,8 @@
   "hash": "28d3cb0fae2775c98b5945221b3f555c",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Unit tests {#sec-unittests}\n\nIn this chapter, I want to dive in on how unit tests are done in\nZig. We are going to talk about what is the testing workflow in Zig, and\nalso, about the `test` command from the `zig` compiler.\n\n\n## Introducing the `test` block\n\nIn Zig, unit tests are written inside a `test` declaration, or, how I prefer to call it, inside a `test` block.\nEvery `test` block is written by using the keyword `test`.\nYou can optionally use a string literal to write a label, which is responsible for identifying\nthe specific group of unit tests that you are writing inside this specific `test` block.\n\nIn the example below, we are testing if the sum of two objects (`a` and `b`)\nis equal to 4. The `expect()` function from the Zig Standard Library\nis a function that receives a logical test as input. If this logical test\nresults in `true`, then, the test passes. But if it results\nin `false`, then, the test fails.\n\nYou can write any Zig code you want inside a `test` block.\nPart of this code might be some necessary commands to setup your testing\nenvironment, or just initializing some objects that you need to use\nin your unit tests.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest \"testing simple sum\" {\n    const a: u8 = 2;\n    const b: u8 = 2;\n    try expect((a + b) == 4);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file153713a3190e.test.testing simple sum...OKA\n  All 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\nYou can have multiple `test` blocks written on the same Zig module.\nAlso, you can mix `test` blocks with your source code, with no problems\nor consequences. If you mix `test` blocks with your normal source code,\nwhen you execute the `build`, `build-exe`, `build-obj` or `build-lib` commands from the\n`zig` compiler that we exposed at @sec-compile-code, these `test` blocks are automatically\nignored by the compiler.\n\nIn other words, the `zig` compiler builds and execute your unit tests only\nwhen you ask it to. By default, the compiler always ignore `test`\nblocks written in your Zig modules. The compiler normally checks only if\nthere are any syntax errors in these `test` blocks.\n\nIf you take a look at the source code for most of the files present in the\nZig Standard Library[^zig-std-lib], you can see that the `test` blocks\nare written together with the normal source code of the library.\nYou can see this for example, at the [`array_list` module](https://github.com/ziglang/zig/blob/master/lib/std/array_list.zig)[^zig-array].\nSo, the standard that the Zig developers decided to adopt\nis to keep their unit tests together with the source code\nof the functionality that they are testing.\n\nEach programmer might have a different opinion on this.\nSome of them might prefer to keep unit tests separate from the actual\nsource code of their application. If that is your case, you can\nsimply create a separate `tests` folder in your project, and\nstart writing Zig modules that contains only unit tests (as you would normally do\non a Python project with `pytest`, for example), and everything will work fine.\nIt boils down to which is your preference here.\n\n[^zig-std-lib]: <https://github.com/ziglang/zig/tree/master/lib/std>\n[^zig-array]: <https://github.com/ziglang/zig/blob/master/lib/std/array_list.zig>\n\n\n## How to run your tests\n\nIf the `zig` compiler ignores any `test` block by default, how can\nyou compile and run your unit tests? The answer is the `test` command from\nthe `zig` compiler. By running the `zig test` command, the compiler will\nfind every instance of a `test` block in your Zig modules, and, it will\ncompile and run the unit tests that you wrote.\n\n\n```bash\nzig test simple_sum.zig\n```\n\n```\n1/1 simple_sum.test.testing simple sum... OK\nAll 1 tests passed.\n```\n\n\n## Testing memory allocations\n\nOne of the advantages of Zig is that it offers great tools\nthat help us, programmers, to avoid (but also detect) memory problems, such as\nmemory leaks and double-frees. The `defer` keyword\nis especially helpful in this regard.\n\nWhen developing your source code, you, the programmer, is responsible for making\nsure that your code do not produce such problems. However,\nyou can also use a special type of an allocator object in Zig\nthat is capable of automatically detecting such problems for you.\nThis is the `std.testing.allocator` object.\nThis allocator object offers some basic memory safety detection\nfeatures, which are capable of detecting memory leaks.\n\nAs we described at @sec-heap, to allocate memory on the heap, you need\nto use an allocator object, and your functions that use these objects to allocate memory\non the heap, should receive an allocator object as one of its inputs.\nEvery memory on the heap that you allocate using these allocator objects,\nmust also be freed using this same allocator object.\n\nSo, if you want to test the memory allocations performed by your functions,\nand make sure that you don't have problems in these allocations, you can simply\nwrite unit tests for these functions, where you provide the\n`std.testing.allocator` object as input to these functions.\n\nLook at the example below, where I'm defining a function that clearly causes\na memory leak. Because we allocate memory, but, at the same time,\nwe do not free this allocated memory at any point. So, when the function\nreturns, we lose the reference to the `buffer` object, which contains\nthe allocated memory, and, as a result, we can no longer free this memory.\n\nNotice that, inside a `test` block I execute this function with\nthe `std.testing.allocator`. The allocator object was capable\nof looking deeper in our program, and detecting the memory leak. As a result,\nthis allocator object returns an error message of \"memory leaked\", and also,\na stack trace showing the exact point where the memory was leaked.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nfn some_memory_leak(allocator: Allocator) !void {\n    const buffer = try allocator.alloc(u32, 10);\n    _ = buffer;\n    // Return without freeing the\n    // allocated memory\n}\n\ntest \"memory leak\" {\n    const allocator = std.testing.allocator;\n    try some_memory_leak(allocator);\n}\n```\n:::\n\n\n\n\n```\nTest [1/1] leak_memory.test.memory leak...\n    [gpa] (err): memory address 0x7c1fddf39000 leaked: \n./ZigExamples/debugging/leak_memory.zig:4:39: 0x10395f2\n    const buffer = try allocator.alloc(u32, 10);\n                                      ^\n./ZigExamples/debugging/leak_memory.zig:12:25: 0x10398ea\n    try some_memory_leak(allocator);\n\n... more stack trace\n```\n\n\n## Testing errors\n\nOne common style of unit tests are those that look for\nspecific errors in your functions. In other words, you write\na unit test that tries to assert if a specific function call\nreturns any error, or a specific type of error.\n\nIn C++ you would normally write this style of unit tests using, for example,\nthe functions `REQUIRE_THROWS()` or `CHECK_THROWS()` from the [`Catch2` test framework](https://github.com/catchorg/Catch2/tree/devel)[^catch2].\nIn the case of a Python project, you would probably use the\n[`raises()` function from `pytest`](https://docs.pytest.org/en/7.1.x/reference/reference.html#pytest-raises)[^pytest].\nWhile in Rust, you would probably use `assert_eq!()` in conjunction with `Err()`.\n\n[^pytest]: <https://docs.pytest.org/en/7.1.x/reference/reference.html#pytest-raises>\n[^catch2]: <https://github.com/catchorg/Catch2/tree/devel>\n\n\nBut in Zig, we use the `expectError()` function, from the `std.testing` module.\nWith this function, you can test if a specific function call returns the exact\ntype of error that you expect it to return. To use this function, you first write\n`try expectError()`. Then, on the first argument, you provide the type of error that you\nare expecting from the function call. Then, on the second argument, you write\nthe function call that you expect to fail.\n\nThe code example below demonstrates such type of unit test in Zig.\nNotice that, inside the function `alloc_error()` we are allocating\n100 bytes of memory, or, an array of 100 elements, for the object `ibuffer`. However,\nin the `test` block, we are using the `FixedBufferAllocator()`\nallocator object, which is limited to 10 bytes of space, because\nthe object `buffer`, which we provided to the allocator object,\nhave only 10 bytes of space.\n\nThat is why, the `alloc_error()` function raises an `OutOfMemory` error\non this case.\nBecause this function is trying to allocate more space than the allocator\nobject allows.\nSo, in essence, we are testing for a specific type of error,\nwhich is `OutOfMemory`. If the `alloc_error()` function returns any other type of error,\nthen, the `expectError()` function would make the entire test fail.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst expectError = std.testing.expectError;\nfn alloc_error(allocator: Allocator) !void {\n    var ibuffer = try allocator.alloc(u8, 100);\n    defer allocator.free(ibuffer);\n    ibuffer[0] = 2;\n}\n\ntest \"testing error\" {\n    var buffer: [10]u8 = undefined;\n    var fba = std.heap.FixedBufferAllocator.init(&buffer);\n    const allocator = fba.allocator();\n    try expectError(error.OutOfMemory, alloc_error(allocator));\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file1537546f248.test.testing error...OKAll 1 t\n  tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n## Testing simple equalities\n\nIn Zig, there are some different ways you can test for an equality.\nYou already saw that we can use `expect()` with the logical operator `==`\nto essentially reproduce an equality test. But we also have\nsome other helper functions that you should know about, especially\n`expectEqual()`, `expectEqualSlices()` and `expectEqualStrings()`.\n\n\nThe `expectEqual()` function, as the name suggests, is a classic\ntest equality function. It receives two objects as input. The first\nobject is the value that you expect to be in the second object.\nWhile second object is the object you have, or, the object that your application\nproduced as result. So, with `expectEqual()` you are essentially\ntesting if the values stored inside these two objects\nare equal or not.\n\nYou can see in the example below that, the test performed by\n`expectEqual()` failed. Because the objects `v1` and `v2` contain\ndifferent values in them.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"values are equal?\" {\n    const v1 = 15;\n    const v2 = 18;\n    try std.testing.expectEqual(v1, v2);\n}\n```\n:::\n\n\n\n\n```\n1/1 ve.test.values are equal?...\n    expected 15, found 18\n    FAIL (TestExpectedEqual)\nve.zig:5:5: test.values are equal? (test)\n    try std.testing.expectEqual(v1, v2);\n    ^\n0 passed; 0 skipped; 1 failed.\n```\n\n\nAlthough useful, the `expectEqual()` function does not work with arrays.\nFor testing if two arrays are equal, you should use the `expectEqualSlices()`\nfunction instead. This function have three arguments. First, you provide\nthe data type contained in both arrays that you are trying to compare.\nWhile the second and third arguments corresponds to the array objects that you want to compare.\n\nIn the example below, we are using this function to test if two array\nobjects (`array1` and `array2`) are equal or not. Since they\nare in fact equal, the unit test passed with no errors.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"arrays are equal?\" {\n    const array1 = [3]u32{1, 2, 3};\n    const array2 = [3]u32{1, 2, 3};\n    try std.testing.expectEqualSlices(\n        u32, &array1, &array2\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file15377bbafb73.test.arrays are equal?...OKAl\n  ll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\nAt last, you might also want to use the `expectEqualStrings()` function.\nAs the name suggests, you can use this function to test if two strings\nare equal or not. Just provide the two string objects that you want to compare,\nas inputs to the function.\n\nIf the function finds any existing differences between the two strings,\nthen, the function will raise an error, and also, print an error message\nthat shows the exact difference between the two string objects provided,\nas the example below demonstrates:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"strings are equal?\" {\n    const str1 = \"hello, world!\";\n    const str2 = \"Hello, world!\";\n    try std.testing.expectEqualStrings(\n        str1, str2\n    );\n}\n```\n:::\n\n\n\n\n```\n1/1 t.test.strings are equal?... \n====== expected this output: =========\nhello, world!␃\n======== instead found this: =========\nHello, world!␃\n======================================\nFirst difference occurs on line 1:\nexpected:\nhello, world!\n^ ('\\x68')\nfound:\nHello, world!\n^ ('\\x48')\n```\n\n",
-    "supporting": [
-      "03-unittests_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Unit tests {#sec-unittests}\n\nIn this chapter, I want to dive in on how unit tests are done in\nZig. We are going to talk about what is the testing workflow in Zig, and\nalso, about the `test` command from the `zig` compiler.\n\n\n## Introducing the `test` block\n\nIn Zig, unit tests are written inside a `test` declaration, or, how I prefer to call it, inside a `test` block.\nEvery `test` block is written by using the keyword `test`.\nYou can optionally use a string literal to write a label, which is responsible for identifying\nthe specific group of unit tests that you are writing inside this specific `test` block.\n\nIn the example below, we are testing if the sum of two objects (`a` and `b`)\nis equal to 4. The `expect()` function from the Zig Standard Library\nis a function that receives a logical test as input. If this logical test\nresults in `true`, then, the test passes. But if it results\nin `false`, then, the test fails.\n\nYou can write any Zig code you want inside a `test` block.\nPart of this code might be some necessary commands to setup your testing\nenvironment, or just initializing some objects that you need to use\nin your unit tests.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest \"testing simple sum\" {\n    const a: u8 = 2;\n    const b: u8 = 2;\n    try expect((a + b) == 4);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filea5b06c1ec326.test.testing simple sum...OKA\n  All 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\nYou can have multiple `test` blocks written on the same Zig module.\nAlso, you can mix `test` blocks with your source code, with no problems\nor consequences. If you mix `test` blocks with your normal source code,\nwhen you execute the `build`, `build-exe`, `build-obj` or `build-lib` commands from the\n`zig` compiler that we exposed at @sec-compile-code, these `test` blocks are automatically\nignored by the compiler.\n\nIn other words, the `zig` compiler builds and execute your unit tests only\nwhen you ask it to. By default, the compiler always ignore `test`\nblocks written in your Zig modules. The compiler normally checks only if\nthere are any syntax errors in these `test` blocks.\n\nIf you take a look at the source code for most of the files present in the\nZig Standard Library[^zig-std-lib], you can see that the `test` blocks\nare written together with the normal source code of the library.\nYou can see this for example, at the [`array_list` module](https://github.com/ziglang/zig/blob/master/lib/std/array_list.zig)[^zig-array].\nSo, the standard that the Zig developers decided to adopt\nis to keep their unit tests together with the source code\nof the functionality that they are testing.\n\nEach programmer might have a different opinion on this.\nSome of them might prefer to keep unit tests separate from the actual\nsource code of their application. If that is your case, you can\nsimply create a separate `tests` folder in your project, and\nstart writing Zig modules that contains only unit tests (as you would normally do\non a Python project with `pytest`, for example), and everything will work fine.\nIt boils down to which is your preference here.\n\n[^zig-std-lib]: <https://github.com/ziglang/zig/tree/master/lib/std>\n[^zig-array]: <https://github.com/ziglang/zig/blob/master/lib/std/array_list.zig>\n\n\n## How to run your tests\n\nIf the `zig` compiler ignores any `test` block by default, how can\nyou compile and run your unit tests? The answer is the `test` command from\nthe `zig` compiler. By running the `zig test` command, the compiler will\nfind every instance of a `test` block in your Zig modules, and, it will\ncompile and run the unit tests that you wrote.\n\n\n```bash\nzig test simple_sum.zig\n```\n\n```\n1/1 simple_sum.test.testing simple sum... OK\nAll 1 tests passed.\n```\n\n\n## Testing memory allocations\n\nOne of the advantages of Zig is that it offers great tools\nthat help us, programmers, to avoid (but also detect) memory problems, such as\nmemory leaks and double-frees. The `defer` keyword\nis especially helpful in this regard.\n\nWhen developing your source code, you, the programmer, is responsible for making\nsure that your code do not produce such problems. However,\nyou can also use a special type of an allocator object in Zig\nthat is capable of automatically detecting such problems for you.\nThis is the `std.testing.allocator` object.\nThis allocator object offers some basic memory safety detection\nfeatures, which are capable of detecting memory leaks.\n\nAs we described at @sec-heap, to allocate memory on the heap, you need\nto use an allocator object, and your functions that use these objects to allocate memory\non the heap, should receive an allocator object as one of its inputs.\nEvery memory on the heap that you allocate using these allocator objects,\nmust also be freed using this same allocator object.\n\nSo, if you want to test the memory allocations performed by your functions,\nand make sure that you don't have problems in these allocations, you can simply\nwrite unit tests for these functions, where you provide the\n`std.testing.allocator` object as input to these functions.\n\nLook at the example below, where I'm defining a function that clearly causes\na memory leak. Because we allocate memory, but, at the same time,\nwe do not free this allocated memory at any point. So, when the function\nreturns, we lose the reference to the `buffer` object, which contains\nthe allocated memory, and, as a result, we can no longer free this memory.\n\nNotice that, inside a `test` block I execute this function with\nthe `std.testing.allocator`. The allocator object was capable\nof looking deeper in our program, and detecting the memory leak. As a result,\nthis allocator object returns an error message of \"memory leaked\", and also,\na stack trace showing the exact point where the memory was leaked.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nfn some_memory_leak(allocator: Allocator) !void {\n    const buffer = try allocator.alloc(u32, 10);\n    _ = buffer;\n    // Return without freeing the\n    // allocated memory\n}\n\ntest \"memory leak\" {\n    const allocator = std.testing.allocator;\n    try some_memory_leak(allocator);\n}\n```\n:::\n\n\n\n\n```\nTest [1/1] leak_memory.test.memory leak...\n    [gpa] (err): memory address 0x7c1fddf39000 leaked: \n./ZigExamples/debugging/leak_memory.zig:4:39: 0x10395f2\n    const buffer = try allocator.alloc(u32, 10);\n                                      ^\n./ZigExamples/debugging/leak_memory.zig:12:25: 0x10398ea\n    try some_memory_leak(allocator);\n\n... more stack trace\n```\n\n\n## Testing errors\n\nOne common style of unit tests are those that look for\nspecific errors in your functions. In other words, you write\na unit test that tries to assert if a specific function call\nreturns any error, or a specific type of error.\n\nIn C++ you would normally write this style of unit tests using, for example,\nthe functions `REQUIRE_THROWS()` or `CHECK_THROWS()` from the [`Catch2` test framework](https://github.com/catchorg/Catch2/tree/devel)[^catch2].\nIn the case of a Python project, you would probably use the\n[`raises()` function from `pytest`](https://docs.pytest.org/en/7.1.x/reference/reference.html#pytest-raises)[^pytest].\nWhile in Rust, you would probably use `assert_eq!()` in conjunction with `Err()`.\n\n[^pytest]: <https://docs.pytest.org/en/7.1.x/reference/reference.html#pytest-raises>\n[^catch2]: <https://github.com/catchorg/Catch2/tree/devel>\n\n\nBut in Zig, we use the `expectError()` function, from the `std.testing` module.\nWith this function, you can test if a specific function call returns the exact\ntype of error that you expect it to return. To use this function, you first write\n`try expectError()`. Then, on the first argument, you provide the type of error that you\nare expecting from the function call. Then, on the second argument, you write\nthe function call that you expect to fail.\n\nThe code example below demonstrates such type of unit test in Zig.\nNotice that, inside the function `alloc_error()` we are allocating\n100 bytes of memory, or, an array of 100 elements, for the object `ibuffer`. However,\nin the `test` block, we are using the `FixedBufferAllocator()`\nallocator object, which is limited to 10 bytes of space, because\nthe object `buffer`, which we provided to the allocator object,\nhave only 10 bytes of space.\n\nThat is why, the `alloc_error()` function raises an `OutOfMemory` error\non this case.\nBecause this function is trying to allocate more space than the allocator\nobject allows.\nSo, in essence, we are testing for a specific type of error,\nwhich is `OutOfMemory`. If the `alloc_error()` function returns any other type of error,\nthen, the `expectError()` function would make the entire test fail.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst expectError = std.testing.expectError;\nfn alloc_error(allocator: Allocator) !void {\n    var ibuffer = try allocator.alloc(u8, 100);\n    defer allocator.free(ibuffer);\n    ibuffer[0] = 2;\n}\n\ntest \"testing error\" {\n    var buffer: [10]u8 = undefined;\n    var fba = std.heap.FixedBufferAllocator.init(&buffer);\n    const allocator = fba.allocator();\n    try expectError(error.OutOfMemory, alloc_error(allocator));\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filea5b059c00874.test.testing error...OKAll 1 \n   tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n## Testing simple equalities\n\nIn Zig, there are some different ways you can test for an equality.\nYou already saw that we can use `expect()` with the logical operator `==`\nto essentially reproduce an equality test. But we also have\nsome other helper functions that you should know about, especially\n`expectEqual()`, `expectEqualSlices()` and `expectEqualStrings()`.\n\n\nThe `expectEqual()` function, as the name suggests, is a classic\ntest equality function. It receives two objects as input. The first\nobject is the value that you expect to be in the second object.\nWhile second object is the object you have, or, the object that your application\nproduced as result. So, with `expectEqual()` you are essentially\ntesting if the values stored inside these two objects\nare equal or not.\n\nYou can see in the example below that, the test performed by\n`expectEqual()` failed. Because the objects `v1` and `v2` contain\ndifferent values in them.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"values are equal?\" {\n    const v1 = 15;\n    const v2 = 18;\n    try std.testing.expectEqual(v1, v2);\n}\n```\n:::\n\n\n\n\n```\n1/1 ve.test.values are equal?...\n    expected 15, found 18\n    FAIL (TestExpectedEqual)\nve.zig:5:5: test.values are equal? (test)\n    try std.testing.expectEqual(v1, v2);\n    ^\n0 passed; 0 skipped; 1 failed.\n```\n\n\nAlthough useful, the `expectEqual()` function does not work with arrays.\nFor testing if two arrays are equal, you should use the `expectEqualSlices()`\nfunction instead. This function have three arguments. First, you provide\nthe data type contained in both arrays that you are trying to compare.\nWhile the second and third arguments corresponds to the array objects that you want to compare.\n\nIn the example below, we are using this function to test if two array\nobjects (`array1` and `array2`) are equal or not. Since they\nare in fact equal, the unit test passed with no errors.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"arrays are equal?\" {\n    const array1 = [3]u32{1, 2, 3};\n    const array2 = [3]u32{1, 2, 3};\n    try std.testing.expectEqualSlices(\n        u32, &array1, &array2\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filea5b054e42b80.test.arrays are equal?...OKAl\n  ll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\nAt last, you might also want to use the `expectEqualStrings()` function.\nAs the name suggests, you can use this function to test if two strings\nare equal or not. Just provide the two string objects that you want to compare,\nas inputs to the function.\n\nIf the function finds any existing differences between the two strings,\nthen, the function will raise an error, and also, print an error message\nthat shows the exact difference between the two string objects provided,\nas the example below demonstrates:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"strings are equal?\" {\n    const str1 = \"hello, world!\";\n    const str2 = \"Hello, world!\";\n    try std.testing.expectEqualStrings(\n        str1, str2\n    );\n}\n```\n:::\n\n\n\n\n```\n1/1 t.test.strings are equal?... \n====== expected this output: =========\nhello, world!␃\n======== instead found this: =========\nHello, world!␃\n======================================\nFirst difference occurs on line 1:\nexpected:\nhello, world!\n^ ('\\x68')\nfound:\nHello, world!\n^ ('\\x48')\n```\n\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/05-pointers/execute-results/html.json b/_freeze/Chapters/05-pointers/execute-results/html.json
index bce4789c..12c21289 100644
--- a/_freeze/Chapters/05-pointers/execute-results/html.json
+++ b/_freeze/Chapters/05-pointers/execute-results/html.json
@@ -2,7 +2,7 @@
   "hash": "8fdb1694a88afd9b81c337b29ec84c86",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Pointers and Optionals {#sec-pointer}\n\nOn our next project we are going to build a HTTP server from scratch.\nBut in order to do that, we need to learn more about pointers and how they work in Zig.\nPointers in Zig are similar to pointers in C. But they come with some extra advantages in Zig.\n\nA pointer is an object that contains a memory address. This memory address is the address where\na particular value is stored in memory. It can be any value. Most of the times,\nit is a value that comes from another object (or variable) present in our code.\n\nIn the example below, I'm creating two objects (`number` and `pointer`).\nThe `pointer` object contains the memory address where the value of the `number` object\n(the number 5) is stored. So, that is a pointer in a nutshell. It is a memory\naddress that points to a particular existing value in the memory. You could\nalso say, that, the `pointer` object points to the memory address where the `number` object is\nstored.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number: u8 = 5;\nconst pointer = &number;\n_ = pointer;\n```\n:::\n\n\n\n\n\nWe create a pointer object in Zig by using the `&` operator. When you put this operator\nbefore the name of an existing object, you get the memory address of this object as result.\nWhen you store this memory address inside a new object, this new object becomes a pointer object.\nBecause it stores a memory address.\n\nPeople mostly use pointers as an alternative way to access a particular value.\nFor example, I can use the `pointer` object to access the value stored by\nthe `number` object. This operation of accessing the value that the\npointer \"points to\" is normally called of *dereferencing the pointer*.\nWe can dereference a pointer in Zig by using the `*` method of the pointer object. Like in the example\nbelow, where we take the number 5 pointed by the `pointer` object,\nand double it.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number: u8 = 5;\nconst pointer = &number;\nconst doubled = 2 * pointer.*;\nstd.debug.print(\"{d}\\n\", .{doubled});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n10\n```\n\n\n:::\n:::\n\n\n\n\n\n\nThis syntax to dereference the pointer is nice. Because we can easily chain it with\nmethods of the value pointed by the pointer. We can use the `User` struct that we have\ncreated at @sec-structs-and-oop as an example. If you comeback to that section,\nyou will see that this struct have a method named `print_name()`.\n\nSo, for example, if we have an user object, and a pointer that points to this user object,\nwe can use the pointer to access this user object, and, at the same time, call the method `print_name()`\non it, by chaining the dereference method (`*`) with the `print_name()` method. Like in the\nexample below:\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst u = User.init(1, \"pedro\", \"email@gmail.com\");\nconst pointer = &u;\ntry pointer.*.print_name();\n```\n:::\n\n\n\n\n\n```\npedro\n```\n\nWe can also use pointers to effectively alter the value of an object.\nFor example, I could use the `pointer` object to set\nthe value of the object `number` to 6, like in the example below.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n6\n```\n\n\n:::\n:::\n\n\n\n\n\n\nTherefore, as I mentioned earlier, people use pointers as an alternative way to access a particular value.\nAnd they use it especially when they do not want to \"move\" these values around. There are situations where,\nyou want to access a particular value in a different scope (i.e. a different location) of your code,\nbut you do not want to \"move\" this value to this new scope (or location) that you are in.\n\nThis matters especially if this value is big in size. Because if it is, then,\nmoving this value becomes an expensive operation to do.\nThe computer will have to spend a considerable amount of time\ncopying this value to this new location.\n\nTherefore, many programmers prefer to avoid this heavy operation of copying the value\nto the new location, by accessing this value through pointers.\nWe are going to talk more about this \"moving operation\" over the next sections.\nFor now, just keep in mind that avoiding this \"move operation\" is\none of main reasons why pointers are used in programming languages.\n\n\n\n\n\n## Constant objects vs variable objects {#sec-pointer-var}\n\nYou can have a pointer that points to a constant object, or, a pointer that points to a variable object.\nBut regardless of who this pointer is, a pointer **must always respect the characteristics of the object that it points to**.\nAs a consequence, if the pointer points to a constant object, then, you cannot use this pointer\nto change the value that it points to. Because it points to a value that is constant. As we discussed at @sec-assignments, you cannot\nchange a value that is constant.\n\nFor example, if I have a `number` object, which is constant, I cannot execute\nthe expression below where I'm trying to change the value of `number` to 6 through\nthe `pointer` object. As demonstrated below, when you try to do something\nlike that, you get a compile time error:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number = 5;\nconst pointer = &number;\npointer.* = 6;\n```\n:::\n\n\n\n\n\n```\np.zig:6:12: error: cannot assign to constant\n    pointer.* = 6;\n```\n\nIf I change the `number` object to be a variable object, by introducing the `var` keyword,\nthen, I can successfully change the value of this object through a pointer, as demonstrated below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n6\n```\n\n\n:::\n:::\n\n\n\n\n\nYou can see this relationship between \"constant versus variable\" on the data type of\nyour pointer object. In other words, the data type of a pointer object already gives you\nsome clues about whether the value that it points to is constant or not.\n\nWhen a pointer object points to a constant value, then, this pointer have a data type `*const T`,\nwhich means \"a pointer to a constant value of type `T`\".\nIn contrast, if the pointer points to a variable value, then, the type of the pointer is usually `*T`, which is\nsimply \"a pointer to a value of type `T`\".\nHence, whenever you see a pointer object whose data type is in the format `*const T`, then,\nyou know that you cannot use this pointer to change the value that it points to.\nBecause this pointer points to a constant value of type `T`.\n\n\nWe have talked about the value pointed by the pointer being constant or not,\nand the consequences that arises from it. But, what about the pointer object itself? I mean, what happens\nif the pointer object itself is constant or not? Think about it.\nWe can have a constant pointer that points to a constant value.\nBut we can also have a variable pointer that points to a constant value. And vice-versa.\n\nUntil this point, the `pointer` object was always constant,\nbut what this means for us? What is the consequence of the\n`pointer` object being constant? The consequence is that\nwe cannot change the pointer object, because it is constant. We can use the\npointer object in multiple ways, but we cannot change the\nmemory address that is inside this pointer object.\n\nHowever, if we mark the `pointer` object as a variable object,\nthen, we can change the memory address pointed by this `pointer` object.\nThe example below demonstrates that. Notice that the object pointed\nby the `pointer` object changes from `c1` to `c2`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c1: u8 = 5;\nconst c2: u8 = 6;\nvar pointer = &c1;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\npointer = &c2;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\n```\n:::\n\n\n\n\n\n```\n5\n6\n```\n\nThus, by setting the `pointer` object to a `var` or `const` object,\nyou specify if the memory address contained in this pointer object can change or not\nin your program. On the other side, you can change the value pointed by the pointer,\nif, and only if this value is stored in a variable object. If this value\nis in a constant object, then, you cannot change this value through a pointer.\n\n\n## Types of pointer\n\nIn Zig, there are two types of pointers [@zigdocs], which are:\n\n- single-item pointer (`*`);\n- many-item pointer (`[*]`);\n\n\nSingle-item pointer objects are objects whose data types are in the format `*T`.\nSo, for example, if an object have a data type `*u32`, it means that, this\nobject contains a single-item pointer that points to an unsigned 32-bit integer value.\nAs another example, if an object have type `*User`, then, it contains\na single-item pointer to an `User` value.\n\nIn contrast, many-item pointers are objects whose data types are in the format `[*]T`.\nNotice that the star symbol (`*`) is now inside a pair of brackets (`[]`). If the star\nsymbol is inside a pair of brackets, you know that this object is a many-item pointer.\n\nWhen you apply the `&` operator over an object, you will always get a single-item pointer.\nMany-item pointers are more of a \"internal type\" of the language, more closely\nrelated to slices. So, when you deliberately create a pointer with the `&` operator,\nyou always get a single-item pointer as result.\n\n\n\n## Pointer arithmetic\n\nPointer arithmetic is available in Zig, and they work the same way they work in C.\nWhen you have a pointer that points to an array, the pointer usually points to\nthe first element in the array, and you can use pointer arithmetic to\nadvance this pointer and access the other elements in the array.\n\n\nNotice in the example below, that initially, the `ptr` object was pointing\nto the first element in the array `ar`. But then, I started to walk through the array, by advancing\nthe pointer with simple pointer arithmetic.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [_]i32{ 1, 2, 3, 4 };\nvar ptr: [*]const i32 = &ar;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\n```\n:::\n\n\n\n\n\n```\n1\n2\n3\n```\n\nAlthough you can create a pointer to an array like that, and\nstart to walk through this array by using pointer arithmetic,\nin Zig, we prefer to use slices, which were presented at @sec-arrays.\n\nBehind the hood, slices already are pointers,\nand they also come with the `len` property, which indicates\nhow many elements are in the slice. This is good because the `zig` compiler\ncan use it to check for potential buffer overflows, and other problems like that.\n\nAlso, you don't need to use pointer arithmetic to walk through the elements\nof a slice. You can simply use the `slice[index]` syntax to directly access\nany element you want in the slice.\nAs I mentioned at @sec-arrays, you can get a slice from an array by using\na range selector inside brackets. In the example below, I'm creating\na slice (`sl`) that covers the entire `ar` array. I can access any\nelement of `ar` from this slice, and, the slice itself already is a pointer\nbehind the hood.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [_]i32{1,2,3,4};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\n\n\n## Optionals and Optional Pointers\n\nLet's talk about optionals and how they relate to pointers in Zig.\nBy default, objects in Zig are **non-nullable**. This means that, in Zig,\nyou can safely assume that any object in your source code is not null.\n\nThis is a powerful feature of Zig when you compare it to the developer experience in C.\nBecause in C, any object can be null at any point, and, as consequence, a pointer in C\nmight point to a null value. This is a common source of undefined behaviour in C.\nWhen programmers work with pointers in C, they have to constantly check if\ntheir pointers are pointing to null values or not.\n\nIf for some reason, your Zig code produces a null value somewhere, and, this null\nvalue ends up in an object that is non-nullable, a runtime error is always\nraised by your Zig program. Take the program below as an example.\nThe `zig` compiler can see the `null` value at compile time, and, as result,\nit raises a compile time error. But, if a `null` value is raised during\nruntime, a runtime error is also raised by the Zig program, with a\n\"attempt to use null value\" message.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nnumber = null;\n```\n:::\n\n\n\n\n```\np5.zig:5:14: error: expected type 'u8',\n        found '@TypeOf(null)'\n    number = null;\n             ^~~~\n```\n\n\nYou don't get this type of safety in C.\nIn C, you don't get warnings or errors about null values being produced in your program.\nIf for some reason, your code produces a null value in C, most of the times, you end up getting a segmentation fault error\nas result, which can mean many things.\nThat is why programmers have to constantly check for null values in C.\n\nPointers in Zig are also, by default, **non-nullable**. This is another amazing\nfeature in Zig. So, you can safely assume that any pointer that you create in\nyour Zig code is pointing to a non-null value.\nTherefore, you don't have this heavy work of checking if the pointers you create\nin Zig are pointing to a null value.\n\n\n### What are optionals?\n\nOk, we know now that all objects are non-nullable by default in Zig.\nBut what if we actually need to use an object that might receive a null value?\nHere is where optionals come in.\n\nAn optional object in Zig is an object that can be null.\nTo mark an object as optional, we use the `?` operator. When you put\nthis `?` operator right before the data type of an object, you transform\nthis data type into an optional data type, and the object becomes an optional object.\n\nTake the snippet below as an example. We are creating a new variable object\ncalled `num`. This object have the data type `?i32`, which means that,\nthis object contains either a signed 32-bit integer (`i32`), or, a null value.\nBoth alternatives are valid values to the `num` object.\nThat is why, I can actually change the value of this object to null, and,\nno errors are raised by the `zig` compiler, as demonstrated below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: ?i32 = 5;\nnum = null;\n```\n:::\n\n\n\n\n\n### Optional pointers\n\nYou can also mark a pointer object as an optional pointer, meaning that,\nthis object contains either a null value, or, a pointer that points to a value.\nWhen you mark a pointer as optional, the data type of this pointer object\nbecomes `?*const T` or `?*T`, depending if the value pointed by the pointer\nis a constant value or not. The `?` identifies the object as optional, while\nthe `*` identifies it as a pointer object.\n\nIn the example below, we are creating a variable object named `num`, and an\noptional pointer object named `ptr`. Notice that the data type of the object\n`ptr` indicates that it is either a null value, or a pointer to an `i32` value.\nAlso, notice that the pointer object (`ptr`) can be marked as optional, even if\nthe object `num` is not optional.\n\nWhat this code tells us is that, the `num` variable will never contain a null value.\nThis variable will always contain a valid `i32` value. But in contrast, the `ptr` object might contain either a null\nvalue, or, a pointer to an `i32` value.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: i32 = 5;\nvar ptr: ?*i32 = &num;\nptr = null;\nnum = 6;\n```\n:::\n\n\n\n\n\nBut what happens if we turn the table, and mark the `num` object as optional,\ninstead of the pointer object. If we do that, then, the pointer object is\nnot optional anymore. It would be a similar (although different) result. Because then, we would have\na pointer to an optional value. In other words, a pointer to a value that is either a\nnull value, or, a not-null value.\n\nIn the example below, we are recreating this idea. Now, the `ptr` object\nhave a data type of `*?i32`, instead of `?*i32`. Notice that the `*` symbol comes before of `?`\nthis time. So now, we have a pointer that points to a value that is either null\n, or, a signed 32-bit integer.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: ?i32 = 5;\n// ptr have type `*?i32`, instead of `?*i32`.\nconst ptr = &num;\n_ = ptr;\n```\n:::\n\n\n\n\n\n\n### Null handling in optionals {#sec-null-handling}\n\nWhen you have an optional object in your Zig code, you have to explicitly handle\nthe possibility of this object being null. It is like error-handling with `try` and `catch`.\nIn Zig you also have to handle null values like if they were a type of error.\n\nWe can do that, by using either:\n\n- an if statement, like you would do in C.\n- the `orelse` keyword.\n- unwrap the optional value with the `?` method.\n\nWhen you use an if statement, you use a pair of pipes\nto unwrap the optional value, and use this \"unwrapped object\"\ninside the if block.\nUsing the example below as a reference, if the object `num` is null,\nthen, the code inside the if statement is not executed. Otherwise,\nthe if statement will unwrap the object `num` into the `not_null_num`\nobject. This `not_null_num` object is guaranteed to be not null inside\nthe scope of the if statement.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst num: ?i32 = 5;\nif (num) |not_null_num| {\n    try stdout.print(\"{d}\\n\", .{not_null_num});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n5\n```\n\n\n:::\n:::\n\n\n\n\n\nNow, the `orelse` keyword behaves like a binary operator. You connect two expressions with this keyword.\nOn the left side of `orelse`, you provide the expression that might result\nin a null value, and on the right side of `orelse`, you provide another expression\nthat will not result in a null value.\n\nThe idea behind the `orelse` keyword is: if the expression on the left side\nresult in a not-null value, then, this not-null value is used. However,\nif this expression on the left side result in a null value, then, the value\nof the expression on the right side is used instead.\n\nLooking at the example below, since the `x` object is currently null, the\n`orelse` decided to use the alternative value, which is the number 15.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x: ?i32 = null;\nconst dbl = (x orelse 15) * 2;\ntry stdout.print(\"{d}\\n\", .{dbl});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n30\n```\n\n\n:::\n:::\n\n\n\n\n\nYou can use the if statement or the `orelse` keyword, when you want to\nsolve (or deal with) this null value. However, if there is no clear solution\nto this null value, and the most logic and sane path is to simply panic\nand raise a loud error in your program when this null value is encountered,\nyou can use the `?` method of your optional object.\n\nIn essence, when you use this `?` method, the optional object is unwrapped.\nIf a not-null value is found in the optional object, then, this not-null value is used.\nOtherwise, the `unreachable` keyword is used. You can read more about this\n[`unreacheable` keyword at the official documentation](https://ziglang.org/documentation/master/#unreachable)[^un-docs].\nBut in essence, when you build your Zig source code using the build modes `ReleaseSafe` or `Debug`, this\n`unreacheable` keyword causes the program to panic and raise an error during runtime,\nlike in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn return_null(n: i32) ?i32 {\n    if (n == 5) return null;\n    return n;\n}\n\npub fn main() !void {\n    const x: i32 = 5;\n    const y: ?i32 = return_null(x);\n    try stdout.print(\"{d}\\n\", .{y.?});\n}\n```\n:::\n\n\n\n\n\n```\nthread 12767 panic: attempt to use null value\np7.zig:12:34: 0x103419d in main (p7):\n    try stdout.print(\"{d}\\n\", .{y.?});\n                                 ^\n```\n\n\n[^un-docs]: <https://ziglang.org/documentation/master/#unreachable>.\n\n\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Pointers and Optionals {#sec-pointer}\n\nOn our next project we are going to build a HTTP server from scratch.\nBut in order to do that, we need to learn more about pointers and how they work in Zig.\nPointers in Zig are similar to pointers in C. But they come with some extra advantages in Zig.\n\nA pointer is an object that contains a memory address. This memory address is the address where\na particular value is stored in memory. It can be any value. Most of the times,\nit is a value that comes from another object (or variable) present in our code.\n\nIn the example below, I'm creating two objects (`number` and `pointer`).\nThe `pointer` object contains the memory address where the value of the `number` object\n(the number 5) is stored. So, that is a pointer in a nutshell. It is a memory\naddress that points to a particular existing value in the memory. You could\nalso say, that, the `pointer` object points to the memory address where the `number` object is\nstored.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number: u8 = 5;\nconst pointer = &number;\n_ = pointer;\n```\n:::\n\n\n\n\nWe create a pointer object in Zig by using the `&` operator. When you put this operator\nbefore the name of an existing object, you get the memory address of this object as result.\nWhen you store this memory address inside a new object, this new object becomes a pointer object.\nBecause it stores a memory address.\n\nPeople mostly use pointers as an alternative way to access a particular value.\nFor example, I can use the `pointer` object to access the value stored by\nthe `number` object. This operation of accessing the value that the\npointer \"points to\" is normally called of *dereferencing the pointer*.\nWe can dereference a pointer in Zig by using the `*` method of the pointer object. Like in the example\nbelow, where we take the number 5 pointed by the `pointer` object,\nand double it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number: u8 = 5;\nconst pointer = &number;\nconst doubled = 2 * pointer.*;\nstd.debug.print(\"{d}\\n\", .{doubled});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n10\n```\n\n\n:::\n:::\n\n\n\n\n\nThis syntax to dereference the pointer is nice. Because we can easily chain it with\nmethods of the value pointed by the pointer. We can use the `User` struct that we have\ncreated at @sec-structs-and-oop as an example. If you comeback to that section,\nyou will see that this struct have a method named `print_name()`.\n\nSo, for example, if we have an user object, and a pointer that points to this user object,\nwe can use the pointer to access this user object, and, at the same time, call the method `print_name()`\non it, by chaining the dereference method (`*`) with the `print_name()` method. Like in the\nexample below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst u = User.init(1, \"pedro\", \"email@gmail.com\");\nconst pointer = &u;\ntry pointer.*.print_name();\n```\n:::\n\n\n\n\n```\npedro\n```\n\nWe can also use pointers to effectively alter the value of an object.\nFor example, I could use the `pointer` object to set\nthe value of the object `number` to 6, like in the example below.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n6\n```\n\n\n:::\n:::\n\n\n\n\n\nTherefore, as I mentioned earlier, people use pointers as an alternative way to access a particular value.\nAnd they use it especially when they do not want to \"move\" these values around. There are situations where,\nyou want to access a particular value in a different scope (i.e. a different location) of your code,\nbut you do not want to \"move\" this value to this new scope (or location) that you are in.\n\nThis matters especially if this value is big in size. Because if it is, then,\nmoving this value becomes an expensive operation to do.\nThe computer will have to spend a considerable amount of time\ncopying this value to this new location.\n\nTherefore, many programmers prefer to avoid this heavy operation of copying the value\nto the new location, by accessing this value through pointers.\nWe are going to talk more about this \"moving operation\" over the next sections.\nFor now, just keep in mind that avoiding this \"move operation\" is\none of main reasons why pointers are used in programming languages.\n\n\n\n\n\n## Constant objects vs variable objects {#sec-pointer-var}\n\nYou can have a pointer that points to a constant object, or, a pointer that points to a variable object.\nBut regardless of who this pointer is, a pointer **must always respect the characteristics of the object that it points to**.\nAs a consequence, if the pointer points to a constant object, then, you cannot use this pointer\nto change the value that it points to. Because it points to a value that is constant. As we discussed at @sec-assignments, you cannot\nchange a value that is constant.\n\nFor example, if I have a `number` object, which is constant, I cannot execute\nthe expression below where I'm trying to change the value of `number` to 6 through\nthe `pointer` object. As demonstrated below, when you try to do something\nlike that, you get a compile time error:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number = 5;\nconst pointer = &number;\npointer.* = 6;\n```\n:::\n\n\n\n\n```\np.zig:6:12: error: cannot assign to constant\n    pointer.* = 6;\n```\n\nIf I change the `number` object to be a variable object, by introducing the `var` keyword,\nthen, I can successfully change the value of this object through a pointer, as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n6\n```\n\n\n:::\n:::\n\n\n\n\nYou can see this relationship between \"constant versus variable\" on the data type of\nyour pointer object. In other words, the data type of a pointer object already gives you\nsome clues about whether the value that it points to is constant or not.\n\nWhen a pointer object points to a constant value, then, this pointer have a data type `*const T`,\nwhich means \"a pointer to a constant value of type `T`\".\nIn contrast, if the pointer points to a variable value, then, the type of the pointer is usually `*T`, which is\nsimply \"a pointer to a value of type `T`\".\nHence, whenever you see a pointer object whose data type is in the format `*const T`, then,\nyou know that you cannot use this pointer to change the value that it points to.\nBecause this pointer points to a constant value of type `T`.\n\n\nWe have talked about the value pointed by the pointer being constant or not,\nand the consequences that arises from it. But, what about the pointer object itself? I mean, what happens\nif the pointer object itself is constant or not? Think about it.\nWe can have a constant pointer that points to a constant value.\nBut we can also have a variable pointer that points to a constant value. And vice-versa.\n\nUntil this point, the `pointer` object was always constant,\nbut what this means for us? What is the consequence of the\n`pointer` object being constant? The consequence is that\nwe cannot change the pointer object, because it is constant. We can use the\npointer object in multiple ways, but we cannot change the\nmemory address that is inside this pointer object.\n\nHowever, if we mark the `pointer` object as a variable object,\nthen, we can change the memory address pointed by this `pointer` object.\nThe example below demonstrates that. Notice that the object pointed\nby the `pointer` object changes from `c1` to `c2`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c1: u8 = 5;\nconst c2: u8 = 6;\nvar pointer = &c1;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\npointer = &c2;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\n```\n:::\n\n\n\n\n```\n5\n6\n```\n\nThus, by setting the `pointer` object to a `var` or `const` object,\nyou specify if the memory address contained in this pointer object can change or not\nin your program. On the other side, you can change the value pointed by the pointer,\nif, and only if this value is stored in a variable object. If this value\nis in a constant object, then, you cannot change this value through a pointer.\n\n\n## Types of pointer\n\nIn Zig, there are two types of pointers [@zigdocs], which are:\n\n- single-item pointer (`*`);\n- many-item pointer (`[*]`);\n\n\nSingle-item pointer objects are objects whose data types are in the format `*T`.\nSo, for example, if an object have a data type `*u32`, it means that, this\nobject contains a single-item pointer that points to an unsigned 32-bit integer value.\nAs another example, if an object have type `*User`, then, it contains\na single-item pointer to an `User` value.\n\nIn contrast, many-item pointers are objects whose data types are in the format `[*]T`.\nNotice that the star symbol (`*`) is now inside a pair of brackets (`[]`). If the star\nsymbol is inside a pair of brackets, you know that this object is a many-item pointer.\n\nWhen you apply the `&` operator over an object, you will always get a single-item pointer.\nMany-item pointers are more of a \"internal type\" of the language, more closely\nrelated to slices. So, when you deliberately create a pointer with the `&` operator,\nyou always get a single-item pointer as result.\n\n\n\n## Pointer arithmetic\n\nPointer arithmetic is available in Zig, and they work the same way they work in C.\nWhen you have a pointer that points to an array, the pointer usually points to\nthe first element in the array, and you can use pointer arithmetic to\nadvance this pointer and access the other elements in the array.\n\n\nNotice in the example below, that initially, the `ptr` object was pointing\nto the first element in the array `ar`. But then, I started to walk through the array, by advancing\nthe pointer with simple pointer arithmetic.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [_]i32{ 1, 2, 3, 4 };\nvar ptr: [*]const i32 = &ar;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\n```\n:::\n\n\n\n\n```\n1\n2\n3\n```\n\nAlthough you can create a pointer to an array like that, and\nstart to walk through this array by using pointer arithmetic,\nin Zig, we prefer to use slices, which were presented at @sec-arrays.\n\nBehind the hood, slices already are pointers,\nand they also come with the `len` property, which indicates\nhow many elements are in the slice. This is good because the `zig` compiler\ncan use it to check for potential buffer overflows, and other problems like that.\n\nAlso, you don't need to use pointer arithmetic to walk through the elements\nof a slice. You can simply use the `slice[index]` syntax to directly access\nany element you want in the slice.\nAs I mentioned at @sec-arrays, you can get a slice from an array by using\na range selector inside brackets. In the example below, I'm creating\na slice (`sl`) that covers the entire `ar` array. I can access any\nelement of `ar` from this slice, and, the slice itself already is a pointer\nbehind the hood.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [_]i32{1,2,3,4};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\n\n## Optionals and Optional Pointers\n\nLet's talk about optionals and how they relate to pointers in Zig.\nBy default, objects in Zig are **non-nullable**. This means that, in Zig,\nyou can safely assume that any object in your source code is not null.\n\nThis is a powerful feature of Zig when you compare it to the developer experience in C.\nBecause in C, any object can be null at any point, and, as consequence, a pointer in C\nmight point to a null value. This is a common source of undefined behaviour in C.\nWhen programmers work with pointers in C, they have to constantly check if\ntheir pointers are pointing to null values or not.\n\nIf for some reason, your Zig code produces a null value somewhere, and, this null\nvalue ends up in an object that is non-nullable, a runtime error is always\nraised by your Zig program. Take the program below as an example.\nThe `zig` compiler can see the `null` value at compile time, and, as result,\nit raises a compile time error. But, if a `null` value is raised during\nruntime, a runtime error is also raised by the Zig program, with a\n\"attempt to use null value\" message.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nnumber = null;\n```\n:::\n\n\n\n```\np5.zig:5:14: error: expected type 'u8',\n        found '@TypeOf(null)'\n    number = null;\n             ^~~~\n```\n\n\nYou don't get this type of safety in C.\nIn C, you don't get warnings or errors about null values being produced in your program.\nIf for some reason, your code produces a null value in C, most of the times, you end up getting a segmentation fault error\nas result, which can mean many things.\nThat is why programmers have to constantly check for null values in C.\n\nPointers in Zig are also, by default, **non-nullable**. This is another amazing\nfeature in Zig. So, you can safely assume that any pointer that you create in\nyour Zig code is pointing to a non-null value.\nTherefore, you don't have this heavy work of checking if the pointers you create\nin Zig are pointing to a null value.\n\n\n### What are optionals?\n\nOk, we know now that all objects are non-nullable by default in Zig.\nBut what if we actually need to use an object that might receive a null value?\nHere is where optionals come in.\n\nAn optional object in Zig is an object that can be null.\nTo mark an object as optional, we use the `?` operator. When you put\nthis `?` operator right before the data type of an object, you transform\nthis data type into an optional data type, and the object becomes an optional object.\n\nTake the snippet below as an example. We are creating a new variable object\ncalled `num`. This object have the data type `?i32`, which means that,\nthis object contains either a signed 32-bit integer (`i32`), or, a null value.\nBoth alternatives are valid values to the `num` object.\nThat is why, I can actually change the value of this object to null, and,\nno errors are raised by the `zig` compiler, as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: ?i32 = 5;\nnum = null;\n```\n:::\n\n\n\n\n### Optional pointers\n\nYou can also mark a pointer object as an optional pointer, meaning that,\nthis object contains either a null value, or, a pointer that points to a value.\nWhen you mark a pointer as optional, the data type of this pointer object\nbecomes `?*const T` or `?*T`, depending if the value pointed by the pointer\nis a constant value or not. The `?` identifies the object as optional, while\nthe `*` identifies it as a pointer object.\n\nIn the example below, we are creating a variable object named `num`, and an\noptional pointer object named `ptr`. Notice that the data type of the object\n`ptr` indicates that it is either a null value, or a pointer to an `i32` value.\nAlso, notice that the pointer object (`ptr`) can be marked as optional, even if\nthe object `num` is not optional.\n\nWhat this code tells us is that, the `num` variable will never contain a null value.\nThis variable will always contain a valid `i32` value. But in contrast, the `ptr` object might contain either a null\nvalue, or, a pointer to an `i32` value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: i32 = 5;\nvar ptr: ?*i32 = &num;\nptr = null;\nnum = 6;\n```\n:::\n\n\n\n\nBut what happens if we turn the table, and mark the `num` object as optional,\ninstead of the pointer object. If we do that, then, the pointer object is\nnot optional anymore. It would be a similar (although different) result. Because then, we would have\na pointer to an optional value. In other words, a pointer to a value that is either a\nnull value, or, a not-null value.\n\nIn the example below, we are recreating this idea. Now, the `ptr` object\nhave a data type of `*?i32`, instead of `?*i32`. Notice that the `*` symbol comes before of `?`\nthis time. So now, we have a pointer that points to a value that is either null\n, or, a signed 32-bit integer.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: ?i32 = 5;\n// ptr have type `*?i32`, instead of `?*i32`.\nconst ptr = &num;\n_ = ptr;\n```\n:::\n\n\n\n\n\n### Null handling in optionals {#sec-null-handling}\n\nWhen you have an optional object in your Zig code, you have to explicitly handle\nthe possibility of this object being null. It is like error-handling with `try` and `catch`.\nIn Zig you also have to handle null values like if they were a type of error.\n\nWe can do that, by using either:\n\n- an if statement, like you would do in C.\n- the `orelse` keyword.\n- unwrap the optional value with the `?` method.\n\nWhen you use an if statement, you use a pair of pipes\nto unwrap the optional value, and use this \"unwrapped object\"\ninside the if block.\nUsing the example below as a reference, if the object `num` is null,\nthen, the code inside the if statement is not executed. Otherwise,\nthe if statement will unwrap the object `num` into the `not_null_num`\nobject. This `not_null_num` object is guaranteed to be not null inside\nthe scope of the if statement.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst num: ?i32 = 5;\nif (num) |not_null_num| {\n    try stdout.print(\"{d}\\n\", .{not_null_num});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n5\n```\n\n\n:::\n:::\n\n\n\n\nNow, the `orelse` keyword behaves like a binary operator. You connect two expressions with this keyword.\nOn the left side of `orelse`, you provide the expression that might result\nin a null value, and on the right side of `orelse`, you provide another expression\nthat will not result in a null value.\n\nThe idea behind the `orelse` keyword is: if the expression on the left side\nresult in a not-null value, then, this not-null value is used. However,\nif this expression on the left side result in a null value, then, the value\nof the expression on the right side is used instead.\n\nLooking at the example below, since the `x` object is currently null, the\n`orelse` decided to use the alternative value, which is the number 15.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x: ?i32 = null;\nconst dbl = (x orelse 15) * 2;\ntry stdout.print(\"{d}\\n\", .{dbl});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n30\n```\n\n\n:::\n:::\n\n\n\n\nYou can use the if statement or the `orelse` keyword, when you want to\nsolve (or deal with) this null value. However, if there is no clear solution\nto this null value, and the most logic and sane path is to simply panic\nand raise a loud error in your program when this null value is encountered,\nyou can use the `?` method of your optional object.\n\nIn essence, when you use this `?` method, the optional object is unwrapped.\nIf a not-null value is found in the optional object, then, this not-null value is used.\nOtherwise, the `unreachable` keyword is used. You can read more about this\n[`unreacheable` keyword at the official documentation](https://ziglang.org/documentation/master/#unreachable)[^un-docs].\nBut in essence, when you build your Zig source code using the build modes `ReleaseSafe` or `Debug`, this\n`unreacheable` keyword causes the program to panic and raise an error during runtime,\nlike in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn return_null(n: i32) ?i32 {\n    if (n == 5) return null;\n    return n;\n}\n\npub fn main() !void {\n    const x: i32 = 5;\n    const y: ?i32 = return_null(x);\n    try stdout.print(\"{d}\\n\", .{y.?});\n}\n```\n:::\n\n\n\n\n```\nthread 12767 panic: attempt to use null value\np7.zig:12:34: 0x103419d in main (p7):\n    try stdout.print(\"{d}\\n\", .{y.?});\n                                 ^\n```\n\n\n[^un-docs]: <https://ziglang.org/documentation/master/#unreachable>.\n\n\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
diff --git a/_freeze/Chapters/07-build-system/execute-results/html.json b/_freeze/Chapters/07-build-system/execute-results/html.json
index 5205e5b4..daf845bf 100644
--- a/_freeze/Chapters/07-build-system/execute-results/html.json
+++ b/_freeze/Chapters/07-build-system/execute-results/html.json
@@ -3,9 +3,7 @@
   "result": {
     "engine": "knitr",
     "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Build System {#sec-build-system}\n\n\nIn this chapter, we are going to talk about the build system, and how an entire project\nis built in Zig.\nOne key advantage of Zig is that it includes a build system embedded in the language itself.\nThis is great, because then you do not have to depend on an external system, separated\nfrom the compiler, to build your code.\n\n\nYou can find a good description of Zig's build system\non the [article entitled \"Build System\"](https://ziglang.org/learn/build-system/#user-provided-options)[^zig-art1]\nfrom the official Zig's website.\nWe also have the excellent [series of posts written by Felix](https://zig.news/xq/zig-build-explained-part-1-59lf)[^felix].\nHence, this chapter represents an extra resource for you to consult and rely on.\n\n[^felix]: <https://zig.news/xq/zig-build-explained-part-1-59lf>\n[^zig-art1]: <https://ziglang.org/learn/build-system/#user-provided-options>\n\nBuilding code is one of the things that Zig is best at. One thing that is particularly\ndifficult in C/C++ and even in Rust, is to cross-compile source code to multiple targets\n(e.g. multiple computer architectures and operating systems),\nand the `zig` compiler is known for being one of the best existing pieces of software\nfor this particular task.\n\n\n\n\n## How source code is built?\n\nWe already have talked about the challenges of building source code in low-level languages\nat @sec-project-files. As we described at that section, programmers invented Build Systems\nto surpass these challenges on the process of building source code in low-level languages.\n\nLow-level languages uses a compiler to compile (or to build) your source code into binary instructions.\nIn C and C++, we normally use compilers like `gcc`, `g++` or `clang` to compile\nour C and C++ source code into these instructions.\nEvery language have its own compiler, and this is no different in Zig.\n\nIn Zig, we have the `zig` compiler to compile our Zig source code into\nbinary instructions that can be executed by our computer.\nIn Zig, the compilation (or the build) process involves\nthe following components:\n\n- The Zig modules that contains your source code;\n- Library files (either a dynamic library or a static library);\n- Compiler flags that tailors the build process to your needs.\n\nThese are the things that you need to connect together in order to build your\nsource code in Zig. In C and C++, you would have an extra component, which are the header files of\nthe libraries that you are using. But header files do not exist in Zig, so, you only need\nto care about them if you are linking your Zig source code with a C library.\nIf that is not your case, you can forget about it.\n\nYour build process is usually organized in a build script. In Zig, we normally\nwrite this build script into a Zig module in the root directory of our project,\nnamed as `build.zig`. You write this build script, then, when you run it, your project\nget's built into binary files that you can use and distribute to your users.\n\nThis build script is normally organized around *target objects*. A target is simply\nsomething to be built, or, in other words, it's something that you want the `zig` compiler\nto build for you. This concept of \"targets\" is present in most Build Systems,\nespecially in CMake[^cmake].\n\n[^cmake]: <https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html>\n\nThere are four types of target objects that you can build in Zig, which are:\n\n- An executable (e.g. a `.exe` file on Windows).\n- A shared library (e.g. a `.so` file in Linux or a `.dll` file on Windows).\n- A static library (e.g. a `.a` file in Linux or a `.lib` file on Windows).\n- An executable file that executes only unit tests (or, a \"unit tests executable\").\n\nWe are going to talk more about these target objects at @sec-targets.\n\n\n\n## The `build()` function {#sec-build-fun}\n\nA build script in Zig always contains a public (and top-level) `build()` function declared.\nIt is like the `main()` function on the main Zig module of your project, that we discussed at @sec-main-file.\nBut instead of creating the entrypoint to your code, this `build()` function is the entrypoint to the build process.\n\nThis `build()` function should accept a pointer to a `Build` object as input, and it should use this \"build object\" to perform\nthe necessary steps to build your project. The return type of this function is always `void`,\nand this `Build` struct comes directly from the Zig Standard Library (`std.Build`). So, you can \naccess this struct by just importing the Zig Standard Library into your `build.zig` module.\n\nJust as a very simple example, here you can see the source code necessary to build\nan executable file from the `hello.zig` Zig module.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"hello.zig\"),\n        .target = b.host,\n    });\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\nYou can define and use other functions and objects in this build script. You can also import\nother Zig modules as you would normally do in any other module of your project.\nThe only real requirement for this build script, is to have a public and top-level\n`build()` function defined, that accepts a pointer to a `Build` struct as input.\n\n\n## Target objects {#sec-targets}\n\nAs we described over the previous sections, a build script is composed around target objects.\nEach target object is normally a binary file (or an output) that you want to get from the build process. You can list\nmultiple target objects in your build script, so that the build process generates multiple\nbinary files for you at once.\n\nFor example, maybe you are a developer working in a cross-platform application,\nand, because this application is cross-platform, you probably need to release\nbinary files of your software for each OS supported by your application to your end users.\nThus, you can define a different target object in your build script\nfor each OS (Windows, Linux, etc.) where you want to publish your software.\nThis will make the `zig` compiler to build your project to multiple target OS's at once.\nThe Zig Build System official documentation have a [great code example that demonstrates this strategy](https://ziglang.org/learn/build-system/#handy-examples)[^zig-ex].\n\n[^zig-ex]: <https://ziglang.org/learn/build-system/#handy-examples>\n\n\nA target object is created by the following methods of the `Build` struct that we introduced\nat @sec-build-fun:\n\n- `addExecutable()` creates an executable file;\n- `addSharedLibrary()` creates a shared library file;\n- `addStaticLibrary()` creates a static library file;\n- `addTest()` creates an executable file that executes unit tests.\n\n\nThese functions are methods from the `Build` struct that you receive\nas input of the `build()` function. All of them, create as output\na `Compile` object, which represents a target object to be compiled\nby the `zig` compiler. All of these functions accept a similar struct literal as input.\nThis struct literal defines three essential specs about this target object that you are building:\n`name`, `target` and `root_source_file`.\n\nWe have already seen these three options being used on the previous example,\nwhere we used the `addExecutable()` method to create an executable target object.\nThis example is reproduced below. Notice the use of the `path()` method\nfrom the `Build` struct, to define a path in the `root_source_file` option.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n```\n:::\n\n\n\n\nThe `name` option specify the name that you want to give to the binary file defined\nby this target object. So, in this example, we are building an executable file named `hello`.\nIs common to set this `name` option to the name of your project.\n\n\nFurthermore, the `target` option specify the target computer architecture (or the target operating system) of this\nbinary file. For example, if you want this target object to run on a Windows machine\nthat uses a `x86_64` architecture, you can set this `target` option to `x86_64-windows-gnu` for example.\nThis will make the `zig` compiler to compile the project to run on a `x86_64` Windows machine.\nYou can see the full list of architectures and OS's that the `zig` compiler supports by running\nthe `zig targets` command in the terminal.\n\nNow, if you are building the project to run on the current machine\nthat you are using to run this build script, you can set this `target`\noption to the `host` method of the `Build` object, like we did in the example above.\nThis `host` method identifies the current machine where you are\ncurrently running the `zig` compiler.\n\n\nAt last, the `root_source_file` option specifies the root Zig module of your project.\nThat is the Zig module that contains the entrypoint to your application (i.e. the `main()` function), or, the main API of your library.\nThis also means that, all the Zig modules that compose your project are automatically discovered\nfrom the import statements you have inside this \"root source file\".\nThe `zig` compiler can detect when a Zig module depends on the other through the import statements,\nand, as a result, it can discover the entire map of Zig modules used in your project.\n\nThis is handy, and it is different from what happens in other build systems.\nIn CMake for example, you have to explicitly list the paths to all source files that you want to\ninclude in your build process. This is probably a symptom of the \"lack of conditional\ncompilation\" in the C and C++ compilers. Since they lack this feature, you have\nto explicitly choose which source files should be sent to the C/C++ compiler, because not\nevery C/C++ code is portable or supported in every operating system, and, therefore,\nwould cause a compilation error in the C/C++ compiler.\n\n\nNow, one important detail about the build process is that, you have to **explicitly\ninstall the target objects that you create in your build script**, by using the\n`installArtifact()` method of the `Build` struct.\n\nEverytime you invoke the build process of your project, by calling the `build` command\nof the `zig` compiler, a new directory named `zig-out` is created in the root\ndirectory of your project. This new directory contains the outputs of the build process,\nthat is, the binary files built from your source code.\n\nWhat the `installArtifact()` method do is to install (or copy) the built target objects\nthat you defined to this `zig-out` directory.\nThis means that, if you do not\ninstall the target objects you define in your build script, these target objects are\nessentially discarded at the end of the build process.\n\nFor example, you might be building a project that uses a third party library that is built\ntogether with the project. So, when you build your project, you would need first, to\nbuild the third party library, and then, you link it with the source code of your project.\nSo, in this case, we have two binary files that are generated in the build process (the executable file of your project, and the third party library).\nBut only one is of interest, which is the executable file of our project.\nWe can discard the binary file of the third party library, by simply not installing it\ninto this `zig-out` directory.\n\nThis `installArtifact()` method is pretty straightforward. Just remember to apply it to every\ntarget object that you want to save into the `zig-out` directory, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n## Setting the build mode\n\nWe have talked about the three essential options that are set when you create a new target object.\nBut there is also a fourth option that you can use to set the build mode of this target object,\nwhich is the `optimize` option.\nThis option is called this way, because the build modes in Zig are treated more of\nan \"optimization vs safety\" problem. So optimization plays an important role here.\nDon't worry, I'm going back to this question very soon.\n\nIn Zig, we have four build modes (which are listed below). Each one of these build modes offer\ndifferent advantages and characteristics. As we described at @sec-compile-debug-mode, the `zig` compiler\nuses the `Debug` build mode by default, when you don't explicitly choose a build mode.\n\n- `Debug`, mode that produces and includes debugging information in the output of the build process (i.e. the binary file defined by the target object);\n- `ReleaseSmall`, mode that tries to produce a binary file that is small in size;\n- `ReleaseFast`, mode that tries to optimize your code, in order to produce a binary file that is as fast as possible;\n- `ReleaseSafe`, mode that tries to make your code as safe as possible, by including safeguards when possible.\n\nSo, when you build your project, you can set the build mode of your target object to `ReleaseFast` for example, which will tell\nthe `zig` compiler to apply important optimizations in your code. This creates a binary file\nthat simply runs faster on most contexts, because it contains a more optimized version of your code.\nHowever, as a result, we often lose some safety features in our code.\nBecause some safety checks are removed from the final binary file,\nwhich makes your code run faster, but in a less safe manner.\n\nThis choice depends on your current priorities. If you are building a cryptography or banking system, you might\nprefer to prioritize safety in your code, so, you would choose the `ReleaseSafe` build mode, which is a little\nslower to run, but much more secure, because it includes all possible runtime safety checks in the binary file\nbuilt in the build process. In the other hand, if you are writing a game for example, you might prefer to prioritize performance\nover safety, by using the `ReleaseFast` build mode, so that your users can experience faster frame rates in your game.\n\nIn the example below, we are creating the same target object that we have used on previous examples.\nBut this time, we are specifying the build mode of this target object to the `ReleaseSafe` mode.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .optimize = .ReleaseSafe\n});\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n## Setting the version of your build\n\nEverytime you build a target object in your build script, you can assign a version\nnumber to this specific build, following a semantic versioning framework.\nYou can find more about semantic versioning by visiting the [Semantic Versioning website](https://semver.org/)[^semver].\nAnyway, in Zig, you can specify the version of your build, by providing a `SemanticVersion` struct to\nthe `version` option, like in the example below:\n\n\n[^semver]: <https://semver.org/>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .version = .{\n        .major = 2, .minor = 9, .patch = 7\n    }\n});\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n## Detecting the OS in your build script {#sec-detect-os}\n\nIs very common in Build Systems to use different options, or, to include different modules, or,\nto link against different libraries depending on the Operational System (OS)\nthat you are targeting in the build process.\n\nIn Zig, you can detect the target OS of the build process, by looking\nat the `os.tag` inside the `builtin` module from the Zig library.\nIn the example below, we are using an if statement to run some\narbitrary code when the target of the build process is a\nWindows system.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nif (builtin.target.os.tag == .windows) {\n    // Code that runs only when the target of\n    // the compilation process is Windows.\n}\n```\n:::\n\n\n\n\n\n## Adding a run step to your build process\n\nOne thing that is neat in Rust is that you can compile and run your\nsource code with one single command (`cargo run`) from the Rust compiler.\nWe saw at @sec-compile-run-code how can we perform a similar job in Zig, by\nbuilding and running our Zig source code through the `run` command from the `zig` compiler.\n\nBut how can we, at the same time, build and run the binary file specified by a target object in our\nbuild script?\nThe answer is by including a \"run artifact\" in our build script.\nA run artifact is created through the `addRunArtifact()` method from the `Build` struct.\nWe simply provide as input to this function the target object that describes the binary file that we\nwant to execute. As a result, this function creates a run artifact that is capable of executing\nthis binary file.\n\nIn the example below, we are defining an executable binary file named `hello`,\nand we use this `addRunArtifact()` method to create a run artifact that will execute\nthis `hello` executable file.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"src/hello.zig\"),\n    .target = b.host\n});\nb.installArtifact(exe);\nconst run_arti = b.addRunArtifact(exe);\n```\n:::\n\n\n\n\nNow that we have created this run artifact, we need to include it in\nthe build process. We do that by declaring a new step in our build\nscript to call this artifact, through the `step()` method of the `Build`\nstruct.\n\nWe can give any name we want to this step, but, for our\ncontext here, I'm going to name this step as \"run\".\nAlso, I give it a brief description to this step (\"Run the project\").\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst run_step = b.step(\n    \"run\", \"Run the project\"\n);\n```\n:::\n\n\n\n\n\nNow that we have declared this \"run step\" we need to tell Zig that\nthis \"run step\" depends on the run artifact.\nIn other words, a run artifact always depends on a \"step\" to effectively be executed.\nBy creating this dependency\nwe finally stablish the necessary commands to build and run the executable file\nfrom the build script.\n\nWe can establish a dependency between the run step and the run artifact\nby using the `dependsOn()` method from the run step. So, we first\ncreate the run step, and then, we link it with the run artifact, by\nusing this `dependsOn()` method from the run step.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nrun_step.dependOn(&run_arti.step);\n```\n:::\n\n\n\n\nThe entire source code of this specific build script that\nwe wrote, piece by piece, in this section, is\navailable in the `build_and_run.zig` module. You can\nsee this module by\n[visiting the official repository of this book](https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig)\n[^module-src].\n\n\n[^module-src]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig>\n\nWhen you declare a new step in your build script, this step\nbecomes available through the `build` command in the `zig` compiler.\nYou can actually see this step by running `zig build --help` in the terminal, like\nin the example below, where we can see that this new \"run\"\nstep that we declared in the build script appeared in the output.\n\n```bash\nzig build --help\n```\n\n```\nSteps:\n  ...\n  run   Run the project\n  ...\n```\n\nNow, everything that we need to is to\ncall this \"run\" step that we created in our build script. We\ncall it by using the name that we gave to this step\nafter the `build` command from the `zig` compiler.\nThis will cause the compiler to build our executable file\nand execute it at the same time.\n\n```bash\nzig build run\n```\n\n## Build unit tests in your project\n\nWe have talked at length about writing unit tests in Zig at @sec-unittests,\nand we also have talked about how to execute these unit tests through\nthe `test` command of the `zig` compiler. However,\nas we did with the `run` command on the previous section, we also might want to\ninclude some commands in our build script to also build and execute the unit tests in our project.\n\nSo, once again, we are going to discuss how a specific built-in command from the `zig` compiler,\n(in this case, the `test` command) can be used in a build script in Zig.\nHere is where a \"test target object\" comes into play.\nAs was described at @sec-targets, we can create a test target object by using the `addTest()` method of\nthe `Build` struct. The first thing that we need to do is to\ndeclare a test target object in our build script.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst test_exe = b.addTest(.{\n    .name = \"unit_tests\",\n    .root_source_file = b.path(\"src/main.zig\"),\n    .target = b.host,\n});\nb.installArtifact(test_exe);\n```\n:::\n\n\n\n\n\nA test target object essentially selects all `test` blocks in all Zig modules\nacross your project, and builds only the source code present inside\nthese `test` blocks in your project. As a result, this target object\ncreates an executable file that contains only the source code present\nin all of these `test` blocks (i.e. the unit tests) in your project.\n\nPerfect! Now that we have declared this test target object, an executable file\nnamed `unit_tests` is built by the `zig` compiler when we trigger the build\nscript with the `build` command. After the build\nprocess is finished, we can simply execute this `unit_tests` executable\nin the terminal.\n\nHowever, if you remember the previous section, we already learned\nhow can we create a run step in our build script, to execute an executable file\nbuilt by the build script.\n\nSo, we could simply add a run step in our build script to run these unit tests\nfrom a single command in the `zig` compiler, to make our lifes easier.\nIn the example below, we demonstrate the commands to\nregister a new build step called \"tests\" in our build script\nto run these unit tests.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst run_arti = b.addRunArtifact(test_exe);\nconst run_step = b.step(\"tests\", \"Run unit tests\");\nrun_step.dependOn(&run_arti.step);\n```\n:::\n\n\n\n\nNow that we registered this new build step, we can trigger it by calling the command below\nin the terminal. You can also checkout the complete source\ncode for this specific build script at the `build_tests.zig` module at the\n[official repository of this book](https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig)\n[^module-src2].\n\n\n[^module-src2]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig>\n\n\n```bash\nzig build tests\n```\n\n\n## Tailoring your build process with user-provided options\n\nSometimes, you want to make a build script that is customizable by the user\nof your project. You can do that by creating user-provided options in\nyour build script. We create an user-provided option by using the\n`option()` method from the `Build` struct.\n\nWith this method, we create a \"build option\" which can be passed\nto the `build.zig` script at the command line. The user have the power of setting\nthis option at the `build` command from the\n`zig` compiler. In other words, each build option that we create\nbecomes a new command line argument that is accessible through the `build` command\nof the compiler.\n\nThese \"user-provided options\" are set by using the prefix `-D` in the command line.\nFor example, if we declare an option named `use_zlib`, that receives a boolean value which\nindicates if we should link our source code to `zlib` or not, we can set the value\nof this option in the command line with `-Duse_zlib`. The code example below\ndemonstrates this idea:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const use_zlib = b.option(\n        bool,\n        \"use_zlib\",\n        \"Should link to zlib?\"\n    ) orelse false;\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"example.zig\"),\n        .target = b.host,\n    });\n    if (use_zlib) {\n        exe.linkSystemLibrary(\"zlib\");\n    }\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\n```bash\nzig build -Duse_zlib=false\n```\n\n\n## Linking to external libraries\n\n\nOne essential part of every build process is the linking stage.\nThis stage is responsible for combining the multiple object files\nthat represent your code, into a single executable file. It also links\nthis executable file to external libraries, if you use any in your code.\n\nIn Zig, we have two notions of a \"library\", which are: 1) a system's library;\n2) a local library. A system's library is just a library that already is installed\nin your system. While a local library is a library that belongs to the current\nproject. Is a library that is present in your project directory, and\nthat you are building together with your project source code.\n\nThe basic difference between the two, is that a system's library is already\nbuilt and installed in your system, supposedly, and all you need to do\nis to link your source code to this library to start using it.\nWe do that by using the `linkSystemLibrary()` method from a\n`Compile` object. This method accepts the name of the library\nin a string as input. Remember from @sec-targets that a `Compile` object\nis a target object that you declare in your build script.\n\nWhen you link a particular target object with a system's library,\nthe `zig` compiler will use `pkg-config` to find where\nare the binary files and also the header files of this library\nin your system.\nWhen it finds these files, the linker present in the `zig` compiler\nwill link your object files with the files of this library to\nproduce a single binary file for you.\n\nIn the example below, we are creating an executable file named `image_filter`,\nand, we are linking this executable file to the C Standard Library with the\nmethod `linkLibC()`, but we also are linking this executable file to the\nC library `libpng` that is currently installed in my system.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"image_filter\",\n        .root_source_file = b.path(\"src/main.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n    exe.linkLibC();\n    exe.linkSystemLibrary(\"png\");\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\nIf you are linking with a C library in your project, is generally a good idea\nto also link your code with the C Standard Library. Because is very likely\nthat this C library uses some functionality of the C Standard Library at some point.\nThe same goes to C++ libraries. So, if you are linking with\nC++ libraries, is a good idea to link your project with the C++\nStandard Library by using the `linkLibCpp()` method.\n\nOn the order side, when you want to link with a local library,\nyou should use the `linkLibrary()` method of a `Compile` object.\nThis method expects to receive another `Compile` object as input.\nThat is, another target object defined in your build script,\nusing either the `addStaticLibrary()` or `addSharedLibrary()` methods\nwhich defines a library to be built.\n\nAs we discussed earlier, a local library is a library\nthat is local to your project, and that is being built together\nwith your project. So, you need to create a target object in your build script\nto build this local library. Then, you link the target objects of interest in your project,\nwith this target object that identifies this local library.\n\nTake a look at this example extracted from the build script of the [`libxev` library](https://github.com/mitchellh/libxev/tree/main)[^libxev2].\nYou can see in this snippet that\nwe are declaring a shared library file, from the `c_api.zig`\nmodule. Then, later in the build script, we declare an\nexecutable file named `\"dynamic-binding-test\"`, which\nlinks to this shared library that we defined earlier\nin the script.\n\n[^libxev2]: <https://github.com/mitchellh/libxev/tree/main>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst optimize = b.standardOptimizeOption(.{});\nconst target = b.standardTargetOptions(.{});\n\nconst dynamic_lib = b.addSharedLibrary(.{\n    .name = dynamic_lib_name,\n    .root_source_file = b.path(\"src/c_api.zig\"),\n    .target = target,\n    .optimize = optimize,\n});\nb.installArtifact(dynamic_lib);\n// ... more lines in the script\nconst dynamic_binding_test = b.addExecutable(.{\n    .name = \"dynamic-binding-test\",\n    .target = target,\n    .optimize = optimize,\n});\ndynamic_binding_test.linkLibrary(dynamic_lib);\n```\n:::\n\n\n\n\n\n\n## Building C code {#sec-building-c-code}\n\nThe `zig` compiler comes with a C compiler embedded in it. In other words,\nyou can use the `zig` compiler to build C projects. This C compiler is available\nthrough the `cc` command of the `zig` compiler.\n\nAs an example, let's use the famous [FreeType library](https://freetype.org/)[^freetype].\nFreeType is one of the most widely used pieces of software in the world.\nIt is a C library designed to produce high-quality fonts. But it is also\nheavily used in the industry to natively render text and fonts\nin the screen of your computer.\n\nIn this section, we are going to write a build script, piece by piece, that is capable\nof building the FreeType project from source.\nYou can find the source code of this build script on the\n[`freetype-zig` repository](https://github.com/pedropark99/freetype-zig/tree/main)[^freetype-zig]\navailable at GitHub.\n\n[^freetype]: <https://freetype.org/>\n[^freetype-zig]: <https://github.com/pedropark99/freetype-zig/tree/main>\n\nAfter you download the source code of FreeType from the official website[^freetype],\nyou can start writing the `build.zig` module. We begin by defining the target object\nthat defines the binary file that we want to compile.\n\nAs an example, I will build the project as a static library file using the `addStaticLibrary()` method\nto create the target object.\nAlso, since FreeType is a C library, I will also link the library\nagainst `libc` through the `linkLibC()` method, to guarantee that any use\nof the C Standard Library is covered in the compilation process.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst target = b.standardTargetOptions(.{});\nconst opti = b.standardOptimizeOption(.{});\nconst lib = b.addStaticLibrary(.{\n    .name = \"freetype\",\n    .optimize = opti,\n    .target = target,\n});\nlib.linkLibC();\n```\n:::\n\n\n\n\n### Creating C compiler flags\n\nCompiler flags are also known as \"compiler options\" by many programmers,\nor also, as \"command options\" in the GCC official documentation.\nIt's fair to also call them as the \"command-line arguments\" of the C compiler.\nIn general, we use compiler flags to turn on (or turn off) some features from the compiler,\nor to tweak the compilation process to fit the needs of our project.\n\nIn build scripts written in Zig, we normally list the C compiler flags to be used in the compilation process\nin a simple array, like in the example below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c_flags = [_][]const u8{\n    \"-Wall\",\n    \"-Wextra\",\n    \"-Werror\",\n};\n```\n:::\n\n\n\n\nIn theory, there is nothing stopping you from using this array to add \"include paths\" (with the `-I` flag)\nor \"library paths\" (with the `-L` flag) to the compilation process. But there are formal ways in Zig to\nadd these types of paths in the compilation process. Both are discussed at @sec-include-paths\nand @sec-library-paths.\n\nAnyway, in Zig, we add C flags to the build process together with the C files that we want to compile, by using the\n`addCSourceFile()` and `addCSourceFiles()` methods. In the example above, we have just declared\nthe C flags that we want to use. But we haven't added them to the build process yet.\nTo do that, we also need to list the C files to be compiled.\n\n### Listing your C files\n\nThe C files that contains \"cross-platform\" source code are listed in the `c_source_files`\nobject below. These are the C files that are included by default in every platform\nsupported by the FreeType library. Now, since the amount of C files in the FreeType library is big,\nI have omitted the rest of the files in the code example below, for brevity purposes.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c_source_files = [_][]const u8{\n    \"src/autofit/autofit.c\",\n    \"src/base/ftbase.c\",\n    // ... and many other C files.\n};\n```\n:::\n\n\n\n\nNow, in addition to \"cross-platform\" source code, we also have some C files in the FreeType project\nthat are platform-specific, meaning that, they contain source code that can only be compiled in specific platforms,\nand, as a result, they are only included in the build process on these specific target platforms.\nThe objects that list these C files are exposed in the code example below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst windows_c_source_files = [_][]const u8{\n    \"builds/windows/ftdebug.c\",\n    \"builds/windows/ftsystem.c\"\n};\nconst linux_c_source_files = [_][]const u8{\n    \"src/base/ftsystem.c\",\n    \"src/base/ftdebug.c\"\n};\n```\n:::\n\n\n\n\nNow that we declared both the files that we want to include and the C compiler flags to be used,\nwe can add them to the target object that describes the FreeType library, by using the\n`addCSourceFile()` and `addCSourceFiles()` methods.\n\nBoth of these functions are methods from a `Compile` object (i.e. a target object).\nThe `addCSourceFile()` method is capable of adding a single C file to the target object,\nwhile the `addCSourceFiles()` method is used to add multiple C files in a single command.\nYou might prefer to use `addCSourceFile()` when you need to use different compiler flags\non specific C files in your project. But, if you can use the same compiler flags\nacross all C files, then, you will probably find `addCSourceFiles()` a better choice.\n\nNotice that we are using the `addCSourceFiles()` method in the example below,\nto add both the C files and the C compiler flags. Also notice that we\nare using the `os.tag` that we learned about at @sec-detect-os, to add the platform-specific\nC files.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nlib.addCSourceFiles(\n    &c_source_files, &c_flags\n);\n\nswitch (builtin.target.os.tag) {\n    .windows => {\n        lib.addCSourceFiles(\n            &windows_c_source_files,\n            &c_flags\n        );\n    },\n    .linux => {\n        lib.addCSourceFiles(\n            &linux_c_source_files,\n            &c_flags\n        );\n    },\n    else => {},\n}\n```\n:::\n\n\n\n\n\n### Defining C Macros\n\nC Macros are an essential part of the C programming language,\nand they are commonly defined through the `-D` flag from a C compiler.\nIn Zig, you can define a C Macro to be used in your build process\nby using the `defineCMacro()` method from the target object that\ndefines the binary file that you are building.\n\nIn the example below, we are using the `lib` object that we have defined\non the previous sections to define some C Macros used by the FreeType project\nin the compilation process. These C Macros specify if FreeType\nshould (or should not) include functionalities from different\nexternal libraries.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nlib.defineCMacro(\"FT_DISABLE_ZLIB\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_PNG\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_HARFBUZZ\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BZIP2\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BROTLI\", \"TRUE\");\nlib.defineCMacro(\"FT2_BUILD_LIBRARY\", \"TRUE\");\n```\n:::\n\n\n\n\n\n### Adding library paths {#sec-library-paths}\n\nLibrary paths are paths in your computer where the C compiler will look (or search) for\nlibrary files to link against your source code. In other words, when you use a library in your\nC source code, and you ask the C compiler to link your source code against this library,\nthe C compiler will search for the binary files of this library across the paths listed\nin this \"library paths\" set.\n\nThese paths are platform specific, and, by default, the C compiler starts by looking at a\npre-defined set of places in your computer. But you can add more paths (or more places)\nto this list. For example, you may have a library installed in a non-conventional place of your\ncomputer, and you can make the C compiler \"see\" this \"non-conventional place\" by adding this path\nto this list of pre-defined paths.\n\nIn Zig, you can add more paths to this set by using the `addLibraryPath()` method from your target object.\nFirst, you defined a `LazyPath` object, containing the path you want to add, then,\nyou provide this object as input to the `addLibraryPath()` method, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst lib_path: std.Build.LazyPath = .{\n    .cwd_relative = \"/usr/local/lib/\"\n};\nlib.addLibraryPath(lib_path);\n```\n:::\n\n\n\n\n\n\n\n### Adding include paths {#sec-include-paths}\n\nThe preprocessor search path is a popular concept from the\nC community, but it is also known by many C programmers as \"include paths\", because\nthe paths in this \"search path\" relate to the `#include` statements found in the C files.\n\nInclude paths are similar to library paths. They are a set of pre-defined places in your computer where\nthe C compiler will look for files during the compilation process. But instead of looking for\nlibrary files, the include paths are places where the compiler looks for header files included\nin your C source code.\nThis is why many C programmers prefer to call these paths as the \"preprocessor search path\".\nBecause header files are processed during the preprocessor stage of the compilation\nprocess.\n\nSo, every header file that you include in your C source code, through a `#include` statements needs to\nbe found somewhere, and the C compiler will search for this header file across the paths listed in this \"include paths\" set.\nInclude paths are added to the compilation process through the `-I` flag.\n\nIn Zig, you can add new paths to this pre-defined set of paths, by using the `addIncludePath()` method\nfrom your target object. This method also accepts a `LazyPath` object as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst inc_path: std.Build.LazyPath = .{\n    .path = \"./include\"\n};\nlib.addIncludePath(inc_path);\n```\n:::\n",
-    "supporting": [
-      "07-build-system_files"
-    ],
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/09-data-structures/execute-results/html.json b/_freeze/Chapters/09-data-structures/execute-results/html.json
index d7ca70b5..7f635a42 100644
--- a/_freeze/Chapters/09-data-structures/execute-results/html.json
+++ b/_freeze/Chapters/09-data-structures/execute-results/html.json
@@ -3,9 +3,7 @@
   "result": {
     "engine": "knitr",
     "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Data Structures\n\nIn this chapter, I want to present the most common Data Structures that are available from\nthe Zig Standard Library, especially `ArrayList` and also `HashMap`. These are generic Data Structures\nthat you can use to store and control any type of data that is produced by your application.\n\n## Dynamic Arrays {#sec-dynamic-array}\n\nIn high level languages, arrays are usually dynamic. They can easily grow\nin size when they have to, and you don't need to worry about it.\nIn contrast, arrays in low level languages are usually static by default.\nThis is the reality of C, C++, Rust and also Zig. Static arrays were presented at\n@sec-arrays, but in this section, we are going to talk about dynamic arrays in Zig.\n\nDynamic arrays are simply arrays that can grow in size during the runtime\nof your program. Most low level languages have some implementation of\na dynamic array in their standard library. C++ have `std::vector`, Rust have `Vec`,\nand Zig have `std.ArrayList`.\n\nThe `std.ArrayList` struct provides a contiguous and growable array for you.\nIt works like any other dynamic array, it allocates a contiguous block of memory, and when this block have no space left,\n`ArrayList` allocates another contiguous and bigger block of memory, copies the\nelements to this new location, and erases (or frees) the previous block of memory.\n\n\n### Capacity vs Length\n\nWhen we talk about dynamic arrays, we usually have two similar concepts that\nare very essential to how a dynamic array works behind the hood.\nThese concepts are *capacity* and *length*. In some contexts, especially\nin C++, *length* is also called of *size*.\n\nAlthough they look similar, these concepts represent different things\nin the context of a dynamic array. *Capacity* is the number of items (or elements)\nthat your dynamic array can currently hold without the need to allocate more memory.\n\nIn contrast, the *length* refers to how many elements in the array\nare currently being used, or, in other words, how many elements in this array\nthat you have assigned a value to. Every dynamic array works around\na block of allocated memory, which represents an array with total capacity for $n$ elements.\nHowever, only a portion of these $n$ elements are being used most of the time. This portion\nof $n$ is the *length* of the array. So every time you append a new value\nto the array, you are incrementing its *length* by one.\n\nThis means that a dynamic array usually works with an extra margin, or, an extra space\nwhich is currently empty, but it is waiting and ready to be used. This \"extra space\"\nis essentially the difference between *capacity* and *length*. *Capacity* represents\nthe total number of elements that the array can hold without the need to re-allocate\nor re-expand the array, while the *length* represents how much of this capacity\nis currently being used to hold/store values.\n\n@fig-capacity-length presents this idea visually. Notice that, at first,\nthe capacity of the array is greater than the length of the array.\nSo, the dynamic array have extra space that is currently empty, but it\nis ready to receive a value to be stored.\n\n![Difference between capacity and length in a dynamic array](./../Figures/dynamic-array.png){#fig-capacity-length}\n\nWe can also see at @fig-capacity-length that, when *length* and *capacity* are equal, it means that the array have no space left.\nWe have reached the ceiling of our capacity, and because of that, if we want to store more values\nin this array, we need to expand it. We need to get a bigger space that can hold more values\nthan what we currently have.\n\nA dynamic array works by expanding the underlying array, whenever the *length* becomes equal\nto the *capacity* of the array. It basically allocates a new contiguous block of memory that is bigger\nthan the previous one, then, it copies all values that are currently being stored to this new\nlocation (i.e. this new block of memory), then, it frees the previous block of\nmemory. At the end of this process, the new underlying array have a bigger *capacity*, and, therefore,\nthe *length* becomes, once again, smaller than the *capacity* of the array.\n\nThis is the cycle of an dynamic array. Notice that, throughout this cycle, the *capacity* is always\neither equal to or higher than the *length* of the array. If youh have an `ArrayList` object (let's suppose\nyou named it `buffer`), you can check the current capacity of your array by accessing the `capacity`\nattribute of your `ArrayList` object, while the current *length* of it is available at the `items.len`\nattribute.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// Check capacity\nbuffer.capacity;\n// Check length\nbuffer.items.len;\n```\n:::\n\n\n\n\n\n### Creating an `ArrayList` object\n\nIn order to use `ArrayList`, you must provide an allocator object to it.\nRemember, Zig does not have a default memory allocator. And as I described at @sec-allocators, all memory\nallocations must be done by an allocator object that you define, that\nyou have control over. In our example here, I'm going to use\na general purpose allocator, but you can use any other allocator\nof your preference.\n\nWhen you initialize an `ArrayList` object, you must provide the data type of the elements of\nthe array. In other words, this defines the type of data that this array (or container) will\nstore. Therefore, if I provide the `u8` type to it, then, I will create a dynamic\narray of `u8` values. However, if I provide a struct that I have defined instead, like the struct `User`\nfrom @sec-structs-and-oop, then, a dynamic array of `User` values\nwill be created. In the example below, with the expression `ArrayList(u8)` we\nare creating a dynamic array of `u8` values.\n\nAfter you provide the data type of the elements of the array, you can initialize\nan `ArrayList` object by either using the `init()` or the `initCapacity()` methods.\nThe former method receives only the allocator object\nas input, while the latter method receives both the allocator object and a capacity number as inputs.\nWith the latter method, you not only initialize the struct, but you\nalso set the starting capacity of the allocated array.\n\nUsing the `initCapacity()` method is the preferred way to initialize your dynamic array.\nBecause reallocations, or, in other words, the process of expanding the capacity of the array,\nis always a high cost operation. You should take any possible opportunity to avoid reallocations in\nyour array. If you know how much space your array needs to occupy at the beginning,\nyou should always use `initCapacity()` to create your dynamic array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n```\n:::\n\n\n\n\n\nIn the example above, the `buffer` object starts as an array of 100 elements. If this\n`buffer` object needs to create more space to accomodate more elements during the runtime of your program, the `ArrayList`\ninternals will perform the necessary actions for you automatically.\nAlso notice the `deinit()` method being used to destroy the `buffer` object at the\nend of the current scope, by freeing all the memory that was allocated for the dynamic\narray stored in this `buffer` object.\n\n\n### Adding new elements to the array\n\nNow that we have created our dynamic array, we can start to use it. You can append (a.k.a \"add\")\nnew values to this array by using the `append()` method. This method works the same way\nas the `append()` method from a Python list, or, the `emplace_back()` method from `std::vector` of C++.\nYou provide a single value to this method, and the method appends this value to the array.\n\nYou can also use the `appendSlice()` method to append multiple values at once. You provide\na slice (slices were described at @sec-arrays) to this method, and the method adds all values present\nin this slice to your dynamic array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry buffer.append('H');\ntry buffer.append('e');\ntry buffer.append('l');\ntry buffer.append('l');\ntry buffer.append('o');\ntry buffer.appendSlice(\" World!\");\n```\n:::\n\n\n\n\n### Removing elements from the array {#sec-dynamic-array-remove}\n\nYou can use the `pop()` method to \"pop\" or remove\nthe last element in the array. Is worth noting that this method\ndo not change the capacity of the array. It just deletes or erases\nthe last value stored in the array.\n\nAlso, this method returns as result the value that got deleted. That is, you can\nuse this method to both get the last value in the array, and also, remove\nit from the array. It is a \"get and remove value\" type of method.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exclamation_mark = buffer.pop();\n```\n:::\n\n\n\n\nNow, if you want to remove specific elements from specific positions\nof your array, you can use the `orderedRemove()` method from your\n`ArrayList` object. With this method, you can provide an index as input,\nthen, the method will delete the value that is at this index in the array.\nYou are effectively reducing the *length* of the array everytime you execute\nan `orderedRemove()` operation.\n\nIn the example below, we first create an `ArrayList` object, and we fill it\nwith numbers. Then, we use `orderedRemove()` to remove the value at\nindex 3 in the array, two consecutive times.\n\nAlso, notice that we are assigning the result of `orderedRemove()` to the\nunderscore character. So we are discarding the result value of this method.\nThe `orderedRemove()` method returns the value that got deleted, in a similar\nstyle to the `pop()` method.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n\nfor (0..10) |i| {\n    const index: u8 = @intCast(i);\n    try buffer.append(index);\n}\n\nstd.debug.print(\n    \"{any}\\n\", .{buffer.items}\n);\n_ = buffer.orderedRemove(3);\n_ = buffer.orderedRemove(3);\n\nstd.debug.print(\"{any}\\n\", .{buffer.items});\nstd.debug.print(\"{any}\\n\", .{buffer.items.len});\n```\n:::\n\n\n\n\n```\n{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }\n{ 0, 1, 2, 5, 6, 7, 8, 9 }\n8\n```\n\nOne key characteristic about `orderedRemove()` is that it preserves the order\nof the values in the array. So, it deletes the value that you asked it to\nremove, but it also makes sure that the order of the values that remain in the array\nstay the same as before.\n\nNow, if you don't care about the order of the values, for example, maybe you want to treat\nyour dynamic array as a set of values, like the `std::unordered_set`\nstructure from C++, you can use the `swapRemove()` method instead. This method\nworks similarly to the `orderedRemove()` method. You give an index to this\nmethod, then, it deletes the value that is at this index in the array.\nBut this method does not preserve the original order of the values that remain\nin the array. As a result, `swapRemove()` is, in general, faster than `orderedRemove()`.\n\n\n### Inserting elements at specific indexes\n\nWhen you need to insert values in the middle of your array,\ninstead of just appending them to the end of the array, you need to use\nthe `insert()` and `insertSlice()` methods, instead of\nthe `append()` and `appendSlice()` methods.\n\nThese two methods work very similarly to `insert()` and `insert_range()`\nfrom the C++ `std::vector` class. You provide an index to these methods,\nand they insert the values that you provide at that index in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 10);\ndefer buffer.deinit();\n\ntry buffer.appendSlice(\"My Pedro\");\ntry buffer.insert(4, '3');\ntry buffer.insertSlice(2, \" name\");\nfor (buffer.items) |char| {\n    try stdout.print(\"{c}\", .{char});\n}\n```\n:::\n\n\n\n\n```\nMy name P3edro\n```\n\n\n### Conclusion\n\nIf you feel the lack of some other method, I recommend\nyou to read the [official documentation for the `ArrayListAligned`](https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned)[^zig-array2]\nstruct, which describes most of the methods available\nthrough the `ArrayList` object.\n\nYou will notice that there is a lot of other methods in this page that\nI did not described here, and I recommend you to explore these methods,\nand understand how they work.\n\n[^zig-array2]: <https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned>\n\n\n\n## Maps or HashTables {#sec-maps-hashtables}\n\nSome professionals know this type of data structure by different terms, like \"map\",\n\"hashmap\" or \"associative arrays\". But the most common term used is *hashtable*.\nEvery programming language normally have some implementation of a hashtable in their\nstandard libraries. Python have `dict()`, C++ have `std::map` and `std::unordered_map`, Rust\nhave `HashMap`, Javascript have `Object()` and `Map()`, etc.\n\n\n\n### What is a hashtable?\n\nA hashtable is a data structure based on key-value pairs.\nYou provide a key and a value to this structure, then, the hashtable will store\nthe input value at a location that can be identified by the input\nkey that you provided.\nIt does that by using an underlying array and a hash function.\nThese two components are essential to how a hashtable works.\n\nUnder the hood, the hashtable contains an array. This array is where the values\nare stored, and the elements of this array are usually called of *buckets*.\nSo the values that you provide to the hashtable are stored inside buckets,\nand you access each bucket by using an index.\n\nWhen you provide a key to a hashtable, it passes this key to the\nhash function. This hash function uses some sort of hashing algorithm to transform\nthis key into an index. This index is actually an array index. It is a position\nin the underlying array of the hashtable.\nThis is how a key identifies a specific position (or location) inside the hashtable\nstructure.\n\nTherefore, you provide a key to the hashtable, and this key identifies a specific location\ninside the hashtable, then, the hashtable takes the input value that you provided,\nand stores this value in the location identified by this input key.\nYou could say that the key maps to the value stored in the hashtable. You find\nthe value, by using the key that identifies the location where the value is stored.\nThe @fig-hashtable presents this process visually.\n\n\n![A diagram of a Hashtable. Source: Wikipedia, the free encyclopedia.](./../Figures/hashtable.svg){#fig-hashtable}\n\n\nThe operation described in the previous paragraph is normally called an *insertion* operation.\nBecause you are inserting new values into the hashtable.\nBut there are other types of operations in hashtables such as *delete* and *lookup*.\nDelete is self describing, it is when you delete (or remove) a value from the hashtable.\nWhile lookup corresponds to when you look at a value that is stored in\nthe hashtable, by using the key that identifies the location where this value is stored.\n\nSometimes, instead of storing the values directly, the underlying array of the hashtable might be an array of pointers,\ni.e. the buckets of the array stores pointers that points to the value,\nor also, may be an array of linked lists.\nThese cases are common on hashtables that allows duplicate keys, or, in other words,\non hashtables that effectively handle \"collisions\" that may arise from the hash function.\n\nDuplicate keys, or this \"collision\" thing that I'm talking about, is when you have two different keys\nthat points to the same location (i.e. to the same index)\nin the underlying array of the hashtable. This might happen depending on the characteristics of the hash function\nthat is being used in the hashtable. Some implementations of the hashtable will actively deal with collisions,\nmeaning that, they will handle this case in some way. For example, the hashtable\nmight transform all buckets into linked lists. Because with a linked list you can store\nmultiple values into a single bucket.\n\nThere are different techniques to handle collisions in hashtables, which I will not describe\nin this book, because it is not our main scope here. But you can find a good description of\nsome of the most common techniques at the Wikipedia page of hashtables [@wikipedia_hashtables].\n\n\n### Hashtables in Zig {#sec-hashmap}\n\nThe Zig Standard Library provides different implementations of a hashtable.\nEach implementation have its own cons and pros, which we will\ndiscuss later on, and all of them are available through the `std.hash_map` module.\n\nThe `HashMap` struct is a general-purpose hashtable,\nwhich have very fast operations (lookup, insertion, delete), and also,\nquite high load factors for low memory usage. You can create and provide a context object\nto the `HashMap` constructor. This context object allows you to tailor\nthe behaviour of the hashtable itself, because you can\nprovide a hash function implementation to be used by the hashtable\nthrough this context object.\n\nBut let's not worry about this context object now, because it is meant to be used\nby \"experts in the field of hashtables\". Since we are most likely not\nexperts in this field, we are going to take the easy way to create\na hashtable. Which is by using the `AutoHashMap()` function.\n\n\nThis `AutoHashMap()` function is essentially a \"create a hashtable object that uses the default settings\"\ntype of function. It automatically chooses a context object, and, therefore, a hash function implementation,\nfor you. This function receives two data types as input, the first input is the data type of the keys\nthat will be used in this hashtable, while the second input is the data type of the data that will be\nstored inside the hashtable, that is, the data type of the values to be stored.\n\nIn the example below, we are providing the data type `u32` in the first argument, and `u16` in the second argument of this\nfunction. This means that we are going to use `u32` values as keys in this hashtable, while `u16` values are the actual values\nthat are going to be stored into this hashtable.\nAt the end of this process, the `hash_table` object contains a `HashMap` object\nthat uses the default settings and context.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n    std.debug.print(\n        \"Value at key 50050: {d}\\n\",\n        .{hash_table.get(50050).?}\n    );\n\n    if (hash_table.remove(57709)) {\n        std.debug.print(\n            \"Value at key 57709 successfully removed!\\n\",\n            .{}\n        );\n    }\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n}\n```\n:::\n\n\n\n\n```\nN of values stored: 3\nValue at key 50050: 55\nValue at key 57709 successfully removed!\nN of values stored: 2\n```\n\nYou can add/put new values into the hashtable by using the `put()` method. The first argument\nis the key to be used, and the second argument is the actual value that you want to store inside\nthe hashtable. In the example below, we first add the value 89 using the key 54321, next, we add\nthe value 55 using the key 50050, etc.\n\nNotice that we have used the method `count()` to see how many values are currently stored in the\nhashtable. After that, we also use the `get()` method to access (or look) at the value stored in\nthe position identified by the key 500050. The output of this `get()` method is an optional value.\nThis is why we use the `?` method at the end to get the actual value.\n\nAlso notice that we can remove (or delete) values from the hashtable by using the `remove()` method.\nYou provide the key that identifies the value that you want to delete, then, the method will\ndelete this value and return a `true` value as output. This `true` value essentially tells us\nthat the method successfully deleted the value.\n\nBut this delete operation might not be always successful. For example, you might provide the wrong\nkey to this method. I mean, maybe you provide\n(either intentionally or unintentionally) a key that points to an empty bucket,\ni.e. a bucket that still doesn't have a value in it.\nIn this case, the `remove()` method would return a `false` value.\n\n\n\n### Iterating through the hashtable\n\nIterating through the keys and values that are currently being stored in\nthe hashtable is a very common necessity.\nYou can do that in Zig by using an iterator object that can iterate\nthrough the elements of your hashtable object.\n\nThis iterator object works like any other iterator object that you would\nfind in languages such as C++ and Rust. It is basically a pointer object\nthat points to some value in the container, and has a `next()` method\nthat you can use to navigate (or iterate) through the values in the\ncontainer.\n\nYou can create such iterator object by using the `iterator()` method of the hashtable object.\nThis method returns an iterator object, from which you can use the `next()` method in conjunction\nwith a while loop to iterate through the elements of your hashtable. The `next()` method returns an optional\n`Entry` value, and therefore, you must unwrap this optional value to get the actual `Entry` value\nfrom which you can access the key and also the value identified by this key.\n\nWith this `Entry` value at hand, you can access the key of this current entry by using the `key_ptr`\nattribute and dereferencing the pointer that lives inside of it, while the value identified by this\nkey is accessed through the `value_ptr` attribute instead, which is also a pointer to be dereferenced.\nThe code example below demonstrates the use of these elements:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n\n    var it = hash_table.iterator();\n    while (it.next()) |kv| {\n        // Access the current key\n        std.debug.print(\"Key: {d} | \", .{kv.key_ptr.*});\n        // Access the current value\n        std.debug.print(\"Value: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n:::\n\n\n\n\n```\nKey: 54321 | Value: 89\nKey: 50050 | Value: 55\nKey: 57709 | Value: 41\n```\n\n\nIf you want to iterate specifically through the values or the keys of your hashtable,\nyou can create a key iterator or a value iterator object. These are also iterator\nobjects, which have the same `next()` method that you can use to iterate through the\nhashtable.\n\nKey iterators are created from the `keyIterator()` method of your\nhashtable object, while value iterators are created from the `valueIterator()` method.\nAll you have to do is to unwrap the value from the `next()` method and deference it\ndirectly to access the key or the value that you are iterating over.\nThe code example below demonstrates the use of a key iterator,\nbut you can replicate the same logic to a value iterator.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar kit = hash_table.keyIterator();\nwhile (kit.next()) |key| {\n    std.debug.print(\"Key: {d}\\n\", .{key.*});\n}\n```\n:::\n\n\n\n\n```\nKey: 54321\nKey: 50050\nKey: 57709\n```\n\n\n### The `ArrayHashMap` hashtable {#sec-array-map}\n\nIf you need to iterate through the elements of your hashtable constantly,\nyou might want to use the `ArrayHashMap` struct for your specific case,\ninstead of going with the usual and general-purpose `HashMap` struct.\n\nThe `ArrayHashMap` struct creates a hashtable that is faster to iterate over.\nThat is why this specific type of hashtable might be valuable to you.\nSome other properties of a `ArrayHashMap` hashtable are:\n\n- the order of insertion is preserved, i.e. the order of the values that you find while iterating through this hashtable is actually the order in which these values were inserted in the hashtable.\n- the key-value pairs are stored sequentially, one after another.\n\n\nYou can create an `ArrayHashMap` object by using, once again, a helper function that\nchooses automatically for you a hash function implementation. This is the\n`AutoArrayHashMap()` function, which works very similarly to the `AutoHashMap()`\nfunction that we presented at @sec-hashmap.\n\nYou provide two data types to this function. The data type of the keys that will be\nused in this hashtable, and the data type of the values that will be stored in\nthis hashtable.\n\nAn `ArrayHashMap` object have essentially the exact same methods from the `HashMap` struct.\nSo you can insert new values into the hashtable by using the `put()` method, and you can look (or get)\na value from the hashtable by using the `get()` method. But the `remove()` method is not available\nin this specific type of hashtable.\n\nIn order to delete values from the hashtable, you would use the same methods that you find in\nan `ArrayList` object, i.e. a dynamic array. I presented these methods at @sec-dynamic-array-remove,\nwhich are the `swapRemove()` and `orderedRemove()` methods. These methods have the same meaning here, or,\nthe same effect that they have in an `ArrayList` object.\n\nThis means that, with `swapRemove()` you remove the value from the hashtable, but you do not preserve\nthe order in which the values were inserted into the structure. While `orderedRemove()` is able\nto retain the order in which these values were inserted.\n\nBut instead of providing an index as input to `swapRemove()` or `orderedRemove()`, like I described\nat @sec-dynamic-array-remove, these methods here in an `ArrayHashMap` take a key as input, like\nthe `remove()` method from a `HashMap` object. If you want to provide an index as input, instead\nof a key, you should use the `swapRemoveAt()` and `orderedRemoveAt()` methods.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar hash_table = AutoArrayHashMap(u32, u16)\n    .init(allocator);\ndefer hash_table.deinit();\n```\n:::\n\n\n\n\n\n\n### The `StringHashMap` hashtable {#sec-string-hash-map}\n\nOne thing that you will notice in the other two types of hashtables that I have\npresented over the last sections, is that neither of them accepts a slice data type\nin their keys.\nWhat this means is that you cannot use a slice value to represent a key in\nthese types of hashtable.\n\nThe most obvious consequence of this, is that you cannot use strings as keys\nin these hashtables. But it is extremely common to use strings as keys\nin hashtables.\n\nTake this very simple Javascript code snippet as an example. We are creating\na simple hashtable object named `people`. Then, we add a new entry to this\nhashtable, which is identified by the string `'Pedro'`. This string is the\nkey in this case, while the object containing different personal information such as\nage, height and city, is the value to be stored in the hashtable.\n\n```js\nvar people = new Object();\npeople['Pedro'] = {\n    'age': 25,\n    'height': 1.67,\n    'city': 'Belo Horizonte'\n};\n```\n\nThis pattern of using strings as keys is very common in\nall sorts of situations. That is why the Zig Standard Library offers a\nspecific type of hashtable for this purpose, which is created through the `StringHashMap()` function.\nThis function creates a hashtable that uses strings as keys. The only input of this\nfunction is the data type of the values that will be stored into this hashtable.\n\nIn the example below, I'm creating a hashtable to store the ages of different people.\nEach key in this hashtable is represented by the name of each person, while the value stored in the\nhashtable is the age of this person identified by the key.\n\nThat is why I provide the `u8` data type (which is the data type used by the age values) as input to this `StringHashMap()` function.\nAs the result, it creates a hashtable that uses string values as keys, and, that stores\n`u8` values in it. Notice that an allocator object is provided at the `init()` method of the\nresulting object from the `StringHashMap()` function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var ages = std.StringHashMap(u8).init(allocator);\n    defer ages.deinit();\n\n    try ages.put(\"Pedro\", 25);\n    try ages.put(\"Matheus\", 21);\n    try ages.put(\"Abgail\", 42);\n\n    var it = ages.iterator();\n    while (it.next()) |kv| {\n        std.debug.print(\"Key: {s} | \", .{kv.key_ptr.*});\n        std.debug.print(\"Age: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n:::\n\n\n\n\n```\nKey: Pedro | Age: 25\nKey: Abgail | Age: 42\nKey: Matheus | Age: 21\n```\n\n\n### The `StringArrayHashMap` hashtable\n\nThe Zig Standard Library also provides a type of hashtable that mix the cons and pros of the\n`StringHashMap` and `ArrayHashMap` together. That is, a hashtable\nthat uses strings as keys, but also have the advantages from `ArrayHashMap`.\nIn other words, you can have a hashtable that is fast to iterate over,\nthat preserves insertion order, and also, that uses strings as keys.\n\nYou can create such type of hashtable by using the `StringArrayHashMap()` function.\nThis function accepts a data type as input, which is the data type of the values that are\ngoing to be stored inside this hashtable, in the same style as the function presented\nat @sec-string-hash-map.\n\nYou can insert new values into this hashtable by using the same `put()` method that\nwe have discussed at @sec-string-hash-map. And you can also get values from the hashtable\nby using the same `get()` method.\nLike its `ArrayHashMap` brother, to delete values from this specific type of hashtable,\nwe also use the `orderedRemove()` and `swapRemove()` methods, with the same effects that\nI have described at @sec-array-map.\n\nIf we take the code example that was exposed at @sec-string-hash-map, we can\nachieve the exact same result with `StringArrayHashMap()`:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar ages = std.StringArrayHashMap(u8).init(allocator);\n```\n:::\n\n\n\n\n\n\n\n## Linked lists\n\nThe Zig Standard Library provides an implementation for both singly and doubly linked lists.\nA linked list is a linear data structure that looks like a chain, or, a rope.\nThe main advantage of this data structure is that you normally have very fast\ninsertion and deletion operations. But, as a disadvantage, iterating through\nthis data structure is usually not so fast as iterating through an array.\n\nThe idea behind a linked list is to build a structure that consists of a sequence of nodes\nconnected to each other by pointers. This means that linked lists are usually not contiguous\nin memory, because each node might be anywhere in memory. They do not need to be close to\none another.\n\nAt @fig-linked-list we can see a diagram of a singly linked list. We begin at the first node\n(which is usually called \"the head of the linked list\"). Then, from this\nfirst node we uncover the remaining nodes in the structure, by following the locations pointed\nby the pointers found in each node.\n\nEach node has two things in it. It has the value that is stored in the current node\n, and also, a pointer. This pointer points to the next node in the list. If this pointer\nis null, then, it means that we have reached the end of our linked list.\n\n![A diagram of a singly linked list.](./../Figures/linked-list.png){#fig-linked-list}\n\n\nAt @fig-linked-list2 we can see a diagram of a doubly linked list. The only thing that really\nchanges now is that every node in the linked list has both a pointer to the previous node,\nand, a pointer to the next node. So every node in a doubly linked list has two pointers in it. These are\nusually called the `prev` (for \"previous\") and the `next` (for \"next\") pointers of the node.\n\nIn the singly linked list example, we had only one single pointer in each node, and this singular\npointer was always pointing to the next node in the sequence. This means that singly linked lists\nnormally have only the `next` pointer in them.\n\n![A diagram of a doubly linked list.](./../Figures/doubly-linked-list.png){#fig-linked-list2}\n\n\nLinked lists are available in Zig through the functions `SinglyLinkedList()` and\n`DoublyLinkedList()`, for \"singly linked lists\" and \"doubly linked lists\", respectively. These functions are\nactually generic functions, which we are going to talk more about at @sec-generic-fun.\n\nFor now, just understand that, in order to create a linked list object,\nwe begin by providing a data type to these functions. This data type defines\nthe type of data that each node in this linked list will store. In the example below,\nwe are creating a singly linked list of `u32` values.\nSo each node in this linked list will store a `u32` value.\n\nBoth the `SinglyLinkedList()` and `DoublyLinkedList()` functions returns a type,\ni.e. a struct definition, as output. Therefore, the object `Lu32` is actually\na struct definition. It defines the type \"singly linked list of `u32` values\".\n\nNow that we have the definition of the struct, we need to instantiate a `Lu32` object.\nWe normally instantiate struct objects in Zig by using an `init()` method.\nBut in this case, we are instantiating the struct directly, by using an empty\n`struct` literal, in the expression `Lu32{}`.\n\nIn this example, we first create multiple node objects, and after we create them,\nwe start to insert and connect these nodes to build the linked list, using the\n`prepend()` and `insertAfter()` methods. Notice that the `prepend()` method\nis a method from the linked list object, while the `insertAfter()` is a method\npresent in the node objects.\n\nIn essence, the `prepend()` method inserts a node at the beginning of the linked\nlist. In other words, the node that you provide to this method, becomes the new\n\"head node\" of the linked list. It becomes the first node in the list (see @fig-linked-list).\n\nOn the other side, the `insertAfter()` method is used to basically connect two nodes together.\nWhen you provide a node to this method, it creates a pointer to this input node,\nand stores this pointer in the `next` attribute of the current node, from which the method was called from.\n\nBecause doubly linked lists have both a `next` and a `prev` attributes in each node\n(as described at @fig-linked-list2), a node object created from\na `DoublyLinkedList` object have both an `insertBefore()` (for `prev`)\nand an `insertAfter()` (for `next`) methods available.\n\nThus, if we have used a doubly linked list, we can use the `insertBefore()` method\nto store the pointer to the input node in the `prev` attribute. This would put the input\nnode as the \"previous node\", or, the node before the current node. In contrast, the `insertAfter()` method\nputs the pointer created to the input node in the `next` attribute of the current node,\nand as result, the input node becomes the \"next node\" of the current node.\n\nSince we are using a singly linked list in this example, we have only the `insertAfter()` method\navailable in the node objects that we create from our `Lu32` type.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SinglyLinkedList = std.SinglyLinkedList;\nconst Lu32 = SinglyLinkedList(u32);\n\npub fn main() !void {\n    var list = Lu32{};\n    var one = Lu32.Node{ .data = 1 };\n    var two = Lu32.Node{ .data = 2 };\n    var three = Lu32.Node{ .data = 3 };\n    var four = Lu32.Node{ .data = 4 };\n    var five = Lu32.Node{ .data = 5 };\n\n    list.prepend(&two); // {2}\n    two.insertAfter(&five); // {2, 5}\n    list.prepend(&one); // {1, 2, 5}\n    two.insertAfter(&three); // {1, 2, 3, 5}\n    three.insertAfter(&four); // {1, 2, 3, 4, 5}\n}\n```\n:::\n\n\n\n\n\nThere are other methods available from the linked list object, depending if this object is\na singly linked list or a doubly linked list, that might be very useful for you. You can find a\nsummary of them in the bullet points below:\n\n- `remove()` to remove a specific node from the linked list.\n- if singly linked list, `len()` to count how many nodes there is in the linked list.\n- if doubly linked list, checkout the `len` attribute to see how many nodes there is in the linked list.\n- if singly linked list, `popFirst()` to remove the first node (i.e. the \"head\") from the linked list.\n- if doubly linked list, `pop()` and `popFirst()` to remove the last and first nodes from the linked list, respectively.\n- if doubly linked list, `append()` to add a new node to end of the linked list (i.e. inverse of `prepend()`).\n\n\n\n## Multi array structure\n\nZig introduces a new data structure called `MultiArrayList()`. It is a different version of the dynamic array\nthat we have introduced at @sec-dynamic-array. The difference between this structure and the `ArrayList()`\nthat we know from @sec-dynamic-array, is that `MultiArrayList()` creates a separate dynamic array\nfor each field of the struct that you provide as input.\n\nConsider the following code example. We create a new custom struct called `Person`. This\nstruct contains three different data members, or, three different fields. As consequence,\nwhen we provide this `Person` data type as input to `MultiArrayList()`, this\ncreates a \"struct of three different arrays\" called `PersonArray`. In other words,\nthis `PersonArray` is a struct that contains three internal dynamic arrays in it.\nOne array for each field found in the `Person` struct definition.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Person = struct {\n    name: []const u8,\n    age: u8,\n    height: f32,\n};\nconst PersonArray = std.MultiArrayList(Person);\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var people = PersonArray{};\n    defer people.deinit(allocator);\n\n    try people.append(allocator, .{\n        .name = \"Auguste\", .age = 15, .height = 1.54\n    });\n    try people.append(allocator, .{\n        .name = \"Elena\", .age = 26, .height = 1.65\n    });\n    try people.append(allocator, .{\n        .name = \"Michael\", .age = 64, .height = 1.87\n    });\n}\n```\n:::\n\n\n\n\nIn other words, instead of creating an array of \"persons\", the `MultiArrayList()` function\ncreates a \"struct of arrays\". Each data member of this struct is a different array that stores\nthe values of a specific field from the `Person` values that were added (or, appended) to this \"struct of arrays\".\nOne important detail is that each of these separate internal arrays stored inside `PersonArray`\nare dynamic arrays. This means that these arrays can grow in capacity automatically as needed, to accomodate\nmore values.\n\nThe @fig-multi-array exposed below presents a diagram that describes the `PersonArray` struct\nthat we have created in the previous code example. Notice that the values of the data members\npresent in each of the three `Person` values that we have appended into the `PersonArray` object\n, are scattered across three different internal arrays of the `PersonArray` object.\n\n![A diagram of the `PersonArray` struct.](./../Figures/multi-array.png){#fig-multi-array}\n\nYou can easily access each of these arrays separately, and iterate over the values of each array.\nFor that, you will need to call the `items()` method from the `PersonArray` object, and provide as input\nto this method, the name of the field that you want to iterate over.\nIf you want to iterate through the `.age` array for example, then, you need to call `items(.age)` from\nthe `PersonArray` object, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (people.items(.age)) |*age| {\n    try stdout.print(\"Age: {d}\\n\", .{age.*});\n}\n```\n:::\n\n\n\n\n```\nAge: 15\nAge: 26\nAge: 64\n```\n\n\nIn the above example, we are iterating over the values of the `.age` array, or,\nthe internal array of the `PersonArray` object that contains the values of the `age`\ndata member from the `Person` values that were added to the multi array struct.\n\nIn this example we are calling the `items()` method directly from the `PersonArray`\nobject. However, it is recommended on most situations to call this `items()` method\nfrom a \"slice object\", which you can create from the `slice()` method.\nThe reason for this is that calling `items()` multiple times have better performance\nif you use a slice object.\n\nTherefore, if you are planning to access only one of the\ninternal arrays from your \"multi array struct\", it is fine to call `items()` directly\nfrom the multi array object. But if you need to access many of the internal arrays\nfrom your \"multi array struct\", then, you will likely need to call `items()` more\nthan once, and, in such circumstance, is better to call `items()` through a slice object.\nThe example below demonstrates the use of such object:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar slice = people.slice();\nfor (slice.items(.age)) |*age| {\n    age.* += 10;\n}\nfor (slice.items(.name), slice.items(.age)) |*n,*a| {\n    try stdout.print(\n        \"Name: {s}, Age: {d}\\n\", .{n.*, a.*}\n    );\n}\n```\n:::\n\n\n\n\n```\nName: Auguste, Age: 25\nName: Elena, Age: 36\nName: Michael, Age: 74\n```\n\n\n## Conclusion\n\nThere are many other data structures that I haven't presented here.\nBut you can check them out at the official Zig Standard Library documentation page.\nActually, when you get into the [homepage of the documentation](https://ziglang.org/documentation/master/std/#)[^home], the first thing\nthat appears to you in this page, is a list of types and data structures that\nare available in the Zig Standard Library.\nThere are some very specific data structures in this list, like a\n[`BoundedArray` struct](https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray)[^bounded]\n, but there is also some more general structures, such as a\n[`PriorityQueue` struct](https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue)[^priority].\n\n\n[^home]: <https://ziglang.org/documentation/master/std/#>\n[^priority]: <https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue>.\n[^bounded]: <https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray>\n\n\n\n\n\n\n",
-    "supporting": [
-      "09-data-structures_files"
-    ],
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/09-error-handling/execute-results/html.json b/_freeze/Chapters/09-error-handling/execute-results/html.json
index a655e2a5..39ca6f04 100644
--- a/_freeze/Chapters/09-error-handling/execute-results/html.json
+++ b/_freeze/Chapters/09-error-handling/execute-results/html.json
@@ -2,7 +2,7 @@
   "hash": "0e6b825195db1ba992b740206fa34ec0",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Error handling and unions {#sec-error-handling}\n\nIn this chapter, I want to discuss how error handling is done in Zig.\nWe already briefly learned about one of the available strategies to handle errors in Zig,\nwhich is the `try` keyword presented at @sec-main-file. But we still haven't learned about\nthe other methods, such as the `catch` keyword.\nI also want to discuss in this chapter how union types are created in Zig.\n\n## Learning more about errors in Zig\n\nBefore we get into how error handling is done, we need to learn more about what errors are in Zig.\nAn error is actually a value in Zig [@zigoverview]. In other words, when an error occurs inside your Zig program,\nit means that somewhere in your Zig codebase, an error value is being generated.\nAn error value is similar to any integer value that you create in your Zig code.\nYou can take an error value and pass it as input to a function,\nand you can also cast (or coerce) it into a different type of an error value.\n\nThis have some similarities with exceptions in C++ and Python.\nBecause in C++ and Python, when an exception happens inside a `try` block,\nyou can use a `catch` block (in C++) or an `except` block (in Python)\nto capture the exception produced in the `try` block,\nand pass it to functions as an input.\n\nHowever, error values in Zig are treated very differently than exceptions.\nFirst, you cannot ignore error values in your Zig code. Meaning that, if an error\nvalue appears somewhere in your source code, this error value must be explicitly handled in some way.\nThis also means that you cannot discard error values by assigning them to an underscore,\nas you could do with normal values and objects.\n\nTake the source code below as an example. Here we are trying to open a file that does not exist\nin my computer, and as a result, an obvious error value of `FileNotFound` is returned from the `openFile()`\nfunction. But because I'm assigning the result of this function to an underscore, I end up\ntrying to discard an error value.\n\nThe `zig` compiler detects this mistake, and raises a compile\nerror telling me that I'm trying to discard an error value.\nIt also adds a note message that suggests the use of `try`,\n`catch` or an if statement to explicitly handle this error value\nThis note is reinforcing that every possible error value must be explicitly handled in Zig.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst dir = std.fs.cwd();\n_ = dir.openFile(\"doesnt_exist.txt\", .{});\n```\n:::\n\n\n\n\n```\nt.zig:8:17: error: error set is discarded\nt.zig:8:17: note: consider using 'try', 'catch', or 'if'\n```\n\n\n### Returning errors from functions\n\nAs we described at @sec-main-file, when we have a function that might return an error\nvalue, this function normally includes an exclamation mark (`!`) in its return type\nannotation. The presence of this exclamation mark indicates that this function might\nreturn an error value as result, and, the `zig` compiler forces you to always handle explicitly\nthe case of this function returning an error value.\n\nTake a look at the `print_name()` function below. This function might return an error in the `stdout.print()` function call,\nand, as a consequence, its return type (`!void`) includes an exclamation mark in it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_name() !void {\n    const stdout = std.getStdOut().writer();\n    try stdout.print(\"My name is Pedro!\", .{});\n}\n```\n:::\n\n\n\n\nIn the example above, we are using the exclamation mark to tell the `zig` compiler\nthat this function might return some error. But which error exactly is returned from\nthis function? For now, we are not specifying a specific error value. We only\nknown for now that some error value (whatever it is) might be returned.\n\nBut in fact, you can (if you want to) specify clearly which exact error values\nmight be returned from this function. There are lot of examples of\nthis in the Zig Standard Library. Take this `fill()` function from\nthe `http.Client` module as an example. This function returns\neither a error value of type `ReadError`, or `void`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn fill(conn: *Connection) ReadError!void {\n    // The body of this function ...\n}\n```\n:::\n\n\n\n\nThis idea of specifying the exact error values that you expect to be returned\nfrom the function is interesting. Because they automatically become some sort of documentation\nof your function, and also, it allows the `zig` compiler to perform some extra checks over\nyour code. Because it can check if there is any other type of error value\nthat is being generated inside your function, and, that it is not being accounted\nfor in this return type annotation.\n\nAnyway, you can list the types of errors that can be returned from the function\nby listing them on the left side of the exclamation mark. While the valid values\nstay on the right side of the exclamation mark. So the syntax format become:\n\n```\n<error-value>!<valid-value>\n```\n\n\n### Error sets\n\nBut what about when we have a single function that might return different types of errors?\nWhen you have such a function, you can list\nall of these different types of errors that can be returned from this function,\nthrough a structure in Zig that we call of an *error set*.\n\nAn error set is a special case of an union type. It is an union that contains error values in it.\nNot all programming languages have a notion of an \"union object\".\nBut in summary, an union is just a set of data types.\nUnions are used to allow an object to have multiple data types.\nFor example, a union of `x`, `y` and `z`, means that\nan object can be either of type `x`, or type `y` or type `z`.\n\nWe are going to talk in more depth about unions at @sec-unions.\nBut you can write an error set by writing the keyword `error` before\na pair of curly braces, then you list the error values that can be\nreturned from the function inside this pair of curly braces.\n\nTake the `resolvePath()` function below as an example, which comes from the\n`introspect.zig` module of the Zig Standard Library. We can see in its return type annotation, that this\nfunction return either: 1) a valid slice of `u8` values (`[]u8`); or, 2) one of the three different\ntypes of error values listed inside the error set (`OutOfMemory`, `Unexpected`, etc.).\nThis is an usage example of an error set.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn resolvePath(\n    ally: mem.Allocator,\n    p: []const u8,\n) error{\n    OutOfMemory,\n    CurrentWorkingDirectoryUnlinked,\n    Unexpected,\n}![]u8 {\n    // The body of the function ...\n}\n```\n:::\n\n\n\n\n\nThis is a valid way of annotating the return value of a Zig function. But, if you navigate through\nthe modules that composes the Zig Standard Library, you will notice that, for the majority of cases,\nthe programmers prefer to give a descriptive name to this error set, and then, use this name (or this \"label\")\nof the error set in the return type annotation, instead of using the error set directly.\n\nWe can see that in the `ReadError` error set that we showed earlier in the `fill()` function,\nwhich is defined in the `http.Client` module.\nSo yes, I presented the `ReadError` as if it was just a standard and single error value, but in fact,\nit is an error set defined in the `http.Client` module, and therefore, it actually represents\na set of different error values that might happen inside the `fill()` function.\n\n\nTake a look at the `ReadError` definition reproduced below. Notice that we are grouping all of these\ndifferent error values into a single object, and then, we use this object into the return type annotation of the function.\nLike the `fill()` function that we showed earlier, or, the `readvDirect()` function from the same module,\nwhich is reproduced below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const ReadError = error{\n    TlsFailure,\n    TlsAlert,\n    ConnectionTimedOut,\n    ConnectionResetByPeer,\n    UnexpectedReadFailure,\n    EndOfStream,\n};\n// Some lines of code\npub fn readvDirect(\n        conn: *Connection,\n        buffers: []std.posix.iovec\n    ) ReadError!usize {\n    // The body of the function ...\n}\n```\n:::\n\n\n\n\nSo, an error set is just a convenient way of grouping a set of\npossible error values into a single object, or a single type of an error value.\n\n\n### Casting error values\n\nLet's suppose you have two different error sets, named `A` and `B`.\nIf error set `A` is a superset of error set `B`, then, you can cast (or coerce)\nerror values from `B` into error values of `A`.\n\nError sets are just a set of error values. So, if the error set `A`\ncontains all error values from the error set `B`, then `A`\nbecomes a superset of `B`. You could also say\nthat the error set `B` is a subset of error set `A`.\n\nThe example below demonstrates this idea. Because `A` contains all\nvalues from `B`, `A` is a superset of `B`.\nIn math notation, we would say that $A \\supset B$.\nAs a consequence, we can give an error value from `B` as input to the `cast()`\nfunction, and, implicitly cast this input into the same error value, but from the `A` set.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst A = error{\n    ConnectionTimeoutError,\n    DatabaseNotFound,\n    OutOfMemory,\n    InvalidToken,\n};\nconst B = error {\n    OutOfMemory,\n};\n\nfn cast(err: B) A {\n    return err;\n}\n\ntest \"coerce error value\" {\n    const error_value = cast(B.OutOfMemory);\n    try std.testing.expect(\n        error_value == A.OutOfMemory\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file10459ffd0e21.test.coerce error value...OKA\n  All 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n## How to handle errors\n\nNow that we learned more about what errors are in Zig,\nlet's discuss the available strategies to handle these errors,\nwhich are:\n\n- `try` keyword;\n- `catch` keyword;\n- an if statement;\n- `errdefer` keyword;\n\n\n\n### What `try` means?\n\nAs I described over the previous sections, when we say that an expression might\nreturn an error, we are basically referring to an expression that have\na return type in the format `!T`.\nThe `!` indicates that this expression returns either an error value, or a value of type `T`.\n\nAt @sec-main-file, I presented the `try` keyword and where to use it.\nBut I did not talked about what exactly this keyword does to your code,\nor, in other words, I have not explained yet what `try` means in your code.\n\nIn essence, when you use the `try` keyword in an expression, you are telling\nthe `zig` compiler the following: \"Hey! Execute this expression for me,\nand, if this expression return an error, please, return this error for me\nand stop the execution of my program. But if this expression return a valid\nvalue, then, return this value, and move on\".\n\nIn other words, the `try` keyword is essentially, a strategy to enter in panic mode, and stop\nthe execution of your program in case an error occurs.\nWith the `try` keyword, you are telling the `zig` compiler, that stopping the execution\nof your program is the most reasonable strategy to take if an error occurs\nin that particular expression.\n\n### The `catch` keyword\n\nOk, now that we understand properly what `try` means, let's discuss `catch` now.\nOne important detail here, is that you can use `try` or `catch` to handle your errors,\nbut you **cannot use `try` and `catch` together**. In other words, `try` and `catch`\nare different and completely separate strategies in the Zig language.\n\nThis is uncommon, and different than what happens in other languages. Most\nprogramming languages that adopts the *try catch* pattern (such as C++, R, Python, Javascript, etc.), normally use\nthese two keywords together to form the complete logic to\nproperly handle the errors.\nAnyway, Zig tries a different approach in the *try catch* pattern.\n\nSo, we learned already about what `try` means, and we also known that both\n`try` and `catch` should be used alone, separate from each other. But\nwhat exactly `catch` do in Zig? With `catch`, we can construct a block of\nlogic to handle the error value, in case it happens in the current expression.\n\nLook at the code example below. Once again, we go back to the previous\nexample where we were trying to open a file that doesn't exist in my computer,\nbut this time, I use `catch` to actually implement a logic to handle the error, instead of\njust stopping the execution right away.\n\nMore specifically, in this example, I'm using a logger object to record some logs into\nthe system, before I return the error, and stop the execution of the program. For example,\nthis could be some part of the codebase of a complex system that I do not have full control over,\nand I want to record these logs before the program crashes, so that I can debug it later\n(e.g. maybe I cannot compile the full program, and properly debug it with a debugger. So, these logs might\nbe a valid strategy to surpass this barrier).\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst dir = std.fs.cwd();\nconst file = dir.openFile(\n    \"doesnt_exist.txt\", .{}\n) catch |err| {\n    logger.record_context();\n    logger.log_error(err);\n    return err;\n};\n```\n:::\n\n\n\n\n\nTherefore, we use `catch` to create a block of expressions that will handle the error.\nI can return the error value from this block of expressions, like I did in the above example,\nwhich, will make the program enter in panic mode, and, stop the execution.\nBut I could also, return a valid value from this block of code, which would\nbe stored in the `file` object.\n\nNotice that, instead of writing the keyword before the expression that might return the error,\nlike we do with `try`, we write `catch` after the expression. We can open the pair of pipes (`|`),\nwhich captures the error value returned by the expression, and makes\nthis error value available in the scope of the `catch` block as the object named `err`.\nIn other words, because I wrote `|err|` in the code, I can access the error value\nreturned by the expression, by using the `err` object.\n\nAlthough this being the most common use of `catch`, you can also use this keyword\nto handle the error in a \"default value\" style. That is, if the expression returns\nan error, we use the default value instead. Otherwise, we use the valid value returned\nby the expression.\n\nThe Zig official language reference, provides a great example of this \"default value\"\nstrategy with `catch`. This example is reproduced below. Notice that we are trying to parse\nsome unsigned integer from a string object named `str`. In other words, this function\nis trying to transform an object of type `[]const u8` (i.e. an array of characters, a string, etc.)\ninto an object of type `u64`.\n\nBut this parsing process done by the function `parseU64()` may fail, resulting in a runtime error.\nThe `catch` keyword used in this example provides an alternative value (13) to be used in case\nthis `parseU64()` function raises an error. So, the expression below essentially means:\n\"Hey! Please, parse this string into a `u64` for me, and store the results into the\nobject `number`. But, if an error occurs, then, use the value `13` instead\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number = parseU64(str, 10) catch 13;\n```\n:::\n\n\n\n\nSo, at the end of this process, the object `number` will contain either a `u64` integer\nthat was parsed successfully from the input string `str`, or, if an error occurs in the\nparsing process, it will contain the `u64` value `13` that was provided by the `catch`\nkeyword as the \"default\", or, the \"alternative\" value.\n\n\n\n### Using if statements\n\nNow, you can also use if statements to handle errors in your Zig code.\nIn the example below, I'm reproducing the previous example, where\nwe try to parse an integer value from an input string with a function\nnamed `parseU64()`.\n\nWe execute the expression inside the \"if\". If this expression returns an\nerror value, the \"if branch\" (or, the \"true branch\") of the if statement is not executed.\nBut if this expression returns a valid value instead, then, this value is unwrapped\ninto the `number` object.\n\nThis means that, if the `parseU64()` expression returns a valid value, this value becomes available\ninside the scope of this \"if branch\" (i.e. the \"true branch\") through the object that we listed inside the pair\nof pipe character (`|`), which is the object `number`.\n\nIf an error occurs, we can use an \"else branch\" (or the \"false branch\") of the if statement\nto handle the error. In the example below, we are using the `else` in the if statement\nto unwrap the error value (that was returned by `parseU64()`) into the `err` object,\nand handle the error.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (parseU64(str, 10)) |number| {\n    // do something with `number` here\n} else |err| {\n    // handle the error value.\n}\n```\n:::\n\n\n\n\nNow, if the expression that you are executing returns different types of error values,\nand you want to take a different action in each of these types of error values, the\n`try` and `catch` keywords, and the if statement strategy, becomes limited.\n\nFor this type of situation, the official documentation of the language suggests\nthe use of a switch statement together with an if statement [@zigdocs].\nThe basic idea is, to use the if statement to execute the expression, and\nuse the \"else branch\" to pass the error value to a switch statement, where\nyou define a different action for each type of error value that might be\nreturned by the expression executed in the if statement.\n\nThe example below demonstrates this idea. We first try to add (or register) a set of\ntasks to a queue. If this \"registration process\" occurs well, we then try\nto distribute these tasks across the workers of our system. But\nif this \"registration process\" returns an error value, we then use a switch\nstatement in the \"else branch\" to handle each possible error value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (add_tasks_to_queue(&queue, tasks)) |_| {\n    distribute_tasks(&queue);\n} else |err| switch (err) {\n    error.InvalidTaskName => {\n        // do something\n    },\n    error.TimeoutTooBig => {\n        // do something\n    },\n    error.QueueNotFound => {\n        // do something\n    },\n    // and all the other error options ...\n}\n```\n:::\n\n\n\n\n\n### The `errdefer` keyword {#sec-errdefer2}\n\nA common pattern in C programs in general, is to clean resources when an error occurs during\nthe execution of the program. In other words, one common way to handle errors, is to perform\n\"cleanup actions\" before we exit our program. This guarantees that a runtime error does not make\nour program to leak resources of the system.\n\n\nThe `errdefer` keyword is a tool to perform such \"cleanup actions\" in hostile situations.\nThis keyword is commonly used to clean (or to free) allocated resources, before the execution of our program\nget's stopped because of an error value being generated.\n\nThe basic idea is to provide an expression to the `errdefer` keyword. Then,\n`errdefer` executes this expression if, and only if, an error occurs\nduring the execution of the current scope.\nIn the example below, we are using an allocator object (that we have presented at @sec-allocators)\nto create a new `User` object. If we are successful in creating and registering this new user,\nthis `create_user()` function will return this new `User` object as its return value.\n\nHowever, if for some reason, an error value is generated by some expression\nthat is after the `errdefer` line, for example, in the `db.add(user)` expression,\nthe expression registered by `errdefer` get's executed before the error value is returned\nfrom the function, and before the program enters in panic mode and stops the\ncurrent execution.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn create_user(db: Database, allocator: Allocator) !User {\n    const user = try allocator.create(User);\n    errdefer allocator.destroy(user);\n\n    // Register new user in the Database.\n    _ = try db.register_user(user);\n    return user;\n}\n```\n:::\n\n\n\n\nBy using `errdefer` to destroy the `user` object that we have just created,\nwe guarantee that the memory allocated for this `user` object\nget's freed, before the execution of the program stops.\nBecause if the expression `try db.add(user)` returns an error value,\nthe execution of our program stops, and we lose all references and control over the memory\nthat we have allocated for the `user` object.\nAs a result, if we do not free the memory associated with the `user` object before the program stops,\nwe cannot free this memory anymore. We simply lose our chance to do the right thing.\nThat is why `errdefer` is essential in this situation.\n\nJust to state clearly the differences between `defer` and `errdefer`\n(which I described at @sec-defer and @sec-errdefer1), it might be worth\nto discuss the subject a bit further. You might still have the question\n\"why use `errdefer` if we can use `defer` instead?\" in your mind.\n\nAlthough being similar, the key difference between `errdefer` and `defer` keyword\nis when the provided expression get's executed.\nThe `defer` keyword always execute the provided expression at the end of the\ncurrent scope, no matter how your code exits this scope.\nIn contrast, `errdefer` executes the provided expression only when an error occurs in the\ncurrent scope.\n\nThis becomes important if a resource that you allocate in the\ncurrent scope get's freed later in your code, in a different scope.\nThe `create_user()` functions is an example of this. If you think\nclosely about this function, you will notice that this function returns\nthe `user` object as the result.\n\nIn other words, the allocated memory for the `user` object does not get\nfreed inside the `create_user()` function, if it returns successfully.\nSo, if an error does not occur inside this function, the `user` object\nis returned from the function, and probably, the code that runs after\nthis `create_user()` function will be responsible for freeing\nthe memory of the `user` object.\n\nBut what if an error occurs inside the `create_user()` function? What happens then?\nThis would mean that the execution of your code would stop in this `create_user()`\nfunction, and, as a consequence, the code that runs after this `create_user()`\nfunction would simply not run, and, as a result, the memory of the `user` object\nwould not be freed before your program stops.\n\nThis is the perfect scenario for `errdefer`. We use this keyword to guarantee\nthat our program will free the allocated memory for the `user` object,\neven if an error occurs inside the `create_user()` function.\n\nIf you allocate and free some memory for an object inside the same scope, then,\njust use `defer` and be happy, i.e. `errdefer` have no use for you in such situation.\nBut if you allocate some memory in a scope A, but you only free this memory\nlater, in a scope B for example, then, `errdefer` becomes useful to avoid leaking memory\nin sketchy situations.\n\n\n\n## Union type in Zig {#sec-unions}\n\nAn union type defines a set of types that an object can be. It is like a list of\noptions. Each option is a type that an object can assume. Therefore, unions in Zig\nhave the same meaning, or, the same role as unions in C. They are used for the same purpose.\nYou could also say that unions in Zig produces a similar effect to\n[using `typing.Union` in Python](https://docs.python.org/3/library/typing.html#typing.Union)[^pyunion].\n\n[^pyunion]: <https://docs.python.org/3/library/typing.html#typing.Union>\n\nFor example, you might be creating an API that sends data to a data lake, hosted\nin some private cloud infrastructure. Suppose you have created different structs in your codebase,\nto store the necessary information that you need, in order to connect to the services of\neach mainstream data lake service (Amazon S3, Azure Blob, etc.).\n\nNow, suppose you also have a function named `send_event()` that receives an event as input,\nand, a target data lake, and it sends the input event to the data lake specified in the\ntarget data lake argument. But this target data lake could be any of the three mainstream data lakes\nservices (Amazon S3, Azure Blob, etc.). Here is where an union can help you.\n\nThe union `LakeTarget` defined below allows the `lake_target` argument of `send_event()`\nto be either an object of type `AzureBlob`, or type `AmazonS3`, or type `GoogleGCP`.\nThis union allows the `send_event()` function to receive an object of any of these three types\nas input in the `lake_target` argument.\n\nRemember that each of these three types (`AmazonS3`, `GoogleGCP` and `AzureBlob`)\nare separate structs that we have defined in our source code. So, at first glance,\nthey are separate data types in our source code. But is the `union` keyword that\nunifies them into a single data type called `LakeTarget`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst LakeTarget = union {\n    azure: AzureBlob,\n    amazon: AmazonS3,\n    google: GoogleGCP,\n};\n\nfn send_event(\n    event: Event,\n    lake_target: LakeTarget\n) bool {\n    // body of the function ...\n}\n```\n:::\n\n\n\n\nAn union definition is composed by a list of data members. Each data member is of a specific data type.\nIn the example above, the `LakeTarget` union have three data members (`azure`, `amazon`, `google`).\nWhen you instantiate an object that uses an union type, you can only use one of its data members\nin this instantiation.\n\nYou could also interpret this as: only one data member of an union type can be activated at a time, the other data\nmembers remain deactivated and unaccessible. For example, if you create a `LakeTarget` object that uses\nthe `azure` data member, you can no longer use or access the data members `google` or `amazon`.\nIt is like if these other data members didn't exist at all in the `LakeTarget` type.\n\nYou can see this logic in the example below. Notice that, we first instantiate the union\nobject using the `azure` data member. As a result, this `target` object contains only\nthe `azure` data member inside of it. Only this data member is active in this object.\nThat is why the last line in this code example is invalid. Because we are trying to instantiate the data member\n`google`, which is currently inactive for this `target` object, and as a result, the program\nenters in panic mode warning us about this mistake through a loud error message.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar target = LakeTarget {\n    .azure = AzureBlob.init()\n};\n// Only the `azure` data member exist inside\n// the `target` object, and, as a result, this\n// line below is invalid:\ntarget.google = GoogleGCP.init();\n```\n:::\n\n\n\n\n```\nthread 2177312 panic: access of union field 'google' while\n    field 'azure' is active:\n    target.google = GoogleGCP.init();\n          ^\n```\n\nSo, when you instantiate an union object, you must choose one of the data types (or, one of the data members)\nlisted in the union type. In the example above, I choose to use the `azure` data member, and, as a result,\nall other data members were automatically deactivated,\nand you can no longer use them after you instantiate the object.\n\nYou can activate another data member by completely redefining the entire enum object.\nIn the example below, I initially use the `azure` data member. But then, I redefine the\n`target` object to use a new `LakeTarget` object, which uses the `google` data member.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar target = LakeTarget {\n    .azure = AzureBlob.init()\n};\ntarget = LakeTarget {\n    .google = GoogleGCP.init()\n};\n```\n:::\n\n\n\n\nA curious fact about union types, is that, at first, you cannot use them in switch statements (which were presented at @sec-switch).\nIn other words, if you have an object of type `LakeTarget` for example, you cannot give this object\nas input to a switch statement.\n\nBut what if you really need to do so? What if you actually need to\nprovide an \"union object\" to a switch statement? The answer to this question relies on another special type in Zig,\nwhich are the *tagged unions*. To create a tagged union, all you have to do is to add\nan enum type into your union declaration.\n\nAs an example of a tagged union in Zig, take the `Registry` type exposed\nbelow. This type comes from the\n[`grammar.zig` module](https://github.com/ziglang/zig/blob/30b4a87db711c368853b3eff8e214ab681810ef9/tools/spirv/grammar.zig)[^grammar]\nfrom the Zig repository. This union type lists different types of registries.\nBut notice this time, the use of `(enum)` after the `union` keyword. This is what makes\nthis union type a tagged union. By being a tagged union, an object of this `Registry` type\ncan be used as input in a switch statement. This is all you have to do. Just add `(enum)`\nto your `union` declaration, and you can use it in switch statements.\n\n[^grammar]: <https://github.com/ziglang/zig/blob/30b4a87db711c368853b3eff8e214ab681810ef9/tools/spirv/grammar.zig>.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const Registry = union(enum) {\n    core: CoreRegistry,\n    extension: ExtensionRegistry,\n};\n```\n:::\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Error handling and unions {#sec-error-handling}\n\nIn this chapter, I want to discuss how error handling is done in Zig.\nWe already briefly learned about one of the available strategies to handle errors in Zig,\nwhich is the `try` keyword presented at @sec-main-file. But we still haven't learned about\nthe other methods, such as the `catch` keyword.\nI also want to discuss in this chapter how union types are created in Zig.\n\n## Learning more about errors in Zig\n\nBefore we get into how error handling is done, we need to learn more about what errors are in Zig.\nAn error is actually a value in Zig [@zigoverview]. In other words, when an error occurs inside your Zig program,\nit means that somewhere in your Zig codebase, an error value is being generated.\nAn error value is similar to any integer value that you create in your Zig code.\nYou can take an error value and pass it as input to a function,\nand you can also cast (or coerce) it into a different type of an error value.\n\nThis have some similarities with exceptions in C++ and Python.\nBecause in C++ and Python, when an exception happens inside a `try` block,\nyou can use a `catch` block (in C++) or an `except` block (in Python)\nto capture the exception produced in the `try` block,\nand pass it to functions as an input.\n\nHowever, error values in Zig are treated very differently than exceptions.\nFirst, you cannot ignore error values in your Zig code. Meaning that, if an error\nvalue appears somewhere in your source code, this error value must be explicitly handled in some way.\nThis also means that you cannot discard error values by assigning them to an underscore,\nas you could do with normal values and objects.\n\nTake the source code below as an example. Here we are trying to open a file that does not exist\nin my computer, and as a result, an obvious error value of `FileNotFound` is returned from the `openFile()`\nfunction. But because I'm assigning the result of this function to an underscore, I end up\ntrying to discard an error value.\n\nThe `zig` compiler detects this mistake, and raises a compile\nerror telling me that I'm trying to discard an error value.\nIt also adds a note message that suggests the use of `try`,\n`catch` or an if statement to explicitly handle this error value\nThis note is reinforcing that every possible error value must be explicitly handled in Zig.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst dir = std.fs.cwd();\n_ = dir.openFile(\"doesnt_exist.txt\", .{});\n```\n:::\n\n\n\n\n```\nt.zig:8:17: error: error set is discarded\nt.zig:8:17: note: consider using 'try', 'catch', or 'if'\n```\n\n\n### Returning errors from functions\n\nAs we described at @sec-main-file, when we have a function that might return an error\nvalue, this function normally includes an exclamation mark (`!`) in its return type\nannotation. The presence of this exclamation mark indicates that this function might\nreturn an error value as result, and, the `zig` compiler forces you to always handle explicitly\nthe case of this function returning an error value.\n\nTake a look at the `print_name()` function below. This function might return an error in the `stdout.print()` function call,\nand, as a consequence, its return type (`!void`) includes an exclamation mark in it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_name() !void {\n    const stdout = std.getStdOut().writer();\n    try stdout.print(\"My name is Pedro!\", .{});\n}\n```\n:::\n\n\n\n\nIn the example above, we are using the exclamation mark to tell the `zig` compiler\nthat this function might return some error. But which error exactly is returned from\nthis function? For now, we are not specifying a specific error value. We only\nknown for now that some error value (whatever it is) might be returned.\n\nBut in fact, you can (if you want to) specify clearly which exact error values\nmight be returned from this function. There are lot of examples of\nthis in the Zig Standard Library. Take this `fill()` function from\nthe `http.Client` module as an example. This function returns\neither a error value of type `ReadError`, or `void`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn fill(conn: *Connection) ReadError!void {\n    // The body of this function ...\n}\n```\n:::\n\n\n\n\nThis idea of specifying the exact error values that you expect to be returned\nfrom the function is interesting. Because they automatically become some sort of documentation\nof your function, and also, it allows the `zig` compiler to perform some extra checks over\nyour code. Because it can check if there is any other type of error value\nthat is being generated inside your function, and, that it is not being accounted\nfor in this return type annotation.\n\nAnyway, you can list the types of errors that can be returned from the function\nby listing them on the left side of the exclamation mark. While the valid values\nstay on the right side of the exclamation mark. So the syntax format become:\n\n```\n<error-value>!<valid-value>\n```\n\n\n### Error sets\n\nBut what about when we have a single function that might return different types of errors?\nWhen you have such a function, you can list\nall of these different types of errors that can be returned from this function,\nthrough a structure in Zig that we call of an *error set*.\n\nAn error set is a special case of an union type. It is an union that contains error values in it.\nNot all programming languages have a notion of an \"union object\".\nBut in summary, an union is just a set of data types.\nUnions are used to allow an object to have multiple data types.\nFor example, a union of `x`, `y` and `z`, means that\nan object can be either of type `x`, or type `y` or type `z`.\n\nWe are going to talk in more depth about unions at @sec-unions.\nBut you can write an error set by writing the keyword `error` before\na pair of curly braces, then you list the error values that can be\nreturned from the function inside this pair of curly braces.\n\nTake the `resolvePath()` function below as an example, which comes from the\n`introspect.zig` module of the Zig Standard Library. We can see in its return type annotation, that this\nfunction return either: 1) a valid slice of `u8` values (`[]u8`); or, 2) one of the three different\ntypes of error values listed inside the error set (`OutOfMemory`, `Unexpected`, etc.).\nThis is an usage example of an error set.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn resolvePath(\n    ally: mem.Allocator,\n    p: []const u8,\n) error{\n    OutOfMemory,\n    CurrentWorkingDirectoryUnlinked,\n    Unexpected,\n}![]u8 {\n    // The body of the function ...\n}\n```\n:::\n\n\n\n\n\nThis is a valid way of annotating the return value of a Zig function. But, if you navigate through\nthe modules that composes the Zig Standard Library, you will notice that, for the majority of cases,\nthe programmers prefer to give a descriptive name to this error set, and then, use this name (or this \"label\")\nof the error set in the return type annotation, instead of using the error set directly.\n\nWe can see that in the `ReadError` error set that we showed earlier in the `fill()` function,\nwhich is defined in the `http.Client` module.\nSo yes, I presented the `ReadError` as if it was just a standard and single error value, but in fact,\nit is an error set defined in the `http.Client` module, and therefore, it actually represents\na set of different error values that might happen inside the `fill()` function.\n\n\nTake a look at the `ReadError` definition reproduced below. Notice that we are grouping all of these\ndifferent error values into a single object, and then, we use this object into the return type annotation of the function.\nLike the `fill()` function that we showed earlier, or, the `readvDirect()` function from the same module,\nwhich is reproduced below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const ReadError = error{\n    TlsFailure,\n    TlsAlert,\n    ConnectionTimedOut,\n    ConnectionResetByPeer,\n    UnexpectedReadFailure,\n    EndOfStream,\n};\n// Some lines of code\npub fn readvDirect(\n        conn: *Connection,\n        buffers: []std.posix.iovec\n    ) ReadError!usize {\n    // The body of the function ...\n}\n```\n:::\n\n\n\n\nSo, an error set is just a convenient way of grouping a set of\npossible error values into a single object, or a single type of an error value.\n\n\n### Casting error values\n\nLet's suppose you have two different error sets, named `A` and `B`.\nIf error set `A` is a superset of error set `B`, then, you can cast (or coerce)\nerror values from `B` into error values of `A`.\n\nError sets are just a set of error values. So, if the error set `A`\ncontains all error values from the error set `B`, then `A`\nbecomes a superset of `B`. You could also say\nthat the error set `B` is a subset of error set `A`.\n\nThe example below demonstrates this idea. Because `A` contains all\nvalues from `B`, `A` is a superset of `B`.\nIn math notation, we would say that $A \\supset B$.\nAs a consequence, we can give an error value from `B` as input to the `cast()`\nfunction, and, implicitly cast this input into the same error value, but from the `A` set.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst A = error{\n    ConnectionTimeoutError,\n    DatabaseNotFound,\n    OutOfMemory,\n    InvalidToken,\n};\nconst B = error {\n    OutOfMemory,\n};\n\nfn cast(err: B) A {\n    return err;\n}\n\ntest \"coerce error value\" {\n    const error_value = cast(B.OutOfMemory);\n    try std.testing.expect(\n        error_value == A.OutOfMemory\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filea64e1da1167c.test.coerce error value...OKA\n  All 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n## How to handle errors\n\nNow that we learned more about what errors are in Zig,\nlet's discuss the available strategies to handle these errors,\nwhich are:\n\n- `try` keyword;\n- `catch` keyword;\n- an if statement;\n- `errdefer` keyword;\n\n\n\n### What `try` means?\n\nAs I described over the previous sections, when we say that an expression might\nreturn an error, we are basically referring to an expression that have\na return type in the format `!T`.\nThe `!` indicates that this expression returns either an error value, or a value of type `T`.\n\nAt @sec-main-file, I presented the `try` keyword and where to use it.\nBut I did not talked about what exactly this keyword does to your code,\nor, in other words, I have not explained yet what `try` means in your code.\n\nIn essence, when you use the `try` keyword in an expression, you are telling\nthe `zig` compiler the following: \"Hey! Execute this expression for me,\nand, if this expression return an error, please, return this error for me\nand stop the execution of my program. But if this expression return a valid\nvalue, then, return this value, and move on\".\n\nIn other words, the `try` keyword is essentially, a strategy to enter in panic mode, and stop\nthe execution of your program in case an error occurs.\nWith the `try` keyword, you are telling the `zig` compiler, that stopping the execution\nof your program is the most reasonable strategy to take if an error occurs\nin that particular expression.\n\n### The `catch` keyword\n\nOk, now that we understand properly what `try` means, let's discuss `catch` now.\nOne important detail here, is that you can use `try` or `catch` to handle your errors,\nbut you **cannot use `try` and `catch` together**. In other words, `try` and `catch`\nare different and completely separate strategies in the Zig language.\n\nThis is uncommon, and different than what happens in other languages. Most\nprogramming languages that adopts the *try catch* pattern (such as C++, R, Python, Javascript, etc.), normally use\nthese two keywords together to form the complete logic to\nproperly handle the errors.\nAnyway, Zig tries a different approach in the *try catch* pattern.\n\nSo, we learned already about what `try` means, and we also known that both\n`try` and `catch` should be used alone, separate from each other. But\nwhat exactly `catch` do in Zig? With `catch`, we can construct a block of\nlogic to handle the error value, in case it happens in the current expression.\n\nLook at the code example below. Once again, we go back to the previous\nexample where we were trying to open a file that doesn't exist in my computer,\nbut this time, I use `catch` to actually implement a logic to handle the error, instead of\njust stopping the execution right away.\n\nMore specifically, in this example, I'm using a logger object to record some logs into\nthe system, before I return the error, and stop the execution of the program. For example,\nthis could be some part of the codebase of a complex system that I do not have full control over,\nand I want to record these logs before the program crashes, so that I can debug it later\n(e.g. maybe I cannot compile the full program, and properly debug it with a debugger. So, these logs might\nbe a valid strategy to surpass this barrier).\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst dir = std.fs.cwd();\nconst file = dir.openFile(\n    \"doesnt_exist.txt\", .{}\n) catch |err| {\n    logger.record_context();\n    logger.log_error(err);\n    return err;\n};\n```\n:::\n\n\n\n\n\nTherefore, we use `catch` to create a block of expressions that will handle the error.\nI can return the error value from this block of expressions, like I did in the above example,\nwhich, will make the program enter in panic mode, and, stop the execution.\nBut I could also, return a valid value from this block of code, which would\nbe stored in the `file` object.\n\nNotice that, instead of writing the keyword before the expression that might return the error,\nlike we do with `try`, we write `catch` after the expression. We can open the pair of pipes (`|`),\nwhich captures the error value returned by the expression, and makes\nthis error value available in the scope of the `catch` block as the object named `err`.\nIn other words, because I wrote `|err|` in the code, I can access the error value\nreturned by the expression, by using the `err` object.\n\nAlthough this being the most common use of `catch`, you can also use this keyword\nto handle the error in a \"default value\" style. That is, if the expression returns\nan error, we use the default value instead. Otherwise, we use the valid value returned\nby the expression.\n\nThe Zig official language reference, provides a great example of this \"default value\"\nstrategy with `catch`. This example is reproduced below. Notice that we are trying to parse\nsome unsigned integer from a string object named `str`. In other words, this function\nis trying to transform an object of type `[]const u8` (i.e. an array of characters, a string, etc.)\ninto an object of type `u64`.\n\nBut this parsing process done by the function `parseU64()` may fail, resulting in a runtime error.\nThe `catch` keyword used in this example provides an alternative value (13) to be used in case\nthis `parseU64()` function raises an error. So, the expression below essentially means:\n\"Hey! Please, parse this string into a `u64` for me, and store the results into the\nobject `number`. But, if an error occurs, then, use the value `13` instead\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number = parseU64(str, 10) catch 13;\n```\n:::\n\n\n\n\nSo, at the end of this process, the object `number` will contain either a `u64` integer\nthat was parsed successfully from the input string `str`, or, if an error occurs in the\nparsing process, it will contain the `u64` value `13` that was provided by the `catch`\nkeyword as the \"default\", or, the \"alternative\" value.\n\n\n\n### Using if statements\n\nNow, you can also use if statements to handle errors in your Zig code.\nIn the example below, I'm reproducing the previous example, where\nwe try to parse an integer value from an input string with a function\nnamed `parseU64()`.\n\nWe execute the expression inside the \"if\". If this expression returns an\nerror value, the \"if branch\" (or, the \"true branch\") of the if statement is not executed.\nBut if this expression returns a valid value instead, then, this value is unwrapped\ninto the `number` object.\n\nThis means that, if the `parseU64()` expression returns a valid value, this value becomes available\ninside the scope of this \"if branch\" (i.e. the \"true branch\") through the object that we listed inside the pair\nof pipe character (`|`), which is the object `number`.\n\nIf an error occurs, we can use an \"else branch\" (or the \"false branch\") of the if statement\nto handle the error. In the example below, we are using the `else` in the if statement\nto unwrap the error value (that was returned by `parseU64()`) into the `err` object,\nand handle the error.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (parseU64(str, 10)) |number| {\n    // do something with `number` here\n} else |err| {\n    // handle the error value.\n}\n```\n:::\n\n\n\n\nNow, if the expression that you are executing returns different types of error values,\nand you want to take a different action in each of these types of error values, the\n`try` and `catch` keywords, and the if statement strategy, becomes limited.\n\nFor this type of situation, the official documentation of the language suggests\nthe use of a switch statement together with an if statement [@zigdocs].\nThe basic idea is, to use the if statement to execute the expression, and\nuse the \"else branch\" to pass the error value to a switch statement, where\nyou define a different action for each type of error value that might be\nreturned by the expression executed in the if statement.\n\nThe example below demonstrates this idea. We first try to add (or register) a set of\ntasks to a queue. If this \"registration process\" occurs well, we then try\nto distribute these tasks across the workers of our system. But\nif this \"registration process\" returns an error value, we then use a switch\nstatement in the \"else branch\" to handle each possible error value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (add_tasks_to_queue(&queue, tasks)) |_| {\n    distribute_tasks(&queue);\n} else |err| switch (err) {\n    error.InvalidTaskName => {\n        // do something\n    },\n    error.TimeoutTooBig => {\n        // do something\n    },\n    error.QueueNotFound => {\n        // do something\n    },\n    // and all the other error options ...\n}\n```\n:::\n\n\n\n\n\n### The `errdefer` keyword {#sec-errdefer2}\n\nA common pattern in C programs in general, is to clean resources when an error occurs during\nthe execution of the program. In other words, one common way to handle errors, is to perform\n\"cleanup actions\" before we exit our program. This guarantees that a runtime error does not make\nour program to leak resources of the system.\n\n\nThe `errdefer` keyword is a tool to perform such \"cleanup actions\" in hostile situations.\nThis keyword is commonly used to clean (or to free) allocated resources, before the execution of our program\nget's stopped because of an error value being generated.\n\nThe basic idea is to provide an expression to the `errdefer` keyword. Then,\n`errdefer` executes this expression if, and only if, an error occurs\nduring the execution of the current scope.\nIn the example below, we are using an allocator object (that we have presented at @sec-allocators)\nto create a new `User` object. If we are successful in creating and registering this new user,\nthis `create_user()` function will return this new `User` object as its return value.\n\nHowever, if for some reason, an error value is generated by some expression\nthat is after the `errdefer` line, for example, in the `db.add(user)` expression,\nthe expression registered by `errdefer` get's executed before the error value is returned\nfrom the function, and before the program enters in panic mode and stops the\ncurrent execution.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn create_user(db: Database, allocator: Allocator) !User {\n    const user = try allocator.create(User);\n    errdefer allocator.destroy(user);\n\n    // Register new user in the Database.\n    _ = try db.register_user(user);\n    return user;\n}\n```\n:::\n\n\n\n\nBy using `errdefer` to destroy the `user` object that we have just created,\nwe guarantee that the memory allocated for this `user` object\nget's freed, before the execution of the program stops.\nBecause if the expression `try db.add(user)` returns an error value,\nthe execution of our program stops, and we lose all references and control over the memory\nthat we have allocated for the `user` object.\nAs a result, if we do not free the memory associated with the `user` object before the program stops,\nwe cannot free this memory anymore. We simply lose our chance to do the right thing.\nThat is why `errdefer` is essential in this situation.\n\nJust to state clearly the differences between `defer` and `errdefer`\n(which I described at @sec-defer and @sec-errdefer1), it might be worth\nto discuss the subject a bit further. You might still have the question\n\"why use `errdefer` if we can use `defer` instead?\" in your mind.\n\nAlthough being similar, the key difference between `errdefer` and `defer` keyword\nis when the provided expression get's executed.\nThe `defer` keyword always execute the provided expression at the end of the\ncurrent scope, no matter how your code exits this scope.\nIn contrast, `errdefer` executes the provided expression only when an error occurs in the\ncurrent scope.\n\nThis becomes important if a resource that you allocate in the\ncurrent scope get's freed later in your code, in a different scope.\nThe `create_user()` functions is an example of this. If you think\nclosely about this function, you will notice that this function returns\nthe `user` object as the result.\n\nIn other words, the allocated memory for the `user` object does not get\nfreed inside the `create_user()` function, if it returns successfully.\nSo, if an error does not occur inside this function, the `user` object\nis returned from the function, and probably, the code that runs after\nthis `create_user()` function will be responsible for freeing\nthe memory of the `user` object.\n\nBut what if an error occurs inside the `create_user()` function? What happens then?\nThis would mean that the execution of your code would stop in this `create_user()`\nfunction, and, as a consequence, the code that runs after this `create_user()`\nfunction would simply not run, and, as a result, the memory of the `user` object\nwould not be freed before your program stops.\n\nThis is the perfect scenario for `errdefer`. We use this keyword to guarantee\nthat our program will free the allocated memory for the `user` object,\neven if an error occurs inside the `create_user()` function.\n\nIf you allocate and free some memory for an object inside the same scope, then,\njust use `defer` and be happy, i.e. `errdefer` have no use for you in such situation.\nBut if you allocate some memory in a scope A, but you only free this memory\nlater, in a scope B for example, then, `errdefer` becomes useful to avoid leaking memory\nin sketchy situations.\n\n\n\n## Union type in Zig {#sec-unions}\n\nAn union type defines a set of types that an object can be. It is like a list of\noptions. Each option is a type that an object can assume. Therefore, unions in Zig\nhave the same meaning, or, the same role as unions in C. They are used for the same purpose.\nYou could also say that unions in Zig produces a similar effect to\n[using `typing.Union` in Python](https://docs.python.org/3/library/typing.html#typing.Union)[^pyunion].\n\n[^pyunion]: <https://docs.python.org/3/library/typing.html#typing.Union>\n\nFor example, you might be creating an API that sends data to a data lake, hosted\nin some private cloud infrastructure. Suppose you have created different structs in your codebase,\nto store the necessary information that you need, in order to connect to the services of\neach mainstream data lake service (Amazon S3, Azure Blob, etc.).\n\nNow, suppose you also have a function named `send_event()` that receives an event as input,\nand, a target data lake, and it sends the input event to the data lake specified in the\ntarget data lake argument. But this target data lake could be any of the three mainstream data lakes\nservices (Amazon S3, Azure Blob, etc.). Here is where an union can help you.\n\nThe union `LakeTarget` defined below allows the `lake_target` argument of `send_event()`\nto be either an object of type `AzureBlob`, or type `AmazonS3`, or type `GoogleGCP`.\nThis union allows the `send_event()` function to receive an object of any of these three types\nas input in the `lake_target` argument.\n\nRemember that each of these three types (`AmazonS3`, `GoogleGCP` and `AzureBlob`)\nare separate structs that we have defined in our source code. So, at first glance,\nthey are separate data types in our source code. But is the `union` keyword that\nunifies them into a single data type called `LakeTarget`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst LakeTarget = union {\n    azure: AzureBlob,\n    amazon: AmazonS3,\n    google: GoogleGCP,\n};\n\nfn send_event(\n    event: Event,\n    lake_target: LakeTarget\n) bool {\n    // body of the function ...\n}\n```\n:::\n\n\n\n\nAn union definition is composed by a list of data members. Each data member is of a specific data type.\nIn the example above, the `LakeTarget` union have three data members (`azure`, `amazon`, `google`).\nWhen you instantiate an object that uses an union type, you can only use one of its data members\nin this instantiation.\n\nYou could also interpret this as: only one data member of an union type can be activated at a time, the other data\nmembers remain deactivated and unaccessible. For example, if you create a `LakeTarget` object that uses\nthe `azure` data member, you can no longer use or access the data members `google` or `amazon`.\nIt is like if these other data members didn't exist at all in the `LakeTarget` type.\n\nYou can see this logic in the example below. Notice that, we first instantiate the union\nobject using the `azure` data member. As a result, this `target` object contains only\nthe `azure` data member inside of it. Only this data member is active in this object.\nThat is why the last line in this code example is invalid. Because we are trying to instantiate the data member\n`google`, which is currently inactive for this `target` object, and as a result, the program\nenters in panic mode warning us about this mistake through a loud error message.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar target = LakeTarget {\n    .azure = AzureBlob.init()\n};\n// Only the `azure` data member exist inside\n// the `target` object, and, as a result, this\n// line below is invalid:\ntarget.google = GoogleGCP.init();\n```\n:::\n\n\n\n\n```\nthread 2177312 panic: access of union field 'google' while\n    field 'azure' is active:\n    target.google = GoogleGCP.init();\n          ^\n```\n\nSo, when you instantiate an union object, you must choose one of the data types (or, one of the data members)\nlisted in the union type. In the example above, I choose to use the `azure` data member, and, as a result,\nall other data members were automatically deactivated,\nand you can no longer use them after you instantiate the object.\n\nYou can activate another data member by completely redefining the entire enum object.\nIn the example below, I initially use the `azure` data member. But then, I redefine the\n`target` object to use a new `LakeTarget` object, which uses the `google` data member.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar target = LakeTarget {\n    .azure = AzureBlob.init()\n};\ntarget = LakeTarget {\n    .google = GoogleGCP.init()\n};\n```\n:::\n\n\n\n\nA curious fact about union types, is that, at first, you cannot use them in switch statements (which were presented at @sec-switch).\nIn other words, if you have an object of type `LakeTarget` for example, you cannot give this object\nas input to a switch statement.\n\nBut what if you really need to do so? What if you actually need to\nprovide an \"union object\" to a switch statement? The answer to this question relies on another special type in Zig,\nwhich are the *tagged unions*. To create a tagged union, all you have to do is to add\nan enum type into your union declaration.\n\nAs an example of a tagged union in Zig, take the `Registry` type exposed\nbelow. This type comes from the\n[`grammar.zig` module](https://github.com/ziglang/zig/blob/30b4a87db711c368853b3eff8e214ab681810ef9/tools/spirv/grammar.zig)[^grammar]\nfrom the Zig repository. This union type lists different types of registries.\nBut notice this time, the use of `(enum)` after the `union` keyword. This is what makes\nthis union type a tagged union. By being a tagged union, an object of this `Registry` type\ncan be used as input in a switch statement. This is all you have to do. Just add `(enum)`\nto your `union` declaration, and you can use it in switch statements.\n\n[^grammar]: <https://github.com/ziglang/zig/blob/30b4a87db711c368853b3eff8e214ab681810ef9/tools/spirv/grammar.zig>.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const Registry = union(enum) {\n    core: CoreRegistry,\n    extension: ExtensionRegistry,\n};\n```\n:::\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
diff --git a/_freeze/Chapters/10-stack-project/execute-results/html.json b/_freeze/Chapters/10-stack-project/execute-results/html.json
index 45ec4bce..2bc7f08f 100644
--- a/_freeze/Chapters/10-stack-project/execute-results/html.json
+++ b/_freeze/Chapters/10-stack-project/execute-results/html.json
@@ -2,10 +2,8 @@
   "hash": "0c651ab91f56f6b099ea4bfebc8882dd",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 3 - Building a stack data structure\n\nIn this chapter we are going to implement a stack data structure as our next small project\nin this book. Implementing basic data structures in any language is kind of a\n\"kindergarten task\" (if this term even exist) in computer science (CS), because\nwe normally learn and implement them in the first semesters of CS.\n\nBut this is actually good! Since this should be a very easy task, we don't need much to explain\nwhat a stack is, then, we can concentrate on what is really important here, which is learning\nhow the concept of \"generics\" is implemented in the Zig language, and how one of the key\nfeatures of Zig, which is comptime, works, and use the stack data structure to demonstrate\nthese concepts on the fly.\n\nBut before we get into building the stack data structure, we first need to understand\nwhat the `comptime` keyword does to your code, and after that, we also need to learn about\nhow generics work in Zig.\n\n\n## Understanding `comptime` in Zig {#sec-comptime}\n\nOne of the key features of Zig is `comptime`. This keyword introduces a whole\nnew concept and paradigm, that is tightly connected with the compilation process.\nAt @sec-compile-time we have described the importance and the role that \"compile-time versus runtime\"\nplays into Zig. At that section, we learned that the rules applied to a value/object change\na lot depending on whether this value is known at compile-time, or just at runtime.\n\nThe `comptime` keyword is strongly related to these two spaces in time (compile-time and runtime).\nLet's quickly recap the differences. Compile-time is the period of time when your\nZig source code is being compiled by the `zig` compiler, while the runtime is\nthe period of time when your Zig program is being executed, i.e. when we execute\nthe binary files that were generated by the `zig` compiler.\n\nThere are three ways in which you can apply the `comptime` keyword, which are:\n\n- apply `comptime` on a function argument.\n- apply `comptime` on an object.\n- apply `comptime` on a block of expressions.\n\n\n\n### Applying over a function argument\n\nWhen you apply the `comptime` keyword on a function argument, you are saying to the `zig` compiler\nthat the value assigned to that particular function argument must be known at compile-time.\nWe explained in details at @sec-compile-time what exactly \"value known at compile-time\" means, so,\nin case you have doubts about this idea, come back to that section.\n\nNow let's think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement\nto that particular function argument. If the programmer accidentally tries to give a value to this\nfunction argument that is not known at compile time, the `zig` compiler will notice this problem, and\nas a consequence, it will raise a compilation error saying that it cannot compile your program. Because\nyou are providing a value that is \"runtime known\" to a function argument that must be \"compile-time known\".\n\nTake a look at this very simple example below, where we define a `twice()` function, that simply\ndoubles the input value named `num`. Notice that we use the `comptime` keyword before the name\nof the function argument. This keyword is marking the function argument `num` as a \"comptime argument\".\n\nThat is a function argument whose value must be compile-time known. This is why the expression\n`twice(5678)` is valid, and no compilation errors are raised. Because the value `5678`\nis compile-time known, so this is the expected behaviour for this function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file1105a40478a9d.test.test comptime...OKAll 1\n  1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\nBut what if we provide a number that is not compile-time known to this function?\nFor example, we might provide a different input value to this function depending\non the target OS of our compilation process. The code example below demonstrates such case.\n\nBecause the value of the object `n` is determined at runtime, we cannot provide this object\nas input to the `twice()` function. The `zig` compiler will not allow it, because we marked\nthe `num` argument as a \"comptime argument\". That is why the `zig` compiler raises\nthe compile-time error exposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    var n: u32 = undefined;\n    if (builtin.target.os.tag == .windows) {\n        n = 1234;\n    } else {\n        n = 5678;\n    }\n    _ = twice(n);\n}\n```\n:::\n\n\n\n\n```\nt.zig:12:16: error: runtime-known argument passed to comptime parameter \n```\n\nComptime arguments are frequently used on functions that return some sort\nof generic structure. In fact, `comptime` is the essence (or the basis) to make generics in Zig.\nWe are going to talk more about generics at @sec-generics.\n\nFor now, let's take a look at this code example from @karlseguin_generics. You\ncan see that this `IntArray()` function have one argument named `length`.\nThis argument is marked as comptime, and receives a value of type `usize` as input. So the value given to this argument\nmust be compile-time known.\nWe can also see that this function returns an array of `i64` values as output.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n```\n:::\n\n\n\n\nNow, the key component of this function is the `length` argument. This argument\nis used to determine the size of the array that is produced by the function. Let's\nthink about the consequences of that. If the size of the array is dependent on\nthe value assigned to the `length` argument, this means that the data type of the\noutput of the function depends on the value of this `length` argument.\n\nLet this statement sink for a bit in your mind. As I described at @sec-root-file,\nZig is a strongly-typed language, especially on function declarations.\nSo every time we write a function in Zig, we have to annotate the data type of\nthe value returned by the function. But how can we do that, if this data type\ndepends on the value given to the argument of the function?\n\nThink about this for a second. If `length` is equal to 3 for example, then, the\nreturn type of the function is `[3]i64`. But if `length` is equal to 40, then,\nthe return type becomes `[40]i64`. At this point the `zig` compiler would be confused,\nand raise a compilation error, saying something like this:\n\n> Hey! You have annotated that this function should return a `[3]i64` value, but I got a `[40]i64` value instead! This doesn't look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when\nthe `type` keyword comes in. This `type` keyword is basically saying to the\n`zig` compiler that this function will return some data type as output, but it doesn't know yet\nwhat exactly data type that is. We will talk more about this at @sec-generics.\n\n\n\n### Applying over an expression\n\nWhen you apply the `comptime` keyword over an expression, then, it is guaranteed that the `zig` compiler will\nexecute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time\n(e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the `zig` compiler\nwill raise a compilation error.\n\nTake this example from the official documentation of Zig [@zigdocs]. We\nare executing the same `fibonacci()` function both at runtime, and, at compile-time.\nThe function is by default executed at runtime, but because we use the `comptime`\nkeyword at the second \"try expression\", this expression is executed at compile-time.\n\nThis might be a bit confusing for some people. Yes! When I say that this expression\nis executed at compile-time, I mean that this expression is compiled and executed\nwhile the `zig` compiler is compiling your Zig source code.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file1105a31c0f24f.test.fibonacci...OKAll 1 tes\n  sts passed.\n```\n\n\n:::\n:::\n\n\n\n\nA lot of your Zig source code might be potentially executed at compile-time,\nbecause the `zig` compiler can figure it out the output of some expressions.\nEspecially if these expressions depends only at compile-time known values.\nWe have talked about this at @sec-compile-time.\n\nBut when you use the `comptime` keyword on an expression, there is no \"it might be executed\nat compile-time\" anymore. With the `comptime` keyword you are ordering the `zig` compiler\nto execute this expression at compile-time. You are imposing this rule, it is guaranteed\nthat the compiler will always execute it at compile-time. Or, at least, the compiler\nwill try to execute it. If the compiler cannot execute the expression for whatever reason,\nthe compiler will raise a compilation error.\n\n\n### Applying over a block\n\nBlocks were described at @sec-blocks. When you apply the `comptime` keyword over a\nblock of expressions, you get essentially the same effect when you apply this keyword to\na single expression. That is, the entire block of expressions is executed at\ncompile-time by the `zig` compiler.\n\nIn the example below, we mark the block labeled of `blk` as a comptime block,\nand, therefore, the expressions inside this block are executed at compile-time.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file1105a37ca2b0d.test.fibonacci in a block...\n  .OKAll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## Introducing Generics {#sec-generics}\n\nFirst of all, what is a generic? Generic is the idea to allow a type\n(`f64`, `u8`, `u32`, `bool`, and also, user-defined types, like the `User` struct\nthat we defined at @sec-structs-and-oop) to be a parameter to methods, classes and\ninterfaces [@geeks_generics]. In other words, a \"generic\" is a class (or a method) that can work\nwith multiple data types.\n\nFor example, in Java, generics are created through the operator `<>`. With this operator,\na Java class is capable of receiving a data type as input, and therefore, the class can fit\nits features according to this input data type.\nAs another example, generics in C++ are supported through the concept of templates.\nClass templates in C++ are generics.\n\nIn Zig, generics are implemented through `comptime`. The `comptime` keyword\nallows us to collect a data type at compile time, and pass this data type as\ninput to a piece of code.\n\n\n### A generic function {#sec-generic-fun}\n\nTake the `max()` function exposed below as a first example.\nThis function is essentially a \"generic function\".\nIn this function, we have a comptime function argument named `T`.\nNotice that this `T` argument have a data type of `type`. Weird right? This `type` keyword is the\n\"father of all types\", or, \"the type of types\" in Zig.\n\nBecause we have used this `type` keyword in the `T` argument, we are telling\nthe `zig` compiler that this `T` argument will receive some data type as input.\nAlso notice the use of the `comptime` keyword in this argument.\nAs I described at @sec-comptime, every time you use this keyword in a function argument,\nthis means that the value of this argument must be known at compile-time.\nThis makes sense, right? Because there is no data type that is not known at compile-time.\n\nThink about this. Every data type that you will ever write is always\nknown at compile-time. Especially because data types are an essential\ninformation for the compiler to actually compile your source code.\nHaving this in mind, makes sense to mark this argument as a comptime argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\n```\n:::\n\n\n\n\nAlso notice that the value of the `T` argument is actually used\nto define the data type of the other arguments in the function, `a` and `b`, and also at the\nreturn type annotation of the function.\nThat is, the data type of these arguments (`a` and `b`), and, the return data type of the function itself,\nare determined by the input value given to the `T` argument.\n\nAs a result, we have a generic function that works with different data types.\nFor example, I can provide `u8` values to this `max()` function, and it will work as expected.\nBut if I provide `f64` values instead, it will also work as expected.\nWithout a generic function, I would have to write a different `max()` function\nfor each one of the data types that I wanted to use.\nThis generic function provides a very useful shortcut for us.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\ntest \"test max\" {\n    const n1 = max(u8, 4, 10);\n    std.debug.print(\"Max n1: {d}\\n\", .{n1});\n    const n2 = max(f64, 89.24, 64.001);\n    std.debug.print(\"Max n2: {d}\\n\", .{n2});\n}\n```\n:::\n\n\n\n\n```\nMax n1: 10\nMax n2: 89.24\n```\n\n\n### A generic data structure {#sec-generic-struct}\n\nEvery data structure that you find in the Zig Standard Library (e.g. `ArrayList`, `HashMap`, etc.)\nis essentially a generic data structure.\nThese data structures are generic in the sense that they work with any data type you want.\nYou just say which is the data type of the values that are going to be stored in this data\nstructure, and they just work as expected.\n\nA generic data structure in Zig is how you replicate a generic class from Java,\nor, a class template from C++. But you may quest yourself: how do we build a\ngeneric data structure in Zig?\n\nThe basic idea is to write a generic function that creates the data structure definition\nfor the specific type we want. In other words, this generic function behaves as a \"factory of data structures\".\nThe generic function outputs the `struct` definition that defines this data structure for a\nspecific data type.\n\nTo create such function, we need to add a comptime argument to this function that receives a data type\nas input. We already learned how to do this at the previous section (@sec-generic-fun).\nI think the best way to demonstrate how to create a generic data structure is to actually write one.\nThis where we go into our next small project in this book. This one is a very small project,\nwhich is to write a generic stack data structure.\n\n\n\n\n## What is a stack? {#sec-what-stack}\n\nA stack data structure is a structure that follows a LIFO (*last in, first out*) principle.\nOnly two operations are normally supported in a stack data structure, which are `push` and `pop`.\nThe `push` operation is used to add new values to the stack, while `pop` is used to remove\nvalues from the stack.\n\nWhen people try to explain how the stack data structure works, the most common analogy\nthat they use is a stack of plates. Imagine that you have a stack of plates,\nfor example, a stack of 10 plates in your table. Each plate represents a value that\nis currently stored in this stack.\n\nWe begin with a stack of 10 different values, or 10 different plates. Now, imagine that you want to\nadd a new plate (or a new value) to this stack, which translates to the `push` operation.\nYou would add this plate (or this value) by just putting the new plate\non the top of the stack. Then, you would increase the stack to 11 plates.\n\nBut how would you remove plates (or remove values) from this stack (a.k.a. the `pop` operation) ?\nTo do that, we would have to remove the plate on the top of the stack, and, as a result, we would\nhave, once again, 10 plates in the stack.\n\nThis demonstrates the LIFO concept, because the first plate in the stack, which is the plate\nin the bottom of the stack, is always the last plate to get out of the stack. Think about it. In order\nto remove this specific plate from the stack, we have to remove all plates in the\nstack. So every operation in the stack, either insertion or deletion, is always made at the top of the stack.\nThe @fig-stack below exposes this logic visually:\n\n![A diagram of a stack structure. Source: Wikipedia, the free encyclopedia.](./../Figures/lifo-stack.svg){#fig-stack}\n\n\n\n## Writing the stack data structure\n\nWe are going to write the stack data structure in two steps. First, we are going\nto implement a stack that can only store `u32` values. Then, after that, we are going\nto extend our implementation to make it generic, so that it works with any data type\nwe want.\n\nFirst, we need to decide how the values will be stored inside the stack. There are multiple\nways to implement the storage behind a stack structure. Some people prefer to use a doubly linked list,\nsome others prefer to use a dynamic array, etc. In this example we are going to use an array behind the hood,\nto store the values in the stack, which is the `items` data member of our `Stack` struct definition.\n\nAlso notice in our `Stack` struct that we have three other data members: `capacity`, `length` and `allocator`.\nThe `capacity` member contains the capacity of the underlying array that stores the values in the stack.\nThe `length` contains the number of values that are currently being stored in the stack.\nAnd the `allocator` contains the allocator object that will be used by the stack structure whenever it\nneeds to allocate more space for the values that are being stored.\n\nWe begin by defining an `init()` method of this struct, which is going to be\nresponsible for instantiating a `Stack` object. Notice that, inside this\n`init()` method, we start by allocating an array with the capacity specified\nin the `capacity` argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst Stack = struct {\n    items: []u32,\n    capacity: usize,\n    length: usize,\n    allocator: Allocator,\n\n    pub fn init(allocator: Allocator, capacity: usize) !Stack {\n        var buf = try allocator.alloc(u32, capacity);\n        return .{\n            .items = buf[0..],\n            .capacity = capacity,\n            .length = 0,\n            .allocator = allocator,\n        };\n    }\n};\n```\n:::\n\n\n\n\n\n### Implementing the `push` operation\n\nNow that we have written the basic logic to create a new `Stack` object,\nwe can start writing the logic responsible for performing a push operation.\nRemember, a push operation in a stack data structure is the operation\nresponsible for adding a new value to the stack.\n\nSo how can we add a new value to the `Stack` object that we have?\nThe `push()` function exposed below is a possible answer to this question.\nRemember from what we discussed at @sec-what-stack that values are always added to the top of the stack.\nThis means that this `push()` function must always find the element in the underlying array\nthat currently represents the top position of the stack, and then, add the input value there.\n\nFirst, we have an if statement in this function. This if statement is\nchecking whether we need to expand the underlying array to store\nthis new value that we are adding to the stack. In other words, maybe\nthe underlying array does not have enough capacity to store this new\nvalue, and, in this case, we need to expand our array to get the capacity that we need.\n\nSo, if the logical test in this if statement returns true, it means that the array\ndoes not have enough capacity, and we need to expand it before we store this new value.\nSo inside this if statement we are executing the necessary expressions to expand the underlying array.\nNotice that we use the allocator object to allocate a new array that is twice as bigger\nthan the current array (`self.capacity * 2`).\n\nAfter that, we use a different built-in function named `@memcpy()`. This built-in function\nis equivalent to the `memcpy()` function from the C Standard Library[^cmemcpy]. It is used to\ncopy the values from one block of memory to another block of memory. In other words,\nyou can use this function to copy the values from one array into another array.\n\n[^cmemcpy]: <https://www.tutorialspoint.com/c_standard_library/c_function_memcpy.htm>\n\nWe are using this `@memcpy()` built-in function to copy the values that are currently stored\nin the underlying array of the stack object (`self.items`) into our new and bigger array that\nwe have allocated (`new_buf`). After we execute this function, the `new_buf` contains a copy\nof the values that are present at `self.items`.\n\nNow that we have secured a copy of our current values in the `new_buf` object, we\ncan now free the memory currently allocated at `self.items`. After that, we just need\nto assign our new and bigger array to `self.items`. This is the sequence\nof steps necessary to expand our array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn push(self: *Stack, val: u32) !void {\n    if ((self.length + 1) > self.capacity) {\n        var new_buf = try self.allocator.alloc(\n            u32, self.capacity * 2\n        );\n        @memcpy(\n            new_buf[0..self.capacity], self.items\n        );\n        self.allocator.free(self.items);\n        self.items = new_buf;\n        self.capacity = self.capacity * 2;\n    }\n\n    self.items[self.length] = val;\n    self.length += 1;\n}\n```\n:::\n\n\n\n\nAfter we make sure that we have enough room to store this new value\nthat we are adding to the stack, all we have to do is to assign\nthis value to the top element in this stack, and, increase the\nvalue of the `length` attribute by one. We find the top element\nin the stack by using the `length` attribute.\n\n\n\n### Implementing the `pop` operation\n\nNow we can implement the pop operation of our stack object.\nThis is a much easier operation to implement, and the `pop()` method below summarises\nall the logic that is needed.\n\nWe just have to find the element in the underlying array that currently represents the top\nof the stack, and set this element to \"undefined\", to indicate that\nthis element is \"empty\". After that, we also need to decrease\nthe `length` attribute of the stack by one.\n\nIf the current length of the stack is zero, it means that there is\nno values being stored in the stack currently. So, in this case,\nwe could just return from the function and do nothing really.\nThis is what the if statement inside this function is checking for.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn pop(self: *Stack) void {\n    if (self.length == 0) return;\n\n    self.items[self.length - 1] = undefined;\n    self.length -= 1;\n}\n```\n:::\n\n\n\n\n\n\n### Implementing the `deinit` method\n\nWe have implemented the methods responsible for the two main operations\nassociated with the stack data structure, which is `pop()` and `push()`,\nand we also have implemented the method responsible for instantiating\na new `Stack` object, which is the `init()` method.\n\nBut now, we need to implement also the method responsible for destroying\na `Stack` object. In Zig, this task is commonly associated with the method\nnamed `deinit()`. Most struct objects in Zig have such method, and it\nis commonly nicknamed \"the destructor method\".\n\nIn theory, all we have to do to destroy the `Stack` object is to make\nsure that we free the allocated memory for the underlying array, using\nthe allocator object that is stored inside the `Stack` object.\nThis is what the `deinit()` method below is doing.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn deinit(self: *Stack) void {\n    self.allocator.free(self.items);\n}\n```\n:::\n\n\n\n\n\n\n\n## Making it generic\n\nNow that we have implemented the basic skeleton of our stack data structure,\nwe can now focus on discussing how can we make it generic. How can we make\nthis basic skeleton to work not only with `u32` values, but also, with any other\ndata type we want?\nFor example, we might need to create a stack object to store `User` values\nin it. How can we make this possible? The answer lies on the use of generics\nand `comptime`.\n\nAs I described at @sec-generic-struct, the basic idea is to write a generic\nfunction that returns a struct definition as output.\nIn theory, we do not need much to transform our `Stack` struct into a generic\ndata structure. All that we need to do is to transform the underlying array\nof the stack into a generic array.\n\nIn other words, this underlying array needs to be a \"chameleon\". It needs to adapt,\nand transform it into an array of any data type that we want. For example, if we need to create\na stack that will store `u8` values, then, this underlying array needs to be\na `u8` array (i.e. `[]u8`). But if we need to store `User` values instead, then,\nthis array needs to be a `User` array (i.e. `[]User`). Etc.\n\nWe do that by using a generic function. Because a generic function can receive a data type\nas input, and we can pass this data type to the struct definition of our `Stack` object.\nTherefore, we can use the generic function to create a `Stack` object that can store\nthe data type we want. If we want to create a stack structure that stores `User` values,\nwe pass the `User` data type to this generic function, and it will create for us\nthe struct definition that describes a `Stack` object that can store `User` values in it.\n\nLook at the code example below. I have omitted some parts of the `Stack` struct definition\nfor brevity reasons. However, if a specific part of our `Stack` struct is not exposed here\nin this example, then it is because this part did not change from the previous example.\nIt remains the same.\n\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn Stack(comptime T: type) type {\n    return struct {\n        items: []T,\n        capacity: usize,\n        length: usize,\n        allocator: Allocator,\n        const Self = @This();\n\n        pub fn init(allocator: Allocator,\n                    capacity: usize) !Stack(T) {\n            var buf = try allocator.alloc(T, capacity);\n            return .{\n                .items = buf[0..],\n                .capacity = capacity,\n                .length = 0,\n                .allocator = allocator,\n            };\n        }\n\n        pub fn push(self: *Self, val: T) !void {\n        // Truncate the rest of the struct\n    };\n}\n```\n:::\n\n\n\n\nNotice that we have created a function in this example named `Stack()`. This function\ntakes a type as input, and passes this type to the struct definition of our\n`Stack` object. The data member `items` is now, an array of type `T`, which is the\ndata type that we have provided as input to the function. The function argument\n`val` in the `push()` function is now a value of type `T` too.\n\nWe can just provide a data type to this function, and it will create a definition of a\n`Stack` object that can store values of the data type that we have provided. In the example below, we are creating\nthe definition of a\n`Stack` object that can store `u8` values in it. This definition is stored at the `Stacku8` object.\nThis `Stacku8` object becomes our new struct, it is the struct that we are going to use\nto create our `Stack` object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst Stacku8 = Stack(u8);\nvar stack = try Stacku8.init(allocator, 10);\ndefer stack.deinit();\ntry stack.push(1);\ntry stack.push(2);\ntry stack.push(3);\ntry stack.push(4);\ntry stack.push(5);\ntry stack.push(6);\n\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\"Stack capacity: {d}\\n\", .{stack.capacity});\n\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\n    \"Stack state: {any}\\n\",\n    .{stack.items[0..stack.length]}\n);\n```\n:::\n\n\n\n\n```\nStack len: 6\nStack capacity: 10\nStack len: 5\nStack len: 4\nStack state: { 1, 2, 3, 4, 0, 0, 0, 0, 0, 0 }\n```\n\nEvery generic data structure in the Zig Standard Library (`ArrayList`, `HashMap`, `SinlyLinkedList`, etc.)\nis implemented through this logic. They use a generic function to create the struct definition that can work\nwith the data type that you provided as input.\n\n\n\n\n## Conclusion\n\nThe full source code of the stack structure discussed in this chapter is freely available at the official\nrepository of this book. Just checkout the [`stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig)[^zig-stack]\nfor the `u32` version of our stack,\nand the [`generic_stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig)[^zig-stack2]\nfor the generic version, available inside the `ZigExamples` folder of the repository.\n\n\n[^zig-stack]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig>\n[^zig-stack2]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig>\n\n",
-    "supporting": [
-      "10-stack-project_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 3 - Building a stack data structure\n\nIn this chapter we are going to implement a stack data structure as our next small project\nin this book. Implementing basic data structures in any language is kind of a\n\"kindergarten task\" (if this term even exist) in computer science (CS), because\nwe normally learn and implement them in the first semesters of CS.\n\nBut this is actually good! Since this should be a very easy task, we don't need much to explain\nwhat a stack is, then, we can concentrate on what is really important here, which is learning\nhow the concept of \"generics\" is implemented in the Zig language, and how one of the key\nfeatures of Zig, which is comptime, works, and use the stack data structure to demonstrate\nthese concepts on the fly.\n\nBut before we get into building the stack data structure, we first need to understand\nwhat the `comptime` keyword does to your code, and after that, we also need to learn about\nhow generics work in Zig.\n\n\n## Understanding `comptime` in Zig {#sec-comptime}\n\nOne of the key features of Zig is `comptime`. This keyword introduces a whole\nnew concept and paradigm, that is tightly connected with the compilation process.\nAt @sec-compile-time we have described the importance and the role that \"compile-time versus runtime\"\nplays into Zig. At that section, we learned that the rules applied to a value/object change\na lot depending on whether this value is known at compile-time, or just at runtime.\n\nThe `comptime` keyword is strongly related to these two spaces in time (compile-time and runtime).\nLet's quickly recap the differences. Compile-time is the period of time when your\nZig source code is being compiled by the `zig` compiler, while the runtime is\nthe period of time when your Zig program is being executed, i.e. when we execute\nthe binary files that were generated by the `zig` compiler.\n\nThere are three ways in which you can apply the `comptime` keyword, which are:\n\n- apply `comptime` on a function argument.\n- apply `comptime` on an object.\n- apply `comptime` on a block of expressions.\n\n\n\n### Applying over a function argument\n\nWhen you apply the `comptime` keyword on a function argument, you are saying to the `zig` compiler\nthat the value assigned to that particular function argument must be known at compile-time.\nWe explained in details at @sec-compile-time what exactly \"value known at compile-time\" means, so,\nin case you have doubts about this idea, come back to that section.\n\nNow let's think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement\nto that particular function argument. If the programmer accidentally tries to give a value to this\nfunction argument that is not known at compile time, the `zig` compiler will notice this problem, and\nas a consequence, it will raise a compilation error saying that it cannot compile your program. Because\nyou are providing a value that is \"runtime known\" to a function argument that must be \"compile-time known\".\n\nTake a look at this very simple example below, where we define a `twice()` function, that simply\ndoubles the input value named `num`. Notice that we use the `comptime` keyword before the name\nof the function argument. This keyword is marking the function argument `num` as a \"comptime argument\".\n\nThat is a function argument whose value must be compile-time known. This is why the expression\n`twice(5678)` is valid, and no compilation errors are raised. Because the value `5678`\nis compile-time known, so this is the expected behaviour for this function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filea72d248f97f8.test.test comptime...OKAll 1 \n   tests passed.\n```\n\n\n:::\n:::\n\n\n\n\nBut what if we provide a number that is not compile-time known to this function?\nFor example, we might provide a different input value to this function depending\non the target OS of our compilation process. The code example below demonstrates such case.\n\nBecause the value of the object `n` is determined at runtime, we cannot provide this object\nas input to the `twice()` function. The `zig` compiler will not allow it, because we marked\nthe `num` argument as a \"comptime argument\". That is why the `zig` compiler raises\nthe compile-time error exposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    var n: u32 = undefined;\n    if (builtin.target.os.tag == .windows) {\n        n = 1234;\n    } else {\n        n = 5678;\n    }\n    _ = twice(n);\n}\n```\n:::\n\n\n\n\n```\nt.zig:12:16: error: runtime-known argument passed to comptime parameter \n```\n\nComptime arguments are frequently used on functions that return some sort\nof generic structure. In fact, `comptime` is the essence (or the basis) to make generics in Zig.\nWe are going to talk more about generics at @sec-generics.\n\nFor now, let's take a look at this code example from @karlseguin_generics. You\ncan see that this `IntArray()` function have one argument named `length`.\nThis argument is marked as comptime, and receives a value of type `usize` as input. So the value given to this argument\nmust be compile-time known.\nWe can also see that this function returns an array of `i64` values as output.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n```\n:::\n\n\n\n\nNow, the key component of this function is the `length` argument. This argument\nis used to determine the size of the array that is produced by the function. Let's\nthink about the consequences of that. If the size of the array is dependent on\nthe value assigned to the `length` argument, this means that the data type of the\noutput of the function depends on the value of this `length` argument.\n\nLet this statement sink for a bit in your mind. As I described at @sec-root-file,\nZig is a strongly-typed language, especially on function declarations.\nSo every time we write a function in Zig, we have to annotate the data type of\nthe value returned by the function. But how can we do that, if this data type\ndepends on the value given to the argument of the function?\n\nThink about this for a second. If `length` is equal to 3 for example, then, the\nreturn type of the function is `[3]i64`. But if `length` is equal to 40, then,\nthe return type becomes `[40]i64`. At this point the `zig` compiler would be confused,\nand raise a compilation error, saying something like this:\n\n> Hey! You have annotated that this function should return a `[3]i64` value, but I got a `[40]i64` value instead! This doesn't look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when\nthe `type` keyword comes in. This `type` keyword is basically saying to the\n`zig` compiler that this function will return some data type as output, but it doesn't know yet\nwhat exactly data type that is. We will talk more about this at @sec-generics.\n\n\n\n### Applying over an expression\n\nWhen you apply the `comptime` keyword over an expression, then, it is guaranteed that the `zig` compiler will\nexecute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time\n(e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the `zig` compiler\nwill raise a compilation error.\n\nTake this example from the official documentation of Zig [@zigdocs]. We\nare executing the same `fibonacci()` function both at runtime, and, at compile-time.\nThe function is by default executed at runtime, but because we use the `comptime`\nkeyword at the second \"try expression\", this expression is executed at compile-time.\n\nThis might be a bit confusing for some people. Yes! When I say that this expression\nis executed at compile-time, I mean that this expression is compiled and executed\nwhile the `zig` compiler is compiling your Zig source code.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filea72d3cf7abe2.test.fibonacci...OKAll 1 test\n  ts passed.\n```\n\n\n:::\n:::\n\n\n\n\nA lot of your Zig source code might be potentially executed at compile-time,\nbecause the `zig` compiler can figure it out the output of some expressions.\nEspecially if these expressions depends only at compile-time known values.\nWe have talked about this at @sec-compile-time.\n\nBut when you use the `comptime` keyword on an expression, there is no \"it might be executed\nat compile-time\" anymore. With the `comptime` keyword you are ordering the `zig` compiler\nto execute this expression at compile-time. You are imposing this rule, it is guaranteed\nthat the compiler will always execute it at compile-time. Or, at least, the compiler\nwill try to execute it. If the compiler cannot execute the expression for whatever reason,\nthe compiler will raise a compilation error.\n\n\n### Applying over a block\n\nBlocks were described at @sec-blocks. When you apply the `comptime` keyword over a\nblock of expressions, you get essentially the same effect when you apply this keyword to\na single expression. That is, the entire block of expressions is executed at\ncompile-time by the `zig` compiler.\n\nIn the example below, we mark the block labeled of `blk` as a comptime block,\nand, therefore, the expressions inside this block are executed at compile-time.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filea72d6353d586.test.fibonacci in a block...O\n  OKAll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## Introducing Generics {#sec-generics}\n\nFirst of all, what is a generic? Generic is the idea to allow a type\n(`f64`, `u8`, `u32`, `bool`, and also, user-defined types, like the `User` struct\nthat we defined at @sec-structs-and-oop) to be a parameter to methods, classes and\ninterfaces [@geeks_generics]. In other words, a \"generic\" is a class (or a method) that can work\nwith multiple data types.\n\nFor example, in Java, generics are created through the operator `<>`. With this operator,\na Java class is capable of receiving a data type as input, and therefore, the class can fit\nits features according to this input data type.\nAs another example, generics in C++ are supported through the concept of templates.\nClass templates in C++ are generics.\n\nIn Zig, generics are implemented through `comptime`. The `comptime` keyword\nallows us to collect a data type at compile time, and pass this data type as\ninput to a piece of code.\n\n\n### A generic function {#sec-generic-fun}\n\nTake the `max()` function exposed below as a first example.\nThis function is essentially a \"generic function\".\nIn this function, we have a comptime function argument named `T`.\nNotice that this `T` argument have a data type of `type`. Weird right? This `type` keyword is the\n\"father of all types\", or, \"the type of types\" in Zig.\n\nBecause we have used this `type` keyword in the `T` argument, we are telling\nthe `zig` compiler that this `T` argument will receive some data type as input.\nAlso notice the use of the `comptime` keyword in this argument.\nAs I described at @sec-comptime, every time you use this keyword in a function argument,\nthis means that the value of this argument must be known at compile-time.\nThis makes sense, right? Because there is no data type that is not known at compile-time.\n\nThink about this. Every data type that you will ever write is always\nknown at compile-time. Especially because data types are an essential\ninformation for the compiler to actually compile your source code.\nHaving this in mind, makes sense to mark this argument as a comptime argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\n```\n:::\n\n\n\n\nAlso notice that the value of the `T` argument is actually used\nto define the data type of the other arguments in the function, `a` and `b`, and also at the\nreturn type annotation of the function.\nThat is, the data type of these arguments (`a` and `b`), and, the return data type of the function itself,\nare determined by the input value given to the `T` argument.\n\nAs a result, we have a generic function that works with different data types.\nFor example, I can provide `u8` values to this `max()` function, and it will work as expected.\nBut if I provide `f64` values instead, it will also work as expected.\nWithout a generic function, I would have to write a different `max()` function\nfor each one of the data types that I wanted to use.\nThis generic function provides a very useful shortcut for us.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\ntest \"test max\" {\n    const n1 = max(u8, 4, 10);\n    std.debug.print(\"Max n1: {d}\\n\", .{n1});\n    const n2 = max(f64, 89.24, 64.001);\n    std.debug.print(\"Max n2: {d}\\n\", .{n2});\n}\n```\n:::\n\n\n\n\n```\nMax n1: 10\nMax n2: 89.24\n```\n\n\n### A generic data structure {#sec-generic-struct}\n\nEvery data structure that you find in the Zig Standard Library (e.g. `ArrayList`, `HashMap`, etc.)\nis essentially a generic data structure.\nThese data structures are generic in the sense that they work with any data type you want.\nYou just say which is the data type of the values that are going to be stored in this data\nstructure, and they just work as expected.\n\nA generic data structure in Zig is how you replicate a generic class from Java,\nor, a class template from C++. But you may quest yourself: how do we build a\ngeneric data structure in Zig?\n\nThe basic idea is to write a generic function that creates the data structure definition\nfor the specific type we want. In other words, this generic function behaves as a \"factory of data structures\".\nThe generic function outputs the `struct` definition that defines this data structure for a\nspecific data type.\n\nTo create such function, we need to add a comptime argument to this function that receives a data type\nas input. We already learned how to do this at the previous section (@sec-generic-fun).\nI think the best way to demonstrate how to create a generic data structure is to actually write one.\nThis where we go into our next small project in this book. This one is a very small project,\nwhich is to write a generic stack data structure.\n\n\n\n\n## What is a stack? {#sec-what-stack}\n\nA stack data structure is a structure that follows a LIFO (*last in, first out*) principle.\nOnly two operations are normally supported in a stack data structure, which are `push` and `pop`.\nThe `push` operation is used to add new values to the stack, while `pop` is used to remove\nvalues from the stack.\n\nWhen people try to explain how the stack data structure works, the most common analogy\nthat they use is a stack of plates. Imagine that you have a stack of plates,\nfor example, a stack of 10 plates in your table. Each plate represents a value that\nis currently stored in this stack.\n\nWe begin with a stack of 10 different values, or 10 different plates. Now, imagine that you want to\nadd a new plate (or a new value) to this stack, which translates to the `push` operation.\nYou would add this plate (or this value) by just putting the new plate\non the top of the stack. Then, you would increase the stack to 11 plates.\n\nBut how would you remove plates (or remove values) from this stack (a.k.a. the `pop` operation) ?\nTo do that, we would have to remove the plate on the top of the stack, and, as a result, we would\nhave, once again, 10 plates in the stack.\n\nThis demonstrates the LIFO concept, because the first plate in the stack, which is the plate\nin the bottom of the stack, is always the last plate to get out of the stack. Think about it. In order\nto remove this specific plate from the stack, we have to remove all plates in the\nstack. So every operation in the stack, either insertion or deletion, is always made at the top of the stack.\nThe @fig-stack below exposes this logic visually:\n\n![A diagram of a stack structure. Source: Wikipedia, the free encyclopedia.](./../Figures/lifo-stack.svg){#fig-stack}\n\n\n\n## Writing the stack data structure\n\nWe are going to write the stack data structure in two steps. First, we are going\nto implement a stack that can only store `u32` values. Then, after that, we are going\nto extend our implementation to make it generic, so that it works with any data type\nwe want.\n\nFirst, we need to decide how the values will be stored inside the stack. There are multiple\nways to implement the storage behind a stack structure. Some people prefer to use a doubly linked list,\nsome others prefer to use a dynamic array, etc. In this example we are going to use an array behind the hood,\nto store the values in the stack, which is the `items` data member of our `Stack` struct definition.\n\nAlso notice in our `Stack` struct that we have three other data members: `capacity`, `length` and `allocator`.\nThe `capacity` member contains the capacity of the underlying array that stores the values in the stack.\nThe `length` contains the number of values that are currently being stored in the stack.\nAnd the `allocator` contains the allocator object that will be used by the stack structure whenever it\nneeds to allocate more space for the values that are being stored.\n\nWe begin by defining an `init()` method of this struct, which is going to be\nresponsible for instantiating a `Stack` object. Notice that, inside this\n`init()` method, we start by allocating an array with the capacity specified\nin the `capacity` argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst Stack = struct {\n    items: []u32,\n    capacity: usize,\n    length: usize,\n    allocator: Allocator,\n\n    pub fn init(allocator: Allocator, capacity: usize) !Stack {\n        var buf = try allocator.alloc(u32, capacity);\n        return .{\n            .items = buf[0..],\n            .capacity = capacity,\n            .length = 0,\n            .allocator = allocator,\n        };\n    }\n};\n```\n:::\n\n\n\n\n\n### Implementing the `push` operation\n\nNow that we have written the basic logic to create a new `Stack` object,\nwe can start writing the logic responsible for performing a push operation.\nRemember, a push operation in a stack data structure is the operation\nresponsible for adding a new value to the stack.\n\nSo how can we add a new value to the `Stack` object that we have?\nThe `push()` function exposed below is a possible answer to this question.\nRemember from what we discussed at @sec-what-stack that values are always added to the top of the stack.\nThis means that this `push()` function must always find the element in the underlying array\nthat currently represents the top position of the stack, and then, add the input value there.\n\nFirst, we have an if statement in this function. This if statement is\nchecking whether we need to expand the underlying array to store\nthis new value that we are adding to the stack. In other words, maybe\nthe underlying array does not have enough capacity to store this new\nvalue, and, in this case, we need to expand our array to get the capacity that we need.\n\nSo, if the logical test in this if statement returns true, it means that the array\ndoes not have enough capacity, and we need to expand it before we store this new value.\nSo inside this if statement we are executing the necessary expressions to expand the underlying array.\nNotice that we use the allocator object to allocate a new array that is twice as bigger\nthan the current array (`self.capacity * 2`).\n\nAfter that, we use a different built-in function named `@memcpy()`. This built-in function\nis equivalent to the `memcpy()` function from the C Standard Library[^cmemcpy]. It is used to\ncopy the values from one block of memory to another block of memory. In other words,\nyou can use this function to copy the values from one array into another array.\n\n[^cmemcpy]: <https://www.tutorialspoint.com/c_standard_library/c_function_memcpy.htm>\n\nWe are using this `@memcpy()` built-in function to copy the values that are currently stored\nin the underlying array of the stack object (`self.items`) into our new and bigger array that\nwe have allocated (`new_buf`). After we execute this function, the `new_buf` contains a copy\nof the values that are present at `self.items`.\n\nNow that we have secured a copy of our current values in the `new_buf` object, we\ncan now free the memory currently allocated at `self.items`. After that, we just need\nto assign our new and bigger array to `self.items`. This is the sequence\nof steps necessary to expand our array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn push(self: *Stack, val: u32) !void {\n    if ((self.length + 1) > self.capacity) {\n        var new_buf = try self.allocator.alloc(\n            u32, self.capacity * 2\n        );\n        @memcpy(\n            new_buf[0..self.capacity], self.items\n        );\n        self.allocator.free(self.items);\n        self.items = new_buf;\n        self.capacity = self.capacity * 2;\n    }\n\n    self.items[self.length] = val;\n    self.length += 1;\n}\n```\n:::\n\n\n\n\nAfter we make sure that we have enough room to store this new value\nthat we are adding to the stack, all we have to do is to assign\nthis value to the top element in this stack, and, increase the\nvalue of the `length` attribute by one. We find the top element\nin the stack by using the `length` attribute.\n\n\n\n### Implementing the `pop` operation\n\nNow we can implement the pop operation of our stack object.\nThis is a much easier operation to implement, and the `pop()` method below summarises\nall the logic that is needed.\n\nWe just have to find the element in the underlying array that currently represents the top\nof the stack, and set this element to \"undefined\", to indicate that\nthis element is \"empty\". After that, we also need to decrease\nthe `length` attribute of the stack by one.\n\nIf the current length of the stack is zero, it means that there is\nno values being stored in the stack currently. So, in this case,\nwe could just return from the function and do nothing really.\nThis is what the if statement inside this function is checking for.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn pop(self: *Stack) void {\n    if (self.length == 0) return;\n\n    self.items[self.length - 1] = undefined;\n    self.length -= 1;\n}\n```\n:::\n\n\n\n\n\n\n### Implementing the `deinit` method\n\nWe have implemented the methods responsible for the two main operations\nassociated with the stack data structure, which is `pop()` and `push()`,\nand we also have implemented the method responsible for instantiating\na new `Stack` object, which is the `init()` method.\n\nBut now, we need to implement also the method responsible for destroying\na `Stack` object. In Zig, this task is commonly associated with the method\nnamed `deinit()`. Most struct objects in Zig have such method, and it\nis commonly nicknamed \"the destructor method\".\n\nIn theory, all we have to do to destroy the `Stack` object is to make\nsure that we free the allocated memory for the underlying array, using\nthe allocator object that is stored inside the `Stack` object.\nThis is what the `deinit()` method below is doing.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn deinit(self: *Stack) void {\n    self.allocator.free(self.items);\n}\n```\n:::\n\n\n\n\n\n\n\n## Making it generic\n\nNow that we have implemented the basic skeleton of our stack data structure,\nwe can now focus on discussing how can we make it generic. How can we make\nthis basic skeleton to work not only with `u32` values, but also, with any other\ndata type we want?\nFor example, we might need to create a stack object to store `User` values\nin it. How can we make this possible? The answer lies on the use of generics\nand `comptime`.\n\nAs I described at @sec-generic-struct, the basic idea is to write a generic\nfunction that returns a struct definition as output.\nIn theory, we do not need much to transform our `Stack` struct into a generic\ndata structure. All that we need to do is to transform the underlying array\nof the stack into a generic array.\n\nIn other words, this underlying array needs to be a \"chameleon\". It needs to adapt,\nand transform it into an array of any data type that we want. For example, if we need to create\na stack that will store `u8` values, then, this underlying array needs to be\na `u8` array (i.e. `[]u8`). But if we need to store `User` values instead, then,\nthis array needs to be a `User` array (i.e. `[]User`). Etc.\n\nWe do that by using a generic function. Because a generic function can receive a data type\nas input, and we can pass this data type to the struct definition of our `Stack` object.\nTherefore, we can use the generic function to create a `Stack` object that can store\nthe data type we want. If we want to create a stack structure that stores `User` values,\nwe pass the `User` data type to this generic function, and it will create for us\nthe struct definition that describes a `Stack` object that can store `User` values in it.\n\nLook at the code example below. I have omitted some parts of the `Stack` struct definition\nfor brevity reasons. However, if a specific part of our `Stack` struct is not exposed here\nin this example, then it is because this part did not change from the previous example.\nIt remains the same.\n\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn Stack(comptime T: type) type {\n    return struct {\n        items: []T,\n        capacity: usize,\n        length: usize,\n        allocator: Allocator,\n        const Self = @This();\n\n        pub fn init(allocator: Allocator,\n                    capacity: usize) !Stack(T) {\n            var buf = try allocator.alloc(T, capacity);\n            return .{\n                .items = buf[0..],\n                .capacity = capacity,\n                .length = 0,\n                .allocator = allocator,\n            };\n        }\n\n        pub fn push(self: *Self, val: T) !void {\n        // Truncate the rest of the struct\n    };\n}\n```\n:::\n\n\n\n\nNotice that we have created a function in this example named `Stack()`. This function\ntakes a type as input, and passes this type to the struct definition of our\n`Stack` object. The data member `items` is now, an array of type `T`, which is the\ndata type that we have provided as input to the function. The function argument\n`val` in the `push()` function is now a value of type `T` too.\n\nWe can just provide a data type to this function, and it will create a definition of a\n`Stack` object that can store values of the data type that we have provided. In the example below, we are creating\nthe definition of a\n`Stack` object that can store `u8` values in it. This definition is stored at the `Stacku8` object.\nThis `Stacku8` object becomes our new struct, it is the struct that we are going to use\nto create our `Stack` object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst Stacku8 = Stack(u8);\nvar stack = try Stacku8.init(allocator, 10);\ndefer stack.deinit();\ntry stack.push(1);\ntry stack.push(2);\ntry stack.push(3);\ntry stack.push(4);\ntry stack.push(5);\ntry stack.push(6);\n\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\"Stack capacity: {d}\\n\", .{stack.capacity});\n\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\n    \"Stack state: {any}\\n\",\n    .{stack.items[0..stack.length]}\n);\n```\n:::\n\n\n\n\n```\nStack len: 6\nStack capacity: 10\nStack len: 5\nStack len: 4\nStack state: { 1, 2, 3, 4, 0, 0, 0, 0, 0, 0 }\n```\n\nEvery generic data structure in the Zig Standard Library (`ArrayList`, `HashMap`, `SinlyLinkedList`, etc.)\nis implemented through this logic. They use a generic function to create the struct definition that can work\nwith the data type that you provided as input.\n\n\n\n\n## Conclusion\n\nThe full source code of the stack structure discussed in this chapter is freely available at the official\nrepository of this book. Just checkout the [`stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig)[^zig-stack]\nfor the `u32` version of our stack,\nand the [`generic_stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig)[^zig-stack2]\nfor the generic version, available inside the `ZigExamples` folder of the repository.\n\n\n[^zig-stack]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig>\n[^zig-stack2]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig>\n\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/12-file-op/execute-results/html.json b/_freeze/Chapters/12-file-op/execute-results/html.json
index d1200279..4bb8d71f 100644
--- a/_freeze/Chapters/12-file-op/execute-results/html.json
+++ b/_freeze/Chapters/12-file-op/execute-results/html.json
@@ -3,9 +3,7 @@
   "result": {
     "engine": "knitr",
     "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n\n# Filesystem and Input/Output (IO) {#sec-filesystem}\n\nIn this chapter we are going to discuss how to use the cross-platform structs and functions\nfrom the Zig Standard Library that can execute filesystem operations. Most of these functions and structs\ncomes from the `std.fs` module.\n\nWe are also going to talk about Input/Output (also known as IO) operations in Zig. Most of\nthese operations are made by using the structs and functions from `std.io` module, which defines\nfile descriptors for the *standard channels* of your system (`stdout` and `stdin`), and also,\nfunctions to create and use I/O streams.\n\n\n## Input/Output basics {#sec-io-basics}\n\nIf you have some experience in a high-level language, you have certainly used\nthese input and output functionalities before in this language. In other words, you certainly have\nbeen in a situation where you needed to sent some output to the user, or, to receive an input\nfrom the user.\n\nFor example, in Python we can receive some input from the user by using the `input()` built-in\nfunction. But we can also print (or \"show\") some output to the user by using the `print()`\nbuilt-in function. So yes, if you have programmed before in Python, you certainly have\nused these functions once before.\n\nBut do you know how these functions relate back to your operating system (OS)? How exactly\nthey are interacting with the resources of your OS to receive or sent some input/output.\nIn essence, these input/output functions from high-level languages are just abstractions\nover the *standard output* and *standard input* channels of your operating system.\n\nThis means that we receive an input, or send some output, through the operating system.\nIt is the OS that makes the bridge between the user and your program. Your program\ndoes not have a direct access to the user. It is the OS that intermediates every\nmessage exchanged between your program and the user.\n\nThe *standard output* and *standard input* channels of your OS are commonly known as the\n`stdout` and `stdin` channels of your OS, respectively. In some contexts, they are also\ncalled the *standard output device* and the *standard input device*. As the name suggests,\nthe *standard output* is the channel through which output flows, while the *standard input*\nis the channel in which input flows.\n\nFurthermore, OS's also normally create a dedicated channel for exchanging error messages, which is known as the\n*standard error* channel, or, the `stderr` channel. This is the channel to which error and warning messages\nare usually sent to. These are the messages that are normally displayed in red-like or orange-like colors\ninto your terminal.\n\nNormally, every OS (e.g. Windows, macOS, Linux, etc.) creates a dedicated and separate set of\n*standard output*, *standard error* and *standard input* channels for every single program (or process) that runs in your computer.\nThis means that every program you write have a dedicated `stdin`, `stderr` and `stdout` that are separate\nfrom the `stdin`, `stderr` and `stdout` of other programs and processes that are currently running.\n\nThis is a behaviour from your OS. This does not come from the programming language that you are using.\nBecause as I sad earlier, input and output in programming languages, especially\nin high-level ones, are just a simple abstraction over the `stdin`, `stderr` and `stdout` from your current OS.\nThat is, your OS is the intermediary between every input/output operation made in your program,\nregardless of the programming language that you are using.\n\n\n### The writer and reader pattern {#sec-writer-reader}\n\nIn Zig, there is a pattern around input/output (IO). I (the author of this book) don't know if there\nis an official name for this pattern. But here, in this book, I will call it the \"writer and reader pattern\".\nIn essence, every IO operation in Zig is made through either a `GenericReader` or a `GenericWriter` object[^gen-zig].\n\nThese two data types come from the `std.io` module of the Zig Standard Library. As their names suggests, a\n`GenericReader` is an object that offers tools to read data from \"something\" (or \"somewhere\"), while a `GenericWriter`\noffers tools to write data into this \"something\". This \"something\" might be different things: like a\nfile that exists in your filesystem; or, it might be a network socket in your system[^sock]; or,\na continuous stream of data, like a standard input device from your system, that might be constantly\nreceiving new data from users, or, as another example, a live chat in a game that is constantly\nreceiving and displaying new messages from the players of the game.\n\n[^gen-zig]: Previously, these objects were known as the `Reader` and `Writer` objects.\n[^sock]: The socket objects that we have created at @sec-create-socket, are examples of network sockets.\n\nSo, if you want to **read** data from something, or somewhere, it means that you need to use a `GenericReader` object.\nBut if you need instead, to **write** data into this \"something\", then, you need to use a `GenericWriter` object instead.\nBoth of these objects are normally created from a file descriptor object. More specifically, through the `writer()` and `reader()`\nmethods of this file descriptor object. If you are not familiar with this type of object, go to the next section.\n\nEvery `GenericWriter` object have methods like `print()`, which allows you to write/send a formatted string\n(i.e. this formatted string is like a `f` string in Python, or, similar to the `printf()` C function)\ninto the \"something\" (file, socket, stream, etc.) that you are using. It also have a `writeAll()` method, which allows you to\nwrite a string, or, an array of bytes into the \"something\".\n\nLikewise, every `GenericReader` object have methods like `readAll()`, which allows you to read the\ndata from the \"something\" (file, socket, stream, etc.) until it fills a particular array (i.e. a \"buffer\") object.\nIn other words, if you provide an array object of 300 `u8` values to `readAll()`, then, this method attempts to read 300 bytes\nof data from the \"something\", and it stores them into the array object that you have provided.\n\nWe also have other methods, like the `readAtLeast()` method, which allows you to specify how\nmany bytes exactly you want to read from the \"something\". In more details, if you give the\nnumber $n$ as input to this method, then, it will attempt to read at least $n$ bytes of data\nfrom the \"something\". The \"something\" might have less than $n$ bytes of data available for you\nto read, so, it is not guaranteed that you will get precisely $n$ bytes as result.\n\nAnother useful method is `readUntilDelimiterOrEof()`. In this method, you specify a \"delimiter character\".\nThe idea is that this function will attempt to read as many bytes of data as possible from the \"something\",\nuntil it encounters the end of the stream, or, it encounters the \"delimiter character\" that you have specified.\n\nIf you don't know exactly how many bytes will come from the \"something\", you may find the `readAllAlloc()` method\nuseful. In essence, you provide an allocator object to this method, so that it can allocate more space if needed.\nAs consequence, this method will try to read all bytes of the \"something\", and, if it runs out of space at some point\nduring the \"reading process\", it uses the allocator object to allocate more space to continue reading the bytes.\nAs result, this method returns a slice to the array object containing all the bytes read.\n\nThis is just a quick description of the methods present in these types of objects. But I recommend you\nto read the official docs, both for\n[`GenericWriter`](https://ziglang.org/documentation/master/std/#std.io.GenericWriter)[^gen-write] and\n[`GenericReader`](https://ziglang.org/documentation/master/std/#std.io.GenericReader)[^gen-read].\nI also think it is a good idea to read the source code of the modules in the Zig Standard Library\nthat defines the methods present in these objects, which are the\n[`Reader.zig`](https://github.com/ziglang/zig/blob/master/lib/std/io/Reader.zig)[^mod-read]\nand [`Writer.zig`]()[^mod-write].\n\n[^gen-read]: <https://ziglang.org/documentation/master/std/#std.io.GenericReader>.\n[^gen-write]: <https://ziglang.org/documentation/master/std/#std.io.GenericWriter>.\n[^mod-read]: <https://github.com/ziglang/zig/blob/master/lib/std/io/Reader.zig>.\n[^mod-write]: <https://github.com/ziglang/zig/blob/master/lib/std/io/Writer.zig>.\n\n\n\n### Introducing file descriptors {#sec-file-descriptor}\n\nA \"file descriptor\" object is a core component behind every IO operation that is made in any operating system (OS).\nSuch object is an identifier for a particular input/output (IO) resource from your OS [@wiki_file_descriptor].\nIt describes and identifies this particular resource. An IO resource might be:\n\n- an existing file in your filesystem.\n- an existing network socket.\n- other types of stream channels.\n- a pipeline (or just \"pipe\") in your terminal[^pipes].\n\n[^pipes]: A pipeline is a mechanism for inter-process communication, or, inter-process IO. You could also interpret a pipeline as a \"set of processes that are chained together, through the standard input/output devices of the system\". At Linux for example, a pipeline is created inside a terminal, by connecting two or more terminal commands with the \"pipe\" character (`|`).\n\nFrom the bullet points listed above, we know that although the term \"file\" is present,\na \"file descriptor\" might describe something more than just a file.\nThis concept of a \"file descriptor\" comes from the Portable Operating System Interface (POSIX) API,\nwhich is a set of standards that guide how operating systems across the world should be implemented,\nto maintain compatibility between them.\n\nA file descriptor not only identifies the input/output resource that you are using to receive or send some data,\nbut it also describes where this resource is, and also, which IO mode this resource is currently using.\nFor example, this IO resource might be using only the \"read\" IO mode, which means that this resource\nis open to \"read operations\", while \"write operations\" are not authorized.\nThese IO modes are essentially the modes that you provide to the argument `mode`\nfrom the `fopen()` C function, and also, from the `open()` Python built-in function.\n\nIn C, a \"file descriptor\" is a `FILE` pointer, but, in Zig, a file descriptor is a `File` object.\nThis data type (`File`) is described in the `std.fs` module of the Zig Standard Library.\nWe normally don't create a `File` object directly in our Zig code. Instead, we normally get such object as result when we\nopen an IO resource. In other words, we normally ask our OS to open a particular IO resource for us,\nand, if the OS do open successfully this IO resource, the OS normally handles back to us\na file descriptor to this particular IO resource.\n\nSo you usually get a `File` object by using functions and methods from the Zig Standard Library\nthat asks the OS to open some IO resource, like the `openFile()` method that opens a file in the\nfilesystem. The `net.Stream` object that we have created at @sec-create-socket is also a type of\nfile descriptor object.\n\n\n### The *standard output*\n\nYou already saw across this book, how can we access and use specifically the `stdout` in Zig\nto send some output to the user.\nFor that, we use the `getStdOut()` function from the `std.io` module. This function returns\na file descriptor that describes the `stdout` channel of your current OS. Through this file\ndescriptor object, we can read from or write stuff to the `stdout` of our program.\n\nAlthough we can read stuff recorded into the `stdout` channel, we normally only\nwrite to (or \"print\") stuff into this channel. The reason is very similar to what we discussed at\n@sec-read-http-message, when we were discussing what \"reading from\" versus \"writing to\" the connection\nobject from our small HTTP Server project would mean.\n\nWhen we write stuff into a channel, we are essentially sending data to the other end of this channel.\nIn contrast, when we read stuff from this channel, we are essentially reading the data that was sent\nthrough this channel. Since the `stdout` is a channel to send output to the user, the key verb here\nis **send**. We want to send something to someone, and, as consequence, we want to **write** something\ninto some channel.\n\nThat is why, when we use `getStdOut()`, most of the times, we also use the `writer()` method from the `stdout` file descriptor,\nto get access to a writer object that we can use to write stuff into this `stdout` channel.\nMore specifically, this `writer()` method returns a `GenericWriter` object. One of the\nmain methods of this `GenericWriter` object is the `print()` method that we have used\nbefore to write (or \"print\") a formatted string into the `stdout` channel.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    try stdout.writeAll(\n        \"This message was written into stdout.\\n\"\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nThis message was written into stdout.\n```\n\n\n:::\n:::\n\n\n\n\n\n\nThis `GenericWriter` object is like any other generic writer object that you would normally get from a file descriptor object.\nSo, the same methods from a generic writer object that you would use while writing files to the filesystem for example, you could also\nuse them here, from the file descriptor object of `stdout`, and vice-versa.\n\n\n### The *standard input*\n\nYou can access the *standard input* (i.e. `stdin`) in Zig by using the `getStdIn()` function from the `std.io` module.\nLike its brother (`getStdOut()`), this function also returns a file descriptor object that describes the `stdin` channel\nof your OS.\n\nBecause we want to receive some input from the user, the key verb here becomes **receive**, and, as consequence,\nwe usually want to **read** data from the `stdin` channel, instead of writing data into it. So, we normally use\nthe `reader()` method of the file descriptor object returned by `getStdIn()`, to get access to a `GenericReader`\nobject that we can use to read data from `stdin`.\n\nIn the example below, we are creating a small buffer capable of holding 20 characters. Then, we try to read\nthe data from the `stdin` with the `readUntilDelimiterOrEof()` method, and save this data into the `buffer` object.\nAlso notice that we are reading the data from the `stdin` until we hit a new line character (`'\\n'`).\n\nIf you execute this program, you will notice that it stops the execution, ands start to wait indefinitely\nfor some input from the user. In other words, you need to type your name into the terminal, and then, you press Enter to\nsend your name to `stdin`. After you send your name to `stdin`, the program reads this input, and continues with the execution,\nby printing the given name to `stdout`. In the example below, I typed my name (Pedro) into the terminal, and then, pressed Enter.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst stdin = std.io.getStdIn().reader();\npub fn main() !void {\n    try stdout.writeAll(\"Type your name\\n\");\n    var buffer: [20]u8 = undefined;\n    @memset(buffer[0..], 0);\n    _ = try stdin.readUntilDelimiterOrEof(buffer[0..], '\\n');\n    try stdout.print(\"Your name is: {s}\\n\", .{buffer});\n}\n```\n:::\n\n\n\n\n```\nType your name\nYour name is: Pedro\n\n```\n\n\n### The *standard error*\n\nThe *standard error* (a.k.a. the `stderr`) works exactly the same as `stdout` and `stdin`.\nYou just call the `getStdErr()` function from the `std.io` module, and you get the file descriptor to `stderr`.\nIdeally, you should write only error or warning messages to `stderr`, because this is\nthe purpose of this channel.\n\n\n\n\n\n## Buffered IO\n\nAs we described at @sec-io-basics, input/output (IO) operations are made directly by the operating system.\nIt is the OS that manages the IO resource that you want to use for your IO operations.\nThe consequence of this fact is that IO operations are heavily based on system calls (i.e. calling the operating system directly).\n\nJust to be clear, there is nothing particularly wrong with system calls. We use them all the time on\nany serious codebase written in any low-level programming language. However, system calls are\nalways orders of magnitude slower than many different types of operations.\n\nSo is perfectly fine to use a system call once in a while. But when these system calls are used often,\nyou can clearly notice most of the time the loss of performance in your application. So, the good rule of thumbs\nis to use a system call only when it is needed, and also, only in infrequent situations, to reduce\nthe number of system calls performed to a minimum.\n\n\n### Understanding how buffered IO works\n\nBuffered IO is a strategy to achieve better performance. It is used to reduce the number of system calls made by IO operations, and, as\nconsequence, achieve a much higher performance. At @fig-unbuffered-io and @fig-buffered-io you can find two different diagrams\nwhich presents the difference between read operations performed in an unbuffered IO environment versus a buffered IO environment.\n\nTo give a better context to these diagrams, let's suppose that we have a text file that contains the famous Lorem ipsum text[^lorem]\nin our filesystem. Let's also suppose that these diagrams at @fig-unbuffered-io and @fig-buffered-io\nare showing the read operations that we are performing to read the Lorem ipsum text from this text file.\nThe first thing you will notice when looking at these diagrams, is that in an unbuffered environment\nthe read operations leads to many system calls.\nMore precisely, in the diagram exposed at @fig-unbuffered-io we get one system call per each byte that we read from the text file.\nOn the other hand, at @fig-buffered-io we have only one system call at the very beginning.\n\nWhen we use a buffered IO system, at the first read operation we perform, instead of sending one single byte directly\nto our program, the OS first sends a chunk of bytes from the file to a buffer object (i.e. an array).\nThis chunk of bytes are cached/stored inside this buffer object.\n\nTherefore, from now on, for every new read operation that you perform, instead of making a new system call to ask\nfor the next byte in the file to the OS, this read operation is redirected to the buffer object, that have\nthis next byte already cached and ready to go.\n\n\n[^lorem]: <https://www.lipsum.com/>.\n\n\n![Unbuffered IO](./../Figures/unbuffered-io.png){#fig-unbuffered-io width=60%}\n\n![Buffered IO](./../Figures/buffered-io.png){#fig-buffered-io}\n\n\n\nThis is the basic logic behind buffered IO systems. The size of the buffer object depends on multiple factors. But it is usually\nequal to the size of a full page of memory (4096 bytes). If we follow this logic, then, the OS reads the first 4096 bytes\nof the file and caches it into the buffer object. As long as your program does not consume all of these 4096 bytes from the buffer,\nyou will not create new system calls.\n\nHowever, as soon as you consume all of these 4096 bytes from the buffer, it means that there is no bytes left in the buffer.\nIn this situation, a new system call is made to ask the OS to send the next 4096 bytes in the file, and once again,\nthese bytes are cached into the buffer object, and the cycle starts once again.\n\n\n### Buffered IO across different languages\n\nIO operations made through a `FILE` pointer in C are buffered\nby default, so, at least in C, you don't need to worry about this subject. But in contrast, IO operations in both Rust and Zig are not\nbuffered depending on which functions from the standard libraries that you are using.\n\nFor example, in Rust, buffered IO is implemented through the `BufReader` and `BufWriter` structs, while in Zig, it is implemented\nthrough the `BufferedReader` and `BufferedWriter` structs.\nSo any IO operation that you perform through the `GenericWriter` and `GenericReader` objects\nthat I presented at @sec-writer-reader are not buffered, which means that these objects\nmight create a lot of system calls depending on the situation.\n\n\n### Using buffered IO in Zig\n\nUsing buffered IO in Zig is actually very easy. All you have to do is to just\ngive the `GenericWriter` object to the `bufferedWriter()` function, or, to give the `GenericReader`\nobject to the `bufferedReader()` function. These functions come from the `std.io` module,\nand they will construct the `BufferedWriter` or `BufferedReader` object for you.\n\nAfter you create this new `BufferedWriter` or `BufferedReader` object, you can call the `writer()`\nor `reader()` method of this new object, to get access to a new (and buffered) generic reader or\ngeneric writer.\n\nLet's describe the process once again. Every time that you have a file descriptor object, you first get the generic writer or generic reader\nobject from it, by calling the `writer()` or `reader()` methods of this file descriptor object.\nThen, you provide this generic writer or generic reader to the `bufferedWriter()` or `bufferedReader()`\nfunction, which creates a new `BufferedWriter` or `BufferedReader` object. Then, you call\nthe `writer()` or `reader()` methods of this buffered writer or buffered reader object,\nwhich gives you access to a generic writer or a generic reader object that is buffered.\n\nTake this program as an example. This program is demonstrating the process exposed at @fig-buffered-io.\nWe are simply opening a text file that contains the Lorem ipsum text, and then, we create a buffered IO reader object\nat `bufreader`, and we use this `bufreader` object to read the contents of this file into a buffer object, then,\nwe end the program by printing this buffer to `stdout`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar file = try std.fs.cwd().openFile(\n    \"ZigExamples/file-io/lorem.txt\", .{}\n);\ndefer file.close();\nvar buffered = std.io.bufferedReader(file.reader());\nvar bufreader = buffered.reader();\n\nvar buffer: [1000]u8 = undefined;\n@memset(buffer[0..], 0);\n\n_ = try bufreader.readUntilDelimiterOrEof(\n    buffer[0..], '\\n'\n);\ntry stdout.print(\"{s}\\n\", .{buffer});\n```\n:::\n\n\n\n\n```\nLorem ipsum dolor sit amet, consectetur\nadipiscing elit. Sed tincidunt erat sed nulla ornare, nec\naliquet ex laoreet. Ut nec rhoncus nunc. Integer magna metus,\nultrices eleifend porttitor ut, finibus ut tortor. Maecenas\nsapien justo, finibus tincidunt dictum ac, semper et lectus.\nVivamus molestie egestas orci ac viverra. Pellentesque nec\narcu facilisis, euismod eros eu, sodales nisl. Ut egestas\nsagittis arcu, in accumsan sapien rhoncus sit amet. Aenean\nneque lectus, imperdiet ac lobortis a, ullamcorper sed massa.\nNullam porttitor porttitor erat nec dapibus. Ut vel dui nec\nnulla vulputate molestie eget non nunc. Ut commodo luctus ipsum,\nin finibus libero feugiat eget. Etiam vel ante at urna tincidunt\nposuere sit amet ut felis. Maecenas finibus suscipit tristique.\nDonec viverra non sapien id suscipit.\n```\n\nDespite being a buffered IO reader, this `bufreader` object is similar to any other `GenericReader` object,\nand have the exact same methods. So, although these two types of objects perform very different IO operations,\nthey have the same interface, so you, the programmer, can interchangeably use them\nwithout the need to change anything in your source code.\nSo a buffered IO reader or a buffered IO writer objects have the same methods than its generic and unbuffered brothers,\ni.e. the generic reader and generic writer objects that I presented at @sec-writer-reader.\n\n::: {.callout-tip}\nIn general, you should always use a buffered IO reader or a buffered IO writer object to perform\nIO operations in Zig. Because they deliver better performance to your IO operations.\n:::\n\n\n## Filesystem basics\n\nNow that we have discussed the basics around Input/Output operations in Zig, we need to\ntalk about the basics around filesystems, which is another core part of any operating system.\nAlso, filesystems are related to input/output, because the files that we store and create in our\ncomputer are considered an IO resource, as we described at @sec-file-descriptor.\n\n\n### The concept of current working directory (CWD)\n\nThe working directory is the folder on your computer where you are currently rooted at.\nIn other words, it is the folder that your program is currently looking at.\nTherefore, whenever you are executing a program, this program is always working with\na specific folder on your computer. It is always in this folder that the program will initially\nlook for the files you require, and it is also in this folder that the program\nwill initially save all the files you ask it to save.\n\nThe working directory is determined by the folder from which you invoke your program\nin the terminal. In other words, if you are in the terminal of your OS, and you\nexecute a binary file (i.e. a program) from this terminal, the folder to which your terminal\nis pointing at is the current working directory of your program that is being executed.\n\nAt @fig-cwd we have an example of me executing a program from the terminal. We are executing\nthe program outputted by the `zig` compiler by compiling the Zig module named `hello.zig`.\nThe CWD in this case is the `zig-book` folder. In other words, while the `hello.zig` program\nis executing, it will be looking at the `zig-book` folder, and any file operation that we perform\ninside this program, will be using this `zig-book` folder as the \"starting point\", or, as the \"central focus\".\n\n![Executing a program from the terminal](./../Figures/cwd.png){#fig-cwd}\n\nJust because we are rooted inside a particular folder (in the case of @fig-cwd, the `zig-book` folder) of our computer,\nit doesn't mean that we cannot access or write resources in other locations of our computer.\nThe current working directory (CWD) mechanism just defines where your program will look first\nfor the files you ask for. This does not prevent you from accessing files that are located\nelsewhere on your computer. However, to access any file that is in a folder other than your\ncurrent working directory, you must provide a path to that file or folder.\n\n\n### The concept of paths\n\nA path is essentially a location. It points to a location in your filesystem. We use\npaths to describe the location of files and folders in our computer.\nOne important aspect about paths is that they are always written inside strings,\ni.e. they are always provided as text values.\n\nThere are two types of paths that you can provide to any program in any OS: a relative path, or an absolute path.\nAbsolute paths are paths that start at the root of your filesystem, and go all the way to the file name or the specific folder\nthat you are referring to. This type of path is called absolute, because it points to an unique and absolute location on your computer.\nThat is, there is no other existing location on your computer that corresponds to this path. It is an unique identifier.\n\nIn Windows, an absolute path is a path that starts with a hard disk identifier (e.g. `C:/Users/pedro`).\nOn the other hand, absolute paths in Linux and macOS, are paths that start with a forward slash character (e.g. `/usr/local/bin`).\nNotice that a path is composed by \"segments\". Each segment is connected to each other by a slash character (`\\` or `/`).\nOn Windows, the backward slash (`\\`) is normally used to connect the path segments. While on Linux and macOS, the forward\nslash (`/`) is the character used to connect path segments.\n\nA relative path is a path that start at the CWD. In other words, a relative path is\n\"relative to the CWD\". The path used to access the `hello.zig` file at @fig-cwd is an example of a relative path. This path\nis reproduced below. This path begins at the CWD, which in the context of @fig-cwd, is the `zig-book` folder,\nthen, it goes to the `ZigExamples` folder, then, into `zig-basics`, then, to the `hello.zig` file.\n\n```\nZigExamples/zig-basics/hello_world.zig\n```\n\n\n### Path wildcards\n\nWhen providing paths, especially relative paths, you have the option of using a *wildcard*.\nThere are two commonly used *wildcards* in paths, which are \"one period\" (.) and \"two periods\" (..).\nIn other words, these two specific characters have special meanings when used in paths,\nand can be used on any operating system (Mac, Windows, Linux, etc.). That is, they\nare \"cross platform\".\n\nThe \"one period\" represents an alias for the current directory.\nThis means that the relative paths `\"./Course/Data/covid.csv\"` and `\"Course/Data/covid.csv\"` are equivalent.\nOn the other hand, the \"two periods\" refers to the previous directory.\nFor example, the path `\"Course/..\"` is equivalent to the path `\".\"`, that is, the current working directory.\n\nTherefore, the path `\"Course/..\"` refers to the folder before the `Course` folder.\nAs another example, the path `\"src/writexml/../xml.cpp\"` refers to the file `xml.cpp`\nthat is inside the folder before the `writexml` folder, which in this example is the `src` folder.\nTherefore, this path is equivalent to `\"src/xml.cpp\"`.\n\n\n\n\n## The CWD handler\n\nIn Zig, filesystem operations are usually made through a directory handler object.\nA directory handler in Zig is an object of type `Dir`, which is an object that describes\na particular folder in the filesystem of our computer.\nYou normally create a `Dir` object, by calling the `std.fs.cwd()` function.\nThis function returns a `Dir` object that points to (or, that describes) the\ncurrent working directory (CWD).\n\nThrough this `Dir` object, you can create new files, or modify, or read existing ones that are\ninside your CWD. In other words, a `Dir` object is the main entrypoint in Zig to perform\nmultiple types of filesystem operations.\nIn the example below, we are creating this `Dir` object, and storing it\ninside the `cwd` object. Although we are not using this object at this code example,\nwe are going to use it a lot over the next examples.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\n_ = cwd;\n```\n:::\n\n\n\n\n\n\n\n\n\n\n\n## File operations\n\n### Creating files {#sec-creating-files}\n\nWe create new files by using the `createFile()` method from the `Dir` object.\nJust provide the name of the file that you want to create, and this function will\ndo the necessary steps to create such file. You can also provide a relative path to this function,\nand it will create the file by following this path, which is relative to the CWD.\n\nThis function might return an error, so, you should use `try`, `catch`, or any of the other methods presented\nat @sec-error-handling to handle the possible error. But if everything goes well,\nthis `createFile()` method returns a file descriptor object (i.e. a `File` object) as result,\nthrough which you can add content to the file with the IO operations that I presented before.\n\nTake this code example below. In this example, we are creating a new text file\nnamed `foo.txt`. If the function `createFile()` succeeds, the object named `file` will contain a file descriptor\nobject, which we can use to write (or add) new content to the file, like we do in this example, by using\na buffered writer object to write a new line of text to the file.\n\nNow, a quick note, when we create a file descriptor object in C, by using a C function like `fopen()`, we must always close the file\nat the end of our program, or, as soon as we complete all operations that we wanted to perform\non the file. In Zig, this is no different. So everytime we create a new file, this file remains\n\"open\", waiting for some operation to be performed. As soon as we are done with it, we always have\nto close this file, to free the resources associated with it.\nIn Zig, we do this by calling the method `close()` from the file descriptor object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.createFile(\"foo.txt\", .{});\n// Don't forget to close the file at the end.\ndefer file.close();\n// Do things with the file ...\nvar fw = file.writer();\n_ = try fw.writeAll(\n    \"Writing this line to the file\\n\"\n);\n```\n:::\n\n\n\n\n\nSo, in this example we not only have created a file into the filesystem,\nbut we also wrote some data into this file, using the file descriptor object\nreturned by `createFile()`. If the file that you are trying to create\nalready exists in your filesystem, this `createFile()` call will\noverwrite the contents of the file, or, in other words, it will\nin erase all the contents of the existing file.\n\nIf you don't want this to happen, meaning, that you don't want to overwrite\nthe contents of the existing file, but you want to write data to this file anyway\n(i.e. you want to append data to the file), you should use the `openFile()`\nmethod from the `Dir` object.\n\nAnother important aspect about `createFile()` is that this method creates a file\nthat is not open to read operations by default. It means that you cannot read this file.\nYou are not allowed to.\nSo for example, you might want to write some stuff into this file at the beginning of the execution\nof your program. Then, at a future point in your program you might need to read what you\nwrote in this file. If you try to read data from this file, you will likely\nget a `NotOpenForReading` error as result.\n\n\nBut how can you overcome this barrier? How can you create a file that is open\nto read operations? All you have to do, is to set the `read` flag to true\nin the second argument of `createFile()`. When you set this flag to true,\nthen the file get's create with \"read permissions\", and, as consequence,\na program like this one below becomes valid:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.createFile(\n    \"foo.txt\",\n    .{ .read = true }\n);\ndefer file.close();\n\nvar fw = file.writer();\n_ = try fw.writeAll(\"We are going to read this line\\n\");\n\nvar buffer: [300]u8 = undefined;\n@memset(buffer[0..], 0);\ntry file.seekTo(0);\nvar fr = file.reader();\n_ = try fr.readAll(buffer[0..]);\ntry stdout.print(\"{s}\\n\", .{buffer});\n```\n:::\n\n\n\n\n\n```\nWe are going to read this line\n```\n\n\nIf you are not familiar with position indicators, you might not recognize the method\n`seekTo()`. If that is your case, do not worry,\nwe are going to talk more about this method at @sec-indicators. But essentially\nthis method is moving the position indicator back to the beginning of the file,\nso that we can read the contents of the file from the beginning.\n\n\n### Opening files and appending data to it\n\nOpening files is easy. Just use the `openFile()` method instead of `createFile()`.\nIn the first argument of `openFile()` you provide the path to the file that\nyou want to open. Then, on the second argument you provide the flags (or, the options)\nthat dictates how the file is opened.\n\nYou can see the full list of options for `openFile()` by visiting the documentation for\n[`OpenFlags`](https://ziglang.org/documentation/master/std/#std.fs.File.OpenFlags)[^oflags].\nBut the main flag that you will most certainly use is the `mode` flag.\nThis flag specifies the IO mode that the file will be using when it get's opened.\nThere are three IO modes, or, three values that you can provide to this flag, which are:\n\n- `read_only`, allows only read operations on the file. All write operations are blocked.\n- `write_only`, allows only write operations on the file. All read operations are blocked. \n- `read_write`, allows both write and read operations on the file.\n\n[^oflags]: <https://ziglang.org/documentation/master/std/#std.fs.File.OpenFlags>\n\nThese modes are similar to the modes that you provide to the `mode` argument of the\n`open()` Python built-in function[^py-open], or, the `mode` argument of the\n`fopen()` C function[^c-open].\nIn the code example below, we are opening the `foo.txt` text file with a `write_only` mode,\nand appending a new line of text to the end of the file. We use `seekFromEnd()` this time\nto guarantee that we are going to append the text to the end of the file. Once again, methods\nsuch as `seekFromEnd()` are described in more depth at @sec-indicators.\n\n[^py-open]: <https://docs.python.org/3/tutorial/inputoutput.html#reading-and-writing-files>\n[^c-open]: <https://www.tutorialspoint.com/c_standard_library/c_function_fopen.htm>\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.openFile(\n    \"foo.txt\", .{ .mode = .write_only }\n);\ndefer file.close();\ntry file.seekFromEnd(0);\nvar fw = file.writer();\n_ = try fw.writeAll(\"Some random text to write\\n\");\n```\n:::\n\n\n\n\n\n### Deleting files\n\nSometimes, we just need to delete/remove the files that we have.\nTo do that, we use the `deleteFile()` method. You just provide the path of the\nfile that you want to delete, and this method will try to delete the file located\nat this path.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.deleteFile(\"foo.txt\");\n```\n:::\n\n\n\n\n### Copying files\n\nTo copy existing files, we use the `copyFile()` method. The first argument in this method\nis the path to the file that you want to copy. The second argument is a `Dir` object, i.e. a directory handler,\nmore specifically, a `Dir` object that points to the folder in your computer where you want to\ncopy the file to. The third argument is the new path of the file, or, in other words, the new location\nof the file. The fourth argument is the options (or flags) to be used in the copy operation.\n\nThe `Dir` object that you provide as input to this method will be used to copy the file to\nthe new location. You may create this `Dir` object before calling the `copyFile()` method.\nMaybe you are planning to copy the file to a completely different location in your computer,\nso it might be worth to create a directory handler to that location. But if you are copying the\nfile to a subfolder of your CWD, then, you can just simply pass the CWD handler to this argument.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.copyFile(\n    \"foo.txt\",\n    cwd,\n    \"ZigExamples/file-io/foo.txt\",\n    .{}\n);\n```\n:::\n\n\n\n\n\n### Read the docs!\n\nThere are some other useful methods for file operations available at `Dir` objects,\nsuch as the `writeFile()` method, but I recommend you to read the docs for the\n[`Dir` type](https://ziglang.org/documentation/master/std/#std.fs.Dir)[^zig-dir]\nto explore the other available methods, since I already talked too much about them.\n\n\n[^zig-dir]: <https://ziglang.org/documentation/master/std/#std.fs.Dir>\n\n\n\n\n## Position indicators {#sec-indicators}\n\nA position indicator is like a type of cursor, or, an index. This \"index\" identifies the current\nlocation in the file (or, in the data stream) that the file descriptor object that you have\nis currently looking at.\nWhen you create a file descriptor, the position indicator starts at the beginning of the file,\nor, at the beginning of the stream. When you read from or write into the file (or socket, or data stream, etc.)\ndescribed by this file descriptor object, you end up moving the position indicator.\n\nIn other words, any IO operation have a common side effect, which is to move the position indicator.\nFor example, suppose that we have a file of 300 bytes total in size. If you\nread 100 bytes from the file, then, the position indicator moves 100 bytes forward. If you try\nto write 50 bytes into this same file, these 50 bytes will be written from the current\nposition indicated by the position indicator. Since the indicator is at a 100 bytes forward from\nthe beginning of the file, these 50 bytes would be written in the middle of the file.\n\nThis is why we have used the `seekTo()` method at the last code example presented at @sec-creating-files.\nWe have used this method to move the position indicator back to the beginning of the file, which\nwould make sure that we would write the text that we wanted to write from the beginning of the file,\ninstead of writing it from the middle of the file. Because before the write operation, we had\nperformed a read operation, which means that the position indicator was moved in this read operation.\n\nThe position indicators of a file descriptor object can be changed (or altered) by using the\n\"seek\" methods from this file descriptor, which are: `seekTo()`, `seekFromEnd()` and `seekBy()`.\nThese methods have the same effect, or, the same responsibility that the\n[`fseek()`](https://en.cppreference.com/w/c/io/fseek)[^c-fseek] C function.\n\n[^c-fseek]: <https://en.cppreference.com/w/c/io/fseek>\n\n\nConsidering that `offset` refers to the index that you provide as input to these \"seek\" methods,\nthe bullet points below summarises what is the effect of each of these methods.\nAs a quick note, in the case of `seekFromEnd()` and `seekBy()`, the `offset` provided can be either a\npositive or a negative index.\n\n- `seekTo()` will move the position indicator to the location that is `offset` bytes from the beginning of the file.\n- `seekFromEnd()` will move the position indicator to the location that is `offset` bytes from the end of the file.\n- `seekBy()` will move the position indicator to the location that is `offset` bytes from the current position in the file.\n\n\n\n\n\n\n\n## Directory operations\n\n### Iterating through the files in a directory\n\nOne of the most classic tasks related to filesystem is to be able\nto iterate through the existing files in a directory. To iterate over the\nfiles in a directory, we need to create an iterator object.\n\nYou can produce such iterator object by using either the `iterate()` or `walk()` methods\nof a `Dir` object. Both methods return an iterator object as output, which you can advance by using the\n`next()` method. The difference between these methods, is that `iterate()` returns a non-recursive iterator,\nwhile `walk()` does. It means that the iterator returned by `walk()` will not only iterate through\nthe files available in the current directory, but also, through the files from any subdirectory found\ninside the current directory.\n\nIn the example below, we are displaying the names of the files stored inside the\ndirectory `ZigExamples/file-io`. Notice that we had to open this directory through\nthe `openDir()` function. Also notice that we provided the flag `iterate` in the\nsecond argument of `openDir()`. This flag is important, because without this flag,\nwe would not be allowed to iterate through the files in this directory.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst dir = try cwd.openDir(\n    \"ZigExamples/file-io/\",\n    .{ .iterate = true }\n);\nvar it = dir.iterate();\nwhile (try it.next()) |entry| {\n    try stdout.print(\n        \"File name: {s}\\n\",\n        .{entry.name}\n    );\n}\n```\n:::\n\n\n\n\n```\nFile name: create_file_and_write_toit.zig\nFile name: create_file.zig\nFile name: lorem.txt\nFile name: iterate.zig\nFile name: delete_file.zig\nFile name: append_to_file.zig\nFile name: user_input.zig\nFile name: foo.txt\nFile name: create_file_and_read.zig\nFile name: buff_io.zig\nFile name: copy_file.zig\n```\n\n\n### Creating new directories\n\nThere are two methods that are important when it comes to\ncreating directories, which are `makeDir()` and `makePath()`.\nThe difference between these two methods is that `makeDir()` can\nonly create one single directory in the current directory in each call,\nwhile `makePath()` is capable of recursively create subdirectories in the same call.\n\n\nThis is why the name of this method is \"make path\". It will create as many\nsubdirectories as necessary to create the path that you provided as input.\nSo, if you provide the path `\"sub1/sub2/sub3\"` as input to this method,\nit will create three different subdirectories, `sub1`, `sub2` and `sub3`,\nwithin the same function call. In contrast, if you provided such path\nas input to `makeDir()`, you would likely get an error as result, since\nthis method can only create a single subdirectory.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.makeDir(\"src\");\ntry cwd.makePath(\"src/decoders/jpg/\");\n```\n:::\n\n\n\n\n### Deleting directories\n\nTo delete a directory, just provide the path to the directory that you want to delete\nas input to the `deleteDir()` method from a `Dir` object. In the example below,\nwe are deleting the `src` directory that we have just created in the previous example.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.deleteDir(\"src\");\n```\n:::\n\n\n\n\n\n## Conclusion\n\nIn this chapter, I have described how to perform in Zig the most common filesystem and IO operations.\nBut you might feel the lack of some other, less common, operation in this chapter, such as: how to rename files,\nor how to open a directory, or how to create symbolic links, or how to use `access()` to test if a particular\npath exists in your computer. But for all of these less common tasks, I recommend you to read\nthe documentation of the [`Dir` type](https://ziglang.org/documentation/master/std/#std.fs.Dir)[^zig-dir]\n, since you can find a good description of these cases there.\n\n\n\n\n",
-    "supporting": [
-      "12-file-op_files"
-    ],
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/index/execute-results/html.json b/_freeze/index/execute-results/html.json
index 94307194..b3df0c6d 100644
--- a/_freeze/index/execute-results/html.json
+++ b/_freeze/index/execute-results/html.json
@@ -3,9 +3,7 @@
   "result": {
     "engine": "knitr",
     "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy a PDF, eBook or a physical copy\nof the book, either at Amazon, or at Leanpub:\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://leanpub.com/introductiontozigaproject-basedbook\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Leanpub!\n    </button>\n</a>\n\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e. it is open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.\nCurrently, he is a Data Platform Engineer at [Blip](https://www.blip.ai/en/)[^blip], and\na Databricks Certified Associate Developer for Apache Spark 3.0.\n\n[^blip]: <https://www.blip.ai/en/>\n\n\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nBrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer who loves to learn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2025 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n\n- System version: Linux, 6.8.0-52-generic, NA, x86_64.\n- Zig version: 0.14.0-dev.3046+08d661fcf.\n- Quarto version: 1.5.57.\n\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2025,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {February},\n    edition = {2},\n    year = {2025},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang), Tommaso Ricci (\\@Zorgatone), Primo Sabatini (\\@primos63), Santiago Fernandez (\\@santif), Hamza Wahed (\\@HamzaWahed), mwilbur (\\@mwilbur), Dima Budaragin (\\@dbud), Jorge Jímenez (\\@jorge-j1m), Alexander (\\@alexwheezy), Maarten Coopens (\\@maarteNNNN), Niklas Johansson (\\@Raphexion)\n",
-    "supporting": [
-      "index_files"
-    ],
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/docs/Chapters/03-structs.html b/docs/Chapters/03-structs.html
index 69a800e7..9a0d90ff 100644
--- a/docs/Chapters/03-structs.html
+++ b/docs/Chapters/03-structs.html
@@ -927,7 +927,8 @@ <h2 data-number="2.5" class="anchored" data-anchor-id="sec-type-cast"><span clas
 <span id="cb49-6"><a href="#cb49-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(y) == <span class="dt">u32</span>);</span>
 <span id="cb49-7"><a href="#cb49-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file2ed34a8fc96.test_0...OKAll 1 tests passed.</code></pre>
+<pre><code>1/1 file9f8940318094.test_0...OKAll 1 tests passed
+  d.</code></pre>
 </div>
 </div>
 <p>This is the general way to perform type casting in Zig. But remember, <code>@as()</code> works only when casting is unambiguous and safe, and there are situations where these assumptions do not hold. For example, when casting an integer value into a float value, or vice-versa, it is not clear to the compiler how to perform this conversion safely.</p>
@@ -942,7 +943,7 @@ <h2 data-number="2.5" class="anchored" data-anchor-id="sec-type-cast"><span clas
 <span id="cb51-6"><a href="#cb51-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(y) == <span class="dt">f32</span>);</span>
 <span id="cb51-7"><a href="#cb51-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file2ed34bfb9fa5.test_0...OKAll 1 tests passed
+<pre><code>1/1 file9f8954828844.test_0...OKAll 1 tests passed
   d.</code></pre>
 </div>
 </div>
@@ -959,7 +960,7 @@ <h2 data-number="2.5" class="anchored" data-anchor-id="sec-type-cast"><span clas
 <span id="cb53-8"><a href="#cb53-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(u32_ptr) == *<span class="kw">const</span> <span class="dt">u32</span>);</span>
 <span id="cb53-9"><a href="#cb53-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file2ed324328e1f.test_0...OKAll 1 tests passed
+<pre><code>1/1 file9f8944ca02e1.test_0...OKAll 1 tests passed
   d.</code></pre>
 </div>
 </div>
diff --git a/docs/Chapters/03-unittests.html b/docs/Chapters/03-unittests.html
index e7ddd754..42c0c02b 100644
--- a/docs/Chapters/03-unittests.html
+++ b/docs/Chapters/03-unittests.html
@@ -323,7 +323,7 @@ <h2 data-number="8.1" class="anchored" data-anchor-id="introducing-the-test-bloc
 <span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect((a + b) == <span class="dv">4</span>);</span>
 <span id="cb1-7"><a href="#cb1-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file153713a3190e.test.testing simple sum...OKA
+<pre><code>1/1 filea5b06c1ec326.test.testing simple sum...OKA
   All 1 tests passed.</code></pre>
 </div>
 </div>
@@ -396,8 +396,8 @@ <h2 data-number="8.4" class="anchored" data-anchor-id="testing-errors"><span cla
 <span id="cb7-14"><a href="#cb7-14" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expectError(<span class="kw">error</span>.OutOfMemory, alloc_error(allocator));</span>
 <span id="cb7-15"><a href="#cb7-15" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file1537546f248.test.testing error...OKAll 1 t
-  tests passed.</code></pre>
+<pre><code>1/1 filea5b059c00874.test.testing error...OKAll 1 
+   tests passed.</code></pre>
 </div>
 </div>
 </section>
@@ -433,7 +433,7 @@ <h2 data-number="8.5" class="anchored" data-anchor-id="testing-simple-equalities
 <span id="cb11-7"><a href="#cb11-7" aria-hidden="true" tabindex="-1"></a>    );</span>
 <span id="cb11-8"><a href="#cb11-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file15377bbafb73.test.arrays are equal?...OKAl
+<pre><code>1/1 filea5b054e42b80.test.arrays are equal?...OKAl
   ll 1 tests passed.</code></pre>
 </div>
 </div>
diff --git a/docs/Chapters/09-error-handling.html b/docs/Chapters/09-error-handling.html
index 597d0a92..e026d192 100644
--- a/docs/Chapters/09-error-handling.html
+++ b/docs/Chapters/09-error-handling.html
@@ -469,7 +469,7 @@ <h3 data-number="10.1.3" class="anchored" data-anchor-id="casting-error-values">
 <span id="cb8-20"><a href="#cb8-20" aria-hidden="true" tabindex="-1"></a>    );</span>
 <span id="cb8-21"><a href="#cb8-21" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file10459ffd0e21.test.coerce error value...OKA
+<pre><code>1/1 filea64e1da1167c.test.coerce error value...OKA
   All 1 tests passed.</code></pre>
 </div>
 </div>
diff --git a/docs/Chapters/10-stack-project.html b/docs/Chapters/10-stack-project.html
index b81ac050..bd3e9cbb 100644
--- a/docs/Chapters/10-stack-project.html
+++ b/docs/Chapters/10-stack-project.html
@@ -370,8 +370,8 @@ <h3 data-number="12.1.1" class="anchored" data-anchor-id="applying-over-a-functi
 <span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a>    _ = twice(<span class="dv">5678</span>);</span>
 <span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file1105a40478a9d.test.test comptime...OKAll 1
-  1 tests passed.</code></pre>
+<pre><code>1/1 filea72d248f97f8.test.test comptime...OKAll 1 
+   tests passed.</code></pre>
 </div>
 </div>
 <p>But what if we provide a number that is not compile-time known to this function? For example, we might provide a different input value to this function depending on the target OS of our compilation process. The code example below demonstrates such case.</p>
@@ -426,8 +426,8 @@ <h3 data-number="12.1.2" class="anchored" data-anchor-id="applying-over-an-expre
 <span id="cb6-11"><a href="#cb6-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> <span class="kw">comptime</span> expect(fibonacci(<span class="dv">7</span>) == <span class="dv">13</span>);</span>
 <span id="cb6-12"><a href="#cb6-12" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file1105a31c0f24f.test.fibonacci...OKAll 1 tes
-  sts passed.</code></pre>
+<pre><code>1/1 filea72d3cf7abe2.test.fibonacci...OKAll 1 test
+  ts passed.</code></pre>
 </div>
 </div>
 <p>A lot of your Zig source code might be potentially executed at compile-time, because the <code>zig</code> compiler can figure it out the output of some expressions. Especially if these expressions depends only at compile-time known values. We have talked about this at <a href="01-memory.html#sec-compile-time" class="quarto-xref"><span>Section 3.1.1</span></a>.</p>
@@ -455,8 +455,8 @@ <h3 data-number="12.1.3" class="anchored" data-anchor-id="applying-over-a-block"
 <span id="cb8-15"><a href="#cb8-15" aria-hidden="true" tabindex="-1"></a>    _ = x;</span>
 <span id="cb8-16"><a href="#cb8-16" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file1105a37ca2b0d.test.fibonacci in a block...
-  .OKAll 1 tests passed.</code></pre>
+<pre><code>1/1 filea72d6353d586.test.fibonacci in a block...O
+  OKAll 1 tests passed.</code></pre>
 </div>
 </div>
 </section>
diff --git a/docs/search.json b/docs/search.json
index a0dbe2a7..1d2f1f9f 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -274,7 +274,7 @@
     "href": "Chapters/03-structs.html#sec-type-cast",
     "title": "2  Control flow, structs, modules and types",
     "section": "2.5 Type casting",
-    "text": "2.5 Type casting\nIn this section, I want to discuss type casting (or, type conversion) with you. We use type casting when we have an object of type “x”, and we want to convert it into an object of type “y”, i.e. we want to change the data type of the object.\nMost languages have a formal way to perform type casting. In Rust for example, we normally use the keyword as, and in C, we normally use the type casting syntax, e.g. (int) x. In Zig, we use the @as() built-in function to cast an object of type “x”, into an object of type “y”.\nThis @as() function is the preferred way to perform type conversion (or type casting) in Zig. Because it is explicit, and, it also performs the casting only if it is unambiguous and safe. To use this function, you just provide the target data type in the first argument, and, the object that you want cast as the second argument.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n\n1/1 file2ed34a8fc96.test_0...OKAll 1 tests passed.\n\n\nThis is the general way to perform type casting in Zig. But remember, @as() works only when casting is unambiguous and safe, and there are situations where these assumptions do not hold. For example, when casting an integer value into a float value, or vice-versa, it is not clear to the compiler how to perform this conversion safely.\nTherefore, we need to use specialized “casting functions” in such situations. For example, if you want to cast an integer value into a float value, then, you should use the @floatFromInt() function. In the inverse scenario, you should use the @intFromFloat() function.\nIn these functions, you just provide the object that you want to cast as input. Then, the target data type of the “type casting operation” is determined by the type annotation of the object where you are saving the results. In the example below, we are casting the object x into a value of type f32, because the object y, which is where we are saving the results, is annotated as an object of type f32.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n\n1/1 file2ed34bfb9fa5.test_0...OKAll 1 tests passed\n  d.\n\n\nAnother built-in function that is very useful when performing type casting operations is @ptrCast(). In essence, we use the @as() built-in function when we want to explicit convert (or cast) a Zig value/object from a type “x” to a type “y”, etc. However, pointers (we are going to discuss pointers in more depth in Chapter 6) are a special type of object in Zig, i.e. they are treated differently from “normal objects”.\nEverytime a pointer is involved in some “type casting operation” in Zig, the @ptrCast() function is used. This function works similarly to @floatFromInt(). You just provide the pointer object that you want to cast as input to this function, and the target data type is, once again, determined by the type annotation of the object where the results are being stored.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n\n1/1 file2ed324328e1f.test_0...OKAll 1 tests passed\n  d.",
+    "text": "2.5 Type casting\nIn this section, I want to discuss type casting (or, type conversion) with you. We use type casting when we have an object of type “x”, and we want to convert it into an object of type “y”, i.e. we want to change the data type of the object.\nMost languages have a formal way to perform type casting. In Rust for example, we normally use the keyword as, and in C, we normally use the type casting syntax, e.g. (int) x. In Zig, we use the @as() built-in function to cast an object of type “x”, into an object of type “y”.\nThis @as() function is the preferred way to perform type conversion (or type casting) in Zig. Because it is explicit, and, it also performs the casting only if it is unambiguous and safe. To use this function, you just provide the target data type in the first argument, and, the object that you want cast as the second argument.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n\n1/1 file9f8940318094.test_0...OKAll 1 tests passed\n  d.\n\n\nThis is the general way to perform type casting in Zig. But remember, @as() works only when casting is unambiguous and safe, and there are situations where these assumptions do not hold. For example, when casting an integer value into a float value, or vice-versa, it is not clear to the compiler how to perform this conversion safely.\nTherefore, we need to use specialized “casting functions” in such situations. For example, if you want to cast an integer value into a float value, then, you should use the @floatFromInt() function. In the inverse scenario, you should use the @intFromFloat() function.\nIn these functions, you just provide the object that you want to cast as input. Then, the target data type of the “type casting operation” is determined by the type annotation of the object where you are saving the results. In the example below, we are casting the object x into a value of type f32, because the object y, which is where we are saving the results, is annotated as an object of type f32.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n\n1/1 file9f8954828844.test_0...OKAll 1 tests passed\n  d.\n\n\nAnother built-in function that is very useful when performing type casting operations is @ptrCast(). In essence, we use the @as() built-in function when we want to explicit convert (or cast) a Zig value/object from a type “x” to a type “y”, etc. However, pointers (we are going to discuss pointers in more depth in Chapter 6) are a special type of object in Zig, i.e. they are treated differently from “normal objects”.\nEverytime a pointer is involved in some “type casting operation” in Zig, the @ptrCast() function is used. This function works similarly to @floatFromInt(). You just provide the pointer object that you want to cast as input to this function, and the target data type is, once again, determined by the type annotation of the object where the results are being stored.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n\n1/1 file9f8944ca02e1.test_0...OKAll 1 tests passed\n  d.",
     "crumbs": [
       "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
     ]
@@ -634,7 +634,7 @@
     "href": "Chapters/03-unittests.html",
     "title": "8  Unit tests",
     "section": "",
-    "text": "8.1 Introducing the test block\nIn Zig, unit tests are written inside a test declaration, or, how I prefer to call it, inside a test block. Every test block is written by using the keyword test. You can optionally use a string literal to write a label, which is responsible for identifying the specific group of unit tests that you are writing inside this specific test block.\nIn the example below, we are testing if the sum of two objects (a and b) is equal to 4. The expect() function from the Zig Standard Library is a function that receives a logical test as input. If this logical test results in true, then, the test passes. But if it results in false, then, the test fails.\nYou can write any Zig code you want inside a test block. Part of this code might be some necessary commands to setup your testing environment, or just initializing some objects that you need to use in your unit tests.\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest \"testing simple sum\" {\n    const a: u8 = 2;\n    const b: u8 = 2;\n    try expect((a + b) == 4);\n}\n\n1/1 file153713a3190e.test.testing simple sum...OKA\n  All 1 tests passed.\nYou can have multiple test blocks written on the same Zig module. Also, you can mix test blocks with your source code, with no problems or consequences. If you mix test blocks with your normal source code, when you execute the build, build-exe, build-obj or build-lib commands from the zig compiler that we exposed at Section 1.2.4, these test blocks are automatically ignored by the compiler.\nIn other words, the zig compiler builds and execute your unit tests only when you ask it to. By default, the compiler always ignore test blocks written in your Zig modules. The compiler normally checks only if there are any syntax errors in these test blocks.\nIf you take a look at the source code for most of the files present in the Zig Standard Library1, you can see that the test blocks are written together with the normal source code of the library. You can see this for example, at the array_list module2. So, the standard that the Zig developers decided to adopt is to keep their unit tests together with the source code of the functionality that they are testing.\nEach programmer might have a different opinion on this. Some of them might prefer to keep unit tests separate from the actual source code of their application. If that is your case, you can simply create a separate tests folder in your project, and start writing Zig modules that contains only unit tests (as you would normally do on a Python project with pytest, for example), and everything will work fine. It boils down to which is your preference here.",
+    "text": "8.1 Introducing the test block\nIn Zig, unit tests are written inside a test declaration, or, how I prefer to call it, inside a test block. Every test block is written by using the keyword test. You can optionally use a string literal to write a label, which is responsible for identifying the specific group of unit tests that you are writing inside this specific test block.\nIn the example below, we are testing if the sum of two objects (a and b) is equal to 4. The expect() function from the Zig Standard Library is a function that receives a logical test as input. If this logical test results in true, then, the test passes. But if it results in false, then, the test fails.\nYou can write any Zig code you want inside a test block. Part of this code might be some necessary commands to setup your testing environment, or just initializing some objects that you need to use in your unit tests.\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest \"testing simple sum\" {\n    const a: u8 = 2;\n    const b: u8 = 2;\n    try expect((a + b) == 4);\n}\n\n1/1 filea5b06c1ec326.test.testing simple sum...OKA\n  All 1 tests passed.\nYou can have multiple test blocks written on the same Zig module. Also, you can mix test blocks with your source code, with no problems or consequences. If you mix test blocks with your normal source code, when you execute the build, build-exe, build-obj or build-lib commands from the zig compiler that we exposed at Section 1.2.4, these test blocks are automatically ignored by the compiler.\nIn other words, the zig compiler builds and execute your unit tests only when you ask it to. By default, the compiler always ignore test blocks written in your Zig modules. The compiler normally checks only if there are any syntax errors in these test blocks.\nIf you take a look at the source code for most of the files present in the Zig Standard Library1, you can see that the test blocks are written together with the normal source code of the library. You can see this for example, at the array_list module2. So, the standard that the Zig developers decided to adopt is to keep their unit tests together with the source code of the functionality that they are testing.\nEach programmer might have a different opinion on this. Some of them might prefer to keep unit tests separate from the actual source code of their application. If that is your case, you can simply create a separate tests folder in your project, and start writing Zig modules that contains only unit tests (as you would normally do on a Python project with pytest, for example), and everything will work fine. It boils down to which is your preference here.",
     "crumbs": [
       "<span class='chapter-number'>8</span>  <span class='chapter-title'>Unit tests</span>"
     ]
@@ -664,7 +664,7 @@
     "href": "Chapters/03-unittests.html#testing-errors",
     "title": "8  Unit tests",
     "section": "8.4 Testing errors",
-    "text": "8.4 Testing errors\nOne common style of unit tests are those that look for specific errors in your functions. In other words, you write a unit test that tries to assert if a specific function call returns any error, or a specific type of error.\nIn C++ you would normally write this style of unit tests using, for example, the functions REQUIRE_THROWS() or CHECK_THROWS() from the Catch2 test framework3. In the case of a Python project, you would probably use the raises() function from pytest4. While in Rust, you would probably use assert_eq!() in conjunction with Err().\nBut in Zig, we use the expectError() function, from the std.testing module. With this function, you can test if a specific function call returns the exact type of error that you expect it to return. To use this function, you first write try expectError(). Then, on the first argument, you provide the type of error that you are expecting from the function call. Then, on the second argument, you write the function call that you expect to fail.\nThe code example below demonstrates such type of unit test in Zig. Notice that, inside the function alloc_error() we are allocating 100 bytes of memory, or, an array of 100 elements, for the object ibuffer. However, in the test block, we are using the FixedBufferAllocator() allocator object, which is limited to 10 bytes of space, because the object buffer, which we provided to the allocator object, have only 10 bytes of space.\nThat is why, the alloc_error() function raises an OutOfMemory error on this case. Because this function is trying to allocate more space than the allocator object allows. So, in essence, we are testing for a specific type of error, which is OutOfMemory. If the alloc_error() function returns any other type of error, then, the expectError() function would make the entire test fail.\n\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst expectError = std.testing.expectError;\nfn alloc_error(allocator: Allocator) !void {\n    var ibuffer = try allocator.alloc(u8, 100);\n    defer allocator.free(ibuffer);\n    ibuffer[0] = 2;\n}\n\ntest \"testing error\" {\n    var buffer: [10]u8 = undefined;\n    var fba = std.heap.FixedBufferAllocator.init(&buffer);\n    const allocator = fba.allocator();\n    try expectError(error.OutOfMemory, alloc_error(allocator));\n}\n\n1/1 file1537546f248.test.testing error...OKAll 1 t\n  tests passed.",
+    "text": "8.4 Testing errors\nOne common style of unit tests are those that look for specific errors in your functions. In other words, you write a unit test that tries to assert if a specific function call returns any error, or a specific type of error.\nIn C++ you would normally write this style of unit tests using, for example, the functions REQUIRE_THROWS() or CHECK_THROWS() from the Catch2 test framework3. In the case of a Python project, you would probably use the raises() function from pytest4. While in Rust, you would probably use assert_eq!() in conjunction with Err().\nBut in Zig, we use the expectError() function, from the std.testing module. With this function, you can test if a specific function call returns the exact type of error that you expect it to return. To use this function, you first write try expectError(). Then, on the first argument, you provide the type of error that you are expecting from the function call. Then, on the second argument, you write the function call that you expect to fail.\nThe code example below demonstrates such type of unit test in Zig. Notice that, inside the function alloc_error() we are allocating 100 bytes of memory, or, an array of 100 elements, for the object ibuffer. However, in the test block, we are using the FixedBufferAllocator() allocator object, which is limited to 10 bytes of space, because the object buffer, which we provided to the allocator object, have only 10 bytes of space.\nThat is why, the alloc_error() function raises an OutOfMemory error on this case. Because this function is trying to allocate more space than the allocator object allows. So, in essence, we are testing for a specific type of error, which is OutOfMemory. If the alloc_error() function returns any other type of error, then, the expectError() function would make the entire test fail.\n\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst expectError = std.testing.expectError;\nfn alloc_error(allocator: Allocator) !void {\n    var ibuffer = try allocator.alloc(u8, 100);\n    defer allocator.free(ibuffer);\n    ibuffer[0] = 2;\n}\n\ntest \"testing error\" {\n    var buffer: [10]u8 = undefined;\n    var fba = std.heap.FixedBufferAllocator.init(&buffer);\n    const allocator = fba.allocator();\n    try expectError(error.OutOfMemory, alloc_error(allocator));\n}\n\n1/1 filea5b059c00874.test.testing error...OKAll 1 \n   tests passed.",
     "crumbs": [
       "<span class='chapter-number'>8</span>  <span class='chapter-title'>Unit tests</span>"
     ]
@@ -674,7 +674,7 @@
     "href": "Chapters/03-unittests.html#testing-simple-equalities",
     "title": "8  Unit tests",
     "section": "8.5 Testing simple equalities",
-    "text": "8.5 Testing simple equalities\nIn Zig, there are some different ways you can test for an equality. You already saw that we can use expect() with the logical operator == to essentially reproduce an equality test. But we also have some other helper functions that you should know about, especially expectEqual(), expectEqualSlices() and expectEqualStrings().\nThe expectEqual() function, as the name suggests, is a classic test equality function. It receives two objects as input. The first object is the value that you expect to be in the second object. While second object is the object you have, or, the object that your application produced as result. So, with expectEqual() you are essentially testing if the values stored inside these two objects are equal or not.\nYou can see in the example below that, the test performed by expectEqual() failed. Because the objects v1 and v2 contain different values in them.\n\nconst std = @import(\"std\");\ntest \"values are equal?\" {\n    const v1 = 15;\n    const v2 = 18;\n    try std.testing.expectEqual(v1, v2);\n}\n\n1/1 ve.test.values are equal?...\n    expected 15, found 18\n    FAIL (TestExpectedEqual)\nve.zig:5:5: test.values are equal? (test)\n    try std.testing.expectEqual(v1, v2);\n    ^\n0 passed; 0 skipped; 1 failed.\nAlthough useful, the expectEqual() function does not work with arrays. For testing if two arrays are equal, you should use the expectEqualSlices() function instead. This function have three arguments. First, you provide the data type contained in both arrays that you are trying to compare. While the second and third arguments corresponds to the array objects that you want to compare.\nIn the example below, we are using this function to test if two array objects (array1 and array2) are equal or not. Since they are in fact equal, the unit test passed with no errors.\n\nconst std = @import(\"std\");\ntest \"arrays are equal?\" {\n    const array1 = [3]u32{1, 2, 3};\n    const array2 = [3]u32{1, 2, 3};\n    try std.testing.expectEqualSlices(\n        u32, &array1, &array2\n    );\n}\n\n1/1 file15377bbafb73.test.arrays are equal?...OKAl\n  ll 1 tests passed.\n\n\nAt last, you might also want to use the expectEqualStrings() function. As the name suggests, you can use this function to test if two strings are equal or not. Just provide the two string objects that you want to compare, as inputs to the function.\nIf the function finds any existing differences between the two strings, then, the function will raise an error, and also, print an error message that shows the exact difference between the two string objects provided, as the example below demonstrates:\n\nconst std = @import(\"std\");\ntest \"strings are equal?\" {\n    const str1 = \"hello, world!\";\n    const str2 = \"Hello, world!\";\n    try std.testing.expectEqualStrings(\n        str1, str2\n    );\n}\n\n1/1 t.test.strings are equal?... \n====== expected this output: =========\nhello, world!␃\n======== instead found this: =========\nHello, world!␃\n======================================\nFirst difference occurs on line 1:\nexpected:\nhello, world!\n^ ('\\x68')\nfound:\nHello, world!\n^ ('\\x48')",
+    "text": "8.5 Testing simple equalities\nIn Zig, there are some different ways you can test for an equality. You already saw that we can use expect() with the logical operator == to essentially reproduce an equality test. But we also have some other helper functions that you should know about, especially expectEqual(), expectEqualSlices() and expectEqualStrings().\nThe expectEqual() function, as the name suggests, is a classic test equality function. It receives two objects as input. The first object is the value that you expect to be in the second object. While second object is the object you have, or, the object that your application produced as result. So, with expectEqual() you are essentially testing if the values stored inside these two objects are equal or not.\nYou can see in the example below that, the test performed by expectEqual() failed. Because the objects v1 and v2 contain different values in them.\n\nconst std = @import(\"std\");\ntest \"values are equal?\" {\n    const v1 = 15;\n    const v2 = 18;\n    try std.testing.expectEqual(v1, v2);\n}\n\n1/1 ve.test.values are equal?...\n    expected 15, found 18\n    FAIL (TestExpectedEqual)\nve.zig:5:5: test.values are equal? (test)\n    try std.testing.expectEqual(v1, v2);\n    ^\n0 passed; 0 skipped; 1 failed.\nAlthough useful, the expectEqual() function does not work with arrays. For testing if two arrays are equal, you should use the expectEqualSlices() function instead. This function have three arguments. First, you provide the data type contained in both arrays that you are trying to compare. While the second and third arguments corresponds to the array objects that you want to compare.\nIn the example below, we are using this function to test if two array objects (array1 and array2) are equal or not. Since they are in fact equal, the unit test passed with no errors.\n\nconst std = @import(\"std\");\ntest \"arrays are equal?\" {\n    const array1 = [3]u32{1, 2, 3};\n    const array2 = [3]u32{1, 2, 3};\n    try std.testing.expectEqualSlices(\n        u32, &array1, &array2\n    );\n}\n\n1/1 filea5b054e42b80.test.arrays are equal?...OKAl\n  ll 1 tests passed.\n\n\nAt last, you might also want to use the expectEqualStrings() function. As the name suggests, you can use this function to test if two strings are equal or not. Just provide the two string objects that you want to compare, as inputs to the function.\nIf the function finds any existing differences between the two strings, then, the function will raise an error, and also, print an error message that shows the exact difference between the two string objects provided, as the example below demonstrates:\n\nconst std = @import(\"std\");\ntest \"strings are equal?\" {\n    const str1 = \"hello, world!\";\n    const str2 = \"Hello, world!\";\n    try std.testing.expectEqualStrings(\n        str1, str2\n    );\n}\n\n1/1 t.test.strings are equal?... \n====== expected this output: =========\nhello, world!␃\n======== instead found this: =========\nHello, world!␃\n======================================\nFirst difference occurs on line 1:\nexpected:\nhello, world!\n^ ('\\x68')\nfound:\nHello, world!\n^ ('\\x48')",
     "crumbs": [
       "<span class='chapter-number'>8</span>  <span class='chapter-title'>Unit tests</span>"
     ]
@@ -834,7 +834,7 @@
     "href": "Chapters/09-error-handling.html#learning-more-about-errors-in-zig",
     "title": "10  Error handling and unions",
     "section": "",
-    "text": "t.zig:8:17: error: error set is discarded\nt.zig:8:17: note: consider using 'try', 'catch', or 'if'\n\n10.1.1 Returning errors from functions\nAs we described at Section 1.2.3, when we have a function that might return an error value, this function normally includes an exclamation mark (!) in its return type annotation. The presence of this exclamation mark indicates that this function might return an error value as result, and, the zig compiler forces you to always handle explicitly the case of this function returning an error value.\nTake a look at the print_name() function below. This function might return an error in the stdout.print() function call, and, as a consequence, its return type (!void) includes an exclamation mark in it.\n\nfn print_name() !void {\n    const stdout = std.getStdOut().writer();\n    try stdout.print(\"My name is Pedro!\", .{});\n}\n\nIn the example above, we are using the exclamation mark to tell the zig compiler that this function might return some error. But which error exactly is returned from this function? For now, we are not specifying a specific error value. We only known for now that some error value (whatever it is) might be returned.\nBut in fact, you can (if you want to) specify clearly which exact error values might be returned from this function. There are lot of examples of this in the Zig Standard Library. Take this fill() function from the http.Client module as an example. This function returns either a error value of type ReadError, or void.\n\npub fn fill(conn: *Connection) ReadError!void {\n    // The body of this function ...\n}\n\nThis idea of specifying the exact error values that you expect to be returned from the function is interesting. Because they automatically become some sort of documentation of your function, and also, it allows the zig compiler to perform some extra checks over your code. Because it can check if there is any other type of error value that is being generated inside your function, and, that it is not being accounted for in this return type annotation.\nAnyway, you can list the types of errors that can be returned from the function by listing them on the left side of the exclamation mark. While the valid values stay on the right side of the exclamation mark. So the syntax format become:\n&lt;error-value&gt;!&lt;valid-value&gt;\n\n\n10.1.2 Error sets\nBut what about when we have a single function that might return different types of errors? When you have such a function, you can list all of these different types of errors that can be returned from this function, through a structure in Zig that we call of an error set.\nAn error set is a special case of an union type. It is an union that contains error values in it. Not all programming languages have a notion of an “union object”. But in summary, an union is just a set of data types. Unions are used to allow an object to have multiple data types. For example, a union of x, y and z, means that an object can be either of type x, or type y or type z.\nWe are going to talk in more depth about unions at Section 10.3. But you can write an error set by writing the keyword error before a pair of curly braces, then you list the error values that can be returned from the function inside this pair of curly braces.\nTake the resolvePath() function below as an example, which comes from the introspect.zig module of the Zig Standard Library. We can see in its return type annotation, that this function return either: 1) a valid slice of u8 values ([]u8); or, 2) one of the three different types of error values listed inside the error set (OutOfMemory, Unexpected, etc.). This is an usage example of an error set.\n\npub fn resolvePath(\n    ally: mem.Allocator,\n    p: []const u8,\n) error{\n    OutOfMemory,\n    CurrentWorkingDirectoryUnlinked,\n    Unexpected,\n}![]u8 {\n    // The body of the function ...\n}\n\nThis is a valid way of annotating the return value of a Zig function. But, if you navigate through the modules that composes the Zig Standard Library, you will notice that, for the majority of cases, the programmers prefer to give a descriptive name to this error set, and then, use this name (or this “label”) of the error set in the return type annotation, instead of using the error set directly.\nWe can see that in the ReadError error set that we showed earlier in the fill() function, which is defined in the http.Client module. So yes, I presented the ReadError as if it was just a standard and single error value, but in fact, it is an error set defined in the http.Client module, and therefore, it actually represents a set of different error values that might happen inside the fill() function.\nTake a look at the ReadError definition reproduced below. Notice that we are grouping all of these different error values into a single object, and then, we use this object into the return type annotation of the function. Like the fill() function that we showed earlier, or, the readvDirect() function from the same module, which is reproduced below.\n\npub const ReadError = error{\n    TlsFailure,\n    TlsAlert,\n    ConnectionTimedOut,\n    ConnectionResetByPeer,\n    UnexpectedReadFailure,\n    EndOfStream,\n};\n// Some lines of code\npub fn readvDirect(\n        conn: *Connection,\n        buffers: []std.posix.iovec\n    ) ReadError!usize {\n    // The body of the function ...\n}\n\nSo, an error set is just a convenient way of grouping a set of possible error values into a single object, or a single type of an error value.\n\n\n10.1.3 Casting error values\nLet’s suppose you have two different error sets, named A and B. If error set A is a superset of error set B, then, you can cast (or coerce) error values from B into error values of A.\nError sets are just a set of error values. So, if the error set A contains all error values from the error set B, then A becomes a superset of B. You could also say that the error set B is a subset of error set A.\nThe example below demonstrates this idea. Because A contains all values from B, A is a superset of B. In math notation, we would say that \\(A \\supset B\\). As a consequence, we can give an error value from B as input to the cast() function, and, implicitly cast this input into the same error value, but from the A set.\n\nconst std = @import(\"std\");\nconst A = error{\n    ConnectionTimeoutError,\n    DatabaseNotFound,\n    OutOfMemory,\n    InvalidToken,\n};\nconst B = error {\n    OutOfMemory,\n};\n\nfn cast(err: B) A {\n    return err;\n}\n\ntest \"coerce error value\" {\n    const error_value = cast(B.OutOfMemory);\n    try std.testing.expect(\n        error_value == A.OutOfMemory\n    );\n}\n\n1/1 file10459ffd0e21.test.coerce error value...OKA\n  All 1 tests passed.",
+    "text": "t.zig:8:17: error: error set is discarded\nt.zig:8:17: note: consider using 'try', 'catch', or 'if'\n\n10.1.1 Returning errors from functions\nAs we described at Section 1.2.3, when we have a function that might return an error value, this function normally includes an exclamation mark (!) in its return type annotation. The presence of this exclamation mark indicates that this function might return an error value as result, and, the zig compiler forces you to always handle explicitly the case of this function returning an error value.\nTake a look at the print_name() function below. This function might return an error in the stdout.print() function call, and, as a consequence, its return type (!void) includes an exclamation mark in it.\n\nfn print_name() !void {\n    const stdout = std.getStdOut().writer();\n    try stdout.print(\"My name is Pedro!\", .{});\n}\n\nIn the example above, we are using the exclamation mark to tell the zig compiler that this function might return some error. But which error exactly is returned from this function? For now, we are not specifying a specific error value. We only known for now that some error value (whatever it is) might be returned.\nBut in fact, you can (if you want to) specify clearly which exact error values might be returned from this function. There are lot of examples of this in the Zig Standard Library. Take this fill() function from the http.Client module as an example. This function returns either a error value of type ReadError, or void.\n\npub fn fill(conn: *Connection) ReadError!void {\n    // The body of this function ...\n}\n\nThis idea of specifying the exact error values that you expect to be returned from the function is interesting. Because they automatically become some sort of documentation of your function, and also, it allows the zig compiler to perform some extra checks over your code. Because it can check if there is any other type of error value that is being generated inside your function, and, that it is not being accounted for in this return type annotation.\nAnyway, you can list the types of errors that can be returned from the function by listing them on the left side of the exclamation mark. While the valid values stay on the right side of the exclamation mark. So the syntax format become:\n&lt;error-value&gt;!&lt;valid-value&gt;\n\n\n10.1.2 Error sets\nBut what about when we have a single function that might return different types of errors? When you have such a function, you can list all of these different types of errors that can be returned from this function, through a structure in Zig that we call of an error set.\nAn error set is a special case of an union type. It is an union that contains error values in it. Not all programming languages have a notion of an “union object”. But in summary, an union is just a set of data types. Unions are used to allow an object to have multiple data types. For example, a union of x, y and z, means that an object can be either of type x, or type y or type z.\nWe are going to talk in more depth about unions at Section 10.3. But you can write an error set by writing the keyword error before a pair of curly braces, then you list the error values that can be returned from the function inside this pair of curly braces.\nTake the resolvePath() function below as an example, which comes from the introspect.zig module of the Zig Standard Library. We can see in its return type annotation, that this function return either: 1) a valid slice of u8 values ([]u8); or, 2) one of the three different types of error values listed inside the error set (OutOfMemory, Unexpected, etc.). This is an usage example of an error set.\n\npub fn resolvePath(\n    ally: mem.Allocator,\n    p: []const u8,\n) error{\n    OutOfMemory,\n    CurrentWorkingDirectoryUnlinked,\n    Unexpected,\n}![]u8 {\n    // The body of the function ...\n}\n\nThis is a valid way of annotating the return value of a Zig function. But, if you navigate through the modules that composes the Zig Standard Library, you will notice that, for the majority of cases, the programmers prefer to give a descriptive name to this error set, and then, use this name (or this “label”) of the error set in the return type annotation, instead of using the error set directly.\nWe can see that in the ReadError error set that we showed earlier in the fill() function, which is defined in the http.Client module. So yes, I presented the ReadError as if it was just a standard and single error value, but in fact, it is an error set defined in the http.Client module, and therefore, it actually represents a set of different error values that might happen inside the fill() function.\nTake a look at the ReadError definition reproduced below. Notice that we are grouping all of these different error values into a single object, and then, we use this object into the return type annotation of the function. Like the fill() function that we showed earlier, or, the readvDirect() function from the same module, which is reproduced below.\n\npub const ReadError = error{\n    TlsFailure,\n    TlsAlert,\n    ConnectionTimedOut,\n    ConnectionResetByPeer,\n    UnexpectedReadFailure,\n    EndOfStream,\n};\n// Some lines of code\npub fn readvDirect(\n        conn: *Connection,\n        buffers: []std.posix.iovec\n    ) ReadError!usize {\n    // The body of the function ...\n}\n\nSo, an error set is just a convenient way of grouping a set of possible error values into a single object, or a single type of an error value.\n\n\n10.1.3 Casting error values\nLet’s suppose you have two different error sets, named A and B. If error set A is a superset of error set B, then, you can cast (or coerce) error values from B into error values of A.\nError sets are just a set of error values. So, if the error set A contains all error values from the error set B, then A becomes a superset of B. You could also say that the error set B is a subset of error set A.\nThe example below demonstrates this idea. Because A contains all values from B, A is a superset of B. In math notation, we would say that \\(A \\supset B\\). As a consequence, we can give an error value from B as input to the cast() function, and, implicitly cast this input into the same error value, but from the A set.\n\nconst std = @import(\"std\");\nconst A = error{\n    ConnectionTimeoutError,\n    DatabaseNotFound,\n    OutOfMemory,\n    InvalidToken,\n};\nconst B = error {\n    OutOfMemory,\n};\n\nfn cast(err: B) A {\n    return err;\n}\n\ntest \"coerce error value\" {\n    const error_value = cast(B.OutOfMemory);\n    try std.testing.expect(\n        error_value == A.OutOfMemory\n    );\n}\n\n1/1 filea64e1da1167c.test.coerce error value...OKA\n  All 1 tests passed.",
     "crumbs": [
       "<span class='chapter-number'>10</span>  <span class='chapter-title'>Error handling and unions</span>"
     ]
@@ -954,7 +954,7 @@
     "href": "Chapters/10-stack-project.html#sec-comptime",
     "title": "12  Project 3 - Building a stack data structure",
     "section": "",
-    "text": "apply comptime on a function argument.\napply comptime on an object.\napply comptime on a block of expressions.\n\n\n12.1.1 Applying over a function argument\nWhen you apply the comptime keyword on a function argument, you are saying to the zig compiler that the value assigned to that particular function argument must be known at compile-time. We explained in details at Section 3.1.1 what exactly “value known at compile-time” means, so, in case you have doubts about this idea, come back to that section.\nNow let’s think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement to that particular function argument. If the programmer accidentally tries to give a value to this function argument that is not known at compile time, the zig compiler will notice this problem, and as a consequence, it will raise a compilation error saying that it cannot compile your program. Because you are providing a value that is “runtime known” to a function argument that must be “compile-time known”.\nTake a look at this very simple example below, where we define a twice() function, that simply doubles the input value named num. Notice that we use the comptime keyword before the name of the function argument. This keyword is marking the function argument num as a “comptime argument”.\nThat is a function argument whose value must be compile-time known. This is why the expression twice(5678) is valid, and no compilation errors are raised. Because the value 5678 is compile-time known, so this is the expected behaviour for this function.\n\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n\n1/1 file1105a40478a9d.test.test comptime...OKAll 1\n  1 tests passed.\n\n\nBut what if we provide a number that is not compile-time known to this function? For example, we might provide a different input value to this function depending on the target OS of our compilation process. The code example below demonstrates such case.\nBecause the value of the object n is determined at runtime, we cannot provide this object as input to the twice() function. The zig compiler will not allow it, because we marked the num argument as a “comptime argument”. That is why the zig compiler raises the compile-time error exposed below:\n\nconst builtin = @import(\"builtin\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    var n: u32 = undefined;\n    if (builtin.target.os.tag == .windows) {\n        n = 1234;\n    } else {\n        n = 5678;\n    }\n    _ = twice(n);\n}\n\nt.zig:12:16: error: runtime-known argument passed to comptime parameter \nComptime arguments are frequently used on functions that return some sort of generic structure. In fact, comptime is the essence (or the basis) to make generics in Zig. We are going to talk more about generics at Section 12.2.\nFor now, let’s take a look at this code example from Seguin (2024). You can see that this IntArray() function have one argument named length. This argument is marked as comptime, and receives a value of type usize as input. So the value given to this argument must be compile-time known. We can also see that this function returns an array of i64 values as output.\n\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n\nNow, the key component of this function is the length argument. This argument is used to determine the size of the array that is produced by the function. Let’s think about the consequences of that. If the size of the array is dependent on the value assigned to the length argument, this means that the data type of the output of the function depends on the value of this length argument.\nLet this statement sink for a bit in your mind. As I described at Section 1.2.2, Zig is a strongly-typed language, especially on function declarations. So every time we write a function in Zig, we have to annotate the data type of the value returned by the function. But how can we do that, if this data type depends on the value given to the argument of the function?\nThink about this for a second. If length is equal to 3 for example, then, the return type of the function is [3]i64. But if length is equal to 40, then, the return type becomes [40]i64. At this point the zig compiler would be confused, and raise a compilation error, saying something like this:\n\nHey! You have annotated that this function should return a [3]i64 value, but I got a [40]i64 value instead! This doesn’t look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when the type keyword comes in. This type keyword is basically saying to the zig compiler that this function will return some data type as output, but it doesn’t know yet what exactly data type that is. We will talk more about this at Section 12.2.\n\n\n12.1.2 Applying over an expression\nWhen you apply the comptime keyword over an expression, then, it is guaranteed that the zig compiler will execute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time (e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the zig compiler will raise a compilation error.\nTake this example from the official documentation of Zig (Zig Software Foundation 2024). We are executing the same fibonacci() function both at runtime, and, at compile-time. The function is by default executed at runtime, but because we use the comptime keyword at the second “try expression”, this expression is executed at compile-time.\nThis might be a bit confusing for some people. Yes! When I say that this expression is executed at compile-time, I mean that this expression is compiled and executed while the zig compiler is compiling your Zig source code.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n\n1/1 file1105a31c0f24f.test.fibonacci...OKAll 1 tes\n  sts passed.\n\n\nA lot of your Zig source code might be potentially executed at compile-time, because the zig compiler can figure it out the output of some expressions. Especially if these expressions depends only at compile-time known values. We have talked about this at Section 3.1.1.\nBut when you use the comptime keyword on an expression, there is no “it might be executed at compile-time” anymore. With the comptime keyword you are ordering the zig compiler to execute this expression at compile-time. You are imposing this rule, it is guaranteed that the compiler will always execute it at compile-time. Or, at least, the compiler will try to execute it. If the compiler cannot execute the expression for whatever reason, the compiler will raise a compilation error.\n\n\n12.1.3 Applying over a block\nBlocks were described at Section 1.7. When you apply the comptime keyword over a block of expressions, you get essentially the same effect when you apply this keyword to a single expression. That is, the entire block of expressions is executed at compile-time by the zig compiler.\nIn the example below, we mark the block labeled of blk as a comptime block, and, therefore, the expressions inside this block are executed at compile-time.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n\n1/1 file1105a37ca2b0d.test.fibonacci in a block...\n  .OKAll 1 tests passed.",
+    "text": "apply comptime on a function argument.\napply comptime on an object.\napply comptime on a block of expressions.\n\n\n12.1.1 Applying over a function argument\nWhen you apply the comptime keyword on a function argument, you are saying to the zig compiler that the value assigned to that particular function argument must be known at compile-time. We explained in details at Section 3.1.1 what exactly “value known at compile-time” means, so, in case you have doubts about this idea, come back to that section.\nNow let’s think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement to that particular function argument. If the programmer accidentally tries to give a value to this function argument that is not known at compile time, the zig compiler will notice this problem, and as a consequence, it will raise a compilation error saying that it cannot compile your program. Because you are providing a value that is “runtime known” to a function argument that must be “compile-time known”.\nTake a look at this very simple example below, where we define a twice() function, that simply doubles the input value named num. Notice that we use the comptime keyword before the name of the function argument. This keyword is marking the function argument num as a “comptime argument”.\nThat is a function argument whose value must be compile-time known. This is why the expression twice(5678) is valid, and no compilation errors are raised. Because the value 5678 is compile-time known, so this is the expected behaviour for this function.\n\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n\n1/1 filea72d248f97f8.test.test comptime...OKAll 1 \n   tests passed.\n\n\nBut what if we provide a number that is not compile-time known to this function? For example, we might provide a different input value to this function depending on the target OS of our compilation process. The code example below demonstrates such case.\nBecause the value of the object n is determined at runtime, we cannot provide this object as input to the twice() function. The zig compiler will not allow it, because we marked the num argument as a “comptime argument”. That is why the zig compiler raises the compile-time error exposed below:\n\nconst builtin = @import(\"builtin\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    var n: u32 = undefined;\n    if (builtin.target.os.tag == .windows) {\n        n = 1234;\n    } else {\n        n = 5678;\n    }\n    _ = twice(n);\n}\n\nt.zig:12:16: error: runtime-known argument passed to comptime parameter \nComptime arguments are frequently used on functions that return some sort of generic structure. In fact, comptime is the essence (or the basis) to make generics in Zig. We are going to talk more about generics at Section 12.2.\nFor now, let’s take a look at this code example from Seguin (2024). You can see that this IntArray() function have one argument named length. This argument is marked as comptime, and receives a value of type usize as input. So the value given to this argument must be compile-time known. We can also see that this function returns an array of i64 values as output.\n\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n\nNow, the key component of this function is the length argument. This argument is used to determine the size of the array that is produced by the function. Let’s think about the consequences of that. If the size of the array is dependent on the value assigned to the length argument, this means that the data type of the output of the function depends on the value of this length argument.\nLet this statement sink for a bit in your mind. As I described at Section 1.2.2, Zig is a strongly-typed language, especially on function declarations. So every time we write a function in Zig, we have to annotate the data type of the value returned by the function. But how can we do that, if this data type depends on the value given to the argument of the function?\nThink about this for a second. If length is equal to 3 for example, then, the return type of the function is [3]i64. But if length is equal to 40, then, the return type becomes [40]i64. At this point the zig compiler would be confused, and raise a compilation error, saying something like this:\n\nHey! You have annotated that this function should return a [3]i64 value, but I got a [40]i64 value instead! This doesn’t look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when the type keyword comes in. This type keyword is basically saying to the zig compiler that this function will return some data type as output, but it doesn’t know yet what exactly data type that is. We will talk more about this at Section 12.2.\n\n\n12.1.2 Applying over an expression\nWhen you apply the comptime keyword over an expression, then, it is guaranteed that the zig compiler will execute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time (e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the zig compiler will raise a compilation error.\nTake this example from the official documentation of Zig (Zig Software Foundation 2024). We are executing the same fibonacci() function both at runtime, and, at compile-time. The function is by default executed at runtime, but because we use the comptime keyword at the second “try expression”, this expression is executed at compile-time.\nThis might be a bit confusing for some people. Yes! When I say that this expression is executed at compile-time, I mean that this expression is compiled and executed while the zig compiler is compiling your Zig source code.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n\n1/1 filea72d3cf7abe2.test.fibonacci...OKAll 1 test\n  ts passed.\n\n\nA lot of your Zig source code might be potentially executed at compile-time, because the zig compiler can figure it out the output of some expressions. Especially if these expressions depends only at compile-time known values. We have talked about this at Section 3.1.1.\nBut when you use the comptime keyword on an expression, there is no “it might be executed at compile-time” anymore. With the comptime keyword you are ordering the zig compiler to execute this expression at compile-time. You are imposing this rule, it is guaranteed that the compiler will always execute it at compile-time. Or, at least, the compiler will try to execute it. If the compiler cannot execute the expression for whatever reason, the compiler will raise a compilation error.\n\n\n12.1.3 Applying over a block\nBlocks were described at Section 1.7. When you apply the comptime keyword over a block of expressions, you get essentially the same effect when you apply this keyword to a single expression. That is, the entire block of expressions is executed at compile-time by the zig compiler.\nIn the example below, we mark the block labeled of blk as a comptime block, and, therefore, the expressions inside this block are executed at compile-time.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n\n1/1 filea72d6353d586.test.fibonacci in a block...O\n  OKAll 1 tests passed.",
     "crumbs": [
       "<span class='chapter-number'>12</span>  <span class='chapter-title'>Project 3 - Building a stack data structure</span>"
     ]

From ffd11313d2ab5387ca44a0a66b551a8db11e09f6 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sun, 16 Feb 2025 17:54:40 -0300
Subject: [PATCH 071/151] Change cover

---
 _quarto.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/_quarto.yml b/_quarto.yml
index b3066403..0bcbbafc 100644
--- a/_quarto.yml
+++ b/_quarto.yml
@@ -6,10 +6,10 @@ book:
   title: "Introduction to Zig"
   subtitle: "a project-based book"
   author: "Pedro Duarte Faria"
-  edition: 2
+  edition: 1
   date: "today"
   google-analytics: "G-6CHJXK4CEV"
-  cover-image: "Cover/cover-artv4.png"
+  cover-image: "Cover/cover-artv3.png"
   chapters:
     - index.qmd
     - Chapters/01-zig-weird.qmd

From 7e889edc9e7922f87bfd665d53c2558151779641 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sun, 16 Feb 2025 17:55:47 -0300
Subject: [PATCH 072/151] Recompile entire book

---
 docs/Cover/cover-artv3.png | Bin 0 -> 1030663 bytes
 docs/Cover/cover-artv4.png | Bin 577665 -> 0 bytes
 docs/index.html            |   2 +-
 3 files changed, 1 insertion(+), 1 deletion(-)
 create mode 100644 docs/Cover/cover-artv3.png
 delete mode 100644 docs/Cover/cover-artv4.png

diff --git a/docs/Cover/cover-artv3.png b/docs/Cover/cover-artv3.png
new file mode 100644
index 0000000000000000000000000000000000000000..c9f280288cc1592df80159b50c7a6bca22f2131b
GIT binary patch
literal 1030663
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%0DD$AQOn=>-gMg;D5ctO$bz%f<2#2`-aGnVzpn#
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%0DAR@qKS#7Q3ov$z))c
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%0DrybHM`B+VS!
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
W#OhKOtH+e5tf8WNv*d=|!~X|Wi-rsU

literal 0
HcmV?d00001

diff --git a/docs/Cover/cover-artv4.png b/docs/Cover/cover-artv4.png
deleted file mode 100644
index fd19809a8a6abb36015fbeba00bb46bd5338d7e1..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 577665
zcmeFYg;!Kz_dPy{3ereQ3J6GtO2a53NOwp#(%mhcgOUP*bayubLw9$~&^^@9{4VeN
z{rnNXwO-b8G0vK~_j%59&OUqZa|u(BlfcFx!vKLm*pgqxlt3VKO%MnR75zEzj*V0-
z7VztZ-Pdo9AP_s<<3AL)9Iy-U<}0T!8cxc#rcSN~4kjR1S66m(8%swc13MFTTL-h0
zLm@H{=ru@E?30RH>i&{z+@iYsF~ZEWmc%?~N~*|I+TmxB@v8*~lmQ|cuA%2xxxaBT
zy759$j0`DWqJ4dx@tN<bn>)?ZCk&hP!AXV`?e!#)i}Xc_@zwK%e|{rz{ePx7<^1`*
zQhIU9AL6M0!Se_et<1%=)zQ}G{+oItDzL!EA3x!KGvWWf1cBP!XsZA3_18E5d-)iP
z|Ha|I8S%e3{4WmwD~A8(!2ja#zc~D_GyK0C_+K&nuNeMU4F5kU29?BfV3qCZA9&W`
zlki4ZYTi(2Cy7k>k!}@p>)9W)N-E69UHF0fhroNg4%4534~y|u6*1}h9HQ9&tJ>_2
z>%)e4wP;84-A#cZL`666QgQzK4g1VzAdqo(%m~z+(FrP@F3g+oXOt+&>(Cz3w?UgL
zYfcDACg3L$Ulh1Ue#LJcSp>{%I4Uvq9b;ot^2Oz4R7!{iClLt5NldX=&u=<y4RNL`
zsqo5ww`UImxjp&M*Zlje&+RuQC*a@mTzV?uO_>UAw>w1grbdv_Cm_&;D`k-X<z#9R
zynb^E;&l-H@0I;d@;lgJhWRVG=b(0@7i=KVU#VnrO#AEcQn$6aD!6%%Y{Yfrt!^1t
za~9!U0F+q<4Ok<6S(?W{7HvdmXjbwxv~J5=u(f_?_VP9tZd9+``&|G8a-j#bksrqH
zp+)#a^ilYP+;+H0kLwqs&gCAWrro*PEYVmL5XflmlyT)QP_Jx&2tG7n6I!)!6d^s6
zhF^y@Sd1_RfrJtsmo1(FL~RXCHvFA@GL>1{ERh725WmAt-H-jT1nbUtEkIt9#+pvr
zLUx=NTyK&B$a#BaaBt<jip&(f3?}R=Y_e;_Cs07g8jm5G#SHRd$I%+4>Y)~<PhdZc
zR8DXb*OET>DOn!h6MOu?3guWm&5r$5sM}850_-+g5VmU_(#`8Z4E+-@kwrmN+=2p{
zrOS9G!+C02*Bus-CobW6N2f<l!QMS;$3#o(5*e4}tN(_UHaJ+iqQq9>>>^6&q|AE3
z^1)Qz(^6-0Y9s3oVrvNGSXPC>mUmo`sL<|E$@FHUMx8ll0=QiGdGMkcZu|Ds%!bie
zN1y%em@+IdE3aEQI`!p2NzKg%kD~t^rsq4PT{6^YYD)^y+~?YJ%CJIdDKQVvYdMAc
z){Z~~pPP!=7F0+nM|(HCmGJc0D)6%oT6-(TPfI(G`57XV`vFYh-0-K2oM%(2qGcA3
z7ke;V>7eHssGAGe8(xEUSICNoar6FS!%ylB_sxY`us|#6vSPSH1I5C%IMsR5$?z6e
zg;6%)xwGI=o~^~L<D0Q+Y0j}}B@$=nhVQl|5y6dK?|Dfwa|(`okq0G1S|RYx^j4PA
zMwg+t_bE>}f7ZMwfpyvnbEnl53j#U!d#GY>r3_T_Yh(kKL?-}SH_Gjf9L`Nzo+HIR
zznX1!=Hsz_6^*8j>~ZF`i40Lgnh7(5_DKZxt}m`UoAx~59ZYr5AY~gMD{JTu>{mwP
z>TTVmuo7KcpK+=%cPW@}wNXcVVI}OQJGDqz_D6|zQg;RiYjY)I2&Ti=2k@<%p5o!-
zA6#YhZlzs%($UVJbSm}|WijbRUN3%qzbQ2qw}Kz!z@&+JLsg)+!pnOPTifbVXyCE^
zJ(#~jl~*H-ce+>CJt^wzG>t80TS3E<kZc71D!n)fX0ahldPTRfpBC{1)Wlfr_W~A~
zGXdWi5&lbSDQi&#k+iPy<gVq&m9q(zZ+5lUc7=Cu&uzxGgZ5i^_3RW<k!N$?Aowlb
z_f)7Bc~x07%O{lqu!g*m@ZsoSVUhccsXP0rnj-j0Ya1=k1=axq0ct1MD<;pM)m(CJ
z8Pk~|&#NxYpH04Liq%r@*2=qM5NTbDD?IoK33X&#p)5;su%uY7rg88UvWEAa5$(Yn
z@7)pSX<6{@`~CEkCm=|zEj1BZ_n*Vk++vCR22mOkv_XqL4=hl3fe~c8*CQ}AblW-e
znF1<s?rt{&xY6kk3+DD?n49!pi1G2!hAqPCblvQ3_lpK#*c@r#-HB6>e&#MKA3d`r
z#~%j?nSOOf3Z3~z=6j=iUU=5KvM{>j=_9Vn(9rK}`=MslD+GFit4)X<esJXPb5GY6
zERceZC}z@YAK#VQ$Mq;RP_WFX98Q2hGOVZpP+@TX^IA+cKjyvt@1bRS?xM}7sv%<1
zr>&IoOXJ$1$d>!^%Y75+%o^z0Z%}z1vwP;Vn_PM@MNeIE>1AWtK{He9d!%PYxjkH@
z%-&-G6|v;L5~;jERk&&lYX6STrvIaUr<4uRnO@T85t)1qtD_DDQoD)@)z5xc3+%zy
z?|C1iIK@BqBtJJ`v$h)v_I60MJDUtIcD?9(2Lp?^8#>8a7x#LAI28wr)7_|lky-LY
zS9jT>F}r?|5TU*Inf_pJKU0<&WA_7^Cc}=^ooDvInf74^H;WnvL|W4k_l!h0;T-Ry
z^)0e&8oH{$h4Xucs$}S9D{ruWBQ(Xgjb7xqPY|}J-VpNA&)fB(zx8s7Quwhf-{tX2
zc<b;)ov6-~MsMH>&=Ti2M_*iDf~mF09Gh4?mvqe}j3`_u<1X*z)g>zUo`-(`k-~Q!
zb1nyV+Av7$O!iPMhr^qmH!;^PLv?0)o+;au&3fSDUup9XfA{3H*-ob{l9*>{<N=kt
zI-HI)&KFT}{v$kT;5*D`LQLk#M8qaKb!P^}X2npq$!~<`INTmar`2y>J0swG)6hca
zXw9d8E6H|G|I>VWSa8BRi6<|h#dW$qj@ow-H6NA;W*>+!8ZLJwAQ0eEYSxg)zP#+c
zVXdk~4Z0vfo3sska2=hgq%sn{`LfdNHqr0MQoHQPct>+@GwrKx)zUNnew>2C<Cwle
z%?btddkzd9$Jtk_P>EhytmXG{T-dz4RHvQS+Jo)KnsuFyq!KZ*?NIQJK@SG%x_KWg
zO>Qq6YsRXqC8pt^a%yq_45{_%*nJ%CuItxjL!e(clGLkOBItGAE4Xh7d%LL80Z>Ge
zCM?*Bj8#PxrSPaaQ-es4Os9~h!X1IrdWDdI8TO)CkJyvX_L9gEV5tN<#pIz#nFm$v
z=IhkLLsXCuf5tPs7H>MllBF8dwd@<w5<m+QFmb{Yg)HSvC9;p?8YmE1dZke#cPlsW
zXwO<xVH^;F46vgC@afI>VveqXw0Ct3o(ayxAA=rQ4P_Z$HiKu&)(1@ZbxIks3Jc@{
zk6}<WOt?3Jk89KzDM6<_m#WE)lzj3H_k@2tGAxnnEjNoClBMdNw}AY52sA;EN|#Q3
z?duWO?!?y9kGB)_5%8o=fl8_!eAlHqHuk&8KlT$kT9s7K{9YW=rQdk73i@acrj2Qz
zw}gK=l6w;GygXsnGgz9NykGNuZJqDDzVz}6o7|$38Wbsk#%opD-w5r6wtW6$fBMmN
zQDl^IPeL;*Z<azUB5F*_s<=N*K9@!>a>v=*erz%YHW!;P<8-uib*HcHRbpljowgjn
z?E#uV$*f0HY=lE|#i=VIT6Ltb&j-|=^@7chvD#49xA_dV(gkj{wNE{*J}mADEAp-2
zS$5p8=HgTt^dJO<{>w1*x+^3?EYGkNU+dCSqoOhI7Xu8#t!)RO5VKLA$yq!zp=@_c
zh$AgXq@@RL^g&K=cxlUs6h66xCd}J%I6AMkG_)`1Uom62;W})*#!Re2yFuAo-a_Zq
zP{Ysgk~&5Jk|TlU6Fd-<eDDIa|Ni0-=)92`Yf8;G{R^<xc<<lCh_*Vba93^nh~6iD
zTpM8D%0h;lIH?bF&y!v!lVRG!U<DtRPOAwTEgFH)F$TTup^3@@k7W|#uPk`D2_5-k
z!cACo34#A~&4#hMC^Byu7H6-oY=5J0RlA&zQr4m_-1hJs|3w`Q*HoKvk_YKCW;`p`
z0!ZFv2*(3W)m?~d91Pah#ulDaaY6_rie{bpTPn>Zy>stdN_3TRe6$(~Wg}}ag3nXj
zad5l%0I?3@)Md4r$78!%Q!KIXS&ekt`OFcHEaPW6d{t<z&`_7~zAP-73t%nDl-7s>
zY-yI(L)hjAB0a|u&(e~sG?3rulds1UdSwvjlwj_;8;Ldza!X#*hjmO)S}$AMiqg5T
zlqlxkAGxx93~t-W%+(-2Mu+{k%SqJiB(M|b0oV^TJ&HP9W8ZVza3FJ2&e8Gl5kH;t
zzW5T!-EJ2a`9wZwOkmWk5P<MBK`+9g4%)t_-7*)gyJj_I?I^FO`fH|qKS_T_Q5mmh
znxmjeQ(Z*?87=+t#$ub^{~nPDcGC5#GE<C9TzH;Gd<}1iJsS3itj|UMt#`S(4KLG5
zWa-WpJpdQ;l&~*YrlaU*zSIOs9yXh4G2AR)gp~Z=#{@B{m6hEWNar9<3Yj?B-+!3A
zn2!OQTOFSOrLIP!9v-Wyet3>t8U+gudmiUJhLBlCRrn~yM@OdL%+ca7{VahD9`2l{
zW^$0L&E=qYqtMEwSN#7X=k(B7!;!^nMHL<;JSTGX#BXV5PN1<VPMPozu&2>(wyB4P
zb1@#1Y7S7ONzaF}=;)4R=mPJ>NHj0_Hg#6Xs&HIo%3gG!6S3bnP(?*|Z+|CQ;gem$
zY-!8!q3dHqDYNC#a5p8}hyMmJ%;QGfqIE05TF|1E5wstbK{*As>6oJVNN+uxD%;!a
z6YEC?qT1V+L>^ATZTHhDZM`n}$MpI)najPWVpzIEOmA6ZC#YPU7gi%LFA}nf8hdho
zP8XIwi182y5rbl$Wju>{6ET`u*LLCgq<xu`qVOKSB&TxpNq(xQx)nt8L1S(i{L+#~
z<)M%sL@IxRZ*RJA*9U3y{wug#e$oJE2N;CgK=n%ZZFicC87UJ9EC6U<7I`N~9NB^s
z9EhvlbI&IrQOwt4cGw~nHySl=rx+k{Be(49BeevJ2X)SJ>V<Omw>EmMHMySmC$8j1
zJ)zX5pz@-;T4BO>yW^$1OWIapb!9%L3^PiR)BmDUV3`HHCc@&kdz<w3BcqdrN2jN)
z?y4(B>Hwf|+~5@Nq=DMy9z_Ugr#9sim3jGlSDh%Nmfpl2NMES_FT6IphiKr+ZKlxC
za4EW$Szg8cD)iD0S)-Ufz*DbXkwqs`w-cDWe_plxOcngWNSzmVFp>?rNp^@1x($2O
z1l{GCKzPb+Z|zKmN}qeVEq%P58JU?h<^Yj$Y);xn0W?O&V;^iI#04~KohARmbwJ)2
zN;=lIp~caWQ0q3aK9>$k-mkOC{%~)(VDMp%g%&oD5?wN<`yccKf%LI}1`t18<;*AY
zP;w@?CIL5kXcUUIL`TtQZTbrz&L-JBB2C5Dqs+6-cAduV(vxcw+2ewtX_0h4Tu>@Z
z2!kuuvXcWTdCx|o({0lMC;>{C;ZZ7b74P3k{>5lLSwe&3;-0BFL-uT!3Bk?N=EOkA
zyBEJUm&1pJMQpOQL#1a@si3`6`i1>Bdpm8Bl2;irW<d5vv&?{NHg8H7#?;P>q^_mU
z?V*h(s!OP#S>X&odq*0`Rf7r*^z%u}ZdRiz%m?gLr}Zjw!OJdCHbv%}SI<FB0!4TC
z+i$TB5%zj>UNVcqld1t>%tr+!xX>zwI~rgg{pWdN@)i8CEp7EXO!nusL8{-H2=R}!
zyj@tScZ>V4K_8PFi_t)S6`KGo!%8>=-{NR-GCdCtx9>bifuD@ri%eV1o?_B~;?-Vi
zwkIj+B|>J>csX=$2l=_GiuifXu%O7&Z$#<W*DZ>y(Ph56>Lui%ygDw*w|hiAUpy^0
zbg2N5_*VDye&x%^^sX2MsLAng=N<f<BbgeFdXyLtW-t<7t5Ar~+Tr$GE#2POYg*dj
z?+d5rIxHcKJ!ZUYCI8;X&!m!v;krDq0vnpSbA;b$;SN|mIIP3&EQdpfJ1#Wl8w)cn
zeZB6O5U~ens!p;X{Ug8_ScN=Nvp#a%2z8O8c8S($fJ{54O;gfA9h&dLwYXDplJdPs
zDY~N@mWB`oNRBXQh^)`LrK9Qlo&{YWyT#Mdi_5i<?v)R(c$eo0INTP_5m&fidYt41
zf!%YP7EjCOol0_}rCcir1{y<JZ9?Paf-5D_2*33vot~uyYuD9C5`mVdYZp;^n_%b8
z>PWQZx0ars+o8q@!*Z2;U|YydbKb7SYwO>`oEpqsCYEv$4&5`QSn+$Xb6hY7`)|Ym
zP+}K~WxU$#T@ur2#4B?iV$X6>LE-~bG$1_ucTLGK!E_;n;!kMlyk>RSM;@R?jXHOv
zn_z__X(#!;hUz6laHMO{jrs)?bH&BmYpVzM=v0*&s>I)V5fB3V5#h^L39>khakoYU
zjHKTF=NoAwT;kOmAz4MGwsnvzwUIGIQ7fv&dqoq<`FbW@;q%Snp3o5+O)?f2Cu3o8
zF|o)vOa!l`d_<eBql*=V`P`PX4|tY{!*ko~=QB_wO_~XabB&F^nNGxYu43#%4MLK7
zf|paNGYoV;I7JiFGV=!vUcR{wQtSm^<<a)s9AP|?M|J8Z;Ya%l4vWAEdzT;w5j7Y|
ze{w+0+6^hwB2RyqMy<I0w@fC3ar`|GFs0Hx9=MvK;5XMj$dT_C)Ir+jb-q3``s%k!
z*Ll<5ll%K6x=fa4#C1xOb|?ly1mG+wkUpni#*@2}5a@>%OxTpNO&Dh0GO;oSs^@JQ
zkXXb2b`ZA05pW4D+$h6tMkf#m0@S>|sOR$UD%jEe$@X`v**hBfl-hbDir(PSCzZ-T
zVX!Q_8>c=*@_Tyi-=8#5j>bv--?IQ6CupAVDC$NghPtVqN}$lzjRcH5%!~$;rV0P!
z6qo=`0cA9r+Bvk$W}cLHahae~(B&Z)|6@(_#qAZMRXETN|7K+5dv{w2G<TM7{N=>%
zH8s-gu|yWsg$0BA;ivRBB(958J@3stqcoXlMXE0%Ntqx+mg?8i*ofb<j9pv2l++O^
zGhLOnXhxqt%R3QY8(G}xTTz;a4?#B{FUgDT)WdPJ8MO;Ar@xKeTej99PAR}tS<tip
z+I+WxCc(ajiekx&qvre8k5S?5p5EB7Kl}RfET`wuQeqJH@x9S8*t?)a1U!7B1Yf2L
zuh8KtSO$r*i<~9U!8S%@n{*9)Z(a>uUTh4>hau%2Hs~JQ0dOp;Ws8KAfcZVbhhE9m
z9yRV>!~W>Zm<fwNQkO-6(Ld*;o+^>ri|;ufU5WVfx1jd7=xm@QJI!Pa1OmwxZI;SS
zcjY<VWJ%Hcbu5fn!7*gm62hT-AD6W7=iaoZQFgftH9v?cb{DQEQvXIyAom^cX?Kwx
z(vzv7p00Cmw5}h)vSWG{ky>b`UA5z}dL{x?x95?1UD=|wj6KB*W5nr;c1pSLKp=vM
z(I<W{ay&Jaz1D1_qq1;*H><B~4H3L%G0Au~ISJU8Fy$jK!@Sl+I=k%=b=bYX)e#+9
z68h$dc@&2Zupn@rb6Klx%a&s#7ZOW0$}@OeZis9zZMu<m*u0GwfH%6mMCgUm=V>G0
zW}%NaGwNHTL^KRUN0k<MK1kv-YJ$E2#_Z%UAl*n3n|I3Jt`i&*Ed<F+p{lGD0M@7P
zefzH#jJ5l&5%c`$&Bd=?e{bf2iUlZtc=`o<FW`ab|G?J-ancAq41Pn@9SJZ4%>3r;
zPB#g)GPBBW*V3xDXTuiEJ?z_^>V55#9``&yO`9DS#i5Hw(zZF;g0n_TdyN)R(c+tp
z5sTu>bx_Au=cAST&I%x0M0;{WPR~L5h5(H$*JB}cut$6e=}ytDJW97BC1vieJrHE(
zBl_5=q-c&Z^&T*xMQ$>T0LQSUNzF?Ahm7CucXReGaI>eP(COr%x31BWI2VOVr$H1s
zOjX$yV6K;w!30KkU$y=dofsfGchi%7*a!}4?U#(~R7)*+rPwHyD$JN{e>LU!JS@Df
z$LYuBxEgPoTf)#3+#hY75#P&MJ}2Fq{Av8oPa7L_u<^rm2^#f&r)a<=fTajWaQ{I8
zCDjKKgZ2}ng&m~4t^=eE#m(UPGr*R<F`L}X)9)ubG=x5)*8Q$CCUS@Lx@UeA?)uD6
zN&w!qg9t;ihf7+YXX#pYnu4=3#@SOnq$wtv875vy;oDy|PGpj1J?P+o^!0!Y=ANF7
zfjl;(*o9p<*tc<>h$u^?cMB#<!W!z@dJ^-NkonZu^N;5YHDme!G`qHOc6{%lOu;(m
z7XjPfUjl+;uzpvL@QFkhRV!J=P598hMfg@47Yp&QEkrQEHmdAS|I0q9Vsyok!2BNk
z+d!jHwnp^BC8F@{^^JYoq(VBR&10#fe*4)et$GGhZpKptjc5w6-fWL<ou`eu>Hzz=
z1og(JWYkS9odx>a8rcH~u<(P8>r3$wm<E6I(F`CqZp6Q%#QgMPC)pA<a%tWJd@E#i
zZfGbFV^6QuSXX1Axyuih9*$lx?+CyWmT*<=HF7^)A9-9+{D>eYyAaZEJ9(Z|?-q#$
z%hIbC+^f)U+uX&=PX)YpX#A0gKx1z7eOHlA825wK+U<o~XT(-dL*7t$W8<HrUm`#X
zk4<WXj(DB6M&=m_S=g|4Sq`U=*n0H+_-;LS#jW<)Tcq_qfasOHcn+n5z7`<;d%D&z
z#UGc^An=rV4|S<6bXv5Qy73VJAF2`AGG@J^T0VTbllBtL4*exuSw1&(df=Axe|%f_
z>SA*{R3HUqQA|HF%lwfZ%#k$8GT*UVpsLRmeQTZUO;G*A*5?LHyCr~5AXC~tRtfpQ
zsZxBI43`y2jKCZbe!YA;|2eB<W28-_c{`O~6f-{)@B#%eNn0$uL_O3|0|;)igMn&$
zoaEGO4MiwN|G5Z!Ag6Y8lQ=*#(oR`aqb5o7{MdZ`46VDG2@;)^zz%52S;)Er{^R@F
zC&8VW1r-X2bK&%We*UJrR=%u*d!YK;^d73W*?53{Jv3OlLd=owV3|5&uMV_%YUGw9
zd9ApF0p}z90;3Xw#L*{z#To8)f;zUSFSFA#DGEC5`-h@}__qC~H8|_oaFXUI*oK_B
z3Ti|&Q!o|v(jk<BQWf6%Z`8`DBhjc1BbpAEh*_r3)V-oDesdRyu)D+8>;VHs-5T<3
zBBikQLSqKtVW;ULjJoHysMI9Szlgn`++e9yXD6w6bXN}Z3o5op`?xGUlx1wnAdRBz
zwMdAV?aJ5UB|cJLx4*oAykYb4T-daCHa=Ugy?(^hEilAU(@4%$y1H)qi?kyR&>0|$
zU|~*;NJ_e#*=nG>TEB`uPYHqjQ}wn7{6&rXRhJpeC?#bhnnw#8Fr||wYfshJa)U)9
z2?xf&d@sH4pc+*MuRUsW?vAwc7r{^D^M#^Un%LGI?T`Jf?awk|;j?rChQPE#5vbT}
zEgmS?%iSF-x{6nrjQqsD*Z;tNAD_~`zv2&<ubidTvH-<Oy~P)8XX{#|vbvJ1x-x~=
zN3Fr+Wx}ODvSa)?G{7`rY`pn2J<+g&V&O)@5Fq^k52|pG^)1$zpk`4+_FNAcof33P
zP;&E^dLhT`HG;r2Ek$z^DKNl8Q?tISD6F8N=HRn*(LU>N2kvj(<h_4!|C3BsmHbMZ
z-Bi{#{0a!szr|_3?=}k$W=E~?tl~-$zlSuY--9y0`m&KvzkYv#=b?&+hll?OZ=d#1
zv!b*m^Kzbepwz_mz+_6t{=geQX4w**KJaXL;q3R;9jZNDu8jMkw<*Kc&DDMna%z29
zI!S0F&2i*vV>$Ewe7O``^$G3hyg|qiduGO5_`Env;T|jBw`Kp1aU8;gn$8`p)U8)k
zzhKoGK8nv1(h^TBpGCamrx<@2r0tj_jVY8+6DNIXB$|P(N~2vSnk4ruN68PmD;6^6
zU&;JVF2QwmwSst(_iD?TBj!z4u;En6ToM;e^c+Q>J)zrvxDwNAdfl7755;=nREoiP
zfje^Eht3&N-```@Yv&!_sik0^5AjU$Xeg+9?h2?Wj7R^%AW+rcqw6426C!O>JT%d7
zVj^0p#)<QMr5!n{X7p{+XAp}eP-**WV|4x3{VKlvPbtjj7Q18M>=$>U$@oP!A#&w(
zGUg$21|hokyJ-uXlkM!xW80INV;P_0g|VO)UkT?T`3$0hb&PL+$)VE(I*Eo62jX>T
zNHr6ybA0WgcT{d#dMh-v)UGRkCP0)M8QDE)Uy&3?9u+6XMo2}q#9GE>)EO;Me3d~F
z5`AMf`jG}*LxA_0D;xDwqo)greU6M!I)2@VaI$w3?zfVfnK<e?NzoBo*{`)%?zU<>
z_dQ47uuBCLkz~Vv>_~nMbM+;tt{n@P_j%h>L`~dbjA-+-j-z=>;F!f_Zv37B5-G0v
z3mBMv!GFtY+0%M!YPGBdk!{)=TNDo?(Fx<S;53Xu>3sfb6#NAeX)HV*>m=-xCTMA1
zmsP(Qm>CY7a4p=}9Sw)V`jg3lZ5gUrT6w(YYkC5v_$R?8uQ+Y$@!`Q=3}m7aGfy*z
zpPyq&e2af^<fTU2$-G2Bp7Sr}evOp-HEa@mBk|X_kV<Of=qS&~A(BsRG8zuG<}RM(
zWsdi&;8!H&6~cfAzv8m`yT+>;A*4F<9lA_6H2Y^J@Zg5r?ozBMu;^UdxSq^cQv@$D
zEqxbJ6_Z!0853QzV1c^pI!(eQj$N9R9?Zi2^>f_6mWgbCsu<!xW$Sweh>)`_HCU){
z#>~?-sYH%KX!^&JyX>XAI_1R%FY@=u*zd}Bbmd-(-L~_?P7>kB-0faG8A|d9bGRXw
ziv}SqOSma7f>uFcJov$;1j-1G%gW}q`!#jvubI<c6Tw{$3zyjz%_%b+oBQ!f(#?BF
zQc{H1U#0*r<_{5K;6@Tl+)P4B=~MR7dV8zh;RCtLG)>vxAm++v1%j|z8o8<E8xn3~
zf_S%PkK|%Yec2cI?>gmIck@wury3JSmv*uIRk4Z{<ii`EDW91nQK&_Z%`=NJFIhon
zI*I?Ps;q_bKSyJIF>5K;@yYRt1w|Y9y%>;@U%zbgo@#lV0X5D{_YLBFlse=*TyjHZ
z2Nf1<7-k~U$$#lMEY+U*t&bE;+kY^0_n17wMY!%lD?1KDk4e0)IHn-2VX``kAa1_Y
zMVUUzkF}D~!=^TFFVw064#|HZm68FibwN8|$vrCHw(_5a5y5O(e#PJV%z(bxmKTaF
zcEj}=tjT|V><}0(T`wl6B-;&7fjvLyX~#XU)BYV6VV3t=?BLF<HhVmfT<s8AL3<UD
zif>?{&B=yOG9)E_xcZf0V@J@jQEY$MvSZ7V1#!^LT<!dH#@s-D+nHI0>Qz)#PnTi;
z_V;Z1>$KVN_(B0p7b>f+Rv>9oRsx^Bi><iL#A0wn0idR9)E&%CzCvOkKqQXEqd%!Y
z*S${4<&lpsP~w?#e&qY@hlF0gS#!tX7m484{JNgIzV@1Lpyof5-F6@3qGuZa#5m5&
zLXJ9-DTS{})HJ1X{9X~jIFb8LWynbuOt>Req?lzdJw6k)YU_plF!V_|!T8h;byTt&
zsX;YxdiUZZMvf|jS4}Gh<AA{EsFevZE7-00OYPp>U!S!{$Yf9bxsGVL*_naBY9JA$
zC6RypU#-=<xp1>5r3Kd86pl+4Gz>-8XjvYoQ?rzxDj1ETv1DP<)Z2NyBp#CM9!0^o
z@m(SC75q^r!gk>%QX}Pmn#Zsjezns}X&A%$LYmM&-F0d$$QARJM{y}#hKeXEo~4rO
zb-dnjQNdKSEsx6DYK7?}?}EOWg6vCBc)x6$^kDo#FU?Pl_bksG^B7)pr{0Aj8^u{#
z7gVAiZZ$r&;eL9ft{&x^TjIZ1^F-I0G$e7ad!QMEr-P73o6wz9oeY=u+rhUEho4iS
zrxB(4)!aMA7G&kUF_5Zr`t3Y(7`Iss9mS2z3qF0hc6>|LXsxU<*nU&I<qIHnBVMwh
z)7WH)MJ&H~!pXyk5n;v%Z?1aTEU<R5RTm8h2EvVZ=N9o#q_=YQ=YC+FnKet+So@+L
z`ijU;*V6VOG#4G*8Hh(DO?|jk*>OTbPi<!-f4meyVfq9THzTjm7q3(&x4jA~NpkHZ
zhO|oLyetRu1o%$w8^%xm%6Z0#ixr=1-^AN@X4=g)s|+SnjAWNp3$m&)wrZ;f@q*c4
zWTSDhQuO+}NgAv|yszFdbbTVAMb@UD$(S-aY!0M<&ro9;1*`fpR~Uxk(}jo`er#Oc
zvqWGX5wGU>rX8Eh0$B+3#ZYuX)p=pjGLiEUy@#a&U-9j!w)>_~&JVDx55FGLhTF_B
zPcYU?mPb=Azhjp+a#BW^=Gna<PB%YI^JuQkMNdIazWZZlX!HKC!39qoYcnyjZ{cUG
zb&@Zf*hUpsj`2*l=`Cuk1k~-1nA?pq+VMuClsQRHs9ILnm#Sa(h<!pV>NhK91=an5
zND+>IZEYM95_mPbiUm(o-?8IFn9>_vU)JjusXJ}Vhq!pgp;O`Kc7MQ}u%BzLwprkl
z`b6kI;#=5Ws18w>s$e(H4O)vXs<K<2d*Q$l^t%=Z%~ZQe@q$?-nDaxzu<XCgZ%i$<
zE`~cAisZ}p#iZ$FC4oa!?ZSv_zM9nz##hud(i3m@1f&jr)*r9upr|)w@b>MhX&VUn
zeffEXt~}dJW)#BoY$lF9&dp?e6dfm(Tro5!xRbP`D8`c?<fkb?iczfiwp=``oh-^|
znl!as{2xPqRr+Uinm2aOW|V=XvSUF1=#q=FB^TZq^zN6J$R{1xrx>^Cb+<*|CH-va
z(dc$cpj{#kER~OES*|orz4;UQ<p*RiJ8L4|m2WQ+mhl*(hDp({;zr!8EpG{xS;4|k
z3OokW(;ji=XY#7|h+#ws8}QsqAiTjdgidhcjv(SNl*{6Ht0}~wk8+_Q?KU-uJZhn|
zzpLIr@s{C0JYPJFek*4c#?PeDmPI_$;!PnT*RQt`@GOhwY2u&sa25`kM0))}f-;|(
z3^ICJy2((Uz}NJjBF^4Wj>n$0-71H4)hkF6EXpOgClC^up#MAh@+wJ)`*|NCBQ$!F
zvy2p8T4_<W&&KWXD<QuVJMpaN%NE0pig2&GvUrbv|2FA5Q8n!0-sh<xj#Qmu8QxPF
zN|FF_j#qwM{NjDx=jxxYLyUIoHHsH>2b`!rCy@ae0Uvia|CK7hf$dj|p&9iuQ70yN
zFY(N1nXI4EJWN2y368huqDuUDz-47j7_)(xIZExoZuwl5gf`{notideTo><z0NTJV
z3?_2bj)&%SM7;)KnlTui<dZHUCQ+;wR@%LWKgPtGv^z^*8yrps{*_GvvuT%g5S>mO
z!<wE|4%(tC!;`<fsy8(V?jdT_Af4o(kYC})a@Bc<=lg(^ygeOIlB!4lIFNPGn`Vpx
zl2=P7dM`<g0g64N*C6{HV!rl8p`#Ajs+96T|7s5aE20`|^;fvGN;`V-J}{MoP~{q<
z%GR?P-z`F-x0SE#7s;Zyn@~(H&{bx!^PRUx*GDs<1^(#BLxU$`V$5uzN}6~D-2d{+
zKL$QQW3$iCQez0jd#UmR-WP}`%7>xI!U+&CQ<=!l$QSlsLw}YoYRi5;%F}(Gy^FX6
zNNy52+g$VEcn~vUFg@5nq0LU{9FjFCuOv4Z)g3;7rr#0zz3oLl!tP>Lg8`01iRVA3
z4CC4=e%dGZ;hXU6n<kG>0*7rjoK+uJwyo$)WkNgWt*uby^R^mq=KXzs>f1AX0_Dnw
zc2*-QE**4;(!AlMg?mf;&bwQY!FY>KlD^tLpOUTOKfA@A2v|lc7(HSF`S*_ib^M8M
zK}sigr#x`A^-W{bXDS{@cCXuxr=@JKg%A_9nr*BH)Bqj~C1ST%2JQT+B|KG?Q+q0+
zElj0no8O^aMtQz-ovngizuV!Y-NO0jThnXb57w+HVwgd%^;KNnBn(RayP9}O-@+5u
zt3g!qNC1mSj4x$>K!10fGcS64VJNMCjqU6G@KofoFiz_WfnMOAYLWmC@jJ$D10X3$
z-&m=t9CUk5T&^j)-6mKWn;e6Os7Z4EdCEhe{pu%(f9g3czMo@~h54y?wYgvC7hyS@
z%+G2Zh7mU^(3k4XQxDv}`3I8$C?i#)0eb1TB>yQ}>Yl_s=DU-tuv=Y^ub4KWb8JZN
z^3oPCkBf0{3syR`Xn~6Z#+N{P5<^C-WBG?0ELE+5$<7)j6u6h=N~5`<_kvhh5rZA*
zb1?-w0+LFBemv^vntw9zXr90d9>8LDpR&q7)79e@meW1O31n^*i33<)eT|omf>#27
zP^mCq`Q<=7SjbC5Q7#je_m2lRXJoi^`01!1tv`bKDartGF1&OD)dZK5z3naP7;uE=
z`=3lxnt|GDKAj|O!@xnjB+2ntqPe`SQbm8_5JJl7DfPruKFsW8VCB4reD$bBoZCq>
zg*G3Z<jK{D69CpS1Z=dOQ}suX0DD9#VVnHDBKi~J!LJ>IVfJoof1WfWzes+3YSNhb
zLh(Pycb#*G&!E`!`{SB})Tt{mK<<-C7%#tY&eMm#Ewux$dh}HK`=kJ6_l*8toqzMT
zAWWmd@NFjD-RTwsdi%4jH-_`|8bZgSRIOJH{YCbVbUnnDj25x`<g-_#Qy=IDD3ao3
zSc5VF7qa;2n=Yx9s>YH||6JlDDT68=frU^;+mWC2q(=pBKclOal7>U8ViBtmA@<w#
zPAFsrSYM}%09YGL!V5vrWhMy?q?8O(v3Ler#MN6~ePq>2Vz)eh3Lp|dU-3)T*Nz?p
zm=*-qxgEZ~(e-wUTLHhT!sA#oz;b=OKs-w@E&uY3R8aGq9!o@rH(j~090t|>o&lsN
z6~FaqsK)Pd9I{W#7E)@8L1q@iznrmKACW`Njb>9U^<!!6OIDW#Da!kw-|giz@To#q
zLXB%4)NW4`K=}9=EVP8nb-@_;srAA(f;_|~U+XwU(P=7owFIYt<7Y4mB!f$c8J+Zg
zml=!__kGb%-;~wbu!p_9?#6cSg|w3)T?6NBaisoy+N9joQiRLRAIAOuU8X$4H&7lA
zqy;;)hx9`dH#3<TBnld*I5sG6qFF3lhZDvfxH`nxZ6^rj0d`zfK?0m|0529|q20u_
z!--kQYXUD7`~k&P$Qxub<?opJluz{!{3m(H>nP=vH@<YLHiJO1A4j~w1mzdkoOv8<
zvr53!J}U|8?)y07Oapi#<nD<B<XWO9lg*2nqT}(;4FJ4FG2Z)hWsLyiBhtac<f9`Q
z(-9vvvvBS}{geFfsprztBup&T&N-8~Mc+s}ChL)qfbz5ENk7b|TgI=BcccjryCFfB
zdtmu?CPk$*-j_z7|08JcPL{i_tDb_+WtSKaumDBkh>VWOUW!tAWJ3Em__jVuZ;(p$
zWL&d&c5PZpT)(fL<`5W)BDRM<qi(jY%ylh(_c}!~xot*exgk$q7TT=k5tByiH%Hs<
z&6YNgagv$1Joqqf%h2=vB-ae+GssEGX8BxOn=I+@#cYGe-B&~)h!WXl-TkXqNV3P;
z!D4J1E9jHKm$?3}+pXSCeOXE@DNM~&uh<hnh?ReOv<6Nv0Zwj7VxoUIDTXzKwdHdy
zNr>V|lCl{q@daLnyMDc4z6`DUrTER#REfBzVG1lSd@?$2>Uv}O423j>AjlkUWIw%4
zibaX{&-rszUN~{V3(e-6GY#W6rwiNBCNUbB6U>N7%1*m~{9(T$)itL5Q6*9om2E%i
z#1aAi$WMG4(j=<jFuE*!5-0<|sY)&W%B>Lwl@}MTUJ3H>j87iWUB!(bv?|j*|Nbh(
z2va%uk-fUp_a!6}Ma-2j;aVaSnr}s?>%*BS`QgbldrD$>YB4&iuN^O$aK6Xr;_m$&
z_w0N3OEY=dQCiopZyW&9YZZ<E`5j%o$e!BdrTVXx(0|XHZ%4mM%K2(pv+obtiW-=s
z?WPpx+t!L^;KdLYLCgK0M^c&^kMqbD;Molj{pPcj!Lo5T1ka?~1EQZ-R{#Wne}*2$
zLtyaXkJ-dQS!h4e=ifC2r%==xY;lv4S1Z=V37$-gZXSOy7=-Tkm3z8jS2yDAq-&ni
zRIzhmI_^<#OF1)I`@*}4$tRhgDZQ-jrKAY^`I#<5<*V<=XyDu9UfIuF&Q`34UYmbc
z)I@fRBBkCPMlUcUxfKi`?I}@N8@l2UK;WzgPU{EOlF?O9krtKs>GmPXG|X|g1oX^0
zKU*HljN^Vy%qNoiE&Sw&C$a-_fU0nGxnh7)vf3`@&9wO{+Q7w)=IJHU(@-9!!XQ=s
zIxyz-e^Vslri?t&1arb9WyRF>-_#Ci$ZL?V#v(5A)&MV77Q5h4)kKrjtZ9YuVhb~|
zP+LhcFWpp;cTBqN^>N7*@tx&1iAB`E#a{Mxp+FLxDYcoJ<%F!oONi6H8>)L<Gqu?v
zu@biyP$s1?`#I(to?n%C&+0`{Rm{L@wo8&+P@7OpgaInH+vd5E&w`Zk?eW`YyA^a(
z6!<SG0-W^kUt|NG0h!c|{^5CcFbyM%=*6^*nS<n+>$>D|@&|bWwi8UP2GxX<xW0X{
zDzrZPVr?!kHe`{HkU9QAgyYQg@-^yoGarijN*(5g&GX2J{u`SH#CYNI!#+Gj!eFig
zD{?s6Sa+?ESJj#L+t$&3_?5Zab})?y8eE!L*6jcud+Fe<3bAGd_yMah2N4T9wO=Ub
z3TmcVKX8Z~y1xUp(q<vnH%*63>^17tl=PN4!V%|nBk6!nWKqY0=4|ElS7!o(@_13W
zQ&Gu4)W_gBUinCBrB%GjGZE;PHZ9Bqz(rRbJG6ZaSafgd(ZN=whg|+5-TD9GPbch_
ze%+4-eogOv4<tydo5@QXHz(Wlt2^|kNT{uNw$i;=U!LX259o&8(RUDD!F%}i_EJ(d
z2NWcmRUA(|n29kY=dOu11mO#2eChi`>bPW{3>1oY47nb=l<3sZfUbm;03X_$zcJGB
z^u@w1>5L6~fPTbIH={22CiZY6Lm-Ndz@gW~6Yb?79+69M_DQ+(B_{_qH?sTzi)8rg
zFZ(Zt_)k~E797h3%U;w(EhCwPl$~3i1({I#s9q!{wp_{DcrO7Gp%Um5e$b1XM00@C
zABhO7CGb3}!5;U1ZYCer<A{v(liRz)EPwli+FLm|5zObmd%YYWlZkG%r~_g1B)2>7
zaJt<|_8;X&zkM*U2V;H3?hIGG(Z48H0b9<n4z{Dt;07x(S+~!w;UWIb<Xm1haZ~Wm
zO>fNPt6~6NNd#bG>R$(He7k8(XHd<A2LEy9^DXpML1QXIuwEWtC)1`1GNtu(x0Wql
zwU|l*NbqnT@Mz<dwdxW2dtb?F)Mep>MA!W-o{yY%5fl|A4E<mc^XHYneP<S@w-;+H
z2=V(mXS-sPgP>x2+B(1Zz}qNYU15&;fPZlj?mGeqI?s{F^AsK{Rp%2l3jhYv8Z1eP
zFE728My)!lY^gf)9!l(rOeC~IP;I@G0?Ve=4X3R6llZxY^RAj+nxGGHNDchovjG2L
zn|CAB9gJYLuOdEXObE@ng;y><w&7Un@F>+RF6M=|@bE=~LPZ#$3E>?nb@!Vic*Qs*
z)tNO*!yET&wigsGN8ZEAfFGdiZv1ALj1oS<2RKDSch_9E<qh*C36$ruYR$(sD6Jam
zVR=Us!Cd^~53M;}mIy=yLAl|Sh}G;j#;eP&cd_R=^{-+1iv#Vs(eH03r}Yj^oOYn=
zM_j|W^M#;~@iNw`rP1>cPZ*E1(zgx<W_!I2R<D(Wo#~k^Ekk?v9q6Sa44Fi%wtspn
z#82~gc^P>j@Pg)z##K)#CQV?kOr9#O45RJg@5=$45V@kRy&`cmv0s2cwq_yZV_CZn
zzb|h%ikm*L>hTw^Yh_p81ZV=MmJfOM3?OYb39`8I(}he}PBF5XR2$Zt37c<^zo!3U
z9aLkq@wEU`T}!9+{L{#j?$UZ->ZW%+{3tD$GI6pM34z{>L<aqn=V^<VLV3({+?DrY
zCvPHvJmkEAq&y1srN?YuTI=wwn_g{{xX{0k(z-K@RWHn>OMg%ad(7Wj91-D8Po<Uh
zZ_ZJld$c$muf%W9(;3SF!-y>TE>A#0Hoz;47%=p<j>y-Xe?b9<&wklCrQ-79!0kLs
z)M{QC0t?4^UpuRyWA-lt&UQIdXHtK<gG$=wL}}yc0KVYHpl~LpF8Ozg#C9!8o(UUw
zA&k3}*dtDx7ogyCsN5oGa~uvwru>IE#q%;r7V)2Z9a#SQqWg(ubEW#3Wh;j(OJ8PH
z@^h9_Ph(u&tMbvj4^9#VgvWzAo%Tz=d}O-8Z0wrLyKh0S?_Z8eMq)$T^pf!KB#HB|
zcS)jC*vVfbx$Es3#co|KOBM%Wpu+)&EhFw7-_iet6!l!C8do^$p%O1P6Rp@fZ~*s-
zHKD9uAEvy-%?e}(OyDx%&6}F!OK}#y<F6ea4T&gC`R&Rdlz~o{XsE)_CRqvcvl#y5
zi9&l%*z^q9ZT;&_U&pi6`$EShxk|p0&Vp`hqAerG5U;7QmY-(PAq^4Xlz{Sm68o^<
zj3*izIY`X7kK-;+wByVS&~tczSr2@ltJONK*8s3y`s8byFYNKdS+3Rk=EkK6YWJOw
z0!uq-d>7E9^Ild-1^FdXQ!(wCB1f8by{X{y(7R)R;&@ri8M)TmZ3qh@rmmUOryaK4
zFiV@wNUElvW>rSH9sRCApBcFMRR%~FTS#;VY>w#{<gT0Xi-yYsJ7hq8i=@`@Dxj$X
zD4t14jglT^c3f2VC3}G{LJx8%;vBjW14qkYydq4$sxf{t?xqN(*JXA`lB}?`Z@3<H
z%|`fk08X;uy{s0(_kk}wpeI|h{3KZW08fP(g+n+g0&^JAEF~Gz=TA<(5RpQ)5(0-V
zF;Y33)-)Ugi)C%~7G!VpWOU&~f9=d;qd`bK?8MPqd9vZvR!@CWy?Jw@`!J~Z{3>AW
zk81y{z#CebC}i5Jz0=e4<y%wM7Ne$-HsqsG#Nlh#k;m0Yhu-e(OA$%VZs2-dSEF+u
z*b?W)Ryp2z+^5Gt%d%8=VdHSw3G)e!I4N6ER7>;Ss#izeeXJEMlRSCT9yqITdvk^8
z?c=_DKMc{busgqNZPBV1!$+2i1j_s96Bw%%JS}c@<s%-BtAl;lb1~YN%P!ooT|2RX
zza?B)2WyYVf6wu)Y245mgI&y8*YkLk8N*w&!Bi_Xrtar0E{gsOESsx=s>>EyX_vs?
zqP@|6Df(3}<NZaOSI%O@>%hyl-cUU47C+lyyKgnG((e<kcNT`b*Trar!+eVZCJ2A{
zL93Kwl3&Z~ePJ?wvq!&VS23@B3Coj;Q%!m7aatEV`ZE~}gzCwFqaHvbgKho&`0PXV
zoQ~W6lothy1IKav&+N{?#qZrkyK_JW`LIQKB5MMYp7t-9RPq73(Oo3ou=T1Er5=eJ
zuxi;8I%P}QGehnr4dgX2OuLgvuCO!ZCKP$&>%=G`KnM@{vbKk<T0VeRJPA<6?n164
z9(J{p3TjV!Y7Sq8ZG?HtFox7TVs0KIl9VDW&h36?D_4zt`L0>45~0ohw|PEN)^ite
zpGg1RqQVGZSNVKtUcOsZhUu|F6ms}AQEK}Gw%u*5Y@NfOWl2SP{eU4<nA%Pnw%}g5
zGxf>^5in73MB?;ZO$f<Xez&QDS2npAHl@VJHY({_cl-Jjw*zyJUK!la+D`d1M(16I
zj%zovE$X$*Wjyenk`HeS-W%N9Kew7&@I&p<RM0gFp4%6zR-|)}r{Gte`DV9r8Zv6L
z%Reh@{E?3Va+2P)M6$xN?L5Q^7%!K0=Wdat`&xf<ff1G}@=)w^#Csy=+5=lLrBvd%
z-&RlP0GIhMFrYw{$dMNV=7w;f=qee^gZHK$=Ld?<TW7oqfc_5*Y}@ivp_)y7{y<;N
zsP2!{2_dU6u|;*+`j7#{Cs$1{6N?625pCoZXDl=fO}F>6dyUh<FF^Jo5SRopKlc~H
z&UXbcOWpO6N6arhK0iI4s1;bp2{Wz?p+$dU3V6E!`lfCN#22l<*H8{&B=G$q8p9h_
z(@hmD$YR#Xe!b-b!F-Y+aTL%dWKe2*6r#f*;>m@HC1EGONZi-GU@O)BS#?YFY%R~6
zB%aSWtmjKGU8S#!=fok#KkxV|{j6|6%DsHQ9S+QV+v;7<KM6T+aRQUVJ;#_StwxYM
z8L8l4C?Jg1iN3mCX8-}gZDZd%X=8eda+=5ZIMp6?w744whz3A1+M@%a-WF_s^p3?o
zFb(P1$jUk1%!887a!_pjiGRIdHf<qTqsZ&&AXKVHYkM>a3|$VDwE`a<WBD1ZGk3}x
z2oL-m65&OaS4D|Nj#w1zu^*`kcteS-R-6+T@?Ak+Jew7%_v({6jsa}zoDgxtleaqr
z!MfL5FZx~*k|kT$!_xk^?G77g2t^$22rzaUN(1!X)>kd^@pAum?HA{JHC~<Ntkkxl
zoZ8O+FgqeURE<Zot?3^P-|#1YZglT7B5kp-&wjhMCfv&rw@KAv?<&l5P|yQ-{q+x!
z0R1?=)g8%!9HTGROAJinfd%$As^2tfWAr-gbU$IXE-M7xNoXplS&KIH{cEuvaV0OZ
z-<m?rQ0k+8Vkhur^20HBj4D%Y^@v46^4H+;*`9<VgTX2xh{~IvnjaOLbUa<QsRl5Q
zegIQHpG76QoqD;v&^@ZTfV{&&#FbME$CJAj^RZ&WVxPTwz3MZ=lE&p9$hQ6K-!dgi
ztK+B2h*j)>h8n@bd@guZ4biM~{tJM3y|0@en_gSJ#@a6h<}k}X4v}yAT5+3`7|r8_
z65qn2^Ke&F+GNE=i_atzf%dd@MCqUGfqAjXD=i{&B}^|Slu(W$1=vDmpku2g!X)kc
z6q%XzNkc6O42GSi<sw)~|GzxvJyL6WDrpVIIX4`|Ff>ck4yI52Qfc&5)I8Wd@rpO}
z8m|O7rsYIaifmPCXai$fe=q~Ie{r0IS<@-$&!wRby~uqj1%MZT@$vC{=!4B_P4$9(
zW;W_G`h&Nu2Op)IC}}K$_KB#(6x$mqy*v=%plITnjGU$D9RgU=NS%QhWx`@B<(}(g
zMt(D@Y>A78HG8_;z)gpZ>)Jxp)Z<tjz}_=sN+f}S1jd4bs_j3m2j1t&cvo^+{1mi@
zZo44O`IZHtR33I>j^%U~Noc62I<=@|&RLEalES7V^wUp~bkn_IziQ6Fz_*JwI&?vg
z%+*~twf|_Sj=TubtA{Hsko)!t*t+P8sLb2Ss>^s&>+iK|>3Rv=f3iyZ!U2l1_>yq>
zzB*7+kRngH3zA|P^P8%>B<^;;q=v7(!nx1nRH;P{{pM7w=S@-d#5X{&O?&A@lV&~t
zjP~`k$)Hxiek2`NYCN;u!f|a&$C;FWvNy+J4wzM~E^px&jI5ceOeT*3-BHE7Pm9gk
z1yCsA_XP%klrWa=eJWQo>wXG`YHtxfU2X6THrniROYdPW;RfbDIREGodRd)JhI_5g
zwS^diB>lbtbCYzu5MaD2x%{N4bSxaw%GAjVR`0ZOHn@BpAkQ|VQDj>Q)36r=MBCr;
zYE*^@0?jC;X)|@e5ZV<eDn2N?^&g;zwO0@a<`a?frh3mI<pD6CLLPJ^v|zt2;m*i8
zNJR2)zVl=kD`^LaH{DE6xKMimG8EkAuKh#xE&-Ts-)FID2noJ=5<ng$#iZZe<>u8?
z(J23hzV9GBA60|!HwWNkXVJYX+RN>2iPW{`%AxzV6ucgzmTw{_clFntum8X*mYQJd
zz>V?X-8Rv9OON;BuP6@9;IBN(T$WhuQ9|hP>1s8X1ufKSGie)%ND9EPT>cLlIt1@}
zVCw2A2Li*uE`Y8>+p$D`ueF%-@*l$!$bjKd1n{WEQi2WyGOfSNFA2=FD_JemdD&1P
ztzJo%L1<L|22GtoO%Gmp3@@Zgqz>B0h$;9y(0zUONFN>E)4UVGA@8wb<5X9dCmnpM
zgge7#mMjXI8#)f3T}+?q`h3rRle2-OvgybbJ{N&Z5Gg)YYyAbGmPmuLW^7*5-&G*(
z2&Qd}(phUBp9Lr}wIDBXyX0{H1;I=eXh5#&oy1U-nJ5Ki4e;xDmF7GwX$A~=?sA#D
zzfnVVL2HWo3RHdC6xz>NBL8Z!i%-sJ$Uw!<bdN@2%k^>=<HB)wvY|Q2q@;2YrR&4h
z>*<4h=)+Q4K(F0OVOH~{jsN--YVCeW&z#Y$Pix(QZTmtx(YrsL1eSGEh6lBpVu1x*
z3_YPaTRFg)@xA3U(@~jf(EB6C3{0~|i~2cq+&4N!`ABP~nM=3ZEgwX}7RoM4IoxfX
zGNhVMj=v5z*<;2|voT67AOLtoK;?<t9_H+QCi=60Jhb&G?e1Q32A+h7oVIysf0OtB
z5%rF7oxaibaMLu|w(ZGo(q!9Bo@{HfZB9)#C)>7Nlljf=fA>4*JkN`I(I?#Zb#1J@
z_S(B+pz#f;1*C*X1JEAZo9#Rd8<Pm1(g96K_0E+{p(7jH>LuWstlo%mGpxS2!C|Nk
zVP2qiaLIwAk?daCkCrH)>>4qC0f0%{jRIrxT20n+Ln;_dDaRUayY9J37YQxMw*e>}
zg0*q+wbm5BLP>Q838j0CAqxJAAVVTk8h&psO1Bq-`$VcnQ7)FR)N<gMQQWtAJSfRQ
z2sX!k^H5HKmx7BV#baZ8ng{NT$ZwU0O1XHk8E~41inqdg`Mnn#Vt^nNs4J-ai%>`b
zr9e6Gq9#bE$^6xNvj+VM03wG;Deu*tB<uqMjpwPgKJe9y9P}UO&f1p`Wshr%A5E)N
zE3!rI3XZ!fTBw+Y-?^IU9c$&l%iFEK6LhJc6bRO=WdST&3R(~U&l5X?+trP%shJZM
zx1(I0!}=K&|Ht1M9Gprt6>QrT@)2oKOwe6*u1IEtR@j1ku=o0$sl!W1?WrM!YDZ-h
znfp%RO?zS9#pOvH&}#&8?wDX*H+AzkC!%}+Az7ry3#gT6^A8=*5dkiSiJxueMEL^1
z_nFd?Hy0dgM(02odT*DoXarRGA&uB7f?J^SY8!EaYwot`6`R49vxcU(>Gr0Fzi07O
zH8%qZ9L!1pCdC9AUf<$tR%8*qnk$v!Yg(>X(n$;N6YI$dvfIc)mLI_E{u$%h_;?Y`
za<3@@YB@oEN8|)X?U+IR@j-x(`6#KohHDW&>LH+sj{?vj5LA;HjD9F0q!hNT=*9GE
zcZ-MC&v*tkPx>=n>K|k<oS8%dy_(WbLm%et=0><wa>uM>UM^Hu-QL0=QtrLnz^Ey@
z<#v(glitE@t{-~|Q;Zlz#osz85Siv=d&+ytK(b{QXA=CXMrO*lSM_iR;uN;PV6rym
zG5$=|vmnC;MWN?$C<SJWdQJd$kh<YqO$KwF9nOAs8)`%Z)8qO(BSSOxyE!(UWCS`8
znchM^1SI)T^Uj!UbhE>KPn2|oZ=*kC+8sV`Jmf=D)|q7pGb;A+<|J+PWc-!TV{GCC
z$YO`Am=G--j|k6Ritr*-E54VuYKOdff)7MQ_2vT6DCi7^^uEUoBwwAG+t*FOXt!4!
zU#otFVJ&-&a=Di#)fIum{~VU>Z?*JO7(fA)@P>TF+e9uLxW12y&G#Ql`%7g0PbumT
z01SC^1coSxds}&sM`azd0sImWj(gW_ToyIia0k+^YnSt*E#olaAB6A&!YgCDC6&Mp
zDadLw&a_;kA;z;>nYIDpMV{Hi0{DuK*D6P)Dy3VpXH3M5!7YC;g=NxJ?>_FnBoAg8
z+9V70(dIJHA{?X3KI2*%y49N1{GkbDqtlFa@M_O0psl?PYM(W9-Wm4A@4td_ag-e4
z0SI{JAmt!>e?la>hlKJ-W<I9?r-B<zs)$cTcZ_<k#j!{DzD-=8|8Nl<9@0%9F!kM3
zCpa*DzC|R^OK$4<WP4VLyr#>I_ikf&FW^mCRP5IrK?|!i4U4#j*(!TwFKB$jI?~v;
z!?kOiHK`SBC<#(}DdUDJxRa3j4bb5N(f?f^7QjFb?4ck2luHS{@1X7;+sn8F7)62m
zTSoemuB7{OVYJ?^)3opKrmJ{Lh=|eMa{BB*2;1|x!?RdN=~u?{IAGii)m*gc`N;c#
zuYv#pjMt?z&AI2>R23BhT==SY`U!yj0FKh3s>8KAl3d5hrdIyi^)KLKJX{bZyfTPh
z56(2R+!KUo0b+Ie&&y8x(p^oQWt%($#%q<Qd~>0bi?#3kyYoB{T=O$zoz+RJUi4w4
z#&8dk)*JPrI(E_bpJv`)6ee!DA-QffJr0@N-L``G8l~$m#%%{0kVf<+$FTU&{&*>_
zn)i>#T<qR8ZzY-MB13%Ocga<Cul8T^N!36kH`Jp!n$8I6!tQ27{tQOM>?6RPFuc?E
z!B?)GaO{RKunYJWast?UyzI{2njwytJbqQjTbH;#3woX!G!xJaJujhbjkM)T@Vr%~
zR5<(w6qB>A`^=WPOX@*%<!;PAf7Sq6lTV!!=d5z8`085pY<Z~hlG|_Y9QM}`^OUdV
zoKRmG4>>{I3}N)=eF(|H)6)<R4u)m9XUla6sY+s?!$s%8LlGFOm$;Z3=bINbs#B0e
zNv~6bL8m`)Q8QLi6phum4d7=#^-Kz0R^i%&z&_rOhK<PvAaZ4Fai+8JJqCjvZSlpi
zwQk(anw0ur`0PMus~-h*3}-{*sdbn4<eq!O1c35l*5l9S?_D~xJtPNDhN1M6SdhT^
z?A8rLgQf9e(>NFxiu~;5eKwp+k$B~+yflVhT1I%k=_%}JUnK}~tMwghj4L(i1%=q$
zoT;4na;vNyO?=edfH+#zTY0i5bkVx1Kk5Ed)G_0QqU;%90y02HF&H}g7M!3*&-PP)
z6&YNbb(rq}ZUIUq3cM;Rxq}i>%Vfhy+%<28)tToEm&M+(687Fo5!qDdGs>4&eJToX
zO0C9r%(6{G?H~DdnPXeh3RD}dw<9v}W6&v9ZGe+EnzaI|DS^l7RtPs&6F^SYLh+h9
zF}=8k(uiPB`<U~7pN0l9k-n@Cu@8skQ{)9sm_9*y&L2)4`(9e$d>|Trc<|Ip7q9h1
zG(aQ*7m`69Xg)$Pel(bnIZyfed=lo5Q0-qw+K1>29Mj!)&po_uqU!lETG3DnzYD`>
zpq=#bd&aOiB2At1&O`<^TJ`?=!$9c038emqSyrg8-pk*;Ze-K6GxmUM8z3TD-n|`o
zYWKwsv}+#$g7?IE8zpcVlCl99n{Q(rX#)WNNHChu3j;_84EDxPp9(tODK?es!4!0+
zfAvx=srlL23y^H0ivBup(er=)wKZY#83n5V^z>W?D9as`HUbm)Lo%4(_bZnEzTdxY
zkE>CswR=D;^4F$l+a<rmaGvS5b^oD=n@0BMO_5whdz}KQX>j>4zQ0;?UxzbFPe^xH
z|2hSKb_s!dj;WUSumTE<C-HmcGVrT?s{Xa?6UaNbT^1ye@2k>HlZ#?-zR{JJ;3q#<
zL8c#Xh#tEIpJUOBOnAig<I2i_Hm?W}-Q=J(RQaQRszP#~a#H;6!tM9U=192*h8(#$
z+rC{{0F%NE{Hj-9d3jBvgp#txUmM20!^8tzsLy|L#y$k9(IvBos&%!|mz%TMDx$ra
z6)-T=pVuO4fQr@v@8Js$oYYFq>6>nQw${0%SQHLYM{3B?D96q#lXMGy8PM-&&E^lq
zkUzcVdH8B!o}bSk0`|M4KNzjROCG%9@z+_{SFk24JzSRA{N>+(Itp?o-YGuPxe#zK
zpA8!M4CsY0H+<d@FfbnMWUqaOSZxKcZ{KSPQzoUae@5~@dVQu}FR85Cx@vVbJipEO
z4^RSJmD^j^?uQMxy=s2F@B8L3^2=zvxU!KsCuGohuhJ4yN-rqP)vp#PE*m20rl=u4
zA+2v|CuMG+Crc5<a?c8O(wb;}8l(u<cyth`1M#v3mgLS#EmHbJREpc+f;UL5SZi%8
z*5q9wp7M`zEK8Ls?ws$<P%hkxS#$>t?k+xx8EkEib8}fl#d+e$lw0F<c_G$GuY4xY
z8t1GoxpZ2>oitvXK-5}NnQ`(zU;gj3*RxWQh5aSO5T0cZb@8Rp8Z+=8ymSjDf8n{3
zD~Z7^&(CQ$t6-vtZEehlke_txDH;v@VcOfRNr^GAd$%L+4-&3W`&~a1_|l`6qs0!q
z63{+OYHJvu&f~DDaF<)PuSSt&;J~Ih74xMm5bk17H{SV6<xPi$3usDO3SKF+<}bWo
zyty;mSW$fxSG(@sx}GN~Ms6I9h2Sr@Ub9APe=9w@)T~_m2qIaC&bI1ROrx`keFvTg
z5L)j~!n*LTs;P5pLeghtkUlnv%hgtB%q3lLs2aW9kQX`v9rC{Xxap;qi+feme1-1f
z5mB>NE)~2nCaeC9URmrUYhwX*LmBfJhI@(24DPRp0I-n~sKj5ax!_bal0jVE%y2&-
z-`PWwo4SZXN)|s8DhwX??n0B5V|dfz1x6*99f#t9Lv9_Syd=u4HmsF<DvcYLW2m!0
z%i7c2Vdib~d*lO-IaH9m5>+^Kb64@IsUb_g`7VYlDJ<F$`-S5CtLB3WlV)oL<a3Oa
zufs4!_z>`HE7lDUHb(4-IhPE>;9wJ3=pmW(N7DR&CY+q8juT*R01<!MB&(|h_*22d
zLck5c^^*(!Tw9jM_d#6$;jOfaAsU9%=dFqJ185gs6ji&a{3HDpB_2D{-SlO~THQpL
z#2J#pPYLJz49|7mv1Gsz5D<(FAQs*iB5^n9Muz9#7k0=X`>j?bSL*7UIp_>_Z0hv#
zebNOQjI$=EbYCFKB4bV0kn6P1O~AnPin9XMf-9K*sTmvPlpi23*X!U^F@-3_3TWPu
zhvdM3;Wt2-CH?<MvkyT{+aQJL;&f<OjjdrRbrP*KS37deDpEc+`)-n{Kya^X1R<q*
zIhL+sr!x#Dljm_HU5NycXK$!?!^~6L?|nHfJ)C3HFyXGaryIZ<W)$cg=$q8>R1}n?
zy+~ZF7Sxmj*A`=co(x^@J{RUF*5@jWi7{gNi+}G@Hy;+&y42W%3ltv#&mpWhtH&mm
zoWAuYw)`pX!Xm}+?)n@+!#Wr-G}cQeVm@r;yH5qVd|5gB?v(u<M#Dr-dZ@XS(p4%L
zO3Xl2!1paj>OWLaV=xc(CO|LIpmc3wUvD){*I2pQ%RgGSY{mj{o*wM?O!u4FM|J^A
zG#3Jd+Ax>LyPYKAUB8S@IR%8->wi#l66UM|$?PvdZ0EmXUdpJ*fza+5^*S)WT3UDi
zG+rc*o^6A7toFk-WApZxtPViMK6^(AWX)lZC`=qPttS5?NYOQ*+1ee%>Saqn9PZ_R
zNM7BLu?(f9u~B5xmf!jBtP8Bm*d;GF&D+pHox>6KTz`TZh9&h}iyc8tWwFMVMDjw`
zdo?N&wR_ZZtd^hbx+yxS7(>HBkM`Q#e;mA5F>+BI5cM^I@o9Qu`tuj9(a;*0BtqNc
zmW5+3ui#SdE^s}NYpJYKPx~VaLlgb?qTa|cqHsy^<D-NirdC7{%#HMRaKUR@l<w+~
z4_XHuK<tFTF1-tg14X^JzbjR+<`)OK)uhEfr<aZDO0I2V9fzEU96&An8wT{sUQyFO
zQ1ImwjFl;34hq#DObMWQEU9(sR8SfAPIEcyLa^hg&+BVJszU3bcQO76k?MN>=6=d7
zYJ$V?l$pci=ES(z)P7|mAWCOnlUT^mLLaq&ZTq~50Z3F}mx{A?_$*Yw`!S9&{td%q
zl<-ADAtq%F9KWznNRThXt}7NUQ-1nPBnK&I3)D-$qW%NiNTmrh)H42)pm>+&l&xey
zZblhnxcEo8Qn?DOGit2a%(DX}If*d%!*fYoUGl4=jvm?p-<;~F{wDdd2&jvtS>!Yu
z_!y!j3~E-u@9B^7mT44Nq)x44zfSLn{^Z5wu78YxS2wznIM(0DXn}kbfFplkNK5Fk
zI(?#i+>pQf$LT1EIU$84q6V2W3+mqLXc`Yy8PPv0@6PSlKcO0Fhqoz@L}SokrX8Q6
zIh7gs+dL;Ta2CEy;hh)MFQ!@y*yIc5he$$#Xl{kkS5OWWA2$3m+4N4&k)(`NM9u>7
z?sv+na3Co53s+p7PAi7rLGc5vKlH?*O!MwGXXx4Ou$*Bjq=a&LPi44_aYf;mU&Ph?
z!#Yex;04rIt&NkJ|8yHlJMtR>DhmRmAVm<j|4$2`5QTc+9yfH#$c@$w)C~ZmIAT(n
zhPK;0hIUAKBK>vJPUa)Ds4dD0;RQ&27UhAlaCzoai{7S=p!QaRI8kH%XqzJa-^0t{
z1&iW-`J^;$*e&DIjU6JA=!_=t4v`}(1N3Zrp>X(~vK^^v)*tvZH%Oj;T9uj$<vUG0
zXbcaqXqQ++!{`B12c-OxgH~SLpA*6CQbn|x!BV+M(?|J!MQ&t3(*a5<5}83pgT*O&
zTlVBOaDfYIG;vY;G^*I2U!VvjH2}U446Jor@}brwc5Rfn9a_EG6S0<6!sie%B0tn4
zMDOY=pjd_A_)oqhFl30Z#xmX4nW*~c`|~N2{xi$$Qc|KdD|af?s;82!t&lcU4lVm`
zNNZ<Y8hVkK8qcay$J^!OA5l2cf}gwjyt=@w2OMgjhPup-v;Nsc*bE}$^^N>I8ArH$
z)y+4t3)#S=t<GqW<PcGkb)Zy#wbKveCK^*HrFkz@eUBY<3=LIpMA50ul+Ib&C0#)_
z@J`DFf1%r9EvQye{SWgF`!H`nTG@aY@!pu5#*=LQZl9p}mLv27Cnstwlm1>CH<Lfu
zd-HzfyWnBQ1lMejWEiIRhd_UNIW9g*yjuu$tS~yR@=03#Uq>UB1FQl#FiXI877k5v
zu3Uzm$`)@ehVxiu<b^r_FmpH3xoG?AIOQe1wZ*Uhxuef4G`dC!xFoRxi&abs$^%8f
z3HpqB0d0fyeaClTM1e~o?+fsJ!fl3ity^{vzQ}IiyR}OMKC$NAC;v`>5g{Ajvs8St
z-lR;WSz_P3FDIK|Sp6f<kwB-ZSaqg7TTu)SwH#=Y#SK(jLxVYK{Cj<+DLve}i`*M-
z&q5}RLJ2^avRF!<OnK%RC<9i(!WW)sq$DDP+;%*uzdY(wTi|=N%`oeon;>&)V*kB2
z&}7(^p+{w))&!`wp|t-Afh2lghuho_5CPU&5j7k6B3$qVKYa9&Tq~dA=(kFX`muAL
z!5tO<F)qW{!6CwlD6|E^jB6x5>Dfi(Jmq^s7&4{?l>+!x4umV0sLDcm^VocjoIhGm
z7S-89n+eP4GroeRW$^d}RhRr?O{FfTGZ=R+`+tXLb*6b}SGuPMX|Eg-vA(HVA3nM9
z1uPJDhEgk4#{zw|_~YziH}gc{fU6F46FVmk<aNu$WPKLO6Z2-x89@a4G#W-1?Q6Za
zw2XM!;}tVG3ZTTHCg;!y&_kcEgm-D?%0#RI`wxg`umZvQjS|ZpN86Yfm^~IGl7GH#
z<dMU=%TnmSf=%&Knh$yIJpVts6AbLHbN+Vg0)2Ce5TAlIk`aeXTfBT;5GtuK#*7{m
zQYzZEfyP+?5R44|@8N<LVJP(f8P{C!o;!^Yjg?#eTNEbaD7_brcq{RMKF8>|3<D0!
zEcSM@L-|dRbUWX-w0>B!JYftvPMRacv$YqAvEx=Y6FhOceRC0pWM;>aAmN>$AX~jh
zgN;Hf^JqITCs%zWC(#BA!!7U5>f^yw4(56pYhmyxiXZDSSW5G&;Q!7hl0T+?L>r=y
zXam@vxe0k)Rp}N|(SZ9GBQRo_qT^djx0kg~UB^(v0_AXWp+1+7q+T}(O|UZN)D&8=
zTV&9g=V#v3-%4C}JLI6_qJbi8$nK5-{biSD;DA7^>W^9WgsE6&7xxdb|L)KQPz-2B
zIWPsd4bjjlm>Vez(TlA2Q4l8)&H#^cvH~R`KnYx8m-vTNRu~#aO9_gxb%!V;^@Ua|
z(89ylYfNIsUIWIUVR-Xzkn;($uf#u+)1T~8*gg3OEee43NACO)$=!_={fD%ur+0rh
zg}j1E8d&5r?3JDHyx<&}?JftWyma|(jS>*JfECw=>=NA?0VV}f>fnwZZt^G~C?R2x
z891kxU8g;A6H_CDEk9jdL;;?J@8-KKU{<le`*-Kc1QYkpn6IU|6v}`{ij3M(?%+gT
zS$r75c<~hlCmz5ieN6RW$Wo%}rV3E^n?X81v!;YfaaXZf`?#xZ)yE23-9fG!dU)i<
zL2I$haCyt%4L(&?4AZ!5@z3)d%CvPgA?C-aQQlg?eHaV^mIU-iZoqN)L$xac>OT^4
zY8dcX^g)5GDutoWn!&o-0N!DQX?XtuUB##F$!urRz)>VQGSs^~GWPhGG-Q$25y?x*
zutkS7apZrUotILSr*M)Hfe&ati(eUMZ$cMu`)!I2Ou(=SwF0C`k%ocQrd^X~ub0Z6
zf`Hw4RX31f$W=GTMlPr_<22R*=y-U*Aymq1gGHql1e^#2)_=@`u!O>lMWPNk2v?B0
z*}AT^t0|zrs+@xpl>y!hm0_)<vKzMnkwj^V#XKlBzKbeW1X|vMASa>b&Cb^Kz=!V3
z$1h=OiI$A1H1boj+nx@*^{JV*1%_b@UBZFHBVgfRQPUnEs~S<)8=e;FnGS~1ykapt
z@LcLld`#d~TKeA|y<NVDeFS*Y=8pO>nsC3~VY7f~!?Sje@5RBBljNdjP=cNVyRB{}
zQ^=Y%5A@>V!QTdne+3|OA8|GGfkHfatGaU2jGn&=L;s$=YUZ>Q{^tw1<xIe;`A|;{
zGE)~n>y1^oI|BxkJbKO1S4jcGiR(IG5J`>9D76s-Mnw{8J`qdLhH9vWkQ;H6Y~2Qb
zjgJH#h@5M<)AQTMgY|$_f&KZ;@J>kyw#1c%ZE0R}`^4UcN-WHN^?s^(AQbBKtx8^j
z^_U?${u@=5gx$0woWe+_Y7gDFqX};yf)nslL`qiH#OM#k&sPBJw~Ic=y2KSS(Dz<*
z;IhcCL{`D(mU>eo`8jvE66}HPe;qQlH67-J!eJtS1$mIaD|3D%80gP!s0{VFZy+uT
zJM#o^Fof~91alOe+<g{#`C@12IR7BUyt(RMC^7>SqKqvH0-vM+Purb-gZ~XiLDB~D
z6bFTzVCT5wuDc1sm?BZVz*lS$sq$x+bK|MSO}3|3A0Q{Wwc3*>)L>y>kuaAcaVx6R
z4s%heL%%5r3dPram<`i=DEvpz36zLb_u}DE>NU&LGv^}bbV|iPWWMbPGpo7cZpXBS
z-e!@H!S<b?p3bvnPFuE$j={AsW?>|8*q)c88K8b|&r+W;bZ!qC<qM2ec5@Djh)#Ux
zPFr;@?;bHB^kt)ZftXmp8vU^8mA^7pR`MyHIHHE{7KFhLtwLA!%JUW2Rdgv{I)7&9
zHN_%27i7O>i7*Xoe0Uqy{{}^B5Ur{uTXC+T%H5`}Q~_8){3~ua9U!9BZN(eLR$_h<
z0unJFbQ~(fQ=m&i!f=yOEzPt)1eTt4?M~j4T%MR@kmtRNa41_j2gm&j>utq}1`rHh
zWSeG!pLaO{C=2E{Tri;AU<P<zkDsi{&hm<+%s_{LY2!bm2~PX~t;<(;du?&t4O?8s
zZUAWnLh$~d$FXQXS{c$p2;C)A@s(<VeXGgHNChr7en+@@Y!=OeKsbM@yEw1k&xt?M
zXUZ@HxkQ6&ebwk$$*;E77Lpn!4z6m%_RSv9ns(&(jT>JYIEtTQ_LaWu;=bJne=V*J
z`FNrs;M`uOk|`dWcAfXI3n~(=_>#8zk_KLZChPIc)~{n6WRi<txWG;R`t?8X3N<mE
z>kdEVxevR_Kt{;ERa<{?p_^)&luYxDCA)l7P&r#{b4yN|&=#On>WavjaWas(+3Z>x
zN4@o-z+|CwJfH13FU|syf3i8WMi1x2j_vZ8*0n0ELD60RvnZ=3XOaH^&~htzmw*7R
zIb}OR#hI?~P?}jond)BYWx;4(S<y5m)@u!Fhf|nFQE=ih*hoUD@sV$0cYanu<UdDP
z6aC)=BLzrZD$ZOO9Sf+An#N`c^ujQqVj7!no!3wqjNh6+$C^tQdoog)Xx)6VCO|Yj
zi)Q4aiW_bU9Lnt&9x=(D69ps^ZAIAbYpW-?75~GBAzul$RT};Dxy%F}+~vj??-Wr$
zRrn=H%FfWF$D?z3&NuJLYDvsjGs;XDL#{3HirokMl2K3k6*cGX8H+IbUGv=JvB0zl
zlQU&fBt&_|!d*n<#Lgt~LY3MH7SASP`TUyef_-mib>Wvl3^3T5e*ryKMEv1N$efq3
zgvN!#o-4l=OBO|JD7EI;uO6FEoN0mCB>-p<EL4c-luMf;cWya_*);Bh<{nTKLt~QP
zodigfww(0=jjoBUd_UQ@qw|kolSM1HSQAN3&}e*mKII%4Wuo}ZtS}3ROu@haW#5lh
z8r5?Xx3gal2&pJ)HyOUJVIbrl3@_9?@NpPRw)2v7gc9Wpo2cdB%qiTQfhJy;vdIc3
zAM??kI(D;1Hb@|scKp|#1B6uda><}0&5R^Q+q^F^vSU59h-_@F>c>r?Mvoh7-EnLC
z$FP8hnQij?UM#{$u5H!>gj6Z|u>;0d!fw0H`cQu5kz1XO7kqO=UWmd&wlyuAIg%yl
zQ%qtT9G*@D33{b17@PyA@t!zfeuzc5lM9eG3Le#kgc0!KKKB=2LPM1l8;Z`$Z7-<Y
zS%iyw!cvqw#M)BAP_N0Nf0Te?<t>-2<$Ao6SSjRzRx>i{%l`slp|V)zZ<NaWq7ioO
z^?SUnwI;UhtNPk16HLg-yh~lyjNGA&rRLM>nbg*19Cud{Pb3`SrCPCFiwoP|tjThe
z3mvEwubLa52gA&TpW@?35V^SdH-~)*l)n;eQiOY-^W53>K$?FMu*UVgmg;qz<N7DN
z59$YmK_pJI(6#-NljHpERWw-g^VwfeW*RgjlpA()j&g`+do36od*rvm`f|L|pNrWc
z=|=XuX=~d}KT@RJe*^{qW0KUniW03ljrpClC{mhRPzQ4vy7u|cskHFvb{6T}g>BeU
z+*@`H+Y~1($+D>mlv)s)v(1J7J!joOj*7x%sfA&rAQ^B7knru<)1nDFeS-kL9gV2>
zZes&bwZ-*t6gmQg_oRhm?(fuf{?5AGGza~`rN0Ivg44kRnD?~jUjmv@2ARe5Nk7c#
z%L4UF-Or}A(MzqwnZRb0FS>7>SbjiJc{u+Z)vTfE9i5Ls3}n0q;#WZp3%)taDXF6B
z-O8m3H^xWLVu+$eM;p$9ozi$QbLZ(zZs3kC{-==Ify5~4B92=CHk~kDQzwCcM~tfq
z`f`$ROj(DP!Oz72gcZ9R@|-PMKtVEt>a6o&XA2}ksb-%lg5|+Q%_R)lkI@sW5n6P3
zI1!dvpmhARq%bscn!h!q%(i>WM8}Qtt%n(T*}mILBj}Xd8U{X~B#roP95m?;)&{)t
zsEs>$`J(1l@4Pk1e!yR1;jYqS$1UW~bS2Go(xlhFj|y2Ng2us$0+Vq4m(%yH)|9#7
zFjJgzg6x7YVg_uxie3f!R283N31`3?>}az@$heq=wWG9+{%$|NUHovr$+jtrZ`wUc
z7HaCS5?IkCQDVsXpgcr*g@6PWig&|9OM)E=2wkWv*zD6RW#rI-OX~4JyDmCwsMg@;
zrKqK=3Y)g@v7OKat?l!moggQT;&=&FhcXK+&K3`KtuXWI%|$1>@YaD;0add=ESzrf
zyG^(yyA&Y9ZC2%vOV=A1`R+YzBX^&Y&jqBN`u|Rle8iSh?JGeJvM*ZUZO(l&uoXmS
zA4gyaEJ`M<h&BoA&o67Zd|S@DEYS$w-M^$-CdnU;$)p8o)W|IfgcJsypS`Nn&#kW)
zgXJ~&>Szxg)&zml(#gO3D6OR@f2BjNVKw4x-ufazLALv^e}0el4tNWWnOWQlPF)XG
zbnl!b6Ye@e_+xK7-&`GmPDln6{CF)1A6UcY_m<?AR%c!GDBo`Iu&ZID^GPfqK=pXx
z&#uP>&G)1Y1ILgs^uT7voXsJ(r}B%OMy&&^gi|LkR5xS^G8PJ$*1nV#NuAiPC}Wfv
zyz`YGY;m0!XmKqhB}uk!w#RhxLGObz1-fUsNk5d7%#2K08tEWD)qHokzXNt={3Y5#
zJEZ8-A6nkOkim0Zbo_~gm8WL#K>RZx=REwY#c$*#3OPc7=?~r8*uXv2pZX*X{4}Z$
z4;i0O;M3+6J2!dwhr3HCN?pGGc5kHih^PQj3amNM(eZ)-BC8=sh#bjyoqm)^j9{{E
zDAqBhQ2q!7U<%~l{!4d&MWFM+XaIsghcqf+IIl4o+AKWA6f3s8ve7N6y!P7Q&!8%E
z8#}-&e;-xBO>-uMh>?Ama2w+wR-OETNlZr;Im)NB(v;zCxHNOEWdAzzHg;gI{xLGf
z&jSl|N5q=m=Gr;fg(5}|3WnQQCW9Uok(p8ftsuwwe!>_h4JW`mnT3bL|Ik`C8AsZ)
zgZ$A?F6@E2FOC6=r)|Y$S06O0<DfgJp}zJE3|Ghu-eUpXpClN(7t_!0%PTbIE|7XG
zr$4_J-~d}iZXVb}7_L;M;f+5;27t!sUOfx0C`T>qp^_aAE}XG<AzGz51-Nwb(1!!v
z7~uLrtX~JZXock8%ue1QfjN%U$v^YdU%iF#uK};9ZF@++Xonj}rI&kYi_lk%pgR~v
zOEk$cCuv!V_N62o{>ry<3JuN-jLcrU=l^xFWVoJ02U~j%5z_d}ob@W&J_Jk@9WcrF
zoYHh|PRYsdC_joyeTAn(j@^9PHxsaCn#jUOY6yS-3o{B<AdL>X5J3G+p3my*ne&`H
z>ud!~gEC%chV40z8N2L6<nUEBVTD$PtwhMk27EyLQ|5xLh~#burd}%7e(NB;Wk-`h
zkwo)t_J*w<Kt!4devq=Hr?T98Sv11^puC4)4`G*w48+0r|G_z-ctA@U8{w^iTYPQT
zF7&~WASbHHefHn-knz08hN<gzZ<TcW+glaq<;lCxTfHbiXe-m?vI1~n&Z1*aMi%of
z3=<#{-?W<j_V5)yxs6v=Hg0v*m@+!@d+jQ$c`bu6mmjbH0k(;NmZj0AJ2POZ#w)zE
zL?nJ1d~aHlK4e|6t`b2DnUnzLHxtA`f(Y5@gN)GCz#)#5j*ksc_30x>z!|NK^eF3>
zmj(8A3$(J(@yjGXqm|vGZK<ecyCeiGKfIC3u1DhKx&DWkfpteU$By7F^F3U;+`z~#
zU=2xkc5GbWWv{<GLzU7m)s7D|(A_o83tmbA&iJ@RGS%}+%4>0?vI5{MV>|vMx&tBj
zS_9<&zI5Gm(TT{*X@2bba4(FG`jzddX$UOe07e`WYTk3&TM=V+bXLK9CMR0@2;#p%
zpWF1))X%NU>&nUR&3Ud=oeSU2wby@<3WA;cEw-|Qnfcp3WxQqleh@rl1}rXZ8KK#C
zF{w<wcY=4))YZ&v-+SZW@#?@ZQJtvS_pF9qLoHehqcjZ6uNcMdx}drA^h7~QoroD{
z-dnJFZG=h-`vx~N@A7!WvCv7y$&14K(Xod185r@4rfc0^9}Fg*C>;Bm{}oi@(RSDM
zjn7rR^A91@^*y)ox-D_>OS7=HmHMpO<7X1D_HTfif;^tO)tKg9&%<%SrhkCaf`&bM
znld1C?B+1-TSevdk8KBME&OaA0okNi{8H&;7MQ7Deu1u?OMixzruVz+#h5MTe)hZ3
z+o~gV>*=qSVY>QBLT`1~_ajG7Q``R$f1Mlw{SL{6&2fFg4;U90<Ww#z7~-&HA*3OS
z8E&oYdY%v1PRc8CMn^#*@J%%r5*4-19xMWiq!|2473;FUXEt3ImWj4TKiERKOfp+I
z&06q(u)A4)2|(R=YjaNcs;3XFU(EIs9;`@SM*N+yrt}O+L14Pa3O#AP`^PDwb1Afr
zkLh2-GO0S&F)mw+RoVK7^F}3AttNctA8srizK(2i1UZ%F&Tvu0TRY0EHJ1T3T<)he
zF$oUpcb9HSg6g4lN3qFc4t*Anmu2k?7S{7R%Hl;mr4Fbj(ZU$%Z#wExx2tm{=^}IZ
z7WjWY{T4qsY{^!p`>{1POh9ZgS0NfZtC$v8)7+W-yXobjYQ)jv)FrZ3R6L_dx5KSX
zo1bguNBziaNkrVAD(?N=tF^eFUsjT{@DpO>YdgOMS8f-_XfMSEpt<NpS;9?rnK^qa
z?xftiwJl<W+?PS^uC-%ro$_NDx>)N|Y9OP;(f;oVE*4D$&h??R9omd;r2UzQ8XKKF
z%^&eWRG|H2zJL_8q`qTu%a!BRDxVa_Ow1Seyu{$G(jG@oV5F*InWiFFzofqMwAe<|
z;`(>HK5V2Mwez~vX3ApT9f=zB1klg(D+C0wafUr~_efofRna|%LSeO(IzTWqaiZ<;
zbYvs!Y>-bVHB*^$tKr^c)JOKS7^X`IzSa?95ZkjE(^o2d@S!(ln8;cY0s%&4hV|IF
zN&(|`{(4p$BTWu9A3aU>=LEam)RAGqrc%{QkU&|sRKQh8VIQ~u1a5mT=GugabEPkw
za4n&YZRQ6U7&)|ClNI<2ttzQP4^GXhoy%G>CBMs`3=D?!k#f-P^i5D|Hi&F2{SVd2
z`%-L#c7(i;_f)80rlwmPy^i$`aDY3YTF^sVCDIjNiCs{-n#m*~i$OabLY?LFj$i?m
z;qkez!OHpQrPm&{6-ac^K07ot+E?a;EDzXtA<l=aha)$K4tRxDtA5QL3{)g;Z0LhV
zyF~@Egr4-G%8$JPT=<iW--kXP`%BE_w%}?ue0SkE+|(d1opWNnv>N5)8radb)YfW<
z0~tlL_)_^rY+wTmRvW$Y%b-J>YCSchD;aXEilmC$Rt`VtIh|HzaoAO+ee0i0|7tuw
zty*p}-i3D!)<I5UiFr`iz|9F^1kNP9h+;F|=9`xPg%4f-9lyAKmJ4~ardlQ+2SQP_
zy!fK&-;F20prM2Ry#gEO|F$70Im+Or1j~0aDVXR(w6Ty8%?=a_p(njo>$rGu2&A{l
zgNy{gG{&`VPEpC8o31fa41522EDut|i>PKH#Y6OW-pk=<!LCbZs9N$bqt6PC4Hiuz
zD0>N}<fKLAyi==t34Uv$l{d`PyR#QeZ>`c*scYhYlqa|Nv+M4oxrt_}b4-ah^0T-Z
z8>!%JC4Uf-#2|uGayv8{i636ot)o|7wiGq~Lbj`&LV0RQ(KUk;XSHn@>RtacvEE6r
z>~4_iZjkIv4>`nEa{XmUeK8EKB1&}+O8onSu&C&ql1x2u9%Wcf@nY-qmOurcsN!sr
zS__7JJ+jy*;5D~rFSvfqsPSJ<xOjoCB>HW4^xR#jZUO#gIL90`LiJc&9%rj`6{Xo~
zx1SH+Pt}9i^jNE7wWJp#Mn{LSnKF}LQ={hG=^G#f6J)~Zq*iS8nu}_9`*893vwgp>
zS~r~tTyerc{`R!C$1t+yERC~IeO=eDM`<ZlSzK<FK@~Kcwqm%Ck7EKKtBFP<<qiVR
zh^%Vfmtxn4=`DC-bl9A#BWGMEiLbdLr7+FQYVfBxi#ssM$2>%))R+9)YDaP2V*~If
zDSmUJpGV5(B~Q&STrhY*k1=9Rhlw&`_p{A^zU&55mR+^8<jc36CZz#}m+hW1PfzXP
z-X=7+>>V1T>T*TDP};jhBB{~TCOrMhHduQ*uhCYD3j7?=b9V)Eo-Zj74jQ<A)p92`
z3D8vC?KDizN#;lA3l*YfuJ#?nNtGd_Gq)Q$<@cJ`=nY7<Er2|+*=5U8>*f={v8XO%
zr2GO$cdqR`M~J52WS?6FR0S{vN`6K_34@h>rc~*j3#SeX4V~-Plp(c<mmudSAHY%B
zq-xL&GO@W)GPvE`uH<iIHGNkI{q`+O4Vt{lS^MO2Z&HlQ)k0kCo)ri@Pfk(YlxfnN
zM3ufV8u{cyp5<$awu7Gf=Sj|E>p^m3nd+g^@{{q-Yh=^V;CjuzV2rJ11v_P~&(0C5
zPA}!~b$Pp-rmuf_R8bkg4BR>)+CWppYcG8sT)Mw7qjFIobUb~`)|{O=%~cpb#nE3M
zTqwwQG$5b_7ZvNx|Ff%6BlwOW(^vc}tn~CE35QqvMUN}JmX_(|7qXL<iL`zM?x)4<
zoPfd2rP4#6L*GK*>d(sZ5@P;6X!VWy(-;xzs<hb#obJY@r$%z`2I8$6U*xQ{f23)H
zMB%_54uZH9lgvMX#kAL8kUdfL{8m5bl>#&?j2Gc}gnDI50*GApi7$gSA^Pi)kVP*C
zP}8Dx5FmvWTV!+_*(H?=6{PRpQ`kq$TE?l(&`hompVVY$=?-4ERSvWoD#Fp$-Dtf@
z1~fA^;u}beyBtz#hpR<JMdKD+@XAr*N*(Ib)vq)WL0@@{3%^FBrJJ6}nNZau4UI7G
zu3S5)EUVX}%~k$nN*LT+D}0bL5&}DKX=%-S2J>U39MK+_KS0_RWU>-vrhXr9PZ5|1
zS+~F0sBoxFZ+O@m&OMw}Z59o+oH&boe>RivAAs_kAfPW*1?M&p%jTKaK*ScL$I)+R
zLH+DG!0x%~vu*@hzWLE~kbYiD1xV3<>y5`Wmq^j^yS>)whDQ-aEm&9dnq4QB;O-#>
zRvT4`#ML0VE+1(gZfL%3+{`tldk_)2%RbI`dbbQ1u4tH)jUCqG%HUDi`aZB{0E6?K
z&&C7^5-=I6E!lW;yo6@5(Uoe@t#DaxN4sAAA2wE+cfbf1i(NFB+I{s`Kee$5U9e>C
zjy#?*YEnc!pygm&TnVMxP))Z}B4nD>tly@eH*J$RKc48{|7ii#tn}FH1o36+x#9_f
zX}van%GJfwgMAA`XActrj$G<T-WL@1;oln|l;w-5j;oZ+{N33BuUikf_h+JJV1=95
zojtohv8OXQMZd<1=@0tW-Wbp9NfC){iV`D8Dw-DXH7j)cCsB7QuWT>N3`5Rl%VTf1
zCj#fu<iTa9)Y~3A8GfM+Rc9Cg8r}{Oueo|7^{-B)%91|Orqa)(?%~aKcCWIphI2E;
zbXg+7_YHjt6PIC}K4CjtWx!O=Op4NEf*<@y_|?$abT?<15xL$;yy71B5&TQqrz%!2
z<~t5h_Rq6;=#n=)26a8E!H82o+1++?e@RFu`(hL?llLrq@AOT&S+_0tKw<s&j)O_M
zx%0HHTY^7jXm_lx8pul<p6y4`PEg?O;{)<G_p^?5C;1&5nZ(ZRL-VF~7Bnv=mj6hd
zbhlP1a^SqIl@OT7qB2rDZ+BpE4s+<$OU?6us`@bE5O;saSUz{7g<GjM>`N{1fTTi*
zE=8Zf4+HlbD4ZajH7?>hQAa^rqN|KvD?br=j?;Z3IV`=nz7~2@M5Cc7KKB9&1Rlyd
z#lFzDxU{||J1wWgRAnRfn(zG>qZWKb6(e-j>el5!f>Uh~N69n5OP+QAN@dZ?h69y5
zv7Wb-;=QGEe;PHD?_)^WA7QDSsS>h^M5Gj1ZFzL)il0|4El2k~P2OOpz2R&*jkMAn
z&7b^0Md6Ffg6M|JPZnbL_FTXpKS4t5F>1UC?q6#emaLQP6J$E}-xR<tl92pI#%-h&
zZ1D{4=Z}hYbzf3<^{#*`)HQ50dwJy8TYWb=och`W-R89k*7kTw>~;5I_i{6VZS~{=
z+u?4FPS{q16?`kJz&Bk$Bj9C0&6t@S_75W9RF&Q94VloxIbx>*mQ*(0uQg|~w*xgL
z@A=V4Hz{wIs8ksW&Qw4UABU!*Y64i>75WC__So@BgWn8QZ7e(VjekzI%K{<ldlu5M
zH<NYGxv&XZ0*`a`mOj>~W3~&IBH31<^gldaa>=IMG+=<uY9oAOL1~vqWL!!<5B5U8
zflghlOmLypHQJor5;UD4!kiz&H;k#vs|nhQYOlV!mec?}0@`_p>kA_Y5mXy*L;li}
z^o`@+6u`@Lxl_^1exJ5NwLf#uGQpb!kYeHB0?|DnhTY1Zqo@u&R(<D9rihk{L(CmE
z6hpF+&<eY75a>5voxqH$>B$Q7%b#jT5L!lakMhSLldC@My@|{*K-GG~@uELdhv&c=
z#l}EEQFQunQG(f^Sr!z_BwG_zNBASOnC(|m{drP>?~i&l4wZVmnC!GDeJhFY83ZHS
zum<x3TJv{UdKEm-^6MK#VpUmcbX)mfe?A-@<v!g0sd+dM(~V8Xt~9mZ?bk&n>osGP
z+rF>(j?By_EUDq(_PCp+QD3Vx?d^1K-kqiHlHk48$HiaCtKWgi;l6rezgXv98|6wK
z53vTaBD6R=-Vg<56XR!VFGpLA?2e8!r+#Mmz?P#xz#pQ7h})b8nXpprRF<`rbfmw$
zB=F{$MYmW(cf3*5a`swbG6dg64gN%%`3hvy?>F+_7UdQwtH{;sU;~GVcZOG=4Ej&Q
zmL9JqmzeKG=^u^xFunN@BLoOTs`Lqho~tgVcXpp<*j3#e7eMW(R!>m8%)XLoJI|Ue
zEmG6rI3c4G%tmk8f9!{UYBEUmgvHG7raSWPrrZzg)E$KE*25ez<BDP<klM8BWM3p>
zmt76AawmYt3>?93<-`D0fbh9Kmb1{s8us!aKalgC#*?dbcN1)_m0$RZzFO#TmbhD&
z4w#Xv^`CT^|E=mPaI2lm1&Ry-PaCfD_P<bL1N-vTxCo>Z0yUra+t|Pb+gTw$BH9Bs
z0h_-cZ`JWa9z^<;1(S`3Rn`t1^xH*nwuJic<C)uogCUnOBuUhBFAk&(m2w>%nm_bG
zTqQv;;8G><8l(h0ia){Nza{}C?`C!NsCW~_&o72-47Ny5MgG<zhN32`$&}{n;gOc}
z50_2@;O0RFWdk)o+a9P-==ie#A~!=iW9b6_-?c<2a<ci~wgi-r=rkSOdgRglO+d*P
zPQrf<J-^AvbTz;mi=3(ME9`fQRU&anZF8o3lhiz_4K#!Dp1BNWhR`#K9XIECoB4#i
z9_w1roFUsG6TS~^&g@D+kgQcbza+56rJ4E<;t7j2G)`ZQX;t_k(oja?$A<c5#zmQ(
zABJ2Px`?_2<MjMUV9KL5xZT$}rLlO7`u<0#@0IgL!7E57QZ>ZZmqF2qNGgupp!*6|
z20z<B-)&Fp@682Hgesn;q6+0ELhO<2y~w7`Rk<l6z2k1Jr&``duH02XFGkn7FceT{
z=X$V%mx)Ed^eWqdN;HQgzLFrr=T4l5OujE>EDyr~TfX8WPbMxR2jAE6)U(%NURwvd
zf7|j2^%6moU?-wKw;g@t>y&5(32=x{+-aEbM_GPxuV`O=+*ssr6M|VOO}G3LSnbc}
zq7N7OF)cY3-_G3G#eqUdJ#$_14i>>;siWu<*4kfu;Fr^omIWesAQ+bO^sV#={*?R<
ze~b}h-y090<{;>XEfdX}Tu71U0W#KcdfzUTyCc^xZg>37E3ocfB*1ru$PvtC@G&2X
zeVjwWU_Qx0p@?-mk+X~MA4?=zNR)M+W#%8EEH=&bSTXA}c)KAKWF2vmWs&G)dI`BK
zvqxyG=(h7_t`L`_IeX#fyMF0BL>vdJ_D_NE{j@*L*}x%h!v`1P!ncuz5}Fc#N?SVy
zo@eJ?#?kv_T%heiv4h@-eNn8)I1i|u(G(FI>_Z4n8s}+RVm>pbCWjHiQt@IYw$!*K
zJxP9@rv55dbu0`Q^}TCr1H@%!A)ZfxyJh!9LH7VI$C2QB)hsdVdgND;c)MHfEYQuF
zx7|u$<aau(v?x-aw|4xbhVdK&21eIE^)qDJw|xTu_vCb8+}qfhG@`~{29&CNzUscq
z(e0BRjh|T$Fh*F^*k<8`+BQJEePPFHL_Ep59imqEw4Rg2%{!u;1Df|cSADl`#MUT`
z(o22<1F(l$Y0zL`@~V+y-U@I3{>Wqzs8f~$K~99ioIh1@mB=TJ&LI<^_mxegz)-<%
z*wl9N9->l>R|C*1K0}f~cuF9}^cjngl3J_=P9z)<9R!(&6&J9~%D7#GkqnK;0})#K
zjLv@hu87lMUCr61m;k`dO!_!spZIss*X7+Cu#A{=^QE36<a6+X<36KetcM69_YA@L
zipaLt7RV!+aD-`mwKObS{amkBu^v;3%LF0&5S+P8P5O0Ws$6n!HG9L)7V|IPuWi8a
zKyzo_T5aBrYi~D@W7cBjammTXePc(xaap-*5T*gFe$p3uVNtwVouns)(k)webpJGm
zbyUs=`d!PvDK@i|8AR{vW4U${z^Xi(SH_a(7EXk;KnjXR`2})$*Qt*P+&!tSx!I>+
z-v3kU!DDsZZoYS|w}@OM#12guEF4CU;|U*G=ek%hp$3YxMWn$}p4<&|PQErw!T0G}
zn1g(`&mVM`5^AC}yz=TP5v=`YM23oW6blgTH@w_pJ$OG*dT!}NNU0W+l_>);SXj-I
zX;x<-In3+C!xu)^Q7Wt(9t0mBTlm_UB-t&{qX^ey%cgeHw-p^TxsfhM*L&sqvtA<0
zGW+q*W!tw6=WFX03x;<QWX5GWY|kOWYwtUzfuvK8LsqCYP6H3$69WF#TY0lHHd__|
z<w8%`jI>~yUG;IM60DSNs?#2-D&4s#;4x^Jlh{R4qsf0tN^kR8CZMv^K3Ayujh9>B
zJwN5~su_ss$wnA8ZTsV|dCT5o+HRsdVkK`)m|bakw@JvdZH=mbADLl<1Jlc{L1Xg8
zPc#17pqtYK+epb2<Am+Io5J=`*#YI_=rTZPi$4O+(Ik8<6N<+!l>ZYi_D_`%l?a0e
zZt2vZMzmEs%e-v(OHFF+2~l{YxAGP2T59pj{XCwk2*_d{T66G)`NR^Q6>FHs)Cl(V
z>(W2Dep6c(DX$u8I4#Bfy5F?sYL!`VC@67}q`YWiqKd-+QU~&L(=Czi4;IluNoyed
z=5%s_*ZETS;MKY0YV=EXOUsQa@ePARZ)P@u^6=aEM3&>@{y<XF0_%$d)eSZQ_`Y_l
zlWl<pFhs~7Kc{-&q+}K%j!g7N#7kz>Rv100wZ>d*RJ~!(Sj+Chd1NDzcdpL$PQ=0g
z6OmUt)~7Tzm(r5*kpSs)t+2G&5HeQT?2LerI?eir%aYutn@WtOme$<<-8DO*Xsf*)
zxY0FWKhzL8P<frOy5<5{a3XDng!EbP8yU1jIA?uR=`fRT@@{Xlr~N91u1R#cvsLoK
zCUn-@Hlhqp){3deV2Y}T-D7*1f*ye$f9ax_eoEg0xs&R=hy5-YP=2xYYN_n-t$4kO
zpq%^K*Of{FgHv|yU+yq@$<hPK!oii$5GvB!UXN4a)hINf!R<D0`O)QT!FqD~k+QM<
z>CUw)w6t@Y;iP|KeBtvp)9<IfjwDPB{csOFBHhIuSYe=qZF@a5SdOPRouKRc%p^`Z
zER5{;uCpit0(Nj=a}%Qg)b36ZCS@i2yx_!;+Q-qW$F&`w%DI_M5cc0=oJrBHJsjOT
z$VAxXnOROCd@=y28q3Cdo4BEjI#-c03}fkPo3XS6maRJoZRfSaREwTxdBiw|;hln*
zD}YFvp8qaFgVO@3lTyz!^Mg%_DiGi*F*6Ao_qHyC!SG2wp9+y>k`QE)@Z*#4uRWtN
z9|vqtM#`gZ$Gr*c{T4x{9DiT&)MOV(Wf$lR*IQ!K13veK>S05eX!{YI%bOLF?%r`G
zZ660V02bPGlAxALYTkXi(oq|gR-tT`t6ew|4Fp)K-Kt?#60rGCa3e1qDiE^8h#CrL
z%z2FF-(`nF)BSMRKapAZQ_ew-UrJBAo{5W!o_(g%LY@}Vt*hWV=|lXWlvJNLI8uN>
zc^@GKEEnk4sLB0agBK<Vf?RV`#QGrIOZUzImJg}Qr&jq+3OVn47fu2Tutc+6rQ!iV
zg*bW-b|Dt8F1tpz8ZRI&4KkhiyaK@Mn~vY+8Qwf)apU~W&QHs<1aCynXdHIVChxaS
zzVugEXd=@9iQ4P(AF|U$xsJPe3RNi8=1TZvhpisY8dnA)(rX#kL~0_5H2w!P9{+5q
zFz@d$;D9RjscJ(Ij4JA<wkjIplIB*|<GWro5L&N%d1!XZn2?+=;P8Nd`&gm>>*k-e
zx7{|IiH*Prjc?Uw^|eOWf~0r4*0#5k;n1+!>$KMFQA=m-itSg_%eMrPJW8Cu6dP||
zNZIbL8OM^CP?<ae1XXK-#4Nli-AK|ScF(MMS~`-sMx`+Kn^S1Y@(Pvo-bQU5$Q!SQ
zNE`1KOctu8ZZ0EDPBNWEIeB5~+OC{ioAMRnZ+hZ&fAMCh2q!n^ku+IU=Hkh>l5n<%
zhb6o!9atEePL9u0OAX2bdVw~M%)0@Ush2WXqxuGB0?@gkn>-I(tvoDUacw34bm7|!
zWjnbXFp@r$og=1o5RLira-PbOaOmDN&U@Ch|E@+P^I}y&H+dZR{JtzQ?P4>^Iky#U
z#__VpS4u+}Bh#JGcpF!MV8l$l-L1~q7~w(!)iz@<K&h?02^pz%ut`C+Yvx&LwR;qZ
z%osk}%P>r5uu!bNjR8#+)uzP`j<;6P*`b&I%!t|$r<pj7dKdc%!-r1lGp5ReH8q@u
zB4+h(76Y-c&G0Kf1cdIxl5ditqJv13TF4DXrhh_zweK)nd?PK)j16W?n^x6pr2!l;
zwKE?+LQTyOsH-$rY;J~Xws(|k?at>AnZKK(_U^$LF1!ePJ?RRSjnZexlFH$vM4wDd
zhAmm*$CJObw4vsB>-!ayl_6W@A5>&k3N*5wcXov2JuCFAj5jo$=QfPX)dKwB0HSP9
z!-2C}f!1&h(C~P95$E1#VC=oHEL%~*`G;MGXv@c@0P5V$OG<J(Z$BF>w~0fy?Rung
z?n^Rrjjv$nm+ws31&*<6FV0mdufRzQLGMZaontZ2P(KU~Yoh~yZ(gr&*-7Jh{+~pM
zlY&VU78;{I{itOoa@k<aMJDkmf>S~Hibli<p-zBD$otj>ya&QxFG1CL(P1MPNQ%hk
zLBm9q`nTXcfTD4`2X$LBE|Zc=y4|gxxjkPGRjyz{80_C{V=r)$<k{Ev0l{gv`Tj4b
zCky{TX)jCws{KkJybNI)>NJcD;6p?y$=j`)QmWkYA2G0sp9|TZV-K~8Z-ZD5h^Iv3
z>miT_aq2s;;8UHR_?3LEXmU6?l%stmi&#CcK$)-JS<e_&)(r6p_;a69vf`ouuA7zz
z#*1y<S-|UZUT^HNq<9_%Hq725leOS;r9jdDW9%=(vf9@6ahUE7=@jYi?i5MsmhO=5
z?oyNnkw#LwyG2U6OS+}|KUiz;-?P^`-Vg8iz<mJsoO8sL=Xs4WITBt@77PMlFg^5D
z%7eta5(df|vnO|n(FjdC+sM!%2FLwR`?~5*MQnho=m!o<{roXxX{{fbY-{6;EP9pi
z^`C?yOx6~EsOOteqbMcWtvvZzL%%4q^;GY#GmpuKa4_@3-esL{C5OrQ;E%c&+@}%y
zQe52dEdjO8)q3gdFs72S*757^t4q@B%4}roASU^pj4Tf5%=7-4s}Br$5`iLU-oBNy
zhw>fv4uWo;*xx6T1IQVSF)&q-*~Wv4G6&yqtkobAq;RssJ~Z{#&8btyIyFIQH5DKk
zve0%qFfgP|b#<7Jua^#zI4;YPj0^BcchaWIBn04ka;0#!V~8*_*=QsNkn(Zsd1}yP
zurrgGzde7`qc-iq=Kc=xnQloMEa<a@fy`1Mn=YVMZqwEZ@;02EEuH!Xz{}N`NCIA0
z@i2O`Slyhu<!~~8mj1=iUai(|+{Puz=@K}wi_Qw}dcKMly);%ln+vD?^YjPwE?t{w
zq9EL7mJZK|(|CsO+LlaA(;H6U#XYu`4zE{BT2-$2BM2eUR~C_zGtzK(mDBQy7Gsee
z44qE!r#bq=JRLGI)`}jt>k4^R!P-^D0>Bz++0W&>?Z%+hC3>jGb-V7P+riJl8l%oT
zlb1N^8_OB3M5ArZ`gNz$=&ySg;_EU^qrJk(>ZQi1UYn;Oo~`hUP0<^ctzCqkjQR8M
zl&C7$C*i)8E;PRXZVFfqyu|GXt_$IxhI(Nv{&Zboc0bMy;JeBQ4E!z0y<Al;1y?pu
zjR*JWOBZy)f4xSB3d8^@zbY2W&h%i|y9X>&A&Z5#zk3wo%WTwjtF~Utv#;NO;$P4B
zMuKb8IE@7;J0NVV&IXWvhHsZji^E^SQ?38usAhBWK&qMFxyd-7dv83VB$aaGyJnbx
zxBv~(;rfbrar-2$U)h|IR3M0|#Zzi+Rj8DLZFM#|xs?dUd0OP+g$9TXmZ!j;iprrF
zD{ZIwI0e&Og#DaG%uW`$P4w4Tfjy@QlYM2aX*Z3L`XmE{_4JV}O5KXZD^jjuX?H^A
zS$Bizx>{?W6w9UH%IQ{oJ37(Q*_J3)YlPQ?jLv4pUs{R$YPP!;WaX1zdWzUEOQ$Tz
zgc4Nb^`a?Z)p;a*+?MOKc8ABgHGWC*0u!?q6R=;_GWHFu@b!kvOvU!3bY>QT&{v8p
z9zWGZ0a7rNl@+|tJP>*7w+%G*enmb#ZZ4V^7>buX7hNDz&9Q!Uyaok{c<fgR&*Jx)
zMgCPncm6A)(<z3RACo4V5)ofl3*0|1J!?I|ryKy)uYFAS&Q_YKb6u+kJXdqpLd3<w
zd|z<{woLvrj5MGjN15REg4c1z*)vMfcyJ9&xzp2yQ0}d__2HJz;`I){8gZ4iTi1zc
z%hmM<1ZmtYARd2Wd|LQy>JLmr{A|ede5}uFFq|5o8jgDvuKiT3a-W3VWU&C2S@c6C
zRFe`fxmiVH6Y)vS>wA4qD1av_>$M(V=m6DOKa_!&dT?JV@DX^t*qJX%m*lg0L-=^t
z5fD+<<50}he9-W)D|j%wP&0U5L-q1YV>L@3ilQnnyJy*=RxrHb+^^r;b9&Oj5#AMt
zaYKrl^-N!}s1U*7lazwDeHy&_d*@a0@#AYFB~2SZ)TGURjbyvw@jHPy;6wex&bCmh
z6}6zZrU=S0-qPTlq9%k=Yc(p!o2B)uN)wvgs@9{ErMt`{k3t%L5V9Plwy7jac4?KM
z#V`LNDpZiw^f7#m97ff0)oTE}emLb7bk1CDq>ZEQpRA8)!4NI#LO3j%ahB8Egb<oE
z<((IiB}UUVnN$sFUkNHSP`kHleaY8mS2o-W@8cM-roUlmyA&g6RsKi}>>W|OUiui?
zWOPoIjP*CjsUpB;XZt)c9kSus^vMDdk(!K;L#DIY>n0Z|H}|YA`=)RCs**lYt?oVP
z`u3#rg6P`kVUJeZOQ^(5$^ezQ)jOZkEY}-w-ut1LD&Efa%j>Fwr_<b@xpMK2p2NZW
zr3bZrJf?b4(JqDfitf>VS^TIMz)J{vIUjS+Os@wRDR&7tU#@Nv+zb~dVaWkBW+T-5
zHdn&>d}$zsk3~;t?IgVuFDosw-{CO#HOiwXLTJAI0fW;!rAq9(D1A`n(6fw%7d5mL
zmAE=%4cl_IV-!O~uN1j6tyN!(RxeZw37cR3Qh4j{)cr>rwOJx*>6~hGSu^4Hl8!)<
zJ7QW|*Kf<rbX?;B$;V_EiRu|Z4Jw8gLuW)5aBDx&YGzI#KKm^|_s{}AIwQOg>b`wo
z^=Cz?Vq&$KM>^NWZ9xmxkGGyD!r4K)z%n$9E%?*Pb^D#9I#<{h$l5jlZ}Dz7jehEK
z?pY4L5D-q;<)Ll=fpOYH^(ST<ER%^ttu8>9iBWG%Vt;>k-V7yp@?#4uNU;hu_UZD5
zgwdFcq1@F6s&|+7l!8x>Zj<v<nYKc9;`{*O*GyMH7+u-#SenQcLDZw;sA}sns%|>`
zQsk73ml3O8jy62MmDV%WAmo`Uj!AdCl-B8yZ9K_F#xqz)RN<CVC@wk9f&jU%Pmp49
z97RUhRM#|x0;+TjbDXy#BTU^dBZr$Ec}W3#)Q2M1l`O*J2YDCIQMI6!0E=-H>I2ZE
z_!LX0%g=Fk^k8Fu*p+<8PGF=~mCj>&?{k=YzmT*MOcO@V#OK8v!o4}OF<4*s?j|hF
z+`)U_tkI4e<X%eC%RW~2>2fti<!5V#@nz5Kw8xHN>sVv%t6vmcbI;jk<CU9{Mc_+d
zkB5q5Yg61Fjy+cU40yMD&{Qh-8k$DJ`<G{<9Q^HC{=BiyVeiMQU<oN}KAf%Tj#B{d
zp|uJp5xC^yEa6Jh11tOFWlQo*Z}>J#6{IQZ2a}Dqx06(F;gVES`RK*mV_WoY+B52C
zM*<(NRo(a^e^@r*ttx<!k{27Xc=Uh4J~i?3Skrge{;22|8U;r*=8MU<JZ%~@EQ$%b
z$sZSK=aVH+`P|vieerehu1;WsG+G?{&HemN6cDvfP@5X<+uzI|5ZeQJc++Z5_vrZ!
ztz1BahMvZeXu}cqWUF-P*+n~g2NxgRtt7kKy#)!f5qDI>c@3lB<JPqF)5D%KfBiR*
z$~Ih2GTvWJWYSjH`%rYA?u@!lUH7*#oKC+C#<Yn3GGlWSMkshQ&29T5{!LDYdwZhs
zX)*nxpOmKFduxqJAAb^g*GzPl(SiQbn@~)?tk@T***l&r^%kyT*wfAFh9p}*LN1Ub
zbH6y7@bJ)$ucKRV>rn{(B+Nomk>bI`f=iEPo7Ic)ew)0`BZDSfN)Uj0RM$uz9ue`o
zR}wkLjgl|hZVCU>(71*pO?_p0C_J&<p8@Nrqe~hYEWF&s*BOW2gpSk0{_Atiw^A)3
zm(xqA9=o|dpe$~Ay{i5FWq0gn%QDvYobno)@AhitosK@oHQfBt%ac)AAITO^2$5m{
zCyO5}Jx4>o)@rl>?$(?&)O~Oh`j_k!+Pslm|3GCl5-;U(n`u{M!~5s8RO3ANXLZk$
z{(0-tfs)RGd#~Te&P4_!YnGr;0^n1x47?q`7WYqlpjwM2i$4A7y`ZAIQbXkXp4fs4
zabUq9KI@6G-+_VtJ5v-kTo45!%jj&RXY|m?z;G+;dr{*aW4e+*tD)#;r&FW7{cj>7
zUsP}5JtqRAD@!an{m<(AxX#|fZekJr>32?R?3=e#MULegr*Nn1GB+uF?HD}z8PR7-
zd-z;(uft2+ui2apD3&v;;kgt9;eM2r8SwOyni(%!+k0>420`@9pC8hXLm|+teepeG
zZ*g=G0n`uPxR!=Pac?x)rpesxUPK?{eFf}h|H?skS+Z*{-Nr;t9j=B{EFRhDQh0pZ
zT%k^Lu4Uasa>VH@(Q^=uZUfiB!o@Q8s|b-&F(%G*KdH*f2O|_CsNdu0%ZG^L!zD+*
zMe0OK8=`Y@jJI|-Db_>%{O<e)--rWo%i}(xMMp$X%Kkro<41Juu45OuD^2Pv#P0$R
zC%57Vp%9rGOH;;X>ZF1XBitS>u{63K4`LZy+No2&K!Km4JH!WwvY(@OhjY!9_BQ&t
zPg`f<AmfXxS}}6+407}g8nfmc8_-k8F7J$|Szbh{muXD&RCLE!VPq7Os>K5ldY7^4
zabGc2sHURu`JVanQx52DTYQ|}niZtt>M9($z^-1xVIs(m?SH;&88K81GfdW`<!)0I
zr+9{VvV3%(c~<_sR8U1!Hht8OCxW{+VsUmdzUWK)&2oXqAC0!`+z8lU+a)_0#R93R
z_N#UE#D=pu!JpT45MNAc^cw-qYg*3_qObqf0(?#T0EiJl2B(}J3O{S3;MF7A{T~ay
zx`V3R;%U4@-&x;BjJCTn9N-hr-!@c*g7*m|i{OE@^3Mq<?K$BzfxVKW$;&pp+Ulo~
z>$tUZ^>`|2ZFtI8c!sM=m(`++=j$pHN(z?4EBxsCn#x=Uj*L{etiFOj@K_x8*(up|
zgdJW)bk!fL;3hV*ZTC~o{^UR31NB`uBjdno{k+Y_s29l$Pd!7@<w`xegmYS}c_US9
z2tWs3J;>fs?B$eN<eR(6Z+*XkecF#g^0|>`gAzjoKoRRs?n@`nGerS|CtJK{>I`J;
z#Rk3W${N)#OmMA9Tvz!eCK0OI9D*qjM_Za7BJ2tn%`rd86#S@bhbF!oExh1Ig-NX#
zbOVQb`HL*!CT_#OF0nb;h|Y>$yM!69&@C;_nlO^>Qj#BfhOtk6#AMRaJD1cQ7Zlar
zoo@VM2Pp%b$|O0@Lh)^Da-S^LcQ<)nw$0_;^zW1vaDM(Sb(n9{g)BR6oDNG+m20$r
z?}QZ6_fdpwkrYBFz`bM)9T=ng6kvzGw-)+BhXN*FxOYe|^}3+V%I*wggHBHO(v~4^
z*S!-kyZrDYF-u{>eXoCes=l+3$E3`0liLyW6mF-BoQD*H7|ED~ER2ztFmECNp>_fc
zCvP`{i*Fmo!3YF#IRs$_<fOp8r6U~1tiQz6K62*<YS%7W*EV`~Cqcj{*`q!yRp%N?
z#cKpPEW!*K!|bn9NZ;|hv6pgaiS-n4Or}Wh{aY2GKZ%9R(TW#NfP_;Vr~4_kcF%~*
z=3RA&KicQJT5T7Mkdxs(;PgB^`xJ3L6F2$`fOlzqhyc~YqVdE;rRGdQVu(P+5^%n-
zg30TCD!c03MeA5Y`Pzy5C@@E|_H=voBm~j1hQ`@+d)?vu0*1V=ICz|#vaeVQu!8u}
zFSw)8*ff~1*3V@l#$VDc2WTxkwnx8e!79o770f5{Vr?H*=6I72q>9gV28tw%W7e>|
zOJXp=6b(WYlaqJK+8a`_0AsL#Kpi>Rw_SPiBJ<EkZ~5X@*gj6=32#6aOWR>S-DQb^
z-bM=VXUxdoGwUK7HStndBmNp+=$s$YD-%vS7y)?pmct9cK9_6Ika30s%DRf9>Mx%0
zwPyM7Yhd119(000fyLl_lUNC^<0+jssHlP6rK8@dff8Ik+5WYitZakcZdkJC^PT6w
zUtb@R_p03?^XSBTW*@n01C?u+!-hSAm7q5`OW+gR{aj4t9)`^Xg|KuuZ#rouH_5uO
z3+rBY{LFqA4-@F6D1v`MQdvo#4TpQ@X56A_U<M%dx<NkWxOeTMuCYp545E{Kn_^Z6
z6}lG{<$^~;$4KH0Q)7VEd-r2UP3m<kyabk?zCqw~SlM!@zyka5ke)kUB0o`VkMp_d
zugjP#o;6rSy)viqx%w=Z=So_!poPhm-lhcrD-^<y1rX}BOuDsqzx;1E&LasFyh^Dc
z_v<E&9~0Q`zt=EY>jVwFlg;vYuJJ7R@}YRP=elkQ_1f{sz^D5A@1n$>`2<kUQr=Du
zU#KJ-F4d`iOyoXkaukH+b0N>RM<P?6Hlas@qS&Qw;VusNiyYdHH6(JJgw@NCu5Cm&
zvf_Q8wKE+H2sC#HX7`g-S5e;7b^q;pMWxk<6*luv2$@BQS^H^S+ndxT*DYh#NLd^y
zF_gw-{3(}NGti<3k4dQfWe{hNFtc!lWbI`|F_zwJpeiOZ_pMW34@wL{MxHgFpBz-(
zQQby8ZsPUj4AxYFLfRfECE)dZL)c`h^N!UL%>WrL2+Ml^%8+Bux9A%XZKU=rw0llo
z=x5(^CjmbS8GrtTXNQY*uQzxm^u^oj437J=_WhU;ULmZFt{H_FpAf__jH*K_wl5PK
zPDV0>`b+s82ft~9^Hfm@=%^8(jND-$WE~rV)@%wMW&*<vc(@MQ(Q3fWZ^RwFgJguV
zxCtb8TnTqv2vcGy8L2V3qnYms_&g5tB*bITK#@MxLAyPcR7ZoqZa720CXw|?-%tIb
zavP#Z|JPBqdyboYnU0-<sj>=c%!u{hf5tW<M?G6=oJ1MT_r2piI<C(hv3T>N<Ad;N
zu|^|87}amPivBJ$TreLA+!yX|7li2Kojf^oltUnR#n-Ny1@c0buqec!WmxZh_fU2*
zKS*A`g0!de(VxfoML}h?`cd+l%I=!f=%gYm6@t@|Wco)B%fo|vcr>Oj2AX^c7n0ac
zXm?y_Pze6%aX(Y^YB=rvMawujjM3!%g>axELYK=x3L(rp0b9Y6o$!DYEu9b}%<dHy
za|(#EllIg51UPSBrxf)WJj2NgD>traXslZM#gqoD;GeHpZG2ATC|f9)f)XO;KVZ6w
zLGMACPr{)(hMzmi^797sbB4q?hPgO~o}Yx&IEJ_&yiSug41N-N!gwQoeKRY`A{k<Y
z`|#b;hZWH;h0_m^Blui?DIp!5+x9q6W5@nSY&q~yFfde*H_MVgOZUUWj3$ot7gO(P
z%3teE<g}}MucPdpnD%P<=&vyR$_C~1KmIDGKTH7CIL4w-KtZA^B@%RN2p^OaU=9|y
zJN~p-GhSCi`InbSv-VWXUW!j5?5uF0ZG=<5`yC*8J`x)^PJaBlxr?2L`>3ct%+6J-
zu8lC=eSTpxN*dyON-e$!Cjm{|>(1|fh-LJNWGHf4shYtzAaL9`He*Wb@c6xD&~R{m
z@bb}HE|lmj`SaSHRQ~YmRZC>R!vgLNGC3n@>bL2qK9KXS6|M}Oo@H%nwda>lG0`mh
z8zc0g3*7GQ2dUz<87K!;;Ng&QuvM1<at~O&zaTcPc9<TreAKy0!0-~)O>N9<;$GWH
zy#nFK5WbZQTe{>MqEBI<R)f`AdA;*@K+>OEajo_;w4rHm;#>l|Ha44_AE<g&#LozE
zlK8}0q$$YnUNfMBIJ%AgZs7>dc2On1R(J2@Zk}Fkx~3utL$Zt_3aSrXq3^c}9liin
z<CJ;^2$gl+xr}<ltnbfd_@-^k?asF60gD9cKtjMwvlh7v@)x9;lB@t!f1g?4kK3fl
zaDmQ!WBF~-;pI-n`*W^{nWi<gP@2|E3L)_Xh<2)u+9!8rx#$2KlEkEWdQ2=vLNY+B
z#l?R%awQ0X*m6mW)ss-jld!@TE+z=DU{DO0{Ao=GD#YCYsv8l3AgWV^+1k|e)glgc
zj)d{q$q3CMd{PM!W9hOS>)1f;+(+#?I`2M0F!~R~0MJDcS7Gj_D~!wFz@G2eN+dHf
z0L$|s)n3{-gLLo|4&=u%aHmF6aD@y3qRK&|Wa4(MPpj5rRj<)66PvzQ%!ao1DlXRu
zM*ZZ(_HvJvvQL7|6wvvQU?llE2of%M%c%Bcb9eg_O#r|*>kev6CPut$=cdN?493|s
zNZNeuaH`PcW{Zn2*6*auuKk?ortPfmc=pnBKoK;skRhF|8{>sGjG!FdKlL+8SQmqz
z&7RLQ1y(17I@>f92e6Jft@+k`VPAWEX*AjUg=3-&$oubkD29)!Ayet|{rm5EW68hT
z&@gzpMvB!dYMADye@wF!Rc)crtNcL)++t^AJCZ7>jp$;>b31SX$vCvG``p6jsVq>2
z1T(2oX71-{(MiDErIV)WCHOiOrnwxQ0};-#$lY;>m;>nN)?Q{H!Ib`4(15m!PcJ4r
zR4G*tU)DDnYc#oTE|7>qjJ#v0->reNeL=!WNRIP)?E8~<?=D(S)3o<@RfBh_$gr=T
z?*MS0vxW+3sl0+x7w2pIOzdDVrvMEGWdL192%097`&^FA!6(;UxSG~`4}ZZ!lz48(
z?O&>gwDf5SU-c4=l|-ZRrLJvgf$m0Du5F~yB1P1OVk1EZI_4{p`=IITU$t9jfv4eo
z4vRMdpUlkU*6{2X7b%HC@TZg|lbpS!O>G`Ewmx~?<dl?&tj|&v5mA)*>r<@9<%l1E
z+Ml695aq+(2VM$g(<6xL#gM{f!nqY1P9=%e8ze>RK8@pwHY854_<!C=78$Cv^;Ky0
z*MGiCL_}I{Rwc26g>NuEYKa3^FZSlfiIp8FHU_(<=#4;K;&UU>gn``2B!aG|i4c-1
z*QlqYpnPuDqwi6tJPJ4JWv411mMX7bp(?I8(_P*Gj2H<MlkN@nF2vu@_)R6(0l-nP
ze<0Nq+!wUT*8;7PycWl>T6;gETxeC40Bx=L;}{^05fN$~piuUI8h;MJ8hLQO#P$E^
z&la|fap6_53vxvVGxXQjar*xCb$Uc7^Xbd(!Dg0Tn%ajo#K@0mbo7WH9HkHH{u&mN
z$$y6R*Vr&Ix#aZ6LTHBijsKK0oS08x@QUBchU2(~rA56Yfdb=*iG1-_pa1h?lF?O+
zLofl2ngU~2IY-gK#4Jw&tV^iXOA_$D)&Fa?B#}BiU*w(;L2chhv{&@0T*6wCA{k=(
zc@kjyLjSXje@_rt2GfQ{gi-VR7}K)q!3CT<6J;{aoRVxLeu_LJm+@|Dk5w3KCa^_F
z69Di3GdDT8zaXwHejzP>s6nF4qqf6_I(c_t)S|(KVlRhWh9QaP%jAV$@}Z<cx^6j+
z(U+;};)0dff=RXot8f+E%|h@8_W$)5a~$(k1hZiBDYCQ<Qd*0GdPj`+Yo#7`i|Ni4
zSSrkgR=L?Dh1($$SXtR|zK`Y3<O(k2>f54CBXKBY*aS^praOcfG+w6O!mmG(caXA6
z@}p2vs$x8M`~O;zio}~&&wFoV$NAG*hCxbi&zu&P_O($iKAHUMqJvc9idRp6N(co1
z&f&lq7rDej0E#{||IXg{uvVzzZ4<TToO1BXJQ?L*|37cP!vZ7QK<&h2FQ<d1g23h3
zOh)wnG%Eqy%pr3vsb+Rpp+nK3Yvpmc^fWg;8%ZcOamT7ul0^cyiKsXYw?4x<xFF&n
z8EhGOuGRjZ#!sv0vauTji*GZxP<psEdC}KxhD|P}O#S_(W2lSPv0}fM`)%jSoFrLT
zIx_2W6*^7dL6E|RI@1@sqdXH4F#LH=KtTV`RAWMXjjtqTaZibN(Vx%_h3L4tSUQ!R
z>nXBY9mkk75tCqk!TEc=@{bcQn>k*&ycX~=vFmpuX9cuv=#-REjNB3b(>+Q`Q11cD
zQPpnkme32>p2xS`1Rt#?ooo%{qL25RH+~8wuMYmHtg7eYTa<QB%h>?s=)eE+PXBLV
ziZYw|otQ|KbP<9vET`Q71oQM+QCvCdk**LUK*{=UBP?fP?USU`CD5nYgLhKMlsOyv
z=l=WuJEV`s<+57g0tru+<8@>+Xg&6ZK|e9+Y(lG{4N3^h2WF!)GS`rHaR|~QB68sW
zDHikJJ|;mee*9HMg`7pT{%QV^T_!J%pcWcOF5<eat@*$NFbL<*WzzrGR0K??uTS6H
zvS3iuTHe8;>MP^24iP8v3sPW~ERmR!R0~`7s9Mly_ft{k?DYI&J#*Z4)~``ze>Lf}
zJg{rZ5ag;DejBCU_b{Bg3Nl=uBm&ezN3PKSJqlArz{TJoNyD!F2c3fyLakhok4d9A
ze~Tf9Y#U@`1a0xZ=W>v1lKidV%KG6e1X{G70sN1*wuBY7Cd1|X(R%@Mb*B*#v`zoM
zhQNr?X6h1^LMX_tML{}knr?`<`~%vtI{IfbMqq1+<}Z23|EEisT)OCQrAq4DL(kcz
zun3^2TsSla*{5}<Bvi0DhuEJ<I@EvK3Tq4g-94S!R_%>XbO{4H#zl$wt^<k=l)^;>
z<j*@rCX@bYlZrCs#+$(R!8SNCgaMq`+df_QdM^}2C{kvk_yDRO&*EJB>fg^us2S0)
ztAHHSUTG@E|L9U>XHn9h@^*&EW{H4Z5<JEZ^<OJb5L|FEMGKcEZyF)#8$8?#G}3ko
z-@E11qx=s{Dv<J=y0Cv*;KLXLggUPnr=-?0bSfwyb2G(<`V=JgOsQ}d$~14Ehcf-|
zp?u7nR>F*}!=cpQ{y;%^an6(YF2~iOq|c+&N6^g+`#0jVj#B+oM{7AyDSS)%0V>I?
zq{Se?xraf%Hu779Le%;cKMQymo(mz<m?&@^<-f1v63b=W&?Bx#%tWoNipj4zTjw_U
z-q_H)@MJsM`*w4~H0Jqn^#8sLq*YZhxwt_d{C1Eo;<8DnpA)ieI!NgJ>pboNx6)8}
zE-86cO+`sr`|sfmIuCsUo4I@y%&wL8jOY43r2`5$A5EmA;Iz*2uI!8HqM8d*OM=GM
z0EisQjQ^!bXC=8DR0yEv|J@?>Vp@w{-RW;i(XMW*_U!n|7O8~__ri@ILDgdz>;uFE
zV9m|`z2=~VQEUIl2iKqb*qUpVHHH+@DnuUz5|Y<`&XzIFyXBX>EN9|}cB9tDz#M<~
zSN`+=9O@)mt1gG~CEIA^Ld+G%_Ve=i9&C*vi3xsa!q<FNZZ&?1OswyyzqacL=gKZ4
z4N7^S|21tA(IlCbT~jKTPT^_MZ1rar4V-=wlEu2`tZHkY4p^L2d;s<BU*U!EsLzQi
zEccm@osyE@03nlRG?|hF=6_Y{8;iVVIA5knI56F&_kVAuhB-UX$5iHZqL@*R1*g_*
z#59y)jNk9F0BRiC4ExmA*Bv(JB`}7F{}Ss;IyQk*<Gy$doevpfYMYSAZ579Ho|i|n
zTM7wwi!PbapGuoqUzyXurN7p_C;kCmnyD&?O0;BE)%!d~mVb@W8L!{2=fNr(SD}s<
zR5x`ZS;*M_p*9JpK@5G=QiEfZv7O4s3yQ!Kk{xUMkY6G}<4e*+P|P-_7shEPQL>Th
za2)n`^kjRX1=K_MpYjvo_-;{pF{=qC2P10W@lZ@ieC#VlUbq-SXVIwyG@?eV(#MA>
zSOuUf#D3r1)lGfC1p56u-jP}cVe0ILQpb4=*+=pwwH5yue8r*&Y@w**eG6~qFGcv#
zKLVsqeK9e|Ps4Hl5ftov1(nxN$#pQF%9<%jq7JydRZm=c5w$k<K!^nd7WH2d+ru!-
zKIvk56;A3c2-SXB=ld}jloN*n(f~8Hk5*FBMev`l0+Z`C^s1z;@MC5R%A6hRnlaew
zOE!hl0a$YwDz;y1KrEet{%K=e)N(MoV1`ID@Y)e`nPA5x`M>5OKwfvJh63ioIF*Cp
z@2dds^8ZBn+3uKvO3XL4n<fc%=(p*wDJVgziFEIjqPs%kyziC6XcX<j3%W=ApYd>M
zkBAC1p?(wEGZ9q8j27N6QU(8|`ozo-G=eX<XTr^-C^?Q+@*0y%>2)1ZaDf`}nG>?`
z56KR^VVm6|rilow0zGxdpZ#`PDKWp6%yIt;38I7%bC3brjBiWdZRE@bLiA$w<`3jX
z;XIf_nIx4RAA@VlQDiaH<^_N%Tg=PCi$0IQE}S;(D@RD&ZAw5E_7}-<Q5)XNZS~yP
z<reQ)X@2v22=WtBdOA7LiRJLLod?Eet)VNUw(RrqcK=!L4iBNlCH$MPczjAZSkD)g
zpTPP<xhuKEc7XPV%~YFpF!jMXwNX6}WXTeN*3l11*AA-w2@u9wzxbz^e`EwTs?*IA
zmCKor_5Rh7!g&#jvy$k>l4Q1oEFkT65l5izd`j-;mi6M5@M;M5QVV}GyAdnlJ61IP
zd_VrbEh=44(vC#`5t`P<!<Z$6d+>{10j476by$l3>UymRs+bUA5Re^^jZ9kqWzJMZ
zM*_Ug3H8tF-*3(N9?&kD_lAWIe$aZC22AyTThZ`4Xge^=sjn;=$D2P=MMJZD^L`L$
zP+a=@->*D>%D(vPmI>N36s{eZ35;k1Bx>koUtaw~=)t+)&k^CEY)SHm4@XvA8{)FE
z?j`?-5itiN|B^3ucAa|}TY~qz&TmBLjQ;T?x4)nC5y#p%Ns5C^{=d@rG`j5TGwAeX
zH^{#$?<zHM6SY_w_81b1+)`2nOOBv;O10!T$AT~VhU18gty%kL=~1Ke5edm|@f4GU
zN*)zfjU&vOZ?;eV6|?aRIb|t~B9E8)W{{)D#CAQR=BDO7cq*sDD|gQmdI9fS;vNtY
zv7@c}gKw;eVa#RX{es@F@nE4Gg9Rt@@WF>Ug?hRz7oSTq38DFy{}Z<EQNcaW2>$?U
zKw`6S%*ZCsQhACidF}e%xPb~wqmOII`jkTbIEi%pW!V1=nm<-P988nzY;85>WJx+B
zvN2Th6XE7BivN!N`Evmy_*pYaGzRu~@6tcgFr%t6+3;TVi<K^(*>`^VuOvKwsx&va
zAb=0NJWV~1r}o&FoN8j^s?a!JQzky@xOEm)fBN6BbKI@>EBIX{ImHr=`4>ZZ+4A3N
z_n&d?VK9?`;{pEBsCu5S_(%KrclZABHF1=GW(eQ{M7HPCOa9UR|Gn9*#xVq@9eOd6
zWY|zdTp~uy)GF%q+9mf_K5!PK6>X8G`e!7<C<2nXJmf(sJa!w!l(4E^?-jC)Be*cP
z&lm)BFY(JdH*GrBtRWx>QDJMNqE!0=^?n5Q1QA6_@$5}K4tF>Dy2c#RlXGi?iKqs5
zF9oP*s{Gg+peE63S?j(HD%?0ODWdKQR_~D>LO@enMW0za=lm*=-fx^+o};0jwqiCP
z_&Wi45SFLdtZd`1s*G0D@@v$NCE{8qz0VrqVjJ9f#mKwd?5_rIRhTVl3rGg2iDenR
zKIl7lEw1bPXDk@X*wzF&wxBo^p&2&74ZrKET*EKY#Qls+_+E~tYG1Kb=;Z6?Z9AoQ
zM=ul<1>AN*^b*IL82^}XSKQjDAo0FHpI?zZIYeOed$o^*=(tmo9z{X3vap>Vux&;p
z<*3`At>}x?an+Fck*r8=K4V9|;$dfC#_xM^d~f1X7zhsf&gsU5$>H*V;%aDt!^!u&
zoGGR!RL2c1jq~{t__G+<=8SZb{^24WVt5pbi0LK&e9N?#I9J0W98T?x_MSTKMOu*f
ze4zMr;A8@Fq;RveM=%#kOfn`(c?X_V+*EuPSz{h{syd#=k>^Kw{yLBNyYwSgj4WCT
z?qy;J!9X|{&9iInwx%cgEn?a{Fg1-Iv`)V2?6sTdLShh>avuAyt6z6>@d`cR3&b`B
z>8MMwmAuSyBX2$EyA2{rG=3spP};cU#z?27U{?zSE6Af9-aRGgpa22Z`n8G-#i6L%
zFj#K*xr@hUk-rfi%AD<J_J@b3)iXp&ui{lvTmiJ-tnA6*6K3t~Y9&QlEt}olC4N-N
zOZv0j%lN5ut0z~}JWE>#6*3>Ro&ENo(9zXd-5G<kQ=xE(Qn7QhjdttM-P;k!YbP_0
zkD8zAAd>6bcDenZvT_FsA60ssnotgW=^`VAZYq#9m8#y4Mk_t~7Ma`;#;CJ4io{py
z1I`as_h}mDL&}xWV=-BDy)P@_66%v|9A0kuYW&lcspb_lL`xul0h&1*w`Ks%_Zx=?
zs>GnM@EPa^|5pLxUi(2v%!bg|&1d*4nKI-WwNFsg9}HaAI@LwCD&Ta4;V56?X50?`
zDOj*fLsVb6zx)BCTu-aIa?KedfG6(eUb(-em{+;&Vm)E^+LPq?UIcsP_9?g$$y~{l
zmEXoeuykf}%fo~1y2q(5`TirJn~$p^pU`C=B}9>Cy2)MlK4huLV$*&Ol#!zh=3Dsp
z5lSzz=SvyV!-9V2AcJ`^zNvGNNB)8ou$D^MceTaJs~uE4w@8Ey)|w4;Ka}W^39*Z|
zIP!D}_RZlaCA(faC2HV*YXK@R9I6rV?0rdlx)el6pD32^SID#sI9S>Q0^l{F+}s;!
z!V053*7_Ne79Jj-(rz_Q`mrsIw#PZCuQtDG#|#psh6N?wkuEml^vwHgL+85Pyi|X4
zG-TqVNy?lx%+?Q+Fm$x_Fsfi^2s_Og9(bw``{rPfg5CHy1wP=tSbz7vuwVn0D8<s!
z_m9Qt*QZZTqwkwX{Y4^rb=&He8E`7r&y|wDBKQ^SNOi-v6H2Fwss3$3bC^2Y2O@VO
zp~eX>TR(TKnts#nwEWm@W@PP;_V&(MR?uZ*Z;n=#p?u`fGQLRXtlGA3^I@yoA$+K#
zEjb}&G2LcYK#dFAr1=m2LSp|9Ar|I#G6}Ysxp#mTU=*3jotqQo;QZ4Sud#Nijdvh`
zYleWX{{7CBF!*h6lA#17E2~OZha{r+8Qmg3URUc-V7aUAM`D(+<)!c8G-Dmhc%Sey
zhZg89MMgGljJ7K|&Erf@R*T7IMB>g}+)5{wIu;{Q3eZgLaDTK(S&_=GWg`I*aXPDJ
zJ@O~G*HHNtRh*L4Ugqe|Xed*y%XnmxW^X*Yi&KDZp~Fw=8Xg!a#P{Z4<lR~Unc<_*
z{F(NAn<I($C>5LFTT2_CiA-wh%PqD_p7`HYL^Gpd&A%QjI3xt3X77xPYsY?R;!H`}
zw#3YO5QN4+8$L2cC3-KT9p(Sr(IfR%DqKUI((%WHjfhRcBw{j|8RRVY#p&#dy^P9t
zLm9=Xe9AW+%A&w8S)C=anFVee`M9s16K4h;2Vz2oeb$%$A=VrJv|UpHMG22hP+!t`
zJeFlSo+5e2w}Szr#P|x?3T3p8ZHrdaB`;=2mcV;7&+$$V!JP$myvRYno=<^?&6z4V
zwVQxfsLW7lsg2(}-t7CC7F;xsZ^Nk^{>|hx-06Hi9}2O*v(#m4N=L6qKS9-hfX;dG
z`;v@^HZc{21HQz*k=#^;X51P|Zi7Dgr>Y2|EJ;T&xj!um!w?`=QrPz5CmsLv51oV_
zx?^}GWRpk%@6&K{1d%kKL1&TtN4=7VU#D+3i+Lz|$xgU?h8XU$Eu||?VlFO}J7B8{
z8{R<SS<dj5NkqMf;QYDsAvnUTX3vbPT8+9kSW41T=Cis_TrlyL2|D(IkMPuF%#nG|
zb-LW(u^CAHp~DU2ja=#iqW$CC1v?~HeqVB*bj538kXDJ9-00#M*=mxWMq&v+nGo*_
zrP!6zb{w2?x@EqZJGwP`#jn>FEu!0Zh)kg;M6`RWs*9E!7`!3}u4&7y*hijn{6oW_
z)v(*0-;Q!_I>!*-9+<mgC}rESI6iX$2V(U;dTDc?hU?_Oa_0CP>#doYT*ZjEq|?22
z=GE#IbmPO$X?NpUq%`~W9dr%0s_F~JE$PZ}c7vNu%C>u56!5BQg&A~pp2~em!s>p0
zZ<Zq$p6^$0us+>6H=HL2GVK;&XECm=+U%de3OM_ta60hxZz18&X?F~dQZ`&@HykHf
zB=BEbi{ICGA4XF!F75g@#QrB@d(8It3db5xa&98>*xi;-5&ClEF|dv)1?iUcdTocO
z#BR9iSSDU)0Nz-=<@~HSE|igUJQFUiy>`AbDCToP`bnq_@5LwF^w7KMcnZUYI8DFC
zh+VXBMsB2@Vvid<`B|s$^(z)UR!x!E4&}yA43TkRjNI=%iFj`=k*Kd+kG<bQ9QeNi
z|15J8G_4%(@F1wTPnHUS6TpD@O7q@}koWAYcO-<7)O+cz1B;2NMRsn*9q*FW>bVG$
z$>{D#IAdD@gh0GG5Gsbt<d*N9M5Sx_{@Mo~1ID?PjZg-Uy;y>QN162ytgIScB~NDA
z8x+y8(&os|W4%na#`u*<t=QW7>(r*{h|_V8h5<i=-u2wI9$KBl39KjyvbJE(E;X93
zJBc&RFB0D+8mGH`kKL?fR`(q5tMxWz)I$GhpZM}6Qz2=wv&X0Ng&`7DZQH!!j-yX>
zE!StS8d{e~f}7siYC>Xrn{7B-55|^|NjJ5C4R(Ju(@-&FN+<}Ad)Joxp;rt0LG{+Q
z<pJF*y2pdw7f};-9UBg-=SrbW{<>cwc+cm(W}>5s_%gukHzF-r9dpP{C;24|D8p9V
zzlRL8B(hr##hL2qJTBenU>N*@OVlLgp2mAIVHWe#?P*pSXZ6H=rWY2nxx)8+Sp6sQ
zh|7I#R?n{e>d(<641!&Q&P&gHYih-IFd1WWGZht3{otio9a`>4KjOQ>p*LFTw9pk3
z9q)&y%44LKMM*3kJrM(CullD%OQSeM4DYAk>twR?s`q@W*K9-MaeGUy(VLpZ<Z9aZ
zH5POVSwv@dzB0dv8VF9*nCQNIx2=p!TmAIZnd`H4MKf)_ybZKOt+=<@4z^Ot`Fi6S
z=jUIx-)SMm<#bS{e&ChO(;2tpNWk*659PCV6z>iWY?yZ1;hI~KnyLyLeZ)BSf(N+U
zU#+SSg!7%dR;#^POx-ghw_8jpv!C`~XS<a&w4f6En&8?Sx<^GBz6}5xdMww80^vqF
zNQvW+tu@gl`E$$&w$QI>@iZqXakra**n@9w;_84(9oFFb6v;SO2nCt8Bm212y@lLm
zb;>nn_<~s$hEoC@`Q(U8>YqHiwEc5=VzAsDSw#)I-@gGazP(!NN+y#rNQhYteH2H4
zl>HYmoMKz+;srA{ktg(pd3YR}`!oSQ!&)eF%aQs0$1PRLOhzkGAFjCzi1;H`N3c>w
z`g>7h4%C;w+3HH}X5xY?s4+>7?rW#XzOD88@A=Y%oi2G2-#qHf{6UX`B7W#3l=jAe
zS{eY71IB-G?~twmB9PoJ(Q3riMY0Xr?Z)2#BYbWuB1U6DJA8#j)Qb0xu0!U&Bpzn1
zG}Wr!KwR4_LhXm&t&Uwyd;bc_o=Sam6VPe!b<MaveLX7iBK{58h|!j;LldpbeD=(A
zGk1wUM=>y6S2O%|i=92o_eo5f>wmZ%*TYAb6Qp%}H?53rEw9Y|9Dcj-I4bjEYl(|h
zv(Bn^ltKgRzGrFk09`@l{flD933y{SSI2L#hDBi;B6|DFSj_1_A>S2Cm`set8EZCE
z+Tuh^+Pde?mtVHbrhm`NN#nh5y@(6*C1!@E@vr(-Yi3;<b39^l75%Ne<?;*OCn0nt
z;q_A<$GyX{=8Dhr&h)VntTkR6pAe==J^oJ(sd~R*NRBo(ZV>3M1sL}Q_NE(9B`wmL
z5*N*=@n*mgAHjiaC+DSE%m{7|#~+u%$V{241~0d}3XW2{KVz+Wli%G&qklGGC+5IS
zD1Y4>&X*3Vq=%z^UAIsw6F!u(nAQEj0)2So1<FfxbOh59?F$EtptPEgJOAjju-lYZ
zv}ty%v13MPu(2BS4cI~|*57koWy(=BA9dYI)L*aI){f6XQC|)s2TUbIO~D(K3ZHyU
znNnfewVX^_NvF}0a48C^T!QrouIefkQSBbdC0M*?T-=j^fB+c_u}7~#rC`>3qs=dP
z-*EAetl&WkRGS7BJ`up8Cu7<W1MYp_b;JUuz5wmF<8gFh*4xb-d(V;3b@dP?e!j^P
z`WN=M+)LEeNAu_HSJlH^JYkSjF9c<oxhq~u>j&nfjb*}te9-u%Sx7iToj41KcksW^
z8Q;X!ANsC1(MGTB=6Kwx8uYI#kYOPk>f<rca~2{N7D6W1$L%QN<~n<NKvkWD6sOL5
z3dYL&6Ifon^kD)qz;A<_YvrH3-yMg-f9DYOmd1HWh30T|Gk(lQl6HHMmWdzIK73G#
z^1}WaBwsrBFbeVJz0v*7*aM{k=^NcuM4K&9*4n`ZkZ7YK<;^bzkk?oHzD&q5E?wrR
zPU<`oH+6Sp&m4va{eUI0IkW$rfcDuL4L^2^Z{yDtX4DKTr@D{1cuASpyif`v$jHRk
zvxyo%W5=c;NpWTGQu|~Rc6H-Q%KS)Q?iLy$`}XeA5{^gM?zjmaLOH<1p>%G)#Rw`A
zmM7`R>!X2duB!65WsxH<5rU+3L~Jr!Q?=3l7waP}!d-QmBnJmS{VL$rAgg5#VYTG>
zP@{REWf_}3C<!Q66py)Le-TB^?gX&|Qbf#vz^j`sF5<gRLgB|HW%<nMCOe~+kj#Fw
zz?xck(#88c=zikAH5=0v1)wXVY``7!t=UdkYj-E2=XiJwqn}m6Cng5LebtuKZrXhQ
z<E#^Fv@c76B*&v0v8`~a{bW|_x8EQEV-bllJ}q#VsQru!i~oh$_{z$gBYs;kkIkP8
z!X%n{AGaFKR3noXms9OEKj(135$hW2v~tNnA;~E5$h>uLtH)5djm1k^(>DDU2D|{h
zUxB^4!ag@wv;}Be-}fb7bLOh3C=mPkk{mzOSK2uV@-Lwh-z$pO*wvP<?S*6hG&~bI
z)$%!SEn7ZYzwO72IUZW;7((1p+;{f4)Pe(1t4c+k@RZM!Jl(iA<nTkwA2E~?bU`J?
z3^jQ|Bm#JiV{gZYPY8Wme`cTFtKyi?JM%{ZomLxCVlH^`tH}(~=jz*Mv#}giH33!G
z6^%EmM|fh3_k#CRt{c08kNoCw=4`&K$WjgGo#l9{T5bDwB`I5%Q<a*$)eDxi4S(Lj
zT(u$i-DS{o$K!T{ZY~JxJ+KBv`tlv%eR+%R?cCtT{bzDR*?M&MGcC?L{EjK~+y-y9
z^D-O3F-AZ0>5K+<z5w9L!VL`Z^h<zmT#V!#d0<=aT7K$2&qkr_u3Fy%M`@M&;EOS@
z`TT*?CfUWsBh^FfIJ9$<Aox;=HqEOC2VB<rkMJ^hi9&P>J0{eR+OBK!{qIVbuI#<E
zO6XbJXu?}9RO`AzN1HYU3_!#xCVcVPWQ_p?t>2)vf0B$w2n75j9$X#iy)5?@bsqfG
zN$2_9=AsQ=Q#eA1twoK_a-c9nt7)PIFKaQq|L859Hi8T!T6>b{`_84y251Py<Uomv
zS3TLKss`N`@j$dT7OsYHApo*+0gG;*g-#);*160<=R{M{Ng@T(PLs#tm94@Z=EDAt
zak7D?iNrsI&qI#a#{5rCxt;bR^``!*X-Ys$Qg>sO0a3-~9DrHq{#-#lL5@l7-^g3n
zrHwmdK^8moib@Stwt~~5{G!CDGz>F+U!G;<bbVt5?Pcpa+?)OWqMOgqSM4aGQ*R_g
zt1p0O=q-hwyBLl}P^vz&glp=4G+6+!()J^71Ou65C6LrwcmpcDC0Ry~@0T6Hz3G08
zD~ZEV=hyqgZYM#TG=#3Oc*~I+Kny48r$Zqolt1XWy<0Pf82`w==(lei+-)YRqEI?o
zznrH1z9psLmm6NhQsJ)%B`rL{_lPvY*HZ{s$fV<y2oQ5z&rlH?zh+IwZizMZ9xm!&
z{xpA}WcbkRm8z=Rhtzhg4w@%nTbq`FR~a52-SG`yons2p0TM`sr+aM8&T1fSYkRh;
zTvob%l&?H=T$yN`YlafDpsQN+dFEu!A8l<JPmI%gI&{!Wy>}iO9cTe7uX>P#^1aI)
zp=?D%7Jf&<{FyP5idb@?s$zftlMVimyU)5aef3t?ye~_i8!ltNfE45(Iru6&7cN9p
zHL2{6;7)Uf@kYBzwm+G{x#WhZ<Tw=_cy&j=fVZl26f$D)sRyb5YA9J*6hE5Y9dC^M
zG3r<P1Adi?Z(1$8;YXa9xG;P{mEet>XkC`G=<B;^&@_Iucf`~IL}W6Kk4jGCr?zRs
z8#ZfcWPz6I=gqb?f7C6C{C>wzvepePKWOF_tpD<cZt&u!M?%F%g&lmwLuzpKl3NvX
ziNVs#dq(Ihfi&;UhM8s19qWX$<IMvkFf#bXuR0&%fyC@}-E)ah2IG3b4q;lMVKdi{
zqm<TKJ(VCj^|wsjk@}pcW9Dh-<($^&jh&t}kzEu=T}#SMKG5>(bly*i4pHbxg<8_(
z<?9OnP6+aT56k<wRcuC!ZTWaf_H>7Vv^#xt0ZuP{Zbja8Mu{erd+_!S(78cepGsb#
zl0BK@=Vv^?@q#Xw`%<Of@R{Z++_`;s?2aFOG#R)o6$Smh=q@TFsK(}=@2Vf-Oyg)6
zeYA%8mOp}HX0DW%El?U=1aQIlCtrMIo`X?Y#!XJ2>-~35Vy3qrTDALi0r+dw-&wlp
zw%HO_4c2nA<-wUZ*>Qbh1y$Gyyj6($YP*L+lZ?likpWp-?_#6N5Kd=rRh7;X;O*}|
z|C!$Y9VelE`X0)(Om))nawb>H-%_OIGXU2PDx{TPyck&^KzA(+jBNEBIs{lK*+a#<
zJk7)Sz*JWn<|iiVc{dLoZrwYpJ~v(e7ZA@Gyz0=UusneEs-K9(&4-&#3TZnAGHeaM
zm~P2RPk!8)Zp5(nBeeRKJDAumBPCD0qlj%1<XuQZu%M3Niw4nf?}x%8jJohhyO|TF
z<i|7lQT)cuY!cV!zBxOo3Gee6|Hz}XpS^rv^e`}79lMpn)Ndp@E&L-kmd)<ud)4I$
zg>Mg8HI4@3B2QcSPT%V)Z6Hsv(%su9IozEL9)}&kSH4*t3B?$BlAGS_+_g8_R?)_5
zH%Jjq=^aCxTM^b2i6Nho{t7m%{neVn&0uo2CwGp5ib(D@+htU&vqkR)mRN#vQr!~>
z^cSA>YowiHOv8I+VY@4(otgowNBYMJ+`+JcT_mEO4^P;__5q&%m%fdPXtF;4(?<v_
zbY1_k#iDQ5=kCF@Na7LzSK4;+-jBMPkAv3UPaUUre9VL#G9%>vr1yT~DF5rG8^|s{
zQrvA<_8azp|2q3Yp3iZ&HLxxzv?z&F&u7L95xTxU@cMT(?&CatY+6*jAIJF=J7F1}
zsjHp`4fE|`cwzMV^iw=hDqV!Q;f!z;d6spnO&@@NabWe4x|lMQh)`pOnwDe*v<1sm
zG#yVzom4PvB)@a^e=2H<+?ALPtU8ZEo*9wW^@^8aZsQ@>ffFY*@?88atc|eKnFw*@
z`%Y*}IM#}m_bR+IE|j7k7yJ5N>9p<$7f4Ii69w~L%SODKuCNjbGxS7wS-c$t&|*p?
zD52PKWyd4*(?XWQ>cAY)meSRUpP91Jk9`BBd`?G7rwYl_)m1=C_ASiTe(wf1wrT0m
z;FlP!q~=*J<O>)qwlxSf8~!KE5kkkWA@@>5MT&|5F-vcHnaC_`8oE24gZ607S-4Hk
zbo)cOj*8P-<|Qei$ord$s>?CufQHzMR$bSP3D&KOxh#do)Nc=b;|Ub<^{ph@y3IP%
zj%!L)L5IJWGm3VaaB-x#Ke_FeSL8E8#W!DgYE9aEH-wIGnlzhcSCo)R>RQh{HGtTw
zRQNmTr!Te40=k<&!c|PM5Al3vNIky0^xwL_<-&#z+I0CsC2X~{)n=f6@^!d!0OsT*
z?4ow+utdVWE{Rc94ZAbtqVznJyW%v}wa_vKv9~0r^3mxfhm;Cl#E^e{6ckzdw<NX2
zMoSXM2()B7JR70MCR$~k3i^gyG4DXkuLMDS;3RHWF|AeY_fJDcx`81wQ3UYzS;?XL
zaD_TV&&i`y_V;JkY-rg&W>E2MUAcQ!4^mOdCJ?4@2!rXu7{BAjeVvJAvvRy_v^!_B
z4FJZ7?^eI*axV2$)=z&$O2VKwCvLd5m=j|7&)nO^Ztw3BVfr#rd8|I2gtfm63=COa
zD=bbwftj~aUqmmzXQH-ua>zGOcRJJ4s<A6Uzs-Ly2XF5~y?{pt+i^|055Fue(V5((
zafby6D^jE+GJq>do8MK>l4j9%ZPXtbzu(r|ug>8q#^F*~a2iCp?MEHe!ZZCt2d@!o
zH~Q)bDe7CW5CV(PK34QmlFpLI@bGBp#+s?kMt0uIp<hhxmIckYD)o^0b94o`%SIA7
zMz1Ss$bvj+ciQrbsG(HuvdqLCV`Z6}1*SFpA76Jg6@7y^Mch{&k(QWvHU3BTiX~jR
zwmGEhEe;2o9v<_`B_r)7r{2x?hYvqqx-*AKQb5Q#-pEm3YKOm4fB*#Np;op~^HI-I
z^t4G;PFjj(rSs72Q46h_>#?!&<U5Hj7{^^9ZJI{6WN)jPM@=jQgd}seJtW~LiN(hR
z`v2fTlW*^bGI#hun!Jkh6Jz+5z!^l1>WA7G_olmQ?*I~HraB}4G<d^XDfHXimrMFy
zn}6;q<3jAYqhb?R5w%8BGTI3(ZEn(N8c!o_Z$6#s>)wezTEV$%;U&m>k_;w}l<l^<
zEb#9D`e|0D4p>2QL0jL0<yM@7osbbA$7)0A@Hv8yaDtCz4s30i`T*(Nd9w(Zvc|lN
z1foinyN&Fev=f-JXhZGJJNeIls%D&OX1A8t5+0frVW4O5OgCbdUX_FVIEB2W)}`8+
zqSRPX#(e2^nTFq-<tGR0JN+0QRM>i03RZz5U(5qpR!f0~3s0B}>+Per*0{JsLCpMX
zoy8aI2JwiJHVA#C{oghhmg7P(NgHoG@xxZz-rFigiy?RVetHK{KjO~ak}l6LIYbUi
z$)z&eLIgm)lzEo@BBvV%wmi+O?oI#y*z&s6?TtYoslm($;PrTPGpXxt`BX&K2f{^1
z@+6N4!0m^8jo5VIvBj&*t3t$^#+x_vTXzb6TSd@`Ug65!0tFEoBQa^t&#w_Q9X=E;
zYkmOYO}BH8H%z)@&{0q!aK-C0F|is{pIR#4*E@%*L9i+q`7Ym{!5IG;6<<+f-XYm%
z|2{t7a#6V&t!4-72O;X7lCxRj<*V<)tE0y+spD`Y8c?n}CM71g+uHxKavV#obEd|p
zuzDsUZ?yrn|1cJnO$?vCc3nJwEHzFm9v^OOrz1grA<#6HznN+yHYW|C?-2JW+-;!A
z=%?Y~!FxMVXGAW!@M7gsYXRGxbNrl>-yor&C)s<f`*?mwxc45ff#wv3koSJcb-WI}
z;?C)5Xyobgzar?FnMwIZazUJJqr>58boWcEVJ($+%6vTRp&y8k8FUD#a4NpeW>c<8
z%j?q`Ky<94?Z0{%)i~m2Hfy=oME3u&_m)vrbzK<fky2VEB?U#gLFq=MySp2ty9ER!
zmG18DF6r(rkvxQS3Eai|>i6C|#{F@}{ddQ>>xaVGoW0jxYp%KGeCG4)T|PF{NmPLJ
zy=Oq>;A46#A%NXm%FYJe`Xn?s#n@3de9>yHPxz!Mw4Tx8z(FFPLCYjb3Z0rV5g}PI
z$+*c2?umR=!BaQM=r6d@LCm=sg-ka{u<VWx&&Q@!j`g%qaWX{<#~hnbkw{j(iB8Oq
zKuR0-L-kB{CyNiV7f~6C_`GJ00bd!Hh|$p85md{z&wocS(Hi56VtQT<h0YJusnt^z
zoFZjn`z^JLCWfKm$6`?-75Z<vRLZevLXczd^A#0}xVML!dpZ+&z6`1@`cbyE8I;#2
zg~_;AP#{UuE$_K|V?(Alm%uhWaANuKp~T@>li6*A3IBld6GU10B9gZ_m)Z?%{PC2s
zP7f@BC35#m+7zFgBvrSU)Y#V@OFJgI_PTG2It@Qh=V>+VK%HYFL}IM2KK|lFq}biG
z29RuNny?PvTf4W-^H&*~W^+N2$%(|qcX?-r*PpX)gyrgJd^GF7IdD4G)^cuPR@0Sl
zTZJKFcSh06LB+^Zq#}V97CTVew9Q7R=+pPk^O5qvnOn=&?)BH=)LD&Bzkh`jP+0o(
zPDO;ol29&E0}8P(&XX#pHXz9GPS<|w=`JMe{W%TVIc`b(g>EBU`Or<av>+zg3)Ixr
z`9tzn?WWAldKwkD_3)6etzF93S2qXjJ^`CkwBNt+SX@Ll6@qUce=pg!)k-XM%dUFx
zC$idBZEO7z^!ZwYXM<0$ET!gMokws-yUJ9B3=&_Jg;-$$7S`M+he#T>m-K0;0y1Su
z!u5F$_QlsC$G#tZN4jmcF)&|pHuK!RGHj=D4h+<Eyq2skN>?jKduEY)REEE+sK|n_
z$M(&C!qVEsTPyNQ^Oc0#5?e}EoL$>f4Lc8#ImS0Td<HPRj;2MK=Re^IwfDZfyZazn
zrI2FaQmOR90Y2Xl$|u{q8AU<D|CFV2bI&Z|CCQUn%7VGd?DmXI!#!6Lvib8L+6WQm
zm7RadKxfzwWEPKMIGI5;9Di<~J0v)ZHx%0j5Rmh^6>skMm#E{^2>7Z_HDf-t{}M4+
zVI^Guk_}C;VqIoJ(wW8xQGBHm3&g#H33e0rQ*iJeyUlvt*Ky9ve%O$R=k{(N8&Hzm
z-QXK4#f$yaejdLSdK4j0fV}R9_zj+rKWj!q^krt$jPM%TZgbS?-N3Lj#?xi_teFP<
zroIyO6>Z=j2THWH<qg*ItX5_W;VvA!fAdrk0xSSPRY4r*ORWUoJ3<d=^8fN;mO8Tq
zKYy<A0gp*n)p2sUu~Rz!`XTsvbVh(}d87XU06H<S7wX(mO&Tb7sm76`KKdFUSW)*2
zL)~-4XW=_GibEO_Fi)216~S8ieRfX>?Ki*ZnAK>n*mt8o@S?QFXjKemCtOP(3W;7Y
z<=Tq@5XE<Lv6uzn04nE=SY!}T^4mmKEG+WO9mXE&<qhJ`x)((sWQv!;$@0q#<`&Ch
z+VfU0FFOlPFW@<3o6j7HyxwXkNc`xAPk~s{Ddhy4(0QFOxzCsr=a?odPkYg&Z{z9I
z5jiuncBI}aZ8YUS;1%NN@ppU3JGoQ{|7?OEF}UhjcWwUu*l5xB@ko>v#(qDU0W-B`
z3rDb~iR=neZd#o(r9F9?99C1w0Ylnu&c>dFDHwQT<skAo4=P0Mx=w#mJ2yDmEaBFz
zr4CeHP(TZ5LH5cDP`-0`=0uP1@pj_L?o_d*D>))LM4gkm?D)-JF2FRqMg`*_B`);!
zjPpER)X{sV7c!V_n2P}}?!IJ|a%geyojQ}FvM0Qa(mos$I)7@<v|3q+hg66@CdJm}
z5`|<C%0I5aT~;kyEK!m@nmb%)z`K36N%p58;`VTZYM_qA<-?(of<RyeTVN(IA(=N{
zo600^R5!M1h6T--aipRVGlIF$n+pgo(+}vG*-lLJS7)%RQHQ3Adtu}j`q+A$sG|gm
zI5th+WPN>d7T%!4Wnbs!wKQgrVdVvDWeqIqk)pX42CIj;z(>GQ0qBa&PdD?7eXObP
zgJU!xAGJA@gE-Oof7dt24QddM<I6PH*W4<pkJ>j=C$LD*EmSTl<wr`;m#Tifef_hN
zD6zmd+k9S;c3`=4qZF2UI$a@_p-zU@>0YH2v4z)EBtZ#IPjSzS-LyF!5#&5!dNsTU
z^nX(FULL?*>rH_9w2lRA>j}E@Q@p%3j9DJxTVwuAquVs?saokYVVqCaW>W_^v)MkM
ztZ2qYsg`s#s|b^5+9^?(X4f#WOUe8V_Yu>J$Qkiy_{QI{!UfixUYdz~Obfm=cow-v
z<qL~-2`5f^HV<%yZl^5<1}*G+KoQnC7eZhbsc`-{6uz(}$c>&L+Rcv9mcs0-XM`-^
zmpBse*kGLiV&XfZH_1MHRv7RL?=?3Of$vR_75wM7QE=0cHWCzZ@dGI2G)q0~=d#o>
zXBC((0xx|@d#*(e;*MiYYvpqw#QLYX`hgOnE0uOxSkNsysC~4r8<*)(v%(4EI^awG
zj^*+`=<9UWjngkQ%HoxhO{g3$Mv?diNEEy6MBMRIaTL^Z2oStm<;EP^H<V($`Hgbq
zb+--@2SfUL)<nx`XU`$(!*Dz|BP30iBjQg`6)bP%K^c0T?}6%}(z4&VB+maDdr5PC
ztY=yM*9|2SgB#6+U$YC-4r2}yogu2@!H#-V8Z{)Z;8ELkM~<m)nkl+3c4!04gbd9g
zrGjbNhf9TYy5BqtBs(86?RW6Xq5dpQBy-h11O9)UtECs9-Hp|PN(OMfp@2yvD;wJ&
zJ?XMmNa|iYb9MmN=XbLVM?1M$WfD?aq%N%9cx}jA^x?cx_1k<BqD9DhysLOc(wD3{
z%fOzMw!I)sK%e2bn_p5Y%)8uv*U5GQZcAuC5IjE*H=b6<pvK#x!@m&+R;6z3(2Pxo
z^NYiHS)4(U{%D35>!+@dJ4b0xYQ6^WEhrXJer$NlJHw*OjIa3gr3>c4_S?Q&{n{AT
zZviykMlySA4!lUF|Kl1~X+FdN+VT(pUg%uxD69;w=DrcU<Wf=ed4FGId!!Hrk)}7g
zj(?+*fP`sya=SA<DAHIXc=QaSbL8>1_Sx^2g`ewk*73gO>G~x6@POvf)xw<Lq9)K=
zVkX+Ta^FLN))LcpdEh=!3PPQamuE=lDWYq4v5ywnaRe0W;Cu)d^olUFGBDd`UNv{i
zABuM4^YLuvMct$l(UQHYACV)QvFjb4({lJ2K|@b=tFe@2_6Dsvrfp6e-TJKL&s4~U
zfOMM_;(fqkvlps}vQJ_4&ml{|9<jMRV+CA8i?b4Yq2`<)zf*sFps6cA%zjN!GF^BB
zT(Vuy!~@o{e?qcYkGnfZ<4&4k+|}lcsNaYLhI(OF^Dlu7n*j{e$2ydxyIjLhkEzw0
zsfC1ImpM<M=PEN;&Y*quKNhhM^!aLC`tq&X@~-Ai9Uw~qh`tjPcO(u*MDdxqA`e)~
zZWNFv0xRpTRG(bX`OhZ%eC`dnr6((MUGY=HX@LDd2WF>96ZROnUh}TK8Cr^ws!kb6
zGqR<W((WJf%-$HG880j;l9FEcSBJk+Z$=)W0p;l9p5j0nJXWkZ2l8MS)U$%?$scoj
z<r18Yb1`P3U4Z|wx||I$3O8opP`5Cz$I5N=xuqv(tbZ4de24~6?A_Jn=g+tsHChnP
zlcd%{F7*Go!++TT7!OsOdchS<5$E3by&ZtTWyRHW&^h1q7(m!%c|&ZP2oHfq744oI
zWzcM0bA+&Kmp_Q=R1z=JB5YMOu^(Ajj{b-Q7HsE5@O`Qh^`TB{rj6E6c@~4|qk=_$
zuZIW_{vX3#I*%{Decqm9bzlg&GWQIa{F^Gh0A4di{}nSl@FXF%+AZr{(dhaVS?u<w
z302i@(340vi3%Z~@l5GgE~%E&NM3-{clFI~V7XOe6_<Z0^8><n?7(oJ^5;fqeSSXB
z6C#Z}b(H$7%<6Z07}-ey)L!8~y2*6`7f$#3BQ}v&bM_1XKW?-|+dwgU{HDA_Gp@i8
zwRXh6;p7KQSJHI(jNH6hn}37Y<wV^0x(1VX^_XTi+MEp4B2K$UvdP{7WbWqF$QV?7
zh_p`hK}~048I+M=yzYrJkM;j-1fOdNs7ZuIC>5E@@23EUq$b=|&)Ze*I<m0QoRK?5
zP?1|=<l%;Cj)w}hv^Ty;WhqRcbbYyEViA4_9)i2TQ*?TDWroy29Xw9MQ?|*6pWkrS
zu8(^@q6**Uqx?1FS{<1Ccq8x^JC(OQw?zQ%xN(2tM27%y{<ghx8sGBi80<uj2!CCG
z5zHq$UV;*?x;k!E1QXm0dLN^ty5N-mg?0yH&(oi=_G@l6;$OdHpOMphoEGoH_0(@N
zxZ29jz^!O!KE4<LM2B!M&M$iJdwvbW2*3jBH9ERd*}4p<hn?To0aeOBO|pWVT<CN#
ze)cQQkP_{NgZr<-X8|-daRsWpDDO}W7cjF>+hMJi#%?>lR>kSQy<WF9ebV||G*Y)v
zG?>Y|saJRez3<5KNry%_ehTf&rwdI_5g=1h0hO&po|^*L52QnXsAtptipbHCbzu43
z=+Zb;g1BGL%xn0(^(&lVO()x9F7?z6m)D4|Ajga%&lm0MT%R_{LL{G>L?b+Zy+DbS
zcJWdn3-N%skuZ%F03f$ZF9Cly2T=pt@nX)73bnSh+Ujp4I_Y*R%TAh+l89aP9v}y)
zcUDj8zfaTh^GP<OWp+94HoT;)xF9tlp=5&aWlE>Gh<73;RNfnlh;yQu;2}qxN>-%#
z-yX@>Yr;L$M@XB0RNP)KL?IR}U#tSo>#z3vcjMz*%lBe1%ihiW3UXD;XzK(olXgbZ
zgjb>vn6mYyGN;KecoQhqxCC9TDVL;NSEkVVF37J4)r?@aR)SvDpN4y@+4hC{<9iNx
z6>y^Nc?nP3MEqS$L=Ve3ov(;0q1x@F@+p%!is~tBpWwQh;SC%ul`yn=pU~r&fe1p?
zb*ExFz=An8ztl`IUR6lPr8Os)N<^+ImakMzr2qE#5(>Ctw6%>+jGw;inJ*F6H2#dj
z_qs{VWV_F;GePkZngG<h<cc$`s1gyhwJ0_9Vx^ipJMno|A6Myd!bcD@tT}dBN>%Hb
zkf)KScA_H=JC59lkx#l2`VL163XL;Wn$GsaM3i~Hq{&tip}#jq#!aGe)SvltA9<Y*
zC@UJOWHe1JBOa2K_9|ZcZO2A59PRZhl$Ww}Du;#d7H{7^A3q<=7PuhlT_B^}{J@cB
zQ7tCw*u=s85INOzPw%4@kh#^?9rZ<R>{(&76`$~{m);CA`T+NJ3H2ft?C7>7&9noA
z;o~z65Ra}%%Sz@gq^(OT%8WX=sH;E&Tsz2ct??X$o4&s%v-aQu0l}DgwcxyA4r!e>
ztarsPo<5x2yXIsAQz39y!C+UYb2#Yp;*Cb;uyV)4ZXWhId|hvk_pj?8d)t-<KW6uV
z$=nGPJ<q5DKYOkrtMl5|s;exDWjCGqxp`&5R1XmM5mz7V>9Jrc4BTQ=<zW`Le%mi=
zskMK*<9JCksZPWXUSz_KPgvdp%F0U=$lWDd{PlTjd)Dt6yrvqkct%l#zYJo3FQrG-
ztFPtfODAQ+Zsw-okvD(c8k&4lD%Y-CAKJ50h9zO<FO6$NiwKJt?Yk_IsS4QmLZvg{
z#b0w`!qAm;EOT_O#JdYXXr{<2URl5?&^>T&kZ%<Jv*0x=JPK@uCK;oC9CthTn?kPy
zrdw4hXLxlX)K^(&f<}t)FuwZLgr4o4m+teFR79u229Ei>^Y_AyW~#!?X56r|>xcIO
zRA({t6fe;C;YocNp$zK2GhNmUlB*!kEqmMQqI(p%{kf@4ZFt~LD3ZpnW-9mvRDTR-
z@1F6-h3pDYt6j!;Qll*Kzc^jpk(1(zoFuT>FXd5FJn3Fq<#XbV?OAzBD@|IDzK_re
z`L}p<uJRtU>dl|xZ*ixoi_pjmVb(P)OuB)$)7rTQ<MtQ_-e=Zt;z?%cD-d%{8dr7T
z;~nN|iX$-bm<n&tnm3s_5Z=69d4s!u{AEmv!3W3%B7_<HCbD6&Kt1xidSRl~R}IIt
z>z>GxCf@4zQxbLXGiAPMb<L6F2AYEfr(@3rZaY{o-9crh<)(E=ov!(L@IX(t-a(;v
zVpj-)o+8kp1Zz7{e+Uy^GHu(jI#s-QZ5Cx;MPcys0&$LYj$4vVtE++G`y`Urch|vz
z;zo;RBda097ZQk0?0nBZ_jbS7IUGeTyx>-;-|89-`;oJdpAZCU=AhEn$vw~fCo`)6
zaAwBVmji}$AdosKL{U2p{q?b{!W(|pZM1a?iSqHTB7B40iN1|<!{;k%pOQU4pfDh;
z@qD>5lqN!Li-_aBn6tpf4d_W6{T<a)wPHLwRVZpg0Y$O)CjJZBJ#9j!6PCem8%bp@
z`~#_E;9xU~SL4S~mR0hRVjJho$UUoItaVQGwg5e;&Wn9E@`5_c0gwpvKAN3mqz}A0
zl#(x{qSz$(h479Z;c+d$NQk?fBWh4+Ou2o}%tkW_ClI5!`|=r)(6%ZmP*Vl7FC7yQ
zrqHcU*GF7B?8{*4=vbUUi6L2*0nf(GrBDtR-Gg3g*9GuZ1!%-_h@nWRtT2BInU8tg
zPk&DveCdo>&~oMR>u*rlUhea+1Ii<|*?IafN)g3AY3#)zQj_?8UlVakiTY-fT<W4F
zAW-yTV>2`<tTjwbKJ{m*Wu9%Qz2}v&6^N=fdd~9=pDU*1sHb}@4C-L2k)5bL+i46P
z8Mb+0*DF>-lfA#?#Ah%hzA+J5K?lgUz|n5bJ=Ff@Zm{6&qIiK|pb|Q*ujyU@rwGlg
zPEL85XrCrq%hQ4I=EiH#bNPFBe?~b;rP1M?_;@~`_m`vKRZ}s^1x)CB@XYV$ku+=L
zB@QgOYH|kT79Ykp&QS^##M!K#!>dLZ-HRj2;{M$!T*DvCKq8aG#Q>#l(LHU3{)g`m
z@#2hmtLWCLX(E+cH)TZ~1ILrO$YQ+bTwmz79DaTpNIDgB?INR^4?SFNf(r9~psS~?
z1*!NNoqhEaR5d5&KFiDv=j+f3Lp}_+_`P6tdy+>j3B^gV;eqc3O><gl*lPP6%9Uzb
znq%QY_bBErTe6>rOt1S*80z$9eC<|ZMupGEf{u{ZPuB|V9KICGt@Ahzqm&!hQFiTG
z_UPD!<xkgs)V<kYchAhF?=d`Ch!iz&4)b~kE7s&Hacs$Dz|co+EnES()j)Zn6)*I~
zYp&OLoSOfHy=OY%fA*GMx`%+1`7B|tFK6O?h&44oKmUm;iK(fz$V)lF52JY8)qB`j
zNH={zCm_+zBTd}z_}irkhz-7HG_yizmdermP7}stB2>N&1)TYFs!MoiG`5O6E>TkT
zOB_JmO}?AO!$LmH(J*;Pe$*%&ajrxe($(onmk`mOz%Y5qWTAN}K|6P|Bq5J2VDG}=
z#G^_ZKM|(U->^-s=_@S8w9uec?KE17Xq+5=xU;->DKdXs@Em!X9~q?Ed8?N-uQ)Ug
z)Rgl)nccXS#%AQfBz0f&q(@8(&y<G(hM|y8U%nr^>=rGj!qE4+w9N1Q+{6-{%aPUz
zLvEbZEjpT$E*&L(9@D7<CKM`-E5!UEu996-=ouN7xoAeuh+IAIQvNuKdAf%^co^3K
z{w(1vpE%fQQ#U0ik?ogR#;ek5LJ9l2Rc1SuR|UU{&ie%QImKKgC#OgO?cd!xuyv;M
z1t3oS==vSaC$ds2uXNaF)H$5Iy^Qh!zHRKCGGj~Q*-AHy4;Fu%p+(6{Gdnu0&x*9j
zOQ4{tms1@Ea`iLZ8?LHHshlZ33p4c}J5JNTP!NDj%9Bq_jsn$@f*?H)q>44mku$DQ
zMLKhsOQ!Z!e!lNaZaHIZ&x6N+Myf06%;GRTp47Me0P7`eIhEGkhMxLXkwFrycf9^w
z%*whAlD7vvH*e)?kK-06p2CadfljjRsB)^ha2Ji{0==V{5nImi*03G4$I~Et7fOY;
zD|(5S@_GrMAA%%GK$a7S)TRMHZr+-(U!!5Yn()g`j(;Lg5xvUF1SRC5Z%2IZ{^Wes
zfe%YfhQv~{?z8l_1?!s<NMLJY7@ts0ch&e7v`Bo9C)u}WCEn_#kBKC~;%pc{GQ{~;
z_MXr0mRJlz>RDG<hdnMM%{suRiFk%dQ`-T=J1G1^*6z|o<zvJ2jgR2jekH?oZz8e%
zzUCl(RovS1!xF0ZwIDH$eX(9|V$lXVqt-N~7K!L>l2ZX-M4ojgU4X=9t{h6}_G0Ae
z_we&So3|*Yb>}f9EC>pV;e38M2RLk8%=OU%Kj%Hd^V-J-BhixOkr)_ExjDI0D_&?Y
zff%Z2q|@jT(^xc27QIGier@bCqJoD_kQOI^87hTYIi2cdkmK!BJ`AUm6K*h%mspDr
zCZD(n)Stb=%o>6;a}7wMm3%cJzxZ%}E_yK0s-X#X>@b$yWSwn+!taMCoc&yM<v+2L
zp@5`qN6z7-x#ISQ?0TQrea`FA{D4<za6=#vgN8W;|FPGMbFTI9%b;yhThTd-nS8(E
zTBtJS>Z;Q;qmh1%+d_L7&nln-?}bj)sB@b)1nFCs1O;<E&{JuLn^w#KEvXj~DG9L5
zFnBdAZ*XNDFnX4wnum)=zzf%u-zkbyDIKUh#>9k(tf=@ctkjpl6d)0}c<e(nY764o
zt}+#!VT+r49!AUV`>?+0Cyp|dv0jO1`i(_B*;ml%mBWc|A-;1JNJ0ZT7EZ7jWFTpD
z(+pL>V!P{3*lyC)K24)hIk~f8=hu}{9Mf7Ac?7@|z3Yf3bAD=lt$N_s4Vo2%-7`Mf
zwAbqxTF{}VrezB2jk%^0z4IEPSJMMq0ARm~E|j*$%QQWZ<F7fm*nw=RU0K~L{IRm3
zet#r!QEjvPLYq+j`bv-EDk_kVh)~Ncpd1i6vyyP+Pz$4)pPYxALq5<oL}Di80$B)P
zSXB|el*L@#MxPeaEmz+XC@y_(3{yMoFPwP55#O;Ib{_lm#X>X=En|$Djqa`PJ^WWY
zMDhd87<j((Br&HddCdRI3K(tpmHrEe6h5g_STr=FCb_!3;6$56HZvLF6G2X6hhAMK
z76-xrw{=vj)KxsXrEYP!h%Nzn#~b>&CKN^aL2fZhP>h8S2m;8w8p1*hU%3)L>h4%U
z{m-@PT%@q!jxM2WCzWKE0{bJM&mMjr5s!1Wpv1||1>g;RNQ}Nq5+dMTPQxQ8!b{y5
zz~6m<4!jczpkllBV;$I!3b8U!(xh#b7A;$R1o^VJ_Z#o*)?}9tJFum3S?(PKAWnP5
zSVx1u18Kto5p|C&x619sHT6I|0=Vp0mA+OS_|>k2_4G-!UYBPM-^tYu(^e5DZTOz@
zFgz++uH-#wjkD1?%GrCj<ig_DY#bFeRYN1WH?*FuP1CV|YqYAn%QvkgW0d(=**8NK
zO5{aIe>Y(}&^37}gh=jHbv@`b=#l_*T)Cd(dJJoY4BxU$&>`s7m%^<(6B_qI*dLw<
znL8h)#;jS`T;T!C==8=M7t=n4a>IU5+p-ke3B-4@5S2$Ce-taCNLBM7pzc%r=)Euy
zXIy&fxuOoD)@Nf;ZyF}r?vztnpMqDAJ~Y|ZaZ={{bM0DJ^3Qp-fVa#UZb%dItiVVQ
zNJiv_Np^h!Gua5u@IfyDr+*&OkdO5)igwU>-yg6fBj<dbK~56@M6u72ttP3CtJ6Hz
zI3C6wgh2vYfOh*M^|4OXWt!L47>a$*rhn6!OSs9jVWBN0IYRe9M%a^O8NyCx;jEaY
zyblcs?qqB-T|nvaEE>~Xa`j{dJvd}T+MT!kNG}1&%5(Z!@Lr5x#JLQqH7&bt!cqq~
z$LOdq4dj9JJSrdz4Z-oOx}L<|qzm_vDWakaw)&>&q^l>rT)~jTDe>iyE-fxPR1`n-
zaCrSv-Fy_DKiSSJxc2O3#+=G1Ts^!T=#QtjmME%6eRQe2-Vgj>+>QLDgLQQDT&|E#
zLA=859g{*kGOub^Tijl=m<wv`GQLUvFI75|S(n$yT^Ve}6m8oYj{u~xm*9XaG9@8F
z*t>q2SomW@;B9{iXZf@M@;%@y1Kt}O%`l}fJfKC6ny|!*`%>N?bO>T4dAh+{r8->r
zpShp|4g+TE`TMIXSoxcijBNglSAY{v^?|ltws2M&&smU_;A$BN>5NnG6u@2+sbw>N
z@OmmQ|Kkl_2BdIcq3yB+M$AQ%YdRk|VEQbZ?dnhaC2G`8&Am^;wu)CDD3Icw_wX!-
zSnrKPdfy~d7#gk@zEkKdCob}!{&2~XlfL?!cs);1UAhXh5)JOLSq9np;vK?!C#(on
zhq(r$%MOR6-(v-JcHe<oPdK^ztsxbKf&G`mn!6<hENzE)xd@GzaDHGvKx+ul<EQ??
zN{22sg1CDg&xPR~lRv0i)!Gjj-`v4Lz6AKHsdoLUIy=PtJRPC6+_JRyCw@yI1L!<=
zAf5wOyHCM(dr3k3gX-+(GC@;1hkYPo?t*to;zt+M%MMlm7wc`U(V(@qgr)E34KRN^
z5fvFQ*K|r;N`nUiC{!>F?Hi0Tba{E-Qhw`b@K>hQLH$wCyquP%p95xKkd8<C+1uXR
zr&SQ|(+Yebe2Wp5N>d$8U0mTJq9#L)&c!5nkXL5;a_7pkU7E>pabDg<^9{hai?}|k
zf+Sd$<(_W|2_pcZBbWSlAhJlX%8*rlhh9iAG<^l6y==#~tX~ePRBH4u{LQ^#URw}-
z%}GyFnr7hA*VGxc$H=UN2ikAlNyTr-9ACP>A~OU29!SarS0sTDMrl&Y^C$-0X}Gr5
z;>(x}1C#uxfku}{YO)E!R>F_W9+c!Txjo*z3O%D?q#7yjwXx;Y5Y-^w<f8-_oq~!G
zBs|s)e0~;1=C$xiAP@Kq9MY^Ehv5~WmHlldg&b{|VnBKuPSGpO+Jm@^g0@lnXI~%N
z{t7e)%8MjA*oMwe1D0*XB_uqmAUNA}umK{uY%6+*Og~52Yn3<K>Jso%QEzq=GAM?A
z0h{ysf;yG^1vR0wZBzl#4%pplG#o+4i}TpK=OVHyzdSXnv)b1zUNVs)7dQ(#?6Jl9
z(QEi+ycIN+#((9#iE^~IL+Y4p5r7FZHgp&YswOFPx@+$t4vE6&dkx5-44J{G?)0{&
zVXPho=w>A3g)?(J*DJTBV8<eXz{J4j^vnU6LJ$mPxZAWZHXpMNTRC}ndk_;Q76TrY
z89oOBMFFC9Sy+1hbH`MP_0>YrOZbbfaKJoXT{}DH49<>Oj9ZMw&`brq?yqhqPrA+W
zzOjBgnaA)$3?AQuse$_2pR~x8p&)_e;K-o}DoC>K%`1liUkY>#xb*t=HINB7F;&9Q
z>#x$!fk?BjnVsMYNT!T}GuE4B<&Tb9(dT%yTg$^W(bOP7U+<qzNG9t{%cRkDOYKv`
zQSi4Ca#J&dDMq>*x3JZT`wWwn7|?0rcqUy3EP{+}hIAE~89mtifPPG20H768lT>(S
zitwO1T3hPFS4BmqWU250TIZJE%*WT-n@w=};}#dKmCpRWh@$O#3Kt;j$rk7J7PHIJ
zZRgEk0nC5#jss>aVSjq9{u74s9g*e6D~lkYQZgqN0jl6nmn+~I2YYV$bB+yilQM(5
zc`>XC;#8Q`svph}c7ORpGY-)40nVzVrUD*Azgc?2$f5ppq#^VlnK2;E2+Riwyca3X
z=wN}w&Up7|2huB4vQ{<%MtPT8dCd8}4HTIO?r~AbIWYK(d`wW(_JFnmW?1{K-yKS-
zYJLnW+tLahHl<kQ)XiwXO1+Y7I)zE`)V(qwzaMCWH)%C_kbFAwU_Tni0PJW`H3VV0
zbvzBHhNT7$vDSsYg_Nh1iy-SB_t)=Qkg4Ecy?GxoQ9oUZkM;N;o$-e3`i+WhfpiIq
zzJLtXynhWgIZ}7sxeJhVfQl<)3n%&n+_5M*l_6?$MzE`*f2SdkQmrCSt)a5O>Nx^h
z{}5@dWOh>k&>@#yd}%uKdMVeLB5%5?P}#eXN6mnT#Il5mwUzo<8s8f7l1c8adtC6W
z0BJ&~azQ+Vbr%#1&cf9W!^&hSOV>I$ZIUk6f-Sr-AIgN0b1;DD3fR#7pa`UPQg?od
z_pA1!w(8(c-KmvviC4J$(K4jtDEPAJOvDUmkYOITe&yrY5#m|rD=re4k^oOexa@Rr
z-ly|3g2DOFAQ1YO3$Q|HQYfxi8V6~)G)Dmyo3Ue+U;busoGIOB;hc5^&;LXN=GXT@
zu+JQX&HDU-WZ}zjpW5r%SM_@V1Ddt&qq{gfpZCq*q+EZT1SCJ6xoeKe@YbQOiytPF
zsmbvc=p}GZgO$tH)0#7~Ck$UsckEsFfS{V^Hk^Obe8F7zh7-s4Ne{Jl^>R(mhUM%o
zZW$#;-7l%8`rmvZ_jf-UVVyU$an{ZUdSHYf{f?yi{R}G8Y4oMR_r!|;vpACO=vM+U
zb0G76^XE`Qg6ko_0nhKbVi{=9is6RdG67K0jS+Xh83m9*54@h0aU)cpY9W&2p?2B6
z2+F0MdgZXT^r-2SKI9joaTV_m`xhT;$|n2PL0u@8<Ed7`jDq_$ai{Z@Hn!zsTTJ*T
z-wU2pHRDLuXThf4Gon>?edz=xMwB7UXM|S!4cR+6b#`$N@PPd*p0RkhaL;HJ`*w@G
z47Yhl7|n2vtCztQp&J85z*YR{&eh%HFkNEQeYIrz^6mWHt#oq%;IiZH&Ym4cs%5(@
zx15FutFQl_*|I2VhH^k23h^C7*bOk2k&_k3Co`~dv-%!{3EVO5olsBA@!Odz@Z`CN
zw(U~hTp%hmDXZPIGWWPk`hkIeal`-3b{hTB?K8K^k(;rh5zYzQx&E{8&JR`Wf_222
zo?a0268i#zH_Ej6Y&X!g7LA<tapgz;XIIm)5vFc9DDYeNm_0v=&x2n8+EBPB=O?x7
z+FJ4)MEAQ~w&(Y}ZcaqxGpZ|BcW%S^&4sQj>gwj@7IRTetEf+WzVAi6c;11cYx@G%
zYO`zb6Wj+QI*h0Y6ayv$n9@ZCL0fJ5n!Znna14p<-Lq`Yk+gGBWOGr~h1ts&B_8Yp
zx0$quyF60`*^SpHcLP@3(l=X54$1OcS3Ir8Rkp42$nxpbcb?Rmy_%><_1<WAS%q)f
zv-QzSfA>bja<r5R&QZ0Z)6nra-f)P$!gHc)lwS!Km>$0)K2>smG=)ABP1M?`el<XF
zs8BL#QFfqPchy%$R9|@*9QN`T*G>?z!;C@T?UBel-m%tN_MR~;clBkw78g-zzej)2
zttE%Yul}%NHN-}f?Q-H%GhH*o9!(l@R{TkjUl(6FXhsbanob{inCFVmk@XOpo}3Zs
ztEHSbEqjSDLmrxp3mmPtLs6WzhIe_$)EuiNjwE4Sqey*K_UZ3q^j6df`HU|o<;t1z
z;k9O2FvgDb8$ZfFNpUa775j3FiX0qH?vShD+-D;&^?4IrS*1oX7oNDg@)9hJ>N}m8
z>{;wPS#s2*-#R&%Um6%{UF63{5M4=?+ESYgv_22B+zxVUVD-#7=55qRuhpI#a7KMh
z8|)&#Qy+o0w4gY}{BwlJYHW_2x|Yop2bKHUj|j_ds$SU9Lh$k7j+_xm-f2=RpNRNH
z^!~2Y2>e-Z?aepIX}S-a904hpHqu=<SGj?iu6sApD=vpUgCB)%S{4fR4*KsGu8OjI
zT2>0(b6nfKk$awVxMc}v3+#I-RV&fNQDI5!w-z?=H}|FIg>j9lRv&u(j&vmS%4#+u
zX>^|+&s>2{Sor&z#WM3g(`qW2*}X)Q=5R?<l;)l-e^Z+2UzCmU`1jJ5lU1+jYJo&F
zHOxPw94j~qqq2paBLKS7Or=m)Da>QO6M1-QYGq+_#Ia%btkF)#vbOe|YiCrtkwqiB
ztgHUj5Qn?hR)YJ-y;$;{%a*s?Hqy1hip!7KU3hW=Tjok9B^(@Wr=!gAU4Qp1g@oKF
zYRr13|Fr*rey891CQvW>wuM=j`?UBj*fGwTto~cJ$id#kESBSsx}>Y1GATk8m)OMW
z-{zh>PENlqBmzC>9lCm4o4$}IbBq?`5*Pip+8A_~c^EN`f{K|gz4pnL!!xtvjvt31
zD;LROKGeK;FIjOW1y^<_PCuS;uKb*M#BFPw+C8Fp?y(j%SN_@aF4Sl1fWBbpBx^#t
z%53Grtu*gzmw5K3uj}PPv)G8@-8Hj2X~`>I^(JMCP5k@y<?Q<&(Eae+G7dtG_tNin
z+BBPOlXtbWrHL)Zz+%aZ$hYD%GGfVi+&WfTA5C<jnDbLYh4+5b`%PfM4Uxj2I>$$+
zS}CsSnjHF!Ej03P31>KAjpwY)%I<JD|4f3)i$Y824Ugg>DP&Taj&O8)=MAe9HWu{>
z!G$stCpNgqd6UUe+t;eA`Hd0$w=|}g@w<+nRDw3cqONP`TlM!Q*Ncxe1lNrde_~2H
zSoHSgwK2Oin(Y3%P3G_@s}T8W(WuMsvpO!FkxT!+uw~&WI?G59&+|?Che6ql$~-YT
z%b(1T2=7z_Q(USv!!)miDR@h9Mwsn)kNSyOncoqOZSTY-s1dSOE944FFk0_?&$M(s
zzLUbLn3_vB!;wTKmd;aQn3`9QP;A%t=MohZNj$p@ck>`z`AB9Yk{SHQqS`)sC0fUf
zqM$x#YUaE(lecsjRh<4Vm3RDjG4dH$dqyG|yNhx14E7sd;ay4je!M%=SGftLmu{L;
zBsinJ`E}1N$ylqkt`5h38>l??oGtXv-@;+lT$o&4{#jw?N1`l<b?N0GmJ=ZTU2za$
zax690RM8P@{Hy(1z7hA``auD4rvZ+nru&<8_h~tG>++04bb1zMyfF+XC;9;L=6?FJ
zSfrSM)FA5Tc2nc3lhIn+Tr;E0;nmRD&ixTura=9$w_3?sw#(n^XG63S3q_lXtM<Zf
z%O{Suc1Lny@pv)hdjfnr%A<)J?Sl02Iqp6NhE0`C2mw!k+=GD>z+G*RO>Il;BFbpI
zyA#N9I_XD<g^G5yHXHC>sykZsNkMUK9$%jA8bo@$H>mD>Wh&FZufH`0RlZ?Y@nj$j
zpK~c|(gMCiJ|+Fs{o~w<rYO=UE_ea0F2T}&>_^9ib$10(r+Oe8X8xj?=geB#yhjq*
z?108gwoHM+!CgBsAjQgaj;_K#zs%NDeC%=@y_xg+m`PI6^TLiW$)!RVLr_-pW?t37
zy1&@uQCBspCfBo>An?}GWd{RV3Ikfgrdsh_v>KD1P~_c(m`E3RWV3kxv|&Q4>Cy5}
z8jWu?iFZl3amMvm4rSG?`Tg8*CTm&MBZa3XEo8RPYE3SMG^D_b>r=Aq0@dx0oCVY`
z-c*|^%Z+{S#~B9Wyq*6hnPXP2lI~3kIk$^ftQ<3mrpJPYYUv7V(~Aqk#%<&GuUuE5
z`1WU(cJoct)fp>5^t0O`Z<FlaR9w&lt0C8`=DHWiy}Oh!6_&U;H7`$b<2FksPkvsz
zv$*zsfMduY>QT0lpI8+=;ZKtT8Y)Z&YP+N$@?<Zn^hkNhd0S06Kew;SO}P7DKBRjb
zu7frU?2YRPM!p85m`(o*ssnRBwwjXl!&2FCFu2P3p3#-6q%ttEutMiX&arRu>xGlq
zwzEK^RjQ)feLqK>1iHxSsUV@4RO{uTPBQ`Fu>cq>;C6T{8yWL0-wje%`7Yh1n46s1
zOY~e+&m8oI;80*m5W1uR1u^Tx%;C*OMq+7P4cX8c?))CZPUcLAkT0-~{Thj36Pj!~
zzNtxxdY~#J5A7FRF0nM(lK?PQHIoNp!4b3M?oy5WsN2aw799`9jC&}@w|@-8Tey3b
zkXLPB<mi!tsGFCThu;ea%VEl8tp@k^ZR#kpUy{tm{q=*$a9ZcDkAvURwx%&VzE!Hs
zME?!CG8Sr`qT#rxsl9j{Y?+N=NoHC1Cc8wEz1p6p*?fvFK7kO`+?FCI662_VD0Qro
ztZ`3j^`}HxPKdEM;wOzW%Ygznd8z$d7vY2$PqxGQfK772gcqSEzb(FQcAK9-=0~7i
z4k$}!U9_zE<WFs<D%o>OLfNa&H?gd#ujWah-z3O#1rvxuO^)3aD%T?$O78HZI1p@i
z=ab~!y!eYX{S9GXJC02*I;*U2>EZF>%k#*$elcY^Fd0aJN8S5C{{pvf@G*-6W6p_4
zqDL)SX||BMXi!)-P8IoZ4;_9tVh@33)0^z&_98VmB=HvP{fzvbwcZ~$Yxy||hi#te
z(<#2!HHMST?4?3C;|}D;9eCVW6QdJ|Saz}6+gAIO6fr8Ekv93MThR;>(uBA0XBK@0
z`hrqH)8oe^xYGSuFbTvVCT45}N0sFXaN55=RK-qm#;Lk{Z4Xmpp4BoWOCqrHzEIPc
z<svS;E=Ls?wa2X1HJ+cj6?pq%^7~a@fV76E&lD0}%RRlJCsUS%?OF582f3_1Aa)!l
z$&D}XHM}1#N-GTIWZqqhQAIhSJGyqX6s%l-CW$7@YD-%3n+mB8!MDT}!ESf{8+ZV{
z)|lb)yC&nq5o3{8V6Z0kObn(1F6Ld4!Qzn>@zN?@5`M8c9=*x@XejJGiwj9XIdge}
z1`dkg?#VOfIDB;K*pfw$_jP@;BB`yv6yLna6J<mB$Hch8)8M@gRUb)9(h3XzD1qTu
z_KBcwG@(i@|CWGSoB$tV)-aydg$(}Ss3wY3vZg4FntHpBGJ)zR?M76LZQp8v2X4#!
zr;ZZ6Vlv?bg81nZ-T}EWg|{yh-kMI4RaMUWV$&O{rDPzAjO9cL$SMbHP(J;oKotk}
zJ^!M74URN-j<N#nkbtZY9kMjCauh%MQR<jrQ}%rG<=VknRFXpi117(fVOi5tVcKle
zM?vxW4Pp8RA5%}%>x44UN(X^n*{J(OkWbie%;p5M%f}mhsIRJ~Qg@4s$<4u5ANzEh
z0o5Zhr)0%fU~F~8HW|>xl`HB}V$qU&`LhqHfvIYiF-@UNp&!5B7{&p$>Dwzz2dvPA
zkeLPVT)y6DD6TD`pyQYf9ial9W%2xdD&MHbxo3MM)~SJ7ikL9ChwMR%yaN8g_Xcq(
z32I`&tei*z8mjGGK+{@+liyZ=e61z*@@GN5;ZZf=lllsnl)VhfMgywEs&AT4iu(>e
z2JBEy?@>%^sQu<ds<#yj&@eu-6LI9}g#x4jv?4qLLKq#@FiQ${3?<u~<!Ba!p0`yD
zSmPa&yW7vpW3Z5Of~!R75}~+YOuofyFVsFt!Cpw;k~6oET~J?iNf0gBPxT_J3rqLk
ziNMa8nZ8Mf;))F+C>!=fQm?s~eZB|~2ZPqNIN!WHPbPn|CsT?$!ul-*nUY)iP^=_L
zlLh}+YupZh9YC1>^atJI@uPo!`uCq-K>&LEuX#(u(f;=v1maE#p4k0gTg3pSKnT?!
zLz7{T^8ot)4z*DUjlw{@k&r*dO3Sjnjn(=474PcLieMn9XmD*~2-j!dqf-6vJAByy
zlZ2#oJSXfj?7?JG`oB4(<`#pl_H)7qPvPI78JyKy>=oz{AAI%M#?+*onxlppor)iL
z{O6x0WBSnlyr&c2O6om^XJ-BTWTFfIyCmyqEdj)vsrn4_+lX3!Hf&VwWwnrqY@-%;
zVc6a8iW6>W;2{<2#r~cSq5%7F!~OP4^uu}8jW5B-jwB!jfEb|U@XAjA8P<ss7WKaa
z3%<fv4Uk!gjz7wTJj=m1?!zC<M^p;1f6wKu#sJj>zd%Jv%uO#}Kb-g9=3O29FbAym
zduxvMHL{0He-A*)1pc|3$gv4Y`^x`)s<Qq>4WwzXU$^u*?5$&ePBlLN-!Y9KzGiUZ
zw8;9J^ohsn_O@R5FaEm_0w0(q_c%giXi#HgEa4XWd(;B{W=ZYO6a)^KlC!adUq{sN
zxW}?8Mby5D+tmNhFibEXwlO_FFtpT9C1=gd%CUmxklt&|)uii9%bC5+vtUv=JpNxN
zWZ*5z;lViA=0ldK{`cwhi^}Eyo$=w*BCP)hw)VfTLsB2^`oDJhU~&JoHgaF=|9*o&
zcpi-FzxMye%>VoL|9@#P7XSZ%gF*QJkeT_of+Tm!0CzlRXaaAMiLBFJ`_%a4gpttA
zH4_Pb8R=iIXjV)eF-3g#TSC3V&TxoR+hl_H%Sw6{Mv0tZ+qEIy`1$@i-YlE^bQAIx
zr^C5LcoWqWJfzL6bC=XR!0>~awe-%sW+xI{QtYh@S4!*_9*3>LSB+Q%-hUTQwSv85
zwHmx7ax_j=98K4T^ZV!mnCV)bysVUE7qTB$6`N<LblV+WQqf{c(NwSy9S2>*XMBPc
zG}6lZ1XHxNNiJOx{#Cf&XRA!#mwFC~va({CslWW^+-)4StM5-IPNyq2XH&9Mb84xe
z2!#q*Wi2lPoaVOj#mi}wr^PvtU?HQuz;T$c1(2YkNtxW7Bf|R)cu|;G511S-BL{yH
zXU#+Vx395_iSuuIPVVD4_7Tqf{0ldN!m#;R*}}3l=oHSI+<9Iv81*5xouJT7nS2C$
zdfHlCPGNiT*9w|@#NDvrEDjENycedWdWQd=%{krIJpX5W1&Y^*4T>NV?#5xw<5lUt
z8Wx`Ef|3#g)sU>r%;E~dFw{rWoShM_oUdG=^rvQ9Is(kd!nYH5l-zfdNdz;6PA+`H
zz>|%Be16oF5qaDoj~m4Ss%9o1%k#2*4)T!5l-K25u*9oQA2uNw?J$Y##WK>IeRKDA
zREm*u623F%@lk)Y{bf6wBW?GOn)3SV#Z$$|Z3V`-;|p3dxxCj-GkJyFzZYlj_uXoC
z54}F}dmU|Hh#CIYJoKsd29agJx(hW_q<Y*1Qa0a38nb*9z|(w4m^e8_6a#f_V2GK(
zxx1@6Cr*yG{QBncLm!CQ-=&FE;-7_mM|{yeo+`;TGTJhTu)$4a4m*X3(r}Dlq4KkD
zm5o?Ovr<BEMsuo&_jX^?%-rSZNHBopHl)^a)S@D<^)|4wA8T8}zZ<++#5>??-zP;H
z1T3WJiK&j!MGg5WGZ=4IMwA`D)*4}A&%?LEog=ls_720$dN!eFK_i4y(if7`<pK{g
z0aa~B-Y%@1fo{%zc7@F+>q()n*)^|xH<`zzb6a64Ut>v$ds>T|F!Fe#JP=l;R-$vX
zaixi$_-bgM9y~JUIZE91XenwzD`x@kP2zfjbo5L#fl6pmP4VH4LURZRM{Er#aI2=q
zBG0*vt!hNcrOpOy2C0+~Ak|nQYS&w>Txrstmw5g#^j=;e!Zb@YwSvZh%y@WxG1bcd
zY=%^Z^H$@X@u9)$!qsXnE-Cr!?{dCiM3D>HSxNAUTTc;7{*D^PW<STudpp8BIjJBc
zZtgh8gOx(ASvQ)U-?y1CiJ;>EhT`3Fi>TMHHS<Z&_=qmD_OyJ>g@kHLc@1<Po?`b%
z{m}B7u`w9F^`k5UCaM`$!-PA!$vF*`8p&Spp@}5iSs%J~W^GG}a*oYa52@z9uE*W|
zTp>V;n6LYjw-i@l9~Ox>2b<>hXm0mP8X9$>_Zl#7rk~swBg~FpUI}{RaoFW3A35{y
z6Xp*D(1KY%wHMeLb|`m&RmmkK5huPr<L@G!KK4sJyH0Ghho(3#o%|BQqJ}L9=ah$_
z_C@5{4nM1+ahkK^d!$2q6>Gha=hTue-LAZCa3mL$<IVGX*^<N6j31piDWBirVP=2X
zvcJpIt<7FGghYIk3Ut^WHL_f0D)zZ!hli;lFt#C?LaM6}f22uZHQ|4f+`kdK+=Z5A
zW4RY%YUfo{#O~vrzEE=b(!_`LA%P0`*7sh4N);*4QhQx~r`L`c6QWbh42Jc7&Pbai
zMEtqrqvkDIe6aNXX`*s(@u!dUVL3c4(ty%QC0n39+5t&>hf9ZbO%WxHgqG$z3+oi=
zh{)GqJ;pR-!Q>5=Hi)+(Ehfv<(la`@<(!t|@vVPP1(_~AdG%r_SIlteh-;_Mc(YL9
znG7e0j96aJu$~SE@kmP6YP{uLbCGL#Iw>!0Df34D&i6H>NGS|T8SB)a65IdnBK^s~
z=W4r-9%8?4A9+8JVE02KxTL}42?3!T8Msx##2>q6=;m~)<2&h9w*JRBT#zD-w;0oR
zBDMLs)>`}frm6wtGwOq}@j1En97W|vN*fhPBu~=HXKQlZh!RFioBO=XrF+g!GgHHr
z%l`&-q2JHAxLw@&?~g4@4)woCCyASy)yQo0d+)w7k%i}cjB)LBxRj%QUPX=fR*|BC
z!-c1K#A`n*g{$S|%!n!igsS5VB{a0g)S^l;O7_qel4j(2dcxRzG__<F_Shqo*N&t(
z5M4^S{=e&;aB26{X+IBDK|(-@-rJpmn}p#HL4sN!Lq~XP)ZI$0T*hV^=R0@z=QG3I
zuOq@zC8zQ^bhuv`Jks%qmyS`OXlUud2`&jHyI=p473k>Yq**M>Qf!xIc5NGIUBQfy
zl%HR@b?K`HkZ3kGt9sq`LA9|f>I@dT-*_B_TTjw9E*QqsT!VCHx13Pg>V@dBZO@+|
zzb$?JgyZrwskD49Dbsq{Bl6(h<Oz_u{A7LSxO<X1Td00fMbB=fuPt$Z5^g<;uRS3+
z3xZgMp-~g1SL>=P>#01^lNuE&UBQ2BgC)VeeQc}6RqS!tFzt)9xH!sf`c_*x^5L;7
z;!vMVL8_Oy3}>l4Rq_k(x?%~<apl~^KM;G|qY?6cogB@(hkpvr(;BrC)$%*}WFEX#
zE3&Nm=WPAYA1VuPME`7iX<R+Sug@Y!2*x>=M@yA87jpR8M$0EeEw@7pSf7o@hnOzi
z^nOZlHq&CM<jZ_%BKxRz-*ToVRMK#0u7$E>;oR{d>47NPjR<1&W1;P=6W56;TS`$p
zb+&m|Y_UA%lUaE^P?|J(6)BNi@F!I&o0c5JJk7RFo``L6C;<zIm47q?hC@xTqUbp6
z5hF@|C9OjC!x+2<7T0!1NywS3;N_&S7Ljj19b<|YEKHNlRP&zPE<rqISM#rNK+F+<
zDa6Io_uFv64_unMrm%4Luy2E8sDaCxQIdyIKF^8r&$vQZ;6O6M;(IG%Jir5EV8W6K
zD?Ox?Px|*T_+JJUOkA3b{TVuMgUWQ0@o)|ci<}nQ!%Uk;=YFiqirGw3TVOH^-Y~?|
zY7Y6Eixfdb0u??`sAw4((y2zRAAckS9T<BNFgX=HK3v#6xtR3Tl)ZmL0FTggW`~)Z
z3cH@{VcP`FyZTdZ16Gv8f-Sdnj_xI1YXqHQ{X>t65Ij8W=G|^1d>?Jqmv-q1Tdpvc
z2-!(JMze^9mXyA?%hAniWG=cZ`7EcZj?-h?kCU`P{--}}RD7cu0x3Mnli%(6Jv1W?
zd$5B`h}_*95EOy^r)fz{C`wDqHI}?^k?sBA-_ZDVzWF9YDtS-wEl!Dz|Jm5Yv+0}r
zE9~YC99PV6cm<kz4%Tne_cu<t4nM!cXs-OzanM6orG@DWkAh`k7T<XP483RKwFmp7
za+0(fBNG>g#1kv`zkCS-1AD=rhxRgXfk4cBB!$Gk^ZfaG*7S5yg1T)&d{Ci+*&c!Y
zOP%e?*48_{Z7^{!A)-S33L>rGeb{E!h?Ll<6l0i^F+OjWJUs%@h!Q8h+ovxZ{=Lzt
zCu$0xw?w505-0q}iW=rSgFn%3AeZDAA=_$5*R1bM%BX4I97NpR#7Y;a*g`cQvh0Ga
zO6Kflw*bs1m&nuIdcwk)WT9a-iuD!OJBMMr=)CTs%SRy|Ohd8cU)7)UFWI=&h9!%d
z8F0~)_WikYC2IX&VZ=u$mA(?4GH&J{ii6T#=d0Laq2Myn3ic_8PMipHs6xEab6!iQ
zaM6yvc>+<&H!p3>vs5P^NRX#eZMeUKDp0U!DTfdyu3w)XYUJWORrgoKcxtCgN1x{2
zug7`*YQw!4`g^(TZnt1{<B}~?*OIgyb~Pf{HnA#o)#mD}D#!OZ(KUXqEVZKOIq#m;
zLCSKzXJl7wsl*h@^jh_%b&0IB3YIpMSoXa-r!xf`z8i6qSkG{l{jqz&b=MzX$QO@y
zNJ$6Lkz_)VF12jPyB~K;ZGhd`YPs{;5xr%p*7Rb!a~)zI<4}46x!bU9uh;^(lwSFf
z)yTV3p|gQnryC?yjqw%2sYI;_$v^42f&!bI9BE3dscXNXpqMe~u}L1H4m{qWD7elL
zBiTNRG!)&9$QhX5c<Qa~k1yT(Z*IeP)T3=X9P*z*`WYGLGD7i<F;O^Lwj@Sa3T4U)
zR1`f<9fb{IzE(IZdA(cX_-AZnUIgrzu6Mt%oMXyXsiNror9cDE!n2$qPkw`EdxGq}
z%k&TUVr|NkPmi*gjoR+7{M$}EWqH9>A@!hHn!Ej!I_#16l!0T7sGXf;OOIPhdSv9=
z{72!UY9FGNs+bLURPT<c|D6VULtHtpm8O!$gA6tG3M79Ec)zd&J$TCnj{HKWuzsY=
z6&hH`b3%ZYI2hojEI;SX<lVoG*E6!|E9dW=!pAV4#OmFx4P422L9UcZ^(f6fha^7W
z-rff)7PjQPMDzN=Rz;-fw!1ZpTefJj#IJWUzbY0X{d4i6$4YHu-KdofRu^3ZJcV;i
zY-BIS^W~d?OJOZ3yA$A-FKtN|Y^-6W#$<B%p&=GdkTfQcAj!}s_W+;lzA^iDS~{Pq
z@z&r-z%6s#)#G<lOLJLaaP*_LXd6xWn)Ox}jr#SO1kOXkG1Qr={zF7ku=VWB?ie`y
zadD_aEZmySb_$8L67-EEMkkw;WC?bzKZ1(;w|rR(%I-iab3OaGWL#ZqA=BByW{yqy
zqy6f3(jD~v;)_(0_*A`s&Y9U_ZaoNx=ykEG$vL#92?SHDtQ%B-$4_G-=ouZ9=(xDl
zpevH#(C7-@rH-fUqh0^~bmr`512voVzdOjPYH~6qa3j<@^#ft7DEXP(#rq50hTq1r
z?P)>OrVsX@*6aU+s<(iOLhHhY2Nh8Sy-G>RMM0zlNofR;?(XhVIt2p|kdO}PuA!S5
zP(->Jh7d-YVF-yK27&L4-uM5%@2sT@moul&-p_vaa}M9n*Q6-p$Vm<T=E{VzYYelT
z{Z4I`E^ibV0fShao=um^-egOf`Z<}%3`;AFDnO&(C;6wdCvk|m=bAPLEHxBzP#PyH
z^h-=M<*Rx06Wjb<{kB+pKbpHKiT1dldyMkNbMi8l=OWyd+V5!74%*LuQ^HP_FY|DX
zzxCKbaJKB<sGJ;ZopmsxuM)uf$%(<Yw1{Sn6G3~~8Zqr+0D=0wl<0-)WT--g69?aG
zKf038ACl1fTnqd#9L6Vz%xAgfGWyNO9oAn_I!-l4lQD2ggYnBe6cc(d`|v+*R_8mn
zF`=~A^#0o<Oxfk{1`RnZrK%T0^?rj<^!?E=7uj0z{Z^zs=nsD}iJsvlJaL;XT%)3P
zR7Au-C9u{?Kl_{&dOG$_8%hFUdysqs-Lo(l@ht*G$83oli3$WVmW0jGIZh8bW~(=h
zZ4epsL+i8>@ZyW(oQ(d4&!WEv-o8HW(2D{AJibKrxRX*u0^^YAq}VV%bvl7M$BECq
zKHCF0y1_L9b9rYb7j;${R;EW$b@*peq8>=c*a&REDr6B>$Bx~HN;!)0D!F}$1d=O0
zac<MGZqsWqS6Rs?k<LwP@}|xEZNRGI1b6OD94fye<d6=DV+S{fuiZ^c8N%4cD5LjH
zMG8C`e$%u3U9jXPXvyd&9p^{;$FU{oZ;_b`e7S<{4ZovDy?@L<=;v8}>hUk(V|`Oq
z9|B03O3%wa;chk?O6%}+A&8!%)9fD)mM3e2n5K!d>hTmyEws8DszGf?HtxGZtO8T~
z%W0CDIh5)*IJ1%OG1T1^MllZ?w$QE_P~A*K86&t0%sLX5e*L)G^gf#qk_~;Kc%4F2
zQysOm)Ylq?vSEPGe8TwBWc4`)u$h9_Vem!r-M*+a^Q^|B<#u-)p*gO}QnEFT78^%j
z<GipJHEiV9^&wmnQ(+_o5FOZf$W5_?=}kwcNz#qhUSl@D|DRS>WT!aW5jql;F3?z#
z@IRjv>okx{4v1-VRz<a)=8DoNU*?hmc3Mprn$I=#qdbf^-J0umc8X^%ZfsN8Pn1`!
zb@A^U0?;%0?Rn%*p5*G91smmCZD{fNkjcRMqTb}u@wAnCSoE-N^?ftv#r1z6l5-jC
zb?75mRDPpC)<jwE17d3E5cw>^-WoyE<5-?B5?Jz#z6aZ{ZkZMHANGM1f4o5@3^0<G
zzrSDatAe-!GL}<ok*JH`LT1#&gl9Wlf~37QQ?0k!$N_KOQOdpZ{2*xcaGloOpGiKm
z&GrFBsA%VYhVa$@dMg>{1{6bdQ-x(v8clEH+qchT8!UT0Nr9m@QccTp90SlRE!{b8
z^2>|%5D$6HS{dW|F4VEr%;ba;yp*57@%Eo)7R8TLLo-G8qGJC?T$>RRhXiN7_Io$<
z!r#gOYSbMo+Dp<D=lCf3R$l{GP`PKGysh)x*+`R1dya8o^+B!oaQr=SzKT)Sx0D@<
z|2HQ+Qe}ixdq`I5O<neOO&)d9`@y9hF75hSIfet1*hvX8@_+$4Kcrn-emW0a(<JX7
zpppKcr^b&H^PJmkW2=3t%oGkYtO$?QNR3lyC^}4vt?@O)8*Pk48;ER5yg?ER&y`oX
z@O8gy@l<VfX=zaYR8^A4LUr)#3w4z0_#uhj4vDWr_1?y<LWIK#zqO!!Il1nPb<uxe
z4UI076Du8GB9}0LQp%r#6{5?G=0A0_@x0UrL>NSm3Pi_&heuu*(nc@VyWGt3(HQh`
zYX0lB;hUHrFAIk#E)^HSs$T`xxo1IRqFL>l`uqvbL}B`-Db3nN`}EkyxBf0$aYVou
zb@;CUWJHKZNi+iD7^c4i;9YS;LsIPdY_~T?xf1RB*osj;$$q_so)d>rHK|lSs|IK!
zJJaPuG@9#ldvvh+HX*5Q9QhL`80)JSL5K@W(kt<vP<$YSFI8!J&W5O?5<e=CMB=|2
z>Vchne}0VG8RMFp;T-2Pd1a*QujlX8;NaGfoipkbRdz*<D`{aPX{t(m`qbU|`e6HF
z3MG4G*;jXAO(*0>vcw|Y*9-)caW8wc6h(`{-@Utbm;ZWdNJ8)3wk26noy!ou{OHNp
zb7WAf4AM#Ym_~xvbb{#O=PP=#W)LhxCej&IU7f`XB+xKZ<<-5df4aAt&iB{p{rFm|
zuObK#=6A<H%!%C=bRC(DQtqRo6Z2#%;R-ta{LqH@|C>8K-gV#&?Bqfj1J~!?`K{67
z0*1q7IO-q1^)tIjP!JG$p8aX-+AzBPV6JFLatL|cq(3pg-n4BrRS;*Z-7K8F2beF{
z^FEui6EM-ZGD8HCV)Xlbipvi~q2Q0n3hC}uej!DCw2CjkI*ncf&cRWY&jO8eH0aN4
zbo8$^xbuZg>xvowG%dAm5V!W^=Xps5q--~y&kzHlo8eId#`3~1Y_Yl{@_c|h-<dZ3
zARIMQ!g*Pl=PCVvhCq)J96U*BVuQl3IeT303)!swR*Bc`JTku2DJ3GCzw?NC>ZP)2
zU(pJ)rpEp9Z$t;3?~*!1n~KZ%oMP#5d$ulPWv=W0I{kM{INsq6E+dE*RWenR#dZ!t
z>f)$di75#5l)o!p7h-eepH3>dE@Dy;5!}a1D!p@In~rrw)oODpzUO#6%`=kUetag@
z;>WH2ZsYI3gX<$fjXxt~NDS$9bewfm2s%r=h2ofy`v+TDB>n7`oh?g#xFOgB1wplu
zuRNrr02dDl9-yUxvobVAmdy`+P-<Ye%n<pE8GTvZTrRXm>@1vysnC#-Tp@fHI=??j
zYVGN>vGs9%t8%BzLi=y49WzvV`1!6Jh$~9B$irbLi|SaLvU6?Ga&XxoiALSL0^Clh
zm^))$N%Py5*-rTPR%nsz&A}c{mW=8?7}gVpn`)oW89Y-Su74Y}>ZFi$Hg;XCDyS6R
zMd0ZHZ@QZ{MQ89!Y>i>9QhR9WklIm}$qHS{xnde~wCz+O#s9Y#l1o43pFqrHNPKa+
zTVYrRVFt~3{eW$Z;P>wbxZ_yyCw^hk%l;dB3-^&&hBR)gV&>Zu%T75F6o{d8)7d<U
zlPyQY<nKkVU0qk@b*|SzG2(lvEcH9RslwVs6Ui*nzWUaK_B9IHrB{n@cE%FRG?qtG
z#(|JiyYw0)IB}0WJYixcE}r5gz()KMNT%5weJ;?kVBF8~YmjUw#?DFl-CA5lbhjya
zO)TZ*yYF)J&*V|Vbx%^tF(Kc*L^EiIj_+j+&eEg~XjkXXe30Qdn@PWV5XJyswFbxp
zun)M+ovlf*N`{A*=tdsdY!&ZRL-Tz_G+-9NY(2|#^r8Z~lXPIEf0B8KUV@b03th19
z3>BL5o3)=iF0F0Z{qF9E7_{{qFB@X})Prml#ZMcCoShvKT=QH>_QJcH45xGv=urEZ
zL1BtIb1YeKt_1l#%t3E1ayq)K_1s?R<ZbPy-f;XjuIQDudw-1aAUKn!^Ud->hohJY
z6zt&so}{W)*4eSk*#<3<gBE>Ni)h09{n>pa!eUHi-6yBDkAfi4S_HcN8(mB+b3xBG
zbj#Kg1@C3kA%sZ!g6JMZ4TSZ4Yvff%)S=|WGaG3Ak$EvH@+ivW3-AsfAU(|S*umP@
z6?6Mcr+X<Py`Q1-$v;XPG5*^~&rjhrT8D0#EP<HJ+kt0cREdM8;*twZnXiBUY&ypU
zWkJn75!JvBi2s6e5?}poyqIo5aCVBCDtvSALge(#i&sxkd6h%+*>Q~rJBmZ3XhmMZ
zjZ`UF02|pl_w#S$>8}J_xyhB9%EgvZ53nHwa;`@pODj0Io|HcPh&*7$QQzNRL2%y3
zq{5k+I`qQw0sfHxR3O{{S#`6mYv~R12sfo?ofkt>^JXtx6+R<0PcqqbynMUj%7z2C
z@&RPd^KOHyW;mM<7Dcd4XMz<6#uTty`P)Gr8nrhZgIFdqGX^&{t|jvq!I<-Dq4tQL
zZ!;1CgpXu<YY!TE1?`8z*E2X-CR|pQ`_$&^$@!h+GaqI&!NnV8y^Fkh_CNY1lOzms
z@EW+L#gUj`z~1Ch(w%Kkap*q0PQ7}EfLMBCT@I}+m@%I7&XA9nw$k_$e%2@X@wsbM
zOGRDF+tixXyL%qa`EbsjS|QmZG2xQad(OXg*24?4IcnPoYl5xW?ky!jFq+><(d@N?
z>$LmG60TUCp?bchZxdv4{oEwVQ?FKxgSsOjWuwgtAIJ0oG{~;pwdJx&7#bM`SkKg%
zQ{Q<`n3er!CA%hv&d5-iZ2d)t*EBQDG2Xfti;MdL-3PnxWQ3OoRkD45OrMa%XVx;A
zHYV%6hM|}Qs%!!pWdJpms+IG+YKcuGsT3+`*c$$+u~ReeoJ1_xpGgJCA-lgL7MGru
z*W(>&`{{hF!r|Ur@oF4%AbNH!FbWuD0}}bUIr$K&l|ZPy%JRh6=L!{d{AB#P<77$*
zITo<)_N*BxF|_D}uRYByk>yD*)uS+3AKCTIVCdaQtGJGGkIqop=;;l?Z|<^pjH<M6
zSp)MOvs^w#mv*r|I&$h+b+vVwv`me1sQd5+Agtrvs<fqNu%j(nM4aAcz_QqE$Q(Ci
z%rr>GY}_!FsEA+F#B$z+K%|MU7|SctQST8e^(R{M&m_`;UUfLg00{Ln{ed*fa7tfi
zWKpYH`lzr$r<$#8WZCH%QC229yWOju2V{M#eY2cbA&%;0+9S5O9fb1e6YAl|^WO&I
zgfHonhOQobTJT<f2`?Jb)-mBR9$RboQ;?Vw%$d`ze?(Wa{1i$;4Tz)KeVHu@;j&NR
zM)>eTGBZDb@zF4^)!p+>$_9G1YB@nXc?GF|hKKG+kzG0<>32tbwtS6FQJ>3brSzAS
zi7##Y#1Hav6-G!^gb`WhWYFgMNu(4d7oK?-4?Nm%*Q}fz=1pJmiK<sy^2@v_QJdX4
zJo4pQ#|#<qbi|8D9%a>LC%F)ds!e~Ba>h))C-b?^hTRl5XW>PI1AMHB5jxe}_&)gD
z!~1J(>QKhK1)Azgmrk<tVdg_od#gD50SHYpqbl-!5f(+XJz6;On>`fxRLacpqSI}p
zsq$Q*>#!-i><dzMLP%SJy&v8dfn;;U^9UYNR?}<ii(M+D#_O?`f;x|G4l5QsP$;k<
z4vUAceT;7SlVSUV$cLB4i6Ge=ODgdX6#!|I#ntc#JvN$~bkEP?1@FF$sU=smwdeYA
z08rfr<HA#!1M5z20}$7H@M_XOJ#k#Nl|en|kv87BE24L@#<9pOT|>hcqjvHOa`K#<
zLR&NZxgdh5^!6=&sOr`yIyX}D^yY0aY{@Nr+?rsWKT#fZ(A@7m6TMMZE7-F?b=ydh
zWvJkQ%2Yf@%LXmbT6;q#@KBM(!{w=FULPd;P~a++hoe(|xe%w#GuMw<Pz@PK@CryI
zlhWFFZb8in-*K6W3M%W)HmcZR8m@;(oyR0~%)||c_1$$&5c;DigObRG0Y%cHZzw#z
zO()|`Ik0+0&N?QA3u4|+Kd_dp8_-mzW0T`6C(%;=V*SR+bjb0>AfDXR=G@oVsLL%j
zhEijTPZ&cPg`fuqC4_<d+vZ|kK1ur(1blTm?3Kal=Qoj12qPb)n5f^aKCt_JgEPJE
zzb{W7Tq7MHhnC4ACgTvJMFORI%eQs&Qd68JJ3{pd%U5D@l?uKp6ruC4fwMx%O$W9*
zHd1-5{z+YSwT9F!TS2rBT(O}W{u1JND@%$1V%`7r*%@M@%v05&)k~IzT!4;3OtFxK
zP|0xIEB>a<DW40=hVe$r%G1nke-Di#2?16Rs5eIvko5Cer9=j)bX@B215u#0f8nL?
zdy#xxeD<dj4{t!!gyxJ{olydh`@0ug?3*_jQZ$9h5aDDnkmj!kDY^1UDq;SoPn(yY
zb~hXh>=IBAdw_*B<3B}ATH<cepCYJx#E<H4wS*n$YBp}9@3(5-cOo#0!ZSvCw{^#=
z0~(`OS~14NNk4t#oF%e~UmB^hxmMhUOx7)ENX4vO^)TGb-4Sy4dVW;Ys15RD9V<>#
zPq)~uUWJ?c%+%Q{u&5s1VRGS)c1BNC6BLZ!#$tzA?>z2(rIe_U^mQSQ37o8r-_4H)
z2bjK@0u4o3JS#f+j_pBKD}&ZLGd;_a%`=7_KRtp@1Zr@;!%`9ANDR&&D5UI5p$Bp{
z@h;J%{d>(<_9bn~UMPB4gEaYvt_bVl@b}Ktp)A9^rE0e~Kw}vq$O6D_625CNLMAvH
z5)(ShYlt%>EY+M+K!Oo$Hc1Dx&a&9^2I)U3@F(<VUTc;c*Om_i#|7CjR~?O*A>}0h
zwc8(`lTVu<s@XCiosmpT-9U2KbxG2gJW^-cU7<l<F!HJ{$5ky3@r%2)T5K1dz`;1|
zpz0)YZh6sZOjRY*QSmC`)K1CvMA4DFjchw^6+~6I+b8%ieq@Al^TTf$4oc>^4|LV+
zG>{E*k9=d3RC?kU-81Vp!1q`69b6g11;@m8-GCKg?YBsj@tMhDx<5iN(mp<t`fu+x
zcA`rgd2{s=<{)}mH`o05ZDj+Z27L+Wdv5mZ9v5GMV7d7-)P%|Q#Nc`)4jy&&5fq?i
zGiH38x>;Mh%*?4{qAU9l#4r#oO8mit@MWuwOjNezsP4S(zv?`DR~P<s9X&38HYo8K
zu|T$8hy32c<HB;VGEIwZojWBrwqS``qxSo^UgoIas-qq~<Y$P{aDw3r*&D-&bm`n6
zA=TkP#((Br<CBx3U;2_6qDKFRzM&cEmUx-?dS6$7_0H?p3+CA@r7+#b4YDkeQldju
zM741CAzZxOkjzVJ$5EnO`HQdoSUH(?q`umS2fwAPr?*?!x%ulDg?l%=AZlEhjy<pX
zt{L>iVqQ9dFrvf3oeB9sS3@YPD$+!<dv6ZGb{)d@M}#OzaW}3!_(8whN^__}gLZsv
z=Tdd>yk~buzZ7Nifyetl$wqWJ2nW|zp4K&V;C}ifZ7Vw?&Yjv@E>p{E^j$COWn=wU
z_J)fVSwYheVdQlP#<=?6qShN_?v=3uI|?e>6!t$nD4nlxXtw137F_b?J&oMY!8g)!
zZ(bG)F~<JWz5rp&XONP+`DR({`kVJ=Qg6e*T>atf)E^g#D~`%XJ0I2borc9mmGk&V
z*$ijG)=rxrn<k6xi_SDIj}FW@o@Jg2@bi*s`ui8=VpEl#Pa9b;<$!godKsNK<LPRX
z=%PYb<}<t<P<fMFq*Rw2GVtKfhS?ve5#=-#C^?7Qccn$JB|9lAG4Z|3*DbKXs`Lp8
zPUB#xsd6ODBh~42F(+EtF%7$-YFwszjuj8wKP|duXx977+HNMwekMxn^h>iR4<SS=
zd?!^{bfgRpr<TbpP=s<ObJC0dVDBzzyNuu9l%Xu>H=BKu&mud!8r)H}mpksi01h2u
zb}zNC(s`Ds-s0rF(*86=+R*<6Jw3G;+_Ao<Sx(#J6ggj`Q`ru3(2j>g)ZtAPF=sOr
zG<1FF9I<%q5)en5J>F}sx)<>B9dyb=!Ffw)no%~>vM<?cI#U#>B}|VvKRZkNEH}|&
z1Ug~#e2inV<qD*j=I<mhk-OD{z(?nCR;+pEEc4gciTO;#q%#ZlTRgi~PuLo^p0j_1
zmW@RJGa~L9+BT>Vh$kQrJ&!ST@jVpGVAn^zVXN13*rTF~Lp9TuE%`>7)?xzyw;dJ&
zdMc&MhQzckG8iI-kE8@@5<aqkDB-^Kb)m*<^RAZZ&VVmtr0vPZR)&tIrh2Pa#pHle
zz`RMjkV{z+?{UDMC%X_K_yQ$McXfioAPT(74E{0spxIj3z-hd2{kYt*JEQ4!iheCb
zo1o*j*#~COsx=RZsbOQLhUrBD$#}YFpu4+?i1$5RKAp@)8U<_B6AQp`y`E9BId=e+
z;mZ(>R~mMDG~FYA;&rd*yOn%#p@7;Keabhqs3At;!g%?IQK4L2z(cFsW~w#JMbXi9
zDj97Dw1WyO#L#>5yd_kq5$)Z3NGvultb26@iw{vijJk$<<q~q<-K&e{@0FgpL;s0H
znx%hmqrNtRI{J{@&qLQQ<B&plg{Y+!2#4@U6Y`UXIgPlcVp>H1H=neIqoPTX%8)5N
z>UdsW%+<El;&xds)}KfNHyR_m_V+Fl_)3vaTy(+=HhD>KqJ<oiqWkeCXue4)(@?)^
zp_$J6wI*)7q=vYw?=r(m4NEt6t^R*>DTIa|Z_b1J6BN2Z+Tqd`NChof_WD-jZTjq;
z^}QpDUh98g`*$n={QUdJLOqVhqzS*ueK3+aI!ZaH)V)?8{otK`lnOb!NxSR66<RH#
zmH!b3z?iRRUN<nJXBeyW5G@s~-$o>@r*J%&`uqwsTF`e?AjQarsth3iu$1C<xxDh5
zR%t%h>$49vLbj9jMKAVnvq3`llas(U`dhA8WSu2@*Gm*qu|zAxh4u~Na0dc`zKae*
zd@%5dlteDmJ<{G{?xvqv`odXHh)~IJ?~4y#88sP>SFjH9@2w0%iDgt9ta}<r6Z<l6
z()X{sn~G;I?0yx6|4k->N)$VJpWRR#_NrRHQGkU*!}!tP4qSN+mmOcL8iM8FOY>kW
ztg&RH%Y?C~aM?ekh!-5D=VU4YdVwerm5s1lF%GBSDP<lcsYER&ewcNzziAI-ZAG_=
zfC6RzeCEG_KsX2wyTr|V$GiP^)J-2%1buGN&~$NP#DErx*~iCUWr)ueYL|Vt9vDO1
z&xpW$3m+<-<b7g17V}zE2Z8)wEoQ7O%SN#u7S`u7V$jlaxB7T&Br>i8lc#k8&v{3L
z^Z4xp<VA{b+nyt(W+>}0@A7Hr=bDn;U7M|Wm_oEAqQ&ZeRdEwhZQ1Q^UQ(@8+#U}q
z6hJR*)`S#;y0RZrL@<h-EE8wk-BeTL;p+UQ%@IOgLl10~lR$27$;0ON9RI7N*s%60
zCsQwvD69!x{Q5H{*)&9d5&UP=*CSG8RepQF(vrynNb#l4UkFR<I*!jtESk~<4@pG^
z>mUE8Rqwb|`pAwkgZhC5E>72Z+39~;0K>sQ2i5FT#NFumnZx|ok9{Qrb3O*hORu~?
zxAseiXUvqpm2IRkgHJW&_)H}2oc2)}3q_k^;{Nt6Q(b-JYkZF73T1O{IzEC3F6b68
zI%{m0^K(UZ5>wCfGPu_6;b58m<orfwOA|MJ+iWjAo}I+X!_XA{^`3zm(HP9n>N@z|
zpr!DWgm~3?uu`CKT%sW4<Z+R^NSs&O!W#*Q*{FRzv7dAQ`MwmTt$t|Pk+)cJvHqll
zs;lly)I_#I_LH_nLNVMo|Hk4*UbZEc<^o!;I?O7j^<Y;bNa1KFt=Rbuz8(l9Za{%j
zOnn_8C#3#g)#~Bt%z<rdE`d#$FE>Ith9Xj}VMY751FQC*@uwCLmj7c%l4NbS74dKm
z2d~(`_z3{YJe09wGZNDnWF0S1VV`6_BJ}s{Pw2=zi&UIb!>3h)Usx&lxnoRVH78YH
z!JBEgs)cn<XH|4!uQY<|rrp1xj4&*M{h(f=`I#6!)y}nAXX(iEb6zAmk!$ml^__-4
zy@k|ks*f!Cl+@37;%E0;>|%8s?zE`RYwH6JS40t+%#@i5(R;pVqt4|h&cQDE>ql&*
zE<c0D4-VaGp6u$j#X^(7<#tys+u2P^Z$IJtxaEtfQjB*Um!$RI`l)P&8~$C9@$j}m
zNKJs*Pl8Bmn4%H{oai)agt$6m15j$h^yBk^XEe0ReMj;}kYcgfUkLlP%R7qTC5wR?
zH<MywZGxySK9aMq?8#-!>L;k=hNP<bg9vLsyW#f%?GgW}A&kB;ix?yXDw<}rXdKz-
za;XV{Q!rZZonLR+eZ8J(e|W%Dki@jtN=2kn6xz_><b2~waMnwJ0W!|spSfGZV)x#2
z1V`Krt#fz(^*AjZ`H+ItP`enwFHp?9hCS-;KJt{K*1VmU{{e0PH5}cLI@lu7su68E
z`W}Rs!I3qbs%K~MGc_v-U(MIvI_8enKw*c)Aor9S8alJ=3tn+i6A=<DXUIo7I9hRx
z9LIv6Mh7ol%hrPa-a+a|W5R9zTFh)6V0?cgzG2z?l5z{nVvSbXVim-Tq=A1F<qoJY
z;x8Q3{hVZNiZfT>GZ-6USM8}0Bh6gTXMP%-_R4x4rK!74ztxIx&=!!&-!#OT+bAcp
zU#1CLJN2_WdT(;Ncy23fti4!WR0Je`2=>3X(th5_wAcRRF6|bmsV|ssFR0K1mTDl~
zr!GH=Hq4e(|FiWpRG^#zc={ZW=Itn$-phxqt!kP)Cq!iig5N3@x1(s<8mKm2qS58g
zBP5Gz!DvyG{XJ_<eA^HpzAMFS^gXg767i&QWh*UUE>e1EP*4gcR-cPQu;WozIc*&K
z3$9DgJ}Ofta<w>=y*yigu1=<zNQ8gn;PH^Irlvf*Zgg2KJLl{HA3r_vr&-v;qC0!k
z_5fl$ev1b+#lq~%axbc={|(i8MMMHAPNEjfExIA*XTF&7QD4~bn5T{%Rr$GpmgC=R
z<2+VZQ)t1vUwk&;ApNv3i1P&+t>VMO0bT}2l~n{HV+>xDj9xDB%4n7bZuI5jXafQ;
zgnsJ>dzUgVy`onPF)CJ|Ads{UpvHYY_M~BBu`%{<`BBcLYEp4OPdZpqg>;Qy+}JlP
z!m`LMO(C&N4{Q-V;@r`=23HARm7c|Ny}I%(5tY(b5t$A$fKg%*4TsK+lPzGojZ6`D
zRr&eZkVom9t6BLK%3r=L=4R}c195O1kYE24(B86D4z@*&tNjmqjlRg9eNyFCb+K5(
z0@bKCIig7V#c#C#C{6EbKl1Y%^~@liPCjoo<?zKVQytoy{rXLGAIxVWH<Ra)5@yCR
zhHW~obsf=a?F(SsCq~n8Ugf<&=sp3YqxPu-nA6fB)^wnJQ+HH^E{c&YT~AanDg_5r
zb!=X$Q9J-gVL+k4Y9ZX`V=fQBW1~-qnhdun+w-V_tZqi1h9X93CjC(jD&Z+0Q@4C#
z`yHDS%811Bi)&9LxBDsqn;FaCbe|e*Yu>bYA!n4Ig0ga#K60i3uq&b3k3u{aebz2%
z0f4+g=zWO*a^wEJ+B#onjV(^|47wro&)ttk$s)^&;nw~H-Y+$-bS%aleVs8~US(4w
zZGKzE6}VKqJ<AWpG&Yts_v++$tj;jf2=He-#^lVA(cB%FY#J+IvB=Qk*(-Lkl;R0E
ziRgKiuI-`At~t+!vYnuXWWzZO#S03b=PY8Aw(Pgk)JbnP^dGIa0N*<FFJ6$s*3WnF
z)lmey;O#O|dfvp*uhzVY$Mm?!i=Eg*dU<5abB@>m0Xn<D$3Oi5Rey2FAnz!F42yg*
zMWe3!8|7KpIIQnGeOQ-!n4Ko2>cDaIu=#bl4)Z0*KYE6azkb??nrJXBm#Q)0RU<<`
zOF<Rdf+mQZ3+#EtOpAEQ^B+1K7Obh)(AL8{qebFP$}r<mgX9l{JWo>9#7*^ma@9!e
z19F=|iUDkK4TJkf=pV6N%}(wHoS*zDq5pz+mEP<S?PQ}*$LJcs=Dvy#X4EJ^s+M^e
zGszHW)rxB!mRPX43oMKQ_9SL!BFVECJPH?*lopN|$uVh;_U!eHwzNmhTlcNtbD0n|
z_J&Uy-)Pc2jX6Bz3O^YJM*wWcV7c^VN4jAA3B`?%{lFj$*UU`9w<ZlhKG%+;!Fj!+
z(j;d%z%G3zF8Q_IJd%D~S=ZaajJu3X`bW022X9GJVPTrpG~B3L2l|f=8@+bPU5)Cy
zW8Zvg54Vk>pFSlCWpIP0JAQu%xyfe3knWkmShDQZyDMB~0*=*wjv7fx8GC`;w-P%T
z2=1!dO-so0YQX1fHx0mT8#_^2U49G_RijhgQy@b1xxPjMdJAs(?%oV<NsasN<hSA=
zxUHQNM@e|NO^6gUz?4lSNveUp^FW(Te@~3Y1++Y2@QtRz$9Y1$psltf0s#V~pwBf0
zZq0kL53G?|(68#nz<Z#7%3p<;&CmI0hb3XJD4w_)&6U%q8<c9@rlcL_)#8|8OLRKP
z%+cu8ss87_6{xjJ?)^aDJIV%dQB(m;qG>22bs@t`-4QI_rS0-vhH&q+%-nx-q*s^|
zt)l{t2m})O##vdnZIVY*yZj0y_(YpSzb`+JqLOP_x^Lwj3Xf2uqJWt+n<tH0Ss^09
zwL&XDg-dx7<Bhc16X|FYZGlFUIHv~>!fywIn*$59!d`8f(Y&WUhA2Ug4Xsw<KheoB
zp2Ozex%We?L^JP1(jV+;bcyum_ju)j!ytDbfwvD&l!mqg5G>IY7TuZI|Hig*BPSBN
zE2?=p%->_#PWR_!88C?5>H5czFH9A2CX)ejT&g5?zE3N@XlQunBhja5Y@biQ0|5v4
zwaYwyxR(n3{uUHFCmY^ZS6bQ}fl&etrAXU-)l$!7bM3qdk>osqd*H0nAF`xROsDE_
z7-;0&)o6Aq5mJxE=+Q8^>Ijo1u2I)N2J6is<w;Rjr6iqX-QyY9JU`}tmrAf7XSR0c
z7l;uL0WyTThoU8G{23DzpRS*E9h3ImZh%x>Ys##26Vk){eEH#_B51wC;-9Fe5d!@E
zw??iZ2K<S+oxyyk?K7{qn*%TWbZtqxo)xUfL~6@51F$|7v~hmeNZiES?a^fqdG8+*
z<;MO+$ph%MV)TabRty>-wv3}@0NpO^Q56YPlgSUE>Z6sB7ZnhiA0DN9UY$@3d;Ag<
z57w*h>MeYj-1$LnH@w`Lq@bzI_6MB=%h-%ce2RIm3|qpMVI5ud%O+QC*9u@KiT&6Z
zlsI(wVmx?HrZJR42gM^&pn7mFH|!|v+w0jrvzyZJLKaK(fNS(+v;CXW%fUBVF*)jI
zU(1qoCrTEl(4P-)=2K>~LENpWGw;067vjoy3m&fk%XhA4Q?>2kKKDm(A_@E7nSS*o
z$$Fh%@CXxh-uIB1EXQ4(>U#Q2L$%D(IP;c7ToN)n4<JeXcBFrdi;MXE*`|Y?QJ#Pb
z64kP~A<Uaig~UL|H>FpC_oI}^ft&&H9dTWMwaZq2l^8015fkQ#vLtgD*jbhgjHHP+
zi4)B|@)Ro<Y}iB$4$4vp7}0Yz_AMA(h6ID_>phP87e3iy(w*QQi3L6%4N7pA_2^a3
zv~;I4oFNi@^xCra{=$u{G?M8;6F2Eb3w1?RdX<uq;0(@&7u^S+wokRtmL$?+GrtnH
z6)MM56m@Sv>X(|}z^CK{e9?AvmkaliOKmGdYw5#x%GCA_j_2(Iw-t#FwirnHoy=|)
z+X5MixBvF&sR+YlXwQ3`w0*^ORZPL4?1c5ofu0NXgMMItB*P2aaF?%gz6cdb7`%hm
z<%3O18o4*r<V=ejY^*?vn6?{y@4EF&VkyH_uVVF~Vf#h<QK^<oxlW?)^Y7M#qD%BV
zM$Qq@_O8`s3fcgW5X<PA;*fc`8SkqUQ7L-?z5Bmyg^iYpp*6m;;?y@lm{Ze-E0|<C
zXqgPG@jS;Oh8yWdQfBk<$fb@J`YZ&ju7MKoF=31SEA>A*A3b48>k*5yzV{~X?paQ)
zZxce8faj}OJ6bp0d0Jqss;b@G62gz1`p~`U0f~H%IZ5kH;EylyWQMRIEN!uGphO3I
z%jO}E-S{o2q4U#l#q``I+*uBl<3LV40KBA@Nuvc+KP>nrzkm}8%42JF@u+qS<=U3n
z2X7ARm^)|SjQRx;4r`-EK|hmzfK51e0tb>32!v)%)_)r@%zW#S&C_HfDgmRpA0Ao^
zJI#jjwM~);;L{v<*Y4D%NK^gAxEqLE5`&aNM(xRgMLJu<QNg$`Ze=d2&LnkfttC;y
z#xD5m4!DZ#{6T4b^_x01!M&;<6CP5AmJj}jc{%d`MH1L@_R%W+>84h1ZU95TriY3q
zZ-J!$*mTX!EW0-NLA0ygH+ikL`Q#jPmYkaQM;AzdePvwSt&AELuFjAN_8U;ym+v}*
zWwv&wxop8BjF03XRURCDMZ2o>pGP04UTxJ6`f2wfMjYWIcuY!NL$PTdW`4}`yk7+Z
z`R9ib!>8ldOP-YA?qvzj>dQvE$4f8%^ru)ilE+S+&3^_KBs`J{Y)k_Cl^aYGmsQ8k
zEs7%G#-q46TYJ+S#d9MYKtKgE?^OThq4)t_j~z;TmFHJFqKUu2(ILgV_R`1l|EZHv
zzWM`&Qy||I&d<%%Ch?F;*p^iFnCCz%$MDvQ4u_gGn6pumL^9m)L7}9-*P6d)@e~l~
zfXd#ccTSW3;VD66X$217O*&;FgZ2x#DlC?1Mdl!UA$dJ#a}Rh2>vi}5@tpAQJJxd}
zmvn&jq!|p?P|U`5_jC678U=v~N}%SO{4-S?j9+k4T-n`6$`}yBcnnT9=p(o3<<M`s
zStzqhXN0siM~GBm3cBB4)Cmcf0+gIR0rgzC9zvq3O5q1OEz2rsgwX(MvWy$FU%pqL
zoG<#<SoG+6KPppRc;y*dL*t(2nLPr1QWSpM5nT0oV?G9w@PC(RCcA4&OFip6{R}rA
zV^Xpr_C$a3MDUyOFcQQnStqk+!a|=bpC#U42jQ-(SHbomG+@>8$WEJ-9q)bD<*JQ+
zQ91)JZHzJfBlA+oOIq4Onq&LvD(jbxZ#igMNhK}xVmSeIFlicPTuJ24e$5cTiQ(g3
zVto603Y5+xUyp`8>W{l(M9X#Ct8{hC75hBJ2J`9p1*eI_lt@4KtRMP^dRjcv#kc_w
zLGxYuWW|pUSxF_3k>a@pmnwQ4tKSOI)^@S|T_=w4E^67dt-Q_IiO{ZQ3~aejfvqh&
z)-{fR>%jn<iH1Ity@7AHW31Zl9i=U448=j>Y&5G?`d(n~D>3~f#&K>fFVT}Wyd*S5
z*IqDpIJ!;E<mjx0QM|a=_x#bPTvtbLsB9K};3p8mU)9d!vTE|PU;Oa8>=f=UMJZ9y
zKZG7mn#&oEf=eFR=#;K=;rh)1*1wbo0$orP<&A&n9|o3a9cG@mcJDIpUIppYYy&)D
zTAgF)q5L~xGOTF1ZvyRB>nBYuLn=!YK|d3}gGd?I!e}sOP*d&AEE5ElubFfWj>#aY
z_v-KSRj3}$7f8_fzHw1>)^EBGMrl^qHVu#{C?o%F{CPSfI7D#eyN9hGY`ff(kwT9)
zb)?c$+^sjZOVzQO7$-R_-6GidVo9aE57?KgD=7fQ02-DmDscjls>7tAlk?Byv0g24
zSJ!A4i1;`j|6yL$jv8cS>p2pL>x#NK)<ci8;qfziAozvo2`jxD$^)_!YdHhBg%qtI
z2|FcMA9nzt0fC-A@HE-cs#yD;#0FReReVYl65N7xO1i|5U(dumV8P!<05R)*;(&jo
z!rkhwhODeXx?q+T-^TBW?m*@{GT?qgv0Lxhv5(a6Z@^L8j!uCtK|Ec1>~(q@FKw~*
zj+D67fG8GHRd=^g7X$eDYXdxDoFEnM2o-VzL26N#1+#I`S#T0(RzmNv2+(?v{WqRW
z4iCrdDN4KH9E-4f{YTpPn^;Md??xE`a<r5)sCChrZOl?*a$AV)(r?&uSW9H7b3<H_
z*astE`eP96AP-jFd##;b-a2{h2ir4g`rD5bQIAUiIr(U+J0d^!HLzne%=I%Tq15V{
zWDg#J@&8F;@_lgY&~Lt8t5u)?rts~bdlE{vwg#Vm6^Q7I;+X<Y&gMT3V&nSXFTBrj
zt68jvlaPuiYnNXI#;EIBlJ^xz_Nr6AW=9*Gq%+xCdy)Xm5ud={-d(%3n#8`MBS36b
z{CR}zWS&j;3OEQ~+Wa7ru-=siZZNYLIl69*oQ`Xt3;0JmfFHBSo`Sa1wX6H0;L9za
zsm4%BMnz{KLxiOyU{aQpOSE2U_Xts3EG5ht=#m0b-qP~A_1GuiI?%<1MT>ZlGEzmt
zO6NsR-2A4M)qJ<*z}ODdo2}9WFA2(+FH|p*cXgUBJ6BVPR<edw-La7`49IxQkHPTH
z9!Pp62F!!t<K;6;mi@jAIM+yK&7{JNM#fvfi(Kli<`YiSa&!bSe4eFzVxOoE0YvLN
zcmDRaeT6=6;p%GJ9}*7PA=&uwVcH6pnx$mtFN(ynT-V;E%=NZ~2+$1(Y2Idf3olH?
z+g7Knv#*51kk{q8vyDk1tFn-KVnErX^`(xt*QqnVhCVQaN7QKVDY=wpvk8<(lzD4s
z;puz@Ya8Tc$i_QsqSI7sH)=viaV(?h+1dC^_0n;w3Z=yDnB<Acv`OfkBcE`b7Qdm9
zUTD!)wK`0^Sye3OqlU_JRDU@#a9W$q=f?w>(Vu-d^0E(JU|w{RdU4M^ok=+DvYwRE
zNehoa`NjNh3N$i9W5C0sX#(o1>^h1pYP>Dn*@m&J1{X_OH7<7FF`k{T9kC^{B3qay
z7&~JZpBN_DKg!_bnz}9lQPdTua`KP^cj`2l0nKW07Y_KCI?vgkLX45MUvKM*G>~pw
zcP)6)ou(aCB{TIB+t46}Q$tGEe6)4+(e8hCrt9!d{K;>N6|vV)<C}jyAcQZ)(V_@=
zv>mmg#P}RuRW?D{@AVC*1fDbcf#!>T6k;yd&CZ)L*~hsL($Y^o9QZ2RPjI&jYE>%w
zr7}R!f^>Er7eQ4Sq)+no^O4d&O`DWB>%Km>-_s;|hYC_^6(9<XMy^lWQ_PH!c<yfX
zw@X@Jl5Gpo_Tv=N2K5d~3pd^a?pct+6U#5l&pnd&rc-S1_sI>z_u%rF<8%>fJz)8B
zYzUM79yVf?AgWmzhpEOS9KH>?xyw=Jyfy1m;fc2&fK1ra-}CegkZU|VQ|p&5*&q5g
z6<WkOdfmD$_9kV^a!<K@hTab;8jY#D*XoLD^E4$c`j9<*q|T_R+^Dj2?7C)r->N-p
zh$6W76N2<YbBQ--&I;5O7YOBB-OsP@Pe0&AdZX7%%A;?tKA*TG$)BLW=$n}nJyfT(
zzlgG@>mHkj_45g(8g&4>i0#%5y7(yIDqf&QxKzT?uW9J7!^^AOXS2rg>mQ(17#s@2
z&O>F%1-X9MkMIR-eIzZDNSK_L5;Tt#`tPYE$;(yCn86BF%y^)8Y4?zchjGtKPs{Oa
z0oiUqTGuOxXK=oRHecZso|(nsblY{}tY!-*E9C4tH{QQK{*@9@Fzw21Vb4Q?Ce-!b
zh~JqlorkXbX2rbVFmA0^4kO|Psa{@%E0Wp+N`m$dY>d=!kku8ZLVUB5QkmAtAs?Hv
zi^Ovo3k#D5$;1%7WpIOKb+8EW!>HIN#vWJ0Y1;XKbC0XGEX3KzPj&5qpLe%qP1H0h
z%=x2|owSvPx7B1nR_McRa&OH)t78XA&&$K99bI<dQLKg5FJlV7y@Iu#JvrM6r(Hgt
zyrlKv#cIo%7nGX>U05dKiA~ZuTkp2yFC~uD?-2l^^~zEFCZn&Q$|9Ycr9fo;K1{@I
z1Z9qxo})V1M6P&42DnUtPpQT8GWwazics4=9<ko1<AY!KS1U6_Ala|<lT1gSmaauS
zSFCZ?h5GxNhanbNVZy$TMl#DRrCXl7){y8chnFKwB0dy?E)QJR94q}*H$S&qEI#L5
zBtC-8_WB-br5#Im74p-KdJmhn%*Z^@=en-9=c%~&!Jy)&;G5tzKbH}yIF9}i?R25D
z$Q%CW+Vp<ITotWWfLd*^lH2iHa)2Ft-zF?3>CjkdDO6xKET{=wMfEo*FsFmdA=wsi
zE?<*h-8-4KJy~H{f*>b_ljePM_+DApFfT9pY)0`m{yHG!aXhQ3tKD?bEl*UX4raRH
z<&FcYfJ@mVubsYK$9JaYGNiPJM-&9GMDs`n1$Kw0AYq_581j}f&g!n{=dUNZw-sFj
zvBX_@iQePkFF0T)6#bq%mP>uB$8bPo1a}o}>d|D$6*mhN{p%X?@L?QVBG<)vHKQt=
zBm<2kw_@PMt-g)MX9beK#8uL!U&YSO9epONi5(I>@RL1V!i6*xkqbQj{R_l8CqGXM
zHRd;qzGkswLRO4cN%SOJUXFbA3>4d2wjwS4Vv+n|c4Pa)mHEatLCQy;@t}u;3B~Ji
zAlE3`xaX*Y;^lif^@OW3sPsqac!5>6n9T6RcEC<s+qnjK`WBE_(NcQ{hlgS~4^)Oj
zO&^sJ*%LZg<9;`;V*3;vuQuRT`&ar#VD2eJI3K7kE0^#Ep?UAC$N$v%*bV0&(p{Tu
zpj3Q^IdS{^vuG9M@}d3q08v0VOrk9bH*TpvPG?JAUHfzvt`T{!kMmZYEr9K^?)@Mo
zpZr(q;BKbiXWRWaunP0cb9!14s+=NorZF3j^BER<50*;X-P<Pd>gCTytS3ouahS0X
zmsVG4m6lO)URU+FzV-e`pN^A4O=dBiR+S42oa^kkSH7UeNEP^evt6E#W?#%uS?%3e
zYZMr>X||Z^iodqmCie56tMV!Dzzq^p7gXNM5ce(86F=?!XU^dtwVQb$U~lzK<kMFA
zz__G+vnYS3Fi;U2JpY=+5kJcJH0y6l1gd+YydE%$koe&hppt<XVFrh2aJ)}Y(VY<*
z8(H>{f(i!h4CWEs!gZC8wZRVmo9&wdGT#v{E0?yy)1sl#x9|w7Lu2hUj*RK)g5tJl
z=I1YCtA1-&IYm*((Rlqt`pOp+=GE!FPy1GeZ><|8a225OlB-~up=2P6kzLu_+-X#_
zR_u=U+PKt=6%x_gOepHRv;!xh=kOXpMRGm)p$<Nt^6rCBV;QRI%b+<#(la5zuyqes
zdQg4%o_73=l&-ep*RkCn(Uj78gmZ^yntS%*!I8fLO;v*bjovxsAra08V>8>O6`m_)
z$<(V*dg%A*=y|A(jm1o@f8zJ=aT+0CJ}7JsdZW)b*-j{ar(N#ynoBhhbghI<aK8kn
z!R+QCm5BB)Cz-*%wdhu!1FIbHS~3A7iAOgS{sg8h5&sk#^=VfTI_P5_`0BUtN@{0>
z?_!JXy_D9>%FD9jxcExCiC;cB-?h!3uqTRb%?MT`i&wVhVu_-y`4V$0o~Z5IFJzzn
zmEgS<p*jnwZr1?R2wKxQEk*88>Og;k@yZQz>OG1mVYX!Dg0Uxw#5uk}TWt(u4ADRG
zQCqL@4)4>Ak8m$*yX>i);g3J^pA}ipJL<8q!Sn9$7*&uI)QO7bJt>m!R;cLn_mZ&(
z%H-e|yxZTfX9IpPf#&u_G5@_lzxyc7u2K-(%$W(57>2n{61ChL8=8t$I@z-Zi5&2z
z2P(GkbIQ5jqVSomgJwm)%w^U@`m@f)Xw0whkN126q-0fX9F6Z#Hfv0e<K4e;ZM|~E
zU^4uRXgn*19VPlAj66G<xgzd0+`1APlc6!?;nDIVw^C(mM6w#T=mI1}6J(|uIsa(n
z5SvF#({a|LgKol%1iz^|$U5mkUD3}=WX^IDazo4VRw(DPj0@rmn1*p&@2XdmW^Dr_
zYs5u!VvgqX94(8iscj$oA5yj)ob1vb<PD^iQsD&*cVRH+nAb&XCe)>y(L2b(S<)M8
z|I-3^t;gqa#qGH75<`j~YmSAkH~E!+EQF;z%qZ3gE7CsX6w_Z<A2K|q6)R?VvZWD!
z0t;^Ci1KgOPV^g@GC9jNf$eNz>g|>HeY5rh(Z}fW^G$}E=)=~q6+b4<V81#ZzKY=k
zR7shI^jd)EN+`CuI{m<P+|Usyfgl|}24_YslzlX^Hd+;DEg!4}1SonaWo^JT8J?ci
zf*4tL2JAo%q0k|wcy<_ZM2fZk-f~Z=g|?m(iFAYvCwNH-WHr0)tkthd8}j52V&V+i
zd2+N0%fZGI_PGC`TVME=nL)aA%U*<zvr&dx$tGaMS+{8ASan}I8q-h`sE)mnD!N&`
zpBj_FF@BRA@oiXeV37VOY8`MGb-u<LoP&%}AE}o8;J6lxzGb>CdO3TiT)Cc0#nPbx
zo>RVo`D+BmCjgy!6!v$ydWn~hujIe}Z1@l<=%~hwAD$7Pop}$ku%}6U;_N5TW!27X
zz7?PLP8R3?EhQFf%$!^W#-}G0+IO7-7HhG(S(_V3O~X;|wqzG>A2I7U-k*$?L3**K
zR`H9Pj0By(l=BwnV?(Z(e=(}qjKRcTSe8Li^H90t0aVGt?%VU7M%DEl_$#dfw<U>9
z4En=5FT)I!*4s;T-<BI}M6f7WBGW0wY$8e0V_~v}p9Vx<0E_-9Jom-J@0t6lC213v
z&EUr~bo9t>zwObXDRkty$9i=wuJe2c(@&<0&MNXMUUtW4b|#4aV9&s9BGQu<f!7K_
zjeD~O45@9)Tq70~9*X<w6oH1V`+<m3knS-XrS?wqkRF%EhK$uhGu*%f4Ly+wd$~8%
zs43q8%>evYc-g@r5;~T)q6~zl_DdT!unid)cz8nW@Su+FE9D!{df9`Z^Pe<$=+=OB
z8WFkOh<#fooG>Ij19L6>`bHdEQuH8K;xr?p1)VnJeom5Wu4pL8gqWn8l=gpkg1f|R
z%Sg)VL~><5`N$Q2^);BOg1G3Q=nRFJTwgEm=1m`{fktLc){%|Jhh!3#0D|?Wn=!ZD
zsQnr?e4fGH)2AiZl*!5m1Tncg`2uWPGOMkC-V2r~S)Ua)Z~(Ho_br=0WL)oMaIj!)
zEr*dnPItqA!J(*CEH~x?XEWz!8S`;1z&s^1$C);cCW8Z9xG3*aw43N!X>svSKS!Q6
z+OJVmP#L>pS9Q89lR)~0-PEc4Hccqw*3^VsVLEUSsl#WB0KS9@Kvlp~W2K$%s0Z`=
z`HRUVVd?%Oi&wR|3n&5e(bnu)X_6?a_v)6@?5_z11+-xa`|=0^0ELM+H?DFD$jV~3
zqm65#`ep}1NmN<-<-zIB7{&n?L0NBJq<_m=*KQz+buGlBd;+>tC}=kzZ&&<zf*y^<
zEq?QC;cC^e7?_ExdTlKgbiA<TH@!c63uq8#3tfIp=TN|2&7H14%^+f{0s@~PY<L;o
zDlj8Mqzj?*V};Pe58Hv|)#pw~4%ac%?{;0s+0Z1s>;}9Z2I366{h9pjCRZ!@j~WEr
z?W;6(kB*VOx=qA@2iX`D5x$3Pd0BN^5<G48Z>>(eOB*270YuHZagSFnO-6=<WrWMB
zN4GH}BRLlgWuq6EaV}*eLkv&VHKxUe^MgE*I%nzra>pfg#md$K)6~y-!@sv)Qz(j(
zw5Jp{RosGE=HXh{Xkp;BqWR-J>z4gDx9476$R(B;-UU}Kk6?i?okMM}@oDaSprJui
z1$l+Q52Et+Xjxn@nLXhZ<v-Yb2$5V_J=hOsxDU92*G4a2t|rjx4&Cs&^yP?@H0kmD
zS3HYu=P}$~Ds6}yzE|_KA1G%whYw2HMRdAKH%txP<&aLK=O#-@iXIdtf@1WyosE-8
z>bm(zjN9{!ckep?Cg33HbS?j+3<+*NeFZhm4EoZ2i;7>%WpY<zWv2+#?tp%)E8N{z
z;ny-ny-uZYVm_A+@RkgiC<xZByD+Ka)}e?&=f)1ST(eUHEZQCAFP)ddAD+fN5ZI7^
zYQ=Wvx>ufo@VHQy0PWH+L{bc&PJg;Yl<Fz0;c%mF4Q10%yi9fn2%fMDZ@o7PGm2j)
zn2@bg;VM%}X<psg*B}QCsm1iE{L*OzFkXqYIp1i0G<>|d<MgVE)v{mI=xZOh!u*9@
zsh@$es;dc{S7>is2RW>}c+$Z3qtGj5|4$J}5qL>nm)RGP8VELMS^rdQ(Xnhdz-H?8
z1XM05=Kpi|l@LKEB}=HAuos(QK?F^wR%v<bJ-Wm--E-S?u9lXw?FBZS`l`Zl>$C1#
zp@2>k$vj^QE4mz{d@0zPf~hl(L}W@ry!RQTgPO53zM!vCI*@u#hD88$UE(oKU5XdG
zYI>%=YO5t^kHcB@o)Q{vy!7T!^w;tG7c7z5rNvJY=vBSN_)0-8nYLb)UJ1S4`~7;=
zG5lc8{~e($kC5&yi6<a00^#Ek`H^pBSR3aYE_pHK;ZFql{d~UGvu(m)7Y8^au!keS
z-i8cRM#2ftfvol6T+>X&wBbSF+=uO9Xd3b>=s>WardONf61@=;nR$8K%~<&6z{5KY
zR#%?>w3&U8jm7?(dX3NkW!D}AxzVkwr}Jp)h)$k|)6~M?Hbl}^SS!HOA?)?TS6a@K
zn>(N2=`+O-2;Ks(3#s=Sjiw}XQ3~RJ4YRR9YpEYN1v;)0i+wg0*!iQ{!hYjsnuV`3
z9})`4HFS;tQuutYzaPtXE1x8aVwq1b*jiXyL)h?yY=ErD_SWF#j^A#M_{)R0r*$_c
zie8xHe{s{;mihiRANIi|eY(6-$%Gks>z4^JI2qp`&x`{3;u+?Ea<J((4CWcr&?OtR
z_ewsL$&|(|4!5y<^K5p&CNTgf4Q!T~y}Pk#SaiXPADqMe5E8O<JQKtOgCru_^H^$U
z1Y;)=hBgu)+2PxA`sqm`y(<Bm;nUQ%yw-a(h~f79ph*{s=p~|i{Fflf{c4thC_;$Q
zJ*1$gzeD_01^Sl9UJ8LZb%k>&V=j9A(ySC#j;c`En3ZJKHNu^Ikke38OjeS83NM(|
zqy=BeTeOjn%W1P^cWSCpHYG&D?e0*3snl}_FvT6Us$e`DImTD(2Wz3Q{V%u0;I4je
zO3PfMmoT^BRk~THJvW{8GMd&~YL?IqBC7a58P~%F|LNYv+6D!w1sbaxx5LhI&2J$0
zJ!dnD4u(<GMpKsvIDA9p0o&hka+6#bBtP^qJfOwZ#6OxOotmmmL$=c-CTXZrVxXcp
zBR(telWw}L3}7Dv7zcEyp@&fRT|SR>;LiE&!0nxzY>DP6fd$_mD&qBdOuY?C$|}ho
z4*A);C2@rs%=F@)5LE46&rMHOpHM_Z`IZVNzB>4oDX%<~Kpv%+mhu>Vpl9-6NhV4)
zk&ioN6#vnnpxGybR(&9aFPRY$`W-<|dT+9iQm16OPB#ZwL2zDS+@#Xs4-FS$S-W=;
zX0|z*=H<;RhcC`xc$>sOj<`3v4|PJ;WTq%EtD-;W9VS(g$OAdHpVLlVO>+pTzTO_l
zaEr=kx*|N^9f2$>o(l9NznL2GLdkj`s<7gBZcIpaGqpxZx+{*QGvPj?CUbZE(l5$e
z9V_<XTmOftw}6Ur``*XL02MB96#?lBNJvUcs|YCFT}nzL3`ir0C@J0D%+L(Y03uyd
zgS1G_3?U68@jv7JeDCjnmaK(~ne(3a#6CNo{cJ5y?6r5tk;-lAC1>3rr5-;dkd5W@
z3Rf@%pFokk@XD-^?GeQ7iAKM+Z29IgZ}TrNAqlTj;^E#}C(e1R8Nnu55M+a0*yKDP
zpCH{DKAvongtRjYPGxs(3=#{)HRs}QD9|VcJ3nW7T7`nUMz6Gp<<0QAJX;v<m(B48
zh=AE?n?SWC#jg|RO>^7Hag-s|<!^UtERYRYJi{;B8i(au++-9;71|D+u(z?KMlu(|
zB4ciukjs<>cd2IZvfG=mf#a2e-S}+m+DNoo4&LT@A)4!shvjUhFZG_^b`rQILtj3x
zbL=$|SGjkEn<??N?Q$w$AyB9QlyA!2ZoHG^u12(a><23y@!f@ChzHd~Hx0S(eDHOQ
zj6&y09i!*zqcLT`-L|%7fg!d!a7P-+EtW$+;pa>+(YLka@b$TT4@+3udh`PT$(^}P
zk7}LPQS`a}DUc8H*bVTDE1h%3`+&@-L=iI{9xs!s*U#;zqKX5i<7Z}T`d67bDP$46
zq>w-*0TNjw6#HShXxS*O8OWS+vey#F+Pdd*%nV(#y$){p%^^SBW@x>=oY`3m2vp3|
zYqb8rkOD+J)bio%-xkmA(N{m;j3B}CCHX02cx<Of{}ymJvn~L@w}k$;OEfwl@)hVk
zZoPWAo9T0iS$StL1!StUgm)Z>FRi(AK+K2pWV^?w>^R-5C^)}p0v0N@ky;N^sPWRb
z#+=bN(_@+QTu|@gR{6;*5SQ10;={AWA0d4f6<NJyvuK~xpLwx6%YG1QHpADmbeld9
z=P@pvfjisT))vq(xG5gzc91Fa*7#UT#B{a4bOa8)qLg9vwn^Gwvu)gO#EXd-ty~mN
zbzgM@wZLfS1+peVSPxjef1Lu)kyC5Ssf!#ott@w8_O!A*f>aN9Gaj=Du7cbWp}zsn
z8<jdaoUtCteg6SSF!36A4fP!9eTW8V8-3%abtPE=uiF-WD`AIk89di~WQn0Nt9jaX
zf=LLIhtufXgd~mBk+h;$2RKO$p4)VPY+2PAurfFd_#U1uN0Jh2x*(Y?W8x87*CWqc
zH9W-?7kbb$aG`XbbMS=%05t-eCSI;XmG*B>%de8Pc*`2J3c2Rv9RW0%9iNm3smx%y
zkysopDHolzjHN3+^+eAEY7Em=?R|KPy9VJV9sO8ve7Wa6k6YkT{K_XuDNR{*FxyuB
zg3-H&5Wz|vLXa&T!VL%*>wqiFLylSfkwq1=t%fY@OC0Vzld*VSye+QFEoBeEBAy$4
zI9HaeVHyY=%@Fkp@6CwRp{LnWAAHNAmGR_*?V9G-Z=PI98k?2K<1tb-6#(P8uZgO2
z490Aw7zFl%WRBYB-zRSPdj&7-hhwd`bZ<u+cu&zzZ5%H)%N1%|vNvDhmO|d2O0)Pe
zU2&N$^dy|d`^7##Ynf)Y)JS-iwx{ipIZ%TjiRD35v3WnX6vj>Si6$ZKKdGXr5DwG%
zB97u^Al)F|q0dd+pY$(&<dvimAzu)|doWvmhV2vbD>D}3jl0bZ38XOs_G*@ot63M8
zM7C+Qo56AZGaS%WsMA~Zj7MiB6Q!rT-D{7q9;*p0rD`TV=Kd0-&p?z}8=Yo_FcPEJ
z`z3-0AnDUYB^kQ6Bx_fgoPKYtcE*6{JwBZ~Jf<S*2<~C*W&CL^XgHH)a9vj1w?PjW
z6Ma-g#9SbGZt&Xp!DRa2jRmUkguA4ToOi|a2qDE82(HwLacYuU_B;I0A(XC^*XM0z
z2qqkh!zEqPOu$UP=hY>;bp1v`ryh8@*S4?T^Gv<E^Wb;knCYrnF@8YabSb#8uZVX?
zbPwvV%_SuGFdAhM3YA{ocvPGkzzLA_Rr&_A^(1zyr7vDlUP%VMNd98=a{6VIh;;7V
zKcyvx6!Q!S2_-%FC$Vc;9C8RGboSGdz2l%x3jz|-8)UkC^1kckIX=}~3Hwjq9c?~1
zuxpqz#^W0x-#Ds?Zit6$0T!8}CHlaEj)(bH18fMl^;>dzRMhC#&yDK-vRm#RCz?K7
z9CK&7NBD%;Sb9WISUOYt+rFb#+^qy9;{l*fW51WAvlRwMM(`y`NqGf2Q9>|Uy&~5L
z29*bFldl0@OS=vADy3sfJ)M??xRT~E`vj7E!{GVtV-_b!$+o=#KRrUSUI_QC4@`$g
zs_6cVo&@DJ-bN8{bX}J#MNIhbcNSmP73%bC{5^PWF-etfN4@0U=EYQBoa4Jrpr;Mi
z2ltEtEr+Of9k?S9K9}wZoL2)eG?^UNiIVAM60}4X?}bv|G@Q`?e0imuZ>T|ItrM>_
z>4Gc{(xe$q(@PhR5W2<ES90xR-xB`>LN?Y-$0~qBfFtD}j<)a5n5|4)yIxQ0S}h55
z9w0oniVY2U>H7mMKV}oGDNI+b-slaWB(5Wpli#`uvE$QoIc#4h2Xnn3Q>K{`Oa{Tk
zEuY|%igJx#9vue*Wrq<7RUSw0UDek0I~a#Cjp${MGG#h*uJ0D&LsT`iZg+6&C0n?R
zOdkq<-i$jk>KhYnBgR#a6Rt$|36S73vZT+3BMoa>0Jf#TxMT8N-s|%|JyN@=@$o(1
zVM9JbkQn#r8UHWjc4mBGQCg|G#`43j*RBpGWiRrH#b1Z$OENE++oY4bGE816cJ`Eh
zSh^i0i<=a!&`>baUvsnm^cGn$x|@r{Wsu`8uI1Uq&$9R)m*>Pfqdz^3HjR_yXbw6`
zrIvvg5zPbV1Q;?VgG+WXeIb_;R_s}~qZtmpkd-q-5{A*^=9i3sjcgdq`L4U_CG=^)
zK@2?x8z#M9<<dJrA~AE=(}s|3I~!GSfAulyCIEpp16a|WIyCAb?f8A$cc&V_)jSeP
z5vk)b#*^`>|G{_)F{JVlop@%++p-;{P&I8N1B5aU_^0(QwvrkA>@=qw9JQ2~^GhaD
zT$vsFDm4uhq9w&jKqk~m6G?3K-%r9*n;pGtOk*FFQhil3-ji2bAV!BTPhs2}y{^E3
zJN>bgn<eH_**GsCbEc3hk0mU*oKSJgu4WHYT`j(PAE=iPlC-kh(^Ed=BuTXywe8#M
zfr!S*Yc3GZXvSw~`nhIp`&+_asya=;KtL0KVjs~tux(Dbw<uBw-wC2jW<=&+yYU-3
zB&=|k$V7Z)rRf7H<F*FAE{b_fgY(q;O!4@!I+8vB3zCQ(lZuYuc?{&7N#>6I$OZM*
zw2T&3lQQCeaQlx1g9#-jr_yqNDLCc?NiJ%46Wf1@>`MarH&(k*&MdjX^itX_gzn#c
z)d4)>!K;+?Jc!rbk#^r-Y&<V9u~3ckeM;G$Zcvyb+5$JLM>@m2CHUy7AHiB#;p=9T
zIdLpr^kOk2b9Wi{d)$UDvs!;g#jTX?v|dW-WUz;3RC?*naBP+9-eP*VbXzRhvR#Dm
z_p3oa7YKVq$C_!|nfXHzQWr+r^oNgJmSzI2{t}?JycMsmUog3r(GX{`UM_wdJz4JI
zsX3*5eBeF;kgNz(*tT1#e_V4Z@=(IgK@pb2q;-&PDNx9sHFtl67)97**!3l^H2jb-
zbN$p+rRXR=hZ(Mbc7Imlu00g_x{=AOJG~7%^*lBPF09CAA@1RuM@VRNf53+Z(mwNf
z;J3KHhwjw2lcv4Jvnau1=XmEb)g!jUm^SIso+vfFY(+@BVhTMUj%M8x1<}(rVu{1t
zWKG!Zq&Z&35DoPj=EXHqs(ACO27#>tX{Q;RWEiKC+1(_NFc@5SH`8=}drT%Qre!SQ
z8{c!Z#Uk!fS+tS2Sz{x*(Hm2SEu?*+b@l=(botM(76+t`R9*#_tek#*gf`VkaiegV
zOK;px7MbBa3!PtdDypalVzewEETtb;=cK$*X9Ebw7uZ(!kgA73L@Q-{VNy`bNEsE~
zW*9>Qz=l`!EePU6fh_8#ntYKPk9dZC<B74e6S__lj1v;r|91P(@g1P2thI2<C~qs2
zTWqvxP}a$z`;rqh%xB$B@^`oZH+|5Z8chKTEdh#6PvB~>e=_n|G2n7lFoE|PM4b(r
zw+>vjps}L9|80tDS+g3JMc<Dbg$(?4k5%hQcZC`0AG8XjT^tXx1})I)-o0UN`-LC9
zduuuFY;2eWMfq@=w1H+CYA0hoCGun|LbiyOJ9>XU+&=Slj0yiO2zRHSLN|1CFv7#x
znZtXSMWN_mqpCzeH{{h_q9_KjYMoHh3>^~_j}F(<7MMj(laRRX*;E7Nir{i8;&tD3
z?9U~mdS$$^@w|K&D(kE6?BuWAoNLi<sOQOEj~>wa4HcQvM(+Wxr2ml$KoVcR5wDP7
zyhn1kwgGswSjR)~Pm7Ec*|_-aX@^C*BI<^F@Ab{>PhaKA(-z3Bv6&UF8wRr(KO`?K
zB|-N#Q`q%^>4zY&BbwG}%qpCG6?e88lz6rU>3<$|%OB3+7|uN|!=cPmh8;kQ#ghCx
zQIN!rdws59ZOe;>eaBPdSMS=VB?w7ne6xsVwTwux9KHdP8ubmR%V3936+5ckfpW<a
zZNu(;m_{$tzzsBma`=&)!a+>r;)H~cS>7!^-5h-9ky_|K6ACGoM<Qs_2K(x}Od^l{
zU{xjQVRTVCmSv46&?>b{8K&?b5qRuT;8<8nkbl8B!};o3Md_r<kVJPcCiQzIvi3Xx
z8**5r*Z36D?)@i87{8>Iy0|4-i_}aWrw5-$`_i{11T@x40~Pn4#TJW;MI~TOZNcN)
zXUr`RXA1Lh&ShkrmWib99v^HDk;BckT;fO~U@f2|{s$`I9%oTg!CcOb7Cn8r8$K|d
zUJ=l84v)%6F(~K{?0+a{e7$4lHqq%!oul@YiKl!hSr#f&>RMROegZyq^Mz(y+NgbM
zruN{2i}S9vU-_mpF3O}^eSlJmvef;Lxe3wcvM-RiIMDJw`x?J+w#PFwN3FL|L&Got
zoWpEW{NjS2$7BKu6!7O^Z1w7@&3^2XyO!|t`_)b8LM=NxMeG>jjfWHCXf(rI&Qgqg
z;x~Xj()Q#i8Fmr)MyD`_{9gPest7*fa|iPH^cPSHK?|h#B?-GcS;*dQ3D8!Fe0iFw
zBVeNL$9#YJo{H+aaNJ-`?p4&Mmi)H`;qAHbS5+-XTa4-!<8z4Z&X}O1ogKZ4+j?>2
zpdup#LZS7U#hDswNCEHk*%9Ww!&_X=3wvgwI<5S?&r&(XA-RG!uoO?J`RB3Kx~Zu{
z_I5`piNDFmYZrTP7AvkV{Uhz2R9{~ruOOV0O<j~NEEK2A0t^+hW{Tfk=<<Th9?o1o
zvx*MiR*?|Oi!>;!n!JL5N&f(kg_Zs%+=mEK(^(j*jv6d2Vhog6=!t^byHvg~ly3lB
zvK=M=n`B5aMTjC*pxngds(WW-5fzDnq@W0_GjzBV=JtjHUudPgmT`13V*ak}uzrrJ
zS^6BGeWQLG<>aK5`*<Y#B=V(Ul$&(l>xhX7cj=YsX)&!OqAS^N|DdG6o2k<zs`A<=
z@av|DMgpoc3aK7fKgU`AQuSUg3o9TnHjR<I-%j$WQ2A6`TEhAw7LzEEyw0h^;v6Qy
z9l+!ZM5h5DYG#`{)N6bUxfunn+CNRPb8Pfg*&7pBVPd>;dzT4@oVshdD^w61w1SVf
zD31iY2``L7_v{^2FokJqB?!meD2gh5)f;4ops>qJ%D=BvuKgdy=HnOl5=jke;G5OF
z`srCc1t71(D&p=P%#bjp)J4ugx79_LY~!;$FO!-!wHO!I9deVNsf+V#rAFEN1pmLv
zRO-y!^wqkj1PXClpW2U43N`r)#+Rxm0D4ceyR`xN2pUP`fgUheCnCX(O)TgXb0!x*
zu(fzAFTp}Sb1(DOTtVIpnA6FLbRwaid$981J^=tUFSz}GhXJgUd#yeU9)a_ot##|E
z{Ic|u?^n9iY`Jd-SZ^?saC4LM@vltKkXUcOee$s6(?$CTAJ_AxZ*GS!O+E=+#>O@r
zC71Q*(o)UkYGqD_79q*Vthw@$2zpfGQ`v$6BZ{2Q>^;}bhFNJ={a6DL_>`T0r}~S&
z>c<MJK1=P)bwVOTWfiu5d`_W~(&<Y-+l^D)`lsL~M7aWgQT99E;5(|OJWhter{41k
zbA>PX>IxG{rthSndYanGukE@~Wx=8?4^h3h=l^D$;5$MpvY46>a2eB2J3I>s%2V$p
z6LR)oGc5${&O&(khHu%=ZW_X0%U3^f;y}dG{>lZSboGalc#8dKpRrPbl0huLuF+F1
zTyXi$M(WA8xhX3Ip9uUII$xmnmyD9%srBTZ*{n8a?(QdVs6#TZx2g#3*tcHX#>tgz
zZ=Tj-ynhok_3L@Q1xoF&;DE6DY(58+JDL9L`1KXY-(N2_K3;fZ_1yhlJ&syadn6uf
zI_jd#xab~Q-k85E$J4)VLJ}?X;!0Cwy2KRRLEIRb3(3Cz|Hi&yTZPIH8!z`=FnN=X
zkhdAG<4R%&F^9)h;+-`(#*D>r)UW)(tAJE+>r*6#tO;4xP_lKbjx2iYh%lZ?8k{j8
zB!sN}LBZh1$@<d4(d>RPL0(>@H)ccLs)mWj{k%xsWpZjUSF1?el7~tR8~~K?=u6NY
zVQP)AKmqNYbE{HY$6jk@qP;}sBoe+8X#xm}h#8IV4}AD`5T$*_x|q0Mp)7eE6tj`8
z$*rj_LY24<&Xd?_W?sywcVv`sFBkXxDG*hXd0djPkGofgT&)mdk|u>=s1Ku6-m7n3
z%CRW%3F>h)&`{g|V{^rP2w!>+-vVQ^^W>nFx~a*<;{bQoO=Doe%0*4xcOA1y0zgju
zTXL&?y(E8=|B4h^?djLoSzUEwk~-S3rhoJe_S|ymI6QNGV=%>oB+K5o3j;Ct`hQak
zNc<^&A7FOXj`!-QE`d&$xZJl%NU}nMU=`3gNZ);GOm<&1v8ojD(wvsxX#W4O0NHY<
zL9h%7d2PL{7<j@?;~Qfx3wZVPXK(MB$;Cxxu0-Bzl}G=HhELq{q%>d?>SherVLIGB
zv$MOB*pKbM!niDS?1K^Vow6!GBhutfO+sjjQ0YGU*$4GqeZ%C%aD^B$iDwl3(-eaX
zWPySqzNSRObN}j)f%8y4JYg*5SJ&l;mB|aIRU#0#dBceZQ{$T*0ba+bL|Qpi`lOFv
z0Tn|~g#Wv9Asn|l@v4@2Mzaj!g@25N&H2a7LHBqB10ZeugBSwefBXqg-Uop@lNB`|
zRK!j7oBh0#&WAoKX>H;|yoM58gT&uG|M=%o5SN%`HARsY_^g{UdH}3gF{c>qSdW5}
z2CB(h<NSqigP4~<{|Qr<ifQ+~A@7&-{H;b=3^MQ*C>N-TU=9rPf4lj?y!bj%*|d5f
z*+G!C0yrnLXO!Q%`nhj-;d*wlwSwX~@EyDS&+0ah9_S&x->6{vMD?1KA?-x}jrsL=
z-vTbsnLfGi3%^tO!&O>7X;026!^R-6>k$!bpZ|SOyRm$TV$z@AA5Z_kReGBM!0@02
zR{y_!_fSL+4S?mKaWtzJfEmTN$7R`he-<VCECP;6Z=sn>ha*xC^HL94V08ii&GKzE
zd0pMYv5-ICv5SwHB*v&=Rfg1TJ>9i4=`w~98#~>kScMXmJ>8|``2UufgYWg>HuIkw
z9nL7PD>HdkyfE$>O_RRawJsW3<Zj}i&dA`O>6A5NbR?c$z4Px8fnY!A<czWY`z&=(
z?IgX4;ast&H7SIf*Vd)R+w(Ws;m;3oL}`1xjxYYz7r>lYaQ~}`K7Jh%QQ?VLtcZ5T
zsR@gv5cEJpZ4O5x7r%|v(rM&Jyd?hbt?1J#-2c3MAk99mko^Fa7<$+9jZ#!(O3*^<
z62m;orPSf@zZK~Nx8k1x#((C5=?O~}By0JGh7~{9n2c0d?N2OV`>$W7e}4<SBcQ7n
z+H*~9_HL%`;DZr<&j0Dkkobt(N}-Ph3djD4+hSHhf1zLLwIs0YJ-YPw{na{uUL68g
zON^q#Ch(8dMMAw-_nX~2g?ai{{mwUbZ_Qt9U5Qk-v>F(%!pE2&NA6o4oKJ7z&?tqg
z(AWm{Mmd8v$(Wn}jffhY5-bYplXh6OC|*pThUJw${%Is}h@tYpN-_FBEBYNv0Vl=x
zgs4VsEEXQ4StHpeZgXxoyy_1}N2Qop!9L-SEWW9WgN;N~*&h)DjGAwZ7v1jw!4;Kh
zvxi>X#fj)T@{iuw)qhfc2HE}any)mU>Vc8ef9lWEQ=nYwtcZh}bW8GnKRrobPu1ZF
zdQ1XT!Y_UXhaRS5XIGN<;4vT=49WKJdb4^%Kk6Z$9<twa^M9t;ziS<SxUv>phRbTJ
zHEXUH<reeU87A~Q5GA#pItsalcjG`FX1y~GCL~f~^fY!6n9aS#XISU`f9EsXl8(Jd
zpS$Q8GuIS}OY`kgRc;K%v0}b3vD;<TO~m8tVWOU60Sv!60w3?aIp`Zr6GnF>(n)M7
z9O_w!a&9F#qd%)p*WpJAJ_0R*x#>%g(Iwq47}vmGZ#g+^1_L37hU6p?O>3C$_Wh%6
z2X)D9&J@o098UaK5SVupY<|Dy!VeZmJWF`uW4YACu>HLp4n&;2I%Y_XESgpWHB0e+
zL*oDTj52ekwydmt?8LXv8b-4bQFPO#NTi4Xjq$`?i~P^zl8=`k$qyvsXWu+yz(`>+
zb2{gS*1Y)NjG7s7<N8cYEHIS1p`htAg)x)Vqk($MUV{G?MIhwMstFN@IClg~#pb_z
zN9o1DHH`{$M~w%osbVN-o30M|9DI+r{sUx$n5VF{ByXqB>yFYqs{V6+AdmY_2%LxA
z$^pa6JJYRsiGO->%H+y=!Dhuy{l3a`MUzASe762K+6gZUvP=IHRDEw3=CVWXH!`V7
zc#_(W7rMSMwyGdNDfWyEbH?q5X9_+{*S%CPi~unQus2Wtf8X18uWe|*2jem7zI%%*
z;3b2-5%XHVtMceF{Z#K=89eVO1O@V2IEXEV7fXJAkaXSrvsUf6C7*CUmfLD8EAJ^u
zEwY;q$O?p|()hg3N*40RsF4@=FP0h=j}c@a0SlnkarPq(%~&<c_KiT!LZ(N7;F4m}
zpA8O4{BaT&`_!;{D-iK!Zr_BH*T?&lH3f40xpckNM3{E>IMw#Xr1ROFQ{(nevnk_+
zsU+ldg{AlIL;Nv=z@gW9)HO3qw8UK;qkrzsb?x(m|IF07J|&Z>Rv{;cCh+{ryUyM3
znaW!6&op!Q@Obh+Spz(h9W=n2=ScEQGW!RWK60*5L4)n|p0%%ga69eNUV=Yi+~#r%
zj>MfmnPx`T<DX^D!(#g`_F*gyjn+(Ch1#cQ+hJ318X7@y-xIjM%kgBtHA`3e|0@0J
z0L5mmtbIRHHOnz+rzX{rCna+TOMdzGsizD8k{d6Ue|Yx1=yzP0oH5k%tB^>_cm`Pn
zrpiKVPjVO^)PfZIU+1ZO)%~1SG!k#9buAOmBVOs4Wue^sHyaqFstr0jRbYlJ_;Eq>
z=`-uU&oJo{G#O0fE2GBe$)eEPH+ncti12@n2gF)%eZ8rCQo0SD`;uyH-?%1N1;pJq
z;Qj}B88nO)W+52-=OD$TQT#LCZ;vN#zrSA+@Td&gQG3Q|WYb}mpBG}OFY@R5Q9rzC
zXf78KQ|Cy_!)fXI1VHQ7RQ^q&0!*xi%xf4GzD0PJcb6`-PQfZ-^w(QmvlGJ#=}Uy^
zP$4BTADjodGhoPNF_=E3*;ibh@|>XbPrupj_<p}EwP0ukuGknL5JT|=f4D{=rK2O4
zUrAfB?4F#Ie%1z&ADTWd{N8V#oVh#7cs{R10q1>G@#Dc=<XNp2)6T~CUEa}uuQK&5
z&|^qMqT7eBcH1VvZUzl5$`kn#gz=0H78iZJdVdDF^p1`oozmb4Tr*$h=!tguRUN{0
zuaNL3#P*TaHhJP6aHDI%JQScN321={VErlj)}N+kMsdaTQcCq0zIKnd`d6G|jkNsq
z+s=u74rizwwI8i;KjLM80^ap4ZBGSbM%+rA&h5IB(Q9d|AJSGEkiH|MgUZUlLy3B`
z3{JlOqVZJkaT&KG^3S1e57U1EP^TD7Dz~>P8@Yy=v(ahTztcq2vQ`)AJs&Re;I5&#
z?~f)R{$JKdWu~IcF0;mA>ht{((ekSjDtPxCsBQGUjz34QHQUGp5W}PoW1Ejju`zjC
zd%hsKMm-WtPgiVTvA}fYt5IK#Wnuz7v_r$-9|-}etZO}zqYVe8lzxC4rqwa-V%uy4
zeoDS4-<5&ibH&goe(!xQ5v-K+Y{60DM>-43vV%p_dXr0+-v;NGSrR$gGcflQNMIo4
zw$iP;L;W1>w-_u|lM#MTZ(5n>KNqSvI>OgUDy*wBkYgsGZtBLro_>+|?5lU{LZTli
zNcB3<bj?ReqTnoWh)(f)A1&#&{w`~t7^O+rKe**;k^gLNa@Mq2#rf^-np{%MH3(b<
z#KFP<V*#KvmCFms?Y0qoX$8zA<h_zSKf~V@XgygAMXG8F@@1&^-UeG_l!$h%Bz{?o
z-{(|CG>Kj(Hd0nzPvASTDlLxxL;iuP*PocAHES|x+Y{6)X=N4PNq#msd1DcwX4JHd
z8yLx$Sov!w2PAO*9n%?RCGhg_pq6TK{0mouIJ8t2RTSCbU7h1+7+Nlo*R2E`gA-$^
z6NjSdx=KpbuMmIaaDnftMDROVa<ktT*^(7RP0#-1<-*-$j+-34FC~t-?^QSab63Fo
zH*FpE+NECw=FS`=31kvb1L+PbVz7>rXf68wRoQ()UbrwQzT~}E;uIMnRPOPq`0r(X
zC=}GiwfCWj9?AL|DYxHrffK}RrpLOL{;*`izjl1@G2=arOZBFW-OgnLzsrkJ0bOnJ
zZWmEDun=wHv$;65o}&&ohEjNeU!KojwTN`bp4ZI^5~#^U6B^6$wwxirH=OW>;RH$=
z7}#-oF02--O}dS~&+}LgQ`6xv_Y!?pdAxT9+azm~^q2Ys@avo(79D=KFq)j5ZBnGb
zulQqV-}*VHfygrfJO?fW`@KVI$j&kBdg{0~BWlTSs0phuc^gg;cnJJ6irt2<9a>D6
z$q!>E$1`}~5fSjJSgXd*hxte**t`#6__pS4QlFXn3N_hvnuLLU7(j0WmSiO>NvrCv
z8|<3YYG}A#cbH;{`X6T~C)-^Cfq{nmciuEcU4=|C{~BW|w~znW7$%=?bsqD0tA<LJ
za_kgI$ZT0fDqMd*;ko6tp-=KecJ^63T5_Q0$#%{a@33b?;NKg4Lz3dxpn9T|hi~b|
zu3Ba~>X&}yGF*{A@sE9mgXY@kmbh02I*6=ezf%uKUwe$W={|eXA*JFyN!)~RbIY)f
zC6EFzIe?73;A~2}+HUvhJuwkYMO8QFouzViV6{n8zc4Y0n`wbQjU;*Pm6_M~>Ah;^
zHYijT@k>BGSaJjtmnBn>Mp|n(+x<1y;)a3%E_@_IyHIhsqZ02W)*n&LRKd*3(4o>y
zk&PQ-?B3SUotRw#5b5S9$PJ?GelBy^&x4z+-_kU4J9xz&t_PT1>*vRE7SB(XY3`{e
z)u=*r*is_;aD^KMviD!0MmHVczIc2jT%%imYfdb8zWK&oQW>|~h${ZFBN9RHUpbC6
zjP}LmA&~x6<p53R%ZwWb_A<>%Q`>gh%nV}(4yLH2RGQ9yOGzpJSB6<9Mdae6T7W;=
z5EO|8y_z8rO_x=>fSNQ;s)i<`IBFYgJ?0?FoX?~0OjH1o#EyoW?Au}ck>(PUoq%<Q
z^X)8|@)85m+$-s#!W2^n4#p~xCAsT^gU^J;4D`B7!HS^(Cnh4t&l;owOTwNp!|aca
zu^<Ekr1`+u^wr`AC`F*Yd+#tZj;;+i{N&dg?+dal=*E2(Ffj9zMVF#2UEkqTsLX}$
zvB-UiGVbBf`=!HCc|cdGJJEGbI3bCj4twRXu)#sSFNfs;vGW|jlyn|}^h#nni-Z1k
zPkRdm<DK8%^K_t|1c7@mida(bsa+>BJUFWB+kYzvHY<v(rwVLez!n<Gxq>5(vVZ*o
zlW2qY{X34fn+v`Sr&(%}M><<IGF;6ti~DWqTs>wLA5k?IaSgJnn{*RRF@hZ{n?jUS
zNyBTdJvi?<zH#`CoV=wCf(p#+h$kX|sTVga*Du@H^c&xXWXDtfWq6OJbxU~mV8FRi
zaksd6<pVh4D8|;~K!5Zx<Jgbqh52$<i&c?r2Rl(pL#@F8j-Ks7{X)XyFZ<s|x5ebR
z>nS5wp+C%{W6>Yk*f*}~mOW+4o6Vfe5k)%G9GOiP1HG4wfni)`&R>^(gl*ML=elrk
zw%mhfUkDJ0k<yX}tg!ugmL7T9gpnH(3xw)EhBTeHeKO-BBT@t>-JAOvJFy4dNls&-
z(ok(PoORn?NJwxCq<^PsdAw<7)OFsw!LhGuU0wi(Gm(X<Q$Vt{!7F`bE?+oWo(%(6
zmy4}hO{V8Eq2E%}LhRie*-ci0UG?%cvDGQ366;_;Ofa*ryxvdT%>`!HGiCzE86i*t
zRI#yqG|j9|Zs+`T-VPqH*1B_~0&O~d3|rV=3WXlr^{mPfxi>Jz#6=Ol2Azl6OroS&
zj?v``nKnY=03;gipp|N2Yd&vRN`}?*w@&ik{BSgoDZ1vH6u#))!;nEcw6Ps3Z=iU+
zID7OH{Ng~cXJXo4eO8opMchro=mcf=inAj6VqQypQcq%j2x2bfV&s8bJzn#9spR=|
z#~(ZSPQ*GwD2?-T)3twIaNad`oHm~83U=qrC1-DrA9{oLV#3LmJ{Q>^9dd05v>?}u
zD?HH>xs`PdQKMX$iv^2*Q%GQDj-6Vd>()M!ZoeLrRa3Qdh$WsV=I+_i>y@dij!bUY
z%Sltz`X+ui>IARbic1voNfdg}l^~_@$7Xa?-YZk9gY$~^m-4McT(DWIF3=E`gDie(
z=<)e`gy!DXJEo_$p}w6RL<q#twp1s+uGky#BCzug=Y13=e0U2oJ8F^8<IfidH9gSv
z^Sm?o)yD}22Oe(r6esyvt9(}i0mc8<gNZ8Mtpz{ToNr$Sf>!p+0mx%)(A}2;ACfQT
zwx{<(=6xo2I2Gb8)yaB0G5LG3QLiFkmyPu&v1eop-ip5H6vfD9`D&WA*+0)5*%dC;
z3l`)O^D6NDa_|IEdmrJs6F4I}xZ!)*)7aEhxYAT~xH77enySbx^w;Ca61DdSHf?^-
ze|w1Viq-Mn9&7f0Q&ecZj~h%H>D@n()8P5iJ*D!=e?ERgOM#<ge427TW3JF*TEvU!
zZ3m(K(?xZ|fWuQQqR^3m^F1$60khXNV$Un<_#C2M0QPA*ZC~-Rv7%8kxt#N0z3#D$
zxJK+3h_;M<q-q8Ruz`=(mF1N>_dY*L`8z2=NP>I{Jx))<;Iz^L%o%+>-$h$@_!E;1
zEzS#~l+oUsJ87k#u=jvwn|8RS=YVYR$32aRX_~RX{ovc4+RZeeml14M)VW$frJ>l?
zxa8#LyF#gQTBVqzC4A=-yj;Rpp5!n^u7}!Ua+JU9Ei<T&&}!Ic2_Q4q)nC+0HOv04
zFcb&U4@=X!)RpGmld&%JFrC-JiX)*RZhY2=5oKh=sGAqpdU8hV1~O|bMA1j+*6PGc
zIpMuB9g*X~7-QZM4SI-nGeIzAN_tVi<#4wDDUTjSYZbeyGS=rfGCuzy1krI!e|U^2
zZEMqEnvw`uFJx~lPl!k`b7@q^%Wl>Yw+Wv*6WST;72dIPtY(S(v*6$%tMb1JCe*3M
z(#()nfY71<ueN+jazH6u;B2Y6uJv=R8nrgA@{>?u4odhF|9<en74ET3ry)E46L`jj
zCv0jhdMX(L9BQ~d#jXht-9xWkD|@$Yf<UO!8nRsHDGiL796?Cude+TXRPOTmI4W5x
zGH$kL<%PW8R&;`?hu~T0h%?buy546e@tP?=XTOt1SqfzgCV}@6?p6#5;u;Z*jgTCP
zQNVLg!rfAgpFe5(YAwi=NLnILRSW|Tq^l#dh%(diPB|^@4?Kg<1!AGRK96FbR?A5d
zA^8>!Tl06{i+A=Z20YhcqC1)x6M$uVeM(HsXC8g(6?V1K`X2S^fWB$F^t=hBy-|1?
z>T>FwzBO;_9sb(+sj3=KyG!fsgAG=EWE=|k%f=`-ZJAy~*;`(vo0I!O${qw}7Lxs(
z&2}@sv#ivjOb7Xci{=*P=f2f-nGRC;2M5lg>D>+rXLe||3XiJ1qm!oW>5q4Lhus_K
z?dU5Y{^!~dMl>P5Xo%Nc7WOb@@76LlRqWiE^$JVXiJ+>gJ5FtS70%wT`l^PU<lDac
zXTc*b{Lg-I;wca*t2a_IGvCEq$91v)962b8SEO3R6IOu5u1QI0c+=<-lNSkSBslNR
zRioaIrM{pzXtyALw|+haOdOu&a-HnEzO)*=aVEPKg+CtfDHsgwl;Pn3z;1iDUNClh
z)h&EMi6C3vcYm8HgO<nNi|GXpb4)0F*M(Gf>fQIx{w=3{xjpRZEeoSZERzz`cwGpR
zSZ(|5=LVYE4;$JkhoDSL9m2YqZ7n^+I}tdCUE!&znm~&l`w;b-_0II;jG4g6*pX&&
zuiTpA)yD!Um8u!rpLh0$j8(>{)h_oArLC$v5?9ZT$U+A|p-FM;J!EEoElhOE7_C_v
zv@V9(awI$RL9RQ{4k%v1KI2>l6aguZ-7+7E4T=30-v014@F&~%JL-{6@;83Am;rK+
zSjxy|pUg?Ki=8;2C2yRHBDiQ=*VD6)d|_@Z)aMle(mBgE)&mB3hj(TETgf7m=HU{U
zz2c~?D$+S#Q4YGNT?E2>4bLNmi|X5SoO(eujT;n1zXf7_eJ*}a@arOl6<PDdaTD@@
zOq<Jy`)Z9Y4b4#Repp*O|D$wW0s2i#iAqY={mct7FLg0-!@G`_`A<-u_lp`_5_f1L
zqebIEopk#b-&T8rqIxjIX+KQ9M8cT|l5apBmxRbh)j6wfq{3(@K0WgO`87iIXpocs
z$A>sOgr!->MNaLX3wE|f!rjF)j`_BNU|$gPONG&oc^yj;NYBNOst12pgV%a&)mUB;
ze8YQUS{T~rrb|LXP2W(cCqFh_vz5U0cXB8w^}44WN_Zn}az>nM3ej&Z`-TqY(vS@p
zqN_kaY2UaQu3HWcK<%Wf@zs~bBsBzTTK@1cEA0ee#0YoYs5x=G0+#{sQB+NZJ(nFE
zF&4)j3~g`6_(+aFP?IkYyF53mWRi-RR>$j<`i8*YS?}*3y>K$7QmT|5O>bG9iFDif
zD1Gv&N0>hW<`S~1GjTPlv86&{Te8S`PWV3Bmx{RO9yQA;iV{%^u4{<8>LCgB*1TYL
z6tEJL-pC@4wy;V3x_*9ToOc^+BZa?a?zF@z%5j<8>i_W_ZJ?sO9{-VVKIW?-delOz
z-|}3i_%Du%k`~sRf2&I~YVy+Ra>Vf1ojC|_>RyMSl4jeavXi9im5iDw1I(6;V0ht+
z3mu1PQzv3`4&<d$w<n;xZgL~1m;>I(yO@4_(W`K!ug2%N5qu%C8lCd}!5A~}ma8(T
zg6H2ye@lBjBOgB{(ls!Bhx_1#Y;DL)a~`?GGZ26iQkKJ%hb7IJ?2aT4H~seM8Bx>G
zjP%xmFvrv?Gh5&!zi`^rI&ubP?2lfQ$Rjs69|$;lVD`iFZmF4?NNJ33E?5T&`vN3V
z*Pz+`S(jnnyAIt`h9wPiDX+bi2<anq5l|ldc8$*y1Ps&`n?0We9Hm&iOXQQailF=n
zVm}0_`{qr}%9CLC*OHWJ{CNj8<f{QtT#Yy)#`Iv5^!%c^Vsw}XLHieX>7Rg2W#ZO?
zU^WW%GqKu@&P>81%Jx;RYVf*YzcDo={dhV+g5`zxl-jno->VDR-6GYIjc6G^<!JgW
z)2{x&z0+;&r0zQiAI&mj)vRsxT;8IgwC)0enO-A%p||A*MQV;e*f`8HcFQL9kP^kA
zS?Lo>nX?7kN6Bxz%o>9#o(%#3#d&lT_6AwxgM^ZE#Hjr{E?V2^zh8uXROf|c3#4Lz
zLJU-Kp3s@v3C@xVU;p}}P1|p?GQR?GAM7dy@RbVNQ<tC5(9=(b)2iC)IT#C?YRf1)
zqD*RLh0s;qf`J2Fuf!Z}$?CQ%u{aDS6ELruPv(zhUaXm^qG5})6OmJO95k-(XPfYu
zRAxKpPj=?_%R-}7UzdI`vU_zd7VDt-@dM>M5D=E~whWj5Ksz}vRj%IKzdxMS;cj9U
z5(MjbN0~uurzx!_N^IVWkxD`pwY@cr;;%mPg>-u1>_XM9!b;x?h{rhcc>9hK!`jr%
zy2Bul0?UZI(M@~4Fo*J{;5XgRo!_Dh@p`y1qQJE6S0O#_8+$a$_*fN0UepO+F2hFq
ziWi0+pcRC-<l<}6AzU9=(2Y==1DPgd(e^iZgjm3v9~2}#?l$KhAQ<47dc>T-bEiG^
z4yg}SfZp}nk(B-FBml{vUWuVrF0py2gVqexS@JSamE_Tq-YKoG*YP{&c@wcB<0n1l
zdVf(7#kU7%3rw{xTQRv)`j5FrD^j{fNoE#TnL0lhYmqhR_$`kb1hE1U!_Wv1r?T-`
zf8R6@hjOisnx^C42IN_pe+I1q?)cpBZgivf_TiRXD0lw;QbZbAZD}JvJZ9J7Gz=CP
z#<=t0sr>vFe^+ifE_AF`@S6IeNNCaFei<2tBC<z&XD$Ay6SuahdcO7jP&~yE=I&*`
zkaLplUxAgt5V7<5NMr808+E=Y@Y8FPIe1!d<`Tkry%M!j4ZuY#A;GQD$_2Srr8gfp
zhC~#}v%{$Q3R}_@ldhRxLBU#4m9Qb4d=j#A_mLwZL>TRWe1Q)jF4QmaB0?xhR~ZKC
z(9xk;d7rM*n_V$4Yu=is$Msg2z!D2>oap=(BDcH`iJJ~H$z<TmHsMBuUOb;Z(6j#R
zaONymdw-X7a^W;BjDQE6xHtAi3%lL)GmVX^-TX9JgJ@#U0}SJ3t3nF5LKLKQr2AKd
z^w_zIN!Go1FK@@L_i^LVqS6KPqZ;RH?E~)ON@=*$_mLH%qKu;wGYpyv9AZ276m%;b
zB+IQu^JEwsbrfp0V8#Gb!jVRdo>Py*d!@Zqd4cWPxCXBCY`PiQ2dz2iTdhd+E!OmO
z0g?O))g4ruvMKDs*P>wHnhU`qo}n`P9*Sn3A7R8U;OK3z?79^h$+<&o(D){jeT0U-
z&mGI9)hxU@sROE&v@_FLxDP<fycZ>oj47)d%txXK&!f%eD#*@)5Fp<K@(<+2vnSfq
zc^FznSSpR?P@yCM-0yUcipJ}5n)u9z%qM0zpSDgelvqTVy6hABZPt_8^{k0^S(Lxh
z(Bo0L4UAfqkf6z!qC)Lor5h5&?M-XFr7Y<a3QcVVSn_Lc+)sD-SU{X>Z0SU7K5Y(8
zEyL#DDb?AFv5I6rcsG1$SS^=p0k4xQtQ8e0bsjP<fS0{>V}sZS#*6})ELUHamJT1^
zCC{k#-(oF!XE?c8cz7{<Ic8+Ys8N%q^W{PD=nxurB4$ECKh;_?q=@6@Ba9D95-<C*
z$-=b|MLwPVe4mFEFvtha*jNc+Sl!j^!Y?emqqmc%%OtEl(Dvia(4IjjspM^c+&S-n
z!j*PIidz!6K0T*Vym<z!o&6|&`I(uFZ->8)fDut%x+>?l$Z1xI+r6~07<H3e#MGEc
z!+fHZC+474Ix;nz;_`gHD8lm*vzdx+T%+TnNzX>o;+uqp({B0!JE^OX1eb^Ys+X0k
z;oiErYTH)>IO$$Yef@AaU1l~`2DQ<vZx=2XjvpPVmCS93<MSRyRK0A4@1ArGGeJ<I
zBcgkbyX<Ln%LBq^7m!jp5Z~MJxJWWZz4aY_0_WGQM;&60o7-Tz_1>zg5NwcH2A1?1
z_LBjsv-~H^TR(8&CG5qnyJN2H%)uh*cUgNFW@hurE@u!kh_aUyoLm_`(Gm7`btm>>
zr!5tH0WdRvVZ=7aSScZoanFWcfJf5Bir)<?<z0|)w1R&tg!IKb>>7y$q}_0A(;6Sq
ze63{JRJ@z9l)o_RS})$Y&lg?A01dGYyErrXL1T8~rz{b5o3hT8Vm7>~!6lua#@E34
zZRlz-5dgR1(s=5ztC2mFf7Q|$NL6e{TzFu&#OWA~SBb80e+3n~11GEJ)ZgnqIIBEU
zsGJG={r09U2y%?UfZ;n{F;l8vd*T)kA_v~*;i7#|*!uiOgzl;D?vzyozpzhhfX)c-
zqKiuS!Y;W)7|s$%GQ77i%j-~Atm`O{Fp%icJ;t%^?{Blkj5@WNm=??m!%Cwqc+>yB
z#b$YCHFQngC$<ET#97EiB4Xv`X;yu}co4ixD+gR#fRX&9G52C^Co&2nD(+voqG<`y
z4K2tcsAMicvuPOL_$W4#_KKk{BAWTgY_Lb8a0EEC+Y^AfJJXQUupdYDsM{7qvE`ml
zx@C?X7vxkqj4tmJm@R8H0uQ$s>_~?=l&*D&HSKQX_1V<{f4CC8<EVfR0fcL6jV<9}
zSN)6F{9-M2g=7?p>aSI-&}T9f!$90<9GY~MXF&N1s09Bx)4SAY+QD|zRd=k{B@ZBc
z^okxrxZeCD0#CybULBgIqDAq1LIRxKKR2;OTqeLyqacSQw@Jv}e)-AjI<xz#8^w-;
z#@7ofSlf3<k8f7n9X|llX~(@PGoh*vS$l&-dL4h3tZ0Znk~sd$p3Q*6O(&u1BxU1H
zm>j*MEeS)it#cH|?R91vbs|@-Z-u?JH0kid^JLt9WdF&TZ`lN#N=LW+73T$+oM}`c
z(feNBdpr|prMTZvl_?OGkM)0c$zQXM9;b%<6B#{;z4%=*rlUtvlEcJe0YFACf!$5J
z7e69FL;HGSH_oJg9mdW|3b&!pF%W*#vHdYREvTupBk}$<bv96W5$^03t-E!ng0DJq
zfRN8u)2Be8cOc6wY=CHBwwXj|KTLc`bDz)4YLskr__S@H{`Fc52;AB!UAo8vZ|h7Q
zzs3RGNWJ&3-CI^}lQqwpoXalITvFndMK4C$T!WwHoG!jF;F`bu-f;2Lja{$t%Vdq+
zlW^Y-&J@y2-4qq7c);k#YtAE3J;RXljjwL8LUxx)Sp2ohDZf<wHp(n&4!+<^P6gBZ
zvFi|ub0cZu6xTRNAN9?M%5MgsFzBw;!P`2PZ|O+iyl$dh0Ud3Vh<x?$T9PqZ_qEjp
zD0D<<6L<FAA`iRzZGBrz<FsydS$K&>fpRn4Q->5pr~T{nR)V)x?XK$Fw=toB0{~lC
z=5im0y}jF(TK0^7npA*CB<o9!PReFq<b>zN+}~YiJKDi#*LfsGzBm8qKbs(g?S9$#
zX>T&D0DYkn{y|_ceTmq~rs`BK0%Y9UYq4R`S;(<Gs=1b&4Y9a!FTYcx^F2ps>$Q7X
z{b<jNP5#yk*0h6}S&`B*u~OfKB#?(j%{rcWvEMd~-Z#TePQRPk+D3v213}^XfJboP
z)R*|ya)Tl5+po8~*cM2#z1Ca90OTp@R#=3YZ~5rZYo)h_&CJWVf(t#2ak~}muLuCW
zMDn{K7ARWVHpFC}JK@oh)UZ-%sA{`#6F0j(-}eSD<K}YdqVDc}&%Y=o6@t%synprq
zy1K@1?+<&9=~(03Nv_&;!~vp%!6|zq%hC-o@{nW(MFNTK>*{Q%{uy}0tvXfyN=lx)
z#T=Z<RnI>&tLudm*y#_8gjeltaeH)_TN#m|x_*usJgFnMBs=;Ue_DU4{I|u$6cx_+
zc00JfQ`0djgfv-0UKrZaVbwr<I1961bWk#qRqFnLqNY?TuFYdzte~cA@zebm0sDMK
z2?OJ!SM^C*VD=WWxL@7QCg3WcKz{!yJp*(Ra$18`jGfXj;XoOyW4>~NcE$L#wbfN$
zhOFMYq^eYm`F*IT3g%k}K0p+E_l=+9w0ODfRECa_VVZpwz_EuSeQS_XK04WAWci|K
z{kk%ccyKdfRaV_<(2A_NeL01nYCV~lOyZb-q$PyW?YM~5u3?Y=cv&B_oN~#3=^rc^
z<d?o$#?`z2`htdP!8x!3>$}KEh4j?@B?at7)CZT|-u>`s1#jeC(yFhn2*b$=W8NL$
zU~NlnzK-Hyfu&&y57=qj%4wIcg-5kM7_EqQJX52OB9r#}@iBYMzq0(wlb(tj7N$?l
zvXF-Uw~KCd6W#Lj^Pb|=MtF!t>3AN$FPHk3r*4aUoU3EA9#6`!sUgWwX#}2a|DNx4
zt@_zaVXRPkMN*H|4fCN&5iRtcKmvlsWWU|2pAWk<sdmB}ZQJIuzxXl^{EQ|J4yQKS
zR>(H&-#z90X<wzyAs;?u#_|64238H!`VCY}P3?p281KH^x3ICceWc!{E5#gl>-%UB
zIMrUMvIgf)>z;^$UXg)W<~W@B)bYehwf4vx$>i-ZxS4TMSS<<qVxmw$Pup(~H3{H_
zqZu``lq5#V-md2rqc-Twl|&u5Q(4tav(4kFMHj=}lP_1~SxTCHp4KmTD?_2_KL{b(
zMcGuuA4#s+hl3ji6<ENhKH|o77WO!Vmss2OLTrE2!s|)ctENZX49WVBK0h>jWQp$S
zZ#IH&-hO+z4~^hh+t)gna<wuWdCU}{)OJ~Z)0}(#H!X;-j(pcv#bX~NozXSqae`jw
z<88<Ar#c)-=B?XGKZb9}BOJA!Mj7DB=0~*z#YOu=n9RjUdv4SUN>bYnZ*LTrN0MO6
zS5N{vI?Yiwvj-#OHx8pvH&#<auDwD6Zu712PIUPsS9w@Em(a#}Fdu5@lmEH?xk2L|
zKv+=-5==IV9j?<HM5e$%j!9Gbj<%ztirw$wmtv}}NwFAAHGWQ_C96#cqD3qrftWp)
zLZjETpaxPao$hcGPNUR^qV%ddH`dkk25cuKPflXQO)o;QD>CDEi^&S&=Q@x0BDb(L
z+TzO_I<bni(UXv97pvd3ZWqoSTPb3f$pI}H`_XcB&H9Joek4iBqU%;Q?QC0Jm#JLc
zchmt{VJ(PQGCIk?j!?y>p0n}@p`q3%Q}w#|Xim)t!xR|<4eW6OM}iKSq3<?K%6pq+
z3vWY&Tk)_J?&DV0)hH8At~}K9v|aQ4DFso`)O%YeNif*}CqX;+IK?N7VpB8KgX7{X
zwLfb-Uk|2wAd_FAvNKuK?W7%6AWJE<+I29L0s}wh*s2ODdENQ>IHJZ5f27fDTo`M0
zYR0Fe5}?cXFWVOCEG8ojE1bleY?b7>@)+;eZ@d%A=nNF@DzazphtcJPtzPF$B+}w`
zS84fvs<airKXA*I+qt<wD>bldj)$A3I=McmK%}`BResZAux+P6_MY21kI*`L*V-xj
zRnD(2UxbSY13;F%u#!CQD~d+bdXk{K?Tz9;He=|Oxft94-eLULTlr&YfpXw{=&wIp
zEwhF()IRdJ*4?@IChI*i>w!KMbyOF6b6O%`U!ahgI$`Fw6pwU0{$`hSV<KWV(B42s
zkWcrgA}Ttc5ydX=G-}gbF%{L@u!qtKDA%B684pVh8eTIJ>R6}ZvZRCA)@ElHNi#F4
z<@`P1dIeIdHWR%;_93$<9eTLeO<wA`W?HK<`xz-wBOCDOOj5=BJ<&VFR~z)-@!u0V
z!p1^4g9tf;LLMZ}PrmANO+edely4>Rn!B!22J7dhbxF=<dCsjaek6{k5K_MFKCJkK
z>N+3rqLqV4p&#&rAQgJJOo;kzCxa<t-46~T{Lk~Ei<_kiyK$A)S_G@ax+)}0tNXgw
zI$x`dP(J&3Lmzo#oL2a=^SAC_%A;=Hdqd)}FJFWw0Q28_CAQ#6p#UwXK8aoAAw586
zWXLROoH6!03@0Rc4(I~3=c*7^;V@=t9WA&V3WZu4i#1|Kgl#P>bv3lUr5K0f_DS4H
zuA%<1zh!8Cx<-7Ln*n~4q4XwAvHpwXS0%q5Pr4)Y^8;5WJYKUB^Nm)~Sz)ZJ+K;Ga
zQR#ks)L-<6W0{FPOOopgxjLzi`o-7DOu2RD72kJe-q}qzp3>rF)D@seJT$lp+--0b
zid%;ITm@s9AnlN=%E#Q~9?$)QvJ}{19V#>|b3Y?xYhe5R6?3Tmi{SNC=;Sa{3S^xI
zpF5{IVnPOJA?#vyWkGh|DB5_SYh86^hExBxdNce%ypx4#q5JI9AuhI?8dd6DE$_n2
zUxtN25f3}+Oi07$IV){VxHxA_k1Dv3j)`+iVNC|cRb`L&`EI>5KAK@Qc}R(|=084#
zEQOzHK06BIcRSL^EvM=(EfX$*RY(^V79N~t%Zb3<IwQsXTZ|eV<ajNBNyHuI$?-U{
zI(Dz_Bu|4Yua+_MSe>MOMu6Y6XxdVngrqC0R@$!+h@Ixg;M0{t3e=4;?=5xx9c<(I
zp2!vJ6cFjcg|u%AscRS~zXGB+_v&5iQyVA6ndw(uzfCiwOgswh`<OR#FPpzfQ_iCH
zg6{2azRlsiN9@tA?{)GDSx)8Fy%EMwy!n!!hv&ik+vNvxfUs)lW~h{jPL>99<~Tk^
z%iB``AYGMpzqYRzYv^kB%dZUdKKS{oyPwmFr5e;sEB(xO-H7ljR6iPz@9uK_qC%vQ
zuW1}8%!c^sm|bT~{Y;-zzbe*=qU!^vB6Tr`^z*83AqN6bguaU@Pij$|oW>g3y6VS@
z($l*Gq!!%n&Erq6e6l%`@N7u2(XRx@{@o`r+Sa`rwxd6~#&U>zs_g93MmuExK(i+&
z#mdeu{OKi71=`|Gsnh=eqf8DUHtm31>qPSww0_3S73}<@c&Z_lzHJ=R4~c)u^dp1r
z^y)k}7_0gf=_lcb<#ZiklYi;N*TUpto`e-Ny}E0pu<K@r?mtv~bzcdZt#2+9{+^$b
z^wsrEYuCQ?kgNCHBs{MZn{k_V`u;ZMd|UNPB!6EePQ;N0WF(yfrm_2dkC1f^^g0$6
zhBDsfp|K?!K^6e~p-cXRIQzqV+zh;8Xmb>s#*ozP(qftkb^krVAeB7R5H@*5|C3v%
zirwNvo}!Pc6n)dh)`fTQ!FoXKO%OzhRYeC;bh*PgOp0^0uSC2`Jmg?|e!B%GS6TUN
z%LAeBBuY#`*E;dDS&4vuv*ptG|0C+HqoV%4?_pF>QgRqdkdC26LP`dPR7zmz0R{!>
z?ogyVr9n!NPHB)4h6X|D5{B-fn`iLzdw-w*SPOLB*SY)bQ~TcA65aKH>M#nXbY`Yn
zl$#<T69619YOm17oFT%<J~t=%%f5a+zkNrgG&rcVv#?P3h+&#BrT}vf=nopqmF7jJ
z<22VB`(>C!bR!9)%cfE8OU|R_%Y7)q4sDYsz`MRYqW3jD!0Hdi(l-Cn4xyd4_%rsr
zYJGGn)kas1ZjO6+Z4DFIu>gPBK}Pp<I^q|@RRREqZRKXhFq46dt*HVcZEg|us>xiu
zF1pO5=8~>iPpC0Vg`iHF`$o(MTD;joGjssu91_u=!2Jg=ujeHswrVw8e~5Tw_9A)H
zOTfRIz<X*qEUpgPVpkA`e(^eTVyj4)lYZDrw!2o?CPl-dyLL9#eTqKaAfdQo*wPAM
z#}+1kusJVUu)FIB$<5NNAw53%{@%P+DGNF%jlshgEsRwAxm{n(W<|H%IP~jjF-U@W
z_(j@2nU&)krzp%Bzr3N9trh6;h*0ItveVrW8A{d!4cmE%uj)O&pRx0lnn!;9N`{$m
zy^;NikriTi6KgB+c->N?gqMg6dq-bGYa&9$xP7}3(xlC8trRB)k093KrVQpNFX>tW
zqLRnPnEq~LriszI^qw00jqL(3Mwzj3x5j{)B?p>+d#(+h4)>oJXkq0|vVvEsy;tVw
zPU3y}8p@bHQ77L#9sa$;lo?&LX4C97WEYFNu(HqAz@(&2&1`_E6~N<5{1C|`1JUh`
zA05W7?rMD!*Le0;ufFBM<<*|-jeaA~Jg^<SI>PwRTS0N-qdI;4Kw^x@yqm}~Tu#E%
zQvuVxR^;Z><4nLS306(Vz}Y0p<M+aw#oOxBRgL&}7QU-{@^ZTdJJx$vbzTWgIQm#s
zxOkB-C%L~bR!*YsJ%qy_?h#H-{>>ARnv|lKI3s+Ad<Kt{oKJDK8U9h(YZmvCEMA}I
zc;0ACMcZ{pJ2lB$zB5yrsV%g*#r@o@x2NYyGDM#GwC%L@^wO-iuSKox6xmMus(O?A
z>+X5?r(TG>a%wRkj|_B?#04I^?+xI3s58doL}!!gvr&b*vR<NdWmO&5&6HN#Hc6R0
zn*^~5sS+GO_=TD6h2&4;+2{6*KTQ>4adVfUCaVC3t=|L1LC>ft>-5RhT2Rk3#Jo$G
z^-})0b9vkZJrnicUDj=f<1z-4j7pbU%3ywo6pQi#&>mZ@p;wX1xKP=<-+@DAob&1)
zP>JtFZ|j)_$Qh4?(?=6%gxx4cZ#S4Hh5O{>GNk4{6DHGL&HNo>#ecK+YZfleqB+Js
z@T*he1v_k8jLTUfR3KUX8j-E64;`vv_DceS*woPoae0;zh7z}&d!^jNCU1Kbg1LFh
zQ6t^FOOt4E8SMh$kxpjf_OPI!*Al0*dN%gX5kVwiT(P2k*ged${;ds{(OlG$X#Mp|
zqP>ckUK0TkseU@Vcxatjr5WVA4<mMPu_&SPkIIYt0M3IF{pDWr>pn7+-c+u4h*$fK
z;6!>#mxq7Pn*yCw$9zRWDVM8IN`!OtlQ^6xyLz8LiazvDc78vhR+cjBq!THEZgt8%
zh><*b82tqH8mVJVH0!+QYP0ue|H|1SD4gkTNn*I_wNL;5waLngOnl*@;5iXob$ffx
zEMtyl<S@pLzE7Q~J5r%FQlmbS_bRSNyTw48r*EiEWW6vRN4+==;{Dyjh6z^66dWD(
z8W%9nb<G9PTp=LZX>lRf45C8mv?zuF19VO6xJrf}+dmOlY9G2x=2gwmMJ_ULO`-9B
zOx4sopb?~{glG=(J2Pz?ap=cZ6&BMp_&ZTsuzl8e;PBq!-r9F!xB)Z)j(4}mcg7Sn
zPdlfDnx9ey8Valz13a(gBjfASx{4`N9djmCo1bdsm*@x9`#&-oV***IY6MpmS;a9b
zvG6kUs7@XhD9zO?Mt>+Jr{qU;hb@=&*JL$0PKSl9D$|kYM&A4oU|zgJGs~NA<cjkG
zaZDT?$;Yf}Iyp?NoM@jto1x%Q9Ol5`=C%9V6DOXMIfFn>Q`pUBboccUx>VnP%orG}
zAv+Qf`TY6V4`PN(p*Bx6PDYmQ$5H$V8t1beapJ!WM!pQfLa?R(Y~RB%5>+Q~1v<Z0
zQjAy6yoK&6#<mm#uEPP-R*Fbm&%RFAX%zxMYd?jU0b&s!FX!uxT$rQB@H-{4kq<8|
zdfa<b)MO!WGqC_T^L_any4F6REhm^jphF_gZ{>(!j2AH`7}%2QVj2xX+x_YqKs}|7
zyZ)g0!^nN^$IQGNUQNvm1SBlXwvQkvL?eTke+~92PAK9svOIRr>75kJNjtmA%kIdQ
zzSywK8x_?s=yHGJM}tpuyFPtcIiEo_$MoN>#D0pNr#i-eEVPP5+4TeR0H6aoJf-4w
zND-BXHUX<7or!kDHl4TQ@5Wh22F8F<S-U(BYqL{O+54Wd>JK?dl{aJuL5UMFhnQ=K
zx}%o0TX0V>t2aY64SScn#JRVGK6E%7m!LVeE*hr+2M!>S6uYyjebMZl%SRgq9^K-`
z?p)t22L^0VJNEt$qTb;E`RJ&pE--M(&#{z2#>4AeeI{}W(QDBXfXMUjvcowa@o!cJ
z*&R$R-UFcu|IbGQWAD%D(jJpNrekcp|8ie9w$^YFm+WVeejKCD(VMc|NG;Oocph2?
zy0tJ0U#&V^B(Z$_q{<kN%jNAUpI#?O?F@~`=!<f6vZ|N<zU%QMa@*tE1!Vv1V<HJ@
z7@khcJ}cE_6EgtRVg;;XmVd}+WZ2#oT6e6(&AZzFF`4%X68R89pc!pd_VLkfdvJZr
zit>I#npIs`H-q<sLuUhzm6e1d5#6Z(67UHV1y9eUK*8qO#+zFJO!Abgn9Ij*KCu|p
z{Mes9=Cx4=vC$P}sSumHW72<E!@Y+kG_KGZ@IXc@u_qQ}7Vz^|u@0eP={l^KDpH+v
zCR9y{SS<Y}ugL1-Nrtz~cT3w+Vk_43Qvq0?gA>x2WQt6_oJFG+-+J&fpU*c$1zkKP
z-*%<q^9ZeWr#)!VG{k;1NKF2Lr4Yru2a1Z`_vpUXdIM$1*cj*fmmY9vj3&+Lf<KYH
z_YA8R7kXmqkJb}n$s@M3*FjKYsW3K}bs$Og+84}b;p0R}`>scvO`kjKp#fNGL&ivA
zx^p4F-D&8TDt13^mj6EJ@#8dw5W=L`BYv(%CQen4B)Sa0vxayuzx=?HVL&)RmlwM4
zy83E_>DzhVDrfpL_fd^&owA02ah0aqElz_$CWXG9{tX>_5(ZsU#(T^X+3h;$P?FP0
zQl74r<vtR=+FuJBgJo`U-kpkVE+el;23>cP$QwM+BtsdEQQo_aAG^95ICRT)yYgIn
zjNiTUdSvgtm9EsA`;s&25kpI4zdb!7b8LgLBANuOsCP$gW^L6`6&e0{M-8V##)!D-
z7v*DX!IfP9g@{0GQ%J-|@_5z(uE&gx;N8QO@FS|m;lT}^vRHF$f1hFoy)iDQg7Da<
zq?BCBbfodRYP*xXtR*VA+Ol2>er+LP_3!7`mdoJ0eOfg=Wx1ro)Z_vZsZ2*d(sDZ;
znZy(VIT(5KHiNv4cIzxT3i*S+M^odi&GT%4Jx^V&o$s#=XZ|>MX0L3hjc(p+``EnO
z6xQ3@l$0~2rE8pp!}wOz#|1E^-=JLIi3u<v#1)#D7!oUq3n38Hc~$g~5_55D_n>yY
zz&9FMUDE%^8f>=C28oa%Nd{e=?54={0i0IC{7Q7pkJ&rJ={_=3taagQOK5sF`?e}k
zSq>*fa`LDW?oGy+;sbR61SM~=8u)%Kn`x3kq9aNBNohga9kD9}jTaF8&$wOZ+I*Ug
zf|oVLMxD#CH!;8szb6$=Rn-!oEI#icYli28eizy=&U;s&CP&1vK7f*w9V}e&0~1Yi
z$7kqqN(xE9J@bLNIMg8Fw1fs@K70IyqG6LVF|j}Z>3<u-f)9yk!|fyE`b8g}JpG6j
z%2KQosZ-jM#MSrYTtm1G0`}_p%+c3R{waxR^t5$hU@qfRSvP6C1p=L_rYwh4WB@V6
z5JlAl;%{_i#PW6K$+a{XcSdNf5avkNOb2;)hR(h5dAF<reAj&5^edB<)6%w9<f96Z
z7&Y3(j0rEuIA(W;ooO<fV=i3IpJfKlWfMAKF~Vg4yNXILd`!TE{6m%O#J)9%cySA8
z%=vt`ey;@wL_~x9&q;d9e;d*s<0GRzj>B(O!bjoxZKK*Cgm0P8^%HicE)Pf2Z)UMz
zNNq91%$divMRDj#s@Z*6fzP?qnu&0=qT#24;&SAxxL5(N&-`E%n7Q`XPCw8Sz%$w%
z)vy#aPTd`feF?`fwKahXu(3M=dnO`e+71Rw|8X&`L4r|Ll>BaR^Ce}Et}u^jbo9Mf
z;_hK{7wZ45996HgXMg)s;`UJ)OwSK{(CFMT{{Iptwx*77%EtU+=owh<-6d}iV5LOI
zvc!?ZtcyQCe3H$BU+oC0zF|f2v)C#wTRgc#k>nsPSfe-BBT<~KHCV^+RX&#1HV$bl
z|I*<l9DxW1!5Xv~mNWd?YCTM~b4D~@z4}I4{0ciiV*ikugoAD)7vvE*{@3r9>r5FJ
zFtbOny@2gerhHxi?F3LcjI#c-MODquO->9+0q-J8^w)AT1t|ZwgW+fC-~M>I{1-t;
z1n<{=wIqdGj)8*Nphr4&h?cBB8Jg|s3lW^0I)wSf5Qkd{UYXANy+fSvkJ@#U3I6GS
zP~)yHll;Yc%ga$c6gj{+Xi$!&DlQ;QcVjY6b@pi&fe7YVZBp^}Um`Cza%Z;t$r!_O
z56>xzoJ@z5HUc`;v8?K@e2K7%icYL!_;|s%Q_h(54jzKJy!C=^H?5~eN+gY3*Y;o%
zV_PiY6PEw90RQt*a~2^H^^2DW4_=;c0?rja5o(r);*nfym949klCZ=JVsemsi^+CJ
zp|K`v^9${3W16vV6K<SO5l`K)9#smmL)@Md6jFUML_bYzPA;Yhdya!cs8obInBXiI
zO1ef%)nSN+zr6A+h0D7r&njvmdSZDy;YzcHeJw+TN<T07;YkFev@}01E`-wb>#)PM
zS{{y%f924_xF>xO#y!P_D5Sn$V6|QDuW2Y<5y;9eqO4ENO7x}*#{SPwJHcC@Z8S2U
z94nt-cLf_(jDb4wsZyOFLbq7U;Vxt04HR*dpizVzOfx7R4%cSu)9Fx*B41P49$VYO
zbF6xMMCiso@|pX<&P;P)KkcIE9jQ-UZ$-8TPGr0$gr%IBv%&tQwMR=XM5{%8$m0oZ
z`Z|FkFh{^_h49dfXM-uR&@hQ$H-<dfdSbPzO6p@{<Bs|E_z8Boq26?mHfEI@IN_A$
z+~*7S5@GeK#y`E+c;!)93lhQpUe}Uw3?cvJP$YsjwZ<Wc4gimw*!}eiuORiY9G5J{
zen6EYhE>pDBF$0~zh@M&TmjlVo#VzaxV_|@qwRz7B?-%dvkRYBZ1{-nalZ3w)Fv|C
z<YSlUC6Wo4S>s0$gp&2eXh!=mGO#kWt};7)VrLB;XC0*IvDa><DtB4LCo#I07poHK
zwq_Z(T!&q3nBthoi;GoSp|&_>vD<;N_kZ&2ndy|7Gn@?Ov1(^yv#;oa!C1+*^@!QK
z;_#_dF5&Mqx(gicyMU<~!*agA?0o(t3$AAo9t*S9DVnaOBJ3mB{IDq*BPcpG>h~G6
zKI=zg+0Q&<-v5Gx)0dGb*CO9*0}g5>H~y}`L@LJrk*@oUcPvP*QRW=}!q+(K$Y<9z
zOd#wkhYD*+iSTWH_(6AIL;CMVR3Msqx%=zh!mdDutp%*Qr@7DkIRP;mva%c=Mioy+
zF%wVRwbl!4g|_12KHepecxs&Z;$5eNvP`qHf_c>FD1;+<B+Ic@v86Aln(IT#=))ia
zr}I9tabfz-IroJhqoZD@+9Q6Rb8V6l5%zRleSIBCT6m1+bd$-_OR8$x=$liz?t1@g
zJv!rzADMM8{Epq{J1eel0HtLU3at`?PkFbw7a5Fw8E%HB6H?0lRLy39-#{ITs-ta<
zx{@v=Kp3$9KmPFkxH??~tt_EPxBYDX>w^4!UV9+_NF2>YGH5`eu~A>_fa{HU1S!`@
zHVs2WZz5NGfZWvCew+6<&jY0U;d0mUvu<8i>L0r`e0oRmq6I&e$Jt|HBui)9_n3vU
zK~J#F3Pj}P$0DkiAnYNG)Sbvj1%xX{?-wUyCcVOau9bm0NdyMvp=-Z>Jz0~*JN<;{
zl99JIdF%Obn0sOD;-)xiA{F050~1<K=q^=jQ_{;8yW4JU&*r5aW5#aotnjF9ThMPQ
z+lRD%Z#&Y`)tt((WLPf-O2b_M`HvyDIUj$pG_}K04uB|IlCVAkSQ2;roNRjY@nk@v
ztgf&-6qTzDx&VNDWI7h4KeGmB7&>K;Z-s#vM+G4^HZAS1ctxH<UrfEdFbw3@OVP%2
z>R#P-2sY*vW0K#7B=VWy%9xe1z$~%)d=Cj<wtPTS|2b!>nTFI3pGov3@wWJ6CV$$^
zf3}9FQ?#Bh0#n=I0*=3!7GIap32d<3X-PXb!z49Trm!$d=bGnNKeAhh7tm4eVb`!*
z0K4PHG@IW|GVH6(T@&Jeo5sYiVGxp*mT-H~s6Zk7=(BYNX(Ag__a`|>NY*lbo>5Yy
zdqv@+MyAQa@Y{`?B}hoEZXC2M_t7`Amtcs8xYRHYE)sW1PI_-zlF{HOlv|HNvP0F>
z#&Cdx-Ml9pY-!Lsmds}oitea;izL!*S;wW%oS`XkBmK;BB?6Zo4XSRgqg;BU&AV+K
z25tOXbywc^_`O{SrR<J*wb<?V*Y<3@Lj05RU*Ns5V#KNMrLU;B(?jXQh+)*R%2soW
zG6s3(XIk3iZ;C&j_X+FJyqO$-E~L=P@eh%L!mkFi5OL@52ZN2}&&N-vb~VaP;^LpY
z;$)-~*KI^>Z7G%G;*xRks3q?1$&_;VYAJr!(zwx$bAXwZR?!;Cf9Q!xT8Kq)7zDCL
z7?-p0ymPr9Xpq8Zwv124d5;;|wqCXg(L*DKNn@W35J#%M#XG%zJFis3r`CiU<2Y_H
zud>tKugyDPEwGaD!Emwcr>Krx$lAYeoPP%krF@eBxauU9inKrfn_7Bi@3EjXF#Km<
zR{B~G<9Z=2FYZ3>)Wdx9MceJV#r{puVT!hRgGP4Ot@j$^)zUFv*C2AcDEWWo-(wEI
zcDA$|8XND+DM}`BE{n##4pcA6Bj>TBY_&I(o}_Z_Tjgk%Jt-|z#RM&;DpeQ2jboxu
zD8|=}c8upi#6w05+<YX`>w4*1HL62N_0#o6p0dxUbzfrc?hn=M!s?9pqRV*HJjVM1
z#!_r#t^|A`Auq+1KUW^<#;(wW8L~px|4a|A4HgwG8i@xH+^wCjhEFb{o8GYVvTfP&
zn}C{BOW<i63RmhP1R7F%S2viuH`*Tv-=L>pKU>NBGusu#^$ogD>HY96tV+%{K(J4=
zu6>kuNS$ieN<<uK;iMb97HS=25L7<-WT~N38LCXKY}x;0Z>J;}WD?rQtdQ0NKUfaW
zmmu8&@#x@ohj}muGioPNa4GjtaO!<2y@~}g++@%_nquPB%ddDz&$mD>E?hd(DMzUC
z6?gtZ;+|~z=clE^NqjC(d6}W@OORA6V534Lb^(EN<zpj@+}55rqZNd1p2kXUG8|It
z=B(Lp*M~Y`x&+rYZ2jSW%=h{;%`*{$pAXyz7xQHG$uVwLZNO20{@iPD_6<|&o~rVC
zOZ!2we0C6^$x*=7H3$}E5S2Q@op|St%re?(qCS>S*i}nS%yOf}K{X9WtBjc5m($Ip
zJ9m)|#r$O_sn6l18mcpnbGD&13U)o$e|9}=tdLiw#_Keo0q52y1XuFo;3!2aDgoyl
zsjD=bpF(TtiPg$O!-0J}YGLH9VSrIL56k9izI(DBlKF@3YhkBr%j>JX5rgSAeEpO(
z{A!W7a*3>`;cpt>c!J0H4{!+IXI1)`wsW>%9?B;0H-0Z=D=pj^@tHf8QRhcF=5+Qk
zhmr3205F`@h=ogwV&{nkQ+pr8f@i8bT>YPUka50@`a<b6O=07zn!8kG=My}4M#F(g
z`#+ZU+=Pqj6Wty(;YShkwS_7aRxF0_`8+e8ld6pX-POuHMJXwkf8#><mgX-j^k(kc
zd+xvXStL09yE#@6S7xg|@JbsEY}?{FTio-DI1Z^>IB~T=Gx%NK_uE{{?ow?PYr?@?
z7YHef$(%$flf_rYvcBeMmSk1XwapSz&-DtzuO(J54`sk(>g8;N|GxG#3*weOqMN8u
zkNeE2$t3?`NG%0O>kr?BOy$-vJ~1@(8k-}s5pgzeQ}nAygH%cje=q$I2ZAM5criu*
zNk7VlhiNtMA9gz>C-Z{ILUe*7bC?xEJ$6<fd19QT{p3#-)5q^iLAyqL|IbI%!LKKq
zTh2DQ=3CnItOgD;Ur60v9mML$VK{pGv4S=289JezJc;|&ZgxvhyVnwNrS2U4LEjyN
z3tAOxM?G5bqCTDVo}0l>O`kzx8qmQ7T}1W_<{2qj#Y;17H-vtF)#lcW6w1Et7q&0*
z`s^{ZKdN~)Ho_h2LX{j&S$vpncRS%%D)c3?o8x;UlWp-ej6Ipt*3v)PtYs8A=}|iQ
zb^11}ih5^<PhV^azU|Gn{ATXf<hW66uFB8f!pG5fT(Ym9u^W3Sd~Nn>nACpM6TVg1
zeSXT$uhVtoJdt(?v$4&welq9pxfKR`Ryq-P=oNnhN^L)_3o0Ko26di#^iH^QBYh>q
zvR%dYL{77sPqpYH6k&z0>p<5<zq|yeGf(Rn7<xytXh+bi7Wo46x+0xh?lbvov(a~9
ztjBT^2;edHgag`dQ@75_i5D^@S5uQeql18)`WUyOwr_L0k%*ocSB~-=9@uJdKVWOC
zbhJ_|`A5V>sTrlHI0fFt@@Bg)nsK+Qj_=+*+VeUUlenCvHf(dDLY*YX{eGi;HOJtG
z?SFM`!7s@gK~a~6fL+=%AY@O6Q4BW`Ku71)>W!iz6Y`h6PWjD>?s<LlihFed5FNw9
zR-a@1=0TW+M98o5?W-Km1Ya(H!xKlwd0)JkWV0(_Q@Ef*ZTRfCiYxwkn-?k|vz37$
zo+15)m%oo_Zg&CQy>1Z{XGN(q{e$ks8J1fe!7ZS;RDtZHSXA-zIV(I&QoS~?*#=z^
zF~$_M>CAehvSRQqF5=PYfefbt0`FIrM7zg;3ASa0MlRrV^RwOOfNa}hawhGcBs1aR
zbkl~fPmN<{+E*}migmQW1f{58B*?z>GtD95TzqogbVD6OOsGLg@_LoqVy~*EsGmtr
zNnie<PwJKGIC_X3*46uFLz*`weWo)3gT6u#4W@fJ6*NW^Jhj2)clC$?>Fx)=Am)8%
zQG6CnJQr1Pj(63gkOj``wGAElqM<=+x!I_}*O^;t!iY!kwUi_x;ox4mi3T`j{nRq{
zUN7KnG<Gi;-vtFIUVuvk3R1Nrw)M48q%yO}3XKDz{E<YOu~b1eiwtw55!<ZL)DnC;
zf+c;G4n|Kwh~ke}IXv;Gr{bY+g1f?vI|=xZ>CB93x_+|$qmaTmGAeMj-24br^(HEm
zYVIRq+V?#|LMQ){UzqrR&RJ2#hj|Mlr6_6UU2#$*`#-9$r}<sRaHD+_Gm<{YC4AIL
z0=>%(V>O(vI`LIA411%qF?7}OsN(OSO2~*!^ub=zVdHJNn9tdDVGSzje%lR5b!qVt
z<^Dkb`DrjAWx>R~ZK4q-HeI>5_}_RKbwfu3t174{IKiVqx~;i^E;$c*po$Y5r(t5B
z%z|pC40!$ZzA+u)>B|4WS`vh8z7d{X@YasFI=jjSxucpP#(;<b7cJe%P^}scv5*vy
z3W7s#5FD9oR`-j$7x;jT4|{`2Y#yLAAoA;JJ^`A(|8Qm^3ATdps&i|>n^R>}A)lLo
zLK}W%zGrr%;Jy1W$)9bcJXxNeIIqhzdPNO&toMPSfAq}&YX(YtT@ed}$)BV+&nWC)
z42|9ygPKD59(mo1uNL2{8pXmgGt;h{<-xe5qJBrJoOt9|t82mnBF#bKCBJ3$$4or8
zS`S5Q)m7=rbO2dC%Ow5`{NQ3;$b)W$riU7pB*LhKr9iG}Cmg(QUJy_=HEkkq;3j}m
z=BE`yjv?a-&Pw<IN)CKIWd<qN($FdDDS1UoCgOx#?K0P?qx!%jK)9HjVX_z<&k)S{
zOyx@&gauk82r1-aF-;`lzl!o`JO~054t&4qByfheD~@fbX*E|Om3=?O@(y@s@EG9=
zJ{Z;JJ%|Cs1xA%W9hJmqRcqKUAi)RTv5sA(y<Ehwv_Eb8IlAO5xI!W|^7;?ZZpmHB
z*A}RAhY7-DV14vbUJ3DESpvSdG3Qa@#7licSO08;O%Rdpah4My>gh!dC>XKfGHh)M
zT+0%V5O+tynG;C_X^QKNqkI2IM$-}{Dcc)(i}`2B1S>$wqHXFGD7dkfwJZ6BXOdb+
z015P^!YbT73C!WgE1lsx#pW%4cuU2fvrQIWwcT{#>jm~Cv3ezQje;SszAE~X^<Lw7
zGNDjBd*qe%A{$SojJ(OY?=xfDGkU@@F)y9|>C-&r6`n8K{2Mc(<B0#Bm(#yAK9KZx
zhzIEoRK7hr0#Mb`st7#MVBB$2F$?WV&z2O(VWij!r7(IU+c2bPu%;UqnqsO<MY<SJ
zjdK^HJWir49WBbDW3CX+DQTsDjba#(SEc^%x6+Ax&;@U=GH=hR4cqIU2WXRFnC6p(
zL9+PcEw@j!wU}Nf__+XV>aN%<6boB@=@&(3;r5PT?_$(BC3|80%C1avMAUUt_-kQ3
zdTLne!`RrjoQh8*f?2aok`d1=>>esl^lxv!`a4ABTQ1?h``B(_ic@<mcjVVu9^X9O
zQn4a_&=~0;L8M%zI$G5Jan0aV-m9qk=`s2^P~t4~D^2i3Hm6R0LAYYZL<$LiV9R1#
zi=(msQw>pn4;9zR+xQ(;|Gj{qbjDfQp(j2$eW|&E!4<oTf-wup>?XSQP68}%iucE#
z_7Gvbj=Ksx<y&?e#~NlnM7Y7ESC@O{uvgd@^ckMe9d5ZZ=UqV)JoPn_y)&Izt%3jF
zuvm}^W4L=*zzUnc6;}gm=phB-#hlAk4SUO3y%M<J*Wlh>eB;*2U^Ra<r5&$*jMuk2
zRQ{NJ|M}9bt*k^=ACK`e0{=s|1uv?ZSURevPP`~Dpio40abea=y!=myHb5Tk=SL7D
z<#vyNfYz)tM|R8Os7hpi`<c6`>nr6ea<E%+2{hSZp>={^I{Ws~Lm)4mOrDg~t-Pqe
zDUtu#A0nUi5>*VW%cNVvfiT)ZdFl5WQ*TFdfgK2Pn&79p*aczq#ZW@o^3X66(?*1(
zCTm88R{N%H3k9ma!>c^k(agZ`M`#rKB9O&tUQRoL@L<W^9rRuLJP+pD**<RhJYwDD
zh0~Vc+wf8W&0_)u-Ctlsev4osQWCx<Pn;_7fPEi6(xQ)}fZ*^!cN}lLHg6)S!KyCl
z+gi^FDbdATP~iX4&)|+WGR);7p01A=F8@6D*?uEIb7!fJzX@9w=)nj+lVVLZWVs0Y
ze(G^eGiIED%-)l@61v%}QZp%U`u*N}ZyU#F?h15PC2~vE*5GOO<C#^4sN<tOpEb`{
zue%n83sreBJ$h}Q%{TTPQM3dnd*pbGkFx6OI7`ci%p)lEL9<QI#h0~-K1Y>3G#2$Q
zOteH}LaU|l`A0G3;${~8K<o%R*lj=%hc!pd>v*>N=S%?*%@htET}ulaE~!~#`Esft
zT}GrRI80h~h_yaBayXuoNt>s7_3;{4y1NgR`tykRLrlM{NZmgxFsD_)&Rf52J(x2`
zoLjqLG?3zVm<w!ndV@Hc_=p+-7Rhf;lh^?3(FcsSU74<i)APjZtssgGNhNhyMs*Cm
zzr2u_MnEj+{ulo^w#7#<<2qb1%d6e#>$BE6Z}i6?D2ce7xyr=8ipWBkia0^@cVRFx
z4o?UTIIKX0MBl`*>QT&!xYGLX9Vwub`Fxl$?V}vAFP_$QZ1nzDV9n}vq{#jx9Jv2Y
zO)4~M@M`otF!oxlU{tOy?RMkO1&()PUeC$>Vokde2RAPtF1KxHu&;|EUjU?}4BC<V
zB!PnazHRiEr-PtqJ|3v(4#La%kWis~9a<V26lSUj=$*`erJ<T1dwE%56(=n}8So^i
zfN>YQ5J;BHz1%rsMak;yDW<GKHQEyI6Bq5;MeuDiD80}E4NljTb@wTq4jL<rY||VK
z`fVqM)8<2x#4#Y^n%@U8wBnyBXdGCpj+JYgpaZaT7~U0Z-uJ`r%F~{dn$eWbVZ&>y
zQlY~A#UP+SPTH?^%v;#^bnR3ZlkFux!kW&pX_(IksTffmm?`HlohSZ+`<b(-)(i!l
zLWn-ADHztWCXL!Nx}mx1n4bFxyG=&*#62Gv?(Yr?)HT%aUK)KNES!9il}%FZZ#iBv
zIhipKy)ad7>TG@GC%KQo)352dS4rO{o)5KFA@N@_e+?Ix?G@JvfUKgQzWwKgm6r%7
zh{vmZHEOX3hmDQZ7ndX;<?bXBE;9xVKiD1_M6*w^+>@A@SLo&=FFyG=$@%VD4^L|^
zRnD>7f-Yvj$fM<Q=nj7th^Nq28HDXGrI+zx%*yY^4Qars@YLwYqgIi<-Kw8pIttMF
zsHWB0AhbJN5fQAH^k6!Qw$>p>|2Epm>`aXnV>Xs-^yO>J0Eh%EF+ZEyz2JBF>8#Nj
z7TnC9Ts2m@c$~>PEA2?DJ=S@c-d&k<4%`dOKYJ6B)d72P!uhILUhpI<Z04+IBW8)u
z=!`#WPGbIawx-6D_2xCjht$-awl%iEZ9bt7BF56;H5PVX^k3gLT_K}9XZ2F4Zx9a$
z>~A}?B`*8$>Af8Us4r(50aqss#&bd1aa4f1&o_B{WT9k%HDS`PI+%oqthbImVm}x%
zBAcvrR%yt{AVsZ-h60ntfZiLzDl;lgh+Ym8>zn-VYk4SbZr+%qhSr818knnk3W@Qv
z5th`$#s^pDta^-fj~54_o!+wf$4Z_*9cj9}xnM1^Yh=rKhl4DNzz#<{*jE?Ra2n%g
z!D-33jwBH}(w~iwHOl$Nd7pro@PHjvvOwN&>s*JszTFW%<X>}z!Ldv##QL~#2vtbS
zuFyaOMn-&7e&E0P%ULfT($PE3B~`n>^inQjFzP@s@nK~b93wNjFJeEq*p)o=mxtJ}
zV>#c4CGMfa)+(K`2U=+J7%l$7+`BL=`>N4mzus@%v;}3Wl2UX&@ypWEXAu*qKf!$N
zP1t<~PWOCy|1#(C+*(DRTq>hVCI7TMi>{*MI33a~1lr2v(;4EDAC}JkxxX#gV=P=F
z3~;Rs@B~BJUXfC8dc|@qH=Mb>uLwX|ZnzWZwrz1yk;QV<QgM?Q*jw7jC93aw_4fkj
zs(zC2EsG6olFX^Yf*lSod>J>GSghoxpTu><oX+fQ@pqBRl*f*%CwBdMmq?ivv;V@I
zoHr4jksn0BGk`%@APK`i&&2$Mb*K9X({HRn0fgqIo~5+Mws|_!8yGx)^}3ffmuze6
zjjl0$dpnptkdR?c%j3KtL02!Uqc@=+lVfzAxDlnNlj|DJ%GG>xxJKURH5469Sg(V6
zY@W}Y#oeMgeO8j`ev;c8AjaLu*Z4{oZ<^QCOSoE&rnzpm*ee!C$D9<N#hF%r^7DJL
z5>CR{k$ZW}fsupi#1`OLlvcw(F+tWqr&66}<U0X|q?Ce)++YxtWd$#9csOZ&xQB0W
z<UN5h;J`P0(15p1@@t?XX`(>9qi25iPC?oDnU$m|6V>w%=RPPfiNFC1q4(TLiH4W0
z7Xe-mP)su@iT%42Dhj3Z5_gz9o(gL#lr)pxLK#?AF-Xj7OBm5lX58#h8=AWCSu%sJ
zkA#7n6hg)sY0W7GB1Z&`jVC*dL~&+;{H35zM=~!flcnxqj2YXC{SSQ@*ToWYVcp+4
z7Zq=M5qn<0rJW(|f1g;|htqo?sb58RA%(8z3PbE6<M_~W?!~^O0u8>mMTTwP!*0*E
zfcp&o*NCEIuwao10a0Qywq(bB65-?1U=vb<gsJh?=vq2bx@;0|r)B)+ihRQyGkD+e
zz13qv)lzl85Dw)|XIB)ss>6fzxC=SuT(CM2p<<tK!u5VzYSFqkfqS|62|X~DgXw&m
z*R<vP{aokOK>!I`A~~wyIV3=l{ypz$)QXl{Y&Su?9Q&X3{#ah{c`e#=I$mZeK6uWK
ze!_GJG{~t{&d-8_@xawhDTTJD)dq+lTKI|vKMRS$=v~K85%_=bYN&n|ll(pUZ)?rg
z6r4u=taEejK`KlpN0alkq~x8fX@(z<D#mggbw-;py|Mw2dOi|3E@jy*b)pGlD6z6-
z1TNX?jX7WUrz7K5L@T?hH^;m!!xzIv`bUENRfxHtNoHiuy*nQ#G4lh@I3@*T&miCl
z@QFm9?RXEOw2z3h_LM_{mmN;bBwyHD_E1BpD+u2^E0l0iwRpCw+-Ic1BPU}uR5uP}
zL=oY(b~w&l3)G3=_#Vg_u2bX5L)wVw86o8)Tx5C<WiJ$5!tTfsFP2^em*if^TfUa>
zBB<EJOp`DU)rlEq-Vrt~qoor0?fY}n7I)!WzT9E^Cmr_XZEv3*T3ZUy%-c)DA7EY$
z{F?R<^S7ABXKN<#(aZTnVqCx|m8|(>31(&zP33YNUK>ejN6bJ#CQa74<t&^Ehu2&t
z{b3klTv6(-gOh7QUKOn?bSg&GFLnNCDH}0njano(Zr5qta?6dcXJOUA6?-6dh5qP>
z3~v5T|2dgY;u|<^K{=h>*o8siVo>BOqmjp9_qfgxK$>YI7MDqd?&i7GqOp7+UhN8w
zf+cQO-<A#%kJHrjrxi$!d?%cIwWSpgn0c;M#VaBoE2IU2I~qociTwNSM^FCS=vq(P
zOOjoo!b<h2zHpees!4&^^OW8?L{$3W<oq{Nr|K+1dm&JRldB`Y^PL{BSq`$pA|fLB
zk?Bq4x=$HGpqW)y(Heg>LJ8OhQ{f-Cniz8Jay~o#dS<ro)Wy*mexMoTfBUm)qve~x
zH^)pWK8~w*n+hq4F>`}EV`o-QPgd+|(HvZs%gWS@ap0b~By}oy5Aep}eRN8LNq57j
zT(n1=bc}G?Om_GaC?^X~k8c@Yl$%Nue+4VAM#?GX9!N#?PIY;kN~XZ4njCqr6_#d&
zF}21-0-vFxLR{_mSh;ad0hP=Tjw}VE+FBgKyS;w&e=x7rK=9qdwXn1vos|?A)UV#D
z?Hcyxw~BPqI~v~A1WXu92PdseeH?s^!TL7-3+`v10o?kwo&k{4tqwfO1JT0Qy-u?2
z-JcRmj5SUyV=-EeD`pwxP~fPP1A|#mGP_DK2S_V1fphkfayYYRr7rPO#9BHRX@XbL
zoMEnU5?*_pWXRfSNs&z5yjE@)OM~k4#U~#5PYdAwF!kVL4I6u*WHL8Iu8Ux&oQKUA
zdl_%#Xk)-}*C)Vb5vBk}atu7$YYQ5O_dL4yjZtX6*>9_fyjngR5kv(qQ*xzui>AU;
zrrFsOkWjrt`n{L`a$gMTJ;vxCF>W4m{;egP(texUv_L?z^4#^!Vi$18#M}Blv4jIo
zLIM%rJL{5QC`>Z=a7_(t(5`jYy*`mrw)MUY&81tkJ?RI_DprO@Q-_-@+Wbf+;a*0`
z80xV|%(s7)D+RpqA&m!J?bH}A<GVA9sg$dS-TXPzjpVTHX#``0p}G=Sd+Uj_j!v(9
ztZNqhIlp!jJ6k`O@)qmOrP6rkqv}>OEhDN>ACBqi&r|UgQ1JBvqxs`v`DP96+F6Y`
zER6KM&Ez#>9WDomqir@2y~(k>R|2Z^hi&ime#O4Ued)>)L@4&t=2>7w`GCm~^T159
zgK2c-TYRMk2iV7~4;nthU+%Jx<qsHv=p8ZwV}*fklxWOJvuFnKbMIal>0G%Q>bBvW
z1>wr>1-B>+Pd0uL<h-V8;?<;W?CT3B!{|?ow9<58>GBBy7%GVsfQT)KN%n%pV&?n~
z9b*E5=$?T)z+I@^(I9rho`6p&B9-I1S(S#2v(ky%wAH#JF&O#cel$MSy&R_FiiX%0
z4K@YQ@AW*tMy~qb7+af^NItk6T2*F2PsUQ1uI-B_jqybHrm@pmOAA2))!QV{h)t+!
zyW2%(Re9p#ajJbrk&Ef7b2)^%g2Y<#-eO1Z??zbG7pBfM&j>igMXo${ntKr(P9A-Y
zix0dfz~uQ_^%!4`-m#nNu;>KMxTCV@c-KFEOhdtgu?EH@@AK*q6{Qm4cUsN<QD;$o
z1KF;ysS$wTq#i=L@nprrZ)@_`_^72;<#*vR&z3eRKo}e5-yNtI-zzK0GY)1~OeEu;
zCgRj%Qmb@0z_hJM4PvM)zT<7huU2*w*LZcAtb}umfk_~<8DiIS!b(ybtZE`id-o-8
zObRauiGHarpM|>$de5~Sj(1I(&8imb@UVyYLSMmnC?#-Y{;!)+kXhuAZ*+lcA3_c)
z=U^7hYK%L^J5bfzM!121h42YjVkxU2WI1A(4Y4qTbk6ZUYwdO1FnsXL%fN_zpZAO4
zSfNCxXg3Y{mcvQi_9?YR3=(?$LjDU353Qr{u4a!<|K^pPE{<$ir|7tr3bShjA#GeA
zO>EV8SfPZBXN+l%H8Fyb*wI&N^PR|XwB<l&Crx5jpfjbMza^1nl+|0JVtOey7S88I
zcCVEC_)o7-nlK|<Hq9|m{Ad?_EGY4J3OiKse%PUI7qZ(qF&xCHb;SIp6Zz0tF8(v=
zGc&?{a>kb)wgs#NDG#>AX$JCk_?DcJa`+%U8`Fc7UkO_Ue}=Ba5P{D=f{d{~d_HV&
z4!ZQ+0B6h?z!aO*RXs3L$%|16m4m>r@rh`cMI}x#vj;CG79@**hCQ3%HkHwb>o<_V
zGhE-VpH#+5Xp|OSOIXYPcxjn+a^abA=NAwDFGHfEX$mhCRz-b_`kiNdSMCU^Q&Q4S
zHc-ZB)WJnvEJeYKCkFyWUfx+JtJ=ybJ^v%jpfO>s4n)~BqmgXUYfA3w5@_hDh;&FR
zG>zRn)OR<_4k_y1YTT}T<ZXK{@KWqsE)Y|KXf_PX3bMgzonzzWUO-cA$2^4JU)D>A
zEy<0f3MAA|@v%oJQ8~eMe^}x@0+)VA<-6vuxtnndFlI1Ig#0cX@UDomgRX}XP<(Y6
zDZ7Y^=e@GtQlyv$uq}zXpd0t*$Yq8|#%BS%`J%9fU+Ty=aeRg@kkm?t5l`b<9<{U6
zvRMCtiS&v|iteCV2?Ba{3_~pc{f|HI_+t43zj%%C=sDm5$gMwkj}(k228IW7=;|_k
zBAd={7=n(XpH{E)Z*Kxtmhn;axLfrMkB~U4{iGl#R$PIY@b1ooW3s&{QnGyW$jO$C
z$(wqKN9=Zi6Y&(x)g0-JvVH1YbST@%WW5*`lf*>6miL$}f(z+s-?J1X{*5#B%y(|F
zRRy^ED2mf4h3pfj#-x*Ma{-D>ZW*6Bq}9)MAd^f2Tpd6?k?mj_MSu(RgAkz_9g6MF
z;Ir1axYVntB{8S+WW*hBUH`xR#j5n5J@$81{^$KC4{DsZm@{EA;+o*)NfH?=T>5*O
z@|gbh?wiBTaWWear|vQXF%z_+r`(0HZZF<2j>p)eQCX23&lFs&L;6|hg8a^jmGgVf
z!?+cY9O*UOKYOT)AitpBecm&(b2+sSihL3+E&agQrLat}RWmp{Nxafe&i5iF>32n@
zpZ#N4-#YTKant@@6^o4M4r_^_?x?&YIpMu7dcImcZLx>UhM}m$R$dWgv4<%h@J8|w
zo3Nl0B^Q9eiTO9AR>P<QF<(OGz@|kGlRACa_7*KREAC2LzxnKJee?S4R%bpOGpN?!
zi}}a?grU8?Jg-!3qP(cFFwy}iP3Td2%wTIZ9p}%I6MmBp@LOb~E!PuvWgzt!=pqiZ
z-3>06TERrNs#4K7G7&5nuA)FEMNhEfXj+S|M$!7~ub5WQAZavT)nKYX@6-HH?vC6)
zyQR&h+4bQrKHIvnijM(QCGbOK=aoL7{<@|-4lXB@CFYNPTYK%Vy>LKP+p7)mP%^vG
znP&#w6NaZu(3C^KRQMjC6&Hx5RSlMN_YHDjTsaMlSUL~W+2J=2Q*Gg|ucthfqU{d(
z&>e>PC^4%49V&UupHTc!+WGA8tRpWQ33hEB6UAxqK4EHe+9kT0>u30J{Nn9hMvOti
zk0nH3Q8HH0xX!DJ0GwX{as)VtTelOQL3DBtmr@`{wkdj<Zq*}+Q8RG*8FmClJ}e^!
z?&@yz6}!e#4h8rs15&{do1apwlFL2!^p*k}#uqi%{LKm4Z<pg+Nam&nU(>6^_c2C3
zU(hu!;?`d71DYAamLU1<*YjHg-{5fXWK0mhNBy&y&UA=R>CtXot+P1;$jpyFST0C0
zJwAw_WHV5#++)xjAJ}x3McPPj9ceXOM)aPU1a=`xs#A}tWU6B@n)SPlH<4;^cr5L)
z9fQelzfZGkKY&U4)B7J!cB9`w+bCz6UgQGq`tyOYGF1(g5}T|)K66A49)wQ*mDI`c
z6ZZ!R%OVuZe})MhbmByOAY=^1*TW35zK^0#0}U4=Saq_KE%-6>tB)DXFkQ!8V<&Fm
zXYNA{>$;AwJ<WTmn>+XOV_vSV2S%qb&S%k==&^Jw52L@V5WHVKSPGJi@gGn;Re_hf
zbwAc@!d)4aPY_Jo_E7spQXvyhGjQ&*c3U!(He)+I@ScF=<l;9X$R$6t{d?sr4P2mp
z^I<bQlGt}gk#<O56C((T(VM#qTT%i4!j==3UXdM2A;$myg6Dcf(L=wCGBC=3xGtLf
zyeFxm!#Ta%-SdAZ5X@t_xA8_0q)ds2lRF{|B_95#TeT*Ob$9_mLPJTC%d?+Ixtr3j
zs<AQT*|aq~;{>5b-=~VyC5_sUEyh(Ml~kgdzm6eK5JR9ZQ!|)fzQWd!q1*0z;FmR-
zR=sA|eQDj7#Ap7Ei35_-s~iqQm^Hy8a1VWFLR@m9_Nd<$5JWAVd>h~b&fy-07G}U9
zrQc8L`Vm13l;petxxuW4*!hIdVz^jH^nx8GMjun|CLHRDs>(&zPuL78{0r2gGMLPb
z%-rp3IA#Eg_2VG(NvXZCd<zq}=V=ibbs6pRc%kaZM!lNf(`i-kX1sTyE5`7QZPsd^
z>Yq?G)=`c#D(GBX*C?G~=f$tNN-mHt)*Met?8`+0N;g&eS4tg-S?4}d?t#I^l&2#L
z=%=5Gj7=BFt0d#PY4Q;8S)Z!L4+j_sxN<AuuGT4gf)9fZg3LalQ<)$hpTzBVk5aB1
z%2JD8FvdAEWV94OB7cP=?gvw(v%?f~m0p?Q4zC$ix?Mz}-P%4J{R(k09n|(2vQ$9w
zJDrmSdcH2F_-m|SdA$LLbbeoIs$&o#Ttq}|7$^Ahlsy%zU^OW^fm>f6G<iv?29Dh&
zY>~8gc^f^TV4pSS$v<IP17=9efz#sP2WUUaHvVam)%bjKg%o_Tyxl3-X1WOZqm?C5
z@C7}2r0ugZYkkHCA|}R+6z)ZZg|Q`$PELJu_1}Am`Hx8i<yPN8HOeqYRU*I4s^6rL
z$Q12&2KJ=1a_Mr2siw(NazBK&nx!~FG+Wf;q%3Si<>R3U0nIEy#~j_;`FGL%DHS$Z
zeoisu`W~6cUcfWWQ(;~+m+`UW4<mU#i@n&I<%u3SnX9^W5xToF%D|yVG4)jp{cvM7
zjJ$;1RxSpx@$O(ceE8gmlDEm4jLVpVs9rNfNX>%hg`<QbTGT5;@wAaQn%r@sAC`=v
zy{WA`+SA3zt3nq1@ue>(7CwIKRW7{Fxuo3h;FJE?ep91{67jpmPn)G?kzMLd?LQ-r
z;QQM<r7~$ZzTX)2=8U+Wq5C{j_SZPEZ$5N4Q@<l@TK}8Co8oAUmInoe3ej91KplT7
z+!J*^VWaoi$EO5N<WOLe;JfPJ?-(@Z@c6D~jLoTTP>3etl)DcN-KQ^+Yd;rte5I&Z
z*+UKAT_l25uJ3rndK}}+$P2&~n4mpQcLyXp!T}GGxyUe+%>cz~mROMb(E)kTxnZ>A
zJks^sN9ug1?gI}#d3Yj=Nni|luL0%|hv>N%1>bh}?v^|?Cwvt7w1A*+uH_|9ce>!G
zq=hS!KYpc>+02?$W<QNdFkW0;!T#dwwQrHAYCbK>xZN@P@`b9LZp{7dO`60z5N+E&
zj<m$|`bEX70-D)Ak9<HBWU?C0rYaag6<USBCxi*)0G}Q27*x0azNtzzM@lB<dNb(@
zs@>9^zrSG(K|7hNxH?KFAb_RM;B3hm`b~RC4LK;2p<rIh7iTZs`-%VB!K3{@$PLm8
zC;wl+@L!+pp{Z!_T?ZK)ydg5EfhhxzrLYN&5?4^zz@Y8ohyq_OW+Li;gPk^by+8B%
zj;^;Ml$22UR%|SzUM7qY{djsv-eO0b02`Bp^v@r7D&tdDIewC$XE8_#okf+Ngc_2P
zKW%9XH5{qXHMJ+}6LVU{>uNlGO0#twgzWO4?z>j%@Znjlw)ex=2(FEda4Wgj2}U)-
zJrQu(`@!FD3UOnX38d>OM5xeA;}ucE4hBsQ-6woTDe!=uu1l@%z_1@)axxtmYBcsO
zrx|&o%T>Pk!0F+Yh^KCE@i>v*vyZt0BTVY>i+0x<qL)E|(eYzEvs<XWynmnaIM7n#
z4bc_mA&8})7zL=gEfEbqbo1~mX(r|`(5{7msE;!6i_V)f`?h1_t9|!&oQOm6js|9x
zgfk22bJeS>c0Zik8Gng(jIiu7)0-_BU9aj(Xu+ma=2jp?pV1VSEqdO3Mw=`ZIPpDM
zz7}!)b89A|K|j0eYFXzbrR*Kfu<a8C=i4iMy9srCQAacC7%8ujcy9dSF}C@O@qP>k
zEJYD0d`Vwnq52mo=}ulj2;|H|K1`|`S7Mb8UK4g8$S6-fm|!HfiN8KSGbSOC=Yg8{
zlUGUE$Gm_I#hP_C6lrOw7OiU|){jb#bl?@zRXZWJ1BRvu#O$vaw&6DdObOWXJ@@6;
z^aYnAT3lK3!}2{Ahv5}QJ@zdchtX8M$-K*3vC~Pu8v4;h;Z%J_?I2QYWQm)>t|Q&L
zOoOF=4Od{`mqZN-ot+77Z+uucX<!81$NM~sOs*M<)<k_&#i&NWkIlQG*2#;ppTs`H
zYEfRKKh5>W&?0I+bPL|ghq^^J4=jCSvMOv)k~Kh$H#FIEqMzh@+qYTG+tIIKzBCNy
z{V}FqTs-uzU+bW=-03<R39LQN>&DC_7zMbnZnonJ_n#H|lXqKhbu^IIJ@-K&B0QWe
zNZ0C#ANc`foOIu-!Zn}ow>3`GbhkA5VoQ7Pl&DW!`RP5xY?Al(eR}UJCN_4T-rO(x
zwoA+3-g0x>EcGS*l#stG!WkbF=#-#7Ucv(ISJpj`>W2==p$gf{;dU2MIi+u%x9t9G
zDSY{G;$PPOL8s4Sc7vQA)Xosg8lp4rA(djA>DnM*7ron*W7c@>s6O2=u9z{UQ`+A^
ziM@J+G_X#Df7<EuwY&1p(kB>L>*!C=ht?1Ksm@HWNI<J*dqOwnt#K!^(n=<D4~^e@
z63tul#1&4Qcb~NzPY@TiH2gRm_4Fh21aA>UC7@=Q<12_(qD~K4&8GSM4t+mtqrotC
z=#6Mi>)~Y6yOlBmyO!VcdJ3wg^*6ZzvK}oHl)5DnI@Hc$wpEVvO-&V?eC`&nKQ_+M
zAur~hd&ESnvHh`^;x&eSAZMH-5Ch)zUxAYo03Oxx@%_1wY-ByJWQg()_p7X*YI)K4
zH-m%qsCRI;WT;}#yop;=I7Wg@t)+D%tyRbdI@_PfKz2)c644qg4$6YfI4pe}7U}%f
zCkv~zrd}Z#%549#tKK~3omlgTRLnM<)#C=-PM?qor<Y=Be@<YBI$+*HQ189!ulZeQ
zhgxl&aJZSpyD7M934<RZmk>_hY{ST;X+D2#)-Z!At+$6mjByAYBgvewsLXK)3J`~n
zW?tZ_(DUUUnC(#I8R1OJqBWb9V|sVrgxy5Wnnk*24~X8vP`y53ld7;~i%)+H_=I45
zjpoQhHJU3c?6=63+2P39xV1Xb0LGT^mh=2gpyo;h=HPZKV`BfXjXS6iq_cx)WqW&?
zYHtS;su+c=ZK;mo7D`gs>%8Wdf(>4>Ae*)viUqMtOjB$>;sdL=DA4#o$QUl_`K(^D
z#(P9)6{wA3_>)tXnm11-o$UzUsVFJY9B*h`=pNmBChZCS@!VhE>`dvO-_by1nlDIy
zK<7J}c<Ackyrj1PhaT1s!?(2lH|vGy{XfsIq9Pa&!SnU?fw4~`2*^cUZJLf6{y(n1
zG9b#f>sFAI&Y_X+6zPx#Dd}ctP`Vo=hVBp~rI7~d8p#2qk?ux%=p4@Yyx())@0=gN
zAAa4}eXqUu+H0-rVQkFYw_Iv6<Z{HaIM~V1mmgj}1a%A{&D6fcd26Em;QQ0ikJ?;B
zd33LEvp#8W9W9WTX`P?uX#D&$-R!c_gJ<t_vG$MEloS)=f*}EmbW`Gq(12V#RD`iF
z4s{s|wp{o=*&>`#4|B^q@zVRv?4lRnl6pbF2Uk$5fWB0v!T>W^LO_j~lMo{e6y2bV
z7xZ!$Mz}oAZ}~m1Ap&aQ6IJ{`zGXFN=)dos;20!zf!0ARg%~ahv<;8^{Vh8~G72!<
zYV8n>1)D#^qif?JXjpVh06-Vx#;FwFE9~r7O3H7)`q;tD+ThmXkF(e#%O(r%0TEb?
z?V$lAeF{hlQ|tVFly6Mh4-@(-%&};K3!VgPP1MFd9M@3rgn_Hz<QrTCzT<ROF>!ku
zA4q)qwKe0astK+l9?64;<N1(1Zw`nMJi9YmKC9Q*9sSNKhB!F#Pq0hGCSq&auGjss
zD~5>idAxM{gj(V2idG>^A`14PfJ^#H*nA3p@A0c*`N%#bz`e|WzUEAAm6UpYsNk>d
zlz9Fs2S3w9yxNvTE`!T1v#%n-{O=3er#@fkfgTJU21>eIsoI}*Ei5i33FuI0^qBn)
znb^g*UlAuo6OJtw)H$1LE0Xp`*UcSW%R&?ahEG!<*ix1ID&-_aAMhRmtiZH#yt=bB
zV)BnmlOsb<SZ4~~1o>}FN_NrqqTZ9_OW5MV%IJYzXKwe}T*J`->ta+hs?tSSy~@bH
z>_!N?am!(<3`(JKD(Ui}OW$W&9WRUH)-dR>@ej{UBo_0*9$CBi7H2bbtnw$}No(v<
z#Bh(i#%53TGUi+yi_z}~#3v)3C)X<09)Cw%zp#Ki^2h!~;?*}7at(xeed(iJ@j*ck
zE|q*OF7nvK0!~g_KgO2_QgEn;siuFE<=yviR63?URCr4%H)xdId`K(EXS0pJo)fni
z@6SPgT+E3$tBM(C0t34mJP4@`15DF(nu2WkS<9T#B^<46N<*xF@czfZy8W(zkC^zR
zsQ1Ou?CyahCBddR|IMU^#fxJ_%wAk}6gN?YcSUIE1o5A7lW9YarBm4oHf73zxNNSV
zsG~xuu)LfQ#Bgq}Ps+9&L(t%`Cr62soxHZExN|hCSb}2-<u%BB&a1e%*rY(Y@l-C$
zI_Y0L3!9+!T!o-<`Pgj*fSJCOy;nRjbPp?rWF;U#H?tO^)B_4Su68zSxS}y?IEkT{
z9xW6`X48^tsjcqT3p%?^sE0)DZ(e;GI~70ee<HBNb#i1_wShlIOM!*-f_{23y>f>%
zDgofaK<eV(-2w%Broq<Q(<1q8mxK@SI-~IlCGZa15ib||9LCW3W2SQRBCFKdcXLN$
z3objtKOBvssX8!)=N9~w=!ESE8W=-#$G}vg)`wGLh=IEYx*KW7z3m-6&{C6{_4`rT
zY*FoMt(z*ti}}Tc^k*45IQkBvW#s5X`uaTi2G$;_SI2#Z@n0b=(CCIoq7iSBFl^&e
z;YiowLabg9n`F^370E=Lm{^&lMduF_4Ijk}5t#ANGUyZy_z5BMywm?)ko`gZz#ErF
zaSg6TO3a(<{M<;hdU5+xY@|-F;mPXpE^&@TIG$b)fljkaK?yHVSszMka@>>3nSD69
z+mYn5y4#+{O?lcxo(HUB1q8-l*3oJhDt(JY2S^#>^vJpxgPhI4#2}tm$McS(k?SOq
zEoiUEWJxhA);iS&P@CZW%DY`=^_3oCF=oTRbBr+@44?v8Z{e1$jo=}};(-<W5z{ns
zukFvSTi5)v0%RFELl1|CC9^F*bh_xpX&9H<qJdp^NUH)5!o=lJAdJ|4pA7bNEFaNP
zAKIOkBlI}f?=(R0CLNl)fbn^@Wg(;A--G-|dA!?F1hl>4#vH!?J1CClsL7RxmZ$3a
z{GQ=dKA<WXU?PaMvK#{*`^UQ=h%dt52WLDJyk2UW*dFiE$Kws9vJbx^)-n8+Ea$Cq
zZT(n_jKQLsIcM)?6=oz^*go50gm?Hxz|jrT5>N%X9&jM#kshXwRflFw_*+@@^9&y=
zfpIQ^%=f_>qbB!%=sSdf*8ZzR$PCf*Dd`+$a1SuV<`+O8jt(&Zvc<2g^!y5Uqc=5^
zfFw@W1OU809M*14v_#XyKLbi9HGOu*%NC$9iZqvj>Q}W_V7~%%N8{Cho+P3|eCpr2
zzS*gt;b^OIkQ{TK{j^t~H+^!LPp<U07e{%}XlR+v?vXzg{p>Yv^6qQT61egH1%GCx
zwInuYoHY!mY&84?R{KtYdbw=e4E5~`pMw6Y9HC0Sl8E-QmwoZo>j|^te}7_qSsw7K
z*lhV&%e2TAELf!<F*N?xO$t%sUEQN_^P1wPcgdLHcPS=pU{S6_T;_XR_BNgn_6;=j
zb`CwHJpy{rJVnm6akUALZEMc~L4Wkwe0JcAg&EfR1i~Ra*7w7N-)}Y?bsG1%AnUcw
z<`4SnC!I0lG|_~l_;LzA(Ue~MoP%_FuIuT5sQ|82+>*FNJ(vPerY#YI#w+*mved6Z
zfmz&L%=o)xDqE#CVV=`~a*j_LK{_#KQH%L%hO=3}caJQzqvafFU6Bl7qX!Jzq;*K5
zAvvuwj1~}|SJG;(l|V33FS_#kbdmAZH7^<dB`P=_DNPojuj_uH?gxrM(Ur@6XEVa9
z*9CN`C{B9N7JBU+1>g#Cw%dB9c*}n9<2{*<jy}8_7?){`f0cRnk}yb%)*=jrEbbK}
z<GE~%HH*qW1|s@+-ASoNes23<$z-JPP+r)NJ<3?q$rUg<1{O_s5A_?ks7WJDs(9<@
z(6(7fL+a%AMEIt}NL{BA*MhfP`;txjl2$8h&B-SyA?GIWDi6$#_%i&7l!nG3U@7bA
z&gUo&s%1Zh<XYVlmj7saCutc!(jqex(*P$V<m=$6Aj?Tz?0;yd99MO7@YWm;hY7+F
zEbO;`)d03;Y=;o9^@2`TK^R!?e0o6an%{2Oo2wc4N{o#WKa)i|n~jt<ypAH#Kr$Vv
zS&COUo#Ci_`^k+8hLQxwEoV4@BEJ~X@%*q0ToNh!)*XlC`dNR?b{zmaX7k?Wz|hM~
zpw4%Lf9J42T;K*JHoAwLxn^wm{ms}B<yrbrE=Q_vN*!uii;&r$jTJF14=3dM;G_-@
zJE|o^A9=xl2(F?s9kPrpLk|NFU3glmg`Z~NJo)!_?S5JYJ@=(44Y_+;g3?j_7``#P
zU%2ct2$J1~S)H7%oldPi25tu5&XCddE1e;-knnpy+`q9>$#qm8ztXPe=~DosfM4hX
zYQjP7JBx?N`abTDUIRi>;hheYw0z>yKe?}AJ9A%BMPAG5^$te?0<k4&Kd9z0n}qeD
z`l+sbK{y_LTsEqAS1%cs)uo6U#Bnr)I7LGATi>Grs-9gy7>W|S<+_AxB9uNdMoJIT
zE!tSLu78Oh@9ao7BZY^D62I(7F))<u;71!stma^O$sF+?0Xtk4OT?j*r8)m;mRo=H
z0q$bI(zo595Rt;h&+|S&5kCiuMo>Ra<E&RtzsV@mshzgfCj0x>*lBY!4eL=2e2Fi9
zby<a1^W_N8<U#a&f4y~^1qq^_j@ly9$x8V<l$-q^O%Fy}V6$b;770RxM{bw}(r^+u
z*ekCWr>h-L{o`SB#m&eA(>V$@^IusI5r?-@^4zi#w}v2pi<=+ek!r-@ahhy443Qmx
zzLqpAfD^7pzb3Y$H{d3=aPMlpNw5|kG3`A*i$o5?&c9lKWw8^P>c@Hi@VhLnkK_v{
ze~93FdLx-n)e~>1zHmQcdHh(3<YM`crxD|sOsXd|X^oJpVR|nPW27{eXEBM#be3Cz
znqw+QHFu8SMeO+CL>=uD8esMUfXjL0vKyh6>pV%i0y9}mW=52c_qK~dBki|1TxHyh
zP+yS}vFMziC36@G{i}XY?Ec{-8#8K6l&1$qU8_xmRrq0n5^7dL9dsIAqh|XWZ#~0C
zV{ZHQ9M^~BvCZIf*wyIlz|E06QN^K$=+&}=QD<u!Og|+N|1mvH-npd>1a`ihE@RPe
zf=|gCdB7lnK(FJj-!)li3!3a)<C_<1YoQU;U15dtD_~}ax_aK2y*!DyigbXNkH_Ef
zcwwBKeff(BqP(X<)_v$ewgA1arEbSyBH8fnQG+ZJhR^69lA6)QQx&bjeR^i~KRrf%
zA6t7q>N0FqiR)K83l#i{0@U(H`r*NMI;<#6S~9Cn`n0k>!38%rUZkx>63bOHfi^!b
z`h)Uk;<UT}2=hz=<NIgH$e7}WQn<FW5u)-hm}yMBXE={;q$?NuO^Y#Ze5GB3Q{|U#
zs(zp}w}s?1Ur>0(6D4i+HI11Bo&Hs31aNzRV#-9#0utRp5$3TRo-L59Z8X4e%T+a%
zxmNprVH-%7<>jJC2m|4gFD%sqcqbwYuOFe7Yth6n&c>_3s5VSGXSbJWw#$10s+&Qb
z&|+I#xTwb#tHZ~Ez{#Xt^q@HLWuJis;`8HuJG25GMN+Y6(l6yfuIsh?L0g5Qsv15i
z6H^;@0^nTJV{l|FgMcIZIzgT{xwTC*_uIx$cqAep`KvcSmdfTTT7C%cJmJUur6P)e
zUx;=4JQd5Gkw2T6D-mB?!)oKv(Xae&OwmF>0_o8sr&ZvUk}!U@W(g;+0F9&76gKmK
zDmxY?)uQ_<k_{is9ZA0&4Zqtef?GxYj&y43bg`P83L}4?`yuir$MnMU3(t!*eX~#1
zeJM-|B>g3xC)pdfk^cGZ&s*T!m$cG*Np9XCI?w(JW6MjH!kScfGn1Oh>S?ISRm^7Z
zD1nv+B%07XR4AQ)pv7U}kWRCumH}00pj}5A34Ms*#N(ZaP_~z1J{vPAc1y;6sgXIJ
zAPFgY{t-b@3c*0$GFB?{!*0j<TO#xD+1*Z?e+Gt7GhhsHjXmXnTF0H_V=JB7hVhT|
z53(-}+fa}}ERCU*#@$S_r`=$9FuKw51~3s{YLNLOqPK$|`tzrUD0MDSV*a<cf2rZd
z#_y_2yTl3I@NX!%;Pdw(;oUs}Zn4hLxH!eiYE=tAKj8DeQe-4ztst1<=!d{91A?jd
zp@uX6y_aMy+Ixniw=$5jSQ3GRgMoRwxCREKm~Tk=M~yNTD_HOj6?>rlxOh9dmSWOC
zNv4CDMW^LqQX@9CG+T?Nug!1d>)qDH{MN<h@V4@}K%@}dP`qp})HiqHl$k!h<52I1
zV1*pp;BV$YuEgcOlI6W|C0}9OQe#21@3w|p@16uVMRyLZD$+pw$e&~lA9}}D{S&G>
z+fO#VV{DCZdO&YEX^gyUURJnD`zyO-M{<dxC7^m|D>S#s`ia2@u-O1jIpPbU*;O(Q
z^giP}{)-Pyuftv_rE&NV9m#gsU8`tm5sW+J{)Eh(42<3@Zvt(@8s_J~4pSezeGZvn
z*ICqk&_%KmHjm|UwZa0zFXiNVPO6*M0hvz3f7`0RD1b^K;faa^KBmQ{)VF)$)Mi`m
zdK<$P2z7)TX9VC&k9s?1TV*u|bJtI7^K19OpI=@KJI!CWb&ZMkbZlIa{uS)hMPFfD
z_+;I+v*{^lgxtw5)d@ZbKQ_(IX=D*pARep6o3_8&8y}r%3(xT8@vf8dt=iLR#BJUW
zc{uDGCcHZx>bR+LK9#?<n|%DP<QQ>q^6X9i7y#ekTFA^+Aa3<pC`h>#g`qRa3Gs+U
z0X%_lVSb(=K7Op{mRqC9$Ox4|1l>#bOhi}N_R(aD5do<^4+06eb5EkW^7W{LRwr%|
z$OMET(yZRulZf8-atC6((LJ`Y%RZZrz|3(a0ynX1Gady#Q@yW`c&)|UP+^EvT^Q*w
zZU_892Q0hRT|A)+qfm~YnT1MZ--<of^{1;#|CojiUA3Pjv7N#%aEp*{5$1)57EJbR
z8?3;J7vEdB%CP<OaN)mrZR08Q``cHq;LRCX4u3HpHno0lde?&}Y#&}uua6h-suL48
zEF1^N$7{Y#!ZiY!cE|JADAljIwJz^J@KYH)Xpo2d;}WnRy_I_yg|N~AZ6rVH_ZUkn
z*PboHX9w0~wpm6r;)Na=(>N%_@iomL(Zab*B{)@Y13dMR!s?613Kxq$uIx*cwqC+G
z*G9oFPtDSX*G%H8_1mFBZufWQ_~GDu$EF9a5_8QZc>}}OHp~M7`DmLUa1|xIs`}b)
zkBgeq!&3})lDAPvctdm6){X$P8q0tc2aZj88Y!<5Hq5vTL9@zI`Hh0BOlI?<L#|mZ
z3b%reKxiH7ENu+ttc5n_jTOpaod;L(-IDGStofaZ2gV9a;=8#lPfdNU--C~?4n+b!
z&9><q?eAN3rGXg0x6f@i=x3`77`F>=!12$p9swvHQnJj-vj=$i^xuaoH2}Y|ZEJhT
zO7wmnd1Q1rs1xT!v(xzI-QM`-eWNVjohJ7}L<afUs~5AdH?=T7lkDp3p1wNpkwbl!
zdAHWin~cgpb3qJ;K%viG?}XeuYr50P?}^w&g$lw<CygPiMC?-a@O7k@_y$=Oh0C9w
z6#`YAcIQPyyYav1tOIsd5!xyyQU7vw)4kJTI_B-~t!!shDpB{Gx8HQ0M*hZRTlCi-
zp1^mvX<x_iranqp6nWc?3lr__#6aBP*Hr^asE^@1eG)`=$z#a-#caFruVZuewwvFV
zM(*rm4%2WWnn_MN&?LReCeorIu{RSkm|vV73=v*->OY7z>Ji?$7%<;?AZr(x3V@Gc
zK)7`z9_)RTa{IH#M+@=vk&zJYhX@Yxz6!WKx+mqk-T`L}z82&r`n#_BTa?0%Bu?56
zQK*8B5I@N=U_?nr%tBARa(Znfyr@_G-OwN0?4l^N*gxiX-gUX|eEdCE?NdkK7U8l@
zvPcf87oD)zQFl7Qw5n=+k35V|>HpE(=7Ef{G#=y0DgoUEIi{fj0WP#<z;sil4w3!x
z+N^TO#LXZ+vWkl@-J=Rl(hLvc_2RO1WZ?hfoM6-}l8L_cs!Bziuv;bUUH(F`ee>s5
zxbdx_sY!+YU}^t5rXX9&u2|gI^mr;LD^THXlcz+%Dj+{6u)(CtETCt|uH!VO9Qlun
zD%?5I|4>Qi@Y!fbD!!5RH6e|O6`ETIx0lQ4%L?a>%El+N$@0MovEkk>Dlf73-khK<
zsl_#>X-E{Iye~<DS=VgrgQkDWM?Xies(u%~l{v-NI*q3}p1E9mLVu{t%)88&0@l@O
z!zi>)GW7=5#IDpudE6Mtbb|-BrghJ5)Sii9i~Tqoe@0W<8>Dz0|C>+B`$bu04tl!<
zP_O7`hzWrcitq+4awm<nvPK09-j!iet1<4|C;nCk262dv5umk^AN2?I$_Tj`*nNP9
zkX>YC3NzkhC1@9{`B&0PfgS|m#yUu>Lao9O-tIuaiKtF{@&(FP&h>2DuU|yaa-#2r
z;#2a$+mS>*X<XZPJy6(1vWR?#1XDzIjq>VBsX$ck$`{TckMj-|QfZOAm#)IVH@J}0
z=tkgAGTeBIB-f97b;%EDbzeCY0FJPIJUaa;ke^eIr&WWUfXNq0(fs_z7d$$Iw5c>U
zgxDY^d)qA`)>#9&7VcbmwHCBN!v2UT{ym(yj}W_?KxC>4bISbN&8z&5w}wx<Pk$nD
z`tK1TAm-yL%~+3FW-7pDr5gSl1IWM`GoBRotDy4<H*d(u%+W1;3;IuTC$RNa#TMJe
z*wX($@}$3SuqC^Yi$Ceir_SFQcXu4@9Dkp+MM7)TspG1Ez}gG<N?H()DlTWZic#i-
zo}nLtk`gfFlLtQ@`QXeQS;22y|K$bXa4N5soU%E`^&*HrjdZUGxrTvVPGN?vr*6fw
z#tBY=M_*d)UfrjyQ71F_CcH5RjeYQM;d(nemXuQJf0F%E(mxO>*{0;0A?9*D^__a4
zB<uMH3}E=~NE%m|VDo{jRL9w#+e71YrSK?>%-)LTHz1i)SzVg=b*yMPWsL>2nt1~D
z{_DAdLLlxUdn*mTP1PIu7Vf@CRZYQxVGFIJ$ekJ60P$wa?8rp*ST4uJrVFB{S?`&^
z%BKV3z%*PU{R;h$h^ihK53NT!GiSx=Co3PVewTZbJ$8*{%=TRi!nb$ir#YP;?pK}$
zFFh#A9oMZbtl@zNTbTd4H_&J-hJIUiUOFagkP)QpY-37Ylf4>1@%5wYBg8s5tg(!}
zfq2M-(wwln@4+#0K5^P(x$6p5(DUeJ4o{V!+Z$mIWrg>(XM1Y96!oTNzg`6!1vi}-
z@d(k<Dl-f5r}o;NYF0bnIQf-((_FEEf%uHB=29-7!8IHZGN?Jw*XWZy?|^qzI$5(F
zlDI!FF{2Xkz<TBQTOno!i}@$viM?11QNRkgJRP3818i~WXKWEr<dbh%OJ+))EFF#P
z6ZBHO$coo>$-jO7h3811l?^$}&3z~7<bDehE$Hxto10>zK$C$%gQF*nvTda+<MpZ=
z$B5nTQKht3QN)QG%eF4`%5(RXR`Z#8+ySw9|Er6;W_p~Bmc-n6{Cs=K!9a`ZdTn22
zmA5?KZ$*%3|5ZK1xd^@bHh$zSwcqt{-g;gy5AGvIBc)p11=o=}UC+z`RkrcAU)Y8E
zc`v;x*~YDS?Q(d{<a{}(`%UAk+;<Bptpackuq|RGqt-MjmS-uPRd0SSJG0mR$3WJD
zW0YP^K%^_E{g^zRje<pr;U4tZ%JYJ^IJ)HnO>-$jtSR^)K4CnmWX?rgD331mD+jwi
z$ssP{qYJCWLfz;2t4mH(g>w*C9oV2~hX$wrYU9aV++>i^-!${`|BPTaz9oN@%lhP0
z<b@R3SNA$++>5T%%RNGD_7j_USf?HF?tUeYTFd^3u7Al68s=vgOt~Th*<feoh@hZ2
z4?|idQ!z2!=KWRlL))ZHzwi8eEaq5uQbacj`-dY7u=l7%apu`BI0%14kZ3H8?v@8g
zJ3J1ozw@Lw0i3JEC5niWT>h_A7#>lzJrIWs&uBAu<b1Bt_@Zm=Yy)DD7`okXI6-CQ
zXMQ1axL4@Yw$+9h+VE9^g3mlz7TPkY2WdP6M`<#F7xqt^qh<BG3sy?Zd3p)iX+y#$
z@nTYTIdU)b>;<`mv%*g7inWL^p}s2T56g!`NsL8c^=sgRuwgk`r&Ez$s~B(f#cTEg
z%N_K};>Q-rDe!NiboL&xbHU@ci!S9$%-0c?(enmHe%}yra-#aP9lK&PZ2K|1{FRTm
zi(@>2=zpX{79PtnJgZGAjJ)ekJUrrwcxq;<TGk!cn_WGMGd9ox9E$H+PIoglv%)y7
z9mS}Pqq@B*gjD<dDi;$Pm$<arKkSNK)|9&GR=y`l(zDW;L8AZ^C{GUjIgDkSCEkB?
zlJDoP_?)K)PnNj&Cmxe{Y(v3AjLk%PL!wGFc7PLh7#R!rS9}g%Gct&XXd88S6XJ-u
z!#!AVBl7%mCduEIQ*?Kr1DxdKbZ|HzOt$1?y{-HUyZ2pwV`+M|Fv4=%lOlzIKU|&f
zCG_<4iWq8l601IDQMyLORnr@zhz6I3toUpT{%NbU(@e^CtX#@f@1$KgF|xCdU9ySO
zbOe5?e9R=ih`4Sp_K>;gx9GgR?nK{vKRT21hKqAl(4MJ}A%>PVJ)7;MD?LOgM6)d<
zByVudKB02lXVe|6rIYf!m`;4EfICYSs9cFV&=$Z7Y)fQ7ac3j@xqLe|H2s7tP+_D{
z_uWF4-ld0HL~w(am6G|JhqByZ*P=!Cm26EnfHWF@E5gd*+b*6@KO_?Ue$H?dy`tE3
zp~><4y{1kJn`D4%bx6Jb1{PLaE!a=OdHX0E0X0k?ZOiQcRaNZ2&kX0JE!xNS&f?J+
z6UL6ZSrjg=Jv#OO765{t<_0xX4eKMLUi7|ZRmmWCXp6!~hjEEIuL1jHJakBwh+Zr|
ztc#r(X~B4CT)`8wDW*w@EJg6zGWT(AHTPq~6i6hn&lNPYXB2TMeEc1_*dD))){p*u
zThGEx^jbXS!8e6@(`92kx)Zj-%b_3Uw^Ik}JloRnl0}u$TGxp<0e9}42Jm|>#tQCT
z(8zZ<_oLVS&0yv7Xb~vz`qT4Cjf%s(n&rce)IVEQ8n#=+Futasjh=WsRulKx?QsVT
zk^vXm92Qzc**a{cCg<uZ?`4?iMTOyff=FG`0dY><<N@)q$OJ6+P$!G~^yBwJ8TWnh
ztP7$V{pU1QH258-6(SiQ;*PwJwY6#c!vEF$!#`vzJ2(8}wN>kWCr4Fm53w-JS57Hw
z^R?H=pHE6$0=6369U1oa$3%>z+}@l2ydHDtaDlFE!rGtNS<4sWsBd{_x=hV#IJgIv
zvld^5$a-B2b|t`rSQYGI2i|8rk3Ef%(On@|OOnmSz^9v8tGb?1x&)6!Em8iaaA)|-
zmq*8>#tJoAHaSCz)W8pwInn-fn$(y?eMBDinTEl6E0#28980l7Vdw0j-D!BXBmg`G
zI_S{ew0OM!B053L*r1>APMEkTtMCT`u;C+|OjAf=Gm3P5_YeyA)Yeuo3;HZtM9-yp
zAjusv3i`ZE(60L;Nx`I1*_^S~xz@A%S#PDM-DWXRu6@qlC`H$yr_*F6Foz)?-=&D?
z`ztv--Q{-LcwFAVWk=;L&j6H+jx?g6Lh*>5f!~R`vIC_5ddqO72ELFB?A11E_x}E^
z%G+d8v$=Q$GS(xadD@6UtS4N@KqP}BBJcS_NT`sm$nl57Fl5DAZhb?EhzqAjrRAXO
zcJ(S1k;7BC#A_@s?T7b~!#sp7G?kbg@$gS20C#ERfq4{<V$JF5l{RlzsC#PkvP}YI
zyj~K)RzHzQ|E9N(!^WMtT^*!kAPWK7a+wvt<-p{dj9gFl2wikg8BJ-!$bZ<Ec-TE`
z@t$zd{dx{+$W@4SHLvf(uq$@9Vmib+)Ydo%L}WmIbuoIN062l$gN=3@N$)_cfXQK^
zS-Fm{x(05#B>R@rp#+@l$KSk@P{LwPls|_YM82)Mx)rK|^gqqIsy?q~)+kDT+xOr4
zQ!PMm<8I#no+8{oe=*^u-BBMaumHC|_BvZgKFXUm{6e%XjW7IioIz?Z5l&&BJy(i`
zaeeifzQ1vbTr+G(g>!Z7wY<F5|Em*kT5c0c&>hR^TUxzmEN^s1pYZLBe$ML@NND0~
zKj;m7=xRNfF`AjtuBvuaTq!X8^qm2L7!65}AD)aa<1$Fgh(u0dBl$Yfikui1iGP3{
zC!>$iPH4VX?{h=XK9U*ktm$Ynh<;)s?zhEv-|~Zla$jvHsuQuht-xOKha<PHixn^M
zgNgR>nnwDG*I4eD(ArIBd3%u4sXTQjhF!(=5_9+yR<0iPu2kwUkw*N%_>$co`B7;k
zdgEF(K5E|_isHM-=fM4g#cA)&9&opq&9gA}NZxn*nYJV0%*zA<#)6B@wqYi#{oi#B
zwj8wPH}=H?%oG;^GHAGTIyDpKDnk!$_6dV?=!y(bA&*?LUGmFb9vb<tuB7~1TRt+e
z&ZkmO*1)^@DwyE6WcGq&toz*j$QdNk-UNn@l%BpW8GDA0=g4XZ5wIc^mfix|HPr=J
zce)d;SBn9EVgDd=Q49%`PPkgDb;45qBim+Uc9~X85*|9hmmyrLgu6!9GSUceTIMd2
z(8D+s5a0JgpaTe(_eI-DssEA5O{=ZaYW^^%-FVIX#C$AOmZ51F#Vv-o*o42q^FSou
zf<<RYf+;`_bG}2!&gu+46^HF*47^KQaM8RSJXpD%(}m$T89VjhkvTGwOiFc+xZ^|s
zN_l4JDjhEC+PbEHul_dWCc#7r?f(16?*;1mA0{=k00$JVpgXIPai{KJZW3JIPO~Wo
z2M_GM@w~qN82RIv54~L|l8j?nhM=?7?lG*(=4#9Pa)O^$o8N?Z1gW$REnBOyXBo(|
zxHjubgGjxy9}Sj$9yu~HGjVRh`x>+N=6-XJLwF6+&Tg5cYQHH9jZ+(F*L+YUBqRl#
z!<M}ViMq2}%rx4BE^?J!!t-+-*%(U`Y!X>Q0$zEf+{f|sImBBR8g8es%SG`@6`VPR
zhZ%f&HitIQm<n2D5EA(Gp?T!?br4)A1C#lG3vrF-G8%_nBmI$Du^GkwQJ~d&7DbgW
zQB|do>D+C>p@@<HM7U9)rH04(Axc=z^MmEBhb*hYJUcpmlqYQ<rd927?lR>3$k+o%
zF*(elkaz4ulmB?S9}zx7$E~YD6jBk%pPJeYLRz`IsAzS$;o2Yz_<`W)JiNIr{^iuO
zH>b8$6_MNb{kygiHM=RQSaya%@3|>9wNV$~)X)dn@v`cwj0TI&0Bt#753y?x+ywyM
zWm@QEoNlx#k$dk^oBWIrzrt_wa<@+T=ZyYyRM*%~k~rgHUKCuSL6|>&h>!^OT+b3(
z+jvbJB9Ldjk;@f0@`GPZ@mVw(r1oXr#LpKA$a@E5ByN+gj0WWiPHjv;iqpkI(yL)C
zCxX|E*}~V_89727b|JD_Hq?0RtcFFgZ}+h+e$i{#ZlxwCq|h{cVVqJOZWd;8>rE1L
z-4!DpPGmU>v-r4BCi-#fIFj(b14i+7VYpk+zCl)er~rNy7#-vsO$HN0u?~5c<iZii
zA*a~2uJ|zjptU$eXEOK+knh-=ogOn6i9G`N1k{$w)vI56OTc)0o2c*_9dQ{LqR>sT
zi_b}s=5iA6j8}F3b5<kwjoRhK;iAf$4MccV9)3&5r)7!doGjy_f;+>J8AYYIP|z6B
zlwiV^WF8bEWChg1M^1OcBj2&1ZL+D$dyNumCSks!vbFN-W&{3n?7<wKMIqN<>b(!6
zy9H7EQJ#o2>piV(YTr=xWUV<PKHoRz_HcD>p<g~+A7}sf;UCFkQkYq|m9(ucXDTX?
zV?Ml;JQq)%PapEBLLR)nzatheu5my2Hd45=zj*le)Xiwpa!zB^ac@Q;eCC=hcrHvK
z<}P7ff*s~(V3N}E<>FCTvi5_8Zt^8h0g~E;+z{a+iPdno1Z4U8b^Avwd`hN(<vB$>
z`p2i_E)Dtw5}J?>oOU{$?P2JTlymi*eWTm#1|P?*`nz#pA($WGZHt3^{RG1_KP`PU
zW_u=9UReG<3lipNf?QV_gs;_q6Vy;R{wpG$6vN%42PLn<9%U#fNUV$C>ydnC&4KtQ
z9;ioZA6`{e<Yq-6dV#q&vuhzf=i?Wm#Ws4M5D5KNR3gbc?W_zlP&kQXVQU-6OQqk#
z+9RemEo%Oa4j%m_+x3v_ZuFHd^m~=e{Hmspxc}JNc=B>SK98RARJv6n9BcaOdf#}T
zrA4@$&r?(zuk`>$8)MU}9Zo#-!g+p162B<%4Qp5BS_cIFX3|g1$U5F|dcN{=3Gl%H
zKS9RL9q3kX=KdFGp@h<)N`?RvaT|~V^my`N9i8{?U2A9?`6_|#?nQ(29BvI`8v_TL
zEp_*Vk!YxJK6HOGK+ylpgd$TS#>A;@7>N8p*{(B)piar4zsAu`8~Pf7uL*T>pd7kR
zr8M|yYZYN268DZnGDPThFjsf%{WK0_aR_>`S+DNnAu9KNXa>ijtiIiU9dh0kNisRL
zHtKu;nH?kWl%|y%mV1L>kx_}gGkxv0z1fGc5?@d=?=|x@8U-*DHf;W-0C=QHNan=f
z>Ki2Il&qc@#4YL{Tf<7?VI80i!<cajamE{9L<eBe$8F}IaOEaCcW;eXI3`6)iXwcS
z;rO(c4@}^bG!1Mup7jjNj!ak!Qm)BQQ}|Ou|Lv^h@eRu<4-2G&$2_7DpN9mKLX5Tp
zHX{$USi2$ep7{lE*<a_=nY)MAO!%ECPNKm$K?e+&m5;kBa4>pt+a{3vbNp#gy5;av
zN^5sL_~T>Wnh!2l`^5{`I53FfSA_^c?8N^*h2AQpTz@Wb(O#6>R~e>rk71!XVDIkY
z^t=%akzcoK{wO^&zysa<*(J{vM=sb6o9%Gi%<4&K{Tx-257ZC(A?SMMNMRxvL5DhS
zRxWVJfGEZ*DVLRa(5CF%KilK}=?;ZdNX})+e`K06Ukr_jwxPmgBdnU2Dg|)8l*p#x
zwkrB|1aQBhmm3S-HBe1cnRl3)-0QJPbMIF6b7^n?F-KL1$4-b<er#1W*Ke6cO9~33
zx&9i0qg+IJR}e2b%!kM2ZVnRXqMl7`nJ6nw<P0w&=)(T`4iFaQI!lM*ykxKwEsPCW
z^WnTCVmyoCnL-Dc@#ghwz$rDw02Mi{%(GcSx{s+d<ip<hMBMMmD_z5^$J?!sWquz3
z(w<ken<vcKPeHaAL=CnKo0mdVx<0uDJZK^b=D&sTM5fUrDdn2r75Jx^7v)dz?d06X
z^1{oR`TWpn@7_>(s2Xh54%#UJWf8sKjuVTWs5M-^mWj~?pK}LZM@-Yl;7?D7f$y69
zYFif|5)U&FM%<kL;uQ&IxFMG4M@u`Uf`7FD<7~8HLjkj_eL|PbK&hY$<fBT7gyXoq
z+Rke}Pkycf2iMeZ43GN#p!lGQVZ$Jyl7{Aaj_gAVpJP(?8nKt_78!YB(KTJqLD0w4
zAv{IbNMpOY0r&9wo%vgI;_n$P*{9O6=)6)XT>>X~SeurS898++Yzlc7R}k4sg%nmk
zKb{3fN+(XUcX`ngzqb5m2h7~uLqHAd34O=v=e)J#E5llSJjEH<Ow_may?sAu0ga`<
z1YuEsi+Wl|1NB!r{=H3Kvkvj7e5!an%x?(<O1>h-I&>PC68B*--W_*g7-{<(3`ead
z`xW#?w+<}$!oy_#AxP~d8{%OcVyTA(1)(RvBeVK8Sw)2xmL3=^hAS9HRA@(pHmmdR
ziwx{K($H=IxIFV+&<rghRyky$epBw{z}JYd^Q@Df3C}sGqRGe*O32<BSJ3&@EePm`
zd3ra`aC9_JzGdC#pw@892J}Nc5f;niSflG{4%{Mr96rr~%p4k0%31%n-9ic7&<WL*
z3}FcOsn1=nZG9BFoa>6s83lxIN5=uym#^o|-)&6Op{EW-)_F(W5z8QewkN&_CS&ZO
zXqT55czw-dt?AT5#*<=TkU=Bvrxuby&*d(NRCZ^VteqHWnD^JuS;w`*O4dZ6tL3_=
zk6t?x`jnx2P1~U}NJ=<t>&a($?~QR6X|Bx0nIdQ8DLM{RWv@&15m?n&)hvp=XUPB6
zGWg}rE8jB^=53EPBFN&3kpJ4cLUG_uAfLcZePxhELkyw_5TDHN)=7&{BVcrwlJ1OW
zZk3uY<=veqF`)^4B>??Gn{V>9c20qm2Oo{-AtPUUM@--0TP;f@hyJllq>78MOx6K0
z*&Twt7vVW_+F|^><egh$$Gm0gPS@?R*yG#TDkZ`Y<O@Tcsr4V?V!i0D(McSb;Y(Oz
zw2zH75^+J7y*1rXx*v)Qy2}B$&-)S7JsY8KZdW9Hh@XNxc^vuwekiCw7c?=jk0l*8
z*Vww17bnSN&;N!lX@2^l9<|81FpRx>J)diV$+fO2bqWvBnYS}gkB2L&wU>&586$w0
zRNA-7SCj1*uWH3nD=A(ym5`$o2V)H<Zg>)IO1;NHyWvzyf8>$)g3=QvFKW9)W*NKv
z>ivk-!pz>zy%gn&sxl{|VVr!bxiE{w$FG-fW=`P2y%zqkUXOt&0*B7h>ssHk0?X(R
zV!HzA{xq2N<exIuXS4Yik}k%m&lf-KxA_WxoqvWtp?M5jb_!QF5aS^XY;E9BERo0Y
z@d)+E-kGTM7bj6hAAV{TPy1P6(run(`T1S$FxXFK7lVriD%l5_GlCBjLnKsp2t;-H
zUx*%lE#~~T!}Cm>d*A1DO7k>h8RN=zp#E$xxPaKz1Q1wb>s(FlHf<qtdE94*ovit4
z(+w5;t=_kOYY(jc>nU8DQ)#2|g>PcXo5d#09SYYBY`C50=PBHA<Nja#K@X!GQ8ga0
zKjpP9;VhJ|&|AD6e=$OM!7C~LwPv%kocI%4Z1p2zoem`dRLz4{=ETcqMWhXJxsFeH
zpmOx3E+DwL_gmoCRdn=MRxl-zUKj1!vSgX)=k1KwOt#_$_o-hT)T+@^>Ua$6Zr^rJ
zph5&AiG=Zr)m8CyQlRKdt!=IR=i7~zFmXu~m;A4m8|2ZyG((lC(4}XFXifWu05Fm_
za#90Io9S<+(#3(s1UQ}<`%a9;XF_+pXo`St;omOT>-_Ku?lK}QB)RO{oyGt@hb*IH
z%ZCcxRGXtJ>FVIMAZ+I(pVnrJYDb>bt)_$VG<G85R1z`Xut+t!_n33Ib_^Q+tk2k+
zjY4>?2c++TJ3nwgyge|cLE=!-aKZ}hcD7sJs1Xd&?Km=J%OQ}rfqtnG2CY4%*oZ_A
zPY^l!74$=3N3Xh$v&Kw4OVX<@cJ_3jmp>{f<*fc6M6vECtg;BaXJJ>Ch->|B^R7X2
z^lF7xNsc)z6rG-r4XhQkqgE#2m5KCiN|zGj=j>XQ-L8mnzPaGW=g`C6=P{Guc6ZFq
zU-B=$@O{5=@itycv9sVMOjp0sOV&JKfGDKf(Hnoj(04Ez<!Y`Bkz~nnR$av0{%&Sc
zS2JWASk5D>rxGTA#Q%ryPrsFsJ?+wNmlUpZjDQY9X8Qr-5-*7SAl%KWUbl76Ad#!y
zYI}4c#5;e<%RW*@@Z-7kSG^nAVGoG;MC7Z%YFE5lLK)<^?EHA`A)gZ)(Xg0u#84?y
zg##qTNA9M35c`b~?RdHTty3XXw;9dyyCXx-A9CKVrYf0`fa^yV8B9+3-p&u`<jz+C
z``LN~?OYwKWLM&3@M;K<#~zKnbZRS%upXd}&3F5Y5jR1bvZ9`Wq&O=<^oDx^YaR$o
zB0B#cPGCt<N9>75^)E=Enw3g^VXA!!>pVPT^H!`^V0dhgK}bY@91emYgl(fLeu`vP
z#R|8KvG}zw7C_eUwigXq0JXay$$eu-V!FP&Wh94x$Zjij7FyFw-{__C(O3nX7VDY^
zkJq@pC|YosiaKDl7?L&$lqh|9Rpv1js`Y)YcsQodd)eAPNQ3FypVT4$9e-oy(uJ55
z#xOOXmm)mW`=v+ita-+|(I5QZQ*u*&tG0ci6?JXED4D_RpnG?Wsqfgl9HSG4!OzIb
z9s9l|5j{{Il*1e>lSuL*83(RjFw%ADTMVr|G|zby)pC`qI3RwcnzWMKX|towr5v|`
zk5!)|5#+K>EiqJU&$borU$N=^c9G7a#P^7`H{)LB_lEUfZ9M$g0S@N2w#=%$3s-en
zBH+-O^)hHg_=A&uH3)A)|7UvTDY5-*p_w&Laap@*4c9IPt&m}&^rG#X5isFAB3PGl
z@(<rD+UML(F!boqTwQU8b4F1me|Sysv{FJve<ykGXwYsr-?I(_O!z&r`z~oJX7$!V
z@!1P}f3ue^Y}F~AE4>f$-;O2>HuutI+ib%N=ns4=_to_k--76!6w`r7{D+de*0wuX
z6Ja%rVtrX+-BgK}dLp+ja;i5oZ?008b1dQdul@i#aUp2PXnTuzvxMUmNMP)yD>&mP
zBz(x9pHtx#*~buwaa>fN|A?0g)lY@6m=ALLnvyLfI!b2*w}JlRA7yg(=8{^pedJ!B
z?a6<4+z7vUQ{jkLos}ZmBQ}MGTMYgzqka-|FwSK7n}~_lHH|BI@oenZkba3~6Q|qX
zZqU)gANt+uaiMVTY+#P!*R0RqR(;y0#*-v1pAG)bVj$*A3_d6A!XrNaMcY~~9+j6J
zckAiUHA){O8ynr)E#KSafsY+qi-*pEhh=!2m?+W_&VpTMx$Mcv-{?bQilh>ePH~rY
z6Gy16-G$E&Q-oQAGPc{^hRBL9k6@$hne_eE^rE$;)3{rZK*C7l%kSI$b<l^_`F7Bo
zO}A(ehn~@r_f2t@7&QZbks{G2d=XmmLHPjdeg5HX>A8i3??1VxM3ZG%z7`hZ5#FXs
zl{n|Vn`+*z(EmcH&Lksk9=7|-C-0V!iA~`t^*FKPry`&n{CbFU;8%ck7=~&_*%2y#
z*>#>h8$Lem!6*EWLR`6cXn>uz&Fv^(P+1`3gJ;DnlE=&*LI0_j?ToF>aG_Y)qQ!m@
z5vs|Gl*8N2yB!%6w01LpG6Zwx!e)FZtFeqhR2V&4WJ?%Dw;dksO^^cphBlu<omK-m
zPd%vHS!wHjm|y&AP=l?Y-%kQY>sVRDMoV_h^cR1x$6h3e2EKIiU4gRS?U@)sirL61
z<^K!6i>A>i-b+dH&@C^2w2RKbx3GyvhK`+|=}_tMCxEy8MIV)%E&N!m*hfU8?*5ei
z*zpOGVZ3LO<)2tI)&gT5wZ(PQc_AHAb4X?<2yfu&T$7CLRjzV4{^W4{)-1|pubga}
zul>!Iq|jOUf_z_-c`4dd^6q>{Xn5|ThTtNVX4;gAB4M!nA!7<XfbUOJ-E`#-;6_MA
zN6S-+(qYjxTftB+*NV|dq2}hKC0!9Z)acfHD&A2#CjovngTG%MU)Ez+DXS=~OM7Y+
zCRpdCS)1?*Dybj3szc8s*RRJEhGAYVz9FTw`f!NLU!?M_JbR)kC$g#f^J{#qSL$d)
z+oxGh6^;zN9W{?aS~?i#$oa2-F}oGNErxf~#{I+$lC>oIY<PLK>dk2AOFz+AWjEv<
zcr*g9uLlQ-QF^OT_CCi|1y)?sxc%r<9Xbg=afZXki**6m`Y-Rpx$K@!FG}TMtn6Nq
zRSyJU;Mo1P^T@=DX%f?wg=5SADS;WH)*n&VT=x|pxBuXneYx*`T=_8v#ToCwk+|pq
z4gdtyjwQqXw%w4;k-X;Lktytq(5J;!owRkk^stZ<!_xhS6X4#-&-HCAWo;RZ)`Ug|
zMe{O69Qf#%T=lM@4o!$gPVelJMXgE66`3jG*7ex_-sSBe-~3QAokPchV~T3LV>OnF
z-rR!P+C7ub42kuLu;nJOxo}+GJ!Y?)+)1`;;wV1CTYV{2Jo^J%@~j2DaoAxZ5+cvo
zAbQtYOC0MR5K9s9#Z7VlApvSV8h{pW{HkZWi#VlPQ+HVbmlnTHeus|dAuO!6O?Fv8
zo0@@??vnhwzj{2e#EqN-L(kT^A}*Q(A&*Nv2#hLw1garPLoE0NN@ce4ZciKHOL#+q
znbNbvmIbE+N=h>Gj)UD=Tpch%<Kd6n(e$g!i*fi{odCNS-?9ljn`zk_K^PfV$(L}3
z|GRaGABkW@#auJ=boGJ)mM7s`qFs?>NF;+@TB>uF0})RUU^nW+y!ZA$L<;o#(|EhN
zi+*YBR3pvzKd8Tql5u#v9wc(-^4Kg-t*%JSU?LEN{=8Z3we{@%#}2wme$y?C2rthr
zW|?1jL_ByT0`~4DwGqtof_b}FRQ}9UT?I&x?7n<N3QBhxl1$!z_X1_#`gja0m6e#b
zRrTe!bg#^(evc7Vtk2?6(KuL07~e*;2DTC{j$--5JYuI@)u%x3aR-@fKesXH4kFnM
zmpIw+1*kA47Pc6TSicu9PAU9_oOu*$=?72nV#{q;lP*#%G@NSCWs&DGmX*h#eGfmo
z`;Xg3o1h9u{Xg<^IJ;4!aiQ)Tecm#;OdDC{Mz`pGj_Ir?!S-wgcnIY@poT<xqg3d3
zy9<IFBE=WXk%%ri!(Q+Tfloy!g#u>O>O=6z?f;<D%v^{zh+vPiq}zOU(qk}dcf64&
zlchsj4Ax>xI_PraA%DA2Alm+!<YnG`eiLnQ#h@4s3rKhC-3Q5D_*hDIduvl;`q77+
zDSnK9*aTb`r{;h1X-*ayi?SO|rrp1cPz%@~>w1uvh!W_yCmGAmhTL0IFNwTlr^*<(
zzJ8Gx^oT+w0XB~<K&;7Z56P3bpc3W2(Rh1({}KS5?JtG8rFY?-nshng6vE%0e+u|A
z_CCUGJYB+idwc-4=I?C64lhr12@eQ7lwsFJwC?Mi@Ly^u^W9Tvoxg{W;i?(3qbI7&
zo7Z9VFMkI6hNYAyn6G2UiLHV{<q<H!>j~OvFC0R+iJp3be)E0qeeu#B1@?&4)q6={
z7EH`m<q|Bq8GI>r`DXv7?s6&y<|M&1ktGy;*KIZ)-tdP2?K;<V@;6l<`Nih@SWRVd
zmDIDF5-PPnmZR#u{!(Cd#(5@{CXRgCj`0+)*F$%=ZoCH<<%h>RHw9)gybLRtc;Iq&
zjgo`pMjh(LE^z>pX_#e_`Vc^ak#{`rZRyCHC*h_+ilB8~1;Db&)mIXpo{#5b(0A3P
z^of0nuMm<#;8Or|B&OtB6k>^HX@-U1@i{!CIV55wDRC+54?7}dj_S$Oj~9gWsEBkv
z%=FPyHbrTXdpOdqwrqG#610}+<>UE`36b}Ny;x}10}n<+sW;IrPN|*@aG2VKXpUEI
zrUyN+Jf1y!OJI+v$?h~Yp?dFugHVF5_Z!jWY)F`5ZM&V12l!W?qX0L;u>n{iy}xYI
z;ZXw5h4S^xF6O>i5`Mb@EmOdsHnU>|PC-2XP7Cf~g_?)nOOx_H6o?sAm20*f<f-~4
zf}n>-O6;NCwRX6luPTD#({?ZxgggJx3Hl4v6@g#t6K;70^jAzCR>h0$c3-pD8_y{c
z@9gCoewOZdKjElRHLX|ncxP9Wq8AebnOs_31OX_2bjps`#J-eG-aEfjnkU<CjPv;6
z)?#-pY5i+$8h?vXugsU-=e-n{T&C?OoaEo7Eh|SZxo04w^lG|2f01FMP{%^$S_uu#
z1g-p`lI>rQMnv+zt>0uG@f{wcwyc*M`}4+S?lBQszr@3r8wnCekY)njZsRx*`L-vu
zaN*Oo!mrD2HJXyORil5nE67R3+UcbCYZbB&@}EMQyFmx^=AWPetcVIJdSpp86<Z>;
zE6TPj_$kr-b{g@UQ>i=KWSPm=Y82WNc^dIITxK4a7!Gu3{XI+!lg@4GDl8@jiL>qT
z-@m)s3eZ_hJK8-pfbSWC)^&rPMRNl^iGsG4#x_pgpmOhv7`4?0i>Qv6eJYQLNf$UX
z40^<bZPTS!X7;OK(ixD{^B_kEQ2V1uxZJ-K6mX+s^{Q<K0Xq&?ZqwMDeu`9!#c}{_
z>`4FJ)fJitH@P_8``UHtj+pckQg~kL-~WWefe|wpliD7x+ZAUL#B^{umrY-%#}Er%
z%L#h*i2VebA#9V%*-S(NZFsad)?C)0*nO9<0OGNC)P2sFP>wCT$n#UIKD&88ox)%2
z=uef%VXXBvEGNTAnHcScPQG+V*HGlx{f3rcU4AmxQvFloO<Ds%q{i#yYwC+)T-p#N
z$#Un+szmP%AR7_e?bAM}+XJH5rVy*!>af<F=fB5aMp&~}h`=JNv<kS<O0E5N`!4p~
z&nP^&#yt}0h20Kb?t2A97jw!f9HrftbWH?Fd%rfd{V%4^*i;nspB*m@{le;d-I&K!
zzY^4?X)E^xq!KZGTl%cl6gkYI&D7CJ8)qL}mPfMC<D_eDi4nSCEe}3DTTK8*CInrx
zs#4|jo38);SmLQNC7q&c-7Uxkbee92m3ukOWH6-pPx9dS*LCqEC^Bt?e|7ttEO5P#
z$)z#q#q-(~>VG-a4bRX*Do@*2@7jYh9NVcLrv9ScV&T1OKrKRZfDclDq%*TCi$PC2
zhAjuDrRYkx+VaI!x|?w;6Z1od(pp8R9q3pz1jMfcNs_KLeUKl{V1z&{If=-G%qglQ
z`vl((MO<qere?&<D~}1_vrSo||6yW8HMNui5zALsbI!rI-l<a?cd=y$@{kSDDo`^~
zmhPCRv1B-M>o@TZLW}js5>p1~`eIu05|`DR!bwyg+6ogn55yuHaHHaM?dWz@W8|ZX
zy}dp<$ny1s%e72IlETD_2{;i+xj6Hbag%8*3&63E1l>+ftiD~P$ZJv)e^X0r)=j%|
z$Bkpd0#;cDCPk`{49VqEdUZm6#S4JWW7!bpGD-?LCw>=$nc8>Z4gK<Kbae@ydReOq
zy*KH#LG@&q0unlNp0#aFn#MJ?<KbD<at+*;aLj?x##pLvuK(um+Plr$FrK4+7szAt
zpLH~RvxB4bB;@aV%)Z)otHsudQ?(pJS<wckQ00)+WZI7bwOK_BK2fK_8%tIv8ambM
zFjm)hkhKH9A%FZi%2513^c~o?)6e*&o+iUy3L*~m)V@wR`|s65YS`txys8=lVJ6&i
zFg*gH!gwdZ4BI@_1Fwt7m61YqqD-)y*eDRg9DYMJt9+Z$NQuO1eAr|Wc^c)08HP3^
zwBW2WUZx%m{~=D*4YTRDM>HDp^o}g&oz(r!C0P^z>pr<*edkb~&KNUdr_Cw^cn^>X
zW(}&kyRzy;k|1*BOpQ6<m3pTzLXzXW(MY0RA>d3Y_tP}WziJdzO8tFoQq}`Q;)}Zn
zMuNYjf1c;sUwRI~8wr~=O5FEtlq)qZgJ)lb>RCWlZdxR@V$)|vGx*C6C+fbN{vWE|
zGA!!$c^{^`mPVwP?(Xge0YOO#K~lPw?(Qx@6a=L~8tIT0q`Q0RrJoP?eSd$?@qfX=
z3tlY8>|E!}oO901vl~;sZJc_$v&E}wu<P*7oohi_?!W$i_yXBM$cOt5RovABTz|6K
zsj<nXdDCAJ`X@&MTmS?0JD71hD)8~jwWVq+h3#I>`={x*nNWlVhIB=88q|fMpC_F5
zbdwZ9gS68AHc=y;7~3V=h%!<HowV|)<B@2|sh{_dEs`>eB+3SdRY>NA<ooE(7TYVS
z82l`*Hgm00iXpqa5(VksHXNu;!S(`sQ?94hA;Gvu4?CZJdxqfjKfas@FfgHAv&EWb
zBh1U}R#_&X+49O(0+I3b+zXE=WP`PTCue%7@kh9I_8}+HFpT-l_%fhl7`;AMOcT=M
zc4g`GLMM@x1pg(bV=_~kbUkfsJ2=B@<CmKcBUJXwOYAgl=ylg=)lC+swTylBbGEi7
zFTA}U8NN$?TSc5xKpEvUirRk*zu=elQ69B)s=ur$=#_$0Xy8u7PqwHe_I->OAas}M
z2aA8KJ-fnH6h=diIAix?W2i&uf8++1ML6Qxt0!s{_I8f|k2|h(RNj9$I!8UIoNJbW
zyCG++4ZD2Ju0+<J{@6!0CxOB;{OAsrbPb9b>m35jx_z7*11h$Sfs4Ui;c%oF6f&}u
z@rjF8?qrM4^{5l(Yq$Aoo0Q4Qi=`CF8zUmOFY(IXCQVM?+wws2w6h{Rw710bB5R0!
zf&C?Y3o!DCh^5}#HzP%RcfSL%@JMa;OfxF|Yx4(%r3g#Wl!>yxlww7Bf0+-X;+5YX
zDA3St)*8g$5~@B8gs$J=%ydQKY799Cn8(g$mKU^>u9*wT9rCC*GWEX%EgU0xBUrgm
zd~Xh=#;;;xt<UwKg)gLEr~0h_GqI*MFWf{gL_ddVJC~>5oZ|J+YPH>w_`bNd!zTvm
zRPMcYm$wk`MG}J{*7dxp>n?lhbMbA)btnl?^NDe|mHFM|xMC~&ink?#$6dB7?E?b;
znb$3ZGH_i#<7^8XC8Utv3n7bfA9aC5v9=$7N9<h%{ZLC_MllKcnKSrZPOi=#dAk#(
zp=W6dDa+iu&^A*lHdebc0$(eHQtiGLTyq|fc+&YWgSurMs`ll#&I*Hak&2$h($6Ev
z9+Lv~-g*iQ#YALe7AhPJ2ZM@)7C!2a>n<(6V{UifoA<|-Zj|*tq4_abF~4I~?uvXf
zwaNdcL@h~66GX=sU~clwBdH{()NO5DWY9T*@Ry{GKYih+``N|UJ>=zO7Fhj!U15U6
zcpPBv;5*jit+E<9BZk-r#ua!@Wm6L!=Ofzl`(|oCta7yh?*>V_X9bXUMf$J%=q8!$
z6bu=BWKp{bl^#YxtgZdO^bif*Dk#ebrcmtSw~)XezdM29QznA$Fw7^lE}*am-u0jE
zNaAq&)_@x#m{a^C^5_Vg)!<1Z<+9&Kd;Djf|0VUKUM}ZC>8R(KCqD#+MDQrzNQSWs
z@&^q7%-jzI&L9)Z!ctPtoECeEB0pl~lM1QBpO3PWvYw_J1hr#P$hmCeTesbp#4}+l
z+Cm(%MPc9<Fw5Zg!C|dqFD%Qlu8?9x3JVq}<$6reEgSHYHdI<4>yHI9b&iRY6>Ru5
zM{cv@GL1feFDf1sycw8quq(&j6pruCPJcm#?O<+umR?0f_f8I-lzUQv@<yiIXRSP<
z2lGipdYJnCz+SVDy>KyRQ#ulQaOO$$_%Hlp6}Ge|Vh8zqu>ZSS{xw<}og3HbY!wo*
z>dJkj10_5@xkKk0nb&w|x^KEj%M2q)Lu?5qtruR?zO_oqM$+y(0dcFS2HOXzaQt0I
zq`mTaXs61vr@1b<Wt;ylXN80gv;#>2-N!#6Y~G9#n22@esFmt{6+o%!n7=E)^k4ky
zc8E*sWb@yc?}nLb`Xl_|QyMZk;#~EtkPM{&GCr(uH7{lFBsR|wE38{Vg}Rn&FebaR
zWK`ubx_eot>b<YsN%pSx7X%PK(fpkWE6dx|D^|nxeCfT)WFiraAnE$@z8?o+cZ+QL
z2{GLC5*!Eptd>@kf(Dw9*7&v{uL-V_Q5_$XT2Kb&2}RRY>PY4iL!QyY->bKz<SV|c
zwIlsnb?^>lZ=iCvizWwVMMzl2CR0R_Jzsj)dI+Nui#x_K3(C<k%|{0>H<LJqqEP}Z
z!gkNz#$ZK6HpTS30B;8w7$!O6bA(4d@wA7kZH+M+4K(T@C}{Tv^|M}+i(OfYCKYx7
zLCk}bq0G=L6oaLLt~gO8T}wA7au#&QYs;GCBRS;DLEAsdvAm9$sK>V{{AGZ+*A!(^
zE*d2(G4wfu>ol9?{0C-rK4v<emQ#o$_$UR;IsC7PIV3)5yyaRA>~KD;6%wx{h8#_K
zii_2FV|2LPsKa97QhW)&0C90n3QDk=oX9l`@y}?0=Un@dNYxyu7N}YPSz40DQ}=Q#
zw^&*BQ8o=Qv~N<!S|t8z^K}T9-Y{6HAnng7i0zewYPOp=EpphYqSaaf%~PDOlNdwg
zoc;jOnM9H`aqXM_DL^zzrxT}L3s4E-BmpSd$78#^#Z2)ol{=pvTn{USL@N|Jm9X|d
z*3J-uWa*T^7S!@0)S#Yq3@aI)2m(a#l({9KsDWK~0Ru+MLcS~0I@zr}3T!6yr=~+?
zau_UqeQJ%+3);|_w+gzIW}(3!*@I)X?kPGexj-~ZTFO33cuZyDTaR1$wV{&AD^Wso
zZH0rkU|flr_O!?oO+0QDVU{tlbUKq|@B{M}hEM#q*Z;HtUCK2G;nap+cltdO>Gp*n
z*=IH%@NP_nx>;E@^=s!d;DBRZb5K^6#Ow5((?!hws&)YqI)M}B^xN~sDt9E@5!0dM
zfDhL2V@_22LM;FD{iAqy!8p^FD-?*=C8d~902wdeuNYC(Dk)JRp0=P251jR+OP$6k
zQ#FXZBk+0rX#V&{bTn8E`Acbj3A@xv#7iCD<XUiuN#Z6&KO-|WJ4&W=JRq7`B1_Up
z&OeHN$9?T=bIas1fbW1td^uZ+6vHteQuhHnS+io5yTomNI8C_0$XsC*LSbE-`@WKL
zrl5Z6q2yL;V?cK1L$fYhyx;zMQ$jLTYG<Gv$X-<^^j4zJTuYgp<%YJ7eBPeH1olHg
zNLzX)p?_$*Pq{e~kD!rF(-1czGAgQpeu9(~o_;<)WMPA|))|ijiMg;!Cs}Hpop;uK
z!Gm^ipSZVvrdcMLcQY$R5lh=D<%gUB7Mp~hCVe$^-J3g|GPRE@p+(6Gv8kPg5bDGY
zxrp0*9VUWU`-uiy<P7Ei=PRHa9=<qTEidR6_cVpS+%Llgj@pu$!n%Zkp$1Fb&wr}7
zzCuUsDtk@EFTn4=tuQ^I3R3?1lGlqa_dlgU<5D%y1en}bhJ5(L@)|&$rFTjQ<4VL5
zWJMjPo22(}+{yAJQT@LJh4z9f>kXmqzkB><+JC<cKlZ!`J;^rgd-w8PL)XLiNg6`a
zYZE*+gU2-b&QH0@E&D`;_BJ{F<?*O@N!*I3O$^2k?eW?}TS?CXk2iV}&>V$f)3^R-
zyOT~W7oYK?NL2{9U$IV@k8kmx$=~EWwKwr`)B5I1!g6^*bgzrI@rz^LG7?*x*d=l0
zCr|zA%i}EH)3=DN8du6?>L2n{#q8=$oSKx%XX=jzw}Y`tX8?g_z8I19DwvtJ^>4W$
z6B26h+on!BQ(b=okD*#8d-_)eP6jmHl|lfb=NU5V-<+L{&f7V^5AMNRoRHI#Pa_40
zwH&6oBB7Mq;-O0tUnSk6nAtd6&HtVN0PwSj7e0usx1Bp5j~BNBze84k5mWlZ#2S8@
z29@jM9<>Y+7Z^*1{Oo}0LlH|PqFPES%RBa5{J0WUT5q}h59aOC0%-p)GX!FBl_a;?
zuZ*Y-QuwZ*)v8*|BIHiZ@CfB=#||v$U$UMF@d4E`&4z5nDvvE6LcquIul7}Nxw9tF
zh%vHgO7V;K(2Z4QG1swX2vZzhI#KHnoJWo(NoLf{S<WPI$}&{(Q_9Hin+$tP)-`1~
z)f46wn2jWjd7o%qO#T@II^9=>DI_&#F_tC0oJYk`BsKG4m0j*S9ycQgvvo2OOq;U!
zax_3^TBj%CBSfh9C()d0mweOL<c}bHxJHdZo^R-gonkHV^#s~m^1~(&v1L%1;jV*n
zX*#A7r9Wf@aPu#CB%`O7Sc8Pk*zLHvO!&FVq4vP`Zdyys6ML~5<jk~nUK;g#Gzc(M
z4d^%ks>Bpf{1Nm8g{g}{SI-*{4wK)4aNxGLJ)nJp`TZH~ZYX0Cz6c?mj*s6YO)jKi
z-Q=c0ih`PJm**tTKJUpmkJ-%Kxk7xcGpcwpJ9lPIdPoE`EEX=WM2!B!p?`kWNSO_u
zfCmwFojTxVOy}|nq8C?Zg{TQ;jenh!(TKb4w8VF6E_<3z7cHLf!~tjP2jX(e4E9VT
z8c<m9t(W;>FVg&|`F=;b$H`RLtWXw1B-RBG-#FybZlH}xh$#BMW&Tn!c9IXofX}y>
z_k088=O60Y60XMt6E<XWE=%-Ra=WH*`4oOd))Rc7l|vGM-^AlA?$GUx&aV39Mpqoe
zCC+A#|3_PiB=KxnC_ove$H6xjs6;a#4Svvl*Mml4#F6k3M6aVop=0pFyj16g!&HSV
zG^W*qmhFB2!_P{`wZYde?cc3`&NE6<J}s6;vlruV<!Ix}we8Rk(iFcLAf`IYmFq>L
z&OuwN%;|@x$7t|zrW~=veDwAzz*46BM|u|C77Su%h@6|F5W8r${<yPu5LbhVY3Q|E
zXuSp}=K3xmO_CDM%lup@e^#u0rttr9YP(c)FSs}`CSFzBeMyVQ?oDce=&+AK5}Oy>
z5-j6x|1SKMu<PO@d;k?(6UkBaqG{R8ucMU43O>SD3V7X{XvEn@tAKRIloLcZxfz|A
zXO_$8NFd_EA)<+W9ux;%wom<sq#yE#H;MOWg4j(JQ!pr;>nCSq$1bQIpbC=yLFiaA
zKuAmYV2!VG^QTy?UkSU=pESaPg{QD$;Ud7dK+-N5D>1PWe<#c(ZAT-KwN=OfIaEas
zpPJSJeyxZvaU3%esU6s%sml$RY0)CjCPNPXGW%t@Bh3!~I^uQZ_la`8&J$ee_R{1B
z2?}Zh9jU<5hn+h7Zx7Bj@^Te6D>Td$%X8Y^IG+h<_B}YG%81Y`PDe{R6*bE7pC$Sz
z-OB(QPtddXNATlqJo((&pFe(!0V^?Hk2f2;CkF0l05tfjU83peg#I|{G>I_(zYGTx
zD`n#bjOijeYx39wgA9#r;(^Edu!?}i+<vkP`cujm6)A1%NHN+vgocio<c<`mHtki0
zqkQ_uiF%wxJP@`RGn$#Q*bgocH5$4eG@MSan7`B$&iS9zcP&Sl?Izp~xEU+REt%+d
z?o{VuZ=61h652e8xj)>yM~QqZxW?K^<jMY%&itS?rYfC6d+^Psfj1JAkN&Q^ej<an
zs8@+@uZwDDN5{{@`Q~G*+FKF}jUihHc@^M-g12s$eDJt-MWv-&&$?ok5h`7fQp-?%
zq$IOs-#&3##j7RSM5`ZiD&qCVN*1h1x4Ak$<Y4)w0$PudnK5y&M~@O2@LDd7<RS@8
z*ffMgu&DlZ)CWMJs)pAe|3mjFaIE)!kr;>F(d@&Xl%h5nAnu@$`!ylU>$M=b5+>O3
zh(x?y0-e1fx_|V|@BXa0EY;x@@UV;vw4%&{8sPC>qt^cQAN*Gg_6~u%s>c^+5CO+f
zP$IfB(m~d?gE?9LdT_M#$(FPE3fHR`Zk^jLVJJc9T%=*5s@0VU_5E1*K@6-kMSdtB
zEzg!M#jNwZuoIy3`T}n$p?xlw${BHUXno)QX-Ay4ep3=3taX(C{s}9~%t+Dj#>M4O
zkG&6ybx72O<je4)qlCWr=bM6IC)`&sEeVygFh^eXT(tQ}yqxRgt033H^5N4AHPuP^
zhonmFlo=L%!kRFzHx4vkPvTB9g8!Jm$or_>YbcSkpS`(fHj9DSZP}qXk9J?jXyo>0
zNhXE;BxbS_Oh^sgTR{7(&OayfSqA!-{(F`JbSF^_q(xxc5gKR@N+b)9x$gTdB%D+f
zW#4(t&>!(HOg{l7Btg&A6jO)v@%X`9f_z9Pm&mc0aDwUmX~gL?E=A=d&9fjc$SL69
z&HXT^cyPc|Pz<S%@7N)c&quG3t{B*{MM3Xx>&ng`C~)!_x-erB!s(Dde*pcD(RO@;
zm2z~XL>%&Cr`rG0*y3#Dp>}Nd@xYn=TL%dk^G&Zg{)eDK(=h0-3dP>7Jk>_mD|<7}
zx)TIiL`lpFojCPCvrgAUu_Uk`jC<<T>bLEk`cQU`+oz+Hikaf_F<!q(D?U+&P4k-W
zC^z}&*1OBAGTVt?(a>UZ-AE}OS^>5Ae*2zvw5@t#8lNr90<S_;hKKO<17_|Ld|bX3
z@caGiEJW^O70gNGYCp8M9-#tWcHy>-g+G+IUV~mjn&v|q6&1inScXPgTqg%wgD*=f
z%QaP65{Er#HvoX{|EB+i=^<Gr5bxl(4gIS=y@EnoMixhy8<tl)thr6{cY(B8A0zK4
zDBTHjfl?B!VXE)HEK_5>nOqF|`uuc=*W8l6;X~xYa#q*bnM}k#&Q4~1V(@G1ezjaY
zSw6}l!WxR}zsql6veX$N`H-yFFpG%yvi)+v0@$HW)m6P0XM4}@%DGOCo8P~{*-k`d
zDE>171SoHwW8`8sGz!@p9P`+xW6%a;{TMRB-CHFHj-kOQLcC+M*uzIE1;->RjR!fE
z=@7i2F&8`t_^^YYyC9wLH5wF#MuUIFf*x{k2<j|~+SQ5!y|DVcG4-lFTQ!OGRZsN%
z`wg*POA%^4FdEUGHBExt#Ig4a+&!D*Qk_hP&l-{kZ!EFC&?>|Rf;4??CGcHzRZ@FG
zjYM6Ruh;Zj@LZQQ_-5HChq8NC3Fy3T7wFV<8H5W%ebx0VO6Q{w;n!$e^^t<$`PXD-
zzF7nrgcw=78@J!nI{VIicaT>a9jJ8F9;~tKxY+wS1>MkzB5V2~*OQOrBG*g#TlD+#
zPU38mY^c;^f=YuF8?kbDBJ00g)M6}GQ7@A7&Dp!}Y-4NVg>moK5XQuO@fQ|eODvml
z)ggkQQ2m#^&&EF;FUL^~U_II`B)jiQ5RVPGYth_Tc^v&SyG-`wEdCv#nhuqz?<(2-
zz+i$m7}E@fTU*Qf8#X7p5^>_Y?cnwPj_dZXO3!~V#714U>47q6UUkXVkS-BAlBS6?
zSTbP&RemXLWO15&cEUJyu=x~vkGcu}X1b`QF7QOLX}NdZ(}*gg!SvVMTuawwRL=t#
zjo4Y7{j1O%4e5f_CC2g#u%f@0I7?Gk)WHBCmEW0F8qnQHdQEh?;P_LIT_ND>XA$EL
zYCbs=bg{UsyJZ{2;c*9nWUe|_N4<w&gea)Qxzk(aRy=-`eed0Kv3OvFO>7c5061dJ
zKXC56ZZ~P^P8&wjNNpDyibQ#^8;Z%iQ9vTeNb+5NA1me3iY>|8U%j`Ub%*XqM(OyA
z!YC6u`WL5y*tJ1oNvWaNw9;EKDmXt3qe2~|_I+#Y>ANf{9xdgF63jYJ-hSCfDki*1
zQwsLV9w4@2dt(_HiIsLhnr0tFt?=x*Zivs}pxmz3z;ul9tq@kZ84zw|4ReL-0|Rca
zO=Ipx*#(9uMa4p>ZY%WH_a}+{cb3N9k|&{?rQgCvKb!u-&A&w=_BGUQ;^k$9UAlHe
zn6}=(zi&Cf)!>r(H;W86BtXj7(oA7%(3gxGIXF=a*pOj##yXcyHe2nVCGtWL|IRk?
zBcSP|UQ;rD^ggDi*3%fA;Stg=NYzcjTf(JUTkn^DN8l^|COAx!VImTnyGFJ#9_5X&
z0{5Jc*!z+f`s<DsW3|fI=OAE~AnmhSQ|Jgo9*sh&?L;ZwN{4s|exzoNO{DJ9GAv&Z
zpE>y!Bwl}ujNGmKN`A7V^;;fZihy}BDtG^!HTq<j<|dvT%463nC6Z=}_jIMSpqQ2F
zo3k)Ih7o>YkahJk(CFM^oXD3=rYoy2MZ()^<{``4nJMx?N|<YT|A@$gvf?}WfKpTB
zfI9n<kto%=;EzgZKLwspDTAR6QbclTm*1&4`RJWx%qRIsD8VkBdPC_IOUs#@+*hHH
zi2-7t*k?Q;l>|;eNMHEiw3)Q55T9HgDt_uTvq=D=LlzqVRX0t{_ai@-LL_g;F#)*R
z<KjVtgZwV+Kcy>?h`uoawi0Y!ym&mOpy~xEgHvrgx_|SbHGw|kKZ4K#D*u<J9bWLf
zQ~eg?j8IWk+%;80#+tGK?35e#qAbSwkTE2C<0mgha10OWv=f;{#GHB)F3}po<qk*T
z%?m~Ts4H%?VC0TvWC0X%*zmqJv@gWzmr*6y5N-qsQxbc!SZ8Oona)7hV)G<MrC96Y
zlK)2FMSohRj>xyhO_6Lj!$Brxw+9p36^3GFafOMPdFvs60)`8NhG4a)uSx_`?1%Jg
z{GZ7LbilC&BD@u!TTiBkNHmN-{N;%x0Zq#1f@y$a7xM{Q_W%hTz1~?dh_x6GCO{)+
zpN~c=hW}L7zDnOsGsckcQQPD$6!TRixR6u7mE3ze6f9k&)Tp@g`{3-$8~PQ@0Qq8f
z_ZZr<ulvNhho5!OaP2!TYzeHeKG)$#0h~{ht>nc%O(AC(&RU*+F+%vhVj_EB@Ta|{
zt$O-@lTvov=eH9A|IXWrl2MbxdeF&9-NM4+>qhA_>l+zCB{ctb=h2tM+01_^l9<9G
z{T5IRbPUkGNfnZ)k9Pt#LrApy;QU?uhY&^SK8nm3GwIb_xq*jl1?_O_LDcWV!$_dm
zF*~Q{oc@T*9rqYm_<O(hmPNL|W^jqNg=X#1+aKk24c)Th(Y<jq)uz=}m)-7bjt+v0
zv*gYywzXf0a5WC5jzj=gRNsj={_P0I<p?0X9?kFGo6`~EaYqxsXytc(iUVVDPLQQ2
z?<VmO*P8ZDtM#D$eHE{*Cg7Ueb((1^d^{qb|Ak>)j;=a5x9GDpqh4JSwi`kr1Yf@8
zt~tx7MjuU?*n8r}XUI3aIJfGch@_c@AAu}^RyEp4s$GeI(^4hvCjqHRh6A`O(<&xu
z*C^Eu6r-nLfCGw=je1in4Z)5!9?^d|Tclr;`DvU)R$8_3gPBNEy|EM>G~`~B7imNC
zihkuwKvM$$9Bmy@r6Wl9JCmQT3%7Y+B34oTvo0~RjLOyu1EE}sXeiAxX1k2w@;vQ|
zfX1-OJwYLyG(Y5@G;D1<45-mCx@yPre=TvgMDOiwBQ2=v<5+lGy+d$*&VI4mK<&uR
zIJ<F0Ha1}df9!;KYbW2H08u~K2F~)n;p@Lb(e59ih;8im8@wmo-IydH&%oz(w})#6
zl+p>6%W+xXh=w&x`-g||-<PCw>Ep3}^~uR!u1~9!i?*D&T!}{P*s?B@^xQA742C4@
zu@joo=2zU~Ubj4|PbZqK^)+0JI+APJOGGgW6d=J3U%mhM{uW0JvdUjS_DMamdvaZ*
zg8e(UYW?uyDBrP(2%8&(tf}%jYX;Qi8;^C|?FDf)^FpUhOG&InuIkOzH{WfEZi=I)
z#2Kz>ty%^X>XI0Ll2a|wf#0Nlc1Uc&f0t225_qoDcO#)lXBw)<Sv)rEZGMiiM?1CU
zMDe;l*kDQ{Lvz0HtQL&c134oJXARLBm7*#~%#d(FBS9x~EKyno4jWc>k9E?3<Ctc2
zn^p0cFl4$Dr#~H`Ryxw4v(D#hP0;iZEgYqQY?-~3pUiOht3SoEg9W8vm^O&hqPpe9
zpxKy2c9=IboxZT(eNFH2AYQk47SbGoz284*hzp?MJ2rOq)g(oea8yb!N>|r~vRKzp
zR(+Dw-Otw5wGQa~A)VutR5uqykn<ePpOZI>85JAhdbPVR7aTD}=@RJ$P;@BdEdDJE
zt2$1%L&jDWPheao{GRkIt}Z^<E1tIr&JKPk55tx5u1drNmA2ArUW)PM^&s%vFYk`x
z#iYA=M(&Pj$jn{58LmuG7p$6pwl9036rUwIQp?0i{jyrD<C_5-j{Wa4x(!-`#=uXX
zUY9Ys-FUV7$fLXoemm5y$k9a0UovWq$69x%+u~_{%_~{*B1?}Qp^i>_b7jNZE|<_P
zS>8mh-SM76=l7n+XG;tW30;iS6`F+Jd<JzPrt4jfNPu)gW;7m9A>*zIwN6Ol*dGG5
zv!`)s&!3_paK8yt>YR^;O%sN`q+(s6U`HqU*dD904K>F&8VU_?uYgaIZmP&+#=bH@
z$k##CU0|Ew93+KT4x_*CKA-br1)V5cfFny^Dw_u5tO5O6gEk@*|FZ$&<z^50aOjvB
z#1hl%4o<=G-wZDnRiQ4EYw=SACW(fbl@(>li9y$Tp}M_;`a4%wl$aPmC5Z-H>0V#&
zrJJ42TsruOO=p(w0WE7Phh-y@e01|6&~&8i?|(hE)|-cj{bVUX+82QfIg>Z?dNj!u
z^`%zzx9(qC0@j*cUfz2UhfjQT-+^mybjGjDY|H+^3kNOuYm&|u@n0|FWBFQ|t3K4i
z6GD2;2q>~VxCR*Bd^~glt_X7Pf-xoMB$#Wu$1{GC<oQ$(q@I0mS-Gxz@?krYT;%mo
zZ^pW&yWDq$K9smc9H3ck+?wYuowTd@EarS}OeoG5D44(iM;Ih&mPM}YoZba=>9OO>
z_?}k2%CpoSuJf^U{j5o*J~u#ZR!42R>k^GcXCm~=j-S?{cz|Go!MN%bk-Zr0L0j1G
zf|wq;I)0|xtrlf^HaR8Itvj%EBXoe!#GWRrdvNI$8p&h=m8ym)sBF;o`wvBjggK4A
z1IF8KA>l8bnlROZ7x1*xD#c<ufUeQ@DL9&5Cf>FtOeO_-MXjI*eUKX<{s@iY-S{rX
z9s8~oAg54D2igCv_)h`u#20QS+%lR~pZHpYusf4m9`SzQTf&BDyhLzF+q+(T)UL1}
z-LP*Yk1P`P{vHW*e2W~79v0-L{_ogxY^tlL`$;G}f`V#0%su1a16PcF_}ed`7IPxN
z8m3cU)yi;8f7O3uSjgJn-k+2{FRw?ol5`Yr4DA8P+gfRMQ6e_>zf=#Z6hSYf-)(`K
z9(x~k_;yHRLCa;KEaWK{mB#&Rt$ud222e|LE`?`FPv2(K;AQB>izZrz@&s2=vG-1k
zwG(2f)TL;6mt<K9c^L)8@xOcR_cxgH)QnY37!s)y)X<!h!#s7Y_WPsA>T?~(HP5#9
z%0vhuHuCLg53HwWcP)DLm{#$#xiZbrjd<8P=j*FB9oIBWePfY2dsdm=%=0akrH0TL
z6_i7@H)kevno7xiRqCkK4jOpi(#H4(f_INf3BuIYvARpN-wm{H*{%guis0~pN$qBY
zfc9L(GFvKtdhB<V^QZ+Tt2ab)i0xnJHFNE0HrlcVh^xh`oPvS2`#VpdA=k;pFg%I#
zcoj7Uh(H5ycu93PkRp8FS8h<{dsF$}-*kkJIo8?jm~q7hf1`ZoD9|A;pMX}&`?t*I
zRby*y<d;W;c#R)Gy3xeUhPy2qKlESi^AxxWg?9BGRt6Xcpc*Xn#piUrp7_e1?(6z-
zw(%69^m?Af*@!XYU`$bS)ZFhf)wU2jSZJVdhMXEuRDj-<bYSeSE}ZxWkYSc~xNx4!
zg^Dm&*SlK4=mYGEoMe9?*&lund@u6~y`#O_1vz9{iocrtyZtg;bzLxtY&GgbC(hrW
ze`|OK9XzeAe39!&84d8@XY|vn<`#&rAED>=0USbt(>Q-l`+{v>fP{q=)@Grui0^`B
z<}%}Ug?hJi8iJc}B8lF$i%GW+RLy{?^5`xtrW9(8B>JorW!c=RREiy7x2Yhv+}H`i
zqzclf4}{T)=6&7;mc~&E>+(e-N=nBznHJYR;=S(scW)WBKRL1&B@^6V!uGtB?Z*en
z9MDN#%zXkIP5sa$%rdW2F;bi<#-m1~P9Mfa1Knr4lo`Uw_12#=Bf$%IFUT$reSXe0
z)>2+#h|=yAtf<K0nGEPThk+wyDq5Y5lsHRYOECdD3?(v*iC=d*G=>A>jot&qof?YQ
zfRd0D>of4`P`XJ!+S(EY9Kfuh6#bN!O2jX(M>*C?##*VKu2oILt}9yc{j8N8WIYWQ
zb~gqw%VGNw@zxIte}`^y@_pWax%-6$w;!;%85}u&ux{w_UpeI$D{zTjVQkn%B5?<4
zxWBLV<@OZQsG%0h^@YBBX*BF~ogVXe^^!x9Tj&0axw1?vz{4?cx}2P}@$`wpufp>M
zpAM}2Ov^vHeTTTJx>>|y1&+(rlB0RYYV`g2^TF5C;aNY<Q3`}Mh!#D$B@t$@?AT?M
zvmf?>sCV(MfROJhpQuxu+G<sOU3mXkfbz5?w=Ys<$2nGvXKD9X1$Ji_BQukQy8z!_
zNM+cpT#CJ0?)q6%L-=XQ0Kxq2#(5f+)qv%!E$hL_w~CC0oP&<J$K%6I-<XA^I7L5-
zc1e{Myfi7hrOaf86>8P!Tucchp5&K>qt^N@kqaX<#y$4acAIvpiLAi}Lj}gghf&)d
z{$4Ejfdp4##$Oe!ywJ0TFc?KsdA@nc(1z6Q^=lv3YO+C(bmSpg8?pvVGS`M3ZOY(#
z*_K?m!r`ddp|;r9ouAH(WPPOQ72`qD^y&z)!*uqF&xradc$4Sb5P|Wm=3x-bensSY
z&dR1rt+KO96_}oQy34{{_l*xAM)fsRo<rR>=^88W<81$MdT$xbyVwBG7pp&49<W}|
zc)qa8Lwwu~Avrz#avG3iGhRJa(0%j6V(yHjA%4|%g#}PEJSRGheydWjsrfmyIPsng
z!T1JOsSnBWGe>ko#Yi;ZH)aTrs#LNCE>z7=Wya?*Ecsm35{@hRWBY6}GE$z8c{?48
z*SD0B2e&)hJ^7~xwAym!v3s2@@2AxVu%8I7^r*z*&AC)x$7?%lz7j&!l!$Gb7o_y9
zI&P$tOfk!c1%R@ODU2(Ysjf_`QK|O?3sWu%?=Hs}uR9vmPaYSy0=yf}%;WR-(5^Zi
zY<6S|DU<#A=TL+nW0}U3A$d{4SFNFUl-{GQ!Z*2my`Lmm@vgm%UeB^w;JV%T)OpIo
z;u9rNH(TPK7ULH<#xUg7IL0TI|Ezf{R49+mJpOi-UX^^G)8@MR8|7}~N@d8UX`FGU
z{5o7W;E?x=eHE|eX{o<*_0f-l14RkeQ=c)m(;fXAwRxdhf_mKdk~E(Wo9d_@?ij*0
zp6zG@)McbtEj@yikQXa%(7jbbdh^T@3dl*d=Emm5+x{dnM^DJH>dfh%r+w|*07t#Y
zF8Q$fIEm$(2oh*O+j&%J?7RC$0fS$arheicJpNdmmpiBB`pa-L&Gxnb)c_-Lo=aYE
zV?RYOQ~sv~aG>~*dbhsKd_P|=SXZ-j@#Plknh^=v8)=_9!LP^7s$$-5xfr=exXeHA
zk;_<(sxo+0E*jaBmt1W3Hh`}hr2!?)25%o3ohJ!Az1jF<-~Y?3Pw4kLLk1=03lhc;
za`<0Wf`1B6R1BY9qM0Kn-*Qudgp=E|5Bu!<uY7dLN3JZM;727Bh@XP8*N-{;>uL%j
zRYi58_crIZuWJ(rX-#_k<W|U)gJ0j1mFMG{kA3lST=%7rAZfNg^tL=nS@lkAX3Ots
zc{P2$jHxvH{vc}jcR@(95Z-Xcj67E7*n}DO*<;L|MnBm?IU08ezU%Z``P}T6%H(T1
zP)eOmrClbw2!Z3?gZ(iwiS>ZW4UdZlXkS{JmK9Us0$~C5a~mh5Q2e`lWM>uT#VS+}
zwV)fT{($0csHt3t*A<cT=;baGPslriZ|k_rPhynb>nQEpYa74{4TK7ll`hp80q2z_
zd3y(3=$>N5nvQ8>czxWXNrbOqr*N0AzDba2^F71;wW4Ig#vi-gr0!4DIu`?lCq9ky
z1^tq~r|htc+d1+0+5aNtnV0hp-0LN^SKIf0wIM5EPZ;DOW3iibmtnp$S_DLVS)468
zQJA0Zu?HL<&NmTO3*=`;yZL|D?hd;{4JYcyS}#+spZse$E9D~-nb#*SU<RMc#aNqe
z?-wluUTuicWKE)9O!-ALr@wr#C!5?{zjAAly@45}R5+qaT`nJBWP3OLAtbP$id90c
ztX`B4zdGo;E6nrZAkGM=)ju;Sk9`%I%I#i~8B3s}t3GtIR=<eqXgW-ELV#K&fXz%{
z)e7loOcgUF@MVb1G$2!L{-N}69+Rp0tsKU_!rUpMER2bNP-f+YiSo3=?0rz`7jy94
zgVx^ZjUgI`p~5lT)R9_lO+bCc=e38z`k_Sb_x1SBkE6%}G3V3sHM%bHckyel&v)mt
zh}(zW)Qh9UC_bd@yWcrajbS<I<DYXIsWR#O_}PrAbeJbu`If9Y4vl9$<%a>o#ZT^M
z6te<!v?1?Es9g*`ZU4o>cjf!#wk?T+9lrEQ@}t+`JrAX5M=Q_*Me;DhecB$<UzcQC
zi4X*;x|q7StxmScm&6}1RUeS=_vVeg-dQ_W%JTn<j<W>AT2wkw0fOwnYkU~<7X=hF
zbXNVY{^ixI19EkmBD;SjuR)NngOIl4ClqT6S^k-CC-aKCzW9lNj#;6kuy2v3la|zC
z3_WARVqd5}QLj&tUcb~eP0Fj|Zbtn)8p~>ke|D;0N2I-C@q}UXcl^%H%cD2H|GZ$x
zsGo@Zu7aTSW`_FYWmYapO?LUG;ZhdDw9`l;@HX-u^|$hyW%j*bao6srQ$oG~0U7dm
zj5leezb<<XZmLeAKhg|hcA2LA+VP+jAzGu68CbQmMhfwX3zmXs830vKqr)zM?ryh%
z?3pah0SJM%2CU4GoT&}IT8lR9mvmS!KuhcRg|Z;p=yRf%3~%J__(HD}B&A#<4=N!*
z!gMUBpF;@3Ef`;WdQ<6|3y1~W<RC5%cnv_h*_nv?4;D(TTtdH$r0j+yo5HDxb@-v_
zdk~An4g;MFtdG>WD<aY7hU~u4<o|UuP-aPoSF1+|8Uv11xPBgg1<d`J0jQN4m7?oZ
zA5TL)axEu}yE-&dVamJ8x_V4U8Kz(L3(}HTmtZ)o5nk34S=PrXQx6p?r=I&OE51xK
zAN&fy2r`qS257{D8Gj&9ZY@hO2G0I(ZzSyE@m+}&=w9;;f$jG;xNqJnUgvz~JhU7<
zCW*Z@u{AK}r<fmOG~Wbqt=9|%q3ChC*dr^<a_Px3o68IAb$!^gR4&r$D=%(*FIlHu
z85D=4hbKa9gcdAC-Aw@N{uHXVDWYsin(yka4rRd(y@LI2Vt66vP`gk3Hn-litda0t
zT0}6DbZ@TCHtdaD@{^g%7s<3pZGVO*EInTktz12RuuMbgH6PeLw83S7*rCi?sRlW<
z4dBnUE7__kA3aX(J#T)RJ-a>7Y69Fo!)s-T^_hqb>Ro={FdFgtq!&{(LNxZj9Q`?Z
zI64a9`9Ix;z?uOTVt2}ie;IX6vEYsv;`lJSuj(Sx;t@}84vvXxz@fP!d)yiIL!8by
z2o;$guXmDKal+>@zN@Uvqb6|MlavV^xG>EF4L-ccGXqWQ44}{R;_s&L5T{J{8K$tN
z+L9EHZ7t|tO!G#k(7SAz`@=J(k-ZYBH+lOtuI)Y5(r07K>NflIIM}=E<dT!2Z_r}I
z<Um1<p-ftmm;UM+19T=zk{Vb9Iuq#R%9F^x8r|vS(XB6c?)GUnF`PmrW8@+6k}KfN
zP{$kd0eT~?!X12`!)9P=j|j1=)=I>L4I2p?xTV(7jU*g0ulF;t2Zy~++c0Ws3jRl0
zqzs}N5~As7!r=86JXASytjJ4Xf5xqmMR9zCWei^-T>_vOH5asufo@*Z?=^IntUM#P
zNUY5}u0#Bc2Hf@9gOXEsR8GqS$j2>8`xcYuj^1<Zf2Mf4M-n8BTQDU(_sF4Ff1W@Q
zUmM`yo?w%Ls}HQ4mF<sTKnuoGUy33Myb-(!eUBiBVs9#v*qUQHZysA42y#D8P?&=;
z^UY5BoEkgUfC*zh=KG|8JQec{<-}j%j485JXeZT#oiZtZ4%4n(+0ru~xkir%h<LC$
zPEK}#?hvDWs73b6lsGZB+mDZ;v>cyTtc@k_KGU3JO(_#c#tYn>9x)3DX-n}FoR|Ml
zOwj|zz_;moFvaCr{0Il%n>PoC{<`dwZ(jAtE;Hh*C;CR2`?5>s!x)|LlnZm0yb_8s
z?CkIQmoe!xkqHg34T%g~Q`N2fVt~-jo=+OTR~JS83SecJz&9>}*BGZ)Q*`67Q#)`7
z1Ff7_W!g0)dn!q`0d7z{9wc%VZVx{e0CCWApo<)Nww&|xZWmI-uiuuOG}(zw@&4;>
zKI1P<JcVGGWcw)##D4<^^3aJ1{1e&``^%SJE|Z!*n}zqZO=_*@q16RF$0&M}Nd7#{
zzR6)!A!=uT<RFSyISfr#v^Wiq%7=b!9iuI%6YK4m_PQG>GzLf(!Lj3IKFEXosW#ji
zQB4ZIYes$yNjERa%hYH{gw50iBr+z?-E%H#9m+ydlscH>iGBiQeg)o;;L$5gd=zJ9
zh7-a$o7l~fUCEuEkr#F2$?Zm$)&|&g5pFaV7)RIyF#APqYR+JszdC~`cl78Wv19Y$
z4=%t}IKfa%<?zT|ys8`z+A@f;4G8`51)Fh!&QfqaK6(`SrM2=IbbEYJrHAf=)*h!C
z^!$q4sy>-?@RL{zABeUHH*abp++KU>z}(bBv!Qg%8t~Tn4v!b3bn~U<tmcS@mCxSj
z_OD4f>?t~PaKv)xMd6@_f0G;$|0f)O-Y<oO2nQ4b>v@KX<($FjOiILC`W+4(2pr1D
zVp(Ji52CWCTb{9&6Mj~x8azt+N~9epTpu(|(!widaBTF%VD3L3g@vW@X?QNh^N!Jo
zA(9BjlSd!?5g%gri3Xi9fPm&Q+S1R=o$<LK5#2#?bLun`lCSZq<Hh*NB}c*2m6o|Z
z(I+r=9W>=g7mvkUq<8>>M><(|0!;TtOwSi7UkcX(XNH*0nC~FeF1-hCDPE<gG!h%+
z5+;xiHVSp##^VSUAerE2Mv7(0$Lb0rQ3S#o5)t_jFV0nx%1V8KRzqrv|NS<;KV}MA
z6ao_(<y&9eJx(ynR64v|B;4biwp1u|v~psME4{%I(}~}L(Gbe$!B>O)si5dSHq?R1
zPVk@chTVUN6O>l#tu)xStmgXel)~r3l9}VKKZc5ocxnGW{bvMN6j@b1<;q&D7^3df
zWKji5s3?W3U-@i<2p~X^a)7fA7l@wB7U&YdJbOJEP~xk_mc8=3{^{k4bDlOj@tMhH
z!!)<bEP+M-W99&nOM$t_qtRU%k;4u=lJ{|`5fd?)=I?T!LkXn?$9J_LW3it%pn+63
zp##j_vrTro)IqS0oST?r=a-M)=SLV#be)7aH7gJ9qHY>jAd~WzkWdzq);MY9#&JJp
z3l-I*2|%AFt81WDu4;3trPo=ewtE+f<@`f8OY6F<uvy+JC)%yW!g_b`FCg{lkZSzO
z;&4*G1l{qn_xHv9b*-O5-O8Kjf&rq|%X$YZ`9wtMUv%4Bn=IRqD3`iF#+||*jP^E}
zz4edMcXr2|ywrdCAcY`6dQaLHsQJAetHb4z^;9wsMu>AQpht$<MMqu&)ii-%3gn6V
z{0~k6Y8}UlC>nZR8r5Eioj#t2H(2zTCoicjK6gbXGHBk2nnLZ{ql`mvihFE|PuhHu
zN3HtF`zQ!Ub!zD0j}n^IdKlyTdOzGgCU%m`a(p&(OLT4x_N~q}{U1tu^zL-${t$Gs
zT^qWCk!tY?hb<VU-_Ji;NN3CNK=qqL)EFwHId2Cl_WOO|sq#9%vb-y~vp0%lA2P>K
zn0gUO!Xuv3FsMx8?ve=-3uTv(;A2Hc7;a!>HZP=|V;x``^)=}=AYKbLZ7NEXQDTVf
z75UE5X;qBVQZax`b~Xrz0JoLgW273+mZ%K}!oaxsxr!F7Apg<&jzlEwf)8?|bRMCW
zLHonB?0hUW$VTpC_4I~VE4Vdhp)gl9OH2=I`D+^a1})E5Z^-c*h?=8Ite+zgRr(P>
zU||3<O*?M6+UuMVRy;Pjb90*F(>k%zQC%A?Y>DCn6Do4MTQW}iGk#?M-wqN$8zGaG
z%h91$A(62`x4Gs0Dkm_ip)&F&V`J$?1Bg=c_CHb<eEpx$o;F1)nDCb^mickn5DH+_
z4loHZ$<5zL?c(HY`7edJxAmE|&7EE_I#7&wfSYJVNOs@ju_E|Jt8x9+7$q-xD?m?G
zfP1o`oqyyZvf<@%CN5BN-{s|&2Mw*`{gbE7zZ9-jIQZA1xHMLw_2V+5K>sumFbB-L
zUI{VFBTeY*pXvKcp&OQH2OY$i&Qu+s$@mDO(b2+LEAm&yK}W1%2vW<To7VsvFUgEz
zCd<_{Bh#s;N(vS^XzuS5Uz#|JzGF>FhI~3=WTXxi$b3mtTD&%xCRZ4U);TKop%5g7
zjLb}*I*yL+;=~}`5V%oY&uAF>_)stX=iHu^@z+({N$c~A5C4}<wQpgDSYA>BKlyDq
z|54G;e|9AMNE@h9BbB9KW0ArbP2+#y&tr+0|1l3dSaii3TR4xJ0A#XQFABqYfaZ1u
z1>W`FWmrW8!EInb$J7%QjR9f6fG-DdSE(3~046m;=F}#U<@<<kGX2OrqrXqcwZe@X
zRLh96G84q33zuz~*Dx;#`;74H?fBI&*SC6V@(vcMPpL~hh|&q6P7^V||Fap>_>!5*
zeO*4)pm4VGRfWl@@vvS2`Qd5AEFFW=&G@5M4<m+6F?z+A2`LlLALS-v0uFo!u6r-=
zTA@i?Yx<F#uJ6|6Y`Njo4>_+_%ch>nXG)1oq{32p=l9G#s2qZeSZgr_R7BRG{Gjjq
zc+=Ltgt5F-HD?h<Czb=mwin7Z$Oup75vk(o4IsP1SF>r4|71--=KBBRCosN1h$I<h
zXnI%ROQ%P}WRI2{l1@k|xR0c?+hMm-|KRd)xx>?-4DsVAx7Braf2%Dsw-dNIUjMXo
z^EEQQJ%fw~5}V4ct`X0Sgqg=h6NyVmmH_N)O3LKVqjuDsJW4j;mUtC*u>gK{z>+>|
zQQGmxyzy;eTWfKZnvWAPp(c$B!goyW7D!kDxr92-XJH!Ic-*ztrH_(L2pW!w=fQYu
z>S31X8iA2X+%9ipVC`9P=??PyNWR?LZo-mQ*u`ihG+78t<$_ZS-}TE&-KH=I78zP9
z@b8jt&U`Ya*%9V!$Gk)+(FRELTuic9FQYd*6kaAy6Sumq3TV~A%;ezGRDMNLd@I92
zj{*elZ{camM-)jcW7fuKZNYM|9}?!(Fyc>#)r;_W>kbNHw5l@!hCo0M&jEU3&(Ht=
zj9GOeWu|Pb?GU6@q8{E9++cbwvLbPZb=t&=he!XWPSdvGygZ4m_2H0|WiXhb{=|PW
z@Z=hNukX)vkyCrko#%*7i~;{m-WRXUr`Hk)Mw)F%_GS?l89f+fR>>}1CTb1JjNcRo
zRi|HvL~&cFjZq*|iQ$4#Yan-w`SStljFG`^XJL|G30TjfNMdIbsZBx~7Lqv38(N(c
z#-GRPZbV3Lq<1~k8xwi_F=Nb^W1@UPNLVh&@X~d-L7L#iX?B(JWG(HZZ}^p(u2Nb{
zv@E~N3`6aP9Oz%2U^7xH3F|*DLdzT@L!Um<b=8{RjZeu~?3O?pvImJ-<U^|%En`?l
zi7hdgJiJu6Wn%n)viiWO)W|d2{WF{N{B)n+s57A4#ckW?I&M3l{`>b1cE2&>e0tVr
z67j#~KuW(<@oOOorVc?V$S6OKGH&pL3k>q*<Ri|0+aBxqAJ0E6C$XiTg9C6yuBl)-
zYV-tfw(=PMOKy*VvR8pjVq4s>+kj8p$$sjJx;VDilBh-OH8a)p#5R)zqlGQMrgPRu
zHor={np-2G%t`h6fnVTdTy?ZT9PV!@TF}m)dGbAx@<n@KOXUINeea%_+qcVjdVTz5
z<nvnsz1<|brisq4g!)XhT8F|I3~$&f%MvyRZ*E)YjD%<#^j<JaC(@}fmO<L0eP(HZ
zF_0Nqlf`|AcU~!=J1<KUBAlZ=#StJmTtNFFSLD)jE&G8)rni)!VUDr~=)BIob`YXP
z3g)i6A!VFHaG~#QDjpz?ydlvOrFP(2IE+WXVjpJ>>uq}uIzM@ztE1<9lGroP<kv#L
zs`UMr8H)a{MM7YW39G81SAPq~s=oip2Vm8vB<g=&dPVMa)&xex>VIHCd%Q;rs4Ood
zn^GPFChF`uj6XeMzgp^0LrGYX{FKB7+tGNa<;Qhpc^4Mrc#lwnFRRqJ>-f;~h&hPv
zeUL7~7Qp-$-$dU6*pBJ5Jd1WDT{ml9Q)ZmB5;xf2A0wRQ8NaKXQz+K*73+B^g5(m)
ztb_{RF8}THQQe;-%Ic~1cqr1kPm=q2j$j!rI!=2$X2qoQYZtH*K~UMtL=Qe%gjQc-
zjo~jBt?u|Sm0%vIE}JIV!G_O5{M)|?VT^gdXNhvy)DMj_>^wen$rC9`H7fOPVral~
zcZH~>og3W4QbKXMNXrcyX$w!rrpwp$_`&c9UDl_s;-8i1r?!}A;Gu`o1+4)OnlPL~
zT3V@rXS7sxt_k}oc^7G4cqB(KN4saLd!(d?8+DY^;Hq_1-_p?p)Scar5uoRJ3}6G+
z`qZiL{pQm>T>H&PN!w`#@J-+bT>BX`SI4b9;Eolo{0zYP4<QaYcah-oLw~rMS&{9h
z2b9o#sMRn^oyKX_VDOP3dRn5DuAz2QxqvDYa|jt$9h}NCrh3g#P(cXDiU!3sR|i=@
z-~0}<%|NlIJ32A+qzQVJq>N263nYc8RGWU|Cu3aR<pmb$FF$N(5NLx&_fC?RmbZ;N
zsDv$>MK$SAAESz|MspI{m|A;kj#a-lc5{F5gf0H%DQ;XvoJ_drbgD8Rg)hF*v%ufb
zyQ)`~cuCH1b>l<$ob>}&)BQC&j5z6xY<!YGa)U)}PGjuKHcrt9*oZ5Cgr%J42LD3C
zmLKMkIBB+WkKti9#itMEj~iD3Q)_=>@U%ffoC^<LDGzE}ldiH1P~wBLHCJIOOhJ(0
zL7HWQD9h|vVwRo?*54}KaB37mDdw`)h%*vWGv&4TLs!1Y2zW&R2JAipgp1FHTuVm)
zeFT`{`|+obRP9^ro@G4et~#)9Cjodds3oU{0T)=W|9UXI1ST2(fo5r0y>AGC1)-kH
z_t2Jiz_{P2rbC7nBN(>Bu~r#%!zh{VI4)IVR_z{Ua1gHyQLn5pj4C&LYCieux3k07
znvN7RuOQwa8jLKN!W7hP7~)u&<R;y0KOA1i3pA^xb3cXOgtjw$9@1_MFa2)2Ff%xz
z{=2^Ax}~BO@l)A-O2S9a^;`7=b??`12jnGJ<cVn6hpNKNp9wg@)wEw$(D#B@ux#x>
z`VVBf6{~lz>0>O~VY2O_U10&QF}#C+02_I2^hoZ#lyaNum^Y{e`j4vZWa>*qghP7w
zWekJZq+we~k?Rna0u14zDGMM+Sj^9*_AGVLEl^BN)$U38M2q!PBE(*MB_>!Gbg4an
z=dRKa*-y0+5-RAQ9jS*4-)da(zO#}A*ns8QEsoCm{vT7L{m;~0e%Ea48Bd-1>x)^4
z%1wxvI<PxnndxGHBgpAVKf%nd#n{y8e=Llbv>7ux;KLG{-IZYvocD^#@xN^`v{HTp
zxPsBDk!-UW!ts#d4|!U;#fHdKWHAmkpGm6WLw(DKS=Eb@mC0n+8k!5r4;YprTbmPl
zD&f;YX^t#GY)Bu1@3}`5)m9R;8D9+ecGb!zIm2vnEe5w!D+CJYWnI2!>C!mtyE3;m
z`qTgXP2T={$0{@TrF=Oo75rh7bbAxdSTff&I&(ZenUgQay9d*0IqD|0BG+OJp3!)U
zdr$?fo;|;~k^l;FK|Uu-L}mf0n|}2P5(teEX);x64#i5~S2o8(LSv~gw#+vzpJpeN
zk-vGwD-Ne7{?aVZ{`<8ac%V%#fPT<VWb-G!vhG){1+A)<=o<_R6#{Ir^5P_-A#s;p
zNNcmKPELHbeP`4Q<79TcI9%n0GrkDHFeBe4-pR@a$F_A8x!%}{CzKC>-`)}Yn^|<T
zhXCqN$dhL~{&lW;3Y*IC=moUFNg~EGV3Sq?I{2GH@t*<&_zoh2ekC_;rZAzgQRqO(
z#t3RdMG8}Jdr?)nG|S550Y2f&laHj%V@oLJL+z>ZeR}KSU7*nT#3SyBzDX}FSb{Il
zFE(@CI3*xlUF0p>T0WD-{_>4Qwy9)$!!&E3W`)w;%}f?g@o&Bb+jNJ?Z`-^DpSA4k
zd;@Y5eiTS7%M&Uis)xohoXkt~x*@&${P>yjJQ>#BHW5Xl>x|xY{Wfy|+a90XIyCg7
z`Wj5DATEZ5M1m}Mf#dMiyPx<IZ;jEOfFZ5GQtgU~UMsO0DgL7Z6|WiMoy6}3G*@%V
zzR?`;)%(Qx_Qmyzji&WRjUDy5e^rVb2GQYUh2xa8^c528UugYKLX-<bS}!QS{QqeB
z#^^ZzuIsR2V>V7EcG9G=ZQFL5#!h2fjV88j+i2X_w)IZ_@BOTG&6*E$&6ghz_St72
zWf7z1`|3UEw4d2e5()H=k8Z<Q^I>R|y!j8rcIiN~W*1_Pp3$mOb(;b}4cIUFKFZb4
z&;;faz4`R5i07S-;QDvdHELX}bG%+-iyL7vKKt;EuH~iwOWpeNdlGn@RfD$F8~XQ8
zrruvs&fW>JAD1BGgSz%do?({WWtaFjJdaq5ya&(UUR3D-f6UQNV&b^d(8rkLrT%Qf
z0pkR|2vGzWpsJ)1o6_Z;R79Y$7nI`{4Rd&XUkO*K*aFSFrOsHiv2anUjk*rQ8w5&i
z%uPJ#5)K-Q7gmAhx~wSL7f&a*I^W^xtRDQ-aU@0@gR~WFFRt2aztQ#VI^*-14Whh=
z!j{w#h$Z#bOsZErM<CPrejF{;46Bv(2%3`uN29bU$kKJM#u%4?yW4&_q-EjuULA3a
z#n9*?=jXTh-jgm|Q#JqIPa`K#zaKix94~~cOuRU~Z`7Pw8LnAzfl`uP102E1!iFI8
zqjo~00g_L!e_Ldr)&JSG(wd`<<}xN;yp9Swoz1$Ra5=~(|6}<aQn2}|V%;$iFqfJ|
zYIEU)lK4MkO%i@>tqsu*Xp_&qJdhlJskQZ5gnPLDs26d<E=I%IeE~GSSH7iKr+9M0
zLGfAsdSSdMSlO_6P_+J#!bJFJ71U39ki=pJO~zhGHV_=u=;dqoq`RHj<rb~Htin50
zu8YpF&M5lHHxx{f5D$I%QTMRlvtYWYyJVl~d4bpEeyC|x(#BT*H=akLmV|vcaHM}Q
z5CaLR@iz*5im@?lGb{$lmq^J0Od1L}VJanXA?SFBRc43LR2(vto@9_E7&}%gYnxB#
z%<6oKa^>Lm&9JO!Smb;7_t4?E@v`3Jqx$xo)v>5&edc`6`QT;#cD`a!CKLCKb!x$@
zg}V!x?iYQ5(#4ymO?e?4?p~58{Z&|R;&o4W5&4(|dcKKPD7GbcDNrS!>{^Ibtk9=y
z>U2!0U!W)){LeS@XVoNx1Rc~TR1qGVYXKWi!(M0y7KxRj=TsVBI-x+W!fTFvSd4!m
z-J!@)2XTynt-S)|sH#oHteaTmegn5iO=y;<aj3$efvX~bfZ(MWxxi^{wO9>bOQj(P
zO6^pUV9vmV+l^iqt8<jbD0s}7_GQg{GkTI)+Luh5t)Cp{<Qy}-pl^K2FHMa_%`Vpd
zH|FYGF>v5+JI92BdK3Tsh7_^`YoK1S38w>rF_H^T0_#6WY7yW4)jiMZ;^vO2YCV=z
z6Q5^!X&xrD#ky^*+$snCQI<4^a@B@j^**{a7l!|wtCLW8&1u1w7oF~y-KuFusx@20
zQ%bL?&Qr*0oYdQc;R;7PgghZpTIaTwv;LNzy;1l6(y*WcdC>(0xZ><mlNz4V!m)?L
zoLD4QP;OJ_)#|t{DiXix-T$m5fnCGLUUaO5pv6}pt||#O-B}SjqlS)e#5p!43X45I
zpchNPftxF7BJPNhgpUUARz3TFTmY^z<Jp>pXC=PXd3u9EeUCBp-IYR#B3F<=J}K;F
zg$P}mpy86t&LS6>q(~@_k_e>0AOzJ2QE9C(H*W6Qpkf?-JmI(Z98uRg_*us$Qo>AG
zc6(Wf8cF<_<%sj2NFjX=@mnGYA$?mvGjMd=9g#nd=j^wxTy0zkS<|6k|4!-l*zD_A
zfBw#aA8jgx0xyBaAmaN+V)HHVSoB8FHg6odUvi}YRJ+qR8e%t1ih9S7b&TPAu+Y!w
zqv;CZz<OI|L<9eayrn)>BfmnA+^WLF0q-xm$|2~I?G~LmsN8n?@1AChYIoMy3CKb5
z-gVv&fAZH7m)JX+emQa7-MBT<Hs!0@PR{1E%7SvTVrmutc-(x+8iVmNPWay5QBAo^
z4zM4TOK}vxTfE{!K-V}pN@9y~x4j$0GMLO}on)`%cT`A7uaclLnAB=K7f2#9Z{_?|
zw4+qY4B^lle>jE;#`x_|F!y?l<xGwUDl<{It2oHTQ<XNvE=dIfFGjOUKxG|Z<Gg7E
zvMl?|`_EeFTeo~Tn4usWaF=LfDUlr@^Nqv<&qg3pO=ILJc0U8|up_}qQj(ZKtS~<4
zU;_HWut4j)#lf5^<M^5YbjSQSy6{#%U{+sW@2leVtm7{Nz4qS%qr$R)|HCgU#Zqa<
zSQwcttn#pIcXMV*w@{#v@$_Mop(8Piqw^rgQ?NSUJ0Ks=R2a}uqt;Z*vFuoYnlY4g
zi7;+i58t`RQCW<@VYH!|9bkdQG8tp5jZmpN6ss(L$$fIhG47Y0A~_y<^{ME(a_H2N
z0-83B;k0#SX1FXC^jU>)um2#05GdQ^$s-t2>C#cJjccw<nT~RsaZ0d?9{Taj9nT<?
z!d%<&r>xu~Hc@u6hr+yH^2O|*ARM-TH5gUbu|e^jF$%6<+RqthZd58E$Ol|F-wH0s
z2B4xdN`RN4%>~N5u!J3XE=_!~6<S<IX};l`thyf6E8M)Ro>3br-@~~H?A;Sc&oAsx
zV=TQ}d%=F{&)GulD)w_c($(TKD<vp>Wfxhr3hWsR+^I=d3((3nTmRn?rpj2+IW4ob
zw-4rdH17IuO_7FbiP18}{2R}Uw%Hivzudg<vx1p`IeQ}IqcGv>N8PG*s%m@4+@xo}
zX@<1WeHnFO?n8t`Jl+)pDT{$8cpdm*t$44c|NBy*YRf)i<m!b08+bZhjtvXeIH;X1
zTit@q`|4$PwlPSIN4R~8a2n|v*Hf*#_XQ<31o!@iS!{W8`c&;^DJyEso#h1(V=sTt
zL@Z>+q!$c{b`WvGCkKU4R$-~1?;+|h;()UYZ*|1#r1j>(1C~&nZ@S_<P)q$J;VWbj
zcOo&m{`EsHS<yO^R#l0<Hh1MWb?l+EW}}frxj$3_g47pVYoS$y(y~%LgQyFMR^o*s
z32c_VQs=9P2veYJ+rPq&is3CZhSWl+EeIn$p5>@Cjc#Wt?)dR(sqA9!&06~1$mC<J
zhH_#L2_RrZcqP%J^hRBbSjAzQxoW`yg*kFpgFMRYE0t0(u@J@%nPq^@^b(K69^BoN
z!Z4PlP*}%&NI4X!W0JU{VF3iy(rp;6p3;#wQBuDjHUO$fmKpDaPz26{?a@E40#$~^
ze+C6TsHrL@!dJk_EB$uA;mwEO7svm<3xA8zD+FXMs8&`bFl6~led259-gHmbI_H;T
zCRmHeI=;?iUmneyuXnpWUmKyH`jOaf&)n$KqHWDf9|ivuT<UBLxw^g2S><oKNBPOc
z_ON|pz~0~RV}r+O73^}|m1ks<I~$H&q`RbHuDN65&C6xr&%83IP-kcPiem<u!Rw5~
zUDqMp<m>Pz!|IB4F&ou8H1o}j#K0`Jr^r2YR~afo4LA8(12mQWm6R)|%(Ps#`cSPS
zSMHZf;=ywe{s^;@I8UWAzvkN+m(nk4%^A6?*3<`i{bhdswfQUH>=2Y=C^`gznOT1m
z^E~@HsX_iOdOn;Ii(@GEHHYB11q0!N7iB(zkrB1Ku<za4HzUmm3B{B0o3;?q=IMM$
zmnj((hJG9x<q5$fl#;7!x1M7xo@IieIxVssL}Q&cfnhY_GFgib5Ha!Y5a5HJ-oKAS
z9FHj@!`Yib&o|v_3I}q$I}RKs5!{O#nKr1FC?*K*>u#^N8{02QG8-sS77O7Ne<YS`
zQ^MKGrx+5+Z%*;%mH#tlz5g?2ip|#xgnTzAi&qUqJpAe|z8O0}-{UB9w>^-f_%vr!
z*`;cUK<8c+J6c0@2s&NenZk!`E^J7kC)Ew<ERb(TtoD$5MC$ZI%@nSM5NX53`&`tH
zb+|L@RCu7ZX5%fx+C9s!h?B(|ola&pXe&iFb-Gi{_nBP1{?0NJ3`wNC8Z>KrM(oD)
z;OK&@Q}>>uXb`JIsV$a8%c)QTM-oCz{aREeEmYKaJ7{5MLH)#j&8WXrE9VZ{-GO-)
zIwfWV&r8mBH9Yk1uQ|1YPBu9IRXem@14mmj9avA5!T>VTFy_Jx7@^#aOR{_2is(wv
zpr_T@XbS!B^AwLfY~Z=KjDY7-huk!=jMFNS9jR|p(FU>LOD)!`q<PPt7OP$ov*N2d
zHP!D=CJ3@Bp(9vd6#Zk%5z$7KOT2d+XpOAnNS#j8ar-h@BVfy-bEi5*2R}V*0xYO^
z@^hg@41Ia}d_Nw5eKGGx$UE=S)+3`JiKFf*-)H*QI^f6XF9N6kztGL%Bxp+}s0?ZF
zkntitg9(3Cql&nf;3p}*-2!z0DvWEUHqVsYP9&PQvbPp!oGeIhtNVe`sVdWsr?PDk
z=nP7#bV^)7yvM|O-psFdyJ)ugt2TK1kGl)R1gnzA_ISn*H4avS8jGQNtP5O?3##-f
z_00Mg?aU6oO(!Sk5+TkcazCBotfXO%^#j!>265v2fJORa^iu7I9C{BRn(fjv25w&K
zLM}bM64#>+1o|SJPgw;M7TA5}hEZOpZ_;{lAcAr*5&E%+kEy<T+2;E=xq`}25(I8f
zt^3t6mZ*?kVQtR7s`?gFBN{4SafKX>?2H=eNCo$3>cUmE<QLE&kSRzqC;>H}P)Pz;
zvBv4$c!}PBgL!2>^=iOs8s7eUl40WQs@V#)n9Hvo-?anIk{DMG@KLE$3Q%VBEAcv>
z|2x<{|97xq!5{ycS8m6=O`Bh?ZQN7wy>B7lAi=8JpBmdb`zhlIw|jd>0^fHrU;BU_
zxJ^w(;%Bx0^E6>Fzsc<}NBrIRF{|7v-YNLW;J|H1hMxGAMIg`ZiHdF1-NOd$J}}8?
zUL+>HaaHMYMuY(KDF*3A+Ry(U_5w{)($mFjix+L2y`Z2X8XeeswlB-nHMqX%M|J+i
z$wL<K*O|%GFr)`k^c1aXnM~X_GT%2d?9l&a;EF+#O$=PEsGNL}y=#XpNW|M2j<qMz
zuRoEtK^H3LAAYa*K|8yV#HQBusHwi69{%MYyeG{Xqc9XQhXU&I(YE)jA>Jaro~YbZ
zn4+x745dI)=}g6>daPNI6B!KJz#lbsVQ?A<H*+g~tDoJxn_#X#q)ymVlMyXI5cS`5
zh^Doyk7bEh{k}bleC5`%27Tnx-w)>9w7DCvRts(P2XqV4QApHRcwR(J5dp&#IrW*T
znhv9~tIX6w<rYTL8ysyGCslW1=HZ!Thf*$}n}81fe>Y*<QNKNm|HD{*=kFkjNZ<%S
zoShhvrPnEK=l&j}?jO+w0n*S&_ozj<viUvJw@IcyX3gH#kO?E3#cQAL1dOJqBtEDA
zWh~{U<bB&Q9Hn~6QMaIslMf;nT#`R|PnbYHzUFMz&Uk|Yz8}i3^AvJnrSwH<6%s$!
zJHbG3ZC_46q}qZ^TH(oD6AD4P(o(<NL-b$a%KRIkK)gxZJMldI$HH;dYO(I%>^wz!
zJdk^m<A?6d!=2kt5aN8}KaF@%S%(iiuS>+e{tM_$&q-c?>W?S}s`y$w=f8_eVq3be
zGoW=Oafi`hW5wk@=?gbk4~p4FpfQx<k&@~Bw9gI4c7(;=Ub@|gXEcT67W2;#lmKZF
z=EK#j1r?+$xidd^UwoLvBXsW-he;|$`-f^LHvTBH=r@Uw8q61V0%#vT!4rWgUgeo8
zqwod<jbK%uikn1Sf3F`X&=HQ>2s;zn{bRaVTq)3FA_@&JT_wn6=z)sHoOkRpD>4jn
z({k|t=dB~&9HQT@9*fsLP1U<VchHTt+r^9C(7=uMa4_q5A#SBEcaS;I8)wnphAzz$
zWT2u66(}0QC_R+};g{YL&x;_*2RX0$D0E;0LZW{0Nydv#Ez8Q*ZUPm3&L><<BQlj0
zw{i~{E1d=sf4%ei+KbJzE<I(*JHa`YY2?FV^=5JG!!_2A3&LWl;VJAnaI2I^G|c&5
zgEYf$8zSqTPZ~M<;VUS~Q{rVuBOIqY{g8iIALY8XSdj7NXG>t%{-*2CyNY-+0!>V!
zAa@<=k7!;Io%3dz6)j$qu_rM)HdJLu3&$gXMcsSL!I>i+x^o8Tz~+L5l0R24+q9w3
z#0dMx_K;~)Y&=Cu9&)=mN0<zRYgLk%^+Scuevvd16j>3#gUh{Aj^{>m0*gPW=?E9g
zg#bOm*tJ1y`pVMjk!j{Bqqx+yK_w)l+QW}Wqr}@bsQnG(66lJeC=nQj;%niS-uq)3
zM|JR_b!N9?Erh45pIZ=3`Tw`zzdYez0f(mtjQ-m^qmg4BNz&I4&hxelEcPEmkGDlc
zeHGd#;)gk)pm;GSVTFo6;oLk-J;F&Ls_NPLP4$-!z=P{qEUI$Y4ygJS)`)P7LNk$}
zn^aRpGQvk!LUk_oAWvSz1Sb9<TYq&N$<VM(Yn{hzQ8|TKA_F;pg{q>>x%|2;PB-6U
zU@MmP);rHur?x9d!*DI7+&Qz=_s=3&!JhVzbG<tyS4xCv)r?(#WcEV(f?>KGIujj&
z;~p0Zqls!H(k`5lHw>}vcUhh<Se$~52&ICVIeT>$N;PKM?p+)*z0mq^fu+x1$oEa~
z(X(ltMWEnSR>K0Xof;2mz3ooLOOC{vsxy;=N&(;%MXhng6(XdWq>A>30>VPomRNf_
zBcv`=mO>(p)A@d)!&uX3cTb^WQh$WWw29MzmAA2^+8DI8AR);&hJB<H{KNy4tKwc^
z(ZN_uD!PteZ<kNUEfU%eySJI+poKp-`ycx7x$@0pv8LeI3^rS2L{BX2?5Cr=czB+V
zOGCgRbKgBhoi-nMk_T*Dq!8m4;{GtrKPX@6T+#Er=BLm^+JRtVwP1c;%p1j$P$(+#
z&91q>8`tWuM!&rEl4^br`_Ma(U$MKv6_9N`nrbIi4drA!`j^0SA>j3oi|`eHpk`-L
z@&t!v+y1EH&e}*&d{#syh^)~ty2!oOfqPN;(WXh7;LO{DaKy*?yu86Ab3-E9#@p6o
z^;N^<HS<sx2}x}tH)7r8>+8!XPSF$UVC!E=acwzCoPLCgp4*~@N$p4I`5>pb>Vifr
z%RwzwhD81(gc&t_9kqt5i@?xbutOEQJ!4T&ao5&|P4ZxYIixldwnpAC=NJoI)ikQ!
zMi9}0MA1*H39aO=B%Gp9N7F%AP2MjtFSy?zfd%9ePziD%mwQ(x0ivlKu*;+k1!6Ld
zp$Chlcp2FS3W^}1aGtWTQEbfR-qL1pa)gsp_>Kw9-)W4AE+X0q`P*(hovNQcTJFCz
zuf_>v{0E=G@T?(EV;oOUCz!J6?v4Kbmrr<NgCq0&gd}>Orq$5Q1Qdk&O+<Nn-R3cF
zF8Z7)>bSp^U;SDDz4`oG#_3u_DM6<yUaj>Q`hxb|Jn8^$3almO)ySt17Ta5RB^eOW
zd9g6lZt2b(I$6hYFqYO<Kk#<A%C1rAs2CqK-8YoLC3hGDhegk#Gev+xN5^?&Y}0fl
z|FTe%c?xpOBYfd6<ux!#Gmf@Nwlm!JGIULk&T=y$<hgPJ3_h7!P$3$Hvi7Y*6b1_O
zxRO(IZ75fy{co)+qSi!gyiwNAKW^p^M7Tk6eiDc>;@@M4@3i<r8$)-yZHL*JhoS=!
zc!7oC!dt&N*qhKLhtZ{GL&|-?&*VcuDID;QbI#*Qc8r2ZC4kmnz;hsMuqrw2Yp*Ne
zNprYZnvLQJ;0TuVH}dxx1_~WinY6>3se)u~V(ofc<yo;t0hl#2HiXK)+f@o#(8b$V
z2WX?K?8h;0*TEa5)Sg#0Q7}KBSmDa%f9{A~FgiUx(vXtFQ!h>D%PQf3@9iqlpf|R9
zO#|=1)W^2=<LbvFwAWV9s`y#fe?ig^;mHZQ*XGEgmLwK_S(!4=)2?;1gE3@V8!fNr
z0m!eg9Ie=(Dz+DrFX*@DHAv!QC>TaF-mSw?|E6@H(GAIIDzlYzDqeY!zgKtpwmL?c
z)_;Jj@ns~pwxS81WT6Q$cf?CbWL1M)-qKrk^%pFb%EysJf9O8yi_xgo*?0X;W&K<$
zXd?4FZI+p*d^?X7n@K!Y`;1u5Zs<i(SH@x=&8|ZZK`;p#U>>Qny;Kx}*pD!Vo$kLy
zwg|JZCGQI$Dzryy9K-&JQP^WEwP58Y+*N6ahW7Ny$tGyrrJ33Cy2c>D0Jawr7~&xF
zF9z%BdR@b8LX*Eneyvm+0~5u-E`>w_Beox6O+AJT2b1#Ks)sZzEGL$<KWN0wkjjSo
zpc)RlW{y?WWL&-Bb9{A;PAxPDwwe3dkQ6dY@~TD~LfoitNGs4kKa1pFDv-0SssC<u
zf{Ll`y>O=^>PtXLsSWbFZA5bQptY3lTUI7}-Q#~3e0|aPCHfMuO>#0`g4%hPPT2dh
z?){DbF|RAQ2-xP_ug3-2&OV2BhpTO@g@v;-A*H3IrJ*MT?IrIsA$dJcd?c6<QWa1>
zho(xwjJf5n^?YJ0v1Gkmy}3Yg`q983RNe%0*@E63ip27?QS`RtV(jS7yeWC_HgOw(
zvOLSI&k@%~Tz;cNq>S=3x^QJW8x5S=W$w|@zQ?IYqq}w1Y5Ma%%r33JlTHy)AH(=s
zzq;q9-F29k+!;98^5(owr#H1gEvM^PvN!D##eR@S0MjwK!vTdz<%bfRG{R@}aCEGf
z(6BTQsQZ^Hpm*+!qOgk~Ttdx=2Z?G%Qnq?6;5^%k=}1eu{7nf8G0x&|t;ui=VBf3F
z@;VR%Acj$U$1-4*{W6TB2%Mx5P~^b^iRe18Zwal&z~ZRjpSWA#4SduS)gVWxHc@$-
zj@T<V{%g#W)W8G4gXuP+QGZFNein<S5`^-rB|kuWQ`OeZrxg}>_<kd2n-o_)qd_w@
z20o0{@WXKgE6SEGpBqdpGAMfG0)tvend#e@!CQPkNm<aaHPU_~^&KwbLGDyymg^ic
zD??^y{pT%9{V(axb49@fMDRa_tOwXXw~n!m_&;=AtQB4L@n2&2Y>M+ms8^nn@*5m&
zv|*l<LB1Bo==Q32eBg`qAp(7#zrA-&>Gf4q*mbFaf@`Fqj({19aJqEHp*U0Uyg2(g
zP}cqo^SgtFE&f1uw!(spEx20}OH38PnAU%L{%QNe$KrMn5MkPWUJ)NNo5HcR)Md+g
zkw>8!%I37x2nVO_6?JE#v#Mwvg*M{z)#ohqN=x5)JihRk3=j$d#KPYfuZhYpw=06)
zt8fwetBy~^P}9o=)E&X5Ue@X~t#N9JR_=otj#KOg1IL9nNi+r{7LEpoHlcba+Z~Q}
zx1$q}s~@KpCWNgMNX;QO+@)G6Bo`!WI`1SMsf<f&C$}H@GSk3uMOsYuE`3eh4|vK$
zILeh$OF0v4XgV(0R~=0g2^#$tXfE2@WWx%J9T&ASWfvH+LJ0n~M=WOMU4fnf7M&?t
z6JlLL{l|SNIsx%BTTU(oyl5wl=C<Px35+|1b71**zu~ML$lsajqSc#WH}QzmL9jF9
zFg9Yvv=)FST27{A|2N%O8<Kpkc>4XLU^Z^i#?T$@EO<w`fv37+mIYXcFDGYwxwM5@
zj0U$U?8c)C%-EXr!j%cZ-Ep0BpzAl}5b|kE#V_2pGm9?s_#X|u9=*-A_xN5r>mDh6
z-+pXPy*CtH)qUJYk-NLzy6wI@zg_~};5Qx{QjUH5-?uhi7`&d3tRL%q&n(*?kMC!=
z4nN~`<Dj=UR5Mlsrb9k6t}&){eFHy`CB_G1LA9csayC+<5Ef3vz=BgUZi6xMju50+
zfSaH-e{W$_VXVOORQ3D-Ab{OSV)1g3oWlJQ>;fRzb%nVaHw}A2(X}UH)zTjzAL3xV
z*MsD|Y5p=xOdyvS3)mIJ$IjU1pRspRt_~;Hor>*H&t%0nt+;p2;N-o8?{Jf;S-d4j
zno18-d>OB>inAax3MRqK4+G!B$$rY1nDJ~Pp`CgGV|A~SHNavS7ufq?l@Ypf4=<-M
z29rQzD!0P20Sh3Xmut6J69d%dFs62k<YTQ;&QErxr!z>e6B}KM+St*?Tja3}jKN}K
zF$*shC{PsJ;^t5a;#BWO2rC`%l58lg<<{7%H&r`hUoDEngklJp0wv`PPRL2Yh!-T8
zd$Kv3A`^3L=#`vv@Be@#aQ(&5Z=m8JN@(yxL>m3{+;u@^-vV~v@Qh7Dt{3eH7L&JB
z90f-hWURU7Nf4*9b8zmH*8DFwOtcOuT8NNcpAly?p*nc^$)*@k9GSBDS#p`71>Mb$
zJtA*@zT0(|c+nsPbM?yr-`$SKYwK0F^MZ=34sMTsz7CkaS1<e^GQYspMN<r)Ga>&g
zBvC)|>u}Zf*~yFeLH?&-jmE6hUG1No{3ZunKjSg;^u%1OvcEq}+L8O|(;PAuU~2;F
z=GpkWY|i<PW^Ie(eN$4Y<qTxe6|UeHPR+x{nt_zut1sBsZE{SEF(!&Q+q>vu-wl24
z&i$(=_#$o=6KtiHzDz&Ze>=f(d@&`BPn4<RQ{cHka^IBT<0@3?YE&PM%@H1h?XqQo
ze&DtubGN(Guw=}V$JSia!)KJMv^d#07(e|nsLj$~-%9UrtzD)C*bPZE4sCz*y(0=g
z#)$s@#q<todi-=sFf|x)j;R|e&=SYsTlmL;s*7?Dseb=zw1zorF@usct!Vu8vt;PJ
zx8O@7&XG|Z4fezW^}GRt_42ml%Jp!u56Wsq5PBd&9~PO8M90yY$hTSHh;~q62cYtu
zQg{;2strYyYtsSKLzEmgKm@$_jF-+cNFNk?O6=h^e%t6V0>fhD<QH+tr~JB{n<Vi&
zm}eSc*?(Z|b{3$$R3n%0Lxv_ob3RXxb1)<DYaN6rI%A+4pOU={LtJa5k5C`$>|24X
zCoR_B8yVj^kl!4-3i|I_SGj!{7hS1d@V6;E&AalqhgH1{2cgT>6GN=u99q6kKX`)?
zeO$V;^5LTT^r`Fi`@R(M2Yy@;`M`Bu2jSf`Avu5A?XaQsb@+9+ol_x^h^BRpkdBTd
z!j50~P>`cnvPGSd{6Ej@+??*PSa#iPe}QHg-AKO9rC$uufzIL3TA)Y}d>v6PP{cRa
zO7u?z)63aEHQI0omf!f4HZPu!b`kS433SPZ8x)#!LyZLXy}!JQ7xeCMW0_O=`2@4G
z>pPoigwqTR8&pT~*>UTlR`&8^%A;0H&p2ybYFBJ|Tjg(+r8nAZ;Pg+}g?}0fL4%XY
zFlXbFK}Avx`I+Hx{>lAe0;`dOtA<D_24;xQBGa1<Ffze85G9Yq$scq9=*1qJOHP;t
z5~dR?#42>hS1JM5Cha(2$DuwJ%xhOt`Ws0p9CE*Dt_4I&q3Xh7^8^vR^zZjIPN2NK
za*##>c9C0JMeCx%qAR58)!`ey`mjg*!WbnSK~)*Z6P1etR}u-OQFHL<tWF@+R=MJn
zstsCyCyhrli8vl-9tk{u&In!ts(6u+N;6S2HRvy7fa9!sSNr&<Rvj|xZq~)^C__bg
z43_gpCprK41U7b%KJlq&y(^H8c6lX3G5{n~bKz!?M;Q|hL+Cq1{TkJEIq!B#aO11{
z8Wy8Jh#r&G`|!F5?5X1SwT4><os5v3X5$%vPPfr@^t&L&CB1oPXxDA`lwrT#!p4t(
zgCPs+{eOD+-q+`=dNCHp+(UNUes??a(+7sL90`_J2!xhWg}!5Ds*>)>NuWm2tC{AS
z*9x0dSrr{)7r$*=NMc1H_pdY)z4@#A#P$=M>+4TzZ~jcb*(R#M#$-)U$cYIfa>bd0
z?CG^ixG}J$)?6dB?TJrjj7Hyu-Qkir`aVR)oV8-A)Jn6AD4G<GIm$d*h(qcsG{6i=
zVvuB}u?L70tRWb|!KHXYF*Zrv#~nodqn7mqqP6;EFJRV~;wIXJlw$Tj`|AZ!|AN5N
zaT$OD<K!b1xs__({E--r7+=iSbCw8aVfn-1pCNY~4GE!wZG+-6Xmn+dx#93PRV)(-
zqD}3ven9vyU6FeyQ~1BTNOA(2ZV||d^8))ec{8oLVN1t*)gxF111*7}`41MLk|786
z+9nsqGQ^6IY$KI?1v8~Jn}uevPs<uiOmIe3bVB7e$+L8(6`R;eU_~z%U+6H+XVmN3
z{fYhNssCHaGUA#5cLFsCfa!FxolljJeL=l^@m=KRild|9@!H_(JXu};gd%}MHv2K@
zpZ~2gwzsbtdVG6Rl+WTo@{h9d-*DgOd@Yd%q5&e{h10e?8Q&o6Ce*H2o3gqqyzXGz
zoj6(rDI_c4F?mK(iDmwN{R)?NjxDJ-uTLQo;o9o*=fS;mXv8NKZnZB&5nKeWn!@z|
zxB%pvFLfJowbKXL$QJ&>4Pwd0c!O#rUgx6v!25=YR1{|W_Q*ey#nVGP2TP{o;Ek{)
z2`+;iyg$y=r5c^R<afgx9WtMz5-ijjLI)J$Xv7kY$<wiR;m4UYgbMJ)`EeAYop&{e
zWX8S_iw8SU!D8=t`E_{t>BL&^9jEGFk^YsH{grw5`|b~ysedOfv2sE3+dT-fwDgZL
z@BjV$6SWtbxxwLET2WouLF{PN0<&v<ri6-Xc8#b7N$BM<Ru0cs9ks%SIVjjag^Su@
zKQm|bw8WDV`8DRl2F*^e2<D$H$&~z#M~Ni=K*rHyk%#~~#OriJ2q;@jBf^Q(Q%u1@
z5J678bYw<=NPF5{-;~p}P1342ppvSFO_G%?o8+ekZAl4I?jX+9jXf`DYnuMItvql4
zWWDw#cr!TXd3zk+7I3;=pH6r^oa;68@iwjb-F$MGMY<P3v^TY2To?0*E|LEt<dNRH
zlOiTU<eFNROj>S2WQV)s5>R#P&>u5xJ4WZx^tA^8I3UI@Ia)D?;d|aGzfE>hwZqu;
zo?b)r3bc#f2`|(NlG|iwe2Q4CGxN>-hy_FnnP)^|zX=@}b)8lY{us*f85ujfg(f5-
z=rV2B+P~3f9}%jGu_CyYX0Xg|f)9hkev79A^av5ChjptF%(IzBHbsY3-3akF5Gc1r
zaz;N@43V#<3Y|GxdC`yE6iSH~xx_!O+MMuJpbLnUPw&tZ=u8#=3pWzsRI>=qQ7`4V
z8jdxN`c*!If!SsBjU}=VWrwL-562)LSxYTPHmmsM(MUd)VYkV}k#}s@UX_<rbapd2
zNq(Xm%acY_do7R)o#9)qu<=kV_;G(l<@R(WbF?*Pn2%38sPAc7Xs~#&)`YDmT9e$|
zmYj4D6{<&AZJ3H54oyI)vXR`|LIP>8MIBRcB@{7^L5MppH)1?9o<4G3@1Y)~hWN`n
z2!ILcub}|SnS|oU(M0k5`xS=fqt)}&QRzlC*jl%57}VPU$ruii2T($Fj?w3g53j7o
z<J;!Gj-R3PRls5n$Uk;$gDL{P55V^3=~PA@Up(N`Yg85w7f1^eS1fOU2y0OdMw%+`
z<TEO60|#N$+tO3~(<%+J#8ADCQ@noKO^eApsm2U^4##7U#wmPjQnkg^X|h+g=3Ral
z91olyA?Z6BLh(dS*R2)_LsvLPwl{;JK5;xqrv*N)8+g9L^EeYljG<5Jl0^NEXJhxE
ziOax`)6hx&5qE6h3kA0X(YH2-*>*;v?tMup3;@vGBtaqJS1AYE4czf7v?xu@-ih&E
zKyuivg8MlYn2}6FG@9)^M;}ZmJ6o2}6A@`goQ;uBQdgrdPjKzjZA99KlW+PtA~@~$
zz9XARgaBS1j+NfMEu=}L`<gh}3=;=rV+l_7TIR{GE?3<@5n{^!^#|n9XAqqmlHnQq
z>8w@VX~it+IujLF5m>c|t*n$;ht%`vKfn>(IisD(HilVu?D6$SqplI{|C?IsKuC)I
z%NxIPXGv7g_xJkPC;2+cR~+wQj|R#4mFm3iJV%YFULTI&`H$!Z-T+RxbHvolKhsEs
zDeVSp+_KE4Sp0}YpOY54Xj-l9sN^Te2`#HZ)zBT<L0rf1oo`dh$Flty-O+d-CK-_j
zX6zv*bXtSsFHOS0DgRF^n|cWp<;0I(7rYULva^+C8k0Zo`+Igqo#pF}N96W8F0{k<
z@lRH!kn#ru==H6`=vZ_;uPv6r9q{$1VYc#$s5lq{7F?t6X{2NZuJ+K3UB6JPIy}Hh
z^lw*}W?<AT!|ge527)BeA)#IuSf_S|?D@jdThPt$hhVk~sL1tTg}a#47=0w)wFPgL
zne@il85i-0MmKKPdKO4tS$&!RF`i-{bB)YWM*Ex09LiH-Bws~gQgUiQ7z@r$Za1oy
zTh1(v1?IWS*uHUv%~rBn8N&fe>P+zmY!@`v)n0JdD3xl%T#}hs@5H&#ypMN5`W0^?
zq66WoX+{O*I$QFl(G0{G*5)Ft8I$2<)=Fw^OH(0B$dJ2&MO1gZe-F#v0}F@Z<r{zS
zD~tQRcX;<wbj1qOrQnZs-7YupH=TQAfHbJ$C6`Likp+(gO7iN}R0OGFv>VY&?h>LI
zPj(y+HP&)VH>dlxhjMq+NL7wuTeTp{ViX4RuOhVR`IQ~{BG<3~DeC^|E}u3~OH%MX
z7(sb1vr(L!x#z32$x)AG`*@Z(TsSDJrU$`OY05O$9$89^8|Qg(5ZR3{3U5%xmGhib
zMpWwfZ4*%L&MHcw+e7<gPNUp$pNXjWe+c_+^woC^<VJ!Giqq4~(+cKml*<JE2h3L(
zpc|OxQ1<ER<R$vYg*sE_Q<XMWz&lI>=&u?0<7T*eK1XPkUVA(X3lzhSrA_D~wfG<`
zF;xym{A^!I@r{el59QZpvo}n+xv~!aIUUb==N7wK-BB*6lMcT_5b#|TO$GIfL?hdd
z`}RDsO7R(Y={v;;?GVOAF!Hb8)h2B#dN~(u;)ZpXIW>#1Dpon2rwNh3yB2<Y-Vy&L
zbHA#cPH))JLJIuxn2vV#ziv_|b2r>H{z2r}N6I(V2eY$s2%|;M!=M_WOQ_$x4QNXZ
z$<s-1zQ^sL2!NttYBdXZlNVU9!Y8mc93w^|BYq;{n8S8<P15R<I;r->GlMe=OUgoi
zs<lx)k#EH-LTs$={GndZ2DTG3V$D>9NJcDy_`)_C-CMSlXvgUiNr#KOk%NuVIhpJ*
z(t+aMUidlAw5W1W%u4@GU)isiByl5`NZ^QVWDu5f(LqKSaSH|1VWma0Zwrcp>6DG$
zr@2NGG{jgN1v2uxB~eS7lgGj)VAQ%$VPwIWU-DYip2Hi^&^e?wG!gUK;MpFstj?V?
zVEq-gH*!JoEC-0{_CPFWk93vukTtM8N7nA(Oa%12r=U>wwLUpSp6YbNv)5VcgG|}~
zfM-Pp|9DQ>(DPRpk1*G3j;d;J2@yZnzX13;TKnt2zuvWwZxcYXFAO!iJ+UvSQ7&!Z
zZC5l+8MwOc{a4tH)?@mE2zvUjI=(>sJbz^;^f=^VXMbSEMZQ{CExLM6a!j3wo+`xK
zi8Z7oqUW)r)$jTK&+}m3A%g^cPvA-_iE>;}HXSEGOCn0JWbWG>3Ua>O-#74x_y$~R
zk)*lG=NFLBYBgd!bSgnDpYp}N_P)N?`Mk@UujKlccgJds&7dl!){yx1O{qq)arjHi
znFZoRN{tuw%4~j^g^dVC*xB_}ZYJ6pwR>5N*0a_Sba{#@t(s-<c+<yEI&dh1#0jQe
zMDtqj-QU&N!Al6jr;}o-q{=4?6uRH@{c3rgV%2SPT8l(Pf{qj99&#m57nb*tK&=Ci
zw5BGlsZp#Fh`%C91r(lyYgG988PH!x-bbaRog<c9GO*0+Vz$YjA34ONBol~DbYwW;
zi80$k(YoVrY6_i9VXEDUh-!mw31UUS9fS8?AK{s3-86XNSRxe3M0E+U!pO2>{#p;g
zACC(Th}|waR-m9e%49+b?n5}e(rKyVBZDj~N9E7l0bVH5&8D}(m#dDAD~|QIVTxek
z-gTd7eeeA*KDQTq5sd9WUy5~|G8A||MzP*|KJHlF`(62e&oE`4f=CtzANyZlPxL*k
z!`2DDhWgq3Ht+B8t8O`OI(5&c+suKf+8LqL?^{`c(!`2Az;$sEb31Q=xf(6Qe(|yY
z&xMl*fVIEW{J84()Eink#+Z+K-vS9b(WcmM-2i=YcCNN}gZZixsx}j}FM7M0o_-xL
zbNb2KcAz(1@1cGP>BC)EC?tl*i3wRELVkOhQ_PbLhV(BtsAn^_5fV&cp0$&BU>ugH
zJi`S<xXF1Fi?aAhSUrTfO@btAfN$=Ah{_}sWE&!zHwF9vKHndb0=36bU4&Xg2u}g%
zbX-w}*39H&``KPKgIA3nbhx%gIz~JVM-8iFZ~d$3%r}EyQLB?>Bj^QdHLFerw+{Uy
zA=oYazsmUaFi?>6+2I(vviIxZl-%K?;~u*houM8H6=@_zLpNfg+NvP?%TcGh&=Ltp
zATG`cHK!g(mwD-8iBS5J=j4W4DzA~QV?d0`)7t7k8Q7Ee@(*ZhqeMDlf%*gb**6A%
zLlk(Nq+V4pD48Hg;wtomVFB}HfF=l74u^kGv_SZ@U4O^m!Z#yKW)^9Yabl(XP!*k>
zVX2P0(GuhNSUilL-1Rh(EPLklP(?EPsyKJ!?=67n%nwIU{S9B=ZQ+~{9QE=FS+^Vc
z?SQBoG9|qf0t7~TZSSNwSQ&>Bz0T<ON$YF2C)V^aBhOiOZ@gSF8gmeP9W-^Ko6BL2
zL@(13kNMG&ot{lyR`I>DzaMY7e_6Dbjb7S$uW9?ycVd6Blk?K5TEDcGz7<vG$?NIt
z8UWkuw8fs~ajaTi$!<+G_A7&{AqLs!Qq{(`YHRRLwhD0@6!1|(iFEIc{kZCU@P^Kd
zdu4ke9=jUuTV&2cybRL!g>qka+^;0_aXEo|-Sh_b#<spa`|#`cd^p?)OP5#(Lg_SD
z2MrPV5){c_kc>gNxT;+qTVr3&j-{YPOCl18!^AaXta_@9j8nL00t|8B<|!;oOS!6j
zvby(-i=~?JO-@i8k!F4PEhuqSs`6f-faY(1lG%L6|M+&fkaG%F7MT8?(j}TAOZ#iQ
zkHX&1+(vP*EPf{J3x$yN`27yo_WzraH8~g0wn{(M(Hbe`@~;#)ZlgmE<IK7EWGhu=
zx~IEjr@<um*GV2fT3fV(6qX5%+_Ol77JAM}Za$CAeDjK4X|J$wv&E})0wqnnfTDW<
z<$yLUS_2~}hS#B}EK{kGqrWlXN9zo4h3r40Xe6M1D+@(4J5IB`ATg(-MO9&zQ8T9E
zn$YW*7mZh%4mzx!W+w`fY0Q4MhBE^kJKDrS)2tmm24xQom|(d#O3N>07)_O`CK4Mb
zB8;ZlJ9OTbZl3%ll};26VD^obq!HZXjL=_Gn@D-&6`RaiPR=Kh|HR820?_Ht!OJ6A
zKqU;lUf;Wpc$1#1nWD)Z@%LTjNBj55y2n??rdUs`S%=}J<@7Dz$BoXwt`Bs^t&R&m
zXo#&K^`@)MJ+_Q>{OtktCWpNW&k%{9H}_EdZ&j6>Wm!BCHk0Y~JW#K@Q{K=Z_LlVZ
z`8lL1cuePw?Po1gF}I?3bQFW=Z3X-C6q~5ux=N2jtzee`6js)7eCfj_^gWg3d4I$k
z@#Ht<B=mgH=4fb%nesl*Tw3OQw#|3BMy;G!aM<`+_L5D`o2K9Dgh2GNbc2JG9(ecs
zjB~(fW9aPc&**&w{_);^Faz+HY*Gy|g-E2FiZIhF=_Xc*{i}R;0&o!N&6e8P7C|^C
z0~hiIs$!llNyZDt?C<fEO<^=Wge_qKeGgsVgELLh7|J<r9GQp^RBEz0-;Qz2Y!VS4
z^q)u$5-qfUdZKvS|Hh#-)m|O30~T4cr5j<gmLpRP^9<}XOM|K{B|SJrOk&+g_tzvY
z*O;Iav`e?Q?5B^Z%ATC4k%(rRSw66&mXEgu!6qm$3q|)K^@lSMftg5=4MGA9&}v6H
zThl6<{mZ6!kYX4>%4vUCGMEH_t&<1LS70=ikAjIdq8v28@>y2+DXwnqV3*T4<eNmK
zQW5i^$3q1kqs^EgRNnxmifXePEiEme^Jx^Qj-%2(T~AJ@l{H$xc}OblMHL*+UBlpD
zwfn-*zYV1#y{9BO&*+Bb)`?Hh8!yAcp*K!ZQE)THcM;tg^EXE4I~n#>lh2{`rTKf?
z)Yiu9^{Vvsv_sX_{sI*6{omd5<0oc*I5A_G4D)*N@j&Z#++lvj-MQscUbWJtlqrW0
zKfwQ5a!x*Y!DfPSc|Nq>n{eU#RdeCp-y1~xE8@F^R})v}c_@HM-UX3tKvlEuotUn$
z2c9dgF9G+S{EFRg4;xUIEPOA^;x%2q^{b(~BnFI5ALdJl-FoZxY!P$_&0bGfAZvvw
zSX(Rr#dFnvf)gX|b~b;5BmWAFdmy#B4g}4wmDbMu;U~A0OQAW;oP)(Q^fwH6?R@5s
zNq_4CZlp((vkK$Hv$N~_0jEnSPUwjG!FTqJ?^d=}z(jjRXV9LU%pa~B7UAY>RRnb>
zb^q3ppX(6A77&v@MZbf#nyg{$uI-GB0>b=;aR>u-;&O=9%T3YCXU9h{qtRg?s<UKk
zvSb~=yM6R*=zn>#3q^-3q!WKnlm+#rOI8{jEf4;rcHM->whfFJZ3_O0YD<(mgg**W
zq~j~F0R<ph$*N7Ernq6bx6E?#Ki(Vc$(7>NS~>zVh_ykD&_?2aSG)>?ZDIjjV6Kf5
z;xQ%&WzT_+I=~I9q*7MpNg@v&TyDM0p4x0RNwTqR8g(63qLL;Z0y;G_{&ep-`-!S}
zMqc{GaAJdEHX}Q1AsfxIr^%?_7LK2gETpfnOYhYq_m3;_uD6;N07ACgy2s`9x6TV>
zp6Drl*PE=R&Ymp}snheROYHaOgDXbgE!o$`4L5#<EbSg^`*RW?bo)+^^S@@cp8trp
z{6H@PZEn2@(x8bsPq&A*jST79VkZ1Ox7V;Am)Eq|F+9urpJ+mW;rFyH-3t#-h7tdr
z>%G<HpN4qql^G{9bx%vkWL_=@KJ7cFviGAjQ3nr<n`d5mKYU@qWB8u2)*m`SOchCf
zd&Do`M4%Zq%|Ex;efH`ugwB)b&#Aw|S^gbS`m?(`VzeBr6s?jD_|}aR;1PMgDEWMR
zciyu<kAioL|15%!_tavKe9VD1o_cTHmT4k*loN6oaGQ4>aqM<$-Bw$4F!{1NsNK0Z
z1enUH;Ahfo(?4c3Ee?phOq!axRBagH>}QwJlxB2JsajF5qh83=*=imV09&Y~USJw%
z>0tobhenWn2u8hDAdf*1DUtK3soC|)YdM|X86X7Liq=k*Z?0x1r9z_Za^m8oFaWW&
zzE@JfVif%G%f0raPzc@O1ktB8A?hYfcS^s3pglAwFg@Fze28i(D5dCv-iYkby6Jy0
zWAavI2oW~F*>fQko_psGk6Cj7Jj2c354JByu!`%aNVJJ(3B+kp|2&gS0W?A#hqouT
zS7JFZ1W8LJdS6*bm>n|yYKqBh9tw0TsONhpeS<<|hnX2%!1vE;`ph(uIcBz@0$?8}
zh}t5h53p(DUVjfwZH|CG8}Fm@Sv;UKgxTm)_*mlW4$XhZScTs}>q<WfTpJvGHcC<y
z%cDMT^TMlY_sF5F`eaMYP)=s84UAeaqZuXdHUD%t84klrh~2u-d!gzy+kq#<U9(E^
z_H2zN@;o^?xi0hGd=0YYx%*o-fY8i2T#Jv)?**y7TD21~#rL<p%_YMk)P!;byGT{2
zb)*3>j4qbjz*iZD_a(<4q-=y1EJa~1GW=ytqMiiGB;ZeNSel9AgdzJX^wy=M=$uz1
z&p1=QA*l;E21MbUH_BJ54<v-0WxLG&&6)#;_4HGJD&Y|AKBH{EwGll>zOO`nejP`A
zUzWF~yj|JZ4-gy0ZkYNwWSBWr#**HsQ7Y^uDN+$(1L#;Qkn8BeRmqzU*-5C~&!u^T
zxrUkevB@>QKR|jjO04efq(9++@*6O+(Hc4Q4Xpkxs+we3(1Qvl)~ZpGPyro@VRa`S
zi+Q?{6A|bbhl@phkRSD2IE%tiFOwfaZdb7W$gw^vTv+FBwX{+xyl(sbNw8=ziEhA!
ztb^_eD05ZznEFe_3VXyk30@xMtCF^E|7z4FRHtaZK_^rN35D|T-*#0_!Kp^FWzuj(
z9dFXCoC57Q3bdQqK!}7?!BY&Y4u`}&&hoqDEn_8=1L?bzlfM9Erp$c00OEaWXSIG<
zJ~1>083-`~?uEf~+=-6EOW@3BWhNVx-oSnN{quYrHo&HaF{>d7oPE*T@)J0O4CoQm
z3q}1Bu$=Sq8Cgc}MDN6jJk7qlzy7Iub@7@i(C>v&+vv7p@6+QGiAKa*hDyk|+}?$F
zADjni%C;dt?87K_lf~$qh}2r3Ty{hLxSCC2G`63j6<))$C^1lMP@F3q`aU8b5NK#a
z-i>}afg{?R?KU3Ld1W12!L#75wtR1#suwcLc+lYO3B&!e$aQiW4ieRMDjAVJazhJ;
z8g%37F==%@ykA^gJbsN4{bU}-?<~ys0lC2f$5;hfEaHzQ4(1M~j9i^-&J0=&yqnRM
z|JLB3fd6JX+2ST6OKZCu>WkrvEL#5v<$Rw7_*Ken*AO(qmBf^Z=&UWW1n)Ymrsmr6
z_4LlF>cZqkMaf1NxoDPoYsAsk!hH#u1pMNV`vN<0Ps-_1!>iq+#@EY%s43MDU#_6@
z0e-d`{*QXAmlQ){jmB2b+=9Mi(BX<a<GhM*kq<w=H3&4^QIf=iFv5mh2-HQYWPpYX
zyQhXxy+>8;SR#p=lu6-U<<0Pnrxc>O1|Dz2JQXbY)Qnym)KVeFy$lg|&e4k%1_);%
z(-s)`LJvqTL<^PF{jH^1+m)KNCSNRhtJnZ<HA!;OGzn}rI<8QPOwxZQeY4vSHRu-|
z64H73L>rwhZJy!81iG~s@0rt~5x=Z;xiz{JHM_4ieRbeChsNl7rOnbeuWP#@pPM{~
zzs`s?U3)_YYiwM6b{qwT1RxlCp@L1O2v<$5m2yjn_+NA9a-RAcs=#B?8qAe``#twn
z)_fBPqOHlSGQjei3t%23>2vf<`AMsPHXmaXYwT^?e%ahG4;S3mC-27<O_a9Fe+(LK
zDV*ysx<(O(YZNJgNGk+=#7u`Occ03NJ!NQG$Ngk}(C~G9$*sjyq=cKufQ$3h7Z156
zyxglKle8ELqLxX3kK60lWp?>IimEe}AO^@>Fgn8cp?;NaV;}KHsqU-|-@3gV(ZS1O
zvrMQc+Wr`@eoM0PdwacXve&`uuUWkRp{Dk8KljbMp@kc|QqOiUDU456h$+TWj-THQ
zTR)sCr|LzltMgrZh03nZ=DN{L=Z7X34l#yyz%)kLAN#SRpLG6+;6*Sm9K1_I0F$M(
z3IpzPBQ;Z7k~tuoCO81Cgk>$<gYLyh9J@EDdSviYrIJvYyb*G=ohR)Z0#Ab;Q3{9y
zY;dQ&>S6J+vO%#mH8-ThURi255rz)s=7h(eb6P;73|1R2mg^Cq=q(8N2m`Xx-c>dA
zYy2Bz8OFM{$sfV0u{%nqK$JieDisRKSJrUEDl3dE^5#RSAadkJor$sVNppk16#jX(
z_oS?@L!DRkZQUN7(uP-7Crt`>BI$E)#o;KmG7JL2USAnIgDzem<u|um&R0Wt-Uia$
z_6JsZJwWk5^fz2ozRP|~ubUryey+UjVR%iHkFH%FnEWsH8~y9=YpO?E&v&x_nrp%k
zup7BzS{%I5)vE|%OwvCiN~|F_o_=XY-Coc28;=8K5RYT~tV#aiaDIDfQvC7sJV4xx
ze;2o~uBUgWunw{1hE9%0L@9Asda4v?)dK}59BCbYq=wgor&?`bn~39B&CBrkDzsMU
zeF_aYh$GdxHQ@?3f74XOJwmVrAZYnRg2eGqPA)D{19@eCrRp1oRzy{*(pkvybAK@y
z9QdX@ra)&LRR%(qIqd?T23D17RbN7X*_arYn<{U7>)+z|Ebl*U5l$K-dp^N7-JrVM
zpr#E8C6SUZU~v^Hm0%^0xUtCrqTtM&zi15Q_V(ku`xAc$>{$cn=IM=AUEtHukqwSZ
zw)5e@P`IqSFnUPh(Hqh7BLS%XsCp}<Y5)@`)J>#eEKv(&xkd{b2|#(oDB{c?KT*<R
zep)ntijsaz)>F<OWa*B07|XeO)a1Vh+x@jl-TVe5fH`KE>Gg#Dv@KzttiH|-DUM+F
zW&5)Z2ywydJD*z#1KP@;?OvuZU60m_mlIt_zbB1-o)fBe7LwIL^hr4y7E-U5AN>9o
zACr`q-31NL8}3~PO?-j!Ua!ut!y7(d)a~isPZsieK^qp8j)#Csujji%C*<?^V#^J3
zBF65`&eq-}Pj7D|_d}iY(BfI>Am#=gp^sb58F-~0Z`7N2%-)E2D~srw7_(q@GFe5)
z2<jqaPMgm|`4Ct*O3w>&GCrjWC$cD^q2m#<xb$}_n-P=NN|sro=u{I!73C5>?2n5X
z_BkR{2Dj)M*&*;oxS6+q|BtAv0E&A3+JK}Wozf*pNF&lMjUc^rBP=OM=hEE>NF&`{
zOSgg`-Q68a!}sIf|DA7Uhn->BVfVb}J?A;~oTxXPd0(YXP@PQGNM||fW$;kS^u-vx
zz1jiK{5_I`&H{;_%nMk@VhB8tyIi1Q^ECtt;(g`Hi8^Imc_<9JT50SPU1p!98dC&<
za4-xnr@bL_$9<!cJQ4q(xWqqO)y_jYbg4WXv~7tp3F8(H3gd_qyhIMEdU(`^^Sd(j
zqH=4#rs3|=D0H9%YHkxMWAfd19^1d#sD!ohLd5M130|{cebH7MuB;*z&k>nR?V(9J
znH&klLF1Gvi}&f*<TnG7l2xHh`35$MdG*+#CHg(54uGf4h2XI&@rlFzM7Kp@C%a9K
z?{-j)#aT6><c}7)3|=NxZ`L*-Ujd1nV%sidtW`XYjv8{dh3m_0hA%c~1bx$-d@c^z
z_b}E+6ziA&{urBb)~3q?oEh1hczEet+vQ03j%0&Y$m}n)a0U`V63;AFi2=)!4ar_e
z5JZJ!ih$*d5YR!&U`(X=2hS8Yb$<deS~wP%vy;DwIS(w%1Nx(0^m>+z%G0{_I5l|g
z62<j=nzfE2WQCy_+r*iQIo;lH)Lp&LERmEy2uO%^FWyfbo@mAe!=)H-;B<chNJC03
z@Sc8t<4X#GM;I~n;EU%`e+LBSJ&4FzH&z}@-DQ8|{_6#>T9$4MF^gE<uetZ}-|*ct
zz&7$blpF#J>6Cza9(8utb?TKy_PP1unN7@|>#?!*7BTdwID?{^`cwoBDX8#N#g!ex
z$xhSiuOV!Zkgt_$)q%I@KWU}-iZo6AZ936jY&D)Kv&+1YGLVvFM<rCKINH952;u88
zwu03#QK+z>I(HJ0Ff;lzD(Sa%Yu)6;1?d|7u3G$Aku~JAEZzgaZ6W|}Qvgo%iYTr<
z&3o|3p0C-&%h~t%e(|{H>i)6c;W6TYd15u@M6dnshwFC0{&o1%--`9b>2Jvgo1K+)
zf4w~N;0!$)mW6-`F92?fxVUHl1^LSAad5?D+WYB!gK@sszsw<R4=NTpNT1ZY?9+8a
zdfuwbT1^FQ1#&RRoe<^yPWcK_E6d3*8`P7*MTS@OfAj?f*N#?*?A$oU^>T($f#}fp
z$u3MlzlBtcazySv%2vlrtA%Z_+j&wVhHupn(8A?ajCM0<{hFtcY`{S(jn}LI3_N-<
z6Vc~`RoGV~&<#^D!!JfwU5m_NlZ5^{h#YIp-m4Y&ln9xzq|vv9-nOF~x$EWgp_0NW
zZ@(p-OgAT#&dKF{|L`{e&cg#MKOTVv7a|jir$!%HE{RGKfFCQ4hXT=mXEbM+Ndz=1
zSrpRF`Wvr>g(T5{YWHnNBow(hWKefs5~TO|S&pbyIQNC!*ds*Jne<dy?N3`UQ<(H4
zZV~r5sht+j4_(4Ba!Luc?=@D9MOfcERR;ozd#3Brm?L=4JuW*F>w<aoo#~~S-tCOG
z*_w|4>}5P5Up~XU@A%fvAPWS##Ms^dK}|5_Efi~Q{H7%!=46Z1qN;tm3~~dTdR?w3
zH2M54px#RQ-q!ZnOMQ!5oTpr!oPGy87+VbU^^D!a_lvoMff&d*Zm7QGzWGoVpTAg-
zf#!%|>hD2~i+t{(5(0TYEgQ1sG9%LqZkpuAj%8ta!lYzb`Y2P)c+d-pe)NK4%6Vb%
z?e{jO$^N=I=HwKA-c-$-3(>OojPr9uIlz)~YYbYCn1rgnP+tFLWSa+d3}k$J{`vlg
zZg4vJ!H2=FRX%fKnrA0Pq1_ZZ+zl=rXK9Yww@ynv*8AG{cq8=I3(L$zhCIz>rcEZg
zB6^IhVF~Z%TRMgHuz%@YRr9y_GxeR?_P>fvb4m9{M57Wc=4W@b4+q#@gv&*J7C^UI
zW|0|-0Lm0u=K)Z3tobr&(aWEmOGf$oN3G4e!1VB4>4)JePpEV|&aj))B*)t5VdB}f
z0BAqqe3ie<!b@^L{zlGI;a-=bPRhwK_4$zauSu&t;Mz}0rcc(N)_8uM!PwFlA4ndz
zMBFJfm*zlm7Jz%vp3$OQ!FmWj?&_P%I#02?o(sRejn>^6E9ve&8ez(CgHbEIIXq8O
zK)xP#x>|=#&BZ;3xR@UeQWUua&woiYx*y_;)0|Sm9UPXe?2fj*5CDBcakJkY;L>ez
zDL!v0T3p1bZxBjiASfbgK9$#MDf_}LOFUMwYUc0Pz{4rl=BmzSeiMFz#EfI9Dz-=O
z>SM^3qrOn<<7KFy1Bs&r>V3K<!?e07gIQ*_dg8mL`b6_8zfh$)*@U+s$in)2pV3+{
z5z$daw(wXWWpkO>gW4vVjQvfk?~X`qS0@ZxA^SjCVF3-b!<@G>Aa~x?zBcf;jjqA8
zy2um7^p*5JR3%bEvQZ||uX%dl_+bb7y;ZsIN+w(ZZoq?f@~SUEPsvy2LY==z*72iP
zkb&$6RTCOciT46jxr=lX+~>HNZ^uSPrM{H@@nNqHoG5^XzvU>$tu{7}!5=qW;?@@3
zt6L|zjIW;*o-Q`Xpta6GTSFuP{}!_;IFrXNDQg_mvj3pSUSv#T_U!C$PRb;X;DK?Z
zlWw1L5}^N@7rKduwMvdvYT^_3JgK^^94$(+iaxsBCGxnddBT<HzFxQpG_42$8Hka8
zP^2|nhh@s@zOX0!)4_Jd#m3|+HJs~izWmIbPA?EIc7OldGH{MD-%<k1W=KePOijJk
zzdfU0Xl&Y*w0N$`Q3HS2&34~%wc>|TzJA|C{z*g4B8vqDr?Rarh`A!OHwy1X94ef?
z>#DFWkeDt|Zon%q_zUm-fR1%X$ijfXhV=6^=X3j40&u?Wy(-T`3GbcR*Y)9hgI~RD
z7Fe7Xr#WeB$t_;lZenEZ5yBL}mTJ$PIL}=?m7D=!#A^QclT;VG9IS44MV8LG^ar2K
z;r6YRLT#o)b#8M|-SH`(+k-SXN%v-1hqu$5w{L)1laK5hE6{u~-2HYWP-r2e%!t`Q
z3=<j){|Scz-gurdp<g$sF7WIwZ?2ezqI;vnA|+;LyWge-)2QNtFM-vQ6dk1bRz7>7
zS{#-=71jg_<>tt7zYBlkJvBwI=0UYt`1mNgQf7J2dZ@+`(x;g@t3k>y{ppmW4*STJ
z6bG?tEbKmQMjBDPVYexy=Fu9QO_TG{5Tt*?rPWiazc*Ao5#Bew!$SIC#xl#qzCHAi
zuq_i=<UGVt7q!+E4-Wk>$E?toUstwHNb?}v``pm^ia}?A_L=47A=8ya<i<&}vWmBZ
z1uI4Ag@!aqh%X2fKQbTwoI}9+8ZBs{-{$@rK=;Oczi<$Yc!$}^e!;y=Q3{3@v;rU{
zT@(l)^}Q}>^qCuw(Jt?1S0KJoGfVoN6`n9X*JY22mHQj8X+Z1s2nK{@7#_R6LGv_!
z`?!B!bA+<4C29%#Dd(M>;OF>_NwmqJypFjZzDeZoHd`hK1_Rora3JMx#O)DW>-N`$
zN1uys-USf-0;7u%mSQ?$cNe+h-99zQdqMF`<Dt21vOIxp{K#emp|DfSvp{i8f2x0Q
zOy@-;r99;=y%qpjY|QV7VQp`KG3;^n95SLH0lr{8;565^Y>+;1W_*zjv&R`cX~B|3
z2&ABm+TZZbY3KjRNneWlfRmjw0yq5CE5ZM#V=0yBPOV#Fp7Mpd4-y&;^~YDSG&DGB
znT!cX%rs&=K{#)>Vp-<~u)X3~MP+blRDJS~w4BIs01CoPH(=C)^{qcrw1^7#wod)y
zx6(1?!iPhJ4(tcy?>R}+r()a<*I}zB{BduGQ1r;{;J$d@zpNM_J>!o!#!$@!q|Nd|
zskSjVCfIlXeSf3(d7%)1Hi!G143@g4VEFqbiw&5A5*-!7PPrc|ZpAVzh@;bR&(;^(
z_nuQl`l6Teq*?CUJ8W9b0ru;+Z@hPtmm_N|TsU6;W=}Iig(t>vqGDKRZu5J1$PTGl
z-^h~v`l6b}ArMyobBxO97pv?7UGpZNz^UBtG;Q8DWIJ)u&hLUv;VnVGqW2oNdpH{y
zgyV%rA7+8Y*SGCsTA;ua=b7dE!##3!<NWZ&?sDU7@cv`Yp*<QQc%2i`CV_y3lR*op
zcoLEz0Igupo=^ko52{gD*v5YM^_EYrUt^hiEnD<ys7<i^ygKypmdl=ak`+=a`*Mr`
zk7@vk7Y$)3gW5t(KSXs6@l(wDXLV-Puc*JMB`&1u3kP4YPBL8FbHjJifKbWh8czIU
z?{atWbY#d1w=t}z_U;3&KG(G7c;~p6tB7Qm-(%yjXl+LCyfit*Gtsi4axc<f@?7NR
z<hLbgZ2O7yrSwfAoMECO6A56yv?v7cHh{S73eMJ6@g&;&mH?n96drT?_1B;^Q2B8j
z2(JGn7g^^s;w4|1tNZ-%Flb$dD*hnn)q$DAA|Zq<e{LYD1fPLf3l${yzLPj0FceL2
zc5x>G3PT!Bl7X>NH>JPPR;#}|_hUHgwfG`@6<RMeuW~n*>jme(BYNxkOJeA$I(ouk
z=-np^&K%;rs7R-;DTv`fie{=BjZ--m_;47UFZsA;`gd(8=Wm#7x0q8PelnEjlHOhz
zqHp50-5Z-n8*Fz~C^SdOa8AYY(};>~#heq{w2~Ow@VwNSw88Ya@l?f4b965hk=e&L
zej6kzL^Hlp^X5fGtGmF7VMQb`!<<EsU1Vo^OU&Q%9cUy2D0Bwl6e{Rww45x3C4Liq
zVpi%^z4+*4W+50x%^+?6<4a;fjw5Ei0*%XLvslPFjS0)(n=&voFa&T3LH0QSp0Hn_
zb%piLqYt*bfhp|_D6cjmfnNep0BG3}ee@TZ0XRQqv^eK*c~jTFk`9Y-gA)~gP({lU
z>y`^NKJ_hlC^wR-vnHLPKf1*Ab{aROctN44oPKNur<B5c)KoP1pPtT>C#j8TB=58&
ztJY1hpo%i@{d;wPhzloG&2bJnFr^vNl6vU$tTqOVA*R1RSf4PY6u3csZ*EP@)g@JU
z?2tgGD~TB42*S|o?G%g(!Aca)2LYR2nq3JH8FPYTHOi05$Qy81p^}a&lYw$kvG8G8
zjCM1`0r=Qn@62N2v}k6#Le%h4ghW8!bepJYv?jb6nAA|Kk-k*8{`#tpB1<N7@v+{N
zWt|C=Gb*M8H?G5PoI)V8PKoCys*+lp#4Q+4H4fZ+!k09eDKICVH_9LjC}hlk!Xw5Q
z^0E2q>A^#Wjr>Af`10dt;8j3=09{MQhQU@6^}X9yYTTeR5M2+J=%+tu*47zb)avkg
zXC=qe-GbiXnreI)^P;4K#w1k?&KRoJ#YFR)PoOP9yQ5&0-kiG3euJ{eA*kTHKJN1{
zv(kEM^BH0VAV26H-2w~?wN%C`0uRJh@jR0vg`$^TNbT#D>u28cUO?CU3-Hg1eN!K}
zJ;bJ@O<8Mgu>YkW4i~>2eOw-quO@TIARMqX!`3#DzA^tjrxMES);iEI?~-Rz9r%Vy
zi|0e}M!Qr!<9(1=n4zk(%`1P%pAs2_2pgQs@Go?03PrSO_o`L|h_9Mxa=ed1y_po_
z-bS!W?iHYM*(UnCqQ^GxNeM;OX*;$?7F)N4h5<6Uh_rzMdIuy=5cEBqu%_*tD?Xj}
zve_AN{`R<dW-<VDuG^t@CDdgyi0SR{Jcgt1B(KGAOkvr$gfwUqPi)r2TXh9*2lCTh
zT35=?cVuHDfJW}D24+TgM_<+TxWE<_WU7)~MK4R}&U#^-CT=PpM?7cKUmdrAJuzoY
zNAq&5{_Rib8r2!sc!4KXm>G*m(13$WWw3lVxsADrasY5>biCDQ6t5Tiyt>It$GM>l
zD(9Y`7XSM7IJjXcz|Kuzi)xo?SKT|al1tM~nYS5~yL2sBpRROrl?Q-b=+K=OQK1)~
z7AS5quOG`rKIi<%jGmamyxkO>HyJMn#<u8+BnC!4ps29Ww)JsYJOJa>6(mx9T-M~<
zY7w~B(WM;uSfSh3UogXk`-g94M^7~r)_C{tL8o!x=NR|>zdR3Ds2Ogngu<8KOMaME
zERwDF1L;^Hk7wif9B%P3&9E_Sw`EDuev}58c6*=N)T=CLP{xmG-1O)Rvmu^Vw-8hA
z9}sDbcgwk6SWwdJn$k1h*1Z}?zB~=TTe3MfMW@Bb-&ywFKxyv(VZg<|Yre~bOU8<b
z;YEhSvUb-2@N2x-;Nx28&mU6)6!cgMNNOr!@K!r0Hfm*Sd-~)gdCV<%=&pHxe5)-r
z!YBZ4u{5QnED?r1XwKW*=14YG_HWL7``}Dv#^{qJ67MO^hf0#8TpdU!l(!wMvFK!s
z?^VI$5?|ftl$ZeCWoT*FCoMW<ic<8sv{<TXJ-z?dG4$0P>}XKNTU*O>9u@lLw_C_`
zmCbXF_wiq<x5kf^H3Hqy4*}aJ^2!GNEDZ(}LBPz$hdzTF(CCUh8<=%g;@>-p`7x6i
z!!i9s8-sqa4x4HjQT17`t4_JsaLfg|MG5#QTpQ;9KqU)OWC=02y$b%y+2MWTc?~->
z74?j|t8MdiL~9gM-Oiw|y{$8t<-ygOpug~=58<c7zi}QH&ssqf&fw!LF~yEv_Vn*9
zDy7o0iPNkE&I#qCRAVFGLT8LQoIT@}K>VK$C^KP^?U;skA&qE?mn^R2UxtiuMi^~*
zUMF~P^l%j3q0aBxgOi<9+T-&3+J}X=v*OpXu=}rM;KeDf!U(-R?cOlf=<j6>H%Iu*
zuI)x8uz=D>z9^hkU)KeE_&_}_N2uaDO;4zn^82;gi0^{aRJp(7KA*05KSz9-#1wTe
zo>fPSLf_Sl)MsbZ>vj7%DMg2-h#O`AywNwGphTmfG4^hGO_vj{r!D8!lOdQ&%iezq
zCuw7QwAxMSj->4Kh%+Orcd42g!Aot?s_+B!h40iq5tmJmqhO*^Y)T7%FnL&B4!OTw
zm-TVE<+6U`r3ZC8K)Qx0o~k{Al(?gH)bt+LdScOq={pLywf5u7Spd?ju;@g|QZz&k
zG8+DP!^cBR>*V+x1=C?8C|TUi{DM{SfO;cmnaqiO;UJt2WTIK0C~^gZ9CW==f~oG(
z1hhq+0x&mOo10&dHkYKC79P3jChf9B%zJGvCNNSV&Uh_UU=Pt2RV2|eT_SQ+%rOPJ
zKaQuFWBQ5TOezKuRlT}tprc1rotw3INkvO>X@MXf<AAFwnPupXOy`_jll$rRXP^2u
z*F=f$59bedZC!hkK6wp-pD*41mX!UG6`MDHVB+_UATr=^ANk!{#^IRMsu=b5Fv%&T
zBHbACax-V!04BwO!x4WTvGL25go8=9WFEN3xorPZiyU!0H#aN$z<B;?NrGcfLox+Q
zy}jGmTa5pczx{%`mfnvwT1q#P=?bv%KFs}LNG*==Pc04uhkX+^eP<akhd%cu2eB92
z+DT^)cb062U%BH#$zP<uQ|f;AbP3`{p%reM4_1hJ-;SY|<dtSRX3-n4Cs^R!G=J5^
zFi_VYirHg2=WMC%Tsk12yX}WYSXwola@mPk!1atJqaI`6pHWYdO+;Fa`ofTA>~wF7
zgwr}x{1g(tUyk_q6)<+e)Qd30CWUKjJu|sfzA=eQ^&%^2xDZ+V{EA;0ibim>FX&K7
zBd}xg_&?of_sUsP(+y&r4-y(ef&^$m9c19KPct95ok7qdhr$8EFd4(y5RHfl^hLI{
zA{n}}4L^V4zdI%mJXKki1g0;gr9+*?aimjI<Z|SAqE(fJMzq@KaU{wtajqEOfWi6D
zy)XFtzJ>Mq74?nJokEzDQ0EZ82-JXxn46$j0QMl7@S>;u4(tCVh^SDYRQ;cxTk(0g
zpin*z$j>Y+^e1O{VDnUUER23{pthyWEsF!$4`a(_uotVxjA;zg!`k)9N{vzSP5z*K
z&B<gax*@x(!P=SG8}*vY_*lJ@d=QiIt&Uzgb7ec-&Or6DE+64~j>Xf$M7~R<?dQ$y
zRR6@%@($a&%CPmrnQ(QgqJvd!K+P;Po(1TEQ;kvSc+OXmEcSi3VS`qvtO;u^b^Gp-
zFcf|fof5*bna4@XD>zK`>N1}sTK=5hM);u`syt!w<-o}x)gs$aV-`14U`8e?(6c^#
zOS`xGi{|q8@u%9u+9MZ{{6pA`crVXXn(Gp_33{5bKHUTM`s5rg?Dw|E1Z;zt*I=#x
zlwYxrQRO!#D>&Sidi>XK%bJaebEV1WUKg)UW*v46WJtwL#|O{9(~HkN+x>|Ru#-Up
zcl4*DnrZgo2lIpf6c<pP7L@Ig!xa-s4}kf@<bI7!&~G;)C;8W{nd83vjM_YWJqG*+
z`nhzUt%N+tg-X@`65&Gz$j;J(L;04ByxA&+?f9+m$A=ja{x~U<>63tq*E=u7W~y;z
z&$G<j5Q_Mc91=o%K0L&1o0dayX;Xo;Q3Ow_ONt)=Ldb-X6V})4i3+-jr+@CxyrRV}
zE=Jt6y9_A)1f;)Rszja9D__FvjOKts2M*;Mm9(9+PvtaNs6JKiNeYSE$oshp*5Fyc
zeR^Xv;p0(i15fykOKwbq;_V`=6}!|y1L-9Nh-6yJj>DkIzfsNe&0eCo3jvmzHS-Qv
zC}U8frn3S>sj1#=5}l)O{4=G*t`QhzM!Y9XksOO^QDgtFqhtQX{nulFV@QQ>ET_j_
z<~rl)n&ZB6`TU)(U;{#yEAlPO&KvP*U*v)FapdWS#sy~n@gV;n;Q4II0TG|a0zHU6
z_peGTA{{m_om|%=Yc8!n-;`XvbRqqO3pZf-nYX2Ok`9A&PD>)p-so}s5Ka=^dI{_#
zU~|G3-t;c=AZx1>_hk6H&k)RUfWn{8u(XLHlKD<lGTk!p-r1g~Z^~qt@W~*;(CCIw
zH0pBz2XFPDZUvByHz5Hgc`1m&Kxh5x+*fiujG+up^pg60%Z|9-O{X|TZ^LS{@zesR
z--qIHpwLQu9$Hn@wE&v8_;f*tMnDqEPlhSsfpy)_M83W-8gZ7UJ`(%4&d$3KEM%)3
z;Y{9G(NWUhVQ(8MVqWh*I<`bhGm9L1zH426gK9}5CfQ-g>MQm$M3aF(_HEB?#JZ}U
z{-1NUZHr!(S@S(+FQQwFxX{TyPll~$23Rse&wXrsP@v~N14Y-BcmF!iAOa&4btL2U
zYP9#A$+celjo7jrP_OtGTLDkskdOm>hp!g9SVm87MuiZ*f2zm|LBem4jf0H2gn)wV
zy&@?WM3_k^?f+>042+&sNwplOG*$R&wI|#ee?m8M=Qw~omEPNQG|S6Cq_sJ5S3^D@
zocbh)@<qE&5f#^6tkEP6sc1g{yYhRagIn!79l!<Pzyjd?lan37cbG0Qr^O-@G5cY6
zbnVMXZtdaqCY+{kAKw9-KHnmtn&A$8Fy&Y>9)6n-3Fm*8_lGd+A}pMu=Mp3HFzO<Z
za$F@d<3Wa6bc&A$*!}$DM%O<xL+6a~gxcx1SZ*UNjKdG+c9`#S&*`QMK1layMixPS
z&kW2+o&V%}r?_xkV{-q?u8!Ol9j7L;zqm?!xY+HvC)a2#qr%eR=mK^5{Eo8U2X?oV
zNT+I3`sySZ`t;)Z#A9^r<5RMQgU7r)^*=;1|4MWH+8>*pOzHHw!MdfT<WycyF*PI(
zk-*<w8&q#Jg0A-Eu>kKX+=e91^Ym9#O~4}rQmQooaWeP=@pmnkr*R`jOM_C!vlP)u
zFT-x`%OGm)uqLdof*l>MKDMf`K<C!D-}dg6(Ku%xGM=XZ$NW*Boz#|L#QtCBg%Qo+
zjJOFG-#x-48+9{3O^J{TDoIdiiaLAYeVzBp@<)Y_iHg#eW&A4qk&Q?2X-?ZicxWVD
z<ZAV(#&_XviLB$QDv=?1M_U6S$zgVN^Wi)N;uU21W|!IlVHOi?#ziAK#-NB)?${It
zH8bqWrd-_$Ux2-?mSJvYZ`<i`!exb3a>H|<cS|7I+SsfIVM-UcH|zHH%9_B;|Ks(y
zHWZ)hD`EZyo!+@UxTnDe=nJ1SEGQAFb%2KU|DfwXPf@rvqORwW=dP!Lcc0poxQmqs
z3~GD94!tOk!@ND<l)uufj<Le~$-c;MeKC_x=wX?E^yt~$B^2IK)#!X|hw%&=e^+On
zlOY_=6fu~O)B1yA>?q0T{XyYOur|_eBsPllF28DyCS;=S^OIxZOx2OaBc^3gO}CIP
z@c}<jJORK5G1bbrJqlKotx2N!0ZG9P!9C3+>#r~Z#^VCh-PkLQht~L8{mQSFoO&06
z@GvjYx0H?KAB1lO3#z3+X2mzRV9H*L^_#-S(hPbU@;#44k@Hix@AY`+wij}aHs>s)
z3I?QlFx|al+ew4rN{i34nHd&j?XFN4jEz>ww2-t^AFp!fUu)aYy!1a7z3l8>r%s<i
zX^#z%f3EkDRZcJMRmJ+%LsT%wYZr70X^7n&E7qFOG5=%@P$&6+gGokq!_xgX(<ASm
zo|?)Bl%-#ZYZuQJk5flr=`qGMh<_GXGtoZ>RD2(}^vOzy%ED>JO<D_&NsEa7mKKT3
zucZ%<s-NX(-m%h!FO`J;X}!6!F<{8k!YxK0q?w|wXk!}eH!~4OPSERl*mMXYD?rB6
zr8qGD(b`o4gz+9#(w_wjftkBO+fP@YT`;&uX$gz6ZYWkq-#CSk^xQQH%W^7uDNkP=
z^zf=)5}Tp8-@^|Q((ux)f1NQ!504niG-B-vn_7&hk->4-6|`H-q>11arqA%g>zTW5
zQtK@|Pnj_g8(J}mn3;seO_{{Y(s=yiZ#0D{Ip=0PuUj`;*RH9?o_+YYFppHrQ)kMi
zkh;m<;?L<KE&f<-S2oHN&q?h6<mIr9>Q~v)66d-)S9_XVO2&!SF&Fct#G0ksyNb!6
zM>D4=xlh+XHLCan*~RqbZt@;KMR2IA_nxMEh{?BW83uY$uhDi;b%Ds8==}Yq{DZ!i
z;b7qPtwN+?3?t(d9s{DpHWMMlH_;|6yjw4Q1eT0T1pMzEQi!oY?8l%6dw$aQSFHdg
z_1cn*s4lpR${=JrTPymK+;BEP48iYF0l8CrK0E2uX#iW@^Wr?^TEXGY^TB~7F0o#r
z8i}EF#HYM!D}Rs>%n_1dr>-E?&S4-#G)vj9(qH&J_;kTi&D*-<@y{=VC>$qh)MWw9
zHkmpVxpz^T1wL#cTD_A>&6?MMq@o16g%oS~b}Hz$z+BJWe*ej*f2_Osmdb#J!5~7F
zma;8^+h>rlU5f}jK{E|o<GVyiymRsO$qi-?H;CBhyG+o+%rZ7OXWXSWz~0WzJR~t6
zh#w4LLeB2bb5{zLMD`dI-nX(2Gd?;TEW}1I&(6G2masAa6LhV!TTdF&o%;qBYe||!
z(ius^TOgb0k{uYc()aKD*9+ikNE6?E3hbOX8cU-8=Cyp)F#6$Y)~m&%+2fW+IeW~S
z&QG68l#MP#Gzf01>Hy+PW<$|wsKv}j9D#ur%3;Vb!l_TEuTi}gsJX^Mh7e?^jfyBO
zPDK~P9hVX-oob={O<7sw=x)hLX*0Tp^0MT1Qur<%dbe=o(Vkg%3;Up6SF(3Cf48J}
zr@5>r1wg5fL41>X{ojvXH*=OgQoPY<2<ai}gDHsG+r{o3J0)m(j<iF3!n+T-#>G)V
zGe+gUIFSN-z1Z1$yNUEa2|zO@*w#Ej6BZLQ6+_7NA0JtVk-Z}J6n~&R%_NAd?-wu~
z&*t5JK|?**FSjj8_*7|f^R7PsO<5-)O?KudSk;zR4K$VDEgdY-V8k<uku=9Q0lWJB
z*Q=HncZ0Oii#@hJAxZ@|#e}43F9cydI^k_J5NvT&YT$?MD{^+F5N6y?6Q}PhoWufp
zhUx`wet$p<oRV-Dw*rk9J-u0VsVhZzjV1ehi9gCcjS;^edt8f^F6f3FG^$s#NL0-G
z@hxvrWeI-;YBkEK4$NLU%UYu%`3!tfKLi4a4xy&SxBItSh<uJ)YJy@o3epFtm4DLG
ziXZrIzbAM_yn#C2p>)IBmRBh5tebb<mb7$lfZBR*8mn5uAN$_0WRDsaRNS%dx`*+?
z74nui!ma{KqZ3DXIh91Q#WCUKXWtQ4lQxbS^hB<9?XYF?@uBv>m*1!9+~<GYv`CIN
zO2<2<(DxiVr^;>beD~{o|3&)sA^lM32B?d`Co{m26Bk|XkLKm)m}rrnA@W6b-I?Yq
z?eyyRO!4!31;Lk^yfV5HOVHu-{r#Y$KqH?aQkCOgc%=jp!zt@|yo^_fP@eO1UI|di
zc^)gv{=gmHElS3dKXWCEI{6E(--#l<*676<)#-d8e}#)YHD<ObL9?rOxq|hzvnOf0
z%wP$1i;Sc@akatX_BnHL)bAM*thLv_*598#Vj1+khaT##n+QLC-@o3-eXnys@O)m+
zhsG%+*Jx-Ph|}Iw&_mFP;q=2&ycm&<6&qV71vytY<_*uLpb8?~fem<dEczjEGmP#k
z<63TjWB4)bPX7XT!RP)lbPw!*U^?(9?khGYj6y~FwW`X?X>?wM=bIoOu=gvE;g~;E
zQ|P)+$c_~52+DyqOXgL-Y>%YG!eUI&;;{s)I!Zsg8Cce_AH(yrIa-+;naXJJSq^PU
z$i#smb&QX^)3BRkyJo>EPSpC^4jzNB^$}~<(_%9JVErZkkop>e?f7Q^E`7(=c=mAR
z<`K7Ek7yI4ES%wx_Ebt34THHN1(8<@+x<0J#sJmZq?21yIqEQuIC<2!L$ddLZM9rP
zUI&3Q2pW{H!&v*K!Si;Z*tLu_)WQQ&NI!{l@yQ?vVL9z+et`_qmMk5GBarIc6LpqK
z8FIY5&DQ}ZLod$chmfp>gnc&3%($V7k>j|JOyxqyDx$LhQK*ad;~4DDo2lH$)eVp|
zYq0x1_BMN!<yuYja?hM}dp-ruzZVCUx<T%RLm-2OC0!oe1m~<n+pSk6r(y&*TQ*GV
z+H1l}2f}gFV(C4jSut)j+jzC}sF}$;Cf4HhDgM-NKs>l-{vd$08nq(04P2vd$`S5F
z8OCyPZ1!Sa>Z+yHWx}E$DVJ@C5L|q`R+(_PW@_<+23>q0+gu5mZyMCAxA@y}T(YO=
zRPOqUu<+6Q&Sx}NJs!@^BYb7)I2rE;W`$l!*~!x36Bz55XRoH`3bS2#mALHa(JCoc
zvZZ(1vK22vY;P|4!oj~7tk({!py!X0EcEul6)w96&x3CGe@%N&99mP-2uj~D?Bo`6
z3AeA-<qm}!L>oO3XG*$+#BPy%e!4fB0ozb>!boUV8T3%7Aq%gAbu8iGJ|=tMC64mn
z|CRs8!k|)bz$8&P4ilNXR@|LSDSgX_`u!B_F3~H-*h9z)cB$+WG^U7@XgoH1UM6Aw
z#VpEx$wahl!N6VVsdmGGDcJBA#pg0^c21w6IwkTj<V~o#i4SAQz#Z*7YSVFu7b`>>
z`Xqfxu!#X5bk&yj%3jmLsa74eTMvSb0B_GS-*vO}ibcj?u_mXz4)uugX4#Qz6t6Q-
z+*gJr#s>|FPzBU?I@Z>^?{xivknW&tri;=p)hlKO_VaK$R1tgDJY1Wlvx@HF^*nZD
zEd8$v(sgYUW1j=-Ns_yM{Lcxn;C^o9zpzd+wj^2Ao6fVy&FHyWNX6GDe{MjHF1wg3
zZYfYzQK?OJFx&pDRWWFc9l!SpdHl5v^PW}uPmxURP6D>oUt=Su2ArL6MXVIgbgE3`
z%TBtec;TaF(6OpeE|j$f+J&naiyR6KcHCf8zInAa7*<~?MZcPs0p_rEEPOb}+!+kl
zV&r&q^;(j{353MUH!oG&K*M^AM&4{Sh9OZyB!3Os*EUO8;QbJvcr!`Y_BO}&vBg$#
z3dAhjv+3w3RbBQaM~jjxr)Z|@7^UlxAd^1!Xf~C<o)|Q>xGzy91va=}N4P7iQggT2
z&g^eAn5y^C(bbKwn0u*Fg5B;JW56t`L}oH)ThOVDH_zq_v+|SkwBb~oBnqjgSE%VX
zo+GjXm00s!fV;4Uh-yfD@We6S1nXO#7GyRDDGN{8+{N@~>hz<C+<FcR(U{hw`flcf
z(*?f0!h-H_9zpMr35l+}*>wMvnM?~^K!^;Ipx43sQ8@CvisB+fa+NvaF-hWDO|!O!
zVQg~iwz_R`iPv~akZWEAkcHD)XwU?tOFx%Exir*oY@1gATi<#$?^7DL_EBqH{pwRj
zR{AgaE+-Yu;BZfrj`aKUVZvpBHG58jUSo|e3USmXJRG=weh}YsOX!Ua_JW9?jNxkd
z0u2tNic^aHP0i45{n}{Y^@~4OvF=rYBKqeHt$L>YwZ`a^D6*G|ciFOwv1~msAHI<)
zPb~pVP7SNdQBaIQM#Y6z|AmTu#A62k8{zk>bvXHnIgkrt*J@VDv%N1pZ+9ox$Gw4}
z`g<c`<{e=gg>dg_!znRT>c4*$k1>Jot~cAo)^??G-%aU3e<ajkD*Q<RMeypL@NwSf
z(Mr$<>;d~hmq#y2Hj>#Ml?=V0iDI#XUt39Exs9Y3JS*}z=|Ue~VGsDntHcNd+IQ8-
zl^8U2N{x0!B4mqYX_HeTRjgCFCGf5$QTKie9$X$!Zu_mNCRl>DGjugaS=LZ~Pm*3z
zABZWV%&C==Q9p;pATE9QqQ<pEMOim;?qam}dc9kCAMNLf$JmnbRKLpX8t=3Jf)^rL
z^SpXvi%Dc(*3LdxseovoE6}$CWnChsf1<-&%Q_1i-DH4IcXHFwwdI!8ttCiioC`)x
z56DzqLLoEd{&4u|lC_li3oRpc92QooepbZWJK;|vNZ1y69^Sqs6)k&Sf6yI#YdldJ
zTlGbVyrI*{jY|s;RqxNwgIblvpfXnS32clHg&@qs()$+!JNn1>F0B;X+ap(sr;3iG
z;w>ia*#|y5lutvY2j%7QL%b*sVyV-k_K<ah2BxycM}(HJn$L-se?3J=yhA)q=6l?*
z#Rs^_+_RD3Jg-M9*5-XKqECMx^F=2Mx#DAXz+iCa=j2}n{67kR!)w3n40k;mn)3dZ
z7$dZKFuQ+U&2~q_|Kp3Y2~IFx|McnYd%-A?#}kQ0Hzx;551D^$sFgpxQb-TM7x8xU
z#FvRF*s8?N307jgt7+f7ed6shZmd*4mtzPjhi#%*yp){l$h<Fy_Q!96d5-R8artX!
zp_dvJ%Pw~jKI;vNrDfu!)*^1LKIshAm3u5ui?zz}*)D_zG-^mp5jI?ZH7g73wsFCr
zFKYO#y)*7<7n5QCywwu}FATfbQT3q{6M|fvPF){@_)5;kukqbmN%Hs*)=yqbPE|-l
zuRS@$iftP|jjt&u?bj!MrLP1HsttvD%SRZYvZ(ol3->Nb8<wys6e1$}rHIdluDvWi
zz;V^la!yR-MaX_~)?wVO`pe=cH(BmVlgs&=NmE}!HENpH0ogE2#&<>}Q3Ouj6EE~#
zYqPF*d0Tdark$YxU|TsEYX{sO=XjUytPMm9xSE?VkuiTnQQ>vk`tU&!#E+=>e^4K_
z95d<PuZ7E*uGX-(hflX|g}Yv`jjlDx_YZfX|BI|PVB&$ilej}jtES~XrTSZqj3OGk
z)ZXqtEW7b!P}geLGKsCsK9~%eR4n`NX3R=?)gvMw2I_>bKnY2&@ixH0ZtMG|gb4Be
z*K;X0Qo$fQ(og>3Z|hGQ6Jgyh34F#1>yO8V@#-vura%aYu07102&j#bq0(*RpB6vs
z0Qv>uU)@Ahh@Y1$AqZkj6RGe^5GSn>BJmU&WHq0w{!somcp${C@E~LKJoiFG)THaq
zM-0)j5yOg4+19lO$QYw(G)W5{gXcd-#diw+92K{H!O$uT!I{}bgIiPQNDX_tCxw<j
zAj)(q&B#6`{MV(=%I))zK}MUISK<|2B~Eeu#7nBG9U8e|pXe`AL`LLh?eb`t)DZ4B
z^T(JAN_;36cbEa4JIcF;D~#1tD42s}6rLxX6yDcwS>7E@B?-CMyr^(H#N+eWaxb}?
z!2Q=!+XmLkWGN7d{6^aKCf9HL3vg`Ws%Ginh$oZBn;#wiC<wJnrYCkFZnnytf6*Qq
zJ4I9V)C%WRLT=y8s<vHzzhHijiU`kz{{bJ&lszb1n~AI4lf$rn-MW4{M5Pl$_r1Hy
zhO}QG4PP6OB?S%K(VoqUg54`UjJ8wdSjtDQcYV5@%T_(>nZ^WcPr_wUr$_K>%iWQ8
zUtB$Jntr}w1eJ0sMPlVXdK_wcp$ms+QlKN2HJ3rPp*51t>}UCXTb0Y79wWe2eNm5%
zO!c|uWO`Fp(Vg86^*-R8bp*=q-X-PoUb?#P<l@;C@0jJn4=~3OT0HN{xZ9VLe$PoC
z&x#|=|90S`hA1Eh0^K^CNzpc|`D|?=EY^gUyDliMz08@t3%c!_8UKToZ={eAKbL5S
zkk8a=@GzEe)~hh?$4FAuzR5a38Hx8>Vpse!R3y5)5kHU}y~Zk`qpwa~{ky2O{zcm=
z;*gCL;pCHZJjbER`(5=!s~5}1Cv&CV6??#vl)tWt$<;~@JA>E^HHs|emu#AV)&HJB
zKiew=ESeYrI=AHW9(jYWen3QxBCrt(kKlpt%MZ2bxAZ|aM$dYDe0Kw%R8iVoBDnaz
z2JAPsTxlal)fbcM`B`w~j<bG}(jfI_Y-XmW&Nlx&kNK++A4gBCf?ku|m08gUZnLz*
z3O>bf8DoQ8Zfjkeuy>Mo*>dm4!}w_^cbzbD4ItR6DE~<3NVqO_;T>J?_&8w{#iC8o
z$A2T9nB5}()>XPwEr-CFO|Kl^0=1_}sM%IQfqxcUX~S5Y-5$XM7DD;RD|Xhw_xnG~
z9pdUESK3!gT!=;7{=7M*>nfEbyqzmai?C|(;+Zv77@0-P3Cmih!3@`?{O0`r4?+1K
zIaF$Jyio|(B2W5(4bAXVMljyaq*otl4N{4l)K#vf|2(!O;(GRpcfEme_!$L{hD|JC
zy4t#;1uVP%u;XaP;_~Xr)cX&^p*%=Zo7*<*ErtNND$LB}Q*`nBSd9h*2(eYCbI$mR
zNghdwuNG9*1u4Le{*4N(&x9Urm;qe9CsT0`ICjOXKmIWi(ss6IRC#bamp`%e|96jI
z6yzPX8s3b;bQ;Z~WY<V=909owaC-Ul{<(FX21RHtax`#XX7<6?f;f|sJ%!LeTYnzg
zdeY%g5mvyevrrLnJZpd1x<zA@QrVOfr?iN2YXd5t?*n;f--X}d1>?;UMwx-i=0#Dd
zC7nuZ0-YAse+_1l5vgA#_6)sTYGbE|#BeYhs+kn^c$E=U1uhB?wVoQI52M6dig&H6
zGONvq>$ljP(o**^3RrHEmS{72lzIyM7XIm7N<NpObDGP~Q17Lpvzy$*<T%J}F|lpn
z5%Twor(d;?)oR1r6q(Z6WF|ZG_r>1Sa<q^bcg9+(jTndXt*)Maj9~w|%fV>ce-)uN
zlub?)`x6;$IciSux__2;#{`?*^y<B&KuqztKUF!gmDC4X*8_hzYp08}NU2od_>mn>
z1dq{e4C<z!A8t6Av&DY*DD0D4a_&wLt|Efm5tyU|aW>gAU)dM8_}xT+ym7?`ygAss
z(vQp5Wa?jR_+&n`pXNRVjPjH)CvN6#UFQ+!C{{_e&AeE(aH<P_eHvoGn}XedSiIWP
z%t|IxF^(OT_}Lhd7^+q;?LFb5CX9M?)2G#>^U#B9wzJ<w_E8$9ZE|#Lft(10>2yke
zA6|LF3r%rmQubXBHZ(C=PZ(Vfuwf0enFZ)h`eTn{yktfFVA^Vb$*7@8#K6CGv#nX#
z#4)WJ{lCyE-WZ8HccuJg^%NTIea{8NgHv(5Q-zro(>u6xL^8EUOa-2*d$2*K(xzdl
z%Q~Dfivn>LWGl><Jmvhy<?ggcZuLqd@J&ud*-p)sz+ct#Q2O-;*+OLJtW+885f_Kn
zn!pG=1PFHZv8jDyOH0(>#aDJxVHaK%#CW@RvDD%*sq1!lRY<MgQki)3QWLWpQ`vnr
zVza4->}%eAyqY)lZRSw^f;kO&Q8@Ji>Yp;#qYWIJ0zSHbzfOkVvPv3Lhq6kR;aLKk
zeZ9+NX3PIN&C{u8l;~gst9-@L#W6_)1ju!vt>cZYFHY{yKaL%rkM@e?yxig-{`ma;
z9W9K@%vCm}{6^AG%J|jw$Ho3^q**Wtp{B~E@Jh?5%$c+qC429W3~q>rSBq)EuaH#i
z#moe>Ou_<up&720K2opF57nyzjy#rm*=^&B6nh%WKgS~s^7mxN+YvZ&&u=-A15vFx
z+3$LXY!5sklBlDS&J@OGqR^5iksfB^lq=4nrv5}QcMBG8iHN@Ti;T!Ii>l~zaDcOJ
z3?&*WM$4gl*(BqAwoMFWWR;0n`CDBA+A>a-*ZYu1E^w)A$vlNbgkz$JiAaQUji=VR
zjnPl_wYlPDXMg)`hSYU>p`;3*dYRdu<HIBNo>HhJ%HP@rL{YyBwJjNT(ef1nD+PDU
z*Fn)<ukAjZAx1gZpInbP+|OMGpRPuFR0(ac`aJ{t4W$lDOk@PaqO*g<*M03qTPT6u
zS<Oe`D#3LAKiu?f<QGAvE|o2e+dn<^i#+0O2_w)`8Wvx9IA-n1&rc{<*2=~Y=EK+-
zG6h8<1T=cG86?O?>;HV$FqK55&U4-}^+j(}*PYetYu@h)6<x4gpxM+bY$U?xn#3I0
z)xFe)+s>KTt3frakM$u$aTuKQ>$~i(?0~1SFK?{q6;Y|Ta}|Sgm~zN{Dx)B{fi4=&
zs<bhFR)fmSnrnHCA^2xRMP1pvbXU6-zZ^fV@KIQ4mrTV&X`Hd$m`2p?(#%DF0}I_`
zP&Y91P{*{_2brZZ6_g>JIkf+^%71Xv-)v}A^Cr($xblq8v~Krw$jIhd$rmZE_G`O2
zHq~8f#zdv=399)5A>&OqbSioO`hquvswvyhDSkeP4Dskki{DlHgBP$MVwaQZYGr|^
z)##L@^(t_BwT-P6*=u@s`(NW6bBaGEWxe@wKeC32?Omp(S*baPhAs}7VVfHv+FQx#
z?Ay{F{8!6AfzNGKk6Cqlcx9(^(?@r>|6Vt?;5SXFbsM<27nw_UvI|f9S2;NA=+#oa
zY$!`=DSsnf3*X$V)uJ+B{cL|=NTlzUt=$^puwf8N`yA-;OqOf{ToPba<8b4Z$|qxV
z`4e`1n^kS2xh<M1DL>{wCO^UaQZzAWs{NG><~jPQ@7tg3p4u=CG*krmpkgk<Ts3jz
zL+XSaY=Z=qNVgv)x7cAAOr4?!lw7|{*q93L3DA{()r$Ycxy`Zc*sXaD;BH|AR75(0
zBr1BC3RUGmg%xB|NI+aHh<UU^I0{=_ypafwIv4|G<t)*J7$a4&(C+x+q-!$w&?T&P
z#B-|OW8_{K`enChr>r1x1QU9^@$s}gH`AmNcq^c%y#0i7mMZ=uwVE}=Uf@avJE{m`
zkT9E#V#+>00(GF8)es?m#n0KCIGSJluc{Pla7YpkQM^@Qb*)|>XM?*QWo-VKr`<7B
zGtL#^Y1i8MP&wip2J`b18|QbI{c{i2T`lk|TC4}o$|NVe;QCxeFWNX-l@+1CKc2WL
z*W;Y_gHPL76)N`XkMAB+dMMa5h6%23em)Jkzi_Z+S|$yaHc=c+j#We(b5bwZL~&gk
zS|RS1-lXLiM=-D=^;EI5M8TL}bBrbC`C$I_PmWdlQmO@NB8T+GAwvgDMHlM+6RjeV
z|EcGZ3W81gY}O&VEzJ@A6avBC?fN!Vb&K5v!fsf+4enffBvt`zpw<urpB01klH^PU
z<c*|iz5Dx{tJQ*0PoTsN;yR-KCuFhm$0U5CQG+eAv$MWNWu{W0wHcXZ{+$A4=HYCR
zKY~@_!0;#0j3Tm4TSsZySL>b>`@pFBfa29DrXgFahQs2v;veiY%kM5}!eIfkif>})
zy4y#(Lkk@aN56nb0ik(}s@8|2KZ60$$Trn0@mV|$NyYD=Vi7|0ydJ_ahbA!ew+cBz
zV#QE#tIC5>n-TPIe@6dv7LG#S$D6*k*4O(JsP1?sFn$&P`ZA?fBQ!Oe>`++Z@)ac7
zPc%jKYGF0sgC;h?E0%KNgY10y-IVCp)#UdNpC6*GVc6m!NDY|O8!>0s>jhQyywP_@
z9u)HO0`{2pN-<^<9cZ@Y?^e+b_(H9xldoDzHV7LVzTt^DY+*S(EksIhwjW;8YLSnu
z`m~;@vtC6!tJvQ^vDD3+JtLLf_M_Q!)a7sy7g?V6P29L9A?n@{jpDD7xgTn&Di4zt
z=NQ%PzugkB?gebrXmNF58aA|pWxwEdK;P-?1biDQlTColPl4y`tn2^OFWcJx1{fZc
zfI!q|cMxv7rKFKltLxSt6LZRiXbJYxqx$#9wHZ+H@-nc&c8U6yq>j=q*1u<Lije7K
z@A8gd3Y{TV$aiC21)r9R7O2W?xllhgy^St%WQP$;!o)YXto*%Z#OaPaR^?CsA^-^b
zDP5CC*3c(0X@2`vtHd&7b6Dl`M()sPQXAaRxxq%yW}T2X#Yam>3_iXNwxbLQ2B&VT
zE7_>fH?qYexDmA52MpkursK#q2-a<#2ZnyRkrfp5$#=NPz&MR$_6hZIKICzQw$B)k
zK08@XG$+muP_!qGoxm9qi<y^Tn-l)iR$s}<#K@5Mx5!_pJe-<#@Ps|`H+|wrCb(^5
z^JadH;t|}}c(9;Gnp2nWM+Q^~*tD<aqzf;$EJ3USpp1jydJ)2yTE$k~^HPmEV&-bg
z+3SSLTzuWyIcQrdis2I`0D3>Tny%UZY>6W6hA)Q^t<n*K4kC$jysD%)WHWF<kobdG
z%N%^Eyj~QeS7t(P?QjwiDleHL?mP79Ut`1hl|g+wK7c=uG3!~3`4~uIUzeUlqON#y
z_<lp$*e<K)gMsKo{aE?zGvLJY>F@KwEOV#_BZtKVdWf{w#mhW7=xQ@vk=OjHo7DFD
z0uDF)PsIMDqtmz-(b(c}&v*BN59Q!U0~8W5uLN1pZgpJc<mXJ^Ny+^|-fDTolySWL
zSGD3_>3wtNJ$2e%if$mk$&q{7XAlm3IvSrpNqes!G<XEt80j&XYLt6{i||r}Ew!x<
z3Ex|9HKKwCtsLofP-Bivd=_TAPezLPB(+g$9skFr`n0Y09e62p;4gR*y0|Q>i{|r*
zlqT7Vchnp1u~K_;3(S3?g61_j(sDa~G6{f--Y|4znHR4R=-KSVMIM-#zsXhp8%}-i
zzM`mctp1Rc(t!)wX~xSzQ?|*5ATw%Y$%LcP_ys1jW&GBm$vTXLAjbOU;$mL|TOkxa
zl|LGyDu#Wy|MNZ<GXCwS-SF|8-5|Fz9L{Z#78)Hc9@P)tJ%boRS8n`CHP{ys0$A6q
zcO}x>?C3p>y229=qKYrEg!vHvh_facG!+0n&;WS_;9goqlfQ4W@B3gF%rE$CsOwiO
zEl@=4_i|m&&*D{<01MRawMXmvH<sa#m6vhC0YklS7ZD>qW$7eKn2j}0IHXea{_J*6
zE{qu$Z{ufU&NYJ=x%AD9l3st|#8=f^PWv#3kIs(+EE|I5pCtFfDAV$Z3(x_&TBjr$
z^hFed2(?g_(&fxHumF9v{Y^3Zy$5iWg9GzzP_~<`cLqg66&^gyZa%bsRNIAWjVFpj
z*C+_R-r3nYUrt|ik~VxlL_FMYUiWA%mbiF$PeI#6#YQ0jxk;+zs@0q>0P{qvfcsqL
zgrg1>^QG3$nope<zc?7@X>WQ`${M#~(gBoB$~mnRb(t(_54El(-5i_4!o-`sNV{(h
zAg~?5_G3{?25QJBOCUBxNsR_)NGvPD3Lg6maiYOL{udux4YfJFKdG@0@jd20-5w+;
zes^KJwmkx+Ty|KCPl@l0@Q^Y8=*|<aW{+3szo)W-r!G2gQQFvr;XRdrGVV8PO6~$D
zpx(dJ2(a$5dN4oL%I2c^YRosh5wG3J)k_B^hC(5{C-bKj`?IB{xCZBs$C@9>2=he(
z^nt@`(o0Dee)m<AgY7}o1}B_pB^0yN0}WBG)*_TOA&csMLDVLD4_yT1;j;<GvA*3T
zP81TIN(KGIgtPV<yfw!6*FKY|>_f*zCgWDQl&5mWiHy{Q*;=q7N8>!HdL$sN`R;Xe
zFTyte>Q{hM@<wTG|8MQ0ax&UqWyFX7dI5$@ZeJM4*yL6Z;^$BmhXXg%mK@L{lvEL|
z7RqRw#Yi?i&+=1_r?WZhO5uaL8D`)`NW^;i$Q$p~g}c{_-OA4IPd-~b!jZ$ZyB|&-
zevA5*!2U@)Z`W{>kqr}0vp@eV$G7k$lo!KX+VA}9rxpb+g!DQwT{vuJV$8<3^_WEn
z-QFS=Tw~?)h%6jo)*nJhmFyFi14Mn&4wI(?IjY8O=K&APdx$lE!XN}7=Ji=Z&ea-X
zY5;fgbM`bHF}=e|s^mzQs7egFbmIQR{{Fg9xP()Td<jNm{)%Tl1TLrkmfdFyyss#J
z_WG<|u_c0nx|qlXikhwy(@|1#V5jck)=D);C~-AeDRM%MZNriCe>{D4RFvQMHAoB6
z3?SWIk|Hf2(kR{CLr8bGlt@TQDBUo0cY{dB&|O0}?}NY3_x*#lW-*Il?sL!Gr}jP<
zLdPUs;~^X<trLDtg9DXQ{*d=4@(giSC!F&5!&K{WB4_DoB3Q$;Z8v|9(Pk*Vs@W~m
z<;L(Xb{u7I{^U+~%51LSaQJM{=C4xu{8?%fn?Tjyo_zz47aWZi#5(T~?l%diPhfxy
zVSI^Qn0903eKycxA~l>2bpm{@lJoGdB^tJi&}XNsfGyB`*iU$J8p0ACyW74B<SWQe
zMi+7p4Q-3Y$NdLZkW?vF<qC~zIKwh?qw*vFpX_%EmG$0?Ur(eEA@$Um&KlX<d8OIm
zxm>-7UO&ukE$j=`W5c1c7mYKX6yG_n#7%MLGaG+jmK{FeX<hp$AEH&H92(Ot{P=kH
z95ySxaTHk4>znGp=0`^V$n~Bn&p*hinm|X@Wx*Id<>HqlPN=4sG#`BBQWDYo0RkbI
z7;SIAMelpA9!p~=A@;RT?cRAXUIUhz_O2+S_(v7)7tkAtz}YZu8P3=0B!LKH7G~O%
zJmZg?-YfY?twnq1lP@}g8TMo%**jI5m=+mrIR}%0F;6E$Y1A*3EOQTFzM>KxGL|+O
z_Lt~5D*@<3*Si$nZ}qQE&`9-;jCV-&>sx~io|Y_NLv6Pni<%2dGa|TOG=V$kfPB|~
zfK#htTzniUnT!Eg+hu}0seXgI)mo|8=!LrD@#002r_?2aju=i}RF+1au6@uHQ{F8{
zZR2|$9Co7{<h7SDaQIN#T4WVBJ7ZL#dJW@Vfe2w>5>Rb4CUH)+sfO*4-sT{%w2`H|
z>08iLF%|#`iS)|1CyrcSR*NQqB=A_bE3l<?q73iS1eWwZ(8Gk8aT#R2vDC79l<E+Z
zZY+qhg20kRjb|csxB2@qeTklntMX}|uD1SyND3>1_uBq$FhCkvdYK<J`O2!zo8nf8
zSYG+2?(p!c6Vi+@6V4{d%f&q48t?oe<Xv|eOR9>o#DK1NNL`FDQy6F@`W<kY?RoTw
z{ywl!O@>hIthH7MKs&}BGQwcf{OP?Dn-h2EKTs7jQu?6R#aJs#P*1;_LmH|)vih8V
z=825$?R`et>UlFDy~%Nvd~$vSOY)Ke&>+sy`FE<rq&-r6kUysNt(B{CH8Wnhc|dbn
zXvg527GK^dPED=LkGLJ$l|vfh3SDKC*QI*|VT$=d4a<Q>;ID?~pn1*(aiT>mu-9XV
zTnfqJEg$Ce&0Ai90C_=uFUN6D6d%@M4r&Z!CFoK3tGfMK8>Mf}6`lz1$WY|-jXt7e
zNjaF2xqsZ2@nF+T5SVd=Oe`QQiO<H8yj$oGjEFpOGVm{rS=m`zD|MsX>C<+@4`uPi
ziZx%*96VnLRf5j88@8r#P?S0DaDM|zBVqozbC`m9z$I8_7@<8)RS_2qrl*N)gNtbD
zkb*DGiL}F0#P^NSY+{jF%Me`Oq42#BE3EIl9<4GBr(KMq`q2o>TobNTH!@ty?0KDw
z?2@$!`GsoYFW;S#quY6)<0R6n(M;@N23mUILs60piqzg<=$tv>-O$cjOWn|GKhW6I
zm&@hr6nncvh>NvVdGj=C9Xg!8FzwVMXw<qNb}^hxik^J&-W`hhag!l`Li5z~zW%B6
z&ErJdH7mQ`Ql=vo+FRWd7!b5$3bgs0(Ov&e99w&AAgSF9g<Gz>HTE_N1Ij}{z%5EF
z*pXkSXfk8A^YKh;bm$@1y{PSv@mN1AmlTrqr^ai;jgKz6vSK(97|k!HbsW{Qgd9Vz
zcOCU0{_P-w9sUjPrnS?lJ-pm+PEo?7yNZy9rHLDY%>)&nc_l*82Pxg9RvwiW1<hg5
zNqd8vJ0Hp#G5i};MW_$|v@8E*^8>dWL+(DK=h+u9N~{QMHnZ*(99EVG_Ll?HPxj-H
z0<4(+7W|jXm!F-S9N?;g`z5-KvT58;meK2{kB>d>uvkamcT*ua00mc%h=r6U53($e
zOX9QZ)lXRN#91>yD8%{9{YWoaZCElppHR{HAkP2^mx5R50X=qmQYNF)4?PGPhEv}U
zoLNf<3osY(AN>H)AR0$3l7E(81=HZ5abk!|Xi?YEfWVed(J`=KykEyPOYNohRBN%6
zwP5|%wiJn0Xa?CrZa|67FsB<W@Jlg)Pe#W(=93TlwR8f7x1cEY&V3Yfy%9v>N22-~
z-V+7O>X}7(kLw<m>z=1uHTRRu+d~N{|EKfA?dP+o^r)28SxfScdyk4L4D0{=a5{rq
z%(_LU7fR-Gty&ozrvtI?_Ldy1P3Xzf_MP>~^YMG=7C#B7<>)|v_!SXz7fr&^v$=HZ
zkKT{~P<o78Sa{8Oqa>H}inUY^`>47#X@BmYf*B`!lt`+F9pc#?Z^qU653A5mr05*A
zZ5UM|AjA!^+Tb=?{Zdo<1q=7e6J=9?bk(voNgbs%n;Fp+G5VXS3dq7GytjVEqB|Am
zvLOXkYMgs4@=<p@sQV;IdaAlv>tOBI%lfCW+I(fm1?~pD`IK-R{WjNoOkK2%$W7My
zE60ffYQWSi`-xr`&$U&@b=xk8I;kab1P$ILL$9dBPmv^M{Z-o9DQ}>Iqe=|XqsnE<
zZee5RcESqLwTB`Z-mN8Q_~Om|h`pafNq-K|tb7M`Mm~05UjmZVxUN?glfd@-b0eO_
zN26a)bKLWK_x#~@pSV{m!2~&gEBw7Y`6t}Syq(X4M4DV~K@xv~<)F^Vm7OP_^kkR_
zOzPNp59ik%XU?6oS|vA9=3R%B2vx>TBC_bYBbA8RO)*#?6Lhr~+rJl7-oN<#2VQ|&
z8GQ$?xUxqAPqkg^z|e)HI{`(Ew%)P@OHhUkDPQLx_^pSEH{XkGa1EBF*M;xNVSLAG
znJwNDnmP->Cj3&rYaD*oq9#=5g{ZTm*j6P~QTtx?y|EekcbC{u-K`@0H`)V~x*hG%
zd5OV9%zM6j0>%>0TH(g;lIquQb8T(*zfD*pwNeD^JyMjd;M`=_a8xQt?;x0XeT6`<
zVRii{UZAqsc<o&(?FQ;6>(a*+`{L~TxH})!4~Cxy?K=i3TyI`CWoy);*2M-G6%TUz
zINg<6SJsSo%y{?gM#Or}=!~w-EMJ}1#L5G`3}s74v9}X*oyCM%U0vwOm4}Vjf2WDP
zjn8=a!kq4wcqRHpDn-(}P^QVdfuF_Wvgc4H4?e@TN~Zst!`tzot^@UIxEGEgvUNQK
z7sXn%-2^!dGn1R(iEyTI##_VY?CI|+&^>6nEy8D8N=NOq!(zzPO=`3$i_lZG_d8Cu
zD$AM6GK_y__=bxN!?CO>Qtp9fR?ObI5=rufc(;3{)J3U)2tJagag-)Lj$K>!@4q9S
z*$3jvH2z;~a6iij1jBXh^ETI5qJNW-G>lS{6&E)~$B~o4j{LY+hmF<)&)JPgFqK5x
zN<;}FV>H<Cxmu`#pu@mrx5_k)C%2_Os)^x4gb(38jDv(Xya?SMtCnT=TY7TyDBAMh
zMvH-Kr=n3S>c@Xv*WWZ?Xweg46x2}Wy<)5p@Ymg0?)DmeBwwz-cW%f(o34n0Hs5@@
z|Fc=%yXWAW^*_o2ai57!{>g2R1xex(xhqU{gwJSWl!}gCdG}j?0$1Or2LQ|6NJAgp
zxP877b>RthZ{n@JL>mfw;JL?%l>Y55%yKz&fQU@<0^qLNkVPCSWZWgCYRpL2n|d^X
zk7N6DET4%hKSJe6M=#YK8~hM$x*C{zK&Xf~7sgS_?kiDjhP4L@ktlD_B|9+?Uqlq>
za~MS61fsc!*POopK~W;}Q)8z95iPp_F*Ka=oZ_#FN1Jd*AV{(OOrd#C>J1yAt3dfL
z2Rdx%vbH0#^2^W9Epcro#R42XxOqa4ceOcD<NA)+<z&Lfk>wFN6V|`J4`|e$^w2)O
z)$pjBC;~P4gfVc~t;ro_*fxy=uM7n?h`z@``Y)RhOzqz;&vlA6oE*cpXq1376i&1M
z_WE)?t5+%g<~^&K_hj_5y#>cDWIS#64mlKxiiEGFuhiMKB90xD4F3cs{l4T1;Drh=
zS%ZKuR=zP+iabn`@n=B{S2w}h)esAZQ7VH-fhvAu)?hs~qTs_zc;o9{P{9FPQaLL{
z?TjlcC!-_?eAQ9cB#__QZwxv_u!=|O!3HqIP6M$WU@@x;>P)1twzl=|Dz6tB-mxE7
z>$y#YrLM=dwpkmQrBlST<-lY)%|G8PYjVGyjF_q86eYSUsI2LR+&vakboH2gwDGoz
zwr2})Ijo!}(*IiHXyOB#^wGJm^iJSvWjims4fSt4-G#N$#VOo$*9~1p3qRJJ9dI46
z&Mv-QnSnkHOR{{nJ;s39KXq|0@&(6%vd7opV5vP(*CA)eUB#d*?lUAzsKdF+{lOfx
z3rK*8gq{%{08PHF>V^ChxnyXt+{5Mu&*^kU5Eghb%Aoa@VAff;;zW^wIPUyRwZi?+
z6zkg0njaRw^Iy~m5|M4)`25**<b+gJj)vAZr=8A0_)y7^0v6hFr)oG(PgKPB7{ixA
zFxqj}5PC6BTuVrC>hu4bbZo2+SfAT4j#?AZQP5w=K{N1X>X`j<PUoVVSqd>jACw(w
zsgs7&@lo1HgWTe+MZgNEsKfhOLx0kie5l>bx4JV<GY*g)ysQ_=Fh>syf<1RJJ&xaY
z)lGoZ!}xl9YeQCe*S#wT!!8kbjqe6T%dJRWtk%<>(h4aqyy$+g4(b?ReNWLASv%sp
zZbJUB#w>ER;rUGQ=EQXqb04@@yYD(X?(=EcuiXSy!7taI5{<gfz;efY5rD#)#ozbO
zmIja~XwUUf+FEY0$)Rrp>RA17uFlmRO$1{1gFJM1N{x09DHepnM77%pXHZCIC@}8p
zHi~!>QCQ+;Y<Z)c+pAV(2|pvUCfGMdkQLM%%G{a#T|UP<OR_J4JJ<g_zl&7kvye{^
z%ac1tE1mY$w%p@$%?P9~f;G?Q?wNO_vuWyvFxS2s(qa6-M;%@lG_K>b^X;T9!d=Jm
zt8Y@nraIOm&?6#Kw!6Z)GXIOyvJ_^(aoPZ;X<O{29u70Ii7y9N{b7BA`(|H@lSg2N
z*iH_n!c9iEC4|Ra$W_%T!{7CITYfyHP6nH1Y<(!wA5(&pH4rE-JD;XhGaDt|6sEYI
zQBaFrMTc=0H=m#}R893eE!S$z>3Sf<i*^c)jrMaKzL^<{>lq59-F4+QC7s3n!;G&@
z3J0X~Z62p%y^*Xh5i!ekJdvTU2RQfT8V1lW$N!!yU?ITK<<`lE&6R#Olj##5M3dbH
zdIXHYoq^N}3WCKSZw54~PtH1rKRFnZeg~QCpq&Y{>?K&mn&nq^2GEs-2W2LxJcSzG
zu`p}CNL3DhgWh>2QVjll-az5EbmVi#OO0MuDi0Vw=BlIx9x-Vq1?#UKP$p&jcVk53
zr~=IRPxv^Sp2krs`Vy4z@4v1_uoan{DK)rLru%dBMJj$29Mtb9=EgPLSVL*6Gdm6(
z_(IpN%m+%iN<3Z(<QY@XP(Nn?5q!7$1=qotTxW)cQ6tbPcjm2@$SaB8sw5OIBkNCT
zl<G((nS(y2uk-bj^Ely&rL8z}pp7n>@}qvR$Epk5F=;pT_X*y@atg48ip4^1f7F=0
zkwx7NB;uLEI6Zp4z=|u;+g17=6E13wUBB)8pu5kf=g(wHf;hVHe_DkDI?TXq(N_n-
z)KLh18BM83{y&@P%1%xZ#j{AlS!f~l9Kks8rN$S<WS?|Ghu8RZ=E%ZX=lcvMB%{F6
z2J?i1c^XwIiCE9D+On!?fu7&EZ(V}iP6Sn5r}r!Q{8bc;Lp$h|=RxZK*Okb(WtFIp
zwYWF7b?0wC7GzG@M3r~6W{>CI<f}r>gS7TaE~7#xPx+XOPWa!Lg;E~BODH*1XAHq}
zD4NUUDp(;&RH6-kCgvzhDPx7tJqh-P!8Zx*^wR?Q?<^<l1D?#!^J_ok(yn*%%d#Wb
z>!EJf?H|}poD!V;gKN-2KqzqV6|@U@6m^VEJ1?hf|KS?YgwLAo=yf=q8?$lZjcRN!
z!3idKS5UP7hJJE{($!K<SEOoe$LaGY@g1$W`8VB!IY2f2sv|Yrvgy!0FbDf@4TrNO
zeO1bc3qbM+K0xZL0;eD4^?<VBsOTUSlCO;uM?{m&&PWQhrir?8`muV2AaFGCSwvme
z2|K^rDFu69Cj(4p6X%pmEk3%*ZYA_ysR?(f1@O(FzK7kgyTQG4oA*4$;{`!1wCj9P
zx=U1ymmFj0&NW1)lmF2L_ihBDw2;%Y1`*bl`9mKR&?Wky5xY9UQ8t}K(iq>r25mhi
z#%Rzcp(^cswt{!;T_ymEH=+UgqW3ntEv5(BKaU9DlrJ~CAt4G$-^MTX>XX2@+J%5?
z4{>EKU8PwJ$Zy-ozzPNRYMJI$b>!`QzW}itnXfg|;S9{)X}{+%%|3m?!vdp(e;~r+
z#m!uA=}Rv`dvR8cyYT$kUIVfg=hRz?9aZzvh>S;Ipy-BLhXY>(mM%)S_6jyG4&!t?
z2iMdF4lUF|7>LPqE`ALYsw{{Uc#GFuysy!di9^t9x)N4msq<%y833ceIo=cn=)azy
zljvTi&MhiWCE<vv1+z|`QfG5`KV6H!{~UEwgLE$Hcb}_hE*Fv}*CC*u-(Z0y6ZLtF
zrq%2<CWVsiOW%xMI%jSMUEUn57hjjP-7#D*+xuacd)zplHxifWF7&Q>qkKqis;_K}
zx_X$PyYEHG?AhYesHV&V3k><f&AuL8t<#|BECzA#F26Kg5xjQeH+WNx{qkS?5I73>
zQZ*G1Q>>lMU%o8a&<qBRM)eShXLfs-^bj!VsD^>LdL1I;%s0?0!C>^Zrz8ciNMZ7J
z8Gh2N+?TotKephRN!D)ARuQPf;@S5qn*6GM1rL<=FxtPdQvz+8z!$<d<l*!}04KV`
z_9bJWO5#Ss{4a;DF+wrmcO2~DAvhjB?Un}zxGyl&@*&l@Aw)SC_JN}K*7$g5(|KNR
z*viXg&q8RWd@8RgnPmDyn5M#e@QjIEqY;tR=#sLEjEr2Csd8LrlylI_MKm72Qwmcx
zo($T+#~K)?Q__GER3F})BE}ms^iM-jw)HOF9hYZ`Hin{4grdjTh854aoya|%s*vjJ
zW+$Lc^WE;aAfca;+1kCTXq~gKX#rL={Tz32BA)b-Tp63pcIoE-7+)J$A`pT&RV~H*
zPYO~<muZS3PbJ~JfnTguu)fx>!}_y;IrcQixeY2<UNazsEb~(Sn`@&mp7dX|kMs1W
z8LCj7*eF>S5h;c-NmH&)!dEvlVhe{h;%HJJ;Iw1nemF~HW4}sHgcFaT_&P;wTp5y~
zqtNbEtcCBU@wt0~Q#6Y<7V)*L*a{lw;731$b|Z8QYAz{Q7qM}qV`oH_y?84B07c@N
zB>Gk*bEzUJ4*F+r1FgrxgDKxrFyBxvc0+e((BDW*ZAqM$IL1%2K3K669)e5QF^qSw
zHxgN#5q)uh_F2CDXKo|uCX9?OAfw;BDg_(5w1@^Jp;3v<`MUWZyppSmvJEtp;iEAF
zXfpqfXPjUpqmhIFmD&$M73l=PtcJhjJe$>fK`ilQ%Wop1)jdSOOMMlMLB$bgov`bi
z_@dZqj|-M_samkKnZ?54%%RmX-(IS+PM7M8)czrZBxq3(`0W0S(TPz$MYoygJKdIk
zF4FazD+^xr(_TdtEfaZ`fyTYl^}8BT5gBj*Xe(_!qkWlC!I(mIU7BWuq)Gd+`d;<-
zk1@EigAW4qRlS{s1ji+nrEh!7iP7^j(Iky2b^z>>5YYR}hH6{n)mn)6U1OVaFkw82
zaiOMq@XYp`WTvG7uq!Bl!^dX7h&8mCwb6ZSc*Hrt@VEuSm*=IMwuK|awAZ&A!~96&
zSeZ+8Dvd$^(!y_7?`pJC5kCbvPi)%Leb*vXwo4A}xZ(>B?1EX7bL*&4V{6sez3W87
zH=)iyeC~%)aU1@sj{YobivzW%V}gh=b-(KKG@CONGLI6t{|L_C<2?(4l@9W&+ZIDo
ztB?2ng<(evKW+Jf5x0sgwybSktRMxDB90RrZ(AdAS>-rfgD~IIhq$WAE0sZr02$g7
zJ_T!~i=~bGSEJ;;88(q8B8l}iZH34oHNw49pl?DpT0?=IdCajIJAG`U>bmmget8~2
zlVY@X@n7fU`5RiLmYT<7&PIFW4vi&9W)hz8#M<1dlVBtEMgMe;vsl>t=0exQV0TKu
zW;@YeYA^Mt`2moQC_ng-94-LPnVL~oaRYIC_T^&TA79SGJbD`<0-&J%#b020uD5X6
z)5DKf3V!QSPa7XF&rZiEz48qE=(E4Dcz;R|Ee~-YqgS(FE&+SafFI#G9XXBmI^R;C
zWJ7mKxm{0;Lr9$_kD(Bj<XSK+$Cz!g0B?2AsbnZ$qpW^PjSYKaN(4b_M%iqbXY8$7
zW~<_e#p~lnhG0@mAhQ*_KVz|PN0}inVXIyjygr;tUU_Q1w8pT&mH5xTv2k(Hk^Osh
zf+Yj`n-wF1YSg^EYEwh#egbzFu=XPBPjUI)Og!a2BrxRj{S*r7+uX9}hb*E{dg9ew
zxb|d~L@*f6LzdDlVIp|IQ$z_dnd3X!vwJN8Z&QpRd1WdW?oVwHScQ6YEDgwmjMa*b
zN#pP--0|js8RwdFZ1`k4c;^b;sM9I4xKx(#fkryaBf3bE3)mtgnq!De@PWKr#dX4@
zLpqx_ndqO2ee*KW_YjFU8=CNd{;N)95cU`B-6J=Y{$-fFAJWrGL)|Kg#^}0Dj5p3u
z2H5tM7dEl6J~Ghx|N3;i_5OMZsK>?ZAGo>wXW<*zxzIf<1VFH5szy&B6MY)^!Yq?e
zAoetF@cnlSr0+w`{jJExxHOi!b)~^+#>R`7vfBZFi6y0S#ooT~t7&eOoctIHnOAJt
z)zXzaEZbUDda(<|i)00&5mHG-XFe`OhnBYRiT;m+ca={b&J2GW{J$QJjE;%B)bv{h
zROZ<J;J+oFQiI@a#a5i@#eH_ec;V%&&2<awqhPNS|3$EQx|K0wXO%0^j$~!lFzd?b
zrv{F&o~zIq{5tCk->r6$ocoTc26G;ZCN0v}Yg0}qs%Cb%z#B%hN&zLOY<9g@!u?CI
z)x)Pb6RKn+_nq+O*Ph#=8(|*ewpO0)domqbl0HDPL=Ip8C;L_G3cvva9s8`--YpRT
zTlo(IkPGXw_9O{%*X`P-SclDmhnTHTFD-eaR0cP6!tfLJk_^mg1RQFqzw@CT7AMVT
zPLR0c8i;y&9Ju-b;=dx15%Ya~;Im9c1?J|u$Ia^Bri9T!3g~~j*xj(D1Zz;gi2rgr
z?}4}8F7uUAG1hg^TfFtn52|)lL^Nh7KF)>@E{aAZ#S8dA2HEjW|M*vG2KSA9ztr?U
zSq<_P>#`CBY!}Of$4Ak8H|)e!x#rsz3AScpJ-(8ct$c54|LN;DNac=`3*DxuQ$Qdc
zCzBxdX5vF+2z_F7=t}pg9H3xkEXxq{&Xy!m2qvCq0E?;t4Jg8Y72f~D{^9T5IsB=X
zSEmy3;>y1jzh?)diU+(IE6_wIVugw0W2(DS_RFE6-QQww%mw1eeOLa=4c_?!(zy1u
zviZ}3jc@4~)MnOi+gX|G`!~X39{dj1m61x}?l9_B`20bv18CsH1r6*T2`0UJcPoPG
zw^&ejc5+rcrq=rU9npHLgKh3{C5(?`)zvtzn``-NTSJdb#hVmfzUg)Sj8M)}yXNn}
zBpMEqUmsJ<!DPuqcq9)o52~~?;gNLYXZgK>h1>pbgew?Cdh2+F==&39&7mMfkKdw^
zBDD9P^olQ?VvqdvGLLcx`Mm*ZO3J@}{C~?vWpN-vV+d@|C5tPG$@1kzr%^)6dZ4Ug
z|3oN14L|fzqgw1c;T#EKZvLEL-ri?H#wB0FzZI2Rx<@We>-4YZ%@!qP7Y=)=qZ-A8
z0XzDlEHJ6n^~r+&HNx$BjYCO(&nqS_<h?Tm_yF>u&>N|Y-zlBg{d^$Byl$jIM^5Yr
z)5N9Pi@D;uUmARJvyqzVoW88+W4~_`7r&Er5LF%+tYpo@TA3s#Aiup6hNEmJc3oWe
z9_LK%<74r1oIcKy>2YV1RTF98NnGLq%$EOvE{^yUqAZ)E_>Wj*YJ_!n0wIi-i2<tX
zhTQ%0v`V<}J(4H&>_4^JQl)O$AT8LEs=hx~t#LQ&8Y!L9e8LeXs<D3r+ZTsI>RNK7
z=VDaBQ%FnCX?{>}zl<$c*2M>Ci<cjrUBz+ilxbV-ywu*K-L^&_VIC5)plD^Ml*3p3
z5NdLoFcWfNMTlgI6<2^T8pU0)Z{kY>fjIr14quQ=Y;r=eu-Ki<FB)<}+nI*T|8W7d
z9#uAlsa#UFuRc>G^haeT{5F{C6r3@8fATQbO{k!LTi}&R1K>^L-4gtl?Qifvd4vF<
zdK>#=#2%-&bHD5RJx7-OFO&iNJ(@|NLxf>TZK{->awXqNxTLa5(Nm{kO&LF?03Rk#
zl8YAn<v2uOOj~<S0fujlH0oloU@+2YZ-4&lC3T&G^~b~0A^8*NXh{>fwk1DR)z6hc
zAd)en#0xuX;T5WO!e1!+yzKR%I2i3^Wr)*SbRr_A-FFr^-J4QYuExHXD}jxX-j3MY
zL$r~1M+J)8ktRi?dfVZrL~x369IPu8L4T0zDN7kO$Tc+eFIavg-60M_nst|xL}So=
zR`Ru6#XV|H3r{1y6VGF*kY$R#p!jvbHtOgo!b}#bCQ_46KPGT|@(@=sH_UQae(LPm
zi9$ZV+$aQ2JH+FEJ={3%`h5nm(-ZJgFJH3ttEL~=tt~N#gu0aqg|06t2r$$yiUvO2
z-Ljnc>G=`xg|<8#QU7N<i|Vs$0gZ{|&ctW0AfHGl9MJS=dXsU<u01MFyURzVb{&^D
zinYXWUA_1enp|Y&pjBhlX@*!*OcyMPHFL2mYznZ+dD|Jnp>F$n$b6aGQYtliZwFvM
zq%Yn8h4Q+{d^h#+56A|%t4c<Mxq&jzB@Jv+`1mgpjrel-H@_&Uus{FAb|C88Aj7r@
zXF9!1PxZbEhTo+1vz2?pmMU;H=z;gJd;22(;}OeeXR1&0YBxj2b(ib?SK4BMoh<PV
zG;GWTi0mQm-OTn8j4z*5J*LjW=p<pbyxu`M%uo?kDIfR&#xYQG-q}m;SMeXS6O>y@
z%DT2hD#2gR(5O&w08pg=jSxoh_QL2sI)S3AVVN29EB2QyA=a>77gp9I>SOhK*6cC+
zf6|VAung>0OG1@Ojo4-rxh+#rB^0D+`7P%q?Cha+&)FwEjkWwB&SjAn67pj*gsn8<
zLJ)c=oFrV0qkH`#Xz$Lpo4ytLdFX3htp0@56<R;h%jZ}Mb!QNJds}@X1fkQ*__3!^
zDfw!w(R*FQVA?*$ixmduEF;KJH$+q4|MT;pT3tZSK3*kl>!yp4nUD{dVsPs&TI%ba
z!hGz;T>C{Y!6KNGi&wg)?@4g%IKPagzqoR2Snh_-UBuG3e98}OkfGGvDm{jGd4@%`
zu_B(0^dlTlklg12mD)NozwTytP+n}C&n=Dnl^#W3#OU<!-9P?5;OpvWm{$F>ER;BB
zP_aJU@fV9hY40#+Hj%{5Xf!c6d~)FS*h<W)7?;V@GQVd;;8ii~7&_`XG-N<rMDGWp
z)JH}u83;dh+_uo)`!J39`5uxFKy<)azyWT^NJ)SnJy(za$V>ibJt$bSlW0A<sZZmA
zU-b7+eF1oTQj^7PJe}Vm>sfz^sP^)KnyVV_*B>ok24D`x_qy*e`FhtN1(YpSdRlGu
zluID0f-}Ylp$QXfusyZXg&g{qoNa`>`#`i)fY9N-v~M!$+I{2rLp2MP%1s2wSa`N1
zj_G}GhmY44K4g}t?F<jViMrmtcei|G_5}tpRtlzPX;J(yu)6H_JR2Jt3QBa0V;AuK
zvyz>4j7BIS9zd+D7O>3)|Hsk8ENma4SUv9DAUZb+CQ&N=f@%BSG_z^h)*-h*iCrmm
zTAqIH7%0sS9f2Qi{3G&In8PgTLC(x>lFtH*9j5EB(_y|IbWWmA=W@X~Rpc$a{_K1J
zY5Dy0wwJSSxvg!^I=$Oty@=kzGTS=wYLZ}Je7~_%Mb!Q~pPEXlJtq<bIP?oMh#MCQ
z|9qXWVcF3?&-b}1<-*a;?NzdCY&%ptyB<$%!H05`u)Pq>)eKzAQp$RN?~NEY`#N`4
zBCn`=wu*{l6I`1eGjL{J8-kjb5>;1+&h$k!)k0(HL)T-w(xW<y+MMJ~mA$%$C|zY@
zxIK-s9S%3M%2c6Gh^fBE^6A+gmYJ%4C&fT>=jP*0*w4iV+M2p%J|3o~TAy1|hC?O0
z!obtUyv4w{AV5r($L05M%>YZHQQ~1<NT7Ng9L&9*-Fo{hkI*?H{vT4cO6Ek~KS}4j
z{208RmrARCBTLHF^QGQgKdM+O?|wz$Ugz@8gD}hUWm=PsbRmz$Xa<7%A75N}SN+-c
z$(hX5f@S&=R#NfpOye(|pm9^|^mk6kHbE^0daIcYG@ILd-g{2X-&`snkk)N5Li^wV
zcg1LvUyEBAwEeS2*@4Hxb`s(03A5?rvBL6J&VljU1*x{<ikkzc`kI!e?Lz~B1`NYr
zkYOu$yAu0UkK#^3Ex<q5bj91EG%YFU9&&iDA=?M)kft+0ly7cKn=>)X>9e8+E|le0
z<Z;B=75leq72qY7God7K72T*VR=)(=@#wDu1C(Vx{Z15C$YU~!1ihMFLp1pQY4dk5
z%GyN}E*4@SLOB^7eg8t?tsaMR0RaVV2vV+%S^7vNYEPZI>{FPpipcm<%pq?k?K$s(
z3&Ux|5C>#M^VpMur4@A$(T+Zt6t3O{)v7z*mc*dx^jfkHFnwtKsioZi>bP<5!Zd#>
z8!FX=naQh!6tyXS$5#4%_roOzLzsA(cC5$4EI&|aO6w3sVZ<8b;DE<wu{y=%+qU1s
zaH!ly>YSztl$^j=<s?3K3x`4WZk6X(>F16$U2N~46A3#Yk*NFz#aj2`{R_fVX??wo
zybvNIpnkDm6T|d+?wCzd_l?4WE`KJ*!D(++VWl&V2v6M)xw~AV?U*H5+7h{g=8Yov
zk0hPW97@)wB{r0MSJ&H2`vEdSS=}BN>nn}h*#e^MpM|4vBrvJ*wd15&-CVh1AG`Z9
zc4qC3{tF!XSF@#q;Sg2$Il@!Idn0h1V`A&1hzrFkN3Rfer>#NKnRze19+sKI!`TTu
zbT<=gW{6X&q6AFBUtgXCEx}AB(hhYJIMwvE<!fdR3EMu95wE#hq;=Q>c!}7)J1Uq|
zB?83Q;sUGbxCFuL%bZYhEX^0Da$jxG&{&Pis7PfZ(Dwe&DpuR7nlN(x5fTRruut#u
z=0s_$h<Cx9{$z5t1aMLj)v1HOdOTXC&zOdYvb42WP*Zwe!Ukm=ybZBtsww}$xK;O_
zA^E=DDVc26J_R_N|NkOhKzF4~D3HD}!s>-9fJ*r~#2UK%jk&+z&g|mhQg=iG4#Nyc
z{J-(h1r~b65EGT1b&>O9NzO=-^4M4V2nT!v?bR&!B8RQd{l2*aXsyAd(vtqwExdr>
zuvv5uW?rF<)Ctp*@W%;9J@595W_<s(rmFf<)8mxKrZxmtoT+8<K^RjJUG<x>X+V68
zv`OEI2Tg5}lxbZS1LWE;RgJA?Nnd|3>HhY|(G6oicVE@+cFy4Ot8PL(;dfJ|r{bt@
zQJ)7RZHyWM^}OQ}k>IDjjVvA!b0>i?Xg%x?=pP~Mc_+QP-eZw=kQn&jUKwb1{@SiP
zu>fu)G4Q@bMy{*S?hJ4ArylfQ+sS?St)&u+`PlOpNg;}v1WAStNAvu4-qLDC74Gei
zFw=G+$V8WdTa0zk*5@e!tp%D?#E=DBC??U^A77g_;BFums)5Q;P-E`}z&j2mH3woG
zNL{Ffs|Ke7<A>OuhlL1)^zT>4Dy>2I)l;JcP+3w^%1@ZwdXLqtbUkrpvMfjA-|94`
z5eE9uJ^%jvBdu38w0SYt*ZAjCBK;bN=E__~EHwQRiS^D$^yP|f{O^{{!K}m#nl_EY
zf>Sd=XAd(2wftiWZY8o@Fz;EOfXA(1fPjF;P1l&yGHm^fl=jNclCWD`_daixBI|UZ
zV5I2PK9k(t@1p$vlF<0&hO676GWg?r6+7|%jsOYtKPgZ3zM{)MYwMbWt|W<m)^13C
z&Av)QKs)l^>4@9iH4SuY-No>|_cDm|8fDK(hz`_GF0)&Iy7tRz_wqYLpI!dp-GgYj
zn5OB1cgt)4C9!hn`c-p1m@u5C+55P(RJCn{O(Mrv%|1)&=7mc$c(SzAoNA3T{gdVD
z=f7rQh6_|Tm#em~ue|MAqUY(C-(Ho)YoY3%hEl<)SFsHb7=qZI11~pHK-U0ty4jD&
zr35B~UT+g5>^vfRWM(NbelUJ%|7khdsyksdDWwxc6V5+SJ`_#gT<iWm3XL@&U_%0@
zIz5~rCj9VnaxlV;PWEGR`5#sl@eISC*!A6OI8f0_<xUV0{<f=XG6>NUis*rM_sxT;
z&3*gx_D$Aa58h?%+MHebdR1;xN-y58uhqPx<+r3S9n8<V#Zj$Dfbj8kHTQvGAMebT
zDN#<c0%08Oe-BUV<m5fe^&EvS(N&fKvlIx<VQWLk_n?WQlfP~Kp6zd@5@T{sC?y9W
zW1bYDc5qy3FsNK!5DHS0>_f4?+8=OZYc9Z3{K>9_dnwaWS}3$_Cxw~-N~npTE33HN
zw<|t$)CsMz^4l@+^1E<dF!)BsYW@JydG?k^-hc!tea{Xqyf4A?zHl-wU+v1-=Ad9w
z+TdVn+?Z;I+?Fb*w;AF;_gYlP6(L-G=g%d5@3?XD)g8gFs7+{vxAt&xuO9Ap$Y0?P
z-6k?!t|mGn`=qgB)sR#cOxf8(g671;Cu*JOHxsoP=N~Kyfo1|g^81rgYD5SSJGM6U
z2={~ZqyE1W+1+tPI)0qKgRzL7X{QU>iEcYL1!mo3YpmqAKA8#lI#*ec=y;DSt5T_p
zG_N>O7ReytM9bRIg<B$v(8XII2C${|ZBLb(b4400YybQdMQToPPTDr+x{!zPRDB{&
z%1Xh&IL`ufcWLGnhf1GK7bVCfgRR6FViZHrO@Z)R3NhY6V$D%Tt2dp8qkAaHorauW
z%lJigI@Mz>{f3EnKvt$E)vz2;de&LSC-{q=apBHa!2q+3f9+N1=*q|#cU~O~mQ%>2
zwS7~TVU<}ryiH&J>a%yeU>mOv3m=|Aun$m`#0Qkn(G5HTfgd18cB<2FJF;vSgD%j5
ziT^|5H|T<79d6BM<oDNCt@sv7Y=4vVQjS-=S~ubEcdmqj8<tID$JeC@3hz~Z%&$=5
zc61c@&|trgpmDC?-fJT~_<E|kw2qLYF4lx?%cC<w4RH~WYJantCV;w(sWPrx@-Yyy
zQ0`Y;H3E5W6qSi><;ELpGB=F@`S5HKn3(xZB${!pOd{h6n;nStL{>KzY$E-WE3qE~
zc_@oM{QAh5DHHDcdEG{?Kb@3?x#|8qm8(*7ePpeVXhO=;-WmyI3PLxmSZ=MtKV3#b
zQQU0Esuj(}pf!~f!MW6LUs2SvENl?6&6rqzD4PrjaR-31%j;^9omGvpR&tHoA(J7I
zDqyHPz}e^a#0vY*`KCJEb_=yWy)y{zxlznLT`F4<ed@hC8GradZ~5ycO`G{=ihFPs
z(n~c7S%DQobc7XG-v=18CZixnCZoLxZxpj33tT8s>O%(Ne(7LNhASYTXTBCqQzMHs
zcQI^!d_6lEdd4TA!`3mN|1IMEbWYqe3+Zh*D(UEGX?Bzm&+=cq-B5>T0o2t~>Y+pl
zkJH+sjS!VcIKx;F!5`J9Nt2q&7fY#*W}hUfVBOy7Wnj6OtXz}5zGS9}fXk7`GHaEm
z64h-yu!*2w`Zaa)D4SniR-!7Izo$BN@Z!z?xvsT|(uC{f{8nPW{f)kp$PhWrIQX(x
zpotDRmL;;1S6eXH2=}#x#&Wn#&@F#g|6>IwwBy~fJAdn@&Dc7?Ij{HhA$fYl;#h_H
zoKTlFSF}Kv{!d|_=c4cZgtO>nXO&|Dn3fLI;dQL{(bjBL;fe*!PtV`k*;|jZVjxYE
z6I#Ra=8)22@u_zqte{l~ayVrTLhi~=ocF(7;r!a%lB0FfbV$I<+H}D?4=Bw|Um8q3
z6Ljn}8j03y?O%<ZYcv~0vK%k3{et@xQ!RZ{Ca+>e?Oz-N8+z;LpWy9H-FPHq|2?$X
zr!766uV|SS#WAkgU-WgMY=nkICjE=;qQ-ki1>FzJNi)ae2FkuHx8~Qt5U+!*BCNG3
zEi#05Vvl(HnpZBDQXbU)o5|F~Nn^%dJ_f;%=+lxjO>Z<?d^K@>XJ^b+V=u}OP|k_U
zl=?h{i<!iov&beWcySIeHTq8RlZL|t_pzSxj-?itVWaRVBP?Rlq<2lTq?bUCGq}~}
z(wyiA8_+TIhPnxbAK#4<8d*6y$Fy!Nn>BB3_QBN3g(KSTqO#g+)0*xU<p2=LBTE9k
zbKgby04qu+?HYgUeS21XeXwnBY+}QyBHR_NWLOVls$WH3asBWVx(^2zM#VY%X)|L%
z@@D7YjZ6}5?n}@7C%OJkgxW(<hgCdHUCj@Evq<TN0tbdWZ!p62Fft4UcG?@LOFwTl
z8HEPyw>MyPi4%@~bQyLy_u<@Fhkr{td{tEl!AwcBX=Kd1K+X!g3Qh8DVk)y}E-)TE
ze6QNdRum2%x3~O}6RECI9S#+8PEogvchj)Fv!LUtfDYQeTii473dt(vmtPS7YoTOH
zt@ipE4eUfgRU(S6d?((1Xss#6JU{fp38bxL{iztG&^%8)c;*f{_<jYy?%42VlnC!Z
z3~{HyCc=kGp58Xs7=9;-cqNMy2tnVI5hmtX4sH`gqnIPVMpabm-#^!MUcHluz>;m7
zT6n$Hv&)D?mOU%>Wg?VLvf}V75-8h}R&d(p{T$hx22Jb9V9FX^7gkbA-ky$xcXk=x
z*d<ypLvY+XJn2sZs<ut+ne%Ud<K5j&68^!!S$Ws?NPb^>>|TMdg%5PomoGQ-VOOnB
zo7X@5E>ZdT7}6Y`gBClt7>dJHVbSxK&1VW0gQYJZZlTvB(6;cWRSl7#{o;|3(5})x
zPR)m|!n?Iln}~FbQE;?Rw@8)ut06i5-*%!sTbDTAYuxtbY&2bIanaBaCj>E2Knc1b
zrs5X-u7oLhoQHrjyq3SIFr2V}7F-_x?T3DFJKmU`p-*n?=C1+r2+>Ig-l$0PoS;gx
zW;Dx0iZ*Woh4kY4-~urU`*7yr`+<XMDTWY3lg24lMD`eJ{_d9@%p~TJ7D);D$uG^d
zHEod^3|)V`Vq0deStZGVHK8`}#<)Q$)&+qc!;JCEcAb!%9PN-7vNDDdNc6Iw6An8f
zv2GAsn7U=;A#zNNCx3A9j(_b?8^m`hMM)A4;=TBL&B&A!-pwfW!CB7}-|eo%T4jqQ
zCtlNk&97*z`hkEv3zYR2&B=H*7_>|azB-6JV<Q1#F2QF-Dyo2^E#~n}NAmhU)Ejgb
zQFkKvW2M}8$wSE92u<{ED62Q0oP<J>9{8R|h%u}#Fm%yJ>*j~({CJOY%&{@EYe;#M
z|BZg=)%{rPO7Ck8m)B7XFCb5(-^y21utQO-+lF3H>IwWHLE|1rGR3ib>~V;?kcdr8
z<URNF!9XU%2qV6IU=MxY@iQx1bf^6-GP4YKW<yN`mhZVo^FEse3B}pK2m6)xe!jIT
zbCo$krmY6%SP(4nJ)hF=1(euo;dDh}IK?#~ct%STFt57Q9!3|>c=wExyu&v7O24Rc
zW}yYXY2G(SjdMc~797RqXdtQwtjIvog};LLz_`z41sz=$UV;aWJfF!?ydorg`7{?B
z@4A=(e=XXYF4%bEQ(Gc(Gnm$vDi9>E8nISdVi?KZ8~O4N-su|IP6+|2tWNLtTxTGR
zMMS=>NXkq_psEy)vU@Ek7;J5La8rD4KWpS?M&Ko{*LEu9{_5`nZ>zkm!92>L<Gm%;
z@%3O6Y+fV1{f`7n*6pIg{ZSaldW6MH{!}TR#Fyu}EB=%F=GPr<m(<>q3uA=?bW!q%
z<vu-V_d&o_D6Ln=PsDa#IwOEGHrZ&@@w>pbvn7t+8Q;w%^H$W8Ebj|qxOUMSC`C^K
zA^&yU9G@MFJ2!1Ux9H{g-BDYx7rU;ahVbw>g*nmrJ0eV^2j6^rvxB3UM+%HL=XYcW
zN3O8zbwaxl(3ifd2I2NT5uaDb-jl@6Rpyh8ewY0hp)73#<+XH@C~Ju@DU^>r-PZ(I
ze=n(|g>SE~V|7`*9e8ihR6?t$D#oz!@%>O!!BO8vosOmff!<zqFatONd#b?3^mt+>
za?(n_ZJth~?qZD^z~taXc2fsHBi1$fK!DM8D3SMC)(Rf^dz_fkn|(Es8i$_(>@rb<
zQxP<;UvhOb!Jfw{(BDrLVf7Y)OzO~K-uUw>Q+Or5%GE_u+M02iFe9FDX=^ofgWykf
zA<~`~p(=h$h{f7F`@P4GvYI(VHC5nn!EH62QM~H{LHX5ze!|Ag=C9kwd>`7c(zUvw
zcdf~*WCkAmTb{Ye4sE-K+b1LTqOn;|gjqddBFhJ6FC@YhCSRGOQMoa4G`bNRJZ)8*
zNP&>3+l%$TVA%U~6()H}1B<E|nwvzw?t2<3hG{H&mO&QpbwllMQ=P8!MQ_XmoUDzc
zTWG+PbJ#6*6zJ#+n%eW7gM)&K>Gcr_4CU(wbHxIFk1vl}u5f`FUs^&Z?L7}i>~j{W
zF|p_|tZq~$nLiId8o!T=W1KY2(TZUH=EEsTu(s{hhm!MxEfskE4cCk|nC{i#XAc#4
zFJAN&P%sGhx+BVW)VK;-h2+rSXF=&4ccSaDJ%-<VU^ba~_&YBAdF~5P5q{@12j}L-
zhaJi1Gf~7l{l|pN?-w`AtM$ol=KMYa)X71|N~(K&uM)DE{a+;Ob;bvKSJ_2<03U6<
zgJ`kp-SGQ3hD`f!9^r)}a@SI^O#6sSke@TJWBEMF3VKJR{pgHrR$@=n>5(&CTz?J8
zQ(FUKEAjHQ)qLNT&Fj#*bT%na`;OLiB39{2+tY-`+Wk@#TdiXMs{ivq8i8#^j+KLf
z0s81IPh$Pcm5Fm57vOOBgBA0E;&z>oe;9?fmG|)TPC(B_uFf7m^i!?E@@Ke6`O?P8
z1;ZFJwfYP>%bF>~_yPm<S5%P}>9IlAc`sT8{TkcN(<zcG!IqHJ5Hf*_v)*!Ncma$n
zLn-tHtZFKPaXY;o_;!rjF<V|NQN!b_DC%bc)P~}!j0FiW5W++f`7*ec_p+!rIy6P>
zYt1)FZ610hrLqO;NHJZ?DZiwOx%3nb3B>YdCS@WT&hS0vdCNBt%vji&F^;TlKK*7;
z{Zr_Pm~9jI&N?&u{*4QysC5c`VgJBdmA)dIm8Q}52Xw9dYL&2j#o*}=fZVO~`l|$R
zN1|=P1`j<Pef&NnZ=D56L-5|bdWQIRVhqwyyt05J(s2rse@Jd;kOUHRUr%1<ogmq#
zZhw}N_QjlQ9}rV*xUMRR-n=09vu;tD8`7wQ-T8en3oH#uEjQ-U5*ycan&zMpH=Nm*
zWNuG8ve0YiVdowlWi&vNp9J(k_8W8dVMemqJ=ZICcVq7_P1_HGk<}gAjszF?U0LeQ
zp0W2!{uf}j(_7*clLCi>LWbm0t{gggneRcOiY2!R^WWHnA2|_0p|fv!rCIl76!K;w
z84qBP%<oF&)<#jtm%vGuqvRSW0x9y2cOMCRjru>)35<Of`jBYmeV1ba8fyJ`u()6m
zdpF9lYT<Wn)O@sxXR>Y#<ma8xr-0=3QhR}xd>_h<3Nb(;i;|w7xzPQ246NupJUt3W
z@igpmq@o1uW6ZAvv>0|b1`#`>)}WiWnDJ<DF-pp=U`}nP#6lj9xsb(+DZTsCa$j;F
z95)9y&<9j|iuYW%Td4KXvgpZI2A9*m2*D*cAXTnA=TcoREipIRd}YtYs6~hm_FHSC
zZ--WmcVXOm!S7BN&b{fzoq9fMz+7Iq^!-xmu8MnK8$cPHVP3YV{5N@-y_>>f?gjLg
z>&I(`BA9~&Fq319d$`g~_9q;o>mIEBZA|NkdhIwL5zDreE4~OZ#~<}eNiv&Ld0t<n
zmf2QS-`gL9HC?Ats$0_@GihUMwdDeUR%Ewn3+4m8Ss}mlkL&8%n6LnRNKe9;-AbK^
zJC5k79*3Rx@OGwVm*4&D8QWzf@CB`s4>PDlp8g7wH(Pk*th4LSbpnAj+eIYymnK+t
ztU-_4Q+L+dyJZh7{hRTZ=?K&Ocbe(PKPPd79v0~zM~;P}m11$Uz82`5g76SgqD~{=
ze!lePo7E8@n7t^HLwmJ$U;mYih?J)2#5?}wp7k9@)2UEcK>R{5y&OT^2U60R%TWny
z!;HHh*X=2k1ztmO|L}=ln0QUq9wFH+c_==EBgTPUCMas~tpI*5B@Vo9ocdSI!GKSR
zq0~(A$T;C7Q=74sc_mN^uT7V51l=O<DL;4K`evvgS;VP_;<93T%tX~>wx~}N<wp|L
zOiIt}KO$wzqk?IX@V08XUq`cmH1PdYuK)>)SEsigy~tIge8z|rN;fgYE6B+#%k4;&
zSKq_TVvul|w?!jpmA~caZ+BnwX-}Vn@vpuVA}Ta?XZy9Gq|B}dU_d}&>Ev}#Eeafv
z+4Kik)MPn7=y+0P`B{@ah(M{I6<pg@wcPFYekat+_l=+NN|j-0ZC9+WuK7BlnZTQ?
zi!v$qu}^g$08LeZQ~MS$)6|I=ND(hDv4d8x9UWy&l{cnZ6nL4refNVK&Aii+RD3?#
z_NW|2>s@eodnrcIr<ST_-)YRav2e2qI@VQS7-aP4J={Dt^6$<=MQAa&bi8uv7A^~3
zxwOa*QUIum+OVWG0IB?OQ6ZR)qO8EFld#{~Kiwet7Kc~2H0FX~DCnar9ivP*d$S<v
zU{^xIiMD_;{uGqqe_Q~%RJ>Ca4<*SJh2Ml<R=@l8Zh5q-(C|586V8*~(ty%aJn+KN
zzpbHjD@CEnli2hyw7N9Jo}OEtr=EULR+{HnKeVy7FpaW!&&W3yrQ)8?-4m|uuNcPC
zjEf5p2f9utuLqi*;5bs7Vq!2(R-^A^vyuF4P~Re+dnPPtz9W9G1FYf5HXUL4X>~|*
zVTWJD9Gn{)d*6fpY~5epRaf!?PtnpP7%*}^K9p!l5K^T~_D}cPV#RRfL<OZ*6tIFS
zJynrEg`#tW_fp&KeUW@KX@%R*&8X8ZcZ%!4Z`n-*j_INu6qj{+s~(I*R@4xyT&&!E
zKG0AN6e7|Fdz*jquN68eFs1WBNqTHWTYh(qhu6F&WN?7T$txm9#71cSn~s_$OIPCh
zo66q4=}YQNu<<XA!w`>F;U`fqdveo{U!Ye$)yorZSHtJSqm_LJn68BAhLur0;@J2c
zQTVUOFy?<-MPf|yfTO-!g~%fXVSWNx%^QW+NPR~AmV|GtY~GLiF}})lIXD;&n-dKf
z&C;_rOIOjv-SqBCcu9Eap{(ef;&`ffxM;Yf#8d6~0`?$z;OsWV!R^;pRJYVNct6d-
z4Gvx&O)5`4>;L=qeIUd4ePbcQK2srk_i1c;Q8ROYT9hfDk#zoU?!x*7jh)OZR<&XJ
z2jY_mw>O!7yZWnq_PTQ&8D1?fTPQaSPc-k?MI83J+>MX;UK<No<UQKuJ&#;$Cv2-)
zeQ>p-r33!PZsgyT_lxSrMG0jwAx%?pU{b5Ita@dIye)mg_c{K@>fdj8#ld@hLUX05
zbO{-AXkz>1gQM;&Mb1>L3C$+!UnJ0H^0sSwkbi{0%`(&$lfEOzs#pRbRpGI^2%s`y
zSBYAQt*JVZ1biel#K)_T`O$*|k@Dn#50trxKZP>pRBYrpK7t8V>c3cPupfG`JAv24
z7aQu>G5gnQOS4MfWKuy6Zd6Ho&$QAOw_o*L5G@q=s9x%t@$sUC4?mbblmtQ_`U!L!
zTlc{f(ztCf6ha&YWwyAupipdFXzT6v^#`m6%+VT1iR-_V%>D2bQ{=pFrsYw&^?DE_
za$A`8`Q#ac3zM5jgbxmGHEQY|i=!U>7l5G-k*m1a2er(gqBg!XiG*}&n*@2*-w_PK
zOZF)ZYdk%KQVCDXkUk-#8nmYaTHB@f`E?irPtEE9AH{gc0{%6<_srOdRxC|sQtY*3
z(Zcj(N#hL%t1kwv=POAAic5>6UN2BL(Z_+bycTLX(Xy*=Tz%BoaN`4&9>IdgTH;Ek
zVEG11yPmhdDBPC!EVxT8Sev4A{|q4NHZAo`k&xNnjocx4ZwC5M{fO(5hFj4|9$U{>
z^u@rc<97lB1da41yYQ@=P0_wEQOB-ZNZI#x4R+gAzeiDn?tKl{-v`gLwLS?qEn!pK
zChVW!Y=p&ke-Qb9RDE?+)ZZ5^9Rf<o(4Ep9lF}$4(k&q(Fm!he5<?2oAt6Y2Hx3;G
zD%}j-Azkl--}ifKy|sWpXSnyCbMHB4@3W5^sv&wkQ0a)HyN1|XnX9DZYB5W5@>_SG
zgVOrs$`=8+P{`rr_j`-1l+toLU}T|KM3>13{dPm^n7Jp7(S*c~Y_^_Stf_-MW<_W$
zITe1<q3T@t<BMYX;9T1T6&=TnyEe?8m602f_-iz4GV%&uXzW!aQ8-F$oWEM7Q&%~|
zzWK{C6n$H0rwNd>LK+f{6_+^Fw@B$TfRM?wF>6Z&G(w29CGu#`$f|I15;if0PLp`9
z(%TB$!~<&6QCz?e>!x%&0rvpGuxfF>_gPs0#+zvWa<I#jdw|M^G-dC8#2|HwvgmA&
zZhAV*D;E!=&~<m*fr*1i(nKD5{d`wX8*uhN0O1N`&&_|`)U-2%h2#iq>hbG(jPx^M
zz{xH6_V-eAU{|2SFG88YRet1@>Fa6So0BD}>9#OucNv2kUKRTiq9C$>zNLKT!04Eb
zK0~|gHHea$&Um-rj96xq!q5Es%e1LhKP9VNsgJ*!2CMKKbT-tyAK9{&rnE>IHVb_{
zi{#zoE$zx#40PYeVqe8nBVkKN#SUGX()GUByG$`Bxd_ytF|X~;Y<1;*DO9b&&%tYt
z**^^%@?Sgc=NKr0jgip3yVhQ(<T%C=b(VpLefCeC-JW7NHk3$i#$X8G--M9Hnhi?x
zJK1i&bF!S3sZsjqWA3}4c^p-)$ZWFj&6<sFVTS~P#C_hS|3kBPAx`n;++?G#WX|f4
z4hae-JFq`@TJPn`@;Xh+zEgOn>u{~xNxSy#)X^4IedI>_zVPwBkt?KFy-Ge<0e(kj
z9~q>UY({M}T@Qb8OnXV%tAj2A?vzW*YR70IUKpqbMVCq5FC(Uo9{ex)4($J0?QsHx
zb2HGh#zpBj3B;OfP=021u&r;&;9M`U=BS~i4EV5kFMjVXgL^P8VV}XS$SUXBfMjD|
z`{dBU?WxE?vf0x9>#)go-U!IvSA)kOxmwCP0;?~rrBP51<r{Y;i%jI7s&N!=j^_SI
z3|tx9IrH1CmdhyjVS2VPIg;69%M90~=Y|wLm<Hn82>tOO+n_~nHG&*#|JVxXi-JaV
zm)5H2H=f^26B2o(e{AQ|=MIFc4_8^iWkr+QsP!N2R)-oQ{OX`8gcO40HG1^i%r&Z_
z-gj6J=Rb9iNIK4uYYh(uLGg(|gOvU1N%R7?0^{0yUK+@vVetQ`mrn(R4_uF91MakM
z6P7%Qk!s82dQaKW@y$u_-S#?3Xr=Ed&_=8pD&dl~!M-^WQ7;4cJ~@PF1tYD!7hB?*
zRUpOwDWL9@J75ybVkyU`nZm*~2C6N4f)av{tOOrt66!u_|Ekn(4V@kZ^SSbdij`Ap
zg#L=XIH&79ZT=w>&FRDx+<%p6w<GpEXEj-0srvWspLa4I9%EG6tALnIVB$2{Ut0nR
zyR+ucH$stquJ9Ha`X5F9N9FjvH|5lGd(Xyji)jLCXf|g5T0(9@@T1AQJLZOH9_$?g
zJ97oGIShjyK}w%^hUlm6d7uMDFw-VsoPrbNO*jFRVKwgsUGHU+WSu84x1>;xgn<BJ
zlTE3+uSy^Jr`xBL;jM*0Bx^PFC>8yh3=mk06vFKeaq_kA3S#%SC{@dexX#@7&IkX2
zE3>s9yQvz}#0x=w#lEu4olckh{pqg_RkL(2>q`yEfO-~IQ_1UXip#zZfVXti0yi@&
zH>-`vhjl!_@NN?V+_H#Gur(Ta^}5>}sTIkoPir-g{=;G7QY{Es5(zjsDyU!C9>dn2
zekVX_89`s$zn|KLNNf2i_ubPz&`CxHjxMP7|G3_v>3T<kqqrcn*>S{I-u~B_38Bn^
z?CHVeM__LFqagz4vykK*qn2h5{jR2tmYJca$J|!^^*KXPmvL_Jajdc+jt{PP#%akL
z&%a=G(tTq}+ls<#swRdn?LS}9EG+CS?b+0Byl+<Deoduo;)OTYwiB=v2DR-BQSZL>
zqM|mG@<LJ1(kt_|LlU7z>*bV9L>0L^3Yiv7J5|g<vn{*raFanYs|YiGrXi;R`S8V%
zX~(_F$>XQzLAz1uEE8~0`8sN~^;L6V89(7^#+PqTWnXCaDNG)(y3)gxMh!|#S#f~;
z)YDTlG(_(kzOEzBjCxCP=!tPrF{o&o@2>cs6b%z`nsh0696=aM&!cp$sKAjh-vKKs
zz3g@~b~Tium~x9;aD}SYrf>uk()s~FjEXi7snYGQind6p`+0Ed!>;=3Fe=X08H3zA
z^Y(?#^8+BetTDViVsZHPyG-(s$x_OtsUuh&ECqRRJo{>7_&=`i3+XW<=@vm#zrN}q
zW6@;WNg9DMJ1x@~GoB+a0c&#}q_uC}Ir1)a0k;d8$S*SuCvZt!1J8W<W$Z4)Ul2M4
z**0@1s+j4;xof*A_YOT_+G`)mI4zETqq0ilku?VMRF%6HAG5~LGcc<9YyOcdBMi$e
zd%_<*(0xpXROjKQe%yu@KS<M)9u43A(A;O!e;t9jFQ3<lLf^#lrVOM5vb{9KeE+Ed
z^{-DVyxQRVdjBtRkPYdLo|x&@7^G7?(8uhIXcS6~UIju8dIi7ra36Ef-XnN?!MRoC
zM8;>k&hAgPl-{9tH?~2l8_Tho6D8|jlQ;?So5Xp5MZXv*(L~Vl8CpikqilqF<XuV=
zfh<d2HiDM;H(QGhrV*}C7H2thl-Jrg@+#l3sB1~(n?rnag5Icnk*MhV&@he|B8tPk
z8N1_?GHYsht9*^3av@<$bYVlH(<o2ZgC!dQ_rKzjyjgD{I+yETF&DO3(G+`znA0(-
zYsVtgR2;DYjOQ`e0mMEMh6Tvw(dli|IT$HO;bz`CRrtlx+jW(RruA$DGH1pFRIDz=
z26hOCcezh2jGSHl*cK(_Xw2yU+G@$i-UA5YiM+r>?i0%S?(||OFj+43Bc#{g^`2?V
z{KZyGfY5rOvg9h^L2uJ{(SVT+y#jIVfg$jDUItZx%jb;QuYF8@WRMYhsu1T<eADv`
z!i2L_n6rc?oGoDu5n&4GSkB&!v{An{imce!B>Z_+CF!8QT5AkNfrDrK?VPT}8_4Xi
z>3l%{vnwD{LLp^A!b`|L?=jDQO>(TKty{&ax!o;T1(gvxAJ~n5)=gL;)K#pq8mY{t
z*0`GfdAa-D2+A1_7hg7Jj%moJ_i1aRM5K>Bc9sDr(k_^I1fRT;I4>ee3Ku4R;rfxv
zp;u1ZhKR~_33XN4b}cd+IIbh~34+!EVtv<TMwRJ)29y1Mno8w<cG4Vi!1+;?lN2yx
z=u>2mSwhriO_{~Di!qnKO#hx|TSsI+VkPmPq|m>!$fq5}miU13=hpp;IgYl`ds0UJ
z0^@uhqaQ*ldt^5QYVYT6B4TgUcdo;gBf&K0Ss5H}-1!V?EYhHNzbmW=EDRh|VxGy|
zNY3#6`#8*m&*7De)5yypA98t;S>Dv*{-lf=PRBkkhskz5ZJgxFZ_UM^1HIb%7aeX7
zzrD&=GA4tvS?ScRX`fSEcr9$w3wiOTNHM%dOe;k9T={-zY?$0+hw8~(_9Sh?S3z|7
z{wC8B(NjK(&ig<K|KE24f1bo^_D)*vYWH+I%;9(Ptt3||tGnu)F{j#>Jdt-b`)r=4
zHf#0rHFH_C6OJZ_)6f9P=Kj<-$&+IJKcYoxnZDWb^3P5;J%oZEqc4a`NSy-7n^z9E
zHDITgqV^)7x#-cWbwS?qj0q;5%5|&WR#lPFPyWOuHaVFjHeyprWRj~9^sCmN1b&@f
zmUecM)@c9ub|We2@LVmis9iU|IaGc9Nein{LydR>Sr*ILCeua_WH>VOM`(7_eRSij
zsr#&8;o7tRoa0e}+)4GIXY&;HT()If?Ie|C+}I(O?t|vf#|OD+zzA^_AC1H~=s;!O
z47$3gFt9Qikx7vv$?av2YrpW;|Ma*7N=r2XkFo6r{MWpM!%z8<w2xj6Kl!`~+cFe=
z8K#x=<!{a!H%i>QI+~fNSlKF?tT%7G`ZghNXQj8_$h?;DA&BJO9%eQXPv(p8^0lY5
z_$BFM{MU9_ve1+Td%f~BjrACM2@!qc){}M#YJm4<oOLMeaZ#KV{@J9rNT93>0R56|
zK}`Cw5e7^;2r3M6Vx{6`&-<fExo(Rc87sC!8ito3i718|6craSG2nj(`R;{`lJtp$
zz`y_AXb*ZkFy}@lR#MzaFU~V9)}Ytlibt%wP^ndgzpX4i5g;3t+EA?WA%&PCXPWdz
z!#tRYnF*90E@yBKIqz}f+%dWoHh#uAiH$fRlVUGV3F?QPcrCl~0ekGs^C<$qFW7h<
zm*gyTW89a18Q(Z6Hs+qH*j}^Gtbqob5u);u;%7UAKKLzMpJYWoqx$=34>{hC&A&b8
zw=M(3JP|CeL6B<JiqgTt9&GonSFe5JMYCO~`1}jyup-sdqUkrru1Rs!-yMIN(vFao
z-d1c<OZ8uU^*OsvrBy*bMAp?j>dgZO!-tB3%j?bQGcsDh7_d6o7c4Gkc9#MtzG1#V
zI|u_0M|4ep{^zJ)d4z>Kw|{$7HCIDlJzqXp_+Zphk3pttTb%SSsUqJ(!MIp;J(jmy
zdV=YN0x5NfOzE~sIGeK%Ary*Xqo$`ySbg6+CD$MChgyLpzgkLtVX~;{)ai6+OQl2M
z;;t?6cro+gOs2I=CxTt`nE6mpeypOntt@afkL??4b86kJi6vjsO0sC;932c2m%D81
zCAuJZ|B94BPbY12{6C5%M~<^81?u~LAs~&C!vX~bz0nH(qh4@1IQK(pJwnyhuwjdF
z-(x3Bf4{n$tR>UjYC9R2?Z=2Fl-qO+Z{dsA{TJ(6(nFA9C>MHN;O(Ekf2Wq?;aH;l
zEbMeT`K0}*Ti^9%8JUmrzkgLU0s2B54YTOjw_a-u4J%EZIlXkrJ-u|_Qb=h=rP&Yb
zZT-p5X~hxbbpsU(E`A1j4Zzb&MU|iqwLU^$y^LJkKud7(M~6G-M(G^b5aK$YR8UmF
znLxZo#crB|V#O2EH-aV<p<9u((nQROMK(G5>V?HUm#xfkZ&#_cug5HqO21MH__FCv
z_b|2#Nv@(M2g2aJ>UOK#-TfrdmUnFQ-8?tX)>&lw7a3COQ2%|C3=$61Sp0ODLeFG7
z24J*}S<8u>bz)?BpAriguHd%)qrMeAEew}N>fOQ85qwoQ_t~;f5QlrUjPI|RCGx}f
zJevIL_@=2>SkNCbKX_kEh$Z?n(kK38;z?D|#`F+`&W2)iGlq{J`j!1GY@fQP`8Ei&
z;b4g#4M!kPlDEwAN(jGR&wuS-L`6g6v|d?G*~dlbzFviJ=>=b(oQfkv&Dt@%)iRQl
zNLO{thoHQ=SX_V34}3Y>sp~iM?e=~-8c*Dm^~LS8>=w3V*GgRrI`wI<iE@0Tkj{JH
zLv(;bn9zXrKEg*>bl*kYoKX*NW|OPxn^6&vS|n;wADlz)O>_=!kAef5$GumogAw_b
zV~-@3xtMDf4uWNe@2|9)`)4=i9>ZU<A?<CM>~EP$ggL6#Y!_N8vRmH*(p3g0B^=2w
z=oP?Nr+!v~|B#`h%EftkocOE<n_QIS6lv2^;my{kW<@;MIQfE#14AF8HzC^@0&79r
zDJq+O#p9_J5eEtC@->vlp&Qxi#LaEB3pwf^UUh7O+N82Kg*~G5#m*=uYiKPiWB?pv
zZ45XjYXN#5-XfF;qGxt1GajvgaoU%k4J4#{Zn{*M`R53uFFl&2Oz}r&UU_$CxUS=J
zTH}z<sp=tjTO5~QNbA6~tCYe@XeBJ=xbGhHzPFe6g_yGaA-|a+NqwU)i){(nQai22
z?sO4626Vb5m$#P01AH9Tj1*d&$l@&ZL&jR_hP-<|T8<DwFc)n<iSclIaVR^Bhjv{c
zA}#-zh+$2l@Q2gYbiNwtt$?lz()%A-h0sO*V^SDBscs$*ERm2`i@V!#{$pO|%tKTQ
zBu+x!WfEw>R$AcTbU*H&nG^ALr3i#=Y@nC~AVlixHwX^<6eGv&<UIGPcC8yQvp5+a
z{W7HRaCPF8#rEu<W>Y>_22t!FT8>}0dR>Fcmi`{XxsJ;zC~ygqW&35u-lBday%ha~
zg)=(gYih(^ys8boP7*Prr~2zD=%E~V!s02fcFh=kBFqfMUjTdYIYIC*!|s3gnN$_!
z-^%BIE2-)fy%u=rG)}*oP4bAdtU4esn25!|Ovv8YEPcOuJ&H|-Bw9PpPcOPN?y5$t
zz`CihaV;w9s#h>)g_wYES6#tUE=x0L`luRcW_ryEE$WS*tzUmSe$n@PV^)yIveTQx
zJHsm7uJzpZOWlZ3x|Y#E&RW)o>lzcxPbNP2X*!Heg@bN7E%kk`ux4-`FDTKm((;34
z+eII0D30<(D59_7Xj#_dXhupb%&;Npm4vkuxoX6j#RX1-n7=vBCU=Ga<No70()na&
zGz_TJ7d3QS-MA;tOm5<_dEoXGd$09uY4@Ni-&R|$qn3=xsVF*{EhhWCoZ$G3D3qjN
zSQ&6dV<~{YKS|YldcwZ(7$2@JJGM53WSZa@xEFA|Gn6NJO|vcU#VZ-JQe0olS^AM=
zp#~+=@>q<MUP<l=;jhXc)ECx+{$<@E!!o{n3g>AsNwQU%yDcVQ?1VM%M{)HY`v~}w
zLbL#Tsq_v@!Zge-uWyZ|TWPdWPO#bGir4CnAF5RC9+@hi0SJ(BJ_-~#OULUOFZA%k
zjsD1icwP39v;1!;MBMGtx0T5t5a0nsdN%j=!z0^0?k@BV1V0;2L<%$YBdJ!MdyzuP
zANgXKTkU(j-B=HLuLz_|XPbpT>aAU(9{Aoc6g^F9<F1t7ED^>jP(+fvm4E*+ac^_V
zwVaEuDz-h9#BVsF^8EO*tXl114aHX^&m33R&v8)5|1|tbRkXOM;*Y3>2?f+a)yn{T
zrSdJD$?I)1>b?<My&a__oYDQ*HOZ6W`H&Y7F*r9yWp_LKJz2YImMZehgmZtkMfmy;
z^fC{VeEMVQJ_n@s=Rp56!2G0?LHam4|FdP$3%QR{n?y(V<)hQD?BzAE*0U--$C#cq
zV4b&jv522|Z12Xe=B`p#c@36Puc;YrCx>A@y&0CXERRi4Ut3p&^_niY7f1Wh^96Lz
z5*iLff{Ftyq`*X#n(xylI0FALwh1|z1l(@lBW|dr%|*AS#9uz%D(Ccl<So|WtW0lt
zBCw1^OBgB$%5NuF8r&kn5j|clfs;u?={-dCr_wJksIsRp&Iw5MvJ?e;?c%CmoRqFw
zAe>a+-EYh>)k{`=g7cS$5rgN)@9HH=uo413m@`9$$sf}g%$SJ@WAU3k3O)UWkve0e
zoz?9^?p0XC$O}(*N7BC(jjm2q@t?9qam-j9uTFS*m>%D%{(FYakrxTzoY37FJBlxL
zzx@Uq#=%h4?(6BbK4t<@Z)Zeg%R$8O?d8sMqcv`UKiu{GI(GWF-qztK7YUDkag!{q
zlwo~f-DgJ+(bIcB7*-={B&f|fjPfMgWh2tXo7xf|3(JQ(yFvOeQczvxi$h3aboSd>
zX2yYQ!|1oZzox%k?kAAkV5$C+B+nk_3yvPoId*FAQtCH(9IDeFB!d;9NYfUfW4pY-
zj72YgJ*_H`&Y`gjMRUA3AnXo$$c`@?k>A^^-F0~c0O<1F2OTKrTba+|syS=G;qoeU
zf6A+YH`shYW#bB1VJ+FkhqEO<QQK4q=(F<HO1v^N#aCthcxvy+uS^iHlP3Ed#gh?N
z7*lGMq7)XAs+^wXe=pSA8ba49+UplV!F@XP+b(&x%n3faIuqSSGt%%~mCb$VaWU(w
zi#|e&!QL0`{o=x`(a#M%?z#F_K|WG1%tF7Xh2ST7M#GVdrDpbJ_ngS&NK<{K_5*en
z#Rw724bONN6=nLfATl_7{17DaE`b84ezV+}Csnoc1Hvj*wSQif$mhrt1S?qk@>I?Z
z$(;XpCm}b8bRVCm$iC+hH=e4evs&77w=$eUbGe-mCrha-tC)B6N)6@o_Yj|05$-Z!
zDYpSV4N{lSXDLXgSeUI4{b!nzfF4egk+vng$=P^Q)J*gv5lPgY<9g*mkEe01SwCJV
zlYdUVx|Dh%d{b4(ZR6NpY(c#R@14+@);i)G_ymd(eKF~$G$RF_K3S5$P+JQs92exp
z#%Ac!%{1}+!rC0WrE`k4N^Iu7mmD9G_>iE(;V@m)kHdfYzW>k7=%Pe$4*E@V1D^6t
z(nri64mY3N6)=q*@T|aLcY5X%%+bV75nUq3g{`b~0Vho+MpNA{gAD6XM?=FtMLnyP
z3m1JgF7~*Rz^3;=<Q+EhBRc1Ydm^OpU3bpBkSKj`pW?$4WF_o)lWq`U+|Q@{n~B*c
zaJ;^_&$Sv+eM)u2J83NfRuAQ*HJgZlo=e;F)(TZ;Io2t07Zd5G@}Ku>myL8u<8}S8
z-02csgO~$DX8WGS=M6#y4E2rCclSH>GTTyz*soacTC(<rFZ3dQdV+gt41w`}fc^4m
z$CTC{c?4{|xc%xN9vymx0YU11yL!`(Ah`Vt%+*sD5Ad1f`r@b7F$HUDc_Y%^uKi=7
zx0l|#O-I#)O6BDOsN6_2vL<$MI5Q4UHs}pWEFJEP(8tC0`}b^uMP1T=-Q2ufOyX<b
z{|Z>Ur2LPI!<fSGK+9%_4&^xt^QNt-E{@#PMU{fX_R)#xj{!cT20Bf@j)~|-UXPV|
z{maz$SSHiw8kcP8R5-(i{sh;CKg3^)CQo;Ijk3m(K4F7YUpf%8{OCpv&Hwt!5lO`2
zPY>B(ck8OHJFjGmXEre#EacgZ6V8)cdCVRd2Jj9?4AGbNo6vlB+Ih*CO_C4@qwjQz
zq?o^0poFea8-i=-X%K=yy7au=K&7D9NUSs9)HrrUtbH99L_&@bb|uFP>Z8%`jeUqN
zJX*_R|Lx@xMybabIAvl=!;<EYl_B+jB#$H?-^pH)0UM#Pjf>fpAVu@suOn*o_rp^`
z`S-G99}zsi)OHS!H7wTE+jBFd;gy+e;H&SpE_^2^y{cRFlSL<?Q7+Ad;V<p3$GQKc
z;=7rjFfB9^^DRZbtbOl4qLMt^GPMxX(8mc6fZ9qLeRsTqA{>Wk;T1E@Ff~mk#k$yx
z(So9!_)I;yjGkPr0p<A<dz9^rw+5pnn?^tabBX=q4(wZeN=%?%csEj`2{z7#3iQbR
zMd*e0=u8DNPBAHV?o&LAa)-p}cSnLO*)rZ`^V|K83*hx0S?X58q5I;#F04#QU8*Y5
z^m@Q!IpAi!V%Z|QDT2q6it$~{LZ&FhEKuQh&24Gobi0&kg(hZVW~S)v%t!c27r%$2
zuOH4US#ytuXaxqDk_E+zsqVTGMMoeLvxGg5!>^`UPDh5sacoGW|Hfo4HHo*~&9WPr
z{or?+=1ZIesQy{zngvfVQxBxNPTsv{?ytGSRsULHopX`U*6_QOBc3n?Yuer+)FO?!
zvJmLSz$YAvHW|tLSO1c7uC0PbJ3d84OOuv~d4r1^8#ylZORMcYY)zYUwOrLO9=5cm
zE8Jgl9v79Sdu7fcDl`{0KL%bMr2IVnmGtuzOL-bHVv-e~NB2@`y)vy*p1fRnF9|d?
z2A7!&W4*xTF=ok+!4*qeKc};hqPiIL<>b5ovR{6n3Q_0cS{D86wtwyj?@%(!_U4jd
z=n@l9<-Ck|KtM0YvW>EXJ=Ub@1C>zl)LmW#ej`9eT>{B{7<+bfz1!z>y!sM?lxv-`
zjFERE9fS^Gk92v+a-C)QSaiG}79(HJ7DKnL96ZTD^PHcXpB=BZe)kU5P+Io3<)R3?
zo?y9Wvk>Yn_7WaYu{fSCelJqAQ!K<6J@cDPr-l@GJFEl$3oyPg;S=tTP|cHae3ZjX
z4fWD?<&~7Y_NcYaCRTz$Pn$1g;K3&(v!|dHw_}L&Tkb!+QH*tsl9Ey;QBysPIyu2M
zsK4FD5vRmdmv#y9ETHjy^H{fl5%-PhVfVo<V2fbUP&*p)rarZ~ThHqH9glNBl5`u;
zD^%L|9r96Mw#_zHTyA3NkN*ntUlyb3Sw$gfQ&!IJ?Cs5MxH>qX^fu-yR(<^(8<G=9
z8NuHD_N^rlJqPsPmrBq=_6Uacqx{Syg?9;(ezko593gFfJ@+|fUn_A3Q%!7w+0=7|
zfv<m7g}KHt;&lOCJx?!tEq7gvlw8CN>tInB5<wEm{Rk6qfrV#ID3I*G*Q@f(5ECt~
zXp;Md&4uiymc{<Z<@~ihVqW-Tx`<(x!=Tr`&`jg-rZxplyptUwq3=d}dk8AFpWtv?
zPWrpv>efQ_IuWrcnCHT5ikEGy`I{aN_|yzA;i2fO0_{=z<|OYF*SUt6j}`VNwL$p+
zyYpB)VWZ;;GOjqA7T`Xo6_PyPJ?a5B-*dBs5pF=@&^Gfk%=m-}lp0z2<CCRktS=e@
zQ*zhp>7?1H4c~V2@PaF8=B%gmgq3`=X%k55ci*-TeX(CtdpRXses%ipf=SQjuL}#}
z@gj0=BtVM66zio_hFds~eiAKlw$C`qAN>>&r+#2R;3SwmZw{fqssPm}t?wJyeV#WN
z%A2_7q$jeF=3{!Ij-GqB1<KrVdT~$QD=3xRSP}9@Zk2^neRgdD5mk|O)#k4*ULKU(
z0g3wrh!_-Qx|dw`ao|gr3`mjWi%*qTtb9+Vh8?KQ+5FxYIvyM<JnG%OnwtfJBvHys
zY|fn*E?fk!JkKP4eDKZo{~ksALE;#P%v<kj8vh-!w}feja#<S7zBscUu_jcSUhLDy
zi@JV82W5&SPv1p<ezn%(ycuS&OI+$<^#w=q_JuK4)FA0cKu_-YX|6W}3pKSpX~qVm
zp=$9=5n4$*Kf&QGxX()HZD+$7G+XYsbxdJ~?<Dq!Br{qSjsI*Vl`LVF!AcgHF3b&5
zA1&YPF!*R9gOGdw{&v^lIjN<Jvx^y`rVF>k@KO>d<!-cQ=o;LhsrH<pFZLOTs1IjE
zNGf)?rNYXvCKfpSUm10%YwwAaBPxuhyG`$VH5U!TkUHB&B+KWg%f|Tu3yANut*Ahp
z?|+~)U6S#!4;;0}$$744v`0sY*68Mgo=yP`Z)|(i@F5tnO1b$li{BDgt$)XkhJrsm
z;-}LdaPiW+YzH0FtnsS@qqnsH(zxCa-&=(^Zs(ac4=PeEO*c6-iQzKcU&NwEi7%u|
z8tT->$d=wYC*}wW2&;?F?!Q)lS1@~N5;BjisM?>~diJ4JXeWQGvcsBI!xEJsC`ZIX
zcs3ME<$|&4BXqY!Wc=m!LW7rh2$lkx^m3LF3BKM-FI=4Q_%DcAeLcew<F}2jXD{vR
zQ3P7=r>}Io!jX)6xM0dHwA4skOYN9sIu9A{sDyzx$pMTg0y@dZfnlt9tm8KR>!UvL
zuoGX3Zl3#h>4v3`W2}5jg*|{~p_hYKUv8yGp5Kn*b=YjK{)~(c*T&~#IG!*_=R?oA
zG?UDZ`g*Q^VHm?_k*q5Ixkmx|stH5J@)x*h`o<VK&DhR-(CB9|)LXbD)<X48Y8$*)
z?@bX;{?U#-?h|Y86kiO>x{;11-c%cWw&1SL6o~WpfKjr4A`?4l{BOzIFDfL1HCZ;=
z=I+iF%a^bB?W42ee+EXO*x7Tvcd5DVp#|&)Gr_7P!haN+pJOCr_~)&*j1d07ccYqU
zL#ps2o3o#oEP)xWoLHc713irHo3F7n!|UA4?mpnX#nyKto@IjKj`d&4`;lR~c5zj8
zBOWgtsIFR9zTd3qJL{az+*u{^w$B0qX`e;kCSJvK!QAdQ1}OCJ+z2y%<I=L2%QbFg
zyI$j=xDGj30M)O{h`U2P<I4Y}h^2~H`{81v%8FvPZD`&i!o2~S+<y6b-2%1qqV-Gw
zsbS2#X{ra>Q2bzcx}57{gk+705-Z`1A&fbpn<Ubb$ek!sCldDRx45yeb$zir(7Av$
zbIO6?2mIJ6a&DTp85{8o*R3Y<F^DTcxoZ#q_FUNM6l38*0+kD2Kq%Q?)~blu7ep};
z(?KS~K!!G5#=Cu#A(OEay>6VYhMR&K<#nLB%a@k>3G{A*ej{y9Up#2u-N05DvNYy?
z<bDxXE+@Yc;R-=w5YoXpOO?#qxIgt}hWx<;Cfn7y-2W0f05=T<7hJ(k8*ESh&C7ws
z;LoQ8<LB~#F!SZHcb;vqJ@c1|d@?wcw#lXm-F!{)b4bT3fGU`feZrpN3zaZ?Yg}$*
zkK?ICDN%Bu)k{QSs>$Bjvqz2BxRBoC-k2=0h&3pu?(h&p-)3KvG8>D)lbH1_vaY)C
za{g)=Bl~`KdtQ0GhYhp&U_a-(C+xGIEH<Ene&)4vy;7u-6umbkLPFt#F03cM$!Ame
z$@??WR|0fC7>}AjSU3j`&5fPTDUYdBswB!h$z3HrT1F}@*KmSIyLrfE$?rvxPt1x5
zRt35%cK(S!Of=ZqSIr^Ea(NaGJC;Tlzze`fR;*S%h+Xf&quw3kn?fi_v{e_AnfgAf
z{T~IC&TAMQl_R!3-F02vy^B`?1>46yBUyNJz0(WlM8WJ;#77iFO<?8PnZZNz<t*20
zCA$RQMS?_SJ@cVWc0$ASy%T2x8eZkw2|w^V$#AVb(dPpXP?#bBy#V43v+;x?0Zwys
z_xGbn!iSFkRA3>)!Q}O5bUt6!doVzoFAkXWPvkI)Glf<@WcqTPGHW#r2&Y%L8!jkb
zFuD~p{H8Dw?YdGaEw0)nDzR!g(S*t~8`~-nW#j`aMHp|Ycn$Qi=7Vo;)h4G6-Sb-L
z&BBavUWgjg-Tou{{@asS@bi)QGtyt13vhI=<LiiGsQ6NTdAw|;S=9J@2Y<Cx6{ReP
z^z$xR9{Rry3AS(LEX~g+_;BegF@VZjL3hX9(FZ&54X2UsWrDEdx>cc7?Bln|RAV{r
z#{HBjAzR)IxYZZG+Ili%{{?qcSxDaUt<}5o{&Vt~_Jz66QQ$hnM#SI_3)NZUiTNpk
z=9Wb|3&}bx7@~ae!RutT!o~M=lkqsOpTg_$gz0|gQbA0#IRk5@y9>X_A|HqHFP#mY
zo!ZIu7R&>wa!YC1VNH-jxzQ5;tI5LJoU8k^IlWK;vPg-a$UB1l0VV^HisCTlZ~eh>
zZAhU&gzmc&Dt1}e;YAHl?dk{1%~+4ub%l;`9xm9Y7gy%;|FbIkZ)2-G$KZe!#`~_=
zHY#<=W<Fcp{;ck^&qiwLC<(E=vuGK%1ru9u&OW%7q#04oZP-!d#vZm~Fpn$i=g2e1
z91Cl5{bYZ4tPZy8lR^FnfYd-iN>Oxjeu88jEc)FBRkM7TLEvcSb$7?0VFt-Z&|;m@
zQd?$LJFNqWne9D@m<(&E&PlT5`Lra=oeFoMz~!OU#={FP;XdaYmSi+Du9Q+9WQ%p#
zmt3dYu>$1p!(TQ^sc6GO0G46E-`$GUp$Y&1@mo;NkmQYRNtdt#KRa3;K*z-(%)a_X
zb$g&#;rxFsFRqQd7N4Wz?F)whXS|2I3yBz-d(*7!I(AFAhLx#l8<;O5rCVq_{Lfl3
zYK=%Pte&o3B(!HFm}pSBhMuVS-l0xe?jR^rr6Dr()1JV_jlM*I4XCE+>A%Cf2jGsR
zV95hTP9*O|zURx#io=_0JOp31Pf5AThvM-d_1`l6ytIJIMJZ=J+4;w64WCL*_($+x
zk@%|@#1&_0KbE%Zt;GD$;%zM8MyD0B;?~tAp9y!j{67pMxcW?od2f1&8b&%Q2J~|-
zt$n-njx{cR`g5P&)%Pg_mjmE#MRZI@Rq9KyY~KSR1J0l>Y5FL}4FlwSw3iY-b&r?@
z5O!52H#{Xk@jM?<<Y}yd;8cvvrib*jEV@50R3ApLHB^ZGZ6ryha%fv0b@=*1Fg^U~
z-(#1(I^<!dj|=U|Gq3Z8=L{1ZC{U29Bg2#`-i=Ra%IRrx#`v(`N;>@8g&Om=rjY$b
z@?PkKMUb40nZf(~xFcfnM$nqYG0;W5Y>}5m5JB7BNK3=LOab~Ms1ZzG`nEiDa_UEb
zrpkclbt+%gHsX4Qydvzk(0M<-NO;||7l&uIr41t_=8WJ-qY&7~i#wg@vzxTDiFv6S
z4;ib+8K#<rQsI>~6uDEe_@4>IGRK;}|8vv++UX$~D9dR1GHSr)Cyr5JtNp>Cycyie
zRyn+v%9Y9E+5tS=qc_-iPq2vOnh(btyYG=cTzpsh4s}f@^x;dM6@vY3PP-#l%Eqxj
z`wbdOq*jBPgbk)fcm7+eCE;gnPH#kZv{&wzHy=(ZC6@T0ahhIVD%U1usx;C+x)Lb+
z+cB{7xzFU^4Fd`F*T!fkWF5L{PW|UeA1R@JRW=^myI*K(?nL{Knksv>j>xUsFME=Y
zdsc1FPZJShbe1;%BjfdB@oHdSd*h>AUVBjWVFs+~x313*mM)0Kxi-_;JKelQ>2xp`
z>L{y;UilVCsp`C;4x3@o9a68hvZEsUF#xkOp8G7qOp52OfgTLe56Arrl#X`J`=$eI
zxNZI!M%!RjZ+VvK6J3+t7wvD`n@@SA(xbLI1MLwB6xZwhmDATx2yRct>9zOY)vI-V
zrh8iQ{->$lN<F;(MN$F_+@;;Cwjz+x)`2=3pO4~l7W8;aV$m_kRW`60pvf$!w{M6@
zUJ@O4p3rMvG+$n1H^#K2-|4r!I%gzOsmBhX?J6YugWb%R06rJ~#&_PmSP<R`3kaT&
zlDv_tG7o%G|CAuf$Ee|#bh@05Z%P_aCfod1%C+R?p~0=B#h8vCaH&oce#%ejSAs6M
z6hG_H?PO9#Kqy0Atr>I-Vw$Zdr2joW=G)p9_J`lP#{?>mmERy85$#+5OvB}Y(M_j5
z55K#0LgDkO;m7B5l8nTdxV(knzA26g=BJ!gLGJ3+h&5BxwlZDc)SH)f40v;`DQRhU
zPNobp{eOWDvd1mNmr($OE9-E`Sz_vrm;4S9diplijFzg99GIe%o6DqqoP>0FB>=J(
z6E8kEfQT5kB)>!OKR-1$ZH18ZLmOH<85_LiZMeMbN{mexOlV9mR9_Bqx7-cK`lWTa
zkMOGfMz*K<cUE^j;~V8!9i%5Rf{N6+I7ZP|v8v%EXM6f1YBfdm&7mcP!N#>l%c<XB
z0Cz)=^IXzt`i_IJrA76e|I5o%8$*GQT&>aJ`>CTRtuV^0xS2=5@!xUrnmcIMid-D=
zWqCP+C+#V%F>>T8Ixgy?==fnmD>jUV#NYlv(p{?gt|pm<Dh1Cn-~UaeoMcfWHViwI
zOz5$qxn)sfDY51ia|(jPJlhbPev<z-=3MB_t7k4<NcP8p>Ib$YI@8Wf9#6MTMTb8U
zEb7L+70On-F;=lF!(l&h*4w}8WKIDwOHp;(l~jBv4{9pA;2-;;s$lm;mVi#VH|q(G
zjMbCSM-gw}qoeSr4P~I;Low1+B?YGjCf#Y~T6{{rV5bs)V3SI@sZ<kqxwLUY#F*m8
z#<!hz&LkLN?Hj_TdJJZ%CW1-Uf1)7{87C2q;GuQH>pfQ4p0bZ0KzOtI|0f)GPN*32
zG|-nfI190(&H49S>1n<lLVTR{?GcEn?@kZ2A{b!FrY?~3(b>ZVy|v18)+u&3E@#*!
zFhCyDR3pO5wz1a&)nbV`G8{Y%M$cFLfSWEg@njpD?)M{1@SnwmOX!TRp0`mS9KJ<+
z%fg+x)D2L=t@bfy5<FY)tkT^ynXQI8M%IMQHpD)q?Jp^$RySrjR1;^2eD2Q<%#gEQ
zX~t;JO)l<N+n5xtf8(n8_w@DS2lKs2qA;$N$NIhMo#i=|u?s5N;knxZ%^aT(oYOt!
zgJU$+ANVBMau0)V(KeOSowe~a;ohQiw4i8!AmR5vij(E=BB4P>M`JX%?*|LO9Q4W;
zc9v=GcZM1pCV)p%jXWA_Xow2Ha_O9z&6Px*S^9Akoa9+1K7*g^!EK4iL;xk|CFc`p
z7q6&Y=KHg3BW)InQ)b=Y_k$6Zp!GuwVoR6+#w(S!Vf(p9Szbt7F+Ng^z{^=U7eR3B
zC9QBFC`tVFR=q{Kk%m)MhUk99j9Oh$zzsgFqRN*6w}e4zg;q5F1P6vy;%rsBRb>LY
zfoT)H)jHhaR=}vofsFb;BiSQ9pPi(mxVX9O&tB}Dl4y{$)qP62U;?4JErPH1=+;~9
zM}D>9hsi!$=xTBi9=E@sV{&}BM=|lgdTzgH6qJ~uP?QnX*d;GdWS<t!0Qdiet>81a
z2Qew;|6cY|e~ZY4YCRaectHqe{IpqeIAP_tYv3c4_eiU&ncZ4-Zw!AM!}pR7d0k(b
zbxG+3!N)HMewiu0*bb@-{#xzRe7i}|9OK<AUkgkjjR}-TmtX?pIVA3G%`@3sZS2r^
zKp-Obw<ts<%Z*|+9u7p#gm$!@K2}$ODPt)X!b)Sw44HINPk1v|KoM}SCHZS<XQTcM
zpA2wrl-b3?Z0`mRfH3`kM~WoPcvWkJdEtR^`D-Y>#{Fj`ekYN-QD2kG)VQ@A0^#Cf
zsAq7n3^nyc)2*OR%?ZPdR%Vmj^3x+JrOLdF#F_Uen|%WH>rGZJc2m(KpPpo8@E*|l
z`@<Gs!KpugC%Ciu?O@!Pp3+nU_wiooH=zxL8RUhCg@hhg0V{$B`?v?qwX>Sa*)6m1
zy$vNUNB4FUNIjXdE4;Qcfq6tevkN9tt&AtvyT(zkmTW}u-PjVaSmzS=m=G~PZ#onb
zKd4f@TqSU*kG?xq+Ws3Sja6%a5`@2nM-QRPc2JV|e~)H(o6a~25@5BXv*>&u$X`Je
zX<8y&Vi(2$2>H~-4?rGwv3>@A<+S<v?iiV?O6J;=7dhA~BatSFWN}!Vl$jtlu>zP2
z+A)?N-pRNdM%fmxmz7(k9br2cw{rDKq-+0C5)Ytui4eLvKEnym&a!+>iO-POV{iB!
z&E<Qb)>qUr8uax3&Ua4Ito}CYc=hsL$luw*a-=3MjypEcJ(uKtYTh%b3T;G{t&n5A
z=U9uwpxM9Qz`==(B!sM5+-oX0(J8NLa`ckc)%gmQ(i14+TJ{f|iQb-dobUkc4+O(-
zbkFSx&fCYD1JrbVvNhlPe<zKGL`w%-Br@>5#_@1Gv%&=8JNPUyANt0|jpy|?RK#zG
zI=E9(`?vkGqXUnQ$m9-h@`@~}2-elL*ZR&RY3MxqJz<UMC|^+^BMp3CxqgAERtZYD
zKig0>btM<Mnh~Vv*?kAAe{^^kOqlonyCmd1+f*>YTWP`c{vUkYFPZm(o&(+3PTr-T
z<oR@os3q7JhB2YrFm`wH!-yAzl@D6Z42~{+IJ2iAe3ofi$8fH}Dmj=Ko5YM^IvB3{
zi;5+fl+z?#NrvJlze%B~l}234$jTZxwqg}k>O^4i9L7f8byV!TU$c8TwB-2&khKVi
z0pL4r7bcL*Yr^4K<o|Bia}?S5o<*P8=9ZbCm=9M&jV&{e@%|HW?{m;-hC7tQJZ%Ka
z!Ta{*Wb9IQ@W(JD4LNCz_Eps0bLZM``xici;rMj6*)PquWW(v5o>xq2$XS0mWAbm~
z5&Uj^g`4{7EuZ}Gg(tbi_Zgo6oX5;Z=0s$6E2;xNl(`>lMWf+NK;T|=`wm_O<o<kc
z^bMg=5eSo21*GW-a(!6ax+sgpkEPS}D=+wszVdS)ox$sMmhQ<}O6RIt{GYEuQs<@}
zWbjrmFh_MbJQGN7Ixd8lg8SfHwwqX~&;Q2+MyBNf;tqv;H2>XLt`&!XWv|=CzVh5D
zxINRWrx;~A;bGLx5*#$U$}JL|vd<RF$4h=nM?@&Rp_#<ix_}xiCgi&>;etbl7Uix6
zVEKf>eI*~1R?i61QtrZ+cGLDQRybhKuN#kdgJ*2t`e<XDwJ(MF1^*)f-XveW4@Box
zI<YYuIIQzkgl9)L74~n;I!Re+bdL%BPG*9?u3vn!4q<ZHvg2|H7(F6RXav`QwR3{}
zIZu7L=y>`sfv%BT%EY4gdeSNu#C|F#96xTHNacUa;Fjpz&cfSBmM#wvIxR$f8%MiR
z7l3$DfNPRD&O5SyQ!5_b4@qWEHAjA!C95MEpn_A+&dt@hhyIakk&v#@_q|E`-eZrq
zNNFX`ObmA68#L6CU!3KOMfelh&MP!BlR;Gq3Y@g|`-x+o|1d#*80e{`ss7Sb1rQ5R
zJfBz<^xBnp{R=d-y5bcuTSC^4;Wla(vxER)<vy`)V3w&~=92|{i+M&8W+uE-J%3K;
zO*wPCaD3U9b#CE`*K6oP8igAxTkn&)zqHYUaCzU#Rm`nCmpfO$h=5%z`o<1}e<2zX
zQYzwS(@*@*6_;Yd)H&B?sSRxr4gpJu#+vb;4gqUV8VKl!envjVJXV7M{J2eY>UqGa
z=(rJtJ`5MM+9#x2i>uaUH-IT&1K9uu9lHUgRyR*zVh_!@x8Kg@&=>ZXV~Zg6Q+Lhz
z=#C@WgT`Tc-|>d@-gBY&pcT%FT%6<PWf)?lwu<|TDWD{icusci^B;*uM?am%{RPO1
zL($Y}^wrR0MZKQE*Y}5`aLU{@Tpy<!`~_iEOM9RY97JDL*ur{b1gTw$tVlxMpQBTI
z*Tb{vHO6q6>lE8Jp7r|#p?fE$;(KE%j$o<|*EhCb@wwk&uoiea_m$qQlS~xwR(?c;
zV)C)Y!$kV=$f0PEl_qTzqvU<6;bmyRF`vohX|#TeB9^G-o?8yO=%wpR&iUrLD8RB2
z3(S!y05w%7Pd5x8Bf!^LK)m%Ab3(EX7AaVh?cTM#Dlr?e7C&oj!p1tN)Oj{whYSMo
zL|Xnw*>B4*rvy_LT}^F%WuHa?OU0Vm#8N6nGoHsI;ZZxm(UR+*{UOCvzeC?r#RehG
z>emu~dpmwht?R0!U9L2<i)dyCL=Sj%Usd*Hf)lFhU;^R?rfm$nZ+tn~!hc_hDrv5{
zn90h7U;bR-t{Ce(uFzY#7pL}Z-`LIzoon6QX0R4Q!Nuq)i6qPg5Y@-y?MB3MAU6H?
z$b5GJHcpMG3MNHRr*Oasw(k+kVh{_BacWf<1n9Y>y{>T&!Z&JfeM)vERR9K$AZF_r
z1if9yoS@Gm|C;&9jv&B!zkE(?{N|P%2T9(NE?N$O6UcwoH`I=p>~=t`(Fn(3=HWA7
z3Y6z97}~M61()gWj~hVe6U`89X)B-YJEZ%^4jwzC)p@#PQ`yfiTc0ai%Ebfq@mqD8
zOPhOH;z9cKsf%+5o2OO4ptw2=vzQ>~*_@{qXO(0Lu@AN5jfdxn7hRygp7^4F$Fxv3
zWEv=!1Hph6P<>e4<MY3EXd`wA;Jd*n$M0k)Bso5ny2o9-Un3{)T6ygSiIXJ;(qD|q
zT=Z0lJO4l)wn`Xxk6D^*QT!9;sa}Qqgo5*``8li0D`7J)qYuBvxegq!v{&Scc;*HN
zoeSs_R*B8h-)l=Mo;}S@Lz6UmA^d2_PkA^AfKCk-oGHNYE7!7<=800p!HKd@vc;=A
zWo{cQQ05M!Z#Y;*DzWkGct22b>+Y*ZbL+0LtF$K<#U-E3%=UsHEBtRa$htiP+OlgR
zdt3oz?sAyq5M+PRL~@u5FY{7Hcies4M$L7<L%lxk`?gI-*SZgNz@m54b&g8{9u_VK
zOfUH!n+*%LR_s#JcM*SzeDsXxLUB>&7xZ9fwzj0W<TdWmak8?{&&Ot3F{T3~kda;*
zPT|*f?~r`A3=e9>9+uh>@VU%k*m5tKdLv8$ZvAp<H*4)WZjUN`rX6O06Jk{Krlu)m
zQby1MGkX2?bx|5CVfYhl&cLmsk?&f;aJe7HoaMm}ha|JHQz8-8=Y4-_wN$z{r}VEP
z<Pa1FF%fTE9+Gm~H6Zu)4&pJ%{CV6B?uSTy)Jhj3_iRY>tsa;fKgF+vlqbUQ{*FJB
z9TpzxAaq$={T~-#D2(U|r9}f$K&Y=B;C}Gg#>=RN=SNL#RGy+PfoGHftOASRfP4Mn
z{%fJyimPpnG&~F8<Gbi1^Ii<A@=v+svn8yP2Y-)Psy<YfZnLKC=Y1fTFaI(GB%~NL
zV>`v`CDk+T5?e!zg{MW?axu})T3F$K&Z)KSXmVq-JK7W`r}(N$6vM#sgMF=>?2uoR
zx?fBfN2~7ohnu6r-EgOVCoL)#M6YM1^&Q93kV*s$)&^Y7MS3>6zQ0_EHR<wbd!WlO
z%08`L+J;=}26$qJbeT2D<g5J)t@s4hvQzqE?>iIJ;zI|=>xBGQF|)g~+Z{1IguDfP
zgc%^Plh>GsUQ=EioE`*GTIT?F?QoA!@}|jUYtLEcD^P-~al*Mcuru4{ZCE(J!#J3~
zwOL2t2vlB9zq1bpR5c#dGDNlSelC}ZA^RWe&I?6vu&GJhTcMdZoE&>}D>{Ab1K0TO
z5tMS6R9JPsC-XU82wfPZtUrKT+)ev&--vl6vks=?msm@S=@n2`f;mJ9ZB^b8PClp#
z=1{x-)!<-;3!liHEADd&?3Xk(y>a}tu)iFgY<hemGSU>b7=Kf5@Nf>|nr|{F4j}2<
zAQ|_)+&{3TV*&*urE8q|V9<c4AAZ3u{>~3rc;3u}vC&W<Wo<2C$XpyYUIffdA?iXW
z2Kyv`9lmNmpBc{$OBJPa+?XbqPts;*3kpl43oQS=k=i%9Jm_-B+i<v#q-#<-&kZ=t
z+PA9dtz1z(7}9ag7rz|IJCddPlzo#pVI2H<vH&|VyWQ#upXahU;rO7g&yq)aT6`eq
z>1+4CuK{?~;Lvbl(xOXBwm?QHP$X?{OhcR;Sxxvin5mJ)k*airloV(}+mAz5MGbj$
zg+L#va{&NW7xp}HINinQOggHKYjoEtJIjD*ehr@vNg$1GV*|sw0Rt;|yTHi7>o?ot
zxn~vjZ_LTfqqD=8CJBl)3g%`xu^$)x3E0^)tNKxp$nhf1&Tc%1G?T~eUBpmj3WB1Z
z{`dynV{gvH811-5%4L1f*uTFMZM~m$(z?jHF_X>yz|J7hUv{*-#qnv=bVHkBh#8GH
zYMUfoQAI~X=6L_ziQMz1bChs^d}&tg+(BeU^erlODl@O}fFvOF@q$?kq(dqdY^ekf
z#f@|zX{v!qxC`Zmx}}z~&d%w`ZgQtOUsqkanks<B8!$M?9qLtgAm3y8;MgX_crMv9
zuO%4_t|hn7P^<-RQJ<lW**SV;XrZzL)YE>toCWgby%|FhpK}l>sTm6s*?z&Ki``Tr
zTFirlH=4ulPKjb)r;4#)9ACt3UOl>bNyN(;M_s~=%+~f?w~@yGQfOoI#&i2Sf1`)P
zr^rPD=gYV+GC0*F_>JyotdcjP%MpDQW?--||BL_@>U?`$Fo~%z{>35pa6ddm&i$nL
z2$IGsTx3nnEm&l=J-naiXFkd<^r5;+MJ2TUO~f6+Ht!z5XP5i>gpj!<>_guhe(kP4
z&*4u!z=%$uz`cCBc-wclmrJB<hg<D-UyrFTYReMElWmY<hZE%W!HGW*CVR@+deQGI
z+Q)7sxV0?wWs~VFt&xq!a(@`8zi%lj5>xSMb3vLkjOW6p?>L?DezhkStrB>|*PeZ`
zfgUrE)OvDiOK9ni`0E#&{E)&<X^<V5$9WiJbbnCb)h~{jo?F+Y6UDW&f9AOIODM~~
z`w$%-edE{ao=VKAB=|2m4GW}=^W6QNd^{%G(5FoVq#%WA_U}J5g^)-FfEw&|Yc|`U
za~IxQXL&N_P@cp__aS2w52<Q*OH8<gM^}kKPXv*no>6O{y8nqXKqM_(rlJc=i~}}V
zI1Z`YSTu63L8r2DIs}XHx(%T38I<AQnV`00f*Np(C}SH^S~rU#bv-LPcy*4V1)x#|
zlDCVkZ?0J>e@}C-tF~tJ%C9DCT;T;~Txj}~lu-}1mg%H3SS0%RifmW{8BSa(;p_J-
zU#24&-Ra+pec4jzR72ZSicn)5j~_TzW2_=Zkx+7Fh!|1&MxpHb9d?Jmg{t>7&{VV~
z&_dL~BVhUKT;qJ1KeXDTbabUnQB4#q=~4lG1{5j=+))cRC_Ek8Ls^my^vW;sPLskb
zN&i+6;cfoPw?OvhBlzsi$S%$^$NVvp;}^?Sp3e=wamu&rw`=5<e%f<D&;Dxs%CWOK
znjfyzN~Z`s`6`(3RK&~ju!i3s5X+X};1D<_iKYYrWB49UJeE2eeD_iHj2z(!e=!OC
zPoHs9&4ULA{^UGHDNjX!tjT55et8A+kaVbmlhf_EzL0z6Y7=g5>yoql$BVb!*$klC
z+arox?sH?rDEw}>Hyx%nesfq0Fpf&N=XEC0625t3EPist>ATMU(Mk|cy}v7rn6sZ+
z24(9kZR_l^Uk9_P8x5ReY!f!rdR3wA$vQSIp5<e<IL*wzu~t>I?iUTl#Z2I3esP#y
zn^~JHKXaqcWI@xbrlRQC#r7C1_FL{nB8lY&EzowxSexsjZABtw(spjYB2oXlKk){6
z`Osv0IrdPO+g0!B`Mv1{#R9TFVkgO61<BL1J)$sa&U4q9!ofJ}XAL`;Ly(2Y^#9QG
zRRL{vO|)2X2?Te7yA*c`?i4Goh2mD+3GVI=#jR*@mqL+J+}*9X-+ceQ_lXw>Is42W
zS!>NqHKO4uxMmBvBGjqNCCIcvkS(j=ri{J341%Qa&SpBKR+12t%wBt0_m;p+=xhYv
zST|JZd1#;OtOr4<+*~fx2w!54eh?>Wv}S>hA|ZzZ{COw;o<%&Y@#3s`1Bkjc-TY|W
z9+Lk)SGOJB{Y)B1_O%#0;>t=7nKB8d%Lrop{2KjmyU}A^t1T&q!fy-RV1kqp8cLq$
zGjhW3Z#Mh2wWTG*@!_d%8_n34FrBS-AuZ6byE|IUZ%c)$aH!|eBi(6dvaiy5272*!
zt*`!BjLcsY&k+|a9OOGn+E5k!Hx(kB;m2Yvd*E{<&qTQ2z20QY$8S{+se+%s+6m;Q
zEVEgx)<_#rvfLH#Bx^QJk0gJn)$%JBRdQUfGbsIUT!2Ln5Oxt&ZxIvjGzzgrwm-5P
zd71!D2-NE^-OEe7h(f%Gjd6+~mHk{4G_C%2wBqh?fXe!0usfRovwnzvDPt8F;9=`|
zMhx(DYl!ryo!s)1CAiFM79h39t2%Bay#XLcsx3p{q?t%lu*nCbx87F5#pRGQV|H}*
zK<9it?Lli+jf;au@_nl<hrFOj)nZTk6{|%s=rUSpWqAIc1}=G!sWn)(cABOKHL|%z
zo!_+{nxI;}@ALTH%<}!OtOB069^QdQ<;?tRgK{Tf@?T!agx|MCz~N`x33^)!7*O%3
zNuKvH*L=L=9tku&ND1Hm#j{(>AAyQ}n;)ARwCt!{YyB>N6`_IGqX89RzGn#u#F5a{
zXcwSfKnymbD0%_;{i)T(gTGIs*zfN2!}X@HG-GC>8ynuyX{PQkk&Nbcq3N#ZSq}MR
zqH(=gE0JU`#s4S=JzU2|A>@V`H0L_L-Yz4G+#oPLx^tb7cn8&GzVKaO<7<9v`c-rl
zRuGWYCmn!OcYbqqtU}TA?MxJAv+$8FPd|4=Xkq{Io9zD8W~WaiGXRHK0*hoz7=|JG
zVM*F{<AcL}kx%9^Ql1uDN~jl)V;aavi=Bz1o_+J+DYre&68|Au^LX^BRI|fL^V{?a
z{~$-pv#?+eMbd$Y8zBCanOMH{WBk#=h{Se(sl7p)=F10J$zT8DPDs_D5f2&#XWI-T
zVxcChlDAl`W!>Pl;n5L8r7tvedJq390bE&e)iq+%t}uUoBYg_7xv!#uFpP$1iG%~T
zLwpLMO^})f7)7g~E;eg9FzL|p(yN9!uG}Doe@eVEFxiu3Gkb?~qfCAS{42iLsG*O4
zzJa=e-!=!x%8dEn6y3^Q2amv$4iUSXr^Un2#Y4>c84ACR6Z2vcvtqH{FLm)9U4ZPh
z!g8}l0+8D->;->!5_1#fbFyMCEZev99S=wJPy(z;zN^}1uTGzDm=^}w1I1`HO4)M-
z|LJ1CPskD=XD|zvpp6{OF=*H$2s4YLPvKX*B?!|aTXL?O)**l7-ijzS17pL=cXt)K
z9;xs3{b`b0-Qm?v97KRiZZHLLGk)rmqF~3%cG*}xQ!>W~eg#O<K}XO-HCzP~>^IZa
zxB=si6`R`u>Y`VVD~n4Q4Q&a=6=pmB6!~xcxq7de(0QitbzOHbDtW7tiMTJ#3o7C=
z&~6zG67_(2a)9LbK%e$8kV0TP;kjZED-rl^1cXO^diKMw?3t-`Q#49h*R0X)3vM#M
z*^g)5ET**N3)^lT1f<3*b1r89v_8a{C4g-qQ9k9?TXf)^!OG%q^~1VOe0IEje&6)!
z?A%&63jq+M3&9(luZ~<8P@uBEjf})^`KX-e<Fh09K~?>Eq-^0tRiHL7;b<LPqA@Jo
zP9;!pE+j|#wn&S@P3#}R8jsKK^dx5+Pff4-L9x%x(WF-rHcCAir;@;$*mSufPrE>Q
ze)GF%0GHu^wMGKGLeByu1_pQ4t9YTxqbg2^eSL)e{RHiy@coo?VrpsR_?G%*pTel$
zs>iogJK)PuuF&`Z63Y~6+lHeFG*B6pAq(t+tD*Dg3j2PRSLc>XrT{#cWwmIcx(+PJ
zXDKyC@oX36o_@599npL)zmI3tQ8J5`6)^g}-cEkC5ZsX!_0)_XlS`kkt}+XCe+^eZ
z=YXDGSIFlr`}MQdW{m>jDg{#)ETQl(tpq(0kL%|#oiyR8D%O)&I>F@UkbympuN8+d
z8Tf10ACMyLvr1|L=0XzBMrA2XgX^3IcRQwnyS#!nb`>){fy_0_q004}v`GvM9GrKC
zq0=-CxWDe$r1MNVMdP&_6o`ybsHFdIY-SKzab0Zh2`rX<y{ADdhT(Ipoj=6;Z&=4a
z$Gj0J2l)QjDi)kP67EAIQwW|W{2u6WetXFtaDnj>z2ODl<v-`+c!81i+sqjyvCf4a
zq9pe>yBP_ZI)Z*7(+d;qxrU+~<LXN|2iHTBq}x5RGPx&c?wI0PxK7P`;^%~hjZlfB
zS0bprU6;J-X{#xCc>mv&DaPS<j~n#b$+^}&7OHRcP~JzS4dzo4ZHnVBdx|3R->4V~
zyyH1z6;CFV4W#zaK9)}zo6M9m&-d3NkyKw#v%eF>uAJ(V1`q{BdY2ST4=M!t9OF(t
zXwf#b><M#GeS)t3`0t{~!4R<JFwiu$`S}pFI?ORQ!35^2L<HQucZLPLt<>%GA>mI`
z$gQ@`_C*%ES~tV3wyjB*33)Ldb}5z3f*q&99XyvmHkPxjT$JS2AR?63Q_E<Qa%V~m
zGSkFbR0?vcJ&&wS9k0K!83~7oc~R|x%x*dJ)_$vgId!%)k5V&A(BJo;lkjCfy_y&H
zADd!>=7UhZT=JBX#rq6C)jl{v<;!zI)1`RX=(ca|w757nJZ{xf0V;FSFFaBE?YB>8
zcR$fy=zc`Mg;vtVY%ehB>^5^g?X!#4N7FC?vSOa|N|I!~CuX|7X&N$~SLMrv05mZF
z!?|~1fMFPNjFb>78~WFzzm<gOG)6s1r$b)1U#ysR&OemkdhXl;J!gNO0D^oHDbe9O
zuZG)OiF2TT&e#FiETN(b4}Xb5Iku>9%ny}D`4#Q*6x<pxgjU6G>f5`jL*y)f&P$ax
znNx&wqFeh+Nwrs!I`zHF5ISHo{iw`ul^5z^<wP}*PZ10>piUF217DNyeg;T=fZu!W
z9C|F;Mkwy0eFR3ucN1kjv8daSVE-l<@+dWvp>hsY{f4CfqCg?qV6jrMrcK4odB4{k
z=GBc4oI13(@5ZkRmKc>NgN+PdA>m)>4uQ@iV!K<obnzg&?|)QyveE|smj`j+Mt}-t
zMq59G71<nBq|qk3zRdxl>fg<q3Lij_0DQbOetKPX$QUQpEvT3ra&Vz2IVw>i$SL_p
z8=DsQuvhrIR1W2h<Mr$BJ1u^dAZNQY#!ot*TFVDFA!9wqEtrYLp5G1E`dn0H*&F6i
z8Wo_qjwLjoOx!fa{vq}mrM)dunxB~vxtUm+sIZSli$b_cgaPeQPm~q%<2EuEB$>3z
zOQhasF-MkkfLa(~>bp{5{uqhza{e2VDy-p`T5*VNUOO#e`hkiU4(9zRk$vkqzALct
z%m<Kg2*wcZd8YJ#dI|_s>`IL^=J_8^h{>_Cg0{GnIq)mWxHLk)RR>#IY4p2v*-HQQ
zlvorqJ)hIRT|_7W-DL!ngsGW_frbVsSJ_vi-^mV93N071#X_dyNoJ;#(^8u5QDJIV
zEBix-O}qHo*!)}eLechs$Zp#z=t$BudWuZnjzZaBreEe&iwwbJvA^`;z?_Ss&Hle?
z(#(y-K!x%-{d+_`0KFdA41=qm(~5@iBb5{UqWVQbI99e92|kOk&&pYZcKg<_fSp>B
z15NwiDzok!)qJ<L(L*#wjx&n*+PZWz8+&a;=)F{f%2mseGsc@G0((mfgp?eC=56^{
z=Q6oWG)!DTlmg<p@rUGLGo&ZJ=iAYWb90aI4F5#Tf9BuVxHcS$hP7Ga*a7)6Ad1Zj
zyV}(l18uKTo)UnA_9SfoN-b`4KSM^K0TIC@Aj3t<p~|7MAZHS5+*zH$QCaBe5<D34
z4<c7|yM}2m<Lm1Z^zSuxvDfKhfRcZpT{Uc)k(!$}$Pl~Qxj?aKAKLLOaPKFK{~3M+
zMF$J4+?@ck1VIONq4fH8r&pqPlJtXT!<yPz-w(CC8)M(-$kh+t0~wFbO1f*NG!_i{
za}r%PnP*_qh3T{6k%NLjCz|tFq2bkMwN5i>J6cy!9SEtWHnE}a!Ls7R)=vIB7@tY?
z_u4Sh)C=s}eRcqB{+d_)jc&^uwBjU%p$Uv8h~FtCppYz^mBB>;CyEmyM)bp|({K<X
zw0XTE8$G;ycI)sp$-`5p0m$@uKBsY@GyI^mSO#}}_7O*}AoB=?NCtQfS(qVQw>e{M
zzAV-I=KtPCXw@B9PiM<>;<vnQEGS1{6vL2A7-P~?@_(l*?w>LnQgec;O9y2ZJRJ2T
z?-<4<u;eFmMc4y1=NjY(C%zQ680Yc)QV*qNZ*<d;`Fob^Q8qLyZBEqUyt@_`#|3gw
z9TxrabXSL-L9($}@XJc--AdBc2dJr^Fdzl98NMJELLqR4!h&>nJOqd1XxtVT;JF`v
z+44wII%58xrbu8DQrH`cMt?ax^sTz)TpR&sMgKY@o1{QwVdQR-)ZJqrwbBIz+MG>A
z3l+qWlG9bcnH<e3#w3tW2sn(5sh0$B+-vd9d-k^;*7h3#dsG_2;=t1S;Sr{ep%)v2
z=9nXM-74~1z4rgn*eRxbn=Wum8{E>6N9Y7?8(7?Oa!Ql+U~>Z=lO!9gy%y}5k%R;g
zTi52~zf=FEoz|8yO=Y>KQO)y93tut_B;}2$YDrd6iLvMPLaRl!kd){4>`tK8d&{^%
zl1%1ybf1DMJkpAwcKbPA<ib7x+D=X(awY$gJAN@D!>!{f{6z-Jq{~6krt?+#yX<2(
zeHi>N2hg<al&XXj2G~WUjJ&j=TPfCigP1}wCfV{nPqf^|!SnGUGxweK=1b-^hERN*
zLXRokpB+4cREWA?Piu6PT-3esCiwztE3~QsY^(A?m0CaEKcjdb#)RUBu`+1j8ct|4
zOA#8|0o4WpdxOaG=Vw2~9f6S#cG-z1*`M7^VmJQC7M_7wKqy}?>Fcrw;axYzmVSV;
z?2Ij2RbXYN%D6<>Lh&GjFQt1rsI6Y!TY@SrE%h_3Y)zX`-N1h^9R&RPKMTw>fDLwc
zN#g2hX&7fMh#%p_G?MtavZ#Ai=T?eFXm*QlTcUhjw?Lx->EeE6;CQsE7Br5E{sR2~
zQgT6P28RjbwGs|Pr_QnYOZD3I=a}?lR>Dg1DgWc#->Bj31v;MI2SLrYxnb}W`BzfO
zm(`XQXG<IXtfDhR5VY;YXG<U?;VS?}*LJxTt)YR?Z3Z6-KmU)eMiy9=g9caumXvJL
zYh0?`9=Y#LtZbe2&u8c3tn>BiPX9hx1h4?BUZ0?W9jFar>QKGeZEID|90oJc>p?#v
zB?t;@NEFaYP7vY$b&*DyR@oQUf#ws0&1CzRX}`>Q6Op41wum-JL2kAr?7yPh8_iWf
z{9{k00X$8tr%pjNC|&2JE2=s^l9*`NfeYTUXssPf#>4J^*?8#wpU!J{nwk+>U|w#D
z2pk_v5m2Rk8-U8*>9DCwo|tZ1a=TOyz;z)%fRJ-}<;e1=O0;6W<4$@BThnDIt0KQ%
zX?}|eeG~p}@ND!6A$>0955unN>cKqe`1qW`3`sueb^i*qJOH1?R_!PJ37;8o<JWZ@
zIt&{65F~GvHu5CDZAfVNseqiy6>=Q$e*;`DAB%tU6$0^qVg6<ZrUoZ<Da7%a(1B<P
zUB5RKYUMlT`Vv#29qrw*rJ)!Ttsc`h-)4{zKRG1;Tqq-=(o?A+r+hDTv%l0TckOF8
zi+5M7<lap#Y=5+lMWwT~#AmW|aW<nBL%q=ANS2+;Uq|%(v9qH>G-ZZPN~q2~?7zb{
zr9GtevWuJkX<d7sYHn*5;i5&3df-^($?~L&`HpS|U*|q~CDY)AJkw||Vvf5+F&-fo
zvxASk%tUu}I^dUUMSV<Xp>1$nw-q{hBxx_&bW3;o%Vnk5`4bNeEDgDx<M!2^y&MAn
zhDdPqYjbATIP~~vByL2pmV|ejJ{z?`CAEIT-lC}4$d>S?f5rK&sgp3k>VX_~R8cY`
z#b5rpE=m%%a3E(Nx~0#YOzDu}Q(44QQKL3On{_-Ruu#QtRE&tI0)kmA?X0uKT4Wh_
z`hg)I=q@3aO5p)ZSHdI9^hzM_ima|}r2kG;HeM3VMI1VLffc)u{&)V-RbybxN0m%c
z4hw~2Y@e{K8!8sAz$*Yg<WKkoP<FmmlO>HadKkBLdU<cKI9`W?xAbC_(6xPLrQb!_
z#q9U}B1a49YxadzCDrhdBA5B|h{~u0EyF`V$yXspW6Z8;GoHik9^H50x1BkHhWSHD
z1rx=|9lnb$ydL*^vPJaqvoYv#lz<RD=*~gb=m3*Ie3&K=)aEX?Ge(2%yAmk9(Yn$1
zPlKY%KhVD?$X`snj(z&#!{IG)@lLU87feWkJR6k{=F<Oaj?7O(qQ3-_?S89iLlPV=
zcoO#PtBVdrpVL_<Ta?Y$DTD?s@K~#NlxejZdz5wVFMpa*ey@Z&78WSW=#rp|>U|iB
zwv&G=?K)!i%_fnAy6SYh)6aDM{m6vo7XT+AtPGVs5iCCwRJKSdl!pWt81sR?VX=U4
zo-lOuTTykyU{6h#Dis3d_|PeNem|;Y;Fja>s*pWN``SAl#dweMP<+_Ho`yH8hi-HB
zf|_!zwCRxzgZGaUk$@i0Yd@gM8q~#QB7asQ<V1sF9z#d7Z~h95(<jh}4VR4ZS1sVf
zv3Bc#^?pV4UV{<pP&Vl7L?Ggnrz>%{_+Q0tL!-lCDy**Nn{a*5?lgzgT*JU1IT|B$
zI*`x*Wr~#>9dXI_oT6iX-r3QD+f+I_5n!=AM>BE3K3O0bu6A+NSAqH8s}R+l2_~gU
zgO;4Jq4>^tAMVYXeG=E8x^e`xN1}!L8nvg(-+%sg>N7<@zMZ|8{XkWAxr$&dgA2nq
z@2kXkeDl_1jbyLl`*2=H?cR8C=d-hrmk=^eu@Qi~(e6tgE%D}i5qhrPxhkaXT`k4j
zr0aOTSx51R^EPgtFDqqHiffMz4QitCVF?dC4r1XQQ9lx);A|5z>{4bk5PIDQR}CV5
z{saWR#=qXFz%SH_MHx-q_EI`O9m-MyKq;;fML)L|>SN_5sbZD~@-0c!7l$eJdev;?
zkkunW+EBlzR)CBj#a?+59Q`BuUuGrNu}-|o^++rGsw&R2TD7`^BJOpYe?!MhER!Fr
zBtiP$*jJ+o6;Et5Hij!`+p1YHGZaif3J)!ahryOapvC{WlTTOf$x(R>xG!{|*HAK0
zH+haUNQ8th_U@bS6CeAb>{(-@j#%3{R!%1x9~CclP27Fv-M@Kod2tkQMj67}t-mU)
z8M!*`*YdqjWH0<W4KoPcmAezrb)|eLv$uy6u3_yAjqmw_kLteH|4w8Qr6+s=+emSu
z@!|T}552dJ{WY*dPz0Mx8Qc{6ebGe@JFF?|9y=6nro@rw`v?|7*0z7G;bKp0O{_vV
zB9xEApge}n@X$q>;4=<KA27WmwPnz|!%rlQ;s}$BDMXeUHj9}FFy)Tt&=a?E`raOh
zyfi)v0I-hsbs5YK?ZMV}39{VlQmJ$I_Dk~Jd#t}m608W#v4^luz)l*IL+KH6C;@{r
z=TJva$+2+=FEA8T^hOp@&eT9CZB<foC{Ba6m8>l>ibsL#;3#Nv?uyelN}~lhofBB~
z%Y4BIhN=1fe4kc9fnvfeJHbpDR4PD9RE>8m=4c0VC=D;S7i+T91%M-?;@IFF)Vcg#
z`kRmBG1|i82_7L9_ATJ<TxdD%v=-~dLnjw{r|wIiCBql$T-7{^(}=0`We{vlV1hVJ
zE@498O<@tkcrsw)m32*o$LFnyhC_rua!Ac@4iP4>pu`-`DYzy56}b0#-S*=v16J8g
zQSjxus)ibBb*O0NKKailJ+1jvxxXF{8v48+w@SC^-@(aCnG~AC!&0#fKxXEQ?QK30
z1|9qj?fs5WDfymolO$Q%enN&;wC3JJ(l9=#22#*j`4QwU<kS%cSgfawL$qt1J~pea
z3^+QsRc3a|CP{;st^l$|l4c?;KK_3#08Jo?wiDOkZCb1g+-yFHVPqJq^We?<<Y#Au
z;a^WcD+dM^*MMg8LbC|nS8Mi#<-Vy`a`@g1Q`1=@UyP`{08%%y&h#?1I>Jp+?2T4q
z6Rq$N-u{x&CvE9P!z{3$7#}&FNXi|Vo#IWNd9S%khRX+JlY%pA&J+HFfsqX%kBfuh
zfPmWt+?nzt1$YW0U);K;xGjAvqrs9H83M#*6%^p`B+p#*+0MgjD$=FoiD$Jr9@osa
z{&(YH9aV!%<sXaYs7S_qSBTw<!a?s=dxcbBSuoh=*B<Zp1IH1w-oceScOqLwKAcEX
z*K4Is-u#zC<AJYTCGVU2=#^#f(!JtMgUnN%m|tsb#5&bQ;{R2=_jzPTd7^0vV<CN$
z`%7twq49Tfl$i7{r8J(#{H6(d5cM&bG07b*!7$>F(q;>E`D9nyUfRmd$R@Jz?Tr8n
z`?KSHCcV+%;NbVW9lop`nC?FT)UI$==j~{FNpF#PLwn|J#0dv~>{4b74X0g%)osj<
zGt#~@5WD~hx3wzx<pkB%jnUr-+uQpJ8zgQYkXA@@c6DsZtv0$`vG}~pG>`i2d)6A}
zk3Gqfk>6I`UG2EqxDP!7HpIXuhn^*OubRvDe?^}`CTEjiPvLYd(HEGO@u%c|6~1gh
zI(rBGuhU_!?w?@`>z$Rai!hgcKrNHy0RBp!E6{q%R+6<QDIRah);kWnl$i$1I2B@3
zYP=(2JalYz?e-YEq0{S%_iqG;e~SHdAcgt#JU^mz+<%+j(F<JAgBr2!*PK7HasQ<s
z)>;$7&gtZwSsgxc>}hWt4E}<p3WGd4M{4U}YN{20w@|DF&x5eR;eF3q=Cn2+aDJ~D
z(kh_ESXeC3XF27|vzoGyv9zSxM3_?$r?w_hXe0R$`LI?JvW9Zc5pS^Q`fq(ogsrs&
z@lGpi7pq}#cuU+6byvCq2D|ntM6!RP@F6&!qRVDvy$~^OgFvgzh7j!4x~F+Ha&o`9
zlih0m>$G4mWAO)b1}hINjN-g*xdjjVkWy2Iw>;yRSv(b~@AY5ihqcu3CVV<t5GWuF
zd9=RZZ>FxSR;SY?n)6|g$a@-tgc&^we8(6ej@A?n29m22E+SGyQ^M0l7HtvBb>75A
z{zJTH*P6~5l_bfVJP=hLx%;`pZguucCnR~@Z?CXr;M6DMUSNgOVf>%)LSdXxSd~c<
zLLE30M^-E%VpRH5p&qPyUQD#Z6hd=cDUEOvmN(sMh>t&2GNvyxSGj6E5`CO!D_%uZ
z2n=O0Yv#7U!9^6c&2z`l!n4jrNs@KfV@M^L&sY4y)BW`unZ<V?kU0XTU@K+D2{Y+|
zfVGS76E4?`*(AD{GvC)1b$tBg9|>4Q*y>E^g<_5Qf2d6)OwfkcU0A}OAH$QlTXO4U
zfmqKi0s;R}6-wFKwTZM_(Z|^aj?+w*EZsV27kPVH<*|XR5vY?Lzoc?ZD_$YdQug7?
z8+<U$3S?WOYkqj?GR{jTmkpl+(4X$Ui9AT?YYfXF9?B!Ai|WL##-}@M4;d*T=BV+N
z0kGAbxj%d7$tZnZWI!V!`|7Ptaj6Q5$n>qxwyR%|`CAgQ-eoap5yEk>FE(}|OBD$&
zL<I*-Y$c&=Yo5UL)BSEEd*A#S`IJcfl7l@{kLz-`mBkaeq|r9kVQEX6W-;apDl+8)
ze>?*)?5L3TgdH)yHzSgc1X`xfG%M75yxV@J)zu!_^RRR~!>LyJkX!rq&5W_5WH;*o
zT+GB_3Nqp9X~ozGVHg4Ua~X;p4Nz}M4$2cRDN6!oqHNkn{0})Vt@#f-OJfANk7)b3
zI5;hff5^OZjw}731c3-}l$r`=xE<W48=jdf@05pqw0NE5Eh4xgDGcQM*ZP{JNB8K2
zlWDj$ZwMn+UJZ(A8AzKL;kR#AjZgQR(bdH6FB|UZ(;*cq+wL!Kga+H%)*%#o;3w$I
z+@9h+?<Z^CQ!C{V>vk5h`x1<ejgcDUzDzZZ%z=)Ssz8z&^>k7(SGgTowt;rk$lD6Q
zq&umD{R27EG#O_i{TyVjV<Pah;93S*`tM6>)eyE_&&%fssE_Qogr={r4*s#>>@nY=
zA-OrH==n8dvf@{qi~8I#T>q|kVG-AMu-P&J`PZF?LeV!y@8B%73}n@ye0u+R-%~O*
z!Jb*t4@LulTxQasLyozVh9RL^kc?4L3zMEe3-|>;TokJNk7E7b5wXax)eQ9L4sUZ$
z`no$%P@fOT-2+<9t5|EWneJXk*!@FsS_uvE8v)NFkwFoi|HXoj`g}VbR^2g;sTiea
zb?)?6p~IPwVi2fk0J1qqZ<!t#TMXSM{M7;LMOgvZQr+*)l%VqMeIu^AzriD!D~E|!
zzg6;wnKqpq8<`~a@ryF>q2i*4EPgcr!TcL=tv2LDk=6IX!)V0V*8w(7tDq1+9_7r*
zo|FdRP@(NoMNrL=I>QGfm7{=)bS0~Q-v2Ie`L&V$v(zy;6X|gm-dp_2C6mpl)D*QE
zXEhaBZbZbt60HIUYCOfY!`@yaP+}a4=RI!`t3U(aX9_ipK5F?Qu}P=oo1z1X^~c}j
z2j14v9GQbfWy+-%NmBN*3K>UVseR3YJzV5hccWfMC}oo5Gng2`xJFb!R)`bj3qkvt
zxgxAAF^UWr40ce$cF3eJss{AS$aAZ45qGcHv*(1do^-EFJ8{f_NR*^{xjzis&=Iqe
zq|wUm#NDPS#id`?1ssbCyG^m&u>~A!0Y3pPU;f2!M1L6{HdkePLeGjteFw&*b6}fR
zpu{_OscDf9ZpLp-7WbSzXt8<Urx%i-inctPZw(SN#^kdU>oh^|auHzQRmzX^!C*~N
z41ba72(D1@++opCN@}H`i3#vR-nUf#x!W95TPi~PgPD~o<J}J$H!ZOUuUZGB6soj&
zWb5P2#TjO?(SaUPWI4{CgRK~Kgm>idw{1u(PLYMGH!YFYYE+F#ExD+AaZhW-D?g&X
zv(OV_V`Km1%&?ZARzVgz16aoofTNp~|0+K0<+l;2`rf>HK8g9Ul0WD6gycWcdzd+V
zPja{Z>9%q9=|Rl@DA)60J%lFOsBsqW<ydts-toD8mLWBYYZS*oqTs%^hT$n~E@E0{
zmkEo_o`Gzl^h`~jpj)1L3yAa-cSh2yk{$P#a|cNEStew2#A_6Vpd&~V{Z1L`+6`TI
zlU*xDheMw;dj0c%7hjx8ixldp!np+mxId)s_YaX=Ee{NBzLA%*rrdh~w*|R^br(QI
zVqyFXiC|o1=xcV+-SMpbCh7Ie&ZBBJw!QWp3?BFrVOC3_I)p8vn(vm3na-rJ0`H-+
za}ltK{+;d@0FIwiXGrYnPXAI-%%44OQhOGYoeu&--fe|Q@w9|=HTnF-uT=#4JM1rq
zT@NE0{>)5!AS2=@_A=~%`s#aE(U*hQ^+1P9aOZoVafDeMy#0v0=q340N(c$lnHYnS
zG+NybCR=G@Q;;i}<Z$=`6;p64GY~sb2zsT8s~t#b^ce2VXIj;F<$b1J;hrGQPc=RZ
zL?PkR39BNP;mBh&q5-EHV(VOCZ@xHRg(<|eTv}s2DXN|Gq(Fa)BZ|M)mj-R<c_BM`
zSi!a6wyoy&JJtw8*cMdjLBxW6U^HUqYU@O*q)7a)*`(}!{M^)b$U$|_mB5Fe6rE_F
zfYlsjMHa*lRvSJ-4njh;+<l_jd{+Y--$>5eEJ2T(VdBWpTcAK2l*AZ})D3s8^odv)
zjTGj#ZGZ{l1RoSK65&^t5s~h@>F;|BD_-|dnihr6=;9^mM)Ooo;eYAH8sZ0pdbWkl
z9J1K@teMb;{9V$XeD6!N+_ANeNK}wN*Uc91{d-l;=H|$IPVurlC_Zx(vj^;!o2sz7
zB6=7gd+;g@soIwSd#C)tq-3pYJ-B=&5R0G?y89rk*%OCS9P+IL6D5+UF_g6|n4YBU
zDzVgKJBlaOy$uWwwJ7+2l%rd$KAc!to$yCN2;rXzG2F&Ko-(Hmve}2;);HPe>hEOg
zExCe513na@#5Vb3S2&`Vtt#7(3%oc{HvCZgctG0l#1FXdqIcQ{lc@@~Mo~PMvJaD^
z!@KGHJhT_`6rZiZm=e2_Z)vhGA@hr;csm!U!DH1RikX;P`vMn;f<y}~gFzrHR)6Vf
z<c~0#(jHbQUa%YIpB-DBojyi}AU+9Yz##=_oV=1X&1FlT|E!Z;eZBIA?w_~VbPk#H
za;yp*nR|UevX@n6Us_?FaNTR^@gZR&8SiW9GQYGP5Qz&B3-w|1Sy77%jex`B{jX_E
zKlx!Ov~C!?F%rklO+5?({(#^9XRy*xRv-U~3ItL}r4l^7osk3POpIcN<GKAfZ)x0V
zd%t58b{9C4`(f{1iSxB0VyPnP%_Pj)y*>E-G5lhfuiKHl^v@(bhxSQ@!s4f8o|l0g
zqhsDU{y8%5d!1<NK|?nx6+8B=A~9!hSL~*%Q>6aQ`)uNjP}D#rF}8|ABtZujI5V{c
zddp>#)9bjmhrtBO@g&`y$uuwY9jWv!A7G9|1t{9;bUHhHpo?j)x}L|Oxjq8+b&la#
z?(<|o>b)3lz7INVBnr7bL?}F@<r^&z=^(afgIPTW=uge%X9W8)i0!1svMB(2h6)ZJ
zvPrhjy^OA6Z4rKo=qObo<X)2Hj-1)rwj5@!nDM18DBU*tHw2_$)Mc|x-*fNoJNta_
zoR;tPtT*7AFPD7!EOe9Z7dtN#K)P;e4DTR+y}F?~NUPyXnj_oElO%n?j)>mEYL10R
z&XUV{T7oup(0xHLK!(ct5jG_v!q@Y@IzmQj?X<`Pk7sYpyHws^Of>nLs#2VkMm#!C
z-s_e(c;`;+el!wA5=NuJCOp3HAzb~+^pdbPUTV~a{MGrig{%TJTBr+Zk^sNOG{Hk{
z$i<wnvm+-e5J>!)ii}QgSK{a3cseE8IP1&Y#wv32)E^s?{3p9MzaQJDV}fsoQt{gq
z{@2QW^7t^9cXNpSEK=BWeS#fVGSz=8g%B?4+(c`WAGu^mLYzq*^tCb+$l6Dczlo$r
zA)P!Q)HB<)<=PIJz%gKBd+q$8;yym^4-T?^U2>Y+US-~wK0zBk?1?HcN6PnkSd_}?
zFe?sumaS_!cpM38L81VPETqjOFJO&qQJ^)lM!0Rs(PCp;Cc)C_O&<cG?ubl<{tQ`8
zBF7Rgs{aR#==BYko$PDF(@VOx)77ziusW@|cTr6Kb76<`#UtZFk8$U+&qnFHiPnaR
zX3R{(Yf!_Yz2^|NLjhkFA)b(dnG?m0u-i)ZzqePr%+;897)o$bz5r_75EV8I`c}ap
zf*J_)Z^l9=M<xe0vU0Hlg?cr~|LrCHU$i7Lkz>Gu-yHn|e7wk|tlz<U$GZexe4jbQ
zc0e)WWRzi0Wu+mh%O@%tf&TnDBu9>qP7j)c(-9S=x+8<7dQoDl6QG{etN!P2+EPtB
zKGwySCm4lNvtI5nftsq3$87q`ZrL~qPsn+z+vwq1<SyqWJvX}9FzMij?KRqkj`uCz
zrnx4$+r5i-J<>GPj2C$@_)RY-zZkBZq+=nc0Vf!~mIs{TpSPXlQMi2<@v*=q*XH);
zfc=Ra!?|i$oO3Q7A*BCSeiwM8YPaBeb`-z@Qow}P8W9Z1(AX|*;>3D0k&py@@T#vL
zyg<aW%{FxFIL>D$f&Q$1@grYz9!IFeyI0g>3{qUke#2->3p{&w-7L`QMHD=5(ukwo
zB)mep+D@fCkEQw}UND}k=R#ApivH-(xQ5g?D2jrO{Q*i#F$HHiQIIS`xv+A<vK*65
z7e5>iF46N_xsA7O2?nEZFh4fg`16o_oU<)`*4v)Oc9ec9B;v-T=)-?TLDlAlj0a24
z!!>a9-z~LuF}0>;?`(-<=7UQ@cmJF=2u-Z|fBfSE%-VTv1ohOfN_N=GwtuRA?~%uZ
zd|=PVUX_`mFz~{1!#u?ijO*$++SWRCDr+HkTit`WiL^S$UA#wAkr9YzM&g6PxCMQ6
zs7!%b&I#6AA_5nGbVQoeAC56z?T;%M7G}SU4x8!Bf3g|qIh$4_YPTb8|B<Ik@~h$0
zk#I*qt6b^N)Sege8X~rIL%y}ChePiXo0MRuVoXHDA9^T?iz@D<LH)60V7FE{La0Iy
z7j4|$cemKlv}((^Vki+O-+voX^!8^cmGt+8>pFWA`&kkB<6r#}MUinGahR0?g9n*T
z*te5hv`-76<aXwcFns&Vqg3ZOe;eH*%!u|OgCvkRpVbfxqW_s70Gd2VtKsu1IDzgL
zb~KBkvjJqS|3U(K{vL1wUf*N>)}8%~oA!zQLI1>)-o9J+6LUFI`)4o;KKLp1?ro<1
zpHO{E-Uk?DbvOke$AmMoD-J{K00+HEMslD4Y{N63>kB5bE2w!hGQ!%8XtRVqR<!SS
z`lBSAfgsJbo;^u4^NWMpEq#F3hx9tWtB?&Z%+?Jq*ja$Cu7l~9A2E7!gSVylqE`>!
zUe5EobH{C<9%w$*-uL(;+C$v?{zUIa?fRkoA}-Q<B;O^{Ahc9y8@Eqbru^b0<nMgg
zWj@&zOM~=r?;N_f2y;<Y6fh8AeA6ux?sdbJGYbFj|7OZsY7&2A*?4o0RRYuy?^S$S
z2|cq<Jx(pAu!=6G@}8MUb#I!;j#!y6+q=%6??+B%z#H?&nB>5%BuPM;4{6_(Pct>v
z`=5{XedcY$IEBdpfbnxqT;t^RGjMcBL}%)%KV#_!w*?cA1z!*Hj-zn3yf=jnd!>P}
zvy2&P8c>lW7rM&#nL~5w=$Hh2&(utN!|}e0fKv^VP((pW+RH&#X3wiw4ARV67^o1{
zUXvM7;d`(9?C`NSQcLp2LbtslOI<S+E#kaFH*vk2!pk6>pB5k(DE>E(nk-c)C0QN!
z*EC{UW9(m<p8u{KbhY$*sX9)pPXf*}H5gn{Fjj}g6p>|mMx*zDtitA`TD`ataIZS!
z-RKjE!u4-1!sF%5xubc@3lkpr6k;FlNX>wm{vg$~MWVQYe;%*C`N%*lS0Ay4iA_7i
zGb34sbnb)LtcSL;va@KTWai@ow-SrOO}yhoO5Fwv0x{8OHx+;YD65f*Tk<1*N3g_f
zvI=ru^|-z3WUR5@LpPqU6(6tyE)iXFfC*VOVLX3Om|8|g4xvV%$;5QXlv`=LgwhN_
zd*=&|gP<8ImOjuM460H(yP*?(DROsc`qR_yv;+WwH2O-V${B3>{bIy#Ud%Z*`1mEL
z9QKfAW?L@aL?b_h058a$eVPiXsi?H^;)8VWl9Y>}W3?5*$o>vH^tz{7^h7ej(w*jj
znYck9D@=jL*J6#Y=I-v6?;aYcc8;nh=C;Jy*`F2{v!GIj;7lzr7y*U@0mxbo!{3mI
z@n1|r?%h#k-5RsX6R+CYtWnhG54cA7MGHUG(-IWRN;i<uL7%T5w38F^^$rVQXl(b>
zt|q|=+cigC{9Jn>!o!joqQLN$eC=aDC`gO#n0t`R8_cB1Kttr&L<J3doNj(tlTK4r
zENv-7P|s<5{Vx@@$mZrgc9p(nj)@+k!UP?6xXo`ZbWY<RfPRd}yt*8boKU|Z6I05J
znPf;~0ior7T6R{>I4VsL23B#6NpMIG>%LjGVvH6XFfO~Qg5ScDthZ#4BO@b~m6Yt@
z=so<c^y%jLtm?Z(qvviv+u17*J=H^P_r<K}16~j(Bnm(EN9YbcF9%<1q{dj^@-bm8
z`$WM^Iii6Yet1gG;8d{oNZ&_x){FO-UDql`87Z%;|LpqZi1y`7Hm?8hv)FE>ZP5_<
zMWmk}9vkL{E&dripMmh0_W7b>n_64AN+Fq8pFPED7k+N-f#CVoY?SH6Ph81<i*0&r
zY{pCDj96>8jD&JzD3S$t`8laywrLR3N6Yhf<ua<UY&!%{NbDNh$0H9i$xIor2Xo{o
zU=gP)qx>~41#f6juaAI=EK1U>w}x4k__;b_s2j)I@B;0#7Z-E-mX}%P`M%UQ@O&8C
zlZl8x?Sr}CD1(!G!2F|E6a9SN0eSpX^_;F*rdqdos?7ZGuaVF6o2Br~&OvC(ODEN@
zD)*5-_Lt%4hewKTl8b<Q=hHpCQx>u!CbRy~e%(0}A<@>hP@9puSma0=s*yEBp!{~z
z){vO|(0meWd7)W2;#WF@l#&5c9jHk|1xcDTTBc`odgZDbK6J9^H1wXThdwG9%-TWx
z*7odupw3O2V48IKBQcpY9PI7f<aH+6aC6k^7D;gAm}b$C>366Ne<5o8DCE(y<c>m;
zJ*%sqJ@oGvryU=^fH;`D5`kGy4Lf3&&Yj5;?SA7O+QGDd_{PgK*Gp}D1zijMc)hq>
zNslk(zz>yTq*xKu@m@;3|07!UA4ec>_d)#K5?h)Y=npyZoZTGkenTZ#ABmcei?Y)>
zKdd_4B+-25EZMJA^TQLudGW`Llkg%HdFz8o(fu795rM1Q@lMSYl?5d{Dww`a{H6c>
z$}C#my!E3o=JOSm(-KN(q)%xnv*vb0X2kThua{UY?1Af{Ks@faKM7}L%0uVf3y|gS
zvf9H(Y{pTy|2^p$z0pK|XK;_#an&Ep$cP9WGs4b+9GQH%f}&7B@2&;#e$4|#cE3fq
zwQ5etbAj4%Yi>aWDj!>tWM81mgg&273-#5%>}=1+-^wuUX_kaC{X?4#+s!*xO*rx;
zN^BA)ZFqF66vd`w`TykuCBbtn<<^y90XB(;nT2tBkEV68<#-fe)s?F>f+bt$OG48s
zufd8NO7A#4kI3FP-Xbl}2zQnB@!mr@>qAFo?>*F9PHen2f9SVEr0i!MH!ZK8pd)d@
zDUV_WXK2)e!6|%j^C|@Tyl|~N6S*DQ%^sMgfnO1H<~hJXmC*||JjCU|Uz@G72#~ie
z&ygkcbva(DP}sHjZa|>;rK=+`eo}@NV=4=RVL9?vFTfDPR_R!)>f6<32m!}O;LC&Z
zDV>FzAnj@!XQ@cqY6974*L?!;rEO^*pA>2Ot%CYPNf(C6vPYxK&ulp}r6qI~C*Ywt
z^6Q0A<l0mx<s>g<%vy)rHa3c{g9h(V9`{C_17&gRo{M>6K!51C?dr~#Dz&Q{dtpx_
z1^Y+4-8Gdq+E1Eh4d(us+#P4VAx)u!=Sbb!h68~g0q<K;Wa2<ffZ3zw+(N(hlt8LT
zk|;?j*F?rEDf`NIqPE}d9|%#ZNjsXaLwBl}X^C+-aQL6KnA?8OsSt!Alqg!_C7M7{
z*~EN07;11?F&b=YVityMuTp_=cg1B*+gC+os_k2#p?vj9UrnutT?UHp3~xIQ8GYLp
zhAe^~t;`S852{bKOPJ_1SBvl`X?bJiS&9^lZ6JvxMH_TFnnPuoLor0kluD|b^P`{Y
z8x+tO&X8t!sZy`zIKW4~!HbxGy$fV1Y8^sA1Nq$nS>tkYq{ak*HV4|@K=l@j=@dRV
zVFocc+3cn<@Qubh9kD_9zqWA%+lVx@n?}UJ;4y%;xvS*|7!Co$0WALmfzE&Pba|c*
zA7b}6L*r70&;8rs6QAv$Gll$!OA)-w<39CO_5&Qt>?QP`fPmP_5Sw1!7S@@s%rr(a
z(>&O^KDIutz#kojuZt~)S{b8w3=5SUzYnE=dvR~3vDuSsjI^ImD>PYFokw_B*p$V?
zGA4*<{~U>rb}c9MC5y2`hoF0&eN;Wf0wa%BPz09e|67{~f=v|v>{F4z@x_DGAmD@x
zy|BmWQrlM4DO;lyQ=QpXAdkb#PYt=~J>UBYl@o^z6U9OHtgDuuyrQ9|022LhuqQ`C
zQWY|8UU8fjkLYkcPvU4&T=@<iFA#)unkQN_F0a7vc^k=YzA_(h@Jl%iHYW!GCWBnD
zo>YW4{JP9>!QT!h!<HSs25-Y&yUt($`Y0FeM?YXDKd@x)%T=?on2!I+|I4BCG4SiV
zrBk*obcKfL+^yrs*>9Ws`b{I!VB8Yh41O+(m$jc|h)9+VQ3W4l&)eSFsu`jCdA=<>
z!92v{WyFQJHztoliq#omFMAx0?0D*1D*exDZQAX~4K|(<a(VSod=~`pU<>v;l;wMA
zk2J9iBeUp8Qy?L=+`e=ZhB(Z^UmB#8+tE(h3mX>P4-qg*`TvyP09wg<Jd1QZkttNg
zn{n#gCBF!qmi`?Dpm4m|pPm1*LnG#tl*?hPF`u_HAE?+qn~d2XlIc2AHP$@l(S*DY
zt(%ew;6Hp>)wS<;Fo?&^p->kHt5_<CwTp>XHG^Z-<qu(VkkDVpBynBdfg&`1U+C?d
z2;3DO^F=r#^B+e%%&JVcDh_n6T;ETw+gcX$H7UtNk{ujKiB{b!1cR~!zP~P}k%ljF
z!9REXVeFGP0T>||5W)w7X%o%i1G$6gB|7Zk(+UHY!fUl;F8`(n0<;Lf+&E-o3zt!3
zZMaYweX(jWMGmsa8zW5+siVS9F+$*OWwkTzsun?~Qkq!(pb5Vpa9SJL%TkWa!tALf
zvBEjMdfW?m0#+}(UutzT%$YE(qSQzZ$|V)~&gME5hIsdfzCVK<`$NO7ffAe*Ygzl+
zj04W3y19pbfl<hB6OAqUx{k*eR!R!u1>4ULs3=W3^Y!a<0lor8A-yyT^&%H4<m@CF
zIk$E7xN{Hxhye-I21hN^tMmDP`3yN>9|C5wU}D@!&T8NC)N62j?bXA<wzey`j%T}U
zK2Z4Ob6BJet!IqMRGXXH5#?po+u{v^UE%w{S;Q=&;9Dd<4=jI62#xlPrdP?algYOm
z_H2EwaR$bmPln67TIIgj^BMiW(Z(senE$^P04SeQv&>WBTu@5KqWc5K3nj{Wj`?Y2
zJ~4)aP_{i1d5l(f&|X$r{B}jn-s?oQetHJ~n#tO2&A@2n{<lcTeVnnRvfE4=t?&|m
z$h+;HMCZDSC`AFFI2sP>M&O1Ajm_sD;xl;OJYu4Iz$oc`@dThEJH~W$-vy*Nj2C~i
zYRJ8a3;O#k);e?$)n<@$kuV32F2Pz%!UGk0rX0)9t;765P*D>j&AGVF9^y|i0Dh|k
zEJH0KJ~Tni*eoDK=cY9f=h>2c_4+jWI|_U1vV<r+Q~VnZ2t=%0qvUIggP~*DlVsi|
znr!<%dCj`Jj)l1(qedz+5^<?b9x>D$yZPp8EW|0QaaX5mc4s+P+l5>E$<4s$cDUs0
zqy{UU5tdpv8N2<Kao!7ex9z@H4rASpbw$wZ9)_>ell05>nCgz*=K$K%0n|im=Zr|6
zzeArgIQ<D+hkHg!9zJSbaUt-Js(@3z>rch(NQpgTcD~O*ksmZz-<{|Es}r$z%JUxT
zOrg_=Fs7hg=rXaf>F4Sim0p)9AtyRZD1i~dz-a^T|N0*B#fkEhtiFUKruFc2x*ASZ
zE(g57=tz=tj}(vg`7~uLBw8aenI$rUA;q1u47+@j$*i?KRg(U94P3U+g@3I#i9|!m
zjAQ(YO8pj1;04h+PMlEWKVq)2RCBZ74|~}F9KO_rOEh}1SlJQwpAOe1uf+b&Z#~-v
zmOL{?N?ShAJqMaYXc^pZVx*j+F^pFu<&o@tfOAV?=zk=l->-Zy_J8vC-E_?DolkrJ
zgB0+bJ92sP_9)~ue&nQRgl!oMcv93b?%@s5R_r>Cc0;H&$P8t1D*6EJZpVv!4osSq
zcUTY_F>5VVpeh7EVy$Omp|8@pTdn5xUAy4UlVcIY=Lzj>k8pODME{xAuAv1Lb)J-`
zu7ZdewWvKO=zN3Sa(I1-#V5cJspOkPrkTjMfZ>bTW9686EmQV3RxO`{GAtlVIRkmE
z@j&>LFWg0T+h)gF#|YcbM*bTiIayChjoyT5sA|(8tw|xsXaw?r@MWmZeE7jWCUU9(
zvezU<4I=j1xVyEwyzFY^fFLV1K?xR*FQgmyec9?7pFNWpiotNn0<qe7vG(uHBR=0)
zfy}l$qcX6!Zv0Rv4LtO50)iHA9>$+wWgw^kkS$>@q%lxJ8u?+a(}WylMHrG`13xEk
zDh=gJHRjTWx{OM;D?L|98}q>hDGa0uCfFx6wD;**5yl^=%bx{G5D=W5sz>c3`zS(y
zEH5i+w#;(xwxA_j)q8WC*kF|6*nIw{538RIHJ9J!kD2_p7Y{geZ0K;X2!7sEQmXfV
zOBwtIeX!nPbiseZ%m3JP`C~z<G63u&ULN&fABwz{cQ4l!u^G6<p8&5ZDc6k5>Vi2r
zF2SN*LX=f`o8F+WVdW`QFtZE~P<Ac2m8xiF#)FZ76I#9|4RSCWv{AU0qtGU<T+su`
zS(FZ<0@~mU=>9|R<ka;q{gs)>;c+at3aCAd-hE!B?#Z)P*ChMv=$D?;FGYGn%#oEV
z`qmFh+(rA&$`8e~J6nRyP(6&^>={pKeBy};YhHQ#hw;u|BL3|rHZZq!xKsZX_0ZJ0
zJZ~6(SR5u>-Z3o-1p#f#qs!C?RQvi6vOIB>4|2bTOM|&_ls*+`h_+c{Ra!Tc>G7J>
zPss_;;bd&qvjA6OnZ8^7<w~fojg%=a5{WZtSota|{?$pao{wVVwGhGlR213uk4HN7
zM;&#pTOIL+Q!ed!m9LJi<!&iubF<n#eJw>BhAGR2nxZ5=^ahZs-9p@Cn4C5|)*pYu
z-D0U9A<;?oAFlyWl=bf0Pbe~|`GL2+BXld3{?w3eL`wDVeY3L@x?%E7$eCx3>TaZe
zD!&;GB?75KeXeyRk~fZ=Thko7X0UXxt6U17tb(#;tP|gFElB9kKklF_D60zxuV22Y
z%njwmKp?V~7FGjeo3r=MpEY--9(yvt8qABqVp2uWOg}GlXBYOwR2@@lL1zO;?3c#H
zNc<$laNML6dtJpIEEqr$YB3iU0*zjd=oQoOG0C#|SMIV5>%z}3Q5Z<n>H~~N%K=IY
zWKzwg^D=^#wmU721Bs91tV%xZl_|adEWu#zcD*D#*7A(Xuu%Js)$433O-UztZ#gy;
z(+m{k^D)w^B%Wa269Mf}NXX?Q%K8|epexzaN|bhCacfPNcErD;Elm>vx(UD-ehc?>
zeO2V(067jec4@7xz{5bi@$&oU(xOmHdEXmgdc)7(C>p=&XwooY15XyLE`KqXO`m0n
z>Z2I6bBF5~<%Y97d3Pu^Q4)W?5?kY@F@UHfO=l+*&~=<3_%s7Milh+_eLDxZfX5+F
zUd7s`5egk>em-UWEf^#Ew8`mqOMtZ;32jF97Cs+Q*k7hzf4ptoyBdLAA91l~-j=^_
z#bf6I{XPK{wdH-C+|lr0`YXC{h9W$tw2w%y-6S`iIqO(#aBgC`$1u-V7F48a2Ecyw
ze4E3lc5veq(i+}(cPf%DJK1cUVxd0Z`>4@J+u$~uw_q$5xwj{uBm6VWyDLPc3{q=p
zW><}|!qw2mA4<aa9WIFzRnq-WTwnwat}Wnez(@#ehebN@sFa?HDyIvAhH<dux|6Z&
z<=wh9ud>dpccWllko-S@SSEa6SyL^w%Q+i>hqu{$Bu?^%2QXNPR7*82%RNjbGuXMZ
zAL#id$)#uwt~%UYPh+|;Kd!}fzI3`E|0olQUP~kC<uO1!Vr-u~@OT{cPgK<*e|RPL
z2)u1tBpv)~57R-=6_zjeXP|pWSn8YrOC9OZuVeLf0R^yI1VVi}Poc&P99#w=v+397
zTx$bxBv(>LlQU`1-X01IyDE))jQW4f4<ME%z4YrXPYwH)q+gOD=a%FGtK*`8s$uYe
zh9b+7Pp2Dn0>Gp2F$dI_CM$+RFB7so{_yu;!E)=Zn%4LIjR91neTfYmDwq5BTN=vp
zp`Czgr!nF_PS`+Pt~-oLK_JWB@@%F_gX<syj(mo*gaB=+_&AEk&Stw|X!7(NFOW5?
zM9<#zZ5Iz(t;3BonOfd5q@~51T7JW9`CS$iG5UkdpnZMt)a`@*%1Y2m>k4lzdvh3o
zNZkb?n0@gpGU+YPYXrlFo2tc$3Rq1s30d^}8&{|I<VOPoiGja@6whmr=t4S*hZI8c
z{(`bGbuADGHApdBO+7WVE4y}6JySxwaM_`k<|qGQ*s)@L1Uo-06~A*yE2~JCDoP<^
z5JCs*Xz%9V$&Xd3|A(fl4637Px@d5Bg1cLAmy5dvcS0bz1a~g(5}e=`AV|>Q7Tn$4
z-5tK=dF%U=Dk@cbXM1OQPM<#A&40USc9tzAtDY=jXCzC9Nuyhkr%~hZJpY|Y#FZG}
z1?`l~91mb{Q)2U1eispw06MQlTe$4!W2n<6TSPrb`Ox{89zPFn$O>-SQu;OIRmF4!
zz!RWH<JW;;3~sS7IJtf?VwhA`m}9bVRw5jKEO@F0%+G7%V7q66?`s4k&=njWH~^d_
zl%+7^PeJ&*rfMP?PTlG+7W(s&8l@|vK+m_YJmxo7S9bY#(r@(|Csf+|R`OgdbyRRS
z;Ey<uShB9V)P&4q+{&gyrKVl*zg<@os0CM2m6>pXmr;NZFD>O#P^{Rf*E8zfouvZ4
zgPGM09pMtwjUuSmL;%z8e9wMs!^;8+i}|Oo2@dJQeuhLu6dj*<E(|qFz;O{VBnGv(
zEkeW#sp%x27-_|2ka941-0yt0UA_e-k$3N4pJ2e{$EZfaPbyp-e#UBGJF&A(1V)ro
z5Y=wckP%_}L3!_KA7}uW_jAYSlfa>36~5)FX5-cL=TZrHQPe9zw3w_}9CTF;*1Fg&
z<+-ySw=v<5jVHz2_T6|H3bk|}$l3Xt0tN<9mOY1#EbET64TVE?e(;ss4vX{aBgKYE
zEiGE$iCmN!Nm=>$yty6e8F+7A9Px6fi#2b(JBAH35nqCjdYSlz7#$I~Y3uXPg5-p@
zod|e;_kV}2f6Uk;U5Tw||0{XU-d&5AOqr<odAfBtYEMk9^A!#QBX|mvD5Yp~QAfC^
z0&YjWsmm-`Km#h!`lA;DF8QJ=Z<Lqb;SavRCAAs9;r?)B76A*I_@15AMNDqbUkNY`
zeK1IamC0tCMr-b@pHB$eOfI>WH4LB&{81pWFvWQrC)55J*{p`3u?j`}=ERB&4#y?<
zT*mGAIK2e4F|~E6;Fz6_G4|M@Oa2_wU7z5kijGle)jZLw-O#i)((GOsko{QqmHqQ4
zlZ6BXTuwC@?Ro(ufbcU9B=^6l#spF^^&_&Pa^m0!Gz{WeymmRUYXrYDfMa)|(WlGa
zJC&0CT#NsmNC^OfRs3q_NMOV=!K!WDdxXP%tgD~_)Lfb!Xzp8OG6Y(~8qqiQPw_IF
ziA?#7o#IAb^Y+%2-+!24?W9pFKJQ*q-j5x*nbl8&ll;MukZ|HM<qO}LTxc;BYamiB
z<3H}G;q}F^07@j-`O!##P>nTqwq`h~0vNpU6Grzvnefj`Qe`95xR%%WuzLIjhG*;h
z%QOr)NEv!uOw5X%jvNk-eV|B%#<N?iXScOiGCN?9pEPNE)K?>&JrDym)k6f@>d8Qm
zh?FI3dgqnmrv6Iof#XLVQ9Xw01->_LnX4sM=(QGrZ~J5m<SL-bj$>B};*E3jE5uH1
zgXMYQaZ<j11Y$IIQf^O*fz{Os=zZlX_!Yxc2^8Z%*k}@Y!guA&j-BV#jzVoed3PLL
z3Lm*BC||b!^CCGqN;F;nBzad{<JRpFubUlYVM1$r#Qr}EVx!l|5pBJX@?659;kapR
ze&r#RzIW^p9dPZtoUh%aEdg&QXlwpoaJGEJt-`b~$hYT{o^~e;=Pod*ma$mGi3Qik
zRx`jNYdQ1gqgc%T<jl(A04XV!v8JtIOnpqF3#JoV=L;uEbzmEYi9DAN+K(K15zMEy
zZnXdFhTU%VE5hizDO)Z`OEY0zG1XWsiK-|srUnDwog$Coo#K~)WYC3|*i6nyad>_H
zo;1V_h9IK?$EE)Kw%+!{YU0GPbJq$8zsgHLBR}8yo#A>P&Ha=r9G1tO?EmgfZviDf
z-R(&vVCcmlaIKXg)Al!bsd{GV^4nN^{-5XBs!*ZeWD`#yJCuM5Fwg-%kZ;=5@7wC$
zE<=9XN*)WMve@Gr2$!8m3aGTqC$!E^XB{hnHmXB8yP|GlMQvUoK~F>IHHoggAdno`
zrkEINV*FSiJ^D0Qxzv2?xe0dJXAUQ|=m|U@zrZYb-XS?mval%IB@<vS8L5!|lWxoC
zWnbui;*2jgoE>*F-(>$ya8v;*urKD(R6wS2ocg|6{r(i|_uDehH+iJ$zwfzb0$`c(
zX%0y=lP=WSVEdspF_BM(U1ENEzXX%9qwqqCUvD=JSgBMM9eC$bSoTI@9rAh{dYqC5
zXh26?IX9eSgXlX~aWh`zjCYX#K#LQAgpT7q@hgRoT3}X09O4>6e$fGKzjdAVqvNQl
zsR?MGlwY|OPHW#ixw);fc|={n)pfw~@VPSmKK@KNRClJM(sz5OwmX+-{F6IZszYvM
zG7MPdB$)iBj{5O+%WIfT@wR@C%uq72oQ5AUH=on7gB{Z*BP>ix8INMOfkpN82N*@~
zZ|q9g%4mk}+lU`QsChEN#2=R)QPP=)DMD|BEFZ%=YSqoUJpw)O)$B^Un?37Dp=ww}
zBo1?gxNE?uJbH#7ve^TkN%;#uXlu&9HPzJ|1bU$Ya$=TJ&i#k`%O7_4w0^K&$WedX
z8#9tFw4o-PGf`WNbGlA(82BUs{~n$@y81GmsL)AYD^QUlb4l8<I&npu1I`yd3jt3h
znpwXK7D5IE0QmYk5d-MJ3B@7yWyHv(`p{=Lo$&L8k^i`XI-$fhr!u>YMDLvaiG&A*
zw!&F9>Gihj+z3i)N=(o-+NdcgEYB=YlAKTU4yxz2&$#@Vu;(xoLWvDsRm$N2oq@1>
z$5iMH3=xw(4<@Kl=^J)|HrwhpI92H1pm9~<oWlCD>@jp+mZj3xOTxBjFZwn~cz6=5
zEE;CpP8hrzpp&)7nB#VU4hca4Fa$O<9_SbtH{Xzy$kB<FYR3(l6p_g5XfbIgV&`Pt
zM1;M)yY-+fs)U5X_dwWaUa~MI29TLEwcTVCi@iX$hshMkDUwmi6-8I!`4o|x;CK57
z796AAxPv(LJ>g=mKYK!4uM&JXPG+8^8*=MfP&>N|K3bfS$agKK#K2G`T+EEfCt}C+
zY)W=5i$ByyR9WNjC&cOwJ`#bBC9XM`pOmLtz{)g^U#`m+e2z>#!B8av;5&qWmDVI`
zK$vAH(do)D$m(M+2#FrHo^WP7rRBsGVMU2PK2?wpaBe{}(Wr*L&Xgx?bj6eMF*12V
zb!sjA)P@mrJjQ1*Fr|DGrm?42n!IsHH2T0*@9N_6)d`cDt{Q~2VJTk)!BIP%8|fgQ
zxBpE!>$LE#=k=`=|Mg~GEW_&aDH#PTppGWKby~zg$AE-@d6#yKz$+EWtS`>!%)2($
zN!T$dnKY})($TpAK4ZHp`*lWB-_Wv%_`^>4`3rjym_g6dhBN#=M8y4QcU|Dq0H-9X
zAQ0COTRI~KIDx396F&*{*?IqS5fl$6HSr4!259xeYE8m{-tVcK)i?FUEb%><bEIK(
z5!$T<3F4kPGL~8DxlVTxE^+hck+sk~7>G+CO0wKZ*RU-hkiqx@OxzB~WpHC0>=Cwy
z{BedsPAnt(^oHDYSLp(80&AZ%zES`|hTYaT-G-L0(yxN&A5-`(IDY$xM`&qDv%DfE
zcyaIW2c<(MIoc+$Q&djPXwVU<z-nt;rE^ho&6rU2w_^ejRm^8w?XHeUYKNr8^OV6F
z)&ix7oRr!NG?CY6gVen1I5H<nzsx^S>}(kI*sv1zh2OOyJoaEg9H;i3Z^|IhYbHy}
z?tZE)8!yjVFR>nf$$=REF>noM6YQJ<Q4aq3^c#!F|Ht^15(ryUpi3+8u*91u_qDa~
z(ttL8o+^LvLK9egRpFvbtz499iTB)s>}Ofo^1NQdGxo;>`}oH_9|4&&5v!a(rqT{x
zCYJhyg`u~A*1-MbODjJm2INy+ntj_1H&I&p=hX@Sj?G(H!MF4`SDq}9@Y(v;hDsd<
z@)GwdGq;I(UD<8u-_|P-P$a*t?OTz(tW}??gOlcU1)-8+p6qypzjPgpGSpdpw5@f4
zkp^L_TYF*EG_}6{`C=r#Q~oBLb&EKwReybFSqS>$2o2vz-(KAWQC8578Jff_6Ko!u
zPfNSe?|9Nz88u=oV4QI~OL6Qf@1@k_57yKP#5m`w_kK|1JVHbuC+CX+C!vCsmA(yd
zvWfV?C=GX>^Hio=##)l6RM`(W@dX!P6(cp%Hg#K7kngW(u+*s#WPrzC)1cue;FpgV
zGg$Mvi~OK|E!9J|%=u9+1lsnIqE;lKr25D%L0KP_{al)}79j1BR*LE-%$O4<Vx%&j
zq2`Co?<~_=>-wzu)+^ai@s=L2Or7kWQ@U|J61A>IAxDKgC0d~y?W#aOk<j@P%46t<
zmF4+NU4fdtRkPK>?~6<4)xb=?p}~+^o`e&dCk(Oj3$~%DaR#LR+tTkv27;$PkP-Wb
z5>fAS@+)eB$p=5bdfShTM?hYW?omz;;{0sA{)mf6gd3^xnmtxQ%4-A*qj%!R2L|#=
zFI)0)Tq$F>jlmln-lEqXN>-Ppj?6c1`4Lp}vLC~4EA_!S13_D7jc{(P?ncm(U+_Pu
zRFKild~qyG>n}JG*McZ{vYRTOad5HYj^A3kap3VT;V@fOVL~sy6HLXy{v{L~-O3Z5
z9FKkGeMiX4>w0{<oId8@C15L8u~i}4BLfl&$364CqilS-b+BJtd%}VfvmZ&^JN?(w
zGa%FXVCDAjyb$lDA)d~}tPs|!(pscVHCuv@Y{K+L>f@Y|yZ%!(WWa?UiKNw}U)kff
zAj2+7A+CTcUd6hj4@F*21&coD>&fQp*v`OG(C=syw?l2+zex(BW_M(kvvt*9au!;D
zzl=|&hGcR<A1RNlIid|(sK|lbD@J8);L4f4@R`lGRObNYUMkt765|w@@^keYwT3{l
zN|itGa=~BU*J}NG;R>HL)~#>rs#3G6@a<p-Y@z<$$<poVbK}YPsuOPhk&%~d#+fCk
zJNlVe6YrX2QO*y;P7XkepA@|H+O=6<7ggc#L4r5ig7Unn8j~>hA$LxL-O-{xTKxuF
zH=>sB9(#&v*@6M3TaQn-lcnpIhg9PiYo~+3T<}lnuUi>c9T+Dg38Cd{IM{BoC_CI{
zFstp>&l~(ZDxTa)MgHfq8t@#NSJ@B{{<B>ihPtzBV|==m-Mo&8XWURw&Yu#s|J-PO
zPSw&bEL*kNJpA?g$_x=T*9?ESoh9H4Gb{VDR_8qVVKK$0p%h-!&Sul|)4Du);8h>=
z2PcTkwDg{B`a5t$wQl2=g|ILeON0QWeyS^kgPh+g2;+Z!QSj0qu};rOSRtKX=RQlz
zL6sfpg)0b-Dt%ZR_dFwR=<@Cps3r9pJk9gHktEAOQ?=%DEUb8|77@V7#CESS{C92j
z;w%NhW^@KI?kAySRY{@?UI3z#<x^SIZduGQ!%J#k@0Y%q<)3{q-%d)i+h_O8csfCr
zzq9+Pkn*-20=S?cl8|4ZXF;HN?F*W-u*-j(Qg>>5i!%h;$&28Q!$ID9?nD{GbJ`QT
zbE%|X?f1)2KmC|Xl8GmNx(KVoB~On}8e*@qQ)Q!LzOl5kX(X@qb0nX<Gv}69dXY|4
zr3kDN;7Vq6A9|5HUppsx=ntfNHysNy;;~bP>2vs2Eb-zXRrZNM2#65NZghP?aM<J?
zFH@yNuW4$&*MPH`BcZ*KAmY;Pfs<Uo$q9p@=L08`KyY8zgkJ;0!Gz7y{W4z4g}vXA
zrVZEiT0E$iM$m73Vi!Gmy1!p5)C+%NOk~(<0nu&1!T>X92dG>5`<*vfl+ToEx@qyC
zq4Z89|7IsNgEOlY;pO#;)Xsb2w@J+%zLYKNnk;|<Cfgwhcap7aI;uncXz4LjS*<=D
zL`L*tKV;Kgnl62KU(77eA+NIq?3S6W%U>F%AyCC^Ft}rK5@xl{9sB5Lpgf-tBuArb
z-kXt9f5F)Pz!5Wgnw0Ldar51K_kg<GuIdn85<^fWDHOqO<p*;D?;hQd@4hAL84k1O
z&PJUK2-G`++GGQ-ntsjFI9^FbWfQy``lmMZ^fr$b2Pn@tlnUw_9X8wlli!B#Hfp5j
zrB4gCECIx;PlKk=21LpN$P^5`eY=z70IcdsS**7WkWYzOzx+YzC9eo&`n6S7Ms$!W
zR4h<7H1S^NVsS~&{jp1r%@xim3nLv=cr14tlS{5q56_9;eV)LaP+_wXHNQ_@48)~$
zWdJ(akxh_b3NhtyyEpvhmJsyS3xjqF&Mh*<7=tn?w{DMh@nLTxb7nE>?HLP)7>n65
z+p4^f7z*Q^X3$_OV%NozJcTKkat=swa*|}FZ=#Z%W$O&QCVV}jcgWg8jxq~ICI37;
zkhJk#%J?9zo8x>EP;nEEW9ajPFDVDK%IFL1=eVEEo8GA0Y7pQ&Y38?jQ@yE?&bafl
z+fU_iWsOyl@-|FZ!*72?jnqnz<pm}xg(m*g;4K=E&(`1ro>H=}W}swdc|vWpU^*YW
zB?C0MrO|um&VlChz`J1?erUn+>28&u)Y)~&8A*kkXdO1egd6E8o)ZN+oQ_GbN8qW0
z4ge+Y31fKl|9(NA8;sb$?%7b90Dwvc__u(94R6f8kHdrA4Z(g<o^V%Ewg+*B9`3)x
z!%BD;GsSZNsCq1u*46q(fBVMTjM_ESbs5rarG9rAvTAD~Phv_%NPSE_Aq)ssK~~Pk
zQt#n(mPw4^!Ihv14l#wC95-BJLc7;D?H?Rcjt77UFpufbyjDwMn+7ltMzdVzB9$M<
z%K;M=y;omcsB+pw2}f%19OQ(h$@{7a^!%%)P=mrEhV2T8At%NOj-v~Q4&Es(6wTpI
zA!bUG3AhFdVqxRr4YY3zneFE<7!d1G+l%CImu&M2z~&scz>yk^rwY|p$S#z4roYv5
zu8GnYHXB~8lOQ3Hra=6c>vOn~LsdV88W@Hc1u*tu3Y1=WUcv7bdvYqSj8arjEBUx)
zE%=v46M<`QKzM`p{&lH<#iI{=4wc_s6tmBECX*`6`BN2T)&jjNLLWFs0+I#3>SL;@
z5Rkbn=_ml^V`vBhx_B08j)}mMRPR|WmK?#%yA6C|l%U|ha6bVdl$0vaftOA?!MhGI
z*3U~GfL+sWc5fbEbK5IT2GE0vBObl63Zo^Sru#VEdH662`>NBeLPcSW8}VorYGqPf
z_<_GblmI(NjTGcNAp6*?aWqL@8Y35Td*lz4-Bpep2n=F;>P#t%H*Qz-n}0MzAvJSA
z_PBQ$kca{$k)WQalfE;_s_8^DUaH&xl_0n4AeWFKwJM*zN0fp}o<}svGoR97?6|)^
zZMJW#D=isG#|}hMIEs-|QAv~`qvp%qwr8(A_r&qOYc(Zjx<Bts4%%_UrGR5q68oNy
zk&8D2Ao-Udof@FCG#)$ms?xLeyG;gw|KkS-IWO2b$8PP*Y7CEFjfeq~{=p)a6x3WI
zb}a8!#O?v#Y`)y7v1bpoe(|;RAx%siG5Qk-Iz1pf51XU{5=meB2Ocy#(C;tt?8O?a
zX<RdzXmvHf?^)a}4J#~0R}{ZLJ|B*hm`|!|6aLFXa%V#FzIAeD<MSc{aS=H*Ij{cz
zYXRcZ@CAX|XF^*{(TuxqYB6CjPhk)4v@&5JQrJ3taf5z%b4u1O$q)(3yeQyo-LS(9
z-D0VF5*5E!4fw>6E_F=gXEeIn(o~z_TX3^3ta7;$h&VqxW>)_0K*v-gY&419;7MK$
zerxgNNoa~SyDylM6@a10lezXq{Cd^gA3ItoA+_}}8b}nj+Z|%ngEpwrkTIU^;M0u#
zH<h+&9ap`X!s$>RWV-Tm*`v4R3$QReYEq9S7t}b26%?rSta^uy?T=R%QJ#Tj<c@B(
z2wyfjz#!RqUd`1WW#T8nHrGo<cy@{u$9E5aI$8uLcSnwR*SaYqBp=!nPEMc`77!L@
zDIGc#qB2UAVJQXzO~(Q!BNjc=hAi(Ia6MmCC%5E6(t1FuoHSG<B+U_T7x%zGnELI%
zBl@KQ*&-KnB@rybbsi+PX=kSeF6Hl@2YHk1m$0l*a*Vk+;9ylJ8*SisP_US<&3a+*
zFi5e5lR^2RLez(5{y5BGbV4yB5x7arE5E~M>cT;>Cg%HcFGt0OeU(6x`m}=i(ax=Q
zx`TD>P3t+asn|H;m?{E9{)GoPY+-az@B0aWjdeN`flmKqsva#!a3?nexRGkk`3J<2
zLA@Oyq(ieXB^G{U5NBSwd5R?&qP6p%n3<Ui;D^$~xhszWT>~laB{Gd-UBOU|!};A;
z!;Tfrw}Pl)pil+`YNCXg?{~{11zv*0h1XV|kMcg9nb*fz&zl+pm;j<XPL2tc=|Gm}
z!V6St(CO84TUY%Za7{^QS)zz)ww7-!Yys-fn$)1r2%8g*s1y$Xdje0Yey^5Ly?np3
z6cg@h95#VsSyVIS@DKPOQqairTx2rBag*33WCGbZ)F$#+_)G9NPEolb6jHPFW4Qr_
zWH7MWQ%V><%&EuXzb9?}_oNyu!(%^83{??eSr8HcsUJ4E0sLD70>T`#aMFLsY0Gg*
zlGa2SN?g;z23G5GZis5TZs*Z}D?*AH)nFGekQG4ATaJUEg8Tcf)|?x-s3XBilwl*_
z8JiJ|lvw+Un{5lox<N=zCWXWh7&t#x<OHDdeDw4*ne?+|pLwOEJk2U=_s+eK+)I3t
zPaM5{pKQc2P!IsiK>yN&c3a_3bHxWWbrnj4g@q-|;Sw|%Q>&R%rGBJxQrQR=+GgtS
zI-){iSJ4oMkS<~@(b9S0M3b|E6J0R#$3g{hdIOR;IT}w@ZeF!@d80O*k<WY=W@!Wj
z4c~Ziyq#XSpHD832A>3Hc!SGUGL=!C0XsoRz$?UDO)|+-@p2Z*tHn|S&J8G;BLRF(
zi>!-oP0q?#;LmyyVY(#$v;mH`lOyFVul5}aqO8(9Grs%dPxAL8BA!^REp3p7P+zg6
zuPpu1Gxw?THWGo0m7`#a#q9fcWK;Mln~=0D!^>0xjsr4*Txp6zSo#xyKnkR!p5;lq
zPUN*vh5-&8Cj3<|MSRbs-iE1+6s{=%9u_B(37S6n%cv$)YX2^faI8*IHUtFfA}`Qx
zn@ew}RvLo>+2&?!7tv=KeYRg|&&S?YoZWAK+$7~w@jQj&>Wy%J=AMRQK$hrW`VJZO
zWcSrAdBTQ@-M<y1F}PN*s#(u}+>htil#YZ-*$u+SJg$7d6{mL<{RdRW?-`L*Bj>TL
zTYyp*(Bg&K<m+b>-hW@1M_rxK2@*w6bC#8dM4+F8YADlU)(&~QGoh+MlAnjnzJsc$
zkgUaQT(quZfwfa7{Sz=iAnL}adSL9`g<4*1Zj3ZpejvmR!Mo(2)b>X)<~VObTg+Kt
z)vUeA5ZZz1^T)qT+8c&_CJkeRkRPR$ZdiRd*m;6-e#X_#LaNG=Q6S8B;wid%5vb9q
z*cLWpHinzocj7AYA|M+r+%g36&u7TvkrxpzN;iTnbC$F}07Ia96BfXnhiyyvP$i!g
zz)cVKRvtK!^BQXbGR@D5rx_LqQav{fR8;lHc4K3wMh{07xW9@HU+52G*QA<JhAz%F
z_{2>sW&*=5Jb0>#<Io{~yArRb`n?@g>~Lwj8a(N4V?x<;rFT4o&s?<{me9Yv3~(~C
zK_!Oss~La%Q1tKmj-3Z|epD*N6`W>=R3xACiJHv*Op{`;A!a7H>SONRQeeRMrOpBW
zODH5}q&gUyN<7_8+2ItRNl7y7r+~2;`6E4u=M)NqYN90m$G(k*U{NF}u{v6TEi7LC
zqPJx|tj@J;JgxeTd2aCZlL2e6sG9;!y_7YkTO!_#o>2JJu9>WdCcr|!+BX-n4&==l
z?9l)-j9hqpch`hNk+kY{7AVYaE6-Q|x<aDR@_OXX)%EJ3Cs{haOw!10%7Mq9`5=jL
zAkd|7KF@)tP<~P&m2o<%uXC$A^K4x|C)}DzK*?8NS;Auf)NZVSU1-Dq`!G4-)-~*b
z<3KS;I<>z!UrGtxp0e{NfLO|87@~>{bKe}E9n1Z>x@oE;?GY}JnJ?y}o>*cj=9ted
z?7Z#E8qbdbFNbZzH(Q#R%-$wF(s4ja+F0$1djuJ*BzI#*mx7s^$@z61hAMVGxyR`B
z!Hf+%LBwaNQx#&*v@Un(Y6QzY|5M}=Ls`Jm@5S$e_21<$#i&d4xh?|y9*KS0_4G44
zr<9-0XyvB-6)4zeAchY*Dww>8T%A?lCd#e?mSm=@n--U4r6v_-m0)Oe^_v@Gc<@N4
zd~Hmo9RaCa4iVcM7rPfCjh&^)>-M%)OWkM$?m@qJV1P2RFf~ntZjRYmOLPPRK|b%b
zjV+Ty#(^%1R>RF2mrJdoG`%rYM;uhv$06-+M{jL>!kW<QA_!_r^BsHb=;y)s6K*Yg
zqrjcSq~Cpn^73+oMGbwazjD{A{s|?s`2icZ`O%(`p9d$C&f}<>AhZ3Y_GnG%J7LER
z-giLCvwd)QNoZ(<;CI4q3m>(jfuzsqJb17vF5&lmM;)s({Gv}`eXw^Z{2Hd1cI<<l
z`oesN>HMz*hQ4HO2BmYid9Sr69Bq!9HBpDrZ&22F-VJFsJm<q}f|c)d$?Gm$yuLwX
z&Z--(=ic8b^ZZ_PxkpH^K?h4t3Z?9lEiK<m;g-ElzEr!k+2*#*Rh{RH(00tX&F--+
ztXS3#lX^*us#`o1Q$Wil7i0s#cU69lY4$b~#Z4Yu(%$qFzdm2}<Z~}ZwDqRhaB|6H
z<SCiFV?k9I9sJmQ(3ic$RlT3542cN!StP#y>4j=DC!YQlPT&^R7;DSkh}G4njq7n=
z?Fo?~`B>lK-<QgHfgya4y+*f$&>m=Yj%@`1d5Q8{2XW)ptbf6GLWUW_R1K<{ELRv%
z_@`iKde}?_m%s231vXa;Ii{Gd7QbtVAhPELW4W3m?6W-(?&f}rb#>%%#Sr`n|2xt9
zF^lqk{*f4vR%KN=zy8Jnc<?9(UjHn5j}q+o1AGa%Vna>yN-J6ia>efgwidZHK=GvN
zZSDPy3?EkOYMRo)-E`#R?2ZR%@~d@xOO~K+H&B;~kQ(xM<uY{O_?+cN+&yIP^srD4
z07?|O0&H&8M`VbzY<J={z9)*)-^_VO`0jZgAN(3UN!#X;SyGe`oKv?YB@5dXzUdoT
zX7;K_PtkqEg@LgNTlsEH&199wh|-VIsQoEA&oEGZmUBtrk>Ja!2b@movNB5uRiaqI
z={J?MQT_L;PdO2xGwG95AT{&t-<*e%)0{U)c+xFPm#PPP8CgD`yqIs)&s|u1qcwSw
z$pCoxAOnC2c#hy8`*cqn5w}hDsE^H+j#&5hLzU|WW+~@bT5XVkmLaOA$HWlfT}MEV
zRQC06wQ+~jb>&<-^#>qHC#8*R6xqG^(^zHt;Z`uy%|0q-`s!yqI>9~3sCX9&P$eL+
z3$4DIDodk#%~>%EghQcOp(GZUvWz;7g9K6J*B*?=aiMz|kG5RpGB`>+^?wmS5~{(<
zKXNDbfM1k~^zV84$GS-y>vu{vkhf<~E4OsN^U&V2QrDYAK?PA>BoRyvWcKpt03Jdo
z_i5LAFy?smB>C9iY!Z6xRtA~U!el%JC}cMR@@RBlyOP$?Sdo18tFHeEqUWoP6CB-1
zx#wKH$);BC`9nZd8Z3A9mPM;PaV~KSKMkviW2j;SyF)C&?Z?zU(8cH7M9&%O**)ye
zOU})JkGk()5b3@f78dB)FNvLc$4f~LH6qMK1ARYB+*{yMlRk{qMpa3YZb!J>`)6IU
zS-SK7qoAV2S;q!Mrf}&k=6RVI2(H*!5-;vIlt55k_$qAdiq)QIJ=QvMOiftTu3XQ2
zvE=7OJ}o@fQWY}hXGNXn|1OLfhd6k*PLO{Ok78@!S*izynUn)xA*BVhi0?5{V|zUt
zc;6CT#H%C~NN}kEK`SV!zy>u_l9=c--f~eFS+UE@UgudvoD~oeBtbI!?x>AY=}dH0
zbjXveQV6hHkWY|VOnMD&_N6{M=j`Z4g?zJKLi|oCHs>_HbNMF?2&oCFn%dB!L(<ef
zl4g1!P@6EGeX^>(sQAR1M|J;&%SGWbud60LR(^1z8vyZ(pE8v<+=FyI?u*W2Ro8NU
ze%h3c_#ZKW|Bi0MA&et{g$h3Y`OBzBm4RHbcQMdS8{`$WAjjD+(TgFMd?KS=|9Dez
zB13i0E{*ZNcO7dIrFxPk{tYDD0jl`XWF9sPZ3Ga=_r1m{H~JQ=`kCMZt4Mf+S)-fs
zm$Rua=g)uew#X{+PgE-`<3*b+fyjavh&e9{Y^VfRsC|CZi??b8ew7WqoQ?E|+i&iZ
z(MIqXS737Hs8YYw{1D_=B+R(_w<UULE@N=X?=^C$ipiJnD}a72{Xw)qxKdkHD5{m7
zdw0|Y9vS_2&R0=Oslu)PZ9`})<s8i-yLV2pCE%B_DQa(_p-1R7y8=xkdUV^y-2v1b
zbPO9!!Xrd(7wT#T$P4uum0p@tEWR619wu>BOgs-3Vra4_o;-PJ*3M(Ku@*NA`MsQc
z`BT$-{@4vLj%Yr&f;}<<Ec&+VZ!g<lT>icqHL5|4wf>EX6>_zeiI4xKwg{>60Z1q2
zOjMZz-K}R;mvwaz>ei;B)h*|r-HEvA1)5~+n;Kl9-wwBn9kpyRcI_H&vYFG}!%4HS
zgV--6$Nvm$1L0CIZM-={h<^<EZ+CXoe{ns0%?$)E&q1b1l-d&%3v(2JmvqMz^@3@4
zwsQG_b*fMrMTX3LLADtHmDp8RTgq^%#`G;gdsRg_3a(G7a*(1@bkbr8v;Bn@Z-W=}
zZU1Z~!c6)X^peY8RN(A!`0nr+b#-x+1%5^OifQF<o(CHp255J9Qb;>_6k30^#8RR>
zcOJgP9h)N?kR+ovmHh=93EbfEy3u(QTWA~iC2eki{Roj0gF-<0jP41*cs)3)+G5%P
z2}#1e<EZ%pv_vK##EjHMJ&P#vrq39_b<iSa9o71RREM8eSNd1=a)?OEZtSbH4?AM(
z$wiQW8zA6$+aopV@OzxbS@!*}*wkKs@n1D1&ajf^`EA{Y->a6nGZvEDOn{yPC1D}^
zm`bhgKttTN{ZwPzVGu!5qKzYS`wN8o*uCU){{$^u0#n%a`sF7p^gsj_5RC1gWw;UK
z+yu#<)X+ri4aZkRIIU=V4dK>15^5S9fGEVRPKVu5l%!fJt10xP2t8}21$70ed107e
zt*rRHdX(7Y>UoYibC0(7+en*wR0QqR1vQ11@ubsBfqntbG05DNRv^5K!@SW%TRt5@
zQe3RS=4*{SE!oA-@P><A^*2~EDV`GtOAUlohNKSw1;`mOoj{Zz%R8<mNf9oGJ3y<`
zBk%@<D_wzl&x^DadF9qSZ%4_9GzSs5O8u)Y!YR||ywbrz@^vHP1ioI~o-wVlSvP%g
zVUN^LBN7i(w&z<ZQoSf%M0ot42A4z@c(aT-x24}TJB@^&m;r;ZvJC`cQd7yd7k0AE
zuaPt4O%OFksMzsJt-my*IvVV)pnMrUs~T~;28znDM>74^)GjnI+k%FYDO{vk3@-zo
z5(xR%(pFC-{n)npic4#P`(o1CNRmV`XQ=P3l#+;ObmIh+?#IJ`COmImH)1wRokIco
zM@sAY)_17n41`pW=6}*h3l{#Z%oNsk=U~vnw7X3KU@mV{)<T8(*}u%lYa<<z1Uz&t
zYT9#qj8XDVrX+m_3N<|v-6bQ@<wJ>ZE74AVI^<rh1Lrv7dd_*o!Qt3cvwpv6bb6Hr
z<KSPRL_eSc=}du(hCm1q(P@U$oWC!Y&IX#lZ2Vox08q*Jrq<>F4Wn*>xT}BED!pn*
zG$L&$y(3YlTo6!h9fm0RHc0?QQMd7nGezbgTx?JqE{rhy6F5{TLr5KPXB$>1TSzG~
z`4RCpvPd7HBr31R8xo7;&=^7q(O+B4diR`G52(D$vKvlwPpE_g9!ix8NWV@F{D?CU
z)c}}TnaCK<3$L=Xjy|5V9<Axh91HEn`Lxc)iO!2j+~jh0?^3>4+hV9RQ7ab2<e4uL
z5IF}))!*jWt+}UAsS}Yq@1k%MuwJdu->E3%Rs=XGHRnpz)7R|L%9-s1rs)L1=_Mqy
zy?Krea`BZ|V!&IF)bUbE^QmJXXw~i?l}AdvY36@Dh<%kq`<sHPDpW5==_w+0UEEaG
zP<$)6_qzsGWG~#*EDyHH*@lHlg0eTHBSEu|mS?P(7_lj?CUK$j7^OIZm3!~vHJk@n
z(I<v4&}eI)g6tpC)f;_VqhtLZFKQ(SAv4dFgUEq~sH=i9$=hvbPZpYPV?tM_4Nt2i
z_HF?NOt&54Fl11eXo;I9leHcLwLz$%)Kkgc<9Ldn#1p#fk8^C~H*)Bud7opMVI?e7
zEVNA`v7wXb1CvBIF-4a<OsnUXeC{&tb`O7^{{D4M`bo%O=7&z2&JWEMp_doX@o2{B
zu#v^*JB=@|ml^G(T1ntcT{VH78>#P>i$8U?**xd8Nc(P|5tw3*3k}&^xtHq8*)erL
ztEf>1OPo7b0G-g|7>GtKw^hYmYP&s8q=QQ(u$}t?MRIkNDokis9m1|va#_E5alxaN
z3-D!4N4LS^wKQXGqS+N<QL9N!odPo&;$<GEP6Lv~FgLT0MYvAvhLN*e{oAiUDQ~^q
z@1SjceeLbLShYTyI-M*fL&w%tfG$EM-@g9iKwI(+K}$d}^ylA`#t<2m@4Rd)X_^P@
zz=|Xb`gSnWK79ky_Af~2-iRzM^G-2RCZq?Q?fB-mv-DP8Hx<Oa+ekPk7~;P~b73dY
zm7Af#aj@dXuEDqv=uU?S5SDc?ubaw--A0dE+5gl+)!{2;gx!k8(9i8N;-(aK+Rw3|
zofEJcZKOFvzVXpp^svDEIrGWRSGSo$=SxE3Qv_PrbBeKUc!m$-RaCX{X-2J^`wITS
zAT3B0XNbp8SE$&qA~8B$OoPP}9#||Bwp-mnC`DBdMF))Ha)U0OZWcnR3(-+wX|`yP
z%Kx>2|NbG{2hI1kk3_mzGCtT1G(0ncZ45#ZS7P;@^op9|Nvba{wXEMu=I^rS$AUai
zwJ=E;?D1{E6x}??<%=-h5cw?o-J((&Xrhf94VfZuKB|p)c%>y7G2)#ah-8Js+>PtV
zF?JJ>0ny1`7ZNJAM<L|?XD_hLwy+g(YgDU(+wQjjeCY=_xiCyf!2Dp&(9DZ4T))ZI
zD7O&3sndVc`?b)|&tq+HZ?npRvhk9N@MmA0!%?DuAxsAak4CPusxvlJNIbM@YgpDK
z${hp4v0dB-3NgpBXnbnk(#Pk)MzjLJ=m0emsamotDS;C9yx{4l?&G2&*ZAS*;yJd4
z1Jla;V9t@ESxe4IiEu}rKSfL;cB>}{^k{DKVT7`|u;c}NV8KjRJj4b0<ny()2bN`g
z77O#pJCQ%(qz^x(i&mni6j7RX!wKHo{`+V=m5m}X9Xh(CFO6!}`ZdA4s^_OxW(8wa
zk%_oC$-zc=GhhHszNtOE+2Z-~KT+qxs#u(;5JBdWU<9hP?%NE_@iMwdSPvDi=PmB#
z#Q1Mw(R#IHW2t>qAQn%OAsE|#AQA5`r6N#hhLaMmzQcCSr+&Upt6ZnF<{>KpV?&9{
zU4KCn6+B^?{g<ev<#=&CS=;RRE56vJ+j7?A5co*wUt*%Y7ZKY_c_WUS3gOw8oJ$?1
z>kYoeMkp%Q9++BdFe*9?!bG%*Km)zNd*FNkyE#i`iAVNd4m(i>Mq>J<>*#Swd#mKd
z?yK6nM22(A8#Z4mNDPl@!jdZj<J(lb!*IcIQfVjC<PdQX_xfju!gI}m$zkN==tB^Y
z{#Vv-5b~V@Q>Ui3U@jJo0gM2d5|(TzVD4DWehJS@G{pz$A3=ZJJpy`5>IL$-`)mbJ
zdQ}=5?N7Iuzp?O9qbUMISjfS{9KZ(HjdoQrg1FO0EIuf2mdPU^57c!~wc}oN?+G28
z^Gh$~VkjuCr8^e*0lddgtXxS<=!x;RJoJvq1itC!sCtaKDly6`>lS5rWHNI!6R%#c
zCzC3BrbOgZO4Rk2sBdHt1VRw!<|a)l$70Du&FGo3SmNoF@R(rYkrz1^lL)tX<TFZ9
zZTa7}1onG|k><R1AN|8zF+yLLP(f%=5)i!;RJs+y$;qRh_I_43`-APbx5B43ca9I<
zZKOQ*YvPPH<f-nn@(9TJFtP_&Y?uM=mP|OtaPa)pOLUe(3nGM|&OSmg!lDT&MTzhj
zd<gG|n5soGuN)ii@aVL7_1AK@TLu3hccg&xqn_|Bc<UqfTgA2D4Q>$1nipudosayl
zwDWOQ3>}Xbo2-vyO=MM_cP;)!xPpJr^8%bHp6HVO5(Lz-XM=3Sxc%c(lzHwdh?TYq
zf1!+~s(+ENbqo3^j2Jhl>M#S{GW5`ylG`jHj<+hTq#g^UYP!CCZP9S7)dU=%PzA)s
zi0cqgM?i&T$kATo6#H7=?dMrX3p3)1&z4L_;@G|OMmnF8n;r4<LuiRl(MGU-2cXZV
zK$Q`{eN8;=^cJ$eHtY8#m1`JwxTS=|6jws)rjlwl$1V-hUf*Er+{)VInmXx*8OnVd
zxybOjBJaw0fzNV9Vjj!5;*fRtWAD4#;^hGE^8A$G3hr2C`<J}IUY`XYmirc@%tLuK
zzjlC9J&lO&e!Eps`wd%{Of+r5*@IoYwUpM|ZdmVTh>nc_FJs4%|BhKpY=7;SOeyCN
zaNJ;~pdDKC6Ysp&x`v0}-LLB5Rsrb#?uKPA3(;EEoEL4!w4Bz6zO^?@s8mUe-=Iya
zWBlDTw0g5;zx(fJw$M-&(ru(gK3UQ~eKE3TSJar7&%QhK=Ku#I#C`kXinskH@Uk_i
z+xfnpTpL7WV_apwO2#NLZ}{o2#NDkw+25^JTYBzzrqJFi6Y_Jsw?m`u#q_s~+m+_B
z`};Szmd9P;w#y1)ePKU(t=;8+G^eYL2d%acyb8j`Oj9~dV6syWd%Xx|7nF}p;x6Zt
zZhj)4KmQVFX}{hXaz7dwv<RcL_qiFegk3;6HM|B_uLAQ!LobRAUs=vx;t|d>+Uvr7
zx`itLc)-@Y)!*Gp?qQgvkpbQ8gQd~o-~8O5ALv|Beuh*GDMRYrwKSkGiT&1ROa8`e
zATH2y)_P;&O|tLFBkzQb#3V)S9XE&7h=e*RDUG{KM^N1z;JtRK3gF^NJR4S4lNWKW
z_=BcV0<*MYQa|LHX7y5HoUgjJE}Y`=7?3c&$765!sNd#~{eCqdwOq|~aje}H8;RY2
zdMmoChg|nsy~kR=%?SQ7`}gU7H|A|5n^B$_;wbpb=RgS7mU9w8wrx|^?#O-U4~{GA
z(L5Ie8Aj@DcWpDc=a~=9K<ftKM&B*r)xUb9mA>`FrZ3gj|C~~^pjtfE*Rn6Jf9d?b
z+g|vd>G%AN*|FwlvuT@F`%P$e&)FJV<cdL4%c9txv<Q4{L}h1#-x=EZY3>^qX{8Md
zB&!h%(^bzuj-JVyJL|Q2^u**ZsRgY;Q|S6(POgZEN4DYKVv!c!#q;OEH@uoSCq}LX
z+j~|y^PlVBX~5`QH^r#&2j!K*CyNW%;-b?|TUCE_hUS?uDCmS-JI(6AaUT%6WxVuo
zaEp^+LD6@5kx%<cK@hNF{y8D%Vfog6^RX9Am4Y32eqRkOO|Bj^_Qj&>U&z4cPAFae
z@dZT^$b9U@na>8&==VY!NKtmwxOak%E|U+_<V@n#o{t&o`1LJ6=Du$zZ^7})W7|LS
zPzuu7D=+b!WOxQh*4xkYa~o~(;@ry+*nej%J^1NtI>qK-bcJmD6#NBP0oFgtC8=-e
zgnVfg8?!bI^%G;#OvUuTq@Z9s?3CL&?YXjpHVdqBot)ow!PIKvG_O-Si;GF&wT5r}
zb@nFena^XaS%m6qsJZEQI5zrE^95SCx9wu~xD@k7TG@e-a`o6aBN(LVL|^MqEWp%<
z^$6rMC9KJqY1UAknLFUPU3lowWleJirjK1d3Evc^8ve|yXv_5<6y5KpJBoUo+kEL&
zo3T6IA#!`<uB(@e5?JDC(4Xn8x51G4W?1<stYZPEocew@GyfG%iUxDaEIE6QamFJv
z?S|EdI{OTBWnk-@FI}4rsqk^}*ttd>)SnzbbWZUWUS|IT*0Qtl8({)~d;nYkb?8g}
z8Raotljx#!sS^v>a)Eyz=$d5eiv1wMuA%6_W;KR-^{>UR*j!OOp-YKjv7CJ|z}AJ_
zkMnGPJ1PcUJPf5Z^@y6osMdP%B%)CC7~87TZuD5wf!sEq6PK({L=K6?e4`TQoUIL8
z7#44JRzEqOO5^{v0DVx22cQNra8j^1QXc4iK(<w!iVD!f-+Px4?Y!6ieoR#<23>)e
z11FUsI<B|d4^`hUV;i&H3i23C^+!-i;M(>v#*$nbbwuil0|(yRycJb7JDV1Ozf<z8
zyZk=@;F+!#3QD)-G`e!jb{08s%wIJO8wcl@n-8_4ciN1zRJaIjU0-GGu4KkN0^{dO
zFqYlPz?{<fs6{KVrt2H05Pm0GZGj>W|0H@`>fJ-dBdy5z*2v8}&w;9n)AdiL9(jY(
zeM(Ay9==aM@;~e`CN!OmRWk@WN&!=CllP?r!=!g3T@^iaLOGbc*L+d61lO{9qdgmh
z6~!Dj#OO|ruH=`lBx%0n!|C0s!Xl8@*A}fna%8}tyYK;D2TH0o)uRBW?e&r5wfpT>
z`Mg?dbOZWKAn28?lhpU}Uv0B113Zitk7D<}0hkE_Q|9Y6-A;N!e#GWB-T^y_zrmW6
z?Nim4%@Ssh=RXO|M@L3%ZHY(Ob<T@F(|v^n?rs5m5=Y_5KBr*bRw8eSA=`X4i0KPP
z2zDi+bsC&@r=|(|q5f8C<B^*5sPMAK0%OGyyamd@iE?HZ4Ko5Zid^G^D7;kyS<bkr
zVWVSl=-Ts&+eJqE6AOf~q>WkhL@^^4TV5}=F(;BZZoss#kL<st$3mWNoGiL}F5K^&
ztX1bGNARr`hg<S3;FDBgMI@$wCr+1u?Fv#sa>(AnaTEpQizWsb%usv%2!qkCC)r7c
zsq5C=!mKiMZWV(!#o_QIzOZ<9_P9ta%Y<}xi&|hLsY%Kn(su|7KgMT|Kn@CpK!;gA
zr;3a=21WkEQ1}R7(xSgxmdA~kC*a8?28U!E81ItVDqfGWS8VdrQBi~J1obMztlh-7
zq<sy*K+`fj$;)6$XK7#=A7qMAFUT6%67VGM@$?nyHD_W_aA5F~qj!SgcPKpWAD4mq
zBLDR{{h0`X+zK!d;qIEFBzzhghz+LL#e4$6y{gvn{eWF>${VY$e8yda0z3H(@o#3H
zU}M*lWJ?AW`O1>Y1?Z&tj>?I=e;w>lV8y#}u8N~S0+4ak>jP2jdY^wUwlo*4cUhhO
zCWy_gcA^OPghlu!FojMrP21?8tLM}zCQ|_%rfK+)3tBLzM1L(gSQN&^lnZ650HdaZ
zE-N`ksY<RmcQBj(7Yl%(E(0nrWaneY*qxl|i?(9RT`5Lz5dy#m@5AA+#}yk5DXyf;
ziVhT$h$L(2ewHncY(3j7N2W_69Mu0>tj;B=_Nrdb3%JPAC?RX4V|Lll&yFhs&Jvvo
zjI+3mI!vd-q5+xtA^d1Rp|n2+GrW#X`Y=|x)s*zUZbdZBm7sFH&WsX<wC!{nhwpMW
zO=jW<JflWWLLwS~>ODO%f^p4XE#Y4Gc&f3(xIXUmip?Iw;A!SxaM3naWmG=mCM4BR
zU$v*ha`bW^+obhN<6Q?|-NTcwt`DZuVMNh_;H|>^F<juq91xvG#z^1Md+I*1;wvof
z49~<0u}ANgGnRGgalt>W&CQ+1t@RS6g15aQqKd!__!N_l<HkxQ5a21naZsp78eEua
zSSN%<j?fDX-fMzJJmm-laGk+K2v`iqhy53^lUwl%exLDVlN8*vjsJcFCDc|N-eV0y
z`1VP|SBElM=YiBL#lo<lI@G>~xeDxh_r|jo0Hevt)}0%y@FxP}Bs-5)_#I_D8gZT?
zz{Y0|&iF=>-jbeGN6HtC1%2pIKZqttE}VZ&{2WM31A<tYbQVh8IKBen`|LGjbX~=9
z@8PwVktN9;kLD-$UyJMw8`i6*^(3X=`aVF?3(eQy4iVMK!e2;K6U8zyi91{cpnn9%
zHG1Aa{x)ciyr~nWqH=YeJ%2n(ao9VxaQ->TM+10X@vxlnJV)L+^6gqm<MgoT)te1d
zLOzb*q#wvJFr;0U-E6{qsKYAXy)PS?O&k>?Pv)=tPMxnD*^IYKvg#uz_U^`mQ}^ut
z+ey*DD7P!==8%^1ZYuvF1x3c6GfGA`fk<8-dwm9KRVPFEFtfzygsh6YTvoNH_?zjR
zaJyVdDZ;n7rQ&71MLS{1M}S*PmE+@APxv%jP~3WWU&F;_<QzuG7VLhZya2EBE=2a*
zvwEYK+n?L2_A4cHwmevJ$n5553E&e(Mz%-WI<{=EGE`;{`w$|ar=!Oa)sYuMfFyac
zRnJY>e{VHRZSkW_3`@t1Sv7IzQyE9816xoRbxZxciW*5;;M)FAwk+}HPs6TPR$1F6
z>1lAwdfqZ}?J{8Pi7A_&R*aiiYnw7zV4(#}`k%2-T5d4a!0?#*t(OpEB5!t5=InV>
z;pda`_FK=v28a?UU`R?}h;?@^k|~&iRU8*8?WK4vQEG;L$x%c|>nDv9S&Flg@}jKL
zl4sqyhOrRH1rE6M>HSM3`UNLBLW7+x$bteNs!i?6==L)yly+?emc~;@7U^hP&dJFf
z8_cG%t>9%3KhDk1g7m1PGx8JA#Rofna7}awFq88KvULuz8uh^$w#6t(x2rbP&-R73
zZJ`L>t$xJa$i~A1f@v6dDE{hnssGL_HiN+5?fGiW#pL0)Zztt5^K45THxef;-~Z&E
zMj9HM)SFD<k(Nr>JWepp5Ox2Sfru}V2ZkeurQ3CJF{Fts{w!8ig9_3BA^n-}Tn@Oj
z#_HpeEq$n83h{07-QH`F5=h2lvM<&j#J2TAwADsrVF;tTgi8D63V`4BU+I?XC&}p4
zP=Ln4R`B9p2+Vv%V^EB>k#@KG@8PN$#l=qeeL%EI6c^6BbFJNC><S{)qY*eo3p`X>
z{N);9GwsDcnlYYdD)O8&W@f;{ZXgaEAkJ%w$B=>N3DoCN+YcPmqXPxC82b2=3fPNm
z?3nt~Y25j`*!%+N+Rj`UO%iL#Z}51J^@9uKV2yyXZ+Rg2RSN{w2`g#$<LW1+jJyiA
zPAuhRY4r0mIZ3)yelWVQTLvxQ1>@8eo3IRT_<Fqso|YdANK-@tB(Y39`)sFw@PkMM
z%KKCm(u>)Pi_HNd>)qeIvjuUk>u#t#am+_0sJ*=rdxJlA{hTz6+^bY64h;wY?MqvA
z1`9qO_*LXt4n-166o%KoUmq+nGNxa<H*LkkVD&YDz1NGGmp3C<RkKMFVB+Bs_Bk^C
zqXrB)FjtZ7yUbOXKQL6fKP<uHJ9Dx^@P;+BE&h`kM$DXLpW{Oco_10LIjzxfE`Dgk
z&fz`PI;U1gTjs#;cYFp6LE_mY{4q>wJEoq|hP+WjUzs(fGdkxpjL>(r$Uh~oEp<${
z5>#!w=kYhM>W@EY%D9f*Lq@tZN86$Eya~(+sWk(F<{^bwjh7*dS*E3T#3Yk-AJW8t
zM^u5oAX-V#7V9G?kCaCs52PHC^2Apy&UZHd%1zWDOrfhFpnqE1gR^xDOTiBe1qWO5
z0!HHqtpywH$&s2I@-%q(G<kT7T?b9(?IxXk2%ZS$mRpy=w>^zq`Fi|S;g!Oz;Hkhm
z5?zhd1rUNv35`kgA9L(CIQn_5G_AgP9fjqM>pMUqNC4~@Mxau85eD`T%o=}fcnk)X
zAS$T|T!vk_WNrg?UZ_I2zN~BX3$gUfc-P#pDei46g{B__YM(~O;dA@;fnkl}N?5I7
zXz(0<wL;3dkFsUPBxR}HxFGea*T}(g>SvpOUyropO|+xFL?j^wUHmw-Z?R+SS`JzH
zJ2D<}O-2>JMXDK01xDw2M-aSeG$6?Yc<-mBl&n{AO#1U%J-ly6Q!QBV00~J2f4^)?
z@=oWyaAHilniqQ(z&ZOBId}a+6ju6NYC|PF1NrF!{%6dTx*XZ9_hlk5pY9+h!=V+l
z8~b_Po&`t3nCwsJuF~#8uqyFk*eRP_zKM>Jx~PE>>tcOFZa%N198MC30K+`}Zfyml
zG%yu646QMb=9|(M0=c*#hO}M7s3kf@1i^^7^ncEFdCT&hzBI4CAP4c*Y|-Kx8wA35
z5jlVOh^U?Q$oOUJzV(B5;7EB`WL8}rWq?W7cSPWB6>JSt#T)R(fDcGM=aD6%s_42K
zakh|f2~~?nC)zuP-G{}yog1GIUCvnGE(d+Y4bqT4ru&*7;ZL=eav62PN!~~X97;Q%
zJTTBQVPflWUeUaRKoRnPo4p@<or~5yAa21gIXyW`V~`(q=$6v9n@)zVO7#~j$681%
z9lpoMovgYdU-xLs_@kg~hn}59yHx_h31(mdH%N>%mojn~k9kbJL1LjM9c^)JEh1ka
zNiSbR`HBbAo3}!i#x~~||6l!!^b{lMf%rm7*QgF6iySf=ZR7vZbe3UJeor3<1X+3s
z3CRVdq>)BqS-PYfqy(fyx@+l{l9m>wySsY<=@5`^>3(j1&-H(?Z}+;-edeAs^O^6=
zVQQ2fJP)mRgSK?N0Q_z<;CF8y_*~tz4lor0?yhETNHoR4oGu^;Rh~Y9&3`dKZp+4)
zgRi-Z@!m*+!BWWTsr%;-EW&S?u}=k?%Z|R44ZTrLi|!MNbH)PBg25>Z;0v&H77^CM
zwGhgc3MTShkTY5-bZs>eR4qw!&2?`zV|>oR)*wI}G)sphW>0rEwG#98cD#n=_Ee)*
z5>z~NZ4E(-6Ie1wrJ3MQ#`*+e{s@v{#vPS{!~7xKo&;-Dr4m_7JN>Ap?@MOwWn=@1
zy;qyysCtK>zFqrCwst4=f0nRCh0$_(C<7dAvj}Sv8MB>>MfZ)-$T)QYe0~m8+UJ-Q
zEhg{VRvA@E)KFJ`1%)Su<@tQgGDUeiont8CIhMvBq%VO=cJ~w$+;yLkB8SIa(ka0~
z?_VZ$XE-3_oc9;pw_P8F|J+9w?~&2O_XpuPsswh<!2IN{>^E%#ZE1AbFC9<LawyzK
zD03|A$rR$#T<yvueoiQoG)!#{DNrP+-qP^~JK*!PIDBbM2d=@n0z$0jpWj7t%QK*_
z*nK%LTzXI^WF$7<dqMp`wkT*Xxj;S}BWGhK67!eO`9YwHZPM<VR3XIsssA|f4i>{I
zj~!1cws^!@<<Ora+)6LaYSH#EeUX5K8=TRwdeeAy*l#9Wx#in76&pZ*n$@U_GDr4x
zyIwemG(`V1^Chj*VmG}6M=}Wd<QpFvM5@Ei?&J>+0D~hE%aEs92%s-bnO-fJ+!Tou
zfqHU0Mym*48BM*7I!rshYE}*86yGIW*F&waK|BUvvlyCDw!&zt+yjrLs*)`aB_k`Z
zy1+SLqp9!g9+yg#3?`k0?WR+{xpB?!#VH-jus7<|`6#1P7y0w0E2~s(7j;3UOb4tK
zj#VamGH8gl!fy%w`QNxO*+HlMgVpDki^uP;w)B;gu9`@YM09nw5SC>*FKiR{4DjO(
z`Y3}qbWl+&IgEd7);PEOQQ;jCrFiTGZ#(+_4B3r9ZS#2`sG}w(@jA09hvMR7PJ`Kx
zO&hQCUYX}Ko*wBUbySb9^z=2En#rOp;?10nYE$=KUV3)7rc<NRQ!RO;OQ|>Kh}hH+
z%5dS<)xW*89r^4P7L%jsWlff2>*b(tO7<3?NX5ILXZz`T3dG9CWVnknhU8vYG4hQX
zvMYA7!iUtOAX!c4S&s#K6!XF_5ic2n&cfbAorXSL^~d*Yjau_4bZot*Isofud2eBe
z`0`R`T3Nbb@jo>*98o_!GM*NQU8~`=63pTFy|j9P#U`ZiT73AauLYYemp2?ySY+uK
zhx$IT7Wr;bIP7xeVv!FCvY=xeKB33Lezm1-92|9Y=g{s#^|QBLUk#m1)nB&tH%$d6
z2&>98(3_mykoR&kAKrvR9T*?q(It4<4fhvcjSaMMzOO<Bv)50QF(F%}CTb#iqNC3V
za<aB4RLt0uc%w<Hfdk4P5!(~d50PBdgeVQpe~RR2z=KGo;fZ>ykCWP`SH8zsD~r$l
zOBL+A4?b3A?|gEg#=9KJHQufh-m+Apkh%U#?TaZa`NWKCyrhHjXnTtD^w%uqbmix4
z;_=%U2zd2ug#(~Vf13UF`cDHU{@@^{lxa&G{IE!g%2S?!V4}(#ieSBi-}R_qMi~{u
za#@{lnU$wCZSd8-n2i<$VTAcU%|ZG>k^=j|_-=09%V~En?|Nrr+{?~Qp|9g4ghU^R
z1u@8m2BjPSR(TRonqyweou-r;bJZG~FrL@(JaBNu#sAKoQ?RTuX^L?vlpU;Fll=3W
z9)%V@Jv2DAUa=@edzrz4SKtxQRO9)4n9}JST|4A7q*r1VTw35#BiUWqLxBB7(=2u7
z@AEO^#)DQn*#Lg~m#$ez=S>(Pcfti}R^`X3mvtart9+t{(=pwp*6Q%lQAxN-lu>y!
zO`^^bYzI&B;JB3L<;<t`YYi^(r;2MTySy&+WKN3dgg|q$5JP?>kQP|S7TiQ&h9NsL
z7I0VZiXUcpd?>@|(8ORx_hWZqIL5;<i=K_1w}wNHybp(hIbd=27(%8+;t4`@ZAB)H
zg3<Z-v>h+I8khE$13Y5to2R;$o69|p6U4)Q6%o{6-?n_K#Uxh^e9djZ%YIp4i!6r)
zetbHj9|^35)gg{=NRq?F-z$AxJf@-#YuenJm8#Ji@46qQ^R-rs`^{cbaU3bp0_hKZ
zGaMr$??_?&1Kwe}6irz5P(hfjID^-<$5W2mRcR9azA*D!vWGHLpvEU)v=mq^*X<aY
z3j3kn&%*8oW`&Fa15Kn6O;Ea?UfMW#Iglgu%p@R11QY*+(!RXDdc{^hayI-9CG@Jk
za`}wo9Gs&IYipeD>l-55^s+%fPU3(_Q})52;gX(@^(a*+IrJIpvG<~mecr22t51hi
z`^53ITKi#RyYKJ1W?qijCAaqpjfJ5e{zg_j8`nf$ihU@WHmDCnYWQWnasR6Qj=?e)
z`6Pxqr&qiVlTJq~{PG)#%~v~JyK~`-MbRHYO}_Y^ol-C2I}sN@85o!zu@7vU{bFwT
zybIV%SZILQJuhbG-5-q(@D}`Q9GDbaufZ)A|Mk%4#FcO`Et^^oxE*!66Tb>fKM3Jm
zLjUrN9`UHUm+emd+1-Cs#utfJgka8`?=OxjON0Qvj;t=C4<U9Q3R#9@*hkT^XbAEb
z9(BXNcW~1VnB$LcE7#fq7lWwyt#dt8V}x*baQjpMv7uUz0Z>q-JO64_^;*9|j@gWZ
z;)Gd9U?o3glYjT8wB#p3@9%b=_y!qs08imeu8P!Bd$|iS4XxS5qB8`mkpKweRaHow
z9UT0n|B0Ckx<$Yo`}h;W&!$R<s$_2hl=Ht}yT!qp%_?EeNMwg};jvGYfZ0)r_sIlC
z<jr3B!zg0}txC=Ihhp8sjU1huO7wcrJBV7l*!~7NijW0#&$$XY*QMhaQZG#v%!R?e
zU_z7E>-rxqoZ3n%xPFO|JNXp$3sr<^$pehjF%C+TI}tcS*0^KvVrMYfRLcPB9ha_5
z9Em$LBKq2HQbB#uC4XwbD5&c;S^6vxE8b_Ss?E^pQLMWq^W*Els&#6ptRN8QeguB-
zH~wJWo=|#o`*5VlX^b8`iH=5Gh!U-ZH+@vtWjw4o4k5a3MJ;=)BYLHZdRW?ZyJ&n@
z4!&49oyi_s;8o`g7GZo*g-<PA-Y`%4B-ABT5K@an>9MGZ#%L|$oa)Tn$i*a<kw^o(
zCXl!eUr{CAbQuqSzsCp#&BGgjof$CT%pV9GfryT)Q7~+Lce_!tIs4G&l^<DIYG4@Z
z7|pjkEbYOG#g3^l6MPW~?oWaZ-rigqN^!H0H<Hxu<R#55PF$GfJ{8!0?Gb~={rJb=
z{)5^`5Oksmg3nQjTyOxVFhhY5IiH(*K}N(o%)BAUy#hyYNs8Os{eFS{ixv9dCp@_t
zbTYRjzQCF1Lg^f2!NhIW<%X|SZEBds9!pt)V3kg6?uyPvpLybwMt0O)T-D+GJVhcr
zYQ|oMLq#*8A8w}2Seh(XuaI+T#PvCo$N*IV4Q8W-_*U%1)DpAwx2Vfk$lt3I<_eNI
zF9B?z8R;CqP%=K}S}Z)@j-S<6Vos6MUEC&pz-=vjS3PHtBulwz`}I~;^dYpImk2_S
zXQ>2x1|*Vkw<bW+swV5=?xlujGVqE4!hU}AppH%DOXc`Pwccq+-yIs4Rzq<nZh4U=
zReVrb-~JuX+NA4LMZpnjavqU^)A~+AclAqUg31RpV!jtr2vSzqa{}2tH7S7z#d}Ul
zli-LPYycX;!6*QP81SC_>-?!Er3SOeVr$gt;ls6TiRy>56{C_I-$vU+bm2;WlaajJ
zSB1@*w9bDP#!X1Ly5#adsl8)MbF4Pm3oQzxgvZJM+mnA-C?6U1A1go=^&$s~56~rn
zrAMOM#q2Cs{uYF;*WVrL)KM27d7N(@J{EJ|#xco<?7lCC)19YZYHcumG{zLCm}gHg
zf-bkU4$wT55f$BeFf;n{A!ZOIA{`%}*%1K8rw=VA+W^J-Ypcy1+fLVK&7TO3tJmx`
zwTCNzLz5M*3+<;w-v;~mMfMwnB(x3x9kQzao!7N(XHMVnJ*#A#l>$Lr;gb$t7w0_0
zjU$tyM2`eRTL9GpgqdC?o=@&y{RS%%v|v?g5HLFUlZ9gbJLyX8Nl*Ix<v@tAFGaxK
zKGWY|%su5c!z(qHHy?E6zpO9K4aOF#q$p)!Q?NkI38BFK?EtA5p<`3QZ}M_nWc%!Y
z=B=D<+Lgp|HiHn76w~G};YxH-N5iz$Gkl%*JI^~G%ju4I_S>h-4^!xCozgesao}}4
zOtvrr-Cbf85X2R9UbKt`{qS5aM=B5A7SjxdZpB>gZGdUp1L7Ptl3Jw9GcpV8zA7_$
z2w5jF$Kfg1{_>H^@qYNc7VbhR+fuIikjd`U>5WpQ+i#Tt>T&J^-XroqNIC*3&A(Mt
zhJH)IL@76>CK`8GhSi{*eF}wW0_}}g^*ZKi%A5yZ2@3ojeWb+Luv1?2E6#9;J?A=|
z7vzSVBWmLx0Q89g7%doD7}D_{k#>zk)Oc0AL;Z(@D{8c}2JVf1ak-jztNaNy-QI$s
zMdJwHXXY!+zIFU8go(DKoOILVCmbRF(ef5|0y$3){O{3-ys6@D=uS9+gpiG1j_efH
z8|@w(CaDF6L@kzh86D|qPrcWy45&K%Y<g^PH-sx#DD6lvk{CN3e<bOcKx6=3Cj?$!
z$owZ>e5f)%fLmqLrZSy;XFvj24CW@gC1RSsK@a)RU?tDg2g|m$R`rQCJlw_{g^UdK
z`MRI`M<rz!*7G~ubKV417?Y|xAs8y0z_udi691#-Ad3rKQx5BHg+1)$CH-VwF`WqT
z8;31aM1=2))I_wp>N-{_bge_7LRkEb@!8>QWuMyOC1h*N=R=iuMB)e*k2DP`stdLG
z*cuB!;6C6%@_hmK6&Q!FNIA*+Pu8?PspnG#D^;aOLl#^sbbjS?g>Sv6hScTlFf^O(
z&U0oeiUKq7!7|^|YseBzD1Nk9q*|QzK$0n!_ZT`_Ew-8bGa#L9cI!myPi_NjjK4_-
z+cR#z>#x1e3CU;ATQfiDQY($QJTeyKflPAsgUzZ5Y`#u_niZ6td1w;|_)3D8Ln`(8
z`AnLB?BssT$E}UtJsSwNxbFZ4E+Z6%=a#A06SCW5%UkOr=Oi&{plKo13;<(OmmCny
zOTzygg%nKuPX+{uj1adx)VnOm5J3LAbj=?@n8^26DrPTT3a$4da$+udL-O5`dbye7
zU?n&|L%^)+Fx>ZJS@vENBe7}X583|lLOp#m_)&C77(oC%Hu&T>P%dD7L!=kyk^d2f
z6|M@4JU!kU-JO=M*Q7^#L5vS(-3pwSCBY>>UKn^umFvOO^L)kyM?>zX39)w~cv>gn
zAp?t<=^aIJ_h?@Y2;PC`eL&!Q3KS1jjC7?)F=a9CmsIdht{&GGuUCCHT%7TCsb8I;
z1u+ov79A#nA?6GiJ^$JFhd2y=-ZXlv_jxg3Zm*hTApiXt;dUR|LOEN$15T9k`Q8or
zDi)v__G^&e&m>~M(Mx+A>rno*HZzOBBW^+ofFF^{MBH8YsbXCb)eRDp&=R@vcNu@X
zAyV0s?laQ!I1i3*TfzAaSrLJPEzX8E0{OF?q#7~5kehw??NStwdFo!-&FcQ6H`QLb
zs-WM&SN7{EkD1#i=NmR4NyoppjitE0N8@6_)K5;@;OEuC&!HOcvg8v7<m)}4ph_6-
z2aiV?**t((R-;0;h2X5ThqXm9PX)0o5cMaf1P;CgJxTfP#u&b?&cWAvzKg%KiHKtm
z!q{8Vys>@u)MQ;tNAaaSvwE5z=(H8x<n`Ex!Z{{a=L4`SqrRVt0^e^cWeBiMg87=K
z2l7C}->cjp_Ain-?s|6Jo{~meer$B^S}|;A3IW&Rn)Pw<;Cww#oI@S9=teB5p&4xr
z*v%VGI`Uf^e*LaUW#JCI$JF8L*H1@xCj-3}7O6=E;HPE3ds_Bv<G$4!bcgj$c08*u
zH~um&fLe$m4g}D9qCj|10TYD0vp-7&b3fHEOodRW_crp^t$}eQ2#Y%hB?=wCr&WSB
z_CG<Y;%U6I7^bpu&jV(Z^MpdZm93~(rP5ssH2f^lzic}Kp%{YfIk1|WypMa;LHUOi
zuR2&22Ns$5XN6bdQjQR_e-G#FI<&)Yf72}l@dlq+Wz!~@rZ4Po(qA)CV{k2_^G>}m
zy1&kD4m5sLF`kZKoxHz$y5+ep$o8VvO1WXBJwpyAhAH)Ce1L;ZC27$AJ%07G?AB-q
zigY!Nx$3SWh)rG)S%pPIg<rLo?0cEmP2|dl+61#r6=ThDjOFRKErN{ZJnNXkw9H_I
zrU>AH<HL_;AW8qz0+1m9FK-g8v7;74t4Hyab*n;-$l;8D;S*a!v89K`dVd{8!`n4;
z-4*B3h>{Yot$vj7Puh`OaH#93*8d1=W!<>l8ZZ3*$XdeYpI1ZUx5ijz;`2*+f-(d}
z?A|ctG>2q-W{C%S-|>qF!TGx01gHZ`bE1+$7y<h-<Fo^eUBPQ}5Hp5ROwgtJP(@&i
zHL6KiXn0z4k;N%Od9`eLj&Xm6P2oJAXTFSbQQdNs>+^@JSNwDT7DDzs%Kjfw4c0YP
zsf(uv?gLT&&SaIm(PXjxZ7d#aUKi^j4?F!@QCg*`^e59ObedX1MRWB>4o12r8lI-q
zjWzky(vjC`YkI?H>)ztAEl+a4+f66li!gBef6(3hBj_I`q@!04eIv~T#4YCd_-ibI
z1z3ChN%d$K;jC<Z36{Hrx-J>=+<z2Zn=S-}KrbA$9I^LQ@KKED^eBYut8w>knfG@}
z^XPs|1wI3aF~mFvD4LAWX^yE=&{H<pHl+tw5h8H%heh3P8h0D~*3GkQjAd4{55^r$
z+#mtL-+MkPY1$hW#FnHS8t1%UzVX_k$!B)2)@iV>Q`J0I4R(Dk{?0VKdU`DlK7tM$
zsyIvjH1O$2f4KOYLwhhc55TLfu?r~}%(-?;-Uge>WQZQv6sXH`H-{e@_?^d6yiiV8
zB0m2jEVRf@LD90sr{0AZYuZ?aYb3Tq=Q(|d$}4z$he4eP2UiWifRl17t|CxnQ@k!y
zs*51v#zq1bIw({}s&1uYSF#vRFtUMI{FK%12^O*Gw=yY-h-+PVsj8tzUAU;SIP#dm
zw$ixVy%MlU)xjx$vaopfzgIo2F<=eI4_vVU83yzNCNs0hM@$IQM~FGTb?IB)(}<fM
zHL_#f8Qq<ugGu3|^P<5Km(jWdik}}d`fWwfik@u0sCzQKPb(T>0FaDAQzY<~Re>Ox
zI~M-xipLaHK(T7o!{t11J=%LV+RM%(6Is`Etn@HlFgV*oB$*bqh&R~mHW8Xr<@M%m
z<{@qRFSNZ^v(Z)G59bMtS}tcqeUGQyGWM1loWfMRFYT4y()Mr|2m)}hyOIDJh5`W$
zgFZSDIGu?gmK|_b`qE#Fu}_*@C~$&qIUd8HV7n9%kB~uQ4Zg^Q+HUtIW&QFcopd7F
z#L@V}m6$=n1&V~2m9Iy%KwPLp8-hgdB>V33`b_kqKPwM<tt^k~bOpsM8_yL*{aW24
z6Awu}d8`V47c3vk61ky!+rl8>#TC!Pl&?}U<CDj&BCnv~npB4DJ%Z#&_}9&h{#}F1
zRYf5c{yIrn#x@ZIHBg)utQm;?LIOB|^Nmpcsh6!$^W=D?-_1Oe1f|*t{Y=1TV-a{V
z_bB?_c8Cb)uGb*%o&J52sQFiF|IS6NqJk>!TDjKc;LjK)&R)?$xNy7AL?}BIgEI*}
zbRd@-`=39dW=l+`J7Ub7_O6cjEl#*5(KOOJJSyiDkI(u#g&<xhw%_t&*JoAgA7OYI
zw_a-BZ*`n5*k(h1+}=DY#YXeiZ%2HMeoq0{>C~Od_<XVFBl2)gDGNFfG3dV7-$oqP
zt&MVZk5WNpm%|=wyu=3-A)V6@B}juCY@iDQBVQXblW8BQY#;KyppRjJ(ojBdXd9<R
z$9#-TRMJ1zZc1z-YaK;cb9xp1ipNQ<($sM=J(zD>h}9JAtFenUs_&}&)kLo>?8+E}
z2>%$PtFLJM%Uv3Z0|a>1Sxo;*Uw-gc3@QXN(8%*+X~&9@6ipe!@9ge;(sAmfEaYU6
z+4?BE;Wv<A4cYWBHsgl*w!~o?QSWjqEey5QJG4+WG~9??Z&%t7QWOgC9K)yfhf9f3
zz@(_1dB$H6Xj3=G4yU-C4s242+#TR}|Dh{i8%bTM5e7bw84!@b(qsK|Mx^edI7*;Y
zkFH-o#V1%?-;ia5|5ACSDH2{_yEG-onp&$l!(8O-t4Hc6XvgrD67wrss9Bn>BRqMG
z5a<v1GtFtf2j&iizXDu7gI!Nr81i294NLkdF+P=Z(x!XNA-BqKoe7Dm@?t&q3n}{I
zTA6uJz(S>_kyq5aNZX;&d3Cd-&8<6j+HbkHQ|q<$cqgeG4*E&0PoMl(AO4i4dBMWO
zND-!h*<HgX2FvG`4%UK6$~Lf!8$#^MgSa8V+)CHD{Q$@yL=6P8K<<<IMN;H~J~%7I
z>6+5gLziEilU&^_Re$fcFMg9Om_VG{ojg>y9fM|YMw_*9nqB+hj@$;g2CuIl)5c<-
z=~fUwP25=f*J34`MJvXlkaRqxr|05zNkWw!g;@mb%?54BYdOohXfE0_j$y20G)H<P
z{5&9u0t}WAZHXIDN9aJKyog4-D44~8`3>BYl2Y+bz?I$}Yhi}V+_`YmoQ4%?Ek#rD
z4^O%uZ1<WH+IQ@dNjOMplSn_kKpsW8qB=jVf4tH@ZNE>U?%Bjr01>HT7N9=wMs2^f
zDPJ2dKT^&~fhXoomdNQ8qwX)fsi=6Juz>oE&lPP?FqH)Yu|T2u$u8>WOHKW-Q-AWS
zTqI_(zW&|e!uS@BhaO0_1QlN^2tw5}9QMl13RFBc@guRODR#DAg00kcHsSBuj;>i&
z)#3$$(i-2S)1LhuZa|N~?LwcunYL`lc6Am$+e<o7#F&N7{phbZ?IM^H4ra|+N_|L`
zz5IG8rk-ba3rB*qA<HhM`^U~ykB>IDD~#dGtBEC-B}tCdj^4soo?!Ov;X+^lpX@yP
z`eB}nPJz*%@C`><jkCh$HW%S|*h+FMlUbDnGIL*@?Y>^LY7Up|EYCPDtDLbKhIrIu
zS5*I>(o&3ddWp|f`LnTN#mohk^!@8!Rq-?|_Gqg}wbj&3KcqL8Zj%{3Pv3v3a?t_-
z;wm|~_<=-fmN;!)!|Hx6hKBuWm#x8e^;oW=TEf%Y_^ywxTC>-o;U4zXvnLr2Nkn=L
z_LC$IBP!D_5&rMkyCi2GnQ|q8+z_o(?g))K{%_2_&<b5fAH!Mu!qpUbw0rWMmcja?
zTh8&>0R~6g$wlb(>|?dcT9NM#SIc!4@R@u%JA#ba)mAo5c3tQj-d{4>ud5r^M0!gM
zlzgJCA;l#e=&@jCjt`^!W@xbYcrjbiviDS+*>lC{@?0=if~0=c*RVL|$Iw`ia7SPJ
zJDm^5E5Z$n9y*O|5C(o!dM)kQ3Xe70vV#RZY7W2OY~GhV<4Cb3CZ9ePn5Qee^76WM
z_uZxPy*wZ}UHj#RAmBRcv$<}kYV%)R@xTrJg6RMqqUD6wOx)E@@FrvEKP$1%Iz^OX
zpe84e1jd<H#F|i^X(67WoK<_wtrkn|;lH{HxPMd+akcb+Z?UXdXfF*48v_^S>zuAh
z4$QS*D={?h&{uH|>iwi#55IaFK>ye20xyVX$Ey;i*n<GO9gDnct8YF7cbElV=&vI=
zTK2ZDNXQPDuj<&kP{tvWxBHOsLpW=*=->7@uHHRQ1dFp?MW5Y`o+<47uG*eKhM)@B
zoz2Vy55Fd*N=`Q>K^PgG+D{30`-F8=T)z&Y5NFsT3e(?C!N+6qy~Hf-njAtj70G^@
zu$KXor#~8M5a{TU4>!Y_64WTLZZUsme>+N-&UdsmGFEXIt`T$~kTdVwVWAQ%BY;Da
zQ?#-6)4*Wa36!SZz@YDR6?Ij5O_Y>!-%{A4rC&Vj*u$**!yRSja{rk@Ap`>uY$EOd
z{0S2AJ1t0@s}yLcIL)#=84-M9obO5&r0^v|)oJ=frJd<*?pnj~HG9?V@-8gbXLI`{
z*8?pi|HG}?@BQpY0}ElfjNi>oUIOiE-s8r8e=!Wm=O}v|O)PxSI!sJb4M8QP>|W!g
z><~wA+JoV8Mf8g)l<%lq{yDu{=MP5IhcEd|jt|n`lDjoMJEszX{dQDkdu~sal!HB?
zQZ@Tz-fi#^PLdXVlbc7en{A&PR5>B8Yjm3X(+aj&6s03cDKzfFD&v9)qelxFiol=D
zF8U#+Z2HoUPE*v(u$eALIlS_t!br&P_1jXa$IJ58kj>4!_SSCSr~+4iP9lK=MpEgh
zONFi21jfg;PSGCm!%s7(h~Y(d+x_8d(<^*$n@_lvBP!TOO9!+^ZCb5GgkfV+wxZew
z403wcx0dYzJ&p!^&SNcsPRFm=&pruv{_fOnt;YeiJke24w>7tj^bo47$atNI2(4wR
zvB}n)92w0&W>RJC*>3nX-Nv4nTW<fUm07%VU;Arl0P?yPUM&BnQi%pB08NBe#G%7X
zmj#3mSu<s}O(~&RNIz4eE#33n$s}xv;SIFC41YdbWnj5o(Z^|!Ty8EnWb$INb)8_(
z@Qse$a#PT6jlW5@3G+I3cM!J97Q@Xcl?fvjJ!xGH-Lw$<8>Zdv@uIwat(S<4bBFr(
zGQY8QTfN)K_sX`N49RBoep+7G1fSor_PBurW5Yhsy6~C!4!uxqm=xPz{I-2ts`ORf
zgz3YQS;MEYm?<1ekwpEzguaw)PmIHptgD&OQ?#W^Ke>m=6}aNPaA(lW^T1D|I!BWU
z<B%So<HP=S?#qOA8M}#vp7}`2HDg0G)YJJ5$_rCOXPBv@RHc6>>&UxB`TkQTl13<n
z2Y;|f)U9aD-PB%9MU%zj*jJt9!|%=zGWHS&6S4EBMu%D<s{&=LpM8`_?&p8e4yG&S
zpT4i>|5as4Id$<h_aQqR-J8{&e{AwNy6z;&>Xcq=AK0`dKweyBVXdZk?!NYL+}rx{
zzUA1E&o6rhJ+z_vXWObB9HZi>SsM=K{!s4~X8d&5t~Eb)Q^4oDCS#0@9oT#9zUi@K
zeJ6Hu<=&39bgyTUs-VEeT3W6>+EMx^J}IVh<R-Zzdg5u0-#n@y;EggHfBf&;06*l_
zYLXGW9~TlN{3~s1wacA)tIWQ4zE$wg<VSl#uH*-3@l@E^vpV_juY!}_T`*HSN@_F4
zKI#c#V8uvL=$^vg3UUQXgL2D@x<vTy&MaQ#dXP%-*dv&^T^=|rSO^&j(3elM#QC#A
zLD}$~;u^{O4SnPOSR-HZhy38!W3ixi-+eEH(ntbGO)OpCaOuaF=DI>~!C6nW!qw?4
z^+RjafGLcL;C}Ng8x84x8J)VvWZl?DabP#Js1hVchdHSWUVR5q0U^FEd1N2$W&^jB
z75Z%rfG^i0N=Unu61nEH1YBS1g~^y-eoG#>SFr15AaZv>y=ROV{JdWA!gZsp2yf$Z
zX?Y3YZ_0G&ODD8W@{5k_)zr-eI0%Qd?fs}NkF5b5&B<T^n0p)pBCHH29fXla^b(gk
z^k<m4d2<PA&dA)s-maY-=)tYa|JRj<S%X0~287)`JgSxmcAdi49&X%pE@unJ_I!(_
zF(Wr3O`lVInwMU_?qK}D*3yzOz9C}D9CmVSc#Zwom-j@fZ{o-#1eK+NT({8BD=8HZ
zgrng9%YvC{sUKZl&Shl@GmEH>U%tt#%-WuE*{h3CnSF6Nj<r6Ae7N=Ja?*Zlo9k6(
z1^dK25Z1w@+y-h1QdOYnMe<QdhN()C-(w8EDU++QGM&V+_s|DuURq4|b3=nLi{B_4
zohLx)cpl}8c@E$tjh;ie!X=qeiLqPp_OsJsP+2E;1qouL>tY_`UJk>1dMazK?Vg(X
zMZ<s+@Re=6O0~$$O0S>eZuZ(~j3BkGOwV;rw8Pq}z?Bpn%X<{WEZK421vdw4(y9WD
z?11hQ%6;vektF{5%gHAeg^lYsGp~Ez8aua@{*6)Dz3|utPu3$BE|a7ZqywNzSMfhx
zU}9b40LGnT(WhgW7~|_|`wH1tIq71<e|MojFmTTC2@ke^;xfO9+7HDn<{^4O)B-W$
zkSA_}b<qGl^J1@0!AW2o!zn|J05`*Ff@NETvCjeZn&RA<b(+B6t#p!~WZ&romnmrA
zJ?&K&E(TVOuLd9Efh9x)a|VIGK!GigeF>!Sxc|~j`1jO4hWeQRs~uV0?S**RE{lv!
z=u68xolW>MOiYAL)6&=gF_PAz2m=T{q$uSXkT5t!3_}K5^ApniG{d&O5pwM}eM!Sp
zAV-Fd)jbq?ueiR*3BW_RiUt}qx=6KA2Vdkbeq~tXasAk(rMu>AucX7A)=!_YO{m6b
z6iiHKq|+9eEp&F_8AV9f+RcZHC;Tglb*FfNn4Ze!SSWj~abnMu=lx4mr~&wk9}heq
zgZO-27{^^J1^ng1f+}hTMesy8{SSdKMocYdq9&mLh|9y2u(OR>*Nvf@`rrIf$L2a{
z`kvjHwJZoiufiV#w1Yt95mgyYy<ma3jn;$_5oc5O4CXhw#1rEi8Wyz;k!eZLLlno*
zVFTgSkhbxKQ#~c_>J8UU>-z{#sRz{vxeVBz8M#(=vFeE$Bn_SM4*mwprUya}KQ?HM
zsf{a2DhdF9XHAU5@+474!ZsgnG@^e-|7DUEY5@9woLdJ}4!K|*pBexyI(PlXZuVoP
zYm~Bxv_WQb@J%9)^bkyn$#1BvY};bW8iuVZvv(9a+3^1MpY?od`ll*QOy-M%B?sj{
zOa0o5wjlT;*On^srk1$=jZazn-`h5#5v78{7-=gt<r2HbtnUJkU60JO0iwVq2itRH
zIzH6AlpkH~BnQ^j7ROFLa>B@+O;v(gmtXWa>J0XsFNaS-l93-ze#`a5X#f5hnsRdV
zDX-87|Fa&znBv|<Ss^HvL}}qWscNG7d9t~IQ=D$YXKQbqosfPm7Vm&AV5x~r7w2Z4
zF%!Ct&;QkER5%L7vPT%}@Y!59UhUs}Fa13)5=&l$7*4uivT`+)`~!dWJSU(D=fxh#
zqi#RsK&U$}P9IVDK(VBzXnHR)mHVNdw@B}VyWrwA<PUrSPJE2Z=SZ{YlFIlpSD<6j
zAzOw*^TCQ_w)d~fRd$DR%euxkKUG^;Yrbg{F_aklUxPP&^uIR_|8^D!<{nJU#k5+i
zcKfO;==!4W{3hapZ^(8a_Kx3`b8&XC4i9uKVrg^yt~4~k@uTvynVZdFArC;I8b^m4
zV(>ctriVe=1v|i=d!>3P68lFHPG!1TO1gft?PToM*CD~$5{RKJ1Pw~~Y_}F3DFAu<
zs3?YMD{!F{W0z#e|6xWB?SZ9C7$cYj{wCTh1{Eux==!kL5~1>uONB@l1Ew0rztR9t
z=O6FlR!bgaAwCTeiDPTwo$G2$Ds#!qw3?UKlplDbYroog6Fn|G8)<=l<tiG%#7s<M
zhuR)2ex$#MQ@OoF0#)Xb=m3{ScgpZVV3M9>zj{h(*-F5S`{m(uS`jfsS5D?;UCEV3
zO{103&OdM$ZMa<n<v~(npEnu%m@)g_9i!7BF+*bejf+4KpJ>Hw&C<*PLltDfn}B~N
zND6cr6_|@whFeuqb68LL{p2tES%4GYSM`<225h9rN@&nC!oD$;GCMnp6&86yzfLvJ
zP0B<k|A~BjPI_L}Q5O-LuG4jNCkrZ$)Jp_EBm0eaS^mo;4aq;T!DAo$=*S=hi3S?J
z_AOYyzOJIac@F`pZs0f3Mxd%d5<I@WI5KhBHQe@8t+I8wZDw1M@<+F5k_I7XzfvOL
zY^8+IOHHjuu-X?TD}S`O>{L&`P$QP=W3yswUMnv#oAXLxCg*b`sIs#{MJKeAN2*HR
zwh)vEcPQi`B=y<auxW3|LIT{J;eSp}iT1*IAug8*#WMgVX)S54<!(Z2Gut9}OfM3b
z_P23JlU77AO54luZ+laeu(9Q&Ymzf_f{u4c8vozJMj7FZ$*#b-;C$koU@!_YJpuc;
z4fJ;@KgWCj{*U$+e{6L{L>F5l@Jg0oR;MseaQW|Fk2lXfr4&JHx!i^#UGD`B*}+gu
zaOBNECMHoW7#cM)5a3%Yn@h70RAyu^;z52Cm|*4@NaX*ngyO|4=OL?x^vOHUd5&zi
z6J0P#KINf|Q^2{Ux@GhHPr+x#ZosN|IwX3+h|NW<$!2ciu_rQRU9zL~IGe2{`z#Lm
z7i!bbg(?H9=w3_(cW^3~PIUOT-1=JgU=XI+=gEHPl4eE(v+^_ecx_oxZT0{k1ot#;
zO#`pN2K5QE_*jISBj$a(@c26VtZ}!xLT}MoD0j!x&2Ni?-eH`JC`E!040hv{&YQD4
zP&X<bRmu9+Xf-MJ*Cwkk;=pM%z}h|fv;__vlZ49Re}G7`QShgdh|FCS=`iKg#gBna
zjBb)5y*b%EGNfVnE|P|pRmORj58e!njIA0z@!t)R1wVTe7s^?q6wpY&>re(ku;e*R
z0jic=gRM{IHArACA^&_a`gR@XfLoPv2v!c>5UeZvGJR1S;tb)-bOo9_Rf<m+X5ue5
zsOrrazaU~(Kfkx=%YPC%d!U8CiM+}jkPW#GZ5|hVT|IzJ`&lI~crCh9@P2)ix{Jf$
zp3d9+f)XBqld9j%dw<)Va_Uwu2C|=33@zA%h@R)nIvy=O4pMH1Gx}e(T=9us%@<Wx
zR}1}m9DNxG^iZV&&1F{Le-xkW4K4h+SKJF?#q**L>k<;}9sc7;G_qo-sckoJsdQ6~
z%ggwT9kVx&d0}K`2`)a|9uT?Koy?Zq>`~6!D49S~V2dN=`3r$k05yuZ)z^*#^U08W
zn?gS-lh^MmUNA7_3GLA0%PReOCUxU@2MjWpRl4n}%xn>WusY5u{~)gIqCh~5Ex%v}
z5-wjy?vdW{M+mIbFd*t=)_^Gs>zY>hgWzm|hLHBB-%{Bh25Tx>inF!aeBF`TKW&7b
zj7<6%*t=8`x>cmJt|4Yb0oNw|L~Ad#PdfB|!O&1PIXTq*^x^pTedEKDm(5R~mh(v$
z?^EE`Z--cfwDdn6N41i8j+7Z{qAUS)GN13d6zI!HuUE+naK=c*ZF)!XqSM|$mwZS_
z2oXxbMy($I8ry7ev7TIV{V+&QSb7;wpA?^FtRgzq)JtVn^dvjdO$5}pph&;p{|g(%
z6w?i!k*#wMCJW7fA5(0E)rmJP_3Y1BOEMf-=8+L?5Zur#s`T&R4B60}&x%Ky<wq*|
z#q<|1Ca8^M+x7n}<FVE^k!*@75ZB4Gt^V$JX&Syho&Z+kPXf*(SURv&*1AARkudGk
z#pdz#r+E+DMJ|>2?B{S<8WJ5C4djH=s88(JXtd>VlldYvY964MH`}Ydo5R8j+}mS^
z8%f$L9sKPcXl_TgymQU-uZV)I-2%XBKv6Lo0MYQcH+n!Hg9ayB1`MO0V|(vUUqbyF
z%bR#+a(TB?Si0`rRwCJt$7^rBp^YacN%J_@5M?@_u*ZELdJz)?pd00X>X0BY3q~Vp
z)#=dt51u^Mk_Nd#e`u+RU`_*(qUQ(#`h$L6U8C6E+KCIw2*;Nd5BHOHY5l4UfpRN-
z2+Or(cB$oLJ&<Xc45&C=9vW%fdY5^fef5}F-WHb{6!U`Hi?tm4WDU=c+{VVoY`)sE
z`T8VurGwgMuhqSxbw>R713BPU&Fe5w*n`skG1{=VIOXAL&8ua(aPLgHX+HBGN@rHf
z>WcZ9L5%Uj`EOu-Uk}C`jz>|Ah~lckx2r@wWt^%5RZ$Zhjdw6;;BmbL<c_64v2Nnz
zQF#*iJqee1tE!>j0vIEIGK6Vm`VztA8JrUni3CyC(w2zX*OBs^xa@^|46dPeXrrWj
z-WlHeZ75#>S)(h}+iw~eo|E?8vHJy>Ct4sGR4IexzJ7YAMH`84^16>lWmS4EmsSk)
zPuH&t7^{@ozcdDs=bFnGe2J<p!FV3i$$~qLNXIPto<zvy^Le<Nxn^XyT1Yhh^Vq8V
z4#gH@`7E1Tg>%e5sSXn^@IQbKCh)`@T@GFKi<m>kYFxc+YJ7UpuOz;nwh~_|J9XEp
z7^#IQgH7&T=#tv^?|0m{86wfMI*gj{yFwP{rVbTLQc7lZ?acroEf!GDjr0<ygYLbu
zeI?-Ky4tuhlS-8=WWe<NUt1dYFz~=mpnp%C+VhIF!q`9xV?!um!QF?{1Y?ma$&EBd
z<+osrNv@%~M>{Aup;geJJmA>%EK%4(1_1l#6J~%b4Xwe%jS`JYi8^DuXwjzb{AQJ~
z=!$!o%-2(9>uF>|U_TuGS9eI}gsC=0AT=RHSLV-ReL0V3r-W5*uS7$s;m^iW^oYCu
z8xe?-DzghnaCu;BvYWs(7)&66;i2P?de8j~`kxbs+9zOw_iSE@mepKVWY?U|{KodI
zGE`VqCI=#4&>$p7PFK~dx?m_G;c0kUMg2zObVS$;a0_~@Q(^fFirM0XYADe5oeXc6
zMA2UDy|{RFHHWel2Z@<@z5APA=u;s;3^O?Suh}BB<_+Oj*z-9tWpWg&Tw2BV<XjyM
zgKWI%M-iBG@c~94&UrCM)`mK;(fiNI+6+D+!*l8`3}u~iH-Qn18?SeMmaPVNVHKC<
z9p1t2%GU8I{G?}8g%c0wus9~W$e^;-z#Bh5DO3Cq#e`YWTptxl;+DC0c*tQU@aK@7
z2vO544kW@AtM~0oEB(d-S7_d=x8yo_&q;@n9B}GSe!7W9aGX;~jo5uL{g<X?aJqUk
zA7>EbDjqWhW0>Ux*qezO8%eE%DAuO_Oi-mwTuh`+Ni60fN*uk|Y#2M;ud36~zd8Li
z2A}NiyE*u2C=3B69mPon{nv9ishCB@pb+=j`J)4EgcOTu06VwAhbiIN9``Q$YR7D1
z@K;n!-O2!}6j_jGd^psWmUlzY!-Uo|xF)qt2<AO-p-brq)s>lbE3#tfbuom~ZO|UY
zZ(xe?<mm*1V|fjh{-*_)BmxS&HJsWasl0$b`|%R3!TpIIxPO_$lr*^Z!o~;$bjH&F
zxAn1RH?!eyw71>gUC&n=_m~}0W?*<V%n5abYT5txYxvvjZgC+!`Zm+gwwxCd8Hh@`
zr(2l5s<r=aT98onkK)<JJ7*V$reJ8D+bxR!xi8H(10xIL#J9Cu)Nb4Sz`CboVxhp6
z@6hTU0N&xxcAA;(R^IK6X`>b1r77lB4MYk-!R<5BV&t>@n=dw_;dzrh_bT2Z5qa4@
z{e{cmRe^k3qN6aOsxU>L*oUTlE$9F~Akjc^4`Qh9e|+S|#iPtsmjxPuW_Ot3aB#P^
zTOe4?Kf2@eqYcT^C|!2PRY`mJJ4Z9Gn%2;Em(7jqqgsB-AVPLx=!A!??8|so`{|!~
zN_Q;EQYsJrUGpDU@q*RW{DuZavbdGk9hd2f^0#)?=Sc22`_zm}h{_ld-u16lL>VvS
zx)y{3^6D;D0p%+svWGLCl))PucO&W2a>Qw!lWjir^8^3nFI9p>r}xFFjIW;z`p$&)
zEB^}E4fJHZ6Aa}m!g0jsUc{7*7~b0dIQ3ztEWoS>J>>${*7Aen*9=s~g%!@Q;G!D-
z29oCc$v8Id1CRvn03)3~%Ujhp<Pf9c^BZEMItG5bb~t|vU@rc0Uy7%{Tl|>AhW3=d
z9gJ=SeE*KjPUL<Q#{nGC7b*6mR@#lgNkJ`}!VDfqSh&G(M1oG<tYJoxj3!IS<1e9f
z-Z2yAKHnp~ul5?~wcQP6brF5C+pK^Li#F<m#MTSVy*TvKDyS7_pLEpw>Kwb*AL=rV
zhctAZ1Ob)V@XOp!tjeYdgQAJ}s)^tnk`kxHO{`L_a6MI;H_RQHB42(=YLh_J1Aq|~
zQk;H*sS@<`mw3sg!~K=w<@Fk7v0FhMl5Zl#LGVt5UtpUy^j`hM?G?@G8Hs2#5T{F9
zoqDf;(63|JeP61$QMn)d-i3Ta3Xa1jz@k8O^*Qq4geFluRlJQ(F5COuHE4hDfnM3#
z&^0FaabM^B&QSyFZa;{-XzsonXyOMXa`rG|&QujW!m}bB%!5}lkMGk33!_PM+{<>j
zwX=*CzyL`x0@=N$am<tv4relNqW(}>*S2aw>#0aQJ(6MrPWygm0nr-&1&l8Xki7S)
zvN{P-{D7YdYI&IP$Pje$*V1W0N+bYA?_h<Q{XjwC`mXVmM=cPVeccHR@w4Qs^y2KH
zej4QS-Eb@0SYCXq@|GTsiiQ%QP|Dusx3Q?K&q31t?7pLK-@Vo^$8%em+?(~^29`}g
zv+Lx3TS-md<IpYB#qWk{xbF6-vPir1)$+L1+I=UTO~Sld3CEYRVD5GNLlf^py?^U#
zt7~;Dq^so_C7;-gi{tx;j`6#{fL;TUOhj2RA+6I}l_qgZBw&;2(Glxo7=zwZX<w<2
z7=~rdAEO-g;^GKj?VvtqeEJF|mK{x$qf?u)k5OT^3)4u}oUL5!s0Sah^rQORN=UgR
zSV<d;u4-@cB7Dj)$?F1By|WqM3_{O>b4dy@Am&<t<`K+o30i9LASNe&YtZb9cUX6;
z@tFd>!Nmrvy!}zO`ypK^@S8U*a<c&Jx5*(EYnk2j`R~H(@$Am*hnTbL@uz-{wTpdp
z(I(k}uDsQQXY4h&^1%?Vnp)#F$s$tZtZ7>MZeUt{-&{DsUYFD-|8O_V;1~Vv%6bHX
z5)yS~x?%C9uhm_YHv5&OieHdLVHQroLEXHLQV!P6ID4*oGnA!yUsd&Qj3|7vE@HER
za&igc-|<_dX#e@Gh%)(?7n}`6c+AA44KUQ|$lGsA@Y&?oRQh!WfMraDm=C?cL|qC7
zvBy)}qP_Zn9Nkow*+9P>CAI1TB}7NSf4T!h>BJbvzo8=2NbW}jB*r1?8h?Kx2i=Dr
zrgR&crE-Q<v|zvQeUcm7R628&0gJ&1;JgA%1mZ_8k5f%P`NQho)+-I1hi@R2w|Syn
z)$==UBG7kOr34OY@uiSwX7TW4Aoi>CU5AVMq_~I2HbrD)SCv;2Z*O6wpc?&W16E>J
zx37VzC&ssp+b7z7n?D<_zQrbKV!R(#kL@o(MZt56816yv!3e}X$E<0Q2G)Ew3|s2G
zhDl8dDDdK(pM%%rCCCEY8=e)v+tZekb~CxfBA9z-KKxXhLV!FnejDxbjXLXWfe#7P
zvsL6q0HHc~@ArFqK}PbyZO6nmo11ym)!=+t*B~T_6#ApwO~l)(Y_%Dk4E?0tKM8bu
zg-<G4_iGbG0NiZ&T#pt7dqEI_iy!el`Nl{8e1bnQ{B|)61*z-mtpgJC)%&L1R|rXL
z!l#%>dM>}?Js4;z30<gElKyr2BY6r2{NQC|=G)bPC=O2tQCp6+&O>LvI6?;OCbx-b
zT((SGzU`KnCpOgFZv8m}vD^A$d!zerB%$AjRW9lEuX=P@h&Fk;qH4gMf1XomQrBC4
zuHEbR=;<6|zty5$N6CpmvbQ^43s16<HO9h7ZG7IX?60YNL{?(zoJku_IB4wJQamn2
zk;#gyFvJldnt(2gL=n3$fHL@J+vBPtwhl=#yuRNUOMhI(KfP7d|DsE+e7Pm|@yFAS
zM?IYLvN{_HFO+M6SJwE5g1+NM*(7x_6ko6MmPcdr8zUTSj1Bp;RzlsbO#2EqiVE%b
za_h6O-xCVy)@67je8;a)GT+f)i<Gm`SJ<6ucr!s+e|-XddyR6=wy+u=5WTr>sYZ4r
zvt{|K)HhIz!b=#nk|<{JfWhuOq2%0@LJ;|#y{tktQ)kPmz4q33!D<1?MvU_BoG-Oq
zwX$Lpzmdr5z%IUX#yH;D@AA~-5^nGgTq2a;^T?%!Q8C|5Ds$!?CuCZ6$)7_(#hD3=
z%G3L_yQ%zdCTnK-M~hxBZpZWxXW>&;C$L$SuQ%fPF?IoSL7X-@JyEW(Z5}0BP&^v8
zTkXVYjP!Vf0yoTYGAr)ooIb7&uoCtoA1$r)WG?aw+^ax@-BvsG%YAb-mK9RiO)TUN
z-#-S#8unGs^8GXF*J0f$l`RKPzRk_`;rqs{>~y`)pDzm?)r<eEHgU$WT_t~CafWkj
zhkoePaE+{f!W{k(ivQ(hR_)rJ({mC5no8ubfhQhGr0_RSKE^(e&vbT|{w@pUno~L~
zu~TVgfLbnl`SG9o=1S9l#^}gaZF4hg2pD&!?v~M7t*omjaXV4DEce)5wBA@dbi-c{
z_}hw{#XS?d{(@qu*^YHP0t^{5c;k0GJ1!Pes~Ln+irV@p^r^fd3jA}Y#Fhs9$lv~4
z;8{X;soz}R?}>>)HCBkA4Kc&vu{`P^<#8!vCmo|#*3`FOAG?XBOdr+>=jKkHS|ux<
zH`Z93W3}FAu11cIek`8Quyx>At6demtyli~$$hT#g2S6w?FU`4=30EeFKK#HXenGM
zw_ENbu0@iDhvI!Qi3L$4*IySWYZy05l(UR9GqXXiLDT`U49U&X@e|JhMbizthWFDH
zHF6e9+w)k129QYxPGfZp*aR$2`=ZmFwkkA{pmPnWIsEB(xj>6thglZu*>79Y_ip7`
z11>4hv+ARnBC*i%r8DZ({k@Oqe`So>@0DF?0x~I=$Zp#&RqX1Ji5x!KNj+O?EvLFm
z-2~62tv?F_fBq3~W7BY%qunyMfbD-qyl|qQ{YbHLaMQjj+CGDlC9JQrrN$^;(Gu8m
z)`^eQV4GtsKxbyaFG4s}@yd)<_n=AC@rGjMaQ3u>C-Uz&!?UG}>kP3uE98BdLwm;I
zVDgz8rL#cp#$orCQ+7tXd=?fMNN@SaG|cBKQ~3&9`)iPg?cQhWp)l;K4NjjsZi|8s
zBJ%NJy8hpe9a3$$SpJYAB&}B;Mb)nbKQ1`G2m(Xz*PgCl3rcYsP(X^%$nI9b<fng<
zH1GfV{iW4|Z0f=_pgY;Xjl9&WUVXcR_r*sW0K8DU@Xdt6*PPiQk?887a{^@PUA^&N
znH>aDlk3YR4`ts7Y9nK9{}?k#`z)`LoNX(1>W)|cws(f8PTAS`(A-GCUVZlfa1B*p
zipdv>TZst#f*fo|aC9)$Eso9d-7dEj^jXSHl>!l#({$)LMU&N-6;IvZ=R)52qyh25
z;liy%v}g5Xu|L`i1)E(BQfp=Q^mb6+2rkiiM&0q8l93q6+>OVBx!(eb5ZXj7bii7o
z?~zU^-(!7<MN3;To&*Gu`U?GU1XBp3m~6q2#l(CgJ1X}HN}Tjfe5Y1Naol8c-GCxx
zHsf;@OZKBhSE}viduNP1k$Jq7mZ_Ud0;RnoHKwvo*_z4egf96{YUG<4J^!kxjG;g<
zEm+_p;<FHw62C)BV!qWtyvzOh3`R6U*ncL_n&~)CC;ZaHrckWdqk8MuNu(?dKo7UE
z8mk90NSD@<+)f*c)L26wXLuKEzU9j|fw3y9)}!}qIvnrjv*B?J|Dx$)i0w;=xez_C
zbPZ|c^cr1o91Dmj^xz;bXimZkk;2wvV9vZIXb5FErRH`oi!Y0*l~*d@o8v{}wm4LF
z*c>jZ#K<YxkL)_NYLKmq(Of*0%Z5g(#b}5T32LVAVfDTMRx$~sqFYIINCeCk<kSVT
z+@r6RaxE^FCM@XM+L(wF%v4i`ue3G$YLqL|>9oN{<TK)pr};B<ADer#Q-731pFnl%
zz8$l7eeuqw$a_hA5e%LLExn*aJHb@~wnF*>i_LwQCf~^DEl}7&q-p8`1GtYwV*-LW
z&En$}W2FaB6)8~^EvuK|Gi!yr`9d$Hg1vh%87p^h^Uv5`53}^rUG7Snsz9;G(VeQh
zu#(JLRxYbJ{t3C^tU?dgZvJs!YEUZ@Sm}~)4$Ja9isdx|mPDNHo0QJ^Qa}!_XC=0&
ze@!F21%2kb+V;zWsw%#M$rRt@QYfU#k`!NZi$x9*&kp*@Fsvy4D*nRW;~L`-(Uxm(
zRyR`#XC(mS&CmgqIC@|axacA{3bHQe=`ypS>DSTd91t}DT!tI9V{Tu|ZQX22VNK34
zbcn7Zz6)`>`WI=K2Mac)gF$K{jXn8!-Nsb(u+3haswDFr<KfI<@rc0XD6YoSf2)XN
zeY=Mk%$N-92y)kbTQ6@y!2FeOr<VCrEpTmQNxq(oofjntDp55Q^MR6vcVld>QkMKn
zo?<>$yUqVm^_Edle_y;X-7$2>0MZT8-6)_)hv3lN-ObP-DBXfccS?76mvndc{r>*<
zxi6kqELgLKbN1Q&*@58uWCiiMc>Hbht9?s|eQS70(_f|6weQ5tA6KeS*?NhBx+d!U
zq=P0zDK1Sd{I6?%RIov`%I`Td6u}z=XafHJH~*K7kBxX`TYF<~&LY!IaX%F%J}y~A
zAW$Uy)2xkMU-w6QJ8H$wXAm5n?iR!X>oC?5(>iSTk-pf3(IOWkgj71s7JNjJ&aN?K
z7@SiUrv8yi_bzrlz8|a0SZjYEq`rO2Eway?hyCCyEO?66e#BJJjiyArrnwiJb~*Lp
z11!qHHYa@u$jNK}YWLGFK9dy2_fl*+7WVUOu^zdkZ#6h)28Bw87-~%}I!`l<?3*@6
z`vkE@CS~^pNzgo{!=waT#}%Sp^FN%_xg_QgGD0{!DTS>Gc%VxSUE)j4#AaWn0j7$*
z6d|^yc3UrZhxnQ|Y4(|DWX%Q`E`j<x7)}8J>KM<uVfQ!EuZzim>#rfscR8R_fKpKG
zoBAC^caG}7^$ygys_UY#acsAdm)>tUk|;8icv0v!C}gX;-*@DPGNzEN>Oex5^zKkx
zdEhvd@Iw{Qr!p$W;xwPDYJT9-16)taEJ~U^aUg>`{$vKJwxEdSUB|#*4lY&yB*ITM
zso6{V<A1Z$$I?QP+)PK(ujp|i+VmesAE&~|zkU+lkgbpF&4bf(gf<-y<P5)0Igawx
zP4e--#zAx5@m!}jIh;WMg!b=iTKsfSsgA{@9Ty$}SPVrbdg1*32dI&#Y}252N$I!B
zyNoT+_fQ-*xfEIC(S${hY>+(uPby1-*rTi>(qHOOGV(lq#$mG~lRSNk;lhst>f2~v
zn`|nqaPG38ng~jH@)e`6Z^y0Pm28V&*YCcrdY{#dH{Go`?}_cMr3!zFF(X!_jgkA_
z`2~uY0_wmQ$VJIT`Pbvvq~8fUR34J2(EDSdO8Q;WAG%oSXhj&jbUGRdDU%Q|T!;jU
zqC(o_-}mljrz5`EcYbbn9RA0vE%P<rC%#@Mt>a?tpJqoyf6rIUmpmP}J~p(yJmJuH
zeXsT`%BHEUb8Mw2jgx&t<izOayaFbPbM_PDHQwty+K0q7ev7;Yk6k7xw>6zUJJT%K
zmXaL+W1}G@@_M5`eqmOjaVXR{-{|RzYog(c<a-wRW{B41IL31Ee?jbP`kZH^9)o_K
z3E#S&^#@$$dx4k2iBUuBVIJ*h978b7IpRq7QMmJv9<J?qin3y#I82bwLBb_$5|SI5
z`4A4t96}90$Z$~E1E=n#jA@tA=rw-B&i$vlt~*>^Y6kAPh6Enj>Gg}fK5|tg9}1We
zhe1>*zm8Q7kgFL%42Az#z7y#|Txwou8@u_G?&y=JJ@TEq+fWII#uobgmwP#7b?;uB
z>>ky+)VE3`xJjj=*#M)Pm5@-E)6NQGaENmxNU=+{w$ZUAJkEDh*=>MZi2~*IG!yx6
zXb&fIhLDW8ilB5nKdm6;s)6o~d@`uhEv>?MY#vteNBw8p!HYlE6p5sLIt>+SCJ>>y
zE2`b&Mi;@PV6|$+4#Px%&<wb-7M<i;M!9GRf2YG0-Zab7%XX%kH6on;;UgtgM9nHc
zSp^1isr(M;F=ClD=H;;+!kFr-h#5X^&#n~dasG5u6HQ9e<DFSLBB^{J_2FcP3YZ(k
z85I&r7)=IzH7ASo&snO;AQX=$P3*VXaWU~o;Ey8-I6d}1#^K@6b&2KV9Awbp{kb|P
zms86*+{}w1pPUk&Y&q|U&Am%79RzgPh-0_Ev?SOPUYiCy$Tbv^zUeP9v{J-cb#h`j
ze?Pbg7k5^&l*kbgN^hpDkD@PBr2107Ru=2TInGFUQ+n6^3p1gA|4r%JnSYb*>oC3%
z-bdkS5r+HN;Z^fEC}ox}gqWT+M%Fz*$L!uX4Wfzo!932Qs+GUT|L!Bl)@JM1zrHQu
z(?^&Yi#D4}G3>AH<11Zjot1rA+#`zNh%i?H4ROSBve4+{SKN@^c04-ag`QvXr%`mt
z(1@}Z@>xD{Mwr|z>4&!vQ!x}{$m_s2T+5)Ln@75vvg4XY2ZisvlryZg@tK8%ADzpi
z_ZI2BP-ZiRa7SRf0VZ|uiaLeq9#LR5f$iW;U@qoAUsa`&<Li3}t8CI&mt5n!y=dy+
zu+Cq8L_rIgv**v94kLc~z1XL3i#|H{Nxyu~`YhjQ|5(1MG6a&++bM<K7x8bDGE4`R
z@uS4zu@RJa^qhstAMZl9z0ZIP!&n++OECdLY=-4<2;#q5cFGb^iJ+DNvwy}2u@e{i
ztrVS0g_HP}zNalqJe07R;k29=B7p}E|5^zl!A_`~;w`!R$X%g4fGp!@B4#)+9cguF
z>+RD1$0*J5i5;2qzYA4gFA|IZf>B{X$Tum2c_5v1^^tF#!PeTzc=&rZwZyO6Rws-v
zq94S6c==3)?He=i&P37(B=qg#E8L@U`1HIh%pBpJ6diFct)Ii|^<Zb?cA6*8@zS65
zEf-6Mq&##0R~!tDF+|qMU_s67JsETVkws>VoW7|AmT4uc2?~G}4TSem`}0-!5s&u(
zQ$mKi7A6v=HXaN&fshL;MMkm&GnX()%3T^PLnc$E`!vEC6;{2NufvJKW4}=Ip2{PO
zL@rb<JY_q5bYpoi(?(;`P2Id0|3DJ&o03g`|16C&Ub`+Q1dXNGHp*>C-#;{zw5e-W
z+{w!$F7lm_{5L1_((%UbTKjf>?Xy9EeVsODz$1?DaBuN3P1BbOi6!f}5XrvB)K=NO
z)ueuU1Z4xs;tQyqT79k|oBF_VhMbbB;S$LFjnxS6?&b$e$~&)6a|G;#-Bs@LFR+;1
zoWn5aY{U#z3k`nls)XJdnczN31go`w1QH=9Lmc0cPQNMtEy~c+u)lB)!5|yh$KbZ1
zAxIyvKqui#n4}MD#ON@`A~qAusjb;(=fv2G0R3GQq`Hqtf|$sZ9S~~<n?59+<Ioh<
zr(~!;%S^TB`<sZi3a3d^#=sGF%Gnv=FoH4;q_;1UB0ich6qE0O3!2**en*Vq5brdP
z&=!Zfocuzec~&9s<{TLe4J8CF{xe8udlFGDNtP#t{)=pChlJ4j1^;&R=4aMyjn2RV
zN)6(Fc#DuUD3(})XwKq&1a?wYlLmvEs^X4_#S24rmDQdSnEC=|g4lO9l+M8U+wG*m
z-K9taAev#Jgc!#0;4WAi$Is+xK3e>h^6TN?uR2Qe#AZm08&E<FXP<xazb5WQv3N!l
zgXCy9UZ=G&u=XJAM(1%(3F6h-Ap|OV4-EjDPX-EK23rUF;jRYtFv|Y41>uPo(=k{5
z!XC7Wwg3y$|1j&bRN1|W;fhHqe0AfpY`u^8o7oR2*Ac5p;}bS#C6WTHDtUh51P;EE
ze4PbZylE)+5F&~O*^OqW<PXfn{!`N6wm+XPBht#gE>JH&6=1?{H(f-y<VJlc#356{
ztAbBENt$FC;G*RAFKaG$^R9_wjWJ8vq0x0gCN?9`A<C8o#_=kUvp2I~1hZ~I36%sq
zz^eRz%Wz0HYrz=#)bZyGafuItm8JH=f*577@*jufVPaQ?bJy%x#x8uPt(W2lbqF_k
ze139KQXDlZQrLUYF*M&8K>jmjxW2Er-(r~(=upn}mMOqfp)?Eed^<7i*?&LP{Kme(
zAy;2)ltqH%X_tOk0u_u!j?16z3FcSKZbn#1VswuXf#sOeQ*g*9gCKAdgoaYlWH133
z=A1q73j2N-=bT^kVf<0KuR^{6rXoZVrR!;~Vyj>+&%0U(g%B1Ye0|cCIMZa3LfZ;0
z+_vM9OL-gZ{SUb&Tg4>wAoEAiV3l@)SjaEuo?n3V3y_&4s`+Y*fq<eqlRo<*`ezjW
z(ysB53feW;tfa~Y+$ANkC*DJ2fZUMAmcr6zB#wW16w}&YRjz3uN7upz1*E`1wanNB
z^JfLrn|71Z1rv4N^{)KKZl3P9&oWMx=w!8AOgHJbbc-sF)|T_^@tmQ1J9#(<8B8|6
zqg)^)pHj=5ltp$sYN#;O7^Gm%JogA+m+nL&{ZHWcs@7sJR))RrLk(LZKRs_KUq3SN
zQ}6+zO3#_F&`p}vo#uh{8^&azBc8GoCeBC!o3=Yu);&STQ5zsj4n@KJ&uNaWgBvYv
z3sn{dcU2+rdq+Sf5yGNQyQa7sTHWNO+tSY-C%fiE`rE3o2Ip2x_**m=hJKnl7eF~P
z_%2b7Un+$2LIrPbt3oB*3Ypmt9e+#t>k$|y_t_}UcL5$(28P#jN)Nd)4URI!XkICX
zI^}2=NP{>pqVhm`rcD`d1M-uRaF*=JFM<8qah$R@|F7Y6oa64kZ`i){VMal=%<09#
zv8}HQZ#QS>!_r+=xBmm}S*I|Skf`8o=iN#$1La~*aI#_V+x@s9>f`qz?rtgcuv8u#
zA#J>I2<A8}oPwhr>t7G#uxk|P8*6IXVD)QWOGha&Tf%0=%GK|C>~VjrH!J_j{nJu>
zDF>OTe^9*ULvvzesmh7GjE7Spq96p=jiqaPi%CWq$B9c4`R{2Gak}4R$^-1omwrZZ
zM&f=SV<OVJk5a5&T8*fQKG_Fxwi*1~`p_=*h0jb=?>`doHvf+Vn-}eK%2rNEO*8_G
z>he5{1SIjaQ=!#39J0-o>fB2??&#P)e7n9fsPZ*|W?P9;pNSHa7E^qg8WPcLuKwXG
zDB;b*r<EB#tGC4W^w(Q_dP#<KUG2mFKF9NaQIs`FsPQZgq<Verceql)Zhu_12al?(
z1qHdgkeGG$G)8H!$dYBlN9=05T&Q5|JDMzLyWFK{P;WTEE4BIzrzT%?6TJ~n<_TAS
zubiL}c&=yfW<>dLZ*SCDWE9K{cu5P_;HGcVc#vpp5?{J+Y1d%7S^KE%oHzoR#A~ol
zfR@Rz6n+QETI1<01KT)<E%dl@r-%^HRTwZX52{ImeKH`%I2BIWU+7LK41MXha*Nx^
zBvawqX^c_#{|KWjc0M5gs!B9I{<XAplwdOe=A1lc;Cp8&9eMl9Q439_w#u^rGgU4i
zFN^2vQv9WL>C&MQUM}I1&8Ia=z8Z;5?SCz82Y$~){#T+4+Hsj~Cw0Vc|Log|sJsrz
zUth<?;#PwbZ=|pR$uNrm5$C-#kV5Bx-P}@epn6=~BL0`D;OIEHY8=Z1=#xK*KNZfC
z`3y}GWT`z2X+?s1Suyfy1jyV;+OX<$Nvk7pVeaj^N;c7=D!Z(ZPxvn@6K#E`!e@w9
z^TuYt4|R324=9;@CYw+O*bS(Z6wP_D1kS*KD35<}dWgq6z&O{~0B+E(0A6RkrQfv$
z;VjT9faYY==pBjvfqx^0i_ITDiWw(j(cXO<DahK#PEz^Dd7f7W?eb97_s6ZCxsNuR
zZCQ^@&k3U=!N1$h(EXppJ@V8|67Wz1+n-18wqlMbp0V4XhseDeM9!z#x>?ymkk-2X
z>?bxdJPKyuy`da!PDh>MJChFz<RPk2rBA{Tk!H%e8;2?qtp@&Jc-|%HCg(s<nM+6N
z4=g_KG|nFskEEU2=onsq<t9(yebp*<BQ-B+^?tSYd-!|tE{?0@#@i{a;i=15=*Qly
zL99y*)A58iN&D4*e%b%M>NMzqZ(cQDr*VG7??BpzMx$|vVvp=-CXx|r=+S_*#@bh2
zOe)yn$h*m}A=73H=YUpRpj*V_Hzqi|kk{$|)dI9vrTMZ_)mWjA{xlpn+8u82zZTPP
zo4BpFe^2W(-XIpBd1a!AtukjpvP+B?AzIs86LpH@i~*QrrOfL;fnpjZ+Nq2G<O|Qw
z$$6q9sR?z}@g5V6>-GCy?SlzUir$)!a|B2U$gGjkJHu3yA%=i%78ckMOSK1fX6||4
z;QS1c$wWVC9x?9z=p>OWJb&~~w#Nt^Q2+0O)xtUZNnpRia9Z<5S<-w(Ir1vAD%0}@
z{H(ecR#n!FAcQ7L%Zwk+s)UQuxN7menul>*c3O}4dh4wSyTxVpOQ3ag-kOukTCm$B
zvUh#T!})eTu*=kWBkO&J@G{y&`VQdM0K!zF(uKp8@+dHpcAq~M9Cg|^Bt<@Hg!SKr
zqCu>+MKmU8;ZCYSHawY?MnD)G`@N>oE4Zz^VSS2Jy!*Gi*nE_2Ms+;B$WA(XF2gqt
z>v78r;9H}yj|Gild8%LtsQ?vSDy6Q<#6B^1$es{%X}>7sE10i+FE*|op*VD+q}P7a
z4wOh4mja^clQq13xOb7!#VLrKd7w60$OPdO&^c5FLd=oKsyUI4hqB~J=mSm!Nhfe<
zAu!7G?&+3-2P#g;#K8hd<#{#)qtM?$%yVS@$4<If&mpu{;8M;$Q844@4|}EDN{Y85
z+O8rO88|mGr-jciIBY}RDC1nA;YZ5t9Vdk1BmBjPunGz}-TyPeKf}fbm+&B((F!`B
z=7>hSWSDD8f6TgOMmC?`;H><NKqt?GtB&h$%f;UFY0O)|88n^{GAH}3r7P`C7oNx7
zBwqNhM~r=Xu5E4nq`Lr9wU>7K*M~r};W1XT*XP&lwJf2j&1A!+-qlsf6f8ET#NSJd
zc9Oi$&SfC(o`n)0m`}(J5=CztsYt@Je3sZrt_cX|6lMpjhquV?35X~a?D2u$ZFBOh
zB!v|cAH@Sg7fR}Lr6n+eqQ&!GKBQ|O!^55m!%}xa3icwVS`>nP9!}K#en%b?o{Bz^
z=nGttTq6-xy5DnRHDep4*dgp=JClPHaC)tIvOfX;j1sO<+b-oK*PXb7O}O;+?^kPA
z$+Gt{s;&NaG9+_LtwYB*s`XKF)~$2(umROrGNwl`1y3N=fO!2uildEg8%*~^*Og^~
z9ye!-qcRNDV?qNEEPUi|=OuFzmG?;dKyRd~7g0A1vkv%Ho`U0HB*wT)*BS+9_U?fc
z`@WM&Kt`eFdjo5A=Fodh)?0c1tM@F%j306Gy)p?P*uj1;cfRn*vvP~DGBffYZlcPd
zZY=YHIJbdCBsnMeI23tSn)7o)Fq!48zEG^@oB6|eUfdqaqoXhZgkI~LC!o1FviXN2
znr;lc7pxmhTFha1FZ34YJt;`_#%m}gtNLMx8@m6^NFnC}b>~!Q(UbX?^NO1jzmi@{
zrj78U)>;a`_$z`0Z|rMslM?EO-lX}Da8e6e$h*Y-?Wj46l@*?aP46R6p1Q|=nLRZI
zwswL+PqLFKg)gxKocK&>s@=@8gA`RS#1{S2Wfwk=la|}r`BH7wTh8)Z>o^iEvoiR~
zZ}Nt2a%s4yD6l~te)VBDjFKj)!Pc4JrFTceI!&t;26}hZ7{c8MWiaE{_O2z%{`ou-
zw8N#t(P2k13V`;Yof=0OB}I(M#8{w!!{!|lAGXIrJ&JjJ>F57`Sfzh-4KCVv(m2CJ
z?IJ^Fs?=z6`<n_fD)!&ngppvNwbAe~T{(Vdfq1X$d6n}RT0w?7ftz=k(5w!_Owf~;
zWkEPGl+gu;ty)!uV-LmYGyRFCuG+ynd7!^jJ&J!IUCQT4RwGk&UX>~v^4ScC_apjX
zJ)?Ju?t<FSjf(dP!WKdRCqpm0Iq>ZDCyU2hqIv6axMG;$W6V7Koz+9iu|j662O*o|
znL5MS7B><>Hn(McMCXPck863f$H|uh<+MJJ2XqcvGR-LNLc6yaHGvz8CS~^txq9#X
z+j`i*zJlo=XSnNLEy!FxHMes$eX{?u(8z3Z{8NG^{<OaEwow(GJIak-S@2iPukqyu
zzNokw<fYr+1$5ReEz2K?)t++j3yOg5NBaG#l7>#b0zF<-dB=QUM$52itX8%B*Ha1#
zCKUp1kKqs|7o=uN+s@u*#oxY~bU%t;ZQi*5n-OlSn=!ju$@ka|Uf1?shH*IQOKjA<
zaCBN1UPn)u;iwG|2)6sH*_30S-Q-T!QIcvg`Wl#s!$}TwUO7I9WO+VH*EL|m7(Pw~
zH+}`zHa<SHnY1Qb+w1X;<z7fUY(+uS?kD8iNyx}<1m(nDQa>(K_zOhKq+vL0jh5I2
z-y-QI4<9w&Pb6B1tFu8<NF#y$5I-)9wc30z6%GvzY1<l{Vtz~sxt+QMly1g3BURtN
z%h^0Cta5{O)OUI@lgSCS(|`GTcg^oZRzEhw5wWnU*UuoX<6UQff)O7%`r&MHw>9pY
zX!$x$#-xy)`xtfE#Alyf>@3-uCOz+`?hQehGv>O*g=SzJ{XH-BAyCHClXz&>PXA$m
ziQExk1EeV-%xs@_1Q+FmBL@K#GAI9`>$41<m~nI(mrC}!(+npC(W#*L!Me$c%utlO
zxBXgYUAJCcErWC6tlV`-T4am@jL{4>Y!C?U%=>M6|NW7Bp}{_uWW_2H^}2g;&TfJ?
z$41qaxfL)@bZwDTG~I;GA*HU8B$bR?i!ZHl?vFV4`i~f^jUiH)s+Mpv%DiYx&tv^M
z3HOrq&ZDiP{F<gZERko0(N-hkFjzbLv#pzwn}>;UKAMbX2UHE%I;s{IN_!*^#mh`e
zyUH>@s`1y0<lo**J&FD=5g$8#Ab+r(;$QEG3csn~80SZrqcj-5vTSVfgs-5Oqr!Qx
zK3j!5cla|}fW+w#MwCKnDk@w)y;4*jYqpU|6GCoUj)L`F*)vuC7kXKYqTt}(#{~8P
zFmnz!?1$Lwe>opqjF#@9OobruLZ9uzz7lO=it!R?N9fRX?v|mO(|}GfY-8fB{OJ12
z@p0zg>)OP3;h=z&+p@pL=UU1#IhMxhGb^ufWLg;pu5(AGn*PK6$Y{<d6dXROqhxoY
z;Df(Gzpl`{=HJ|9%Azc6#DaI{vZc3Xw!XdFwvs;Z`4SGoDY|tSd-eaQ<{$34rDYGj
zmEH{zM+=|nx>`kVtZw4J9OQ5~4fY*>niJHOn4LSu;E3U#mdd-%x@bj!h&dnI*X)Br
z2d&PY8f4J@{t`*biT9fO23S*_3XkNUFntLRN%3A60(LIJ9AOwrgLnNh=@Y1^sr6NV
zD%`9pBcLTJd-uBJF>uNdZ#~{TfbcfLnY*YJL3u787b`h>aD!aBtD5N9KOb@Jfy<zL
z?=df1_Xvxq2Y6gxJxd}#@{-j_*X0@d>#0Xg;&M!ga(rD5u8oMX2w*bKMl?@oqXVz3
z52D|2abeU<kr!H)t$VJyvd#VAdHjn#6KdQUi6Iu7H>K?LM1RvbQhb*pnig88q_f+s
zhCrHr{f_L^Zxim#GbMUhi0VP{XBC+-BT;4%9Q+^u@+MBg-aO9Am<XliL&rhm#H{p;
zmuxXxg;a+gA*?uOVtN6}gm9CtUr+je0$}>?42kMaHjL9}LL_%Tbk!>n()2TF<10&E
zzIAl)y)k5G;85!~4@0`jT+jI03uvwV^)|1i+Nn{hi06IvFF5)z9dcL$u)gB%#RIvJ
zFO>Ob<??{|pL#dIk5F<!KM<I`oBMq{puQ^?Wrc&byg$2$?mbR&hlE2NX-!=3n!AGd
zWJzYeCHw9(!2b}KoW#o-MrWUh%TZTZ3~Ku}Ya_V*BX-ZL6_Ys&LJhLZVhc$|#5rZJ
zKbUIxoWVt1<XAqt-Q?LND_mmTh5FGFVVSG-R!TctnzlzOWJa-_Y<ZPY@<T`FDWKzH
z%=2R)(=ee%z=YMO-!j>2J%1P%&~iMJef}MiVl2z|H@I_kU3TwKyr)yk4`G$xA8T*}
zJ?fNDjaDXD);&;1GV5e5>h1ZFe`6Gq5<kW81FB`_96+T+A}6O#UjhmEoS-g8tRfQ5
zZ|}vhhCe1;(Xe}5zcV(ZLtb~NXXRvAEmRS_8DCB+FOYO3gdK`(Gv9hF6n=s%nUnaQ
zb71q|2^ZkX+6ifRt^hG!L`aGZD<>lUsq2_Xz7Daq=dkX49qgGwOUuwKUoqb)dKJ|4
zv*{IhR*jFtit6VTNr93F7m42Dzi%YQqn6UdW@{kW_Uj`p#}~~C?hcEJ>`nhCe}n$A
z76yBc$khjoZl!@Kc#L{~>|nk2ru}kG*Z=%-7!%NaX0ZFe>{VZ{$*($WKz!BB>1>uZ
z16F!bZwK#Sv9W3y5kLeo8j6Eue4SOQc!d54dQ-$6tVr&c|E{E%-8zeZSL}{A(62~_
zHalqp>~;vj`mSc!>?XPV&e_L%QTLxF3E(ks3o&rc@Ye|SbhQnNJ(^-ovVIu9(m7K+
zvI+mz)23O$;;R7BtE)Oo<fAoQC*%9c1^R%1G}gozb)37{Mc<|Rw8bD0Xr)$V#@APL
zJ!orvyFT?bES1*Kw<fs#M$NEiSPMIYFFX_BZFIaH3ZO%5CJdaj;60RY#9=y))urt~
z4wpqK*@H=y0S8$R1$&$eNEKj6K5IA1kiYX)NL7Bl;0HpVmKZBNQ)%7h`U`@02$1WV
z-3D9Kt)wqY0#}C8MvgP^2$DwZUBgDur8?RXwqZiWyM+KFmm2yx+Suy<B1aT}dd?XU
z3IQR_Vn{>$l_%+EJivT8`BWO#O8LSXbcUg!p`P*Yn1X$0xLMjVXwwBq7gc{4e4%UO
zPGqz79~8bXKSpE5?-lvLp76+7zYW+9b6!!?cKvR5Kwf{K@<luI^g-7;wcYAF5p%l@
zzfY6@v{jkDc{OfpZ0@g3a$}?ci6aG4t<2I0CdZ{FDO*ARpoE>MB(K?!SO(PlDu)Yv
zvN2<#G}HWc5RA4A%J)`gw<1DKrKQ@1=1@FiGF<9|7HcEg8#R)2=?)1z$3S{glI1;~
zL^D@AxIZdZH$?%0A6;pMGnD6T&Itl<mI&rqU7miS3ZcNY9FWfCA*kL@@&F7?nwcc-
zox1gr4gr8BDJNOCxih~_vJR;7;mBL0A8Ag8eEJnxeNn<Ub`kH>Rx9T+8m`rhp#jR{
zPaaPYLedlcj`^qFOjOr*I|XkTadbLNyBB{c|D)*#iSbt!<I4FSPUiygf%7KwhKnZi
zC}WPc`u0XFHk=Hh5CE<T1s?_{8w2@lsE27E=ST)l5MpZ7ZjpTeft%a!QcL*Jgx|+*
z!sM|xVdS@-A4kZi72rM-x$TvZ)(g@VV0kAS*Pq@}U_E+@itXD+n}GxdbgwKkfaI_0
zw_HSL{Xs1rQ#dqWtN}f9iaam+iF(0^cv|SV&>VYOkvW?oL2u_CNuiBT&9X$z1sMl*
z+@FkMbK)Aq9UP{ir-~&&>t|F7X9K7FF^Cj(3ZPok9XM=VJmI4(VS*|s9|%_w<&2xp
zYvkR(rMbE3H3U!f3krU`hp4fBpFK6o=tCugd#mh`tVFZkrM>)oc4kD0RYQntq(uNc
z`QHO4AVHIYE1a*hO_-LW-U*B!v*Ja6O4Ez(#Zi-~ndsm7%J*L;tMp=!OY@6AYn}k{
z4-Zr<pSgTjk&2mjC>%>$Kz_Wtav}&gUqSBwBnE>Ak$jRygtwyS3d30m;H8fey?PFZ
zxrdc?VLa0`oQV|0Vcp|J{imhu?jyUmgyx0AswbeX1S7RK`gp;x2LWCdio3wjz<O(O
z`&>mwaUv7C%Jj0)Kga-+D5)^$LAT=|u}Y;Vux4>);3%}5AA<aAALlL#J0zIc38)tM
zm+PDfI>YFSIp=oY|H4)s<A_q&15s*caeSCIjW?lvvo1r{6*YBESQhRR-n!D7WKbdN
z;$*;a+XJ|;l#{jgTgp}_aBAlOAQ6$@B^4#B_BwcWC-=ijP0Pc;g3mQ{Ept`zW097{
zMq1Q^5FZi2EX}%&LlnCdWIdWO_NE4j`?U?guv1wm{sV^9XdpPa7I2WOMze}p9e3WS
zLEUjZZR%|P(X=`lb;w9W<%l9=OC|rimV50r__Xb5ft5Zo)JBc4H;7KJwcSnFyWLbc
z4Dyo*NHzfH<JPgC6#YhQhDNid2K*S4>5+;u?O~9wJm_Gl8BDE#S979I7A$43jqh#}
z6eGSg)oY;@Hu0XtdagWKK8un?SGqLL5c`kk{XhYfN31EvA4)6I74fuSilSX4mzI>6
zo$Wf1p=OYz1Y^;16ux4$kR)`>;!qU%ul;)cN|A~e*|cAQ{V};#8GYL1tg_7ggV@K6
zCMl-j+4_LS)+GK9vF=C5sZtRYd5$0AM5FoYf=!$=qgwK&`*T^x)#L-8S_palyxO%|
zy~fdGYM-SZJz>IL;o8&eNo7{@0=0RYDw|7SC{N6Y{^RGB=|kU+^?BgoukzAyxu22+
zyIDo6V6N*9P<U1;YO9CT!B||SUnRKOEeKU6VHd|jtHb!`+ov9eh;7NizR><g7qWs<
zb(g$FmARik9Tnh^+(o|&3iet1syL&|9*=8f@P$A$VgEnU{`d68vORyKySktF0MJJu
zuUG2AF>jV2YwmF2s{SI*&QX2OCUyVUm@>8hZ&v|*dt}Y8XI@M7!vBc4UW<+Y<4^5o
z;46U~aAleKP@Y<cw((;D{N#8QFq6f#>C3Tx4Vh`yBx~{9nTjgXhdyPe)hS|3M@e=g
zM<_FXLf7>;gSwTPp>DSonFXI1fD`OtHYm^55CN#9vhgGZV3i<Ul7BtBIQ!9X+&-D2
z4g_o~L$@)h7Xt^}xV(e~1A*DXTKHwbW6u(@qD+h@5;DJGxH9cLc7CTo3T4lAArByG
zkX*L59lyawBQ5lz-7Vd*j1ES1M!0Ga8}^H+kvg@_&Gv05+m3;0uK!r<Ay~Cmkcok@
z4<Ras?<Z?O$s~C?FLEFdZd@LTQT+*Yd-;{Wk*|Yd8pfcNX;DpR^qU({D$o1Bp8pJ!
z8ycyyGZLf1j*K1y&!h%L(<eK(`U-q}A(XC=vHMrK0)bdw<ab7_KA$3VX=5Mu$p~kV
z=>eAW%3XjUrL79<ZExeTD#GkzUpRgLVsI~K|NsA;YP-fi8=b>dzOjH7%f0mZqsKJn
zWDh8j>|f_$PT()-Wn7T*90_T}FnjJKdeSBSBI0BRTG&YT=ml8BelpllG)wuT_^^6W
z@U3=384nzCyU2K=KxBjf3q}RwJ1e57+L)Kj>);S6_@390+|4s;^_$qOwb-l#;hO%X
z{;YXM*5El>?l=lB`z=rZXySxWX*U4D!UsDn8#%pFCIG4ubeRMQ*`Ixrzmz7sALB@2
zkm_a#c34ogyrM6-I%vwNlSPkjr!32p{MotSNKEBp%piE0Nu#hc+)g5>-;Gzo7;}`8
zHnNaw*2QqH%_6Gzn3HYIqK!6i)ss+^N5quzBH|$_rT|9!9w$!x_KRjJU?*fg4*{5v
zpr#DVGx6+O5V%@^I|+7>9i=6wlWeDcQb^`MA`~}ZV>n0SC;)Z?DHPsTlS@jqAAgdK
z*D<gnMo)i(mT)i>!wnM1z2+$T=y4Qd0cn%fy0)ZLWeb^v6D<E2(AU2p!?V$k6^$S%
zdmVXcLH|Ft7jQ-4`NWNKY-SB3R5!yPX`xC}o`YKz=!QXDF&T}wvKi7VTN6JtP$g)X
z_CfZn9WzdW$b`z@F9<9_J<XaOH|SxrquajiUt&`nicWceX=}_>m$=s>ue4EbN^I5y
z$?e5~!uUA6kox_5&fbtdvd;x`i_Et`v)i9A#C-3mTi8g#bOdBx0RJ13!UXL>LuV_>
zYS1vFKMJa5M}CA5N1!|-SGhzZBK7svn67){ySdlu*)}5d-&Sv_0D57Sw}C%T50oS!
zkw{g*OLsaz&>QCaLwQlIg;k8YSUgX54O{fFU!*<ZimSQY^#xz$V6#D=6+RtX1ZAjk
z$Jo>{?LU8YNpKseMj&tcVM9GSwR9MT4+&|$D5qqJG6UCc*})>Zc<+!unfWgEwW#tX
zTM))_J3%o;c7N?B0#IyJjE2G&Au8GRSuX9qJ={!fu~&sO^do8;V@H`!8c+F=#zXzR
zLBR8}S59oA_*`FWUEn4AVQZy%CmI{JT+mY*w!~yN-9Vl%R}tM}A;d^9(07Iy&KcS#
z3X9L4J)FZxRTD-L=ZbY;;r%YThR?&`AB!~91L7Ks`0@&uUk=y(X&LfKX7k3Ngid5b
zRf^eN@-7Z&n7cXk)VQFozXr5b^8f1l-*zUYM~c{-zj*yuWCjz!j?R`MI60WMpfWEh
zP*gUikOXB>SXQS>ZbCpT_#;&aHREEM?!l4$`q<Z^j?_9LDh7n7x;n14$n6S5|G_~}
zW(B)>Y5mX45`mhUeC)nHJAB2QJt{vuWbF5fR9T0fe5!GRCM=>u?i6uj@|d_sa66=;
zNCYV`&$A64;Q=tv`O`{w+}CGbu@^IV4vrjq;8=o5Z1<Q>VUR+aNW#@%2WT|EOKQHe
zm#Cb*|75E+1x=@aa+I9gaZ@N>Z(qwWrnYImu;$G^CJcQ7hEvp_nRr6gS(%){1On;S
zmfSWPO+2H`FpXAYpM=g!?&xaXcTYh9HmP8r!{8`3&Ze+SQLZ@0Pvs4CwcwL16F^1p
zc0&Trw8AC_sU1WYOMRVr=lD7q;9yM^H)1bypqL5`cOWhNCCE{j&mz)aRkMh-&$V17
z4pIOD{?+P-Obut>E^`IQRO!(ahnm<3XL)65Pr9jI4mrxR443os;Cuf54MMe)mz%1|
z$6?~q3heU*VY|(1Gol0-H#dG@mno5hLuLJbITr>xo7qn55&!vT=V_fbg1hsWbpDIW
zGC{XU2(g^`WbPwLSSni8&>!iJZ26H%&+Q>5k+<hO?<ygb4-3gP(eW^f2}tzGz>I<I
z_FXt6y>rBQ`eyx4sRJDb?92DE4U8YjjO4f{`s3v@h+}dArb)S;;L7SS9K<uP1b;x~
z5E#g8cIv@<V2*eeLtSWlZ1KV_y|jV?I+5g{5U{je&ccfw)KS(I?&|rpPKc~z_uq3m
z?CkO2lF&h={e!G5v2jmEGp0Xv`s45BL5$lBp1-h}2=Etr7<6?ki=)$~!;{94@zbjr
zDRzv=>+t5Fl)qlJQAEhGXSazfxPCW(4xySdW!GQme#-WwAUlHJPITYsqAb^M3g+;;
zfUGoD)h%FgGh`9?*>kgU6%*x%Gyz3}q?`N$B)i)GQ3a|-!u8(a%+pUVS0&_M`|wUj
zKNHGm;qfTr+eCd$$bp6phWS4aR?Xk`5ypDOzeg@U;(w!s4)uv}tUPo|Z#vy-t%l3X
zlX3j%|F3T1VG5Fqh?he7zK==zm?k(M1eBt0%-kqXYBn`Wu{o5<x8~~z9Hp_RAu1nU
zMwqE;?h+DiGpXozg-q2o8QW-VeIAObv*2pb7=LFs8M<;;?Rvrr;EOh9-dOO(kKWZF
zxCN2v-j;P=OtK?iMjqOLn;Y=j-L*!B(5l`A(LCUu)xiLQQ35ap@vb(GEX(t^4ji`>
zQYg(@Knc-ni#}4J)2mKqeq|dMKU2u@3=c)qho(&!jrBEV=e1(n#=d`)=6?o4A_WIT
z3_Q*YMkWP0kbe(XiDGvKz7pp8igg(~KWhnA|EB}J4hjMD9}-M`e(QjjN>5i5RkV;?
zL8!&Jsgn9#9c)4r+}uliTDRgd$!c>nRc%4|Q=L=}dng2Pwrd^uZMQLw^iNlnrpDto
z(W>-8i?Iz}`p_P8%Yq!g#t~CGhcoMl1>tE+ZE(d?vzEiHO}}Ns8s#P}l_w6ih=aRd
zrZF+53I$M)Q8RSjNAE0y5KvY_VPofp!_Q4lSzqPrPNCQZY-ufZl0k>{bIuYJa(BD;
zE>jV39pL6xG2~KAg|y4iEe;(}6;>tq*A!qfHT+Q_+a!mF1^uiA{~{ea;E7Dab!~SP
zwhLB2iHLutLYwkW*flZW4(^&{?XwR|oqw;tY}E{!=L!R=B1OUhPKR@1S(Nb4;HC>n
z;U#=%>G3qFiyR>6<ATU|IYa~yfP-Y|bY<)+7xZKiO($6|-;_y4gRZM10m3+v8dv|+
zLm;C|R%G!s_H&(-NoDM=Wy1Sj<l9j7kCD)1iLeWUe(yQd_wU(@)})oj6Yl)7^xwTd
z{9NR`4w=(XPV@kGMS%Y_iD>}8d?XeW!jR>IjxFj!c5(}Xllb1#=xmNRF6NDhj7;9u
zZkMNl<=WrHQHZqWvHU_0&m$^zE(FnumqiTtsILko*Jp2MCX*%R!jUSnO{DVxeetE{
ze*Q%pD5Huk*dK5IFMShru@7Wu;rqLE?M%^?)ec9I7)`!Xkb%Yn`?7`3zNPW>p%qW%
zlzRQ$(0hIv0e~S#MD~FQlpeHN8qsp#wPSXz3Z*7D3Ih1RYzE2OOE`QXV1?|sxRnlz
z+B+2hc9?=S-D)ieABlIky?N1-JAN^`M{#4QD*h?zGW5tBN%;6n!t_dY_3prCsNXVL
zwh9&RWT%k^M&x?JmLow{r6l!VXSm%~UkqE8wAm?8oB;4ELD-kI1rsy#vdn)G{T0T(
ztkp09a<sh#A6q=$o+|Pt{}ouTLVo}}Mb<nrxhTFp!06hQU`7~s0Q!keVXvpNj>5Cv
zlb$4;(R}#8BOt+M|ARnX!22D;pUoM*zQQnuavoPG7uHli3E^@^QoAovIrbyH<hdAe
zI{alF*5ZFPoyPgy|K-$vfjn3i)u)se<~)hbU;bY$0EPTJ&BN+4(I^+tW2T*<_u{m1
z(UFt93z~GsH>wI|m{cI7JS@WA=|XL||Fs`iJ64{NSgk-{nukB#*ZQ*}_7qm4<x|pU
zZ(S<q$q3p=M8Up;GyvPrbjg#8<S}nn%XS}c>Q<DI4NGMJcooQdLH<ie;q%QsZE;Qs
zg*fkFT_nW)4Ty<(U3sb-Dg|B(h?ZPI{Uy)x)hOB)Rr>cK&7o#ncth@K4S$$zL^6XD
zxsRyLM#(T|vW0%FY>=%fYkkKSsmz~!<a;;U{-8P)s3@)=JTfT#pQ-%F@L#dr%Zic;
z#6p?mi~V<Aa7cYDNgb>Ql;zj^Qd>-;ufG%i`d#B2#|t8dwt7=ovFKUwqQ_L5$9_-^
zwI+}J2CtiK2GY=eJV_LjY3mc?8zL^{o3I%|pdV4%v<^QHg-G!zQgA<Zq+H4=wak8r
zxdwK(n(ylh%7jzOF~#4&s@gx{pm<Y)XK%k_IMT%@NSwr?U8=gcQh$D1fnPnuez6I_
zkcPtOX0hH7d(R<)i`PYgJXxz%OD(+Wl`k?3%@s;=rfVQ8Y|pXtCzjS}_bG+gR}ux^
z3d}Dbuwz};n~us}|Bg>#aTgobe#n_@EIyus|BP}%b0d+Y?jLH>nkMdyA_db8NreUh
z+6<ZNHeOZ#Z3R7$RTRd-J`|ENu9rtyOzDWg-J=Tk;pk~Z|LcZpn5u_Uw)IZU7%|+w
zB*OiOq-N{bz<22!lHAkEQ#hD{%puFX(kPIZ<)yYc2ovT5NOklC9meve?#%6O5=w(I
zUWbMg|3D{PfRS{={QEtw?`Ifs7dpasx*w@Qk~v<!EK^t@L~YtB2Ny$)x=)$Zv3S`}
z208q%?CkB5DAS@hsDT$(Rysp5n?<QclJ<ttc3u!gGVc2EIF&DQN>hILW)Il;?KOGI
z1wK<g5a*;?@P|~cddF2d7+k2;{WC2r#uOOEDGeh{Nl``ofELYR{bm}0=>U}*2%ugr
z+c4rKOl~Tig$^uiISjcxDN!Vd7A*>`$zJa%hY+x8F!1?5Hx@)a=|%Uq@e@;D{+*e2
zarFPp#z|&If|ZCL12Y_*3DLEk{)7WNchO(cqHRKK7KrhsShW2<07VoVw*QoKng(~K
z`;=39HhA`wT9Q?Yl?%}gY1Xgy#E+ED*Mb2N$r1_Jx%`Qn7anENJscIQ`u%aCt#Q8S
z+e?mkY=*A%Rj+%#ad4)7`swYc8=QnX{e%OQ1s@z>i)SE?bzd-0Y1=iAH`*m<sbk4Z
z5Vha&E-ghf36jAvD;?`(DRz8Cmrkhqi8VA7lbnyz*dZ?X4&pLJ*EM!)X=AI5GaD43
z*T5Hik3n1*IY?@CHpa)<D7Lx?L<nR%^m;@bG-OB~YRttJ#4t30({~vpg38urS2nIs
zCz|jvb)bhMM9_PdGTkyhnfzCgxm1h%A%YBgruvF?IMW;97+G(;lgNYhbx|39&yw4E
zFe!1pn!2cOX<0=a--knbgNk|_966TgMR!<)e(SF!d@B5bb<^_2($M$R<$l|g*Wo!m
z(g^(Ta5Bqk7h7G4{2yo6OImGV6qfyAH%E|%mfKsSY|h<IY@<9Vtg$sXn)Hs2Bt`{?
zVZYgyJ@V}JS#$h*828Hs@NjBNf3iHDGsZg0@-lB<29+3#T&vwgy52qUn|=ebq_*oY
zVEO82J>QS;n36?n+Qb_*CE$1$<N>(S3!@K{#g$FYFIaY`z6HP?5SH%zdD6^>Mul3C
z2c}wX8mMf+<=VzLu!<GvLx-P~-^FVRdED8ZflrX`{}N!<o_@m7aQQbb_FyTaS_fmV
zTYbzMU~W~>5UGG6F+eR6!sA}P9!Tt0cPj=h3O%;@($wa6^N|DYz~JOW&4=>BcZW}h
zd4kL(2)e;I7Vz_{KFkE8NmXSO9?W8bx%<PPF(qaMLM$>_mv2cQ;V><w{l4&#1k<+>
zQ_c4hRTp)vxvQn%G#K%+h!?zA@I|GMz3+Q{1-oIpSy_HE%WtChY(-Cq6u~Cp_PNDt
z54Zc`FH`g}hVON=`%L3B+=xd?0tN0JlUFb&4d-NR0DbA5yWeU}C#ZGo8XR0=Q71AN
z1Gj&A3gHjnD2W?A+^xZHE%!b3E(38)1GVx~P16Tkm3n721n+5%!V1S`fw>KOt&iDk
zl!A3g`kq>Ul%p|L%fl!938x~%g<$v%{oyNY=Fh~%rfsOb|0$}YDxZ4qqq!wM%KIO<
z;Mrq;`ca4>xU$?`V(6Ls^Omyd62;;u5EmSJl9K9HA@Uf?wiGmKVAv{!3ulpj#_kBW
zz2)@vM!u#p61fnUPzi5TikUW?x|2DLF`aC>P(3L(dN}rIDb3hH2HPd3vvEDL>2rSv
z44l1w3o^Et3$p5VL;rhXzW+j;E}twOB}BY&DQ;rwbSKH#6&sD$2mWRAfWBK+UzX6k
znjikWQoPi2Dv};D*(pCq&29>}{>Z_rhB~?MAu#HeQ2HCgtLnC^DR@BjQ7|#QnW}4F
zG2`WGyi}&?q~=Q2nPh0-mncck`jBX5#P2LhwUCDitn-!olcXhiB=W(1WPS3~LZKrJ
zMgbPI%13X1<MP}JMjaR(Jhn7XY~dxIa3N)z4+4s$3RZ3(U;-@4jYo~A1taGJVeF;(
zmuK%(xRuW5O8%?!fXVQr>z3<XiSnQwNY8?P0+(p-fM6T!Pr*{YWd4fr3hEy_@GYfL
zW@$8VxxQEhd@;NT6UQm$|2D<jw{hxsVvCNG?`n7>L_3%^AhH&p*8F1Dy@ds2AB?Db
zR@81*7-l*+JN9hpmMpyf_PgJ?5z(~jct7FycQh@Pl*xQXL!rhi`yhYsz!*;v2EvuM
zu+?bq_h=NCnXB;krKrf3{XzF*0^wbX6epiDa#|w)BY|UAiW6+mJ10b!i%`0>_#X1e
z7{XbjFDeo^6w*ua$%m6qc2JI_?4f+!0aZ+iUj@^o$*5BJ^LS=CBz5$nj<R)7Mk#I-
zYSySU5R~58G|Ea62FuRI__twu{KIpqbBFY2gL~Yi_jXd$nCCj!(T7<pa&!`TDR0kN
zy7oN^@b^x9B5NzQ5;>`+#7Ot$tLL9>G9zhCVw=X{Mo<BF($9bYc_sCS8A7S2Ol}n5
zKCYMf$B^{TcGbstTz|zgGCob}&yuhfK)KZS^vd5M$lczYW5RfZy;bI0QW(tS4nffl
zF0wry3=ORI(&TGW6x${I!q`u)O7`K1xFLV(5uI_HJ6?Aem$LCo4x{M@^Wl7*BvcHa
zP{ewIHf#17ZVS^TADuo3QPws=OMd#mjd}!gaS#0=G0?P@w9JXvI!4;OO0SZ6dFB3F
zF~p$abU_JY3whm>hx^(=`gcjQP8a9MMJFvjKalYaMv3?K6D;!24}zo!{c9iX1vZOc
zWtw-#n6E<FkGTYe2n|6x1f<pQ(`*xrtlPAvo2UgDeUi+;!?@beN+L$&QMN7@a?)m?
zSKB=2lGUPr?rNR=DI6S%uhB#9Z!w}k$s6Zs4me>Lw}~3QSf+%M#Wr@!d?QC+&3W_m
zXTV7}rwTCt2<77aFh1uw;J*;2rAU@HK-It5HA>@v8A~X)JXFmnllzT{2o}akGR@f%
zcg>b82<IG^hFIr?+L248@Q&^aBh*#twTnO+>Lc>1{(c++c|O{*4E5f0;<=TA&dq^k
z)5<PhOaLmWFrC;+PZ$)P3_J7*MucaCTj`{7!br~GIJ2KDm`!A1sqW|c2fp)zZZ;U$
zE+HNaXVwT>SU|-GRQlKnRHJs2GgxSZ5|Y^Oa*uG+bOepaCRU(f!on5ji4VLxbuU#X
zbH-c7H?-J9m8AwpFhFZ9P^{Kxn@6u!RfUK0bYWcEopojQ9OUazdV5kiW{%{ys>Y>{
zzO}saHu*t>sSiSGJwKme|KE@<kcOBm+E#6?l|+op@t0lJ@)zmGJn;nt_&H2Z*;-Y?
zCMh9cnJZ)|8C4ZP<Qs<uz80#{OF6_K4um33|H8hAFw6a+(+?}nss_~_k|FVYk^e}w
z*&ORerfs`@S*ID|e=+S(dH2-@sBixIJonq~U$)=zdvZ6GazlSkn;hqbzCW1a*|Po<
z5)FEvA{E0@flkMf0k`JZGrtq>i>zB)eGBqU-RcMk;nv0+-)#+F+e|Bwck8;23qOz|
z<#c2{A88rew0~}i+c;oo0Lj7`-Vb5<9q=3UGrVnUdbl3qZ#<Hi5ngBf9GPSshx7E=
z7}XEcQ9(fGPL3v-3X8YYwwckR(NaP{NV}(*=VNSD&Hn=9CHRY5PaWZbAt=?!<T=q@
zJ<3rxCM{l;@vzEqT#AJ)@+X>O#Bm|^OG?1Sd&(#ww8?Riybt(euY)NJ33|JET>o{-
z^nn7#Q2m|L{!qE*>&9yTTT99Mp^7V|7m3nB+*uz{9*MfWMPP&)<hCNM&!uR+0p=bU
z9&jTk$P3y5Xo{vd!|gl*jG^JHpW<TPTMl6ejbSF76ha*KNr}@MYkOMqxoZ#!sPJ@2
zI^7pNv)LS!=fCKo{e7_|{<4F|QcsLU`}gs%wb9`fhKAXniA@>Nz;_3Csx}Kh5rc<~
zwN?NQd6D$B(OFjT*5+(&a9nDH;U7I9rxBnI{^zEs`xfy>eD+Mkbn>^bidN{ISXHS1
zxwv>7P*tG25Mu=dO@V{luZ1Pav%q-1r1LZ=<R=KMQaEk4_?bqFxGUm<{_nfXKuEs*
zjNURQ;3?o~#aY2h;3*WTvMD(t(fi&+>8om*$<?9YJPeY|(g?^B9~wpXE_C1KIOy+*
zqkKe5_`DsvyBVu-_BJue3s5s9$RG{8#m|_M#zmv8Kz4Ske6bjjub`umMz;68v1@_O
zJ&I*J#x=R4gQ=X_SM6&($KyMyX@FsmTWP*B1{brWg=)&(R<Rggve7~~=68GWZN7a$
zvLwHKDxvX(I<@(-9X79d=H4_nhLC*U-}Y{Qk?f_9MQpn{;xIP1hh{(YCOdk!ob6vQ
z(>h%3l8C%@`Fd<8q+2wE%hgKL1a5Hl4Oi&*-5i+{O)H1N0(q%0NYF)s`PkOk^LYzF
zg6!Bs4cqg*p*Jr7>Gef;b_?EqE?;-C-4gdmF^%S}{ZF91dE|?fw4bZb!2o~DDh{O+
zvsx6WPxwBqBtEC$<#WC+OtJXq7<~v!Hhr-ydsjfgr&(3D!)S{@#fnv9^c!R&p#b!a
z2qE(gYGv*34eZ-wV27vPRvk9N{|bz{CdRc*I%i^7aVsO>4_^x7@;p`ybY#$!2o2|E
zXiV0>aS&)R(!jJ-b`aMPj!M<Jqc9GvnR}Z=Z;I5gTevEdjdt-&g&G?`BOTNBBw0#g
z%^=x{U48gA+I`aOs&b)4a7!s{eC5`q%YW~z>(6Jl%%dN-wEsP|ZApq;4A8%BwcmLH
zOV2KQ2xZ_n+FeK*?6UqF3T(m4WAX<kL;~Mb;X8`^X;$CZEz&|&CoAs%Aj}!15|Rz%
z_9Mvif}tn*k#*Jd>GLAt>&5y5jNiq4`6ktC*T;QqtF>=C7K9_@)UiM>6nJgsE0Ro~
z{V1SvyZ%W3L}luN@AS|!cM<timSZc&0*C6p9l0_?(j;{d!<@xA-2WzSq>iqmzR8-H
zr)yH@_o>*Pq6>GHW@S!ogL+Js-Ag^n)5d#HOU`1RyJ$tyF{tF!Tqhbxa&(9M9=4QD
zNt@(Pz8XDtLcKWdk&3j~0KHqFrP!XN`jDp{zoY%5F$m3D!SpufPCw*ZB<9H0muyH)
z1wcDA)on+ep<Uw9F5+bAN(i^?WBk;WvTE$4y}Xs=lc)h}>1Y)J-}+thj0GWg0thJH
zy8FlQ`q*;5^>&gxaq?SbStAtY_}K27xx4RmN7ARffM-y@#s8t{s{*3zy0%HBM27Ad
zx<k4dQb0*XTDrSCWMF6zX$k3+?(XjH4r!$OzkS~CKY*iw*|GNObzQJc&bVa6|I!|X
z$<e}2<bD@xUO=7`Y?e*7^}6-KpxOBf4j3@v$p-=H+jp-US7x)CurOS#%=K)3=Zzz*
zk5LC}$^hBn5ox0^f=sf)Fk4Qe#h7!(K^Y-AY&r8MYDHCrTdChMV?0Boo9GCXML|SY
zK1ze59}WJv-NLXPg?v>M4{X;6>m1V%>%>~)gLt1ql|uksn2g@y{3$~sxkuIdp2R|`
zcgF=3Zaz(3cqn9on8wnVBUloM7?PA}t&_WnX61>&gAk;f^A&`x*o{hyfIZ~C&2?3;
z^KTC2%V1uFsfw1V&R#R5?<YfW0FXA18e&=d5`9ia(K0p>cfNpd+gsKI^BODLIM7a0
zU7C?;YU8HDd}nB51A91K>ge&h!RjNrzMeh*Uuj_%7mZVv{@>grkX8(pLwOWhyNBad
zx;vcboi+MzIEDZB!%)<ks!5d048qZRX5=B?=XbAHWw^W78gD~xi}%Dr-0JK`Dt122
z5MP+Gb+J$fN+&DGBs)0_S7S;I&4sl&jZaY>IASVb+T<!87P|;XRYn}FVsNdA{><na
zC7Y~&EN!|kUqLsC+7Vo0UBmikI(DU_0et|^Fza1=1@(y(WOktWQG@h#O|Fi-O3J$2
zrn;#csW&CrcqvQlz@dpyQk1SNE;D{%PQJ3dhll*BUfVt<oVvth+c&{pL^A2=I@;90
zk1d5$6*~K?lAGzTyWBxBCtVSFm7oT6ME^Nl!`?F6^X<l^3?ji;a^V1xjHyve^jq(B
zp5_~$vaP>6WIE0DA${ac0dM_oX?0qgoAysix&KXY66VRw&KU{2uk}vvi9DZKbjOOT
z=4;2kx|-?vDJPi5v)t(NYQ!{<CNwq=G&_r}{L1<?y_1<;ACmt7bW;)ql@^3h2;Ly0
zz&}P_us)W#W%P<QTu?bP9!*-9P-_`CCl7Hbgnm`o?M&te0j2_JL`ehx4^`P98Aw8O
zDovHfZb_^N>Tt6Cvb}#1p~BkxVV2CQD2X*tq)3|I*^DzFMiv*9^{PLux0A3e8A7A;
z(Bq<Us(W!7030%^EW7rEnX)P4IA5|P3ey(DB=5-1^@k3Khh;2;Q01~tOEEKy^pRTk
z76nZa6xgP$`3LsFor7p^B1>~WTsC*in4+n4?b;FO)yU04tKU^Pby~Q)e&|@W`xNo}
zhY~T??W&zy{+rnM*qsI;87oA5R#uY2SFL;w8=dJYv$k)~E~hj&3A^jP%;GYt5P&&#
zz{U~3SA+O*JV{#SC(fqwBEi83z79|9U!~l}iFv#xj>NSfrXE5{89|al_~r}HRO(3d
zhE7t$kxan7Jl~CNeRd>%**j_C%&~{>SdMn?BLlQ3;6C2kIWhK&-HmV)spY+y=q7^3
zMVI`c4Es@g7u*!>j*#H^$=iS+!rX-WuBeo-SX~C!`N601H|TE?L=7e%<jPXN9EjFd
z#|oAE686D=;z>ZT_b(c-*1M@4pg$7svhFedgJqFhAt=0`>SGMwi%l&05kg?4k?9Z2
zw+>MJ8u)^uF7hjM4~on&eQ9p=KJN$Vs`1@`?TaF0+Fin2F2^65yI*nzQ;^>~8G@@F
z80als5<{7y5=6HP>Ho7NC0B>SH-qG>jSCl*CLi%3aAsrVn<A$kIA*5;G3gbbv`UdE
z9>+D#C&LpRt`3lmiRhaOaMC~gJI+5>YL62cE6MlGVz*OEa#omg{TuDcf^y#pTlCPo
zHW;#`%jO_r1e!l77r`CTdXKoi+nf0nAn3!=zXAitFe&J#skMOes_S>siQdHH`9eAJ
zk3H0a$X9%0bS5cN-m1Iyue8@XnOVDxMXgQLtGF5l8A-8?taC9pIF5@yTEBzJ-CoNc
zFRXH#{Cm}s8Nj@mggpwXCB7z{I1RXdQi?xXC6sJoln07<T~ki&2;E6yS!B?D$J~cX
zeobqL;lU;>g}ke^z``79x{(xpz%`VlbAu_6&e*%RbOP@}N<OB9x$)jtjAU+=hhp;G
z?2TWaWE6Q}4$;O|n;)51$dQJTA}_C}``T35)^Y=)6kfFQaShe#)$cm{oq*#z=MyAg
z#0yxO<?fu{p3URBn@GeIxxg&k`n4-X+oNAw0C(|&$~QhG!n}{8-H4Cl4P#sB_2F%9
zTkM%6;yC~PZ88Oszw<=eSC-U8pv|Dxk+le#3l+A63!=3_*?De#^v>wVGclpc*4i&6
zkIcfeQH;AJ`$a7;r$Sb3rLl|gy9OO;r&al+vYm`$5{eZNBuv0k`!&fVCpCxgi#Ndv
zjU>C;99~P%xRR=M4T<~qrKd%UexsAW#!Zt<nva53xb63>va4T-Is3GEtiUAYJ<rWX
z$JFuU^-G+XClUK8nbsnhx<*Fq{e%LGQ%o}8v<<)Vy%9=hwDFp77H~nqfm_<GVy%%O
z>jv}kE)1y#w|go^RerT?-s?o!BAn(d>VpSL{A?WMVYK~@id7+>^U!7KuC+3*9JHz3
zrin&6dGIIqx<x<M*>~#YMT}G?<bD@myx+zt>?AGL`W+?9zBX^ZF4Xo%wCXK>WrV#~
zlNcW-uTyiqqseRSR5H5<pf+Q4S|4g<moAxbe(_oNzuv<<Q%pfr+m&N4bk^@b#{VE=
zNdu55!G&prL3Uyn*w1BYZW~oA=<r%!KG75Sk#i1LQvHi(kP)h@DZcOfoBtey2$`|G
zf~&4{5UGT<Gqw_v9NKCwELePC<Puf44vrqm;VdxW{UxWVsh5)g4ZAmvBKQtROWKgl
zlkxW58^w7{Wl=qgk_-7{@K}TI6Qex^7k0x5%phu5;`>Lvq<JD5O03BUdk#WWOi#^V
zTL=v4Y`Q^>ziyVL^i-qO^L5>;Y?lklk@0xmV;s1UE=a#Poa^fYw>#hO;5b)9OaNvE
z!~Iqr{beeIg4yPwX9ctMrmhWktQXi~&;l7g_1*?QC)&BY6^@8`UVnHD*RY#jWP`J=
zCBCgAZ&hZjzMYQL^)`9PyuO|?qBPuhkV4Nhy^J*VdAHK~UQ}p;#<WSD?@!<Mh+jwy
zMCjEWp=K0dw51XAlG?FAF@p5|0!scYu=2?FV!s!(dnNwDYa}}^(@w|qnoOGz5WB}S
zro{}(QN%HERIDlO099QRDM^gic3(N%-(Y>HR`PScTs9F}^YjTHO$v-L9QJ$m*&Ejj
zFTGk^{PQ;Pr71`g13*sVsByLNX^D3A^8aYY3LrF5{?98T0;g!15O<ID0ooq5Gezz!
zcFGP3TWj2X$e^eBg~)E73%E*#4T9dpV6=&jTfVY>Jj`<>|M!;&TaN=WP53hqkj-`r
zLnshC@v7hslg|XQ7zq*sdYq0XIl>f^M2SW`_^T=R?6_SiUMc>Zjwt>;BA6mQrc7w!
z))!@t7k++dk)OmV{csBdex4$a5ZgW}Z$CFkB4vYvmWIfH{XOR}N{B_UUW!2si0wDe
znVr6Xw$`bb$1}0-PJAk1)C=6rJu1u}H>jne0QgAbfHNfMGbsQ($hR6&*4F&V^2UjM
ztv%80aZUa*H{<gS-v~<6w`$i|<f_L@)zx+*2&J8WA`E0n83nfKYNm<opJtS_?z2XK
zQ>!+JzK?ksqxwx5@})C{ybIhLv*$nTP;iY8-=iv1l|(lQ^<<6bRNR%K{ZKn`*yb;B
zN{jJI1D@FDEw5H|rq6x$B!4vFABg3{Q8L~4pmB5c7cw9f^LzwdkrxU+r#;)64Fw>G
zfEq1NRg+k^Q`yl5+1vELm2Ixs;d5&zpGiKVQf-_n2BS&|t*5SM^SM6#IPOCZ=m0PW
zI3j}A<=!cLWBMH9#}sX;Vm)cKiE0t;-S|(hg-2UT;M!8ltzC}24W1U<#?;gd0xOX1
zh647|Jvo%AF<I)GaP5>zpkK>83?m<`m%&2f)rI@=G*stM%GbTh(WCdBYJkfb8<NO%
zsRp4Rh#Ah5y5H}aiid<Jx;5P%m9}U$jdAq-i-@RVdS3MeH#HjQ5jd#dD&;8=sXEWI
z(O?;!7nj9=^@GqalIVUbOOx<|{6p#kt*=cs(Q+%Xy;@GAxU$)NYyp<{ax_Jjt(hSh
z2VrY~-YM;+Cp+Z_TkVqG<1bm7xIRpvPwk?!&5!!e9dG`ZT<}_Jm}Ibek_gUtnYVJ^
zI=+`q8n(3GyQVv7adRs&_jw&+<1COOUHX4YtMLi9?aWH!oIunW-t1#y$g340!p(o_
z9t_q7sc4LIl5GqeguwQT7OV*t85HA8JRB{oinDNogf~<`=@nxiQ%^)Un0&?%+-h&z
zpD5ePF!~*=5rJ+jmPI}TIVmP@fUr(IFwHQcqW$3d8*Ujp(|o1R5BrxtV1dTf6IyXT
zk3(Kd22rmdg3snn_Nq93-^f{mw6-f#YbS6SwF1{x_35tTFxsxK*=%p_G!p<nn-876
z)aWBqC+rprGE5ZSUwM9-%9R6-MA3};aKKEUIv>>_P2$;>yQL0l=;RMR=US~zF99OB
z93=;sa@aFFLkiTPv@b+w69)lyU+;3b7fVwYaej!hfj`u*t1JaTuqmkO2dFHbzZ{vh
zMo`>!^!-Z;WUqw9ng(@nNH*~dLIF;ybppR9rsoB_W^&<4GAD13hkH%o+i{@L<G!U^
z0jc@CSD-cD@*jW=Aik1F-q%A*w*wg-_+r<R(OVO*k78K?Td{Teyj8Yd_i|>M8Flsw
ztt)7~XVt^I@#1U!t01a5efZl*m0(Rlpff~ugFf9~Qxu<_a1V%wEhJa4S;be+5_)hP
zlc|Q`s`v4}-v-Jpma~s$@Dw3ON@Hn?+bJi*(Hf`5G19=Jyla%~ubs)5sR+>zM)@$$
zdH>Q3_8k8*>q)=R-m^<Zyk6Hp6fDr-ERcna1Lsqvvk>w5Swt`vMj!c+cjl@!`^^6F
z|Mvp$s|G9jPDC#pRo}~e0rSS}Bz@AM3PmC93{rJ~Dk#I@Nh?DBIt-*2^_51w$HSZN
z6Fdb_7h>7C<YP_J|7<a+`qe~reX?EL_wn3`lzg0DdwB;W8!VRnP6Yu;tUI}O*qIcB
zTW1E|`tFLT9qe81<^7w>hd02nF63K8JUv~NrwIo9C%bf5ZFd8Qw@+iMy<X&E-!9Cw
z>s_ltHaNPdHF(S2V%EdikG`7u5n6Z9wA;aRDx$Pbw-LBa@nY@UDJnNQ3ZlpUPmH6?
zD}?1dq37%g1(;zV4&7}u?Nlvp#6s#yCyr?6%)4K?7uK<q>L942w`!uFdbpwO!Herp
zm?8~)n6TSMED~Lu03jLrN+VPG0N*P(0jOMmE$ZD9B|6Kt6-7EOf?Ehl{W!mPcjr3*
zhlioXc_v*n*@SWpHpiELOmZkojeR}hlJSGevO0L#)O#2UyFi7kgyhs%fDV=V@{-Zj
z0m`!IZ}4`%Z`ne5_`GSihl+{HX?a(`QnTM2Uw*5W>qGelaoO7*&t>(()C&`witV{^
zRyO%}of>*8eZWr!sn?%_4vZF)k4z3yFlu~7Hsb&CG)Q3T&XW!-zuP;Z!E^SOdZEN?
z0d=viAOlGna}>%SVwU8mv7;2L<0eTa-;k4sq@>kf59G1@g|gxWS#t}7_xEoUp}n(K
zVg0K&EL0?|mncrxDG;Lw|K6R>5HZ?{q?SU9J3RE(K=e3}19Rl4@dmN_16(9BEuz%?
zM?U-C6B}mqz;V#DMDUp>HO5NgCyY22-H~WW$y>hC<yg<)>W+9+W~1TAR_BM}2AgN^
zmobVnfCv?(NK9gxS*~$5U_GlKAQ4k1EK`~ICktV&{s-3wQusp$8<xq54to->hq3G_
zk2e~>z1w`=DC~N~!{kW5>2j#>%2fR{I56S2UN4{O71_gVIeK_{b>H$={bu;`e*+}a
zpl%Wd3^hKafVz-;&VECraC0j29S9=!8;^@Xg9HqTuDg?6u8-<eUAO+_u(v2F;)XiB
zAB8r^8nQ}Q=HAQMpcKBTX)^#kXOdG*f6~8U{a;CE41JfLpwu3JmuR5<q(PXAK5;@J
z^x(9Hn6)nI3Md;ts)U{s8v}^axiDbGnas?nZMhfF8pTMm)n6?`!d!Z8H7r^*UWn<H
z&ak*lU=0hl#bZ=C%A<2p7EZZns$WUfqP4s6XqM2A>vhF9QocP3Huja?tN^1vKr>%8
z7l0)1ulGWCjj7kZ+JV0BT!sLQ_E&umWz0!Vh(%ez-{=AtDWA|j5E9WLNwv=u6WHIi
z+Hh}LZfsv2-mGU%rAUr_#Q$GojwS$Q#NkqvQFHckA{K=KPZ7uP=F`O{kjCraPzYIf
z>E!w<n8MnLwDq&H|FxDpNHvnqjMYLN{W}sFq?Qul*D9awRl^wB90Wzd;%WQiy!Yd^
z0BSV2+<%0VG_dnrU+OYO`;Cw*akK`$HmT_cZmF=T2}<)N;4p?{*mr<7otAAYbf37@
z_|eUNlwYCXqAA$$Pp%-AJ~)e#1S3_SqJnnN6G9S->QUAk*=@8+baZ(&sJl#6%#gTc
zvgX{;1j|vMtVu{qU3t|Fi|chp*H?R4zNBd@(kdM*v0<-y1$A)ZlyEvzQrzfDQ~p^l
zyJ!%7hBx}*q2&BYBX^|z@raZApWLBL7A|H3fD-Uu6!sbK-{xy7(|&L5oeF;|yJUN1
zW2Q$nw1@tmlMjSj3CIf_2aZ$k?e4Xau;EA%pbp72_8i$-xHc@3>gYbpe>JI8ts1&%
zFF+&_2Yi)cad4sIq20Y2sYu=1DMc4pl~0C<GT*f$)Vhb2wzI-m;W}*>WhAlOSAa_0
zdqYA>L)@+}(y!yROZCb^NYfM|H#u|%v9yg5OpJguoug1CDKn0$Vi1UzN;<T@lS(m$
zbFV|hb!rtqpp!iXT6}7$tCehI`}djrdbRiZIkBSZf#tr-=2jVhWRn5J1{~Q}q72<1
z9UQ+XvE45sFXorD`=IC#^Yet6b5@4@5fu#!k||R4K6~6Jt1D99%lpAd|0gT+68#)i
zlVgUDf3Lk9a$Wq@Ca}uhoOHA;dtqe!5hi?uFFfIMO@x<tbY<vbA%WQEB%5^L5=9{4
zW!GISZ=%yWN^25H+#r8k9M9&f4|?r?KzSKyDY4~DD*a*xcyKj)F??iQzdZ^`?%vcv
z<|(C_CVp%7`|cN-9XY0P*pL9dkXf(Mm@XN3Inh8MI&gH;fFN<RtpVXKQU{5@BL6lw
zVbRyj+0RnOD405ok|@w$jP*(9N!UIR9ITk-GA=48<D$LH?{YHghvkGYW)=&b!5%zF
z_$bxF9M%Y!UFfJa65xY$aC>3i7XoYC0?mNo6N}?DY_+;}+18W$1D;L4Sh2lV3i-}{
zU)x+(5$Yf5^=7!9>O0qcCPyf5Y6@6c0RSs^q&ol0B7HK!n|ce3{Q*tv=W2Xy<Zn1V
zX^0_|x$bN>;dr=O_CaL9nxg*#Mi|7K(oS%Xw(<k{3_>S%gCT0R7Ob-3LpKu8m8+95
zbDTimH&6fcmdr?=GGp@GE~d<>zt*Ymj7GPAyKzw!hI9ZI=7C>19>js)7-X#{=k}TE
zGZ@8~a{0sDx7x9P9reXgVC?do4t{xKcpTkjW$X^ff_oz0^OIU|J3qm-k&Msy0kaY{
zIC_k3QTgFZ=4gv|^Rix)IMtF;Zyu@J7*s1!$Pg+#+qL>;dBqFg?K)lPdwmv*$Vl~}
zRe-s-9@Tum!n9|xG%Y>U?e|KLlHNT{x~;yfLQX%@_!#l+?dsO;A8m@>l^@b@!<PR$
zoOmdoGNI{b6!BmbMpnw4l>X1B?<3YQOp<7WsI^$$OqvQ&+SF4p0(QtnTJx*`|NcD7
zR#VCVMLxobBP>dV`Y(U@T3<^d*dYk)*1YRvsAD#y9ei~o(IR#!fI9b^&2@ZNVlfG2
zMU?V|b=xp}!VfqF0QN4J5ry!nBw<F9X842iCzP*Zc_^>AK>^sm{D+^1z}Q<~lF#5E
zIEoR`9}eC{CuhB}i8P1tUJ9~oqG9jy(;HoZunYFYnVmwJ<plGm+Mq&SV;iHZRr}X=
z*?P+=qL0PqnX2l)N;P-Rcb@nee@1%U4k%=Fhw%QUA|6x5_)1N@*;Jd}2hVf<j!!It
zjfY@KB^b4RA_#x`qSqwpwR1pqqbV4s?6Hf_@4D7_=qiPW=M|C0)uZ{v?m=`5?Si))
zF2<vpz4;_s^NiH1z-o+?y&&%mF1W1C3zCUKEE+2y)$X;*%q3UQc8B4caTB1^k>z=W
z%k3!dvZC^IS{HTpM4DTDy_aXdMimbJHdZqX5}o^j((!!aEqV%Bz0u34`!y@zYlHsx
zOUPLFrl{S!amZZK#(_(=RP|YXzI5iPmPFy+jeCK>-}+MoU$&{+(}4&b_#K$mZj>cF
zcINv6lz|WOF;XP1=h7z}B>=LdZj3>=rHYiQeI9o5qxPu_B{3?=#Sc&zzwu+6^4RnO
z%^UexJ?ZxiT<MW4<1LBr-4K+mabW{4c$vzrxDn3>j+~Kf+yel<fyk#}SkShYMx<$M
zI4c*zckwMHk%Kog*AA4_Z2~FK>8(?NB>Is4zVJ}xMA38maTB=8uTG~%IC(aMTxEwT
z#s;%D?=#0L1<%i&M%CH-57R#))SNmgK^sru#^_VUNAih0L>6fRY{xJrJv+gqXI_7Q
z25%xKYpMp%N5zhDRxS)o&=2>&`D;1H{~7zKgD5mmz8lZDf}&21_oIiXx<r6a^TGLM
z5*uXT*v{II+-~KW+WGZW81vt&s^eJ=C_}m%MbE62=CnoIXV1I$>wm6DZYRPsI_GS4
zsuKFZT{kNiv^p@M+rm`+=+uEf0yi-Rom?O-sYo8!EbcFD7}hT}i&?RH@@_`i>d4(Y
zwA7MlUpIES`GFEYlG3UjUMnj^N+BNC<>?Sg%1E#H)66%Rc2rT2;U}_8@ORS`7mgze
z2<*PAM9r>glJ3|}k_MsRVNnf%<^c<@v#F+rimT`aojMHLnc2FsL-c!2bgZd8@1}Hf
z$H??(CZG7MK;wL1dF1XNw#_i@q7}OF#RlrS{3+{Ceo@jY1XhQsHGZpsD3PXZlh!t@
z(o$vzHY9LJ9zG$iH?|T|S1&7h3q029-gCKKx+oJEXC4au!A<d|El=78vqbX})I;)n
zJRd^lSAf>R2Bk3?**g?{K^TCWbnl0+;);G;#G^MU$;B@P0~qei#_a)I8gTa#s-~*X
zT3;4=is{NpXn~Fi+z;0n3@>qi9=+KW>6xZCAVFB_;g#R6zkkX7!oLl}?#1jF7kZmD
z^jo?RFCQM@K%PKnn+{u@-(z8jL-|T^3q>pzKP-j6r2dIv;dK@Ok24nR70>%LYJ>6i
zrjMlkiV6;+TiaYem?nl{5Ka*ZyHZ>t+L9_9H0-FJ7)fn5uWGiBfW#oykgZh^%N({P
zO)-c}8&~k^dlJnDY-hLPmya!2K|)>H?$$V}XgD52K9_cUe=<QcFSDP-hz#Y3W;xO&
z!K_6Ca{Ko4hg4|mWAg&SKTgo!L1A$AR&K9XI@q#OPQ4H|WW*5I(q<=D3eH)tCz0}J
z4_;DFjfv!N;`a^1B@zta)-ScJmQ(NNujU<E9RN&I<C#nzjmO-ut`01(5Z!M0lLr!^
z*YUhUSo4A{Dos&hh#tBRP3p^TE{=0Xd^a)vyM<~6UxLTFzm^J;jUD?2M)J46V}*Bn
zm>C1td48ijUOQs*L#hD&2Q1|3#>q}@o&*E#$J*2bxOYMAN^I%KLzsD$oMzsf$Li%b
zEu34(Olm`mE6Lv2t20{oGtHVc;eBL}+6IB;3~Ob?d%Bzby`yPCwl%+o1onl`#XPoU
zUq(jhO<=m#aM_}`uEqj+)fVJ&ZTBtI8s<*yTeuoucKdDFBW=K!XVIqT2Qx}v<z`w#
zEQqe1^rM7QkX6vK;DZXDf8#Ay<x|m7$r2S_R39|EJ-zZhc#hr**!3;c#UW}v9v<SS
za68+wdr7U2{h6ZnmWWOm=a=->i`nUl5$(XqL+k0EzT?)ihKuxt9npG)lizX{cUX*?
zszKr^*hEpRRDnO+V{vIK;Uvqcks&2CFes7(R=)~q7b>=RIqOo`We5g}qH#a2bw~w<
zLWH6g?gxiNofAj5Yo5~vx82rz&8s1bl}|2upJsgQ(i&Gp*4}csH7cbQtqJ58H36VN
z07!6citq=ncW9G>`bC4p7;_-9hj_(&iBergT^LkL@`V8+?D?hPX?7Nec1kL9q7@cd
z1J@uTZQ%DRM9;7M7146ha<ipwmsTkICmvp`XuK?kyUv|v=f<75Q^Hi({f=1Hp7b=a
zV5B3wwA+JVO1)ac6H4L)b80?c9Vc;5%=y4WnIInP*YEFk>~HX2y;XX7S~5RfpTyY-
z|0$%Aft*z&*#bZ5TXd;6WvMS^m9O1k11G-cSUB6z;z49(wKKZl5!;Jt9K5dfI$8$C
z^tS4CiH#qw$y$ABO*j@2a;yd4;!bB;N5QxKeHpl=#PUy#^ON1jBuy|G`Z0<>Ta!b5
z=4IojZ;0NOyLnxoW|{60%ZrVSu=Q@4#t5ux?cGfZM%JLm)Zh2W<))Zdv;Ua2a$|?z
zI@p_=Y}UC~`D}@}6`R7}!kky5=DWeyMDR;yhW!h}jC8iHXdAg~YRrV!%#xkhr~9QW
z%WK<~Z(Ckv@Nlzb-f%*+SL|XJV7+G?4JNxj`}y9}7rnbjts2+B$65>LbcRx#0Xp*L
z3)>iT-c+U52;&43+23cf9{sC3w%XGL_#TDI!YZss6<7?Ho_+Oq*KgE&rr4VcYSu`j
zbF8ylLR+#ePcPugS5_bjJR%Sr8}A>TTGQ>>5?5<=N;>_bP99IE-GQlg8h&N){*iAp
zl*({*jdQB4_7-Oagi+RSn`&1-q;ZB8bU!!ET5om&$-k>X<hhH#-JkD>Cu%;TKgd3>
zZHJIB=k#8cFIb9SdDYJqiykl2r!&3SoKIiV5vR^%++5{#)?EEvo2HmQ*o?3DRM~RU
z-l=7GUaa>%=E6h}-hAGM{&i`#TH%e#KCrPXtFdoTV@vWfG$PYqD)uEizf0>GlWi+C
zTwW`EcALrlNU~JwNdH`w=z6xRa+Pss<~rDBmodK&S+tVCJ{4`yY?ZmX>>+E;E+W9w
zJK-*0U~1K0Cb7$0p;&iqyFdL&Fq$T-$NjBaz;9<6GyQ%xk*Q+t#5GdjlO{1plAqEv
znToJn3Q5$gam$;X$th|t4}%e3^^1vzVPGIv#iL(Tc{c-JpB%faiVvlqH<I{tM@RO7
zpPHLsV)G%9=L@cua#1)xTZTS*H`c~5Sd_D_RP+Oi?`CJ>x%xx9(@X;cN~_TYo$vbc
z;cd-|()2h4au5(*iUa8n13SPn!h&MP`@?cEW9#pw-$DBSgd)PA{ix#vr_Jc!P07{*
zOWab8@{CjKE5n<i8g-Ggomu;?%hIx6mLB_5M=LhrAOug0eI=|{!alo~8jrvzOZ}nq
z8GCz(WLv_O^1^}(h<F8L(DskI;&XgULHKKxFQ6D^ZVqZ*b&re;BtNwVClaS9kq{K>
zGR5WRKTaC?!x~Db{<tva5|5g)x8*~m6EYK|V$7E#$5;2`wRb_(PaC3`UT#j^gss&K
zR1Dae!&XfuM`o7;)S?q*HGQ-x(vm&5ts`~2_fmY6x6dPdh_zuc_l$mu2>=6&DrAq2
zN<kh@c2cwR6b!+~2`%<BO#BHqHCBcPjj;U19`>1J24ZpiYB$<)BT901j6VizA{9an
zqs=&uV1dGfTstC)OI~ESquUL`jXAZH2(pCd6!{-;n&e}m>Yfw-G1q@0@6lZ*vYT-%
zyAhbXx+I?=Qj>A}D+P)|k;IWs+C<y|<ucvOyS{X*B~0TeC6}eIVrKh@8U!(qGvI2t
z_xjeF<KJ!WZ`=~rkvE6koca-Yy*}OCdHck{+cYP9HS#<S_4&9bQAlTslPU(lA;4w+
z^0#$*el0SWYQ#+mqrj0s)AadA<r;%09i&u*UHPL#>%<0N{?=3s${3NRiltRNL&g0r
zuSp!~>@l{yu)I6(fQ;N*TZjT#GezT4q<3DebvF1CpMxDhOA~8BU~uK6rB^c!cDgo0
zPM#8J?ppbgV!RcHVgu0{!ylt1yP(NcWa2ICfzL)|skX|Cf?*d{cT(4WsYoUS2q+QY
z_#=esMN(iaook27=9m&v`2D+%wf*e`3+=dA+c1u9%ew2+97f6Y!q;2w(pjj*ieDqM
z9q)5*YSeXNsbvNZr|i8Wgqq5>W>1*wAI@B;nTi=13WZXjFFz6Qo|uhOcE^^-+>R-i
zOds3srLxXOI;5NDli6oB51)o`HDlrf0S0K`P6)Ao#^g$UX33IPG-IPe50&~!&w{Te
zdoz6@=BJLX<Q#@0Q!~yQFI!VS<N|`~ias$L9>vjfarTPiZt@R5O%T5R-~n3Q_$_Qy
zN;!32h^U=p)P@$$HCij*gKyAOhHf3!jSq-;Ka&HEO|#hQwbW;nZztAD-LJme7JEkJ
z{zb-%8u^KW|2{e4zQdu?3mLU47bA9(E9oKZKY6d4f12#=O4Xvpp(AvOGcxxfmKIrF
z^&vYIb4R`*Z{eJ3UdAmj?kftPlB!A?ua4Ryh|O6dg&#h^3GK8K^F$T%+R@L-HGL?Z
zjl+MQ=m<fqi-_?AXrF*bha0;0c10RRz)L-IeBTTz1uzj+!eAUO{or4BHx9EZtUpqy
z9ebQp$s53c#~bA`S%9zgfFR|KjVpbIqEPF8tW<&Bi2TRo-9$w@%v9yu@ix=&eMW8$
z2+uWH@B<k_+dRV5H6Zs?#p3L?Tf4WUG`wkJ8)==t0bZq;8RmlV>Q0kQ1P!=Yja`S|
z`L!QoxTJ(lK8oxJ=&Afbs~e6|HH{9{%R|SJ*%Gxq_Cfr&V>gP{&@ZOiW}|rE;p&?|
z1uQAZa4M`f%_MX29<9z^(dY=!m(yE|N2yEM`sIU>>M@dU3hqYs0`@~Fg#`aN?v14Z
z@>oa$PKTv*^;b^>;GKtM;)C?n(XF)aN9$}>3-IqA8o+2d$JjRL)z|mZxB`I~AnL?g
z4d>Wvr%F~d8Y$;)dKte?bWASh-}_(|t;QJcK{?%X(n{$Y?i6S%kNx8JP#d8@X}VhX
zpZNW#R6!-YE%neFnLVtIh<mJiJu_MRa<b!3qrAj}jyd7BYhhmvV4^G?Q1`*_t{F5Y
za-O(K$?;s>1$*x+R2g#QFfr@aOvOsLB&#_W@OzAwJuc~1n_ie~MQ@3-aHJJ#gQye6
z^Dx7*G>2D%S+by~qz~De!oH9d9=u-yeSCw&yTwZVT;jiwfpsteM9BS)m4=0qG@EJ{
z0M{uX=%k_B27%1N1)@dJ23G9|VF`6~73Gvn$!fAIqhv#j`m4y+FDEx)Q2YUelFC7h
z32EgYwC(|>8dTzNZ@(Q`)7r#ZaD$cvuzG71%ZPNXH-29DUyE>|=NN|f*~k6_r2b$c
zTHD>O`5j2p9Neoll^v>NuX66=%Jc)t`dqxx!%*$=Chj`tRJy^W(7r29hUQN=9hd`|
zb`aZpzwa7dsdB4Be~g-v^VqW+Z<7LDTgSoa^i8wZOL2Y6jbN6VlpGs&QV_vSJ+Jp>
zvZhLr#ZSA3`-%tDpwlg|Bm1JbzNy>0wP;>@mScZbaE|YPy6+RTP!dH`-grheq}$sv
zJw}?w^dJV=gh_ZD7q0de@-<OuHI26j$`=o7`4E$rTrN!@r@sTJJfKxG+R`A5%^QNn
zqsF!$_ccteveURjlx9H9S3Y?U-y#+AtHfz1{ZtUY%K*muJ>f&iYdlXyF&qy=bd<mw
zfJzkwbwFHeo+KHJo)IU4G$1nV{I@A9U{Klgg$oCHGxV~h%{tE<Pc0TYcCPn>i-y@5
znV`XhoXXr&v`6jL7Z)1`>7b>zYu!z6^?F8LueBFczBVp#xIj^Xyi-z-HcVOcJt>QG
zPQ9%YVOs`(`}d;Ld!m2(<yQZOb&9R}!G~}{@r`T#5zqoJKM#}2_`PNYkbDMY!Vm(Q
zHZ%-lST4X9$3FiRRe;}Gdxu0c5KaT6FVYESI&qB&eF)-R85Xc#*NcVKjc6Kwi`lO|
zx**pw|5_`FlS~Lni7^g8^W?@AX_YoN_Kdvi#>dtCXYnkhHl8N%M{9IrrL}0Cakyil
zaWXlU64?a<k3BH{uc7qZA#K$BATNp!!c?;kUn%<3@=zIvpYm*KhOoW#4CGa$&|1dG
z9ia7ri17ASrysnZNisUjmt|-6kCmR?pwv7YKj%E$lyvf2&GEHz!iSfQ-XlTv7oKR+
zb-iGAYwi@0KRqQaHZsUWL)Jvy2X1vhm1zHX=&6cfC{lzIfiWh=GhnUm|DD3G9t1Tz
zb@cbrSozVGvCLT<_gOP;_xm!gatD0@C(&7<f|t)BdbqO$yYVQOxZq#VR|^OgIa}#6
zyrAUth;pUIFy7Sxm#@8(C|3HvzE}g_62!s`!ZoyTm&Py5UWIWhi_`*#4Ht_X6UK5R
z_sUe?=c6P41PTTyNF(Qa?(G@syUML$&Ad1A4ue?wB79*X$NjU1$2TXhL7GXm!=iW8
zenI8Bq$7rGOGOqn3lt*=={C_Me8B`~Ri`hEkNbCGz4^Sh1}&VOP1$7D+^_1Vk2WL#
zf;ACu%(ki*@V&!DNveX}&VT!7M#)g6H4fF}`~~ff_$}GrNrhk#RsrpCeis7xHz)5(
zZKP}LrEy&aGF2xa0sD|Lv6}2~jLF)M(eXceRgWvJE6pusF8c}6)T8ld4DKOHRM?M&
z{F26q7xIPfB~HWnpYd>wna&ER9YPgtwnG8U8x&*GOV3-bKes_ROSTlXo&^zdV2KG9
z`zxus|A893@P!|Y;Xrnj=iiP~3c>k4?}N7wy~x8jpHb@#*6cy%Q9O^4_CJ$7EkHiM
z@e|cLldkf=A}TUjZAB7}m^~kQ+lrIc0>bsL;2u{N$KeEXbHGSOdF1<xVh9GHfFk1R
zGRF^MVGYDnAcJfWP@(rp#SH9Z_Lw%>@3G8UF8%yFP`fNGJ+Q{RG^L++0Jf_Ty(wgO
zAkchL3jMQ@Qsav(UmDL+?M1MMxT)=2+sAN(<CjO~_wnLvf3IznbT0U!4`&rncqp2#
zj>rU27orizM>X=$S5zle_ZSn*1q?~~_q$owq;ntxcWO0CKEdAY5ewB|_d#JuU`tn%
z`|&P?z=hUYeGs+2&M#R4RI8<9BfXqxuvEDD#zQHvb~a9bz2#nq<zD5K{k{*RJvNtH
zbkg|7xdu}Iych|oTO<Lhp)j;<IYDNrB*CB<s3e2Gmh*R)rYY%~GixVnT-lobNjaLG
zXV}}_3R6J7ua%JQ8}t8O3P>GbiTEHRS;+qw|Ly9uAx!cn_e!9-N<SJLTdkn*6I2er
z0CsnLHOY)w@auFTzTk-mto_fb4}GZU&%zAJr^U3F!k?+3O6C&?M04nC$9MCTCX^Y(
zQV`w%^#BAHe}^vLhfqTXKzaKn4=p0ie@6+<MuhZxBu=T)n{NT!i_N7{&sGL9gZ}$%
zlCGfkxeRKEK(a`#mPMCt2XZ!`N4Wmyv<CgUN7dB(r?{maMZv}sFd_@n_enr^FDR(8
zu7fS3*=f>VF;*REBMjA18aE}gOZc<nS)e*NWl2!i{S$2#`p`r=8Xv+6h0hb_iR~PI
zBbh@04Wm@&cYH3qs{h{$kPd(NI1A>%+7gqrhF4K$Dw*$;BijW1Z^s{#`?F^IbrZg3
z9u(kn3J0P|wtq!sQmqK04}{)!<0RWtvzx$}4f{jKO{XiQ3AK{9XQtFN8N4q>nQ#9_
zuD$EcR&>TD&Jgd(ctsmzqt6{~jIn$4!kzWsE(gB?o(XW3|I`w#X%AS7(iFH`{5QYG
z4H@n6?ekwq!V`M~%fwz+w~loCOmb9-=re)LBpTP>i`zZ@M7C_PCDmZAJ`<(dN39{n
zIA=Mb-_q+ctoLYLK1X45PSR_-zH-Qdp2gL6+%%3_`2*jDDi_-iKJpQ5stey<b1DYQ
z&>hr3QKX$P%rL>}Tw6&3v5ce}!Reb_e7hI<7!xF=iIM2!)(+8oqXWggAdMUoxuHO?
zYum~iSJjl_je~C;TzV@ALay;YI~xQ7A`30ZPNo>Mp)Uof(p}lSLh2UZx5_3j#-P>)
z+$yc~VrZ>(;_#S?-c1WeYth*)7W2r)dfgy)k6&|q9n?{~p*>&rZ4&wEtLp}gH7Bo?
zUWp3-|8xnRzA^mqD#7>10*ry{A{g1PZ+=nnsWROQ^s*>LH7jXmUSKu%-Q~h0&1J5Z
z4i6`_CTn5dIqhaJ;`tBc?uXQ#2W`3t8-4AMTy;1WovBPTJe_x7Dq{pF;H*~$a=4&S
zDMSQ4|IuXcgaLYkGy-U-m`AT4c*#SdT1p_80V_#u@Xxk{w>}r(%LGh(-eIi6XY5g1
zV{m&Qehml=-tXy6V|FjcNei9a`MGaoS&ifs(&;$adFJ@EhQN!ZGEN>K(477uD1{?d
z-}(B}pGsNonjicf7f5*ayFi<8vA8nTZavWjfvh-3Dhf4Uq+ArgbOy;m?4AtrVcT#2
z9P)}TB)@|nf(+rqeD8{OL=x=>QK+JY{`v4y+{A&zlULvI{Qr46dPv2169|wHfLiwz
z6o06fF-r^P2O6iC0qe)avObO`%S(mf^E*w3Z=>+#SpI@meJQmW482z=z01;Bzv6#P
zGsjPNBJKS>CZQ5N--(}?Q&#i0{Oq*|pwK-Tur-6y&62?3B_)=zP_N~m1^6jvT?=dp
z?g$GyJtC$M-$5+3dKHzy7}9g`?e}Dc*CT59gl!yDkIPzhX4TR^+_VK)joPZPA_1Qq
z@n0kg^uE4wKPY_N93Q9pe-A-5L{17=J^E`XzCw>;c)V)4O{4xVSf@Y&YnJ^|Tq3)m
zhO<E;(Z?s!3Fvj}0StfF(8AYGa+9sM>FKQniJH*$U74D7?6yc<5B`Qdwa32=C`aT3
z062AkRYJ;BHwJlk0&^ypUcNKCM&eBwUPwPvvR4+^&Z^bytbo|usXq0B?@MQ7j&8mp
z(f4;|WOyZYFo$Nr>=28&l%y>zEybg!G{YZb0hYUun8lJDz$2#9+WCY+6&|SCE-QLZ
z9_2+QT;Jw0J3<wXK@D6`GZIRqZvqf$0UwbW{voOWL!gY4{v6M8@nMh-J>eRAy;^kI
zIR4Wg+Xo9D6@RWoDrup-R*V$3@i1}5_=Nq>Emu^^YC@hq$ZMR{wc#|2->MY@Q9yAO
zQ%hx$O5&HC@_Nk2-obk9c*mp+Hl%cWB~i%6#ixG+_{wsz`m5WfRzH?mIVnOwp`9(}
zh#FcV+~rzMqJU6_OD6Y&OR81~(x@u5TaJx+RcM&{2`(DJ5z8p}qnthu!^EW!yBBXp
z$xF?rev%2W{%whDG`d8^dXpY@Y@`VOyX+K>-^d*U(b96r&a=d~^9n-lcTh5C!4KXS
zX_DUO#a{DX-LEZ1iT~X-mtY!ay0>8>1YH&7-?4O;q>KmtQyTpIN?$~|P{sewId>Q5
zeE%EDR_SKQ{`RBKVakvu^Gzt$_mTHLA2?!f|Ab2s)V4!1QTf7<sKrUe&8d<s#aZZ^
z*yK^6t?Q+E=^=_bs$B@bU0MpN`J3n4PnwjhLBvlffF%4Pg9jYL6LZ8w?LPCunUot4
zaBWC~()ho!(e`=iU7rfsizx9qqpZTwteZSjhwtNju=5+mw0`<3T2UB7r3?QI`|K(a
zeMb|OGWc1ynpHEgT1Wl^kJVTUf4*o!zhY>w=^5$6X<1PtGIbDK`{-v9zdwDVK@@iZ
z`Su$+Byb$0J-3e(BJJ!?gI2fqsjtnJJNrofx#g$=byGrzbTP=Xo9CK*0a%WzpIKc{
z$Ql791jZF-rC;bQYuexQ^Taq4qvca$0#yuE8QmQa<e`I_bnG&;P1#22ex-Hs=Y&7t
zVk^D$xI_e1mSz||Xce&MRG+}fBfZ^NS|3u$NR*+0`M}GVZ=Sg0NLswAmO`Q0b}(^d
zFV;6USXAQJEBrL(1h!&}9cD~x$Z6G8INgwH!KxaO5t|gK0j%BjQ5-o=ujqpBiO2a!
zlaJF)1$!2>e#>gC3SxLYNAM>*kJsHddl+hI(pNbuMCEef^zsM&c7WpfD-(bNRO5=c
zc9W)Y7A|(fHELIfeoglaNJ+%d8Vhe4VlW2$Q(Ia{%yiY6l8G@r-(pP@u-jk=qmWWR
z1OA00kg>TE;qF`=zLgXHfzO7=RsM;$jnd-LwJcCWNdH{&T@xY{(oL%2Rv{)lD9C<w
zB_?LqtbeQ8;M0}21N-Y^&qNEtga;AV^Q}VIP0KX_xt}paLCr^Y31hOMGGg*Y`6?95
z-{*o1TD(^G-&n96$vvJ1`L~EvXvD~L^XKurR7-(+m$ijW5?U&*zJ`}6-8T!~a`%;=
zzLa8N>&nH&r&&j_G9_nlrXULlr8hT5z1;1I1&iIBibR@D`Mqg-oD_I0ZM$dm?i(T)
zSH?w5L;k0=jbU(ZrzbyM-t}j7(f0$64#bPVQYNe8p9~mE0Qi-06f;@;^p3vMuQYTF
z*fEx_o|O8N4d1%KYqL)wzv@4Z_P_|0%)v}%opzG@DSbzb-*NF1F{w5?>Ul4e74C+(
zc(q=CJ$4@Rt~=jA!Jn}Gn>kL%xfbC!AUQ=YWD3%p<{abP%dk}sFCtX1UY!#8=vuZ8
zR#J{VNn=mPvhtb`9!!;?VGo3UjuASYz2B3n9^Z{!b*An>=C!41Y22F?_x0P;wzbk~
zYuaz8yK;0ed((C{wH63S{M)akX{UpB3{WM%CFI9R{bxea^N9<d+87!j7U}<9(bg8Q
zRCfz~A7)VC3rR>+{xvZck%XxW_&x?w;ki9uwuexaFt!Q>(gMd@1U#x%=uf{p-k=KC
z`TAO7R5ddcNnT&-lJeIi=tp3Wr{DGt2-i_njFrau2{SYnbl*&ye35GU?R|Yn@-R$P
zK~QSMelU9wL<yMrMwajWodnV)gAKhX=hGion<1%2VP?LTD9KJpcu`oN2@daf=QX#>
zbwI(ld*r!bj8g0E$KTBIM5_79lwx6e3`b7Z31eO>JXGf9ZMp{^d>|-rj{~PI!G1Su
z^}J3`W*N)vV~_J82(_^7j@zIh79y2taa=Wt_hGT^=o3LP{{6Ql+R9|ulAjC3f=bYU
z*DW#t(Z4PhhsQF4S6)l71&K$~F-<)^Ud<T4clfJXY%<7v*<+NukX)ibXVQ9YQi~(&
z4?vW<>PTEcr0SG3*ACrJK4Pma&YOgvUOnzA{D!B6`%yWn%8-iFgvLdN*z&T`CtAZk
zwaWD5q}&I&H~u-rtVCD#b_)}1VNaD2(-+~_;uewd_%t^`q4DzP<*leY=;et%z3{Q#
z7&YdPFtw~PNVqZp_$@!q|D8W|N)saAj`!#ZZB4=I0I9<Sw0WtOaHYzz>V}2$#3IQ`
zDlT#{-Y;@pqwJFz1khm@YHe@MkK*M_Gpm=6IjHhqT;-=MIvm`75{C`7UD5x}T1Yy*
zxc?h2RPWmmzI5{tpe5~{13{lLm*f$uI%PzFK25T0POOV=VtGbQ=vl<`A5amKi6hKM
zzq(O4?B5sdMcbACjLeXW)%P~Q)S>14TsH_sD=X`Du1iWJ)gl@6+Vd)wppj$;-Fj>5
zHEc^}$4vst+51hmT4*eBdMV?sQ4NmxO^2~bagu?bvLI_{@7n-(jNuE9+NEjp40ruX
zN(O-$o=j?$w_KtKf*NRtZ@g}Pnbt?`)r!@Jd>+tvU*&^QQ>y~h0+p>qe$a{%lCMZm
zi?0R9ns*}>^m<B=LCtRqDlbZL-VB|(ys3$HHLLpTMJ6@g>FZH5!IoL{wuV&pAx<BL
zyrRk_lRY7u-SnyO*wo6U^_vk<)&x_duPzOf*eTNqqJ!Uw(U_FCvKB4z$Fe2?zq21;
zgk*!L1?x-7W80cqc<yP=!R1p2XC$d_lo>)qA}pm-?eIA>s2qKWlskK(<SQX^S8c4*
z1&_@dmSu(Gv#m{wrFwrvpS~^4>zC>A&nTlgc%x))r;v+bIIX;K8#=@|QNmv$#>;s4
zLbpcm^j(e;o97#Y52Mq)29hCvbQN)9Ogok$Ox`bUJB%&DRgtV4c@w2&B-!4`u#dj6
zKj?J=mZX2p)f?;drggG7kG4o;PW3r!iAiugngZ_qH%abKcRn7gxm&CCA#z|it9~Sg
z0fFQ}c`18-euz=j+GSN#SJ#%$%1A~iNuD7=z&Z+N;|d!w{g()K;%LIaY#D1EoX~lQ
z-B@f`MTOo<3)`Qb*nKYIx-~eCuz)V}2wQ)Fg>Mu6f@{0CH{-oa*}S!LO{=kMM<uRd
zvEM4z`LV5Cie7B0gu1Fwnu<b?ZSx%o)R8)#h^h^5z+bIc+g<p+A^O#c$=LDB2(^zb
zF1_9ff2#9BEUA;n7gTCz2y<u>>+MrGSo!m&V&S*%k=^xRc4Vs?H&EGBzjMj|(HYtG
zmpiJ-A!$rU-|#4UkiEdms6)oz$<OV}^RFfm!e2|a;_rJ7_t5HjSY9SQ7~WX_{;-=^
zEBVBYfwUjK{*%huo|>DKvBR|Pel5O_2}kK(iX02t^zfE5DnuDOe@ST&OER-mHmyGz
z-xQ4w8@@MZxJksuSyLV>Ba_mM;+%q>^8klVad9(DwlOvJOL&!2!7MO+D??FJxw=k8
z9Eq<UP;f(2hY;|U!y9J(=v|16_v%TPJH-Pawa~~2Ki^mR$c_HgNFg!6Nn_@lk#^!@
z<9*xCEI`6Lx7WtUn~IjkLswal>YQ7!Vw*Yh^R)X)`&k+@O|F(h*wgPhA%6VmM~I?I
zBwKJc-KIeUgOT3ssF;RUzSx((b^h+G!oVZz1T<F9CtjJ5Q+3;xnJ2ixW#ZBrr`z#9
zQOw*y0-HS(2KKLQ+qOc4ZsSdE`HoBG&h~%qT`hPz1h_exp4@vwsv1d1=EdgQ&6C>t
zm#ot=SP-J4&1&tss&R&*rM`tymmsKny)LTJ)H>a0f$x3Nj-Q{luxs;IP>P?{Yzhij
z!b6w%IM}f+_=+~Y@0$;FBfE~dZpB=`JHFT?TqJOJaa0kZ-NV9GhplvK!58~5pjWRp
zo#n|Pcab1qqh-*BPb*Qrhq`E?H{MJXqdU5YXLSYTZ1{u-6g~cDn6E>_>Ya{Ksf%+R
z8>AO6TEu_Wv*BrXQCd8h;S=dtxFy78P|Qu6AVXZOC}U5mKB)4lU&hG^d_+v~*;c=1
z2)VIz)TDZ+bkGKoth+RAQY(9cZnL8)Ufa$&oh^<?eQ>sc$GXg9F2y;6?Wxu0fuzpi
zkYuf(nYE(Ch?0V}Y+mp!Mp1@YK@I)Tp)(sIHoU_Xs4K;aK&d)|5!A2u=P#57(qX)y
z=ERzB7>qCh-3j|xw18>Y&i1Yc6iTLF{VJDhDHyAZL9%ftIZ+gLSmgatkU8<ZWN9qN
z46KZ{?^=6Spz%a%Ra_GpZ26Jk<`dKBkM|{+nLi-!Y`?Z?Jhhxyx|vyy;fzSqC63HE
z5!e@UdKD~s)YqoXXUu;9=fi+X$@Ks|Ws4*Ha<h(g8P)9X_a>KKe;ZfK*C(%eT|;Ib
z(<ePPmus&Ir^fE3oc|8zD$I{MjM`djoMPzGxC*igdpvQSye%TQ7I7-nA$?lTb-Gop
z@`U#*h8J$o^v!=cn?b+5cewKL^9_dHrzLcLJq2CM&Mdt|<pXMXZcb=Fa!9)FqOxVS
z^UAhC`R_vb-r1GxOqqdbof;cPTWjm9Tz@_Fr?Pgd!=24oGq&`;!>t1-Cc)wdo&AI*
zKT9)2J_MbcG3$8rsr2O|gf!cjwKXNX#Eb_sHruVw`S*7_4W{Uar3w1RzfdvL{dO6T
zqKfqqeT!O>nJeYMTqSReny=%_)D2Gu-vuf)pK)IjrBT((^`OTc8`{Y(xVC-GRSw$t
zK=d7_1H6zgJ{;RJHfY%Geyu$cB2kyBG5j3fx|UP2BoNJyiQ`dS<+^&O%lLUZy5>as
zl469NmpxlVSAnx{F~SsnCb-}Y<+a#)b~VASi-g>h_wfj#_YFPUNX=N+6X-;^;F%AD
zF?bRml7JG5*LpWn+}si8$dEu~Yyr|FO74-05J%Az2SPL4(X_*jxQyliCEvfVL~lF1
zzMPIa*?KGOCoesQe>;hD{$p51?^elf?ci!{LfWr6Uybi(z(Ut0U|VT^9OM+t+ERcr
zVRQR8B%})i(IzU|uDQ4_W8Hy#`n%-PQL*A$5GL!fi(u~4s9uOv%-*(2$Cwb1Z0Mmv
z+fQM{(G2pI*U#{~m%{(##C_y-daS9v>|xR<Vz!z*Y&6nPEs!7{<=&Y@qJ7~!rbC~G
z$lv*f&jhB2zf(fi@c(#v%cv^5@B15&M!K5=NT+nyArvW5;LzPE-H05zOOS4m?(RlX
zx+SC!A>Gf#{r&x)F?_`<&mPy_YwbBdYi?L07=`bT3O;@Z<=Q&%I??inVzAGEC#jH#
z`2B>#82gW#P6>DXM|ky-c}zeDV#95hB9{+w6+cl(CX^yEdke}(4$RLHq673TQ*K;z
zb|NV2_v^EZ>6a0D?9+e0PX6Ent5WV<E2d^6ZuS?Sf!^OoWvjcSl6rxVs!NN+4NRPg
z^kKcHVzFVfYQP>cdp#JBGx^nFP+aXjB|^kZher^y+bfx+5cV4Gej*U&1Z@MVrQdI4
zMwPawZBAefKJTi{$Vy<v+WWo-l*njrrOct+gZqc>Dgm*IWruUWH2(>AL_%W>{?Qr6
zW@m*d80!SLGp$xABzboD&M;9*ihey+TeJ}?L?r7XN><G7^qD_3$&GzWRspwiRj_Ya
zAjZ7He<k7+TKS2ZJvdPY@C_Bgy!NNaD(2D%K@AK+Gkxf?b+Mu2y3$0rZwO2|UN7Bc
zee6nNy}#)jT$5@QJJcN~#uHjL=U}n9jL6j{Kw|)NUPDE%*ldLn5LD=2>4a`TZYqRx
zp_ZIJ5uI*z(KHPk(GbdrDL?tIC&QzvSC77zdKN}xv5aq>vcTn3%eN+Sjekyn#u{RW
zh~6l#(<H{BV&USYb4wc`e0=Fi8}ZYQI_7R5{o{$ipK%#IsUUFyZdsx$-6hUXmj#H!
zOz)qKj<@i$cP7&4CLCHW1amvx@2Qi0oMdl8?PQHlg=|abd@j+@B;CuuDtlke=;K|<
zzh(~jj|`BaSFI3}R-i14RSkbpB~+OLwM{v6Mf=?SuMeAiZnIrHIW@sK-$gKn-(13P
z?eom*D|_K8QRFn1tA-k}A?QfIu3pv#Mhsn!=I{G5SRDh-`iwnLLJxh=_7R<qA_i08
z?$Z%#FcZVsrE}%06e!?~ZCMw-9~J>Ole)-)ukOJj9t7^+A}9e-;!<w%M;-HrPZ9Fp
zwnnLZ&dFJ=p?m`4z_WI?oIv00;LX2#Io3Ru2;v#dsIL)pfGIrmM1C;D!{YfD0@0W!
z7`SgWR=&^GuCM<dD~c68u;9yk-*V9V4fpD*8OxjKf0j_Fv4SIT{rVhkiR&DwG9=wI
zu_K)amoDKS6ytlOcXUMYeQtu7VVm9dKxHOPo~7c1Sbkd~r)W3Hjrg*bpMagg#tt)C
zyObWPV3^+TJfQ{czV0j9r$K%9<yc0<;EUZWiyfaYV9Mn4g5qZrUMGsiZw)ax(h8Rp
zgEmdvZ2=v1>9;DV=6Hn2M0`Z6yQRFoyhk|#WR}jeqPS28KigTtR$sGyu@y_LE79LX
zpUIqUc2f%B<^?8{*T6#35u!$N8MtJ93Hk-mhaA;BR=rktR2=2lpxU>9(vsotM6M>f
z9I~TWDc&a{U;&Y!`TX*A2bIzE#Qq6l<Ftkb5di^GL(;T>(o0}#cX@i`?5=p28j<qE
z_>aLMT$bSKUzEewneQC*wHAd-j$mRTmHAXy{Ro(~^afY-tJ!=lDixksVzn5Dz4mvw
ztD=UF_xih13d_^;7PJjqvJ9@_?6x9ah%u0Kds^V?{i=0J&O-wD55&G-h?qND+oKp5
z789=;LXa#O>WKzxG~fQ9(_B4)slZwS<xIv+Myt!5xUcFF@sV)5MtSLzvwMC_FXB=k
z`F<o{JDa}G#(AgDJCmNsZ2TSC{X}Uz;eJq+ajj#r)4__)K4g3v<9AK;)NQdYL-5z%
z100~awlKJUbHCo@<PXiI=fr&&c!7ezUl^AG<H!O^t9@GH37`>3=x@IRM;x|ASqaUs
zb@}^bLP9R)S!>88JkvXVdb5N_f><h*iyEtDrX-EY@4##WQ>m@>v?elYB9r8zT}Fe1
zl?)Cj_pO|Q(z1O6J;hZMy~byyDYhE-E1?Qj-+_yhi-$uPs*MQg<u*@tT`03Fn$nS)
zN+L&X7<=?4e{c=-SGh?YLjEj33w`l2=5=(ggXVdR(H&#_N)2aglm588s9*l5gMxj!
z-CSB&1!v!x!Am>rHgz)5K$A-o6$+{u8j3PBvb#<)JAuK>sdLjqj#e6a_6=0q;(o^_
zLuFNFH^Y_8pHKN%9Y{fpIRc@l5>Nl;PybfJHc&dQg*lGPjJP7Xq7l<p8Ibcx3?2@s
z{I+UOHpd^IAOhFb(EmFnb`pL99}sJu*7$$iSa^0aa)EKabqE69;Mpg5qx?k$Sz_8B
zg0v#J9~#XNqJ}l(U5t*He@M!>6SU^S=Y7C;70d;w3zk}|aGV~&^~<=~jMY2AAlfK6
zV^l~@M~MFtU-e&fs)JlDTio9jtPKHX65C8ES#0Y1bYV@!j?cpuZcIumq;?y|wIP?t
zySl*fp#aWxG->)4#~XFua(sjR4k#8__xiYBgPJEg>fJHcpSI=smeDGjzz%6zv=NJl
z_-4zl7M)3Q;99g&Hs36{`+xG{iX*x4^?5TDj7kPfN5wSwY4%=8hF8=4H@PQcUyXn8
z*9cx9<NBRvwZ*L8`8yc3FN6JYK;ejK<m{1y+<97TaDb_f3Svc74|!2`Rl#I&|4CV!
z(DNWOBL@eJTH$-74p}hkXm$0_k^ji3P;isVirLkdXd|%_twfH#?=nl*7y6gDSw36Y
zzxx+kC~zPnSl$~FWlqjh5+@~NsyoiVfm9QxtUtn;2Xzibiq-02qb`vbRvOUzDP$_y
z)gJ@VfbYw8q}ZrxYBUk?Q%>|+n5SP>t4)m^VZ2)3|CCB@YJpI#YyJeVEgUD}GPK7i
zRNTcA#+cE;By-$xRK4Pbd;(lM4(JHaOL0P3DgM!Fm~*ZgTlGb0b$O6c+q4pyA%wSN
zg9{QAMuOqE{eh3YxUxh5g7lw-#PlL@>s$N8^9sHkEXK4Cwj8gv)bLL_+^xpj<5$Ky
zpdSPp>p=Wf_7eJ2(A{_K+nsHWgSQw%JG9rP@N4SHbEQ{LDOq{sC3M+XE+~?B9aziB
zue!!%sMa19!`LYp(Le1Z#)X}Ncxgwx4yK6=2#zpnS82QaX1Z6;7zT8A=zz^ENq@VG
zj&*eMIAUk>{5=d)dNUlc=dxMgc*~&UIh>(JVTV_;B9zv(V;5Y0TG-{7$Fm*g*1p_N
zM!dIM4D2E24>VV0kHXHjPQRoR7`aON8=S<?{WTM%fy2`j>jondph<ATO3dj^A!@7_
zw}isZXpj##i@NA{-}oq~Ty~cjUrMA7#&|7T&|MID$I5RA`6$JZvY18OBIDbtkx!Q;
z_2GAfRQ_6fWt1C}_vzGlB7f8yN+cN#Y;p0XDkSd1blQETY{{PqE>LM}^}W3aBDdS&
zNcz}czIZK?;~zNE<5Xs&-EFv32%Gr0cYVkkM`_oyZQg!KKF4VWT_>IAW*37p^5Bgt
zkqAe_Mpj(Ng0q>}+YmZ&<p$zWf9L7YY#(X^vbY8EDe0Jj4MozA01f8cR#Q{8eF3Sd
zS+vwxWCDQL|Em@*_INd;Gh1sVufjqsRuQE`We^j$&)-By$@E+DDt}R#B(5*7>0u(g
zLyp<&*`iPx@y(53+r3QRm+mv*Out@c<Wifvfp)tzEn^&i?MDvg$=2V+;9YJujtH1z
z^u7LTRoM$~i2epoK9pp6<Vv8DP>&ZctmoSqvRfWzA0L<jI0`oh+bZW+4-{>cjuwou
zJ5?LJ?hA*cIk9IiwTvGm93J4GX74MN?NXhMw$c@@maM*~xWZs&fnh7KOiwrK-{fcI
z9`+P}!93$)%IpYfv`%gwK7n{AC*f}iWJ`l$7yriw;=Fvl#t5R--sY$;tuRG89UJDO
z6#2LA2O}GpteHdVHoMmyBJz_0v0SRhNMuWeN0+`T|I)rU0w)-Z0oO4(;mVFE67gq1
zaBd2Ddg_l(I+mS?FXpwY*1aGwA1q<pmiE3cW+F8qk?}+}ptm@xb&LHqRK*ledI++C
z-v?iDLzCirCh~k(C02d1X0VG(q+ubV^5HN{8>FF^a{adlwpoqj9le{X;=R-UWJ$B5
zH4smYIs5%>pTGoGNE+4~(-sN<MOZjL^i(f;>2Fdg8OUjY7TOg05gX^<0;rU(&hW)w
zk4<OH8Zrju0%3|sk#daJS4$cHj|F%fuAoV&sQPJY<)ocFg9G;-K6c-@V&C{WNs7R<
zCa>Ys4+>4vUq$<wwD>#&Q-!|<<I64?%-(tXn9XvG9q@w*vir!2yuN%t++x`GfKKFP
zT&hZe3+Kc9q7Xk&#y@50QRnIrgEBaWbG?_;)l^5?c6u<xj-1BzOCgbr<8)?OtS~{i
z;NM-qc6R&m%2oh*mNx@9(msTq`ER<6>mR!I@Jbduxm0FzpN<`~$r9n~Ry(D3@k+4B
zGLQ|e+J{*j6+1R`$r_^L9&sb+N&%87yzw@;PN5%@%1LSO!q%~p+hARKIm@sxq}p#b
zQ8MRejD1m9>33m|yF1}yagsletzs0{d*5h+{wsB|dti{MCj^v(WGpVEGPKz}@i&*Q
zx+lt=V=JSPGfS|{h1Odk@pbM|fvloS+!JB%Z3d+SGAI}>H~y`n3pb(bO%O@y5RFaL
zkBV?}o9>ZfHNwI)Ve$mw<mWL3#FinrR64OHUl^N~al~ZAM%W}BVAd_UWiIrzz3(Lf
zo>O4vW+DGN>XcWwRY*PfU^<9!6xF&Xpxv}^kTX1^7KHPWyk%OG7=q|7sAx{7VyYHW
zJmr_s0J?!|Lih&xSa?fomr9$O4jb^;MdL?DBs`6rx>$IECHOmai>)$p6w|S1E+YGr
z#Z`IGdT5yl;A6HZ*@^#q;D3t9^1*%HDXPq#{TOQ8t*P%FWbmM4Fi71|quIOrBeoy9
zPV)aV1Ec5#ST9Hp5e|AbQFvY+)|&4w9$fZpG&f0|<L<c7N@wRcCgD}-{EoS#a1LAU
z?oV(V_<E*ll%sFdc<yA3ZM0Q>zp{+>VKx4y$G^&GlgAK{vQ$$*^4X9hTSX%?iLpnX
zDZYpRR?V$<oHJF4q7L|(fF1Xy0X2l#ajKsvA%dn9A05}y_p+hT1IY47^$WIJjD6CF
z-|J^zp|UqBnjO^GvfZ($MkQl;sFwvS->(v%LyuRmmEwkSsqU%1eq}I6wILpgvW}aZ
z34*gSMT=4B!5Q8Lmk%x5qw<!)KGGE9=&}7Fmw^iIf?7q51|If#lmVYVR{Qr~$-~kV
zGv`I(7A4orj*jT(%Ss;vYA-KV!Yu)E^sI*=&xfezyRDmMgNON>Ud^lVhPa?~(Es(G
z=>INorHRrB!!1ECwIw3h7#soJyn>wz-u**)rJd4Z!UqrD$#u>9L=t`NLLIXwtq9t5
zCiedIMLqOG17Q&kn$zmRu*#^@$GIy*)Za`r#~w%mV)drs>^07~Yi`vGwE4cZ^TCr+
zJ>j~)p-+A1xuecp5ktL+vTtIFlI0si;f|u`ryLp_s~6?-cJ_z{)gsG@WSsD&sj%Oo
zv;(H-MAy&8P7hiP%PrgvOpQ+%XEE<+YbN_i<jDI)iRw(2OspN;?@OaX;)46gIENPp
z@vv_`hHPU99JCx8)>X4nzOQfE#G{K+n5!ejl5J#$<4x>o6zz=aeAqSU3&~piH|Ke<
zB<#0QBoX+$f8s+4qz6+O2RG2ffTC*c;edO>0j_xY`=Q?-=XuKNUw~eWknQb%Z%V_O
zEsw-!QEWCAA%;ZWQoo7+EqT2k)7Ir%+Jfj_&hbPu?g?~iElecjarQ9o^n_fF8)RRH
zgkl*<2-v!LDFyW&KD^V{Q7+-Sg4wK%)l&U<_gpiPB7`OT;hHBpLFl4S_<P6opc;9j
zT-shg>_9|A(xEQ|9zacSOTMjz%LN?y;r}zY@w@J2<wXrsG2L)(3#oO8u4N9IT%zf?
z4e-z09R2pjp|!JfUkFzZN0kkHdTml87W~{{jlnW{>m#Q23oy~-uTd>T$e&l%#cP3|
zmWa@Ct^WPA)E_2t>bve)P<1@mX@=5yH{bEf|L(pbZ_)7L?Y|qT|6Si$c4&zJ@NML_
zx-Ah*;EP-1$W<`$8+2yX&kb2HS(kRY+6G>N7qa`N5~_B3k>votNNm0MI_n7iHDXuQ
zE&4!I<L;5O&^T?KMUE)%&UE|+5>YU02HrI0TZbg&<kM@QFb}YYgx?F7d3ILO;Yt&n
z910)0NFmYRKHT<`4Bsof_{d$4mam-la2V91a|wTJ0VVA9!us^&Itno#LP_=nT@9*t
z=@>x!eD#ePOFIeEG|i!uU*YD7Nux_S9k*hal0A0o+|wv~3;#tuq-#HB@mhGNsZgvo
z%ZMAwH=Z(n(~Qr6(B;(_*7<Lmy1U@qhG*8Hk?iI+%L`3K&j5SntuzrfP_99yNE_3@
zRfPMc@kT@6MOBnv5t%&>-dZ3p?~Xb!6rEy(kY;ltT8I#Y@ua_<TGzq&Wt`mqGe+$^
z#^U4%?et3I2HoY!xK)V32)1mDQH%MN+3{}XEYWV$<4Zr$C78E*P|P_<sUhhkD>7jn
zjaS7bA}!C3VxX2iH!FB+>R{9f4V3>n>y-qdE+P?xrrHJ#1OD8PJYF<TR_vUjYu^9y
zDU-T{)`0hjY96MdpZHd1#R!AN^lm_cQGGvMmNUZnw;Z`IVdF{8S%!(u5&j(iA4R(O
zzXNGTnZuz(H*?roy%-aB)6ng+nR-{ByJZeUYg|wS#((Yh7X>60aXjhq=vhb*(Mxse
z$pQFB;my69nZZ+u*}uUO9LkvSbbUjtin1iP5#{#eW3p2UtJsI94MDU6H;8^C>yS|5
z*5{3^o9TWc{Ir(U$r2G&rUuloeT8@Wt$_)#SH97t%bp3XolINIE4orp`uXa?=qvHy
zo?{P6U_3Sy;p)+26kx?-2QeHF=}PwXw+KmR=&W@=#X-4I8g>FE4|hh5?BHue+%GZ0
zr?2ILUfZ;CGyan&t-Z(HMcu14*^%YI2=P5?0S2xy9d}*sv_>as(AgayzckK0qC(97
z$3PmkPxoE^($igl^wPs5GitS@73#~PClOrs@M=6z)$iEI--_#jBO)I}$JS<Oyizq|
zx!76XgN!-FCq5RkM}~AT-Vu+ko}n!Vx5-|ex{cZ74p<UR-gzP$WAyG92$>uakmuO8
zsu1bW#>6A%yOzi9c<xKD>=F4n4LFI0**oF5{@gF?pYnk2Gyw%S&{Ku`gwHj9a`FU2
zzgrelV3{^fRzb=pbBMOppF!yYoQu<50VJb}Q8x_E;F9znRnisXEGP4;)DEbf$m_<s
z@pGCPei@A&72d@*Tp%sAswT{FNak0yJX?dUt*qnIc6q!1yo0?T`q$;~8qffZ=aw*i
zCKx$42K`P+b=w!Z4N11HpH9Ud1pFQ6*y)1OQ$D|^{14cpA<$+cKVw!8p{GAIwZ7A&
z5c-M$rg;z2$xUxd-sdm4*xJARGJ-gFR_C>JR?~0(_5E^OJsaZArt@!v^3JcCISEk1
zRbd*{Y3@=P+kg^1q*S*2pZQ|0VPd1=_mw|!=pTO_m5^052bq=?ofNWvbk_CM)=NFk
zsj<5%61x<YREiK?PS^_X(VywBu5+sPjBNO6ufJpgbOu8v!5MfxyEoY1$P1Y3b<|nV
zvW93^i3F_|5Icux-%)Q6dWN@Wy}_yO%L%5*1EdN%{;&S&K0PG0el=p8x&5ZC{#jL{
zc>Nq~nSK!ves!BqBH*p$@cA|2E^-IzO(^zwrua6{xIIjjV!sTy^}leK0PSxD92q4N
z_Y_Z829E?!u#=YX?*=Q~MV&B&rvz%RgR(R^R3SpvI@B@7T{Ix{t65k0rvhcXQ81W)
zB$iFiYb4UE1Ls#J<8`F0jk^=+DQ5?={}OwD<KFR=0KKQmJ(T~5qbo~|7bC^DLf}Wp
z4xH2uJ(>ivwtvRNlI`RCVPU0Wp3a`zd7c6N35pX&qx`Z5NjY7`-uXg=hWv*Qs1VHP
z&8qQFBA*rXupHK}@3+Nw3*%AegVQ~OXS^#LcfGHC#U*|w6MmI?aIF>kFrKb#6XQSr
zolZ`QU**)E_^ZPBQe2Y$=w6K5XzYTT`cCR@`gn!6@1dFXTt%sQJ*JLy^!<Nwg}}V{
z^8?29=`oDOzZI{Bf-4tL;n+Z{%J>p@MOgy|56%;Li@X+Ly`U@_M$_gJlf@i{7ZR~w
z=0Qa~u3vTlWtI{{dj?r8pyoU6*bTZe<c=hzD3dAlJzHqKgGRDgt-(i)U(#(vi!$*v
zugvRWR2M+`u+E&Us}IEK^*kkYp$s`^myj4++&TDyERzWm#JY?H6@4WRZ*R8n3EzL*
z1X|o$@iua1zC05JSNgSScHh(tva6`eHw3LWj9Wu0gjXN)24{ed0Lh33=;`c?IfY-F
z_cH#RT%UKU<VGY;CdtMMX`IHY9?Yd$t{Cbe#9j`ReWYkE5vvpW$z-AXICzQ5@Y{KF
zv0}9%1C~pJ=V_rB->4$YbqTJYG`I)T8%<63rAXrsmA%DpQG(B&N;$a>{Wy{W!T;Cv
zzis%oK|tqb;(3esbW7sm_1u!ZA??d`@r%YA*U&y3VHe>02?A6eIx3i^m*{l)LE*^I
zNB2Fm;f@45RSjUQQNK`V^73!XCIKyK3tk#q*WGXEOtoYR#}kX@msne%6<x^XKnZ;m
zz=sQ}WuHEr`aqV@j+NS|@4k}1Fa3LBFkddta~cvyS3C*+bWB*$u0kO{BA$Hf7sPNJ
z&0oDnvLRg?Glw=Ec9BaMz9a_>`xvWv;Mf^*YFEl0#eQd@cX|lv!@*Rz5?&;F3rvv@
z<?av=>Bm7e1RCwES!xs-Aigzs8>r}PMq!{KoO`Xpp`N<G=qR}>3dI_T5&0huNUsrF
z{UvV>Icnn^!$a*pPy(}zqGWX8eV#+pA*faUg1JM1qR9Zbf(vE(A(jyOQBu@Pm1Q;*
z`8tQphSA>e*h${Iz?J?$W?)ctO!@DX8S*{JiF7_84OxODfSkk|C7n_IfZ5LufYdxQ
z-;h$%+F#(JXyt_Fw*T&6J<3}=&=9|(MF{&vEc|9khQM_5w5m=;$u+Vt{A+y_z7Eg`
z$6BkR|8KKD#Q1PEj$4Wj+{w8;$p&mN1*e~$GpSMIP2gN9QsuaYA9BRV={^xy@cIN;
zVurHnx2mIuB4fXoaDTgm>0B8W&7~fCeZw`nu%%{2Nh&VM7BxbQmiRF=<T__A;;_FL
zB^It_%A+kyIQ}0FsZ6d+Xb>v1pwlB8-&^6S<~X%m*N|fDuxNyg`+uIwylvP8OGzSu
zV8k=W#yWk`6<LZugQY!Gs$YZ@eGvP4Y0kaD0G&d1l#9FjY;MI1SFl4)4v!=Ms;@W1
zvM!UkY+3c*67i-3`g1N$-|~H!^Ap(t6Ju{>19joLJE6ffW@PpxYkAS8yk*_bth}Ed
z!R!2aVv>B>WV3#|OmV{w2Y8zs8Si1r<tjwog^lFuE^&3(`}ik?s9l<cLYRp#<ndfW
zQ|vv+y|SGdE=S?tC@O*<1G%<uG_z3=eS4FCG#LD5qDJpM18J8pcAV^3&C?vvWd?g+
zg|RbW+y}1hk-)C@cTzgsD6wK_a<davEV+cPz1w|h@L&Sq&)1aD)m~qP>mPH{ie5Bb
zPfalz0aau2Q()Ud1Lr$FG&mEc3)4vZ;f1ViZBa=?9_x_{b-t+loWvejo(ymQ^Qe`g
z>5`jLF}$MW*J0O!fD5lHG^XDwTQj8by4Y)5QX7K$G7|PCt=wJBb8t~Ym0{kGUvk#F
z1qZsBq#Gf=g<IaeU*J#2wm?hj@LEX<h%5Us0hgOL2akE6CHMz?ftX+Y+^yfZk=266
z(^V?Rdos49tTKQ<@Xu)%-w8}IMLYQ?JFiolw10kdA0LytJ-HQW2N{R4QhOH=*i$CQ
zJnFM80FL~pBgM$a;)lQvUr`pF9Wh*in6Z=e$EI)IdF+vVyNBPpQDJiUKaW@~#wQ9S
zt3=3lLfPJK^!9Gxl*ijV(Ho#WdIaV470^Zi)Q*PL?(QxZSz<UF*1)Se9rj}U#R+Pj
zuYa`eqU|(IHwrtQ!34%97P8hj&JrTB=;>QOXd_l&(d>fDCg4!9tje_;+<d!m%sxTn
zNosMhdi}2c0BbvuEEmO*P@}5)1%f2j<nicj+LBP=!~<w_h<c|<iT|~Q?%>w>KHO=4
z<?+Va8r(eR_h&3>d2aD*6!&lF$!L&Iza1h&+>ecYJWMJw=Chs>EWZm%{>b<h8vHjx
z{`~izE^Fnq_TWJCuTc5F5f<mam%MW8#+lZnT|~dt8rl;q=`1s)1?&1=<#kzhh`z6-
z8DlLFnA>QA&Kr1QszHtH@#n_<(TVk0Dr%kodKQ<rCM^eB%kYof`(JBdlXMugKh`r=
zU75a18vEsOHocAo{YS0t8M)0o)3~Ctv++uE{;a6u+RG?o%F<F$DiJ|ABY~5ocn*uK
zy!^Kpr{95hwkb01QabqHm4{Xhhl|T(7ZAZ$^<^1uviXizSTo|#r7^QhD@jCtSGJxL
zF6tjr46($co@Msk$+Ci&y6{!rnXs3;j9@^(<zZR@2FI2Me(!&%%#kjKJHvZ?lvWw=
z*1^Q%_-C{`UJJ^;DY(bH+g+*J(KE0s7fCUVb6fqDGr;26d<Wuo#&>yTOBl#(h!qdp
zZ!bkis5?HFJHbUA<2U^~ix)1pb7^o7*emwBPkUp~0Eb1@zqjgN`(^p(Vt;>3+4u2E
zAPCkyZ?;Xd`O(P*$$g|AIjO2+R?^*OnTh<5FqUG+36hTLf%#up*k@weHxexHz?#!Z
z>OL;yUDA(i=a(Owl~q>Ce958^5y}|*x1O{*_U|n9dl(O27)>^>g)Ku14nbl;BeMXX
z0wFW_cSHYSY@yI`lFuazoRhotyU31`l2a)--L^Y|tC&&)c3lUD+$mcNWxFiNf~l@c
z#>|1Ksym@Ie4Y6?R1@9me$%78kXLR04!*NAV#2N8RiA|Dj^KNJ(9g1Qt(K_p6Z`Aa
znvm(PV;k3I-T1>}KW{y-_vhyoIPtnUKHGh#PYhY|hQ5LWtq!ZF$LsBm@HczE@Zlrh
zU%jePkyCTQ@NTWIT$o}Xy+fCL4Sj5i$WtTVP4l(oH^+ghKnz%kG3^@37VHIp#~gh>
z)v?<ARZbY&qHB9pzU&0%7to0-2qJ{wfx9}D{&Klr^yTky<kON(p)07{E0T*dM`X30
zHr=LAe$?K_2S`4iy6wI0t+QSAV_#6FP=Kj!a+Jprm_(zV->ShrFSp<^O4!|(eXm>X
z@sO;x;N@NOXSRtEWtk1*MjtVm)z%1dlv$M^2`4M^uG+nK81C|Ed%yD8TV6dK+zD$R
zuKx6&gNLiIvlkh6*TTh`qx<ux_-^8%*__<YN>Dmr+tt{=c6K1|Y<NEAylLi`Ae;>j
z$|^$abekG4dyN0(w#Rj_!N4>QmOx$7lSPJ@S*_F<0nwD$EeJ#(UbaV<K>kLz;_;WS
z=wx@o7iYp(v8MAMRc);sm0G~%YdA}Hj+BPWC#8wObLxBE%_ab~3#2@vyDwAXnowc0
zqd3NVPn|37UZPfg<RIj^1(SJbpLn5rZ$hf;<0N7ZuxTH@t$Sh{JZWFrxCF7i(gtHZ
zzJvB#Sas};dnw4go{1b3J-1<zT({8hLJz#~okQXMETcq(s$#!?RH?W5cj+$&M<%D6
z7<S0)vt(wN6;(qm?aKAo=DHIBnX1K3BKECs^^FPVe%8+za+#zSA7b(_mE=srvxz$d
z9P3Q(b3XS03+6ue@v^~BsOP>qTd^!*6Q`LQMsq@?AElPs3Dnmhv=JF_(@ECit>VnR
zpF)h1K!9SzPKLbV>ua`jmR?M}MnJn!wK5f4O5L)?-FGr_;cv%Ae=BIpUP9MagFi<5
zSQ<E9c@Cw5uu8`YGQX}yddnU7<Es5D*Sb)E-|Avk;0GVIi@*8)=JDTa<r;?~G~(Li
zg{i#gY`Iamk{PHX1swAS1lJFY?1Eir+t0q_4`Mj2PB;&J){&?CB^7$o3W-@%-Iyb=
zk7{(pF_T8mS^&+sW--=qQ9K%bpbI9q>-J=~-f`V&erLNI$`;=d(lViZ9999;f;jvV
z<E4<58R8|~p8c#hHI6Z*@+nn_q;hFxFyjV)ikOG%2wRrYa!rU87~!qWNUUM!VLJB(
z&aU00YNRDRTs5j6jJo3+3U<g1#`A{rP1o$@J4EBSVRwN55$wC0sELk<^_!#C(9MDy
zS0#nNr{v#&aivfvg73=Oa&$ZTjHZhvoX+Ng;2S+~a>$$CX<1}Y9z4@{e7Z9@JW5Hv
z#$T)xV>9h6lVJR047VCQ`{dh$H!vhF6?9xWy`h=p3~74AmRcS6%OYR&hknBd_5(aJ
z`i4g}O559aTH*afd<%0>$=t$@IN?4j>pM^U-BCu`?>_M)Y(FG(xmuuC`h}05CmWW(
z<n1#W9x$ceNSq@Qql;PPNmv`za`!+rD!DQgIJL0=z08!4L;>S|ivCB~v7pMjO2%0Z
zxB3Tqx84L+!~o_1)Nj9Sw^2W^C`*(kpfTGPb*h-=z!K<cxPr)j3?a;29SK&1A`Eok
z-w(Ly&=`fXx#%SLPYFugskU?)aUMErJ#1}~H{$H=KJhvW@yWPs3__o1dMuvy?{CT{
zR{H?m3J31`8d=ca9y6mJ`51<UGZxDb9{bt6nL3FckWC^R*F*+%P6$H?DPHfd(3|eZ
z5o(1-|F@>Kkwc#(W<wAeH{zyXT!YYt8<viu&i5mI9Mj^8o5^ONNJ6(0zcr?F&e7lp
z+aI75Mz=$qNDg$q3|s854Mdz({e>c1rRDdBjbBE37aKFg3r*h8rzWsEyO@nrn#~ML
z1i!tD-H9W9)T)XupLd1r%n_eIY%fYg&I8OrRLB;`W;*wgI$$D|;BI*<iLR#=Z|F0+
znW713O9`$#(ORh+{t8onWCIhK^N1Rw$(tIDX*z?6QW};Sa~%ig2q6n`RFQ{WxS%Fn
zrX$!^4{B~lF$teseZZQAZ-;uXC-Hjv6aDF}OBxf=$|~ibwPQHiuC+Xn{raK0sTAse
z!cT$mvty9KbI1w79BIa9U{F-SZ04NJLJRzJ;_^MJkl1@Q%j(3}y{POAH$?jEC_%MM
z83c#MNaa9ej`#EF6S33t)rq!i%@(Qox7^peb!&5dXH+X4My(7e3Kg%iGm$(hzx8h2
zphD@Y0`>#YI2*V!lnSQ{78*#N(_kT2x7A3j<KAk?c6vvfPN?Ct_7mc9yr)dZn{$rj
zA=PQe@h=iXJsk@n_rdz(;(b@chSNY14AqwE>BO%xfCd$ywI*qaY2?||Xloq%agG=M
zuGaQ9XQ@P2QqS9^S%{m%PR7-Xu2&X1uS(Y&C*%}t8~f?luxy{}&J_x@yJ!oR=!4iq
zfhig3p?D|%$^}m$)0Y&FEW%JrT=^H#_a(LD3m!_iCHxIhAdGP@(V~0qb?*_Yv+S#c
z`9Tzc)A2)ply@C?7CFLtpDMPjTCMI2o@DnR#D~50-Ne6J>~mx~7HH|k<r83*Xx7vL
zq@)8;ENX53K>k3IxD>mx-h_9aeYGTAM9&75`pE<drYMQSpE*m6K_?=wwEup*u}|Y|
zC$^0x!WTLOAmC@J^YD-WqGkMb`;s(*t<8BhU%!Hc)}ga)hHB)fQOgyRTpVE4sOxsO
z7q6VAydwCszU*A&pinQ8&`$|p)SMcxg+-~msskfLAXD+1av)1UQ7%tSl$kPSPZDH$
z3;7DQlmjS4kQ&}>ZHFw&8>$sluLo1^k4n$s)#;)#sr1->W@f`?47qT8%;Z#^Ap!=E
zhoO1hE;?6T3#J=db&nT$L3CE-KlmAJ{KeEL8Imv5(xSnCs+O7?WTigcENE|PWpxlq
z&Ylt&ebHl}vo~noxH}0?BryF4=`ua~m13F5z&;VpyD#<eXEqJ3D$71~9c;gd%_fBA
zG2PsbXPt3SfkH5$cY6k&E0O3pN@tH3IQsW;Br3XFWl%w64KhA~J093K_1jAgx#*zn
z_5p&K+hzPUw+;Yn+|#=?MiYsWt0w7*B>Ia=U3SKY$l<1USWh|ji*xN1m4RL&7YQBl
zjn{Hd&LUA~6FvQBRL@U&dir5F(!79FgH!WS6f3TMt=%;e1^YZt<25s|Qoxdh5`9eJ
zNyPc0!PM{B^Op8o<JUdGD#CUA<hg{9ar`gus()v;OpnxEe_OL_yPY+V<`tefXu3Q?
zT8!NewhC^}rX1k^LX>^zBu;PVm|2F1BkJC=9n<KIiOel=Yw#tVygt-ccksiGRw~Fh
z)YSD-JW;;!RK8Twcp1$#i@KfGN(K@XA+^$zamIf&*ro8Jh(bgfaHTc(4CP3R8Gk}K
z->TktBFA#p6c?Rf(ANw_?HG+4ocH7S0rZ<sRLhdjV5&u^XPM7gu!sR36By}`-OXTn
zOR?SAcKt#8p}8{G|7C;hd;`4Nq2GA~rx%y54-44h-?ARhu(t-EMtJ~N_iiMd!(L)<
zYu@kB4qWZ;B~0<V`Q6Yz_3sgHD0%=*iH#n8tJWSt2p4w%<(ak^>HJ-Dx??ZgD9+%M
z>WJH7wmY#v$6W*oHZ|lbmgCNgxWvY>>7ID`Ff4xqyM)3Iw6sf6Y+$;Ht7Ta!vx!cw
z+btuwTnGs2d~i(d$FRwB{jX3vc|$agBR4IRO~C@6d-~lk{N4Rd^i4ub1CM9ONW?+0
z+KwHy;ODin-iD`D^rn(jge6W~{JCj=g0&N1w3rx@LTmJwx+qsjJ0}!r;9)Mz+GsWA
z(MtTnrjMW;PLhK7x$sxkR`47Dql<G&k7&>LpT50=Lj|38J75ASU(>cM52u~y@DCOe
zcOaiXOTs^tpiFpe{*58ekMrwY&zH?<p}BwEwGJW&0}bAkoNfI-7T|Ui)7Gxx)S}}A
zO}BN15B%n3W)GoE5{#knT&5$5dM2IIUxO!h$M!=fE6`dG%bYHiuk@l)&`g#YoJbFa
zK%W1&wq0L7V{UE8#I)1vA;p#t{}{%UHsa7{OeUnk6U~;H3l95i$xKy~JR2(vCP=KA
zPW~{EhlTPXzR=WIk5p5~qxze<nxaFVwa18Nol~Q_->BDGlyA{Ee!+!F^S(3#vsK?a
z#(1LwjCbOwBVy(n)cfMr2cM*s-^ck8$iPwb+X#lwS51*@`ZxzPgqt7mfPzN9?H6C6
zQ8JwL#_b*nG(u@rbh)flFr~4xRZZ0*raQr=@I`vE#;EtM9ijaMkgmN(KV6T8h@0rc
zXp2uYbzDf~x4xKiQq-~t47;TVT`!m{=={Z)GqqAfzsXe5?eV`==iK}URn}g!Wf48^
zL-u<r((lPYdG)aN{TRictinDzdhq7Z|C;;;w%!hn5%tF!V{lxFn6wu-9nf4CKit8U
zRt}@VIyOYdd>Iig1~LTd`eY(c9$A*={g5roka&4rB~<#cqf-!4*s@vX`PkH_Bx~05
zM4n$au0MQM*id&LuKwIYFV?wyYifFIJUv_qreUe8U5{Kd0vau^11?-0Q#(A^hag&!
z4uChfN>4M|o-XBd8Yn)c%My!YDdBpz{IR9->6Ys%qnN$S#B&Yf^|HQHFkKT4tk>gh
zcRyEjj{kQ6VHJ#iS=<euT9s}jP`>d6laybMjAQjTljZMtv;lf!YmiVjhTw2nqK&~0
zNmHYC{^cab;8QdUATg2Np>q?Ju4Bl$(4*JZhTwi)heBub#D>Y1JXq_Ehjoi}H0OU?
z`vt=o`dBk%w;9s${O-Zse?M=p?6#IhuX&++{k~sii}-1W^`+SYJ5*_72=uB&R<>QC
z8hFCuAWwgeN$W##K9aI#V?{uxTu~uFN{DH5*u8_H%k}rEmMh}yPXeJ);D2yK^w5AE
zM1hs+5_L`YDP`;E5NxNDfy%8vYrBeeN>>4(wPF=pOWE4frf8Ymm^6-tVpiW^%Bk*f
z3!F)QLpkZ;J|g8$P@1bGr=8l5)7<#u;)ThK%7h{<vZ=nUs|xE8S94VI6W)rB8x7-k
zF65VE!l{_$&>w${Nd`lW-ACd72-<H6+MDEY_h@0g_fkOx)o#hfJN9FB+rAo#*vys}
zN3~f0e%y29FSzV@XV;dAt{S*V+~gY~g0)Dp9l=J?4Ruu_%|&p!<~gu_bh8chZ##OT
zUp}YPzWE)S;#>Yo=Tq)?XuX#g5R!uPmh)kbCWwu4EVxJI;eKM%!tbHCnKmLQ_~VVk
z^QOF`Uu#t7W12&`E*UO$zshSo>16nB^n9$amx6KzAW|9uP1k&pYxmTXEf>@|)n|56
zwkh`0n=T-)MaxsT`^IN(s@12W(7eTu3T7DHsUCFBA|Z5;8IAYugpAb`1oTyVQ!WiD
z#u(FQl)pQOWa$ZYQg-<h?ew&`m}mN_HtsVQxhCMaC?m49Opd^fOjVr23#lfS@_7ni
ztOO=z&wVgnbqM{~@96Y;K5ko7jzmb&2gfOLd2O_^^K>+h<46JA`J`5Wzx)S8G}OLZ
zH^LxyvG6Z%V0V(rxLy*LB{C-m*mAl25QMn?d|1a238eE&KdGvm3%)vH&V<NAoJ7r*
zxmk7MW1)JoWG|6!P;Z0Dl@r<vHZ_#~!c;+oGatK<{T@)Vy1j~o)E@zQi2AYH;<Q<!
z33$v%{PjwUtYJN^JI+7BT+>@95uO?VLgwb+fNp+rlpv9w7`yB~OXfY&lP#}92kw5U
z!fdpc0$7GVhMI=(ZNc@aQRi)4b1(Q4wuczVIXr(J#ZP*t@-eQ(kIy^IM3A5)Pp0`_
zU{x|B(c6$_Qe4yIV&u<;p}N5RN!nNfVzrDt${QFgcI7(s!4@R~<Qd1-BD=v2HZw95
z9elf{QhBlhD{+;Kyx_ZYbI!WZh3CQG@KW2hYh`ajeXe5#na1r6vPTx&!2g_9WvVKE
zw-;+6(l#jtl%IX!1IH%fFt&r6iY$3kZqGc~`Tzsd4T%PML8DHhMthcA9D^W2y@!o;
zs@;67cgu_o>|&Sijw^}=()eXZ&lGk#BhZ1fOnL{pP8Jkfu%*841+U3DPRw#UT&m~u
zP>?YwZ3!y)X)ZmqS&JZzL7MK0j|w7+G_UsR%S#J&mw5GuNA>5cSx>T`u9%itA=dUX
ze4HOLM?SJkx(3K$yf0U}wudXHWV-49l_0AM?Ovm%C4<pMN7LlV^i6>_yD49L3*cf>
zrMF<ay?&K-&qtx&SjEubn2Q-CZCLQWTHPwhS(+YWwP8q>SR^Q>cq2iG9xJ43D~tW^
zum?eh0tej;RhYs`ejh(e-2(dIdiG;S$`pIuby#hGnld8So%kjA&6Y7bBan`Ot9y|r
zSj+2LmuehmYYSv<MZpP%i!4yOPkq;zWa96z#N*2RhfO`(Z5i_S0V|5qEQcdb#+urE
zo%pk<Q4!`Zd`Qz~>IVgyj>o#gv9JJcU)U0lERp?c%?zj|wukaWm{xJ`ad>T>r?wJN
z_B-?cHOdfSz$E51$1sn}&92gjH#aq7Qsu*!PX3mp@PF2DI$haY+E)tCm~alG4KgMu
zHY$&rlIPM--0-3;XYSloD<%0+JJpwrOCK7Y8Gu(kY8*4ru(Fe8HjXCxh@w|xcVrFf
zCh$cN`6M1C2E{-9DPphBv?<Y!pTa&sts0=(KU{nx9?aE;E4(dVd0K>Dz5LcUOE-Ie
zAzj%qt^jK)`pu$KJpb(92fCmc6+o~nj%Y6iP;FdoTbhCAMc)GD?ysPqj$rJsFrBLd
zBHaZbF79!1l)mP)jROyI6O%!gj<fE!!?z#K6Cdtr1!nNyEY^~AkYg`VG2Dv$##CfG
zH4NSd&NlLwnvooReR2U5)T(;!d(8zkhsZQ{i(mNd5B~++sQhU=b)|WUhQSEgr1(0j
zGAVn*>lL`w!1q`WvR%gLKwv5;l0&1Ol8Qx);ex$CK*ol?pGCfndxP*Ji^_m-0sA(w
zS~BJ#I~!c+1^tl@r#?8c?Zso9+Lg@X;RbySOMS4A4;>=b{SZ}jGVSD8wu`~xLmNfg
zEvph^34gA&i2QPgAtZf=ACrqkHLz-Rfi99ECunQYWGAxiKEA!s($%X(hli&l8N0wo
z_aUf0YvF7Wdu)^zWA}j|f{p%qLE{3gGE};h)e%-;vO^5n8;nBFCB5&b3&@~)Lr}uh
zr_lIu!qoung@{Q_7~DRy2XZ*iUbKCib<q@?EQdDN0M7P1F4YJk3}#enc~l6V=`Edh
zAMOjZZpl<gOcxQ_uy@E27~(E%Xl+qLlfGDH0TOlqwKMD{%-^bSsTWRTMeG>P8=y2|
z!$czvW6@1CYuV@SXWXhE+lm4ixAukq*%leUy~>Shw_9J7Ke}3)k92(u|M8TTcqtcG
zRGH~}*mMKjot@m<ppC)1)#T-L@xiy0G=+5hh#e=w+2SFU>kYSJ<f9En6O1*eoO`3d
z1RQa*>2=~Qn5aU5rg3$=di7RU-ycTsHuw+i>W=+<4Ef*_YOZnHTm=vJ$@Iq1?-F`g
zHJumRU3=z#{n>x$_P(Gn)z)>Vi+_c$`14=ABWiI570u}|=^^y02WgD|kYBR*Vhqlp
z8r}trj)sIzs*uk50QQ|gM}<~}BVml=%LPt6ouGz{Mc%BtvR<@5?g2D}$a{9LEesCt
zXEy$VA<V1moEi$USedZJv-%<@XGCKC!9O1YF_z;BCaEoOliGS-+ek<c{lf>WD|@qb
zcP=ENTEE>4<gI(Gr<2jxfyd3ak5mL2M}NZ6FHat-w!@e%8xZXSfE<SQ@zm$-Fhtv&
zaAvBiTy0BfqFs`bCME-L91Nwl!fyotKz5$of+B?-5$TI}TS^i8U$C6pKaI#BQ)b8s
z|L)JuIX@p4GuZ??>7kmJ-y60!`Nnig^{sxmW%>3Q-8)cxeq>5MK5AMU9RyCJM2tQ4
ztE6H%PPlC~L`n(_m-NQCSjP5iU$lZUS&SopKh>?(9acMUzVE7=hIZEZa2@Axe<-9g
zzt(16SuEZbY3ChdZaf2%_rt0$1G6-E*>=7<8Z(<%DTwIKVzq4mT&jc$A$-jZO<Av8
zyw=#ep!DlTDwM8@T|kgqo}$*Du~>3m#w&cTh#mK$Y&j{ygQWD3EL8Th3j~R(a|d0M
z1PAmILT-?#M!Z*;SctT{mZ%%bCFvh|2N0JYebEw$!ht{)kaN#}7oaa&k6X<LotJBB
z*~x5FuQ8N|&~b!~tT97xWFP=Pg@uHkJ!EVocvXa@)pgQ<X}ID>Y4atbs>09NNw1a#
zfeAWU@nqYrb8i#IF1;0fnUAT^PXup=LBk?)c&7mOgNG*37jE*XAP_AT){-V@4L*-a
z6;qIN{nz}XL(^DmM#mWNioY<-_dEn*JSOCy%tvh6p7d3hjCv(%;naBDq*ve{c-E{E
zX?+-}QFxzY*NPD1WovPD`3dB=A-TZ6jX}{Pf6n9}lS5)E7l(B5$i^My^xA<1Q{8lf
z*n{4GbZg+_MXNI8z9lfiF!bp+88G^4YorFNwTB0p4tw}eoiPNJ5j-E1w(>+Ut~Gl`
zaz32d{~=<>!UNR3p&GgxbX@kA^gLM^=5gGiO(V94_YGaT5!+nuY9cNQHvUbPaO3JJ
zIgVL97b4UL)-u9GUnx}^C<Vmi#7uYBl;_nd8kG*iS7R1`hoxL?tTVa>6NId&9HK@x
zEDS2sY41IQAz9s3yM}C-eP6Tm8G}+nFG<}yuMw7%VP+>|Cu5U=DEA_~_>dWp3zsZW
z$H{S3`Xz<Q96w3r^nJdCUkY6f&enp^dF#q2dVuV}^$<Mo89rnhC)REnyu215xZ+D5
zvl|`ahzK_Z^s)cz(cas)`A2r%`gcTc=_l&QBMKhN-WWVR0h-v@Ev+FNPv8SLs1)rx
zhGv}X^FAcH?`2vgxBJ4_bgGIt3dZ<KW_euafxiKzw~-_Z`niI~HFN?Emp8F>hu5*6
z;pZnyN9+5^JL~#47wQcSO?|!w_UmX+&bfP1B;p1pge&pftkP*Tj=QbuIk(d1cWLxT
z7WVX*Z34m}t7pQ<(v0XJS5>wu)vqV6{p-H2V?2>3pPJTNjZ%d7+OKug|B#~RJ?np!
zv0P>(grv;xnd(#zA#5J+dc&fEK~F9FLWt>C$`$+1S?vN5&1S>LZBKEj-VZxGtIkC~
zbzE(#4mFZ~LCpldNwIUCA`{UB=}3#x%p}K>P~qUQcVR0iTqu6~gM`-oYElasBsr<1
zIQg*^mMivY(M+>>K*wEpH}lqKEAy?%S*$vEyYBkw%ipzokweCeb6AE5k0#i3o8XYz
zhOcd2?M%=eupRno3tX4YMZ+vXs6Ez0X;2zek$3rM&-c&wIMm{8J)JibZBY01wL#h$
zj|-RZ`Qz797@`l`c^D7l>rW*9|A>pyIP4o|f@AOzjRczDaoOozLuqU&@us8~_}?dx
z0#SvD^@*=U9NIq0p=01Q;gjOPtD>79;Lxa;c8lRDL&OxHPH3Qz^f&z#ovTEV4IA{!
z3emD&hzl7wiG}Aw34^BlGGs@~%IGFaj2WRx;`z4E)lMeVp4K?-X=M_{o5D#}3h9Zo
z>U6nK8_r544zi7aY@F`iRH{E8uyL4rG6e=Z1msnQO_8MjfQWfh#y1K4j578OV}6-@
zhpu<P*iIP2KW3Onu%dV`@4B^=wc7bp#zE;`Ye}1`F*0!-8Z3ldHqFzIR{`(H72mZ-
zzwaksm4nsv(;uJza-+j#N0ibcY_>)XteSopHb~#}mJlEG*ptCGdK<w-c5^BQ{q-(L
zw&{L+<a68%sFG^mu-fq(kfVQ;Gy@8(@?}E*8w|3=yy~jix>N2W(i4>YFj)I>J27h7
zP0bdL1j}M4Fkc#bSxULVm;c}0=P-6bkYZ4*))-ZBYjG?4se)qC(;7HQ3zYHr1A}8_
zecEi_GZ{mC1d;fbXxM33ql8#@n<zGkkw`m*XDH(`-fT79yLt?XIbH4*@bBVtkeCBJ
zyTCgsOUn6StbBwBEc1C0S_~b-DIid}w>xW@-Or+0kJgq+__^7()h#^QUwMfDl88?K
zd%~1+!e8-9?c?*mPxNnkLIYuKk=pn!vfzjsUOMwmfx};47lQ-zChA`6#KeaZ1=5rS
zqXH|n;7OD-urJF|EQoDjm-Dr!RL@_k3HPXP+2R$Ro;*$iR>5`~K|{n$v)+N1nHvH<
zgW>41fbN){;DcQ?Jlnj#01vi$HI&(PZxclCPOmCuJEccz8~2V)R3Vwgd{D=j2ew@@
z_SZXuGNUI-BL{CcnzG<cqwY;68i%e_aJ$lyq9(p>-><?P4naZK<L<8}O35qSP`h!a
zF42EZIrousNJb(Xk+y~fdyeVjx5DXHcHV#2Z*7TTX9l|;?kkkkDZ0u#?C~Iua$E=%
zbTv#=t!7}NhCjL5rg+Qj;cSK#iiFDr_j<IHrni0~(bj69Pm6Ae`B=D!MzUaFa|Jr~
z(zM_6Y#?nU$-_K&sc2(~LMmu%$!P}&8VGf?4dt5tH0(F&GQ0D;$941&kmm>DYr=Jz
zEk|$vVL1Mil$sy?isz#=OT!SI^=a^@81BAT!|wTZJ(0|@L+$!3*zeUE?cBVYatU_5
zH&x#u5u3%+rmQntVSmmd%U5<Z`u@g%Ur9P0pVaKr_!Bz+a{re*CTA=C9gg&@z$#2j
zkER(hU9hh%E<D>rXyLTrGuFbqk#hL8mrQ^pORMs~Y*ogZKki<ofyFfS>q_9Ly4P>A
zQuA2yr9+x1O2gR_Kg%_q@P@Jd7B|rJ_ZC^UPaO)3d_<63z!`2T6E|aaX{thG+^d+V
z5B}eJ)RfAJelzZmD9hxn$mN3gb}BA*SnEPvP{Tcr5;`pPnOnB2F$0o|J9~o69DDN6
z$X1)Yu*!G;Sl#dV$@3bKlBnlPc`dc&c61fqiCrM7M%XN^V?s+*WkdO6K>N(uyJLs4
zngcXC-mx8)Wzo?UU9%3Zb$ypqqE|_oaATUfaJ8m}F7=wph2Dr$W?SL}O5L+p@7bN&
zu{|pqowBSgRl+5We2#P+?u&2Jm(4@XwXU1kT*s#nnu4S5d^x917BbH)OLi&5BuuI+
zd(Q`4Lw9Jzwwxs8#^%#+NK>|c)WW$qw~+U|`L&0W(|l}~jgy4Mr0#;|p|s4ftNZIx
zQ%f=jk|H~0_HTTNL(K#2^})Pa%D}jLFuaqjqUbvQgh+W0fubxmZQ;4H!JBWhhy}J^
zrFL>>)eCVUP^K1X)g3SXJ|db-_ay~R$$Y61M;^xgk8g9}ad$uy)mcz{olk1C4Jpt=
zu`Tx6e%^G5{k^VjyrLb$2AfS9f2u47PD%d6B0|K)vx0oeerP{T9F2IuIonP`&!sv=
zvmx(2g++M$Z_Pp~CnVy;$8EVTCSc!0XcFr#^d$MTL-L()IU@Z~R1YqP!E{}0v>$R~
z|0?^}qn^i;M*n|2y=6d@@AExO$_mo3NSAaY-L-^DgLJ1zN_TflOSgn{cY`z{-Q6s?
zG(5MT@9+P--Q72P-*e5(IdiT#2BuVWJ&?E6^Rq}9p<__z2@4@u_Slci{gm7RuI+ff
z%<=RS1IsMBHhy@GkIS8kl39HmY`wcjLp1Q%s+&L1dLILXbPq*Xoyb*JMo4l9HV{gm
zMo7)IO^Bq$CfV>c3$iDAkQG;Y-HoU5`L<zfy^tE|2b!i&r_SmKXb9{xLVJ%Ap<z*9
z+tL{Om?yYePOI72p12~ivk#@f(^a<$3!iy2m@B?N)l=70^&v!4Mdl54{ql8a6&lvs
zaT#dQ)`)$OF%rpAs$XN@CYD4eIQL{RJ26cbX7F`Fp4fUjqSa#|X|y?A-cXq+)rf;+
z#Lb!8Z|EB(Zr}80z^C&r@A8zb4aK0d!Q(fP<|G_j`Xf2TsD<PHPxmelbp+qngDDr?
z9E^CPL0oH5Fbs@tj<512QAI{>$idI{Ai$39hmYNSlLD6xMMj<P@&@u*N%QqhOpF#S
zb%N_W-y7ld(esT#QGLcJP5ka>tlq}iRo!`ZamDUpFga>FW#S%h1?+dMs2|3}Vr_bk
zN2L*TCB!)qg;md~4eB9{f|B!Wbu+mWg*ml<hhXpSQk{YI6*5E)_i%l5OisFKdFyi2
z08ep9p7;A?;Rti%;1%Wq5q;;KK5p!=2i&jsN3~xfS7LzCWvwPOL(Q^d_0|WI&J~If
zEo|x>Ftsw^{L0hwES7)VJ=n)CoIQzbj=S>CBVX;Co@v_Yl8~cmU1z9%-xLh~G3Rde
z?re}8;U4k;YsbB{tLxNBxwKF`yEqQ)`9?&R@7w9Klp`u;Q19D5!|3<JBRZvhkX$qf
z!=M3}EwA)<ryR~5pucKzeqkN4e-|A~Op^o%^nT=?_`?g~bLq>kdfe#I&pbPZTtMMv
zQGPL;6QoZugAyW{+T1jcYi;cLJkSGmiab~B1?loadj%UgA{IO804c$q;Hl-jF`7z~
zfasu*uJNQB#AEB$LxZjX^avM7DbtDQwHA7?tGHGrf8KR<fn$*Xo47ODJo|X`73Nn5
z$qPIC9lJKjWo>ZV@|HB919m4-`Mw{sU0;+;ks)^u+UulEpZBTCB!cckzDB`n^0Be`
zTwB%HhXAy<6R#@bkh|Q%5J?2)h|P{8ILBo9bPNaLFt~_fIE#~MKpav8?c(I^Q=Cxv
zGHiNe-*DH%sjARtoR~XxLiF@(HsRpyrux{<Af*e~lVFpmfbEKl0sNEr<@?q4#<ieE
z%NGyd&c?pmlT~0Fz`$IWA=!;x?3obBR=|DgK@(<+ap)dq_Gb6Om!pQzj@Yy9iVf>A
zn;$z(FR=7^ojP*#^Ha-XzPU)49PVxc;m6LocvhgRRd`y>i6!fOzbba;XMu)@>Kxj0
zuw{`NbkeCxeuF7KI70;-$M&WkI_OKe^Aeo>Ui6&!;0aJA>&y~{0+gy_hv^ArVS3+B
zsh_Mt1YE)Um?M>6yA9)#%B(t--x~3lou$J~N`1CUEC78b7J1snrhlw+UK(DLoa7Rc
z3%axZe8fhgeAyI60Sb`g`9XMv@DrcZaXXfnTnZL*n!DNJ%L1N)*B7ZUkST#9YNxTF
zt_*AJlZ=~t9?^=pkRIE8@B|UjV3*-;R5?(n-60}%V+mNj?94;C=Q7pEmH+zOBmEKa
z;&R<Lw1=|`*Ggkry1^g{2LJGA;>)J3EuS;-V>-Lm_a~k}q_-sN(*o~cR)3nWD~kke
z)OqJZpzGYn+~xV2m5o~i&X21ie{tqQ)G48G1wUeUj4R+mxX|l@rl*chjF#;LB#s<P
zh}Fp8+MY!$r}TX%U`tCf`Q-}kO3(Hs^r~ff$@Xq`@9}<#YUV%gJ_xnJJw2JwuRL>y
zdU!@pH2PGbFmo8T3XoMvJ+&K>V-t}D%~g{zJF?!u&me{lA^Tij*3T`;bWOrOpy#yh
zKI!XO0!rbhabl8<oa=UQn*0QZD4R$=EMS*T_afx%5mwolLkSwg$XQUM%&2?uT3NEo
z!pmvH4%rfBCNQ(&2Di8GwtMvUajdXzN2hp<zs+9ukA;!0YOnM#U)~L1ljMBjtq7R)
z)=j!v;F%{!3MoL8V|a7J#Bg;_?N<7<_lcZZ%rnh-WF|X|B?k}d4rFm6`0(T~k(7+r
z2Yy-&+si;<-$%Ep7L((D9O^Y*eZD-=yylE#bVj0YMWHXO;>%t)Ui4X0waOsh>NEfJ
z?7d8`*4R!xDNdy}>}n<h&wy{J84ziV6m^Y6FkaJ_o5mX972K=L>Lfc?3zMm)$dy4&
z`6%V9nUuSigeLrl6LJ0$G5N?wk>U8}$Bn1Z+x0EE2WL?&V?&p1&$qXzxFK(FM*coo
z@^z((i*@cX9N&%EUU{NW>vEWiv`v3)XkSCK|Mq~S`pVANj<2iMQjO6GZZnHKh;pR8
zVGc^|x5wvBS}Y3h8iRo~zUbS?M;MK}=W5N?m?`Lw(h*A^p&0~5Ofsk(qX!o~DNhEH
z*ZYngczU~?p;1K!tQ(UV34Aq}EP14s>GKO1>I#j0J^ellbIs~#2Lh(AQ&rxdd{;w{
z8hMCB()_mQ-Abs5;K?8nc3XtQn*JJWF6m?rO?vW;4=$XN6)3ST9?+?cO1kx*Ma>ZB
zIeZ8~&6%paCisJcD~2SF^=Z5GUw=B?B+Z2@j@5t&bNV%kb>eb}E8bKxiBr;rl>5<|
zw~TZwFH*;dOuQ$iLg`aUm+4x~UKmTNgU$-R&e;-Mb*5KC<_$@Mqu>|MbnLfHo(6~Z
z%EPDU=4|D~R2~r8rk^<Ce8#8}pF?<%2nt7Viif$v-<U+ENATP&b<kJrpGHuF(sOn9
z<9s$`znd=AWSoRZwkm-!9+3S5m0#H|l?V?u+a(vLbEfjh4~jOfT-6TSDnj59v!6y?
z?%f&UgBcl2)bS!1;~{ctkuCIu^j|8=X&Z*9^c0T{9SpweZMpwx$2i*vlZD&ze0*rg
zf27HaLJgpJ8#XC{g|sn1DS-yy6U#=`PzoFipe?6)GZl+uq<6gF^Lz5^X0W_oL*|<v
zI-Xya;E>3)F`o=5Wvz;=akWu3a_1!)yK2(B3b9XaU^*)jo=nY9Ke(+Rh5#;jA1vQ6
z<~XSP9a1T)Qq_0O(MXSN_|9w{tUFpCQkh6;Sp}guSeOg$ZPe^&6Vio+`!&PfKLkwT
z!$xnNj5ILj>fVSocLj8ks3Sx^5_P#re=o(?a-w7|i|CkCC$EBl&9KQ+ZHluinQACJ
z-D`(>ewsuB*RmR!#)m{w!kFQZzr_&#{~iG=?5F7|{A?+$2CR$_25DkjL91}f$N&lu
zEma*Bl6aF*oKziF5OJ3+8q2%9U<zx7e-NHC;&hD<J)lN~$Ua^gIm|}IxOT)6oCx8j
zA7a+D=>_&c0iZN8jvw#4xa-pIHSv|`MQxmPj10IU>H!>9`Ylh%H6~bm4K$2clMo?F
zV$B8UD5YTZ273YlktMV9mru*h`PN@lt^8NcHL)7E8%{b;E}4lo0`Elb^@DP?4S!O-
z`HSF_%N#JtY8K<HQ`J8WbwqLaK}6a31&!>M9@oif=Zwv9xE03Fail?8W7udwZMz<-
zXlnEt#0UW&I4aZ*<#ComT>K)IW*~K9xuXhdkqWl_3ZB?6ceAv^xVZq`QTFfMV+E!E
z!>C4kxumg{xitSC01Z_DPD6w>7M}~ejznOe__7=}R*EFQaU`oO%574O)mk_%m2-ny
zI7^d_P6_9CJXUjtrWil|+F6&Y^eL&-sA4nrax)9D&Hdl8GGnmBx&+P%3SJLnV<s(u
z_~XtWHfpmBbNITN4bjfK@dNWW@e@|O*5)g}(BkFqDQzMPFrDzsB@k1;kiWm>lRv&u
z56dMm%8`(5L-R-E^_G5YPVbObbD~``+i2ZVp`v0SAfCr?U>%kML-s^cY`VZCO*<Q%
zbA!IE1iJPS%$)FJ->J~btDxo91GOI(M1BN;VLp-GnXM<kT2!i|8^{!Oi~hlMU2Y&9
z*uIUpvK4AV4Nw}3L1QtUZ3BYgU5RAS36(S7V77d?_@VV4SrD(@NyB`ABmI14eX8{N
z{s(I#{uahQ@Z)&#ygn=(ZwO20EcbgIi%awv&z^URN?QGu;HR>`LQ7mrBF_3mQ|!z8
z_-XWc6iq*|6?7%-bK|VuUU*|;gYn?^wR9}%f0y<UPxYM6RZtW*)p<XhR>z9UGjuVd
z!o6Xq%dST1X~=~iW#|fqiLJZ)e#>k<wc9lydw{vy2qxY!{LMawE}H?)j!x7+M-MGu
zW3<#lQT2wAu&iN(5U?e{VW7z;<JzmG@CzoRL!BTFAzG}bCU)7-Q~tH2p(6o$n*Vqm
zbZl)<0LAh<*+49t7Q6roUEKO7XjVPe7>^$CkUmggi@#oa1z!+>fR^*FMl{yFDW2rp
zoC7bzJ5JtC>W1}!X!?x^mKF*E1iXImu?vfiZMrKpr<|FHty5%?jb8i*-P}?EK7==U
zpZ*#?+g3PwcSFb=5Gh8TMX+;HDF)}s{e^$X>VHsg4H~OB+CF6e5n83ig}1vH8_d0J
zq5!|U7#I=?;G-a9w|nulNlLx(Se9M-j|O>N?yv=g>%Unm7+wu!$Y8zsi4!pCy$fN}
ze8v!!=;|9PG*vuhh8m>?;VsAM4yKVerh}YTQI;EF?=!wRB-G2u>G`*PT8j7&sH^{v
zxX8zf52jc~`kCIBX07zDb{E-*n383$s7kLdW=+=`J~igX_Cl7R4=h&~$QqJo!`sQ!
zu;1fSKOeBvaAL*#?p49O@alq}C=E-cO0Fcc*E)FKFV1YK3PLubAw*E}?&6)ya-1q_
zm!`D6Q6aDh-Cj9r9Gfluz$>%GrkT1KSdn$~!8m@26;uMs{Hrrhf_8D<{fLEjp+sZ5
z-Z7&d&eYN}*wO=;zMHTWZ6#U2SgoLXYsQ0070F5^pti&n3~vq7YgIc&%V^l@1pfZ8
zXmJCeAfVaN{I*uO!;AF3;AqeXO__^vxZj_lW(b)<j^D6xWp?wLR}VoP%jM1gg~3m)
z8D>xqM%58uMfNW}&}om$8?_FZH{yP;gFiiE+WMsWA@hi4iaF{pjx{V=D{}TFd_FHy
zd|#j%`RmDVJk<GL*%7bYj-Ul-a`>VPc5U0WLbz<L)IyfueDJ3Y=9MW`x*_LL+Vb|w
z%N6?e%HTo?_*5bc%2u1CYWZhToreUS4&(5ak7=sUXc{Y!p=y4v#3Y;|x2R@n0bns2
zSmUgC!ro%06#?zpGn%Oit|ej@J~5oM1;@Q9<{GCPx%nwqeraYixXxPdZ|C|tTli^p
z#Sj$%wpuuI#y;M57N$HxOesADY74Eithlbkt{v$L=1{%*r`DP=dYUh70MYq>2ZAE(
z-~V5J<Dz3J9$!F*6=YMukX=dP6wW<8Zr{*r?_ZljiS3qpAW`#@R{T(iI2kiSUNRp*
z{5~LX;eujD{D=<mW%zreX(vm9#Fju}IOZQUsud~qq5QY>dCXxbgukkfVM#q<YURct
z)(D$Sy989$M8*o$Ocf*=Wu=G!G^RYrV&?~HJNqrE-yBk`cg<baox8jW;O&j4{?{Ip
z`;-!jUv3$nK7w2xS4@^1kfm)!4PE&xUPWL$vm&AF9>bQ+HH-tT(kpO(4ElIWy%up$
zpOQ|?@k{YIN1$6`uIW;F00ev62Qt9dW6$yfKFu6QX1=j0&JJVEWFJ&Q0kW6#e<f2n
z3=x85i%_?P&B7H9^brj>|D6iWifg_b@r%qk_;?)-lt8^^NumS4-$FYH_rv9ms<dCL
zXfWE|mpfKN+~xRw2cs%vmQef0(!|kAH~wVvuc4}F`XYjg5GC~~(HCHF3-r@=kO+nZ
ztCf9fi{RL!RYK#Gd8dCDU*I^xyd7VfQyJBx_;yShvj0SPQA;QEkcjM_eQ3R-%Qd!n
zv7rnIjl-jI3#&sx4~`QG;({N%GjLfhISZ~{LEm$j@;Qy#eQzh=>8R6inLXlC--RHC
zLKTUVzU#V#I40&^ipAT4L{Lr9<=jvvk$%?ARO2_5r9LGI6q(?k;KGN7IcL$MSGkZG
z7hA$RdhC2SX}v~*9pruKM+Q)jyhIQ{{DOF2|2J6Rp%~W{pH~0^r^=aciaAWIl(<A(
z;I<6MKa|C3oi2T&>{F}s3gP9Pg#yZmmK`dyn+^r3S8V3Wa708G=@?am0ZwkWwfAn-
zY=cRylzsImEbYS}{y-v#y+++?_BX5}YhA)@Ty5ATzJiw*sn2{dp}d$dBA=DSmuL9a
ze-2S9i23`+FN95$jnD<lfv*ZuWV9_PiU;r1)kx6$S;=B2btN~Z?aATqCeLtm%*-<2
z*9jGY$f<Z@?Ry1rfbhaDpHjkwTf(fAosQFcFrPuv>DcZCJii)>^S08}O(kh;>=w;z
z0}GMxM#@!z6@I~p>Qs?j-#;ep=Nhd^6E{Chjub>!;JG=`+gD40hwr_=D&vevU<J)!
z|LZ`2hsAbY#RBS?%};%G*CGMLSPx7b??VKK(NWlw4J_ky{xw0XPb;nvRw7NqdbWiv
zs_<|hco_?;ctn<D%N7UMXE24(nX)<yB4r5n!20e)YP$)h5Ip?^q1dupU0SxpW3tZP
zCH*}?VKK%P5XjWT&SY7>#r#zg=<4d&NA$sW2&MwYZaFxu!?%C?`Ll_BA2Y5#XDvZL
zNPjl{08bW#Qh%hoj|L|M1=21S4OQfLrWgLxBAE2-=E2GVLeP+OF5Iv%!(mUlYu<cu
zVZXo{Ydob+tQP)ybnP}uBb<4Z9xG~h%72LJE@MGQ+*EwzIQ_yKzYj+qo8=IRY?O2Y
z=X=3g<`8WuTH(|W*+ndItXc8@#Sf}O4yY&EFw#IM#s9z261jGs7HBE-=x~h0A5YMw
zwJKYN0~qI;hu@wcR%g$|Y)=JGQa+g$*;J2o$sH<H{RviLy<acX+<PS0ZJ^Wn8?VjX
z$s5U%F@*P9<Z_6j-@7FM4LRvn_%p6<lQPG!4b2FS;#3}09;Cxui!lNAn?z{nA^V9*
zwD9vAI-$m`>eDuJXV|p4ft{{}Z(I4t2UhhGAwKKYapztilxU^hxN)C+FaB(A)nz40
zAH#aPNVH{6Cx=S52xcG?<7GaHu_Ekm&r?Hve?>A!IlVgyW3Kw!G4>FMomQY=DUQDc
zFP#`~+oxySUh~cQEUJ_BU#2l4{a+nUh>Kefu&3T<)Ob%kWj#%Uh13nn!VdcNE}CQ`
z;*Bl}7iMq}sZ@AZpupQO1(Y4!qmcQY$IR)DnQ;X*Oa<%WY{IE-Jh8I{o?uc`ht_nN
z%(>TvD#GDrb5VtVqzY519OjDyA}>G;13X_rtavmdZ|K5lk{PskqCe$A?mg3*^3e7S
zlA0v=eci1I00;EfLO;fBY~y8WCDV&fUhlfwEgckHkHmP+NnrMFWbi+zwlq!rh*@1W
zC$LeXwH<nKq5R1lYh1m|?_jfqj4j4did=k$lMC;xWS0mcuL|%phQvcCOChtT?pi>K
zQ8z~NT)XobgOz<GRhbz)R%2~Tog=7aafPQTkp!v{;{WP0g=LzMcL2pPoDhFRYd~Kv
z6G#W;OE?#`HF=_2pkAo`q5Yl<uxmJ7iw-VAxI&x<&X%T<K8(ffWQoNtlBLDIYaYYn
za{f}#TmB0sW1i00g5q%jvcoY?QkQM3lc&iDmqY+(Av1nFqrF}?<jDihr~*9~nZ{ZD
z)Z@J6_-VW}i&MKJ-I0~xhZ=ttUohGA1Jv03#o4E`;$$q6^pikLsS;(yzSMr)GZVI^
zy`Vv)0xZuYBcW||#u!Eaq4aMB1MPafT{2?wP){4#w?(#CF8Dfznw;-XdoD*1u%^{o
z|303)NvD}J8?KMN;ezwxH@dSvJw{N^;ZTw!09<J)$K}PF2qyv5R`(CTok*(OgLGtw
zB(&j6-;U)aTw&W6zLN9um$L4TK6u3@eZ5|<Q{KwbU>FSScVc-p)Q?cUYZQU6Vx-8*
zdC;?A9VP^qSiDWYHoq)VDH#sei>=G`nrf1wiC!-`snbgsIXG=xGQ+}bqSR(UeZ$t%
z(Oj5+X2Z3O2Qa2RabDmb{8E6S&c0ed9bJy8hlV~}d5|`p^yGn(IFpvq$qaiv`{{mJ
zpJ1@7{wR!9mS&TU_Gh1Y?&`8c!h8r5*8x>h?AJ2pXi()-sVwgGW&$e&{I|(Ywa!pF
zq(qTe@3ZS158W4c6Bk)ic-g~$IpY7-7$6jSqWyT%`kIhsNm>Hz<*kb~1zQs@Rpwb`
zcgB6<5VUHct<9K=o3CVUyL5weXZ`!ESe>deXPF0nwWI(L_BRO}68+9V{dz1dP6}mX
z*p=h)fuT#oV8gN#rD*}j7Xg@y8c1VViK@s_&R#kBlv>9e#JYTK{`oKtl|xpA{Ir41
z)mCLSBO}hiDoOfkoyTCM%Yl4ZR|?JQ_NgW0h~zLc3|+}Z>x40?ljV%^D?gifXRNRN
z`UZQdIL%zr-(W(qZp9cm=q*<021p7iQ>u$nKF9RJAA`C;gE@k$ZZ@oEC%-xQHS-_n
z@@DC>?TvA0p5FVKpeJI?k6~!3n$m#w@NY@D{Z!SsGX(sz9vT7u^E89TQhK<WG=xB!
zX+pBC!2p2Vo&Q&FfaGdVtt6Nwfb>023~ROrld8?-=FK3T2Ivt~Y(XvL;T3dH;CteI
zBs>1mXoNlE$&aOKi0UKz#1&Gv?94{8-@-=Lyh}d7MmU9`#m%)J`#uxS%C%Y;M_v*5
zE!|nem>xg{Q!JWe7T%*SqT44^+i@{3rF=7=im-kX=xWAXu_6(OfoXa^kZvxrpWwXN
zK*lU89|o=_`|ed|qJ8!2i8r6s<#PV&lPfNXyim!{N-ABSW2KYHFT!+ql!a)si7X;Q
z2$!9skH^vGi_(h^^E}_gixqh+aLLRUZ1j5)ew6njN(uIZBZKP-9e$RF?YcdTWXlx1
zF5s5^s&kyX1^%;O7i2Fo*ngn)>nVqzix`G|f8Gq0Nyqlk9Df*H$o8_RL(k!|2}<V-
zoDoUJ)tcY4Af`fl&|i61lS3Pif<N*rMV@psajbp}q1!f_RPye>Ozr%?OdV)BJWU7c
ziK#lmX8HFC(|eMT+r>GNzLnNuP=Kjl3f}m5_PXGj4~m7w){!2OR1||XOL#i3LsOvE
zx}k)u*EplA%+fi2)A24gsS-nj;rr}F$_mfS`GA#<gABz!gv>f$+Ee>r(h{$n$QEkX
zmew6hJ{W8QH3C$yPSSYMVitg=u3HRfH-k!l&b!`mLe8Iega1-${r&~sa}ijCjSP?5
zEeX5q7W4HZq+B1?F`EV8V({F#Oef;}Ec4NDd2G&%htQQ7i8_a!!pbZdhE@Hb8|7c3
z%27yGJL>;*Sfps&PGx&lx@7XMJ~79<T+E%5)_xKId%^h;^v?~o-tXBrg-zR9Wy)Ml
z8oiAa!oy;{5Rftov#;(dhWe^~?G%06<>^hLp+u+L!sR!~H;)$Gn?UV$30J%DMj)J`
zCY3EGe>d#4JYF!$jxt%3rn;$e3&zflzP_oERK2E(DZIs6GeC6>u($&D<!r>fddsR!
z6g2;coX;}<*LXVQ{YwgXmp>8T7g(gT0yP5f1H8fgAH=rjdo&CFjeYw7yXVb`vxl{N
zs-o$yZ-7;Q4Au<EZItI?7RvbZHtEXv7yd@?QQ?YDtj#?EESLThLyZ9d_V~^P#{LR<
z;S_c^^Tx{Ny>bBj#@A(@zArRJ{m?<Yr&tn3eX^5yJm|4o4%XE?a8m2_7_ZTys;eTk
zfwZ2gU<~W<DQ@+yLU}08hHMBpbn??1Dg$+_m24{CJLnzQk)lNnH8d{SWws)_iye~1
zdci53O%1x$X>YeInEs)!drN*yecRtEwiYPi41G@VIWZ_(QDi<23nnwdGpbHC`Q{M5
zc4znO85H^BTt;!D_xWLRQt509auz4eqOwgXfN>5Z5XB6TZUWlW<SJ7R-eehyzId6U
z6pgSRt7>?73Vir&gO8?wCC~^}q{J0=6BXvttAmg*FggP6_`Y(*PxCpY)oW@w)PS?Y
z|KrYr0PbwVTnxx3@4kPHrzr2S<mwfK3Y9!Qt=k6}Jk4}=WqaSS2t8hzvJk(U0QG<q
z1e)PLWK2Ffo*okhA;kr#xEx~HJ|wolJ_0%zCEA9t19S6MJ&h!Ym@Mg?SD%bVA%;xx
zsh(7w810okGRoMX2tIsL1jCzdNJ}}V3Nl=hfX6Jh?z_^MmM27MKt?8BzESb9p0)eP
zNT8x7dDX9}dH%EB!mq|bHqI~lp_tE?EvSvBF2at*%y#f<5JDHnf#yk4AFM7+<C`fs
zxT;Wntalny9tuw>nmM$8c1YJV1r79@KSkal_`*DW{UQm9XPB_<uVJy`!h26Ld&Za)
z(X`u3M^Yl?j)8cIu&CB_iK}Cg{lluyrr0qZm=_gdXK*!o_B+bv7sV4-3i}a0(<c}T
z_o<&sOUa;Hu=EKIkqo>OZ2On@D7TNEoyjbM-Y^8;XHQ?vj^3mNy?A6e`u}hg(f{ab
zT1o{x@g~aSi!z2BIhD}mcS42sH=oHnAFp-hk8aL*Uj#90Bm7B?gadN;g`k#PgLA$c
zlB0XVLY^I=NhpIfg|SsTz~&+~>+Z-J8w46-H2qJ?GRoH7U+0`=Ev7luPZRfCJ$AEC
zoGAOA-<nS7PaN5P6m80Qs(uJk@kdj`k*A40RrY<vk1)=l?FKxT^XQv~Qj)@HQAhqn
zC$?v$f#2b3n_h=fmR8R>|EibIJsH(%AEj&awmzYr>QCq-E;8t@5P`aP^5-J@{itJJ
zN&MYb6xYuFJTwmv+O1}ZEw2U!PZEURJ~5pgzh-d|<cAueuW};86*pQzz;HQ%bd%i+
z!w@z6Z26FfG1m6LB?7)?4H{`e_*)OyNj~{=0e5bH#f|Vzc&i$KvErFR|6!~=hL-|B
z+y;N*CWR(P`mOf1urh1C@@aQsqs&04C)Ve}<k9XWflVTER?9ZWmmPH8JRv%8a3BcE
zpUFVfj(n>+?^FJl@Na)qQ%wQ(;}kR8dm?e$TAk|Pn&-xoOG$cc&7AaE-X)Q*CsJ2&
zU+^?f5Rr3b!ZmZhJ$!n*Sz%Y)o?FgY24am$s~i@l-I0j6iVff-xoOrkF%RNno97lD
zEzP&2qPYy5Hm4f5KTNJQNLs#k_tgKg<g$J2`pH?L)-QaaW2$l(Sagpnf;X(<;D9<z
zLfymk+dRMUEE{@Fg$BEFMc;yyEoLh&;%-B|GD!Z{DU$;25%ZNNWrYx9m;|7M3zk(7
z5N~=-e;Th~+n4KUa=YtEcT4=z&3m?Z(p?lu^=`SvIVOjkGQ+LRhCbdrD6`uM@x6es
zk+gG|O`0*HPqBrvwc*m9E8cwV5$-wsf`U6)tGyIW!&XP6ES2rz_hSOi&dY@fj^XN{
zle$VQ8g6<JE6E1ZES_$cJq7_1!7h*u%ilIfLn!kgT0w8%q(;Y|h2D8quljkKx*fNA
zk3D5#HqJ!G++d8~sSM{c+b0^S!t|6SQ|vs<3%<Af1X`Db{XAd0Pp0siuF%q&Up>aN
zt5RutoelJg|Isr7Kq=PlzXaVtJNt-TeM8o~MZe>n1Wa;&7m&iTePxvb++>jr0t+g3
z?ro626bjzPzKm6d4H=J|wQ=il06&_?9;HVtSI`*FR0y^N;|W%&7Bib*e>lNytzA<P
zRi=mMM&B@q9p%`N`o?ZzeYT(xGDIsp@K>)hkWjfdir(1AZjo$AcPFvPk6w;kMYENq
zJDBNDb)))cVn#aWurIwy>gUp=?3u>qU%uT2W7rBV4SFJCvk26zSZ6Q6icXmJTIG0^
zy>weYJ0+2(2cDvgoxa)mMK7xlKXF4m_u9jYm0-ed)ph+rNo2wS-J@OTrwTHWm=xv5
zxeFm=MQ(C~2@UH@(Wj2kDsj_Xp)nWRGMbhYD2tu<YTl&robm`)1u!=6y{;hn7*ucW
zDXdRhz%%vjsCr?~@jElFicog=AJ$Uyfybu@w)1O)Tde8n*K3}OIQe8=l?)$GQx4|Y
zTt&XnkKM4-S@V-fp#Ax%4^7iIN)G!YzTURVYLv}2JsC8>IY-L#V3pQj5tWzcWO6Mm
z#Z05wpl_{gdUYyYoNF0#B!tAA#1jni>ZKjgRZOkmw`#U{`{&aHq4a%;!Gnx`ukVFj
zXK1gtr*!Bnk-(<a0}X7%X}sU3nC6}(0c4frS`--x?7zP5HYxR%wye-t5$w7SOKyq9
zRrRPV9H*PTX)#+&8thOJ@UgJgj^&#6G;?m}Eatrt<ffE!R{CU;Yh7tMGQb^%r<Pol
zr)%APosr9cfSse(Z3RnHy(r1G$(5n9{!OgwkEghW+mEs`j<qrW3X4NH@(btM%t*d6
zmtM+;MqVm8dl2hpY{PnwZl&##`=4ZN>|=V?erIk_-waG3`fb9JOE89RaocA`_u8_A
zKlJv|+d-x`VR`t$VQ@t<pQQeJ@kgf;86Zxk;nqbpN$%55oG-%Eb30piCKFStZK$^9
zTd6v{_@}RDZydb7=`xO#GMeC`2KjWxqKH1_xU^5LzU`d?>GwL&P)RX~d_@w!jB?$%
z3)^+1|0`NsX+_+n0yWNpN;1sc9@dPvvw{MoDbd7Dc$y{BsCtiGJu;7;a2PeIqFq<-
z-hijtt}Xa?;0c_<07KG9W)Ny`J0(@o*Lyep%Qy1aAk=mrW+EjThU&1o>!{|`2D-YR
zo*fe!n?$1eyIy&V9LWC_C;?N6NPC5x1x5m2g!>8XsKYsr$LAaN#jh_$+}c72A=gKi
zKm7AvC(ilU(r9OJSG@0Zi?S^GNX}Scp(`n$-Ag`K3A>n5oI0w1NyZDd=+g5{+rwV<
zy5wK=gqi?3On=-wRiQ}9c12G7=;$|v<$az*=DCPbO#bYWKK45DdoJ`#MsN6^FuTzR
zR-(DwGX$xr`up|^srKeFB!5g_r^!<V{B`%SN)%yVe?zbN3L7}_Ng+huAMH{F!gWw&
zilExP=&$nnLVkM-7|d%rV+`2ArS@Y~9wFUR2=c~HzZY<m35nyMk+!z(oqO&+j?x=9
z&0$Nl!4a{Vc{sqkolG>)35Uz%S(QTY0<IDVeg1m2uW4I4{PLXSbfy#TK0eI5wnc&S
zfW3JN@#*BHWxk5Xu4pC2gPTd`9!3|^rP${c0#%s#BEU5{a&~oISNh~q0M@f3BWOX|
zCNEtbb6D_^O4Ka_^wm&q1E>XoqS%{>IVp`ZFx%8ux6U&M<Qd~7Cb+Ch?D6DC9&zoB
zUQAmP?26}d>4K3;jRNt=%YhTNEMY0WCfx;F$7WWnl8;@TdaYR)6I!cBSDR*A0<~qu
znz~tZtj#=>%zqKDpuE3akdwW-JurgZx8ARAKWc5&4haNpNapNL#ltbvPOw+<?Nz#R
zfu?_}9;bjvHVsTPwrdrALsqNq9?R3qbglF{`wV^IcW!djn*YL6T!o5w^d{gR&Zsq{
zt`3bn9pf8EKKuA3cvk9-xVXE6o}R>6i^O%~)U4x^{XBxsEi0WL1j5z6N4)w2Q)FR+
zGb-RnlTQ}d(>Mt&*4V3_MBH^OI=Rof4?1_N<jX=Z<Ra>h@-s>ac!Q$W8i4jSZQ8}`
zLGhy)94$c#;Jux-UnYTv%eOR9C%w-U^){=L?!zGWZ>CKWv0$x<!DqL>9bcpTKAL5%
z?MyN2k6XND=Fst0*B{^e8MBYIl;t-`9y_UVB5EStD<1unilUfpG)}>qj<eA$+NaaL
zwdueO7IJ&U>%)Ry7njQE-K_sBq?)Ctx3Rf1^2hO68|w@Uck;HvWSTiJz_%_G*Sp<Q
zp0KwUkz}oNsckbt=xLua<Z06}eqj({V(`|!^Pg(U!2?74@6AkE%3kV(d!CR&C2f<N
zi+1by);eV#d%#*{Y{!QC*c88R#W)-LKITT*4;#duO=EvTd5u+HT;-n|WpG;#ck^@%
z68mFkyg`sx|8Flq+5^<ksm|jmc_UV&8No=Op@ssky_+lqkqmzBU^+!}bOfrlvB>}u
z<AdhUm09_U-VscbM>}{`-Uk<)X8q)x`u14PzB(6eywX487-!DMb9sM>04K|4^%Oj8
z_ZAC~6VOw7dSvToP`0_X{2AB^G`CnSCeJkSc@CWUIO`|shVJTH?L#_2EP?Dfd1*fQ
zSo*UF+YJsI=5TkR1*i~%yPwQ0b}t7VnOS}Qv|JnB(w@GZ_}x)?9?a$w;kxD>)D>%2
z_#{pq!9|;rFnfX-GREfJelAQBMP6r{j<p_zK|DA<BpMVUVzVOBwo5>cPlDisiKqX|
zCWLDuO58uYTb9!D0_PW~MEFzk+kK+!Hh66z+Zi6XpWR1eM@TZMia#=?j@X;L|2B=A
z&JI3aCCu7*w(B%KxLk@Y-5nrIS=W2sa$aF}1QapZzCGEvXnT5KhMRoG3G`~GHe7wa
zo;_Nzb=qdc@4CFnAs92xNIG9~Wp)aleLu;qf_EEeUW`!!PfLKNH2+A|&e;8YB!5qa
zl)uDhsY3Y+@s6)>OF9?g`$&}cdqSHRioS``R@vt1=h--1`5+@R$R{Au6PW_pt0RYd
z=GM*Tq9=rN4Z9+v1rot9vC);wrJ*%@3!1jqa*Z?Q1Kr3qojfX={&6M2tiAz4i&w+<
zL+-UBR#v}Snd@4Vxt=wdmur#30W0_}XeOXKU4e<Q`;<9khQZE`dt){8(2m>BuLr(j
z{1p*95w(bO1*wcpxD~VQ=2SiHz2UwUx<{|9-zH^mS4G_F4IJI5NMx~>eG&ET=$g61
z)M;FSl5f@Dw5dF35uxpD%sw?%fzs*R%K_6$XVVHt8SD6l?&oKgHixr+%F}f*QsQ6M
zqZhGE7|1>6&n){s54bV|&+}M}6fg|>+EYL1-C2F;rPc$Kpc1+^9?RX2kz0qZV$}Eh
z7Avs#VsCxba$lA(?zI#rory<+eO|rh5i?B_Jt{YFAEL;TieO@UM8xL|tJczg4i*z-
zli-ZL_Xhs$JrFd5eCdtk1CN$mE?Mtu;yAUm?9fB^$?IN7P8rsJ@`^c2MK)2|Ud!Ab
z)M>#rG1|q#-lMx~aiPKS?PEGTJPYdvpTwf92#Q#H4IC+&-|j0vK%Gt223IqA(L*f>
zQLi@f$n_f7TwX?3{aIug83xIOgr09zncwC$w|TzUj3hI_<WkmJor&3Ci`mRBZF3jz
za_|(zuOqkK?dpVGxRET2ktlEOT;6l|C6vLCX&E+*{j;CeW$KTv);T~yxI)1j-EWOF
zS>Ev<uOS#n@#Kh-r3&~Xc;<V+-#Am|006Xi4u#<IHLHH2XgZWM39amqPl&%u$H3Bu
zPCLZW16|&+S&r0j{7irECVfJ1=Q=mQd*6MAe>BBK7Er}Re$pYR82hD@a@(^<-h1Q9
zpWOz`e(_W_ZN#x!%w3@+bJ)N*rrUBoe=Y$&<Rl2|YL+;tILzX6CWU<uo?N>nHMU^i
z8q1t$zFzN?I%UIpU({xtVEg5w>om-qX^%mbFB4amS-U}wMjU(`hUf(&T@n*NuD*gT
z@KmUQLe}#nbd?)MadcC67?{Y-AQP~?0(?q1$FEeO)O|T#&4r$ZJ--^YSX=e@tn=G^
zi6!t??=>>#Natyh8DAS1Fe4|p(;v+zFBsPwD7#MckC+qhYU$(8NHjUbk?1J=kOIrk
zwH^`VQ1;J9z<PtDXo_VM?fwm)DoA?j-H(1*oCU6o(XfGd(cJmKLB#MT3LY+Xe2%V}
znB@8!SJwVhdRa<kJ@=L;8=GEZL+bAUQG{pJ*nrfj^~86Lck$>g@mlk+5kL>dcM)Q0
zwE8N;7?CQ;iujo4r&GZDM0ocr<d5sQE%?ov@!UB6l9^9xDB?;=rEeX2@D=FcoaDP9
zCmsWwrq@H$5u^F+jhKzL<FF#bz;I)(xQp-SIpz6gDAVgATSrzuGdhJDcn_|ePweuT
z&1!)WFL8>^T+vhJh|f`pQc$Mx^d4Z_U=`nA1Ys>(jD1T*c*00h!iX&1bT_2Ny|MV_
z)wlQHpkMx!dHq?PUGZ~1`Veuf!+E`2Wc31CESJ!1FQ;(3CkDw6B)Q+sUiF6IiMZRN
zMcT{5zmcmW6t|b_$1n@rTE;M#_JO6T8S#@dI#${Ah{rAdK3ddUN>F!w5R|Q6ES6{$
zyw*1cTQvw5dKY<R2g3?Y(<7YAU1U>~YckcJFKmE|RZHU%o+=6pEkm$0=}pZV4h?Db
z#7;M6zN(YNl;Bv-)_#}ug5?g!V=emHnL_WzQ$Q0gZD=}2dUx%oyr1voAlO!Ft!>#g
z0gGV%H$r^%;U61V9wT%PnltA~=%Np(60RfHGyf^^n55$y;ZKLT8Zb%Ndh3!!Q6lM*
zeJ8O6eO%3#C)i4&%0QV!AFroV#5~_3Uolt;$w&`SlAjCQM)rpU1HukY>mFr8fvsOq
z(g+qqJ`G0;Usl8Qf_;1E4&EY7`?*GBf*qbxWP%Y8H)l8UOc>LLjNk7E-BlZH=`bu9
z8?%$6XI!EagoQEMU}ZM0)I65YjdBlqQdjm%Bnsr)wFY<^PE$}JgS@TRya`1X#jN8;
z0-x*IN+iGi8-jw4C^RrO7QHThzt;DCLJlx=wOB*#kr(%;W4^5<_a?vbgnurx=!^=D
z^ac|LP;8%}{4$ryXyy&r3S2FUJo~_r_Ud*P>I-kzevQzsA4Y#6R)B>>q|GGc{w)k8
zJA)#sA~zugxVU8)FX;U7Sy9E($!P6Udb~F+@@d$Sl&p$kVxzc4$r}}A@suw*f7)oO
zje7M_s8afthzPpn$ZOPArk&`D=>4NazpVW9$}}Z+`G9SbHVsDIRsB*E_5E6{W3<j_
zF;hBbvWIWg-2KnV9kK{2MR5ut9kCr(!c~TAEa!`3C(XL@?jPF^)fr(S#V0HrX!yQc
z1LdA+!ahbCkJ${g4)WjdyV0a9&kuXp$jb859X&lE;4&&~mjCyJB+xb%+q{}%Q`l|*
z6Pr7L*Z?88k;UMHI(;7Z+{%0-d|$dnqh&V8B1y%uR9rOLe$qG(MXzru(uHw#1J=^t
zc<F__J;E#|ZZ?=GsE{p@C#EUrExn(%a;V8TiYSf+>H*%Y7vdjG-C)R-DVXuGAH2e+
zr#k4Pyxb#ND`IQ#!Rd908>J}lhSl?&IBc4G!a`0mZJ6WxPy-^}rZ@x8G+xCE{9<^o
zZf>HFGu0#1naIhqQ1X$FUbtg9%eI%V5Z!QUtQL$fGVc=Je9n91#w<Fjm&D*YQ1mhJ
zT8Fnpb(!=0MsNZUF;+3$LbsOaYh<+!v_e2e^FB`7nUMbi-yhI%Y5P%_oCQ?TU}d8&
zAOb?A*z?Ma$AjcH0Z<Qmh>M1$xVE|EGLp}2t)tfq9aY{5(I2v&A;g1Q1>!H2`0<c7
z$A8F<)<FPi>;16E<)UIgSpADs6GH=hXTIQoyt>gu6Vxi%JwrObjXA^Rz0MZ_jPluM
z7x$BkRtBZbd-Y<x>SXNoBK#a8&xMAhFA%(<n4!ulMU}fwnnNGG;Xkh1G5f3}j>8p>
zj2%_Oz1E!t=mPwEB?si$&aE%Wg{OuJDT&wT#t(>kR}VEj>!L7mgI!l!RKn_`5J2rq
zAW<anxtjdor(pL625^Rf$uJ7Qcg;yBgtFrl0y-_k2!_1i-=Zxy@TbTc$1X@4N#>!!
z;J7d_Z-C5%`R%Wl3s1K*x0-`Ikj+0bo4zV)K41by+YeUIW1(|x#DHGCHxyjGJO0f7
zU{fqe*Wjpb7LSyiwx9qfrf~NW340Dl_uW#Cl)ZApFPe&~KI*Q~RGOvj<CEQa#0tlD
zrfz@tWi%VW9<lRTJrD7@j^X-+Zvp&pXVG}lY$G^_R7|3a{5DEPNDv(K>cUf?_+OG{
z{SD3wma1h}wyHXy0^~-4VNxHPc#M9Y9Us7-t_X%&nj;%cpNUdnwqqgEYz!j%r>x*>
z$AMUE-}qkbv7M!NUfVq0i(b?E9F)<4yn-=BJEZV_U#_xBXag~!B&~{yuD=AAlN0v+
z6Qv6gw*JzW4`K6JRLCk?;i)$1X0o09B~qy;tp^fnjBZMO(2U=Uyp^7h&dnVu5iEFc
zD%U0ApXC`;G^KxYs%Lr>u>Kk<$2u52-LMtiF0#yTm6P0&_;H$5V!hO`VyoRPr~c>6
zbLnrUMw?7GxY~M?VG-Z8(4cAL&l+xSf7u5wgZAcBi5Qjm{t$x{4eTF5XoPFr%Kvz}
zAa1POV0&-bjX=!P^=RJgt$kT@VbmU4<#k`Nj<8pJb9ra@NS|HiW98qm9rA`lpU?2t
zo;Db~L|uOD_f!A;D2G{_@Q*EL{zKTFR@(>+zy({EqqLO)0ZqS?D<Ys>Z9PqNH(I{`
zHo~kMT4pj4VcTuCR%gSi1++Ugh1e7oluh)DtXjz-KFZvis3uEw%+tY7qhd5iKbC4`
zaDOi{J#A%uT?vc&<oPJvG1^cgvNMI=Qqy@4ovYO|;643$r*^;4j^VH{p8vUN=H2dP
zg(y+Yu?E(Uebx{1%|ph;DxpCawsw^N6Eie_1N~w*K)Ri6><D7>KA=2Z6_$Mas`Z!}
zCx|rU1^(_u#Fv1LDlLrylo7YM5eANzs%r`_P-eEh7%d=<4a-5w6{8FQGSPZH=@Q4@
z4d8_1vlKE)%?6=r*rzHD)LQfUf->&X_fNpS&sr*B#UP9@e7AZW=Mse5RgXmAkX@-Y
zp=<6@kV#Kq=CT)0T~}4aPtZ@g9FNRNY|1<m(e3^?{TF>knTC(@Efwx`Ma|p>OYd$L
z)z%e%7j2g52vu6#rN8>VIPAGKq9QkkeVO>ZHdc^83vhAh%N+1_X}zh+7GosjNR5FE
z{eNfl7e_ks?WL$MTJHvlhsXd`TiVJ|^!l4@(x9fl@MO#}XKvM@vdb7fpT*$LMJRCb
zo?&+cS~j2nI6oInONT)7F($>{8;~}W<%vxTUqBU)6n5AhA)wey@~B2`wCR#3P{AWV
zTX10}#&GkT6-{|+>ZtZ?W%B=MB?N0uh9s`z>-1qj8JBi%?!60^tR?K@ZKTG&K#D3R
zsnWEvPc)hl&_yCJ>}sC385C2G(=qHMmDI^j{JMQ$zr)Opr1*z|-vT|?k((2QRc|SD
z2Cl*@%|Q1vOT~JP@G@~PbY;}R$mq50<MBw|5EZ`T4mK;#AY%hyHWB^rF0>|!`zE$F
z<ZEzQ8GO%yVaoJ~#vcu$&g=WNezsUiEIc0`(Qe;|N8;OTgAP~RGNxl9Qa<z7ePo|i
zv5*W?WN2lf&yg(%_Fmuo8`ped&Mjjg`&-j8GPhS7uk&R4l6o+xrkH`45ZIcG*Wxoq
zQ^@#B8L|y8b)3L4J%nIpjAq*`d78@JHXhOy?8$1mt2vs-)HKDyM=ZM9NmYvN`FDve
zf^HTV)Q|ijd@1#5?|H5<rr)}W2m{YHUcIB<`bseMNyTyaZk(k?*=6nM*1hv!bhl%b
z`!)YOvVyc$%fK&B<zqmXdA0!7x1SenaqOwm5Z8=h9WP;w5B7|)37Am{4ST!xPw5s=
z_3GOWRuKMKZuQ<6yqgk*SH%m-%hb~g3fzXPen+Ena2ti#c`-VFq;zWhgslvgzPpP+
zUcYTI2C%Jfxi$7|bwbqd;$rJ;AbsL|``q#IoV*h;Y(jgU+g7Q7P}~xo5nB^@0-rAv
zBT+xyI6ulcQ`mlXAOgu)`@gcV)@fpWC?CV!K-_C}X8kEvvYty^Y@u=_Rh*-Ccvab$
zeZRMo$RrDEZd*sF@@!YGxmspNA~0K`dZ4*$fA?!hh>QG(T6c0YCf36j4P}&K66=PK
zLA0cs0xuC$TrIfGPKuY@h3S@5r!{K!gQW5W+WXyR53r*fO&C*o*Xj7mJa#Dryfk?=
zk}OW8J^z2g^MCW29`19vM?u%lVE>4-&a7u4*1F}m;IW)k(po9hPTxClg=LqO3=j&%
zG7!r~(w0E+u<VBm$&aS+eZ4uZ(5#I}gL^#kr{IqG_|~9wG&w1tu!Y7I2>-;<VNZ`0
zKBkZT+6}!@E15@d=l}C^moG5S8R_Ky<3kW`t8KV9bqmC`b|g}nGSSNRhWQY+g1V`y
zkqO@@uDbl)Fr-^r&f6T2$bZt=6^Ssj%(lvvB$!xjm@FWcOZc+%ID4`romSg9R1_mD
zYW9A))z<e&(Bwxdo*eOoRWCk+8U91t-$-U2;UBdh)X>8%<MR_S3r)Y}0{1Ye6@>#P
z5eA=;URJ+$Moz#CHbuQ3V}Y~X!-NLyJrA@ef4QzT=usPyET*Wc9l>VFTLEj6kSJgw
z?aZkbf}lRn*hLfL_V+)x0$%qx&!5Y_59ksXz^bt70|PA>IFlmATnSI-Y*CSeipjKu
zTp(<Bqpta+4l1^dz^fOAy@D`yAUNAd3>bykRfy#>lm_mIH3RF3ifM<XT9_SZ`w#R=
z=Nut;=2DT%3;OtS0fNplr-q-0e+6?64_dBO&2x`olkyNx1>DT1gbkt|BI-Xlk1RY0
z$7KVv3!W1^FyH<&(IunNs^X|8%8j?F)@O!5sk)(f%YOhR5=aWUGzgZD1Lv;i4;pq`
zH^5$v=rgMx>blA8jTfN@&gYcN&Y&BM?-r_9Ek>@Pt(Jq-+RR(Ji%aPnb%8Y?37xoP
zcrI~zYR5~BFc!WOZ46f`Cg&jI82b371~ZxnddK<N&?(+Up<<@^$S)JR--mGKA!H@o
zmv6VnpFNhHfy3T+#4A%$l}r<W_Pz(A#TAvPW!jm)tE?LVEVLwVdJthQcC>CGc2IRc
z#PhjGo12+pzNK!q9>0?fU(C_p@1d(;9A%|D!o1{`fmds5unv5$iPg0Kf$uX-jV!gE
zb$~i`4TRE{=rFSzYSV%Q$T8@FF<lT?IpR!_tS#0~ctH;(t!m^9#4?^I@_bp`8GtNh
zN(qv9kN11jU3{MBAMR08WdkbQ*Ft5A4|&K<9PmxYdk?%@U;OAl=61_5Huw#b-sy$u
z!adCIVsl^YgO8o*%=lnOd2(vj29#m4E`UlH!8FxI77c-`2w!e4Q|9!EPEi9l<vsME
zM7Sg0uK2Wy-JI4@T)OW2Cp8n&!_#~3J7`oxO4#2XxkI=WS!__DMCcV=s{tptyP7gT
z8G$XG;NmQD5IDoc_?+<!XI9dHdm{aRGL%_Kpx2t@q<cpCSfIXQ1x^v|+1wo5Kk+r1
zhG2gd<9N+NMIW?n)9d*im`VGMW)K9iNI_kIgteYS;WQsN-*dl)qhn9>Ik~CplV+ZZ
z44*5uiiOXv`)Sn*LrF0W);_H_#7cSU9yX?RcZABiEWC4|ZQULGrJnN}B=0TzbVR|?
zIJIYywS#%5@~fHXUP1-J7P;93?QcO++mENxi<a?^9vV-A<YR-$f)O$Nh{8p!@G*aW
zf(Ps#8`7z?hYTm=C4;ygy*-#9;Md;;OobEa{_9jQ?WU0dT4*4@U*rlbq^5_`&ewYh
zeF{w#dRmbufM~)a1562$(dDrRpwMdyk4pwlp;E|!*RY5x@B3^tm+6T_U-NoJ2%Z1I
zn{8*0-G<>s@1(TUqXmUyEU|*&kzQGIrt|}Sr&%@Ij|!wUHpdMkvvOd~k(zHmFU%4j
zYln{(nXA(qil>TdCw*iJdqi*C%9k@fs%Cf}C;N+<#S(Vs+{UIewmv$e49B!T#S+xU
zn0cq^>?_;UmNhhv7-gVr#&=e?4TmPbi0HG`?C-YBVrWxoZ@U54-LQhLfu5714kW%|
zm)YKWU|ffAz^~x@$ZLOoZfDm*-%}GOM1mGjg)H?ia(_tz)k}iL**J3iq$qn#3_iom
zz7M@h#8I`}_q1T&g_e<I4^%u^pjH?6TI9m{hs*a}UppCl<?2x^U1qcV0^n{MzV^=^
zk@e%i1WqG}25<~51ScUaS@N$*hnH6H-OnO*OM^vL&`6h`yDVA{AA@KjaDsRiVnk;8
zxeGs-Rxi9xEvxJNmqPyAu@VVDy&&+Nr9+TtT1WN9U<nVUuGiyIn0c(jZF48;&Tkr%
z*4OD8*hu1r(o{f&0aNW2QUGqh2gkJKL(kBzOHC`@r_O}5CkJZ!BsxWQ+=#Qq*k5VR
z4JzU6OETu7THiqgsp%rMgg5PfyVDrICKJoC$CAd8iJFLN@)pYWb8^Bo;y?E-uhzBO
zn-4GA=+tA<;tYOUwKvB+?(>Sy321)ST45Ru>?HkRH6J|RbvPRZvpxplnAsOah2La9
zI>(&5@bw}a@iO4<*#-_FFeOt0%VP*X{3~8qvyyE^0h3hkPXaB8$x0T@F1DdmKZN?u
zHJ*ut?2rom^s#d1FgddSKbpQWstvB`7D{k;cXuuBZbb@|;#S<<gG<p;ptw_@xNC8D
zC{BRjuEiyA)93x}TKSRu%Q<I!@0mgT9NzW2z!6p%dO+wqY0xpF0L(!7idHPh(!{bT
z8VhcSpFpEQ#pS1eMZ|bDp#d`&c^F%>QV5EgQ^UrZW8PG*0JIJ34F5_*X-yc)hHgar
zaOY?Zc?ykvv48aY39{<o_qT7#$-q5|`vd2k%4?Fhw37R(GxV;3y!BVL1xNc<7z$-J
zc%_LVi<FsFMMVqGkb5O^eb=%OWwFG&+O~RGDe`Z4mLegut14`=f6&UVuiO-vp)f*q
zRptNEo_`e0#*u3q0Q!ae{%(fJ3rrd%g#R4)2pxVUlIVJ|LG0IwWOleSTV(Na0})A|
z-VOQEFw$Q~g_Nc6?_KYt=-x3&l@%I0^x6n`R+E~?rgNApr+nt65%w^bu)R-dBwKIn
zWN%PZ`Sv<?;iBd$M?bF6$Yt^Ei@zhDVG0{7zTxu8$`7r;P_q_>u|XP?D*Co`dOeej
z=7$`uK?v&!;*^DY*;m8-(@)lQ>r9(w7!6<zq3UM!6XQ?a)!7C6uAD8SdD~QP#&LGk
z=BQGi<DqG~)JzNY>9fas;h21-hBRyIZ_oiqRFz-<^LjLYFYh_Q^0LSKxu3UG0(M9#
zH_tn@PLi%J4^b2p(jM+wz`X%L3wvl-2hHcgCuRPnv9+Ey|H=~Z+9Y!MYET|iMoD<e
zndkv!q4!(_oeEO$F;nV0W+qE{X|DB`-`MYCwu7AteT(n#%NPO``tKB58j6&^bX(~#
zpLcw#ro%NP8qao1UFEu09Oc%oUDScuPl6=qNAH_WH0zdExKA0I&*k)kUX$Lk?d=SV
zqeR|(7i9I;Pl4<4XCE46pa{WD%fc8QKrFmK)BpvfLU^E;Gg25EP2$Oxm7w@1a+wJl
z(uLMC2)J%{Qh6jGT;6j?gn@yNo`>k&qHb;hZV~?XQz-AXVT?PxBWnWoaM2XDO+iHe
zrNQVje!U|2E-F}>1-15Aqo%D?cvSU>L%#xgvL}CA#G*xA^E6C@>T2AcBPXE^Z=Y`&
zya{X&F>vbp{k`$eK@RpEXm@os8{&CC)fb(Ic*dSn1G7ng(4!tN%B(b}yvC-nd$^W3
z%y!jL>Td`&Qg~%-r4+^Tp?Gz=Ur7;a!jCz042LWMAri)*Jx`7k+_k%qa{f)i$K@rG
z=Kzz4A`wPMLd{mQwHNG=Gkm>D>DF)Fvbaj*G)R5zUy23*lztJu4>3rwqZT&_$4f<r
z@V`wPy<jWu{a0HP3WWmRM@g(YuLGy^_^NqHCb7=RrG42?^cv-7IvfnE2vzg%FhEV{
zJ-U<4skxHBuz*2OI5@Z6&X6&)TXMJMzVHwhNjqE!R-*OPY+59^hR<&%{bO*q`zy!m
zFri7m9v&-Ye+8q4@w56TeF<17_dvq~1s;82+qV>^j4CurOIw_SwGZSh*1y#Y0KZO&
z2ue`q7s-}NOAGoVPY4YV9L&7ZYrnMu-v?sgqv^L)A6B}O$K>{-BG?#6lqrVw5yqb!
zJ@WQAcb^Nl2bTy1%p0lTGl^QaEz$UGw8rE@+45(Y6TT=jbBvcH<@joOp+wtAM~~w^
zjV=2;`^@pi5`ZUkOd0zb%8N3W7y=>+K0{U#4I6?}=FEOA_k6HZw=PV{98}e*kz%O%
zl>A#;k9YbhP5NT@&!!)AsHGu9M4eh4nNin^Cm1lf?KXythQ9$;X`4jiu>^^;5@jaC
zx(AntJB!vpmOuH2zg@*TeGm%oYJ}{rDsKZbzhSU~Z&ThC9?cB}qD4_lue$^<hVTUh
zMV90@`SrTj#9K`|s$W|N|AnpDv#3Fy{k_tKp<XcJyu=S9n--i4V+;vo)6Wj2C)z(%
z+F_YJg>pLJe*MV1YLpjDeD1{W?fdGm<)20sdBV;GpC8ZqYph5~Qi?e=GBSY!R!8j6
z01c*_3^nk_0;oRkEY-#J6%f1e`~89(g=Am9?+xCw|3!~7;di-==ri_tyb$nfuy?fY
z`HboXJ&Q9UOuAOMtzgK-ee%z<^=ppOgS(Av9wsKkBW6FTnwxJ3KuoGs2dgv@_6pKK
z8kGez*;c05kD8yG&GnPA1^EVP;<o+hvOjQE;pm?*suJ)TPL;4V^cfpwhp>#3UGJX4
zNB4>TR93NJ673KiHej^8pZ%?By#)x%hX8{}CQ1CSRy;yS9WZLH5`MFws86etMgXie
z!_7EtAjn$DeZGP<YtC%SAANwn7<s)iPp5w?O+k*a2gxdjTn^n}*3HMkHpj%Z+?vb7
zJuTS{H;kpLUh$zKYzp<`xj#w!DhiTG@*X;lc`%33(_II?%MxXj&KH;@2+lPjA1UOE
zT+f7l;$Qf@vz?#1%{(StCT+e*j*cI0W@f4B{@Alu{J6fKDW~}Q3DrwaQ#?h2sk2({
z+L{W+e`nwNevoFsVb$0~Q`xed=j#7+0n8}GobHUmr!!t6CU=HIYPd;YmphCes#-W{
zc%XilwqtwBIxXFVKbBAxLF#(Yy7peUke=+iqVUN(YYADt70UFJVdu7KXPFNwz1n)a
z+#qy$YufKET8L-Oo;`_oie3`G$M=~HyPNd)o}u%+^g|T<eNCd+5(I^oPvTEh8O0__
z&>U;ty$~Mf4X?~`njNy&UQD`FNBI!1sAEm%Mb6A&8VFoqf@SB#z!!O@f*Xi(ljivg
zmo6?JC6Fpa`>sauH=d7&ABrSi$Oup)Va*D@SHvPuZM;dHJm2~$v_cldGZXe*-YBq|
z-gsm>{o|KF`9XwXu)}EXn4MSlllHgHaLI|FmW>W5cP^ruHV)%liZfFVyJ9;L4ArT)
zJ1*a+Rwx^T%MSwcp=oJ(_~rYSpGfQ6sqDSq!`f08GT7crt!9kP4^=(WGr}P1!aiWj
z-lTO=oQ7;iuD><?uYzFfGeU|JFv&P$!}{v%A^?MNIE@M>Rxg+;dJ~aES64<9=n<@t
z_lnIy`C@xglKR*6#r=&80o?-Qxdn{Sr>@_k4!pkoVS_nMDH?_W3hJU*YX|#GVPb$K
z)dOeR9e*MmqC35>ZuuNnU`^TN1Sb8x&PU<NPB5o6VYhKBUt|S4I1BOSx&u)*F7Wjw
zSIF?i5Bqn5X3*~SgKn&Lgv*0OC}tPVmcSQ;h>wN@TQGcPtsA}yhZRyg8kgp?h?Ah8
zmcK*yBuiI_-a9r*>@qL`7ODlx4&1^(-1HWRF}%+!^$4n@%Up!U{*BgH*ue!gO2zcL
zr%|Zb#SD&T>m5Gc{y}(N!18M+229seo3~^}!ZKEXhNz-C)oEgaD{)iMDWaVNva)%{
z*JvuC^AHp+H2K!-rl5^8bj)wc0&JtO^n02;ua{W8m1`^K_W{MTEO>^!a{8R^dS5r+
zwUzzkW=Hzi8Nn=Bt+%uc;>)%$D<*7h@OD^nTVjL>tce<2p`WrolR)aeTU}m6$Irb*
zJ`PC81Kt!ZIzHz{T}j-ug<elOz`?Zo`-CQPLI+K~Z5-B$>qpbXby7@G0At2|pEZ@i
zKG)arOBDwG&kv@?aru5m2*BX5joRi{09AUVkH_Mx$gP2bH_C8MHs>>t(t6s&yw_#&
zxovub^>A<Puc~-p$c2Po&@Tw2A!yH}rznwf`x*S|)VUt?kR>R%<*J|C>GSm>sC47?
z(1udsJ~OXwu|R-qGp8o-msie?zxQVcxZsOtLEoZR;^QgE(#n2U(xT7f4KqRPvHjre
zMwaCBwWj&Ate`|-$f#V?^wyo(Gp<Axk6==8dqNCCjHG7U@(8#Cx)!W0vHK<-^ze#!
zJAIMHIemGB30$_Dm3M})JfU+ohd~6ejG818O8mwjP@^86B(Bo19|jNN($Y+Na3gg&
zpyMILaqd53eG1OM6eJ4^g-K@WiH)}KnyZ#+^}okcP|)>xN-<k3()bz<PY5uZV+x;S
zbrga^ivcci>Xc-|xI7l>(OcPA;p<_I#a_7K4A4f_7k*fQ%y4LHMT32DC6$4LCPh`g
z<FlH7mYUyoQ_kx2nXoycPF%|jM+uy~rAqysGulp#=@=~(S2ev|anRGb`P!J1TE_<Z
z6K`mi!rtU0*T#hF2h%VT$e~St@WY7Xydj~UKMKEzrW)71yXd9u4}(chj(8!8oGnXM
z^;tzbr9qRCbsqug)p85!rm%TiQ7-{`_X*$QRu%5=dzJ2J#=L-4hoq~3j~h78P9p7%
zwm})?uEy#=mYe>HGL;;p@6mW?P2;kIbdT0cVIvji^oYMd<I~>{smT#YI=)e01iWAd
zLDH^*AYpGst^%<cziBhE6aZ3ESjNcznuDZIm|*<<wXpR)(2mx<T~I=6cgnJ8AL<cg
z<-Sm#3jWJA_gn@Eeu~e2Ivsd!Azv(6E}Y<A@**bFj7n+`O()+NoLMa)3MN|TEg7L5
zWR}@?*>5(%BTb=SC|gy~(?*sXN8-q~9NiZD9^JXYVk@`y2e#)oG{+belP_TRU)x%=
z&jF#?(mH@x+{aRXM6WCvFEqFHf6MrO9m68tf*AxZFFMWqqq9Exkk*jP`;gWB#M&w-
zVQ{Q02T<i?yo6W{|77U=*iKQibUG#2<&O&F{5(coqpO<6d;DHOh3G6kKV`|rXzth=
z?6M|$<Sa-MDjLBQS5&8?N2M<|sLXZRf8r}SS<(F$udzE=Vd2-e=o|ez2r$@m8PN`o
zhDj9oggm5s^5I*h7!ANswS;O-z^Q0VaC&>%KMFQ_Ro!24rd0=*d+z`&HUJTk`Tdrh
zXYQvNw~7@B_<#))-*7Pb>$?fPhXtE8v;)rVzZ<U*eZE0<0(ZwUeUD16-a@KigNElQ
zF*L8pdeF2a4w{yj`Ks2*5o(g-Y07y7bC69%K4;@8dRmay7DX0sV>IlooROXxk*tSK
zb44FVpntG*(VF@qqIU0w-YX}L+96b>*i|MvHdslA9?JgftH9V3ga=lvI)uHRxuNeQ
z&imxk;YDR%dHXu&(#6B+bweDq(cJQ`-iaoo_|ASVjm<1bkb)Yp<qv-45Qo$XMQmNG
z=Sd3eMHnO>U{XL?vw2f4K3R;Oqr1O_KHQn}54$8XqPQ82#ihhvqZ%3+4TeVlXcO*~
zY_w4<RS2KmB*HGK0woeq_sKyX7-1itgDx;(6B#K_ZeG$F3`+6op%n?Vp_V%D86X69
z^9cF^+s~ui_Xi~4=dg?U^Me(fgFh7j+bc`xB~d`d5m2B5d>94~Zp=E0<^?#;$@%V4
z;V{NP6HvMJd}uAgrD$ePC;%Q>auz5FwMB%{&dya{;eg^^SPG|HhIhr=n*`)Y7)X}e
z2~LJ}UQdzc?Rc;4rEQ~by%FpC3u@}_Lu{32$^gI-+tVLya{MILxRtgmbAK`3Dn+dn
zRDnXd*_D%&kT@RRBnrO<vcVfh!xUtp_GHQwq3cOt%VRW7Hci?G`Np#5bvaO$C#P&v
z{@z(PWY0TIm6+NA?k*78P9UJbSf~WuQXs$%;>a&T=$&9iVE!*h```JDqA$ZFUf>?0
z!~iWoxNlJ@=TN{nl*)lfuHavnExT-?F>>E=F*fGIoe6^*6j2L1WALUWbrI=^uf0u~
z|Gc8f(0W$trKKtPq*4&Tc88voA!zn^LoHXJ*tXdhM}qyPP4Tm^m5tf*4`Irf0Yj<K
z*q~@-f{ob)EwmrOy4&7XOOw3a--V;X)t4m4>C{`v7Ucao-%ab$vm`4;h(+u@>6p$J
zE{d%U>kWsF&!M#q^IzEn=MtMf&`G1B{>Q{_|F2bups)c9H%Up|daqmX0{K9Aupmk3
zz6l+C<q`A!<QtU(t?a+LS9ARQl{I~(;vZX=Sat`{5zgnITZI0CN7CC^ge%V3>6++x
zgSV3r6u)^Ax6$ro_rK``X0(^`&e|gPM%1z48m81(r<IFWAyvK~FEX4^ArsVY0Ct6A
zj>S}0N*MX9PhOWRYYeR3qfAM-0j(S3_btXL7R+R()KzvhUJ7tK74+|=Wn<}E-X_w(
z5sb5JUWp%~Qd?)CFoD<4qauxP0tVS_7JPu2*zPgZT2`cECi^|%vQfNRAFe-tD0_v(
zryl8qC|XsZyd#9dCAV9&0q!p__o1u-ToOZX-oBWVE1D+kc)P-MNFXG+@5ZWF&6sne
zmc^*t0|eRMXpgzbFMeN<O|0xS?-*;+bk!EBx-4^M460jspuR>^)X}q`7?-U`S&W*q
z00^6A8UK{gtJ!@kyd2tCRAsGKO^J>0zbN=?LuTcCNb@~9wK(FmYlOu``6Q3{V)5#N
zg1M!-QkT5toYb@k`#sCFy`>>$hC{#jxRJq!JNnFs+E^Dx)1p%oC?f3sE9R4o0*~g9
zY%<aq6e7g@Cy+BN=WI}R>d?zvcfxCD5S-n^PxRE|1<Afp)OVP0_}eDk5QT@d#5XkW
zP*xa8Km_F^#?^&*JXK8z0}n0qWwCwbvBJ;#J=h6f83)f!634$qvwuq&gyJBjE+gb8
zUS!BkDa)Jf>9)$yg87~%!fH#-HVS%70c5<Tg<R1xG?r&p){K~VJjK>yrIDsA&J7l(
z;m<tvFX^y2ozyE4&cSxUPkN~NmB6K@gP`PDKGo-iZukB`ql%LA_A&OxXh-cFi%G}7
z8JvN}g?dPD68_E<Y@?nz-avsg{f$@S?j=%^c!Y2SNj89FFsY*Jth{C+oxyj@D4}Lr
zE4=T+ncuA32L@E*EJSg0Yc16$!uhs{{pmi~5bJHwX*DX^QOhFJN#OvZ5s>)&WQs^T
zIh{?)S$HopB+BdEpx>OWI`5}AH4b(41TNZqulN1B{4sFDBql#+kC+R{Hf_#Rn+bX%
z^>g+2dMl&#<0+To7J=QGO^x30M{WtnoM(WcT2WkaI6%Ae4=?M3&iDUypSjeuMG|-F
zn2ir%CfM|H?I0_uk@s=!AlwG7cM;xlbDpKHcuVXelNvr>O&z{-Otv3yAUs8E8dyOO
z&|M2QHNLko`Enb$CLE~1@%8o8ce;&Ki{tnDyn(=?yej3REcLn~I*kS=j0aAxx|l*r
zO=pTTNP)hcz4uJpUSy-h+90q!pYPeSm{s|?j1Jlf5*B#Ts%b6a*j?)E@9u^ZbuLm;
z>4;Vohf}@NVe|zSCV{=esqeFtC}WOUI`viqVn0{g%4&Jh9JfY=5YjZXJ=MdogFkU$
z;p?&|GDc-bH|lyjti@KT3TAQ}C6$*8k7@zip~yqTPbWH5@+-{z)oR~x4#eIoF(NBb
zvjX`3IBFwAcL8`AzWNBez9Z?idE#T-s2ft4W6-s;|Aj)T7c2l*2XMyX-KsTR5)Iu5
z(?nxtG;rF{Q`2c#jY4A$UG(PM`Ytb}k;b>k@Uz!V7Z;H7zEBiP8LQ3XtnG~v{BZ#=
zh_)vo<1@>*eOBS9Nx>arS10v!_0#QHEJO=m_PGm;p?r~yo0t>6X+to9r49K}-1waS
z?ek)jk>&9>0nW;uqC5!7{zU3TJ<q;yXCC!-Gyz&a8X_t?QRL|4>M@;hz!e<>!zvX{
zEgM{kt&C02-6wQ|EObRi2=#<s5XEj~ui=wOFqewm<7+ToRDeZ#Ar=hK_DJq!eogN%
zROi(fO2|Ot&2>4(iX>JqV|2NM4wgXLt2s0p&O52SD9yt<{z(zY2xyZIwn0JnjPBCI
z;Xabd_X9<=)ZoGs>UrKktJ@m1O!*-#Y$+wQI+ap-wsHZMaN}aVa>K~R{-F&AJMf6g
z)^{D!3DL;im(o=Y;OCYAMnlN~9FZ%zK-ol1Amu_cp<G$OcP($2a$0?W!*_emtY43M
zY#Z)hY_iS>6o6mu_`hP0uI;qZG>tx$#M`%c%{VpAO!%B}kOP<Ypo}Q!jiCN_Bk^>m
zj*jo_?XNUh-If||d4#7B?4n*d^53J{k@s_{x)Mom*G%L_PR)8FNF(K9_i|YvDq&sK
zjdJZoo?M{EvTx^r<v@4S<`_eahmk!~7dMn$=((-^_^=Nx##LwEaAg5|_?8p0Kcl&*
zYc~7RRtFff6$uS*emp*{ns6|?MJz4%78<q&d7qYzaFVppGp%VzoC8AT%Va0RB)`Xv
z8kIYpwlT8=OWt5pvJ`#Q7V8(u&SU^;Ei`hnak+&}%A))V4R&EE&u@EZe19)-cd2N#
zbY8tVbLB5z9!4B-47SiFUI^Wk8~>;k#P#t5l(^-on3(M%8%y>5ze_+KelsU3!71}3
zSZoSHs86eKLV=z-JhJwY!4?VN`h`4_Sb)wI8e9@9(C|`^Uc_lrn&-Zog2jHI@RTQv
z2Y>Q-9{<X+dCQw*y#!`t0bzNK-GHR7)TXKWPIzOSySq7y0?#g-O#<sqo}>$KVUDZv
zG#0zpV!oE_Iu&(`zPqIwzQa^mrry86bnejJI;*LjG&NyrNNk1RuX~T3YCS3BxZZzG
z1ihJ2hm-t<#P`$@3Lcc#pFIos#4AyFUq=yew|JQHb$quTyKpWi^ebb06-Uvos%7J(
zL;mR5Rc(Zz&}d3z^?5m}hfCE`@q|Qp>6N+Iv+B5n3#}hO{C2Qi7yi#C#!+HWrlIjx
z%MPOF!WsG!1s$(OH^N#XqZjreEUlEUZIP~6b)Sh!N70-rkn>4)IVR#OYWxxZphtjX
zI1s~Xz6xqOAVeNWI~$ltL61=`q(NUO{)#%*K<Re*3?Q-uap*XFW4hGneoKy!>gBH4
z0Dj)p7+OxGyzYHPa@(GrE!2ZKj2y6JiMS759Wm{-uVf`+z3}5_!BA+3?vX}~G>eS*
z_g>nu4Jaq8Zy0vnTAnIIk!DZJ-<^{prGhCJiLKVCR(`c3qxH*1yWY?;32Jb9VL`NE
zrH1|VZ6JjX&u{qAf|B_DOfOS|wGFelY-P=qjHV-A4-7Hd0f7S1n|+kCuyuv8Xw;D>
zpa05*xs2;`FXiPItuVIc=YPN-h(#@Txl7~ZyF4w8C7)lVAWTxYB-5^j?7Egsc`deL
zx?OG*rDtXluXDJ{#zIsVq{H08-Fy9`E<4v+Y3UVc(fj{*icTcxDH7LY51!s&+uYla
ze?Z>>24=N*r|QmpVRG3M>7SFaK*WYBrxn>({Lc?>9K9-=-V?)L*;7FBGe-xji1Q^J
zSJ{=leC#2Cg(JY0^Za!BDcEd1g+4#CUbz?5yOa@pW?Q*G4jrJqM7Jc8*>|IbsHw6J
zk>cf!rLpMc_`+rDua!0g$26n6ILl>fq+ypp4$e#jb4M>yT=D(zlC1}SH3D-jH(AsY
zJ3O$$O-%vB-f<1G_OQLo)`&!Fro9e`H1lF+`zKhU`TUhxZ)8)8-sMin{ak2t0ArAl
zwkNL_xwMNcY9z4;8G%06MC+_K3!Ea3L5e_w#3>UK<8D*XUFlMZn^l;+mhpgGkcNUr
z3KnOpqKSlp9p+Mq$|W)*&H#RrV<HO2Hascv_^*z@PpZe|jeal8+S*ce5Y6q@L~O#8
z_jgYg99u==mTI2TiHCQ6Dul8zjta8$+@R`KxEE=L`-eDOKeDzr!OUb__!Tm50p9*N
zwa;bk2C@V&sO;OD|2c;L%pfu4NTmD85_OAlbvr$DE3-Rv*?3M7FIo)Me}7+UzWSeJ
z4Q#vLrP9@2;wG5Rdf%naM4AG^T(l!`vd>^aX0wvS(x}}`)GVzdZa&Y?=twORW_ocw
zR5aDmxS9{-b4m4524=mXXI~T=iTE;ynE(z?*=MfOc$Uq~Ylz2=h@fwOHO~*Has0~Y
zeNR)D?^9+l%N@0R{EHxFM8XLYFJgl$d(i}{5h*y#4A4=)Ds1|Af3|MKr2x^(I%8ZD
zE-s>Ek!C|Ep>QX6&OKC!PxFZ7P8j`M&v@@#eu<&dz*0ZZYZ?m{LR~oJcUtJ1e3pg*
z$a*hw!eYHUXMJ{)9_<H*ZkQbUVaVPKG)3nc9cSV>sl1$NIg)nzcb=cx*IbMv?}3{R
z$_@PZ<?cjXT7DjW^=N;4T*8HXN8-Hpo$Clp(9qj52n$e=bJjueRIjg6JA9hM54drN
zdHn=fWOhFF=kJWLQ^+}qcAo^aNUYVcoLUoWaPkxF-OoCd#xkdzKjya5Oga(M6di(l
z@#OEb17NH=KV?ty{59d;Q5ozodE~~Ytw(z4M2(aXBAe|~*Zso%`i|Hth+D*R8<*0s
zZy4Mi{z#1LY_ifv2^mDs7Vboef{(X=|L5t5B^3L*uCriz%%RqVWrwpxZL@~+cSP8b
z)xw7rITt*ri5H26+8Evh0NFAX(z`O6x`^k=Ce~=YX(vKzYZDDVjmUlxDlDXxPZyWB
zxU{V!voOlG-QD}O-)L$l)<?z7K5+C#>V`}+Zc)~(zatm%gIs;OO}+ohF^}pH3c@4s
zXG&!I_E4d*0jq;T-hQil&=Yg9`gb+?i^!*&qMqirY(ghg*qIZAb6+SG(rX2F;MDA8
z>91hYpi{KnmSTd<R@7W1*Ur#H%Gb9?Ldt$jQE#kCKkoqG=?Z<o{*J<>I`9ll{Ql*=
zAcl$kFnmH(Ki7nhG|to+c$<#~YIBCX4G^z5&&9*u>(#U~cl>8(b`X^Q$+r(qGDr9}
z*_GX8>1l8c`fEnUm_yX*Bl)Hi3;x30&gzyrV<B`MS!RN0+dAY#_L$~|MqYN#m2PDs
z`4e5XF?B6?tq~JX9|P84=qJY4U){xcD6h>5S_&!LutJ&DG?{&J<X6q>kaGS&guRC{
zI>$WSxqC~eAh&j`dtP5Kjz`gFMrhxVYeuKq!}4Df)L{c?9QzS!ek7nidV)x^#`dA+
zbxP@FWEc|~l1mD}Z2yrae}ha*geG=5*Yy$bnEexLE(_G&5YLmh2;VXU$L+7>S<v%~
z?}95uL$pK`E|cAzH`Ci-v-lc+CLm8r$I|idp~IXGc+8HF+<zrSYq+5L7u8#Q4H6IB
zd<!@Jf|^P=Z+slr#eU4`O-qtO-F#UIrMQ29*RcVenV8^V!a#1Qk<DIF8`KYfvMMQe
zBsoclv&abc$z7x=hJS-vU}Rgl`XXqY(_u#qtN7i;JX^3giNIKYs8z)_XwwA083Ia7
z7uRWl*iOCtE&4j36*)s&3nR%F7$+RM5Zm*YXQ~A@t81w8t0NylX-vx~Hv8Rsor}Qx
zbY1T+5rc)xIy9&--!NheUa&fpGPt*PzcRmgOFScq-<{HUu)hY>a~bs4ykM$t2>{>7
zU&ezV{9dbU+2thSVO(gu`+~Jj5Q#GKM^5TvOzm~38@(gO0Bkt0Z&i`zNg6G?P?;u0
zwlh%A^cq4t8tqR9paW?3bIpb@>~z=PMVj?}JAla_d7Hf+V0}-C?d3CdgF^;@WtW?|
zqV(ut<<6lYiN>rl2_TgP&t<T+DjI<4mCCko6*QbPMhH~D{KWs-fZLG`GoFy>woi|I
zRkM{?S(xB-gO;}-`GbIE7<hW6lc2(*Cb<hH)e%BeS@9G2t1Ne>7^f|}<@##`Xaj;M
zK!_pbG+Czu>tJnmekNKT-K7L?v@~~iR+Q~|YFKDE!;7J+PV$fk+|mp<9EHOoF0DIK
zf_r-e`@o!#5&*9y3`4a8d3%fde#t=XLeNNP;Pn!0{eKSZ84uYs3e7_iQ7WI_vyo0B
zIs!W&*DAd(?4QZ>*;Y@+`d~tpBC;XcaacORG_Ev*4->AXnL;#{_xlxHP&ojcnh_b~
zFIRK14h}ss+-AKb8`^6Bn3g26Z$6|?_u|_an2XCy9ieFB3rgs|0~{x;9~{%_-<&1A
z6$!`0)leE`Mc+kzd?uz`7=mLq51_n}P@XIe_<h4X=J0&q;XILAcac0qBDI;>9Ea|x
z5WjA;WoLEAviCqLclboq`I^8>HcNwq3LVtG`7G{%H7&}Y$6W97D}w~MKR4{MYbxW|
zpRW3!wsgEJBp7Lj(-isWsRfmQbN~PvD5lrR)WgJ>4G|QY7KfM`e&vxK?f4Nei}~)C
ztoByK%DETJZQ3(XM;=_Dj<oDG7gaV)X+V?SOgkN`qg%FJ{UPa9rV;4<!EI?28y(KK
z&~RXBHtA}KqHx0pxA(7;Sh>H1@x+$aI+LU1$m2dafF8^9B_h#dVY{4V{ai;x970pP
z%X578To)165>MK{kk%hN`Aa5!or<66N7rXeNe2>aZU3q9;fI!5RU~NmQ7*Rx$PMtp
zc<)}jj5Lh#-t}UOp?X7`Hv7xp-ha`S7kXo<^BghsiwF+X;S*V%y8IXGl1kGmF4a-u
z2t)^G89@2x9@NGx*iFr0cksv>R80|2We6K-8({G|Y2qaK!afXjm!zh9+9LrP&}PN-
zQc(yV{Vr=-`lkT{iM654!ZI6LAy37c0Fwr6JR_!@6>yEjS{RLnd=5mg<wx|RN={&R
zm5afAtYQ5}?-Y6t)S_2*t=~I3vOryDP=l{hM?6L(?v7KH;}?)+0lXIT9@&x<wvL7i
z_qofD5UPKkT8H*8ay4xQGtkN6?<}D{(q#C|$>S1TXycED@fB7qeaH0XpII%7_2VP_
z;hk_eC^vL>c3#9M9Aq-AFJtro$ve9eRrw-MNj&g<XuWe;#2P|b(HF3clNABAKR%V%
z)hQiJdSA$oYtdbp+TsoJ`#X~QNIao&<z}OOBJWUs*yR}nq1<b#GF@-sKl%ttotOT~
zZo*Xl<YnaS&D&yt75lK9VJIn~QPNGMA-nNYJ`F8?QyOm+?#eh;JMx!ZBXT0xo+<CD
zIW%~)_FaO%#S_%lT9c3b!_6XRA~11%CK$*_f@h$Ny%A%bKlgt&BtHQ?Xh^?h)oz1n
z6Rp5{%v~S%mR-KU9>638R?V78Mf2yIg6*wP^}Z4Ss(QIdBSZ=n#|-cF>KoALiD4}7
zxNB_L58L7Tvsu;xCLJt)%nlOdFQMigefTzG!+LF4^7Z{;6GJ%vp<W`DQt+3)PN+?3
zCMNg*7q=>FM{G3SH6>CdQX97o9zhN)^`BbUpBopl&j4|!1dg5ilV{C%;7YSTh{qze
zk8D-eep(1`@N9-Dji^L6{G%ThBScc4d?4J7_Mry0@X(zi#Ldt?XVJ(;Xu2g+zRe^d
zsWaj65x=sMLP}yR7)ic?ibk;wKI!r@!-hp&7GV8;`xLV^54raAy-lXj8fmxo4q)8)
zR){8G77#GY?xkPR({r$@x<lnLeOo=z?--JA{D#`|oj`bz-(#I^q8=10Qgs{M@Sd%8
z*~uAZCba#l#s}D0S!d=503o)kTv>u7U2-mOMr_aj=K^ff{BqFvu{pVnFK(vjjpki9
z8fgZ|Q|A{Uy^@B@J1n&Do^ciCn)KUpDkt}6?1kNr4~w5-K>N@uBKvL;WDq@Mj|?=h
zca+rK%r~%iwn8CpKEojUUbYkyRK51&Y{I{?X;J<vN)!fEU%Rr>Ywk|nwAS1ZFW>oK
z9qZ`NICJlswHyk+K5rURc;SvjJ}D(gKZ_yUT4-q!wo|)G-YC#)_B55~3M$42uHRuv
zhb6fJ2~f`9V1$msblPyU{<KWj>Bu+Yu3!5rlajR|n=0v{dNg1Z<zCXrD`Qo`F}=3+
z((8PY+PV(7LYfRVwjX*e(ZtBZpRu>DTM~hl-1kXj6lp<iL5Hbb;*CZ6jAcVziP+=_
zjfWPt1;YiVs(S0`RcYVepB`6{8+N2ZIN~)`-r_#-dfLSIs<||MmC3L?o>QO#q4fPA
zie0gkML*-0RJ-EjXc`h5@!K^9&rmIGFt71bnUdL2ovch}3nIbwM}(;K_r7bc|KmfP
zY@<2_n*#acrBUWebsahAMdH#t$64JUr~JpRY+BX&hrKE#yk|9<8Fh}REia!thPz4>
z3=8m%=6#~o9b~FGWYO(vM~#=E&c&zx((fK8epIIR$ZG2r#eyI+=}e;|&=FOw^dZn$
zEoUGkZajX&P`XoZEmlKfNcOIO>t-8y<VUD|j(D1i<ZQa}*d7}ZUR5rwPNH~J4*Poy
zX?I(WhKY$kf#0gOO=yrTVD;=ozrQ=^cE?tu;GPOTOup#dg+%C95Ulh*t#27G!<Wwz
z2H)K0V_D%2Q~2UV8o#)<%!x-<5O;WN9m;SKIO98!&dfNGO~s+Q-FuNPE`lNqmQEDv
zQe3+nRVjKJ@}8s)^{?)U4RW4c#fmPhf1Jw%avzKrg_N10U)S<Fc_fIv@bSSf=`&-P
z$!TV;{j|8YA@f&<&KvSU%Obu5`<^fevw~S_EsgjrP_7eS>Ea%|BLXP`_WNgCT3nt#
zio~VHg;fjr1EMzG0PRWsF+U>|YE!w-o0|c`6)5L5lR{*IpT^NrKy`NC&bEg;g#rZ|
zR0EHh8V6VU9N~hwbJ#bHjhbimI9~%qgm~jAUry<Nzskcc)l7M>ug|-ic5HYSNF64B
zO%}z8`jFf5yl;39?@zTC&e)7aHP1kxk)`1tWaP~D^aZ|<F#t)vr4{%}u(&uy=+v>2
zJ`ADs>W+{DybFafN-xX6T|UAKN(5C-)5TCe6%rcsk5xT9qpjfO%hlZaLiZCN#X*yM
zO^$cWvgQ#)!4gf;?BwaUn-3X|6A{^vtzH(5nh&N&m)NJD2f;h+lN4%#qQCh+ER>jz
zZ|lrwmY9``rxMK;atf_ByINO0_)mms#fD69RyPk#&kx`w<O+r~YrQlq%w|}uV6!jk
zx4NC>^f@j~3QzdQZDJ)-UGDNun-5MA1YnMZa^u#L5-x1_oYHJOcT$G3EsLqZoX=rK
z75+jp<f@jA**dq~@ZCXM{dDIZoP)Jcf)q`68t1B9d^kiRS-LPZC@@t_h|>c}l&Bo&
z+7bNRmI^fCf1d$4_xl{qz}3Ws&S*KLBxAN}{b9-V;XzaI(_bR4tb3?ZZ!GlV>Hz?R
zbkf6FBqjSLF5rGf^B~%t5JT}qFMCvW_=~?2{VNw&4npx$pRRzoRX-rFi>`cYtsaa#
zy@QL4!P^HMJQI=uM->8Bu|dyt3FKowLfbp;CS8%N0)mc;3#Y5|)NQxxmWJzpCN4$=
zRfYV!kIUY(v>UGn`qkN(-#5PJ)JbGyz@?V`d0^mq8rrLCi>pII`PP+|FXmT8iGUgr
zE<C-Gmx&dj@SX_pe(Mn--S?;I@?P#EeWP+eZh2kK8%Z-rn%Ay2%Bi75<&Z>b4r#6d
z-NS|el$BM>EB(kuE`rivB|YbfM4eA6tcXP9xAe1y)aW3~><}vxqw`ACsp<8TpGCR&
zegU<a-=ocGsLIGW$yL}lftT=ibMv0&>gvrdM)~*V8}X+z@yAr!D|eY#wfImZJs&vT
zk?@?q+;1dXydQ{?L^@3KyVKa9ub~^Y33C=Rb6;)<1(i^CyV?IN(SWltE?^r4o8ut$
z7L`9T-VOV+8r})u=S;WjHu_$2kCKnS@vRgAbvDV*HB=ZWfPCPxsHXD>lkiPL^N+uH
zB&)Sc_eu;%cIQ_w3Cmp&7jO|NY$ysa>EPU1H$V<%u@QZ3A=16tsk(Y+f3Ko#OgTb2
z%9ZNmsrZFlO8&Nd5;Zy|4{<J0cVQas-1V%x`Z2M==BBVv>HKZYEA_0KC2uK`lR2Ek
zmAfCUZ@)SII*lI@M?V|rPyQXOqB~WMuMe%O{rgyiYZK?DnB6g!z!C}PlZNYa$}Em4
zKe5sor3nIGIP5%8Gv#gUw7B9GIzkbR5cy!&55*BOt?o@G(?jvV5w?O@q4_5``gFj1
zcN<6Xi0QZ0x2RMD?~fpt-2vD6%*RrIQd?>VTmLCO9rEdEy0~?;`nja^7V0I(uKwv)
z_BDRM+-IhGa-@p0HXvk{eV#wRlv|1^Q1PO}4GR2n>$oJ<cXeF9o5cz(Od6?w&C_(1
zGY^k}Ei?>I^TsKZrb9*lld~y@l@Ybz-t#<&sC+LLk&|bRRilBu&#MtI#VkB|K-H}I
zM_jF*lD6`YM*5AV9{j8u>e5RDBzTNiQad2Py8HqtQJzl}?;er9Np$V5wOflAE1x?#
z<!9m@qU=uztH$)YOLwS`4I<m@?D^ld#l=D6<@75B$(~Ao<_x<M<N{kNA})0Fj~?!d
z=?qd!&`d-%YzB287=gTZA@+#6)7sklYWF!e(uoKQ=GdvrS*lFn_Zs+Czw<(&>OI4j
z24cK06`%Av*38WzYhOHj$lKXl`Om43yl9A+VjkqT?f$B2x8izuc^C|w9c+q7{djQ5
zBO1VKNeART{jmJnqLa(}j!AqF<7{H%rqF3WHUr)Y1`=kUIo$26sOT@53j;-$B(dx6
ztnKhMeE(ZHIi6m}6I6Sc0cg6JLe4TK=k5FPa}dg@xik5aybw*==J$FedH&1aZXry#
z%1R>D3n+1aPYrJGWHjlO>3k*>&MMZuI5UUeL-?BqTzuD@P1+)FJK%~ZQv5{<;d%GJ
ztv(Z7WbYH|m34cw;22q(Nnt_DwsD9xc}D&B;tlB)m6j^mZLLX0-!w7))t=1$Wmrkn
z%N7#$Matnna-3vr5bUf-KPKj_t5Yqjd8GuyDPR_CC~{h-zqgUU+>7~S&@-{sVNARp
zf+Y8TdBuz8Y>5>8u(LfPI-`m>`JFUUh?1R|)9YZ5+xj7(%e&c;&03ZX`0}e1YNFMp
zY)DkyX9yWiesxz@i6?-&eOQ_%<|p_zt{*JQ7VLiQ6>9W>{V8v+hl#CTY8~M0?PqIi
z@m$0!BKkOtgI2%S4<Lj~%Et3d1sUI<<mV0dAHZ;0GdRSRh5x+`H0A$Y5gc8NFdA(r
zl}k^;Jtk-9%gS09VWPBq@>Ygb=o9+f^1EXxe>wl9WB<nWOn7IZiPaxm-e`1Y^l7d6
zc{udgRUJn7aI@akvFw(7_@5_0vr4Ab*H%mQ&p+-oiGk#%7jd>S^;?D5kaTw<_c?vE
z5`9RnSs$<#cLfY5suur9mi_N{Dyay4Q=C%RG}V8qUR;PwI*jq6AXpzMaxz`uIQ{d-
z+iUkDZhCqq#Y(ktUbs~k!Dp}67uU7+R4C;yib9gTe>6J+3&9j9&NJ@U5cqDKRQ+eQ
z|638J*}04Ot!q65p>c>(;YZ7AgU|hb)W;<;t{`{?3}d2EAkLW@?g0mo>Q!OIGdk;*
z#ES5MHsQt)i9B;g>dAR1D<64n_0|5Dj!k=H1TA8L?JO}#=ExMiO7Rw;3+Fk@a^Z4)
zPQ7nR(LMm|uhv(FE<(GleSy0q7@{JO*MAmA(sf@0Bym?kjBE_zzg-$nBdm27XhNEh
zCvSSnr-6fU(Qy9akTXG{+g?!giSmpLs<lO#6}tO%b=Y}9OZd>*rQpe**ziqt`a-`*
z&wCTjF=@W`2o_mI94bk%kTC0Rv?ymcKn&kou>h|GUBacbnq;&`uk65iv?j;Xc!chv
za*WMv&3X%E0I8vsb{NsGr0qaXXcw%V3Hd09AdazU3h1dZ;rby-LVFdlPx?Dg1SKFO
zc3(%3h+}LZwSjPUgMtkQ;e_o@WM^|gcNqaiu1UjMi8vIBRYF1diPp=fmG>`yYjS!e
z9wHQ6U8r9>39v7>y?<P(2SM1pR#%b>h;D0VLjO}64}gmgcCbyq1CbA-1<l0vEG<{u
zJ16e&@XJZ)9R40z2!F6g!Qjmc+YR;^E&$NC;SoCHWG+O@0-E>(t2(8c_)yDEB|D#0
zbF^|KL_pBY#oP3ASMG{WSkRmMXz6@na4<|IJu{EA*Kf>0xGoF?(zA~>CYpH2u*hhr
z7*Pt)`N%86b>lcNJ$o~wY7wqyNb<ee1g4C1#SE6Qgh5Is;shUy1_IwdP@Kcuh}F*j
z@=&^KSQi>B3d@3o0|J3$PQ!M)ypNVwI5Xn)(ZADqc_C!zQTg5R9xuWcdSJ(zy~F+R
zPN}7Vj>lvRHEH!8M$(0gTkPwv72C?S_GJA<2MmVBQ4(*ohNW6|xC2hIF{Yp5f$}q3
z=kAZ+HI5%+KNMhnbt+hG1`m?Q)ngstvA3gBxQ51xdKSx8yVL}ADPk)XCiE2=-n_cP
z<K=uVkkhuAF*+Xitodx4L@`;IZNqZaypX)sQr%PfI~oVr@yf&U74*s?#}N`u5HsCE
zx=)}#$6taaK^&^cupw~a;J9`CIDpvmrQ?rO>3RqQ-<Q2;T4wh=ICvQLsIb<>?BMmf
z2J16isXx%3!pz*jX=7*pt<PTjJ<2D~bZBDFMp2r)n}XzmRpDnBdCiDHR`cJ;e`(I4
z^D%e?GiWIf<`LJskRgJkWq#PZ213Hpb6!=DxK(53QqFLL89wpI5r~ksnAr`sZzw9-
zz*Lg;F?Ix!Vla6HVAI`@?f95b|EvB{V8NRBZ7~>2bVRBL-f*2u@PEx|4*LY^JxxKT
z*{rBp>lILAw+Kwu5==z>hhjnPGXwq{-&L%{+x7C=kB7aWIut61{P}8xijCS&F%8V=
zrzf!tOFknR3m&n7)mn!d&M!Y~ot-WAdzhr*(hgNHZLO#Oc-v6K-hUBtj<m3^NP5W1
zcalZ@uypl{5@I$_I%*kZ>2A=U0aoOs{W-9DhK~eaz(rn~;Kc|EVPp3Xk0xN|%vQ{I
zv{s0%(<dmgvW{%bQ|rj-G#O38>KC_+PDu-VS6g`sc{=aVtzEHYbv5&Fn;`hCXVhzd
zuo3D+@CLQ(S;0Qe$0AC$_UX111G}<UZFMdD{4*P41m6xbBcEhnR3U=J^Dt`cW2dwZ
z24Rl&(a2r%QRYVOgHld{$a$<eejFD(R#ph)Q{tuKsdESdc8V?>-ADmiR#~!=6Pv4E
zgIGs*@S(0m<^as<)=<A~ln{-T6eN5|`Cqv<MSUl0XltUb?rik8^kC_Iyx1(J-xu2&
zbCEWDm~WhW`5#A;><F*0+1J2hbr(2zb*W}1b9`&}GK^PZ4T%^{ug<SyZ|K7m0nHBf
zrSTx$YD`Ps*bV_F%O853uDHC{cDYgfpXRjC-}Q`DiM09((So<WHM*_E*3?w)+*Fjp
zc0OcGHCy(({yD*i$%PyaoAJjq1s$Ej|9)ypGX))86eCFv3x~$XKWm`MDY1wCc%ST>
z=5;4>P+&b&NQNOY%-z<-P&?a|{owDPHHZFCP+(%prFx}E^V{D7vHR`<fl!!dp~o8Q
zKSxev<q@4a4<%5H3x*R~r9<R7E#)O9!zF&n2o;<f9RR;?O8s<{a8e2Vj;ZsYWi^1x
zQGe<!$8+^d!JJkXYX)2&*GQAJN36;5oyKzDCx$Eeh9>m~-=$y|XL!b^?|(<$tv^8m
zmz?9=wgo;s0CfY`bQD&9KYkn_K&D9s(h)`k2A$6Ca9Ks+2Iolx64V5q>=i7sE7T94
z5-KYHe(8&C^|(6=*z;eKQ7BQ6S)Yz0f%m%T#U>z*B&HBA;`v`x4F5k&otE~AtDg(y
zuw!C0XMxh=Pld<JE%_A9=_RMk_LjR>Z0*_kJ&!EIxygFacA-LX6{bl8?f`z*Q^TJa
zy3|R+y}pWJlMOH7D@V+m!1>6u#h*T*n&jJ0`Z<n0lseS3Q4u)XG{PEVE#^uwOxzfE
z<BA90zl70r6OQlh0?z%nUkesfKW@8sLuw)gs`)Un8c3P!0L#r0&M!wM+xw|;WX)#J
z03>$Wi^G}I*C@huQ)ry^52l&8{6FUat=^OW!^@$E>Uihv<t<^PNHr)+Y#wDCgYlP!
zO}5COtUu>ywTUvmq(J}6HsnMIvfjx2$}{TuFz`;iSFUw`(~GVYANj{5<zAtQrmC-j
zRWZg@l$#=!Q5lp?kef4KB>1ePX)*5<)OhYw8svL7PRm{h&jTdQsSajjFN`dApPHle
zk!YmO`2~KtCUiObn_A$Ai^|SYqE9WU=?}JRx#}bAic1yoj<N|0F6cJUP`RU!p3Bcd
zARDi4XSRT?gL=7iY*Q$+>c7C7S9k#P@E<p)JI*@29=Rh`jxIG?8RUvhuw7_S)&M3<
zxtWa3oeAT~sV@Q%BAtiiZ_)&==PQ<Ur>xyjAa6&L*~)z{G<*QYEhbU59}W~_xSo6+
z(7gQ05j~IMh*RX5vY7%68)6bgaKv%<OuQQuyp@>4SX%dx&Y#@?9Eg~deVxM><aX;h
zRgM8yU`SNbX~RsR`B1^Lf<u_&%EK{X9wl@ggN->{q?di8{Hd#5lQ48V%WN2J02Ejf
z{Xb(GX(k`FEhEeOPu6&W0PDr)0rXC7nlY`Yo9^2}y#d)44O?*2y2*Adn&u~MxO;=o
zF5HT;v5LDW-R`^!`q*#v#Y}`sp3$2lM+&=GFsFb5xz-;p^XMpqEJSWPEX1~aDa-PU
zu0Na6d%Mt^`@7$?SEeYIj;U}mGT7!zIh6P-rIRloaMjT|&(mHZl;-vp?u`ggks*e)
z6?u4~lt|nIc}G?kIpq%dFsTg@HfRn{Eq+><BtljE$5}9o{Er{??>$suFIAELDgBC=
z?AmUKHcdG)3d?usOGpDw{g0H(4sNu`^<cy$yg!X4q~Fr+;n3*rDzbj(9FxoSLO_f^
z8$fm0nal8T{K$HFv_R<vgX)aN)B;Wv#nF{+nxS^0L>Mn~klc6u`Oy^a?T|CA%Td`W
zEXGwp=)KUqpFp+o@KX0nYSLLUSzAme=22}GMx6c??~!-Y?_ebG!(Wr_yW6aOUD%LJ
zU|o;=*@p@Fs$+&Y%+U2>r~qN+N&R2iG5e3M27QPI`$PF}hsx+QwoLgOO1KHfFmK+2
zyambOD9~+cRgSt7+wzGnpzRondJtB^V-j{7je>sCfF)cBfomFwN2E~B(8%&8=!-;}
z;I+6=pqvo)`}P6ZhG@O&saKcoL^}gd<znsU6pAXV?CkBJ2a#^XBf%ow0c`e<v%+&+
z7os5o>Td*JEa1V{^A<L0YTE0Sb<kBvouMabHF1WRAq(Pq^T(bx?FdIMCazFsoteB;
zMLX=j{|$w4&lRx#V=)QNckmNOBLB(iR5w=ie~WY8n>znCH|rUU(8X#8xIKMt5vs=2
z-fls~DY*LrDuK3HwVq*hon3O`cHX``i*>Pm|8f6^bC)>}S_5n8j9y2yqt*9ulrMB#
zm;&B|Tlvc<y=NUUTNJ9!ZW5oODO{gBDqRWBFa9<MVi~{PdAsc23ZVW{aeP;{p4jY*
z8Qq?+o|@%-d3<d${Is4LW1vIUe-4SYp4wWoAB>Y?Af*P7B=^g8uh?V#L!G$#|6>5%
z;f2a9K{Z2L_GLm2niaC)DI8f7F@&2K!u-wt9VYm!-~<Ox4slHgvTP3N>gk0TS3@qF
z{ojR)HoSIvzMS};L`J}wS$B0*cU&ZoF~r~)_QKQ0;%|o&B(<B%60#_{H9iMv*-I#W
z(f9$W&HrgwC*{|noy<2?v3kF^GNn?w-g^K%Fd_Uz3FRqyd|`LlXl6%s{{6tyyvWbu
z_$ieQ{5$L-;MO2wez1sB0zIMlPZ-=A@Bitxl{&X=myRbcRJ88sQ?O_<|BKMC=x~mx
zb}M!536n<9fF0$usDNw;Y}TG&cE5S#D^DH_o$tC0AhPR_=7S-2T^7Y2jhZC39tCZ?
zOL4f&)h|Sxob_tcV!)nJrB88jG{IF~{-IPxAj;WA^k?~7*EE7rX;<i)Gyd4+#E;KO
z>e@b<?@eCUD9!e!*87ev3gm=~Tl_->oKIKCQNfU>mf2M&{4YP1>90+jL1+A3S9{$s
zqoE%^UtW%X=v)bQa#=<D=P@Rj{<)BJvB58A@A=|eDx47h(FKYP3nCaE&XD_0$sc^I
zpaxjp8CtGo>c1k4rjzWwOGy^*v##O%$TYWd3Z!hDPF{+~t=Yv^rGo}Qs?^_W*F1L(
z)c%T@eaXS06^0RK^rugPA7U(&%V)RzioPvNLERfATpnwKE&lrMS5`nCi(Y4ETus20
zdTdqWaXg88S#zWyx3qO>1TXjrL-G9YD{20tY<Sx1i~aJ-Dn~6W83!k)G?MDnl=gbu
zF*X~&8IhHbAOn=+<B!%SeU19rIS7k1$GVpE<_n$3w?*NRjc|(^8GU;yf4Dyz;f(@R
zRp|32ltTks>bmRNP|3p^!_`NEwP^?7^KC`^d&oOdfTU#b(*{;ZZdxZEsJf@9JKPTp
zuOUzS`z&e+wOBkeQWqK!hB@o~2vq*u(t$X7pM0sKa!!%(1HBPZ3h~#aNCnQ=b8|G6
zX{oHxbqh^(wcFFib3ZwpF)p6)!8X~kblrz(j|as>_M&F=1tD?f8)w5jR?urYghCWi
z8zca8nHuya>QJ$4EtFuBl;E%t@;Q*}uH|-5$57lI_P&$x^}cgxMay|}ze5+bDp>(+
z3eE2<+<npAOu9{>lO+D>*uNm{j_h6d%98+>C6JJGan45XzQ1JUqeJp(@aYFdd-8-%
z<a%A|s$A2)4VaaaZ+8e}_MMC+%P>M`6MpZL7Y5P#;{*x^=BeBFCFhW)fI!S1E`Oxn
zhAE;Fk5CMS<G1dMVBPbdhyRbMw~UMO`{K0$kp}5*q@<-mx}{sXL%O@WL%LH!q&tQ#
zrIjAKYZ$tQfoJ^v&pDsx?aZsa*S^<YajozEP4=nVsJ)LmBx2P)EUT^`?3V<4x^#uH
z$PtIpZ~RN&t8SF(AZSw>M=>*omIo^$hMDZcyZ+BzjOA6~f@?2V1yKBFIkPuCD6}t;
zG{><p+2mb)tFB@@iX!dGBb58V4hrqNse|u?>_weg0V8L}Dss&<dEU6)$LrjOT*0<D
z-01G#`Dz?=z^uDdx+>c138LRfu}h7%S4v4EDoO;oBWqi4f8=S9y#N0@AJ(q6*v=<(
zap>D+H^R(j#CWX!OwAM?cm+)CW9pCaC86T8v+!`Xg9s7p{%@C%Qe!jSX%~!bc6oGE
zUZql67M#gppUJYi(?1V=hYLBiVi-zz`(AtyPw0m5?nV3597VPTC5{4NjtzhH-T{kJ
zy%Yrkl}D?y>Eq}aH!E6W!r1OTT|7@V+}4wBFyV$pDr1o*0d!laX5XYKz06Or=j??a
z<L_VP<66}4F9Qt<XPwE<DsLNCT{%+dZ`4Q@1~%`1sk8kSIDE)@1ZmR=(C4|F?kn?p
zUIUC6cmhcjx+K3vxO4O+RrbBo&9+=7&yz9CY<QCoDw;f!mWQq24JGupx#N3#2Vr<Z
zKVtFpeeuZ~EvW9)JNxOJiN9b@KJzYLD8ejz`ycDh2|<uD2rsEEiM^Jp-E_^IT@_6=
zwl#_VVnJ-(CpFIuA}I0TkzWnu$S00c81jVY!YCtkz6;>|9ZIG<=<Z)5IV>PNq|Q4p
zG2cuR5EiXb_Q6N`EfMsUzK(1;7>-(Fm>`hl$obG#ojt(u?UOqDb1C}7ad}&x3DKj&
z4N*0vH|<5OlI}a24}2)?5=Q=rO^8}nNf0;Jb`b^{W#$4Zj*rYXeU<Kqt!!TmlD>5b
zy31otI!;m+j$Y|M&j88tIxg?5$OA8=tEWE1{k(oOsBdfRZTc~OXZmGYVr}Jx3)^nF
zk!o1>P)}*8x3=7IH_quOJHKdT^eWEHpfxvqPdM`GI7#~-Am;R)#$le9Od0|BCnE7`
zlc@QBwHa9WO(L-`bDfHv(k7n|KMcF6r7Q(Ph@+UXBzjjsh$!3M_pn_J^=rbyQ8Ly*
z3bg4vJ-SC_Un^8w_-6VPLrn9=O8Av|&0?=+hKPQUqb_DyA=V9tEwAa5tVinm7L<E?
z>fF!HCfL;!ZwI>m7Hpn?#@Z!vKnaPORLbvRMMp^p{@Tl46=B>NBRf%O@I*Pl+TwAF
z0-L$()%?2*J67Nf0=v;H4ajF;;(PnF#pOm>)q*{JyAm6V_ldy0b=Y7z_7#;T-_*|C
zbaMFC?WH~>yowB5TCuJ**U@NY=Y<3$BXeQZ2793(6Sjr?;^PB<_{fEb;D7pHo(&CS
zC;tTOiJF=2OTud<@Q@#45th4j)}b1DybIL;4r;=a(A(xlR9q_a{)=MH$g0)^Q8ip&
zJpPL(Yp~&L&oTU$P>%(Hzg_sclXRDyUc24qG8o@qu7=2yY2md4eDmjAPoIETX!l<~
zuQWh61VZXrY4^(}!grb2JY)I-8kAo)wdSY}8w2-B{{%g^$pMSUgUZ2WRNwEIp=I-Y
z*sIe=qD&KBrWlzmP}jBRMTT-MqJ_vWwyEgNW?K(*<f*6^|Ca@L$ME9h&1x8Qy{6`w
zd`d};+Vk}1Q~8OzO47$~b{*YN5_!9*pt*+CCrf(Tst-81{gZ<|-?}^tT&@Q4d|r{+
zA2f;*(aER6%)H1*L;ASxk%IOMId+gMIJO3!K2kcajoKWV4ApO3%lTOE*d2q+vL$ig
zlGd9M*0*@j{1eBh@<(2;6qC1YL}BU_So6LNT(CXcE$fLPG#UkM=bL5EZCT`+eJ;!5
z-<>UKHRg$DFQn^8s6vqFMnMtL5;pl%>DI?q_ZKg2Mi#%7im_w7idLO-?p4hrZ_qqe
znkLF51)FYGo=5>@nWS3kYQ8c~Jnsz_*ljehzmc-RC~THyOs*D+22)6*x<#lDsd_&u
z8t{4`@mJ2jpf9L8a_Thms+aK>IP%(M<`-Ueeu2s}bW|8z+S;jY9zXAPSF884Hjz-G
z|7T8hU-#0T2M=p|5Mrib477EZ)vV_FfpZGDz*EVfUW9_KDtoxx*e&ol>p5>{)yMxk
z3K1D<lf53n{2n&5f$_4j!_QUQ{-zHV`@E)hn~K7hQf><Kh#p{L4r7A^5@WF_eYPsD
ze3_IU^FMJ#&IBC@yub#H5ra;tg5i>j@@u;k{>94z;)p4^&%M7IR+C{~`s6_CBL*Ha
zP6I%5$el_s{6Kol-Q%9T|2ODO3;}X+!pi<7!W&(ek|&QnLBk<QB-NiOZSb)>apfo^
zTw(FBOsp)99VLXVnNI&bs;JiH=69Ji>XBVh=G<tLkdkRH%93!&X#eSCA>bv@ps=5@
za|XGUBSIW7N8H8shhfd<Yt2%fn>3%2Q10x-Y_qB)-lY>M?chE)5z>$5lfYcdVEezr
zIsDds_oPD$>)E#EZgwBawC)}qT5nxj&ipkeetL@{#y-K-0?8)XC_-k@dKgd!!x^0i
ziI)^QX^lEy%YEQ1(R=88vpFgz^lX#8WDvWblvnex4tZe{<>fZis**UKXpJC#uFx+o
z(2Lre?!P?<wH215K`w5?g%lS|(uV1OcJOx3w!R05EB*@4o&AQ)2}ds4f>w$}4jd2%
z7B$yeRsxaX+~yO6;gR1P<nX37e;*bV6dVOO+>Qou-9gn^7Wo$;!D2p}_%FYLuMvZe
zg98Z;*&Y23zUR7fP@unW9s@+3S-2DPq>7wV8(>S@StF{o1(uuyFaqJenPlF^uh@->
z<WEh~{z&qzKgZZ>BZbT(q!t8Dt9z{BSk2_BwQai77Fz?|C6ZtdOLaH+FS)A6xg%M=
znLpk*M3H=i6l)((uzYnc?Q(UNDo%4rR#2lnkIOHldvEoQX<abAV7KRlKkv8tUc#^C
z+7#et6%LJqj_JQx@@0c#nQ&L@yUbnF;j8P{Uv;>&?*#?VFS}*{cGE19mX$rY<<>w{
zHWW*ML&b*ZhmGDSLUOp;%-Eb`ih#3S=k58LG1uLvPlj`8Eeq?r0&TBCC#y$n$By-7
zNBW0ffLt^71AOw#G~aU@ZGg3ff#Ccd8G_@NK8x=+0PGD<Sw!G@fvi;E3Hxa<J<4{*
z?IQZ(928iSI^J$LJP&p%`y1;RJcbG=J6Y#`0152%GqCtV<odmYxOS%@veX{9tD+yJ
zkH-0)yV=hH5;bK90h>*2+#F^UV_|gh{#p1{z;nx9#>TJx-Z6qSZl-Bz9Z;uk)*O#u
zVN#09_2x8(zTGd>Y(=)v{#2>umC4>92G`RCwl6^3mnunxv9l`d>bR^D<MfPr%(7=n
zOFJ*pF)HC$?_PhtyL$t$@faZaQ_R7hblnrZXYo}DlOp3>pd7*eJj=DqS>5cos~3W9
z@h23Ti{9iQZ0Fu9zbk#|6rCrorWIe(JRPqVGzCnDmZDJyC|M`)3)U}O&#%rFT8=SJ
z#MwrlLKY0Xk&ShSAI@?y(eaeQ1-%Q$d;ZSiZ+cIEZP&kX5N|`s5`w|5u&n-}dWHYe
z9oaaHxhc{BIg#xd`n`TTiZ@Z$D~ZWb*Tj}9*azoHqbrU>sgf&|PQE1~4!wKab(bR|
zL{GO&2*1_g)}?GEVpePNfv5pf<hnIMuYL%7s3t$nMGaZw8Or-N)I#`6r!R7wc0jM!
zT>g+lfL6UItk&wZ?~?G&jtuE4h6Ch<{4tu^(iGxHcWtcjITn<`8`4Cv8~$hG%IQl4
z9Hp-*Y2Wi^FVX9>iBW%+NzdDrtoJNkIWwt4j`kMlxob>oEpHyCvoEu6g$}T&5I-hQ
z56szEf1Kd4sZgu8$|5743#qW$^iY|e4$0r4^159$^rCTWh;Eh`cLzJSvn@Nm9qXwW
z!uO?O(PBEiGPLLAZF6t(m{CVTOHwW4(<lDjgN-NzQjt!eD`=t<)_V7gFw=Pr4sLQ%
zDXe^z%glgq1BT8s9Z0NlDu24^y&wF^lAj^I(7Rf*K(-EPM2wJZ47X6se_5;%!7=`n
z9C)NhF5spX8(8yqVE?a;#)NHd|MNCI{aqy7$<z(RzS+3uWxf6bY=7%Z7Ulcsw7HO+
zje3!oI>y3#QMh-xmK*8$_;oU>Y|r$`#$%?1yE{<)-M+g3CFe^{S4!MqBmaoMVkh0g
zOLO9Ltn3nnDw2N)7A?!->3KUV$|d&;sy(|CNWV$vbYGZ(HFYDHUV3HYm~WC9Xw<kJ
zdS0Q<yQ{6fJzggQtcuYKO%1JG`W=pNRmz@Hi`~<XOUGxg8<_n+4qh_H@nHCCb1BiF
z2_C1tvaRgp-RZ60Or5GB4z8hx*Xpv;k-wR;FV<-xUYcYWy2;ngO&S`c+uukkODmp;
zulOPZQK|{>F#K@mu7E)@4fpwQe#0}I+7Aqg1N;AxHqDp8nYHJgCq*lyk3drX8wjN8
z3zXEn6_xS95yoYoOWHTxKX4RKxjgI{b$FBRS}Wr7%=Ghd$I*UPJ<rw)B3fa;F2m9e
zF0~>kDl9Qm3ANsd<YgBI0tJH4F~<{7LjR&)3q1CYxt^m}x*V=f%{LWLJ$lSfQ;>P9
zwm&(#s=j$?mP$=|Uv*((*OlqZ@#FY}yiyvsK&MM;iDW16p)u`#_k7{B!yl@11_lS*
zV{BXxRCW*6VnDp)1^|lhzD3k7Xv;G`uG;`e0M0$0fY?0UJZNfLb7$o3DHy{NGF0^R
z{veCc^?ns|t;>(C(Gb)xl!@!aZ7>b}VjujzeM<S1S!qE<g2;~H4s&RFl)=fQlM<3w
zg;SxL<YZy)hbB9vv_9jS%>@x9zkTk#&mSI4m7;6qz={=Wn%?<C^K-2i&nLNZfvk#x
zrAH7ptvp%ov^{3C`J2AUMbOr1Tl4SX1fKqU9_IY;o;VATC)JmVp+$lBoQO@Xj;Tbd
zhL<LP$6YLSV{(n%jK}O-T-Gy!N*$;uq~cw@o66uXpI>dAMq?#1m`Mu~_T3M8DSjej
zQ%zM;t7zm#xmbHXbM$js<|h12k=zla4vJwKSEX1J(sV-Sg#ng?eb4tr{hN^J&4Kv(
zjmS(J2dvPFJZ!-TDIK|RhWJgd>YN-&^eNj?K`wa7OGx2l^`v`}HBZSBK@a{P25R@c
z8t%MiY8K&>@!}Xi9eMFRQZlJD3nj%W!9x_y=<!QyN!vtY#Og2*9k80#gLf>zIAIjy
zq{P0UA|std*_Qg_c0>e0%Y9|DTuPGn6u2c$3|a0hHEJq@Ed@aMSgTWCJ%jx7DnISb
zdOp(G-U|JP@XzwNU%CNUUm1maYLmLSsOcLTy9)Iy{(gAT-z%}|?O5P(1fQ_N+2&%2
zobKOZhpSm4CfK$jT6X&&$H2hJMZCOn(w}XZ1m^l5n~I2TSKni(Ki_7ykfdY=ChO*9
zN2Z{iJ12IYK@0*BFg2$Hz4I8jH*K<~^yclu0gS)im>~gS8v<V@`c`?MqnQ&`Ui>qr
z{V68-m!l0u3X!g`$TxWcw<m!<hq8D&1`Cfp=XvGCUKgHy_Oh2dlyI|&DMPJP+M!##
z3ekGba0NT{j7E^4fTa74cez#ccL1a2wLcqOdu*ZdNow0HXDfFyofquJs5@~T`+Ei(
z@ouSmRs1d1u)%RhNfVC}iRe0#27*t2$x1Vc=LQ|sr>dm5<Gg22a*?F!E0^VFUJyfe
z-l||WlPoW|+75>NJ-;cn!;jCN`$(tHlc$-z7+)k%YR{lFrL^!F7qRM13%=5_otiFr
z#wQ46$b4gO4;G`<8oKgUnb_l3+uW$yTjifHomkV)Btf!o>v}svw=6W;jiM^7OT&J&
zxJbrK`m1LQx?|IV;RfYNpI6x;`YmPvR2(mJMJ25S1=~Ki&oXPT4|LRO6@j!AC+VAr
zH5QdBoLo|1hFC;nf2$3CUR7}oOd#1K7z7SJGwT6c%#;8C;fr@FCtahG&(KzSA{XyN
z&78wBQ=qbgS0U`OJ?&glPjp;~1)AhBpOfm4nIkmwl-*AW3wxe9EOBzJ0P1s%vo&d>
zn)Z3xK1Sh7$oV6O#vCJsxK-G5VQ`~G-zc-52-3blu&F<-#t?B5Dkv19Sc|zr7BTdN
z1AJFiCslGDR*HJ5((qO|>`0<k0;{GG`_F>p2PRx#B@+@Dd&GsI$=X)7y%R~l+;(qQ
zrQUuq@GgIB&SK*CnFhz1u=<hzk#~j%MbSDR_G2%dEMoERHfNpA%^)G#KRQ<&U}sg2
zyfrJ7l@pFir}^;ltB9-Ar|MIsW=)2`;dbU##vjyIx2dXIS$(f^t!z)ZxgE)$!yv3L
zWwSmFn--!UgsJ_33pwB=5T(hs>U2=>^U#d>apAU&#fEPnGH{})1%w30l;qYy#C6L1
z>GAU2h)~J*^bWUk5Sl)(kaJPd=xW!o@a8+dJ8PnYON-!B8(G|0`FU6GL+)Z4h7l)y
zm_b_8*u1zAw+a;Ff7iQ9rAhfrb1L0>$cJ+eL+un5I3uWGZ6dU>6XK3Qo30aUPWtOT
zy5{V{Ju<wgmH39~uwN1XCVgQI3kdbr=#*f-h&O(1=CNQ2O+$lPfQM3%-ptCMcES8>
zD|`stlZr|ota~v|yBsAjAd?A=>7cFXZP=o1b?_04yjSdTd4qcU9+hq9M6z7@Bqr{I
zw2Oh_1>D=Qz?-rSFJ9W@I%u3U<#;y;E!jT~kLYdkK94mK(ZxJt5!q^x|N6kxQWv-Q
zZn6~b*^qd0B&WYAd~(oH&hlnmejiFFIwI=};c8p|F?brG_mXd%keC-Qc;Ds~kB1>T
z*+T~V%f_SGvRel}Sen<tAQ{842%e9RG^MR8U9^lEU*^_~xZ+D4@UOt8F|jQLG6IKF
z^$g~)v3i9MqUlkbloz*!-1>a+Ws7&zO4>#0l;r@<e;k>$H|_T*^h2!e(OW%MHm810
z3IUC+QP0+9>u?pqx!dtu&Dbihj&5_Lr8tg2lxlCGdy11#c~N7#WL5~it-p&=Fl<b3
zX-=Wn+?84STjrrE+fMuG_`^KSc^AG-rAhRYJcHR%*XEoNY*1}==tKJ&-kO#aC0F$7
zt_mQV4)Zl89ys0NNF=${N%cx|H0n}+5sRYR+ZgGT89e|>9t={dKBg_0+lZ$M+!AQh
zS#r5d<PP00C?GsH28e2`Te-hXV(8b_g^N)8ObC7of<4GAfVJ-LQO@_Xy+~?8R8)f^
zZ*e#KM}ef^pB6wg@hN}&8Ld_JdWaNhkn=6zVR`=h+Nq(_%=WeYI~E6RBGGux&$jIg
z(H3T-@!VhsbN{irE)tBPst_41C8U4NNNcTcMyjwMqTn2y_!>HoBS$uRYxzFY!^9bS
zPYuM?z}-6rGe;PA#aoiMzp9+4l>gE^v;E$9sB`~(ldFi+C_WqK+<CfyTS%{agN<W5
z%*N>Kn|nmd>nY!-H+Y}CwD_qRB1hBv;#Mc>TS}CUGe?KzEmqT9BzIKo)u-#7jI(wp
z5s8&7a*u&U(Pv|O>Ku5AvAXn*R!^y%J#Hqbx4GLN%258smQHCa_~Ll1v9m1{20y&b
zH0k#79bU|M1K+?F+Uz`a*LOc6Di}SgNd=|efRxzC*^RZ`V)F^9CTk(XExS=V9x|Og
zEu@~VCOd%UXOE9;NmUk<W2rsvEVw3}w%bHvGw0`KuL=}}W*Zew$`)bL6%{TqAqxu%
zOi6y@2{>)a56LjXF_G<Gt<N|@^-zi7zs-}ryPoigT5(3y)E+KxRy%XVie^u)n29O6
zH8R8t17h%dA~sPBzHD|Mv*Z2=e#jhX$AGpFpnP{Ap>9QqSh9}GY}Y(Tr>mA*b1XLX
z*Oq9c3VuS<#yae1q=Z({(Ho)0;+|DHx7$Gw-#Z0Ael@tNRLK$HOs*8YOf3P`)z@vG
znmk)qB}=stczpte;S>EhYFX{@@<T4(Hi9)mK3xK+`sV{U*GFL8w@>!(9NXomdwJu%
z<j@oN`IU7uA5M;9cOPDgo+jn**g9h}7VpcdUTjz1;cLtUS-O{n=CvP;UdO8b)A3kg
zgBcfFTNGX&HA@<{37@~{<%H~BT&!|<u*N#)>qj*wQ<V~1bCi7zaNs`vuSqN$8P3Qx
zDOw7)jEzJ1BoQKc4Ie7mvn5#_IPA#nCLBPAfZ|3cGaS#NA%h=*I4ASXU7+g|E57R=
zTK)3Y*jewVnn4aF2_-VEv@^?kS<62r=Xgd;%_4k~(M>Y!W?ZT+lbVumBCvhV8Aaa?
zk&6=Ff?p57rOg(PN%yl{sxUAM^2|FpN<p@GRYpAW%b6Id@MX`viuYuM_vd?ZxvjO%
zoRogr4;}IULQS#DBIs0!<^fztxzPFfGZPbYvGDiropCnvH*^pZ+E8wrce^JUkw5Zq
zW&W*gg^g8M+3;j?pFOy(IfhLR$~9f+B8!R$KX$O)YJyG5$vcn}Lu_6DF-0SNC2M@%
za1G|J1(y#wc1f(oBml3G6q8m0`2dpj<1lp3yP@et0c3|R=)=l!(BUz*I{R7<2*3GL
zTN3e{%#3;wYm0mx2P>|+L`%^pIrp!$c`=|ATbb{mFRpUFl4-6uLKwK}rNqE(=s8|?
zc|y0G*mG~HMwFq?HHLBUafTC_`G^)hxx2=PpMl<{&J>}5r!9F;9!AE?y)iKiWh$C?
z3U3XAY;Zws8+~;Te~&sgcd>J$W}ZQPNynWl%bV9ti!a0uf@u%k9$rXwf4`wud!7?T
zi8!|yFsKxCy(1%=k_2*p2!mZn&GsEus=MA<MG<Lq=JU$-XnlaI4P5;ZNpxA7vrM2E
z?4WqpJL|4vM492!X!Sjsdx=Pce&qGTis#WBd>GBnC^H91%E~2cy{gM8)E#P$VjsIj
z+K2d~;RXws#kA7nkIr@_PFyXo0?oQ&$^sfCmQm~64#$K#*XJn!qPhxA;}U@7;&}Pz
zbTcu<qY~piJa3E<VBx>dMeK1d)gfqm^Cfg<+Vn2R!!{&5gL+o4k7{u=Hq~L8%5d0U
z^kN>)t0of8u!EBVw|T#NG4OdTn3$20L^&S;&hb#*FErg=o3!AkUyc^JT)0(Yj;;LR
zzv_ZP3Y=))3--(Yx{b?NVTcSV`JY*aHxz%mgB9QCf=Hgj^ERXZ){bbbj%d!p0HYi+
z=o8yo&x8tJ)Jn|}shO28fpsm?SGG6VDs1(~LPE6&)2Nc-4?HE3cnt=+@cHu2^~Uoc
zWwqoF)U#F2R&~6soU4=Zy}URJLyPt+%t8!|?KA`cu9_vhGht)t`05qrql(bQSqthQ
zAbhd<%pwX|MW}u=mn3PJC1jSB$Bx2sDv*SJm_tJRJ-`PyLN<`Q8LL?j2ChhbQC;!!
z&=gjhZ?<_+Qc?{qCpSm220HUKnfyMgKpktMMppjH(6ZMHrm^zsTRibZF^VR)B{b>n
zxwy^E@O3zi3YQ%Ub;RpRF7chTiAHDqR>ezZtE6J7W5YK&FfAb&t_CtQC$|1syg`yB
zj*Xad5g2V(Ss8x>EfPOE0ep59NPA6Z>4|*QeOG(xD0T0=l=HcFa8P&6d7`hDYvNbC
zq4b15<hOxS<#((SHG-0--`JfUIzymyc1`jX>eh&^Mk2ySAE3!bYx`<V0Ey%`%Tgd^
z!uxIKyo#?d7ZHRa3713x0MBDm;QiIi;p1Q8cLVB1S|3#{kml^$!e!uvHh3IS*A)f|
zx31lUc5ZAJK%eD#zU(EE5p7OsPjfhY<tRcdd1JAop8yH~20aYBI=}`q{v5mKSlN5x
z&9cffvPfzKLD;)Wq-+sf{+!S|IFg{q)=Ey^Q^VvkF;oNhphqofoAkuDq@-zOa?;c*
zq;?_`dSTUUHkma`jw!5s`{=1}u+99;DEo!0tqu?9SMBi{A4yOd##bmme2$~;|GCuA
z+r@X$wHs$j#5{ENVbyZ$wdYzQAP9={X}u>Ys-f{i9_O~{XXo7{k=U%ZWb+Yb4nM3S
z8CVaBR1UZBb(HP-#Mx$Zj~k=eUr(<yu?V92DkokP;d|5<qN7Tr-}97FFTtX8hCOWP
z2d6*kPhVy|__G=n+CKMt`i)%D@G}i>+)84i1J2l!EM{8<+c<F)2=qW?wWmno20g(H
zIL*j1Ta4dCE>OYjAJdqSUje-yXti<sxImCLdiiqnRQNIHPtdN8zJ+)S`(qgPJ+N0;
zFGTPFJa^Tsb3lp8ldO}Nk3zywnN1az{Y2yBQzDKMfQS#%@~0y|Oz!w&Nb$N|$@;3g
z8>K_5y@;x*8(2THUwA1~y`HG(PbHu=JhAn5(yhy>bYn88@m$VUKG19ec3BUC_uMI-
z>bOk+-1CW5*dE<Okh)JzAs2`kgN~t$N%GvAiT%`mU8r$)7P&E{n<Is_rX0f@$!BFR
zrBz3;UTOJ5n(yX{YA-!4lb;$}L#z;R0-sd60BVIsSxSp{p9k?LVRoneoTm}vd6rrA
z9CK>$`2kXLFA}O>n{+G8(&!1JF6_N`gX7yVhbasOz;<`PkVT&**6uIv@r}V`^*vF#
zCJ(Z9Bx7Ej!M4>dKo)-R)|t2QjL}9SD<VpZF6GeT6Gcjpr!7QrEXmx$7juH&`FkdC
zWo`6oiWdd{_0!fe-?$1<r9kFcGQ=lT#$!@>N@aILPIYH$X+ypiXlL-H*VCq7M~=ou
zzT_>Nc-qQLE^G!7H!W=??S0fXXi3E;)Aw0QEC!+)AaK|2rMPq5cPsobH}k@iD=2+q
zcD~k;$N}8|zw6mpF8v1{tvF&MZX8c;7pUC%KYjcU%<Jq72qf#fj?Qugr!uTk#P<0d
z^S$iZ^SgR$CrTxoWpmMtVK`X_OARl<!?>mJT|LgpmjQR5Xc_nt6bv*__Z<2f6KPQ1
zNddHuH@FK$*CT~udmR1a_79$&5ds-lx{gls6wDaI?!dTSeRvz_ToAHyMXUdiVEtUT
z8WbR`MO+ah&%K=cQ6o$1n`K8kX#GZfA%*9BFf6MxJl^LhP?f2Xit(q*edmuL*Sjw*
zACComw%_%l9Peo&$sr<@OErrjRl^#1Ym{9Sa#WvEnOj^yx&&h*Vh6Ng@!766*+_-Y
z!*Zs?`<*}Jv9b_=ZiMRmS2DaLx)E^tz<<2lt6(p<{sl!Em3FBy>R)b_08<$FC#E*x
z{B!H3zJetlmgk0J!v=;hEHAmOV6>cx*5QjOam5FOV=2kaj8%G^E77;0A1Yj13$UU4
z8+`o7KZ*~AEp=~vBbbPW$_ZofjFvwd1t`YemJrn{xNd6JuhZI^cy{I1wU*xy>>Iv@
z(GpRA_^7^qPtsS@0;=gd>rPyj|3D+ht<Fy|1nC8rVe5PSh#vsLWd8jdNPbh>G^CU7
zPFMH&;7ss0y~PT8hV%h9ks@vtQXUyYzEJ$2=pJLHj5C**1G6Uw??JQkf2qW3zPEfw
z<TzNOpq7-*vzt)o4S9LmXYsk-*Yr7Csr=xi-iq>{sDP}6w+X?2Y@Iq*Xe6PMkn}G>
zEttl@6}9wA-Mc8WAA_C(-P8YG$pj(WbRdI%WCcdH3-_?rz;Cb~tM#d0d5x@uIS1Y>
zy<=DX!PvWrNY1Eei_=#a-1*rY5*G$7o8)^dMr|Vexq(X9T9QgzdQA1E?Az9*PAGJ?
zH#sRdR8I5)zv3`X6}m*R>k2V|wkdXcyA7`Qx>3{z-+m8WynI^WxWR$rr4|x{Q}g=#
zd;PQJ&$o4o0M{ilKbS%qC)S3)>SJO$Odv$j&lOY!w|$M$`*fS-a({4vqjQJ&zsUc~
z|EO9eq2W2SY>yb23;_l=t>jrj)+NS}<zG*pF;s-#E*+4Ow+dnC8Es`daaAa^IRYh8
z<=_B>Fad*V1hgVJYT8kG{mT1aaki;)!zFQ5?jo!`YMtP}(nu1>Js-Z^`{tNO?<MP(
z9%i~lGN3{L_c+{G=fTgG$9M3pKz52-|27PVi9y}hEyWbK3lxf=P#Im9E#p^)km+}W
zjrX!tBXc6{k&&VUjow@15}zJ!b~9R3g@$BW;NS+&y(S@Lr77t!VD$yV%jUKB?|&3z
z0^0wX#!|2uU(1*jrKO|dhf$t{<a1$Wckd*S+r>HaeNd0-u(>A$-gl^dUGqF*M5T1o
z!eKgX6;u#UfuU>lN3_2rPE8oOJyAwhE>Bp)ZG*FxqI~3n^(3S1O7)~cSyT(Oil!PH
zzKj)Yq$NR{D$HKtn+x~d&9LWM0wAg;{j2Nyp-bpD%`6Qlta&2~?x+40MF=+|egmgz
zMY8Jy{(bjS8Q&#o{2yWnTYz->F~!T~7LF7!ytrOxxioI>pJgU(|L=5+mONJdjm;hM
zf7FUP&a#1T4@s1Q#IQgh^Mld%%c?T24;^YUn@*d@gan_;1p}(@`^p{V3Dn<9cgm|U
zb9EdIPGfI+wHxg!aMS)@764JxCc>fmy^%w)jzj8uPG+gIl%Ch$INk4Kg+Bwmip9=L
zs|`LOcaVOA<iUMW)Gc0^-*{t{C}QPRu+Bl<ad&6cbNk0T$`HtZU=A@hwV4==)N~HB
z%yDaWLoq3PM%msPh}Jb-wAbdrgcGNeY2ie3P~b&jJ0k4yd17Vn^{gvh)QYdr=Es70
z6|(=g&T;FKw`o`k-6ssN%FqPP>Ul8945yOH_-pcv-ljJ~4IfyROCHBCeKu-XZ`yb9
zRyYyIW5;tsS_U7w?<6J%BaJ5L8Vh;mA}8Z)Lv8(`)8|+D(0w$_(z{(?Nm4@t^Gn%A
z(5f88-27Wt92mW%`XHcb?^2<gv8tl9^jA1Y;-u8~>~5Z>K!?l(vX&Jk#`TCu2&fO`
zI%*2CAp!S1E{=mJ#J(k;S|FQ@?pf;mU~cu;bjR#=_wG|v{#y#Xm^w7+KREGwTU$;1
zAHyDV_ELlJAKz-{%J;(wp8G%^rt$*|XE1Ns*<ngvsU0NsMu$a`{-Umu-?k*_8<Xzf
z^Ve}MrRw{>MbK4G7!Amr&(n%_bCse46}<9&Z)Jh|n}k+SFj4k{G{u0UPBanQ_vaWw
z@wFf}b%zw{GZeXOH5*aEZ&HGRn?P{yuJQ@i&+ja8Y{)VMP%UNrO(Ge(uio*teUBrD
zjjgbjYD&3#!z+JQ_mcDW?-leRey>US?gWmhf`R8rAl<^|*Tk2X&~c=dA&|+!&d-n7
zv?qiu!i2^TgGCZTWpXQAJPWi<2>)SJbc6rISYR$wgT{tPgqmw1h08w`Hgbbb<8=?K
zFPO>Fsh|{3>+q0DtDS30o}{FcOzQzD!R4wj^|}w~E@G%y%M#K=Dsi)eeb9wC%x5S8
zfiY7%6*e&<uq5crDtLaSPJR!^R;q<f%|WbT26BgbH{cBq$oDVu3B^ml2WW;gw|!vm
z^TZ-j0qDsaeLZv#<7YP-m{L3$;kTm3Rblvxx8&k;ypVcgY+@{9?{8BsWSD<9MYFU9
zW#?5+-i+#QciNqg=SVaRmI@}~g)WZYriae{?>qc|M*Lhd-L1_ZO5!eGaky)p4G3fR
z0;BJ`%31sa$u9EmPe2j03e-m!n)bp*Fg+Qlx{YhX1r7c_t-^9jy8ipGi~gBMw6NKN
zr&C5@z(fpd%8|=?rMjApu(IhNuz%!T4Zg4z{ngPbma{$Y-8z)RCQBl1DEct#<15tm
zs<Fa&UT65{!v|YO$KBJS*S`pMad+<G_(aX4-G>{aSBdM}`IPChj+plpzOLomfQ93&
zL?V+9XO;>D+fPEQ-&PWB^{@DP9<P`UgS~m?l0$|=N2w%;4Cod#(f;|yY@GiL2}|>1
zQyfCifZF`wB<?XV9ie8i*^KUxJC3gDFt#YOm*Be%R-Mefo@<EQo(^zjW__u*Jqvi|
zbT_!MycZ)ZlPDjXUOe&#g`2pa^LYoEBr0?OE{JFJA|8GyWShhnV``Z+Q6|1ro=@gS
zo+5wN#y#lH4Giio46Nbhrh8VaRB_B9(bFc$(LM|iEA9gSii_j;=$82Kav7-X5zi(>
z@dQeF36G_aZJ&|MFR~l62|jw{M0Qh4k8fC5paJ?z6QQtfz9iPixU~_Dl*oOVTfcug
zBJ3zXba4V=dHbCb5?j%`*#dQAKmAEMNLAky=6#5+OVl#)b>~c#o%Jmo<>jxIj5m2+
zPgY||rsOIC8=m5Ri9pFOAC`0OjjwHm5@^r!*a`UW*lYzn+y^q#8wVfw&i~FBUfu7O
zLSwrNRZP6T2u#t~AyO3;aofWV2b<EoLK~9}$K`D$u!m!mUNl3gQNpNE9LGn;{IYa#
zAaCOS`-3<i(Ew4RT&kfe1cZjB;nD#n1tk*0R}~bpT}nNiJjXavK!_O9W7an8+#`-?
z^=;>9ex{&c8yzLu;!sRcC&rNK$!Z-5c;Qgh-Vsn0Ac8r%MD;=KNy1qd$%a@nHQ3>&
zRK}99QPSC<h7KFB;e5-hWKz33Z%llBPb>?#x9Cft|6HWyD}doA@H_UyRtCS?dQONu
z9GB_j*owtWKc5`1D0#z&h-Jy?{rnFGxAA!zI>SMWH|Po!e@gZ1wqR6j82KfV85uv<
z;WP2E{8LnfMl?1e7w!9&|JF;3ukI^y%7Bdr_Z^D{#at@^N2db^G4+#!m=BKRk@4I*
z$H)FU3#E4=Ds6BBGA+lMwxye{(RG{67a+FEF0CvoEe{&=?^ws)SLcG=ywMi#y!a~j
z&g8!IwUybI+lU#JNFDkTJ<ZvQ1oTOjqS-ca5IVt4U$6|<2ov;NP7onKYxj3<(0`mG
znKN%Hq!T7H@Ht0TrPsFscP@6bVQk)CzDzjx+bi8cxGWHCl0@PqgRIK^bevhY!*w^6
zs<a(@R#OHs+umtJbG8~>jAqpM>^^46wrMwP47FSjj^7@IxeCKphsd>^G7GbA7<CLb
z;`5ce9)DOiTsg6WHh~1TG)KBn1odb<b8m1F2>O-fk9$Y->KV4-aE(p7L*<aiEDAw^
zI=iKdZ*jBgd?`9i>9|nUxuEMSx=>iehg^#Df}QkUQB|oU9Q>&*I8>3rQbF6cKJTCC
zz?9~p%Dr@ro&Cz9Py;GfgfB~v8=ggT!RwEB=|a+<V{Q7b_xhn^dW>O39Dw^J&XZQs
zjo|&MSml91YS*WudQPJrQ4NvX&jj^i*Qcp;EQmCxy70c7W7O)^QbN9<EDp2dRogLa
zxC)R7oijZV8-pNm|Kv|H*l~`Kl0^S+wPBa-aL(MPIxzFf!0c_VB>=N>Oyi(s+VOI%
zR3E3AxBq9XSJP+%Ih5cLv}-jSnGhf9fVaW@e33`ApQ-1bd~k5sXh%qm0!yM_pvNmV
zQ^=w{GtG%7A%(%G%@pi6<0^Zp-vWoiKlzcA-CQBp_a^S!^G7#R`L0U<Ulh3ntEDzx
zZYMe}=f+T%e*4um2Za{I6-+4`20_*%fEie0geId($G_!af*ThnGeIIQUHKjI#{>0=
zi=zrM8A9ce=?G%4FPc@_QOTpt26zYVVqqiEMEPGsb3zVm;3TjiMX3>lu2FEfT}X#q
z#*5{Me|a^&>8T10uW*P!rgz9SnW;Sz|Cp0&8V&vJxP>(mIdKkq@JMH7h?jcmu$yr&
zzipw4K-eudz#f=t7V8rpw}2RL6$PV1qlCbv`=9WZ2|cABr@6nPWMjv8u76z(-Zaq$
zP78qTgzPs5=X}qV@jqH2SEpZY$a&-}c}$HlXdY%wKJ?5y<uZDh83@PWlJuI`lS4-Q
zlTI3EsLhjVKav~R2F}D>2G!VaT5ODYuGnx*A3K_Cp7eeJFXbi$x=;Qg<V8ehzqtiO
zoVlDKp;Jce1QG4=fYy@Ow?l-4WVY@y;b@8j)l1QFaP||pNYqW5RZ4u>t98H3dVOqv
zl1z4G-glDC4U+TL_2-$gdHC}Vhu`Cct@S4{vi@OU`j*75aHh1}X0%)jHfg;tIRGO8
zyVKs?3e#Ea^~yy|$JiUAYlEACzI5c^H>vT{SP`SKGsO3=d*8WIH~wy}0iZD=FAEtz
zw8d$QWPq5Ho43nle@C(2!ov5Wh0gVW(Lgn@-tX(y(^zgcST!KzhH=4-Waj0f+Gi#v
zrq|}8A^Vk`xM#TynWm7c0TL_qRSG3cJ`9lRUUoikkL-J#=CXp863=dRfmWVF)#QuQ
zklPe<VPEB38~SxTZ-3%+d`32_F#!!@`~8dY5L|XoX};Z0&{~Aedoe+pk#8DDjL;9%
z_NJ_l(HS>w8CF-m@W#0+Ykd8tq`doFypu>ib=f_hEKzid=>wQZE+Zp?h~xxTIYVQg
zm${PZgErhpx0Zh}Gn(2!NihnaZ3ppmO$%e#>DJjE3ZsX^-*Sm}+5gthF+nn=w<m+!
zIu9zX&dO?yP{2*hQ(IT)`Hi*~C7z$(J7ptzO`dAIIgPM6Mne62g7dKS)T4$ar097A
z@<K@csb4L<#yOmR4YC%)sB=R`W;!Xk6fWWJw6Bs`-y1Di2bpegc}8JnTax70=t$X6
zd2MEwt(yppOm{&8*%TTvN#4i7O{8S!PD%YH7qDqi>dj(Um|of9(zU^eH!%LHLLFg9
z+odZ#J+0?*9WB{+7&SVZHTYIq>N2Ua{<RZ+?=yF*m6E~GvPD+ZA^gMuZA%vqH9a+=
z{WJ&j`FfiCU({h5t(hL0y3l+8fzkK&R!ENm;kFagL`SRkxErR>x#J)p){wbNNt9#D
z9n%6GsUxZ~ps&v1)OYN9M0<|_{3WCIG-OTTWjzdD`_+ONeQu;JQ!L8Sqkd~Qf1nKs
zoa!farmTjp2cN{#kIC55la8>ENKb8TdnjScBZ_oTHZgw+<jg^}4{6Lu4?&mOX3DxC
zJ2{<h`eFJb{>}1K8s%omaCSE%mhDT^ZhJQeUcO@bXQT+V{NgD)BwAe_zuYc<(iKR2
zvrxVv7bkL$718RHjN<#*mq3#;A(PKtC+N(Z#{qCah+z0xCq{TMx4$h`War;NSo3|T
ziN+wKVO^-(&Jz1icsiy_;WM<C#!Kj_M&^Fbr2<pw(LFR!jJWBQL(zkL-}L010fPc^
zo(W-3HP(w|B;{m%6P59NjZ{H3d%rIKHxd=oy$Tom4@fk)JAtQ<$+=F_4x4)>pABK;
z$UC1YU~{ZS%%3vKY>0Sg{SUzcyM#6eZpf*QsjUm&Q(*<Z);9^Xg>KtP9wl6#JLh1;
zZTE}!5b@6)=d$g^KgyJA9XrD!F6c)2y5BB2)tOnFQ9f$mB)IPRk4gc?7TvOYX#{u2
zGb*TQkpM7Nzu@7kR)db)%WrOHOX%SdyH$sr-@8#qS!3+}q$=GEnMNdy1$v9<P#7B(
z>m-5EpO0#jFHW|zF8Xam-!fZ{JJTaN(Gqcy^ZSq}Y0XuQ7<}Qw)_?~6%0ZsEf@^;K
zX>nkBNCdk{vHhDHfcEy-3j<eddeQN}QHdt>5EHIA9pk01d~a*BSC$RyC3$v4Opyi(
zMGzP8>v#@K^GL0~&`T-*kU<pAgX<ytmB)|8%xIOZhj=LXz$J|nKFE683;a&Uv}djq
zhY@4R2Yb!d?c+x=ck)RxkzhTl1Dx;E`8nJT*Kg%Z2<b56aLQCGiBxyT8~3Ef(FMM+
zt4h(wn3%Y3fAvw|i$83r!qyK_9dMj)iIC&@$-EEMxx&p3W^)B@(T7B;BDCAiv--5|
zfdv=mDNZB<2!&5ij?jlVwY4_g-xtZ0c?r4#*K(1~1u_C=qFk168-EdpXSic8soM#m
zrvL=mJY{rIO>eC+`P(*5R=u7EN%pRO#ZUQ}ts(GNZg-0u8Xu_F{}~;6PQAM}vvc~~
zw>Uhxy$m8Uy$FIY{+hEjG%1M{!WdWO9JT50Q7h}f6?~$yj6=iEW>7X812p}FjPsaO
z>HI3#-aXw;tpxjV`1axe=qyJl=y!*I9&}?&yd2$W{9U@NH{6fyi6S_gNjFpP?IC3Z
z$~nLFw8VT`@C+yG0y-r%XJn#5d&|!T4$9YbI}pO;^Cz^&JxyO!{6-pzee%P*F66!-
z78qAEZ}gk1^^m}Ie@8eLh!j$-`A%|QWo^aU)*&dp!*NKze-LLuB+Tsb2}>I6FN=E@
z?_E+({MX$dzVK!XGhnqQ*i;BD5<TR39u>uZo^t`p>0URsP4>Q{p~2_Li}Sr$5xf_g
zxvImgSGPAB!`TiEzBO8?SUW}K@lT7XCJF-YXJK3a!<SnJu#>5e2$wXGcfg4X@pN^6
zTf8im0hNc&y1GIQM+auOu#1Rxdf7l@Vs!}6sGYG%O9;Wj&!^Id7=t`XY@LX=O!q9s
z{h(o`Bew%88B{XyiwwVes3|_Xupqj|jJ^7c*37oPENWfq^D|rY+k?aIJ28}P{bhDW
z;beXQXY_SZkA1n&hX1AK{BL2-XzT}gaT@+50>SSJ(L*K(nc86-Jkm_*exsJX;8LB$
zUa>JFB|ng(>G28g5z4FS>eRKUyy;xmA(2h;z^}3EJcn9mYTa>I^<k2ERLaW?t1F!_
zpL>$3F!7A5sCu)$%y$0dOQ)Zd;5oV!Ay##A6)*Zq2dX!OV6QvVEKv+s)KXqceaJXL
zdu;lEbkPZmFZ#Kx?}g9$pfZ(ZPbyeA(3s6|%Mi{*eM9Namt}=DJsjP-jME!m=`5)>
z;cJ|xBKGh&c>{eGq69XgM8p8>0DHH{y`jD%!eFk%ge3q)wA)`u^K)T;i+DuOIKQsv
zXh_$C)`Qyz#}sc`=wvByL9^Fp%+g(Fp5>@1wVU@2ayG(YPgNHFrog;o30QATqtaoi
zI{rnA1aNHb(V;I4y1%nmLyP7)iw?dS$i+dT71JjxUcTRhY;a<Jdj1~#@z1i~<EnDN
z^EvWK7>-AwyZD$V@JZZcDL&zE!jCGaLzjJu0{-Vak=pww@ERe}=50e`ZV&O-wG_#%
z-Fwjp@TmgFoXw0;v<cwjvh&@*POjOxvIa`P{pPFKvVu6Z*&+E}+(79ctvPJ2RO*=U
zF;PQn8Q9{nhl^dphup|HMFl?unJc9nD}`VqHoh|N>8RB*Qe`Ajqm-sCb}gLqV1ZoT
zDRmEZZ!+vT<z;ILZCI+|V`1R!Bdq`UmgGUQ{#8WMo!#R*5&ZjNc@yBuM3aU6sgEs@
z@QrpIS5HtqsIK=U_QSxc)y=HeIg(8CtbMn3uucO&HP^A@TC-?)zK8bE12Ivb!ue$<
zQhN1|?}q2*{S9r;rKhaoz{RCOCH06*Am1#rhrP4ZQrke1jHf?xQdyFK@UOL=0D^^r
zy|Oa7ZASnGT`+@}FQFG*0d-U&f_{zG<zMip9C@;<@3awzW$H`m)=Y%|az1kp+g~64
z8K2w*V<IerF7+)J`L_r{M2Yvq9?XyP)Ub^Kw9ra;$Z;PfwG=M|MNduJ;)AfS=fHa<
zIE<Euy|=Q7F^vHG4F50X@h>sh1=G@_+LGwnz?*o(FbF1vx~RuWQj9fCjt-Cw0`e-S
zn4>k{6fR{uYOdXQEf)-2dQ1&^J>W2rF5~OER`*;#`E=fU;1O5mvKvlUbuPeMa1SVr
zPqLZ9##~;J7cE%pXz1)pS|C%b270y^QdI?XHL;0Y;9LRf*di;rDAEUE7bHt}>(;k4
zSbi5XM^p0lzqP3m!?D;5xv_G}(xOWyjvz41SoJ)&!`Akp;)>r)FXLw(%>JU4Ch4<{
zM%~R~;)Yzs<7Mp*y83Wuac_n0-igaUZh<akhyYlIsH3G6HFn$4#(uz!ywB47>a@`w
zG7QHR?6Dip&@s{JUdFG%^NqJ-;GmfOnqRT1{tyAS(6o!Oza)TW_2J(cGA+_7La6v(
zTBMDnR_}VCowFtCHM>v9SsxogOLc=lUv4j7&$H^w=sZ{fU7mC_<j>jUEDoP+^gp8{
zV8JFpV5!^=++e@yJ_Rv@6%O4_vu)<3{I<U83kWJWCxwldcy86$Wr`4exG~*DfGBZh
z@l+}wfx>>X@{UM%*!2M^j+XXh9VkYk-R3>wsVc%HL$oy~vgD*#Q)i59Nve)H_?Ggi
z017B24orG!K)R6y%PVgE;VDWSFZ<g4x07P_oyE<n*2dakHwPfow!mx<cYVxw{0N0#
z&-Juy2)oulRaQ9geh=X8$mzO%(Z-0(OfMP)mU=MuI#deWM{b<>Asv|pceuMtXqjKe
zBaF!>nVz`)pP|aQMZLBDOH?&NxsbY#EUSna83@o3Uav2ycJls$L)t5xm`dMDB+#Vs
zw60D)-yk#X=`=eb!4g0Gwr(umq%BFJf~0loF&mzrGZK_+9Vo!Dj?(x-5KbvN)1Ro~
z_G!4e$h%&-WzkBPwTvPRTK)0qWS!m6ov4-wENE$xM<k^yj^x&@O<}bB><T&i2RkZ%
zqxYRu3bX;4zj>E%lWsS;8C6kA^769kOS?3uTQE27$S&G8WAyy4k_*ievJ7T9m0|E+
zE)Bazg!&0~7&WeG&v_N>m?28oM!F+)r%cE*tDGTY<ybvGZkw16I7Hqvmb`U!x%m1}
zPBDt8LIr*6zykcG6GnX}W)>E2Hq<%R4y5Bjv5mjF_gDY0dS2+n=r()@(1t?y<#3D|
zvL)li4XOnpkg}|syFR{ae-)5JDf%#u-;se46~&Y}c?A1zKQgRxRNI<3d<w$Txmok~
z*p7ESUU8CE)u%V&0jI5-7jF3fR9W`%3Z^o!Km7s-VmY;jOQ|x1w5PnN{A@~_7GUpb
zav&Qyu5PKVa7d<(fuc;|<NouP@S(0)EJb9rHmq-&Rc*iGapkZQ69jy}p@9oQ{Y)WA
zPX5fLcUfiK#Q5q^li&_3JUNc!9KA;gBTl3qh=l1wdim1|SLH*EXyc}15Jhg0>Mh^J
zxy><mp|DWVciFaysW9CZGa&$OPs#x^B6H*#E;rslF!U&qbvBqaJd#rA*XJYb0QP%y
z<0fm+!AEw0r@G=gw6yL85=z)@u0*FVzY+LuQC=(99&o6DDhR(DDhmj;2b=uvBJr2^
zrr4i&WhpmFWE~r2-keQI&^$>|Im-_>Y)r`&`NdQKdxE))yYT;<M%+kOEJiQ}O%vQ?
zXMH%(Ce0b2YmU6J&HGgbhYiL2Y#BK%xJ_^L5l@w-$Y7$28Rkr}HDc{%&FBQ0!k-8!
zKa|Gc8xAjTFpCq*do*^dM*Xh-@k6tInWl$BXoSHJWJ558a0I&F+AY3cOHQ&adF?_c
z^e&&f{}5rbm1xp~QGE<$Gqf%9-i)j#G_eZB|HK=r+|J1+lB#(3hlUrozcrp}kg6G<
zJLu6dUF?a9<^)Hb&u7s)agJmxhL8>B@z3(plDMoZEuyJo0x|#RLClMWyk!W7_Jnvo
zC--MV+2k8**_Ftd7JJsUk-pLDV-I(5J!%Fkv(|(GRbPnFoBecrU`9uzfv;VW8Z1?W
zyVTJ|798t7IZ}EztLc5FMI#l%PORI9CmTm$e*VhT0-;-PAt-1YDnlzzZ(?{;BG)ob
zhY6XZeYZ|aMqp1hU8-LDwOaTg*EzUSbB}h|2aQeo5TI`VJ}1UjoJ-mhQt<t|Z+iPE
zw_kw?AfX`s6>Z@(7_~2`7VOV3cD+U!;Yz3vC+_NpR*@#F|L(uq?9psN#J`f>9oLix
z%}^|Bd5bCg3ke+3@NZ28a(u6d@Jg>~(98cUmK|Z`z-6YiHC#euCgy`gWMUWv{?-vs
z9fLo61ZOWipZ9v=)gXuL?<{zrXQHsE`Qvt`t@hmJ4G>bl=Kgxy{v9gTcF(=IG`bG<
zNtmah5VK6UJqvvizptePM|%d;&v>~&K`%=R9h%-tO)8!^H}ST#jx71BdQaVCHH_+;
ze@<IK9#{8HOR?Z&-SRL($qRs%$XDraUr~+p$yWL9=g=V`>GttojB_WtNK)mGOB$an
zcyxj>&dDS7x`?bVRk9<6Eu>vYgGYHi$0-v^c(}tsx0qAAeLTbDFpuy3uZj)(L?QU2
zBxf{#BjuU5CS*c*ktsA_Wl!7dcfdo}br#-NY*+vg<4Ong%<&WO2*CP&%y@C~w=e9J
zugM7u_I<mY`F+Y;jl{wkraW2L*Jz7Fgo-){+rR#r-`|aA7m6U|qSN;P%iD0@$a<o<
z^R@Ras5TG~UV+OU<-qM;(anP)#t_%(+M9w6V^7kBea(=b(kWSCyU(vg{<Lt)1!8SD
zY|mc7<+SG~J%Q&F?KcD1gM$lsMN#Qsm4tcedFN8~zSz-|WOz8YO98uc1=x~J@xc+P
z!rb#a6|7ts07>-FIoMlbqny0L;kB)pC`N;9D*p<d|GO$-!P~p-{4xPegv0RYH|Z%%
z&gXDm5Z(d4|BtG-463VZx&U!^y|_bg4esv2g1ZC=?(Qx@f(Hu@0YY%+;_mJm+}&YL
zp7)!onJV}Jb&F!})7@wF>ebyeg&2eTezQ2&G@9#>y$2zR{fdG0@BwO`gS)>}nisOf
z(VYLvk-*LKY<?fapUn?m3WH^%m&vR*L5aOxv=q(z`BrB4nZoy^aylvm5;3U^{<lDd
zm-59pZbXHT+S<^*F~~PGhz(l%g7KF{i;7!?3E>}Gp9A`eJ#*~~H?tKeFBxMA)reEx
zp4^a8QEhh-xTq}kuo7NWyAeYB-`X6ql53pQ(Necg%u1g=x+tRa+l+W#x1c+aX0>^X
z57yXSnDCS5pX-4do=8>F83KuD+k!OLVb)xpoS5qUW-d&YLMkbfjT8OQxwPDLyoi)z
zi4sk8pie}gcW7thq|n`2BEqmEoUW(m(%rBDK!JZ+3P*At&GbQB%9W(jlF7^t-do!>
zy5ltaJklUPX0sHS&=a$Ug<>py)A}jEJ2L0FBY9ckP+@2}k(0kQkE#tUywmO%FBD_q
z#Er#G2BGeon{4-5rka0RLRR1HPW<p2zCU=Qx{yt!*;|IeTH)_H%}M}@>++ot+3l~V
zwa@ZZeD0BuX2juT?v{U}r95-cN!c1OYdEu`rJd9l97~^hkMRr^z2H+J1Ix44-a0E2
z)PmX32oi-ug1WeDF!I6gA|1DENA^ypl6Yc^sS&3s`<wQ{@DQ8Qh~tS4U4{==h6MBs
zj>oTlHXM-9ArrW>MWHxYu`U;&g}|NJEgvW~xLAjx$+xyj??#j1T&Vq&KnHjb9cTFT
z377jk&uwI*_x>6XRl)=R;V;0bCO#xbKg@$4uoWl9P~ObwFAE$3(9f$npnL4?O%=Dn
zz=j-%oQcaD*7&>zLW8~#@Fl@t`NuB1fz7MiYi->)7WJ&0exPR`@A;PK=pq$)ruLzi
z?rg?1z+y}@wagY;;Mhj@WFl%Wu!&M>yDSXQP>@5&Ns4LwnU{3>B#GQOABY3NBQx|!
zAQ<Rwfb68{MVhS_Xi@(BRfP~0ZbNHfL<voxYKt%-kabr1Z2E=iM4!d$8KU7x%7TD#
z-}v%@o%xPOt9+QFSs!vH;!FLa!|ZI5c*-fquM`eoR;?V7TQb~4eKO~Ej>At~H<J};
z<sbd&7rz#cOBZJOdef@(!>s8<tZBj|y)r48Fk#r2>WFQ9pd!(_q@H~~lT^B*lYkF^
zx454A`<?O>EHt?cj)5bdNWPTAj|BJjmKm+OiafK%>6kARK0JlV!xY*F<Wz6dQ{gAF
zx(7fZ+E?Vsm(?M~gs;*`qG~ZPuiBT)m$h+0*ly7MRct`C<n%V>v*7LPIgR1@@HZNZ
zjBiDsN10&a;eADvE|pYnP+qqQd+HpYL+*Pxk~|cBQ1KmJuDr;_XP65mEe0aGMhsRO
z%NtEx_7%77<cSVF?#nMcHW#Wq>{=g&pZ}zrUfIgdr)nl!q}tm_L_0p$w|Fb^Ac^y9
zm%VZCJp{l=`2BqXCPV2K{SqS=|Nljrc;ncu`?uZP?b+s9iPyK1jd#rTfaC1nc8^)T
zC)<L*+&Ws1cnMoKf3kfh9PU6GpHsGn>#UP@x{|@%nUj;}9X~L^3Sl$70iW||p&te+
zpyQfsJzgO`_+am@CB=#(A<%c?CPIc&XeOf}I*uFnY45Us=om0lk{({;rj9elm{w^B
z<ota~m_RWl?2U9-J7JooMGPPWY}%aioC=(dz#HE|3QDB1NbEv!c~MW{!jzYf2dz*X
z(o}?~T7UwKzNq6*HDKQKn1pj;{VrZ-QoRS262rem=E|hJJBU<WyG;L9oWHrf^LS_H
znv9R#sCmFdkxWN^2@)l0x0_;iR*fuDmm}ijFKQ;3W&FG=ka6D3cDi{P+2}@SxT~V|
z>^jwaE>`B^YUt9z`lr1<+q1p?m#!zXAdjme6ZJ;Smpqa03V%Aq?>|mV#{M!DAY|$z
z-bd={61bbaj%liY%lNyJ1Q|4gC4>agc-D=7<l+WulST>ZK=(9kB4_%xA4i97BH@e8
zc_KokmVpi5Z@lkZs)dagsUiuy53ocXIB5TuR`jtcjiM5aZGFQx>|zbLN$NONj?2=O
z%rr`#*xcW(^$8g1z}1BjGmksd{__vwPSz2h)eIa0wa16X)0zXP?Nh!hnqwrL4fl)M
zxQ+XjlPB4EoTlORb8Vw%J+l5C1ZMG*zQuc0>xiTCx4Mp*_U`t8+~;TYlFKjA(VK7Z
zHH-JIPwjRA9vc=HbZEtPTXCP(Id%02XB>IX4w_TlroH@Oft*9KD0T3A@g$``Or9!2
zhf%}XOj4GhnPVz<ZeYTYO!g=g9`%Q`q>m2$p8WP=S~-0U56sjQdpmFu*$VEeN#@Tx
zS=0!WdjC=-00o>-LBad7H@P30`My_mkfamUClE~_Vo~~WOQF3#_2a8zlKcu_7xh>A
z?}{R!<0KggVK9i@D3AO)v|@kC;!+AUcogC-Dd+{i4dVFy9stI7tljou=?;?mRJ1ZL
z6;{cPEG;n>%WB~)c`>-2xg6`yp5BaUK(#OmM>FM@2D67Fql-WYi1>O7(<{zuokfIB
zS#VZH;*Ei4T+ZOfm}8;E>z+ibI_W?BkhM&!YaoGX?sLB-9=@H?;h|!Oa>K)>t((LO
z;tb_K3#0H*F%}_cX6fNF=EGa{Rzvn56q3j2{eQ6^8m}G^(L*Nq0sTUv8)*-KK_@l4
ze2Z8@j0n^~#WT`LLL6c;MLY_?iJ(-W2yUC#x!`(|^<jRT?dU(J6!|gZS58v+W8G^T
zP7=%=rwYkahYyxd*_~o#0^RTO%kB=Z6^%S~)9d%+l5q6PS_pjR3PFWE+}>eIAudn9
zuhRu;BBkqvfidd!pE~cae6rWwJ4!s(J&^66z@KK%Ku1hJ5)G!2FV;@Z?Su3MT9myx
zs+bZXG(Ch<+&Hm9I7v(Ej0=kUWeIZBBxCS!A9;Bj63tlS^znI6$jb(Qu}@<Iuk6yF
zvlRc{L{5QDM5r&|_W`4P;zWUu=l`G`B{Ws>zsh!hoKx14aw2lPFvLop94GLLq~b*=
zk}|%Qo=3(2VEE;5YDgVVnCy*vl>67jO&q*zFrqTg6hPh`g*BB)cpsmXYBk&|;rl$V
z)ud=1q21i!AKN2ulfCDi7PP+iOqU+ile|sI`G6y8MLf(gOITKg)reM4)h~tzTGX0u
z3=3Kg`1dW|KbDUDZulW1dX=-2)9n`jcI?3PER8=Mysu=r7Tvq~<&S{fzb+i0vYSNm
zXu)+6HG3-EWktd-hJh&hzmhfYPg(j)kN2%Ar{m>sgU-!@h|G~6KDZ%>#gf3Ac<IAj
z%b;(~7`=1s#gUHxOS}M@lE0}HAZjQh*jiwaYVPk%l-rFVVfjhk*aNWdNVE``gR|Cv
zoYFTCHd@d-44+?$R4A7vFJzWzjy!Hsv}&i(Xf`pmmh50{qU%H;jF?5x_kEI{A5xU7
zSVa$vF?Ihm{<`_9B)7^L-fcwTBPIQGAk+b`Y+Q|O#v=cSUTZH6G#_Zsb`JgE*^$Px
z7Yk>;T)FU-G2o)1W^$tdTnzSqN{dM7;ZGgU)ayQ{%ofeWfNkdgd#vo?#J$$5_F3Yj
z=mC$lO*>sa96HqiJBca1IJ`Ih0YBumL&g>JNafo)sg^6|9m)P>Z=(*MU(os;yg=UV
zGWzjI-JOu&52+T@2&OR7OFNfwr~3l*?z)Kh@4G(242<^@@>GQrx8-J^_uIL9K^^gT
zl6A8CZ3R5n5;NdHvr3D#SjkOkM;I7-I-7N-*2}~oX+NZHvZS}||Kke#|G5r18hO?0
z6YR@TS?&NsW=SNTB#ffkzep=BA&)F@bsSao!8CTO!H0FTy2=mju}m%hAJn84tJ)MN
z0Ww_!g0)6d??y_4d}Ltjiw;vB01je*HXIZ#G-ss@Qt2Q3WdGH7cDX9R^AuNQuN@mt
z`gEUp>lfT~+JOu#b|o3Q>q`?3c2q!0j5-@cdhL$Zh<gV8LJs}A=Eojxw;B&>i^E3V
zkQmnmEP@IfZz@<x_Xs03TTg`}T)GmDqTl2<pc451aA|=~him8;e~kj@+#j<zb)cmw
zE&gMf$gp{>^^@*R)nAZ3Wrf!UZn_19Uq68(%^I_n+w1{)ks2Y|5z~O1fnVGsIYxO(
zDqWTmaVm_#4M7)d!`EQZ*iLI*h>mDDSLI?6aC0fIaDa(5l&|jibHu%>iE6VTZC#f1
z=uO1+iZ?D-fb;v@h=Wn@aDDxt3rqVAF2z20d`CFE45#n}x4^otsQOH<*BCV`JpfB;
zUw&SR0FjikE+M_bi*vko>?1wRWa%tLO`LDffAXb+{}Z>+!Xb{!5QSE-Fz>uS-@o(t
zioB600J(kQe<31aC~NulPax{$glb~0)N~y8OoQWwC0W;Nt`G4%0!1fcFnL`;(<>@r
zc0Ox;<O#kUxxGPlKJwBf2{cIS8vzvYYI`Cq+<E0<saom*p1=vBk$Cp0wdBp9^xvsE
zlKPFqDAeVE2pR05wCJYSE+6Td=K6-97}oX<8;5)E5lQpu+A1IM5}Z)DXf9cuNyV+;
z9J5b_u=}XQx$o?F#kskQIXvBJ5s`@4x}c?2SQ=`=IYM(no^Ceni_3o`Qs~L~|CqJj
z?FN?xGezTY^(Fcpk@xd={I7FIqTmq$z+@>C>MQg_F(k>7d^fmN5_9{CU#K4bJ<G%y
zx{JfA07MrVG#W!5pjJuw;RThs8m5pk41u3y6v%njXK76Gk#Foba19;tSW~jpPJS-2
zuVf2{xSfK>WeJsZ{qQj7#0skD74jrz{N2Ul|Gc8sIDlx+{9h>2_pHVn8~tx7LotN9
z3vHiB4eSoU9d6mr8T_9ltjHp6B&8);v99|T98V5_odmr71U(3HBpfC?tm6X(=S9h-
zTE__)k`0>>{RLzQ!RfaDm(F8%W^nR2?v0M+1)TekzU^(i(#&fuz`fbA@cd`B|30=e
zAe{cueOJde@*NA+m-4d3r4Neq@yKDbo9aH~+YmJsa8~`6tWbmCAj5sP#sjDWk3VrN
zEmr;mv7U@xJx8bCe&@xA()q+w>F1tq$|6};R%juT+(;*@09rgnf|=$@@cD#@BYL!Y
z0isZ5T+bbdzWf7&=&V<oG*SO~n1<}STfi*qAIk0ze;XZ-#$7%rf3jFh4nj~Op`>HV
zhb78&F+vLRuFNUrWz4NAud<gX6337fKN)g?RYc$$9Fr2A)#{3wDk4nLn{?SQR6iOk
zGzz&G4op;7ZE@sDu|TmE>z3SRwL>ws)oWK#vK6cO+q3OlT{+6%uNq<k8P1v1<Ts#N
zm28!qM$RX3#d_=ZpbdXjLaD$WAfd3q8K9@r?_k^MLL{r7I0ON%flDa{x3t6Tc_tv<
z3xyzWtii-S4mx)m%sG!efBS4fu;m~wpX0g64u^Q?@L}Zfn_K56Ly-X$xHg7#A$%QW
zF7BHfKOyCfs-R3XERpjfvhs5aGlPlR{*9mn7Uf*+{xy7-f_VgQWln?uc;oT2TyF1N
z0X6x5I4q_-&Axu5uS+k)LIEWGaGS;2<XE!bLi{<aXur<%46aG%U@3h(P&FFPH=yKv
zu@>iE#HO&Z?RnIC!zXk>-=u8rw-KOu3nsdVqbaHqf~gvEhbYHT6+eH|;&JHw*t5|e
zI*yjWLcaEP{2Tk*LLd%{V475iB|_yg8)7Ty)!$|}deC=TbHy(qh@kmkC-<ixBD~(V
zM}pbDO7aFQZ>JJ`cqQoDAJ21%64uqYFf$8ZPZ#8rBUeuW!sD^)A9R8QbTlt5x)9bY
zq)mf#fB+^<7-b{uD`bWv&u!a&uP6A9sN8rp_@udt4Q`P(!bCFHMqJ)ACv@NAoEqET
zW%Z}%Q|8gNA3|XTL^o_~<PHN(;UZiN11Gh<E&WKkEm5kv>{||tpJVCi^BKcmQ5TI%
z<1=oJdn<Z_hg)V(!n2~BMyL-gbd4=2hn$0f^{Uf6?zw@L4Q^R0mG`XkwL(7yj~}$2
zH)?h)D+)5ZkG=-b6~$D}IrkbuLJ0_&2ETdJ=m+|+c~NXWPqBHDU{(5|^EY7KE;BI6
zFu3%i`+jjmY|3Q&R*>jpu`7t<b(1x~21+f#apqbjX);7rq!lSqsrpSHU%Y=F7({ir
z!;%5d!U%!)1YUVYH|8Ua%V{Q(Q6`J8h<A$Xo+TEfGkog(vf;6OB7&9!h8`#A>~=uw
zxj`}uycqG}em=HBVgZ$R*WqHnOr-|%jCdy6!!`6Pfub!rku%b4iqWha7w+e~l!z)U
zS?CXb(-jeKl4wCW?OlGg36y>NfxT|5st7L*b^9aqJOaHXR2vS%j~O!1<Oi?!9kn~R
zyW{l{b7Um{PB#U`u}$FiZJ7#&m9hKgQ?@v!eLG~y;;Y_StTQSq+zuX!fHp>d-klC4
zgoo|l;{1It`2PFE+S&aaEhETtlB&nR^EuTIyQZkSZJm$jch5zqT#jd}Zf&>oOTVpj
zV!bv?p~9gr{ua<-!8oxk`5a&TvhdvX<k<%1h?J5^>k(mnJ5_+@Q4HH6?xN_sZs9}J
z4z;SFv(MH03K<k{&1U6UmW-m-ui|rM&Gtzsi2XyiO2pE~Y=W$o9Ttd`-qYuPJC(}p
zN)28@n>4IORQm!~Ju&7h_Agy+$3rVTW^EAFSPeW46zzYXg~6UBHKW7dI9A8BfKL`g
zPV*5_U@qTn&O=Gw?))9wpM{389}Q%Oq~Atu+M$GWlmIq^rlNWZG-B1GLX2jKSx>1d
z(>nR!<-1ckJxf#QF2X>h`XR&>P*vq1G6rbtL@&9B-pX&!H-C&b8~D|9zdizioT-}#
za8BK8ZnH4GS+9>t?~y!)p8gkb>DPk-Q{xpGJ^PLWB=H`0wb#&*eA2x?_>tDH-@4VX
zblL2C*yJyKh(9JZd^f=X{$*8z!;bSsJo2Kzag5jwHpkl#y}*M2k1>2?jCK6FB{+yy
zR~)JRkjeAr?n@qqwDo34kNuv>^K-wGqz{TT=OCCLN&L;zD20vKy5Tml8T-$j(<$+k
zBY&@H@#2r=kWF;Zl(R)Jb-sM{FXq$9!9-y}QJ)YqM)_lhHW0NAE<Eq~=*8Oh?L3cb
zH($ls_{Y>O5%gbTmT?@XiP;Iq-KX}ZdS^JXai}j7kkjyzW|PH??8NmFWAscvH>t^l
z2JyWrDob;hR(}K;eR?BF!XN)I0=nxyYjwMSu7^<}Gbv@BBIYR_#6|B(V(cM83erP1
zX4pcr98@9+zk!RFF0RW}-=NAqG#hlf^|@e+q`zGpzLvjWT)=7^tMvMNw|d$oYhrxZ
zugOHW)OqLP(Zdf6ro4|?G}J+Q8E3#vSRo;WMWVTT!>4VD#N(HYV)?NF8^baTj3Jx@
zMn0aUnUM8Yw+4U<5Zebtg9-RXnTR3H>#WQ`D94TwA@wr8b9HgL876-8k4_{ZK}&sY
zYQ*jXuklcVk2a*vcr~O3p#_0g{b+(bkIjXTed_Xg5f`?esJGksK_=YJO!%Hd9?_{R
zf>$3-g1uP=>J(QWC)cXA3>Dbnm#m1;pHi$RI*0cmGhTec4bnGOCdgN?M4k3Npr|to
z6XWzS<*Co7;ABBJY#VSf8S5}UeZq$85r!G4#;E!h(za2f?IJf9o#WM}Z<q_cbT6pi
z`amkk^Wx23a@J{bYqL&Tw1lO+&#d3-iMU%ibq-z3S(NpS*LP)YFk?&nn2l*A97h;0
zj@jML;UVHr^2;e_6KY)0VY4v};z)MfXPIh^-qZW+Pc=Fafp%V4ZhgBN^qCm-o7eu9
zGu_*lRC)A3z2!l;LGvkKBGzk>gr&AXM#~r^Y#8wB8?o3Otey^^q?a%{wb@LGuuU#r
z1}HfJae*SA{~a%>=K+#->7e)+(F8cw=%r^y;yq_N9K%G`0lB{D+<XlsnB3b~R`Y_7
z<ssO_#tyn8?ZqX^C8(Cps0Uc$fjXk*nGgK2{@6hcidK3t@{noR&=SnZG{eGIfvo}T
z5V?~EshW2FmFI*nPq9C5aIK4-4&D!F4WG~q8U!ZtHsh7M;~sM!0vC+;h3teT{jz+P
zt9^tHsJZOq2I|v!V@=$hkPfrfE-}A*tc65gcDWO;x}O{H`kyHlCJDKSvuO3x+MF>}
z!petif7Guq1mhC0TVTYI8TG&38=+)rrTmkNM~0IBPiYWK5knWZ?GkVy<tY5JxxItV
zx&!}yxI(qd=W6@Ik36_c|J5UbkkS%hP8punt){x~Z$k6n0+$YHe6N0&u=BX6XQBcZ
zmwkhb$e;ZyB#H&&Zp|K&eq{quBuAEc@=L^lc==9k{W*u?$)s!BaqY(8qO#EeCe0NH
zJugCe1@n1~`lQV0TV0cwHTb&eK3ef7_<d!8`Iry>R`o}Y`0sRI`CZk-;1ch3>=4d?
z8;mp03q!?$$if`htxr)ySi0ufha5<aTc*2Dz{V4fDbsjTgFdSGHq-*v*I#jigFt0d
z^8di7S^r5Mtncop0Q6L$wia(cFWi7@hj*+Tp5@No20Gh6vW4LnJ?b(TFo`5trw(~x
z_KLMZ0uDZCjoIF~a0_%tKpr`%WIh{RD1}eyFBwycK*%p7V$i^!HP*h3{Cf9HC0Hj3
z;veG3m--J~m-;nCS9ShL{kV*_yzn+ixP0P)=rfHC+EwtL2E|1~d{Ww!K#8~3<MmrO
z<@FliOP^2Y>ye-o`vc?;Y}t>(*qt^_+U<$@<}r_tN`hB|dVfyG`KH+g8UcK*ePA#C
zuUuv(Y3)vE^jNzQp^h-#2#V0Hj|M-+yhnbuxUmh1lTt_DkstDhof&s|UCD+D>~i^r
z1ygNAo+pJxY}gcgIL)vQe!)1()M*R{ET2nvd~KciG=PJRD@53}wOzu0<~lo)xennM
zPpQ2SSN5=2L%Mr>KwY}n`&&8F0d7Vwrt<;r5{${NaBzx`QRW(L*E5U6TV=@jG0Wh5
z5aFdw++Q*3k&`^H<S!*a`DS2I+i<Lf4}wz7KGrETl6(<{Yq7FbyWJfdFu*{%1m!R8
zU*O|~?;zJb`=tw@fO<TJq-kuU>$m^%cZ_CJ$bScwaq|9J=-u(Iwb8#kEl+8eABnev
z90DKb-5H^2jNL01t^h1tlp0^^67moXnX%;V=Z<FwXwjdsgojX&U~GTEJgIXBpOu2l
zH^1`@{Pu<rD!zj_+eyI&6MBVys{Am+eGkhYKlUOrj~$~~t?QR5nZ8RB`fb=TmI}ci
zze*!Ghba;kTWtR&X$0tkv*4r&i?yuDm7Bj(b?LD-8*T<n2Cc9gN?&rywSR2|P55Dj
zm0>|(=>j%|a^wDAh0`o>ck$s!<k=7C>W|lmKlcK7&Ye(QSndB<mUJd<p<}!gMi4fy
zk2}eymvJq3y1zgyxkK-XVOge!rv?EE0L!Wr7OK(WaKDopGGj)eJelM{iax(I3bNBX
zTuSuHDapxf((r|ZOn*G%f}*8Z2NCVr?_*vY0cRxCXg~g#i>PL0bf4aDgh<fEhZmpA
zhB%I3b9-=$Q95t9Rr~JX`SN7I!YZ$K(TUvi7VpPI%>phV_CIoK5H!PaStRm^w---B
z+RQ@non&?CPAt=#;$O}ODnb)0$Z1<N-#Vc1eM1KaE%n4iEhquKD`>r#27?$=VHlTZ
ztv=vW=PS$V8j&?CJiF&9@p!Ij4|BXRO2y5@;K>3TBZ7q7HyU0tp|LN%&ycxs2ZSx3
zIy$f03(nE8)M9h|0|(Li3Gm{`!ji~@=gtnk0c5kXzGMs{mM%o#xwm$UJF>mFDe_2z
z<2z6@JeZWGyv2lZ`tyIPDsu!LUg3B6jm{}fx>|dA^0<#WAyWTH<Z1Z!_ai;+_U2^I
z_Ed|lzmF?eRcU}vtRi3=Ky>9JQ<zHE9h5dQejEG^d1@L#I^h3{o|vEbcrEuNl+=3B
zZiOtqj;48ggsoC_19SUcx2iPX@6@$X316(6wvgJMP^K4hWn*;G*KBJi{VrH(ew84%
z(?;w;ShH#^bU{|y)&zutE_4H+oQ@1xKOki3|6j-gS`>OL{r7Enz4n_cGO>{U^}qzD
zGw~AY@KCsf?(g(0Y;;9bfuT33wh#d;{}5V4bP(-I@fCU&J9}6Zm<hnZABsj_ae|J|
z?<&bX`Bg-5GeH?C>O-E4uC+qNDh==Bz4Wh<`@YV7`M=c*{_7Dkj&gdooM^IQzZ19;
z#JBgJ_NOlPYV75&LZ#{wl4$CTvAyXZIy#r9znb2%(>hJi33rDfr_rf+iv#)#w!Fsw
z#8BzJq_4~Pj&E<R0J%urAoSlQM~0vkMB@2Wtm}7Yf_)KJjx%+5!hkC_nmi;wi<aFg
z55qg%kP+~6`<`9fY9XS%nc#PXWwjRYnJb3tY2(klDw7b88i_bU)3+|z%B|<DxoVLn
zOlGv@w=Z(_PB>|4;HaW8I`YsYHy5m6sVuRij~?9CK$}q_Vu>PLV6A1<PEf>pSQp(f
zFBS|t=|4It(oZ7CE1moM#E=pOzvt%lr_Hkg($N+IdE$TmDy9gct~)3+EZ<tgH|&|a
z7YP=$iW&qMCa&q-x^I|MQ0?@x5TQ|Mu0Ne!OTKqgTqKDvW8IWgi4Gqs)WlkKrN>Oq
zPDmr2vI27Ec@V>m+-$WB;ehaF+qvz+PsN6iRDFuW?rNQ8A~NQ83U2qauq;O{joC60
zC#^mhqk$G)XHQfh7Sa;aWz13o20={wd?*dna*^RL23)F4rYg+WaDr8w@6FJ+gC+v_
zkH7Q=|LckqQ^bo^i@2enaM~$|zr1s)`l<W-%Np^&!$#cfFnb<2-@zl0xVHZ44kgVF
zM)zwdD9|xybhRpCnW}rQF*=x{dzpka`=AVlvqurpqK0g`?MEmtEuhjZ6w{E55ep;b
zjKFi{V#lRjn-VEQFfsFbX4f}-@=HE0QLol<{Y`CXSvY6~L!pJISYs?t$H^)1a8qK`
zGmG<xj}RP*-fjTIf=isH7>Dt;u=lfz+RZXlbwpF%alb2j!KZpw^R?K;|A;`-8sk{a
z%}~|#<$gV|Kc<3Kl}&vTD_-6FC*Tjb_W}zhcTP@SJMJs$769@xL^Cf$QtNM|t2*xu
zvi!87QC{?yycz$z<PZyoSd9oRk1e0KN$|PwzK_V*0p$|{hUZP435I>^zA}!yl#r4V
zB*kEJ7R_&wZ^t%9UAMPY`CH4nb|gO@ag|3!5JwiLzm_NweyWC{$dmfetPdS8bO(n<
zLU_6a_*+-dKU!9ii^gyO%zwrCa!e&M1aSI!e;-aQFPAo6mnG>3>}+Z@9)VXiJV~?_
z=C=!27VxVuOUDb`YB;ItaPud_&coL6PqWuKfGgk>M&dJnU{aDzo6*5$mf_*g9xX#8
z32eu~%s%9ocJxG-58#Toua0=LqBKz@0XnSI2fK#i_eO7p$Z`Z;p2ZpMkj)o6N~kUl
zh0h}t^qjBmYI)uEy$qC;5S_zfp?8<*^*fy5?G2jYwvIDh7<d;P_a+;wRlE^nQCU-$
zCA^vy$6pA{Y@x2R3nQ$bJP-0b9M2kTATr4zQN=JaL>=&fvofJzfjM7EJA_|ZoCSmM
zzXVSXc1KY?bd&i*uYyje7+-Ek*NXd0KwLk`NvwEB|6eTt5Vfd5AM&M$xi#l6`dN*7
z`{nsATL{c}ucHK<-uFpm{DZap0J&DLbgu#llw=X>WUh4HgkjaBm>D$Gj9Xz=OQA@M
z7{9ebO=q1QPI0mHFA0PoX**ZQat^zZK|GDS9#~SR_}8tZ0mqeg{2OjA*ur#Qtw{Aj
z%e7ERjPGWTN2vO~yKc6XzpZO~(&Hb?(wu;^t2+LU)6Lvo8N$?sfS_71rjC_c^;*Cc
zbbOaehkGPJ2u6rFEB<$AIP8b^rAA}AJb7A#Z;BHWTZ{o$K7UT8G-vd|4W&E*cIc@E
zJjno436lpYCmz$}`3;Vx!ylW>&sW6Pgx2tVc9n_rrQ6c+WHqDrm=@rIi3*YFv1Q8>
z#5JPW@+2&iQT-Zv)ZGhdTveikZh*d9O6x>KXbGoZTxuk0!v=|c2Qsw077Fs1%;F-K
z@y{n)QmeOR&-YS=EEIGrxZR+hmnjLL^r*Vp62l0{c;nZ7@$0{~9mw_=6X@}>ze^Bj
z`XLpwXHDvQq5gxHif=R|^564+0SVFN;*P^ll}J_w8iZ}*#1~sEfNhm$V<T>y9<G<c
z=t*S6yC@QQr9H`l-a_Yx9O_JmgwQt3=<ACqNpdiTNwx02U!D<$yY5nj#$fK;1XfpJ
zJvRs#RhmOs9zj-HtX#;Ti7cHx;}K&uR0@Z?3!`sbQ^@?_IBrCT2+wo>`6CWCs`$xY
zn;N9uNu6x%IlQr_01Hax>*m8~JBKjVIeOa<M;vkAME7m~m<Vj<LY3&%9b)@Y8ck)J
zufq|g&(hDAPIO0zaQ?j4h}8@TWOjKmIzTUk#waMNcaS5RpVI%9$V>EX*q`~_*e03$
zI^NBKjund*i-VLPMs4ewyN4JTbhJmg8#O^uQ4~~oU{j>hG^ZWmz+ABF1Q|QR?a7^@
zHL#^>P8i!*V(xzehniA+zy}0%l>L|#x^eA3=*gRKJ&%ABcTY()JzNo$YS|2N1FlSI
zR+w98rYLTt5s_NZI-{vVAao-zJL9u=T2ytgvV5t9G$p8E@%;$X{&Memab3C3v8g&v
zQ@*ou4&FBnxw6S-Bji~uU^&(5dFvl|o+v;MyxglQf^lZ2WWYg^dbse=8kIRWx+Y<?
z9|09x7CRv?P%7~8!Hdf}&ikE6MI&puvH?}jutU()GzfYJsw2&OgQwb7A?BdCt@+!%
zkr#5zK-}iVp&47Oabt>w?%=LV>6zpNDnVP^PaAMDI9B|Pknkh+v>C|!U9SY2hj$b9
zTm7<|6Bp$`LkKy=-5E7jp!F{U@8YRN1-)4<vLs`*6XZ(`(5^FN{V!~e0IJCox!cz=
zsWR<8v-tM71;bX7^72}P4fZ8p^zWmAUpsK7!*G76`8mVKO63x%%?27eF-=H~Lu10^
zh5r{)nXo#Gb9*Ypu;+U{O_%UGt|t7^IgziaW+|(iKlhebttEctLWa0#BlN$#`NZFl
zzPS8E9C$dmVaHS{?kr?yr}2paP%azCrso&Qz4!jWIeKmJKV_(}7TOZz;U<BY+E239
z11fV<rr<69VU7lq?b*v6HdB;0_&&SR`0{g~CifkF6wb$>d{#xS)q`s?2s}JI<0Z}Q
zJJ`VT1?ORB)GA0BG!L|2nuRSLPfeO57PAZ~c_-ziw&l5xMN9NqE!SCi&-N1APZ4BN
zX=TmYdb*HiLsjWX?D;GYhPYa+{xBp-cL13Acq^Y{)|eY)*9V3prf|BtLT%IFOU+o!
z*JRxuyB7)RJ8X3FyqlZEwN9zgy%<2nZuY&e_r4jGV<Huaj$s7{*^ueW=MVi$1%oi;
z;s)Sdyivu|C-Y`Z3F(RRnGS)}2KD&Su(sCdW2(|*+YJrj?G}lSIFfAQ>Xg-dFaO)x
zYth>^%frT47;5V~I-vIHHUr;E@d}-D3HI}zkANR>6(>pulzJQ=3ly3jmRAxjd?`A;
zI$zC!h0LQQI=wsKS1C_aGO{+T_V<)ZySA4kqhPsP@hGuGakTbQF@xsb;oHnoTl=lN
z3BhpW`?VQ5I7b8YaxDi_lJdmQOU;5PcyGSL`@RSPgeln^f;@&I8O4Zn`#-U2-eaTM
z)mcP7LQANJ#(edHS25S4cUUm49vkE+U`8W!@Xg(7-aqdOLGK88d|a3Mk*%7%eIK;b
z<oU4WadFma>3BF@{YA+cKJ4fn1_I+n@K<vHsg8`_VQVR~A6>(k*oUlF7j5->nN<3K
z2Zv29k=Wmn>}-Y*(9p4h>8cPrd~7*3(Hs>7jy901!cd$6c%wfQ99a=eIsVHfuwxQX
z-v9WKzB_NxfSw<A6Ver%Og51NUX+-K1vu1%=Ay&W4BLo0(mGleuLW0|md8!#6J)6R
zi;6i{3yyz1Q=E}|eR$6CHvQsagH5D21-)#tw62Q$p)g^2x}&K>*J`Vo)VU!<U)ZZ!
zjxT)J@PYK-nh;u;q)s=xrs&UN5XOXXSA=&)NN`4_*$eiSknBa4Y9*>#M$orkQGb`y
z`AKETxzNMN*LwF#r!d!Z4qXe)dN3FZK1S((!kG<|B+;`$Wfn)@xHVlfb9sb9QfJp(
zIo(DedzW|}csO_P#jVnakDKnDN+4#;yf-fKMv$=#fErmmW8ChKl%)tma1~!Hj`GRz
z1pOnAPWKI^slu)Pq4|?bI`gfNRkyp^HIW*t?i`)@{gruU&J#SfoAZDl<8LM%WV5OJ
zt*uiyH6>c+)2&t3g=p4M48gXrb|bh~52NS4uwjQ~9p}EEURiiWMB+Icvq=ie0GwQ3
z!L;)+cz`nL2S2qI)22eeP3zz%-0Jq<aVIOKJbzp*5Jj(CIH&Kiqwlbki}brV-!HgW
z+V3ek?kXKN4~BMpHa;_^Xj6Dnj|62-?KAKMSr16J>q=O(R;;pq0c{pXU2Nu^ZV+jb
z&L_~zYiNud(S@%VJEoZJzY<MBS&fr*Ty(EBop;<jooLsw(XqtJWwoEe{ni&oq9AC}
zmn&Sa7MGU=uljO72n=tp@}c>>jX2_g3)`(>*ncbTt^AWUK|qF|JFG>0W_^<s7Au4_
zL&<&JbJ%`po>KGUIznx`c;TBp9;%9shhD%*`InPU!bb>KXDBN#Wj^o>1VoBt`!Kse
z+EqG%fLteRY}i2eNW^)MI_IHZ%js_&zdSa8N42SFUakam8Y#KQa0rzKJQgf@KC~J}
z@EkwXEl<5pMV&nT0Tzm^ymGgmo=;R;YUGy8yjNbg2{<cQW_nlKBFDeqr9nyIB`Ghf
ziYEmEdnB*MswhMPBfY?mx6>9cz@8=W)^oshqf$^9ZI&-uZNy%(wUb5}cls=&sN4^~
zEIxB|3SL9MQ#9Y3ttiQ33tz2nTAVy7G>CkEl5cZlUjX8C5a&PXyX20XnNb8k6>So{
z@H@=-n#aAY8_=X)@(wfu?2(33_T_N%&SX$!0QVqEO7{H`q6YKe+c3Qia)AGXj=q!S
z#dS7kMuU_*vO;EVpYkbFoT3oyj6An|Oty<704E2In1eER`CmYoA^(V2Sb9HCBCxdG
z<2l9ALXEw$tvApBK!X=4o12hzs;s?X^vq``M|c|_o!mxnXC$)*xv#0BflOj)tR)$P
zv69U;etF^GPs$lnP$)uTRG8lOvE=@}-wdc$ZAQC<VR#<mPi$3c84fu3-YPWhcOA?k
z^mKz{Oj=-C6C^Bbhztvi+J0l{!W89_IG_#s=9+unx6dptvuv*Why<EYdt^0H|D$66
z)2nn_%L-TLy+^*vb!c>k$&iA|(CBIW?@q}!=TmTrhuP*xfFv4-_Smok7mtGjVS?8e
zmM&GBDZ{F^F(-ZSDNl0x`t9fuNFtrvQB%`Fu+@&CX8q5QzgdKWE1hc?D}meiE-jCK
zwmhL~^hhcxLDCVBl~6I$Ma(rmMWpqUq@DtLNKC62W&RfIp2!tO8xl~3O|OKY6WBFN
zPZ0hq;M}Oo6#f*G*>rva)Kk)NqeCq0rD*0;Bc-hEc%Ia_5e^Ja;ywNn3tKOb`+m_F
z5U-Wv1KE9Fzr?PDt$yud1yhKvDqUx6`tsR=gt(3mOvHnyS}rg6u$lQM+q^$R|D@-i
zR15{>U&}|j)o&m5ho9{6W|{$LcEN+e-J=IvA9I0fo4)_CkR#*DXX;o$8v@{S(2%sj
zV06+v-j^}{2BIZoW{A#vrMByra$eVK1f-(BJ=~dJP%Y!%iI4Rxo&0vyFJ6aYWdX+G
zO)8p@&_+beZ&yy%L+E%9MJDjNTx1w#hN;17>9B#JwPV4eRp#%MnWDoH7I!~A5eQ&g
zMc2JmGs6JXPB`F~uzdbHO2zB+tmCId0NuNo6Y)AqV%Td5zRhIM|3J)?`g>#6J|r(g
zx!2uR!+qFF<7;bB{M}M@I=QN>nr#LC#nnvJR?fh=xV5|Y-zU&NdI#!%c5q2E@ZNj}
zapq=kGGAc<r0}4Og<L;Uhxe!5icCldUgK?dAghmxs2z&8f~-^1`nEB;F`WVwP5dMd
znhzB|;M#93PZumQoNvq(0yl)FHoN)z6{UU`9C5>4Yd<boAYdw4cWRs{<3ZqeN;Fa8
zog}|Qp|K{wh0M%v;zM*Fif6X@0=`zi-&*y<udxqzr=@X|?a=7Oe>))hV=Hi6Ol$?(
z2c!~RL%XW$>u_4i-<33v5<(cZ%e06*PfNhv%>(ZsnfO@B<OJj3e~|8fluKvTaLI*{
z(KFoJO3#G&<dKhQ@Z&{&<K=dIK&l((ov|+mEx;v`N8&wG<@dGLOI3J=Rb*mDp5N`;
zC}WLOY@b}_n%Z3p{;m>)p!m=Nc+DYIJM*koj-=Tsy)5{Lo68-nT7Cw&Fr*!Xy<Ebs
zy;mlnAs)vR3UWIqZXk-csi(kXDU_wl5BpJz4=i9QpyRZc(v5x3$}`FMm&20u9ZnS#
zVGS8C(|*C*n@tQ@G)H8n-E^J|XN58JdQ@KZfBv}Y|HjY>2gc@XM#cNylEhAi;)cMN
zW2OsuR@i^oRS*lMN;7^N-2AlCwETb=m|c-6i2?2M+QaC%Cm=HFpIQXn55s1{rwFh~
zXdJ$|2+VKJr;r-xO`XR6d(euw4x2lA@m~Obha3%bTXg=j<HjRFt?JLoPfWg1g|407
zaoTwcJKWMe`VfJ1c-5-!&hplJ{3ehaa$|Bf-F*JOu=nd8Dw24C7}E1fk)iD20avZy
zs4z2`8ha$nKn4hy%s;^OvfvIw$fiSp)&t(D8yc^HR~x$Vk2g^_$7aII%FetOk3Vys
zD4)+)W$kDXOkb>l0i8iXuJ|YyM~o^;0qoU?J;Ug8O|qf<=6N?Z35Kv)bh#@$%F6QK
z4wMP=C^~*~#cmHRNV+H5u|KdEe<fm_no;K*Goz4T2#q-&@wE>f7)RKeVZZS9L}Gr%
zm58nc^>IU{`fhNRHJ}C{C)jWAx0?sva3}AEw!(FaZ}(`ZM%*+&WFauuZ0&CjAu-WC
zt}YQfo$(Qkr64hR4FulI<_#8t(TaN-jKXkmA&?VyeLW;bUNyP$4fXZHxI3G_{T!kg
z`O6lYGlYWZ*%5foIIa%ImM46U+JHJ^FMO;xf@mv)b39V+xd%+DuwUFHX;h*wHy##X
zAz!sSm{jJNg^(<-dhJIN)Dn+&H`3+)q(s2F7I-aO*_D4o-iOvS<+5JuO6$<}#36__
zm~)R3@TYofQhN_gvh#Jm?iyl-adN8$GLFIAVFTJYyz-U!;_Jv}EHvd`(tN&`svB<O
z^ybO)dga+@xI!a|8zGtf%X_MO5(wUf{hw*Tq&JF)qQ4nRX$n(;7!_V<U#$XRpwpuY
zbNSk}rs2<gjR<JDA$Jd49JRBYidxaw(8l@0Clo1}F0d62NUbt(vji^HXMY85Z2H|l
zCz`l9E<s?to{gG63(?6nY23FP8A0x(rau4L(2g<*K;>Vr4sC>`*Jq>3H!2FfXn;U9
z`wFhcGh?wd^UzPS-Qbi3Ib;7?z@?qP9o>D{1r-U3YIbssmWcL))Oj>}?$^rmJKms9
z4nGAFcx%eF=!wAY!v&g8wDY>qt7-h$`IPa}8p=8k*+*|-Or$p81mF3mAhvVpFP<-I
z87inDnUkw~CH#WOSZ>0idQU${?SP_zB0bMH1gjf*Kl-_5JA=X;&89v8i9+CRZX=Y=
zwXNNb;Xb<-sR@#e`n4j3?VJ2TV+4BDR>$)?nePELU*XYGp^IQYu!JNgEOyAJAcn0P
z)?Sy*Jw7pcX!MJGziIovtV5-Zk??I1o#WB(>u4kP-8ThQ*q@A)a1z&RAKFSJ4PN6c
zE=V4VQB!Yf;joIUq3M$XBCIH=L(cDWcQ|O|2%u#Sp38{L(CWjuzT=XyBht>NRK@xG
z>5M#A-k7yn4)TYBq3Ks#kQ(iojeS}pBS^jBi>4t|+g?6C82VWHHN&|oes<LC5r6Y3
zZSpW_e}k2^?lRV68`a;IaD#*l>ATR0LIpuyTNPmKlf;wXar$`tm97kyw)lhG{bgpD
zL&gD&zWVNYkxHN7i}z8Az<w{0bxgu)kjff&Zg_ew^P`6S;o#)}o6r7&G2>a3`gMu%
zrsnp%A9oCDnCMJIh<6`+k`paEoW%0iA~*jh7$o<reUfz8tx@_IzQ-QGT|3~>sC*-5
zLsvKlcT32_j*tk5TOGA^`me7`wZ4P*np8y-%VBXmgx>hHnI2!PP^%+xrP4Ue@M7g;
z6JLhOzKs1ENv}=dc)ZTZ;51eg+MGy3lV}==TH!$+NU^Bs#$1e;ohUR(=rbG6n=Wf5
z3#9)sP|C{*+Y>9or&%@YczEmKcz5Q1nKdE57+x^j+u8vu(l6?+LOsqfQo;Jsai`w0
zwPEeKx989GRNQ2t@jS7lS(%U7bX+Oh%4+vbVv^{DPxxseHk<9OG;CUx&`jfNx7q#9
z-_w%%mG@rDj>zD(fc3G_@owTxLJ(3;&rRNrag9iDqP3p!@M>8>bv=tp^P}d$ea=Fl
zd?6Q7OvxG4_3to$2i>P}u^}d|BjHf|w>UaqKUG}Ck*=+z2r4=UB+jQN!-vkjVKwuN
z?i(DuxN$0L_|L=)dW?%rx1{469z3J(x$OezaXZ83Fz<e>@hz$!R^cHpgeB#1q~yQe
zRvy}~oZjBVo)WBJ3&edR8R$JR!WMWRRes1_TYTr{{=zC_+uQGHX&bR-=+U_5Y}C-Y
zn>x$SBwr|-xQ!az<nZ&1iji|;MFdGu6lzfNGi?ph?X%>cB`EAiLz0ZgxQ%BakvrE^
zC~3ZUdFy?=vgB61vD=#g0yDVj#TVklHt5m2j%*6;svY*PO+;IcplPSCP5mpcaWvhS
zooX5tqhkg7jz_2`+oMcq>N|1OsxpS&xY02~!D}^(7+KQf$tw7T7yCK+2NQ5Nf@8^;
z+O5QNP9Zi1fo3Wo2@0FX>HZmP1IMprmnuB2WWi04owKdPRmIv9pr*&p>l&I*e4j$t
zP`9+>%L9)M(yH$HQ>*&mjqw|N!p&849>FSKh`*Yn$iHyaJ-Db83<&92&A4pxHnsZ+
z6c~Ol+T`-1uq7F(wU#C8znt}intB)?2*vh8plJ&@HAZsgxK)fjo7o8S)r7bkKaFj<
zARU~%o1ldYq(@{c7DG7C;e>!dbo_Yu(9ZLV5C<Q*JZI6-LNEFkIgXtDl3}vSAH%ng
z+IM@GAxlwivMyaxkF7m*6jo>wgt|>c&~)*^t+tj;G?2*^J%gZ$H$4vzIMxnN^ols#
zue;)CODWj{f_5_lOg3tw!`Tz8yYuI}NkMr0wU^7H1ZlI7M#TfncCML9u%u>R>CB7V
zC;0r|P?X!f=le2>c8=janwCC_%0m_;M=a*GSJA=|Phcyfn3N9Wro1&DfoS*Rw?sE+
zdMVd8)LqKU2P=dH?wG#Qh-`P~nq+*|K+<dcH1|Nh+5i{b%oVM}b8m1jNqGXA)n@rs
zir1FQv*jIc_N=+c@MQqMlUnA!c|e3UrTZZQJ$K;R^32S*)8LQ1`z4+{awF+$<NT$d
z+K^>@%vTQ#HN0xWN4R{yh{=up*IGCTXOQct!;+9U)@sgehvWJ#ucg$W|D6?%rudnE
zSZoX=^*C=6x=)+Jnf>N>r?X4Zg#v5=Qc6gKmH1@UQ3FrrYfGB!R@oWdfr0q&U#{0)
z9DBgb7ITzXzH>Xo@lIcD)f0PFc<7zg+_}2n>*{;2Uj+nx`B={Q^p~{#c9=<TlojlS
zeMPiXS|3gbw0v7OT0RiH>0hHyoHn6SsduI<TlV6>H8Q^2&h)l3E|}=e7i<K4hl$7>
z4N;rFMDYk}O|Mu#(pj*zHhJysYV>3|9piVWC+NjHWc=%{gD2RZ0rgwZ2V7bI?CXyX
zf`(oJx<p3&4(PE0F$DCpgacr*Tx?sDNiQBxEfc15E!$VFmhkRJlw=-WNF04ngW7qB
z2wq=0;G4YmxKzSuIO8mA%DYT*bFS@|@8ZvR?2k8JEq@*n!l8dNakEEUnlq@-SP2S+
zaZNk5A>){1`@piy=MQ(rmz&uYp-35cToq|#C#YqaygD!tm3b$0U*tETk5&>Wmpkk+
z)wo#vtu`anAP4x8blV*;R)mcw4Z#zFA|-_IMA)Q|ZG~BcjXdH%IikEdtCEPxb+0I3
zolxU>b?tw7UT@_sg1Il!qt9ryxDsb`%r$&=xAX%wkat0hZ(i!Z!@Vie235v6dAWQ&
zNKo8$1Kst=Z4S77R}(**?WjtNIpXN=Y~D8gYvKWF7_XUI${0}CKMTHoGOP;CymK@t
zxm)W|Bu2pkRy4o~<99@j*a!=q>aQt&&7BC^iMSkQ^_y$W7ZRA6&pMm=z3s8s|4>f`
z3Q;}nd|g^dJWB62p7>lE?SYKd*b27_XYoArX!uOM=e01W^f+D84BdE7Lh&~>Bhgl&
zYwlD0mI`;=&OiwX^wj9|YOzyZw&C~g+JmS!n%J*o>4&##{vk0Hif7B|t@~d);u8Fr
zHZvr|5hx0U5cM|KQ;14&GI{nElzzfegeL55$w=3>o6Es&jOBzMN(?`=b9wEsP?8`@
znyy=FMY+)mBG-|Jp0vvrMq{<*h9pl18??c;dfE)^+{~s4vSic+%LL(k^5WnL-I*sv
zO*{9E-ME@dQ{nn#r|$1_<A)tZId0U1DuwDV&Wj+<Q99c1K<%)#aqA!W30e5dx?`E8
zCxp>k33%IRQcTZGb{~yW3nU$I?{-5y0J%4izxZwXuc003HfmLafUVq$1!NKmIw=Z8
zTFlPLQtRaH={csmg+~TGh`Rd;s}N6Yj*Z+;=cf_^qBzlp5+ZQAKw0DMCuSUu^^)FO
zEOp(o7+C}g7}J>5N#=ZNu9vAN9pJk;HTUGh9#YfQ{ke%rcSI!$A_X%u9;f45Hw>j}
zN$6GR!zU<Ncf89Y){XARv~!8iem`zZh#1p79(L{tU!vVGbas#hG@Rb={miP73_Bc=
ze;mEKH&#-P+5#qrej$R|7WM&Mcrc#|x9=GI%KSmt{#6!2&nn%>3-P`f9Hdq>(CA#4
znOrwkSl_CTYJ#>>Sy}0}8G>#o%HKZ5J*U>qeYBDq&K{@2i}HD4<&lcq+$c{J8F-w%
zMIC4KpT;@;o=G`I*3TPHKdz5YorYpe2b;&h>1q@O2Yh@zegH2BM|@ul`S$HT&~6C?
zej@k{zQ>Gp<~umT5dSf_sX{oB{UbzNY^)Fw1@+5R1``!#6>qUzRi>6+@a#~HK(*#0
z?#B2AQnv{-E7%v>yYzAsYQ=U<^xJi!*UOjvv7hCT5C~yPzPGt;fsWL~uAi5sn}2ja
zj4rU%-Y_tYJo}*81XoJ9htxaa>6M5gLzHT``rb^rq^E=Y_Yi3+hzqT#ty0D2xDFBr
zQ}wQ}#C4I!eqsQJV{!EuH~n*N*t4&bp5A{o+6Mpe%1FSY1+ZdVxv91l)ze-a;su7+
z(#Thy!DJo7o?V`ep6-ytpXK5R)>tT_4n}C%*<t^FGL1so)C!cs#%So(ef%ifECR)M
zoOeviqTdwe*mSALU#!|Uy7o*u%K)m9DZ$+8vcysQ9HeDLAj3p}*ur2JNs%oO+PdJP
zt*0GalIb@%KWx>t%$FM+0~{vd`_|c-s_)B`3tQ{}*o<hMDaR~J0zD!xqTAT+#R+5j
z=)+_%a2lt{4DJ5J>T=YQIlWAy?$uZLb&ap+Y#jmcs|Xb4Mm3CL3xT#>+|02?%|S$D
z`qK5&KXhaeDAuO|vW_JAG#qAv<Nkc|Pcl}REn))+Y70Y<>gRA|)(uI)^@rE~iXRV$
zxxVNrrZ#YQP@=hnzH0<&O^zl|+1XtSMcGTKo!ub>tM4~>@{jpimbV9jw>$dzVAhDz
z80KMZqKOk1(&f3!<6}ABi>_;Jy>dGmQ?2$fwb9S8-qc7^MRuVG)>6-nAC(X&LOsa|
z(|Fwvus}9U972t${eQ;<{J%)vW{DFp1CON$VWeD4d^_T{&%*br_TG2GHs$0rD8K%E
z*g#wt%B*shnf!TiS`DkA{XIOQ2qt<-(6+o@Gu<bO5lJ~~ZYt5rSA2s*>E*Q%9G}t*
zi~bca>+vh)A`;tXU#<GV@d%tA`ju>vc6aZsUOG{3=-fdAuTsJkW#WgOmq)}x{_N+l
zQ(~*GhqGt-@VuSrqJ6eU<H_1syv(CsP@M{bH!n&9dZTlyCaLrtVdzg$vzm96NF0h#
zjGAwbT){gN1e>T|+&}DHgTUU<YIXCD41lcyhQ!R=;wCG=KE`n7`$Dg|kMDHS$2s}`
z&~%nTbu>*IKDfIR+}+(Bf&_QB;KAMHKyZ=}T!RD&?(R;|;LZu|?(l7%x4x=V#ZPu;
zd%An>zPd;1bY}ikjt8r+XD=ad3XkLeSpbW}c~PsB1rc#^%0kzV+LB`OjF9)|DXGFq
zD^VK*iutg!93Xsj;Nxu~5B1CrVX5$l>Dw6ctv|lK632eyCi}x8@pUVEn=*jemtZ=i
z5ySWN4~d*yiPL=C%vkww#m{MRKTv6CPHW>_5~A3Y)U0Dk#t9R(voL}|^P13KI}I-7
z59qxtRX#@fz^o+--01FF<;9P9wGEM9n`n=*Yawq4h1wCs!pN*ag!acA*Nf&1Utr7}
z-<+rwml5C${%tzLDG#)viR{o~-uWNAqj+(quc*D~V&KhBbB*YBkOTtCh<ZZv)Pu@3
zs`=fNBvTd0BD1NqZq?o1f|O7~rw{SL0G{$1S(G+!2YUpjMpHwB!2AM?iM|RVh?21I
zmyKeL?|Vk`<Q0G6hAqn|OqG6OvBYY)_19AjPVeB+a056cg@nWy1eb=@#L1ysG26e3
z)3PL@t<8Ho*msU&gU|iA^Qk%<9zKo>3z*@y6^`0Yz!&#w@f@E06%!na4+6oLWWdX6
zo9mQg>Vz-pWPDEM8}B6rrj;ZH4K}0ma>4Tk?W=Es@dZJ}gD}4sDNoh^g+R<pTv>J3
z=b}BV1ir@Fp|XtTyAjW{IWrw4o-oe&_5XR)LWYy_=&vu8_F9}l?+B|+`_wk9OT>Ov
zDx+OfO@HtIQ{h^e+OF!VgjlMYkGamzjQjowCyeskvyiNKmB8z~d^8;2&V>aARG4%>
zVEO{f?S1O6R<QYg1Zx|=H{gt*CoZ9K`%h_$D0}Lky)7@Q(oVALL^Ns77TVn8iiYl(
zf8KMDc;(}C<s*r04KR{R6gO-Uu{p^iSZt%Pq?ctqT)#bvo*#e90O8LtV)8jh{V+%J
zFjUDGN``#0sa}a0<^MS%UuX!)kVydgw2Y;CT_dZ@*{G*hOhx)&b|V@PE$69EsKRm?
zDcin}B<8D~4!NAs(m?8Ra!uzvNd%ur04q%E<VByg?EtAs-M*W++mjFkM(nv*ak+XR
zWS9*^QW=O__6AWE^*@Q<3oEZTLjqi4lfL#~A~RVyzZ(k=C(05P-dV~rYcTQ>`|Ps~
zyk}rR-#+oa=jw;TIWB|xt8J!Yo|I`Rtp(AtXkm;doEp~h#<VJxAD-ZJ>A7~Ozn>hD
zyUmQi*u){kq+smB@SFgw{J-hlhwl|2?;5ZG1Ac<FM3tY&lK4?xmw%<e$a!&qhFj;G
zXy158_>&GAFkfs&R*5NCzw+8&9L4yZpG(1$eT_h$`pSp0Dg>KO7bsB#_&`B%%6?KL
zif{Q^!-c*gY5TI28$R$6j|vfS<RK$Q5<A~)6gIb2gAy*v`NJxse@6UeP(pJiz&O=U
z7Zvr*3O)$65$4fCrft6q&-HWX+KzEr(gQ-+i>h;eGP@ATnt^2U$-9r!dU@bv{0O{p
zpQ;~ah_by-;^oX>xN?!$(PadNiLTI@ZH(|rY&-Yl>3;!aiNkLjQR5}vIa$ozhGc23
zBmUDZv8L^Np8sBH*`NLLh02gnwq`X7CNOmx>n`ZcMONGOyv0)C#>@P2Uc^>~hSJ|T
zkTvwi6S<z^cY(&V%hPRAYMXa+ak{fqL)CF$kCh?$+cD|t>%INd+<8`VL;480wd(d*
zja@r_=50fJLUN?8Nef1$kGnZut#A9o&*12Q$gr<rYK$r8n{_Muq8!zI>a2}`x3sA@
zyHSl*<lf6t?_G$%K_wyik<d*xVZcl{tn`rX+{Y9r9gQj-k1CCXA&Dlw8X1u^sP^AJ
zgf=^$VtAB`1iXTN>5pVqAGHFr3%*kqEU7Tci2l`QN>mILO~o5Oy${U46w0fQIp_#F
zLniupBK_H=)lnzM6mGpB9yau3$`xioj8F=Gr#Q6)ESZqOco>G%cPsC*FxlUO9;66U
z8k&@>c#o(&uGU0Zza1Zs8lFK05mLh{BiYH|4Xlnif`Ye>?mJG$_H7nGR-)`mb6Qz%
zQY2-Ezx(|^vBvXvy#Qy;`QI6><O+=HqXhZ(D<XY{PQp=q6INqB&8Hg;<#t1sG(5Ov
z?36@77{8MbXhxOmci|V}zv*BB!6&Js@nA2`K~3r<v5``pnpzF`{RrO_DRDF{ocnJf
zk{TC87ZYLRG5p*rUuw?;od7y?NvXH-;$lU!B%(9)#)E$%s}*^mAaulwQnn2}{n#}9
znE|;-jAZ|j*~7!{%}9qAZYV)a!qk-5`z%|kl;o-%RciQSx(BM1On4<crQu4Sng2j1
zTE*ixQRYN}whN5ZivwYDcw@AUVfrvd-3o@+)FO7tx~F`|<mS!g)oG|$gw%TdTCKwo
zaF25!x%H3}v%-0XjnrCvBiRkaZ>@_-c@Id3hBIx{@e!u*9tAzDYfdlQd!hQjGb!p!
z@!GLzq*agB0l&%TcMF<RRMeaKK_y#3C0}6F3aHhtJ4KzizwF9~;zwXgEgRT46QJjc
zk$LcDp#O`)!(=roC}%I{KNW1?zX+jQ)iN5j`JzvXd*hWU7Jxpz&*TeTOk@#`8_-87
zI_C0=@>bL~>avoD-!pChT$<jOmi}&q2TKz10^is)0u+-bvv`jlFj4WrYioW$_55O^
zgVcjJfc9^lB?<KF>NmW(OvY3ogK2*_;WtaRi|wADvOs}b_W6-^@yH$9f(8r$8ao|y
zJK+B^B`z8D%1MawDIi=jY}VadSB4kOG8UE2_~)C=e)Jx636`A>Pps6i*q_edG*Vvl
zImg{!_HrGLCI-9&e%@J$kNxCszUOz&Pb>OUK%<vpx4p*y3LlG;d8aV3BXn_abH(xd
zQ8%Ohot>s!?8~pT5%b-N2<LL57AlwhO#u_3CoF8&<)=(csn6ogdQ!vp?jT&{6_!Eq
z%%Op<K<0h>`wubm8Swh)#@&;z$4|Ic(;5cM1;C4}Ce}O-5v@9s))L8g`az8qZG>8%
z8N>Hz(u+xRJv3KBOK3Cs>%0chu@d`JW;W=cgahv9LO}q3pvL`Y51t?HCvYSBQde#H
z(f!KXCFyGGJ<{tT#w$15%QdN%-FYNzH;|4Fn7+a)X}TM}`sb&0&pGUw6XuIn>N|Yp
zQ%N}UZnUQCsNZ%Vy6_>}n+S^QLpTd%X64gU22#jU&X$Dg3wpD!wJvk2Qj6=Nxi%l4
zTn^688f4wDmZWAWfHcYHYH~xO!2;G8ul8MS!}3H{!vyaZ{NAavm2zotTu<f4!$(og
z!lZH%APuP|;9rxWiY3VHiX)gXlC-fQ#zqyyy6sr?qF`AbjdpD8IxUXC1UXHMQx#I?
zyAaZw_(7HF1eZ0xBtWy?{=A++e%(!cg&r_s{RVc@zdsIFx?g{Lh-!X)9jaC~(3iW7
zw9~qn@D7gnz62&sWd3g1>~{jqv@=XL_sjErEY}}QXAU|}H#1~{iNMbj6Kj==KpVPL
z&VUvA)+l-Sd;6+CN{Z3;BW*~n>FGhM&92Q(gP4Za=mDp%G(oQf;t|@s;g!fs4fqdV
zoe+l#KGO?#-@Z>V6}6)L;?nf_GhmPg#~+W9Y!r~j>dlfzt1CK)f|Wcgw~o`td=3T@
zG0#r&wD!r8yeRjXlIW!C82)Xpm|_QkpjY30b4B?soYCu=w_g*i+s?21!X>ylDz3T}
zgw4-&rkhW}=ee$Tqn^WFL{8M9B`Ij_H`(N7PUa(X7kJcR<qPb2ddqD*nH36vzq-()
zG3s5K&E4$&V#2^wluip|e&iFOz-Qe28g_R`3zlfm2)$-7F#G5S;{QYjZS^$XjKmXc
z`0;UGVEtht@y-!C#pjpy4_`hR2q%e1AjwY?U#tT91gg0W7;Wb@I6DAI@pnZYu|oO)
zWfwR1CM26p#F|4>6k$i$@YK4Pd8R^@(>J~Mbn#4JBDXP25&y&|F*Q&5m(hb4$O!D-
z#ryzR6d<>oZ{jl0c1(2m)4qt$2rJl>UphewQqg=V(KuOU6NAydsS42cRPRizGToZk
zxnk9!W>J~k`Wbv_Jj5y$(;^~vf0VnuC!V5baJamUxTnn<$GM>+Q^M969LLEZR@D7>
z96tQYChtHD&dn7`)|GRA*HVrcESy?(u<~<@N74HESy)`c&(2eKhj<QCtRo1jc<Y%|
zP5TW#YSn1NNV};$$}hC;WFy#aj*cByHgtQ|zgrtFCe~4{(-@{7uhQ@S#S+{2<vmH@
z1*%Z1#(H)trj&x=W>!JlPeitq@JhuoKU^zHSQ?tb*b<*&M{+F=Zqbl;P3VurR$Df=
zYOGqOhFYT?negh;ZR9v<%|Qrfofl2jvJl9JhSz3QBF<*$>RXfaniJR?oKSqnsGv;e
z9hhpC1S7UE#if_KY-VJkR$<P7zZ4%#1Y)Uea-}zhF{x@w2<Fx_vrC~({7=Z>qe#Li
zli|4x^w#0fkXItr8T+_?8(R^4O=3&XX(DPvlBFgT^+aV4IM7BVB?^~Y%JEiN#<i8?
zyK<%r0bGn7mC=?!&=xAT@rdzDjuq;$xzRRyINp;=*-xN>I~x|F+Wv8bLySOjDPMJ(
zn+KM`#H0P8ctjCCua*Rw1mDRWEWL<^{z0Mfp#jEhd@U!@NSy-g$WU-pe74q?3uU(I
z`_<Po2(C%IGbRdexT4r~Z-#fV%}4c8e{=LZ4x&S>!ho2Ro*^tqYZP=on$YDyh{wXl
z7CI+--%HUnV$I+PZ)Q8Rk)rV<?e{`1`WH^ecd;x)g(X5cRJsg#7R^ff4~`e3a-@wP
zS6qkOe~q)`sV(Fo!gwKKnt?7INE2+LX?mwTU(&}Jb^@@RUj{IejLV(PdU<$P+qT*X
zij$z_N{{U^{kR7%{4HDWjfe=lY5Lh>Qq3lMh_Ji)Ld7%;Fn8=g4WTEY;Rr@(og#zw
z8y(p(seBZ)#h=z?DZi~<=$Wr1gc_^X!oq#@8L7-*Ac$eBC2(Fn%Q{Wf04e_fbT&Vp
zIPECbVBjE+nTK!Xdijj9zklN9Xaj;?DVqD1G|W=f=h#<)8^NkJLBQAGpzZXOw;NS9
zK*a*t`nv?-+kM{VI9(G*>~bGcWu5F%qaoBJjs4o|CGN@|T6DuZ)c2<vzOp2<QN}vp
zj1I?>71ns6ha^n6upUZbwdI*e?EYf%aKFpZeLcR5XvOzX9{F7xX|q}4Ym;a=YXoa|
zW8g{Rlf731YBOP%tK}6hmG^i^(wMBv#kTsj=Qss%tvzqxA#t+X&jk=eS=dD9Cy!gt
zJ}y>VcVAp?-{ebQ#I}bzul-gq&JaOOYetCv+9R>quP+tSZk}(aDKuu<<s4`*#pb=W
zq+uR3;g!s4r1<=}Ty_kq>^fheRZZG1CeUTRA>qyt0VjBMMh#HtyI%W=3TdHjVj*Fk
z5@hL0GjmZ*a9;9&e;72Nc0?Te$8lx_Jji-r-12&mm1~&N#p(Rv|C5Nrp0j?<T`=nE
z+~a%6w~QrEwIf1gnAq|?0>Y_X5TiHqAYe1eCs)4WF~diy$=U5=38UMvfj{{?UYmsw
z#l`H<?0!HD>i(spKK}QRthzJ}MsGL(#p?q3_~tB(6K^>*J9vnrOwUN~-1@lEUJ!!`
z*^r_w<(Bq$2WxLN%idY{@@1|3M$b>gNDaIGi|X+iCS<Xq=kf0ef@GGuPBPn>O%DuK
zZa@(2GWAXxkWOhZCY-R`k;3|}7#Pa-A?BeL!r5pog{&{n^dU-;89psCdi5k2fmZ~%
z(p#Dft@^S$#+zb%Ij;_rul30vGr_-WPO(VM4R2UylmJsj00B;vhGh>#w{7xCG~QOe
zH}zO*btp~{h&;C#gM@4WkTF6Lp5?{p!v5=%i$>JiYGsrGW%%vr{WSye*%oJArsSLv
zrkZv?OpK3-eP<LXptS5<dGG@_rEt?e$+?}j%Kn$%-;#_jii7(J-H%NT<?yD}7Uv$s
z0^g|H?;yEO?`*XQ7@=&FX7bN8hIA#Dz1jx#KqailCB%jsiG=+HO@p;~3M(yVdWmH<
zfgA4;6WsKpux9ey3$|(rLww|+FA`u2lNkt<hO2ByVa~$wV~O`qnao^k+{c1#Vy+fv
zbRrnq3<5NPce$=c*T)~OEH>9^VvBN5$jJ{Hy4vB=wvA~!krmXP;+;a7<xm^PS7XC>
zKp7rRiP&ie*|NJ1o*yo;Js$-JA^uG8pa3fPX{_7v{CgKC<SKo|lQZ6cLj(lDV9V~B
z)EsAlVQA3Dk3%9QY7Q>nh;w+F><1(mQ}3*_<FJJhXx)gtwu~|C<(5^%vU?I=XPdq_
zU-qQwQ2ypo{&p)szrwr|lh!2;?))NYoBs%p^-m3#%X%5zBgUu&afow*japxplXT`}
zD8JpX^!3afQYug6^q9cv^DwioD-IGyCd8S43aGvK2G#uhY8-Ihm+R-ohAqOFDZV02
zO=$Uf&~h`2KQIqY6P73N2@d+^V||i|P2Hjt1Ge1RFi5cl+RZ^95u*{uO$h}&wL~DL
zQK&YKr#`-8mig)wK3i6}W)zCQaUVeb3VCzEpB{$5+3bDr+<vfpk9sG6-t{tVto8dP
zFc_JbRsNqyS4Ar3j{Q;~?9974c)ZGhk58I%c}5*{TB`UA^qAn*-PqJFVlU)-1pIEh
z`qG#*X?4*jUPyr=b!z}9hU3{tg{itLesh$-8gwj7XZP-3P^0DA_<kfiQYt6=Q__$o
zhv%yr&Vt?;m;?t>m^K@fhL6h@OPE;yq<ZMSW6v+<ca%cENA)|@sqQ!Rl7Fv`nN}nD
zf>nE`1d4g<80Itse59T{^h<&CXIh+wllOO+5R!`t*hl%OY3|iTTdEp6=3+1U44Nsb
zLiguOg2#)ex3y9gNqme_roOJ{d4|`4VBW9^*!ZibXs&-c+)|U=2a=xi>F|FKX$```
zNZ>cg$NypXN5)pWx7IA#)>Ia|U5YM>{N<-}!Bk{9CXyYzhT<=FmV&gAd~Ykn{LgK;
z^T3`{pxz!CZ2DqkYB2CmKyR>P1w4=i-`)}*_ELSq$kN{QsU$v#g4hRx&_=*xm!=io
zPkn-4pocD0DffDN_oSkUhoVAB!{dsY8X;vmebn5u0jJy{o5R?#@2E&hQeLRzMkgb#
zTq4_$B}R1E_JXF;#pBk4GDVr9DMPO4@1z%x@N}Q~{uakqF0f)voLgszV$14$&vPwO
zBf2_n<lEzd+{MNl{}5*4r{F-@KIEXcjjVn!H{<iu+l|mDJY2-X)-=7^N|$FUKjBt@
zIk(QmL54e<q2jxl%I?I$LR>aFjzV$ka46IXf5-RgVb?{ZC(p}*EFiw;5>V6uA^E7;
zy#}8pw8Y$luoFSx!@3f|0*MTqhTb`(jo#>(l|JxsU1<e2BDP~kW+c@}bllEV+A%;3
z8z}KZjKre0l$MmWdN#A@etDT*L+ZSzeat6KuEL|_TmW4KEj3r4pgHjFI$?oFdTI8A
zhkSb+)<~uwr5v?t!(ZE*;J{!dm91G47z!MGQaL7fl8(7}lxo;@yZkzUHve9S1fw+Y
zESFXOwC9NujMVu1%7^{YkE{F4xB}YRbXo8d$70gVgTLwc?nQz4v-{s!{UJ;8Y{OQc
zi4``Jw!|})lU8q`u8mw3?&Pk!4e{NDyLIh%Rj^Q7V~SL|FN!O+`|CQ4x*YD#(534p
z9%$E&*DptV+L=+&KOnmAmtX7I$#YjiO-~H<mzr~reg4S3jYTb-6$i2^hFn8xEgNcR
zeu4)8%z>9ZYehg~d2=S06OKPHbD6Uz@T|!A(nh53H!nT;?Ni|XLaXhDVjJwz=8wAy
zRaAwxV~bzCxpz4&L`q-hmYZYg&jKy?0B6d<&$%Nh3Ziq;by7CRd-0uUYu#lAIckl;
z#|WO$U0kNK;O}a>Jc<;mE@X9inVK@@bbyMC;TI>I-c1Oicex;!b`GVpWL3_dJoaOE
z4<tUh+?ilYIIZ{RdPN>Q2=cGAh*KPgT`|fKVWW;i+H#Ul2i3sFks6ckCbdJsIlYC8
zeJy)Vho?WBA<-4<!aA8DA3?aXW<EY}eSOSHAh#uf`FWwF5A<JlZdTn3EnQ?9F7Hjm
zxo2T!R}Vu!L7_PgQ2rumEN^S$(;-sx-pJL^Ml*&9<QT>KJA1Hv_Z;nB9kuf`9qFqF
zZ~3{u0Ql*d8cDX?_aAvq4`TO%9D@hdied$seFPHdGbpCE-EG>=$zN~Ymy}&O%xEQ;
zKFolMca`op-tNg9+X8=B5q?ukUgn)_K?5&5ZW`6}=$!<rY2%<`$3ewtWWqp{Lzo*Z
z@dn^+Fy6Z0I3kO7f|3<4<ab1n>k;J(rv9E%C9ECal|@Ra72ZAdDiV2duCenQh;@2s
zk|gdQpGwI$U%VhTu?S;(1!ynrcyiS223{y4OtoE68fi~2ZJ-RcJ1=T~k(xK3;Kz=Y
zjOQVfd_yhGD=ABmwn*RcRPbNB+D^Bi@Nn6)j7Z{$M=m^n?O2eW*wgYP<vQ*&nNmi;
z-8=epxog}#>SNjo%!<s<#xVaXDdD&Neo>$ef<?M!oD?laK8oI>gFB>K6y>4N(D}zf
zc+0Q<B2A4Z!sq(JLDlOghsUv5pS5m`wQ>S|W0vx|%%xv=zPDJ#ST`x4eP8=bimmPB
zoN9pPMm5n4#D9EfoSvSA`{+a_pgGqOooo|V5PS_HTrmowAzS-)*>@pOFDYK>E8$*q
z=zIFgqjl>jOr7!B{O_W<%Rm=dPPG$@%5N!0&X6C6#D4IPc_pvk$zx=?g`1phT)H%w
z6hSO$30Ql`k3(|ZUWDzCEXejo2Uw3QRF7-xag}A}Y;ll@KoPSjJNIfX#+|;)#7KQg
zwEoKTXH=irYHpAHpx}0C_DXZU?P61Xj*&Kpj}<DZXenu;`@3IvN#)VObT1G8*n}Sp
zQ`D3k<T=hUyQ^MIDadAWkdu{OKlm~3Izmxb*cu_-cPlCJH{c@D#Aq6Oe|~~G;h*z(
zOx=E7Y>CWF9^#MqB{%xnH2$q-LxBod<5UwH{_y=m*bV%nmWurk>qZsCCA$Ipx=<27
zkWXDQ8FrA9itl!~$z=P@MPM|jI_h`FUdLE)WoIal+O0Dt8>>XIu_x|o#ubUHy*ek3
zdXfpH4B6QN15hCio$(lVhGcG?8@oC)!zn*S*$uhSD;7ZR`*dk|v)UX}l^2+sYJ8eR
z79%ti<!A&134(W9O`5}2u2%)jn2qu;hQ*;bh#XOsl8mWQ*XAtI4#-(K7CRb9btpKW
z=^^Oy(2cAd{&!;IhZDJ)jHyGb_b|i5zA~g<6570^=lA+YHZc!CytPD+wcpMju?cFN
zYfexvqu}NTpAbhFX`f%R2YPBIf%SQ7?#=cj^0XG_ce>sr$?53Gn|fLi5PJNKVKdLZ
zvf`#io<Nv@>B*|6e@bE0*l=r_1rD^qd^ObaP*G!yO&O6q_}+o136;3l)d@EPHo4yn
zhA=HAgRXOCr5<ksrPiVzl70g1LN@~y8*S%#q34=sqA*Fy_`nY|4q0spj=2F_vrLYg
z`}(1e)uB|E#ZOx9Zw*28FzA(X2lCo%5uBq&W*P%=_}z;hZcyF8aw|mG4p%5Xe(ib(
zoZZ>v)Hzd9Lj5?9DQwE2mSqDyyl`@Ux&sRlN|M;HOcP`BUwjl3VM`yt+>y>5Vt<*2
zw<*Eg0WS?=&s`h-As!QFX6?&iH?{&8vK0-wxF5qWhI)`2y5W()hKUJ#s_=p?{t&&V
zX=pg@(z%sdpdBtd)cka{Iq;^p4Kb=Ccu;ZV%Orgxdc7L&oc2%1dn3;rg-sS{u)p{e
zE2d|FEq8HPsky@J(+6b8L^eDvu6&yCHPsO_DIV`(^I(g8X;LIcm9a|iMP@Hh+b0yb
z>I^WK->PrUDK)n}589wa!c&eU$wkoC1fQEHnIZ{$PjyRG(?(sFX+F}Nu9~SOGenSo
zb5JCV6I6Z1bI1SXwtTfcr-z)N+kp*lGoC8=aWLDo4Le3sy+aj=RUg%QSEPIF2Db3v
zC4^!&E0;G;maM2xhZjv+euy|hoj0BdpWX&4%UeW;E0_)hI}18kwbi^Kj5u)Wlbkhf
zMDiiL)x68>P);q87wSIwz0huolQn5ZvZY6l+v(d7St}n(7DE<=UlEMyPOlL!7!<Sf
z160?j=Q@za9u86cs;0)IkGWfiLt&tB*AXBa3nko;`SQ8l4?D4$xcw4N6Z5@C*w{(i
zv}V%~C0K^1rp>FmXpq#s5ow<zJ{ut=x0BvC+7-?`N`gjvVQa5U;&=XJ@j-_3fcqe(
zQva4m=8dI`F%>dAK{>>0OtuSM1X@;oYY04qw|D8J1im&q$0|`lUwzzX0*WUb0oNS3
zp5D3Nak0N&PP~w?lJpK=^f6dn>G^QL%`Uc{vJ?v3GPe+iZ)<Ln>1Lm)+Y2E5{_SnG
z0H&uTLD(g{R=}RQe9am3+=KeaD4m1q=Pc_<rXIp7RZV(&ce9z1iDipkKt&O-zp~HP
zxMwMHxKcN+(lt|yyGVOB#NC|Z!I_gEcC-~gj=XNccG{Fu(QE5r7*gQ^r<l0gJoN`(
zDDC8>POi0imk>o7L!MHU!9;zob(yLt0BT{Q>o1{9^}9G`wW3`;QcCISfabjtwn1AD
zUjlOiAW;P|s*mHTv7J7P{;r&R9L6GWeTcyiz5eG9ycOnn`@IqU5E?(Rqts~g$&nTX
zU>Txa+h;_wzdrI$^K;cdct<SWXP=0+)V`W8b@>E?W@j_SZA8C@z@P1*D{F@9Uoh&;
z!0}HSQ1TGM1?zyzTekzc8t}A^79;=dH&@3Na5(Dsz<ZwD0X*v!vHU+-LvF;h5sO|Z
zC~FVzF(!!oq@;cR{67m2`SdUK-xIsTj=)r4uQUVB8e`m7dfA4*%F&2p#5y-JcKJ?N
zi>0QCKSyGLou257T*<l`o$&C)mx(|>)-uT7cQ*A4Zd{8w^6I`r)(7yCTo{N@+K-m8
z#m=M0<~06kiv&x?HmcE(S^`~>Zaq9@WDp;rvTa$+)@$}k!+{a}!s)scpQ#~_8gDs6
z3flGE_z!OVCscvpv{Ff_HAFYF)gauzc})0!<$U65vHo_aMX+iaJshWcv6yNrX9)yg
zW$Xs#_SQ=!9xk%j!g&3wttv9?T7dIl#&|g2%-|b$+O0=}idqR_>8zCe)21VMep1|`
z(MB}W7xm9vlW;k}qi4S$V_#^SjvnkE%CIbj?i>jIVrP3Ig9XTzLQf*=(4({9W4k2T
zt8Y`kbEPbG!zvXFG1>5IL<+$k0T28^c%pqUXsHe>sLpQ|nC@5p+?4XrG?@<DRoX5S
z)1rS8PxFJa{BBkYx?|^BWPgpbS~!^_eGiL08RAPG6PjP}Mr86*EN_H4_-IH14e~i@
z@HaCu3lvSbX%Ns!Ww}rC51w=ZORLWrgdkaB)}l5_+kTIs-9Lu1XC7qbNHeSMSsV;j
za<DA-!ik%MX0Q*%)dpEmzYXC?`l~8?B2I$?F2;oCz0IwOf}a;QBp*r#Ha+PYSNm@%
zAr|EY-oWW=xU=^iYAt3;JQ#ty^Vdf^+Opk19f}#UQ83kbS&L1&D57u10c0MKlIZ1@
z`umT43x(VX4_{!*wgU}RWVZmJB+Sa0VE0TlU&BLOK@nIq(KH=Ielh*9tt3vn;2Ny5
zPN=y@p8c45v>{e={s>E~fQN-(yi%y2fyG(+_(PK$WWC#8#nTzye*<_iRS_Z|*X^A;
zP>2Oz;@pEQp!=I!e?(uJtEkgoNePR7dSSqAnl$Rxdx2#4UYaZQ1hQaNQD9Y>Io9JZ
znm$~1^&TEm>EPqn@HKtD8NmBHLv+@N;x9#GL4jK)rS4c#77{m<w>Xqvf()qF#52I(
z<{uIm2b*PpugX6VYBoSA1K<)P^&BE<RrZSQzF6Tq2VTB-27mu27~-@}-~#wPg4ByK
z)8nc)ntn|l=nsI#=7=d}VeSS$S9^zpRuKu!s?Y&YAZyGEfOHu<)kjvmL)~B0a={2#
z0d0xU+7O~E^*3_qPM(nbb!G)xx<E#1;>4}tB~86d)4|K@=VH-7Km@60UzvB=dv#z)
zedXFOJEnvIM*Ze3LL_wyE1Hq&_xBI`Q-iN`v98QUoad^~@6JeiM`P{`pTF+XbS(Nu
zJ2C=?+Z1K9<3F6ZGy2c>7;n$%mW7+mL4mN`b!)=(22K=H(0p(PJX9p{o81@E0xr)}
z1-VEoa%|a>pLpYeGrLB9hy@+OY`t2A7KpJ&8!umha7z!jMur5CBATB@8c4^4f-I23
zVN`dg_SfzqXm+Uqs~q!7h6K9R%^E!t?4p(#Q2&E<78MFad7~7+XspBJIl>lF%9Vz#
zq*iYCg9$K^H4Ac&E9?il8%&M*l}z6(rnD&wtrxuzxnpys>AW%f0#oxG)_)FIo9z=F
z%FF8_UtttWjQoSRI*{@=C&G2rSp1WQT4g!(fodtY3+Fok>r22Db|#$>7mAw<K1$7t
zl159l*5_Nlzje~O)<nyVt;a;BLDwq!Vdhti0_rvkk(Ah6a^(6IS|J_rz5L1h&LE#F
zM(bE^YR;t}4=!7DZU6Yd>qVGfymgz<c1sxRn2)QNF=-?d*LIr579X5s{6(!fgw__t
zPwEyA>7SgQTrm7MiYGn;v5-@)B}_QA5*TJhkSAZVrFuJm+<~x9O4K_X-6yFFPD=U8
zj<$LFho5sQ5N)lr&Fs8$wjj!rM8p$y$pi0b4x0t*1}KLkQoeqs+h*8#mur;t6|(*p
z?k~zIy^aAX0Z~MpIDBeFyHem0_KH<KaGl5><~^5P6!vge=XrY7)pnGID@^QyoUDZU
z&pKna7fVm%l&KR`#EHOxf-2`w#zvL@2kAv#xek3~)DtIzBO2*(TgV?XbIf9rkoX`i
zeP~;XDJg@V50z(w_NVS8S_qs|59oy4;gu7e)F)=)pCXb=v>2Pq^`}^nDcid7qH%`s
zzc9*ih_0RZ1&d25xEmVk$%$p7wGykyPM1bY5Zfd(H+vpvX0^NEQzAD~_#Z#E5lqi*
zgzMQn{rXDNk0QmCW-1!x@k)VyZ7M^Pd{LBTr6@1;Osj*!POU3)AgzEv86i?!#zVMP
z0_4=;QRrsRvxaEd^3cuVf#~T*Psgki15~|(xnU#o`e+>+3J;EQv3k9OEgKK`evt?w
ztYZw{^S%816lb7m4E6*yM|ZxMRKf-B%o6>bB?3xlFd!{sc^g%NuN}q;H+K}+v2glx
zkuE9W2_zm~HV}jm(O<nEH-J0j7Hbjs%3oMXixrFNDNp7VM|4Z#%s-wixa2(zZT=$m
z@Vv#dBY<J;a$IcoqK~bk7wWN%;d1#`U}xh18L#=qk!4GHdz0lFlgrL&g;nBH7D62q
z@mlHF%8tz9HiU|zAo)r)SZtosFSs7=)Tw!j?jI)cS)}8$bv%%DUcc)?oha>)8~*e?
z9{2S3Gj{7Dx!JxMdvmS(=!u_;iLB|+(>`LNCF2vERz>ojHK5UfXoQ$JJW=MD(7^N5
z%U`+|-Q~@R<5mAC|LzQFxUNQMut$p#jZV67;?NQi%*Cx}u<z6tY0*pIjE3o(6%fdP
z-&=>*PvWDi$aC0SUfv#UeEX<fu9t1vfA~xV0+xxAcPh5>)r7|1psS*i0UtL`dg#6n
zmM|$!G7kse&!LB4A580SR)Eqys264oYrw#h#f^i^F0FZ)q~UvQ5H0`9jKI+#rJp?L
z4$8#8=H1Ys0WZq$SIG_(sl#p%Dq4{`6WHY~NL(2(nL^r~d2T&Z19ZTq-fNadPsK6G
zIeY|{B#$<G-@t#!5<eP~A*Eaysr<DyAEoR1c(n(Vr70`kyRm$zvIsOsj>-{6XZ>^E
zxnqcQq(pe+3v;kd^ow9ZQo%k7Q>wkl4u7J<jl9Vj!`z8ga;4`~s-8NuMpIrC$tc@c
zB)VuWJYKg<RtAC$*cj;iBXpxZAqUestYiH<O8b{7y<Z_X^3GIW@{XzcEm`Y5hd(ub
zU?YfS*kHGKeWk&bl@)1t<C5c2U{H{jBsTLVf5ilaOF;7pnY*GX24j@r!3_MuFjVD+
zZ@fT2-HgjmDGPCW9v~Y~Ow*p_-2YU6_cVpOOtr#3V}jO-oMy}f5q};!x^L?8$F)hI
z&37OvrZro_E{aicS`(EiAc*)A?H*k)gbz^CTi=)w?6hGi{X=@%7Po+q3J?G~$a3qN
zF>-hH#neQ_Ht2B1v8@0qwc6!{Gh`xyHtHaMJM-eeKkaXZ8CW3wpQo}0mN@W0)8ppu
zQ5O+MVW5f<t0nRKssn@8;4^b9=8P91VQVY0&nwu@sMQ1Z!N>ug<E%k%ri~&N{Jk&D
zP~=py!a!Qy8(B0^s2#bMW7L{OSy_5!{QVkw!Ur>tzfgn)cS-ko-=SHNZ=8T@fbjup
zgKVKV{k_ZI?l0lR&|gAL^oqe6mDP|AJ;ism9u2qT%5Z7u3OLmSdA7uaFoZT{aSN~T
z?%A$kIZ(ePGgfTCOG>(*tk0cahg4k-6`)JeNtfEAYt0LQ34&#7LMucKLK(8a&dYj#
zePiQ#3uZKWxu&pgr0CbhMtZUQTUNyrP^_3AQB>-ST)P<ggP{S@entyFB~p!{(Mza#
z{7{I_c@3aymu*76^FSdP`98t4zZ!0YkrkgfAlmgmetm;cEYs*WJ5<4CrcPsTIL(;?
z8W@s4>$<o&!Yx!K!Ww@sCOA9pUK}YfYrlx|U_PQw%Mm{Lw@5b5{H+L2qQa(vrrq0r
zSYVyrX*5~Nf0EWVv~fU~@hf!9ey`G|xDeLGlIE}hb3D%d_5*BNzWXAve6Z{#$#Tzl
zTgG^PaPr$QeVpCK<+&P`7H|FCH6PA)=z1qKcC_2n9DwC3MXt-sbZnga#<{_veB(}H
z#kK2Pz>Oz<`CV)<$I0o-vTyHWVf_h9Y1Um*H@u#xKyT3IED+a&7m>0J6J>I9IKPch
zfCqZQc0UYrJ6o%)^LzUV&6mUe#SzOKSp8qDx}2O>RLgeZ_g1P+HhZH#>-5sH@+o5B
z)sx^ZOi|zr7GF&;P-558vWR7hq)<qQ#b{||JjM16lISE0@FIL9v|0Oc>gA~@gANb_
z<068JwyuD}2MP{1CLfyGv5Y#Suxee)+a@dv^F4!I)%a?*gjlwxSP~}2?{)tW@Y5{t
z%$T((Stuj|UWh-%g3+V3Y^LUb^c5#Y>ZK=}rcIMj)E736pN#N}iOIl;gPla9Y7#gV
zC~4~Dq!(yiMAV1q7)<TlHJ6y%HU}P2touHRh&}G}eB669Gvt|9xFyifMs7teeE$!E
zBl{926d!S)U!W-)^=jU?SEGz`g)>{tYA~=VqkT6S@fuX!xgNiRcQ!M@2g68vYT5-i
z%Mn(Ie9^PTO%IUOHmz@}8y$!R${WH`1}Zf8ebK3=-TTqhz_!Dz#rRc87gi}Xt9a|N
z)g9fJ<4BvXZ#)zqo0|u&J>dU72d4eS$^vJMcA2ag%|-mpX?UK<`LBO{ZU`*!PeUgw
z$$KU@#1fAd5-qIRqzwhX1xgZgOX`O5AOUP;KMbC<G}}8MK1Uo2M{8k=zQq4b$NBFN
zP+eAx(6Ic58xPHz0d`_;_I|ShP)o3#7U$~$tAeEH@eAD-#qBv$U(%?_ELi7SRKYnn
zxP^5m5uZfNTG1^?*~%Y@MCU!ai25i+*}hdHrhR*!qKWkn|Gvj~IIGy@5z*>>loBSs
ztp0IIGWOVP-EieEIAc8EHS!}8gCD&BBUJ$|mos1(T~B;kN(pOeF=@XVq`%JuKrUsY
zF1SoC^l$idOx|IY(015BDe^PI%n|2bl&!pS$>C0HRj<6eZneHWtpAd7ZG)cUj2}D;
z{kFoH8G>;!SV*nJos3rQX{5QRt;GEZM(Qs6<46Iox?Ksc;RqlM9a%r?tyiAieSi7S
z&WcMSwaiEV>`AIotD=kn*Y0`OZX|&Sm6Yt7<{Q{Lqxlsh)m$@apc09)T0k&9fR4aJ
zdss70gUC7fE{fsf74R8(80V!9{HdU9^2RGFAds#=1o6k<SKO;RyC=ArjKUUFy9xkk
zoPh-{)utpH-uZ!9?}<p66HRBaPfq&D$Kr!xbWy3GR!s7;D?jeCP$8oh6V~`|z=fb~
zu&PW_&8>ian20>IKVwKub4&!BipV994FbJ&UyPLyjA=pLH{R?&Y-~aK3@Y`Q+rX_a
zyL81#`o?`zU&0Y(_l2k<crXTOaX&EI=KdjS3tdlm7lM$^0s;#4k+|1nXDR=P;H)t9
zG5}(`#GNhKJ~?|Sv3uky6db`vuHQdC8GPKn%=tdlA^{w)usNp)$mD2NqkWj7tyBrN
zvw84k3{n{a;fo;UzzV{~ebhj_fc2z6x=;ilz3xQ?NO>-8HCJ7TMuN_}<CJBq($|%_
z{=e#oHE-V%-!pQ$LeM{S-D*%AFpsP&+!nfQ9hvq59&u2-1F3-I806NVF%XZzwpCOW
z%sJ(US(}UJ4i{(I5t_3FbxleL3we4=mqWA*l9LTLx0Tc_uq)hNnEH0VIP0#FG;o?8
z84X6z<S3s5`fhT7<SOVwS6uRAdZQcV2ZOzJejgv)gYVjf1iAr&!Op7iQRtJ>3+0I5
zvZ;FdaJ3Kj8g!JBm|zUXsjz<@z+~780&J?JKuTOB%k#|=dYB6bl(FHTb!30aUR;1u
zhfxbfb?rQX2k&j1dZig4$dU-Dke&v{a{|P%<k>Jq@uvjK!&`v}($%uuC4UT;&3p6f
zc)m^*JW4AEpjtZ4M$y)qkl$zd+1u;hgicog_T)|(aVabrb#`_w`HP3N?lW>LPA;r*
zd`d4K9I_3E%2=Jd!G7;*KYg_da;+^N0OY=6yrP%8#{$+^4`MW+FM!)4u`y{2S@k1+
zXh4m55OGujX-FYL$!h17FyX3z%NW!=Ny{pw7kCNrV7$d!8X*rr%UElxt#Zn7@Q+py
zBa>NHtw19;;6@6uzM6aThJODpGsR0;xO0$?3A9g!GRGt67pBf9>F3YE-)LwXY~j@x
z`NAZf@PgWfx*`B3rqIv-pA$^~Q6ljC{2l<U`ha#By{s&7GFMWoQScp=$=ivudI%Av
zSh)_W@_KtLU{Ubs2@<m}4h}NgoN?Jgk!`6}J(n(2ahNm9g|MGCh<kejnD)zfz^DDz
z9s^bIz;gTmdt~{ZKz|DGAv)iGuwaf-=V0${?D)+jMNALwj}m_n#3vsIOnZjQ>co83
zHga9`&-8aG`GwP**awfnpUaptKgRJW>ff4z=vE3=vm<~uGhCJ`8kd(x#0ZsCY|8j4
z4^rtU`FtOaX>HyzJ=5j3K=?aqb}<BvF1P&88u_C1k;Tr5vrK>auoL9YSIgPAzMH->
zwIYO%Y-)_-x$Ip|l)D1WQzMm?koCFA>dxkEhmg68)SMyy;4^Oyx9!i)Kmu=|M2FLN
zFC%`;x0o^cUUf(w*Q!QoS_Zl*=!!hQpzYtcK13<m??MT|7vdpBGV;4J9$#%C_fS!Y
z{Zi{$3zX^GDXpswAzwGu&%%<7fljcVaIw{P!ML$hjIEiXzF`6eR!quxHD0uE`N2Hf
zbyPOO9WKoA-u*ynZN@F_q#31?%=jXMQj1$LIK_rc9~%Ud=TV2|^CB1pIwgOTSD;;h
zO1|6;af!RPmJ`4=MudF{i@kAlRAcG3@1L7GL#tlr#pNtgnQs7PPPL&-qVXk#61#(x
zoC>dv%tO{d5ol-t-o;Y}XWi+YqrGWp{u^Dl?H6h8$K&usPS=x<KrpEI{10U+Jo&fX
z+9+Uwkb(?>z~~t$_STk2%P3H5X%9?oaoUo>>4WkpP%vD;r%sZkxJm$8CaFuUrc~#^
zkRlvb36CV<9gJ)GI?CF9Jwrn^-LX<&un4`d(W#t>A$6-)YHRLylWWF%hg^8=%<KHN
z$Pu*D^<v|*#he>{2uT5O(V1~Vn#Zqa1>9cL`(^dXJ<<gNZ#V3cC<kQO>cC?Ql`SuT
z>isuW-7}hlQ21ZB{v}(iid=`<*is5@|7(Q|-7E|1k+vj5*TbwTA%-)6rLCLkTw)>n
zs$t=_%cA0kAR#3+YR0|H0YX6kwdGK?(S0ymH`UOwBuC#-pD@tUpOY+$=!-4idM`q!
z8-yckIo_qw9Hv>-{@M9;-P!W`ulmL)0FQj^7vM<pLmAo6&MTkMNN9IKo(#Ugo5ZJ5
zh)_p=VPm<;qTi!lH_S>K+{x{D=fSIhVj1?2=l~vbb@LwtMY2aCjWCoaFV*%aItW(f
zrBc=SQ=#kc2G4OS^76YS*flFo(A$9Msw#k=J^tcRhb}!b)S^;t;p~(jtbttaV7Y&i
zvwZE&mVE{l$4TB54m~c5_<39NAq*<6#Rmh|dqWbKjrTzHpTvmN<4@7{$|}Gtxg)qg
zO4U1xDs?DAXir3^rQPeol*`*Gl*kM%pTJ`7;emHIh;U){gP`%mIqtsShu{%@R4w@=
zTzIve=eGaN@3;0tT<C)*n#<`Snf&y#6;L~le7LEiCd-j>9*R=?UXdG>C9LYjIoQ~N
zAqR17zfJ5)pte!ndenydDBVB@<mf{JL){9{)8{a%6ZFR~8}zzbcs63eP%oAUjraVg
zWffz&LUPr(apzqTW*s?mb)~*j<cle>p9A#eFAj>d|ItU1pXc8alm<a`&m;GT5Fgd@
z&Cy#;du(V&h;vu-gC8^75bWVrvFHRIxoKDICO^FXJK>8hVzVqui1d0WZ1~9-?QnOu
zVE8O#@%N&7$7)>5gF$EP8R(9?Ew0=vBzF><01{@@TUEcYs`7wQB}vXf2hzR5>BPl=
z4-wZE`%iIO(gYAyk4M<;_o;?39PoMbAsSNeSrVRf`8E0k!ma0^i3$BzwbXE<t4~Sx
z%?z}0Yg-0^vgz_=IT{J-%qaB!%Eg_~xAz<kJs*m!CXZ9c2&cY#d>W@0)>M-|tX!!(
zLK&;S`Hk}tKY<#*6XR9JB_0z`A&NiR9WJJLUL0|JvH0v|*WFMpO*2iBb*hK&D7#bB
zYrh`Jw(M%2D=L9RuEl8SA}xR~YUv3>jW=iQhx9N*nHR3MKM1ZJaS&GMN9_J#nxt-2
zf<Jn+uH#skI?Ehq_rrbATVbCi4k20EK!3RTYUav`;2L)s2?m`!hfsj?ily?{gZp<N
zinS#iEgigWR~C%70Fth`VcRf#uRvBGwIjzwUde>9LV;C?!>1}J_?6;gox)-@BI#10
zxbW~h&Q*Rmc&O;1Nhp;Cmz@d>FA;=2k`%ihuBI;2LCx&@)g#oaE1a|}vT!F&K6a_$
z*MbrzfPRvr!S^qAzG6Wd&VKT1v@_r8srSZnl$w?S?xdTm%CGzBKNhTuiw>XwHJXN*
zQ1%Mp$=IN9wLvxYV3e-|&!rwXOjd4cT27W&5t=`{jX8wX9FX?7_4gnwP_rBqMSXWB
ziVAl5S`3>6!8bT*o_AXru|K#XsEKL3*11%WQQA)G&!a*YoHCjv)$u%T?>+^yuQn%g
z>3h0vctV!^>oVV;PEX?&u3@yy4Kc$N_PqqrcXWu}|J^$~@lmF+2$fvAT%onL)MxIS
zu7+^dz{)c%Ls8~bN}hDK8#dgPd$ECC$JbjhlpNoLw7%#2*CRA$FW-vXXy7Is&j`&h
zmkX0Eh^IwZ%jG=UK?vAjq#1B~w>|8JAQ21&_9B98^pvuYs$5P9?;5z4-mz-si+$px
z>Ym1S3NJ&bkTybhon&l*XQI8$ad;B16|^YUh+g7C3`$Vh={E5;eh4zlSYjSK%<90`
zXf?gwL`+0@3X&zGAj_g=J#B`-7=tftqm{fV&oLx!nw`PwN}o(pgR9mC(3XZ4Iz3U$
zV=n`dS3NQ|q3rpEgV&+>ZSc%A?s;_gDg(s-kVSmzyb~)T^uEbX=?uJC^ArkXGD6l}
zNY3;}*A*~%*%g=C7*;dZX8c>wjUS31B<f(lnzfQk_VL93Y`5<2HfF(twCu53`u=`Z
z?t6jJ(yGT|nS0~C8UB}M@o)uj@A)pd<Aw56dYD$(Sn8#2>JQbIze|_evXa4X-EWiY
zfe5-@Yu;gRIhm&Y(i8d9@e|Sc>9hv5wCcp~8-KZ`tzG(!Hq@Cc=s5kZ95URgSbA}8
zysaXg^b=uQX-lzwk8VJ#Nk{wThl1j`)i=`5=pbT281|ueldqv4>)N2&pFpcmY`tfi
z1BZ0yk6GbSPp6_=-a$4>I~lD&Ez9_&`A>$>ThJ|cSSGJ|Q*M1RUhlOBy~U`%cc;x2
zBB=4!e}hJ7t&ugYwPq(y@a}u<g)S)?{sQ02t9;B7bp81Y%(8(t5sOQtn;<N@$xX_t
zxWMPZl;6O0@%%$BHz%=2UJezkwx85k36fa7C=HLp+M8iVc9zGAxjL_<TMc$8#4v|;
zQrp>A%t<y$P?VxD7a}Q@-l-Dn6+i7wxRUJCuBFBYH151E)w7@!SwPv_GB21p-QkRJ
zn18~|a_{=1=%yqtzITd4J6`2)!YXXs4ATWq&>krU3u%axXiVU2E3WzOEPTmVy5dR`
zH%TfzA`-*?;s!4&N-pltUCPs$=&a2;U$U>4o*wn9RUCn8207u@c%b*t*Xr^eiSf4P
zUg!KqNwDRk!QovMyPBbRU+$wrTTV;xT^4bWm-v%;L-NT8&2^-GrhIt?`LX6pkgTY1
z!}s4JtAVAFyji~6&{CYvgVx2LHaiG{6ExOE_q{uSNs|)}{-%Q7Q{GmXT`ve-QMLhB
zkiVBpERHKL?ldvbG_sOn1%032KFop9O|F`Q-`S5K?)TYzvU7uPnXBL1fo@>^mJ+*@
z!L7NN0`?Ai=3*MSOjz;aubCGs#xPb^$DE#8hx+16E?{vOd9-6NTgSKQiR0)_rj8P2
zMwFQtbt+<$4o}flAvE9OY-X+7*693pTq8rCfcp4N(#Ffpe)g<p<tBBE*vh(2;#)Rc
z-e1jk2!?Bc><}s3m!A_-w_6M|Zut>PRh<p$FsF}g5p}tbc(!Fva@iF#%t9tFL%}9*
z@lTacm7zGF<(`qq+OBuo?sPhO+zZp{Kr6YwI?}BU*V!G<)7kOhWTe*D7sNFt*47Bz
zs@27ZB%xz=#U^V=Q)V}bZOskLBeszgzTQEQjlD4_Tpf{$s3?@y-_TirTMy^X*J}~$
zlb)XEbOf^`t5(~@Tz;nR37}4-%v`uF`Vj+nLYE_#*CpYdiBBbHLL2c(yQg8MK`ET7
ze=?*+JS9-z<V7K}HhmoRvcj`?*1K8I(&=f&cu;4#OQ_W!q0}_Gwic?@YlW+Cp39A-
zxc@>n3L<c?e1THuqOe_O=i*v=8SGXID^vh^Ke&7fXK4vekv2ykiFx8sGfRT)yU`t0
z3uAEhc6D%v_C6zttxZtl*?zDd>ZXWtTF^Ra{IX&aB%_PhEY<<FKk&WG-yBY|yDvA;
zZ$%P+PT?2ggluZjP=zH3b~=#i{TH<Ei&uT>9{6%|b=9xR64$3W1@;YZEcr=j^wS=b
zFFNNm_Fa5_c5vH)qy`(iAJ6)nV8DNRTaB!WYi>eUD~>D`s)9uH{xEBH?_T*kRE@BO
z90Z|e2sBrt&h2m|4L}Rry|(U!1?}<sB+Rw_KMRn-PbQ^D7CC%+;vF4^rft2c*!Sqg
zNPd!anb<uVLQ*y}dCsZL1}do5;zcuW@GWX7C3@ap5npxLp57`?GPX!&DiVoMM*cNA
zX>0hZlEGN!E)4nHbjG=d-uyiZ@>x$$G^#U!pFbemNq?BOT$}(`MY3J?igqfD6JEa}
zs4G<)Z~SMUumI3fa%YUSvcjPCok0ua6FdpU-0}fV_~Wiu3dz}quE|LAF)u6&HQK$4
z2YQoI66xKDxZ&iZyNY(%S+9Z7$NRCa_6URo_RaJvpzC^SxuK#tuFi_Lz9@O8R!h!w
zDAU%y8Qk(cD({F~-0-^hF({JW2VN>1NyoY}%oP|M(M@_5E?<=N`Or5JRF@o9^n_*A
zZ?5|_X<oedtfH&^aLf~9C6J!S5?u-lX>+~nPI3Ij#_bmm;gux<Nt9*l+q0i9+<4U8
zdS#)JDMZgYZHMG}UrBJD3pZ8IR<<(ai6a#TgnD}QxoBJj76V@nPi0`~Comf5Vz<Rk
z3$^{O*I~Hma&e-rI>jdYM_M)S*<MXZgK@<t?@N?i0q|tdj=Q&$z#^d~biD$}hX!RN
z#}m)=@2E4S*cKOuFLa-F=J64Y#qMfpv_#Rnw@6Y3&X#(d3{TVPtOua4?pyCp2!%l@
zJKevu$lV>x5lZarleYR6#3d*-*DnH7IpNjKn!dTYWf6N!xwT`R{U1%&7+qJ_bz|GM
zt;R-U+qRv?HXF8a(j-k|Ta9hoR%3sseZF^$bMMIglX3PrYwx}Gnsd!*u<lDFked}!
z&@7PDq>zR%q;n^ix7rT@niM|pD~Le`F+EvXFWj7aW73oj$v{R_MlC>FRu_V@!gaJ?
z5<fG)pG>OW@zt>(Z)W*23&hS_^X`LNhYCiCv)#}&(vGjkOSd-&agmj9HFvAh9VdjQ
zVl$Au`y=;F0UZK1cHIw=d&{HP;cgWxLiy>DsQU}t(y&1ZBbvm1j;&Iu@%Wgm?F|`m
z*T-6cX&!PbpMZdDRX3gEd2phRevTGMtu?gAaHcEB<v@x?pFS94MxH1vSMVZB;s%|F
zJF$}{0^;zO%K(qS{9~`aPxq7C&P(Q(r`T(si$UxvjZRj$?M4fS#@l|zAs0?lPW@(4
z%lL$_(-h5)E49{@`K3ci3_Ih~<(Id_6@BQ4;4EQ|X_yPIO=WCyCP#h{#)WvR=I0;B
z9!|yiWc_*}ICD<;1nVyk22*QQKFTsA8`Hkj-ixy48*uCU5lwc89;q0^t5o7WwnvP(
zn7A6|#=V!U16NUoA7HJ>58ms%Ac5z7-5KYjGsUKD<sRT$CSc!p-rgp5P@QH4p45KS
zpgXmnD%mEjgrufO;TQNl_zQ}+#0O!uf|a;9j(i@xr>z_J;}#!NEdR}V>9>*Pz16oc
zvQ6Ol_E_Yjk|#5r9NDbrorW&qKb`A}fyVk!=qFwT8H}7Xob_p^a5JwL6C*ZaDsLk_
zO=T|e=m^|(L6IQ(E5yO>mmeS`bn=Pi<J8E0@i&2$w$-CCnf{y06k+D2N_`LS&$^jJ
z=j1=LE0ebfNXy44x7Ch!?{fJex^v6f5WX@mmq8Q<4cjjIQEf(~^}+mJd1hC!TkW|W
zKUE)%{zQdh8x8s?OTSHB&M1=d*JdH5#PvCz*%nAs_tqaiBi&5%?N~7*Om6kyCbJ6M
zG3{lQmQVAHoNd(E80ajcso!fA?NagFyEb_h%tlS`bXZD3^_28q6w@k#@PRoiy3`TC
zNF(3ua?B&QhSzV|`3QMSj3?Y@&R_hKZi$mDyCC13;QS5t>o-z{B86TLvy9?sm!AFh
zANDAFRN`Db#V1GuQ)}!nQC~jV7SEZ~ep$YRg>b{+0s#eLW#tl83(~C(9vl7eMxg9Y
zJj*5`V*7y#<9jH%y*`QhqMyDh(E^$E!fwn!cQI+n)Mt#5&R?bb%UncuN{LSA6J)4e
z>Q^V?nCN^B@h!o_I&}mx0?KXPTxA-V>S(^M3q_&3NJ|kcZ|%WMAz##%y?g9xvwnd<
zQKSYEiWinfW4w{y2a`HMpb0|X`&(2Ee^ziOkxqXP#44?&nFJae5CC^bM_i}34tN)E
zZgi0JEy-T-`8`j3RP%=xAIcR3_4|8v=E(PP*o;&*w$b@RLULBj?dF&EfmdJlwBnNO
zeg%Pvpf*$F94{}JfY(9ntAN*ici)%6y6W;f_q{p-jh>g57pVfmX{-P+MhInLT}Pk!
zGrjn!)93PC6R@y)p|@DCwYQwvIrdN{>(hr9EmLqa^)Lo|{w<*1zjQ%c+~8V$JRUgj
zC3k}q85}9qJCMt)d_x^Gu+Ht7r@1gG85#ZI4sLtBR!b$^e96veb>Syh<unL(_+S7o
z_s0^+f;`m(H0(^@HQz*5ADoe5f5TP@rfIRt#g~KG<>k#1E@SWGF#gOzP!Swm6o%&t
z=jt)tA2P%;-bWSZI-5l0Auq?mQGUT~;!H%HWwP4?Y2wR(|MPTHSC=(_5|s-CG_v-Z
z{E?fA<5q&uI*NQpL_4uX341<=AoGzF%pH7qe<!}qc6{rox??%WE4rqNN92zv4%h88
zD+U^bx}<Bl4wdou;Wl2k;rRe?aa^sxr|WTzZX){+cV1i-<j=%)M%|;{*Q_r1!tKP!
zfCrz!tH%}#8n*E|0*D5}H=z66Oemk4ANXH}0)JWze@{bCdaEov_ASglCso|IKEP^U
zKKrDHIQ*_0XbBDeB6wtR_NA$Evu`NX*1hy}hThTSaXjW{$}11@Y#iRo6VileDfqt3
zn@1>$aA4HWKcKwi0U@8yDW%H&OBIJVSlK_Fzmp+LnLrBIU+#<*W=C?hTtWerlDE&y
z>Q~Qo%p~b+xs$u%zkh3XwFhrFz(sOLx{-%}E0R1>(IlhVRs4AS@|w`)3IQhJbm23W
zKz{hQCDG<z`&b_rvhTBWmhTy<;s_q`B@kbJGu?!4WRN;@aR!w}c8{N@#+UBk4sf~e
z#>AQ@wbJ6SyIy)*=Ph-y2AGg{`yKs|(+&LK`?Ef@IW86ir$X2j1%kb9Ca@&aXQ>5j
zP?zzbQJ?Tu3OB`*@6m^XA0#zURLZ3EdRh#<2?mJ-q5DHfn1CK8_*)f7NB$SGKc#Qq
z+^ec22Q|CuW5vb%;<G5);19uyv2z1=y^^1bu&#f`eq3-tT~`Hk5ElsdVELrd$R?^c
zeSsbM+YARS|K^PWl+KV+*a1757Dd4WX>Im8dmLPMA=Pv*F^p0lC1&)+&&HV?J%{10
zxRAR9WPhBd<d>5Lz25A9XsTW?-)5MuX0!?hALADu@vbElBIi`BPF#uWvZL82kk@7P
z&D~Ag7qw4dwJNjX<<Y*lCK)%GZo!O_!;BXG)OurK=;jP|z~uS4^4vPLHXlE{ote?~
z3DeCL&|l;7E{z4m%TdE_-_Jg>_*A=hv1{`hE<$Ym_d!$c23i;Cr4hQ`zd7)~)IpXP
z(<YBN^gw{tl8I?xNHu+=sN>eQ-<ME~CVs-KWe9?`^+}_yO0YK|DvSkWFkGglWZ-~c
zoFoj`1LeQ{rU(S%?GagJf)JF`ci2*Fk%CyPJGL*b97j}Vz@QO+qnUp!(G?c##$g*G
z)gxxPj>XBFyf0wzBHwK<iCLmLR!;66=yXfmaDp@8Xv|Pgt-hx@o|89hP5qFziVG~F
zRvO#i;^qjFK2b~&za<ok-Frp5b)h^u00brufj3$8F&jf;c5j#%M&rW&W`;Ew5iP<M
z20>$ZCd$T#q4g&DVj3wy0ayPMT)r-kjtXNu^p_UUvO+o@TJU{}1ASWw8>0dL>)!bv
zoRWXT+xlB`4n<LHxbxVpnG9G-uEnCVxEgRxPvU;ZR2(61K&9l>E+=Z<HL`Fc1Lhho
z5^|v(pnQhwGr?EY9<E~SDM#Zv!73ye_H^A47_*C<TjtX(;XxVoEeTL!(y)E@Toy%c
z)is9+K6ZtdW~4B;*Zh`0yT`GdwY$`rHhJXh4k&Y|(aL)5MhI=Di(u8z3|b1+1utNo
zOcI(QVY4=!jZZhOn)4B4Eo?W1!XiW$i@;keiIPgy#?H;4-KyN>EmG&U2TA={$q>13
z%x_{<66PiiCE)mP2C7C(=0fmi1Sl{uZ0`p=f;P`|-TWR(iv%;T{~6JL%%e84pO;xv
zk}_s0!ey*Tiz(}Mn7SC^Fc6MKRb0cus{are6TV=<QO{YJF>dPNMo?B4qh3eO9Utmj
zN{BeU+*%I+!mer7#ujD->k%*cRytGTe;;O40nF+>XI{A;?C#8qK8+cCPFfqj+nxJv
zaxS>qd>aY;#gxpGL46iKVsA9WO89mSL2cL@@l`L57==n8g$_z+!lh<`SxAr=hP@Ul
zbavb!2`!wNMEH-&H`+2h4B(GnN@8?#QyqRhh2^{Rm+y79c@j=X@4~<=Mf_JGy-vYy
zdvz)0FnB$9Fgk)V>ks*y#E2>mghfPY(sf>D^<jpB>XiJF>c;bN*%W=7JDAP504R2X
zV7OO-U`#<$I8MBPFA{i3ya}N6B%3^%*{Q*0;%<#j+Q-*#M^u<znO{@}ULin;0x_~6
z0kixvml(dAkTtlk*}=C^t`)sC5`kQxSIM}#XaM+2F2f`5tdS%4jEaj77h&Q&UtAa_
z-^tO(rpi@|yfpS+D>9FhXYzprVUal<%u)V~UbWo6ZmloLp(z9+lYsxfR$NWmeR!{J
z$F3Ne8Vom8BnIUl7a{@-6H`b}=lO(W4K!x1UYFR8Q0uYZ8Rg{2Q_uUh;k!aA<1-^e
zPm&vT5W`r!4!ED=2}S7GL)=<0TT#0XKW!`3GTD=Epo*i$54QOYZ}bvE)7RYqP<?@4
z9yX%;NR}83sedFT-c?kUKhcxgKpor76L+NnAM)&)VH-Y<>0_UzP@I@#f|t(45&#@M
zJz;krpG62zr{Y5#_CV?LA`LFNfg<S(y%4<l!;<dh<)>l*Y{#~6<;txvM_*6F9Qd~M
zNVN0k@`(ATBH*1!ercw(CvJ0o5?e~cbYpL1NIe&(Ta6zGr*vCn-4a!ysBd5_K%6X8
zvleNb0@SMuNO>cytZwYE%{+OZr*QXF|I++=*zP|nMO3o$@iSV!z#oTm^FqHY6y@Fb
zhIGABIJEoW7X5yg?Nx*+?Mkae;=fC^%nRq31Y@jifv7~vjj+G$D&5u+Bhc?y2VifW
z!T!a~-@vDsBu3zu-ZJ4gRP(5T+807|K#4T*ZPWuoD-C9~#q-?k<E|K>^qxr<8*lYH
z`Xhhae@m@(V@9Lo<?VCq*CR3?SrPT+aJ6Lv7D*5>-qj#C5KwFolm!jcg(L0y^r)|)
z6Fq|U4-ZD}4xll~bu4t=Q{!Zy^k%L&Z5*-16P)!A9#7tCI+N34IQ%|fTpKN+_?LRY
z<`*5^T%to4Q$A-bL~pMpBr+TF+r=~E%^q(Ic9sG0FYWwHBW#SXXDzu#uLF^m=3k%L
zE0m_>1Fc=wvWB475q9_hfHyR8J=_&)6vJ2tO-?M_I*LUeHjQ@u>18E=j6pWsI+}$M
zwfXIm+p_v>{AK)KEK)c%n(qRu2{piVhgin|6Gpi|3|)1otrcEoi0o3Ke<4*e^6Q4I
zMsq71A|i_f12(MbmD#Ah-)und3n0@K;(!H<a!4@zL}{j}YK8BMATN*kn7X5#LXqXY
zV~mi)6GY$T1+BXH*@~Kj)J!(skUOF-*B2r7OB1}mc?062V-DzHecgsUt6_IS*9(IN
zmi1ZVqIM&m)m!8E^~0pRDUU=@*9%c$ClP7r<75Z%%RBVoC4`bzT9+;1e*;j8-`$$O
zd}TivED3RdYZ)J1S1~h{1|Ei>Yz0+_LvVy3QgfoLA#y9L8L~-mVA=%|hi3zMU43-e
zFm8&A+mBum3tTD-%K|CPTv5+eiO{(eNB1xjRQ~5M#qA@plItE>M<pXx(mqT8&3L_4
z<#u^bDcNUYayK?RgMieYGctFE6?&eibAy-@B#pw%&}hE6b3ww8!OHn~0(<}SkqOeT
zO9bIDg$TSHfk9^qt$4W68KYG?Io%L@`f3LI^V3GSRSn~1JfLW%DyGq>$D|UGR`uWX
z>e=qbpX>}g#y1sd3SE=H=#XuY;Y`z(hhB%MP52fLI?58_5RQyfODof**qFc?J`k_L
z(bz<mE@$j-0`;UfRY4{~r~aLl^G%zBb4^t822-jafKMKORrmV%<3y8{oh`ns%J89r
zNOWj}YM71aW2P$4wt92c<q*r8mD3*sfM+##xjtXj9r}w73Z9e8BkpGCI{dQD#*UbM
zOfV$w>EA|RLMk!NaQo3GvSkcL1|(>+a`XtZ(cRB9!oOPy8Mdve8TRjU@$4ikXq`;B
z3jZn0eo{?^a}&EMZ*K~CWgB2Z^wA)?4i^r>>ZISZGEaCcQ7KNT4^`_A^pZv2VU!=T
zq|3-sBujND=q~|}2A48NCeOT-kQ`O#7<2?3>*`P3C=5B`^@T}Jz5(Q4uLR;~NzE>&
z$l!7wN7AR4rcbO}xR~ROYhLMd(prd}C!DYEn*M%{egX{*Eyf67b=6sdkn552MH8Mv
za=RAqSmrg{R@{FVg)_x)(q0w{j6WB+1q`~qOJkO&Q@_@O{t0!=iNmK(FA9Vu)$Hb^
zcpj&6IlY}f2++oOMX*8*&`kYy3}XQHt`D^lU@a6L%0ZR2;!b`92{S>MWe3;Nw}&2&
zAeL(^G;(+%rKpRTo_`hu&aj&&XcFPQ5$V&bnFB{!$QG6>w5dX*(0be|-C<Sy(M}9|
z`uPOSe`1<gygx;yxo%+MQ;1+}Ep0&eYNy3%=6t{oRIcB)+tu=M3{X$w<c1o5R%YFq
zii1koW7u;+W)O?8)~QBBFSh<&!)3^@DRUqUSIg~%6Gs7T40W2M<*#iGT`}iQ-`}lP
zC2%qSwmPM%!0!8k?u){vilPEy9z}nDqNV~rO<?2eIzKRN{NWJAJ{oNZm#2k9c%D`|
z49&nYjy4X><)F~#5WA?QNGal9btCh0ewmAhVRt+E<fO!GB`&^4Cww49c843Lceg-H
z;Bc#fuyLpN<aZkzJ5{dvV*)wHj_52xmXJWKUT078pURFqL8gvB#nk4gj<9Iwzse&_
z;wPRd-=}3$^D<FrRJnp3z?MOgAh$Si$}SzMttb+b2dfJ7I>U~aK^Yi5XMR6`s!yZi
z<i2sB)mXbx_=8H^R5|{jp;E}s5;nX<b66t~cA3xY<Rmq7l;-&1e9~tw_0>}ZEB<^7
z@G|b%yMp<lRAspjB|WWXmBivA?U-Q9kS6iE*T!u0B`uf%2~2`XI0;_ZjK~V&8JcK)
zri<CE7RdjYHT=ehBPO@myPi-oyvn?d@3FgU8VI|d+>io30zT%`-VsZQp?Jx{QPB8T
zv66=Sj8*}F9j>;nsvtwYP)`f~7tKEWPYl`Wion_{C+Ic0)~@oEhclMuUH`GnSlmc0
z?U&qhx$CtLM~9Dquv|&dNszpMvx`X$s8QCDE2$G+kxZGK&9H1d4UZDl$3BXn(E@Q<
zY%I)7d=}=kQzf%+WM~M#JImrm_%;}UV*OLm#%Kp|{bIo87;sx5Wr!oC>O$7mtFXlv
z%}0wz)bADE<OW!kHPuUyy!mfNBYQ6_AKL`HZHTu-0uVief+`Fezr!M`jLln6xg72b
zwQijx`AE$)Z5?&HYw~T4#@h6!fR!3s=n)l*+Jc{+T?zqV+Y3WRDny@hw%en;oX+dL
zM4pCup{Yyco=X`mKb)f5eOe#t;_Q1xoWh{^g#(c1l7xCC@DaqD_SV?p05tp&i$br<
z4s;NZGVZ9kJI`&cl(z-u|57Z~=;EERWXnA34TQa7$Jm`XOT(W;@ls&>hh$*ds$=^h
zK+qi06}e2w!|1s<zz(-i*1LJ;T|T11H7}9ZK2vv-f)dbt8&qOT5KS&dO=cEJEk0er
zQm@#$+LFJ$Q!uhn=^ttb6Dyfq5a}h1KRzwg`kvL_eOzc|XM5k!xzNa=qf?uaV?9_=
z!(@0$777vTeET40l;;R`#R3Sh3<y4=6#0D>QT$3Nj<?ept2#(6=5;*(IRguvFh?5Z
zI+$)EFBDyb3!uhgJ9RtTEu|r@Hg0nx5zGdkFFDykH`<4+V%d!@Uo9ck`usceBq9#~
z3I-0d!Zg3WsBFAGau~c#xX!UI?Lz<y)~g27j40uCx<S6}896{LlbT@8Zz;<LWAflx
zwGK3H+IUb8kDgBeuI9Irsk!INtz>iX5HYCd=KxIfUM^PeYcVa0b4%CcHxcG^=bQD>
z$WK&T-0z<e*n0qw6s)y1t%hwi^i~u$OZDSh;#(+de4*Il^fc$C?9&V7kZ4S3o&>qk
z>d1}WdjBYEyDKY_LZ)z|9EQXsdkjjg;m;i~oTD3&A(2BT#PD^<Oi3d?RPLgf>Tv{u
z(N;q7ntSSH;(tQ3L%g+QyJN}NDDjd4w2tN;pv)h=LXe&p*rnfSl=H$i<<?<ZVa;+2
z-D)3pvQ)eKiHx`j)w>+O2`f*6j=l7!=}1M#=0huhgH(3iiICWn^Z;s!?q#xR_HKkW
zVz!=OvdOMPl@zqJYl2hcme)cLuP9j9PAzLehc}WnMxT59w4|uok{R&1-FM*dcJA78
z&pyeaphOLlltmw!^C4Z0*ut*i#CaLq`xk|C{M<&Vmx9@r!a3fjs2z3#Qb3^Ga57TM
zaMaKChxS2GZ<sge>z%U)ewq*V*a~q_wVA-*{0+qgSvt-6WEeh&QM4#s<9es56M8nU
zf4@T*g~s~VCPFq=PgIvx)7!uTq+S+|XkTHVXsv7by4or{_=Yzf1jdmF5|g&_l<O^u
zPU|Xg=nFAPizitf^-dwkiB|vv5yZ^wo}H$BjVMyw3Ex1o>y^?MC;yTq_yzZu4s0uJ
zTUt2{3|F5oZu&`hAaU1RY|EERaPE6}3Drd~dQrT&M7U2FV1+zjfBQBwO7W*gQ&&Gy
zjZ^OU0=jPQR3ID8A=lMvW&i0PC-R9)_mxr;i87!*{Al;(4Z-ewBE&KOF111rF#_~v
z0fY6glf!#eclGR+kky3tRwT#|jM48t*tivdS+1&=!g-?(XL;I|Pl4;t%M@#jT2D<E
z2N@LG=6QXI*Sr=Q7YxD7^jNyIWVDwc;Cm+$Ppaj2puzz3)5Cm+4N}KryxytDr7X=S
zM>lM7K%~dSlIoQDI8v&?C5Qs?RC;hA)&EN35F>~MS<_9qV|qIirH(<|Mk95ob<!t_
zMu-g>ClMC>TTnqjlrfx6Y9de^WxP}jXbrpJ4L^`ZzI=z-kQHC4*x@S_4Z`X(q>@-(
z40VkMG{%8MI<Ke<9~`jhrV*bk&s$R9KBDsaj3UmBB)@RxjzEA`SF?KYvp{Z^`(^xT
ziobK=1N=2tR&hJdBmg*Z8<+}DPJuitGC{jPt8YOBkrPZCe<PC<)A2<3%0Q81r4_{R
zG>fgJ1C<j{gSkJ_v!d1w0UAAmqFj<MgDa&%^eZKtuB3Zu9rp?+P)TW=0tmatzQ%P)
ztAD9Bv1j|)9->x@u~4Q25({2FP*e>fiRQk346(ARV6|_8@6hXk-+V;+^R1kEKj}F?
z7VDkeo%eIZ<7ng2QDTJ*BSn6MVnM0=XP;dbwbUHLy91|7EX{!`1Ia}rAvF7OBhYdi
zeXj%SJq=ZyHs835Cm*#)?MGi<h|4l*y^R5BLT_zJ8kuh{QuYuaAu@0ux-Vsqy-$``
zKz>Y?gGz}Cl=@;0Chqex(S8mTgAw_;ArzAuoAbm+m1^L$LUfDheL;5K7YKYp&*SFd
zjmquxfC+c49%v~6d;-KzCExO}LmZHR1VRPVlN+G}tV2s=ztWU1Rt3_#2&_ZxbCF7r
z_H+;7!>;%xQY}fJ<G-x}ngAVwAYhLlPd8J5cCyi~{nm3+(t_t$`U@ERJ;Qy-XAI;8
z2sM<WBa|Jk%y^__EF_ZTOEJ#P2rV<D^Kng76?PG>({87&^)JUjdep>Z7=ku4HN6>^
zcA)@c^2WwVONwck>yJQ98~}q(ywM%!S(%rzIbb6IJ9gRB9<yoR8v0>j<}-Pg>wo&f
z?Yzyez<&<{aiW`qcSooFI@-qqsdI*Iqt!bsNi05BXv!mGqU*zK`t_Gqq{L!8y1gAk
zUQKBrJuw9edH|HR-hIUezGnFK1T)ib6{HFYj&tP#3ejmbnqN@LUzLW;^aoRPC@`d|
zX@O_tA~cAahtC%Kibhui2GILrqvK^t5ej|zA`7&_d$aR0WriBpVCxg>Ss*Oo0e!e|
zvb2RFpElwq6%f^?<#wC>13kmuW>AqS(4Ln$*8(+Xzc`9i5^H4^ueF+e&Wx@18~Ab%
znvIV$urku3T78H^DhT44ch-`vXS_kVpzFJ17*81|0w?xUyaF>#jqO32_+{(GGHGGd
zU=ZQk#}3Otnr6d?XcG_%7z4w5CxS>5NZ>rZCiCJl8I<bc7p1Ke#)NbA`rA~vUkk)!
z-p~Tyy1VnT)s&#1o9oS;C1|@Z%+>0`YW)lQ7oq~R{vl|tMA-upI^ETNY8V1A!1uJj
zFw$C_3@W;R9NS3F4-%?Qzbc`^1c8MvCUEq%IY$>v(|1W^f^91v6lT8C8ftJN#0P_K
zIJ6>Ld$fXsKoaDFcQkd8opWHM@@4GCTb{-lK3-o-Q^>W&h#|Rcql94A&sj5VR7p(P
zsb?3GU@)8_RnM>(JB=h#5FyxWM!>Z~Kiu@7=Lu?3X8<IZd{JVrr~f2Z)^J&y#rcM7
zxH0V4<|cyc8g_7tK7{YdF6^hd%M4r=Wl+y{zXTpTCw7t+Pv!q{0iZ({h;~~{xc>Az
zaP$>VEw~|m|DzlZ4_&MA7Q{eH`UsFLCzNT`k$)uF_cXn*90n@a=&j~i5y-8b_$YN;
z+G%{%RcLYej=9$A4L?h+dUSO9*(ZR@%)Mk%78U825WUdJ7wNxS=j7H^i)uzEYy9b@
zo`l8St{^42k%mTo%iPftPr$&O2W++bVohA3W%oB^%azlzO6Hn7brzvY>j6+d_jNT9
zxw-59NBLKWUCN(hzoWNFTsD;nkt|tSVA@6w*PH{ln<7}<UGXe)y-@_jz=_texDnPx
zirVYKG)DED?GsGPgISkv{GnX!v{Er2uve@Nb3Uyxb)QEZ#)Ilk{@yUoW$R<8ehD5p
ztfdMZPq6Xj=7$EP%*&E|o)<T&dzxSB(s)h>T?&rod|_RYmL{GX7ge~LkwBrAum-<2
zpoG=F*eW?4@6J=9CG6ayACl5<Z19bSu~l~X%{MT+2#NeOCK?|J)@`MJ@EHIJ;xV#2
zpVb)idu_AaavI^9`Y{3Gi~qoel))tCI10wp<pZm^(FO+Mln7d1`RikVq2hVgk3Efq
zQzIbi=m$z%7-?x-q8e;;LHS$hFC`4f-}-)ZgF6|lpqZM)RjiYj#Kfw-sN#BTp^x8a
zlYxrPulJj$mgH~jP?1a>TnCpM8cm%)P1_O<n-Y40APkCJsh0dLpv?mF?4J3I;t@xs
zz_`zJ;pJk)7P;P^AoqH<9fh+@Z{#mS*0h56#-pY(cR=iX3MZSvQ_@Kt&QTl8<xo(g
z9qYBL1@RTQEuESX4m+P{9E$Y?zZrZ2*?NeR#wFl>{&l(%q-pokX<3t`$A#|gdW#{a
z8=PO}L;$K_j+VL{(0zcc3$+OQIKHB)(AxP>YX+hNF$T1Cf=ko%+Iyt%@Hic;AAIH8
zcX@C(sU{Oo5=m+A5atG_81^#_HZ@<%&0H<rtT9^EUc^k2afT(k@qb?tha;9hShE(h
z)nvz5=qL(yX(tRH4TVnr4$|uv<WiP#)=4uYj#zWR1k-?U&^Uy}x7D~u;BX`&?r`1i
z5Ex{8UTNDhT};&d{jS}Esj+o|QHnK`4AB-|i75H^#bxPvs4;fO<(zY|uza81ph15y
zObOfJm$!liKxOi75yk}^Pe%vzf(WBVJ#7xENw);e<}=O3+l3-D9bNxVTNLnQyq>!+
zlcy1L$IocJYR;zv5nJ&Ogl$fe*gH&<zg?6=)wO=L$WgKIKaMKqw~S_T6xS^HJGtUI
zA@t#Q@NL$Wc3_q$jBlOH3#yI$2~Q8KEX(-Td90o7nT!`f(u$yhRZ>?Sy^(t}u=lwy
z9HObz2&c6f%WMyHb!}xrK4x$$<+5#Yk$pzg2Bh4F`c%8)#1ajH6>hM-DR-CiXQMs%
z*8HZWhzBvQB%aSS&bh1OA?J}y$tjAvc_{+><=dfx+UmAPbW$${#td(B!@D*!JzMi^
z#5vNG4Jpld;_|`%3*l+uz{>W~Y^J|qBEir63a;Q``^qZReVTeJ@aBC<;>nHx<{{W6
z$jby1BRTNoOGIA7QK#tyyUq`f?tT{WVNqMpI|QZZ;xApC9+~z!IBjmFC$>Ot2h4Gh
zsdmGRCPw&KE(el26#?7%zr-4}6`ePHD1~*(2ECv{X1mg{w(*3GV4A2SK7X7LOGUDo
z>JDkB(Ybu=vIqAkKg$8Qg1{hENfxI+Fb4xvtgi=c8N`M!2$FbfTzoJl1W36n8a`#l
zD&R`J!3EZ3)psi|84X`eFZ`4;2bFcMI~_ojR(l^HS}6M9-hZBd@)Z<>ORacAYTGrI
z(>{H{M6;1awmE^+^F2Py!08NPSJV?O@Uz6-Ywk_T%I%+VyQ{JAaYU{y#h~kt!`6W~
zhcQdvj?1eLbVaZ3K%_bVp%{PjuM+1at;M54YLZISb!;-ZIi!e)obTsvK9>J@cJQ;G
zzZA$~55@OJ`RYLg(`EcLjd$?%`%Cwo^yFz}Q7);Jai1<<kNxH0wbqb18)RS}r^r1?
z^U=^Z(#a48xMPO!&1aD9jBqDA+vIsYw~r2XQmEegt&C50l`92}oed-rKxfM_ev{Ie
zV;8aYDyK$qnGiaB89mOEQAJl@9|~E-?@ICzx0z7&mG*!ReH&ktiuF;H#E|YkDB4J|
zhomIXNth%g&}r3y;`TAWV?mQLz@#hR@i8GjpeRC0fP}bI(5TJ*32y{40P97*Bly+k
zt}|%*(7$V$X@JM5ZLG!R1Iw4kQ}3l9TGnWK0&h#0dH)xbPULs4K{Ur1kZzzbN$3Rf
zbw_?+V;p0Kmg11J#V|5XxUh@XjjkU|qnMiOH3v;7uDF8n+WwpUx1kCqhsO>tMAOV{
z6?MoGB7u&J(=_znf`^3ayJqmh4E=OtnP|Y<)&*pXg)YqfAt+H-Z4-+-K18K5(3dmD
zgegJK`+U;Z;(YRH824yDK`7+wLR8vIWt;Ezh9I*gDMqb1ck#oUPeTp9!}jvFICTBM
z`6RWSf@m67t0NNDj!_!2tw!)mhK>r}^vWu<(?i}a<E*!Sh#Um%_WRlz6jc~$G-72{
zCa!jv`h8~twvDYs@7BuZ@ey#+;0eSrZN8$<72mAUfxaQbF+H+bbUF{8j9V3!l!VGp
z3_=z<6JgUXxmp8{X6<hF%XwYFxE)kgL7*~gfoMMKu(z`hw!h#H&J77#Z|MC7PjFs=
zK%36p>P82ty{?^d_2v!^VoLCIixzkil75h8p>}F~+3(inBTYl_S=NW1z^83`1i>zu
z1dhrD!yeQ+okvVMtxSPmo!V%&pZI{}M~kAIE*2r-PEi{;lTM0|r=K4M5g@qIn6Vw*
zBY=-rb-Xc9?SY8FrVGPsG4=@`IRbIe!=|;d7g5=%?Vii%oc-|Q8m`gYbf*_p4k-b^
zobV$Q2qndAZ;ErD5}W}7CaZ=jNYpQzY6RC_*}RG_eEYX`DMrTK=gdp;Z$<SRZT$i3
zUbu$wo44jovNq1RRsJ75w*)+)=m~;>N*t|~xizRr&}WtO(kYbU_`8)sSoUxFRu^_+
zg30}V&iHS?A}8DQVW*E|Z>=uxD|%p3{%~;e_evGqAVlIk5vIUSV{rkrj_n^DL;7)g
z*D7d%KD}U9f5%41PAsE7<3)^W=HUxahW)R(ZBMqYJJZkrL<vC^SkqPZM+P>~>&4#?
zJc=9xQLIW0c@3GX4<xe+f7VfI>w(|)*R~d)|3X|hgw$8x7tNDe_t4d!4ZCBwC}pHt
zjU7$!(FF@@gR9YLNDmSfjg^(FZN=+sj&tvI0TdfsowQ;xp(LXqyAGxiahE*vFkfLr
zFn&$g!W4k0vj@_BQ{*Nv!XJd7A;p{y=T?cCuQQD*2T`rMf7yJVL;^7)_;nyiWotKW
zl)^PRQJ=l}b`F(S(S+}6nyhZ9PRo>+k<Nu+v3cS1k>s-M*P~`ei-U=dAMl>taOSdV
zw#c%H3UFf7kp>op*c(4KHktT{!boJ)g}@88gjMCY-pjE+37-B^=D<wyLKqG^0kzy;
zLo-@W2hCWWlBLABk-)fVX%MPw`WV|+9>Z1|IaH=g>CWz0J|v-l`R`PPV2WV)tl1SL
znd5IV`f>mK^MSU~W`0WP_tTB4*KS-PO?rs!pnnNI6c!d&{M9E$-2MWe(EF`!<39Yi
zD3gz6<~8#A&8Pm;M9hH7B)Ex|&f-MIypOA`;!SKnxm_8M!NzM@ML)Ef&ksKjD(F%J
zyWS-qY)9GTX-+)qV4duEj}8&`qkZV?*Z0RPY6S>{Sr0q4j=2feC7%IkjT)%}W9@Vi
zU_-z3z@zv{E!(Yf%J4ks4*-%m+e-^Gor)GGTpasZrp_i<G3a%XO~jImHIk^)RJJ;1
zTG{Jf4-4yGV`LNcJlN=KgIxhU3p3mFlOMWlS%i`HTo-I~pPla~=k;`w7(Q+mKHi|P
zC|m@AM-&BqU!<??4bKdtqO_;)xOS)Kq8v2~*t=P##=dZi8=avh3onFbeSBYZd+J(D
zK`J5FF>1v=_Xpy23XPfq!7Om0pYpxyQy5?o<bl$MUml)D1)%ww$S7@oeNv3p+j8qK
zV;1<Rl(4nM!pfL5Ixx}2qRN;sUn5IT3#-S+v7d2Ftxk_uw(ypC25S>_JcPXISE}zi
zwJL02U*kSe<~?&zX@7IxL@k#>Q^+yw+Fge)ySez*s3JQW8QT8w1};28Sw{ep5gw*h
z09ml-2hwSt;iPvV8Q<H}2W4e^DOBZM8f?<zchfWD3;KOWaZ24|USL;!amrfU^nFg~
z&%64=Vl0EPvBmH7=Nsz>xrJkj-gcH_**68m%yc(>35FRk^=m<|h79^{=U?fk++=pt
zv56iZmPUuB8#1M_Du}s&fnH-ZmIiuQ91VeZV*7nS{#U|vXM7mahkvCS9$^5--f;|Y
z*A>BP6X7l|tfP;+zP`_fAWo)(ND2mdwOFl}O?tF_S>}g<g@Rsaq=CxIC^I5`v!+pj
zic3O9g^vrWd0sF1l$u|%OVzq6S@Zp30MM|;kQF2@ms^O6ruyFZd=}Wq2+zg5(WiHB
zxYIXG@$9YXC*Tsz8eZ88e#Ac)F>G6i)8YjQB|zm-L`feGIhz}%T>IcO*mDHkTZwDu
zLC;7aIypsxX75i>+U`e2FJ?p;DGEv!jS@;GuJQTIi%+~1I2MSiV8UdY*|WHVk6pTg
z0dRC;TM9g7ipv)a7alVW6`K7ua7LNeVRysAV=2*Bk-r`{E`j_v^US-`hTe2X7Iyfi
z!eZ?RLC)Nuj6-LhnesHKmrI<4r^2riv_!)Oz1ds20^zCMD)+P$@W`a7M4$Ox2+7JO
zE44w4#zbsq5p*&wlxRMgIGdxC${mIu`$s(>NCx&$(zqkkPSc|?8J-OGdEqN$f0wW=
z>sqGDAlaHaHa!yX$3gFn$<V1W(&nJ7&y*Sq7oOgOu;m+w*n9_RnO6e{RB2B9(Ywe(
zC|W38G_qFb$AJY_C}y}akC-rI5s_@w%YL29=Wd=reX-9pt5A&w@I|O1Tu&O$PaH2y
znJi44$j_k9%NSjB(}N?W;O6)RaNEFl*t_nTul6hj0h)owSfj0gK#CnSdb{E$#fyEd
zdKiV*22EAj<dB%lf-UJ$B;!vXEMLQ1r9vGGNZAmy-8NbGimbTf$ltJyJxaA?kc?~$
zg4H*v2)HRFdnV!E9z}hBT(}>)khVV^pscL8aDQ>Zx^8|!72zY5Mhl;~%iC-Zjk;!%
zQ}pa^q|LMB%3$A>;;UcsnM(a5fzag+pk;owXOAL?VcnryIp<#)^79*TXR=M#))Mso
z7KHixaYrz5_rJn*kmc(sCuVnr&z+sxf?~Gt16t<<GVCHlIsg2NTtIwJVkWnaCj+Pe
z+7gZ@&df1QbDa;C**!kMN(g8aOF9AqplKb4psyv??V4kzKN)8G&<a6clmfNP7T-);
zQgKk;O~4gKc9zY;VNJ9++_h!+zCBSWSh0Tq)ue~NBt3msOIt81r;|c~ATt8%4_9F{
zSthrK9o*X+eDkM;nB|rQeau_8DJ{Lex@A)uZnmSQ>NeP~TC-1At4Z3lThFVGJ#5zP
z!Z6Ei6iH9s40xn%+4k^{$BK#-r@Gh{29m}XI>HrXp^ssI@l&(hm%n@y!}l4Wc-D*F
zN^5M~$qJ0jmJG;2`2JD!e4+y78gY{yyQ0Kx!EBn}+r}Y-@?G<=v%xzu2nh!pngoCP
z;3Eb9AQbISL-`u4yR`>mQJl#tv>4jc14$srk0_C(|FN!M^*u<n#L;+bivP2uPfhb2
zgi^PJerijo<By45$tO~$37RPr?3hmj`Qf5~PST(Dv*i{+xy}y)?jmUF&@<<Vmx9P}
z$_$OS_-*n&`bPUgAP_S~NpmL(oL(N|eW^l38v}i*;8!V0T<nQK?~Y)2X#PPJ_cen7
zPu9K{Wrp|V?fpeY38^$#99k(WOPaA@jJ|_Be~C>)1}O##U@)A8;uHp(<#^Ch<G5$~
zY@{};2;_z5I6k`{J=YP>&W~r(FoF+&B_-QLF0lv`e*cgab1}AG#YMLcTjAr)JUj}n
zWTDpQ8Mxil-=uo8y2j2Y5tkPB9s0oR>KhqrFWKjf51iH=1jY_Ikh@ChnI9KcV9ep^
zZscLce^iVj>QR$OMOq#;G&AjKmR`dc?n@PC!WkmUneci}&JXvE0Iuo7fC(eSfr`{D
z;a^`ga8Ud54C}ki<v(8chpO1TJwW2Fy#3s0$*;8k;a@zuVFGn!(zeO^=|Bnkc&t(a
zH`R+NdS0fEXMhZ9*!zu|=<{H{;O1#87sl09@1pZhuHXm%wHRQV+&tx%8i=EMJw5?Q
zY$0|*45LRp-Y`kw&4=cv;nB8>lcebnopx2Brpj)J_xY~X#Pa7ALq&D}VSbvk?x<Xj
zoWfk<7%^zk60l(fu`V^CzmEc-nr1|}l2B?B{y}ADV#tEmG@Z9q{@`PUVyKn}IPb?#
zFa*>~Z=a6kIHsPF!9-v<ZHI%pY3Bf!yvP6u<v>%_`yUlD%f`NpcO>s(gE3Q~>#40>
ziNo9DhXLWm_Y1A&qz(?)*DafG@(glgTQj3orq<q-f|%&FF@0!=M?`pm6g~l=icG|V
z4X1~B_&p95&AC`e00u`mo_%h0Y$sVxi|UsA*F(i=Vta|xuD2sMXL7XJt*8YFm@_DU
zk)cFC%cD8x*OklHG=NX;s(SM{;YwHyhEzL*%`rB{0l5+$68N_(9EOxnb?gAVqU&-G
z#iWMYVsOBb*i+Qz&IIVk3xN74-q*h!)xOeC>l13IS9##&L%u7xnQ}Dsw?iXte}&RG
zz&hE05<Q7$b-Q)XFKU}j-@#6AW$`}c2A)q1Hqb|7LzLu%l~jo<t`LAU&28@hU{)#t
zYunZK`0@6=&IABbd9hT@2pw-4!dGt{g;LA+4-PtG&wbuu&&l3y=je*;daH93K6)jG
z*>Kz`g|!qG#QuHNK(yzYZ-nO@$dWtxL6!2?;P$?)tg0)fe;AiQ&=c+4Pr$v(5Cy`G
z=tAspTM(m;XDnX91jw7h9p*Y1ec~WNg(ir5Qf2tO_Zb|HHX($eW5I<NlR(`Fal0qG
zUibls0=bnZ^zpL><}DGSIQM~HH|Qb4F1lDo_QMBG-V1DSm=jHe)ZZ({>F)(Sa4``m
zE&^<<qOZowbO5d8zzn3M9!tr1wJC(2!09^!dFYw)zrcHmCGo1eVQOfP?s`i82v$jg
z<Xu;xv+;TxH)V0-ohcw{hnpdtpV~_LJEqisvZ7=QOM$(Xih$Y+N`cx(r`!+HcvIxu
z{;80X8h(L@<!R|3Sm~!5@f{W$vBn#*J@vFh5B}E{yq^Ql4CCYpI>4z(qc;@Ob&3OR
z$q$nhUUG|+=Q;Ymqr-&t!bkv@iIS)gSR6q43!M|wRy6Y87s0WB2*(XGme}I9om^PB
z^303I7y^Vzg#I5`{icQ&@J9TB@MMQ1X9H8u7)}a?VW!OG<`(%uBa;gdrQ>~hV}Opr
zsMAYdpyV>h;&p<PlBn_E0TUb;A7tQ$a9fbYTyEZyAv51W7>ZJhFI^B8lrw7OP`^E>
zX5FGR5V4q0_+#;qX6*hQ5J+?1d{D>x>jAfnJLmzh$n*>~8JY^U8~}557*Yzae@}If
zC`^yY@FiJDk}4Icm6ie|SW1M^f7jPD`vH*g><jR23C_IKA6P0f23~02b{!zl)CX=Y
zOM~_IDLOy4hsfPSX{bmhjyFxCtqHQR^TzKYXBUxg!<35fr}b@bJmk}u8;(peP_qj1
z!|C%Q+Fg^=MuLe>!vNQB;JXG!ZoT_)9>23b6}Zu-Naf1B#8H4co1ZxR*AYX7Zu)>!
z6s86FA4j#NP>W{AHsFt8qFzDD3^b<v&>}dZ%wM8pEhBvL;%63jKa6v~b#Cu%bSt|g
zaO)Tn7%Lk+3DsRXH}cq2Ghz)DKbEm)%Qcb>yf2q<2M+POOXP>s>~1iz^ISu!F`>3A
z=TcIM5Ivv&?&I}wJ?V-t&{zW{EJA{a&|pfGIr_>7p<)u^JMu7LrcEJq1xmdut&@&6
zK?5g1{I*-FxdHK%q^I?nDK*F(M}#X1h(w5gcrzFXO}fnEbHKAJ!}wnUAR0+hJkm8G
z<Oi^VZv*Ea8>}yNk@2Qo(G&N&RyG;XrV1qI%Bg7HypDNoH&kpb0CD4<G}#vV!SX3-
zP6S}_y)bu#*U0vAKMjFf5g(Q6u9xICgA}UtJkFm27D4W1>4`f1WV8e)9e{wtB<^**
zsp;#8`;Rn@h0bmeDv)g_)NLiyd?naz;Bo>5zQ3BSzo$PCKLD)#&_}=%2e8jOaFi$O
z$U*?7GfFM>e{Q=+`*5A_x$j^%vvq$N<Z^ica9Jn?m@Sif(x&0Fa6XY>JW;IZQcbV$
zLu$`}Tf>7(n);%~T}$8;hnxMvPL0B0la&psk2up~`Zk~|^o;wRZ`J8_8hUzW`5>Su
zHs3T4`}|D+=t3T>C|gWYG=Hs1N5Kv@Dr~xeTG1Ws@f~ApVrzquPMdOdL(!o?U?d1e
z>x2wi|5Kp=+=3bXNI#iFrw`;4$K5pWlltGJL*f=&yl(n<VrJpv!E{p{@&h!LM3CLw
zqzLDD{J8#_%Ji^&8e<?BJlj#O=a|Uva3@Go;;g=>ae>S}FFbl3K_6lu?!O)4wvZe&
zK1uoP#Vo_buzN@Ric=ww&3(PJYh@SrY(Q;_VDGnXb$U85vIaI#wI=M5>LL5ph~oPv
z0)cxtwT2@feIPC)KYe;MKnAv-TEZ4JJmSuKBD+<W09N28e*KruBsvX=l%B1NHd|*r
z4g|c@%f-oiX;57&n1;k|KFbJoz9n;vwCbnxLIUZiC&nl+=pT3!kmWzTYrdXHaD4qN
z`}n2a<1^SeZ>p88NI?Z8ICa9#zM~Mn7T?fB1t6OAG^sh|e*fTPW(9@l{DGYfn%B^V
zUa_7n#l&DrYaLX4C*48wJzA_JKEI<1QP{8Y?-9YQi46gDal<<|m;qQ1$p0-GKH|D{
zVG|1Y=|XA%m|M&E+H2^Gh)!;rlOowp%@Q7PgC9bpad7pPeqg-%PRv6JQ*h}{;1;X=
z17K$-u3$vRX+1lE1`9-A^!WGb;(^;En|H1VX=vcp)Xqd693aFKW`1s00L329wzs+%
z%Ts%zO;e>#r1w}XGH|(Kp#s>G$l%oBBqJPe(lDfVJ5CDJ#TO>B@T?<BfIKx(K@t?e
zD+VRhM|>Qw!ni(Y`%b;D-5A#OaZ|N@5V6QloA5|YfOg&WflSRhh2E3vcbazjjnN9U
zKOk6G5>UN_S;i~W>*>217p~Jue53s)w>8d%c66lIpG004DL&#}%2i%rl6Q(tqyD`n
zg*VK%1|8%sDUu8CJ3i}ew{@uLJ8=@QCF~i@x>D9-j^|~Ha2l<!{+QVqV+1C<wpbkp
z@cu{LZ#{MmKi<({tmCQommA|8Kjs&mZ%(SI_fbD2deQtpnxL+`UYiC{ke)J~MSm2E
z`AYsZYTq*`=yU%0z$U6AcvO7m9lt9dFr}Dp1rfDCb)tGkO3?jV6drK&Bd9bG2v!-+
zMDT8av6Ut`dFBa!_74`fgEMOTz@u*4oC3F`83Oixu&=}TG^e-xn{h7tq=BkN^ng$N
zKO3VVriG2!Frmj?A#sWw`TCk&?#Btk0Q5z{<`d~JKm5gmw##zQ2X2H6yW2EpJLkpt
z%ufS1Oo4S88eCHM24m%WNg{o{k+nI>u^k`xxx;3%xVGrx7Kl>@dHNVxU2U`|XH(;M
zMUPJtxCaM1tX)&FjYnlTyw)V&BNvM<62FT8Ey+jKl}4ZZ5GYZvxDxPzIU_pMqw?z(
zL<^=B7kGeG|K*q}=la=?AwutBfd8c82w?8vWB9?R=XVJXw4vN#Bg%U1_|{bgVg21;
zj~Ibt?0A1+S)`<9K0Yc##l0!zGV&-utzO7c`I~uzfe53BQ|M$STG<C%;|!JmNYs`V
zWu8B@f~)mgLuFw#**cN^V2;lc2xHIng{T=2*FVwtLDs6XDY-fep3${$1f)q&+2p{k
z3EUrfBYLnyBh)$|R=n)_Z*qI&H%@rGK75=KlPzqGBe6~J_+P~Z^c6L2-2C82BT&D)
zJVFVAH3B;)y2mF3T!Tq3)QTcID{YT1aC&T7p?70Q_cVhY<~ORHZ1I*;F}&ju3Qnbj
zFw|jNr4unBE7l3E&M$<E)I^xRiPp&Z#jj7)5XSmCVVb5#0Ee5XkK7JE<l4PvWWJB_
z@?V}^os%sr;6@+_3SblzI&AJ4ycM>T6^w(G9c`#-ViAi5K7<=rLijZ`+g<GeXT+yV
zFphRZE}`vgl(T6PfXGG^hBPXP$W^yU7WkN-n_}*zf7LIxhXf*{%8Oqo7bE`b0$qv_
z5^z5&$23z@QwOWq0M9^wr^%Un`0wbJL<dXcC0fl+Vf2?dg{v25+RrA<{F^1bIwfk1
zs+AhF>Z2)i=E0&tbydE(4fyoE69vGebk4i|jjL@0JY9lEmMOA$%xTUv3w0UPh|xqg
zi$d#y;6L%~&6uXTxbbk)jnH%-%z6AX56JN^vQ~wzhJQ5ZW%;#4O7wh$j*Q$X7wbV&
z&J*tiqT={)W+jWvU7+pibNrR&mYOf=Hf^h_mzuwMOWN1(>@{Vw^lF|tgQFt{W>Non
zW}H<09~S^4qsQii-SPJ)GKq_QgXxH7NE@<iZu?9tX!m%sj<s)IgeejCp4h#d0(|3+
z?=c@yNj1~<Z`lQ5_cBh46qOBWll~_OPZwOBP1l!A!{3RP{GWr0gYIvZclJE!#Qbav
z)s@}_y8ISn`#;;3M)YrwG;V%^qbY)rFR!eeI=wTx4LQ@=;PJe?t9Fi=OBYS!hg@ZD
zv#1WP-5{KNHSk!IYxbUOXyRFX(~aq_zrLV*kfGev++^Ok;qp}F6l+0FXC08A3WwEH
z>2-E*k3Y=o?EmrMu|w3CEx*|y1G(kZ7UWeOYl&Xju`8gs+ry@?Q&f2C5gw(pv?TKK
z9OChL#keu*K6=kTp<><2^2by$JY7qtyFS#LsLPALDLjqlF?|Z18O+Eiv!9~mm_m-_
zy=9L1@e1pP?=|Lg2g3Q+@}1j<_TsR6_@7yu%nLgFsRkE<cDwdsRfNv>sh(b!4RvEg
zxw}WlyRnmU=Nx5Ce+txWd=yVbO;BmnWm4!QK_VXspYIXCeZn*3HRK`}*Z6O=>aBke
zn=dLGupZX;eCJ%EVRW`z8!L+QoGh)YcZ8Ou=}^wq-a0G0{IhXtiJSRd>hkp9vD|9X
z^t}gtESq;?CKZyY{hDa~enL}%)!3U)3^m_wP<fLIc$-d;cJG&8!q%<YO74yc8`#gN
zc5yq2l}qb?s;#Jv64LFPj}X5=?Av^q9TY?&=kH2+*W*1yrrAF~W_RKex}sG->9aUB
zNWWjJfGA37)n;~-w~aV1yi$E8$uSh?v4gk&(RJszX2skry;&fPtwfgxU|y2%Yj6HA
z(5%K8zOk$W+RrrE&j`hL!=CA#GUw3rlje!G-nt0Mrn*l|3v{v9EEcD1#ccKL9t!zt
z)$X{}Y0X^-YT5hUIudrA%%&?G)eGkbmNH*-(}TQD1>FOxS&RLB@R<#<W({QoWR~w3
zt2Q01*dX>+Kr_-ZdCItZ*F>6GE%yoxtqX5S)bOi#aR=*^!~NCQ1_tycT`i8?<4abJ
zZgQC+Vk9G2%vsjL>9wHGPwnpPp(9lWYdsRZi&^#Xxi}9_?K;_^76$O&_Ay49X&**5
zez^*^*J)1Vm{)gp?C(h`_+_b#XpOJ+Dxxfvt&SQ)u@?ToBrSr+C@Wm1TegS$CY3FH
zQqOUIdg!W%kFlGOGJDX*^EQU8T)MYeeH^B4;6wj}v!ANm8W?wD*r@RZxAW@Z)TsB>
z@<k2Qjq#3Ul9>ENe}c#PYKDlLBsRL-usz&;>L=3YL)wzp*D`Dk*u}17pA{L+pIOi5
zGXoh3g3lO4PXX&_?8!QZ7^AAO3UNJ5cyqg|$-u&WMXW@;ZjcBmZ0?JsZ@=~A$*Ixx
z=ZX2xJ$@A{Z>oU@SCLHyLdeT3HBpaZhs-KAd#=AmfSqaeN<TtCqCYd4E|r}n3|N~i
zS5b6UW_F=kyZiYj_v#*g)rM|oYNZLg97fUdaEc#BsudH{+V!MdyC<K`pmJEX-*J3^
z#qRJA=c+XteWQat085uh`87N_x-`bkp8c)Q)Z~)Fy1}dMeA<vZm$YP6lSjEv(K=*8
z=#^q*@1wHLCe~m@q&4!-NQOMG>jIV&;l-@AjYj%}<I|<0&<jp!QdHZN16{$y-P+`7
z>Vb5&!W`!F8xH>d<^cWUaq_p+ByBa;4;N?&IaWVy-_z6{D(Fxx{GDG2&m!IAlY(hk
zoi!W_3pEN*&5R33)l}wg>(iIHS(!USV*f|fS3pJeec^(IN-9XFDBayiDBa!NB_Yj#
z0@5JT4bsvv^f1yL(lB&LcMLEL^De*td+V)rS&PL2X5W3z-sk(iz0Wx^x_bRCc9>-3
zN+V8I9<lS=*=T3bq5$QDD;}-h?Z4Al61E0A4P=?fWjNzBlOk1?&0atGJ<c~~Guj_E
zmT#Mt^nNFDshnK1te1WKy~iwl^*ms7yfMyvZs+{XZw-Rtv-wZQ&PB<0Y|j`pi~a^5
zHl9xCibhN`!ap!3R+`~I8}^d7vR&~FjquC<;$XVv`#k{SPAMH66EU=F;m%-nbChB-
zck1I|#wE&XWcjaKilNqjwNA8GJZWKcH|)J{)D3hSor!+1bYxR`h}LmC1Ek8rAr_cU
z>z+~yggp}lQxaiMr#0(x$fuIpCm)qc6GbF8xQ<#h8M*k9MA*QSLVQs*^NgTt=&j{C
zC&V*Mf*$-4LMtypvlWca{@Lqs+n<eY3*2{<`64k_OHT?APjkYug<_OSwh3NBSBtP1
zSW?kvzF*+CEX|k&?i{)VqzoNrD~SB7i4&EwvJA6OwJYyP-&8>}QuaW69UHFMJS6(m
zyHsz4R-dv=Sf+R&*5t`d7u)1|D&ksy$y*ss57+VRGj~eWeby#<Cga-*Zm;iN4;{%t
zH%hg%UpNdSlHi=H#oC!TWkppIIVWO5<jC0BTT(%X84iR_gz9lH(0YCWj%~@K9r*@a
zpGLWxU3cxCJ(i-af5;zJ%eJ@I7I?<P;;w;A$chau)s~P5&*iG6NMOX&mWd0^?}K{?
zbFAq_tIHrbYAYQA#;&pT&J{Dfkx2`^VZ(w^m)?7NW%x3TZ_eUg{b629ndm!>6+2@Y
zWc!!xPcCx3_U#Fk*mN(kVjJXZK8q4xOomlIuMkWirEaVF%ih!KRoftL*rjH+q~8q+
z^u{_uK(i#nq<u5zD+_c*Yf~WYEsoN1nVdfZ%%!oUTX{v<N-&?-c@UzNtOzyni+u}+
zD1M2Zd6|JXon`57{tXI;31ilxsqXk?$5jQKD)=MFRu-0I6SULrm(O_y2Xq#9FCjx!
zyj)1SvMdpIuUY<MW82!Mdb#uW#qr%SRk@7{f+UJ#gKJ(~X$%()w0}h_)KQ;ot{?U3
z^M65NY%Ay2H~ys@5<X-xp<+xz49daGI_AM+(#<V!y`$nsI#%ootww&a)+)7-{qH_7
zbk%}};}}v;Itq<V{b#k8dIb7@&Mm}z5R+y-G8cN^L$;J<pB(1nEE|8%^fZgUk{D-{
z1GL_2P8m9WHm&7fsjg-6c73N;o`}h_NnOhqNIqh-z?)cO$+%s@xU;-a&R-hnk4+B+
zcVP@%_3nJ6q|L<;8f3dZ7~$Z*nU|nQnP%o_|MTzei{G?Vib6&H-~_n_uLf@Wrd{U3
zleSH_0*Y<+OVQQZtV+#20rzE-mn%ws1IWN)Xdo3wFP_Xm85cIVsvbjga4uq>E7cP;
zb}GC`njvu2>Qxr)-0|gh#u16Y*Crc`k!N`PVuKNBd-gA<m4!;LkAQsGz><>M;{w4A
zCY$Vg?8VmQlcZb$^-Qi;K7=t8A2woHq>gH540;-G*x!lRftO$mL>2f7MTa#>3-@zA
zeDm7w)7hT{bzdzkUS%wX>SEG_^gBA5XF?G$X#3%z<j=P26qBt&s4r*ZdBobeXw220
zf^r^+2HUsuZo15;UmrH|?<zX#wzvG5xMbV9fsPFib7^eooQUw7G&tq-Y;(1@C>B16
zr?eX1=ib4to|jP##gn?YQ@MX$sDE!T|M2(bi1N#D3olqHK%kL|k63}9^ndE>yKaSE
z?nlQKvwumPRxk<pO4NP_UL2*r3R9RBmX2@T@upWBS*Pr}ZvyBfPHWBXiv<Uz&U)<b
zr&-1^=P7Y+yL%go(MA^b>u+hnZwy^J5|bW%ll-9iyd?Gmbha3hjdH7dYm#;O48QIu
znN>xjRBN~XY-N29R9J6*-~UQk><*9Hz0QA)J12iKd7l|zSmXp|BDE^|Z~$#z%jSmS
zNn-u&pJNDwHwI?aM4T>;-pn|xYzwouC&F&J@5lF~{r?S-Ty-x$&8mG;(I4@o9$-Ei
zwD=Z^!(-!4^>!>(6Lt+*M_M4_?%wU*L09K;@?y;$4ql&#($gpc%q26MLmY`bjsuo(
ztmW%}Ub;>GNkIPVn!DJ{E=EP<+`OQ(F7jT(H2K##4~L5&gNM&oH%n>BGyH-uD8+gn
z<BIl2XyB?cC86sY=xr(FpgMoJGXgIWen>2RQ<2L8>~B+kZ3}o`N}a6qd<b>8(gF8R
z-;V*VqFB8_S95ve&2c(+4B9Zbu~Ns%0$0yq-SFr5=6H>^BEM;%n+1Mmb~;*=(YFgO
zLXUozP0w)c0m~xiDmb1KR`-egQ1xhF2v5iUjVJUtTXLzcv9NFtE{FKQ#rF#0Ow`)5
zoXHpImDY$b9IUwXr-B;hLN?f0`CH*+^~ER13y9x0^LT;f`G93vzjLb6#6sf!ltrLF
z@Ubsr;~!jqf^=JhGDe08cqDiyQFOq}BBL}H&(S66ZJ|2+s=nJ4D=A)RUx7KIkC53)
zv9o;yP6z$c4DHEv&K8b|V5N&>)RtG&`4{mkd`3SQcx<W53=4L#nGD;n7<4K{<ttjc
zrB7rOhhu(;;%4O;YRT+hlMJpd9Y&ADahAY>EiLzdJhr$Q{E}Q{Xk+f2j*;V=c?#2M
zYATCqByq4fGS>T;S2AT^YBx(S<8wX0EpmNrVF>vg?*iI&XuE{yaMmQ|z}~#%;CD*R
z`Ff+*bysg?J@{+7${hiY`xUP3u(74Xka7aK$dhJ2+4b`CLQYn|bQ^U|_YnnPx~?)j
z@snd8Ts_U(_KU$E^}pgCX?|bzfZ{nmxn2S>WwgiDs}pLvndZ*_igOhnJ3kdUp7A`@
zHq(H|HuC4RS|<65UZ$#7)YcHeG4!;U!0j?=ihe0Jc9>ef-`wSXhPAKhU7aYm!>Oug
zOxJf}LFbS@$F{X~j<*hEW6O@)1rxc*3ohG=yp=;M|JmL&zcKkzMfe9hC4!zEtXWXq
zEodJ<IEQA3>i~C$$6#&>vY)V@IpQI-iyY>Nwrvzj?axj6=yHlM&$vkm?6=&pA;mXS
z%xTK-zj87{WYiY}i$EUZb-;Q^WnIrfiP1KZzkJdKD~Ds#rxiz|E6+0+di@z!KmpHA
z<v9HH1hh3KBVOwzeqo%PCNqsbMoGq)iRC%sj|z}RvfhmY62bQmb}=R=H^YH<DzMvD
zi8Y%J6`cBNl4tbY9URZGbMDvQw4WXFvHN=o4mC|yh9G}Lxj-7XpmB^7haw5S*)IOb
zkMh$O5!G2uwb!Rp7IbmL8dM56&*n?XhUlrS47WyfOt$Y3+YNW{G6e;}?Y;Zc)3`4;
z|Aq#v%3z0QH{yso#e^Ezn~xu7W&#;5n`ZWedgK}57d4T}Dp$f(MFXXF=?X-z<Lvks
z3`M=rE6z>cGYoA;;yeOf69xXv)g2Z^8n+H@2f{T<`!0ozm@Y2{#tm5J>G=6Zv#fXb
zE@NI~w?2^wDi&R5cpJH)h%W@^#^ix%u$Z(2`C5f8%rR`)-~MTsNS_=N4NWn7YukFe
zL>ZM*MNf(U<msoPKD!EDt|X$hnZZl4azoV1g!4L)+ZvlxF`>q?b6)MAk0EGmnXR%;
zAm0sCDdF{3lk0bJf$KiY{=33$sC3wy^{X<;nhycy(E}SwdloB2`g+B>j!ueD-6qd~
z4RJf)EVe_eglLzxYqz3-@x$7gaYF@MAt!!)f+3s*^FOQEXg~cv2LH&#TNH$r1MB#N
zW!ffNoMx%u9&W{oY~Zsl;~ewCOvWmhmAO>aw7f{~xj*QjSX{0qF_2`(Q`mnkPAtR!
z$G1>SqWORm6vWYSmv=I!<2Vor8`Um9;Q3i4{%0ZPz5E+~WHLB0$Rz04|L~)6;EkX1
z1d3XdX8_^SK7w$8Y`puDKqHU`J2-(<fyfl^52+m#?N@(sa`IO;Fg)44-0}>Ch#g*D
zPHh+?{t1@|K*|rg7uI7gE=;^1I}v6Utn3%9%&zypDk^rKMjwF}nT^N+$0Dt_(|;wD
zd|uO+SWH4fmf%Dx{TpoE54{asp{sTNMtD?2jujH&$B6ORIV|fDXkA8F<W4n}^dT9`
z)ffLYMql|BLHicp<y^QIkpS$cA7qM2nl`g}pEMD<o9{lHBQlyhn_pA=$-*bexr`Ql
zK&sx~=_`@g`BUHk0q^xH6gmE+Uu&n1lViws;9j5izrJUN5Vx<GMBBTb=eV*k+{Bsa
zF=Z|x-hrKNfy)8T!D(DNky)2}KpYOigGX`vJcNhfb-sB~4=fg<1>hnvvG4Q}gl`{P
zu$bAZ`du_EZ*G{Z1sQH1s*!@O5}dNVJwBAx#Z=&h;Jy8-PG*4Z!}Hu1mEMnf9uMcy
zZoYY>izSn%X%27~4Vi!8o#FpRa-+1RfHTLElR`flBc0=SHK?|B4q(wSEJt>?p^{${
ziYrh54D7S8D1N?Qd^I!ESodh`UZ-@{`xakZwxeV46A;-U0^ZN^p6CPLF#orR`AIu`
z4Di?d#?syX#R1n~Em>OMa?9rgQ+)d0g_ObZS75noEgX3p+Cjun!v1<+qkEY<<Q_i=
zOO}!jw8||e+;e?EKo@IQPs-CmWZMvjmti_L-+ElXu+fIR?<>{P5fFpZ(OzzeDw!}2
zEiQ7oyAPFDObdEBXZM5-kn?$dwy|`K9++nwg#>uc>AeCB>_+E$URc2#B49Wrw%088
zfEEtWE8c)lIYmr<8`Z=OsAKv`HP{ZkJ7I-h@WV2NUf~EcONJvt!QQ6`;CZr^W7@_Y
zvOLM4@{F$0Vr${;u|Gm9R^$RLUjx5ubhM~`o0D(B#_{4KOS-nr_fPx8F;{AxvJE8*
z3KdsRT-xDX(NoT!@A?g<nEarkBXhb5HaSichlv7#X0gmEVbI!<oo-_HzBn$gi~im~
zDslNjZL0vQ7!)E9rPDQ<4Je8<I6pp9qi;%vcNG?x|85xr>6WQm-vKj&^RmN}roG&f
z=8B*7E1{ocrCW=6#~HKu%D=f+FKY4DLA7nZ1X1SZ7fkvYdH+7n<FWg`0iH625K#2C
zpDk;dcp+!+=iMxL^TjAa(_YJ3g~H~3)79RhE2nKax>L2vu-LeHRIOdfi{n$Bs7#rt
zN@IuEt@6Lm4)sMh_rjCWF>Ie5k63?iU5buLHBW2|r=5%3Rrg)G(>LEP!?0Qcws&Kr
zr4?1aE2@Mls^Fw%-#ss!=*ujAfN<dmDFV6GCcO2}r<%hnq<&c|$C<e{{s(w6i|-#+
z403gSH7c@rYD`yZh8Oj7_-<JVZ-zdCj#AQx$9lU)Bk|1RcnuO*SaLSoK<TG74vKLm
z)&=d|)x|AIyRWdRNkguCf~bFd9V{2B;M+F#i*m1md<5cf9$zLc@Z?F7uhX0!>|3Fs
zF7Q}c-zg2pzY-dev8}9}G&HsvPpK$3G%(1qatiovdWhOwE2bk!BVRcec_J}<DiiB=
zutv*b0vX+^+qSDL-*P*W2lpTN$L;R^NE<+}<9;j;bWIOgmi(u$-*9}gsEC$&L4!l|
z^louS_^v->EwJ@|Ba<o`o0WaS52&=rBx+Cf^_{pcvUUIVb>4oxPFY*nldbBO)u>r9
zecc0eM?|a0{RqW_=l46-r<rfm)w^XDCT%1}Iu+5gaq`|ilW?VaQaO0`On64$VO-zg
zWZA)mi%)dmE?9-b>x@C7Ixv{1UVG}3Oi4^EN8p*jp>=|SOS=rg$F9)@8bIEz?cHiL
z*__+ecvy5wVh;kuW$k*VYJ7@fN9sH+(#nprZLHRw%@pZ8k!SqW+n1V|ZRzHlK9FYD
zTTIVL@bXVBVi@2mc#>!}^B4gPG$EfiZwBAo_YCXYY|nzytqsZLDgVO&<a4?M<~+01
znE7$9cDb9gRKi>BUZBm<x@GZeP*JQA1s>{<P>>lvsl_vIQuKFeEd`GK+g-3Q^x5E!
zj>h8P>IgW|(={-(4nT5k6QXc7ESMEl*ti6nW$_M<S@R<cUoV`07+lM)o^gAa(Pzs(
z%A%*laiELcye%t7-=8(Ra@tkwXSbLu$|9auJ0dxE%{g=oI5xQeN&yy%$8^abFloBi
z3akAK{9}q0F#RC`<_tbRfFFkRr>RHA*KoE`Lz(y*tZoZYI6r!8KFeKYtzg!E>4)^v
z(?1MTnI`;D{Y)|(f|pSNQ=ZW$WiIne&B)3~&B>eHov`DvdKyhI!=$ZEucwzK4S^Hq
z(>f@suyP3c1e@oH9~?vkbasD-8wUhOx#Vp12jgP#viI1(2S8$J2)h9m(DI3AP8Cj@
z_J}}|+?jScXrtqHd?H0(`#Fu9Hd)0sndPgV`uqg%X?5pq0&{L)1}*>i5GAZMqIixO
zh|posnV@G2!3#4`&+U;=C!;dEpL+3&!!p1psdwV#(kC)zHKK@et@4Vvx(2b)c{pXh
zSncS=&OTtDP5L5Xn8_T~=d}^9uq^C{fewF6%XOxf1cWZPZ6^)rgRj7++6U`S-4@y2
z#lB51b0|p%lG5VjYqV<mcjN2H&9vutcPqD6FKg=?@E(P4WVWL<5?)Cd?PH)PxN|Fx
zj^JHN&FE+Yw*%(E?1$uu7+J<`qbJ(bHWt0^xxqEBieiV=bI7SYXMhiXSaCS`VA*Ow
zT1+S`=`?`s<`uGo%Ym$};Yu*6YtTo^O!hq-QiDrZc!cSehAwdX$MybS)!kbORbo%=
z5Ilr*<|MUg)odSJr0tK?KJstmSrj?|xfDmoxOQ-DS*je%J^qq=j^cd(kCj-=&G*L{
z$?&7l3<P4ZDId95&k4SMumUekmEbt;{s*39)0x{ggUi+T+2V&O6fzga_l;$yx`xD4
zyE{NyTmNB(3*L+e-%YV2McUaZKs4Q~H3KdmqZlH?e?70@&E8&ndf)Cd_9pTv@S>bw
zEMxOUhdN{G7Io7Lrz>%V9n7nAb5TscQG1{63M(ywHSjXOt<sc>^KW83aCTr>_(M$M
z^$M64DV?vr3r5lXhj_-i)f6qhU^~3)mpouCv|Q<hRErngeBZuE>$~0@L-Ob=_~1(}
znpgA+%!$tt2XlUBh*r(+gg+KhInKy!G=HH?E<P5qvAyf@8?eL7)hAiGmG7XOLf6%i
z!xc+H`Kz#B2ag(3ClAGhCZ9wj5OHb|eaQ!k`)`2oV4J_<fIC+Z5u|6!<^RC~MEDcE
za5Ht^Kt&-6PsCQ#o|*Su8vV`RoZAS*E$MR_J|eP4BaNt@-eieI8O9TlKocj{N2;au
zKC9h=lmf1?%B{WY6IlGoHoKMB!ZsKR<e_bdtYeKzol=!(H7cq?O-5W{1DHiChj+ps
zjJwxpbg`VSiUgl@g%`iRdvMZoR}Nxkz%k)n%ngypp4(yR82`a4An0C=On-l(_uO@E
zsTiGgOa!F{+UXOckpO;IsmHI$s~Wtxpx>P%Gn?HJ)gIL_B040ME)VV*u#ZZ>ZBs$y
z<u5k9uJy3`>RcuY_~$vHLh<~sNynPcYh0n`@e9|_Y4JBSW$a5HH~s#3B~m|=I)}H?
z$84y%$15~4Q(gBz+o*|YEjR$%_J=CMybFaFEBOCg1Fz8W`*^fTiQQ2+>5*#*Z&<Is
zx8U;Q`rL=1NXJkoeGl>2Ek>BJ=6G&8F5RJ$`%UH72K;2>c&*3fm!m-9onw)Zey-5%
zb6~T1NGPU`_qK2qwy*-mXzq&5)-ASn<;n-2^xK{1;57QuIHpHc!UqRi&bK?{Wl=-Y
zYxj(O!dp+p66z+0#Xd(jC-m7>R-VR;1=!8a|2O{y@X8%2-i8Q-ute&#)ZHnchv`Ns
zNR322V8L!a2Jq<{%j}0h01o`X%1TapcGZon{}rqrNp*WlwU!nqnlg0LVkEk01VG%%
zRPQEW@ZVlh(p^zLyS@HvaD7^~bA2!lN3<E0>XUd9;)sxukup1!U+!1m@iU}om!=Sv
z=u~MiE`2BshPEumq1MOLbBL|JxTf_C&FZ%K#`G}H>KYi2K)DmR3$ZTunDA9bxH$td
zPt)w`y&S&fHZ%F{KE$x3rPaaxJQI*i&L()#QEqE}934B=b#EU+C_bs!%$(erW!p;`
z08@y;00J})MflJljXWdhq8Rk8FUN-~<($_bUHsONH^u!0%~g(V|5rjUrq?%PcsFCY
zjtS;>T6a5E2NHHw&EZ&L^#n`HPk<+?%w}BZm%e_1F+{n-ElWL*^8o88RXcrP-j2?u
zSn&LBF*@<ZEsHT^G-h8^`_?HrS^ff}i^3oG4t;u%33wOqAQyO#NuO+WNA(<tGGJ~K
zr|N10B!OIvGjeV(pvL(EL^|?XGCV-RFWm&;(_;cjT*>`H-p8Xe%kghDke41OEV#+!
zMxtP94LYjtAa>&}-nGje_s^{z{3T8WsTT9;{KQ0<=18YzKF3I-Y_Izsf9e}Q2cHNY
zIu<xy2t<=Rdo&JIbgfa_K2VO{;(0;II`=0*l5kX>u~8nMkff8NWq&gaB3asBgF&@A
z7mTKZZVP^-tsPZf`9{x(wYo*WVBW1RDej8r@|5#m+(*UXfH?gxNp3Yy5w_FB|4VA!
zb4U(sKqm{Et^8EyI3*|E>*@Mh-JI(n-`;{CfPNQ-wF{eDGOp4at?*bG_#C=@sUBBT
z6jyjm{iRy%yF*T)|3Oe^(7;KnB24a<u8TWt_iIdMLC$WAP|H;+-T`%&t5d%Z<><Kx
z=tc(=f=~bRF)P7i$KDP&ZZONbqXZ$-(77drsJkZ`$rWQ`uTp>uw}?uwRx_<b!12Gd
zK96cXd1$%bULlre?U!&@K%92-Jgj?<Qvk(3PPW>|!w2W3dQ$R_iCC7oJ1#C<r0K|S
zky_TY9h_pI3O|*(`)yI?51ZOfa-}WzvFXX|+6Yu}1}Glv1SAv&?C%(1s5P|kC>Tf|
z$lB+I=3jw%^|Fg8ONawLJlaas266|}CFu+?K<pu&DaMWNGUK6q0dMht-q(>|Rycm=
zGoI?5_QmAeD`=>B_NRyL{r~F)$RaGOc&|;AtSYZoo*0q;xVBdA6Ifrig3xW<d%r7?
z@Oye;k6tAdrBKdZHKA(+Fx%eSJ*LA;>pj5$@m#|y)!*90X~Z^`ZkaWuFYGt+Z7aT_
zfBw4^_mB^cEP8QN?Y$+2nJAqD^$txl>DXsHsy)4_rgoJ;t-M~mR~4<Cnn_lQG|t<i
z9)aiGB)$0IOCv^eSnk$1IWa8To|ld#SXP6(y6VX{z&&op^8zqk?IPE(!yzsg^Fy@I
z;2X&#*LIGsx|+Jpx)CD%NzeMdo{IV`sB224p-fNIP0n1^DwUkryIAZp<{@P|DvPR+
zbVadVctB*K`jK6*q~C6rl7bE)gZF-OF(vH6s<i@q;rF;ac#!+~1igP&ubp-Jv@7>z
z!WSHmRH_A^P&9eQx?thFZ;H^s-Lo$oyTO5aKJ9&|6Eaj#A7wzeGXG8IZBNkN0goj>
z#@m7OFy-I7k>O9Nhc$J9p65k9i|Qe(D;=9&FLYqQNT8nCe|2!46pR`AXh9;Ns?DwF
zWrdLb<5q-D%T;3_4jIWUM3_ub?{VxI-X$UgUI69K(sy75G@_-+T(()JL<a*XbJDkc
zA~yOQk)YeIfw1W4I1YWGWZqWT>lB3oh?9$<QP9pZ-}1p<T5@rpw<-QCiznAz;+2z!
z%Qw{C3l@%^uUqBF#@Go|vta|{3|PmE@J4qeR;KsCE6q$K#m^)y-rA{k`LY;+{7fsm
zf4b2Lp4o%mGoWGxKUOPd^!-X!LYY@YE57WfspieY7GvU4tGR;zenuofbC3D-=LDd9
z%VBN6?CcxpO};k`8uYfPdp2<-EkIoDCfXc$h#>|<x~T>Dw_AmLvvv=ug1b}JzmW)c
z2mjx+oW_IufsVc}t(bj~A-H;?9~VAP0=i1ZnV;8hj`?3dYh^z+&VN6d;a<@nnSoYD
zPi0mR%s4fYT>OOHwJs%dJjXhhDI2CjUW=lRLdOClT#!ApuTl3HpnrX7sTs>!lvm6S
zEWx0&AY+1-n-g@tg?I`1Kp6Y8(Ptm)i%D|Q<RQ-%)C?3ENBX;M_g2FjgF#B#S=t%X
zp@rQR*0IG{x<{Q8N&9V=6*{lud@gQm1it)xW#dCk=YUlK-n<Grembh{&gDA1URdS<
zd*Q<Il)LZWxE=dkmTIIMBwZi3$*`h!<#0k@0YsHPXQcXz>WQX?cG}rvuP;FnBcBk|
zoX8+^@B!W9nb$@2j}u)^F`X;FZX?M3E;_pJ6Ld1Ye)0ufiNuPZQ3I+?g9shl=!AjN
z5%=Mz8uj_J8|{|N-HmjkLK8NP-;T!Z<>DX}#KN5Lez1CBv^f99I~R~(fMY$(KF^#8
zcAlhaH>v#+*poMq8pCF(_iEH=zTfTNp6pXA^709rA<O1`dBJqvp_7d&leR}o$HKCU
zT{(y+Ao=<8C^7wQaoPO43-?cE-GiO43t}&hsFCYDp^39b&HAB#diH*x$8Q%VmwM*M
z)Z*-As$*!)UFWp=ZZL@lR2QyjbZ6aRbZh2G-&Xv+Xz7)!|H<Z8pp_+5V*N6FP7KU>
zll%)7`@*h}veC$OfxZE)1+CY8vid&vg0ASeh|}Tks?`mW*YrL7A}PfzNFzmcp|2N*
zX%uT#%kRy}IXhfFg}Q5~1cp92Ry=wdkh5}Kj0!K#380%il}`Z*_7^aU147tWNB<W(
z3!eF{4i2TPucU%v&Zwp|jMFYiaebYlNH$GY{E~JrZnaZfr(?!6kC5pJx5iJW6-{WK
z^u!M*h|78MQ15B+mF~mY#yj_vCRXw{S<{`l-{KrQmVY#JLzdMSP1@3V9=y!og)d>+
zYred6Oj{}{DlMesCiV^)Q6l|)?%uo@%slHahD;+xc32NtUlTCrmnba=8siC2&8Zp-
zHpgrTjQ<kilakm*kx6kY3%{R`+<z<oX0hBbIWHi}ZMyfI3(T!}P^|o!aOkKZrMh=Q
zS5HZ#Nb}HT9%p{+mq7C}W<J{F7<AER>w+(~Fg$|A($T4Yh7?E@f@zx^HF+sK&5xyn
zM^>cdnLp9>0;zl>9PE)!A$cs?G8H~DLo3xYn3|yVUh)%7VTrzcDb%a@TLjiv8!KL+
z$aw~%HuE*k5fq%v5dB<(uGy&lyU2=)6I=*{jhpsfdDs1rZ~T2)r^2p_Uv^mC*Sien
z)`DlY!c0%(B~)3g7=n*pn(;i}{ql4FeTr2s%-;R9qAsG3+-C>fW*0XDoGc;lM@^3P
zd781lcfziIr~WnR$jgIxJ;OGUH)ILd`mOrMj7H==yT>$Puw*+G4OvW{4k0qa>Y1V|
z475mry+&Pio!PVc4AwuZ)_%Zc0j>&D0*CukM&l16Qoio8Z?r$;*t4~<z*KCD-Xufh
z`m0J_)6Jc1f4}G<P%0{CZ_AA}84(XB{qtnkLetf-`ye+U>ywYxgiVZpn<O^bwm7JA
z(t3erGIKfBDwY52+be&J^HA#qH!uE*C<Y^sGc(WReW4v@A^x9_t-KN&m^j1|jJNkp
zy9X?xqbI{=0k=zE6DWvZl6=b$g?^Lagdas{y*D>f3|Q$?3vxYit;KO3Nj)5k`5X#V
zT>V$J`BC%Y|7fZF*c#oLDj1R*s4M~6>tBBrPT_HY6Lp^Q=zgb8t5bGQf#!(F3m1*j
za(213f4#>6XhP%S<W~wXcU%FZ64f<je*bAC*??gUvn-uR_@2sjdfU&<3!kJ9mD!Hb
zGdz0|`Uv#bOKb;_27o2Jd#QZM1c?WHlH-4Z&CxnS40<EJO>UV-&{GTWHze!+#Em(;
zzRI;Jeedg4Z<))v4f`E+`~!P3sk!>BB-v-y52Q*Kqvlwu>u6;aE<n%Snd)wL#3j6V
z6uSN>zfIP0?_wQe=R5sw-;LwbFXCLT(op=r$BzDjn>S(-H9;mPr<grb?RyWKK>#X^
z8!c#vWC6Z$`OhNf4ZxzyvHMqJn-rEc!H1F|a}Mg#@Yro19M4|i>vqIC|4ncpLXa-I
z-AlzAP;)#}wd<P<2tKix7@6MeJpy&uc-RMG7<sqIX+f2Fy(yyNA}kc^PgmHkxZ6#-
z)#_`uq{-Sk-+>cQcyCOkv6n+nL~EUuX#aDMwDx~Y*7-jPd6D4y!4lL96>)g{;wYm8
z;d<_PHvN_dt`8$ZekIQMZbIk!0*Zw1bPfZ2B82#nd%t%5oIFp{8xJ)GLK49<5&XK1
z=qa+?D-*onx1HyI&iSq+`PI5}b5Qq1a54wh8SzIwVbw`g7_g6_$6c#N#BEWLMBlSM
z{*N&}Uu1vq3o+pXi+v98ED$2_hF;{d92h1<+_ukDuZ)#klxTtfi~6P|6VOrA-M}#_
z&!3UCJK&(&iQ;EZ?#lLp)lg{YHY1_mgABzDmW4Ek2eY9iwxf<FvsJAe*IqD)pa=0{
zYob_vF;Ur)YHK%K9{+PigUSQlc-~mh$QII{q;2{=E5hmQA@SOv1Xidqff*b58c?N0
z$KWM#F?k}p-iPm16moko+ArvHw(C%9lU<|Vfr*ZDK0~8-fq2hm;uAEaLz%04z{%M@
zyxEOS*PEh-;Mp-}mS=pC31b!g#u$*;yLXHSPdPybNft`iXg+Fg_)mm+OY30i2ry2=
zpMdltU1^OZ)Oj%GBsd6lnuF5F_P^R)94$@!rOMJz6llJ3?w@meU6MFWGk)LE_OA%e
z*5V<Q;;!d#GklDaX+LXb-*gkB>F)3pue7a60ztdM`!da*NQThPpuyD@PCpjYf7kJ5
zHmnJQwpjx=dJFs5`epkUtq?Pt-9J&kew4fdWWKPhha+nNQWms$jD860nn{0P#BLgY
zY1}2w|2)yZ{yJ8L+F04#+|{VpXADl(enk*@-GZr!kIS0)vi4`_9Q=+tmyfSSO}p`q
zL;Y(D@9Ea7^-@BP4DTbiipWt~Zz;Per(FXJl2W*yp2~e)t}b=#`Vw7ii_P?lk2JQ$
z_gmK&1PkY~zn_YT&uJZf|AiuLIb~!(4s~}iT{2}K|K0a&6zSC;3cP`+oK{q||L|fv
zeVk+NO2qt<@u{OR2pr3hGBNAKG|ME6W2!y~b0ed2z`peDr`{sLJMxyerPgvX4*|;j
zRakQ)dzr0q=vvC`v+Y!>3@I-#f)93?!D?4Oe>QSTaOSEq6=hfIvb_rX%l8u=VL^hn
zIBcrAdTW5$b{TX0iU2e18!Mf4@u>*Al&JT4dohLeh?7AY!|jVp;UM*NdB~?yee1J+
z7BiO*t@8zwwtw|p%!efmP)DnbNkbvX0wHS1XwA%LxPGWS;~-ey_cm#8L`#X!#geH3
zG#ilG9>IU(_p#7eMM<3DSqQR&(27+mpf&!h(geK*;+J8Wd31+###Hc&!)V-uhG*a&
zFtgTB=`In|`<FeYQA1UejhKt;jgJXlK5hF$PaYCc{QTRa+w6+7qXPrSY(D<|jFHJk
zSH)6w^Klhrll_?XE;<z5d!MM<7he+9pY&XKwwbV)uD6aQfDZZD;f?QcHSGsBUZHL6
zeG*=s;q9Lp1?Xb{y?5xviU}E2&-sPZw!Di?&_KPpiYiM1<pz;|TkZ!aTq4)xwskaJ
zV6wre$4zk3QyHX+7B}o9(mxkCt(q%am2k(#rZvc)Q_S*3InxLH4!>`Bc&xU)?Web)
zRl)ZwUVTJ{v2WC)vg)~RA)AC@b&ArOhNeXC)T;nTEIx31-CX(XeGv;Bs$P{Rf?JUg
z2j;s;TM<ECc%_=0{FP=9FI)o2kg;dP_`bhsv9DlwLSyN3)F|gi399)+U6b{=$25q^
z(a1y}%O0aFq=&9Zy`sA9GwrE>30&g+REluZ6<J_o4bmlDy%b?a-5UP}Xea7qe8^Xu
zMU@x?T2~U6W)u47{q8EKdoY(1;LGwhV~(Jy;aYCu5$l6)=>=MAppKGGhGF<)eKgMy
zYXY53$?f4=v<_})x8GDWPg&^4JiClnqu*_WahLWfjwqh?bE~|ktn<Eqt)Nr6mBhLo
zO9|=FQ1RTk3`~OF4Q*NwRT^)Ex_};w&$Xr5#jI^XuSrvuLE@<BN4nmd7qn!-QG)xI
zye>Iq1(aTA9U4=;=j_2Ve`cYaNeG{ho`;@ixqLwl>BWJo`2;U_(O<x(?HX?O0`Dig
zJ5D-s`;zLm83@i*#L2OMu8Y#XrKYwIHMNk7{LhW(ZvTnsTL(8&8=rbV-CV2OrzVJa
zWH_~7*#u^LD>^u3c^QMgoO5~?s%B&K{&MOc(W55P6V(J_HeVwFNaxM2TTH;+^bvhf
zB=T5;%zcuu#cj=hkCQXm?fbxLmac(vw&7y|6tdB-s#On3JB%mY&{X|L_!zofU^2Jw
zp&rL+rU(|3{6WLv+}ddzn1J@Jm7xb0b+Ph!f-q`5oWC7O3UH)%E{#jB4fZBgSs+}Y
z7`p8Ii`kS}^|<DXE5YHSuXL@m4#gPR7A*9X!ZDuJqE^tQtpnx(3xSbKI(EqQqwJKx
z&xqU=C~J^~`^%pAFsgon%oZa$zO-94=!FA{_cA_yaT4SDAn=;!xc%OGoztCOg@cp-
z@Ex*8K}Q27)gzzwD|jDw{1{gkk}Wb|T%PE2O&ixL2ZdSeo?UiZ__MFhS;XZ|^F6BK
zuI+t&=@+p^L&y*}qRR3PqvtRr0(*$@D<7IT(gB5?WPiW=_-=X|nn-HP$q7dT{kW@K
zD6Qttom6z*zQC~B13yFiq>TgIT2cG}E#foUFF8C>xQR>^KG*Z~rO`7a1^yB4t#h{X
zul2~iCGtKvIle<GG$>iJ-piLMzPb`lpjqj4_9xj08sQ-+P=|88AXf}(aXXuOt0Ma4
zMW_mKVW5O{^n09qC3+%7NAH_4=pfjg$jI_iYS3NdnP>%f5=$XC;lk-V`$UKVpMumM
z{rW4e0H+3{G`bj;ZnfwaXC}PVv9$rGwoaLc`b)jKdVk-tzihzrgt1asG6oY`Og^>|
zAxu+6rK1-U&tbd}41JG^m=7*lty06O<T_oHijEaOUn5#{C8+V>^>KSj9qV*!d5vS0
z)}}Qh6qPfeUZ-mj!Ed1SHts^ncfMifb;eF?()`(LD_!u2ew5bB!gJ^gzKz+&1^DS>
z4CW@Q!!Ab%LvN*(FGO#j19@QsBi^XQ>GxianZ_coH>hKgwO~~vwmN8aQX%-1_VTOx
z%PgzQ%tJ2Az5UyE6`HO+s!E0=r>)SeED;z@rP#MYU+qI%#dnjfADyCyY%z}W%8$_#
zJ<llLHl$@suruHh7{;gpnwY01#?K1JmHXd6SV=?iI$8ghJzf#%#ZE#mDCi1#0h;$S
zUXI@chFOyX6i}EfX!}$0ySDfC)7wP-Z-wG=25h8C1R}k6F-^=)*Cpmn<)7C81OAqO
zC2+SD(B(z$HaEyRk`SrdPV#Naau6Jbx5Cg@-W|c+d;uAWUB3W#G8z_ZHhpUTjJ<*|
zz08cr`={`qa!l^n`(Nu})4PYV!Xhz&PUnTFd)P-mG6}-U1|B?fapuHGO$t^DriLn2
zHf&+c($UQ3&fUpflM(AzA8A(ZCfVye-shYHrC}<)2|jU$A!h$I4OA%mT?ZAnpJR4d
zj!0LRO19b6bv#9dE!c~ty(Mx?i^-oNUp`UBekYAFeIL6s5z>VFQ@yZX_fV9n@V$Jf
z!?jQV^P~Up2Tg;*Lj&jk^%>JbaquR9$&PG7)#LX{p6DIW7fy)b)T>5vt6&SbGUeok
zf96;v%Ryplt6y=vkzCxaWs_p5txFD7(9vu1NUB2Zny8YIt>w{=e!eZ`&h*}t;2*l(
zmYvL3KTz|zepg*X?_*&V6N;G<mQmxRF0WRpRT2{eR2mD##C+YEf4JZXJNyUO)_>If
z2cwlAVD$QU0#M)=XV#Y2v<I8nNG%rXE*JZaGxtcTh>sqea->X#BGK7FS7UlchJ#!F
zK!rr1d12VtzXUw9np72-pwoV@bSL@ebW-K4oBp1Xo+`RDG2hIFU8}~>+|l>!!xMeY
zJuUkUi>W@D5|!vfL@wd~pxL!9GXy}-pOqdw)Xa5I#h`cSlL<O{vA6NyBk@A}G=T3M
zDD(t0eF@i256kiUS$Z>XI6AxU;j^aFF6(Z^n({Dkf_i_=Re;_p%;U^_t@5+OV<j%Z
z`HkySzP{Lc5~^cdVZYXOA2Coz@ya1KD{e9HZ*q0X^=}`zmU544G?;KD#qKc;ju8HF
zm8&nnyP^wv-T{ER24S;e19bWzJRAsUj<kPkGtB-55c6Co2(x}XyDy(AApJD06fnmL
zeDiM`_0uyye&_~J%5(f3ctr?x_1S9b4cA*&G77Y@1wG40YVs+pZG^m+J6iZ9I9F-K
zZ)Z7XCUlMSfW{?vt1RU@Ir1K1u`2aQ$x>MXVpH=3i&&sXCVY*9FuAhg^V$K-P%JPz
z>NsnAp-|y&GVlh<<!1?+o5z<t_-TcTo&<{KX73+DK+2A`e_d{GBfmL|J67R>R*yvL
zAn>(i4JzqMEjM%<k?C_!8?6|-?ba?3>wW4TDA71Q`Y@)5o{sck@nQYLpvGm&jf%#;
z6QIO)o@0F^o0XQSEwaGe;})@NA(JZR`2@{@6%gjG^n<T%g^GyR5DwC=*cL9>G2Sh4
z#jQ_32@8K;hOTlBUcTJ24;6^^J}*3;IHo+%5(n`3VqkeF_{&Hqc8)`o*esC<p|dwj
z`@PFfRl9#*&6d2CY%_u6=D;9E@WVd$2gHs;K_o$_X4~9wg|EB6<*7_#_@8VJ)ZF6D
zq2;z~80c|<cY^l$w9Q#{HEm2Lw=ZctKRjZ+%4g7KF*Y*4+0$#s)x`NsU928y5BUT(
z4&IOnqC2reGdK7{N;S5h*K|n1XN+!H3+xQ;?wEAs(KFm}x4IDkOsizSy+F*jJF^d^
ze!~m<wj{%>^8cN@J%u0lkIa(uxepxt{*JabJyZbAGJEd>!(s5(vRvKOh&XYXLgTT^
zHee!$%)KbweCmnkfwOD>F`G1qpV*TRa7DPG|1JFfF~m8gA4QDp+;u`asR9}IWvm-r
z$ehA|(RnnmAOVc%M~9D2EKv4345XM#`-N!BAxES8OB!iamS0mRLT$jf6oYnd7K4GF
zF7x6<>6esjTqO^^Jx%d>15^8+UjDv%BS6e{$z~Wnr^y8Bm%toVh&}8BRgDP)+g(77
zVarrycbGIdFA51HYWj0$VdwQjV5T_Ksyo6O@p>&tQoHdLMr@L#UsHc-CBUg_9D0d;
zEBKbQ!<5UE8t1LYkA;=$4C7hrLIijUqJUc1=zrwg@z=`X>F7|^_;JhOpO-aM(!qFz
z9p}MjHe2oLzZ2mi<G<9a&b#|^Xc-38tHaW|^}>T?wd(~OH$e{tb(lHpl5&c1nNsn5
z5$tH(!Rtzd3~);Knpp*lEjv)H{GR|&xUze8HB`m51N7zy+;!du&G-i2Ue8t6xvk9a
zzj?oBk)L_fVRQQUMTy|uyD3R>Y3n%>Jip;;&iMR!gxo_>+I;Rdn5p85IIF?D`s$5u
z#g}ptkY9;rQiW8A0Ly>HRlLz9LfgD*nBmH#G{t&{{TU}+rvUM`7M-#Ztd~`h++zKX
z+cY09>k77!ov?y~7s{$Bf15{X8sVlQZ2iIU=VWZxvu6!PMYSBRslLY>B`OE2?fF=L
zb0f6v;LA$QeW@2VY>wv9JwmeLli)ZE<!nJKZ2Rii_sv~4ifv^cEr&QRkUP>fBMHJm
z=~AdsDP3NqDh}Ptw=kLpyDc^kw?i;j_nOe)JMpoah^$26H^n9h0sCg3f9P+%(16=<
zDIojK#t82p-iE~AZCll@lGM|-bub`eF<a9yh~%w*dQ#+k5%~sXG^r&U1(hp<pI{p^
z?#_z-Dz|LKDNZ8S)gq*mU8eju$oWc{X8onJg*2=$$|bN6l9h9dN&L*4YxnE>BXh?J
z$n<?JpPSop1-KMSG5I#~Z6c&`6dpXMM^imx-bv>=1>9j2D2xy0e}oSCJY<nLBTQNl
zqbLq($0nOo8bTgf+1Zp-W5x%g+rF`QrlcuPHtS0VZub%rshoh#Rt^;{NkBO<@%h6s
z3>wd)BbM46HZDN#U85MHfx|bs`SItSeaXfIe!G129!L8L^}xJD+sHK`QL|pUXL<@&
zlrSmCWyjkgD=o{wLXdDIU)1jK%#4h1rzVY@AhH^IJ_p9(Pd4HewuKp9D%56+d-CEv
zHKmDkJma1F6le(>FnHb-E)lrziT9z#&_i23TJ8pExvzhy*<kZ0Ks2>`7yri^$%RE@
z$4k58uOpQp;%7VtwDm$?^ead!JhK=Ub~5bTftv&<KDsq8NAzEW%TbLrK@^k9rl-!2
z;J$NKys2Avl~T(Z2-=xLZakb{-7B_j=#CRQW5Mr{qIg%rrZQOtxTY~nXGZ0kiafeq
zLbpgXI=+zL5!gQ(QS-V;-nEf7=ZV=Dz;2cR`#;}V$L%bd;xkSixQ2<+M|<01qHa0`
z0@^t|1x$#;DyA-^mfU$vh^<rE4g2(EEad2hGLu?eMerLYwhzdY{L1n#+=zHNXGZ+Z
z$gwB-sxU+y$+wq9z#-BtU$uI=H_T<m+FB|gH*2=7oai-jqvK2IvruK5t&whvU!&Ok
z$J3ywlY?WR^hc}cLg9Fy6n4gzOFFQdaj&KRuh+AmtLf}xJv^p6KYfoY@-F3FV>#Z!
zijqigDy5ojji;X#Qxs@lh?x<-jKgM;f5+ag^~xBo@`0W`p9rku`nO06srAebDth$V
zON#!DjktfDGreE{chhs6O3}gGmcS780h1sY$f6GlnLIcdoHel;Z{<h*hDwTWEin6*
z@0BrN5Q!H_Ij*RP^j@&97EJub_CVlDybpXz)sUfVouV1Yc)4IO`N!F9#Z3;1<g!0i
zU*~k)W@?Q-ofmPMwmP{-g>|+b<}e-@Sq(>3{TY!Uso=GkOt5A5nJB1PSYL+`aq=5n
z19i4L$urT0)1ZG_;(1FgNuWiOmPX_%hj}~rnpb<&`2GY%<&j(iuQypNTybgZ8k|oF
zipdTBjMrgw+)}Q<O<0z1&;W5neA;Ur)o}1;DJ*io=&%sEnH7s{9HPby5^w~iR!P`6
zB{)F+PIGf^VKlu_Rh@Jc-SQRk2ezN5dyQt;?-{eE8#yANOG+g5Gvh7yR%~rILi$cd
z+c!Ytp%YZSmM@nI<-E?>dl4bISbv(Xqj3z0tTNlsKC)xx@w|znDa=yyG5ye(;a>?_
zSzG;WmA@=&>p-mWnJ>sxt-I()-bxelLKxG;(#mxoWH99{U~j@++<5AU;pDu!K1zyw
zt(~PHLg&a{G$kmEk83_NilULHhoUm}z9kG$buq;wy}a(Y$JkXXNPkbKE`+Zw>!irD
z2G)GJ#?sxn%uP|pZOX9JBI$Ep1c&|#pYk35*n0hVW^Zc6#o0l4n>7||2y@^#PrV`x
zOm_Orhr4&eP~iw}E8Z<c+QZ*l>zl7sm7w}O@wPfHKJfN?**0O5@4fuGtIFM<e1ak8
zL5bpN71qaVf3~Dn3&kJLEODDE`ciOwp5(=#js-gB_ey$*_Y3H%30p*o-(fW}JsklP
zMy0q^`$IZ>-FZ%%wJyf3UlCzbl(h%{9T-!XYXQj!=Nl?z=km>{um<zJ4|nIkg)o4z
z2;{8>-|#cb;vh(>`9uSt0)N6FH^~3j3())c<UH_IkJ@k{oRH(iSEP{b*+HDhlTB#4
zH8}|z)GKB>w1WOha*{e0MDn=~Te%V638`47rMV6FHg$XQ(m6X=JHM;PtIFy27;9hJ
zGpl0&pM!fax7FW;O4t}3BfuUl8T#lpsar}BRSTp8aOBZF@aCLFFtm)ol}|oIliQdW
zv*8r1xuQ*XM7AiP)VerA#8x~?qz|LVIux}i@!4r4RPX!QIr@=4z+RPy4Mj4D@?BRe
zYDA+$xm8_YYa+bxfrbx-#R&2dqHLgAylCf+ZAErNA1iZ!q^B-anrQv{<?|t?XK3d^
zFKT%!9C4ETPFpWQtelx1_mqD=IzpJtaB%9A2eDq(ZWwmmc(a1=B*e>eqb|#<*sFbM
z=OKh?7T><rx2p8`K5*G+F_5X%nC84E(IhVHYSRZcW}iF`!)gdO9J3E-9_aC6Ulxq5
z+ps^cHb#_t-XoZ&D}<40qxMdF0e-7B8h4i_*J|~n#leAB;85X7DpKJozU6A76-`D#
zRsFgI_G70audECPZ)#ZRm&7K>O~6j|1ktLGT^WHu%T*UBH_SOT;MQ+4me#i1fpnkr
zi;`LePpbIuQ_R}^QUKBgcjynz-d~rY*&210i6viQbRBB1OcOFC0lg?RIF-W82_r34
z&NBqEvY!*kv69?0w{Zf>S3i%+Z1q?*u2>7AIQl3K!cf~M10JUo&8$nfGR)u1U)7C#
zPu%YNKomTt{VGzwNB20ELf$Qp!}Rr)n-*nm^-Pd_nqjpy?6DWqQC|LLzqmsS+`luI
z>(hn33B55>g<nZx)zC(D)P&to<-#!fq`u2${{rQLO02(zeGsc}b;7l)Lj-<umHJ*o
zppBn_v_G7tSgsIO+td3d3ja8!Hh@6wX!kM0+r*{k1`W1z9(v@#6S+s>`Gdu8wU|Ph
zAY0JJ!LIW+e1(pky*kY><(2vxM&_w&O4z+e31oTg(ghM4ahPo4&umr0IM&9=8m$!f
zQcFJ1W5&i}W0?ddff%6KpSke5oS#ZI5$*ZgJHtwqxp2jA^hkA=xUc~=>`>@!U(hXE
zJ-xz|*zRp(T(RyZ&{^2A)BA=?)S2+^ZhpA}9y5^vI&@q=$qv9xT0kcL0KYPx>Rjg(
z)7w5qb>(cLZpH8M5U4t@Z3#C^c)%(Y3O_3;V_*D(7L3jzV8el7^PS*5<@(Q`3~Gk)
z7V|F`3PzJWw~Q(}7nbJ2m*!5O$ul*c-cFPggEMA78yJR?86y*=)!U>a;6F0apQVy4
zF733Iwd@b>Ly-BTA565;^peuPTpZ))S&+`BRh4m_8$scI_uqr4U+<6gK)gJF%RIM2
zwHBLvEnsB{Z<mBgnQT8GaI>W(@!vK2d)cw9w9<d(6OAg8Q|(;vkgbOn3hVp9tE#@B
zy?zPXYpM3^Yw6T|AxSC>GB&{fiT4PvL3(A+y03ICAug*E7qZU^-#<1EI6ijX2(4OP
z)TA?e2bFxPiZ^%NPRpP>m%5Ps9Pekf2128M)Tv|{FPB30EVuA)3aB23yeWp)RDmq6
zn$lF_$&aAzFD2~Y@7neVNIr$_OTGDD6hEfImwThK#SH)8RyiPre3f#fg+=oVJ`Ap$
z*_2)i9d}Ss7X)E79~bhdA8yNa&AH;qRC#d>$R6K5`BSY(Jo6pS_UdZxnerwp!SPcC
z*;lPNJO#KChcGos23y&ZeiDbbl-s;g$HFoC%*bP$K!O+OuTCLV-&pOEUj+RQ6Y~l&
z^)rH<dPf=(VJ<WqHO5ci{Is)l5)8ZYTm*OHeTi1WqoaFq^9zg&5-T32r<r-YaI5)*
z=0oR)L9#dCkCOEjsAJ^3aJx-Hi&(@ZYpoD@;vQ(z*T7S7)mU`VS9#Jg>Jd^!j~yG`
z&cmC&@CNSi2kzgbysc$tXLT{B`6K%tLR2sIZ~pC*hB(n84odLWBN~hXe<XI!@eIg&
z-$wS3c^vJ-)D<_~c+u$}Wh2fC@((_$EwR*DiT&fc!5n=bY6E_V$Lm+==);v=9m_Wa
zLpi8NMi19K5Su%xN^8rUb~JBgC-<(2-^DA{vO>-SRHWf1PxUeO%QPqF_V7>IayPuF
zwPXilmgUjL&R2!VCLiI+;vH4=KG!^BzT#Jxr?o}Eg@1tFe0X68!892A(3-LMR1+J{
z)#k7zPCP{aNE%1g*ny3u05UZ)C#s6E`{TY=b)2j(PA-IvZeI2G6-qkjh{xnP+KEAq
zT>qBPH0=}9VFH2VMh<IvJiBt=mtJISGny6W2pM6~slODx+Om!R^2cwNWrc-D(-?Ws
z<*RWeeqA2@rO9Emqb{i$)1u39iL6JN9vG+2*_HnQE)SX&{V{Bl7i_<69mbP)XIrYc
zF6KqRLmgA?vuC|eIj`xew%L;Y4(#)ZSJsiDYiXCm3wiz`@Z{IbO2vID#tzemtZhuK
zRcS-rnIm(j1|$yU@Yo`>4r>z4O&HtUqxPlg8}wehonT=~nql%E+FN@ojwqL3Px`wm
z{(S!tp*MDk2Yq^kew3sO{c9io(J%fV=FN{3XD4K!(2unQs;|fSE&36fMKz^z;fTln
zbu_cj9P0>n+YCynKh(|SsVCxo!|c!bJ|paS9uy*+tS?oHmi{DMh(9^B1(P|Yw|i0u
zEVia7_{8J?&~%kiado|V@WI{P-L<%tV#P~wcXxNE3|ibNQYZ}W?oiyNxVyXGdGA`^
z-}CDvJ3Bkc^Ca<G5&OwuM1Xf2@k0_$f~x~%KFH;tqoD*9LLzx6Pp?o^tWM##N&=S5
zP)($O$iLLApDVf=IyHxE+4Uo>iJWYppu5&uNC8*5Pc*woa6m>KZ1iKzAyZvfvb8l|
z9cvyN`*lV$Nr&vsTg!sGdrOVMbik5L&-W!uPoG9Uel8LMt=pJ~jn$%)`~)yp>-RvF
zjRdIl-%aF_Sb|F~7r?~f&5(`exHp7{t-vR-K*X5@;PK)nKRM4t6ib5nb`KuX*~Lfk
zvU&S+$9GQ>lDO+7E7;2u{!LA(<2)P$UT9CWfSvh?H07)3k@9YEL_0DS-w#(f;t2El
zjN3I5*)R3*rYC%q^+z9eF6YZbm#cv{&;9VNU3UY-kOkZPU7<zhlxYelEh`D@nhIWC
zKqBImGUyU>N3_oVjt)^zAcZUlz2LmJS{MND*4C3U2am^_?2BJH>wPJ{XWty_aHHxG
z&>7^_=PoII(r#^4nvaNk?ME+hdK*B8_)n1Hk4S<iv5%Ao#xLvwU2YMAU4@?K&Ih56
zA*lNGF2+vSXrPB^6C;C<8d7#G+$m~c?czY5BjGnKmx8yhc-*ZyVk;lxP|GW;(#r=Q
zgb4GVTI$<E-c24NAwN%die5eyXP|YM0|GpN0!DH&@;*)1r>&}fVFe-V^ZWZ_owW@p
zmKpRFmI0^tU-Dbl=A6|$Z!mt6gTTO;m>Q5ELTe+F;w4Iq5w3!dQ09EGhjF3~S%QNV
z+o4WMB+Z0R63n|w>e7fznV>tVnQD?PSB^sITUT$NN23W?Tl|*A1f&Ad7JcvRzS(s9
zCkPjXiL(SZleKV{p4xI&f^1uU%Tm-uEm^B^cm8g7eIFn&^$$UqGWW#TJb-ZT373Vv
zBEPnJ#yLxpO0rX9^)gg%Mc8$u1$i$GoB3oy*y;lwG!x$V1!ygmf2WjE5<KHob5;W|
zO2_i3bj@^-XIKiP7rfl!6;duLCq0kp$1qyfv}G%fm9_7yJX(;x!kgisSPU&doz)6d
zn)SwSzS9{3Gl3-!&MbX?1$W<VIs%(#0dAK@l;CRhc2S+XY8#;dl+t77DI0VjCAy9C
z*8o7%^bujHBtj(AY4|-kXwMc4<K7uS=QgZa2yXP{cVF&({*acU*p-JPpzP5F<ZA#X
zomcoJcmVUpolg46;tZ3{{~CGGc3HFYhN+thDp}>DMN$VF{@JhEdz{lpRSw0JN)e|4
zS|8S(3sz5r&iB&XPNa$8!*Ep0+#Noc(Hj{|T|NTRBcK*tRULU+|6O}nKKCqjtRf7*
zt;Au>K-(`JYr|Y(A1gn_PUyNJzEIR-O-Tse>`LJ85JH3>zid5TH_5thvJd)d+APEw
z!~n$?Ox_*e@vxwHh$$U~Io6Od^T&Q8aA#pFJMbqbAI@oZY?JVZ2c&)XgQ>=KVe#1O
z?qzYym+?GrgsSY>M#NpeUY>m_to0x1x1|E=NC@rqHqXfB0%wGI4ZXL5MZ@W>nAo2F
zK#c^!*d9kd2cf#P;b2Ns_~D+P#+3_v)i7x|6tmI%bL>frZpJ`vbV(-i>pvW`Y499<
z_)<6L*XWuufay=9aLK@0ZjM0$Q(|6Xv=P@)EdwpcWJ)g0wC^hj&2go|j-<Uy!&Z4u
zA?~IlT+SZ9su_p3$#gN4aP8;(!@n7xwYC=iEJGxYC;1c^eZ>i+#DIm;95HYAcq6j8
zGs9QoSU_(xP5r^iHwO`y-2bCZh2(-wVMNKMoEPF@h=EvoN8PRXfdMj7;!?4XgU4Uu
z$a)+hMedO3vh`nAX$P84Hz`MPv3|Mf;|87S6M%)_NRJ6FysU-CmC4Qsg$<;5G>g#i
zJj+zv7+`VOHnqT%i6;juj4AeK&;=uv;n<dh3>!o^7F`|dxdj`oT;1N0SEST~)Tz>v
zmc1UQVcbT?v=IVgr9b6oVoRFPVTH8Bmh?!Z+-h1Omvd%hO~-5w3nC0?jotm}(L>70
z-Kz;lhVs$=z7JG+qgyX&29o}fcFrJFY_xhK5Gs$5<<3yRJ$=o^Wx(8GQnXWrrj6Ix
z%c4+;ui5f7@05nP=r)Oheg-wUne+A>_2b>g$)f5h=Sk1@n)zw~FHJZ;V4RVaD@{`-
zhK8Z|s#vV+$D%>@iKnU-zQ9z7dGR-Ude<)J{DDI*MVR7f;X%3!xbOcR-SUkH`RL6k
z!z8<@c>vtr09Q!=Olo|bUof{02OkrUWxZ_wdUo_Iq^0ITmWqT~%L<mLj&dam#6<~I
z-@%*6X0S)9T`E;!*t|lH-`XqxUahHraxmcrx(kD0B`}2<omhUHMsG)cL37;rUam`G
z#+j}MuGxk6Vz3NTT70A!d-`k6PbeLq8;J99^KoS>^7~Y;y$!Td^?6ig>WwV8LN`2_
zOXrqJ1<CMr_G0rnMW-vKx3yoHd-O*+ub)*q;;K7|6{n6)4{rF~=8uV&W^RZ~)<9wM
zz2a{bESRYl4#wslMDkZ!Dg+QU+qqo|u@j=>vJyZB)1gw4{LN|;oZ8;(BvBI63o)+$
zSd9V}n_%LT`;xHhcZRtXCmACWDxe|ga16pH<xFnnkUz?uinO!WxK>tbIG+_0t3c#&
zN``mf5!MQ+p2Whir?Z0w>Uq-F;Gj6r1sUW7ZVSH;eY}zPHTq^Hr{@{;-!`;O2L{7H
z&WRoOSwGA^nS8VAW7g97CKG*1t1G6jRXV#M!dx0E{ed?wi^QsjY#85;M8rL6<1=JB
z+jFnAz~l2lXWX+5DFtG!a&J}Db(pDiyF1XdFqB*8RtclPsy|PLm9VWTFl+Mf6h%y|
z-DvO8&)=6FX$E0Ct&C}LHM`FFaHe*fOP`3v?%zFWi6LDL5sL<`h~uOu!F#rwHsb@?
z)YU^t2>_x10Hfm4zCfmq$zOJ(ugla~@~7J;Y}?;I77fF#?=(f&*Y$f(!B1LUeT1yF
zmO6AOv*MfRgT8+sg#EUZMI(<E&jD`D8w1877$y%MhuZfG&=ed{%RAmEosM7N5ym05
zcS65$x7pU_iR;WB1#A(9sF{zco(yzVVqC(D;l_zU3OZbJ$ML0Sl_hk{ZqZ`-rN!cs
z4@WEy(aW<uGy|}ku6tVitF_ZzSKHo?Pwh8v7lXM{zSu&R=GM52Y-_s=>y(?eMt{|{
zu5t2tH822@lDkRBt%Mqr?N@}ao?Y(>9Ia7F>xx5YwE%&F&t1DQ-Wtqr8^8M8_59wk
z1Ea%_9v{$%g>mYnMzz?JT35nOc{M^gA?8(R=UxWN`tESwMnFA2u}ncmVq|A_spWOS
z!;?yij?IZbz}gldPfO%iLTM7ujZA4oAWYXCfsLS3-I<Zp%?ZO$(dEV))Jmu42^{ZC
z1>GrBrVj~;T{@h8YNoGoWt*(p+)oi&tu})>Lv{3l3D{Z;Ama*_qnqFBm<VNjOJv7;
zCbQb&BlSCvf5(dP#DCU7OC^zL&&)O-g4wjrUwkC1iBT^{3!Ql+AnWiViX;~WDF?o)
zzp<g2f@<{hRqc)5Cs@wcn`1I;XG_7FFZxA^Y3%zi`mlpqAzq_JW@B@tB&_>JGOI+>
zszkG~YgyWVopI~qno1|p{k+!CQI(AQVqsXd3_*ySVTfA90WyFeu-Wy%uj(fA$j{$|
z7Z9G*pe|m!+c@2gAa4_!BK!6TautM6M(3e4m~@{??v1?u!TeF$6^tgGJ@ZR>8_jGF
z*_-D$w!d<tg7<Ry<B_m}rGmyoX(6y*m!lemH)Ze-w2R0f(tWEvp2B*^<_~WC$<5&_
zY5=AtUQ4GDh%+@#1|0mf0`C6Nw)k5W>}2$L0rE6;#dH%WV6Y1-%H;Ft6&wAq$}vDi
z4b*t(h%;*0?sbOQJv|JCZLmRY(D~qg=UPA|8#l?I0$@W6bkYu+6oyb_6V_eX%u9It
zzX16D{lKPueVpth-tncw5;}Ojg*JHK9~EBihyS+{@EUp5Y3OITQ6~pPt3Ax}0|i&q
z{B>^MqhJ4_?0@<*TCc59r_b;$QrXnroHy~NriZfm+>}s_DE&%T`}oJN7qGP1q^@NR
z%_)vv4}mGDxB$YHJ73UeS<M)F&G`hG<lQi{R@=D+!UM(P&F{1$1(Ug5x-ka@eXh&$
zRsBle?J_Ws2s3?>Jg`UGyna3o-5Wt1Z&9O2%A>Oq9yU-LON^!bb>G>#A=-QBAZ`K3
z92dVuA8@`#kVT|?njPbrc6t0@7{1{1o!@53=;i969ec9t<0$|i1~6H0tKNwNo~`lR
zfX)3FXe#JTRdn-gP#drmd$+Fmwt)4CoR~!tawSJK)nV9uy91U-^uEtsA*4nD`ZzXU
zve|fSN&XXw1-bJCvMC74({aq`eh>vg6D40ybn$|UgRdSIm`d{qll)l{Zp|Epo@zG+
zF1duxXqgYtZO^C5TJ=lS)~KnYUB9?y|A~QUnu~`ACRV1pO|%fa&Bip>zLbf|3GwO~
zHF7&qMG$xA3kw`V##;~$m+5|qj{P+wjrgA(s*tcte142`ebTf2aA<ntBzg`=fHMs}
z))#wYd+omwgIbKmFVkg7H6nlq&`)1us1{icCcsx@qiP5$-|NB=S1xWztTAoxFv;a}
z;N?Q~)`Lhl7*$suTct8iCENTI(IH{wV{RmazpW5{K<8WJ&{gh(Sd89!*hyGm<x`Dt
zh&Ytb!Gn!?OUPv4cGXnrLLag~SQw?zo~x6IsG+LtXqb6M!I1VR<jS^peOfJ2M2SRr
zvDm1bK)k%<E%qcoMs#bSS9H}N#qPDop=ybB@5J(<KPoCz5&v70x$ZEoOKFvTVBjNB
z^9jriAeRGNdG2p5k5)e{YyB(i3%OV%w{mvxmT6@EBC{O(;p@{1=6R1_8Q{k)8P%y*
zp<A=3B6ItCy&bZ}gk+H=#cjeJS7qAYG3{zQ<Z+$49Y?~(W%ED#tdlwGdNLBw9+d55
z3~{)+%osmww={eo&Iii98g{l?B+;0{<>09(@F|J4to`gdw$l8j5>k)@;ZL(stxz{M
ztX)EVM*dmvQ47O-LXNQS-LTHHwYgdSY_@+YOBltnB3-xq^vU|f;L79i85WTM6I#BQ
zvTZdjSDZ309=G7l;lRF>Le`k*N5W_%f(>y=7!nUw9&k1&d26F9r>+1d)}k;tybU?M
zi#KLDt4=G!aK9!K%F^+4=u|vGI)Lg`#BR^-F&N1^m#Q<qktB&6d4tT$Wpd6ZwJRO!
z5c5y0B;_k1LtGkwN(K7iWkG$H%8azeg|EoCB+0+K8U=_2_@}&yOliCV9bDCTOP|!-
zNm!<AM+hBPr!F$5E5Z^M)?hv=B^O2wNBrdnAB&s{5eG7!+lsHBuReBzbdj#9sBsa_
zr5<_k%IEw6pM-(O^|G%q0;iH>CHBF1snc5JXMaxdf)|=w79g<}9JiU%^deEyiNoZw
zbVSa{fNi8RA2Q$Ae^H!;9tJ3Vhvc(Vz7-Iyo<KtV<@e=m*EKgm7D>#j(6|gXumyLH
zEgsK2G&broH}ICM{Vc~(Du3J4<M_@e3u<K@NXgma$aE{PflLL5zUp`8W5f6*4L?mP
z9uaze_Q$)@x0H*pz<1<2*I{MpmzPk!9*l=m5v_jR4R@>t8Mp>`6$6&Y+`45e$%d9L
z&Hc2i0kJ2R%saDCclhWF?`EGTt}!5_^fpPFZ-9)h;(b@loJc3RJwv3WgBA!M)<eiT
zqh@FuMmAeIU!zyq&G8f6>nfA2H)2Z`V<KBD(l0DJy;*OlXV0;H^(q}8Zd?Hzjr&0P
z_e7FCc-Wcu4CXQDjYg(-zP?fy@VcFP1NO^+B)~SsL_VOD$(>Vf<)S40A$y*y-tV1@
zR|HhOQuOgv2qd(l)`E`{_?@Ia*~Z${W4n>M$um=!|3W53u6RoB&*fg90ha?^uWE;!
zCB`OxOfB}5{C`sW>U_VFEJdm-XDjVJ-^oMRV_En@kpJd~IHlqwl0oYTv8vpiU)tc}
z8N6!}bcv;7EifeJeqoLR_Cz}~f@^rX2z>Mk_q!*Gx#Q+4A`ucE9RQTGh<<m}?RCWE
z-{xG7P@V)ap}Q;{6nD4-ALWwqN6TRKYi^r?PPPFhJDfK+n9sYp<cth|hz-JgFHfIb
z1wQ7&H7X6YD>p|xt2~A2((0V|ds`r1sv;IciNgF59wbVp$(@A{6BgSRkVX*3^sXO*
z4!kd^SpGcz!|#HgRXiYT_kHQ%ri!{8)*|~o=$aLxr||M1S;E7%FR&GS)KsY_W$uiL
zJgab}qy*cR(D#`8mvrS?QeN>iOLFtYiFl$Csga>g)WD!@>sA`7u^oS^jZ;vAda8S#
z7eQeSwi%Ru{U@>z!M$hz!c;eQZ%C3TBTztqggs;FIDsP3fF1~+)MHNZJge6?@akzn
zzEB`}e;(b=3KMhvCHUZKpWNH^aMwpjX;yBJkU}oO;!(UpjYzO}q}rzeP5x+&)Et^k
zJ|f#89E}CWiD*2oJcuueRP*&*NUt|5;8cJDy7?rho`I0nZ*k>HR69d=5dUM>)hV-3
zB)SYbc7BA&1yl2NaF0*_5%WCwSO@o0%IjT&+9j1=pfrh9VybvJx{Y@(`lLHRUUaDh
zbL(YMp4xGlfS8#!;LWEWMHXZFI0gL6?8*2FXDG&N_f;;t*$E3Fo~)f*57Vt-hIsmz
zAFRrNOQ{aziApM#U_|Y!O=OO!YK~=AiQ=&?O@S}w`1=R5zE(4wVd>LpMz-SXvv|E|
z#|#lyvD`jGhNLVIXXl=m`a1jaZw{p9;Y}uul!%v$4Q4%UGZ^x)SX}g6lYI-`3;#Tf
zL#LfGlSsFed?8ilb}oTSxx@(ki#8X-kdf!Nq0B0!kv!R@Q~8TdhTC_&6kF{VW>PG~
zUJ=N?9PxXO#yg=Cl|=g^-2Zm*pG5vxsh?pennHsDu*<8|E?|^E%_?=;uh~SnRmL<d
zTtdTfyBM4tCjX{dGu+$zrez^$Iy~-kLdX&2RFT|QxU&Mogu-ZCgmH^p|J9&Xu5KaB
z7-N-SM~nt&s{Rwqrx8g9;z2nTasfhG-!<{Sdwi=NP+aTL>l;Y6@5X|j@W~QmhZ6>?
z-b2HZ7y$uVmCeoEi`{*Z$fTk1p%mQ>CyP=iWP|X8|5*^vUE|pA0%$9N>;j{rQ;}x$
zi?{HDME2s@Eh9S&M8+%hz&(GjeT2NTBVnBrH~29x_WMrjw2-&qzfxX(@np(&K|b#j
zB%QCn15r2jl3&{-bbjiBipNi>kl|M*YFYKX`miBuHV{d?4k;FISh#6m6=yenqG~XU
z8)WME{z<H~ks@?(;l)aX#rP^L@o&DR3B)wGghL~l7F)GlAWB-BkQmH<?jXv&a!7{N
zF?AN{Bfyl%6sMI0EI1T448|T2k??nK`SU4CNu6lsC-b0S1eNR<?VqFU<Kz1*Pe;~t
z?ua9&W_*KdCK?_fI4FNYn#U>3*KWKgUysjw4)2QeLn;Rm5^F>lZ@zUsLkT}U)B6g>
zt08^tnSRiwq)>u86tu;(gkW_@g#1w^J9gZoi}mulL}J)K7TKK=2H27`We5jn7REiO
z?b_%AF6D%8;>Zs@IhWX|QDFwIu*R};<oU1%wF2uKCv5XID^1M{vPU#i?VPk2&BTrD
z<}iTtgEvcgbtaY<6MFs2wph?lYMcvN(1?-&6;U$aLBi7IxDfH32|JiNWZUW^w&d$A
zA2z#DXv~6Tx7LaJ;U$W{`46^$dgE@zFB>1ch|+^-e`9#^TTByp4Pj!SoOlNHn@-`K
zJ{1ng3OMaj1RUe9$LQsTvMik&>%a%RF9ty2=lWFqzA2^X{vvj*+J4!9kHxfX(LO5v
zVYeps-f#N*vXwl5l%ZgLXtru?a3kP&G;s!0H!VRTJP?5csbK&utBnY;B~AP$X%MtH
z_@L|6O2NFUy7u|4nvrdtHuyTO5G5rHYGQ+8iPSOTa87&BYXSMxsYzjnOw<|1L=;$4
z!i$4~mww^hRZ>+KzUq#be3W+eMH|R`aSrc}7r5e<^}mu(RL<SJ+_$@cr6_6}f2pLm
z+=eB<6c}G!DT)jw5{G+;d`sQOtKaJTk%HFgY(VL(7_5Wh3#lS^()TdcG$;v6Ff#zF
zYJ_+mSPG>4yB`WtP;<i^&BH+v-XG5Zr^79&$FjT^N8{pp64O+Z|8W8MNlinCA<I#&
z9bb`@#PIIdFIa%kuUiNofQ`3jPi&@T57^w~GkoR`BZ`x;S<B0QbWvQ#crcoSeoJtb
z|Gp#D8SSKug4(hQ!DyzrbN=Ua$+9S)hJ_0gjs;2BSuRxqW(lIuHDwD>LqV`i-)H}Z
zxMLldSRI&5(|S+VpG|1SEXfqzWJ#i)hklc9Fz&ae{O_4F;`m)dkVHAmw>N`|V#EyZ
z@2MswB4X0hf_YzDF_I5z{iVr58(E6@pqBEYVgw==`du4FB8GO5vz<D2<Xribm6^+%
z_=QxE|HH@2;T2>1!9f6^WG&C%r-5(!mK;qaPFAX1FbD;@XE;RLkLF)NJuJnWI0qIy
z=+*g<^gSTNsw0g{hDLl4mf{y=s4vMEB|Hi;SggHkzW0}pvoz=HF=~;Vg$MuFp00O)
zzYpDwi<+Pu#C3~&$D(8o7HrEr(U_Y_ec99YMaagPjmOmuu&2+mL*EKijd8=Qhdc@-
z-WqE8J-PFGLMDa5;CE~IZqOCePXOrV`3m}~Bu?;lbiz5<y5kFFV~eW6>^`?Z1Qbw*
z)3tP&Vm3`=08>U%#_094iX^K!k@6d85~B)?)5QyM4tjJ*L$fjr%6rc+{UqQAhYrs=
z6oo2|NOMZ|mJJ0(3@=94AYdKkAGD19fJTFkQZsK$(7Nwy%or}=Zl2wB^<DP!bXIe*
zPWg(L0iIl&#`e8>o$MqlNtx=-TDU?0xIya5N;=eaEk0Cmn7ly@T8d2^#InAIj}lsw
zNlA!MwPZg$7*y$?=FX0*V}rRRkzTJqZm9*l_nnj%uSLka9;)6+4ScqW6R2Uj1>^7e
zFGDXBd>4cAYtMiX)ph0izYsg$YPj_H?S*q0cyGynpA3VS=z*7rco$3zW;quAilj3A
zk3#39zfu3lui%z_I;H@no}hcOetv<dJvy@IrSu$Za{RVDihGlT9_53GYBf?~jqfgI
zLb{^`VE7uh^*W31^nQfwb+}vea?zMowR&2T4x)_*4n)_y!)l{!_784$WGy>L&`4g0
z74sg?(;cU1E+GBh@^CGv97+2_@Oef%mVD5M&}@DJ6hI0Ipbb=;qGSh+I?#d33w^l@
z3~f;NXnl>5#G(W<t^R|yVAb-90s(^`em2E8f0$D$xr~Jwa^u$XW(4<zJn9dlls`!f
z9D7;>Gdw@6wh6e~@|jbaaet6}$#w=wBrj_i^rLSE<cH6?Z7#IxU9rKME%`mRc0bf*
z6k$V|^|vaGT>cHCQ33f^uF7!#G(wJrY@7J>DHh&mocs{b{FC2F*wF*@eB02?>WLM1
zt|w5eL8ohCm6V8m!d#p%&MXTB)9%D@1ZmjB5&ig`Cxub;;Ggx0SWxz(jT&=Df67f<
zFccg+9K<3c#B=$k*ce1rYW0@|kU*gVKhG=?#<zG+PBOGr=<CxOck%T27Wnqk{Ms>E
zfL$VO?D!kuLy5){<xdp1xRPWTf(43Zo{*{}FkSP2_@_xp0tnlz06JVo*7s~7g}A1&
z3lS0c0vm-?5NU%mT{`X=2p%@40x~ZpYkjc|Zmko+P<T<`h&3<LL_b-$Ici}W_5+%X
z#;8kyo9<^7h<>L;tW&CJ+J=mg2J!shsOaFhj<<VyKy|FjkLy;ra{U*yyYzNyZGQyN
z`7{+k`;$vzU);rY9~LzvV(ImH=FhhS`}`22mB~gmi6EX2G|E!k&r|msb*S~zI(_zn
zSs%M>AFqDv5i7=Bnj525$Rh;X8s5ftmIdiUWkbq4s}PgAek~*IQuyJNtHEpn-fA%z
zlJXN92&VZp<+H>yKDQ5p2)+uPvghKmLjEginTVk#p7|!5B=3*PP{j8@VV**%bg_!I
z<R%M(<JHFj<Q_zJBFy|j;B_l!-FHL7k#*(B3j_Kim|;D(RSJCSJj<wd<?}P_vG%g!
z6Ba;qeB-8EdV)Un^U@7u2IHh2;8Bs5LzAlz3jY?Ac^v{w;2eq<zqVHz(#sU%nDe&H
z05@`70Ad$3W!;gB#-LU7BlaQ*I8ou>cReqaY3twf>#{l4wyvjuAx5*7eu2Uqh2N{{
z?ODDPFa2Dj<)5B9xk2Ab{^!La;qiE0uQ?_E#c}p<p~W{K{&UXdH>A!J3oJX#JI5KF
z$T)PG&(ehPpKY_7=QY1}1yKHYzC$%A76+h=j_eZBF(yt69^zQ>oGhD-d;tx(YKwTP
z8VWr4!jC*`wdqUqz+hM~Ui($4;n>m!G)aS$PzmW6VsO4tJyS?ySc!+b>tR!j4@1G`
z{)U=g6RDkcUzA$AbFQ#59!s8TotI664GQ}4n-lwV=$9c%Ae=2?PR{|3;|z$)+G$Wb
zSgAJ%jq5Rc!LlbV=U?Q3*rgAF1sAC;<R0ABC~wa+^=jT<Xp|npBuEnF6HHn+@n|Pz
z3ChC=#{7^PK6Dn!T%b>!`Ap>#ge_sglaBk&sBPhhc~*I{_3%F5)i;k{CH<0RvbsY9
zBAp~GpMW(NbP}+V1x8H;&)>r1HZ15jE&ih5qBynMTf`_!-GhSB?9Ueg5BP9s`4p=L
zqvKl1&f3`%*F)LA8<ttMZHEGT31A3!Ff^ge6dl-C1Zi2i4JY!e6evuUZHY@UdaJ0c
zDlM=R>`4IHSuook?}Ie;REMZN;W}kgf+}S=+>eQ{a@fFsO{h^b3VZo--F?PhUK|pI
z4G4Q1{ey|24lBLA2^dM6d@Jp`yRc(3I692X{{qo<;4X=0hfNd&SdmmrPTq<d-G_Ot
zfm`;ic|n?Z@n6V&>rI^oG>z{#iktUzlY9E>SE38<s*`2UDDxL6EFT||19atNr|(5_
zKLcuIYdU6C7e+Nb8M>7oj8eyUsy!<fIx1LE+q`UzxZRw%2QFmG^LZ0D=%q13{JGjG
zQTl>1R#xfk1;q=!*_~8rYI(n7P%o)6=g7e$LVqT!q8_nI)X!!irm4%Qj=SoNOP!|j
z`{jRGGM7}G>|m~MS4ghQ2$_z(xDhK~O#HZZ;i%=9vAPJ527R{g;6i~3KK)XC)C%lj
zdwAD(9B~kzGIJYKs%nUvkDL4RaEdrRM1VMg?lY2~7{LO)50DN_o9zgix;-&2b}I^B
z)<Fi2SWK{7kC;)(GA4Wtd)+keihf<Srnqb$+ZT$hhC@BkxjWr#M}F3#u3nRu*m39^
zSmP^0lEX8?p<)AD!VHaMJYMAm2-Z-<bfaGy27ZX`jCdL<?fQXGxfbs(9Y6Liw&xY9
z%zW0yG&ea1xi~>Wk=4c$L3{=L<~a(Du37AREATo%<4`KQu96f49!stxPutym>&etS
z;}x&3wlxyA3e657%q9f{zRY!$QWPf`4E*qC>k~AitD2cVR7}MD=0{5A;vaRf;KLdq
zkJSk_0u5D(-q+-y5>0q|QtLX6!5MBV#=d2z1hvMHM@SS_C`H$AAIXF|>1>2A$)yIt
z<dt^Eh(MftBaoUBXKHDg2poY7SD`&*mZ5UM0e18Ib%XT8&=Q3!2}0M)$7^7-2kpy?
zh*AW};L_#}lp5a{QZY1BOiBPgwR8Bd*e`iLL<hN|p{Bp%oYzKMr2%^qzZ%w5#jJJ<
ztkIzXakJv0d7nMXS;OG!oZ8>SvbHjklPo2oBcTAT?7?Jq{H5QB(mOifjnDlr`*4~n
zRzMVH)+@@q)&9KY9$d@&O?OHtFE5`CY5ssSR0&Ma=G~YLyYrPR2fSfyz^c07-ukmC
z&hYM=nntyAuoFZmD)<gI2%ef1mdfK@87cODCe}M%zKH#a+%$B|ndEgP@T$!pu@<mx
zPufdB?3Y~>fm-Ls`QCXI%JjY3>3TIF+y50v=IthiAW@UJBLMI6sfk^im0$(69x|}S
zg@a#zXw?mM{s(e*&={$&69$+n=5`Z<&TMO1HuCxIdvJcHOE3TkLlr3ccG52apDgVC
zA@+icgCEIp54BHodNpkwS{zLwZYFUe3QGhHcK%-DFGQgR<p#g9UxTL%b0g}sG;FpL
zOx6!<m?BatjGiyX1%3T0o++eE`dk^G@&w0Y8yhw<OknyS1_QxYe=l2Y$BW)NkFBPk
zd#VyB=+{kmU%cLI^o%b$+=Ef3AEeAcs4xbMlM&jTJg=dzLrUj;b&i5PJ-BwaSCY<y
zSO+{LEQ;(V4inwIilm)G*2|I63$U?0D={6^%l|r;Ynv=tj90AFr%XtIcrWSz;~ug=
zzm<4@OFRkcH)jphkWU^^Y7LV?CR*A}fvCf;)EI*utnD<lK=HO67*QTHxe(scJ{zHi
zc{5Du$bTf{`A2}*3?|rPh|BUN%ZKXYDbN7?-m3rP%ny`5z&!L=NfB<2n?d7Qz-o1n
zEt5v0`PVhd>&Be*Q&VLG%6ysu59?5cF3!)QA`oJ`vBDCtx)`vS(BLg5)Pa|8Xcf;o
zs2^LQ<bAKVdJvpg>p1g{F5o5agU>;~ZGO?^vWUgB@bhp$T2RgTp2GA!EScG4=Mk(@
zuE-K3-ANS$19h;YnghqRn(7xyS-x?2+Tyu3S*RMY!1P88=Nx%XL-J+rJd%sJgw<u^
zmBea*4P0P-N!BcSy$Zm>zt<&SRZE%q$flcO)7{63eqDAqD8YWBz6<GhBdlGz)YYn6
zZS$iI2@`PR{%aW%FlLI-uZhbOb|w=^L<zyYdHy>fCxDNT3r%9_MXgJTME*4L*Waiw
z5BwNmW1$qT9}#(v6d!1Abh<fEnnyeyNGdZrYk?E>Xq)quQ2!J<gfj;LH?m>WxSQ>n
zav8G8;vUIdP`h17;99S9c@7u!vq#4nAC7(Q(hJ`~ti+$t^gr<Ez9On)2t(j_*k*0d
zO;}+99;-ilyne5t<O4HydB1uIM^!p>hQ7RCpqoBhd~i2SIe~t20GKv$?OC!3E_aJT
z?rJ2=_iaE>O;me#&;@aI#Vx`*0Wqz^>_G3W@V>)@iGvSXZr>!viP$Jn93Ub(+F2_V
zj=xyWaBy1%keNBP%JuyOeYie!f1m`^FqK;7lyhYyaF!iwrcQ-LN>Lt!Lxrev5X791
z3;g9SV+t}0GONF$$eDil!a)Jb;SNajyL^J+*~Hp#Qkykb!h;|L^c;z>LhoQi_06^v
zcs;a60)ld8T))?kw+Ah4y(7p4v9+Bn5Yf^)d=qYHU=n@RCGS~V;qJ&|fePW)L4n&q
zzC2_1>)04Dk_u{KBCs#|BBUE=T?<P^G%V5MM;R}IaBq~^)MSbx&TQ)9&Kh|Y4T$LJ
z$%p8HwaWN@Uw>?p#pLOnDtX&70u_&&pJW#HlTaiwKHKI@@u-vjZwML=f$^8v_(>pH
z-Zq7#1Qr|UK!wXA*NTA<+EV_LUiqg|1Rr%Gmeh{DCtAPP4L=-P=JGc-BvX4*0Uv;+
zp(mQ*<D8xHL0P5d)z-!{hsDL}*HW_%>dT_j{F@Gd;p@*y6KA?$S#rK-f$*1MDgX`7
zEpT#NRtmyqDKr2-v@rmJ{6ynjmGg!MEc3dLhLm<3#Xi3M$BclP#4b&aVZb3xmm!4}
zzk%g41-=59T@}(hcq7~REv8C&pY>@51-T;4PA~uheuo?`9%yN7hJ(j8#SpRVjIO2t
z5bQD@hIMI}kRO(ec#@KSg?@q#18oT&De3Y$GxQsKR!91hheBP<<73wo!=IFf0Q~Tp
zMl>-OSmoELpH>T5A~}}e+6eTIg-A~RHQj2N?FdU@^Y7Q$0K>=KCXPT?rx4dAqa6@l
zVT{LLS#4{V3dqh)-B9MDo;8a>!7KmZd3mykT$s(ChnWrbv>J)~Yks!E_U7J|_nHEe
z%)T1;VG(t8bphXfl+K%8&&?OT3y#L0Ytz1Fpqlq>Olm$gJ4PpuF&WWqSgF4W0%Ey+
z{HZ4@+4EF$PX}Z}5KJO{>FInuw<qv*b7*=uh14#H)c2Nv>?L?eVs0hCEF}d=^fimT
zxA%0@oCbrcuwy~X&Vjo-P0Sxg!P7ehEk@~@dpu%wDc5;yBV+V7^U06wAg?oMD6cJQ
z7GIz_q{e{(EK!*45?K=kp%^_w(0CJW@D@@%An0$I-05;1!p+Uif0hs$9SIMCRNaMr
z`eh)??o{mR^ks#-CDQ9@Qc2?i&Uee2L_^i_mFe-UoDZH+M6U|sd#vwMDT8WwMEvdr
z*n~Ze)f2)$gHZ&?%y#u7M@G&49{I(>23iJqek^lu%Pj}*^7#85sV}N(Z$Hq)L<$tZ
z5xe~KrRQ#mv(6HD>Gy6wkFDw}#8>L$Xz?8*Fs<Mo(A}xVH2>F!Z)GeC^GRqC;z{|M
zy^I+l))4n4X-W1kV(>k2M7@M~96h0s&;6NWx2dBa^t=n#itlQGJ!anHnOMZA1fE?`
zj^8WJgs8vAs4{QvNK@lmDKqx$JHbdmrzuk>q|w3eG0z`38Z%m!((t{*;>750`J%Aj
zllo$frpL2B4qq4zgl!hFx*L28%?hE5-6)Gh&>I9|#v2Iq_25Eoo#gx<q7*KbjE>-E
zofe42vfwTx*pos7bZi+Wiu$#5Nh}~p_0f(hEuWfjaY2CuXDF+1-1#aY)a2VRvGdkl
zJiW(=?f3o5zwv<xxub;AOPhjkyM)5e{e>$5N&uu@n1zpvWV>ywd(*#@7hbsoPoMpE
zA&N~Y?jZve_NR5ZZpyIRd_y;Uud^+!Y=xX8v08R<1Zvy17N+Jz$co~=h?Nffgs3-^
zvgiZNgq|?M?6w03gs^d+yif|ZN&e2mG)k1)^nOE!AW=8X3nFCA9H$#$4i#DNg>VLH
zrU$7N?TRX%pfZDH3}o_*oKj?#QPo)H6R0-t#GXS1K2}YmbFN1oF19DduAnu#^Z1GN
z4st)mW8*7H3u-3y68d6(uR$M`2vC>l9B483JIwRPNJ){Gr~MkY39$)PUDvB(W&JO)
zp)6YL0t%?aP`>DA18c;dZSVelJeP-0v(1mIpY^<+IhQ^O^~~I1V*VJQ8kDD%rBp3n
zQ~}R#zL4}ojHLtUXJr4aP)}1!e;WAMFycWtOVlYIv$tnHcMS0cp*1}NF$#nb<AyMN
zWaL?=O1+@2In^vCd4#=w5R+zMTt;}lV@!y+Qr4&&yr1)k-VAN*y(un>3w^A@3A>yp
zYIT{a2i3KF9&0vjK59_QVV|hleh_=Sh@={Z-ULg*59loSq`jXC61i7xd^VO+0y->K
zZ#8`!_Ef^KuD`|&UBNi|v;QcT>@7a-@?(oU$o0l+TtgyJl{a>F#)L4!U>El&L<R|B
z`s@WtSr)5xa=QO9<$K#jotX?`!0Yg2eznS#wWwenC$#*Z5HSl*rhL^cEj5IQz36Yd
zx=zQ@+|fBVZH8^Zlm6GV=dablpQW20L-DVs{ub)Lb%q1bb<Hani6No*gXpz)MWqHd
zo4JoHO@})$ro4TwAL33(m2%Q1YSs}s{X&aC_U@a9P#CJ;&xT?qg}IU>@Bj&;dlv}W
zfFKNL1T>N$V}i%^n2pFCCmml1->RrlXK3V=EA?Qsv}#_Q3f<PPePh6+;-Z2Qr5@mw
zo%kQQ>1`kw&u$l%^E(CXDqUAR?AF(d0A?iv;hd#UT{jKHkFWHG+ZyI}Mu`~BkApFg
zQk;}X&KH1yNyYYvA5^87-h&W*{b5x~IDF@8#)%VgI~Yp=en=^{a_f)2k2(Wx^~0qo
z%LL198v{(SevSw)Z+J|+NE~yO-gu)pBzWJ11YW7-TG|Yz-T{OV{=vp)6FZ8GdnY&@
zhGG>1#)mcn5Go&8yd|h+?!Sls6SG0kmwX9Kmv4_crsD@-7J#^HF#pHg%H?qQPl%o!
z#R72+-$>B!YkO$Jx@R5zNzq6|5{92x3UsnwOq$^tqP#R44e>5CuTr|25jXZ)qi7>b
z?*ewtT4fT}^%I?c=LvK$PMNqkBI^9p(%-5;)y2fTKVOUajif9=*f)=645}%D>+GFb
zqy2x1v`X-W>w>^wZ~DH|S8Ns*HlyP98HhWCXw@!_xDpS?6cf@4!Hr7(<yvOQ2pKgt
zBO<bPh}6Lv*uK|s(cNbmPwy%Tz8aX+8|3eL)!{lYWr6EW@Y;{e>*?%!f$)y19pa@-
zJio4@CMj&>Zc!koB4H72>e}vF0etY`bWg>60QiB2a*vfU)bwN!qISP$r{GX99x2YX
zx0d<<<bFXYgvSF_T|iRq6-LuGLc|bbv>|AeV&0P9znzb+Y0-X}u=H2QsdEi3acqer
z^SLB1G;6wISjE0ILYewQb50Q@0jI!<cy(XVJ&D#UC-Z4hgPTM@&`5-SswBV#Rr%c`
zbw1qbisbb1D4uR~q5GEHcXOarRDw+c0-zdnP<_7BPFPqcMD%kz`r<(x$k*HU6bf`@
z^bIDpo?r;OiG&gkI<Kja@N*j&*KPYX`sJf*Tdq!)W#!Zp6Y|nj2@HqScquASNt$d1
zSGU)PrLpNtVmLv#JpXYc|BF0iuagJMc@aE`$gb7IrTP$g?Bpmgh=L`#H_dZP%(u_P
zZcGKdUY$%1^jH@mA;t<>bgK1M@6(Nd(<Z>mpZYiy0e!oG8hvYK4?<-&*f&C6;GN~V
zI$g=@+wJ@-Jy{O5dNmYzJ+b>A6^o1!XwZe+LvVtOmTv}Gx&y|%ysrY$PLL$o;Q=7<
zErRy{pSzJ0#7y;xtQ-(atuA{fUKCe)h1MUGNCbR1t}nDc3Eig4jGq;2aeT!-n8+FE
z30)ce#(?8=bv1OAgKyA%e9VNPTfKCe9d5bt?gP3Yyf}XNIx7BqahSuR4gd&=y5*7U
z3;9+ZTs$#U+>*rieJq^(=V<Y@2L+(G=F;tSh9Fnsk19=3n6++Mwr(aCSMT~jgko6)
z6_j;Ymt~lQA9;!N2yml|lEPf@F4#IkIbVU%_~52YZ=<$C_QGpa{x=x~m6pe&WtPRU
zEqCvR#S)`Oo%y54Cj61R4+wZc(Z@p}Ew~|(JZUHo)hB--#KFQnvthAp!E_gd6DIk0
zaK^9h#+k8kVC<5O5{0_MvYVstLV|g~Q#{#6YsB~LWcMOO_6%b*h;XaffuIo%vmmYz
zn5V8GZ#`FzI>+R$!OZ)ZT@zE&pTYT$twqu+Pfy0G%8hx%_wxPG94Vy+G({HA<uC=-
zV{5On)wZy4uQ8Wb8U8{MW@RoX7i^qSO?CS~Tg-34V&)}8J>vh5l^OpX<zM&$cQ^F`
zgf|Eop<`r+KZ1MXHOc-aavFFjUa{e7=JR5V4ID7RJebHGn48mB*|A$0#KvdeevTzh
z&&UX#Y0nJ*Y`SMJ{I;-2`F*U%y%iaFy>{RA8&H2wMb!DN$QS**?@FCsG9D6<r*&SL
z96CeL@M>yU3-`XpzR8zo%UlWP_T-VfD#)Ns$JaZ4A+kCFZgf)VQQD~reooNC*g5W5
zn@)O0sH~};9L%^5^=)<W(I=})a`l?P3xhGeymK$bLY<*;h3^uKiaZGNk@2aRn_g@h
zNTD&E_~PZ4zRX~#j#9_b@-zb(YnB`zt9_+|3vvL{9v2?|>=RDr`~>zXfW!X`@6X*{
zawYjYnoAbi{>7MhSZuE+<z?^p>gU|}m8y35jNTXl6{uIBxq#=pupRSLeiwyGddCx2
zko?fj`+j*~=+)IZbWC6Sv(6)Tb!{{3*CWM<?|8izXOJYE`6i}Jud7oBS!B?iq+*Oc
zOi9|k@1bucUB}id4k1NyDutXuC9KJ>K;xA0P~|D?S`CglCI+%%F%-$`PgD($b|a>@
ziKu+{)@iIz={HSZ)`d8{-<DGGEkfL(X;nqsbk%B=kz_yXTm%F%PBj}I=D=1v+Q~Bl
zp>bL*#i|H{LhO`a1G!|XqPwRiC9-!<$Sinh^_P<B_Q!8LRJY^=#IRwS`Ahx%G)Pa-
zej8FPY7!l)2lmp-;t&{q&?9483sLMQej~CY@_yi5pT4)-rio>=cPCy1lEOw$nL_4(
zPvm}rnY`f;6PwIn)hgBN8T{!OfYcHa+kGKAP_*K<qM2>Wguq*by}yIKvsCA)eCQnO
zLmEshYNSAu$XrsF`Om!<A?^1dz4K|JX_?-~gsrD!eA%}JiqG|O4ja^fBQwJ#um(oA
ztDY?NlP|~RtL#s|@=;q3kQ+3qqBVuxRH;rSG=#SDg8}>ZxDPh+Y+adI!{ys0U;G6^
z>7ot8$Sy(}@mGAMu!rgcpF}S7{^I(Gldwf8*E&}%U4`G}ZM8U}e|5_jRLhH9{kzEC
zpC*;rd+!$2S~_P@$X6W~h_&=}AS@gwYP}6t5temrS##RrgXhZ*pnYOAqoPvygYCA9
zFnREU%b_!W<(hb9vXZWyv8eE4XQR$nds<t2Fj0UaIC@Y=aIvZ?T)Da>E`CslJ4LR9
z!QOcCYRZl;QGxPuxr`rEdYHkOK;{(1w6jW8dqGPZ{*Nt@k~y9r@S~m3w1eB8@DuU3
zI!saPwpKj}jDpTn8FyOYAX9H^!W(3WmkMkkS;uoeMw1VBtJUGL-MTPZyxV*tv&--k
z*=z~0ja5aEXKYpiP=~X`<nDad5yrKm0B6@pgq;oRo()`%VXrw6Z`pIsHac%^QJ0y&
zn6aRmn$l+b-=fGD&%B-O>QDCN99gfnyZ^KdTI$~Z&oUBg{&K#CLdd*Jt`vTfyta|(
z<Z(D=&hf?s0?yl*EUc_O2OWgk|1qGIJD%j0p4NrZ%VTg)Z*L!UjQ)MKoHxSzRU`tb
z$VGfn7C|aQ9aEfiL*c=p>cABS)$|PB37XnzdF9HO6KZK|mVz5<ojC?;EsI;u2u&*-
zc`Tufq)aL_`b`hmD7wsvHAZ=yw;!FYKF*O^{>KFXJDp6NO^LG)J_qZng3hq8ed#XI
z1Md9OR~G|x;{q}>vq5h{JEl9}V6*jKDGjP5%$tAtMG%>TDPoFS%-ipKznwCQmJ0F)
zW!5^)W_ABEJbWU0qoU<UARxw*4pXOBE>Nq?*Ey;F!#^NmO=udbU`uM9LJC<P6LSKc
zf*X7NL()Dalo@intj#G+KzI0yHFi^&P`<zKH+Q3du7t3Vkw^&yoEpngI$K&0Imi?K
zBsjsFtl(%wK3x_I@A?oEj<1QX3BWG~JKS^9QvtVeeeEoZ|6=9(&HjuoVl&Lt?^OtV
zz>-DwYx2eb7>P?r<d-N4j1U~V@62pU;0{K}6{vLY?wSpWBTrcMES=Za)<TPIGMEi6
z898UNjUbz|uxm`;lAU`x6PW5k9%j?RXh_tMzrxKMj(jlD$04ZvjW{BB2VD%LH!%q5
zWf7=@BW8f)B1=&#zD6j49|s!|+tPx*Fm&eT-h?j?XEAp|<+kOQ{_A{U_WXRjarEnM
zm?g`;36Sa+G+W>fR`LvhM)TF}zU`b|iF0DfiIPf-(ie>Mw?k>rBdei-SFgnfcc83i
z%xH*UML#<t^x6bY!F9AWRkx>r#)Sjk*D9n&KN`ZYu#>*B;~_RmwcdtIWkf`+ZH|m`
zGWvjmM3^SV){J{IoOq;7zX*tp5y&(9l|Noj5}Dm{LD4o_=YCWN%YR>cp~*zwA@v%z
znJXRJvGH-rO^9BRNBOSivhoyZ6d=V?VaVTJ4_{a_&{i23+ofB9r|o!z$fUBTLuwLt
zUqp}Z1R;Y!bfkb#sIkSx=Bq8P2=g{6|J9%UJ)d;HPgi(4ltWr%5G*0jsq|F>fY=C9
z-3aGf39qLP>+bJ|#Y;;Qh>Jo+`R}=vCKVA4e|SG7Hrh+_9&_ySLC$;bQ>JsN%xSI+
z)oH-{G(`o3P9DXza^S3GEkRSH#Wr)cBunf1^bAREC_WX!nMxIFmKW$TdJ4;^$b=h%
z%x&E5Q4L?77cpU>>NOK0puoJA-liZ_9JE>^yJoHbjt?VxefhxIm2Wr<14G}A-jM(v
z*#E#!On?Zd)32>snbcwy<@KU$u1@#EJqKifCFqkOi?E!`B$H7;L6;T0z~q80GsF<c
zF8Fqap7$^Qq5WgIpK8YN>7Ds;m;BWdHsD}V_k_Yn-O=_bn!=>=PkiH=M7FPR)<N91
zuqPoe;dXl-59<1hoM|7oe8(i)#Cm%S^G0W@ls?wZ)5PH$&hJjEhxMqJ)0$oB4&9vw
zN*{417n{Fh$3~?Dlj<_=95@N{ZB7U&@^E)P{x|3igM$weznPNU67<!v1!w##8$#$(
zR9k+nDZ|b`S0aoDv93%_!F(@KG}qkNXv>W_X?gfi_g+UELfP~mRpap5aMe7+CF+*=
zMrFW5G`<--KR`G;W+y8qvz8?O!2i!3{;Dm8*CJusOSz&;B#TcvnJc5+T~;wPO+QUT
z^Wmq%9X*0<J7;J`(ZfXa-TKDkqdMq<ZIm-~*qo@H69)XP!n@Ew`Xif%=QDBS(YLuq
zs0KoACw+vtlfe<2f(99|CZys>++dGk`darLTvN=TVc}ZsJlF~(97i6?9Ey3)xM%w3
z>e+=$TND=6j6b1CHJJ1%2{uuJ3N>kZ)QkX2{JGp)ZuoGV16;s;$U4vxqRI3#E?SdQ
zkhX{lZR3GXDN+qiwARYW7BI8=elz2R25H^5T(~${@3<XLyF4I&q0tDtpj84u!ow^s
zxC9I<zMSDMat64?J0q=}rq7f=-tByIk$<sh!Z4}yR}JxeWw8FOO9H@Y5En1Utet(4
zgMt0$eXXjF4@EQ`k1mXl1inyu>OehK?BWYe>+<(LfX_ms3iKR#;6`e{{<UbtWF_LM
z+u3O)p}<NcD4fnY5b*~Ci>s(3$>B~8lMSN~fGNh@$3fxheMt7+xKL#imcnl6Htpsz
zWsE<|bgL(4WgmnI-jRouwJy?Op+uEsl<<dS>zEbxq^cdA`oqtZIb^oKq`5xAW?(U|
zT&W7`5T9+-!_T}Jj_$xIWPa(Y>k?`s8hM}v&z1K&D$2xxx~CwAJIvb5qa*&W%^y!T
zx0I#9f{T5EYkz5|Lgq`}{MlC(h=knKu!<xb(dOi-8Zfoijw4}>{R>gx&tRci*L>@g
z;|r5(@BaRN6s5qzP@_0h=Vd7pcQ&zm5le{H@qdY*6{lqWkd5khgj~iEWaj3#V^RPt
z^P)L<3TRmQcTQ752+F@qDxViA>cW~<g0nH57HDG&6?{f$W3KIov~O(`&j)7d&^k1A
zU<Y~}Q@@O`Lmw8=+{=sJ`d?|fPe|`d!MVi6I_M5oG48^2BEbg|2xnrU)!{bQ6ml3R
z{>GHE9aU}{g~<FHFksG5JGxXTak$n=UF|RAX*TZqWF*AA4B{K)h6LH3EeS*s84hAF
zfc%{?&-E8!_4jO(TcM+O&$RPLq$6J_oUI`nFb3><<EKU&a9nXQElwO+te^hI1E-i+
z*9~_mlq@;b2(t<d25jPeyA$aBQ?Pi1)p%8rUP<YLfT}GSd(1fJc73!?Fco8<63$y&
zo1qI;$SKuVWPrGgW2t-}v^9Bzd2c<7m6caqO!v)CaNg(Jv`QX(3`wFWL={1q&|Fwq
zbB-<I9ii_DLGmB2Kd@<}IG}O@<VOTZ9gBg2p%-x;KWYI^w}~AbSjVOQFA5v|hHt;S
zqH-ze2H$9k;iATIw|i%x(a4s_8O`V9z2OWt!x54bNI#u^W^_Acpp{wTppH{OoDCVH
zVAB0b_{k!H;@>)Ut33>}PM_^h0T_cH7?0o!HehSuyMtjzY+C2L$x0x7EfqgA4~+(%
zbvvWdnn`_#Sfd|4*Whl6CX<1<UT+xA*3X(UwByg(Eu_?=vi-G5#yvb-1OzzH115kz
z7Zv?FA$Z*cj>Pf9AF!(R9;Aq-Z||~4WciS0*<!@CA=1ZW&1%=I3j|as^1-*2I`wbz
zy#PY4tg855{z}sDMLgWv(bAYNh|+XnJO%vqGz`5$rMyt7>%OwUWzK|nE;KKSC`}_<
zJpVKaapKw`43j&dpZNvUbA60xc$gAlkg+I=&Q`Lvu#{)z-T2mn+Tw5$eD>`ey|70p
z&uq@JFjz-?15rA6T3vY9KQS0UxJ_@X4<I{e)+ou18@YKH9a{}NW(X=0v#jg+e>7cX
zR8{@crMaXumky=7yDyCrD%~yJ-659-Y3T;(?oMft?nb(#>pjnZt@jgOU~ztN=FIHb
zv-cLS&XNmy-4k!zy!!4mU*8y&F>W=T;|K!OhSNyKMhsTGZVRSCCL$D;Rw>-K5#x_O
zL@FK7Sg<VlWR|#8juXvcPFa8$N8)E#W$fcF`7>a`kYp0{PA%g=n}I??E=Rgu>5rrB
z#O}gts!KiXjoHwo_zgSj91G6=i>*;8;IMK8HD<9=9GdqQ4>A_^?obnKXGz_EkHwO2
zc)ZcD+-zk4Ictk!*Lhi<-Pprx@yFye0;}_C(Y=o)0#_tq3GP{B<;9v<{=oVW@8!k-
z=Q7mTEdwVAGmDx1XLXf1W&l*LSyq{=t!Mpo9zWE4?*Hk~-(B!ZgjL(wT<hN@b*u@N
z64N_V4*yT;|CZCy#fw)f|G-F-K8^c?EV6%4z%{A97N}pxsu<L$)0S<hCHOWcY*H?w
zVEOsB%I8t>ex$f7akwQ<yEM`9WgkP>=O1{C7yFmCHIUbA4_2fzxUVkSIlo-F>ORbm
zzOc#|^rO@pw!wVcy~flX3fOT#U6RPJA9V7h`Pa-(bO4~>9D^|84AF&ck^h}e=%MHR
zIt&7SO(!;lU$54Y-a;HJP$d*;t66LCt2+h3^LFLBh)p8cyo+ukEG&*#5`BB0%4Pw2
zv%QzXO=5GpAF#Zw^AjUSNp@1+GI3C$+WEFfS|1XkTMC1bqh0CnKC?!2Mti5u|C#W9
zKBa3ZHqylWmQ{UWzS@0~eD{P@cry6Fd-&j5MZu_0cTk}PeS@NUPRFK1&-;=`*LTaR
zD{`7It>D-~Dil=hOpdILp5x?+IH%3>kN?MNjybRvP5uh*<O6kfZ*QdQrh~1P)dlkk
z%E+)Q+L+z(kH_06#7MBk<z^lVd8E4@6DA0$q?Xu3@x6;7p|$Vd{BO^M6=HTf-#znD
zbJk6ClJK#EGq~U<(3RtL6_QhCrT=K_B<@;#ldn>*t=IN;&!+Lre!KE|+t}%7pwX#i
zjVOSq*2^j4F@*E+v<uw98V2<Ey1@UfI~!p#ezPRS$Z2D$6XZI6^!vx10b5I*|ErdB
z=YD`q(9S|;)>^kf?xk|cst1fK@Ls1bX<FYG!ePqmRhc-rs7cb2QD;P}M}>g8M{S7y
zvq7*oE{z3RThuUk@OEFv|FF8RLuaZQW>pbkRk2(rIAtktHzJVXy%(*okzagPkn%yB
zZDM^YF*CGqfTbzAS<1ZK7Xcd^8w1lMU@w$+pLK!VzXIh?CkVD_VJ=V9NHI{Vko0!9
z;v*l$a5xqnYLmlKW<QU=@SjK3E9NlR+jx|~t7eRqrQlHOYxKsP&c->nYRF5@l1-jk
zsiBio?M{sZmZ6amRj@YpK!QBeNG%WTAW5}Nbj2+bfn*N9`ggOH64omA#UOeqBdqN@
zikB+>>nlsUO!54~)lvJ+)v^OGz38mt`US!0BKBR^Y5S<~PU_G=P6!0@FUM=3Z!XeR
zw@Xv1&DCB9EB%_?B^?h=IqHC8$A;Y0F$^R6eT$hTXbjn8OhvfcCf&D76CsXim!rcP
zIeFh+8a0IO2+_Pg$Bz&JR$t5+NxAdzBYnzfIyvEYDpvj0kb!|hbZc3>kAS1-KoHt!
z#NsAaK*A)I0dtP(aRxyev~kk5?f&1nFRI3R^Xl<0EL#PIaNP67@P$tQ_wiTy{;#gO
zg1#K_wMb-K+Ec+U^jnQ4X9;q?(()6jSiqK7x6Tf(?jh}0%}-k)WEzOSw_R0Fb^J0!
z87YJi;OmAzYJ_du_xn-8jAQv1Q;RWdvPqwN8a5PKqLXBWSk?ZBdV8`Ixs*mE4gyzD
zg#hh}adTYfYiCVO-4Js_lAGLr@GKz`tb{g6!^Xi2FfDNKz%`k&YP>M;J4i@vbLm+4
zO0}H$1?Svr12%Ce6W~pM5_2a`G3cs)iNHWH<M>FwHhD+$901E7taN4Z5dz_^Ju2hT
z&1egHI2Pcx@~bM7f;VLurd}`bR(%}qktG3`$PhIJdh?c(h+4c4gq12{CNgNmSPfoe
z4SW;ZCzj`DAK@8qs5BX1T;f|b<#^Sg<OR&3>~ePJT{49+%CEO{)$Hy}HJsr;ikQRQ
z--cmN1o&e{)Vx>rGQDm;RA#jN5Fh`J{NGlFXg>Mh{zgvO%;Tn}&WoQdnZFz}cqI#A
z>}C|5KR%iYIBdoE-FVPlOB#dhGHQuo>Gm@m3YF11Vqq}(-~xW*HtL3Y=iQJF^-KcJ
znKbI_M>C9~ujgVTlxRoRBgyx<+5Auu<e?_LWDcY%zk{zxS~lX0mHN3)q1rH{Y{Zrd
zj`itKs3qQE979s6_gAskZSn<rk5yh%!=*9vX&yl9=zjG__+!e}5fOFXY+=@PFE}{a
z+GH$dU4?HsXU(QilPRy~$K=5U+uQhC&}DcHWJD*`pga4eSUE?(ltztQm6&vB@SXoA
zmbn{#liqwLWn>H5D)oVcqymW5xA-P1;8=UioMRJVND){Ul)lJ}4f1}Leqh+EnRtJT
zSZF|7^(S)}S(qJ9nQI6YaPI#tp0<tesS;5SFOG8=>I+7=&|}-v#>V(QqlwaWYyXB%
zE^<X*X|VqK;j#fu<MQC`VRFjO)*lTiuYNbev;EFuBdnBc<z4NR_D+(0M-)kl{Rfr0
zt$gMpl)@*^EX2w2Kn511^oYeXTHr)p2|ZxdQ_3`3z8<=MwH!t?XDO4O6-R?N6rgvy
z3xPFXBE|iijG3^qo(4P_(r3VKlrx$pR##6k<np)U^CKW)vFPvMPraun>Wq^8+M(QY
z4IYNPFc~mzc8ERYr)FfXx@l=!w?9XxI9wl%BUtffFek~6(O{sySE)Kk({}>V|8C^Q
z#-64`3&Ofd5>!vIDyf)X63tfv!7%QpmgB5en#T!X!n3pvJaOI#>E}Zrhl-|dX1z|i
zU(iO4jQYA3WW<mE60t;au>Xv9A-3hJ`va(jT=P|1PfkEagl?YY0p$R(QA_J1>%vQ%
z^(SRNbd!XY4O-bSVm99$n$^}p%E$^$;2-=YH%T2b)|87$!NFD?1aCL_qF3hVbFo{7
zUJjb3Q#D}_na=E|it|PBI;63r0#|C6X68q&G<4`1&7+|MH;MgiYU5a?_l_CxH~sq0
zt`1{7!<oC+?R+JA<KDe1rZlY-GU9zG#I}Q${Y;Adt)wbiId<p2J))0EYSdE)fA_dN
zW;1m3yX+Jr#8Qbtq)Q2|#gh~ZSaHKf%5N(!s^u?{<W5AO{9p)fQ-VN<RFc0Z{+!HY
zwX9Ipsx)%Vjqob$@e{g9hP7*fb=zaveGfTPcP0ONeWA&YftgOkV$4Nc!pai+PZI}-
zXBF}`ZUZ>Pv3n^FJ(;~u9&hVDgD}xDn2lt;wY}ph0^n}jrfDnggkJ>H-AmqvY<@c%
zFM_m1v^WgsOBNGbW&W4=nDZ(I>8WY`-u}0;D)fX+2C1<6_m9__KMh*XV-XP|cFX`O
zUw17F5b{j0JVY5IM;+2_Q?YeN?HzAWr>E4C#W$nZeWRh!+QP)aSqS{NAeV`>S(HTn
zO#g^6;@lo_Zz>T2bmj{hH!F`YDWkx!EsjktEO&kI^%*z+D)%C@&P^*S`~XbJSK%)j
zj2)Gzs<IjHD5(_;^6HqRw{~itsae|+n$Kc47J4wH!sq6wBU;iOt^iSSYaK8MmI1#W
zbE|RLa*kxoT*6lo1UrfoCn-)6OvxV3tBFbGiT8H2@ye8lqdEP~<YJ7_V5n{~1KGP{
zcCyHQ9Jtxn`3|U`sP|abb%Pe1C?2nMIbs1%T#&1MjvNS9=)lnGfEoB|^*ZO9=@Zi?
zk8@W+`V>&$D{Fukt{xwiJaJq+kY1Z5JV^&lQ%_T7^P1tK?+AFT0e%)fI#U1*ktUaF
zn&312Fbo`05_{}Gbx7m>hnE}^nMe;8O4X|S)!Pi<WrX=aY6%O&%Z<6GUX4RAHFc-F
z9+C^`P(x;fouAQOO?&QmIbS8rcuX~uCtcO)pKXrL$lvs$BG3@l?V1ZZx9@WF-5#g=
zFRpcov!<-LX~~fI9I_b<luha_xoJVZE!X%HzP=)FpsmQ;)xPymqA}0_hpIHDBsCoU
znUP_o_hfwyczVgQb<)x?g5-ffjyxlpxyM^xY;4u55Cj{c6IY(cp9iR4)bW4eqfFw0
zh`)lzfvD{~m~#|Xf<z356o(11LzP^8u_neL#f1(zyaoZwnwO_BXb$ROEsH^0pOx~r
zIC~p<6r(xPf$L5f8sy+PTRr`<Pa0nHBf8X)q^eU@8q0;k=5pS>6S3>c`VH5{;z>;2
z1YPv5l+f{ZuEjP*x`V3U5?%Ym$CS_SzIYu?XrO`#0bwKo7o7fck$ZR>^BaTGX$E3-
zh<XPHXAi-uV2GuM{BLnIYHEd)fbVfW^TPBX1S_8K<zJAx-*emC-BB$<QB3T_CiwY-
zZeU9Z?s9b8DlF_m)`lf~*^u{KT5^4C2PIEI%x73|sXrZnS`~*?-@5l^yK47gi{i=1
z=dZ@A_wdKtj;Q11P?}lmQ^-i34TIwQ>}x|Uq+BH7Ny(`r*NT~%x4*FM2NbXDiAiTU
z`Fo3ie#JQ$NRw1>06FoCWm|+E%W}>-W+ZJa45m*$z>Y6R#e?8}mlGV<AK@HKYOfMz
zLXm>ZxTgNw(h{B0@yh!+U2$2dzS@2%34-I(H7)T{%dLM8#J{5d?!5+Qdx?qO=f0D)
z`RbvBUJDk7qbCqf9JK{GdZ&Q`jHiQ-@uo^zr5f&b@?$A_+t%O6<&s`UDgj{ys_o1n
zHyh0u5zasY#y}-O$ZR&=kWx65-fR%&G&xwZ=iK${qYM^jJ|2*^rUw#0YUn@k#bgWi
z+=75-R!iIC#L@&QoT$&prO~f=Y!7P|<e*R?y#8i;X7+pR6U(%WL&PAb0xpv-T5a4N
z;L-hxIgC%X8yTA0@+qcckAM9okYen^Fr4@aW#kH5kQ{yA7^R^MTHY4ToP)3su=K8n
zz@TZLeJpGY>QVB{%XfJnPR8YxR;)&)(||NdQ0<#MPeZ77s$#xnUMH`9?esT&4TW(3
z+cJv5*f)1E@;0BeD_*oj79fWo;H9M_PA_sNgaabB>Q6Am{qHy2b06IG%T9M&CQC@a
zt|j)psM1)q7@5^yLl-rQA(Z;K-iZ3~_}V{c>niF8k(8wssl3cWy$|?*K>rf44t<f;
z<cC49x-$wE{n9YidC#4*%f7KG##ed5eThHfo5~{;W#~1AE$>FoCfMH3^(Y)}<HCFi
z`5nNW4X-My!&EpacJ%NyLPDK$#J;<+70oSL9P;;_JOh>5BYFW&ydS)q0#RQgj7{;i
z1*ICgRU@z0Ad#VOzlZi6B}}zV+YSd~p|?ZZp3&aE6Qda}_D#fTf13rMn9=vGAvDnP
zbW6^+h*kQVNx>W@OdjH(9D|z9rm6gNjq-<(fJ`-=ZlG&!8;G&Ogu-y(>`|V>UNc~k
zVTC1=xY2!DBWh<N14-=slJzKxSEn^4hXbb~X;{agZKidfX7Efz>UYFnxzSG4_Plp=
zbjv9BA_c-zWK}418yakiGiE6Z#Ve^&M|L8KA6mcV&$<t!0|u4a2}SRhQaxa?PG!(?
zDY~5m-Fwe2mRWt+%teqj^Yw>X5~^ec=fUtzYo6ZJU28IHkX5e%=x`~zbpQR-C|_m1
zS>q*{ojTq7>Mw`F&7v*VNG<L7r7Q)NJUa`qji!cEC0_%zuild&A!)mJHr|nWA{aRc
zg?dF<x8qVF?B3AKGLcoLPlcVM72tgqnfZANNKKw(z!$5Cm)Bp$S0zj=G;km#&EbD3
zTX}xvD@ou$8gyAF?`GJa;&^OEQ-f>KJ+Np^Xo^!P55*eBM<shVicbcjxtwa==S3C_
zg+VQxIM7HA;T0#=A%r~WUKhee?3mmkw+*%s+Bs?-xOWj`ob8@~DBLpyE65IZnTJ7v
zkdF(}qvu5|)Q!(+XjCv|&Y6lPd%HpP81r-TIhsFUmfw-#e7~D$^4_rH|5V?oLJB9I
zs|n{|KDtu?T3EiO9no{P?j+1<)Rr}C`L6zF&HNh#@<MkZGRrjA@b-7g4@*+!r-a?Y
z5xbzK_p80WW<6?URRYX1AjNv=Q;PMCvo&3C@9NW#30x^hlLM{{-Ngr=oKJRb&N{jv
z*s9ZBDO3}kK^Gfig;Ev9J$vOVx)tK;NCMP{36@@|p;&4VuZNwiO+p0n>)qLCVF;H$
zTJ#=j3<0yQRhTBGr11S$HvM#|vT5;xJBpq6I51X`ie#~9fW=Kk{1}fM1frurGey1n
z3tO6dmzQL!&KB+bspT%e-5piKPVfAeO=T7lxtbLoT4pfw84geh_SD+mpBZ9Yh}>iq
zJN_#*nUd%azhhzEI9birS3br%H7D5v2NKxTA&La_Ft2HMHUy+}z1S3(^sxh9)JT<m
zYK5J`Q*~P@)d~NzZE5B&e_9OmTbvqpIFijw76LosN80WO@nKf~2+QYEZ13+0XfmAe
zkRnJF1k|jBVde^F`MB{_U=SR1PG9mjkx^Tq7pTaUwusfL|4ND(LI{+}{i0+h-E`pU
zCyJ;apm@M4O^k51|6E~y;H?fOP8_@r&o;1*c58F??(LSW1ivg%gaN<%7HAO{ixoE=
zourcqUnRoVF47d|)3u5w^llzWKj1R$_ZL5aP?5jGVT2`#iqaO>YoBvUg)W5rs-M{w
zGXoL0ynYHCJaRgi6lX-+!<%>q<E+7FX+jjJ{<LmisX}kGk^iJ7@K#utB1rzn>Jij_
z2LI8eM763xMW-}h>zve73Bo-r+!QWD^Jr@0`mJz>qhU_FK$>{Xa$YdyxKVF6^00nj
z)%@UkqqQbrl&_WK>9j!o)W@&tG_O-F7@tc=9<TCP!X0WpX9UvOS0z^LWSO_(evi0v
z0+6I}KM(XzzJnnYyEEg4!7J#V4(jD0Y(D#bH=wxM%=zwMu;R;vf!3KYtGdCj91)(0
zC;}iQmh;*D3a^Pd^KBUGrj3$)iUbm|AL03YA0`U0m)&o3)MsN8XW|(3O*BBTD?}N9
z4JX3->qaL$a*WsyInOdhR{cl2XC-#k8HII=eq+SFk`ALhZ0Z(QIpc^u>RYm<Sh6QK
z!!sYj;35blxO~njPMPDQ`*IXVi3T7q=wKWKm686blZA~Tqyr)y)6qmhC*JzYybR=g
z-Z<~-OF}$XQU7QONF>sjX{BbQ0)s+fxJKuEFsVA0B6xE;V5V(4(SHf4>pYn<Jm18_
zS^o^nE|GLn$kANJ+;!kSVbaz8u=UK1K7U&i4gxWGQsCWRa(+WtzvZ$=PsF?XM3cAv
z1I1R0^H&57@)Nm8#Ea~$k=Gr12v$kO7jHcl>by=<?wkg236{PI`f5?wkri3P+`gPy
z!+YvhDGbfH)!p3>pGf_Q1!n;=*x;PChH9Cs{+4ng0g7QUi(}0@c$V)p4zmQrT<Rny
zF^I6i+Br2RVGd8{@9FZe69IQI*ePy;<Y4Mb58MlkyWpZ8b=DNe-6<obkIH=!)yU^$
zTkxeWbmp{|xNj$PxbiDjQ9Vo>K8`DUD*hmN#C*h%s5*b4&8L^HfdByJ@O$&FwtlMw
zO6}IA-n%zDa-%7|gKpbKtWQzW3I=2zu<f^orsz#i?yLXL1(1(0%t4%<ikJ?`U5PLw
zdBXf?__l>IcETK^oBW<S@01-JwNkWjtD^TUr*T;v%Viz)JJd2&3!cDIl^#!pvC{Ud
zHfu_a$q;7y#dc)L92o0k$BrB<74L>xMyp1gXv}^x2aQfslPsdkM9wx-hW%rS?Ba49
zl>TElVB8fXtZ#iPGrA~+OCy^<T5Bup_ROL5@zbE+>Eo!s+Z`rw1H}S-zCGz2{$=my
z@&_PMkJHu0(Y)832FOZ-D!oU%!Ojyo9N*(*htvH>SzNSQ%~bpCB?~)o`~2yX2EADg
zCUADvGG~c+7!{-9=oI$t8ab_#cx?fes!veOWIWy|@2!Ynpl=u*ds}1=J_OQ7k1jRK
z#PUUh#F9_&++G>N&4}a)sOuvDMCJA8e}6m<3sY3=XT9}kh*djVaP5{YoK4_GHRy~S
zn43br&G~IkA{N<%?$89LShIqyB_JLDoiK8!xX#};WE53WNkbnS(jh>9bhjUJk`k6H
z(b3Yl*L@~?w=L^`_Tu0)(O9<UE!ufy;r|~N^3Ep}r~naA+2Nq6%Od~!!WxSXWla)(
z+feZMKOpHp+ga-X&2B?O6@!XicacQe!JI@ycz80al9ka8-wmmJwcw3gLzxq;LEs(l
zizH&<)gW$5X)*Rf4rYQvzsJubMO%?HC}2cudvDT_K%p~~bDMl2LxY1C6Yib3786-L
zH^-!6g(obJKhffFc`J2E$5~92?6N#P#(sE=dSDX%6jk>XF@E0)nPtO4si!1H!rj^7
zzwAdzj2Kv~;z82Xbga?6Wbg1s61&WO2U#x4!EM^xj?BInCa7FncGH>-Gv@6M{X4q&
z_lvHOKL(r6i`j7RPI#h4ltkN7(2AARNCVBf_ObUH`B6Mtb+Z&Bt0x_?x?1$UuPxU=
z4fQRBFTztS#lXp#Ba#M?r7~36I$SD|M54hCDwf5~Tbh->r;bq2wq7Aa57uQ3qa*i+
zYtXJ(_?nCTX9}r7^keB%cEeG5fe+~<OD=QM#0fJ@6hpWP4N294$d|TNx1Uf;A)rb@
zfRWt1$d#%IW{!dlQZaEH=o_%cu(Z9nUx}f^F;z9F*h2Gv_WY8p-lRuxQ_K!Xw31YO
zwhmwi$x;hG9<?xeyjoAfSI4=40yvPiS}P=au~%qK-$!_(VPRBIX=XIq0@%tenLxnH
z5P8o@mezkOi4JHfJ4V`5>?lLVR_&@g*-{9!SmDJy5t}-;nu4N48_k!8oHkmK1vAex
zDTH?jpv`qF*Qi4vB#MB^rT7p(Z$3{StygAk<Z0yRV*VjJsq#sNGC}D#QS={aA6N)b
z!A!9OetLyxJJE`+v*|r+C>I~7do=7=cF_E<Jh{uFKgI$M&27LRDo0(LexWnTGkD)?
znqaK7DjIn#f8QCDfF{@}V~x?2w65PvJ#o&utxmVr?D7bw|2U|~J}5p6J~$k*7S8uJ
z&#<_Vxr6J8A_(pYSyI9x2`)L!<G))towhy~L(S)U$UsM@tZhAqm{E?soSuB-(gtU$
zUTaVubvRV)|Mn?zo9M~K4GZII&YK*(7=ylJju<-&b&NW@<51uv(FvCTC;S%C==V4%
zdbhHx^&(>uP1J3A-Hb>3xH4I;w-9FX)7L{};K;d{-`t@Kd<U1$)iQ`^9K~cd@3;Ki
zrf8U{xxtX6;9i$fR7|nruXUsRvHZY+AVjW`Z7I6j&{ooL&A!#XHRt%8t5+P-o)S4W
zh+e&QZ6?!TOvrUgpA)Z=Bi(<nsI5~rxqmr!+Ne%z0#!W^U3!tpZ#vG4^|#a6<yb>M
zo-KAJRo(C{znyo3v=gpk)T<;Tnysv5DoUTLS&>nvN76uj*e*NVXur)UEh0IozT;&l
z`oj3BPp-GSU|mJJ{P)*Fgs4@&s%|$@D68l><y48t1<b<A3H`Xi&%TtmfA(7~WNIdd
z6A9OMjQFO1{3BKAHmoH~+2zf0uy1f`oCuWu7U)pHNDem`WMP-^U4d~~G~JpneTQL;
zz&V}Tiab+rv?25mq1jrz`o(8Ys@CU^`og{_03ggGXMH;T!MGmOfC=nebhux%kSFr;
zNbzewZd{X)3pOS%73EpiwIb2^x<v@|!bjm+FVd8Hxz%(`d-HR#Ngg5iR22NkTK}7#
z(*Q9bV#<(%3I;aealyzC%hvGA@#bwEO`-Kv`RQGyD=1eAN{+5X4F4BnBg>N><|{~i
zIE;;}0zQ>8c$3V8G9;FMT$TaDkS4+AyrxMc5ck~cGqst>aO%WT-255#;Tm!u`{GsG
zAKJBRdk2{iqeTn&%0s<XI2_{_=}gb5x%o+>z{KG4=)?OAu5Y4XgtND2KEV$IqGjU!
zH3{fH8ApDwr&nYis_MuilT*$_2hQh8I6Mifa;r1NxjkmfZW6=bV#i`~J;WFz79fcB
z@&}%+al+;mvHTMulr(2g`^Jss$p3|Y+SQ*A6MJU`t&eiPH~b7Sp6e4MtfeB=X}VDc
z2R!cM5`sPv2GOM#r{myFqe)~qyV-!hIip$MgzcKaiFp(chos~$mjn+*uw}zT2W8|_
ze{dqg*y(M!Qi(wWN4ydHoQwrwT=I*9PPr@^6?Xu>@_Y1iG5?=No|2#vOcPIczhDJa
zIjZxR6$qIQhdbT(x_g!le>PnqljligI28rkw*)@x?9T;GW2Y4*pF0mwaDA1uttsrL
zPVS@dB*o<%y)(+%Hk3hx)HA1ptK<{ohISm=9o>Jij8ez>%Oqg1%|?Ewu3T#p)$^F`
znz?~od3QvRrk_yU*4NwFGO%F9wcQHbJ6WeBd)!*fG@-h?-r3W}6(&iX*!dFp9>g-T
z%F?qexg*nEUb&PmNMs}Y7-D8pE}nm)r68yAFma5?VE2`Sf5ACr$O?5Y7w&k)`FA;r
zbdx*Q*{?Xgl)dg%dB_Oh5~WJV;lHk^K`TA747jy0bQGtWqa!Af_ksPE{LOV{8Rrb;
zmB}i@Pt_+5wm+HUROYo2@;7uP@>}6H)?QsZY0{)vjdMcPFcVkXsc_u4$zdkC+%PQ+
zgwa;?-Ba+~qIlp?X(PSO3)H8HM}JH0%~T}>29aEHOD>B$yje9gZ=|r(_KNHOB#T<F
z%-|J-{Iy@higjmEfM{XhT7_57MXB1khg2KJmdb79#9_|Y(iiA4p;2FrFG+&$OD8yv
zyTdSDs8>P;EDY<vFInap3}dXgCc{04{p3dtJU6@0!MWR5XcC?Y+S`rmKVn}R2yk>k
zk_fYK`ukMsCgEz?NNS4mwSTj%0E9wDZ0O6r$ZpY$wcq(0o+@8vhOQ9kixrR}&I@d^
zkI&J-)%J-O0i4kyC>9WNM$cy5mHbt-mjpmIK5T#I5K<`0*U)A_w}9(v&+mgz+ezmg
zQS9Qo;g`!+@G?UN_(Ulx(){rWrrK#ykpo2M(=y%nL{W1nbXPD|SgBEi=vUR$`pRlc
zX{MZ<z2QmsQWhMll+N)(+@T{9W{%NA;BF2XNsBl&eLxb7pafMg_*7|tU<a&DcxujM
zL1nP&mGkkI-PwH9mbz-&7K1EBML^T*+S`V2$9RS23+DXk1J<ZoDUUS3#1mPMUa!R~
zcMT-??`UAxFupuvIgj)9B5Oz$ER(f%<WbM$;z(AGtAnYiO#9EzCZ3g$OpxBiG!Vn^
zWJ;+HddJMVy7!onTz;%SmX||=V@!XT7`|pjJ^kKhmN~M=iFvXTD_H|WX2s0HX5{Bb
zE`fFKTheRVf5VBRwiGb2FF<<A-@wb3(UZq}s02aF#KKY7gDEhed!L7h1%^-E47|*$
z*DM^iE%Et=P91!rwv4wa&HvFpI|Aa{dndxo%wqhu?hE9p55#Drzd!nA`(AQ)KBO3&
z3kJm@rOd-c?{}0l4z3b)^Ep^+7zHH;Gkcx%{=Vja+FsJvFflF6R!e|-$!j5XZt#UG
zHhq+Xt#ed(M@>!4slPJNl5pT~^zgaa=j^JZ#}Aw1M-~*?_+jqiAMROdmnZJ$FmrD`
z3}WM4Snb@wAB3Auf5J9~UOsc>z+UjZaGF;TeCbz$Pz9v-7<Mi&qk#UK9;N$~5zxV^
z`R(p(ZL!UrP2Y15zh3(gnI0E|1VBvJ8f#l|n5OcUFjcKT;8xsU@fmd289aZYHk;nm
z-nj3$JAavzTlF?1=3_HZEN}lanLSwenGlyLb{kiUzgiM<Czmw0pK++F&|Qn4kr9NA
zbTfxu>jGe~%3u?Ry;ZXezb(9pP9FllFePIMWVXW&kaVx3L^r7#rj0mO_|tc&fL1Yu
zZbK>6Wlcn4TcPq}8ji)sWa?xmAjOZ8lATK^cxNbfgU}SV-0WA{&y3#7ogv4g*>Crv
zL%PuI|H>TO!ScxuQ)yT$8-Amf!S?>IL>Yd!4X5~!#K7WpKdd2&jp(lXd#3P2_s6Br
z&Ho+?0gU;KBOh_vLDAKF9gl&*NC4;4r=HsLwc=;`l`^3F)~(gr5|S{P-Cug3FO@(4
z*VPqj2?I(M)%nTkktkxi1Do-$2)$l1+MJz|s1*5@&d8XB5F6UgwIugL&G_vV9^g4I
z0=Tj}hzcNt=<jBb{@0_Qv!dD2#=)qBCG(<D(8odo^}^f|q&t774QcH-s5!T`u}Fz!
z2VFKO`=g|M$~y1F%8P2h4vX1(5xXJC@bY|GVvgeQxDl$_etg*FG*NL6!4g^NONZ7P
z{q7;sicb#MS#)qhjaYI6ssR1E_5MRb<*iv~I!Eg>b)er3fge=E=}o?PhE2OTk(!Td
zXeql{-ke~<o!0A&zlefxY+nY#3cud-HMpOP3SZvu#1pKHkBw~}7H9Qdvk6byLZH;f
z|LyguIteh%_2=^+lGhG<;rl^p)u<k@q0zvxph)V0*ZoYk5BYV<e&c7eJf-Ij3X#CO
zmtZ<v21RRt9{GS{r<<i*AiPY@5N53s3MDT(c_p`1VT6b-KtwkJ3VGkT(NO1YVST5X
z$QBGsn9S-g<RZ*%s`Cnj%KS7#5%zN-EuL7|^cwS;k2YEs?7#C})z$p#$^)f`%~jO|
zDW<B}4UG{Xb*ou!-rY^fPA)b^!#~{(jacdewXF4moo;LYX=ixe|E`SR=FUtK6Ft7-
z@SfA%OJ*dmwq-8?W)!R)bEBhm>DrtpARf_qQ8Q_Dh(z+H#emPEq|8shi?0pLE8)Kz
zS0DEMCx|7vDJyz`=Xc>7OQ)s}wrc<9&bB%4TB&|aD2XwdgNkiCruK4Iu7g%-NtJEg
zTl=i95e9{Fvio~t(q)T<FBtfd+10gma$`>i(+-gdyOl&Ou+63}<)O_G#|#i=oo|iY
zSZh{P-nKGAd<)-X;PW_O_B%MD<lhNZJQl44fx*m3-547=8t3Z&PR6G3(4=>-A2h45
zB@La7;Uwk2eHKirbm;Yz+QsuFJ4v6bj5e}5=u<}GB)gk@D4TAZ|M^58JM)aKSxFt=
z$4)IP;QL?KOy;%ri&WMcGi=(@(HiL--?=X|yHtdi@%<Dj*Yd}e+#Gtl)VVzCa_5e}
z>ZR<zHt;7`yp9Y{l>H6G9an+`%imNtWIH>7N!Y}fFrT}FIb3(0Soj+k+7vMOiL8sY
zsq@yI(rq(5_t5npZxuCDEvk92X_P^RZj50~qPY%NKKM5>Q^$-Lcq`=X9Dy=*;R}<Q
zp^2z5Chsrc%fB#ze7dUWgu=ay;s}YXKpCzUHDEjrYaXL;nBIC=Bg*PVy<scMYEsL8
zjChm>av`Xor~7HHW(}C>&Hv8aYY^b}Y_Eo1J2(lP2(^>!sU4mfX#66tT>E=A-ND}!
zz~=K@HD%>sU&buZ*vd8x2V<kSJ=}w%YhYruMD|z4g1F$v{m|P#GLOg8SX#BL^9PSJ
zrb%PhcqX(*j3!JfV!sYhJ(i^5e^Iu}p91c_gwMYFX7N=%NJTSU)$mU!^l|ZdPoVvx
z;=plh*7I*%*(Q|Uw=gf%1bOIUnFRlS%m#aj(!AcXVa1X&=Q}+P$7bN;GEAfdwxR^K
zWW8Z7B4vA~bY4@-hd~8i%(KSJE2fthq9*N+^(&{ET0qBNv*JtYco01`5YuhNwQ!JQ
z&ZTQ~o6jddrbH(k6IO1GX5U-ilm9WXuuG^?LJi!BO;#Od(rufDfSm^6V3>8bEJUB}
zgkN_%AtTN!<XKN6cdB}ov})uuiVSndj9988<>b#}cPDG1SEiVJ8dYZgS5$OUZ>93#
z(9TP~$$zb=5bmHsMS?*Ef@F;}5f;YCm2eyk9<C1}vd#w-#%um}7aa^V4wnAd$tQ1!
zG@a)=BXdlt85vQ}#0##DJA*zE4b;S}z>W11XFcDX3J-R;0(#1N9yb_1FI)zJn0=6u
z{9XRW{@fSo#pLdm(Hnh@;)9Hg-pQBkcUx1yuteek@5=paN@ti?L%f`4qVQZKktX#>
zqM2C}oCHIti1)3r4QJT*(E}@D^!_;XB%tq)4J<9Ny-(DRbmYI_#*TX;Ttt09ucRzk
z@^z)7QsF~`HeeUAaW`!Tm|MI*LbmycUGbTiX><5<7!F!3|4qljMT6KIPB8OhDjwXE
zJE6*OteZu<%J5EK*W(?4TUpNO+@BG4jZ#L64oTqWZP9(@T?vz8aJ;|3{x8PH{kTi6
z2iwBfdCCCIw^^|I5}8Rrz><PVO*2A*<?v-zD$)v0TwYfbx>hVvbok7`KHju#LLKg+
zzl{OsJ9&8Fr^55iJ^Rk;ms)yPHIP!YkS2Iqd>k+!c)osnNvUz3w4vT>&|&So4n6O-
zjrof#DE{G32u?J@5Qin=iv0$ED5+CSsP^6#Wov0E1F3)y*f;=*1S#G;4iWnXdi=fF
zFE?h?-a%13uU>!}p&&N7(OWMmaOPHWHeI5sj6<dQJ_t%LI=KM4+59)Ya>@(P9(N!*
zy1Es$9m;sf0C@*y>@2NkUDh2IMF|rOI14HJ6CD@`B#4jGGbzOE_fPGf;JrQo(xv8Z
z;~&)b2R<KQKaOp4f^5RZVe(WBmyUV4qJK{arDl-#?Vcbg>_{`~8u-uyaERf?x-WVy
zC6F%-g3DKbZEv^m+UeU$9-lPkQxlt^B854P@-HpJj+^$!S9}rX)<Lg_N@?44;bL$N
z9v1gq^QbeDpTK%T+U!UcDh-BmWhqYi?RHvOEA`ucs*Xdy!&_)t7NAg7-%XK^on$GL
zk7;zdqbBL_;V{M4s@mRnR7&puM`U@sG<f42q#MLxNs%B3?sIFFjIhMpB@Nb&+R1DW
zE=@yGI!P6;$vF3DkE6aC0Z~&Q`HySkIujmn_<zH!Xbd1cIdn~e%1nf~aFpsYhlT2E
zm>D*c2ls5NjXB9f@N~e$%oSdX0zBY&W^HTTb`RJAN!U6eb0gd8u5u0}KqX)-jZ0In
z;$KcOBsemVfV;LJ(POvf1)Qzm_M@eB7<oEJtKy+#J~+OW>P)PjqU*xCD@3hj_V|}d
ztY%E8B*Vh7Rg`cgMIJN%r-KPVN}of3%a6}ln$%rz7r2hiE+sWUP_!o8ul8~FT-&Jb
zkefwQu*55P$38_}3p=vC&WFbZ^xFm2!GCZ<%yUHbC$BF?%Bl>#yoiDH0GJE_!O2nO
zCQ7c@niv_u-gp75JsM*EeC{eamy|tC{(tupc+}-H1zSz+M?Fz0tPLh~F<Vk^$8Run
zLvus<HVdy>MGxoj&zSURpX_$#d_S$Xkm#zC9{XW!fP+c+><l+Lef3f#`XuB~7+N@g
zSjGWxo#RWdu$_KKIJ=>_V4j~bIGHSs7b%Gm-hanf28}xJEF?D&JD4XM$S?>92&${A
zL9hTOl)mKs_6f2!%sfTS2Cr1gYu8GA()O7RaFrqT+on7r{k;E&*gAyzKHFmy_x|DS
zp|9Fza4EWWY3(!pkZ#Q<2BPXuL>NUrJ>pv8V3<Z*m8>sdAs>3T{fG+YD&~BEPO7=v
zVTQ+`n8z&|Dp?9*peZQy(xahX4q9+?ygp*l?cxu6WYnm@zIi`M|3%6?F}xRS_^M7a
z2Yd;Cp_3{`Pk4Z*>9==1y%=37+KTd!%jBt4>OYJmhjv@ezF^svc>lww=;HK9!m`z%
z<+3%~+k)0bq09{$uLX?jA0=HuP>?CS5k`#rc`G=OEZg$2Uv6$G9$|eh2>pICeUx2Y
z{6fUlR_vvR(Hc#}LXRd1<9+v_GLoaht$7UhVFiQT+}0H#nw$oM)@?FRr8Na#8q~-G
zeT<$)isU2Ua5o|cei)^iWS3NZ?G+~eu0`KujK29_Rm94wYb}1=NsvyO8!8Kd$Y1$J
zlSJwloJs*oJI234$UKpcZuxUataMA89CPOtT8bcvjkEA9c-&dTY<VA2JEOg<oen-=
zk}i$Pv$QIYV${?NKHn9;?aQtQXFosq_aFQB<By_x-<|^*;9t?_k7~RlCM5P0KS<#>
z?mmkm-;gk1jO@XL!rjHv9ccjX9be^Y_v(OWefsHtc^I`75!(CuzHb`O-J1^yOqLBq
zCo34h(U|%tT9%|We59f$i)6AJq7;)w6&BDNv{`SlM_@1h5Tk^bW8~1X&so(EWlUlI
zFDWEsZkB)^9en@{ds$71*-MeMmC6VJ5)#-{LZs=q8}mf4+IeLU<R<=IVFknSRl)bK
z(4N?BPj<Jr|CMie;=o4tCgU#r$)Z-T8vzj-RIW!*<lSHSI(wY0ih+krkXykIx;(w&
zwKz!`MxCM?683371M8szXItCkQt>e2(b3V=pFiQ$l*}pL<7Jt%hSH}I_b&%Be5Kqr
zV#qYuT-T{%j=l`1wPErp(LWSHgcQvD@xlB}zaai|vIkUWcSwsDenqKti3-(qv-b}^
z^hKJ^auh`8aCgL9V4KLT)s!z~g(TAU1f0Z3+J5&Fru$esss#%uqub8dpg{zFHNDux
z8`Cby-62t_oy0)A?InxmDDX=gdEPHj1)8+t(}@2%*l~I<Wmv`^nOErGlLsYxi01kt
z4<aRI5*OdJ>WB`&PJS;13QUtn9wKLXe_qno)L=Nov8vr3dQHeCeq2weq^hQdRu9%-
zjoD98!CR#d@sgDbG*KoWSP%AY)QE$n3`kqzWX%xCmRqAIk;tjhzRqosSiy*&WB^gA
z*dsO9Ov!WzwBONFA&6cmzft*J$ogSHuME#-L44hzb$kh>q-MV~XBVI3Kn$ph69K_k
zaG^ES+R+snQu|jef1`WA(>IbZ12x7&J4a<n(L!0OPigySV&vPrg2n%sl%qCS=|-N6
z5BR=4_+Zv~yHlh8pm0f2Fy0zuTpk}_iRHSOvICTB-q%!V!BjiD4ei8;_#xap9_=IB
zI7Ykw>Ny$vq}#^c1lYc4RO<G`kO@^EPs3N+t*u^>4hmP}S{6*o=WvUDPuLLa*i&UZ
z@3wzpH%_>gefh+DpHXo1Tq`N?ZbgklBR4|Mb>u+MeZyu*CRaCP$*uT#OK>leHzNpM
z>yCqWKFHSoS?F4XP+RQT-8>y$77i}?<atH({;z)X>3-ux!`4G+cdkj8!(+>59dZpF
zZSlhP9`BEao8^tQ1NKjiWU(ibHS~EE5fNI2;Y-33+3mG^915_0Wf<q3XmT*=FSI7J
zze6%t&RUGg2QJm>D>#fBFkplZC=HmqZEZVJ`|X=l(OOR|Y`)ULgIx57uU0j(mG=bX
zAWNm8nJYe!mD~cK<_)_>KYcWS`SK8B7CZR~u+ja1bKzi+iGYgBOMFwvVleZIPgSSX
z?roK%q-tJ}oQs1C6P%!={u6l_QB~A`RR6fXV1|w$;AE-@7YF1+*q}fhX^-(GgvDOB
zDdy-1iHH#Q{!?E6G^vmy>6{ghOcxh1RY1oRTC?lR3fai4LwbenT~~>>C(Y&U5(i#I
z1u`}%gQHDefTQeIQXvwTP89UAHgxD+Y){R3SFUDq@A{fIp!HFy-!*6$2^+7SGa%ab
z9}T+{(29Haaunw9FFZdyaiOH?g5vGGOTK`4B<6sm-NC7FVQx4>4VB`NkYaFU<2nX1
z!Zo<bCUzqt{FZqQWgmk0nmWz*=&bXQmA+pNKlf_(x%C>_S+3v(I2T|V*(#m7dC%>W
ztK)-B{zGm@My8vXq55=|6TxO7HP4ZKHpXw-B*HiF=i;7u86Hc3K0tAn(4WiZ^b|WP
z1EtqC9_{?vS<fFgAMO1}+)mS!o}XbZZn|EVi~J9~SoM7lX`b^99={2{o)v!<c#AH(
zCW8lNjLJ$TKNUE=$}~)0f}8dv1Oyh{uI{Ls)>{1W5vVdUf_++?4Ym0W-nHvEWWY4m
zdFt&?7%1+xTvO%;jyN5_?)Z9B44l>b!TZ-e*l)&+7PIZl?>U!dbS+UWV#6dR4TZaR
zF(h4Uq%gsBcI|OA>=9RXIHIW0bp8C}EM%{W=K(udR2;|V1^{7YYcBT6q_(Fw2L_?I
zRP3y*WN=K8naC?ZwB=ru1eJ%ZCP&VgEx|eU5$#m0I7G`Fh(0X-`=DUrIEav^)6#%y
zcq|@CqOq@{rz^MjoVC!Bt)cg;_xGNffWK>lv(A*Yw<Rxe^_Q!c`0jT?m3yecSj7ec
z!MdUkjXCE?CDI@_frnm(-Ov1DFstpn8<(j=*?z=rx3*$!w=!98`_5#sTAeKj@Smn`
zBSO04FOB~<5rN=_PkO@om}=k3un^-V4+?x~L-R0IzRabJydf8GfC=@1O{vtEX&XPK
zc+z96!-DHh9AL}#vM{#7>ALTFfpa^J<ei@TJ=4qS_tw<;y)bkFLm*GT&W5Dx9?0nE
zHXco>_YPHdKKoy>v|s3%I}>sLIY#$n`hPBfkh8~Q<{y=e(Q_T81G&DUIjcPVDib6j
zFFkyP_*$hZu3LZtjlr@(k3c);n*+_kBXNd6z6~=3mV%b(7jUr_<C`4o4kftC22^k)
z4Hs-MWyu*_SDiFb!!w24x*KgXd|vRlbpEx>a%#(&q++Cd8JiEG`|Sa_F>TQgtpT^2
znXf)4Vt%MegG$tU*oCLXqW?aJBWfWSLB(E%xjb${N5d2O77<8?BqmfZeAey`@7zv)
z@BDUGf+&2G6X|cn!JsN?CH3=t1$`ja)+V_Z^$&pbeX2_kCsH9mMuUFW>x$LGWMV)#
ziEiXR>;3_!2BYdGUeL3%h=c4#D1@Z7N)^)mZx*kJwz#^!-IbQ^sNxG83wppWH};Cu
zxuDv+o_B99#u5a@27;ktFTu*acP!$ZQ$a|5?`1J*)nX2i?*E?q;oE0qDHgO#076n@
zW9TuYqCrlc=#q@}dePQ=I?XMM-_QEy&$DDBJhoYIb!~-V?(qQ%|CKLd1x>;3FVs9{
zZW5%(CUkWI*CCfRVE#u{&b%JrW=k8QFXw*8b-vLNngtP&a@9M<Kw7~53Vv2jKLQDS
zSsS7Vu3y1}g~*BycmcI$boGR1&Kq8sZ#T-XaDwQt@yp7gfZ2Mw=<7vOSCry`JpdJn
zGy$Xy;hWvh4x|TX*-Od&m$IYPiQNq(6`c`SglgNvxH|x$74JC<05l)6AXswzm``4i
zZz%AFu39Er$r5GLVzwUvAR2SbQUa2Q$u_HL^8{|%8E06t^cs67*xyQ4Mkra{(Hy%^
z@z<|(oP41nxErLIA)W(k64j$2diT|5&)MM2^()jXPu+U!o!@n2YFp#X@vncYz^Bb&
zI~?~8QEN4~pnD6R#?qF(Yf3DQCFCU5ONBcqo&drfhtMky_fCvF+%i421EA{G=A=#o
zB_=*ncY_y6*bpiJxLZZzFDO^3%{pgQO*={9T{F%fTQv{^6}YZdAb}dVvZyc+H-t*`
zdRh!HvGpzmCWVf|llBDt&c%GNBb$B!MZK~-gX7;RDpFAwaB{;#zM6cXNo+EQYNO-6
z8io=7b2Pb`7QkpVS|WfG3s`W&zCQuEMB36&6MyM@>wiD;32a%;T4`+58JOHuyf8;a
zorj%c<0cahoiQF*<^6DyfasH$)mT>3yuBSSGB8}_DDp0HmABx$kic@w3N0{xIGnxW
zGZxK=t@nNZ`76pqmhcKNe|6JeL4yDMYVU_##srMJ6&?VpT>rbeq1_Wpq*l=|fS~UJ
zFSR_bq@mRi^K-bN?I@bbrnjg%Ve-^3zMgM<)OpiePXMO`tNjkwwM@(2$kC68sYyMz
z;X9TzWm+aXFl^Ik`ajH@Wc%{B#O5~)cwB*miqS7_Qj_3dg>hu#{<(!C9t4Rv{X%-|
zQbcV88DlE?+`r|V47@iT%U1Xl4;5m)&vOs@8lfe0m3pl)V)v)^fJNU;E8{UV%SMcr
zvf6*+RSp2X<*2H?Wyzh<SVE*o4d_EclIpgedNRcVGM(A$yy*xkHv(3UijM&(bY{2p
zKakM&-DPkrJ)#kov1?6G=&_<D4*<PjVq-_smu^=y(&qK_vPZ5vNk!xHb-PqL<28Km
zsYsqYw?P1mK^t`k#-b!U;sH9&qA9`2PcckcghlIx^VhTqn?dG5&qt0{wlcv1{#bUw
z{B+-cb>P3Y$XBcFz=!Cb;uSPEH$osQ9ZS!xC4#e)L0iXovvEGre}7i19nYW?C1`db
zkm>&-?05e50IGN9p1HK1Za!2^4)v*lq00`7;|bBuSsKng)wX7`;QO)ZUYsZ?njQPn
z>hnob!O{K+D?k2YfzkKL>W}NO^?2sDClJ?fh&Ku>ZI9@|(1l@h+X@$mkcRq_4gxwg
zVAIzco4x{=tM>GppQcS4B;`?=bE{~v7}}JhtYFHxRg0>(v2yt?b^)wg4CXb>!6Qkt
zKaTO^KU+yCGNwhuCQ>D2I*h3Dvgy?Q9fXX1J}pHP^&e&zYeZKnCrrQatl!1YA>$u(
zSj^r>I*Xtr{FbG`GRdf=7|O3}6|;3BABZB*8$DUVQT*<D)E4FTqMq$%M!kVnM;eU7
zG3Z@O92UM>#6#R`<9D*8fNTGg(P(VlhgiMOFn4duEB`Z$TmR&5@V`BK>M}p)-KWoP
z*$JBNSzcV4$Ai-CaU{{^3Jnnwf1^ZydAv;6K!hgO3_QT!@6<~M3tZ89J?|&s-#boZ
z_9$p}N6iHxVz8C08;sYVMFk==5ngKMQb8W!gE`fMW&2F49ldvviD2@Bl~@gM?fl3H
zB5*49TLq6DbX*1fAK^q_g(zg(=C&lvB`LRQjI{#hOKBoom_D(mCp6{sm54#l<ndp8
znG{X01qLkrh!UnFlyGIp(KuvGUV8Q}IgjQZ_t~I_v!lhA@o(pMTb@)-B&$Pw##(TL
z1=ni~g(}1p!Dc#58;#$;bl*eJ)cYjzRe_F+1_++&D`yfGoDt#Sa?r)A*MmNZ_QUVl
zZ%l*Tav0b*v`ILlH5?7r$RUZPF*iiEg31@g_tiL(lCHyU)W)kh`Q(g=fl={hW<q(N
zh?h~ZKJ}9fxk3MuVUaz?XD_U=!$e`TYs3HjdL$b7(chH%C8jK{cBdiLs%;sjwQs$!
z^mYSd>VY=JjznJ$K5#tSQ;p`Ia1<pvK4TdHgdcgd*04U1msrS6*`-|rlaXQ8_xz*z
z3-36=U4T$nfiRRta6K`fcKGyD@lboX(-begqJ);t+r*g<B#^>zPaS_0jmbghY<YvB
z<&aGi`d687!?y5otW63T7VFZHjmEIHBoQiFPn&DR2|mZ>$m;10NsGFplzCIPrbvs*
zAr`xOk<h}S4dw{ucQ5aDrm9_})(XQ4wG2~0u}pZaGw4s%#HY=_>;s$pw0@~%UY46a
zE^tkie-7h-o%h?gGdND3Tl1wycNr2u_><ewNd|oVU*}C&1eKat3gGQWQI7S?5AmkD
zGY|BBO?H6MsAhfzw)k&_Nq|x*ubO+@<jo`m$ZGKl1X#b*N2V<>I&3%&c3V<V&s4B$
zT3=gS<;vK+SYbfR3E*VQ5;(R_Ev5&vKM$Z?E-T<7D+rA3pN5G}h?9)*ECez8M1LHG
zg~`v4;W%#45ht*PhuGi}VN}!+N#O>D(SQDe^q5<NkNqCTxFg2B-}NO#U8vt`u5T7{
zfSG*UqN%BU!jCkM0ncV^FjIbm%+-SL5vLlK#sz*uz-ke5z58*kZCigFT{%H>N_z59
z6b2(OG$$l92LT4un;vl4DyUp8s5S6+h!J_}Z~=vJ(7a4i;xD?OJqIl<53_i2_VSmK
zXn43=QU^+y`k!~5OeVXhn0<oS=R#~gchb)f6fcAb5(kq46Cr_S2S%LDgP~*6cAC2p
zW+0&9ZDP}m&9>4o$*}ea=!SmUos_qRjhCnn#s2i~>xtUhX^!aQy+nuv)QcxA3YN|9
z4)OWY|M7lV)PU2AGNzuCKJ7V$E=0UjGhmr=L<1D8HXS^VQ=xvA8}3$0D%Tu7XZFn#
zrH+fMM!!z&^31Fb2J10k<LIoV6`!i#_uK%4tllD~o(E!J7v)Mi`cTF}T(tAbe7L4t
z@S|GDrNpE#F!EkYJ}G#NvP1%eg6lZ1vgnC-0)5}TVua_j7~lDo$_AWiKC}W5TBZWT
zqulg*T^H|(Q-+N%JWlzlZyLaS_{OAzU<5KGH`kxGmaveF{g2URLOP!cn9R($DH{jD
zp;HT>)%{kn<34<D6weER9FzLrxKx5w?by>Y%5B13fA2|@dD==jrpT6IGhh9LLSUFz
z&O9h==JZy7G5;S;Ul|o;*S0;>fOIo--84u@Nq32~ba$t8cbBv@h@f<XbayvHBi-Hb
zT|Vo3`QtCw+Iy~D=W!m9-!R?u<h_4Q1Y)BNM_Qe!ci|Kip<8%ejj580Scb<^M`tYb
zvzX22%Fl}FXE&~!2|+MrUnDW1gwHeVX6|P%Xv}5i&z-V0dw<9Y18dL|LTH;te>Erx
z5X$gPzu&#I&_(&h5-*B??}B(EzlZLKn6ck78NZ&^K%Vf>xrsu)sk>twce?P8Q|`aV
zuav+8`wd)$CwYPx-t*#cce4ZuUgJk2sZ!ewLbp+D?CR?t;jkG_rN|?vHea^Ix`PI*
z6dFt@7btP;e{UP}tz15~xS*n*3M<GAB0)7lpdWCQX5b7KAV%v&9Sv9BgTIQ_Oj|qA
zPfTn%K&dnMO7%!hkep7C9FTChg_*OQe||^7IrYINvc%+0rK^UNB6u%4Vv(Coi~<#u
zeogS-?+6q{cwA=ww83s@oQ3X!;^gwi@eUuEus~Sk<!*=c`km7zpe0~oDViZ`Q0qPS
z2xP-u8a;qcL2LU<_5+2W*e6RIStBu)B}kO#gII`9=(~;=wj89(4t_g2_oa%jb4nPn
zGmalGuayOyk3r*Y&r(!7f={t$+c+Ihk!pwq+e)dSx|AKR%T88GWHwzjaI-cDmf36n
zO?Pim#gXu#GHqF}P_Q-m)n?0u9C)eL;*>CJJUI`P@+YfgD4hRm7u{qY5jgy7bOC~k
z8mX^P;Mt{*bOxLdNRJ-2Y14C-V2>Mlgj&^)qw*C9MwYdy88Yc$?Q+^(`_V#Whih6%
z?7n^xK&Y((6ECRMIcv+2_IsWv_vNp}#Yv?fUE*cLG;K(y$(aX<H~Oh;*{DVPx%>U-
zfY2&Wpp=T-U*u*P?-mr8zgI$a_$3R|I<n+pl)4kKfb3C17P=rv8JPWKq0G1o=wIFZ
zL|G$8-QJO*KUV>QH{g%nq-LaCJi=1xdZ39FOK|jxYuCOW$T)cEc1By}%aq;4ki&;#
zDRKDtF_LagSHg-p1IcC`<J`jk+`?n0Sp%CPp5E@CuiX*vPxsG2uO{v7@Y8*%@QbbS
z4vpv%zG;kIOb7`10aTtU1^H12+ta(Q%302f^6S4_vXw|NhVaR=c+~%NIC`=<gsigf
zn(3(i_a~RyCxTLt-=FxAs=$_QGU#y{u&@}&8SioWmLXBTaCkrH;D@Whsw?|LprB5x
zp?BM1+{A|}16s!p&V5+S-OgYYNRsiC{if2dKgSB6_d^Qe#8chW%_dT$E!wOb_tj?v
zZOWRC9DegJDG(b8*YJTi-lp<|W0DGtZU=l$G(e+|kdyiPS_gbkt6E%dKu#?o0p;TT
zz{APmcAVLd<G>_F%jxfB^NRm^zU~hXIFJwF$|Q3PVDVneQ$_8V`oZ&|UPP|Hz~{X5
z-{CM+3PU=7@X+Vg_s<<Iu<?J0)_vc&Q!Q%f=vk5B;V4?2HE=5JCPLHd@Ee^g)q%yt
zZNj!-XKl0Do^j`&4EaWE!)8>kDehCHfrRU?>7zryYk@|L?SD)ar<LT0h*P6HgqxHX
z>AUUy8R<kd+8dYRiA|G^7eLg1Vv78qoK`!<MXwHE<o_*07b6Hn{!|{nwR6^yEaPc~
z6bwo=8CVvhL`8V6Yd~u**Du|kORC%)+@uE77ak>k{h)HU2$Y3GO-%(iv+a8|LjJqY
zbnWFK(982n9(^&Zf@JMHguWhN5k*8is+MnUO=sZg`uHMrcOX%M4N-UiT}Q+>{aI0o
zm#`)C$cUOwV4<U^$O+sw3{*XBoc0d;oa#($ejtBC4GMrW=7h+ZAk(dBhuG15xHxRk
zdwzX;YT@<11R9n_G)S<#+T!$h4_ssFWVFG9$8&NBtR0se$f2+#&@ciB<VpE2$-8p2
z?<bg|hS+1~?6uy=GyMHHOlNT^G~|^&Pn@lfjB+?dy(5UA^!iT1s6Zz`4kO_!ZWDV%
zVAJI2^$x`)w#7dudQH9v-MLxdCtWd{5I5Ka)%u1gRXugnQ;3&RL?W5gjQxLdQOg#9
zF)nDq&z<9Qmz2K3o*^IDzu_Q!h2V2j+3{W8Q-TnZTX)`@iK6tb$li9A_<rJT;cVlw
z`BP+a8Y3LUE&u|z$Tw=~whVz64bU!cxLxlKV}`eE_$Hi^4BK)$Q6Qi!-+F9AK<u#%
zSfVuKdMq7Tm2YwcD>478!6jzB$Nt2l6sI{I+~C#e95kd!X*H|$Zw806ajS<lk=p$+
zal`+h`k~43f$Dp?dAyAbAmjX3HCsC37Gc=W%g^Ti8~zu1g7a(d94RN}=Ey!)-`h{T
zGkZ+;k@K0~>(3WeB?m(un{Kp8bD!IU`&LqphHw|-!))!BYghmyi)bIpG|T2UVeh*e
znuWx@$QNQKz2)IcM+95}(SSUgZ-T3W(82>PS!uq~IkL8W$+wWT8;AYlk9^ZTmhQL5
z*5=;D19rr>oGqE)uOQI?#}J+`^bXVdI9OivAo$MTqnTgsewLo?<)e8r*_-Zi8TnnH
zlyg=1>-CSeT_cv)Piq?J8v)%rpnZzc4`Civb9!3lFh5PsuRnE50e|0a;&r-)Ts9MY
zD1C>7nkL8V_m{q6ttpPpI1dF&nQn1D0If`EK<1axJG63ym|fS|(sVl8s$*Bi^K9hZ
zZdiYv0<s=prG8J0G|GBNTG(h(DA?f`40;^;3qvrVKSVJkdGdDg_K2Zrpr=^TiLRs!
zKN5K-H!UY78C-iwm2_3*?**HhZL472k?(YHg;&OcID}^nlynl4=SFpb39zuR%D4p$
z`l1_j9u;~);@H4KJaH=OOyA4fx2?;b2c%1)AtD3B&eumm_6F^d(Dl(gvi}-gY3w8o
zzk0yWAY%Bj4sLk@j>HxU+5Op1?$r(L=n5Es!upf5dO$;;p+^&#5+OOYWI=HD_j~LW
z<+N|z>!x{&Vw(w#NN|QZUHB4$p`RHKqkLzc94}9j5@cC6=?=x8e(I8V(j<8_zu=p~
zfRrI!Zd|6Nvnf(}Q;vDFh64OiMFO<N{S;<3GbcMKpoRApU3Xs!c8Kh%+FOHecDVNU
zU|H(s4J*C8zrCIS&;mFE6V^id65_@(NVgfqw`cq@!qKc8-M}t8#n{vS9ZyGlq_>7W
zWfblYL3k$UukUC2;-OS=WI{nP3j!{g0YK3Ezy-Cm)5&gQi8>SMZ%VAGQ|ge7dCEFF
zF^C9~W~!8sK{zgWrv~Lc%>jGR_SfKkSjR!F9=T*m!*6<3(h^X>^z#sC@Wi#c!OzeY
zx9H&&RPgyw1;2!^*lQG80G5^|bBROd6f8DZ?HTwbT)N3j`s>nWD3ojs?hxv2@gV~H
zfKLWxKT}_|ZO~p!v3uxe&V(fw-T_P+EUZ5BPk}~veMYDZ+#I^C>e%;Q^^e^hC_PAb
z6)XK?l@5kxenm-Nis)`nR-qigw_1|Nf1<tH*d_h<zl$WD{o=5x;1k9km553fbRj+L
z=mnfRrtpf4@KG4f1^QjU$RSp;t&hQ~=>ko~PynwY0w$7^)7=XL)@qe!3iYZ7Tgl2W
z<j0Dvl84(dfMAU*?M!R-uQGfYXl?;hRX_SPxd&~+>zA~;XqnUKPZAQiP<0yzgaE9G
zeqw4*fsoK)Yr=&IgDzmKRF?PIWmIjZ9woE4>&anqi}zoae$r6M1&`U{CsR<OMIn&q
z5F5F2A(}T($i)W)hJM9gz?!-Ru4caOktUCmfl3q0AB!iyF<oPmVF$*^diHY??KO&k
z$b&p81Ox;-+mOIe%wU}SqbBZKMa9lBw#hJVfG$9`Q0ugxBFO9bBV_$;wUKS*cUVM(
zJ{2gYiCY)W=YF9>s%?myYL)?3tZsdNsXrGJOPQEC979_!oy}1%)Mrh4b#KkKEue=s
zn1K!dFl^?JL|cgae?{+w)jE%aKSs;HpZVXA>X@^9u6X547;N!GeJL|14A=ADX>x1C
zO}hWrh`#hK8T$$SY~Z?7+G%4E_Xmw~sq+^OEG(`xoX)P+@XRALOLK{Rj^G<-!b0j3
zgzsr1W^9=VSjt|!??r!Mf-4BRFd)av#EYp!5+jV!34nHAFccVr_16jd@#i7JMK_K#
zB5L+u<R2?yRUJBlbmep;mCl%A@!6~WO?8+aEvvLzY1@lA)w{0`3VFRAAp&44z*!{|
zKH!^4*SCOOUjKzLmeE2^PWX|iv?2wD(B{6rWE)9|x)v?Kgh7R>2xcJ(vq&7p@QYdA
zM`@{9Rp3<rwd8LqtkCYtQ61UmrDx)#K%;`MT<oDmQ0#Y({Nc~BiWpMN8FAM+r15jX
z*gJGb7!bz;GkSJb|K^M|JIBZ66X1cN9RH2I5pEOYe^$bEh*ZetmKREXZ^?Pcun-kt
z>AsDhnv7qFKp=-*)MrTjJ1fEq8IFbCNen5=;|l&?oPuVC4HNPL>jGA&?l*}SYK_s&
zlt#twn=Fap899@S3l%Ce<wskTbOFvt+Z<8uy82atP8t>z)d7sH^8@NdZ%bi#i$1_S
z2F0x$#@!6<R-0!2VorwITpnB`j|?-_A5n$*O=}|}LIqH}C8x60<)Kwp=5z+61)5My
zDrHU69CEcXJw;%`YJCDS#fKrB$$_U`m{Y34yrFF~-Z)GSM%=ySz=xgl&P}mo3QeR^
zX!C?k#c|kCXJS-odL9DcG~LxX3|$Q)V}G)^%+a$qwZc>J55g-VOR-%D+fM^d_j4w^
z_rsjJ6DMx2fPI3rRZ+D-V~n96VI|)M;&BRl`Y(h@61~%RqL>shVjejQ{TIr^^;A^L
ztH-AEa9F;I_1|IOp@tGxC6*XRjQW}1BlyArWWT!>9(_kQrkVSgE)bt7zxzcyKzml_
zlj|)xe}YKw4-mZLn>pN_gOhQ_<H%qyn?kD-EJq?9EZ7LLd4$1gY-hz1cu8+p!Q^PU
z9G>v;KSH7Q2DSce#Gzx2@_I1{yxm)NLI9~rK~D`ltgvn2Uyt=9Oe*!TbX`isS}TgJ
z@gO2p&dWXl_1%R`GM;7!>;|&|xwM1DmO_TqAq%JTUP}26XUM~5Z28x^Y0Fun^0)iu
zvng!YpM5t}%rKOwj7K}!YMxg$lC5(F4=U!-Hjd$YJYec16HSl0$?K+@6a-#{OKAB!
zN~Q9;SN&S?k0mnsOM;C{#yjc;8JHs6xptm@tZ9Mj$h3)B-&xg%-E`J#<MzZr5#4UI
z$lG&sH9F)LE!-Rrwu}tkt1-dy<6Vz(SKbR_O)@6$QW8YC9ZX!CANc#zL37qD4_9yr
z`bQQb_VjR8qqGE%=p8t4xX2Hw;XC0jN{MR^58POEBI6@o0k~|?<DX%E5ur;6qk`$u
zxKfTqy-eOw3G8P$W&v{nItsT@Y*AHBbs;|Q*Ev)}*}*8Eq9cGkCXviI(m?rF9Yy?m
zBYFSr=Z*QI%+K)*vGJYX3M7?J>gL93-$+*Z*Dm*e^&n#X$}5kNb2{Su&bsk>vP;<D
zTqIDy79wk!KN{`oymI#1kqn-mW|Q&}ZV<H!Vfb-}t<o7$?yU_bN<HZu(VTd(9&!>O
zUJ}DU8W|ffLl*xi;xI+FBFi%cm=H==b2cttv&ACSYxBDhT@3Uc%OBk~Wscdluqd?s
z$|q&Mr=DEl4=LF@j+=TB+S9@=4(EV)8kx0<%zvX_#$GSu@nT%0G9VFi`f4d{MqhN%
zM{a(;p?(SXL&D1YWWXVhZPp7@AWpkJaN_M0E?MKdJ4K26-zc)UHX*cuPqdk#>O=<q
zK3MUm0t!C_K$dDpnjUO3x9h)T28MrgxIAIC+VXueRmabCH;2h%(-nK4?|p8D60eQe
z!rR@)G@#hasK`mSVX^|Xs`mm;;=U;=ss2xc1hoN}>20;O6GUN(JU>>vfJjuXbLiWp
zqNA~VM5F&Jrp-usWmjUPFMaYi12e<q?($EKI%IcO9giPv`LktzYZtjD%s*Zdg-Lz-
zmF4eS@0urVR)p$Lm3_6qR1W=F?~FI%5?ys-T1x~Y0x=;L#IuKQ{u|ZYJF#9OeNJ3X
zS5-vALkq<*uM^#9^uzG=+{6x(J1`w>_CB#6F{ufq3LB78{pg={w{f^a6jXQsUz%pJ
z6708%SQlvN;$1fUr|UVZ|1#KSa@qfO0-8gG6+i>C%CGlVZ`{z$54~c~X#H;vOEB<M
zO3%*idF~cSKl&a)uLlT~l2oB1Qa&fobEyNk(o$?rhR!-Wjm}5TR}>haMVE8X+Wiy|
z+TnlUM40>1?wM<AWe)SH_6q2jYoo!y{H=lESOTSTPJ)rFVY=z`>N_#m-2L&zXy1gm
zmO&hdw)1oBu&~&C9GKIR+?itjC0Mp~Tsjc`D)P|$uML;knI9J}(`_^y@-*cvbPvaG
z=1pKl+hABHPz!=hxtT>!%xftQB~k14&BQ2}5aRFzP#vm+nhZa+s*G+(H3xp@_*Is3
z%-MmpvGRmb&8B+d_T@1w88$QvZ6Og!ELM(X>lRioc{a6s&N>3)?UjTPwPvwC=uf=j
z`WtTahcS&x)wdcG)BSy(>2K*-L<58Oj$#?Uz!jimWmnZ;%67Myr|(^JdQl`)&JDhi
zp(g*}F{D8xSce`6qQ~1jeeu@R((4*LM<RhrK_oFjw!lAOn)+H@US_1<M_3~xRMMnG
z*j&ezs^jFjJ-A=#Vd!;)QR?<n*}hF`8;_VW%xYy3LFn_VxnmswLZC^WBnHzmc5xJ0
z)Mug&SXk<~(ApyAiZtIc_?K+s+M1d;jMrOg&hB5pBgX+1kAws`I@le=kzwpmhv$&o
z$<?d1?de>FZ@$f$k>|eI<IlN*Nlw(6qM7cmHTI0lbAG<=cm^-vj_h(kav)*J|2V4!
zV-M|JTdiHwL4nAb@vuyAqda2r1g0Y=;+&}FHlibTKTEFa)c?(L_)xB~R7|2p=?D$U
zodCM|Rj=b4EGxX$HFEiXzf+2JEN?Y;fMQ&Q)1&YSt~(W$4tXq?IVY|5KLuPtUER5J
z)kXhu9DH(*jlWd?#|2>7xO>}aJokOqxOlRB9qu#U&m<j1zuVE0!h#f&s_PNgyOViT
zGXKbbZ_cBgWwQ}2JW3UnNR|bj33fQ!?j|1>ms~OMnQT7YFasLcRLgQ^V}?eeCUy@`
z8B7fYMvj$R)D}AFgNr&~9SB6=H-d-S(WSEjP`WY1l~ROAO?ov3>h-u0;;vWznAF3l
zVUq%B3q%&PMNpy4MIj11c5))Og}|^%NMv`4M3a4~fk$@pj$O;DPh8z{A_r@)v^k^f
z`8}|!{h%oOdzVBep@N*n_h_8ZcXj!ZxRQ)zYqt&g@W6ITp26ceFA61hRGfYNqT)wN
z{{p#xD8I((*A~WE%9qqBF(h_OXfmKs+AEPUvC5C?dmwr4zg?ruXK(tW-6PiDW!fLe
z(pzifLm41qGrAzo{D4K(UK|mz|88K49&JuZe-|=x)#NHee)PD~+<7R6j{Kh4$`BP(
zQgM%M5qv~5x-Bj-OZdX|rz5&4HDJ!XM^>!U?k;}WbV<F2sSM5WASwF(u@J>Jx}ITM
zn;!3bWe6D~FRx2MNM$>gk}hQZ>U3SVr)VOLH?sNDLp^x>WtSwCoYfT=y{JMiy!PL4
zT@nH9&T|R;J-@3G=)WGc&}7Mz=6AjR;ciAMy@13e(i8%s;3cnsft%PEya`yAoM#@L
zNx*kB88hHWk{<u4>c3!SeRHT@Zh5iL&)AT8SnUhGe-(E8)QcYdG<Z3$9Ehk2mMP|G
z<!pDr<+C;P^!u22S*OB#Hxlo(m#Gt(+z9OjVvCxwE0{9o3I<mH)C83p(6~4#dtHiq
z&i4Er(bLoIYc}u=@+wO8*_@prX>`vtZeXgmU<?-zkA^^7677Dg$Zmpx{Sb&PiF{Wf
z-1%s|)8e1L!TUTSs1Me}#F`orV3lwxL1%bKU5wdrJi;sp92g+SQkK3x-G6=GNJcoD
zBAOqIv@Jqh7JBf5h4(9Sd=K5k*0Zob!2b8^86bbVbx&`3<4wFQ`8WjH?nPoS`s!Rt
z83WV);Ed(&P)4IpTV%4H2*>-B#B=^SLH?iiX`7Av#auW+-jgGgZu#RtH3iGkhmH<R
z*d#<`UdOMf-sq-AS|kC0fyV7DlPg<4;H3FS5-HfHy^A86Hg)$mgh*>(QU*W6_R6*y
zsPiT2xWL-i^ajMt_ms#D1Wyk0VzJiUI9$`;JZ^3%j|Gz@aU~*?we<A|&ir15hDVM7
zA<Znqk`Gwh=3a3c?<{$qh(Jic^Y}&XDEOB*{P|&v#rbl)zO<`ga|{l^2!Fh%viEo4
zujcqA+?*3D#gef%?1m>DmComei5T~pGRd_?o8W&iYr%=LEy9R#g5-xZVeg2MTtRqH
z6Cts9j~1>p$DqX#Jvu*xh`9gU^4-HGmBdOiVEv%#v4@T23Wj6x(rlr`$)At>8R9I6
zV&TslvzhppR+nr&vya^W0wyRdS2IH*TZv@c#P|(jemYL0l7oyU^weX*Jm%D9!0JLm
zeD>-t+&vo^9GQBwKy-i2vsZQP!7%0gOL*r>Ujvp!ccL$_@X2Z8UKBMxh0o8g!0+zs
z<Prq^FU~(a6qR<z=F?<E)qPV;-+-A!y|+@=R;|B<7Jd}9IDIUdiDg;H^gi2sT6$ti
zge3*wTG(L7j~+9R)Pwm`n&TAvCMg7#Wx4r*j}wz&nOAWDEDbGH{Q-^USA#x4bbM~N
zs)85RiA8B`><TBxR+}8r3|?<P?59HC_r9%U6VKc45uM4mTJi@!%H3_ji&z}aj%)Se
zcdVY@W76Kmi_z4XMXV#8FCkuO>cn9=&i>j{CEjDt{&V$5!08Lg`>lbunGO*vTiz+>
zw7s;8C5Q2ReOboApV?=>2yzkB=$kaPEuECa?t+tHaa5ClXfg^~jN`z%hPQF-{_73w
zNc1+H-u?`)qwP%nvRM%#Lc*@DU%?PE!Z7yE$7Q0^m9}8#=9P@RXfp3)_cFc7LJ37b
zxP#de<twMX%W}I{SJnm%uZy&!E~l6Vg_&O$IrqhfE2PWb3#vK`GOS><@8hV~nQr|U
z{PUC6g$kslD*Ub-q<?6*g(IW>(?9)Pr$Y)uVe`(kD1ZflXgKdDXLl;X&E3;@>(_OL
zqN+blL34d64deGuxgGI7>=+{rM$O#13!w?H`n$5b=2p}?%NQ^)l<*|()O=DhFaxWQ
z=v2km#(AOts211y@#*GntaV&vCBt(RPxfu2>+aSF3lNWHU0DSic`6c{&`Q=?a^O)p
z<)!t#FEYQ|`4scx-!<c$k=ibCU-pO(?$%(c!1jwUgkBC45!HLO+EADiTW@PQ@HuPU
zY>gT}yJW=G=P$R!dpRm}m~71*Xyt|0G0S*+I}xbs`2Pe=1x^|l8k7Ha4OdT;f-xP<
z7O6w7CX<us4<)6R%na*_s?3Y^w6D28kUTf7Uo|HPMeZQj7i<=eo^ePs^mVx0IoS90
zZp@!20#=L5N|WPB=%a1lKAYPTHnNo4)(z1cErF8Auq!rZM8UmIv)V8aXBSxV1<(XA
zMfo621;$0*QkvNF{OShxe)9HEI415}T%%)ZL(7W|Toc`pD_7|Oj?J*|<gDU=l$edw
z!@S`_C#0SzCiC^i^y~8|k2XT28|*E4MtA&cIC<BF{`h`vt;<S>ABKVNR~W`=5wQav
zG%ARRanaSRGF<<0nNewMpuLue*Fw0bGkF6aZT%JXc(Kh{;~3rtcDWetiVQn_?xHE|
zpK+g!-V%KsKU_4@*hopn###(~a#i`G3Rk*LR}@xVHp{mL3p?FFQ51wZWczF04J{-j
zArrA1IbZedFjjOVZ>f%dqCk?LY3#Z`)ogQ&XHA0kYSmX~aF3mXBWPsZC%CVus5j?K
zXNu+VWA=Cz<@pcq#y;02G^@s5gZtRei&G#v7#JhF7d?k(vLSsqCYO;W&kG%a)*Fy@
zCR0}3uYpsP%;K}w<P7e9)PkzD#MuKz6_L^Q=xsR&&eaBKRTlT@34O@7gS(5EOOrc(
zmi&DFbDwW^*Tpf&Mtm15mL|564CJI%osxdXcm`9nFIQ@o<d&->h*eJORw=K(bWosG
z%*IxO!$7iSu-z@eRuCIeVh3#%tVj+y;~(73AwJ^**Ju$>Z!GyTfR3G*Nk*3khhvr1
z%}~{;f}uB<H$P3pE}+|Dhp|KDvsS&agQ;S4&VuDE<woUJyC^Wl`{EJvitt}L(8`Bd
zUp%iSE{{51@%--GJG@`N4%$v*;H&r%Ji~MjlZ9cvXa3ab)^5Nv(vVjllt46H)9_rL
zMxgGrc}HOQ5&tjk8O1=oi9$S*j0L>dVnS+Q+Pl2MF(|7trtgAcG(4<9{ghNJ&rf)P
z6AUTPchgR8*eeXCs%%U)p>MX#rAm~jc<0@&zhPSM+XVj9M#;M+?bY8>N;DPnl~<<f
z#Er0yj~3SOp+-Q?P;oj-?xU;cQx}X{#zxA4K;-3Ck1VVN_Qo$9!{N$&FSk+b3CrOT
zQ)(X~DCFr5Ll%7n3VY}RH5fF8LH)h93s!SAxzr)OlZ*5mAJ3Zieg)Xc0(Gnre%e$?
z!=exrG-*_(_&$%4#?bVUn0YYW7Yh!~gpaeLI7oAWHzsh3^mo$jwqAX=h&H(Y2Q(KO
zWJ-MUN^kkqco3v)YJ4-1tG5()1X@ZLj821OM6a$iFk|%pAYY^?zlZA4)9~=AGvK&A
zpJ`YH&V7%6it9}@ZrG6&R=ug#EETW+SjBiu&{2GVgFxb4-_$4hSeJzRMgsV_7k0eC
zk*#`Rb|}~hIEL<srK8)5Q|b1ShT%*HT6%A%-Fn)|Co>r2PnG=8%tRA2-$d`@SC<S>
zj{V9MLgyOgY5N0&V>=6weBq?;jK5yCe0>Ci6UiwoIV<nfaY&9vj_&t!g(M0qHvewV
z4b=#W^peA`aTC5}9Po(EGVRPGo+e*!^tI;1q)sY72lleO+Zgq>xae10Uu#Wj9&@59
z<f`!TL*Qxu(_Z^%Cx*o17Y;#JgNT)$a4n;ve#I3HWobXc9hj+$a(d-tGDQ6vE&J1r
z?&DRT?NRU#lqK_lF(=aF?6q)lIt(LA&fT$DFaX)!oVmA>EF3OB+FO}z@Mc`o?!#|*
zk%c(r{a8p*WU#ZD5fz4mDL=Wr%dts{qY7bJ3)U{aTf>G;VDVe$<k!hL>Y7=1n6aqU
zYIWO1eedr=xQQS9Dyy7t&qsmzQC(Vt;vIvL_fl*?Rq-2h5xHoDhgtE{!5GSVrBxwX
z3Opr(Zl$NNNN+5My%<wy__|PM{gp=5xuf5}jw~Gx|D;&w!C<;*)=+k_wHf(-FK?J$
z2+q~s2>vJ56?dztbIe|W&zOgCG36rWSni9R&KwD(%{d%)WnXFy)e!NY>)7A_tY1Mg
zl+8$BUv5(b1YpW6;0GKEQ+)f;O+HqQ0NexNJFer!yX*vR2|8NjEqQz)qm8eBGnUE}
zSP``~8xZDfjjx;2Z)F#{Bg<a8yE#80#qh&wjr0}CML3Q$q~dr#D`}JckoDKK-S&=J
z;7(Ei!yc@=Cn!9Jrcc8a+%!aKC||d&w<ue^HitMG?MVkhPT)qyyRmh6Y=gW4q}|E-
zN^NKOwAjXtKtL72CZHW?=diYk1IubVw<>dBf!iHaeeyFcSp`5}+L89nDCEphcGHG{
z1`IrNdYWJ3grB$jOvlV7huXFuqpR0ipRj&N%13~WrcGuuL`1Tr@69hf>l0I~VxOmC
z-})6`>I(MCEi&uT<GJP;Fi><f4%#ts$AIM#clEZoIYYm~7{OR|gd<RV7jV%Rm=BvW
z9$|-rHn4MY$H>30J@92_iQK$UE+Y!|Dq8*;quL*fNr2y~OZjs44yZabH6j9lT4G<q
zFnGJy3x$}{ux>8n;cC$Y3>%krH0Xdx=>OWPZvVB!Ux=jCKgSOV%MQ42Pk?|im|Jr_
zk9jFLF+#Wp(*$-UqUcx<&%!cBjYm!$!g#A-%#be>rC~|lvnU1wcq`wX9>KJwPd25=
zGC1!4#SN3v<_X)@&eH1qS8=c*VR<KK@C`eWKHmcY9qD|Y^i$5kQUU)1AmZJGWJQC2
zDaqVsB(Rt|9iIH_x->rgW}&jyskJ3qvc-33zo0!GTiHf`{|n2J)V?+6r&oO(G|d69
zT_`O{<7b-^laNS;t&Y8(NyS{;lOs7VJ2QLpWn@KA*s)!?!kaH#g9-(K)23nTe}``=
zndmI=U?pz<fn<<`XF6qqKgoVFHgzUx*v@OMS-vRC0J`OY_<{<A!8%7=qiVjUcJJUQ
zroj!En6T$5QY<R`-=!vYnX_It>7&Gl^w8ta#<t=+?l(eZwB<BM$pvFL8wMGrGplS-
zr1b?ObSYouGS$sbM>nGVU%#5PARWr~;85QmbUYA7QTIuV=xJ&87k3DSd(rqIi!A%f
z^)yS20P%N`Z8J~UEJ+btP9%t`h(DDiA2WL0Xkau^DL(aWjlx#=dLm%huh?WX1C73t
z1qK!)`Db|x6_9F9Xt4f~9a6YmWDIVTI$#RQpTt+9zdoq&ZGwxtApjHHZ)@vd!dF9w
zhjmlCC1Yj6zX^#)p+rFL5kEgdyLXMV!Qtu=i561UKz2=ewtX19$6R}@b!xJAX6iZB
zZwVgB)%^?78}1$yA)ev%ZD8*__JR9z@S1p?yuHNh?9AF~>s&f=X3!CS<<E<O!^BGL
z+5_}<&gtG>6b)O3+Of&kykf4%v!IJMnI(}!zD4tZ@!EQo9kJMlBQZwQyyow;KxPa8
zXZEJJ7|_)SA^~_nrBb2@WYMwB<5xv=Y7Cy~g_;yH$+-6YPwPeQe01!R1ycAxgb{U2
z%t<McP7y@X#jvo5$5b<|LHtW6_iwOOiAz*EgMi6&2?ALA*ceffq&GwO<5PEzx$OO8
z4@zXJbS8>etizdll{;0iPk&gT=nquePa-0D^AT(<lby$6a8_q(f=I0~{axbT8~^bx
z`E8dT-S5tfM5ag&eN)-G@xQ<yZ*^}dmog{ed0)P@+s8DCT9XH%y+s$-=1>nPFw;_E
zfY--XuE{B5I&$LzCj^qSdAJsf8EmeNebIfhMlbz90K#!=kpqg;$Z72Yl_BH7-`x#5
zjimh~OSe^>2{fC?d0n*RuIVb+a&4SBmF1^uzzl=x8t!7MY=v|pw2kum-v1ZUIn-#-
zRlN}B-ojWX{^1I3l=Z2qJoYqizH_E2LxxZyag$7&{jW1vb%v6esablfNU<I0ly-bB
z6OdD<&FoTqy~!=AX%jPB9XQ0+z*h2!qh{yR@7-EiP8~ST{N77^)*2frh;v`+|8&N$
z$q$gMs1_Sm124bFL)V$NZ*R;>l!CiN0FClsx010dSG+E5fK{U1Xk^R4pv!+C9k!;_
zhzPG-b!6hR(%Uun(OLOfA~+T|LTL5Bi?loEm*8pzGEFBWn2i&u8OaWcERKwb&iG&R
z>RnO%`>l(YfgwDZNTSsbQMs>~xs(QsKUDm1ofATr-H(9>EP^&_iZkz1u(-!jxHLO=
zyHnfvO74NwO+?A({`5ufAe<t*3nw%{J85$3m*E2NH|k1DWD0bLIyuJRSPq9l3f^YY
z{S<~EdZ4_8DZ(Y1<E!cOIqsN}D^xE3`7c}pK)&?;6HXrB7xu<@P<ak#n4%yiR9&p)
zk@KMn5yfvix+kvO$nNlnx0)!~YrQHSINvGep)Bewtt9WwJR|G6o_eP+i+w{`gj+XN
zm2iCPBXJTz75v1betyF9iN2C;M!mzCG&1p9w9kCdbf@;mUN4%E`K(21D(h&gwQB7s
z&RfEFjj`y9a;5;q7f4p{EzmEgR2>xU^;tkbBNy#aY*v?ei4VkY>Fo`aZGD(&+-R~3
zv%o<E_88K3lDu!dj%Gus``b?L#^Mp(AD|QeIaU$(qT`MH4Y|Rl$8|}7`q07%0vogU
z34tKC|HGT*yT*z~BqC)1>f~1%gz~cM^$t$D``*)Yr0dyk+y=`L*hoomdK@kr3UWZ)
zw>}G5LCPeEzQ^JKa21Z!QG*-C<`!##2k*BI6q1iFxIpXE`dEgmKonrowZBlxQ3LQZ
zi?g`r^R@r0OUw!JncJ6$@56W;s}-<7?{nK!isVx*Q$U})obZS_bJj=h5TDaNN@6H}
z`f^gJ-Mf|cg`#1AC`JKO*IZN<pa6(r0jAjGvaPKP(TC}7fsZ*6-%axRKuIcF_2k)o
zvlqdUDMJH{Hy<bie+9!JOS*--M-K&iUlhMRc8GFM41s|`$4C{z{9Ur9EwICcrKTaE
z`-w7W#zS6#1-r<f6G-#(!ts`pNNDB(8|x$)2D4$xXQrRxFSi0f1d=YGkiZRbtkpjX
zMw={|BeWF7g@a=OC#N}G+~#%!Ck{>Z4wrqg*3{7kHd=u~jh&%2p9D8xKA|THDqi<Q
zb9i2YCaAcza083-6U2nAgDpPtS>hkW>}&b8DP(3KY@>M$S}6uf+BT`Oi_COCqljwy
zjEXg-U};iCWF^lF%h4~l9tOi0m88hI7_z82$PgMbPqgePpHh;`fS2F;CrsI$q}zIW
zolRuYGEcq2t-@KtHzp7tu0)A(W7YqGtR_^~*sOv%^!~DuAdkwvQRHRdCg9frC}%|B
z+@7MS7vOLzI_=MHN{oC->@IRigZYcYk_OPtq-*C$ZlvHE9oD<O%46OEbcAmUC0ytC
zr@D=$q6~>DTZ@UoECBY+qe9ewzfVs#F;T4ffvRBDh;kOvKtoHyiPmsl-?i!$5>e`7
z6|m#-QJ!2NqPm)WF%?Z1>D=R#oosBp%c2!QdEHvgT2tkUJ}!B~Q~-$*sJ}3=0V6(o
zu|jQePct-am-h+u=wKkP%l&n0RU(*~Y_)u=zX%ytSiVfYKw$`9mqci*XKTiOVbT3s
zWJ?tP#u?53zVEDxw*_4Jm3yitGNQzvlL&34>6yhADq5}|j0>9~k8cDqw6jA4CK$RY
z)>tYF_p?={zXw{YnPG6?_Jv-u*%rN-yRijFEKiLDuqnY(hK*rw(u-G8#@>z#p@!$=
zuF=ypramvIKqY%b#v98pC(;e|AuCpB56U;bSP~xbAp40yCMIOiIR`~^WT92|=U}s(
zJwoy!pZ*4dH$>&$LP3aOpOkYN!7Si*Jahud@@M4EK{n>+I8J?a{!uR#h>4iC&W9Le
znDSxKFz-dhLY1|3CqCD;J|M<lY_7kM-B^=i4y6J?OD~c(u^CHC_8P%%Fo40gMH-un
z1-Rb14LX;Po-p6fSmUOpu98hkMHLm(6;sJZV95)s1Xco(z(7Fx+#9nvXpAtOR{~kQ
zZpWb%(H3v|NHOtoTQW+0+0tkdSa5L>k16v+-$jEZA^}4mJGoGBTDxw~GzsEOiE!)*
zVb|=%3zVpAC1whY;V?mgOjy&Fxzg%En%nWlP-one1oTR#i>YHXyyMwj-0_t$?Mh=P
z4+=Nbs>*6CEfu=&qP5H8C{Q<>PY`a^f3NUoL`?53WA~Vl;cLKJ3f|{~han|<LO+G?
z$urzO!Wf#G!dob`ArCk;2q_?utZ0b*+TT1p;rLyDQm^rk5`_R{=y+Ry39S^?6RjUD
z7b_9|Oa>Wvr3PpTtWmh9dj1iIUMv81+ZZYuqUe8vb*k6)kHrGGkG;p77atYW>>O<)
zl;9uj%SwY$@QOyFbebXW^HBqR=(ugCN4~hfpo$u}tbU_Kf@7|HU#!VQRe;vOa=sji
z4K$_}&XTM3H`6JnD2B{ydHt>}XDFig@UGAm<Ov)vmWdi60PL<88;E}$lv0G5CS)MB
z?{dR^Lq~}~iylLxt`7-m@;-q%{385scqtmg_dV;cAJhq&F!%sawrBtnJQw<9bS<;z
za7%k@hkufH^SwA>WD)&<+MchWl@%Uc+~)xyAtZ6NQdBVAAzlSY>W8R0Y(AFejK~+0
zyqu1{)>u{P=%(irK5N$sQ#vBto+9ka=KHQ3F;G!Ku+O+y(Xa&!7S@SAYF(ZM+1jto
z{vFqJy#&|<u!b0aC<t`;h1|Vjb=_^*{7@LfL9mnV?OYn(ZxZ<Nrha1k4B}w9%Hm3-
zd-KK*-0f{F%-Fdsifx;kzq|7dl{Rw9qkRG=CY-eG!NZ3nv#l6pl$62;V4?7CfyP}<
z=HNhNOdCc>sMC7dgG;>L#=tMBUiD|Z{lgT+pn0vGLkBZ_!p%QcfJ6&1aP%tCrdiq4
zEI}fV3@SG^Pu3QpDXR2!IH`4sLuQ6r6KB$-cfTL)_nTX_`%akd^4!w@WPCH@$5vkS
ziLkc(fmH6QBWltQ@wpmW0NnnLZjVeq{pG+H(4a!)I&2RkzrJ;)4hg7RUawtE#9k6Z
z2lml{lm2|L<&hQHStAD<Jvu?vy=DG^lRbB>WFo(B55yFuIaPWoRiscqT-J;83kb8k
zqck`iy}Q~DY3bErWq3aV=={o$2b&G03fr^<^MW>bMM|IV;!JwRntu8Cjnn`Ub5-*t
zoPzIls`7KzXFuix1)hl0kHyO-pQ&J#nm%P{x;<Ct`Cm45e1JQ$Yo;q9djDUj?Kc*F
zIH>)qFGDPbxXjY7i{+7v5UY-D+b~n+mEltPSs+1QY3X)ddqrDJv@JVg^)_z%dZjAu
z5rxKiRl}?gf-h~Fop(1cdO26vz@_GQhnyE9OZueY2Lw(jT4^1!Ju^E9sJm4&T&g@U
zqop?8zYeLKZ$aHL-*Hwa2$u+>2OFZX-crCOhH2fTP-<}x7Cz4>G!>ow0xO~{gjVB`
z2w$}TD`vt*5E+QvFt}&i>Sm0jVP9_InF7!wU*01_F;dyUNYvcSkpSfhXbF=$2@>=}
zLPW28F~jNl6QbFXP(iVO;)P$g?F8C^h5=yDy@cG;!=+|J)=lvsi%sMRdq4Ab%bGxL
zFNjs2Qo2{ULH_!}3Nf8Bsqr*?OYST`8jIJ-Fc4L;>3z?04(D_6TAbd-19i&=`j!J2
zcx<{~4YgpGA!@&|P6f)0+NWBKOhPxY<FY)9PCBl9$=xdjZ9R1x5~Lf_R~6>8y*zAw
z?y!qRX(r`Er>uhrK|(M4sy^P^+KhXZU$l!6S-m`;9o|OXz7IcGkX3H%`Fj=}um_TN
zUvN~@hCuPa$YK&>cL8{?#eVm2f02g_f@8HwKiv7RUN+UI5Fv|~2dgX>)psqc9GxI2
zwB5ZAlll;uOAe~=b3$;hSaI+gZ7Xe5();X33=g8OtZPSPf%Z?;76Z`;%hT2)CO*PJ
znHR<gp><41+KN*lq9K51S-YCd^Ye{%0EN`|^IzN2iL5klB=f@?Q^BPPib3?(_*ifz
zNl)xT%`XjxANB~^Z9QYyxt&ALPP>592?O{}7hQOe)oj5Nng9k1(kmnM*t5?FDwQQq
zFzWN-$AmU7=<NN5PM*zh^;8ArNFW@1HnU6u4lMyiSYAVvCRh&$jCH{7e|pl!UIyq)
zHbz&sAF*y)>u<P1l#vGF))i32Vx8;x?Q{SFJHW<_7Gmer?zR!;i)QtI(lR!CKf$u~
z@^*%C-t!Wfk^xT%V#VopqAsi0CA1YKz3Dp>?g0!ZiP5pI(-WN{gQfoq+Kt3rZfK~B
zQUn^+ziq}eiXCXTwRpV?LUeCiERu0y#SsuIvmxD~Qdpl*NS<ls$Z{tnTGBcftHPhF
zDP>^Ptg*~@i3KxcharYm?SbCw>eYX6L6a;WE`N;SAxkoeP#fn-R;nn6=-e?4nla;E
z>0m5C-~_U=dxn?g5N)I-CU8KsEQZT4rqQEn+}s>Gyr5H5%_>PD3+ipz*^LmK=>Ova
z5Ch+qw%~q#_()U7VBmgV^SGl~Sk;?7iTd9i)C>F)RX~zq*2~2a%LlEx?bjRr`wfRR
z=@OEr&^6>b4>`HuX(dvdBQ3Cw(ql}QGyp6B8^obS563Gm8TJW7R{mI4h`;wAZ{Qg*
zml_#Lj!E>MkJq{CTnuQ~Gk@B+9<o}ggB=~4U@!WhEXM7ofMr;PFm?K0NY`s5>hHyU
zg3mEt>C2gYMMpN8EO+D9e~OwxJnz$#ORv}b=G<afN=jOY+PjO0ZPH1u*wmdVSuU8R
zq>(x?ICs;C=+nr1s$yklxf(#X%fy6CTbLjzmS9hsDj|`0W6E>p8C<LzRuj<N?!23B
zp;X<+ks6~Gbig_VS2E%mQ|?B8Jt5*7uolRGBI5s-x^N;uq!YO5e#+D5BGUzMM6XLk
zFC%8wF=|qitl!O7|15;Sg9QR;RU>acSZTr!KcHXo_dIffw=3oTq70!g1NLWQ#p@f7
zp`~_j<(R-3Vxf=>Jh#JVotsg|vjB=!!^OswxVbE)T!2-zc0z<3`9LbKQ&WUZ<A`9=
zpZl)twWZVxPa=^ocW!U-+?+n4Pan7h(pP2n%wqyEx0c?(pow`OCT!P4x&Yfup8Sx`
z1WwI`V3)hFMA04#Zj=Jiyf5A`StL7DkL~jB!>8|&R&2py|FY<~eac2zyDJCQ55Gq|
z0;X+V$wz!1SH%uSKI<OFW?`Zc7_Wf;_Ss=}@9;6a6(KINP(de<U{%{^Psf7tXAJ4c
zyjx_G;B6CS<;jh*n!{>Ou27u!w*Os|eGQzFUt8dWpD+4V{BGmTU4z|r@1`+Oj}$YH
zbPpxbRoB(TSl9E==|wz7ZYrT;*%hQWIz4J)xs%ORRUNyx@Cn*{HiKABS>#~MnoYh}
zc1UFF<nGR9X6FS?V7A7^jd>UeIAbd_!l&EQSl2RgOSRv+`HI&916OQ*hO9qsR-39Z
zVePqtFJ8Q>&n@vqgI~TBhysWcnHq_k<1M1FL_@;oveEjYFVByaukUQ4Uz)>9F~J#G
z@s5H6b*3%J0G-(H?u+iz7ST7k1Rbrri>tRgRp!wOIyI`3bj)<VKjesUq#g~{tPCSA
zpYH#rkpm^XLraX0P`Fq{n?^AZYXTv+0N(3Z%2B{MUmQ>1bV1apvKRwXRUt@^!!slZ
zkdJ5BV6m2oHMu~);jX`PfCcMa39wE^hle@v)6&?uIhMc5E7$}NM5C!40mg{1+(8T+
z4<um&1Nuk+G77|?LHQ%+`pjmTNT_Lv{sSmm?A||XJZ{FY0o3JP{}a#YR&d8F8mzEP
z*{FRLv#ss8J(%e+SKCDw(c$fw6gSEfn4C71+57R7i>r=j+#Rl;$A@@v+d$<m%`PAW
z*vB+>G>1l$>s#`pZH?#-bh&K_>!#_D|9b^~Mh^TXxMbH>x($RJpKfk{MWzEXRj`Q+
zC1G&v{?jifG_*^AWif1mL|F!eBz8CQIEaydi~?$|!Oui<ats1lrJJv|pz;S01#G~I
z5)5?`jt*E$V8>J-=4?H<FT-<|DFuBlE@HYL_+FGDofk8bBz!rF6-sbEH=CY553kKI
zvLE=6as!uBSWGWY4O+vy9kKjaGV&r28woBN{cmW3z#973QQeL(bnCn@JlnL|707tw
z|CVWoA8X>}VJx_gJ=2Xl^VghpWL7Rv8hjtIIO&CBA-Vy-_w~Xu@b!V2yLr|1H3i*&
zU-hRd_yGaop~Yy4tmum3p-I4T*5OHpLBlZ7(!B};9V+w#_dEypoFkIO+LWb*8rdzB
z%jdAt8ASf$_miHj{6WKBV*#tuZ-a)!0PwEEChxF9voa}&;7P0wVB%~x>)qub*)sNh
zwNbdQ_tEQ{yM0HIDNA<k4n3CUwTqttvV+GR>zX)iE}#h{PO|`P2Y0Co5)Mwh`u@)T
z7uU*%hE*#{q~Tf~^zY7@PgTcZs@1=%ZXh%Mf!iUzWXV}oSC_0w3e2(O!+hF;<7?qn
z)AIw3gs4A8&_jQ}N-_WyMnt%Ap#*epFjH&m1BOVTDG&#Us69UHO!&z{w2HlfHl&Y`
zreM$1Ib%^2UvVi8Zs7`e26Ix}YaiE$4RtL6=gbJro$BoH|27j=^aqrGGw281@Ts1i
z(c(POozLgKff}+`+MHgKfQy8@5>+NF?G>PM#N~Vps`fRBOcV5W2OG4$5e88#u_P7H
zcTZ~vY*O;vS}%o$BHRl#mQVuNNr<)JvJ=tOgS1Q2`Gu!$ha;NyoqycjpK2#4d7#7c
zAdu}M!Sc}GNufV52|{9nh~oEycB~`#F-lkX0{+d>%AqixX3{wmi|UXZ*e?Y`FIriC
zrSKyP+@E^<Uq(8@4ai$%1!vw&vT$dve_3VuopD8kTngFPokKf1Vk(6{nLi;dH|w&8
zCpl!vaOw=HmZC5<`BS&8|5>$2G}8*e+}N!LAff|rPJ;m`)MJOp#PR6zbJp8A%IHd_
zY`Zb3+6=n7D;S&Th%xw~B%sFF%K}(iDX}7-;rbvhGys8gt|Jg%4(2EYQx1;F28N84
zd-D8CW2q#7|9oMz6s}ET4_j)81j~p8;-7rQ@v8bXwK>EJ2u9kpJFg?f7<U@+Os80J
z{8u<k!yosa_%C*4vplv<jdw!*Lj3O)2^^mu0SLxTtz)Io4zeyBS6CeX1HZYYy(UMl
zS@9vizyD8>$K4l9@MwV;ob{dl!cRnlQbA3cf(m*KC~;L(0n)mkFI?{1sVXxobFo?}
zTDBZP$IlP<zZ-aVr`qnX7u(JV3QTXdURKxjU!_uDPNh5R;Qsc_uX`8<NMk9*lGd$z
zcVv?@`Z#$OLFYWMo|cA=X5E*Qg!PD14kzzs=e68!UaB&My?u6@-(o!3`Zg90k%BSf
zj(T4+t2U{xlg7GNNPYeCuRU-0%@P{gYz$fzUzsPnL6cA)%A+b6ESJETDI@7e6m5iv
z%({UZ&KOzY=5RBZI69}>Y^<1=#*P9R5N0Zx6;0Z5ezq-<3L_*@_s^2sdpO~h=ewn*
z96m?UjC)ogya!B<7wPzU*NF6%UyE^p*rZMU&~zT2-RAXiP%6vCqvBd`d(YGN*KEv!
z2Zz^{j?yxX^M$utVIxmpK&;=KgN9esv8-5E?~oaE(8={){#kG{WYW$r3~d@aUC0xX
zq`GbQX2;YIPwIsqqFEV&Bn~%W=POi%tFEpN6Vc02=VJhGB42hHdz<T{$Y1iQ)Z1}e
z9?IH5^Dg4FXyF5xt$h0Xk7s1dlpJ3B$1TzYaYPU|q4H^OTN6V0;jdy=?tYO{ByBLJ
zI`^E5opRt<aAOS2R}jSsU!N!VhdUZ%=Fh~pQ%GTeZFPA@UD<Uz3|yyW1noqZ`P+Lu
z?JkPL4A6g{`b%ZXRr>k>=sq-l;@{Qw<iqz{%mb$!gA>So$j;zb725h57R#O>)-`zD
zh?}U+Uz+nJykh%a^dl@5KnE~gzR!_gO!R|Y-lwzNao;Dxz`R@7*L>6EqA-c8<c|xO
zzChe=9I@V>PgM~gAd`d&F)R~KMDfj@#{0)+e$F92BD&`W^_QP<=*)6$48=-2={cCz
z&}ZJS!dq<#=f*_x%{(q#bkL1VPx8I2D~M2^;+f^d9u+;?)nARq@FmA;A||j!TrGY1
zTWmlMnuK94G+Ev54#~D6fFPLQO2k~K77-;#6~B$E0)}5@()o785Y2;yA&~aI=ER3W
zxCoE5wejDkoH6exC63CP#X=IggRl-7(71)%Tj`Rc4ii*dcN=GfD0JcpAtw&4b<_4X
zM4j~H5mU_H#9&l@ya}*@LZa^c*ePSCO3F0=_mD_m<c?GEOz!>#Gz#NJ4dC%*NNjR<
zf(cGwe^Tw2P*P6VTD+gZfsvb|Se=I^6XS@w7x>$Qu;xtkw!70~tLGKIUZ}NlM}YXa
z<Ba4XPn;^&KiZALL1pR19&VcZh)501t08r@)h#B=nu_4SnK^6FwWof?qPn<83v!PM
z?^U6bX)W})6**9TK3M*o(n^Bct+@BXne-t?Kkju#J5L?za|wk!m=@6KiSbs0nP4c+
z@nY6q4efNhhr445EjP`gF=aYxO=F0kQdmQ3vFPDCZ**H<_Rb8yPFTjcr0;&9SA1O^
z?nZvyetS3rGU5aHaakv+RO!1@haAi<ILvI-Y}hgIxg`*RxQ}}n+SC)#sM{Qb3|+AF
z1c_8b!Z>^$=KC1gxAtJisdGGg!IF)?U$NYh47tkD$i_wufrlQ)?vIJv!@s@uCCCRb
z%7pw;@RqI^_E}a>JB^H5RQ-1uYY+8N+6`%Sa;z`8>;dXybVf0!qxw2xUW@y99lC+1
zeIJRpDb9%x=DI-nXVll?ni<!0)ZC>3QB)FLv}XvEMy7Ob2r*ZvGG|0=+KsJ<Uy|1Z
z>5D|T7h20VJng;URA3Y0;P%Uf3zI*m&i?E~LSf`&oA`|E%9NyvX$_w*Rcqr2=p7AS
zFI;r*_diKMWv(7M4)C^OGC*QtHdBeO$yM2!X#tq93fvfV?D>s$?BK7tq}I*ACs?+6
zlN(t@!d1+u+fr<|VSz#%SA}BlU#N@z%bUsN#Z`ZQTdj<gjy}h5ikHHGDq6RcyNnJ;
z;5Q0|UN{pcF*4wE$C3j)T{anio2XcBI{_(K5uXlHb;NUuF6m!UzFaU;(XlY+b+SBe
z0ZCQ5yy}mx9FCYg|Bt7yjH;^bx<2%w58d63fPi#^h_rxoceivLQc_9j2Jz61v~)Mp
zDcvdgZSQBi-~Pd1@P}*ftJa!pt~vX3$y({gnd+(s28qdp*h_TMnV{&xo?8>)i$5w8
z`8H@ht!s9qJZYz^ovBSZx%v9!CiXh7=_#7hy}h!lc+P%a5y2DFsbL?b8Hh2>o+nyC
zF>xwov1oX!maiU0;c*%NTy|QM)!QQNSCXVwx%!%l4u|cCrklKPRW{wye?`2}Icy%Z
zQ2TL-h*@B6oTd<cX|&UGv9%bAU$vChfyjSyuG5c7)UexChu7Kmp3yQ3gFeJ(AyF(l
znI!tRVRbI;bfVB(C;GXW{NTNX$7YLOJ3G?a$+;tim*uz)YnHEU`B}#M$2_z|hf&i}
zlREJKG@UcO5AoT{<x_mF5$GUtxXFshCY|p*RCmH%y>G3=W!jTeevJG^;k}Cpy!9&m
zU<Yx)I8YY~?~eeQ!KAB>9F-J{%>oAHiAl+qQ)T;>?(`K&bkrpjs4-q!QjME>{u$#`
zSpyt7XGj)_mvdkae;56|55>fuNBf&T{Y73I1)>AsNdgz)n=)c83W_O;gF}F>u-bVR
zJoWW~eL6w+3)RN*DS@P#s+Mn|uO#pn$=EuqsbiI5){k@A5P-WK=`EWs+2iBOUosgJ
z6x!l478;-x?{|dg^f^!T6&?&TMa%!k50tazSiz6t6V4Q<H2hjK;nzsiy&q<QVR5J|
z6=(i9B~UXz^DYZc|J#TDo3Bp2$>m%~?9&S!0PF6XVgmRz@K{5Df}bwi0P#ZuiNpH5
za6)o=q!2(?U~#Rb9D6*&01~~G3PqzyQeZ=!YAdePd-=dSJ>FpyCLaZu*c79e-06>Z
zCC+0NaBJ>)eo!x}mux#Xz<2GjlHmc=@oL%0<cmw-5R%vke*Az*dC*dDiq`%lH2z~k
zph#veimph)UWuY(fSs4Kjg5^EHZFcgzPtJY*-5_UoCo~o|2@bb7S7Z@auf)vhgjFF
zR8Jxw4wtLyQ!DbR5?d#Jnes+0Srh*E!Hjyf^0}4FsZ8=6g}wRW@hXqQ6zpDH556mn
z^$a#Dce;GVOq=R6K5@yH1!NfNdp*d>7h0)6fQ-YzJ*nebTWI)Nu;@2bfGzOnu<4;{
z@v5ogxkFsW;#}S828ZE)6l(*R7N@i<&V_U@Q#uDm48ID{siBFVr&W=wX7(@r2J%k)
zBhfk(ra)&jp02msL$*k%V$B$%PtdY>RF<<LJ83~@`uXGUs?j&(%U`_{fZi4_CtJ;7
zKV+awlt^^`XR5lXxi_(VN&Naj<2-Pz8Mf^q1&^=0|M%}{4=@TaNoPq(uZ7rcfD$qr
zrp;S0n7N2w3kx#YX_713z5FAhz$%`J)cn=0G1mO}T9B5~Ta~9_S46`=FT?^oL!b=k
zZ|Og~e&T>hQ1ePrW`zN2%+Kf(9Mrit05<f!<~vz#{j69&b<7H6fBzme0c(V!4)n))
zoZYKP<g6o4B;;5#y{Kf1m@c46%lZ1U9H1t&rwr<P@2d0zXsiPO(%s~B!N`CnnEX}h
zLWw*+M4AO?F;Q}~G|;q9T$66!Sk80S1paSo|NZcR<JG+?Wmavv_$#23t#<-cZaoVH
zkJe+U;<|^O)uT5*cZ0nu#iW`8a+f}kD5$&2icNZ2d`9wqgH2;*yw3m#@_yaI)2aC3
z*~*H*awV<b=8S^vR2}%g9SHnf>Hh}?aL6}Z4a)Md?l@|PS<Ck^@(MnjaI*_Hzcn}s
z6ubL=_+h!-4@Huhns=pQbRF<_IL&)SF7%9cL%BK+G|*mi&>*>niOkKl7~mbe20Dm(
z=rHOOblP<Li`<O1?o+iPQ0bu8lmGv-;o!WQ$e$k>=Xc(DWL25~&68<}3p)!&Xpf~N
zn0sEgYM)B500qXHzw+qb-j_Hr{6X%m23f%g!@`2zKO)NtWX;|Dj`0{I8Jj+kV-nIV
zgs3bYJ2`Gn$s0L50*sgcy<2M>6FzieS@BDx50;g_5A;>%3Yo=nyA~YC`76?a)ie{D
zU_eWn&L_a){&L@9xx<AE0B(GNSJ&}N@N3q!TkbfAysLdTNYsx0mgQA7S7;fX>`~T`
zv~xKmU#5)vz>}a<{)64DqqfO9@n|C7|8~I2cY3mgUD&!L*qKN>|0SpG!SBmq%PI1U
z=x*`YR|HFB5^6~ZhUph(<gossI{J4tPcvq|q4V_*rY{Mw#YLhA)AELfq1Ap*7*#}n
zd<e|=9W8@e)Y}pINC_EQOh&Jk^GyFq1PC><n-liQ@yY&k!1n>#VBy{D{q_y$+Fy!;
z*FZuC7hHKZ$2P3fegJS&WW3mo_^KX^U)5i9bN{jv4<yj$8Y$6YtRHu!j}zg8QcD~F
zCdWNJWsNEYADxQz&Vs&#cYZa>l(rZ+02bT*7cJ6Q9|Vaa0Lr7pgTir+8^K{9BNs-o
z0sNAG53+`G_`)eW94#Uu=mtBgv>#}7r|C%$d^~?RpK~%)sb8*7203;7jIj)@_MV|)
zXKTwG8?{B?5`Vz8Ew7&$D!hq}S!%l7z!7{C#YVKOIc(Tc6XSN8C0*FWpri{0*+(?b
zM%Ccni^0!F7_;N~%MgcK^JNUAx&p^;ph+QsEKPRuV&WBBNaoJ|L6fpfD>%UkIo8Pk
zfeJFSL_j%`-8P55#-hMeiw7`c_%K%-760Su0iw$?WL<r+wO^A0TDin#lJ1|A!w4Qv
zey6TCk6cZ?7rrHMSzqNbAJS7{E^;}4`rLE@$D0h9^z4CoTblt<>lZRm@q2*e1Y8ig
zu^92jmbNHpe?_Pf^&6vxFSWTl>iUvLXI!M<QwV6y)wS}KK41``WXTGKe6^C9St7Q^
zF|%A_7yFxBV!TVvH#ha$?ITN=nUj{wxjkL-MdbZxa&7AQeWjr^ehtkmM+%+GsdNu<
zhPyh~l7qM4^_UHx-BEJGa2<OobBHN2B)?)((IrgOff+1yCkZ0+1TIeP|H^ZGrHG7u
zea`dGp^(iUW2^p#SDGXtpZ>6q8Q|En{nG>C=9`f*`w&d0TSr2}S2(jia5D!6)oLY6
z63WzZa8GP{B0Aqq(s{4%M>yJ!tg$qbY`{{rs~Sc=+&7wi#2GSs-Si$kwiwg8f}Dch
zDlWTkGIh;DzWH;woc;2{9{0uHtHvCi=9XyQ(<}?f`wY2axoQARS31h<Q+YXw0I<9R
z+O^BvBzS?nJTe>Ds}62#*k3<oGCe4;fkWjL5ej<f7CNlf9QrN1PBW!*Nt<f+XrmWQ
zbL~;f)XJIwHaDgth14s0KF`H+!Nc9W&L0uSHL}qB?MD(E2W*VGg`lr)XLs7!-6QS4
zHHQs;{tWRlyu`W7G>!oVuf!H&VmtF4i!YSpK6{SzwEc>Itlg^tI76+MSqr^%-jE4n
zpLBPjV3}I`A%Z4;xQ!yJ3D{ureIHSfYix17MyudtcW)(qdh0?BbU;~8i~zy8Xa7<0
zQcZezaO+KqD(g2vm*PGo;Utz})vDvFrP*AELRy2E49t;;B1dhDrH$##$Ob%QUB6#v
z+hEF<DGg?==(ClKf<Ns2(NBNXi(>S}yr$`kK+gAVyn=sk7-UR2k6CXy;HYzML6|eP
zZ!Gs$8C^f27c*>;$q0}GZVs#7&mTtIaNF(Jmwx%j$D7$7-0Y7b1x=}nHL#Z$OWXNB
zvE5{djggCn-jgyhZGmaHUkOC5c%61F2WKT%+KoQeV^Di?qL?U9FZ{sh<ii*73JtC6
z%yQQ*OiIYWa5vb(cY~obM)4mM*2`HGhM>Rd-?<p;JH<#m({F@*m2+Wk57lQTs>tGg
z)^8-Iotqb0_6ulxR;ft%%)w(c*yAAzozy}Jc6@n5;ClYPUy22LI!WRi`onyO@KV$`
zoykW=S0og*2}|ShrW=pt6W?iW2Ru))06j31)r#}8aO<ffEfQL?)R9Rs2jnh8gqgab
z?kOq>_Q0lGt*$HnSs`GJ;rmyKcKsL*z+0XgO?sKXS%%C5cRn5ul7H>p<my2QY}@c)
zZj9=>pE12VMTZtz;lowz=ryrFymis3yM_e&<2q23rU8joAj{djbkZ-=J2d}>Y%lzL
zTXV_pC!R&1VAAxv9$<sXJX!j=lM7qz>N*S(tAj`0?@U^U->vfyF{*lEXh;qm^9njh
z_uxtt!kva2VtT|Oa@)4(L@LHmIB9?o-dp4||0bf(Uj^=6vX~R%-t1N{ljlbivS<Ij
zUhxGEo6SR`N1o{3IZ*AA`?>bZZD8M^fQr;-sf#Ek_z6-JE_}Z<E$D2rNRsJynBx$E
zt20>!_M#nTjEYK+5;qPA6l+T%{uB||vuRNQf1Fa5HGOvxc+bj8x3gfT(w0h1EcbT%
zGc2mJi0z%=c^@kDSlJsZ&96FWCF0f?Xar<-;7L3c@GrH#{C&ucao)NcfIu^)VpLft
z=V8Hc({xUu!Azfqu@YU|Ki*HNK}pdyvEa<OTdBQ;a>`2AlO|fl`}MMty#n6bYT9g7
zG=RK!?OEjO<^0^w1vA>BS7O3Q)6v+f4ymW%pzj%!c;PsH;!60C3C{6Li1&GpqysG4
zk4B8Tz(ALUPirf5t|GHFMCw(>==&5-qgYW(b60pbk`)B)F{3C^OA8Z{`ki{EvC}zH
zL6-x6FdUdhFF1@UYOl%xCFg#m#Q68V5du)LHhMa1%)m<Wd5<k`6o_saLVfNTCZ<~6
zD~>XrBZ$eAI(BNLxAK?`sIlcg(-Z|)Pfp565(<1Hc5(jHB~9!~CNLD<-f*AS-+%Mo
zTIp>pPMJx5{c~O(5+_?QDX*MYCce+p=7!Z87AzRu1Zj&AVK1`u_SFPDjG(2~*9t(o
zW1PRv1_q}ZTa?ZX2qPuEW5^Ws$9n01xe44HD!PL+S%gkh9Ycz0BI@gx?-k7s>Nd_z
zmY>dOe%_sO+52Qp!AmI;YdvmRY;1mbygO|l=Q~=VMWlQ<Vmg~i%~4J&%Dv`2?>88>
zbh+8H(HHdCA3Ip+FQln98^`!(Prtvy3qftLi_%QWwPRf8_lq2zGPF;e65^jg0OcZ$
zAdUyYCQ!$?WNNG?QpR$eNkVK&#Jf=IkSVwBvg3VtGj?rZBpp%)Y!V81;pxv_)aH-3
zmG$9hwWudkd5Z4XGQlBQ``8x;3N+E1fdT~Kk=^zwBlM`5cv9xL<{;|HIW09}n&>Yg
zTuVei*%%WB2Xngo$lN)&lQ`UKm20E@WgCl>^!<F;*RGb=Yuc))Hxk$)RN;xrLGD_&
zyf{TF5^lZhI4d~Pih`aGaMKM8Ch71rUY@xz(8OS7T<(!o|7ntmw6COiRD(Y^z_B5D
zE<8!r&fOga%LC9qR_zR<12VY`KQIWt0L2=cbp(#g%+A$TPuiS|@BKzkn*w)%&y^j}
z-M&hnLUUK;pzwWaj0M5{x-x_5rc*rmb^htrY;nO)aO2NC*rw_k8d`u}Nc$sGN4)>-
zkxJVUH~8$vX|+#Rt~{!-^+Exu^<*`+?e?U@<TEM|3@(C89HJUfG?>A8&Jh`eIFmus
zx^(KtC?Dk%=|Tmq@(=S>X~FM_EuG@b7Ns1B&0S&<j4Sh;wSanUBkn#F46j`PFMh~@
z8}dma(%P4JPvY~&tKb#i_X>1vGef#|k56mQ2-y#VT<UCJb)hrdg;HQgs;RdCS2*ZN
zekv<Q{C<((@#aB17|o~FZR*sMayi!O`RZ2f`!6Sg8iL)p9F@9Fp9J7Q{2eL`+{yt;
zBg)k!0G&7qq8)^DEe3c(-0&#7^wQw0<N=Z(H7(JJc{dFq`en#x2x6hk!nz11#-Qd^
zvf+_oh}XvtnvQtpF7G8l513)-iND}^<*YcTaA%pHINqbkmNJkI$@E5!|4@{fd5=J1
z4bXH)IHRIi;0nn#ysr;vIk^XD$>tmQ3gQyfH&^4=K2!Kws<UaZttT60cKKEsC}#%b
zOwkqoViJErq<mRsqWR)TP=ka~bEo>LE~M@DsArY#VWTkf4Un%}Q&%BK%v@qHE2Uv(
z9(c+|mSS7$XLp2%3VTULZsT=P={ri*j!GaXpcyx|h0vtiuQliH3H=`zfSj!JN1p0u
zdVOR)bJmPeb`<$i;Ig(zijn1PWysIwcMc|OpsU&qlBrG_{XBL{Vv?H7{UtL0swRHo
z_;*|^O12M#4v(%ZndBaA{AHb<Gt*EJrleS*%DI^?{@4Gg-PZ|-%x<BOv=w1!o7cFp
z?XFHEU`i=d2XmQ%mfogIbrE6!Qs3?}YKTRzWBB1YXgUAnVS&3>$x=DNRCIE+u$*d8
z3|j1GQsbf7BWUynoR<_r6LFF%pNLX=y(3`gv)6#kI+4%AUTu{FHSuU=tRrZ*qlsR)
z8`jO!@08B*Ar5n;sply#=M1=6+0rqvFVtdWXnd$>yBo?83pH(?IsT3T-KZv~^l?S@
zthg0guX{S@P>>0g1GuK8yDS_{wqGOFi<04SEjKlFdEp2>WY#mz^m&gFe|!DHC$-EV
zz_muwE6h2}aIE`ru~O09P(tmzOxB;A3;m)NHh1l)U1o=o*NIsZ=`$^Xs0#!jwHn5*
zC<Wj~Ub$dPC;NUuO7Bg$G%cU_a5f^_yWS4U(D}VKQH+NyJ`9nkWR;Cc74f-6!E~Yg
ztgB*~<1fX*fRj|?WY8wixIzm0_O($)lnWX>%RGN<3sGB}0Bj>o?9KTmCue;knN8Os
zYf4_L!ggqUn73-+A*jKgwuNvq#=^qy(BRqZ$%>@xj2VVZKETCIA|mrG8~6RlV~y7N
z@Uvoy7SW5f$o<McH_Qg!7h5rj)m{+dVClF<jwR|z%+vdJleeGnJR?v%ig}x?e43Sx
zK;&}GAG6l?4?z2-RZL96-I=7pXO;cI0qgW?wjjZ|765|QnTI6g3aBjSXNLTl%#Jg-
z=rDNKu|If<0lCfxep$yz2WiYn;I`Ft^)fc}*?~SCvZV-SQ294EhL2Oa5-f1eE6hcO
z#&>DeMCX=nxD}Q|&wOBOPa|f6wrSP@i89)%-CU?e%|_LV4dz|IsSNrp9u4Bj{er=Q
z|84da+H9v?$1{+U-AVdbsGGK8o%GGW^gDGA3YVp}d0RN&{$fk|oVNJ-^JgL;ou}>O
zey=GPUhV3EszzL6CL#0m8IMV3Nh%l9`71B2;yajOf0V|l+3m72{sj_17OsPLXS>t4
zi!I*W90>!n*^T5XX3Ytowko{S$9m_0r0Wf`wKv6c5dK7BJXW#kADFbVjn9mnsit_(
zJ0S%gIil!4GNhZe{~Hr`f(3&cugAGo)olnc(Pcad+zg00O;dm=!CnVEZE4)C&$!xJ
zsQYF=4_T>W*GwpGh2`XQe(n%Vv~6x1<7O!K95dcE5Prok8g2=T`b?zNV!%NQ3NlFt
zL`Y;kEC>vz5C5rI@pQdrlvxTr$a~8~dw@b(ZddNTtAkl&iW+W0jUg@3*jJ-js0wSf
z4j<WU&PoeM9d20v6q<f7&ek$I*e!wXNG4T>i3+ml355$w*jJDAky}I31<VcCyAX)8
zh~L&PbAw%;>9u#gzRd+4E|z|9Q<DBxBh?%fFZu+DPB#6%Q^6@v&1a-iuXIqMJKKZ(
zy#LzI**0(K!+u&`HO&acLR7kcZIykoS;4A>4kK#;9YAakp8to2R8-4Ce_~MM&?aGw
z&>yfJAwV3^V+Tx)@o|bcqiKIsz#Q+qNRP^$hzjTm76R8neRA?}AV527DkOrJ=o?rX
z*<iV>bTk(=U{hu(6)x6rpZ;AQ98Hr%7P2Am3Yv1m#FS);^&^%my}xhAx^B~=EAaAx
zMw22Cm>P^BLsM`$#n1C91SQ)K;yI?=cEoJ#)|Qj$`@$M<r{a`rc=&><Kip6S1R<U)
z^<>G_fQXB9QW_sU+79hw@e-W@Y%CF;Sm0p6p|UdtC--%oMi5Q2P(-Pb^GLY0?^%5?
z7&)jEkO9ocSSW^mfmb~5RXQdiCGA7N775bl^m-a+AO1CFgV$iQe)pR+l;cE|u4cmy
zRqt0|99k#o^bVebUj0Cb)GZ+~DxBb7a@SsXjOn1M*WT@@jV978VtUrx2H158Qc{r|
zO4fFuMW?Mh$imPk+%Ix1)pY2osm|v!45j#Tcba=r^rL?&5!_8X1Yq#=qdfF7P|aJ@
z=Hn<neSwdfEpdJlmTQ9=iP(vJs$yGqk3s~DVw&=lb=LmMttX4IzLf1`QjV~=4A1ZN
zId?u&ta}63g&!_<HTDGH*dBz+m_JRVptZ#<dp2eYsNe0xul2BXi1`m=L}<b3`q#v;
z&GmVeB%?^w88FZw_LcO%@-k*B_Ixiz>Vi4zh|P-H$xZFpf=$53ClfIxrq~0Wd6jjG
zQBDh8zPMy7BBl54^J)(OP!R=Gn2>-(5pAQ#JNIg;*N!tTskPwC#h@=B4C(HHvo014
zJasg1fiT`%U9&CEvgq6-6qDkNvV#I>Qo^4<$HyGkEK^D61wx#o6=N5@KmcdDxSi!F
zxChY<OBY42sEnJ0-L@(46&F%N;68S6@lhvKwdK$HJP0hYN;ckSSx$K$G@Uv=y~(Lt
zybsT5KF6-V_>!6@9r>eji@*OBbOu5}Ji!;U-Qk7b@;gu&l;n!XHL0cwnF`VggrNJ~
zDLkKb%xkx;NX}Z2nSs>hR0k=^y?$92D6?J&@tEg+xG?@i;2kv5PEoc*qNf&MwQAE6
z`}}EJ+T9pKvFDv%yuF9Lg+Gq%<|SfYM3&nd{ie;n3jGgx^NH0$ohtf)dH(L^jvtw*
z%Iyq%YY-el`TMZzBlr&a0ATDPj=Y&=U=y&%+K(caDms5|Ce63rvXhI3=z4CtMJMph
zhsJ$d7$VkO(gZVyH8Dn3V(On^9(igWS<4vMup`?Znj{LrYl0&0`Xu}NFf_q=eiExb
zSt~w2<`ac%V7VR%dwj6*{jo*4!Gpp)I&5x5RID4CI%}BYV4ZT1@&e<0;%5b~QgMRU
zaC8CovIAAKJIl6u8tCA}b^o&0`d}GI6M0JY{#DFHUV*(B6AdC-5l?i_4%s~ojXhh4
zSr}l4E8zsOr*W?nvr6%&Qjte()FMQaVg{Sk8NeEJM@YHNYi_H8LL?UQTw)53jaI5%
zFesX%<Y$)B=T~_!t&bUn#v`0$;09n~f}@CB)gIyd^a0+Evbyue_^bdajE|7BD3#SH
z&0+x+fg_1$@!-fIT`7CAv+5$@Eeh^w(46vS#0O&3J?aPl{V+9!%xBqeo_YwRdJHjz
zYQhqbI-%rS|BHYlu{x{a-5K4UHTu_W32!2y@dz}qxp(4b`LT9C)jaYF<ihJeGEwND
z?sg@mOi0$kHc$Bs=7(Gn#2@?To%bIv9EMU=)o$=&j{Ur(gkTSx8<p8y1l(T6Si;yx
zG8Jh~C0Y*T8DcabCaW%PF~8q7X<%w0Tm)LE1OQB|yzmac)#~9h*3F0?i^dQRp?&Mi
z@|KAOL6@zR`$(rMEP<ca<FGatZ#NY_jmK``kiF-~cvA!T)V=T_iiqN_{Kw0dy|?;J
z^_UHNxVT!ABabW=zX_vvMvY9v(^sG=b3!*1g<BzACkc_C)}z@qxWN(%W|#b${TdR)
zFkc#5Gt)dwU0GF=a(kMuqhqKhopo-<?>+64(|=Ip(Lllmf$s=4VHzJPO4?KEm}X}P
z5JNTbELNudq{pkxEE#!J$ppKMiun2MI`{R*gjXhnCQQWfC?GcNqY1B6Ka3%kB)F`n
zUBpBc5u2S>wTM0p*C?U~#Juo0AyuaIh^)E?28Ud_r_1dn6~th8p|cf9p(sG6L82!J
ztG1&L{V%*F<7Jcktn9M01Tj2N@kF#?ddY;Y%$de<yyO1s7t2R3(I~K5OOPLXn`N>M
z=dpX671X)BOnxHd4Y5>8xLMYuq_aSGBG(H$T=8*vONT;J^O6ZdSL^;rX0jb@%<$ks
zY{T&FXaY3GXYU<AQ2Pm8RzvE?t!~BBk~Zn*fJhAw>}Q7%-7m9)P-pWR&#Wp4GDXv=
zarYR5ejSVbUd%m*01mQw_iscR3g)7Ozeo(`o7Gw-+s1-g4gO1W>C`di*seuNGxOgk
zC<d}E3FUBF39(_j<r>WJs5OJjWnX4>m8-sAEL`d05c+W`wQ;dSC0t5Frkr=?HeB*d
zglUE>h^}?9)Z8!ObctcNW+?ZlZ+Aza+=*N%aON)}sx@gxCxpmK!fScYpQezTt?Lhk
zxZ`MG&@5$;NvZJV8<IBzi18QgOG5ORqb;BDDsv<X=7O;()KC`U!Xm_<AbnPhK#X|c
z!nE294SYG#J0s271AC<KVJMws{yKVoqco=MX^up#R#M6>g^wlo-4Qj+;0Eo_kNWF2
zmZ;JkmqQ2uS*)s#H1f2ra9)BYU;mY&M8PJH#H?v5*5R)9s)#fzDPPXEEJt)6#H`+v
zcb+4PSWauAnIaukDEU&K5!oVb-6;dj?MZhJOCrwtCXuJV?2c*5x!c1>@ZIhWqU3FZ
z0L=m4KZvrs7wO-Q&yV!&Q43_oUh=-$?^k24ueHtbQRB?%IYDT3If9v$rBWc%1pGbi
zKRa+zDKYeHOb#DTTM-AW>Abo;zf^8hFDjGP-*=A4VP#N;vPU8hWLX{nnR33nb4bdU
zZ`t3%3BE>M6!e8V2sX$}Q^X)4ew@(l`OL?!fB|&pbxtEot!z*Oa>ac7A*Mz6t=AEd
zAd9e4O?`F_r=PK4HF4A2ULgXOOfes1KrJ6o<cn12eXaLPIwv#4<h-b1<+#n4>Uodr
znYiQr{IU#1mtDU-`t)(O!x;7|*|vGb{5PTH&8X>aS5|2ZmPf0QO!`!!)Vc>XgJ(Rj
z^?`aFDShV5z90<)G)a|JO8Z6u7<hJ_7AD{}j?03N=I|2Z@HQ<RQK*Uogfr<`00)G-
z6jYeJN_a(iiuMV;u}W;vEvR$GG14-QgZ2`Tritjwc@%x~X?9%cITwg4P}|X>nGwHP
zeGTowj&HogimB)6$TT!bicG@Id0yN-OSck3Pd7H|^K5&X%D9^p_oI@e-q5_Kn=th@
zC8m0L+~QU$W-fqxWnAqZx86xMNo|rTyQ?rQQLP^SbzCx1D_6F5PNLQ@!m>{ukQ<x3
zqW$^2%F6p*jkbO5*|QF(v7VZ?1%|guO#9*F?i1!Tbh(?j)kY2k6cR#BmJoGEPBMDq
zR;ImotUBJ+FDEm^eyyaECg#)NNG;WaLcGtmzNW2cE7mX9o@RArbbR8S<*{*-?m_Z<
z3jE7^)NJQ<VDXS0PxbVKeKt0HxK`$_E-v4QKP-#<aY8~ZF+@F-7w(TO!ia|S3<b|9
zcomAwp7O)4(8k!@6vI=@t0(7M6$MI)nTdx<x*DL2hoB_QI}n1~>f=G_dwXPaXf<aG
zClcs<53ml8Cm<_>$1S~H;t%J13O-^J-LCB9K6el~Ci#idISn>#o7i_&um4msL-n(y
z{muR4X=bU>Vfd>78xFt<*90<(pVIP{=d<EI_<!@We14~n8+3a;uf0U?l#i%N&0sIf
z;h8`@TS+P0UbCBwl=f@`vN05?lCChFZ?`^wFotC;+_&i@2@erfnUf)5IHYzTm~XNG
zXo9)#;D9tGC52l^=-ZtYCr1-lx`7uc@4kf~f<>rOru)dl2%SYOYl#un6%|-;!b5pE
z+Y+;}>WE3H`ZnaTy2grxC-;0wt(0wN?CgK4y;NsiX<a;2#A|2!lAse+7Hcs&jMXVU
zuJYb)Y^hKxbvVP$FUF0!-PWE^^PPQ*SI3FyzhR2CMu8;kFgy118+0j3KlIrp#_Dbx
zFF60x3J<1hsp1SPx2gr&tpHLrWo2g-KM5&B!lo2{sk*wQD#p4KMGdI;F~`Zx$j!;Z
z^z<UG5a76#(jxD}qw&AhBeO3lXBKzgVnQW}v}{!Sw_QJtjE<R_n!>9qdS^$}?v9zd
zxS%RJjDIQ-p8Oh2C<O)(5hBl(HgwvZtGe=cq*f~Ok%Ig(b!7(^q=t{@=+>HKD-}bX
zfY|`l>1lr}Ev=%^(6eB*6A+{H6+FK=pBWzeW`e4uq?eZ2Kpob3$Tizy0B|(b)DRn2
z?U6n<aeli-z6yeI5`v)X69j4k?hLJnPPZfAJT(%wp1Lh<GE|oJ?Mvo()*t!?q@^Hn
z;3Trmadh(?K5i$o97|YGb5`ZUgzB1fVOFgpuT%gC9>o+`1e;Xoyc?YW)%h~vIeC27
zWzGNA?1=7TxtzSb%f-`IK@ZzAo~>K`+^`*;rrix`K=R^ky*@1XGZpiQ(efV{e?C^)
z%Q~9jrxOCGm@s0N>q|lF`G^2zutiB~;`TQ;rm^+bz$b?pt?y;2Sw$DlsJstu#5oPd
z#IU}P1w&SXm<`O)RU#b|_c?G`+tJhz8@WC_kI<8DyEGDx8nY$1BTw~CG{A5+x8Y|v
zx3PFIFk$?~um4H<o=3ST;H-I}ONGrY-q`B_EkbX|<mKLR??g-|2)}zXBH;hCR#Sf9
zh8+hJGD`fpeMb-ri%QJzT>=saKnb57ZhCGJ^qZXFTF4L-45l=K3C%PL1h39kqO@k}
zdT#l~epaeh)~HG2?{1UzyIds~kk6bX_)T_czntNaw>a@%*VL=u&2~KDcHB>1I#kl{
zrRcAAU7gq{9e<OmsOl2ikO@^bGe%&qP}BVf#LQR&d<7W<d5?|1ybCHn?bH7dE=EXo
zRw@0bMnCCbW3AurN}}=gD=`VlZ$2{*e4EU+1qouuc$acARFHH-l&@TL)%Ivd0kl(d
zRjxMQ*%mfvj841Q;5QzjMcS<Zk<1I`=0o=1tKo``iP_ASj^O6wb6+x3n*Jpkft9Du
zx%F!h4~%TSoXZ5yQJA#gdrCQSob#^jsGcCUwuBZMdhU<w@DZQo=ksHE)7dl1zm>Ys
z=0qNN#+1`J;Y@Q~GoPY$-q!IKYb-}3!{@gRF9yOEuUXpa>)5>WyqU%rpxBU4<4nVB
zHuNKp`FAJXfiHR9;E0yEF0whG`lm*|c6&b7dTRR8?w^*O9iG%^+2Gs;w&LP<-v7Q7
zM!MSkJ3kab8cC4s(Gf&VT~(4Py_zK0Fcl<hycB?|76`1<QC)=IJoTe$6Z(zjea^y?
zli^+TYDvQRwBjg(R!<r*LZ+ZgK0^Irdj*Q_HX0U|xDWA8qU-k^TbRpEeqRy#x8dAK
z)28=CTrb<Q?BiSjlK??dF^Wmd7o78V6Ngyte*bhlTQHU=;L(nctgUUaRYbopPINjg
zEdy#(++l%+b6u(M?&oA?AEz%tfgD~+48#@{_BstcqO`-hcT8W)Zw;!&300!pCPkuw
zUmLH|0_tirT%@DOs{y+d<l-*y%43qm4U0H`rARCTxDG197sDMy^Ilt`VV#h0O7*c5
z;zH7fgq<;>v@5mJe}_ai6z%*ipJ0`8DaEK(b52Ko?396hlg4*xT?^oS{W?mq=*yiq
z4dNfmUFVbKPu{CH7{&JT+6WxQe;EIPHQb}_<v4e6V?PDr!yD;lU87nY#y9*0FHg!e
zhxMCVLQ(@R;FslI#Ls-XCib|W&$yoHZpassf4>2c)ErB#n=IFhH%h13-7{lAb?xsz
zEVkj55t-ml{ALK4CM<j^2%nQx3sa*7B|j?aKEV>v*9cV#!Esu;JxxRg_R)#^E)3YI
zxYHA7e%RTk1~0W$x)FKs;A&B#6&-bBZ5ARjpgsWNw$~#b|J}5FWf~8FRj*n9odl8h
zx&%PgRzlhYtmO!n0;$pCAR;H379Rv?awad0NjVZD1C}ue95u9<QU13ly+`f8XNIvJ
zAwa>Kk~TS_>y5|(UbxNr<l2Lv9Am#aW?hr_0lcB_^9LD|B;9m(-&-+vuJ#+Nz#u7?
zL%lGteMet3AAMhOKX<(wZh=O@GAT4ty?}3GhKk<`bHB%&hc_R?<C$V?Jr2W0qKsc%
z=Wq^0*60SbE#ymDz730BF-(XAai`S&<0mYo%%K@hht1o+&m{ZHBjw=LtTltGw<_i?
z(T62OX|2Xi<g%CO50u5zlZ*_?;6R0g%;*Q${}>zr*ETWl<IQ#s6m561{k8;G{r|4a
z3>7T7xni~7!MHXiOQ>46YUIfAaN%vql!THZh5<Y?YOwjO4*#ts9Wa&~Oofi0@7(qB
zcu9Q@5!ivHC*yBgp4YGM3H-J+33y>yT3Q+t4~AkG%=hYgaP;V2$Hf7r_D5A!rxm^?
zY0Cu>%u!LzZ$<u&lqA^EWjSSX$DAz!_7X+BsX#%-(aCX~{NExWHv4K;mL!l}>wIdB
zBcFOG+FH4_x6O<tQkA0@`mfEMV(V8x3L-pL5a+%ONq^lG_$e3R`X80(z#y2gGy;vG
zw(SRDc|e+4EU-RmYMYvZeA?pvt!1mRY~jz$q%lhO6sUFF9KlZ!7sMIdaC;nF?`p`4
z^YXe}=KHZW%mB<^D*6y%M0qvp>CF-jOz)`p;m7q_tS$oA%asKHN?WR$wE!TsivPKd
z-~Dh-7~d~sE&{;(aav*o)Ci(>AQMKzf-iFMtB0En{fb@tV3o+Vt*#s5b7^I|cpmK2
zEY<EYZhkhIrtD{l#pKjoSFzH#U!m<xPNuF1YIG`8V4*HTo{`I$&6*ud09_FN?ECYT
z-E-B^?d7JhA8lLl98M&~VTF;v$M?`v;C^2}1QrOT$;&S+TL4r_zeI8G-tTtIW~|@r
zR^cs&7F$RtP8tf`Lp^w4cg5u<#8nQwJC}`V4XD%6fmjO-=ZU`5Stwr!VeD^RFf=Ta
zkR*EQ@cd9xP>UKa$m3q%*t-5+_DYoxyDVKaJd@YqUCAH)#O&e5VF<vY-`(CEclyQ%
z1Th<=P1kNb?@^atsZ~0PDcFCs%s35xe`TmqQptD78NDNw&mT8$-+lXtH4_a?N~sqT
zTGQf{8v8EZE&H;9$*P4g@aKjcYA^(PjD*fV-<U>%n2w?wqfB@<U}dSsy7nnSreIDX
zPfn(7lpE9U=I{kBf=bkNcn!wUU$Ph#0uJ^%3<!L8IqdzETG_R07?eJoispUsS;f@V
z6PHPaT&4b~zFeCIG=fi|U)oxV+(txTy+fWPAI{6tIvE4{wTuGqe6ep4++4PYm}S~i
z^{Um3FlBaiD4gDJJU+`hRedvWTm+7;3+mmfNxZQ_v=%(Cv-&6qqc#`DOCOA%MP=ly
zpE`tN@iN^KDnm?cq9PX$Tb$aY$PP4%we{0uzLJIp@FNJeldYBB7+_!SauuFYEGx>=
zdX9ZyLF(A=Qh+2)Rxrmv%I?N<+ttH%3SS=Vti1yseMP2%vfdi%!evnhSv-fLgP-h$
zG>0$WRrjYggiTprFh6+S#on!z@3#nw2g23FCPlwR3aEPvdixpDxfh4JKw`f{fQU9#
z+DBRPdeINtURPIfXF{${UFVyTgoQh?vRLEBZ82?_B`j`ni1gO=-;onsLS40ov|upA
zpo;+qvXcahoBlUB1?F49^VTpLymqPwNlPFWMI-;@j(jUFhLS!-t+)Q_J<D|?;O(?_
z_u0v$zaky;rM*Evo}=fIpqshHCi?6#>a*a@f$%<zz3{#N(SCf_0Ev#il2`r*0fW-p
zaRd-MjVj-09B{2h^B=sr{3)cKZb6MZdN;V$iN3hV^@HMV4SuOAozre2S6`)&llJ>r
z+(K0%;;by$ytHSwRX5S~qJrxFFh{U?om)&QwGO*IZ+8PlJ6Yf}5E<uFXXG|?zJu&d
zTtUKqi;(@42__W#&h{bgqY@9w`RS`7eEo50&d{s_zj=9}w|2?idqUymcK%S3zM2-v
z+&KU+n7G?DHiKaaOa6(1l~(qlWQ9wDmfpUQV1Nwio-e&JIJLC2O@8lppp#wS-R4e_
z#yQX#u@(meG~!Sza!Zhho8%ucMLC;_yQx8pJxp+lExM}Mt&0Hb8#7S~Phv!HXpsNE
z`gguZIK+Wrh?knW6JnZwECZGRBS}cubdjYYr}YgTu=e%$<53)cqWtE_yCrlTrz9uw
znE@r|aSBf9l-){AM9t{iQV06l-KA5$s<M-+K1<l`>W|IM^V>Jvi;{2Emm1$083qY?
zq77JIxbucHxSXw$EZ<I$AH2qXxt~Av{D}n|<a}wwR+A*G>SuJ=3J_I*jxNKuM=A;R
z^o)VYpQrBwTQ{v(s(rnuMhXlvp`ZLAd?x)hOOsTAhzk&$9>KWydpDb$%4H<iM%iKg
z)2L94Oi;wIbN6MBJ5zs1)^7c&QMpi$Q7zv4EGpux*(qS-{(Ci_cSW}z7nhkw)WeH|
zof@M5Ci_eno4`|bCH`E<k=8Ln=gbi|R-ip$1XY@B#e{D1!)gW*uP771C7z5G3<o;g
zWMtZk3FUO05tRNMFX*5fvFLyI#i*rTWXvSz7SWF|DLw4cEGD3_iYT3PwdSiC+*X<y
zKDZV#41Dq+7xN=dR<!7W)rL@a7QIV#-u#7H%HKfx`$QePPSE*O=0K9ru`O!1<AGdE
z@RQiTDCge^^o-pRi9-3J^RF27;Qi1`;BB~DOQq`LUXOe|_cr&F-M6ChQIKQE)$uWF
zvRl)xnVaCn8M$2lyRuZ3-*^+;+=7@Sz=h>S{)O@1ysx^M*28IlW44tBFuOVUKwRpA
z1`ejP<DS((X-cxQh65vBk@yd?S-E<Fj%!|0(C){qN=mg<*pG_!*?B|RA|9wzUJ&)!
zhObz3FKv>#j-H-$y_PIK=G;$n{tTv)z0ET8yI!vx+1f>bP#>xOfs}QN>}9%<yVi<-
z*0s$iaz3C9{90$croCX?C`8D`v&SNnRDw4;SN)qeHwPZdsW=oR+Z*2(OId1&pFh1Y
zn--DVhTj;BtlPriW%GYr0KgL{a6-uj&^VEi5iO;Z^ENAsF8dja(;os-#U>z^?!<?8
zEOai~Hygz!5mLhMA;jq$MZVyX$i-w2`!u6z#VZfgd}Ea2dKS#*G!<iqRPnCAg$%R2
zBbBH)?Dkm6cs@Glp5>e^7Pzv{4O2&R5_w@Y41D$?*Dq-2ZS}(Xx9;-<lLGpJ2mrD}
z+h4euR;D~6ZGKVq*#6C{3IGMIMseP*en{XVJozbcz{(Qje}nrc(`Sl93cwnCC~s^2
zn+ih$=2+|lO3oQk5Uf{izR!FinjxAAk=umdx$`5GgBA=Tg>OA3@PlYN&yj^6bSjj5
z9XB&~rJbBRk*ed-lhBL&IZ`esBU-_PzyY+>0=?fi8tnSyN6f?rD%fJ@5V6})E_xpu
z4JSY~vDp->{9So^QYE2w?wTm-T~~3xjr9*Cy?1YPC@a?6`%n6x;>9B;2dg=fCELnq
z4UVejsJpDt0R=dmIMshb=W6lOjenhJ7h@#eh6}F$=){@C4E$~aN~@h)XG2KsR{WDe
zPsGMREO+th0}W6Fl%a!^u}9M9AD06%psRt0f&rILMzoRX*7S>x7}K4*?SGL(?tTHy
z8E6h&0GKLrzN4~1wDyVrS^~WYe~jFq=dS2h4gY++{k3@amsF8|IMK5Ii>Tnm`9t;X
zgc!KX59LV?l*VU=Q4I(Mwf9J}{R_*0w2e25x4N<kS>AqmpEtL9-cV9mPLLpNVX>x%
z9+ACYvNejg5I;ekdXw-(1_1_>K=0v(SX|A3L%|)sH%LD(H}%q!RA%1qY@j`_k9S0+
zi`D`|tRJkx5V`oRvffof8M3A%PNY*nxN*G3QP6^G+(q0I;7cMM-fGgSENM1~>0)1m
zMZkMV4eeZR&l0>?cxt+xd@vTyTA7X$QbK4L5NZGjsio+||69B=Gvd%rrLkYZUobEE
z|D}IYCS$r`AKcHB4X8&-eM=iBPG=_c?%&WJa77_-^p*6TFO-PKQ9W;At5^QIc;pFq
zUJHoX`MWbS%m_GCqIhi`zVryFG7|xik?r)t6|vX@jLX=*-<xsA2w+qDI#p2XV)w)3
zu;P61i23#L!?2Np>-#?7TYy=D2*iIy6Lo86sFaG|{p#`FL{~Ajwio>Bqk)YZH1GTN
zI}l8r5TjHyaIr8b7UA~w_nGVtIfs%Hrug%%M6R*@>$jK;;z6paHSSSL^Jq>UobUOh
zXUg*AkpSXb_CZjlnb%_6<4%esDQ3!tOR(1ZlUPF8OVn}AkohJ+Xr<O}Ju7v!n@#+Q
zBR@ff{(x6%{cBDjyo&$64Vb0XfXp^D0T)~JiJS8I$SlF(Xf#C=0`)$PCH=$2=k!-t
zg`_Dz8l)TirrnoB$iD8wb7+oVq$DAN96}Q*{wuo*z?T9zDatne9&hLie^q3)R$1LT
zru~WN!4fVZP|hyj7z$bHUHtb7IBJdf7*Y9?tA0`VojPOPUv{n3OMoP<Xah}YN%4`_
zvB%m&r}>@0q{I^6L_R<svJ1TTAa8k5Jz%;a<;;Fr9d~}d19CWEI`qXNte%g`1)aAm
z0Dg0OOOov;_i}(X;CG{E)HzeJuQX)zQKyTnBY=qJ#!_7jv!Z@L?){rm^CmMIU>GG)
zX__@Nq0r83gVt)Vams;s#7yCaUn{;tk+iX4J4z`9{~Ip$S3L}+g@bX1Jla{UgpN7*
zMC2)>{I@boqYelhH*0R7z_Ya%xFPA}85N(uBeIW=fChTCmP(s_z9U<_=2_13y!fxP
zJB9B%l>XNSk7pf^@4j11jh^_NfwKMnpz1itR5WZIRr3now3?|_89SITk<cIlad~Bz
zq|IX5W{nXj$e8&Jpjx_K?%-R^j^65Z+Bf#QSucdW;??`$*4vasH+s&oR@G=Dp2@5)
z;nmOaP&7IjwVD4ln>dt`*g$oeR)r9)EiPfmBn?i#>T4l5^}B%I<)lwcT1wQo-;VhD
z;JCQUVStRT{axu~;%EA(fTSt!%hbw^YojMD-F>A-4G8UDY3)eJfU$2-JdgPWN_`UA
z1jT}*6f6BoooobUK7T+2Og%BfS%XX>8r*`g<XYz@>i@`#T|#P}m)y<O{(}DVY}sjE
zLk+f;%4%JJLDhnH8ON$1(q{7;S1s+mL{F@Fh#kLC)!BCHNq0r4Sq3E&HMJ7Ll#+LF
z#iaq2Q^y%UAtx8Sdbf4KBx9JAi91->^Sznp3%fFvXefZW+Z;aHOwU)gE%`64q;1E|
zonpe#`_MUjxFuWG4K$y68v!%Y1Iu)S63%nKC%^*vMH!b^?X?2LQsu{7c*H&}bER#d
zP=kK8-7fBxuA;(3Ko@gHjncbo3iy1v`QVQ$<)jjYv@&WSf=@vs7OvT&3N!+%bBYKx
z2qX@5bCIU}G^3uT`VzlHLwWqL>negr178#l?Tv_Z9Twvcu2MX7!zR?yeixkH_m}BC
zDbq<_s!7ACo{taXgR|H@U_s#tI5H@6A|!G(l-YAFvlZ|5TLHWbfcASTvfQfsg&KZ6
z8!#xaIG=3FHx7Olx?HKB>_?#8Q?7IIxbS_ei1e=z`n!*%4o&Dwn4G+rOm{`0R)Bm9
zlkTTMBXOY>yJZ*hB)M>7K-dygH+A-n^82veV85^CL?VBtqZv7ZkkZ+hO0e>3z?7QL
z_{jURZJSBG92+NpFZI&6nAyD8hDwM@#664Jrls+rzXSE<sR~=2uEzQ9Bv^PlWrl`7
z+oCBMZRPsI5lM%UJBWiWl0I~55rw+8qtG3ZIoW#fXWUOMJ%+>EDl{5RFfnSMfqRg$
zpE4<$?gM0?pOQ@$#2`T2uh6DWs<1GpnYh&QvsP)o%8-fTQ_#ma(HV$IIqZvCvJ?ot
zy}Rz~&%BTE^n@!%i)^}fh=!oyYCH<6Fgd%(F_8P*F#%?p6pi9U)%1{)=q+#M*Kmae
z!$ehxRQ-JQ0veJ+;tz*h4=}9zC?_2<VS=YH<u!?>8__s6Y^7EX-6Dn@KK=R8Aq?W#
z5JV1&^H-LrxjDT~k;aD-XAt*Ny^O!$OuGs5i|Fiw^8ycvsA1|yQGg0v$MXiN{+mlI
zjGhs(5@j-kwZEnoPrW%D9B5I(&BYpf1IEoE2;v(yq#jhNzfX(UV&ISNZbd<zLj-Uu
z!Lv`aIo=0T+|%fk)^izmt44ujR&iOY>oSAm1$A%~7PW!DW1)4p@f^wF@+JdEr@}=X
zGh#xXzM-OC@mo<`lro$->zDZOK;g6Z;?MX`GVN0i1H<mY##Q<Ci1|R}u9&vd%*^1y
zbn;?L%ASdZ2mz=~dX-y-_?ly*4>t#C-@VKqhi5~kK$c=z(z)yPI;Ew=EaJT-=$yoQ
z1o)Bcgu(<~>+qB?R7CEG{nP`FMK;8a{nGF%{GypWj=Tj$F1+h2KowyAgFJRc8Ts-k
zJUxL}m>9wDD5_mD){)4}qiXbV*xsXV4lQ<;^<emePEi@B2rgo#6jtvL?34yG3er5H
z{eqGm-)HMFZI;j7dfS=+UtIrpy<~a4Md`B^>&@-09NPp57NTApLg`XR#QRzVgd2e`
z$la=I%Q=eYQW$<OK2$Rb3(o`zkm6a=%&~8YRckEtXvrp#aaZTjU_3u0sYtz!R$-uM
z8cs2-5fv{`*jYh=G{WWM+=ku3X0zz<-p?^zi9ZrezjX&-1#Hl_`=jsBL_!h7y`*ST
z_k7@kxMlS4egUivsi}IBNU3T{@^7!`u+!bUB5fo~t}^Q=(0lN<AOcEbV3q{7KgK$Y
zTH3GknV<7<r)-f%EtCefw}``Sq`jzlBN7Hf>*&J%snq|$#m=zh5WZN+iyeRa4NHb8
zd#hVfM2jg5a{$ZFOTmzd%}A~SfdUPN>5ZC=05aBnWBoh0+Q@`4J1r(DxYNl}pH2eo
z+eSe#&V8BSb15dtT8NtH?)q-w+>C$)(rq6r%|IPX&fePAYpX{)@@w4HWP5$PRzK4%
zR;Cmt<0d&ZK!ZCVmYkCSc?)k2>U2)vBH)R2vK=a<G3KyK43nUl9=CC@AyHlp#^L>w
z`&!j$K~<Mpn_Y6?sK49p+T5Rr#(}sPDeJGVPTeFCe<D}1@KpbFP1;^N9{0L0jXTPp
zup$HHxeC0R>zLyK{rarERXhmn@1^pUuq@3vU5Q4HMh!Tf44xxS#FeW39wr`5(X<@x
z#*}il1Qe@JUDv$x3pumeBAs4l#S2<$=8nH#F$}*t8(b3(Lbzq1!f=d;#s?&@2~)@P
zl^=P-QI(Dc%=*Vf<odE4InhcS6cCzllezQ!M%-I@40v9@iE@2oQb>t|<A84SUQYdn
zH5rY)ye-$Q2f|D=ngP!d$(#)d${NlS(f>zxl1p*OSGUR49i_o&4iy9<fNQMS8+Z=g
zVbmH5_FDt&&#AkwTFg)|q^0bupi;8%qs0j0^~S`Rr}X*23sDAKsHJJO;FPQ3Z`ALO
zZ|&I)GLc4sy>|h>wSvG$xbDJzxl#@dH)-$t^j1}pI2D#g0>_?S-wxq$ACIq^q=$tx
zuY^oYY#HODC_WKWfUk<537Dg{PMEO{l<65yIix@Un{lNA8KCpW1rsiXRfmQDfCP;Q
zz2{NO!2w<L!YlSjHv;^JK2NEbG>;!Yk|2mHqhs<wXyzWf))$vS8dT1p`Nv-xvvIX^
zlOR_A6*kN3nfrhvsXeXYjZPW-n)k9YR73WPP8NAlM$c!6T7;Xx_)8fuq#o~bUND`W
zZvYl^5f@2HuzWT^@T1Ba=F|JtT1g(dYX0KMg4oCCmX<wiVk(5vv$@Vw)IZIbAB<jW
zEnDxFA0Aoy!kyQ9Q{B)I&K$kC*!@mc0@k(en(wJFt$=Ut^5iXDpy_DpQ4dOXegOST
zG}u49o=}x|BRL{f%J9d(#O&3b8e)^9&r%PbTHrAK#O772_IY=02@dk_)AvB-<U5<)
z-Hp)`FR*X`Z{n+>!F06j`ym5jN;dO=ir5f#D1<paiM!nl!%UdbSXjwGGKmrP+V)zA
zb>}~WJsBI*!rq4Jnwl70Sa@Du-Y@ams?EH~?FJf|W9N(JUqI@hqXm{`Eww&_2NZmP
z9v2x>K`QuGB?Q?rYDYZTjh@ct+z{3!Zkd?^^_+cS4|lkCm)CWl84gg3qC*$IrTR4Q
zs$}<iJzq9XmR_vB%}Bz%4K!t<46qd_ocvp7Sd@p$xZC%t!Hm42M?ok5hc!t1&u+Du
zZ41BxrOoGiHDS7R=1+C)(*~3HT=aqJ+uAENy~RONxA%4#l&f~Y1kVW1;XBWebrs^|
z+TTIoOJxaNX`w9m--f#Vbh>S~L8Tt8Eiy7>ilP%Cl7usrH<a0(BNa4{_iM_<+NE>e
z8^4LpKA*nWPs13k?EtdC`M|DNaNgutg)^5XT3TjS=iLZ#X6E#y8y;qjTtTo;)-i-O
zKcM@~-Eq-MF6!|1bDzv{boWhdr!_||{;2>kfd?G#E!LGZTiQn(=kCrrx}K?lzKTB;
zOwlI9xY+(TCggt3;$!4SiZK1P%k!R&2koD?_me<BETN48`STsl^3#N9LjI-i#Ome5
z$^d~Ig*ew_CtgqjxdbEa0UNo_l9p}#Hrr^@oOR1GKeW^!`!Jt4d1+{Y7?H8N^wQt#
z-x3m}!Ynm*M#6Dm0-7xsWo(*am^$uRVw7WxbWf%pY1^MtUt+?BwE+?bhz2qHd9j51
zmGCSeA*&Yg|A_j^u(qD3?cgrKT>`}&3KWMTMT)z-7b#vGihFT)DOM;@pt!e1gS!^@
z7Pq{I{{GMP&WBtfA-iYy%-Nl}=iZsmOd-3aT^)d5?vY>(C<c$Xc!H?!Rk!PA!*{Ji
z+RDp1AkpLjCrj-5OQYY4Vg2G;KFE#Fd6}O@Eei<mxRbk~cy8dE1i*i@DAzyv>7~4W
zA9yd?@>XEx{b!jhJRsNz<gJ!A!VL%48s-iG>F9yt1EpmvHB1$40G_of`hnn@Lg=I6
z$rb4;*(fUG`0V=ah^=HJVNvc#99fWc;{W<u1p2xFt1I{&O(m?KM4Z5>Q^cq$Y}}s0
zC^$v#4R*R9kY7Qv4lmx}hI1u3B~kz*0`hAtMTHM;52vs5XJ=$(NtLQg63CoM1)IB)
zfa>(IT&$qmfZlsaFwYD^;iG{n*Z<_R1M7tO#vdu|OPT|;|H4ojB>9<dnwG6=f=?eu
zy<B$Y_ce!KK#H<u6nd^je<z8g0=2a-IR+V>RamQ7fpV6uPq0a{Fs<dK0W$C<4i?Rs
z$euZz)F6tgE!GXyoZi3L1DCR^sVFjs<-^u(yiZI5vON4Fzgu5*D~mjBGit1{{C@c9
zc5|}kM}9e@U%8D3h7Jlc$^mYEiw7zgTGL*J(Yz{At2ysZ4hAY@zC=;rF8;rnGDl$7
zCQ1h~ryb<G+|7Sho{p&4DoJU%#=qYB!FcNIoIfR~zm>XcGU&GEPsC!bZwTlRr05&>
zSV-g^kv>Ax3=5E6wo@}G5iclw_JhCSYZ`PqzO2`0B2`N>|7CzUP|QZwZ-4xgeKWQe
zKt3wlpm9liP$Bg>lCkrSkHMNzgMH3T^kJ{dkNUJDfN$nKiczg;pEI(m;le+37MG8X
z9Uv@}02$=;UpHt+@X<FSr$p0WA;3$NDA~HTFU`<DUlQcNfE-!Br8Xw;5!M+o7jSQ1
ze)xKtd#cTAJ=w&Etks-j=6w~b*25+2DP7lCSGj3fk^w8Ke&38h5h+L5H7VQU8E?Wu
z=f4L!D{Tx%7au7it${TsMtNcYxS4%6E_~{zsMdY>aD|%dQG53Ouwks~St%zNu#q5a
zr5Vq)UXO3&KmDPu<LjD_yTi3QQT~R`9d~14?053wV}O55Q*i<dHX&EN1wr_Nej!~6
zXxdtwmL}E_Ii-Y_=A)8}VF-p*j1udU7jN~^nDfGUS74U#*|NU3pWLWt&WN&e=DD5M
zTSdz&O5L=mc}3Md>G8@MuHSc}Bz@l+6jhFXZ+4l`RpEewj{9Lw%3>>^&TOC+5P#s1
z;4S7U5a!}lMMdqWZYD(I5JzP;wQ|QIDMPaxggJ$0LPJ$SWx4C3rrAI2J%!TO?|69q
zkTbOX7Q&N8FXvc<pB8!E;`0>$WasU<M4`o-abv|~#_QOPLp)9`5qzWg{2WXh01Q2f
zWeus-+q$(RH%!b_r5r(nzL^(aVw&g<jHFNr-utA)ywDAgDmyg?vb&$6tg|2#9q-?v
z&f9ws!v0*t!in>J;q>1L#mG0ldlg1O<@ZN2Rw>T>_Lr2eI9t%70{d0nUU({fqeqxJ
z+_i|e0I(d3J-ntp@446EhsCB2PKFI1`c8jqoRVH}Jdtn+o4DQ@PK4KAd8&T*GV>xL
z6%RCmm>l7>XHhe2T{n)k+sY1y$P&qZa1f@L2q~3bqs|<)t8NAH=l^EajAlwvP|fy3
zF|gX*8jf}USeiO8EA1B2o#<&>W5G#N6MXxZm^LmBn*i7AY}B?Cd~-h6-M{za?e+Rj
zSag4WGC{Yh71NcV8LBjtQY7Z`GH}JP_6`5f`+59?KF?Uo<WPCK<VH}z#ytPizH?XG
zeqnL3MMh4>NQrM59o+gz*$`rI!c5qJcIwpo8n#k6(Xac3iFgXkH=`FQo_y{_XpW3F
zfx5f=wdcAJz3#aU-;>};?$auEC1XWq)vpQwTHh=n>g4_bzEr{Wkst5;H2u&c`qmdt
za6rnD`%<6s?=FXvvEioBiedDU%T}N)ym2u$=ehhWYsznzxcPBrOsO3IQ^ZZWzfXZz
zCynx758LtYVXwSKMIFAZ!ts5F!=(X*q_jj9y@>l=_>!PhwLg|(>+EXm^hjkrVe3p$
zM(M{l*}TNk#20bQNf5Ne`QX7xhvU?xm9Z^iJ)^x+mebLL_Dnr3m<i&Wg8SbcDy!|o
zt-B(-Iqm+U{wJ02KMT_Dp$Z*hN&SjDK($jqM!|54qwAmPV<LLHd*U2C`lAL;_}k*5
zsDP9z2b(<F#A#IIp!Tnc>sODy^T$V{TtX0`&wbJ{uwC(omnWUD>xNi>6FNG8TpRc(
z6ok2SO_gIy-e#aw#FWh)BGC1S+<AT9g>)K)J$e#A99SGE{O7MWd*{uWHZw1JiCws4
zSH1y<qPjPoEQPpYS6_j|keQ7QwPaHc_}I7YHkWnjntx)Av)tUa24}rB$qM-qHE!Tx
z>?V1BX>pu=>QuVLZ5Qsr<<G8Zm#{=yoN{<$=4Q;bbI&D1K3}F)bVYg~7NT;{K<QQg
zH4Z4$>FH^TDQt?(hR^Fuav)Z9b?xR-*JF0+5o{_!e3(6XfV9@IL;cs2fWRMo>@B9A
zofTiM7fQ~>E}&TD#ya`%Rb%2*eXGs;ggfwNKtQjNHPX!DZyOKQs>tGp$1l~j7ROSr
z=GF((ZyQ!ghkAZ(V*o9W)d;s*UGaZ&h5cPBJqnx{RcRz~zuP<UTu<d{7%Ir$N&ESU
zpzH1@=el5W7c%clk_#P|5%iRZSn#y|rOj&oHt5+ng%q`##`dHR>$q$Uq$Zt`nXRvn
zrZ3&xG$7`$eIFJQ1&8zMRkN{)rdq;*IuAE~-N{%s^SXb?Vb0xaeC0^H)Y|oOSTIt7
z4$|WOh{qw;C3dAw%V$JfYuJ4XyD>5IdFL}*_^b}lYF7n}|N5(IZ~S=3DWbzvxa5jB
zZlovG)$s8iN11;;X|LLa0);qzZo-K#;W+<&Y|qT4VoUQS$e>NwP%3$kfZ68UwCL3a
z3RP`a0Oe@dVD;-luzj3R=e_S*kAri^FH4f=9^ku0{_Dxd^>%W*+?twdz>U)IyL)C7
zk$df{_)x{FLtWe7<DEyX92~XPa3FrKZ^PJekqjS!@2#8C4ZJs+h-Eo8BpS9O#5yk@
z*SZC|{$jN}<N~O6<Q`b*xl%L)k|jzP^1=V16pozn1{12Mj=^d>mmM}t&aG=;*mJeY
zk-kDJ^kTk2-X@-;XNH*5;<5EI%DJsA|E*v4Zqi}v&8%}r@ae;t09c!)0XyQk=^fm1
z#eaKm77pY7g_Rt4u2+-7yCc$e(K(s*`#l`w7cw%^$^Ft8LT-71+dkEX`dNGYT7)Kk
zWLv{3#ZgYz?PyXsYd3MbXB}(4NO9JJhc3^}+SYPIf#fE@o7rj>egOfss+qyN<((aC
zc`!H^doaf_)1A(`HwjlwuT!B>a05wYYU2aP15MD@D^;Yg^pbp$ro7f+VxQIX9Z>@C
z%5V0LIqRA_1fj=yjF+-VYj>*{H)GCg(yGjzY0rst!MP?m|Laa{xz(5W@Q`@@eqhma
zOK{-0%}XIZ+P3o&`LSNyqGo_*C&;8|YLg3E)X^Rp|E{pD8D~31*=+#F?_(2szhCOW
zP75~0oJ`l!>$LZ;V!j?Z9&K(li%WiL2{J1hXqn|~I$xn)?yp*FK_4<BVtDSGa7g;U
z8-I(-$o+|)Imb3hFNXf@zg|5)7+n;@u}Gfx^eo-C{ouK}1?Lh)L=hR|n!5TU1*}`#
z_b?>0?|eM;MRm~n0p^Vt%!^T|iCzszKg@lbQMoysaJqgq)Et4;-mB#qjR#(SSVZ!>
zzZU@VlFii5(EwB=K=D9L|EC=&@Nk2UyM%Q{8Dq`#qk{^Ksx$bbA(GM!e>G2CYgVMw
z^p2e0HT(?-mqs)zg%`(+SNiJx<J@psAM2t`w1k^invs^O|K=>6+AOe*_fS>2bOz(?
z!_9aA{!Etmq3ZMP{7?2sWz;?ze~Hm=Qm=S0O*H3P|AXS*83mFRoDzWQT}=~mKx{dh
z>fK!_<A>EA8t@REoIVY_9^|f=u5_WWK~Ktkw}j()HXP_3Ax|{k%`JihIE0aV3$C*N
zo5)0KW--{Nq9qdYuC@00KrXwbo>172$er{`h;lSe;y3#t78U6RFH4rx$O82*MIB!e
z&A!bj-4J%E{_Ex}q(MAXqCtzz!qc!anp5n19M04B>k>59pnrBaZ~6bt7jbsBfj2DK
zNc#NzCy}c;P*H%=(b1!vgcSO)xVjcRV_t=Ffr7w6DdqkvHs@=RdQ~rmUw>#%<0dW0
zoFJYzAY@oCFSws1^z`8*Ch`N?(=D}F=H9nf%{P+pH^C9!-LVSKH;5&l=YPuSRKeo3
zwl=h*9Io9LdP;gxj9Dr1(mk<+sO_G4v!CchmqF+dS?%M}^{LrAJEYY}vG$XKh$ZrC
zQ;ZR^*V2D2EXUhjDLLf0F`_s2*qOzO2Xv@KeDyI1A2zyt0TMUI`WM({Zj_VnZV$HD
zhkN`nbMBDCR~0X%rpailSxy4Jy*x~OzJYrbrbYj3dT5TCWR9-Ld^FYl*6|AIz-xDO
z$CG1ITshkra@0pqX49KV#9(R(E$H!e-PFSCUaQxU%DG8VM1A4x%o7{b#H)pi%qvV^
z;Y!vKai*f>-@P9(XIDwlkj%1lc|5nSc(ZAFq@?B$1M{r=iS|i+u>7j3BtmDkJysmB
zf;N!k7#}L)g7H6EYMtNu=5LMJT%!lja9k|G1=%7iS^T7A4_H0O=*r~|QFtj)1MbG@
z=o4?Y<9{z~WujOqk!AI!;b@+xNPUxSDtbiU^6KUhM=@3IW!F^U5l7U6o8O(HGAT+B
z_9?#XFD2ZZK5Xi2slvqMWlR+b+EzK*u72L5HT!@egU{m01T919K3Km4VRn~_(ezw{
zBA13-gG&33A|Y|VzEnj@n3=sCyqHQNw1;y@xJh~$YL6&5^T{IP@}=r;JWd#ecUe~;
z5xT_jp1)FI=hOU&DXlqe*;M#K{r_<RKC((7?$Df@5OS5Rx5ev9uv?N1No|EBPzw85
zr&E3cWfA&%scE6|bf=hj;WOvWi*@jaws>a;D>HJN40)ewW~T&-6?zLJgCff&><qmu
za_H=f_ovqzT+I~}12rj6%3U_>nyzE#;<<DGGIKn*VFtF{3Jnb~6-;@fa0ZAi@R1E_
z@v{evk9>ubE^`%NS{-BI$@LAU34K$4-OnZ}sQiMOr3tOSDQr<iM*RoD0m}pdy1^M^
zRJnR!$YSXCz@#E@_^JJih!Rpw4b%{LtF6!dh@(Lv9xt=6%w)>(l4nR<{-jG%KY232
zZi|Gf9f+8-Wa|3T$3I!%(Zqm~19M{K;WRwkPW!IM%y*L)NiyFC6))Px*JabsudE46
zYQn$02lYyEe;x&CT-_qlu(sfZl-22>r#w<<2RHdg>J(Iz0q*+ei!H($awh4oq4DwW
zNr#BqzY})5A9Ts`#GZKgPB$)cN6YYi)uWBmuw0O&yF(rPZL*Ft5b79<fA~B0ux~hU
z6#=x##QKovL$oRAf&o-ToLD(5Y@KFW7R(q#yK44Ij1%S!)d*wu&M_6~PV0(|736rB
z7&wLPy=?yzH%vEd{n<~8^i{ztoNocm3D<#lVpm?#oP-eNQWv@$SN}cDc#ZQz<r#?v
zTT4=~q%M}K!^ev0zT(r|%DVmY-3)>X0#S@6BH?Q)8Zru)QLIIQ00-O)_rT9AcfR*~
zNAboMstte2u76FExCUMbz0?15VIEK2YdMsUQg#%*3=UDi+9@z6(2QA~9u!FZHTMSn
z?bOhh*XLXvPVd63nce$OaZ;9``3y+4!Fc86e6s64#nh-)oqs>iET86=ZqM0)y3Z?7
z+slP7<9h0n-H`jyXw{7ulO#-IyIn;|&J`DjZ9@ZaR#xbYM+Um9YEttKtSORxu~Kep
zi)SHma`{{QyHuCee^%oZj+cos$xA%?hgVbF;0L^I**LI-kEov((9$GD-Y-FH*&1<R
z!c%0Qq)uCr<G0Lmlnax;hOLERebU4bfEULv*RIHj?EW%aj-Sk&hsdA)4mp%SNVe!+
zo^&W!qi&QY{_93i(APMqb-^ZfGS#s51r6LA4TPrcFK+Dd1~*vlHvwXC{7lW>xo<>F
zbNXZP@iZQq8xDSdvrr1jsB?Lgj}=Z`!?vJc9RFg<qNgMCfgQWw75S}PbGFh)G+e$I
z!ncsHTv??}I$J{4$^&>N7=?}pdROt%2u;jzmyML)jb!~b|6G+sjvbrB2`#I)04}~%
z<HL&z84BB;bXIP-pg+l$(uQw(WZ#3Sg~BpuIHLKNZ8AeEygtRBxV}0&R4#N|7Tl10
z@3VmNOCrZS_4|lWWSeg({~0OxW>6wT2K7%@hahcMObqCkvvYKVec^Hx9~{54c!q-d
zH+*AuO;Ow}91Ch_1TXU@u>)}f*P9PeU4#ggUufiEccwCiB+f#YCIsy#G$D1Xe%0?v
z*)p}!zty0|l1r#QIj8rq`jKBepmT*~X!c5Z<s_*TRLs5BKC+$qSZasfgzg&M!KUZn
zhL5Qnqd0EVPyL7^-rc+TTh7vHd9@p*>n3scl1^kzriQd=wz@Y{wfGsl2SXcJgnd%}
z+x5$az&+~go9|x+IV0L%)jRO|W%6;?ZH=BOOY`B#j@u?-meZB%Wh|5|@mj?8I6vx$
zcV7qIEaB(laVYZoT?{9<z+zDFS5EA<Td?ip&<|?R4V~}s^PjO4@HW)#1}M+>Ebc^T
zh~skzhE*sDBV*Y``$vVx(l?i;q@o6X$N)Cxlb8${q>s`2`3aGK*c5$?E0F>1h?(lV
zspb1e@h55+0dcKy&ds-LFClMO`Dx)=?jWDr-(gqG$~asgkw*bf_WszjwGkP;bq|z}
z1O#fg8@X;iGnA_D@*D4m2mXe2UGQ}g;l-;4BycWdXtiFG@Z40$!Eb7c#{qik4%M}V
zdvz#MrFC&7R9c&<RrV$D-s9nHJOGh1!|&VXv5M2yl!-sOuWXtYX*!9_`t?Mm7FaWD
zyO#9d`1mAktn8$p%>qc#-(LbD#ALJ_ntm-q7b>VhY4{sWXH;U5X?59QN^Oiq8XJ4k
z7)W>bM)chH?AEfuC&nm{kPmG>j$dWcO6J#ACGm1Q*D7Z#HgI5%39eh0+4yUocrUzR
zCSu)JkH=BYz9&&MXLqQfVj%@MV5Dy5=I3$mrI-zq{WtK>o=sGn?`I-@vtcoV>=}AS
zP4S&^v|D3Q!MW%vFZAd6UUyCPt<Lgaq>LrHXje4NuPwapT8f}X=8{dMM~meK+$Oy&
zS~BT6J^n-0p{rijx$|P!m5QqK3}ff<W3K<h9b=cQA9}J11MQiwtw6IiB@lQ4CY)Ez
zS|1mj%Zg*OVd+Z`e6WB^5{f~{De!YsjWF5#=W!u%vqEfaq%99NK0B~9CwWrQ#NpGs
zj-+S#6h`yKC*>tA$h3F&ox=9J1_e4{qmx(X=S$S--;Sq(s-9`_|9Y|85F|>q#~dFm
zK=1z?b0U#w)mtJA%(_PPCYhiGy&fn?LQOy(@JGOJXU&RarVr^BPe*u&gtj;g+akrE
zPGJNw4vG!f+tYY-hE-Y5Q#Xdx<T*<VQ2Ty9(8x3_L~QwajN>Fi&WP&#1vb780=iqC
zp*4`<Lj($nHKLJrR}g7(M}?L|ao>z}-BAUc6|V(v2{mBvPIE&ln(S@aXE$_2{2s=3
z8?gUrWQBW<Wm4px<6n^&>#cJD!FcF??dyRCKn95n6f;1%S$8rIyqJKjp1;vvGS;|`
zOA1kHz{LY|RH0c@${+9moYkvs_kK59n8PxNYCmfBUdEyx+X53rb0EhXANxE4TcMVm
z7r=beLr{B3;_g5@kw7;gT>X<_FONj#rI)E)NWl;xdWef5vGMxrSQ<qhdRNSBs|LVP
zr7|nLDN0{=sM$11S{do{`~`SDLX;V{lBGUdZEM}s4@=a&I1hRe?^y)%LS@_HccieI
zw6SEBxyp(D-44B;11>N$^Y=YkR-9P>Z+d0abtEdHxwLwpU8>E<;YeIC2&|dy@o|Qw
zpF)#_@W&)UZmuZDD``HPBFFX@w7evi_6pJAk+xrfF7b6fYo9qkWm9kMWOJ$nY}q)T
zg-`=~(e#9_ZGk=xty1kjZ<%Z}7J%Mu)SJk*8TCYZ&kZ%RvHEfN6=S0#l@WkV`b(jD
zm1tfHYoD)7$4dXx6-PP+B#V~_U4t*#*zyKv4aF`^TD59cwMuJ45c}>?Oehz7k}uc8
zlF#P(8m^sT<uJ1JFDAJ+p4VO|H|x1=_-iMPNQBgJVM1ibLY0>;vm5_mQZFc-*MVg&
z7ajsXPTdu}h!cueL|Zh~PlA&AfzYhx{n3aGPBQz4d!v3ezL|J^pf2JK488jxlbrXB
zJ0x@j@{545T(@W-fXIbZK8txvu*LlxQfu5A!bO6es60iGZD4S-mz*$hcx6oq83i-w
zPxQ}_0gnIQP_L79@uyo(?!DaJ&ufSknh1Q09*soVXRNE$|9nSCman5B9YiRGpa}kl
z_qF#JOx}Ggs$kU#JGu6~6Kd^gVf}pX(=7I;Bwy;82;3|@N=zQYIO<*IK&W7!tYfC5
z<gPJiQ_ED$xfEUCgq@1fvOL3Dmo#5|3^B+0;3cuyh>qes0JJyFXniz`418KpF>7!P
z2TzKa6(PONAsA6&gGBK@T$;3pnmkR};4kg)k<e8%SK2m4@ahQW@g^Nd|1`-S$y`4V
z{KQ-rXn{DGf*<ONU4}JGoBV27#aU-W$3Z-vMQ8FF1vK;%_TK8G>&JmN@H%lIq`pcP
zF!*!rTV&cSsx1wY@q|aUo%aweB<utso_QZ4U4O4ykH2k+zJky=;y@F)6t7`?ImYaQ
zC86Mm$~m#m0^veBNo8E@V7_5vvx7<W>`G+LNd&(oZq>=ttlu(OeMy7VnavGP(5jOw
zkz~JmM#l7+ql`&&oYnmchxv%IAOO|`R!Zauo`s%UH<4VRya2e_<-yc9VV~Hj@W7e}
zFH2m}9fprF|6-jfjLHqWVK0r6#rJ$VUH=;pJ&wZ6qwTOy(V)6~Ad3q&toVRBG8GeP
ziR)gSfKx1k$=1eh$8R{^m#UcVdig8WV(F#+D8uT_-QmsNRzh8K*Z2#k$S5K{pG=nT
zxnm9Qq!A5pKHPM{9^N^M?kO|WG2bo<IGfv*VrxjrS(F+NpoqgPEi+SNFe(tSFQ6y$
zXe&pLT>Zq<Yt(v!SQNT%p~u_RVcwrID3X_gS<Tl4v8Na1V0H6XZszY}yD$GZXCF7o
z*k=93^9sr6Ct<7RK)A8}EmvfWlbgF@zC_K)0QX4{_Q9~rlhh8+41!ND23FT~Fo(?*
zix=s|u8bb5-&q$)25cFB!mMlVKnm_DVT_{S$NrsDo)<c6zMT>NF#=yVFP0>9C0Fcj
z1v+Hr<xH-oUq`En17i$?L4Ke=)cIx`;Jz~NyzQM^IUlmC%ZK^hZ~j%OyOF$~e<wnv
zQJ+XfRjwjV@`wov(yxjaj8_rE^Xqs0^YAdHp@SLAiZAwv6Mzqw=w|Oz8)IJ#Z_xV*
zp-CS}vIgGqB!R8DWjSONJ1^8CXA7vQr)z99Xmh$orgyS+9T<1=^lL9Jm!4j2`Sy>e
zQ@wr%T+`i*GJ5{5k0hG?sQ!sHhj<{;=)mBXM<L@k-qogSLh&=8O4R+pkA!J`56!BL
z9&VD?!5I%Ug1S|n(wP%Oi`y|j@;p{1=w!*sha?}Ykj_J)bO`=yp`&?^kVdpQY+B%9
zy+gps%a=s&Y_zfq57>2Y!U97ru?~B-{0A>ZNQP3<Y-vG;aJ6Ani>p(VL)eJvuZfei
zmJ@gx3?^FBDmS+t;ZAVyrj39V(45ez4t^YsTa`F>M6P-p%aE3Az}2w*?BQ?A`~CMP
zpt8~d8AQn-lgB%q`K6_7^^bgCo>xAv-M^erUB^5>1a!Zfs<#h+#Mflf@;V1+4h2m5
z1-f8y>fiiNhkZd$?=4Bs4{l}yZ)KV9PaRJ;7-9SQvgr$_TVsRBA$VzT_D?*L7>e-)
zHQ6TxLy7ZDVXtr|=;afoU!l>1Drb=OhilHSO}gcr6O_M#g6{LzdI}7b>81xe9!^c1
zn_Z8$9RLK{nQ;)M>&eeD^Y|WE1&LoRkT4S9{1L9X%SCjCJ&v1>{5~}S3`Mt-82jLv
z-F&%Hp<6jWih-M>&<Ew&{Kt!3REO>ALO)<gZo__8Kxsa|JaNhmc}MXdD&}_!Dgog*
ztG-`S9<P0Gr}CUc<|Q2S3qw7mx5lrWp2$8%o6+f#Hn8Zv?B1h5DbYh8!hzaqGIqiw
zn-f~PZGUMyppAM00DE)hfXdU9%KPERQIjVu!)sFEg#_rzus90J3Y9kJm$a|2xFwwT
z!z8X}v)5flzn+>;oOjYlFCf!PHR`jUPCa7Y`afK*-C=1Syf8%QKs0%9?gDWM#rM!i
zdEni1x~8!Ki%l+{Yk@Y6GE_Q-KyTF)86wp7+p?iNI_1?0MAZ$Eb5^8rWlK2R2)tb3
zW7~>MeS!C^4%UV9it0y{{G1pRXr{}9Y<&Ql$i~4zpzzhZ!nkVV4rA`TA@El3XA-pC
zq6jHYMq0s$)n|fyof`HhzwW#sNBO`;>*^XveG1rB2-RNr;9U8>tHaG}Z!mMimz2nz
zTzI=r=F5CLY{P^3R<$%bLFtEL_A+TiA5Ga^5}D5A#U<qdDlwE-SI?N#cS5&qCWIO>
zve-P-e9zIm2#N4p-DEh;;A}^Y`nSN{S;~h#lLvNW|KPQZd})mF>pE{&(yH_&Rl<h@
zo2CERP=JlIr}>Kqp$Zv!!20u>WP)$89vhK+(~)-wn%S52LOq`(5wlZy$;XOL3wA_0
z41c&HhFGojtT4%>PXRXRDCL*#Pv<H;gWVpK{UZ&6bAY<HQp~OIIJ`6TIcIq~huySA
zIj>n0Im5O%&#u;B6qV?%4C15bEtQunX`D5t+nYR#RTx~>8M%I^imTlJ?7FgG-k-qc
z|8^Gr&L1aEHW*t~%l-N)6QDSZEwH`D8?ay>C&nt8JV=h?2KEMYtaWl=cLYNz4leI3
z0vX<F^s5<4@wsPlK|^HiIm5jF3bR%;`_Z5Op1WIJS{zt=jOZG;>Ug-U9j1raayHk!
zw<Bat*HL{pZB2&r&+_saVz7l2HB_x#Z;;58;=LY$dOfg>PAn|QxQB#0Lxg+>b0>|I
zUd3Refx@J4o;sM2bOz}lSvuF$%R_f}Lhx(UhrD(|w*eYLM!<B);aQyZ4zssk+`%i!
zr%tM@-lB@%Rs}M>2rfn)a;<CWjNFc4)$M5K(U#?V?jD?4RsFIFC<=QujV_dnt9I0T
ztsV*YRTBh9A(w>B5B9jm#n}u!QGy7a4(cOI!)2#6I7Y(Hzh&cyKqsY}DavPt%sNL!
z?x>ef$&@!Fn7V#e^>JY5=eH3K%Gp7{XWwIv`<5Wk*${nY{wfN^m0*i8@G{}%LWes2
z>!aGk#L#4zRke{(-{c}*tVJ0W!oN#`HsHarm_>3`)5zmpd=RzF(a(=m25Zs88}>t|
zMw9KnV2rl-v4Z_y9LSyZ)lDc7+I>n9`sFQLzh@mCt|0>5l*}>f2JGLWR?FCKl5!Ux
zt!*|L#Gojm3seit+OEmLxG&9$*#nzTyVvKir-8MC<~eq&dpSD}{`&WJNUZ7FfD@_o
zuIoQ{_dP|AUpp77%i}F^-Go!0D@6s%_YNv2e@~3;wlul;XTKvyFnZ$DUG4LnEQ3Lb
zYslD1z~@7EUC`r55%(ZXXTabhI~dyj%Q2i@K01AzhhE;$T-se9&=(MB6p8u^Y=>o0
zaeKtP5PkW>wZ_BdDGcfH(U|$(`-fo2)h~!P2fM}PAF^J1-GirRA0e^=k>cE|r2E?C
z?;sYNICrUC)k6QUfJrasT1VK*dz04Z|0z=;d{id3`vj@hHZ?@CXV)Yg#Kfoi#ME0L
zE|HefrFkhh91iMR_yM>aVhbbY7H$Zv!$6E(;K->t#wmewwO=~MZQK=+v!fLV$~B|E
zZPV^gUW&Q{uRiWx*EKgqTunmwn)Z%P-ddW-`5bz6hK0?9O@0Fk(*eSVF{6MqZq#<A
z384L*r(3DSUp7O>k>?lV3Uh{^v5GNVEg2CK8Y)a{O7tuB7^^kr6sJPfqjJN|xJcW)
zl@4Fx7>pQQ10%{zM{W|#vyCBYT1pFKOrf?6Ti1B@T8@o4*d{xlep8gAO01+sA=1#}
zLE~b3Ll_W6@TW)7>o><-tQvL^!SOX%n!uaI<+o5;@FaR=TKX?mr!2mM>L&x5wtwmO
zI5UTfTx>&It&QM!EQ6CDu+T^Bb+7d8**Rh9k^N-$(qqC!u33ha;JOIYe{5D(ns2VU
z$@{v)tG>A_B6XY4I}amU&yqiM_XDtGe5dsLaLDWKyP_AN=oS)1w41mk=)GT)?(%p^
z9#+=PT-iD=>*gw${84|P=GtlFFHTo?a?CjCP(c$PTXS=(R?Eh?D<xuKsBy$0m8d+T
zZ3ZfFyT9RCyIus4LsnY)Vnj1j;vsQM$opy0t>WWAn#_e^C^5%eT|H%?_z#8nXGPq5
z*tdyJ_<&YBCo-KQM~nv+al~y#cVr;SzrwGLmXme|Lg3NkV)vNM&THX^-+%DLjFg>;
zQfm{+k7UyAyV?jrdnMGo%n?69)B%elg3|4{vBBETAI<sU%Ai8UmMA6yIDG0>h{YWu
z7=6AvzB=@D^>j{+3-}{NYy0sz2kfXu)kZa2n==fvoC0TK;%j{<UCSA^M>aj*mwG$`
z$!jeuNR@S-M<ZQMP0rbghfGUEJZL}#bw#XFq;>NDnZ*D6oz=WNdq5|#8Pp9|2wtmO
z>fA*#sbkulvq9-A4MfOll20b9ECMF_!@A3oaI~B^+ZK9-B*1d5D!?sGP#F?`cSEn=
zZA>Kc>Su4}?j4o!;}wu{e$uVfQM}?~5UDoJ+U@u$4Qt&_&X&+w-+H|?26srR;&98K
zKSHx#_$G{5_{|U7@!+zogARKbmfgIxp8+uFf@f#)Z|d#u927&O_in*~o#|R4@mqqn
zjbs&kfN@hK@FS5vNAfw#!(cj#i}((vIWUl2Xr@wQMJu-PJ5tSDIi6T)Xd0X`HvgGt
zV~EqvI7c_LLEHCu03c!LwfB+7NZ^oEr~kPL9S=*zJsdabFD2&K=>3}x)|CD7O6he`
zbkzwq2a50W900p{Lj<or#ji;My|lPoNAQpmmA86__R!_wTz&gj`0>j`tLR6k5S7j&
zGcWNCrRTFt&!YLmtSBrJ6R13*2-gH9+18NwMXE&yB0|97Y-Xttk_$|amOrz1p{DLv
zoL6S;OLTny^;8TS$ux#@zaUG@P04tDW5&57+JV!=x9pe#56R`i2T$(jnJ^Km9%4n)
z0kFHd{H-C^ZEb<KQ2wA?lE^47ycO&m{hl}Da{b;2mAw|Z&7~~Yl6$jVlRa<&k9%i-
z?IEg*Qy>U`m6egWJN8<<-R9s2Nf~wisChT3C;dDR`OvPZX-%|9z>EXBmOtA@&GaLy
zsoQQl+o=F9$s760NOQO!8<@&;=&2O1SFiKO&cXB(be)HL_pg5*fdtF21-T)rO{#G=
z?uvptuL{sdizcTkWJ<alzKzh)@pd93GL#oDk!Y-fRe|`>_npSJNF-83J!bJXvAcjm
zQ1ooW415;lZ1ymOB`7Wk(u!jbmz^V6wrU!*($P_$hV!#}^J(_{^q>;Ge!s`pIEp|u
z4m}?dLLk_4L@DzzAac$mkg`Vm@NC>rr*7hpT1|`hZm7}G5%r~V^4rf(+{)%kKosR9
zbmOIQhH~LMB$BFkRwPpd0m5(p4pSt)dN@YhZkiEo$}cJdDl1@)Cxyh;*XfTv?sM}D
z-qI6Id8<*D*C-}RmG<9FzzvWbSM!HR{c?Vy-13`r2OZk(kDIB<Y{(k)1DOQkHPD&$
z9cFCjN%ZgR@{0D{bdT5TGTW8xdAk>-z6fMpM!>zLWdMRqzj0Fd7-X!=T*dTA<YRKx
z$ShdiRaL6KMSrB2#STxmbuyT082ZQtpYy><jSl5lRQaa|LKQBv_gW*k+L8$tr&F*1
z;%a*M#MADavPxapw^pL6Mvjp6wzNwFgQJu-i}C_Pr5J~wLzfTX$UR;Int@2f6XuD@
zL=$$%Ds+Uwa{pZ;*qlq&ZPk6X9CK3YWoTcSu9oO|WFZ7+Hln?NXI4?^oCdKfIF$Sn
zS90w2XM1%&cJH9;`j2sq{C@Jk2Hz09vWs*ob<uOMY99<`H2fYw>ijU9jh{y;MHByu
zhZ&-XC*2{|`{DA3%3W~6l|8wlLkys{8+Xb3NN21sQK`Draz*Scc&5|57&Wy@)G&kB
z|CqnKlPBt<iGO6}HvZg31O|u*6sI?T<zkte`))~3Qt{DEcZ!9zupB-8`he3=<%+R)
zXpY}eK&Y(Sxe@l|XAGh|pzgALi=Xt6CxT=)f=6YPm6Z<Ywt}JGG?vIsDwLNm^)`eK
z!e#BgWuMs<5!p@dih~F$KO){hKtKI4$ep<@`s*Xeb9g0!MH*Au`law9_c$CkZux^=
z55?Ti8j~!%aY^pmxgcilg+W2&CTk1J%sOrMQ!Aq&??g=efdn(mGJPFY!9J}DMeiq^
zH8twT<f2>yWcg2VGv_|$#t5$xkU&9FiI_YUL=Kid>X_?e$4eG3^c_$7_i*B2M$(9O
zMU3%w6oWNA%(^lTY#gsGzwRcZs@7<_9#0bTQOkez)?6oV|4<xe64)M*+wr@;Uw!Ti
zXv-ZpUvO-5IOltSRV?z?WDT^K^1w&|B{3EQXfj$5v1Xws`XRIMz>;r!9dgp2FTyfG
zCF^M0ItN==MMAXTE^pTG^PuVnHwueJ3r&0WNFd6pck>2=iiw-U5`A2l@XJ|8H^u=|
zS30QAR~cHw5F~Om!Uh#QMTOFYzEuqH>fvH&Ha@yO3lTE(A{!Sb*5_&+u0)wv{t1S|
z^@>#{543EX?<XNHTX$8*S7Kyv-5_Xp7IH!g&R^4eJi^=@;k-b%Tt*k^TE21s1qpJM
z%|A-e2Q`tZnj0*-$RR8DWW*XswoK$G5C!IFVfbINx#1q4q>23?1TEW>D+j-R!64DJ
z3SxLTd7q-m8kW~*?kAD+xg8@$!v)#jb)%(66L~)?gd2^b!WASO=j&4s1Se@4EEpK_
z69=G=Eh_3r-+doL>6_k@I)jaS<ig1{2gz|=q_q2_w*1FNCTa6PK+Xq%wV|`ko_Fn4
zmmZeU%X+QZaVfmk+mz107b7EyE;CI{!JvOrm@uo3Q8U1x&&sZuAm3e(e2%G_tuFU3
z#sFn=L5mnFUGQ$u9qo}ebSqYKUcYPFRYQ{#Xh-Voap3%R_Eh7)ycFq;4HS)g7HIvL
zQjyG(n<}XrqQeZmtq?*iRl4t8wUJ)-&j9LpW546JFJ@+?qRAv<$)pKY|6ETNLg7~G
zbcU@s$Dce@;vkpU9yguZ9R@v--`_(33ua=!bkDt<tM{KX25g|prM$fKtKu7E+D`;!
zm#;WK2?kd}a`xW8a8K!H@l1A|J^e?BDw=ZiwLx(;bo@0o!ou%m!B7RNm^-XML@I9*
z#l68MB5TlxJST8@7UfXhWLs{*9x`oo(*h0M<ingu6ois<g4uC;rl4P_71RI61-O4C
z`1K0lC<C@swfU!Ri%;}}L)3w>e3YWYA(iG1jDv%oe5F5jvUk6Sr5pIXK|B-bbog&#
zz|iyO`_d*K?qsdz7QGvPF+CJ8sK%1~iGkTu;9G%d=pNruDN!c6;l}yD!}|>p4csEf
zvo!`J(%@R7wrEd>7Q^BuA_%+%CV*w1EHCw>XN#p{zrtlit3J>zR?-a4;6?qvyMSuL
z0EIL~--iOBxM)s;`qc0@)6CqJKk<`Vom^r+Ak3!>*DHlefX0A4On}%-Q*>R8#7end
zpBOnhiUb{g!1c*Ugy6z`9qG+t$T>Txew|Cc;zZmLfHV4`_{;{`HT+m~Z1$P7{VYSm
zyowPLTvzS|s;^$UaYmwc-mW+o%~p&Gr6dsu%|+4J{G`#M|Btm(#2d}KO(~aD#*7>)
z1`Gr_v}dDh$Q4nv=WCXYo;5p_qhsu4rW2>kmvK16f2{+7llF#W+rmCQ_Gtb==AfGt
zzefj7!#>zU*AwT>Rv>I>i!pg3b7qw7r2Hkn_&;+jvm{MXV8Swz^i))6R4@oAd;L#j
zpDz^Dt^A3$KFEY75TX%!T&*6UI$qE;-<$BXLcNi_cF!P<crWY=;1N3`#I6{~(HKs|
z@s>Gj|JZP2*gJX?9|4}|20ZIPKbnfzGjak5*|E|Kec<jjqoCDli)Mh|GLa&BeL@z>
z6d%}&b`wPrzv){WpnmvyN{bo-*z0a=YN0BdGLBYSd`gHYM8}Q619~X3&x5^)ZE;6^
ztMFy*HHA#r>X#apZ(hmF(*M$e0N<7`WGXZUv54&t?v)aySJGD221_OCBj~VU5>Os)
zIq45QHi{kE=9^QXI6n=#-E2^Igk4F!o86dTHY1!@e(gwy2olK;<9&7o00mxf-A2wz
zG44v>JX!6*(D@Q)7_ULt;vX1v+~FM!{Xea>bN`0N4ys@|kwxQgz;$u~2T2g(!XZX$
zV)49md&#dLeRkPgyI}&`W3R4$X+w$q?|0CV&)a{n_+H`gQ_~FdRDY?4ocULf&_{K<
zBFYBQYb~!upAD=~Rp*uyA^bOikSsYH4k$dRK*Am=(}ViH!N)Db^jvPO`<J}~5QTx3
z5EwmVK3}zLMqj$1P*b&*qvJbs8!wd3(>{Bol?tr!mt4q^7BPZm@Be`&z*P{s@#C}a
z<Qxj!3^to|pFW;>u(7|i1}^X|1@FHnIFFFAv4E#UFT8OrLW|~S)|(8&e-8sN(Tv^F
zG0gT&hc{QJ9pTRYr!v#_VxWShV@i#?eW<~p*SfdzNr3$**^w>=8Sx<jcATU`eH?%R
z%BKBgh5O1!X#pEB$3wM`d(fD*X8y#K>1cA@vq3;fz?4<g&}H%~YciB65XM@C6`8?E
z)Rd>h73V43tW;$r(?pi`=P|nm8HnTKF%G4<8ipz~po^;c?(Y>Ct-bayj2d(DvTQBb
zq*Wa3LMC|MZ~oilv6)1&I5$6M#?Z0Hb!7gY^F6dNt$mqC@o<=HtR&6$gGkw+)Qf9;
z$-N$Zj1;czhOHgyVtrQW8nxg`^GP~a8Hx;F-#X~|Zu)MkZSx^rnSr>El3Cx-<^dl6
zsbegMPE|q9M>?4ft#S5L88ke%PY$Mh!7^!7fiRy6XyxmXGyLSziY9o_wOrbJQOT|;
z@&=Bximk10b}9FETWwr}65Hp;sLI|~qJIh@;#EwErD#IJZHx;BtFt(@$I!*&gR{H<
zTb^t9A&<HMJFL^EBOSV7q(Y3*Hk7>I7n+i)9?-)<x|r6^7<z>Q3)o&U1_r2E!l<Qw
zTH+Hu9lyX}dSFon`EPL)|Fwup2wAL{asogBq6nosKvzj4?c|kyd^q%IEKf)VhaGOC
zkZbovv2}EBlRvA{v)CGQLyIgSA(vH$-sf@YF55dVBf)+j?u+r?IZPZ|OpKq}ewih&
z;CEnL9AZ*SDOfw)O<P)9l<CM^1AF2L8{FQnwYyQTD3Io|cCXfkwh!;DG_MUf*|eoR
zdR@zUogs8TDaWP`45(jqwPnIO08qO|0b?fAvPk~m$TP8Q;RlaBp@R+wZABRVTHtiT
z*<s)Zf#&7G+<RL#KE}>K(0seF5EKm*Vo#_@oTj({Bc|RpF_6zO-<}Kun)DEdk?nch
zMc&_DM<+)X6Ljz0SAhY*=<0es;x;#U>%i;o=3*{Cfi2mJXx!uj+^BYd`mdJnxg1ZG
ze*?GEG_*7wW};51L3b+;Yo3Qs2qYR~BRn#)9pB9&w=om}a6ZsRym^E;-w&?qN~QFu
zYmGB;AdUG!0hKNphBe6+m<=5BJbii)?{#I&ceLP*IdOV&Ubhbl8~8aF=9p%7FZt9U
zSS^5yxb3cb>a-IGLorzmEyw|Hl6%Q9et_%l;5^;vjnPq92uyNt3A7>3_di23^!hU%
zY@3+>gLH^n>~<ysm8GZuntF)nQ8@rOEg&G#Bo?&`!e@^hV+98ves}RB=5KnFjA&2z
z>mL5U6>AiYK|iHrwsI>>=gZcBfK$<8hTkLtc$E9w<MTg=Hb8iP;6fL+ZmIMYWBT+a
zvGD|wC1X2|DKCU?qvoF1U_hpT=N}ED7qs>$ur^dmT${q{AO!pvnqxs28OZ>EH`2TD
zhd#QxM!~TDY7yhTVt~ThL<DW9js5TU(tL2q`5L!581}Sj9MyFZ&v{tKO25-po8m#G
zU1Twe{=TL;^P|S78diA$m^m%ji>!*MtZ*eCU;KL3%AL5#ZVdR3O)Q3MHk5#pjsZV;
zUMI66E5U{rhz1SVA0x*Q8T4^;sRKw%&wE)Y=1BF%E=AdDo1pvH6Ngl}iO(yUI}zdx
z`g6;@XD+7B02kzBkYN+9{03+Ug~CNwqLgU!V0e6^X6<oQFG32~#$Akvt5~am==5au
zYg(aZBBS6TD4{eTt-TE;9QbW0H+Gid@iM?T=m#~~BaUyqecltt$_mtbChu566mI5^
z_JMe~BJu1x($f*(uoS({fo`J4@0wn2vdreSMPkfxn7h71!!2lA>QRB+!LmKPfgKOg
zf?~Nn0H2uCP@)9k2wN~O&z49ET$?8=jo+`VS@gI2uc&vAcY_8Af_Fd&{YLfkX*~Bd
z)DVTBuqLaPPA^L|&a-+yGc0ni6S^otfb;`p<A%cbd5ERY&enTcVO8nO)xYNs{0?w=
zvv3AcYel`#(m9PtYBe&(ga8f?>lPnOnoknopYQo`#Rq3_YrK>(i=~V|v%Cy_9$ut=
zL;S$y%<}gnVr1R6_uy==)8e&#Wo97=<iljEQX^Nbsa<Qxz$Mu%$4q_W-Ah3#d{)4q
z%vRW2za4&A&34mAj{(X0yrKj(cSZrfjr<cJ<<2qB7HUnzGZ;jy)omRv|8GRr-kk|M
zlTsUqnp;A)oSd`=IHnENzxRNBnrRmT?R7<pNnp^f)>#)+ss=!=(OB@ZUv2O}8V+!7
zW;7yK$u)^?BFa{(+6spS>XX=yw#g*Br;Q#ctA#rxr&9j*dCtggQ_tqNrQ)~lI6@SD
z=mC46^=~D>0Z0Y0rq9;B--b_{t<u%4?G`)=11JTGL<VBXY>_*$NQomts1PCH3>!&z
z4qXT6(jiSXp-ST$d}2F$1%QeH=;wC;^a>m_24k}@K(Y#X({1ZNSW$}KB(GVS1Gj^8
z&fXh9rLtcCidTbV;c6)-y>>Sy$c5a~t^&#p7}7r{2`YuOzlP}pxZMj`z}P9yX}t&(
zKkF_80Am~K=c~}j&m;mA@z*^Xw3Ykh`)1a;)w4}EmR14a)v@V(NepO3PX#5wM@-|(
z<F*@jR75(&^*}H~p(Z5%aa6^I60nR%gFBSrwHOR>N3)L!Y)79*h5tONfPS@DHu(+j
z+fhyXV5YqL9UvYDDXJGy%5w4la%Lmc=Bql~+6hdTRqd*h4C19HLd`bO;_y4RTK2-G
zX`vhzyFi=3K`?L>vweO!3QBERq1}Q_3l)*qG=t+piH^)8v}vRf5_ilp^Kv6UPJKbL
zd-GFAi?Cx1q&A&n?*6=FOmRC+eoW#OuoDGCKl4mU$JF5!bxg`Sw2CTK>zafJ$bJJ3
z@aLN7mCYYA0CsfNYjoi0hav(og1u!`CV*ll5v<<^CytuOl3dFC-Iwx0h*_xxDAe}s
zGyO`9Yt6~pb_CRn*CWH07Q&bvXav`E>mWfYS68=Jyx@n8!HS`)YamgoP3omHk%QZG
zWc}D~p?O7d#rT-ZuvxHV8NaiylP%(*Jn~)CQ!u_+#5`QD60)WBoq@PJa?K=J-K&Pg
zc&j+TT=b@#kGBIk*rx?~rtB5B5~tXZ(!K78WW+fBZh<|#mT1o7=Zh6`6m#p0<szio
zKRkg9?7k?k5QBb_)^L@&NxnlQ>`5NlI>Q~^)Gk%K6($O{N1m~i{Yj53Xx|^rV!AbX
zU5h^7u1NEx_o<ruw^L{TW0jQK37k(L%<&#YvjIAH+jxkU1(zlERKw_wT0Jvl-BhPn
z@8;(nXT7}^K_I~oLXRcHWztOk6G)BJxZWXAsQQ+6iUf&qtDVtu%4hOG@X#coS^G+U
zUy$35Cv}TYS*d6rI$psIoUpj??dZEUes;mY0Qks6!!riT<?A}(gA3U_-M#xQ+Q4Tq
zjlq|zyz(}NnlW?MSzz#$)4PZ2a&K-j;wRDY)7|ZG-eoAsHGGMc4hl}}U&qW|UJ{Zj
zBc<b>HpK<4P*?NG(0kc^ZmT|zf@nik{=BjK(zk_mNM86j7MvZmb~y1G0cubZ4Ljax
z%sMpFJmpBg$_iPO;|nYC%cCBj6JjPIk}K-B8_f+_1wZKe7JJTcDH~m}zx(qMu`31J
zn5LCP-l^5Et+4RLfST0`95GYX*Bs$MMIcASHv!^>i?;KpJgL{8AD+g{77$rH(MLb>
zh$tf|GtD5X8r%uz9rWERgBQ+n&B?lQWe1||(VJeqW5th_cdX9<VayYFq92pY%1RXO
z_=|e0Ftx!~lU%Qq9ue?Lp7U4qNn>PN)$RWz!-@5|qt$lsw&je_)y1ALMu$4ybIF1X
z#h_v!Q01Fqs0o{*;?W-AZ?W}Q?rpJhEt_=t0{GF%hrgE58<$sf702RNHv9%z#vr+~
z_J`;lfOjm}@v<6|8J@mDkWe-^u<SRfohJDDE)sc2JjZa3`I3y={15B*?NvnUytgG>
zbf*ZFQ^O@E7wXk)X}~c@E9^gPN6FV_=jG{^v;Z_lIXZB)_g>j2ibS4*?%+}`?ek0}
zldb`UL0W0#hho+rj5R8RX0ejGr2b=VNVEL;h}o|qH&-<RolN1Txs#PJ&{XfjD$&8b
z){Nu7TWW*7`kkxIX`FQLo|2iQyllKIGx^v#H(u9_`cv2G`OFnmLJs1b+~w`fe98+!
z@w*6DH>Z0U%zSrZQd$$I*i<og>WTrF-$gI3g(G0>#)JbLqM>~CrHpV0L1^t#DimSe
zu6<vGxPHZc1{9g*toK(28VaLjG|tyI7BS~S<I1uFtkb$^ApYdfIVzhU!#LOYdNlEl
z)?1jeEDn)Ve^Qsr9i;ATbSa+i=9+w#9JFf`rj^mXdGwozi4j;AM{s3vsgl8H3(D;^
z#b!2^yY3SzC_a2l1`{YJ?|aeNUb#PdZ7M|;tRD!<=SVg%Q!sAzRRO$g7aY6-MSfZT
zWx*azb3En=sISCEk9F=t$hduMhO{5khte+fD8Y%4Tp*>Ds`=wnqBj>3D{{O+a0c@-
zMt|5#<-+{Fmel<b0w=>r4M%Z1^Td7)U36o^H|qokD4I8=ot#wR^w>&0KYz!eC81$2
z`EK=q?hV>(Ilj@-A!mGU0?uMe;>j?%L&*?aqnirLG9{-MvZcryyFat_5D03T!=sLH
zsZ||SDAj*2s|>ZpRoV7eco>k{ZQ&N{)qlq_B%d2Xh#=_FZkkb|#RIUey`o!GSuI}B
z<)yeri$-W6<#s%AZG5wg?=n0Sm0V9fkM~OH<>Zj?Y8Eg3mP!<zqmJ(!)%Ct3N@vyZ
zBee^Q7Z5C*8}y95OvNP>b9>&jsFXwhouroDjjS|xcEgypu4vA3=_toH_#`N6<4c^o
z;y*G_!38ODbKHy~iYprjEC@)}bHE12*~4W^AIVJBFXfqvJ1Q=G_!90vT&zq<tG=r#
z^s&Z>WJp3QV)!%VNSRY+BEanykY&)<%zjyItUvUtR0}u(D1$d}Qw4j3<!CzsTTd(h
zH;W_3fY_!|GW#a7YKIM?+}3BZ>CS9P8V!&|7Z4$T0{(k@G}NZFzd8WPA`>`oTR>+1
z*n8Pm65UjFSTRjyg1<f6mail#0c@OVnuHxr)YQkTNFcWAZ?4BX+oW>O2*!9cU^o9y
z_`U$N*8tdfKx9)>hu$Dyd_K!_2>!o!K$N&^q#EHL4HPi6KE2;J`*$V4OP0p}j(-8+
z`{I%R&Q$^*7rhz)BKrR%OW3~E9mpo}pTx=0Xe=ZMr*{00SR5Dj|2s(;kL>A{0_tlT
zOVt>^&MIkvt;3zHv_(krF<IsR|8Dw7{{aS(c?^)m(BSWtN-6+ChX*!n_XcyWw4=>E
zvOJoZnZW@e@|%IBE@_G({54L%NBJkVClz0RW<0;$Q^R1VCe~rK6%YY+8#DIont0ZC
z&{hM06||Ke*HG7FXp~%lO7SZw9F0U#QSs)k>dQv@X}jpTB?d3F=6|Dk3j%D3=TVa3
zfvee&y)OqCX4BviJ0;i2pZ`4G9tOBLgByIrz&!4LJZx$4*+MoB*thb|^Kxw6-nR1F
ziW7i3H8Xw>1Pq9OZ9<nff<&HMEHe8f({Zpl*d*k4y3awm=5{_gnqJpZ*KG;RtB?R<
z$Z$I6)?$+bT{0V$ee;s{_O=f0O;5kMV2(Il6c9G)Ie&rVg3iV_X^YbR!=p!eRi9{<
zrPT_6NeZI*<Us^AnglUFar%~d%xd5{FU)v-m7<b|e(OkicScBh^`9bke?fjz<XR@i
zOq6_x%5rJ%^osK=v235@o|EYRvG*NZO)XKQC?X077J5|yL3-~+L}^OzUFp3Dgx*Bp
z(v>P5q$V^ep@*OdNUs4Q1Vozj8UloncewX@zxRH^Tk9KGi$ii|X74?_&z^Hq{wgr(
zOM=c<cF~4wG;2I2nKZq!=Py=g=Ino^$LF<L`NR|hdQNDQX7+X($8bSkgO0dK)tt}}
zi0E~<Vmh<$tsI$BlltquUf~MfE_6#$H=GvlvEJwK;@?wbL4%mGeZ_&y%~clFog>Ai
zUbctjl+6@p;n6&*h1M)fV}da^Vr4=Zm2abo@6kt|`MrbyFK?!Rrq2rW6vW4U))@%B
zE#-FoPF#7u)p&(XYaZc;G0Ehf8$k;N$aUuZCZYDs-1pXuer^|n4kD1zT8k~xp5oXv
zG!;<IG4Y|BaU_~Bu&yVvOKNaT@Yd$lqLD7ABGBIHLoCa#1Qj?=53<--MmltA<nb(G
zIOSZ8px5)!T(j_8y5Y}rv^j;s?~FGTTKd4Alaw^>!wQ!u#hA5EZQmSeydaQ5@EXvE
zFjE$7a&yF}7L@agg=y|2@=QC35(J-6X3fE#5KNLxMt*hrOGKmK*m!eE)61NrY4Ga-
z@NzQ(-KQFDx<4f;-(7(~=?8@^BQ!(jeRzOFAFWs{tNc0*gmk4o%a{4@(;vC658pb|
zR5XKXNqQwa5?QWYnGeF<3OZQlI60~xQEI<T$>rWkQ~T=$4gb>~2SVq`O(RRoF8lo8
zkhgLTWlW8e!N>E_&G@mZ50Opcpf}<_c1_<UT%N1{OZ*T6$Gswzrf9s+E>cYqP{e?^
z@@jOOmG0XO$SKo<B3UMU0aE!cM@#<sZyLOOpzj&uv`?A;g`{sEQ%stXigs#wS}M<r
z^o%z%)pf{~V{i14nBYA@!3q3Kd)~*tV%I$l(~6J?P~-sLE~u~3W;<0yd+v#q@{X_M
z;njD~VxP>XJehxX^(5q6=@I#k?Dux8|ITiEk(IxnV~)8e|J2!mlU-X{_5jy(9dQJO
zRWLhN`eT-SQD)=}<CL4vX21&_{Fg{IXsNx0|D$O1i%pCe8?MwnI{}fnT4qln9QC;d
z(S{?up4<Q(Gbm#M>+q5V<B$wUHQ-(3c_JFNHhR^D(H$3VZADWc?t0V^_jJzHJH)kb
z4&6Z6NbaoIx+E&%+QvEg-|VWpxJBNo`HtLyvo<DHFupPEk%4B%Nf6(ryPIf<{IUFX
z5wX?)>~zflMHHUiZ7xnY!bO{ZYT;sfx59|_Lg9X*4yrAXzaDk|%NS9{5!Df*8i4WL
zwP^%TIZG36Oa3t0lyBzT4$@pPIexXLz{Zd;D7I~2Ul2DCZF6o?mW?ZTq^_ersImKw
zH;N~=(wlc1n-#c0XMT3Tt#JjVfS#4b9b!V0XLc~|9YrR=C(~ArSsSap;=)Mv!Ql$2
z#rN;!!YbTDKF*XPx7P>1?TvILH?-uzDCW=hqGDIJD6tCOSu@k0R8u!dYuX`JlF`nE
zRp}RB&Oh(EzRD^N*zcwh5zJ)jr_-yS8FPkzpC@)}5B1^1u&TZsy-GkpP==iIejsd9
zJ8&o?>$!MS)RY$m%f^x2AqZQlG~$66F>alv2r5CH)O$Wgz$;G(O3AMPy$Ir2{=VpZ
zyy~Avy{e}1AkMsF*V)li+k%{5o`4`M`cA{;Z3OYT5890`FBnZb?DcqWF@NNwdZFQk
zASCd}ftt8NO=k3ev!s@Sr^LllXBS`AKK~mi0)Y?}6QI*i%KAFB@h>$oy3V!}i)8n&
z5C~KU!1CPY2J`Gr>)~Fz^LwS!4;}u7h*rAmBlkU^lSFm$H>dhL6z73RBy!`qHo5Fo
zf>%LCGvVAO4JN$L_kXTU;cov6-GjH(mpx#W(AJQO5((z5)|0c|X)rl4fdo}hXy@a`
zc)E?Vo0p&v5cH6bL;*8-%-)jnQAuWtjXo*mBOq9+oN*!Z1_~DE82_(3b)$g}KN}d1
zx=pJKuMm`}mLU<jE7BTka8Oy1^uU0kxx51D<)EELwT=Ok=9ia=W|SqfZY^+dTMM*=
zP4&&z9bj};bzK-{9@`p>Z5)>yNzSS&oe$VlcXhkf^y#_4WXa!{d#Df^s9Xm|(5Osu
zZ_?w{EWdpm>Mj=h5Y_Cdc(c%!p!4zF?hlu*k3lv2>rMdYy?V-LT*{4j9+N3TO?j)T
zYAPny$%0YWcrU>qSn59TpauTEFNO}~Rhzm0Uhj1#A=K<qX`>qVy+A@}o}cY)M4K3!
zpB@2N=G^tX>l|!tzR9r3YR>;3QmKCvm`&Bu$!87lkf&O+s%a>r@}y9?>k4YmEn&m0
zQ-;-CiKsGK0EKAfe^=c=XZ|Z8Fg0^Bn*sMGO8ElSgRFbULqI^=a*-17H?jg&djG5)
zL8k=kzbnt39(%crSfM-)Yrh5xV2x5gN?ij!ArLSqzr1J9SgBi06}_%X6#147jNB=&
ztu3)A^ZFJHOePV0<KOiqp}HghvjJFNv|faN1mBSS+=!>#tjb|!ipdB0?($0|$AW^$
z4;)LurEHmL@i9>|W$_v|Y0m~)Y_bHSv8RR8yOKfI{i~2_LZ|qI2$jGk1dFPWV|859
z>}g;^f|vP7$64@vBTzSj*;L%Y{?y(jRQ4nLVY?JR@{?08|KwuL%F6;zOLi6nVrckK
z2^C_U;j7Z&E}@ICeAGMA_ffX`xl%vlI`l87&eV(fBKqtGRr|FZ8)l0_*{_Pl>d54L
zynkmYScjo+#8*AAPN*($dv|KbjAo@HusMhL@SHpm#3J*?AX&X6r1#4m7S<~DVv(7^
zHkrXUy4X>ngtW?SNjGz_P0HK|jaXXzTy<zdrOnd$$ZLb->&=><RWGI+fh&Kz+expa
z8->)aJ1`}!-W5-nGqf(cgUTS=lbqq4-t5$z5*}TnOj;(HmtrPm>x;KxVA;zISGQ@u
z<Dxl*^N)ebCRp_f6EfzzWcl#RFoMGDxqBWJNn$AKWHVKYBpq5YeGb>wUa6{~ur?F(
z!$T?7P5o)Hr8KL|B*t3@T~CDL4ozUehA=mbFn8?oMWu~Bd;mAz`3S>b3_KsMxNR+X
zZBLqNVD?#0Gg-!*yxa;bGxR{RrD5A~E%WtozHZihD4)^bj!r8^IHIsVCVpF$OR{0R
z@B09*t$wPX3xwSOjrbNdKk}7<(;`!9mHM%>_kDI#pt8m#tS33~Hf=N8AgoQw9Y)gl
zmmBoOaqQWv_?#bVO6FyoF4lKvysu4jgV}nW-#9PjZnkQ>EX5#w?Nbw1nMdZ~*F9Za
zwr}i2RuxaW!c#yy(!J|hK>$awoI$2Im`^d2ld17PhY_?zRxNl{8J_F?+onxA^ceUn
zjU`6+UkS_pN)}VY`P0X?383Szg0v2ED^$e|!ILn*k3*Puwb-Bi%-ws5f(K_gw-eSp
z6arNo88Ik|iT05MRXqAdzYmYx4cy?;EBLMhZM^0C>9tQQoNqWojFQ*3W$qtFFk%vl
z$XisTdw&uqb(IQydfz>qVCC%f0=Wr1Jh?<QB)lHg<a5^N#j-~j9W3yD7yH=}G7PGB
z&u*4}JIcel?eeD<Ae+tkYBx-o|80tc2qAr-5c`acY!lklxWx0JbCt}!)rRzo_{u@%
zX{#we>FMV!UM<vv?xcG`{9Y_aU5q1y<QPIR)l{VYt74s!I<KO(Br8YnH6m4^o(yzQ
z=9TNzX2p(Y-y7ZHkz#H#mMbx5!>{ayb=<#hBgOLi@A>pCFK|>qtjahnl6PrDjBfmT
zrBm~}-SApu-QW$mvPtSR3A-D~c}xyJ4+~yurEY$hBUQr?kGv7<Y+>Iht{bKZrx-rb
zr>g7qWmAP|Jls6_d@c}g2%_^!W}{LQRXxS@WqmTM=_f6TjqeL(Xlg8|-VC960SY6o
zCboU4+Ot3Y#V_1N=&f})5H+ikyr806fiD=}lXBP0Gh`eaPzd*;tklZ<L1#9UeJf`K
z(!>2d%Wl=SNKgr#>4+%hz{>63h$9-xHJzN=Xr*V!rr;^KKONoOVVO>|9O_mprnP($
z%qFJQ+8ey~nT|hotv!LV!OJq$K8Y=}^Hef*KUV0=ji*6989pRMDpOH`a>BG?)>r+X
zH(|Z_IR|tvFb7I`l}n<jEU7DoYW<-R2gRM+=f6(biCEWDv^Uanr+%G2kL>=mMNl{t
zaqzazdO%Ax^#~@<lHN&?s}vDW!^uM}s$z6jV3o!gO+px1GXAP?h_KFLW<Q|Ykc+jO
zwK-pisBCwbUNb~%?&h84K~l5c{rKb`<hKVUB={>Oll<uKC9Yn~?a%CX>PBzj2Ho^1
z4&u97dn#MMyl)A*D#0F47niXq=%gG<+04>HFU`oH-0dXO6s9fJ>U<{<A8PEXv_!e<
zQx;4k@utiVDgB&0kcVNQ%H|rsoSJpOU-ZqtfA|GQ<QSvk-H;3(>a2do-$HZ(-voVB
z2(U@Kkn_?k`cdAq2RzZedA=a&YuK0Zr2uliX$WLQLs~!g=GP~>_I6Z0fg6n!dsef}
z`nQ-L1g4hIMZYdy$X#kxnk?}Q;5hP7+7G|Ahe}vEwJoT~{y^K7<WQVH+8oS4NDt@N
zTsq0j%dy^4Xbxr}B>u;meoq<7;<yPo1Mh_M%4R2*pXg%!I?87C%wZbJ$KFYaKd%Y)
zlp8%Bptw3CqF*zi&zRsL6-YpEtnkMqURtNHiD3+mP(6wM-4~o%vzg}N32EGO_1sMD
zTC?;uI%95j&&n$FEm85tAA?s2lw%8sE^Xhd%DwB40Q-inl+|+ds{Z7m<JVD>87WD{
zy`p(BMEjWYT~=0hn!1i?6S;soIRSy<(|@Ln`cAuB-sZ9Ow+B~d&d9L=Y9o0;gt4sC
zX_`q_pE#Gg9{;3JZ~W+dOYuP*v42O|ObHQPsJ`|anH{EhK`ts;1Xp;x;D+}-SND5~
zS2bd-T8ed`kk7Zd60Ljy2P_7AWGRvNkJ0UXf1<!S!s_5@^!U<c3ez2d)OHlkF26f;
zFLs3VtQsT+Up+A7$q;Q5sVTU9?Cwy!E-dUMc26`Lw8qktx<;34%DFlB)VTXChjp<;
zqlq!bXL}=73N@_ld#CdXowZ(WrSls%rH<XuH=Gc41j6Z?lh4PYO}3?*_b*9ArrKi0
zytWqD8^wO<CKRx#T@ON`xMEV;TM6UC#+K(^g1%cdLGAUbOsHa)V5t0D{`Fs{5H5Dh
z4*O-gqNl&tw}Q+yErWFOdexUz?*u5tt$fP+$m!Ujr}gT@O|#Xiq!KJ#e?W*YTvN!~
z1shQ4^Z6!Kdwpl3;?=m{m2&C!{Zu*8tEVNmzyR0p2ZvLgdOQn;P5Nm0N<4z7)QBRx
zuapjau#u^-5;Ulh4(T#i`040aU0lXL*|6Xy6KZGCvAc<*kkhI_F}o5A>LuyN1q9T6
zdb`%=z`-%Cu7h)g6(TgeCsAGR0b=B5YX=AD*um`;dK^B@Yu_$)a>+<7jbF$Uks*=^
z|Dg^zstJNhA-4fJhwkQb6U0B^-w^EExm}#@-wlvwTtt6zTe4}_r?sw_$0MF@Ns>5@
z`2x1z7P=Q)RK`-X0VYKZD(lw^*S8+cc|i=giq;vU+^Q)zX26hGj3V{;u#tHm=IE=p
zzHs+G>D5Jn_(!E>dij~N@;3WnI^eRH7_pHm&HI-w`A?%m8BHj-wRF`^L{gkr{$~$S
z=h(WpR2>^Hc|s1r-eEQqdI<^YWsZn(Hht@0>ua#92PteZE>b5$PqN|{w5I30wMo6$
z{Syf*QqZcop<A^%fswC;lZW-=T4l`jn@4=jkAq<X<`Yl-KRfZ#S}HuybA{|Mk_jtu
zr9F)N;-~5L?n}bL3~_XiwK+kj<D!4wBfC<)%2eARK4$_(+3Zpcimzk&?2Z6g?yEYv
zxH;l>Vt>uc*{)Sl`UIN5V3nYH(b?fEiqx0@Lib)rtI6&71%l)Am)afTKaiWk6T)2N
z5<Vn}Q^F}!=6Mjv7B(2Ef7LQSziQp3L`DDX-hDDfqDYU=mO?s(v}+R&80jodWy1X;
z$O$~?PZSC^mfwB7DqcX~G0ymtT@0Ycy$Zmi)u=Cd+QK$+NU8iGKK@)li=Jb{M>>}E
zy1R!^Ln8yg{<%nw7|Mj#&*KCb+ckS=i8^ZB$Z=ox^n;3eop<zK#K-65a5}>nz_}h1
zft7Uihf~-BFkLA|%JcdS6WX-??m+`YfP$ly?T{S9z=Os@EA~L#ij%Pc*yWch7QOgE
zt_8}ST1Wimd=$ukZTK8ZQne1l>y<O!-haO)G_Bdfwtyj?g;%|_d(tJGSGs1`(AqxR
zWZq%`%1SA(fdR(Z=}qe=B#Zko4xv^Rfahj9zA~We^DvNsb6O4aBIg!9%-G{&?|?Xy
z&#de7eL`_VMJc~%@|&>xDpV&r6=@%2<eucmu2`+g-98ELhi-JW!4E^G;hNn#+9?w$
zt-ecc3!t<ZwPQJt_txR+qO$TurYxv+EO&{MaYX(iQ%JWOqHk--!}SxWpoJ2%Gto8h
zI2Fqg!S49l(IU^@CKUw&URGpcmu)qpdz*ecsGv)h{9U(J-WvC|*MptYJd(mDOipFA
zjM(+U8l95jD)jaRj)!K_(RYs8DdF&R79&H|FWvh<eosF?ch)QG{ZsH~`%Kj}_}tDR
zYDN#*mu0YfBu{~O<osry*xWY_yI@|DE^D|p_;qWz_Mj76IMZZ_fP9$zjYURUDRk_g
zxs?%b>)y7(tB25*8*y>PL|ex4^F(o_lWf3=Rl4hH{CshWGGw%x5GlY|KQC%n@cFKg
zM5F}KuyKzld86&wfNexwASa4~`>CnxlD54_y$*0sdX6M%SUzha0*;|Zg_QjP1}G5n
zH9N-87WHYIJzA*f_0I~u>T;x4{y^ZahHO9(ALUi5{+WD*TC>T*IF5roKpcKvG4Q06
z^~k-IV`kU6mNn(XGZ5t48Y3e3gJIV(3({nXrjO5^(cuj3TysZ^8j2p>G-34eq<pM?
z*Z&KF_3bIn*l2mX@FH}dZXIAH@1@OjB#7_Wj_gmlC>@-mu9Pl1x!SIsNDU>jY39{j
zIr}+PJ<%UxG&}3^n?fF!_ErJJr>vS&j_ki6>o|(!hloiE9-)1uWMSCsCLtuRxu4lR
z;hmTX1sB|MR`CU)nL=&BdUs3E)Pm87i`VX|Y#H$=@z@U+yT;QAmIXwwVMyA*SqfX=
zs1tfVssk?`%E3>25&4voeZvR4O9)o?4gqQ3liVWQHZYZUvbX##=e6#yKCE#o7?*rh
zkH4506a%!F9W|C^gks|?Z7aCIEPwRWo_WL;m#}TL+wNK9p8b|)0~xwsWi|!xXf1?K
z0Gfcdrl2=ZiXSd;e)y^kHNgN6XmigNQD32n<)VzrUrzd@0<$<~5Q3ja=W}}BP-gyy
zrl=mE1y(J1<b5QYEPC8FtzyM&Ds%~#bTrl`j%~czZ_6u}Ig*oA(PSuuq$FjBok44s
z>n?^88bgk|E_w^gk-AR0r*!Q1C?0zHDR8f&8(`4f7vQ0C2Jpmi2em1z1(K{N;POfg
z(E|fyq=rLZI7xw6S_ulIp1ORi7xWlc4ljm|XASJKXEG&&H*4UT180W2)f*h4*pv>}
zojH@Kq>Brd<rRTkZN?c`gg3?SqlYl`u_;&T3q{M&rh64FY34n?Z`?FiW)~B?7%Ffz
zrvNVz<h*ojJ-l1wnFC@~@AY~ZwUSo7S{kdtpRm>HySvlHuVqz9M5u9#bz3IkCOP(#
zP@>t~CK%-eHt}VN-gw^e$)ddWWz=G)98;mdqr+P+n+H$C`rHXU{lR^$=z}mO4~OL0
zTp?FUJz<sPZ|j-OEZ0c7uB=^uV;q_)6@0zt1WO*mlnzZ~{}_c9!?7}bcT0ZMm*=iS
zp_pYy%=Ak_U%Ddeo5J+&=g=~+e$8~c_&H4sl{DF&TC$)8A7N0BaApKU^0I&UTgGDr
zRm?)e?#OoueRy9=zT%IU$?<*jpDXqGdY?F!)g=v_CAhyiCClmEs>~Sh95s^MCWKkA
z33sY5-yi?he+cWK0?8~GYJGPEiS&+$HU*EqMo)1yS-)Sij~+S*`oQKB(1qem(4G0Z
z7x<wxW<u^gTTCU>h1e@yZfB-y!8euHe(Kb6tB*f06gk!V)jao9Lzjdo<hZu`5jX&)
z!M7I9*?)npg2tw(gh-t)y-M!ERg`QANd=9*TLT<Jf=)0c<{?^&iHdt>(KXw|XLd=_
z0alCBZOeA}>RI{CqymB7%HS4|%Oc18&Zjc10Fmn(37Slqpl4CxZ>c@oHL08!oq-3T
z1Np`u(VjP=uM#9SO%^8814D<UaH!sOt**2sKB=0Vb1O&Ejl@#t*<a5>AWSMm%4j4$
zBthLOSHlWphTJOczTtLa1b!CwE+r)2dt5dx3$VyRZQxR-vT+DOr{B-hhroy)0X`<K
zyq0iqOy*;%SRy*QZcm;O%(8!8vV?Zqn3i=>$!D=_%d|s9mAe&wVI+InjMD0;g#A0F
z6)PZ38jiWLVYAKWu}S*+ghlJ%$Gkb2)6c3(Mbx1{QjTGO$<=nmJM`1@+`K?*XUgtV
zy(_(Af9D?)(?nE(*n!JHO&LW+@I*srfKUkl=BG$pt9jKz3-|5?<(OmEe9apto0Ovv
zbo4&cFE!l?L_*#p=R#fExb1CMpElIFbW|Y;?2DCLFPHU$B4IDD){~Qa6zT|bzBExu
zy7eIp!>p5yrf`ss50VKz%LHiNk@A#px=k4q-iH!8?Ia{X5|PST7x-4&^%j8!pLA!o
zB>)70#v|vdWC?@2y>*Td5!KXZ`?Z-?OUI~2vBrAhPeq*L&`p-du}gQ3NV+D6vVN@!
zOA$88tD$3V%ATG?Mn9!)>+jae;L|8Kp<DQ@J71{|4e@=h-GrCRd!&?Lr>#2p{#?~N
z;L?Bfh!-RvCg8}FeMF&gDZQ`cVVnq-g_+UrUPu-snnY34(<QCgp!;o^h-w22R+=Pt
zVKij0S>6^$*gPF`WF)HJ_d0e-BiYIJ{raQCzXbF6WIz@#NaGH0xU#l#gR8-d2dVS;
z@<KohZ0&PR3sRy$$^+Bx<wDv>aEA*!H#aM5A7^c0z!)8SpM-|TyVv(Gz52vl5!qmx
z9RiOmj~wDlDDM`75yULwRM(X{+*3<+oT{!ae1D{lo@HUmCSmfM1o2Nnw;S^yhG!bA
z<ElC^_>7LoF{V{|A~MI^EP2f~TKQ||gfNYh6EsCvIzc6i&B?_DQd{eTx2!DAb^XFU
z%*}JJPNMJcxXqd)<{`W4L-`-_`nL!qI>tpLH-MZmAW>RI&WO0mqfQBLN>w%1nD^ba
zcI@Wv-jnh7a%<A`ZUq^0LsOpFE@TLf2Z&Eq85nNT>AsAQ=)^z;e0v_-)N+%_@a8>s
zY@^HXhfwF&Vb8^x0S@O%xko}uRN@HHC@T3)D}VKpGd&D=1d?cbBA^CCL#~L@jRQut
z!(0(1rL@k8XFmsobvV?aGcQteHnQmmIBx!(03{&k4Nq$rj{$ydm`|FB@z~})V0Yt<
z|IdYr^dSGdRK}$%UduIlRSqCei;&wvbrF;HrISw2oEj@DWkV41mx$*?UhGScEiP~P
zv|UoitRh5b=4+{e)Z%MGO(hy9qTDJ<{R3aS^SG*pu>|xyXsx`Bm_YHhf5qQPagV{A
zcUjku3HarVa!-`&B#NJcfw<4>pewrQW)H2t6A@ia*|yUDk8O$kb5U(GeQ^lJm9Zq*
z&}?prgQ{;>CE3c<u)>_liNn_?z#zmC9LgGMf-2`r=^ChlHJ29zHR3l&!z+E2z~bjR
zt5c5-UUX1mlHR$xM8<CIO)qSosNsZ3`l~v&O|~KDN{+ubGm6=&2KXE0Pw^rC+G=eS
z&~<N)Nf+|GX0Ne0$U&TNF!Ebt0m%1Z2HKYuKM_0{rG|E}l!0^JTlHcSiqY5F*};3&
z+~?0R_#}~G{o3j-(Mr_II(&pL{I-KNw_fGqF5xzalOac2Ysd0e#TeHBk_*`EN~SEC
z$n5<hg9+E*Pqs8k&DaTL{A>HA8}<qR&UOn$Kq+tbB%A7o-0^-BIV$q0rniIEVf&;T
z-W+dcuD5A7doh#z(!`IEuF%-Ad4<l4FO<_vmpGghe&kGCrlO`w<qk%&XKAOd)>Cl)
zwL%k@Up=6f5cOegH)!5588TD-o${cCI%XU^82p(=eYKGS)aJvhZaLZ#^HwI4m|Fv4
z@jj2MM{Oux%uDLJD19FXHf*15=H!EzMQ!Pi;qRqg3&g)f(ky@A8DGh0S~wx%IBY*H
zhF;g6OEEOl({khH98$fQ$37L$dcPi}XbD%>HO9xEj~Ce+vubh;_xtHTS2ag*=F9jv
ztqRpd-y4F^Xs*;<{J5TpeI;J)>?51+7%A37nz<<+8EYk7B$5$)|AV2?`<MB+`#j~S
zOf9QeY@=kk1;>Y*rOPyd`4>eA%izb(@-Ss!-E3x~rO6-J8HB7aI`iEd?0<&?Hq>k=
z2VO`eAB3j$2&bsYX2`K0yfn1C7Mxtwzpy0tIw|TPVk)oq;I(im*XEw2YVsOJ=|Gas
zG&R2!{kWWGJJn}6^Jd+yxcnlo10}LqFO~6FT9u?fPG@$&%}=F=Uoup~fV7TvBjs^3
zx=$0CJOtMidfw*`kCXSZ&7`P!67s7#A^UlW>cs=AB`O=nrn37MsZ0v_%Tzf{p8VV2
zf8g>b$l^r9<2R2}k8NC}+ZJDEcKS15)E^d|V{NK-{m9c@#`Wlzy%tX1Yv$2Oh@>rN
zUVc&YM7ZvaAIQ2*t^H0r_eLa1Y<+T9s|<Ih_X#F2NuXnSsDH)WI3=Kt^`i;md&(_4
zwv=GFs|@$d9kU8rO$AS-1Exk4Tk6|$<-K^(y2TtD#vYaAU%0iP(~dd2$`7~f*lX~@
zu-ry=f5%VS@gRD4jj6?E>xtyz>dFI(<-kbEK3~7a+|;y3e`BoRsFBwNE!Eb{`_(Z*
zR#)6J5l~UE?(wEz!PLFc=IQPj$1kyD_dr%jW+QjCo|pFGFIh|W$5nPBabGK!e9RxF
z@bt~zne#nMaSN_9Sl8N#Oz20{IZdRHkOt<<#}}&w+XvMkcsOf=tM4csN&1JV&&%bf
zSe_iwzRo+Zz=H<s9$f0(KTUb*NZskuwfWOLp8UJ}_3sCa|L$M@`>)5de{y60{@Z!y
zpN+0Ry_NsB^Zycz;D4Ef;C}^!fZ+dEW$;DY7uYa2v%JX95Urn_!K_scY02ZV>shz%
zBo>9D^WDp}G>&nn2hi9Me3vlr=^yRa>38X8bHuY0lf<oe$WxGD@nk=!D9_xLLmZTU
zF#NeKZ2!yT|D%KxfxY>k_tN@Q>h0UIayG#sr4>&lfvhwMDY#NJHc-iPWcoOud>iq0
zYKIaUP|uc~RkR}&X1%&Kp>BRM*SJwH>z}7@Eju}cfwZ0};f$DdNmlemf;<&TX|lKs
zbh<y3p^?wc{atk!eB+c+vVY(Zcy^69Om~<<*SvXdw8fqw%jEa5qazhH`{S{1E}8+Y
zk5xB(WKpLD5bhdvaLbnmL{A#+I~uCj;C1_>aCKg9QRpaQYo<B`8{xlBJM>bAv+V2)
zAMgUv_d6w&lmwifmk8Z^_5yx!@z%gCHR&_3t?^HL^${pakSK}&z}Nn{${oMP5U|Kl
zLH8gIM->ZZhPPL_<MLTHSKJqL3v<X@$_O-)V`lR5um?RI@|Hmm@ZpHK(vPC9wj%@-
z2+1f8u2y8=H}YigwCu`%CU|0biCDQ_92$yWX|y<-ij76sa1MwlNri$7-El194JS6v
zoCDW94st@PAEyWke~%n6Em|ME?bm^5vBwfC_CueMYI>OcT{!^^`m-2V*Bl|Qwb`=)
zJTAR7L#l-buBCC*9okmOVJRg?SVEvwCYNC@Yk%<4{hBOY;)WiZ{P$`DLCMgd3t;Ez
zpEhdgG06lx)vexM`s@I13Zkc!A!A+dh8v}^nFqu2Hd_f8`T2TTMw*0_>Uv)_-kM$l
zkNgjx<j`K?WOeXT(~?f%`!5ClpkQ@VXQHZk&IFfSf*#YhMQNzy%kNfiIx0x{T`;a*
z+vuCFRn!z6$yh0*TZWEnFX#^-ug>=;StN+g1rQYrFmCymxuIn(R1RJ(#Z!$n<x2w;
zI#d-gb|WCY?8Kb(*D@9SL2G#-=b`eY&GzK8!2}%N0mdJeMQ$Nihohm2RYhWS_SboL
zEGitF(OMNi2F9dAY?oS85{^&hoKhPw<c_wa`!h2w=_L|ByWK0nQY*I;KacnBPI{x!
zs;=|gTS%8x7iIn+S9M)dECtUF7r@Zi?prW)+`2+5+0S>aJ|&R2{DoP}$=K#e03O<R
z2eaWZf40(au_Zq@7UEe~QKJcI>1L<-GZ#msFF@}1H30JrTkhcPn%I0yJ3=mC?6^gi
zk)vD2D&w<N$sxy<>E7E3t-36E=jWxdY2U!SVJSnUO7IIT5eoNvjD#W^Lvq%Qp+>mc
zY4Qtc7|8K$LRkhYkO9pLj$FZev#IlEGlO@~WPfH|4xi=@zqd1PIE@J&XpCD0!npec
zs?QYk0t}nhH|_DZs#R5^{w-pn0ZSb92N8N}{Gw-#=%5M?i@EVOcp-!+EEhs`IeVIO
z?ISx@I%~u%2^6*(LPjs%RITTO?TRg34dl|ddM<0p;7b}CXk!8d_J21CM<CwhF!JG=
z`Wk7lAU352$L<~yM)EKpoyiY52Go|#de^wO_411!?YNh*2Noa*B*JGCo^1E@wNTcA
z$Ify;75~!q{d>doa=higrg_5eZJn36+NRYvA1j$V`>GLJC}+{aPDf_axYVFV=**q)
z>B}Oef7?=60g=aB+2bwHLOycxcR&0kbAYUGjbTHJ&UY8_&_b`@K7U{Z;(l!)CeP7=
zuB)uX6uW0j8xCxUMC&%<d!(U*V(6BOiMT(*0{1op^-VciUTbv~%5$d$QVnQSi%Fl0
zZuW!Atj53Xr{CW<>BgZ3#kj@$6-_Ojh4pH-F|N8*y^5wRe{KWn?}*+~ciz;`-m;Ya
zG(k4$h^9~?gFq3X^mpO!)$GbE{s=vglKZeB&qea{2Sfu?!#wumMs&w;Wh}K)GE1@A
zr!l+s_z!?0$da1Sb(PXFQUi7-o0lpkjuDP0vqpSQOBUL7tlP7!U#%cB^-KsmR>a1K
z^QT<$pVh32+y)H2Sm)L^-|UyS1vpWv#n`2{LWYzeQ>;W3K^&@E;E5x|99aWQXLJ?z
zX^S>Uu-oa=Oi7}X@CPomO314fVgt_+-KOn|T56|l4Q*saWYG>+)SwDv1T7-Dpzq3M
zP)pB!qq4HLE~X5a%9?fZ*r^=d_Pk_&Uj<GD%r@*JA~~(=|4>^?#a0)LJU}?_GBOyt
zr$;g0|AYK1en3#~eWwL$y*z7N7m1RmMYu{|<J|fg5l|C?$s;Mj;q#h8MXM54ezD>$
z^8P|ka%W3nT<Ujscb(j^trsBkX^VWV8sXM2QcK3U!KL6{eplyXGv%H|)(x@X;G?N`
z)g5x+yn(gEa7sYw2Zos1=es%ubZnZ%u<!VrbQnybn;td1sh1i5naENaaIT}c1`KfU
z5+5tpmc<ZW-Jv~=7T;7;68R|y`++#LG~Pw7=2~hx<A#f{N7bhsCIK6Vrr3*iqrUlt
zd~E$K+0*fh0Y7ZU#B6h0C=0Xq>85j54hk>qE>4JBRQA#skSfotXOazZG$qw+%uV!7
zPVG_R79Th}+0NQAtKw8Yn7LlM+SYo6z`+kKrYGR%uR=!hhb$e|e+`&sNl$;+KikzZ
zxKt?B9TwBM-1=V~{$;qZIiSK)<G%c0-Y3=#@=y;sb!?4D!ch2iud)m&uIb~NQSGyd
zcSlb~A95PWV$ytMPg|-6!&`{cIPS_~R(#9>tu%jj8ea_;74)zqhI-eQys$LY^%0`~
zjfq7(8wqi=FE|+r%^U08U0#@;DA0O|-ZGp*pRBl^e)-wepzr{&XO|13%P{a9hCZaL
zn&(;>ogk)NkD+No&t**ObGF_3ybICj4%laKZaq0jx4`e`?3nYfP4;O5tg<@Xgl#&t
zhV70FAhv96z$2iN8C)oHyV!brWnWA6D)Z(R_ORz{kNd{9iQlJ^wT||}zSEsf_$HCT
zA&p5Ed{n1xakFbdbA6V<r)1p&OPfC4v0ykCcoZb!Us^U2?Dc$tbSE_9gGgXw5g;a2
z{50rZmfSH=V*Vc|<>%3*o_G@SN;rbj{~GUCEBsiCg?K*KoiBuhzfum(gVz^$Dr5wI
zgdIizqBerBphBz#oK47&tm>q79#&bL4d~~>+k?wj-gWEo;}NlT!yq)E5Bu%jnSX|t
zlw}93^Bd}MQrM^ZI~7*Q<29SmUsyQM$NZ&Ur*41~WqC4ep6h?^Q5ezxtg_}DD;=;#
zBit(Vq?16o%<RQci+i=hV$9TNI_9gm0s4g0^lT|<!~xf6Dw_1#k8{$d*xmv)>SZ}k
z%gKo`o**?3#)Y<(ESxt1X8XJ3)*oS$@VV67T1_jP#Q5pR4>e6%8}d(3^TUrF?(C5D
z@X8`4X*#?#=dW<x*;?t#XiWX4<c_zp;~YRzQC4=GPy31>*KVCC$cFfvhJ4(>;6MAG
z25*h1w4Out&4X<5j%?)hdu0~$li&1;7cO2|tlutM<J4q3s}BuThB`JmKCPow&A13s
zw|Iq~cQ1{qd%0|V?4oRWzS%ac`;N@Y>e2Z0#f0l6^8|m?HnuT}w_iCmm{O}bM_hUV
zwEb@)o<eHQk+!&Vyy^HV?5kEfP~`J>3uC*5PXiH@8Ms35M>PJoyiXM%C2{JoGt^=v
z4@ef*U%JXqwwB=OX#Zp%vCBsxYE!#8C#)`uw|7>w+)=e-3%)>N4sIIDyt;@<x4`Y7
zD(QlABD?i0Pko!Bsq6dz%34fYE7Je&+2fT%Od8^sa?OAweY`#Tay7nAEBnga{Hj-T
zu^FgHdRZ_DTx$CImQG$)dtbI!DgfPSW3AY=!PFSndQb8EgKc4Z>3|i>1!=v^(_p%F
zuLZNTH46Kgj0+dVLmG1NAw_x3U{782%tbg&(8j^EfzQRb!&9O-&Bmj_3^8)}eb(Sb
zX^e<q$^zyb;0;br0RdUJ)qIEbxP_s0qo(LMe)o;>{G>-N`@bwJ9oN_G_y(#qlmb=}
zLuTo>{sD?WBKL2o)+62QvZ2UsvniNgExUYCa-@2~r|Pn1@srmzLU%Uz2av?u^BjPi
z=Dkl!%;J#Ln&&bLfAsc)9_JdS6s!8?;<V>g8c*e<+qFw`w6at;wUavOMkYo$U2i!n
z;r-;-*A>?xdC$*W+y>If4?;cb5pRd)$^=ZH>v<MT0$O(LK3U;Fmj+Np@f7I2KiO$z
z8T_+kvOw|+_BghA$;7h0pU~HQ9qpOURJZ?yymMXX$BjD#TT5HQIO4v>X+=@-uXoUP
z%9H4$vHXoo2d)aSmvW`&^G7E;aM57~gGoT$<BU_rypy@~YM8dXhh=;*4c-djzwuZ3
z=6X+?C<<mUHD#gzGbj*28Ee$iSI8kJX6&=1FlLI(A6mlGoMSA`<MhiK0oUa0q$+DC
zM9-k?^tWTZ*$eNTnW($~TVdhlI%)Q<nhVhW6C8OQIFF^^>yt9N-%CxtXY;dU2v=+!
zsEnn=2?CBx1Rgdy`ZY3rB1C}CEz}6ngTh6a+B3Va1FjsFZ)qrh$N_EVzmP93-n(|U
z@35HvBD-x^U#W5Wsd;F9HN&m}V)KLoH%L*L&L`$`@kY@rsYQR<AJ8rho@M3R=rQK5
zlHA8-0GiXNO<NyOg!-ku2Q0{DUxt`|?uMnh>g;LTh^5o-hy~5nIqN?pbrg^*x<Qaw
zRqzVxSBqyj_LZwlEEkt{3)LFil+O#ad9OWtQ;^59!r|29xz`#p0NsWWTJX;M7z3F2
ziB+}5Cpby0nIgI+PZybVp*M|$=gfm;_UPK&%YCze*NxQtj*x%3vEp9i;3U`f>4u!o
z>1IV{#FVPb(OJ@(_Y%rv0kj=e1H^wDXGl>%aNDv1D<_(8nTM`G{0FU-@r%qTvzXB<
z{3!dwO}EH5RJep9M80JWi5C+E`~W9+Lm#Y~zE_gZ(LvKLM8;EQ{$v*_i=M^q#zDbb
zkOx3uosA)Hluw$~t!dVOs%ljvj`ug1UdZ{;<e++&0p(Xy%CL*bf&21*4p=wkK0C#v
z3sn@7y`X1+?N1n+hX(!{^DzOp&~0pN7FOdNpJw2L%xNr#^XQl7>i;Jb+4UuGlz@DD
zt{#~=K{nSRlvNO!cC=GdhHhiw*`ljEsZ0a5orf?qIsNPW7B0-qmYTuyuVYELVHZo1
zunW!lz$l*MI+)4m$i)IXDgYizOOOv40r?z*FBWXGXmMw|)WV9?6dTZB+$uKC#P^1l
zS&(Dc;}<)Jgg_`}r};YNn-cu2jR=Nsd%X6T8i<9DH1Q+WCT+U(&6eK{Ym<Lx^4n@k
zrasFH*@v+QPjcAo8*_`Rovkm(Of^Y;uLc~G+<|g45guSA@<ZKKrx#{fZT9Ja5aQ5Y
zSc5A1(ON+7qnCe-39UPTIAiRZswR9Eul@^g(7w+zhOT8y1nf5H62g37A!X$iHTD$a
zLpj@);8*g14ON%Y%kcxgJ^MWr6Q1F&TQnUaQP#$?Er08(92(GT!exDan`^=*Fj2qX
z_hS-5@Dzt?zb?3qntvp-w5k)<Zf;Es4fb;<A4LPUyFcMeQ)KhndQ&L8U>mWdy|UQg
zw~;n9ct2Y`Ap{d~N~o{84wbzm+T?719`$l2zuU50*GoW04B%Tu_7)BR+l$GWU3;LE
zCA%qR4(#Oq(=Jb{cyO-qyMu-9U|g5(TG2+C8bVqRW+%f#FkSK*fJGNBrD+o)rnQy9
zyachwZ=<z#aiD;`$OU@<ql@04<0ngx4LLbX`aiDP9a<<%lh+Q3HC+upQo?t>yj^P2
zEbt?2*Eo9n_i;28O6nQ<<3E0$g`<+zwW7snFkkz7bKEj)L4%3Q0g&~8?Pz-;LZ^Ge
zA6D~!!|{w!X-BhoiK0~{(C?-CU*9K`L;J}gLp*{*cmGA;=N_QfB?RO@1M2>QeLK(<
zuSE#2p1oxmdfwX-&Sflfghh5tWnc{j_6W1-xMl`^rOXhf7>0<a(H(ui>mv(r<4hOt
z@;hm~nPSf-UcvG-103O|l;3<-7O>hV;X5zu06@7qY}*uy_a!E!mvsn~oos_k`u!&E
z@;U~WzI}?n1xDRC`m)PG0jmZQLMT7}KuFGEMtxb0WO+sC$4OKY7x4wo)UYnJNo+!T
z@8C~x^#eGI)EO>|ElC(W-Kl981B>+Gw@)x3!c`Jda}Qj%l|bOL4R4WAA?|y%5M5ko
z8EkuV729>Q=u$6vMS@w5>)&e+J&ch-wSe}*=gq5z1P%iw4nJb`M1Wk#flz6ZQH%D}
zD(XvF;*Wvo&`RzdZN#r~+2bG(Rf=z@Y_6n!LWOULWQy^S&3;THN%xmhnCBgUAb4aK
zQ6&8)kxzEWf*7LjOV^t}%o0QmY)cU9<ZrHn4aKmH>tey?fvk8(#Vpfsxe)0#o1pY6
z=vLTMqYW0G(@Mu^A@smBSKa#Fb!ZWJ^fByOq@Hjb4xZG;k`^uI+B3U-L8SvkUWH3x
z&;f7aCV7dVCpLyzwCsY&F>MkOu-(Wp#nLy~B2z^YM^)*x@H#Fv+L4XHr3m%FrC(k0
zFCo*i=VBQ?jQpwpo}U7sBu~<&Bp?)4Iy-MNs4IKr=j!C(Zi1O`ycV4YQcP~Gx?it;
zoBa3@=Ew?!c-xiQAKjK&qOmF#xYo58OtU#ahhUG_lV1``_~Nbf<XQ5L1-~>eX>V6%
zFJt3$1)`9}+Pyu4X-?wM@7P-<!pR*|^K21<+<-HVq{xKc;P{iQ=maYP3)=}8aWFXY
zf)Jj7{;C2oCevNs6Z0{mbqT9Z7j*qgJ;A{3xF#rUv3$ffnqJH>N*Eo*<~rABG4-v%
zbo7%H0&ecbt>rB2Z9<(G{W$vllt6{?mdQo=CpK&P(#O$1N3=a96DjCF{z(-4tiN<`
zzE1`jj)eN~)}t8YbF~8od+I*99cM2py#6c?kwVEkj5(cTMr6?@p1I&ZzlG{}3AaIF
zDyBdMl|~vRd9n!#w@bMUv6{vc9v_dd_r3_O#@8w)Ph~{2jH_7}4F%$wfVy%vdD;=k
zZBO!W$v<2n7dIwLF#J{k!M)JJ!N2s~b5l*9n}r4LNcM}f%^N1)nLXO0vSNY{KN8cw
zp;RiBxo_?gsg|;+-t|hi$f6!Erl0qn+$5Fb?&Bg;y?P1%y0;43N(C0u`2)>EX%`Bl
z*2S~&rlRTEaZGQWFT(!sd4W1~d;Sn>b!a@vEm&iXJkA^ROqO0K8<$?+N53EP#OS4s
zP?mU8l%c{E992E!sS6pt?RNu~nD=V5_$Fz|1ungq8aWnY1ynynLvPq~vyyqz0<NRY
zyYGpyLzS#4nWley+WYqa&es^0LrtCzAaM-F>lAp2GB@rvp>K}wML+YaqT*wTY45V8
zaRK~YE`7fHa1(p03!e|elE1I0#^CW;9nwf_sY}4FY_aa$ySEwM{&fZ|FdKj!=g<9m
z4*OAU?qYQ14pHjEhbXouVJ=VaCcn23pF!CK?n<v<ly|t^OWF?)0zX@FEcm{)Ey?`B
z9O3$%HMBpxYk_q~;4r<Id8g<#`_Lu@!}Z_s)>J8cq`cnaLR||Pe-??%&?TJcwt<oc
zeAROP_HnZ?alO9jqIze%PDGj$ksM24#l0`<B;W1CL*=)Q3xw*d+g>az3cyRds4kd2
zjUBu?gGJi?c-}b&1@8xrR5dJkl->LHm>h5h(+seUAM2#wnl#i}3=71;wuktbf&}Fi
z>eX&7QqQpWEoid8edZz21*a)0^>&&}9lkcWnx8}cmKsFbq|&Jz4q5zWw^-jb%>c)=
zFMMs;re3}AFWj9T-Th<)y7ki{Tusf>M<1U&2|#CBozCdvuZv|z77*1KKQ+3^O%~~K
z<&kO~vWsPDcTJ97qjIjs0HX1%0?vQlQuXdX8qih)G9n-n;1vC6(2*i=?!$o$bgJ#1
zK+)vgYW+wyqH~`298c?ZI+}#|vm@P|c8V6ebwqO{q8ci5ki+ip{{<=RPP}{y;f=?v
z(`Ba_qEWKdg+k_K7DJb$yzRW8$|e~>oo-Yf|A%u3!oC6dw4V<__F8e`h$!IccBsY4
z9s5`+8>Y)ckpHyK8^Cdl&gZLDu6i1;^VbExgsHdX^BGu*v#|cT1vnc>ZlH3d{mXAK
z6IV8Z`M5cPf3@PYo#Tq|e^U{JEiW=|+$2z8HYN(r3iY@Cu{50feRLf+bMvEiEa~i5
zW~=%!Uv}dh$@f(N1KbVN=5`Oge;&+68hzi#$g$TZ&RTD(2lvP43408b%Co6z7(R&;
zpXysD`N%vy^J~0=_xa5%eJ9crfZ85+8&u-=xO-*I$^WKg#`kMH*LWE<4%eu`-Mggt
zJZTiQ+^bK^Z=&&L2bkXNgFo1?$(lqHyk{FSMwV9w9j4WXjg+D^sRpKdLH686_cfUf
zp7IZ~-GW`?nR|E*6qOOS@O1Pm6&y2n=aC18YKT1i=^vbx_%77QpDfuyD_rc9e=Hr#
z8x~AOEhG2yE3Z<6N|5F^Ki=TsHIx2j^x&1idGI0}vefcB@!O%X{|IWI)G@Nch0Qqo
zKN@#Yg|ZVXHE(^D0|28vZmy56)AMKJz9LL77tqT1I?0oL{nv%Z(k2B<g9p2#QDKwx
zdGPX)7M-oc`a0Rd%+ON8Lg0=XY3NQ~;vR<m53XHQ3Z$>Dd9_BE)Peb2kl|C;o5<U>
z-WM3(VhN_E{tlbzxHfq0BBU({w`%EcK%Ei&HVw-u8;5m}*hkNNZFK1G-;G0}h2MN#
z(3CY_?7IJFTrxu-nRv%#zT{T__ib_6o@x8(9get_rqSz!?v#7TuYAe&%OBwvf91{#
zP$>x=CLh9nH)^56uns5d4ub9zspg{`*|Ku_MnZ>Qqa~zF0NMDrDe(cR+#8}H8reNB
zHwEN5Ibp3WTDeu#-(EV=Za4^rZkIcJkU+Vvl6K8khDf6NrsaxjkU)m+ux67CP(x*~
zFES3VeXpgZvE+xT+kGUkuxv7yW%{4MftBWxApN{Mh#Z9a>m+HYxTz?I@LhqT#fthF
z8HdG#YsrntUp*$KY&tx6vs3kN!$D*bcXs6Z`8LvIUy|N0PM;D`AXVkc8)Z7&oXu5O
zN!k#VErrhCJKX%k7Vp&nbXemjm_~mkpkLG2W{;Guj~<_28*(~vswRaSnTS*a%c_ta
z8M!%rv+vZRVX`zcQ99>xDAiGy_cv~(t-ns9ldh6oo#thn;Em>f74T9~|D@%Q?<SA~
z)Nd%=&2IP^8{qHtH8pbA(_wnzImvaGn^`~h5Z?1a;bzIPz1^VjxgL%{6?MeoLY&})
zbZWeBu$TG?$<^*9D^pabUD4AXEhl#nxDC}Vt85SguOl6-(0m5*wmQL<U-0}_1Je1u
z=MAI4+m|`h5bcy9-z{SHZU0ggS*BIepwFd6V^#Bf(d&ZGZBhL<?uFEHu_DXbb+{Pb
zjnAy=*=L^y=jN^Jj-C7fs(JbJay_EJl&^{lrPLR#C~SqLKgr><snUD~a+$NeZV|yF
z!APb)7B)%yLZ69-l`6qDK!9s%C!}8{t-JVup@Km^|LLqK;Y%j@U^-r5T#@ya**D0Z
zuPx1*lM}q!FnvUuEn5zbv#vLi^72X93aVp()PDAmb+%1$IsU=-70IN)8~mb*y4oFh
z43Cm~h9d84NKx~|IlX+~UKQIG$nkh%FQ2N9=O-!tcJui8&5wOQ^_Yjr0td@gbGaB9
zvOPv8*{fb7qjF?(N<M@C+k=RbOkWDS)46ifVZXHXGwB{WZC$ESm|rl3USZhOXpTj?
zNU^0m!ug7pSiNG=BOme&#yhpDd1P>*y5Kjhy4EYu1C^7=&C0iO>K3Ea_0F?f3cRyM
zWuNNY(lmA^<6nFt70i*ob0L>iSFE2G|Apv=U8RGLfx<$;u;646ZgGicJt8RgZXs-}
zs>f^5bbio$nzPB?gG!~2<V@ss<7x0NW`-wH{*R2&?f?whm8)*@xx-?fCx895ER)8z
zf9qcf{hp&9V&=J3d=u6##|6~x5W@gF?>PALrB>11y0h{SF&zzGEn!2k^?r(cL>h}+
z#elpPxWcV^bd~`k8lZMHf?4}>tB0)h^OSzOk4;*izb>JjPeq~hqU-s*fu%f-w~%=c
zQu|pm53qxT*LFnU>28p?*2wQClCD|p0-!3+C^gN%lPTp$+kMA7_neh^-z^9oo<X;=
z=p}Q;g5S1H;7kJabGKfHTnv8UL4&fI{?o*-*nr(!GOrYx27rGv{;^?sfDNM{b=be1
zs#hy7z2!N-6;joH-2UcarHi&$h50}=SXE`<cA0c}+OAC5<2aL*{SH1#tCTmfXAOS3
zxutxriTG#N7f-6^KKK4`89zs(v)Vt4Ziqbur~%ypjsep9?!Ub_A7Dro=c>cBz^AJr
ztj4dC1{e@URJ-Nc0UtdOn=@Mq>X!4B{+slyS-N!_JKmhM0u&|7>Bn55-kNXiC}BMi
z5mCJ;_q9}Uh~dD3LD5m=_pc_I{xovFLT|9@Nr&heA1loh`^(DS%NF+G{&~74!DDWB
zy&Ajf8}Q%emYJnTWclM|MwTC$D)Tg=vxcK<cm&M!7zf9TBdgR#L_!l_GdL43oTNTe
z-()7?j1w6Bu2RS<MNg!|G=-)S;^FcOv^ruoR-E(ju<@>NI<&ly%X~=n>|!ck-4K=O
zO_d}bigHP|t7_Gn`L%Z}gUD5<X!CPVNtK2u1O36?I%V;Rjez?F@~LXXIX1NN=vmTw
z1Q{mw+ciX2$-D<-bYR}FBo-$Lk;wrcuZ~jbZzUF}ariiG{4%hmDFwB?pC-NT;#B3!
z-Skaj&?=?D&l+|tV_Mt;5udNvISP9lPP&+G^BI5o)ch<D@_9G#%Wr1$0P8ezcuoz(
zI`aTcw@?GH(xXAw>C|rCbgtKo0g_2hmyb;NyPdNDszSiFo*3$9om+xB>0WB<;*;t%
zLDAKKWYTj;_xEq_&3K=z1o5`k@om+LW$OVF3Mi+^X=g+G`WG-1Iod~h*_&uZ1M|44
zSyRK;d;7ts6_4xsV)e4;;bM-z+8c{+nW&6Ak5D<G0xNi-KfZJQo~UznTG^}z1Eh4l
z<%R}HPa?P9t0#9+>6zHU>khE`60OR4WX@DXW_e-b^+9)tcw41&q*}z4bu${?$xbbj
zIURhWR=1e^v_l>pFl)ZC{ieLBH)L@(Q*MRwIMTdbQ$JyC;$;MNa%%eGM89v2p>Lb+
z_K=%o&Xp4X;Dgn(1{{A8AIU4Sv|;Kpa#&7{q;r=cqh~8&R-j{qU6q^O5SR=qE{&Mj
zNnWr|>D|oW=&G6fWkD6cQF}f=ovS)ML%3M+pSvWW1Egu99!Im%HU?b1TXAL-rKGtJ
z@lN*V&Y1QJy!s|XY0BzT(M;7~`wv470QvfcL-XVV)*P=-K2T|>yH_E#`~PY0J;Rz>
z!meSD9?KELf;4F=RuB-RR}~cj0hL~((tGbsL_tM*uc1ij1PC=W6(LeXP3Q;#LI@CA
zD1pE`QP1;S-~0Rh^<5`_xGvb)%)a-`J?ma;%}i0u%i#~=PRJnMv;n5xU5mL&Jl%k&
zz}mY#6ZlL4=tAXdT?VrC#@;XpAt|ad_C3}w_Qs&%9Z|1)g*hhu2w#>;{W4F3E1dvM
zw%=UP8t!CJL4g@FEXjOH_fDFfS_9>Y(~owke_#41&9-NZ?1vt`Z%7Fp=v@pS-C;-P
z5Qg|_og}OK&HVBQqkdYm_eywNRtV`>KNm3d^PL#I1%vrRGVZS?Rk+Nvtj6^1N+$`I
z+bVc9Pn`Sy1IuEM!W;}E8GSrvg?Xa7@+n^Z+OpqEZ&ihVy#NGz4@(r}QNEy(e%`;$
zh`hDkA$jP^(*U@UG#6iZp3z$^(AFid0$o4Z)g4RHa%p4fWdGF14vtq#-<J(J$Kv5H
z-c%8f9}!y`H_VIiImQx9uywM+<F2leTlO35r4nF4qbCQrQ5O}nIJ|E{dgEU`ZavBH
z8?a-B6?)&fUhbWk$8<z|dTznqg8sK1o?yB>6#2r)PM~40$FfrFdrA32i$ayzi1>os
zj?8_Dqx@0^h6}c3RrC5Tys`o=??W_pohzul&lU(D9ZEAA+HzR9FXXiIl<8e@kR$cd
zZm+Jm$ovfen_rFFwRNIfyz(4ZE0Q*nz&MD$#_P+N|KbbG&)_6^#O2)@8HJZEkc-a;
zcPTEZ8aVOfUnCQ0ncwvB@S&S|b<LS9+#JRIyUxcNG7NO4215h5a!N3Cp;>+aD${dJ
zq;qd3E;Hn+k;3eqeDXxJbF7FBCT`9S;fMVVo}kAkZLqzZUfxstWkJ?vXO(Rl4A7JE
z-YZL2-aKy!yw$Lm@SJ=ANqIljCotX9;RV`qwne>lQ|^7`$0K^)`w=Ft`?2EYv*J<)
zsUthp=V$<@v2kX9>tBN7c5L49Q->6;{6rAGRQaY!#^w_`lC`AD48-clO#PeJ62eLC
zTI8}$@x3iifk>!)QsxoC^Ol%`Yr~u@=t{(3jt-ZgQrkms2-GOVxD(qZE17&dSJedO
z!ON2?zp(CBRpV+6sp5?=ZRgHyKN3BF#r2e2SJAv(rPv=YQt0?Z{Q+AbY~4yqKfN$`
zL0tRN>ZzcQ%zf`po`K706wQrjcj-=C&Xs<#dK@PW*PXZau*Nc8Z5Nmy{Cw2zf@rOV
zn#Wtl)5bN&c^S+JV`ZJ6i)a3Q0e6MVR1FXQ4tRb%m?veX9GM~U_u;?vjD6jaN6M3K
zaU2h-8d_|uT1h^-C${6aI!st<TPZa4O*o0#yiu2-&Q?oxIB{oVYh<u@Mq8s;u`;*b
zS_W!f!@9V}dLaGgD_!QBuaD6iHUl#ZW-Oa+Qzr|mJ2L0Ma|8%01kN-pU5?l4$$it?
z(9TbIW^UY6pCsocyvM?c9i4sZ5u(A_B>?I=El5(yX6sO8@Q1hJxsV)2q~>jyqTW&J
zn)%MenV$rZ85`OF=&>r0UDC4goA(;A6+U(K!5V$jRQ+Z~s=zu#)|V=F^hjAick1%%
zc5~M})B6d|D&CVTsoRvr1xxq*{MKv=f?%DeTx~f1oxsp;erI32WjYD*ZHgXDj@2hy
zH*e&Y>Lk_5<(N?>96!O)CEeP&BNxW4!Dyr?!;z!7Q884z&oZeRHG^ngrf)xc`R`5d
zMmg!ge_7%$86bhazGCk2H<&kOiIutEj_sapo}zDGKJkcC>~Tfl&Svh5oG8x=y0P5L
z=!AZz$S#42fPV+?tGAd-ha$fp_D`8LB0uJ667-K#oxU_UmvZATsA}NZ73B8wi}e3i
z&3AdH1WEsXllGJO|7-OwegAv=gg=+Oe)zwI5$#vEel7R<^G6`2{$Eb;(ElydXxHfe
zU%v6nzxJE@pKt&7uR$pOe-rQ-8n<)kj6=>lEB&&JyLYacS$$)LpLCX0ULP{69v&EF
zd8%Op?M^54eYnFpvZEgp4kfTI-269#f{g@dMeA$V2!-PZ?q*NW!<b%pxByg5$Bi&g
za9@%fD8hS)<{>&*`iU|=czsoYj`sw~V#>OP7G;an#JpLv)!>%exJej(2FWcPg;$09
zYhhdqvyd9Q;Z>H{KxWQD%Lqzp)OLruj`hSw>OE*~c1P|qR}*hRoohjX!twA*tI_3S
zX|j_{L3)n_`iTQ|B^=pAvGBpgo5N?Ri#rr9*|jZe*_8)5yf#RjNb`^vo+3oqZ$gJs
z@O9n-V?l$J<5EWBIaEc13gTTvc)GpLZPw-w!7J0;0)z9@8<8d+a)z1kNhgUp?AYp;
zS>E=ow;a1v2zs7RUh@39P2+^PoV22NW6rIaAy^9J$q?cI&ux^|f>=N1mmX+w&{->x
zR<Jk_$XGm5Rd~;$`{DlL!TxARh4r(q8Tj)y$JHwc#Zb?-jl`4*(R&Bf)uextds|>e
z<XGQE3Hefo@}&tCQP`D@b#`?>>R(+o6vDkUTo8#B4&NgdMVdhOTaBqpwd+ArO<LyA
z<5BYqtA)8(ctNs#TFJsdW{jP;m3lS<)H;-a_cX3jspHmnkl3Gvatt&C$g<bb1+V5r
zboD5fq_8?Kj;PyVCwTb(N%^&!4KRa%N<EYnokn=>4pYev?XR?c7HIE{{hLfaUg2iZ
z;O}&xv?SdpHK6f?ZNfFAp1=^toMS~8lQC+tD!M`dk1e~u=QY0NnNwgB6Hq4KPt=5A
z^Rs*-;=8;0Pw5zKlTf@P<XuJdLR6DZVIhip%j>fj2W8%kaU+U&jrV##)1c%drW`_y
zxEcmEA*&Rz*Pt)IJ?=C(u=U*&*4CUd7b)JA+4oI^KRqp%Si-@hR8X*l!J*Tze(IVF
zw&z3VY7(36`-9_Jf^jL@30H1ep5=oFY$kNJ_1C#g-C6uT%rL$_&nCNPTZu&C4i=9@
z4b>nAOpC6(ycep=w#|V?JK0QZa5PXq_C|kB4(6gg$^LdV!rGR=KCRa}5%+RJ@!!1o
zo@Mu``k^l?Q|`l+PFf$hcG{Gwb2gz``mtgI8p>8UMIUk-`*mXNWO4t}LFHYOkQZ3T
zTTfCVbKrjFRaN`;X%p@{^EJjc`=2;u-BG-L`wIP840`qH%`f}i*ij1v2z*Cz`^6PD
zgXofo@!LuUz`zR~M?Ph2rB`)JnlfEolwq2CR|31F#ExYZyZ}qSi4%4k%{3?P_y`PE
zvbX*)XJ26Zi)991Q|VgbB%06>&&1b-d;Ig$bZ*6MRp{<d%?3wO4rSZtS{s2w?(}qO
z{xC0}=>E86|80uQZ<FcWHNZDt6cA|otgBA777dsQ|0|>!R&6Y%jNWq(lXJqE4r{np
zmfx7n<_2r6##iGWDn~RQ#*D&Qi;w#|DjDi`nVLzE(*(Qwi=nAELu5rE2VYA^ZIRY?
z`RNq0wclot#;oI~dhA7Qv67oYoKVS|Dj;f%A}QZ*{BR@sRCo3Z9$1vs6Pis{FXY=b
zx1Z}rJ3Am13S&y&b-noP!-1UT=_jv5=oC~qdj9>gt04L@%i+R1*Uhe4f{jLKA6A;<
z_I=9YlLUWn;^78TvXg>r+{;T{xE>aVWZ0y?NtrX^7^L`Ro~@x#mb|}1ZMpC(Y{P=A
zP6FZhfgHqM$F~V1x7Ym-1%t<b8cN%-PcVY|ADpLxp{yB6<XRwn=15T;scDz7ymV^P
zXo#qDp14nfoQnZxF21lm$>@o6>|F6>z(482G|L-jelXE!y5HLh2t3r3=G8yCL>rJE
zUe}b5+EPX=%n!14B#t?Z_g$t=`E<lVV~}*?>lQQfD2V=<n1wU!+VS%?&?L@h+h6f?
z1+Yd%`~q@tl;!=rH`b1$5FKEt{}#bvERY0+gXp)F4l||QScl;)U7fa>?`kuj)))k@
zm@=He!ce$*^fCW%l0dN`YomS(6W_;>B|m-rSlFa5f2Bf-2Fk*^y{5AiWp|+!n)@e^
z`embP^cT%!ckYK7kM+OU*#@a!FG-*)H8v;5Wj!u|bN@6r9es?06F%Pq5>Qam0{fzL
zUxB==7TBDnVK~3NJ24f{-XxP%Vh{OI242XT%UFAdQ(=*akxTCEj}+#{iv3O{Jxa4j
z0s)DRFGTQd)S67K<hzgWV(+|+P}!1*CAe9y)jR<M-^NPF3&hB8Pc~))A)o%q+utmQ
zKv`zN2cNRt*gfn`Y0;P6AM;w09Lu7>Cd5DCO_3rt%2gQnEeseJZ^xYuKCoZ6!tY<R
z8?~d>vMEnCtS9P^Q0|ADd8hGquHO(G%@MjvNS2qyKKBVxGGn9Qw&DpOQR=Ap1Qg}U
z+<M37BL8B4!w{std|2c4?mNQn^;rrY2RWA)oj|f->24n!ie5qQx4%0|soqlUjqvx_
z%PN!RmMgw)EWzCstEHa^Q*Q|PIJGUvC6Uv<ZuBgzE?;zGo$<q{zyFQt7dlrC@7JVB
z@zybj5J8$m&5rHgy}bZ!@b!u^>|W7ZPkoZ0-6_c0hu*=2`}^U=6`Q&6?!$2)K6{q%
zId$~lz&}$*PB5a(=To35+3FLU*0*5Ej@n18`mdQ<O%Kthm3-_Xx&D5!Uk-tEwy`k9
z3^JW-;L(Ks5>*>z*A7LP&8N1*2Fa*Q2Y>tU66%2a(Ko$<k@dz8-7E&y)jo$ni?tCg
z52e8MgQ0XA%Z2R~FU`spubEwdsdx6BJ}_yN+mDkK@=={ELRLvnV~5ORn7i8h@$w>C
ze9VcY3;Q!Z*NK8D=zQ8=Ylm(7w(OJOi?=i1^Ut~=m+&EO7}LPY%52E!mYDVK#3Sm;
zGLAy~${g|fg<}$nVkwP29Wq9%Q!LXLTtCF2s!}!LTChV?rB;LA4%4P0vErMer^=qN
z#$-Y#kWaby&^j|)C_ER3TG4V5m!;5JUDMmsk}Vyzlpjz(C4CV-9VqpSX0frMrT5sc
zX-CGO_zr$z+t7ae8TYE_@y^s(vkMj5yB(F_T;{6_>!&eLXo=bfbf~VR-f&dxWN%bO
zG?++$l+SE5zMp5@OzSn+Ej5gE39E_zl2w25^J1gtc`WWZk1SWnMaQrL90pmCu>jt1
z#P8be%i{;cGlzouNObdM#rVqAIXmyU9Q}S1yehi4QYT!gr}Mc+lVC=%^aA+<e7RSY
zJ3tA}B?dWf*p#J9@*&pz-PN7^;^~NAsUE4xEVpq#v>A3O5)4sjy_2&hwsx-XnZA@b
zdLwa^Bw3QuR6i<Wx@yj8BuDE!Zv6pE&vhbJnOCQMBjk3{mEzGUynFi@#zTV{>VAH3
zF+bN7_eBR`S^wE@hsS-X-~a9sa8rdQ=KNzKe2cs3=9`wE;H=Q6p>iwS@cBY{SyO$t
zFSsh=<b(ys$3xR!Q|5X`uFhS`z}7iyIX%%gygHKKuI4v2y6d){;89pOT0hXnBA4o2
zT-vVOFY2RQHH#B}c&7b#=R8ydDwvDckVq;8J8C?L5KIZ-m-BDF(mx)zoy(Iu;?|7s
za64d}tJ8DX`5_X<tE|#fR77_yN1D5!2TPK$^&XSPL@<mN;JP^64Tf4WrI)4iM*{-x
z_cHGeRn^^tZZB~4w@jagNZ<34T%H$*JglbezCeYH<x6vy+?HLwbKqe8;L@9@AJ(Fw
zf2qvP<X;qbBNh8_$!5d%XCetgSVJl0o#ySGduw`i6^{w&E5%XA&d+&OSi0MDSe%C#
zv=d#yGp1;BBun!v(pkVTO+wMupwJJ<j*B<{{e*X~&?YFhfQxy8zCKOe*ezDBJNdU1
zY`(?DqU3jc@A(lFk8k|E)9SZ;r(Uh!c}HPsS+P4Y{;K+x#N~;GCMUNKtzl~y!V^d~
zeOn|cu3kxnVenw`yEvuhRgnk<QXR~;2diYhfA=Y*30J!8HBb}w4rPbM%Sng^B9vtx
z(FHw%CNR{gvTHwL?tUy5usy10Cjh_0u~oC=-GO}ePwLr6$U^!?n`Hgnfqr)6nnHng
z0$Zt{L$*Klr&YhnM6Fz9K^WUn>?b*OyQ&|}_J5vA0u-X(H5C)oC+pS|2|_w>vzPqm
zzGk=*myWy6Xx2>$VT~lUO_ZZOs^?BGi#1)xJb2n}6g_cJwHj>VfAG%nqh3e!<1wd6
zB`vHwd-&vbyi<9^Yhiv!9j?@hFQwX0zo5-bv+{)5w?z7`#8@Wh#brfaO*6*;JC0*?
zLGm?xRcN_0{M8*L9q}yhI7Xiv=PvmuR4a|t6kM6*bE2;8Yb-3Tv4t!4shQ=)o%gJG
zp*??+<Fw4Pd>j+!CDi5OH-89~w+cOn?{>;=j!BAEZnA~L4YXs|LYY5cMp=4_<>f3T
zmR(0S(hFm%%fIbs7YB!OM_0V^Z=7|Z-O|=LeQKL01x;|(vUsq5ryqO;eqdYA?y31q
zUpXPZx}9`-0W*5~!ZBTt%qDg*PXDB9S>GO2YN)MOGoUY!D>Bs0SUfSha3!S~^z)yd
zDO1~5*VlLC?%prb*UWeVzcZ6K>>`1bpv|7&U96q3BfW5oYIdCjHt~@Z;bPGeLoI7o
z`?2zDwG@xH`yK-6F@;&a>N2^<e!ZdBXM+LiNL=4}11r9)d{PDgKl|O+J?`ALz=s7N
zzx{~8XRSn6ZcDjgO4m5tU`Ntk1wULf;u-ZYn#;F<ce?i7`VhtiCcCWBP*JZHqE<y9
z*i{DONHx9{hHCzmo_Dg-2679f+zQGyQcf}7HBze+5FZMJDyNHkZQf~6i#rdy>L|vV
zFUBSl0_q#P(eaEf=>=2G6K(Sr8g1G^hrYeOiF=-Xxfdpy8Dt}RN><7<t7~O_z#d`M
z+&=B8_Q#0LLtl95(DZa|S}UDRw20)x{S2t>GL^{IT=wjtRkA#fm&f?B{D`%boKsPy
z&#S?#!_8$Qt;S1IJsiFDMV9tNY&Z6PLR`XUCb~~}k+HGeA-(3ZdXDON#iwbeS6H=T
zVP5?T@(D+z=RH9ByG4}exG(b(N)__uzSzjYkb;4qX!v2=2nX9g_=ECfzNf8cP$yV{
z9jfbh{B#cOK3%7%oQRxy<F6SNTaKa0rwR&Ag?#yA?TS7QBw44jt;eARPu{(I@@%pP
z%0VO2VY@|ez3BS7NgH;bC#X=mZwVXjLw5RdXwORr`F5hg#r(&J!wF%0l24$C`D4I4
zzWQP?+)vfoa#@rEQvLaMAVSF>bOP3@)}g(Cd!d1x<jf+Y=QkXZd5rs2-s{TjetB^#
zB?T@MRG<Whzb+ll@cZ$-j4fGCh)=*pC6;mxhqhDVRST@T0HAEg)Cp=JvUcyAM}_>E
z0qvkt($#gkN1Yy`zX$nr1P!=ao>)IlU3{|N!x`oexhqJr6XAd)eUD@M<etdzqqH<p
z#{Uy`W8&td#oh>gyj~7{T^B4V27z;5GCg<V*eQj-z>s;lHW8%oHP7y`jbf9r*SKtD
z%Zos90MU_VZR{E4mlqMxbZ{8Vm8QZcyv?>=Mk=SW@lT`0ay+#{OSqcA3Ch8^30I55
z7L1(PAJ30B_}fkHq6;)0k+S=(`k9W!ss3*5>&JkwIKyHj>+j~qesE8|KV>hVM_oHa
z{jGqVfD+=GMVozvpZ|N&N^(kgZtlCL>#*<+5l(q07*Ceu!)Z;kT&v1Y`M55;SSp9q
zu)Tzsop1b@fPX{e=QoDc@ttjSlAGW7POa@8c*)z1>p6G^<apQa&auku-mL)RTde3L
zXS9TKfe~OG4z?%ZoHkl%_nvOFpATTTn%^>`_hhqOGRZjiC9yPNQ=|azb}5?0T{Lf!
z<%Cz!v+X~f{r!19(Ai;=+?0s1=x8ze$dlozV#YJwD^jBN72<)2vTm!V%RaBsGyZJ1
zhp$-nV!5BT)Rw%*n`!ApK=8y*1{a@ji93%>aY&kRY&uEVC5yeBd8^iGtE+c8WIV5v
z%I;w(UbSIGn!-e)jH~Kz<TUfWg!%;?eRh$VxwBpC!#$s5tPUdbGe8+g9#_$~NipRj
za!O5*VqxpLOG?zn?TYb_ObGN>ah=ln`89y9d$jT}w*+Dnc>m})?*j*@g|e?d&$*7o
zro9}S&P0qRd>N(}Gzb0*rMfe*2}@#}B$52r!Y?$RB~J~3ia}iS#QTt#xU^uCmZPmM
z?Dpa5VsH*&drjwwpbu4T8AgGV+ym><L_rG4fdN8)d$cX><eKv_P}KJd+w7Ei?Y5u|
z^A0v6T#_m-D!IF-sMhM`@A@P?+hxgi?3`O0iA4E~xf@k|+Pw6;i?GT7C_H^xev}`P
z#gt~$Mm<h7)i&zqk6~cu6&tFR9=H~lq~n`sce{jHDC73z_9Ui<13Bh%OSFm=l6^x^
z60+rKX}PTB0biZ=Y&&r>jkT@Y)vD#qUZhDKgIHlDZu;E5!$cg_JAX{hv`=^4qN(*8
z;`D=#Jgo;ND$q^N+M17@DWgy8R}EV;!%W4iM8+$G!{bOlGozQCESLJSB2A8mR~J;R
zPLt;NXIVmqkJ;+SAW44=N59jF5cra7J+frfm7{ep@I~Uo<r%{ji12l^>t5&1ik<w)
zC+@8t<nIAGz6ovJyL%kCv~SJN6my+)dG(s*KDf4AZE==VI7l|DFxdwzp4MRSzAXTl
zLluhw!gO1U&@ht@?oYNZF!RFBpIcD?i=ICbrN6jLw%MJ4Matg^@GenS<>kAID4qPO
zw8v3G%RBn>?%a={xfW;-g6G5e1(gJTzIasE!KvTV(3hVpEZ0C5w2a^3-cV1fcyZU$
zoatUYq5JRd?-xL(IK>y{5s4AoEP%=F*^h`stYWnRD{aot&^N|Yh_BO2+WB;){y1Zo
zEq*utjM?&mkonWW%Yvw4GZzJ&ACJw&Qe0<waoDWdO7%F=wz@B&1Lm4t_l4~TdD!Gb
z#8N7HXZ+R7&C!`xmZZI%+#*cNdOw?m4&w>tK|+9KuwiCl@HYO_HHK+0jSe9{zePUo
z8lBOS;hOk2f3(xrfbsJC%|<QJ6)pku<IN7{+M6<Gsk3!HpWs4$?kIQHq_=8M4h!*s
ze3n_Ma$j&7@N*)klG&EJ<3ATZVP=mREO_`X*|JZ{6mQc7D~^2q_4Y{_8r5d!5j2Ii
zn|Nm739(oHig$dXgcN`n+e-MCm*2UxRGl^DJmR*q)?=q&eZkvx<w436I@vEh`JLnM
z<{sjEw5fdJbxoq2kV>cpyH3TBTgGtdfn<?T;Y6e@-M&DsQMIork|3nsplh;Y_{jU*
z)821IW}zKd{ubtNOA1zt7F>*ZOpIr`*~Lf^y*+YM{sn6PTJuLycI~(y_9|(cm(+6k
z7ZC?DVm1J1<pbhL)XdQQN7<U6Dy%redcnta-gN%x-c^@1%}ATER$jL8wJ3tKRG7SU
zdet_k%z15rTTk81=P`x=BC7`J`<$-MtF08A83Ig%Dui|}2KZd$u=Y9fzE*HTMAh6T
z(7*$Onvp`lOo{Ok$%4}lt+xWr`<<uTE?btDN7@og56Hh}u@1-jvK(~-58b-!o%?nQ
z4L9Z5j5llO{tos&)@Gv-yL9q%z;eauN}I;dU$T!PoGbA!)-&*lCuqT#d(tJw;b29=
zPC`mle|`$a;N@;>`85v7O85snoopiNc6N)8C03Gz3SCzsOxlSeKJ6`A@Mix^CJa?w
zlfl~mgY$T6nK#ian;v!KYX+A$Oe*ls$4;2&HIhl~4n71-p_nu>(!Dt`wAC45h&1&N
zG#1IX{o^uAq!Dc}xsC2s<lZ^l+CYQfU$Seqw)+|KZoV*B_~`}%QGE|2@AJ!+Q738D
z?{<_G<)?IO3YW(g50j?E*HS=2x+UF9+69b2gY!k-$FEep(q8(!Q7u%7ma}|`P=X%x
zi1=+FKfq8l{<D8UrnyU%lzgUtoxFK8TFO$W_Lc^X%{IqNJ5?#b>&>YX;x?zs%oMjt
zJD?<|Z0zQ;rb>&xVaD3CW;^)VhZBU*^}2=qT5ZGKb{7ZEDSN;{tsd+kU6oTWVA^vZ
zdFJDv6E6<EwxrFxjAAJpQ68!T0ehid?>?Z?rQz3tgu7Yg%vHNF3374@e9Y$)xpa(1
zi$U%7xbyStzjYgGo+eH7G#NLnC<pEBuT<((Ef?urWThXzW{O*Q?zf(xcuW@UnIv{e
z1wz@TFV+LKyP>K=gg+JE|4%Yg@V975FMVNDO_=WI{grA&d=N7riGl|;!&9ww-0VDt
zT<YD6wA@r1c)Pa@MZ|i#vx>7P`+Uz8SKLqqv3fRE0*3zYeE~#_Jj~`_e|<gC__~pr
zk_{ZIGl0$3@K>7`;}=}AsyN^0`%))};ujcMj1nulg-Hmo)%a3$@Q2@f0oL5VzE?K<
zImcy<oOJrhKXrK%gE;JIlG?<0b&ak&Ov42>_g1!hsXYHSI-89VQDLta#oYPh)abV>
zXXqE29OU!t3-n&F4x3_1zPzeTZH<>(k{v5}h;SCXz^;2&&as|<K~g^|ZmN85k!8kP
z#N>HAhX3ZkH$5+aRbM<sk~f1uvD0E%^@aUZRq{L6DY<cEwwk!1o0Ap;U~f7SSO|cJ
zc_^#MXQ-BvgYTJ&Tq_?>7Q3VY-iYPkxBHT5Q|$WV{%EH(Ni0)ne(O8JuI1`_1(0LX
zc2g>?ds~{anP+_}Jk{(U#6AB#bYK4k%0J7g&awCHKDoJ)v9oU0?c0F3i_7iH5>b)g
z%AVxJ?oiS#b3a@vwY6{Dr>w_0Np3}uBs1}l{D_X)z|5bHL#{0!d+yOS$>-rc^qVHd
z6R_{-^&hh^bK^KGbVc~Y?a}*alC)CjweN9OKdtJ>J`U@f;CiKz3Yf_9z0hwm>SO86
zxsZZE!2?%b0etvT8c)l+u`6-rO_{Zem)(yH5Q_EKfA!NWV48kiqHj=8h`B(z@af%k
z<Gfx6?yM&=0yV^_lho}AMg`eZ7h&<}4jtnvzL}wtpf2mMjIJ;7Yf^rzFsn-_u@Zsa
zEs}EA!rcJR#UlT^W<1}YDFrIh(cf1N<M$i!_&m5)du&7lh#f3pfC>VLT){{-Unh>x
zGJcA(D89v;ByD~xG0KK@M%J-jt1_%19$g7a2gttZd>I(T8(|O*wFT^-Y|-|C2EBcp
zJc1gx)2KoRJnkw!O$FAk4AzjrAK9H|w~mvGA>6%br?u$Gny(Y<tizmM@JAbMM7wUd
z))iRSiB?^qW|jR;+c34%rT3oU3N73x7JNLo`r-So*53szxuk|+cQ3jhY&Y(orQ8oL
zd#Uwd@fg*nYB^8i;v4qTIxKw2C&hJmEi1IOPlln`K>PD`NZtqU5{0RVfWm=;y~Ri{
zATrZG-b7Sgit<lSmz~T3#dWgOrS+_`-WCFl5!sE<KmGG}k2!RXRt>oyFvd~V)EV0G
zq0~1$0NIgi55`&6*DuR4a5xMGP**Y-I4p#YG)Ih^_a6%q-iofc`bK!`U^@xCgr7?|
zg>XB-;xh(33Cm~!6f~tTg5iOt(hCXX)VlP*@GSd+6}=BEF!zQ&#`Y$hj;$i{GYG84
zHA|<)Mn%X@+dZo6x5#f#g=`Mab>RtfoNkwbm|04+l>gmL?JP)W7X?7{$g|ws11{3U
z5O3bchYxm%Jd`dd-{lb{`p?nt5YAeuq<<vckp&vLywW^!__-zXd!f&%ixJm(<SerM
z4oXarxJC_`U7jAE064}@UYY~3P9}%IzeFbBFy*y7!SYRZ9tz*F<Mr8U)kiJ(G^0KN
z5~FRY+#q@MsrP)6HFaz0_`qnw*gD5;m*?@VVVl7mg;w*uUm5MrLS5E3rTq4Sm40_e
z4}Tw#X_wz!=7lM(_2!4aW*Ey3WYH+B>(ztbb3PtD_EsP?y$JTH<J0ba8|#M4`REMc
zgZF00U8#?tzf_n6#7NcowyzlP5l4OrM5;Pwsveqnwb*<dkk5D|0azIr>4o;#lt7-{
z3gOuZ(b#Fc=H|8wo>tW_f+5YeA1JacVSriJugtq^;Bmzx&vkC5DE1$)yUU}Pf-3+4
zWLwMss*eqJV-s+VmbQSQRs|}V3DZ&(^p8iFhqhYmEOCA<zYqlvSNkPQw;?#C9J5qM
zL8X*m>5!Kze%aH|y}3+xxo8~d)s6nBvnr^4bgsD-NJNn)4t2g2jR9DpL9tB+YdPw*
zDb9#dp*$CZm+oPWXPIv~U!UiC!lY9YZdZ4h@Qt`Vo&Ly9<b;!9EmE_|Z^cy;&tQSh
zWcDNHhTP)xAznAPCXCgCo9c=G5)XjZDShV6)XNw^$-IweOX(oqKgNHogbkkYP{9Rm
zPwBH)LHYmW#JP>fncNTWN=_{Xq&fN3c_!K5H+qhCARTGqH;%s<K_ZN?_9v(p?DUQP
z9B^^y&{=>C?oRH_o~2$>3w3)RQ6Yjmda#`S!(;J+6>){|#mUC6BVhff6?GBw?h<ND
zpiXW({GT9!F1xDNQ2Vvy?;o)<7kKy$BbSBz`MteOJWj*jNNTufYA16!7ZqniKxv}r
zx7;;qb1H~gr&!<vSTNRrm|Q~~6w0Ud_0@(dgiCUW`E92$Zjd40OWyr`MmZRpA4f+=
zkE&i~ebDpDCrysJfAbOwh$~Sz#p8fwm$Su^==A*=0yaY!0o<`1KGlATMjOYT(5Kf-
zIFSQV$6ABxGpLUXKqx)0aLLbU>Gc`(&*ob^r@^a!e2>6|vpy`VpvkqD#A2hRHCkMD
zHIpTE(nmGP-+fZa&3z}UF<6hV-g#z;=~Y*XJ%_;j61(2iVMI^cV>*4-qnD12k;8JH
zL8Y5*_M`+8;|ik>qciwg=rI^hazWnmz*`}<ODKmL>mq+=(ucRzQD1&I@2p++8p~{A
z_iM~(B=6KdgN_zyJqPM}$J`t!a9Z=w+;kS*ZdSx_ZzCrqryr|>p(jPb2xNdNFBhCL
zhvxnj@U#iZ@0!<f5;2)(uGZdH(`%e2i)AAJ+8rEhS5{8*4V}k1kHkTJoFZ2LBCE>&
zliDS}bL8ImdcqwFJfiD_WO^E*@03p1AV}R0{KDeJa2Syf`IayDDu?^T%9*1=Ps#+F
zxTz}Ctw1ePFs#*lKR}5&co}E38T7JxxB?_;z<&+bq)ryxy`5LbEeVL~(V|Ekn{lpv
zJ?u$S&4K0{i{Pjk-WYrjp`v9;lA~tx>2dxmgzgYt`XFXdFRj;IC#)aT34TR<>>RWS
zn?%vW?<|vWg4{n{{;c!GusRU`I&>u``f$WcD@UaQ_HW}$r)Bhjjbs{TbNvTFWcUKd
zBR|Ay6Tjdn6WOb{U9|R*NvP8a)0(yp_oONYHl=%^`M5ixwYOZahCCRm81Z~29L41e
zQ?|Rt#0LQIKhAaAm5i%VbH9q-OLhCfT32C{9Usa8>1@^V(FPONmzP!XclQlp;7$O7
zL3gClLA%!6;D<lh1B(-!I28HnTDT}=ptxX3t>=jVW`fWkgw|vaj}TD98eqacQufR*
zMJt)ydD2mb`t~3Qb0S(({>`_eFG*jMGwY5s@*9pudK$<H%3r#a?FhsN@1JeF%`|mn
z!oOwy@9q;kZ6jCT!InNv7ym9JLKZ1-53EA&DO9RjiapZ({`57*Ofa`h@5|bofBj?_
zcg^X{pIw`1YVV=XiC+C-9zL79ho!u#?gS!ghsGl`Z=9jO5IzaUNgmp-pnZEXe#*_-
z)yaDR&wwISSdHC)Pi+$xGX2IG+ZMU#kL6_NhIwczUN)w)FOwm)UMjgU^$Rl1488M1
zXIso{vCHprH`q@{3S_<77Pgs;DV3ymnz#M}sZQ4kQX=QFmk4OM&-H{L?z1hRH2^kx
zto6qL^2-MHyfaJBE7%0ZD>Xo(yW%LuBJEP50#fxUl!a<{I1)txt{@l=2*r=wjQOs8
z>b`B~<1EuT798{LP8jJc0$(@qvQKWV%iBAQg!QaUUa1N5X!O|94e<Xh^0?oEiQLe+
z`t>s63LyB2gaqqTsN8V$Ku$++NyCxg>%Va6X{w*-z@@;y06|QhDnkV007GW)tD<+<
z!c_HHqhctY-cKvi)QkH!S0A~TssQ#_f9*CQ5~6+Uhd9UNj=siW3zNm}5H%a>$5+j(
z0bW~I8Y*&yrq|OYMl&1tUr!z0+heQsw$F9?VRC!!i74c$yfd$u7DseihZPo?^DY=C
zy`|`W+MUcABHVfSY*5s)keq{}PSfmqBL9y{_YLBgva0uUX4ho9G9Ml*{zsdi_bCj^
z_Uy}5<7MBP`#Nw@f1~}`@t6uXMc?#ipPulsFtch~&TkzBT!Bkxi5Wr(AndnAozJzC
zOC&WAfa70G-?gMpImA)EhsB&~;*;MFUq!BGe!O(rym10JTFTjD>#ax|RtLS9M57K|
zl}%e}PvBRezQ;mw+8Q>H&XV5?3tmqFczEb@q)Gy)-%X=DM@xeL?rzlu^D-v@b$T%h
zA&lCByaPaOm*RLSky$O6(V(bbVQW8M+BRsT;<hV`;z@@y5p^ykFv3fgFty0#8bk5n
zB7M{PyqiksrgOuWy)CLI9gA+DIeTl1esnmcXkQ~N3a6t}k}6MnuH^Ij;Sv-tC#SFh
z0cQNPaV9;fr3qPU1gN(9#}Rh2+z8@B8}wImU?VEnxpTidK~GK)0(=VJU3<^-j6RCN
zJMK<g^P884d?1jy>P+HZUQG!rREfE4+1oQ#*kmu63v6DeB#nWFUJa2`J}sw__A`lX
z)byO8k1f%QhK^pj^M{PX(gKi%UXm;UD4-VG>FQ-2PcQm3O#YoDZp-w7GZ&x#02Q#M
z1g3WuV3wIY%S%cgvW71u%n?f54HMgwugrIiaRIo2)g(|2@fEBmJJl`f*M0x|Q6XCM
zoYLErlC&2RG$knXtTwL@U0!UQH;+^T6DTraxHwUx_->8oKYI@con!<@pw<gydA;k$
zI_!@m^FO~fl6D#@#@Qs<Zo%z|2z=<olTwY^l#K0!+97%rv&OB~IBywkGl<=|80A>2
zCtxHzS(7s~=ZuSg(7OUKg7tH%b${~A|MdHMz)ao!s9X2Br_}AW>r0e{I-ESdy}CJs
zSub!{5akFU=46W&+~A*Hm#Zvpb=^xNDk}PRJ7NTGYMQ@SK73@KE2O2~w8GOpU0YC$
zAytO@Dr`imsCpvuGoyv{DO793YO*%^ed`{f6&-nnQ@Z~pK?a<LDSFFg5-3hO4BtzP
zzP|1n4P#-)zRP!yd8}?<_zVEQsco2O&INJa%}W<P$^4Q|u{CR5@tkD`wiB<;RU`@v
zXlS&WweBVN(rEF~tqUOtnCg!{WX{8XQlrZFw9m6^UszZsryRSLZN{7^WTW`Uc}P#&
zzVqhAX5s)=?ha}raTofyL>T)&DMBq*m0K)7{KX8QFFA#*B-a|N!!?ZEZCM`EMj|~5
z>AmM|uV}g?{QMcPHXKmD8TOkj`^c>Mth`k!{ra++5WSN*`u%|o`4!HnALu$-Y1Np+
zt+uFjI=ILW(&<Ms)sDYe2ueN3GggCf57u_xAn|YudK9O73h>Fj{jPeV83Pk-jWhgB
zG%OlOHPDELYnQ%#F0fvG`i|gPu9+}w`8*1rBOB)QPn7-WV1_^B;!Gk)I<p-yJa2yk
z_SZAC<7J~$ftk&t@iw+%_A973$RlN#zq{L$<@c6~ym#*lnm+FH0f}5Y*eT}(Pk`^3
z#Fr?7+rp&06wkEFg<9aU0?Nc4j)1+|^#!#o<;$xts)sko=uXT`IeoK<dn4vE=Pu8r
zTRi~zzH+#y-^eMgk9^g5T6VaMs)~jjeSyQW8H9Rvwx-gy#Ocr#jGe+U5t>Hu5{DnN
z?Un3Z4yf<jsI9Tb4J97Wx?K*|RkdohW(Ip|{?-Yso$V1lceCuqpTR#`;|lK47=`YE
z)W5suUjgqRCQ(yaxbUJdEASyK-L|T(68a#g{wJBI(mM4y7s(|`Hw%8Dpt3b!W$XAG
z%GYreqXZxEf&pa%%a5l=0V%OzE7|ERbSpEraByJ6Lc*U4`^CXsmLsJAKR~}7G}%sq
zi(VPHIfdqlSMC7&+NhkY0bsFAJfGaYL954}r8NN@4ClCQyoj{*iel~(V?aKbzQdhp
zt($I)?4f-BNap)E>-bhK;+Ncj)0z5i+q=3p`_Nf32B%XOzv)kN6He6tig&BY&iAmz
z+bMIJIViaTI>Ld9S2M?_-w_=ZVNH4*_~NOD{3}DFM;9ms%)gj$PKpbkVV+rO=QjzP
zg!Anw@f=Huzf)9XYBUbMdgyg1&BG#pFn_MWrD64O^_6j|<2wcp^+s#vBg@{Ozq#%K
zS19-Dv?Ji(JjMdr9mmXL8h2Z~MoNV#=awJtaE(*Da(I8Zv2(32c2r7vkJN+#$fglp
zvfEf~NNRv}Zq)2T^9K0fqKbZLimKlvfJ`z;J(%Maw{aXije+05oYG;}LD9rg1T%}d
zc+#Toq+6+8F(>sb8qJHaW}~^tbkB@x^94C=H8TnGommU4ju1C|arB#zO>gf|U#_3x
z^i~6FNm@&slIGy_SBruH^R*;b^2qZrem3Nb_rtrMKRpYr*~3OF=rQrmxTl6l6rjqj
zxc^WcCVOt|hoU=E^Cf9rfsiy=)LT!OyV?+uYOOv3f&fMtwgWB(ED+2vf?a~5vEQ^u
zKz>h~GA?=^xb@@@+VB6e8M;5*bgO=KFOZ8$P*zQgwDNoc>@*J4g~t!@s!YH#NFYL!
zviUvWqIM~lm4I}8oGK-=wkVkfCkb&tCBziAe0`E0B`q3@yMU&T@8=vXAN^FQw?{$e
z0&0QIr{oD-qmY@2H5}!_(r|@ScD$ru#J+je)SBD5yj%m_^r}8mFOn!$9D6uXs194b
zoQD`Vc0>P{T4`hW!6HV<^J4G6NYe>)QeX=f(c+h}uM;pZ=P-Z2g(nQJ8%Y`WzLfCS
zI_H=EJ2)42BtpCoA39T<dJF8>7s@TuYmMX?{Rot~0nAzNzr_2APah#QVo+w53){Df
zbtB=uEg1KBv8oNioFGZNx~*iy)Cu3rq+i?P=|lm}s)Z?wLLTp8PypHQEc?r@1gX%E
z-UHL8ABC#1(M>jSoy1v?H$p3=jF_ZSX#gD<f*Q8?&5(Q1)1}yhDN;BQ7=Ve4T=)C0
zo8J_db~OwC^vffx%9cPA3EbM=9PTh98Awyey#^kI&G+wqrM(62aTmkM{cncNCV+#-
z^f&2cLk@N-_BTw;hK#y_Ok=5?Zr|viRbpt?IIpMI4-7b>f^hkt<+BfAUpW!aH_FO$
z>eaYCedep!X%0!?s%YnaKY7{Z3Jr!OB;We%4|s3ypC1Zp1U_C5)r&z4j5EF;-9ckL
z3d>q*a{3&FX+%oI=7sPSE&mU3GzXfk*SwF<RFNTYa!l)oT{_pa+rc*Oy7YH*ydtR)
z6peekIBTm2h-ms#fTT2ovD*jX*QVE9X%%gr^Uw80xV%4_|Mx(C4pyiix=HLadkCZR
zEW1rD$Q>lHk8ux?sNLnPU31Wd6mN3if#<`)Yto}JZ7$LaZh$)i-o3XRP(W=H<CzJ-
z-%vNH;6-)}ZKRH7Q~FTmfGG!{(Lhf4my81(?phj?*}$y~N=c?!FU?pI2GqCle31Hz
z+-FVRKV2WVa4I+Lk4z^*5kL#$rofGYzs5bL?&R~*kP(^hlY#&M*K%85^C=q#DOogU
z6&RGDWgw^K0+Ai)6};{1d4L)RQ+eU%FN~W=YU67;YM9R8pdEjyX;t%%t5&XBlBV7V
zCPc==dnE?oIxCbvZhZ5@Mqm0dU<$o$_#+hzBccv7F)6{CQ3mnd=jZW+@8rE|>R#ls
z|9AZtHwNuQycl*VM@FjZE-kwZ{Y!vla?q5(LS<JH1l{V#rJY(x#PkaeE-X}LLc{@$
z3hZwZG=7ayN)S<SMU+f4i|~W*8ye?EG+8|VQ5Jaek%7m9&ALCE9zHq-WZuYE;X1DK
zbMQsX@cDe$MI~BlmVKT%DknO+l9&RAvO4wLkM`gFX+@hvRIzHMuD*I!$k~slGC5>=
zVd@iA77rG`h&zK<#eJ~A#VK!M=q!8TV4sTJ$mKT9YBS3`B6)<vJ;hwT4FmYEAf)l_
z8{-sQ5RC`!TP1LXU<5=NJnWRd2zV>;PGUcI3qYsTR%kHyn&nw~<2>utVl-MvW)2L>
zaInVb6{<*75#aZZulZl|@=3jb-3*2*r0gGTE{n95tTp1c17s%bY|*TOKhHQmMnuKN
zW}G|G9(wm=Tj*Wp&js!Ge`Mvkei%6+nw4LmT%1)^kfr@GtLk~q4Sv<Pk&ho+D!o3*
zXj1C5IK;qkG9|36OqMHx4Lz-A57D)IHtRw)iMNs7@tu%!!OOVdQ>ClAw`9<jHt6J@
ztc4l3q4WBhT7GM=P$HD%U-C%Z)tnq$>r%IX6ni<Y5W$_i`SH~UJ9W<D{XoV+#NI%m
z+_>kGe&(-oICo=2toZoPPga!$%ar{I<j$5@x<*vXK@C38PxSUs{jHrrlA+{m@r(U6
zcJ)Dde~V3>#32eIo18B{YzXIoPH3~?3$zOt(z%xlPmeb`weo}(#DE2D)8W^poc-0S
z^vQAHMB~ZYgO+VkQp4Jwetl`3Q$6D-lV+MP*rl}CFAOJcST`4|J`BCNCAaaMd|Jf8
zYPF=pd*Ne;x0D1=w;2(5Y9?IUyuxs&<uFOa(gLbzz#x1}8(r?jnbJY99Up{@x^vrc
zKnCkF>>KTkP;=|c9Xgng>&cVQ<Kk}D8j}-k2b=9Kqls|i@tWCR6iU;`TjoRf*Tr=d
zVs^la?)Xk+ny8G_uKGfEaAwp8usnujw<`**Go!{fdK7Ar2LncoJodWOiQ7Gk56*ZT
z;6ur)(&>3TcJ{0X!lSDjcd47)4h4c#@?rx@OY1m8#6U<u04`QrT#0j;yV#(qK4*Wa
zaTAX_z}nZn3H(|%QjZ8gYJ|#e>#nQ*pws3r>X@w0GI5bii|YMA!S0U856chQKq0c?
z6?$D+1q+!dX%_togBDm_U13Qbl4>Zu1X=cKT-vs9(1W;0X<Ak8$}&W#4Va8dRr9LX
zy?|Nl>`}TrHr#E09Uhe`4Ib7aKXd8>WukeP7%ymF5COL59KHSw%`{oR^)5Nl(wGil
z7$XC?!5y-l?6Ut0$oTe-A~BG=NybDaT)uA0bKD&tkHk564E&J1Q2S(XW&Qyb6?}v&
z4e_qGNBWuAP4p&3W*iLZ`pv0V4<sDeTX0Iq2%AiL_||JpQkK&xU+~<;icp!oWMgTE
z<y7xUt*+5vnerXSQ5PSW?B4gxs!?p}vbk%nAF<BI+P2<H<;@lZffUfg`ggGAN!7+F
z#EhdGpYIxTEe{#G%g8=G9`Q*mJRn0g)$Q6?)6`u~iGjT&Z^A>B1wWGgern217bJ3_
zy2NV#6J-_C7{1>yUOMYIiq1tWZP6sbFT?jN|8itbw5?p2ZR{P{j%lP&jL-vi9`^Yj
zev69akbuhK^s&L(+!>3}eFYx3gWw}!xbbl#a$AaEI!0)-LB<fWy<Y6rzr;?Yb^OdJ
ztUtoMe6ZlUJ4e1eWnmLJg<v;#b9;w)Sg7T;^25?@#Q$^S>XHS~1>#j+vNs<@t_xU=
z8L4P+QD<)QmYZx0a4_;9^0?u#?wFW5N-hVw-qo?D(I0!qjcOM$0HrpUEJ#yEbgtIU
ziECrZbC%+3Nn;utT3UXJ>H}4|$1b28WIF8WxnzX(x2V|t)>TO(BR675uE)}P2kF~j
z=mMvM^~5VMF!eOk_ENoTx`ZZOTH5uIp7zHr1}3&W3md&ibaqX1{oJ*t7`#)98K1Ql
z=}qgZJKwv`;IEmh-t}FRwOdUVswiy=ZA$$))?2wx;dWhKRr&cTv42p@!3S5~x_Tr;
zaltWQoiWLx4{lUm!Q4rdGeJ#~Lj(IK#+Hoangk4GE45gI6<cjQUCS9b+3a>jW^Iuh
zSywA9r}7>C=9HGx_A$PY+>0aMf<lNR^$^rClr?%kNqTPj-MHJ}Y=awFS_fl*f$Ffp
z4W9EQpy4f{YUw)J*RR>USeZfZbWVI7sn2c_vnSf@4v>an7Q^-W)#j_Q#?r!4&ziFt
z-AYNFX+ime4Ri|y9X`bN>a78ao65qpn~L>LU+n?=-Bi|;BHH7wesPp-B6-?P%05l0
z+8RVd*=_463a>y+^byW4aod8M^zObbF?2eD1rxLD>?o-BoUZB<v4b&(8cQX9`<hK~
z5HNAa50xv6(vcqbqO`A;dB3~>6{lly#j-=1DxCJfp_ZZ|!ahye>pozM$MqC+)Ns{7
z&r0m&EQ04cW!-vWOv7W8ic;&`UO3kg-(84>^!PF?jmv8u2{O6k-Px~K`^w*_v|z_!
zgwS2*X2Yz7F4usdOmH#eb-Z!XCI`f>_suf0qRY+sm2G*tf8$Oft^Z=gMGjKda)O$3
z$6whXNyE0fb=EJ_nzAJKhp1y^7r3`3e|e(!BmNcK4qY?_p7`IN*OCAG+bjRGTiA(z
z{(!7Qhwk71!(Sfye|~A^_lv-jLf=X|Bj8tS{-6Jc|L*!<1pbS_e-ZdE0{=zezX<#n
pf&U`#Uj+V(z<&|=e;<K^Q>nP(Gl8Zx-)Q$%dZ_lG<o=5{{|61;IRpRz

diff --git a/docs/index.html b/docs/index.html
index 1a7ce185..3fe26f1d 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -301,7 +301,7 @@ <h1 class="title">Introduction to Zig</h1>
 
 
 <section id="welcome" class="level1 unnumbered">
-<h1 class="unnumbered">Welcome</h1><p><img src="Cover/cover-artv4.png" title="Introduction to Zig" class="quarto-cover-image img-fluid"></p>
+<h1 class="unnumbered">Welcome</h1><p><img src="Cover/cover-artv3.png" title="Introduction to Zig" class="quarto-cover-image img-fluid"></p>
 <p>Welcome! This is the initial page for the “Open Access” HTML version of the book “Introduction to Zig: a project-based book”, written by <a href="https://pedro-faria.netlify.app/">Pedro Duarte Faria</a>. This is an open book that provides an introduction to the <a href="https://ziglang.org/">Zig programming language</a>, which is a new general-purpose, and low-level language for building robust and optimal software.</p>
 <section id="support-the-project" class="level2 unnumbered">
 <h2 class="unnumbered anchored" data-anchor-id="support-the-project">Support the project!</h2>

From c91b691c85651d17d40f43aaf1e5b49c4264e04a Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sun, 16 Feb 2025 18:01:24 -0300
Subject: [PATCH 073/151] Update index

---
 _freeze/index/execute-results/html.json | 4 ++--
 docs/index.html                         | 8 ++++----
 docs/search.json                        | 2 +-
 index.qmd                               | 8 ++++----
 4 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/_freeze/index/execute-results/html.json b/_freeze/index/execute-results/html.json
index b3df0c6d..df53cb9c 100644
--- a/_freeze/index/execute-results/html.json
+++ b/_freeze/index/execute-results/html.json
@@ -1,8 +1,8 @@
 {
-  "hash": "9747d27d8e8f5fadf3da395f3899d9d8",
+  "hash": "b59fabe5a5ffda4f02945f654dba67de",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy a PDF, eBook or a physical copy\nof the book, either at Amazon, or at Leanpub:\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://leanpub.com/introductiontozigaproject-basedbook\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Leanpub!\n    </button>\n</a>\n\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e. it is open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.\nCurrently, he is a Data Platform Engineer at [Blip](https://www.blip.ai/en/)[^blip], and\na Databricks Certified Associate Developer for Apache Spark 3.0.\n\n[^blip]: <https://www.blip.ai/en/>\n\n\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nBrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer who loves to learn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2025 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n\n- System version: Linux, 6.8.0-52-generic, NA, x86_64.\n- Zig version: 0.14.0-dev.3046+08d661fcf.\n- Quarto version: 1.5.57.\n\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2025,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {February},\n    edition = {2},\n    year = {2025},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang), Tommaso Ricci (\\@Zorgatone), Primo Sabatini (\\@primos63), Santiago Fernandez (\\@santif), Hamza Wahed (\\@HamzaWahed), mwilbur (\\@mwilbur), Dima Budaragin (\\@dbud), Jorge Jímenez (\\@jorge-j1m), Alexander (\\@alexwheezy), Maarten Coopens (\\@maarteNNNN), Niklas Johansson (\\@Raphexion)\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy a PDF, eBook or a physical copy\nof the book, either at Amazon, or at Leanpub:\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://leanpub.com/introductiontozigaproject-basedbook\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Leanpub!\n    </button>\n</a>\n\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e. it is open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.\nCurrently, he is a Data Platform Engineer at [Blip](https://www.blip.ai/en/)[^blip], and\na Databricks Certified Associate Developer for Apache Spark 3.0.\n\n[^blip]: <https://www.blip.ai/en/>\n\n\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nBrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer who loves to learn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2025 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n\n\n- System version: Linux, 6.8.0-52-generic, NA, x86_64.\n- Zig version: 0.14.0-dev.3046+08d661fcf.\n- Quarto version: 1.5.57.\n\n\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang), Tommaso Ricci (\\@Zorgatone), Primo Sabatini (\\@primos63), Santiago Fernandez (\\@santif), Hamza Wahed (\\@HamzaWahed), mwilbur (\\@mwilbur), Dima Budaragin (\\@dbud), Jorge Jímenez (\\@jorge-j1m), Alexander (\\@alexwheezy), Maarten Coopens (\\@maarteNNNN), Niklas Johansson (\\@Raphexion)\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
diff --git a/docs/index.html b/docs/index.html
index 3fe26f1d..6012b60d 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -434,13 +434,13 @@ <h2 class="unnumbered anchored" data-anchor-id="book-compilation-metadata">Book
 <section id="book-citation" class="level2 unnumbered">
 <h2 class="unnumbered anchored" data-anchor-id="book-citation">Book citation</h2>
 <p>You can use the following BibTex entry to cite this book:</p>
-<pre><code>@book{pedro2025,
+<pre><code>@book{pedro2024,
     author = {Pedro Duarte Faria},
     title = {Introduction to Zig},
     subtitle = {a project-based book},
-    month = {February},
-    edition = {2},
-    year = {2025},
+    month = {October},
+    edition = {1},
+    year = {2024},
     address = {Belo Horizonte},
     url = {https://github.com/pedropark99/zig-book}
 }</code></pre>
diff --git a/docs/search.json b/docs/search.json
index 1d2f1f9f..0a1da144 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -64,7 +64,7 @@
     "href": "index.html#book-citation",
     "title": "Introduction to Zig",
     "section": "Book citation",
-    "text": "Book citation\nYou can use the following BibTex entry to cite this book:\n@book{pedro2025,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {February},\n    edition = {2},\n    year = {2025},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}",
+    "text": "Book citation\nYou can use the following BibTex entry to cite this book:\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}",
     "crumbs": [
       "Welcome"
     ]
diff --git a/index.qmd b/index.qmd
index cbe7ef75..f7e81492 100644
--- a/index.qmd
+++ b/index.qmd
@@ -143,13 +143,13 @@ source("./Scripts/zig-quarto-versions.R")
 You can use the following BibTex entry to cite this book:
 
 ```
-@book{pedro2025,
+@book{pedro2024,
     author = {Pedro Duarte Faria},
     title = {Introduction to Zig},
     subtitle = {a project-based book},
-    month = {February},
-    edition = {2},
-    year = {2025},
+    month = {October},
+    edition = {1},
+    year = {2024},
     address = {Belo Horizonte},
     url = {https://github.com/pedropark99/zig-book}
 }

From a18e77edba6d5c4e2f721a878795e4c63b5dd432 Mon Sep 17 00:00:00 2001
From: Lyall Jonathan Di Trapani <lj.ditrapani@gmail.com>
Date: Mon, 17 Feb 2025 14:08:59 -0500
Subject: [PATCH 074/151] Chapter 03-unittests grammer corrections

- Subject is you, so verb is are not is.
- Also, it does, not it do.
---
 Chapters/03-unittests.qmd | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Chapters/03-unittests.qmd b/Chapters/03-unittests.qmd
index 56cfb051..72f8efd6 100644
--- a/Chapters/03-unittests.qmd
+++ b/Chapters/03-unittests.qmd
@@ -109,8 +109,8 @@ that help us, programmers, to avoid (but also detect) memory problems, such as
 memory leaks and double-frees. The `defer` keyword
 is especially helpful in this regard.
 
-When developing your source code, you, the programmer, is responsible for making
-sure that your code do not produce such problems. However,
+When developing your source code, you, the programmer, are responsible for making
+sure that your code does not produce such problems. However,
 you can also use a special type of an allocator object in Zig
 that is capable of automatically detecting such problems for you.
 This is the `std.testing.allocator` object.

From 8b90851de221b72cedef68a0ea019d4ff3a2177d Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Wed, 19 Feb 2025 18:05:03 -0400
Subject: [PATCH 075/151] fix: typos and improve flow

---
 Chapters/10-stack-project.qmd | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Chapters/10-stack-project.qmd b/Chapters/10-stack-project.qmd
index ada7535d..ed37847f 100644
--- a/Chapters/10-stack-project.qmd
+++ b/Chapters/10-stack-project.qmd
@@ -37,8 +37,8 @@ how generics work in Zig.
 
 One of the key features of Zig is `comptime`. This keyword introduces a whole
 new concept and paradigm, that is tightly connected with the compilation process.
-At @sec-compile-time we have described the importance and the role that "compile-time versus runtime"
-plays into Zig. At that section, we learned that the rules applied to a value/object change
+In @sec-compile-time we have described the importance and the role that "compile-time versus runtime"
+plays into Zig. In that section, we learned that the rules applied to a value/object changes
 a lot depending on whether this value is known at compile-time, or just at runtime.
 
 The `comptime` keyword is strongly related to these two spaces in time (compile-time and runtime).
@@ -59,8 +59,8 @@ There are three ways in which you can apply the `comptime` keyword, which are:
 
 When you apply the `comptime` keyword on a function argument, you are saying to the `zig` compiler
 that the value assigned to that particular function argument must be known at compile-time.
-We explained in details at @sec-compile-time what exactly "value known at compile-time" means, so,
-in case you have doubts about this idea, come back to that section.
+We explained in detail in @sec-compile-time what exactly "value known at compile-time" means. So,
+if you have any doubts about this idea, refer back to that section.
 
 Now let's think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement
 to that particular function argument. If the programmer accidentally tries to give a value to this

From 203528b3036f120f3bb9ee28ad7e2e5db429d0f0 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Wed, 19 Feb 2025 18:19:01 -0400
Subject: [PATCH 076/151] fix remaining typos in 12.1

---
 Chapters/10-stack-project.qmd | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/Chapters/10-stack-project.qmd b/Chapters/10-stack-project.qmd
index ed37847f..31521cb5 100644
--- a/Chapters/10-stack-project.qmd
+++ b/Chapters/10-stack-project.qmd
@@ -119,10 +119,10 @@ t.zig:12:16: error: runtime-known argument passed to comptime parameter
 
 Comptime arguments are frequently used on functions that return some sort
 of generic structure. In fact, `comptime` is the essence (or the basis) to make generics in Zig.
-We are going to talk more about generics at @sec-generics.
+We are going to talk more about generics in @sec-generics.
 
 For now, let's take a look at this code example from @karlseguin_generics. You
-can see that this `IntArray()` function have one argument named `length`.
+can see that this `IntArray()` function has one argument named `length`.
 This argument is marked as comptime, and receives a value of type `usize` as input. So the value given to this argument
 must be compile-time known.
 We can also see that this function returns an array of `i64` values as output.
@@ -140,7 +140,7 @@ think about the consequences of that. If the size of the array is dependent on
 the value assigned to the `length` argument, this means that the data type of the
 output of the function depends on the value of this `length` argument.
 
-Let this statement sink for a bit in your mind. As I described at @sec-root-file,
+Let this statement sink for a bit in your mind. As I described in @sec-root-file,
 Zig is a strongly-typed language, especially on function declarations.
 So every time we write a function in Zig, we have to annotate the data type of
 the value returned by the function. But how can we do that, if this data type
@@ -169,8 +169,8 @@ will raise a compilation error.
 
 Take this example from the official documentation of Zig [@zigdocs]. We
 are executing the same `fibonacci()` function both at runtime, and, at compile-time.
-The function is by default executed at runtime, but because we use the `comptime`
-keyword at the second "try expression", this expression is executed at compile-time.
+The function is executed by default at runtime, but because we use the `comptime`
+keyword in the second "try expression", this expression is executed at compile-time.
 
 This might be a bit confusing for some people. Yes! When I say that this expression
 is executed at compile-time, I mean that this expression is compiled and executed
@@ -195,9 +195,9 @@ test "fibonacci" {
 ```
 
 A lot of your Zig source code might be potentially executed at compile-time,
-because the `zig` compiler can figure it out the output of some expressions.
-Especially if these expressions depends only at compile-time known values.
-We have talked about this at @sec-compile-time.
+because the `zig` compiler can figure the output of some expressions.
+Especially if these expressions depend only on compile-time known values.
+We have talked about this in @sec-compile-time.
 
 But when you use the `comptime` keyword on an expression, there is no "it might be executed
 at compile-time" anymore. With the `comptime` keyword you are ordering the `zig` compiler
@@ -209,8 +209,8 @@ the compiler will raise a compilation error.
 
 ### Applying over a block
 
-Blocks were described at @sec-blocks. When you apply the `comptime` keyword over a
-block of expressions, you get essentially the same effect when you apply this keyword to
+Blocks were described in @sec-blocks. When you apply the `comptime` keyword to a
+block of expressions, you get essentially the same effect as when you apply this keyword to
 a single expression. That is, the entire block of expressions is executed at
 compile-time by the `zig` compiler.
 

From ac187274880f7a6e7f46080582a89681790dd54f Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Wed, 19 Feb 2025 19:51:53 -0400
Subject: [PATCH 077/151] fix typos and improve flow

---
 Chapters/10-stack-project.qmd | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Chapters/10-stack-project.qmd b/Chapters/10-stack-project.qmd
index 31521cb5..5640b5e0 100644
--- a/Chapters/10-stack-project.qmd
+++ b/Chapters/10-stack-project.qmd
@@ -266,13 +266,13 @@ input to a piece of code.
 Take the `max()` function exposed below as a first example.
 This function is essentially a "generic function".
 In this function, we have a comptime function argument named `T`.
-Notice that this `T` argument have a data type of `type`. Weird right? This `type` keyword is the
+Notice that this `T` argument has a data type of `type`. Weird right? This `type` keyword is the
 "father of all types", or, "the type of types" in Zig.
 
 Because we have used this `type` keyword in the `T` argument, we are telling
 the `zig` compiler that this `T` argument will receive some data type as input.
 Also notice the use of the `comptime` keyword in this argument.
-As I described at @sec-comptime, every time you use this keyword in a function argument,
+As I described in @sec-comptime, every time you use this keyword in a function argument,
 this means that the value of this argument must be known at compile-time.
 This makes sense, right? Because there is no data type that is not known at compile-time.
 
@@ -300,7 +300,7 @@ As a result, we have a generic function that works with different data types.
 For example, I can provide `u8` values to this `max()` function, and it will work as expected.
 But if I provide `f64` values instead, it will also work as expected.
 Without a generic function, I would have to write a different `max()` function
-for each one of the data types that I wanted to use.
+for each data type I wanted to use.
 This generic function provides a very useful shortcut for us.
 
 ```{zig}
@@ -333,7 +333,7 @@ You just say which is the data type of the values that are going to be stored in
 structure, and they just work as expected.
 
 A generic data structure in Zig is how you replicate a generic class from Java,
-or, a class template from C++. But you may quest yourself: how do we build a
+or, a class template from C++. But you may ask yourself: how do we build a
 generic data structure in Zig?
 
 The basic idea is to write a generic function that creates the data structure definition
@@ -342,7 +342,7 @@ The generic function outputs the `struct` definition that defines this data stru
 specific data type.
 
 To create such function, we need to add a comptime argument to this function that receives a data type
-as input. We already learned how to do this at the previous section (@sec-generic-fun).
+as input. We already learned how to do this in the previous section (@sec-generic-fun).
 I think the best way to demonstrate how to create a generic data structure is to actually write one.
 This where we go into our next small project in this book. This one is a very small project,
 which is to write a generic stack data structure.

From 8fd3dd9ae1b231f2420ed5f69c500fb06a41215f Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Wed, 19 Feb 2025 20:17:35 -0400
Subject: [PATCH 078/151] fix remaining typos and improve flow

---
 Chapters/10-stack-project.qmd | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/Chapters/10-stack-project.qmd b/Chapters/10-stack-project.qmd
index 5640b5e0..f3c27502 100644
--- a/Chapters/10-stack-project.qmd
+++ b/Chapters/10-stack-project.qmd
@@ -390,7 +390,7 @@ we want.
 
 First, we need to decide how the values will be stored inside the stack. There are multiple
 ways to implement the storage behind a stack structure. Some people prefer to use a doubly linked list,
-some others prefer to use a dynamic array, etc. In this example we are going to use an array behind the hood,
+others prefer to use a dynamic array, etc. In this example we are going to use an array behind the hood,
 to store the values in the stack, which is the `items` data member of our `Stack` struct definition.
 
 Also notice in our `Stack` struct that we have three other data members: `capacity`, `length` and `allocator`.
@@ -438,7 +438,7 @@ responsible for adding a new value to the stack.
 
 So how can we add a new value to the `Stack` object that we have?
 The `push()` function exposed below is a possible answer to this question.
-Remember from what we discussed at @sec-what-stack that values are always added to the top of the stack.
+Remember from what we discussed in @sec-what-stack that values are always added to the top of the stack.
 This means that this `push()` function must always find the element in the underlying array
 that currently represents the top position of the stack, and then, add the input value there.
 
@@ -558,14 +558,14 @@ pub fn deinit(self: *Stack) void {
 ## Making it generic
 
 Now that we have implemented the basic skeleton of our stack data structure,
-we can now focus on discussing how can we make it generic. How can we make
-this basic skeleton to work not only with `u32` values, but also, with any other
+we can now focus on discussing how we can make it generic. How can we make
+this basic skeleton to work not only with `u32` values, but also with any other
 data type we want?
 For example, we might need to create a stack object to store `User` values
-in it. How can we make this possible? The answer lies on the use of generics
+in it. How can we make this possible? The answer lies in the use of generics
 and `comptime`.
 
-As I described at @sec-generic-struct, the basic idea is to write a generic
+As I described in @sec-generic-struct, the basic idea is to write a generic
 function that returns a struct definition as output.
 In theory, we do not need much to transform our `Stack` struct into a generic
 data structure. All that we need to do is to transform the underlying array
@@ -573,7 +573,7 @@ of the stack into a generic array.
 
 In other words, this underlying array needs to be a "chameleon". It needs to adapt,
 and transform it into an array of any data type that we want. For example, if we need to create
-a stack that will store `u8` values, then, this underlying array needs to be
+a stack that will store `u8` values, then this underlying array needs to be
 a `u8` array (i.e. `[]u8`). But if we need to store `User` values instead, then,
 this array needs to be a `User` array (i.e. `[]User`). Etc.
 
@@ -585,7 +585,7 @@ we pass the `User` data type to this generic function, and it will create for us
 the struct definition that describes a `Stack` object that can store `User` values in it.
 
 Look at the code example below. I have omitted some parts of the `Stack` struct definition
-for brevity reasons. However, if a specific part of our `Stack` struct is not exposed here
+for brevity. However, if a specific part of our `Stack` struct is not exposed here
 in this example, then it is because this part did not change from the previous example.
 It remains the same.
 
@@ -677,7 +677,7 @@ with the data type that you provided as input.
 
 ## Conclusion
 
-The full source code of the stack structure discussed in this chapter is freely available at the official
+The full source code of the stack structure discussed in this chapter is freely available in the official
 repository of this book. Just checkout the [`stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig)[^zig-stack]
 for the `u32` version of our stack,
 and the [`generic_stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig)[^zig-stack2]

From 6421a9625ac0caf372b08f5be9b9aaeb7d39590b Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Wed, 19 Feb 2025 20:18:13 -0400
Subject: [PATCH 079/151] change 'at' to 'in'

---
 Chapters/10-stack-project.qmd | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Chapters/10-stack-project.qmd b/Chapters/10-stack-project.qmd
index f3c27502..40e95dbf 100644
--- a/Chapters/10-stack-project.qmd
+++ b/Chapters/10-stack-project.qmd
@@ -156,7 +156,7 @@ and raise a compilation error, saying something like this:
 So how can you solve this problem? How do we overcome this barrier? This is when
 the `type` keyword comes in. This `type` keyword is basically saying to the
 `zig` compiler that this function will return some data type as output, but it doesn't know yet
-what exactly data type that is. We will talk more about this at @sec-generics.
+what exactly data type that is. We will talk more about this in @sec-generics.
 
 
 
@@ -246,7 +246,7 @@ test "fibonacci in a block" {
 
 First of all, what is a generic? Generic is the idea to allow a type
 (`f64`, `u8`, `u32`, `bool`, and also, user-defined types, like the `User` struct
-that we defined at @sec-structs-and-oop) to be a parameter to methods, classes and
+that we defined in @sec-structs-and-oop) to be a parameter to methods, classes and
 interfaces [@geeks_generics]. In other words, a "generic" is a class (or a method) that can work
 with multiple data types.
 

From a36e065eb4d99b3a8ae8cec60987aba4577440f7 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Thu, 20 Feb 2025 11:32:45 -0400
Subject: [PATCH 080/151] fix: typos in 17.1

---
 Chapters/15-vectors.qmd | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Chapters/15-vectors.qmd b/Chapters/15-vectors.qmd
index 94019c19..c5c490f9 100644
--- a/Chapters/15-vectors.qmd
+++ b/Chapters/15-vectors.qmd
@@ -32,10 +32,10 @@ was only used on "supercomputer models".
 
 Most modern CPU models (from AMD, Intel, etc.) these days (either in a desktop or in a
 notebook model) have support for SIMD operations. So, if you have a very old CPU model installed in your
-computer, then, is possible that you have no support for SIMD operations in your computer.
+computer, then, it is possible that you have no support for SIMD operations in your computer.
 
-Why people have started using SIMD on their software? The answer is performance.
-But what SIMD precisely do to achieve better performance? Well, in essence, SIMD operations are a different
+Why have people started using SIMD in their software? The answer is performance.
+But what does SIMD precisely do to achieve better performance? Well, in essence, SIMD operations are a different
 strategy to get parallel computing in your program, and therefore, make faster calculations.
 
 The basic idea behind SIMD is to have a single instruction that operates over multiple data

From d76969afd70b6bdde283fc0092cec5fcb3f5aafd Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Thu, 20 Feb 2025 13:04:03 -0400
Subject: [PATCH 081/151] fix typos in 12.2

---
 Chapters/15-vectors.qmd | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Chapters/15-vectors.qmd b/Chapters/15-vectors.qmd
index c5c490f9..c22c745b 100644
--- a/Chapters/15-vectors.qmd
+++ b/Chapters/15-vectors.qmd
@@ -61,7 +61,7 @@ always operate over a special type of object, which are called "vectors". So,
 in order to use SIMD, you have to create a "vector object".
 
 A vector object is usually a fixed-sized block of 128 bits (16 bytes).
-As consequence, most vectors that you find in the wild are essentially arrays that contains 2 values of 8 bytes each,
+As a consequence, most vectors that you find in the wild are essentially arrays that contains 2 values of 8 bytes each,
 or, 4 values of 4 bytes each, or, 8 values of 2 bytes each, etc.
 However, different CPU models may have different extensions (or, "implementations") of SIMD,
 which may offer more types of vector objects that are bigger in size (256 bits or 512 bits)
@@ -154,12 +154,12 @@ try stdout.print("{any}\n", .{v1});
 
 ### Careful with vectors that are too big
 
-As I described at @sec-what-vectors, each vector object is usually a small block of 128, 256 or 512 bits.
+As I described in @sec-what-vectors, each vector object is usually a small block of 128, 256 or 512 bits.
 This means that a vector object is usually small in size, and when you try to go in the opposite direction,
 by creating a vector object that is very big in size (i.e. sizes that are close to $2^{20}$),
 you usually end up with crashes and loud errors from the compiler.
 
-For example, if you try to compile the program below, you will likely face segmentation faults, or, LLVM errors during
+For example, if you try to compile the program below, you will likely face segmentation faults, or LLVM errors during
 the build process. Just be careful to not create vector objects that are too big in size.
 
 ```{zig}

From f4e9a8e66c0d175e961a00a13654c838080725ac Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Thu, 20 Feb 2025 13:22:46 -0400
Subject: [PATCH 082/151] fix typos and improve flow in 16.1

---
 Chapters/14-threads.qmd | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/Chapters/14-threads.qmd b/Chapters/14-threads.qmd
index 8ddbc00a..001ecf7a 100644
--- a/Chapters/14-threads.qmd
+++ b/Chapters/14-threads.qmd
@@ -36,31 +36,31 @@ parallelism. And when we don't have parallelism, the commands are executed seque
 only one command is executed at a time, one after another. By creating multiple threads inside our program,
 we start to execute multiple commands at the same time.
 
-Programs that create multiple threads are very common on the wild. Because many different types
+Programs that create multiple threads are very common in the wild. Because many different types
 of applications are well suited for parallelism. Good examples are video and photo-editing applications
 (e.g. Adobe Photoshop or DaVinci Resolve), games (e.g. The Witcher 3), and also web browsers
 (e.g. Google Chrome, Firefox, Microsoft Edge, etc).
 For example, in web browsers, threads are normally used to implement tabs.
 The tabs in a web browsers usually run as separate threads in the main process of
-the web browser. That is, each new tab that you open in your web browser,
+the web browser. That is, each new tab that you open in your web browser
 usually runs on a separate thread of execution.
 
 By running each tab in a separate thread, we allow all open tabs in the browser to run at the same time,
-and independently from each other. For example, you might have YouTube, or Spotify, currently opened in
-a tab, and you are listening to some podcast in that tab, while, at the same time,
-you are working in another tab, writing an essay on Google Docs. Even if you are not looking
+and independently from each other. For example, you might have YouTube or Spotify currently open in
+a tab, and you are listening to some podcast in that tab while at the same time
+working in another tab, writing an essay on Google Docs. Even if you are not looking
 into the YouTube tab, you can still hear the podcast only because this YouTube tab is running in parallel
 with the other tab where Google Docs is running.
 
 Without threads, the other alternative would be to run each tab as a completely separate
-process in your computer. But that would be a bad choice, because just a few tabs would already consume
-too much power and resources from your computer. In other words, is very expensive to create a completely new process,
+process in your computer. But that would be a bad choice because just a few tabs would already consume
+too much power and resources from your computer. In other words, it is very expensive to create a completely new process,
 compared to creating a new thread of execution. Also, the chances of you experiencing lag and overhead
 while using the browser would be significant. Threads are faster to create, and they also consume
 much, much less resources from the computer, especially because they share some resources
 with the main process.
 
-Therefore, is the use of threads in modern web browsers that allows you to hear the podcast
+Therefore, it is the use of threads in modern web browsers that allow you to hear the podcast
 at the same time while you are writing something on Google Docs.
 Without threads, a web browser would probably be limited to just one single tab.
 
@@ -78,9 +78,9 @@ the following steps:
 If you think about the bullet points above, you will notice that one big moment of waiting time
 is present in this whole process, which is while the food is being cooked
 inside the kitchen. While the food is being prepped, both the waiter and the client
-itself are waiting for the food to be ready and delivered.
+themselves are waiting for the food to be ready and delivered.
 
-If we write a program to represent this restaurant, more specifically, a single-threaded program, then,
+If we write a program to represent this restaurant, more specifically, a single-threaded program, then
 this program would be very inefficient. Because the program would stay in idle, waiting for a considerable amount
 of time on the "check if food is ready" step. Consider the code snippet exposed below that could
 potentially represent such program.

From dfcd1036567af8993bac3366b049d68ddbaf0d85 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Thu, 20 Feb 2025 13:31:00 -0400
Subject: [PATCH 083/151] fix: change 'have' to 'has' in 16.2

---
 Chapters/14-threads.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/14-threads.qmd b/Chapters/14-threads.qmd
index 001ecf7a..ee9c6634 100644
--- a/Chapters/14-threads.qmd
+++ b/Chapters/14-threads.qmd
@@ -186,7 +186,7 @@ is on the heap, then, the other threads can potentially access this object.
 
 Therefore, objects that are stored in the stack are local to the thread where they were created.
 But objects that are stored on the heap are potentially accessible to other threads. All of this means that,
-each thread have its own separate stack frame, but, at the same time, all threads share
+each thread has its own separate stack frame, but, at the same time, all threads share
 the same heap, the same standard file descriptors (which means that they share the same `stdout`, `stdin`, `stderr`),
 and the same global data section in the program.
 

From bc381754ff9b16076a4b561aec67e94e6c7fff06 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Thu, 20 Feb 2025 13:34:18 -0400
Subject: [PATCH 084/151] remove extra commas

---
 Chapters/14-threads.qmd | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Chapters/14-threads.qmd b/Chapters/14-threads.qmd
index ee9c6634..a2de242f 100644
--- a/Chapters/14-threads.qmd
+++ b/Chapters/14-threads.qmd
@@ -194,9 +194,9 @@ and the same global data section in the program.
 
 ## Creating a thread
 
-We create new threads in Zig, by first, importing the `Thread` struct into
-our current Zig module, and then, calling the `spawn()` method of this struct,
-which creates (or, "spawns") a new thread of execution from our current process.
+We create new threads in Zig by first importing the `Thread` struct into
+our current Zig module and then calling the `spawn()` method of this struct,
+which creates (or "spawns") a new thread of execution from our current process.
 This method have three arguments, which are, respectively:
 
 1. a `SpawnConfig` object, which contains configurations for the spawn process.

From fe9e6505f4a0d5b3959ec8a1904e7037ad41b86c Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Thu, 20 Feb 2025 14:05:15 -0400
Subject: [PATCH 085/151] fix typos

---
 Chapters/14-threads.qmd | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Chapters/14-threads.qmd b/Chapters/14-threads.qmd
index a2de242f..4a4e011c 100644
--- a/Chapters/14-threads.qmd
+++ b/Chapters/14-threads.qmd
@@ -197,17 +197,17 @@ and the same global data section in the program.
 We create new threads in Zig by first importing the `Thread` struct into
 our current Zig module and then calling the `spawn()` method of this struct,
 which creates (or "spawns") a new thread of execution from our current process.
-This method have three arguments, which are, respectively:
+This method has three arguments, which are, respectively:
 
 1. a `SpawnConfig` object, which contains configurations for the spawn process.
-1. the name of the function that is going to be executed (or, that is going to be "called") inside this new thread.
+1. the name of the function that is going to be executed (or that is going to be "called") inside this new thread.
 1. a list of arguments (or inputs) to be passed to the function provided in the second argument.
 
-With these three arguments, you can control how the thread get's created, and also, specify which
+With these three arguments, you can control how the thread gets created, and also, specify which
 work (or "tasks") will be performed inside this new thread. A thread is just a separate context of execution,
-and we usually create new threads in our code, because we want to perform some work inside this
-new context of execution. And we specify which exact work, or, which exact steps that are going to be
-performed inside this context, by providing the name of a function on the second argument of the `spawn()` method.
+and we usually create new threads in our code because we want to perform some work inside this
+new context of execution. And we specify which exact work, or which exact steps that are going to be
+performed inside this context by providing the name of a function as the second argument of the `spawn()` method.
 
 Thus, when this new thread get's created, this function that you provided as input to the `spawn()`
 method get's called, or, get's executed inside this new thread. You can control the

From 5c9555c421a98bb922eeafc329319fb90845b5e3 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Thu, 20 Feb 2025 14:39:57 -0400
Subject: [PATCH 086/151] fix typos and improve flow in 16.3

---
 Chapters/14-threads.qmd | 28 ++++++++++++++--------------
 1 file changed, 14 insertions(+), 14 deletions(-)

diff --git a/Chapters/14-threads.qmd b/Chapters/14-threads.qmd
index 4a4e011c..b2c19155 100644
--- a/Chapters/14-threads.qmd
+++ b/Chapters/14-threads.qmd
@@ -209,9 +209,9 @@ and we usually create new threads in our code because we want to perform some wo
 new context of execution. And we specify which exact work, or which exact steps that are going to be
 performed inside this context by providing the name of a function as the second argument of the `spawn()` method.
 
-Thus, when this new thread get's created, this function that you provided as input to the `spawn()`
-method get's called, or, get's executed inside this new thread. You can control the
-arguments, or, the inputs that are passed to this function when it get's called, by providing
+Thus, when this new thread gets created, this function that you provided as input to the `spawn()`
+method gets called, or gets executed inside this new thread. You can control the
+arguments, or the inputs that are passed to this function when it gets called by providing
 a list of arguments (or a list of inputs) on the third argument of the `spawn()` method.
 These arguments are passed to the function in the same order that they are
 provided to `spawn()`.
@@ -219,13 +219,13 @@ provided to `spawn()`.
 Furthermore, the `SpawnConfig` is a struct object with only two possible fields, or, two possible members, that you
 can set to tailor the spawn behaviour. These fields are:
 
-- `stack_size`: you can provide an `usize` value to specify the size (in bytes) of the thread's stack frame. By default, this value is: $16 \times 1024 \times 1024$.
+- `stack_size`: you can provide a `usize` value to specify the size (in bytes) of the thread's stack frame. By default, this value is: $16 \times 1024 \times 1024$.
 - `allocator`: you can provide an allocator object to be used when allocating memory for the thread.
 
-To use one of these two fields (or, "configs") you just have to create a new object of type `SpawnConfig`,
+To use one of these two fields (or "configs"), you just have to create a new object of type `SpawnConfig`,
 and provide this object as input to the `spawn()` method. But, if you are not interested in using
 one of these configs, and you are ok with using just the defaults, you can just provide an anonymous
-struct literal (`.{}`) in the place of this `SpawnConfig` argument.
+struct literal (`.{}`) in place of this `SpawnConfig` argument.
 
 As our first, and very simple example, consider the code exposed below.
 Inside the same program, you can create multiple threads of execution if you want to.
@@ -234,8 +234,8 @@ we call `spawn()` only once.
 
 Also, notice in this example that we are executing the function `do_some_work()`
 inside the new thread. Since this function receives no inputs, because it has
-no arguments, we have passed an empty list in this instance, or, more precisely,
-an empty and anonymous struct (`.{}`) in the third argument of `spawn()`.
+no arguments, we have passed an empty list in this instance, or more precisely,
+an empty, anonymous struct (`.{}`) in the third argument of `spawn()`.
 
 
 ```{zig}
@@ -264,13 +264,13 @@ But, if the new thread is successfully created, the `spawn()` method returns a h
 object (which is just an object of type `Thread`) to this new thread. You can use
 this handler object to effectively control all aspects of the thread.
 
-When the thread get's created, the function that you provided as input to `spawn()`
-get's invoked (i.e. get's called) to start the execution on this new thread.
-In other words, everytime you call `spawn()`, not only a new thread get's created,
-but also, the "start work button" of this thread get's automatically pressed.
-So the work being performed in this thread starts at the moment that the thread is created.
+When the thread gets created, the function that you provided as input to `spawn()`
+gets invoked (i.e. gets called) to start the execution on this new thread.
+In other words, every time you call `spawn()`, not only is a new thread created,
+but the "start work button" of this thread is also automatically pressed.
+So the work being performed in this thread starts as soon as the thread is created.
 This is similar to how `pthread_create()` from the `pthreads` library in C works,
-which also starts the execution at the moment that the thread get's created.
+which also starts the execution as soon as the thread is created.
 
 
 ## Returning from a thread

From d3d5fbb0b3e8827dc0f9c3858403019ab698449d Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Thu, 20 Feb 2025 15:04:38 -0400
Subject: [PATCH 087/151] fix typos and improve flow in 16.4.1

---
 Chapters/14-threads.qmd | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/Chapters/14-threads.qmd b/Chapters/14-threads.qmd
index b2c19155..2e42ae05 100644
--- a/Chapters/14-threads.qmd
+++ b/Chapters/14-threads.qmd
@@ -275,15 +275,15 @@ which also starts the execution as soon as the thread is created.
 
 ## Returning from a thread
 
-We have learned on the previous section that the execution of the thread starts at the moment
-that the thread get's created. Now, we will learn how to "join" or "detach" a thread in Zig.
+We have learned in the previous section that the execution of the thread starts as soon as
+the thread is created. Now, we will learn how to "join" or "detach" a thread in Zig.
 "Join" and "detach" are operations that control how the thread returns to
-the main thread, or, to the main process in our program.
+the main thread, or to the main process in our program.
 
 We perform these operations by using the methods `join()` and `detach()` from the thread handler object.
 Every thread that you create can be marked as either *joinable* or *detached* [@linux_pthread_create].
 You can turn a thread into a *detached* thread by calling the `detach()` method
-from the thread handler object. But if you call the `join()` method instead, then, this thread
+from the thread handler object. But if you call the `join()` method instead, then this thread
 becomes a *joinable* thread.
 
 A thread cannot be both *joinable* and *detached*. Which in general means
@@ -291,7 +291,7 @@ that you cannot call both `join()` and `detach()` on the same thread.
 But a thread must be one of the two, meaning that, you should always call
 either `join()` or `detach()` over a thread. If you don't call
 one of these two methods over your thread, you introduce undefined behaviour into your program,
-which is described at @sec-not-call-join-detach.
+which is described in @sec-not-call-join-detach.
 
 Now, let's describe what each of these two methods do to your thread.
 
@@ -299,13 +299,13 @@ Now, let's describe what each of these two methods do to your thread.
 ### Joining a thread
 
 When you join a thread, you are essentially saying: "Hey! Could you please wait for the thread to finish,
-before you continue with your execution?". For example, if we comeback to our first and simpliest example
-of a thread in Zig, in that example we have created a single thread inside the `main()` function of our program,
-and just called `join()` over this thread at the end. This section of the code example is reproduced below.
+before you continue with your execution?". For example, if we come back to our first and simplest example
+of a thread in Zig, we created a single thread inside the `main()` function of our program
+and just called `join()` on this thread at the end. This section of the code example is reproduced below.
 
 Because we are joining this new thread inside the `main()`'s scope, it means that the
 execution of the `main()` function is temporarily stopped, to wait for the execution of the thread
-to finish. That is, the execution of `main()` stops temporarily at the line where `join()` get's called,
+to finish. That is, the execution of `main()` stops temporarily at the line where `join()` gets called,
 and it will continue only after the thread has finished its tasks.
 
 ```{zig}
@@ -332,11 +332,11 @@ we wait for two whole seconds, then, at last, we join the second thread.
 
 The idea behind this example is that the last `join()` call is executed
 only after the first thread finishes its task (i.e. the first `join()` call),
-and also, after the two seconds of delay. If you compile and run this
+and the two-second delay. If you compile and run this
 example, you will notice that most messages are quickly printed to `stdout`,
 i.e. they appear almost instantly on your screen.
 However, the last message ("Joining thread 2") takes around 2 seconds to appear
-in the screen.
+on the screen.
 
 
 ```{zig}
@@ -369,7 +369,7 @@ Joining thread 2
 This demonstrates that both threads finish their work (i.e. printing the IDs)
 very fast, before the two seconds of delay end. Because of that, the last `join()` call
 returns pretty much instantly. Because when this last `join()` call happens, the second
-thread have already finished its task.
+thread has already finished its task.
 
 Now, if you compile and run this example, you will also notice that, in some cases,
 the messages intertwine with each other. In other words, you might see
@@ -379,12 +379,12 @@ or vice-versa. This happens because:
 - the threads are executing basically at the same time as the main process of the program (i.e. the `main()` function).
 - the threads share the same `stdout` from the main process of the program, which means that the messages that the threads produce are sent to exact same place as the messages produced by the main process.
 
-Both of these points were described previously at @sec-what-thread.
+Both of these points were described previously in @sec-what-thread.
 So the messages might get intertwined because they are being produced and
 sent to the same `stdout` roughly at the same time.
 Anyway, when you call `join()` over a thread, the current process will wait
-for the thread to finish before it continues, and, when the thread does finishes its
-task, the resources associated with this thread are automatically freed, and,
+for the thread to finish before it continues, and, when the thread finishes its
+task, the resources associated with this thread are automatically freed, and
 the current process continues with its execution.
 
 

From 38aa394cf23ae284bd91661b22e7f82d0bd2d13f Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Thu, 20 Feb 2025 15:14:28 -0400
Subject: [PATCH 088/151] fix typos in 16.4.2

---
 Chapters/14-threads.qmd | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Chapters/14-threads.qmd b/Chapters/14-threads.qmd
index 2e42ae05..0491c3b1 100644
--- a/Chapters/14-threads.qmd
+++ b/Chapters/14-threads.qmd
@@ -393,11 +393,11 @@ the current process continues with its execution.
 When you detach a thread, the resources associated with this thread are automatically
 released back to the system, without the need for another thread to join with this terminated thread.
 
-In other words, when you call `detach()` over a thread it's like when your children becomes adults,
-i.e. they become independent from you. A detached thread frees itself, and when this thread finishes its
+In other words, when you call `detach()` on a thread it's like when your children become adults,
+i.e., they become independent from you. A detached thread frees itself, and when this thread finishes its
 tasks, it does not report the results back to you. Thus, you normally mark a thread as *detached*
-when you don't need to use the return value of the thread, or, when you don't care about
-when exactly the thread finishes its job, i.e. the thread solves everything by itself.
+when you don't need to use the return value of the thread, or when you don't care about
+when exactly the thread finishes its job, i.e., the thread solves everything by itself.
 
 Take the code example below. We create a new thread, detach it, and then, we just
 print a final message before we end our program. We use the same `print_id()`
@@ -425,10 +425,10 @@ Finish main
 Now, if you look closely at the output of this code example, you will notice
 that only the final message in main was printed to the console. The message
 that was supposed to be printed by `print_id()` did not appear in the console.
-Why? Is because the main process of our program has finished first,
+Why? It is because the main process of our program has finished first,
 before the thread was able to say anything.
 
-And that is perfectly ok behaviour, because the thread was detached, so, it was
+And that is perfectly ok behaviour, because the thread was detached, so it was
 able to free itself, without the need to wait for the main process.
 If you ask main to sleep (or "wait") for some extra nanoseconds, before it ends, you will likely
 see the message printed by `print_id()`, because you give enough time for the thread to

From d72671f95d6e57cda94cb2307edf9422f1a8ecf2 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Sat, 22 Feb 2025 04:09:47 -0400
Subject: [PATCH 089/151] fix typos in 16.5

---
 Chapters/14-threads.qmd | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Chapters/14-threads.qmd b/Chapters/14-threads.qmd
index 0491c3b1..60267be6 100644
--- a/Chapters/14-threads.qmd
+++ b/Chapters/14-threads.qmd
@@ -438,8 +438,8 @@ finish before the main process ends.
 ## Thread pools
 
 Thread pools is a very popular programming pattern, which is used especially on servers and daemons processes.
-A thread pool is just a set of threads, or, a "pool" of threads. Many programmers like to use this pattern, because it makes
-easier to manage and use multiple threads in your program, instead of manually creating the threads when you need them.
+A thread pool is just a set of threads, or a "pool" of threads. Many programmers like to use this pattern because it makes
+it easier to manage and use multiple threads in your program, instead of manually creating the threads when you need them.
 
 Also, using thread pools might increase performance as well in your program,
 especially if your program is constantly creating threads to perform short-lived tasks.
@@ -449,7 +449,7 @@ in this constant process of creating and destroying threads.
 
 The main idea behind a thread pool is to have a set of threads already created and ready to perform
 tasks at all times. You create a set of threads at the moment that your program starts, and keep
-these threads alive while your program runs. Each of these threads will be either performing a task, or,
+these threads alive while your program runs. Each of these threads will be either performing a task, or
 waiting for a task to be assigned.
 Every time a new task emerges in your program, this task is added to a "queue of tasks",
 and the moment that a thread becomes available and ready to perform a new task,
@@ -503,17 +503,17 @@ To assign a task to be performed by a thread, we need to call the `spawn()` meth
 from the thread pool object.
 
 This `spawn()` method works identical to the `spawn()` method from the
-`Thread` object. The method have almost the same arguments as the previous one,
+`Thread` object. The method has almost the same arguments as the previous one,
 more precisely, we don't have to provide a `SpawnConfig` object in this case.
 But instead of creating a new thread, this `spawn()` method from
-the thread pool object just register a new task in the internal "queue of tasks" to be performed,
+the thread pool object just registers a new task in the internal "queue of tasks" to be performed,
 and any available thread in the pool will get this task, and it will simply perform the task.
 
 In the example below, we are using our previous `print_id()` function once again.
 But you may notice that the `print_id()` function is a little different this time,
 because now we are using `catch` instead of `try` in the `print()` call.
 Currently, the `Pool` struct only supports functions that don't return errors
-as tasks. Thus, when assigning tasks to threads in a thread pool, is essential to use functions
+as tasks. Thus, when assigning tasks to threads in a thread pool, it is essential to use functions
 that don't return errors. That is why we are using `catch` here, so that the
 `print_id()` function don't return an error.
 

From 3dcc938ed4cf779cb2bf95d195bcc145207a746d Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Sat, 22 Feb 2025 04:18:54 -0400
Subject: [PATCH 090/151] void return type does not need to be discarded
 explicitly

---
 Chapters/14-threads.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/14-threads.qmd b/Chapters/14-threads.qmd
index 60267be6..4a6735a3 100644
--- a/Chapters/14-threads.qmd
+++ b/Chapters/14-threads.qmd
@@ -492,7 +492,7 @@ pub fn main() !void {
         .allocator = allocator,
     };
     var pool: Pool = undefined;
-    _ = try pool.init(opt);
+    try pool.init(opt);
     defer pool.deinit();
 }
 ```

From 134a3e2b9d2af98d4047c250c2d6ec81ef42e704 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Sat, 22 Feb 2025 04:29:20 -0400
Subject: [PATCH 091/151] fix typos and improve flow in 16.6 intro

---
 Chapters/14-threads.qmd | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/Chapters/14-threads.qmd b/Chapters/14-threads.qmd
index 4a6735a3..37243b9f 100644
--- a/Chapters/14-threads.qmd
+++ b/Chapters/14-threads.qmd
@@ -552,17 +552,17 @@ and, therefore, major bugs and undefined behaviour that are usually difficult to
 
 The main idea behind a mutex is to help us to control the execution of a particular section of the code, and to
 prevent two or more threads from executing this particular section of the code at the same time.
-Many programmers like to compare a mutex to a bathroom door (which usually have a lock).
-When a thread locks its own mutex object, it is like if the bathroom door was locked,
-and, therefore, the other people (in this case, the other threads) that wants to use the same bathroom at the same time
-have to be patient, and simply wait for the other person (or the other thread) to unlock the door and get out of the bathroom.
+Many programmers like to compare a mutex to a bathroom door (which typically has a lock).
+When a thread locks its own mutex object, it is like if the bathroom door was locked.
+Therefore, other people (in this case, other threads) who want to use the same bathroom at the same time
+must be patient and simply wait for the current occupant (or thread) to unlock the door and get out of the bathroom.
 
 Some other programmers also like to explain mutexes by using the analogy of "each person will have their turn to speak".
 This is the analogy used on the [*Multithreading Code* video from the Computerphile project](https://www.youtube.com/watch?v=7ENFeb-J75k&ab_channel=Computerphile)[^computerphile].
 Imagine if you are in a conversation circle. There is a moderator in this circle, which is the person that decides who
-have the right to speak at that particular moment. The moderator gives a green card (or some sort of an authorization card) to the person that
+has the right to speak at that particular moment. The moderator gives a green card (or some sort of an authorization card) to the person that
 is going to speak, and, as a result, everyone else must be silent and hear this person that has the green card.
-When the person finishes talking, it gives the green card back to the moderator, and the moderator decides
+When the person finishes talking, they give the green card back to the moderator, and the moderator decides
 who is going to talk next, and delivers the green card to that person. And the cycle goes on like this.
 
 [^computerphile]: <https://www.youtube.com/watch?v=7ENFeb-J75k&ab_channel=Computerphile>
@@ -572,7 +572,7 @@ A mutex acts like the moderator in this conversation circle. The mutex authorize
 and it also blocks the other threads from executing this same section of the code. If these other threads want to execute this same
 piece of the code, they are forced to wait for the the authorized thread to finish first.
 When the authorized thread finishes executing this code, the mutex authorizes the next thread to execute this code,
-and the other threads are still blocked. Therefore, a mutex is like a moderator that does a "each
+while the remaining threads remain blocked. Therefore, a mutex is like a moderator that does a "each
 thread will have their turn to execute this section of the code" type of control.
 
 
@@ -584,7 +584,7 @@ When a thread tries to run this code that is locked by a mutex, this thread stop
 and patiently waits for this section of the codebase to be unlocked to continue.
 
 Notice that mutexes are normally used to lock areas of the codebase that access/modify data that is **shared** with all threads,
-i.e. objects that are either stored in the global data section, or, in the heap space of your program.
+i.e., objects that are either stored in the global data section, or in the heap space of your program.
 So mutexes are not normally used on areas of the codebase that access/modify objects that are local to the thread.
 
 

From 2aac3469343277a03bbce53af8de88cbbdbe802c Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Sat, 22 Feb 2025 04:37:25 -0400
Subject: [PATCH 092/151] fix typos and improve flow in 16.6.3

---
 Chapters/14-threads.qmd | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/Chapters/14-threads.qmd b/Chapters/14-threads.qmd
index 37243b9f..8d022f50 100644
--- a/Chapters/14-threads.qmd
+++ b/Chapters/14-threads.qmd
@@ -611,27 +611,27 @@ and they summarise well the role that a critical section plays in the thread syn
 ### Atomic operations {#sec-atomic-operation}
 
 You will also see the term "atomic operation" a lot when reading about threads, race conditions and mutexes.
-In summary, an operation is categorized as "atomic", when there is no way to happen a context switch in
-the middle of this operation. In other words, this operation is always done from beginning to end, without interruptions
+In summary, an operation is categorized as "atomic" when a context switch cannot occur in
+the middle of the operation. In other words, this operation is always done from beginning to end, without interruptions
 of another process or operation in the middle of its execution phase.
 
-Not many operations today are atomic. But why atomic operations matters here? Is because data races
+Not many operations today are atomic. But why do atomic operations matter here? It is because data races
 (which is a type of a race condition) cannot happen on operations that are atomic.
-So if a particular line in your code performs an atomic operation, then, this line will never
+So if a particular line in your code performs an atomic operation, then this line will never
 suffer from a data race problem. Therefore, programmers sometimes use an atomic operation
 to protect themselves from data race problems in their code.
 
 When you have an operation that is compiled into just one single assembly instruction, this operation might be atomic,
 because it is just one assembly instruction. But this is not guaranteed. This is usually true for old CPU architectures
-(such as `x86`). But nowadays, most assembly instructions in modern CPU architectures turn into multiple micro-tasks,
-which inherently makes the operation not atomic anymore, even though it has just one single assembly instruction.
+(such as `x86`). But nowadays, most assembly instructions in modern CPU architectures are broken down into multiple micro-tasks,
+which inherently makes the operation non-atomic, even if it consists of a single assembly instruction.
 
-The Zig Standard Library offers some atomic functionality at the `std.atomic` module.
+The Zig Standard Library offers some atomic functionality in the `std.atomic` module.
 In this module, you will find a public and generic function called `Value()`. With this function we create an "atomic object", which is
 a value that contains some native atomic operations, most notably, a `load()` and a `fetchAdd()` operation.
 If you have experience with multithreading in C++, you probably have recognized this pattern. So yes, this generic
 "atomic object" in Zig is essentially identical to the template struct `std::atomic` from the C++ Standard Library.
-Is important to emphasize that only primitive data types (i.e. the types presented at @sec-primitive-data-types)
+It is important to emphasize that only primitive data types (i.e. the types presented in @sec-primitive-data-types)
 are supported by these atomic operations in Zig.
 
 

From eb1b694182dc70dc309b1394c61d9ee8b56c4711 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Sat, 22 Feb 2025 04:52:19 -0400
Subject: [PATCH 093/151] fix typos and improve flow in 16.6.3

---
 Chapters/14-threads.qmd | 44 ++++++++++++++++++++---------------------
 1 file changed, 22 insertions(+), 22 deletions(-)

diff --git a/Chapters/14-threads.qmd b/Chapters/14-threads.qmd
index 8d022f50..878a916a 100644
--- a/Chapters/14-threads.qmd
+++ b/Chapters/14-threads.qmd
@@ -641,21 +641,21 @@ are supported by these atomic operations in Zig.
 ### Data races and race conditions
 
 To understand why mutexes are used, we need to understand better the problem that they seek
-to solve, which can be summarized into data races problems. A data race problem is a type of a race condition,
+to solve, which can be summarized into data race problems. A data race problem is a type of a race condition,
 which happens when one thread is accessing a particular memory location (i.e. a particular shared object) at the same
 time that another thread is trying to write/save new data into this same memory location (i.e. the same shared object).
 
 We can simply define a race condition as any type of bug in your program that is based
-on a "who get's there first" problem. A data race problem is a type of a race condition, because it occurs when two or more parties
+on a "who gets there first" problem. A data race problem is a type of a race condition, because it occurs when two or more parties
 are trying to read and write into the same memory location at the same time, and, therefore, the end result of this operation
-depends completely on who get's to this memory location first.
-As consequence, a program that have a data race problem will likely produce a different result each time that we execute it.
+depends completely on who gets to this memory location first.
+As a consequence, a program that has a data race problem will likely produce a different result each time that we execute it.
 
 Thus, race conditions produce undefined behaviour and unpredictability because the program produces
-a different answer in each time that a different person get's to the target location first than the others.
-And we have no easy way to either predict or control who is getting to this target location first.
-In other words, in each execution of your program, you get a different answer, because a different person,
-or, a different function, or, a different part of the code is finishing its tasks first than the others.
+a different answer each time a different person gets to the target location before the others.
+And, we have no easy way to either predict or control who is getting to this target location first.
+In other words, each time your program runs, you may get a different answer because a different person,
+function, or part of the code finishes its tasks before the others.
 
 As an example, consider the code snippet exposed below. In this example, we create a global counter
 variable, and we also create an `increment()` function, whose job is to just increment this global counter
@@ -668,8 +668,8 @@ to print 2 hundred thousand at the end, but in practice, every time that I execu
 I get a different answer.
 
 In the example exposed below, you can see that this time the end
-result was 117254, instead of the expected 200000. The second time I have executed this program,
-I got the number 108592 as result. So the end result of this program is varying, but it never gets
+result was 117254, instead of the expected 200000. The second time I executed this program,
+I got the number 108592 as the result. So the end result of this program is varying, but it never gets
 to the expected 200000 that we want.
 
 
@@ -701,13 +701,13 @@ Couter value: 117254
 
 
 Why this is happening? The answer is: because this program contains a data race problem.
-This program would print the correct number 200000, if, and only if the first thread finishes
+This program would print the correct number 200000, if and only if, the first thread finishes
 its tasks before the second thread starts to execute. But that is very unlikely to happen.
-Because the process of creating the thread is too fast, and therefore, both threads starts to execute roughly
+Because the process of creating the thread is too fast, and therefore, both threads start to execute roughly
 at the same time. If you change this code to add some nanoseconds of sleep between the first and the second calls to `spawn()`,
 you will increase the chances of the program producing the "correct result".
 
-So the data race problem happens, because both threads are reading and writing to the same
+So the data race problem happens because both threads are reading and writing to the same
 memory location at roughly the same time. In this example, each thread is essentially performing
 three basic operations at each iteration of the for loop, which are:
 
@@ -717,16 +717,16 @@ three basic operations at each iteration of the for loop, which are:
 
 Ideally, a thread B should read the value of `count`, only after the other thread A has finished
 writing the incremented value back into the `count` object. Therefore, in the ideal scenario, which is demonstrated
-at @tbl-data-race-ideal, the threads should work in sync with each other. But the reality is that these
+in @tbl-data-race-ideal, the threads should work in sync with each other. But the reality is that these
 threads are out of sync, and because of that, they suffer from a data race problem, which is demonstrated
-at @tbl-data-race-not.
+in @tbl-data-race-not.
 
 Notice that, in the data race scenario (@tbl-data-race-not), the read performed by a thread B happens
 before the write operation of thread A, and that ultimately leads to wrong results at the end of the program.
-Because when the thread B reads the value from the `count` variable, the thread A is still processing
-the initial value from `count`, and it did not write the new and incremented value into `count` yet. So what
-happens is that thread B ends up reading the same initial value (the "old" value) from `count`, instead of
-reading the new and incremented version of this value that would be calculated by thread A.
+Because when thread B reads the value of the `count` variable, thread A is still processing
+the initial value from `count`, and has not yet written the new, incremented value back to `count`. As a result,
+thread B ends up reading the same initial (or "old") value from `count` instead of
+the updated, incremented value that thread A would have written.
 
 
 ::: {#tbl-data-race-ideal}
@@ -759,16 +759,16 @@ reading the new and incremented version of this value that would be calculated b
 
 
 If you think about these diagrams exposed in form of tables, you will notice that they relate back to our discussion of atomic operations
-at @sec-atomic-operation. Remember, atomic operations are operations that the CPU executes
+in @sec-atomic-operation. Remember, atomic operations are operations that the CPU executes
 from beginning to end, without interruptions from other threads or processes. So,
-the scenario exposed at @tbl-data-race-ideal do not suffer from a data race, because
+the scenario exposed in @tbl-data-race-ideal does not suffer from a data race, because
 the operations performed by thread A are not interrupted in the middle by the operations
 from thread B.
 
 If we also think about the discussion of critical section from @sec-critical-section, we can identify
 the section that representes the critical section of the program, which is the section that is vulnerable
 to data race conditions. In this example, the critical section of the program is the line where we increment
-the `counter` variable (`counter += 1`). So, ideally, we want to use a mutex, and lock right before this line, and then,
+the `counter` variable (`counter += 1`). So, ideally, we want to use a mutex, and lock right before this line, and then
 unlock right after this line.
 
 

From 0e1ac6e7d37a0050901e110be465745bce81183b Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Sat, 22 Feb 2025 04:58:35 -0400
Subject: [PATCH 094/151] fix typo in 16.6.4

---
 Chapters/14-threads.qmd | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Chapters/14-threads.qmd b/Chapters/14-threads.qmd
index 878a916a..ec25ae56 100644
--- a/Chapters/14-threads.qmd
+++ b/Chapters/14-threads.qmd
@@ -778,10 +778,10 @@ unlock right after this line.
 
 Now that we know the problem that mutexes seek to solve, we can learn how to use them in Zig.
 Mutexes in Zig are available through the `std.Thread.Mutex` struct from the Zig Standard Library.
-If we take the same code example from the previous example, and improve it with mutexes, to solve
-our data race problem, we get the code example exposed below.
+If we take the same code from the previous example, and improve it with mutexes, to solve
+our data race problem, we get the code example below.
 
-Notice that we had this time to alter the `increment()` function to receive a pointer to
+Notice that this time, we had to alter the `increment()` function to receive a pointer to
 the `Mutex` object as input. All that we need to do, to make this program safe against
 data race problems, is to call the `lock()` method at the beginning of
 the critical section, and then, call `unlock()` at the end of the critical section.

From 32feb515ea5bc026ad791343ba58c43ca1cf1ff4 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Sat, 22 Feb 2025 05:04:32 -0400
Subject: [PATCH 095/151] fix typos in 16.7 intro

---
 Chapters/14-threads.qmd | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/Chapters/14-threads.qmd b/Chapters/14-threads.qmd
index ec25ae56..f3c8311a 100644
--- a/Chapters/14-threads.qmd
+++ b/Chapters/14-threads.qmd
@@ -817,28 +817,28 @@ pub fn main() !void {
 
 ## Read/Write locks
 
-Mutexes are normally used when is always not safe to have two or more threads running the same
+Mutexes are normally used when it is not always safe for two or more threads running the same
 piece of code at the same time. In contrast, read/write locks are normally used in situations
-where you have a mixture of scenarios, i.e. there are some pieces of the codebase that are safe
+where you have a mixture of scenarios, i.e., there are some pieces of the codebase that are safe
 to run in parallel, and other pieces that are not safe.
 
-For example, suppose that you have multiple threads that uses the same shared file in the filesystem to store some configurations, or,
+For example, suppose that you have multiple threads that uses the same shared file in the filesystem to store some configurations, or
 statistics. If two or more threads try to read the data from this same file at the same time, nothing bad happens.
 So this part of the codebase is perfectly safe to be executed in parallel, with multiple threads reading the same file at the same time.
 
-However, if two or more threads try to write data into this same file at the same time, then, we cause some race conditions
+However, if two or more threads try to write data into this same file at the same time, then we cause some race condition
 problems. So this other part of the codebase is not safe to be executed in parallel.
 More specifically, a thread might end up writing data in the middle of the data written by the other thread.
-This process of two or more threads writing to the same location, might lead to data corruption.
-This specific situation is usually called of a *torn write*.
+This process of two or more threads writing to the same location might lead to data corruption.
+This specific situation is usually called a *torn write*.
 
-Thus, what we can extract from this example is that there is certain types of operations that causes
-a race condition, but there are also, other types of operations that do not cause a race condition problem.
-You could also say that, there are types of operations that are susceptible to race condition problems,
+Thus, what we can extract from this example is that there are certain types of operations that cause
+a race condition, but there are also other types of operations that do not cause a race condition problem.
+You could also say that there are types of operations that are susceptible to race condition problems,
 and there are other types of operations that are not.
 
-A read/write lock is a type of lock that acknowledges the existance of this specific scenario, and you can
-use this type of lock to control which parts of the codebase are safe to run in parallel, and which parts are not safe.
+A read/write lock is a type of lock that acknowledges the existence of this specific scenario, and you can
+use this type of lock to control which parts of the codebase are safe to run in parallel and which parts are not. 
 
 
 

From d8dca8b8bd124598c42a50b36aa4166bd2de550e Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Sat, 22 Feb 2025 05:16:08 -0400
Subject: [PATCH 096/151] fix typos

---
 Chapters/14-threads.qmd | 46 ++++++++++++++++++++---------------------
 1 file changed, 23 insertions(+), 23 deletions(-)

diff --git a/Chapters/14-threads.qmd b/Chapters/14-threads.qmd
index f3c8311a..4de23adc 100644
--- a/Chapters/14-threads.qmd
+++ b/Chapters/14-threads.qmd
@@ -258,14 +258,14 @@ pub fn main() !void {
 Notice the use of `try` when calling the `spawn()` method. This means
 that this method can return an error in some circumstances. One circumstance
 in particular is when you attempt to create a new thread, when you have already
-created too much (i.e. you have exceeded the quota of concurrent threads in your system).
+created too much (i.e., you have exceeded the quota of concurrent threads in your system).
 
 But, if the new thread is successfully created, the `spawn()` method returns a handler
 object (which is just an object of type `Thread`) to this new thread. You can use
 this handler object to effectively control all aspects of the thread.
 
 When the thread gets created, the function that you provided as input to `spawn()`
-gets invoked (i.e. gets called) to start the execution on this new thread.
+gets invoked (i.e., gets called) to start the execution on this new thread.
 In other words, every time you call `spawn()`, not only is a new thread created,
 but the "start work button" of this thread is also automatically pressed.
 So the work being performed in this thread starts as soon as the thread is created.
@@ -331,7 +331,7 @@ new threads, one after another. Then, we join the first thread, then,
 we wait for two whole seconds, then, at last, we join the second thread.
 
 The idea behind this example is that the last `join()` call is executed
-only after the first thread finishes its task (i.e. the first `join()` call),
+only after the first thread finishes its task (i.e., the first `join()` call),
 and the two-second delay. If you compile and run this
 example, you will notice that most messages are quickly printed to `stdout`,
 i.e. they appear almost instantly on your screen.
@@ -366,7 +366,7 @@ Thread ID: 2
 Joining thread 2
 ```
 
-This demonstrates that both threads finish their work (i.e. printing the IDs)
+This demonstrates that both threads finish their work (i.e., printing the IDs)
 very fast, before the two seconds of delay end. Because of that, the last `join()` call
 returns pretty much instantly. Because when this last `join()` call happens, the second
 thread has already finished its task.
@@ -376,7 +376,7 @@ the messages intertwine with each other. In other words, you might see
 the message "Joining thread 1" inserted in the middle of the message "Thread 1",
 or vice-versa. This happens because:
 
-- the threads are executing basically at the same time as the main process of the program (i.e. the `main()` function).
+- the threads are executing basically at the same time as the main process of the program (i.e., the `main()` function).
 - the threads share the same `stdout` from the main process of the program, which means that the messages that the threads produce are sent to exact same place as the messages produced by the main process.
 
 Both of these points were described previously in @sec-what-thread.
@@ -593,7 +593,7 @@ So mutexes are not normally used on areas of the codebase that access/modify obj
 
 Critical section is a concept commonly associated with mutexes and thread synchronization.
 In essence, a critical section is the section of the program that a thread access/modify a shared resource
-(i.e. an object, a file descriptor, something that all threads have access to). In other words,
+(i.e., an object, a file descriptor, something that all threads have access to). In other words,
 a critical section is the section of the program where race conditions might happen, and, therefore,
 where undefined behaviour can be introduced into the program.
 
@@ -631,7 +631,7 @@ In this module, you will find a public and generic function called `Value()`. Wi
 a value that contains some native atomic operations, most notably, a `load()` and a `fetchAdd()` operation.
 If you have experience with multithreading in C++, you probably have recognized this pattern. So yes, this generic
 "atomic object" in Zig is essentially identical to the template struct `std::atomic` from the C++ Standard Library.
-It is important to emphasize that only primitive data types (i.e. the types presented in @sec-primitive-data-types)
+It is important to emphasize that only primitive data types (i.e., the types presented in @sec-primitive-data-types)
 are supported by these atomic operations in Zig.
 
 
@@ -642,8 +642,8 @@ are supported by these atomic operations in Zig.
 
 To understand why mutexes are used, we need to understand better the problem that they seek
 to solve, which can be summarized into data race problems. A data race problem is a type of a race condition,
-which happens when one thread is accessing a particular memory location (i.e. a particular shared object) at the same
-time that another thread is trying to write/save new data into this same memory location (i.e. the same shared object).
+which happens when one thread is accessing a particular memory location (i.e., a particular shared object) at the same
+time that another thread is trying to write/save new data into this same memory location (i.e., the same shared object).
 
 We can simply define a race condition as any type of bug in your program that is based
 on a "who gets there first" problem. A data race problem is a type of a race condition, because it occurs when two or more parties
@@ -846,7 +846,7 @@ use this type of lock to control which parts of the codebase are safe to run in
 
 Therefore, a read/write lock is a little different from a mutex. Because a mutex is always an *exclusive lock*, meaning that, only
 one thread is allowed to execute at all times. With an exclusive lock, the other threads are always "excluded",
-i.e. they are always blocked from executing. But in a read/write lock, the other threads might be authorized
+i.e., they are always blocked from executing. But in a read/write lock, the other threads might be authorized
 to run at the same time, depending on the type of lock that they acquire.
 
 We have two types of locks in a read/write lock, which are: an exclusive lock and a shared lock. An exclusive lock works exactly the same
@@ -860,28 +860,28 @@ this C struct, you can create:
 The terminology might be a little different compared to Zig. But the meaning is still the same.
 Therefore, just remember this relationship, write locks are exclusive locks, while read locks are shared locks.
 
-When a thread tries to acquire a read lock (i.e. a shared lock), this thread get's the shared lock
-if, and only if another thread does not currently holds a write lock (i.e. an exclusive lock), and also,
-if there are no other threads that are already in the queue,
-waiting for their turn to acquire a write lock. In other words, the thread in the queue have attempted
+When a thread tries to acquire a read lock (i.e., a shared lock), this thread gets the shared lock
+if and only if another thread does not currently holds a write lock (i.e., an exclusive lock), and also
+if there are no other threads already in the queue,
+waiting for their turn to acquire a write lock. In other words, the thread in the queue has attempted
 to get a write lock earlier, but this thread was blocked
-because there was another thread running that already had a write lock. As consequence, this thread is on the queue to get a write lock,
+because there was another thread running that already had a write lock. As a consequence, this thread is in the queue to get a write lock,
 and it's currently waiting for the other thread with a write lock to finish its execution.
 
 When a thread tries to acquire a read lock, but it fails in acquiring this read lock, either because there is
-a thread with a write lock already running, or, because there is a thread in the queue to get a write lock,
-the execution of this thread is instantly blocked, i.e. paused. This thread will indefinitely attempt to get the
+a thread with a write lock already running, or because there is a thread in the queue to get a write lock,
+the execution of this thread is instantly blocked, i.e., paused. This thread will indefinitely attempt to get the
 read lock, and its execution will be unblocked (or unpaused) only after this thread successfully acquires the read lock.
 
 If you think deeply about this dynamic between read locks versus write locks, you might notice that a read lock is basically a safety mechanism.
 More specifically, it is a way for us to
-allow a particular thread to run together with the other threads, only when it's safe to. In other words, if there is currently
-a thread with a write lock running, then, it is very likely not safe for the thread that is trying to acquire the read lock to run now.
-As consequence, the read lock protects this thread from running into dangerous waters, and patiently waits for the
+allow a particular thread to run together with the other threads only when it's safe to. In other words, if there is currently
+a thread with a write lock running, then it is very likely not safe for the thread that is trying to acquire the read lock to run now.
+As a consequence, the read lock protects this thread from running into dangerous waters, and patiently waits for the
 "write lock" thread to finishes its tasks before it continues.
 
-On the other hand, if there are only "read lock" (i.e. "shared lock") threads currently running
-(i.e. not a single "write lock" thread currently exists), then,
+On the other hand, if there are only "read lock" (i.e., "shared lock") threads currently running
+(i.e., not a single "write lock" thread currently exists), then it
 is perfectly safe for this thread that is acquiring the read lock to run in parallel with the other
 threads. As a result, the read lock just
 allows for this thread to run together with the other threads.
@@ -1054,7 +1054,7 @@ nobody becomes responsible for clearing (or freeing) the resources associated wi
 You don't want to be in this situation, so remember to always use `join()` or `detach()`
 on the threads that you create. When you don't use one of these methods, we lose
 control over the thread, and its resources are never freed
-(i.e. you have leaked resources in the system).
+(i.e., you have leaked resources in the system).
 
 
 ### Cancelling or killing a particular thread

From d99c6eedd95142df9719f1bcd78d5cdd4540d813 Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Sat, 22 Feb 2025 10:34:49 -0400
Subject: [PATCH 097/151] fix typos in 16.7.2

---
 Chapters/14-threads.qmd | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Chapters/14-threads.qmd b/Chapters/14-threads.qmd
index 4de23adc..bb2988e4 100644
--- a/Chapters/14-threads.qmd
+++ b/Chapters/14-threads.qmd
@@ -896,9 +896,9 @@ of our multithreaded code is safe to have parallelism, and which sections are no
 ### Using read/write locks in Zig
 
 The Zig Standard Library supports read/write locks through the `std.Thread.RwLock` module.
-If you want to a particular thread to acquire a shared lock (i.e. a read lock), you should
-call the `lockShared()` method from the `RwLock` object. But, if you want for this thread
-to acquire an exclusive lock (i.e. a write lock) instead, then, you should call the
+If you want a particular thread to acquire a shared lock (i.e., a read lock), you should
+call the `lockShared()` method from the `RwLock` object. But, if you want this thread
+to acquire an exclusive lock (i.e., a write lock) instead, then you should call the
 `lock()` method from the `RwLock` object.
 
 As with mutexes, we also have to unlock the shared or exclusive locks that we acquire through a read/write lock object,
@@ -906,8 +906,8 @@ once we are at the end of our "critical section". If you have acquired an exclus
 this exclusive lock by calling the `unlock()` method from the read/write lock object. In contrast,
 if you have acquired a shared lock instead, then, call `unlockShared()` to unlock this shared lock.
 
-As a simple example, the snippet exposed below creates three separate threads responsible for reading the
-current value in a `counter` object, and it also creates another thread, responsible for writing
+As a simple example, the snippet below creates three separate threads responsible for reading the
+current value in a `counter` object, and it also creates another thread responsible for writing
 new data into the `counter` object (incrementing it, more specifically).
 
 ```{zig}

From 31ab59c17a68661c3df0a0129ee902e037849c6f Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Sat, 22 Feb 2025 10:47:27 -0400
Subject: [PATCH 098/151] fix typos in 16.8

---
 Chapters/14-threads.qmd | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Chapters/14-threads.qmd b/Chapters/14-threads.qmd
index bb2988e4..90bbfad0 100644
--- a/Chapters/14-threads.qmd
+++ b/Chapters/14-threads.qmd
@@ -950,7 +950,7 @@ pub fn main() !void {
 
 The `Thread` struct supports yielding through the `yield()` method.
 Yielding a thread means that the execution of the thread is temporarily stopped,
-and the thread comes back to the end of the queue of priority of the scheduler from
+and it moves to the end of the priority queue managed by the scheduler of
 your operating system.
 
 That is, when you yield a thread, you are essentially saying the following to your OS:
@@ -960,12 +960,12 @@ to focus on doing other things instead?".
 So this yield operation is also a way for you
 to stop a particular thread, so that you can work and prioritize other threads instead.
 
-Is important to say that, yielding a thread is a "not so common" thread operation these days.
-In other words, not many programmers use yielding in production, simply because is hard to use
+It is important to say that, yielding a thread is a "not so common" thread operation these days.
+In other words, not many programmers use yielding in production, simply because it is hard to use
 this operation and make it work properly, and also, there
 are better alternatives. Most programmers prefer to use `join()` instead.
-In fact, most of the times, when you see somebody using this "yield" operation in some code example,
-they are mostly using it to help them debug race conditions in their applications.
+In fact, most of the time, when you see someone using this "yield" operation in some code example,
+they are usually doing so to help debug race conditions in their applications.
 That is, this "yield" operation is mostly used as a debug tool nowadays.
 
 Anyway, if you want to yield a thread, just call the `yield()` method from it, like this:

From 4d30a4d2d54d693c5eaeec593ed74933867c44ea Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Sat, 22 Feb 2025 10:53:26 -0400
Subject: [PATCH 099/151] fix typos in 16.9

---
 Chapters/14-threads.qmd | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/Chapters/14-threads.qmd b/Chapters/14-threads.qmd
index 90bbfad0..66be59b5 100644
--- a/Chapters/14-threads.qmd
+++ b/Chapters/14-threads.qmd
@@ -1002,14 +1002,14 @@ After that, the function sleeps for 1 second, to
 simulate some type of work, and then, the function tries to acquire the `mut2` lock.
 
 On the other hand, when we look into the second thread, which executes the `work2()` function,
-we can see that this function acquires the `mut2` lock first. Because when this thread get's created and it tries
+we can see that this function acquires the `mut2` lock first. Because when this thread gets created and it tries
 to acquire this `mut2` lock, the first thread is still sleeping on that "sleep 1 second" line.
 After acquiring `mut2`, the `work2()` function also sleeps for 1 second, to
-simulate some type of work, and then, the function tries to acquire the `mut1` lock.
+simulate some type of work, and then the function tries to acquire the `mut1` lock.
 
 This creates a deadlock situation, because after the "sleep for 1 second" line in both threads,
-the thread 1 is trying to acquire the `mut2` lock, but this lock is currently being used by thread 2.
-However, at this moment, the thread 2 is also trying to acquire the `mut1` lock, which is currently
+thread 1 is trying to acquire the `mut2` lock, but this lock is currently being used by thread 2.
+However, at this moment, thread 2 is also trying to acquire the `mut1` lock, which is currently
 being used by thread 1. Therefore, both threads end up waiting for ever. Waiting for their peer to
 free the lock that they want to acquire.
 
@@ -1044,7 +1044,7 @@ pub fn main() !void {
 
 ### Not calling `join()` or `detach()` {#sec-not-call-join-detach}
 
-When you do not call either `join()` or `detach()` over a thread, then, this thread becomes a "zombie thread",
+When you do not call either `join()` or `detach()` over a thread, then this thread becomes a "zombie thread",
 because it does not have a clear "return point".
 You could also interpret this as: "nobody is properly responsible for managing the thread".
 When we don't establish if a thread is either *joinable* or *detached*,
@@ -1061,21 +1061,21 @@ control over the thread, and its resources are never freed
 
 When we think about the `pthreads` C library, there is a possible way to asynchronously kill or cancel
 a thread, which is by sending a `SIGTERM` signal to the thread through the `pthread_kill()` function.
-But canceling a thread like this is bad. Is dangerously bad. As consequence, the Zig implementation
+But canceling a thread like this is bad. It is dangerously bad. As a consequence, the Zig implementation
 of threads does not have a similar function, or, a similar way to asynchronously cancel or kill
 a thread.
 
 Therefore, if you want to cancel a thread in the middle of its execution in Zig,
-then, one good strategy that you can take is to use control flow in conjunction with `join()`.
-More specifically, you can design your thread around a while loop, that is constantly
+then one good strategy that you can take is to use control flow in conjunction with `join()`.
+More specifically, you can design your thread around a while loop that is constantly
 checking if the thread should continue running.
-If is time to cancel the thread, we could make the while loop break, and join the thread with the main thread
+If is time to cancel the thread, we could make the while loop break and join the thread with the main thread
 by calling `join()`.
 
 The code example below demonstrates to some extent this strategy.
 Here, we are using control flow to break the while loop, and exit the thread earlier than
 what we have initially planned to. This example also demonstrates how can we use
-atomic objects in Zig with the `Value()` generic function that we have mentioned at @sec-atomic-operation.
+atomic objects in Zig with the `Value()` generic function that we have mentioned in @sec-atomic-operation.
 
 
 ```{zig}

From ad64b0f04e9652bce0f5a92f127cd6c282f04c7d Mon Sep 17 00:00:00 2001
From: hamza wahed <hzd454@gmail.com>
Date: Sat, 22 Feb 2025 11:01:22 -0400
Subject: [PATCH 100/151] remove commas around 'if and only if'

---
 Chapters/14-threads.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/14-threads.qmd b/Chapters/14-threads.qmd
index 66be59b5..232fee95 100644
--- a/Chapters/14-threads.qmd
+++ b/Chapters/14-threads.qmd
@@ -701,7 +701,7 @@ Couter value: 117254
 
 
 Why this is happening? The answer is: because this program contains a data race problem.
-This program would print the correct number 200000, if and only if, the first thread finishes
+This program would print the correct number 200000 if and only if the first thread finishes
 its tasks before the second thread starts to execute. But that is very unlikely to happen.
 Because the process of creating the thread is too fast, and therefore, both threads start to execute roughly
 at the same time. If you change this code to add some nanoseconds of sleep between the first and the second calls to `spawn()`,

From 2d2528d238ef4ff3c91553ed8f58f59f9ce1f44f Mon Sep 17 00:00:00 2001
From: Glystik <glystik@proton.me>
Date: Tue, 25 Feb 2025 16:40:47 +0100
Subject: [PATCH 101/151] fixing typos and grammar

---
 Chapters/01-base64.qmd          | 56 +++++++++----------
 Chapters/01-memory.qmd          | 21 +++----
 Chapters/01-zig-weird.qmd       | 99 ++++++++++++++++-----------------
 Chapters/02-debugging.qmd       |  7 +--
 Chapters/03-structs.qmd         | 13 ++---
 Chapters/03-unittests.qmd       |  9 ++-
 Chapters/04-http-server.qmd     | 25 ++++-----
 Chapters/05-pointers.qmd        | 10 ++--
 Chapters/07-build-system.qmd    | 33 ++++++-----
 Chapters/09-data-structures.qmd | 38 ++++++-------
 Chapters/09-error-handling.qmd  | 25 ++++-----
 Chapters/10-stack-project.qmd   | 25 ++++-----
 Chapters/12-file-op.qmd         | 44 +++++++--------
 Chapters/13-image-filter.qmd    | 26 ++++-----
 Chapters/14-threads.qmd         | 61 ++++++++++----------
 Chapters/14-zig-c-interop.qmd   | 25 ++++-----
 Chapters/15-vectors.qmd         |  8 +--
 README.md                       |  4 +-
 zig_engine.R                    |  2 +-
 19 files changed, 246 insertions(+), 285 deletions(-)

diff --git a/Chapters/01-base64.qmd b/Chapters/01-base64.qmd
index 962f63bb..0d9a22f5 100644
--- a/Chapters/01-base64.qmd
+++ b/Chapters/01-base64.qmd
@@ -155,11 +155,11 @@ into 4 characters from the base64 scale. It keeps iterating through the input st
 per iteration. It keeps iterating, and producing these "new characters"
 until it hits the end of the input string.
 
-Now, you may think, what if you have a particular string that have a number of bytes
-that is not divisible by 3? What happens? For example, if you have a string
-that contains only two characters/bytes, such as "Hi". How the
-algorithm would behave in such situation? You find the answer at @fig-base64-algo1.
-You can see at @fig-base64-algo1 that the string "Hi", when converted to base64,
+Now you may think, what if you have a particular string that has a number of bytes
+that is not divisible by 3 - what happens? For example, if you have a string
+that contains only two characters/bytes, such as "Hi". How would the algorithm
+behave in such situation? You find the answer in @fig-base64-algo1.
+You can see in @fig-base64-algo1 that the string "Hi", when converted to base64,
 becomes the string "SGk=":
 
 ![The logic behind a base64 encoder](./../Figures/base64-encoder-flow.png){#fig-base64-algo1}
@@ -171,7 +171,7 @@ the algorithm does, is to check how to divide the input bytes into groups of 6 b
 If the algorithm notices that there is a group of 6 bits that, have some bits in it, but, at the same time, it is not full
 (in other words, $0 < nbits < 6$, being $nbits$ the number of bits), meaning that, it lacks
 some bits to fill the 6-bits requirement, the algorithm simply add extra zeros in this group
-to fill the space that it needs. That is why at @fig-base64-algo1, on the third group after the 6-bit transformation,
+to fill the space that it needs. That is why in @fig-base64-algo1, on the third group after the 6-bit transformation,
 2 extra zeros were added to fill the gap in this group.
 
 When we have a 6-bit group that is not completely full, like the third group, extra zeros
@@ -190,7 +190,7 @@ of meaningful characters in the sequence. Hence, everytime that the algorithm pr
 As another example, if you give the string "0" as input to a base64 encoder, this string is
 translated into the base64 sequence "MA==".
 The character "0" is, in binary, the sequence `00110000`[^zero-note]. So, with the 6-bit transformation
-exposed at @fig-base64-algo1, this single character would produce these two 6-bit groups: `001100`, `000000`.
+exposed in @fig-base64-algo1, this single character would produce these two 6-bit groups: `001100`, `000000`.
 The remaining two 6-bit groups become "padding groups". That is why the last
 two characters in the output sequence (MA==) are `==`.
 
@@ -211,7 +211,7 @@ by the base64 encoder.
 Each byte in the input string (the base64 encoded string) normally contributes to re-create
 two different bytes in the output (the original binary data).
 In other words, each byte that comes out of a base64 decoder is created by transforming merging two different
-bytes in the input together. You can visualize this relationship at @fig-base64-algo2:
+bytes in the input together. You can visualize this relationship in @fig-base64-algo2:
 
 ![The logic behind a base64 decoder](./../Figures/base64-decoder-flow.png){#fig-base64-algo2}
 
@@ -220,7 +220,7 @@ into the bytes of the output, are a bit tricky to visualize in a figure like thi
 summarized these transformations as "Some bit shifting and additions ..." in the figure. These transformations
 will be described in depth later.
 
-Besides that, if you look again at @fig-base64-algo2, you will notice that the character `=` was completely
+Besides that, if you look again in @fig-base64-algo2, you will notice that the character `=` was completely
 ignored by the algorithm. Remember, this is just a special character that marks the end of meaningful characters
 in the base64 sequence. So, every `=` character in a base64 encoded sequence should be ignored by a base64 decoder.
 
@@ -283,13 +283,13 @@ fn _calc_encode_length(input: []const u8) !usize {
 
 
 Also, you might have notice that, if the input length is less than 3 bytes, then, the output length of the encoder is
-always 4 bytes. This is the case for every input with less than 3 bytes, because, as I described at @sec-base64-encoder-algo,
+always 4 bytes. This is the case for every input with less than 3 bytes, because, as I described in @sec-base64-encoder-algo,
 the algorithm always produces enough "padding-groups" in the end result, to complete the 4 bytes window.
 
 Now, for the decoder, we just need to apply the inverse logic: for each 4 bytes in the input, 3 bytes
 will be produced in the output of the decoder. I mean, this is roughly true, because we also need to
-take the `=` character into account, which is always ignored by the decoder, as we described at @sec-base64-decoder-algo, and,
-at @fig-base64-algo2. But we can ignore this fact for now, just to keep things simple.
+take the `=` character into account, which is always ignored by the decoder, as we described in @sec-base64-decoder-algo, and,
+in @fig-base64-algo2. But we can ignore this fact for now, just to keep things simple.
 
 The function `_calc_decode_length()` exposed below summarizes this logic that we described. It is very similar
 to the function `_calc_encode_length()`. Only the division part is twisted, and also, in the special
@@ -329,7 +329,7 @@ this book[^zig-base64-algo].
 
 ### The 6-bit transformation {#sec-6bit-transf}
 
-The 6-bit transformation presented at @fig-base64-algo1 is the core part of the base64 encoder algorithm.
+The 6-bit transformation presented in @fig-base64-algo1 is the core part of the base64 encoder algorithm.
 By understanding how this transformation is made in code, the rest of the algorithm becomes much simpler
 to comprehend.
 
@@ -425,13 +425,13 @@ you have, and change them in some way. This ultimately also changes
 the value itself, because the binary representation of this value
 changes.
 
-We have already seen at @fig-encoder-bitshift the effect produced by a bit-shift.
+We have already seen in @fig-encoder-bitshift the effect produced by a bit-shift.
 But let's use the first byte in the output of the base64 encoder as another example of what
 bit-shifting means. This is the easiest byte of the 4 bytes in the output
 to build. Because we only need to move the bits from the first byte in the input two positions to the right,
 with the *bit shift to the right* (`>>`) operator.
 
-If we take the string "Hi" that we used at @fig-base64-algo1 as an example, the first byte in
+If we take the string "Hi" that we used in @fig-base64-algo1 as an example, the first byte in
 this string is "H", which is the sequence `01001000` in binary.
 If we move the bits of this byte, two places to the right, we get the sequence `00010010` as result.
 This binary sequence is the value `18` in decimal, and also, the value `0x12` in hexadecimal.
@@ -512,7 +512,7 @@ pub fn main() !void {
 
 ### Allocating space for the output
 
-As I described at @sec-stack, to store an object in the stack,
+As I described in @sec-stack, to store an object in the stack,
 this object needs to have a known and fixed length at compile-time. This is an important
 limitation for our base64 encoder/decoder case. Because the size of
 the output (from both the encoder and decoder) depends
@@ -525,7 +525,7 @@ this means that we cannot store the output for both the encoder
 and decoder in the stack.
 
 Consequently, we need to store this output on the heap,
-and, as I commented at @sec-heap, we can only
+and, as I commented in @sec-heap, we can only
 store objects in the heap by using allocator objects.
 So, one the arguments to both the `encode()` and `decode()`
 functions, needs to be an allocator object, because
@@ -544,8 +544,8 @@ the type `std.mem.Allocator` from the Zig Standard Library.
 
 Now that we have a basic understanding on how the bitwise operators work, and how
 exactly they help us to achieve the result we want to achieve. We can now encapsulate
-all the logic that we have described at @fig-base64-algo1 and @tbl-transf-6bit into a nice
-function that we can add to our `Base64` struct definition, that we started at @sec-base64-table.
+all the logic that we have described in @fig-base64-algo1 and @tbl-transf-6bit into a nice
+function that we can add to our `Base64` struct definition, that we started in @sec-base64-table.
 
 You can find the `encode()` function below. Notice that the first argument of this function,
 is the `Base64` struct itself. Therefore, this argument clearly signals
@@ -561,7 +561,7 @@ Furthermore, this `encode()` function has two other arguments:
 1. `input` is the input sequence of characters that you want to encode in base64;
 1. `allocator` is an allocator object to use in the necessary memory allocations.
 
-I described everything you need to know about allocator objects at @sec-allocators.
+I described everything you need to know about allocator objects in @sec-allocators.
 So, if you are not familiar with them, I highly recommend you to comeback to
 that section, and read it.
 By looking at the `encode()` function, you will see that we use this
@@ -644,7 +644,7 @@ pub fn encode(self: Base64,
 
 Now, we can focus on writing the base64 decoder logic. Remember from @fig-base64-algo2 that,
 a base64 decoder does the inverse process of an encoder. So, all we need to do, is to
-write a `decode()` function that performs the inverse process that I exposed at @sec-encoder-logic.
+write a `decode()` function that performs the inverse process that I exposed in @sec-encoder-logic.
 
 
 ### Mapping base64 characters to their indexes {#sec-map-base64-index}
@@ -667,7 +667,7 @@ If these characters match, then, we return the index of this character in the
 base64 scale as the result.
 
 Notice that, if the input character is `'='`, the function returns the index 64, which is
-"out of range" in the scale. But, as I described at @sec-base64-scale,
+"out of range" in the scale. But, as I described in @sec-base64-scale,
 the character `'='` does not belong to the base64 scale itself.
 It is a special and meaningless character in base64.
 
@@ -724,12 +724,12 @@ So, the steps to produce the 3 bytes in the output are:
 
 
 Before we continue, let's try to visualize how these transformations make the original bytes that we had
-before the encoding process. First, think back to the 6-bit transformation performed by the encoder exposed at @sec-encoder-logic.
+before the encoding process. First, think back to the 6-bit transformation performed by the encoder exposed in @sec-encoder-logic.
 The first byte in the output of the encoder is produced by moving the bits in the first byte of the input two positions to the right.
 
 If for example the first byte in the input of the encoder was the sequence `ABCDEFGH`, then, the first byte in the output of the encoder would be
 `00ABCDEF` (this sequence would be the first byte in the input of the decoder). Now, if the second byte in the input of the encoder was the sequence
-`IJKLMNOP`, then, the second byte in the encoder output would be `00GHIJKL` (as we demonstrated at @fig-encoder-bitshift).
+`IJKLMNOP`, then, the second byte in the encoder output would be `00GHIJKL` (as we demonstrated in @fig-encoder-bitshift).
 
 Hence, if the sequences `00ABCDEF` and `00GHIJKL` are the first and second bytes, respectively, in the input of the decoder, the
 @fig-decoder-bitshift demonstrates visually how these two bytes are transformed into the first byte of the output of the decoder.
@@ -834,8 +834,8 @@ var fba = std.heap.FixedBufferAllocator.init(
 );
 const allocator = fba.allocator();
 
-const text = "Testing some more stuff";
-const etext = "VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=";
+const text = "Testing some more stuff";
+const etext = "VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=";
 const base64 = Base64.init();
 const encoded_text = try base64.encode(
     allocator, text
@@ -852,8 +852,8 @@ try stdout.print(
 ```
 
 ```
-Encoded text: VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=
-Decoded text: Testing some more stuff
+Encoded text: VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=
+Decoded text: Testing some more stuff
 ```
 
 You can also see the full source code at once, by visiting the official repository of this book[^repo].
diff --git a/Chapters/01-memory.qmd b/Chapters/01-memory.qmd
index 3d7aa0a8..c08ce5d9 100644
--- a/Chapters/01-memory.qmd
+++ b/Chapters/01-memory.qmd
@@ -359,7 +359,7 @@ how much memory is allocated, and where this memory is freed.
 > Unlike stack memory, heap memory is allocated explicitly by programmers and it won’t be deallocated until it is explicitly freed [@jenny2022].
 
 To store an object in the heap, you, the programmer, needs to explicitly tells Zig to do so,
-by using an allocator to allocate some space in the heap. At @sec-allocators, I will present how you can use allocators to allocate memory
+by using an allocator to allocate some space in the heap. In @sec-allocators, I will present how you can use allocators to allocate memory
 in Zig.
 
 ::: {.callout-important}
@@ -393,7 +393,7 @@ object you declare is stored:
 
 Allocating memory on the stack is generally faster than allocating it on the heap.
 But this better performance comes with many restrictions. We have already discussed
-many of these restrictions of the stack at @sec-stack. But there is one more important
+many of these restrictions of the stack in @sec-stack. But there is one more important
 limitation that I want to talk about, which is the size of the stack itself.
 
 The stack is limited in size. This size varies from computer to computer, and it depends on
@@ -495,7 +495,7 @@ but you don't need to change the function calls to the methods that do the memor
 
 ### Why you need an allocator?
 
-As we described at @sec-stack, everytime you make a function call in Zig,
+As we described in @sec-stack, everytime you make a function call in Zig,
 a space in the stack is reserved for this function call. But the stack
 has a key limitation which is: every object stored in the stack has a
 known fixed length.
@@ -506,12 +506,12 @@ But in reality, there are two very common instances where this "fixed length lim
 1. sometimes, it is impossible to know upfront how many inputs you will receive, or how big this input will be.
 
 Also, there is another instance where you might want to use an allocator, which is when you want to write a function that returns a pointer
-to a local object. As I described at @sec-stack, you cannot do that if this local object is stored in the
+to a local object. As I described in @sec-stack, you cannot do that if this local object is stored in the
 stack. However, if this object is stored in the heap, then, you can return a pointer to this object at the
 end of the function. Because you (the programmer) control the lifetime of any heap memory that you allocate. You decide
 when this memory gets destroyed/freed.
 
-These are common situations for which the stack is not good. 
+These are common situations for which the stack is not good.
 That is why you need a different memory management strategy to
 store these objects inside your function. You need to use
 a memory type that can grow together with your objects, or that you
@@ -622,7 +622,7 @@ the stack, or, from the heap. It all depends on where the buffer object that you
 In the above example, the `buffer` object lives in the stack, and, therefore, the memory allocated
 is based in the stack. But what if it was based on the heap?
 
-As we described at @sec-stack-overflow, one of the main reasons why you would use the heap,
+As we described in @sec-stack-overflow, one of the main reasons why you would use the heap,
 instead of the stack, is to allocate huge amounts of space to store very big objects.
 Thus, let's suppose you wanted to use a very big buffer object as the basis for your
 allocator objects. You would have to allocate this very big buffer object on the heap.
@@ -699,7 +699,7 @@ you can create an array to store any type of value you want. Next, on the second
 define the size of the allocated array, by specifying how many elements
 this array will contain. In the case below, we are allocating an array of 50 elements.
 
-At @sec-zig-strings we described that strings in Zig are simply arrays of characters.
+In @sec-zig-strings we described that strings in Zig are simply arrays of characters.
 Each character is represented by a `u8` value. So, this means that the array that
 was allocated in the object `input` is capable of storing a string that is
 50-characters long.
@@ -732,12 +732,12 @@ pub fn main() !void {
 }
 ```
 
-Also, notice that in this example, we use the `defer` keyword (which I described at @sec-defer) to run a small
+Also, notice that in this example, we use the `defer` keyword (which I described in @sec-defer) to run a small
 piece of code at the end of the current scope, which is the expression `allocator.free(input)`.
 When you execute this expression, the allocator will free the memory that it allocated
 for the `input` object.
 
-We have talked about this at @sec-heap. You **should always** explicitly free any memory that you allocate
+We have talked about this in @sec-heap. You **should always** explicitly free any memory that you allocate
 using an allocator! You do that by using the `free()` method of the same allocator object you
 used to allocate this memory. The `defer` keyword is used in this example only to help us execute
 this free operation at the end of the current scope.
@@ -787,6 +787,3 @@ pub fn main() !void {
     user.* = User.init(0, "Pedro");
 }
 ```
-
-
-
diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index 1a1afa74..4b395303 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -60,7 +60,7 @@ your C code. With macros, you are no longer 100% sure about which pieces
 of the code are being sent to the compiler, i.e.
 they obscure the actual source code that you wrote.
 
-You don't have macros in Zig. In Zig, the code you write, is the actual code that get's compiled by the compiler.
+You don't have macros in Zig. In Zig, the code you write, is the actual code that gets compiled by the compiler.
 You also don't have a hidden control flow happening behind the scenes. And, you also
 don't have functions or operators from the standard library that make
 hidden memory allocations behind your back.
@@ -125,7 +125,7 @@ tree .
 The `init` command also creates two additional files in our working directory:
 `build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.
 This script is executed when you call the `build` command from the `zig` compiler.
-In other words, this file contain Zig code that executes the necessary steps to build the entire project.
+In other words, this file contains Zig code that executes the necessary steps to build the entire project.
 
 
 Low-level languages normally use a compiler to build your
@@ -150,9 +150,8 @@ these build systems separately.
 
 In Zig, we don't need to use a separate set of tools to build our projects,
 because a build system is embedded inside the language itself.
-Therefore, Zig contains a native build system in it, and
-we can use this build system to write small scripts in Zig,
-which describes the necessary steps to build/compile our Zig project[^zig-build-system].
+We can use this build system to write small scripts in Zig,
+which describe the necessary steps to build/compile our Zig project[^zig-build-system].
 So, everything you need to build a complex Zig project is the
 `zig` compiler, and nothing more.
 
@@ -199,9 +198,9 @@ In this example, we are importing the `std` module,
 which gives you access to the Zig Standard Library.
 
 In this `root.zig` file, we can also see how assignments (i.e. creating new objects)
-are made in Zig. You can create a new object in Zig by using the following syntax
+are made in Zig. You can create a new object in Zig by using the syntax
 `(const|var) name = value;`. In the example below, we are creating two constant
-objects (`std` and `testing`). At @sec-assignments we talk more about objects in general.
+objects (`std` and `testing`). In @sec-assignments we talk more about objects in general.
 
 
 ```{zig}
@@ -222,7 +221,7 @@ The function returns an integer of the type `i32` as result.
 
 Zig is a strongly-typed language. There are some specific situations where you can (if you want to) omit
 the type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more
-about that at @sec-type-inference). But there are other situations where you do need to be explicit.
+about that in @sec-type-inference). But there are other situations where you do need to be explicit.
 For example, you do have to explicitly specify the type of each function argument, and also,
 the return type of every function that you create in Zig.
 
@@ -258,7 +257,7 @@ First, look at the return type of the `main()` function in this file.
 We can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).
 This exclamation mark tells us that this `main()` function might return an error.
 
-Is worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),
+It's worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),
 or an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig
 to return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,
 which returns an integer value that usually serves as a "status code" for the process.
@@ -391,14 +390,14 @@ includes some global variables whose initialization rely on runtime resources, t
 you might have some troubles while trying to compile this Zig code on Windows.
 
 An example of that is accessing the `stdout` (i.e. the *standard output* of your system), which is usually
-done in Zig by using the expression `std.io.getStdOut()`. Thus, if you use this expression to instantiate
+done in Zig by using the expression `std.io.getStdOut()`. If you use this expression to instantiate
 a global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,
-with a "unable to evaluate comptime expression" error message.
+with an "unable to evaluate comptime expression" error message.
 
 This failure in the compilation process happens because all global variables in Zig are initialized
-at *compile-time*. However, operations like accessing the `stdout` (or opening a file) on Windows
-depends on resources that are available only at *runtime* (you will learn more about compile-time
-versus runtime at @sec-compile-time).
+at *compile-time*. However, on Windows, operations like accessing the `stdout` (or opening a file) depend on
+resources that are available only at *runtime* (you will learn more about compile-time versus runtime
+in @sec-compile-time).
 
 For example, if you try to compile this code example on Windows, you will likely get the error message
 exposed below:
@@ -430,7 +429,7 @@ that by simply moving the expression to a function body.
 
 This solves the problem because all expressions that are inside a function body in Zig
 are evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.
-You will learn more about this `comptime` keyword at @sec-comptime.
+You will learn more about this `comptime` keyword in @sec-comptime.
 
 
 ```{zig}
@@ -448,8 +447,8 @@ pub fn main() !void {
 Hello
 ```
 
-You can read more details about this Windows-specific limitation at a couple of
-GitHub issues opened at the official Zig repository. More specifically, the issues 
+You can read more details about this Windows-specific limitation in a couple of
+GitHub issues opened  the official Zig repository. More specifically, the issues
 17186 [^cissue1] and 19864 [^cissue2].
 
 [^cissue1]: <https://github.com/ziglang/zig/issues/17186>
@@ -511,7 +510,7 @@ Hello, world!
 
 ## How to learn Zig?
 
-What are the best strategies to learn Zig? 
+What are the best strategies to learn Zig?
 First of all, of course this book will help you a lot on your journey through Zig.
 But you will also need some extra resources if you want to be really good at Zig.
 
@@ -675,7 +674,7 @@ On the other hand, you can, in fact, declare a new object in your source code,
 and not give it an explicit value. But we need to use a special keyword for that,
 which is the `undefined` keyword.
 
-Is important to emphasize that, you should avoid using `undefined` as much as possible.
+It's important to emphasize that, you should avoid using `undefined` as much as possible.
 Because when you use this keyword, you leave your object uninitialized, and, as a consequence,
 if for some reason, your code use this object while it is uninitialized, then, you will definitely
 have undefined behaviour and major bugs in your program.
@@ -702,7 +701,7 @@ But in case you really need to declare an object without initializing it... the
 Every object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object
 to a function call, as a function argument, or, you can use it in another expression
 to calculate the value of another object, or, you can call a method that belongs to this
-particular object. 
+particular object.
 
 It doesn't matter in which way you use it. As long as you use it.
 If you try to break this rule, i.e. if your try to declare a object, but not use it,
@@ -771,7 +770,7 @@ t.zig:7:5: error: pointless discard
 
 This same rule applies to variable objects. Every variable object must also be used in
 some way. And if you assign a variable object to the underscore,
-this object also get's discarded, and you can no longer use this object.
+this object also gets discarded, and you can no longer use this object.
 
 
 
@@ -857,7 +856,7 @@ const ls = [_]f64{432.1, 87.2, 900.05};
 _ = ns; _ = ls;
 ```
 
-Is worth noting that these are static arrays, meaning that
+It's worth noting that these are static arrays, meaning that
 they cannot grow in size.
 Once you declare your array, you cannot change the size of it.
 This is very common in low level languages.
@@ -893,7 +892,7 @@ a range of indexes, and it have the syntax `start..end`.
 In the example below, at the second line of code,
 the `sl` object stores a slice (or a portion) of the
 `ns` array. More precisely, the elements at index 1 and 2
-in the `ns` array. 
+in the `ns` array.
 
 ```{zig}
 #| auto_main: true
@@ -978,7 +977,7 @@ these are array operators.
 One important detail about these two operators is that they work
 only when both operands have a size (or "length") that is compile-time known.
 We are going to talk more about
-the differences between "compile-time known" and "runtime known" at @sec-compile-time.
+the differences between "compile-time known" and "runtime known" in @sec-compile-time.
 But for now, keep this information in mind, that you cannot use these operators in every situation.
 
 In summary, the `++` operator creates a new array that is the concatenation,
@@ -995,7 +994,7 @@ try stdout.print("{any}\n", .{c});
 ```
 
 This `++` operator is particularly useful to concatenate strings together.
-Strings in Zig are described in depth at @sec-zig-strings. In summary, a string object in Zig
+Strings in Zig are described in depth in @sec-zig-strings. In summary, a string object in Zig
 is essentially an arrays of bytes. So, you can use this array concatenation operator
 to effectively concatenate strings together.
 
@@ -1015,24 +1014,24 @@ try stdout.print("{any}\n", .{c});
 ### Runtime versus compile-time known length in slices
 
 We are going to talk a lot about the differences between compile-time known
-and runtime known across this book, especially at @sec-compile-time.
+and runtime known across this book, especially in @sec-compile-time.
 But the basic idea is that a thing is compile-time known, when we know
 everything (the value, the attributes and the characteristics) about this thing at compile-time.
 In contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.
 Therefore, we don't know the value of this thing at compile-time, only at runtime.
 
-We have learned at @sec-select-array-elem that slices are created by using a *range selector*,
+We have learned in @sec-select-array-elem that slices are created by using a *range selector*,
 which represents a range of indexes. When this "range of indexes" (i.e. the start and the end of this range)
-is known at compile-time, the slice object that get's created is actually, under the hood, just
+is known at compile-time, the slice object that gets created is actually, under the hood, just
 a single-item pointer to an array.
 
 You don't need to precisely understand what that means now. We are going to talk a lot about pointers
-at @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,
-the slice that get's created is just a pointer to an array, accompanied by a length value that
+in @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,
+the slice that gets created is just a pointer to an array, accompanied by a length value that
 tells the size of the slice.
 
 If you have a slice object like this, i.e. a slice that has a compile-time known range,
-you can use common pointer operations over this slice object. For example, you can 
+you can use common pointer operations over this slice object. For example, you can
 dereference the pointer of this slice, by using the `.*` method, like you would
 do on a normal pointer object.
 
@@ -1050,7 +1049,7 @@ const slice = arr1[1..4];
 
 
 On the other hand, if the range of indexes is not known at compile time, then, the slice object
-that get's created is not a pointer anymore, and, thus, it does not support pointer operations.
+that gets created is not a pointer anymore, and, thus, it does not support pointer operations.
 For example, maybe the start index is known at compile time, but the end index is not. In such
 case, the range of the slice becomes runtime known only.
 
@@ -1154,14 +1153,14 @@ Therefore, a string literal value have a data type in the format `*const [n:0]u8
 indicates the size of the string.
 
 On the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,
-or, in other words, a slice of `u8` values (slices were presented at @sec-arrays). Thus,
+or, in other words, a slice of `u8` values (slices were presented in @sec-arrays). Thus,
 a string object have a data type of `[]u8` or `[]const u8`, depending if the string object is
 marked as constant with `const`, or as variable with `var`.
 
 Because a string object is essentially a slice, it means that a string object always contains two things:
 a pointer to an array of bytes (i.e. `u8` values) that represents the string value; and also, a length value,
 which specifies the size of the slice, or, how many elements there is in the slice.
-Is worth to emphasize that the array of bytes in a string object is not null-terminated, like in a
+It's worth to emphasize that the array of bytes in a string object is not null-terminated, like in a
 string literal value.
 
 ```{zig}
@@ -1337,7 +1336,7 @@ Type 4: []const u8
 
 ### Byte vs unicode points
 
-Is important to point out that each byte in the array is not necessarily a single character.
+It's important to point out that each byte in the array is not necessarily a single character.
 This fact arises from the difference between a single byte and a single unicode point.
 
 The encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in
@@ -1595,11 +1594,11 @@ program logic safety. These rules are:
 We already learned a lot about Zig's syntax, and also, some pretty technical
 details about it. Just as a quick recap:
 
-- We talked about how functions are written in Zig at @sec-root-file and @sec-main-file.
-- How to create new objects/identifiers at @sec-root-file and especially at @sec-assignments.
-- How strings work in Zig at @sec-zig-strings.
-- How to use arrays and slices at @sec-arrays.
-- How to import functionality from other Zig modules at @sec-root-file.
+- We talked about how functions are written in Zig in @sec-root-file and @sec-main-file.
+- How to create new objects/identifiers in @sec-root-file and especially in @sec-assignments.
+- How strings work in Zig in @sec-zig-strings.
+- How to use arrays and slices in @sec-arrays.
+- How to import functionality from other Zig modules in @sec-root-file.
 
 
 But, for now, this amount of knowledge is enough for us to continue with this book.
@@ -1607,15 +1606,11 @@ Later, over the next chapters we will still talk more about other parts of
 Zig's syntax that are also equally important. Such as:
 
 
-- How Object-Oriented programming can be done in Zig through *struct declarations* at @sec-structs-and-oop.
-- Basic control flow syntax at @sec-zig-control-flow.
-- Enums at @sec-enum;
-- Pointers and Optionals at @sec-pointer;
-- Error handling with `try` and `catch` at @sec-error-handling;
-- Unit tests at @sec-unittests;
-- Vectors at @sec-vectors-simd;
-- Build System at @sec-build-system;
-
-
-
-
+- How Object-Oriented programming can be done in Zig through *struct declarations* in @sec-structs-and-oop.
+- Basic control flow syntax in @sec-zig-control-flow.
+- Enums in @sec-enum;
+- Pointers and Optionals in @sec-pointer;
+- Error handling with `try` and `catch` in @sec-error-handling;
+- Unit tests in @sec-unittests;
+- Vectors in @sec-vectors-simd;
+- Build System in @sec-build-system;
diff --git a/Chapters/02-debugging.qmd b/Chapters/02-debugging.qmd
index 46bfd83e..851c8d44 100644
--- a/Chapters/02-debugging.qmd
+++ b/Chapters/02-debugging.qmd
@@ -30,7 +30,7 @@ The key advantage that debugging offers you is *visibility*.
 With *print statements* you can easily see what results and objects
 are being produced by your application.
 
-That is the essence of *print debugging*. Is to use
+This is the essence of *print debugging* - using
 print expressions to see the values that are being generated by your program,
 and, as a result, get a much better understanding of how your program
 is behaving.
@@ -157,7 +157,7 @@ By compiling your source code in `Debug` mode, you ensure that the debugger
 will find the necessary information in your program to debug it.
 By default, the compiler uses the `Debug` mode when compiling your code.
 Having this in mind, when you compile your program with the `build-exe`
-command (which was described at @sec-compile-code), if you don't specify
+command (which was described in @sec-compile-code), if you don't specify
 an explicit mode through the `-O` command-line [^oargument]
 argument, then, the compiler will compile your code in `Debug` mode.
 
@@ -257,7 +257,7 @@ If we take a look at the value stored in the `n` object (`p n`),
 notice that it stores the hexadecimal value `0x06`, which
 is the number 6 in decimal. We can also see that this value has a type of `unsigned char`,
 which is an unsigned 8-bit integer.
-We have talked already about this at @sec-zig-strings, that `u8` integers in Zig are equivalent
+We have talked already about this in @sec-zig-strings, that `u8` integers in Zig are equivalent
 to the C data type `unsigned char`.
 
 
@@ -346,4 +346,3 @@ pub fn main() !void {
 
 This function is similar to the `type()` built-in function from Python,
 or, the `typeof` operator in Javascript.
-
diff --git a/Chapters/03-structs.qmd b/Chapters/03-structs.qmd
index 008c5e72..1f603615 100644
--- a/Chapters/03-structs.qmd
+++ b/Chapters/03-structs.qmd
@@ -352,7 +352,7 @@ functions, normal blocks, etc. This also affects the interpretation of `defer`.
 For example, if you use `defer` inside a for loop, then, the given expression
 will be executed everytime this specific for loop exits its own scope.
 
-Before we continue, is worth emphasizing that the `defer` keyword is an "unconditional defer".
+Before we continue, it's worth emphasizing that the `defer` keyword is an "unconditional defer".
 Which means that the given expression will be executed no matter how the code exits
 the current scope. For example, your code might exit the current scope because of an error value
 being generated, or, because of a return statement, or, a break statement, etc.
@@ -378,7 +378,7 @@ But we are going to discuss `errdefer` later as a error handling tool in @sec-er
 
 The code example below demonstrates three things:
 
-- that `defer` is an "unconditional defer", because the given expression get's executed regardless of how the function `foo()` exits its own scope.
+- that `defer` is an "unconditional defer", because the given expression gets executed regardless of how the function `foo()` exits its own scope.
 - that `errdefer` is executed because the function `foo()` returned an error value.
 - that `defer` and `errdefer` expressions are executed in a LIFO (*last in, first out*) order.
 
@@ -410,7 +410,7 @@ You could also interpret this as: "defer expressions" are executed from bottom t
 from last to first.
 
 Therefore, if I change the order of the `defer` and `errdefer` expressions, you will notice that
-the value of `i` that get's printed to the console changes to 1. This doesn't mean that the
+the value of `i` that gets printed to the console changes to 1. This doesn't mean that the
 `defer` expression was not executed in this case. This actually means that the `defer` expression
 was executed only after the `errdefer` expression. The code example below demonstrates this:
 
@@ -1287,9 +1287,9 @@ are basically accessing the data members of the struct stored in the `std`
 object. That is why we use the same syntax that we use in normal structs, with the dot operator (`.`)
 to access the data members and methods of the struct.
 
-When this "import statement" get's executed, the result of this expression is a struct
+When this "import statement" gets executed, the result of this expression is a struct
 object that contains the Zig Standard Library modules, global variables, functions, etc.
-And this struct object get's saved (or stored) inside the constant object named `std`.
+And this struct object gets saved (or stored) inside the constant object named `std`.
 
 
 Take the [`thread_pool.zig` module from the project `zap`](https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig)[^thread]
@@ -1316,6 +1316,3 @@ const pool = ThreadPool.init(
     .{ .max_threads = num_threads }
 );
 ```
-
-
-
diff --git a/Chapters/03-unittests.qmd b/Chapters/03-unittests.qmd
index 56cfb051..485f9da4 100644
--- a/Chapters/03-unittests.qmd
+++ b/Chapters/03-unittests.qmd
@@ -55,7 +55,7 @@ You can have multiple `test` blocks written on the same Zig module.
 Also, you can mix `test` blocks with your source code, with no problems
 or consequences. If you mix `test` blocks with your normal source code,
 when you execute the `build`, `build-exe`, `build-obj` or `build-lib` commands from the
-`zig` compiler that we exposed at @sec-compile-code, these `test` blocks are automatically
+`zig` compiler that we exposed in @sec-compile-code, these `test` blocks are automatically
 ignored by the compiler.
 
 In other words, the `zig` compiler builds and execute your unit tests only
@@ -117,7 +117,7 @@ This is the `std.testing.allocator` object.
 This allocator object offers some basic memory safety detection
 features, which are capable of detecting memory leaks.
 
-As we described at @sec-heap, to allocate memory on the heap, you need
+As we described in @sec-heap, to allocate memory on the heap, you need
 to use an allocator object, and your functions that use these objects to allocate memory
 on the heap, should receive an allocator object as one of its inputs.
 Every memory on the heap that you allocate using these allocator objects,
@@ -159,7 +159,7 @@ test "memory leak" {
 
 ```
 Test [1/1] leak_memory.test.memory leak...
-    [gpa] (err): memory address 0x7c1fddf39000 leaked: 
+    [gpa] (err): memory address 0x7c1fddf39000 leaked:
 ./ZigExamples/debugging/leak_memory.zig:4:39: 0x10395f2
     const buffer = try allocator.alloc(u32, 10);
                                       ^
@@ -322,7 +322,7 @@ test "strings are equal?" {
 ```
 
 ```
-1/1 t.test.strings are equal?... 
+1/1 t.test.strings are equal?...
 ====== expected this output: =========
 hello, world!␃
 ======== instead found this: =========
@@ -336,4 +336,3 @@ found:
 Hello, world!
 ^ ('\x48')
 ```
-
diff --git a/Chapters/04-http-server.qmd b/Chapters/04-http-server.qmd
index 4ba8c181..2cb1fe62 100644
--- a/Chapters/04-http-server.qmd
+++ b/Chapters/04-http-server.qmd
@@ -40,7 +40,7 @@ But the messages that are transmitted inside this connection are in a
 specific format. They are HTTP messages
 (i.e. messages that use the HTTP Protocol specification).
 The HTTP Protocol is the backbone of the modern web.
-The world wide web as we know it today, would not exist without the 
+The world wide web as we know it today, would not exist without the
 HTTP Protocol.
 
 So, Web servers (which is just a fancy name to
@@ -166,7 +166,7 @@ a separate Zig module. I will name it `config.zig`.
 
 In Zig, we can create a web socket using
 the `std.posix.socket()` function, from the Zig Standard Library.
-As I mentioned earlier at @sec-http-how-impl, every socket object that we create
+As I mentioned earlier in @sec-http-how-impl, every socket object that we create
 represents a communication channel, and we need to bind this channel to a specific address.
 An "address" is defined as an IP address, or, more specifically, an IPv4 address^[It can be also an IPv6 address. But normally, we use a IPv4 address for that.].
 Every IPv4 address is composed by two components. The first component is the host,
@@ -175,7 +175,7 @@ While the second component is a port number, which identifies the specific
 door, or, the specific port to use in the host machine.
 
 The sequence of 4 numbers (i.e. the host) identifies the machine (i.e. the computer itself) where
-this socket will live in. Every computer normally have multiple "doors" available inside of him, because 
+this socket will live in. Every computer normally have multiple "doors" available inside of him, because
 this allows the computer to receive and work with multiple connections at the same time.
 He simply use a single door for each connection. So the port number, is
 essentially a number that identifies the specific door in the computer that will be responsible
@@ -204,7 +204,7 @@ For TCP connections, which is our case here,
 a port number is a 16-bit unsigned integer (type `u16` in Zig),
 thus ranging from 0 to 65535 [@wikipedia_port].
 So, we can choose
-a number from 0 to 65535 for our port number. In the 
+a number from 0 to 65535 for our port number. In the
 example of this book, I will use the port number 3490
 (just a random number).
 
@@ -256,7 +256,7 @@ pub const Socket = struct {
 ### Listening and receiving connections
 
 Remember that we stored the `Socket` struct
-declaration that we built at @sec-create-socket inside a Zig module named `config.zig`.
+declaration that we built in @sec-create-socket inside a Zig module named `config.zig`.
 This is why I imported this module into our main module (`main.zig`) in the example below, as the `SocketConf` object,
 to access the `Socket` struct.
 
@@ -435,7 +435,7 @@ will finally be executed to create the
 connection object that we need, and the remaining of the program
 will run.
 
-You can see that at @fig-print-zigrun1. The message `Server Addr: 127.0.0.1:3490`
+You can see that in @fig-print-zigrun1. The message `Server Addr: 127.0.0.1:3490`
 is printed to the console, and the program is now waiting for an incoming connection.
 
 ![A screenshot of running the program](./../Figures/print-zigrun1.png){#fig-print-zigrun1}
@@ -473,7 +473,7 @@ when you have executed the program, you will see that the
 program finished its execution, and, a new message is
 printed in the console, which is the actual HTTP Request
 message that was sent by the web browser to the server.
-You can see this message at @fig-print-zigrun2.
+You can see this message in @fig-print-zigrun2.
 
 ![A screenshot of the HTTP Request sent by the web browser](./../Figures/print-zigrun2.png){#fig-print-zigrun2}
 
@@ -680,7 +680,7 @@ But in order to build these functions, I will use a functionality from the Zig S
 In other words, we can use this map structure to map a string to the respective enum value.
 To some extent, this specific structure from the standard library works almost like a "hashtable" structure,
 and it is optimized for small sets of words, or, small sets of keys, which is our case here.
-We are going to talk more about hashtables in Zig at @sec-maps-hashtables.
+We are going to talk more about hashtables in Zig in @sec-maps-hashtables.
 
 To use this "static string map" structure, you have to import it from the `std.static_string_map` module
 of the Zig Standard Library. Just to make things shorter and easier to type, I am going to import this
@@ -801,7 +801,7 @@ This is the line where we have the three information that we want to parse
 
 Therefore, we are using this `indexOfScalar()` function
 to limit our parsing process to the first line in the message.
-Is also worth mentioning that, the `indexOfScalar()` function returns an optional value.
+It's also worth mentioning that, the `indexOfScalar()` function returns an optional value.
 That is why I use the `orelse` keyword to provide an alternative value, in case
 the value returned by the function is a null value.
 
@@ -843,11 +843,11 @@ pub fn parse_request(text: []u8) Request {
 ```
 
 
-As I described at @sec-zig-strings, strings in Zig are simply arrays of bytes in the language.
+As I described in @sec-zig-strings, strings in Zig are simply arrays of bytes in the language.
 So, you will find lots of excellent utility functions to work directly with strings
 inside this `mem` module from the Zig Standard Library.
 We have described some of these useful utility functions already
-at @sec-strings-useful-funs.
+in @sec-strings-useful-funs.
 
 
 
@@ -987,7 +987,7 @@ or not to decide which function to call.
 
 Also, notice that I'm using the function `std.mem.eql()` from the Zig Standard Library
 to check if the string from `uri` is equal or not the string `"/"`. We have
-described this function already at @sec-strings-useful-funs, so, comeback to
+described this function already in @sec-strings-useful-funs, so, comeback to
 that section if you are not familiar yet with this function.
 
 
@@ -1036,4 +1036,3 @@ successfully to the web browser, as demonstrated by @fig-print-zigrun3.
 
 
 ![The Hello World message sent in the HTTP Response](./../Figures/print-zigrun3.png){#fig-print-zigrun3}
-
diff --git a/Chapters/05-pointers.qmd b/Chapters/05-pointers.qmd
index 3e2d8dc1..bf8eba08 100644
--- a/Chapters/05-pointers.qmd
+++ b/Chapters/05-pointers.qmd
@@ -66,7 +66,7 @@ std.debug.print("{d}\n", .{doubled});
 
 This syntax to dereference the pointer is nice. Because we can easily chain it with
 methods of the value pointed by the pointer. We can use the `User` struct that we have
-created at @sec-structs-and-oop as an example. If you comeback to that section,
+created in @sec-structs-and-oop as an example. If you comeback to that section,
 you will see that this struct have a method named `print_name()`.
 
 So, for example, if we have an user object, and a pointer that points to this user object,
@@ -126,7 +126,7 @@ one of main reasons why pointers are used in programming languages.
 You can have a pointer that points to a constant object, or, a pointer that points to a variable object.
 But regardless of who this pointer is, a pointer **must always respect the characteristics of the object that it points to**.
 As a consequence, if the pointer points to a constant object, then, you cannot use this pointer
-to change the value that it points to. Because it points to a value that is constant. As we discussed at @sec-assignments, you cannot
+to change the value that it points to. Because it points to a value that is constant. As we discussed in @sec-assignments, you cannot
 change a value that is constant.
 
 For example, if I have a `number` object, which is constant, I cannot execute
@@ -270,7 +270,7 @@ try stdout.print("{d}\n", .{ptr[0]});
 
 Although you can create a pointer to an array like that, and
 start to walk through this array by using pointer arithmetic,
-in Zig, we prefer to use slices, which were presented at @sec-arrays.
+in Zig, we prefer to use slices, which were presented in @sec-arrays.
 
 Behind the hood, slices already are pointers,
 and they also come with the `len` property, which indicates
@@ -280,7 +280,7 @@ can use it to check for potential buffer overflows, and other problems like that
 Also, you don't need to use pointer arithmetic to walk through the elements
 of a slice. You can simply use the `slice[index]` syntax to directly access
 any element you want in the slice.
-As I mentioned at @sec-arrays, you can get a slice from an array by using
+As I mentioned in @sec-arrays, you can get a slice from an array by using
 a range selector inside brackets. In the example below, I'm creating
 a slice (`sl`) that covers the entire `ar` array. I can access any
 element of `ar` from this slice, and, the slice itself already is a pointer
@@ -505,5 +505,3 @@ p7.zig:12:34: 0x103419d in main (p7):
 
 
 [^un-docs]: <https://ziglang.org/documentation/master/#unreachable>.
-
-
diff --git a/Chapters/07-build-system.qmd b/Chapters/07-build-system.qmd
index 6bced377..d1dce207 100644
--- a/Chapters/07-build-system.qmd
+++ b/Chapters/07-build-system.qmd
@@ -47,7 +47,7 @@ for this particular task.
 ## How source code is built?
 
 We already have talked about the challenges of building source code in low-level languages
-at @sec-project-files. As we described at that section, programmers invented Build Systems
+in @sec-project-files. As we described at that section, programmers invented Build Systems
 to surpass these challenges on the process of building source code in low-level languages.
 
 Low-level languages uses a compiler to compile (or to build) your source code into binary instructions.
@@ -73,7 +73,7 @@ If that is not your case, you can forget about it.
 Your build process is usually organized in a build script. In Zig, we normally
 write this build script into a Zig module in the root directory of our project,
 named as `build.zig`. You write this build script, then, when you run it, your project
-get's built into binary files that you can use and distribute to your users.
+gets built into binary files that you can use and distribute to your users.
 
 This build script is normally organized around *target objects*. A target is simply
 something to be built, or, in other words, it's something that you want the `zig` compiler
@@ -89,19 +89,19 @@ There are four types of target objects that you can build in Zig, which are:
 - A static library (e.g. a `.a` file in Linux or a `.lib` file on Windows).
 - An executable file that executes only unit tests (or, a "unit tests executable").
 
-We are going to talk more about these target objects at @sec-targets.
+We are going to talk more about these target objects in @sec-targets.
 
 
 
 ## The `build()` function {#sec-build-fun}
 
 A build script in Zig always contains a public (and top-level) `build()` function declared.
-It is like the `main()` function on the main Zig module of your project, that we discussed at @sec-main-file.
+It is like the `main()` function on the main Zig module of your project, that we discussed in @sec-main-file.
 But instead of creating the entrypoint to your code, this `build()` function is the entrypoint to the build process.
 
 This `build()` function should accept a pointer to a `Build` object as input, and it should use this "build object" to perform
 the necessary steps to build your project. The return type of this function is always `void`,
-and this `Build` struct comes directly from the Zig Standard Library (`std.Build`). So, you can 
+and this `Build` struct comes directly from the Zig Standard Library (`std.Build`). So, you can
 access this struct by just importing the Zig Standard Library into your `build.zig` module.
 
 Just as a very simple example, here you can see the source code necessary to build
@@ -145,7 +145,7 @@ The Zig Build System official documentation have a [great code example that demo
 
 
 A target object is created by the following methods of the `Build` struct that we introduced
-at @sec-build-fun:
+in @sec-build-fun:
 
 - `addExecutable()` creates an executable file;
 - `addSharedLibrary()` creates a shared library file;
@@ -176,7 +176,7 @@ const exe = b.addExecutable(.{
 
 The `name` option specify the name that you want to give to the binary file defined
 by this target object. So, in this example, we are building an executable file named `hello`.
-Is common to set this `name` option to the name of your project.
+It's common to set this `name` option to the name of your project.
 
 
 Furthermore, the `target` option specify the target computer architecture (or the target operating system) of this
@@ -258,7 +258,7 @@ an "optimization vs safety" problem. So optimization plays an important role her
 Don't worry, I'm going back to this question very soon.
 
 In Zig, we have four build modes (which are listed below). Each one of these build modes offer
-different advantages and characteristics. As we described at @sec-compile-debug-mode, the `zig` compiler
+different advantages and characteristics. As we described in @sec-compile-debug-mode, the `zig` compiler
 uses the `Debug` build mode by default, when you don't explicitly choose a build mode.
 
 - `Debug`, mode that produces and includes debugging information in the output of the build process (i.e. the binary file defined by the target object);
@@ -322,7 +322,7 @@ b.installArtifact(exe);
 
 ## Detecting the OS in your build script {#sec-detect-os}
 
-Is very common in Build Systems to use different options, or, to include different modules, or,
+It's very common in Build Systems to use different options, or, to include different modules, or,
 to link against different libraries depending on the Operational System (OS)
 that you are targeting in the build process.
 
@@ -346,7 +346,7 @@ if (builtin.target.os.tag == .windows) {
 
 One thing that is neat in Rust is that you can compile and run your
 source code with one single command (`cargo run`) from the Rust compiler.
-We saw at @sec-compile-run-code how can we perform a similar job in Zig, by
+We saw in @sec-compile-run-code how can we perform a similar job in Zig, by
 building and running our Zig source code through the `run` command from the `zig` compiler.
 
 But how can we, at the same time, build and run the binary file specified by a target object in our
@@ -446,7 +446,7 @@ zig build run
 
 ## Build unit tests in your project
 
-We have talked at length about writing unit tests in Zig at @sec-unittests,
+We have talked at length about writing unit tests in Zig in @sec-unittests,
 and we also have talked about how to execute these unit tests through
 the `test` command of the `zig` compiler. However,
 as we did with the `run` command on the previous section, we also might want to
@@ -455,7 +455,7 @@ include some commands in our build script to also build and execute the unit tes
 So, once again, we are going to discuss how a specific built-in command from the `zig` compiler,
 (in this case, the `test` command) can be used in a build script in Zig.
 Here is where a "test target object" comes into play.
-As was described at @sec-targets, we can create a test target object by using the `addTest()` method of
+As was described in @sec-targets, we can create a test target object by using the `addTest()` method of
 the `Build` struct. The first thing that we need to do is to
 declare a test target object in our build script.
 
@@ -570,9 +570,9 @@ that represent your code, into a single executable file. It also links
 this executable file to external libraries, if you use any in your code.
 
 In Zig, we have two notions of a "library", which are: 1) a system's library;
-2) a local library. A system's library is just a library that already is installed
+2) a local library. A system's library is just a library that is already installed
 in your system. While a local library is a library that belongs to the current
-project. Is a library that is present in your project directory, and
+project; a library that is present in your project directory, and
 that you are building together with your project source code.
 
 The basic difference between the two, is that a system's library is already
@@ -732,7 +732,7 @@ const c_flags = [_][]const u8{
 
 In theory, there is nothing stopping you from using this array to add "include paths" (with the `-I` flag)
 or "library paths" (with the `-L` flag) to the compilation process. But there are formal ways in Zig to
-add these types of paths in the compilation process. Both are discussed at @sec-include-paths
+add these types of paths in the compilation process. Both are discussed in @sec-include-paths
 and @sec-library-paths.
 
 Anyway, in Zig, we add C flags to the build process together with the C files that we want to compile, by using the
@@ -786,7 +786,7 @@ across all C files, then, you will probably find `addCSourceFiles()` a better ch
 
 Notice that we are using the `addCSourceFiles()` method in the example below,
 to add both the C files and the C compiler flags. Also notice that we
-are using the `os.tag` that we learned about at @sec-detect-os, to add the platform-specific
+are using the `os.tag` that we learned about in @sec-detect-os, to add the platform-specific
 C files.
 
 ```{zig}
@@ -896,4 +896,3 @@ const inc_path: std.Build.LazyPath = .{
 };
 lib.addIncludePath(inc_path);
 ```
-
diff --git a/Chapters/09-data-structures.qmd b/Chapters/09-data-structures.qmd
index 82d26f5b..4b8f99cd 100644
--- a/Chapters/09-data-structures.qmd
+++ b/Chapters/09-data-structures.qmd
@@ -74,7 +74,7 @@ is ready to receive a value to be stored.
 
 ![Difference between capacity and length in a dynamic array](./../Figures/dynamic-array.png){#fig-capacity-length}
 
-We can also see at @fig-capacity-length that, when *length* and *capacity* are equal, it means that the array have no space left.
+We can also see in @fig-capacity-length that, when *length* and *capacity* are equal, it means that the array have no space left.
 We have reached the ceiling of our capacity, and because of that, if we want to store more values
 in this array, we need to expand it. We need to get a bigger space that can hold more values
 than what we currently have.
@@ -105,7 +105,7 @@ buffer.items.len;
 ### Creating an `ArrayList` object
 
 In order to use `ArrayList`, you must provide an allocator object to it.
-Remember, Zig does not have a default memory allocator. And as I described at @sec-allocators, all memory
+Remember, Zig does not have a default memory allocator. And as I described in @sec-allocators, all memory
 allocations must be done by an allocator object that you define, that
 you have control over. In our example here, I'm going to use
 a general purpose allocator, but you can use any other allocator
@@ -159,7 +159,7 @@ as the `append()` method from a Python list, or, the `emplace_back()` method fro
 You provide a single value to this method, and the method appends this value to the array.
 
 You can also use the `appendSlice()` method to append multiple values at once. You provide
-a slice (slices were described at @sec-arrays) to this method, and the method adds all values present
+a slice (slices were described in @sec-arrays) to this method, and the method adds all values present
 in this slice to your dynamic array.
 
 ```{zig}
@@ -175,7 +175,7 @@ try buffer.appendSlice(" World!");
 ### Removing elements from the array {#sec-dynamic-array-remove}
 
 You can use the `pop()` method to "pop" or remove
-the last element in the array. Is worth noting that this method
+the last element in the array. It's worth noting that this method
 do not change the capacity of the array. It just deletes or erases
 the last value stored in the array.
 
@@ -566,7 +566,7 @@ Some other properties of a `ArrayHashMap` hashtable are:
 You can create an `ArrayHashMap` object by using, once again, a helper function that
 chooses automatically for you a hash function implementation. This is the
 `AutoArrayHashMap()` function, which works very similarly to the `AutoHashMap()`
-function that we presented at @sec-hashmap.
+function that we presented in @sec-hashmap.
 
 You provide two data types to this function. The data type of the keys that will be
 used in this hashtable, and the data type of the values that will be stored in
@@ -578,7 +578,7 @@ a value from the hashtable by using the `get()` method. But the `remove()` metho
 in this specific type of hashtable.
 
 In order to delete values from the hashtable, you would use the same methods that you find in
-an `ArrayList` object, i.e. a dynamic array. I presented these methods at @sec-dynamic-array-remove,
+an `ArrayList` object, i.e. a dynamic array. I presented these methods in @sec-dynamic-array-remove,
 which are the `swapRemove()` and `orderedRemove()` methods. These methods have the same meaning here, or,
 the same effect that they have in an `ArrayList` object.
 
@@ -587,7 +587,7 @@ the order in which the values were inserted into the structure. While `orderedRe
 to retain the order in which these values were inserted.
 
 But instead of providing an index as input to `swapRemove()` or `orderedRemove()`, like I described
-at @sec-dynamic-array-remove, these methods here in an `ArrayHashMap` take a key as input, like
+in @sec-dynamic-array-remove, these methods here in an `ArrayHashMap` take a key as input, like
 the `remove()` method from a `HashMap` object. If you want to provide an index as input, instead
 of a key, you should use the `swapRemoveAt()` and `orderedRemoveAt()` methods.
 
@@ -683,16 +683,16 @@ that preserves insertion order, and also, that uses strings as keys.
 You can create such type of hashtable by using the `StringArrayHashMap()` function.
 This function accepts a data type as input, which is the data type of the values that are
 going to be stored inside this hashtable, in the same style as the function presented
-at @sec-string-hash-map.
+in @sec-string-hash-map.
 
 You can insert new values into this hashtable by using the same `put()` method that
-we have discussed at @sec-string-hash-map. And you can also get values from the hashtable
+we have discussed in @sec-string-hash-map. And you can also get values from the hashtable
 by using the same `get()` method.
 Like its `ArrayHashMap` brother, to delete values from this specific type of hashtable,
 we also use the `orderedRemove()` and `swapRemove()` methods, with the same effects that
-I have described at @sec-array-map.
+I have described in @sec-array-map.
 
-If we take the code example that was exposed at @sec-string-hash-map, we can
+If we take the code example that was exposed in @sec-string-hash-map, we can
 achieve the exact same result with `StringArrayHashMap()`:
 
 ```{zig}
@@ -716,7 +716,7 @@ connected to each other by pointers. This means that linked lists are usually no
 in memory, because each node might be anywhere in memory. They do not need to be close to
 one another.
 
-At @fig-linked-list we can see a diagram of a singly linked list. We begin at the first node
+In @fig-linked-list we can see a diagram of a singly linked list. We begin at the first node
 (which is usually called "the head of the linked list"). Then, from this
 first node we uncover the remaining nodes in the structure, by following the locations pointed
 by the pointers found in each node.
@@ -728,7 +728,7 @@ is null, then, it means that we have reached the end of our linked list.
 ![A diagram of a singly linked list.](./../Figures/linked-list.png){#fig-linked-list}
 
 
-At @fig-linked-list2 we can see a diagram of a doubly linked list. The only thing that really
+In @fig-linked-list2 we can see a diagram of a doubly linked list. The only thing that really
 changes now is that every node in the linked list has both a pointer to the previous node,
 and, a pointer to the next node. So every node in a doubly linked list has two pointers in it. These are
 usually called the `prev` (for "previous") and the `next` (for "next") pointers of the node.
@@ -742,7 +742,7 @@ normally have only the `next` pointer in them.
 
 Linked lists are available in Zig through the functions `SinglyLinkedList()` and
 `DoublyLinkedList()`, for "singly linked lists" and "doubly linked lists", respectively. These functions are
-actually generic functions, which we are going to talk more about at @sec-generic-fun.
+actually generic functions, which we are going to talk more about in @sec-generic-fun.
 
 For now, just understand that, in order to create a linked list object,
 we begin by providing a data type to these functions. This data type defines
@@ -774,7 +774,7 @@ When you provide a node to this method, it creates a pointer to this input node,
 and stores this pointer in the `next` attribute of the current node, from which the method was called from.
 
 Because doubly linked lists have both a `next` and a `prev` attributes in each node
-(as described at @fig-linked-list2), a node object created from
+(as described in @fig-linked-list2), a node object created from
 a `DoublyLinkedList` object have both an `insertBefore()` (for `prev`)
 and an `insertAfter()` (for `next`) methods available.
 
@@ -827,7 +827,7 @@ summary of them in the bullet points below:
 ## Multi array structure
 
 Zig introduces a new data structure called `MultiArrayList()`. It is a different version of the dynamic array
-that we have introduced at @sec-dynamic-array. The difference between this structure and the `ArrayList()`
+that we have introduced in @sec-dynamic-array. The difference between this structure and the `ArrayList()`
 that we know from @sec-dynamic-array, is that `MultiArrayList()` creates a separate dynamic array
 for each field of the struct that you provide as input.
 
@@ -954,9 +954,3 @@ There are some very specific data structures in this list, like a
 [^home]: <https://ziglang.org/documentation/master/std/#>
 [^priority]: <https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue>.
 [^bounded]: <https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray>
-
-
-
-
-
-
diff --git a/Chapters/09-error-handling.qmd b/Chapters/09-error-handling.qmd
index 81df68fc..ea05ebc7 100644
--- a/Chapters/09-error-handling.qmd
+++ b/Chapters/09-error-handling.qmd
@@ -20,7 +20,7 @@ knitr::opts_chunk$set(
 
 In this chapter, I want to discuss how error handling is done in Zig.
 We already briefly learned about one of the available strategies to handle errors in Zig,
-which is the `try` keyword presented at @sec-main-file. But we still haven't learned about
+which is the `try` keyword presented in @sec-main-file. But we still haven't learned about
 the other methods, such as the `catch` keyword.
 I also want to discuss in this chapter how union types are created in Zig.
 
@@ -73,7 +73,7 @@ t.zig:8:17: note: consider using 'try', 'catch', or 'if'
 
 ### Returning errors from functions
 
-As we described at @sec-main-file, when we have a function that might return an error
+As we described in @sec-main-file, when we have a function that might return an error
 value, this function normally includes an exclamation mark (`!`) in its return type
 annotation. The presence of this exclamation mark indicates that this function might
 return an error value as result, and, the `zig` compiler forces you to always handle explicitly
@@ -138,7 +138,7 @@ Unions are used to allow an object to have multiple data types.
 For example, a union of `x`, `y` and `z`, means that
 an object can be either of type `x`, or type `y` or type `z`.
 
-We are going to talk in more depth about unions at @sec-unions.
+We are going to talk in more depth about unions in @sec-unions.
 But you can write an error set by writing the keyword `error` before
 a pair of curly braces, then you list the error values that can be
 returned from the function inside this pair of curly braces.
@@ -269,7 +269,7 @@ return an error, we are basically referring to an expression that have
 a return type in the format `!T`.
 The `!` indicates that this expression returns either an error value, or a value of type `T`.
 
-At @sec-main-file, I presented the `try` keyword and where to use it.
+In @sec-main-file, I presented the `try` keyword and where to use it.
 But I did not talked about what exactly this keyword does to your code,
 or, in other words, I have not explained yet what `try` means in your code.
 
@@ -446,18 +446,18 @@ our program to leak resources of the system.
 
 The `errdefer` keyword is a tool to perform such "cleanup actions" in hostile situations.
 This keyword is commonly used to clean (or to free) allocated resources, before the execution of our program
-get's stopped because of an error value being generated.
+gets stopped because of an error value being generated.
 
 The basic idea is to provide an expression to the `errdefer` keyword. Then,
 `errdefer` executes this expression if, and only if, an error occurs
 during the execution of the current scope.
-In the example below, we are using an allocator object (that we have presented at @sec-allocators)
+In the example below, we are using an allocator object (that we have presented in @sec-allocators)
 to create a new `User` object. If we are successful in creating and registering this new user,
 this `create_user()` function will return this new `User` object as its return value.
 
 However, if for some reason, an error value is generated by some expression
 that is after the `errdefer` line, for example, in the `db.add(user)` expression,
-the expression registered by `errdefer` get's executed before the error value is returned
+the expression registered by `errdefer` gets executed before the error value is returned
 from the function, and before the program enters in panic mode and stops the
 current execution.
 
@@ -476,7 +476,7 @@ fn create_user(db: Database, allocator: Allocator) !User {
 
 By using `errdefer` to destroy the `user` object that we have just created,
 we guarantee that the memory allocated for this `user` object
-get's freed, before the execution of the program stops.
+gets freed, before the execution of the program stops.
 Because if the expression `try db.add(user)` returns an error value,
 the execution of our program stops, and we lose all references and control over the memory
 that we have allocated for the `user` object.
@@ -485,19 +485,19 @@ we cannot free this memory anymore. We simply lose our chance to do the right th
 That is why `errdefer` is essential in this situation.
 
 Just to state clearly the differences between `defer` and `errdefer`
-(which I described at @sec-defer and @sec-errdefer1), it might be worth
+(which I described in @sec-defer and @sec-errdefer1), it might be worth
 to discuss the subject a bit further. You might still have the question
 "why use `errdefer` if we can use `defer` instead?" in your mind.
 
 Although being similar, the key difference between `errdefer` and `defer` keyword
-is when the provided expression get's executed.
+is when the provided expression gets executed.
 The `defer` keyword always execute the provided expression at the end of the
 current scope, no matter how your code exits this scope.
 In contrast, `errdefer` executes the provided expression only when an error occurs in the
 current scope.
 
 This becomes important if a resource that you allocate in the
-current scope get's freed later in your code, in a different scope.
+current scope gets freed later in your code, in a different scope.
 The `create_user()` functions is an example of this. If you think
 closely about this function, you will notice that this function returns
 the `user` object as the result.
@@ -627,7 +627,7 @@ target = LakeTarget {
 };
 ```
 
-A curious fact about union types, is that, at first, you cannot use them in switch statements (which were presented at @sec-switch).
+A curious fact about union types, is that, at first, you cannot use them in switch statements (which were presented in @sec-switch).
 In other words, if you have an object of type `LakeTarget` for example, you cannot give this object
 as input to a switch statement.
 
@@ -654,4 +654,3 @@ pub const Registry = union(enum) {
     extension: ExtensionRegistry,
 };
 ```
-
diff --git a/Chapters/10-stack-project.qmd b/Chapters/10-stack-project.qmd
index ada7535d..3d9a8263 100644
--- a/Chapters/10-stack-project.qmd
+++ b/Chapters/10-stack-project.qmd
@@ -37,7 +37,7 @@ how generics work in Zig.
 
 One of the key features of Zig is `comptime`. This keyword introduces a whole
 new concept and paradigm, that is tightly connected with the compilation process.
-At @sec-compile-time we have described the importance and the role that "compile-time versus runtime"
+In @sec-compile-time we have described the importance and the role that "compile-time versus runtime"
 plays into Zig. At that section, we learned that the rules applied to a value/object change
 a lot depending on whether this value is known at compile-time, or just at runtime.
 
@@ -59,7 +59,7 @@ There are three ways in which you can apply the `comptime` keyword, which are:
 
 When you apply the `comptime` keyword on a function argument, you are saying to the `zig` compiler
 that the value assigned to that particular function argument must be known at compile-time.
-We explained in details at @sec-compile-time what exactly "value known at compile-time" means, so,
+We explained in details in @sec-compile-time what exactly "value known at compile-time" means, so,
 in case you have doubts about this idea, come back to that section.
 
 Now let's think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement
@@ -114,12 +114,12 @@ test "test comptime" {
 ```
 
 ```
-t.zig:12:16: error: runtime-known argument passed to comptime parameter 
+t.zig:12:16: error: runtime-known argument passed to comptime parameter
 ```
 
 Comptime arguments are frequently used on functions that return some sort
 of generic structure. In fact, `comptime` is the essence (or the basis) to make generics in Zig.
-We are going to talk more about generics at @sec-generics.
+We are going to talk more about generics in @sec-generics.
 
 For now, let's take a look at this code example from @karlseguin_generics. You
 can see that this `IntArray()` function have one argument named `length`.
@@ -140,7 +140,7 @@ think about the consequences of that. If the size of the array is dependent on
 the value assigned to the `length` argument, this means that the data type of the
 output of the function depends on the value of this `length` argument.
 
-Let this statement sink for a bit in your mind. As I described at @sec-root-file,
+Let this statement sink for a bit in your mind. As I described in @sec-root-file,
 Zig is a strongly-typed language, especially on function declarations.
 So every time we write a function in Zig, we have to annotate the data type of
 the value returned by the function. But how can we do that, if this data type
@@ -156,7 +156,7 @@ and raise a compilation error, saying something like this:
 So how can you solve this problem? How do we overcome this barrier? This is when
 the `type` keyword comes in. This `type` keyword is basically saying to the
 `zig` compiler that this function will return some data type as output, but it doesn't know yet
-what exactly data type that is. We will talk more about this at @sec-generics.
+what exactly data type that is. We will talk more about this in @sec-generics.
 
 
 
@@ -197,7 +197,7 @@ test "fibonacci" {
 A lot of your Zig source code might be potentially executed at compile-time,
 because the `zig` compiler can figure it out the output of some expressions.
 Especially if these expressions depends only at compile-time known values.
-We have talked about this at @sec-compile-time.
+We have talked about this in @sec-compile-time.
 
 But when you use the `comptime` keyword on an expression, there is no "it might be executed
 at compile-time" anymore. With the `comptime` keyword you are ordering the `zig` compiler
@@ -209,7 +209,7 @@ the compiler will raise a compilation error.
 
 ### Applying over a block
 
-Blocks were described at @sec-blocks. When you apply the `comptime` keyword over a
+Blocks were described in @sec-blocks. When you apply the `comptime` keyword over a
 block of expressions, you get essentially the same effect when you apply this keyword to
 a single expression. That is, the entire block of expressions is executed at
 compile-time by the `zig` compiler.
@@ -246,7 +246,7 @@ test "fibonacci in a block" {
 
 First of all, what is a generic? Generic is the idea to allow a type
 (`f64`, `u8`, `u32`, `bool`, and also, user-defined types, like the `User` struct
-that we defined at @sec-structs-and-oop) to be a parameter to methods, classes and
+that we defined in @sec-structs-and-oop) to be a parameter to methods, classes and
 interfaces [@geeks_generics]. In other words, a "generic" is a class (or a method) that can work
 with multiple data types.
 
@@ -272,7 +272,7 @@ Notice that this `T` argument have a data type of `type`. Weird right? This `typ
 Because we have used this `type` keyword in the `T` argument, we are telling
 the `zig` compiler that this `T` argument will receive some data type as input.
 Also notice the use of the `comptime` keyword in this argument.
-As I described at @sec-comptime, every time you use this keyword in a function argument,
+As I described in @sec-comptime, every time you use this keyword in a function argument,
 this means that the value of this argument must be known at compile-time.
 This makes sense, right? Because there is no data type that is not known at compile-time.
 
@@ -438,7 +438,7 @@ responsible for adding a new value to the stack.
 
 So how can we add a new value to the `Stack` object that we have?
 The `push()` function exposed below is a possible answer to this question.
-Remember from what we discussed at @sec-what-stack that values are always added to the top of the stack.
+Remember from what we discussed in @sec-what-stack that values are always added to the top of the stack.
 This means that this `push()` function must always find the element in the underlying array
 that currently represents the top position of the stack, and then, add the input value there.
 
@@ -565,7 +565,7 @@ For example, we might need to create a stack object to store `User` values
 in it. How can we make this possible? The answer lies on the use of generics
 and `comptime`.
 
-As I described at @sec-generic-struct, the basic idea is to write a generic
+As I described in @sec-generic-struct, the basic idea is to write a generic
 function that returns a struct definition as output.
 In theory, we do not need much to transform our `Stack` struct into a generic
 data structure. All that we need to do is to transform the underlying array
@@ -686,4 +686,3 @@ for the generic version, available inside the `ZigExamples` folder of the reposi
 
 [^zig-stack]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig>
 [^zig-stack2]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig>
-
diff --git a/Chapters/12-file-op.qmd b/Chapters/12-file-op.qmd
index 0a880e28..cdf64326 100644
--- a/Chapters/12-file-op.qmd
+++ b/Chapters/12-file-op.qmd
@@ -89,7 +89,7 @@ receiving new data from users, or, as another example, a live chat in a game tha
 receiving and displaying new messages from the players of the game.
 
 [^gen-zig]: Previously, these objects were known as the `Reader` and `Writer` objects.
-[^sock]: The socket objects that we have created at @sec-create-socket, are examples of network sockets.
+[^sock]: The socket objects that we have created in @sec-create-socket, are examples of network sockets.
 
 So, if you want to **read** data from something, or somewhere, it means that you need to use a `GenericReader` object.
 But if you need instead, to **write** data into this "something", then, you need to use a `GenericWriter` object instead.
@@ -173,7 +173,7 @@ a file descriptor to this particular IO resource.
 
 So you usually get a `File` object by using functions and methods from the Zig Standard Library
 that asks the OS to open some IO resource, like the `openFile()` method that opens a file in the
-filesystem. The `net.Stream` object that we have created at @sec-create-socket is also a type of
+filesystem. The `net.Stream` object that we have created in @sec-create-socket is also a type of
 file descriptor object.
 
 
@@ -277,7 +277,7 @@ the purpose of this channel.
 
 ## Buffered IO
 
-As we described at @sec-io-basics, input/output (IO) operations are made directly by the operating system.
+As we described in @sec-io-basics, input/output (IO) operations are made directly by the operating system.
 It is the OS that manages the IO resource that you want to use for your IO operations.
 The consequence of this fact is that IO operations are heavily based on system calls (i.e. calling the operating system directly).
 
@@ -294,16 +294,16 @@ the number of system calls performed to a minimum.
 ### Understanding how buffered IO works
 
 Buffered IO is a strategy to achieve better performance. It is used to reduce the number of system calls made by IO operations, and, as
-consequence, achieve a much higher performance. At @fig-unbuffered-io and @fig-buffered-io you can find two different diagrams
+consequence, achieve a much higher performance. In @fig-unbuffered-io and @fig-buffered-io you can find two different diagrams
 which presents the difference between read operations performed in an unbuffered IO environment versus a buffered IO environment.
 
 To give a better context to these diagrams, let's suppose that we have a text file that contains the famous Lorem ipsum text[^lorem]
-in our filesystem. Let's also suppose that these diagrams at @fig-unbuffered-io and @fig-buffered-io
+in our filesystem. Let's also suppose that these diagrams in @fig-unbuffered-io and @fig-buffered-io
 are showing the read operations that we are performing to read the Lorem ipsum text from this text file.
 The first thing you will notice when looking at these diagrams, is that in an unbuffered environment
 the read operations leads to many system calls.
-More precisely, in the diagram exposed at @fig-unbuffered-io we get one system call per each byte that we read from the text file.
-On the other hand, at @fig-buffered-io we have only one system call at the very beginning.
+More precisely, in the diagram exposed in @fig-unbuffered-io we get one system call per each byte that we read from the text file.
+On the other hand, in @fig-buffered-io we have only one system call at the very beginning.
 
 When we use a buffered IO system, at the first read operation we perform, instead of sending one single byte directly
 to our program, the OS first sends a chunk of bytes from the file to a buffer object (i.e. an array).
@@ -342,7 +342,7 @@ buffered depending on which functions from the standard libraries that you are u
 For example, in Rust, buffered IO is implemented through the `BufReader` and `BufWriter` structs, while in Zig, it is implemented
 through the `BufferedReader` and `BufferedWriter` structs.
 So any IO operation that you perform through the `GenericWriter` and `GenericReader` objects
-that I presented at @sec-writer-reader are not buffered, which means that these objects
+that I presented in @sec-writer-reader are not buffered, which means that these objects
 might create a lot of system calls depending on the situation.
 
 
@@ -364,7 +364,7 @@ function, which creates a new `BufferedWriter` or `BufferedReader` object. Then,
 the `writer()` or `reader()` methods of this buffered writer or buffered reader object,
 which gives you access to a generic writer or a generic reader object that is buffered.
 
-Take this program as an example. This program is demonstrating the process exposed at @fig-buffered-io.
+Take this program as an example. This program is demonstrating the process exposed in @fig-buffered-io.
 We are simply opening a text file that contains the Lorem ipsum text, and then, we create a buffered IO reader object
 at `bufreader`, and we use this `bufreader` object to read the contents of this file into a buffer object, then,
 we end the program by printing this buffer to `stdout`.
@@ -410,7 +410,7 @@ and have the exact same methods. So, although these two types of objects perform
 they have the same interface, so you, the programmer, can interchangeably use them
 without the need to change anything in your source code.
 So a buffered IO reader or a buffered IO writer objects have the same methods than its generic and unbuffered brothers,
-i.e. the generic reader and generic writer objects that I presented at @sec-writer-reader.
+i.e. the generic reader and generic writer objects that I presented in @sec-writer-reader.
 
 ::: {.callout-tip}
 In general, you should always use a buffered IO reader or a buffered IO writer object to perform
@@ -423,7 +423,7 @@ IO operations in Zig. Because they deliver better performance to your IO operati
 Now that we have discussed the basics around Input/Output operations in Zig, we need to
 talk about the basics around filesystems, which is another core part of any operating system.
 Also, filesystems are related to input/output, because the files that we store and create in our
-computer are considered an IO resource, as we described at @sec-file-descriptor.
+computer are considered an IO resource, as we described in @sec-file-descriptor.
 
 
 ### The concept of current working directory (CWD)
@@ -440,7 +440,7 @@ in the terminal. In other words, if you are in the terminal of your OS, and you
 execute a binary file (i.e. a program) from this terminal, the folder to which your terminal
 is pointing at is the current working directory of your program that is being executed.
 
-At @fig-cwd we have an example of me executing a program from the terminal. We are executing
+In @fig-cwd we have an example of me executing a program from the terminal. We are executing
 the program outputted by the `zig` compiler by compiling the Zig module named `hello.zig`.
 The CWD in this case is the `zig-book` folder. In other words, while the `hello.zig` program
 is executing, it will be looking at the `zig-book` folder, and any file operation that we perform
@@ -475,7 +475,7 @@ On Windows, the backward slash (`\`) is normally used to connect the path segmen
 slash (`/`) is the character used to connect path segments.
 
 A relative path is a path that start at the CWD. In other words, a relative path is
-"relative to the CWD". The path used to access the `hello.zig` file at @fig-cwd is an example of a relative path. This path
+"relative to the CWD". The path used to access the `hello.zig` file in @fig-cwd is an example of a relative path. This path
 is reproduced below. This path begins at the CWD, which in the context of @fig-cwd, is the `zig-book` folder,
 then, it goes to the `ZigExamples` folder, then, into `zig-basics`, then, to the `hello.zig` file.
 
@@ -544,7 +544,7 @@ do the necessary steps to create such file. You can also provide a relative path
 and it will create the file by following this path, which is relative to the CWD.
 
 This function might return an error, so, you should use `try`, `catch`, or any of the other methods presented
-at @sec-error-handling to handle the possible error. But if everything goes well,
+in @sec-error-handling to handle the possible error. But if everything goes well,
 this `createFile()` method returns a file descriptor object (i.e. a `File` object) as result,
 through which you can add content to the file with the IO operations that I presented before.
 
@@ -600,7 +600,7 @@ get a `NotOpenForReading` error as result.
 But how can you overcome this barrier? How can you create a file that is open
 to read operations? All you have to do, is to set the `read` flag to true
 in the second argument of `createFile()`. When you set this flag to true,
-then the file get's create with "read permissions", and, as consequence,
+then the file gets create with "read permissions", and, as consequence,
 a program like this one below becomes valid:
 
 
@@ -634,7 +634,7 @@ We are going to read this line
 
 If you are not familiar with position indicators, you might not recognize the method
 `seekTo()`. If that is your case, do not worry,
-we are going to talk more about this method at @sec-indicators. But essentially
+we are going to talk more about this method in @sec-indicators. But essentially
 this method is moving the position indicator back to the beginning of the file,
 so that we can read the contents of the file from the beginning.
 
@@ -649,11 +649,11 @@ that dictates how the file is opened.
 You can see the full list of options for `openFile()` by visiting the documentation for
 [`OpenFlags`](https://ziglang.org/documentation/master/std/#std.fs.File.OpenFlags)[^oflags].
 But the main flag that you will most certainly use is the `mode` flag.
-This flag specifies the IO mode that the file will be using when it get's opened.
+This flag specifies the IO mode that the file will be using when it gets opened.
 There are three IO modes, or, three values that you can provide to this flag, which are:
 
 - `read_only`, allows only read operations on the file. All write operations are blocked.
-- `write_only`, allows only write operations on the file. All read operations are blocked. 
+- `write_only`, allows only write operations on the file. All read operations are blocked.
 - `read_write`, allows both write and read operations on the file.
 
 [^oflags]: <https://ziglang.org/documentation/master/std/#std.fs.File.OpenFlags>
@@ -664,7 +664,7 @@ These modes are similar to the modes that you provide to the `mode` argument of
 In the code example below, we are opening the `foo.txt` text file with a `write_only` mode,
 and appending a new line of text to the end of the file. We use `seekFromEnd()` this time
 to guarantee that we are going to append the text to the end of the file. Once again, methods
-such as `seekFromEnd()` are described in more depth at @sec-indicators.
+such as `seekFromEnd()` are described in more depth in @sec-indicators.
 
 [^py-open]: <https://docs.python.org/3/tutorial/inputoutput.html#reading-and-writing-files>
 [^c-open]: <https://www.tutorialspoint.com/c_standard_library/c_function_fopen.htm>
@@ -754,7 +754,7 @@ to write 50 bytes into this same file, these 50 bytes will be written from the c
 position indicated by the position indicator. Since the indicator is at a 100 bytes forward from
 the beginning of the file, these 50 bytes would be written in the middle of the file.
 
-This is why we have used the `seekTo()` method at the last code example presented at @sec-creating-files.
+This is why we have used the `seekTo()` method at the last code example presented in @sec-creating-files.
 We have used this method to move the position indicator back to the beginning of the file, which
 would make sure that we would write the text that we wanted to write from the beginning of the file,
 instead of writing it from the middle of the file. Because before the write operation, we had
@@ -884,7 +884,3 @@ or how to open a directory, or how to create symbolic links, or how to use `acce
 path exists in your computer. But for all of these less common tasks, I recommend you to read
 the documentation of the [`Dir` type](https://ziglang.org/documentation/master/std/#std.fs.Dir)[^zig-dir]
 , since you can find a good description of these cases there.
-
-
-
-
diff --git a/Chapters/13-image-filter.qmd b/Chapters/13-image-filter.qmd
index 66e83e96..513b83c3 100644
--- a/Chapters/13-image-filter.qmd
+++ b/Chapters/13-image-filter.qmd
@@ -22,7 +22,7 @@ this project is to write a program that applies a filter over an image.
 More specifically, a "grayscale filter", which transforms
 any color image into a grayscale image.
 
-We are going to use the image displayed at @fig-pascal in this project.
+We are going to use the image displayed in @fig-pascal in this project.
 In other words, we want to transform this colored image into a grayscale image,
 by using our "image filter program" written in Zig.
 
@@ -34,9 +34,9 @@ by explaining the theory behind digital images and how colors are represented in
 We also give a brief explanation about the PNG (Portable Network Graphics) file format, which is the format used
 in the example images.
 
-At the end of this chapter, we should have a full example of a program that takes the PNG image displayed at @fig-pascal
+At the end of this chapter, we should have a full example of a program that takes the PNG image displayed in @fig-pascal
 as input, and writes a new image to the current working directory that is the grayscale version of this input image.
-This grayscale version of @fig-pascal is exposed at @fig-pascal-gray.
+This grayscale version of @fig-pascal is exposed in @fig-pascal-gray.
 You can find the full source code of this small project at the `ZigExamples/image_filter`
 [folder at the official repository of this book](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter)[^img-filter-folder].
 
@@ -131,13 +131,13 @@ and 70 of blue. In contrast, the set `(129, 77, 250)` describes a color that is
 This is not a rule written in stone, but the big majority of digital images are displayed from top
 to bottom and left to right. Most computers screens also follow this pattern. So, the first pixels
 in the image are the ones that are at the top and left corner of the image. You can find a visual representation
-of this logic at @fig-img-display.
+of this logic in @fig-img-display.
 
 Also notice in @fig-img-display that, because a raster image is essentially a 2D matrix of pixels,
 the image is organized into rows and columns of pixels. The columns are defined by the horizontal x axis,
 while the rows are defined by the vertical y axis.
 
-Each pixel (i.e. the gray rectangles) exposed at @fig-img-display contains a number inside of it.
+Each pixel (i.e. the gray rectangles) exposed in @fig-img-display contains a number inside of it.
 These numbers are the indexes of the pixels. You can notice that the first pixels are in the top and left
 corner, and also, that the indexes of these pixels "grow to the sides", or, in other words, they grow in the direction of the horizontal x axis.
 Most raster images are organized as rows of pixels. Thus, when these digital images are
@@ -214,9 +214,9 @@ to store this image in our Zig code, we need to create an array whose size is a
 
 Let's begin our project by focusing on writing the necessary Zig code to
 read the data from the PNG file. In other words, we want to read the PNG file exposed
-at @fig-pascal, and parse its data to extract the 2D matrix of pixels that represents the image.
+in @fig-pascal, and parse its data to extract the 2D matrix of pixels that represents the image.
 
-As we have discussed at @sec-pixel-repr, the image that we are using as example here
+As we have discussed in @sec-pixel-repr, the image that we are using as example here
 is a PNG file that uses the RGBA color model, and, therefore, each pixel of the image
 is represented by 4 integer values. You can download this image by visiting the `ZigExamples/image_filter`
 [folder at the official repository of this book](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter)[^img-filter-folder].
@@ -259,7 +259,7 @@ a function called `spng_decode_image()` that does all this heavy work for us.
 
 Now, since `libspng` is a C library, most of the file and I/O operations in this library are made by using
 a `FILE` C pointer. Because of that, is probably a better idea to use the `fopen()` C function
-to open our PNG file, instead of using the `openFile()` method that I introduced at @sec-filesystem.
+to open our PNG file, instead of using the `openFile()` method that I introduced in @sec-filesystem.
 That is why I'm importing the `stdio.h` C header in this project, and using the `fopen()` C function to open the file.
 
 If you look at the snippet below, you can see that we are:
@@ -328,7 +328,7 @@ image header section of the PNG file.
 
 Since this Zig function is receiving a C object (the `libspng` context object) as input, I marked
 the function argument `ctx` as "a pointer to the context object" (`*c.spng_ctx`), following the recommendations
-that we have discussed at @sec-pass-c-structs.
+that we have discussed in @sec-pass-c-structs.
 
 ```{zig}
 #| eval: false
@@ -463,7 +463,7 @@ the first $12 / 4 = 3$ pixels in the image.
 So, based on how these first 12 bytes (or these 3 pixels) look, with these 255 values at every 4 bytes, we can say that is likely
 that every pixel in the image have alpha (or transparency) setted to 100%. This might not be true,
 but, is the most likely possibility. Also, if we look at the image itself, which if your recall is
-exposed at @fig-pascal, we can see that the transparency does not change across the image,
+exposed in @fig-pascal, we can see that the transparency does not change across the image,
 which enforces this theory.
 
 
@@ -503,7 +503,7 @@ $$
     p' = (0.2126 \times r) + (0.7152 \times g) + (0.0722 \times b)
 $${#eq-grayscale}
 
-This @eq-grayscale is the formula to calculate the linear luminance of a pixel. Is worth noting that this formula
+This @eq-grayscale is the formula to calculate the linear luminance of a pixel. It's worth noting that this formula
 works only for images whose pixels are using the sRGB color space, which is the standard color space
 for the web. Thus, ideally, all images on the web should use this color space. Luckily,
 this is our case here, i.e. the `pedro_pascal.png` image is using this sRGB color space, and, as consequence,
@@ -610,7 +610,7 @@ try save_png(&image_header, buffer[0..]);
 
 After we execute this `save_png()` function, we should have a new PNG file
 inside our CWD, named `pedro_pascal_filter.png`. If we open this PNG file,
-we will see the same image exposed at @fig-pascal-gray.
+we will see the same image exposed in @fig-pascal-gray.
 
 
 ## Building our project
@@ -662,5 +662,3 @@ running the `zig build` command in the terminal.
 ```bash
 zig build
 ```
-
-
diff --git a/Chapters/14-threads.qmd b/Chapters/14-threads.qmd
index 8ddbc00a..3dd7802b 100644
--- a/Chapters/14-threads.qmd
+++ b/Chapters/14-threads.qmd
@@ -119,7 +119,7 @@ this `send_order()` function returns almost immediately,
 so the waiter spends almost no time worrying about the order, and just
 move on and tries to get the next order from the clients.
 
-Inside the new thread created, the order get's cooked by a chef, and when the
+Inside the new thread created, the order gets cooked by a chef, and when the
 food is ready, it is delivered to the client's table.
 
 
@@ -203,15 +203,15 @@ This method have three arguments, which are, respectively:
 1. the name of the function that is going to be executed (or, that is going to be "called") inside this new thread.
 1. a list of arguments (or inputs) to be passed to the function provided in the second argument.
 
-With these three arguments, you can control how the thread get's created, and also, specify which
+With these three arguments, you can control how the thread gets created, and also, specify which
 work (or "tasks") will be performed inside this new thread. A thread is just a separate context of execution,
 and we usually create new threads in our code, because we want to perform some work inside this
 new context of execution. And we specify which exact work, or, which exact steps that are going to be
 performed inside this context, by providing the name of a function on the second argument of the `spawn()` method.
 
-Thus, when this new thread get's created, this function that you provided as input to the `spawn()`
-method get's called, or, get's executed inside this new thread. You can control the
-arguments, or, the inputs that are passed to this function when it get's called, by providing
+Thus, when this new thread gets created, this function that you provided as input to the `spawn()`
+method gets called, or, gets executed inside this new thread. You can control the
+arguments, or, the inputs that are passed to this function when it gets called, by providing
 a list of arguments (or a list of inputs) on the third argument of the `spawn()` method.
 These arguments are passed to the function in the same order that they are
 provided to `spawn()`.
@@ -264,19 +264,19 @@ But, if the new thread is successfully created, the `spawn()` method returns a h
 object (which is just an object of type `Thread`) to this new thread. You can use
 this handler object to effectively control all aspects of the thread.
 
-When the thread get's created, the function that you provided as input to `spawn()`
-get's invoked (i.e. get's called) to start the execution on this new thread.
-In other words, everytime you call `spawn()`, not only a new thread get's created,
-but also, the "start work button" of this thread get's automatically pressed.
+When the thread gets created, the function that you provided as input to `spawn()`
+gets invoked (i.e. gets called) to start the execution on this new thread.
+In other words, everytime you call `spawn()`, not only a new thread gets created,
+but also, the "start work button" of this thread gets automatically pressed.
 So the work being performed in this thread starts at the moment that the thread is created.
 This is similar to how `pthread_create()` from the `pthreads` library in C works,
-which also starts the execution at the moment that the thread get's created.
+which also starts the execution at the moment that the thread gets created.
 
 
 ## Returning from a thread
 
 We have learned on the previous section that the execution of the thread starts at the moment
-that the thread get's created. Now, we will learn how to "join" or "detach" a thread in Zig.
+that the thread gets created. Now, we will learn how to "join" or "detach" a thread in Zig.
 "Join" and "detach" are operations that control how the thread returns to
 the main thread, or, to the main process in our program.
 
@@ -291,7 +291,7 @@ that you cannot call both `join()` and `detach()` on the same thread.
 But a thread must be one of the two, meaning that, you should always call
 either `join()` or `detach()` over a thread. If you don't call
 one of these two methods over your thread, you introduce undefined behaviour into your program,
-which is described at @sec-not-call-join-detach.
+which is described in @sec-not-call-join-detach.
 
 Now, let's describe what each of these two methods do to your thread.
 
@@ -305,7 +305,7 @@ and just called `join()` over this thread at the end. This section of the code e
 
 Because we are joining this new thread inside the `main()`'s scope, it means that the
 execution of the `main()` function is temporarily stopped, to wait for the execution of the thread
-to finish. That is, the execution of `main()` stops temporarily at the line where `join()` get's called,
+to finish. That is, the execution of `main()` stops temporarily at the line where `join()` gets called,
 and it will continue only after the thread has finished its tasks.
 
 ```{zig}
@@ -379,7 +379,7 @@ or vice-versa. This happens because:
 - the threads are executing basically at the same time as the main process of the program (i.e. the `main()` function).
 - the threads share the same `stdout` from the main process of the program, which means that the messages that the threads produce are sent to exact same place as the messages produced by the main process.
 
-Both of these points were described previously at @sec-what-thread.
+Both of these points were described previously in @sec-what-thread.
 So the messages might get intertwined because they are being produced and
 sent to the same `stdout` roughly at the same time.
 Anyway, when you call `join()` over a thread, the current process will wait
@@ -425,7 +425,7 @@ Finish main
 Now, if you look closely at the output of this code example, you will notice
 that only the final message in main was printed to the console. The message
 that was supposed to be printed by `print_id()` did not appear in the console.
-Why? Is because the main process of our program has finished first,
+Why? It's because the main process of our program has finished first,
 before the thread was able to say anything.
 
 And that is perfectly ok behaviour, because the thread was detached, so, it was
@@ -615,7 +615,7 @@ In summary, an operation is categorized as "atomic", when there is no way to hap
 the middle of this operation. In other words, this operation is always done from beginning to end, without interruptions
 of another process or operation in the middle of its execution phase.
 
-Not many operations today are atomic. But why atomic operations matters here? Is because data races
+Not many operations today are atomic. But why do atomic operations matter here? It's because data races
 (which is a type of a race condition) cannot happen on operations that are atomic.
 So if a particular line in your code performs an atomic operation, then, this line will never
 suffer from a data race problem. Therefore, programmers sometimes use an atomic operation
@@ -631,7 +631,7 @@ In this module, you will find a public and generic function called `Value()`. Wi
 a value that contains some native atomic operations, most notably, a `load()` and a `fetchAdd()` operation.
 If you have experience with multithreading in C++, you probably have recognized this pattern. So yes, this generic
 "atomic object" in Zig is essentially identical to the template struct `std::atomic` from the C++ Standard Library.
-Is important to emphasize that only primitive data types (i.e. the types presented at @sec-primitive-data-types)
+It's important to emphasize that only primitive data types (i.e. the types presented in @sec-primitive-data-types)
 are supported by these atomic operations in Zig.
 
 
@@ -646,13 +646,13 @@ which happens when one thread is accessing a particular memory location (i.e. a
 time that another thread is trying to write/save new data into this same memory location (i.e. the same shared object).
 
 We can simply define a race condition as any type of bug in your program that is based
-on a "who get's there first" problem. A data race problem is a type of a race condition, because it occurs when two or more parties
+on a "who gets there first" problem. A data race problem is a type of a race condition, because it occurs when two or more parties
 are trying to read and write into the same memory location at the same time, and, therefore, the end result of this operation
-depends completely on who get's to this memory location first.
+depends completely on who gets to this memory location first.
 As consequence, a program that have a data race problem will likely produce a different result each time that we execute it.
 
 Thus, race conditions produce undefined behaviour and unpredictability because the program produces
-a different answer in each time that a different person get's to the target location first than the others.
+a different answer in each time that a different person gets to the target location first than the others.
 And we have no easy way to either predict or control who is getting to this target location first.
 In other words, in each execution of your program, you get a different answer, because a different person,
 or, a different function, or, a different part of the code is finishing its tasks first than the others.
@@ -717,9 +717,9 @@ three basic operations at each iteration of the for loop, which are:
 
 Ideally, a thread B should read the value of `count`, only after the other thread A has finished
 writing the incremented value back into the `count` object. Therefore, in the ideal scenario, which is demonstrated
-at @tbl-data-race-ideal, the threads should work in sync with each other. But the reality is that these
+in @tbl-data-race-ideal, the threads should work in sync with each other. But the reality is that these
 threads are out of sync, and because of that, they suffer from a data race problem, which is demonstrated
-at @tbl-data-race-not.
+in @tbl-data-race-not.
 
 Notice that, in the data race scenario (@tbl-data-race-not), the read performed by a thread B happens
 before the write operation of thread A, and that ultimately leads to wrong results at the end of the program.
@@ -759,9 +759,9 @@ reading the new and incremented version of this value that would be calculated b
 
 
 If you think about these diagrams exposed in form of tables, you will notice that they relate back to our discussion of atomic operations
-at @sec-atomic-operation. Remember, atomic operations are operations that the CPU executes
+in @sec-atomic-operation. Remember, atomic operations are operations that the CPU executes
 from beginning to end, without interruptions from other threads or processes. So,
-the scenario exposed at @tbl-data-race-ideal do not suffer from a data race, because
+the scenario exposed in @tbl-data-race-ideal do not suffer from a data race, because
 the operations performed by thread A are not interrupted in the middle by the operations
 from thread B.
 
@@ -860,7 +860,7 @@ this C struct, you can create:
 The terminology might be a little different compared to Zig. But the meaning is still the same.
 Therefore, just remember this relationship, write locks are exclusive locks, while read locks are shared locks.
 
-When a thread tries to acquire a read lock (i.e. a shared lock), this thread get's the shared lock
+When a thread tries to acquire a read lock (i.e. a shared lock), this thread gets the shared lock
 if, and only if another thread does not currently holds a write lock (i.e. an exclusive lock), and also,
 if there are no other threads that are already in the queue,
 waiting for their turn to acquire a write lock. In other words, the thread in the queue have attempted
@@ -960,7 +960,7 @@ to focus on doing other things instead?".
 So this yield operation is also a way for you
 to stop a particular thread, so that you can work and prioritize other threads instead.
 
-Is important to say that, yielding a thread is a "not so common" thread operation these days.
+It's important to say that, yielding a thread is a "not so common" thread operation these days.
 In other words, not many programmers use yielding in production, simply because is hard to use
 this operation and make it work properly, and also, there
 are better alternatives. Most programmers prefer to use `join()` instead.
@@ -1002,7 +1002,7 @@ After that, the function sleeps for 1 second, to
 simulate some type of work, and then, the function tries to acquire the `mut2` lock.
 
 On the other hand, when we look into the second thread, which executes the `work2()` function,
-we can see that this function acquires the `mut2` lock first. Because when this thread get's created and it tries
+we can see that this function acquires the `mut2` lock first. Because when this thread gets created and it tries
 to acquire this `mut2` lock, the first thread is still sleeping on that "sleep 1 second" line.
 After acquiring `mut2`, the `work2()` function also sleeps for 1 second, to
 simulate some type of work, and then, the function tries to acquire the `mut1` lock.
@@ -1061,7 +1061,7 @@ control over the thread, and its resources are never freed
 
 When we think about the `pthreads` C library, there is a possible way to asynchronously kill or cancel
 a thread, which is by sending a `SIGTERM` signal to the thread through the `pthread_kill()` function.
-But canceling a thread like this is bad. Is dangerously bad. As consequence, the Zig implementation
+But canceling a thread like this is bad. It's dangerously bad. As consequence, the Zig implementation
 of threads does not have a similar function, or, a similar way to asynchronously cancel or kill
 a thread.
 
@@ -1069,13 +1069,13 @@ Therefore, if you want to cancel a thread in the middle of its execution in Zig,
 then, one good strategy that you can take is to use control flow in conjunction with `join()`.
 More specifically, you can design your thread around a while loop, that is constantly
 checking if the thread should continue running.
-If is time to cancel the thread, we could make the while loop break, and join the thread with the main thread
+If it's time to cancel the thread, we could make the while loop break, and join the thread with the main thread
 by calling `join()`.
 
 The code example below demonstrates to some extent this strategy.
 Here, we are using control flow to break the while loop, and exit the thread earlier than
 what we have initially planned to. This example also demonstrates how can we use
-atomic objects in Zig with the `Value()` generic function that we have mentioned at @sec-atomic-operation.
+atomic objects in Zig with the `Value()` generic function that we have mentioned in @sec-atomic-operation.
 
 
 ```{zig}
@@ -1110,4 +1110,3 @@ pub fn main() !void {
     thread.join();
 }
 ```
-
diff --git a/Chapters/14-zig-c-interop.qmd b/Chapters/14-zig-c-interop.qmd
index 97b9e73e..dd184bbc 100644
--- a/Chapters/14-zig-c-interop.qmd
+++ b/Chapters/14-zig-c-interop.qmd
@@ -19,7 +19,7 @@ knitr::opts_chunk$set(
 # Zig interoperability with C
 
 In this chapter, we are going to discuss the interoperability of Zig with C.
-We have discussed at @sec-building-c-code how you can use the `zig` compiler to build C code.
+We have discussed in @sec-building-c-code how you can use the `zig` compiler to build C code.
 But we haven't discussed yet how to actually use C code in Zig. In other words,
 we haven't discussed yet how to call and use C code from Zig.
 
@@ -33,7 +33,7 @@ this next project.
 
 Interoperability with C is not something new. Most high-level programming languages have FFI (foreign function interfaces),
 which can be used to call C code. For example, Python have Cython, R have `.Call()`, Javascript have `ccall()`, etc.
-But Zig integrates with C in a deeper level, which affects not only the way that C code get's called, but also,
+But Zig integrates with C in a deeper level, which affects not only the way that C code gets called, but also,
 how this C code is compiled and incorporated into your Zig project.
 
 In summary, Zig have great interoperability with C. If you want to call any C code from Zig,
@@ -111,7 +111,7 @@ installed in your system. Anyway, if you have doubts about this, comeback to @se
 
 ## Importing C header files {#sec-import-c-header}
 
-At @sec-strategy-c, we have described that, currently, there are two different paths that
+In @sec-strategy-c, we have described that, currently, there are two different paths that
 you can take to import a C header file into your Zig modules, `translate-c` or `@cImport()`.
 This section describes each strategy separately in more details.
 
@@ -134,7 +134,7 @@ Also notice that we are saving the results of the translation process inside a Z
 
 Therefore, after running this command, all we have to do is to import this `c.zig` module, and start
 calling the C functions that you want to call from it. The example below demonstrates that.
-Is important to remember what we've discussed at @sec-linking-c. In order to compile this
+It's important to remember what we've discussed in @sec-linking-c. In order to compile this
 example you have to link this code with `libc`, by passing the flag `-lc` to the `zig` compiler.
 
 ```{zig}
@@ -204,7 +204,7 @@ pub fn main() !void {
 
 Zig objects have some intrinsic differences between their C equivalents.
 Probably the most noticeable one is the difference between C strings and Zig strings,
-which I described at @sec-zig-strings.
+which I described in @sec-zig-strings.
 Zig strings are objects that contains both an array of arbitrary bytes and a length value.
 On the other hand, a C string is usually just a pointer to a null-terminated array of arbitrary bytes.
 
@@ -221,7 +221,7 @@ that Zig object into a C compatible value, before passing it to C code.
 
 There is also a third scenario that is not being described here, which is when you create a C object, or, a C struct, or
 a C compatible value in your Zig code, and you pass this C object/value as input to a C function in your Zig code.
-This scenario will be described later at @sec-c-inputs. In this section, we are focused on the scenarios where
+This scenario will be described later in @sec-c-inputs. In this section, we are focused on the scenarios where
 we are passing Zig objects/values to C code, instead of C objects/values being passed to C code.
 
 
@@ -231,7 +231,7 @@ An "auto-conversion" scenario is when the `zig` compiler automatically converts
 C compatible values for us. This specific scenario happens mostly in two instances:
 
 - with string literal values;
-- with any of the primitive data types that were introduced at @sec-primitive-data-types.
+- with any of the primitive data types that were introduced in @sec-primitive-data-types.
 
 When we think about the second instance described above, the `zig` compiler does automatically
 convert any of the primitive data types into their C equivalents, because the compiler knows how
@@ -321,7 +321,7 @@ Therefore, when we talk exclusively about string literal values, as long as you
 explicit data type to these string literal values, the `zig` compiler should be capable of automatically
 converting them into C strings as needed.
 
-But what about using one of the primitive data types that were introduced at @sec-primitive-data-types?
+But what about using one of the primitive data types that were introduced in @sec-primitive-data-types?
 Let's take code exposed below as an example of that. Here, we are giving some float literal values as input
 to the C function `powf()`. Notice that this code example compiles and runs successfully.
 
@@ -440,7 +440,7 @@ with no errors.
 ## Creating C objects in Zig {#sec-c-inputs}
 
 Creating C objects, or, in other words, creating instances of C structs in your Zig code
-is actually something quite easy to do. You first need to import the C header file (like I described at @sec-import-c-header) that defines
+is actually something quite easy to do. You first need to import the C header file (like I described in @sec-import-c-header) that defines
 the C struct that you are trying to instantiate in your Zig code. After that, you can just
 create a new object in your Zig code, and annotate it with the data type of the C struct.
 
@@ -469,7 +469,7 @@ i.e. the memory is currently populated with "garbage" values.
 Thus, this expression have the exact same effect of the expression `User new_user;` in C,
 which means "declare a new object named `new_user` of type `User`".
 
-Is our responsibility to properly initialize this memory associated with this `new_user` object,
+It's our responsibility to properly initialize this memory associated with this `new_user` object,
 by assigning valid values to the members (or the fields) of the C struct. In the example below,
 I'm assigning the integer 1 to the member `id`. I am also saving the string `"pedropark99"` into the member `name`.
 Notice in this example that I manually add the null character (zero byte) to the end of the allocated array
@@ -538,7 +538,7 @@ any special manner to use them in C code. This is how we create and use C object
 
 Now that we have learned how to create/declare C objects in our Zig code, we
 need to learn how to pass these C objects as inputs to Zig functions.
-As I described at @sec-c-inputs, we can freely pass these C objects as inputs to C code
+As I described in @sec-c-inputs, we can freely pass these C objects as inputs to C code
 that we call from our Zig code. But what about passing these C objects to Zig functions?
 
 In essence, this specific case requires one small adjustment in the Zig function declaration.
@@ -546,7 +546,7 @@ All you need to do, is to make sure that you pass your C object *by reference* t
 instead of passing it *by value*. To do that, you have to annotate the data type of the function argument
 that is receiving this C object as "a pointer to the C struct", instead of annotating it as "an instance of the C struct".
 
-Let's consider the C struct `User` from the `user.h` C header file that we have used at @sec-c-inputs.
+Let's consider the C struct `User` from the `user.h` C header file that we have used in @sec-c-inputs.
 Now, consider that we want to create a Zig function that sets the value of the `id` field
 in this C struct, like the `set_user_id()` function declared below.
 Notice that the `user` argument in this function is annotated as a pointer (`*`) to a `c.User` object.
@@ -593,4 +593,3 @@ pub fn main() !void {
 ```
 New ID: 25
 ```
-
diff --git a/Chapters/15-vectors.qmd b/Chapters/15-vectors.qmd
index 94019c19..47d3fd60 100644
--- a/Chapters/15-vectors.qmd
+++ b/Chapters/15-vectors.qmd
@@ -123,7 +123,7 @@ _ = v1; _ = v2;
 ```
 
 
-Is worth emphasizing that only arrays and slices whose sizes
+It's worth emphasizing that only arrays and slices whose sizes
 are compile-time known can be transformed into vectors. Vectors in general
 are structures that work only with compile-time known sizes. Therefore, if
 you have an array whose size is runtime known, then, you first need to
@@ -154,7 +154,7 @@ try stdout.print("{any}\n", .{v1});
 
 ### Careful with vectors that are too big
 
-As I described at @sec-what-vectors, each vector object is usually a small block of 128, 256 or 512 bits.
+As I described in @sec-what-vectors, each vector object is usually a small block of 128, 256 or 512 bits.
 This means that a vector object is usually small in size, and when you try to go in the opposite direction,
 by creating a vector object that is very big in size (i.e. sizes that are close to $2^{20}$),
 you usually end up with crashes and loud errors from the compiler.
@@ -171,7 +171,3 @@ _ = v1;
 ```
 Segmentation fault (core dumped)
 ```
-
-
-
-
diff --git a/README.md b/README.md
index cf953f91..567e904d 100644
--- a/README.md
+++ b/README.md
@@ -95,7 +95,7 @@ You can find instructions on how to install these pieces of software by clicking
 After you installed the three pieces of software listed above, you should run the `dependencies.R` R script, to install
 some R packages that are used across the book. Just run the command below in your terminal, and you should be fine.
 
-OBS: If you are on Linux or MacOS, this command will probably take some time to run, because every single dependency get's built from source.
+OBS: If you are on Linux or MacOS, this command will probably take some time to run, because every single dependency gets built from source.
 In Windows, this usually doesn't take that long because pre-built binaries are usually available.
 
 ```bash
@@ -138,5 +138,3 @@ slower than the first one, but is more garanteed to work.
 Copyright © 2024 Pedro Duarte Faria. This book is licensed by the CC-BY 4.0 Creative Commons Attribution 4.0 International Public License.
 
 <a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a>
-
-
diff --git a/zig_engine.R b/zig_engine.R
index d3831fc5..9471c870 100644
--- a/zig_engine.R
+++ b/zig_engine.R
@@ -173,7 +173,7 @@ increase_indentation__ <- function(code_without_main) {
 #' This function is used to get the value of the `auto_main` code block option.
 #' The `auto_main` code block option is used to specify if the Zig code written
 #' in the current code block should (or should not) be encapsulated inside a
-#' `main()` function, before it get's sent to the Zig compiler to be compiled.
+#' `main()` function, before it gets sent to the Zig compiler to be compiled.
 #'
 #' If the user did not configured/setted this
 #' specific option in the current code block that is being analyzed,

From eb5665b1eba9c82776eafb3b98e08114dd71f983 Mon Sep 17 00:00:00 2001
From: Glystik <glystik@proton.me>
Date: Tue, 25 Feb 2025 17:41:25 +0100
Subject: [PATCH 102/151] Fixing typos and grammar

---
 Chapters/01-base64.qmd       | 6 +++---
 Chapters/01-memory.qmd       | 2 +-
 Chapters/01-zig-weird.qmd    | 2 +-
 Chapters/02-debugging.qmd    | 2 +-
 Chapters/04-http-server.qmd  | 6 +++---
 Chapters/07-build-system.qmd | 4 ++--
 Chapters/14-threads.qmd      | 8 ++++----
 Chapters/15-vectors.qmd      | 6 +++---
 8 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/Chapters/01-base64.qmd b/Chapters/01-base64.qmd
index 0d9a22f5..cddc5b70 100644
--- a/Chapters/01-base64.qmd
+++ b/Chapters/01-base64.qmd
@@ -170,9 +170,9 @@ the algorithm does, is to check how to divide the input bytes into groups of 6 b
 
 If the algorithm notices that there is a group of 6 bits that, have some bits in it, but, at the same time, it is not full
 (in other words, $0 < nbits < 6$, being $nbits$ the number of bits), meaning that, it lacks
-some bits to fill the 6-bits requirement, the algorithm simply add extra zeros in this group
-to fill the space that it needs. That is why in @fig-base64-algo1, on the third group after the 6-bit transformation,
-2 extra zeros were added to fill the gap in this group.
+some bits to fill the 6-bits requirement, the algorithm simply adds extra zeros in this group
+to fill the space that it needs. That is why in @fig-base64-algo1, in the third group after the 6-bit transformation,
+2 extra zeros were added to fill the gap.
 
 When we have a 6-bit group that is not completely full, like the third group, extra zeros
 are added to fill the gap. But what about when an entire 6-bit group is empty, or, it
diff --git a/Chapters/01-memory.qmd b/Chapters/01-memory.qmd
index c08ce5d9..f92e5bd0 100644
--- a/Chapters/01-memory.qmd
+++ b/Chapters/01-memory.qmd
@@ -695,7 +695,7 @@ of the allocator object is used to allocate an array capable of storing 50 `u8`
 Notice that this `alloc()` method receives two inputs. The first one, is a type.
 This defines what type of values the allocated array will store. In the example
 below, we are allocating an array of unsigned 8-bit integers (`u8`). But
-you can create an array to store any type of value you want. Next, on the second argument, we
+you can create an array to store any type of value you want. Next, in the second argument, we
 define the size of the allocated array, by specifying how many elements
 this array will contain. In the case below, we are allocating an array of 50 elements.
 
diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index 4b395303..18afd01f 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -406,7 +406,7 @@ exposed below:
 #| auto_main: false
 #| build_type: "ast"
 const std = @import("std");
-// ERROR! Compile-time error that emerge from
+// ERROR! Compile-time error that emerges from
 // this next line, on the `stdout` object
 const stdout = std.io.getStdOut().writer();
 
diff --git a/Chapters/02-debugging.qmd b/Chapters/02-debugging.qmd
index 851c8d44..23751eb7 100644
--- a/Chapters/02-debugging.qmd
+++ b/Chapters/02-debugging.qmd
@@ -142,7 +142,7 @@ or LLDB (LLVM Project Debugger) as your debugger.
 
 Both debuggers can work with Zig code, and it's a matter of taste here.
 You choose the debugger of your preference, and you work with it.
-In this book, I will use LLDB as my debugger on the examples.
+In this book, I will use LLDB as my debugger in the examples.
 
 
 ### Compile your source code in debug mode {#sec-compile-debug-mode}
diff --git a/Chapters/04-http-server.qmd b/Chapters/04-http-server.qmd
index 2cb1fe62..e4804dd8 100644
--- a/Chapters/04-http-server.qmd
+++ b/Chapters/04-http-server.qmd
@@ -283,7 +283,7 @@ when someone tries to connect to the socket. This means that, the `accept()` met
 returns a new connection object as a result. And you can use this connection object
 to read or write messages from or to the client.
 For now, we are not doing anything with this connection object.
-But we are going to use it on the next section.
+But we are going to use it in the next section.
 
 
 ```{zig}
@@ -306,7 +306,7 @@ server will wait for one incoming connection, and as soon as the
 server is done with this first connection that it establishes, the
 program ends, and the server stops.
 
-This is not the norm on the real world. Most people that write
+This is not the norm in the real world. Most people that write
 a HTTP server like this, usually put the `accept()` method
 inside a `while` (infinite) loop, where if a connection
 is created with `accept()`, a new thread of execution is created to deal with
@@ -530,7 +530,7 @@ work in C. Each enum value is essentially represented as an integer.
 The first value in the set is represented as zero,
 then, the second value is one, ... etc.
 
-One thing that we are going to learn on the next section is that
+One thing that we are going to learn in the next section is that
 enums can have methods in them. Wait... What? This is amazing!
 Yes, enums in Zig are similar to structs, and they can have
 private and public methods inside them.
diff --git a/Chapters/07-build-system.qmd b/Chapters/07-build-system.qmd
index d1dce207..349fc81b 100644
--- a/Chapters/07-build-system.qmd
+++ b/Chapters/07-build-system.qmd
@@ -27,7 +27,7 @@ from the compiler, to build your code.
 
 
 You can find a good description of Zig's build system
-on the [article entitled "Build System"](https://ziglang.org/learn/build-system/#user-provided-options)[^zig-art1]
+in the [article entitled "Build System"](https://ziglang.org/learn/build-system/#user-provided-options)[^zig-art1]
 from the official Zig's website.
 We also have the excellent [series of posts written by Felix](https://zig.news/xq/zig-build-explained-part-1-59lf)[^felix].
 Hence, this chapter represents an extra resource for you to consult and rely on.
@@ -823,7 +823,7 @@ by using the `defineCMacro()` method from the target object that
 defines the binary file that you are building.
 
 In the example below, we are using the `lib` object that we have defined
-on the previous sections to define some C Macros used by the FreeType project
+in the previous sections to define some C Macros used by the FreeType project
 in the compilation process. These C Macros specify if FreeType
 should (or should not) include functionalities from different
 external libraries.
diff --git a/Chapters/14-threads.qmd b/Chapters/14-threads.qmd
index 3dd7802b..bf99dffa 100644
--- a/Chapters/14-threads.qmd
+++ b/Chapters/14-threads.qmd
@@ -207,12 +207,12 @@ With these three arguments, you can control how the thread gets created, and als
 work (or "tasks") will be performed inside this new thread. A thread is just a separate context of execution,
 and we usually create new threads in our code, because we want to perform some work inside this
 new context of execution. And we specify which exact work, or, which exact steps that are going to be
-performed inside this context, by providing the name of a function on the second argument of the `spawn()` method.
+performed inside this context, by providing the name of a function in the second argument of the `spawn()` method.
 
 Thus, when this new thread gets created, this function that you provided as input to the `spawn()`
 method gets called, or, gets executed inside this new thread. You can control the
 arguments, or, the inputs that are passed to this function when it gets called, by providing
-a list of arguments (or a list of inputs) on the third argument of the `spawn()` method.
+a list of arguments (or a list of inputs) in the third argument of the `spawn()` method.
 These arguments are passed to the function in the same order that they are
 provided to `spawn()`.
 
@@ -275,7 +275,7 @@ which also starts the execution at the moment that the thread gets created.
 
 ## Returning from a thread
 
-We have learned on the previous section that the execution of the thread starts at the moment
+We have learned in the previous section that the execution of the thread starts at the moment
 that the thread gets created. Now, we will learn how to "join" or "detach" a thread in Zig.
 "Join" and "detach" are operations that control how the thread returns to
 the main thread, or, to the main process in our program.
@@ -558,7 +558,7 @@ and, therefore, the other people (in this case, the other threads) that wants to
 have to be patient, and simply wait for the other person (or the other thread) to unlock the door and get out of the bathroom.
 
 Some other programmers also like to explain mutexes by using the analogy of "each person will have their turn to speak".
-This is the analogy used on the [*Multithreading Code* video from the Computerphile project](https://www.youtube.com/watch?v=7ENFeb-J75k&ab_channel=Computerphile)[^computerphile].
+This is the analogy used in the [*Multithreading Code* video from the Computerphile project](https://www.youtube.com/watch?v=7ENFeb-J75k&ab_channel=Computerphile)[^computerphile].
 Imagine if you are in a conversation circle. There is a moderator in this circle, which is the person that decides who
 have the right to speak at that particular moment. The moderator gives a green card (or some sort of an authorization card) to the person that
 is going to speak, and, as a result, everyone else must be silent and hear this person that has the green card.
diff --git a/Chapters/15-vectors.qmd b/Chapters/15-vectors.qmd
index 47d3fd60..ee6c5335 100644
--- a/Chapters/15-vectors.qmd
+++ b/Chapters/15-vectors.qmd
@@ -34,8 +34,8 @@ Most modern CPU models (from AMD, Intel, etc.) these days (either in a desktop o
 notebook model) have support for SIMD operations. So, if you have a very old CPU model installed in your
 computer, then, is possible that you have no support for SIMD operations in your computer.
 
-Why people have started using SIMD on their software? The answer is performance.
-But what SIMD precisely do to achieve better performance? Well, in essence, SIMD operations are a different
+Why have people started using SIMD in their software? The answer is performance.
+But what precisely are SIMD doing to achieve better performance? Well, in essence, SIMD operations are a different
 strategy to get parallel computing in your program, and therefore, make faster calculations.
 
 The basic idea behind SIMD is to have a single instruction that operates over multiple data
@@ -93,7 +93,7 @@ to iterate through the elements of `v1` and `v2`, and adding them together, one
 we enjoy the benefits of SIMD, which performs all 4 additions in parallel, at the same time.
 
 Therefore, the `@Vector` structure is essentially the Zig representation of SIMD vector objects.
-The elements on these vector objects will be operated in parallel, if, and only if your current CPU model
+The elements in these vector objects will be operated in parallel, if, and only if your current CPU model
 supports SIMD operations. If your CPU model does not have support for SIMD, then, the `@Vector` structure will
 likely produce a similar performance from a "for loop solution".
 

From ad348c8a6bf97ddf8aeba57035bd9946b3173119 Mon Sep 17 00:00:00 2001
From: Michael Lynch <git@mtlynch.io>
Date: Tue, 25 Feb 2025 14:36:11 -0500
Subject: [PATCH 103/151] Fix syntax of get's -> gets

There's an error pattern in the book in that the word 'get's' appears frequently, but this is not correct English syntax. The word 'gets' has no apostrophe, so this change replaces instances of 'get's' with 'gets'.

Note that I only updated Markdown files and did not modify the JSON files, as the JSON files appear to be derived from the Markdown files.
---
 Chapters/01-zig-weird.qmd      | 10 +++++-----
 Chapters/03-structs.qmd        |  6 +++---
 Chapters/07-build-system.qmd   |  2 +-
 Chapters/09-error-handling.qmd | 10 +++++-----
 Chapters/12-file-op.qmd        |  4 ++--
 Chapters/14-threads.qmd        |  2 +-
 Chapters/14-zig-c-interop.qmd  |  2 +-
 README.md                      |  2 +-
 zig_engine.R                   |  2 +-
 9 files changed, 20 insertions(+), 20 deletions(-)

diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index 1a1afa74..063e87ac 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -60,7 +60,7 @@ your C code. With macros, you are no longer 100% sure about which pieces
 of the code are being sent to the compiler, i.e.
 they obscure the actual source code that you wrote.
 
-You don't have macros in Zig. In Zig, the code you write, is the actual code that get's compiled by the compiler.
+You don't have macros in Zig. In Zig, the code you write, is the actual code that gets compiled by the compiler.
 You also don't have a hidden control flow happening behind the scenes. And, you also
 don't have functions or operators from the standard library that make
 hidden memory allocations behind your back.
@@ -771,7 +771,7 @@ t.zig:7:5: error: pointless discard
 
 This same rule applies to variable objects. Every variable object must also be used in
 some way. And if you assign a variable object to the underscore,
-this object also get's discarded, and you can no longer use this object.
+this object also gets discarded, and you can no longer use this object.
 
 
 
@@ -1023,12 +1023,12 @@ Therefore, we don't know the value of this thing at compile-time, only at runtim
 
 We have learned at @sec-select-array-elem that slices are created by using a *range selector*,
 which represents a range of indexes. When this "range of indexes" (i.e. the start and the end of this range)
-is known at compile-time, the slice object that get's created is actually, under the hood, just
+is known at compile-time, the slice object that gets created is actually, under the hood, just
 a single-item pointer to an array.
 
 You don't need to precisely understand what that means now. We are going to talk a lot about pointers
 at @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,
-the slice that get's created is just a pointer to an array, accompanied by a length value that
+the slice that gets created is just a pointer to an array, accompanied by a length value that
 tells the size of the slice.
 
 If you have a slice object like this, i.e. a slice that has a compile-time known range,
@@ -1050,7 +1050,7 @@ const slice = arr1[1..4];
 
 
 On the other hand, if the range of indexes is not known at compile time, then, the slice object
-that get's created is not a pointer anymore, and, thus, it does not support pointer operations.
+that gets created is not a pointer anymore, and, thus, it does not support pointer operations.
 For example, maybe the start index is known at compile time, but the end index is not. In such
 case, the range of the slice becomes runtime known only.
 
diff --git a/Chapters/03-structs.qmd b/Chapters/03-structs.qmd
index 008c5e72..26f03b18 100644
--- a/Chapters/03-structs.qmd
+++ b/Chapters/03-structs.qmd
@@ -410,7 +410,7 @@ You could also interpret this as: "defer expressions" are executed from bottom t
 from last to first.
 
 Therefore, if I change the order of the `defer` and `errdefer` expressions, you will notice that
-the value of `i` that get's printed to the console changes to 1. This doesn't mean that the
+the value of `i` that gets printed to the console changes to 1. This doesn't mean that the
 `defer` expression was not executed in this case. This actually means that the `defer` expression
 was executed only after the `errdefer` expression. The code example below demonstrates this:
 
@@ -1287,9 +1287,9 @@ are basically accessing the data members of the struct stored in the `std`
 object. That is why we use the same syntax that we use in normal structs, with the dot operator (`.`)
 to access the data members and methods of the struct.
 
-When this "import statement" get's executed, the result of this expression is a struct
+When this "import statement" gets executed, the result of this expression is a struct
 object that contains the Zig Standard Library modules, global variables, functions, etc.
-And this struct object get's saved (or stored) inside the constant object named `std`.
+And this struct object gets saved (or stored) inside the constant object named `std`.
 
 
 Take the [`thread_pool.zig` module from the project `zap`](https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig)[^thread]
diff --git a/Chapters/07-build-system.qmd b/Chapters/07-build-system.qmd
index 6bced377..0fe6f2b4 100644
--- a/Chapters/07-build-system.qmd
+++ b/Chapters/07-build-system.qmd
@@ -73,7 +73,7 @@ If that is not your case, you can forget about it.
 Your build process is usually organized in a build script. In Zig, we normally
 write this build script into a Zig module in the root directory of our project,
 named as `build.zig`. You write this build script, then, when you run it, your project
-get's built into binary files that you can use and distribute to your users.
+gets built into binary files that you can use and distribute to your users.
 
 This build script is normally organized around *target objects*. A target is simply
 something to be built, or, in other words, it's something that you want the `zig` compiler
diff --git a/Chapters/09-error-handling.qmd b/Chapters/09-error-handling.qmd
index 81df68fc..5a92b0fb 100644
--- a/Chapters/09-error-handling.qmd
+++ b/Chapters/09-error-handling.qmd
@@ -446,7 +446,7 @@ our program to leak resources of the system.
 
 The `errdefer` keyword is a tool to perform such "cleanup actions" in hostile situations.
 This keyword is commonly used to clean (or to free) allocated resources, before the execution of our program
-get's stopped because of an error value being generated.
+gets stopped because of an error value being generated.
 
 The basic idea is to provide an expression to the `errdefer` keyword. Then,
 `errdefer` executes this expression if, and only if, an error occurs
@@ -457,7 +457,7 @@ this `create_user()` function will return this new `User` object as its return v
 
 However, if for some reason, an error value is generated by some expression
 that is after the `errdefer` line, for example, in the `db.add(user)` expression,
-the expression registered by `errdefer` get's executed before the error value is returned
+the expression registered by `errdefer` gets executed before the error value is returned
 from the function, and before the program enters in panic mode and stops the
 current execution.
 
@@ -476,7 +476,7 @@ fn create_user(db: Database, allocator: Allocator) !User {
 
 By using `errdefer` to destroy the `user` object that we have just created,
 we guarantee that the memory allocated for this `user` object
-get's freed, before the execution of the program stops.
+gets freed, before the execution of the program stops.
 Because if the expression `try db.add(user)` returns an error value,
 the execution of our program stops, and we lose all references and control over the memory
 that we have allocated for the `user` object.
@@ -490,14 +490,14 @@ to discuss the subject a bit further. You might still have the question
 "why use `errdefer` if we can use `defer` instead?" in your mind.
 
 Although being similar, the key difference between `errdefer` and `defer` keyword
-is when the provided expression get's executed.
+is when the provided expression gets executed.
 The `defer` keyword always execute the provided expression at the end of the
 current scope, no matter how your code exits this scope.
 In contrast, `errdefer` executes the provided expression only when an error occurs in the
 current scope.
 
 This becomes important if a resource that you allocate in the
-current scope get's freed later in your code, in a different scope.
+current scope gets freed later in your code, in a different scope.
 The `create_user()` functions is an example of this. If you think
 closely about this function, you will notice that this function returns
 the `user` object as the result.
diff --git a/Chapters/12-file-op.qmd b/Chapters/12-file-op.qmd
index 0a880e28..1ccc6ad8 100644
--- a/Chapters/12-file-op.qmd
+++ b/Chapters/12-file-op.qmd
@@ -600,7 +600,7 @@ get a `NotOpenForReading` error as result.
 But how can you overcome this barrier? How can you create a file that is open
 to read operations? All you have to do, is to set the `read` flag to true
 in the second argument of `createFile()`. When you set this flag to true,
-then the file get's create with "read permissions", and, as consequence,
+then the file gets create with "read permissions", and, as consequence,
 a program like this one below becomes valid:
 
 
@@ -649,7 +649,7 @@ that dictates how the file is opened.
 You can see the full list of options for `openFile()` by visiting the documentation for
 [`OpenFlags`](https://ziglang.org/documentation/master/std/#std.fs.File.OpenFlags)[^oflags].
 But the main flag that you will most certainly use is the `mode` flag.
-This flag specifies the IO mode that the file will be using when it get's opened.
+This flag specifies the IO mode that the file will be using when it gets opened.
 There are three IO modes, or, three values that you can provide to this flag, which are:
 
 - `read_only`, allows only read operations on the file. All write operations are blocked.
diff --git a/Chapters/14-threads.qmd b/Chapters/14-threads.qmd
index 232fee95..8ec78648 100644
--- a/Chapters/14-threads.qmd
+++ b/Chapters/14-threads.qmd
@@ -119,7 +119,7 @@ this `send_order()` function returns almost immediately,
 so the waiter spends almost no time worrying about the order, and just
 move on and tries to get the next order from the clients.
 
-Inside the new thread created, the order get's cooked by a chef, and when the
+Inside the new thread created, the order gets cooked by a chef, and when the
 food is ready, it is delivered to the client's table.
 
 
diff --git a/Chapters/14-zig-c-interop.qmd b/Chapters/14-zig-c-interop.qmd
index 97b9e73e..5b1d133b 100644
--- a/Chapters/14-zig-c-interop.qmd
+++ b/Chapters/14-zig-c-interop.qmd
@@ -33,7 +33,7 @@ this next project.
 
 Interoperability with C is not something new. Most high-level programming languages have FFI (foreign function interfaces),
 which can be used to call C code. For example, Python have Cython, R have `.Call()`, Javascript have `ccall()`, etc.
-But Zig integrates with C in a deeper level, which affects not only the way that C code get's called, but also,
+But Zig integrates with C in a deeper level, which affects not only the way that C code gets called, but also,
 how this C code is compiled and incorporated into your Zig project.
 
 In summary, Zig have great interoperability with C. If you want to call any C code from Zig,
diff --git a/README.md b/README.md
index cf953f91..b450a5dc 100644
--- a/README.md
+++ b/README.md
@@ -95,7 +95,7 @@ You can find instructions on how to install these pieces of software by clicking
 After you installed the three pieces of software listed above, you should run the `dependencies.R` R script, to install
 some R packages that are used across the book. Just run the command below in your terminal, and you should be fine.
 
-OBS: If you are on Linux or MacOS, this command will probably take some time to run, because every single dependency get's built from source.
+OBS: If you are on Linux or MacOS, this command will probably take some time to run, because every single dependency gets built from source.
 In Windows, this usually doesn't take that long because pre-built binaries are usually available.
 
 ```bash
diff --git a/zig_engine.R b/zig_engine.R
index d3831fc5..9471c870 100644
--- a/zig_engine.R
+++ b/zig_engine.R
@@ -173,7 +173,7 @@ increase_indentation__ <- function(code_without_main) {
 #' This function is used to get the value of the `auto_main` code block option.
 #' The `auto_main` code block option is used to specify if the Zig code written
 #' in the current code block should (or should not) be encapsulated inside a
-#' `main()` function, before it get's sent to the Zig compiler to be compiled.
+#' `main()` function, before it gets sent to the Zig compiler to be compiled.
 #'
 #' If the user did not configured/setted this
 #' specific option in the current code block that is being analyzed,

From 7c05040d65ff965b0804703054421609f926b01f Mon Sep 17 00:00:00 2001
From: glystik <81292524+glystik@users.noreply.github.com>
Date: Wed, 26 Feb 2025 12:00:05 +0100
Subject: [PATCH 104/151] Removed duplicate, wrong sentence

---
 Chapters/14-threads.qmd | 2 --
 1 file changed, 2 deletions(-)

diff --git a/Chapters/14-threads.qmd b/Chapters/14-threads.qmd
index addac8e4..bf389319 100644
--- a/Chapters/14-threads.qmd
+++ b/Chapters/14-threads.qmd
@@ -275,8 +275,6 @@ which also starts the execution as soon as the thread is created.
 
 ## Returning from a thread
 
-We have learned in the previous section that the execution of the thread starts at the moment
-that the thread gets created. Now, we will learn how to "join" or "detach" a thread in Zig.
 We have learned in the previous section that the execution of the thread starts as soon as
 the thread is created. Now, we will learn how to "join" or "detach" a thread in Zig.
 "Join" and "detach" are operations that control how the thread returns to

From 3048303c2413b563937faeb8b0ed4f843df9de9e Mon Sep 17 00:00:00 2001
From: Glystik <glystik@proton.me>
Date: Wed, 26 Feb 2025 14:29:36 +0100
Subject: [PATCH 105/151] Adjusting "it is" to "it's", "i.e.,", etc

---
 CONTRIBUTING.md                 |  3 +-
 Chapters/01-base64.qmd          | 24 +++++++--------
 Chapters/01-memory.qmd          | 24 +++++++--------
 Chapters/01-zig-weird.qmd       | 52 ++++++++++++++++-----------------
 Chapters/02-debugging.qmd       | 10 +++----
 Chapters/03-structs.qmd         | 36 +++++++++++------------
 Chapters/04-http-server.qmd     | 32 ++++++++++----------
 Chapters/05-pointers.qmd        | 12 ++++----
 Chapters/07-build-system.qmd    | 16 +++++-----
 Chapters/09-data-structures.qmd | 46 ++++++++++++++---------------
 Chapters/09-error-handling.qmd  | 28 +++++++++---------
 Chapters/10-stack-project.qmd   | 12 ++++----
 Chapters/12-file-op.qmd         | 50 +++++++++++++++----------------
 Chapters/13-image-filter.qmd    | 10 +++----
 Chapters/14-threads.qmd         | 32 ++++++++++----------
 Chapters/14-zig-c-interop.qmd   | 10 +++----
 Chapters/15-vectors.qmd         |  6 ++--
 README.md                       |  2 +-
 index.qmd                       |  4 +--
 zig_engine.R                    | 10 +++----
 20 files changed, 208 insertions(+), 211 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 52219fde..304049e4 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -16,7 +16,7 @@ on the official repository of the project:
 - to give a feedback, or, a suggestion of improvement.
 - to point out an error in the book. This error can be:
     - a typo;
-    - it might also be an error in the code examples (i.e. the code example doesn't work when it is supposed to work);
+    - it might also be an error in the code examples (i.e., the code example doesn't work when it is supposed to work);
     - a knowledge error in the book, meaning that, there is a mistake in the technical explanation of a subject.
 
 Now, maybe, you want to do something more than just open an issue. Maybe you want to actually
@@ -35,4 +35,3 @@ If you've never done this before, the process is very easy:
 
 If you send a Pull Request with significant changes, you need to include the phrase "I assign the copyright of this contribution
 to Pedro Duarte Faria" in the description of your Pull Request - I need this so I can publish the book.
-
diff --git a/Chapters/01-base64.qmd b/Chapters/01-base64.qmd
index cddc5b70..7a831bb7 100644
--- a/Chapters/01-base64.qmd
+++ b/Chapters/01-base64.qmd
@@ -54,7 +54,7 @@ take a look at @sec-encode-vs-decode.
 ### The base64 scale {#sec-base64-scale}
 
 The base64 encoding system is based on a scale that goes from 0 to 63 (hence the name).
-Each index in this scale is represented by a character (it is a scale of 64 characters).
+Each index in this scale is represented by a character (it's a scale of 64 characters).
 So, in order to convert some binary data, to the base64 encoding, we need to convert each binary number to the corresponding
 character in this "scale of 64 characters".
 
@@ -95,7 +95,7 @@ We retrieve the character that we need directly from memory.
 
 We can start building a Zig struct to store our base64 decoder/encoder logic.
 We start with the `Base64` struct below. For now, we only have one single data member in this
-struct, i.e. the member `_table`, which represents our lookup table. We also have an `init()` method,
+struct, i.e., the member `_table`, which represents our lookup table. We also have an `init()` method,
 to create a new instance of a `Base64` object, and, a `_char_at()` method, which is a
 "get character at index $x$" type of function.
 
@@ -123,7 +123,7 @@ const Base64 = struct {
 
 
 In other words, the `_char_at()` method is responsible for getting the character in the lookup
-table (i.e. the `_table` struct data member) that corresponds to a particular index in the
+table (i.e., the `_table` struct data member) that corresponds to a particular index in the
 "base64 scale". So, in the example below, we know that the character that corresponds to the
 index 28 in the "base64 scale" is the character "c".
 
@@ -168,10 +168,10 @@ Taking the string "Hi" as an example, we have 2 bytes, or, 16 bits in total. So,
 to complete the window of 24 bits that the base64 algorithm likes to work on. The first thing that
 the algorithm does, is to check how to divide the input bytes into groups of 6 bits.
 
-If the algorithm notices that there is a group of 6 bits that, have some bits in it, but, at the same time, it is not full
-(in other words, $0 < nbits < 6$, being $nbits$ the number of bits), meaning that, it lacks
-some bits to fill the 6-bits requirement, the algorithm simply adds extra zeros in this group
-to fill the space that it needs. That is why in @fig-base64-algo1, in the third group after the 6-bit transformation,
+If the algorithm notices that there is a group of 6 bits that have some bits in it, but, at the same time it's
+not full—lacking some bits to fill the 6-bits requirement ($0 < nbits < 6$, being $nbits$ the number of bits),
+the algorithm simply adds extra zeros in this group to fill the space that it needs.
+That is why in @fig-base64-algo1, in the third group after the 6-bit transformation,
 2 extra zeros were added to fill the gap.
 
 When we have a 6-bit group that is not completely full, like the third group, extra zeros
@@ -201,7 +201,7 @@ two characters in the output sequence (MA==) are `==`.
 
 The algorithm behind a base64 decoder is essentially the inverse process of a base64 encoder.
 A base64 decoder needs to translate base64 messages back into their original meaning,
-i.e. into the original sequence of binary data.
+i.e., into the original sequence of binary data.
 
 A base64 decoder usually works on a window of 4 bytes. Because it wants to convert these 4 bytes
 back into the original sequence of 3 bytes, that was converted into 4 groups of 6 bits by the
@@ -229,7 +229,7 @@ in the base64 sequence. So, every `=` character in a base64 encoded sequence sho
 
 If you don't have any previous experience with base64, you might not understand the differences
 between "encode" and "decode". Essentially, the terms "encode" and "decode" here
-have the exact same meaning as they have in the field of encryption (i.e. they mean the same thing as "encode" and "decode" in hashing
+have the exact same meaning as they have in the field of encryption (i.e., they mean the same thing as "encode" and "decode" in hashing
 algorithms, like the MD5 algorithm).
 
 Thus, "encode" means that we want to encode, or, in other words, we want to translate some message into
@@ -242,7 +242,7 @@ So, in this process we get a sequence of base64 characters as input, and produce
 the binary data that is represented by this sequence of base64 characters.
 
 Any base64 library is normally composed of these two parts: 1) the encoder, which is a function that encodes
-(i.e. it converts) any sequence of binary data into a sequence of base64 characters; 2) the decoder, which is a function
+(i.e., it converts) any sequence of binary data into a sequence of base64 characters; 2) the decoder, which is a function
 that converts a sequence of base64 characters back into the original sequence of binary data.
 
 
@@ -291,7 +291,7 @@ will be produced in the output of the decoder. I mean, this is roughly true, bec
 take the `=` character into account, which is always ignored by the decoder, as we described in @sec-base64-decoder-algo, and,
 in @fig-base64-algo2. But we can ignore this fact for now, just to keep things simple.
 
-The function `_calc_decode_length()` exposed below summarizes this logic that we described. It is very similar
+The function `_calc_decode_length()` exposed below summarizes this logic that we described. It's very similar
 to the function `_calc_encode_length()`. Only the division part is twisted, and also, in the special
 case where we have less than 4 bytes in the input to work on. Also notice that this time, we apply
 a floor operation over the output of the division, by using the `divFloor()`
@@ -669,7 +669,7 @@ base64 scale as the result.
 Notice that, if the input character is `'='`, the function returns the index 64, which is
 "out of range" in the scale. But, as I described in @sec-base64-scale,
 the character `'='` does not belong to the base64 scale itself.
-It is a special and meaningless character in base64.
+It's a special and meaningless character in base64.
 
 Also notice that this `_char_index()` function is a method from our `Base64` struct,
 because of the `self` argument. Again, I have omitted the `Base64` struct definition in this example
diff --git a/Chapters/01-memory.qmd b/Chapters/01-memory.qmd
index f92e5bd0..54d71fe0 100644
--- a/Chapters/01-memory.qmd
+++ b/Chapters/01-memory.qmd
@@ -72,7 +72,7 @@ and only if, the type of this object has a known fixed size.
 In order for a type to have a known fixed size, this type must have data members whose size is fixed.
 If this type includes, for example, a variable sized array in it, then, this type does not have a known
 fixed size. Because this array can have any size at runtime
-(i.e. it can be an array of 2 elements, or 50 elements, or 1 thousand elements, etc.).
+(i.e., it can be an array of 2 elements, or 50 elements, or 1 thousand elements, etc.).
 
 For example, a string object, which internally is an array of constant u8 values (`[]const u8`)
 has a variable size. It can be a string object with 100 or 500 characters in it. If we do not
@@ -118,8 +118,8 @@ argument depends on the value that you assign to this particular argument,
 when you call the function.
 
 For example, the function `input_length()` contains an argument named `input`, which is an array of constant `u8` integers (`[]const u8`).
-It is impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length
-of this particular argument. Because it is an array that do not have a fixed size specified explicitly in the argument type annotation.
+It's impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length
+of this particular argument. Because it's an array that does not have a fixed size specified explicitly in the argument type annotation.
 
 So, we know that this `input` argument will be an array of `u8` integers. But we do not know at compile-time, its value, and neither its size.
 This information is known only at runtime, which is the period of time when you program is executed.
@@ -163,7 +163,7 @@ I will describe each memory space in detail over the next sections. But for now,
 stablish the main difference between these two types of memory.
 
 In essence, the stack memory is normally used to store values whose length is fixed and known
-at compile time. In contrast, the heap memory is a *dynamic* type of memory space, meaning that, it is
+at compile time. In contrast, the heap memory is a *dynamic* type of memory space, meaning that, it's
 used to store values whose length might grow during the execution (runtime) of your program [@jenny2022].
 
 Lengths that grow during runtime are intrinsically associated with "runtime known" type of values.
@@ -200,7 +200,7 @@ usually stored in this same stack space.
 Looking at the example below, the object `result` is a local object declared inside the scope of the `add()`
 function. Because of that, this object is stored inside the stack space reserved for the `add()` function.
 The `r` object (which is declared outside of the `add()` function scope) is also stored in the stack.
-But since it is declared in the "outer" scope, this object is stored in the
+But since it's declared in the "outer" scope, this object is stored in the
 stack space that belongs to this outer scope.
 
 ```{zig}
@@ -277,7 +277,7 @@ Think about that for a second. If all local objects in the stack are destroyed a
 would you even consider returning a pointer to one of these objects? This pointer is at best,
 invalid, or, more likely, "undefined".
 
-Conclusion, it is totally fine to write a function that returns the local object
+In conclusion, it's totally fine to write a function that returns the local object
 itself as result, because then, you return the value of that object as the result.
 But, if this local object is stored in the stack, you should never write a function
 that returns a pointer to this local object. Because the memory address pointed by the pointer
@@ -286,7 +286,7 @@ no longer exists.
 
 So, using again the `add()` function as an example, if you rewrite this function so that it
 returns a pointer to the local object `result`, the `zig` compiler will actually compile
-your program, with no warnings or errors. At first glance, it looks that this is good code
+your program, with no warnings or errors. At first glance, it looks like this is good code
 that works as expected. But this is a lie!
 
 If you try to take a look at the value inside of the `r` object,
@@ -315,7 +315,7 @@ pub fn main() !void {
 ```
 
 This "invalid pointer to stack variable" problem is well known across many programming language communities.
-If you try to do the same thing, for example, in a C or C++ program (i.e. returning an address to
+If you try to do the same thing, for example, in a C or C++ program (i.e., returning an address to
 a local object stored in the stack), you would also get undefined behaviour
 in the program.
 
@@ -337,7 +337,7 @@ from its scope.
 
 One important limitation of the stack, is that, only objects whose length/size is known at compile-time can be
 stored in it. In contrast, the heap is a much more dynamic
-(and flexible) type of memory. It is the perfect type of memory to use
+(and flexible) type of memory. It's the perfect type of memory to use
 for objects whose size/length might grow during the execution of your program.
 
 Virtually any application that behaves as a server is a classic use case of the heap.
@@ -404,7 +404,7 @@ In essence, if you try to make an allocation on the stack, that is so big that e
 a *stack overflow* happens, and your program just crashes as a result of that. In other words, a stack overflow happens when
 you attempt to use more space than is available on the stack.
 
-This type of problem is very similar to a *buffer overflow*, i.e. you are trying to use more space
+This type of problem is very similar to a *buffer overflow*, i.e., you are trying to use more space
 than is available in the "buffer object". However, a stack overflow always causes your program to crash,
 while a buffer overflow does not always cause your program to crash (although it often does).
 
@@ -503,7 +503,7 @@ known fixed length.
 But in reality, there are two very common instances where this "fixed length limitation" of the stack is a deal braker:
 
 1. the objects that you create inside your function might grow in size during the execution of the function.
-1. sometimes, it is impossible to know upfront how many inputs you will receive, or how big this input will be.
+1. sometimes, it's impossible to know upfront how many inputs you will receive, or how big this input will be.
 
 Also, there is another instance where you might want to use an allocator, which is when you want to write a function that returns a pointer
 to a local object. As I described in @sec-stack, you cannot do that if this local object is stored in the
@@ -650,7 +650,7 @@ defer allocator.free(input);
 ### Arena allocator {#sec-arena-allocator}
 
 The `ArenaAllocator()` is an allocator object that takes a child allocator as input. The idea behind the `ArenaAllocator()` in Zig
-is similar to the concept of "arenas" in the programming language Go[^go-arena]. It is an allocator object that allows you
+is similar to the concept of "arenas" in the programming language Go[^go-arena]. It's an allocator object that allows you
 to allocate memory as many times you want, but free all memory only once.
 In other words, if you have, for example, called 5 times the method `alloc()` of an `ArenaAllocator()` object, you can
 free all the memory you allocated over these 5 calls at once, by simply calling the `deinit()` method of the same `ArenaAllocator()` object.
diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index 18afd01f..a05d7747 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -52,9 +52,9 @@ with tons of features, and also, there are lots of different "flavors of C++". T
 are what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.
 Zig is a very simple language, more closely related to other simple languages such as C and Go.
 
-The phrase above is still important for C programmers too. Because, even C being a simple
-language, it is still hard sometimes to read and understand C code. For example, pre-processor macros in
-C are a frequent source of confusion. They really make it sometimes hard to debug
+The phrase above is still important for C programmers too. Because, even if C is a simple
+language, it's still hard sometimes to read and understand C code. For example, pre-processor macros in
+C are a frequent source of confusion. They sometimes really make it hard to debug
 C programs. Because macros are essentially a second language embedded in C that obscures
 your C code. With macros, you are no longer 100% sure about which pieces
 of the code are being sent to the compiler, i.e.
@@ -101,7 +101,7 @@ is a separate Zig module, which is simply a text file that contains some Zig cod
 
 By convention, the `main.zig` module is where your main function lives. Thus,
 if you are building an executable program in Zig, you need to declare a `main()` function,
-which represents the entrypoint of your program, i.e. it is where the execution of your program begins.
+which represents the entrypoint of your program, i.e., where the execution of your program begins.
 
 However, if you are building a library (instead of an executable program), then,
 the normal procedure is to delete this `main.zig` file and start with the `root.zig` module.
@@ -197,7 +197,7 @@ in C or C++, or, to the `import` statement in Python or Javascript code.
 In this example, we are importing the `std` module,
 which gives you access to the Zig Standard Library.
 
-In this `root.zig` file, we can also see how assignments (i.e. creating new objects)
+In this `root.zig` file, we can also see how assignments (i.e., creating new objects)
 are made in Zig. You can create a new object in Zig by using the syntax
 `(const|var) name = value;`. In the example below, we are creating two constant
 objects (`std` and `testing`). In @sec-assignments we talk more about objects in general.
@@ -284,7 +284,7 @@ which, in this example, is the `stdout.print()` expression.
 
 In essence, the `try` keyword executes the expression `stdout.print()`. If this expression
 returns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.
-It is like if this `try` keyword was never there. However, if the expression does return an error, then,
+It's like if this `try` keyword was never there. However, if the expression does return an error, then,
 the `try` keyword will unwrap the error value, then, it returns this error from the function
 and also prints the current stack trace to `stderr`.
 
@@ -389,7 +389,7 @@ operating systems, such as Linux and macOS. In summary, if you have a piece of Z
 includes some global variables whose initialization rely on runtime resources, then,
 you might have some troubles while trying to compile this Zig code on Windows.
 
-An example of that is accessing the `stdout` (i.e. the *standard output* of your system), which is usually
+An example of that is accessing the `stdout` (i.e., the *standard output* of your system), which is usually
 done in Zig by using the expression `std.io.getStdOut()`. If you use this expression to instantiate
 a global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,
 with an "unable to evaluate comptime expression" error message.
@@ -576,7 +576,7 @@ more about the language each day:
 Another great strategy to learn Zig, or honestly, to learn any language you want,
 is to practice it by solving exercises. For example, there is a famous repository
 in the Zig community called [Ziglings](https://ziglings.org)[^ziglings]
-, which contains more than 100 small exercises that you can solve. It is a repository of
+, which contains more than 100 small exercises that you can solve. It's a repository of
 tiny programs written in Zig that are currently broken, and your responsibility is to
 fix these programs, and make them work again.
 
@@ -603,7 +603,7 @@ the exercises, you can look at these two repositories:
 
 
 
-## Creating new objects in Zig (i.e. identifiers) {#sec-assignments}
+## Creating new objects in Zig (i.e., identifiers) {#sec-assignments}
 
 Let's talk more about objects in Zig. Readers that have past experience
 with other programming languages might know this concept through
@@ -653,7 +653,7 @@ in your source code.
 So, using the same code example exposed above, if I change the declaration of the
 `age` object to use the `var` keyword, then, the program gets compiled successfully.
 Because now, the `zig` compiler detects that we are changing the value of an
-object that allows this behaviour, because it is an "variable object".
+object that allows this behaviour, because it's a "variable object".
 
 ```{zig}
 #| build_type: "run"
@@ -676,7 +676,7 @@ which is the `undefined` keyword.
 
 It's important to emphasize that, you should avoid using `undefined` as much as possible.
 Because when you use this keyword, you leave your object uninitialized, and, as a consequence,
-if for some reason, your code use this object while it is uninitialized, then, you will definitely
+if for some reason, your code uses this object while it's uninitialized, then, you will definitely
 have undefined behaviour and major bugs in your program.
 
 In the example below, I'm declaring the `age` object again. But this time,
@@ -704,7 +704,7 @@ to calculate the value of another object, or, you can call a method that belongs
 particular object.
 
 It doesn't matter in which way you use it. As long as you use it.
-If you try to break this rule, i.e. if your try to declare a object, but not use it,
+If you try to break this rule, i.e., if your try to declare a object, but not use it,
 the `zig` compiler will not compile your Zig source code, and it will issue a error
 message warning that you have unused objects in your code.
 
@@ -746,7 +746,7 @@ _ = age;
 ```
 
 Now, remember, everytime you assign a particular object to the underscore, this object
-is essentially destroyed. It is discarded by the compiler. This means that you can no longer
+is essentially destroyed. It's discarded by the compiler. This means that you can no longer
 use this object further in your code. It doesn't exist anymore.
 
 So if you try to use the constant `age` in the example below, after we discarded it, you
@@ -827,7 +827,7 @@ But here is a quick list:
 ## Arrays {#sec-arrays}
 
 You create arrays in Zig by using a syntax that resembles the C syntax.
-First, you specify the size of the array (i.e. the number of elements that will be stored in the array)
+First, you specify the size of the array (i.e., the number of elements that will be stored in the array)
 you want to create inside a pair of brackets.
 
 Then, you specify the data type of the elements that will be stored inside this array.
@@ -910,8 +910,8 @@ Therefore, the syntax `start..end` actually means `start..end - 1` in practice.
 
 You can for example, create a slice that goes from the first to the
 last elements of the array, by using `ar[0..ar.len]` syntax
-In other words, it is a slice that
-access all elements in the array.
+In other words, it's a slice that
+accesses all elements in the array.
 
 ```{zig}
 #| auto_main: true
@@ -1021,7 +1021,7 @@ In contrast, a runtime known thing is when the exact value of a thing is calcula
 Therefore, we don't know the value of this thing at compile-time, only at runtime.
 
 We have learned in @sec-select-array-elem that slices are created by using a *range selector*,
-which represents a range of indexes. When this "range of indexes" (i.e. the start and the end of this range)
+which represents a range of indexes. When this "range of indexes" (i.e., the start and the end of this range)
 is known at compile-time, the slice object that gets created is actually, under the hood, just
 a single-item pointer to an array.
 
@@ -1030,7 +1030,7 @@ in @sec-pointer. For now, just understand that, when the range of indexes is kno
 the slice that gets created is just a pointer to an array, accompanied by a length value that
 tells the size of the slice.
 
-If you have a slice object like this, i.e. a slice that has a compile-time known range,
+If you have a slice object like this, i.e., a slice that has a compile-time known range,
 you can use common pointer operations over this slice object. For example, you can
 dereference the pointer of this slice, by using the `.*` method, like you would
 do on a normal pointer object.
@@ -1104,7 +1104,7 @@ are also examples of blocks.
 This means that, every if statement, or for loop,
 etc., that you create in your source code have its own separate scope.
 That is why you can't access the objects that you defined inside
-of your for loop (or if statement) in an outer scope, i.e. a scope outside of the for loop.
+of your for loop (or if statement) in an outer scope, i.e., a scope outside of the for loop.
 Because you are trying to access an object that belongs to a scope that is different
 than your current scope.
 
@@ -1147,7 +1147,7 @@ In summary, there are two types of string values that you care about in Zig, whi
 - String literal values.
 - String objects.
 
-A string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string).
+A string literal value is just a pointer to a null-terminated array of bytes (i.e., similar to a C string).
 But in Zig, a string literal value also embeds the length of the string into the data type of the value itself.
 Therefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type
 indicates the size of the string.
@@ -1158,7 +1158,7 @@ a string object have a data type of `[]u8` or `[]const u8`, depending if the str
 marked as constant with `const`, or as variable with `var`.
 
 Because a string object is essentially a slice, it means that a string object always contains two things:
-a pointer to an array of bytes (i.e. `u8` values) that represents the string value; and also, a length value,
+a pointer to an array of bytes (i.e., `u8` values) that represents the string value; and also, a length value,
 which specifies the size of the slice, or, how many elements there is in the slice.
 It's worth to emphasize that the array of bytes in a string object is not null-terminated, like in a
 string literal value.
@@ -1182,7 +1182,7 @@ So if your string literal is not UTF-8 encoded, then, you will likely have probl
 Let's take for example the word "Hello". In UTF-8, this sequence of characters (H, e, l, l, o)
 is represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this
 sequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,
-and ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then,
+and ask Zig to print this sequence of bytes as a sequence of characters (i.e., a string), then,
 the text "Hello" will be printed into the terminal:
 
 ```{zig}
@@ -1229,10 +1229,10 @@ and this array is also null-terminated.
 
 But one key difference between a Zig string literal and a C string, is that Zig also stores the length of
 the string inside the object itself. In the case of a string literal value, this length is stored in the
-data type of the value (i.e. the `n` variable in `[n:0]u8`). While, in a string object, the length is stored
+data type of the value (i.e., the `n` variable in `[n:0]u8`). While, in a string object, the length is stored
 in the `len` attribute of the slice that represents the string object. This small detail makes your code safer,
-because it is much easier for the Zig compiler to check if you are trying to access an element that is
-"out of bounds", i.e. if your trying to access memory that does not belong to you.
+because it's much easier for the Zig compiler to check if you are trying to access an element that is
+"out of bounds", i.e., if your trying to access memory that does not belong to you.
 
 To achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.
 So getting this kind of safety is not automatic and much harder to do in C. For example, if you want
@@ -1297,7 +1297,7 @@ Now, if we create an pointer to the `simple_array` object, then, we get a consta
 which is very similar to the type of the string literal value. This demonstrates that a string literal value
 in Zig is already a pointer to a null-terminated array of bytes.
 
-Furthermore, if we take a look at the type of the `string_obj` object, you will see that it is a
+Furthermore, if we take a look at the type of the `string_obj` object, you will see that it's a
 slice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence
 the `const u8` portion of the type).
 
diff --git a/Chapters/02-debugging.qmd b/Chapters/02-debugging.qmd
index 23751eb7..15c337bc 100644
--- a/Chapters/02-debugging.qmd
+++ b/Chapters/02-debugging.qmd
@@ -37,7 +37,7 @@ is behaving.
 
 Many programmers often resort to the print functions in Zig, such as the `stdout.print()`,
 or, the `std.debug.print()`, to get a better understanding of their programs.
-This is a known and old strategy that is very simple and effective, and it is better known within
+This is a known and old strategy that is very simple and effective, and it's better known within
 the programming community as *print debugging*.
 In Zig, you can print information to the `stdout` or `stderr` streams of your system.
 
@@ -78,7 +78,7 @@ Here is a quick list of the most used format specifiers:
 - `s`: for printing strings.
 - `p`: for printing memory addresses.
 - `x`: for printing hexadecimal values.
-- `any`: use any compatible format specifier (i.e. it automatically selects a format specifier for you).
+- `any`: use any compatible format specifier (i.e., it automatically selects a format specifier for you).
 
 The code example below gives you an example of use of this `print()` method
 with the `d` format specifier.
@@ -98,7 +98,7 @@ pub fn main() !void {
 }
 ```
 
-It is important to emphasize that, the `stdout.print()` method, as you would expect,
+It's important to emphasize that, the `stdout.print()` method, as you would expect,
 prints your template string into the `stdout` stream of your system.
 However, you can also print your template string into the `stderr` stream
 if your prefer. All you need to do, is to replace the `stdout.print()`
@@ -188,7 +188,7 @@ pub fn main() !void {
 }
 ```
 
-There is nothing wrong with this program. But it is
+There is nothing wrong with this program. But it's
 a good start for us. First, we need to compile
 this program with the `zig build-exe` command.
 For this example, suppose that I have compiled the above
@@ -207,7 +207,7 @@ lldb add_program
 From now on, LLDB is started, and you can know that I'm
 executing LLDB commands by looking at the prefix `(lldb)`.
 If something is prefixed with `(lldb)`, then you know
-that it is a LLDB command.
+that it's a LLDB command.
 
 The first thing I will do, is to set a breakpoint at
 the `main()` function, by executing `b main`.
diff --git a/Chapters/03-structs.qmd b/Chapters/03-structs.qmd
index 1f603615..999845d4 100644
--- a/Chapters/03-structs.qmd
+++ b/Chapters/03-structs.qmd
@@ -176,7 +176,7 @@ comes from the Zig Standard Library. More precisely, from the
 [`debug.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/debug.zig)[^debug-mod].
 There are multiple lines in this function, but I omitted them to focus solely on the
 switch statement found in this function. Notice that this switch statement has four
-possible cases (i.e. four explicit branches). Also, notice that we used an `else` branch
+possible cases (i.e., four explicit branches). Also, notice that we used an `else` branch
 in this case.
 
 An `else` branch in a switch statement works as the "default branch".
@@ -240,7 +240,7 @@ t.zig:9:13: 0x1033c58 in main (switch2)
 Furthermore, you can also use ranges of values in switch statements.
 That is, you can create a branch in your switch statement that is used
 whenever the input value is within the specified range. These "range expressions"
-are created with the operator `...`. It is important
+are created with the operator `...`. It's important
 to emphasize that the ranges created by this operator are
 inclusive on both ends.
 
@@ -555,7 +555,7 @@ In Zig, you can explicitly stop the execution of a loop, or, jump to the next it
 the keywords `break` and `continue`, respectively. The `while` loop presented in the next code example is,
 at first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to `true`.
 But what makes this `while` loop stop when the `i` object reaches the count
-10? It is the `break` keyword!
+10? It's the `break` keyword!
 
 Inside the while loop, we have an if statement that is constantly checking if the `i` variable
 is equal to 10. Since we are incrementing the value of `i` at each iteration of the
@@ -565,7 +565,7 @@ will execute the `break` expression, and, as a result, the execution of the whil
 Notice the use of the `expect()` function from the Zig Standard Library after the while loop.
 This `expect()` function is an "assert" type of function.
 This function checks if the logical test provided is equal to true. If so, the function do nothing.
-Otherwise (i.e. the logical test is equal to false), the function raises an assertion error.
+Otherwise (i.e., the logical test is equal to false), the function raises an assertion error.
 
 ```{zig}
 #| auto_main: true
@@ -624,7 +624,7 @@ cannot assign values to them inside the body's function.
 
 This is the reason why, the code example below does not compile successfully. If you try to compile
 this code example, you will get a compile error message about "trying to change the value of a
-immutable (i.e. constant) object".
+immutable (i.e., constant) object".
 
 ```{zig}
 #| eval: false
@@ -677,7 +677,7 @@ You can change the value that the pointer points to, by dereferencing it.
 
 Therefore, if we take our previous `add2()` example, we can change the value of the
 function argument `x` inside the function's body by marking the `x` argument as a
-"pointer to a `u32` value" (i.e. `*u32` data type), instead of a `u32` value.
+"pointer to a `u32` value" (i.e., `*u32` data type), instead of a `u32` value.
 By making it a pointer, we can finally alter the value of this function argument directly inside
 the body of the `add2()` function. You can see that the code example below compiles successfully.
 
@@ -883,7 +883,7 @@ usually declare this method as a function that has a `self` argument.
 This `self` argument is the reference to the object itself from which the method
 is being called from.
 
-It is not mandatory to use this `self` argument. But why would you not use this `self` argument?
+It's not mandatory to use this `self` argument. But why would you not use this `self` argument?
 There is no reason to not use it. Because the only way to get access to the data stored in the
 data members of your struct is to access them through this `self` argument.
 If you don't need to use the data in the data members of your struct inside your method, you very likely don't need
@@ -970,7 +970,7 @@ But why? Why am I talking about this here? It's because the `self` argument
 in the methods are affected depending on whether the
 methods present in a struct change or don't change the state of the object itself.
 More specifically, when you have a method in a struct that changes the state
-of the object (i.e. changes the value of a data member), the `self` argument
+of the object (i.e., changes the value of a data member), the `self` argument
 in this method must be annotated in a different manner.
 
 As I described in @sec-self-arg, the `self` argument in methods of
@@ -1070,7 +1070,7 @@ So remember, every function argument is immutable in Zig, and `self`
 is no exception to this rule.
 
 In this example, we marked the `v3` object as a variable object.
-But this does not matter. Because it is not about the input object, it is about
+But this does not matter. Because it's not about the input object, it's about
 the function argument.
 
 The problem begins when we try to alter the value of `self` directly, which is a function argument,
@@ -1105,7 +1105,7 @@ as input.
 
 In general, type inference in Zig is done by using the dot character (`.`).
 Everytime you see a dot character written before a struct literal, or before an enum value, or something like that,
-you know that this dot character is playing a special part in this place. More specifically, it is
+you know that this dot character is playing a special part in this place. More specifically, it's
 telling the `zig` compiler something along the lines of: "Hey! Can you infer the type of this
 value for me? Please!". In other words, this dot character is playing a similar role as the `auto` keyword in C++.
 
@@ -1137,8 +1137,8 @@ switch statements that begin with a dot character, such as `.release` and `.acqu
 
 Because these weird values contain a dot character before them, we are asking the `zig`
 compiler to infer the types of these values inside the switch statement. Then, the `zig`
-compiler is looking into the current context where these values are being used, and it is
-trying to infer the types of these values.
+compiler is looking into the current context where these values are being used, and trying
+to infer the types of these values.
 
 Since they are being used inside a switch statement, the `zig` compiler looks into the type
 of the input object given to the switch statement, which is the `order` object in this case.
@@ -1187,7 +1187,7 @@ is commonly used on switch statements in Zig.
 
 In this section, I want to discuss type casting (or, type conversion) with you.
 We use type casting when we have an object of type "x", and we want to convert
-it into an object of type "y", i.e. we want to change the data type of the object.
+it into an object of type "y", i.e., we want to change the data type of the object.
 
 Most languages have a formal way to perform type casting. In Rust for example, we normally
 use the keyword `as`, and in C, we normally use the type casting syntax, e.g. `(int) x`.
@@ -1195,7 +1195,7 @@ In Zig, we use the `@as()` built-in function to cast an object of type "x", into
 an object of type "y".
 
 This `@as()` function is the preferred way to perform type conversion (or type casting)
-in Zig. Because it is explicit, and, it also performs the casting only if it
+in Zig. Because it's explicit, and, it also performs the casting only if it
 is unambiguous and safe. To use this function, you just provide the target data type
 in the first argument, and, the object that you want cast as the second argument.
 
@@ -1212,8 +1212,8 @@ test {
 ```
 
 This is the general way to perform type casting in Zig. But remember, `@as()` works only when casting
-is unambiguous and safe, and there are situations where these assumptions do not hold. For example,
-when casting an integer value into a float value, or vice-versa, it is not clear to the compiler
+is unambiguous and safe—there are situations where these assumptions do not hold. For example,
+when casting an integer value into a float value, or vice-versa, it's not clear to the compiler
 how to perform this conversion safely.
 
 Therefore, we need to use specialized "casting functions" in such situations.
@@ -1244,7 +1244,7 @@ Another built-in function that is very useful when performing type casting opera
 In essence, we use the `@as()` built-in function when we want to explicit convert (or cast) a Zig value/object
 from a type "x" to a type "y", etc. However, pointers (we are going to discuss pointers
 in more depth in @sec-pointer) are a special type of object in Zig,
-i.e. they are treated differently from "normal objects".
+i.e., they are treated differently from "normal objects".
 
 Everytime a pointer is involved in some "type casting operation" in Zig, the `@ptrCast()` function is used.
 This function works similarly to `@floatFromInt()`.
@@ -1273,7 +1273,7 @@ test {
 ## Modules
 
 We already talked about what modules are, and also, how to import other modules into
-your current module via *import statements*. Every Zig module (i.e. a `.zig` file) that you write in your project
+your current module via *import statements*. Every Zig module (i.e., a `.zig` file) that you write in your project
 is internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the
 Zig Standard Library into our current module.
 
diff --git a/Chapters/04-http-server.qmd b/Chapters/04-http-server.qmd
index e4804dd8..06e115e6 100644
--- a/Chapters/04-http-server.qmd
+++ b/Chapters/04-http-server.qmd
@@ -38,7 +38,7 @@ through this connection.
 
 But the messages that are transmitted inside this connection are in a
 specific format. They are HTTP messages
-(i.e. messages that use the HTTP Protocol specification).
+(i.e., messages that use the HTTP Protocol specification).
 The HTTP Protocol is the backbone of the modern web.
 The world wide web as we know it today, would not exist without the
 HTTP Protocol.
@@ -91,7 +91,7 @@ that connected to the server is asking this server to do something for him.
 
 There are different "types of request" that a client can send to a HTTP Server.
 But the most basic type of request, is when a client ask to the
-HTTP Server to serve (i.e. to send) some specific web page (which is a HTML file) to him.
+HTTP Server to serve (i.e., to send) some specific web page (which is a HTML file) to him.
 When you type `google.com` in your web browser, you are essentially sending a HTTP Request to Google's
 HTTP servers. This request is asking these servers to send the Google webpage to you.
 
@@ -137,7 +137,7 @@ You are creating a channel where people can send messages through.
 When you create a socket object, this object is not binded to any particular
 address. This means that with this object you have a representation of a channel of communication
 in your hands. But this channel is not currently available, or, it is not currently accessible,
-because it do not have a known address where you can find it.
+because it does not have a known address where you can find it.
 
 That is what the "bind" operation do. It binds a name (or more specifically, an address) to
 this socket object, or, this channel of communication, so that it becomes available,
@@ -174,7 +174,7 @@ which is a sequence of 4 numbers separated by dot characters (`.`) that identifi
 While the second component is a port number, which identifies the specific
 door, or, the specific port to use in the host machine.
 
-The sequence of 4 numbers (i.e. the host) identifies the machine (i.e. the computer itself) where
+The sequence of 4 numbers (i.e., the host) identifies the machine (i.e., the computer itself) where
 this socket will live in. Every computer normally have multiple "doors" available inside of him, because
 this allows the computer to receive and work with multiple connections at the same time.
 He simply use a single door for each connection. So the port number, is
@@ -273,7 +273,7 @@ you will notice that the programs keeps running indefinitely,
 without a clear end.
 
 This happens, because the program is waiting for something to happen.
-It is waiting for someone to try to connect to the address (`http://127.0.0.1:3490`) where
+It's waiting for someone to try to connect to the address (`http://127.0.0.1:3490`) where
 the server is running and listening for incoming connections. This is what
 the `listen()` method do, it makes the socket to be active waiting for someone
 to connect.
@@ -329,7 +329,7 @@ terminates as soon as the connection is accepted.
 
 ### Reading the message from the client {#sec-read-http-message}
 
-Now that we have a connection established, i.e. the connection
+Now that we have a connection established, i.e., the connection
 object that we created through the `accept()` function, we can now
 use this connection object to read any messages that the client
 send to our server. But we can also use it to send messages back
@@ -566,7 +566,7 @@ and third, we have the version of the HTTP protocol that is being used in this H
 In the snippet below, you can find an example of this first line in a HTTP Request.
 First, we have the HTTP method of this request (`GET`). Many programmers
 refer to the URI component (`/users/list`) as the "API endpoint" to which the HTTP Request
-is being sent to. In the context of this specific request, since it is a GET request,
+is being sent to. In the context of this specific request, since it's a GET request,
 you could also say that the URI component is the path to the resource we want to access,
 or, the path to the document (or the file) that we want to retrieve from the server.
 
@@ -609,9 +609,9 @@ of this `Accept` header.
 
 ### The body
 
-The body comes after the list of HTTP headers, and it is an optional section of the HTTP Request, meaning that, not
-all HTTP Request will come with a body in it. For example, every HTTP Request that uses the
-GET method usually do not come with a body.
+The body comes after the list of HTTP headers, and it's an optional section of the HTTP Request, meaning that, not
+all HTTP Requests will come with a body in them. For example, every HTTP Request that uses the
+GET method usually does not come with a body.
 
 Because a GET request is used to request data, instead of sending it to the server.
 So, the body section is more related to the POST method, which is a method that involves
@@ -635,7 +635,7 @@ is identified by one these words:
 - and some other methods.
 
 Each HTTP method is used for a specific type of task. The POST method for example is normally
-used to post some data into the destination. In other words, it is used
+used to post some data into the destination. In other words, it's used
 to send some data to the HTTP server, so that it can be processed and stored by the server.
 
 As another example, the GET method is normally used to get content from the server.
@@ -679,7 +679,7 @@ But in order to build these functions, I will use a functionality from the Zig S
 `StaticStringMap()`. This function allows us to create a simple map from strings to enum values.
 In other words, we can use this map structure to map a string to the respective enum value.
 To some extent, this specific structure from the standard library works almost like a "hashtable" structure,
-and it is optimized for small sets of words, or, small sets of keys, which is our case here.
+and it's optimized for small sets of words, or, small sets of keys, which is our case here.
 We are going to talk more about hashtables in Zig in @sec-maps-hashtables.
 
 To use this "static string map" structure, you have to import it from the `std.static_string_map` module
@@ -687,9 +687,9 @@ of the Zig Standard Library. Just to make things shorter and easier to type, I a
 function through a different and shorter name (`Map`).
 
 With `Map()` imported, we can just apply this function over the enum structure
-that we are going to use in the resulting map. In our case here, it is the `Method` enum structure
+that we are going to use in the resulting map. In our case here, it's the `Method` enum structure
 that we declared at the last code example. Then, I call the `initComptime()` method with the
-map, i.e. the list of key-value pairs that we are going to use.
+map, i.e., the list of key-value pairs that we are going to use.
 
 You can see in the example below that I wrote this map using multiple anonymous struct literals.
 Inside the first (or "top-level") struct literal, we have a list (or a sequence) of struct literals.
@@ -762,7 +762,7 @@ actually parsing the HTTP Request.
 
 The first thing we can do, is to write a struct to represent the HTTP Request.
 Take the `Request` struct below as an example. It contains the three
-essential information from the "top-level" header (i.e. the first line)
+essential information from the "top-level" header (i.e., the first line)
 in the HTTP Request.
 
 ```{zig}
@@ -956,7 +956,7 @@ pub fn send_404(conn: Connection) !void {
 Notice that both functions receives the connection object as input, and
 use the `write()` method to write the HTTP Response message directly
 into this communication channel. As result, the party in the other
-side of the connection (i.e. the client), will receive such message.
+side of the connection (i.e., the client), will receive such message.
 
 Most real-world HTTP Servers will have a single function (or a single struct) to effectively handle
 the response. It gets the HTTP Request already parsed as input, and then, it tries to build
diff --git a/Chapters/05-pointers.qmd b/Chapters/05-pointers.qmd
index bf8eba08..f75cbe85 100644
--- a/Chapters/05-pointers.qmd
+++ b/Chapters/05-pointers.qmd
@@ -23,11 +23,11 @@ Pointers in Zig are similar to pointers in C. But they come with some extra adva
 
 A pointer is an object that contains a memory address. This memory address is the address where
 a particular value is stored in memory. It can be any value. Most of the times,
-it is a value that comes from another object (or variable) present in our code.
+it's a value that comes from another object (or variable) present in our code.
 
 In the example below, I'm creating two objects (`number` and `pointer`).
 The `pointer` object contains the memory address where the value of the `number` object
-(the number 5) is stored. So, that is a pointer in a nutshell. It is a memory
+(the number 5) is stored. So, that is a pointer in a nutshell. It's a memory
 address that points to a particular existing value in the memory. You could
 also say, that, the `pointer` object points to the memory address where the `number` object is
 stored.
@@ -103,7 +103,7 @@ try stdout.print("{d}\n", .{number});
 
 Therefore, as I mentioned earlier, people use pointers as an alternative way to access a particular value.
 And they use it especially when they do not want to "move" these values around. There are situations where,
-you want to access a particular value in a different scope (i.e. a different location) of your code,
+you want to access a particular value in a different scope (i.e., a different location) of your code,
 but you do not want to "move" this value to this new scope (or location) that you are in.
 
 This matters especially if this value is big in size. Because if it is, then,
@@ -178,7 +178,7 @@ We can have a constant pointer that points to a constant value.
 But we can also have a variable pointer that points to a constant value. And vice-versa.
 
 Until this point, the `pointer` object was always constant,
-but what this means for us? What is the consequence of the
+but what does this mean for us? What is the consequence of the
 `pointer` object being constant? The consequence is that
 we cannot change the pointer object, because it is constant. We can use the
 pointer object in multiple ways, but we cannot change the
@@ -377,7 +377,7 @@ the `*` identifies it as a pointer object.
 
 In the example below, we are creating a variable object named `num`, and an
 optional pointer object named `ptr`. Notice that the data type of the object
-`ptr` indicates that it is either a null value, or a pointer to an `i32` value.
+`ptr` indicates that it's either a null value, or a pointer to an `i32` value.
 Also, notice that the pointer object (`ptr`) can be marked as optional, even if
 the object `num` is not optional.
 
@@ -418,7 +418,7 @@ _ = ptr;
 ### Null handling in optionals {#sec-null-handling}
 
 When you have an optional object in your Zig code, you have to explicitly handle
-the possibility of this object being null. It is like error-handling with `try` and `catch`.
+the possibility of this object being null. It's like error-handling with `try` and `catch`.
 In Zig you also have to handle null values like if they were a type of error.
 
 We can do that, by using either:
diff --git a/Chapters/07-build-system.qmd b/Chapters/07-build-system.qmd
index 349fc81b..6c64c0cd 100644
--- a/Chapters/07-build-system.qmd
+++ b/Chapters/07-build-system.qmd
@@ -96,7 +96,7 @@ We are going to talk more about these target objects in @sec-targets.
 ## The `build()` function {#sec-build-fun}
 
 A build script in Zig always contains a public (and top-level) `build()` function declared.
-It is like the `main()` function on the main Zig module of your project, that we discussed in @sec-main-file.
+It's like the `main()` function in the main Zig module of your project, that we discussed in @sec-main-file.
 But instead of creating the entrypoint to your code, this `build()` function is the entrypoint to the build process.
 
 This `build()` function should accept a pointer to a `Build` object as input, and it should use this "build object" to perform
@@ -194,13 +194,13 @@ currently running the `zig` compiler.
 
 
 At last, the `root_source_file` option specifies the root Zig module of your project.
-That is the Zig module that contains the entrypoint to your application (i.e. the `main()` function), or, the main API of your library.
+That is the Zig module that contains the entrypoint to your application (i.e., the `main()` function), or, the main API of your library.
 This also means that, all the Zig modules that compose your project are automatically discovered
 from the import statements you have inside this "root source file".
 The `zig` compiler can detect when a Zig module depends on the other through the import statements,
 and, as a result, it can discover the entire map of Zig modules used in your project.
 
-This is handy, and it is different from what happens in other build systems.
+This is handy, and it's different from what happens in other build systems.
 In CMake for example, you have to explicitly list the paths to all source files that you want to
 include in your build process. This is probably a symptom of the "lack of conditional
 compilation" in the C and C++ compilers. Since they lack this feature, you have
@@ -261,7 +261,7 @@ In Zig, we have four build modes (which are listed below). Each one of these bui
 different advantages and characteristics. As we described in @sec-compile-debug-mode, the `zig` compiler
 uses the `Debug` build mode by default, when you don't explicitly choose a build mode.
 
-- `Debug`, mode that produces and includes debugging information in the output of the build process (i.e. the binary file defined by the target object);
+- `Debug`, mode that produces and includes debugging information in the output of the build process (i.e., the binary file defined by the target object);
 - `ReleaseSmall`, mode that tries to produce a binary file that is small in size;
 - `ReleaseFast`, mode that tries to optimize your code, in order to produce a binary file that is as fast as possible;
 - `ReleaseSafe`, mode that tries to make your code as safe as possible, by including safeguards when possible.
@@ -475,7 +475,7 @@ A test target object essentially selects all `test` blocks in all Zig modules
 across your project, and builds only the source code present inside
 these `test` blocks in your project. As a result, this target object
 creates an executable file that contains only the source code present
-in all of these `test` blocks (i.e. the unit tests) in your project.
+in all of these `test` blocks (i.e., the unit tests) in your project.
 
 Perfect! Now that we have declared this test target object, an executable file
 named `unit_tests` is built by the `zig` compiler when we trigger the build
@@ -674,7 +674,7 @@ through the `cc` command of the `zig` compiler.
 
 As an example, let's use the famous [FreeType library](https://freetype.org/)[^freetype].
 FreeType is one of the most widely used pieces of software in the world.
-It is a C library designed to produce high-quality fonts. But it is also
+It's a C library designed to produce high-quality fonts. But it's also
 heavily used in the industry to natively render text and fonts
 in the screen of your computer.
 
@@ -777,7 +777,7 @@ Now that we declared both the files that we want to include and the C compiler f
 we can add them to the target object that describes the FreeType library, by using the
 `addCSourceFile()` and `addCSourceFiles()` methods.
 
-Both of these functions are methods from a `Compile` object (i.e. a target object).
+Both of these functions are methods from a `Compile` object (i.e., a target object).
 The `addCSourceFile()` method is capable of adding a single C file to the target object,
 while the `addCSourceFiles()` method is used to add multiple C files in a single command.
 You might prefer to use `addCSourceFile()` when you need to use different compiler flags
@@ -871,7 +871,7 @@ lib.addLibraryPath(lib_path);
 ### Adding include paths {#sec-include-paths}
 
 The preprocessor search path is a popular concept from the
-C community, but it is also known by many C programmers as "include paths", because
+C community, but it's also known by many C programmers as "include paths", because
 the paths in this "search path" relate to the `#include` statements found in the C files.
 
 Include paths are similar to library paths. They are a set of pre-defined places in your computer where
diff --git a/Chapters/09-data-structures.qmd b/Chapters/09-data-structures.qmd
index 4b8f99cd..add3878e 100644
--- a/Chapters/09-data-structures.qmd
+++ b/Chapters/09-data-structures.qmd
@@ -60,8 +60,8 @@ However, only a portion of these $n$ elements are being used most of the time. T
 of $n$ is the *length* of the array. So every time you append a new value
 to the array, you are incrementing its *length* by one.
 
-This means that a dynamic array usually works with an extra margin, or, an extra space
-which is currently empty, but it is waiting and ready to be used. This "extra space"
+This means that a dynamic array usually works with an extra margin, or an extra space
+that is currently empty, but waiting and ready to be used. This "extra space"
 is essentially the difference between *capacity* and *length*. *Capacity* represents
 the total number of elements that the array can hold without the need to re-allocate
 or re-expand the array, while the *length* represents how much of this capacity
@@ -82,12 +82,12 @@ than what we currently have.
 A dynamic array works by expanding the underlying array, whenever the *length* becomes equal
 to the *capacity* of the array. It basically allocates a new contiguous block of memory that is bigger
 than the previous one, then, it copies all values that are currently being stored to this new
-location (i.e. this new block of memory), then, it frees the previous block of
+location (i.e., this new block of memory), then, it frees the previous block of
 memory. At the end of this process, the new underlying array have a bigger *capacity*, and, therefore,
 the *length* becomes, once again, smaller than the *capacity* of the array.
 
-This is the cycle of an dynamic array. Notice that, throughout this cycle, the *capacity* is always
-either equal to or higher than the *length* of the array. If youh have an `ArrayList` object (let's suppose
+This is the cycle of a dynamic array. Notice that, throughout this cycle, the *capacity* is always
+either equal to or higher than the *length* of the array. If you have an `ArrayList` object (let's suppose
 you named it `buffer`), you can check the current capacity of your array by accessing the `capacity`
 attribute of your `ArrayList` object, while the current *length* of it is available at the `items.len`
 attribute.
@@ -181,7 +181,7 @@ the last value stored in the array.
 
 Also, this method returns as result the value that got deleted. That is, you can
 use this method to both get the last value in the array, and also, remove
-it from the array. It is a "get and remove value" type of method.
+it from the array. It's a "get and remove value" type of method.
 
 ```{zig}
 #| eval: false
@@ -322,7 +322,7 @@ and you access each bucket by using an index.
 
 When you provide a key to a hashtable, it passes this key to the
 hash function. This hash function uses some sort of hashing algorithm to transform
-this key into an index. This index is actually an array index. It is a position
+this key into an index. This index is actually an array index. It's a position
 in the underlying array of the hashtable.
 This is how a key identifies a specific position (or location) inside the hashtable
 structure.
@@ -341,18 +341,18 @@ The @fig-hashtable presents this process visually.
 The operation described in the previous paragraph is normally called an *insertion* operation.
 Because you are inserting new values into the hashtable.
 But there are other types of operations in hashtables such as *delete* and *lookup*.
-Delete is self describing, it is when you delete (or remove) a value from the hashtable.
+Delete is self describing, it's when you delete (or remove) a value from the hashtable.
 While lookup corresponds to when you look at a value that is stored in
 the hashtable, by using the key that identifies the location where this value is stored.
 
 Sometimes, instead of storing the values directly, the underlying array of the hashtable might be an array of pointers,
-i.e. the buckets of the array stores pointers that points to the value,
+i.e., the buckets of the array stores pointers that points to the value,
 or also, may be an array of linked lists.
 These cases are common on hashtables that allows duplicate keys, or, in other words,
 on hashtables that effectively handle "collisions" that may arise from the hash function.
 
 Duplicate keys, or this "collision" thing that I'm talking about, is when you have two different keys
-that points to the same location (i.e. to the same index)
+that points to the same location (i.e., to the same index)
 in the underlying array of the hashtable. This might happen depending on the characteristics of the hash function
 that is being used in the hashtable. Some implementations of the hashtable will actively deal with collisions,
 meaning that, they will handle this case in some way. For example, the hashtable
@@ -360,7 +360,7 @@ might transform all buckets into linked lists. Because with a linked list you ca
 multiple values into a single bucket.
 
 There are different techniques to handle collisions in hashtables, which I will not describe
-in this book, because it is not our main scope here. But you can find a good description of
+in this book, because it's not our main scope here. But you can find a good description of
 some of the most common techniques at the Wikipedia page of hashtables [@wikipedia_hashtables].
 
 
@@ -378,7 +378,7 @@ the behaviour of the hashtable itself, because you can
 provide a hash function implementation to be used by the hashtable
 through this context object.
 
-But let's not worry about this context object now, because it is meant to be used
+But let's not worry about this context object now, because it's meant to be used
 by "experts in the field of hashtables". Since we are most likely not
 experts in this field, we are going to take the easy way to create
 a hashtable. Which is by using the `AutoHashMap()` function.
@@ -459,7 +459,7 @@ that the method successfully deleted the value.
 But this delete operation might not be always successful. For example, you might provide the wrong
 key to this method. I mean, maybe you provide
 (either intentionally or unintentionally) a key that points to an empty bucket,
-i.e. a bucket that still doesn't have a value in it.
+i.e., a bucket that still doesn't have a value in it.
 In this case, the `remove()` method would return a `false` value.
 
 
@@ -472,7 +472,7 @@ You can do that in Zig by using an iterator object that can iterate
 through the elements of your hashtable object.
 
 This iterator object works like any other iterator object that you would
-find in languages such as C++ and Rust. It is basically a pointer object
+find in languages such as C++ and Rust. It's basically a pointer object
 that points to some value in the container, and has a `next()` method
 that you can use to navigate (or iterate) through the values in the
 container.
@@ -559,7 +559,7 @@ The `ArrayHashMap` struct creates a hashtable that is faster to iterate over.
 That is why this specific type of hashtable might be valuable to you.
 Some other properties of a `ArrayHashMap` hashtable are:
 
-- the order of insertion is preserved, i.e. the order of the values that you find while iterating through this hashtable is actually the order in which these values were inserted in the hashtable.
+- the order of insertion is preserved, i.e., the order of the values that you find while iterating through this hashtable is actually the order in which these values were inserted in the hashtable.
 - the key-value pairs are stored sequentially, one after another.
 
 
@@ -578,7 +578,7 @@ a value from the hashtable by using the `get()` method. But the `remove()` metho
 in this specific type of hashtable.
 
 In order to delete values from the hashtable, you would use the same methods that you find in
-an `ArrayList` object, i.e. a dynamic array. I presented these methods in @sec-dynamic-array-remove,
+an `ArrayList` object, i.e., a dynamic array. I presented these methods in @sec-dynamic-array-remove,
 which are the `swapRemove()` and `orderedRemove()` methods. These methods have the same meaning here, or,
 the same effect that they have in an `ArrayList` object.
 
@@ -610,7 +610,7 @@ What this means is that you cannot use a slice value to represent a key in
 these types of hashtable.
 
 The most obvious consequence of this, is that you cannot use strings as keys
-in these hashtables. But it is extremely common to use strings as keys
+in these hashtables. But it's extremely common to use strings as keys
 in hashtables.
 
 Take this very simple Javascript code snippet as an example. We are creating
@@ -751,7 +751,7 @@ we are creating a singly linked list of `u32` values.
 So each node in this linked list will store a `u32` value.
 
 Both the `SinglyLinkedList()` and `DoublyLinkedList()` functions returns a type,
-i.e. a struct definition, as output. Therefore, the object `Lu32` is actually
+i.e., a struct definition, as output. Therefore, the object `Lu32` is actually
 a struct definition. It defines the type "singly linked list of `u32` values".
 
 Now that we have the definition of the struct, we need to instantiate a `Lu32` object.
@@ -818,15 +818,15 @@ summary of them in the bullet points below:
 - `remove()` to remove a specific node from the linked list.
 - if singly linked list, `len()` to count how many nodes there is in the linked list.
 - if doubly linked list, checkout the `len` attribute to see how many nodes there is in the linked list.
-- if singly linked list, `popFirst()` to remove the first node (i.e. the "head") from the linked list.
+- if singly linked list, `popFirst()` to remove the first node (i.e., the "head") from the linked list.
 - if doubly linked list, `pop()` and `popFirst()` to remove the last and first nodes from the linked list, respectively.
-- if doubly linked list, `append()` to add a new node to end of the linked list (i.e. inverse of `prepend()`).
+- if doubly linked list, `append()` to add a new node to end of the linked list (i.e., inverse of `prepend()`).
 
 
 
 ## Multi array structure
 
-Zig introduces a new data structure called `MultiArrayList()`. It is a different version of the dynamic array
+Zig introduces a new data structure called `MultiArrayList()`. It's a different version of the dynamic array
 that we have introduced in @sec-dynamic-array. The difference between this structure and the `ArrayList()`
 that we know from @sec-dynamic-array, is that `MultiArrayList()` creates a separate dynamic array
 for each field of the struct that you provide as input.
@@ -906,13 +906,13 @@ the internal array of the `PersonArray` object that contains the values of the `
 data member from the `Person` values that were added to the multi array struct.
 
 In this example we are calling the `items()` method directly from the `PersonArray`
-object. However, it is recommended on most situations to call this `items()` method
+object. However, in most situations it's recommened to call this `items()` method
 from a "slice object", which you can create from the `slice()` method.
 The reason for this is that calling `items()` multiple times have better performance
 if you use a slice object.
 
 Therefore, if you are planning to access only one of the
-internal arrays from your "multi array struct", it is fine to call `items()` directly
+internal arrays from your "multi array struct", it's fine to call `items()` directly
 from the multi array object. But if you need to access many of the internal arrays
 from your "multi array struct", then, you will likely need to call `items()` more
 than once, and, in such circumstance, is better to call `items()` through a slice object.
diff --git a/Chapters/09-error-handling.qmd b/Chapters/09-error-handling.qmd
index ea05ebc7..301b4c29 100644
--- a/Chapters/09-error-handling.qmd
+++ b/Chapters/09-error-handling.qmd
@@ -92,8 +92,8 @@ fn print_name() !void {
 
 In the example above, we are using the exclamation mark to tell the `zig` compiler
 that this function might return some error. But which error exactly is returned from
-this function? For now, we are not specifying a specific error value. We only
-known for now that some error value (whatever it is) might be returned.
+this function? For now, we are not specifying a specific error value. For now,
+we only know that some error value (whatever it is) might be returned.
 
 But in fact, you can (if you want to) specify clearly which exact error values
 might be returned from this function. There are lot of examples of
@@ -110,9 +110,9 @@ pub fn fill(conn: *Connection) ReadError!void {
 
 This idea of specifying the exact error values that you expect to be returned
 from the function is interesting. Because they automatically become some sort of documentation
-of your function, and also, it allows the `zig` compiler to perform some extra checks over
-your code. Because it can check if there is any other type of error value
-that is being generated inside your function, and, that it is not being accounted
+of your function, and also, this allows the `zig` compiler to perform some extra checks over
+your code. Because the compiler can check if there is any other type of error value
+that is being generated inside your function, and, that it's not being accounted
 for in this return type annotation.
 
 Anyway, you can list the types of errors that can be returned from the function
@@ -131,9 +131,9 @@ When you have such a function, you can list
 all of these different types of errors that can be returned from this function,
 through a structure in Zig that we call of an *error set*.
 
-An error set is a special case of an union type. It is an union that contains error values in it.
-Not all programming languages have a notion of an "union object".
-But in summary, an union is just a set of data types.
+An error set is a special case of a union type. It's a union that contains error values in it.
+Not all programming languages have a notion of a "union object".
+But in summary, a union is just a set of data types.
 Unions are used to allow an object to have multiple data types.
 For example, a union of `x`, `y` and `z`, means that
 an object can be either of type `x`, or type `y` or type `z`.
@@ -173,7 +173,7 @@ of the error set in the return type annotation, instead of using the error set d
 We can see that in the `ReadError` error set that we showed earlier in the `fill()` function,
 which is defined in the `http.Client` module.
 So yes, I presented the `ReadError` as if it was just a standard and single error value, but in fact,
-it is an error set defined in the `http.Client` module, and therefore, it actually represents
+it's an error set defined in the `http.Client` module, and therefore, it actually represents
 a set of different error values that might happen inside the `fill()` function.
 
 
@@ -349,7 +349,7 @@ by the expression.
 The Zig official language reference, provides a great example of this "default value"
 strategy with `catch`. This example is reproduced below. Notice that we are trying to parse
 some unsigned integer from a string object named `str`. In other words, this function
-is trying to transform an object of type `[]const u8` (i.e. an array of characters, a string, etc.)
+is trying to transform an object of type `[]const u8` (i.e., an array of characters, a string, etc.)
 into an object of type `u64`.
 
 But this parsing process done by the function `parseU64()` may fail, resulting in a runtime error.
@@ -383,7 +383,7 @@ But if this expression returns a valid value instead, then, this value is unwrap
 into the `number` object.
 
 This means that, if the `parseU64()` expression returns a valid value, this value becomes available
-inside the scope of this "if branch" (i.e. the "true branch") through the object that we listed inside the pair
+inside the scope of this "if branch" (i.e., the "true branch") through the object that we listed inside the pair
 of pipe character (`|`), which is the object `number`.
 
 If an error occurs, we can use an "else branch" (or the "false branch") of the if statement
@@ -520,7 +520,7 @@ that our program will free the allocated memory for the `user` object,
 even if an error occurs inside the `create_user()` function.
 
 If you allocate and free some memory for an object inside the same scope, then,
-just use `defer` and be happy, i.e. `errdefer` have no use for you in such situation.
+just use `defer` and be happy, i.e., `errdefer` have no use for you in such situation.
 But if you allocate some memory in a scope A, but you only free this memory
 later, in a scope B for example, then, `errdefer` becomes useful to avoid leaking memory
 in sketchy situations.
@@ -529,7 +529,7 @@ in sketchy situations.
 
 ## Union type in Zig {#sec-unions}
 
-An union type defines a set of types that an object can be. It is like a list of
+A union type defines a set of types that an object can be. It's like a list of
 options. Each option is a type that an object can assume. Therefore, unions in Zig
 have the same meaning, or, the same role as unions in C. They are used for the same purpose.
 You could also say that unions in Zig produces a similar effect to
@@ -581,7 +581,7 @@ in this instantiation.
 You could also interpret this as: only one data member of an union type can be activated at a time, the other data
 members remain deactivated and unaccessible. For example, if you create a `LakeTarget` object that uses
 the `azure` data member, you can no longer use or access the data members `google` or `amazon`.
-It is like if these other data members didn't exist at all in the `LakeTarget` type.
+It's like if these other data members didn't exist at all in the `LakeTarget` type.
 
 You can see this logic in the example below. Notice that, we first instantiate the union
 object using the `azure` data member. As a result, this `target` object contains only
diff --git a/Chapters/10-stack-project.qmd b/Chapters/10-stack-project.qmd
index 99c0e241..8dc43567 100644
--- a/Chapters/10-stack-project.qmd
+++ b/Chapters/10-stack-project.qmd
@@ -44,7 +44,7 @@ a lot depending on whether this value is known at compile-time, or just at runti
 The `comptime` keyword is strongly related to these two spaces in time (compile-time and runtime).
 Let's quickly recap the differences. Compile-time is the period of time when your
 Zig source code is being compiled by the `zig` compiler, while the runtime is
-the period of time when your Zig program is being executed, i.e. when we execute
+the period of time when your Zig program is being executed, i.e., when we execute
 the binary files that were generated by the `zig` compiler.
 
 There are three ways in which you can apply the `comptime` keyword, which are:
@@ -455,7 +455,7 @@ Notice that we use the allocator object to allocate a new array that is twice as
 than the current array (`self.capacity * 2`).
 
 After that, we use a different built-in function named `@memcpy()`. This built-in function
-is equivalent to the `memcpy()` function from the C Standard Library[^cmemcpy]. It is used to
+is equivalent to the `memcpy()` function from the C Standard Library[^cmemcpy]. It's used to
 copy the values from one block of memory to another block of memory. In other words,
 you can use this function to copy the values from one array into another array.
 
@@ -574,8 +574,8 @@ of the stack into a generic array.
 In other words, this underlying array needs to be a "chameleon". It needs to adapt,
 and transform it into an array of any data type that we want. For example, if we need to create
 a stack that will store `u8` values, then this underlying array needs to be
-a `u8` array (i.e. `[]u8`). But if we need to store `User` values instead, then,
-this array needs to be a `User` array (i.e. `[]User`). Etc.
+a `u8` array (i.e., `[]u8`). But if we need to store `User` values instead, then,
+this array needs to be a `User` array (i.e., `[]User`). Etc.
 
 We do that by using a generic function. Because a generic function can receive a data type
 as input, and we can pass this data type to the struct definition of our `Stack` object.
@@ -586,7 +586,7 @@ the struct definition that describes a `Stack` object that can store `User` valu
 
 Look at the code example below. I have omitted some parts of the `Stack` struct definition
 for brevity. However, if a specific part of our `Stack` struct is not exposed here
-in this example, then it is because this part did not change from the previous example.
+in this example, then it's because this part did not change from the previous example.
 It remains the same.
 
 
@@ -629,7 +629,7 @@ We can just provide a data type to this function, and it will create a definitio
 `Stack` object that can store values of the data type that we have provided. In the example below, we are creating
 the definition of a
 `Stack` object that can store `u8` values in it. This definition is stored at the `Stacku8` object.
-This `Stacku8` object becomes our new struct, it is the struct that we are going to use
+This `Stacku8` object becomes our new struct, that we are going to use
 to create our `Stack` object.
 
 
diff --git a/Chapters/12-file-op.qmd b/Chapters/12-file-op.qmd
index cdf64326..f38845ff 100644
--- a/Chapters/12-file-op.qmd
+++ b/Chapters/12-file-op.qmd
@@ -47,8 +47,8 @@ In essence, these input/output functions from high-level languages are just abst
 over the *standard output* and *standard input* channels of your operating system.
 
 This means that we receive an input, or send some output, through the operating system.
-It is the OS that makes the bridge between the user and your program. Your program
-does not have a direct access to the user. It is the OS that intermediates every
+It's the OS that makes the bridge between the user and your program. Your program
+does not have a direct access to the user. It's the OS that intermediates every
 message exchanged between your program and the user.
 
 The *standard output* and *standard input* channels of your OS are commonly known as the
@@ -97,12 +97,12 @@ Both of these objects are normally created from a file descriptor object. More s
 methods of this file descriptor object. If you are not familiar with this type of object, go to the next section.
 
 Every `GenericWriter` object have methods like `print()`, which allows you to write/send a formatted string
-(i.e. this formatted string is like a `f` string in Python, or, similar to the `printf()` C function)
+(i.e., this formatted string is like a `f` string in Python, or, similar to the `printf()` C function)
 into the "something" (file, socket, stream, etc.) that you are using. It also have a `writeAll()` method, which allows you to
 write a string, or, an array of bytes into the "something".
 
 Likewise, every `GenericReader` object have methods like `readAll()`, which allows you to read the
-data from the "something" (file, socket, stream, etc.) until it fills a particular array (i.e. a "buffer") object.
+data from the "something" (file, socket, stream, etc.) until it fills a particular array (i.e., a "buffer") object.
 In other words, if you provide an array object of 300 `u8` values to `readAll()`, then, this method attempts to read 300 bytes
 of data from the "something", and it stores them into the array object that you have provided.
 
@@ -110,7 +110,7 @@ We also have other methods, like the `readAtLeast()` method, which allows you to
 many bytes exactly you want to read from the "something". In more details, if you give the
 number $n$ as input to this method, then, it will attempt to read at least $n$ bytes of data
 from the "something". The "something" might have less than $n$ bytes of data available for you
-to read, so, it is not guaranteed that you will get precisely $n$ bytes as result.
+to read, so, it's not guaranteed that you will get precisely $n$ bytes as result.
 
 Another useful method is `readUntilDelimiterOrEof()`. In this method, you specify a "delimiter character".
 The idea is that this function will attempt to read as many bytes of data as possible from the "something",
@@ -126,7 +126,7 @@ This is just a quick description of the methods present in these types of object
 to read the official docs, both for
 [`GenericWriter`](https://ziglang.org/documentation/master/std/#std.io.GenericWriter)[^gen-write] and
 [`GenericReader`](https://ziglang.org/documentation/master/std/#std.io.GenericReader)[^gen-read].
-I also think it is a good idea to read the source code of the modules in the Zig Standard Library
+I also think it's a good idea to read the source code of the modules in the Zig Standard Library
 that defines the methods present in these objects, which are the
 [`Reader.zig`](https://github.com/ziglang/zig/blob/master/lib/std/io/Reader.zig)[^mod-read]
 and [`Writer.zig`]()[^mod-write].
@@ -223,7 +223,7 @@ use them here, from the file descriptor object of `stdout`, and vice-versa.
 
 ### The *standard input*
 
-You can access the *standard input* (i.e. `stdin`) in Zig by using the `getStdIn()` function from the `std.io` module.
+You can access the *standard input* (i.e., `stdin`) in Zig by using the `getStdIn()` function from the `std.io` module.
 Like its brother (`getStdOut()`), this function also returns a file descriptor object that describes the `stdin` channel
 of your OS.
 
@@ -278,22 +278,22 @@ the purpose of this channel.
 ## Buffered IO
 
 As we described in @sec-io-basics, input/output (IO) operations are made directly by the operating system.
-It is the OS that manages the IO resource that you want to use for your IO operations.
-The consequence of this fact is that IO operations are heavily based on system calls (i.e. calling the operating system directly).
+It's the OS that manages the IO resource that you want to use for your IO operations.
+The consequence of this fact is that IO operations are heavily based on system calls (i.e., calling the operating system directly).
 
 Just to be clear, there is nothing particularly wrong with system calls. We use them all the time on
 any serious codebase written in any low-level programming language. However, system calls are
 always orders of magnitude slower than many different types of operations.
 
 So is perfectly fine to use a system call once in a while. But when these system calls are used often,
-you can clearly notice most of the time the loss of performance in your application. So, the good rule of thumbs
-is to use a system call only when it is needed, and also, only in infrequent situations, to reduce
+you can clearly notice most of the time the loss of performance in your application. So, the good rule of thumb
+is to use a system call only when it's needed, and also, only in infrequent situations, to reduce
 the number of system calls performed to a minimum.
 
 
 ### Understanding how buffered IO works
 
-Buffered IO is a strategy to achieve better performance. It is used to reduce the number of system calls made by IO operations, and, as
+Buffered IO is a strategy to achieve better performance. It's used to reduce the number of system calls made by IO operations, and, as
 consequence, achieve a much higher performance. In @fig-unbuffered-io and @fig-buffered-io you can find two different diagrams
 which presents the difference between read operations performed in an unbuffered IO environment versus a buffered IO environment.
 
@@ -306,7 +306,7 @@ More precisely, in the diagram exposed in @fig-unbuffered-io we get one system c
 On the other hand, in @fig-buffered-io we have only one system call at the very beginning.
 
 When we use a buffered IO system, at the first read operation we perform, instead of sending one single byte directly
-to our program, the OS first sends a chunk of bytes from the file to a buffer object (i.e. an array).
+to our program, the OS first sends a chunk of bytes from the file to a buffer object (i.e., an array).
 This chunk of bytes are cached/stored inside this buffer object.
 
 Therefore, from now on, for every new read operation that you perform, instead of making a new system call to ask
@@ -323,7 +323,7 @@ this next byte already cached and ready to go.
 
 
 
-This is the basic logic behind buffered IO systems. The size of the buffer object depends on multiple factors. But it is usually
+This is the basic logic behind buffered IO systems. The size of the buffer object depends on multiple factors. But it's usually
 equal to the size of a full page of memory (4096 bytes). If we follow this logic, then, the OS reads the first 4096 bytes
 of the file and caches it into the buffer object. As long as your program does not consume all of these 4096 bytes from the buffer,
 you will not create new system calls.
@@ -339,7 +339,7 @@ IO operations made through a `FILE` pointer in C are buffered
 by default, so, at least in C, you don't need to worry about this subject. But in contrast, IO operations in both Rust and Zig are not
 buffered depending on which functions from the standard libraries that you are using.
 
-For example, in Rust, buffered IO is implemented through the `BufReader` and `BufWriter` structs, while in Zig, it is implemented
+For example, in Rust, buffered IO is implemented through the `BufReader` and `BufWriter` structs, while in Zig, it's implemented
 through the `BufferedReader` and `BufferedWriter` structs.
 So any IO operation that you perform through the `GenericWriter` and `GenericReader` objects
 that I presented in @sec-writer-reader are not buffered, which means that these objects
@@ -410,7 +410,7 @@ and have the exact same methods. So, although these two types of objects perform
 they have the same interface, so you, the programmer, can interchangeably use them
 without the need to change anything in your source code.
 So a buffered IO reader or a buffered IO writer objects have the same methods than its generic and unbuffered brothers,
-i.e. the generic reader and generic writer objects that I presented in @sec-writer-reader.
+i.e., the generic reader and generic writer objects that I presented in @sec-writer-reader.
 
 ::: {.callout-tip}
 In general, you should always use a buffered IO reader or a buffered IO writer object to perform
@@ -429,15 +429,15 @@ computer are considered an IO resource, as we described in @sec-file-descriptor.
 ### The concept of current working directory (CWD)
 
 The working directory is the folder on your computer where you are currently rooted at.
-In other words, it is the folder that your program is currently looking at.
+In other words, it's the folder that your program is currently looking at.
 Therefore, whenever you are executing a program, this program is always working with
-a specific folder on your computer. It is always in this folder that the program will initially
-look for the files you require, and it is also in this folder that the program
+a specific folder on your computer. It's always in this folder that the program will initially
+look for the files you require, and it's also in this folder that the program
 will initially save all the files you ask it to save.
 
 The working directory is determined by the folder from which you invoke your program
 in the terminal. In other words, if you are in the terminal of your OS, and you
-execute a binary file (i.e. a program) from this terminal, the folder to which your terminal
+execute a binary file (i.e., a program) from this terminal, the folder to which your terminal
 is pointing at is the current working directory of your program that is being executed.
 
 In @fig-cwd we have an example of me executing a program from the terminal. We are executing
@@ -461,12 +461,12 @@ current working directory, you must provide a path to that file or folder.
 A path is essentially a location. It points to a location in your filesystem. We use
 paths to describe the location of files and folders in our computer.
 One important aspect about paths is that they are always written inside strings,
-i.e. they are always provided as text values.
+i.e., they are always provided as text values.
 
 There are two types of paths that you can provide to any program in any OS: a relative path, or an absolute path.
 Absolute paths are paths that start at the root of your filesystem, and go all the way to the file name or the specific folder
 that you are referring to. This type of path is called absolute, because it points to an unique and absolute location on your computer.
-That is, there is no other existing location on your computer that corresponds to this path. It is an unique identifier.
+That is, there is no other existing location on your computer that corresponds to this path. It's an unique identifier.
 
 In Windows, an absolute path is a path that starts with a hard disk identifier (e.g. `C:/Users/pedro`).
 On the other hand, absolute paths in Linux and macOS, are paths that start with a forward slash character (e.g. `/usr/local/bin`).
@@ -545,7 +545,7 @@ and it will create the file by following this path, which is relative to the CWD
 
 This function might return an error, so, you should use `try`, `catch`, or any of the other methods presented
 in @sec-error-handling to handle the possible error. But if everything goes well,
-this `createFile()` method returns a file descriptor object (i.e. a `File` object) as result,
+this `createFile()` method returns a file descriptor object (i.e., a `File` object) as result,
 through which you can add content to the file with the IO operations that I presented before.
 
 Take this code example below. In this example, we are creating a new text file
@@ -585,7 +585,7 @@ in erase all the contents of the existing file.
 
 If you don't want this to happen, meaning, that you don't want to overwrite
 the contents of the existing file, but you want to write data to this file anyway
-(i.e. you want to append data to the file), you should use the `openFile()`
+(i.e., you want to append data to the file), you should use the `openFile()`
 method from the `Dir` object.
 
 Another important aspect about `createFile()` is that this method creates a file
@@ -702,7 +702,7 @@ try cwd.deleteFile("foo.txt");
 ### Copying files
 
 To copy existing files, we use the `copyFile()` method. The first argument in this method
-is the path to the file that you want to copy. The second argument is a `Dir` object, i.e. a directory handler,
+is the path to the file that you want to copy. The second argument is a `Dir` object, i.e., a directory handler,
 more specifically, a `Dir` object that points to the folder in your computer where you want to
 copy the file to. The third argument is the new path of the file, or, in other words, the new location
 of the file. The fourth argument is the options (or flags) to be used in the copy operation.
diff --git a/Chapters/13-image-filter.qmd b/Chapters/13-image-filter.qmd
index 513b83c3..55ebd3cc 100644
--- a/Chapters/13-image-filter.qmd
+++ b/Chapters/13-image-filter.qmd
@@ -137,7 +137,7 @@ Also notice in @fig-img-display that, because a raster image is essentially a 2D
 the image is organized into rows and columns of pixels. The columns are defined by the horizontal x axis,
 while the rows are defined by the vertical y axis.
 
-Each pixel (i.e. the gray rectangles) exposed in @fig-img-display contains a number inside of it.
+Each pixel (i.e., the gray rectangles) exposed in @fig-img-display contains a number inside of it.
 These numbers are the indexes of the pixels. You can notice that the first pixels are in the top and left
 corner, and also, that the indexes of these pixels "grow to the sides", or, in other words, they grow in the direction of the horizontal x axis.
 Most raster images are organized as rows of pixels. Thus, when these digital images are
@@ -167,7 +167,7 @@ Therefore, we need to create an array of 36 `u8` values to store this small imag
 
 The reason why unsigned 8-bit integer (`u8`) values are used to represent the amounts of each color,
 instead of any other integer type, is because they take the minimum amount of space as possible, or,
-the minimum amount of bits as possible. Which helps to reduces the binary size of the image, i.e. the 2D matrix.
+the minimum amount of bits as possible. Which helps to reduces the binary size of the image, i.e., the 2D matrix.
 Also, they convey a good amount of precision and detail about the colors, even though they can represent
 a relatively small range (from 0 to 255) of "color amounts".
 
@@ -227,11 +227,11 @@ are developing here.
 
 There are some C libraries available that we can use to read and parse PNG files.
 The most famous and used of all is `libpng`, which is the "official library" for reading and writing
-PNG files. Although this library is available on most operating system, it is well known
+PNG files. Although this library is available on most operating system, it's well known
 for being complex and hard to use.
 
 That is why, I'm going to use a more modern alternative here in this project, which is the `libspng` library.
-I choose to use this C library here, because it is much, much simpler to use than `libpng`,
+I choose to use this C library here, because it's much, much simpler to use than `libpng`,
 and it also offers very good performance for all operations. You can checkout the
 [official website of the library](https://libspng.org/)[^libspng]
 to know more about it. You will also find there some documentation that might help you to understand and
@@ -506,7 +506,7 @@ $${#eq-grayscale}
 This @eq-grayscale is the formula to calculate the linear luminance of a pixel. It's worth noting that this formula
 works only for images whose pixels are using the sRGB color space, which is the standard color space
 for the web. Thus, ideally, all images on the web should use this color space. Luckily,
-this is our case here, i.e. the `pedro_pascal.png` image is using this sRGB color space, and, as consequence,
+this is our case here, i.e., the `pedro_pascal.png` image is using this sRGB color space, and, as consequence,
 we can use the @eq-grayscale. You can read more about this formula at the Wikipedia page for grayscale [@wiki_grayscale].
 
 The `apply_image_filter()` function exposed below summarises the necessary steps to
diff --git a/Chapters/14-threads.qmd b/Chapters/14-threads.qmd
index addac8e4..d6876769 100644
--- a/Chapters/14-threads.qmd
+++ b/Chapters/14-threads.qmd
@@ -54,13 +54,13 @@ with the other tab where Google Docs is running.
 
 Without threads, the other alternative would be to run each tab as a completely separate
 process in your computer. But that would be a bad choice because just a few tabs would already consume
-too much power and resources from your computer. In other words, it is very expensive to create a completely new process,
+too much power and resources from your computer. In other words, it's very expensive to create a completely new process,
 compared to creating a new thread of execution. Also, the chances of you experiencing lag and overhead
 while using the browser would be significant. Threads are faster to create, and they also consume
 much, much less resources from the computer, especially because they share some resources
 with the main process.
 
-Therefore, it is the use of threads in modern web browsers that allow you to hear the podcast
+Therefore, it's the use of threads in modern web browsers that allow you to hear the podcast
 at the same time while you are writing something on Google Docs.
 Without threads, a web browser would probably be limited to just one single tab.
 
@@ -120,7 +120,7 @@ so the waiter spends almost no time worrying about the order, and just
 move on and tries to get the next order from the clients.
 
 Inside the new thread created, the order gets cooked by a chef, and when the
-food is ready, it is delivered to the client's table.
+food is ready, it's delivered to the client's table.
 
 
 ```{zig}
@@ -180,7 +180,7 @@ same memory space on the heap and global data section.
 
 In more details, each thread that you create have a separate stack frame reserved just for that thread,
 which essentially means that each local object that you create inside this thread, is local to that
-thread, i.e. the other threads cannot see this local object. Unless this object that you have created
+thread, i.e., the other threads cannot see this local object. Unless this object that you have created
 is an object that lives on the heap. In other words, if the memory associated with this object
 is on the heap, then, the other threads can potentially access this object.
 
@@ -320,7 +320,7 @@ pub fn main() !void {
 
 Because we have joined this new thread inside the `main()` scope, we have a
 guarantee that this new thread will finish before the end of the execution of `main()`.
-Because it is guaranteed that `main()` will wait for the thread to finish its tasks.
+Because it's guaranteed that `main()` will wait for the thread to finish its tasks.
 
 In the example above, there are no more expressions after the `join()` call. We just have the end
 of the `main()`'s scope, and, therefore, the execution of our program just ends after the thread finishes its tasks,
@@ -336,7 +336,7 @@ The idea behind this example is that the last `join()` call is executed
 only after the first thread finishes its task (i.e., the first `join()` call),
 and the two-second delay. If you compile and run this
 example, you will notice that most messages are quickly printed to `stdout`,
-i.e. they appear almost instantly on your screen.
+i.e., they appear almost instantly on your screen.
 However, the last message ("Joining thread 2") takes around 2 seconds to appear
 on the screen.
 
@@ -532,8 +532,8 @@ try pool.spawn(print_id, .{&id1});
 try pool.spawn(print_id, .{&id2});
 ```
 
-This limitation should probably not exist, and, in fact, it is already on the radar of the
-Zig team to fix this issue, and it is being tracked on an [open issue](https://github.com/ziglang/zig/issues/18810)[^issue].
+This limitation should probably not exist, and, in fact, it's already on the radar of the
+Zig team to fix this issue, and it's being tracked in an [open issue](https://github.com/ziglang/zig/issues/18810)[^issue].
 So, if you do need to provide a function that might return an error as the task
 to be performed by the threads in the thread pool, then, you are either limited to:
 
@@ -555,7 +555,7 @@ and, therefore, major bugs and undefined behaviour that are usually difficult to
 The main idea behind a mutex is to help us to control the execution of a particular section of the code, and to
 prevent two or more threads from executing this particular section of the code at the same time.
 Many programmers like to compare a mutex to a bathroom door (which typically has a lock).
-When a thread locks its own mutex object, it is like if the bathroom door was locked.
+When a thread locks its own mutex object, it's like if the bathroom door was locked.
 Therefore, other people (in this case, other threads) who want to use the same bathroom at the same time
 must be patient and simply wait for the current occupant (or thread) to unlock the door and get out of the bathroom.
 
@@ -624,7 +624,7 @@ suffer from a data race problem. Therefore, programmers sometimes use an atomic
 to protect themselves from data race problems in their code.
 
 When you have an operation that is compiled into just one single assembly instruction, this operation might be atomic,
-because it is just one assembly instruction. But this is not guaranteed. This is usually true for old CPU architectures
+because it's just one assembly instruction. But this is not guaranteed. This is usually true for old CPU architectures
 (such as `x86`). But nowadays, most assembly instructions in modern CPU architectures are broken down into multiple micro-tasks,
 which inherently makes the operation non-atomic, even if it consists of a single assembly instruction.
 
@@ -633,7 +633,7 @@ In this module, you will find a public and generic function called `Value()`. Wi
 a value that contains some native atomic operations, most notably, a `load()` and a `fetchAdd()` operation.
 If you have experience with multithreading in C++, you probably have recognized this pattern. So yes, this generic
 "atomic object" in Zig is essentially identical to the template struct `std::atomic` from the C++ Standard Library.
-It's important to emphasize that only primitive data types (i.e. the types presented in @sec-primitive-data-types)
+It's important to emphasize that only primitive data types (i.e., the types presented in @sec-primitive-data-types)
 are supported by these atomic operations in Zig.
 
 
@@ -819,7 +819,7 @@ pub fn main() !void {
 
 ## Read/Write locks
 
-Mutexes are normally used when it is not always safe for two or more threads running the same
+Mutexes are normally used when it's not always safe for two or more threads running the same
 piece of code at the same time. In contrast, read/write locks are normally used in situations
 where you have a mixture of scenarios, i.e., there are some pieces of the codebase that are safe
 to run in parallel, and other pieces that are not safe.
@@ -840,7 +840,7 @@ You could also say that there are types of operations that are susceptible to ra
 and there are other types of operations that are not.
 
 A read/write lock is a type of lock that acknowledges the existence of this specific scenario, and you can
-use this type of lock to control which parts of the codebase are safe to run in parallel and which parts are not. 
+use this type of lock to control which parts of the codebase are safe to run in parallel and which parts are not.
 
 
 
@@ -876,9 +876,9 @@ the execution of this thread is instantly blocked, i.e., paused. This thread wil
 read lock, and its execution will be unblocked (or unpaused) only after this thread successfully acquires the read lock.
 
 If you think deeply about this dynamic between read locks versus write locks, you might notice that a read lock is basically a safety mechanism.
-More specifically, it is a way for us to
+More specifically, it's a way for us to
 allow a particular thread to run together with the other threads only when it's safe to. In other words, if there is currently
-a thread with a write lock running, then it is very likely not safe for the thread that is trying to acquire the read lock to run now.
+a thread with a write lock running, then it's very likely not safe for the thread that is trying to acquire the read lock to run now.
 As a consequence, the read lock protects this thread from running into dangerous waters, and patiently waits for the
 "write lock" thread to finishes its tasks before it continues.
 
@@ -1063,7 +1063,7 @@ control over the thread, and its resources are never freed
 
 When we think about the `pthreads` C library, there is a possible way to asynchronously kill or cancel
 a thread, which is by sending a `SIGTERM` signal to the thread through the `pthread_kill()` function.
-But canceling a thread like this is bad. It is dangerously bad. As a consequence, the Zig implementation
+But canceling a thread like this is bad. It's dangerously bad. As a consequence, the Zig implementation
 of threads does not have a similar function, or, a similar way to asynchronously cancel or kill
 a thread.
 
diff --git a/Chapters/14-zig-c-interop.qmd b/Chapters/14-zig-c-interop.qmd
index dd184bbc..d38ad83e 100644
--- a/Chapters/14-zig-c-interop.qmd
+++ b/Chapters/14-zig-c-interop.qmd
@@ -241,9 +241,9 @@ converted into C strings as well, especially because the `zig` compiler does not
 a specific Zig data type into a string literal at first glance, unless you store this
 string literal into a Zig object, and explicitly annotate the data type of this object.
 
-Thus, with string literal values, the `zig` compiler have more freedom to infer which is the appropriate data type
+Thus, with string literal values, the `zig` compiler has more freedom to infer which is the appropriate data type
 to be used in each situation. You could say that the string literal value "inherits its data type" depending on the context that
-it is used. Most of the times, this data type is going to be the type that we commonly associate with Zig strings (`[]const u8`).
+it's used in. Most of the times, this data type is going to be the type that we commonly associate with Zig strings (`[]const u8`).
 But it might be a different type depending on the situation. When the `zig` compiler detects that you are providing
 a string literal value as input to some C function, the compiler automatically interprets this string
 literal as a C string value.
@@ -406,14 +406,14 @@ while using the `fopen()` C function.
 ```
 
 This strategy works because this pointer to the underlying array found in the `ptr` property,
-is semantically identical to a C pointer to an array of bytes, i.e. a C object of type `*unsigned char`.
+is semantically identical to a C pointer to an array of bytes, i.e., a C object of type `*unsigned char`.
 This is why this option also solves the problem of converting the Zig string into a C string.
 
 Another option is to explicitly convert the Zig string object into a C pointer by using the
 built-in function `@ptrCast()`. With this function we can convert
 an object of type `[]const u8` into an object of type `[*c]const u8`.
 As I described at the previous section, the `[*c]` portion of the type
-means that it is a C pointer. This strategy is not-recommended. But it is
+means that it's a C pointer. This strategy is not-recommended. But it's
 useful to demonstrate the use of `@ptrCast()`.
 
 You may recall of `@as()` and `@ptrCast()` from @sec-type-cast. Just as a recap,
@@ -465,7 +465,7 @@ a new object with type `User`. These steps are reproduced in the code example be
 Notice that I have used the keyword `undefined` in this example. This allows me to
 create the `new_user` object without the need to provide an initial value to the object.
 As consequence, the underlying memory associated with this `new_user` object is uninitialized,
-i.e. the memory is currently populated with "garbage" values.
+i.e., the memory is currently populated with "garbage" values.
 Thus, this expression have the exact same effect of the expression `User new_user;` in C,
 which means "declare a new object named `new_user` of type `User`".
 
diff --git a/Chapters/15-vectors.qmd b/Chapters/15-vectors.qmd
index f191ec39..99fb35e0 100644
--- a/Chapters/15-vectors.qmd
+++ b/Chapters/15-vectors.qmd
@@ -20,7 +20,7 @@ knitr::opts_chunk$set(
 # Introducing Vectors and SIMD {#sec-vectors-simd}
 
 In this chapter, I want to discuss vectors in Zig, which are
-related to SIMD operations (i.e. they have no relationship with the `std::vector` class
+related to SIMD operations (i.e., they have no relationship with the `std::vector` class
 from C++).
 
 ## What is SIMD?
@@ -32,7 +32,7 @@ was only used on "supercomputer models".
 
 Most modern CPU models (from AMD, Intel, etc.) these days (either in a desktop or in a
 notebook model) have support for SIMD operations. So, if you have a very old CPU model installed in your
-computer, then, it is possible that you have no support for SIMD operations in your computer.
+computer, then, it's possible that you have no support for SIMD operations in your computer.
 
 Why have people started using SIMD in their software? The answer is performance.
 But what does SIMD precisely do to achieve better performance? Well, in essence, SIMD operations are a different
@@ -156,7 +156,7 @@ try stdout.print("{any}\n", .{v1});
 
 As I described in @sec-what-vectors, each vector object is usually a small block of 128, 256 or 512 bits.
 This means that a vector object is usually small in size, and when you try to go in the opposite direction,
-by creating a vector object that is very big in size (i.e. sizes that are close to $2^{20}$),
+by creating a vector object that is very big in size (i.e., sizes that are close to $2^{20}$),
 you usually end up with crashes and loud errors from the compiler.
 
 For example, if you try to compile the program below, you will likely face segmentation faults, or LLVM errors during
diff --git a/README.md b/README.md
index 567e904d..b8eb409c 100644
--- a/README.md
+++ b/README.md
@@ -56,7 +56,7 @@ If you do have a Revolut account, you can scan the following QR code:
 
 ## About this book
 
-This is an open (i.e. it is open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),
+This is an open (i.e., open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),
 which is a new general purpose, and low-level programming language for building optimal and robust software.
 
 Official repository of the book: <https://github.com/pedropark99/zig-book>.
diff --git a/index.qmd b/index.qmd
index f7e81492..a63df77b 100644
--- a/index.qmd
+++ b/index.qmd
@@ -70,7 +70,7 @@ If you do have a Revolut account, you can scan the following QR code:
 
 ## About this book {.unnumbered}
 
-This an open (i.e. it is open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),
+This an open (i.e., open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),
 which is a new general purpose, and low-level programming language for building optimal and robust software.
 
 Official repository of the book: <https://github.com/pedropark99/zig-book>.
@@ -184,5 +184,3 @@ for (i in seq_len(n)) {
 }
 cat(paste(vec, collapse = ", "), sep = "\n")
 ```
-
-
diff --git a/zig_engine.R b/zig_engine.R
index 9471c870..1f76d880 100644
--- a/zig_engine.R
+++ b/zig_engine.R
@@ -236,7 +236,7 @@ get_build_type <- function(options) {
 #' @param options The list of code block options.
 #'
 #' @return The knitr engine output, which contains the output of the Zig code
-#'     (i.e. the output of the executable compiled from this Zig code).
+#'     (i.e., the output of the executable compiled from this Zig code).
 zig_engine <- function(options) {
   code <- str_flatten(options$code, "\n")
   if (!options$eval) {
@@ -297,7 +297,7 @@ write_zig <- function(zig_code) {
 #' @param options The list of code block options.
 #'
 #' @return The knitr engine output, which contains the output of the Zig code
-#'     (i.e. the output of the executable compiled from this Zig code).
+#'     (i.e., the output of the executable compiled from this Zig code).
 zig_run <- function(zig_code, options) {
   if (get_auto_main(options)) {
     zig_code <- generate_main(zig_code)
@@ -348,7 +348,7 @@ zig_build_lib <- function(zig_code, options) {
 #' @param options The list of code block options.
 #'
 #' @return The knitr engine output, which contains the output of the Zig code
-#'     (i.e. the output of the executable compiled from this Zig code).
+#'     (i.e., the output of the executable compiled from this Zig code).
 zig_test <- function(zig_code, options) {
   file_path <- write_zig(zig_code)
   output <- zig_compile_file(file_path, "test")
@@ -361,7 +361,7 @@ zig_test <- function(zig_code, options) {
 #' Check syntax of Zig code with ast-check.
 #'
 #' This function is normally used only on code blocks that are not evaluated
-#' (i.e. `eval: false`). This function receives some Zig source code as input,
+#' (i.e., `eval: false`). This function receives some Zig source code as input,
 #' and then, it writes this source code to a Zig file (`*.zig`), then, it checks
 #' if the syntax of the source code in this file is correct, by using the
 #' `zig ast-check` command
@@ -370,7 +370,7 @@ zig_test <- function(zig_code, options) {
 #' @param options The list of code block options.
 #'
 #' @return The knitr engine output, which contains the output of the Zig code
-#'     (i.e. the output of the executable compiled from this Zig code).
+#'     (i.e., the output of the executable compiled from this Zig code).
 zig_ast_check <- function(zig_code, options) {
   if (get_auto_main(options)) {
     zig_code <- generate_main(zig_code)

From e14bced2ecb27765a6fca0ca1c44ecdc9b0584df Mon Sep 17 00:00:00 2001
From: Pedro Faria <69123925+pedropark99@users.noreply.github.com>
Date: Thu, 6 Mar 2025 14:10:53 -0300
Subject: [PATCH 106/151] Update Chapters/03-structs.qmd

---
 Chapters/03-structs.qmd | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Chapters/03-structs.qmd b/Chapters/03-structs.qmd
index 999845d4..59280306 100644
--- a/Chapters/03-structs.qmd
+++ b/Chapters/03-structs.qmd
@@ -1212,7 +1212,8 @@ test {
 ```
 
 This is the general way to perform type casting in Zig. But remember, `@as()` works only when casting
-is unambiguous and safe—there are situations where these assumptions do not hold. For example,
+is unambiguous and safe. There are many situations where these assumptions do not hold. For example,
+
 when casting an integer value into a float value, or vice-versa, it's not clear to the compiler
 how to perform this conversion safely.
 

From 754af9002fbd78e832bd556077e58537ce655884 Mon Sep 17 00:00:00 2001
From: Pedro Faria <69123925+pedropark99@users.noreply.github.com>
Date: Thu, 6 Mar 2025 14:11:02 -0300
Subject: [PATCH 107/151] Update Chapters/01-base64.qmd

---
 Chapters/01-base64.qmd | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Chapters/01-base64.qmd b/Chapters/01-base64.qmd
index 7a831bb7..caca28bd 100644
--- a/Chapters/01-base64.qmd
+++ b/Chapters/01-base64.qmd
@@ -168,7 +168,8 @@ Taking the string "Hi" as an example, we have 2 bytes, or, 16 bits in total. So,
 to complete the window of 24 bits that the base64 algorithm likes to work on. The first thing that
 the algorithm does, is to check how to divide the input bytes into groups of 6 bits.
 
-If the algorithm notices that there is a group of 6 bits that have some bits in it, but, at the same time it's
+If the algorithm notices that there is a group of 6 bits that it's not complete, meaning that, this group contains $nbits$, where $0 < nbits < 6$,
+
 not full—lacking some bits to fill the 6-bits requirement ($0 < nbits < 6$, being $nbits$ the number of bits),
 the algorithm simply adds extra zeros in this group to fill the space that it needs.
 That is why in @fig-base64-algo1, in the third group after the 6-bit transformation,

From 2299abf8fad3777e91bcf763acd67ca84df69f26 Mon Sep 17 00:00:00 2001
From: Pedro Faria <69123925+pedropark99@users.noreply.github.com>
Date: Thu, 6 Mar 2025 14:11:12 -0300
Subject: [PATCH 108/151] Update Chapters/01-base64.qmd

---
 Chapters/01-base64.qmd | 1 -
 1 file changed, 1 deletion(-)

diff --git a/Chapters/01-base64.qmd b/Chapters/01-base64.qmd
index caca28bd..d2c4f28e 100644
--- a/Chapters/01-base64.qmd
+++ b/Chapters/01-base64.qmd
@@ -170,7 +170,6 @@ the algorithm does, is to check how to divide the input bytes into groups of 6 b
 
 If the algorithm notices that there is a group of 6 bits that it's not complete, meaning that, this group contains $nbits$, where $0 < nbits < 6$,
 
-not full—lacking some bits to fill the 6-bits requirement ($0 < nbits < 6$, being $nbits$ the number of bits),
 the algorithm simply adds extra zeros in this group to fill the space that it needs.
 That is why in @fig-base64-algo1, in the third group after the 6-bit transformation,
 2 extra zeros were added to fill the gap.

From 267b8f6700f2c0c713057790d7de3e2ccb289b64 Mon Sep 17 00:00:00 2001
From: Pedro Faria <69123925+pedropark99@users.noreply.github.com>
Date: Thu, 6 Mar 2025 14:11:20 -0300
Subject: [PATCH 109/151] Update Chapters/01-zig-weird.qmd

---
 Chapters/01-zig-weird.qmd | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index a05d7747..27370753 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -52,7 +52,8 @@ with tons of features, and also, there are lots of different "flavors of C++". T
 are what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.
 Zig is a very simple language, more closely related to other simple languages such as C and Go.
 
-The phrase above is still important for C programmers too. Because, even if C is a simple
+The phrase above is still important for C programmers too. Because, even C being a simple
+
 language, it's still hard sometimes to read and understand C code. For example, pre-processor macros in
 C are a frequent source of confusion. They sometimes really make it hard to debug
 C programs. Because macros are essentially a second language embedded in C that obscures

From 8210952b84fcc6ace7bcba4f711b2015d6edaf13 Mon Sep 17 00:00:00 2001
From: Pedro Faria <69123925+pedropark99@users.noreply.github.com>
Date: Thu, 6 Mar 2025 14:11:27 -0300
Subject: [PATCH 110/151] Update Chapters/01-zig-weird.qmd

---
 Chapters/01-zig-weird.qmd | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index 27370753..eb58a6ed 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -55,7 +55,8 @@ Zig is a very simple language, more closely related to other simple languages su
 The phrase above is still important for C programmers too. Because, even C being a simple
 
 language, it's still hard sometimes to read and understand C code. For example, pre-processor macros in
-C are a frequent source of confusion. They sometimes really make it hard to debug
+C are a frequent source of confusion. Sometimes, they really make it hard to debug
+
 C programs. Because macros are essentially a second language embedded in C that obscures
 your C code. With macros, you are no longer 100% sure about which pieces
 of the code are being sent to the compiler, i.e.

From 9e918261a26ae0cea9abb454266dd9e12dd890a6 Mon Sep 17 00:00:00 2001
From: Pedro Faria <69123925+pedropark99@users.noreply.github.com>
Date: Thu, 6 Mar 2025 14:11:35 -0300
Subject: [PATCH 111/151] Update Chapters/01-zig-weird.qmd

---
 Chapters/01-zig-weird.qmd | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index eb58a6ed..4c9d4f68 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -450,7 +450,8 @@ Hello
 ```
 
 You can read more details about this Windows-specific limitation in a couple of
-GitHub issues opened  the official Zig repository. More specifically, the issues
+GitHub issues opened at the official Zig repository. More specifically, the issues
+
 17186 [^cissue1] and 19864 [^cissue2].
 
 [^cissue1]: <https://github.com/ziglang/zig/issues/17186>

From 00a184129e336f1f30c7ffa604167e7bcada729d Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Thu, 6 Mar 2025 14:41:50 -0300
Subject: [PATCH 112/151] Add runtime length example

---
 ZigExamples/zig-basics/runtime-slices-length.zig | 13 +++++++++++++
 1 file changed, 13 insertions(+)
 create mode 100644 ZigExamples/zig-basics/runtime-slices-length.zig

diff --git a/ZigExamples/zig-basics/runtime-slices-length.zig b/ZigExamples/zig-basics/runtime-slices-length.zig
new file mode 100644
index 00000000..8d0147de
--- /dev/null
+++ b/ZigExamples/zig-basics/runtime-slices-length.zig
@@ -0,0 +1,13 @@
+const std = @import("std");
+const builtin = @import("builtin");
+
+pub fn main() !void {
+    comptime var n: usize = 0;
+    if (builtin.target.os.tag == .windows) {
+        n = 10;
+    } else {
+        n = 12;
+    }
+    const buffer: [n]u8 = undefined;
+    _ = buffer;
+}

From c2d31ccbf4587f2c17b37d8e9d4390108992f544 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Thu, 6 Mar 2025 17:50:49 -0300
Subject: [PATCH 113/151] Recompile book with changes

---
 .../01-base64/execute-results/html.json       |   8 +-
 .../01-memory/execute-results/html.json       |   8 +-
 .../01-zig-weird/execute-results/html.json    |   8 +-
 .../02-debugging/execute-results/html.json    |   8 +-
 .../03-structs/execute-results/html.json      |   8 +-
 .../03-unittests/execute-results/html.json    |   8 +-
 .../04-http-server/execute-results/html.json  |   8 +-
 .../05-pointers/execute-results/html.json     |   8 +-
 .../07-build-system/execute-results/html.json |   8 +-
 .../execute-results/html.json                 |   8 +-
 .../execute-results/html.json                 |   8 +-
 .../execute-results/html.json                 |   8 +-
 .../12-file-op/execute-results/html.json      |   8 +-
 .../13-image-filter/execute-results/html.json |   8 +-
 .../14-threads/execute-results/html.json      |   8 +-
 .../execute-results/html.json                 |   8 +-
 .../15-vectors/execute-results/html.json      |   8 +-
 _freeze/index/execute-results/html.json       |   4 +-
 contributors.txt                              |   2 +
 docs/Chapters/01-base64.html                  |  51 ++---
 docs/Chapters/01-memory.html                  |  40 ++--
 docs/Chapters/01-zig-weird.html               | 109 +++++-----
 docs/Chapters/02-debugging.html               |  18 +-
 docs/Chapters/03-structs.html                 |  47 ++---
 docs/Chapters/03-unittests.html               |  18 +-
 docs/Chapters/04-http-server.html             |  46 ++---
 docs/Chapters/05-pointers.html                |  20 +-
 docs/Chapters/07-build-system.html            |  46 ++---
 docs/Chapters/09-data-structures.html         |  68 +++----
 docs/Chapters/09-error-handling.html          |  44 ++---
 docs/Chapters/10-stack-project.html           |  58 +++---
 docs/Chapters/12-file-op.html                 |  64 +++---
 docs/Chapters/13-image-filter.html            |  28 +--
 docs/Chapters/14-threads.html                 | 158 +++++++--------
 docs/Chapters/14-zig-c-interop.html           |  32 +--
 docs/Chapters/15-vectors.html                 |  16 +-
 docs/index.html                               |   8 +-
 docs/search.json                              | 186 +++++++++---------
 38 files changed, 620 insertions(+), 579 deletions(-)

diff --git a/_freeze/Chapters/01-base64/execute-results/html.json b/_freeze/Chapters/01-base64/execute-results/html.json
index 7a805424..78be8b28 100644
--- a/_freeze/Chapters/01-base64/execute-results/html.json
+++ b/_freeze/Chapters/01-base64/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "f1304b563ed8036a5bbeaa9b658cfdf0",
+  "hash": "d5c0ae1b8bb17e483184003ae042e212",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 1 - Building a base64 encoder/decoder {#sec-base64}\n\nAs our first small project, I want to implement a base64 encoder/decoder with you.\nBase64 is an encoding system which translates binary data to text.\nA big chunk of the web uses base64 to deliver binary data to systems\nthat can only read text data.\n\nThe most common example of a modern use case for base64 is essentially any email system,\nlike GMail, Outlook, etc. Because email systems normally use\nthe Simple Mail Transfer Protocol (SMTP), which is a web protocol\nthat supports only text data. So, if you need, for any reason, to\nsend a binary file (like for example, a PDF, or an Excel file) as\nan attachment in your email, these binary files are normally\nconverted to base64, before they are included in the SMTP message.\nSo, the base64 encoding is largely used in these email systems to include\nbinary data into the SMTP message.\n\n\n\n\n\n\n## How the base64 algorithm work?\n\nBut how exactly does the algorithm behind the base64 encoding work? Let's discuss that. First, I will\nexplain the base64 scale, which is the 64-character scale that is the basis for\nthe base64 encoding system.\n\nAfter that, I explain the algorithm behind a base64 encoder, which is the part of the algorithm that is responsible for encoding messages\ninto the base64 encoding system. Then, after that, I explain the algorithm behind a base64 decoder, which is\nthe part of the algorithm that is responsible for translating base64 messages back into their original meaning.\n\nIf you are unsure about the differences between an \"encoder\" and a \"decoder\",\ntake a look at @sec-encode-vs-decode.\n\n\n### The base64 scale {#sec-base64-scale}\n\nThe base64 encoding system is based on a scale that goes from 0 to 63 (hence the name).\nEach index in this scale is represented by a character (it is a scale of 64 characters).\nSo, in order to convert some binary data, to the base64 encoding, we need to convert each binary number to the corresponding\ncharacter in this \"scale of 64 characters\".\n\nThe base64 scale starts with all ASCII uppercase letters (A to Z) which represents\nthe first 25 indexes in this scale (0 to 25). After that, we have all ASCII lowercase letters\n(a to z), which represents the range 26 to 51 in the scale. After that, we\nhave the one digit numbers (0 to 9), which represents the indexes from 52 to 61 in the scale.\nFinally, the last two indexes in the scale (62 and 63) are represented by the characters `+` and `/`,\nrespectively.\n\nThese are the 64 characters that compose the base64 scale. The equal sign character (`=`) is not part of the scale itself,\nbut it is a special character in the base64 encoding system. This character is used solely as a suffix, to mark the end of the character sequence,\nor, to mark the end of meaningful characters in the sequence.\n\nThe bullet points below summarises the base64 scale:\n\n- range 0 to 25 is represented by: ASCII uppercase letters `-> [A-Z]`;\n- range 26 to 51 is represented by: ASCII lowercase letters `-> [a-z]`;\n- range 52 to 61 is represented by: one digit numbers `-> [0-9]`;\n- index 62 and 63 are represented by the characters `+` and `/`, respectively;\n- the character `=` represents the end of meaningful characters in the sequence;\n\n\n\n\n### Creating the scale as a lookup table {#sec-base64-table}\n\nThe best way to represent this scale in code, is to represent it as a *lookup table*.\nLookup tables are a classic strategy in computer science to speed up calculations. The basic idea\nis to replace a runtime calculation (which can take a long time to be done) with a basic array indexing\noperation.\n\nInstead of calculating the results everytime you need them, you calculate all possible results at once, and then, you store them in an array\n(which behaves lake a \"table\"). Then, every time you need to use one of the characters in the base64 scale, instead of\nusing many resources to calculate the exact character to be used, you simply retrieve this character\nfrom the array where you stored all the possible characters in the base64 scale.\nWe retrieve the character that we need directly from memory.\n\nWe can start building a Zig struct to store our base64 decoder/encoder logic.\nWe start with the `Base64` struct below. For now, we only have one single data member in this\nstruct, i.e. the member `_table`, which represents our lookup table. We also have an `init()` method,\nto create a new instance of a `Base64` object, and, a `_char_at()` method, which is a\n\"get character at index $x$\" type of function.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Base64 = struct {\n    _table: *const [64]u8,\n\n    pub fn init() Base64 {\n        const upper = \"ABCDEFGHIJKLMNOPQRSTUVWXYZ\";\n        const lower = \"abcdefghijklmnopqrstuvwxyz\";\n        const numbers_symb = \"0123456789+/\";\n        return Base64{\n            ._table = upper ++ lower ++ numbers_symb,\n        };\n    }\n\n    pub fn _char_at(self: Base64, index: usize) u8 {\n        return self._table[index];\n    }\n};\n```\n:::\n\n\n\n\n\nIn other words, the `_char_at()` method is responsible for getting the character in the lookup\ntable (i.e. the `_table` struct data member) that corresponds to a particular index in the\n\"base64 scale\". So, in the example below, we know that the character that corresponds to the\nindex 28 in the \"base64 scale\" is the character \"c\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst base64 = Base64.init();\ntry stdout.print(\n    \"Character at index 28: {c}\\n\",\n    .{base64._char_at(28)}\n);\n```\n:::\n\n\n\n\n```\nCharacter at index 28: c\n```\n\n\n\n### A base64 encoder {#sec-base64-encoder-algo}\n\nThe algorithm behind a base64 encoder usually works on a window of 3 bytes. Because each byte has\n8 bits, so, 3 bytes forms a set of $8 \\times 3 = 24$ bits. This is desirable for the base64 algorithm, because\n24 bits is divisible by 6, which forms $24 / 6 = 4$ groups of 6 bits each.\n\nTherefore, the base64 algorithm works by converting 3 bytes at a time\ninto 4 characters from the base64 scale. It keeps iterating through the input string,\n3 bytes at a time, and converting them into the base64 scale, producing 4 characters\nper iteration. It keeps iterating, and producing these \"new characters\"\nuntil it hits the end of the input string.\n\nNow, you may think, what if you have a particular string that have a number of bytes\nthat is not divisible by 3? What happens? For example, if you have a string\nthat contains only two characters/bytes, such as \"Hi\". How the\nalgorithm would behave in such situation? You find the answer at @fig-base64-algo1.\nYou can see at @fig-base64-algo1 that the string \"Hi\", when converted to base64,\nbecomes the string \"SGk=\":\n\n![The logic behind a base64 encoder](./../Figures/base64-encoder-flow.png){#fig-base64-algo1}\n\nTaking the string \"Hi\" as an example, we have 2 bytes, or, 16 bits in total. So, we lack a full byte (8 bits)\nto complete the window of 24 bits that the base64 algorithm likes to work on. The first thing that\nthe algorithm does, is to check how to divide the input bytes into groups of 6 bits.\n\nIf the algorithm notices that there is a group of 6 bits that, have some bits in it, but, at the same time, it is not full\n(in other words, $0 < nbits < 6$, being $nbits$ the number of bits), meaning that, it lacks\nsome bits to fill the 6-bits requirement, the algorithm simply add extra zeros in this group\nto fill the space that it needs. That is why at @fig-base64-algo1, on the third group after the 6-bit transformation,\n2 extra zeros were added to fill the gap in this group.\n\nWhen we have a 6-bit group that is not completely full, like the third group, extra zeros\nare added to fill the gap. But what about when an entire 6-bit group is empty, or, it\nsimply doesn't exist? This is the case of the fourth 6-bit group exposed at\n@fig-base64-algo1.\n\nThis fourth group is necessary, because the algorithm works on 4 groups of 6 bits.\nBut the input string does not have enough bytes to create a fourth 6-bit group.\nEvery time this happens, where an entire group of 6 bits is empty,\nthis group becomes a \"padding group\". Every \"padding group\" is mapped to\nthe character `=` (equal sign), which represents \"null\", or, the end\nof meaningful characters in the sequence. Hence, everytime that the algorithm produces a\n\"padding group\", this group is automatically mapped to `=`.\n\nAs another example, if you give the string \"0\" as input to a base64 encoder, this string is\ntranslated into the base64 sequence \"MA==\".\nThe character \"0\" is, in binary, the sequence `00110000`[^zero-note]. So, with the 6-bit transformation\nexposed at @fig-base64-algo1, this single character would produce these two 6-bit groups: `001100`, `000000`.\nThe remaining two 6-bit groups become \"padding groups\". That is why the last\ntwo characters in the output sequence (MA==) are `==`.\n\n\n[^zero-note]: Notice that, the character \"0\" is different than the actual number 0, which is simply zero in binary.\n\n### A base64 decoder {#sec-base64-decoder-algo}\n\nThe algorithm behind a base64 decoder is essentially the inverse process of a base64 encoder.\nA base64 decoder needs to translate base64 messages back into their original meaning,\ni.e. into the original sequence of binary data.\n\nA base64 decoder usually works on a window of 4 bytes. Because it wants to convert these 4 bytes\nback into the original sequence of 3 bytes, that was converted into 4 groups of 6 bits by the\nbase64 encoder. Remember, in a base64 decoder we are essentially reverting the process made\nby the base64 encoder.\n\nEach byte in the input string (the base64 encoded string) normally contributes to re-create\ntwo different bytes in the output (the original binary data).\nIn other words, each byte that comes out of a base64 decoder is created by transforming merging two different\nbytes in the input together. You can visualize this relationship at @fig-base64-algo2:\n\n![The logic behind a base64 decoder](./../Figures/base64-decoder-flow.png){#fig-base64-algo2}\n\nThe exact transformations, or, the exact steps applied to each byte from the input to transform them\ninto the bytes of the output, are a bit tricky to visualize in a figure like this. Because of that, I have\nsummarized these transformations as \"Some bit shifting and additions ...\" in the figure. These transformations\nwill be described in depth later.\n\nBesides that, if you look again at @fig-base64-algo2, you will notice that the character `=` was completely\nignored by the algorithm. Remember, this is just a special character that marks the end of meaningful characters\nin the base64 sequence. So, every `=` character in a base64 encoded sequence should be ignored by a base64 decoder.\n\n\n## Difference between encode and decode {#sec-encode-vs-decode}\n\nIf you don't have any previous experience with base64, you might not understand the differences\nbetween \"encode\" and \"decode\". Essentially, the terms \"encode\" and \"decode\" here\nhave the exact same meaning as they have in the field of encryption (i.e. they mean the same thing as \"encode\" and \"decode\" in hashing\nalgorithms, like the MD5 algorithm).\n\nThus, \"encode\" means that we want to encode, or, in other words, we want to translate some message into\nthe base64 encoding system. We want to produce the sequence of base64 characters that represent this\noriginal message in the base64 encoding system.\n\nIn contrast, \"decode\" represents the inverse process.\nWe want to decode, or, in other words, translate a base64 message back to its original content.\nSo, in this process we get a sequence of base64 characters as input, and produce as output,\nthe binary data that is represented by this sequence of base64 characters.\n\nAny base64 library is normally composed of these two parts: 1) the encoder, which is a function that encodes\n(i.e. it converts) any sequence of binary data into a sequence of base64 characters; 2) the decoder, which is a function\nthat converts a sequence of base64 characters back into the original sequence of binary data.\n\n\n\n## Calculating the size of the output {#sec-base64-length-out}\n\nOne task that we need to do is to calculate how much space we need to reserve for the\noutput, both of the encoder and decoder. This is simple math, and can be done easily in Zig\nbecause every array has its length (its number of elements) easily accesible by consulting\nthe `.len` property of the array.\n\nFor the encoder, the logic is the following: for each 3 bytes that we find in the input,\n4 new bytes are created in the output. So, we take the number of bytes in the input, divide it\nby 3, use a ceiling function, then, we multiply the result by 4. That way, we get the total\nnumber of bytes that will be produced by the encoder in its output.\n\nThe `_calc_encode_length()` function below encapsulates this logic.\nInside this function, we take the length of the input array,\nwe divide it by 3, and apply a ceil operation over the result by using the\n`divCeil()` function from the Zig Standard Library. Lastly, we multiply\nthe end result by 4 to get the answer we need.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_encode_length(input: []const u8) !usize {\n    if (input.len < 3) {\n        const n_output: usize = 4;\n        return n_output;\n    }\n    const n_output: usize = try std.math.divCeil(\n        usize, input.len, 3\n    );\n    return n_output * 4;\n}\n```\n:::\n\n\n\n\n\nAlso, you might have notice that, if the input length is less than 3 bytes, then, the output length of the encoder is\nalways 4 bytes. This is the case for every input with less than 3 bytes, because, as I described at @sec-base64-encoder-algo,\nthe algorithm always produces enough \"padding-groups\" in the end result, to complete the 4 bytes window.\n\nNow, for the decoder, we just need to apply the inverse logic: for each 4 bytes in the input, 3 bytes\nwill be produced in the output of the decoder. I mean, this is roughly true, because we also need to\ntake the `=` character into account, which is always ignored by the decoder, as we described at @sec-base64-decoder-algo, and,\nat @fig-base64-algo2. But we can ignore this fact for now, just to keep things simple.\n\nThe function `_calc_decode_length()` exposed below summarizes this logic that we described. It is very similar\nto the function `_calc_encode_length()`. Only the division part is twisted, and also, in the special\ncase where we have less than 4 bytes in the input to work on. Also notice that this time, we apply\na floor operation over the output of the division, by using the `divFloor()`\nfunction (instead of a ceiling operation with `divCeil()`).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_decode_length(input: []const u8) !usize {\n    if (input.len < 4) {\n        const n_output: usize = 3;\n        return n_output;\n    }\n    const n_output: usize = try std.math.divFloor(\n        usize, input.len, 4\n    );\n    return n_output * 3;\n}\n```\n:::\n\n\n\n\n\n## Building the encoder logic {#sec-encoder-logic}\n\nIn this section, we can start building the logic behind the `encode()` function, which\nwill be responsible for encoding messages into the base64 encoding system.\nIf you are an anxious person, and you want to see now the full source code of the implementation\nfor this base64 encoder/decoder, you can find it at the `ZigExamples` folder in the official repository of\nthis book[^zig-base64-algo].\n\n[^zig-base64-algo]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/base64/base64_basic.zig>.\n\n\n\n### The 6-bit transformation {#sec-6bit-transf}\n\nThe 6-bit transformation presented at @fig-base64-algo1 is the core part of the base64 encoder algorithm.\nBy understanding how this transformation is made in code, the rest of the algorithm becomes much simpler\nto comprehend.\n\nIn essence, this 6-bit transformation is made with the help of bitwise operators.\nBitwise operators are essential to any type of low-level operation that is done at the bit-level. For the specific case of the base64 algorithm,\nthe operators *bif shift to the left* (`<<`), *bit shift to the right* (`>>`), and the *bitwise and* (`&`) are used. They\nare the core solution for the 6-bit transformation.\n\nThere are 3 different scenarios that we need to take into account in this transformation. First, is the perfect scenario,\nwhere we have the perfect window of 3 bytes to work on. Second, we have the scenario where we have a window of only\ntwo bytes to work with. And last, we have the scenario where we have a window of one single byte.\n\nIn each of these 3 scenarios, the 6-bit transformation works a bit differently. To make the explanation\neasier, I will use the variable `output` to refer to the bytes in the output of the base64 encoder,\nand the variable `input` to refer to the bytes in the input of the encoder.\n\n\nSo, if you have the perfect window of 3 bytes, these are steps for the 6-bit transformation:\n\n1. `output[0]` is produced by moving the bits from `input[0]` two positions to the right.\n1. `output[1]` is produced by summing two components. First, take the last two bits from `input[0]`, then, move them four positions to the left. Second, move the bits from `input[1]` four positions to the right. Sum these two components.\n1. `output[2]` is produced by summing two components. First, take the last four bits from `input[1]`, then, move them two positions to the left. Second, move the bits from `input[2]` six positions to the right. Sum these two components.\n1. `output[3]` is produced by taking the last six bits from `input[2]`.\n\n\nThis is the perfect scenario, where we have a full window of 3 bytes to work on.\nJust to make things as clear as possible, the @fig-encoder-bitshift demonstrates visually how\nthe step 2 mentioned above works. So the 2nd byte in the `output` of the encoder, is made by taking the 1st byte (dark purple)\nand the 2nd byte (orange) from the input. You can see that, at the end of the process, we get a new\nbyte that contains the last 2 bits from the 1st byte in the `input`, and the first 4 bits\nfrom the 2nd byte in the `input`.\n\n![How the 2nd byte in the output of the encoder is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input.](../Figures/base64-encoder-bit-shift.png){#fig-encoder-bitshift}\n\nOn the other hand, we must be prepared for the instances where we do not have the perfect window of 3 bytes.\nIf you have a window of 2 bytes, then, the steps 3 and 4, which produces the bytes `output[2]` and `output[3]`, change a little bit,\nand they become:\n\n- `output[2]` is produced by taking the last 4 bits from `input[1]`, then, move them two positions to the left.\n- `output[3]` is the character `'='`.\n\n\nFinally, if you have a window of a single byte, then, the steps 2 to 4, which produces the bytes `output[1]`, `output[2]` and `output[3]` change,\nbecoming:\n\n- `output[1]` is produced by taking the last two bits from `input[0]`, then, move them four positions to the left.\n- `output[2]` and `output[3]` are the character `=`.\n\n\nIf these bullet points were a bit confusing for you, you may find the @tbl-transf-6bit more intuitive.\nThis table unifies all this logic into a simple table. Notice that\nthis table also provides the exact expression in Zig that creates the corresponding\nbyte in the output.\n\n\n::: {#tbl-transf-6bit}\n\n| Number of bytes in the window | Byte index in the output | In code                                    |\n|-------------------------------|--------------------------|--------------------------------------------|\n| 3                             | 0                        | input[0] >> 2                              |\n| 3                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 3                             | 2                        | ((input[1] & 0x0f) << 2) + (input[2] >> 6) |\n| 3                             | 3                        | input[2] & 0x3f                            |\n| 2                             | 0                        | input[0] >> 2                              |\n| 2                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 2                             | 2                        | ((input[1] & 0x0f) << 2)                   |\n| 2                             | 3                        | '='                                        |\n| 1                             | 0                        | input[0] >> 2                              |\n| 1                             | 1                        | ((input[0] & 0x03) << 4)                   |\n| 1                             | 2                        | '='                                        |\n| 1                             | 3                        | '='                                        |\n\n: How the 6-bit transformation translates into code in different window settings.\n\n:::\n\n\n\n\n\n\n### Bit-shifting in Zig\n\nBit-shifting in Zig works similarly to bit-shifting in C.\nAll bitwise operators that exist in C are available in Zig.\nHere, in the base64 encoder algorithm, they are essential\nto produce the result we want.\n\nFor those who are not familiar with these operators, they are\noperators that operates at the bit-level of your values.\nThis means that these operators takes the bits that form the value\nyou have, and change them in some way. This ultimately also changes\nthe value itself, because the binary representation of this value\nchanges.\n\nWe have already seen at @fig-encoder-bitshift the effect produced by a bit-shift.\nBut let's use the first byte in the output of the base64 encoder as another example of what\nbit-shifting means. This is the easiest byte of the 4 bytes in the output\nto build. Because we only need to move the bits from the first byte in the input two positions to the right,\nwith the *bit shift to the right* (`>>`) operator.\n\nIf we take the string \"Hi\" that we used at @fig-base64-algo1 as an example, the first byte in\nthis string is \"H\", which is the sequence `01001000` in binary.\nIf we move the bits of this byte, two places to the right, we get the sequence `00010010` as result.\nThis binary sequence is the value `18` in decimal, and also, the value `0x12` in hexadecimal.\nNotice that the first 6 bits of \"H\" were moved to the end of the byte.\nWith this operation, we get the first byte of the output.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const input = \"Hi\";\n    try stdout.print(\"{d}\\n\", .{input[0] >> 2});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n18\n```\n\n\n:::\n:::\n\n\n\n\nIf you recall @fig-base64-algo1, the first byte present in the output should\nbe equivalent to the 6-bit group `010010`. Although being visually different, the\nsequences `010010` and `00010010` are semantically equal. They mean the same thing.\nThey both represent the number 18 in decimal, and the value `0x12` in hexadecimal.\n\nSo, don't take the \"6-bit group\" factor so seriously. We do not need necessarily to\nget a 6-bit sequence as result. As long as the meaning of the 8-bit sequence we get is the same\nof the 6-bit sequence, we are in the clear.\n\n\n\n### Selecting specific bits with the `&` operator\n\nIf you comeback to @sec-6bit-transf, you will see that, in order to produce\nthe second and third bytes in the output, we need to select specific\nbits from the first and second bytes in the input string. But how\ncan we do that? The answer relies on the *bitwise and* (`&`) operator.\n\nThe @fig-encoder-bitshift already showed you what effect this `&` operator\nproduces in the bits of its operands. But let's make a clear description of it.\n\nIn summary, the `&` operator performs a logical conjunction operation\nbetween the bits of its operands. In more details, the operator `&`\ncompares each bit of the first operand to the corresponding bit of the second operand.\nIf both bits are 1, the corresponding result bit is set to 1.\nOtherwise, the corresponding result bit is set to 0 [@microsoftbitwiseand].\n\nSo, if we apply this operator to the binary sequences `1000100` and `00001101`\nthe result of this operation is the binary sequence `00000100`. Because only\nat the sixth position in both binary sequences we had a 1 value. So any\nposition where we do not have both binary sequences setted to 1, we get\na 0 bit in the resulting binary sequence.\n\nWe lose information about the original bit values\nfrom both sequences in this case. Because we no longer know\nif this 0 bit in the resulting binary sequence was produced by\ncombining 0 with 0, or 1 with 0, or 0 with 1.\n\nAs an example, suppose you have the binary sequence `10010111`, which is the number 151 in decimal. How\ncan we get a new binary sequence which contains only the third and\nfourth bits of this sequence?\n\nWe just need to combine this sequence with `00110000` (is `0x30` in hexadecimal) using the `&` operator.\nNotice that only the third and fourth positions in this binary sequence is setted to 1. As a consequence, only the\nthird and fourth values of both binary sequences are potentially preserved in the output. All the remaining positions\nare setted to zero in the output sequence, which is `00010000` (is the number 16 in decimal).\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const bits = 0b10010111;\n    try stdout.print(\"{d}\\n\", .{bits & 0b00110000});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n16\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Allocating space for the output\n\nAs I described at @sec-stack, to store an object in the stack,\nthis object needs to have a known and fixed length at compile-time. This is an important\nlimitation for our base64 encoder/decoder case. Because the size of\nthe output (from both the encoder and decoder) depends\ndirectly on the size of the input.\n\nHaving this in mind, we cannot know at compile time which is\nthe size of the output for both the encoder and decoder.\nSo, if we can't know the size of the output at compile time,\nthis means that we cannot store the output for both the encoder\nand decoder in the stack.\n\nConsequently, we need to store this output on the heap,\nand, as I commented at @sec-heap, we can only\nstore objects in the heap by using allocator objects.\nSo, one the arguments to both the `encode()` and `decode()`\nfunctions, needs to be an allocator object, because\nwe know for sure that, at some point inside the body of these\nfunctions, we need to allocate space on the heap to\nstore the output of these functions.\n\nThat is why, both the `encode()` and `decode()` functions that I\npresent in this book, have an argument called `allocator`,\nwhich receives a allocator object as input, identified by\nthe type `std.mem.Allocator` from the Zig Standard Library.\n\n\n\n### Writing the `encode()` function\n\nNow that we have a basic understanding on how the bitwise operators work, and how\nexactly they help us to achieve the result we want to achieve. We can now encapsulate\nall the logic that we have described at @fig-base64-algo1 and @tbl-transf-6bit into a nice\nfunction that we can add to our `Base64` struct definition, that we started at @sec-base64-table.\n\nYou can find the `encode()` function below. Notice that the first argument of this function,\nis the `Base64` struct itself. Therefore, this argument clearly signals\nthat this function is a method from the `Base64` struct.\n\nBecause the `encode()` function itself is fairly long,\nI intentionally omitted the `Base64` struct definition in this source code,\njust for brevity reasons. So, just remember that this function is a public function (or a public method) from the\n`Base64` struct.\n\nFurthermore, this `encode()` function has two other arguments:\n\n1. `input` is the input sequence of characters that you want to encode in base64;\n1. `allocator` is an allocator object to use in the necessary memory allocations.\n\nI described everything you need to know about allocator objects at @sec-allocators.\nSo, if you are not familiar with them, I highly recommend you to comeback to\nthat section, and read it.\nBy looking at the `encode()` function, you will see that we use this\nallocator object to allocate enough memory to store the output of\nthe encoding process.\n\nThe main for loop in the function is responsible for iterating through the entire input string.\nIn every iteration, we use a `count` variable to count how many iterations we had at the\nmoment. When `count` reaches 3, then, we try to encode the 3 characters (or bytes) that we have accumulated\nin the temporary buffer object (`buf`).\n\nAfter encoding these 3 characters and storing the result in the `output` variable, we reset\nthe `count` variable to zero, and start to count again on the next iteration of the loop.\nIf the loop hits the end of the string, and, the `count` variable is less than 3, then, it means that\nthe temporary buffer contains the last 1 or 2 bytes from the input.\nThat is why we have two `if` statements after the for loop. To deal which each possible case.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn encode(self: Base64,\n              allocator: std.mem.Allocator,\n              input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n\n    const n_out = try _calc_encode_length(input);\n    var out = try allocator.alloc(u8, n_out);\n    var buf = [3]u8{ 0, 0, 0 };\n    var count: u8 = 0;\n    var iout: u64 = 0;\n\n    for (input, 0..) |_, i| {\n        buf[count] = input[i];\n        count += 1;\n        if (count == 3) {\n            out[iout] = self._char_at(buf[0] >> 2);\n            out[iout + 1] = self._char_at(\n                ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n            );\n            out[iout + 2] = self._char_at(\n                ((buf[1] & 0x0f) << 2) + (buf[2] >> 6)\n            );\n            out[iout + 3] = self._char_at(buf[2] & 0x3f);\n            iout += 4;\n            count = 0;\n        }\n    }\n\n    if (count == 1) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            (buf[0] & 0x03) << 4\n        );\n        out[iout + 2] = '=';\n        out[iout + 3] = '=';\n    }\n\n    if (count == 2) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n        );\n        out[iout + 2] = self._char_at(\n            (buf[1] & 0x0f) << 2\n        );\n        out[iout + 3] = '=';\n        iout += 4;\n    }\n\n    return out;\n}\n```\n:::\n\n\n\n\n\n\n## Building the decoder logic {#sec-decoder-logic}\n\nNow, we can focus on writing the base64 decoder logic. Remember from @fig-base64-algo2 that,\na base64 decoder does the inverse process of an encoder. So, all we need to do, is to\nwrite a `decode()` function that performs the inverse process that I exposed at @sec-encoder-logic.\n\n\n### Mapping base64 characters to their indexes {#sec-map-base64-index}\n\nOne thing that we need to do, in order to decode a base64-encoded message, is to calculate\nthe index in the base64 scale of every base64 character that we encounter in the decoder input.\n\nIn other words, the decoder receives as input, a sequence of base64 characters. We need\nto translate this sequence of characters into a sequence of indexes. These indexes\nare the index of each character in the base64 scale. This way, we get the value/byte\nthat was calculated in the 6-bit transformation step of the encoder process.\n\nThere are probably better/faster ways to calculate this, especially using a \"divide and conquer\"\ntype of strategy. But for now, I am satisfied with a simple and \"brute force\" type of strategy.\nThe `_char_index()` function below contains this strategy.\n\nWe are essentially looping through the *lookup table* with the base64 scale,\nand comparing the character we got with each character in the base64 scale.\nIf these characters match, then, we return the index of this character in the\nbase64 scale as the result.\n\nNotice that, if the input character is `'='`, the function returns the index 64, which is\n\"out of range\" in the scale. But, as I described at @sec-base64-scale,\nthe character `'='` does not belong to the base64 scale itself.\nIt is a special and meaningless character in base64.\n\nAlso notice that this `_char_index()` function is a method from our `Base64` struct,\nbecause of the `self` argument. Again, I have omitted the `Base64` struct definition in this example\nfor brevity reasons.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn _char_index(self: Base64, char: u8) u8 {\n    if (char == '=')\n        return 64;\n    var index: u8 = 0;\n    for (0..63) |i| {\n        if (self._char_at(i) == char)\n            break;\n        index += 1;\n    }\n\n    return index;\n}\n```\n:::\n\n\n\n\n\n\n### The 6-bit transformation\n\nOnce again, the core part of the algorithm is the 6-bit transformation.\nIf we understand the necessary steps to perform this transformation, the rest\nof the algorithm becomes much easier.\n\nFirst of all, before we actually go to the 6-bit transformation,\nwe need to make sure that we use `_char_index()` to convert the sequence of base64 characters\ninto a sequence of indexes. So the snippet below is important for the job that will be done.\nThe result of `_char_index()` is stored in a temporary buffer, and this temporary buffer\nis what we are going to use in the 6-bit transformation, instead of the actual `input` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (0..input.len) |i| {\n    buf[i] = self._char_index(input[i]);\n}\n```\n:::\n\n\n\n\nNow, instead of producing 4 bytes (or 4 characters) as output per each window of 3 characters in the input,\na base64 decoder produces 3 bytes (or 3 characters) as output per each window of 4 characters in the input.\nOnce again, is the inverse process.\n\nSo, the steps to produce the 3 bytes in the output are:\n\n1. `output[0]` is produced by summing two components. First, move the bits from `buf[0]` two positions to the left. Second, move the bits from `buf[1]` 4 positions to the right. Then, sum these two components.\n1. `output[1]` is produced by summing two components. First, move the bits from `buf[1]` four positions to the left. Second, move the bits from `buf[2]` 2 positions to the right. Then, sum these two components.\n1. `output[2]` is produced by summing two components. First, move the bits from `buf[2]` six positions to the left. Then, you sum the result with `buf[3]`.\n\n\nBefore we continue, let's try to visualize how these transformations make the original bytes that we had\nbefore the encoding process. First, think back to the 6-bit transformation performed by the encoder exposed at @sec-encoder-logic.\nThe first byte in the output of the encoder is produced by moving the bits in the first byte of the input two positions to the right.\n\nIf for example the first byte in the input of the encoder was the sequence `ABCDEFGH`, then, the first byte in the output of the encoder would be\n`00ABCDEF` (this sequence would be the first byte in the input of the decoder). Now, if the second byte in the input of the encoder was the sequence\n`IJKLMNOP`, then, the second byte in the encoder output would be `00GHIJKL` (as we demonstrated at @fig-encoder-bitshift).\n\nHence, if the sequences `00ABCDEF` and `00GHIJKL` are the first and second bytes, respectively, in the input of the decoder, the\n@fig-decoder-bitshift demonstrates visually how these two bytes are transformed into the first byte of the output of the decoder.\nNotice that the output byte is the sequence `ABCDEFGH`, which is the original byte from the input of the encoder.\n\n![How the 1st byte in the decoder output is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input](../Figures/base64-decoder-bit-shift.png){#fig-decoder-bitshift}\n\nThe @tbl-6bit-decode presents how the three steps described earlier translate into Zig code:\n\n\n\n::: {#tbl-6bit-decode}\n\n| Byte index in the output | In code                       |\n|--------------------------|-------------------------------|\n| 0                        | (buf[0] << 2) + (buf[1] >> 4) |\n| 1                        | (buf[1] << 4) + (buf[2] >> 2) |\n| 2                        | (buf[2] << 6) + buf[3]        |\n\n: The necessary steps for the 6-transformation in the decode process.\n\n\n:::\n\n\n\n\n\n\n\n### Writing the `decode()` function\n\nThe `decode()` function below contains the entire decoding process.\nWe first calculate the size of the output, with\n`_calc_decode_length()`, then, we allocate enough memory for this output with\nthe allocator object.\n\nThree temporary variables are created: 1) `count`, to hold the window count\nin each iteration of the for loop; 2) `iout`, to hold the current index in the output;\n3) `buf`, which is the temporary buffer that holds the base64 indexes to be\nconverted through the 6-bit transformation.\n\nThen, in each iteration of the for loop we fill the temporary buffer with the current\nwindow of bytes. When `count` hits the number 4, then, we have a full window of\nindexes in `buf` to be converted, and then, we apply the 6-bit transformation\nover the temporary buffer.\n\nNotice that we check if the indexes 2 and 3 in the temporary buffer are the number 64, which, if you recall\nfrom @sec-map-base64-index, is when the `_calc_index()` function receives a `'='` character\nas input. So, if these indexes are equal to the number 64, the `decode()` function knows\nthat it can simply ignore these indexes. They are not converted because, as I described before,\nthe character `'='` has no meaning, despite being the end of meaningful characters in the sequence.\nSo we can safely ignore them when they appear in the sequence.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn decode(self: Base64,\n          allocator: std.mem.Allocator,\n          input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n    const n_output = try _calc_decode_length(input);\n    var output = try allocator.alloc(u8, n_output);\n    var count: u8 = 0;\n    var iout: u64 = 0;\n    var buf = [4]u8{ 0, 0, 0, 0 };\n\n    for (0..input.len) |i| {\n        buf[count] = self._char_index(input[i]);\n        count += 1;\n        if (count == 4) {\n            output[iout] = (buf[0] << 2) + (buf[1] >> 4);\n            if (buf[2] != 64) {\n                output[iout + 1] = (buf[1] << 4) + (buf[2] >> 2);\n            }\n            if (buf[3] != 64) {\n                output[iout + 2] = (buf[2] << 6) + buf[3];\n            }\n            iout += 3;\n            count = 0;\n        }\n    }\n\n    return output;\n}\n```\n:::\n\n\n\n\n\n## The end result\n\nNow that we have both `decode()` and `encode()` implemented. We have a fully functioning\nbase64 encoder/decoder implemented in Zig. Here is an usage example of our\n`Base64` struct with the `encode()` and `decode()` methods that we have implemented.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar memory_buffer: [1000]u8 = undefined;\nvar fba = std.heap.FixedBufferAllocator.init(\n    &memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst text = \"Testing some more stuff\";\nconst etext = \"VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=\";\nconst base64 = Base64.init();\nconst encoded_text = try base64.encode(\n    allocator, text\n);\nconst decoded_text = try base64.decode(\n    allocator, etext\n);\ntry stdout.print(\n    \"Encoded text: {s}\\n\", .{encoded_text}\n);\ntry stdout.print(\n    \"Decoded text: {s}\\n\", .{decoded_text}\n);\n```\n:::\n\n\n\n\n```\nEncoded text: VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=\nDecoded text: Testing some more stuff\n```\n\nYou can also see the full source code at once, by visiting the official repository of this book[^repo].\nMore precisely inside the `ZigExamples` folder[^zig-base64-algo].\n\n[^repo]: <https://github.com/pedropark99/zig-book>\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 1 - Building a base64 encoder/decoder {#sec-base64}\n\nAs our first small project, I want to implement a base64 encoder/decoder with you.\nBase64 is an encoding system which translates binary data to text.\nA big chunk of the web uses base64 to deliver binary data to systems\nthat can only read text data.\n\nThe most common example of a modern use case for base64 is essentially any email system,\nlike GMail, Outlook, etc. Because email systems normally use\nthe Simple Mail Transfer Protocol (SMTP), which is a web protocol\nthat supports only text data. So, if you need, for any reason, to\nsend a binary file (like for example, a PDF, or an Excel file) as\nan attachment in your email, these binary files are normally\nconverted to base64, before they are included in the SMTP message.\nSo, the base64 encoding is largely used in these email systems to include\nbinary data into the SMTP message.\n\n\n\n\n\n\n## How the base64 algorithm work?\n\nBut how exactly does the algorithm behind the base64 encoding work? Let's discuss that. First, I will\nexplain the base64 scale, which is the 64-character scale that is the basis for\nthe base64 encoding system.\n\nAfter that, I explain the algorithm behind a base64 encoder, which is the part of the algorithm that is responsible for encoding messages\ninto the base64 encoding system. Then, after that, I explain the algorithm behind a base64 decoder, which is\nthe part of the algorithm that is responsible for translating base64 messages back into their original meaning.\n\nIf you are unsure about the differences between an \"encoder\" and a \"decoder\",\ntake a look at @sec-encode-vs-decode.\n\n\n### The base64 scale {#sec-base64-scale}\n\nThe base64 encoding system is based on a scale that goes from 0 to 63 (hence the name).\nEach index in this scale is represented by a character (it's a scale of 64 characters).\nSo, in order to convert some binary data, to the base64 encoding, we need to convert each binary number to the corresponding\ncharacter in this \"scale of 64 characters\".\n\nThe base64 scale starts with all ASCII uppercase letters (A to Z) which represents\nthe first 25 indexes in this scale (0 to 25). After that, we have all ASCII lowercase letters\n(a to z), which represents the range 26 to 51 in the scale. After that, we\nhave the one digit numbers (0 to 9), which represents the indexes from 52 to 61 in the scale.\nFinally, the last two indexes in the scale (62 and 63) are represented by the characters `+` and `/`,\nrespectively.\n\nThese are the 64 characters that compose the base64 scale. The equal sign character (`=`) is not part of the scale itself,\nbut it is a special character in the base64 encoding system. This character is used solely as a suffix, to mark the end of the character sequence,\nor, to mark the end of meaningful characters in the sequence.\n\nThe bullet points below summarises the base64 scale:\n\n- range 0 to 25 is represented by: ASCII uppercase letters `-> [A-Z]`;\n- range 26 to 51 is represented by: ASCII lowercase letters `-> [a-z]`;\n- range 52 to 61 is represented by: one digit numbers `-> [0-9]`;\n- index 62 and 63 are represented by the characters `+` and `/`, respectively;\n- the character `=` represents the end of meaningful characters in the sequence;\n\n\n\n\n### Creating the scale as a lookup table {#sec-base64-table}\n\nThe best way to represent this scale in code, is to represent it as a *lookup table*.\nLookup tables are a classic strategy in computer science to speed up calculations. The basic idea\nis to replace a runtime calculation (which can take a long time to be done) with a basic array indexing\noperation.\n\nInstead of calculating the results everytime you need them, you calculate all possible results at once, and then, you store them in an array\n(which behaves lake a \"table\"). Then, every time you need to use one of the characters in the base64 scale, instead of\nusing many resources to calculate the exact character to be used, you simply retrieve this character\nfrom the array where you stored all the possible characters in the base64 scale.\nWe retrieve the character that we need directly from memory.\n\nWe can start building a Zig struct to store our base64 decoder/encoder logic.\nWe start with the `Base64` struct below. For now, we only have one single data member in this\nstruct, i.e., the member `_table`, which represents our lookup table. We also have an `init()` method,\nto create a new instance of a `Base64` object, and, a `_char_at()` method, which is a\n\"get character at index $x$\" type of function.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Base64 = struct {\n    _table: *const [64]u8,\n\n    pub fn init() Base64 {\n        const upper = \"ABCDEFGHIJKLMNOPQRSTUVWXYZ\";\n        const lower = \"abcdefghijklmnopqrstuvwxyz\";\n        const numbers_symb = \"0123456789+/\";\n        return Base64{\n            ._table = upper ++ lower ++ numbers_symb,\n        };\n    }\n\n    pub fn _char_at(self: Base64, index: usize) u8 {\n        return self._table[index];\n    }\n};\n```\n:::\n\n\n\n\n\nIn other words, the `_char_at()` method is responsible for getting the character in the lookup\ntable (i.e., the `_table` struct data member) that corresponds to a particular index in the\n\"base64 scale\". So, in the example below, we know that the character that corresponds to the\nindex 28 in the \"base64 scale\" is the character \"c\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst base64 = Base64.init();\ntry stdout.print(\n    \"Character at index 28: {c}\\n\",\n    .{base64._char_at(28)}\n);\n```\n:::\n\n\n\n\n```\nCharacter at index 28: c\n```\n\n\n\n### A base64 encoder {#sec-base64-encoder-algo}\n\nThe algorithm behind a base64 encoder usually works on a window of 3 bytes. Because each byte has\n8 bits, so, 3 bytes forms a set of $8 \\times 3 = 24$ bits. This is desirable for the base64 algorithm, because\n24 bits is divisible by 6, which forms $24 / 6 = 4$ groups of 6 bits each.\n\nTherefore, the base64 algorithm works by converting 3 bytes at a time\ninto 4 characters from the base64 scale. It keeps iterating through the input string,\n3 bytes at a time, and converting them into the base64 scale, producing 4 characters\nper iteration. It keeps iterating, and producing these \"new characters\"\nuntil it hits the end of the input string.\n\nNow you may think, what if you have a particular string that has a number of bytes\nthat is not divisible by 3 - what happens? For example, if you have a string\nthat contains only two characters/bytes, such as \"Hi\". How would the algorithm\nbehave in such situation? You find the answer in @fig-base64-algo1.\nYou can see in @fig-base64-algo1 that the string \"Hi\", when converted to base64,\nbecomes the string \"SGk=\":\n\n![The logic behind a base64 encoder](./../Figures/base64-encoder-flow.png){#fig-base64-algo1}\n\nTaking the string \"Hi\" as an example, we have 2 bytes, or, 16 bits in total. So, we lack a full byte (8 bits)\nto complete the window of 24 bits that the base64 algorithm likes to work on. The first thing that\nthe algorithm does, is to check how to divide the input bytes into groups of 6 bits.\n\nIf the algorithm notices that there is a group of 6 bits that it's not complete, meaning that, this group contains $nbits$, where $0 < nbits < 6$,\n\nthe algorithm simply adds extra zeros in this group to fill the space that it needs.\nThat is why in @fig-base64-algo1, in the third group after the 6-bit transformation,\n2 extra zeros were added to fill the gap.\n\nWhen we have a 6-bit group that is not completely full, like the third group, extra zeros\nare added to fill the gap. But what about when an entire 6-bit group is empty, or, it\nsimply doesn't exist? This is the case of the fourth 6-bit group exposed at\n@fig-base64-algo1.\n\nThis fourth group is necessary, because the algorithm works on 4 groups of 6 bits.\nBut the input string does not have enough bytes to create a fourth 6-bit group.\nEvery time this happens, where an entire group of 6 bits is empty,\nthis group becomes a \"padding group\". Every \"padding group\" is mapped to\nthe character `=` (equal sign), which represents \"null\", or, the end\nof meaningful characters in the sequence. Hence, everytime that the algorithm produces a\n\"padding group\", this group is automatically mapped to `=`.\n\nAs another example, if you give the string \"0\" as input to a base64 encoder, this string is\ntranslated into the base64 sequence \"MA==\".\nThe character \"0\" is, in binary, the sequence `00110000`[^zero-note]. So, with the 6-bit transformation\nexposed in @fig-base64-algo1, this single character would produce these two 6-bit groups: `001100`, `000000`.\nThe remaining two 6-bit groups become \"padding groups\". That is why the last\ntwo characters in the output sequence (MA==) are `==`.\n\n\n[^zero-note]: Notice that, the character \"0\" is different than the actual number 0, which is simply zero in binary.\n\n### A base64 decoder {#sec-base64-decoder-algo}\n\nThe algorithm behind a base64 decoder is essentially the inverse process of a base64 encoder.\nA base64 decoder needs to translate base64 messages back into their original meaning,\ni.e., into the original sequence of binary data.\n\nA base64 decoder usually works on a window of 4 bytes. Because it wants to convert these 4 bytes\nback into the original sequence of 3 bytes, that was converted into 4 groups of 6 bits by the\nbase64 encoder. Remember, in a base64 decoder we are essentially reverting the process made\nby the base64 encoder.\n\nEach byte in the input string (the base64 encoded string) normally contributes to re-create\ntwo different bytes in the output (the original binary data).\nIn other words, each byte that comes out of a base64 decoder is created by transforming merging two different\nbytes in the input together. You can visualize this relationship in @fig-base64-algo2:\n\n![The logic behind a base64 decoder](./../Figures/base64-decoder-flow.png){#fig-base64-algo2}\n\nThe exact transformations, or, the exact steps applied to each byte from the input to transform them\ninto the bytes of the output, are a bit tricky to visualize in a figure like this. Because of that, I have\nsummarized these transformations as \"Some bit shifting and additions ...\" in the figure. These transformations\nwill be described in depth later.\n\nBesides that, if you look again in @fig-base64-algo2, you will notice that the character `=` was completely\nignored by the algorithm. Remember, this is just a special character that marks the end of meaningful characters\nin the base64 sequence. So, every `=` character in a base64 encoded sequence should be ignored by a base64 decoder.\n\n\n## Difference between encode and decode {#sec-encode-vs-decode}\n\nIf you don't have any previous experience with base64, you might not understand the differences\nbetween \"encode\" and \"decode\". Essentially, the terms \"encode\" and \"decode\" here\nhave the exact same meaning as they have in the field of encryption (i.e., they mean the same thing as \"encode\" and \"decode\" in hashing\nalgorithms, like the MD5 algorithm).\n\nThus, \"encode\" means that we want to encode, or, in other words, we want to translate some message into\nthe base64 encoding system. We want to produce the sequence of base64 characters that represent this\noriginal message in the base64 encoding system.\n\nIn contrast, \"decode\" represents the inverse process.\nWe want to decode, or, in other words, translate a base64 message back to its original content.\nSo, in this process we get a sequence of base64 characters as input, and produce as output,\nthe binary data that is represented by this sequence of base64 characters.\n\nAny base64 library is normally composed of these two parts: 1) the encoder, which is a function that encodes\n(i.e., it converts) any sequence of binary data into a sequence of base64 characters; 2) the decoder, which is a function\nthat converts a sequence of base64 characters back into the original sequence of binary data.\n\n\n\n## Calculating the size of the output {#sec-base64-length-out}\n\nOne task that we need to do is to calculate how much space we need to reserve for the\noutput, both of the encoder and decoder. This is simple math, and can be done easily in Zig\nbecause every array has its length (its number of elements) easily accesible by consulting\nthe `.len` property of the array.\n\nFor the encoder, the logic is the following: for each 3 bytes that we find in the input,\n4 new bytes are created in the output. So, we take the number of bytes in the input, divide it\nby 3, use a ceiling function, then, we multiply the result by 4. That way, we get the total\nnumber of bytes that will be produced by the encoder in its output.\n\nThe `_calc_encode_length()` function below encapsulates this logic.\nInside this function, we take the length of the input array,\nwe divide it by 3, and apply a ceil operation over the result by using the\n`divCeil()` function from the Zig Standard Library. Lastly, we multiply\nthe end result by 4 to get the answer we need.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_encode_length(input: []const u8) !usize {\n    if (input.len < 3) {\n        const n_output: usize = 4;\n        return n_output;\n    }\n    const n_output: usize = try std.math.divCeil(\n        usize, input.len, 3\n    );\n    return n_output * 4;\n}\n```\n:::\n\n\n\n\n\nAlso, you might have notice that, if the input length is less than 3 bytes, then, the output length of the encoder is\nalways 4 bytes. This is the case for every input with less than 3 bytes, because, as I described in @sec-base64-encoder-algo,\nthe algorithm always produces enough \"padding-groups\" in the end result, to complete the 4 bytes window.\n\nNow, for the decoder, we just need to apply the inverse logic: for each 4 bytes in the input, 3 bytes\nwill be produced in the output of the decoder. I mean, this is roughly true, because we also need to\ntake the `=` character into account, which is always ignored by the decoder, as we described in @sec-base64-decoder-algo, and,\nin @fig-base64-algo2. But we can ignore this fact for now, just to keep things simple.\n\nThe function `_calc_decode_length()` exposed below summarizes this logic that we described. It's very similar\nto the function `_calc_encode_length()`. Only the division part is twisted, and also, in the special\ncase where we have less than 4 bytes in the input to work on. Also notice that this time, we apply\na floor operation over the output of the division, by using the `divFloor()`\nfunction (instead of a ceiling operation with `divCeil()`).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_decode_length(input: []const u8) !usize {\n    if (input.len < 4) {\n        const n_output: usize = 3;\n        return n_output;\n    }\n    const n_output: usize = try std.math.divFloor(\n        usize, input.len, 4\n    );\n    return n_output * 3;\n}\n```\n:::\n\n\n\n\n\n## Building the encoder logic {#sec-encoder-logic}\n\nIn this section, we can start building the logic behind the `encode()` function, which\nwill be responsible for encoding messages into the base64 encoding system.\nIf you are an anxious person, and you want to see now the full source code of the implementation\nfor this base64 encoder/decoder, you can find it at the `ZigExamples` folder in the official repository of\nthis book[^zig-base64-algo].\n\n[^zig-base64-algo]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/base64/base64_basic.zig>.\n\n\n\n### The 6-bit transformation {#sec-6bit-transf}\n\nThe 6-bit transformation presented in @fig-base64-algo1 is the core part of the base64 encoder algorithm.\nBy understanding how this transformation is made in code, the rest of the algorithm becomes much simpler\nto comprehend.\n\nIn essence, this 6-bit transformation is made with the help of bitwise operators.\nBitwise operators are essential to any type of low-level operation that is done at the bit-level. For the specific case of the base64 algorithm,\nthe operators *bif shift to the left* (`<<`), *bit shift to the right* (`>>`), and the *bitwise and* (`&`) are used. They\nare the core solution for the 6-bit transformation.\n\nThere are 3 different scenarios that we need to take into account in this transformation. First, is the perfect scenario,\nwhere we have the perfect window of 3 bytes to work on. Second, we have the scenario where we have a window of only\ntwo bytes to work with. And last, we have the scenario where we have a window of one single byte.\n\nIn each of these 3 scenarios, the 6-bit transformation works a bit differently. To make the explanation\neasier, I will use the variable `output` to refer to the bytes in the output of the base64 encoder,\nand the variable `input` to refer to the bytes in the input of the encoder.\n\n\nSo, if you have the perfect window of 3 bytes, these are steps for the 6-bit transformation:\n\n1. `output[0]` is produced by moving the bits from `input[0]` two positions to the right.\n1. `output[1]` is produced by summing two components. First, take the last two bits from `input[0]`, then, move them four positions to the left. Second, move the bits from `input[1]` four positions to the right. Sum these two components.\n1. `output[2]` is produced by summing two components. First, take the last four bits from `input[1]`, then, move them two positions to the left. Second, move the bits from `input[2]` six positions to the right. Sum these two components.\n1. `output[3]` is produced by taking the last six bits from `input[2]`.\n\n\nThis is the perfect scenario, where we have a full window of 3 bytes to work on.\nJust to make things as clear as possible, the @fig-encoder-bitshift demonstrates visually how\nthe step 2 mentioned above works. So the 2nd byte in the `output` of the encoder, is made by taking the 1st byte (dark purple)\nand the 2nd byte (orange) from the input. You can see that, at the end of the process, we get a new\nbyte that contains the last 2 bits from the 1st byte in the `input`, and the first 4 bits\nfrom the 2nd byte in the `input`.\n\n![How the 2nd byte in the output of the encoder is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input.](../Figures/base64-encoder-bit-shift.png){#fig-encoder-bitshift}\n\nOn the other hand, we must be prepared for the instances where we do not have the perfect window of 3 bytes.\nIf you have a window of 2 bytes, then, the steps 3 and 4, which produces the bytes `output[2]` and `output[3]`, change a little bit,\nand they become:\n\n- `output[2]` is produced by taking the last 4 bits from `input[1]`, then, move them two positions to the left.\n- `output[3]` is the character `'='`.\n\n\nFinally, if you have a window of a single byte, then, the steps 2 to 4, which produces the bytes `output[1]`, `output[2]` and `output[3]` change,\nbecoming:\n\n- `output[1]` is produced by taking the last two bits from `input[0]`, then, move them four positions to the left.\n- `output[2]` and `output[3]` are the character `=`.\n\n\nIf these bullet points were a bit confusing for you, you may find the @tbl-transf-6bit more intuitive.\nThis table unifies all this logic into a simple table. Notice that\nthis table also provides the exact expression in Zig that creates the corresponding\nbyte in the output.\n\n\n::: {#tbl-transf-6bit}\n\n| Number of bytes in the window | Byte index in the output | In code                                    |\n|-------------------------------|--------------------------|--------------------------------------------|\n| 3                             | 0                        | input[0] >> 2                              |\n| 3                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 3                             | 2                        | ((input[1] & 0x0f) << 2) + (input[2] >> 6) |\n| 3                             | 3                        | input[2] & 0x3f                            |\n| 2                             | 0                        | input[0] >> 2                              |\n| 2                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 2                             | 2                        | ((input[1] & 0x0f) << 2)                   |\n| 2                             | 3                        | '='                                        |\n| 1                             | 0                        | input[0] >> 2                              |\n| 1                             | 1                        | ((input[0] & 0x03) << 4)                   |\n| 1                             | 2                        | '='                                        |\n| 1                             | 3                        | '='                                        |\n\n: How the 6-bit transformation translates into code in different window settings.\n\n:::\n\n\n\n\n\n\n### Bit-shifting in Zig\n\nBit-shifting in Zig works similarly to bit-shifting in C.\nAll bitwise operators that exist in C are available in Zig.\nHere, in the base64 encoder algorithm, they are essential\nto produce the result we want.\n\nFor those who are not familiar with these operators, they are\noperators that operates at the bit-level of your values.\nThis means that these operators takes the bits that form the value\nyou have, and change them in some way. This ultimately also changes\nthe value itself, because the binary representation of this value\nchanges.\n\nWe have already seen in @fig-encoder-bitshift the effect produced by a bit-shift.\nBut let's use the first byte in the output of the base64 encoder as another example of what\nbit-shifting means. This is the easiest byte of the 4 bytes in the output\nto build. Because we only need to move the bits from the first byte in the input two positions to the right,\nwith the *bit shift to the right* (`>>`) operator.\n\nIf we take the string \"Hi\" that we used in @fig-base64-algo1 as an example, the first byte in\nthis string is \"H\", which is the sequence `01001000` in binary.\nIf we move the bits of this byte, two places to the right, we get the sequence `00010010` as result.\nThis binary sequence is the value `18` in decimal, and also, the value `0x12` in hexadecimal.\nNotice that the first 6 bits of \"H\" were moved to the end of the byte.\nWith this operation, we get the first byte of the output.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const input = \"Hi\";\n    try stdout.print(\"{d}\\n\", .{input[0] >> 2});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n18\n```\n\n\n:::\n:::\n\n\n\n\nIf you recall @fig-base64-algo1, the first byte present in the output should\nbe equivalent to the 6-bit group `010010`. Although being visually different, the\nsequences `010010` and `00010010` are semantically equal. They mean the same thing.\nThey both represent the number 18 in decimal, and the value `0x12` in hexadecimal.\n\nSo, don't take the \"6-bit group\" factor so seriously. We do not need necessarily to\nget a 6-bit sequence as result. As long as the meaning of the 8-bit sequence we get is the same\nof the 6-bit sequence, we are in the clear.\n\n\n\n### Selecting specific bits with the `&` operator\n\nIf you comeback to @sec-6bit-transf, you will see that, in order to produce\nthe second and third bytes in the output, we need to select specific\nbits from the first and second bytes in the input string. But how\ncan we do that? The answer relies on the *bitwise and* (`&`) operator.\n\nThe @fig-encoder-bitshift already showed you what effect this `&` operator\nproduces in the bits of its operands. But let's make a clear description of it.\n\nIn summary, the `&` operator performs a logical conjunction operation\nbetween the bits of its operands. In more details, the operator `&`\ncompares each bit of the first operand to the corresponding bit of the second operand.\nIf both bits are 1, the corresponding result bit is set to 1.\nOtherwise, the corresponding result bit is set to 0 [@microsoftbitwiseand].\n\nSo, if we apply this operator to the binary sequences `1000100` and `00001101`\nthe result of this operation is the binary sequence `00000100`. Because only\nat the sixth position in both binary sequences we had a 1 value. So any\nposition where we do not have both binary sequences setted to 1, we get\na 0 bit in the resulting binary sequence.\n\nWe lose information about the original bit values\nfrom both sequences in this case. Because we no longer know\nif this 0 bit in the resulting binary sequence was produced by\ncombining 0 with 0, or 1 with 0, or 0 with 1.\n\nAs an example, suppose you have the binary sequence `10010111`, which is the number 151 in decimal. How\ncan we get a new binary sequence which contains only the third and\nfourth bits of this sequence?\n\nWe just need to combine this sequence with `00110000` (is `0x30` in hexadecimal) using the `&` operator.\nNotice that only the third and fourth positions in this binary sequence is setted to 1. As a consequence, only the\nthird and fourth values of both binary sequences are potentially preserved in the output. All the remaining positions\nare setted to zero in the output sequence, which is `00010000` (is the number 16 in decimal).\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const bits = 0b10010111;\n    try stdout.print(\"{d}\\n\", .{bits & 0b00110000});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n16\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Allocating space for the output\n\nAs I described in @sec-stack, to store an object in the stack,\nthis object needs to have a known and fixed length at compile-time. This is an important\nlimitation for our base64 encoder/decoder case. Because the size of\nthe output (from both the encoder and decoder) depends\ndirectly on the size of the input.\n\nHaving this in mind, we cannot know at compile time which is\nthe size of the output for both the encoder and decoder.\nSo, if we can't know the size of the output at compile time,\nthis means that we cannot store the output for both the encoder\nand decoder in the stack.\n\nConsequently, we need to store this output on the heap,\nand, as I commented in @sec-heap, we can only\nstore objects in the heap by using allocator objects.\nSo, one the arguments to both the `encode()` and `decode()`\nfunctions, needs to be an allocator object, because\nwe know for sure that, at some point inside the body of these\nfunctions, we need to allocate space on the heap to\nstore the output of these functions.\n\nThat is why, both the `encode()` and `decode()` functions that I\npresent in this book, have an argument called `allocator`,\nwhich receives a allocator object as input, identified by\nthe type `std.mem.Allocator` from the Zig Standard Library.\n\n\n\n### Writing the `encode()` function\n\nNow that we have a basic understanding on how the bitwise operators work, and how\nexactly they help us to achieve the result we want to achieve. We can now encapsulate\nall the logic that we have described in @fig-base64-algo1 and @tbl-transf-6bit into a nice\nfunction that we can add to our `Base64` struct definition, that we started in @sec-base64-table.\n\nYou can find the `encode()` function below. Notice that the first argument of this function,\nis the `Base64` struct itself. Therefore, this argument clearly signals\nthat this function is a method from the `Base64` struct.\n\nBecause the `encode()` function itself is fairly long,\nI intentionally omitted the `Base64` struct definition in this source code,\njust for brevity reasons. So, just remember that this function is a public function (or a public method) from the\n`Base64` struct.\n\nFurthermore, this `encode()` function has two other arguments:\n\n1. `input` is the input sequence of characters that you want to encode in base64;\n1. `allocator` is an allocator object to use in the necessary memory allocations.\n\nI described everything you need to know about allocator objects in @sec-allocators.\nSo, if you are not familiar with them, I highly recommend you to comeback to\nthat section, and read it.\nBy looking at the `encode()` function, you will see that we use this\nallocator object to allocate enough memory to store the output of\nthe encoding process.\n\nThe main for loop in the function is responsible for iterating through the entire input string.\nIn every iteration, we use a `count` variable to count how many iterations we had at the\nmoment. When `count` reaches 3, then, we try to encode the 3 characters (or bytes) that we have accumulated\nin the temporary buffer object (`buf`).\n\nAfter encoding these 3 characters and storing the result in the `output` variable, we reset\nthe `count` variable to zero, and start to count again on the next iteration of the loop.\nIf the loop hits the end of the string, and, the `count` variable is less than 3, then, it means that\nthe temporary buffer contains the last 1 or 2 bytes from the input.\nThat is why we have two `if` statements after the for loop. To deal which each possible case.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn encode(self: Base64,\n              allocator: std.mem.Allocator,\n              input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n\n    const n_out = try _calc_encode_length(input);\n    var out = try allocator.alloc(u8, n_out);\n    var buf = [3]u8{ 0, 0, 0 };\n    var count: u8 = 0;\n    var iout: u64 = 0;\n\n    for (input, 0..) |_, i| {\n        buf[count] = input[i];\n        count += 1;\n        if (count == 3) {\n            out[iout] = self._char_at(buf[0] >> 2);\n            out[iout + 1] = self._char_at(\n                ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n            );\n            out[iout + 2] = self._char_at(\n                ((buf[1] & 0x0f) << 2) + (buf[2] >> 6)\n            );\n            out[iout + 3] = self._char_at(buf[2] & 0x3f);\n            iout += 4;\n            count = 0;\n        }\n    }\n\n    if (count == 1) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            (buf[0] & 0x03) << 4\n        );\n        out[iout + 2] = '=';\n        out[iout + 3] = '=';\n    }\n\n    if (count == 2) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n        );\n        out[iout + 2] = self._char_at(\n            (buf[1] & 0x0f) << 2\n        );\n        out[iout + 3] = '=';\n        iout += 4;\n    }\n\n    return out;\n}\n```\n:::\n\n\n\n\n\n\n## Building the decoder logic {#sec-decoder-logic}\n\nNow, we can focus on writing the base64 decoder logic. Remember from @fig-base64-algo2 that,\na base64 decoder does the inverse process of an encoder. So, all we need to do, is to\nwrite a `decode()` function that performs the inverse process that I exposed in @sec-encoder-logic.\n\n\n### Mapping base64 characters to their indexes {#sec-map-base64-index}\n\nOne thing that we need to do, in order to decode a base64-encoded message, is to calculate\nthe index in the base64 scale of every base64 character that we encounter in the decoder input.\n\nIn other words, the decoder receives as input, a sequence of base64 characters. We need\nto translate this sequence of characters into a sequence of indexes. These indexes\nare the index of each character in the base64 scale. This way, we get the value/byte\nthat was calculated in the 6-bit transformation step of the encoder process.\n\nThere are probably better/faster ways to calculate this, especially using a \"divide and conquer\"\ntype of strategy. But for now, I am satisfied with a simple and \"brute force\" type of strategy.\nThe `_char_index()` function below contains this strategy.\n\nWe are essentially looping through the *lookup table* with the base64 scale,\nand comparing the character we got with each character in the base64 scale.\nIf these characters match, then, we return the index of this character in the\nbase64 scale as the result.\n\nNotice that, if the input character is `'='`, the function returns the index 64, which is\n\"out of range\" in the scale. But, as I described in @sec-base64-scale,\nthe character `'='` does not belong to the base64 scale itself.\nIt's a special and meaningless character in base64.\n\nAlso notice that this `_char_index()` function is a method from our `Base64` struct,\nbecause of the `self` argument. Again, I have omitted the `Base64` struct definition in this example\nfor brevity reasons.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn _char_index(self: Base64, char: u8) u8 {\n    if (char == '=')\n        return 64;\n    var index: u8 = 0;\n    for (0..63) |i| {\n        if (self._char_at(i) == char)\n            break;\n        index += 1;\n    }\n\n    return index;\n}\n```\n:::\n\n\n\n\n\n\n### The 6-bit transformation\n\nOnce again, the core part of the algorithm is the 6-bit transformation.\nIf we understand the necessary steps to perform this transformation, the rest\nof the algorithm becomes much easier.\n\nFirst of all, before we actually go to the 6-bit transformation,\nwe need to make sure that we use `_char_index()` to convert the sequence of base64 characters\ninto a sequence of indexes. So the snippet below is important for the job that will be done.\nThe result of `_char_index()` is stored in a temporary buffer, and this temporary buffer\nis what we are going to use in the 6-bit transformation, instead of the actual `input` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (0..input.len) |i| {\n    buf[i] = self._char_index(input[i]);\n}\n```\n:::\n\n\n\n\nNow, instead of producing 4 bytes (or 4 characters) as output per each window of 3 characters in the input,\na base64 decoder produces 3 bytes (or 3 characters) as output per each window of 4 characters in the input.\nOnce again, is the inverse process.\n\nSo, the steps to produce the 3 bytes in the output are:\n\n1. `output[0]` is produced by summing two components. First, move the bits from `buf[0]` two positions to the left. Second, move the bits from `buf[1]` 4 positions to the right. Then, sum these two components.\n1. `output[1]` is produced by summing two components. First, move the bits from `buf[1]` four positions to the left. Second, move the bits from `buf[2]` 2 positions to the right. Then, sum these two components.\n1. `output[2]` is produced by summing two components. First, move the bits from `buf[2]` six positions to the left. Then, you sum the result with `buf[3]`.\n\n\nBefore we continue, let's try to visualize how these transformations make the original bytes that we had\nbefore the encoding process. First, think back to the 6-bit transformation performed by the encoder exposed in @sec-encoder-logic.\nThe first byte in the output of the encoder is produced by moving the bits in the first byte of the input two positions to the right.\n\nIf for example the first byte in the input of the encoder was the sequence `ABCDEFGH`, then, the first byte in the output of the encoder would be\n`00ABCDEF` (this sequence would be the first byte in the input of the decoder). Now, if the second byte in the input of the encoder was the sequence\n`IJKLMNOP`, then, the second byte in the encoder output would be `00GHIJKL` (as we demonstrated in @fig-encoder-bitshift).\n\nHence, if the sequences `00ABCDEF` and `00GHIJKL` are the first and second bytes, respectively, in the input of the decoder, the\n@fig-decoder-bitshift demonstrates visually how these two bytes are transformed into the first byte of the output of the decoder.\nNotice that the output byte is the sequence `ABCDEFGH`, which is the original byte from the input of the encoder.\n\n![How the 1st byte in the decoder output is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input](../Figures/base64-decoder-bit-shift.png){#fig-decoder-bitshift}\n\nThe @tbl-6bit-decode presents how the three steps described earlier translate into Zig code:\n\n\n\n::: {#tbl-6bit-decode}\n\n| Byte index in the output | In code                       |\n|--------------------------|-------------------------------|\n| 0                        | (buf[0] << 2) + (buf[1] >> 4) |\n| 1                        | (buf[1] << 4) + (buf[2] >> 2) |\n| 2                        | (buf[2] << 6) + buf[3]        |\n\n: The necessary steps for the 6-transformation in the decode process.\n\n\n:::\n\n\n\n\n\n\n\n### Writing the `decode()` function\n\nThe `decode()` function below contains the entire decoding process.\nWe first calculate the size of the output, with\n`_calc_decode_length()`, then, we allocate enough memory for this output with\nthe allocator object.\n\nThree temporary variables are created: 1) `count`, to hold the window count\nin each iteration of the for loop; 2) `iout`, to hold the current index in the output;\n3) `buf`, which is the temporary buffer that holds the base64 indexes to be\nconverted through the 6-bit transformation.\n\nThen, in each iteration of the for loop we fill the temporary buffer with the current\nwindow of bytes. When `count` hits the number 4, then, we have a full window of\nindexes in `buf` to be converted, and then, we apply the 6-bit transformation\nover the temporary buffer.\n\nNotice that we check if the indexes 2 and 3 in the temporary buffer are the number 64, which, if you recall\nfrom @sec-map-base64-index, is when the `_calc_index()` function receives a `'='` character\nas input. So, if these indexes are equal to the number 64, the `decode()` function knows\nthat it can simply ignore these indexes. They are not converted because, as I described before,\nthe character `'='` has no meaning, despite being the end of meaningful characters in the sequence.\nSo we can safely ignore them when they appear in the sequence.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn decode(self: Base64,\n          allocator: std.mem.Allocator,\n          input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n    const n_output = try _calc_decode_length(input);\n    var output = try allocator.alloc(u8, n_output);\n    var count: u8 = 0;\n    var iout: u64 = 0;\n    var buf = [4]u8{ 0, 0, 0, 0 };\n\n    for (0..input.len) |i| {\n        buf[count] = self._char_index(input[i]);\n        count += 1;\n        if (count == 4) {\n            output[iout] = (buf[0] << 2) + (buf[1] >> 4);\n            if (buf[2] != 64) {\n                output[iout + 1] = (buf[1] << 4) + (buf[2] >> 2);\n            }\n            if (buf[3] != 64) {\n                output[iout + 2] = (buf[2] << 6) + buf[3];\n            }\n            iout += 3;\n            count = 0;\n        }\n    }\n\n    return output;\n}\n```\n:::\n\n\n\n\n\n## The end result\n\nNow that we have both `decode()` and `encode()` implemented. We have a fully functioning\nbase64 encoder/decoder implemented in Zig. Here is an usage example of our\n`Base64` struct with the `encode()` and `decode()` methods that we have implemented.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar memory_buffer: [1000]u8 = undefined;\nvar fba = std.heap.FixedBufferAllocator.init(\n    &memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst text = \"Testing some more stuff\";\nconst etext = \"VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=\";\nconst base64 = Base64.init();\nconst encoded_text = try base64.encode(\n    allocator, text\n);\nconst decoded_text = try base64.decode(\n    allocator, etext\n);\ntry stdout.print(\n    \"Encoded text: {s}\\n\", .{encoded_text}\n);\ntry stdout.print(\n    \"Decoded text: {s}\\n\", .{decoded_text}\n);\n```\n:::\n\n\n\n\n```\nEncoded text: VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=\nDecoded text: Testing some more stuff\n```\n\nYou can also see the full source code at once, by visiting the official repository of this book[^repo].\nMore precisely inside the `ZigExamples` folder[^zig-base64-algo].\n\n[^repo]: <https://github.com/pedropark99/zig-book>\n",
+    "supporting": [
+      "01-base64_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/01-memory/execute-results/html.json b/_freeze/Chapters/01-memory/execute-results/html.json
index eec3bc03..269c7d87 100644
--- a/_freeze/Chapters/01-memory/execute-results/html.json
+++ b/_freeze/Chapters/01-memory/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "6d9a92b4e90ed5229b91d3e433ba3d4c",
+  "hash": "55899a376e1db53689b78790e55a518d",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Memory and Allocators\n\n\nIn this chapter, we will talk about memory. How does Zig control memory? What\ncommon tools are used? Are there any important aspects that make memory\ndifferent/special in Zig? You will find the answers here.\n\nComputers fundamentally rely on memory to function. This memory acts as a temporary storage\nspace for the data and values generated during computations. Without memory, the core\nconcepts of \"variables\" and \"objects\" in programming languages would be impossible.\n\n\n\n\n## Memory spaces\n\nEvery object that you create in your Zig source code needs to be stored somewhere,\nin your computer's memory. Depending on where and how you define your object, Zig\nwill use a different \"memory space\", or a different\ntype of memory to store this object.\n\nEach type of memory normally serves for different purposes.\nIn Zig, there are 3 types of memory (or 3 different memory spaces) that we care about. They are:\n\n- Global data register (or the \"global data section\");\n- Stack;\n- Heap;\n\n\n### Compile-time known versus runtime known {#sec-compile-time}\n\nOne strategy that Zig uses to decide where it will store each object that you declare, is by looking\nat the value of this particular object. More specifically, by investigating if this value is\nknown at \"compile-time\" or at \"runtime\".\n\nWhen you write a program in Zig, the values of some of the objects that you write in your program are *known\nat compile time*. Meaning that, when you compile your Zig source code, during the compilation process,\nthe `zig` compiler can figure out the exact value of a particular object\nthat exists in your source code.\nKnowing the length (or the size) of each object is also important. So the length (or the size) of each object that you write in your program is,\nin some cases, *known at compile time*.\n\nThe `zig` compiler cares more about knowing the length (or the size) of a particular object\n, than to know its actual value. But, if the `zig` compiler knows the value of the object, then, it\nautomatically knows the size of this object. Because it can simply calculate the\nsize of the object by looking at the size of the value.\n\nTherefore, the priority for the `zig` compiler is to discover the size of each object in your source code.\nIf the value of the object in question is known at compile-time, then, the `zig` compiler\nautomatically knows the size/length of this object. But if the value of this object is not\nknown at compile-time, then, the size of this object is only known at compile-time if,\nand only if, the type of this object has a known fixed size.\n\nIn order for a type to have a known fixed size, this type must have data members whose size is fixed.\nIf this type includes, for example, a variable sized array in it, then, this type does not have a known\nfixed size. Because this array can have any size at runtime\n(i.e. it can be an array of 2 elements, or 50 elements, or 1 thousand elements, etc.).\n\nFor example, a string object, which internally is an array of constant u8 values (`[]const u8`)\nhas a variable size. It can be a string object with 100 or 500 characters in it. If we do not\nknow at compile-time, which exact string will be stored inside this string object, then, we cannot calculate\nthe size of this string object at compile-time. So, any type, or any struct declaration that you make, that\nincludes a string data member that does not have an explicit fixed size, makes this type, or this\nnew struct that you are declaring, a type that does not have a known fixed size at compile-time.\n\nIn contrast, if the type of this struct that you are declaring, includes a data member that is an array,\nbut this array has a known fixed size, like `[60]u8` (which declares an array of 60 `u8` values), then,\nthis type, or, this struct that you are declaring, becomes a type with a known fixed size at compile-time.\nAnd because of that, in this case, the `zig` compiler does not need to know at compile-time the exact value of\nany object of this type. Since the compiler can find the necessary size to store this object by\nlooking at the size of its type.\n\n\nLet's look at an example. In the source code below, we have two constant objects (`name` and `array`) declared.\nBecause the values of these particular objects are written down, in the source code itself (`\"Pedro\"`\nand the number sequence from 1 to 4), the `zig` compiler can easily discover the values of these constant\nobjects (`name` and `array`) during the compilation process.\nThis is what \"known at compile time\" means. It refers to any object that you have in your Zig source code\nwhose value can be identified at compile time.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn input_length(input: []const u8) usize {\n    const n = input.len;\n    return n;\n}\n\npub fn main() !void {\n    const name = \"Pedro\";\n    const array = [_]u8{1, 2, 3, 4};\n    _ = name; _ = array;\n}\n```\n:::\n\n\n\n\nThe other side of the spectrum are objects whose values are not known at compile time.\nFunction arguments are a classic example of this. Because the value of each function\nargument depends on the value that you assign to this particular argument,\nwhen you call the function.\n\nFor example, the function `input_length()` contains an argument named `input`, which is an array of constant `u8` integers (`[]const u8`).\nIt is impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length\nof this particular argument. Because it is an array that do not have a fixed size specified explicitly in the argument type annotation.\n\nSo, we know that this `input` argument will be an array of `u8` integers. But we do not know at compile-time, its value, and neither its size.\nThis information is known only at runtime, which is the period of time when you program is executed.\nAs a consequence, the value of the expression `input.len` is also known only at runtime.\nThis is an intrinsic characteristic of any function. Just remember that the value of function arguments is usually not \"compile-time known\".\n\nHowever, as I mentioned earlier, what really matters to the compiler is to know the size of the object\nat compile-time, and not necessarily its value. So, although we don't know the value of the object `n`, which is the result of the expression\n`input.len`, at compile-time, we do know its size. Because the expression `input.len` always returns a value of type `usize`,\nand the type `usize` has a known fixed size.\n\n\n\n### Global data register\n\nThe global data register is a specific section of the executable of your Zig program, that is responsible\nfor storing any value that is known at compile time.\n\nEvery constant object whose value is known at compile time that you declare in your source code,\nis stored in the global data register. Also, every literal value that you write in your source code,\nsuch as the string `\"this is a string\"`, or the integer `10`, or a boolean value such as `true`,\nis also stored in the global data register.\n\nHonestly, you don't need to care much about this memory space. Because you can't control it,\nyou can't deliberately access it or use it for your own purposes.\nAlso, this memory space does not affect the logic of your program.\nIt simply exists in your program.\n\n\n### Stack vs Heap\n\nIf you are familiar with systems programming, or just low-level programming in general, you\nprobably have heard of the \"duel\" between Stack vs Heap. These are two different types of memory,\nor different memory spaces, which are both available in Zig.\n\nThese two types of memory don't actually duel with\neach other. This is a common mistake that beginners have, when seeing \"x vs y\" styles of\ntabloid headlines. These two types of memory are actually complementary to each other.\nSo, in almost every Zig program that you ever write, you will likely use a combination of both.\nI will describe each memory space in detail over the next sections. But for now, I just want to\nstablish the main difference between these two types of memory.\n\nIn essence, the stack memory is normally used to store values whose length is fixed and known\nat compile time. In contrast, the heap memory is a *dynamic* type of memory space, meaning that, it is\nused to store values whose length might grow during the execution (runtime) of your program [@jenny2022].\n\nLengths that grow during runtime are intrinsically associated with \"runtime known\" type of values.\nIn other words, if you have an object whose length might grow during runtime, then, the length\nof this object becomes not known at compile time. If the length is not known at compile-time,\nthe value of this object also becomes not known at compile-time.\nThese types of objects should be stored in the heap memory space, which is\na dynamic memory space, which can grow or shrink to fit the size of your objects.\n\n\n\n### Stack {#sec-stack}\n\nThe stack is a type of memory that uses the power of the *stack data structure*, hence the name.\nA \"stack\" is a type of *data structure* that uses a \"last in, first out\" (LIFO) mechanism to store the values\nyou give it to. I imagine you are familiar with this data structure.\nBut, if you are not, the [Wikipedia page](https://en.wikipedia.org/wiki/Stack_(abstract_data_type))[^wiki-stack]\n, or, the [Geeks For Geeks page](https://www.geeksforgeeks.org/stack-data-structure/)[^geek-stack] are both\nexcellent and easy resources to fully understand how this data structure works.\n\n[^wiki-stack]: <https://en.wikipedia.org/wiki/Stack_(abstract_data_type)>\n[^geek-stack]: <https://www.geeksforgeeks.org/stack-data-structure/>\n\nSo, the stack memory space is a type of memory that stores values using a stack data structure.\nIt adds and removes values from the memory by following a \"last in, first out\" (LIFO) principle.\n\nEvery time you make a function call in Zig, an amount of space in the stack is\nreserved for this particular function call [@jenny2022; @zigdocs].\nThe value of each function argument given to the function in this function call is stored in this\nstack space. Also, every local object that you declare inside the function scope is\nusually stored in this same stack space.\n\n\nLooking at the example below, the object `result` is a local object declared inside the scope of the `add()`\nfunction. Because of that, this object is stored inside the stack space reserved for the `add()` function.\nThe `r` object (which is declared outside of the `add()` function scope) is also stored in the stack.\nBut since it is declared in the \"outer\" scope, this object is stored in the\nstack space that belongs to this outer scope.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn add(x: u8, y: u8) u8 {\n    const result = x + y;\n    return result;\n}\n\npub fn main() !void {\n    const r = add(5, 27);\n    _ = r;\n}\n```\n:::\n\n\n\n\n\nSo, any object that you declare inside the scope of a function is always stored inside\nthe space that was reserved for that particular function in the stack memory. This\nalso counts for any object declared inside the scope of your `main()` function for example.\nAs you would expect, in this case, they\nare stored inside the stack space reserved for the `main()` function.\n\nOne very important detail about the stack memory is that **it frees itself automatically**.\nThis is very important, remember that. When objects are stored in the stack memory,\nyou don't have the work (or the responsibility) of freeing/destroying these objects.\nBecause they will be automatically destroyed once the stack space is freed at the end of the function scope.\n\nSo, once the function call returns (or ends, if you prefer to call it this way)\nthe space that was reserved in the stack is destroyed, and all of the objects that were in that space goes away with it.\nThis mechanism exists because this space, and the objects within it, are not necessary anymore,\nsince the function \"finished its business\".\nUsing the `add()` function that we exposed above as an example, it means that the object `result` is automatically\ndestroyed once the function returns.\n\n::: {.callout-important}\nLocal objects that are stored in the stack space of a function are automatically\nfreed/destroyed at the end of the function scope.\n:::\n\n\nThis same logic applies to any other special structure in Zig that has its own scope by surrounding\nit with curly braces (`{}`).\nFor loops, while loops, if else statements, etc. For example, if you declare any local\nobject in the scope of a for loop, this local object is accessible only within the scope\nof this particular for loop. Because once the scope of this for loop ends, the space in the stack\nreserved for this for loop is freed.\nThe example below demonstrates this idea.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This does not compile successfully!\nconst a = [_]u8{0, 1, 2, 3, 4};\nfor (0..a.len) |i| {\n    const index = i;\n    _ = index;\n}\n// Trying to use an object that was\n// declared in the for loop scope,\n// and that does not exist anymore.\nstd.debug.print(\"{d}\\n\", .{index});\n```\n:::\n\n\n\n\n\n\nOne important consequence of this mechanism is that, once the function returns, you can no longer access any memory\naddress that was inside the space in the stack reserved for this particular function. Because this space was\ndestroyed. This means that, if this local object is stored in the stack,\nyou cannot make a function that **returns a pointer to this object**.\n\nThink about that for a second. If all local objects in the stack are destroyed at the end of the function scope, why\nwould you even consider returning a pointer to one of these objects? This pointer is at best,\ninvalid, or, more likely, \"undefined\".\n\nConclusion, it is totally fine to write a function that returns the local object\nitself as result, because then, you return the value of that object as the result.\nBut, if this local object is stored in the stack, you should never write a function\nthat returns a pointer to this local object. Because the memory address pointed by the pointer\nno longer exists.\n\n\nSo, using again the `add()` function as an example, if you rewrite this function so that it\nreturns a pointer to the local object `result`, the `zig` compiler will actually compile\nyour program, with no warnings or errors. At first glance, it looks that this is good code\nthat works as expected. But this is a lie!\n\nIf you try to take a look at the value inside of the `r` object,\nor, if you try to use this `r` object in another expression\nor function call, then, you would have undefined behaviour, and major\nbugs in your program [@zigdocs, see \"Lifetime and Ownership\"[^life] and \"Undefined Behaviour\"[^undef] sections].\n\n[^life]: <https://ziglang.org/documentation/master/#Lifetime-and-Ownership>\n[^undef]: <https://ziglang.org/documentation/master/#Undefined-Behavior>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn add(x: u8, y: u8) *const u8 {\n    const result = x + y;\n    return &result;\n}\n\npub fn main() !void {\n    // This code compiles successfully. But it has\n    // undefined behaviour. Never do this!!!\n    // The `r` object is undefined!\n    const r = add(5, 27); _ = r;\n}\n```\n:::\n\n\n\n\nThis \"invalid pointer to stack variable\" problem is well known across many programming language communities.\nIf you try to do the same thing, for example, in a C or C++ program (i.e. returning an address to\na local object stored in the stack), you would also get undefined behaviour\nin the program.\n\n::: {.callout-important}\nIf a local object in your function is stored in the stack, you should never\nreturn a pointer to this local object from the function. Because\nthis pointer will always become undefined after the function returns, since the stack space of the function\nis destroyed at the end of its scope.\n:::\n\nBut what if you really need to use this local object in some way after your function returns?\nHow can you do this? The answer is: \"in the same way you would do if this were a C or C++ program. By returning\nan address to an object stored in the heap\". The heap memory has a much more flexible lifecycle,\nand allows you to get a valid pointer to a local object of a function that already returned\nfrom its scope.\n\n\n### Heap {#sec-heap}\n\nOne important limitation of the stack, is that, only objects whose length/size is known at compile-time can be\nstored in it. In contrast, the heap is a much more dynamic\n(and flexible) type of memory. It is the perfect type of memory to use\nfor objects whose size/length might grow during the execution of your program.\n\nVirtually any application that behaves as a server is a classic use case of the heap.\nA HTTP server, a SSH server, a DNS server, a LSP server, ... any type of server.\nIn summary, a server is a type of application that runs for long periods of time,\nand that serves (or \"deals with\") any incoming request that reaches this particular server.\n\nThe heap is a good choice for this type of system, mainly because the server does not know upfront\nhow many requests it will receive from users, while it is active. It could be a single request,\n5 thousand requests, or even zero requests.\nThe server needs to have the ability to allocate and manage its memory according to how many requests it receives.\n\nAnother key difference between the stack and the heap, is that the heap is a type\nof memory that you, the programmer, have complete control over. This makes the heap a\nmore flexible type of memory, but it also makes it harder to work with. Because you,\nthe programmer, is responsible for managing everything related to it. Including where the memory is allocated,\nhow much memory is allocated, and where this memory is freed.\n\n> Unlike stack memory, heap memory is allocated explicitly by programmers and it won’t be deallocated until it is explicitly freed [@jenny2022].\n\nTo store an object in the heap, you, the programmer, needs to explicitly tells Zig to do so,\nby using an allocator to allocate some space in the heap. At @sec-allocators, I will present how you can use allocators to allocate memory\nin Zig.\n\n::: {.callout-important}\nEvery memory you allocate in the heap needs to be explicitly freed by you, the programmer.\n:::\n\nThe majority of allocators in Zig do allocate memory on the heap. But some exceptions to this rule are\n`ArenaAllocator()` and `FixedBufferAllocator()`. The `ArenaAllocator()` is a special\ntype of allocator that works in conjunction with a second type of allocator.\nOn the other side, the `FixedBufferAllocator()` is an allocator that works based on\nbuffer objects created on the stack. This means that the `FixedBufferAllocator()` makes\nallocations only on the stack.\n\n\n\n\n### Summary\n\nAfter discussing all of these boring details, we can quickly recap what we learned.\nIn summary, the Zig compiler will use the following rules to decide where each\nobject you declare is stored:\n\n1. every literal value (such as `\"this is string\"`, `10`, or `true`) is stored in the global data section.\n1. every constant object (`const`) whose value **is known at compile-time** is also stored in the global data section.\n1. every object (constant or not) whose length/size **is known at compile time** is stored in the stack space for the current scope.\n1. if an object is created with the method `alloc()` or `create()` of an allocator object, this object is stored in the memory space used by this particular allocator object. Most of allocators available in Zig use the heap memory, so, this object is likely stored in the heap (`FixedBufferAllocator()` is an exception to that).\n1. the heap can only be accessed through allocators. If your object was not created through the `alloc()` or `create()` methods of an allocator object, then, it is most certainly not an object stored in the heap.\n\n\n## Stack overflows {#sec-stack-overflow}\n\nAllocating memory on the stack is generally faster than allocating it on the heap.\nBut this better performance comes with many restrictions. We have already discussed\nmany of these restrictions of the stack at @sec-stack. But there is one more important\nlimitation that I want to talk about, which is the size of the stack itself.\n\nThe stack is limited in size. This size varies from computer to computer, and it depends on\na lot of things (the computer architecture, the operating system, etc.). Nevertheless, this size is usually\nnot that big. This is why we normally use the stack to store only temporary and small objects in memory.\n\nIn essence, if you try to make an allocation on the stack, that is so big that exceeds the stack size limit,\na *stack overflow* happens, and your program just crashes as a result of that. In other words, a stack overflow happens when\nyou attempt to use more space than is available on the stack.\n\nThis type of problem is very similar to a *buffer overflow*, i.e. you are trying to use more space\nthan is available in the \"buffer object\". However, a stack overflow always causes your program to crash,\nwhile a buffer overflow does not always cause your program to crash (although it often does).\n\nYou can see an example of a stack overflow in the example below. We are trying to allocate a very big array of `u64` values\non the stack. You can see below that this program does not run successfully, because it crashed\nwith a \"segmentation fault\" error message.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar very_big_alloc: [1000 * 1000 * 24]u64 = undefined;\n@memset(very_big_alloc[0..], 0);\n```\n:::\n\n\n\n\n```\nSegmentation fault (core dumped)\n```\n\nThis segmentation fault error is a result of the stack overflow that was caused by the big\nmemory allocation made on the stack, to store the `very_big_alloc` object.\nThis is why very big objects are usually stored on the heap, instead of the stack.\n\n\n\n## Allocators {#sec-allocators}\n\nOne key aspect about Zig, is that there are \"no hidden-memory allocations\" in Zig.\nWhat that really means, is that \"no allocations happen behind your back in the standard library\" [@zigguide].\n\nThis is a known problem, especially in C++. Because in C++, there are some operators that do allocate\nmemory behind the scene, and there is no way for you to know that, until you actually read the\nsource code of these operators, and find the memory allocation calls.\nMany programmers find this behaviour annoying and hard to keep track of.\n\nBut, in Zig, if a function, an operator, or anything from the standard library\nneeds to allocate some memory during its execution, then, this function/operator needs to receive (as input) an allocator\nprovided by the user, to actually be able to allocate the memory it needs.\n\nThis creates a clear distinction between functions that \"do not\" from those that \"actually do\"\nallocate memory. Just look at the arguments of this function.\nIf a function, or operator, has an allocator object as one of its inputs/arguments, then, you know for\nsure that this function/operator will allocate some memory during its execution.\n\nAn example is the `allocPrint()` function from the Zig Standard Library. With this function, you can\nwrite a new string using format specifiers. So, this function is, for example, very similar to the function `sprintf()` in C.\nIn order to write such a new string, the `allocPrint()` function needs to allocate some memory to store the\noutput string.\n\nThat is why, the first argument of this function is an allocator object that you, the user/programmer, gives\nas input to the function. In the example below, I am using the `GeneralPurposeAllocator()` as my allocator\nobject. But I could easily use any other type of allocator object from the Zig Standard Library.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst name = \"Pedro\";\nconst output = try std.fmt.allocPrint(\n    allocator,\n    \"Hello {s}!!!\",\n    .{name}\n);\ntry stdout.print(\"{s}\\n\", .{output});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello Pedro!!!\n```\n\n\n:::\n:::\n\n\n\n\n\nYou get a lot of control over where and how much memory this function can allocate.\nBecause it is you, the user/programmer, that provides the allocator for the function to use.\nThis makes \"total control\" over memory management easier to achieve in Zig.\n\n### What are allocators?\n\nAllocators in Zig are objects that you can use to allocate memory for your program.\nThey are similar to the memory allocating functions in C, like `malloc()` and `calloc()`.\nSo, if you need to use more memory than you initially have, during the execution of your program, you can simply ask\nfor more memory by using an allocator object.\n\nZig offers different types of allocators, and they are usually available through the `std.heap` module of\nthe standard library. Thus, just import the Zig Standard Library into your Zig module (with `@import(\"std\")`), and you can start\nusing these allocators in your code.\n\nFurthermore, every allocator object is built on top of the `Allocator` interface in Zig.\nThis means that, every allocator object you find in Zig must have the methods `alloc()`,\n`create()`, `free()` and `destroy()`. So, you can change the type of allocator you are using,\nbut you don't need to change the function calls to the methods that do the memory allocation\n(and the free memory operations) for your program.\n\n### Why you need an allocator?\n\nAs we described at @sec-stack, everytime you make a function call in Zig,\na space in the stack is reserved for this function call. But the stack\nhas a key limitation which is: every object stored in the stack has a\nknown fixed length.\n\nBut in reality, there are two very common instances where this \"fixed length limitation\" of the stack is a deal braker:\n\n1. the objects that you create inside your function might grow in size during the execution of the function.\n1. sometimes, it is impossible to know upfront how many inputs you will receive, or how big this input will be.\n\nAlso, there is another instance where you might want to use an allocator, which is when you want to write a function that returns a pointer\nto a local object. As I described at @sec-stack, you cannot do that if this local object is stored in the\nstack. However, if this object is stored in the heap, then, you can return a pointer to this object at the\nend of the function. Because you (the programmer) control the lifetime of any heap memory that you allocate. You decide\nwhen this memory gets destroyed/freed.\n\nThese are common situations for which the stack is not good. \nThat is why you need a different memory management strategy to\nstore these objects inside your function. You need to use\na memory type that can grow together with your objects, or that you\ncan control the lifetime of this memory.\nThe heap fits this description.\n\nAllocating memory on the heap is commonly known as dynamic memory management. As the objects you create grow in size\nduring the execution of your program, you grow the amount of memory\nyou have by allocating more memory in the heap to store these objects.\nAnd you do that in Zig, by using an allocator object.\n\n\n### The different types of allocators\n\n\nAt the moment of the writing of this book, in Zig, we have 6 different\nallocators available in the standard library:\n\n- `GeneralPurposeAllocator()`.\n- `page_allocator()`.\n- `FixedBufferAllocator()` and `ThreadSafeFixedBufferAllocator()`.\n- `ArenaAllocator()`.\n- `c_allocator()` (requires you to link to libc).\n\n\nEach allocator has its own perks and limitations. All allocators, except `FixedBufferAllocator()` and `ArenaAllocator()`,\nare allocators that use the heap memory. So any memory that you allocate with\nthese allocators, will be placed in the heap.\n\n### General-purpose allocators\n\nThe `GeneralPurposeAllocator()`, as the name suggests, is a \"general purpose\" allocator. You can use it for every type\nof task. In the example below, I'm allocating enough space to store a single integer in the object `some_number`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const some_number = try allocator.create(u32);\n    defer allocator.destroy(some_number);\n\n    some_number.* = @as(u32, 45);\n}\n```\n:::\n\n\n\n\n\nWhile useful, you might want to use the `c_allocator()`, which is a alias to the C standard allocator `malloc()`. So, yes, you can use\n`malloc()` in Zig if you want to. Just use the `c_allocator()` from the Zig standard library. However,\nif you do use `c_allocator()`, you must link to Libc when compiling your source code with the\n`zig` compiler, by including the flag `-lc` in your compilation process.\nIf you do not link your source code to Libc, Zig will not be able to find the\n`malloc()` implementation in your system.\n\n### Page allocator\n\nThe `page_allocator()` is an allocator that allocates full pages of memory in the heap. In other words,\nevery time you allocate memory with `page_allocator()`, a full page of memory in the heap is allocated,\ninstead of just a small piece of it.\n\nThe size of this page depends on the system you are using.\nMost systems use a page size of 4KB in the heap, so, that is the amount of memory that is normally\nallocated in each call by `page_allocator()`. That is why, `page_allocator()` is considered a\nfast, but also \"wasteful\" allocator in Zig. Because it allocates a big amount of memory\nin each call, and you most likely will not need that much memory in your program.\n\n### Buffer allocators\n\nThe `FixedBufferAllocator()` and `ThreadSafeFixedBufferAllocator()` are allocator objects that\nwork with a fixed sized buffer object at the back. In other words, they use a fixed sized buffer\nobject as the basis for the memory. When you ask these allocator objects to allocate some memory for you,\nthey are essentially reserving some amount of space inside this fixed sized buffer object for you to use.\n\nThis means that, in order to use these allocators, you must first create a buffer object in your code,\nand then, give this buffer object as an input to these allocators.\n\nThis also means that, these allocator objects can allocate memory both in the stack or in the heap.\nEverything depends on where the buffer object that you provide lives. If this buffer object lives\nin the stack, then, the memory allocated is \"stack-based\". But if it lives on the heap, then,\nthe memory allocated is \"heap-based\".\n\n\nIn the example below, I'm creating a `buffer` object on the stack that is 10 elements long.\nNotice that I give this `buffer` object to the `FixedBufferAllocator()` constructor.\nNow, because this `buffer` object is 10 elements long, this means that I am limited to this space.\nI cannot allocate more than 10 elements with this allocator object. If I try to\nallocate more than that, the `alloc()` method will return an `OutOfMemory` error value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar buffer: [10]u8 = undefined;\nfor (0..buffer.len) |i| {\n    buffer[i] = 0; // Initialize to zero\n}\n\nvar fba = std.heap.FixedBufferAllocator.init(&buffer);\nconst allocator = fba.allocator();\nconst input = try allocator.alloc(u8, 5);\ndefer allocator.free(input);\n```\n:::\n\n\n\n\nRemember, the memory allocated by these allocator objects can be either from\nthe stack, or, from the heap. It all depends on where the buffer object that you provide lives.\nIn the above example, the `buffer` object lives in the stack, and, therefore, the memory allocated\nis based in the stack. But what if it was based on the heap?\n\nAs we described at @sec-stack-overflow, one of the main reasons why you would use the heap,\ninstead of the stack, is to allocate huge amounts of space to store very big objects.\nThus, let's suppose you wanted to use a very big buffer object as the basis for your\nallocator objects. You would have to allocate this very big buffer object on the heap.\nThe example below demonstrates this case.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst heap = std.heap.page_allocator;\nconst memory_buffer = try heap.alloc(\n    u8, 100 * 1024 * 1024 // 100 MB memory\n);\ndefer heap.free(memory_buffer);\nvar fba = std.heap.FixedBufferAllocator.init(\n    memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst input = try allocator.alloc(u8, 1000);\ndefer allocator.free(input);\n```\n:::\n\n\n\n\n\n\n### Arena allocator {#sec-arena-allocator}\n\nThe `ArenaAllocator()` is an allocator object that takes a child allocator as input. The idea behind the `ArenaAllocator()` in Zig\nis similar to the concept of \"arenas\" in the programming language Go[^go-arena]. It is an allocator object that allows you\nto allocate memory as many times you want, but free all memory only once.\nIn other words, if you have, for example, called 5 times the method `alloc()` of an `ArenaAllocator()` object, you can\nfree all the memory you allocated over these 5 calls at once, by simply calling the `deinit()` method of the same `ArenaAllocator()` object.\n\n[^go-arena]: <https://go.dev/src/arena/arena.go>\n\nIf you give, for example, a `GeneralPurposeAllocator()` object as input to the `ArenaAllocator()` constructor, like in the example below, then, the allocations\nyou perform with `alloc()` will actually be made with the underlying object `GeneralPurposeAllocator()` that was passed.\nSo, with an arena allocator, any new memory you ask for is allocated by the child allocator. The only thing that an arena allocator\nreally does is help you to free all the memory you allocated multiple times with just a single command. In the example\nbelow, I called `alloc()` 3 times. So, if I did not use an arena allocator, then, I would need to call\n`free()` 3 times to free all the allocated memory.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nvar aa = std.heap.ArenaAllocator.init(gpa.allocator());\ndefer aa.deinit();\nconst allocator = aa.allocator();\n\nconst in1 = try allocator.alloc(u8, 5);\nconst in2 = try allocator.alloc(u8, 10);\nconst in3 = try allocator.alloc(u8, 15);\n_ = in1; _ = in2; _ = in3;\n```\n:::\n\n\n\n\n\n\n### The `alloc()` and `free()` methods\n\nIn the code example below, we are accessing the `stdin`, which is\nthe standard input channel, to receive an input from the\nuser. We read the input given by the user with the `readUntilDelimiterOrEof()`\nmethod.\n\nNow, after reading the input of the user, we need to store this input somewhere in\nour program. That is why I use an allocator in this example. I use it to allocate some\namount of memory to store this input given by the user. More specifically, the method `alloc()`\nof the allocator object is used to allocate an array capable of storing 50 `u8` values.\n\nNotice that this `alloc()` method receives two inputs. The first one, is a type.\nThis defines what type of values the allocated array will store. In the example\nbelow, we are allocating an array of unsigned 8-bit integers (`u8`). But\nyou can create an array to store any type of value you want. Next, on the second argument, we\ndefine the size of the allocated array, by specifying how many elements\nthis array will contain. In the case below, we are allocating an array of 50 elements.\n\nAt @sec-zig-strings we described that strings in Zig are simply arrays of characters.\nEach character is represented by a `u8` value. So, this means that the array that\nwas allocated in the object `input` is capable of storing a string that is\n50-characters long.\n\nSo, in essence, the expression `var input: [50]u8 = undefined` would create\nan array for 50 `u8` values in the stack of the current scope. But, you\ncan allocate the same array in the heap by using the expression `var input = try allocator.alloc(u8, 50)`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdin = std.io.getStdIn();\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var input = try allocator.alloc(u8, 50);\n    defer allocator.free(input);\n    for (0..input.len) |i| {\n        input[i] = 0; // initialize all fields to zero.\n    }\n    // read user input\n    const input_reader = stdin.reader();\n    _ = try input_reader.readUntilDelimiterOrEof(\n        input,\n        '\\n'\n    );\n    std.debug.print(\"{s}\\n\", .{input});\n}\n```\n:::\n\n\n\n\nAlso, notice that in this example, we use the `defer` keyword (which I described at @sec-defer) to run a small\npiece of code at the end of the current scope, which is the expression `allocator.free(input)`.\nWhen you execute this expression, the allocator will free the memory that it allocated\nfor the `input` object.\n\nWe have talked about this at @sec-heap. You **should always** explicitly free any memory that you allocate\nusing an allocator! You do that by using the `free()` method of the same allocator object you\nused to allocate this memory. The `defer` keyword is used in this example only to help us execute\nthis free operation at the end of the current scope.\n\n\n### The `create()` and `destroy()` methods\n\nWith the `alloc()` and `free()` methods, you can allocate memory to store multiple elements\nat once. In other words, with these methods, we always allocate an array to store multiple elements at once.\nBut what if you need enough space to store just a single item? Should you\nallocate an array of a single element through `alloc()`?\n\nThe answer is no! In this case,\nyou should use the `create()` method of the allocator object.\nEvery allocator object offers the `create()` and `destroy()` methods,\nwhich are used to allocate and free memory for a single item, respectively.\n\nSo, in essence, if you want to allocate memory to store an array of elements, you\nshould use `alloc()` and `free()`. But if you need to store just a single item,\nthen, the `create()` and `destroy()` methods are ideal for you.\n\nIn the example below, I'm defining a struct to represent an user of some sort.\nIt could be a user for a game, or software to manage resources, it doesn't mater.\nNotice that I use the `create()` method this time, to store a single `User` object\nin the program. Also notice that I use the `destroy()` method to free the memory\nused by this object at the end of the scope.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst User = struct {\n    id: usize,\n    name: []const u8,\n\n    pub fn init(id: usize, name: []const u8) User {\n        return .{ .id = id, .name = name };\n    }\n};\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const user = try allocator.create(User);\n    defer allocator.destroy(user);\n\n    user.* = User.init(0, \"Pedro\");\n}\n```\n:::\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Memory and Allocators\n\n\nIn this chapter, we will talk about memory. How does Zig control memory? What\ncommon tools are used? Are there any important aspects that make memory\ndifferent/special in Zig? You will find the answers here.\n\nComputers fundamentally rely on memory to function. This memory acts as a temporary storage\nspace for the data and values generated during computations. Without memory, the core\nconcepts of \"variables\" and \"objects\" in programming languages would be impossible.\n\n\n\n\n## Memory spaces\n\nEvery object that you create in your Zig source code needs to be stored somewhere,\nin your computer's memory. Depending on where and how you define your object, Zig\nwill use a different \"memory space\", or a different\ntype of memory to store this object.\n\nEach type of memory normally serves for different purposes.\nIn Zig, there are 3 types of memory (or 3 different memory spaces) that we care about. They are:\n\n- Global data register (or the \"global data section\");\n- Stack;\n- Heap;\n\n\n### Compile-time known versus runtime known {#sec-compile-time}\n\nOne strategy that Zig uses to decide where it will store each object that you declare, is by looking\nat the value of this particular object. More specifically, by investigating if this value is\nknown at \"compile-time\" or at \"runtime\".\n\nWhen you write a program in Zig, the values of some of the objects that you write in your program are *known\nat compile time*. Meaning that, when you compile your Zig source code, during the compilation process,\nthe `zig` compiler can figure out the exact value of a particular object\nthat exists in your source code.\nKnowing the length (or the size) of each object is also important. So the length (or the size) of each object that you write in your program is,\nin some cases, *known at compile time*.\n\nThe `zig` compiler cares more about knowing the length (or the size) of a particular object\n, than to know its actual value. But, if the `zig` compiler knows the value of the object, then, it\nautomatically knows the size of this object. Because it can simply calculate the\nsize of the object by looking at the size of the value.\n\nTherefore, the priority for the `zig` compiler is to discover the size of each object in your source code.\nIf the value of the object in question is known at compile-time, then, the `zig` compiler\nautomatically knows the size/length of this object. But if the value of this object is not\nknown at compile-time, then, the size of this object is only known at compile-time if,\nand only if, the type of this object has a known fixed size.\n\nIn order for a type to have a known fixed size, this type must have data members whose size is fixed.\nIf this type includes, for example, a variable sized array in it, then, this type does not have a known\nfixed size. Because this array can have any size at runtime\n(i.e., it can be an array of 2 elements, or 50 elements, or 1 thousand elements, etc.).\n\nFor example, a string object, which internally is an array of constant u8 values (`[]const u8`)\nhas a variable size. It can be a string object with 100 or 500 characters in it. If we do not\nknow at compile-time, which exact string will be stored inside this string object, then, we cannot calculate\nthe size of this string object at compile-time. So, any type, or any struct declaration that you make, that\nincludes a string data member that does not have an explicit fixed size, makes this type, or this\nnew struct that you are declaring, a type that does not have a known fixed size at compile-time.\n\nIn contrast, if the type of this struct that you are declaring, includes a data member that is an array,\nbut this array has a known fixed size, like `[60]u8` (which declares an array of 60 `u8` values), then,\nthis type, or, this struct that you are declaring, becomes a type with a known fixed size at compile-time.\nAnd because of that, in this case, the `zig` compiler does not need to know at compile-time the exact value of\nany object of this type. Since the compiler can find the necessary size to store this object by\nlooking at the size of its type.\n\n\nLet's look at an example. In the source code below, we have two constant objects (`name` and `array`) declared.\nBecause the values of these particular objects are written down, in the source code itself (`\"Pedro\"`\nand the number sequence from 1 to 4), the `zig` compiler can easily discover the values of these constant\nobjects (`name` and `array`) during the compilation process.\nThis is what \"known at compile time\" means. It refers to any object that you have in your Zig source code\nwhose value can be identified at compile time.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn input_length(input: []const u8) usize {\n    const n = input.len;\n    return n;\n}\n\npub fn main() !void {\n    const name = \"Pedro\";\n    const array = [_]u8{1, 2, 3, 4};\n    _ = name; _ = array;\n}\n```\n:::\n\n\n\n\nThe other side of the spectrum are objects whose values are not known at compile time.\nFunction arguments are a classic example of this. Because the value of each function\nargument depends on the value that you assign to this particular argument,\nwhen you call the function.\n\nFor example, the function `input_length()` contains an argument named `input`, which is an array of constant `u8` integers (`[]const u8`).\nIt's impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length\nof this particular argument. Because it's an array that does not have a fixed size specified explicitly in the argument type annotation.\n\nSo, we know that this `input` argument will be an array of `u8` integers. But we do not know at compile-time, its value, and neither its size.\nThis information is known only at runtime, which is the period of time when you program is executed.\nAs a consequence, the value of the expression `input.len` is also known only at runtime.\nThis is an intrinsic characteristic of any function. Just remember that the value of function arguments is usually not \"compile-time known\".\n\nHowever, as I mentioned earlier, what really matters to the compiler is to know the size of the object\nat compile-time, and not necessarily its value. So, although we don't know the value of the object `n`, which is the result of the expression\n`input.len`, at compile-time, we do know its size. Because the expression `input.len` always returns a value of type `usize`,\nand the type `usize` has a known fixed size.\n\n\n\n### Global data register\n\nThe global data register is a specific section of the executable of your Zig program, that is responsible\nfor storing any value that is known at compile time.\n\nEvery constant object whose value is known at compile time that you declare in your source code,\nis stored in the global data register. Also, every literal value that you write in your source code,\nsuch as the string `\"this is a string\"`, or the integer `10`, or a boolean value such as `true`,\nis also stored in the global data register.\n\nHonestly, you don't need to care much about this memory space. Because you can't control it,\nyou can't deliberately access it or use it for your own purposes.\nAlso, this memory space does not affect the logic of your program.\nIt simply exists in your program.\n\n\n### Stack vs Heap\n\nIf you are familiar with systems programming, or just low-level programming in general, you\nprobably have heard of the \"duel\" between Stack vs Heap. These are two different types of memory,\nor different memory spaces, which are both available in Zig.\n\nThese two types of memory don't actually duel with\neach other. This is a common mistake that beginners have, when seeing \"x vs y\" styles of\ntabloid headlines. These two types of memory are actually complementary to each other.\nSo, in almost every Zig program that you ever write, you will likely use a combination of both.\nI will describe each memory space in detail over the next sections. But for now, I just want to\nstablish the main difference between these two types of memory.\n\nIn essence, the stack memory is normally used to store values whose length is fixed and known\nat compile time. In contrast, the heap memory is a *dynamic* type of memory space, meaning that, it's\nused to store values whose length might grow during the execution (runtime) of your program [@jenny2022].\n\nLengths that grow during runtime are intrinsically associated with \"runtime known\" type of values.\nIn other words, if you have an object whose length might grow during runtime, then, the length\nof this object becomes not known at compile time. If the length is not known at compile-time,\nthe value of this object also becomes not known at compile-time.\nThese types of objects should be stored in the heap memory space, which is\na dynamic memory space, which can grow or shrink to fit the size of your objects.\n\n\n\n### Stack {#sec-stack}\n\nThe stack is a type of memory that uses the power of the *stack data structure*, hence the name.\nA \"stack\" is a type of *data structure* that uses a \"last in, first out\" (LIFO) mechanism to store the values\nyou give it to. I imagine you are familiar with this data structure.\nBut, if you are not, the [Wikipedia page](https://en.wikipedia.org/wiki/Stack_(abstract_data_type))[^wiki-stack]\n, or, the [Geeks For Geeks page](https://www.geeksforgeeks.org/stack-data-structure/)[^geek-stack] are both\nexcellent and easy resources to fully understand how this data structure works.\n\n[^wiki-stack]: <https://en.wikipedia.org/wiki/Stack_(abstract_data_type)>\n[^geek-stack]: <https://www.geeksforgeeks.org/stack-data-structure/>\n\nSo, the stack memory space is a type of memory that stores values using a stack data structure.\nIt adds and removes values from the memory by following a \"last in, first out\" (LIFO) principle.\n\nEvery time you make a function call in Zig, an amount of space in the stack is\nreserved for this particular function call [@jenny2022; @zigdocs].\nThe value of each function argument given to the function in this function call is stored in this\nstack space. Also, every local object that you declare inside the function scope is\nusually stored in this same stack space.\n\n\nLooking at the example below, the object `result` is a local object declared inside the scope of the `add()`\nfunction. Because of that, this object is stored inside the stack space reserved for the `add()` function.\nThe `r` object (which is declared outside of the `add()` function scope) is also stored in the stack.\nBut since it's declared in the \"outer\" scope, this object is stored in the\nstack space that belongs to this outer scope.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn add(x: u8, y: u8) u8 {\n    const result = x + y;\n    return result;\n}\n\npub fn main() !void {\n    const r = add(5, 27);\n    _ = r;\n}\n```\n:::\n\n\n\n\n\nSo, any object that you declare inside the scope of a function is always stored inside\nthe space that was reserved for that particular function in the stack memory. This\nalso counts for any object declared inside the scope of your `main()` function for example.\nAs you would expect, in this case, they\nare stored inside the stack space reserved for the `main()` function.\n\nOne very important detail about the stack memory is that **it frees itself automatically**.\nThis is very important, remember that. When objects are stored in the stack memory,\nyou don't have the work (or the responsibility) of freeing/destroying these objects.\nBecause they will be automatically destroyed once the stack space is freed at the end of the function scope.\n\nSo, once the function call returns (or ends, if you prefer to call it this way)\nthe space that was reserved in the stack is destroyed, and all of the objects that were in that space goes away with it.\nThis mechanism exists because this space, and the objects within it, are not necessary anymore,\nsince the function \"finished its business\".\nUsing the `add()` function that we exposed above as an example, it means that the object `result` is automatically\ndestroyed once the function returns.\n\n::: {.callout-important}\nLocal objects that are stored in the stack space of a function are automatically\nfreed/destroyed at the end of the function scope.\n:::\n\n\nThis same logic applies to any other special structure in Zig that has its own scope by surrounding\nit with curly braces (`{}`).\nFor loops, while loops, if else statements, etc. For example, if you declare any local\nobject in the scope of a for loop, this local object is accessible only within the scope\nof this particular for loop. Because once the scope of this for loop ends, the space in the stack\nreserved for this for loop is freed.\nThe example below demonstrates this idea.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This does not compile successfully!\nconst a = [_]u8{0, 1, 2, 3, 4};\nfor (0..a.len) |i| {\n    const index = i;\n    _ = index;\n}\n// Trying to use an object that was\n// declared in the for loop scope,\n// and that does not exist anymore.\nstd.debug.print(\"{d}\\n\", .{index});\n```\n:::\n\n\n\n\n\n\nOne important consequence of this mechanism is that, once the function returns, you can no longer access any memory\naddress that was inside the space in the stack reserved for this particular function. Because this space was\ndestroyed. This means that, if this local object is stored in the stack,\nyou cannot make a function that **returns a pointer to this object**.\n\nThink about that for a second. If all local objects in the stack are destroyed at the end of the function scope, why\nwould you even consider returning a pointer to one of these objects? This pointer is at best,\ninvalid, or, more likely, \"undefined\".\n\nIn conclusion, it's totally fine to write a function that returns the local object\nitself as result, because then, you return the value of that object as the result.\nBut, if this local object is stored in the stack, you should never write a function\nthat returns a pointer to this local object. Because the memory address pointed by the pointer\nno longer exists.\n\n\nSo, using again the `add()` function as an example, if you rewrite this function so that it\nreturns a pointer to the local object `result`, the `zig` compiler will actually compile\nyour program, with no warnings or errors. At first glance, it looks like this is good code\nthat works as expected. But this is a lie!\n\nIf you try to take a look at the value inside of the `r` object,\nor, if you try to use this `r` object in another expression\nor function call, then, you would have undefined behaviour, and major\nbugs in your program [@zigdocs, see \"Lifetime and Ownership\"[^life] and \"Undefined Behaviour\"[^undef] sections].\n\n[^life]: <https://ziglang.org/documentation/master/#Lifetime-and-Ownership>\n[^undef]: <https://ziglang.org/documentation/master/#Undefined-Behavior>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn add(x: u8, y: u8) *const u8 {\n    const result = x + y;\n    return &result;\n}\n\npub fn main() !void {\n    // This code compiles successfully. But it has\n    // undefined behaviour. Never do this!!!\n    // The `r` object is undefined!\n    const r = add(5, 27); _ = r;\n}\n```\n:::\n\n\n\n\nThis \"invalid pointer to stack variable\" problem is well known across many programming language communities.\nIf you try to do the same thing, for example, in a C or C++ program (i.e., returning an address to\na local object stored in the stack), you would also get undefined behaviour\nin the program.\n\n::: {.callout-important}\nIf a local object in your function is stored in the stack, you should never\nreturn a pointer to this local object from the function. Because\nthis pointer will always become undefined after the function returns, since the stack space of the function\nis destroyed at the end of its scope.\n:::\n\nBut what if you really need to use this local object in some way after your function returns?\nHow can you do this? The answer is: \"in the same way you would do if this were a C or C++ program. By returning\nan address to an object stored in the heap\". The heap memory has a much more flexible lifecycle,\nand allows you to get a valid pointer to a local object of a function that already returned\nfrom its scope.\n\n\n### Heap {#sec-heap}\n\nOne important limitation of the stack, is that, only objects whose length/size is known at compile-time can be\nstored in it. In contrast, the heap is a much more dynamic\n(and flexible) type of memory. It's the perfect type of memory to use\nfor objects whose size/length might grow during the execution of your program.\n\nVirtually any application that behaves as a server is a classic use case of the heap.\nA HTTP server, a SSH server, a DNS server, a LSP server, ... any type of server.\nIn summary, a server is a type of application that runs for long periods of time,\nand that serves (or \"deals with\") any incoming request that reaches this particular server.\n\nThe heap is a good choice for this type of system, mainly because the server does not know upfront\nhow many requests it will receive from users, while it is active. It could be a single request,\n5 thousand requests, or even zero requests.\nThe server needs to have the ability to allocate and manage its memory according to how many requests it receives.\n\nAnother key difference between the stack and the heap, is that the heap is a type\nof memory that you, the programmer, have complete control over. This makes the heap a\nmore flexible type of memory, but it also makes it harder to work with. Because you,\nthe programmer, is responsible for managing everything related to it. Including where the memory is allocated,\nhow much memory is allocated, and where this memory is freed.\n\n> Unlike stack memory, heap memory is allocated explicitly by programmers and it won’t be deallocated until it is explicitly freed [@jenny2022].\n\nTo store an object in the heap, you, the programmer, needs to explicitly tells Zig to do so,\nby using an allocator to allocate some space in the heap. In @sec-allocators, I will present how you can use allocators to allocate memory\nin Zig.\n\n::: {.callout-important}\nEvery memory you allocate in the heap needs to be explicitly freed by you, the programmer.\n:::\n\nThe majority of allocators in Zig do allocate memory on the heap. But some exceptions to this rule are\n`ArenaAllocator()` and `FixedBufferAllocator()`. The `ArenaAllocator()` is a special\ntype of allocator that works in conjunction with a second type of allocator.\nOn the other side, the `FixedBufferAllocator()` is an allocator that works based on\nbuffer objects created on the stack. This means that the `FixedBufferAllocator()` makes\nallocations only on the stack.\n\n\n\n\n### Summary\n\nAfter discussing all of these boring details, we can quickly recap what we learned.\nIn summary, the Zig compiler will use the following rules to decide where each\nobject you declare is stored:\n\n1. every literal value (such as `\"this is string\"`, `10`, or `true`) is stored in the global data section.\n1. every constant object (`const`) whose value **is known at compile-time** is also stored in the global data section.\n1. every object (constant or not) whose length/size **is known at compile time** is stored in the stack space for the current scope.\n1. if an object is created with the method `alloc()` or `create()` of an allocator object, this object is stored in the memory space used by this particular allocator object. Most of allocators available in Zig use the heap memory, so, this object is likely stored in the heap (`FixedBufferAllocator()` is an exception to that).\n1. the heap can only be accessed through allocators. If your object was not created through the `alloc()` or `create()` methods of an allocator object, then, it is most certainly not an object stored in the heap.\n\n\n## Stack overflows {#sec-stack-overflow}\n\nAllocating memory on the stack is generally faster than allocating it on the heap.\nBut this better performance comes with many restrictions. We have already discussed\nmany of these restrictions of the stack in @sec-stack. But there is one more important\nlimitation that I want to talk about, which is the size of the stack itself.\n\nThe stack is limited in size. This size varies from computer to computer, and it depends on\na lot of things (the computer architecture, the operating system, etc.). Nevertheless, this size is usually\nnot that big. This is why we normally use the stack to store only temporary and small objects in memory.\n\nIn essence, if you try to make an allocation on the stack, that is so big that exceeds the stack size limit,\na *stack overflow* happens, and your program just crashes as a result of that. In other words, a stack overflow happens when\nyou attempt to use more space than is available on the stack.\n\nThis type of problem is very similar to a *buffer overflow*, i.e., you are trying to use more space\nthan is available in the \"buffer object\". However, a stack overflow always causes your program to crash,\nwhile a buffer overflow does not always cause your program to crash (although it often does).\n\nYou can see an example of a stack overflow in the example below. We are trying to allocate a very big array of `u64` values\non the stack. You can see below that this program does not run successfully, because it crashed\nwith a \"segmentation fault\" error message.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar very_big_alloc: [1000 * 1000 * 24]u64 = undefined;\n@memset(very_big_alloc[0..], 0);\n```\n:::\n\n\n\n\n```\nSegmentation fault (core dumped)\n```\n\nThis segmentation fault error is a result of the stack overflow that was caused by the big\nmemory allocation made on the stack, to store the `very_big_alloc` object.\nThis is why very big objects are usually stored on the heap, instead of the stack.\n\n\n\n## Allocators {#sec-allocators}\n\nOne key aspect about Zig, is that there are \"no hidden-memory allocations\" in Zig.\nWhat that really means, is that \"no allocations happen behind your back in the standard library\" [@zigguide].\n\nThis is a known problem, especially in C++. Because in C++, there are some operators that do allocate\nmemory behind the scene, and there is no way for you to know that, until you actually read the\nsource code of these operators, and find the memory allocation calls.\nMany programmers find this behaviour annoying and hard to keep track of.\n\nBut, in Zig, if a function, an operator, or anything from the standard library\nneeds to allocate some memory during its execution, then, this function/operator needs to receive (as input) an allocator\nprovided by the user, to actually be able to allocate the memory it needs.\n\nThis creates a clear distinction between functions that \"do not\" from those that \"actually do\"\nallocate memory. Just look at the arguments of this function.\nIf a function, or operator, has an allocator object as one of its inputs/arguments, then, you know for\nsure that this function/operator will allocate some memory during its execution.\n\nAn example is the `allocPrint()` function from the Zig Standard Library. With this function, you can\nwrite a new string using format specifiers. So, this function is, for example, very similar to the function `sprintf()` in C.\nIn order to write such a new string, the `allocPrint()` function needs to allocate some memory to store the\noutput string.\n\nThat is why, the first argument of this function is an allocator object that you, the user/programmer, gives\nas input to the function. In the example below, I am using the `GeneralPurposeAllocator()` as my allocator\nobject. But I could easily use any other type of allocator object from the Zig Standard Library.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst name = \"Pedro\";\nconst output = try std.fmt.allocPrint(\n    allocator,\n    \"Hello {s}!!!\",\n    .{name}\n);\ntry stdout.print(\"{s}\\n\", .{output});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello Pedro!!!\n```\n\n\n:::\n:::\n\n\n\n\n\nYou get a lot of control over where and how much memory this function can allocate.\nBecause it is you, the user/programmer, that provides the allocator for the function to use.\nThis makes \"total control\" over memory management easier to achieve in Zig.\n\n### What are allocators?\n\nAllocators in Zig are objects that you can use to allocate memory for your program.\nThey are similar to the memory allocating functions in C, like `malloc()` and `calloc()`.\nSo, if you need to use more memory than you initially have, during the execution of your program, you can simply ask\nfor more memory by using an allocator object.\n\nZig offers different types of allocators, and they are usually available through the `std.heap` module of\nthe standard library. Thus, just import the Zig Standard Library into your Zig module (with `@import(\"std\")`), and you can start\nusing these allocators in your code.\n\nFurthermore, every allocator object is built on top of the `Allocator` interface in Zig.\nThis means that, every allocator object you find in Zig must have the methods `alloc()`,\n`create()`, `free()` and `destroy()`. So, you can change the type of allocator you are using,\nbut you don't need to change the function calls to the methods that do the memory allocation\n(and the free memory operations) for your program.\n\n### Why you need an allocator?\n\nAs we described in @sec-stack, everytime you make a function call in Zig,\na space in the stack is reserved for this function call. But the stack\nhas a key limitation which is: every object stored in the stack has a\nknown fixed length.\n\nBut in reality, there are two very common instances where this \"fixed length limitation\" of the stack is a deal braker:\n\n1. the objects that you create inside your function might grow in size during the execution of the function.\n1. sometimes, it's impossible to know upfront how many inputs you will receive, or how big this input will be.\n\nAlso, there is another instance where you might want to use an allocator, which is when you want to write a function that returns a pointer\nto a local object. As I described in @sec-stack, you cannot do that if this local object is stored in the\nstack. However, if this object is stored in the heap, then, you can return a pointer to this object at the\nend of the function. Because you (the programmer) control the lifetime of any heap memory that you allocate. You decide\nwhen this memory gets destroyed/freed.\n\nThese are common situations for which the stack is not good.\nThat is why you need a different memory management strategy to\nstore these objects inside your function. You need to use\na memory type that can grow together with your objects, or that you\ncan control the lifetime of this memory.\nThe heap fits this description.\n\nAllocating memory on the heap is commonly known as dynamic memory management. As the objects you create grow in size\nduring the execution of your program, you grow the amount of memory\nyou have by allocating more memory in the heap to store these objects.\nAnd you do that in Zig, by using an allocator object.\n\n\n### The different types of allocators\n\n\nAt the moment of the writing of this book, in Zig, we have 6 different\nallocators available in the standard library:\n\n- `GeneralPurposeAllocator()`.\n- `page_allocator()`.\n- `FixedBufferAllocator()` and `ThreadSafeFixedBufferAllocator()`.\n- `ArenaAllocator()`.\n- `c_allocator()` (requires you to link to libc).\n\n\nEach allocator has its own perks and limitations. All allocators, except `FixedBufferAllocator()` and `ArenaAllocator()`,\nare allocators that use the heap memory. So any memory that you allocate with\nthese allocators, will be placed in the heap.\n\n### General-purpose allocators\n\nThe `GeneralPurposeAllocator()`, as the name suggests, is a \"general purpose\" allocator. You can use it for every type\nof task. In the example below, I'm allocating enough space to store a single integer in the object `some_number`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const some_number = try allocator.create(u32);\n    defer allocator.destroy(some_number);\n\n    some_number.* = @as(u32, 45);\n}\n```\n:::\n\n\n\n\n\nWhile useful, you might want to use the `c_allocator()`, which is a alias to the C standard allocator `malloc()`. So, yes, you can use\n`malloc()` in Zig if you want to. Just use the `c_allocator()` from the Zig standard library. However,\nif you do use `c_allocator()`, you must link to Libc when compiling your source code with the\n`zig` compiler, by including the flag `-lc` in your compilation process.\nIf you do not link your source code to Libc, Zig will not be able to find the\n`malloc()` implementation in your system.\n\n### Page allocator\n\nThe `page_allocator()` is an allocator that allocates full pages of memory in the heap. In other words,\nevery time you allocate memory with `page_allocator()`, a full page of memory in the heap is allocated,\ninstead of just a small piece of it.\n\nThe size of this page depends on the system you are using.\nMost systems use a page size of 4KB in the heap, so, that is the amount of memory that is normally\nallocated in each call by `page_allocator()`. That is why, `page_allocator()` is considered a\nfast, but also \"wasteful\" allocator in Zig. Because it allocates a big amount of memory\nin each call, and you most likely will not need that much memory in your program.\n\n### Buffer allocators\n\nThe `FixedBufferAllocator()` and `ThreadSafeFixedBufferAllocator()` are allocator objects that\nwork with a fixed sized buffer object at the back. In other words, they use a fixed sized buffer\nobject as the basis for the memory. When you ask these allocator objects to allocate some memory for you,\nthey are essentially reserving some amount of space inside this fixed sized buffer object for you to use.\n\nThis means that, in order to use these allocators, you must first create a buffer object in your code,\nand then, give this buffer object as an input to these allocators.\n\nThis also means that, these allocator objects can allocate memory both in the stack or in the heap.\nEverything depends on where the buffer object that you provide lives. If this buffer object lives\nin the stack, then, the memory allocated is \"stack-based\". But if it lives on the heap, then,\nthe memory allocated is \"heap-based\".\n\n\nIn the example below, I'm creating a `buffer` object on the stack that is 10 elements long.\nNotice that I give this `buffer` object to the `FixedBufferAllocator()` constructor.\nNow, because this `buffer` object is 10 elements long, this means that I am limited to this space.\nI cannot allocate more than 10 elements with this allocator object. If I try to\nallocate more than that, the `alloc()` method will return an `OutOfMemory` error value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar buffer: [10]u8 = undefined;\nfor (0..buffer.len) |i| {\n    buffer[i] = 0; // Initialize to zero\n}\n\nvar fba = std.heap.FixedBufferAllocator.init(&buffer);\nconst allocator = fba.allocator();\nconst input = try allocator.alloc(u8, 5);\ndefer allocator.free(input);\n```\n:::\n\n\n\n\nRemember, the memory allocated by these allocator objects can be either from\nthe stack, or, from the heap. It all depends on where the buffer object that you provide lives.\nIn the above example, the `buffer` object lives in the stack, and, therefore, the memory allocated\nis based in the stack. But what if it was based on the heap?\n\nAs we described in @sec-stack-overflow, one of the main reasons why you would use the heap,\ninstead of the stack, is to allocate huge amounts of space to store very big objects.\nThus, let's suppose you wanted to use a very big buffer object as the basis for your\nallocator objects. You would have to allocate this very big buffer object on the heap.\nThe example below demonstrates this case.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst heap = std.heap.page_allocator;\nconst memory_buffer = try heap.alloc(\n    u8, 100 * 1024 * 1024 // 100 MB memory\n);\ndefer heap.free(memory_buffer);\nvar fba = std.heap.FixedBufferAllocator.init(\n    memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst input = try allocator.alloc(u8, 1000);\ndefer allocator.free(input);\n```\n:::\n\n\n\n\n\n\n### Arena allocator {#sec-arena-allocator}\n\nThe `ArenaAllocator()` is an allocator object that takes a child allocator as input. The idea behind the `ArenaAllocator()` in Zig\nis similar to the concept of \"arenas\" in the programming language Go[^go-arena]. It's an allocator object that allows you\nto allocate memory as many times you want, but free all memory only once.\nIn other words, if you have, for example, called 5 times the method `alloc()` of an `ArenaAllocator()` object, you can\nfree all the memory you allocated over these 5 calls at once, by simply calling the `deinit()` method of the same `ArenaAllocator()` object.\n\n[^go-arena]: <https://go.dev/src/arena/arena.go>\n\nIf you give, for example, a `GeneralPurposeAllocator()` object as input to the `ArenaAllocator()` constructor, like in the example below, then, the allocations\nyou perform with `alloc()` will actually be made with the underlying object `GeneralPurposeAllocator()` that was passed.\nSo, with an arena allocator, any new memory you ask for is allocated by the child allocator. The only thing that an arena allocator\nreally does is help you to free all the memory you allocated multiple times with just a single command. In the example\nbelow, I called `alloc()` 3 times. So, if I did not use an arena allocator, then, I would need to call\n`free()` 3 times to free all the allocated memory.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nvar aa = std.heap.ArenaAllocator.init(gpa.allocator());\ndefer aa.deinit();\nconst allocator = aa.allocator();\n\nconst in1 = try allocator.alloc(u8, 5);\nconst in2 = try allocator.alloc(u8, 10);\nconst in3 = try allocator.alloc(u8, 15);\n_ = in1; _ = in2; _ = in3;\n```\n:::\n\n\n\n\n\n\n### The `alloc()` and `free()` methods\n\nIn the code example below, we are accessing the `stdin`, which is\nthe standard input channel, to receive an input from the\nuser. We read the input given by the user with the `readUntilDelimiterOrEof()`\nmethod.\n\nNow, after reading the input of the user, we need to store this input somewhere in\nour program. That is why I use an allocator in this example. I use it to allocate some\namount of memory to store this input given by the user. More specifically, the method `alloc()`\nof the allocator object is used to allocate an array capable of storing 50 `u8` values.\n\nNotice that this `alloc()` method receives two inputs. The first one, is a type.\nThis defines what type of values the allocated array will store. In the example\nbelow, we are allocating an array of unsigned 8-bit integers (`u8`). But\nyou can create an array to store any type of value you want. Next, in the second argument, we\ndefine the size of the allocated array, by specifying how many elements\nthis array will contain. In the case below, we are allocating an array of 50 elements.\n\nIn @sec-zig-strings we described that strings in Zig are simply arrays of characters.\nEach character is represented by a `u8` value. So, this means that the array that\nwas allocated in the object `input` is capable of storing a string that is\n50-characters long.\n\nSo, in essence, the expression `var input: [50]u8 = undefined` would create\nan array for 50 `u8` values in the stack of the current scope. But, you\ncan allocate the same array in the heap by using the expression `var input = try allocator.alloc(u8, 50)`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdin = std.io.getStdIn();\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var input = try allocator.alloc(u8, 50);\n    defer allocator.free(input);\n    for (0..input.len) |i| {\n        input[i] = 0; // initialize all fields to zero.\n    }\n    // read user input\n    const input_reader = stdin.reader();\n    _ = try input_reader.readUntilDelimiterOrEof(\n        input,\n        '\\n'\n    );\n    std.debug.print(\"{s}\\n\", .{input});\n}\n```\n:::\n\n\n\n\nAlso, notice that in this example, we use the `defer` keyword (which I described in @sec-defer) to run a small\npiece of code at the end of the current scope, which is the expression `allocator.free(input)`.\nWhen you execute this expression, the allocator will free the memory that it allocated\nfor the `input` object.\n\nWe have talked about this in @sec-heap. You **should always** explicitly free any memory that you allocate\nusing an allocator! You do that by using the `free()` method of the same allocator object you\nused to allocate this memory. The `defer` keyword is used in this example only to help us execute\nthis free operation at the end of the current scope.\n\n\n### The `create()` and `destroy()` methods\n\nWith the `alloc()` and `free()` methods, you can allocate memory to store multiple elements\nat once. In other words, with these methods, we always allocate an array to store multiple elements at once.\nBut what if you need enough space to store just a single item? Should you\nallocate an array of a single element through `alloc()`?\n\nThe answer is no! In this case,\nyou should use the `create()` method of the allocator object.\nEvery allocator object offers the `create()` and `destroy()` methods,\nwhich are used to allocate and free memory for a single item, respectively.\n\nSo, in essence, if you want to allocate memory to store an array of elements, you\nshould use `alloc()` and `free()`. But if you need to store just a single item,\nthen, the `create()` and `destroy()` methods are ideal for you.\n\nIn the example below, I'm defining a struct to represent an user of some sort.\nIt could be a user for a game, or software to manage resources, it doesn't mater.\nNotice that I use the `create()` method this time, to store a single `User` object\nin the program. Also notice that I use the `destroy()` method to free the memory\nused by this object at the end of the scope.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst User = struct {\n    id: usize,\n    name: []const u8,\n\n    pub fn init(id: usize, name: []const u8) User {\n        return .{ .id = id, .name = name };\n    }\n};\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const user = try allocator.create(User);\n    defer allocator.destroy(user);\n\n    user.* = User.init(0, \"Pedro\");\n}\n```\n:::\n",
+    "supporting": [
+      "01-memory_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/01-zig-weird/execute-results/html.json b/_freeze/Chapters/01-zig-weird/execute-results/html.json
index 7f926500..5bdb8502 100644
--- a/_freeze/Chapters/01-zig-weird/execute-results/html.json
+++ b/_freeze/Chapters/01-zig-weird/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "ba740c33772422f50c73c140fef90a2d",
+  "hash": "686bec0276a3623e1397e1b7ecac1bfa",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\nlanguage, it is still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. They really make it sometimes hard to debug\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscure the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that get's compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e. it is where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contain Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nTherefore, Zig contains a native build system in it, and\nwe can use this build system to write small scripts in Zig,\nwhich describes the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e. creating new objects)\nare made in Zig. You can create a new object in Zig by using the following syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). At @sec-assignments we talk more about objects in general.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that at @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIs worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt is like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portable C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nIn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e. the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. Thus, if you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith a \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, operations like accessing the `stdout` (or opening a file) on Windows\ndepends on resources that are available only at *runtime* (you will learn more about compile-time\nversus runtime at @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword at @sec-comptime.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation at a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues \n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described in @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig later in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig? \nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar to our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentation.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It is a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (on YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e. identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nIn contrast, if you use `var`, then, the object created is a variable object.\nWith `var` you can declare this object in your source code, and then,\nchange the value of this object how many times you want over future points\nin your source code.\n\nSo, using the same code example exposed above, if I change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it is an \"variable object\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIs important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code use this object while it is uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object. \n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e. if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to a special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It is discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also get's discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e. the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\nIs worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array. \n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it is a slice that\naccess all elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" at @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth at @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially at @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned at @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e. the start and the end of this range)\nis known at compile-time, the slice object that get's created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nat @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that get's created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e. a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can \ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n```\n:::\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat get's created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, the `slice` object have a runtime known range, because the end index of the range\nis not known at compile time. In other words, the size of the array at `buffer` is not known\nat compile time. When we execute this program, the size of the array might be 10, or, it might be 12\ndepending on where we execute it. Therefore, we don't know at compile time if\nthe slice object have a range of size 10, or, a range of size 12.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e. a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented at @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e. `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIs worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e. the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause it is much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e. if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it is a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIs important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig at @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers at @sec-root-file and especially at @sec-assignments.\n- How strings work in Zig at @sec-zig-strings.\n- How to use arrays and slices at @sec-arrays.\n- How to import functionality from other Zig modules at @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* at @sec-structs-and-oop.\n- Basic control flow syntax at @sec-zig-control-flow.\n- Enums at @sec-enum;\n- Pointers and Optionals at @sec-pointer;\n- Error handling with `try` and `catch` at @sec-error-handling;\n- Unit tests at @sec-unittests;\n- Vectors at @sec-vectors-simd;\n- Build System at @sec-build-system;\n\n\n\n\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\n\nlanguage, it's still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. Sometimes, they really make it hard to debug\n\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscure the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that gets compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e., where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contains Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nWe can use this build system to write small scripts in Zig,\nwhich describe the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e., creating new objects)\nare made in Zig. You can create a new object in Zig by using the syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). In @sec-assignments we talk more about objects in general.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that in @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIt's worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt's like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portable C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nIn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e., the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. If you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith an \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, on Windows, operations like accessing the `stdout` (or opening a file) depend on\nresources that are available only at *runtime* (you will learn more about compile-time versus runtime\nin @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerges from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword in @sec-comptime.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation in a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues\n\n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described in @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig later in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig?\nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar to our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentation.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It's a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (on YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e., identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nIn contrast, if you use `var`, then, the object created is a variable object.\nWith `var` you can declare this object in your source code, and then,\nchange the value of this object how many times you want over future points\nin your source code.\n\nSo, using the same code example exposed above, if I change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it's a \"variable object\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIt's important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code uses this object while it's uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object.\n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e., if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to a special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It's discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also gets discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e., the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\nIt's worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it's a slice that\naccesses all elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" in @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth in @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially in @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned in @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e., the start and the end of this range)\nis known at compile-time, the slice object that gets created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nin @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that gets created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e., a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can\ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n```\n:::\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat gets created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, the `slice` object have a runtime known range, because the end index of the range\nis not known at compile time. In other words, the size of the array at `buffer` is not known\nat compile time. When we execute this program, the size of the array might be 10, or, it might be 12\ndepending on where we execute it. Therefore, we don't know at compile time if\nthe slice object have a range of size 10, or, a range of size 12.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e., a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e., similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented in @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e., `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIt's worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e., a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e., the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause it's much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e., if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it's a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIt's important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig in @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers in @sec-root-file and especially in @sec-assignments.\n- How strings work in Zig in @sec-zig-strings.\n- How to use arrays and slices in @sec-arrays.\n- How to import functionality from other Zig modules in @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* in @sec-structs-and-oop.\n- Basic control flow syntax in @sec-zig-control-flow.\n- Enums in @sec-enum;\n- Pointers and Optionals in @sec-pointer;\n- Error handling with `try` and `catch` in @sec-error-handling;\n- Unit tests in @sec-unittests;\n- Vectors in @sec-vectors-simd;\n- Build System in @sec-build-system;\n",
+    "supporting": [
+      "01-zig-weird_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/02-debugging/execute-results/html.json b/_freeze/Chapters/02-debugging/execute-results/html.json
index 5b18dbcb..2068b83e 100644
--- a/_freeze/Chapters/02-debugging/execute-results/html.json
+++ b/_freeze/Chapters/02-debugging/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "81acc8dfbc423fbdea18f9b7f8f1ea18",
+  "hash": "f6eea7230762e3b8cde487458c00b745",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Debugging Zig applications\n\nBeing able to debug your applications is essential for any programmer who wants to\ndo serious programming in any language. That is why, in this chapter, we are going to talk about the\navailable strategies and tools to debug applications written in Zig.\n\n\n## Print debugging\n\nWe begin with the classic and battle-tested *print debugging* strategy.\nThe key advantage that debugging offers you is *visibility*.\nWith *print statements* you can easily see what results and objects\nare being produced by your application.\n\nThat is the essence of *print debugging*. Is to use\nprint expressions to see the values that are being generated by your program,\nand, as a result, get a much better understanding of how your program\nis behaving.\n\nMany programmers often resort to the print functions in Zig, such as the `stdout.print()`,\nor, the `std.debug.print()`, to get a better understanding of their programs.\nThis is a known and old strategy that is very simple and effective, and it is better known within\nthe programming community as *print debugging*.\nIn Zig, you can print information to the `stdout` or `stderr` streams of your system.\n\nLet's begin with `stdout`. First, you\nneed to get access to the `stdout`, by calling the `getStdOut()` method, from\nthe Zig Standard Library. This method returns a *file descriptor* object,\nand, through this object you can read/write to the `stdout`.\nI recommend you to check out all methods available in this object, by [checking the page in\nthe Zig Standard Library Official Reference for the type `File`](https://ziglang.org/documentation/master/std/#std.fs.File)[^zig-fiile-reference].\n\n[^zig-fiile-reference]: <https://ziglang.org/documentation/master/std/#std.fs.File>.\n\nFor our purpose here, which is to write something to the `stdout`, especially to debug our\nprogram, I recommend you to use the `writer()` method, which gives you a *writer* object.\nThis *writer* object offers some helper methods to write stuff into the file descriptor object\nthat represents the `stdout` stream. In special, the `print()` method.\n\n\nThe `print()` method from this *writer* object is a \"print formatter\" type of a function.\nIn other words, this method works exactly like the `printf()` function from C,\nor, like `println!()` from Rust.\nIn the first argument of the function, you specify a template string, and,\nin the second argument, you provide a list of values (or objects) that you want to insert\ninto your template message.\n\nIdeally, the template string in the first argument should contain some format specifier.\nEach format specifier is matched to a value (or object) that you have listed in the second argument.\nSo, if you provided 5 different objects in the second argument, then, the template string\nshould contain 5 format specifiers, one for each object provided.\n\nEach format specifier is represented by a single letter, and\nyou provide this format specifier inside a pair of curly braces. So, if you want to format\nyour object using the string specifier (`s`), then, you can insert the text `{s}` in your template string.\nHere is a quick list of the most used format specifiers:\n\n- `d`: for printing integers and floating-point numbers.\n- `c`: for printing characters.\n- `s`: for printing strings.\n- `p`: for printing memory addresses.\n- `x`: for printing hexadecimal values.\n- `any`: use any compatible format specifier (i.e. it automatically selects a format specifier for you).\n\nThe code example below gives you an example of use of this `print()` method\nwith the `d` format specifier.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    try stdout.print(\"Result: {d}\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\n\n\nIt is important to emphasize that, the `stdout.print()` method, as you would expect,\nprints your template string into the `stdout` stream of your system.\nHowever, you can also print your template string into the `stderr` stream\nif your prefer. All you need to do, is to replace the `stdout.print()`\ncall with the function `std.debug.print()`. Like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    std.debug.print(\"Result: {d}\\n\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\n\n\n\nYou could also achieve the exact same result by getting a file descriptor object to `stderr`,\nthen, creating a *writer* object to `stderr`, then, using the `print()` method of this\n*writer* object, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stderr = std.io.getStdErr().writer();\n// some more lines ...\ntry stderr.print(\"Result: {d}\", .{result});\n```\n:::\n\n\n\n\n\n\n## Debugging through debuggers\n\nAlthough *print debugging* is a valid and very useful strategy,\nmost programmers prefer to use a debugger to debug their programs.\nSince Zig is a low-level language, you can use either GDB (GNU Debugger),\nor LLDB (LLVM Project Debugger) as your debugger.\n\nBoth debuggers can work with Zig code, and it's a matter of taste here.\nYou choose the debugger of your preference, and you work with it.\nIn this book, I will use LLDB as my debugger on the examples.\n\n\n### Compile your source code in debug mode {#sec-compile-debug-mode}\n\nIn order to debug your program through a debugger, you must compile\nyour source code in `Debug` mode. Because when you compile your\nsource code in other modes (such as `Release`), the compiler usually\nstrips out some essential information that is used by the debugger\nto read and track your program, like PDB (*Program Database*) files.\n\nBy compiling your source code in `Debug` mode, you ensure that the debugger\nwill find the necessary information in your program to debug it.\nBy default, the compiler uses the `Debug` mode when compiling your code.\nHaving this in mind, when you compile your program with the `build-exe`\ncommand (which was described at @sec-compile-code), if you don't specify\nan explicit mode through the `-O` command-line [^oargument]\nargument, then, the compiler will compile your code in `Debug` mode.\n\n[^oargument]: See <https://ziglang.org/documentation/master/#Debug>.\n\n\n### Let's debug a program\n\nAs an example, let's use LLDB to navigate and investigate the following\npiece of Zig code:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\nfn add_and_increment(a: u8, b: u8) u8 {\n    const sum = a + b;\n    const incremented = sum + 1;\n    return incremented;\n}\n\npub fn main() !void {\n    var n = add_and_increment(2, 3);\n    n = add_and_increment(n, n);\n    try stdout.print(\"Result: {d}!\\n\", .{n});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 13!\n```\n\n\n:::\n:::\n\n\n\n\nThere is nothing wrong with this program. But it is\na good start for us. First, we need to compile\nthis program with the `zig build-exe` command.\nFor this example, suppose that I have compiled the above\nZig code into a binary executable called `add_program`.\n\n```bash\nzig build-exe add_program.zig\n```\n\nNow, we can start LLDB with `add_program`, like this:\n\n```bash\nlldb add_program\n```\n\nFrom now on, LLDB is started, and you can know that I'm\nexecuting LLDB commands by looking at the prefix `(lldb)`.\nIf something is prefixed with `(lldb)`, then you know\nthat it is a LLDB command.\n\nThe first thing I will do, is to set a breakpoint at\nthe `main()` function, by executing `b main`.\nAfter that, I just start the execution of the program\nwith `run`.\nYou can see in the output below, that the execution\nstopped at the first line in the function `main()`, as we expected.\n\n```bash\n(lldb) b main\nBreakpoint 1: where = debugging`debug1.main + 22\n    at debug1.zig:11:30, address = 0x00000000010341a6\n(lldb) run\nProcess 8654 launched: 'add_program' (x86_64)\nProcess 8654 stopped\n* thread #1, name = 'add_program',\n    stop reason = breakpoint 1.1 frame #0: 0x10341a6\n    add_program`debug1.main at add_program.zig:11:30\n   8   \t}\n   9\n   10  \tpub fn main() !void {\n-> 11  \t    var n = add_and_increment(2, 3);\n   12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n```\n\nI can start navigating through the code, and checking the objects\nthat are being generated. If you are not familiar with the commands\navailable in LLDB, I recommend you to read the official documentation\nof the project[^lldb].\nYou can also look for cheat sheets, which quickly describes all commands\navailable for you[^lldb-quick-list].\n\n[^lldb]: <https://lldb.llvm.org/>\n[^lldb-quick-list]: <https://gist.github.com/ryanchang/a2f738f0c3cc6fbd71fa>.\n\nCurrently, we are in the first line at the `main()` function. In this line, we create\nthe `n` object, by executing the `add_and_increment()` function.\nTo execute the current line of code, and go to the next line, we can\nrun the `n` LLDB command. Let's execute this command.\n\nAfter we executed this line, we can also look at the value stored inside this `n` object\nby using the `p` LLDB command. The syntax for this command is `p <name-of-object>`.\n\nIf we take a look at the value stored in the `n` object (`p n`),\nnotice that it stores the hexadecimal value `0x06`, which\nis the number 6 in decimal. We can also see that this value has a type of `unsigned char`,\nwhich is an unsigned 8-bit integer.\nWe have talked already about this at @sec-zig-strings, that `u8` integers in Zig are equivalent\nto the C data type `unsigned char`.\n\n\n\n```bash\n(lldb) n\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step over frame #0: 0x10341ae\n    debugging`debug1.main at debug1.zig:12:26\n   9\n   10  \tpub fn main() !void {\n   11  \t    var n = add_and_increment(2, 3);\n-> 12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n(lldb) p n\n(unsigned char) $1 = '\\x06'\n```\n\nNow, on the next line of code, we are executing the `add_and_increment()` function once again.\nWhy not step inside this function? Shall we? We can do that, by executing the `s` LLDB command.\nNotice in the example below that, after executing this command, we have entered into the context of the\n`add_and_increment()` function.\n\nAlso notice in the example below that, I have walked two more lines in the function's body, then,\nI execute the `frame variable` LLDB command, to see at once, the value stored in each of the variables\nthat were created inside the current scope.\n\nYou can see in the output below that, the object `sum` stores the value `\\f`,\nwhich represents the *form feed* character. This character in the ASCII table,\ncorresponds to the hexadecimal value `0x0C`, or, in decimal, the number 12.\nSo, this means that the result of the expression `a + b` executed at line\n5, resulted in the number 12.\n\n```bash\n(lldb) s\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step in frame #0: 0x10342de\n    debugging`debug1.add_and_increment(a='\\x02', b='\\x03')\n    at debug1.zig:4:39\n-> 4   \tfn add_and_increment(a: u8, b: u8) u8 {\n   5   \t    const sum = a + b;\n   6   \t    const incremented = sum + 1;\n   7   \t    return incremented;\n(lldb) n\n(lldb) n\n(lldb) frame variable\n(unsigned char) a = '\\x06'\n(unsigned char) b = '\\x06'\n(unsigned char) sum = '\\f'\n(unsigned char) incremented = '\\x06'\n```\n\n\n\n## How to investigate the data type of your objects\n\nSince Zig is a strongly-typed language, the data types associated with your objects\nare very important for your program. So, debugging the data types associated\nwith your objects might be important to understand bugs and errors in your program.\n\nWhen you walk through your program with a debugger, you can inspect the types of\nyour objects by simply printing them to the console, with the LLDB `p` command.\nBut you also have alternatives embedded in the language itself to access the data\ntypes of your objects.\n\nIn Zig, you can retrieve the data type of an object, by using the built-in function\n`@TypeOf()`. Just apply this function over the object, and you get access to\nthe data type of the object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst expect = std.testing.expect;\n\npub fn main() !void {\n    const number: i32 = 5;\n    try expect(@TypeOf(number) == i32);\n    try stdout.print(\"{any}\\n\", .{@TypeOf(number)});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ni32\n```\n\n\n:::\n:::\n\n\n\n\nThis function is similar to the `type()` built-in function from Python,\nor, the `typeof` operator in Javascript.\n\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Debugging Zig applications\n\nBeing able to debug your applications is essential for any programmer who wants to\ndo serious programming in any language. That is why, in this chapter, we are going to talk about the\navailable strategies and tools to debug applications written in Zig.\n\n\n## Print debugging\n\nWe begin with the classic and battle-tested *print debugging* strategy.\nThe key advantage that debugging offers you is *visibility*.\nWith *print statements* you can easily see what results and objects\nare being produced by your application.\n\nThis is the essence of *print debugging* - using\nprint expressions to see the values that are being generated by your program,\nand, as a result, get a much better understanding of how your program\nis behaving.\n\nMany programmers often resort to the print functions in Zig, such as the `stdout.print()`,\nor, the `std.debug.print()`, to get a better understanding of their programs.\nThis is a known and old strategy that is very simple and effective, and it's better known within\nthe programming community as *print debugging*.\nIn Zig, you can print information to the `stdout` or `stderr` streams of your system.\n\nLet's begin with `stdout`. First, you\nneed to get access to the `stdout`, by calling the `getStdOut()` method, from\nthe Zig Standard Library. This method returns a *file descriptor* object,\nand, through this object you can read/write to the `stdout`.\nI recommend you to check out all methods available in this object, by [checking the page in\nthe Zig Standard Library Official Reference for the type `File`](https://ziglang.org/documentation/master/std/#std.fs.File)[^zig-fiile-reference].\n\n[^zig-fiile-reference]: <https://ziglang.org/documentation/master/std/#std.fs.File>.\n\nFor our purpose here, which is to write something to the `stdout`, especially to debug our\nprogram, I recommend you to use the `writer()` method, which gives you a *writer* object.\nThis *writer* object offers some helper methods to write stuff into the file descriptor object\nthat represents the `stdout` stream. In special, the `print()` method.\n\n\nThe `print()` method from this *writer* object is a \"print formatter\" type of a function.\nIn other words, this method works exactly like the `printf()` function from C,\nor, like `println!()` from Rust.\nIn the first argument of the function, you specify a template string, and,\nin the second argument, you provide a list of values (or objects) that you want to insert\ninto your template message.\n\nIdeally, the template string in the first argument should contain some format specifier.\nEach format specifier is matched to a value (or object) that you have listed in the second argument.\nSo, if you provided 5 different objects in the second argument, then, the template string\nshould contain 5 format specifiers, one for each object provided.\n\nEach format specifier is represented by a single letter, and\nyou provide this format specifier inside a pair of curly braces. So, if you want to format\nyour object using the string specifier (`s`), then, you can insert the text `{s}` in your template string.\nHere is a quick list of the most used format specifiers:\n\n- `d`: for printing integers and floating-point numbers.\n- `c`: for printing characters.\n- `s`: for printing strings.\n- `p`: for printing memory addresses.\n- `x`: for printing hexadecimal values.\n- `any`: use any compatible format specifier (i.e., it automatically selects a format specifier for you).\n\nThe code example below gives you an example of use of this `print()` method\nwith the `d` format specifier.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    try stdout.print(\"Result: {d}\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\n\n\nIt's important to emphasize that, the `stdout.print()` method, as you would expect,\nprints your template string into the `stdout` stream of your system.\nHowever, you can also print your template string into the `stderr` stream\nif your prefer. All you need to do, is to replace the `stdout.print()`\ncall with the function `std.debug.print()`. Like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    std.debug.print(\"Result: {d}\\n\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\n\n\n\nYou could also achieve the exact same result by getting a file descriptor object to `stderr`,\nthen, creating a *writer* object to `stderr`, then, using the `print()` method of this\n*writer* object, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stderr = std.io.getStdErr().writer();\n// some more lines ...\ntry stderr.print(\"Result: {d}\", .{result});\n```\n:::\n\n\n\n\n\n\n## Debugging through debuggers\n\nAlthough *print debugging* is a valid and very useful strategy,\nmost programmers prefer to use a debugger to debug their programs.\nSince Zig is a low-level language, you can use either GDB (GNU Debugger),\nor LLDB (LLVM Project Debugger) as your debugger.\n\nBoth debuggers can work with Zig code, and it's a matter of taste here.\nYou choose the debugger of your preference, and you work with it.\nIn this book, I will use LLDB as my debugger in the examples.\n\n\n### Compile your source code in debug mode {#sec-compile-debug-mode}\n\nIn order to debug your program through a debugger, you must compile\nyour source code in `Debug` mode. Because when you compile your\nsource code in other modes (such as `Release`), the compiler usually\nstrips out some essential information that is used by the debugger\nto read and track your program, like PDB (*Program Database*) files.\n\nBy compiling your source code in `Debug` mode, you ensure that the debugger\nwill find the necessary information in your program to debug it.\nBy default, the compiler uses the `Debug` mode when compiling your code.\nHaving this in mind, when you compile your program with the `build-exe`\ncommand (which was described in @sec-compile-code), if you don't specify\nan explicit mode through the `-O` command-line [^oargument]\nargument, then, the compiler will compile your code in `Debug` mode.\n\n[^oargument]: See <https://ziglang.org/documentation/master/#Debug>.\n\n\n### Let's debug a program\n\nAs an example, let's use LLDB to navigate and investigate the following\npiece of Zig code:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\nfn add_and_increment(a: u8, b: u8) u8 {\n    const sum = a + b;\n    const incremented = sum + 1;\n    return incremented;\n}\n\npub fn main() !void {\n    var n = add_and_increment(2, 3);\n    n = add_and_increment(n, n);\n    try stdout.print(\"Result: {d}!\\n\", .{n});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 13!\n```\n\n\n:::\n:::\n\n\n\n\nThere is nothing wrong with this program. But it's\na good start for us. First, we need to compile\nthis program with the `zig build-exe` command.\nFor this example, suppose that I have compiled the above\nZig code into a binary executable called `add_program`.\n\n```bash\nzig build-exe add_program.zig\n```\n\nNow, we can start LLDB with `add_program`, like this:\n\n```bash\nlldb add_program\n```\n\nFrom now on, LLDB is started, and you can know that I'm\nexecuting LLDB commands by looking at the prefix `(lldb)`.\nIf something is prefixed with `(lldb)`, then you know\nthat it's a LLDB command.\n\nThe first thing I will do, is to set a breakpoint at\nthe `main()` function, by executing `b main`.\nAfter that, I just start the execution of the program\nwith `run`.\nYou can see in the output below, that the execution\nstopped at the first line in the function `main()`, as we expected.\n\n```bash\n(lldb) b main\nBreakpoint 1: where = debugging`debug1.main + 22\n    at debug1.zig:11:30, address = 0x00000000010341a6\n(lldb) run\nProcess 8654 launched: 'add_program' (x86_64)\nProcess 8654 stopped\n* thread #1, name = 'add_program',\n    stop reason = breakpoint 1.1 frame #0: 0x10341a6\n    add_program`debug1.main at add_program.zig:11:30\n   8   \t}\n   9\n   10  \tpub fn main() !void {\n-> 11  \t    var n = add_and_increment(2, 3);\n   12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n```\n\nI can start navigating through the code, and checking the objects\nthat are being generated. If you are not familiar with the commands\navailable in LLDB, I recommend you to read the official documentation\nof the project[^lldb].\nYou can also look for cheat sheets, which quickly describes all commands\navailable for you[^lldb-quick-list].\n\n[^lldb]: <https://lldb.llvm.org/>\n[^lldb-quick-list]: <https://gist.github.com/ryanchang/a2f738f0c3cc6fbd71fa>.\n\nCurrently, we are in the first line at the `main()` function. In this line, we create\nthe `n` object, by executing the `add_and_increment()` function.\nTo execute the current line of code, and go to the next line, we can\nrun the `n` LLDB command. Let's execute this command.\n\nAfter we executed this line, we can also look at the value stored inside this `n` object\nby using the `p` LLDB command. The syntax for this command is `p <name-of-object>`.\n\nIf we take a look at the value stored in the `n` object (`p n`),\nnotice that it stores the hexadecimal value `0x06`, which\nis the number 6 in decimal. We can also see that this value has a type of `unsigned char`,\nwhich is an unsigned 8-bit integer.\nWe have talked already about this in @sec-zig-strings, that `u8` integers in Zig are equivalent\nto the C data type `unsigned char`.\n\n\n\n```bash\n(lldb) n\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step over frame #0: 0x10341ae\n    debugging`debug1.main at debug1.zig:12:26\n   9\n   10  \tpub fn main() !void {\n   11  \t    var n = add_and_increment(2, 3);\n-> 12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n(lldb) p n\n(unsigned char) $1 = '\\x06'\n```\n\nNow, on the next line of code, we are executing the `add_and_increment()` function once again.\nWhy not step inside this function? Shall we? We can do that, by executing the `s` LLDB command.\nNotice in the example below that, after executing this command, we have entered into the context of the\n`add_and_increment()` function.\n\nAlso notice in the example below that, I have walked two more lines in the function's body, then,\nI execute the `frame variable` LLDB command, to see at once, the value stored in each of the variables\nthat were created inside the current scope.\n\nYou can see in the output below that, the object `sum` stores the value `\\f`,\nwhich represents the *form feed* character. This character in the ASCII table,\ncorresponds to the hexadecimal value `0x0C`, or, in decimal, the number 12.\nSo, this means that the result of the expression `a + b` executed at line\n5, resulted in the number 12.\n\n```bash\n(lldb) s\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step in frame #0: 0x10342de\n    debugging`debug1.add_and_increment(a='\\x02', b='\\x03')\n    at debug1.zig:4:39\n-> 4   \tfn add_and_increment(a: u8, b: u8) u8 {\n   5   \t    const sum = a + b;\n   6   \t    const incremented = sum + 1;\n   7   \t    return incremented;\n(lldb) n\n(lldb) n\n(lldb) frame variable\n(unsigned char) a = '\\x06'\n(unsigned char) b = '\\x06'\n(unsigned char) sum = '\\f'\n(unsigned char) incremented = '\\x06'\n```\n\n\n\n## How to investigate the data type of your objects\n\nSince Zig is a strongly-typed language, the data types associated with your objects\nare very important for your program. So, debugging the data types associated\nwith your objects might be important to understand bugs and errors in your program.\n\nWhen you walk through your program with a debugger, you can inspect the types of\nyour objects by simply printing them to the console, with the LLDB `p` command.\nBut you also have alternatives embedded in the language itself to access the data\ntypes of your objects.\n\nIn Zig, you can retrieve the data type of an object, by using the built-in function\n`@TypeOf()`. Just apply this function over the object, and you get access to\nthe data type of the object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst expect = std.testing.expect;\n\npub fn main() !void {\n    const number: i32 = 5;\n    try expect(@TypeOf(number) == i32);\n    try stdout.print(\"{any}\\n\", .{@TypeOf(number)});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ni32\n```\n\n\n:::\n:::\n\n\n\n\nThis function is similar to the `type()` built-in function from Python,\nor, the `typeof` operator in Javascript.\n",
+    "supporting": [
+      "02-debugging_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/03-structs/execute-results/html.json b/_freeze/Chapters/03-structs/execute-results/html.json
index 2629908d..8781660b 100644
--- a/_freeze/Chapters/03-structs/execute-results/html.json
+++ b/_freeze/Chapters/03-structs/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "ddf3054f897e82f090f3aa7c5890ec78",
+  "hash": "ec9ff8aaff4376d4eab0dd3ee150d725",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Control flow, structs, modules and types\n\nWe have discussed a lot of Zig's syntax in the last chapter,\nespecially in @sec-root-file and @sec-main-file.\nBut we still need to discuss some other very important\nelements of the language. Elements that you will use constantly on your day-to-day\nroutine.\n\nWe begin this chapter by discussing the different keywords and structures\nin Zig related to control flow (e.g. loops and if statements).\nThen, we talk about structs and how they can be used to do some\nbasic Object-Oriented (OOP) patterns in Zig. We also talk about\ntype inference and type casting.\nFinally, we end this chapter by discussing modules, and how they relate\nto structs.\n\n\n\n## Control flow {#sec-zig-control-flow}\n\nSometimes, you need to make decisions in your program. Maybe you need to decide\nwhether or not to execute a specific piece of code. Or maybe,\nyou need to apply the same operation over a sequence of values. These kinds of tasks,\ninvolve using structures that are capable of changing the \"control flow\" of our program.\n\nIn computer science, the term \"control flow\" usually refers to the order in which expressions (or commands)\nare evaluated in a given language or program. But this term is also used to refer\nto structures that are capable of changing this \"evaluation order\" of the commands\nexecuted by a given language/program.\n\nThese structures are better known\nby a set of terms, such as: loops, if/else statements, switch statements, among others. So,\nloops and if/else statements are examples of structures that can change the \"control\nflow\" of our program. The keywords `continue` and `break` are also examples of symbols\nthat can change the order of evaluation, since they can move our program to the next iteration\nof a loop, or make the loop stop completely.\n\n\n### If/else statements\n\nAn if/else statement performs a \"conditional flow operation\".\nA conditional flow control (or choice control) allows you to execute\nor ignore a certain block of commands based on a logical condition.\nMany programmers and computer science professionals also use\nthe term \"branching\" in this case.\nIn essence, an if/else statement allow us to use the result of a logical test\nto decide whether or not to execute a given block of commands.\n\nIn Zig, we write if/else statements by using the keywords `if` and `else`.\nWe start with the `if` keyword followed by a logical test inside a pair\nof parentheses, followed by a pair of curly braces which contains the lines\nof code to be executed in case the logical test returns the value `true`.\n\nAfter that, you can optionally add an `else` statement. To do that, just add the `else`\nkeyword followed by a pair of curly braces, with the lines of code\nto executed in case the logical test defined at `if` returns `false`.\n\nIn the example below, we are testing if the object `x` contains a number\nthat is greater than 10. Judging by the output printed to the console,\nwe know that this logical test returned `false`. Because the output\nin the console is compatible with the line of code present in the\n`else` branch of the if/else statement.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x = 5;\nif (x > 10) {\n    try stdout.print(\n        \"x > 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x <= 10!\\n\", .{}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nx <= 10!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Switch statements {#sec-switch}\n\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust.\nAs you would expect, to write a switch statement in Zig we use the `switch` keyword.\nWe provide the value that we want to \"switch over\" inside a\npair of parentheses. Then, we list the possible combinations (or \"branches\")\ninside a pair of curly braces.\n\nLet's take a look at the code example below. You can see that\nI'm creating an enum type called `Role`. We talk more about enums in @sec-enum.\nBut in summary, this `Role` type is listing different types of roles in a fictitious\ncompany, like `SE` for Software Engineer, `DE` for Data Engineer, `PM` for Product Manager,\netc.\n\nNotice that we are using the value from the `role` object in the\nswitch statement, to discover which exact area we need to store in the `area` variable object.\nAlso notice that we are using type inference inside the switch statement, with the dot character,\nas we are going to describe in @sec-type-inference.\nThis makes the `zig` compiler infer the correct data type of the values (`PM`, `SE`, etc.) for us.\n\nAlso notice that, we are grouping multiple values in the same branch of the switch statement.\nWe just separate each possible value with a comma. For example, if `role` contains either `DE` or `DA`,\nthe `area` variable would contain the value `\"Data & Analytics\"`, instead of `\"Platform\"` or `\"Sales\"`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO => {\n            area = \"Platform\";\n        },\n        .DE, .DA => {\n            area = \"Data & Analytics\";\n        },\n        .KS => {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nPlatform\n```\n\n\n:::\n:::\n\n\n\n\n\n#### Switch statements must exhaust all possibilities\n\nOne very important aspect about switch statements in Zig\nis that they must exhaust all existing possibilities.\nIn other words, all possible values that could be found inside the `role`\nobject must be explicitly handled in this switch statement.\n\nSince the `role` object has type `Role`, the only possible values to\nbe found inside this object are `PM`, `SE`, `DPE`, `PO`, `DE`, `DA` and `KS`.\nThere are no other possible values to be stored in this `role` object.\nThus, the switch statements must have a combination (branch) for each one of these values.\nThis is what \"exhaust all existing possibilities\" means. The switch statement covers\nevery possible case.\n\nTherefore, you cannot write a switch statement in Zig, and leave an edge case\nwith no explicit action to be taken.\nThis is a similar behaviour to switch statements in Rust, which also have to\nhandle all possible cases.\n\n\n\n#### The else branch\n\nTake a look at the `dump_hex_fallible()` function below as an example. This function\ncomes from the Zig Standard Library. More precisely, from the\n[`debug.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/debug.zig)[^debug-mod].\nThere are multiple lines in this function, but I omitted them to focus solely on the\nswitch statement found in this function. Notice that this switch statement has four\npossible cases (i.e. four explicit branches). Also, notice that we used an `else` branch\nin this case.\n\nAn `else` branch in a switch statement works as the \"default branch\".\nWhenever you have multiple cases in your switch statement where\nyou want to apply the exact same action, you can use an `else` branch to do that.\n\n[^debug-mod]: <https://github.com/ziglang/zig/blob/master/lib/std/debug.zig>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' => try writer.writeAll(\"␊\"),\n        '\\r' => try writer.writeAll(\"␍\"),\n        '\\t' => try writer.writeAll(\"␉\"),\n        else => try writer.writeByte('.'),\n    }\n}\n```\n:::\n\n\n\n\nMany programmers would also use an `else` branch to handle a \"not supported\" case.\nThat is, a case that cannot be properly handled by your code, or, just a case that\nshould not be \"fixed\". Therefore, you can use an `else` branch to panic (or raise an error)\nin your program to stop the current execution.\n\nTake the code example below. We can see that, we are handling the cases\nfor the `level` object being either 1, 2, or 3. All other possible cases are not supported by default,\nand, as consequence, we raise a runtime error in such cases through the `@panic()` built-in function.\n\nAlso notice that, we are assigning the result of the switch statement to a new object called `category`.\nThis is another thing that you can do with switch statements in Zig. If a branch\noutputs a value as result, you can store the result value of the switch statement into\na new object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 => \"beginner\",\n    3 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n:::\n\n\n\n\n```\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n```\n\n\n\n#### Using ranges in switch\n\nFurthermore, you can also use ranges of values in switch statements.\nThat is, you can create a branch in your switch statement that is used\nwhenever the input value is within the specified range. These \"range expressions\"\nare created with the operator `...`. It is important\nto emphasize that the ranges created by this operator are\ninclusive on both ends.\n\nFor example, I could easily change the previous code example to support all\nlevels between 0 and 100. Like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 => \"beginner\",\n    26...75 => \"intermediary\",\n    76...100 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nbeginner\n```\n\n\n:::\n:::\n\n\n\n\nThis is neat, and it works with character ranges too. That is, I could\nsimply write `'a'...'z'`, to match any character value that is a\nlowercase letter, and it would work fine.\n\n\n#### Labeled switch statements\n\nIn @sec-blocks we have talked about labeling blocks, and also, about using these labels\nto return a value from the block. Well, from version 0.14.0 and onwards of the `zig` compiler,\nyou can also apply labels over switch statements, which makes it possible to almost implement a\n\"C `goto`\" like pattern.\n\nFor example, if you give the label `xsw` to a switch statement, you can use this\nlabel in conjunction with the `continue` keyword to go back to the beginning of the switch\nstatement. In the example below, the execution goes back to the beginning of the\nswitch statement two times, before ending at the `3` branch.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nxsw: switch (@as(u8, 1)) {\n    1 => {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 => continue :xsw 3,\n    3 => return,\n    4 => {},\n    else => {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n```\n:::\n\n\n\n\n\n### The `defer` keyword {#sec-defer}\n\nWith the `defer` keyword you can register an expression to be executed when you exit the current scope.\nTherefore, this keyword has a similar functionality as the `on.exit()` function from R.\nTake the `foo()` function below as an example. When we execute this `foo()` function, the expression\nthat prints the message \"Exiting function ...\" is getting executed only when the function exits\nits scope.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nAdding some numbers ...\nMultiplying ...\nExiting function ...\n```\n\nTherefore, we can use `defer` to declare an expression that is going to be executed\nwhen your code exits the current scope. Some programmers like to interpret the phrase \"exit of the current scope\"\nas \"the end of the current scope\". But this interpretation might not be entirely correct, depending\non what you consider as \"the end of the current scope\".\n\nI mean, what do you consider as **the end** of the current scope? Is it the closing curly bracket (`}`) of the scope?\nIs it when the last expression in the function gets executed? Is it when the function returns to the previous scope?\nEtc. For example, it would not be correct to interpret the \"exit of the current scope\" as the closing\ncurly bracket of the scope. Because the function might exit from an earlier position than this\nclosing curly bracket (e.g. an error value was generated at a previous line inside the function;\nthe function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\n\nNow, if you remember of what we have discussed in @sec-blocks, there are multiple structures in the language\nthat create their own separate scopes. For/while loops, if/else statements,\nfunctions, normal blocks, etc. This also affects the interpretation of `defer`.\nFor example, if you use `defer` inside a for loop, then, the given expression\nwill be executed everytime this specific for loop exits its own scope.\n\nBefore we continue, is worth emphasizing that the `defer` keyword is an \"unconditional defer\".\nWhich means that the given expression will be executed no matter how the code exits\nthe current scope. For example, your code might exit the current scope because of an error value\nbeing generated, or, because of a return statement, or, a break statement, etc.\n\n\n\n### The `errdefer` keyword {#sec-errdefer1}\n\nOn the previous section, we have discussed the `defer` keyword, which you can use to\nregister an expression to be executed at the exit of the current scope.\nBut this keyword has a brother, which is the `errdefer` keyword. While `defer`\nis an \"unconditional defer\", the `errdefer` keyword is a \"conditional defer\".\nWhich means that the given expression is executed only when you exit the current\nscope on a very specific circumstance.\n\nIn more details, the expression given to `errdefer` is executed only when an error occurs in the current scope.\nTherefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope\nin a normal situation, without errors, the expression given to `errdefer` is not executed.\n\nThis makes the `errdefer` keyword one of the many tools available in Zig for error handling.\nIn this section, we are more concerned with the control flow aspects around `errdefer`.\nBut we are going to discuss `errdefer` later as a error handling tool in @sec-errdefer2.\n\nThe code example below demonstrates three things:\n\n- that `defer` is an \"unconditional defer\", because the given expression get's executed regardless of how the function `foo()` exits its own scope.\n- that `errdefer` is executed because the function `foo()` returned an error value.\n- that `defer` and `errdefer` expressions are executed in a LIFO (*last in, first out*) order.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\nWhen I say that \"defer expressions\" are executed in a LIFO order, what I want to say is that\nthe last `defer` or `errdefer` expressions in the code are the first ones to be executed.\nYou could also interpret this as: \"defer expressions\" are executed from bottom to top, or,\nfrom last to first.\n\nTherefore, if I change the order of the `defer` and `errdefer` expressions, you will notice that\nthe value of `i` that get's printed to the console changes to 1. This doesn't mean that the\n`defer` expression was not executed in this case. This actually means that the `defer` expression\nwas executed only after the `errdefer` expression. The code example below demonstrates this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\n\n\n### For loops\n\nA loop allows you to execute the same lines of code multiple times,\nthus, creating a \"repetition space\" in the execution flow of your program.\nLoops are particularly useful when we want to replicate the same function\n(or the same set of commands) over different inputs.\n\nThere are different types of loops available in Zig. But the most\nessential of them all is probably the *for loop*. A for loop is\nused to apply the same piece of code over the elements of a slice, or, an array.\n\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from\nother languages. You start with the `for` keyword, then, you\nlist the items that you want to iterate\nover inside a pair of parentheses. Then, inside of a pair of pipes (`|`)\nyou should declare an identifier that will serve as your iterator, or,\nthe \"repetition index of the loop\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (items) |value| {\n    // code to execute\n}\n```\n:::\n\n\n\n\nTherefore, instead of using a `(value in items)` syntax,\nin Zig, for loops use the syntax `(items) |value|`. In the example\nbelow, you can see that we are looping through the items\nof the array stored at the object `name`, and printing to the\nconsole the decimal representation of each character in this array.\n\nIf we wanted, we could also iterate through a slice (or a portion) of\nthe array, instead of iterating through the entire array stored in the `name` object.\nJust use a range selector to select the section you want. For example,\nI could provide the expression `name[0..3]` to the for loop, to iterate\njust through the first 3 elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n80 | 101 | 100 | 114 | 111 | \n```\n\n\n:::\n:::\n\n\n\n\nIn the above example we are using the value itself of each\nelement in the array as our iterator. But there are many situations where\nwe need to use an index instead of the actual values of the items.\n\nYou can do that by providing a second set of items to iterate over.\nMore precisely, you provide the range selector `0..` to the for loop. So,\nyes, you can use two different iterators at the same time in a for\nloop in Zig.\n\nBut remember from @sec-assignments that, every object\nyou create in Zig must be used in some way. So if you declare two iterators\nin your for loop, you must use both iterators inside the for loop body.\nBut if you want to use just the index iterator, and not use the \"value iterator\",\nthen, you can discard the value iterator by maching the\nvalue items to the underscore character, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n:::\n\n\n\n\n```\n0 | 1 | 2 | 3 | 4 |\n```\n\n\n### While loops\n\nA while loop is created from the `while` keyword. A `for` loop\niterates through the items of an array, but a `while` loop\nwill loop continuously, and infinitely, until a logical test\n(specified by you) becomes false.\n\nYou start with the `while` keyword, then, you define a logical\nexpression inside a pair of parentheses, and the body of the\nloop is provided inside a pair of curly braces, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\nYou can also specify the increment expression to be used at the beginning of a while loop.\nTo do that, we write the increment expression inside a pair of parentheses after a colon character (`:`).\nThe code example below demonstrates this other pattern.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\n### Using `break` and `continue`\n\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using\nthe keywords `break` and `continue`, respectively. The `while` loop presented in the next code example is,\nat first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to `true`.\nBut what makes this `while` loop stop when the `i` object reaches the count\n10? It is the `break` keyword!\n\nInside the while loop, we have an if statement that is constantly checking if the `i` variable\nis equal to 10. Since we are incrementing the value of `i` at each iteration of the\nwhile loop, this `i` object will eventually be equal to 10, and when it is, the if statement\nwill execute the `break` expression, and, as a result, the execution of the while loop is stopped.\n\nNotice the use of the `expect()` function from the Zig Standard Library after the while loop.\nThis `expect()` function is an \"assert\" type of function.\nThis function checks if the logical test provided is equal to true. If so, the function do nothing.\nOtherwise (i.e. the logical test is equal to false), the function raises an assertion error.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nEverything worked!\n```\n\n\n:::\n:::\n\n\n\n\nSince this code example was executed successfully by the `zig` compiler,\nwithout raising any errors, we known that, after the execution of the while loop,\nthe `i` object is equal to 10. Because if it wasn't equal to 10, an error would have\nbeen raised by `expect()`.\n\nNow, in the next example, we have a use case for\nthe `continue` keyword. The if statement is constantly\nchecking if the current index is a multiple of 2. If\nit is, we jump to the next iteration of the loop.\nOtherwise, the loop just prints the current index to the console.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 3 | 5 | \n```\n\n\n:::\n:::\n\n\n\n\n\n\n## Function parameters are immutable {#sec-fun-pars}\n\nWe have already discussed a lot of the syntax behind function declarations in @sec-root-file and @sec-main-file.\nBut I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig.\nIn summary, function parameters are immutable in Zig.\n\nTake the code example below, where we declare a simple function that just tries to add\nsome amount to the input integer, and returns the result back. If you look closely\nat the body of this `add2()` function, you will notice that we try\nto save the result back into the `x` function argument.\n\nIn other words, this function not only uses the value that it received through the function argument\n`x`, but it also tries to change the value of this function argument, by assigning the addition result\ninto `x`. However, function arguments in Zig are immutable. You cannot change their values, or, you\ncannot assign values to them inside the body's function.\n\nThis is the reason why, the code example below does not compile successfully. If you try to compile\nthis code example, you will get a compile error message about \"trying to change the value of a\nimmutable (i.e. constant) object\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n\n\n```\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n```\n\n\n### A free optimization\n\nIf a function argument receives as input an object whose data type is\nany of the primitive types that we have listed in @sec-primitive-data-types,\nthis object is always passed by value to the function. In other words, this object\nis copied into the function stack frame.\n\nHowever, if the input object have a more complex data type, for example, it might\nbe a struct instance, or an array, or an union value, etc., in cases like that, the `zig` compiler\nwill take the liberty of deciding for you which strategy is best. Thus, the `zig` compiler will\npass your object to the function either by value, or by reference. The compiler will always\nchoose the strategy that is faster for you.\nThis optimization that you get for free is possible only because function arguments are\nimmutable in Zig.\n\n\n### How to overcome this barrier\n\nThere are some situations where you might need to change the value of your function argument\ndirectly inside the function's body. This happens more often when we are passing\nC structs as inputs to Zig functions.\n\nIn a situation like this, you can overcome this barrier by using a pointer. In other words,\ninstead of passing a value as input to the argument, you can pass a \"pointer to value\" instead.\nYou can change the value that the pointer points to, by dereferencing it.\n\nTherefore, if we take our previous `add2()` example, we can change the value of the\nfunction argument `x` inside the function's body by marking the `x` argument as a\n\"pointer to a `u32` value\" (i.e. `*u32` data type), instead of a `u32` value.\nBy making it a pointer, we can finally alter the value of this function argument directly inside\nthe body of the `add2()` function. You can see that the code example below compiles successfully.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n```\n:::\n\n\n\n\n```\nResult: 6\n```\n\n\nEven in this code example above, the `x` argument is still immutable. Which means that the pointer itself is immutable.\nTherefore, you cannot change the memory address that it points to. However, you can dereference the pointer\nto access the value that it points to, and also, to change this value, if you need to.\n\n\n\n\n\n## Structs and OOP {#sec-structs-and-oop}\n\nZig is a language more closely related to C (which is a procedural language),\nthan it is to C++ or Java (which are object-oriented languages). Because of that, you do not\nhave advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or\nclass inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\n\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C.\nYou give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can\nalso register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object\nthat you create with this new type, will always have these methods available and associated with them.\n\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which\nis used to construct (or, to instantiate) every object of this particular class, and we also have\na destructor method (or a destructor function), which is the function responsible for destroying\nevery object of this class.\n\nIn Zig, we normally declare the constructor and the destructor methods\nof our structs, by declaring an `init()` and a `deinit()` methods inside the struct.\nThis is just a naming convention that you will find across the entire Zig Standard Library.\nSo, in Zig, the `init()` method of a struct is normally the constructor method of the class represented by this struct.\nWhile the `deinit()` method is the method used for destroying an existing instance of that struct.\n\nThe `init()` and `deinit()` methods are both used extensively in Zig code, and you will see both of\nthem being used when we talk about allocators in @sec-allocators.\nBut, as another example, let's build a simple `User` struct to represent a user of some sort of system.\n\nIf you look at the `User` struct below, you can see the `struct` keyword.\nNotice the data members of this struct: `id`, `name` and `email`. Every data member has its\ntype explicitly annotated, with the colon character (`:`) syntax that we described earlier in @sec-root-file.\nBut also notice that every line in the struct body that describes a data member, ends with a comma character (`,`).\nSo every time you declare a data member in your Zig code, always end the line with a comma character, instead\nof ending it with the traditional semicolon character (`;`).\n\nNext, we have registered an `init()` function as a method\nof this `User` struct. This `init()` method is the constructor method that we will use to instantiate\nevery new `User` object. That is why this `init()` function returns a new `User` object as result.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    pub fn init(id: u64,\n                name: []const u8,\n                email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    pub fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\npedro\n```\n\n\n:::\n:::\n\n\n\n\nThe `pub` keyword plays an important role in struct declarations, and OOP in Zig.\nEvery method that you declare in your struct that is marked with the keyword `pub`,\nbecomes a public method of this particular struct.\n\nSo every method that you create inside your struct, is, at first, a private method\nof that struct. Meaning that, this method can only be called from within this\nstruct. But, if you mark this method as public, with the keyword `pub`, then,\nyou can call the method directly from an instance of the `User` struct.\n\nIn other words, the functions marked by the keyword `pub`\nare members of the public API of that struct.\nFor example, if I did not mark the `print_name()` method as public,\nthen, I could not execute the line `u.print_name()`. Because I would\nnot be authorized to call this method directly in my code.\n\n\n\n### Anonymous struct literals {#sec-anonymous-struct-literals}\n\nYou can declare a struct object as a literal value. When we do that, we normally specify the\ndata type of this struct literal by writing its data type just before the opening curly brace.\nFor example, I could write a struct literal value of the type `User` that we have defined\nin the previous section like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n```\n:::\n\n\n\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a\nstruct literal, but not specify explicitly the type of this particular struct.\nAn anonymous struct is written by using the syntax `.{}`. So, we essentially\nreplaced the explicit type of the struct literal with a dot character (`.`).\n\nAs we described in @sec-type-inference, when you put a dot before a struct literal,\nthe type of this struct literal is automatically inferred by the `zig` compiler.\nIn essence, the `zig` compiler will look for some hint of what is the type of that struct.\nThis hint can be the type annotation of a function argument,\nor the return type annotation of the function that you are using, or the type annotation\nof an existing object.\nIf the compiler does find such type annotation, it will use this\ntype in your literal struct.\n\nAnonymous structs are very commonly used as inputs to function arguments in Zig.\nOne example that you have seen already constantly, is the `print()`\nfunction from the `stdout` object.\nThis function takes two arguments.\nThe first argument, is a template string, which should\ncontain string format specifiers in it, which tells how the values provided\nin the second argument should be printed into the message.\n\nWhile the second argument is a struct literal that lists the values\nto be printed into the template message specified in the first argument.\nYou normally want to use an anonymous struct literal here, so that the\n`zig` compiler do the job of specifying the type of this particular\nanonymous struct for you.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello, world!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Struct declarations must be constant\n\nTypes in Zig must be `const` or `comptime` (we are going to talk more about comptime in @sec-comptime).\nWhat this means is that you cannot create a new data type, and mark it as variable with the `var` keyword.\nSo struct declarations are always constant. You cannot declare a new struct type using the `var` keyword.\nIt must be `const`.\n\nIn the `Vec3` example below, this declaration is allowed because I'm using the `const` keyword\nto declare this new data type.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n```\n:::\n\n\n\n\n\n### The `self` method argument {#sec-self-arg}\n\nIn every language that have OOP, when we declare a method of some class or struct, we\nusually declare this method as a function that has a `self` argument.\nThis `self` argument is the reference to the object itself from which the method\nis being called from.\n\nIt is not mandatory to use this `self` argument. But why would you not use this `self` argument?\nThere is no reason to not use it. Because the only way to get access to the data stored in the\ndata members of your struct is to access them through this `self` argument.\nIf you don't need to use the data in the data members of your struct inside your method, you very likely don't need\na method. You can just declare this logic as a simple function, outside of your\nstruct declaration.\n\n\nTake the `Vec3` struct below. Inside this `Vec3` struct we declared a method named `distance()`.\nThis method calculates the distance between two `Vec3` objects, by following the distance\nformula in euclidean space. Notice that this `distance()` method takes two `Vec3` objects\nas input, `self` and `other`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n```\n:::\n\n\n\n\n\nThe `self` argument corresponds to the `Vec3` object from which this `distance()` method\nis being called from. While the `other` is a separate `Vec3` object that is given as input\nto this method. In the example below, the `self` argument corresponds to the object\n`v1`, because the `distance()` method is being called from the `v1` object,\nwhile the `other` argument corresponds to the object `v2`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n```\n:::\n\n\n\n\n```\nDistance: 3.3970575502926055\n```\n\n\n\n### About the struct state\n\nSometimes you don't need to care about the state of your struct object. Sometimes, you just need\nto instantiate and use the objects, without altering their state. You can notice that when you have methods\ninside your struct declaration that might use the values that are present in the data members, but they\ndo not alter the values in these data members of the struct in anyway.\n\nThe `Vec3` struct that was presented in @sec-self-arg is an example of that.\nThis struct have a single method named `distance()`, and this method does use the values\npresent in all three data members of the struct (`x`, `y` and `z`). But at the same time,\nthis method does not change the values of these data members at any point.\n\nAs a result of that, when we create `Vec3` objects we usually create them as\nconstant objects, like the `v1` and `v2` objects presented in @sec-self-arg.\nWe can create them as variable objects with the `var` keyword,\nif we want to. But because the methods of this `Vec3` struct do not change\nthe state of the objects in any point, it's unnecessary to mark them\nas variable objects.\n\nBut why? Why am I talking about this here? It's because the `self` argument\nin the methods are affected depending on whether the\nmethods present in a struct change or don't change the state of the object itself.\nMore specifically, when you have a method in a struct that changes the state\nof the object (i.e. changes the value of a data member), the `self` argument\nin this method must be annotated in a different manner.\n\nAs I described in @sec-self-arg, the `self` argument in methods of\na struct is the argument that receives as input the object from which the method\nwas called from. We usually annotate this argument in the methods by writing `self`,\nfollowed by the colon character (`:`), and the data type of the struct to which\nthe method belongs to (e.g. `User`, `Vec3`, etc.).\n\nIf we take the `Vec3` struct that we defined in the previous section as an example,\nwe can see in the `distance()` method that this `self` argument is annotated as\n`self: Vec3`. Because the state of the `Vec3` object is never altered by this\nmethod.\n\nBut what if we do have a method that alters the state of the object, by altering the\nvalues of its data members, how should we annotate `self` in this instance? The answer is:\n\"we should annotate `self` as a pointer of `x`, instead of just `x`\".\nIn other words, you should annotate `self` as `self: *x`, instead of annotating it\nas `self: x`.\n\nIf we create a new method inside the `Vec3` object that, for example, expands the\nvector by multiplying its coordinates by a factor of two, then, we need to follow\nthis rule specified in the previous paragraph. The code example below demonstrates\nthis idea:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n```\n:::\n\n\n\n\nNotice in the code example above that we have added a new method\nto our `Vec3` struct named `twice()`. This method doubles the\ncoordinate values of our vector object. In the\ncase of the `twice()` method, we annotated the `self` argument as `*Vec3`,\nindicating that this argument receives a pointer (or a reference, if you prefer to call it this way)\nto a `Vec3` object as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n```\n:::\n\n\n\n\n```\nDoubled: 8.4\n```\n\n\n\nNow, if you change the `self` argument in this `twice()` method to `self: Vec3`, like in the\n`distance()` method, you will get the compiler error exposed below as result. Notice that this\nerror message is showing a line from the `twice()` method body,\nindicating that you cannot alter the value of the `x` data member.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n```\n:::\n\n\n\n\n```\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\n```\n\nThis error message indicates that the `x` data member belongs to a constant object,\nand, because of that, it cannot be changed. Ultimately, this error message\nis telling us that the `self` argument is constant.\n\nIf you take some time, and think hard about this error message, you will understand it.\nYou already have the tools to understand why we are getting this error message.\nWe have talked about it already in @sec-fun-pars.\nSo remember, every function argument is immutable in Zig, and `self`\nis no exception to this rule.\n\nIn this example, we marked the `v3` object as a variable object.\nBut this does not matter. Because it is not about the input object, it is about\nthe function argument.\n\nThe problem begins when we try to alter the value of `self` directly, which is a function argument,\nand, every function argument is immutable by default. You may ask yourself how can we overcome\nthis barrier, and once again, the solution was also discussed in @sec-fun-pars.\nWe overcome this barrier, by explicitly marking the `self` argument as a pointer.\n\n\n::: {.callout-note}\nIf a method of your `x` struct alters the state of the object, by\nchanging the value of any data member, then, remember to use `self: *x`,\ninstead of `self: x` in the function signature of this method.\n:::\n\n\nYou could also interpret the content discussed in this section as:\n\"if you need to alter the state of your `x` struct object in one of its methods,\nyou must explicitly pass the `x` struct object by reference to the `self` argument of this method\".\n\n\n\n## Type inference {#sec-type-inference}\n\nZig is a strongly typed language. But, there are some situations\nwhere you don't have to explicitly write the type of every single object in your source code,\nas you would expect from a traditional strongly typed language, such as C and C++.\n\nIn some situations, the `zig` compiler can use type inference to solve the data types for you, easing some of\nthe burden that you carry as a developer.\nThe most common way this happens is through function arguments that receive struct objects\nas input.\n\nIn general, type inference in Zig is done by using the dot character (`.`).\nEverytime you see a dot character written before a struct literal, or before an enum value, or something like that,\nyou know that this dot character is playing a special part in this place. More specifically, it is\ntelling the `zig` compiler something along the lines of: \"Hey! Can you infer the type of this\nvalue for me? Please!\". In other words, this dot character is playing a similar role as the `auto` keyword in C++.\n\nI gave you some examples of this in @sec-anonymous-struct-literals, where we used anonymous struct literals.\nAnonymous struct literals are, struct literals that use type inference to\ninfer the exact type of this particular struct literal.\nThis type inference is done by looking for some minimal hint of the correct data type to be used.\nYou could say that the `zig` compiler looks for any neighbouring type annotation that might tell it\nwhat the correct type would be.\n\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in @sec-switch).\nI also gave some other examples of type inference in @sec-switch, where we were inferring the data types of enum values listed inside\nof switch statements (e.g. `.DE`).\nBut as another example, take a look at this `fence()` function reproduced below,\nwhich comes from the [`atomic.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig)[^fence-fn]\nof the Zig Standard Library.\n\n[^fence-fn]: <https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig>.\n\nThere are a lot of things in this function that we haven't talked about yet, such as:\nwhat `comptime` means? `inline`? `extern`?\nLet's just ignore all of these things, and focus solely on the switch statement\nthat is inside this function.\n\nWe can see that this switch statement uses the `order` object as input. This `order`\nobject is one of the inputs of this `fence()` function, and we can see in the type annotation,\nthat this object is of type `AtomicOrder`. We can also see a bunch of values inside the\nswitch statements that begin with a dot character, such as `.release` and `.acquire`.\n\nBecause these weird values contain a dot character before them, we are asking the `zig`\ncompiler to infer the types of these values inside the switch statement. Then, the `zig`\ncompiler is looking into the current context where these values are being used, and it is\ntrying to infer the types of these values.\n\nSince they are being used inside a switch statement, the `zig` compiler looks into the type\nof the input object given to the switch statement, which is the `order` object in this case.\nBecause this object have type `AtomicOrder`, the `zig` compiler infers that these values\nare data members from this type `AtomicOrder`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic => @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire => tsan.__tsan_acquire(addr),\n            .release => tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst => {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n```\n:::\n\n\n\n\nThis is how basic type inference is done in Zig. If we didn't use the dot character before\nthe values inside this switch statement, then, we would be forced to explicitly write\nthe data types of these values. For example, instead of writing `.release` we would have to\nwrite `AtomicOrder.release`. We would have to do this for every single value\nin this switch statement, and this is a lot of work. That is why type inference\nis commonly used on switch statements in Zig.\n\n\n\n## Type casting {#sec-type-cast}\n\nIn this section, I want to discuss type casting (or, type conversion) with you.\nWe use type casting when we have an object of type \"x\", and we want to convert\nit into an object of type \"y\", i.e. we want to change the data type of the object.\n\nMost languages have a formal way to perform type casting. In Rust for example, we normally\nuse the keyword `as`, and in C, we normally use the type casting syntax, e.g. `(int) x`.\nIn Zig, we use the `@as()` built-in function to cast an object of type \"x\", into\nan object of type \"y\".\n\nThis `@as()` function is the preferred way to perform type conversion (or type casting)\nin Zig. Because it is explicit, and, it also performs the casting only if it\nis unambiguous and safe. To use this function, you just provide the target data type\nin the first argument, and, the object that you want cast as the second argument.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file9f8940318094.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\nThis is the general way to perform type casting in Zig. But remember, `@as()` works only when casting\nis unambiguous and safe, and there are situations where these assumptions do not hold. For example,\nwhen casting an integer value into a float value, or vice-versa, it is not clear to the compiler\nhow to perform this conversion safely.\n\nTherefore, we need to use specialized \"casting functions\" in such situations.\nFor example, if you want to cast an integer value into a float value, then, you\nshould use the `@floatFromInt()` function. In the inverse scenario, you should use\nthe `@intFromFloat()` function.\n\nIn these functions, you just provide the object that you want to\ncast as input. Then, the target data type of the \"type casting operation\" is determined by\nthe type annotation of the object where you are saving the results.\nIn the example below, we are casting the object `x` into a value of type `f32`,\nbecause the object `y`, which is where we are saving the results, is annotated\nas an object of type `f32`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file9f8954828844.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\nAnother built-in function that is very useful when performing type casting operations is `@ptrCast()`.\nIn essence, we use the `@as()` built-in function when we want to explicit convert (or cast) a Zig value/object\nfrom a type \"x\" to a type \"y\", etc. However, pointers (we are going to discuss pointers\nin more depth in @sec-pointer) are a special type of object in Zig,\ni.e. they are treated differently from \"normal objects\".\n\nEverytime a pointer is involved in some \"type casting operation\" in Zig, the `@ptrCast()` function is used.\nThis function works similarly to `@floatFromInt()`.\nYou just provide the pointer object that you want to cast as input to this function, and the\ntarget data type is, once again, determined by the type annotation of the object where the results are being\nstored.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file9f8944ca02e1.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## Modules\n\nWe already talked about what modules are, and also, how to import other modules into\nyour current module via *import statements*. Every Zig module (i.e. a `.zig` file) that you write in your project\nis internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the\nZig Standard Library into our current module.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n```\n:::\n\n\n\n\nWhen we want to access the functions and objects from the standard library, we\nare basically accessing the data members of the struct stored in the `std`\nobject. That is why we use the same syntax that we use in normal structs, with the dot operator (`.`)\nto access the data members and methods of the struct.\n\nWhen this \"import statement\" get's executed, the result of this expression is a struct\nobject that contains the Zig Standard Library modules, global variables, functions, etc.\nAnd this struct object get's saved (or stored) inside the constant object named `std`.\n\n\nTake the [`thread_pool.zig` module from the project `zap`](https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig)[^thread]\nas an example. This module is written as if it was\na big struct. That is why we have a top-level and public `init()` method\nwritten in this module. The idea is that all top-level functions written in this\nmodule are methods from the struct, and all top-level objects and struct declarations\nare data members of this struct. The module is the struct itself.\n\n[^thread]: <https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig>\n\n\nSo you would import and use this module by doing something like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst ThreadPool = @import(\"thread_pool.zig\");\nconst num_cpus = std.Thread.getCpuCount()\n    catch @panic(\"failed to get cpu core count\");\nconst num_threads = std.math.cast(u16, num_cpus)\n    catch std.math.maxInt(u16);\nconst pool = ThreadPool.init(\n    .{ .max_threads = num_threads }\n);\n```\n:::\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Control flow, structs, modules and types\n\nWe have discussed a lot of Zig's syntax in the last chapter,\nespecially in @sec-root-file and @sec-main-file.\nBut we still need to discuss some other very important\nelements of the language. Elements that you will use constantly on your day-to-day\nroutine.\n\nWe begin this chapter by discussing the different keywords and structures\nin Zig related to control flow (e.g. loops and if statements).\nThen, we talk about structs and how they can be used to do some\nbasic Object-Oriented (OOP) patterns in Zig. We also talk about\ntype inference and type casting.\nFinally, we end this chapter by discussing modules, and how they relate\nto structs.\n\n\n\n## Control flow {#sec-zig-control-flow}\n\nSometimes, you need to make decisions in your program. Maybe you need to decide\nwhether or not to execute a specific piece of code. Or maybe,\nyou need to apply the same operation over a sequence of values. These kinds of tasks,\ninvolve using structures that are capable of changing the \"control flow\" of our program.\n\nIn computer science, the term \"control flow\" usually refers to the order in which expressions (or commands)\nare evaluated in a given language or program. But this term is also used to refer\nto structures that are capable of changing this \"evaluation order\" of the commands\nexecuted by a given language/program.\n\nThese structures are better known\nby a set of terms, such as: loops, if/else statements, switch statements, among others. So,\nloops and if/else statements are examples of structures that can change the \"control\nflow\" of our program. The keywords `continue` and `break` are also examples of symbols\nthat can change the order of evaluation, since they can move our program to the next iteration\nof a loop, or make the loop stop completely.\n\n\n### If/else statements\n\nAn if/else statement performs a \"conditional flow operation\".\nA conditional flow control (or choice control) allows you to execute\nor ignore a certain block of commands based on a logical condition.\nMany programmers and computer science professionals also use\nthe term \"branching\" in this case.\nIn essence, an if/else statement allow us to use the result of a logical test\nto decide whether or not to execute a given block of commands.\n\nIn Zig, we write if/else statements by using the keywords `if` and `else`.\nWe start with the `if` keyword followed by a logical test inside a pair\nof parentheses, followed by a pair of curly braces which contains the lines\nof code to be executed in case the logical test returns the value `true`.\n\nAfter that, you can optionally add an `else` statement. To do that, just add the `else`\nkeyword followed by a pair of curly braces, with the lines of code\nto executed in case the logical test defined at `if` returns `false`.\n\nIn the example below, we are testing if the object `x` contains a number\nthat is greater than 10. Judging by the output printed to the console,\nwe know that this logical test returned `false`. Because the output\nin the console is compatible with the line of code present in the\n`else` branch of the if/else statement.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x = 5;\nif (x > 10) {\n    try stdout.print(\n        \"x > 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x <= 10!\\n\", .{}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nx <= 10!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Switch statements {#sec-switch}\n\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust.\nAs you would expect, to write a switch statement in Zig we use the `switch` keyword.\nWe provide the value that we want to \"switch over\" inside a\npair of parentheses. Then, we list the possible combinations (or \"branches\")\ninside a pair of curly braces.\n\nLet's take a look at the code example below. You can see that\nI'm creating an enum type called `Role`. We talk more about enums in @sec-enum.\nBut in summary, this `Role` type is listing different types of roles in a fictitious\ncompany, like `SE` for Software Engineer, `DE` for Data Engineer, `PM` for Product Manager,\netc.\n\nNotice that we are using the value from the `role` object in the\nswitch statement, to discover which exact area we need to store in the `area` variable object.\nAlso notice that we are using type inference inside the switch statement, with the dot character,\nas we are going to describe in @sec-type-inference.\nThis makes the `zig` compiler infer the correct data type of the values (`PM`, `SE`, etc.) for us.\n\nAlso notice that, we are grouping multiple values in the same branch of the switch statement.\nWe just separate each possible value with a comma. For example, if `role` contains either `DE` or `DA`,\nthe `area` variable would contain the value `\"Data & Analytics\"`, instead of `\"Platform\"` or `\"Sales\"`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO => {\n            area = \"Platform\";\n        },\n        .DE, .DA => {\n            area = \"Data & Analytics\";\n        },\n        .KS => {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nPlatform\n```\n\n\n:::\n:::\n\n\n\n\n\n#### Switch statements must exhaust all possibilities\n\nOne very important aspect about switch statements in Zig\nis that they must exhaust all existing possibilities.\nIn other words, all possible values that could be found inside the `role`\nobject must be explicitly handled in this switch statement.\n\nSince the `role` object has type `Role`, the only possible values to\nbe found inside this object are `PM`, `SE`, `DPE`, `PO`, `DE`, `DA` and `KS`.\nThere are no other possible values to be stored in this `role` object.\nThus, the switch statements must have a combination (branch) for each one of these values.\nThis is what \"exhaust all existing possibilities\" means. The switch statement covers\nevery possible case.\n\nTherefore, you cannot write a switch statement in Zig, and leave an edge case\nwith no explicit action to be taken.\nThis is a similar behaviour to switch statements in Rust, which also have to\nhandle all possible cases.\n\n\n\n#### The else branch\n\nTake a look at the `dump_hex_fallible()` function below as an example. This function\ncomes from the Zig Standard Library. More precisely, from the\n[`debug.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/debug.zig)[^debug-mod].\nThere are multiple lines in this function, but I omitted them to focus solely on the\nswitch statement found in this function. Notice that this switch statement has four\npossible cases (i.e., four explicit branches). Also, notice that we used an `else` branch\nin this case.\n\nAn `else` branch in a switch statement works as the \"default branch\".\nWhenever you have multiple cases in your switch statement where\nyou want to apply the exact same action, you can use an `else` branch to do that.\n\n[^debug-mod]: <https://github.com/ziglang/zig/blob/master/lib/std/debug.zig>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' => try writer.writeAll(\"␊\"),\n        '\\r' => try writer.writeAll(\"␍\"),\n        '\\t' => try writer.writeAll(\"␉\"),\n        else => try writer.writeByte('.'),\n    }\n}\n```\n:::\n\n\n\n\nMany programmers would also use an `else` branch to handle a \"not supported\" case.\nThat is, a case that cannot be properly handled by your code, or, just a case that\nshould not be \"fixed\". Therefore, you can use an `else` branch to panic (or raise an error)\nin your program to stop the current execution.\n\nTake the code example below. We can see that, we are handling the cases\nfor the `level` object being either 1, 2, or 3. All other possible cases are not supported by default,\nand, as consequence, we raise a runtime error in such cases through the `@panic()` built-in function.\n\nAlso notice that, we are assigning the result of the switch statement to a new object called `category`.\nThis is another thing that you can do with switch statements in Zig. If a branch\noutputs a value as result, you can store the result value of the switch statement into\na new object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 => \"beginner\",\n    3 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n:::\n\n\n\n\n```\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n```\n\n\n\n#### Using ranges in switch\n\nFurthermore, you can also use ranges of values in switch statements.\nThat is, you can create a branch in your switch statement that is used\nwhenever the input value is within the specified range. These \"range expressions\"\nare created with the operator `...`. It's important\nto emphasize that the ranges created by this operator are\ninclusive on both ends.\n\nFor example, I could easily change the previous code example to support all\nlevels between 0 and 100. Like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 => \"beginner\",\n    26...75 => \"intermediary\",\n    76...100 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nbeginner\n```\n\n\n:::\n:::\n\n\n\n\nThis is neat, and it works with character ranges too. That is, I could\nsimply write `'a'...'z'`, to match any character value that is a\nlowercase letter, and it would work fine.\n\n\n#### Labeled switch statements\n\nIn @sec-blocks we have talked about labeling blocks, and also, about using these labels\nto return a value from the block. Well, from version 0.14.0 and onwards of the `zig` compiler,\nyou can also apply labels over switch statements, which makes it possible to almost implement a\n\"C `goto`\" like pattern.\n\nFor example, if you give the label `xsw` to a switch statement, you can use this\nlabel in conjunction with the `continue` keyword to go back to the beginning of the switch\nstatement. In the example below, the execution goes back to the beginning of the\nswitch statement two times, before ending at the `3` branch.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nxsw: switch (@as(u8, 1)) {\n    1 => {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 => continue :xsw 3,\n    3 => return,\n    4 => {},\n    else => {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n```\n:::\n\n\n\n\n\n### The `defer` keyword {#sec-defer}\n\nWith the `defer` keyword you can register an expression to be executed when you exit the current scope.\nTherefore, this keyword has a similar functionality as the `on.exit()` function from R.\nTake the `foo()` function below as an example. When we execute this `foo()` function, the expression\nthat prints the message \"Exiting function ...\" is getting executed only when the function exits\nits scope.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nAdding some numbers ...\nMultiplying ...\nExiting function ...\n```\n\nTherefore, we can use `defer` to declare an expression that is going to be executed\nwhen your code exits the current scope. Some programmers like to interpret the phrase \"exit of the current scope\"\nas \"the end of the current scope\". But this interpretation might not be entirely correct, depending\non what you consider as \"the end of the current scope\".\n\nI mean, what do you consider as **the end** of the current scope? Is it the closing curly bracket (`}`) of the scope?\nIs it when the last expression in the function gets executed? Is it when the function returns to the previous scope?\nEtc. For example, it would not be correct to interpret the \"exit of the current scope\" as the closing\ncurly bracket of the scope. Because the function might exit from an earlier position than this\nclosing curly bracket (e.g. an error value was generated at a previous line inside the function;\nthe function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\n\nNow, if you remember of what we have discussed in @sec-blocks, there are multiple structures in the language\nthat create their own separate scopes. For/while loops, if/else statements,\nfunctions, normal blocks, etc. This also affects the interpretation of `defer`.\nFor example, if you use `defer` inside a for loop, then, the given expression\nwill be executed everytime this specific for loop exits its own scope.\n\nBefore we continue, it's worth emphasizing that the `defer` keyword is an \"unconditional defer\".\nWhich means that the given expression will be executed no matter how the code exits\nthe current scope. For example, your code might exit the current scope because of an error value\nbeing generated, or, because of a return statement, or, a break statement, etc.\n\n\n\n### The `errdefer` keyword {#sec-errdefer1}\n\nOn the previous section, we have discussed the `defer` keyword, which you can use to\nregister an expression to be executed at the exit of the current scope.\nBut this keyword has a brother, which is the `errdefer` keyword. While `defer`\nis an \"unconditional defer\", the `errdefer` keyword is a \"conditional defer\".\nWhich means that the given expression is executed only when you exit the current\nscope on a very specific circumstance.\n\nIn more details, the expression given to `errdefer` is executed only when an error occurs in the current scope.\nTherefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope\nin a normal situation, without errors, the expression given to `errdefer` is not executed.\n\nThis makes the `errdefer` keyword one of the many tools available in Zig for error handling.\nIn this section, we are more concerned with the control flow aspects around `errdefer`.\nBut we are going to discuss `errdefer` later as a error handling tool in @sec-errdefer2.\n\nThe code example below demonstrates three things:\n\n- that `defer` is an \"unconditional defer\", because the given expression gets executed regardless of how the function `foo()` exits its own scope.\n- that `errdefer` is executed because the function `foo()` returned an error value.\n- that `defer` and `errdefer` expressions are executed in a LIFO (*last in, first out*) order.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\nWhen I say that \"defer expressions\" are executed in a LIFO order, what I want to say is that\nthe last `defer` or `errdefer` expressions in the code are the first ones to be executed.\nYou could also interpret this as: \"defer expressions\" are executed from bottom to top, or,\nfrom last to first.\n\nTherefore, if I change the order of the `defer` and `errdefer` expressions, you will notice that\nthe value of `i` that gets printed to the console changes to 1. This doesn't mean that the\n`defer` expression was not executed in this case. This actually means that the `defer` expression\nwas executed only after the `errdefer` expression. The code example below demonstrates this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\n\n\n### For loops\n\nA loop allows you to execute the same lines of code multiple times,\nthus, creating a \"repetition space\" in the execution flow of your program.\nLoops are particularly useful when we want to replicate the same function\n(or the same set of commands) over different inputs.\n\nThere are different types of loops available in Zig. But the most\nessential of them all is probably the *for loop*. A for loop is\nused to apply the same piece of code over the elements of a slice, or, an array.\n\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from\nother languages. You start with the `for` keyword, then, you\nlist the items that you want to iterate\nover inside a pair of parentheses. Then, inside of a pair of pipes (`|`)\nyou should declare an identifier that will serve as your iterator, or,\nthe \"repetition index of the loop\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (items) |value| {\n    // code to execute\n}\n```\n:::\n\n\n\n\nTherefore, instead of using a `(value in items)` syntax,\nin Zig, for loops use the syntax `(items) |value|`. In the example\nbelow, you can see that we are looping through the items\nof the array stored at the object `name`, and printing to the\nconsole the decimal representation of each character in this array.\n\nIf we wanted, we could also iterate through a slice (or a portion) of\nthe array, instead of iterating through the entire array stored in the `name` object.\nJust use a range selector to select the section you want. For example,\nI could provide the expression `name[0..3]` to the for loop, to iterate\njust through the first 3 elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n80 | 101 | 100 | 114 | 111 | \n```\n\n\n:::\n:::\n\n\n\n\nIn the above example we are using the value itself of each\nelement in the array as our iterator. But there are many situations where\nwe need to use an index instead of the actual values of the items.\n\nYou can do that by providing a second set of items to iterate over.\nMore precisely, you provide the range selector `0..` to the for loop. So,\nyes, you can use two different iterators at the same time in a for\nloop in Zig.\n\nBut remember from @sec-assignments that, every object\nyou create in Zig must be used in some way. So if you declare two iterators\nin your for loop, you must use both iterators inside the for loop body.\nBut if you want to use just the index iterator, and not use the \"value iterator\",\nthen, you can discard the value iterator by maching the\nvalue items to the underscore character, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n:::\n\n\n\n\n```\n0 | 1 | 2 | 3 | 4 |\n```\n\n\n### While loops\n\nA while loop is created from the `while` keyword. A `for` loop\niterates through the items of an array, but a `while` loop\nwill loop continuously, and infinitely, until a logical test\n(specified by you) becomes false.\n\nYou start with the `while` keyword, then, you define a logical\nexpression inside a pair of parentheses, and the body of the\nloop is provided inside a pair of curly braces, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\nYou can also specify the increment expression to be used at the beginning of a while loop.\nTo do that, we write the increment expression inside a pair of parentheses after a colon character (`:`).\nThe code example below demonstrates this other pattern.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\n### Using `break` and `continue`\n\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using\nthe keywords `break` and `continue`, respectively. The `while` loop presented in the next code example is,\nat first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to `true`.\nBut what makes this `while` loop stop when the `i` object reaches the count\n10? It's the `break` keyword!\n\nInside the while loop, we have an if statement that is constantly checking if the `i` variable\nis equal to 10. Since we are incrementing the value of `i` at each iteration of the\nwhile loop, this `i` object will eventually be equal to 10, and when it is, the if statement\nwill execute the `break` expression, and, as a result, the execution of the while loop is stopped.\n\nNotice the use of the `expect()` function from the Zig Standard Library after the while loop.\nThis `expect()` function is an \"assert\" type of function.\nThis function checks if the logical test provided is equal to true. If so, the function do nothing.\nOtherwise (i.e., the logical test is equal to false), the function raises an assertion error.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nEverything worked!\n```\n\n\n:::\n:::\n\n\n\n\nSince this code example was executed successfully by the `zig` compiler,\nwithout raising any errors, we known that, after the execution of the while loop,\nthe `i` object is equal to 10. Because if it wasn't equal to 10, an error would have\nbeen raised by `expect()`.\n\nNow, in the next example, we have a use case for\nthe `continue` keyword. The if statement is constantly\nchecking if the current index is a multiple of 2. If\nit is, we jump to the next iteration of the loop.\nOtherwise, the loop just prints the current index to the console.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 3 | 5 | \n```\n\n\n:::\n:::\n\n\n\n\n\n\n## Function parameters are immutable {#sec-fun-pars}\n\nWe have already discussed a lot of the syntax behind function declarations in @sec-root-file and @sec-main-file.\nBut I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig.\nIn summary, function parameters are immutable in Zig.\n\nTake the code example below, where we declare a simple function that just tries to add\nsome amount to the input integer, and returns the result back. If you look closely\nat the body of this `add2()` function, you will notice that we try\nto save the result back into the `x` function argument.\n\nIn other words, this function not only uses the value that it received through the function argument\n`x`, but it also tries to change the value of this function argument, by assigning the addition result\ninto `x`. However, function arguments in Zig are immutable. You cannot change their values, or, you\ncannot assign values to them inside the body's function.\n\nThis is the reason why, the code example below does not compile successfully. If you try to compile\nthis code example, you will get a compile error message about \"trying to change the value of a\nimmutable (i.e., constant) object\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n\n\n```\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n```\n\n\n### A free optimization\n\nIf a function argument receives as input an object whose data type is\nany of the primitive types that we have listed in @sec-primitive-data-types,\nthis object is always passed by value to the function. In other words, this object\nis copied into the function stack frame.\n\nHowever, if the input object have a more complex data type, for example, it might\nbe a struct instance, or an array, or an union value, etc., in cases like that, the `zig` compiler\nwill take the liberty of deciding for you which strategy is best. Thus, the `zig` compiler will\npass your object to the function either by value, or by reference. The compiler will always\nchoose the strategy that is faster for you.\nThis optimization that you get for free is possible only because function arguments are\nimmutable in Zig.\n\n\n### How to overcome this barrier\n\nThere are some situations where you might need to change the value of your function argument\ndirectly inside the function's body. This happens more often when we are passing\nC structs as inputs to Zig functions.\n\nIn a situation like this, you can overcome this barrier by using a pointer. In other words,\ninstead of passing a value as input to the argument, you can pass a \"pointer to value\" instead.\nYou can change the value that the pointer points to, by dereferencing it.\n\nTherefore, if we take our previous `add2()` example, we can change the value of the\nfunction argument `x` inside the function's body by marking the `x` argument as a\n\"pointer to a `u32` value\" (i.e., `*u32` data type), instead of a `u32` value.\nBy making it a pointer, we can finally alter the value of this function argument directly inside\nthe body of the `add2()` function. You can see that the code example below compiles successfully.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n```\n:::\n\n\n\n\n```\nResult: 6\n```\n\n\nEven in this code example above, the `x` argument is still immutable. Which means that the pointer itself is immutable.\nTherefore, you cannot change the memory address that it points to. However, you can dereference the pointer\nto access the value that it points to, and also, to change this value, if you need to.\n\n\n\n\n\n## Structs and OOP {#sec-structs-and-oop}\n\nZig is a language more closely related to C (which is a procedural language),\nthan it is to C++ or Java (which are object-oriented languages). Because of that, you do not\nhave advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or\nclass inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\n\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C.\nYou give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can\nalso register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object\nthat you create with this new type, will always have these methods available and associated with them.\n\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which\nis used to construct (or, to instantiate) every object of this particular class, and we also have\na destructor method (or a destructor function), which is the function responsible for destroying\nevery object of this class.\n\nIn Zig, we normally declare the constructor and the destructor methods\nof our structs, by declaring an `init()` and a `deinit()` methods inside the struct.\nThis is just a naming convention that you will find across the entire Zig Standard Library.\nSo, in Zig, the `init()` method of a struct is normally the constructor method of the class represented by this struct.\nWhile the `deinit()` method is the method used for destroying an existing instance of that struct.\n\nThe `init()` and `deinit()` methods are both used extensively in Zig code, and you will see both of\nthem being used when we talk about allocators in @sec-allocators.\nBut, as another example, let's build a simple `User` struct to represent a user of some sort of system.\n\nIf you look at the `User` struct below, you can see the `struct` keyword.\nNotice the data members of this struct: `id`, `name` and `email`. Every data member has its\ntype explicitly annotated, with the colon character (`:`) syntax that we described earlier in @sec-root-file.\nBut also notice that every line in the struct body that describes a data member, ends with a comma character (`,`).\nSo every time you declare a data member in your Zig code, always end the line with a comma character, instead\nof ending it with the traditional semicolon character (`;`).\n\nNext, we have registered an `init()` function as a method\nof this `User` struct. This `init()` method is the constructor method that we will use to instantiate\nevery new `User` object. That is why this `init()` function returns a new `User` object as result.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    pub fn init(id: u64,\n                name: []const u8,\n                email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    pub fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\npedro\n```\n\n\n:::\n:::\n\n\n\n\nThe `pub` keyword plays an important role in struct declarations, and OOP in Zig.\nEvery method that you declare in your struct that is marked with the keyword `pub`,\nbecomes a public method of this particular struct.\n\nSo every method that you create inside your struct, is, at first, a private method\nof that struct. Meaning that, this method can only be called from within this\nstruct. But, if you mark this method as public, with the keyword `pub`, then,\nyou can call the method directly from an instance of the `User` struct.\n\nIn other words, the functions marked by the keyword `pub`\nare members of the public API of that struct.\nFor example, if I did not mark the `print_name()` method as public,\nthen, I could not execute the line `u.print_name()`. Because I would\nnot be authorized to call this method directly in my code.\n\n\n\n### Anonymous struct literals {#sec-anonymous-struct-literals}\n\nYou can declare a struct object as a literal value. When we do that, we normally specify the\ndata type of this struct literal by writing its data type just before the opening curly brace.\nFor example, I could write a struct literal value of the type `User` that we have defined\nin the previous section like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n```\n:::\n\n\n\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a\nstruct literal, but not specify explicitly the type of this particular struct.\nAn anonymous struct is written by using the syntax `.{}`. So, we essentially\nreplaced the explicit type of the struct literal with a dot character (`.`).\n\nAs we described in @sec-type-inference, when you put a dot before a struct literal,\nthe type of this struct literal is automatically inferred by the `zig` compiler.\nIn essence, the `zig` compiler will look for some hint of what is the type of that struct.\nThis hint can be the type annotation of a function argument,\nor the return type annotation of the function that you are using, or the type annotation\nof an existing object.\nIf the compiler does find such type annotation, it will use this\ntype in your literal struct.\n\nAnonymous structs are very commonly used as inputs to function arguments in Zig.\nOne example that you have seen already constantly, is the `print()`\nfunction from the `stdout` object.\nThis function takes two arguments.\nThe first argument, is a template string, which should\ncontain string format specifiers in it, which tells how the values provided\nin the second argument should be printed into the message.\n\nWhile the second argument is a struct literal that lists the values\nto be printed into the template message specified in the first argument.\nYou normally want to use an anonymous struct literal here, so that the\n`zig` compiler do the job of specifying the type of this particular\nanonymous struct for you.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello, world!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Struct declarations must be constant\n\nTypes in Zig must be `const` or `comptime` (we are going to talk more about comptime in @sec-comptime).\nWhat this means is that you cannot create a new data type, and mark it as variable with the `var` keyword.\nSo struct declarations are always constant. You cannot declare a new struct type using the `var` keyword.\nIt must be `const`.\n\nIn the `Vec3` example below, this declaration is allowed because I'm using the `const` keyword\nto declare this new data type.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n```\n:::\n\n\n\n\n\n### The `self` method argument {#sec-self-arg}\n\nIn every language that have OOP, when we declare a method of some class or struct, we\nusually declare this method as a function that has a `self` argument.\nThis `self` argument is the reference to the object itself from which the method\nis being called from.\n\nIt's not mandatory to use this `self` argument. But why would you not use this `self` argument?\nThere is no reason to not use it. Because the only way to get access to the data stored in the\ndata members of your struct is to access them through this `self` argument.\nIf you don't need to use the data in the data members of your struct inside your method, you very likely don't need\na method. You can just declare this logic as a simple function, outside of your\nstruct declaration.\n\n\nTake the `Vec3` struct below. Inside this `Vec3` struct we declared a method named `distance()`.\nThis method calculates the distance between two `Vec3` objects, by following the distance\nformula in euclidean space. Notice that this `distance()` method takes two `Vec3` objects\nas input, `self` and `other`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n```\n:::\n\n\n\n\n\nThe `self` argument corresponds to the `Vec3` object from which this `distance()` method\nis being called from. While the `other` is a separate `Vec3` object that is given as input\nto this method. In the example below, the `self` argument corresponds to the object\n`v1`, because the `distance()` method is being called from the `v1` object,\nwhile the `other` argument corresponds to the object `v2`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n```\n:::\n\n\n\n\n```\nDistance: 3.3970575502926055\n```\n\n\n\n### About the struct state\n\nSometimes you don't need to care about the state of your struct object. Sometimes, you just need\nto instantiate and use the objects, without altering their state. You can notice that when you have methods\ninside your struct declaration that might use the values that are present in the data members, but they\ndo not alter the values in these data members of the struct in anyway.\n\nThe `Vec3` struct that was presented in @sec-self-arg is an example of that.\nThis struct have a single method named `distance()`, and this method does use the values\npresent in all three data members of the struct (`x`, `y` and `z`). But at the same time,\nthis method does not change the values of these data members at any point.\n\nAs a result of that, when we create `Vec3` objects we usually create them as\nconstant objects, like the `v1` and `v2` objects presented in @sec-self-arg.\nWe can create them as variable objects with the `var` keyword,\nif we want to. But because the methods of this `Vec3` struct do not change\nthe state of the objects in any point, it's unnecessary to mark them\nas variable objects.\n\nBut why? Why am I talking about this here? It's because the `self` argument\nin the methods are affected depending on whether the\nmethods present in a struct change or don't change the state of the object itself.\nMore specifically, when you have a method in a struct that changes the state\nof the object (i.e., changes the value of a data member), the `self` argument\nin this method must be annotated in a different manner.\n\nAs I described in @sec-self-arg, the `self` argument in methods of\na struct is the argument that receives as input the object from which the method\nwas called from. We usually annotate this argument in the methods by writing `self`,\nfollowed by the colon character (`:`), and the data type of the struct to which\nthe method belongs to (e.g. `User`, `Vec3`, etc.).\n\nIf we take the `Vec3` struct that we defined in the previous section as an example,\nwe can see in the `distance()` method that this `self` argument is annotated as\n`self: Vec3`. Because the state of the `Vec3` object is never altered by this\nmethod.\n\nBut what if we do have a method that alters the state of the object, by altering the\nvalues of its data members, how should we annotate `self` in this instance? The answer is:\n\"we should annotate `self` as a pointer of `x`, instead of just `x`\".\nIn other words, you should annotate `self` as `self: *x`, instead of annotating it\nas `self: x`.\n\nIf we create a new method inside the `Vec3` object that, for example, expands the\nvector by multiplying its coordinates by a factor of two, then, we need to follow\nthis rule specified in the previous paragraph. The code example below demonstrates\nthis idea:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n```\n:::\n\n\n\n\nNotice in the code example above that we have added a new method\nto our `Vec3` struct named `twice()`. This method doubles the\ncoordinate values of our vector object. In the\ncase of the `twice()` method, we annotated the `self` argument as `*Vec3`,\nindicating that this argument receives a pointer (or a reference, if you prefer to call it this way)\nto a `Vec3` object as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n```\n:::\n\n\n\n\n```\nDoubled: 8.4\n```\n\n\n\nNow, if you change the `self` argument in this `twice()` method to `self: Vec3`, like in the\n`distance()` method, you will get the compiler error exposed below as result. Notice that this\nerror message is showing a line from the `twice()` method body,\nindicating that you cannot alter the value of the `x` data member.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n```\n:::\n\n\n\n\n```\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\n```\n\nThis error message indicates that the `x` data member belongs to a constant object,\nand, because of that, it cannot be changed. Ultimately, this error message\nis telling us that the `self` argument is constant.\n\nIf you take some time, and think hard about this error message, you will understand it.\nYou already have the tools to understand why we are getting this error message.\nWe have talked about it already in @sec-fun-pars.\nSo remember, every function argument is immutable in Zig, and `self`\nis no exception to this rule.\n\nIn this example, we marked the `v3` object as a variable object.\nBut this does not matter. Because it's not about the input object, it's about\nthe function argument.\n\nThe problem begins when we try to alter the value of `self` directly, which is a function argument,\nand, every function argument is immutable by default. You may ask yourself how can we overcome\nthis barrier, and once again, the solution was also discussed in @sec-fun-pars.\nWe overcome this barrier, by explicitly marking the `self` argument as a pointer.\n\n\n::: {.callout-note}\nIf a method of your `x` struct alters the state of the object, by\nchanging the value of any data member, then, remember to use `self: *x`,\ninstead of `self: x` in the function signature of this method.\n:::\n\n\nYou could also interpret the content discussed in this section as:\n\"if you need to alter the state of your `x` struct object in one of its methods,\nyou must explicitly pass the `x` struct object by reference to the `self` argument of this method\".\n\n\n\n## Type inference {#sec-type-inference}\n\nZig is a strongly typed language. But, there are some situations\nwhere you don't have to explicitly write the type of every single object in your source code,\nas you would expect from a traditional strongly typed language, such as C and C++.\n\nIn some situations, the `zig` compiler can use type inference to solve the data types for you, easing some of\nthe burden that you carry as a developer.\nThe most common way this happens is through function arguments that receive struct objects\nas input.\n\nIn general, type inference in Zig is done by using the dot character (`.`).\nEverytime you see a dot character written before a struct literal, or before an enum value, or something like that,\nyou know that this dot character is playing a special part in this place. More specifically, it's\ntelling the `zig` compiler something along the lines of: \"Hey! Can you infer the type of this\nvalue for me? Please!\". In other words, this dot character is playing a similar role as the `auto` keyword in C++.\n\nI gave you some examples of this in @sec-anonymous-struct-literals, where we used anonymous struct literals.\nAnonymous struct literals are, struct literals that use type inference to\ninfer the exact type of this particular struct literal.\nThis type inference is done by looking for some minimal hint of the correct data type to be used.\nYou could say that the `zig` compiler looks for any neighbouring type annotation that might tell it\nwhat the correct type would be.\n\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in @sec-switch).\nI also gave some other examples of type inference in @sec-switch, where we were inferring the data types of enum values listed inside\nof switch statements (e.g. `.DE`).\nBut as another example, take a look at this `fence()` function reproduced below,\nwhich comes from the [`atomic.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig)[^fence-fn]\nof the Zig Standard Library.\n\n[^fence-fn]: <https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig>.\n\nThere are a lot of things in this function that we haven't talked about yet, such as:\nwhat `comptime` means? `inline`? `extern`?\nLet's just ignore all of these things, and focus solely on the switch statement\nthat is inside this function.\n\nWe can see that this switch statement uses the `order` object as input. This `order`\nobject is one of the inputs of this `fence()` function, and we can see in the type annotation,\nthat this object is of type `AtomicOrder`. We can also see a bunch of values inside the\nswitch statements that begin with a dot character, such as `.release` and `.acquire`.\n\nBecause these weird values contain a dot character before them, we are asking the `zig`\ncompiler to infer the types of these values inside the switch statement. Then, the `zig`\ncompiler is looking into the current context where these values are being used, and trying\nto infer the types of these values.\n\nSince they are being used inside a switch statement, the `zig` compiler looks into the type\nof the input object given to the switch statement, which is the `order` object in this case.\nBecause this object have type `AtomicOrder`, the `zig` compiler infers that these values\nare data members from this type `AtomicOrder`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic => @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire => tsan.__tsan_acquire(addr),\n            .release => tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst => {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n```\n:::\n\n\n\n\nThis is how basic type inference is done in Zig. If we didn't use the dot character before\nthe values inside this switch statement, then, we would be forced to explicitly write\nthe data types of these values. For example, instead of writing `.release` we would have to\nwrite `AtomicOrder.release`. We would have to do this for every single value\nin this switch statement, and this is a lot of work. That is why type inference\nis commonly used on switch statements in Zig.\n\n\n\n## Type casting {#sec-type-cast}\n\nIn this section, I want to discuss type casting (or, type conversion) with you.\nWe use type casting when we have an object of type \"x\", and we want to convert\nit into an object of type \"y\", i.e., we want to change the data type of the object.\n\nMost languages have a formal way to perform type casting. In Rust for example, we normally\nuse the keyword `as`, and in C, we normally use the type casting syntax, e.g. `(int) x`.\nIn Zig, we use the `@as()` built-in function to cast an object of type \"x\", into\nan object of type \"y\".\n\nThis `@as()` function is the preferred way to perform type conversion (or type casting)\nin Zig. Because it's explicit, and, it also performs the casting only if it\nis unambiguous and safe. To use this function, you just provide the target data type\nin the first argument, and, the object that you want cast as the second argument.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file79ce58134f59.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\nThis is the general way to perform type casting in Zig. But remember, `@as()` works only when casting\nis unambiguous and safe. There are many situations where these assumptions do not hold. For example,\n\nwhen casting an integer value into a float value, or vice-versa, it's not clear to the compiler\nhow to perform this conversion safely.\n\nTherefore, we need to use specialized \"casting functions\" in such situations.\nFor example, if you want to cast an integer value into a float value, then, you\nshould use the `@floatFromInt()` function. In the inverse scenario, you should use\nthe `@intFromFloat()` function.\n\nIn these functions, you just provide the object that you want to\ncast as input. Then, the target data type of the \"type casting operation\" is determined by\nthe type annotation of the object where you are saving the results.\nIn the example below, we are casting the object `x` into a value of type `f32`,\nbecause the object `y`, which is where we are saving the results, is annotated\nas an object of type `f32`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file79ce286cee5b.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\nAnother built-in function that is very useful when performing type casting operations is `@ptrCast()`.\nIn essence, we use the `@as()` built-in function when we want to explicit convert (or cast) a Zig value/object\nfrom a type \"x\" to a type \"y\", etc. However, pointers (we are going to discuss pointers\nin more depth in @sec-pointer) are a special type of object in Zig,\ni.e., they are treated differently from \"normal objects\".\n\nEverytime a pointer is involved in some \"type casting operation\" in Zig, the `@ptrCast()` function is used.\nThis function works similarly to `@floatFromInt()`.\nYou just provide the pointer object that you want to cast as input to this function, and the\ntarget data type is, once again, determined by the type annotation of the object where the results are being\nstored.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file79ce1e7313c8.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## Modules\n\nWe already talked about what modules are, and also, how to import other modules into\nyour current module via *import statements*. Every Zig module (i.e., a `.zig` file) that you write in your project\nis internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the\nZig Standard Library into our current module.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n```\n:::\n\n\n\n\nWhen we want to access the functions and objects from the standard library, we\nare basically accessing the data members of the struct stored in the `std`\nobject. That is why we use the same syntax that we use in normal structs, with the dot operator (`.`)\nto access the data members and methods of the struct.\n\nWhen this \"import statement\" gets executed, the result of this expression is a struct\nobject that contains the Zig Standard Library modules, global variables, functions, etc.\nAnd this struct object gets saved (or stored) inside the constant object named `std`.\n\n\nTake the [`thread_pool.zig` module from the project `zap`](https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig)[^thread]\nas an example. This module is written as if it was\na big struct. That is why we have a top-level and public `init()` method\nwritten in this module. The idea is that all top-level functions written in this\nmodule are methods from the struct, and all top-level objects and struct declarations\nare data members of this struct. The module is the struct itself.\n\n[^thread]: <https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig>\n\n\nSo you would import and use this module by doing something like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst ThreadPool = @import(\"thread_pool.zig\");\nconst num_cpus = std.Thread.getCpuCount()\n    catch @panic(\"failed to get cpu core count\");\nconst num_threads = std.math.cast(u16, num_cpus)\n    catch std.math.maxInt(u16);\nconst pool = ThreadPool.init(\n    .{ .max_threads = num_threads }\n);\n```\n:::\n",
+    "supporting": [
+      "03-structs_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/03-unittests/execute-results/html.json b/_freeze/Chapters/03-unittests/execute-results/html.json
index 37cb076d..7e5990dc 100644
--- a/_freeze/Chapters/03-unittests/execute-results/html.json
+++ b/_freeze/Chapters/03-unittests/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "28d3cb0fae2775c98b5945221b3f555c",
+  "hash": "555cc5c67a26414e89a3511dba578c1d",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Unit tests {#sec-unittests}\n\nIn this chapter, I want to dive in on how unit tests are done in\nZig. We are going to talk about what is the testing workflow in Zig, and\nalso, about the `test` command from the `zig` compiler.\n\n\n## Introducing the `test` block\n\nIn Zig, unit tests are written inside a `test` declaration, or, how I prefer to call it, inside a `test` block.\nEvery `test` block is written by using the keyword `test`.\nYou can optionally use a string literal to write a label, which is responsible for identifying\nthe specific group of unit tests that you are writing inside this specific `test` block.\n\nIn the example below, we are testing if the sum of two objects (`a` and `b`)\nis equal to 4. The `expect()` function from the Zig Standard Library\nis a function that receives a logical test as input. If this logical test\nresults in `true`, then, the test passes. But if it results\nin `false`, then, the test fails.\n\nYou can write any Zig code you want inside a `test` block.\nPart of this code might be some necessary commands to setup your testing\nenvironment, or just initializing some objects that you need to use\nin your unit tests.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest \"testing simple sum\" {\n    const a: u8 = 2;\n    const b: u8 = 2;\n    try expect((a + b) == 4);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filea5b06c1ec326.test.testing simple sum...OKA\n  All 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\nYou can have multiple `test` blocks written on the same Zig module.\nAlso, you can mix `test` blocks with your source code, with no problems\nor consequences. If you mix `test` blocks with your normal source code,\nwhen you execute the `build`, `build-exe`, `build-obj` or `build-lib` commands from the\n`zig` compiler that we exposed at @sec-compile-code, these `test` blocks are automatically\nignored by the compiler.\n\nIn other words, the `zig` compiler builds and execute your unit tests only\nwhen you ask it to. By default, the compiler always ignore `test`\nblocks written in your Zig modules. The compiler normally checks only if\nthere are any syntax errors in these `test` blocks.\n\nIf you take a look at the source code for most of the files present in the\nZig Standard Library[^zig-std-lib], you can see that the `test` blocks\nare written together with the normal source code of the library.\nYou can see this for example, at the [`array_list` module](https://github.com/ziglang/zig/blob/master/lib/std/array_list.zig)[^zig-array].\nSo, the standard that the Zig developers decided to adopt\nis to keep their unit tests together with the source code\nof the functionality that they are testing.\n\nEach programmer might have a different opinion on this.\nSome of them might prefer to keep unit tests separate from the actual\nsource code of their application. If that is your case, you can\nsimply create a separate `tests` folder in your project, and\nstart writing Zig modules that contains only unit tests (as you would normally do\non a Python project with `pytest`, for example), and everything will work fine.\nIt boils down to which is your preference here.\n\n[^zig-std-lib]: <https://github.com/ziglang/zig/tree/master/lib/std>\n[^zig-array]: <https://github.com/ziglang/zig/blob/master/lib/std/array_list.zig>\n\n\n## How to run your tests\n\nIf the `zig` compiler ignores any `test` block by default, how can\nyou compile and run your unit tests? The answer is the `test` command from\nthe `zig` compiler. By running the `zig test` command, the compiler will\nfind every instance of a `test` block in your Zig modules, and, it will\ncompile and run the unit tests that you wrote.\n\n\n```bash\nzig test simple_sum.zig\n```\n\n```\n1/1 simple_sum.test.testing simple sum... OK\nAll 1 tests passed.\n```\n\n\n## Testing memory allocations\n\nOne of the advantages of Zig is that it offers great tools\nthat help us, programmers, to avoid (but also detect) memory problems, such as\nmemory leaks and double-frees. The `defer` keyword\nis especially helpful in this regard.\n\nWhen developing your source code, you, the programmer, is responsible for making\nsure that your code do not produce such problems. However,\nyou can also use a special type of an allocator object in Zig\nthat is capable of automatically detecting such problems for you.\nThis is the `std.testing.allocator` object.\nThis allocator object offers some basic memory safety detection\nfeatures, which are capable of detecting memory leaks.\n\nAs we described at @sec-heap, to allocate memory on the heap, you need\nto use an allocator object, and your functions that use these objects to allocate memory\non the heap, should receive an allocator object as one of its inputs.\nEvery memory on the heap that you allocate using these allocator objects,\nmust also be freed using this same allocator object.\n\nSo, if you want to test the memory allocations performed by your functions,\nand make sure that you don't have problems in these allocations, you can simply\nwrite unit tests for these functions, where you provide the\n`std.testing.allocator` object as input to these functions.\n\nLook at the example below, where I'm defining a function that clearly causes\na memory leak. Because we allocate memory, but, at the same time,\nwe do not free this allocated memory at any point. So, when the function\nreturns, we lose the reference to the `buffer` object, which contains\nthe allocated memory, and, as a result, we can no longer free this memory.\n\nNotice that, inside a `test` block I execute this function with\nthe `std.testing.allocator`. The allocator object was capable\nof looking deeper in our program, and detecting the memory leak. As a result,\nthis allocator object returns an error message of \"memory leaked\", and also,\na stack trace showing the exact point where the memory was leaked.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nfn some_memory_leak(allocator: Allocator) !void {\n    const buffer = try allocator.alloc(u32, 10);\n    _ = buffer;\n    // Return without freeing the\n    // allocated memory\n}\n\ntest \"memory leak\" {\n    const allocator = std.testing.allocator;\n    try some_memory_leak(allocator);\n}\n```\n:::\n\n\n\n\n```\nTest [1/1] leak_memory.test.memory leak...\n    [gpa] (err): memory address 0x7c1fddf39000 leaked: \n./ZigExamples/debugging/leak_memory.zig:4:39: 0x10395f2\n    const buffer = try allocator.alloc(u32, 10);\n                                      ^\n./ZigExamples/debugging/leak_memory.zig:12:25: 0x10398ea\n    try some_memory_leak(allocator);\n\n... more stack trace\n```\n\n\n## Testing errors\n\nOne common style of unit tests are those that look for\nspecific errors in your functions. In other words, you write\na unit test that tries to assert if a specific function call\nreturns any error, or a specific type of error.\n\nIn C++ you would normally write this style of unit tests using, for example,\nthe functions `REQUIRE_THROWS()` or `CHECK_THROWS()` from the [`Catch2` test framework](https://github.com/catchorg/Catch2/tree/devel)[^catch2].\nIn the case of a Python project, you would probably use the\n[`raises()` function from `pytest`](https://docs.pytest.org/en/7.1.x/reference/reference.html#pytest-raises)[^pytest].\nWhile in Rust, you would probably use `assert_eq!()` in conjunction with `Err()`.\n\n[^pytest]: <https://docs.pytest.org/en/7.1.x/reference/reference.html#pytest-raises>\n[^catch2]: <https://github.com/catchorg/Catch2/tree/devel>\n\n\nBut in Zig, we use the `expectError()` function, from the `std.testing` module.\nWith this function, you can test if a specific function call returns the exact\ntype of error that you expect it to return. To use this function, you first write\n`try expectError()`. Then, on the first argument, you provide the type of error that you\nare expecting from the function call. Then, on the second argument, you write\nthe function call that you expect to fail.\n\nThe code example below demonstrates such type of unit test in Zig.\nNotice that, inside the function `alloc_error()` we are allocating\n100 bytes of memory, or, an array of 100 elements, for the object `ibuffer`. However,\nin the `test` block, we are using the `FixedBufferAllocator()`\nallocator object, which is limited to 10 bytes of space, because\nthe object `buffer`, which we provided to the allocator object,\nhave only 10 bytes of space.\n\nThat is why, the `alloc_error()` function raises an `OutOfMemory` error\non this case.\nBecause this function is trying to allocate more space than the allocator\nobject allows.\nSo, in essence, we are testing for a specific type of error,\nwhich is `OutOfMemory`. If the `alloc_error()` function returns any other type of error,\nthen, the `expectError()` function would make the entire test fail.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst expectError = std.testing.expectError;\nfn alloc_error(allocator: Allocator) !void {\n    var ibuffer = try allocator.alloc(u8, 100);\n    defer allocator.free(ibuffer);\n    ibuffer[0] = 2;\n}\n\ntest \"testing error\" {\n    var buffer: [10]u8 = undefined;\n    var fba = std.heap.FixedBufferAllocator.init(&buffer);\n    const allocator = fba.allocator();\n    try expectError(error.OutOfMemory, alloc_error(allocator));\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filea5b059c00874.test.testing error...OKAll 1 \n   tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n## Testing simple equalities\n\nIn Zig, there are some different ways you can test for an equality.\nYou already saw that we can use `expect()` with the logical operator `==`\nto essentially reproduce an equality test. But we also have\nsome other helper functions that you should know about, especially\n`expectEqual()`, `expectEqualSlices()` and `expectEqualStrings()`.\n\n\nThe `expectEqual()` function, as the name suggests, is a classic\ntest equality function. It receives two objects as input. The first\nobject is the value that you expect to be in the second object.\nWhile second object is the object you have, or, the object that your application\nproduced as result. So, with `expectEqual()` you are essentially\ntesting if the values stored inside these two objects\nare equal or not.\n\nYou can see in the example below that, the test performed by\n`expectEqual()` failed. Because the objects `v1` and `v2` contain\ndifferent values in them.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"values are equal?\" {\n    const v1 = 15;\n    const v2 = 18;\n    try std.testing.expectEqual(v1, v2);\n}\n```\n:::\n\n\n\n\n```\n1/1 ve.test.values are equal?...\n    expected 15, found 18\n    FAIL (TestExpectedEqual)\nve.zig:5:5: test.values are equal? (test)\n    try std.testing.expectEqual(v1, v2);\n    ^\n0 passed; 0 skipped; 1 failed.\n```\n\n\nAlthough useful, the `expectEqual()` function does not work with arrays.\nFor testing if two arrays are equal, you should use the `expectEqualSlices()`\nfunction instead. This function have three arguments. First, you provide\nthe data type contained in both arrays that you are trying to compare.\nWhile the second and third arguments corresponds to the array objects that you want to compare.\n\nIn the example below, we are using this function to test if two array\nobjects (`array1` and `array2`) are equal or not. Since they\nare in fact equal, the unit test passed with no errors.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"arrays are equal?\" {\n    const array1 = [3]u32{1, 2, 3};\n    const array2 = [3]u32{1, 2, 3};\n    try std.testing.expectEqualSlices(\n        u32, &array1, &array2\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filea5b054e42b80.test.arrays are equal?...OKAl\n  ll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\nAt last, you might also want to use the `expectEqualStrings()` function.\nAs the name suggests, you can use this function to test if two strings\nare equal or not. Just provide the two string objects that you want to compare,\nas inputs to the function.\n\nIf the function finds any existing differences between the two strings,\nthen, the function will raise an error, and also, print an error message\nthat shows the exact difference between the two string objects provided,\nas the example below demonstrates:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"strings are equal?\" {\n    const str1 = \"hello, world!\";\n    const str2 = \"Hello, world!\";\n    try std.testing.expectEqualStrings(\n        str1, str2\n    );\n}\n```\n:::\n\n\n\n\n```\n1/1 t.test.strings are equal?... \n====== expected this output: =========\nhello, world!␃\n======== instead found this: =========\nHello, world!␃\n======================================\nFirst difference occurs on line 1:\nexpected:\nhello, world!\n^ ('\\x68')\nfound:\nHello, world!\n^ ('\\x48')\n```\n\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Unit tests {#sec-unittests}\n\nIn this chapter, I want to dive in on how unit tests are done in\nZig. We are going to talk about what is the testing workflow in Zig, and\nalso, about the `test` command from the `zig` compiler.\n\n\n## Introducing the `test` block\n\nIn Zig, unit tests are written inside a `test` declaration, or, how I prefer to call it, inside a `test` block.\nEvery `test` block is written by using the keyword `test`.\nYou can optionally use a string literal to write a label, which is responsible for identifying\nthe specific group of unit tests that you are writing inside this specific `test` block.\n\nIn the example below, we are testing if the sum of two objects (`a` and `b`)\nis equal to 4. The `expect()` function from the Zig Standard Library\nis a function that receives a logical test as input. If this logical test\nresults in `true`, then, the test passes. But if it results\nin `false`, then, the test fails.\n\nYou can write any Zig code you want inside a `test` block.\nPart of this code might be some necessary commands to setup your testing\nenvironment, or just initializing some objects that you need to use\nin your unit tests.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest \"testing simple sum\" {\n    const a: u8 = 2;\n    const b: u8 = 2;\n    try expect((a + b) == 4);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file81c21dbf264e.test.testing simple sum...OKA\n  All 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\nYou can have multiple `test` blocks written on the same Zig module.\nAlso, you can mix `test` blocks with your source code, with no problems\nor consequences. If you mix `test` blocks with your normal source code,\nwhen you execute the `build`, `build-exe`, `build-obj` or `build-lib` commands from the\n`zig` compiler that we exposed in @sec-compile-code, these `test` blocks are automatically\nignored by the compiler.\n\nIn other words, the `zig` compiler builds and execute your unit tests only\nwhen you ask it to. By default, the compiler always ignore `test`\nblocks written in your Zig modules. The compiler normally checks only if\nthere are any syntax errors in these `test` blocks.\n\nIf you take a look at the source code for most of the files present in the\nZig Standard Library[^zig-std-lib], you can see that the `test` blocks\nare written together with the normal source code of the library.\nYou can see this for example, at the [`array_list` module](https://github.com/ziglang/zig/blob/master/lib/std/array_list.zig)[^zig-array].\nSo, the standard that the Zig developers decided to adopt\nis to keep their unit tests together with the source code\nof the functionality that they are testing.\n\nEach programmer might have a different opinion on this.\nSome of them might prefer to keep unit tests separate from the actual\nsource code of their application. If that is your case, you can\nsimply create a separate `tests` folder in your project, and\nstart writing Zig modules that contains only unit tests (as you would normally do\non a Python project with `pytest`, for example), and everything will work fine.\nIt boils down to which is your preference here.\n\n[^zig-std-lib]: <https://github.com/ziglang/zig/tree/master/lib/std>\n[^zig-array]: <https://github.com/ziglang/zig/blob/master/lib/std/array_list.zig>\n\n\n## How to run your tests\n\nIf the `zig` compiler ignores any `test` block by default, how can\nyou compile and run your unit tests? The answer is the `test` command from\nthe `zig` compiler. By running the `zig test` command, the compiler will\nfind every instance of a `test` block in your Zig modules, and, it will\ncompile and run the unit tests that you wrote.\n\n\n```bash\nzig test simple_sum.zig\n```\n\n```\n1/1 simple_sum.test.testing simple sum... OK\nAll 1 tests passed.\n```\n\n\n## Testing memory allocations\n\nOne of the advantages of Zig is that it offers great tools\nthat help us, programmers, to avoid (but also detect) memory problems, such as\nmemory leaks and double-frees. The `defer` keyword\nis especially helpful in this regard.\n\nWhen developing your source code, you, the programmer, are responsible for making\nsure that your code does not produce such problems. However,\nyou can also use a special type of an allocator object in Zig\nthat is capable of automatically detecting such problems for you.\nThis is the `std.testing.allocator` object.\nThis allocator object offers some basic memory safety detection\nfeatures, which are capable of detecting memory leaks.\n\nAs we described in @sec-heap, to allocate memory on the heap, you need\nto use an allocator object, and your functions that use these objects to allocate memory\non the heap, should receive an allocator object as one of its inputs.\nEvery memory on the heap that you allocate using these allocator objects,\nmust also be freed using this same allocator object.\n\nSo, if you want to test the memory allocations performed by your functions,\nand make sure that you don't have problems in these allocations, you can simply\nwrite unit tests for these functions, where you provide the\n`std.testing.allocator` object as input to these functions.\n\nLook at the example below, where I'm defining a function that clearly causes\na memory leak. Because we allocate memory, but, at the same time,\nwe do not free this allocated memory at any point. So, when the function\nreturns, we lose the reference to the `buffer` object, which contains\nthe allocated memory, and, as a result, we can no longer free this memory.\n\nNotice that, inside a `test` block I execute this function with\nthe `std.testing.allocator`. The allocator object was capable\nof looking deeper in our program, and detecting the memory leak. As a result,\nthis allocator object returns an error message of \"memory leaked\", and also,\na stack trace showing the exact point where the memory was leaked.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nfn some_memory_leak(allocator: Allocator) !void {\n    const buffer = try allocator.alloc(u32, 10);\n    _ = buffer;\n    // Return without freeing the\n    // allocated memory\n}\n\ntest \"memory leak\" {\n    const allocator = std.testing.allocator;\n    try some_memory_leak(allocator);\n}\n```\n:::\n\n\n\n\n```\nTest [1/1] leak_memory.test.memory leak...\n    [gpa] (err): memory address 0x7c1fddf39000 leaked:\n./ZigExamples/debugging/leak_memory.zig:4:39: 0x10395f2\n    const buffer = try allocator.alloc(u32, 10);\n                                      ^\n./ZigExamples/debugging/leak_memory.zig:12:25: 0x10398ea\n    try some_memory_leak(allocator);\n\n... more stack trace\n```\n\n\n## Testing errors\n\nOne common style of unit tests are those that look for\nspecific errors in your functions. In other words, you write\na unit test that tries to assert if a specific function call\nreturns any error, or a specific type of error.\n\nIn C++ you would normally write this style of unit tests using, for example,\nthe functions `REQUIRE_THROWS()` or `CHECK_THROWS()` from the [`Catch2` test framework](https://github.com/catchorg/Catch2/tree/devel)[^catch2].\nIn the case of a Python project, you would probably use the\n[`raises()` function from `pytest`](https://docs.pytest.org/en/7.1.x/reference/reference.html#pytest-raises)[^pytest].\nWhile in Rust, you would probably use `assert_eq!()` in conjunction with `Err()`.\n\n[^pytest]: <https://docs.pytest.org/en/7.1.x/reference/reference.html#pytest-raises>\n[^catch2]: <https://github.com/catchorg/Catch2/tree/devel>\n\n\nBut in Zig, we use the `expectError()` function, from the `std.testing` module.\nWith this function, you can test if a specific function call returns the exact\ntype of error that you expect it to return. To use this function, you first write\n`try expectError()`. Then, on the first argument, you provide the type of error that you\nare expecting from the function call. Then, on the second argument, you write\nthe function call that you expect to fail.\n\nThe code example below demonstrates such type of unit test in Zig.\nNotice that, inside the function `alloc_error()` we are allocating\n100 bytes of memory, or, an array of 100 elements, for the object `ibuffer`. However,\nin the `test` block, we are using the `FixedBufferAllocator()`\nallocator object, which is limited to 10 bytes of space, because\nthe object `buffer`, which we provided to the allocator object,\nhave only 10 bytes of space.\n\nThat is why, the `alloc_error()` function raises an `OutOfMemory` error\non this case.\nBecause this function is trying to allocate more space than the allocator\nobject allows.\nSo, in essence, we are testing for a specific type of error,\nwhich is `OutOfMemory`. If the `alloc_error()` function returns any other type of error,\nthen, the `expectError()` function would make the entire test fail.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst expectError = std.testing.expectError;\nfn alloc_error(allocator: Allocator) !void {\n    var ibuffer = try allocator.alloc(u8, 100);\n    defer allocator.free(ibuffer);\n    ibuffer[0] = 2;\n}\n\ntest \"testing error\" {\n    var buffer: [10]u8 = undefined;\n    var fba = std.heap.FixedBufferAllocator.init(&buffer);\n    const allocator = fba.allocator();\n    try expectError(error.OutOfMemory, alloc_error(allocator));\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file81c24fea00d1.test.testing error...OKAll 1 \n   tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n## Testing simple equalities\n\nIn Zig, there are some different ways you can test for an equality.\nYou already saw that we can use `expect()` with the logical operator `==`\nto essentially reproduce an equality test. But we also have\nsome other helper functions that you should know about, especially\n`expectEqual()`, `expectEqualSlices()` and `expectEqualStrings()`.\n\n\nThe `expectEqual()` function, as the name suggests, is a classic\ntest equality function. It receives two objects as input. The first\nobject is the value that you expect to be in the second object.\nWhile second object is the object you have, or, the object that your application\nproduced as result. So, with `expectEqual()` you are essentially\ntesting if the values stored inside these two objects\nare equal or not.\n\nYou can see in the example below that, the test performed by\n`expectEqual()` failed. Because the objects `v1` and `v2` contain\ndifferent values in them.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"values are equal?\" {\n    const v1 = 15;\n    const v2 = 18;\n    try std.testing.expectEqual(v1, v2);\n}\n```\n:::\n\n\n\n\n```\n1/1 ve.test.values are equal?...\n    expected 15, found 18\n    FAIL (TestExpectedEqual)\nve.zig:5:5: test.values are equal? (test)\n    try std.testing.expectEqual(v1, v2);\n    ^\n0 passed; 0 skipped; 1 failed.\n```\n\n\nAlthough useful, the `expectEqual()` function does not work with arrays.\nFor testing if two arrays are equal, you should use the `expectEqualSlices()`\nfunction instead. This function have three arguments. First, you provide\nthe data type contained in both arrays that you are trying to compare.\nWhile the second and third arguments corresponds to the array objects that you want to compare.\n\nIn the example below, we are using this function to test if two array\nobjects (`array1` and `array2`) are equal or not. Since they\nare in fact equal, the unit test passed with no errors.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"arrays are equal?\" {\n    const array1 = [3]u32{1, 2, 3};\n    const array2 = [3]u32{1, 2, 3};\n    try std.testing.expectEqualSlices(\n        u32, &array1, &array2\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file81c25513148.test.arrays are equal?...OKAll\n  l 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\nAt last, you might also want to use the `expectEqualStrings()` function.\nAs the name suggests, you can use this function to test if two strings\nare equal or not. Just provide the two string objects that you want to compare,\nas inputs to the function.\n\nIf the function finds any existing differences between the two strings,\nthen, the function will raise an error, and also, print an error message\nthat shows the exact difference between the two string objects provided,\nas the example below demonstrates:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"strings are equal?\" {\n    const str1 = \"hello, world!\";\n    const str2 = \"Hello, world!\";\n    try std.testing.expectEqualStrings(\n        str1, str2\n    );\n}\n```\n:::\n\n\n\n\n```\n1/1 t.test.strings are equal?...\n====== expected this output: =========\nhello, world!␃\n======== instead found this: =========\nHello, world!␃\n======================================\nFirst difference occurs on line 1:\nexpected:\nhello, world!\n^ ('\\x68')\nfound:\nHello, world!\n^ ('\\x48')\n```\n",
+    "supporting": [
+      "03-unittests_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/04-http-server/execute-results/html.json b/_freeze/Chapters/04-http-server/execute-results/html.json
index 8f509955..09b85ed5 100644
--- a/_freeze/Chapters/04-http-server/execute-results/html.json
+++ b/_freeze/Chapters/04-http-server/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "3ea52d4cb7e3e92c83ca208ca4f62693",
+  "hash": "d35b08ad233c0b9a03e30bed4b1982f2",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 2 - Building a HTTP Server from scratch\n\nIn this chapter, I want to implement a new\nsmall project with you. This time, we are going\nto implement a basic HTTP Server from scratch.\n\nThe Zig Standard Library already have a HTTP Server\nimplemented, which is available at `std.http.Server`.\nBut again, our objective here in this chapter, is to implement\nit **from scratch**. So we can't use this server object available\nfrom the Zig Standard Library.\n\n## What is a HTTP Server?\n\nFirst of all, what is a HTTP Server?\nA HTTP server, as any other type of server, is essentially\na program that runs indefinitely, on an infinite loop, waiting for incoming connections\nfrom clients. Once the server receives an incoming connection, it will\naccept this connection, and it will send messages back-and-forth to the client\nthrough this connection.\n\nBut the messages that are transmitted inside this connection are in a\nspecific format. They are HTTP messages\n(i.e. messages that use the HTTP Protocol specification).\nThe HTTP Protocol is the backbone of the modern web.\nThe world wide web as we know it today, would not exist without the \nHTTP Protocol.\n\nSo, Web servers (which is just a fancy name to\nHTTP Servers) are servers that exchange HTTP messages with clients.\nAnd these HTTP servers and the HTTP Protocol specification\nare essential to the operation of the world wide web today.\n\nThat is the whole picture of the process.\nAgain, we have two subjects involved here, a server (which is\na program that is running indefinitely, waiting to receive incoming connections),\nand a client (which is someone that wants to connect to the server,\nand exchange HTTP messages with it).\n\nYou may find the material about the [HTTP Protocol available at the Mozilla MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview)[^mdn-http]\n, a great resource for you to also look at. It gives you a great overview on how\nHTTP works, and what role the server plays in this matter.\n\n[^mdn-http]: <https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview>.\n\n\n## How a HTTP Server works? {#sec-how-http-works}\n\nImagine a HTTP Server as if it were the receptionist of a large hotel. In a hotel,\nyou have a reception, and inside that reception there is a receptionist\nwaiting for customers to arrive. A HTTP Server is essentially a receptionist\nthat is indefinitely waiting for new customers (or, in the context of HTTP, new clients)\nto arrive in the hotel.\n\nWhen a customer arrives at the hotel, that customer starts a conversation with the\nreceptionist. He tells the receptionist how many days he wants to stay at the hotel.\nThen, the receptionist search for an available apartment. If there is an available apartment\nat the moment, the customer pays the hotel fees, then, he gets the keys to the apartment,\nand then, he goes to the apartment to rest.\n\nAfter this entire process of dealing with the customer (searching for available apartments,\nreceiving payment, handing over the keys), the receptionist goes back to what he was\ndoing earlier, which is to wait. Wait for new customers to arrive.\n\nThat is, in a nutshell, what a HTTP Server do. It waits for clients to connect to the\nserver. When a client attempts to connect to the server, the server accepts this connection,\nand it starts to exchange messages with the client through this connection.\nThe first message that happens inside this connection is always a message from the client\nto the server. This message is called the *HTTP Request*.\n\nThis HTTP Request is a HTTP message that contains what\nthe client wants from the server. It is literally a request. The client\nthat connected to the server is asking this server to do something for him.\n\nThere are different \"types of request\" that a client can send to a HTTP Server.\nBut the most basic type of request, is when a client ask to the\nHTTP Server to serve (i.e. to send) some specific web page (which is a HTML file) to him.\nWhen you type `google.com` in your web browser, you are essentially sending a HTTP Request to Google's\nHTTP servers. This request is asking these servers to send the Google webpage to you.\n\nNonetheless, when the server receives this first message, the *HTTP Request*, it\nanalyzes this request, to understand: who the client is? What he wants the server to do?\nThis client has provided all the necessary information to perform the action that he\nasked? Etc.\n\nOnce the server understands what the client wants, he simply perform the action\nthat was requested, and, to finish the whole process, the server sends back\na HTTP message to the client, informing if the action performed was successful or not,\nand, at last, the server ends (or closes) the connection with the client.\n\nThis last HTTP message sent from the server to the client, is called the *HTTP Response*.\nBecause the server is responding to the action that was requested by the client.\nThe main objective of this response message is let the client know if the\naction requested was successful or not, before the server closes the connection.\n\n\n## How a HTTP server is normally implemented? {#sec-http-how-impl}\n\nLet's use the C language as an example. There are many materials\nteaching how to write a simple HTTP server in C code, like @jeffrey_http,\nor @nipun_http, or @eric_http.\nHaving this in mind, I will not show C code examples here, because you\ncan find them on the internet.\nBut I will describe the theory behind the necessary steps to create\nsuch HTTP server in C.\n\n\nIn essence, we normally implement a HTTP server in C by using WebSocket technology,\nwhich involves the following steps:\n\n1. Create a socket object.\n1. Bind a name (or more specifically, an address) to this socket object.\n1. Make this socket object to start listening and waiting for incoming connections.\n1. When a connection arrive, we accept this connection, and we exchange the HTTP messages (HTTP Request and HTTP Response).\n1. Then, we simply close this connection.\n\n\nA socket object is essentially a channel of communication.\nYou are creating a channel where people can send messages through.\nWhen you create a socket object, this object is not binded to any particular\naddress. This means that with this object you have a representation of a channel of communication\nin your hands. But this channel is not currently available, or, it is not currently accessible,\nbecause it do not have a known address where you can find it.\n\nThat is what the \"bind\" operation do. It binds a name (or more specifically, an address) to\nthis socket object, or, this channel of communication, so that it becomes available,\nor, accessible through this address. While the \"listen\" operation makes the socket object to\nlisten for incoming connections in this address. In other words, the \"listen\" operation\nmakes the socket to wait for incoming connections.\ncurrently\nNow, when a client actually attempts to connect to the server through the socket address\nthat we have specified, in order to establish this connection with the client,\nthe socket object needs to accept this incoming connection. Thus, when we\naccept an incoming connection, the client and the server become\nconnected to each other, and they can start reading or writing messages into this\nestablished connection.\n\nAfter we receive the HTTP Request from the client, analyze it, and send the HTTP Response\nto the client, we can then close the connection, and end this communication.\n\n\n## Implementing the server - Part 1\n\n### Creating the socket object {#sec-create-socket}\n\nLet's begin with creating the socket object for our server.\nJust to make things shorter, I will create this socket object in\na separate Zig module. I will name it `config.zig`.\n\nIn Zig, we can create a web socket using\nthe `std.posix.socket()` function, from the Zig Standard Library.\nAs I mentioned earlier at @sec-http-how-impl, every socket object that we create\nrepresents a communication channel, and we need to bind this channel to a specific address.\nAn \"address\" is defined as an IP address, or, more specifically, an IPv4 address^[It can be also an IPv6 address. But normally, we use a IPv4 address for that.].\nEvery IPv4 address is composed by two components. The first component is the host,\nwhich is a sequence of 4 numbers separated by dot characters (`.`) that identifies the machine used.\nWhile the second component is a port number, which identifies the specific\ndoor, or, the specific port to use in the host machine.\n\nThe sequence of 4 numbers (i.e. the host) identifies the machine (i.e. the computer itself) where\nthis socket will live in. Every computer normally have multiple \"doors\" available inside of him, because \nthis allows the computer to receive and work with multiple connections at the same time.\nHe simply use a single door for each connection. So the port number, is\nessentially a number that identifies the specific door in the computer that will be responsible\nfor receiving the connection. That is, it identifies the \"door\" in the computer that the socket will use\nto receive incoming connections.\n\nTo make things simpler, I will use an IP address that identifies our current machine in this example.\nThis means that, our socket object will reside on the same computer that we are currently using\n(this is also known as the \"localhost\") to write this Zig source code.\n\nBy convention, the IP address that identifies the \"localhost\", which is the current machine we\nare using, is the IP `127.0.0.1`. So, that is the IP\naddress we are going to use in our server. I can declare it in Zig\nby using an array of 4 integers, like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst localhost = [4]u8{ 127, 0, 0, 1 };\n_ = localhost;\n```\n:::\n\n\n\n\nNow, we need to decide which port number to use. By convention, there are some\nport numbers that are reserved, meaning that, we cannot use them for our own\npurposes, like the port 22 (which is normally used for SSH connections).\nFor TCP connections, which is our case here,\na port number is a 16-bit unsigned integer (type `u16` in Zig),\nthus ranging from 0 to 65535 [@wikipedia_port].\nSo, we can choose\na number from 0 to 65535 for our port number. In the \nexample of this book, I will use the port number 3490\n(just a random number).\n\n\nNow that we have these two informations at hand, I can\nfinally create our socket object, using the `std.posix.socket()` function.\nFirst, we use the host and the port number to create an `Address` object,\nwith the `std.net.Address.initIp4()` function, like in the example below.\nAfter that, I use this address object inside the `socket()` function\nto create our socket object.\n\nThe `Socket` struct defined below summarizes all the logic behind\nthis process. In this struct, we have two data members, which are:\n1)  the address object; 2) and a stream object, which is\nthe object we will use to read and write the messages into any connection we establish.\n\nNotice that, inside the constructor method of this struct,\nwhen we create the socket object, we are using the `IPROTO.TCP` property as an input to\ntell the function to create a socket for TCP connections.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\nconst net = @import(\"std\").net;\n\npub const Socket = struct {\n    _address: std.net.Address,\n    _stream: std.net.Stream,\n\n    pub fn init() !Socket {\n        const host = [4]u8{ 127, 0, 0, 1 };\n        const port = 3490;\n        const addr = net.Address.initIp4(host, port);\n        const socket = try std.posix.socket(\n            addr.any.family,\n            std.posix.SOCK.STREAM,\n            std.posix.IPPROTO.TCP\n        );\n        const stream = net.Stream{ .handle = socket };\n        return Socket{ ._address = addr, ._stream = stream };\n    }\n};\n```\n:::\n\n\n\n\n\n### Listening and receiving connections\n\nRemember that we stored the `Socket` struct\ndeclaration that we built at @sec-create-socket inside a Zig module named `config.zig`.\nThis is why I imported this module into our main module (`main.zig`) in the example below, as the `SocketConf` object,\nto access the `Socket` struct.\n\nOnce we created our socket object, we can focus now on making this socket object\nlisten and receive new incoming connections. We do that, by calling the `listen()`\nmethod from the `Address` object that is contained inside the socket object, and then,\nwe call the `accept()` method over the result.\n\nThe `listen()` method from the `Address` object produces a server object,\nwhich is an object that will stay open and running indefinitely, waiting\nto receive an incoming connection. Therefore, if you try to run the code\nexample below, by calling the `run` command from the `zig` compiler,\nyou will notice that the programs keeps running indefinitely,\nwithout a clear end.\n\nThis happens, because the program is waiting for something to happen.\nIt is waiting for someone to try to connect to the address (`http://127.0.0.1:3490`) where\nthe server is running and listening for incoming connections. This is what\nthe `listen()` method do, it makes the socket to be active waiting for someone\nto connect.\n\nOn the other side, the `accept()` method is the function that establishes the connection\nwhen someone tries to connect to the socket. This means that, the `accept()` method\nreturns a new connection object as a result. And you can use this connection object\nto read or write messages from or to the client.\nFor now, we are not doing anything with this connection object.\nBut we are going to use it on the next section.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n    _ = connection;\n}\n```\n:::\n\n\n\n\nThis code example allows one single connection. In other words, the\nserver will wait for one incoming connection, and as soon as the\nserver is done with this first connection that it establishes, the\nprogram ends, and the server stops.\n\nThis is not the norm on the real world. Most people that write\na HTTP server like this, usually put the `accept()` method\ninside a `while` (infinite) loop, where if a connection\nis created with `accept()`, a new thread of execution is created to deal with\nthis new connection and the client. That is, real-world examples of HTTP Servers\nnormally rely on parallel computing to work.\n\nWith this design, the server simply accepts the connection,\nand the whole process of dealing with the client, and receiving\nthe HTTP Request, and sending the HTTP Response, all of this\nis done in the background, on a separate execution thread.\n\nSo, as soon as the server accepts the connection, and creates\nthe separate thread, the server goes back to what he was doing earlier,\nwhich is to wait indefinitely for a new connection to accept.\nHaving this in mind, the code example exposed above, is a\nserver that serves only a single client. Because the program\nterminates as soon as the connection is accepted.\n\n\n\n### Reading the message from the client {#sec-read-http-message}\n\nNow that we have a connection established, i.e. the connection\nobject that we created through the `accept()` function, we can now\nuse this connection object to read any messages that the client\nsend to our server. But we can also use it to send messages back\nto the client.\n\nThe basic idea is, if we **write** any data into this connection object,\nthen, we are sending data to the client, and if we **read** the data present in\nthis connection object, then, we are reading any data that the\nclient sent to us, through this connection object. So, just\nhave this logic in mind. \"Read\" is for reading messages from the client,\nand \"write\" is to send a message to the client.\n\nRemember from @sec-how-http-works that, the first thing that we need to do is to read the HTTP Request\nsent by the client to our server. Because it is the first message that happens\ninside the established connection, and, as a consequence, it is the first\nthing that we need to deal with.\n\nThat is why, I'm going to create a new Zig module in this small project, named `request.zig`\nto keep all functions related to the HTTP Request\ntogether. Then, I will create a new function named `read_request()` that will\nuse our connection object to read the message sent by the client,\nwhich is the HTTP Request.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Connection = std.net.Server.Connection;\npub fn read_request(conn: Connection,\n                    buffer: []u8) !void {\n    const reader = conn.stream.reader();\n    _ = try reader.read(buffer);\n}\n```\n:::\n\n\n\n\n\nThis function accepts a slice object which behaves as a buffer.\nThe `read_request()` function reads the message sent into\nthe connection object, and saves this message into this buffer object that\nwe have provided as input.\n\nNotice that I'm using the connection object that we created to read\nthe message from the client. I first access the `reader` object that lives inside the\nconnection object. Then, I call the `read()` method of this `reader` object\nto effectively read and save the data sent by the client into the buffer object\nthat we created earlier. I'm discarding the return value\nof the `read()` method, by assigning it to the underscore character (`_`),\nbecause this return value is not useful for us right now.\n\n\n\n## Looking at the current state of the program\n\n\nI think now is a good time to see how our program is currently working. Shall we?\nSo, the first thing I will do is to update the `main.zig` module in our small Zig project,\nso that the `main()` function call this new `read_request()` function that we have just created.\nI will also add a print statement at the end of the `main()` function,\njust so that you can see what the HTTP Request that we have just loaded into the buffer object\nlooks like.\n\nAlso, I'm creating the buffer object in the `main()` function, which will be\nresponsible for storing the message sent by the client, and, I'm also\nusing a `for` loop to initialize all fields of this buffer object to the number zero.\nThis is important to make sure that we don't have uninitialized memory in\nthis object. Because uninitialized memory may cause undefined behaviour in our program.\n\nSince the `read_request()` function should receive as input the buffer object as a slice object (`[]u8`),\nI am using the syntax `array[0..array.len]` to get access to a slice of this `buffer` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    _ = try Request.read_request(\n        connection, buffer[0..buffer.len]\n    );\n    try stdout.print(\"{s}\\n\", .{buffer});\n}\n```\n:::\n\n\n\n\nNow, I'm going to execute this program, with the `run` command from the\n`zig` compiler. But remember, as we sad earlier, as soon as I execute this program, it will\nhang indefinitely, because the program is waiting for a client trying to\nconnect to the server.\n\nMore specifically, the program will pause at the line\nwith the `accept()` call. As soon as a client try to connect to the\nserver, then, the execution will \"unpause\", and the `accept()` function\nwill finally be executed to create the\nconnection object that we need, and the remaining of the program\nwill run.\n\nYou can see that at @fig-print-zigrun1. The message `Server Addr: 127.0.0.1:3490`\nis printed to the console, and the program is now waiting for an incoming connection.\n\n![A screenshot of running the program](./../Figures/print-zigrun1.png){#fig-print-zigrun1}\n\n\nWe can finally try to connect to this server, and there are several ways we can do this.\nFor example, we could use the following Python script:\n\n```python\nimport requests\nrequests.get(\"http://127.0.0.1:3490\")\n```\n\nOr, we could also open any web browser of our preference, and type\nthe URL `localhost:3490`. OBS: `localhost` is the same thing as the\nIP `127.0.0.1`. When you press enter, and your web browser go\nto this address, first, the browser will probably print a message\nsaying that \"this page isn't working\", and, then, it will\nprobably change to a new message saying that \"the site can't be\nreached\".\n\nYou get these \"error messages\" in the web browser, because\nit got no response back from the server. In other words, when the web\nbrowser connected to our server, it did send the HTTP Request through the established connection.\nThen, the web browser was expecting to receive a HTTP Response back, but\nit got no response from the server (we didn't implemented the HTTP Response logic yet).\n\nBut that is okay. We have achieved the result that we wanted for now,\nwhich is to connect to the server, and see the HTTP Request\nthat was sent by the web browser (or by the Python script)\nto the server.\n\nIf you comeback to the console that you left open\nwhen you have executed the program, you will see that the\nprogram finished its execution, and, a new message is\nprinted in the console, which is the actual HTTP Request\nmessage that was sent by the web browser to the server.\nYou can see this message at @fig-print-zigrun2.\n\n![A screenshot of the HTTP Request sent by the web browser](./../Figures/print-zigrun2.png){#fig-print-zigrun2}\n\n\n\n\n## Learning about Enums in Zig {#sec-enum}\n\nEnums structures are available in Zig through the `enum` keyword.\nAn enum (short for \"enumeration\") is a special structure that represents a group of constant values.\nSo, if you have a variable which can assume a short and known\nset of values, you might want to associate this variable to an enum structure,\nto make sure that this variable only assumes a value from this set.\n\nA classic example for enums are primary colors. If for some reason, your program\nneeds to represent one of the primary colors, you can create an enum\nthat represents one of these colors.\nIn the example below, we are creating the enum `PrimaryColorRGB`, which\nrepresents a primary color from the RGB color system. By using this enum,\nI am guaranteed that the `acolor` object for example, will contain\none of these three values: `RED`, `GREEN` or `BLUE`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst PrimaryColorRGB = enum {\n    RED, GREEN, BLUE\n};\nconst acolor = PrimaryColorRGB.RED;\n_ = acolor;\n```\n:::\n\n\n\n\nIf for some reason, my code tries to save in `acolor`,\na value that is not in this set, I will get an error message\nwarning me that a value such as \"MAGENTA\" do not exist\ninside the `PrimaryColorRGB` enum.\nThen I can easily fix my mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst acolor = PrimaryColorRGB.MAGENTA;\n```\n:::\n\n\n\n\n```\ne1.zig:5:36: error: enum 'PrimaryColorRGB' has\n        no member named 'MAGENTA':\n    const acolor = PrimaryColorRGB.MAGENTA;\n                                   ^~~~~~~\n```\n\nBehind the hood, enums in Zig work the same way that enums\nwork in C. Each enum value is essentially represented as an integer.\nThe first value in the set is represented as zero,\nthen, the second value is one, ... etc.\n\nOne thing that we are going to learn on the next section is that\nenums can have methods in them. Wait... What? This is amazing!\nYes, enums in Zig are similar to structs, and they can have\nprivate and public methods inside them.\n\n\n\n\n\n\n\n## Implementing the server - Part 2\n\nNow, on this section, I want to focus on parsing\nthe HTTP Request that we received from the client.\nHowever, to effectively parse a HTTP Request message, we first need to understand its\nstructure.\nIn summary, a HTTP Request is a text message that is divided into 3 different\nsections (or parts):\n\n- The top-level header indicating the method of the HTTP Request, the URI, and the HTTP version used in the message.\n- A list of HTTP Headers.\n- The body of the HTTP Request.\n\n### The top-level header\n\nThe first line of text in a HTTP Request always come with the three most essential\ninformation about the request. These three key attributes of the HTTP Request\nare separated by a simple space in this first line of the request.\nThe first information is the HTTP method that is being\nused in the request, second, we have the URI to which this HTTP Request is being sent to,\nand third, we have the version of the HTTP protocol that is being used in this HTTP Request.\n\nIn the snippet below, you can find an example of this first line in a HTTP Request.\nFirst, we have the HTTP method of this request (`GET`). Many programmers\nrefer to the URI component (`/users/list`) as the \"API endpoint\" to which the HTTP Request\nis being sent to. In the context of this specific request, since it is a GET request,\nyou could also say that the URI component is the path to the resource we want to access,\nor, the path to the document (or the file) that we want to retrieve from the server.\n\n```\nGET /users/list HTTP/1.1\n```\n\nAlso, notice that this HTTP Request is using the version 1.1 of the HTTP protocol,\nwhich is the most popular version of the protocol used in the web.\n\n\n\n### The list of HTTP headers\n\nMost HTTP Requests also include a section of HTTP Headers,\nwhich is just a list of attributes or key-value pairs associated with this\nparticular request. This section always comes right after the \"top-level header\" of the request.\n\nFor our purpose in this chapter, which is to build a simple HTTP Server,\nwe are going to ignore this section of the HTTP Request, for simplicity.\nBut most HTTP servers that exist in the wild parses and use these\nHTTP headers to change the way that the server responds to the request\nsent by the client.\n\nFor example, many requests we encounter in the real-world comes with\na HTTP header called `Accept`. In this header, we find a list of [MIME types](https://en.wikipedia.org/wiki/Media_type)[^mime].\nThis list indicates the file formats that the client can read, or parse, or interpret.\nIn other words, you also interpret this header as the client saying the following phrase\nto the server: \"Hey! Look, I can read only HTML documents, so please, send me back\na document that is in a HTML format.\".\n\n[^mime]: <https://en.wikipedia.org/wiki/Media_type>.\n\nIf the HTTP server can read and use this `Accept` header, then, the server can identify\nwhich is the best file format for the document to be sent to the client. Maybe the HTTP server have\nthe same document in multiple formats, for example, in JSON, in XML, in HTML and in PDF,\nbut the client can only understand documents in the HTML format. That is the purpose\nof this `Accept` header.\n\n\n### The body\n\nThe body comes after the list of HTTP headers, and it is an optional section of the HTTP Request, meaning that, not\nall HTTP Request will come with a body in it. For example, every HTTP Request that uses the\nGET method usually do not come with a body.\n\nBecause a GET request is used to request data, instead of sending it to the server.\nSo, the body section is more related to the POST method, which is a method that involves\nsending data to the server, to be processed and stored.\n\nSince we are going to support only the GET method in this project, it means that\nwe also do not need to care about the body of the request.\n\n\n\n### Creating the HTTP Method enum\n\nEvery HTTP Request comes with a explicit method. The method used in a HTTP Request\nis identified by one these words:\n\n- GET;\n- POST;\n- OPTIONS;\n- PATCH;\n- DELETE;\n- and some other methods.\n\nEach HTTP method is used for a specific type of task. The POST method for example is normally\nused to post some data into the destination. In other words, it is used\nto send some data to the HTTP server, so that it can be processed and stored by the server.\n\nAs another example, the GET method is normally used to get content from the server.\nIn other words, we use this method whenever we want the server to send some\ncontent back to us. It can be any type of content. It can be a web page,\na document file, or some data in a JSON format.\n\nWhen a client sends a POST HTTP Request, the HTTP Response sent by the server normally have the sole purpose of\nletting the client know if the server processed and stored the data successfully.\nIn contrast, when the server receives a GET HTTP Request, then, the server sends the content\nthat the client asked for in the HTTP Response itself. This demonstrates that the method associated\nwith the HTTP Request changes a lot on the dynamics and the roles that each party\nplays in the whole process.\n\nSince the HTTP method of the HTTP Request is identified by this very small and specific\nset of words, it would be interesting to create an enum structure to represent a HTTP method.\nThis way, we can easily check if the HTTP Request we receive from the client is a\nHTTP method that we currently support in our small HTTP server project.\n\nThe `Method` structure below represents this enumeration.\nNotice that, for now, only the GET HTTP method is included in this\nenumeration. Because, for the purpose of this chapter, I want to\nimplement only the GET HTTP method. That is why I am not\nincluding the other HTTP methods in this enumeration.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const Method = enum {\n    GET\n};\n```\n:::\n\n\n\n\n\nNow, I think we should add two methods to this enum structure. One method is `is_supported()`,\nwhich will be a function that returns a boolean value, indicating if the input HTTP method is supported\nor not by our HTTP Server. The other is `init()`, which is a constructor function that takes a string as input,\nand tries to convert it into a `Method` value.\n\n\nBut in order to build these functions, I will use a functionality from the Zig Standard Library, called\n`StaticStringMap()`. This function allows us to create a simple map from strings to enum values.\nIn other words, we can use this map structure to map a string to the respective enum value.\nTo some extent, this specific structure from the standard library works almost like a \"hashtable\" structure,\nand it is optimized for small sets of words, or, small sets of keys, which is our case here.\nWe are going to talk more about hashtables in Zig at @sec-maps-hashtables.\n\nTo use this \"static string map\" structure, you have to import it from the `std.static_string_map` module\nof the Zig Standard Library. Just to make things shorter and easier to type, I am going to import this\nfunction through a different and shorter name (`Map`).\n\nWith `Map()` imported, we can just apply this function over the enum structure\nthat we are going to use in the resulting map. In our case here, it is the `Method` enum structure\nthat we declared at the last code example. Then, I call the `initComptime()` method with the\nmap, i.e. the list of key-value pairs that we are going to use.\n\nYou can see in the example below that I wrote this map using multiple anonymous struct literals.\nInside the first (or \"top-level\") struct literal, we have a list (or a sequence) of struct literals.\nEach struct literal in this list represents a separate key-value pair. The first element (or the key)\nin each key-value pair should always be a string value. While the second element should\nbe a value from the enum structure that you have used inside the `Map()` function.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Map = std.static_string_map.StaticStringMap;\nconst MethodMap = Map(Method).initComptime(.{\n    .{ \"GET\", Method.GET },\n});\n```\n:::\n\n\n\n\nTherefore, the `MethodMap` object is basically a `std::map` object from C++, or,\na `dict` object from Python. You can retrieve (or get) the enum value that\ncorresponds to a particular key, by using the `get()` method from the map\nobject. This method returns an optional value, so, the `get()` method might\nresult in a null value.\n\nWe can use this in our advantage to detect if a particular HTTP method is\nsupported or not in our HTTP server. Because, if the `get()` method returns null,\nit means that it did not found the method that we provided inside the `MethodMap` object, and,\nas a consequence, this method is not supported by our HTTP server.\n\nThe `init()` method below, takes a string value as input, and then, it simply passes this string value\nto the `get()` method of our `MethodMap` object. As consequence, we should get the enum value that corresponds\nto this input string.\n\nNotice in the example below that, the `init()` method returns either an error\n(which might happen if the `?` method returns `unreacheable`, checkout @sec-null-handling for more details)\nor a `Method` object as result. Since `GET` is currently the only value in our `Method` enum\nstructure, it means that, the `init()` method will most likely return the value `Method.GET` as result.\n\nAlso notice that, in the `is_supported()` method, we are using the optional value returned\nby the `get()` method from our `MethodMap` object. The if statement unwraps the optional value\nreturned by this method, and returns `true` in case this optional value is a not-null value.\nOtherwise, it simply returns `false`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const Method = enum {\n    GET,\n    pub fn init(text: []const u8) !Method {\n        return MethodMap.get(text).?;\n    }\n    pub fn is_supported(m: []const u8) bool {\n        const method = MethodMap.get(m);\n        if (method) |_| {\n            return true;\n        }\n        return false;\n    }\n};\n```\n:::\n\n\n\n\n\n\n\n\n\n\n### Writing the parse request function\n\nNow that we created the enum that represents our HTTP method,\nwe should start to write the function responsible for\nactually parsing the HTTP Request.\n\nThe first thing we can do, is to write a struct to represent the HTTP Request.\nTake the `Request` struct below as an example. It contains the three\nessential information from the \"top-level\" header (i.e. the first line)\nin the HTTP Request.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Request = struct {\n    method: Method,\n    version: []const u8,\n    uri: []const u8,\n    pub fn init(method: Method,\n                uri: []const u8,\n                version: []const u8) Request {\n        return Request{\n            .method = method,\n            .uri = uri,\n            .version = version,\n        };\n    }\n};\n```\n:::\n\n\n\n\n\nThe `parse_request()` function should receive a string as input. This input string\ncontains the entire HTTP Request message, and the parsing function should\nread and understand the individual parts of this message.\n\nNow, remember that for the purpose of this chapter, we care only about the first\nline in this message, which contains the \"top-level header\", or, the three essential attributes about the HTTP Request,\nwhich are the HTTP method used, the URI and the HTTP version.\n\nNotice that I use the function `indexOfScalar()` in `parse_request()`. This function from the\nZig Standard Library returns the first index where the scalar value that we provide\nhappens in a string. In this case, I'm looking at the first occurrence of the new line character (`\\n`).\nBecause once again, we care only about the first line in the HTTP Request message.\nThis is the line where we have the three information that we want to parse\n(version of HTTP, the HTTP method and the URI).\n\nTherefore, we are using this `indexOfScalar()` function\nto limit our parsing process to the first line in the message.\nIs also worth mentioning that, the `indexOfScalar()` function returns an optional value.\nThat is why I use the `orelse` keyword to provide an alternative value, in case\nthe value returned by the function is a null value.\n\nSince each of these three attributes are separated by a simple space, we\ncould use the function `splitScalar()` from the Zig Standard Library to split\nthe input string into sections by looking for every position that appears\na simple space. In other words, this `splitScalar()` function is equivalent\nto the `split()` method in Python, or, the `std::getline()` function from C++,\nor the `strtok()` function in C.\n\nWhen you use this `splitScalar()` function, you get an iterator as the result.\nThis iterator have a `next()` method that you can use to advance the iterator\nto the next position, or, to the next section of the splitted string.\nNote that, when you use `next()`, the method not only advances the iterator,\nbut it also returns a slice to the current section of the splitted\nstring as result.\n\nNow, if you want to get a slice to the current section of the splitted\nstring, but not advance the iterator to the next position, you can use\nthe `peek()` method. Both `next()` and `peek()` methods return an optional value, that is\nwhy I use the `?` method to unwrap these optional values.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn parse_request(text: []u8) Request {\n    const line_index = std.mem.indexOfScalar(\n        u8, text, '\\n'\n    ) orelse text.len;\n    var iterator = std.mem.splitScalar(\n        u8, text[0..line_index], ' '\n    );\n    const method = try Method.init(iterator.next().?);\n    const uri = iterator.next().?;\n    const version = iterator.next().?;\n    const request = Request.init(method, uri, version);\n    return request;\n}\n```\n:::\n\n\n\n\n\nAs I described at @sec-zig-strings, strings in Zig are simply arrays of bytes in the language.\nSo, you will find lots of excellent utility functions to work directly with strings\ninside this `mem` module from the Zig Standard Library.\nWe have described some of these useful utility functions already\nat @sec-strings-useful-funs.\n\n\n\n### Using the parse request function\n\nNow that we wrote the function responsible for parsing the HTTP Request,\nwe can add the function call to `parse_request()` in\nthe `main()` function of our program.\n\nAfter that, is a good idea to test once again the state of our program.\nI execute this program again with the `run` command from the `zig` compiler,\nthen, I use my web browser to connect once again to the server through the URL `localhost:3490`, and finally,\nthe end result of our `Request` object is printed to the console.\n\nA quick observation, since I have used the `any` format specifier in the\nprint statement, the data members `version` and `uri` of the `Request`\nstruct were printed as raw integer values. String data being printed\nas integer values is common in Zig, and remember, these integer values are just the decimal representation of\nthe bytes that form the string in question.\n\nIn the result below, the sequence of decimal values 72, 84, 84, 80, 47, 49, 46, 49, and 13,\nare the bytes that form the text \"HTTP/1.1\". And the integer 47, is the decimal value of\nthe character `/`, which represents our URI in this request.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    try Request.read_request(\n        connection, buffer[0..buffer.len]\n    );\n    const request = Request.parse_request(\n        buffer[0..buffer.len]\n    );\n    try stdout.print(\"{any}\\n\", .{request});\n}\n```\n:::\n\n\n\n\n```\nrequest.Request{\n    .method = request.Method.GET,\n    .version = {72, 84, 84, 80, 47, 49, 46, 49, 13},\n    .uri = {47}\n}\n```\n\n\n\n### Sending the HTTP Response to the client\n\nIn this last part, we are going to write the logic responsible for\nsending the HTTP Response from the server to the client. To make things\nsimple, the server in this project will send just a simple web page\ncontaining the text \"Hello world\".\n\nFirst, I create a new Zig module in the project, named `response.zig`.\nIn this module, I will declare just two functions. Each function\ncorresponds to a specific status code in the HTTP Response.\nThe `send_200()` function will send a HTTP Response with status code 200\n(which means \"Success\") to the client. While the `send_404()` function sends a response\nwith status code 404 (which means \"Not found\").\n\nThis is definitely not the most ergonomic and adequate way of handling the\nHTTP Response, but it works for our case here. We are just building toy projects\nin this book after all, therefore, the source code that we write do not need to be perfect.\nIt just needs to work!\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Connection = std.net.Server.Connection;\npub fn send_200(conn: Connection) !void {\n    const message = (\n        \"HTTP/1.1 200 OK\\nContent-Length: 48\"\n        ++ \"\\nContent-Type: text/html\\n\"\n        ++ \"Connection: Closed\\n\\n<html><body>\"\n        ++ \"<h1>Hello, World!</h1></body></html>\"\n    );\n    _ = try conn.stream.write(message);\n}\n\npub fn send_404(conn: Connection) !void {\n    const message = (\n        \"HTTP/1.1 404 Not Found\\nContent-Length: 50\"\n        ++ \"\\nContent-Type: text/html\\n\"\n        ++ \"Connection: Closed\\n\\n<html><body>\"\n        ++ \"<h1>File not found!</h1></body></html>\"\n    );\n    _ = try conn.stream.write(message);\n}\n```\n:::\n\n\n\n\nNotice that both functions receives the connection object as input, and\nuse the `write()` method to write the HTTP Response message directly\ninto this communication channel. As result, the party in the other\nside of the connection (i.e. the client), will receive such message.\n\nMost real-world HTTP Servers will have a single function (or a single struct) to effectively handle\nthe response. It gets the HTTP Request already parsed as input, and then, it tries to build\nthe HTTP Response bit by bit, before the function sends it over the connection.\n\nWe would also have a specialized struct to represent a HTTP Response, and\na lot of methods that would be used to build each part or component of the response object.\nTake the `Response` struct created by the Javascript runtime Bun as an example.\nYou can find this struct in the [`response.zig` module](https://github.com/oven-sh/bun/blob/main/src/bun.js/webcore/response.zig)[^bun-resp]\nin their GitHub project.\n\n[^bun-resp]: <https://github.com/oven-sh/bun/blob/main/src/bun.js/webcore/response.zig>.\n\n\n## The end result\n\nWe can now, update once again our `main()` function to incorporate our new\nfunctions from the `response.zig` module. First, I need to import this module\ninto our `main.zig` module, then, I add the function calls to `send_200()`\nand `send_404()`.\n\nNotice that I'm using if statements to decide which \"response function\" to call,\nbased especially on the URI present in the HTTP Request. If the user asked for\na content (or a document) that is not present in our server, we should respond\nwith a 404 status code. But since we have just a simple HTTP server, with no\nreal documents to send, we can just check if the URI is the root path (`/`)\nor not to decide which function to call.\n\nAlso, notice that I'm using the function `std.mem.eql()` from the Zig Standard Library\nto check if the string from `uri` is equal or not the string `\"/\"`. We have\ndescribed this function already at @sec-strings-useful-funs, so, comeback to\nthat section if you are not familiar yet with this function.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst Response = @import(\"response.zig\");\nconst Method = Request.Method;\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    try Request.read_request(connection, buffer[0..buffer.len]);\n    const request = Request.parse_request(\n        buffer[0..buffer.len]\n    );\n    if (request.method == Method.GET) {\n        if (std.mem.eql(u8, request.uri, \"/\")) {\n            try Response.send_200(connection);\n        } else {\n            try Response.send_404(connection);\n        }\n    }\n}\n```\n:::\n\n\n\n\n\nNow that we adjusted our `main()` function, I can now execute our program, and\nsee the effects of these last changes. First, I execute the program once again, with the\n`run` command of the `zig` compiler. The program will hang, waiting for a client to connect.\n\nThen, I open my web browser, and try to connect to the server again, using the URL `localhost:3490`.\nThis time, instead of getting some sort of an error message from the browser, you will get the message\n\"Hello World\" printed into your web browser. Because this time, the server sended the HTTP Response\nsuccessfully to the web browser, as demonstrated by @fig-print-zigrun3.\n\n\n![The Hello World message sent in the HTTP Response](./../Figures/print-zigrun3.png){#fig-print-zigrun3}\n\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 2 - Building a HTTP Server from scratch\n\nIn this chapter, I want to implement a new\nsmall project with you. This time, we are going\nto implement a basic HTTP Server from scratch.\n\nThe Zig Standard Library already have a HTTP Server\nimplemented, which is available at `std.http.Server`.\nBut again, our objective here in this chapter, is to implement\nit **from scratch**. So we can't use this server object available\nfrom the Zig Standard Library.\n\n## What is a HTTP Server?\n\nFirst of all, what is a HTTP Server?\nA HTTP server, as any other type of server, is essentially\na program that runs indefinitely, on an infinite loop, waiting for incoming connections\nfrom clients. Once the server receives an incoming connection, it will\naccept this connection, and it will send messages back-and-forth to the client\nthrough this connection.\n\nBut the messages that are transmitted inside this connection are in a\nspecific format. They are HTTP messages\n(i.e., messages that use the HTTP Protocol specification).\nThe HTTP Protocol is the backbone of the modern web.\nThe world wide web as we know it today, would not exist without the\nHTTP Protocol.\n\nSo, Web servers (which is just a fancy name to\nHTTP Servers) are servers that exchange HTTP messages with clients.\nAnd these HTTP servers and the HTTP Protocol specification\nare essential to the operation of the world wide web today.\n\nThat is the whole picture of the process.\nAgain, we have two subjects involved here, a server (which is\na program that is running indefinitely, waiting to receive incoming connections),\nand a client (which is someone that wants to connect to the server,\nand exchange HTTP messages with it).\n\nYou may find the material about the [HTTP Protocol available at the Mozilla MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview)[^mdn-http]\n, a great resource for you to also look at. It gives you a great overview on how\nHTTP works, and what role the server plays in this matter.\n\n[^mdn-http]: <https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview>.\n\n\n## How a HTTP Server works? {#sec-how-http-works}\n\nImagine a HTTP Server as if it were the receptionist of a large hotel. In a hotel,\nyou have a reception, and inside that reception there is a receptionist\nwaiting for customers to arrive. A HTTP Server is essentially a receptionist\nthat is indefinitely waiting for new customers (or, in the context of HTTP, new clients)\nto arrive in the hotel.\n\nWhen a customer arrives at the hotel, that customer starts a conversation with the\nreceptionist. He tells the receptionist how many days he wants to stay at the hotel.\nThen, the receptionist search for an available apartment. If there is an available apartment\nat the moment, the customer pays the hotel fees, then, he gets the keys to the apartment,\nand then, he goes to the apartment to rest.\n\nAfter this entire process of dealing with the customer (searching for available apartments,\nreceiving payment, handing over the keys), the receptionist goes back to what he was\ndoing earlier, which is to wait. Wait for new customers to arrive.\n\nThat is, in a nutshell, what a HTTP Server do. It waits for clients to connect to the\nserver. When a client attempts to connect to the server, the server accepts this connection,\nand it starts to exchange messages with the client through this connection.\nThe first message that happens inside this connection is always a message from the client\nto the server. This message is called the *HTTP Request*.\n\nThis HTTP Request is a HTTP message that contains what\nthe client wants from the server. It is literally a request. The client\nthat connected to the server is asking this server to do something for him.\n\nThere are different \"types of request\" that a client can send to a HTTP Server.\nBut the most basic type of request, is when a client ask to the\nHTTP Server to serve (i.e., to send) some specific web page (which is a HTML file) to him.\nWhen you type `google.com` in your web browser, you are essentially sending a HTTP Request to Google's\nHTTP servers. This request is asking these servers to send the Google webpage to you.\n\nNonetheless, when the server receives this first message, the *HTTP Request*, it\nanalyzes this request, to understand: who the client is? What he wants the server to do?\nThis client has provided all the necessary information to perform the action that he\nasked? Etc.\n\nOnce the server understands what the client wants, he simply perform the action\nthat was requested, and, to finish the whole process, the server sends back\na HTTP message to the client, informing if the action performed was successful or not,\nand, at last, the server ends (or closes) the connection with the client.\n\nThis last HTTP message sent from the server to the client, is called the *HTTP Response*.\nBecause the server is responding to the action that was requested by the client.\nThe main objective of this response message is let the client know if the\naction requested was successful or not, before the server closes the connection.\n\n\n## How a HTTP server is normally implemented? {#sec-http-how-impl}\n\nLet's use the C language as an example. There are many materials\nteaching how to write a simple HTTP server in C code, like @jeffrey_http,\nor @nipun_http, or @eric_http.\nHaving this in mind, I will not show C code examples here, because you\ncan find them on the internet.\nBut I will describe the theory behind the necessary steps to create\nsuch HTTP server in C.\n\n\nIn essence, we normally implement a HTTP server in C by using WebSocket technology,\nwhich involves the following steps:\n\n1. Create a socket object.\n1. Bind a name (or more specifically, an address) to this socket object.\n1. Make this socket object to start listening and waiting for incoming connections.\n1. When a connection arrive, we accept this connection, and we exchange the HTTP messages (HTTP Request and HTTP Response).\n1. Then, we simply close this connection.\n\n\nA socket object is essentially a channel of communication.\nYou are creating a channel where people can send messages through.\nWhen you create a socket object, this object is not binded to any particular\naddress. This means that with this object you have a representation of a channel of communication\nin your hands. But this channel is not currently available, or, it is not currently accessible,\nbecause it does not have a known address where you can find it.\n\nThat is what the \"bind\" operation do. It binds a name (or more specifically, an address) to\nthis socket object, or, this channel of communication, so that it becomes available,\nor, accessible through this address. While the \"listen\" operation makes the socket object to\nlisten for incoming connections in this address. In other words, the \"listen\" operation\nmakes the socket to wait for incoming connections.\ncurrently\nNow, when a client actually attempts to connect to the server through the socket address\nthat we have specified, in order to establish this connection with the client,\nthe socket object needs to accept this incoming connection. Thus, when we\naccept an incoming connection, the client and the server become\nconnected to each other, and they can start reading or writing messages into this\nestablished connection.\n\nAfter we receive the HTTP Request from the client, analyze it, and send the HTTP Response\nto the client, we can then close the connection, and end this communication.\n\n\n## Implementing the server - Part 1\n\n### Creating the socket object {#sec-create-socket}\n\nLet's begin with creating the socket object for our server.\nJust to make things shorter, I will create this socket object in\na separate Zig module. I will name it `config.zig`.\n\nIn Zig, we can create a web socket using\nthe `std.posix.socket()` function, from the Zig Standard Library.\nAs I mentioned earlier in @sec-http-how-impl, every socket object that we create\nrepresents a communication channel, and we need to bind this channel to a specific address.\nAn \"address\" is defined as an IP address, or, more specifically, an IPv4 address^[It can be also an IPv6 address. But normally, we use a IPv4 address for that.].\nEvery IPv4 address is composed by two components. The first component is the host,\nwhich is a sequence of 4 numbers separated by dot characters (`.`) that identifies the machine used.\nWhile the second component is a port number, which identifies the specific\ndoor, or, the specific port to use in the host machine.\n\nThe sequence of 4 numbers (i.e., the host) identifies the machine (i.e., the computer itself) where\nthis socket will live in. Every computer normally have multiple \"doors\" available inside of him, because\nthis allows the computer to receive and work with multiple connections at the same time.\nHe simply use a single door for each connection. So the port number, is\nessentially a number that identifies the specific door in the computer that will be responsible\nfor receiving the connection. That is, it identifies the \"door\" in the computer that the socket will use\nto receive incoming connections.\n\nTo make things simpler, I will use an IP address that identifies our current machine in this example.\nThis means that, our socket object will reside on the same computer that we are currently using\n(this is also known as the \"localhost\") to write this Zig source code.\n\nBy convention, the IP address that identifies the \"localhost\", which is the current machine we\nare using, is the IP `127.0.0.1`. So, that is the IP\naddress we are going to use in our server. I can declare it in Zig\nby using an array of 4 integers, like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst localhost = [4]u8{ 127, 0, 0, 1 };\n_ = localhost;\n```\n:::\n\n\n\n\nNow, we need to decide which port number to use. By convention, there are some\nport numbers that are reserved, meaning that, we cannot use them for our own\npurposes, like the port 22 (which is normally used for SSH connections).\nFor TCP connections, which is our case here,\na port number is a 16-bit unsigned integer (type `u16` in Zig),\nthus ranging from 0 to 65535 [@wikipedia_port].\nSo, we can choose\na number from 0 to 65535 for our port number. In the\nexample of this book, I will use the port number 3490\n(just a random number).\n\n\nNow that we have these two informations at hand, I can\nfinally create our socket object, using the `std.posix.socket()` function.\nFirst, we use the host and the port number to create an `Address` object,\nwith the `std.net.Address.initIp4()` function, like in the example below.\nAfter that, I use this address object inside the `socket()` function\nto create our socket object.\n\nThe `Socket` struct defined below summarizes all the logic behind\nthis process. In this struct, we have two data members, which are:\n1)  the address object; 2) and a stream object, which is\nthe object we will use to read and write the messages into any connection we establish.\n\nNotice that, inside the constructor method of this struct,\nwhen we create the socket object, we are using the `IPROTO.TCP` property as an input to\ntell the function to create a socket for TCP connections.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\nconst net = @import(\"std\").net;\n\npub const Socket = struct {\n    _address: std.net.Address,\n    _stream: std.net.Stream,\n\n    pub fn init() !Socket {\n        const host = [4]u8{ 127, 0, 0, 1 };\n        const port = 3490;\n        const addr = net.Address.initIp4(host, port);\n        const socket = try std.posix.socket(\n            addr.any.family,\n            std.posix.SOCK.STREAM,\n            std.posix.IPPROTO.TCP\n        );\n        const stream = net.Stream{ .handle = socket };\n        return Socket{ ._address = addr, ._stream = stream };\n    }\n};\n```\n:::\n\n\n\n\n\n### Listening and receiving connections\n\nRemember that we stored the `Socket` struct\ndeclaration that we built in @sec-create-socket inside a Zig module named `config.zig`.\nThis is why I imported this module into our main module (`main.zig`) in the example below, as the `SocketConf` object,\nto access the `Socket` struct.\n\nOnce we created our socket object, we can focus now on making this socket object\nlisten and receive new incoming connections. We do that, by calling the `listen()`\nmethod from the `Address` object that is contained inside the socket object, and then,\nwe call the `accept()` method over the result.\n\nThe `listen()` method from the `Address` object produces a server object,\nwhich is an object that will stay open and running indefinitely, waiting\nto receive an incoming connection. Therefore, if you try to run the code\nexample below, by calling the `run` command from the `zig` compiler,\nyou will notice that the programs keeps running indefinitely,\nwithout a clear end.\n\nThis happens, because the program is waiting for something to happen.\nIt's waiting for someone to try to connect to the address (`http://127.0.0.1:3490`) where\nthe server is running and listening for incoming connections. This is what\nthe `listen()` method do, it makes the socket to be active waiting for someone\nto connect.\n\nOn the other side, the `accept()` method is the function that establishes the connection\nwhen someone tries to connect to the socket. This means that, the `accept()` method\nreturns a new connection object as a result. And you can use this connection object\nto read or write messages from or to the client.\nFor now, we are not doing anything with this connection object.\nBut we are going to use it in the next section.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n    _ = connection;\n}\n```\n:::\n\n\n\n\nThis code example allows one single connection. In other words, the\nserver will wait for one incoming connection, and as soon as the\nserver is done with this first connection that it establishes, the\nprogram ends, and the server stops.\n\nThis is not the norm in the real world. Most people that write\na HTTP server like this, usually put the `accept()` method\ninside a `while` (infinite) loop, where if a connection\nis created with `accept()`, a new thread of execution is created to deal with\nthis new connection and the client. That is, real-world examples of HTTP Servers\nnormally rely on parallel computing to work.\n\nWith this design, the server simply accepts the connection,\nand the whole process of dealing with the client, and receiving\nthe HTTP Request, and sending the HTTP Response, all of this\nis done in the background, on a separate execution thread.\n\nSo, as soon as the server accepts the connection, and creates\nthe separate thread, the server goes back to what he was doing earlier,\nwhich is to wait indefinitely for a new connection to accept.\nHaving this in mind, the code example exposed above, is a\nserver that serves only a single client. Because the program\nterminates as soon as the connection is accepted.\n\n\n\n### Reading the message from the client {#sec-read-http-message}\n\nNow that we have a connection established, i.e., the connection\nobject that we created through the `accept()` function, we can now\nuse this connection object to read any messages that the client\nsend to our server. But we can also use it to send messages back\nto the client.\n\nThe basic idea is, if we **write** any data into this connection object,\nthen, we are sending data to the client, and if we **read** the data present in\nthis connection object, then, we are reading any data that the\nclient sent to us, through this connection object. So, just\nhave this logic in mind. \"Read\" is for reading messages from the client,\nand \"write\" is to send a message to the client.\n\nRemember from @sec-how-http-works that, the first thing that we need to do is to read the HTTP Request\nsent by the client to our server. Because it is the first message that happens\ninside the established connection, and, as a consequence, it is the first\nthing that we need to deal with.\n\nThat is why, I'm going to create a new Zig module in this small project, named `request.zig`\nto keep all functions related to the HTTP Request\ntogether. Then, I will create a new function named `read_request()` that will\nuse our connection object to read the message sent by the client,\nwhich is the HTTP Request.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Connection = std.net.Server.Connection;\npub fn read_request(conn: Connection,\n                    buffer: []u8) !void {\n    const reader = conn.stream.reader();\n    _ = try reader.read(buffer);\n}\n```\n:::\n\n\n\n\n\nThis function accepts a slice object which behaves as a buffer.\nThe `read_request()` function reads the message sent into\nthe connection object, and saves this message into this buffer object that\nwe have provided as input.\n\nNotice that I'm using the connection object that we created to read\nthe message from the client. I first access the `reader` object that lives inside the\nconnection object. Then, I call the `read()` method of this `reader` object\nto effectively read and save the data sent by the client into the buffer object\nthat we created earlier. I'm discarding the return value\nof the `read()` method, by assigning it to the underscore character (`_`),\nbecause this return value is not useful for us right now.\n\n\n\n## Looking at the current state of the program\n\n\nI think now is a good time to see how our program is currently working. Shall we?\nSo, the first thing I will do is to update the `main.zig` module in our small Zig project,\nso that the `main()` function call this new `read_request()` function that we have just created.\nI will also add a print statement at the end of the `main()` function,\njust so that you can see what the HTTP Request that we have just loaded into the buffer object\nlooks like.\n\nAlso, I'm creating the buffer object in the `main()` function, which will be\nresponsible for storing the message sent by the client, and, I'm also\nusing a `for` loop to initialize all fields of this buffer object to the number zero.\nThis is important to make sure that we don't have uninitialized memory in\nthis object. Because uninitialized memory may cause undefined behaviour in our program.\n\nSince the `read_request()` function should receive as input the buffer object as a slice object (`[]u8`),\nI am using the syntax `array[0..array.len]` to get access to a slice of this `buffer` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    _ = try Request.read_request(\n        connection, buffer[0..buffer.len]\n    );\n    try stdout.print(\"{s}\\n\", .{buffer});\n}\n```\n:::\n\n\n\n\nNow, I'm going to execute this program, with the `run` command from the\n`zig` compiler. But remember, as we sad earlier, as soon as I execute this program, it will\nhang indefinitely, because the program is waiting for a client trying to\nconnect to the server.\n\nMore specifically, the program will pause at the line\nwith the `accept()` call. As soon as a client try to connect to the\nserver, then, the execution will \"unpause\", and the `accept()` function\nwill finally be executed to create the\nconnection object that we need, and the remaining of the program\nwill run.\n\nYou can see that in @fig-print-zigrun1. The message `Server Addr: 127.0.0.1:3490`\nis printed to the console, and the program is now waiting for an incoming connection.\n\n![A screenshot of running the program](./../Figures/print-zigrun1.png){#fig-print-zigrun1}\n\n\nWe can finally try to connect to this server, and there are several ways we can do this.\nFor example, we could use the following Python script:\n\n```python\nimport requests\nrequests.get(\"http://127.0.0.1:3490\")\n```\n\nOr, we could also open any web browser of our preference, and type\nthe URL `localhost:3490`. OBS: `localhost` is the same thing as the\nIP `127.0.0.1`. When you press enter, and your web browser go\nto this address, first, the browser will probably print a message\nsaying that \"this page isn't working\", and, then, it will\nprobably change to a new message saying that \"the site can't be\nreached\".\n\nYou get these \"error messages\" in the web browser, because\nit got no response back from the server. In other words, when the web\nbrowser connected to our server, it did send the HTTP Request through the established connection.\nThen, the web browser was expecting to receive a HTTP Response back, but\nit got no response from the server (we didn't implemented the HTTP Response logic yet).\n\nBut that is okay. We have achieved the result that we wanted for now,\nwhich is to connect to the server, and see the HTTP Request\nthat was sent by the web browser (or by the Python script)\nto the server.\n\nIf you comeback to the console that you left open\nwhen you have executed the program, you will see that the\nprogram finished its execution, and, a new message is\nprinted in the console, which is the actual HTTP Request\nmessage that was sent by the web browser to the server.\nYou can see this message in @fig-print-zigrun2.\n\n![A screenshot of the HTTP Request sent by the web browser](./../Figures/print-zigrun2.png){#fig-print-zigrun2}\n\n\n\n\n## Learning about Enums in Zig {#sec-enum}\n\nEnums structures are available in Zig through the `enum` keyword.\nAn enum (short for \"enumeration\") is a special structure that represents a group of constant values.\nSo, if you have a variable which can assume a short and known\nset of values, you might want to associate this variable to an enum structure,\nto make sure that this variable only assumes a value from this set.\n\nA classic example for enums are primary colors. If for some reason, your program\nneeds to represent one of the primary colors, you can create an enum\nthat represents one of these colors.\nIn the example below, we are creating the enum `PrimaryColorRGB`, which\nrepresents a primary color from the RGB color system. By using this enum,\nI am guaranteed that the `acolor` object for example, will contain\none of these three values: `RED`, `GREEN` or `BLUE`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst PrimaryColorRGB = enum {\n    RED, GREEN, BLUE\n};\nconst acolor = PrimaryColorRGB.RED;\n_ = acolor;\n```\n:::\n\n\n\n\nIf for some reason, my code tries to save in `acolor`,\na value that is not in this set, I will get an error message\nwarning me that a value such as \"MAGENTA\" do not exist\ninside the `PrimaryColorRGB` enum.\nThen I can easily fix my mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst acolor = PrimaryColorRGB.MAGENTA;\n```\n:::\n\n\n\n\n```\ne1.zig:5:36: error: enum 'PrimaryColorRGB' has\n        no member named 'MAGENTA':\n    const acolor = PrimaryColorRGB.MAGENTA;\n                                   ^~~~~~~\n```\n\nBehind the hood, enums in Zig work the same way that enums\nwork in C. Each enum value is essentially represented as an integer.\nThe first value in the set is represented as zero,\nthen, the second value is one, ... etc.\n\nOne thing that we are going to learn in the next section is that\nenums can have methods in them. Wait... What? This is amazing!\nYes, enums in Zig are similar to structs, and they can have\nprivate and public methods inside them.\n\n\n\n\n\n\n\n## Implementing the server - Part 2\n\nNow, on this section, I want to focus on parsing\nthe HTTP Request that we received from the client.\nHowever, to effectively parse a HTTP Request message, we first need to understand its\nstructure.\nIn summary, a HTTP Request is a text message that is divided into 3 different\nsections (or parts):\n\n- The top-level header indicating the method of the HTTP Request, the URI, and the HTTP version used in the message.\n- A list of HTTP Headers.\n- The body of the HTTP Request.\n\n### The top-level header\n\nThe first line of text in a HTTP Request always come with the three most essential\ninformation about the request. These three key attributes of the HTTP Request\nare separated by a simple space in this first line of the request.\nThe first information is the HTTP method that is being\nused in the request, second, we have the URI to which this HTTP Request is being sent to,\nand third, we have the version of the HTTP protocol that is being used in this HTTP Request.\n\nIn the snippet below, you can find an example of this first line in a HTTP Request.\nFirst, we have the HTTP method of this request (`GET`). Many programmers\nrefer to the URI component (`/users/list`) as the \"API endpoint\" to which the HTTP Request\nis being sent to. In the context of this specific request, since it's a GET request,\nyou could also say that the URI component is the path to the resource we want to access,\nor, the path to the document (or the file) that we want to retrieve from the server.\n\n```\nGET /users/list HTTP/1.1\n```\n\nAlso, notice that this HTTP Request is using the version 1.1 of the HTTP protocol,\nwhich is the most popular version of the protocol used in the web.\n\n\n\n### The list of HTTP headers\n\nMost HTTP Requests also include a section of HTTP Headers,\nwhich is just a list of attributes or key-value pairs associated with this\nparticular request. This section always comes right after the \"top-level header\" of the request.\n\nFor our purpose in this chapter, which is to build a simple HTTP Server,\nwe are going to ignore this section of the HTTP Request, for simplicity.\nBut most HTTP servers that exist in the wild parses and use these\nHTTP headers to change the way that the server responds to the request\nsent by the client.\n\nFor example, many requests we encounter in the real-world comes with\na HTTP header called `Accept`. In this header, we find a list of [MIME types](https://en.wikipedia.org/wiki/Media_type)[^mime].\nThis list indicates the file formats that the client can read, or parse, or interpret.\nIn other words, you also interpret this header as the client saying the following phrase\nto the server: \"Hey! Look, I can read only HTML documents, so please, send me back\na document that is in a HTML format.\".\n\n[^mime]: <https://en.wikipedia.org/wiki/Media_type>.\n\nIf the HTTP server can read and use this `Accept` header, then, the server can identify\nwhich is the best file format for the document to be sent to the client. Maybe the HTTP server have\nthe same document in multiple formats, for example, in JSON, in XML, in HTML and in PDF,\nbut the client can only understand documents in the HTML format. That is the purpose\nof this `Accept` header.\n\n\n### The body\n\nThe body comes after the list of HTTP headers, and it's an optional section of the HTTP Request, meaning that, not\nall HTTP Requests will come with a body in them. For example, every HTTP Request that uses the\nGET method usually does not come with a body.\n\nBecause a GET request is used to request data, instead of sending it to the server.\nSo, the body section is more related to the POST method, which is a method that involves\nsending data to the server, to be processed and stored.\n\nSince we are going to support only the GET method in this project, it means that\nwe also do not need to care about the body of the request.\n\n\n\n### Creating the HTTP Method enum\n\nEvery HTTP Request comes with a explicit method. The method used in a HTTP Request\nis identified by one these words:\n\n- GET;\n- POST;\n- OPTIONS;\n- PATCH;\n- DELETE;\n- and some other methods.\n\nEach HTTP method is used for a specific type of task. The POST method for example is normally\nused to post some data into the destination. In other words, it's used\nto send some data to the HTTP server, so that it can be processed and stored by the server.\n\nAs another example, the GET method is normally used to get content from the server.\nIn other words, we use this method whenever we want the server to send some\ncontent back to us. It can be any type of content. It can be a web page,\na document file, or some data in a JSON format.\n\nWhen a client sends a POST HTTP Request, the HTTP Response sent by the server normally have the sole purpose of\nletting the client know if the server processed and stored the data successfully.\nIn contrast, when the server receives a GET HTTP Request, then, the server sends the content\nthat the client asked for in the HTTP Response itself. This demonstrates that the method associated\nwith the HTTP Request changes a lot on the dynamics and the roles that each party\nplays in the whole process.\n\nSince the HTTP method of the HTTP Request is identified by this very small and specific\nset of words, it would be interesting to create an enum structure to represent a HTTP method.\nThis way, we can easily check if the HTTP Request we receive from the client is a\nHTTP method that we currently support in our small HTTP server project.\n\nThe `Method` structure below represents this enumeration.\nNotice that, for now, only the GET HTTP method is included in this\nenumeration. Because, for the purpose of this chapter, I want to\nimplement only the GET HTTP method. That is why I am not\nincluding the other HTTP methods in this enumeration.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const Method = enum {\n    GET\n};\n```\n:::\n\n\n\n\n\nNow, I think we should add two methods to this enum structure. One method is `is_supported()`,\nwhich will be a function that returns a boolean value, indicating if the input HTTP method is supported\nor not by our HTTP Server. The other is `init()`, which is a constructor function that takes a string as input,\nand tries to convert it into a `Method` value.\n\n\nBut in order to build these functions, I will use a functionality from the Zig Standard Library, called\n`StaticStringMap()`. This function allows us to create a simple map from strings to enum values.\nIn other words, we can use this map structure to map a string to the respective enum value.\nTo some extent, this specific structure from the standard library works almost like a \"hashtable\" structure,\nand it's optimized for small sets of words, or, small sets of keys, which is our case here.\nWe are going to talk more about hashtables in Zig in @sec-maps-hashtables.\n\nTo use this \"static string map\" structure, you have to import it from the `std.static_string_map` module\nof the Zig Standard Library. Just to make things shorter and easier to type, I am going to import this\nfunction through a different and shorter name (`Map`).\n\nWith `Map()` imported, we can just apply this function over the enum structure\nthat we are going to use in the resulting map. In our case here, it's the `Method` enum structure\nthat we declared at the last code example. Then, I call the `initComptime()` method with the\nmap, i.e., the list of key-value pairs that we are going to use.\n\nYou can see in the example below that I wrote this map using multiple anonymous struct literals.\nInside the first (or \"top-level\") struct literal, we have a list (or a sequence) of struct literals.\nEach struct literal in this list represents a separate key-value pair. The first element (or the key)\nin each key-value pair should always be a string value. While the second element should\nbe a value from the enum structure that you have used inside the `Map()` function.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Map = std.static_string_map.StaticStringMap;\nconst MethodMap = Map(Method).initComptime(.{\n    .{ \"GET\", Method.GET },\n});\n```\n:::\n\n\n\n\nTherefore, the `MethodMap` object is basically a `std::map` object from C++, or,\na `dict` object from Python. You can retrieve (or get) the enum value that\ncorresponds to a particular key, by using the `get()` method from the map\nobject. This method returns an optional value, so, the `get()` method might\nresult in a null value.\n\nWe can use this in our advantage to detect if a particular HTTP method is\nsupported or not in our HTTP server. Because, if the `get()` method returns null,\nit means that it did not found the method that we provided inside the `MethodMap` object, and,\nas a consequence, this method is not supported by our HTTP server.\n\nThe `init()` method below, takes a string value as input, and then, it simply passes this string value\nto the `get()` method of our `MethodMap` object. As consequence, we should get the enum value that corresponds\nto this input string.\n\nNotice in the example below that, the `init()` method returns either an error\n(which might happen if the `?` method returns `unreacheable`, checkout @sec-null-handling for more details)\nor a `Method` object as result. Since `GET` is currently the only value in our `Method` enum\nstructure, it means that, the `init()` method will most likely return the value `Method.GET` as result.\n\nAlso notice that, in the `is_supported()` method, we are using the optional value returned\nby the `get()` method from our `MethodMap` object. The if statement unwraps the optional value\nreturned by this method, and returns `true` in case this optional value is a not-null value.\nOtherwise, it simply returns `false`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const Method = enum {\n    GET,\n    pub fn init(text: []const u8) !Method {\n        return MethodMap.get(text).?;\n    }\n    pub fn is_supported(m: []const u8) bool {\n        const method = MethodMap.get(m);\n        if (method) |_| {\n            return true;\n        }\n        return false;\n    }\n};\n```\n:::\n\n\n\n\n\n\n\n\n\n\n### Writing the parse request function\n\nNow that we created the enum that represents our HTTP method,\nwe should start to write the function responsible for\nactually parsing the HTTP Request.\n\nThe first thing we can do, is to write a struct to represent the HTTP Request.\nTake the `Request` struct below as an example. It contains the three\nessential information from the \"top-level\" header (i.e., the first line)\nin the HTTP Request.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Request = struct {\n    method: Method,\n    version: []const u8,\n    uri: []const u8,\n    pub fn init(method: Method,\n                uri: []const u8,\n                version: []const u8) Request {\n        return Request{\n            .method = method,\n            .uri = uri,\n            .version = version,\n        };\n    }\n};\n```\n:::\n\n\n\n\n\nThe `parse_request()` function should receive a string as input. This input string\ncontains the entire HTTP Request message, and the parsing function should\nread and understand the individual parts of this message.\n\nNow, remember that for the purpose of this chapter, we care only about the first\nline in this message, which contains the \"top-level header\", or, the three essential attributes about the HTTP Request,\nwhich are the HTTP method used, the URI and the HTTP version.\n\nNotice that I use the function `indexOfScalar()` in `parse_request()`. This function from the\nZig Standard Library returns the first index where the scalar value that we provide\nhappens in a string. In this case, I'm looking at the first occurrence of the new line character (`\\n`).\nBecause once again, we care only about the first line in the HTTP Request message.\nThis is the line where we have the three information that we want to parse\n(version of HTTP, the HTTP method and the URI).\n\nTherefore, we are using this `indexOfScalar()` function\nto limit our parsing process to the first line in the message.\nIt's also worth mentioning that, the `indexOfScalar()` function returns an optional value.\nThat is why I use the `orelse` keyword to provide an alternative value, in case\nthe value returned by the function is a null value.\n\nSince each of these three attributes are separated by a simple space, we\ncould use the function `splitScalar()` from the Zig Standard Library to split\nthe input string into sections by looking for every position that appears\na simple space. In other words, this `splitScalar()` function is equivalent\nto the `split()` method in Python, or, the `std::getline()` function from C++,\nor the `strtok()` function in C.\n\nWhen you use this `splitScalar()` function, you get an iterator as the result.\nThis iterator have a `next()` method that you can use to advance the iterator\nto the next position, or, to the next section of the splitted string.\nNote that, when you use `next()`, the method not only advances the iterator,\nbut it also returns a slice to the current section of the splitted\nstring as result.\n\nNow, if you want to get a slice to the current section of the splitted\nstring, but not advance the iterator to the next position, you can use\nthe `peek()` method. Both `next()` and `peek()` methods return an optional value, that is\nwhy I use the `?` method to unwrap these optional values.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn parse_request(text: []u8) Request {\n    const line_index = std.mem.indexOfScalar(\n        u8, text, '\\n'\n    ) orelse text.len;\n    var iterator = std.mem.splitScalar(\n        u8, text[0..line_index], ' '\n    );\n    const method = try Method.init(iterator.next().?);\n    const uri = iterator.next().?;\n    const version = iterator.next().?;\n    const request = Request.init(method, uri, version);\n    return request;\n}\n```\n:::\n\n\n\n\n\nAs I described in @sec-zig-strings, strings in Zig are simply arrays of bytes in the language.\nSo, you will find lots of excellent utility functions to work directly with strings\ninside this `mem` module from the Zig Standard Library.\nWe have described some of these useful utility functions already\nin @sec-strings-useful-funs.\n\n\n\n### Using the parse request function\n\nNow that we wrote the function responsible for parsing the HTTP Request,\nwe can add the function call to `parse_request()` in\nthe `main()` function of our program.\n\nAfter that, is a good idea to test once again the state of our program.\nI execute this program again with the `run` command from the `zig` compiler,\nthen, I use my web browser to connect once again to the server through the URL `localhost:3490`, and finally,\nthe end result of our `Request` object is printed to the console.\n\nA quick observation, since I have used the `any` format specifier in the\nprint statement, the data members `version` and `uri` of the `Request`\nstruct were printed as raw integer values. String data being printed\nas integer values is common in Zig, and remember, these integer values are just the decimal representation of\nthe bytes that form the string in question.\n\nIn the result below, the sequence of decimal values 72, 84, 84, 80, 47, 49, 46, 49, and 13,\nare the bytes that form the text \"HTTP/1.1\". And the integer 47, is the decimal value of\nthe character `/`, which represents our URI in this request.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    try Request.read_request(\n        connection, buffer[0..buffer.len]\n    );\n    const request = Request.parse_request(\n        buffer[0..buffer.len]\n    );\n    try stdout.print(\"{any}\\n\", .{request});\n}\n```\n:::\n\n\n\n\n```\nrequest.Request{\n    .method = request.Method.GET,\n    .version = {72, 84, 84, 80, 47, 49, 46, 49, 13},\n    .uri = {47}\n}\n```\n\n\n\n### Sending the HTTP Response to the client\n\nIn this last part, we are going to write the logic responsible for\nsending the HTTP Response from the server to the client. To make things\nsimple, the server in this project will send just a simple web page\ncontaining the text \"Hello world\".\n\nFirst, I create a new Zig module in the project, named `response.zig`.\nIn this module, I will declare just two functions. Each function\ncorresponds to a specific status code in the HTTP Response.\nThe `send_200()` function will send a HTTP Response with status code 200\n(which means \"Success\") to the client. While the `send_404()` function sends a response\nwith status code 404 (which means \"Not found\").\n\nThis is definitely not the most ergonomic and adequate way of handling the\nHTTP Response, but it works for our case here. We are just building toy projects\nin this book after all, therefore, the source code that we write do not need to be perfect.\nIt just needs to work!\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Connection = std.net.Server.Connection;\npub fn send_200(conn: Connection) !void {\n    const message = (\n        \"HTTP/1.1 200 OK\\nContent-Length: 48\"\n        ++ \"\\nContent-Type: text/html\\n\"\n        ++ \"Connection: Closed\\n\\n<html><body>\"\n        ++ \"<h1>Hello, World!</h1></body></html>\"\n    );\n    _ = try conn.stream.write(message);\n}\n\npub fn send_404(conn: Connection) !void {\n    const message = (\n        \"HTTP/1.1 404 Not Found\\nContent-Length: 50\"\n        ++ \"\\nContent-Type: text/html\\n\"\n        ++ \"Connection: Closed\\n\\n<html><body>\"\n        ++ \"<h1>File not found!</h1></body></html>\"\n    );\n    _ = try conn.stream.write(message);\n}\n```\n:::\n\n\n\n\nNotice that both functions receives the connection object as input, and\nuse the `write()` method to write the HTTP Response message directly\ninto this communication channel. As result, the party in the other\nside of the connection (i.e., the client), will receive such message.\n\nMost real-world HTTP Servers will have a single function (or a single struct) to effectively handle\nthe response. It gets the HTTP Request already parsed as input, and then, it tries to build\nthe HTTP Response bit by bit, before the function sends it over the connection.\n\nWe would also have a specialized struct to represent a HTTP Response, and\na lot of methods that would be used to build each part or component of the response object.\nTake the `Response` struct created by the Javascript runtime Bun as an example.\nYou can find this struct in the [`response.zig` module](https://github.com/oven-sh/bun/blob/main/src/bun.js/webcore/response.zig)[^bun-resp]\nin their GitHub project.\n\n[^bun-resp]: <https://github.com/oven-sh/bun/blob/main/src/bun.js/webcore/response.zig>.\n\n\n## The end result\n\nWe can now, update once again our `main()` function to incorporate our new\nfunctions from the `response.zig` module. First, I need to import this module\ninto our `main.zig` module, then, I add the function calls to `send_200()`\nand `send_404()`.\n\nNotice that I'm using if statements to decide which \"response function\" to call,\nbased especially on the URI present in the HTTP Request. If the user asked for\na content (or a document) that is not present in our server, we should respond\nwith a 404 status code. But since we have just a simple HTTP server, with no\nreal documents to send, we can just check if the URI is the root path (`/`)\nor not to decide which function to call.\n\nAlso, notice that I'm using the function `std.mem.eql()` from the Zig Standard Library\nto check if the string from `uri` is equal or not the string `\"/\"`. We have\ndescribed this function already in @sec-strings-useful-funs, so, comeback to\nthat section if you are not familiar yet with this function.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst Response = @import(\"response.zig\");\nconst Method = Request.Method;\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    try Request.read_request(connection, buffer[0..buffer.len]);\n    const request = Request.parse_request(\n        buffer[0..buffer.len]\n    );\n    if (request.method == Method.GET) {\n        if (std.mem.eql(u8, request.uri, \"/\")) {\n            try Response.send_200(connection);\n        } else {\n            try Response.send_404(connection);\n        }\n    }\n}\n```\n:::\n\n\n\n\n\nNow that we adjusted our `main()` function, I can now execute our program, and\nsee the effects of these last changes. First, I execute the program once again, with the\n`run` command of the `zig` compiler. The program will hang, waiting for a client to connect.\n\nThen, I open my web browser, and try to connect to the server again, using the URL `localhost:3490`.\nThis time, instead of getting some sort of an error message from the browser, you will get the message\n\"Hello World\" printed into your web browser. Because this time, the server sended the HTTP Response\nsuccessfully to the web browser, as demonstrated by @fig-print-zigrun3.\n\n\n![The Hello World message sent in the HTTP Response](./../Figures/print-zigrun3.png){#fig-print-zigrun3}\n",
+    "supporting": [
+      "04-http-server_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/05-pointers/execute-results/html.json b/_freeze/Chapters/05-pointers/execute-results/html.json
index 12c21289..322b1cc9 100644
--- a/_freeze/Chapters/05-pointers/execute-results/html.json
+++ b/_freeze/Chapters/05-pointers/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "8fdb1694a88afd9b81c337b29ec84c86",
+  "hash": "8201d761dfd46af14c754587b77047a2",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Pointers and Optionals {#sec-pointer}\n\nOn our next project we are going to build a HTTP server from scratch.\nBut in order to do that, we need to learn more about pointers and how they work in Zig.\nPointers in Zig are similar to pointers in C. But they come with some extra advantages in Zig.\n\nA pointer is an object that contains a memory address. This memory address is the address where\na particular value is stored in memory. It can be any value. Most of the times,\nit is a value that comes from another object (or variable) present in our code.\n\nIn the example below, I'm creating two objects (`number` and `pointer`).\nThe `pointer` object contains the memory address where the value of the `number` object\n(the number 5) is stored. So, that is a pointer in a nutshell. It is a memory\naddress that points to a particular existing value in the memory. You could\nalso say, that, the `pointer` object points to the memory address where the `number` object is\nstored.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number: u8 = 5;\nconst pointer = &number;\n_ = pointer;\n```\n:::\n\n\n\n\nWe create a pointer object in Zig by using the `&` operator. When you put this operator\nbefore the name of an existing object, you get the memory address of this object as result.\nWhen you store this memory address inside a new object, this new object becomes a pointer object.\nBecause it stores a memory address.\n\nPeople mostly use pointers as an alternative way to access a particular value.\nFor example, I can use the `pointer` object to access the value stored by\nthe `number` object. This operation of accessing the value that the\npointer \"points to\" is normally called of *dereferencing the pointer*.\nWe can dereference a pointer in Zig by using the `*` method of the pointer object. Like in the example\nbelow, where we take the number 5 pointed by the `pointer` object,\nand double it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number: u8 = 5;\nconst pointer = &number;\nconst doubled = 2 * pointer.*;\nstd.debug.print(\"{d}\\n\", .{doubled});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n10\n```\n\n\n:::\n:::\n\n\n\n\n\nThis syntax to dereference the pointer is nice. Because we can easily chain it with\nmethods of the value pointed by the pointer. We can use the `User` struct that we have\ncreated at @sec-structs-and-oop as an example. If you comeback to that section,\nyou will see that this struct have a method named `print_name()`.\n\nSo, for example, if we have an user object, and a pointer that points to this user object,\nwe can use the pointer to access this user object, and, at the same time, call the method `print_name()`\non it, by chaining the dereference method (`*`) with the `print_name()` method. Like in the\nexample below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst u = User.init(1, \"pedro\", \"email@gmail.com\");\nconst pointer = &u;\ntry pointer.*.print_name();\n```\n:::\n\n\n\n\n```\npedro\n```\n\nWe can also use pointers to effectively alter the value of an object.\nFor example, I could use the `pointer` object to set\nthe value of the object `number` to 6, like in the example below.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n6\n```\n\n\n:::\n:::\n\n\n\n\n\nTherefore, as I mentioned earlier, people use pointers as an alternative way to access a particular value.\nAnd they use it especially when they do not want to \"move\" these values around. There are situations where,\nyou want to access a particular value in a different scope (i.e. a different location) of your code,\nbut you do not want to \"move\" this value to this new scope (or location) that you are in.\n\nThis matters especially if this value is big in size. Because if it is, then,\nmoving this value becomes an expensive operation to do.\nThe computer will have to spend a considerable amount of time\ncopying this value to this new location.\n\nTherefore, many programmers prefer to avoid this heavy operation of copying the value\nto the new location, by accessing this value through pointers.\nWe are going to talk more about this \"moving operation\" over the next sections.\nFor now, just keep in mind that avoiding this \"move operation\" is\none of main reasons why pointers are used in programming languages.\n\n\n\n\n\n## Constant objects vs variable objects {#sec-pointer-var}\n\nYou can have a pointer that points to a constant object, or, a pointer that points to a variable object.\nBut regardless of who this pointer is, a pointer **must always respect the characteristics of the object that it points to**.\nAs a consequence, if the pointer points to a constant object, then, you cannot use this pointer\nto change the value that it points to. Because it points to a value that is constant. As we discussed at @sec-assignments, you cannot\nchange a value that is constant.\n\nFor example, if I have a `number` object, which is constant, I cannot execute\nthe expression below where I'm trying to change the value of `number` to 6 through\nthe `pointer` object. As demonstrated below, when you try to do something\nlike that, you get a compile time error:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number = 5;\nconst pointer = &number;\npointer.* = 6;\n```\n:::\n\n\n\n\n```\np.zig:6:12: error: cannot assign to constant\n    pointer.* = 6;\n```\n\nIf I change the `number` object to be a variable object, by introducing the `var` keyword,\nthen, I can successfully change the value of this object through a pointer, as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n6\n```\n\n\n:::\n:::\n\n\n\n\nYou can see this relationship between \"constant versus variable\" on the data type of\nyour pointer object. In other words, the data type of a pointer object already gives you\nsome clues about whether the value that it points to is constant or not.\n\nWhen a pointer object points to a constant value, then, this pointer have a data type `*const T`,\nwhich means \"a pointer to a constant value of type `T`\".\nIn contrast, if the pointer points to a variable value, then, the type of the pointer is usually `*T`, which is\nsimply \"a pointer to a value of type `T`\".\nHence, whenever you see a pointer object whose data type is in the format `*const T`, then,\nyou know that you cannot use this pointer to change the value that it points to.\nBecause this pointer points to a constant value of type `T`.\n\n\nWe have talked about the value pointed by the pointer being constant or not,\nand the consequences that arises from it. But, what about the pointer object itself? I mean, what happens\nif the pointer object itself is constant or not? Think about it.\nWe can have a constant pointer that points to a constant value.\nBut we can also have a variable pointer that points to a constant value. And vice-versa.\n\nUntil this point, the `pointer` object was always constant,\nbut what this means for us? What is the consequence of the\n`pointer` object being constant? The consequence is that\nwe cannot change the pointer object, because it is constant. We can use the\npointer object in multiple ways, but we cannot change the\nmemory address that is inside this pointer object.\n\nHowever, if we mark the `pointer` object as a variable object,\nthen, we can change the memory address pointed by this `pointer` object.\nThe example below demonstrates that. Notice that the object pointed\nby the `pointer` object changes from `c1` to `c2`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c1: u8 = 5;\nconst c2: u8 = 6;\nvar pointer = &c1;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\npointer = &c2;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\n```\n:::\n\n\n\n\n```\n5\n6\n```\n\nThus, by setting the `pointer` object to a `var` or `const` object,\nyou specify if the memory address contained in this pointer object can change or not\nin your program. On the other side, you can change the value pointed by the pointer,\nif, and only if this value is stored in a variable object. If this value\nis in a constant object, then, you cannot change this value through a pointer.\n\n\n## Types of pointer\n\nIn Zig, there are two types of pointers [@zigdocs], which are:\n\n- single-item pointer (`*`);\n- many-item pointer (`[*]`);\n\n\nSingle-item pointer objects are objects whose data types are in the format `*T`.\nSo, for example, if an object have a data type `*u32`, it means that, this\nobject contains a single-item pointer that points to an unsigned 32-bit integer value.\nAs another example, if an object have type `*User`, then, it contains\na single-item pointer to an `User` value.\n\nIn contrast, many-item pointers are objects whose data types are in the format `[*]T`.\nNotice that the star symbol (`*`) is now inside a pair of brackets (`[]`). If the star\nsymbol is inside a pair of brackets, you know that this object is a many-item pointer.\n\nWhen you apply the `&` operator over an object, you will always get a single-item pointer.\nMany-item pointers are more of a \"internal type\" of the language, more closely\nrelated to slices. So, when you deliberately create a pointer with the `&` operator,\nyou always get a single-item pointer as result.\n\n\n\n## Pointer arithmetic\n\nPointer arithmetic is available in Zig, and they work the same way they work in C.\nWhen you have a pointer that points to an array, the pointer usually points to\nthe first element in the array, and you can use pointer arithmetic to\nadvance this pointer and access the other elements in the array.\n\n\nNotice in the example below, that initially, the `ptr` object was pointing\nto the first element in the array `ar`. But then, I started to walk through the array, by advancing\nthe pointer with simple pointer arithmetic.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [_]i32{ 1, 2, 3, 4 };\nvar ptr: [*]const i32 = &ar;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\n```\n:::\n\n\n\n\n```\n1\n2\n3\n```\n\nAlthough you can create a pointer to an array like that, and\nstart to walk through this array by using pointer arithmetic,\nin Zig, we prefer to use slices, which were presented at @sec-arrays.\n\nBehind the hood, slices already are pointers,\nand they also come with the `len` property, which indicates\nhow many elements are in the slice. This is good because the `zig` compiler\ncan use it to check for potential buffer overflows, and other problems like that.\n\nAlso, you don't need to use pointer arithmetic to walk through the elements\nof a slice. You can simply use the `slice[index]` syntax to directly access\nany element you want in the slice.\nAs I mentioned at @sec-arrays, you can get a slice from an array by using\na range selector inside brackets. In the example below, I'm creating\na slice (`sl`) that covers the entire `ar` array. I can access any\nelement of `ar` from this slice, and, the slice itself already is a pointer\nbehind the hood.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [_]i32{1,2,3,4};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\n\n## Optionals and Optional Pointers\n\nLet's talk about optionals and how they relate to pointers in Zig.\nBy default, objects in Zig are **non-nullable**. This means that, in Zig,\nyou can safely assume that any object in your source code is not null.\n\nThis is a powerful feature of Zig when you compare it to the developer experience in C.\nBecause in C, any object can be null at any point, and, as consequence, a pointer in C\nmight point to a null value. This is a common source of undefined behaviour in C.\nWhen programmers work with pointers in C, they have to constantly check if\ntheir pointers are pointing to null values or not.\n\nIf for some reason, your Zig code produces a null value somewhere, and, this null\nvalue ends up in an object that is non-nullable, a runtime error is always\nraised by your Zig program. Take the program below as an example.\nThe `zig` compiler can see the `null` value at compile time, and, as result,\nit raises a compile time error. But, if a `null` value is raised during\nruntime, a runtime error is also raised by the Zig program, with a\n\"attempt to use null value\" message.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nnumber = null;\n```\n:::\n\n\n\n```\np5.zig:5:14: error: expected type 'u8',\n        found '@TypeOf(null)'\n    number = null;\n             ^~~~\n```\n\n\nYou don't get this type of safety in C.\nIn C, you don't get warnings or errors about null values being produced in your program.\nIf for some reason, your code produces a null value in C, most of the times, you end up getting a segmentation fault error\nas result, which can mean many things.\nThat is why programmers have to constantly check for null values in C.\n\nPointers in Zig are also, by default, **non-nullable**. This is another amazing\nfeature in Zig. So, you can safely assume that any pointer that you create in\nyour Zig code is pointing to a non-null value.\nTherefore, you don't have this heavy work of checking if the pointers you create\nin Zig are pointing to a null value.\n\n\n### What are optionals?\n\nOk, we know now that all objects are non-nullable by default in Zig.\nBut what if we actually need to use an object that might receive a null value?\nHere is where optionals come in.\n\nAn optional object in Zig is an object that can be null.\nTo mark an object as optional, we use the `?` operator. When you put\nthis `?` operator right before the data type of an object, you transform\nthis data type into an optional data type, and the object becomes an optional object.\n\nTake the snippet below as an example. We are creating a new variable object\ncalled `num`. This object have the data type `?i32`, which means that,\nthis object contains either a signed 32-bit integer (`i32`), or, a null value.\nBoth alternatives are valid values to the `num` object.\nThat is why, I can actually change the value of this object to null, and,\nno errors are raised by the `zig` compiler, as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: ?i32 = 5;\nnum = null;\n```\n:::\n\n\n\n\n### Optional pointers\n\nYou can also mark a pointer object as an optional pointer, meaning that,\nthis object contains either a null value, or, a pointer that points to a value.\nWhen you mark a pointer as optional, the data type of this pointer object\nbecomes `?*const T` or `?*T`, depending if the value pointed by the pointer\nis a constant value or not. The `?` identifies the object as optional, while\nthe `*` identifies it as a pointer object.\n\nIn the example below, we are creating a variable object named `num`, and an\noptional pointer object named `ptr`. Notice that the data type of the object\n`ptr` indicates that it is either a null value, or a pointer to an `i32` value.\nAlso, notice that the pointer object (`ptr`) can be marked as optional, even if\nthe object `num` is not optional.\n\nWhat this code tells us is that, the `num` variable will never contain a null value.\nThis variable will always contain a valid `i32` value. But in contrast, the `ptr` object might contain either a null\nvalue, or, a pointer to an `i32` value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: i32 = 5;\nvar ptr: ?*i32 = &num;\nptr = null;\nnum = 6;\n```\n:::\n\n\n\n\nBut what happens if we turn the table, and mark the `num` object as optional,\ninstead of the pointer object. If we do that, then, the pointer object is\nnot optional anymore. It would be a similar (although different) result. Because then, we would have\na pointer to an optional value. In other words, a pointer to a value that is either a\nnull value, or, a not-null value.\n\nIn the example below, we are recreating this idea. Now, the `ptr` object\nhave a data type of `*?i32`, instead of `?*i32`. Notice that the `*` symbol comes before of `?`\nthis time. So now, we have a pointer that points to a value that is either null\n, or, a signed 32-bit integer.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: ?i32 = 5;\n// ptr have type `*?i32`, instead of `?*i32`.\nconst ptr = &num;\n_ = ptr;\n```\n:::\n\n\n\n\n\n### Null handling in optionals {#sec-null-handling}\n\nWhen you have an optional object in your Zig code, you have to explicitly handle\nthe possibility of this object being null. It is like error-handling with `try` and `catch`.\nIn Zig you also have to handle null values like if they were a type of error.\n\nWe can do that, by using either:\n\n- an if statement, like you would do in C.\n- the `orelse` keyword.\n- unwrap the optional value with the `?` method.\n\nWhen you use an if statement, you use a pair of pipes\nto unwrap the optional value, and use this \"unwrapped object\"\ninside the if block.\nUsing the example below as a reference, if the object `num` is null,\nthen, the code inside the if statement is not executed. Otherwise,\nthe if statement will unwrap the object `num` into the `not_null_num`\nobject. This `not_null_num` object is guaranteed to be not null inside\nthe scope of the if statement.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst num: ?i32 = 5;\nif (num) |not_null_num| {\n    try stdout.print(\"{d}\\n\", .{not_null_num});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n5\n```\n\n\n:::\n:::\n\n\n\n\nNow, the `orelse` keyword behaves like a binary operator. You connect two expressions with this keyword.\nOn the left side of `orelse`, you provide the expression that might result\nin a null value, and on the right side of `orelse`, you provide another expression\nthat will not result in a null value.\n\nThe idea behind the `orelse` keyword is: if the expression on the left side\nresult in a not-null value, then, this not-null value is used. However,\nif this expression on the left side result in a null value, then, the value\nof the expression on the right side is used instead.\n\nLooking at the example below, since the `x` object is currently null, the\n`orelse` decided to use the alternative value, which is the number 15.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x: ?i32 = null;\nconst dbl = (x orelse 15) * 2;\ntry stdout.print(\"{d}\\n\", .{dbl});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n30\n```\n\n\n:::\n:::\n\n\n\n\nYou can use the if statement or the `orelse` keyword, when you want to\nsolve (or deal with) this null value. However, if there is no clear solution\nto this null value, and the most logic and sane path is to simply panic\nand raise a loud error in your program when this null value is encountered,\nyou can use the `?` method of your optional object.\n\nIn essence, when you use this `?` method, the optional object is unwrapped.\nIf a not-null value is found in the optional object, then, this not-null value is used.\nOtherwise, the `unreachable` keyword is used. You can read more about this\n[`unreacheable` keyword at the official documentation](https://ziglang.org/documentation/master/#unreachable)[^un-docs].\nBut in essence, when you build your Zig source code using the build modes `ReleaseSafe` or `Debug`, this\n`unreacheable` keyword causes the program to panic and raise an error during runtime,\nlike in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn return_null(n: i32) ?i32 {\n    if (n == 5) return null;\n    return n;\n}\n\npub fn main() !void {\n    const x: i32 = 5;\n    const y: ?i32 = return_null(x);\n    try stdout.print(\"{d}\\n\", .{y.?});\n}\n```\n:::\n\n\n\n\n```\nthread 12767 panic: attempt to use null value\np7.zig:12:34: 0x103419d in main (p7):\n    try stdout.print(\"{d}\\n\", .{y.?});\n                                 ^\n```\n\n\n[^un-docs]: <https://ziglang.org/documentation/master/#unreachable>.\n\n\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Pointers and Optionals {#sec-pointer}\n\nOn our next project we are going to build a HTTP server from scratch.\nBut in order to do that, we need to learn more about pointers and how they work in Zig.\nPointers in Zig are similar to pointers in C. But they come with some extra advantages in Zig.\n\nA pointer is an object that contains a memory address. This memory address is the address where\na particular value is stored in memory. It can be any value. Most of the times,\nit's a value that comes from another object (or variable) present in our code.\n\nIn the example below, I'm creating two objects (`number` and `pointer`).\nThe `pointer` object contains the memory address where the value of the `number` object\n(the number 5) is stored. So, that is a pointer in a nutshell. It's a memory\naddress that points to a particular existing value in the memory. You could\nalso say, that, the `pointer` object points to the memory address where the `number` object is\nstored.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number: u8 = 5;\nconst pointer = &number;\n_ = pointer;\n```\n:::\n\n\n\n\nWe create a pointer object in Zig by using the `&` operator. When you put this operator\nbefore the name of an existing object, you get the memory address of this object as result.\nWhen you store this memory address inside a new object, this new object becomes a pointer object.\nBecause it stores a memory address.\n\nPeople mostly use pointers as an alternative way to access a particular value.\nFor example, I can use the `pointer` object to access the value stored by\nthe `number` object. This operation of accessing the value that the\npointer \"points to\" is normally called of *dereferencing the pointer*.\nWe can dereference a pointer in Zig by using the `*` method of the pointer object. Like in the example\nbelow, where we take the number 5 pointed by the `pointer` object,\nand double it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number: u8 = 5;\nconst pointer = &number;\nconst doubled = 2 * pointer.*;\nstd.debug.print(\"{d}\\n\", .{doubled});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n10\n```\n\n\n:::\n:::\n\n\n\n\n\nThis syntax to dereference the pointer is nice. Because we can easily chain it with\nmethods of the value pointed by the pointer. We can use the `User` struct that we have\ncreated in @sec-structs-and-oop as an example. If you comeback to that section,\nyou will see that this struct have a method named `print_name()`.\n\nSo, for example, if we have an user object, and a pointer that points to this user object,\nwe can use the pointer to access this user object, and, at the same time, call the method `print_name()`\non it, by chaining the dereference method (`*`) with the `print_name()` method. Like in the\nexample below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst u = User.init(1, \"pedro\", \"email@gmail.com\");\nconst pointer = &u;\ntry pointer.*.print_name();\n```\n:::\n\n\n\n\n```\npedro\n```\n\nWe can also use pointers to effectively alter the value of an object.\nFor example, I could use the `pointer` object to set\nthe value of the object `number` to 6, like in the example below.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n6\n```\n\n\n:::\n:::\n\n\n\n\n\nTherefore, as I mentioned earlier, people use pointers as an alternative way to access a particular value.\nAnd they use it especially when they do not want to \"move\" these values around. There are situations where,\nyou want to access a particular value in a different scope (i.e., a different location) of your code,\nbut you do not want to \"move\" this value to this new scope (or location) that you are in.\n\nThis matters especially if this value is big in size. Because if it is, then,\nmoving this value becomes an expensive operation to do.\nThe computer will have to spend a considerable amount of time\ncopying this value to this new location.\n\nTherefore, many programmers prefer to avoid this heavy operation of copying the value\nto the new location, by accessing this value through pointers.\nWe are going to talk more about this \"moving operation\" over the next sections.\nFor now, just keep in mind that avoiding this \"move operation\" is\none of main reasons why pointers are used in programming languages.\n\n\n\n\n\n## Constant objects vs variable objects {#sec-pointer-var}\n\nYou can have a pointer that points to a constant object, or, a pointer that points to a variable object.\nBut regardless of who this pointer is, a pointer **must always respect the characteristics of the object that it points to**.\nAs a consequence, if the pointer points to a constant object, then, you cannot use this pointer\nto change the value that it points to. Because it points to a value that is constant. As we discussed in @sec-assignments, you cannot\nchange a value that is constant.\n\nFor example, if I have a `number` object, which is constant, I cannot execute\nthe expression below where I'm trying to change the value of `number` to 6 through\nthe `pointer` object. As demonstrated below, when you try to do something\nlike that, you get a compile time error:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number = 5;\nconst pointer = &number;\npointer.* = 6;\n```\n:::\n\n\n\n\n```\np.zig:6:12: error: cannot assign to constant\n    pointer.* = 6;\n```\n\nIf I change the `number` object to be a variable object, by introducing the `var` keyword,\nthen, I can successfully change the value of this object through a pointer, as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n6\n```\n\n\n:::\n:::\n\n\n\n\nYou can see this relationship between \"constant versus variable\" on the data type of\nyour pointer object. In other words, the data type of a pointer object already gives you\nsome clues about whether the value that it points to is constant or not.\n\nWhen a pointer object points to a constant value, then, this pointer have a data type `*const T`,\nwhich means \"a pointer to a constant value of type `T`\".\nIn contrast, if the pointer points to a variable value, then, the type of the pointer is usually `*T`, which is\nsimply \"a pointer to a value of type `T`\".\nHence, whenever you see a pointer object whose data type is in the format `*const T`, then,\nyou know that you cannot use this pointer to change the value that it points to.\nBecause this pointer points to a constant value of type `T`.\n\n\nWe have talked about the value pointed by the pointer being constant or not,\nand the consequences that arises from it. But, what about the pointer object itself? I mean, what happens\nif the pointer object itself is constant or not? Think about it.\nWe can have a constant pointer that points to a constant value.\nBut we can also have a variable pointer that points to a constant value. And vice-versa.\n\nUntil this point, the `pointer` object was always constant,\nbut what does this mean for us? What is the consequence of the\n`pointer` object being constant? The consequence is that\nwe cannot change the pointer object, because it is constant. We can use the\npointer object in multiple ways, but we cannot change the\nmemory address that is inside this pointer object.\n\nHowever, if we mark the `pointer` object as a variable object,\nthen, we can change the memory address pointed by this `pointer` object.\nThe example below demonstrates that. Notice that the object pointed\nby the `pointer` object changes from `c1` to `c2`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c1: u8 = 5;\nconst c2: u8 = 6;\nvar pointer = &c1;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\npointer = &c2;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\n```\n:::\n\n\n\n\n```\n5\n6\n```\n\nThus, by setting the `pointer` object to a `var` or `const` object,\nyou specify if the memory address contained in this pointer object can change or not\nin your program. On the other side, you can change the value pointed by the pointer,\nif, and only if this value is stored in a variable object. If this value\nis in a constant object, then, you cannot change this value through a pointer.\n\n\n## Types of pointer\n\nIn Zig, there are two types of pointers [@zigdocs], which are:\n\n- single-item pointer (`*`);\n- many-item pointer (`[*]`);\n\n\nSingle-item pointer objects are objects whose data types are in the format `*T`.\nSo, for example, if an object have a data type `*u32`, it means that, this\nobject contains a single-item pointer that points to an unsigned 32-bit integer value.\nAs another example, if an object have type `*User`, then, it contains\na single-item pointer to an `User` value.\n\nIn contrast, many-item pointers are objects whose data types are in the format `[*]T`.\nNotice that the star symbol (`*`) is now inside a pair of brackets (`[]`). If the star\nsymbol is inside a pair of brackets, you know that this object is a many-item pointer.\n\nWhen you apply the `&` operator over an object, you will always get a single-item pointer.\nMany-item pointers are more of a \"internal type\" of the language, more closely\nrelated to slices. So, when you deliberately create a pointer with the `&` operator,\nyou always get a single-item pointer as result.\n\n\n\n## Pointer arithmetic\n\nPointer arithmetic is available in Zig, and they work the same way they work in C.\nWhen you have a pointer that points to an array, the pointer usually points to\nthe first element in the array, and you can use pointer arithmetic to\nadvance this pointer and access the other elements in the array.\n\n\nNotice in the example below, that initially, the `ptr` object was pointing\nto the first element in the array `ar`. But then, I started to walk through the array, by advancing\nthe pointer with simple pointer arithmetic.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [_]i32{ 1, 2, 3, 4 };\nvar ptr: [*]const i32 = &ar;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\n```\n:::\n\n\n\n\n```\n1\n2\n3\n```\n\nAlthough you can create a pointer to an array like that, and\nstart to walk through this array by using pointer arithmetic,\nin Zig, we prefer to use slices, which were presented in @sec-arrays.\n\nBehind the hood, slices already are pointers,\nand they also come with the `len` property, which indicates\nhow many elements are in the slice. This is good because the `zig` compiler\ncan use it to check for potential buffer overflows, and other problems like that.\n\nAlso, you don't need to use pointer arithmetic to walk through the elements\nof a slice. You can simply use the `slice[index]` syntax to directly access\nany element you want in the slice.\nAs I mentioned in @sec-arrays, you can get a slice from an array by using\na range selector inside brackets. In the example below, I'm creating\na slice (`sl`) that covers the entire `ar` array. I can access any\nelement of `ar` from this slice, and, the slice itself already is a pointer\nbehind the hood.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [_]i32{1,2,3,4};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\n\n## Optionals and Optional Pointers\n\nLet's talk about optionals and how they relate to pointers in Zig.\nBy default, objects in Zig are **non-nullable**. This means that, in Zig,\nyou can safely assume that any object in your source code is not null.\n\nThis is a powerful feature of Zig when you compare it to the developer experience in C.\nBecause in C, any object can be null at any point, and, as consequence, a pointer in C\nmight point to a null value. This is a common source of undefined behaviour in C.\nWhen programmers work with pointers in C, they have to constantly check if\ntheir pointers are pointing to null values or not.\n\nIf for some reason, your Zig code produces a null value somewhere, and, this null\nvalue ends up in an object that is non-nullable, a runtime error is always\nraised by your Zig program. Take the program below as an example.\nThe `zig` compiler can see the `null` value at compile time, and, as result,\nit raises a compile time error. But, if a `null` value is raised during\nruntime, a runtime error is also raised by the Zig program, with a\n\"attempt to use null value\" message.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nnumber = null;\n```\n:::\n\n\n\n```\np5.zig:5:14: error: expected type 'u8',\n        found '@TypeOf(null)'\n    number = null;\n             ^~~~\n```\n\n\nYou don't get this type of safety in C.\nIn C, you don't get warnings or errors about null values being produced in your program.\nIf for some reason, your code produces a null value in C, most of the times, you end up getting a segmentation fault error\nas result, which can mean many things.\nThat is why programmers have to constantly check for null values in C.\n\nPointers in Zig are also, by default, **non-nullable**. This is another amazing\nfeature in Zig. So, you can safely assume that any pointer that you create in\nyour Zig code is pointing to a non-null value.\nTherefore, you don't have this heavy work of checking if the pointers you create\nin Zig are pointing to a null value.\n\n\n### What are optionals?\n\nOk, we know now that all objects are non-nullable by default in Zig.\nBut what if we actually need to use an object that might receive a null value?\nHere is where optionals come in.\n\nAn optional object in Zig is an object that can be null.\nTo mark an object as optional, we use the `?` operator. When you put\nthis `?` operator right before the data type of an object, you transform\nthis data type into an optional data type, and the object becomes an optional object.\n\nTake the snippet below as an example. We are creating a new variable object\ncalled `num`. This object have the data type `?i32`, which means that,\nthis object contains either a signed 32-bit integer (`i32`), or, a null value.\nBoth alternatives are valid values to the `num` object.\nThat is why, I can actually change the value of this object to null, and,\nno errors are raised by the `zig` compiler, as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: ?i32 = 5;\nnum = null;\n```\n:::\n\n\n\n\n### Optional pointers\n\nYou can also mark a pointer object as an optional pointer, meaning that,\nthis object contains either a null value, or, a pointer that points to a value.\nWhen you mark a pointer as optional, the data type of this pointer object\nbecomes `?*const T` or `?*T`, depending if the value pointed by the pointer\nis a constant value or not. The `?` identifies the object as optional, while\nthe `*` identifies it as a pointer object.\n\nIn the example below, we are creating a variable object named `num`, and an\noptional pointer object named `ptr`. Notice that the data type of the object\n`ptr` indicates that it's either a null value, or a pointer to an `i32` value.\nAlso, notice that the pointer object (`ptr`) can be marked as optional, even if\nthe object `num` is not optional.\n\nWhat this code tells us is that, the `num` variable will never contain a null value.\nThis variable will always contain a valid `i32` value. But in contrast, the `ptr` object might contain either a null\nvalue, or, a pointer to an `i32` value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: i32 = 5;\nvar ptr: ?*i32 = &num;\nptr = null;\nnum = 6;\n```\n:::\n\n\n\n\nBut what happens if we turn the table, and mark the `num` object as optional,\ninstead of the pointer object. If we do that, then, the pointer object is\nnot optional anymore. It would be a similar (although different) result. Because then, we would have\na pointer to an optional value. In other words, a pointer to a value that is either a\nnull value, or, a not-null value.\n\nIn the example below, we are recreating this idea. Now, the `ptr` object\nhave a data type of `*?i32`, instead of `?*i32`. Notice that the `*` symbol comes before of `?`\nthis time. So now, we have a pointer that points to a value that is either null\n, or, a signed 32-bit integer.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: ?i32 = 5;\n// ptr have type `*?i32`, instead of `?*i32`.\nconst ptr = &num;\n_ = ptr;\n```\n:::\n\n\n\n\n\n### Null handling in optionals {#sec-null-handling}\n\nWhen you have an optional object in your Zig code, you have to explicitly handle\nthe possibility of this object being null. It's like error-handling with `try` and `catch`.\nIn Zig you also have to handle null values like if they were a type of error.\n\nWe can do that, by using either:\n\n- an if statement, like you would do in C.\n- the `orelse` keyword.\n- unwrap the optional value with the `?` method.\n\nWhen you use an if statement, you use a pair of pipes\nto unwrap the optional value, and use this \"unwrapped object\"\ninside the if block.\nUsing the example below as a reference, if the object `num` is null,\nthen, the code inside the if statement is not executed. Otherwise,\nthe if statement will unwrap the object `num` into the `not_null_num`\nobject. This `not_null_num` object is guaranteed to be not null inside\nthe scope of the if statement.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst num: ?i32 = 5;\nif (num) |not_null_num| {\n    try stdout.print(\"{d}\\n\", .{not_null_num});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n5\n```\n\n\n:::\n:::\n\n\n\n\nNow, the `orelse` keyword behaves like a binary operator. You connect two expressions with this keyword.\nOn the left side of `orelse`, you provide the expression that might result\nin a null value, and on the right side of `orelse`, you provide another expression\nthat will not result in a null value.\n\nThe idea behind the `orelse` keyword is: if the expression on the left side\nresult in a not-null value, then, this not-null value is used. However,\nif this expression on the left side result in a null value, then, the value\nof the expression on the right side is used instead.\n\nLooking at the example below, since the `x` object is currently null, the\n`orelse` decided to use the alternative value, which is the number 15.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x: ?i32 = null;\nconst dbl = (x orelse 15) * 2;\ntry stdout.print(\"{d}\\n\", .{dbl});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n30\n```\n\n\n:::\n:::\n\n\n\n\nYou can use the if statement or the `orelse` keyword, when you want to\nsolve (or deal with) this null value. However, if there is no clear solution\nto this null value, and the most logic and sane path is to simply panic\nand raise a loud error in your program when this null value is encountered,\nyou can use the `?` method of your optional object.\n\nIn essence, when you use this `?` method, the optional object is unwrapped.\nIf a not-null value is found in the optional object, then, this not-null value is used.\nOtherwise, the `unreachable` keyword is used. You can read more about this\n[`unreacheable` keyword at the official documentation](https://ziglang.org/documentation/master/#unreachable)[^un-docs].\nBut in essence, when you build your Zig source code using the build modes `ReleaseSafe` or `Debug`, this\n`unreacheable` keyword causes the program to panic and raise an error during runtime,\nlike in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn return_null(n: i32) ?i32 {\n    if (n == 5) return null;\n    return n;\n}\n\npub fn main() !void {\n    const x: i32 = 5;\n    const y: ?i32 = return_null(x);\n    try stdout.print(\"{d}\\n\", .{y.?});\n}\n```\n:::\n\n\n\n\n```\nthread 12767 panic: attempt to use null value\np7.zig:12:34: 0x103419d in main (p7):\n    try stdout.print(\"{d}\\n\", .{y.?});\n                                 ^\n```\n\n\n[^un-docs]: <https://ziglang.org/documentation/master/#unreachable>.\n",
+    "supporting": [
+      "05-pointers_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/07-build-system/execute-results/html.json b/_freeze/Chapters/07-build-system/execute-results/html.json
index daf845bf..8d0f268d 100644
--- a/_freeze/Chapters/07-build-system/execute-results/html.json
+++ b/_freeze/Chapters/07-build-system/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "0bac007aec8b6fa9d1efa7b682df4b7b",
+  "hash": "0286d5b6db10173d3df147400fd019aa",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Build System {#sec-build-system}\n\n\nIn this chapter, we are going to talk about the build system, and how an entire project\nis built in Zig.\nOne key advantage of Zig is that it includes a build system embedded in the language itself.\nThis is great, because then you do not have to depend on an external system, separated\nfrom the compiler, to build your code.\n\n\nYou can find a good description of Zig's build system\non the [article entitled \"Build System\"](https://ziglang.org/learn/build-system/#user-provided-options)[^zig-art1]\nfrom the official Zig's website.\nWe also have the excellent [series of posts written by Felix](https://zig.news/xq/zig-build-explained-part-1-59lf)[^felix].\nHence, this chapter represents an extra resource for you to consult and rely on.\n\n[^felix]: <https://zig.news/xq/zig-build-explained-part-1-59lf>\n[^zig-art1]: <https://ziglang.org/learn/build-system/#user-provided-options>\n\nBuilding code is one of the things that Zig is best at. One thing that is particularly\ndifficult in C/C++ and even in Rust, is to cross-compile source code to multiple targets\n(e.g. multiple computer architectures and operating systems),\nand the `zig` compiler is known for being one of the best existing pieces of software\nfor this particular task.\n\n\n\n\n## How source code is built?\n\nWe already have talked about the challenges of building source code in low-level languages\nat @sec-project-files. As we described at that section, programmers invented Build Systems\nto surpass these challenges on the process of building source code in low-level languages.\n\nLow-level languages uses a compiler to compile (or to build) your source code into binary instructions.\nIn C and C++, we normally use compilers like `gcc`, `g++` or `clang` to compile\nour C and C++ source code into these instructions.\nEvery language have its own compiler, and this is no different in Zig.\n\nIn Zig, we have the `zig` compiler to compile our Zig source code into\nbinary instructions that can be executed by our computer.\nIn Zig, the compilation (or the build) process involves\nthe following components:\n\n- The Zig modules that contains your source code;\n- Library files (either a dynamic library or a static library);\n- Compiler flags that tailors the build process to your needs.\n\nThese are the things that you need to connect together in order to build your\nsource code in Zig. In C and C++, you would have an extra component, which are the header files of\nthe libraries that you are using. But header files do not exist in Zig, so, you only need\nto care about them if you are linking your Zig source code with a C library.\nIf that is not your case, you can forget about it.\n\nYour build process is usually organized in a build script. In Zig, we normally\nwrite this build script into a Zig module in the root directory of our project,\nnamed as `build.zig`. You write this build script, then, when you run it, your project\nget's built into binary files that you can use and distribute to your users.\n\nThis build script is normally organized around *target objects*. A target is simply\nsomething to be built, or, in other words, it's something that you want the `zig` compiler\nto build for you. This concept of \"targets\" is present in most Build Systems,\nespecially in CMake[^cmake].\n\n[^cmake]: <https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html>\n\nThere are four types of target objects that you can build in Zig, which are:\n\n- An executable (e.g. a `.exe` file on Windows).\n- A shared library (e.g. a `.so` file in Linux or a `.dll` file on Windows).\n- A static library (e.g. a `.a` file in Linux or a `.lib` file on Windows).\n- An executable file that executes only unit tests (or, a \"unit tests executable\").\n\nWe are going to talk more about these target objects at @sec-targets.\n\n\n\n## The `build()` function {#sec-build-fun}\n\nA build script in Zig always contains a public (and top-level) `build()` function declared.\nIt is like the `main()` function on the main Zig module of your project, that we discussed at @sec-main-file.\nBut instead of creating the entrypoint to your code, this `build()` function is the entrypoint to the build process.\n\nThis `build()` function should accept a pointer to a `Build` object as input, and it should use this \"build object\" to perform\nthe necessary steps to build your project. The return type of this function is always `void`,\nand this `Build` struct comes directly from the Zig Standard Library (`std.Build`). So, you can \naccess this struct by just importing the Zig Standard Library into your `build.zig` module.\n\nJust as a very simple example, here you can see the source code necessary to build\nan executable file from the `hello.zig` Zig module.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"hello.zig\"),\n        .target = b.host,\n    });\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\nYou can define and use other functions and objects in this build script. You can also import\nother Zig modules as you would normally do in any other module of your project.\nThe only real requirement for this build script, is to have a public and top-level\n`build()` function defined, that accepts a pointer to a `Build` struct as input.\n\n\n## Target objects {#sec-targets}\n\nAs we described over the previous sections, a build script is composed around target objects.\nEach target object is normally a binary file (or an output) that you want to get from the build process. You can list\nmultiple target objects in your build script, so that the build process generates multiple\nbinary files for you at once.\n\nFor example, maybe you are a developer working in a cross-platform application,\nand, because this application is cross-platform, you probably need to release\nbinary files of your software for each OS supported by your application to your end users.\nThus, you can define a different target object in your build script\nfor each OS (Windows, Linux, etc.) where you want to publish your software.\nThis will make the `zig` compiler to build your project to multiple target OS's at once.\nThe Zig Build System official documentation have a [great code example that demonstrates this strategy](https://ziglang.org/learn/build-system/#handy-examples)[^zig-ex].\n\n[^zig-ex]: <https://ziglang.org/learn/build-system/#handy-examples>\n\n\nA target object is created by the following methods of the `Build` struct that we introduced\nat @sec-build-fun:\n\n- `addExecutable()` creates an executable file;\n- `addSharedLibrary()` creates a shared library file;\n- `addStaticLibrary()` creates a static library file;\n- `addTest()` creates an executable file that executes unit tests.\n\n\nThese functions are methods from the `Build` struct that you receive\nas input of the `build()` function. All of them, create as output\na `Compile` object, which represents a target object to be compiled\nby the `zig` compiler. All of these functions accept a similar struct literal as input.\nThis struct literal defines three essential specs about this target object that you are building:\n`name`, `target` and `root_source_file`.\n\nWe have already seen these three options being used on the previous example,\nwhere we used the `addExecutable()` method to create an executable target object.\nThis example is reproduced below. Notice the use of the `path()` method\nfrom the `Build` struct, to define a path in the `root_source_file` option.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n```\n:::\n\n\n\n\nThe `name` option specify the name that you want to give to the binary file defined\nby this target object. So, in this example, we are building an executable file named `hello`.\nIs common to set this `name` option to the name of your project.\n\n\nFurthermore, the `target` option specify the target computer architecture (or the target operating system) of this\nbinary file. For example, if you want this target object to run on a Windows machine\nthat uses a `x86_64` architecture, you can set this `target` option to `x86_64-windows-gnu` for example.\nThis will make the `zig` compiler to compile the project to run on a `x86_64` Windows machine.\nYou can see the full list of architectures and OS's that the `zig` compiler supports by running\nthe `zig targets` command in the terminal.\n\nNow, if you are building the project to run on the current machine\nthat you are using to run this build script, you can set this `target`\noption to the `host` method of the `Build` object, like we did in the example above.\nThis `host` method identifies the current machine where you are\ncurrently running the `zig` compiler.\n\n\nAt last, the `root_source_file` option specifies the root Zig module of your project.\nThat is the Zig module that contains the entrypoint to your application (i.e. the `main()` function), or, the main API of your library.\nThis also means that, all the Zig modules that compose your project are automatically discovered\nfrom the import statements you have inside this \"root source file\".\nThe `zig` compiler can detect when a Zig module depends on the other through the import statements,\nand, as a result, it can discover the entire map of Zig modules used in your project.\n\nThis is handy, and it is different from what happens in other build systems.\nIn CMake for example, you have to explicitly list the paths to all source files that you want to\ninclude in your build process. This is probably a symptom of the \"lack of conditional\ncompilation\" in the C and C++ compilers. Since they lack this feature, you have\nto explicitly choose which source files should be sent to the C/C++ compiler, because not\nevery C/C++ code is portable or supported in every operating system, and, therefore,\nwould cause a compilation error in the C/C++ compiler.\n\n\nNow, one important detail about the build process is that, you have to **explicitly\ninstall the target objects that you create in your build script**, by using the\n`installArtifact()` method of the `Build` struct.\n\nEverytime you invoke the build process of your project, by calling the `build` command\nof the `zig` compiler, a new directory named `zig-out` is created in the root\ndirectory of your project. This new directory contains the outputs of the build process,\nthat is, the binary files built from your source code.\n\nWhat the `installArtifact()` method do is to install (or copy) the built target objects\nthat you defined to this `zig-out` directory.\nThis means that, if you do not\ninstall the target objects you define in your build script, these target objects are\nessentially discarded at the end of the build process.\n\nFor example, you might be building a project that uses a third party library that is built\ntogether with the project. So, when you build your project, you would need first, to\nbuild the third party library, and then, you link it with the source code of your project.\nSo, in this case, we have two binary files that are generated in the build process (the executable file of your project, and the third party library).\nBut only one is of interest, which is the executable file of our project.\nWe can discard the binary file of the third party library, by simply not installing it\ninto this `zig-out` directory.\n\nThis `installArtifact()` method is pretty straightforward. Just remember to apply it to every\ntarget object that you want to save into the `zig-out` directory, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n## Setting the build mode\n\nWe have talked about the three essential options that are set when you create a new target object.\nBut there is also a fourth option that you can use to set the build mode of this target object,\nwhich is the `optimize` option.\nThis option is called this way, because the build modes in Zig are treated more of\nan \"optimization vs safety\" problem. So optimization plays an important role here.\nDon't worry, I'm going back to this question very soon.\n\nIn Zig, we have four build modes (which are listed below). Each one of these build modes offer\ndifferent advantages and characteristics. As we described at @sec-compile-debug-mode, the `zig` compiler\nuses the `Debug` build mode by default, when you don't explicitly choose a build mode.\n\n- `Debug`, mode that produces and includes debugging information in the output of the build process (i.e. the binary file defined by the target object);\n- `ReleaseSmall`, mode that tries to produce a binary file that is small in size;\n- `ReleaseFast`, mode that tries to optimize your code, in order to produce a binary file that is as fast as possible;\n- `ReleaseSafe`, mode that tries to make your code as safe as possible, by including safeguards when possible.\n\nSo, when you build your project, you can set the build mode of your target object to `ReleaseFast` for example, which will tell\nthe `zig` compiler to apply important optimizations in your code. This creates a binary file\nthat simply runs faster on most contexts, because it contains a more optimized version of your code.\nHowever, as a result, we often lose some safety features in our code.\nBecause some safety checks are removed from the final binary file,\nwhich makes your code run faster, but in a less safe manner.\n\nThis choice depends on your current priorities. If you are building a cryptography or banking system, you might\nprefer to prioritize safety in your code, so, you would choose the `ReleaseSafe` build mode, which is a little\nslower to run, but much more secure, because it includes all possible runtime safety checks in the binary file\nbuilt in the build process. In the other hand, if you are writing a game for example, you might prefer to prioritize performance\nover safety, by using the `ReleaseFast` build mode, so that your users can experience faster frame rates in your game.\n\nIn the example below, we are creating the same target object that we have used on previous examples.\nBut this time, we are specifying the build mode of this target object to the `ReleaseSafe` mode.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .optimize = .ReleaseSafe\n});\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n## Setting the version of your build\n\nEverytime you build a target object in your build script, you can assign a version\nnumber to this specific build, following a semantic versioning framework.\nYou can find more about semantic versioning by visiting the [Semantic Versioning website](https://semver.org/)[^semver].\nAnyway, in Zig, you can specify the version of your build, by providing a `SemanticVersion` struct to\nthe `version` option, like in the example below:\n\n\n[^semver]: <https://semver.org/>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .version = .{\n        .major = 2, .minor = 9, .patch = 7\n    }\n});\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n## Detecting the OS in your build script {#sec-detect-os}\n\nIs very common in Build Systems to use different options, or, to include different modules, or,\nto link against different libraries depending on the Operational System (OS)\nthat you are targeting in the build process.\n\nIn Zig, you can detect the target OS of the build process, by looking\nat the `os.tag` inside the `builtin` module from the Zig library.\nIn the example below, we are using an if statement to run some\narbitrary code when the target of the build process is a\nWindows system.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nif (builtin.target.os.tag == .windows) {\n    // Code that runs only when the target of\n    // the compilation process is Windows.\n}\n```\n:::\n\n\n\n\n\n## Adding a run step to your build process\n\nOne thing that is neat in Rust is that you can compile and run your\nsource code with one single command (`cargo run`) from the Rust compiler.\nWe saw at @sec-compile-run-code how can we perform a similar job in Zig, by\nbuilding and running our Zig source code through the `run` command from the `zig` compiler.\n\nBut how can we, at the same time, build and run the binary file specified by a target object in our\nbuild script?\nThe answer is by including a \"run artifact\" in our build script.\nA run artifact is created through the `addRunArtifact()` method from the `Build` struct.\nWe simply provide as input to this function the target object that describes the binary file that we\nwant to execute. As a result, this function creates a run artifact that is capable of executing\nthis binary file.\n\nIn the example below, we are defining an executable binary file named `hello`,\nand we use this `addRunArtifact()` method to create a run artifact that will execute\nthis `hello` executable file.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"src/hello.zig\"),\n    .target = b.host\n});\nb.installArtifact(exe);\nconst run_arti = b.addRunArtifact(exe);\n```\n:::\n\n\n\n\nNow that we have created this run artifact, we need to include it in\nthe build process. We do that by declaring a new step in our build\nscript to call this artifact, through the `step()` method of the `Build`\nstruct.\n\nWe can give any name we want to this step, but, for our\ncontext here, I'm going to name this step as \"run\".\nAlso, I give it a brief description to this step (\"Run the project\").\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst run_step = b.step(\n    \"run\", \"Run the project\"\n);\n```\n:::\n\n\n\n\n\nNow that we have declared this \"run step\" we need to tell Zig that\nthis \"run step\" depends on the run artifact.\nIn other words, a run artifact always depends on a \"step\" to effectively be executed.\nBy creating this dependency\nwe finally stablish the necessary commands to build and run the executable file\nfrom the build script.\n\nWe can establish a dependency between the run step and the run artifact\nby using the `dependsOn()` method from the run step. So, we first\ncreate the run step, and then, we link it with the run artifact, by\nusing this `dependsOn()` method from the run step.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nrun_step.dependOn(&run_arti.step);\n```\n:::\n\n\n\n\nThe entire source code of this specific build script that\nwe wrote, piece by piece, in this section, is\navailable in the `build_and_run.zig` module. You can\nsee this module by\n[visiting the official repository of this book](https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig)\n[^module-src].\n\n\n[^module-src]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig>\n\nWhen you declare a new step in your build script, this step\nbecomes available through the `build` command in the `zig` compiler.\nYou can actually see this step by running `zig build --help` in the terminal, like\nin the example below, where we can see that this new \"run\"\nstep that we declared in the build script appeared in the output.\n\n```bash\nzig build --help\n```\n\n```\nSteps:\n  ...\n  run   Run the project\n  ...\n```\n\nNow, everything that we need to is to\ncall this \"run\" step that we created in our build script. We\ncall it by using the name that we gave to this step\nafter the `build` command from the `zig` compiler.\nThis will cause the compiler to build our executable file\nand execute it at the same time.\n\n```bash\nzig build run\n```\n\n## Build unit tests in your project\n\nWe have talked at length about writing unit tests in Zig at @sec-unittests,\nand we also have talked about how to execute these unit tests through\nthe `test` command of the `zig` compiler. However,\nas we did with the `run` command on the previous section, we also might want to\ninclude some commands in our build script to also build and execute the unit tests in our project.\n\nSo, once again, we are going to discuss how a specific built-in command from the `zig` compiler,\n(in this case, the `test` command) can be used in a build script in Zig.\nHere is where a \"test target object\" comes into play.\nAs was described at @sec-targets, we can create a test target object by using the `addTest()` method of\nthe `Build` struct. The first thing that we need to do is to\ndeclare a test target object in our build script.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst test_exe = b.addTest(.{\n    .name = \"unit_tests\",\n    .root_source_file = b.path(\"src/main.zig\"),\n    .target = b.host,\n});\nb.installArtifact(test_exe);\n```\n:::\n\n\n\n\n\nA test target object essentially selects all `test` blocks in all Zig modules\nacross your project, and builds only the source code present inside\nthese `test` blocks in your project. As a result, this target object\ncreates an executable file that contains only the source code present\nin all of these `test` blocks (i.e. the unit tests) in your project.\n\nPerfect! Now that we have declared this test target object, an executable file\nnamed `unit_tests` is built by the `zig` compiler when we trigger the build\nscript with the `build` command. After the build\nprocess is finished, we can simply execute this `unit_tests` executable\nin the terminal.\n\nHowever, if you remember the previous section, we already learned\nhow can we create a run step in our build script, to execute an executable file\nbuilt by the build script.\n\nSo, we could simply add a run step in our build script to run these unit tests\nfrom a single command in the `zig` compiler, to make our lifes easier.\nIn the example below, we demonstrate the commands to\nregister a new build step called \"tests\" in our build script\nto run these unit tests.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst run_arti = b.addRunArtifact(test_exe);\nconst run_step = b.step(\"tests\", \"Run unit tests\");\nrun_step.dependOn(&run_arti.step);\n```\n:::\n\n\n\n\nNow that we registered this new build step, we can trigger it by calling the command below\nin the terminal. You can also checkout the complete source\ncode for this specific build script at the `build_tests.zig` module at the\n[official repository of this book](https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig)\n[^module-src2].\n\n\n[^module-src2]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig>\n\n\n```bash\nzig build tests\n```\n\n\n## Tailoring your build process with user-provided options\n\nSometimes, you want to make a build script that is customizable by the user\nof your project. You can do that by creating user-provided options in\nyour build script. We create an user-provided option by using the\n`option()` method from the `Build` struct.\n\nWith this method, we create a \"build option\" which can be passed\nto the `build.zig` script at the command line. The user have the power of setting\nthis option at the `build` command from the\n`zig` compiler. In other words, each build option that we create\nbecomes a new command line argument that is accessible through the `build` command\nof the compiler.\n\nThese \"user-provided options\" are set by using the prefix `-D` in the command line.\nFor example, if we declare an option named `use_zlib`, that receives a boolean value which\nindicates if we should link our source code to `zlib` or not, we can set the value\nof this option in the command line with `-Duse_zlib`. The code example below\ndemonstrates this idea:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const use_zlib = b.option(\n        bool,\n        \"use_zlib\",\n        \"Should link to zlib?\"\n    ) orelse false;\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"example.zig\"),\n        .target = b.host,\n    });\n    if (use_zlib) {\n        exe.linkSystemLibrary(\"zlib\");\n    }\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\n```bash\nzig build -Duse_zlib=false\n```\n\n\n## Linking to external libraries\n\n\nOne essential part of every build process is the linking stage.\nThis stage is responsible for combining the multiple object files\nthat represent your code, into a single executable file. It also links\nthis executable file to external libraries, if you use any in your code.\n\nIn Zig, we have two notions of a \"library\", which are: 1) a system's library;\n2) a local library. A system's library is just a library that already is installed\nin your system. While a local library is a library that belongs to the current\nproject. Is a library that is present in your project directory, and\nthat you are building together with your project source code.\n\nThe basic difference between the two, is that a system's library is already\nbuilt and installed in your system, supposedly, and all you need to do\nis to link your source code to this library to start using it.\nWe do that by using the `linkSystemLibrary()` method from a\n`Compile` object. This method accepts the name of the library\nin a string as input. Remember from @sec-targets that a `Compile` object\nis a target object that you declare in your build script.\n\nWhen you link a particular target object with a system's library,\nthe `zig` compiler will use `pkg-config` to find where\nare the binary files and also the header files of this library\nin your system.\nWhen it finds these files, the linker present in the `zig` compiler\nwill link your object files with the files of this library to\nproduce a single binary file for you.\n\nIn the example below, we are creating an executable file named `image_filter`,\nand, we are linking this executable file to the C Standard Library with the\nmethod `linkLibC()`, but we also are linking this executable file to the\nC library `libpng` that is currently installed in my system.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"image_filter\",\n        .root_source_file = b.path(\"src/main.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n    exe.linkLibC();\n    exe.linkSystemLibrary(\"png\");\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\nIf you are linking with a C library in your project, is generally a good idea\nto also link your code with the C Standard Library. Because is very likely\nthat this C library uses some functionality of the C Standard Library at some point.\nThe same goes to C++ libraries. So, if you are linking with\nC++ libraries, is a good idea to link your project with the C++\nStandard Library by using the `linkLibCpp()` method.\n\nOn the order side, when you want to link with a local library,\nyou should use the `linkLibrary()` method of a `Compile` object.\nThis method expects to receive another `Compile` object as input.\nThat is, another target object defined in your build script,\nusing either the `addStaticLibrary()` or `addSharedLibrary()` methods\nwhich defines a library to be built.\n\nAs we discussed earlier, a local library is a library\nthat is local to your project, and that is being built together\nwith your project. So, you need to create a target object in your build script\nto build this local library. Then, you link the target objects of interest in your project,\nwith this target object that identifies this local library.\n\nTake a look at this example extracted from the build script of the [`libxev` library](https://github.com/mitchellh/libxev/tree/main)[^libxev2].\nYou can see in this snippet that\nwe are declaring a shared library file, from the `c_api.zig`\nmodule. Then, later in the build script, we declare an\nexecutable file named `\"dynamic-binding-test\"`, which\nlinks to this shared library that we defined earlier\nin the script.\n\n[^libxev2]: <https://github.com/mitchellh/libxev/tree/main>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst optimize = b.standardOptimizeOption(.{});\nconst target = b.standardTargetOptions(.{});\n\nconst dynamic_lib = b.addSharedLibrary(.{\n    .name = dynamic_lib_name,\n    .root_source_file = b.path(\"src/c_api.zig\"),\n    .target = target,\n    .optimize = optimize,\n});\nb.installArtifact(dynamic_lib);\n// ... more lines in the script\nconst dynamic_binding_test = b.addExecutable(.{\n    .name = \"dynamic-binding-test\",\n    .target = target,\n    .optimize = optimize,\n});\ndynamic_binding_test.linkLibrary(dynamic_lib);\n```\n:::\n\n\n\n\n\n\n## Building C code {#sec-building-c-code}\n\nThe `zig` compiler comes with a C compiler embedded in it. In other words,\nyou can use the `zig` compiler to build C projects. This C compiler is available\nthrough the `cc` command of the `zig` compiler.\n\nAs an example, let's use the famous [FreeType library](https://freetype.org/)[^freetype].\nFreeType is one of the most widely used pieces of software in the world.\nIt is a C library designed to produce high-quality fonts. But it is also\nheavily used in the industry to natively render text and fonts\nin the screen of your computer.\n\nIn this section, we are going to write a build script, piece by piece, that is capable\nof building the FreeType project from source.\nYou can find the source code of this build script on the\n[`freetype-zig` repository](https://github.com/pedropark99/freetype-zig/tree/main)[^freetype-zig]\navailable at GitHub.\n\n[^freetype]: <https://freetype.org/>\n[^freetype-zig]: <https://github.com/pedropark99/freetype-zig/tree/main>\n\nAfter you download the source code of FreeType from the official website[^freetype],\nyou can start writing the `build.zig` module. We begin by defining the target object\nthat defines the binary file that we want to compile.\n\nAs an example, I will build the project as a static library file using the `addStaticLibrary()` method\nto create the target object.\nAlso, since FreeType is a C library, I will also link the library\nagainst `libc` through the `linkLibC()` method, to guarantee that any use\nof the C Standard Library is covered in the compilation process.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst target = b.standardTargetOptions(.{});\nconst opti = b.standardOptimizeOption(.{});\nconst lib = b.addStaticLibrary(.{\n    .name = \"freetype\",\n    .optimize = opti,\n    .target = target,\n});\nlib.linkLibC();\n```\n:::\n\n\n\n\n### Creating C compiler flags\n\nCompiler flags are also known as \"compiler options\" by many programmers,\nor also, as \"command options\" in the GCC official documentation.\nIt's fair to also call them as the \"command-line arguments\" of the C compiler.\nIn general, we use compiler flags to turn on (or turn off) some features from the compiler,\nor to tweak the compilation process to fit the needs of our project.\n\nIn build scripts written in Zig, we normally list the C compiler flags to be used in the compilation process\nin a simple array, like in the example below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c_flags = [_][]const u8{\n    \"-Wall\",\n    \"-Wextra\",\n    \"-Werror\",\n};\n```\n:::\n\n\n\n\nIn theory, there is nothing stopping you from using this array to add \"include paths\" (with the `-I` flag)\nor \"library paths\" (with the `-L` flag) to the compilation process. But there are formal ways in Zig to\nadd these types of paths in the compilation process. Both are discussed at @sec-include-paths\nand @sec-library-paths.\n\nAnyway, in Zig, we add C flags to the build process together with the C files that we want to compile, by using the\n`addCSourceFile()` and `addCSourceFiles()` methods. In the example above, we have just declared\nthe C flags that we want to use. But we haven't added them to the build process yet.\nTo do that, we also need to list the C files to be compiled.\n\n### Listing your C files\n\nThe C files that contains \"cross-platform\" source code are listed in the `c_source_files`\nobject below. These are the C files that are included by default in every platform\nsupported by the FreeType library. Now, since the amount of C files in the FreeType library is big,\nI have omitted the rest of the files in the code example below, for brevity purposes.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c_source_files = [_][]const u8{\n    \"src/autofit/autofit.c\",\n    \"src/base/ftbase.c\",\n    // ... and many other C files.\n};\n```\n:::\n\n\n\n\nNow, in addition to \"cross-platform\" source code, we also have some C files in the FreeType project\nthat are platform-specific, meaning that, they contain source code that can only be compiled in specific platforms,\nand, as a result, they are only included in the build process on these specific target platforms.\nThe objects that list these C files are exposed in the code example below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst windows_c_source_files = [_][]const u8{\n    \"builds/windows/ftdebug.c\",\n    \"builds/windows/ftsystem.c\"\n};\nconst linux_c_source_files = [_][]const u8{\n    \"src/base/ftsystem.c\",\n    \"src/base/ftdebug.c\"\n};\n```\n:::\n\n\n\n\nNow that we declared both the files that we want to include and the C compiler flags to be used,\nwe can add them to the target object that describes the FreeType library, by using the\n`addCSourceFile()` and `addCSourceFiles()` methods.\n\nBoth of these functions are methods from a `Compile` object (i.e. a target object).\nThe `addCSourceFile()` method is capable of adding a single C file to the target object,\nwhile the `addCSourceFiles()` method is used to add multiple C files in a single command.\nYou might prefer to use `addCSourceFile()` when you need to use different compiler flags\non specific C files in your project. But, if you can use the same compiler flags\nacross all C files, then, you will probably find `addCSourceFiles()` a better choice.\n\nNotice that we are using the `addCSourceFiles()` method in the example below,\nto add both the C files and the C compiler flags. Also notice that we\nare using the `os.tag` that we learned about at @sec-detect-os, to add the platform-specific\nC files.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nlib.addCSourceFiles(\n    &c_source_files, &c_flags\n);\n\nswitch (builtin.target.os.tag) {\n    .windows => {\n        lib.addCSourceFiles(\n            &windows_c_source_files,\n            &c_flags\n        );\n    },\n    .linux => {\n        lib.addCSourceFiles(\n            &linux_c_source_files,\n            &c_flags\n        );\n    },\n    else => {},\n}\n```\n:::\n\n\n\n\n\n### Defining C Macros\n\nC Macros are an essential part of the C programming language,\nand they are commonly defined through the `-D` flag from a C compiler.\nIn Zig, you can define a C Macro to be used in your build process\nby using the `defineCMacro()` method from the target object that\ndefines the binary file that you are building.\n\nIn the example below, we are using the `lib` object that we have defined\non the previous sections to define some C Macros used by the FreeType project\nin the compilation process. These C Macros specify if FreeType\nshould (or should not) include functionalities from different\nexternal libraries.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nlib.defineCMacro(\"FT_DISABLE_ZLIB\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_PNG\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_HARFBUZZ\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BZIP2\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BROTLI\", \"TRUE\");\nlib.defineCMacro(\"FT2_BUILD_LIBRARY\", \"TRUE\");\n```\n:::\n\n\n\n\n\n### Adding library paths {#sec-library-paths}\n\nLibrary paths are paths in your computer where the C compiler will look (or search) for\nlibrary files to link against your source code. In other words, when you use a library in your\nC source code, and you ask the C compiler to link your source code against this library,\nthe C compiler will search for the binary files of this library across the paths listed\nin this \"library paths\" set.\n\nThese paths are platform specific, and, by default, the C compiler starts by looking at a\npre-defined set of places in your computer. But you can add more paths (or more places)\nto this list. For example, you may have a library installed in a non-conventional place of your\ncomputer, and you can make the C compiler \"see\" this \"non-conventional place\" by adding this path\nto this list of pre-defined paths.\n\nIn Zig, you can add more paths to this set by using the `addLibraryPath()` method from your target object.\nFirst, you defined a `LazyPath` object, containing the path you want to add, then,\nyou provide this object as input to the `addLibraryPath()` method, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst lib_path: std.Build.LazyPath = .{\n    .cwd_relative = \"/usr/local/lib/\"\n};\nlib.addLibraryPath(lib_path);\n```\n:::\n\n\n\n\n\n\n\n### Adding include paths {#sec-include-paths}\n\nThe preprocessor search path is a popular concept from the\nC community, but it is also known by many C programmers as \"include paths\", because\nthe paths in this \"search path\" relate to the `#include` statements found in the C files.\n\nInclude paths are similar to library paths. They are a set of pre-defined places in your computer where\nthe C compiler will look for files during the compilation process. But instead of looking for\nlibrary files, the include paths are places where the compiler looks for header files included\nin your C source code.\nThis is why many C programmers prefer to call these paths as the \"preprocessor search path\".\nBecause header files are processed during the preprocessor stage of the compilation\nprocess.\n\nSo, every header file that you include in your C source code, through a `#include` statements needs to\nbe found somewhere, and the C compiler will search for this header file across the paths listed in this \"include paths\" set.\nInclude paths are added to the compilation process through the `-I` flag.\n\nIn Zig, you can add new paths to this pre-defined set of paths, by using the `addIncludePath()` method\nfrom your target object. This method also accepts a `LazyPath` object as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst inc_path: std.Build.LazyPath = .{\n    .path = \"./include\"\n};\nlib.addIncludePath(inc_path);\n```\n:::\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Build System {#sec-build-system}\n\n\nIn this chapter, we are going to talk about the build system, and how an entire project\nis built in Zig.\nOne key advantage of Zig is that it includes a build system embedded in the language itself.\nThis is great, because then you do not have to depend on an external system, separated\nfrom the compiler, to build your code.\n\n\nYou can find a good description of Zig's build system\nin the [article entitled \"Build System\"](https://ziglang.org/learn/build-system/#user-provided-options)[^zig-art1]\nfrom the official Zig's website.\nWe also have the excellent [series of posts written by Felix](https://zig.news/xq/zig-build-explained-part-1-59lf)[^felix].\nHence, this chapter represents an extra resource for you to consult and rely on.\n\n[^felix]: <https://zig.news/xq/zig-build-explained-part-1-59lf>\n[^zig-art1]: <https://ziglang.org/learn/build-system/#user-provided-options>\n\nBuilding code is one of the things that Zig is best at. One thing that is particularly\ndifficult in C/C++ and even in Rust, is to cross-compile source code to multiple targets\n(e.g. multiple computer architectures and operating systems),\nand the `zig` compiler is known for being one of the best existing pieces of software\nfor this particular task.\n\n\n\n\n## How source code is built?\n\nWe already have talked about the challenges of building source code in low-level languages\nin @sec-project-files. As we described at that section, programmers invented Build Systems\nto surpass these challenges on the process of building source code in low-level languages.\n\nLow-level languages uses a compiler to compile (or to build) your source code into binary instructions.\nIn C and C++, we normally use compilers like `gcc`, `g++` or `clang` to compile\nour C and C++ source code into these instructions.\nEvery language have its own compiler, and this is no different in Zig.\n\nIn Zig, we have the `zig` compiler to compile our Zig source code into\nbinary instructions that can be executed by our computer.\nIn Zig, the compilation (or the build) process involves\nthe following components:\n\n- The Zig modules that contains your source code;\n- Library files (either a dynamic library or a static library);\n- Compiler flags that tailors the build process to your needs.\n\nThese are the things that you need to connect together in order to build your\nsource code in Zig. In C and C++, you would have an extra component, which are the header files of\nthe libraries that you are using. But header files do not exist in Zig, so, you only need\nto care about them if you are linking your Zig source code with a C library.\nIf that is not your case, you can forget about it.\n\nYour build process is usually organized in a build script. In Zig, we normally\nwrite this build script into a Zig module in the root directory of our project,\nnamed as `build.zig`. You write this build script, then, when you run it, your project\ngets built into binary files that you can use and distribute to your users.\n\nThis build script is normally organized around *target objects*. A target is simply\nsomething to be built, or, in other words, it's something that you want the `zig` compiler\nto build for you. This concept of \"targets\" is present in most Build Systems,\nespecially in CMake[^cmake].\n\n[^cmake]: <https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html>\n\nThere are four types of target objects that you can build in Zig, which are:\n\n- An executable (e.g. a `.exe` file on Windows).\n- A shared library (e.g. a `.so` file in Linux or a `.dll` file on Windows).\n- A static library (e.g. a `.a` file in Linux or a `.lib` file on Windows).\n- An executable file that executes only unit tests (or, a \"unit tests executable\").\n\nWe are going to talk more about these target objects in @sec-targets.\n\n\n\n## The `build()` function {#sec-build-fun}\n\nA build script in Zig always contains a public (and top-level) `build()` function declared.\nIt's like the `main()` function in the main Zig module of your project, that we discussed in @sec-main-file.\nBut instead of creating the entrypoint to your code, this `build()` function is the entrypoint to the build process.\n\nThis `build()` function should accept a pointer to a `Build` object as input, and it should use this \"build object\" to perform\nthe necessary steps to build your project. The return type of this function is always `void`,\nand this `Build` struct comes directly from the Zig Standard Library (`std.Build`). So, you can\naccess this struct by just importing the Zig Standard Library into your `build.zig` module.\n\nJust as a very simple example, here you can see the source code necessary to build\nan executable file from the `hello.zig` Zig module.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"hello.zig\"),\n        .target = b.host,\n    });\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\nYou can define and use other functions and objects in this build script. You can also import\nother Zig modules as you would normally do in any other module of your project.\nThe only real requirement for this build script, is to have a public and top-level\n`build()` function defined, that accepts a pointer to a `Build` struct as input.\n\n\n## Target objects {#sec-targets}\n\nAs we described over the previous sections, a build script is composed around target objects.\nEach target object is normally a binary file (or an output) that you want to get from the build process. You can list\nmultiple target objects in your build script, so that the build process generates multiple\nbinary files for you at once.\n\nFor example, maybe you are a developer working in a cross-platform application,\nand, because this application is cross-platform, you probably need to release\nbinary files of your software for each OS supported by your application to your end users.\nThus, you can define a different target object in your build script\nfor each OS (Windows, Linux, etc.) where you want to publish your software.\nThis will make the `zig` compiler to build your project to multiple target OS's at once.\nThe Zig Build System official documentation have a [great code example that demonstrates this strategy](https://ziglang.org/learn/build-system/#handy-examples)[^zig-ex].\n\n[^zig-ex]: <https://ziglang.org/learn/build-system/#handy-examples>\n\n\nA target object is created by the following methods of the `Build` struct that we introduced\nin @sec-build-fun:\n\n- `addExecutable()` creates an executable file;\n- `addSharedLibrary()` creates a shared library file;\n- `addStaticLibrary()` creates a static library file;\n- `addTest()` creates an executable file that executes unit tests.\n\n\nThese functions are methods from the `Build` struct that you receive\nas input of the `build()` function. All of them, create as output\na `Compile` object, which represents a target object to be compiled\nby the `zig` compiler. All of these functions accept a similar struct literal as input.\nThis struct literal defines three essential specs about this target object that you are building:\n`name`, `target` and `root_source_file`.\n\nWe have already seen these three options being used on the previous example,\nwhere we used the `addExecutable()` method to create an executable target object.\nThis example is reproduced below. Notice the use of the `path()` method\nfrom the `Build` struct, to define a path in the `root_source_file` option.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n```\n:::\n\n\n\n\nThe `name` option specify the name that you want to give to the binary file defined\nby this target object. So, in this example, we are building an executable file named `hello`.\nIt's common to set this `name` option to the name of your project.\n\n\nFurthermore, the `target` option specify the target computer architecture (or the target operating system) of this\nbinary file. For example, if you want this target object to run on a Windows machine\nthat uses a `x86_64` architecture, you can set this `target` option to `x86_64-windows-gnu` for example.\nThis will make the `zig` compiler to compile the project to run on a `x86_64` Windows machine.\nYou can see the full list of architectures and OS's that the `zig` compiler supports by running\nthe `zig targets` command in the terminal.\n\nNow, if you are building the project to run on the current machine\nthat you are using to run this build script, you can set this `target`\noption to the `host` method of the `Build` object, like we did in the example above.\nThis `host` method identifies the current machine where you are\ncurrently running the `zig` compiler.\n\n\nAt last, the `root_source_file` option specifies the root Zig module of your project.\nThat is the Zig module that contains the entrypoint to your application (i.e., the `main()` function), or, the main API of your library.\nThis also means that, all the Zig modules that compose your project are automatically discovered\nfrom the import statements you have inside this \"root source file\".\nThe `zig` compiler can detect when a Zig module depends on the other through the import statements,\nand, as a result, it can discover the entire map of Zig modules used in your project.\n\nThis is handy, and it's different from what happens in other build systems.\nIn CMake for example, you have to explicitly list the paths to all source files that you want to\ninclude in your build process. This is probably a symptom of the \"lack of conditional\ncompilation\" in the C and C++ compilers. Since they lack this feature, you have\nto explicitly choose which source files should be sent to the C/C++ compiler, because not\nevery C/C++ code is portable or supported in every operating system, and, therefore,\nwould cause a compilation error in the C/C++ compiler.\n\n\nNow, one important detail about the build process is that, you have to **explicitly\ninstall the target objects that you create in your build script**, by using the\n`installArtifact()` method of the `Build` struct.\n\nEverytime you invoke the build process of your project, by calling the `build` command\nof the `zig` compiler, a new directory named `zig-out` is created in the root\ndirectory of your project. This new directory contains the outputs of the build process,\nthat is, the binary files built from your source code.\n\nWhat the `installArtifact()` method do is to install (or copy) the built target objects\nthat you defined to this `zig-out` directory.\nThis means that, if you do not\ninstall the target objects you define in your build script, these target objects are\nessentially discarded at the end of the build process.\n\nFor example, you might be building a project that uses a third party library that is built\ntogether with the project. So, when you build your project, you would need first, to\nbuild the third party library, and then, you link it with the source code of your project.\nSo, in this case, we have two binary files that are generated in the build process (the executable file of your project, and the third party library).\nBut only one is of interest, which is the executable file of our project.\nWe can discard the binary file of the third party library, by simply not installing it\ninto this `zig-out` directory.\n\nThis `installArtifact()` method is pretty straightforward. Just remember to apply it to every\ntarget object that you want to save into the `zig-out` directory, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n## Setting the build mode\n\nWe have talked about the three essential options that are set when you create a new target object.\nBut there is also a fourth option that you can use to set the build mode of this target object,\nwhich is the `optimize` option.\nThis option is called this way, because the build modes in Zig are treated more of\nan \"optimization vs safety\" problem. So optimization plays an important role here.\nDon't worry, I'm going back to this question very soon.\n\nIn Zig, we have four build modes (which are listed below). Each one of these build modes offer\ndifferent advantages and characteristics. As we described in @sec-compile-debug-mode, the `zig` compiler\nuses the `Debug` build mode by default, when you don't explicitly choose a build mode.\n\n- `Debug`, mode that produces and includes debugging information in the output of the build process (i.e., the binary file defined by the target object);\n- `ReleaseSmall`, mode that tries to produce a binary file that is small in size;\n- `ReleaseFast`, mode that tries to optimize your code, in order to produce a binary file that is as fast as possible;\n- `ReleaseSafe`, mode that tries to make your code as safe as possible, by including safeguards when possible.\n\nSo, when you build your project, you can set the build mode of your target object to `ReleaseFast` for example, which will tell\nthe `zig` compiler to apply important optimizations in your code. This creates a binary file\nthat simply runs faster on most contexts, because it contains a more optimized version of your code.\nHowever, as a result, we often lose some safety features in our code.\nBecause some safety checks are removed from the final binary file,\nwhich makes your code run faster, but in a less safe manner.\n\nThis choice depends on your current priorities. If you are building a cryptography or banking system, you might\nprefer to prioritize safety in your code, so, you would choose the `ReleaseSafe` build mode, which is a little\nslower to run, but much more secure, because it includes all possible runtime safety checks in the binary file\nbuilt in the build process. In the other hand, if you are writing a game for example, you might prefer to prioritize performance\nover safety, by using the `ReleaseFast` build mode, so that your users can experience faster frame rates in your game.\n\nIn the example below, we are creating the same target object that we have used on previous examples.\nBut this time, we are specifying the build mode of this target object to the `ReleaseSafe` mode.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .optimize = .ReleaseSafe\n});\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n## Setting the version of your build\n\nEverytime you build a target object in your build script, you can assign a version\nnumber to this specific build, following a semantic versioning framework.\nYou can find more about semantic versioning by visiting the [Semantic Versioning website](https://semver.org/)[^semver].\nAnyway, in Zig, you can specify the version of your build, by providing a `SemanticVersion` struct to\nthe `version` option, like in the example below:\n\n\n[^semver]: <https://semver.org/>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .version = .{\n        .major = 2, .minor = 9, .patch = 7\n    }\n});\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n## Detecting the OS in your build script {#sec-detect-os}\n\nIt's very common in Build Systems to use different options, or, to include different modules, or,\nto link against different libraries depending on the Operational System (OS)\nthat you are targeting in the build process.\n\nIn Zig, you can detect the target OS of the build process, by looking\nat the `os.tag` inside the `builtin` module from the Zig library.\nIn the example below, we are using an if statement to run some\narbitrary code when the target of the build process is a\nWindows system.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nif (builtin.target.os.tag == .windows) {\n    // Code that runs only when the target of\n    // the compilation process is Windows.\n}\n```\n:::\n\n\n\n\n\n## Adding a run step to your build process\n\nOne thing that is neat in Rust is that you can compile and run your\nsource code with one single command (`cargo run`) from the Rust compiler.\nWe saw in @sec-compile-run-code how can we perform a similar job in Zig, by\nbuilding and running our Zig source code through the `run` command from the `zig` compiler.\n\nBut how can we, at the same time, build and run the binary file specified by a target object in our\nbuild script?\nThe answer is by including a \"run artifact\" in our build script.\nA run artifact is created through the `addRunArtifact()` method from the `Build` struct.\nWe simply provide as input to this function the target object that describes the binary file that we\nwant to execute. As a result, this function creates a run artifact that is capable of executing\nthis binary file.\n\nIn the example below, we are defining an executable binary file named `hello`,\nand we use this `addRunArtifact()` method to create a run artifact that will execute\nthis `hello` executable file.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"src/hello.zig\"),\n    .target = b.host\n});\nb.installArtifact(exe);\nconst run_arti = b.addRunArtifact(exe);\n```\n:::\n\n\n\n\nNow that we have created this run artifact, we need to include it in\nthe build process. We do that by declaring a new step in our build\nscript to call this artifact, through the `step()` method of the `Build`\nstruct.\n\nWe can give any name we want to this step, but, for our\ncontext here, I'm going to name this step as \"run\".\nAlso, I give it a brief description to this step (\"Run the project\").\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst run_step = b.step(\n    \"run\", \"Run the project\"\n);\n```\n:::\n\n\n\n\n\nNow that we have declared this \"run step\" we need to tell Zig that\nthis \"run step\" depends on the run artifact.\nIn other words, a run artifact always depends on a \"step\" to effectively be executed.\nBy creating this dependency\nwe finally stablish the necessary commands to build and run the executable file\nfrom the build script.\n\nWe can establish a dependency between the run step and the run artifact\nby using the `dependsOn()` method from the run step. So, we first\ncreate the run step, and then, we link it with the run artifact, by\nusing this `dependsOn()` method from the run step.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nrun_step.dependOn(&run_arti.step);\n```\n:::\n\n\n\n\nThe entire source code of this specific build script that\nwe wrote, piece by piece, in this section, is\navailable in the `build_and_run.zig` module. You can\nsee this module by\n[visiting the official repository of this book](https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig)\n[^module-src].\n\n\n[^module-src]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig>\n\nWhen you declare a new step in your build script, this step\nbecomes available through the `build` command in the `zig` compiler.\nYou can actually see this step by running `zig build --help` in the terminal, like\nin the example below, where we can see that this new \"run\"\nstep that we declared in the build script appeared in the output.\n\n```bash\nzig build --help\n```\n\n```\nSteps:\n  ...\n  run   Run the project\n  ...\n```\n\nNow, everything that we need to is to\ncall this \"run\" step that we created in our build script. We\ncall it by using the name that we gave to this step\nafter the `build` command from the `zig` compiler.\nThis will cause the compiler to build our executable file\nand execute it at the same time.\n\n```bash\nzig build run\n```\n\n## Build unit tests in your project\n\nWe have talked at length about writing unit tests in Zig in @sec-unittests,\nand we also have talked about how to execute these unit tests through\nthe `test` command of the `zig` compiler. However,\nas we did with the `run` command on the previous section, we also might want to\ninclude some commands in our build script to also build and execute the unit tests in our project.\n\nSo, once again, we are going to discuss how a specific built-in command from the `zig` compiler,\n(in this case, the `test` command) can be used in a build script in Zig.\nHere is where a \"test target object\" comes into play.\nAs was described in @sec-targets, we can create a test target object by using the `addTest()` method of\nthe `Build` struct. The first thing that we need to do is to\ndeclare a test target object in our build script.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst test_exe = b.addTest(.{\n    .name = \"unit_tests\",\n    .root_source_file = b.path(\"src/main.zig\"),\n    .target = b.host,\n});\nb.installArtifact(test_exe);\n```\n:::\n\n\n\n\n\nA test target object essentially selects all `test` blocks in all Zig modules\nacross your project, and builds only the source code present inside\nthese `test` blocks in your project. As a result, this target object\ncreates an executable file that contains only the source code present\nin all of these `test` blocks (i.e., the unit tests) in your project.\n\nPerfect! Now that we have declared this test target object, an executable file\nnamed `unit_tests` is built by the `zig` compiler when we trigger the build\nscript with the `build` command. After the build\nprocess is finished, we can simply execute this `unit_tests` executable\nin the terminal.\n\nHowever, if you remember the previous section, we already learned\nhow can we create a run step in our build script, to execute an executable file\nbuilt by the build script.\n\nSo, we could simply add a run step in our build script to run these unit tests\nfrom a single command in the `zig` compiler, to make our lifes easier.\nIn the example below, we demonstrate the commands to\nregister a new build step called \"tests\" in our build script\nto run these unit tests.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst run_arti = b.addRunArtifact(test_exe);\nconst run_step = b.step(\"tests\", \"Run unit tests\");\nrun_step.dependOn(&run_arti.step);\n```\n:::\n\n\n\n\nNow that we registered this new build step, we can trigger it by calling the command below\nin the terminal. You can also checkout the complete source\ncode for this specific build script at the `build_tests.zig` module at the\n[official repository of this book](https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig)\n[^module-src2].\n\n\n[^module-src2]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig>\n\n\n```bash\nzig build tests\n```\n\n\n## Tailoring your build process with user-provided options\n\nSometimes, you want to make a build script that is customizable by the user\nof your project. You can do that by creating user-provided options in\nyour build script. We create an user-provided option by using the\n`option()` method from the `Build` struct.\n\nWith this method, we create a \"build option\" which can be passed\nto the `build.zig` script at the command line. The user have the power of setting\nthis option at the `build` command from the\n`zig` compiler. In other words, each build option that we create\nbecomes a new command line argument that is accessible through the `build` command\nof the compiler.\n\nThese \"user-provided options\" are set by using the prefix `-D` in the command line.\nFor example, if we declare an option named `use_zlib`, that receives a boolean value which\nindicates if we should link our source code to `zlib` or not, we can set the value\nof this option in the command line with `-Duse_zlib`. The code example below\ndemonstrates this idea:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const use_zlib = b.option(\n        bool,\n        \"use_zlib\",\n        \"Should link to zlib?\"\n    ) orelse false;\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"example.zig\"),\n        .target = b.host,\n    });\n    if (use_zlib) {\n        exe.linkSystemLibrary(\"zlib\");\n    }\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\n```bash\nzig build -Duse_zlib=false\n```\n\n\n## Linking to external libraries\n\n\nOne essential part of every build process is the linking stage.\nThis stage is responsible for combining the multiple object files\nthat represent your code, into a single executable file. It also links\nthis executable file to external libraries, if you use any in your code.\n\nIn Zig, we have two notions of a \"library\", which are: 1) a system's library;\n2) a local library. A system's library is just a library that is already installed\nin your system. While a local library is a library that belongs to the current\nproject; a library that is present in your project directory, and\nthat you are building together with your project source code.\n\nThe basic difference between the two, is that a system's library is already\nbuilt and installed in your system, supposedly, and all you need to do\nis to link your source code to this library to start using it.\nWe do that by using the `linkSystemLibrary()` method from a\n`Compile` object. This method accepts the name of the library\nin a string as input. Remember from @sec-targets that a `Compile` object\nis a target object that you declare in your build script.\n\nWhen you link a particular target object with a system's library,\nthe `zig` compiler will use `pkg-config` to find where\nare the binary files and also the header files of this library\nin your system.\nWhen it finds these files, the linker present in the `zig` compiler\nwill link your object files with the files of this library to\nproduce a single binary file for you.\n\nIn the example below, we are creating an executable file named `image_filter`,\nand, we are linking this executable file to the C Standard Library with the\nmethod `linkLibC()`, but we also are linking this executable file to the\nC library `libpng` that is currently installed in my system.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"image_filter\",\n        .root_source_file = b.path(\"src/main.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n    exe.linkLibC();\n    exe.linkSystemLibrary(\"png\");\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\nIf you are linking with a C library in your project, is generally a good idea\nto also link your code with the C Standard Library. Because is very likely\nthat this C library uses some functionality of the C Standard Library at some point.\nThe same goes to C++ libraries. So, if you are linking with\nC++ libraries, is a good idea to link your project with the C++\nStandard Library by using the `linkLibCpp()` method.\n\nOn the order side, when you want to link with a local library,\nyou should use the `linkLibrary()` method of a `Compile` object.\nThis method expects to receive another `Compile` object as input.\nThat is, another target object defined in your build script,\nusing either the `addStaticLibrary()` or `addSharedLibrary()` methods\nwhich defines a library to be built.\n\nAs we discussed earlier, a local library is a library\nthat is local to your project, and that is being built together\nwith your project. So, you need to create a target object in your build script\nto build this local library. Then, you link the target objects of interest in your project,\nwith this target object that identifies this local library.\n\nTake a look at this example extracted from the build script of the [`libxev` library](https://github.com/mitchellh/libxev/tree/main)[^libxev2].\nYou can see in this snippet that\nwe are declaring a shared library file, from the `c_api.zig`\nmodule. Then, later in the build script, we declare an\nexecutable file named `\"dynamic-binding-test\"`, which\nlinks to this shared library that we defined earlier\nin the script.\n\n[^libxev2]: <https://github.com/mitchellh/libxev/tree/main>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst optimize = b.standardOptimizeOption(.{});\nconst target = b.standardTargetOptions(.{});\n\nconst dynamic_lib = b.addSharedLibrary(.{\n    .name = dynamic_lib_name,\n    .root_source_file = b.path(\"src/c_api.zig\"),\n    .target = target,\n    .optimize = optimize,\n});\nb.installArtifact(dynamic_lib);\n// ... more lines in the script\nconst dynamic_binding_test = b.addExecutable(.{\n    .name = \"dynamic-binding-test\",\n    .target = target,\n    .optimize = optimize,\n});\ndynamic_binding_test.linkLibrary(dynamic_lib);\n```\n:::\n\n\n\n\n\n\n## Building C code {#sec-building-c-code}\n\nThe `zig` compiler comes with a C compiler embedded in it. In other words,\nyou can use the `zig` compiler to build C projects. This C compiler is available\nthrough the `cc` command of the `zig` compiler.\n\nAs an example, let's use the famous [FreeType library](https://freetype.org/)[^freetype].\nFreeType is one of the most widely used pieces of software in the world.\nIt's a C library designed to produce high-quality fonts. But it's also\nheavily used in the industry to natively render text and fonts\nin the screen of your computer.\n\nIn this section, we are going to write a build script, piece by piece, that is capable\nof building the FreeType project from source.\nYou can find the source code of this build script on the\n[`freetype-zig` repository](https://github.com/pedropark99/freetype-zig/tree/main)[^freetype-zig]\navailable at GitHub.\n\n[^freetype]: <https://freetype.org/>\n[^freetype-zig]: <https://github.com/pedropark99/freetype-zig/tree/main>\n\nAfter you download the source code of FreeType from the official website[^freetype],\nyou can start writing the `build.zig` module. We begin by defining the target object\nthat defines the binary file that we want to compile.\n\nAs an example, I will build the project as a static library file using the `addStaticLibrary()` method\nto create the target object.\nAlso, since FreeType is a C library, I will also link the library\nagainst `libc` through the `linkLibC()` method, to guarantee that any use\nof the C Standard Library is covered in the compilation process.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst target = b.standardTargetOptions(.{});\nconst opti = b.standardOptimizeOption(.{});\nconst lib = b.addStaticLibrary(.{\n    .name = \"freetype\",\n    .optimize = opti,\n    .target = target,\n});\nlib.linkLibC();\n```\n:::\n\n\n\n\n### Creating C compiler flags\n\nCompiler flags are also known as \"compiler options\" by many programmers,\nor also, as \"command options\" in the GCC official documentation.\nIt's fair to also call them as the \"command-line arguments\" of the C compiler.\nIn general, we use compiler flags to turn on (or turn off) some features from the compiler,\nor to tweak the compilation process to fit the needs of our project.\n\nIn build scripts written in Zig, we normally list the C compiler flags to be used in the compilation process\nin a simple array, like in the example below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c_flags = [_][]const u8{\n    \"-Wall\",\n    \"-Wextra\",\n    \"-Werror\",\n};\n```\n:::\n\n\n\n\nIn theory, there is nothing stopping you from using this array to add \"include paths\" (with the `-I` flag)\nor \"library paths\" (with the `-L` flag) to the compilation process. But there are formal ways in Zig to\nadd these types of paths in the compilation process. Both are discussed in @sec-include-paths\nand @sec-library-paths.\n\nAnyway, in Zig, we add C flags to the build process together with the C files that we want to compile, by using the\n`addCSourceFile()` and `addCSourceFiles()` methods. In the example above, we have just declared\nthe C flags that we want to use. But we haven't added them to the build process yet.\nTo do that, we also need to list the C files to be compiled.\n\n### Listing your C files\n\nThe C files that contains \"cross-platform\" source code are listed in the `c_source_files`\nobject below. These are the C files that are included by default in every platform\nsupported by the FreeType library. Now, since the amount of C files in the FreeType library is big,\nI have omitted the rest of the files in the code example below, for brevity purposes.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c_source_files = [_][]const u8{\n    \"src/autofit/autofit.c\",\n    \"src/base/ftbase.c\",\n    // ... and many other C files.\n};\n```\n:::\n\n\n\n\nNow, in addition to \"cross-platform\" source code, we also have some C files in the FreeType project\nthat are platform-specific, meaning that, they contain source code that can only be compiled in specific platforms,\nand, as a result, they are only included in the build process on these specific target platforms.\nThe objects that list these C files are exposed in the code example below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst windows_c_source_files = [_][]const u8{\n    \"builds/windows/ftdebug.c\",\n    \"builds/windows/ftsystem.c\"\n};\nconst linux_c_source_files = [_][]const u8{\n    \"src/base/ftsystem.c\",\n    \"src/base/ftdebug.c\"\n};\n```\n:::\n\n\n\n\nNow that we declared both the files that we want to include and the C compiler flags to be used,\nwe can add them to the target object that describes the FreeType library, by using the\n`addCSourceFile()` and `addCSourceFiles()` methods.\n\nBoth of these functions are methods from a `Compile` object (i.e., a target object).\nThe `addCSourceFile()` method is capable of adding a single C file to the target object,\nwhile the `addCSourceFiles()` method is used to add multiple C files in a single command.\nYou might prefer to use `addCSourceFile()` when you need to use different compiler flags\non specific C files in your project. But, if you can use the same compiler flags\nacross all C files, then, you will probably find `addCSourceFiles()` a better choice.\n\nNotice that we are using the `addCSourceFiles()` method in the example below,\nto add both the C files and the C compiler flags. Also notice that we\nare using the `os.tag` that we learned about in @sec-detect-os, to add the platform-specific\nC files.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nlib.addCSourceFiles(\n    &c_source_files, &c_flags\n);\n\nswitch (builtin.target.os.tag) {\n    .windows => {\n        lib.addCSourceFiles(\n            &windows_c_source_files,\n            &c_flags\n        );\n    },\n    .linux => {\n        lib.addCSourceFiles(\n            &linux_c_source_files,\n            &c_flags\n        );\n    },\n    else => {},\n}\n```\n:::\n\n\n\n\n\n### Defining C Macros\n\nC Macros are an essential part of the C programming language,\nand they are commonly defined through the `-D` flag from a C compiler.\nIn Zig, you can define a C Macro to be used in your build process\nby using the `defineCMacro()` method from the target object that\ndefines the binary file that you are building.\n\nIn the example below, we are using the `lib` object that we have defined\nin the previous sections to define some C Macros used by the FreeType project\nin the compilation process. These C Macros specify if FreeType\nshould (or should not) include functionalities from different\nexternal libraries.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nlib.defineCMacro(\"FT_DISABLE_ZLIB\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_PNG\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_HARFBUZZ\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BZIP2\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BROTLI\", \"TRUE\");\nlib.defineCMacro(\"FT2_BUILD_LIBRARY\", \"TRUE\");\n```\n:::\n\n\n\n\n\n### Adding library paths {#sec-library-paths}\n\nLibrary paths are paths in your computer where the C compiler will look (or search) for\nlibrary files to link against your source code. In other words, when you use a library in your\nC source code, and you ask the C compiler to link your source code against this library,\nthe C compiler will search for the binary files of this library across the paths listed\nin this \"library paths\" set.\n\nThese paths are platform specific, and, by default, the C compiler starts by looking at a\npre-defined set of places in your computer. But you can add more paths (or more places)\nto this list. For example, you may have a library installed in a non-conventional place of your\ncomputer, and you can make the C compiler \"see\" this \"non-conventional place\" by adding this path\nto this list of pre-defined paths.\n\nIn Zig, you can add more paths to this set by using the `addLibraryPath()` method from your target object.\nFirst, you defined a `LazyPath` object, containing the path you want to add, then,\nyou provide this object as input to the `addLibraryPath()` method, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst lib_path: std.Build.LazyPath = .{\n    .cwd_relative = \"/usr/local/lib/\"\n};\nlib.addLibraryPath(lib_path);\n```\n:::\n\n\n\n\n\n\n\n### Adding include paths {#sec-include-paths}\n\nThe preprocessor search path is a popular concept from the\nC community, but it's also known by many C programmers as \"include paths\", because\nthe paths in this \"search path\" relate to the `#include` statements found in the C files.\n\nInclude paths are similar to library paths. They are a set of pre-defined places in your computer where\nthe C compiler will look for files during the compilation process. But instead of looking for\nlibrary files, the include paths are places where the compiler looks for header files included\nin your C source code.\nThis is why many C programmers prefer to call these paths as the \"preprocessor search path\".\nBecause header files are processed during the preprocessor stage of the compilation\nprocess.\n\nSo, every header file that you include in your C source code, through a `#include` statements needs to\nbe found somewhere, and the C compiler will search for this header file across the paths listed in this \"include paths\" set.\nInclude paths are added to the compilation process through the `-I` flag.\n\nIn Zig, you can add new paths to this pre-defined set of paths, by using the `addIncludePath()` method\nfrom your target object. This method also accepts a `LazyPath` object as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst inc_path: std.Build.LazyPath = .{\n    .path = \"./include\"\n};\nlib.addIncludePath(inc_path);\n```\n:::\n",
+    "supporting": [
+      "07-build-system_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/09-data-structures/execute-results/html.json b/_freeze/Chapters/09-data-structures/execute-results/html.json
index 7f635a42..3bbf890a 100644
--- a/_freeze/Chapters/09-data-structures/execute-results/html.json
+++ b/_freeze/Chapters/09-data-structures/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "cabd5fbe8584b5427f83c698f124df64",
+  "hash": "ec46a394836e999ef1cdcb2a2a2407a2",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Data Structures\n\nIn this chapter, I want to present the most common Data Structures that are available from\nthe Zig Standard Library, especially `ArrayList` and also `HashMap`. These are generic Data Structures\nthat you can use to store and control any type of data that is produced by your application.\n\n## Dynamic Arrays {#sec-dynamic-array}\n\nIn high level languages, arrays are usually dynamic. They can easily grow\nin size when they have to, and you don't need to worry about it.\nIn contrast, arrays in low level languages are usually static by default.\nThis is the reality of C, C++, Rust and also Zig. Static arrays were presented at\n@sec-arrays, but in this section, we are going to talk about dynamic arrays in Zig.\n\nDynamic arrays are simply arrays that can grow in size during the runtime\nof your program. Most low level languages have some implementation of\na dynamic array in their standard library. C++ have `std::vector`, Rust have `Vec`,\nand Zig have `std.ArrayList`.\n\nThe `std.ArrayList` struct provides a contiguous and growable array for you.\nIt works like any other dynamic array, it allocates a contiguous block of memory, and when this block have no space left,\n`ArrayList` allocates another contiguous and bigger block of memory, copies the\nelements to this new location, and erases (or frees) the previous block of memory.\n\n\n### Capacity vs Length\n\nWhen we talk about dynamic arrays, we usually have two similar concepts that\nare very essential to how a dynamic array works behind the hood.\nThese concepts are *capacity* and *length*. In some contexts, especially\nin C++, *length* is also called of *size*.\n\nAlthough they look similar, these concepts represent different things\nin the context of a dynamic array. *Capacity* is the number of items (or elements)\nthat your dynamic array can currently hold without the need to allocate more memory.\n\nIn contrast, the *length* refers to how many elements in the array\nare currently being used, or, in other words, how many elements in this array\nthat you have assigned a value to. Every dynamic array works around\na block of allocated memory, which represents an array with total capacity for $n$ elements.\nHowever, only a portion of these $n$ elements are being used most of the time. This portion\nof $n$ is the *length* of the array. So every time you append a new value\nto the array, you are incrementing its *length* by one.\n\nThis means that a dynamic array usually works with an extra margin, or, an extra space\nwhich is currently empty, but it is waiting and ready to be used. This \"extra space\"\nis essentially the difference between *capacity* and *length*. *Capacity* represents\nthe total number of elements that the array can hold without the need to re-allocate\nor re-expand the array, while the *length* represents how much of this capacity\nis currently being used to hold/store values.\n\n@fig-capacity-length presents this idea visually. Notice that, at first,\nthe capacity of the array is greater than the length of the array.\nSo, the dynamic array have extra space that is currently empty, but it\nis ready to receive a value to be stored.\n\n![Difference between capacity and length in a dynamic array](./../Figures/dynamic-array.png){#fig-capacity-length}\n\nWe can also see at @fig-capacity-length that, when *length* and *capacity* are equal, it means that the array have no space left.\nWe have reached the ceiling of our capacity, and because of that, if we want to store more values\nin this array, we need to expand it. We need to get a bigger space that can hold more values\nthan what we currently have.\n\nA dynamic array works by expanding the underlying array, whenever the *length* becomes equal\nto the *capacity* of the array. It basically allocates a new contiguous block of memory that is bigger\nthan the previous one, then, it copies all values that are currently being stored to this new\nlocation (i.e. this new block of memory), then, it frees the previous block of\nmemory. At the end of this process, the new underlying array have a bigger *capacity*, and, therefore,\nthe *length* becomes, once again, smaller than the *capacity* of the array.\n\nThis is the cycle of an dynamic array. Notice that, throughout this cycle, the *capacity* is always\neither equal to or higher than the *length* of the array. If youh have an `ArrayList` object (let's suppose\nyou named it `buffer`), you can check the current capacity of your array by accessing the `capacity`\nattribute of your `ArrayList` object, while the current *length* of it is available at the `items.len`\nattribute.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// Check capacity\nbuffer.capacity;\n// Check length\nbuffer.items.len;\n```\n:::\n\n\n\n\n\n### Creating an `ArrayList` object\n\nIn order to use `ArrayList`, you must provide an allocator object to it.\nRemember, Zig does not have a default memory allocator. And as I described at @sec-allocators, all memory\nallocations must be done by an allocator object that you define, that\nyou have control over. In our example here, I'm going to use\na general purpose allocator, but you can use any other allocator\nof your preference.\n\nWhen you initialize an `ArrayList` object, you must provide the data type of the elements of\nthe array. In other words, this defines the type of data that this array (or container) will\nstore. Therefore, if I provide the `u8` type to it, then, I will create a dynamic\narray of `u8` values. However, if I provide a struct that I have defined instead, like the struct `User`\nfrom @sec-structs-and-oop, then, a dynamic array of `User` values\nwill be created. In the example below, with the expression `ArrayList(u8)` we\nare creating a dynamic array of `u8` values.\n\nAfter you provide the data type of the elements of the array, you can initialize\nan `ArrayList` object by either using the `init()` or the `initCapacity()` methods.\nThe former method receives only the allocator object\nas input, while the latter method receives both the allocator object and a capacity number as inputs.\nWith the latter method, you not only initialize the struct, but you\nalso set the starting capacity of the allocated array.\n\nUsing the `initCapacity()` method is the preferred way to initialize your dynamic array.\nBecause reallocations, or, in other words, the process of expanding the capacity of the array,\nis always a high cost operation. You should take any possible opportunity to avoid reallocations in\nyour array. If you know how much space your array needs to occupy at the beginning,\nyou should always use `initCapacity()` to create your dynamic array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n```\n:::\n\n\n\n\n\nIn the example above, the `buffer` object starts as an array of 100 elements. If this\n`buffer` object needs to create more space to accomodate more elements during the runtime of your program, the `ArrayList`\ninternals will perform the necessary actions for you automatically.\nAlso notice the `deinit()` method being used to destroy the `buffer` object at the\nend of the current scope, by freeing all the memory that was allocated for the dynamic\narray stored in this `buffer` object.\n\n\n### Adding new elements to the array\n\nNow that we have created our dynamic array, we can start to use it. You can append (a.k.a \"add\")\nnew values to this array by using the `append()` method. This method works the same way\nas the `append()` method from a Python list, or, the `emplace_back()` method from `std::vector` of C++.\nYou provide a single value to this method, and the method appends this value to the array.\n\nYou can also use the `appendSlice()` method to append multiple values at once. You provide\na slice (slices were described at @sec-arrays) to this method, and the method adds all values present\nin this slice to your dynamic array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry buffer.append('H');\ntry buffer.append('e');\ntry buffer.append('l');\ntry buffer.append('l');\ntry buffer.append('o');\ntry buffer.appendSlice(\" World!\");\n```\n:::\n\n\n\n\n### Removing elements from the array {#sec-dynamic-array-remove}\n\nYou can use the `pop()` method to \"pop\" or remove\nthe last element in the array. Is worth noting that this method\ndo not change the capacity of the array. It just deletes or erases\nthe last value stored in the array.\n\nAlso, this method returns as result the value that got deleted. That is, you can\nuse this method to both get the last value in the array, and also, remove\nit from the array. It is a \"get and remove value\" type of method.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exclamation_mark = buffer.pop();\n```\n:::\n\n\n\n\nNow, if you want to remove specific elements from specific positions\nof your array, you can use the `orderedRemove()` method from your\n`ArrayList` object. With this method, you can provide an index as input,\nthen, the method will delete the value that is at this index in the array.\nYou are effectively reducing the *length* of the array everytime you execute\nan `orderedRemove()` operation.\n\nIn the example below, we first create an `ArrayList` object, and we fill it\nwith numbers. Then, we use `orderedRemove()` to remove the value at\nindex 3 in the array, two consecutive times.\n\nAlso, notice that we are assigning the result of `orderedRemove()` to the\nunderscore character. So we are discarding the result value of this method.\nThe `orderedRemove()` method returns the value that got deleted, in a similar\nstyle to the `pop()` method.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n\nfor (0..10) |i| {\n    const index: u8 = @intCast(i);\n    try buffer.append(index);\n}\n\nstd.debug.print(\n    \"{any}\\n\", .{buffer.items}\n);\n_ = buffer.orderedRemove(3);\n_ = buffer.orderedRemove(3);\n\nstd.debug.print(\"{any}\\n\", .{buffer.items});\nstd.debug.print(\"{any}\\n\", .{buffer.items.len});\n```\n:::\n\n\n\n\n```\n{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }\n{ 0, 1, 2, 5, 6, 7, 8, 9 }\n8\n```\n\nOne key characteristic about `orderedRemove()` is that it preserves the order\nof the values in the array. So, it deletes the value that you asked it to\nremove, but it also makes sure that the order of the values that remain in the array\nstay the same as before.\n\nNow, if you don't care about the order of the values, for example, maybe you want to treat\nyour dynamic array as a set of values, like the `std::unordered_set`\nstructure from C++, you can use the `swapRemove()` method instead. This method\nworks similarly to the `orderedRemove()` method. You give an index to this\nmethod, then, it deletes the value that is at this index in the array.\nBut this method does not preserve the original order of the values that remain\nin the array. As a result, `swapRemove()` is, in general, faster than `orderedRemove()`.\n\n\n### Inserting elements at specific indexes\n\nWhen you need to insert values in the middle of your array,\ninstead of just appending them to the end of the array, you need to use\nthe `insert()` and `insertSlice()` methods, instead of\nthe `append()` and `appendSlice()` methods.\n\nThese two methods work very similarly to `insert()` and `insert_range()`\nfrom the C++ `std::vector` class. You provide an index to these methods,\nand they insert the values that you provide at that index in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 10);\ndefer buffer.deinit();\n\ntry buffer.appendSlice(\"My Pedro\");\ntry buffer.insert(4, '3');\ntry buffer.insertSlice(2, \" name\");\nfor (buffer.items) |char| {\n    try stdout.print(\"{c}\", .{char});\n}\n```\n:::\n\n\n\n\n```\nMy name P3edro\n```\n\n\n### Conclusion\n\nIf you feel the lack of some other method, I recommend\nyou to read the [official documentation for the `ArrayListAligned`](https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned)[^zig-array2]\nstruct, which describes most of the methods available\nthrough the `ArrayList` object.\n\nYou will notice that there is a lot of other methods in this page that\nI did not described here, and I recommend you to explore these methods,\nand understand how they work.\n\n[^zig-array2]: <https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned>\n\n\n\n## Maps or HashTables {#sec-maps-hashtables}\n\nSome professionals know this type of data structure by different terms, like \"map\",\n\"hashmap\" or \"associative arrays\". But the most common term used is *hashtable*.\nEvery programming language normally have some implementation of a hashtable in their\nstandard libraries. Python have `dict()`, C++ have `std::map` and `std::unordered_map`, Rust\nhave `HashMap`, Javascript have `Object()` and `Map()`, etc.\n\n\n\n### What is a hashtable?\n\nA hashtable is a data structure based on key-value pairs.\nYou provide a key and a value to this structure, then, the hashtable will store\nthe input value at a location that can be identified by the input\nkey that you provided.\nIt does that by using an underlying array and a hash function.\nThese two components are essential to how a hashtable works.\n\nUnder the hood, the hashtable contains an array. This array is where the values\nare stored, and the elements of this array are usually called of *buckets*.\nSo the values that you provide to the hashtable are stored inside buckets,\nand you access each bucket by using an index.\n\nWhen you provide a key to a hashtable, it passes this key to the\nhash function. This hash function uses some sort of hashing algorithm to transform\nthis key into an index. This index is actually an array index. It is a position\nin the underlying array of the hashtable.\nThis is how a key identifies a specific position (or location) inside the hashtable\nstructure.\n\nTherefore, you provide a key to the hashtable, and this key identifies a specific location\ninside the hashtable, then, the hashtable takes the input value that you provided,\nand stores this value in the location identified by this input key.\nYou could say that the key maps to the value stored in the hashtable. You find\nthe value, by using the key that identifies the location where the value is stored.\nThe @fig-hashtable presents this process visually.\n\n\n![A diagram of a Hashtable. Source: Wikipedia, the free encyclopedia.](./../Figures/hashtable.svg){#fig-hashtable}\n\n\nThe operation described in the previous paragraph is normally called an *insertion* operation.\nBecause you are inserting new values into the hashtable.\nBut there are other types of operations in hashtables such as *delete* and *lookup*.\nDelete is self describing, it is when you delete (or remove) a value from the hashtable.\nWhile lookup corresponds to when you look at a value that is stored in\nthe hashtable, by using the key that identifies the location where this value is stored.\n\nSometimes, instead of storing the values directly, the underlying array of the hashtable might be an array of pointers,\ni.e. the buckets of the array stores pointers that points to the value,\nor also, may be an array of linked lists.\nThese cases are common on hashtables that allows duplicate keys, or, in other words,\non hashtables that effectively handle \"collisions\" that may arise from the hash function.\n\nDuplicate keys, or this \"collision\" thing that I'm talking about, is when you have two different keys\nthat points to the same location (i.e. to the same index)\nin the underlying array of the hashtable. This might happen depending on the characteristics of the hash function\nthat is being used in the hashtable. Some implementations of the hashtable will actively deal with collisions,\nmeaning that, they will handle this case in some way. For example, the hashtable\nmight transform all buckets into linked lists. Because with a linked list you can store\nmultiple values into a single bucket.\n\nThere are different techniques to handle collisions in hashtables, which I will not describe\nin this book, because it is not our main scope here. But you can find a good description of\nsome of the most common techniques at the Wikipedia page of hashtables [@wikipedia_hashtables].\n\n\n### Hashtables in Zig {#sec-hashmap}\n\nThe Zig Standard Library provides different implementations of a hashtable.\nEach implementation have its own cons and pros, which we will\ndiscuss later on, and all of them are available through the `std.hash_map` module.\n\nThe `HashMap` struct is a general-purpose hashtable,\nwhich have very fast operations (lookup, insertion, delete), and also,\nquite high load factors for low memory usage. You can create and provide a context object\nto the `HashMap` constructor. This context object allows you to tailor\nthe behaviour of the hashtable itself, because you can\nprovide a hash function implementation to be used by the hashtable\nthrough this context object.\n\nBut let's not worry about this context object now, because it is meant to be used\nby \"experts in the field of hashtables\". Since we are most likely not\nexperts in this field, we are going to take the easy way to create\na hashtable. Which is by using the `AutoHashMap()` function.\n\n\nThis `AutoHashMap()` function is essentially a \"create a hashtable object that uses the default settings\"\ntype of function. It automatically chooses a context object, and, therefore, a hash function implementation,\nfor you. This function receives two data types as input, the first input is the data type of the keys\nthat will be used in this hashtable, while the second input is the data type of the data that will be\nstored inside the hashtable, that is, the data type of the values to be stored.\n\nIn the example below, we are providing the data type `u32` in the first argument, and `u16` in the second argument of this\nfunction. This means that we are going to use `u32` values as keys in this hashtable, while `u16` values are the actual values\nthat are going to be stored into this hashtable.\nAt the end of this process, the `hash_table` object contains a `HashMap` object\nthat uses the default settings and context.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n    std.debug.print(\n        \"Value at key 50050: {d}\\n\",\n        .{hash_table.get(50050).?}\n    );\n\n    if (hash_table.remove(57709)) {\n        std.debug.print(\n            \"Value at key 57709 successfully removed!\\n\",\n            .{}\n        );\n    }\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n}\n```\n:::\n\n\n\n\n```\nN of values stored: 3\nValue at key 50050: 55\nValue at key 57709 successfully removed!\nN of values stored: 2\n```\n\nYou can add/put new values into the hashtable by using the `put()` method. The first argument\nis the key to be used, and the second argument is the actual value that you want to store inside\nthe hashtable. In the example below, we first add the value 89 using the key 54321, next, we add\nthe value 55 using the key 50050, etc.\n\nNotice that we have used the method `count()` to see how many values are currently stored in the\nhashtable. After that, we also use the `get()` method to access (or look) at the value stored in\nthe position identified by the key 500050. The output of this `get()` method is an optional value.\nThis is why we use the `?` method at the end to get the actual value.\n\nAlso notice that we can remove (or delete) values from the hashtable by using the `remove()` method.\nYou provide the key that identifies the value that you want to delete, then, the method will\ndelete this value and return a `true` value as output. This `true` value essentially tells us\nthat the method successfully deleted the value.\n\nBut this delete operation might not be always successful. For example, you might provide the wrong\nkey to this method. I mean, maybe you provide\n(either intentionally or unintentionally) a key that points to an empty bucket,\ni.e. a bucket that still doesn't have a value in it.\nIn this case, the `remove()` method would return a `false` value.\n\n\n\n### Iterating through the hashtable\n\nIterating through the keys and values that are currently being stored in\nthe hashtable is a very common necessity.\nYou can do that in Zig by using an iterator object that can iterate\nthrough the elements of your hashtable object.\n\nThis iterator object works like any other iterator object that you would\nfind in languages such as C++ and Rust. It is basically a pointer object\nthat points to some value in the container, and has a `next()` method\nthat you can use to navigate (or iterate) through the values in the\ncontainer.\n\nYou can create such iterator object by using the `iterator()` method of the hashtable object.\nThis method returns an iterator object, from which you can use the `next()` method in conjunction\nwith a while loop to iterate through the elements of your hashtable. The `next()` method returns an optional\n`Entry` value, and therefore, you must unwrap this optional value to get the actual `Entry` value\nfrom which you can access the key and also the value identified by this key.\n\nWith this `Entry` value at hand, you can access the key of this current entry by using the `key_ptr`\nattribute and dereferencing the pointer that lives inside of it, while the value identified by this\nkey is accessed through the `value_ptr` attribute instead, which is also a pointer to be dereferenced.\nThe code example below demonstrates the use of these elements:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n\n    var it = hash_table.iterator();\n    while (it.next()) |kv| {\n        // Access the current key\n        std.debug.print(\"Key: {d} | \", .{kv.key_ptr.*});\n        // Access the current value\n        std.debug.print(\"Value: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n:::\n\n\n\n\n```\nKey: 54321 | Value: 89\nKey: 50050 | Value: 55\nKey: 57709 | Value: 41\n```\n\n\nIf you want to iterate specifically through the values or the keys of your hashtable,\nyou can create a key iterator or a value iterator object. These are also iterator\nobjects, which have the same `next()` method that you can use to iterate through the\nhashtable.\n\nKey iterators are created from the `keyIterator()` method of your\nhashtable object, while value iterators are created from the `valueIterator()` method.\nAll you have to do is to unwrap the value from the `next()` method and deference it\ndirectly to access the key or the value that you are iterating over.\nThe code example below demonstrates the use of a key iterator,\nbut you can replicate the same logic to a value iterator.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar kit = hash_table.keyIterator();\nwhile (kit.next()) |key| {\n    std.debug.print(\"Key: {d}\\n\", .{key.*});\n}\n```\n:::\n\n\n\n\n```\nKey: 54321\nKey: 50050\nKey: 57709\n```\n\n\n### The `ArrayHashMap` hashtable {#sec-array-map}\n\nIf you need to iterate through the elements of your hashtable constantly,\nyou might want to use the `ArrayHashMap` struct for your specific case,\ninstead of going with the usual and general-purpose `HashMap` struct.\n\nThe `ArrayHashMap` struct creates a hashtable that is faster to iterate over.\nThat is why this specific type of hashtable might be valuable to you.\nSome other properties of a `ArrayHashMap` hashtable are:\n\n- the order of insertion is preserved, i.e. the order of the values that you find while iterating through this hashtable is actually the order in which these values were inserted in the hashtable.\n- the key-value pairs are stored sequentially, one after another.\n\n\nYou can create an `ArrayHashMap` object by using, once again, a helper function that\nchooses automatically for you a hash function implementation. This is the\n`AutoArrayHashMap()` function, which works very similarly to the `AutoHashMap()`\nfunction that we presented at @sec-hashmap.\n\nYou provide two data types to this function. The data type of the keys that will be\nused in this hashtable, and the data type of the values that will be stored in\nthis hashtable.\n\nAn `ArrayHashMap` object have essentially the exact same methods from the `HashMap` struct.\nSo you can insert new values into the hashtable by using the `put()` method, and you can look (or get)\na value from the hashtable by using the `get()` method. But the `remove()` method is not available\nin this specific type of hashtable.\n\nIn order to delete values from the hashtable, you would use the same methods that you find in\nan `ArrayList` object, i.e. a dynamic array. I presented these methods at @sec-dynamic-array-remove,\nwhich are the `swapRemove()` and `orderedRemove()` methods. These methods have the same meaning here, or,\nthe same effect that they have in an `ArrayList` object.\n\nThis means that, with `swapRemove()` you remove the value from the hashtable, but you do not preserve\nthe order in which the values were inserted into the structure. While `orderedRemove()` is able\nto retain the order in which these values were inserted.\n\nBut instead of providing an index as input to `swapRemove()` or `orderedRemove()`, like I described\nat @sec-dynamic-array-remove, these methods here in an `ArrayHashMap` take a key as input, like\nthe `remove()` method from a `HashMap` object. If you want to provide an index as input, instead\nof a key, you should use the `swapRemoveAt()` and `orderedRemoveAt()` methods.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar hash_table = AutoArrayHashMap(u32, u16)\n    .init(allocator);\ndefer hash_table.deinit();\n```\n:::\n\n\n\n\n\n\n### The `StringHashMap` hashtable {#sec-string-hash-map}\n\nOne thing that you will notice in the other two types of hashtables that I have\npresented over the last sections, is that neither of them accepts a slice data type\nin their keys.\nWhat this means is that you cannot use a slice value to represent a key in\nthese types of hashtable.\n\nThe most obvious consequence of this, is that you cannot use strings as keys\nin these hashtables. But it is extremely common to use strings as keys\nin hashtables.\n\nTake this very simple Javascript code snippet as an example. We are creating\na simple hashtable object named `people`. Then, we add a new entry to this\nhashtable, which is identified by the string `'Pedro'`. This string is the\nkey in this case, while the object containing different personal information such as\nage, height and city, is the value to be stored in the hashtable.\n\n```js\nvar people = new Object();\npeople['Pedro'] = {\n    'age': 25,\n    'height': 1.67,\n    'city': 'Belo Horizonte'\n};\n```\n\nThis pattern of using strings as keys is very common in\nall sorts of situations. That is why the Zig Standard Library offers a\nspecific type of hashtable for this purpose, which is created through the `StringHashMap()` function.\nThis function creates a hashtable that uses strings as keys. The only input of this\nfunction is the data type of the values that will be stored into this hashtable.\n\nIn the example below, I'm creating a hashtable to store the ages of different people.\nEach key in this hashtable is represented by the name of each person, while the value stored in the\nhashtable is the age of this person identified by the key.\n\nThat is why I provide the `u8` data type (which is the data type used by the age values) as input to this `StringHashMap()` function.\nAs the result, it creates a hashtable that uses string values as keys, and, that stores\n`u8` values in it. Notice that an allocator object is provided at the `init()` method of the\nresulting object from the `StringHashMap()` function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var ages = std.StringHashMap(u8).init(allocator);\n    defer ages.deinit();\n\n    try ages.put(\"Pedro\", 25);\n    try ages.put(\"Matheus\", 21);\n    try ages.put(\"Abgail\", 42);\n\n    var it = ages.iterator();\n    while (it.next()) |kv| {\n        std.debug.print(\"Key: {s} | \", .{kv.key_ptr.*});\n        std.debug.print(\"Age: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n:::\n\n\n\n\n```\nKey: Pedro | Age: 25\nKey: Abgail | Age: 42\nKey: Matheus | Age: 21\n```\n\n\n### The `StringArrayHashMap` hashtable\n\nThe Zig Standard Library also provides a type of hashtable that mix the cons and pros of the\n`StringHashMap` and `ArrayHashMap` together. That is, a hashtable\nthat uses strings as keys, but also have the advantages from `ArrayHashMap`.\nIn other words, you can have a hashtable that is fast to iterate over,\nthat preserves insertion order, and also, that uses strings as keys.\n\nYou can create such type of hashtable by using the `StringArrayHashMap()` function.\nThis function accepts a data type as input, which is the data type of the values that are\ngoing to be stored inside this hashtable, in the same style as the function presented\nat @sec-string-hash-map.\n\nYou can insert new values into this hashtable by using the same `put()` method that\nwe have discussed at @sec-string-hash-map. And you can also get values from the hashtable\nby using the same `get()` method.\nLike its `ArrayHashMap` brother, to delete values from this specific type of hashtable,\nwe also use the `orderedRemove()` and `swapRemove()` methods, with the same effects that\nI have described at @sec-array-map.\n\nIf we take the code example that was exposed at @sec-string-hash-map, we can\nachieve the exact same result with `StringArrayHashMap()`:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar ages = std.StringArrayHashMap(u8).init(allocator);\n```\n:::\n\n\n\n\n\n\n\n## Linked lists\n\nThe Zig Standard Library provides an implementation for both singly and doubly linked lists.\nA linked list is a linear data structure that looks like a chain, or, a rope.\nThe main advantage of this data structure is that you normally have very fast\ninsertion and deletion operations. But, as a disadvantage, iterating through\nthis data structure is usually not so fast as iterating through an array.\n\nThe idea behind a linked list is to build a structure that consists of a sequence of nodes\nconnected to each other by pointers. This means that linked lists are usually not contiguous\nin memory, because each node might be anywhere in memory. They do not need to be close to\none another.\n\nAt @fig-linked-list we can see a diagram of a singly linked list. We begin at the first node\n(which is usually called \"the head of the linked list\"). Then, from this\nfirst node we uncover the remaining nodes in the structure, by following the locations pointed\nby the pointers found in each node.\n\nEach node has two things in it. It has the value that is stored in the current node\n, and also, a pointer. This pointer points to the next node in the list. If this pointer\nis null, then, it means that we have reached the end of our linked list.\n\n![A diagram of a singly linked list.](./../Figures/linked-list.png){#fig-linked-list}\n\n\nAt @fig-linked-list2 we can see a diagram of a doubly linked list. The only thing that really\nchanges now is that every node in the linked list has both a pointer to the previous node,\nand, a pointer to the next node. So every node in a doubly linked list has two pointers in it. These are\nusually called the `prev` (for \"previous\") and the `next` (for \"next\") pointers of the node.\n\nIn the singly linked list example, we had only one single pointer in each node, and this singular\npointer was always pointing to the next node in the sequence. This means that singly linked lists\nnormally have only the `next` pointer in them.\n\n![A diagram of a doubly linked list.](./../Figures/doubly-linked-list.png){#fig-linked-list2}\n\n\nLinked lists are available in Zig through the functions `SinglyLinkedList()` and\n`DoublyLinkedList()`, for \"singly linked lists\" and \"doubly linked lists\", respectively. These functions are\nactually generic functions, which we are going to talk more about at @sec-generic-fun.\n\nFor now, just understand that, in order to create a linked list object,\nwe begin by providing a data type to these functions. This data type defines\nthe type of data that each node in this linked list will store. In the example below,\nwe are creating a singly linked list of `u32` values.\nSo each node in this linked list will store a `u32` value.\n\nBoth the `SinglyLinkedList()` and `DoublyLinkedList()` functions returns a type,\ni.e. a struct definition, as output. Therefore, the object `Lu32` is actually\na struct definition. It defines the type \"singly linked list of `u32` values\".\n\nNow that we have the definition of the struct, we need to instantiate a `Lu32` object.\nWe normally instantiate struct objects in Zig by using an `init()` method.\nBut in this case, we are instantiating the struct directly, by using an empty\n`struct` literal, in the expression `Lu32{}`.\n\nIn this example, we first create multiple node objects, and after we create them,\nwe start to insert and connect these nodes to build the linked list, using the\n`prepend()` and `insertAfter()` methods. Notice that the `prepend()` method\nis a method from the linked list object, while the `insertAfter()` is a method\npresent in the node objects.\n\nIn essence, the `prepend()` method inserts a node at the beginning of the linked\nlist. In other words, the node that you provide to this method, becomes the new\n\"head node\" of the linked list. It becomes the first node in the list (see @fig-linked-list).\n\nOn the other side, the `insertAfter()` method is used to basically connect two nodes together.\nWhen you provide a node to this method, it creates a pointer to this input node,\nand stores this pointer in the `next` attribute of the current node, from which the method was called from.\n\nBecause doubly linked lists have both a `next` and a `prev` attributes in each node\n(as described at @fig-linked-list2), a node object created from\na `DoublyLinkedList` object have both an `insertBefore()` (for `prev`)\nand an `insertAfter()` (for `next`) methods available.\n\nThus, if we have used a doubly linked list, we can use the `insertBefore()` method\nto store the pointer to the input node in the `prev` attribute. This would put the input\nnode as the \"previous node\", or, the node before the current node. In contrast, the `insertAfter()` method\nputs the pointer created to the input node in the `next` attribute of the current node,\nand as result, the input node becomes the \"next node\" of the current node.\n\nSince we are using a singly linked list in this example, we have only the `insertAfter()` method\navailable in the node objects that we create from our `Lu32` type.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SinglyLinkedList = std.SinglyLinkedList;\nconst Lu32 = SinglyLinkedList(u32);\n\npub fn main() !void {\n    var list = Lu32{};\n    var one = Lu32.Node{ .data = 1 };\n    var two = Lu32.Node{ .data = 2 };\n    var three = Lu32.Node{ .data = 3 };\n    var four = Lu32.Node{ .data = 4 };\n    var five = Lu32.Node{ .data = 5 };\n\n    list.prepend(&two); // {2}\n    two.insertAfter(&five); // {2, 5}\n    list.prepend(&one); // {1, 2, 5}\n    two.insertAfter(&three); // {1, 2, 3, 5}\n    three.insertAfter(&four); // {1, 2, 3, 4, 5}\n}\n```\n:::\n\n\n\n\n\nThere are other methods available from the linked list object, depending if this object is\na singly linked list or a doubly linked list, that might be very useful for you. You can find a\nsummary of them in the bullet points below:\n\n- `remove()` to remove a specific node from the linked list.\n- if singly linked list, `len()` to count how many nodes there is in the linked list.\n- if doubly linked list, checkout the `len` attribute to see how many nodes there is in the linked list.\n- if singly linked list, `popFirst()` to remove the first node (i.e. the \"head\") from the linked list.\n- if doubly linked list, `pop()` and `popFirst()` to remove the last and first nodes from the linked list, respectively.\n- if doubly linked list, `append()` to add a new node to end of the linked list (i.e. inverse of `prepend()`).\n\n\n\n## Multi array structure\n\nZig introduces a new data structure called `MultiArrayList()`. It is a different version of the dynamic array\nthat we have introduced at @sec-dynamic-array. The difference between this structure and the `ArrayList()`\nthat we know from @sec-dynamic-array, is that `MultiArrayList()` creates a separate dynamic array\nfor each field of the struct that you provide as input.\n\nConsider the following code example. We create a new custom struct called `Person`. This\nstruct contains three different data members, or, three different fields. As consequence,\nwhen we provide this `Person` data type as input to `MultiArrayList()`, this\ncreates a \"struct of three different arrays\" called `PersonArray`. In other words,\nthis `PersonArray` is a struct that contains three internal dynamic arrays in it.\nOne array for each field found in the `Person` struct definition.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Person = struct {\n    name: []const u8,\n    age: u8,\n    height: f32,\n};\nconst PersonArray = std.MultiArrayList(Person);\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var people = PersonArray{};\n    defer people.deinit(allocator);\n\n    try people.append(allocator, .{\n        .name = \"Auguste\", .age = 15, .height = 1.54\n    });\n    try people.append(allocator, .{\n        .name = \"Elena\", .age = 26, .height = 1.65\n    });\n    try people.append(allocator, .{\n        .name = \"Michael\", .age = 64, .height = 1.87\n    });\n}\n```\n:::\n\n\n\n\nIn other words, instead of creating an array of \"persons\", the `MultiArrayList()` function\ncreates a \"struct of arrays\". Each data member of this struct is a different array that stores\nthe values of a specific field from the `Person` values that were added (or, appended) to this \"struct of arrays\".\nOne important detail is that each of these separate internal arrays stored inside `PersonArray`\nare dynamic arrays. This means that these arrays can grow in capacity automatically as needed, to accomodate\nmore values.\n\nThe @fig-multi-array exposed below presents a diagram that describes the `PersonArray` struct\nthat we have created in the previous code example. Notice that the values of the data members\npresent in each of the three `Person` values that we have appended into the `PersonArray` object\n, are scattered across three different internal arrays of the `PersonArray` object.\n\n![A diagram of the `PersonArray` struct.](./../Figures/multi-array.png){#fig-multi-array}\n\nYou can easily access each of these arrays separately, and iterate over the values of each array.\nFor that, you will need to call the `items()` method from the `PersonArray` object, and provide as input\nto this method, the name of the field that you want to iterate over.\nIf you want to iterate through the `.age` array for example, then, you need to call `items(.age)` from\nthe `PersonArray` object, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (people.items(.age)) |*age| {\n    try stdout.print(\"Age: {d}\\n\", .{age.*});\n}\n```\n:::\n\n\n\n\n```\nAge: 15\nAge: 26\nAge: 64\n```\n\n\nIn the above example, we are iterating over the values of the `.age` array, or,\nthe internal array of the `PersonArray` object that contains the values of the `age`\ndata member from the `Person` values that were added to the multi array struct.\n\nIn this example we are calling the `items()` method directly from the `PersonArray`\nobject. However, it is recommended on most situations to call this `items()` method\nfrom a \"slice object\", which you can create from the `slice()` method.\nThe reason for this is that calling `items()` multiple times have better performance\nif you use a slice object.\n\nTherefore, if you are planning to access only one of the\ninternal arrays from your \"multi array struct\", it is fine to call `items()` directly\nfrom the multi array object. But if you need to access many of the internal arrays\nfrom your \"multi array struct\", then, you will likely need to call `items()` more\nthan once, and, in such circumstance, is better to call `items()` through a slice object.\nThe example below demonstrates the use of such object:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar slice = people.slice();\nfor (slice.items(.age)) |*age| {\n    age.* += 10;\n}\nfor (slice.items(.name), slice.items(.age)) |*n,*a| {\n    try stdout.print(\n        \"Name: {s}, Age: {d}\\n\", .{n.*, a.*}\n    );\n}\n```\n:::\n\n\n\n\n```\nName: Auguste, Age: 25\nName: Elena, Age: 36\nName: Michael, Age: 74\n```\n\n\n## Conclusion\n\nThere are many other data structures that I haven't presented here.\nBut you can check them out at the official Zig Standard Library documentation page.\nActually, when you get into the [homepage of the documentation](https://ziglang.org/documentation/master/std/#)[^home], the first thing\nthat appears to you in this page, is a list of types and data structures that\nare available in the Zig Standard Library.\nThere are some very specific data structures in this list, like a\n[`BoundedArray` struct](https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray)[^bounded]\n, but there is also some more general structures, such as a\n[`PriorityQueue` struct](https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue)[^priority].\n\n\n[^home]: <https://ziglang.org/documentation/master/std/#>\n[^priority]: <https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue>.\n[^bounded]: <https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray>\n\n\n\n\n\n\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Data Structures\n\nIn this chapter, I want to present the most common Data Structures that are available from\nthe Zig Standard Library, especially `ArrayList` and also `HashMap`. These are generic Data Structures\nthat you can use to store and control any type of data that is produced by your application.\n\n## Dynamic Arrays {#sec-dynamic-array}\n\nIn high level languages, arrays are usually dynamic. They can easily grow\nin size when they have to, and you don't need to worry about it.\nIn contrast, arrays in low level languages are usually static by default.\nThis is the reality of C, C++, Rust and also Zig. Static arrays were presented at\n@sec-arrays, but in this section, we are going to talk about dynamic arrays in Zig.\n\nDynamic arrays are simply arrays that can grow in size during the runtime\nof your program. Most low level languages have some implementation of\na dynamic array in their standard library. C++ have `std::vector`, Rust have `Vec`,\nand Zig have `std.ArrayList`.\n\nThe `std.ArrayList` struct provides a contiguous and growable array for you.\nIt works like any other dynamic array, it allocates a contiguous block of memory, and when this block have no space left,\n`ArrayList` allocates another contiguous and bigger block of memory, copies the\nelements to this new location, and erases (or frees) the previous block of memory.\n\n\n### Capacity vs Length\n\nWhen we talk about dynamic arrays, we usually have two similar concepts that\nare very essential to how a dynamic array works behind the hood.\nThese concepts are *capacity* and *length*. In some contexts, especially\nin C++, *length* is also called of *size*.\n\nAlthough they look similar, these concepts represent different things\nin the context of a dynamic array. *Capacity* is the number of items (or elements)\nthat your dynamic array can currently hold without the need to allocate more memory.\n\nIn contrast, the *length* refers to how many elements in the array\nare currently being used, or, in other words, how many elements in this array\nthat you have assigned a value to. Every dynamic array works around\na block of allocated memory, which represents an array with total capacity for $n$ elements.\nHowever, only a portion of these $n$ elements are being used most of the time. This portion\nof $n$ is the *length* of the array. So every time you append a new value\nto the array, you are incrementing its *length* by one.\n\nThis means that a dynamic array usually works with an extra margin, or an extra space\nthat is currently empty, but waiting and ready to be used. This \"extra space\"\nis essentially the difference between *capacity* and *length*. *Capacity* represents\nthe total number of elements that the array can hold without the need to re-allocate\nor re-expand the array, while the *length* represents how much of this capacity\nis currently being used to hold/store values.\n\n@fig-capacity-length presents this idea visually. Notice that, at first,\nthe capacity of the array is greater than the length of the array.\nSo, the dynamic array have extra space that is currently empty, but it\nis ready to receive a value to be stored.\n\n![Difference between capacity and length in a dynamic array](./../Figures/dynamic-array.png){#fig-capacity-length}\n\nWe can also see in @fig-capacity-length that, when *length* and *capacity* are equal, it means that the array have no space left.\nWe have reached the ceiling of our capacity, and because of that, if we want to store more values\nin this array, we need to expand it. We need to get a bigger space that can hold more values\nthan what we currently have.\n\nA dynamic array works by expanding the underlying array, whenever the *length* becomes equal\nto the *capacity* of the array. It basically allocates a new contiguous block of memory that is bigger\nthan the previous one, then, it copies all values that are currently being stored to this new\nlocation (i.e., this new block of memory), then, it frees the previous block of\nmemory. At the end of this process, the new underlying array have a bigger *capacity*, and, therefore,\nthe *length* becomes, once again, smaller than the *capacity* of the array.\n\nThis is the cycle of a dynamic array. Notice that, throughout this cycle, the *capacity* is always\neither equal to or higher than the *length* of the array. If you have an `ArrayList` object (let's suppose\nyou named it `buffer`), you can check the current capacity of your array by accessing the `capacity`\nattribute of your `ArrayList` object, while the current *length* of it is available at the `items.len`\nattribute.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// Check capacity\nbuffer.capacity;\n// Check length\nbuffer.items.len;\n```\n:::\n\n\n\n\n\n### Creating an `ArrayList` object\n\nIn order to use `ArrayList`, you must provide an allocator object to it.\nRemember, Zig does not have a default memory allocator. And as I described in @sec-allocators, all memory\nallocations must be done by an allocator object that you define, that\nyou have control over. In our example here, I'm going to use\na general purpose allocator, but you can use any other allocator\nof your preference.\n\nWhen you initialize an `ArrayList` object, you must provide the data type of the elements of\nthe array. In other words, this defines the type of data that this array (or container) will\nstore. Therefore, if I provide the `u8` type to it, then, I will create a dynamic\narray of `u8` values. However, if I provide a struct that I have defined instead, like the struct `User`\nfrom @sec-structs-and-oop, then, a dynamic array of `User` values\nwill be created. In the example below, with the expression `ArrayList(u8)` we\nare creating a dynamic array of `u8` values.\n\nAfter you provide the data type of the elements of the array, you can initialize\nan `ArrayList` object by either using the `init()` or the `initCapacity()` methods.\nThe former method receives only the allocator object\nas input, while the latter method receives both the allocator object and a capacity number as inputs.\nWith the latter method, you not only initialize the struct, but you\nalso set the starting capacity of the allocated array.\n\nUsing the `initCapacity()` method is the preferred way to initialize your dynamic array.\nBecause reallocations, or, in other words, the process of expanding the capacity of the array,\nis always a high cost operation. You should take any possible opportunity to avoid reallocations in\nyour array. If you know how much space your array needs to occupy at the beginning,\nyou should always use `initCapacity()` to create your dynamic array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n```\n:::\n\n\n\n\n\nIn the example above, the `buffer` object starts as an array of 100 elements. If this\n`buffer` object needs to create more space to accomodate more elements during the runtime of your program, the `ArrayList`\ninternals will perform the necessary actions for you automatically.\nAlso notice the `deinit()` method being used to destroy the `buffer` object at the\nend of the current scope, by freeing all the memory that was allocated for the dynamic\narray stored in this `buffer` object.\n\n\n### Adding new elements to the array\n\nNow that we have created our dynamic array, we can start to use it. You can append (a.k.a \"add\")\nnew values to this array by using the `append()` method. This method works the same way\nas the `append()` method from a Python list, or, the `emplace_back()` method from `std::vector` of C++.\nYou provide a single value to this method, and the method appends this value to the array.\n\nYou can also use the `appendSlice()` method to append multiple values at once. You provide\na slice (slices were described in @sec-arrays) to this method, and the method adds all values present\nin this slice to your dynamic array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry buffer.append('H');\ntry buffer.append('e');\ntry buffer.append('l');\ntry buffer.append('l');\ntry buffer.append('o');\ntry buffer.appendSlice(\" World!\");\n```\n:::\n\n\n\n\n### Removing elements from the array {#sec-dynamic-array-remove}\n\nYou can use the `pop()` method to \"pop\" or remove\nthe last element in the array. It's worth noting that this method\ndo not change the capacity of the array. It just deletes or erases\nthe last value stored in the array.\n\nAlso, this method returns as result the value that got deleted. That is, you can\nuse this method to both get the last value in the array, and also, remove\nit from the array. It's a \"get and remove value\" type of method.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exclamation_mark = buffer.pop();\n```\n:::\n\n\n\n\nNow, if you want to remove specific elements from specific positions\nof your array, you can use the `orderedRemove()` method from your\n`ArrayList` object. With this method, you can provide an index as input,\nthen, the method will delete the value that is at this index in the array.\nYou are effectively reducing the *length* of the array everytime you execute\nan `orderedRemove()` operation.\n\nIn the example below, we first create an `ArrayList` object, and we fill it\nwith numbers. Then, we use `orderedRemove()` to remove the value at\nindex 3 in the array, two consecutive times.\n\nAlso, notice that we are assigning the result of `orderedRemove()` to the\nunderscore character. So we are discarding the result value of this method.\nThe `orderedRemove()` method returns the value that got deleted, in a similar\nstyle to the `pop()` method.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n\nfor (0..10) |i| {\n    const index: u8 = @intCast(i);\n    try buffer.append(index);\n}\n\nstd.debug.print(\n    \"{any}\\n\", .{buffer.items}\n);\n_ = buffer.orderedRemove(3);\n_ = buffer.orderedRemove(3);\n\nstd.debug.print(\"{any}\\n\", .{buffer.items});\nstd.debug.print(\"{any}\\n\", .{buffer.items.len});\n```\n:::\n\n\n\n\n```\n{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }\n{ 0, 1, 2, 5, 6, 7, 8, 9 }\n8\n```\n\nOne key characteristic about `orderedRemove()` is that it preserves the order\nof the values in the array. So, it deletes the value that you asked it to\nremove, but it also makes sure that the order of the values that remain in the array\nstay the same as before.\n\nNow, if you don't care about the order of the values, for example, maybe you want to treat\nyour dynamic array as a set of values, like the `std::unordered_set`\nstructure from C++, you can use the `swapRemove()` method instead. This method\nworks similarly to the `orderedRemove()` method. You give an index to this\nmethod, then, it deletes the value that is at this index in the array.\nBut this method does not preserve the original order of the values that remain\nin the array. As a result, `swapRemove()` is, in general, faster than `orderedRemove()`.\n\n\n### Inserting elements at specific indexes\n\nWhen you need to insert values in the middle of your array,\ninstead of just appending them to the end of the array, you need to use\nthe `insert()` and `insertSlice()` methods, instead of\nthe `append()` and `appendSlice()` methods.\n\nThese two methods work very similarly to `insert()` and `insert_range()`\nfrom the C++ `std::vector` class. You provide an index to these methods,\nand they insert the values that you provide at that index in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 10);\ndefer buffer.deinit();\n\ntry buffer.appendSlice(\"My Pedro\");\ntry buffer.insert(4, '3');\ntry buffer.insertSlice(2, \" name\");\nfor (buffer.items) |char| {\n    try stdout.print(\"{c}\", .{char});\n}\n```\n:::\n\n\n\n\n```\nMy name P3edro\n```\n\n\n### Conclusion\n\nIf you feel the lack of some other method, I recommend\nyou to read the [official documentation for the `ArrayListAligned`](https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned)[^zig-array2]\nstruct, which describes most of the methods available\nthrough the `ArrayList` object.\n\nYou will notice that there is a lot of other methods in this page that\nI did not described here, and I recommend you to explore these methods,\nand understand how they work.\n\n[^zig-array2]: <https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned>\n\n\n\n## Maps or HashTables {#sec-maps-hashtables}\n\nSome professionals know this type of data structure by different terms, like \"map\",\n\"hashmap\" or \"associative arrays\". But the most common term used is *hashtable*.\nEvery programming language normally have some implementation of a hashtable in their\nstandard libraries. Python have `dict()`, C++ have `std::map` and `std::unordered_map`, Rust\nhave `HashMap`, Javascript have `Object()` and `Map()`, etc.\n\n\n\n### What is a hashtable?\n\nA hashtable is a data structure based on key-value pairs.\nYou provide a key and a value to this structure, then, the hashtable will store\nthe input value at a location that can be identified by the input\nkey that you provided.\nIt does that by using an underlying array and a hash function.\nThese two components are essential to how a hashtable works.\n\nUnder the hood, the hashtable contains an array. This array is where the values\nare stored, and the elements of this array are usually called of *buckets*.\nSo the values that you provide to the hashtable are stored inside buckets,\nand you access each bucket by using an index.\n\nWhen you provide a key to a hashtable, it passes this key to the\nhash function. This hash function uses some sort of hashing algorithm to transform\nthis key into an index. This index is actually an array index. It's a position\nin the underlying array of the hashtable.\nThis is how a key identifies a specific position (or location) inside the hashtable\nstructure.\n\nTherefore, you provide a key to the hashtable, and this key identifies a specific location\ninside the hashtable, then, the hashtable takes the input value that you provided,\nand stores this value in the location identified by this input key.\nYou could say that the key maps to the value stored in the hashtable. You find\nthe value, by using the key that identifies the location where the value is stored.\nThe @fig-hashtable presents this process visually.\n\n\n![A diagram of a Hashtable. Source: Wikipedia, the free encyclopedia.](./../Figures/hashtable.svg){#fig-hashtable}\n\n\nThe operation described in the previous paragraph is normally called an *insertion* operation.\nBecause you are inserting new values into the hashtable.\nBut there are other types of operations in hashtables such as *delete* and *lookup*.\nDelete is self describing, it's when you delete (or remove) a value from the hashtable.\nWhile lookup corresponds to when you look at a value that is stored in\nthe hashtable, by using the key that identifies the location where this value is stored.\n\nSometimes, instead of storing the values directly, the underlying array of the hashtable might be an array of pointers,\ni.e., the buckets of the array stores pointers that points to the value,\nor also, may be an array of linked lists.\nThese cases are common on hashtables that allows duplicate keys, or, in other words,\non hashtables that effectively handle \"collisions\" that may arise from the hash function.\n\nDuplicate keys, or this \"collision\" thing that I'm talking about, is when you have two different keys\nthat points to the same location (i.e., to the same index)\nin the underlying array of the hashtable. This might happen depending on the characteristics of the hash function\nthat is being used in the hashtable. Some implementations of the hashtable will actively deal with collisions,\nmeaning that, they will handle this case in some way. For example, the hashtable\nmight transform all buckets into linked lists. Because with a linked list you can store\nmultiple values into a single bucket.\n\nThere are different techniques to handle collisions in hashtables, which I will not describe\nin this book, because it's not our main scope here. But you can find a good description of\nsome of the most common techniques at the Wikipedia page of hashtables [@wikipedia_hashtables].\n\n\n### Hashtables in Zig {#sec-hashmap}\n\nThe Zig Standard Library provides different implementations of a hashtable.\nEach implementation have its own cons and pros, which we will\ndiscuss later on, and all of them are available through the `std.hash_map` module.\n\nThe `HashMap` struct is a general-purpose hashtable,\nwhich have very fast operations (lookup, insertion, delete), and also,\nquite high load factors for low memory usage. You can create and provide a context object\nto the `HashMap` constructor. This context object allows you to tailor\nthe behaviour of the hashtable itself, because you can\nprovide a hash function implementation to be used by the hashtable\nthrough this context object.\n\nBut let's not worry about this context object now, because it's meant to be used\nby \"experts in the field of hashtables\". Since we are most likely not\nexperts in this field, we are going to take the easy way to create\na hashtable. Which is by using the `AutoHashMap()` function.\n\n\nThis `AutoHashMap()` function is essentially a \"create a hashtable object that uses the default settings\"\ntype of function. It automatically chooses a context object, and, therefore, a hash function implementation,\nfor you. This function receives two data types as input, the first input is the data type of the keys\nthat will be used in this hashtable, while the second input is the data type of the data that will be\nstored inside the hashtable, that is, the data type of the values to be stored.\n\nIn the example below, we are providing the data type `u32` in the first argument, and `u16` in the second argument of this\nfunction. This means that we are going to use `u32` values as keys in this hashtable, while `u16` values are the actual values\nthat are going to be stored into this hashtable.\nAt the end of this process, the `hash_table` object contains a `HashMap` object\nthat uses the default settings and context.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n    std.debug.print(\n        \"Value at key 50050: {d}\\n\",\n        .{hash_table.get(50050).?}\n    );\n\n    if (hash_table.remove(57709)) {\n        std.debug.print(\n            \"Value at key 57709 successfully removed!\\n\",\n            .{}\n        );\n    }\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n}\n```\n:::\n\n\n\n\n```\nN of values stored: 3\nValue at key 50050: 55\nValue at key 57709 successfully removed!\nN of values stored: 2\n```\n\nYou can add/put new values into the hashtable by using the `put()` method. The first argument\nis the key to be used, and the second argument is the actual value that you want to store inside\nthe hashtable. In the example below, we first add the value 89 using the key 54321, next, we add\nthe value 55 using the key 50050, etc.\n\nNotice that we have used the method `count()` to see how many values are currently stored in the\nhashtable. After that, we also use the `get()` method to access (or look) at the value stored in\nthe position identified by the key 500050. The output of this `get()` method is an optional value.\nThis is why we use the `?` method at the end to get the actual value.\n\nAlso notice that we can remove (or delete) values from the hashtable by using the `remove()` method.\nYou provide the key that identifies the value that you want to delete, then, the method will\ndelete this value and return a `true` value as output. This `true` value essentially tells us\nthat the method successfully deleted the value.\n\nBut this delete operation might not be always successful. For example, you might provide the wrong\nkey to this method. I mean, maybe you provide\n(either intentionally or unintentionally) a key that points to an empty bucket,\ni.e., a bucket that still doesn't have a value in it.\nIn this case, the `remove()` method would return a `false` value.\n\n\n\n### Iterating through the hashtable\n\nIterating through the keys and values that are currently being stored in\nthe hashtable is a very common necessity.\nYou can do that in Zig by using an iterator object that can iterate\nthrough the elements of your hashtable object.\n\nThis iterator object works like any other iterator object that you would\nfind in languages such as C++ and Rust. It's basically a pointer object\nthat points to some value in the container, and has a `next()` method\nthat you can use to navigate (or iterate) through the values in the\ncontainer.\n\nYou can create such iterator object by using the `iterator()` method of the hashtable object.\nThis method returns an iterator object, from which you can use the `next()` method in conjunction\nwith a while loop to iterate through the elements of your hashtable. The `next()` method returns an optional\n`Entry` value, and therefore, you must unwrap this optional value to get the actual `Entry` value\nfrom which you can access the key and also the value identified by this key.\n\nWith this `Entry` value at hand, you can access the key of this current entry by using the `key_ptr`\nattribute and dereferencing the pointer that lives inside of it, while the value identified by this\nkey is accessed through the `value_ptr` attribute instead, which is also a pointer to be dereferenced.\nThe code example below demonstrates the use of these elements:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n\n    var it = hash_table.iterator();\n    while (it.next()) |kv| {\n        // Access the current key\n        std.debug.print(\"Key: {d} | \", .{kv.key_ptr.*});\n        // Access the current value\n        std.debug.print(\"Value: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n:::\n\n\n\n\n```\nKey: 54321 | Value: 89\nKey: 50050 | Value: 55\nKey: 57709 | Value: 41\n```\n\n\nIf you want to iterate specifically through the values or the keys of your hashtable,\nyou can create a key iterator or a value iterator object. These are also iterator\nobjects, which have the same `next()` method that you can use to iterate through the\nhashtable.\n\nKey iterators are created from the `keyIterator()` method of your\nhashtable object, while value iterators are created from the `valueIterator()` method.\nAll you have to do is to unwrap the value from the `next()` method and deference it\ndirectly to access the key or the value that you are iterating over.\nThe code example below demonstrates the use of a key iterator,\nbut you can replicate the same logic to a value iterator.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar kit = hash_table.keyIterator();\nwhile (kit.next()) |key| {\n    std.debug.print(\"Key: {d}\\n\", .{key.*});\n}\n```\n:::\n\n\n\n\n```\nKey: 54321\nKey: 50050\nKey: 57709\n```\n\n\n### The `ArrayHashMap` hashtable {#sec-array-map}\n\nIf you need to iterate through the elements of your hashtable constantly,\nyou might want to use the `ArrayHashMap` struct for your specific case,\ninstead of going with the usual and general-purpose `HashMap` struct.\n\nThe `ArrayHashMap` struct creates a hashtable that is faster to iterate over.\nThat is why this specific type of hashtable might be valuable to you.\nSome other properties of a `ArrayHashMap` hashtable are:\n\n- the order of insertion is preserved, i.e., the order of the values that you find while iterating through this hashtable is actually the order in which these values were inserted in the hashtable.\n- the key-value pairs are stored sequentially, one after another.\n\n\nYou can create an `ArrayHashMap` object by using, once again, a helper function that\nchooses automatically for you a hash function implementation. This is the\n`AutoArrayHashMap()` function, which works very similarly to the `AutoHashMap()`\nfunction that we presented in @sec-hashmap.\n\nYou provide two data types to this function. The data type of the keys that will be\nused in this hashtable, and the data type of the values that will be stored in\nthis hashtable.\n\nAn `ArrayHashMap` object have essentially the exact same methods from the `HashMap` struct.\nSo you can insert new values into the hashtable by using the `put()` method, and you can look (or get)\na value from the hashtable by using the `get()` method. But the `remove()` method is not available\nin this specific type of hashtable.\n\nIn order to delete values from the hashtable, you would use the same methods that you find in\nan `ArrayList` object, i.e., a dynamic array. I presented these methods in @sec-dynamic-array-remove,\nwhich are the `swapRemove()` and `orderedRemove()` methods. These methods have the same meaning here, or,\nthe same effect that they have in an `ArrayList` object.\n\nThis means that, with `swapRemove()` you remove the value from the hashtable, but you do not preserve\nthe order in which the values were inserted into the structure. While `orderedRemove()` is able\nto retain the order in which these values were inserted.\n\nBut instead of providing an index as input to `swapRemove()` or `orderedRemove()`, like I described\nin @sec-dynamic-array-remove, these methods here in an `ArrayHashMap` take a key as input, like\nthe `remove()` method from a `HashMap` object. If you want to provide an index as input, instead\nof a key, you should use the `swapRemoveAt()` and `orderedRemoveAt()` methods.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar hash_table = AutoArrayHashMap(u32, u16)\n    .init(allocator);\ndefer hash_table.deinit();\n```\n:::\n\n\n\n\n\n\n### The `StringHashMap` hashtable {#sec-string-hash-map}\n\nOne thing that you will notice in the other two types of hashtables that I have\npresented over the last sections, is that neither of them accepts a slice data type\nin their keys.\nWhat this means is that you cannot use a slice value to represent a key in\nthese types of hashtable.\n\nThe most obvious consequence of this, is that you cannot use strings as keys\nin these hashtables. But it's extremely common to use strings as keys\nin hashtables.\n\nTake this very simple Javascript code snippet as an example. We are creating\na simple hashtable object named `people`. Then, we add a new entry to this\nhashtable, which is identified by the string `'Pedro'`. This string is the\nkey in this case, while the object containing different personal information such as\nage, height and city, is the value to be stored in the hashtable.\n\n```js\nvar people = new Object();\npeople['Pedro'] = {\n    'age': 25,\n    'height': 1.67,\n    'city': 'Belo Horizonte'\n};\n```\n\nThis pattern of using strings as keys is very common in\nall sorts of situations. That is why the Zig Standard Library offers a\nspecific type of hashtable for this purpose, which is created through the `StringHashMap()` function.\nThis function creates a hashtable that uses strings as keys. The only input of this\nfunction is the data type of the values that will be stored into this hashtable.\n\nIn the example below, I'm creating a hashtable to store the ages of different people.\nEach key in this hashtable is represented by the name of each person, while the value stored in the\nhashtable is the age of this person identified by the key.\n\nThat is why I provide the `u8` data type (which is the data type used by the age values) as input to this `StringHashMap()` function.\nAs the result, it creates a hashtable that uses string values as keys, and, that stores\n`u8` values in it. Notice that an allocator object is provided at the `init()` method of the\nresulting object from the `StringHashMap()` function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var ages = std.StringHashMap(u8).init(allocator);\n    defer ages.deinit();\n\n    try ages.put(\"Pedro\", 25);\n    try ages.put(\"Matheus\", 21);\n    try ages.put(\"Abgail\", 42);\n\n    var it = ages.iterator();\n    while (it.next()) |kv| {\n        std.debug.print(\"Key: {s} | \", .{kv.key_ptr.*});\n        std.debug.print(\"Age: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n:::\n\n\n\n\n```\nKey: Pedro | Age: 25\nKey: Abgail | Age: 42\nKey: Matheus | Age: 21\n```\n\n\n### The `StringArrayHashMap` hashtable\n\nThe Zig Standard Library also provides a type of hashtable that mix the cons and pros of the\n`StringHashMap` and `ArrayHashMap` together. That is, a hashtable\nthat uses strings as keys, but also have the advantages from `ArrayHashMap`.\nIn other words, you can have a hashtable that is fast to iterate over,\nthat preserves insertion order, and also, that uses strings as keys.\n\nYou can create such type of hashtable by using the `StringArrayHashMap()` function.\nThis function accepts a data type as input, which is the data type of the values that are\ngoing to be stored inside this hashtable, in the same style as the function presented\nin @sec-string-hash-map.\n\nYou can insert new values into this hashtable by using the same `put()` method that\nwe have discussed in @sec-string-hash-map. And you can also get values from the hashtable\nby using the same `get()` method.\nLike its `ArrayHashMap` brother, to delete values from this specific type of hashtable,\nwe also use the `orderedRemove()` and `swapRemove()` methods, with the same effects that\nI have described in @sec-array-map.\n\nIf we take the code example that was exposed in @sec-string-hash-map, we can\nachieve the exact same result with `StringArrayHashMap()`:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar ages = std.StringArrayHashMap(u8).init(allocator);\n```\n:::\n\n\n\n\n\n\n\n## Linked lists\n\nThe Zig Standard Library provides an implementation for both singly and doubly linked lists.\nA linked list is a linear data structure that looks like a chain, or, a rope.\nThe main advantage of this data structure is that you normally have very fast\ninsertion and deletion operations. But, as a disadvantage, iterating through\nthis data structure is usually not so fast as iterating through an array.\n\nThe idea behind a linked list is to build a structure that consists of a sequence of nodes\nconnected to each other by pointers. This means that linked lists are usually not contiguous\nin memory, because each node might be anywhere in memory. They do not need to be close to\none another.\n\nIn @fig-linked-list we can see a diagram of a singly linked list. We begin at the first node\n(which is usually called \"the head of the linked list\"). Then, from this\nfirst node we uncover the remaining nodes in the structure, by following the locations pointed\nby the pointers found in each node.\n\nEach node has two things in it. It has the value that is stored in the current node\n, and also, a pointer. This pointer points to the next node in the list. If this pointer\nis null, then, it means that we have reached the end of our linked list.\n\n![A diagram of a singly linked list.](./../Figures/linked-list.png){#fig-linked-list}\n\n\nIn @fig-linked-list2 we can see a diagram of a doubly linked list. The only thing that really\nchanges now is that every node in the linked list has both a pointer to the previous node,\nand, a pointer to the next node. So every node in a doubly linked list has two pointers in it. These are\nusually called the `prev` (for \"previous\") and the `next` (for \"next\") pointers of the node.\n\nIn the singly linked list example, we had only one single pointer in each node, and this singular\npointer was always pointing to the next node in the sequence. This means that singly linked lists\nnormally have only the `next` pointer in them.\n\n![A diagram of a doubly linked list.](./../Figures/doubly-linked-list.png){#fig-linked-list2}\n\n\nLinked lists are available in Zig through the functions `SinglyLinkedList()` and\n`DoublyLinkedList()`, for \"singly linked lists\" and \"doubly linked lists\", respectively. These functions are\nactually generic functions, which we are going to talk more about in @sec-generic-fun.\n\nFor now, just understand that, in order to create a linked list object,\nwe begin by providing a data type to these functions. This data type defines\nthe type of data that each node in this linked list will store. In the example below,\nwe are creating a singly linked list of `u32` values.\nSo each node in this linked list will store a `u32` value.\n\nBoth the `SinglyLinkedList()` and `DoublyLinkedList()` functions returns a type,\ni.e., a struct definition, as output. Therefore, the object `Lu32` is actually\na struct definition. It defines the type \"singly linked list of `u32` values\".\n\nNow that we have the definition of the struct, we need to instantiate a `Lu32` object.\nWe normally instantiate struct objects in Zig by using an `init()` method.\nBut in this case, we are instantiating the struct directly, by using an empty\n`struct` literal, in the expression `Lu32{}`.\n\nIn this example, we first create multiple node objects, and after we create them,\nwe start to insert and connect these nodes to build the linked list, using the\n`prepend()` and `insertAfter()` methods. Notice that the `prepend()` method\nis a method from the linked list object, while the `insertAfter()` is a method\npresent in the node objects.\n\nIn essence, the `prepend()` method inserts a node at the beginning of the linked\nlist. In other words, the node that you provide to this method, becomes the new\n\"head node\" of the linked list. It becomes the first node in the list (see @fig-linked-list).\n\nOn the other side, the `insertAfter()` method is used to basically connect two nodes together.\nWhen you provide a node to this method, it creates a pointer to this input node,\nand stores this pointer in the `next` attribute of the current node, from which the method was called from.\n\nBecause doubly linked lists have both a `next` and a `prev` attributes in each node\n(as described in @fig-linked-list2), a node object created from\na `DoublyLinkedList` object have both an `insertBefore()` (for `prev`)\nand an `insertAfter()` (for `next`) methods available.\n\nThus, if we have used a doubly linked list, we can use the `insertBefore()` method\nto store the pointer to the input node in the `prev` attribute. This would put the input\nnode as the \"previous node\", or, the node before the current node. In contrast, the `insertAfter()` method\nputs the pointer created to the input node in the `next` attribute of the current node,\nand as result, the input node becomes the \"next node\" of the current node.\n\nSince we are using a singly linked list in this example, we have only the `insertAfter()` method\navailable in the node objects that we create from our `Lu32` type.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SinglyLinkedList = std.SinglyLinkedList;\nconst Lu32 = SinglyLinkedList(u32);\n\npub fn main() !void {\n    var list = Lu32{};\n    var one = Lu32.Node{ .data = 1 };\n    var two = Lu32.Node{ .data = 2 };\n    var three = Lu32.Node{ .data = 3 };\n    var four = Lu32.Node{ .data = 4 };\n    var five = Lu32.Node{ .data = 5 };\n\n    list.prepend(&two); // {2}\n    two.insertAfter(&five); // {2, 5}\n    list.prepend(&one); // {1, 2, 5}\n    two.insertAfter(&three); // {1, 2, 3, 5}\n    three.insertAfter(&four); // {1, 2, 3, 4, 5}\n}\n```\n:::\n\n\n\n\n\nThere are other methods available from the linked list object, depending if this object is\na singly linked list or a doubly linked list, that might be very useful for you. You can find a\nsummary of them in the bullet points below:\n\n- `remove()` to remove a specific node from the linked list.\n- if singly linked list, `len()` to count how many nodes there is in the linked list.\n- if doubly linked list, checkout the `len` attribute to see how many nodes there is in the linked list.\n- if singly linked list, `popFirst()` to remove the first node (i.e., the \"head\") from the linked list.\n- if doubly linked list, `pop()` and `popFirst()` to remove the last and first nodes from the linked list, respectively.\n- if doubly linked list, `append()` to add a new node to end of the linked list (i.e., inverse of `prepend()`).\n\n\n\n## Multi array structure\n\nZig introduces a new data structure called `MultiArrayList()`. It's a different version of the dynamic array\nthat we have introduced in @sec-dynamic-array. The difference between this structure and the `ArrayList()`\nthat we know from @sec-dynamic-array, is that `MultiArrayList()` creates a separate dynamic array\nfor each field of the struct that you provide as input.\n\nConsider the following code example. We create a new custom struct called `Person`. This\nstruct contains three different data members, or, three different fields. As consequence,\nwhen we provide this `Person` data type as input to `MultiArrayList()`, this\ncreates a \"struct of three different arrays\" called `PersonArray`. In other words,\nthis `PersonArray` is a struct that contains three internal dynamic arrays in it.\nOne array for each field found in the `Person` struct definition.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Person = struct {\n    name: []const u8,\n    age: u8,\n    height: f32,\n};\nconst PersonArray = std.MultiArrayList(Person);\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var people = PersonArray{};\n    defer people.deinit(allocator);\n\n    try people.append(allocator, .{\n        .name = \"Auguste\", .age = 15, .height = 1.54\n    });\n    try people.append(allocator, .{\n        .name = \"Elena\", .age = 26, .height = 1.65\n    });\n    try people.append(allocator, .{\n        .name = \"Michael\", .age = 64, .height = 1.87\n    });\n}\n```\n:::\n\n\n\n\nIn other words, instead of creating an array of \"persons\", the `MultiArrayList()` function\ncreates a \"struct of arrays\". Each data member of this struct is a different array that stores\nthe values of a specific field from the `Person` values that were added (or, appended) to this \"struct of arrays\".\nOne important detail is that each of these separate internal arrays stored inside `PersonArray`\nare dynamic arrays. This means that these arrays can grow in capacity automatically as needed, to accomodate\nmore values.\n\nThe @fig-multi-array exposed below presents a diagram that describes the `PersonArray` struct\nthat we have created in the previous code example. Notice that the values of the data members\npresent in each of the three `Person` values that we have appended into the `PersonArray` object\n, are scattered across three different internal arrays of the `PersonArray` object.\n\n![A diagram of the `PersonArray` struct.](./../Figures/multi-array.png){#fig-multi-array}\n\nYou can easily access each of these arrays separately, and iterate over the values of each array.\nFor that, you will need to call the `items()` method from the `PersonArray` object, and provide as input\nto this method, the name of the field that you want to iterate over.\nIf you want to iterate through the `.age` array for example, then, you need to call `items(.age)` from\nthe `PersonArray` object, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (people.items(.age)) |*age| {\n    try stdout.print(\"Age: {d}\\n\", .{age.*});\n}\n```\n:::\n\n\n\n\n```\nAge: 15\nAge: 26\nAge: 64\n```\n\n\nIn the above example, we are iterating over the values of the `.age` array, or,\nthe internal array of the `PersonArray` object that contains the values of the `age`\ndata member from the `Person` values that were added to the multi array struct.\n\nIn this example we are calling the `items()` method directly from the `PersonArray`\nobject. However, in most situations it's recommened to call this `items()` method\nfrom a \"slice object\", which you can create from the `slice()` method.\nThe reason for this is that calling `items()` multiple times have better performance\nif you use a slice object.\n\nTherefore, if you are planning to access only one of the\ninternal arrays from your \"multi array struct\", it's fine to call `items()` directly\nfrom the multi array object. But if you need to access many of the internal arrays\nfrom your \"multi array struct\", then, you will likely need to call `items()` more\nthan once, and, in such circumstance, is better to call `items()` through a slice object.\nThe example below demonstrates the use of such object:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar slice = people.slice();\nfor (slice.items(.age)) |*age| {\n    age.* += 10;\n}\nfor (slice.items(.name), slice.items(.age)) |*n,*a| {\n    try stdout.print(\n        \"Name: {s}, Age: {d}\\n\", .{n.*, a.*}\n    );\n}\n```\n:::\n\n\n\n\n```\nName: Auguste, Age: 25\nName: Elena, Age: 36\nName: Michael, Age: 74\n```\n\n\n## Conclusion\n\nThere are many other data structures that I haven't presented here.\nBut you can check them out at the official Zig Standard Library documentation page.\nActually, when you get into the [homepage of the documentation](https://ziglang.org/documentation/master/std/#)[^home], the first thing\nthat appears to you in this page, is a list of types and data structures that\nare available in the Zig Standard Library.\nThere are some very specific data structures in this list, like a\n[`BoundedArray` struct](https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray)[^bounded]\n, but there is also some more general structures, such as a\n[`PriorityQueue` struct](https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue)[^priority].\n\n\n[^home]: <https://ziglang.org/documentation/master/std/#>\n[^priority]: <https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue>.\n[^bounded]: <https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray>\n",
+    "supporting": [
+      "09-data-structures_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/09-error-handling/execute-results/html.json b/_freeze/Chapters/09-error-handling/execute-results/html.json
index 39ca6f04..aaffaa3e 100644
--- a/_freeze/Chapters/09-error-handling/execute-results/html.json
+++ b/_freeze/Chapters/09-error-handling/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "0e6b825195db1ba992b740206fa34ec0",
+  "hash": "1ef4c69c6b1bfd8553723d38f6a46fb8",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Error handling and unions {#sec-error-handling}\n\nIn this chapter, I want to discuss how error handling is done in Zig.\nWe already briefly learned about one of the available strategies to handle errors in Zig,\nwhich is the `try` keyword presented at @sec-main-file. But we still haven't learned about\nthe other methods, such as the `catch` keyword.\nI also want to discuss in this chapter how union types are created in Zig.\n\n## Learning more about errors in Zig\n\nBefore we get into how error handling is done, we need to learn more about what errors are in Zig.\nAn error is actually a value in Zig [@zigoverview]. In other words, when an error occurs inside your Zig program,\nit means that somewhere in your Zig codebase, an error value is being generated.\nAn error value is similar to any integer value that you create in your Zig code.\nYou can take an error value and pass it as input to a function,\nand you can also cast (or coerce) it into a different type of an error value.\n\nThis have some similarities with exceptions in C++ and Python.\nBecause in C++ and Python, when an exception happens inside a `try` block,\nyou can use a `catch` block (in C++) or an `except` block (in Python)\nto capture the exception produced in the `try` block,\nand pass it to functions as an input.\n\nHowever, error values in Zig are treated very differently than exceptions.\nFirst, you cannot ignore error values in your Zig code. Meaning that, if an error\nvalue appears somewhere in your source code, this error value must be explicitly handled in some way.\nThis also means that you cannot discard error values by assigning them to an underscore,\nas you could do with normal values and objects.\n\nTake the source code below as an example. Here we are trying to open a file that does not exist\nin my computer, and as a result, an obvious error value of `FileNotFound` is returned from the `openFile()`\nfunction. But because I'm assigning the result of this function to an underscore, I end up\ntrying to discard an error value.\n\nThe `zig` compiler detects this mistake, and raises a compile\nerror telling me that I'm trying to discard an error value.\nIt also adds a note message that suggests the use of `try`,\n`catch` or an if statement to explicitly handle this error value\nThis note is reinforcing that every possible error value must be explicitly handled in Zig.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst dir = std.fs.cwd();\n_ = dir.openFile(\"doesnt_exist.txt\", .{});\n```\n:::\n\n\n\n\n```\nt.zig:8:17: error: error set is discarded\nt.zig:8:17: note: consider using 'try', 'catch', or 'if'\n```\n\n\n### Returning errors from functions\n\nAs we described at @sec-main-file, when we have a function that might return an error\nvalue, this function normally includes an exclamation mark (`!`) in its return type\nannotation. The presence of this exclamation mark indicates that this function might\nreturn an error value as result, and, the `zig` compiler forces you to always handle explicitly\nthe case of this function returning an error value.\n\nTake a look at the `print_name()` function below. This function might return an error in the `stdout.print()` function call,\nand, as a consequence, its return type (`!void`) includes an exclamation mark in it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_name() !void {\n    const stdout = std.getStdOut().writer();\n    try stdout.print(\"My name is Pedro!\", .{});\n}\n```\n:::\n\n\n\n\nIn the example above, we are using the exclamation mark to tell the `zig` compiler\nthat this function might return some error. But which error exactly is returned from\nthis function? For now, we are not specifying a specific error value. We only\nknown for now that some error value (whatever it is) might be returned.\n\nBut in fact, you can (if you want to) specify clearly which exact error values\nmight be returned from this function. There are lot of examples of\nthis in the Zig Standard Library. Take this `fill()` function from\nthe `http.Client` module as an example. This function returns\neither a error value of type `ReadError`, or `void`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn fill(conn: *Connection) ReadError!void {\n    // The body of this function ...\n}\n```\n:::\n\n\n\n\nThis idea of specifying the exact error values that you expect to be returned\nfrom the function is interesting. Because they automatically become some sort of documentation\nof your function, and also, it allows the `zig` compiler to perform some extra checks over\nyour code. Because it can check if there is any other type of error value\nthat is being generated inside your function, and, that it is not being accounted\nfor in this return type annotation.\n\nAnyway, you can list the types of errors that can be returned from the function\nby listing them on the left side of the exclamation mark. While the valid values\nstay on the right side of the exclamation mark. So the syntax format become:\n\n```\n<error-value>!<valid-value>\n```\n\n\n### Error sets\n\nBut what about when we have a single function that might return different types of errors?\nWhen you have such a function, you can list\nall of these different types of errors that can be returned from this function,\nthrough a structure in Zig that we call of an *error set*.\n\nAn error set is a special case of an union type. It is an union that contains error values in it.\nNot all programming languages have a notion of an \"union object\".\nBut in summary, an union is just a set of data types.\nUnions are used to allow an object to have multiple data types.\nFor example, a union of `x`, `y` and `z`, means that\nan object can be either of type `x`, or type `y` or type `z`.\n\nWe are going to talk in more depth about unions at @sec-unions.\nBut you can write an error set by writing the keyword `error` before\na pair of curly braces, then you list the error values that can be\nreturned from the function inside this pair of curly braces.\n\nTake the `resolvePath()` function below as an example, which comes from the\n`introspect.zig` module of the Zig Standard Library. We can see in its return type annotation, that this\nfunction return either: 1) a valid slice of `u8` values (`[]u8`); or, 2) one of the three different\ntypes of error values listed inside the error set (`OutOfMemory`, `Unexpected`, etc.).\nThis is an usage example of an error set.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn resolvePath(\n    ally: mem.Allocator,\n    p: []const u8,\n) error{\n    OutOfMemory,\n    CurrentWorkingDirectoryUnlinked,\n    Unexpected,\n}![]u8 {\n    // The body of the function ...\n}\n```\n:::\n\n\n\n\n\nThis is a valid way of annotating the return value of a Zig function. But, if you navigate through\nthe modules that composes the Zig Standard Library, you will notice that, for the majority of cases,\nthe programmers prefer to give a descriptive name to this error set, and then, use this name (or this \"label\")\nof the error set in the return type annotation, instead of using the error set directly.\n\nWe can see that in the `ReadError` error set that we showed earlier in the `fill()` function,\nwhich is defined in the `http.Client` module.\nSo yes, I presented the `ReadError` as if it was just a standard and single error value, but in fact,\nit is an error set defined in the `http.Client` module, and therefore, it actually represents\na set of different error values that might happen inside the `fill()` function.\n\n\nTake a look at the `ReadError` definition reproduced below. Notice that we are grouping all of these\ndifferent error values into a single object, and then, we use this object into the return type annotation of the function.\nLike the `fill()` function that we showed earlier, or, the `readvDirect()` function from the same module,\nwhich is reproduced below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const ReadError = error{\n    TlsFailure,\n    TlsAlert,\n    ConnectionTimedOut,\n    ConnectionResetByPeer,\n    UnexpectedReadFailure,\n    EndOfStream,\n};\n// Some lines of code\npub fn readvDirect(\n        conn: *Connection,\n        buffers: []std.posix.iovec\n    ) ReadError!usize {\n    // The body of the function ...\n}\n```\n:::\n\n\n\n\nSo, an error set is just a convenient way of grouping a set of\npossible error values into a single object, or a single type of an error value.\n\n\n### Casting error values\n\nLet's suppose you have two different error sets, named `A` and `B`.\nIf error set `A` is a superset of error set `B`, then, you can cast (or coerce)\nerror values from `B` into error values of `A`.\n\nError sets are just a set of error values. So, if the error set `A`\ncontains all error values from the error set `B`, then `A`\nbecomes a superset of `B`. You could also say\nthat the error set `B` is a subset of error set `A`.\n\nThe example below demonstrates this idea. Because `A` contains all\nvalues from `B`, `A` is a superset of `B`.\nIn math notation, we would say that $A \\supset B$.\nAs a consequence, we can give an error value from `B` as input to the `cast()`\nfunction, and, implicitly cast this input into the same error value, but from the `A` set.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst A = error{\n    ConnectionTimeoutError,\n    DatabaseNotFound,\n    OutOfMemory,\n    InvalidToken,\n};\nconst B = error {\n    OutOfMemory,\n};\n\nfn cast(err: B) A {\n    return err;\n}\n\ntest \"coerce error value\" {\n    const error_value = cast(B.OutOfMemory);\n    try std.testing.expect(\n        error_value == A.OutOfMemory\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filea64e1da1167c.test.coerce error value...OKA\n  All 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n## How to handle errors\n\nNow that we learned more about what errors are in Zig,\nlet's discuss the available strategies to handle these errors,\nwhich are:\n\n- `try` keyword;\n- `catch` keyword;\n- an if statement;\n- `errdefer` keyword;\n\n\n\n### What `try` means?\n\nAs I described over the previous sections, when we say that an expression might\nreturn an error, we are basically referring to an expression that have\na return type in the format `!T`.\nThe `!` indicates that this expression returns either an error value, or a value of type `T`.\n\nAt @sec-main-file, I presented the `try` keyword and where to use it.\nBut I did not talked about what exactly this keyword does to your code,\nor, in other words, I have not explained yet what `try` means in your code.\n\nIn essence, when you use the `try` keyword in an expression, you are telling\nthe `zig` compiler the following: \"Hey! Execute this expression for me,\nand, if this expression return an error, please, return this error for me\nand stop the execution of my program. But if this expression return a valid\nvalue, then, return this value, and move on\".\n\nIn other words, the `try` keyword is essentially, a strategy to enter in panic mode, and stop\nthe execution of your program in case an error occurs.\nWith the `try` keyword, you are telling the `zig` compiler, that stopping the execution\nof your program is the most reasonable strategy to take if an error occurs\nin that particular expression.\n\n### The `catch` keyword\n\nOk, now that we understand properly what `try` means, let's discuss `catch` now.\nOne important detail here, is that you can use `try` or `catch` to handle your errors,\nbut you **cannot use `try` and `catch` together**. In other words, `try` and `catch`\nare different and completely separate strategies in the Zig language.\n\nThis is uncommon, and different than what happens in other languages. Most\nprogramming languages that adopts the *try catch* pattern (such as C++, R, Python, Javascript, etc.), normally use\nthese two keywords together to form the complete logic to\nproperly handle the errors.\nAnyway, Zig tries a different approach in the *try catch* pattern.\n\nSo, we learned already about what `try` means, and we also known that both\n`try` and `catch` should be used alone, separate from each other. But\nwhat exactly `catch` do in Zig? With `catch`, we can construct a block of\nlogic to handle the error value, in case it happens in the current expression.\n\nLook at the code example below. Once again, we go back to the previous\nexample where we were trying to open a file that doesn't exist in my computer,\nbut this time, I use `catch` to actually implement a logic to handle the error, instead of\njust stopping the execution right away.\n\nMore specifically, in this example, I'm using a logger object to record some logs into\nthe system, before I return the error, and stop the execution of the program. For example,\nthis could be some part of the codebase of a complex system that I do not have full control over,\nand I want to record these logs before the program crashes, so that I can debug it later\n(e.g. maybe I cannot compile the full program, and properly debug it with a debugger. So, these logs might\nbe a valid strategy to surpass this barrier).\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst dir = std.fs.cwd();\nconst file = dir.openFile(\n    \"doesnt_exist.txt\", .{}\n) catch |err| {\n    logger.record_context();\n    logger.log_error(err);\n    return err;\n};\n```\n:::\n\n\n\n\n\nTherefore, we use `catch` to create a block of expressions that will handle the error.\nI can return the error value from this block of expressions, like I did in the above example,\nwhich, will make the program enter in panic mode, and, stop the execution.\nBut I could also, return a valid value from this block of code, which would\nbe stored in the `file` object.\n\nNotice that, instead of writing the keyword before the expression that might return the error,\nlike we do with `try`, we write `catch` after the expression. We can open the pair of pipes (`|`),\nwhich captures the error value returned by the expression, and makes\nthis error value available in the scope of the `catch` block as the object named `err`.\nIn other words, because I wrote `|err|` in the code, I can access the error value\nreturned by the expression, by using the `err` object.\n\nAlthough this being the most common use of `catch`, you can also use this keyword\nto handle the error in a \"default value\" style. That is, if the expression returns\nan error, we use the default value instead. Otherwise, we use the valid value returned\nby the expression.\n\nThe Zig official language reference, provides a great example of this \"default value\"\nstrategy with `catch`. This example is reproduced below. Notice that we are trying to parse\nsome unsigned integer from a string object named `str`. In other words, this function\nis trying to transform an object of type `[]const u8` (i.e. an array of characters, a string, etc.)\ninto an object of type `u64`.\n\nBut this parsing process done by the function `parseU64()` may fail, resulting in a runtime error.\nThe `catch` keyword used in this example provides an alternative value (13) to be used in case\nthis `parseU64()` function raises an error. So, the expression below essentially means:\n\"Hey! Please, parse this string into a `u64` for me, and store the results into the\nobject `number`. But, if an error occurs, then, use the value `13` instead\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number = parseU64(str, 10) catch 13;\n```\n:::\n\n\n\n\nSo, at the end of this process, the object `number` will contain either a `u64` integer\nthat was parsed successfully from the input string `str`, or, if an error occurs in the\nparsing process, it will contain the `u64` value `13` that was provided by the `catch`\nkeyword as the \"default\", or, the \"alternative\" value.\n\n\n\n### Using if statements\n\nNow, you can also use if statements to handle errors in your Zig code.\nIn the example below, I'm reproducing the previous example, where\nwe try to parse an integer value from an input string with a function\nnamed `parseU64()`.\n\nWe execute the expression inside the \"if\". If this expression returns an\nerror value, the \"if branch\" (or, the \"true branch\") of the if statement is not executed.\nBut if this expression returns a valid value instead, then, this value is unwrapped\ninto the `number` object.\n\nThis means that, if the `parseU64()` expression returns a valid value, this value becomes available\ninside the scope of this \"if branch\" (i.e. the \"true branch\") through the object that we listed inside the pair\nof pipe character (`|`), which is the object `number`.\n\nIf an error occurs, we can use an \"else branch\" (or the \"false branch\") of the if statement\nto handle the error. In the example below, we are using the `else` in the if statement\nto unwrap the error value (that was returned by `parseU64()`) into the `err` object,\nand handle the error.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (parseU64(str, 10)) |number| {\n    // do something with `number` here\n} else |err| {\n    // handle the error value.\n}\n```\n:::\n\n\n\n\nNow, if the expression that you are executing returns different types of error values,\nand you want to take a different action in each of these types of error values, the\n`try` and `catch` keywords, and the if statement strategy, becomes limited.\n\nFor this type of situation, the official documentation of the language suggests\nthe use of a switch statement together with an if statement [@zigdocs].\nThe basic idea is, to use the if statement to execute the expression, and\nuse the \"else branch\" to pass the error value to a switch statement, where\nyou define a different action for each type of error value that might be\nreturned by the expression executed in the if statement.\n\nThe example below demonstrates this idea. We first try to add (or register) a set of\ntasks to a queue. If this \"registration process\" occurs well, we then try\nto distribute these tasks across the workers of our system. But\nif this \"registration process\" returns an error value, we then use a switch\nstatement in the \"else branch\" to handle each possible error value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (add_tasks_to_queue(&queue, tasks)) |_| {\n    distribute_tasks(&queue);\n} else |err| switch (err) {\n    error.InvalidTaskName => {\n        // do something\n    },\n    error.TimeoutTooBig => {\n        // do something\n    },\n    error.QueueNotFound => {\n        // do something\n    },\n    // and all the other error options ...\n}\n```\n:::\n\n\n\n\n\n### The `errdefer` keyword {#sec-errdefer2}\n\nA common pattern in C programs in general, is to clean resources when an error occurs during\nthe execution of the program. In other words, one common way to handle errors, is to perform\n\"cleanup actions\" before we exit our program. This guarantees that a runtime error does not make\nour program to leak resources of the system.\n\n\nThe `errdefer` keyword is a tool to perform such \"cleanup actions\" in hostile situations.\nThis keyword is commonly used to clean (or to free) allocated resources, before the execution of our program\nget's stopped because of an error value being generated.\n\nThe basic idea is to provide an expression to the `errdefer` keyword. Then,\n`errdefer` executes this expression if, and only if, an error occurs\nduring the execution of the current scope.\nIn the example below, we are using an allocator object (that we have presented at @sec-allocators)\nto create a new `User` object. If we are successful in creating and registering this new user,\nthis `create_user()` function will return this new `User` object as its return value.\n\nHowever, if for some reason, an error value is generated by some expression\nthat is after the `errdefer` line, for example, in the `db.add(user)` expression,\nthe expression registered by `errdefer` get's executed before the error value is returned\nfrom the function, and before the program enters in panic mode and stops the\ncurrent execution.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn create_user(db: Database, allocator: Allocator) !User {\n    const user = try allocator.create(User);\n    errdefer allocator.destroy(user);\n\n    // Register new user in the Database.\n    _ = try db.register_user(user);\n    return user;\n}\n```\n:::\n\n\n\n\nBy using `errdefer` to destroy the `user` object that we have just created,\nwe guarantee that the memory allocated for this `user` object\nget's freed, before the execution of the program stops.\nBecause if the expression `try db.add(user)` returns an error value,\nthe execution of our program stops, and we lose all references and control over the memory\nthat we have allocated for the `user` object.\nAs a result, if we do not free the memory associated with the `user` object before the program stops,\nwe cannot free this memory anymore. We simply lose our chance to do the right thing.\nThat is why `errdefer` is essential in this situation.\n\nJust to state clearly the differences between `defer` and `errdefer`\n(which I described at @sec-defer and @sec-errdefer1), it might be worth\nto discuss the subject a bit further. You might still have the question\n\"why use `errdefer` if we can use `defer` instead?\" in your mind.\n\nAlthough being similar, the key difference between `errdefer` and `defer` keyword\nis when the provided expression get's executed.\nThe `defer` keyword always execute the provided expression at the end of the\ncurrent scope, no matter how your code exits this scope.\nIn contrast, `errdefer` executes the provided expression only when an error occurs in the\ncurrent scope.\n\nThis becomes important if a resource that you allocate in the\ncurrent scope get's freed later in your code, in a different scope.\nThe `create_user()` functions is an example of this. If you think\nclosely about this function, you will notice that this function returns\nthe `user` object as the result.\n\nIn other words, the allocated memory for the `user` object does not get\nfreed inside the `create_user()` function, if it returns successfully.\nSo, if an error does not occur inside this function, the `user` object\nis returned from the function, and probably, the code that runs after\nthis `create_user()` function will be responsible for freeing\nthe memory of the `user` object.\n\nBut what if an error occurs inside the `create_user()` function? What happens then?\nThis would mean that the execution of your code would stop in this `create_user()`\nfunction, and, as a consequence, the code that runs after this `create_user()`\nfunction would simply not run, and, as a result, the memory of the `user` object\nwould not be freed before your program stops.\n\nThis is the perfect scenario for `errdefer`. We use this keyword to guarantee\nthat our program will free the allocated memory for the `user` object,\neven if an error occurs inside the `create_user()` function.\n\nIf you allocate and free some memory for an object inside the same scope, then,\njust use `defer` and be happy, i.e. `errdefer` have no use for you in such situation.\nBut if you allocate some memory in a scope A, but you only free this memory\nlater, in a scope B for example, then, `errdefer` becomes useful to avoid leaking memory\nin sketchy situations.\n\n\n\n## Union type in Zig {#sec-unions}\n\nAn union type defines a set of types that an object can be. It is like a list of\noptions. Each option is a type that an object can assume. Therefore, unions in Zig\nhave the same meaning, or, the same role as unions in C. They are used for the same purpose.\nYou could also say that unions in Zig produces a similar effect to\n[using `typing.Union` in Python](https://docs.python.org/3/library/typing.html#typing.Union)[^pyunion].\n\n[^pyunion]: <https://docs.python.org/3/library/typing.html#typing.Union>\n\nFor example, you might be creating an API that sends data to a data lake, hosted\nin some private cloud infrastructure. Suppose you have created different structs in your codebase,\nto store the necessary information that you need, in order to connect to the services of\neach mainstream data lake service (Amazon S3, Azure Blob, etc.).\n\nNow, suppose you also have a function named `send_event()` that receives an event as input,\nand, a target data lake, and it sends the input event to the data lake specified in the\ntarget data lake argument. But this target data lake could be any of the three mainstream data lakes\nservices (Amazon S3, Azure Blob, etc.). Here is where an union can help you.\n\nThe union `LakeTarget` defined below allows the `lake_target` argument of `send_event()`\nto be either an object of type `AzureBlob`, or type `AmazonS3`, or type `GoogleGCP`.\nThis union allows the `send_event()` function to receive an object of any of these three types\nas input in the `lake_target` argument.\n\nRemember that each of these three types (`AmazonS3`, `GoogleGCP` and `AzureBlob`)\nare separate structs that we have defined in our source code. So, at first glance,\nthey are separate data types in our source code. But is the `union` keyword that\nunifies them into a single data type called `LakeTarget`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst LakeTarget = union {\n    azure: AzureBlob,\n    amazon: AmazonS3,\n    google: GoogleGCP,\n};\n\nfn send_event(\n    event: Event,\n    lake_target: LakeTarget\n) bool {\n    // body of the function ...\n}\n```\n:::\n\n\n\n\nAn union definition is composed by a list of data members. Each data member is of a specific data type.\nIn the example above, the `LakeTarget` union have three data members (`azure`, `amazon`, `google`).\nWhen you instantiate an object that uses an union type, you can only use one of its data members\nin this instantiation.\n\nYou could also interpret this as: only one data member of an union type can be activated at a time, the other data\nmembers remain deactivated and unaccessible. For example, if you create a `LakeTarget` object that uses\nthe `azure` data member, you can no longer use or access the data members `google` or `amazon`.\nIt is like if these other data members didn't exist at all in the `LakeTarget` type.\n\nYou can see this logic in the example below. Notice that, we first instantiate the union\nobject using the `azure` data member. As a result, this `target` object contains only\nthe `azure` data member inside of it. Only this data member is active in this object.\nThat is why the last line in this code example is invalid. Because we are trying to instantiate the data member\n`google`, which is currently inactive for this `target` object, and as a result, the program\nenters in panic mode warning us about this mistake through a loud error message.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar target = LakeTarget {\n    .azure = AzureBlob.init()\n};\n// Only the `azure` data member exist inside\n// the `target` object, and, as a result, this\n// line below is invalid:\ntarget.google = GoogleGCP.init();\n```\n:::\n\n\n\n\n```\nthread 2177312 panic: access of union field 'google' while\n    field 'azure' is active:\n    target.google = GoogleGCP.init();\n          ^\n```\n\nSo, when you instantiate an union object, you must choose one of the data types (or, one of the data members)\nlisted in the union type. In the example above, I choose to use the `azure` data member, and, as a result,\nall other data members were automatically deactivated,\nand you can no longer use them after you instantiate the object.\n\nYou can activate another data member by completely redefining the entire enum object.\nIn the example below, I initially use the `azure` data member. But then, I redefine the\n`target` object to use a new `LakeTarget` object, which uses the `google` data member.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar target = LakeTarget {\n    .azure = AzureBlob.init()\n};\ntarget = LakeTarget {\n    .google = GoogleGCP.init()\n};\n```\n:::\n\n\n\n\nA curious fact about union types, is that, at first, you cannot use them in switch statements (which were presented at @sec-switch).\nIn other words, if you have an object of type `LakeTarget` for example, you cannot give this object\nas input to a switch statement.\n\nBut what if you really need to do so? What if you actually need to\nprovide an \"union object\" to a switch statement? The answer to this question relies on another special type in Zig,\nwhich are the *tagged unions*. To create a tagged union, all you have to do is to add\nan enum type into your union declaration.\n\nAs an example of a tagged union in Zig, take the `Registry` type exposed\nbelow. This type comes from the\n[`grammar.zig` module](https://github.com/ziglang/zig/blob/30b4a87db711c368853b3eff8e214ab681810ef9/tools/spirv/grammar.zig)[^grammar]\nfrom the Zig repository. This union type lists different types of registries.\nBut notice this time, the use of `(enum)` after the `union` keyword. This is what makes\nthis union type a tagged union. By being a tagged union, an object of this `Registry` type\ncan be used as input in a switch statement. This is all you have to do. Just add `(enum)`\nto your `union` declaration, and you can use it in switch statements.\n\n[^grammar]: <https://github.com/ziglang/zig/blob/30b4a87db711c368853b3eff8e214ab681810ef9/tools/spirv/grammar.zig>.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const Registry = union(enum) {\n    core: CoreRegistry,\n    extension: ExtensionRegistry,\n};\n```\n:::\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Error handling and unions {#sec-error-handling}\n\nIn this chapter, I want to discuss how error handling is done in Zig.\nWe already briefly learned about one of the available strategies to handle errors in Zig,\nwhich is the `try` keyword presented in @sec-main-file. But we still haven't learned about\nthe other methods, such as the `catch` keyword.\nI also want to discuss in this chapter how union types are created in Zig.\n\n## Learning more about errors in Zig\n\nBefore we get into how error handling is done, we need to learn more about what errors are in Zig.\nAn error is actually a value in Zig [@zigoverview]. In other words, when an error occurs inside your Zig program,\nit means that somewhere in your Zig codebase, an error value is being generated.\nAn error value is similar to any integer value that you create in your Zig code.\nYou can take an error value and pass it as input to a function,\nand you can also cast (or coerce) it into a different type of an error value.\n\nThis have some similarities with exceptions in C++ and Python.\nBecause in C++ and Python, when an exception happens inside a `try` block,\nyou can use a `catch` block (in C++) or an `except` block (in Python)\nto capture the exception produced in the `try` block,\nand pass it to functions as an input.\n\nHowever, error values in Zig are treated very differently than exceptions.\nFirst, you cannot ignore error values in your Zig code. Meaning that, if an error\nvalue appears somewhere in your source code, this error value must be explicitly handled in some way.\nThis also means that you cannot discard error values by assigning them to an underscore,\nas you could do with normal values and objects.\n\nTake the source code below as an example. Here we are trying to open a file that does not exist\nin my computer, and as a result, an obvious error value of `FileNotFound` is returned from the `openFile()`\nfunction. But because I'm assigning the result of this function to an underscore, I end up\ntrying to discard an error value.\n\nThe `zig` compiler detects this mistake, and raises a compile\nerror telling me that I'm trying to discard an error value.\nIt also adds a note message that suggests the use of `try`,\n`catch` or an if statement to explicitly handle this error value\nThis note is reinforcing that every possible error value must be explicitly handled in Zig.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst dir = std.fs.cwd();\n_ = dir.openFile(\"doesnt_exist.txt\", .{});\n```\n:::\n\n\n\n\n```\nt.zig:8:17: error: error set is discarded\nt.zig:8:17: note: consider using 'try', 'catch', or 'if'\n```\n\n\n### Returning errors from functions\n\nAs we described in @sec-main-file, when we have a function that might return an error\nvalue, this function normally includes an exclamation mark (`!`) in its return type\nannotation. The presence of this exclamation mark indicates that this function might\nreturn an error value as result, and, the `zig` compiler forces you to always handle explicitly\nthe case of this function returning an error value.\n\nTake a look at the `print_name()` function below. This function might return an error in the `stdout.print()` function call,\nand, as a consequence, its return type (`!void`) includes an exclamation mark in it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_name() !void {\n    const stdout = std.getStdOut().writer();\n    try stdout.print(\"My name is Pedro!\", .{});\n}\n```\n:::\n\n\n\n\nIn the example above, we are using the exclamation mark to tell the `zig` compiler\nthat this function might return some error. But which error exactly is returned from\nthis function? For now, we are not specifying a specific error value. For now,\nwe only know that some error value (whatever it is) might be returned.\n\nBut in fact, you can (if you want to) specify clearly which exact error values\nmight be returned from this function. There are lot of examples of\nthis in the Zig Standard Library. Take this `fill()` function from\nthe `http.Client` module as an example. This function returns\neither a error value of type `ReadError`, or `void`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn fill(conn: *Connection) ReadError!void {\n    // The body of this function ...\n}\n```\n:::\n\n\n\n\nThis idea of specifying the exact error values that you expect to be returned\nfrom the function is interesting. Because they automatically become some sort of documentation\nof your function, and also, this allows the `zig` compiler to perform some extra checks over\nyour code. Because the compiler can check if there is any other type of error value\nthat is being generated inside your function, and, that it's not being accounted\nfor in this return type annotation.\n\nAnyway, you can list the types of errors that can be returned from the function\nby listing them on the left side of the exclamation mark. While the valid values\nstay on the right side of the exclamation mark. So the syntax format become:\n\n```\n<error-value>!<valid-value>\n```\n\n\n### Error sets\n\nBut what about when we have a single function that might return different types of errors?\nWhen you have such a function, you can list\nall of these different types of errors that can be returned from this function,\nthrough a structure in Zig that we call of an *error set*.\n\nAn error set is a special case of a union type. It's a union that contains error values in it.\nNot all programming languages have a notion of a \"union object\".\nBut in summary, a union is just a set of data types.\nUnions are used to allow an object to have multiple data types.\nFor example, a union of `x`, `y` and `z`, means that\nan object can be either of type `x`, or type `y` or type `z`.\n\nWe are going to talk in more depth about unions in @sec-unions.\nBut you can write an error set by writing the keyword `error` before\na pair of curly braces, then you list the error values that can be\nreturned from the function inside this pair of curly braces.\n\nTake the `resolvePath()` function below as an example, which comes from the\n`introspect.zig` module of the Zig Standard Library. We can see in its return type annotation, that this\nfunction return either: 1) a valid slice of `u8` values (`[]u8`); or, 2) one of the three different\ntypes of error values listed inside the error set (`OutOfMemory`, `Unexpected`, etc.).\nThis is an usage example of an error set.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn resolvePath(\n    ally: mem.Allocator,\n    p: []const u8,\n) error{\n    OutOfMemory,\n    CurrentWorkingDirectoryUnlinked,\n    Unexpected,\n}![]u8 {\n    // The body of the function ...\n}\n```\n:::\n\n\n\n\n\nThis is a valid way of annotating the return value of a Zig function. But, if you navigate through\nthe modules that composes the Zig Standard Library, you will notice that, for the majority of cases,\nthe programmers prefer to give a descriptive name to this error set, and then, use this name (or this \"label\")\nof the error set in the return type annotation, instead of using the error set directly.\n\nWe can see that in the `ReadError` error set that we showed earlier in the `fill()` function,\nwhich is defined in the `http.Client` module.\nSo yes, I presented the `ReadError` as if it was just a standard and single error value, but in fact,\nit's an error set defined in the `http.Client` module, and therefore, it actually represents\na set of different error values that might happen inside the `fill()` function.\n\n\nTake a look at the `ReadError` definition reproduced below. Notice that we are grouping all of these\ndifferent error values into a single object, and then, we use this object into the return type annotation of the function.\nLike the `fill()` function that we showed earlier, or, the `readvDirect()` function from the same module,\nwhich is reproduced below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const ReadError = error{\n    TlsFailure,\n    TlsAlert,\n    ConnectionTimedOut,\n    ConnectionResetByPeer,\n    UnexpectedReadFailure,\n    EndOfStream,\n};\n// Some lines of code\npub fn readvDirect(\n        conn: *Connection,\n        buffers: []std.posix.iovec\n    ) ReadError!usize {\n    // The body of the function ...\n}\n```\n:::\n\n\n\n\nSo, an error set is just a convenient way of grouping a set of\npossible error values into a single object, or a single type of an error value.\n\n\n### Casting error values\n\nLet's suppose you have two different error sets, named `A` and `B`.\nIf error set `A` is a superset of error set `B`, then, you can cast (or coerce)\nerror values from `B` into error values of `A`.\n\nError sets are just a set of error values. So, if the error set `A`\ncontains all error values from the error set `B`, then `A`\nbecomes a superset of `B`. You could also say\nthat the error set `B` is a subset of error set `A`.\n\nThe example below demonstrates this idea. Because `A` contains all\nvalues from `B`, `A` is a superset of `B`.\nIn math notation, we would say that $A \\supset B$.\nAs a consequence, we can give an error value from `B` as input to the `cast()`\nfunction, and, implicitly cast this input into the same error value, but from the `A` set.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst A = error{\n    ConnectionTimeoutError,\n    DatabaseNotFound,\n    OutOfMemory,\n    InvalidToken,\n};\nconst B = error {\n    OutOfMemory,\n};\n\nfn cast(err: B) A {\n    return err;\n}\n\ntest \"coerce error value\" {\n    const error_value = cast(B.OutOfMemory);\n    try std.testing.expect(\n        error_value == A.OutOfMemory\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file826379a872a1.test.coerce error value...OKA\n  All 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n## How to handle errors\n\nNow that we learned more about what errors are in Zig,\nlet's discuss the available strategies to handle these errors,\nwhich are:\n\n- `try` keyword;\n- `catch` keyword;\n- an if statement;\n- `errdefer` keyword;\n\n\n\n### What `try` means?\n\nAs I described over the previous sections, when we say that an expression might\nreturn an error, we are basically referring to an expression that have\na return type in the format `!T`.\nThe `!` indicates that this expression returns either an error value, or a value of type `T`.\n\nIn @sec-main-file, I presented the `try` keyword and where to use it.\nBut I did not talked about what exactly this keyword does to your code,\nor, in other words, I have not explained yet what `try` means in your code.\n\nIn essence, when you use the `try` keyword in an expression, you are telling\nthe `zig` compiler the following: \"Hey! Execute this expression for me,\nand, if this expression return an error, please, return this error for me\nand stop the execution of my program. But if this expression return a valid\nvalue, then, return this value, and move on\".\n\nIn other words, the `try` keyword is essentially, a strategy to enter in panic mode, and stop\nthe execution of your program in case an error occurs.\nWith the `try` keyword, you are telling the `zig` compiler, that stopping the execution\nof your program is the most reasonable strategy to take if an error occurs\nin that particular expression.\n\n### The `catch` keyword\n\nOk, now that we understand properly what `try` means, let's discuss `catch` now.\nOne important detail here, is that you can use `try` or `catch` to handle your errors,\nbut you **cannot use `try` and `catch` together**. In other words, `try` and `catch`\nare different and completely separate strategies in the Zig language.\n\nThis is uncommon, and different than what happens in other languages. Most\nprogramming languages that adopts the *try catch* pattern (such as C++, R, Python, Javascript, etc.), normally use\nthese two keywords together to form the complete logic to\nproperly handle the errors.\nAnyway, Zig tries a different approach in the *try catch* pattern.\n\nSo, we learned already about what `try` means, and we also known that both\n`try` and `catch` should be used alone, separate from each other. But\nwhat exactly `catch` do in Zig? With `catch`, we can construct a block of\nlogic to handle the error value, in case it happens in the current expression.\n\nLook at the code example below. Once again, we go back to the previous\nexample where we were trying to open a file that doesn't exist in my computer,\nbut this time, I use `catch` to actually implement a logic to handle the error, instead of\njust stopping the execution right away.\n\nMore specifically, in this example, I'm using a logger object to record some logs into\nthe system, before I return the error, and stop the execution of the program. For example,\nthis could be some part of the codebase of a complex system that I do not have full control over,\nand I want to record these logs before the program crashes, so that I can debug it later\n(e.g. maybe I cannot compile the full program, and properly debug it with a debugger. So, these logs might\nbe a valid strategy to surpass this barrier).\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst dir = std.fs.cwd();\nconst file = dir.openFile(\n    \"doesnt_exist.txt\", .{}\n) catch |err| {\n    logger.record_context();\n    logger.log_error(err);\n    return err;\n};\n```\n:::\n\n\n\n\n\nTherefore, we use `catch` to create a block of expressions that will handle the error.\nI can return the error value from this block of expressions, like I did in the above example,\nwhich, will make the program enter in panic mode, and, stop the execution.\nBut I could also, return a valid value from this block of code, which would\nbe stored in the `file` object.\n\nNotice that, instead of writing the keyword before the expression that might return the error,\nlike we do with `try`, we write `catch` after the expression. We can open the pair of pipes (`|`),\nwhich captures the error value returned by the expression, and makes\nthis error value available in the scope of the `catch` block as the object named `err`.\nIn other words, because I wrote `|err|` in the code, I can access the error value\nreturned by the expression, by using the `err` object.\n\nAlthough this being the most common use of `catch`, you can also use this keyword\nto handle the error in a \"default value\" style. That is, if the expression returns\nan error, we use the default value instead. Otherwise, we use the valid value returned\nby the expression.\n\nThe Zig official language reference, provides a great example of this \"default value\"\nstrategy with `catch`. This example is reproduced below. Notice that we are trying to parse\nsome unsigned integer from a string object named `str`. In other words, this function\nis trying to transform an object of type `[]const u8` (i.e., an array of characters, a string, etc.)\ninto an object of type `u64`.\n\nBut this parsing process done by the function `parseU64()` may fail, resulting in a runtime error.\nThe `catch` keyword used in this example provides an alternative value (13) to be used in case\nthis `parseU64()` function raises an error. So, the expression below essentially means:\n\"Hey! Please, parse this string into a `u64` for me, and store the results into the\nobject `number`. But, if an error occurs, then, use the value `13` instead\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number = parseU64(str, 10) catch 13;\n```\n:::\n\n\n\n\nSo, at the end of this process, the object `number` will contain either a `u64` integer\nthat was parsed successfully from the input string `str`, or, if an error occurs in the\nparsing process, it will contain the `u64` value `13` that was provided by the `catch`\nkeyword as the \"default\", or, the \"alternative\" value.\n\n\n\n### Using if statements\n\nNow, you can also use if statements to handle errors in your Zig code.\nIn the example below, I'm reproducing the previous example, where\nwe try to parse an integer value from an input string with a function\nnamed `parseU64()`.\n\nWe execute the expression inside the \"if\". If this expression returns an\nerror value, the \"if branch\" (or, the \"true branch\") of the if statement is not executed.\nBut if this expression returns a valid value instead, then, this value is unwrapped\ninto the `number` object.\n\nThis means that, if the `parseU64()` expression returns a valid value, this value becomes available\ninside the scope of this \"if branch\" (i.e., the \"true branch\") through the object that we listed inside the pair\nof pipe character (`|`), which is the object `number`.\n\nIf an error occurs, we can use an \"else branch\" (or the \"false branch\") of the if statement\nto handle the error. In the example below, we are using the `else` in the if statement\nto unwrap the error value (that was returned by `parseU64()`) into the `err` object,\nand handle the error.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (parseU64(str, 10)) |number| {\n    // do something with `number` here\n} else |err| {\n    // handle the error value.\n}\n```\n:::\n\n\n\n\nNow, if the expression that you are executing returns different types of error values,\nand you want to take a different action in each of these types of error values, the\n`try` and `catch` keywords, and the if statement strategy, becomes limited.\n\nFor this type of situation, the official documentation of the language suggests\nthe use of a switch statement together with an if statement [@zigdocs].\nThe basic idea is, to use the if statement to execute the expression, and\nuse the \"else branch\" to pass the error value to a switch statement, where\nyou define a different action for each type of error value that might be\nreturned by the expression executed in the if statement.\n\nThe example below demonstrates this idea. We first try to add (or register) a set of\ntasks to a queue. If this \"registration process\" occurs well, we then try\nto distribute these tasks across the workers of our system. But\nif this \"registration process\" returns an error value, we then use a switch\nstatement in the \"else branch\" to handle each possible error value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (add_tasks_to_queue(&queue, tasks)) |_| {\n    distribute_tasks(&queue);\n} else |err| switch (err) {\n    error.InvalidTaskName => {\n        // do something\n    },\n    error.TimeoutTooBig => {\n        // do something\n    },\n    error.QueueNotFound => {\n        // do something\n    },\n    // and all the other error options ...\n}\n```\n:::\n\n\n\n\n\n### The `errdefer` keyword {#sec-errdefer2}\n\nA common pattern in C programs in general, is to clean resources when an error occurs during\nthe execution of the program. In other words, one common way to handle errors, is to perform\n\"cleanup actions\" before we exit our program. This guarantees that a runtime error does not make\nour program to leak resources of the system.\n\n\nThe `errdefer` keyword is a tool to perform such \"cleanup actions\" in hostile situations.\nThis keyword is commonly used to clean (or to free) allocated resources, before the execution of our program\ngets stopped because of an error value being generated.\n\nThe basic idea is to provide an expression to the `errdefer` keyword. Then,\n`errdefer` executes this expression if, and only if, an error occurs\nduring the execution of the current scope.\nIn the example below, we are using an allocator object (that we have presented in @sec-allocators)\nto create a new `User` object. If we are successful in creating and registering this new user,\nthis `create_user()` function will return this new `User` object as its return value.\n\nHowever, if for some reason, an error value is generated by some expression\nthat is after the `errdefer` line, for example, in the `db.add(user)` expression,\nthe expression registered by `errdefer` gets executed before the error value is returned\nfrom the function, and before the program enters in panic mode and stops the\ncurrent execution.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn create_user(db: Database, allocator: Allocator) !User {\n    const user = try allocator.create(User);\n    errdefer allocator.destroy(user);\n\n    // Register new user in the Database.\n    _ = try db.register_user(user);\n    return user;\n}\n```\n:::\n\n\n\n\nBy using `errdefer` to destroy the `user` object that we have just created,\nwe guarantee that the memory allocated for this `user` object\ngets freed, before the execution of the program stops.\nBecause if the expression `try db.add(user)` returns an error value,\nthe execution of our program stops, and we lose all references and control over the memory\nthat we have allocated for the `user` object.\nAs a result, if we do not free the memory associated with the `user` object before the program stops,\nwe cannot free this memory anymore. We simply lose our chance to do the right thing.\nThat is why `errdefer` is essential in this situation.\n\nJust to state clearly the differences between `defer` and `errdefer`\n(which I described in @sec-defer and @sec-errdefer1), it might be worth\nto discuss the subject a bit further. You might still have the question\n\"why use `errdefer` if we can use `defer` instead?\" in your mind.\n\nAlthough being similar, the key difference between `errdefer` and `defer` keyword\nis when the provided expression gets executed.\nThe `defer` keyword always execute the provided expression at the end of the\ncurrent scope, no matter how your code exits this scope.\nIn contrast, `errdefer` executes the provided expression only when an error occurs in the\ncurrent scope.\n\nThis becomes important if a resource that you allocate in the\ncurrent scope gets freed later in your code, in a different scope.\nThe `create_user()` functions is an example of this. If you think\nclosely about this function, you will notice that this function returns\nthe `user` object as the result.\n\nIn other words, the allocated memory for the `user` object does not get\nfreed inside the `create_user()` function, if it returns successfully.\nSo, if an error does not occur inside this function, the `user` object\nis returned from the function, and probably, the code that runs after\nthis `create_user()` function will be responsible for freeing\nthe memory of the `user` object.\n\nBut what if an error occurs inside the `create_user()` function? What happens then?\nThis would mean that the execution of your code would stop in this `create_user()`\nfunction, and, as a consequence, the code that runs after this `create_user()`\nfunction would simply not run, and, as a result, the memory of the `user` object\nwould not be freed before your program stops.\n\nThis is the perfect scenario for `errdefer`. We use this keyword to guarantee\nthat our program will free the allocated memory for the `user` object,\neven if an error occurs inside the `create_user()` function.\n\nIf you allocate and free some memory for an object inside the same scope, then,\njust use `defer` and be happy, i.e., `errdefer` have no use for you in such situation.\nBut if you allocate some memory in a scope A, but you only free this memory\nlater, in a scope B for example, then, `errdefer` becomes useful to avoid leaking memory\nin sketchy situations.\n\n\n\n## Union type in Zig {#sec-unions}\n\nA union type defines a set of types that an object can be. It's like a list of\noptions. Each option is a type that an object can assume. Therefore, unions in Zig\nhave the same meaning, or, the same role as unions in C. They are used for the same purpose.\nYou could also say that unions in Zig produces a similar effect to\n[using `typing.Union` in Python](https://docs.python.org/3/library/typing.html#typing.Union)[^pyunion].\n\n[^pyunion]: <https://docs.python.org/3/library/typing.html#typing.Union>\n\nFor example, you might be creating an API that sends data to a data lake, hosted\nin some private cloud infrastructure. Suppose you have created different structs in your codebase,\nto store the necessary information that you need, in order to connect to the services of\neach mainstream data lake service (Amazon S3, Azure Blob, etc.).\n\nNow, suppose you also have a function named `send_event()` that receives an event as input,\nand, a target data lake, and it sends the input event to the data lake specified in the\ntarget data lake argument. But this target data lake could be any of the three mainstream data lakes\nservices (Amazon S3, Azure Blob, etc.). Here is where an union can help you.\n\nThe union `LakeTarget` defined below allows the `lake_target` argument of `send_event()`\nto be either an object of type `AzureBlob`, or type `AmazonS3`, or type `GoogleGCP`.\nThis union allows the `send_event()` function to receive an object of any of these three types\nas input in the `lake_target` argument.\n\nRemember that each of these three types (`AmazonS3`, `GoogleGCP` and `AzureBlob`)\nare separate structs that we have defined in our source code. So, at first glance,\nthey are separate data types in our source code. But is the `union` keyword that\nunifies them into a single data type called `LakeTarget`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst LakeTarget = union {\n    azure: AzureBlob,\n    amazon: AmazonS3,\n    google: GoogleGCP,\n};\n\nfn send_event(\n    event: Event,\n    lake_target: LakeTarget\n) bool {\n    // body of the function ...\n}\n```\n:::\n\n\n\n\nAn union definition is composed by a list of data members. Each data member is of a specific data type.\nIn the example above, the `LakeTarget` union have three data members (`azure`, `amazon`, `google`).\nWhen you instantiate an object that uses an union type, you can only use one of its data members\nin this instantiation.\n\nYou could also interpret this as: only one data member of an union type can be activated at a time, the other data\nmembers remain deactivated and unaccessible. For example, if you create a `LakeTarget` object that uses\nthe `azure` data member, you can no longer use or access the data members `google` or `amazon`.\nIt's like if these other data members didn't exist at all in the `LakeTarget` type.\n\nYou can see this logic in the example below. Notice that, we first instantiate the union\nobject using the `azure` data member. As a result, this `target` object contains only\nthe `azure` data member inside of it. Only this data member is active in this object.\nThat is why the last line in this code example is invalid. Because we are trying to instantiate the data member\n`google`, which is currently inactive for this `target` object, and as a result, the program\nenters in panic mode warning us about this mistake through a loud error message.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar target = LakeTarget {\n    .azure = AzureBlob.init()\n};\n// Only the `azure` data member exist inside\n// the `target` object, and, as a result, this\n// line below is invalid:\ntarget.google = GoogleGCP.init();\n```\n:::\n\n\n\n\n```\nthread 2177312 panic: access of union field 'google' while\n    field 'azure' is active:\n    target.google = GoogleGCP.init();\n          ^\n```\n\nSo, when you instantiate an union object, you must choose one of the data types (or, one of the data members)\nlisted in the union type. In the example above, I choose to use the `azure` data member, and, as a result,\nall other data members were automatically deactivated,\nand you can no longer use them after you instantiate the object.\n\nYou can activate another data member by completely redefining the entire enum object.\nIn the example below, I initially use the `azure` data member. But then, I redefine the\n`target` object to use a new `LakeTarget` object, which uses the `google` data member.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar target = LakeTarget {\n    .azure = AzureBlob.init()\n};\ntarget = LakeTarget {\n    .google = GoogleGCP.init()\n};\n```\n:::\n\n\n\n\nA curious fact about union types, is that, at first, you cannot use them in switch statements (which were presented in @sec-switch).\nIn other words, if you have an object of type `LakeTarget` for example, you cannot give this object\nas input to a switch statement.\n\nBut what if you really need to do so? What if you actually need to\nprovide an \"union object\" to a switch statement? The answer to this question relies on another special type in Zig,\nwhich are the *tagged unions*. To create a tagged union, all you have to do is to add\nan enum type into your union declaration.\n\nAs an example of a tagged union in Zig, take the `Registry` type exposed\nbelow. This type comes from the\n[`grammar.zig` module](https://github.com/ziglang/zig/blob/30b4a87db711c368853b3eff8e214ab681810ef9/tools/spirv/grammar.zig)[^grammar]\nfrom the Zig repository. This union type lists different types of registries.\nBut notice this time, the use of `(enum)` after the `union` keyword. This is what makes\nthis union type a tagged union. By being a tagged union, an object of this `Registry` type\ncan be used as input in a switch statement. This is all you have to do. Just add `(enum)`\nto your `union` declaration, and you can use it in switch statements.\n\n[^grammar]: <https://github.com/ziglang/zig/blob/30b4a87db711c368853b3eff8e214ab681810ef9/tools/spirv/grammar.zig>.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const Registry = union(enum) {\n    core: CoreRegistry,\n    extension: ExtensionRegistry,\n};\n```\n:::\n",
+    "supporting": [
+      "09-error-handling_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/10-stack-project/execute-results/html.json b/_freeze/Chapters/10-stack-project/execute-results/html.json
index 2bc7f08f..398f20fc 100644
--- a/_freeze/Chapters/10-stack-project/execute-results/html.json
+++ b/_freeze/Chapters/10-stack-project/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "0c651ab91f56f6b099ea4bfebc8882dd",
+  "hash": "fe2d7fa4c6d4bcadd97ff3ab647083a0",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 3 - Building a stack data structure\n\nIn this chapter we are going to implement a stack data structure as our next small project\nin this book. Implementing basic data structures in any language is kind of a\n\"kindergarten task\" (if this term even exist) in computer science (CS), because\nwe normally learn and implement them in the first semesters of CS.\n\nBut this is actually good! Since this should be a very easy task, we don't need much to explain\nwhat a stack is, then, we can concentrate on what is really important here, which is learning\nhow the concept of \"generics\" is implemented in the Zig language, and how one of the key\nfeatures of Zig, which is comptime, works, and use the stack data structure to demonstrate\nthese concepts on the fly.\n\nBut before we get into building the stack data structure, we first need to understand\nwhat the `comptime` keyword does to your code, and after that, we also need to learn about\nhow generics work in Zig.\n\n\n## Understanding `comptime` in Zig {#sec-comptime}\n\nOne of the key features of Zig is `comptime`. This keyword introduces a whole\nnew concept and paradigm, that is tightly connected with the compilation process.\nAt @sec-compile-time we have described the importance and the role that \"compile-time versus runtime\"\nplays into Zig. At that section, we learned that the rules applied to a value/object change\na lot depending on whether this value is known at compile-time, or just at runtime.\n\nThe `comptime` keyword is strongly related to these two spaces in time (compile-time and runtime).\nLet's quickly recap the differences. Compile-time is the period of time when your\nZig source code is being compiled by the `zig` compiler, while the runtime is\nthe period of time when your Zig program is being executed, i.e. when we execute\nthe binary files that were generated by the `zig` compiler.\n\nThere are three ways in which you can apply the `comptime` keyword, which are:\n\n- apply `comptime` on a function argument.\n- apply `comptime` on an object.\n- apply `comptime` on a block of expressions.\n\n\n\n### Applying over a function argument\n\nWhen you apply the `comptime` keyword on a function argument, you are saying to the `zig` compiler\nthat the value assigned to that particular function argument must be known at compile-time.\nWe explained in details at @sec-compile-time what exactly \"value known at compile-time\" means, so,\nin case you have doubts about this idea, come back to that section.\n\nNow let's think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement\nto that particular function argument. If the programmer accidentally tries to give a value to this\nfunction argument that is not known at compile time, the `zig` compiler will notice this problem, and\nas a consequence, it will raise a compilation error saying that it cannot compile your program. Because\nyou are providing a value that is \"runtime known\" to a function argument that must be \"compile-time known\".\n\nTake a look at this very simple example below, where we define a `twice()` function, that simply\ndoubles the input value named `num`. Notice that we use the `comptime` keyword before the name\nof the function argument. This keyword is marking the function argument `num` as a \"comptime argument\".\n\nThat is a function argument whose value must be compile-time known. This is why the expression\n`twice(5678)` is valid, and no compilation errors are raised. Because the value `5678`\nis compile-time known, so this is the expected behaviour for this function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filea72d248f97f8.test.test comptime...OKAll 1 \n   tests passed.\n```\n\n\n:::\n:::\n\n\n\n\nBut what if we provide a number that is not compile-time known to this function?\nFor example, we might provide a different input value to this function depending\non the target OS of our compilation process. The code example below demonstrates such case.\n\nBecause the value of the object `n` is determined at runtime, we cannot provide this object\nas input to the `twice()` function. The `zig` compiler will not allow it, because we marked\nthe `num` argument as a \"comptime argument\". That is why the `zig` compiler raises\nthe compile-time error exposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    var n: u32 = undefined;\n    if (builtin.target.os.tag == .windows) {\n        n = 1234;\n    } else {\n        n = 5678;\n    }\n    _ = twice(n);\n}\n```\n:::\n\n\n\n\n```\nt.zig:12:16: error: runtime-known argument passed to comptime parameter \n```\n\nComptime arguments are frequently used on functions that return some sort\nof generic structure. In fact, `comptime` is the essence (or the basis) to make generics in Zig.\nWe are going to talk more about generics at @sec-generics.\n\nFor now, let's take a look at this code example from @karlseguin_generics. You\ncan see that this `IntArray()` function have one argument named `length`.\nThis argument is marked as comptime, and receives a value of type `usize` as input. So the value given to this argument\nmust be compile-time known.\nWe can also see that this function returns an array of `i64` values as output.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n```\n:::\n\n\n\n\nNow, the key component of this function is the `length` argument. This argument\nis used to determine the size of the array that is produced by the function. Let's\nthink about the consequences of that. If the size of the array is dependent on\nthe value assigned to the `length` argument, this means that the data type of the\noutput of the function depends on the value of this `length` argument.\n\nLet this statement sink for a bit in your mind. As I described at @sec-root-file,\nZig is a strongly-typed language, especially on function declarations.\nSo every time we write a function in Zig, we have to annotate the data type of\nthe value returned by the function. But how can we do that, if this data type\ndepends on the value given to the argument of the function?\n\nThink about this for a second. If `length` is equal to 3 for example, then, the\nreturn type of the function is `[3]i64`. But if `length` is equal to 40, then,\nthe return type becomes `[40]i64`. At this point the `zig` compiler would be confused,\nand raise a compilation error, saying something like this:\n\n> Hey! You have annotated that this function should return a `[3]i64` value, but I got a `[40]i64` value instead! This doesn't look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when\nthe `type` keyword comes in. This `type` keyword is basically saying to the\n`zig` compiler that this function will return some data type as output, but it doesn't know yet\nwhat exactly data type that is. We will talk more about this at @sec-generics.\n\n\n\n### Applying over an expression\n\nWhen you apply the `comptime` keyword over an expression, then, it is guaranteed that the `zig` compiler will\nexecute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time\n(e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the `zig` compiler\nwill raise a compilation error.\n\nTake this example from the official documentation of Zig [@zigdocs]. We\nare executing the same `fibonacci()` function both at runtime, and, at compile-time.\nThe function is by default executed at runtime, but because we use the `comptime`\nkeyword at the second \"try expression\", this expression is executed at compile-time.\n\nThis might be a bit confusing for some people. Yes! When I say that this expression\nis executed at compile-time, I mean that this expression is compiled and executed\nwhile the `zig` compiler is compiling your Zig source code.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filea72d3cf7abe2.test.fibonacci...OKAll 1 test\n  ts passed.\n```\n\n\n:::\n:::\n\n\n\n\nA lot of your Zig source code might be potentially executed at compile-time,\nbecause the `zig` compiler can figure it out the output of some expressions.\nEspecially if these expressions depends only at compile-time known values.\nWe have talked about this at @sec-compile-time.\n\nBut when you use the `comptime` keyword on an expression, there is no \"it might be executed\nat compile-time\" anymore. With the `comptime` keyword you are ordering the `zig` compiler\nto execute this expression at compile-time. You are imposing this rule, it is guaranteed\nthat the compiler will always execute it at compile-time. Or, at least, the compiler\nwill try to execute it. If the compiler cannot execute the expression for whatever reason,\nthe compiler will raise a compilation error.\n\n\n### Applying over a block\n\nBlocks were described at @sec-blocks. When you apply the `comptime` keyword over a\nblock of expressions, you get essentially the same effect when you apply this keyword to\na single expression. That is, the entire block of expressions is executed at\ncompile-time by the `zig` compiler.\n\nIn the example below, we mark the block labeled of `blk` as a comptime block,\nand, therefore, the expressions inside this block are executed at compile-time.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filea72d6353d586.test.fibonacci in a block...O\n  OKAll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## Introducing Generics {#sec-generics}\n\nFirst of all, what is a generic? Generic is the idea to allow a type\n(`f64`, `u8`, `u32`, `bool`, and also, user-defined types, like the `User` struct\nthat we defined at @sec-structs-and-oop) to be a parameter to methods, classes and\ninterfaces [@geeks_generics]. In other words, a \"generic\" is a class (or a method) that can work\nwith multiple data types.\n\nFor example, in Java, generics are created through the operator `<>`. With this operator,\na Java class is capable of receiving a data type as input, and therefore, the class can fit\nits features according to this input data type.\nAs another example, generics in C++ are supported through the concept of templates.\nClass templates in C++ are generics.\n\nIn Zig, generics are implemented through `comptime`. The `comptime` keyword\nallows us to collect a data type at compile time, and pass this data type as\ninput to a piece of code.\n\n\n### A generic function {#sec-generic-fun}\n\nTake the `max()` function exposed below as a first example.\nThis function is essentially a \"generic function\".\nIn this function, we have a comptime function argument named `T`.\nNotice that this `T` argument have a data type of `type`. Weird right? This `type` keyword is the\n\"father of all types\", or, \"the type of types\" in Zig.\n\nBecause we have used this `type` keyword in the `T` argument, we are telling\nthe `zig` compiler that this `T` argument will receive some data type as input.\nAlso notice the use of the `comptime` keyword in this argument.\nAs I described at @sec-comptime, every time you use this keyword in a function argument,\nthis means that the value of this argument must be known at compile-time.\nThis makes sense, right? Because there is no data type that is not known at compile-time.\n\nThink about this. Every data type that you will ever write is always\nknown at compile-time. Especially because data types are an essential\ninformation for the compiler to actually compile your source code.\nHaving this in mind, makes sense to mark this argument as a comptime argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\n```\n:::\n\n\n\n\nAlso notice that the value of the `T` argument is actually used\nto define the data type of the other arguments in the function, `a` and `b`, and also at the\nreturn type annotation of the function.\nThat is, the data type of these arguments (`a` and `b`), and, the return data type of the function itself,\nare determined by the input value given to the `T` argument.\n\nAs a result, we have a generic function that works with different data types.\nFor example, I can provide `u8` values to this `max()` function, and it will work as expected.\nBut if I provide `f64` values instead, it will also work as expected.\nWithout a generic function, I would have to write a different `max()` function\nfor each one of the data types that I wanted to use.\nThis generic function provides a very useful shortcut for us.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\ntest \"test max\" {\n    const n1 = max(u8, 4, 10);\n    std.debug.print(\"Max n1: {d}\\n\", .{n1});\n    const n2 = max(f64, 89.24, 64.001);\n    std.debug.print(\"Max n2: {d}\\n\", .{n2});\n}\n```\n:::\n\n\n\n\n```\nMax n1: 10\nMax n2: 89.24\n```\n\n\n### A generic data structure {#sec-generic-struct}\n\nEvery data structure that you find in the Zig Standard Library (e.g. `ArrayList`, `HashMap`, etc.)\nis essentially a generic data structure.\nThese data structures are generic in the sense that they work with any data type you want.\nYou just say which is the data type of the values that are going to be stored in this data\nstructure, and they just work as expected.\n\nA generic data structure in Zig is how you replicate a generic class from Java,\nor, a class template from C++. But you may quest yourself: how do we build a\ngeneric data structure in Zig?\n\nThe basic idea is to write a generic function that creates the data structure definition\nfor the specific type we want. In other words, this generic function behaves as a \"factory of data structures\".\nThe generic function outputs the `struct` definition that defines this data structure for a\nspecific data type.\n\nTo create such function, we need to add a comptime argument to this function that receives a data type\nas input. We already learned how to do this at the previous section (@sec-generic-fun).\nI think the best way to demonstrate how to create a generic data structure is to actually write one.\nThis where we go into our next small project in this book. This one is a very small project,\nwhich is to write a generic stack data structure.\n\n\n\n\n## What is a stack? {#sec-what-stack}\n\nA stack data structure is a structure that follows a LIFO (*last in, first out*) principle.\nOnly two operations are normally supported in a stack data structure, which are `push` and `pop`.\nThe `push` operation is used to add new values to the stack, while `pop` is used to remove\nvalues from the stack.\n\nWhen people try to explain how the stack data structure works, the most common analogy\nthat they use is a stack of plates. Imagine that you have a stack of plates,\nfor example, a stack of 10 plates in your table. Each plate represents a value that\nis currently stored in this stack.\n\nWe begin with a stack of 10 different values, or 10 different plates. Now, imagine that you want to\nadd a new plate (or a new value) to this stack, which translates to the `push` operation.\nYou would add this plate (or this value) by just putting the new plate\non the top of the stack. Then, you would increase the stack to 11 plates.\n\nBut how would you remove plates (or remove values) from this stack (a.k.a. the `pop` operation) ?\nTo do that, we would have to remove the plate on the top of the stack, and, as a result, we would\nhave, once again, 10 plates in the stack.\n\nThis demonstrates the LIFO concept, because the first plate in the stack, which is the plate\nin the bottom of the stack, is always the last plate to get out of the stack. Think about it. In order\nto remove this specific plate from the stack, we have to remove all plates in the\nstack. So every operation in the stack, either insertion or deletion, is always made at the top of the stack.\nThe @fig-stack below exposes this logic visually:\n\n![A diagram of a stack structure. Source: Wikipedia, the free encyclopedia.](./../Figures/lifo-stack.svg){#fig-stack}\n\n\n\n## Writing the stack data structure\n\nWe are going to write the stack data structure in two steps. First, we are going\nto implement a stack that can only store `u32` values. Then, after that, we are going\nto extend our implementation to make it generic, so that it works with any data type\nwe want.\n\nFirst, we need to decide how the values will be stored inside the stack. There are multiple\nways to implement the storage behind a stack structure. Some people prefer to use a doubly linked list,\nsome others prefer to use a dynamic array, etc. In this example we are going to use an array behind the hood,\nto store the values in the stack, which is the `items` data member of our `Stack` struct definition.\n\nAlso notice in our `Stack` struct that we have three other data members: `capacity`, `length` and `allocator`.\nThe `capacity` member contains the capacity of the underlying array that stores the values in the stack.\nThe `length` contains the number of values that are currently being stored in the stack.\nAnd the `allocator` contains the allocator object that will be used by the stack structure whenever it\nneeds to allocate more space for the values that are being stored.\n\nWe begin by defining an `init()` method of this struct, which is going to be\nresponsible for instantiating a `Stack` object. Notice that, inside this\n`init()` method, we start by allocating an array with the capacity specified\nin the `capacity` argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst Stack = struct {\n    items: []u32,\n    capacity: usize,\n    length: usize,\n    allocator: Allocator,\n\n    pub fn init(allocator: Allocator, capacity: usize) !Stack {\n        var buf = try allocator.alloc(u32, capacity);\n        return .{\n            .items = buf[0..],\n            .capacity = capacity,\n            .length = 0,\n            .allocator = allocator,\n        };\n    }\n};\n```\n:::\n\n\n\n\n\n### Implementing the `push` operation\n\nNow that we have written the basic logic to create a new `Stack` object,\nwe can start writing the logic responsible for performing a push operation.\nRemember, a push operation in a stack data structure is the operation\nresponsible for adding a new value to the stack.\n\nSo how can we add a new value to the `Stack` object that we have?\nThe `push()` function exposed below is a possible answer to this question.\nRemember from what we discussed at @sec-what-stack that values are always added to the top of the stack.\nThis means that this `push()` function must always find the element in the underlying array\nthat currently represents the top position of the stack, and then, add the input value there.\n\nFirst, we have an if statement in this function. This if statement is\nchecking whether we need to expand the underlying array to store\nthis new value that we are adding to the stack. In other words, maybe\nthe underlying array does not have enough capacity to store this new\nvalue, and, in this case, we need to expand our array to get the capacity that we need.\n\nSo, if the logical test in this if statement returns true, it means that the array\ndoes not have enough capacity, and we need to expand it before we store this new value.\nSo inside this if statement we are executing the necessary expressions to expand the underlying array.\nNotice that we use the allocator object to allocate a new array that is twice as bigger\nthan the current array (`self.capacity * 2`).\n\nAfter that, we use a different built-in function named `@memcpy()`. This built-in function\nis equivalent to the `memcpy()` function from the C Standard Library[^cmemcpy]. It is used to\ncopy the values from one block of memory to another block of memory. In other words,\nyou can use this function to copy the values from one array into another array.\n\n[^cmemcpy]: <https://www.tutorialspoint.com/c_standard_library/c_function_memcpy.htm>\n\nWe are using this `@memcpy()` built-in function to copy the values that are currently stored\nin the underlying array of the stack object (`self.items`) into our new and bigger array that\nwe have allocated (`new_buf`). After we execute this function, the `new_buf` contains a copy\nof the values that are present at `self.items`.\n\nNow that we have secured a copy of our current values in the `new_buf` object, we\ncan now free the memory currently allocated at `self.items`. After that, we just need\nto assign our new and bigger array to `self.items`. This is the sequence\nof steps necessary to expand our array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn push(self: *Stack, val: u32) !void {\n    if ((self.length + 1) > self.capacity) {\n        var new_buf = try self.allocator.alloc(\n            u32, self.capacity * 2\n        );\n        @memcpy(\n            new_buf[0..self.capacity], self.items\n        );\n        self.allocator.free(self.items);\n        self.items = new_buf;\n        self.capacity = self.capacity * 2;\n    }\n\n    self.items[self.length] = val;\n    self.length += 1;\n}\n```\n:::\n\n\n\n\nAfter we make sure that we have enough room to store this new value\nthat we are adding to the stack, all we have to do is to assign\nthis value to the top element in this stack, and, increase the\nvalue of the `length` attribute by one. We find the top element\nin the stack by using the `length` attribute.\n\n\n\n### Implementing the `pop` operation\n\nNow we can implement the pop operation of our stack object.\nThis is a much easier operation to implement, and the `pop()` method below summarises\nall the logic that is needed.\n\nWe just have to find the element in the underlying array that currently represents the top\nof the stack, and set this element to \"undefined\", to indicate that\nthis element is \"empty\". After that, we also need to decrease\nthe `length` attribute of the stack by one.\n\nIf the current length of the stack is zero, it means that there is\nno values being stored in the stack currently. So, in this case,\nwe could just return from the function and do nothing really.\nThis is what the if statement inside this function is checking for.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn pop(self: *Stack) void {\n    if (self.length == 0) return;\n\n    self.items[self.length - 1] = undefined;\n    self.length -= 1;\n}\n```\n:::\n\n\n\n\n\n\n### Implementing the `deinit` method\n\nWe have implemented the methods responsible for the two main operations\nassociated with the stack data structure, which is `pop()` and `push()`,\nand we also have implemented the method responsible for instantiating\na new `Stack` object, which is the `init()` method.\n\nBut now, we need to implement also the method responsible for destroying\na `Stack` object. In Zig, this task is commonly associated with the method\nnamed `deinit()`. Most struct objects in Zig have such method, and it\nis commonly nicknamed \"the destructor method\".\n\nIn theory, all we have to do to destroy the `Stack` object is to make\nsure that we free the allocated memory for the underlying array, using\nthe allocator object that is stored inside the `Stack` object.\nThis is what the `deinit()` method below is doing.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn deinit(self: *Stack) void {\n    self.allocator.free(self.items);\n}\n```\n:::\n\n\n\n\n\n\n\n## Making it generic\n\nNow that we have implemented the basic skeleton of our stack data structure,\nwe can now focus on discussing how can we make it generic. How can we make\nthis basic skeleton to work not only with `u32` values, but also, with any other\ndata type we want?\nFor example, we might need to create a stack object to store `User` values\nin it. How can we make this possible? The answer lies on the use of generics\nand `comptime`.\n\nAs I described at @sec-generic-struct, the basic idea is to write a generic\nfunction that returns a struct definition as output.\nIn theory, we do not need much to transform our `Stack` struct into a generic\ndata structure. All that we need to do is to transform the underlying array\nof the stack into a generic array.\n\nIn other words, this underlying array needs to be a \"chameleon\". It needs to adapt,\nand transform it into an array of any data type that we want. For example, if we need to create\na stack that will store `u8` values, then, this underlying array needs to be\na `u8` array (i.e. `[]u8`). But if we need to store `User` values instead, then,\nthis array needs to be a `User` array (i.e. `[]User`). Etc.\n\nWe do that by using a generic function. Because a generic function can receive a data type\nas input, and we can pass this data type to the struct definition of our `Stack` object.\nTherefore, we can use the generic function to create a `Stack` object that can store\nthe data type we want. If we want to create a stack structure that stores `User` values,\nwe pass the `User` data type to this generic function, and it will create for us\nthe struct definition that describes a `Stack` object that can store `User` values in it.\n\nLook at the code example below. I have omitted some parts of the `Stack` struct definition\nfor brevity reasons. However, if a specific part of our `Stack` struct is not exposed here\nin this example, then it is because this part did not change from the previous example.\nIt remains the same.\n\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn Stack(comptime T: type) type {\n    return struct {\n        items: []T,\n        capacity: usize,\n        length: usize,\n        allocator: Allocator,\n        const Self = @This();\n\n        pub fn init(allocator: Allocator,\n                    capacity: usize) !Stack(T) {\n            var buf = try allocator.alloc(T, capacity);\n            return .{\n                .items = buf[0..],\n                .capacity = capacity,\n                .length = 0,\n                .allocator = allocator,\n            };\n        }\n\n        pub fn push(self: *Self, val: T) !void {\n        // Truncate the rest of the struct\n    };\n}\n```\n:::\n\n\n\n\nNotice that we have created a function in this example named `Stack()`. This function\ntakes a type as input, and passes this type to the struct definition of our\n`Stack` object. The data member `items` is now, an array of type `T`, which is the\ndata type that we have provided as input to the function. The function argument\n`val` in the `push()` function is now a value of type `T` too.\n\nWe can just provide a data type to this function, and it will create a definition of a\n`Stack` object that can store values of the data type that we have provided. In the example below, we are creating\nthe definition of a\n`Stack` object that can store `u8` values in it. This definition is stored at the `Stacku8` object.\nThis `Stacku8` object becomes our new struct, it is the struct that we are going to use\nto create our `Stack` object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst Stacku8 = Stack(u8);\nvar stack = try Stacku8.init(allocator, 10);\ndefer stack.deinit();\ntry stack.push(1);\ntry stack.push(2);\ntry stack.push(3);\ntry stack.push(4);\ntry stack.push(5);\ntry stack.push(6);\n\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\"Stack capacity: {d}\\n\", .{stack.capacity});\n\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\n    \"Stack state: {any}\\n\",\n    .{stack.items[0..stack.length]}\n);\n```\n:::\n\n\n\n\n```\nStack len: 6\nStack capacity: 10\nStack len: 5\nStack len: 4\nStack state: { 1, 2, 3, 4, 0, 0, 0, 0, 0, 0 }\n```\n\nEvery generic data structure in the Zig Standard Library (`ArrayList`, `HashMap`, `SinlyLinkedList`, etc.)\nis implemented through this logic. They use a generic function to create the struct definition that can work\nwith the data type that you provided as input.\n\n\n\n\n## Conclusion\n\nThe full source code of the stack structure discussed in this chapter is freely available at the official\nrepository of this book. Just checkout the [`stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig)[^zig-stack]\nfor the `u32` version of our stack,\nand the [`generic_stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig)[^zig-stack2]\nfor the generic version, available inside the `ZigExamples` folder of the repository.\n\n\n[^zig-stack]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig>\n[^zig-stack2]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig>\n\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 3 - Building a stack data structure\n\nIn this chapter we are going to implement a stack data structure as our next small project\nin this book. Implementing basic data structures in any language is kind of a\n\"kindergarten task\" (if this term even exist) in computer science (CS), because\nwe normally learn and implement them in the first semesters of CS.\n\nBut this is actually good! Since this should be a very easy task, we don't need much to explain\nwhat a stack is, then, we can concentrate on what is really important here, which is learning\nhow the concept of \"generics\" is implemented in the Zig language, and how one of the key\nfeatures of Zig, which is comptime, works, and use the stack data structure to demonstrate\nthese concepts on the fly.\n\nBut before we get into building the stack data structure, we first need to understand\nwhat the `comptime` keyword does to your code, and after that, we also need to learn about\nhow generics work in Zig.\n\n\n## Understanding `comptime` in Zig {#sec-comptime}\n\nOne of the key features of Zig is `comptime`. This keyword introduces a whole\nnew concept and paradigm, that is tightly connected with the compilation process.\nIn @sec-compile-time we have described the importance and the role that \"compile-time versus runtime\"\nplays into Zig. In that section, we learned that the rules applied to a value/object change\na lot depending on whether this value is known at compile-time, or just at runtime.\n\nThe `comptime` keyword is strongly related to these two spaces in time (compile-time and runtime).\nLet's quickly recap the differences. Compile-time is the period of time when your\nZig source code is being compiled by the `zig` compiler, while the runtime is\nthe period of time when your Zig program is being executed, i.e., when we execute\nthe binary files that were generated by the `zig` compiler.\n\nThere are three ways in which you can apply the `comptime` keyword, which are:\n\n- apply `comptime` on a function argument.\n- apply `comptime` on an object.\n- apply `comptime` on a block of expressions.\n\n\n\n### Applying over a function argument\n\nWhen you apply the `comptime` keyword on a function argument, you are saying to the `zig` compiler\nthat the value assigned to that particular function argument must be known at compile-time.\nWe explained in detail in @sec-compile-time what exactly \"value known at compile-time\" means. So\nif you have any doubts about this idea, refer back to that section.\n\nNow let's think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement\nto that particular function argument. If the programmer accidentally tries to give a value to this\nfunction argument that is not known at compile time, the `zig` compiler will notice this problem, and\nas a consequence, it will raise a compilation error saying that it cannot compile your program. Because\nyou are providing a value that is \"runtime known\" to a function argument that must be \"compile-time known\".\n\nTake a look at this very simple example below, where we define a `twice()` function, that simply\ndoubles the input value named `num`. Notice that we use the `comptime` keyword before the name\nof the function argument. This keyword is marking the function argument `num` as a \"comptime argument\".\n\nThat is a function argument whose value must be compile-time known. This is why the expression\n`twice(5678)` is valid, and no compilation errors are raised. Because the value `5678`\nis compile-time known, so this is the expected behaviour for this function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file833f3ad20be9.test.test comptime...OKAll 1 \n   tests passed.\n```\n\n\n:::\n:::\n\n\n\n\nBut what if we provide a number that is not compile-time known to this function?\nFor example, we might provide a different input value to this function depending\non the target OS of our compilation process. The code example below demonstrates such case.\n\nBecause the value of the object `n` is determined at runtime, we cannot provide this object\nas input to the `twice()` function. The `zig` compiler will not allow it, because we marked\nthe `num` argument as a \"comptime argument\". That is why the `zig` compiler raises\nthe compile-time error exposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    var n: u32 = undefined;\n    if (builtin.target.os.tag == .windows) {\n        n = 1234;\n    } else {\n        n = 5678;\n    }\n    _ = twice(n);\n}\n```\n:::\n\n\n\n\n```\nt.zig:12:16: error: runtime-known argument passed to comptime parameter\n```\n\nComptime arguments are frequently used on functions that return some sort\nof generic structure. In fact, `comptime` is the essence (or the basis) to make generics in Zig.\nWe are going to talk more about generics in @sec-generics.\n\nFor now, let's take a look at this code example from @karlseguin_generics. You\ncan see that this `IntArray()` function has one argument named `length`.\nThis argument is marked as comptime, and receives a value of type `usize` as input. So the value given to this argument\nmust be compile-time known.\nWe can also see that this function returns an array of `i64` values as output.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n```\n:::\n\n\n\n\nNow, the key component of this function is the `length` argument. This argument\nis used to determine the size of the array that is produced by the function. Let's\nthink about the consequences of that. If the size of the array is dependent on\nthe value assigned to the `length` argument, this means that the data type of the\noutput of the function depends on the value of this `length` argument.\n\nLet this statement sink for a bit in your mind. As I described in @sec-root-file,\nZig is a strongly-typed language, especially on function declarations.\nSo every time we write a function in Zig, we have to annotate the data type of\nthe value returned by the function. But how can we do that, if this data type\ndepends on the value given to the argument of the function?\n\nThink about this for a second. If `length` is equal to 3 for example, then, the\nreturn type of the function is `[3]i64`. But if `length` is equal to 40, then,\nthe return type becomes `[40]i64`. At this point the `zig` compiler would be confused,\nand raise a compilation error, saying something like this:\n\n> Hey! You have annotated that this function should return a `[3]i64` value, but I got a `[40]i64` value instead! This doesn't look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when\nthe `type` keyword comes in. This `type` keyword is basically saying to the\n`zig` compiler that this function will return some data type as output, but it doesn't know yet\nwhat exactly data type that is. We will talk more about this in @sec-generics.\n\n\n\n### Applying over an expression\n\nWhen you apply the `comptime` keyword over an expression, then, it is guaranteed that the `zig` compiler will\nexecute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time\n(e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the `zig` compiler\nwill raise a compilation error.\n\nTake this example from the official documentation of Zig [@zigdocs]. We\nare executing the same `fibonacci()` function both at runtime, and, at compile-time.\nThe function is executed by default at runtime, but because we use the `comptime`\nkeyword in the second \"try expression\", this expression is executed at compile-time.\n\nThis might be a bit confusing for some people. Yes! When I say that this expression\nis executed at compile-time, I mean that this expression is compiled and executed\nwhile the `zig` compiler is compiling your Zig source code.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file833f119d55a3.test.fibonacci...OKAll 1 test\n  ts passed.\n```\n\n\n:::\n:::\n\n\n\n\nA lot of your Zig source code might be potentially executed at compile-time,\nbecause the `zig` compiler can figure out the output of some expressions.\nEspecially if these expressions depend only on compile-time known values.\nWe have talked about this in @sec-compile-time.\n\nBut when you use the `comptime` keyword on an expression, there is no \"it might be executed\nat compile-time\" anymore. With the `comptime` keyword you are ordering the `zig` compiler\nto execute this expression at compile-time. You are imposing this rule, it is guaranteed\nthat the compiler will always execute it at compile-time. Or, at least, the compiler\nwill try to execute it. If the compiler cannot execute the expression for whatever reason,\nthe compiler will raise a compilation error.\n\n\n### Applying over a block\n\nBlocks were described in @sec-blocks. When you apply the `comptime` keyword to a\nblock of expressions, you get essentially the same effect as when you apply this keyword to\na single expression. That is, the entire block of expressions is executed at\ncompile-time by the `zig` compiler.\n\nIn the example below, we mark the block labeled of `blk` as a comptime block,\nand, therefore, the expressions inside this block are executed at compile-time.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file833f6ccf145c.test.fibonacci in a block...O\n  OKAll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## Introducing Generics {#sec-generics}\n\nFirst of all, what is a generic? Generic is the idea to allow a type\n(`f64`, `u8`, `u32`, `bool`, and also, user-defined types, like the `User` struct\nthat we defined in @sec-structs-and-oop) to be a parameter to methods, classes and\ninterfaces [@geeks_generics]. In other words, a \"generic\" is a class (or a method) that can work\nwith multiple data types.\n\nFor example, in Java, generics are created through the operator `<>`. With this operator,\na Java class is capable of receiving a data type as input, and therefore, the class can fit\nits features according to this input data type.\nAs another example, generics in C++ are supported through the concept of templates.\nClass templates in C++ are generics.\n\nIn Zig, generics are implemented through `comptime`. The `comptime` keyword\nallows us to collect a data type at compile time, and pass this data type as\ninput to a piece of code.\n\n\n### A generic function {#sec-generic-fun}\n\nTake the `max()` function exposed below as a first example.\nThis function is essentially a \"generic function\".\nIn this function, we have a comptime function argument named `T`.\nNotice that this `T` argument has a data type of `type`. Weird right? This `type` keyword is the\n\"father of all types\", or, \"the type of types\" in Zig.\n\nBecause we have used this `type` keyword in the `T` argument, we are telling\nthe `zig` compiler that this `T` argument will receive some data type as input.\nAlso notice the use of the `comptime` keyword in this argument.\nAs I described in @sec-comptime, every time you use this keyword in a function argument,\nthis means that the value of this argument must be known at compile-time.\nThis makes sense, right? Because there is no data type that is not known at compile-time.\n\nThink about this. Every data type that you will ever write is always\nknown at compile-time. Especially because data types are an essential\ninformation for the compiler to actually compile your source code.\nHaving this in mind, makes sense to mark this argument as a comptime argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\n```\n:::\n\n\n\n\nAlso notice that the value of the `T` argument is actually used\nto define the data type of the other arguments in the function, `a` and `b`, and also at the\nreturn type annotation of the function.\nThat is, the data type of these arguments (`a` and `b`), and, the return data type of the function itself,\nare determined by the input value given to the `T` argument.\n\nAs a result, we have a generic function that works with different data types.\nFor example, I can provide `u8` values to this `max()` function, and it will work as expected.\nBut if I provide `f64` values instead, it will also work as expected.\nWithout a generic function, I would have to write a different `max()` function\nfor each data type I wanted to use.\nThis generic function provides a very useful shortcut for us.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\ntest \"test max\" {\n    const n1 = max(u8, 4, 10);\n    std.debug.print(\"Max n1: {d}\\n\", .{n1});\n    const n2 = max(f64, 89.24, 64.001);\n    std.debug.print(\"Max n2: {d}\\n\", .{n2});\n}\n```\n:::\n\n\n\n\n```\nMax n1: 10\nMax n2: 89.24\n```\n\n\n### A generic data structure {#sec-generic-struct}\n\nEvery data structure that you find in the Zig Standard Library (e.g. `ArrayList`, `HashMap`, etc.)\nis essentially a generic data structure.\nThese data structures are generic in the sense that they work with any data type you want.\nYou just say which is the data type of the values that are going to be stored in this data\nstructure, and they just work as expected.\n\nA generic data structure in Zig is how you replicate a generic class from Java,\nor, a class template from C++. But you may ask yourself: how do we build a\ngeneric data structure in Zig?\n\nThe basic idea is to write a generic function that creates the data structure definition\nfor the specific type we want. In other words, this generic function behaves as a \"factory of data structures\".\nThe generic function outputs the `struct` definition that defines this data structure for a\nspecific data type.\n\nTo create such function, we need to add a comptime argument to this function that receives a data type\nas input. We already learned how to do this in the previous section (@sec-generic-fun).\nI think the best way to demonstrate how to create a generic data structure is to actually write one.\nThis where we go into our next small project in this book. This one is a very small project,\nwhich is to write a generic stack data structure.\n\n\n\n\n## What is a stack? {#sec-what-stack}\n\nA stack data structure is a structure that follows a LIFO (*last in, first out*) principle.\nOnly two operations are normally supported in a stack data structure, which are `push` and `pop`.\nThe `push` operation is used to add new values to the stack, while `pop` is used to remove\nvalues from the stack.\n\nWhen people try to explain how the stack data structure works, the most common analogy\nthat they use is a stack of plates. Imagine that you have a stack of plates,\nfor example, a stack of 10 plates in your table. Each plate represents a value that\nis currently stored in this stack.\n\nWe begin with a stack of 10 different values, or 10 different plates. Now, imagine that you want to\nadd a new plate (or a new value) to this stack, which translates to the `push` operation.\nYou would add this plate (or this value) by just putting the new plate\non the top of the stack. Then, you would increase the stack to 11 plates.\n\nBut how would you remove plates (or remove values) from this stack (a.k.a. the `pop` operation) ?\nTo do that, we would have to remove the plate on the top of the stack, and, as a result, we would\nhave, once again, 10 plates in the stack.\n\nThis demonstrates the LIFO concept, because the first plate in the stack, which is the plate\nin the bottom of the stack, is always the last plate to get out of the stack. Think about it. In order\nto remove this specific plate from the stack, we have to remove all plates in the\nstack. So every operation in the stack, either insertion or deletion, is always made at the top of the stack.\nThe @fig-stack below exposes this logic visually:\n\n![A diagram of a stack structure. Source: Wikipedia, the free encyclopedia.](./../Figures/lifo-stack.svg){#fig-stack}\n\n\n\n## Writing the stack data structure\n\nWe are going to write the stack data structure in two steps. First, we are going\nto implement a stack that can only store `u32` values. Then, after that, we are going\nto extend our implementation to make it generic, so that it works with any data type\nwe want.\n\nFirst, we need to decide how the values will be stored inside the stack. There are multiple\nways to implement the storage behind a stack structure. Some people prefer to use a doubly linked list,\nothers prefer to use a dynamic array, etc. In this example we are going to use an array behind the hood,\nto store the values in the stack, which is the `items` data member of our `Stack` struct definition.\n\nAlso notice in our `Stack` struct that we have three other data members: `capacity`, `length` and `allocator`.\nThe `capacity` member contains the capacity of the underlying array that stores the values in the stack.\nThe `length` contains the number of values that are currently being stored in the stack.\nAnd the `allocator` contains the allocator object that will be used by the stack structure whenever it\nneeds to allocate more space for the values that are being stored.\n\nWe begin by defining an `init()` method of this struct, which is going to be\nresponsible for instantiating a `Stack` object. Notice that, inside this\n`init()` method, we start by allocating an array with the capacity specified\nin the `capacity` argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst Stack = struct {\n    items: []u32,\n    capacity: usize,\n    length: usize,\n    allocator: Allocator,\n\n    pub fn init(allocator: Allocator, capacity: usize) !Stack {\n        var buf = try allocator.alloc(u32, capacity);\n        return .{\n            .items = buf[0..],\n            .capacity = capacity,\n            .length = 0,\n            .allocator = allocator,\n        };\n    }\n};\n```\n:::\n\n\n\n\n\n### Implementing the `push` operation\n\nNow that we have written the basic logic to create a new `Stack` object,\nwe can start writing the logic responsible for performing a push operation.\nRemember, a push operation in a stack data structure is the operation\nresponsible for adding a new value to the stack.\n\nSo how can we add a new value to the `Stack` object that we have?\nThe `push()` function exposed below is a possible answer to this question.\nRemember from what we discussed in @sec-what-stack that values are always added to the top of the stack.\nThis means that this `push()` function must always find the element in the underlying array\nthat currently represents the top position of the stack, and then, add the input value there.\n\nFirst, we have an if statement in this function. This if statement is\nchecking whether we need to expand the underlying array to store\nthis new value that we are adding to the stack. In other words, maybe\nthe underlying array does not have enough capacity to store this new\nvalue, and, in this case, we need to expand our array to get the capacity that we need.\n\nSo, if the logical test in this if statement returns true, it means that the array\ndoes not have enough capacity, and we need to expand it before we store this new value.\nSo inside this if statement we are executing the necessary expressions to expand the underlying array.\nNotice that we use the allocator object to allocate a new array that is twice as bigger\nthan the current array (`self.capacity * 2`).\n\nAfter that, we use a different built-in function named `@memcpy()`. This built-in function\nis equivalent to the `memcpy()` function from the C Standard Library[^cmemcpy]. It's used to\ncopy the values from one block of memory to another block of memory. In other words,\nyou can use this function to copy the values from one array into another array.\n\n[^cmemcpy]: <https://www.tutorialspoint.com/c_standard_library/c_function_memcpy.htm>\n\nWe are using this `@memcpy()` built-in function to copy the values that are currently stored\nin the underlying array of the stack object (`self.items`) into our new and bigger array that\nwe have allocated (`new_buf`). After we execute this function, the `new_buf` contains a copy\nof the values that are present at `self.items`.\n\nNow that we have secured a copy of our current values in the `new_buf` object, we\ncan now free the memory currently allocated at `self.items`. After that, we just need\nto assign our new and bigger array to `self.items`. This is the sequence\nof steps necessary to expand our array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn push(self: *Stack, val: u32) !void {\n    if ((self.length + 1) > self.capacity) {\n        var new_buf = try self.allocator.alloc(\n            u32, self.capacity * 2\n        );\n        @memcpy(\n            new_buf[0..self.capacity], self.items\n        );\n        self.allocator.free(self.items);\n        self.items = new_buf;\n        self.capacity = self.capacity * 2;\n    }\n\n    self.items[self.length] = val;\n    self.length += 1;\n}\n```\n:::\n\n\n\n\nAfter we make sure that we have enough room to store this new value\nthat we are adding to the stack, all we have to do is to assign\nthis value to the top element in this stack, and, increase the\nvalue of the `length` attribute by one. We find the top element\nin the stack by using the `length` attribute.\n\n\n\n### Implementing the `pop` operation\n\nNow we can implement the pop operation of our stack object.\nThis is a much easier operation to implement, and the `pop()` method below summarises\nall the logic that is needed.\n\nWe just have to find the element in the underlying array that currently represents the top\nof the stack, and set this element to \"undefined\", to indicate that\nthis element is \"empty\". After that, we also need to decrease\nthe `length` attribute of the stack by one.\n\nIf the current length of the stack is zero, it means that there is\nno values being stored in the stack currently. So, in this case,\nwe could just return from the function and do nothing really.\nThis is what the if statement inside this function is checking for.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn pop(self: *Stack) void {\n    if (self.length == 0) return;\n\n    self.items[self.length - 1] = undefined;\n    self.length -= 1;\n}\n```\n:::\n\n\n\n\n\n\n### Implementing the `deinit` method\n\nWe have implemented the methods responsible for the two main operations\nassociated with the stack data structure, which is `pop()` and `push()`,\nand we also have implemented the method responsible for instantiating\na new `Stack` object, which is the `init()` method.\n\nBut now, we need to implement also the method responsible for destroying\na `Stack` object. In Zig, this task is commonly associated with the method\nnamed `deinit()`. Most struct objects in Zig have such method, and it\nis commonly nicknamed \"the destructor method\".\n\nIn theory, all we have to do to destroy the `Stack` object is to make\nsure that we free the allocated memory for the underlying array, using\nthe allocator object that is stored inside the `Stack` object.\nThis is what the `deinit()` method below is doing.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn deinit(self: *Stack) void {\n    self.allocator.free(self.items);\n}\n```\n:::\n\n\n\n\n\n\n\n## Making it generic\n\nNow that we have implemented the basic skeleton of our stack data structure,\nwe can now focus on discussing how we can make it generic. How can we make\nthis basic skeleton to work not only with `u32` values, but also with any other\ndata type we want?\nFor example, we might need to create a stack object to store `User` values\nin it. How can we make this possible? The answer lies in the use of generics\nand `comptime`.\n\nAs I described in @sec-generic-struct, the basic idea is to write a generic\nfunction that returns a struct definition as output.\nIn theory, we do not need much to transform our `Stack` struct into a generic\ndata structure. All that we need to do is to transform the underlying array\nof the stack into a generic array.\n\nIn other words, this underlying array needs to be a \"chameleon\". It needs to adapt,\nand transform it into an array of any data type that we want. For example, if we need to create\na stack that will store `u8` values, then this underlying array needs to be\na `u8` array (i.e., `[]u8`). But if we need to store `User` values instead, then,\nthis array needs to be a `User` array (i.e., `[]User`). Etc.\n\nWe do that by using a generic function. Because a generic function can receive a data type\nas input, and we can pass this data type to the struct definition of our `Stack` object.\nTherefore, we can use the generic function to create a `Stack` object that can store\nthe data type we want. If we want to create a stack structure that stores `User` values,\nwe pass the `User` data type to this generic function, and it will create for us\nthe struct definition that describes a `Stack` object that can store `User` values in it.\n\nLook at the code example below. I have omitted some parts of the `Stack` struct definition\nfor brevity. However, if a specific part of our `Stack` struct is not exposed here\nin this example, then it's because this part did not change from the previous example.\nIt remains the same.\n\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn Stack(comptime T: type) type {\n    return struct {\n        items: []T,\n        capacity: usize,\n        length: usize,\n        allocator: Allocator,\n        const Self = @This();\n\n        pub fn init(allocator: Allocator,\n                    capacity: usize) !Stack(T) {\n            var buf = try allocator.alloc(T, capacity);\n            return .{\n                .items = buf[0..],\n                .capacity = capacity,\n                .length = 0,\n                .allocator = allocator,\n            };\n        }\n\n        pub fn push(self: *Self, val: T) !void {\n        // Truncate the rest of the struct\n    };\n}\n```\n:::\n\n\n\n\nNotice that we have created a function in this example named `Stack()`. This function\ntakes a type as input, and passes this type to the struct definition of our\n`Stack` object. The data member `items` is now, an array of type `T`, which is the\ndata type that we have provided as input to the function. The function argument\n`val` in the `push()` function is now a value of type `T` too.\n\nWe can just provide a data type to this function, and it will create a definition of a\n`Stack` object that can store values of the data type that we have provided. In the example below, we are creating\nthe definition of a\n`Stack` object that can store `u8` values in it. This definition is stored at the `Stacku8` object.\nThis `Stacku8` object becomes our new struct, that we are going to use\nto create our `Stack` object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst Stacku8 = Stack(u8);\nvar stack = try Stacku8.init(allocator, 10);\ndefer stack.deinit();\ntry stack.push(1);\ntry stack.push(2);\ntry stack.push(3);\ntry stack.push(4);\ntry stack.push(5);\ntry stack.push(6);\n\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\"Stack capacity: {d}\\n\", .{stack.capacity});\n\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\n    \"Stack state: {any}\\n\",\n    .{stack.items[0..stack.length]}\n);\n```\n:::\n\n\n\n\n```\nStack len: 6\nStack capacity: 10\nStack len: 5\nStack len: 4\nStack state: { 1, 2, 3, 4, 0, 0, 0, 0, 0, 0 }\n```\n\nEvery generic data structure in the Zig Standard Library (`ArrayList`, `HashMap`, `SinlyLinkedList`, etc.)\nis implemented through this logic. They use a generic function to create the struct definition that can work\nwith the data type that you provided as input.\n\n\n\n\n## Conclusion\n\nThe full source code of the stack structure discussed in this chapter is freely available in the official\nrepository of this book. Just checkout the [`stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig)[^zig-stack]\nfor the `u32` version of our stack,\nand the [`generic_stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig)[^zig-stack2]\nfor the generic version, available inside the `ZigExamples` folder of the repository.\n\n\n[^zig-stack]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig>\n[^zig-stack2]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig>\n",
+    "supporting": [
+      "10-stack-project_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/12-file-op/execute-results/html.json b/_freeze/Chapters/12-file-op/execute-results/html.json
index 4bb8d71f..f21b00fa 100644
--- a/_freeze/Chapters/12-file-op/execute-results/html.json
+++ b/_freeze/Chapters/12-file-op/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "e7a97064b2b87b0c0d58e245144e133b",
+  "hash": "1e79228e1613c85b9e688833811e2fda",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n\n# Filesystem and Input/Output (IO) {#sec-filesystem}\n\nIn this chapter we are going to discuss how to use the cross-platform structs and functions\nfrom the Zig Standard Library that can execute filesystem operations. Most of these functions and structs\ncomes from the `std.fs` module.\n\nWe are also going to talk about Input/Output (also known as IO) operations in Zig. Most of\nthese operations are made by using the structs and functions from `std.io` module, which defines\nfile descriptors for the *standard channels* of your system (`stdout` and `stdin`), and also,\nfunctions to create and use I/O streams.\n\n\n## Input/Output basics {#sec-io-basics}\n\nIf you have some experience in a high-level language, you have certainly used\nthese input and output functionalities before in this language. In other words, you certainly have\nbeen in a situation where you needed to sent some output to the user, or, to receive an input\nfrom the user.\n\nFor example, in Python we can receive some input from the user by using the `input()` built-in\nfunction. But we can also print (or \"show\") some output to the user by using the `print()`\nbuilt-in function. So yes, if you have programmed before in Python, you certainly have\nused these functions once before.\n\nBut do you know how these functions relate back to your operating system (OS)? How exactly\nthey are interacting with the resources of your OS to receive or sent some input/output.\nIn essence, these input/output functions from high-level languages are just abstractions\nover the *standard output* and *standard input* channels of your operating system.\n\nThis means that we receive an input, or send some output, through the operating system.\nIt is the OS that makes the bridge between the user and your program. Your program\ndoes not have a direct access to the user. It is the OS that intermediates every\nmessage exchanged between your program and the user.\n\nThe *standard output* and *standard input* channels of your OS are commonly known as the\n`stdout` and `stdin` channels of your OS, respectively. In some contexts, they are also\ncalled the *standard output device* and the *standard input device*. As the name suggests,\nthe *standard output* is the channel through which output flows, while the *standard input*\nis the channel in which input flows.\n\nFurthermore, OS's also normally create a dedicated channel for exchanging error messages, which is known as the\n*standard error* channel, or, the `stderr` channel. This is the channel to which error and warning messages\nare usually sent to. These are the messages that are normally displayed in red-like or orange-like colors\ninto your terminal.\n\nNormally, every OS (e.g. Windows, macOS, Linux, etc.) creates a dedicated and separate set of\n*standard output*, *standard error* and *standard input* channels for every single program (or process) that runs in your computer.\nThis means that every program you write have a dedicated `stdin`, `stderr` and `stdout` that are separate\nfrom the `stdin`, `stderr` and `stdout` of other programs and processes that are currently running.\n\nThis is a behaviour from your OS. This does not come from the programming language that you are using.\nBecause as I sad earlier, input and output in programming languages, especially\nin high-level ones, are just a simple abstraction over the `stdin`, `stderr` and `stdout` from your current OS.\nThat is, your OS is the intermediary between every input/output operation made in your program,\nregardless of the programming language that you are using.\n\n\n### The writer and reader pattern {#sec-writer-reader}\n\nIn Zig, there is a pattern around input/output (IO). I (the author of this book) don't know if there\nis an official name for this pattern. But here, in this book, I will call it the \"writer and reader pattern\".\nIn essence, every IO operation in Zig is made through either a `GenericReader` or a `GenericWriter` object[^gen-zig].\n\nThese two data types come from the `std.io` module of the Zig Standard Library. As their names suggests, a\n`GenericReader` is an object that offers tools to read data from \"something\" (or \"somewhere\"), while a `GenericWriter`\noffers tools to write data into this \"something\". This \"something\" might be different things: like a\nfile that exists in your filesystem; or, it might be a network socket in your system[^sock]; or,\na continuous stream of data, like a standard input device from your system, that might be constantly\nreceiving new data from users, or, as another example, a live chat in a game that is constantly\nreceiving and displaying new messages from the players of the game.\n\n[^gen-zig]: Previously, these objects were known as the `Reader` and `Writer` objects.\n[^sock]: The socket objects that we have created at @sec-create-socket, are examples of network sockets.\n\nSo, if you want to **read** data from something, or somewhere, it means that you need to use a `GenericReader` object.\nBut if you need instead, to **write** data into this \"something\", then, you need to use a `GenericWriter` object instead.\nBoth of these objects are normally created from a file descriptor object. More specifically, through the `writer()` and `reader()`\nmethods of this file descriptor object. If you are not familiar with this type of object, go to the next section.\n\nEvery `GenericWriter` object have methods like `print()`, which allows you to write/send a formatted string\n(i.e. this formatted string is like a `f` string in Python, or, similar to the `printf()` C function)\ninto the \"something\" (file, socket, stream, etc.) that you are using. It also have a `writeAll()` method, which allows you to\nwrite a string, or, an array of bytes into the \"something\".\n\nLikewise, every `GenericReader` object have methods like `readAll()`, which allows you to read the\ndata from the \"something\" (file, socket, stream, etc.) until it fills a particular array (i.e. a \"buffer\") object.\nIn other words, if you provide an array object of 300 `u8` values to `readAll()`, then, this method attempts to read 300 bytes\nof data from the \"something\", and it stores them into the array object that you have provided.\n\nWe also have other methods, like the `readAtLeast()` method, which allows you to specify how\nmany bytes exactly you want to read from the \"something\". In more details, if you give the\nnumber $n$ as input to this method, then, it will attempt to read at least $n$ bytes of data\nfrom the \"something\". The \"something\" might have less than $n$ bytes of data available for you\nto read, so, it is not guaranteed that you will get precisely $n$ bytes as result.\n\nAnother useful method is `readUntilDelimiterOrEof()`. In this method, you specify a \"delimiter character\".\nThe idea is that this function will attempt to read as many bytes of data as possible from the \"something\",\nuntil it encounters the end of the stream, or, it encounters the \"delimiter character\" that you have specified.\n\nIf you don't know exactly how many bytes will come from the \"something\", you may find the `readAllAlloc()` method\nuseful. In essence, you provide an allocator object to this method, so that it can allocate more space if needed.\nAs consequence, this method will try to read all bytes of the \"something\", and, if it runs out of space at some point\nduring the \"reading process\", it uses the allocator object to allocate more space to continue reading the bytes.\nAs result, this method returns a slice to the array object containing all the bytes read.\n\nThis is just a quick description of the methods present in these types of objects. But I recommend you\nto read the official docs, both for\n[`GenericWriter`](https://ziglang.org/documentation/master/std/#std.io.GenericWriter)[^gen-write] and\n[`GenericReader`](https://ziglang.org/documentation/master/std/#std.io.GenericReader)[^gen-read].\nI also think it is a good idea to read the source code of the modules in the Zig Standard Library\nthat defines the methods present in these objects, which are the\n[`Reader.zig`](https://github.com/ziglang/zig/blob/master/lib/std/io/Reader.zig)[^mod-read]\nand [`Writer.zig`]()[^mod-write].\n\n[^gen-read]: <https://ziglang.org/documentation/master/std/#std.io.GenericReader>.\n[^gen-write]: <https://ziglang.org/documentation/master/std/#std.io.GenericWriter>.\n[^mod-read]: <https://github.com/ziglang/zig/blob/master/lib/std/io/Reader.zig>.\n[^mod-write]: <https://github.com/ziglang/zig/blob/master/lib/std/io/Writer.zig>.\n\n\n\n### Introducing file descriptors {#sec-file-descriptor}\n\nA \"file descriptor\" object is a core component behind every IO operation that is made in any operating system (OS).\nSuch object is an identifier for a particular input/output (IO) resource from your OS [@wiki_file_descriptor].\nIt describes and identifies this particular resource. An IO resource might be:\n\n- an existing file in your filesystem.\n- an existing network socket.\n- other types of stream channels.\n- a pipeline (or just \"pipe\") in your terminal[^pipes].\n\n[^pipes]: A pipeline is a mechanism for inter-process communication, or, inter-process IO. You could also interpret a pipeline as a \"set of processes that are chained together, through the standard input/output devices of the system\". At Linux for example, a pipeline is created inside a terminal, by connecting two or more terminal commands with the \"pipe\" character (`|`).\n\nFrom the bullet points listed above, we know that although the term \"file\" is present,\na \"file descriptor\" might describe something more than just a file.\nThis concept of a \"file descriptor\" comes from the Portable Operating System Interface (POSIX) API,\nwhich is a set of standards that guide how operating systems across the world should be implemented,\nto maintain compatibility between them.\n\nA file descriptor not only identifies the input/output resource that you are using to receive or send some data,\nbut it also describes where this resource is, and also, which IO mode this resource is currently using.\nFor example, this IO resource might be using only the \"read\" IO mode, which means that this resource\nis open to \"read operations\", while \"write operations\" are not authorized.\nThese IO modes are essentially the modes that you provide to the argument `mode`\nfrom the `fopen()` C function, and also, from the `open()` Python built-in function.\n\nIn C, a \"file descriptor\" is a `FILE` pointer, but, in Zig, a file descriptor is a `File` object.\nThis data type (`File`) is described in the `std.fs` module of the Zig Standard Library.\nWe normally don't create a `File` object directly in our Zig code. Instead, we normally get such object as result when we\nopen an IO resource. In other words, we normally ask our OS to open a particular IO resource for us,\nand, if the OS do open successfully this IO resource, the OS normally handles back to us\na file descriptor to this particular IO resource.\n\nSo you usually get a `File` object by using functions and methods from the Zig Standard Library\nthat asks the OS to open some IO resource, like the `openFile()` method that opens a file in the\nfilesystem. The `net.Stream` object that we have created at @sec-create-socket is also a type of\nfile descriptor object.\n\n\n### The *standard output*\n\nYou already saw across this book, how can we access and use specifically the `stdout` in Zig\nto send some output to the user.\nFor that, we use the `getStdOut()` function from the `std.io` module. This function returns\na file descriptor that describes the `stdout` channel of your current OS. Through this file\ndescriptor object, we can read from or write stuff to the `stdout` of our program.\n\nAlthough we can read stuff recorded into the `stdout` channel, we normally only\nwrite to (or \"print\") stuff into this channel. The reason is very similar to what we discussed at\n@sec-read-http-message, when we were discussing what \"reading from\" versus \"writing to\" the connection\nobject from our small HTTP Server project would mean.\n\nWhen we write stuff into a channel, we are essentially sending data to the other end of this channel.\nIn contrast, when we read stuff from this channel, we are essentially reading the data that was sent\nthrough this channel. Since the `stdout` is a channel to send output to the user, the key verb here\nis **send**. We want to send something to someone, and, as consequence, we want to **write** something\ninto some channel.\n\nThat is why, when we use `getStdOut()`, most of the times, we also use the `writer()` method from the `stdout` file descriptor,\nto get access to a writer object that we can use to write stuff into this `stdout` channel.\nMore specifically, this `writer()` method returns a `GenericWriter` object. One of the\nmain methods of this `GenericWriter` object is the `print()` method that we have used\nbefore to write (or \"print\") a formatted string into the `stdout` channel.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    try stdout.writeAll(\n        \"This message was written into stdout.\\n\"\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nThis message was written into stdout.\n```\n\n\n:::\n:::\n\n\n\n\n\n\nThis `GenericWriter` object is like any other generic writer object that you would normally get from a file descriptor object.\nSo, the same methods from a generic writer object that you would use while writing files to the filesystem for example, you could also\nuse them here, from the file descriptor object of `stdout`, and vice-versa.\n\n\n### The *standard input*\n\nYou can access the *standard input* (i.e. `stdin`) in Zig by using the `getStdIn()` function from the `std.io` module.\nLike its brother (`getStdOut()`), this function also returns a file descriptor object that describes the `stdin` channel\nof your OS.\n\nBecause we want to receive some input from the user, the key verb here becomes **receive**, and, as consequence,\nwe usually want to **read** data from the `stdin` channel, instead of writing data into it. So, we normally use\nthe `reader()` method of the file descriptor object returned by `getStdIn()`, to get access to a `GenericReader`\nobject that we can use to read data from `stdin`.\n\nIn the example below, we are creating a small buffer capable of holding 20 characters. Then, we try to read\nthe data from the `stdin` with the `readUntilDelimiterOrEof()` method, and save this data into the `buffer` object.\nAlso notice that we are reading the data from the `stdin` until we hit a new line character (`'\\n'`).\n\nIf you execute this program, you will notice that it stops the execution, ands start to wait indefinitely\nfor some input from the user. In other words, you need to type your name into the terminal, and then, you press Enter to\nsend your name to `stdin`. After you send your name to `stdin`, the program reads this input, and continues with the execution,\nby printing the given name to `stdout`. In the example below, I typed my name (Pedro) into the terminal, and then, pressed Enter.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst stdin = std.io.getStdIn().reader();\npub fn main() !void {\n    try stdout.writeAll(\"Type your name\\n\");\n    var buffer: [20]u8 = undefined;\n    @memset(buffer[0..], 0);\n    _ = try stdin.readUntilDelimiterOrEof(buffer[0..], '\\n');\n    try stdout.print(\"Your name is: {s}\\n\", .{buffer});\n}\n```\n:::\n\n\n\n\n```\nType your name\nYour name is: Pedro\n\n```\n\n\n### The *standard error*\n\nThe *standard error* (a.k.a. the `stderr`) works exactly the same as `stdout` and `stdin`.\nYou just call the `getStdErr()` function from the `std.io` module, and you get the file descriptor to `stderr`.\nIdeally, you should write only error or warning messages to `stderr`, because this is\nthe purpose of this channel.\n\n\n\n\n\n## Buffered IO\n\nAs we described at @sec-io-basics, input/output (IO) operations are made directly by the operating system.\nIt is the OS that manages the IO resource that you want to use for your IO operations.\nThe consequence of this fact is that IO operations are heavily based on system calls (i.e. calling the operating system directly).\n\nJust to be clear, there is nothing particularly wrong with system calls. We use them all the time on\nany serious codebase written in any low-level programming language. However, system calls are\nalways orders of magnitude slower than many different types of operations.\n\nSo is perfectly fine to use a system call once in a while. But when these system calls are used often,\nyou can clearly notice most of the time the loss of performance in your application. So, the good rule of thumbs\nis to use a system call only when it is needed, and also, only in infrequent situations, to reduce\nthe number of system calls performed to a minimum.\n\n\n### Understanding how buffered IO works\n\nBuffered IO is a strategy to achieve better performance. It is used to reduce the number of system calls made by IO operations, and, as\nconsequence, achieve a much higher performance. At @fig-unbuffered-io and @fig-buffered-io you can find two different diagrams\nwhich presents the difference between read operations performed in an unbuffered IO environment versus a buffered IO environment.\n\nTo give a better context to these diagrams, let's suppose that we have a text file that contains the famous Lorem ipsum text[^lorem]\nin our filesystem. Let's also suppose that these diagrams at @fig-unbuffered-io and @fig-buffered-io\nare showing the read operations that we are performing to read the Lorem ipsum text from this text file.\nThe first thing you will notice when looking at these diagrams, is that in an unbuffered environment\nthe read operations leads to many system calls.\nMore precisely, in the diagram exposed at @fig-unbuffered-io we get one system call per each byte that we read from the text file.\nOn the other hand, at @fig-buffered-io we have only one system call at the very beginning.\n\nWhen we use a buffered IO system, at the first read operation we perform, instead of sending one single byte directly\nto our program, the OS first sends a chunk of bytes from the file to a buffer object (i.e. an array).\nThis chunk of bytes are cached/stored inside this buffer object.\n\nTherefore, from now on, for every new read operation that you perform, instead of making a new system call to ask\nfor the next byte in the file to the OS, this read operation is redirected to the buffer object, that have\nthis next byte already cached and ready to go.\n\n\n[^lorem]: <https://www.lipsum.com/>.\n\n\n![Unbuffered IO](./../Figures/unbuffered-io.png){#fig-unbuffered-io width=60%}\n\n![Buffered IO](./../Figures/buffered-io.png){#fig-buffered-io}\n\n\n\nThis is the basic logic behind buffered IO systems. The size of the buffer object depends on multiple factors. But it is usually\nequal to the size of a full page of memory (4096 bytes). If we follow this logic, then, the OS reads the first 4096 bytes\nof the file and caches it into the buffer object. As long as your program does not consume all of these 4096 bytes from the buffer,\nyou will not create new system calls.\n\nHowever, as soon as you consume all of these 4096 bytes from the buffer, it means that there is no bytes left in the buffer.\nIn this situation, a new system call is made to ask the OS to send the next 4096 bytes in the file, and once again,\nthese bytes are cached into the buffer object, and the cycle starts once again.\n\n\n### Buffered IO across different languages\n\nIO operations made through a `FILE` pointer in C are buffered\nby default, so, at least in C, you don't need to worry about this subject. But in contrast, IO operations in both Rust and Zig are not\nbuffered depending on which functions from the standard libraries that you are using.\n\nFor example, in Rust, buffered IO is implemented through the `BufReader` and `BufWriter` structs, while in Zig, it is implemented\nthrough the `BufferedReader` and `BufferedWriter` structs.\nSo any IO operation that you perform through the `GenericWriter` and `GenericReader` objects\nthat I presented at @sec-writer-reader are not buffered, which means that these objects\nmight create a lot of system calls depending on the situation.\n\n\n### Using buffered IO in Zig\n\nUsing buffered IO in Zig is actually very easy. All you have to do is to just\ngive the `GenericWriter` object to the `bufferedWriter()` function, or, to give the `GenericReader`\nobject to the `bufferedReader()` function. These functions come from the `std.io` module,\nand they will construct the `BufferedWriter` or `BufferedReader` object for you.\n\nAfter you create this new `BufferedWriter` or `BufferedReader` object, you can call the `writer()`\nor `reader()` method of this new object, to get access to a new (and buffered) generic reader or\ngeneric writer.\n\nLet's describe the process once again. Every time that you have a file descriptor object, you first get the generic writer or generic reader\nobject from it, by calling the `writer()` or `reader()` methods of this file descriptor object.\nThen, you provide this generic writer or generic reader to the `bufferedWriter()` or `bufferedReader()`\nfunction, which creates a new `BufferedWriter` or `BufferedReader` object. Then, you call\nthe `writer()` or `reader()` methods of this buffered writer or buffered reader object,\nwhich gives you access to a generic writer or a generic reader object that is buffered.\n\nTake this program as an example. This program is demonstrating the process exposed at @fig-buffered-io.\nWe are simply opening a text file that contains the Lorem ipsum text, and then, we create a buffered IO reader object\nat `bufreader`, and we use this `bufreader` object to read the contents of this file into a buffer object, then,\nwe end the program by printing this buffer to `stdout`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar file = try std.fs.cwd().openFile(\n    \"ZigExamples/file-io/lorem.txt\", .{}\n);\ndefer file.close();\nvar buffered = std.io.bufferedReader(file.reader());\nvar bufreader = buffered.reader();\n\nvar buffer: [1000]u8 = undefined;\n@memset(buffer[0..], 0);\n\n_ = try bufreader.readUntilDelimiterOrEof(\n    buffer[0..], '\\n'\n);\ntry stdout.print(\"{s}\\n\", .{buffer});\n```\n:::\n\n\n\n\n```\nLorem ipsum dolor sit amet, consectetur\nadipiscing elit. Sed tincidunt erat sed nulla ornare, nec\naliquet ex laoreet. Ut nec rhoncus nunc. Integer magna metus,\nultrices eleifend porttitor ut, finibus ut tortor. Maecenas\nsapien justo, finibus tincidunt dictum ac, semper et lectus.\nVivamus molestie egestas orci ac viverra. Pellentesque nec\narcu facilisis, euismod eros eu, sodales nisl. Ut egestas\nsagittis arcu, in accumsan sapien rhoncus sit amet. Aenean\nneque lectus, imperdiet ac lobortis a, ullamcorper sed massa.\nNullam porttitor porttitor erat nec dapibus. Ut vel dui nec\nnulla vulputate molestie eget non nunc. Ut commodo luctus ipsum,\nin finibus libero feugiat eget. Etiam vel ante at urna tincidunt\nposuere sit amet ut felis. Maecenas finibus suscipit tristique.\nDonec viverra non sapien id suscipit.\n```\n\nDespite being a buffered IO reader, this `bufreader` object is similar to any other `GenericReader` object,\nand have the exact same methods. So, although these two types of objects perform very different IO operations,\nthey have the same interface, so you, the programmer, can interchangeably use them\nwithout the need to change anything in your source code.\nSo a buffered IO reader or a buffered IO writer objects have the same methods than its generic and unbuffered brothers,\ni.e. the generic reader and generic writer objects that I presented at @sec-writer-reader.\n\n::: {.callout-tip}\nIn general, you should always use a buffered IO reader or a buffered IO writer object to perform\nIO operations in Zig. Because they deliver better performance to your IO operations.\n:::\n\n\n## Filesystem basics\n\nNow that we have discussed the basics around Input/Output operations in Zig, we need to\ntalk about the basics around filesystems, which is another core part of any operating system.\nAlso, filesystems are related to input/output, because the files that we store and create in our\ncomputer are considered an IO resource, as we described at @sec-file-descriptor.\n\n\n### The concept of current working directory (CWD)\n\nThe working directory is the folder on your computer where you are currently rooted at.\nIn other words, it is the folder that your program is currently looking at.\nTherefore, whenever you are executing a program, this program is always working with\na specific folder on your computer. It is always in this folder that the program will initially\nlook for the files you require, and it is also in this folder that the program\nwill initially save all the files you ask it to save.\n\nThe working directory is determined by the folder from which you invoke your program\nin the terminal. In other words, if you are in the terminal of your OS, and you\nexecute a binary file (i.e. a program) from this terminal, the folder to which your terminal\nis pointing at is the current working directory of your program that is being executed.\n\nAt @fig-cwd we have an example of me executing a program from the terminal. We are executing\nthe program outputted by the `zig` compiler by compiling the Zig module named `hello.zig`.\nThe CWD in this case is the `zig-book` folder. In other words, while the `hello.zig` program\nis executing, it will be looking at the `zig-book` folder, and any file operation that we perform\ninside this program, will be using this `zig-book` folder as the \"starting point\", or, as the \"central focus\".\n\n![Executing a program from the terminal](./../Figures/cwd.png){#fig-cwd}\n\nJust because we are rooted inside a particular folder (in the case of @fig-cwd, the `zig-book` folder) of our computer,\nit doesn't mean that we cannot access or write resources in other locations of our computer.\nThe current working directory (CWD) mechanism just defines where your program will look first\nfor the files you ask for. This does not prevent you from accessing files that are located\nelsewhere on your computer. However, to access any file that is in a folder other than your\ncurrent working directory, you must provide a path to that file or folder.\n\n\n### The concept of paths\n\nA path is essentially a location. It points to a location in your filesystem. We use\npaths to describe the location of files and folders in our computer.\nOne important aspect about paths is that they are always written inside strings,\ni.e. they are always provided as text values.\n\nThere are two types of paths that you can provide to any program in any OS: a relative path, or an absolute path.\nAbsolute paths are paths that start at the root of your filesystem, and go all the way to the file name or the specific folder\nthat you are referring to. This type of path is called absolute, because it points to an unique and absolute location on your computer.\nThat is, there is no other existing location on your computer that corresponds to this path. It is an unique identifier.\n\nIn Windows, an absolute path is a path that starts with a hard disk identifier (e.g. `C:/Users/pedro`).\nOn the other hand, absolute paths in Linux and macOS, are paths that start with a forward slash character (e.g. `/usr/local/bin`).\nNotice that a path is composed by \"segments\". Each segment is connected to each other by a slash character (`\\` or `/`).\nOn Windows, the backward slash (`\\`) is normally used to connect the path segments. While on Linux and macOS, the forward\nslash (`/`) is the character used to connect path segments.\n\nA relative path is a path that start at the CWD. In other words, a relative path is\n\"relative to the CWD\". The path used to access the `hello.zig` file at @fig-cwd is an example of a relative path. This path\nis reproduced below. This path begins at the CWD, which in the context of @fig-cwd, is the `zig-book` folder,\nthen, it goes to the `ZigExamples` folder, then, into `zig-basics`, then, to the `hello.zig` file.\n\n```\nZigExamples/zig-basics/hello_world.zig\n```\n\n\n### Path wildcards\n\nWhen providing paths, especially relative paths, you have the option of using a *wildcard*.\nThere are two commonly used *wildcards* in paths, which are \"one period\" (.) and \"two periods\" (..).\nIn other words, these two specific characters have special meanings when used in paths,\nand can be used on any operating system (Mac, Windows, Linux, etc.). That is, they\nare \"cross platform\".\n\nThe \"one period\" represents an alias for the current directory.\nThis means that the relative paths `\"./Course/Data/covid.csv\"` and `\"Course/Data/covid.csv\"` are equivalent.\nOn the other hand, the \"two periods\" refers to the previous directory.\nFor example, the path `\"Course/..\"` is equivalent to the path `\".\"`, that is, the current working directory.\n\nTherefore, the path `\"Course/..\"` refers to the folder before the `Course` folder.\nAs another example, the path `\"src/writexml/../xml.cpp\"` refers to the file `xml.cpp`\nthat is inside the folder before the `writexml` folder, which in this example is the `src` folder.\nTherefore, this path is equivalent to `\"src/xml.cpp\"`.\n\n\n\n\n## The CWD handler\n\nIn Zig, filesystem operations are usually made through a directory handler object.\nA directory handler in Zig is an object of type `Dir`, which is an object that describes\na particular folder in the filesystem of our computer.\nYou normally create a `Dir` object, by calling the `std.fs.cwd()` function.\nThis function returns a `Dir` object that points to (or, that describes) the\ncurrent working directory (CWD).\n\nThrough this `Dir` object, you can create new files, or modify, or read existing ones that are\ninside your CWD. In other words, a `Dir` object is the main entrypoint in Zig to perform\nmultiple types of filesystem operations.\nIn the example below, we are creating this `Dir` object, and storing it\ninside the `cwd` object. Although we are not using this object at this code example,\nwe are going to use it a lot over the next examples.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\n_ = cwd;\n```\n:::\n\n\n\n\n\n\n\n\n\n\n\n## File operations\n\n### Creating files {#sec-creating-files}\n\nWe create new files by using the `createFile()` method from the `Dir` object.\nJust provide the name of the file that you want to create, and this function will\ndo the necessary steps to create such file. You can also provide a relative path to this function,\nand it will create the file by following this path, which is relative to the CWD.\n\nThis function might return an error, so, you should use `try`, `catch`, or any of the other methods presented\nat @sec-error-handling to handle the possible error. But if everything goes well,\nthis `createFile()` method returns a file descriptor object (i.e. a `File` object) as result,\nthrough which you can add content to the file with the IO operations that I presented before.\n\nTake this code example below. In this example, we are creating a new text file\nnamed `foo.txt`. If the function `createFile()` succeeds, the object named `file` will contain a file descriptor\nobject, which we can use to write (or add) new content to the file, like we do in this example, by using\na buffered writer object to write a new line of text to the file.\n\nNow, a quick note, when we create a file descriptor object in C, by using a C function like `fopen()`, we must always close the file\nat the end of our program, or, as soon as we complete all operations that we wanted to perform\non the file. In Zig, this is no different. So everytime we create a new file, this file remains\n\"open\", waiting for some operation to be performed. As soon as we are done with it, we always have\nto close this file, to free the resources associated with it.\nIn Zig, we do this by calling the method `close()` from the file descriptor object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.createFile(\"foo.txt\", .{});\n// Don't forget to close the file at the end.\ndefer file.close();\n// Do things with the file ...\nvar fw = file.writer();\n_ = try fw.writeAll(\n    \"Writing this line to the file\\n\"\n);\n```\n:::\n\n\n\n\n\nSo, in this example we not only have created a file into the filesystem,\nbut we also wrote some data into this file, using the file descriptor object\nreturned by `createFile()`. If the file that you are trying to create\nalready exists in your filesystem, this `createFile()` call will\noverwrite the contents of the file, or, in other words, it will\nin erase all the contents of the existing file.\n\nIf you don't want this to happen, meaning, that you don't want to overwrite\nthe contents of the existing file, but you want to write data to this file anyway\n(i.e. you want to append data to the file), you should use the `openFile()`\nmethod from the `Dir` object.\n\nAnother important aspect about `createFile()` is that this method creates a file\nthat is not open to read operations by default. It means that you cannot read this file.\nYou are not allowed to.\nSo for example, you might want to write some stuff into this file at the beginning of the execution\nof your program. Then, at a future point in your program you might need to read what you\nwrote in this file. If you try to read data from this file, you will likely\nget a `NotOpenForReading` error as result.\n\n\nBut how can you overcome this barrier? How can you create a file that is open\nto read operations? All you have to do, is to set the `read` flag to true\nin the second argument of `createFile()`. When you set this flag to true,\nthen the file get's create with \"read permissions\", and, as consequence,\na program like this one below becomes valid:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.createFile(\n    \"foo.txt\",\n    .{ .read = true }\n);\ndefer file.close();\n\nvar fw = file.writer();\n_ = try fw.writeAll(\"We are going to read this line\\n\");\n\nvar buffer: [300]u8 = undefined;\n@memset(buffer[0..], 0);\ntry file.seekTo(0);\nvar fr = file.reader();\n_ = try fr.readAll(buffer[0..]);\ntry stdout.print(\"{s}\\n\", .{buffer});\n```\n:::\n\n\n\n\n\n```\nWe are going to read this line\n```\n\n\nIf you are not familiar with position indicators, you might not recognize the method\n`seekTo()`. If that is your case, do not worry,\nwe are going to talk more about this method at @sec-indicators. But essentially\nthis method is moving the position indicator back to the beginning of the file,\nso that we can read the contents of the file from the beginning.\n\n\n### Opening files and appending data to it\n\nOpening files is easy. Just use the `openFile()` method instead of `createFile()`.\nIn the first argument of `openFile()` you provide the path to the file that\nyou want to open. Then, on the second argument you provide the flags (or, the options)\nthat dictates how the file is opened.\n\nYou can see the full list of options for `openFile()` by visiting the documentation for\n[`OpenFlags`](https://ziglang.org/documentation/master/std/#std.fs.File.OpenFlags)[^oflags].\nBut the main flag that you will most certainly use is the `mode` flag.\nThis flag specifies the IO mode that the file will be using when it get's opened.\nThere are three IO modes, or, three values that you can provide to this flag, which are:\n\n- `read_only`, allows only read operations on the file. All write operations are blocked.\n- `write_only`, allows only write operations on the file. All read operations are blocked. \n- `read_write`, allows both write and read operations on the file.\n\n[^oflags]: <https://ziglang.org/documentation/master/std/#std.fs.File.OpenFlags>\n\nThese modes are similar to the modes that you provide to the `mode` argument of the\n`open()` Python built-in function[^py-open], or, the `mode` argument of the\n`fopen()` C function[^c-open].\nIn the code example below, we are opening the `foo.txt` text file with a `write_only` mode,\nand appending a new line of text to the end of the file. We use `seekFromEnd()` this time\nto guarantee that we are going to append the text to the end of the file. Once again, methods\nsuch as `seekFromEnd()` are described in more depth at @sec-indicators.\n\n[^py-open]: <https://docs.python.org/3/tutorial/inputoutput.html#reading-and-writing-files>\n[^c-open]: <https://www.tutorialspoint.com/c_standard_library/c_function_fopen.htm>\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.openFile(\n    \"foo.txt\", .{ .mode = .write_only }\n);\ndefer file.close();\ntry file.seekFromEnd(0);\nvar fw = file.writer();\n_ = try fw.writeAll(\"Some random text to write\\n\");\n```\n:::\n\n\n\n\n\n### Deleting files\n\nSometimes, we just need to delete/remove the files that we have.\nTo do that, we use the `deleteFile()` method. You just provide the path of the\nfile that you want to delete, and this method will try to delete the file located\nat this path.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.deleteFile(\"foo.txt\");\n```\n:::\n\n\n\n\n### Copying files\n\nTo copy existing files, we use the `copyFile()` method. The first argument in this method\nis the path to the file that you want to copy. The second argument is a `Dir` object, i.e. a directory handler,\nmore specifically, a `Dir` object that points to the folder in your computer where you want to\ncopy the file to. The third argument is the new path of the file, or, in other words, the new location\nof the file. The fourth argument is the options (or flags) to be used in the copy operation.\n\nThe `Dir` object that you provide as input to this method will be used to copy the file to\nthe new location. You may create this `Dir` object before calling the `copyFile()` method.\nMaybe you are planning to copy the file to a completely different location in your computer,\nso it might be worth to create a directory handler to that location. But if you are copying the\nfile to a subfolder of your CWD, then, you can just simply pass the CWD handler to this argument.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.copyFile(\n    \"foo.txt\",\n    cwd,\n    \"ZigExamples/file-io/foo.txt\",\n    .{}\n);\n```\n:::\n\n\n\n\n\n### Read the docs!\n\nThere are some other useful methods for file operations available at `Dir` objects,\nsuch as the `writeFile()` method, but I recommend you to read the docs for the\n[`Dir` type](https://ziglang.org/documentation/master/std/#std.fs.Dir)[^zig-dir]\nto explore the other available methods, since I already talked too much about them.\n\n\n[^zig-dir]: <https://ziglang.org/documentation/master/std/#std.fs.Dir>\n\n\n\n\n## Position indicators {#sec-indicators}\n\nA position indicator is like a type of cursor, or, an index. This \"index\" identifies the current\nlocation in the file (or, in the data stream) that the file descriptor object that you have\nis currently looking at.\nWhen you create a file descriptor, the position indicator starts at the beginning of the file,\nor, at the beginning of the stream. When you read from or write into the file (or socket, or data stream, etc.)\ndescribed by this file descriptor object, you end up moving the position indicator.\n\nIn other words, any IO operation have a common side effect, which is to move the position indicator.\nFor example, suppose that we have a file of 300 bytes total in size. If you\nread 100 bytes from the file, then, the position indicator moves 100 bytes forward. If you try\nto write 50 bytes into this same file, these 50 bytes will be written from the current\nposition indicated by the position indicator. Since the indicator is at a 100 bytes forward from\nthe beginning of the file, these 50 bytes would be written in the middle of the file.\n\nThis is why we have used the `seekTo()` method at the last code example presented at @sec-creating-files.\nWe have used this method to move the position indicator back to the beginning of the file, which\nwould make sure that we would write the text that we wanted to write from the beginning of the file,\ninstead of writing it from the middle of the file. Because before the write operation, we had\nperformed a read operation, which means that the position indicator was moved in this read operation.\n\nThe position indicators of a file descriptor object can be changed (or altered) by using the\n\"seek\" methods from this file descriptor, which are: `seekTo()`, `seekFromEnd()` and `seekBy()`.\nThese methods have the same effect, or, the same responsibility that the\n[`fseek()`](https://en.cppreference.com/w/c/io/fseek)[^c-fseek] C function.\n\n[^c-fseek]: <https://en.cppreference.com/w/c/io/fseek>\n\n\nConsidering that `offset` refers to the index that you provide as input to these \"seek\" methods,\nthe bullet points below summarises what is the effect of each of these methods.\nAs a quick note, in the case of `seekFromEnd()` and `seekBy()`, the `offset` provided can be either a\npositive or a negative index.\n\n- `seekTo()` will move the position indicator to the location that is `offset` bytes from the beginning of the file.\n- `seekFromEnd()` will move the position indicator to the location that is `offset` bytes from the end of the file.\n- `seekBy()` will move the position indicator to the location that is `offset` bytes from the current position in the file.\n\n\n\n\n\n\n\n## Directory operations\n\n### Iterating through the files in a directory\n\nOne of the most classic tasks related to filesystem is to be able\nto iterate through the existing files in a directory. To iterate over the\nfiles in a directory, we need to create an iterator object.\n\nYou can produce such iterator object by using either the `iterate()` or `walk()` methods\nof a `Dir` object. Both methods return an iterator object as output, which you can advance by using the\n`next()` method. The difference between these methods, is that `iterate()` returns a non-recursive iterator,\nwhile `walk()` does. It means that the iterator returned by `walk()` will not only iterate through\nthe files available in the current directory, but also, through the files from any subdirectory found\ninside the current directory.\n\nIn the example below, we are displaying the names of the files stored inside the\ndirectory `ZigExamples/file-io`. Notice that we had to open this directory through\nthe `openDir()` function. Also notice that we provided the flag `iterate` in the\nsecond argument of `openDir()`. This flag is important, because without this flag,\nwe would not be allowed to iterate through the files in this directory.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst dir = try cwd.openDir(\n    \"ZigExamples/file-io/\",\n    .{ .iterate = true }\n);\nvar it = dir.iterate();\nwhile (try it.next()) |entry| {\n    try stdout.print(\n        \"File name: {s}\\n\",\n        .{entry.name}\n    );\n}\n```\n:::\n\n\n\n\n```\nFile name: create_file_and_write_toit.zig\nFile name: create_file.zig\nFile name: lorem.txt\nFile name: iterate.zig\nFile name: delete_file.zig\nFile name: append_to_file.zig\nFile name: user_input.zig\nFile name: foo.txt\nFile name: create_file_and_read.zig\nFile name: buff_io.zig\nFile name: copy_file.zig\n```\n\n\n### Creating new directories\n\nThere are two methods that are important when it comes to\ncreating directories, which are `makeDir()` and `makePath()`.\nThe difference between these two methods is that `makeDir()` can\nonly create one single directory in the current directory in each call,\nwhile `makePath()` is capable of recursively create subdirectories in the same call.\n\n\nThis is why the name of this method is \"make path\". It will create as many\nsubdirectories as necessary to create the path that you provided as input.\nSo, if you provide the path `\"sub1/sub2/sub3\"` as input to this method,\nit will create three different subdirectories, `sub1`, `sub2` and `sub3`,\nwithin the same function call. In contrast, if you provided such path\nas input to `makeDir()`, you would likely get an error as result, since\nthis method can only create a single subdirectory.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.makeDir(\"src\");\ntry cwd.makePath(\"src/decoders/jpg/\");\n```\n:::\n\n\n\n\n### Deleting directories\n\nTo delete a directory, just provide the path to the directory that you want to delete\nas input to the `deleteDir()` method from a `Dir` object. In the example below,\nwe are deleting the `src` directory that we have just created in the previous example.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.deleteDir(\"src\");\n```\n:::\n\n\n\n\n\n## Conclusion\n\nIn this chapter, I have described how to perform in Zig the most common filesystem and IO operations.\nBut you might feel the lack of some other, less common, operation in this chapter, such as: how to rename files,\nor how to open a directory, or how to create symbolic links, or how to use `access()` to test if a particular\npath exists in your computer. But for all of these less common tasks, I recommend you to read\nthe documentation of the [`Dir` type](https://ziglang.org/documentation/master/std/#std.fs.Dir)[^zig-dir]\n, since you can find a good description of these cases there.\n\n\n\n\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n\n# Filesystem and Input/Output (IO) {#sec-filesystem}\n\nIn this chapter we are going to discuss how to use the cross-platform structs and functions\nfrom the Zig Standard Library that can execute filesystem operations. Most of these functions and structs\ncomes from the `std.fs` module.\n\nWe are also going to talk about Input/Output (also known as IO) operations in Zig. Most of\nthese operations are made by using the structs and functions from `std.io` module, which defines\nfile descriptors for the *standard channels* of your system (`stdout` and `stdin`), and also,\nfunctions to create and use I/O streams.\n\n\n## Input/Output basics {#sec-io-basics}\n\nIf you have some experience in a high-level language, you have certainly used\nthese input and output functionalities before in this language. In other words, you certainly have\nbeen in a situation where you needed to sent some output to the user, or, to receive an input\nfrom the user.\n\nFor example, in Python we can receive some input from the user by using the `input()` built-in\nfunction. But we can also print (or \"show\") some output to the user by using the `print()`\nbuilt-in function. So yes, if you have programmed before in Python, you certainly have\nused these functions once before.\n\nBut do you know how these functions relate back to your operating system (OS)? How exactly\nthey are interacting with the resources of your OS to receive or sent some input/output.\nIn essence, these input/output functions from high-level languages are just abstractions\nover the *standard output* and *standard input* channels of your operating system.\n\nThis means that we receive an input, or send some output, through the operating system.\nIt's the OS that makes the bridge between the user and your program. Your program\ndoes not have a direct access to the user. It's the OS that intermediates every\nmessage exchanged between your program and the user.\n\nThe *standard output* and *standard input* channels of your OS are commonly known as the\n`stdout` and `stdin` channels of your OS, respectively. In some contexts, they are also\ncalled the *standard output device* and the *standard input device*. As the name suggests,\nthe *standard output* is the channel through which output flows, while the *standard input*\nis the channel in which input flows.\n\nFurthermore, OS's also normally create a dedicated channel for exchanging error messages, which is known as the\n*standard error* channel, or, the `stderr` channel. This is the channel to which error and warning messages\nare usually sent to. These are the messages that are normally displayed in red-like or orange-like colors\ninto your terminal.\n\nNormally, every OS (e.g. Windows, macOS, Linux, etc.) creates a dedicated and separate set of\n*standard output*, *standard error* and *standard input* channels for every single program (or process) that runs in your computer.\nThis means that every program you write have a dedicated `stdin`, `stderr` and `stdout` that are separate\nfrom the `stdin`, `stderr` and `stdout` of other programs and processes that are currently running.\n\nThis is a behaviour from your OS. This does not come from the programming language that you are using.\nBecause as I sad earlier, input and output in programming languages, especially\nin high-level ones, are just a simple abstraction over the `stdin`, `stderr` and `stdout` from your current OS.\nThat is, your OS is the intermediary between every input/output operation made in your program,\nregardless of the programming language that you are using.\n\n\n### The writer and reader pattern {#sec-writer-reader}\n\nIn Zig, there is a pattern around input/output (IO). I (the author of this book) don't know if there\nis an official name for this pattern. But here, in this book, I will call it the \"writer and reader pattern\".\nIn essence, every IO operation in Zig is made through either a `GenericReader` or a `GenericWriter` object[^gen-zig].\n\nThese two data types come from the `std.io` module of the Zig Standard Library. As their names suggests, a\n`GenericReader` is an object that offers tools to read data from \"something\" (or \"somewhere\"), while a `GenericWriter`\noffers tools to write data into this \"something\". This \"something\" might be different things: like a\nfile that exists in your filesystem; or, it might be a network socket in your system[^sock]; or,\na continuous stream of data, like a standard input device from your system, that might be constantly\nreceiving new data from users, or, as another example, a live chat in a game that is constantly\nreceiving and displaying new messages from the players of the game.\n\n[^gen-zig]: Previously, these objects were known as the `Reader` and `Writer` objects.\n[^sock]: The socket objects that we have created in @sec-create-socket, are examples of network sockets.\n\nSo, if you want to **read** data from something, or somewhere, it means that you need to use a `GenericReader` object.\nBut if you need instead, to **write** data into this \"something\", then, you need to use a `GenericWriter` object instead.\nBoth of these objects are normally created from a file descriptor object. More specifically, through the `writer()` and `reader()`\nmethods of this file descriptor object. If you are not familiar with this type of object, go to the next section.\n\nEvery `GenericWriter` object have methods like `print()`, which allows you to write/send a formatted string\n(i.e., this formatted string is like a `f` string in Python, or, similar to the `printf()` C function)\ninto the \"something\" (file, socket, stream, etc.) that you are using. It also have a `writeAll()` method, which allows you to\nwrite a string, or, an array of bytes into the \"something\".\n\nLikewise, every `GenericReader` object have methods like `readAll()`, which allows you to read the\ndata from the \"something\" (file, socket, stream, etc.) until it fills a particular array (i.e., a \"buffer\") object.\nIn other words, if you provide an array object of 300 `u8` values to `readAll()`, then, this method attempts to read 300 bytes\nof data from the \"something\", and it stores them into the array object that you have provided.\n\nWe also have other methods, like the `readAtLeast()` method, which allows you to specify how\nmany bytes exactly you want to read from the \"something\". In more details, if you give the\nnumber $n$ as input to this method, then, it will attempt to read at least $n$ bytes of data\nfrom the \"something\". The \"something\" might have less than $n$ bytes of data available for you\nto read, so, it's not guaranteed that you will get precisely $n$ bytes as result.\n\nAnother useful method is `readUntilDelimiterOrEof()`. In this method, you specify a \"delimiter character\".\nThe idea is that this function will attempt to read as many bytes of data as possible from the \"something\",\nuntil it encounters the end of the stream, or, it encounters the \"delimiter character\" that you have specified.\n\nIf you don't know exactly how many bytes will come from the \"something\", you may find the `readAllAlloc()` method\nuseful. In essence, you provide an allocator object to this method, so that it can allocate more space if needed.\nAs consequence, this method will try to read all bytes of the \"something\", and, if it runs out of space at some point\nduring the \"reading process\", it uses the allocator object to allocate more space to continue reading the bytes.\nAs result, this method returns a slice to the array object containing all the bytes read.\n\nThis is just a quick description of the methods present in these types of objects. But I recommend you\nto read the official docs, both for\n[`GenericWriter`](https://ziglang.org/documentation/master/std/#std.io.GenericWriter)[^gen-write] and\n[`GenericReader`](https://ziglang.org/documentation/master/std/#std.io.GenericReader)[^gen-read].\nI also think it's a good idea to read the source code of the modules in the Zig Standard Library\nthat defines the methods present in these objects, which are the\n[`Reader.zig`](https://github.com/ziglang/zig/blob/master/lib/std/io/Reader.zig)[^mod-read]\nand [`Writer.zig`]()[^mod-write].\n\n[^gen-read]: <https://ziglang.org/documentation/master/std/#std.io.GenericReader>.\n[^gen-write]: <https://ziglang.org/documentation/master/std/#std.io.GenericWriter>.\n[^mod-read]: <https://github.com/ziglang/zig/blob/master/lib/std/io/Reader.zig>.\n[^mod-write]: <https://github.com/ziglang/zig/blob/master/lib/std/io/Writer.zig>.\n\n\n\n### Introducing file descriptors {#sec-file-descriptor}\n\nA \"file descriptor\" object is a core component behind every IO operation that is made in any operating system (OS).\nSuch object is an identifier for a particular input/output (IO) resource from your OS [@wiki_file_descriptor].\nIt describes and identifies this particular resource. An IO resource might be:\n\n- an existing file in your filesystem.\n- an existing network socket.\n- other types of stream channels.\n- a pipeline (or just \"pipe\") in your terminal[^pipes].\n\n[^pipes]: A pipeline is a mechanism for inter-process communication, or, inter-process IO. You could also interpret a pipeline as a \"set of processes that are chained together, through the standard input/output devices of the system\". At Linux for example, a pipeline is created inside a terminal, by connecting two or more terminal commands with the \"pipe\" character (`|`).\n\nFrom the bullet points listed above, we know that although the term \"file\" is present,\na \"file descriptor\" might describe something more than just a file.\nThis concept of a \"file descriptor\" comes from the Portable Operating System Interface (POSIX) API,\nwhich is a set of standards that guide how operating systems across the world should be implemented,\nto maintain compatibility between them.\n\nA file descriptor not only identifies the input/output resource that you are using to receive or send some data,\nbut it also describes where this resource is, and also, which IO mode this resource is currently using.\nFor example, this IO resource might be using only the \"read\" IO mode, which means that this resource\nis open to \"read operations\", while \"write operations\" are not authorized.\nThese IO modes are essentially the modes that you provide to the argument `mode`\nfrom the `fopen()` C function, and also, from the `open()` Python built-in function.\n\nIn C, a \"file descriptor\" is a `FILE` pointer, but, in Zig, a file descriptor is a `File` object.\nThis data type (`File`) is described in the `std.fs` module of the Zig Standard Library.\nWe normally don't create a `File` object directly in our Zig code. Instead, we normally get such object as result when we\nopen an IO resource. In other words, we normally ask our OS to open a particular IO resource for us,\nand, if the OS do open successfully this IO resource, the OS normally handles back to us\na file descriptor to this particular IO resource.\n\nSo you usually get a `File` object by using functions and methods from the Zig Standard Library\nthat asks the OS to open some IO resource, like the `openFile()` method that opens a file in the\nfilesystem. The `net.Stream` object that we have created in @sec-create-socket is also a type of\nfile descriptor object.\n\n\n### The *standard output*\n\nYou already saw across this book, how can we access and use specifically the `stdout` in Zig\nto send some output to the user.\nFor that, we use the `getStdOut()` function from the `std.io` module. This function returns\na file descriptor that describes the `stdout` channel of your current OS. Through this file\ndescriptor object, we can read from or write stuff to the `stdout` of our program.\n\nAlthough we can read stuff recorded into the `stdout` channel, we normally only\nwrite to (or \"print\") stuff into this channel. The reason is very similar to what we discussed at\n@sec-read-http-message, when we were discussing what \"reading from\" versus \"writing to\" the connection\nobject from our small HTTP Server project would mean.\n\nWhen we write stuff into a channel, we are essentially sending data to the other end of this channel.\nIn contrast, when we read stuff from this channel, we are essentially reading the data that was sent\nthrough this channel. Since the `stdout` is a channel to send output to the user, the key verb here\nis **send**. We want to send something to someone, and, as consequence, we want to **write** something\ninto some channel.\n\nThat is why, when we use `getStdOut()`, most of the times, we also use the `writer()` method from the `stdout` file descriptor,\nto get access to a writer object that we can use to write stuff into this `stdout` channel.\nMore specifically, this `writer()` method returns a `GenericWriter` object. One of the\nmain methods of this `GenericWriter` object is the `print()` method that we have used\nbefore to write (or \"print\") a formatted string into the `stdout` channel.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    try stdout.writeAll(\n        \"This message was written into stdout.\\n\"\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nThis message was written into stdout.\n```\n\n\n:::\n:::\n\n\n\n\n\n\nThis `GenericWriter` object is like any other generic writer object that you would normally get from a file descriptor object.\nSo, the same methods from a generic writer object that you would use while writing files to the filesystem for example, you could also\nuse them here, from the file descriptor object of `stdout`, and vice-versa.\n\n\n### The *standard input*\n\nYou can access the *standard input* (i.e., `stdin`) in Zig by using the `getStdIn()` function from the `std.io` module.\nLike its brother (`getStdOut()`), this function also returns a file descriptor object that describes the `stdin` channel\nof your OS.\n\nBecause we want to receive some input from the user, the key verb here becomes **receive**, and, as consequence,\nwe usually want to **read** data from the `stdin` channel, instead of writing data into it. So, we normally use\nthe `reader()` method of the file descriptor object returned by `getStdIn()`, to get access to a `GenericReader`\nobject that we can use to read data from `stdin`.\n\nIn the example below, we are creating a small buffer capable of holding 20 characters. Then, we try to read\nthe data from the `stdin` with the `readUntilDelimiterOrEof()` method, and save this data into the `buffer` object.\nAlso notice that we are reading the data from the `stdin` until we hit a new line character (`'\\n'`).\n\nIf you execute this program, you will notice that it stops the execution, ands start to wait indefinitely\nfor some input from the user. In other words, you need to type your name into the terminal, and then, you press Enter to\nsend your name to `stdin`. After you send your name to `stdin`, the program reads this input, and continues with the execution,\nby printing the given name to `stdout`. In the example below, I typed my name (Pedro) into the terminal, and then, pressed Enter.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst stdin = std.io.getStdIn().reader();\npub fn main() !void {\n    try stdout.writeAll(\"Type your name\\n\");\n    var buffer: [20]u8 = undefined;\n    @memset(buffer[0..], 0);\n    _ = try stdin.readUntilDelimiterOrEof(buffer[0..], '\\n');\n    try stdout.print(\"Your name is: {s}\\n\", .{buffer});\n}\n```\n:::\n\n\n\n\n```\nType your name\nYour name is: Pedro\n\n```\n\n\n### The *standard error*\n\nThe *standard error* (a.k.a. the `stderr`) works exactly the same as `stdout` and `stdin`.\nYou just call the `getStdErr()` function from the `std.io` module, and you get the file descriptor to `stderr`.\nIdeally, you should write only error or warning messages to `stderr`, because this is\nthe purpose of this channel.\n\n\n\n\n\n## Buffered IO\n\nAs we described in @sec-io-basics, input/output (IO) operations are made directly by the operating system.\nIt's the OS that manages the IO resource that you want to use for your IO operations.\nThe consequence of this fact is that IO operations are heavily based on system calls (i.e., calling the operating system directly).\n\nJust to be clear, there is nothing particularly wrong with system calls. We use them all the time on\nany serious codebase written in any low-level programming language. However, system calls are\nalways orders of magnitude slower than many different types of operations.\n\nSo is perfectly fine to use a system call once in a while. But when these system calls are used often,\nyou can clearly notice most of the time the loss of performance in your application. So, the good rule of thumb\nis to use a system call only when it's needed, and also, only in infrequent situations, to reduce\nthe number of system calls performed to a minimum.\n\n\n### Understanding how buffered IO works\n\nBuffered IO is a strategy to achieve better performance. It's used to reduce the number of system calls made by IO operations, and, as\nconsequence, achieve a much higher performance. In @fig-unbuffered-io and @fig-buffered-io you can find two different diagrams\nwhich presents the difference between read operations performed in an unbuffered IO environment versus a buffered IO environment.\n\nTo give a better context to these diagrams, let's suppose that we have a text file that contains the famous Lorem ipsum text[^lorem]\nin our filesystem. Let's also suppose that these diagrams in @fig-unbuffered-io and @fig-buffered-io\nare showing the read operations that we are performing to read the Lorem ipsum text from this text file.\nThe first thing you will notice when looking at these diagrams, is that in an unbuffered environment\nthe read operations leads to many system calls.\nMore precisely, in the diagram exposed in @fig-unbuffered-io we get one system call per each byte that we read from the text file.\nOn the other hand, in @fig-buffered-io we have only one system call at the very beginning.\n\nWhen we use a buffered IO system, at the first read operation we perform, instead of sending one single byte directly\nto our program, the OS first sends a chunk of bytes from the file to a buffer object (i.e., an array).\nThis chunk of bytes are cached/stored inside this buffer object.\n\nTherefore, from now on, for every new read operation that you perform, instead of making a new system call to ask\nfor the next byte in the file to the OS, this read operation is redirected to the buffer object, that have\nthis next byte already cached and ready to go.\n\n\n[^lorem]: <https://www.lipsum.com/>.\n\n\n![Unbuffered IO](./../Figures/unbuffered-io.png){#fig-unbuffered-io width=60%}\n\n![Buffered IO](./../Figures/buffered-io.png){#fig-buffered-io}\n\n\n\nThis is the basic logic behind buffered IO systems. The size of the buffer object depends on multiple factors. But it's usually\nequal to the size of a full page of memory (4096 bytes). If we follow this logic, then, the OS reads the first 4096 bytes\nof the file and caches it into the buffer object. As long as your program does not consume all of these 4096 bytes from the buffer,\nyou will not create new system calls.\n\nHowever, as soon as you consume all of these 4096 bytes from the buffer, it means that there is no bytes left in the buffer.\nIn this situation, a new system call is made to ask the OS to send the next 4096 bytes in the file, and once again,\nthese bytes are cached into the buffer object, and the cycle starts once again.\n\n\n### Buffered IO across different languages\n\nIO operations made through a `FILE` pointer in C are buffered\nby default, so, at least in C, you don't need to worry about this subject. But in contrast, IO operations in both Rust and Zig are not\nbuffered depending on which functions from the standard libraries that you are using.\n\nFor example, in Rust, buffered IO is implemented through the `BufReader` and `BufWriter` structs, while in Zig, it's implemented\nthrough the `BufferedReader` and `BufferedWriter` structs.\nSo any IO operation that you perform through the `GenericWriter` and `GenericReader` objects\nthat I presented in @sec-writer-reader are not buffered, which means that these objects\nmight create a lot of system calls depending on the situation.\n\n\n### Using buffered IO in Zig\n\nUsing buffered IO in Zig is actually very easy. All you have to do is to just\ngive the `GenericWriter` object to the `bufferedWriter()` function, or, to give the `GenericReader`\nobject to the `bufferedReader()` function. These functions come from the `std.io` module,\nand they will construct the `BufferedWriter` or `BufferedReader` object for you.\n\nAfter you create this new `BufferedWriter` or `BufferedReader` object, you can call the `writer()`\nor `reader()` method of this new object, to get access to a new (and buffered) generic reader or\ngeneric writer.\n\nLet's describe the process once again. Every time that you have a file descriptor object, you first get the generic writer or generic reader\nobject from it, by calling the `writer()` or `reader()` methods of this file descriptor object.\nThen, you provide this generic writer or generic reader to the `bufferedWriter()` or `bufferedReader()`\nfunction, which creates a new `BufferedWriter` or `BufferedReader` object. Then, you call\nthe `writer()` or `reader()` methods of this buffered writer or buffered reader object,\nwhich gives you access to a generic writer or a generic reader object that is buffered.\n\nTake this program as an example. This program is demonstrating the process exposed in @fig-buffered-io.\nWe are simply opening a text file that contains the Lorem ipsum text, and then, we create a buffered IO reader object\nat `bufreader`, and we use this `bufreader` object to read the contents of this file into a buffer object, then,\nwe end the program by printing this buffer to `stdout`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar file = try std.fs.cwd().openFile(\n    \"ZigExamples/file-io/lorem.txt\", .{}\n);\ndefer file.close();\nvar buffered = std.io.bufferedReader(file.reader());\nvar bufreader = buffered.reader();\n\nvar buffer: [1000]u8 = undefined;\n@memset(buffer[0..], 0);\n\n_ = try bufreader.readUntilDelimiterOrEof(\n    buffer[0..], '\\n'\n);\ntry stdout.print(\"{s}\\n\", .{buffer});\n```\n:::\n\n\n\n\n```\nLorem ipsum dolor sit amet, consectetur\nadipiscing elit. Sed tincidunt erat sed nulla ornare, nec\naliquet ex laoreet. Ut nec rhoncus nunc. Integer magna metus,\nultrices eleifend porttitor ut, finibus ut tortor. Maecenas\nsapien justo, finibus tincidunt dictum ac, semper et lectus.\nVivamus molestie egestas orci ac viverra. Pellentesque nec\narcu facilisis, euismod eros eu, sodales nisl. Ut egestas\nsagittis arcu, in accumsan sapien rhoncus sit amet. Aenean\nneque lectus, imperdiet ac lobortis a, ullamcorper sed massa.\nNullam porttitor porttitor erat nec dapibus. Ut vel dui nec\nnulla vulputate molestie eget non nunc. Ut commodo luctus ipsum,\nin finibus libero feugiat eget. Etiam vel ante at urna tincidunt\nposuere sit amet ut felis. Maecenas finibus suscipit tristique.\nDonec viverra non sapien id suscipit.\n```\n\nDespite being a buffered IO reader, this `bufreader` object is similar to any other `GenericReader` object,\nand have the exact same methods. So, although these two types of objects perform very different IO operations,\nthey have the same interface, so you, the programmer, can interchangeably use them\nwithout the need to change anything in your source code.\nSo a buffered IO reader or a buffered IO writer objects have the same methods than its generic and unbuffered brothers,\ni.e., the generic reader and generic writer objects that I presented in @sec-writer-reader.\n\n::: {.callout-tip}\nIn general, you should always use a buffered IO reader or a buffered IO writer object to perform\nIO operations in Zig. Because they deliver better performance to your IO operations.\n:::\n\n\n## Filesystem basics\n\nNow that we have discussed the basics around Input/Output operations in Zig, we need to\ntalk about the basics around filesystems, which is another core part of any operating system.\nAlso, filesystems are related to input/output, because the files that we store and create in our\ncomputer are considered an IO resource, as we described in @sec-file-descriptor.\n\n\n### The concept of current working directory (CWD)\n\nThe working directory is the folder on your computer where you are currently rooted at.\nIn other words, it's the folder that your program is currently looking at.\nTherefore, whenever you are executing a program, this program is always working with\na specific folder on your computer. It's always in this folder that the program will initially\nlook for the files you require, and it's also in this folder that the program\nwill initially save all the files you ask it to save.\n\nThe working directory is determined by the folder from which you invoke your program\nin the terminal. In other words, if you are in the terminal of your OS, and you\nexecute a binary file (i.e., a program) from this terminal, the folder to which your terminal\nis pointing at is the current working directory of your program that is being executed.\n\nIn @fig-cwd we have an example of me executing a program from the terminal. We are executing\nthe program outputted by the `zig` compiler by compiling the Zig module named `hello.zig`.\nThe CWD in this case is the `zig-book` folder. In other words, while the `hello.zig` program\nis executing, it will be looking at the `zig-book` folder, and any file operation that we perform\ninside this program, will be using this `zig-book` folder as the \"starting point\", or, as the \"central focus\".\n\n![Executing a program from the terminal](./../Figures/cwd.png){#fig-cwd}\n\nJust because we are rooted inside a particular folder (in the case of @fig-cwd, the `zig-book` folder) of our computer,\nit doesn't mean that we cannot access or write resources in other locations of our computer.\nThe current working directory (CWD) mechanism just defines where your program will look first\nfor the files you ask for. This does not prevent you from accessing files that are located\nelsewhere on your computer. However, to access any file that is in a folder other than your\ncurrent working directory, you must provide a path to that file or folder.\n\n\n### The concept of paths\n\nA path is essentially a location. It points to a location in your filesystem. We use\npaths to describe the location of files and folders in our computer.\nOne important aspect about paths is that they are always written inside strings,\ni.e., they are always provided as text values.\n\nThere are two types of paths that you can provide to any program in any OS: a relative path, or an absolute path.\nAbsolute paths are paths that start at the root of your filesystem, and go all the way to the file name or the specific folder\nthat you are referring to. This type of path is called absolute, because it points to an unique and absolute location on your computer.\nThat is, there is no other existing location on your computer that corresponds to this path. It's an unique identifier.\n\nIn Windows, an absolute path is a path that starts with a hard disk identifier (e.g. `C:/Users/pedro`).\nOn the other hand, absolute paths in Linux and macOS, are paths that start with a forward slash character (e.g. `/usr/local/bin`).\nNotice that a path is composed by \"segments\". Each segment is connected to each other by a slash character (`\\` or `/`).\nOn Windows, the backward slash (`\\`) is normally used to connect the path segments. While on Linux and macOS, the forward\nslash (`/`) is the character used to connect path segments.\n\nA relative path is a path that start at the CWD. In other words, a relative path is\n\"relative to the CWD\". The path used to access the `hello.zig` file in @fig-cwd is an example of a relative path. This path\nis reproduced below. This path begins at the CWD, which in the context of @fig-cwd, is the `zig-book` folder,\nthen, it goes to the `ZigExamples` folder, then, into `zig-basics`, then, to the `hello.zig` file.\n\n```\nZigExamples/zig-basics/hello_world.zig\n```\n\n\n### Path wildcards\n\nWhen providing paths, especially relative paths, you have the option of using a *wildcard*.\nThere are two commonly used *wildcards* in paths, which are \"one period\" (.) and \"two periods\" (..).\nIn other words, these two specific characters have special meanings when used in paths,\nand can be used on any operating system (Mac, Windows, Linux, etc.). That is, they\nare \"cross platform\".\n\nThe \"one period\" represents an alias for the current directory.\nThis means that the relative paths `\"./Course/Data/covid.csv\"` and `\"Course/Data/covid.csv\"` are equivalent.\nOn the other hand, the \"two periods\" refers to the previous directory.\nFor example, the path `\"Course/..\"` is equivalent to the path `\".\"`, that is, the current working directory.\n\nTherefore, the path `\"Course/..\"` refers to the folder before the `Course` folder.\nAs another example, the path `\"src/writexml/../xml.cpp\"` refers to the file `xml.cpp`\nthat is inside the folder before the `writexml` folder, which in this example is the `src` folder.\nTherefore, this path is equivalent to `\"src/xml.cpp\"`.\n\n\n\n\n## The CWD handler\n\nIn Zig, filesystem operations are usually made through a directory handler object.\nA directory handler in Zig is an object of type `Dir`, which is an object that describes\na particular folder in the filesystem of our computer.\nYou normally create a `Dir` object, by calling the `std.fs.cwd()` function.\nThis function returns a `Dir` object that points to (or, that describes) the\ncurrent working directory (CWD).\n\nThrough this `Dir` object, you can create new files, or modify, or read existing ones that are\ninside your CWD. In other words, a `Dir` object is the main entrypoint in Zig to perform\nmultiple types of filesystem operations.\nIn the example below, we are creating this `Dir` object, and storing it\ninside the `cwd` object. Although we are not using this object at this code example,\nwe are going to use it a lot over the next examples.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\n_ = cwd;\n```\n:::\n\n\n\n\n\n\n\n\n\n\n\n## File operations\n\n### Creating files {#sec-creating-files}\n\nWe create new files by using the `createFile()` method from the `Dir` object.\nJust provide the name of the file that you want to create, and this function will\ndo the necessary steps to create such file. You can also provide a relative path to this function,\nand it will create the file by following this path, which is relative to the CWD.\n\nThis function might return an error, so, you should use `try`, `catch`, or any of the other methods presented\nin @sec-error-handling to handle the possible error. But if everything goes well,\nthis `createFile()` method returns a file descriptor object (i.e., a `File` object) as result,\nthrough which you can add content to the file with the IO operations that I presented before.\n\nTake this code example below. In this example, we are creating a new text file\nnamed `foo.txt`. If the function `createFile()` succeeds, the object named `file` will contain a file descriptor\nobject, which we can use to write (or add) new content to the file, like we do in this example, by using\na buffered writer object to write a new line of text to the file.\n\nNow, a quick note, when we create a file descriptor object in C, by using a C function like `fopen()`, we must always close the file\nat the end of our program, or, as soon as we complete all operations that we wanted to perform\non the file. In Zig, this is no different. So everytime we create a new file, this file remains\n\"open\", waiting for some operation to be performed. As soon as we are done with it, we always have\nto close this file, to free the resources associated with it.\nIn Zig, we do this by calling the method `close()` from the file descriptor object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.createFile(\"foo.txt\", .{});\n// Don't forget to close the file at the end.\ndefer file.close();\n// Do things with the file ...\nvar fw = file.writer();\n_ = try fw.writeAll(\n    \"Writing this line to the file\\n\"\n);\n```\n:::\n\n\n\n\n\nSo, in this example we not only have created a file into the filesystem,\nbut we also wrote some data into this file, using the file descriptor object\nreturned by `createFile()`. If the file that you are trying to create\nalready exists in your filesystem, this `createFile()` call will\noverwrite the contents of the file, or, in other words, it will\nin erase all the contents of the existing file.\n\nIf you don't want this to happen, meaning, that you don't want to overwrite\nthe contents of the existing file, but you want to write data to this file anyway\n(i.e., you want to append data to the file), you should use the `openFile()`\nmethod from the `Dir` object.\n\nAnother important aspect about `createFile()` is that this method creates a file\nthat is not open to read operations by default. It means that you cannot read this file.\nYou are not allowed to.\nSo for example, you might want to write some stuff into this file at the beginning of the execution\nof your program. Then, at a future point in your program you might need to read what you\nwrote in this file. If you try to read data from this file, you will likely\nget a `NotOpenForReading` error as result.\n\n\nBut how can you overcome this barrier? How can you create a file that is open\nto read operations? All you have to do, is to set the `read` flag to true\nin the second argument of `createFile()`. When you set this flag to true,\nthen the file gets create with \"read permissions\", and, as consequence,\na program like this one below becomes valid:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.createFile(\n    \"foo.txt\",\n    .{ .read = true }\n);\ndefer file.close();\n\nvar fw = file.writer();\n_ = try fw.writeAll(\"We are going to read this line\\n\");\n\nvar buffer: [300]u8 = undefined;\n@memset(buffer[0..], 0);\ntry file.seekTo(0);\nvar fr = file.reader();\n_ = try fr.readAll(buffer[0..]);\ntry stdout.print(\"{s}\\n\", .{buffer});\n```\n:::\n\n\n\n\n\n```\nWe are going to read this line\n```\n\n\nIf you are not familiar with position indicators, you might not recognize the method\n`seekTo()`. If that is your case, do not worry,\nwe are going to talk more about this method in @sec-indicators. But essentially\nthis method is moving the position indicator back to the beginning of the file,\nso that we can read the contents of the file from the beginning.\n\n\n### Opening files and appending data to it\n\nOpening files is easy. Just use the `openFile()` method instead of `createFile()`.\nIn the first argument of `openFile()` you provide the path to the file that\nyou want to open. Then, on the second argument you provide the flags (or, the options)\nthat dictates how the file is opened.\n\nYou can see the full list of options for `openFile()` by visiting the documentation for\n[`OpenFlags`](https://ziglang.org/documentation/master/std/#std.fs.File.OpenFlags)[^oflags].\nBut the main flag that you will most certainly use is the `mode` flag.\nThis flag specifies the IO mode that the file will be using when it gets opened.\nThere are three IO modes, or, three values that you can provide to this flag, which are:\n\n- `read_only`, allows only read operations on the file. All write operations are blocked.\n- `write_only`, allows only write operations on the file. All read operations are blocked.\n- `read_write`, allows both write and read operations on the file.\n\n[^oflags]: <https://ziglang.org/documentation/master/std/#std.fs.File.OpenFlags>\n\nThese modes are similar to the modes that you provide to the `mode` argument of the\n`open()` Python built-in function[^py-open], or, the `mode` argument of the\n`fopen()` C function[^c-open].\nIn the code example below, we are opening the `foo.txt` text file with a `write_only` mode,\nand appending a new line of text to the end of the file. We use `seekFromEnd()` this time\nto guarantee that we are going to append the text to the end of the file. Once again, methods\nsuch as `seekFromEnd()` are described in more depth in @sec-indicators.\n\n[^py-open]: <https://docs.python.org/3/tutorial/inputoutput.html#reading-and-writing-files>\n[^c-open]: <https://www.tutorialspoint.com/c_standard_library/c_function_fopen.htm>\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.openFile(\n    \"foo.txt\", .{ .mode = .write_only }\n);\ndefer file.close();\ntry file.seekFromEnd(0);\nvar fw = file.writer();\n_ = try fw.writeAll(\"Some random text to write\\n\");\n```\n:::\n\n\n\n\n\n### Deleting files\n\nSometimes, we just need to delete/remove the files that we have.\nTo do that, we use the `deleteFile()` method. You just provide the path of the\nfile that you want to delete, and this method will try to delete the file located\nat this path.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.deleteFile(\"foo.txt\");\n```\n:::\n\n\n\n\n### Copying files\n\nTo copy existing files, we use the `copyFile()` method. The first argument in this method\nis the path to the file that you want to copy. The second argument is a `Dir` object, i.e., a directory handler,\nmore specifically, a `Dir` object that points to the folder in your computer where you want to\ncopy the file to. The third argument is the new path of the file, or, in other words, the new location\nof the file. The fourth argument is the options (or flags) to be used in the copy operation.\n\nThe `Dir` object that you provide as input to this method will be used to copy the file to\nthe new location. You may create this `Dir` object before calling the `copyFile()` method.\nMaybe you are planning to copy the file to a completely different location in your computer,\nso it might be worth to create a directory handler to that location. But if you are copying the\nfile to a subfolder of your CWD, then, you can just simply pass the CWD handler to this argument.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.copyFile(\n    \"foo.txt\",\n    cwd,\n    \"ZigExamples/file-io/foo.txt\",\n    .{}\n);\n```\n:::\n\n\n\n\n\n### Read the docs!\n\nThere are some other useful methods for file operations available at `Dir` objects,\nsuch as the `writeFile()` method, but I recommend you to read the docs for the\n[`Dir` type](https://ziglang.org/documentation/master/std/#std.fs.Dir)[^zig-dir]\nto explore the other available methods, since I already talked too much about them.\n\n\n[^zig-dir]: <https://ziglang.org/documentation/master/std/#std.fs.Dir>\n\n\n\n\n## Position indicators {#sec-indicators}\n\nA position indicator is like a type of cursor, or, an index. This \"index\" identifies the current\nlocation in the file (or, in the data stream) that the file descriptor object that you have\nis currently looking at.\nWhen you create a file descriptor, the position indicator starts at the beginning of the file,\nor, at the beginning of the stream. When you read from or write into the file (or socket, or data stream, etc.)\ndescribed by this file descriptor object, you end up moving the position indicator.\n\nIn other words, any IO operation have a common side effect, which is to move the position indicator.\nFor example, suppose that we have a file of 300 bytes total in size. If you\nread 100 bytes from the file, then, the position indicator moves 100 bytes forward. If you try\nto write 50 bytes into this same file, these 50 bytes will be written from the current\nposition indicated by the position indicator. Since the indicator is at a 100 bytes forward from\nthe beginning of the file, these 50 bytes would be written in the middle of the file.\n\nThis is why we have used the `seekTo()` method at the last code example presented in @sec-creating-files.\nWe have used this method to move the position indicator back to the beginning of the file, which\nwould make sure that we would write the text that we wanted to write from the beginning of the file,\ninstead of writing it from the middle of the file. Because before the write operation, we had\nperformed a read operation, which means that the position indicator was moved in this read operation.\n\nThe position indicators of a file descriptor object can be changed (or altered) by using the\n\"seek\" methods from this file descriptor, which are: `seekTo()`, `seekFromEnd()` and `seekBy()`.\nThese methods have the same effect, or, the same responsibility that the\n[`fseek()`](https://en.cppreference.com/w/c/io/fseek)[^c-fseek] C function.\n\n[^c-fseek]: <https://en.cppreference.com/w/c/io/fseek>\n\n\nConsidering that `offset` refers to the index that you provide as input to these \"seek\" methods,\nthe bullet points below summarises what is the effect of each of these methods.\nAs a quick note, in the case of `seekFromEnd()` and `seekBy()`, the `offset` provided can be either a\npositive or a negative index.\n\n- `seekTo()` will move the position indicator to the location that is `offset` bytes from the beginning of the file.\n- `seekFromEnd()` will move the position indicator to the location that is `offset` bytes from the end of the file.\n- `seekBy()` will move the position indicator to the location that is `offset` bytes from the current position in the file.\n\n\n\n\n\n\n\n## Directory operations\n\n### Iterating through the files in a directory\n\nOne of the most classic tasks related to filesystem is to be able\nto iterate through the existing files in a directory. To iterate over the\nfiles in a directory, we need to create an iterator object.\n\nYou can produce such iterator object by using either the `iterate()` or `walk()` methods\nof a `Dir` object. Both methods return an iterator object as output, which you can advance by using the\n`next()` method. The difference between these methods, is that `iterate()` returns a non-recursive iterator,\nwhile `walk()` does. It means that the iterator returned by `walk()` will not only iterate through\nthe files available in the current directory, but also, through the files from any subdirectory found\ninside the current directory.\n\nIn the example below, we are displaying the names of the files stored inside the\ndirectory `ZigExamples/file-io`. Notice that we had to open this directory through\nthe `openDir()` function. Also notice that we provided the flag `iterate` in the\nsecond argument of `openDir()`. This flag is important, because without this flag,\nwe would not be allowed to iterate through the files in this directory.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst dir = try cwd.openDir(\n    \"ZigExamples/file-io/\",\n    .{ .iterate = true }\n);\nvar it = dir.iterate();\nwhile (try it.next()) |entry| {\n    try stdout.print(\n        \"File name: {s}\\n\",\n        .{entry.name}\n    );\n}\n```\n:::\n\n\n\n\n```\nFile name: create_file_and_write_toit.zig\nFile name: create_file.zig\nFile name: lorem.txt\nFile name: iterate.zig\nFile name: delete_file.zig\nFile name: append_to_file.zig\nFile name: user_input.zig\nFile name: foo.txt\nFile name: create_file_and_read.zig\nFile name: buff_io.zig\nFile name: copy_file.zig\n```\n\n\n### Creating new directories\n\nThere are two methods that are important when it comes to\ncreating directories, which are `makeDir()` and `makePath()`.\nThe difference between these two methods is that `makeDir()` can\nonly create one single directory in the current directory in each call,\nwhile `makePath()` is capable of recursively create subdirectories in the same call.\n\n\nThis is why the name of this method is \"make path\". It will create as many\nsubdirectories as necessary to create the path that you provided as input.\nSo, if you provide the path `\"sub1/sub2/sub3\"` as input to this method,\nit will create three different subdirectories, `sub1`, `sub2` and `sub3`,\nwithin the same function call. In contrast, if you provided such path\nas input to `makeDir()`, you would likely get an error as result, since\nthis method can only create a single subdirectory.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.makeDir(\"src\");\ntry cwd.makePath(\"src/decoders/jpg/\");\n```\n:::\n\n\n\n\n### Deleting directories\n\nTo delete a directory, just provide the path to the directory that you want to delete\nas input to the `deleteDir()` method from a `Dir` object. In the example below,\nwe are deleting the `src` directory that we have just created in the previous example.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.deleteDir(\"src\");\n```\n:::\n\n\n\n\n\n## Conclusion\n\nIn this chapter, I have described how to perform in Zig the most common filesystem and IO operations.\nBut you might feel the lack of some other, less common, operation in this chapter, such as: how to rename files,\nor how to open a directory, or how to create symbolic links, or how to use `access()` to test if a particular\npath exists in your computer. But for all of these less common tasks, I recommend you to read\nthe documentation of the [`Dir` type](https://ziglang.org/documentation/master/std/#std.fs.Dir)[^zig-dir]\n, since you can find a good description of these cases there.\n",
+    "supporting": [
+      "12-file-op_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/13-image-filter/execute-results/html.json b/_freeze/Chapters/13-image-filter/execute-results/html.json
index 94161bf3..5564dfd4 100644
--- a/_freeze/Chapters/13-image-filter/execute-results/html.json
+++ b/_freeze/Chapters/13-image-filter/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "913ef6c1f2a988d49f8b7ce026c813b6",
+  "hash": "99b3cf5d4ae363f25838f780686e3234",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 4 - Developing an image filter\n\nIn this chapter we are going to build a new project. The objective of\nthis project is to write a program that applies a filter over an image.\nMore specifically, a \"grayscale filter\", which transforms\nany color image into a grayscale image.\n\nWe are going to use the image displayed at @fig-pascal in this project.\nIn other words, we want to transform this colored image into a grayscale image,\nby using our \"image filter program\" written in Zig.\n\n![A photo of the chilean-american actor Pedro Pascal. Source: Google Images.](../ZigExamples/image_filter/pedro_pascal.png){#fig-pascal}\n\nWe don't need to write a lot of code to build such \"image filter program\". However, we first need\nto understand how digital images work. That is why we begin this chapter\nby explaining the theory behind digital images and how colors are represented in modern computers.\nWe also give a brief explanation about the PNG (Portable Network Graphics) file format, which is the format used\nin the example images.\n\nAt the end of this chapter, we should have a full example of a program that takes the PNG image displayed at @fig-pascal\nas input, and writes a new image to the current working directory that is the grayscale version of this input image.\nThis grayscale version of @fig-pascal is exposed at @fig-pascal-gray.\nYou can find the full source code of this small project at the `ZigExamples/image_filter`\n[folder at the official repository of this book](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter)[^img-filter-folder].\n\n\n![The grayscale version of the photo.](../ZigExamples/image_filter/pedro_pascal_filter.png){#fig-pascal-gray}\n\n\n## How we see things? {#sec-eyes}\n\nIn this section, I want to briefly describe to you how we (humans) actually see things with our own eyes.\nI mean, how our eyes work? If you do have a very basic understanding of how our eyes work, you will understand\nmore easily how digital images are made. Because the techniques behind digital images\nwere developed by taking a lot of inspiration from how our human eyes work.\n\nYou can interpret a human eye as a light sensor, or, a light receptor. The eye receives some amount of light as input,\nand it interprets the colors that are present in this \"amount of light\".\nIf no amount of light hits the eye, then, the eye cannot extract color from it, and as result,\nwe end up seeing nothing, or, more precisely, we see complete blackness.\n\nTherefore, everything depends on light. What we actually see are the colors (blue, red, orange, green, purple, yellow, etc.) that\nare being reflected from the light that is hitting our eyes. **Light is the source of all colors!**\nThis is what Isaac Newton discovered on his famous prism experiment[^newton] in the 1660s.\n\n[^newton]: <https://library.si.edu/exhibition/color-in-a-new-light/science>\n\nInside our eyes, we have a specific type of cell called the \"cone cell\".\nOur eye have three different types, or, three different versions of these \"cone cells\".\nEach type of cone cell is very sensitive to a specific spectrum of the light. More specifically,\nto the spectrums that define the colors red, green and blue.\nSo, in summary, our eyes have specific types of cells that\nare highly sensitive to these three colors (red, green and blue).\n\nThese are the cells responsible for perceiving the color present in the light that hits our eyes.\nAs a result, our eyes perceives color as a mixture of these three colors (red, green and blue). By having an amount\nof each one of these three colors, and mixing them together, we can get any other visible color\nthat we want. So every color that we see is perceived as a specific mixture of blues, greens and reds,\nlike 30% of red, plus 20% of green, plus 50% of blue.\n\nWhen these cone cells perceive (or, detect) the colors that are found in the\nlight that is hitting our eyes, these cells produce electrical signals, which are sent to the brain.\nOur brain interprets these electrical signals, and use them to form the image that we are seeing\ninside our head.\n\nBased on what we have discussed here, the bullet points exposed below describes the sequence of events that\ncomposes this very simplified version of how our human eyes work:\n\n1. Light hits our eyes.\n1. The cone cells perceive the colors that are present in this light.\n1. Cone cells produce electrical signals that describes the colors that were perceived in the light.\n1. The electrical signals are sent to the brain.\n1. Brain interprets these signals, and form the image based on the colors identified by these electrical signals.\n\n\n## How digital images work? {#sec-digital-img}\n\nA digital image is a \"digital representation\" of an image that we see with our eyes.\nIn other words, a digital image is a \"digital representation\" of the colors that we see\nand perceive through the light.\nIn the digital world, we have two types of images, which are: vector images and raster images.\nVector images are not described here. So just remember that the content discussed here\n**is related solely to raster images**, and not vector images.\n\nA raster image is a type of digital image that is represented as a 2D (two dimensional) matrix\nof pixels. In other words, every raster image is basically a rectangle of pixels, and each pixel have a particular color.\nSo, a raster image is just a rectangle of pixels, and each of these pixels are displayed in the screen of your computer (or the screen\nof any other device, e.g. laptop, tablet, smartphone, etc.) as a color.\n\n@fig-raster demonstrates this idea. If you take any raster image, and you zoom into it very hard,\nyou will see the actual pixels of the image. JPEG, TIFF and PNG are file formats that are commonly\nused to store raster images.\n\n![Zooming over a raster image to see the pixels. Source: Google Images.](../Figures/imagem-raster.png){#fig-raster}\n\nThe more pixels the image has, the more information and detail we can include in the image.\nThe more accurate, sharp and pretty the image will look. This is why photographic cameras\nusually produce big raster images, with several megapixels of resolution, to include as much detail as possible into the final image.\nAs an example, a digital image with dimensions of 1920 pixels wide and 1080 pixels high, would be a image that\ncontains $1920 \\times 1080 = 2073600$ pixels in total. You could also say that the \"total area\" of the image is\nof 2073600 pixels, although the concept of \"area\" is not really used here in computer graphics.\n\nMost digital images we see in our modern world uses the RGB color model. RGB stands for (red, green and blue).\nSo the color of each pixel in these raster images are usually represented as a mixture of red, green and blue,\njust like in our eyes. That is, the color of each pixel is identified by a set of\nthree different integer values. Each integer value identifies the \"amount\" of each color (red, green and blue).\nFor example, the set `(199, 78, 70)` identifies a color that is more close to red. We have 199 of red, 78 of green,\nand 70 of blue. In contrast, the set `(129, 77, 250)` describes a color that is more close to purple. Et cetera.\n\n\n\n### Images are displayed from top to bottom\n\nThis is not a rule written in stone, but the big majority of digital images are displayed from top\nto bottom and left to right. Most computers screens also follow this pattern. So, the first pixels\nin the image are the ones that are at the top and left corner of the image. You can find a visual representation\nof this logic at @fig-img-display.\n\nAlso notice in @fig-img-display that, because a raster image is essentially a 2D matrix of pixels,\nthe image is organized into rows and columns of pixels. The columns are defined by the horizontal x axis,\nwhile the rows are defined by the vertical y axis.\n\nEach pixel (i.e. the gray rectangles) exposed at @fig-img-display contains a number inside of it.\nThese numbers are the indexes of the pixels. You can notice that the first pixels are in the top and left\ncorner, and also, that the indexes of these pixels \"grow to the sides\", or, in other words, they grow in the direction of the horizontal x axis.\nMost raster images are organized as rows of pixels. Thus, when these digital images are\ndisplayed, the screen display the first row of pixels, then, the second row, then, the third row, etc.\n\n![How the pixels of raster images are displayed.](./../Figures/image-display.png){#fig-img-display}\n\n\n\n\n\n\n### Representing the matrix of pixels in code {#sec-pixel-repr}\n\nOk, we know already that raster images are represented as 2D matrices of pixels.\nBut we do not have a notion of a 2D matrix in Zig. Actually, most low-level languages in general\n(Zig, C, Rust, etc.) do not have such notion.\nSo how can we represent such matrix of pixels in Zig, or any other low-level language?\nThe strategy that most programmers choose in this situation is to just use a normal 1D array to store the values of\nthis 2D matrix. In other words, you just create an normal 1D array, and store all values from both dimensions into this 1D array.\n\nAs an example, suppose we have a very small image of dimensions 4x3.\nSince a raster image is represented as a 2D matrix of pixels, and each pixel\nis represented by 3 \"unsigned 8-bit\" integer values, we have 12 pixels in\ntotal in this image, which are represented by $3 \\times 12 = 36$ integer values.\nTherefore, we need to create an array of 36 `u8` values to store this small image.\n\nThe reason why unsigned 8-bit integer (`u8`) values are used to represent the amounts of each color,\ninstead of any other integer type, is because they take the minimum amount of space as possible, or,\nthe minimum amount of bits as possible. Which helps to reduces the binary size of the image, i.e. the 2D matrix.\nAlso, they convey a good amount of precision and detail about the colors, even though they can represent\na relatively small range (from 0 to 255) of \"color amounts\".\n\nComing back to our initial example of a 4x3 image,\nthe `matrix` object exposed below could be an example of an 1D array that stores\nthe data that represents this 4x3 image.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst matrix = [_]u8{\n    201, 10, 25, 185, 65, 70,\n    65, 120, 110, 65, 120, 117,\n    98, 95, 12, 213, 26, 88,\n    143, 112, 65, 97, 99, 205,\n    234, 105, 56, 43, 44, 216,\n    45, 59, 243, 211, 209, 54,\n};\n```\n:::\n\n\n\n\nThe first three integer values in this array are the color amounts of the first pixel in the image.\nThe next three integers are the colors amounts for the second pixel.\nAnd the sequence goes on in this pattern. Having that in mind, the size of the array that stores\na raster image is usually a multiple of 3. In this case, the array have a size of 36.\n\nI mean, the size of the array is **usually** a multiple of 3, because in specific circumstances,\nit can also be a multiple of 4. This happens when a transparency amount is\nalso included into the raster image. In other words, there are some types of raster images\nthat uses a different color model, which is the RGBA (red, green, blue and alpha)\ncolor model. The \"alpha\" corresponds to an amount of transparency in the pixel.\nSo every pixel in a RGBA image is represented by a red, green, blue and alpha values.\n\nMost raster images uses the standard RGB model, so, for the most part, you will\nsee arrays sizes that are multiples of 3. But some images, especially the ones\nthat are stored in PNG files, might be using the RGBA model, and, therefore, are\nrepresented by an array whose size is a multiple of 4.\n\nIn our case here, the example image of our project (@fig-pascal) is a raster image\nstored in a PNG file, and this specific image is using the RGBA color model. Therefore,\neach pixel in the image is represented by 4 different integer values, and, as consequence,\nto store this image in our Zig code, we need to create an array whose size is a multiple of 4.\n\n\n## The PNG library that we are going to use\n\nLet's begin our project by focusing on writing the necessary Zig code to\nread the data from the PNG file. In other words, we want to read the PNG file exposed\nat @fig-pascal, and parse its data to extract the 2D matrix of pixels that represents the image.\n\nAs we have discussed at @sec-pixel-repr, the image that we are using as example here\nis a PNG file that uses the RGBA color model, and, therefore, each pixel of the image\nis represented by 4 integer values. You can download this image by visiting the `ZigExamples/image_filter`\n[folder at the official repository of this book](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter)[^img-filter-folder].\nYou can also find in this folder the complete source code of this small project that we\nare developing here.\n\n[^img-filter-folder]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter>\n\nThere are some C libraries available that we can use to read and parse PNG files.\nThe most famous and used of all is `libpng`, which is the \"official library\" for reading and writing\nPNG files. Although this library is available on most operating system, it is well known\nfor being complex and hard to use.\n\nThat is why, I'm going to use a more modern alternative here in this project, which is the `libspng` library.\nI choose to use this C library here, because it is much, much simpler to use than `libpng`,\nand it also offers very good performance for all operations. You can checkout the\n[official website of the library](https://libspng.org/)[^libspng]\nto know more about it. You will also find there some documentation that might help you to understand and\nfollow the code examples exposed here.\n\n[^libspng]: <https://libspng.org/>\n\n\nFirst of all, remember to build and install this `libspng` into your system. Because\nif you don't do this step, the `zig` compiler will not be able to find the files and resources of\nthis library in your computer, and link them with the Zig source code that we are writing together here.\nThere is good information about how to build and install the library at the\n[build section of the library documentation](https://libspng.org/docs/build/)[^lib-build].\n\n[^lib-build]: <https://libspng.org/docs/build/>\n\n\n\n\n## Reading the PNG file\n\nIn order to extract the pixel data from the PNG file, we need to read and decode the file.\nA PNG file is just a binary file written in the \"PNG format\". Luckily, the `libspng` library offers\na function called `spng_decode_image()` that does all this heavy work for us.\n\nNow, since `libspng` is a C library, most of the file and I/O operations in this library are made by using\na `FILE` C pointer. Because of that, is probably a better idea to use the `fopen()` C function\nto open our PNG file, instead of using the `openFile()` method that I introduced at @sec-filesystem.\nThat is why I'm importing the `stdio.h` C header in this project, and using the `fopen()` C function to open the file.\n\nIf you look at the snippet below, you can see that we are:\n\n1. opening the PNG file with `fopen()`.\n1. creating the `libspng` context with `spng_ctx_new()`.\n1. using `spng_set_png_file()` to specify the `FILE` object that reads the PNG file that we are going to use.\n\nEvery operation in `libspng` is made through a \"context object\". In our snippet below, this object is `ctx`.\nAlso, to perform an operation over a PNG file, we need to specify which exact PNG file we are referring to.\nThis is the job of `spng_set_png_file()`. We are using this function to specify the file descriptor\nobject that reads the PNG file that we want to use.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n    @cInclude(\"spng.h\");\n});\n\nconst path = \"pedro_pascal.png\";\nconst file_descriptor = c.fopen(path, \"rb\");\nif (file_descriptor == null) {\n    @panic(\"Could not open file!\");\n}\nconst ctx = c.spng_ctx_new(0) orelse unreachable;\n_ = c.spng_set_png_file(\n    ctx, @ptrCast(file_descriptor)\n);\n```\n:::\n\n\n\n\nBefore we continue, is important to emphasize the following: since we have opened the file with `fopen()`,\nwe have to remember to close the file at the end of the program, with `fclose()`.\nIn other words, after we have done everything that we wanted to do with the PNG file\n`pedro_pascal.png`, we need to close this file, by applying `fclose()` over the file descriptor object.\nWe could use also the `defer` keyword to help us in this task, if we want to.\nThis code snippet below demonstrates this step:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (c.fclose(file_descriptor) != 0) {\n    return error.CouldNotCloseFileDescriptor;\n}\n```\n:::\n\n\n\n\n\n\n\n### Reading the image header section\n\nNow, the context object `ctx` is aware of our PNG file `pedro_pascal.png`, because it has access to\na file descriptor object to this file. The first thing that we are going to do is to read the\n\"image header section\" of the PNG file. This \"image header section\" is the section\nof the file that contains some basic information about the PNG file, like, the bit depth of the pixel data\nof the image, the color model used in the file, the dimensions of the image (height and width in number of pixels),\netc.\n\nTo make things easier, I will encapsulate this \"read image header\" operation into a\nnice and small function called `get_image_header()`. All that this function needs to do\nis to call the `spng_get_ihdr()` function. This function from `libspng` is responsible\nfor reading the image header data, and storing it into a C struct named `spng_ihdr`.\nThus, an object of type `spng_ihdr` is a C struct that contains the data from the\nimage header section of the PNG file.\n\nSince this Zig function is receiving a C object (the `libspng` context object) as input, I marked\nthe function argument `ctx` as \"a pointer to the context object\" (`*c.spng_ctx`), following the recommendations\nthat we have discussed at @sec-pass-c-structs.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn get_image_header(ctx: *c.spng_ctx) !c.spng_ihdr {\n    var image_header: c.spng_ihdr = undefined;\n    if (c.spng_get_ihdr(ctx, &image_header) != 0) {\n        return error.CouldNotGetImageHeader;\n    }\n\n    return image_header;\n}\n\nvar image_header = try get_image_header(ctx);\n```\n:::\n\n\n\n\nAlso notice in this function, that I'm checking if the `spng_get_ihdr()` function call have\nreturned or not an integer value that is different than zero. Most functions from the\n`libspng` library return a code status as result, and the code status \"zero\" means\n\"success\". So any code status that is different than zero means that an error\noccurred while running `spng_get_ihdr()`. This is why I'm returning an error value from\nthe function in case the code status returned by the function is different than zero.\n\n\n### Allocating space for the pixel data\n\nBefore we read the pixel data from the PNG file, we need to allocate enough space to hold this data.\nBut in order to allocate such space, we first need to know how much space we need to allocate.\nThe dimensions of the image are obviously needed to calculate the size of this space. But there are\nother elements that also affect this number, such as the color model used in the image, the bit depth, and others.\n\nAnyway, all of this means that calculating the size of the space that we need, is not a simple task.\nThat is why the `libspng` library offers an utility function named\n`spng_decoded_image_size()` to calculate this size for us. Once again, I'm going\nto encapsulate the logic around this C function into a nice and small Zig function\nnamed `calc_output_size()`. You can see below that this function returns a nice\ninteger value as result, informing the size of the space that we need to allocate.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn calc_output_size(ctx: *c.spng_ctx) !u64 {\n    var output_size: u64 = 0;\n    const status = c.spng_decoded_image_size(\n        ctx, c.SPNG_FMT_RGBA8, &output_size\n    );\n    if (status != 0) {\n        return error.CouldNotCalcOutputSize;\n    }\n    return output_size;\n}\n```\n:::\n\n\n\n\n\n\nYou might quest yourself what the value `SPNG_FMT_RGBA8` means. This value is actually an enum\nvalue defined in the `spng.h` C header file. This enum is used to identify a \"PNG format\".\nMore precisely, it identifies a PNG file that uses the RGBA color model and 8 bit depth.\nSo, by providing this enum value as input to the `spng_decoded_image_size()` function,\nwe are saying to this function to calculate the size of the decoded pixel data, by considering\na PNG file that follows this \"RGBA color model with 8 bit depth\" format.\n\nHaving this function, we can use it in conjunction with an allocator object, to allocate an\narray of bytes (`u8` values) that is big enough to store the decoded pixel data of the image.\nNotice that I'm using `@memset()` to initialize the entire array to zero.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst output_size = try calc_output_size(ctx);\nvar buffer = try allocator.alloc(u8, output_size);\n@memset(buffer[0..], 0);\n```\n:::\n\n\n\n\n\n### Decoding the image data\n\nNow that we have the necessary space to store the decoded pixel data of the image,\nwe can start to actually decode and extract this pixel data from the image,\nby using the `spng_decode_image()` C function.\n\nThe `read_data_to_buffer()` Zig function exposed below summarises the necessary\nsteps to read this decoded pixel data, and store it into an input buffer.\nNotice that this function is encapsulating the logic around the `spng_decode_image()` function.\nAlso, we are using the `SPNG_FMT_RGBA8` enum value once again to inform the corresponding function,\nthat the PNG image being decoded, uses the RGBA color model and 8 bit depth.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn read_data_to_buffer(ctx: *c.spng_ctx, buffer: []u8) !void {\n    const status = c.spng_decode_image(\n        ctx,\n        buffer.ptr,\n        buffer.len,\n        c.SPNG_FMT_RGBA8,\n        0\n    );\n\n    if (status != 0) {\n        return error.CouldNotDecodeImage;\n    }\n}\n```\n:::\n\n\n\n\nHaving this function at hand, we can apply it over our context object, and also, over\nthe buffer object that we have allocated in the previous section to hold the decoded pixel data\nof the image:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry read_data_to_buffer(ctx, buffer[0..]);\n```\n:::\n\n\n\n\n\n### Looking at the pixel data\n\nNow that we have the pixel data stored in our \"buffer object\", we can take\na quick look at the bytes. In the example below, we are looking at the first\n12 bytes in the decoded pixel data.\n\nIf you take a close look at these values, you might notice that every 4 bytes\nin the sequence is 255. Which, coincidentally is the maximum possible integer value\nto be represented by a `u8` value. So, if the range from 0 to 255, which is the range\nof integer values that can be represented by an `u8` value, can be represented as a scale from 0% to 100%,\nthese 255 values are essentially 100% in that scale.\n\nIf you recall from @sec-pixel-repr, I have\ndescribed in that section that our `pedro_pascal.png` PNG file uses the RGBA color model,\nwhich adds an alpha (or transparency) byte to each pixel in the image.\nAs consequence, each pixel in the image is represented by 4 bytes. Since we are looking\nhere are the first 12 bytes in the image, it means that we are looking at the data from\nthe first $12 / 4 = 3$ pixels in the image.\n\nSo, based on how these first 12 bytes (or these 3 pixels) look, with these 255 values at every 4 bytes, we can say that is likely\nthat every pixel in the image have alpha (or transparency) setted to 100%. This might not be true,\nbut, is the most likely possibility. Also, if we look at the image itself, which if your recall is\nexposed at @fig-pascal, we can see that the transparency does not change across the image,\nwhich enforces this theory.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry stdout.print(\"{any}\\n\", .{buffer[0..12]});\n```\n:::\n\n\n\n\n```\n{\n    200, 194, 216, 255, 203, 197,\n    219, 255, 206, 200, 223, 255\n}\n```\n\n\nWe can see in the above result that the first pixel in this image have 200 of red, 194 of green, and 216 of blue.\nHow do I know the order in which the colors appears in the sequence? If you have not guessed that yet,\nis because of the acronym RGB. First RED, then GREEN, then BLUE. If we scale these integer values\naccording to our scale of 0% to 100% (0 to 255), we get 78% of red, 76% of green and 85% of blue.\n\n\n\n## Applying the image filter\n\nNow that we have the data of each pixel in the image, we can focus on applying our image\nfilter over these pixels. Remember, our objective here is to apply a grayscale filter over\nthe image. A grayscale filter is a filter that transforms a colored image into a grayscale image.\n\nThere are different formulas and strategies to transform a colored image into a grayscale image.\nBut all of these different strategies normally involve applying some math over the colors of each pixel.\nIn this project, we are going to use the most general formula, which is exposed below.\nThis formula considers $r$ as the red of the pixel, $g$ as the green, $b$ as the blue, and $p'$ as the\nlinear luminance of the pixel.\n\n$$\n    p' = (0.2126 \\times r) + (0.7152 \\times g) + (0.0722 \\times b)\n$${#eq-grayscale}\n\nThis @eq-grayscale is the formula to calculate the linear luminance of a pixel. Is worth noting that this formula\nworks only for images whose pixels are using the sRGB color space, which is the standard color space\nfor the web. Thus, ideally, all images on the web should use this color space. Luckily,\nthis is our case here, i.e. the `pedro_pascal.png` image is using this sRGB color space, and, as consequence,\nwe can use the @eq-grayscale. You can read more about this formula at the Wikipedia page for grayscale [@wiki_grayscale].\n\nThe `apply_image_filter()` function exposed below summarises the necessary steps to\napply @eq-grayscale over the pixels in the image. We just apply this function\nover our buffer object that contains our pixel data, and, as result, the pixel\ndata stored in this buffer object should now represent the grayscale version of our image.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn apply_image_filter(buffer:[]u8) !void {\n    const len = buffer.len;\n    const red_factor: f16 = 0.2126;\n    const green_factor: f16 = 0.7152;\n    const blue_factor: f16 = 0.0722;\n    var index: u64 = 0;\n    while (index < len) : (index += 4) {\n        const rf: f16 = @floatFromInt(buffer[index]);\n        const gf: f16 = @floatFromInt(buffer[index + 1]);\n        const bf: f16 = @floatFromInt(buffer[index + 2]);\n        const y_linear: f16 = (\n            (rf * red_factor) + (gf * green_factor)\n            + (bf * blue_factor)\n        );\n        buffer[index] = @intFromFloat(y_linear);\n        buffer[index + 1] = @intFromFloat(y_linear);\n        buffer[index + 2] = @intFromFloat(y_linear);\n    }\n}\n\ntry apply_image_filter(buffer[0..]);\n```\n:::\n\n\n\n\n\n\n## Saving the grayscale version of the image\n\nSince we have now the grayscale version of our image stored in our buffer object,\nwe need to encode this buffer object back into the \"PNG format\", and save the encoded data into\na new PNG file in our filesystem, so that we can access and see the grayscale version of our image\nthat was produced by our small program.\n\nTo do that, the `libspng` library help us once again by offering an \"encode data to PNG\" type of function,\nwhich is the `spng_encode_image()` function. But in order to \"encode data to PNG\" with `libspng`, we need\nto create a new context object. This new context object must use an \"encoder context\", which\nis identified by the enum value `SPNG_CTX_ENCODER`.\n\nThe `save_png()` function exposed below, summarises all the necessary steps to save the\ngrayscale version of our image into a new PNG file in the filesystem. By default, this\nfunction will save the grayscale image into a file named `pedro_pascal_filter.png` in the CWD.\n\nNotice in this code example that we are using the same image header object (`image_header`) that we have\ncollected previously with the `get_image_header()` function. Remember, this image header object\nis a C struct (`spng_ihdr`) that contains basic information about our PNG file, such as\nthe dimensions of the image, the color model used, etc.\n\nIf we wanted to save a very different image in this new PNG file, e.g. an image\nwith different dimensions, or, an image that uses a different color model, a different bit depth, etc.\nwe would have to create a new image header (`spng_ihdr`) object that describes the properties\nof this new image.\n\nBut we are essentially saving the same image that we have begin with here (the dimensions of\nthe image, the color model, etc. are all still the same). The only difference\nbetween the two images are the colors of the pixels, which are now \"shades of gray\".\nAs consequence, we can safely use the exact same image header data in this new PNG file.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn save_png(image_header: *c.spng_ihdr, buffer: []u8) !void {\n    const path = \"pedro_pascal_filter.png\";\n    const file_descriptor = c.fopen(path.ptr, \"wb\");\n    if (file_descriptor == null) {\n        return error.CouldNotOpenFile;\n    }\n    const ctx = (\n        c.spng_ctx_new(c.SPNG_CTX_ENCODER)\n        orelse unreachable\n    );\n    defer c.spng_ctx_free(ctx);\n    _ = c.spng_set_png_file(ctx, @ptrCast(file_descriptor));\n    _ = c.spng_set_ihdr(ctx, image_header);\n\n    const encode_status = c.spng_encode_image(\n        ctx,\n        buffer.ptr,\n        buffer.len,\n        c.SPNG_FMT_PNG,\n        c.SPNG_ENCODE_FINALIZE\n    );\n    if (encode_status != 0) {\n        return error.CouldNotEncodeImage;\n    }\n    if (c.fclose(file_descriptor) != 0) {\n        return error.CouldNotCloseFileDescriptor;\n    }\n}\n\ntry save_png(&image_header, buffer[0..]);\n```\n:::\n\n\n\n\nAfter we execute this `save_png()` function, we should have a new PNG file\ninside our CWD, named `pedro_pascal_filter.png`. If we open this PNG file,\nwe will see the same image exposed at @fig-pascal-gray.\n\n\n## Building our project\n\nNow that we have written the code, let's discuss how can we build/compile this project.\nTo do that, I'm going to create a `build.zig` file in the root directory of our project,\nand start writing the necessary code to compile the project, using the knowledge\nthat we have acquired from @sec-build-system.\n\n\nWe first create the build target for our executable file, that executes our\nZig code. Let's suppose that all of our Zig code was written into a Zig module\nnamed `image_filter.zig`. The `exe` object exposed in the build script below\ndescribes the build target for our executable file.\n\nSince we have used some C code from the `libspng` library in our Zig code,\nwe need to link our Zig code (which is in the `exe` build target) to both\nthe C Standard Library, and, to the `libspng` library. We do that, by calling\nthe `linkLibC()` and `linkSystemLibrary()` methods from our `exe` build target.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const target = b.standardTargetOptions(.{});\n    const optimize = b.standardOptimizeOption(.{});\n    const exe = b.addExecutable(.{\n        .name = \"image_filter\",\n        .root_source_file = b.path(\"src/image_filter.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n    exe.linkLibC();\n    // Link to libspng library:\n    exe.linkSystemLibrary(\"spng\");\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\nSince we are using the `linkSystemLibrary()` method, it means that the library\nfiles for `libspng` are searched in your system to be linked with the `exe` build target.\nIf you have not yet built and installed the `libspng` library into your system, this\nlinkage step will likely not work. Because it will not find the library files in your system.\n\nSo, just remember to install `libspng` in your system, if you want to build this project.\nHaving this build script above written, we can finally build our project by\nrunning the `zig build` command in the terminal.\n\n```bash\nzig build\n```\n\n\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 4 - Developing an image filter\n\nIn this chapter we are going to build a new project. The objective of\nthis project is to write a program that applies a filter over an image.\nMore specifically, a \"grayscale filter\", which transforms\nany color image into a grayscale image.\n\nWe are going to use the image displayed in @fig-pascal in this project.\nIn other words, we want to transform this colored image into a grayscale image,\nby using our \"image filter program\" written in Zig.\n\n![A photo of the chilean-american actor Pedro Pascal. Source: Google Images.](../ZigExamples/image_filter/pedro_pascal.png){#fig-pascal}\n\nWe don't need to write a lot of code to build such \"image filter program\". However, we first need\nto understand how digital images work. That is why we begin this chapter\nby explaining the theory behind digital images and how colors are represented in modern computers.\nWe also give a brief explanation about the PNG (Portable Network Graphics) file format, which is the format used\nin the example images.\n\nAt the end of this chapter, we should have a full example of a program that takes the PNG image displayed in @fig-pascal\nas input, and writes a new image to the current working directory that is the grayscale version of this input image.\nThis grayscale version of @fig-pascal is exposed in @fig-pascal-gray.\nYou can find the full source code of this small project at the `ZigExamples/image_filter`\n[folder at the official repository of this book](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter)[^img-filter-folder].\n\n\n![The grayscale version of the photo.](../ZigExamples/image_filter/pedro_pascal_filter.png){#fig-pascal-gray}\n\n\n## How we see things? {#sec-eyes}\n\nIn this section, I want to briefly describe to you how we (humans) actually see things with our own eyes.\nI mean, how our eyes work? If you do have a very basic understanding of how our eyes work, you will understand\nmore easily how digital images are made. Because the techniques behind digital images\nwere developed by taking a lot of inspiration from how our human eyes work.\n\nYou can interpret a human eye as a light sensor, or, a light receptor. The eye receives some amount of light as input,\nand it interprets the colors that are present in this \"amount of light\".\nIf no amount of light hits the eye, then, the eye cannot extract color from it, and as result,\nwe end up seeing nothing, or, more precisely, we see complete blackness.\n\nTherefore, everything depends on light. What we actually see are the colors (blue, red, orange, green, purple, yellow, etc.) that\nare being reflected from the light that is hitting our eyes. **Light is the source of all colors!**\nThis is what Isaac Newton discovered on his famous prism experiment[^newton] in the 1660s.\n\n[^newton]: <https://library.si.edu/exhibition/color-in-a-new-light/science>\n\nInside our eyes, we have a specific type of cell called the \"cone cell\".\nOur eye have three different types, or, three different versions of these \"cone cells\".\nEach type of cone cell is very sensitive to a specific spectrum of the light. More specifically,\nto the spectrums that define the colors red, green and blue.\nSo, in summary, our eyes have specific types of cells that\nare highly sensitive to these three colors (red, green and blue).\n\nThese are the cells responsible for perceiving the color present in the light that hits our eyes.\nAs a result, our eyes perceives color as a mixture of these three colors (red, green and blue). By having an amount\nof each one of these three colors, and mixing them together, we can get any other visible color\nthat we want. So every color that we see is perceived as a specific mixture of blues, greens and reds,\nlike 30% of red, plus 20% of green, plus 50% of blue.\n\nWhen these cone cells perceive (or, detect) the colors that are found in the\nlight that is hitting our eyes, these cells produce electrical signals, which are sent to the brain.\nOur brain interprets these electrical signals, and use them to form the image that we are seeing\ninside our head.\n\nBased on what we have discussed here, the bullet points exposed below describes the sequence of events that\ncomposes this very simplified version of how our human eyes work:\n\n1. Light hits our eyes.\n1. The cone cells perceive the colors that are present in this light.\n1. Cone cells produce electrical signals that describes the colors that were perceived in the light.\n1. The electrical signals are sent to the brain.\n1. Brain interprets these signals, and form the image based on the colors identified by these electrical signals.\n\n\n## How digital images work? {#sec-digital-img}\n\nA digital image is a \"digital representation\" of an image that we see with our eyes.\nIn other words, a digital image is a \"digital representation\" of the colors that we see\nand perceive through the light.\nIn the digital world, we have two types of images, which are: vector images and raster images.\nVector images are not described here. So just remember that the content discussed here\n**is related solely to raster images**, and not vector images.\n\nA raster image is a type of digital image that is represented as a 2D (two dimensional) matrix\nof pixels. In other words, every raster image is basically a rectangle of pixels, and each pixel have a particular color.\nSo, a raster image is just a rectangle of pixels, and each of these pixels are displayed in the screen of your computer (or the screen\nof any other device, e.g. laptop, tablet, smartphone, etc.) as a color.\n\n@fig-raster demonstrates this idea. If you take any raster image, and you zoom into it very hard,\nyou will see the actual pixels of the image. JPEG, TIFF and PNG are file formats that are commonly\nused to store raster images.\n\n![Zooming over a raster image to see the pixels. Source: Google Images.](../Figures/imagem-raster.png){#fig-raster}\n\nThe more pixels the image has, the more information and detail we can include in the image.\nThe more accurate, sharp and pretty the image will look. This is why photographic cameras\nusually produce big raster images, with several megapixels of resolution, to include as much detail as possible into the final image.\nAs an example, a digital image with dimensions of 1920 pixels wide and 1080 pixels high, would be a image that\ncontains $1920 \\times 1080 = 2073600$ pixels in total. You could also say that the \"total area\" of the image is\nof 2073600 pixels, although the concept of \"area\" is not really used here in computer graphics.\n\nMost digital images we see in our modern world uses the RGB color model. RGB stands for (red, green and blue).\nSo the color of each pixel in these raster images are usually represented as a mixture of red, green and blue,\njust like in our eyes. That is, the color of each pixel is identified by a set of\nthree different integer values. Each integer value identifies the \"amount\" of each color (red, green and blue).\nFor example, the set `(199, 78, 70)` identifies a color that is more close to red. We have 199 of red, 78 of green,\nand 70 of blue. In contrast, the set `(129, 77, 250)` describes a color that is more close to purple. Et cetera.\n\n\n\n### Images are displayed from top to bottom\n\nThis is not a rule written in stone, but the big majority of digital images are displayed from top\nto bottom and left to right. Most computers screens also follow this pattern. So, the first pixels\nin the image are the ones that are at the top and left corner of the image. You can find a visual representation\nof this logic in @fig-img-display.\n\nAlso notice in @fig-img-display that, because a raster image is essentially a 2D matrix of pixels,\nthe image is organized into rows and columns of pixels. The columns are defined by the horizontal x axis,\nwhile the rows are defined by the vertical y axis.\n\nEach pixel (i.e., the gray rectangles) exposed in @fig-img-display contains a number inside of it.\nThese numbers are the indexes of the pixels. You can notice that the first pixels are in the top and left\ncorner, and also, that the indexes of these pixels \"grow to the sides\", or, in other words, they grow in the direction of the horizontal x axis.\nMost raster images are organized as rows of pixels. Thus, when these digital images are\ndisplayed, the screen display the first row of pixels, then, the second row, then, the third row, etc.\n\n![How the pixels of raster images are displayed.](./../Figures/image-display.png){#fig-img-display}\n\n\n\n\n\n\n### Representing the matrix of pixels in code {#sec-pixel-repr}\n\nOk, we know already that raster images are represented as 2D matrices of pixels.\nBut we do not have a notion of a 2D matrix in Zig. Actually, most low-level languages in general\n(Zig, C, Rust, etc.) do not have such notion.\nSo how can we represent such matrix of pixels in Zig, or any other low-level language?\nThe strategy that most programmers choose in this situation is to just use a normal 1D array to store the values of\nthis 2D matrix. In other words, you just create an normal 1D array, and store all values from both dimensions into this 1D array.\n\nAs an example, suppose we have a very small image of dimensions 4x3.\nSince a raster image is represented as a 2D matrix of pixels, and each pixel\nis represented by 3 \"unsigned 8-bit\" integer values, we have 12 pixels in\ntotal in this image, which are represented by $3 \\times 12 = 36$ integer values.\nTherefore, we need to create an array of 36 `u8` values to store this small image.\n\nThe reason why unsigned 8-bit integer (`u8`) values are used to represent the amounts of each color,\ninstead of any other integer type, is because they take the minimum amount of space as possible, or,\nthe minimum amount of bits as possible. Which helps to reduces the binary size of the image, i.e., the 2D matrix.\nAlso, they convey a good amount of precision and detail about the colors, even though they can represent\na relatively small range (from 0 to 255) of \"color amounts\".\n\nComing back to our initial example of a 4x3 image,\nthe `matrix` object exposed below could be an example of an 1D array that stores\nthe data that represents this 4x3 image.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst matrix = [_]u8{\n    201, 10, 25, 185, 65, 70,\n    65, 120, 110, 65, 120, 117,\n    98, 95, 12, 213, 26, 88,\n    143, 112, 65, 97, 99, 205,\n    234, 105, 56, 43, 44, 216,\n    45, 59, 243, 211, 209, 54,\n};\n```\n:::\n\n\n\n\nThe first three integer values in this array are the color amounts of the first pixel in the image.\nThe next three integers are the colors amounts for the second pixel.\nAnd the sequence goes on in this pattern. Having that in mind, the size of the array that stores\na raster image is usually a multiple of 3. In this case, the array have a size of 36.\n\nI mean, the size of the array is **usually** a multiple of 3, because in specific circumstances,\nit can also be a multiple of 4. This happens when a transparency amount is\nalso included into the raster image. In other words, there are some types of raster images\nthat uses a different color model, which is the RGBA (red, green, blue and alpha)\ncolor model. The \"alpha\" corresponds to an amount of transparency in the pixel.\nSo every pixel in a RGBA image is represented by a red, green, blue and alpha values.\n\nMost raster images uses the standard RGB model, so, for the most part, you will\nsee arrays sizes that are multiples of 3. But some images, especially the ones\nthat are stored in PNG files, might be using the RGBA model, and, therefore, are\nrepresented by an array whose size is a multiple of 4.\n\nIn our case here, the example image of our project (@fig-pascal) is a raster image\nstored in a PNG file, and this specific image is using the RGBA color model. Therefore,\neach pixel in the image is represented by 4 different integer values, and, as consequence,\nto store this image in our Zig code, we need to create an array whose size is a multiple of 4.\n\n\n## The PNG library that we are going to use\n\nLet's begin our project by focusing on writing the necessary Zig code to\nread the data from the PNG file. In other words, we want to read the PNG file exposed\nin @fig-pascal, and parse its data to extract the 2D matrix of pixels that represents the image.\n\nAs we have discussed in @sec-pixel-repr, the image that we are using as example here\nis a PNG file that uses the RGBA color model, and, therefore, each pixel of the image\nis represented by 4 integer values. You can download this image by visiting the `ZigExamples/image_filter`\n[folder at the official repository of this book](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter)[^img-filter-folder].\nYou can also find in this folder the complete source code of this small project that we\nare developing here.\n\n[^img-filter-folder]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter>\n\nThere are some C libraries available that we can use to read and parse PNG files.\nThe most famous and used of all is `libpng`, which is the \"official library\" for reading and writing\nPNG files. Although this library is available on most operating system, it's well known\nfor being complex and hard to use.\n\nThat is why, I'm going to use a more modern alternative here in this project, which is the `libspng` library.\nI choose to use this C library here, because it's much, much simpler to use than `libpng`,\nand it also offers very good performance for all operations. You can checkout the\n[official website of the library](https://libspng.org/)[^libspng]\nto know more about it. You will also find there some documentation that might help you to understand and\nfollow the code examples exposed here.\n\n[^libspng]: <https://libspng.org/>\n\n\nFirst of all, remember to build and install this `libspng` into your system. Because\nif you don't do this step, the `zig` compiler will not be able to find the files and resources of\nthis library in your computer, and link them with the Zig source code that we are writing together here.\nThere is good information about how to build and install the library at the\n[build section of the library documentation](https://libspng.org/docs/build/)[^lib-build].\n\n[^lib-build]: <https://libspng.org/docs/build/>\n\n\n\n\n## Reading the PNG file\n\nIn order to extract the pixel data from the PNG file, we need to read and decode the file.\nA PNG file is just a binary file written in the \"PNG format\". Luckily, the `libspng` library offers\na function called `spng_decode_image()` that does all this heavy work for us.\n\nNow, since `libspng` is a C library, most of the file and I/O operations in this library are made by using\na `FILE` C pointer. Because of that, is probably a better idea to use the `fopen()` C function\nto open our PNG file, instead of using the `openFile()` method that I introduced in @sec-filesystem.\nThat is why I'm importing the `stdio.h` C header in this project, and using the `fopen()` C function to open the file.\n\nIf you look at the snippet below, you can see that we are:\n\n1. opening the PNG file with `fopen()`.\n1. creating the `libspng` context with `spng_ctx_new()`.\n1. using `spng_set_png_file()` to specify the `FILE` object that reads the PNG file that we are going to use.\n\nEvery operation in `libspng` is made through a \"context object\". In our snippet below, this object is `ctx`.\nAlso, to perform an operation over a PNG file, we need to specify which exact PNG file we are referring to.\nThis is the job of `spng_set_png_file()`. We are using this function to specify the file descriptor\nobject that reads the PNG file that we want to use.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n    @cInclude(\"spng.h\");\n});\n\nconst path = \"pedro_pascal.png\";\nconst file_descriptor = c.fopen(path, \"rb\");\nif (file_descriptor == null) {\n    @panic(\"Could not open file!\");\n}\nconst ctx = c.spng_ctx_new(0) orelse unreachable;\n_ = c.spng_set_png_file(\n    ctx, @ptrCast(file_descriptor)\n);\n```\n:::\n\n\n\n\nBefore we continue, is important to emphasize the following: since we have opened the file with `fopen()`,\nwe have to remember to close the file at the end of the program, with `fclose()`.\nIn other words, after we have done everything that we wanted to do with the PNG file\n`pedro_pascal.png`, we need to close this file, by applying `fclose()` over the file descriptor object.\nWe could use also the `defer` keyword to help us in this task, if we want to.\nThis code snippet below demonstrates this step:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (c.fclose(file_descriptor) != 0) {\n    return error.CouldNotCloseFileDescriptor;\n}\n```\n:::\n\n\n\n\n\n\n\n### Reading the image header section\n\nNow, the context object `ctx` is aware of our PNG file `pedro_pascal.png`, because it has access to\na file descriptor object to this file. The first thing that we are going to do is to read the\n\"image header section\" of the PNG file. This \"image header section\" is the section\nof the file that contains some basic information about the PNG file, like, the bit depth of the pixel data\nof the image, the color model used in the file, the dimensions of the image (height and width in number of pixels),\netc.\n\nTo make things easier, I will encapsulate this \"read image header\" operation into a\nnice and small function called `get_image_header()`. All that this function needs to do\nis to call the `spng_get_ihdr()` function. This function from `libspng` is responsible\nfor reading the image header data, and storing it into a C struct named `spng_ihdr`.\nThus, an object of type `spng_ihdr` is a C struct that contains the data from the\nimage header section of the PNG file.\n\nSince this Zig function is receiving a C object (the `libspng` context object) as input, I marked\nthe function argument `ctx` as \"a pointer to the context object\" (`*c.spng_ctx`), following the recommendations\nthat we have discussed in @sec-pass-c-structs.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn get_image_header(ctx: *c.spng_ctx) !c.spng_ihdr {\n    var image_header: c.spng_ihdr = undefined;\n    if (c.spng_get_ihdr(ctx, &image_header) != 0) {\n        return error.CouldNotGetImageHeader;\n    }\n\n    return image_header;\n}\n\nvar image_header = try get_image_header(ctx);\n```\n:::\n\n\n\n\nAlso notice in this function, that I'm checking if the `spng_get_ihdr()` function call have\nreturned or not an integer value that is different than zero. Most functions from the\n`libspng` library return a code status as result, and the code status \"zero\" means\n\"success\". So any code status that is different than zero means that an error\noccurred while running `spng_get_ihdr()`. This is why I'm returning an error value from\nthe function in case the code status returned by the function is different than zero.\n\n\n### Allocating space for the pixel data\n\nBefore we read the pixel data from the PNG file, we need to allocate enough space to hold this data.\nBut in order to allocate such space, we first need to know how much space we need to allocate.\nThe dimensions of the image are obviously needed to calculate the size of this space. But there are\nother elements that also affect this number, such as the color model used in the image, the bit depth, and others.\n\nAnyway, all of this means that calculating the size of the space that we need, is not a simple task.\nThat is why the `libspng` library offers an utility function named\n`spng_decoded_image_size()` to calculate this size for us. Once again, I'm going\nto encapsulate the logic around this C function into a nice and small Zig function\nnamed `calc_output_size()`. You can see below that this function returns a nice\ninteger value as result, informing the size of the space that we need to allocate.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn calc_output_size(ctx: *c.spng_ctx) !u64 {\n    var output_size: u64 = 0;\n    const status = c.spng_decoded_image_size(\n        ctx, c.SPNG_FMT_RGBA8, &output_size\n    );\n    if (status != 0) {\n        return error.CouldNotCalcOutputSize;\n    }\n    return output_size;\n}\n```\n:::\n\n\n\n\n\n\nYou might quest yourself what the value `SPNG_FMT_RGBA8` means. This value is actually an enum\nvalue defined in the `spng.h` C header file. This enum is used to identify a \"PNG format\".\nMore precisely, it identifies a PNG file that uses the RGBA color model and 8 bit depth.\nSo, by providing this enum value as input to the `spng_decoded_image_size()` function,\nwe are saying to this function to calculate the size of the decoded pixel data, by considering\na PNG file that follows this \"RGBA color model with 8 bit depth\" format.\n\nHaving this function, we can use it in conjunction with an allocator object, to allocate an\narray of bytes (`u8` values) that is big enough to store the decoded pixel data of the image.\nNotice that I'm using `@memset()` to initialize the entire array to zero.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst output_size = try calc_output_size(ctx);\nvar buffer = try allocator.alloc(u8, output_size);\n@memset(buffer[0..], 0);\n```\n:::\n\n\n\n\n\n### Decoding the image data\n\nNow that we have the necessary space to store the decoded pixel data of the image,\nwe can start to actually decode and extract this pixel data from the image,\nby using the `spng_decode_image()` C function.\n\nThe `read_data_to_buffer()` Zig function exposed below summarises the necessary\nsteps to read this decoded pixel data, and store it into an input buffer.\nNotice that this function is encapsulating the logic around the `spng_decode_image()` function.\nAlso, we are using the `SPNG_FMT_RGBA8` enum value once again to inform the corresponding function,\nthat the PNG image being decoded, uses the RGBA color model and 8 bit depth.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn read_data_to_buffer(ctx: *c.spng_ctx, buffer: []u8) !void {\n    const status = c.spng_decode_image(\n        ctx,\n        buffer.ptr,\n        buffer.len,\n        c.SPNG_FMT_RGBA8,\n        0\n    );\n\n    if (status != 0) {\n        return error.CouldNotDecodeImage;\n    }\n}\n```\n:::\n\n\n\n\nHaving this function at hand, we can apply it over our context object, and also, over\nthe buffer object that we have allocated in the previous section to hold the decoded pixel data\nof the image:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry read_data_to_buffer(ctx, buffer[0..]);\n```\n:::\n\n\n\n\n\n### Looking at the pixel data\n\nNow that we have the pixel data stored in our \"buffer object\", we can take\na quick look at the bytes. In the example below, we are looking at the first\n12 bytes in the decoded pixel data.\n\nIf you take a close look at these values, you might notice that every 4 bytes\nin the sequence is 255. Which, coincidentally is the maximum possible integer value\nto be represented by a `u8` value. So, if the range from 0 to 255, which is the range\nof integer values that can be represented by an `u8` value, can be represented as a scale from 0% to 100%,\nthese 255 values are essentially 100% in that scale.\n\nIf you recall from @sec-pixel-repr, I have\ndescribed in that section that our `pedro_pascal.png` PNG file uses the RGBA color model,\nwhich adds an alpha (or transparency) byte to each pixel in the image.\nAs consequence, each pixel in the image is represented by 4 bytes. Since we are looking\nhere are the first 12 bytes in the image, it means that we are looking at the data from\nthe first $12 / 4 = 3$ pixels in the image.\n\nSo, based on how these first 12 bytes (or these 3 pixels) look, with these 255 values at every 4 bytes, we can say that is likely\nthat every pixel in the image have alpha (or transparency) setted to 100%. This might not be true,\nbut, is the most likely possibility. Also, if we look at the image itself, which if your recall is\nexposed in @fig-pascal, we can see that the transparency does not change across the image,\nwhich enforces this theory.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry stdout.print(\"{any}\\n\", .{buffer[0..12]});\n```\n:::\n\n\n\n\n```\n{\n    200, 194, 216, 255, 203, 197,\n    219, 255, 206, 200, 223, 255\n}\n```\n\n\nWe can see in the above result that the first pixel in this image have 200 of red, 194 of green, and 216 of blue.\nHow do I know the order in which the colors appears in the sequence? If you have not guessed that yet,\nis because of the acronym RGB. First RED, then GREEN, then BLUE. If we scale these integer values\naccording to our scale of 0% to 100% (0 to 255), we get 78% of red, 76% of green and 85% of blue.\n\n\n\n## Applying the image filter\n\nNow that we have the data of each pixel in the image, we can focus on applying our image\nfilter over these pixels. Remember, our objective here is to apply a grayscale filter over\nthe image. A grayscale filter is a filter that transforms a colored image into a grayscale image.\n\nThere are different formulas and strategies to transform a colored image into a grayscale image.\nBut all of these different strategies normally involve applying some math over the colors of each pixel.\nIn this project, we are going to use the most general formula, which is exposed below.\nThis formula considers $r$ as the red of the pixel, $g$ as the green, $b$ as the blue, and $p'$ as the\nlinear luminance of the pixel.\n\n$$\n    p' = (0.2126 \\times r) + (0.7152 \\times g) + (0.0722 \\times b)\n$${#eq-grayscale}\n\nThis @eq-grayscale is the formula to calculate the linear luminance of a pixel. It's worth noting that this formula\nworks only for images whose pixels are using the sRGB color space, which is the standard color space\nfor the web. Thus, ideally, all images on the web should use this color space. Luckily,\nthis is our case here, i.e., the `pedro_pascal.png` image is using this sRGB color space, and, as consequence,\nwe can use the @eq-grayscale. You can read more about this formula at the Wikipedia page for grayscale [@wiki_grayscale].\n\nThe `apply_image_filter()` function exposed below summarises the necessary steps to\napply @eq-grayscale over the pixels in the image. We just apply this function\nover our buffer object that contains our pixel data, and, as result, the pixel\ndata stored in this buffer object should now represent the grayscale version of our image.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn apply_image_filter(buffer:[]u8) !void {\n    const len = buffer.len;\n    const red_factor: f16 = 0.2126;\n    const green_factor: f16 = 0.7152;\n    const blue_factor: f16 = 0.0722;\n    var index: u64 = 0;\n    while (index < len) : (index += 4) {\n        const rf: f16 = @floatFromInt(buffer[index]);\n        const gf: f16 = @floatFromInt(buffer[index + 1]);\n        const bf: f16 = @floatFromInt(buffer[index + 2]);\n        const y_linear: f16 = (\n            (rf * red_factor) + (gf * green_factor)\n            + (bf * blue_factor)\n        );\n        buffer[index] = @intFromFloat(y_linear);\n        buffer[index + 1] = @intFromFloat(y_linear);\n        buffer[index + 2] = @intFromFloat(y_linear);\n    }\n}\n\ntry apply_image_filter(buffer[0..]);\n```\n:::\n\n\n\n\n\n\n## Saving the grayscale version of the image\n\nSince we have now the grayscale version of our image stored in our buffer object,\nwe need to encode this buffer object back into the \"PNG format\", and save the encoded data into\na new PNG file in our filesystem, so that we can access and see the grayscale version of our image\nthat was produced by our small program.\n\nTo do that, the `libspng` library help us once again by offering an \"encode data to PNG\" type of function,\nwhich is the `spng_encode_image()` function. But in order to \"encode data to PNG\" with `libspng`, we need\nto create a new context object. This new context object must use an \"encoder context\", which\nis identified by the enum value `SPNG_CTX_ENCODER`.\n\nThe `save_png()` function exposed below, summarises all the necessary steps to save the\ngrayscale version of our image into a new PNG file in the filesystem. By default, this\nfunction will save the grayscale image into a file named `pedro_pascal_filter.png` in the CWD.\n\nNotice in this code example that we are using the same image header object (`image_header`) that we have\ncollected previously with the `get_image_header()` function. Remember, this image header object\nis a C struct (`spng_ihdr`) that contains basic information about our PNG file, such as\nthe dimensions of the image, the color model used, etc.\n\nIf we wanted to save a very different image in this new PNG file, e.g. an image\nwith different dimensions, or, an image that uses a different color model, a different bit depth, etc.\nwe would have to create a new image header (`spng_ihdr`) object that describes the properties\nof this new image.\n\nBut we are essentially saving the same image that we have begin with here (the dimensions of\nthe image, the color model, etc. are all still the same). The only difference\nbetween the two images are the colors of the pixels, which are now \"shades of gray\".\nAs consequence, we can safely use the exact same image header data in this new PNG file.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn save_png(image_header: *c.spng_ihdr, buffer: []u8) !void {\n    const path = \"pedro_pascal_filter.png\";\n    const file_descriptor = c.fopen(path.ptr, \"wb\");\n    if (file_descriptor == null) {\n        return error.CouldNotOpenFile;\n    }\n    const ctx = (\n        c.spng_ctx_new(c.SPNG_CTX_ENCODER)\n        orelse unreachable\n    );\n    defer c.spng_ctx_free(ctx);\n    _ = c.spng_set_png_file(ctx, @ptrCast(file_descriptor));\n    _ = c.spng_set_ihdr(ctx, image_header);\n\n    const encode_status = c.spng_encode_image(\n        ctx,\n        buffer.ptr,\n        buffer.len,\n        c.SPNG_FMT_PNG,\n        c.SPNG_ENCODE_FINALIZE\n    );\n    if (encode_status != 0) {\n        return error.CouldNotEncodeImage;\n    }\n    if (c.fclose(file_descriptor) != 0) {\n        return error.CouldNotCloseFileDescriptor;\n    }\n}\n\ntry save_png(&image_header, buffer[0..]);\n```\n:::\n\n\n\n\nAfter we execute this `save_png()` function, we should have a new PNG file\ninside our CWD, named `pedro_pascal_filter.png`. If we open this PNG file,\nwe will see the same image exposed in @fig-pascal-gray.\n\n\n## Building our project\n\nNow that we have written the code, let's discuss how can we build/compile this project.\nTo do that, I'm going to create a `build.zig` file in the root directory of our project,\nand start writing the necessary code to compile the project, using the knowledge\nthat we have acquired from @sec-build-system.\n\n\nWe first create the build target for our executable file, that executes our\nZig code. Let's suppose that all of our Zig code was written into a Zig module\nnamed `image_filter.zig`. The `exe` object exposed in the build script below\ndescribes the build target for our executable file.\n\nSince we have used some C code from the `libspng` library in our Zig code,\nwe need to link our Zig code (which is in the `exe` build target) to both\nthe C Standard Library, and, to the `libspng` library. We do that, by calling\nthe `linkLibC()` and `linkSystemLibrary()` methods from our `exe` build target.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const target = b.standardTargetOptions(.{});\n    const optimize = b.standardOptimizeOption(.{});\n    const exe = b.addExecutable(.{\n        .name = \"image_filter\",\n        .root_source_file = b.path(\"src/image_filter.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n    exe.linkLibC();\n    // Link to libspng library:\n    exe.linkSystemLibrary(\"spng\");\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\nSince we are using the `linkSystemLibrary()` method, it means that the library\nfiles for `libspng` are searched in your system to be linked with the `exe` build target.\nIf you have not yet built and installed the `libspng` library into your system, this\nlinkage step will likely not work. Because it will not find the library files in your system.\n\nSo, just remember to install `libspng` in your system, if you want to build this project.\nHaving this build script above written, we can finally build our project by\nrunning the `zig build` command in the terminal.\n\n```bash\nzig build\n```\n",
+    "supporting": [
+      "13-image-filter_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/14-threads/execute-results/html.json b/_freeze/Chapters/14-threads/execute-results/html.json
index 391ecd93..e68da4ad 100644
--- a/_freeze/Chapters/14-threads/execute-results/html.json
+++ b/_freeze/Chapters/14-threads/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "043ca4f316462852f28e8b4d4fe3047b",
+  "hash": "5330e6bae2255d3ad46893b0641f0683",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Introducing threads and parallelism in Zig {#sec-thread}\n\nThreads are available in Zig through the `Thread` struct from the Zig Standard Library.\nThis struct represents a kernel thread, and it follows a POSIX Thread pattern,\nmeaning that, it works similarly to a thread from the `pthread` C library, which is usually available on any distribution\nof the GNU C Compiler (`gcc`). If you are not familiar with threads, I will give you some theory behind it first, shall we?\n\n\n## What are threads? {#sec-what-thread}\n\nA thread is basically a separate context of execution.\nWe use threads to introduce parallelism into our program,\nwhich in most cases, makes the program run faster, because we have multiple tasks\nbeing performed at the same time, parallel to each other.\n\nPrograms are normally single-threaded by default. Which means that each program\nusually runs on a single thread, or, a single context of execution. When we have only one thread running, we have no\nparallelism. And when we don't have parallelism, the commands are executed sequentially, that is,\nonly one command is executed at a time, one after another. By creating multiple threads inside our program,\nwe start to execute multiple commands at the same time.\n\nPrograms that create multiple threads are very common on the wild. Because many different types\nof applications are well suited for parallelism. Good examples are video and photo-editing applications\n(e.g. Adobe Photoshop or DaVinci Resolve), games (e.g. The Witcher 3), and also web browsers\n(e.g. Google Chrome, Firefox, Microsoft Edge, etc).\nFor example, in web browsers, threads are normally used to implement tabs.\nThe tabs in a web browsers usually run as separate threads in the main process of\nthe web browser. That is, each new tab that you open in your web browser,\nusually runs on a separate thread of execution.\n\nBy running each tab in a separate thread, we allow all open tabs in the browser to run at the same time,\nand independently from each other. For example, you might have YouTube, or Spotify, currently opened in\na tab, and you are listening to some podcast in that tab, while, at the same time,\nyou are working in another tab, writing an essay on Google Docs. Even if you are not looking\ninto the YouTube tab, you can still hear the podcast only because this YouTube tab is running in parallel\nwith the other tab where Google Docs is running.\n\nWithout threads, the other alternative would be to run each tab as a completely separate\nprocess in your computer. But that would be a bad choice, because just a few tabs would already consume\ntoo much power and resources from your computer. In other words, is very expensive to create a completely new process,\ncompared to creating a new thread of execution. Also, the chances of you experiencing lag and overhead\nwhile using the browser would be significant. Threads are faster to create, and they also consume\nmuch, much less resources from the computer, especially because they share some resources\nwith the main process.\n\nTherefore, is the use of threads in modern web browsers that allows you to hear the podcast\nat the same time while you are writing something on Google Docs.\nWithout threads, a web browser would probably be limited to just one single tab.\n\nThreads are also well-suited for anything that involves serving requests or orders.\nBecause serving a request takes time, and usually involves a lot of \"waiting time\".\nIn other words, we spend a lot of time in idle, waiting for something to complete.\nFor example, consider a restaurant. Serving orders in a restaurant usually involves\nthe following steps:\n\n1. receive order from the client.\n1. pass the order to the kitchen, and wait for the food to be cooked.\n1. start cooking the food in the kitchen.\n1. when the food is fully cooked deliver this food to the client.\n\nIf you think about the bullet points above, you will notice that one big moment of waiting time\nis present in this whole process, which is while the food is being cooked\ninside the kitchen. While the food is being prepped, both the waiter and the client\nitself are waiting for the food to be ready and delivered.\n\nIf we write a program to represent this restaurant, more specifically, a single-threaded program, then,\nthis program would be very inefficient. Because the program would stay in idle, waiting for a considerable amount\nof time on the \"check if food is ready\" step. Consider the code snippet exposed below that could\npotentially represent such program.\n\nThe problem with this program is the while loop. This program will spend a lot of time\nwaiting on the while loop, doing nothing more than just checking if the food is ready.\nThis is a waste of time. Instead of waiting for something to happen, the waiter\ncould just send the order to the kitchen, and just move on, and continue with receiving\nmore orders from other clients, and sending more orders to the kitchen, instead\nof doing nothing and waiting for the food to be ready.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst order = Order.init(\"Pizza Margherita\", n = 1);\nconst waiter = Waiter.init();\nwaiter.receive_order(order);\nwaiter.ask_kitchen_to_cook();\nvar food_not_ready = true;\nwhile (food_not_ready) {\n    food_not_ready = waiter.is_food_ready();\n}\nconst food = waiter.get_food_from_kitchen();\nwaiter.send_food_to_client(food);\n```\n:::\n\n\n\n\nThis is why threads would be a great fit for this program. We could use threads\nto free the waiters from their \"waiting duties\", so they can go on with their\nother tasks, and receive more orders. Take a look at the next example, where I have re-written the above\nprogram into a different program that uses threads to cook and deliver the orders.\n\nYou can see in this program that when a waiter receives a new order\nfrom a client, this waiter executes the `send_order()` function.\nThe only thing that this function does is to create a new thread\nand detaches it. Since creating a thread is a very fast operation,\nthis `send_order()` function returns almost immediately,\nso the waiter spends almost no time worrying about the order, and just\nmove on and tries to get the next order from the clients.\n\nInside the new thread created, the order get's cooked by a chef, and when the\nfood is ready, it is delivered to the client's table.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn cook_and_deliver_order(order: *Order) void {\n    const chef = Chef.init();\n    const food = chef.cook(order.*);\n    chef.deliver_food(food);\n}\nfn send_order(order: Order) void {\n    const cook_thread = Thread.spawn(\n        .{}, cook_and_deliver_order, .{&order}\n    );\n    cook_thread.detach();\n}\n\nconst waiter = Waiter.init();\nwhile (true) {\n    const order = waiter.get_new_order();\n    if (order) {\n        send_order(order);\n    }\n}\n```\n:::\n\n\n\n\n\n\n## Threads versus processes\n\nWhen we run a program, this program is executed as a *process* in the operating system.\nThis is a one to one relationship, each program or application that you execute\nis a separate process in the operating system. But each program, or each process,\ncan create and contain multiple threads inside of it. Therefore,\nprocesses and threads have a one to many relationship.\n\nThis also means that every thread that we create is always associated with a particular process in our computer.\nIn other words, a thread is always a subset (or a children) of an existing process.\nAll threads share some of the resources associated with the process from which they were created.\nAnd because threads share resources with the process, they are very good for making communication\nbetween tasks easier.\n\nFor example, suppose that you were developing a big and complex application\nthat would be much simpler if you could split it in two, and make these two separate pieces talk\nwith each other. Some programmers opt to effectively write these two pieces of the codebase as two\ncompletely separate programs, and then, they use IPC (*inter-process communication*) to make these\ntwo separate programs/processes talk to each other, and make them work together.\n\nHowever, some programmers find IPC hard to deal with, and, as consequence,\nthey prefer to write one piece of the codebase as the \"main part of the program\",\nor, as the part of the code that runs as the process in the operating system,\nwhile the other piece of the codebase is written as a task to be executed in\na new thread. A process and a thread can easily comunicate with each other\nthrough both control flow, and also, through data, because they share and have\naccess to the same standard file descriptors (`stdout`, `stdin`, `stderr`), and also to the\nsame memory space on the heap and global data section.\n\n\nIn more details, each thread that you create have a separate stack frame reserved just for that thread,\nwhich essentially means that each local object that you create inside this thread, is local to that\nthread, i.e. the other threads cannot see this local object. Unless this object that you have created\nis an object that lives on the heap. In other words, if the memory associated with this object\nis on the heap, then, the other threads can potentially access this object.\n\nTherefore, objects that are stored in the stack are local to the thread where they were created.\nBut objects that are stored on the heap are potentially accessible to other threads. All of this means that,\neach thread have its own separate stack frame, but, at the same time, all threads share\nthe same heap, the same standard file descriptors (which means that they share the same `stdout`, `stdin`, `stderr`),\nand the same global data section in the program.\n\n\n\n## Creating a thread\n\nWe create new threads in Zig, by first, importing the `Thread` struct into\nour current Zig module, and then, calling the `spawn()` method of this struct,\nwhich creates (or, \"spawns\") a new thread of execution from our current process.\nThis method have three arguments, which are, respectively:\n\n1. a `SpawnConfig` object, which contains configurations for the spawn process.\n1. the name of the function that is going to be executed (or, that is going to be \"called\") inside this new thread.\n1. a list of arguments (or inputs) to be passed to the function provided in the second argument.\n\nWith these three arguments, you can control how the thread get's created, and also, specify which\nwork (or \"tasks\") will be performed inside this new thread. A thread is just a separate context of execution,\nand we usually create new threads in our code, because we want to perform some work inside this\nnew context of execution. And we specify which exact work, or, which exact steps that are going to be\nperformed inside this context, by providing the name of a function on the second argument of the `spawn()` method.\n\nThus, when this new thread get's created, this function that you provided as input to the `spawn()`\nmethod get's called, or, get's executed inside this new thread. You can control the\narguments, or, the inputs that are passed to this function when it get's called, by providing\na list of arguments (or a list of inputs) on the third argument of the `spawn()` method.\nThese arguments are passed to the function in the same order that they are\nprovided to `spawn()`.\n\nFurthermore, the `SpawnConfig` is a struct object with only two possible fields, or, two possible members, that you\ncan set to tailor the spawn behaviour. These fields are:\n\n- `stack_size`: you can provide an `usize` value to specify the size (in bytes) of the thread's stack frame. By default, this value is: $16 \\times 1024 \\times 1024$.\n- `allocator`: you can provide an allocator object to be used when allocating memory for the thread.\n\nTo use one of these two fields (or, \"configs\") you just have to create a new object of type `SpawnConfig`,\nand provide this object as input to the `spawn()` method. But, if you are not interested in using\none of these configs, and you are ok with using just the defaults, you can just provide an anonymous\nstruct literal (`.{}`) in the place of this `SpawnConfig` argument.\n\nAs our first, and very simple example, consider the code exposed below.\nInside the same program, you can create multiple threads of execution if you want to.\nBut, in this first example, we are creating just a single thread of execution, because\nwe call `spawn()` only once.\n\nAlso, notice in this example that we are executing the function `do_some_work()`\ninside the new thread. Since this function receives no inputs, because it has\nno arguments, we have passed an empty list in this instance, or, more precisely,\nan empty and anonymous struct (`.{}`) in the third argument of `spawn()`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Thread = std.Thread;\nfn do_some_work() !void {\n    _ = try stdout.write(\"Starting the work.\\n\");\n    std.time.sleep(100 * std.time.ns_per_ms);\n    _ = try stdout.write(\"Finishing the work.\\n\");\n}\n\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, do_some_work, .{});\n    thread.join();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nStarting the work.Finishing the work.\n```\n\n\n:::\n:::\n\n\n\n\nNotice the use of `try` when calling the `spawn()` method. This means\nthat this method can return an error in some circumstances. One circumstance\nin particular is when you attempt to create a new thread, when you have already\ncreated too much (i.e. you have exceeded the quota of concurrent threads in your system).\n\nBut, if the new thread is successfully created, the `spawn()` method returns a handler\nobject (which is just an object of type `Thread`) to this new thread. You can use\nthis handler object to effectively control all aspects of the thread.\n\nWhen the thread get's created, the function that you provided as input to `spawn()`\nget's invoked (i.e. get's called) to start the execution on this new thread.\nIn other words, everytime you call `spawn()`, not only a new thread get's created,\nbut also, the \"start work button\" of this thread get's automatically pressed.\nSo the work being performed in this thread starts at the moment that the thread is created.\nThis is similar to how `pthread_create()` from the `pthreads` library in C works,\nwhich also starts the execution at the moment that the thread get's created.\n\n\n## Returning from a thread\n\nWe have learned on the previous section that the execution of the thread starts at the moment\nthat the thread get's created. Now, we will learn how to \"join\" or \"detach\" a thread in Zig.\n\"Join\" and \"detach\" are operations that control how the thread returns to\nthe main thread, or, to the main process in our program.\n\nWe perform these operations by using the methods `join()` and `detach()` from the thread handler object.\nEvery thread that you create can be marked as either *joinable* or *detached* [@linux_pthread_create].\nYou can turn a thread into a *detached* thread by calling the `detach()` method\nfrom the thread handler object. But if you call the `join()` method instead, then, this thread\nbecomes a *joinable* thread.\n\nA thread cannot be both *joinable* and *detached*. Which in general means\nthat you cannot call both `join()` and `detach()` on the same thread.\nBut a thread must be one of the two, meaning that, you should always call\neither `join()` or `detach()` over a thread. If you don't call\none of these two methods over your thread, you introduce undefined behaviour into your program,\nwhich is described at @sec-not-call-join-detach.\n\nNow, let's describe what each of these two methods do to your thread.\n\n\n### Joining a thread\n\nWhen you join a thread, you are essentially saying: \"Hey! Could you please wait for the thread to finish,\nbefore you continue with your execution?\". For example, if we comeback to our first and simpliest example\nof a thread in Zig, in that example we have created a single thread inside the `main()` function of our program,\nand just called `join()` over this thread at the end. This section of the code example is reproduced below.\n\nBecause we are joining this new thread inside the `main()`'s scope, it means that the\nexecution of the `main()` function is temporarily stopped, to wait for the execution of the thread\nto finish. That is, the execution of `main()` stops temporarily at the line where `join()` get's called,\nand it will continue only after the thread has finished its tasks.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, do_some_work, .{});\n    thread.join();\n}\n```\n:::\n\n\n\n\nBecause we have joined this new thread inside the `main()` scope, we have a\nguarantee that this new thread will finish before the end of the execution of `main()`.\nBecause it is guaranteed that `main()` will wait for the thread to finish its tasks.\n\nIn the example above, there are no more expressions after the `join()` call. We just have the end\nof the `main()`'s scope, and, therefore, the execution of our program just ends after the thread finishes its tasks,\nsince there is nothing more to do. But what if we had more stuff to do after the join call?\n\nTo demonstrate this other possibility, consider the next example exposed\nbelow. Here, we create a `print_id()` function, that just receives an id\nas input, and prints it to `stdout`. In this example, we are creating two\nnew threads, one after another. Then, we join the first thread, then,\nwe wait for two whole seconds, then, at last, we join the second thread.\n\nThe idea behind this example is that the last `join()` call is executed\nonly after the first thread finishes its task (i.e. the first `join()` call),\nand also, after the two seconds of delay. If you compile and run this\nexample, you will notice that most messages are quickly printed to `stdout`,\ni.e. they appear almost instantly on your screen.\nHowever, the last message (\"Joining thread 2\") takes around 2 seconds to appear\nin the screen.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_id(id: *const u8) !void {\n    try stdout.print(\"Thread ID: {d}\\n\", .{id.*});\n}\n\npub fn main() !void {\n    const id1: u8 = 1;\n    const id2: u8 = 2;\n    const thread1 = try Thread.spawn(.{}, print_id, .{&id1});\n    const thread2 = try Thread.spawn(.{}, print_id, .{&id2});\n\n    _ = try stdout.write(\"Joining thread 1\\n\");\n    thread1.join();\n    std.time.sleep(2 * std.time.ns_per_s);\n    _ = try stdout.write(\"Joining thread 2\\n\");\n    thread2.join();\n}\n```\n:::\n\n\n\n\n```\nThread ID: Joining thread 1\n1\nThread ID: 2\nJoining thread 2\n```\n\nThis demonstrates that both threads finish their work (i.e. printing the IDs)\nvery fast, before the two seconds of delay end. Because of that, the last `join()` call\nreturns pretty much instantly. Because when this last `join()` call happens, the second\nthread have already finished its task.\n\nNow, if you compile and run this example, you will also notice that, in some cases,\nthe messages intertwine with each other. In other words, you might see\nthe message \"Joining thread 1\" inserted in the middle of the message \"Thread 1\",\nor vice-versa. This happens because:\n\n- the threads are executing basically at the same time as the main process of the program (i.e. the `main()` function).\n- the threads share the same `stdout` from the main process of the program, which means that the messages that the threads produce are sent to exact same place as the messages produced by the main process.\n\nBoth of these points were described previously at @sec-what-thread.\nSo the messages might get intertwined because they are being produced and\nsent to the same `stdout` roughly at the same time.\nAnyway, when you call `join()` over a thread, the current process will wait\nfor the thread to finish before it continues, and, when the thread does finishes its\ntask, the resources associated with this thread are automatically freed, and,\nthe current process continues with its execution.\n\n\n### Detaching a thread\n\nWhen you detach a thread, the resources associated with this thread are automatically\nreleased back to the system, without the need for another thread to join with this terminated thread.\n\nIn other words, when you call `detach()` over a thread it's like when your children becomes adults,\ni.e. they become independent from you. A detached thread frees itself, and when this thread finishes its\ntasks, it does not report the results back to you. Thus, you normally mark a thread as *detached*\nwhen you don't need to use the return value of the thread, or, when you don't care about\nwhen exactly the thread finishes its job, i.e. the thread solves everything by itself.\n\nTake the code example below. We create a new thread, detach it, and then, we just\nprint a final message before we end our program. We use the same `print_id()`\nfunction that we have used over the previous examples.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_id(id: *const u8) !void {\n    try stdout.print(\"Thread ID: {d}\\n\", .{id.*});\n}\n\npub fn main() !void {\n    const id1: u8 = 1;\n    const thread1 = try Thread.spawn(.{}, print_id, .{&id1});\n    thread1.detach();\n    _ = try stdout.write(\"Finish main\\n\");\n}\n```\n:::\n\n\n\n\n```\nFinish main\n```\n\nNow, if you look closely at the output of this code example, you will notice\nthat only the final message in main was printed to the console. The message\nthat was supposed to be printed by `print_id()` did not appear in the console.\nWhy? Is because the main process of our program has finished first,\nbefore the thread was able to say anything.\n\nAnd that is perfectly ok behaviour, because the thread was detached, so, it was\nable to free itself, without the need to wait for the main process.\nIf you ask main to sleep (or \"wait\") for some extra nanoseconds, before it ends, you will likely\nsee the message printed by `print_id()`, because you give enough time for the thread to\nfinish before the main process ends.\n\n\n## Thread pools\n\nThread pools is a very popular programming pattern, which is used especially on servers and daemons processes.\nA thread pool is just a set of threads, or, a \"pool\" of threads. Many programmers like to use this pattern, because it makes\neasier to manage and use multiple threads in your program, instead of manually creating the threads when you need them.\n\nAlso, using thread pools might increase performance as well in your program,\nespecially if your program is constantly creating threads to perform short-lived tasks.\nIn such instance, a thread pool might cause an increase in performance because you do not have be constantly\ncreating and destroying threads all the time, so you don't face a lot of the overhead involved\nin this constant process of creating and destroying threads.\n\nThe main idea behind a thread pool is to have a set of threads already created and ready to perform\ntasks at all times. You create a set of threads at the moment that your program starts, and keep\nthese threads alive while your program runs. Each of these threads will be either performing a task, or,\nwaiting for a task to be assigned.\nEvery time a new task emerges in your program, this task is added to a \"queue of tasks\",\nand the moment that a thread becomes available and ready to perform a new task,\nthis thread takes the next task from the \"queue of tasks\", and it simply performs the task.\n\nThe Zig Standard Library offers a thread pool implementation on the `std.Thread.Pool` struct.\nYou create a new instance of a `Pool` object by providing a `Pool.Options` object\nas input to the `init()` method of this struct. A `Pool.Options` object, is a struct object that contains\nconfigurations for the pool of threads. The most important settings in this struct object are\nthe members `n_jobs` and `allocator`. As the name suggests, the member `allocator` should receive an allocator object,\nwhile the member `n_jobs` specifies the number of threads to be created and maintained in this pool.\n\nConsider the example exposed below, that demonstrates how can we create a new thread pool object.\nHere, we create a `Pool.Options` object that contains\na general purpose allocator object, and also, the `n_jobs` member was set to 4, which\nmeans that the thread pool will create and use 4 threads.\n\nAlso notice that the `pool` object was initially set to `undefined`. This allow us\nto initially declare the thread pool object, but not properly instantiate the\nunderlying memory of the object. You have to initially declare your thread pool object\nby using `undefined` like this, because the `init()` method of `Pool` needs\nto have an initial pointer to properly instantiate the object.\n\nSo, just remember to create your thread pool object by using `undefined`, and then,\nafter that, you call the `init()` method over the object.\nYou should also not forget to call the `deinit()` method over the thread pool\nobject, once you are done with it, to release the resources allocated for the thread pool. Otherwise, you will\nhave a memory leak in your program.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Pool = std.Thread.Pool;\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const opt = Pool.Options{\n        .n_jobs = 4,\n        .allocator = allocator,\n    };\n    var pool: Pool = undefined;\n    _ = try pool.init(opt);\n    defer pool.deinit();\n}\n```\n:::\n\n\n\n\nNow that we know how to create `Pool` objects, we have\nto understand how to assign tasks to be executed by the threads in this pool object.\nTo assign a task to be performed by a thread, we need to call the `spawn()` method\nfrom the thread pool object.\n\nThis `spawn()` method works identical to the `spawn()` method from the\n`Thread` object. The method have almost the same arguments as the previous one,\nmore precisely, we don't have to provide a `SpawnConfig` object in this case.\nBut instead of creating a new thread, this `spawn()` method from\nthe thread pool object just register a new task in the internal \"queue of tasks\" to be performed,\nand any available thread in the pool will get this task, and it will simply perform the task.\n\nIn the example below, we are using our previous `print_id()` function once again.\nBut you may notice that the `print_id()` function is a little different this time,\nbecause now we are using `catch` instead of `try` in the `print()` call.\nCurrently, the `Pool` struct only supports functions that don't return errors\nas tasks. Thus, when assigning tasks to threads in a thread pool, is essential to use functions\nthat don't return errors. That is why we are using `catch` here, so that the\n`print_id()` function don't return an error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_id(id: *const u8) void {\n    _ = stdout.print(\"Thread ID: {d}\\n\", .{id.*})\n        catch void;\n}\nconst id1: u8 = 1;\nconst id2: u8 = 2;\ntry pool.spawn(print_id, .{&id1});\ntry pool.spawn(print_id, .{&id2});\n```\n:::\n\n\n\n\nThis limitation should probably not exist, and, in fact, it is already on the radar of the\nZig team to fix this issue, and it is being tracked on an [open issue](https://github.com/ziglang/zig/issues/18810)[^issue].\nSo, if you do need to provide a function that might return an error as the task\nto be performed by the threads in the thread pool, then, you are either limited to:\n\n- implementing your own thread pool that does not have this limitation.\n- wait for the Zig team to actually fix this issue.\n\n[^issue]: <https://github.com/ziglang/zig/issues/18810>\n\n\n\n\n## Mutexes\n\nMutexes are a classic component of every thread library. In essence, a mutex is a *Mutually Exclusive Flag*, and this flag\nacts like a type of \"lock\", or as a gate keeper to a particular section of your code. Mutexes are related to thread synchronization,\nmore specifically, they prevent you from having some classic race conditions in your program,\nand, therefore, major bugs and undefined behaviour that are usually difficult to track and understand.\n\nThe main idea behind a mutex is to help us to control the execution of a particular section of the code, and to\nprevent two or more threads from executing this particular section of the code at the same time.\nMany programmers like to compare a mutex to a bathroom door (which usually have a lock).\nWhen a thread locks its own mutex object, it is like if the bathroom door was locked,\nand, therefore, the other people (in this case, the other threads) that wants to use the same bathroom at the same time\nhave to be patient, and simply wait for the other person (or the other thread) to unlock the door and get out of the bathroom.\n\nSome other programmers also like to explain mutexes by using the analogy of \"each person will have their turn to speak\".\nThis is the analogy used on the [*Multithreading Code* video from the Computerphile project](https://www.youtube.com/watch?v=7ENFeb-J75k&ab_channel=Computerphile)[^computerphile].\nImagine if you are in a conversation circle. There is a moderator in this circle, which is the person that decides who\nhave the right to speak at that particular moment. The moderator gives a green card (or some sort of an authorization card) to the person that\nis going to speak, and, as a result, everyone else must be silent and hear this person that has the green card.\nWhen the person finishes talking, it gives the green card back to the moderator, and the moderator decides\nwho is going to talk next, and delivers the green card to that person. And the cycle goes on like this.\n\n[^computerphile]: <https://www.youtube.com/watch?v=7ENFeb-J75k&ab_channel=Computerphile>\n\n\nA mutex acts like the moderator in this conversation circle. The mutex authorizes one single thread to execute a specific section of the code,\nand it also blocks the other threads from executing this same section of the code. If these other threads want to execute this same\npiece of the code, they are forced to wait for the the authorized thread to finish first.\nWhen the authorized thread finishes executing this code, the mutex authorizes the next thread to execute this code,\nand the other threads are still blocked. Therefore, a mutex is like a moderator that does a \"each\nthread will have their turn to execute this section of the code\" type of control.\n\n\nMutexes are especially used to prevent data race problems from happening. A data race problem happens when two or more threads\nare trying to read from or write to the same shared object at the same time.\nSo, when you have an object that is shared will all threads, and, you want to avoid two or more threads from\naccessing this same object at the same time, you can use a mutex to lock the part of the code that access this specific object.\nWhen a thread tries to run this code that is locked by a mutex, this thread stops its execution,\nand patiently waits for this section of the codebase to be unlocked to continue.\n\nNotice that mutexes are normally used to lock areas of the codebase that access/modify data that is **shared** with all threads,\ni.e. objects that are either stored in the global data section, or, in the heap space of your program.\nSo mutexes are not normally used on areas of the codebase that access/modify objects that are local to the thread.\n\n\n\n### Critical section {#sec-critical-section}\n\nCritical section is a concept commonly associated with mutexes and thread synchronization.\nIn essence, a critical section is the section of the program that a thread access/modify a shared resource\n(i.e. an object, a file descriptor, something that all threads have access to). In other words,\na critical section is the section of the program where race conditions might happen, and, therefore,\nwhere undefined behaviour can be introduced into the program.\n\nWhen we use mutexes in our program, the critical section defines the area of the codebase that we want to lock.\nSo we normally lock the mutex object at the beginning of the critical section,\nand then, we unlock it at the end of the critical section.\nThe two bullet points exposed below comes from the \"Critical Section\" article from GeekFromGeeks,\nand they summarise well the role that a critical section plays in the thread synchronization problem [@geeks_critical_section].\n\n\n1. The critical section must be executed as an atomic operation, which means that once one thread or process has entered the critical section, all other threads or processes must wait until the executing thread or process exits the critical section. The purpose of synchronization mechanisms is to ensure that only one thread or process can execute the critical section at a time.\n1. The concept of a critical section is central to synchronization in computer systems, as it is necessary to ensure that multiple threads or processes can execute concurrently without interfering with each other. Various synchronization mechanisms such as semaphores, mutexes, monitors, and condition variables are used to implement critical sections and ensure that shared resources are accessed in a mutually exclusive manner.\n\n\n### Atomic operations {#sec-atomic-operation}\n\nYou will also see the term \"atomic operation\" a lot when reading about threads, race conditions and mutexes.\nIn summary, an operation is categorized as \"atomic\", when there is no way to happen a context switch in\nthe middle of this operation. In other words, this operation is always done from beginning to end, without interruptions\nof another process or operation in the middle of its execution phase.\n\nNot many operations today are atomic. But why atomic operations matters here? Is because data races\n(which is a type of a race condition) cannot happen on operations that are atomic.\nSo if a particular line in your code performs an atomic operation, then, this line will never\nsuffer from a data race problem. Therefore, programmers sometimes use an atomic operation\nto protect themselves from data race problems in their code.\n\nWhen you have an operation that is compiled into just one single assembly instruction, this operation might be atomic,\nbecause it is just one assembly instruction. But this is not guaranteed. This is usually true for old CPU architectures\n(such as `x86`). But nowadays, most assembly instructions in modern CPU architectures turn into multiple micro-tasks,\nwhich inherently makes the operation not atomic anymore, even though it has just one single assembly instruction.\n\nThe Zig Standard Library offers some atomic functionality at the `std.atomic` module.\nIn this module, you will find a public and generic function called `Value()`. With this function we create an \"atomic object\", which is\na value that contains some native atomic operations, most notably, a `load()` and a `fetchAdd()` operation.\nIf you have experience with multithreading in C++, you probably have recognized this pattern. So yes, this generic\n\"atomic object\" in Zig is essentially identical to the template struct `std::atomic` from the C++ Standard Library.\nIs important to emphasize that only primitive data types (i.e. the types presented at @sec-primitive-data-types)\nare supported by these atomic operations in Zig.\n\n\n\n\n\n### Data races and race conditions\n\nTo understand why mutexes are used, we need to understand better the problem that they seek\nto solve, which can be summarized into data races problems. A data race problem is a type of a race condition,\nwhich happens when one thread is accessing a particular memory location (i.e. a particular shared object) at the same\ntime that another thread is trying to write/save new data into this same memory location (i.e. the same shared object).\n\nWe can simply define a race condition as any type of bug in your program that is based\non a \"who get's there first\" problem. A data race problem is a type of a race condition, because it occurs when two or more parties\nare trying to read and write into the same memory location at the same time, and, therefore, the end result of this operation\ndepends completely on who get's to this memory location first.\nAs consequence, a program that have a data race problem will likely produce a different result each time that we execute it.\n\nThus, race conditions produce undefined behaviour and unpredictability because the program produces\na different answer in each time that a different person get's to the target location first than the others.\nAnd we have no easy way to either predict or control who is getting to this target location first.\nIn other words, in each execution of your program, you get a different answer, because a different person,\nor, a different function, or, a different part of the code is finishing its tasks first than the others.\n\nAs an example, consider the code snippet exposed below. In this example, we create a global counter\nvariable, and we also create an `increment()` function, whose job is to just increment this global counter\nvariable in a for loop.\n\nSince the for loop iterates 1 hundred thousand times, and, we create two separate threads\nin this code example, what number do you expect to see in the final message printed to `stdout`?\nThe answer should be 2 hundred thousand. Right? Well, in theory, this program was supposed\nto print 2 hundred thousand at the end, but in practice, every time that I execute this program\nI get a different answer.\n\nIn the example exposed below, you can see that this time the end\nresult was 117254, instead of the expected 200000. The second time I have executed this program,\nI got the number 108592 as result. So the end result of this program is varying, but it never gets\nto the expected 200000 that we want.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// Global counter variable\nvar counter: usize = 0;\n// Function to increment the counter\nfn increment() void {\n    for (0..100000) |_| {\n        counter += 1;\n    }\n}\n\npub fn main() !void {\n    const thr1 = try Thread.spawn(.{}, increment, .{});\n    const thr2 = try Thread.spawn(.{}, increment, .{});\n    thr1.join();\n    thr2.join();\n    try stdout.print(\"Couter value: {d}\\n\", .{counter});\n}\n```\n:::\n\n\n\n\n```\nCouter value: 117254\n```\n\n\nWhy this is happening? The answer is: because this program contains a data race problem.\nThis program would print the correct number 200000, if, and only if the first thread finishes\nits tasks before the second thread starts to execute. But that is very unlikely to happen.\nBecause the process of creating the thread is too fast, and therefore, both threads starts to execute roughly\nat the same time. If you change this code to add some nanoseconds of sleep between the first and the second calls to `spawn()`,\nyou will increase the chances of the program producing the \"correct result\".\n\nSo the data race problem happens, because both threads are reading and writing to the same\nmemory location at roughly the same time. In this example, each thread is essentially performing\nthree basic operations at each iteration of the for loop, which are:\n\n1. reading the current value of `count`.\n1. incrementing this value by 1.\n1. writing the result back into `count`.\n\nIdeally, a thread B should read the value of `count`, only after the other thread A has finished\nwriting the incremented value back into the `count` object. Therefore, in the ideal scenario, which is demonstrated\nat @tbl-data-race-ideal, the threads should work in sync with each other. But the reality is that these\nthreads are out of sync, and because of that, they suffer from a data race problem, which is demonstrated\nat @tbl-data-race-not.\n\nNotice that, in the data race scenario (@tbl-data-race-not), the read performed by a thread B happens\nbefore the write operation of thread A, and that ultimately leads to wrong results at the end of the program.\nBecause when the thread B reads the value from the `count` variable, the thread A is still processing\nthe initial value from `count`, and it did not write the new and incremented value into `count` yet. So what\nhappens is that thread B ends up reading the same initial value (the \"old\" value) from `count`, instead of\nreading the new and incremented version of this value that would be calculated by thread A.\n\n\n::: {#tbl-data-race-ideal}\n\n| Thread 1    | Thread 2    | Integer value |\n|-------------|-------------|---------------|\n| read value  |             | 0             |\n| increment   |             | 1             |\n| write value |             | 1             |\n|             | read value  | 1             |\n|             | increment   | 2             |\n|             | write value | 2             |\n\n: An ideal scenario for two threads incrementing the same integer value\n:::\n\n::: {#tbl-data-race-not}\n\n| Thread 1    | Thread 2    | Integer value |\n|-------------|-------------|---------------|\n| read value  |             | 0             |\n|             | read value  | 0             |\n| increment   |             | 1             |\n|             | increment   | 1             |\n| write value |             | 1             |\n|             | write value | 1             |\n\n: A data race scenario when two threads are incrementing the same integer value\n:::\n\n\nIf you think about these diagrams exposed in form of tables, you will notice that they relate back to our discussion of atomic operations\nat @sec-atomic-operation. Remember, atomic operations are operations that the CPU executes\nfrom beginning to end, without interruptions from other threads or processes. So,\nthe scenario exposed at @tbl-data-race-ideal do not suffer from a data race, because\nthe operations performed by thread A are not interrupted in the middle by the operations\nfrom thread B.\n\nIf we also think about the discussion of critical section from @sec-critical-section, we can identify\nthe section that representes the critical section of the program, which is the section that is vulnerable\nto data race conditions. In this example, the critical section of the program is the line where we increment\nthe `counter` variable (`counter += 1`). So, ideally, we want to use a mutex, and lock right before this line, and then,\nunlock right after this line.\n\n\n\n\n### Using mutexes in Zig\n\nNow that we know the problem that mutexes seek to solve, we can learn how to use them in Zig.\nMutexes in Zig are available through the `std.Thread.Mutex` struct from the Zig Standard Library.\nIf we take the same code example from the previous example, and improve it with mutexes, to solve\nour data race problem, we get the code example exposed below.\n\nNotice that we had this time to alter the `increment()` function to receive a pointer to\nthe `Mutex` object as input. All that we need to do, to make this program safe against\ndata race problems, is to call the `lock()` method at the beginning of\nthe critical section, and then, call `unlock()` at the end of the critical section.\nNotice that the output of this program is now the correct number of 200000.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Thread = std.Thread;\nconst Mutex = std.Thread.Mutex;\nvar counter: usize = 0;\nfn increment(mutex: *Mutex) void {\n    for (0..100000) |_| {\n        mutex.lock();\n        counter += 1;\n        mutex.unlock();\n    }\n}\n\npub fn main() !void {\n    var mutex: Mutex = .{};\n    const thr1 = try Thread.spawn(.{}, increment, .{&mutex});\n    const thr2 = try Thread.spawn(.{}, increment, .{&mutex});\n    thr1.join();\n    thr2.join();\n    try stdout.print(\"Couter value: {d}\\n\", .{counter});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nCouter value: 200000\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n## Read/Write locks\n\nMutexes are normally used when is always not safe to have two or more threads running the same\npiece of code at the same time. In contrast, read/write locks are normally used in situations\nwhere you have a mixture of scenarios, i.e. there are some pieces of the codebase that are safe\nto run in parallel, and other pieces that are not safe.\n\nFor example, suppose that you have multiple threads that uses the same shared file in the filesystem to store some configurations, or,\nstatistics. If two or more threads try to read the data from this same file at the same time, nothing bad happens.\nSo this part of the codebase is perfectly safe to be executed in parallel, with multiple threads reading the same file at the same time.\n\nHowever, if two or more threads try to write data into this same file at the same time, then, we cause some race conditions\nproblems. So this other part of the codebase is not safe to be executed in parallel.\nMore specifically, a thread might end up writing data in the middle of the data written by the other thread.\nThis process of two or more threads writing to the same location, might lead to data corruption.\nThis specific situation is usually called of a *torn write*.\n\nThus, what we can extract from this example is that there is certain types of operations that causes\na race condition, but there are also, other types of operations that do not cause a race condition problem.\nYou could also say that, there are types of operations that are susceptible to race condition problems,\nand there are other types of operations that are not.\n\nA read/write lock is a type of lock that acknowledges the existance of this specific scenario, and you can\nuse this type of lock to control which parts of the codebase are safe to run in parallel, and which parts are not safe.\n\n\n\n### Exclusive lock vs shared lock\n\nTherefore, a read/write lock is a little different from a mutex. Because a mutex is always an *exclusive lock*, meaning that, only\none thread is allowed to execute at all times. With an exclusive lock, the other threads are always \"excluded\",\ni.e. they are always blocked from executing. But in a read/write lock, the other threads might be authorized\nto run at the same time, depending on the type of lock that they acquire.\n\nWe have two types of locks in a read/write lock, which are: an exclusive lock and a shared lock. An exclusive lock works exactly the same\nas a mutex, while a shared lock is a lock that does not block the other threads from running at the same time.\nIn the `pthreads` C library, read/write locks are available through the `pthread_rwlock_t` C struct. With\nthis C struct, you can create:\n\n- a \"write lock\", which corresponds to an exclusive lock.\n- a \"read lock\", which corresponds to a shared lock.\n\nThe terminology might be a little different compared to Zig. But the meaning is still the same.\nTherefore, just remember this relationship, write locks are exclusive locks, while read locks are shared locks.\n\nWhen a thread tries to acquire a read lock (i.e. a shared lock), this thread get's the shared lock\nif, and only if another thread does not currently holds a write lock (i.e. an exclusive lock), and also,\nif there are no other threads that are already in the queue,\nwaiting for their turn to acquire a write lock. In other words, the thread in the queue have attempted\nto get a write lock earlier, but this thread was blocked\nbecause there was another thread running that already had a write lock. As consequence, this thread is on the queue to get a write lock,\nand it's currently waiting for the other thread with a write lock to finish its execution.\n\nWhen a thread tries to acquire a read lock, but it fails in acquiring this read lock, either because there is\na thread with a write lock already running, or, because there is a thread in the queue to get a write lock,\nthe execution of this thread is instantly blocked, i.e. paused. This thread will indefinitely attempt to get the\nread lock, and its execution will be unblocked (or unpaused) only after this thread successfully acquires the read lock.\n\nIf you think deeply about this dynamic between read locks versus write locks, you might notice that a read lock is basically a safety mechanism.\nMore specifically, it is a way for us to\nallow a particular thread to run together with the other threads, only when it's safe to. In other words, if there is currently\na thread with a write lock running, then, it is very likely not safe for the thread that is trying to acquire the read lock to run now.\nAs consequence, the read lock protects this thread from running into dangerous waters, and patiently waits for the\n\"write lock\" thread to finishes its tasks before it continues.\n\nOn the other hand, if there are only \"read lock\" (i.e. \"shared lock\") threads currently running\n(i.e. not a single \"write lock\" thread currently exists), then,\nis perfectly safe for this thread that is acquiring the read lock to run in parallel with the other\nthreads. As a result, the read lock just\nallows for this thread to run together with the other threads.\n\nThus, by using read locks (shared locks) in conjunction with write locks (exclusive locks), we can control which regions or sections\nof our multithreaded code is safe to have parallelism, and which sections are not safe to have parallelism.\n\n\n\n\n\n### Using read/write locks in Zig\n\nThe Zig Standard Library supports read/write locks through the `std.Thread.RwLock` module.\nIf you want to a particular thread to acquire a shared lock (i.e. a read lock), you should\ncall the `lockShared()` method from the `RwLock` object. But, if you want for this thread\nto acquire an exclusive lock (i.e. a write lock) instead, then, you should call the\n`lock()` method from the `RwLock` object.\n\nAs with mutexes, we also have to unlock the shared or exclusive locks that we acquire through a read/write lock object,\nonce we are at the end of our \"critical section\". If you have acquired an exclusive lock, then, you unlock\nthis exclusive lock by calling the `unlock()` method from the read/write lock object. In contrast,\nif you have acquired a shared lock instead, then, call `unlockShared()` to unlock this shared lock.\n\nAs a simple example, the snippet exposed below creates three separate threads responsible for reading the\ncurrent value in a `counter` object, and it also creates another thread, responsible for writing\nnew data into the `counter` object (incrementing it, more specifically).\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar counter: u32 = 0;\nfn reader(lock: *RwLock) !void {\n    while (true) {\n        lock.lockShared();\n        const v: u32 = counter;\n        try stdout.print(\"{d}\", .{v});\n        lock.unlockShared();\n        std.time.sleep(2 * std.time.ns_per_s);\n    }\n}\nfn writer(lock: *RwLock) void {\n    while (true) {\n        lock.lock();\n        counter += 1;\n        lock.unlock();\n        std.time.sleep(2 * std.time.ns_per_s);\n    }\n}\n\npub fn main() !void {\n    var lock: RwLock = .{};\n    const thr1 = try Thread.spawn(.{}, reader, .{&lock});\n    const thr2 = try Thread.spawn(.{}, reader, .{&lock});\n    const thr3 = try Thread.spawn(.{}, reader, .{&lock});\n    const wthread = try Thread.spawn(.{}, writer, .{&lock});\n\n    thr1.join();\n    thr2.join();\n    thr3.join();\n    wthread.join();\n}\n```\n:::\n\n\n\n\n\n## Yielding a thread\n\nThe `Thread` struct supports yielding through the `yield()` method.\nYielding a thread means that the execution of the thread is temporarily stopped,\nand the thread comes back to the end of the queue of priority of the scheduler from\nyour operating system.\n\nThat is, when you yield a thread, you are essentially saying the following to your OS:\n\"Hey! Could you please stop executing this thread for now, and comeback to continue it later?\".\nYou could also interpret this yield operation as: \"Could you please deprioritize this thread,\nto focus on doing other things instead?\".\nSo this yield operation is also a way for you\nto stop a particular thread, so that you can work and prioritize other threads instead.\n\nIs important to say that, yielding a thread is a \"not so common\" thread operation these days.\nIn other words, not many programmers use yielding in production, simply because is hard to use\nthis operation and make it work properly, and also, there\nare better alternatives. Most programmers prefer to use `join()` instead.\nIn fact, most of the times, when you see somebody using this \"yield\" operation in some code example,\nthey are mostly using it to help them debug race conditions in their applications.\nThat is, this \"yield\" operation is mostly used as a debug tool nowadays.\n\nAnyway, if you want to yield a thread, just call the `yield()` method from it, like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nthread.yield();\n```\n:::\n\n\n\n\n\n\n\n\n\n## Common problems in threads\n\n\n\n### Deadlocks\n\nA deadlock occurs when two or more threads are blocked forever,\nwaiting for each other to release a resource. This usually happens when multiple locks are involved,\nand the order of acquiring them is not well managed.\n\nThe code example below demonstrates a deadlock situation. We have two different threads that execute\ntwo different functions (`work1()` and `work2()`) in this example. And we also have two separate\nmutexes. If you compile and run this code example, you will notice that the program just runs indefinitely,\nwithout ending.\n\nWhen we look into the first thread, which executes the `work1()` function, we can\nnotice that this function acquires the `mut1` lock first. Because this is the first operation\nthat is executed inside this thread, which is the first thread created in the program.\nAfter that, the function sleeps for 1 second, to\nsimulate some type of work, and then, the function tries to acquire the `mut2` lock.\n\nOn the other hand, when we look into the second thread, which executes the `work2()` function,\nwe can see that this function acquires the `mut2` lock first. Because when this thread get's created and it tries\nto acquire this `mut2` lock, the first thread is still sleeping on that \"sleep 1 second\" line.\nAfter acquiring `mut2`, the `work2()` function also sleeps for 1 second, to\nsimulate some type of work, and then, the function tries to acquire the `mut1` lock.\n\nThis creates a deadlock situation, because after the \"sleep for 1 second\" line in both threads,\nthe thread 1 is trying to acquire the `mut2` lock, but this lock is currently being used by thread 2.\nHowever, at this moment, the thread 2 is also trying to acquire the `mut1` lock, which is currently\nbeing used by thread 1. Therefore, both threads end up waiting for ever. Waiting for their peer to\nfree the lock that they want to acquire.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar mut1: Mutex = .{}; var mut2: Mutex = .{};\nfn work1() !void {\n    mut1.lock();\n    std.time.sleep(1 * std.time.ns_per_s);\n    mut2.lock();\n    _ = try stdout.write(\"Doing some work 1\\n\");\n    mut2.unlock(); mut1.unlock();\n}\n\nfn work2() !void {\n    mut2.lock();\n    std.time.sleep(1 * std.time.ns_per_s);\n    mut1.lock();\n    _ = try stdout.write(\"Doing some work 1\\n\");\n    mut1.unlock(); mut2.unlock();\n}\n\npub fn main() !void {\n    const thr1 = try Thread.spawn(.{}, work1, .{});\n    const thr2 = try Thread.spawn(.{}, work2, .{});\n    thr1.join();\n    thr2.join();\n}\n```\n:::\n\n\n\n\n\n### Not calling `join()` or `detach()` {#sec-not-call-join-detach}\n\nWhen you do not call either `join()` or `detach()` over a thread, then, this thread becomes a \"zombie thread\",\nbecause it does not have a clear \"return point\".\nYou could also interpret this as: \"nobody is properly responsible for managing the thread\".\nWhen we don't establish if a thread is either *joinable* or *detached*,\nnobody becomes responsible for dealing with the return value of this thread, and also,\nnobody becomes responsible for clearing (or freeing) the resources associated with this thread.\n\nYou don't want to be in this situation, so remember to always use `join()` or `detach()`\non the threads that you create. When you don't use one of these methods, we lose\ncontrol over the thread, and its resources are never freed\n(i.e. you have leaked resources in the system).\n\n\n### Cancelling or killing a particular thread\n\nWhen we think about the `pthreads` C library, there is a possible way to asynchronously kill or cancel\na thread, which is by sending a `SIGTERM` signal to the thread through the `pthread_kill()` function.\nBut canceling a thread like this is bad. Is dangerously bad. As consequence, the Zig implementation\nof threads does not have a similar function, or, a similar way to asynchronously cancel or kill\na thread.\n\nTherefore, if you want to cancel a thread in the middle of its execution in Zig,\nthen, one good strategy that you can take is to use control flow in conjunction with `join()`.\nMore specifically, you can design your thread around a while loop, that is constantly\nchecking if the thread should continue running.\nIf is time to cancel the thread, we could make the while loop break, and join the thread with the main thread\nby calling `join()`.\n\nThe code example below demonstrates to some extent this strategy.\nHere, we are using control flow to break the while loop, and exit the thread earlier than\nwhat we have initially planned to. This example also demonstrates how can we use\natomic objects in Zig with the `Value()` generic function that we have mentioned at @sec-atomic-operation.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Thread = std.Thread;\nconst stdout = std.io.getStdOut().writer();\nvar running = std.atomic.Value(bool).init(true);\nvar counter: u64 = 0;\nfn do_more_work() void {\n    std.time.sleep(2 * std.time.ns_per_s);\n}\nfn work() !void {\n    while (running.load(.monotonic)) {\n        for (0..10000) |_| { counter += 1; }\n        if (counter < 15000) {\n            _ = try stdout.write(\n                \"Time to cancel the thread.\\n\"\n            );\n            running.store(false, .monotonic);\n        } else {\n            _ = try stdout.write(\"Time to do more work.\\n\");\n            do_more_work();\n            running.store(false, .monotonic);\n        }\n    }\n}\n\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, work, .{});\n    thread.join();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nTime to cancel the thread.\n```\n\n\n:::\n:::\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Introducing threads and parallelism in Zig {#sec-thread}\n\nThreads are available in Zig through the `Thread` struct from the Zig Standard Library.\nThis struct represents a kernel thread, and it follows a POSIX Thread pattern,\nmeaning that, it works similarly to a thread from the `pthread` C library, which is usually available on any distribution\nof the GNU C Compiler (`gcc`). If you are not familiar with threads, I will give you some theory behind it first, shall we?\n\n\n## What are threads? {#sec-what-thread}\n\nA thread is basically a separate context of execution.\nWe use threads to introduce parallelism into our program,\nwhich in most cases, makes the program run faster, because we have multiple tasks\nbeing performed at the same time, parallel to each other.\n\nPrograms are normally single-threaded by default. Which means that each program\nusually runs on a single thread, or, a single context of execution. When we have only one thread running, we have no\nparallelism. And when we don't have parallelism, the commands are executed sequentially, that is,\nonly one command is executed at a time, one after another. By creating multiple threads inside our program,\nwe start to execute multiple commands at the same time.\n\nPrograms that create multiple threads are very common in the wild. Because many different types\nof applications are well suited for parallelism. Good examples are video and photo-editing applications\n(e.g. Adobe Photoshop or DaVinci Resolve), games (e.g. The Witcher 3), and also web browsers\n(e.g. Google Chrome, Firefox, Microsoft Edge, etc).\nFor example, in web browsers, threads are normally used to implement tabs.\nThe tabs in a web browsers usually run as separate threads in the main process of\nthe web browser. That is, each new tab that you open in your web browser\nusually runs on a separate thread of execution.\n\nBy running each tab in a separate thread, we allow all open tabs in the browser to run at the same time,\nand independently from each other. For example, you might have YouTube or Spotify currently open in\na tab, and you are listening to some podcast in that tab while at the same time\nworking in another tab, writing an essay on Google Docs. Even if you are not looking\ninto the YouTube tab, you can still hear the podcast only because this YouTube tab is running in parallel\nwith the other tab where Google Docs is running.\n\nWithout threads, the other alternative would be to run each tab as a completely separate\nprocess in your computer. But that would be a bad choice because just a few tabs would already consume\ntoo much power and resources from your computer. In other words, it's very expensive to create a completely new process,\ncompared to creating a new thread of execution. Also, the chances of you experiencing lag and overhead\nwhile using the browser would be significant. Threads are faster to create, and they also consume\nmuch, much less resources from the computer, especially because they share some resources\nwith the main process.\n\nTherefore, it's the use of threads in modern web browsers that allow you to hear the podcast\nat the same time while you are writing something on Google Docs.\nWithout threads, a web browser would probably be limited to just one single tab.\n\nThreads are also well-suited for anything that involves serving requests or orders.\nBecause serving a request takes time, and usually involves a lot of \"waiting time\".\nIn other words, we spend a lot of time in idle, waiting for something to complete.\nFor example, consider a restaurant. Serving orders in a restaurant usually involves\nthe following steps:\n\n1. receive order from the client.\n1. pass the order to the kitchen, and wait for the food to be cooked.\n1. start cooking the food in the kitchen.\n1. when the food is fully cooked deliver this food to the client.\n\nIf you think about the bullet points above, you will notice that one big moment of waiting time\nis present in this whole process, which is while the food is being cooked\ninside the kitchen. While the food is being prepped, both the waiter and the client\nthemselves are waiting for the food to be ready and delivered.\n\nIf we write a program to represent this restaurant, more specifically, a single-threaded program, then\nthis program would be very inefficient. Because the program would stay in idle, waiting for a considerable amount\nof time on the \"check if food is ready\" step. Consider the code snippet exposed below that could\npotentially represent such program.\n\nThe problem with this program is the while loop. This program will spend a lot of time\nwaiting on the while loop, doing nothing more than just checking if the food is ready.\nThis is a waste of time. Instead of waiting for something to happen, the waiter\ncould just send the order to the kitchen, and just move on, and continue with receiving\nmore orders from other clients, and sending more orders to the kitchen, instead\nof doing nothing and waiting for the food to be ready.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst order = Order.init(\"Pizza Margherita\", n = 1);\nconst waiter = Waiter.init();\nwaiter.receive_order(order);\nwaiter.ask_kitchen_to_cook();\nvar food_not_ready = true;\nwhile (food_not_ready) {\n    food_not_ready = waiter.is_food_ready();\n}\nconst food = waiter.get_food_from_kitchen();\nwaiter.send_food_to_client(food);\n```\n:::\n\n\n\n\nThis is why threads would be a great fit for this program. We could use threads\nto free the waiters from their \"waiting duties\", so they can go on with their\nother tasks, and receive more orders. Take a look at the next example, where I have re-written the above\nprogram into a different program that uses threads to cook and deliver the orders.\n\nYou can see in this program that when a waiter receives a new order\nfrom a client, this waiter executes the `send_order()` function.\nThe only thing that this function does is to create a new thread\nand detaches it. Since creating a thread is a very fast operation,\nthis `send_order()` function returns almost immediately,\nso the waiter spends almost no time worrying about the order, and just\nmove on and tries to get the next order from the clients.\n\nInside the new thread created, the order gets cooked by a chef, and when the\nfood is ready, it's delivered to the client's table.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn cook_and_deliver_order(order: *Order) void {\n    const chef = Chef.init();\n    const food = chef.cook(order.*);\n    chef.deliver_food(food);\n}\nfn send_order(order: Order) void {\n    const cook_thread = Thread.spawn(\n        .{}, cook_and_deliver_order, .{&order}\n    );\n    cook_thread.detach();\n}\n\nconst waiter = Waiter.init();\nwhile (true) {\n    const order = waiter.get_new_order();\n    if (order) {\n        send_order(order);\n    }\n}\n```\n:::\n\n\n\n\n\n\n## Threads versus processes\n\nWhen we run a program, this program is executed as a *process* in the operating system.\nThis is a one to one relationship, each program or application that you execute\nis a separate process in the operating system. But each program, or each process,\ncan create and contain multiple threads inside of it. Therefore,\nprocesses and threads have a one to many relationship.\n\nThis also means that every thread that we create is always associated with a particular process in our computer.\nIn other words, a thread is always a subset (or a children) of an existing process.\nAll threads share some of the resources associated with the process from which they were created.\nAnd because threads share resources with the process, they are very good for making communication\nbetween tasks easier.\n\nFor example, suppose that you were developing a big and complex application\nthat would be much simpler if you could split it in two, and make these two separate pieces talk\nwith each other. Some programmers opt to effectively write these two pieces of the codebase as two\ncompletely separate programs, and then, they use IPC (*inter-process communication*) to make these\ntwo separate programs/processes talk to each other, and make them work together.\n\nHowever, some programmers find IPC hard to deal with, and, as consequence,\nthey prefer to write one piece of the codebase as the \"main part of the program\",\nor, as the part of the code that runs as the process in the operating system,\nwhile the other piece of the codebase is written as a task to be executed in\na new thread. A process and a thread can easily comunicate with each other\nthrough both control flow, and also, through data, because they share and have\naccess to the same standard file descriptors (`stdout`, `stdin`, `stderr`), and also to the\nsame memory space on the heap and global data section.\n\n\nIn more details, each thread that you create have a separate stack frame reserved just for that thread,\nwhich essentially means that each local object that you create inside this thread, is local to that\nthread, i.e., the other threads cannot see this local object. Unless this object that you have created\nis an object that lives on the heap. In other words, if the memory associated with this object\nis on the heap, then, the other threads can potentially access this object.\n\nTherefore, objects that are stored in the stack are local to the thread where they were created.\nBut objects that are stored on the heap are potentially accessible to other threads. All of this means that,\neach thread has its own separate stack frame, but, at the same time, all threads share\nthe same heap, the same standard file descriptors (which means that they share the same `stdout`, `stdin`, `stderr`),\nand the same global data section in the program.\n\n\n\n## Creating a thread\n\nWe create new threads in Zig by first importing the `Thread` struct into\nour current Zig module and then calling the `spawn()` method of this struct,\nwhich creates (or \"spawns\") a new thread of execution from our current process.\nThis method has three arguments, which are, respectively:\n\n1. a `SpawnConfig` object, which contains configurations for the spawn process.\n1. the name of the function that is going to be executed (or that is going to be \"called\") inside this new thread.\n1. a list of arguments (or inputs) to be passed to the function provided in the second argument.\n\nWith these three arguments, you can control how the thread gets created, and also, specify which\nwork (or \"tasks\") will be performed inside this new thread. A thread is just a separate context of execution,\nand we usually create new threads in our code because we want to perform some work inside this\nnew context of execution. And we specify which exact work, or which exact steps that are going to be\nperformed inside this context by providing the name of a function as the second argument of the `spawn()` method.\n\nThus, when this new thread gets created, this function that you provided as input to the `spawn()`\nmethod gets called, or gets executed inside this new thread. You can control the\narguments, or the inputs that are passed to this function when it gets called by providing\na list of arguments (or a list of inputs) in the third argument of the `spawn()` method.\nThese arguments are passed to the function in the same order that they are\nprovided to `spawn()`.\n\nFurthermore, the `SpawnConfig` is a struct object with only two possible fields, or, two possible members, that you\ncan set to tailor the spawn behaviour. These fields are:\n\n- `stack_size`: you can provide a `usize` value to specify the size (in bytes) of the thread's stack frame. By default, this value is: $16 \\times 1024 \\times 1024$.\n- `allocator`: you can provide an allocator object to be used when allocating memory for the thread.\n\nTo use one of these two fields (or \"configs\"), you just have to create a new object of type `SpawnConfig`,\nand provide this object as input to the `spawn()` method. But, if you are not interested in using\none of these configs, and you are ok with using just the defaults, you can just provide an anonymous\nstruct literal (`.{}`) in place of this `SpawnConfig` argument.\n\nAs our first, and very simple example, consider the code exposed below.\nInside the same program, you can create multiple threads of execution if you want to.\nBut, in this first example, we are creating just a single thread of execution, because\nwe call `spawn()` only once.\n\nAlso, notice in this example that we are executing the function `do_some_work()`\ninside the new thread. Since this function receives no inputs, because it has\nno arguments, we have passed an empty list in this instance, or more precisely,\nan empty, anonymous struct (`.{}`) in the third argument of `spawn()`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Thread = std.Thread;\nfn do_some_work() !void {\n    _ = try stdout.write(\"Starting the work.\\n\");\n    std.time.sleep(100 * std.time.ns_per_ms);\n    _ = try stdout.write(\"Finishing the work.\\n\");\n}\n\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, do_some_work, .{});\n    thread.join();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nStarting the work.Finishing the work.\n```\n\n\n:::\n:::\n\n\n\n\nNotice the use of `try` when calling the `spawn()` method. This means\nthat this method can return an error in some circumstances. One circumstance\nin particular is when you attempt to create a new thread, when you have already\ncreated too much (i.e., you have exceeded the quota of concurrent threads in your system).\n\nBut, if the new thread is successfully created, the `spawn()` method returns a handler\nobject (which is just an object of type `Thread`) to this new thread. You can use\nthis handler object to effectively control all aspects of the thread.\n\nWhen the thread gets created, the function that you provided as input to `spawn()`\ngets invoked (i.e., gets called) to start the execution on this new thread.\nIn other words, every time you call `spawn()`, not only is a new thread created,\nbut the \"start work button\" of this thread is also automatically pressed.\nSo the work being performed in this thread starts as soon as the thread is created.\nThis is similar to how `pthread_create()` from the `pthreads` library in C works,\nwhich also starts the execution as soon as the thread is created.\n\n\n## Returning from a thread\n\nWe have learned in the previous section that the execution of the thread starts as soon as\nthe thread is created. Now, we will learn how to \"join\" or \"detach\" a thread in Zig.\n\"Join\" and \"detach\" are operations that control how the thread returns to\nthe main thread, or to the main process in our program.\n\nWe perform these operations by using the methods `join()` and `detach()` from the thread handler object.\nEvery thread that you create can be marked as either *joinable* or *detached* [@linux_pthread_create].\nYou can turn a thread into a *detached* thread by calling the `detach()` method\nfrom the thread handler object. But if you call the `join()` method instead, then this thread\nbecomes a *joinable* thread.\n\nA thread cannot be both *joinable* and *detached*. Which in general means\nthat you cannot call both `join()` and `detach()` on the same thread.\nBut a thread must be one of the two, meaning that, you should always call\neither `join()` or `detach()` over a thread. If you don't call\none of these two methods over your thread, you introduce undefined behaviour into your program,\nwhich is described in @sec-not-call-join-detach.\n\nNow, let's describe what each of these two methods do to your thread.\n\n\n### Joining a thread\n\nWhen you join a thread, you are essentially saying: \"Hey! Could you please wait for the thread to finish,\nbefore you continue with your execution?\". For example, if we come back to our first and simplest example\nof a thread in Zig, we created a single thread inside the `main()` function of our program\nand just called `join()` on this thread at the end. This section of the code example is reproduced below.\n\nBecause we are joining this new thread inside the `main()`'s scope, it means that the\nexecution of the `main()` function is temporarily stopped, to wait for the execution of the thread\nto finish. That is, the execution of `main()` stops temporarily at the line where `join()` gets called,\nand it will continue only after the thread has finished its tasks.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, do_some_work, .{});\n    thread.join();\n}\n```\n:::\n\n\n\n\nBecause we have joined this new thread inside the `main()` scope, we have a\nguarantee that this new thread will finish before the end of the execution of `main()`.\nBecause it's guaranteed that `main()` will wait for the thread to finish its tasks.\n\nIn the example above, there are no more expressions after the `join()` call. We just have the end\nof the `main()`'s scope, and, therefore, the execution of our program just ends after the thread finishes its tasks,\nsince there is nothing more to do. But what if we had more stuff to do after the join call?\n\nTo demonstrate this other possibility, consider the next example exposed\nbelow. Here, we create a `print_id()` function, that just receives an id\nas input, and prints it to `stdout`. In this example, we are creating two\nnew threads, one after another. Then, we join the first thread, then,\nwe wait for two whole seconds, then, at last, we join the second thread.\n\nThe idea behind this example is that the last `join()` call is executed\nonly after the first thread finishes its task (i.e., the first `join()` call),\nand the two-second delay. If you compile and run this\nexample, you will notice that most messages are quickly printed to `stdout`,\ni.e., they appear almost instantly on your screen.\nHowever, the last message (\"Joining thread 2\") takes around 2 seconds to appear\non the screen.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_id(id: *const u8) !void {\n    try stdout.print(\"Thread ID: {d}\\n\", .{id.*});\n}\n\npub fn main() !void {\n    const id1: u8 = 1;\n    const id2: u8 = 2;\n    const thread1 = try Thread.spawn(.{}, print_id, .{&id1});\n    const thread2 = try Thread.spawn(.{}, print_id, .{&id2});\n\n    _ = try stdout.write(\"Joining thread 1\\n\");\n    thread1.join();\n    std.time.sleep(2 * std.time.ns_per_s);\n    _ = try stdout.write(\"Joining thread 2\\n\");\n    thread2.join();\n}\n```\n:::\n\n\n\n\n```\nThread ID: Joining thread 1\n1\nThread ID: 2\nJoining thread 2\n```\n\nThis demonstrates that both threads finish their work (i.e., printing the IDs)\nvery fast, before the two seconds of delay end. Because of that, the last `join()` call\nreturns pretty much instantly. Because when this last `join()` call happens, the second\nthread has already finished its task.\n\nNow, if you compile and run this example, you will also notice that, in some cases,\nthe messages intertwine with each other. In other words, you might see\nthe message \"Joining thread 1\" inserted in the middle of the message \"Thread 1\",\nor vice-versa. This happens because:\n\n- the threads are executing basically at the same time as the main process of the program (i.e., the `main()` function).\n- the threads share the same `stdout` from the main process of the program, which means that the messages that the threads produce are sent to exact same place as the messages produced by the main process.\n\nBoth of these points were described previously in @sec-what-thread.\nSo the messages might get intertwined because they are being produced and\nsent to the same `stdout` roughly at the same time.\nAnyway, when you call `join()` over a thread, the current process will wait\nfor the thread to finish before it continues, and, when the thread finishes its\ntask, the resources associated with this thread are automatically freed, and\nthe current process continues with its execution.\n\n\n### Detaching a thread\n\nWhen you detach a thread, the resources associated with this thread are automatically\nreleased back to the system, without the need for another thread to join with this terminated thread.\n\nIn other words, when you call `detach()` on a thread it's like when your children become adults,\ni.e., they become independent from you. A detached thread frees itself, and when this thread finishes its\ntasks, it does not report the results back to you. Thus, you normally mark a thread as *detached*\nwhen you don't need to use the return value of the thread, or when you don't care about\nwhen exactly the thread finishes its job, i.e., the thread solves everything by itself.\n\nTake the code example below. We create a new thread, detach it, and then, we just\nprint a final message before we end our program. We use the same `print_id()`\nfunction that we have used over the previous examples.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_id(id: *const u8) !void {\n    try stdout.print(\"Thread ID: {d}\\n\", .{id.*});\n}\n\npub fn main() !void {\n    const id1: u8 = 1;\n    const thread1 = try Thread.spawn(.{}, print_id, .{&id1});\n    thread1.detach();\n    _ = try stdout.write(\"Finish main\\n\");\n}\n```\n:::\n\n\n\n\n```\nFinish main\n```\n\nNow, if you look closely at the output of this code example, you will notice\nthat only the final message in main was printed to the console. The message\nthat was supposed to be printed by `print_id()` did not appear in the console.\nWhy? It's because the main process of our program has finished first,\nbefore the thread was able to say anything.\n\nAnd that is perfectly ok behaviour, because the thread was detached, so it was\nable to free itself, without the need to wait for the main process.\nIf you ask main to sleep (or \"wait\") for some extra nanoseconds, before it ends, you will likely\nsee the message printed by `print_id()`, because you give enough time for the thread to\nfinish before the main process ends.\n\n\n## Thread pools\n\nThread pools is a very popular programming pattern, which is used especially on servers and daemons processes.\nA thread pool is just a set of threads, or a \"pool\" of threads. Many programmers like to use this pattern because it makes\nit easier to manage and use multiple threads in your program, instead of manually creating the threads when you need them.\n\nAlso, using thread pools might increase performance as well in your program,\nespecially if your program is constantly creating threads to perform short-lived tasks.\nIn such instance, a thread pool might cause an increase in performance because you do not have be constantly\ncreating and destroying threads all the time, so you don't face a lot of the overhead involved\nin this constant process of creating and destroying threads.\n\nThe main idea behind a thread pool is to have a set of threads already created and ready to perform\ntasks at all times. You create a set of threads at the moment that your program starts, and keep\nthese threads alive while your program runs. Each of these threads will be either performing a task, or\nwaiting for a task to be assigned.\nEvery time a new task emerges in your program, this task is added to a \"queue of tasks\",\nand the moment that a thread becomes available and ready to perform a new task,\nthis thread takes the next task from the \"queue of tasks\", and it simply performs the task.\n\nThe Zig Standard Library offers a thread pool implementation on the `std.Thread.Pool` struct.\nYou create a new instance of a `Pool` object by providing a `Pool.Options` object\nas input to the `init()` method of this struct. A `Pool.Options` object, is a struct object that contains\nconfigurations for the pool of threads. The most important settings in this struct object are\nthe members `n_jobs` and `allocator`. As the name suggests, the member `allocator` should receive an allocator object,\nwhile the member `n_jobs` specifies the number of threads to be created and maintained in this pool.\n\nConsider the example exposed below, that demonstrates how can we create a new thread pool object.\nHere, we create a `Pool.Options` object that contains\na general purpose allocator object, and also, the `n_jobs` member was set to 4, which\nmeans that the thread pool will create and use 4 threads.\n\nAlso notice that the `pool` object was initially set to `undefined`. This allow us\nto initially declare the thread pool object, but not properly instantiate the\nunderlying memory of the object. You have to initially declare your thread pool object\nby using `undefined` like this, because the `init()` method of `Pool` needs\nto have an initial pointer to properly instantiate the object.\n\nSo, just remember to create your thread pool object by using `undefined`, and then,\nafter that, you call the `init()` method over the object.\nYou should also not forget to call the `deinit()` method over the thread pool\nobject, once you are done with it, to release the resources allocated for the thread pool. Otherwise, you will\nhave a memory leak in your program.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Pool = std.Thread.Pool;\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const opt = Pool.Options{\n        .n_jobs = 4,\n        .allocator = allocator,\n    };\n    var pool: Pool = undefined;\n    try pool.init(opt);\n    defer pool.deinit();\n}\n```\n:::\n\n\n\n\nNow that we know how to create `Pool` objects, we have\nto understand how to assign tasks to be executed by the threads in this pool object.\nTo assign a task to be performed by a thread, we need to call the `spawn()` method\nfrom the thread pool object.\n\nThis `spawn()` method works identical to the `spawn()` method from the\n`Thread` object. The method has almost the same arguments as the previous one,\nmore precisely, we don't have to provide a `SpawnConfig` object in this case.\nBut instead of creating a new thread, this `spawn()` method from\nthe thread pool object just registers a new task in the internal \"queue of tasks\" to be performed,\nand any available thread in the pool will get this task, and it will simply perform the task.\n\nIn the example below, we are using our previous `print_id()` function once again.\nBut you may notice that the `print_id()` function is a little different this time,\nbecause now we are using `catch` instead of `try` in the `print()` call.\nCurrently, the `Pool` struct only supports functions that don't return errors\nas tasks. Thus, when assigning tasks to threads in a thread pool, it is essential to use functions\nthat don't return errors. That is why we are using `catch` here, so that the\n`print_id()` function don't return an error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_id(id: *const u8) void {\n    _ = stdout.print(\"Thread ID: {d}\\n\", .{id.*})\n        catch void;\n}\nconst id1: u8 = 1;\nconst id2: u8 = 2;\ntry pool.spawn(print_id, .{&id1});\ntry pool.spawn(print_id, .{&id2});\n```\n:::\n\n\n\n\nThis limitation should probably not exist, and, in fact, it's already on the radar of the\nZig team to fix this issue, and it's being tracked in an [open issue](https://github.com/ziglang/zig/issues/18810)[^issue].\nSo, if you do need to provide a function that might return an error as the task\nto be performed by the threads in the thread pool, then, you are either limited to:\n\n- implementing your own thread pool that does not have this limitation.\n- wait for the Zig team to actually fix this issue.\n\n[^issue]: <https://github.com/ziglang/zig/issues/18810>\n\n\n\n\n## Mutexes\n\nMutexes are a classic component of every thread library. In essence, a mutex is a *Mutually Exclusive Flag*, and this flag\nacts like a type of \"lock\", or as a gate keeper to a particular section of your code. Mutexes are related to thread synchronization,\nmore specifically, they prevent you from having some classic race conditions in your program,\nand, therefore, major bugs and undefined behaviour that are usually difficult to track and understand.\n\nThe main idea behind a mutex is to help us to control the execution of a particular section of the code, and to\nprevent two or more threads from executing this particular section of the code at the same time.\nMany programmers like to compare a mutex to a bathroom door (which typically has a lock).\nWhen a thread locks its own mutex object, it's like if the bathroom door was locked.\nTherefore, other people (in this case, other threads) who want to use the same bathroom at the same time\nmust be patient and simply wait for the current occupant (or thread) to unlock the door and get out of the bathroom.\n\nSome other programmers also like to explain mutexes by using the analogy of \"each person will have their turn to speak\".\nThis is the analogy used in the [*Multithreading Code* video from the Computerphile project](https://www.youtube.com/watch?v=7ENFeb-J75k&ab_channel=Computerphile)[^computerphile].\nImagine if you are in a conversation circle. There is a moderator in this circle, which is the person that decides who\nhas the right to speak at that particular moment. The moderator gives a green card (or some sort of an authorization card) to the person that\nis going to speak, and, as a result, everyone else must be silent and hear this person that has the green card.\nWhen the person finishes talking, they give the green card back to the moderator, and the moderator decides\nwho is going to talk next, and delivers the green card to that person. And the cycle goes on like this.\n\n[^computerphile]: <https://www.youtube.com/watch?v=7ENFeb-J75k&ab_channel=Computerphile>\n\n\nA mutex acts like the moderator in this conversation circle. The mutex authorizes one single thread to execute a specific section of the code,\nand it also blocks the other threads from executing this same section of the code. If these other threads want to execute this same\npiece of the code, they are forced to wait for the the authorized thread to finish first.\nWhen the authorized thread finishes executing this code, the mutex authorizes the next thread to execute this code,\nwhile the remaining threads remain blocked. Therefore, a mutex is like a moderator that does a \"each\nthread will have their turn to execute this section of the code\" type of control.\n\n\nMutexes are especially used to prevent data race problems from happening. A data race problem happens when two or more threads\nare trying to read from or write to the same shared object at the same time.\nSo, when you have an object that is shared will all threads, and, you want to avoid two or more threads from\naccessing this same object at the same time, you can use a mutex to lock the part of the code that access this specific object.\nWhen a thread tries to run this code that is locked by a mutex, this thread stops its execution,\nand patiently waits for this section of the codebase to be unlocked to continue.\n\nNotice that mutexes are normally used to lock areas of the codebase that access/modify data that is **shared** with all threads,\ni.e., objects that are either stored in the global data section, or in the heap space of your program.\nSo mutexes are not normally used on areas of the codebase that access/modify objects that are local to the thread.\n\n\n\n### Critical section {#sec-critical-section}\n\nCritical section is a concept commonly associated with mutexes and thread synchronization.\nIn essence, a critical section is the section of the program that a thread access/modify a shared resource\n(i.e., an object, a file descriptor, something that all threads have access to). In other words,\na critical section is the section of the program where race conditions might happen, and, therefore,\nwhere undefined behaviour can be introduced into the program.\n\nWhen we use mutexes in our program, the critical section defines the area of the codebase that we want to lock.\nSo we normally lock the mutex object at the beginning of the critical section,\nand then, we unlock it at the end of the critical section.\nThe two bullet points exposed below comes from the \"Critical Section\" article from GeekFromGeeks,\nand they summarise well the role that a critical section plays in the thread synchronization problem [@geeks_critical_section].\n\n\n1. The critical section must be executed as an atomic operation, which means that once one thread or process has entered the critical section, all other threads or processes must wait until the executing thread or process exits the critical section. The purpose of synchronization mechanisms is to ensure that only one thread or process can execute the critical section at a time.\n1. The concept of a critical section is central to synchronization in computer systems, as it is necessary to ensure that multiple threads or processes can execute concurrently without interfering with each other. Various synchronization mechanisms such as semaphores, mutexes, monitors, and condition variables are used to implement critical sections and ensure that shared resources are accessed in a mutually exclusive manner.\n\n\n### Atomic operations {#sec-atomic-operation}\n\nYou will also see the term \"atomic operation\" a lot when reading about threads, race conditions and mutexes.\nIn summary, an operation is categorized as \"atomic\" when a context switch cannot occur in\nthe middle of the operation. In other words, this operation is always done from beginning to end, without interruptions\nof another process or operation in the middle of its execution phase.\n\nNot many operations today are atomic. But why do atomic operations matter here? It's because data races\n(which is a type of a race condition) cannot happen on operations that are atomic.\nSo if a particular line in your code performs an atomic operation, then this line will never\nsuffer from a data race problem. Therefore, programmers sometimes use an atomic operation\nto protect themselves from data race problems in their code.\n\nWhen you have an operation that is compiled into just one single assembly instruction, this operation might be atomic,\nbecause it's just one assembly instruction. But this is not guaranteed. This is usually true for old CPU architectures\n(such as `x86`). But nowadays, most assembly instructions in modern CPU architectures are broken down into multiple micro-tasks,\nwhich inherently makes the operation non-atomic, even if it consists of a single assembly instruction.\n\nThe Zig Standard Library offers some atomic functionality in the `std.atomic` module.\nIn this module, you will find a public and generic function called `Value()`. With this function we create an \"atomic object\", which is\na value that contains some native atomic operations, most notably, a `load()` and a `fetchAdd()` operation.\nIf you have experience with multithreading in C++, you probably have recognized this pattern. So yes, this generic\n\"atomic object\" in Zig is essentially identical to the template struct `std::atomic` from the C++ Standard Library.\nIt's important to emphasize that only primitive data types (i.e., the types presented in @sec-primitive-data-types)\nare supported by these atomic operations in Zig.\n\n\n\n\n\n### Data races and race conditions\n\nTo understand why mutexes are used, we need to understand better the problem that they seek\nto solve, which can be summarized into data race problems. A data race problem is a type of a race condition,\nwhich happens when one thread is accessing a particular memory location (i.e., a particular shared object) at the same\ntime that another thread is trying to write/save new data into this same memory location (i.e., the same shared object).\n\nWe can simply define a race condition as any type of bug in your program that is based\non a \"who gets there first\" problem. A data race problem is a type of a race condition, because it occurs when two or more parties\nare trying to read and write into the same memory location at the same time, and, therefore, the end result of this operation\ndepends completely on who gets to this memory location first.\nAs a consequence, a program that has a data race problem will likely produce a different result each time that we execute it.\n\nThus, race conditions produce undefined behaviour and unpredictability because the program produces\na different answer each time a different person gets to the target location before the others.\nAnd, we have no easy way to either predict or control who is getting to this target location first.\nIn other words, each time your program runs, you may get a different answer because a different person,\nfunction, or part of the code finishes its tasks before the others.\n\nAs an example, consider the code snippet exposed below. In this example, we create a global counter\nvariable, and we also create an `increment()` function, whose job is to just increment this global counter\nvariable in a for loop.\n\nSince the for loop iterates 1 hundred thousand times, and, we create two separate threads\nin this code example, what number do you expect to see in the final message printed to `stdout`?\nThe answer should be 2 hundred thousand. Right? Well, in theory, this program was supposed\nto print 2 hundred thousand at the end, but in practice, every time that I execute this program\nI get a different answer.\n\nIn the example exposed below, you can see that this time the end\nresult was 117254, instead of the expected 200000. The second time I executed this program,\nI got the number 108592 as the result. So the end result of this program is varying, but it never gets\nto the expected 200000 that we want.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// Global counter variable\nvar counter: usize = 0;\n// Function to increment the counter\nfn increment() void {\n    for (0..100000) |_| {\n        counter += 1;\n    }\n}\n\npub fn main() !void {\n    const thr1 = try Thread.spawn(.{}, increment, .{});\n    const thr2 = try Thread.spawn(.{}, increment, .{});\n    thr1.join();\n    thr2.join();\n    try stdout.print(\"Couter value: {d}\\n\", .{counter});\n}\n```\n:::\n\n\n\n\n```\nCouter value: 117254\n```\n\n\nWhy this is happening? The answer is: because this program contains a data race problem.\nThis program would print the correct number 200000 if and only if the first thread finishes\nits tasks before the second thread starts to execute. But that is very unlikely to happen.\nBecause the process of creating the thread is too fast, and therefore, both threads start to execute roughly\nat the same time. If you change this code to add some nanoseconds of sleep between the first and the second calls to `spawn()`,\nyou will increase the chances of the program producing the \"correct result\".\n\nSo the data race problem happens because both threads are reading and writing to the same\nmemory location at roughly the same time. In this example, each thread is essentially performing\nthree basic operations at each iteration of the for loop, which are:\n\n1. reading the current value of `count`.\n1. incrementing this value by 1.\n1. writing the result back into `count`.\n\nIdeally, a thread B should read the value of `count`, only after the other thread A has finished\nwriting the incremented value back into the `count` object. Therefore, in the ideal scenario, which is demonstrated\nin @tbl-data-race-ideal, the threads should work in sync with each other. But the reality is that these\nthreads are out of sync, and because of that, they suffer from a data race problem, which is demonstrated\nin @tbl-data-race-not.\n\nNotice that, in the data race scenario (@tbl-data-race-not), the read performed by a thread B happens\nbefore the write operation of thread A, and that ultimately leads to wrong results at the end of the program.\nBecause when thread B reads the value of the `count` variable, thread A is still processing\nthe initial value from `count`, and has not yet written the new, incremented value back to `count`. As a result,\nthread B ends up reading the same initial (or \"old\") value from `count` instead of\nthe updated, incremented value that thread A would have written.\n\n\n::: {#tbl-data-race-ideal}\n\n| Thread 1    | Thread 2    | Integer value |\n|-------------|-------------|---------------|\n| read value  |             | 0             |\n| increment   |             | 1             |\n| write value |             | 1             |\n|             | read value  | 1             |\n|             | increment   | 2             |\n|             | write value | 2             |\n\n: An ideal scenario for two threads incrementing the same integer value\n:::\n\n::: {#tbl-data-race-not}\n\n| Thread 1    | Thread 2    | Integer value |\n|-------------|-------------|---------------|\n| read value  |             | 0             |\n|             | read value  | 0             |\n| increment   |             | 1             |\n|             | increment   | 1             |\n| write value |             | 1             |\n|             | write value | 1             |\n\n: A data race scenario when two threads are incrementing the same integer value\n:::\n\n\nIf you think about these diagrams exposed in form of tables, you will notice that they relate back to our discussion of atomic operations\nin @sec-atomic-operation. Remember, atomic operations are operations that the CPU executes\nfrom beginning to end, without interruptions from other threads or processes. So,\nthe scenario exposed in @tbl-data-race-ideal does not suffer from a data race, because\nthe operations performed by thread A are not interrupted in the middle by the operations\nfrom thread B.\n\nIf we also think about the discussion of critical section from @sec-critical-section, we can identify\nthe section that representes the critical section of the program, which is the section that is vulnerable\nto data race conditions. In this example, the critical section of the program is the line where we increment\nthe `counter` variable (`counter += 1`). So, ideally, we want to use a mutex, and lock right before this line, and then\nunlock right after this line.\n\n\n\n\n### Using mutexes in Zig\n\nNow that we know the problem that mutexes seek to solve, we can learn how to use them in Zig.\nMutexes in Zig are available through the `std.Thread.Mutex` struct from the Zig Standard Library.\nIf we take the same code from the previous example, and improve it with mutexes, to solve\nour data race problem, we get the code example below.\n\nNotice that this time, we had to alter the `increment()` function to receive a pointer to\nthe `Mutex` object as input. All that we need to do, to make this program safe against\ndata race problems, is to call the `lock()` method at the beginning of\nthe critical section, and then, call `unlock()` at the end of the critical section.\nNotice that the output of this program is now the correct number of 200000.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Thread = std.Thread;\nconst Mutex = std.Thread.Mutex;\nvar counter: usize = 0;\nfn increment(mutex: *Mutex) void {\n    for (0..100000) |_| {\n        mutex.lock();\n        counter += 1;\n        mutex.unlock();\n    }\n}\n\npub fn main() !void {\n    var mutex: Mutex = .{};\n    const thr1 = try Thread.spawn(.{}, increment, .{&mutex});\n    const thr2 = try Thread.spawn(.{}, increment, .{&mutex});\n    thr1.join();\n    thr2.join();\n    try stdout.print(\"Couter value: {d}\\n\", .{counter});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nCouter value: 200000\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n## Read/Write locks\n\nMutexes are normally used when it's not always safe for two or more threads running the same\npiece of code at the same time. In contrast, read/write locks are normally used in situations\nwhere you have a mixture of scenarios, i.e., there are some pieces of the codebase that are safe\nto run in parallel, and other pieces that are not safe.\n\nFor example, suppose that you have multiple threads that uses the same shared file in the filesystem to store some configurations, or\nstatistics. If two or more threads try to read the data from this same file at the same time, nothing bad happens.\nSo this part of the codebase is perfectly safe to be executed in parallel, with multiple threads reading the same file at the same time.\n\nHowever, if two or more threads try to write data into this same file at the same time, then we cause some race condition\nproblems. So this other part of the codebase is not safe to be executed in parallel.\nMore specifically, a thread might end up writing data in the middle of the data written by the other thread.\nThis process of two or more threads writing to the same location might lead to data corruption.\nThis specific situation is usually called a *torn write*.\n\nThus, what we can extract from this example is that there are certain types of operations that cause\na race condition, but there are also other types of operations that do not cause a race condition problem.\nYou could also say that there are types of operations that are susceptible to race condition problems,\nand there are other types of operations that are not.\n\nA read/write lock is a type of lock that acknowledges the existence of this specific scenario, and you can\nuse this type of lock to control which parts of the codebase are safe to run in parallel and which parts are not.\n\n\n\n### Exclusive lock vs shared lock\n\nTherefore, a read/write lock is a little different from a mutex. Because a mutex is always an *exclusive lock*, meaning that, only\none thread is allowed to execute at all times. With an exclusive lock, the other threads are always \"excluded\",\ni.e., they are always blocked from executing. But in a read/write lock, the other threads might be authorized\nto run at the same time, depending on the type of lock that they acquire.\n\nWe have two types of locks in a read/write lock, which are: an exclusive lock and a shared lock. An exclusive lock works exactly the same\nas a mutex, while a shared lock is a lock that does not block the other threads from running at the same time.\nIn the `pthreads` C library, read/write locks are available through the `pthread_rwlock_t` C struct. With\nthis C struct, you can create:\n\n- a \"write lock\", which corresponds to an exclusive lock.\n- a \"read lock\", which corresponds to a shared lock.\n\nThe terminology might be a little different compared to Zig. But the meaning is still the same.\nTherefore, just remember this relationship, write locks are exclusive locks, while read locks are shared locks.\n\nWhen a thread tries to acquire a read lock (i.e., a shared lock), this thread gets the shared lock\nif and only if another thread does not currently hold a write lock (i.e., an exclusive lock), and also\nif there are no other threads already in the queue,\nwaiting for their turn to acquire a write lock. In other words, the thread in the queue has attempted\nto get a write lock earlier, but this thread was blocked\nbecause there was another thread running that already had a write lock. As a consequence, this thread is in the queue to get a write lock,\nand it's currently waiting for the other thread with a write lock to finish its execution.\n\nWhen a thread tries to acquire a read lock, but it fails in acquiring this read lock, either because there is\na thread with a write lock already running, or because there is a thread in the queue to get a write lock,\nthe execution of this thread is instantly blocked, i.e., paused. This thread will indefinitely attempt to get the\nread lock, and its execution will be unblocked (or unpaused) only after this thread successfully acquires the read lock.\n\nIf you think deeply about this dynamic between read locks versus write locks, you might notice that a read lock is basically a safety mechanism.\nMore specifically, it's a way for us to\nallow a particular thread to run together with the other threads only when it's safe to. In other words, if there is currently\na thread with a write lock running, then it's very likely not safe for the thread that is trying to acquire the read lock to run now.\nAs a consequence, the read lock protects this thread from running into dangerous waters, and patiently waits for the\n\"write lock\" thread to finishes its tasks before it continues.\n\nOn the other hand, if there are only \"read lock\" (i.e., \"shared lock\") threads currently running\n(i.e., not a single \"write lock\" thread currently exists), then it\nis perfectly safe for this thread that is acquiring the read lock to run in parallel with the other\nthreads. As a result, the read lock just\nallows for this thread to run together with the other threads.\n\nThus, by using read locks (shared locks) in conjunction with write locks (exclusive locks), we can control which regions or sections\nof our multithreaded code is safe to have parallelism, and which sections are not safe to have parallelism.\n\n\n\n\n\n### Using read/write locks in Zig\n\nThe Zig Standard Library supports read/write locks through the `std.Thread.RwLock` module.\nIf you want a particular thread to acquire a shared lock (i.e., a read lock), you should\ncall the `lockShared()` method from the `RwLock` object. But, if you want this thread\nto acquire an exclusive lock (i.e., a write lock) instead, then you should call the\n`lock()` method from the `RwLock` object.\n\nAs with mutexes, we also have to unlock the shared or exclusive locks that we acquire through a read/write lock object,\nonce we are at the end of our \"critical section\". If you have acquired an exclusive lock, then, you unlock\nthis exclusive lock by calling the `unlock()` method from the read/write lock object. In contrast,\nif you have acquired a shared lock instead, then, call `unlockShared()` to unlock this shared lock.\n\nAs a simple example, the snippet below creates three separate threads responsible for reading the\ncurrent value in a `counter` object, and it also creates another thread responsible for writing\nnew data into the `counter` object (incrementing it, more specifically).\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar counter: u32 = 0;\nfn reader(lock: *RwLock) !void {\n    while (true) {\n        lock.lockShared();\n        const v: u32 = counter;\n        try stdout.print(\"{d}\", .{v});\n        lock.unlockShared();\n        std.time.sleep(2 * std.time.ns_per_s);\n    }\n}\nfn writer(lock: *RwLock) void {\n    while (true) {\n        lock.lock();\n        counter += 1;\n        lock.unlock();\n        std.time.sleep(2 * std.time.ns_per_s);\n    }\n}\n\npub fn main() !void {\n    var lock: RwLock = .{};\n    const thr1 = try Thread.spawn(.{}, reader, .{&lock});\n    const thr2 = try Thread.spawn(.{}, reader, .{&lock});\n    const thr3 = try Thread.spawn(.{}, reader, .{&lock});\n    const wthread = try Thread.spawn(.{}, writer, .{&lock});\n\n    thr1.join();\n    thr2.join();\n    thr3.join();\n    wthread.join();\n}\n```\n:::\n\n\n\n\n\n## Yielding a thread\n\nThe `Thread` struct supports yielding through the `yield()` method.\nYielding a thread means that the execution of the thread is temporarily stopped,\nand it moves to the end of the priority queue managed by the scheduler of\nyour operating system.\n\nThat is, when you yield a thread, you are essentially saying the following to your OS:\n\"Hey! Could you please stop executing this thread for now, and comeback to continue it later?\".\nYou could also interpret this yield operation as: \"Could you please deprioritize this thread,\nto focus on doing other things instead?\".\nSo this yield operation is also a way for you\nto stop a particular thread, so that you can work and prioritize other threads instead.\n\nIt's important to say that, yielding a thread is a \"not so common\" thread operation these days.\nIn other words, not many programmers use yielding in production, simply because it's hard to use\nthis operation and make it work properly, and also, there\nare better alternatives. Most programmers prefer to use `join()` instead.\nIn fact, most of the time, when you see someone using this \"yield\" operation in some code example,\nthey are usually doing so to help debug race conditions in their applications.\nThat is, this \"yield\" operation is mostly used as a debug tool nowadays.\n\nAnyway, if you want to yield a thread, just call the `yield()` method from it, like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nthread.yield();\n```\n:::\n\n\n\n\n\n\n\n\n\n## Common problems in threads\n\n\n\n### Deadlocks\n\nA deadlock occurs when two or more threads are blocked forever,\nwaiting for each other to release a resource. This usually happens when multiple locks are involved,\nand the order of acquiring them is not well managed.\n\nThe code example below demonstrates a deadlock situation. We have two different threads that execute\ntwo different functions (`work1()` and `work2()`) in this example. And we also have two separate\nmutexes. If you compile and run this code example, you will notice that the program just runs indefinitely,\nwithout ending.\n\nWhen we look into the first thread, which executes the `work1()` function, we can\nnotice that this function acquires the `mut1` lock first. Because this is the first operation\nthat is executed inside this thread, which is the first thread created in the program.\nAfter that, the function sleeps for 1 second, to\nsimulate some type of work, and then, the function tries to acquire the `mut2` lock.\n\nOn the other hand, when we look into the second thread, which executes the `work2()` function,\nwe can see that this function acquires the `mut2` lock first. Because when this thread gets created and it tries\nto acquire this `mut2` lock, the first thread is still sleeping on that \"sleep 1 second\" line.\nAfter acquiring `mut2`, the `work2()` function also sleeps for 1 second, to\nsimulate some type of work, and then the function tries to acquire the `mut1` lock.\n\nThis creates a deadlock situation, because after the \"sleep for 1 second\" line in both threads,\nthread 1 is trying to acquire the `mut2` lock, but this lock is currently being used by thread 2.\nHowever, at this moment, thread 2 is also trying to acquire the `mut1` lock, which is currently\nbeing used by thread 1. Therefore, both threads end up waiting for ever. Waiting for their peer to\nfree the lock that they want to acquire.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar mut1: Mutex = .{}; var mut2: Mutex = .{};\nfn work1() !void {\n    mut1.lock();\n    std.time.sleep(1 * std.time.ns_per_s);\n    mut2.lock();\n    _ = try stdout.write(\"Doing some work 1\\n\");\n    mut2.unlock(); mut1.unlock();\n}\n\nfn work2() !void {\n    mut2.lock();\n    std.time.sleep(1 * std.time.ns_per_s);\n    mut1.lock();\n    _ = try stdout.write(\"Doing some work 1\\n\");\n    mut1.unlock(); mut2.unlock();\n}\n\npub fn main() !void {\n    const thr1 = try Thread.spawn(.{}, work1, .{});\n    const thr2 = try Thread.spawn(.{}, work2, .{});\n    thr1.join();\n    thr2.join();\n}\n```\n:::\n\n\n\n\n\n### Not calling `join()` or `detach()` {#sec-not-call-join-detach}\n\nWhen you do not call either `join()` or `detach()` over a thread, then this thread becomes a \"zombie thread\",\nbecause it does not have a clear \"return point\".\nYou could also interpret this as: \"nobody is properly responsible for managing the thread\".\nWhen we don't establish if a thread is either *joinable* or *detached*,\nnobody becomes responsible for dealing with the return value of this thread, and also,\nnobody becomes responsible for clearing (or freeing) the resources associated with this thread.\n\nYou don't want to be in this situation, so remember to always use `join()` or `detach()`\non the threads that you create. When you don't use one of these methods, we lose\ncontrol over the thread, and its resources are never freed\n(i.e., you have leaked resources in the system).\n\n\n### Cancelling or killing a particular thread\n\nWhen we think about the `pthreads` C library, there is a possible way to asynchronously kill or cancel\na thread, which is by sending a `SIGTERM` signal to the thread through the `pthread_kill()` function.\nBut canceling a thread like this is bad. It's dangerously bad. As a consequence, the Zig implementation\nof threads does not have a similar function, or, a similar way to asynchronously cancel or kill\na thread.\n\nTherefore, if you want to cancel a thread in the middle of its execution in Zig,\nthen one good strategy that you can take is to use control flow in conjunction with `join()`.\nMore specifically, you can design your thread around a while loop that is constantly\nchecking if the thread should continue running.\nIf it's time to cancel the thread, we could make the while loop break, and join the thread with the main thread\nby calling `join()`.\n\nThe code example below demonstrates to some extent this strategy.\nHere, we are using control flow to break the while loop, and exit the thread earlier than\nwhat we have initially planned to. This example also demonstrates how can we use\natomic objects in Zig with the `Value()` generic function that we have mentioned in @sec-atomic-operation.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Thread = std.Thread;\nconst stdout = std.io.getStdOut().writer();\nvar running = std.atomic.Value(bool).init(true);\nvar counter: u64 = 0;\nfn do_more_work() void {\n    std.time.sleep(2 * std.time.ns_per_s);\n}\nfn work() !void {\n    while (running.load(.monotonic)) {\n        for (0..10000) |_| { counter += 1; }\n        if (counter < 15000) {\n            _ = try stdout.write(\n                \"Time to cancel the thread.\\n\"\n            );\n            running.store(false, .monotonic);\n        } else {\n            _ = try stdout.write(\"Time to do more work.\\n\");\n            do_more_work();\n            running.store(false, .monotonic);\n        }\n    }\n}\n\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, work, .{});\n    thread.join();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nTime to cancel the thread.\n```\n\n\n:::\n:::\n",
+    "supporting": [
+      "14-threads_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/14-zig-c-interop/execute-results/html.json b/_freeze/Chapters/14-zig-c-interop/execute-results/html.json
index dac50d94..fe46362b 100644
--- a/_freeze/Chapters/14-zig-c-interop/execute-results/html.json
+++ b/_freeze/Chapters/14-zig-c-interop/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "f39e8db0da66759da16d297f7de43596",
+  "hash": "7f0fb45d8337d93333a20759133b82dc",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Zig interoperability with C\n\nIn this chapter, we are going to discuss the interoperability of Zig with C.\nWe have discussed at @sec-building-c-code how you can use the `zig` compiler to build C code.\nBut we haven't discussed yet how to actually use C code in Zig. In other words,\nwe haven't discussed yet how to call and use C code from Zig.\n\nThis is the main subject of this chapter.\nAlso, in our next small project in this book, we are going to use a C library in it.\nAs consequence, we will put in practice a lot of the knowledge discussed here on\nthis next project.\n\n\n## How to call C code from Zig\n\nInteroperability with C is not something new. Most high-level programming languages have FFI (foreign function interfaces),\nwhich can be used to call C code. For example, Python have Cython, R have `.Call()`, Javascript have `ccall()`, etc.\nBut Zig integrates with C in a deeper level, which affects not only the way that C code get's called, but also,\nhow this C code is compiled and incorporated into your Zig project.\n\nIn summary, Zig have great interoperability with C. If you want to call any C code from Zig,\nyou have to perform the following steps:\n\n- import a C header file into your Zig code.\n- link your Zig code with the C library.\n\n\n### Strategies to import C header files {#sec-strategy-c}\n\nUsing C code in Zig always involves performing the two steps cited above. However, when\nwe talk specifically about the first step listed above, there are currently two\ndifferent ways to perform this first step, which are:\n\n- translating the C header file into Zig code, through the `zig translate-c` command, and then, import and use the translated Zig code.\n- importing the C header file directly into your Zig module through the `@cImport()` built-in function.\n\nIf you are not familiar with `translate-c`, this is a subcommand inside the `zig` compiler that takes C files\nas input, and outputs the Zig representation of the C code present in these C files.\nIn other words, this subcommand works like a transpiler. It takes C code, and translates it into\nthe equivalent Zig code.\n\nI think it would be ok to interpret `translate-c` as a tool to generate Zig bindings\nto C code, similarly to the `rust-bindgen`[^bindgen] tool, which generates Rust FFI bindings to C code.\nBut that would not be a precise interpretation of `translate-c`. The idea behind this tool is\nto really translate the C code into Zig code.\n\n[^bindgen]: <https://github.com/rust-lang/rust-bindgen>\n\nNow, on a surface level, `@cImport()` versus `translate-c` might seem like\ntwo completely different strategies. But in fact, they are effectively the exact same strategy.\nBecause, under the hood, the `@cImport()` built-in function is just a shortcut to `translate-c`.\nBoth tools use the same \"C to Zig\" translation functionality. So when you use `@cImport()`,\nyou are essentially asking the `zig` compiler to translate the C header file into Zig code, then,\nto import this Zig code into your current Zig module.\n\nAt the present moment, there is an accepted proposal at the Zig project, to move `@cImport()`\nto the Zig build system[^cimport-issue]. If this proposal is completed, then, the \"use `@cImport()`\"\nstrategy would be transformed into \"call a translate C function in your Zig build script\".\nSo, the step of translating the C code into Zig code would be moved to\nthe build script of your Zig project, and you would only need to import the translated Zig code into\nyour Zig module to start calling C code from Zig.\n\n[^cimport-issue]: <https://github.com/ziglang/zig/issues/20630>\n\nIf you think about this proposal for a minute, you will understand that this is actually\na small change. I mean, the logic is the same, and the steps are still essentially the same.\nThe only difference is that one of the steps will be moved to the build script of your Zig project.\n\n\n\n### Linking Zig code with a C library {#sec-linking-c}\n\nRegardless of which of the two strategies from the previous section you choose,\nif you want to call C code from Zig, you must link your Zig code\nwith the C library that contains the C code that you want to call.\n\nIn other words, everytime you use some C code in your Zig code, **you introduce a dependency in your build process**.\nThis should come as no surprise to anyone that have any experience with C and C++.\nBecause this is no different in C. Everytime you use a C library in your C code, you also\nhave to build and link your C code with this C library that you are using.\n\nWhen we use a C library in our Zig code, the `zig` compiler needs to access the definition of the C functions that\nare being called in your Zig code. The C header file of this library provides the\ndeclarations of these C functions, but not their definitions. So, in order to access these definitions,\nthe `zig` compiler needs to build your Zig code and link it with the C library during the build process.\n\nAs we discussed across the @sec-build-system, there are different strategies to link something with a library.\nThis might involve building the C library first, and then, linking it with the Zig code. Or,\nit could also involve just the linking step, if this C library is already built and\ninstalled in your system. Anyway, if you have doubts about this, comeback to @sec-build-system.\n\n\n\n## Importing C header files {#sec-import-c-header}\n\nAt @sec-strategy-c, we have described that, currently, there are two different paths that\nyou can take to import a C header file into your Zig modules, `translate-c` or `@cImport()`.\nThis section describes each strategy separately in more details.\n\n### Strategy 1: using `translate-c`\n\nWhen we choose this strategy, we first need to use the `translate-c` tool to translate\nthe C header files that we want to use into Zig code. For example, suppose we wanted to\nuse the `fopen()` C function from the `stdio.h` C header file. We can translate the\n`stdio.h` C header file through the bash command below:\n\n```bash\nzig translate-c /usr/include/stdio.h \\\n    -lc -I/usr/include \\\n    -D_NO_CRT_STDIO_INLINE=1 > c.zig \\\n```\n\nNotice that, in this bash command, we are passing the necessary compiler flags (`-D` to define macros,\n`-l` to link libraries, `-I` to add an \"include path\") to compile and use the `stdio.h` header file.\nAlso notice that we are saving the results of the translation process inside a Zig module called `c.zig`.\n\nTherefore, after running this command, all we have to do is to import this `c.zig` module, and start\ncalling the C functions that you want to call from it. The example below demonstrates that.\nIs important to remember what we've discussed at @sec-linking-c. In order to compile this\nexample you have to link this code with `libc`, by passing the flag `-lc` to the `zig` compiler.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @import(\"c.zig\");\npub fn main() !void {\n    const x: f32 = 1772.94122;\n    _ = c.printf(\"%.3f\\n\", x);\n}\n```\n:::\n\n\n\n\n```\n1772.941\n```\n\n\n### Strategy 2: using `@cImport()`\n\nTo import a C header file into our Zig code, we can use the built-in functions `@cInclude()` and `@cImport()`.\nInside the `@cImport()` function, we open a block (with a pair of curly braces). Inside this block\nwe can (if we need to) include multiple `@cDefine()` calls to define C macros when including this specific C header file.\nBut for the most part, you will probably need to use just a single call inside this block,\nwhich is a call to `@cInclude()`.\n\nThis `@cInclude()` function is equivalent to the `#include` statement in C.\nYou provide the name of the C header that you want to include as input to this `@cInclude()` function,\nthen, in conjunction with `@cImport()`, it will perform the necessary steps\nto include this C header file into your Zig code.\n\nYou should bind the result of `@cImport()` to a constant object, pretty much like you would do with\n`@import()`. You just assign the result to a constant object in your\nZig code, and, as consequence, all C functions, C structs, C macros, etc. that are defined inside the\nC header files will be available through this constant object.\n\nLook at the code example below, where we are importing the Standard I/O C Library (`stdio.h`),\nand calling the `printf()`[^printf] C function. Notice that we have also used in this example the C function `powf()`[^powf],\nwhich comes from the C Math Library (`math.h`).\nIn order to compile this example, you have to link this Zig code with both\nthe C Standard Library and the C Math Library, by passing the flags `-lc` and `-lm`\nto the `zig` compiler.\n\n[^printf]: <https://cplusplus.com/reference/cstdio/printf/>\n[^powf]: <https://en.cppreference.com/w/c/numeric/math/pow>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n    @cInclude(\"math.h\");\n});\n\npub fn main() !void {\n    const x: f32 = 15.2;\n    const y = c.powf(x, @as(f32, 2.6));\n    _ = c.printf(\"%.3f\\n\", y);\n}\n```\n:::\n\n\n\n\n```\n1182.478\n```\n\n\n## About passing Zig values to C functions {#sec-zig-obj-to-c}\n\nZig objects have some intrinsic differences between their C equivalents.\nProbably the most noticeable one is the difference between C strings and Zig strings,\nwhich I described at @sec-zig-strings.\nZig strings are objects that contains both an array of arbitrary bytes and a length value.\nOn the other hand, a C string is usually just a pointer to a null-terminated array of arbitrary bytes.\n\nBecause of these intrinsic differences, in some specific cases, you cannot pass Zig objects directly\nas inputs to C functions before you convert them into C compatible values. However, in some other cases,\nyou are allowed to pass Zig objects and Zig literal values directly as inputs to C functions,\nand everything will work just fine, because the `zig` compiler will handle everything for you.\n\nSo we have two different scenarios being described here. Let's call them \"auto-conversion\" and \"need-conversion\".\nThe \"auto-conversion\" scenario is when the `zig` compiler handles everything for you, and automatically convert your\nZig objects/values into C compatible values. In contrast,\nthe \"need-conversion\" scenario is when you, the programmer, have the responsibility of converting\nthat Zig object into a C compatible value, before passing it to C code.\n\nThere is also a third scenario that is not being described here, which is when you create a C object, or, a C struct, or\na C compatible value in your Zig code, and you pass this C object/value as input to a C function in your Zig code.\nThis scenario will be described later at @sec-c-inputs. In this section, we are focused on the scenarios where\nwe are passing Zig objects/values to C code, instead of C objects/values being passed to C code.\n\n\n### The \"auto-conversion\" scenario\n\nAn \"auto-conversion\" scenario is when the `zig` compiler automatically converts our Zig objects into\nC compatible values for us. This specific scenario happens mostly in two instances:\n\n- with string literal values;\n- with any of the primitive data types that were introduced at @sec-primitive-data-types.\n\nWhen we think about the second instance described above, the `zig` compiler does automatically\nconvert any of the primitive data types into their C equivalents, because the compiler knows how\nto properly convert a `i16` into a `signed short`, or, a `u8` into a `unsigned char`, etc.\nNow, when we think about string literal values, they can be automatically\nconverted into C strings as well, especially because the `zig` compiler does not forces\na specific Zig data type into a string literal at first glance, unless you store this\nstring literal into a Zig object, and explicitly annotate the data type of this object.\n\nThus, with string literal values, the `zig` compiler have more freedom to infer which is the appropriate data type\nto be used in each situation. You could say that the string literal value \"inherits its data type\" depending on the context that\nit is used. Most of the times, this data type is going to be the type that we commonly associate with Zig strings (`[]const u8`).\nBut it might be a different type depending on the situation. When the `zig` compiler detects that you are providing\na string literal value as input to some C function, the compiler automatically interprets this string\nliteral as a C string value.\n\nAs an example, look at the code exposed below. Here we are using\nthe `fopen()` C function to simply open and close a file. If you do not know how this `fopen()`\nfunction works in C, it takes two C strings as input. But in this code example below, we are passing some\nstring literals written in our Zig code directly as inputs to this `fopen()` C function.\n\nIn other words, we are not doing any conversion from a Zig string to a C string.\nWe are just passing the Zig string literals directly as inputs to the C function. And it works just fine!\nBecause the compiler interprets the string `\"foo.txt\"` as a C string given the current context.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n});\n\npub fn main() !void {\n    const file = c.fopen(\"foo.txt\", \"rb\");\n    if (file == null) {\n        @panic(\"Could not open file!\");\n    }\n    if (c.fclose(file) != 0) {\n        return error.CouldNotCloseFileDescriptor;\n    }\n}\n```\n:::\n\n\n\n\nLet's make some experiments, by writing the same code in different manners, and we\nsee how this affects the program. As a starting point, let's store the `\"foo.txt\"` string inside\na Zig object, like the `path` object below, and then, we pass this Zig object as input to the `fopen()` C function.\n\nIf we do this, the program still compiles and runs successfully. Notice that I have omitted most of the code in this example below.\nThis is just for brevity reasons, because the remainder of the program is still the same.\nThe only difference between this example and the previous one is just these two lines exposed below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\n\nNow, what happens if you give an explicit data type to the `path` object? Well, if I force\nthe `zig` compiler to interpret this `path` object as a Zig string object,\nby annotating the `path` object with the data type `[]const u8`, then, I actually get a compile error\nas demonstrated below. We get this compile error because now I'm forcing the `zig` compiler\nto interpret `path` as a Zig string object.\n\nAccording to the error message, the `fopen()` C function was expecting to receive an\ninput value of type `[*c]const u8` (C string) instead of a value of type `[]const u8` (Zig string).\nIn more details, the type `[*c]const u8` is actually the Zig type representation of a C string.\nThe `[*c]` portion of this type identifies a C pointer. So, this Zig type essentially means: a C pointer to an array (`[*c]`) of\nconstant bytes (`const u8`).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\n\n```\nt.zig:2:7 error: expected type '[*c]const u8', found '[]const u8':\n    const file = c.fopen(path, \"rb\");\n                         ^~~~\n```\n\nTherefore, when we talk exclusively about string literal values, as long as you don't give an\nexplicit data type to these string literal values, the `zig` compiler should be capable of automatically\nconverting them into C strings as needed.\n\nBut what about using one of the primitive data types that were introduced at @sec-primitive-data-types?\nLet's take code exposed below as an example of that. Here, we are giving some float literal values as input\nto the C function `powf()`. Notice that this code example compiles and runs successfully.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst cmath = @cImport({\n    @cInclude(\"math.h\");\n});\n\npub fn main() !void {\n    const y = cmath.powf(15.68, 2.32);\n    try stdout.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n\n\n```\n593.2023\n```\n\nOnce again, because the `zig` compiler does not associate a specific data type with the literal values\n`15.68` and `2.32` at first glance, the compiler can automatically convert these values\ninto their C `float` (or `double`) equivalents, before it passes to the `powf()` C function.\nNow, even if I give an explicit Zig data type to these literal values, by storing them into a Zig object,\nand explicit annotating the type of these objects, the code still compiles and runs successfully.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const x: f32 = 15.68;\n    const y = cmath.powf(x, 2.32);\n    // The remainder of the program\n```\n:::\n\n\n\n\n```\n593.2023\n```\n\n\n\n### The \"need-conversion\" scenario\n\nA \"need-conversion\" scenario is when we need to manually convert our Zig objects into C compatible values\nbefore passing them as input to C functions. You will fall in this scenario, when passing Zig string objects\nto C functions.\n\nWe have already seen this specific circumstance in the last `fopen()` example,\nwhich is reproduced below. You can see in this example, that we have given an explicit Zig data type\n(`[]const u8`) to our `path` object, and, as a consequence of that, we have forced the `zig` compiler\nto see this `path` object, as a Zig string object. Therefore, we need now to manually convert\nthis `path` object into a C string before we pass it to `fopen()`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\n\n```\nt.zig:10:26: error: expected type '[*c]const u8', found '[]const u8'\n    const file = c.fopen(path, \"rb\");\n                         ^~~~\n```\n\n\nThere are different ways to convert a Zig string object into a C string.\nOne way to solve this problem is to provide the pointer to the underlying array\nof bytes, instead of providing the Zig object directly as input.\nYou can access this pointer by using the `ptr` property of the Zig string object.\n\nThe code example below demonstrates this strategy. Notice that, by giving the\npointer to the underlying array in `path` through the `ptr` property, we get no compile errors as result\nwhile using the `fopen()` C function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path.ptr, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\n\nThis strategy works because this pointer to the underlying array found in the `ptr` property,\nis semantically identical to a C pointer to an array of bytes, i.e. a C object of type `*unsigned char`.\nThis is why this option also solves the problem of converting the Zig string into a C string.\n\nAnother option is to explicitly convert the Zig string object into a C pointer by using the\nbuilt-in function `@ptrCast()`. With this function we can convert\nan object of type `[]const u8` into an object of type `[*c]const u8`.\nAs I described at the previous section, the `[*c]` portion of the type\nmeans that it is a C pointer. This strategy is not-recommended. But it is\nuseful to demonstrate the use of `@ptrCast()`.\n\nYou may recall of `@as()` and `@ptrCast()` from @sec-type-cast. Just as a recap,\nthe `@as()` built-in function is used to explicitly convert (or cast) a Zig value\nfrom a type \"x\" into a value of type \"y\". But in our case here, we are converting\na pointer object. Everytime a pointer is involved in some \"type casting operation\" in Zig,\nthe `@ptrCast()` function is involved.\n\nIn the example below, we are using this function to cast our `path` object\ninto a C pointer to an array of bytes. Then, we pass this C pointer as input\nto the `fopen()` function. Notice that this code example compiles successfully\nwith no errors.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path: []const u8 = \"foo.txt\";\n    const c_path: [*c]const u8 = @ptrCast(path);\n    const file = c.fopen(c_path, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\n\n\n\n## Creating C objects in Zig {#sec-c-inputs}\n\nCreating C objects, or, in other words, creating instances of C structs in your Zig code\nis actually something quite easy to do. You first need to import the C header file (like I described at @sec-import-c-header) that defines\nthe C struct that you are trying to instantiate in your Zig code. After that, you can just\ncreate a new object in your Zig code, and annotate it with the data type of the C struct.\n\nFor example, suppose we have a C header file called `user.h`, and that this header file is declaring a new struct named `User`.\nThis C header file is exposed below:\n\n```c\n#include <stdint.h>\n\ntypedef struct {\n    uint64_t id;\n    char* name;\n} User;\n```\n\nThis `User` C struct have two distinct fields, or two struct members, named `id` and `name`.\nThe field `id` is an unsigned 64-bit integer value, while the field `name` is just a standard C string.\nNow, suppose that I want to create an instance of this `User` struct in my Zig code.\nI can do that by importing this `user.h` header file into my Zig code, and creating\na new object with type `User`. These steps are reproduced in the code example below.\n\nNotice that I have used the keyword `undefined` in this example. This allows me to\ncreate the `new_user` object without the need to provide an initial value to the object.\nAs consequence, the underlying memory associated with this `new_user` object is uninitialized,\ni.e. the memory is currently populated with \"garbage\" values.\nThus, this expression have the exact same effect of the expression `User new_user;` in C,\nwhich means \"declare a new object named `new_user` of type `User`\".\n\nIs our responsibility to properly initialize this memory associated with this `new_user` object,\nby assigning valid values to the members (or the fields) of the C struct. In the example below,\nI'm assigning the integer 1 to the member `id`. I am also saving the string `\"pedropark99\"` into the member `name`.\nNotice in this example that I manually add the null character (zero byte) to the end of the allocated array\nfor this string. This null character marks the end of the array in C.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst c = @cImport({\n    @cInclude(\"user.h\");\n});\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n\n    var new_user: c.User = undefined;\n    new_user.id = 1;\n    var user_name = try allocator.alloc(u8, 12);\n    defer allocator.free(user_name);\n    @memcpy(user_name[0..(user_name.len - 1)], \"pedropark99\");\n    user_name[user_name.len - 1] = 0;\n    new_user.name = user_name.ptr;\n}\n```\n:::\n\n\n\n\nSo, in this example above, we are manually initializing each field of the C struct.\nWe could say that, in this instance, we are \"manually instantiating\nthe C struct object\". However, when we use C libraries in our Zig code, we rarely need\nto manually instantiate the C structs like that. Only because C libraries\nusually provide a \"constructor function\" in their public APIs. As consequence, we normally rely on\nthese constructor functions to properly initialize the C structs, and\nthe struct fields for us.\n\nFor example, consider the Harfbuzz C library. This a text shaping C library,\nand it works around a \"buffer object\", or, more specifically, an instance of\nthe C struct `hb_buffer_t`. Therefore, we need to create an instance of\nthis C struct if we want to use this C library. Luckily, this library offers\nthe function `hb_buffer_create()`, which we can use to create such object.\nSo the Zig code necessary to create such object would probably look something like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cInclude(\"hb.h\");\n});\nvar buf: c.hb_buffer_t = c.hb_buffer_create();\n// Do stuff with the \"buffer object\"\n```\n:::\n\n\n\n\nTherefore, we do not need to manually create an instance of the C struct\n`hb_buffer_t` here, and manually assign valid values to each field in this C struct.\nBecause the constructor function `hb_buffer_create()` is doing this heavy job for us.\n\nSince this `buf` object, and also, the `new_user` object from previous examples, are instances of C structs, these\nobjects are by themselves C compatible values. They are C objects defined in our Zig code. As consequence,\nyou can freely pass these objects as input to any C function that expects to receive this type\nof C struct as input. You do not need to use any special syntax, or, to convert them in\nany special manner to use them in C code. This is how we create and use C objects in our Zig code.\n\n\n\n## Passing C structs across Zig functions {#sec-pass-c-structs}\n\nNow that we have learned how to create/declare C objects in our Zig code, we\nneed to learn how to pass these C objects as inputs to Zig functions.\nAs I described at @sec-c-inputs, we can freely pass these C objects as inputs to C code\nthat we call from our Zig code. But what about passing these C objects to Zig functions?\n\nIn essence, this specific case requires one small adjustment in the Zig function declaration.\nAll you need to do, is to make sure that you pass your C object *by reference* to the function,\ninstead of passing it *by value*. To do that, you have to annotate the data type of the function argument\nthat is receiving this C object as \"a pointer to the C struct\", instead of annotating it as \"an instance of the C struct\".\n\nLet's consider the C struct `User` from the `user.h` C header file that we have used at @sec-c-inputs.\nNow, consider that we want to create a Zig function that sets the value of the `id` field\nin this C struct, like the `set_user_id()` function declared below.\nNotice that the `user` argument in this function is annotated as a pointer (`*`) to a `c.User` object.\n\nTherefore, all you have to do when passing C objects to Zig functions, is to add `*` to the\ndata type of the function argument that is receiving the C object. This will make sure that\nthe C object is passed *by reference* to the function.\n\nBecause we have transformed the function argument into a pointer,\neverytime that you have to access the value pointed by this input pointer inside the function body, for whatever reason (e.g. you want\nto read, update, or delete this value), you have to dereference the pointer with the `.*` syntax that we\nlearned from @sec-pointer. Notice that the `set_user_id()` function is using this syntax to alter\nthe value in the `id` field of the `User` struct pointed by the input pointer.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst c = @cImport({\n    @cInclude(\"user.h\");\n});\nfn set_user_id(id: u64, user: *c.User) void {\n    user.*.id = id;\n}\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n\n    var new_user: c.User = undefined;\n    new_user.id = 1;\n    var user_name = try allocator.alloc(u8, 12);\n    defer allocator.free(user_name);\n    @memcpy(user_name[0..(user_name.len - 1)], \"pedropark99\");\n    user_name[user_name.len - 1] = 0;\n    new_user.name = user_name.ptr;\n\n    set_user_id(25, &new_user);\n    try stdout.print(\"New ID: {any}\\n\", .{new_user.id});\n}\n```\n:::\n\n\n\n\n```\nNew ID: 25\n```\n\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Zig interoperability with C\n\nIn this chapter, we are going to discuss the interoperability of Zig with C.\nWe have discussed in @sec-building-c-code how you can use the `zig` compiler to build C code.\nBut we haven't discussed yet how to actually use C code in Zig. In other words,\nwe haven't discussed yet how to call and use C code from Zig.\n\nThis is the main subject of this chapter.\nAlso, in our next small project in this book, we are going to use a C library in it.\nAs consequence, we will put in practice a lot of the knowledge discussed here on\nthis next project.\n\n\n## How to call C code from Zig\n\nInteroperability with C is not something new. Most high-level programming languages have FFI (foreign function interfaces),\nwhich can be used to call C code. For example, Python have Cython, R have `.Call()`, Javascript have `ccall()`, etc.\nBut Zig integrates with C in a deeper level, which affects not only the way that C code gets called, but also,\nhow this C code is compiled and incorporated into your Zig project.\n\nIn summary, Zig have great interoperability with C. If you want to call any C code from Zig,\nyou have to perform the following steps:\n\n- import a C header file into your Zig code.\n- link your Zig code with the C library.\n\n\n### Strategies to import C header files {#sec-strategy-c}\n\nUsing C code in Zig always involves performing the two steps cited above. However, when\nwe talk specifically about the first step listed above, there are currently two\ndifferent ways to perform this first step, which are:\n\n- translating the C header file into Zig code, through the `zig translate-c` command, and then, import and use the translated Zig code.\n- importing the C header file directly into your Zig module through the `@cImport()` built-in function.\n\nIf you are not familiar with `translate-c`, this is a subcommand inside the `zig` compiler that takes C files\nas input, and outputs the Zig representation of the C code present in these C files.\nIn other words, this subcommand works like a transpiler. It takes C code, and translates it into\nthe equivalent Zig code.\n\nI think it would be ok to interpret `translate-c` as a tool to generate Zig bindings\nto C code, similarly to the `rust-bindgen`[^bindgen] tool, which generates Rust FFI bindings to C code.\nBut that would not be a precise interpretation of `translate-c`. The idea behind this tool is\nto really translate the C code into Zig code.\n\n[^bindgen]: <https://github.com/rust-lang/rust-bindgen>\n\nNow, on a surface level, `@cImport()` versus `translate-c` might seem like\ntwo completely different strategies. But in fact, they are effectively the exact same strategy.\nBecause, under the hood, the `@cImport()` built-in function is just a shortcut to `translate-c`.\nBoth tools use the same \"C to Zig\" translation functionality. So when you use `@cImport()`,\nyou are essentially asking the `zig` compiler to translate the C header file into Zig code, then,\nto import this Zig code into your current Zig module.\n\nAt the present moment, there is an accepted proposal at the Zig project, to move `@cImport()`\nto the Zig build system[^cimport-issue]. If this proposal is completed, then, the \"use `@cImport()`\"\nstrategy would be transformed into \"call a translate C function in your Zig build script\".\nSo, the step of translating the C code into Zig code would be moved to\nthe build script of your Zig project, and you would only need to import the translated Zig code into\nyour Zig module to start calling C code from Zig.\n\n[^cimport-issue]: <https://github.com/ziglang/zig/issues/20630>\n\nIf you think about this proposal for a minute, you will understand that this is actually\na small change. I mean, the logic is the same, and the steps are still essentially the same.\nThe only difference is that one of the steps will be moved to the build script of your Zig project.\n\n\n\n### Linking Zig code with a C library {#sec-linking-c}\n\nRegardless of which of the two strategies from the previous section you choose,\nif you want to call C code from Zig, you must link your Zig code\nwith the C library that contains the C code that you want to call.\n\nIn other words, everytime you use some C code in your Zig code, **you introduce a dependency in your build process**.\nThis should come as no surprise to anyone that have any experience with C and C++.\nBecause this is no different in C. Everytime you use a C library in your C code, you also\nhave to build and link your C code with this C library that you are using.\n\nWhen we use a C library in our Zig code, the `zig` compiler needs to access the definition of the C functions that\nare being called in your Zig code. The C header file of this library provides the\ndeclarations of these C functions, but not their definitions. So, in order to access these definitions,\nthe `zig` compiler needs to build your Zig code and link it with the C library during the build process.\n\nAs we discussed across the @sec-build-system, there are different strategies to link something with a library.\nThis might involve building the C library first, and then, linking it with the Zig code. Or,\nit could also involve just the linking step, if this C library is already built and\ninstalled in your system. Anyway, if you have doubts about this, comeback to @sec-build-system.\n\n\n\n## Importing C header files {#sec-import-c-header}\n\nIn @sec-strategy-c, we have described that, currently, there are two different paths that\nyou can take to import a C header file into your Zig modules, `translate-c` or `@cImport()`.\nThis section describes each strategy separately in more details.\n\n### Strategy 1: using `translate-c`\n\nWhen we choose this strategy, we first need to use the `translate-c` tool to translate\nthe C header files that we want to use into Zig code. For example, suppose we wanted to\nuse the `fopen()` C function from the `stdio.h` C header file. We can translate the\n`stdio.h` C header file through the bash command below:\n\n```bash\nzig translate-c /usr/include/stdio.h \\\n    -lc -I/usr/include \\\n    -D_NO_CRT_STDIO_INLINE=1 > c.zig \\\n```\n\nNotice that, in this bash command, we are passing the necessary compiler flags (`-D` to define macros,\n`-l` to link libraries, `-I` to add an \"include path\") to compile and use the `stdio.h` header file.\nAlso notice that we are saving the results of the translation process inside a Zig module called `c.zig`.\n\nTherefore, after running this command, all we have to do is to import this `c.zig` module, and start\ncalling the C functions that you want to call from it. The example below demonstrates that.\nIt's important to remember what we've discussed in @sec-linking-c. In order to compile this\nexample you have to link this code with `libc`, by passing the flag `-lc` to the `zig` compiler.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @import(\"c.zig\");\npub fn main() !void {\n    const x: f32 = 1772.94122;\n    _ = c.printf(\"%.3f\\n\", x);\n}\n```\n:::\n\n\n\n\n```\n1772.941\n```\n\n\n### Strategy 2: using `@cImport()`\n\nTo import a C header file into our Zig code, we can use the built-in functions `@cInclude()` and `@cImport()`.\nInside the `@cImport()` function, we open a block (with a pair of curly braces). Inside this block\nwe can (if we need to) include multiple `@cDefine()` calls to define C macros when including this specific C header file.\nBut for the most part, you will probably need to use just a single call inside this block,\nwhich is a call to `@cInclude()`.\n\nThis `@cInclude()` function is equivalent to the `#include` statement in C.\nYou provide the name of the C header that you want to include as input to this `@cInclude()` function,\nthen, in conjunction with `@cImport()`, it will perform the necessary steps\nto include this C header file into your Zig code.\n\nYou should bind the result of `@cImport()` to a constant object, pretty much like you would do with\n`@import()`. You just assign the result to a constant object in your\nZig code, and, as consequence, all C functions, C structs, C macros, etc. that are defined inside the\nC header files will be available through this constant object.\n\nLook at the code example below, where we are importing the Standard I/O C Library (`stdio.h`),\nand calling the `printf()`[^printf] C function. Notice that we have also used in this example the C function `powf()`[^powf],\nwhich comes from the C Math Library (`math.h`).\nIn order to compile this example, you have to link this Zig code with both\nthe C Standard Library and the C Math Library, by passing the flags `-lc` and `-lm`\nto the `zig` compiler.\n\n[^printf]: <https://cplusplus.com/reference/cstdio/printf/>\n[^powf]: <https://en.cppreference.com/w/c/numeric/math/pow>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n    @cInclude(\"math.h\");\n});\n\npub fn main() !void {\n    const x: f32 = 15.2;\n    const y = c.powf(x, @as(f32, 2.6));\n    _ = c.printf(\"%.3f\\n\", y);\n}\n```\n:::\n\n\n\n\n```\n1182.478\n```\n\n\n## About passing Zig values to C functions {#sec-zig-obj-to-c}\n\nZig objects have some intrinsic differences between their C equivalents.\nProbably the most noticeable one is the difference between C strings and Zig strings,\nwhich I described in @sec-zig-strings.\nZig strings are objects that contains both an array of arbitrary bytes and a length value.\nOn the other hand, a C string is usually just a pointer to a null-terminated array of arbitrary bytes.\n\nBecause of these intrinsic differences, in some specific cases, you cannot pass Zig objects directly\nas inputs to C functions before you convert them into C compatible values. However, in some other cases,\nyou are allowed to pass Zig objects and Zig literal values directly as inputs to C functions,\nand everything will work just fine, because the `zig` compiler will handle everything for you.\n\nSo we have two different scenarios being described here. Let's call them \"auto-conversion\" and \"need-conversion\".\nThe \"auto-conversion\" scenario is when the `zig` compiler handles everything for you, and automatically convert your\nZig objects/values into C compatible values. In contrast,\nthe \"need-conversion\" scenario is when you, the programmer, have the responsibility of converting\nthat Zig object into a C compatible value, before passing it to C code.\n\nThere is also a third scenario that is not being described here, which is when you create a C object, or, a C struct, or\na C compatible value in your Zig code, and you pass this C object/value as input to a C function in your Zig code.\nThis scenario will be described later in @sec-c-inputs. In this section, we are focused on the scenarios where\nwe are passing Zig objects/values to C code, instead of C objects/values being passed to C code.\n\n\n### The \"auto-conversion\" scenario\n\nAn \"auto-conversion\" scenario is when the `zig` compiler automatically converts our Zig objects into\nC compatible values for us. This specific scenario happens mostly in two instances:\n\n- with string literal values;\n- with any of the primitive data types that were introduced in @sec-primitive-data-types.\n\nWhen we think about the second instance described above, the `zig` compiler does automatically\nconvert any of the primitive data types into their C equivalents, because the compiler knows how\nto properly convert a `i16` into a `signed short`, or, a `u8` into a `unsigned char`, etc.\nNow, when we think about string literal values, they can be automatically\nconverted into C strings as well, especially because the `zig` compiler does not forces\na specific Zig data type into a string literal at first glance, unless you store this\nstring literal into a Zig object, and explicitly annotate the data type of this object.\n\nThus, with string literal values, the `zig` compiler has more freedom to infer which is the appropriate data type\nto be used in each situation. You could say that the string literal value \"inherits its data type\" depending on the context that\nit's used in. Most of the times, this data type is going to be the type that we commonly associate with Zig strings (`[]const u8`).\nBut it might be a different type depending on the situation. When the `zig` compiler detects that you are providing\na string literal value as input to some C function, the compiler automatically interprets this string\nliteral as a C string value.\n\nAs an example, look at the code exposed below. Here we are using\nthe `fopen()` C function to simply open and close a file. If you do not know how this `fopen()`\nfunction works in C, it takes two C strings as input. But in this code example below, we are passing some\nstring literals written in our Zig code directly as inputs to this `fopen()` C function.\n\nIn other words, we are not doing any conversion from a Zig string to a C string.\nWe are just passing the Zig string literals directly as inputs to the C function. And it works just fine!\nBecause the compiler interprets the string `\"foo.txt\"` as a C string given the current context.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n});\n\npub fn main() !void {\n    const file = c.fopen(\"foo.txt\", \"rb\");\n    if (file == null) {\n        @panic(\"Could not open file!\");\n    }\n    if (c.fclose(file) != 0) {\n        return error.CouldNotCloseFileDescriptor;\n    }\n}\n```\n:::\n\n\n\n\nLet's make some experiments, by writing the same code in different manners, and we\nsee how this affects the program. As a starting point, let's store the `\"foo.txt\"` string inside\na Zig object, like the `path` object below, and then, we pass this Zig object as input to the `fopen()` C function.\n\nIf we do this, the program still compiles and runs successfully. Notice that I have omitted most of the code in this example below.\nThis is just for brevity reasons, because the remainder of the program is still the same.\nThe only difference between this example and the previous one is just these two lines exposed below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\n\nNow, what happens if you give an explicit data type to the `path` object? Well, if I force\nthe `zig` compiler to interpret this `path` object as a Zig string object,\nby annotating the `path` object with the data type `[]const u8`, then, I actually get a compile error\nas demonstrated below. We get this compile error because now I'm forcing the `zig` compiler\nto interpret `path` as a Zig string object.\n\nAccording to the error message, the `fopen()` C function was expecting to receive an\ninput value of type `[*c]const u8` (C string) instead of a value of type `[]const u8` (Zig string).\nIn more details, the type `[*c]const u8` is actually the Zig type representation of a C string.\nThe `[*c]` portion of this type identifies a C pointer. So, this Zig type essentially means: a C pointer to an array (`[*c]`) of\nconstant bytes (`const u8`).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\n\n```\nt.zig:2:7 error: expected type '[*c]const u8', found '[]const u8':\n    const file = c.fopen(path, \"rb\");\n                         ^~~~\n```\n\nTherefore, when we talk exclusively about string literal values, as long as you don't give an\nexplicit data type to these string literal values, the `zig` compiler should be capable of automatically\nconverting them into C strings as needed.\n\nBut what about using one of the primitive data types that were introduced in @sec-primitive-data-types?\nLet's take code exposed below as an example of that. Here, we are giving some float literal values as input\nto the C function `powf()`. Notice that this code example compiles and runs successfully.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst cmath = @cImport({\n    @cInclude(\"math.h\");\n});\n\npub fn main() !void {\n    const y = cmath.powf(15.68, 2.32);\n    try stdout.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n\n\n```\n593.2023\n```\n\nOnce again, because the `zig` compiler does not associate a specific data type with the literal values\n`15.68` and `2.32` at first glance, the compiler can automatically convert these values\ninto their C `float` (or `double`) equivalents, before it passes to the `powf()` C function.\nNow, even if I give an explicit Zig data type to these literal values, by storing them into a Zig object,\nand explicit annotating the type of these objects, the code still compiles and runs successfully.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const x: f32 = 15.68;\n    const y = cmath.powf(x, 2.32);\n    // The remainder of the program\n```\n:::\n\n\n\n\n```\n593.2023\n```\n\n\n\n### The \"need-conversion\" scenario\n\nA \"need-conversion\" scenario is when we need to manually convert our Zig objects into C compatible values\nbefore passing them as input to C functions. You will fall in this scenario, when passing Zig string objects\nto C functions.\n\nWe have already seen this specific circumstance in the last `fopen()` example,\nwhich is reproduced below. You can see in this example, that we have given an explicit Zig data type\n(`[]const u8`) to our `path` object, and, as a consequence of that, we have forced the `zig` compiler\nto see this `path` object, as a Zig string object. Therefore, we need now to manually convert\nthis `path` object into a C string before we pass it to `fopen()`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\n\n```\nt.zig:10:26: error: expected type '[*c]const u8', found '[]const u8'\n    const file = c.fopen(path, \"rb\");\n                         ^~~~\n```\n\n\nThere are different ways to convert a Zig string object into a C string.\nOne way to solve this problem is to provide the pointer to the underlying array\nof bytes, instead of providing the Zig object directly as input.\nYou can access this pointer by using the `ptr` property of the Zig string object.\n\nThe code example below demonstrates this strategy. Notice that, by giving the\npointer to the underlying array in `path` through the `ptr` property, we get no compile errors as result\nwhile using the `fopen()` C function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path.ptr, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\n\nThis strategy works because this pointer to the underlying array found in the `ptr` property,\nis semantically identical to a C pointer to an array of bytes, i.e., a C object of type `*unsigned char`.\nThis is why this option also solves the problem of converting the Zig string into a C string.\n\nAnother option is to explicitly convert the Zig string object into a C pointer by using the\nbuilt-in function `@ptrCast()`. With this function we can convert\nan object of type `[]const u8` into an object of type `[*c]const u8`.\nAs I described at the previous section, the `[*c]` portion of the type\nmeans that it's a C pointer. This strategy is not-recommended. But it's\nuseful to demonstrate the use of `@ptrCast()`.\n\nYou may recall of `@as()` and `@ptrCast()` from @sec-type-cast. Just as a recap,\nthe `@as()` built-in function is used to explicitly convert (or cast) a Zig value\nfrom a type \"x\" into a value of type \"y\". But in our case here, we are converting\na pointer object. Everytime a pointer is involved in some \"type casting operation\" in Zig,\nthe `@ptrCast()` function is involved.\n\nIn the example below, we are using this function to cast our `path` object\ninto a C pointer to an array of bytes. Then, we pass this C pointer as input\nto the `fopen()` function. Notice that this code example compiles successfully\nwith no errors.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path: []const u8 = \"foo.txt\";\n    const c_path: [*c]const u8 = @ptrCast(path);\n    const file = c.fopen(c_path, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\n\n\n\n## Creating C objects in Zig {#sec-c-inputs}\n\nCreating C objects, or, in other words, creating instances of C structs in your Zig code\nis actually something quite easy to do. You first need to import the C header file (like I described in @sec-import-c-header) that defines\nthe C struct that you are trying to instantiate in your Zig code. After that, you can just\ncreate a new object in your Zig code, and annotate it with the data type of the C struct.\n\nFor example, suppose we have a C header file called `user.h`, and that this header file is declaring a new struct named `User`.\nThis C header file is exposed below:\n\n```c\n#include <stdint.h>\n\ntypedef struct {\n    uint64_t id;\n    char* name;\n} User;\n```\n\nThis `User` C struct have two distinct fields, or two struct members, named `id` and `name`.\nThe field `id` is an unsigned 64-bit integer value, while the field `name` is just a standard C string.\nNow, suppose that I want to create an instance of this `User` struct in my Zig code.\nI can do that by importing this `user.h` header file into my Zig code, and creating\na new object with type `User`. These steps are reproduced in the code example below.\n\nNotice that I have used the keyword `undefined` in this example. This allows me to\ncreate the `new_user` object without the need to provide an initial value to the object.\nAs consequence, the underlying memory associated with this `new_user` object is uninitialized,\ni.e., the memory is currently populated with \"garbage\" values.\nThus, this expression have the exact same effect of the expression `User new_user;` in C,\nwhich means \"declare a new object named `new_user` of type `User`\".\n\nIt's our responsibility to properly initialize this memory associated with this `new_user` object,\nby assigning valid values to the members (or the fields) of the C struct. In the example below,\nI'm assigning the integer 1 to the member `id`. I am also saving the string `\"pedropark99\"` into the member `name`.\nNotice in this example that I manually add the null character (zero byte) to the end of the allocated array\nfor this string. This null character marks the end of the array in C.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst c = @cImport({\n    @cInclude(\"user.h\");\n});\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n\n    var new_user: c.User = undefined;\n    new_user.id = 1;\n    var user_name = try allocator.alloc(u8, 12);\n    defer allocator.free(user_name);\n    @memcpy(user_name[0..(user_name.len - 1)], \"pedropark99\");\n    user_name[user_name.len - 1] = 0;\n    new_user.name = user_name.ptr;\n}\n```\n:::\n\n\n\n\nSo, in this example above, we are manually initializing each field of the C struct.\nWe could say that, in this instance, we are \"manually instantiating\nthe C struct object\". However, when we use C libraries in our Zig code, we rarely need\nto manually instantiate the C structs like that. Only because C libraries\nusually provide a \"constructor function\" in their public APIs. As consequence, we normally rely on\nthese constructor functions to properly initialize the C structs, and\nthe struct fields for us.\n\nFor example, consider the Harfbuzz C library. This a text shaping C library,\nand it works around a \"buffer object\", or, more specifically, an instance of\nthe C struct `hb_buffer_t`. Therefore, we need to create an instance of\nthis C struct if we want to use this C library. Luckily, this library offers\nthe function `hb_buffer_create()`, which we can use to create such object.\nSo the Zig code necessary to create such object would probably look something like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cInclude(\"hb.h\");\n});\nvar buf: c.hb_buffer_t = c.hb_buffer_create();\n// Do stuff with the \"buffer object\"\n```\n:::\n\n\n\n\nTherefore, we do not need to manually create an instance of the C struct\n`hb_buffer_t` here, and manually assign valid values to each field in this C struct.\nBecause the constructor function `hb_buffer_create()` is doing this heavy job for us.\n\nSince this `buf` object, and also, the `new_user` object from previous examples, are instances of C structs, these\nobjects are by themselves C compatible values. They are C objects defined in our Zig code. As consequence,\nyou can freely pass these objects as input to any C function that expects to receive this type\nof C struct as input. You do not need to use any special syntax, or, to convert them in\nany special manner to use them in C code. This is how we create and use C objects in our Zig code.\n\n\n\n## Passing C structs across Zig functions {#sec-pass-c-structs}\n\nNow that we have learned how to create/declare C objects in our Zig code, we\nneed to learn how to pass these C objects as inputs to Zig functions.\nAs I described in @sec-c-inputs, we can freely pass these C objects as inputs to C code\nthat we call from our Zig code. But what about passing these C objects to Zig functions?\n\nIn essence, this specific case requires one small adjustment in the Zig function declaration.\nAll you need to do, is to make sure that you pass your C object *by reference* to the function,\ninstead of passing it *by value*. To do that, you have to annotate the data type of the function argument\nthat is receiving this C object as \"a pointer to the C struct\", instead of annotating it as \"an instance of the C struct\".\n\nLet's consider the C struct `User` from the `user.h` C header file that we have used in @sec-c-inputs.\nNow, consider that we want to create a Zig function that sets the value of the `id` field\nin this C struct, like the `set_user_id()` function declared below.\nNotice that the `user` argument in this function is annotated as a pointer (`*`) to a `c.User` object.\n\nTherefore, all you have to do when passing C objects to Zig functions, is to add `*` to the\ndata type of the function argument that is receiving the C object. This will make sure that\nthe C object is passed *by reference* to the function.\n\nBecause we have transformed the function argument into a pointer,\neverytime that you have to access the value pointed by this input pointer inside the function body, for whatever reason (e.g. you want\nto read, update, or delete this value), you have to dereference the pointer with the `.*` syntax that we\nlearned from @sec-pointer. Notice that the `set_user_id()` function is using this syntax to alter\nthe value in the `id` field of the `User` struct pointed by the input pointer.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst c = @cImport({\n    @cInclude(\"user.h\");\n});\nfn set_user_id(id: u64, user: *c.User) void {\n    user.*.id = id;\n}\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n\n    var new_user: c.User = undefined;\n    new_user.id = 1;\n    var user_name = try allocator.alloc(u8, 12);\n    defer allocator.free(user_name);\n    @memcpy(user_name[0..(user_name.len - 1)], \"pedropark99\");\n    user_name[user_name.len - 1] = 0;\n    new_user.name = user_name.ptr;\n\n    set_user_id(25, &new_user);\n    try stdout.print(\"New ID: {any}\\n\", .{new_user.id});\n}\n```\n:::\n\n\n\n\n```\nNew ID: 25\n```\n",
+    "supporting": [
+      "14-zig-c-interop_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/15-vectors/execute-results/html.json b/_freeze/Chapters/15-vectors/execute-results/html.json
index 3b0c6a8d..d68d2db0 100644
--- a/_freeze/Chapters/15-vectors/execute-results/html.json
+++ b/_freeze/Chapters/15-vectors/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "79d14ec3c3354d3a9fca4cbd05f42110",
+  "hash": "3da767c3f773d387d2d0a42df4405278",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Introducing Vectors and SIMD {#sec-vectors-simd}\n\nIn this chapter, I want to discuss vectors in Zig, which are\nrelated to SIMD operations (i.e. they have no relationship with the `std::vector` class\nfrom C++).\n\n## What is SIMD?\n\nSIMD (*Single Instruction/Multiple Data*) is a group of operations that are widely used\non video/audio editing programs, and also in graphics applications. SIMD is not a new technology,\nbut the massive use of SIMD on normal desktop computers is somewhat recent. In the old days, SIMD\nwas only used on \"supercomputer models\".\n\nMost modern CPU models (from AMD, Intel, etc.) these days (either in a desktop or in a\nnotebook model) have support for SIMD operations. So, if you have a very old CPU model installed in your\ncomputer, then, is possible that you have no support for SIMD operations in your computer.\n\nWhy people have started using SIMD on their software? The answer is performance.\nBut what SIMD precisely do to achieve better performance? Well, in essence, SIMD operations are a different\nstrategy to get parallel computing in your program, and therefore, make faster calculations.\n\nThe basic idea behind SIMD is to have a single instruction that operates over multiple data\nat the same time. When you perform a normal scalar operation, like for example, four add instructions,\neach addition is performed separately, one after another. But with SIMD, these four add instructions\nare translated into a single instruction, and, as consequence, the four additions are performed\nin parallel, at the same time.\n\nCurrently, the `zig` compiler allows you to apply the following group of operators on vector objects.\nWhen you apply one of these operators on vector objects, SIMD is used to make the calculations, and,\ntherefore, these operators are applied element-wise and in parallel by default.\n\n- Arithmetic (`+`, `-`, `/`, `*`, `@divFloor()`, `@sqrt()`,  `@ceil()`, `@log()`, etc.).\n- Bitwise operators (`>>`, `<<`, `&`, `|`, `~`, etc.).\n- Comparison operators (`<`, `>`, `==`, etc.).\n\n\n## Vectors {#sec-what-vectors}\n\nA SIMD operation is usually performed through a *SIMD intrinsic*, which is just a fancy\nname for a function that performs a SIMD operation. These SIMD intrinsics (or \"SIMD functions\")\nalways operate over a special type of object, which are called \"vectors\". So,\nin order to use SIMD, you have to create a \"vector object\".\n\nA vector object is usually a fixed-sized block of 128 bits (16 bytes).\nAs consequence, most vectors that you find in the wild are essentially arrays that contains 2 values of 8 bytes each,\nor, 4 values of 4 bytes each, or, 8 values of 2 bytes each, etc.\nHowever, different CPU models may have different extensions (or, \"implementations\") of SIMD,\nwhich may offer more types of vector objects that are bigger in size (256 bits or 512 bits)\nto accomodate more data into a single vector object.\n\nYou can create a new vector object in Zig by using the `@Vector()` built-in function. Inside this function,\nyou specify the vector length (number of elements in the vector), and the data type of the elements\nof the vector. Only primitive data types are supported in these vector objects.\nIn the example below, I'm creating two vector objects (`v1` and `v2`) of 4 elements of type `u32` each.\n\nAlso notice in the example below, that a third vector object (`v3`) is created from the\nsum of the previous two vector objects (`v1` plus `v2`). Therefore,\nmath operations over vector objects take place element-wise by default, because\nthe same operation (in this case, addition) is transformed into a single instruction\nthat is replicated in parallel, across all elements of the vectors.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1 = @Vector(4, u32){4, 12, 37, 9};\nconst v2 = @Vector(4, u32){10, 22, 5, 12};\nconst v3 = v1 + v2;\ntry stdout.print(\"{any}\\n\", .{v3});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 14, 34, 42, 21 }\n```\n\n\n:::\n:::\n\n\n\n\nThis is how SIMD introduces more performance in your program. Instead of using a for loop\nto iterate through the elements of `v1` and `v2`, and adding them together, one element at a time,\nwe enjoy the benefits of SIMD, which performs all 4 additions in parallel, at the same time.\n\nTherefore, the `@Vector` structure is essentially the Zig representation of SIMD vector objects.\nThe elements on these vector objects will be operated in parallel, if, and only if your current CPU model\nsupports SIMD operations. If your CPU model does not have support for SIMD, then, the `@Vector` structure will\nlikely produce a similar performance from a \"for loop solution\".\n\n\n### Transforming arrays into vectors\n\nThere are different ways to transform a normal array into a vector object.\nYou can either use implicit conversion (which is when you assign the array to\na vector object directly), or, use slices to create a vector object from a normal array.\n\nIn the example below, we are implicitly converting the array `a1` into a vector object (`v1`)\nof length 4. We first explicitly annotate the data type of the vector object,\nand then, we assign the array object to this vector object.\n\nAlso notice in the example below, that a second vector object (`v2`) is also created\nby taking a slice of the array object (`a1`), and then, storing the pointer to this\nslice (`.*`) into this vector object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a1 = [4]u32{4, 12, 37, 9};\nconst v1: @Vector(4, u32) = a1;\nconst v2: @Vector(2, u32) = a1[1..3].*;\n_ = v1; _ = v2;\n```\n:::\n\n\n\n\n\nIs worth emphasizing that only arrays and slices whose sizes\nare compile-time known can be transformed into vectors. Vectors in general\nare structures that work only with compile-time known sizes. Therefore, if\nyou have an array whose size is runtime known, then, you first need to\ncopy it into an array with a compile-time known size, before transforming it into a vector.\n\n\n\n### The `@splat()` function\n\nYou can use the `@splat()` built-in function to create a vector object that is filled\nwith the same value across all of its elements. This function was created to offer a quick\nand easy way to directly convert a scalar value (a.k.a. a single value, like a single character, or a single integer, etc.)\ninto a vector object.\n\nThus, we can use `@splat()` to convert a single value, like the integer `16` into a vector object\nof length 1. But we can also use this function to convert the same integer `16` into a\nvector object of length 10, that is filled with 10 `16` values. The example below demonstrates\nthis idea.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1: @Vector(10, u32) = @splat(16);\ntry stdout.print(\"{any}\\n\", .{v1});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 16, 16, 16, 16, 16, 16, 16, 16, 16, 16 }\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Careful with vectors that are too big\n\nAs I described at @sec-what-vectors, each vector object is usually a small block of 128, 256 or 512 bits.\nThis means that a vector object is usually small in size, and when you try to go in the opposite direction,\nby creating a vector object that is very big in size (i.e. sizes that are close to $2^{20}$),\nyou usually end up with crashes and loud errors from the compiler.\n\nFor example, if you try to compile the program below, you will likely face segmentation faults, or, LLVM errors during\nthe build process. Just be careful to not create vector objects that are too big in size.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1: @Vector(1000000, u32) = @splat(16);\n_ = v1;\n```\n:::\n\n\n\n\n```\nSegmentation fault (core dumped)\n```\n\n\n\n\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Introducing Vectors and SIMD {#sec-vectors-simd}\n\nIn this chapter, I want to discuss vectors in Zig, which are\nrelated to SIMD operations (i.e., they have no relationship with the `std::vector` class\nfrom C++).\n\n## What is SIMD?\n\nSIMD (*Single Instruction/Multiple Data*) is a group of operations that are widely used\non video/audio editing programs, and also in graphics applications. SIMD is not a new technology,\nbut the massive use of SIMD on normal desktop computers is somewhat recent. In the old days, SIMD\nwas only used on \"supercomputer models\".\n\nMost modern CPU models (from AMD, Intel, etc.) these days (either in a desktop or in a\nnotebook model) have support for SIMD operations. So, if you have a very old CPU model installed in your\ncomputer, then, it's possible that you have no support for SIMD operations in your computer.\n\nWhy have people started using SIMD in their software? The answer is performance.\nBut what does SIMD precisely do to achieve better performance? Well, in essence, SIMD operations are a different\nstrategy to get parallel computing in your program, and therefore, make faster calculations.\n\nThe basic idea behind SIMD is to have a single instruction that operates over multiple data\nat the same time. When you perform a normal scalar operation, like for example, four add instructions,\neach addition is performed separately, one after another. But with SIMD, these four add instructions\nare translated into a single instruction, and, as consequence, the four additions are performed\nin parallel, at the same time.\n\nCurrently, the `zig` compiler allows you to apply the following group of operators on vector objects.\nWhen you apply one of these operators on vector objects, SIMD is used to make the calculations, and,\ntherefore, these operators are applied element-wise and in parallel by default.\n\n- Arithmetic (`+`, `-`, `/`, `*`, `@divFloor()`, `@sqrt()`,  `@ceil()`, `@log()`, etc.).\n- Bitwise operators (`>>`, `<<`, `&`, `|`, `~`, etc.).\n- Comparison operators (`<`, `>`, `==`, etc.).\n\n\n## Vectors {#sec-what-vectors}\n\nA SIMD operation is usually performed through a *SIMD intrinsic*, which is just a fancy\nname for a function that performs a SIMD operation. These SIMD intrinsics (or \"SIMD functions\")\nalways operate over a special type of object, which are called \"vectors\". So,\nin order to use SIMD, you have to create a \"vector object\".\n\nA vector object is usually a fixed-sized block of 128 bits (16 bytes).\nAs a consequence, most vectors that you find in the wild are essentially arrays that contains 2 values of 8 bytes each,\nor, 4 values of 4 bytes each, or, 8 values of 2 bytes each, etc.\nHowever, different CPU models may have different extensions (or, \"implementations\") of SIMD,\nwhich may offer more types of vector objects that are bigger in size (256 bits or 512 bits)\nto accomodate more data into a single vector object.\n\nYou can create a new vector object in Zig by using the `@Vector()` built-in function. Inside this function,\nyou specify the vector length (number of elements in the vector), and the data type of the elements\nof the vector. Only primitive data types are supported in these vector objects.\nIn the example below, I'm creating two vector objects (`v1` and `v2`) of 4 elements of type `u32` each.\n\nAlso notice in the example below, that a third vector object (`v3`) is created from the\nsum of the previous two vector objects (`v1` plus `v2`). Therefore,\nmath operations over vector objects take place element-wise by default, because\nthe same operation (in this case, addition) is transformed into a single instruction\nthat is replicated in parallel, across all elements of the vectors.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1 = @Vector(4, u32){4, 12, 37, 9};\nconst v2 = @Vector(4, u32){10, 22, 5, 12};\nconst v3 = v1 + v2;\ntry stdout.print(\"{any}\\n\", .{v3});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 14, 34, 42, 21 }\n```\n\n\n:::\n:::\n\n\n\n\nThis is how SIMD introduces more performance in your program. Instead of using a for loop\nto iterate through the elements of `v1` and `v2`, and adding them together, one element at a time,\nwe enjoy the benefits of SIMD, which performs all 4 additions in parallel, at the same time.\n\nTherefore, the `@Vector` structure is essentially the Zig representation of SIMD vector objects.\nThe elements in these vector objects will be operated in parallel, if, and only if your current CPU model\nsupports SIMD operations. If your CPU model does not have support for SIMD, then, the `@Vector` structure will\nlikely produce a similar performance from a \"for loop solution\".\n\n\n### Transforming arrays into vectors\n\nThere are different ways to transform a normal array into a vector object.\nYou can either use implicit conversion (which is when you assign the array to\na vector object directly), or, use slices to create a vector object from a normal array.\n\nIn the example below, we are implicitly converting the array `a1` into a vector object (`v1`)\nof length 4. We first explicitly annotate the data type of the vector object,\nand then, we assign the array object to this vector object.\n\nAlso notice in the example below, that a second vector object (`v2`) is also created\nby taking a slice of the array object (`a1`), and then, storing the pointer to this\nslice (`.*`) into this vector object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a1 = [4]u32{4, 12, 37, 9};\nconst v1: @Vector(4, u32) = a1;\nconst v2: @Vector(2, u32) = a1[1..3].*;\n_ = v1; _ = v2;\n```\n:::\n\n\n\n\n\nIt's worth emphasizing that only arrays and slices whose sizes\nare compile-time known can be transformed into vectors. Vectors in general\nare structures that work only with compile-time known sizes. Therefore, if\nyou have an array whose size is runtime known, then, you first need to\ncopy it into an array with a compile-time known size, before transforming it into a vector.\n\n\n\n### The `@splat()` function\n\nYou can use the `@splat()` built-in function to create a vector object that is filled\nwith the same value across all of its elements. This function was created to offer a quick\nand easy way to directly convert a scalar value (a.k.a. a single value, like a single character, or a single integer, etc.)\ninto a vector object.\n\nThus, we can use `@splat()` to convert a single value, like the integer `16` into a vector object\nof length 1. But we can also use this function to convert the same integer `16` into a\nvector object of length 10, that is filled with 10 `16` values. The example below demonstrates\nthis idea.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1: @Vector(10, u32) = @splat(16);\ntry stdout.print(\"{any}\\n\", .{v1});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 16, 16, 16, 16, 16, 16, 16, 16, 16, 16 }\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Careful with vectors that are too big\n\nAs I described in @sec-what-vectors, each vector object is usually a small block of 128, 256 or 512 bits.\nThis means that a vector object is usually small in size, and when you try to go in the opposite direction,\nby creating a vector object that is very big in size (i.e., sizes that are close to $2^{20}$),\nyou usually end up with crashes and loud errors from the compiler.\n\nFor example, if you try to compile the program below, you will likely face segmentation faults, or LLVM errors during\nthe build process. Just be careful to not create vector objects that are too big in size.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1: @Vector(1000000, u32) = @splat(16);\n_ = v1;\n```\n:::\n\n\n\n\n```\nSegmentation fault (core dumped)\n```\n",
+    "supporting": [
+      "15-vectors_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/index/execute-results/html.json b/_freeze/index/execute-results/html.json
index df53cb9c..9f591c93 100644
--- a/_freeze/index/execute-results/html.json
+++ b/_freeze/index/execute-results/html.json
@@ -1,8 +1,8 @@
 {
-  "hash": "b59fabe5a5ffda4f02945f654dba67de",
+  "hash": "335ac568e17c5057352e05da9521e5ae",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy a PDF, eBook or a physical copy\nof the book, either at Amazon, or at Leanpub:\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://leanpub.com/introductiontozigaproject-basedbook\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Leanpub!\n    </button>\n</a>\n\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e. it is open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.\nCurrently, he is a Data Platform Engineer at [Blip](https://www.blip.ai/en/)[^blip], and\na Databricks Certified Associate Developer for Apache Spark 3.0.\n\n[^blip]: <https://www.blip.ai/en/>\n\n\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nBrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer who loves to learn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2025 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n\n\n- System version: Linux, 6.8.0-52-generic, NA, x86_64.\n- Zig version: 0.14.0-dev.3046+08d661fcf.\n- Quarto version: 1.5.57.\n\n\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang), Tommaso Ricci (\\@Zorgatone), Primo Sabatini (\\@primos63), Santiago Fernandez (\\@santif), Hamza Wahed (\\@HamzaWahed), mwilbur (\\@mwilbur), Dima Budaragin (\\@dbud), Jorge Jímenez (\\@jorge-j1m), Alexander (\\@alexwheezy), Maarten Coopens (\\@maarteNNNN), Niklas Johansson (\\@Raphexion)\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy a PDF, eBook or a physical copy\nof the book, either at Amazon, or at Leanpub:\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://leanpub.com/introductiontozigaproject-basedbook\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Leanpub!\n    </button>\n</a>\n\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e., open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.\nCurrently, he is a Data Platform Engineer at [Blip](https://www.blip.ai/en/)[^blip], and\na Databricks Certified Associate Developer for Apache Spark 3.0.\n\n[^blip]: <https://www.blip.ai/en/>\n\n\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nBrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer who loves to learn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2025 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n\n\n- System version: Linux, 6.8.0-52-generic, NA, x86_64.\n- Zig version: 0.14.0-dev.3046+08d661fcf.\n- Quarto version: 1.5.57.\n\n\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang), Tommaso Ricci (\\@Zorgatone), Primo Sabatini (\\@primos63), Santiago Fernandez (\\@santif), Hamza Wahed (\\@HamzaWahed), mwilbur (\\@mwilbur), Dima Budaragin (\\@dbud), Jorge Jímenez (\\@jorge-j1m), Alexander (\\@alexwheezy), Maarten Coopens (\\@maarteNNNN), Niklas Johansson (\\@Raphexion), glystik (\\@glystik), Michael Lynch (\\@mtlynch)\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
diff --git a/contributors.txt b/contributors.txt
index d3b64d0c..8a789f25 100644
--- a/contributors.txt
+++ b/contributors.txt
@@ -22,3 +22,5 @@ Jorge Jímenez,@jorge-j1m
 Alexander,@alexwheezy
 Maarten Coopens,@maarteNNNN
 Niklas Johansson,@Raphexion
+glystik,@glystik
+Michael Lynch,@mtlynch
diff --git a/docs/Chapters/01-base64.html b/docs/Chapters/01-base64.html
index 9e6d25c9..e32e01a4 100644
--- a/docs/Chapters/01-base64.html
+++ b/docs/Chapters/01-base64.html
@@ -385,7 +385,7 @@ <h2 data-number="4.1" class="anchored" data-anchor-id="how-the-base64-algorithm-
 <p>If you are unsure about the differences between an “encoder” and a “decoder”, take a look at <a href="#sec-encode-vs-decode" class="quarto-xref"><span>Section 4.2</span></a>.</p>
 <section id="sec-base64-scale" class="level3" data-number="4.1.1">
 <h3 data-number="4.1.1" class="anchored" data-anchor-id="sec-base64-scale"><span class="header-section-number">4.1.1</span> The base64 scale</h3>
-<p>The base64 encoding system is based on a scale that goes from 0 to 63 (hence the name). Each index in this scale is represented by a character (it is a scale of 64 characters). So, in order to convert some binary data, to the base64 encoding, we need to convert each binary number to the corresponding character in this “scale of 64 characters”.</p>
+<p>The base64 encoding system is based on a scale that goes from 0 to 63 (hence the name). Each index in this scale is represented by a character (it’s a scale of 64 characters). So, in order to convert some binary data, to the base64 encoding, we need to convert each binary number to the corresponding character in this “scale of 64 characters”.</p>
 <p>The base64 scale starts with all ASCII uppercase letters (A to Z) which represents the first 25 indexes in this scale (0 to 25). After that, we have all ASCII lowercase letters (a to z), which represents the range 26 to 51 in the scale. After that, we have the one digit numbers (0 to 9), which represents the indexes from 52 to 61 in the scale. Finally, the last two indexes in the scale (62 and 63) are represented by the characters <code>+</code> and <code>/</code>, respectively.</p>
 <p>These are the 64 characters that compose the base64 scale. The equal sign character (<code>=</code>) is not part of the scale itself, but it is a special character in the base64 encoding system. This character is used solely as a suffix, to mark the end of the character sequence, or, to mark the end of meaningful characters in the sequence.</p>
 <p>The bullet points below summarises the base64 scale:</p>
@@ -401,7 +401,7 @@ <h3 data-number="4.1.1" class="anchored" data-anchor-id="sec-base64-scale"><span
 <h3 data-number="4.1.2" class="anchored" data-anchor-id="sec-base64-table"><span class="header-section-number">4.1.2</span> Creating the scale as a lookup table</h3>
 <p>The best way to represent this scale in code, is to represent it as a <em>lookup table</em>. Lookup tables are a classic strategy in computer science to speed up calculations. The basic idea is to replace a runtime calculation (which can take a long time to be done) with a basic array indexing operation.</p>
 <p>Instead of calculating the results everytime you need them, you calculate all possible results at once, and then, you store them in an array (which behaves lake a “table”). Then, every time you need to use one of the characters in the base64 scale, instead of using many resources to calculate the exact character to be used, you simply retrieve this character from the array where you stored all the possible characters in the base64 scale. We retrieve the character that we need directly from memory.</p>
-<p>We can start building a Zig struct to store our base64 decoder/encoder logic. We start with the <code>Base64</code> struct below. For now, we only have one single data member in this struct, i.e.&nbsp;the member <code>_table</code>, which represents our lookup table. We also have an <code>init()</code> method, to create a new instance of a <code>Base64</code> object, and, a <code>_char_at()</code> method, which is a “get character at index <span class="math inline">\(x\)</span>” type of function.</p>
+<p>We can start building a Zig struct to store our base64 decoder/encoder logic. We start with the <code>Base64</code> struct below. For now, we only have one single data member in this struct, i.e., the member <code>_table</code>, which represents our lookup table. We also have an <code>init()</code> method, to create a new instance of a <code>Base64</code> object, and, a <code>_char_at()</code> method, which is a “get character at index <span class="math inline">\(x\)</span>” type of function.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb1"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Base64 = <span class="kw">struct</span> <span class="op">{</span></span>
 <span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a>    _table: *<span class="kw">const</span> [<span class="dv">64</span>]<span class="dt">u8</span>,</span>
@@ -420,7 +420,7 @@ <h3 data-number="4.1.2" class="anchored" data-anchor-id="sec-base64-table"><span
 <span id="cb1-15"><a href="#cb1-15" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
 <span id="cb1-16"><a href="#cb1-16" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>In other words, the <code>_char_at()</code> method is responsible for getting the character in the lookup table (i.e.&nbsp;the <code>_table</code> struct data member) that corresponds to a particular index in the “base64 scale”. So, in the example below, we know that the character that corresponds to the index 28 in the “base64 scale” is the character “c”.</p>
+<p>In other words, the <code>_char_at()</code> method is responsible for getting the character in the lookup table (i.e., the <code>_table</code> struct data member) that corresponds to a particular index in the “base64 scale”. So, in the example below, we know that the character that corresponds to the index 28 in the “base64 scale” is the character “c”.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb2"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> base64 = Base64.init();</span>
 <span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(</span>
@@ -434,7 +434,7 @@ <h3 data-number="4.1.2" class="anchored" data-anchor-id="sec-base64-table"><span
 <h3 data-number="4.1.3" class="anchored" data-anchor-id="sec-base64-encoder-algo"><span class="header-section-number">4.1.3</span> A base64 encoder</h3>
 <p>The algorithm behind a base64 encoder usually works on a window of 3 bytes. Because each byte has 8 bits, so, 3 bytes forms a set of <span class="math inline">\(8 \times 3 = 24\)</span> bits. This is desirable for the base64 algorithm, because 24 bits is divisible by 6, which forms <span class="math inline">\(24 / 6 = 4\)</span> groups of 6 bits each.</p>
 <p>Therefore, the base64 algorithm works by converting 3 bytes at a time into 4 characters from the base64 scale. It keeps iterating through the input string, 3 bytes at a time, and converting them into the base64 scale, producing 4 characters per iteration. It keeps iterating, and producing these “new characters” until it hits the end of the input string.</p>
-<p>Now, you may think, what if you have a particular string that have a number of bytes that is not divisible by 3? What happens? For example, if you have a string that contains only two characters/bytes, such as “Hi”. How the algorithm would behave in such situation? You find the answer at <a href="#fig-base64-algo1" class="quarto-xref">Figure&nbsp;<span>4.1</span></a>. You can see at <a href="#fig-base64-algo1" class="quarto-xref">Figure&nbsp;<span>4.1</span></a> that the string “Hi”, when converted to base64, becomes the string “SGk=”:</p>
+<p>Now you may think, what if you have a particular string that has a number of bytes that is not divisible by 3 - what happens? For example, if you have a string that contains only two characters/bytes, such as “Hi”. How would the algorithm behave in such situation? You find the answer in <a href="#fig-base64-algo1" class="quarto-xref">Figure&nbsp;<span>4.1</span></a>. You can see in <a href="#fig-base64-algo1" class="quarto-xref">Figure&nbsp;<span>4.1</span></a> that the string “Hi”, when converted to base64, becomes the string “SGk=”:</p>
 <div id="fig-base64-algo1" class="quarto-float quarto-figure quarto-figure-center anchored">
 <figure class="quarto-float quarto-float-fig figure">
 <div aria-describedby="fig-base64-algo1-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
@@ -446,16 +446,17 @@ <h3 data-number="4.1.3" class="anchored" data-anchor-id="sec-base64-encoder-algo
 </figure>
 </div>
 <p>Taking the string “Hi” as an example, we have 2 bytes, or, 16 bits in total. So, we lack a full byte (8 bits) to complete the window of 24 bits that the base64 algorithm likes to work on. The first thing that the algorithm does, is to check how to divide the input bytes into groups of 6 bits.</p>
-<p>If the algorithm notices that there is a group of 6 bits that, have some bits in it, but, at the same time, it is not full (in other words, <span class="math inline">\(0 &lt; nbits &lt; 6\)</span>, being <span class="math inline">\(nbits\)</span> the number of bits), meaning that, it lacks some bits to fill the 6-bits requirement, the algorithm simply add extra zeros in this group to fill the space that it needs. That is why at <a href="#fig-base64-algo1" class="quarto-xref">Figure&nbsp;<span>4.1</span></a>, on the third group after the 6-bit transformation, 2 extra zeros were added to fill the gap in this group.</p>
+<p>If the algorithm notices that there is a group of 6 bits that it’s not complete, meaning that, this group contains <span class="math inline">\(nbits\)</span>, where <span class="math inline">\(0 &lt; nbits &lt; 6\)</span>,</p>
+<p>the algorithm simply adds extra zeros in this group to fill the space that it needs. That is why in <a href="#fig-base64-algo1" class="quarto-xref">Figure&nbsp;<span>4.1</span></a>, in the third group after the 6-bit transformation, 2 extra zeros were added to fill the gap.</p>
 <p>When we have a 6-bit group that is not completely full, like the third group, extra zeros are added to fill the gap. But what about when an entire 6-bit group is empty, or, it simply doesn’t exist? This is the case of the fourth 6-bit group exposed at <a href="#fig-base64-algo1" class="quarto-xref">Figure&nbsp;<span>4.1</span></a>.</p>
 <p>This fourth group is necessary, because the algorithm works on 4 groups of 6 bits. But the input string does not have enough bytes to create a fourth 6-bit group. Every time this happens, where an entire group of 6 bits is empty, this group becomes a “padding group”. Every “padding group” is mapped to the character <code>=</code> (equal sign), which represents “null”, or, the end of meaningful characters in the sequence. Hence, everytime that the algorithm produces a “padding group”, this group is automatically mapped to <code>=</code>.</p>
-<p>As another example, if you give the string “0” as input to a base64 encoder, this string is translated into the base64 sequence “MA==”. The character “0” is, in binary, the sequence <code>00110000</code><a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>. So, with the 6-bit transformation exposed at <a href="#fig-base64-algo1" class="quarto-xref">Figure&nbsp;<span>4.1</span></a>, this single character would produce these two 6-bit groups: <code>001100</code>, <code>000000</code>. The remaining two 6-bit groups become “padding groups”. That is why the last two characters in the output sequence (MA==) are <code>==</code>.</p>
+<p>As another example, if you give the string “0” as input to a base64 encoder, this string is translated into the base64 sequence “MA==”. The character “0” is, in binary, the sequence <code>00110000</code><a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>. So, with the 6-bit transformation exposed in <a href="#fig-base64-algo1" class="quarto-xref">Figure&nbsp;<span>4.1</span></a>, this single character would produce these two 6-bit groups: <code>001100</code>, <code>000000</code>. The remaining two 6-bit groups become “padding groups”. That is why the last two characters in the output sequence (MA==) are <code>==</code>.</p>
 </section>
 <section id="sec-base64-decoder-algo" class="level3" data-number="4.1.4">
 <h3 data-number="4.1.4" class="anchored" data-anchor-id="sec-base64-decoder-algo"><span class="header-section-number">4.1.4</span> A base64 decoder</h3>
-<p>The algorithm behind a base64 decoder is essentially the inverse process of a base64 encoder. A base64 decoder needs to translate base64 messages back into their original meaning, i.e.&nbsp;into the original sequence of binary data.</p>
+<p>The algorithm behind a base64 decoder is essentially the inverse process of a base64 encoder. A base64 decoder needs to translate base64 messages back into their original meaning, i.e., into the original sequence of binary data.</p>
 <p>A base64 decoder usually works on a window of 4 bytes. Because it wants to convert these 4 bytes back into the original sequence of 3 bytes, that was converted into 4 groups of 6 bits by the base64 encoder. Remember, in a base64 decoder we are essentially reverting the process made by the base64 encoder.</p>
-<p>Each byte in the input string (the base64 encoded string) normally contributes to re-create two different bytes in the output (the original binary data). In other words, each byte that comes out of a base64 decoder is created by transforming merging two different bytes in the input together. You can visualize this relationship at <a href="#fig-base64-algo2" class="quarto-xref">Figure&nbsp;<span>4.2</span></a>:</p>
+<p>Each byte in the input string (the base64 encoded string) normally contributes to re-create two different bytes in the output (the original binary data). In other words, each byte that comes out of a base64 decoder is created by transforming merging two different bytes in the input together. You can visualize this relationship in <a href="#fig-base64-algo2" class="quarto-xref">Figure&nbsp;<span>4.2</span></a>:</p>
 <div id="fig-base64-algo2" class="quarto-float quarto-figure quarto-figure-center anchored">
 <figure class="quarto-float quarto-float-fig figure">
 <div aria-describedby="fig-base64-algo2-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
@@ -467,15 +468,15 @@ <h3 data-number="4.1.4" class="anchored" data-anchor-id="sec-base64-decoder-algo
 </figure>
 </div>
 <p>The exact transformations, or, the exact steps applied to each byte from the input to transform them into the bytes of the output, are a bit tricky to visualize in a figure like this. Because of that, I have summarized these transformations as “Some bit shifting and additions …” in the figure. These transformations will be described in depth later.</p>
-<p>Besides that, if you look again at <a href="#fig-base64-algo2" class="quarto-xref">Figure&nbsp;<span>4.2</span></a>, you will notice that the character <code>=</code> was completely ignored by the algorithm. Remember, this is just a special character that marks the end of meaningful characters in the base64 sequence. So, every <code>=</code> character in a base64 encoded sequence should be ignored by a base64 decoder.</p>
+<p>Besides that, if you look again in <a href="#fig-base64-algo2" class="quarto-xref">Figure&nbsp;<span>4.2</span></a>, you will notice that the character <code>=</code> was completely ignored by the algorithm. Remember, this is just a special character that marks the end of meaningful characters in the base64 sequence. So, every <code>=</code> character in a base64 encoded sequence should be ignored by a base64 decoder.</p>
 </section>
 </section>
 <section id="sec-encode-vs-decode" class="level2" data-number="4.2">
 <h2 data-number="4.2" class="anchored" data-anchor-id="sec-encode-vs-decode"><span class="header-section-number">4.2</span> Difference between encode and decode</h2>
-<p>If you don’t have any previous experience with base64, you might not understand the differences between “encode” and “decode”. Essentially, the terms “encode” and “decode” here have the exact same meaning as they have in the field of encryption (i.e.&nbsp;they mean the same thing as “encode” and “decode” in hashing algorithms, like the MD5 algorithm).</p>
+<p>If you don’t have any previous experience with base64, you might not understand the differences between “encode” and “decode”. Essentially, the terms “encode” and “decode” here have the exact same meaning as they have in the field of encryption (i.e., they mean the same thing as “encode” and “decode” in hashing algorithms, like the MD5 algorithm).</p>
 <p>Thus, “encode” means that we want to encode, or, in other words, we want to translate some message into the base64 encoding system. We want to produce the sequence of base64 characters that represent this original message in the base64 encoding system.</p>
 <p>In contrast, “decode” represents the inverse process. We want to decode, or, in other words, translate a base64 message back to its original content. So, in this process we get a sequence of base64 characters as input, and produce as output, the binary data that is represented by this sequence of base64 characters.</p>
-<p>Any base64 library is normally composed of these two parts: 1) the encoder, which is a function that encodes (i.e.&nbsp;it converts) any sequence of binary data into a sequence of base64 characters; 2) the decoder, which is a function that converts a sequence of base64 characters back into the original sequence of binary data.</p>
+<p>Any base64 library is normally composed of these two parts: 1) the encoder, which is a function that encodes (i.e., it converts) any sequence of binary data into a sequence of base64 characters; 2) the decoder, which is a function that converts a sequence of base64 characters back into the original sequence of binary data.</p>
 </section>
 <section id="sec-base64-length-out" class="level2" data-number="4.3">
 <h2 data-number="4.3" class="anchored" data-anchor-id="sec-base64-length-out"><span class="header-section-number">4.3</span> Calculating the size of the output</h2>
@@ -495,9 +496,9 @@ <h2 data-number="4.3" class="anchored" data-anchor-id="sec-base64-length-out"><s
 <span id="cb4-10"><a href="#cb4-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> n_output * <span class="dv">4</span>;</span>
 <span id="cb4-11"><a href="#cb4-11" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>Also, you might have notice that, if the input length is less than 3 bytes, then, the output length of the encoder is always 4 bytes. This is the case for every input with less than 3 bytes, because, as I described at <a href="#sec-base64-encoder-algo" class="quarto-xref"><span>Section 4.1.3</span></a>, the algorithm always produces enough “padding-groups” in the end result, to complete the 4 bytes window.</p>
-<p>Now, for the decoder, we just need to apply the inverse logic: for each 4 bytes in the input, 3 bytes will be produced in the output of the decoder. I mean, this is roughly true, because we also need to take the <code>=</code> character into account, which is always ignored by the decoder, as we described at <a href="#sec-base64-decoder-algo" class="quarto-xref"><span>Section 4.1.4</span></a>, and, at <a href="#fig-base64-algo2" class="quarto-xref">Figure&nbsp;<span>4.2</span></a>. But we can ignore this fact for now, just to keep things simple.</p>
-<p>The function <code>_calc_decode_length()</code> exposed below summarizes this logic that we described. It is very similar to the function <code>_calc_encode_length()</code>. Only the division part is twisted, and also, in the special case where we have less than 4 bytes in the input to work on. Also notice that this time, we apply a floor operation over the output of the division, by using the <code>divFloor()</code> function (instead of a ceiling operation with <code>divCeil()</code>).</p>
+<p>Also, you might have notice that, if the input length is less than 3 bytes, then, the output length of the encoder is always 4 bytes. This is the case for every input with less than 3 bytes, because, as I described in <a href="#sec-base64-encoder-algo" class="quarto-xref"><span>Section 4.1.3</span></a>, the algorithm always produces enough “padding-groups” in the end result, to complete the 4 bytes window.</p>
+<p>Now, for the decoder, we just need to apply the inverse logic: for each 4 bytes in the input, 3 bytes will be produced in the output of the decoder. I mean, this is roughly true, because we also need to take the <code>=</code> character into account, which is always ignored by the decoder, as we described in <a href="#sec-base64-decoder-algo" class="quarto-xref"><span>Section 4.1.4</span></a>, and, in <a href="#fig-base64-algo2" class="quarto-xref">Figure&nbsp;<span>4.2</span></a>. But we can ignore this fact for now, just to keep things simple.</p>
+<p>The function <code>_calc_decode_length()</code> exposed below summarizes this logic that we described. It’s very similar to the function <code>_calc_encode_length()</code>. Only the division part is twisted, and also, in the special case where we have less than 4 bytes in the input to work on. Also notice that this time, we apply a floor operation over the output of the division, by using the <code>divFloor()</code> function (instead of a ceiling operation with <code>divCeil()</code>).</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb5"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> _calc_decode_length(input: []<span class="kw">const</span> <span class="dt">u8</span>) !<span class="dt">usize</span> <span class="op">{</span></span>
@@ -517,7 +518,7 @@ <h2 data-number="4.4" class="anchored" data-anchor-id="sec-encoder-logic"><span
 <p>In this section, we can start building the logic behind the <code>encode()</code> function, which will be responsible for encoding messages into the base64 encoding system. If you are an anxious person, and you want to see now the full source code of the implementation for this base64 encoder/decoder, you can find it at the <code>ZigExamples</code> folder in the official repository of this book<a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a>.</p>
 <section id="sec-6bit-transf" class="level3" data-number="4.4.1">
 <h3 data-number="4.4.1" class="anchored" data-anchor-id="sec-6bit-transf"><span class="header-section-number">4.4.1</span> The 6-bit transformation</h3>
-<p>The 6-bit transformation presented at <a href="#fig-base64-algo1" class="quarto-xref">Figure&nbsp;<span>4.1</span></a> is the core part of the base64 encoder algorithm. By understanding how this transformation is made in code, the rest of the algorithm becomes much simpler to comprehend.</p>
+<p>The 6-bit transformation presented in <a href="#fig-base64-algo1" class="quarto-xref">Figure&nbsp;<span>4.1</span></a> is the core part of the base64 encoder algorithm. By understanding how this transformation is made in code, the rest of the algorithm becomes much simpler to comprehend.</p>
 <p>In essence, this 6-bit transformation is made with the help of bitwise operators. Bitwise operators are essential to any type of low-level operation that is done at the bit-level. For the specific case of the base64 algorithm, the operators <em>bif shift to the left</em> (<code>&lt;&lt;</code>), <em>bit shift to the right</em> (<code>&gt;&gt;</code>), and the <em>bitwise and</em> (<code>&amp;</code>) are used. They are the core solution for the 6-bit transformation.</p>
 <p>There are 3 different scenarios that we need to take into account in this transformation. First, is the perfect scenario, where we have the perfect window of 3 bytes to work on. Second, we have the scenario where we have a window of only two bytes to work with. And last, we have the scenario where we have a window of one single byte.</p>
 <p>In each of these 3 scenarios, the 6-bit transformation works a bit differently. To make the explanation easier, I will use the variable <code>output</code> to refer to the bytes in the output of the base64 encoder, and the variable <code>input</code> to refer to the bytes in the input of the encoder.</p>
@@ -640,8 +641,8 @@ <h3 data-number="4.4.1" class="anchored" data-anchor-id="sec-6bit-transf"><span
 <h3 data-number="4.4.2" class="anchored" data-anchor-id="bit-shifting-in-zig"><span class="header-section-number">4.4.2</span> Bit-shifting in Zig</h3>
 <p>Bit-shifting in Zig works similarly to bit-shifting in C. All bitwise operators that exist in C are available in Zig. Here, in the base64 encoder algorithm, they are essential to produce the result we want.</p>
 <p>For those who are not familiar with these operators, they are operators that operates at the bit-level of your values. This means that these operators takes the bits that form the value you have, and change them in some way. This ultimately also changes the value itself, because the binary representation of this value changes.</p>
-<p>We have already seen at <a href="#fig-encoder-bitshift" class="quarto-xref">Figure&nbsp;<span>4.3</span></a> the effect produced by a bit-shift. But let’s use the first byte in the output of the base64 encoder as another example of what bit-shifting means. This is the easiest byte of the 4 bytes in the output to build. Because we only need to move the bits from the first byte in the input two positions to the right, with the <em>bit shift to the right</em> (<code>&gt;&gt;</code>) operator.</p>
-<p>If we take the string “Hi” that we used at <a href="#fig-base64-algo1" class="quarto-xref">Figure&nbsp;<span>4.1</span></a> as an example, the first byte in this string is “H”, which is the sequence <code>01001000</code> in binary. If we move the bits of this byte, two places to the right, we get the sequence <code>00010010</code> as result. This binary sequence is the value <code>18</code> in decimal, and also, the value <code>0x12</code> in hexadecimal. Notice that the first 6 bits of “H” were moved to the end of the byte. With this operation, we get the first byte of the output.</p>
+<p>We have already seen in <a href="#fig-encoder-bitshift" class="quarto-xref">Figure&nbsp;<span>4.3</span></a> the effect produced by a bit-shift. But let’s use the first byte in the output of the base64 encoder as another example of what bit-shifting means. This is the easiest byte of the 4 bytes in the output to build. Because we only need to move the bits from the first byte in the input two positions to the right, with the <em>bit shift to the right</em> (<code>&gt;&gt;</code>) operator.</p>
+<p>If we take the string “Hi” that we used in <a href="#fig-base64-algo1" class="quarto-xref">Figure&nbsp;<span>4.1</span></a> as an example, the first byte in this string is “H”, which is the sequence <code>01001000</code> in binary. If we move the bits of this byte, two places to the right, we get the sequence <code>00010010</code> as result. This binary sequence is the value <code>18</code> in decimal, and also, the value <code>0x12</code> in hexadecimal. Notice that the first 6 bits of “H” were moved to the end of the byte. With this operation, we get the first byte of the output.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb6"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb6-2"><a href="#cb6-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
@@ -679,14 +680,14 @@ <h3 data-number="4.4.3" class="anchored" data-anchor-id="selecting-specific-bits
 </section>
 <section id="allocating-space-for-the-output" class="level3" data-number="4.4.4">
 <h3 data-number="4.4.4" class="anchored" data-anchor-id="allocating-space-for-the-output"><span class="header-section-number">4.4.4</span> Allocating space for the output</h3>
-<p>As I described at <a href="01-memory.html#sec-stack" class="quarto-xref"><span>Section 3.1.4</span></a>, to store an object in the stack, this object needs to have a known and fixed length at compile-time. This is an important limitation for our base64 encoder/decoder case. Because the size of the output (from both the encoder and decoder) depends directly on the size of the input.</p>
+<p>As I described in <a href="01-memory.html#sec-stack" class="quarto-xref"><span>Section 3.1.4</span></a>, to store an object in the stack, this object needs to have a known and fixed length at compile-time. This is an important limitation for our base64 encoder/decoder case. Because the size of the output (from both the encoder and decoder) depends directly on the size of the input.</p>
 <p>Having this in mind, we cannot know at compile time which is the size of the output for both the encoder and decoder. So, if we can’t know the size of the output at compile time, this means that we cannot store the output for both the encoder and decoder in the stack.</p>
-<p>Consequently, we need to store this output on the heap, and, as I commented at <a href="01-memory.html#sec-heap" class="quarto-xref"><span>Section 3.1.5</span></a>, we can only store objects in the heap by using allocator objects. So, one the arguments to both the <code>encode()</code> and <code>decode()</code> functions, needs to be an allocator object, because we know for sure that, at some point inside the body of these functions, we need to allocate space on the heap to store the output of these functions.</p>
+<p>Consequently, we need to store this output on the heap, and, as I commented in <a href="01-memory.html#sec-heap" class="quarto-xref"><span>Section 3.1.5</span></a>, we can only store objects in the heap by using allocator objects. So, one the arguments to both the <code>encode()</code> and <code>decode()</code> functions, needs to be an allocator object, because we know for sure that, at some point inside the body of these functions, we need to allocate space on the heap to store the output of these functions.</p>
 <p>That is why, both the <code>encode()</code> and <code>decode()</code> functions that I present in this book, have an argument called <code>allocator</code>, which receives a allocator object as input, identified by the type <code>std.mem.Allocator</code> from the Zig Standard Library.</p>
 </section>
 <section id="writing-the-encode-function" class="level3" data-number="4.4.5">
 <h3 data-number="4.4.5" class="anchored" data-anchor-id="writing-the-encode-function"><span class="header-section-number">4.4.5</span> Writing the <code>encode()</code> function</h3>
-<p>Now that we have a basic understanding on how the bitwise operators work, and how exactly they help us to achieve the result we want to achieve. We can now encapsulate all the logic that we have described at <a href="#fig-base64-algo1" class="quarto-xref">Figure&nbsp;<span>4.1</span></a> and <a href="#tbl-transf-6bit" class="quarto-xref">Table&nbsp;<span>4.1</span></a> into a nice function that we can add to our <code>Base64</code> struct definition, that we started at <a href="#sec-base64-table" class="quarto-xref"><span>Section 4.1.2</span></a>.</p>
+<p>Now that we have a basic understanding on how the bitwise operators work, and how exactly they help us to achieve the result we want to achieve. We can now encapsulate all the logic that we have described in <a href="#fig-base64-algo1" class="quarto-xref">Figure&nbsp;<span>4.1</span></a> and <a href="#tbl-transf-6bit" class="quarto-xref">Table&nbsp;<span>4.1</span></a> into a nice function that we can add to our <code>Base64</code> struct definition, that we started in <a href="#sec-base64-table" class="quarto-xref"><span>Section 4.1.2</span></a>.</p>
 <p>You can find the <code>encode()</code> function below. Notice that the first argument of this function, is the <code>Base64</code> struct itself. Therefore, this argument clearly signals that this function is a method from the <code>Base64</code> struct.</p>
 <p>Because the <code>encode()</code> function itself is fairly long, I intentionally omitted the <code>Base64</code> struct definition in this source code, just for brevity reasons. So, just remember that this function is a public function (or a public method) from the <code>Base64</code> struct.</p>
 <p>Furthermore, this <code>encode()</code> function has two other arguments:</p>
@@ -694,7 +695,7 @@ <h3 data-number="4.4.5" class="anchored" data-anchor-id="writing-the-encode-func
 <li><code>input</code> is the input sequence of characters that you want to encode in base64;</li>
 <li><code>allocator</code> is an allocator object to use in the necessary memory allocations.</li>
 </ol>
-<p>I described everything you need to know about allocator objects at <a href="01-memory.html#sec-allocators" class="quarto-xref"><span>Section 3.3</span></a>. So, if you are not familiar with them, I highly recommend you to comeback to that section, and read it. By looking at the <code>encode()</code> function, you will see that we use this allocator object to allocate enough memory to store the output of the encoding process.</p>
+<p>I described everything you need to know about allocator objects in <a href="01-memory.html#sec-allocators" class="quarto-xref"><span>Section 3.3</span></a>. So, if you are not familiar with them, I highly recommend you to comeback to that section, and read it. By looking at the <code>encode()</code> function, you will see that we use this allocator object to allocate enough memory to store the output of the encoding process.</p>
 <p>The main for loop in the function is responsible for iterating through the entire input string. In every iteration, we use a <code>count</code> variable to count how many iterations we had at the moment. When <code>count</code> reaches 3, then, we try to encode the 3 characters (or bytes) that we have accumulated in the temporary buffer object (<code>buf</code>).</p>
 <p>After encoding these 3 characters and storing the result in the <code>output</code> variable, we reset the <code>count</code> variable to zero, and start to count again on the next iteration of the loop. If the loop hits the end of the string, and, the <code>count</code> variable is less than 3, then, it means that the temporary buffer contains the last 1 or 2 bytes from the input. That is why we have two <code>if</code> statements after the for loop. To deal which each possible case.</p>
 <div class="cell">
@@ -757,14 +758,14 @@ <h3 data-number="4.4.5" class="anchored" data-anchor-id="writing-the-encode-func
 </section>
 <section id="sec-decoder-logic" class="level2" data-number="4.5">
 <h2 data-number="4.5" class="anchored" data-anchor-id="sec-decoder-logic"><span class="header-section-number">4.5</span> Building the decoder logic</h2>
-<p>Now, we can focus on writing the base64 decoder logic. Remember from <a href="#fig-base64-algo2" class="quarto-xref">Figure&nbsp;<span>4.2</span></a> that, a base64 decoder does the inverse process of an encoder. So, all we need to do, is to write a <code>decode()</code> function that performs the inverse process that I exposed at <a href="#sec-encoder-logic" class="quarto-xref"><span>Section 4.4</span></a>.</p>
+<p>Now, we can focus on writing the base64 decoder logic. Remember from <a href="#fig-base64-algo2" class="quarto-xref">Figure&nbsp;<span>4.2</span></a> that, a base64 decoder does the inverse process of an encoder. So, all we need to do, is to write a <code>decode()</code> function that performs the inverse process that I exposed in <a href="#sec-encoder-logic" class="quarto-xref"><span>Section 4.4</span></a>.</p>
 <section id="sec-map-base64-index" class="level3" data-number="4.5.1">
 <h3 data-number="4.5.1" class="anchored" data-anchor-id="sec-map-base64-index"><span class="header-section-number">4.5.1</span> Mapping base64 characters to their indexes</h3>
 <p>One thing that we need to do, in order to decode a base64-encoded message, is to calculate the index in the base64 scale of every base64 character that we encounter in the decoder input.</p>
 <p>In other words, the decoder receives as input, a sequence of base64 characters. We need to translate this sequence of characters into a sequence of indexes. These indexes are the index of each character in the base64 scale. This way, we get the value/byte that was calculated in the 6-bit transformation step of the encoder process.</p>
 <p>There are probably better/faster ways to calculate this, especially using a “divide and conquer” type of strategy. But for now, I am satisfied with a simple and “brute force” type of strategy. The <code>_char_index()</code> function below contains this strategy.</p>
 <p>We are essentially looping through the <em>lookup table</em> with the base64 scale, and comparing the character we got with each character in the base64 scale. If these characters match, then, we return the index of this character in the base64 scale as the result.</p>
-<p>Notice that, if the input character is <code>'='</code>, the function returns the index 64, which is “out of range” in the scale. But, as I described at <a href="#sec-base64-scale" class="quarto-xref"><span>Section 4.1.1</span></a>, the character <code>'='</code> does not belong to the base64 scale itself. It is a special and meaningless character in base64.</p>
+<p>Notice that, if the input character is <code>'='</code>, the function returns the index 64, which is “out of range” in the scale. But, as I described in <a href="#sec-base64-scale" class="quarto-xref"><span>Section 4.1.1</span></a>, the character <code>'='</code> does not belong to the base64 scale itself. It’s a special and meaningless character in base64.</p>
 <p>Also notice that this <code>_char_index()</code> function is a method from our <code>Base64</code> struct, because of the <code>self</code> argument. Again, I have omitted the <code>Base64</code> struct definition in this example for brevity reasons.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb11"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> _char_index(self: Base64, char: <span class="dt">u8</span>) <span class="dt">u8</span> <span class="op">{</span></span>
@@ -797,8 +798,8 @@ <h3 data-number="4.5.2" class="anchored" data-anchor-id="the-6-bit-transformatio
 <li><code>output[1]</code> is produced by summing two components. First, move the bits from <code>buf[1]</code> four positions to the left. Second, move the bits from <code>buf[2]</code> 2 positions to the right. Then, sum these two components.</li>
 <li><code>output[2]</code> is produced by summing two components. First, move the bits from <code>buf[2]</code> six positions to the left. Then, you sum the result with <code>buf[3]</code>.</li>
 </ol>
-<p>Before we continue, let’s try to visualize how these transformations make the original bytes that we had before the encoding process. First, think back to the 6-bit transformation performed by the encoder exposed at <a href="#sec-encoder-logic" class="quarto-xref"><span>Section 4.4</span></a>. The first byte in the output of the encoder is produced by moving the bits in the first byte of the input two positions to the right.</p>
-<p>If for example the first byte in the input of the encoder was the sequence <code>ABCDEFGH</code>, then, the first byte in the output of the encoder would be <code>00ABCDEF</code> (this sequence would be the first byte in the input of the decoder). Now, if the second byte in the input of the encoder was the sequence <code>IJKLMNOP</code>, then, the second byte in the encoder output would be <code>00GHIJKL</code> (as we demonstrated at <a href="#fig-encoder-bitshift" class="quarto-xref">Figure&nbsp;<span>4.3</span></a>).</p>
+<p>Before we continue, let’s try to visualize how these transformations make the original bytes that we had before the encoding process. First, think back to the 6-bit transformation performed by the encoder exposed in <a href="#sec-encoder-logic" class="quarto-xref"><span>Section 4.4</span></a>. The first byte in the output of the encoder is produced by moving the bits in the first byte of the input two positions to the right.</p>
+<p>If for example the first byte in the input of the encoder was the sequence <code>ABCDEFGH</code>, then, the first byte in the output of the encoder would be <code>00ABCDEF</code> (this sequence would be the first byte in the input of the decoder). Now, if the second byte in the input of the encoder was the sequence <code>IJKLMNOP</code>, then, the second byte in the encoder output would be <code>00GHIJKL</code> (as we demonstrated in <a href="#fig-encoder-bitshift" class="quarto-xref">Figure&nbsp;<span>4.3</span></a>).</p>
 <p>Hence, if the sequences <code>00ABCDEF</code> and <code>00GHIJKL</code> are the first and second bytes, respectively, in the input of the decoder, the <a href="#fig-decoder-bitshift" class="quarto-xref">Figure&nbsp;<span>4.4</span></a> demonstrates visually how these two bytes are transformed into the first byte of the output of the decoder. Notice that the output byte is the sequence <code>ABCDEFGH</code>, which is the original byte from the input of the encoder.</p>
 <div id="fig-decoder-bitshift" class="quarto-float quarto-figure quarto-figure-center anchored">
 <figure class="quarto-float quarto-float-fig figure">
diff --git a/docs/Chapters/01-memory.html b/docs/Chapters/01-memory.html
index 52b997d6..e4c2e35d 100644
--- a/docs/Chapters/01-memory.html
+++ b/docs/Chapters/01-memory.html
@@ -362,7 +362,7 @@ <h3 data-number="3.1.1" class="anchored" data-anchor-id="sec-compile-time"><span
 <p>When you write a program in Zig, the values of some of the objects that you write in your program are <em>known at compile time</em>. Meaning that, when you compile your Zig source code, during the compilation process, the <code>zig</code> compiler can figure out the exact value of a particular object that exists in your source code. Knowing the length (or the size) of each object is also important. So the length (or the size) of each object that you write in your program is, in some cases, <em>known at compile time</em>.</p>
 <p>The <code>zig</code> compiler cares more about knowing the length (or the size) of a particular object , than to know its actual value. But, if the <code>zig</code> compiler knows the value of the object, then, it automatically knows the size of this object. Because it can simply calculate the size of the object by looking at the size of the value.</p>
 <p>Therefore, the priority for the <code>zig</code> compiler is to discover the size of each object in your source code. If the value of the object in question is known at compile-time, then, the <code>zig</code> compiler automatically knows the size/length of this object. But if the value of this object is not known at compile-time, then, the size of this object is only known at compile-time if, and only if, the type of this object has a known fixed size.</p>
-<p>In order for a type to have a known fixed size, this type must have data members whose size is fixed. If this type includes, for example, a variable sized array in it, then, this type does not have a known fixed size. Because this array can have any size at runtime (i.e.&nbsp;it can be an array of 2 elements, or 50 elements, or 1 thousand elements, etc.).</p>
+<p>In order for a type to have a known fixed size, this type must have data members whose size is fixed. If this type includes, for example, a variable sized array in it, then, this type does not have a known fixed size. Because this array can have any size at runtime (i.e., it can be an array of 2 elements, or 50 elements, or 1 thousand elements, etc.).</p>
 <p>For example, a string object, which internally is an array of constant u8 values (<code>[]const u8</code>) has a variable size. It can be a string object with 100 or 500 characters in it. If we do not know at compile-time, which exact string will be stored inside this string object, then, we cannot calculate the size of this string object at compile-time. So, any type, or any struct declaration that you make, that includes a string data member that does not have an explicit fixed size, makes this type, or this new struct that you are declaring, a type that does not have a known fixed size at compile-time.</p>
 <p>In contrast, if the type of this struct that you are declaring, includes a data member that is an array, but this array has a known fixed size, like <code>[60]u8</code> (which declares an array of 60 <code>u8</code> values), then, this type, or, this struct that you are declaring, becomes a type with a known fixed size at compile-time. And because of that, in this case, the <code>zig</code> compiler does not need to know at compile-time the exact value of any object of this type. Since the compiler can find the necessary size to store this object by looking at the size of its type.</p>
 <p>Let’s look at an example. In the source code below, we have two constant objects (<code>name</code> and <code>array</code>) declared. Because the values of these particular objects are written down, in the source code itself (<code>"Pedro"</code> and the number sequence from 1 to 4), the <code>zig</code> compiler can easily discover the values of these constant objects (<code>name</code> and <code>array</code>) during the compilation process. This is what “known at compile time” means. It refers to any object that you have in your Zig source code whose value can be identified at compile time.</p>
@@ -379,7 +379,7 @@ <h3 data-number="3.1.1" class="anchored" data-anchor-id="sec-compile-time"><span
 <span id="cb1-10"><a href="#cb1-10" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>The other side of the spectrum are objects whose values are not known at compile time. Function arguments are a classic example of this. Because the value of each function argument depends on the value that you assign to this particular argument, when you call the function.</p>
-<p>For example, the function <code>input_length()</code> contains an argument named <code>input</code>, which is an array of constant <code>u8</code> integers (<code>[]const u8</code>). It is impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length of this particular argument. Because it is an array that do not have a fixed size specified explicitly in the argument type annotation.</p>
+<p>For example, the function <code>input_length()</code> contains an argument named <code>input</code>, which is an array of constant <code>u8</code> integers (<code>[]const u8</code>). It’s impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length of this particular argument. Because it’s an array that does not have a fixed size specified explicitly in the argument type annotation.</p>
 <p>So, we know that this <code>input</code> argument will be an array of <code>u8</code> integers. But we do not know at compile-time, its value, and neither its size. This information is known only at runtime, which is the period of time when you program is executed. As a consequence, the value of the expression <code>input.len</code> is also known only at runtime. This is an intrinsic characteristic of any function. Just remember that the value of function arguments is usually not “compile-time known”.</p>
 <p>However, as I mentioned earlier, what really matters to the compiler is to know the size of the object at compile-time, and not necessarily its value. So, although we don’t know the value of the object <code>n</code>, which is the result of the expression <code>input.len</code>, at compile-time, we do know its size. Because the expression <code>input.len</code> always returns a value of type <code>usize</code>, and the type <code>usize</code> has a known fixed size.</p>
 </section>
@@ -393,7 +393,7 @@ <h3 data-number="3.1.2" class="anchored" data-anchor-id="global-data-register"><
 <h3 data-number="3.1.3" class="anchored" data-anchor-id="stack-vs-heap"><span class="header-section-number">3.1.3</span> Stack vs Heap</h3>
 <p>If you are familiar with systems programming, or just low-level programming in general, you probably have heard of the “duel” between Stack vs Heap. These are two different types of memory, or different memory spaces, which are both available in Zig.</p>
 <p>These two types of memory don’t actually duel with each other. This is a common mistake that beginners have, when seeing “x vs y” styles of tabloid headlines. These two types of memory are actually complementary to each other. So, in almost every Zig program that you ever write, you will likely use a combination of both. I will describe each memory space in detail over the next sections. But for now, I just want to stablish the main difference between these two types of memory.</p>
-<p>In essence, the stack memory is normally used to store values whose length is fixed and known at compile time. In contrast, the heap memory is a <em>dynamic</em> type of memory space, meaning that, it is used to store values whose length might grow during the execution (runtime) of your program <span class="citation" data-cites="jenny2022">(<a href="../references.html#ref-jenny2022" role="doc-biblioref">Chen and Guo 2022</a>)</span>.</p>
+<p>In essence, the stack memory is normally used to store values whose length is fixed and known at compile time. In contrast, the heap memory is a <em>dynamic</em> type of memory space, meaning that, it’s used to store values whose length might grow during the execution (runtime) of your program <span class="citation" data-cites="jenny2022">(<a href="../references.html#ref-jenny2022" role="doc-biblioref">Chen and Guo 2022</a>)</span>.</p>
 <p>Lengths that grow during runtime are intrinsically associated with “runtime known” type of values. In other words, if you have an object whose length might grow during runtime, then, the length of this object becomes not known at compile time. If the length is not known at compile-time, the value of this object also becomes not known at compile-time. These types of objects should be stored in the heap memory space, which is a dynamic memory space, which can grow or shrink to fit the size of your objects.</p>
 </section>
 <section id="sec-stack" class="level3" data-number="3.1.4">
@@ -401,7 +401,7 @@ <h3 data-number="3.1.4" class="anchored" data-anchor-id="sec-stack"><span class=
 <p>The stack is a type of memory that uses the power of the <em>stack data structure</em>, hence the name. A “stack” is a type of <em>data structure</em> that uses a “last in, first out” (LIFO) mechanism to store the values you give it to. I imagine you are familiar with this data structure. But, if you are not, the <a href="https://en.wikipedia.org/wiki/Stack_(abstract_data_type)">Wikipedia page</a><a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a> , or, the <a href="https://www.geeksforgeeks.org/stack-data-structure/">Geeks For Geeks page</a><a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a> are both excellent and easy resources to fully understand how this data structure works.</p>
 <p>So, the stack memory space is a type of memory that stores values using a stack data structure. It adds and removes values from the memory by following a “last in, first out” (LIFO) principle.</p>
 <p>Every time you make a function call in Zig, an amount of space in the stack is reserved for this particular function call <span class="citation" data-cites="jenny2022 zigdocs">(<a href="../references.html#ref-jenny2022" role="doc-biblioref">Chen and Guo 2022</a>; <a href="../references.html#ref-zigdocs" role="doc-biblioref">Zig Software Foundation 2024</a>)</span>. The value of each function argument given to the function in this function call is stored in this stack space. Also, every local object that you declare inside the function scope is usually stored in this same stack space.</p>
-<p>Looking at the example below, the object <code>result</code> is a local object declared inside the scope of the <code>add()</code> function. Because of that, this object is stored inside the stack space reserved for the <code>add()</code> function. The <code>r</code> object (which is declared outside of the <code>add()</code> function scope) is also stored in the stack. But since it is declared in the “outer” scope, this object is stored in the stack space that belongs to this outer scope.</p>
+<p>Looking at the example below, the object <code>result</code> is a local object declared inside the scope of the <code>add()</code> function. Because of that, this object is stored inside the stack space reserved for the <code>add()</code> function. The <code>r</code> object (which is declared outside of the <code>add()</code> function scope) is also stored in the stack. But since it’s declared in the “outer” scope, this object is stored in the stack space that belongs to this outer scope.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb2"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> add(x: <span class="dt">u8</span>, y: <span class="dt">u8</span>) <span class="dt">u8</span> <span class="op">{</span></span>
 <span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> result = x + y;</span>
@@ -444,8 +444,8 @@ <h3 data-number="3.1.4" class="anchored" data-anchor-id="sec-stack"><span class=
 </div>
 <p>One important consequence of this mechanism is that, once the function returns, you can no longer access any memory address that was inside the space in the stack reserved for this particular function. Because this space was destroyed. This means that, if this local object is stored in the stack, you cannot make a function that <strong>returns a pointer to this object</strong>.</p>
 <p>Think about that for a second. If all local objects in the stack are destroyed at the end of the function scope, why would you even consider returning a pointer to one of these objects? This pointer is at best, invalid, or, more likely, “undefined”.</p>
-<p>Conclusion, it is totally fine to write a function that returns the local object itself as result, because then, you return the value of that object as the result. But, if this local object is stored in the stack, you should never write a function that returns a pointer to this local object. Because the memory address pointed by the pointer no longer exists.</p>
-<p>So, using again the <code>add()</code> function as an example, if you rewrite this function so that it returns a pointer to the local object <code>result</code>, the <code>zig</code> compiler will actually compile your program, with no warnings or errors. At first glance, it looks that this is good code that works as expected. But this is a lie!</p>
+<p>In conclusion, it’s totally fine to write a function that returns the local object itself as result, because then, you return the value of that object as the result. But, if this local object is stored in the stack, you should never write a function that returns a pointer to this local object. Because the memory address pointed by the pointer no longer exists.</p>
+<p>So, using again the <code>add()</code> function as an example, if you rewrite this function so that it returns a pointer to the local object <code>result</code>, the <code>zig</code> compiler will actually compile your program, with no warnings or errors. At first glance, it looks like this is good code that works as expected. But this is a lie!</p>
 <p>If you try to take a look at the value inside of the <code>r</code> object, or, if you try to use this <code>r</code> object in another expression or function call, then, you would have undefined behaviour, and major bugs in your program <span class="citation" data-cites="zigdocs">(<a href="../references.html#ref-zigdocs" role="doc-biblioref">Zig Software Foundation 2024</a>, see “Lifetime and Ownership”<a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a> and “Undefined Behaviour”<a href="#fn4" class="footnote-ref" id="fnref4" role="doc-noteref"><sup>4</sup></a> sections)</span>.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb4"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> add(x: <span class="dt">u8</span>, y: <span class="dt">u8</span>) *<span class="kw">const</span> <span class="dt">u8</span> <span class="op">{</span></span>
@@ -460,7 +460,7 @@ <h3 data-number="3.1.4" class="anchored" data-anchor-id="sec-stack"><span class=
 <span id="cb4-10"><a href="#cb4-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> r = add(<span class="dv">5</span>, <span class="dv">27</span>); _ = r;</span>
 <span id="cb4-11"><a href="#cb4-11" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>This “invalid pointer to stack variable” problem is well known across many programming language communities. If you try to do the same thing, for example, in a C or C++ program (i.e.&nbsp;returning an address to a local object stored in the stack), you would also get undefined behaviour in the program.</p>
+<p>This “invalid pointer to stack variable” problem is well known across many programming language communities. If you try to do the same thing, for example, in a C or C++ program (i.e., returning an address to a local object stored in the stack), you would also get undefined behaviour in the program.</p>
 <div class="callout callout-style-default callout-important callout-titled">
 <div class="callout-header d-flex align-content-center">
 <div class="callout-icon-container">
@@ -478,14 +478,14 @@ <h3 data-number="3.1.4" class="anchored" data-anchor-id="sec-stack"><span class=
 </section>
 <section id="sec-heap" class="level3" data-number="3.1.5">
 <h3 data-number="3.1.5" class="anchored" data-anchor-id="sec-heap"><span class="header-section-number">3.1.5</span> Heap</h3>
-<p>One important limitation of the stack, is that, only objects whose length/size is known at compile-time can be stored in it. In contrast, the heap is a much more dynamic (and flexible) type of memory. It is the perfect type of memory to use for objects whose size/length might grow during the execution of your program.</p>
+<p>One important limitation of the stack, is that, only objects whose length/size is known at compile-time can be stored in it. In contrast, the heap is a much more dynamic (and flexible) type of memory. It’s the perfect type of memory to use for objects whose size/length might grow during the execution of your program.</p>
 <p>Virtually any application that behaves as a server is a classic use case of the heap. A HTTP server, a SSH server, a DNS server, a LSP server, … any type of server. In summary, a server is a type of application that runs for long periods of time, and that serves (or “deals with”) any incoming request that reaches this particular server.</p>
 <p>The heap is a good choice for this type of system, mainly because the server does not know upfront how many requests it will receive from users, while it is active. It could be a single request, 5 thousand requests, or even zero requests. The server needs to have the ability to allocate and manage its memory according to how many requests it receives.</p>
 <p>Another key difference between the stack and the heap, is that the heap is a type of memory that you, the programmer, have complete control over. This makes the heap a more flexible type of memory, but it also makes it harder to work with. Because you, the programmer, is responsible for managing everything related to it. Including where the memory is allocated, how much memory is allocated, and where this memory is freed.</p>
 <blockquote class="blockquote">
 <p>Unlike stack memory, heap memory is allocated explicitly by programmers and it won’t be deallocated until it is explicitly freed <span class="citation" data-cites="jenny2022">(<a href="../references.html#ref-jenny2022" role="doc-biblioref">Chen and Guo 2022</a>)</span>.</p>
 </blockquote>
-<p>To store an object in the heap, you, the programmer, needs to explicitly tells Zig to do so, by using an allocator to allocate some space in the heap. At <a href="#sec-allocators" class="quarto-xref"><span>Section 3.3</span></a>, I will present how you can use allocators to allocate memory in Zig.</p>
+<p>To store an object in the heap, you, the programmer, needs to explicitly tells Zig to do so, by using an allocator to allocate some space in the heap. In <a href="#sec-allocators" class="quarto-xref"><span>Section 3.3</span></a>, I will present how you can use allocators to allocate memory in Zig.</p>
 <div class="callout callout-style-default callout-important callout-titled">
 <div class="callout-header d-flex align-content-center">
 <div class="callout-icon-container">
@@ -515,10 +515,10 @@ <h3 data-number="3.1.6" class="anchored" data-anchor-id="summary"><span class="h
 </section>
 <section id="sec-stack-overflow" class="level2" data-number="3.2">
 <h2 data-number="3.2" class="anchored" data-anchor-id="sec-stack-overflow"><span class="header-section-number">3.2</span> Stack overflows</h2>
-<p>Allocating memory on the stack is generally faster than allocating it on the heap. But this better performance comes with many restrictions. We have already discussed many of these restrictions of the stack at <a href="#sec-stack" class="quarto-xref"><span>Section 3.1.4</span></a>. But there is one more important limitation that I want to talk about, which is the size of the stack itself.</p>
+<p>Allocating memory on the stack is generally faster than allocating it on the heap. But this better performance comes with many restrictions. We have already discussed many of these restrictions of the stack in <a href="#sec-stack" class="quarto-xref"><span>Section 3.1.4</span></a>. But there is one more important limitation that I want to talk about, which is the size of the stack itself.</p>
 <p>The stack is limited in size. This size varies from computer to computer, and it depends on a lot of things (the computer architecture, the operating system, etc.). Nevertheless, this size is usually not that big. This is why we normally use the stack to store only temporary and small objects in memory.</p>
 <p>In essence, if you try to make an allocation on the stack, that is so big that exceeds the stack size limit, a <em>stack overflow</em> happens, and your program just crashes as a result of that. In other words, a stack overflow happens when you attempt to use more space than is available on the stack.</p>
-<p>This type of problem is very similar to a <em>buffer overflow</em>, i.e.&nbsp;you are trying to use more space than is available in the “buffer object”. However, a stack overflow always causes your program to crash, while a buffer overflow does not always cause your program to crash (although it often does).</p>
+<p>This type of problem is very similar to a <em>buffer overflow</em>, i.e., you are trying to use more space than is available in the “buffer object”. However, a stack overflow always causes your program to crash, while a buffer overflow does not always cause your program to crash (although it often does).</p>
 <p>You can see an example of a stack overflow in the example below. We are trying to allocate a very big array of <code>u64</code> values on the stack. You can see below that this program does not run successfully, because it crashed with a “segmentation fault” error message.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb5"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> very_big_alloc: [<span class="dv">1000</span> * <span class="dv">1000</span> * <span class="dv">24</span>]<span class="dt">u64</span> = <span class="cn">undefined</span>;</span>
@@ -558,13 +558,13 @@ <h3 data-number="3.3.1" class="anchored" data-anchor-id="what-are-allocators"><s
 </section>
 <section id="why-you-need-an-allocator" class="level3" data-number="3.3.2">
 <h3 data-number="3.3.2" class="anchored" data-anchor-id="why-you-need-an-allocator"><span class="header-section-number">3.3.2</span> Why you need an allocator?</h3>
-<p>As we described at <a href="#sec-stack" class="quarto-xref"><span>Section 3.1.4</span></a>, everytime you make a function call in Zig, a space in the stack is reserved for this function call. But the stack has a key limitation which is: every object stored in the stack has a known fixed length.</p>
+<p>As we described in <a href="#sec-stack" class="quarto-xref"><span>Section 3.1.4</span></a>, everytime you make a function call in Zig, a space in the stack is reserved for this function call. But the stack has a key limitation which is: every object stored in the stack has a known fixed length.</p>
 <p>But in reality, there are two very common instances where this “fixed length limitation” of the stack is a deal braker:</p>
 <ol type="1">
 <li>the objects that you create inside your function might grow in size during the execution of the function.</li>
-<li>sometimes, it is impossible to know upfront how many inputs you will receive, or how big this input will be.</li>
+<li>sometimes, it’s impossible to know upfront how many inputs you will receive, or how big this input will be.</li>
 </ol>
-<p>Also, there is another instance where you might want to use an allocator, which is when you want to write a function that returns a pointer to a local object. As I described at <a href="#sec-stack" class="quarto-xref"><span>Section 3.1.4</span></a>, you cannot do that if this local object is stored in the stack. However, if this object is stored in the heap, then, you can return a pointer to this object at the end of the function. Because you (the programmer) control the lifetime of any heap memory that you allocate. You decide when this memory gets destroyed/freed.</p>
+<p>Also, there is another instance where you might want to use an allocator, which is when you want to write a function that returns a pointer to a local object. As I described in <a href="#sec-stack" class="quarto-xref"><span>Section 3.1.4</span></a>, you cannot do that if this local object is stored in the stack. However, if this object is stored in the heap, then, you can return a pointer to this object at the end of the function. Because you (the programmer) control the lifetime of any heap memory that you allocate. You decide when this memory gets destroyed/freed.</p>
 <p>These are common situations for which the stack is not good. That is why you need a different memory management strategy to store these objects inside your function. You need to use a memory type that can grow together with your objects, or that you can control the lifetime of this memory. The heap fits this description.</p>
 <p>Allocating memory on the heap is commonly known as dynamic memory management. As the objects you create grow in size during the execution of your program, you grow the amount of memory you have by allocating more memory in the heap to store these objects. And you do that in Zig, by using an allocator object.</p>
 </section>
@@ -620,7 +620,7 @@ <h3 data-number="3.3.6" class="anchored" data-anchor-id="buffer-allocators"><spa
 <span id="cb10-9"><a href="#cb10-9" aria-hidden="true" tabindex="-1"></a><span class="kw">defer</span> allocator.free(input);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>Remember, the memory allocated by these allocator objects can be either from the stack, or, from the heap. It all depends on where the buffer object that you provide lives. In the above example, the <code>buffer</code> object lives in the stack, and, therefore, the memory allocated is based in the stack. But what if it was based on the heap?</p>
-<p>As we described at <a href="#sec-stack-overflow" class="quarto-xref"><span>Section 3.2</span></a>, one of the main reasons why you would use the heap, instead of the stack, is to allocate huge amounts of space to store very big objects. Thus, let’s suppose you wanted to use a very big buffer object as the basis for your allocator objects. You would have to allocate this very big buffer object on the heap. The example below demonstrates this case.</p>
+<p>As we described in <a href="#sec-stack-overflow" class="quarto-xref"><span>Section 3.2</span></a>, one of the main reasons why you would use the heap, instead of the stack, is to allocate huge amounts of space to store very big objects. Thus, let’s suppose you wanted to use a very big buffer object as the basis for your allocator objects. You would have to allocate this very big buffer object on the heap. The example below demonstrates this case.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb11"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> heap = std.heap.page_allocator;</span>
 <span id="cb11-2"><a href="#cb11-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> memory_buffer = <span class="kw">try</span> heap.alloc(</span>
@@ -638,7 +638,7 @@ <h3 data-number="3.3.6" class="anchored" data-anchor-id="buffer-allocators"><spa
 </section>
 <section id="sec-arena-allocator" class="level3" data-number="3.3.7">
 <h3 data-number="3.3.7" class="anchored" data-anchor-id="sec-arena-allocator"><span class="header-section-number">3.3.7</span> Arena allocator</h3>
-<p>The <code>ArenaAllocator()</code> is an allocator object that takes a child allocator as input. The idea behind the <code>ArenaAllocator()</code> in Zig is similar to the concept of “arenas” in the programming language Go<a href="#fn5" class="footnote-ref" id="fnref5" role="doc-noteref"><sup>5</sup></a>. It is an allocator object that allows you to allocate memory as many times you want, but free all memory only once. In other words, if you have, for example, called 5 times the method <code>alloc()</code> of an <code>ArenaAllocator()</code> object, you can free all the memory you allocated over these 5 calls at once, by simply calling the <code>deinit()</code> method of the same <code>ArenaAllocator()</code> object.</p>
+<p>The <code>ArenaAllocator()</code> is an allocator object that takes a child allocator as input. The idea behind the <code>ArenaAllocator()</code> in Zig is similar to the concept of “arenas” in the programming language Go<a href="#fn5" class="footnote-ref" id="fnref5" role="doc-noteref"><sup>5</sup></a>. It’s an allocator object that allows you to allocate memory as many times you want, but free all memory only once. In other words, if you have, for example, called 5 times the method <code>alloc()</code> of an <code>ArenaAllocator()</code> object, you can free all the memory you allocated over these 5 calls at once, by simply calling the <code>deinit()</code> method of the same <code>ArenaAllocator()</code> object.</p>
 <p>If you give, for example, a <code>GeneralPurposeAllocator()</code> object as input to the <code>ArenaAllocator()</code> constructor, like in the example below, then, the allocations you perform with <code>alloc()</code> will actually be made with the underlying object <code>GeneralPurposeAllocator()</code> that was passed. So, with an arena allocator, any new memory you ask for is allocated by the child allocator. The only thing that an arena allocator really does is help you to free all the memory you allocated multiple times with just a single command. In the example below, I called <code>alloc()</code> 3 times. So, if I did not use an arena allocator, then, I would need to call <code>free()</code> 3 times to free all the allocated memory.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb12"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> gpa = std.heap.GeneralPurposeAllocator(.<span class="op">{}</span>)<span class="op">{}</span>;</span>
@@ -656,8 +656,8 @@ <h3 data-number="3.3.7" class="anchored" data-anchor-id="sec-arena-allocator"><s
 <h3 data-number="3.3.8" class="anchored" data-anchor-id="the-alloc-and-free-methods"><span class="header-section-number">3.3.8</span> The <code>alloc()</code> and <code>free()</code> methods</h3>
 <p>In the code example below, we are accessing the <code>stdin</code>, which is the standard input channel, to receive an input from the user. We read the input given by the user with the <code>readUntilDelimiterOrEof()</code> method.</p>
 <p>Now, after reading the input of the user, we need to store this input somewhere in our program. That is why I use an allocator in this example. I use it to allocate some amount of memory to store this input given by the user. More specifically, the method <code>alloc()</code> of the allocator object is used to allocate an array capable of storing 50 <code>u8</code> values.</p>
-<p>Notice that this <code>alloc()</code> method receives two inputs. The first one, is a type. This defines what type of values the allocated array will store. In the example below, we are allocating an array of unsigned 8-bit integers (<code>u8</code>). But you can create an array to store any type of value you want. Next, on the second argument, we define the size of the allocated array, by specifying how many elements this array will contain. In the case below, we are allocating an array of 50 elements.</p>
-<p>At <a href="01-zig-weird.html#sec-zig-strings" class="quarto-xref"><span>Section 1.8</span></a> we described that strings in Zig are simply arrays of characters. Each character is represented by a <code>u8</code> value. So, this means that the array that was allocated in the object <code>input</code> is capable of storing a string that is 50-characters long.</p>
+<p>Notice that this <code>alloc()</code> method receives two inputs. The first one, is a type. This defines what type of values the allocated array will store. In the example below, we are allocating an array of unsigned 8-bit integers (<code>u8</code>). But you can create an array to store any type of value you want. Next, in the second argument, we define the size of the allocated array, by specifying how many elements this array will contain. In the case below, we are allocating an array of 50 elements.</p>
+<p>In <a href="01-zig-weird.html#sec-zig-strings" class="quarto-xref"><span>Section 1.8</span></a> we described that strings in Zig are simply arrays of characters. Each character is represented by a <code>u8</code> value. So, this means that the array that was allocated in the object <code>input</code> is capable of storing a string that is 50-characters long.</p>
 <p>So, in essence, the expression <code>var input: [50]u8 = undefined</code> would create an array for 50 <code>u8</code> values in the stack of the current scope. But, you can allocate the same array in the heap by using the expression <code>var input = try allocator.alloc(u8, 50)</code>.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb13"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
@@ -680,8 +680,8 @@ <h3 data-number="3.3.8" class="anchored" data-anchor-id="the-alloc-and-free-meth
 <span id="cb13-18"><a href="#cb13-18" aria-hidden="true" tabindex="-1"></a>    std.debug.print(<span class="st">"{s}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>input<span class="op">}</span>);</span>
 <span id="cb13-19"><a href="#cb13-19" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>Also, notice that in this example, we use the <code>defer</code> keyword (which I described at <a href="03-structs.html#sec-defer" class="quarto-xref"><span>Section 2.1.3</span></a>) to run a small piece of code at the end of the current scope, which is the expression <code>allocator.free(input)</code>. When you execute this expression, the allocator will free the memory that it allocated for the <code>input</code> object.</p>
-<p>We have talked about this at <a href="#sec-heap" class="quarto-xref"><span>Section 3.1.5</span></a>. You <strong>should always</strong> explicitly free any memory that you allocate using an allocator! You do that by using the <code>free()</code> method of the same allocator object you used to allocate this memory. The <code>defer</code> keyword is used in this example only to help us execute this free operation at the end of the current scope.</p>
+<p>Also, notice that in this example, we use the <code>defer</code> keyword (which I described in <a href="03-structs.html#sec-defer" class="quarto-xref"><span>Section 2.1.3</span></a>) to run a small piece of code at the end of the current scope, which is the expression <code>allocator.free(input)</code>. When you execute this expression, the allocator will free the memory that it allocated for the <code>input</code> object.</p>
+<p>We have talked about this in <a href="#sec-heap" class="quarto-xref"><span>Section 3.1.5</span></a>. You <strong>should always</strong> explicitly free any memory that you allocate using an allocator! You do that by using the <code>free()</code> method of the same allocator object you used to allocate this memory. The <code>defer</code> keyword is used in this example only to help us execute this free operation at the end of the current scope.</p>
 </section>
 <section id="the-create-and-destroy-methods" class="level3" data-number="3.3.9">
 <h3 data-number="3.3.9" class="anchored" data-anchor-id="the-create-and-destroy-methods"><span class="header-section-number">3.3.9</span> The <code>create()</code> and <code>destroy()</code> methods</h3>
diff --git a/docs/Chapters/01-zig-weird.html b/docs/Chapters/01-zig-weird.html
index 1f772abb..43f740f4 100644
--- a/docs/Chapters/01-zig-weird.html
+++ b/docs/Chapters/01-zig-weird.html
@@ -310,7 +310,7 @@ <h2 id="toc-title">Table of contents</h2>
   <li><a href="#sec-compile-project" id="toc-sec-compile-project" class="nav-link" data-scroll-target="#sec-compile-project"><span class="header-section-number">1.2.7</span> Compiling the entire project</a></li>
   </ul></li>
   <li><a href="#how-to-learn-zig" id="toc-how-to-learn-zig" class="nav-link" data-scroll-target="#how-to-learn-zig"><span class="header-section-number">1.3</span> How to learn Zig?</a></li>
-  <li><a href="#sec-assignments" id="toc-sec-assignments" class="nav-link" data-scroll-target="#sec-assignments"><span class="header-section-number">1.4</span> Creating new objects in Zig (i.e.&nbsp;identifiers)</a>
+  <li><a href="#sec-assignments" id="toc-sec-assignments" class="nav-link" data-scroll-target="#sec-assignments"><span class="header-section-number">1.4</span> Creating new objects in Zig (i.e., identifiers)</a>
   <ul class="collapse">
   <li><a href="#constant-objects-vs-variable-objects" id="toc-constant-objects-vs-variable-objects" class="nav-link" data-scroll-target="#constant-objects-vs-variable-objects"><span class="header-section-number">1.4.1</span> Constant objects vs variable objects</a></li>
   <li><a href="#declaring-without-an-initial-value" id="toc-declaring-without-an-initial-value" class="nav-link" data-scroll-target="#declaring-without-an-initial-value"><span class="header-section-number">1.4.2</span> Declaring without an initial value</a></li>
@@ -371,8 +371,10 @@ <h2 data-number="1.1" class="anchored" data-anchor-id="what-is-zig"><span class=
 <p>“Focus on debugging your application rather than debugging your programming language knowledge”.</p>
 </blockquote>
 <p>This phrase is specially true for C++ programmers. Because C++ is a gigantic language, with tons of features, and also, there are lots of different “flavors of C++”. These elements are what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction. Zig is a very simple language, more closely related to other simple languages such as C and Go.</p>
-<p>The phrase above is still important for C programmers too. Because, even C being a simple language, it is still hard sometimes to read and understand C code. For example, pre-processor macros in C are a frequent source of confusion. They really make it sometimes hard to debug C programs. Because macros are essentially a second language embedded in C that obscures your C code. With macros, you are no longer 100% sure about which pieces of the code are being sent to the compiler, i.e. they obscure the actual source code that you wrote.</p>
-<p>You don’t have macros in Zig. In Zig, the code you write, is the actual code that get’s compiled by the compiler. You also don’t have a hidden control flow happening behind the scenes. And, you also don’t have functions or operators from the standard library that make hidden memory allocations behind your back.</p>
+<p>The phrase above is still important for C programmers too. Because, even C being a simple</p>
+<p>language, it’s still hard sometimes to read and understand C code. For example, pre-processor macros in C are a frequent source of confusion. Sometimes, they really make it hard to debug</p>
+<p>C programs. Because macros are essentially a second language embedded in C that obscures your C code. With macros, you are no longer 100% sure about which pieces of the code are being sent to the compiler, i.e. they obscure the actual source code that you wrote.</p>
+<p>You don’t have macros in Zig. In Zig, the code you write, is the actual code that gets compiled by the compiler. You also don’t have a hidden control flow happening behind the scenes. And, you also don’t have functions or operators from the standard library that make hidden memory allocations behind your back.</p>
 <p>By being a simpler language, Zig becomes much more clear and easier to read/write, but at the same time, it also achieves a much more robust state, with more consistent behaviour in edge situations. Once again, less is more.</p>
 </section>
 <section id="hello-world-in-zig" class="level2" data-number="1.2">
@@ -389,7 +391,7 @@ <h2 data-number="1.2" class="anchored" data-anchor-id="hello-world-in-zig"><span
 <section id="sec-project-files" class="level3" data-number="1.2.1">
 <h3 data-number="1.2.1" class="anchored" data-anchor-id="sec-project-files"><span class="header-section-number">1.2.1</span> Understanding the project files</h3>
 <p>After you run the <code>init</code> command from the <code>zig</code> compiler, some new files are created inside of your current directory. First, a “source” (<code>src</code>) directory is created, containing two files, <code>main.zig</code> and <code>root.zig</code>. Each <code>.zig</code> file is a separate Zig module, which is simply a text file that contains some Zig code.</p>
-<p>By convention, the <code>main.zig</code> module is where your main function lives. Thus, if you are building an executable program in Zig, you need to declare a <code>main()</code> function, which represents the entrypoint of your program, i.e.&nbsp;it is where the execution of your program begins.</p>
+<p>By convention, the <code>main.zig</code> module is where your main function lives. Thus, if you are building an executable program in Zig, you need to declare a <code>main()</code> function, which represents the entrypoint of your program, i.e., where the execution of your program begins.</p>
 <p>However, if you are building a library (instead of an executable program), then, the normal procedure is to delete this <code>main.zig</code> file and start with the <code>root.zig</code> module. By convention, the <code>root.zig</code> module is the root source file of your library.</p>
 <div class="sourceCode" id="cb3"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="ex">tree</span> .</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <pre><code>.
@@ -400,11 +402,11 @@ <h3 data-number="1.2.1" class="anchored" data-anchor-id="sec-project-files"><spa
     └── root.zig
 
 1 directory, 4 files</code></pre>
-<p>The <code>init</code> command also creates two additional files in our working directory: <code>build.zig</code> and <code>build.zig.zon</code>. The first file (<code>build.zig</code>) represents a build script written in Zig. This script is executed when you call the <code>build</code> command from the <code>zig</code> compiler. In other words, this file contain Zig code that executes the necessary steps to build the entire project.</p>
+<p>The <code>init</code> command also creates two additional files in our working directory: <code>build.zig</code> and <code>build.zig.zon</code>. The first file (<code>build.zig</code>) represents a build script written in Zig. This script is executed when you call the <code>build</code> command from the <code>zig</code> compiler. In other words, this file contains Zig code that executes the necessary steps to build the entire project.</p>
 <p>Low-level languages normally use a compiler to build your source code into binary executables or binary libraries. Nevertheless, this process of compiling your source code and building binary executables or binary libraries from it, became a real challenge in the programming world, once the projects became bigger and bigger. As a result, programmers created “build systems”, which are a second set of tools designed to make this process of compiling and building complex projects, easier.</p>
 <p>Examples of build systems are CMake, GNU Make, GNU Autoconf and Ninja, which are used to build complex C and C++ projects. With these systems, you can write scripts, which are called “build scripts”. They simply are scripts that describes the necessary steps to compile/build your project.</p>
 <p>However, these are separate tools, that do not belong to C/C++ compilers, like <code>gcc</code> or <code>clang</code>. As a result, in C/C++ projects, you have not only to install and manage your C/C++ compilers, but you also have to install and manage these build systems separately.</p>
-<p>In Zig, we don’t need to use a separate set of tools to build our projects, because a build system is embedded inside the language itself. Therefore, Zig contains a native build system in it, and we can use this build system to write small scripts in Zig, which describes the necessary steps to build/compile our Zig project<a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>. So, everything you need to build a complex Zig project is the <code>zig</code> compiler, and nothing more.</p>
+<p>In Zig, we don’t need to use a separate set of tools to build our projects, because a build system is embedded inside the language itself. We can use this build system to write small scripts in Zig, which describe the necessary steps to build/compile our Zig project<a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>. So, everything you need to build a complex Zig project is the <code>zig</code> compiler, and nothing more.</p>
 <p>The second generated file (<code>build.zig.zon</code>) is a JSON-like file, in which you can describe your project, and also, declare a set of dependencies of your project that you want to fetch from the internet. In other words, you can use this <code>build.zig.zon</code> file to include a list of external libraries in your project.</p>
 <p>One possible way to include an external Zig library in your project, is to manually build and install the library in your system, and just link your source code with the library at the build step of your project.</p>
 <p>However, if this external Zig library is available on GitHub for example, and it has a valid <code>build.zig.zon</code> file in root folder of the project, which describes the project, you can easily include this library in your project by simply listing this external library in your <code>build.zig.zon</code> file.</p>
@@ -414,7 +416,7 @@ <h3 data-number="1.2.1" class="anchored" data-anchor-id="sec-project-files"><spa
 <h3 data-number="1.2.2" class="anchored" data-anchor-id="sec-root-file"><span class="header-section-number">1.2.2</span> The file <code>root.zig</code></h3>
 <p>Let’s take a look into the <code>root.zig</code> file. You might have noticed that every line of code with an expression ends with a semicolon (<code>;</code>). This follows the syntax of a C-family programming language<a href="#fn5" class="footnote-ref" id="fnref5" role="doc-noteref"><sup>5</sup></a>.</p>
 <p>Also, notice the <code>@import()</code> call at the first line. We use this built-in function to import functionality from other Zig modules into our current module. This <code>@import()</code> function works similarly to the <code>#include</code> pre-processor in C or C++, or, to the <code>import</code> statement in Python or Javascript code. In this example, we are importing the <code>std</code> module, which gives you access to the Zig Standard Library.</p>
-<p>In this <code>root.zig</code> file, we can also see how assignments (i.e.&nbsp;creating new objects) are made in Zig. You can create a new object in Zig by using the following syntax <code>(const|var) name = value;</code>. In the example below, we are creating two constant objects (<code>std</code> and <code>testing</code>). At <a href="#sec-assignments" class="quarto-xref"><span>Section 1.4</span></a> we talk more about objects in general.</p>
+<p>In this <code>root.zig</code> file, we can also see how assignments (i.e., creating new objects) are made in Zig. You can create a new object in Zig by using the syntax <code>(const|var) name = value;</code>. In the example below, we are creating two constant objects (<code>std</code> and <code>testing</code>). In <a href="#sec-assignments" class="quarto-xref"><span>Section 1.4</span></a> we talk more about objects in general.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb5"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> testing = std.testing;</span>
@@ -424,7 +426,7 @@ <h3 data-number="1.2.2" class="anchored" data-anchor-id="sec-root-file"><span cl
 <span id="cb5-6"><a href="#cb5-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>Functions in Zig are declared using the <code>fn</code> keyword. In this <code>root.zig</code> module, we are declaring a function called <code>add()</code>, which has two arguments named <code>a</code> and <code>b</code>. The function returns an integer of the type <code>i32</code> as result.</p>
-<p>Zig is a strongly-typed language. There are some specific situations where you can (if you want to) omit the type of an object in your code, if this type can be inferred by the <code>zig</code> compiler (we talk more about that at <a href="03-structs.html#sec-type-inference" class="quarto-xref"><span>Section 2.4</span></a>). But there are other situations where you do need to be explicit. For example, you do have to explicitly specify the type of each function argument, and also, the return type of every function that you create in Zig.</p>
+<p>Zig is a strongly-typed language. There are some specific situations where you can (if you want to) omit the type of an object in your code, if this type can be inferred by the <code>zig</code> compiler (we talk more about that in <a href="03-structs.html#sec-type-inference" class="quarto-xref"><span>Section 2.4</span></a>). But there are other situations where you do need to be explicit. For example, you do have to explicitly specify the type of each function argument, and also, the return type of every function that you create in Zig.</p>
 <p>We specify the type of an object or a function argument in Zig by using a colon character (<code>:</code>) followed by the type after the name of this object/function argument. With the expressions <code>a: i32</code> and <code>b: i32</code>, we know that both <code>a</code> and <code>b</code> arguments have type <code>i32</code>, which is a signed 32 bit integer. In this part, the syntax in Zig is identical to the syntax in Rust, which also specifies types by using the colon character.</p>
 <p>Lastly, we have the return type of the function at the end of the line, before we open the curly braces to start writing the function’s body. In the example above, this type is also a signed 32 bit integer (<code>i32</code>) value.</p>
 <p>Notice that we also have an <code>export</code> keyword before the function declaration. This keyword is similar to the <code>extern</code> keyword in C. It exposes the function to make it available in the library API. Therefore, if you are writing a library for other people to use, you have to expose the functions you write in the public API of this library by using this <code>export</code> keyword. If we removed the <code>export</code> keyword from the <code>add()</code> function declaration, then, this function would be no longer exposed in the library object built by the <code>zig</code> compiler.</p>
@@ -433,7 +435,7 @@ <h3 data-number="1.2.2" class="anchored" data-anchor-id="sec-root-file"><span cl
 <h3 data-number="1.2.3" class="anchored" data-anchor-id="sec-main-file"><span class="header-section-number">1.2.3</span> The <code>main.zig</code> file</h3>
 <p>Now that we have learned a lot about Zig’s syntax from the <code>root.zig</code> file, let’s take a look at the <code>main.zig</code> file. A lot of the elements we saw in <code>root.zig</code> are also present in <code>main.zig</code>. But there are some other elements that we haven’t seen yet, so let’s dive in.</p>
 <p>First, look at the return type of the <code>main()</code> function in this file. We can see a small change. The return type of the function (<code>void</code>) is accompanied by an exclamation mark (<code>!</code>). This exclamation mark tells us that this <code>main()</code> function might return an error.</p>
-<p>Is worth noting that, a <code>main()</code> function in Zig is allowed to return nothing (<code>void</code>), or an unsigned 8-bit integer (<code>u8</code>) value<a href="#fn6" class="footnote-ref" id="fnref6" role="doc-noteref"><sup>6</sup></a>, or an error. In other words, you can write your <code>main()</code> function in Zig to return essentially nothing (<code>void</code>), or, if you prefer, you can also write a more C-like <code>main()</code> function, which returns an integer value that usually serves as a “status code” for the process.</p>
+<p>It’s worth noting that, a <code>main()</code> function in Zig is allowed to return nothing (<code>void</code>), or an unsigned 8-bit integer (<code>u8</code>) value<a href="#fn6" class="footnote-ref" id="fnref6" role="doc-noteref"><sup>6</sup></a>, or an error. In other words, you can write your <code>main()</code> function in Zig to return essentially nothing (<code>void</code>), or, if you prefer, you can also write a more C-like <code>main()</code> function, which returns an integer value that usually serves as a “status code” for the process.</p>
 <p>In this example, the return type annotation of <code>main()</code> indicates that this function can either return nothing (<code>void</code>), or return an error. This exclamation mark in the return type annotation is an interesting and powerful feature of Zig. In summary, if you write a function and something inside the body of this function might return an error, then, you are forced to:</p>
 <ul>
 <li>either add the exclamation mark to the return type of the function and make it clear that this function might return an error.</li>
@@ -441,7 +443,7 @@ <h3 data-number="1.2.3" class="anchored" data-anchor-id="sec-main-file"><span cl
 </ul>
 <p>In most programming languages, we normally handle (or deal with) an error through a <em>try catch</em> pattern. Zig does have both <code>try</code> and <code>catch</code> keywords. But they work a little differently than what you’re probably used to in other languages.</p>
 <p>If we look at the <code>main()</code> function below, you can see that we do have a <code>try</code> keyword on the 5th line. But we do not have a <code>catch</code> keyword in this code. In Zig, we use the <code>try</code> keyword to execute an expression that might return an error, which, in this example, is the <code>stdout.print()</code> expression.</p>
-<p>In essence, the <code>try</code> keyword executes the expression <code>stdout.print()</code>. If this expression returns a valid value, then, the <code>try</code> keyword does absolutely nothing. It only passes the value forward. It is like if this <code>try</code> keyword was never there. However, if the expression does return an error, then, the <code>try</code> keyword will unwrap the error value, then, it returns this error from the function and also prints the current stack trace to <code>stderr</code>.</p>
+<p>In essence, the <code>try</code> keyword executes the expression <code>stdout.print()</code>. If this expression returns a valid value, then, the <code>try</code> keyword does absolutely nothing. It only passes the value forward. It’s like if this <code>try</code> keyword was never there. However, if the expression does return an error, then, the <code>try</code> keyword will unwrap the error value, then, it returns this error from the function and also prints the current stack trace to <code>stderr</code>.</p>
 <p>This might sound weird to you if you come from a high-level language. Because in high-level languages, such as Python, if an error occurs somewhere, this error is automatically returned and the execution of your program will automatically stop even if you don’t want to stop the execution. You are obligated to face the error.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb6"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
@@ -477,12 +479,12 @@ <h3 data-number="1.2.5" class="anchored" data-anchor-id="sec-compile-run-code"><
 <section id="important-note-for-windows-users" class="level3" data-number="1.2.6">
 <h3 data-number="1.2.6" class="anchored" data-anchor-id="important-note-for-windows-users"><span class="header-section-number">1.2.6</span> Important note for Windows users</h3>
 <p>First of all, this is a Windows-specific thing, and, therefore, does not apply to other operating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that includes some global variables whose initialization rely on runtime resources, then, you might have some troubles while trying to compile this Zig code on Windows.</p>
-<p>An example of that is accessing the <code>stdout</code> (i.e.&nbsp;the <em>standard output</em> of your system), which is usually done in Zig by using the expression <code>std.io.getStdOut()</code>. Thus, if you use this expression to instantiate a global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows, with a “unable to evaluate comptime expression” error message.</p>
-<p>This failure in the compilation process happens because all global variables in Zig are initialized at <em>compile-time</em>. However, operations like accessing the <code>stdout</code> (or opening a file) on Windows depends on resources that are available only at <em>runtime</em> (you will learn more about compile-time versus runtime at <a href="01-memory.html#sec-compile-time" class="quarto-xref"><span>Section 3.1.1</span></a>).</p>
+<p>An example of that is accessing the <code>stdout</code> (i.e., the <em>standard output</em> of your system), which is usually done in Zig by using the expression <code>std.io.getStdOut()</code>. If you use this expression to instantiate a global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows, with an “unable to evaluate comptime expression” error message.</p>
+<p>This failure in the compilation process happens because all global variables in Zig are initialized at <em>compile-time</em>. However, on Windows, operations like accessing the <code>stdout</code> (or opening a file) depend on resources that are available only at <em>runtime</em> (you will learn more about compile-time versus runtime in <a href="01-memory.html#sec-compile-time" class="quarto-xref"><span>Section 3.1.1</span></a>).</p>
 <p>For example, if you try to compile this code example on Windows, you will likely get the error message exposed below:</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb14"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb14-2"><a href="#cb14-2" aria-hidden="true" tabindex="-1"></a><span class="co">// ERROR! Compile-time error that emerge from</span></span>
+<span id="cb14-2"><a href="#cb14-2" aria-hidden="true" tabindex="-1"></a><span class="co">// ERROR! Compile-time error that emerges from</span></span>
 <span id="cb14-3"><a href="#cb14-3" aria-hidden="true" tabindex="-1"></a><span class="co">// this next line, on the `stdout` object</span></span>
 <span id="cb14-4"><a href="#cb14-4" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
 <span id="cb14-5"><a href="#cb14-5" aria-hidden="true" tabindex="-1"></a></span>
@@ -494,7 +496,7 @@ <h3 data-number="1.2.6" class="anchored" data-anchor-id="important-note-for-wind
     break :blk asm {
                ^~~</code></pre>
 <p>To avoid this problem on Windows, we need to force the <code>zig</code> compiler to instantiate this <code>stdout</code> object only at runtime, instead of instantiating it at compile-time. We can achieve that by simply moving the expression to a function body.</p>
-<p>This solves the problem because all expressions that are inside a function body in Zig are evaluated only at runtime, unless you use the <code>comptime</code> keyword explicitly to change this behaviour. You will learn more about this <code>comptime</code> keyword at <a href="10-stack-project.html#sec-comptime" class="quarto-xref"><span>Section 12.1</span></a>.</p>
+<p>This solves the problem because all expressions that are inside a function body in Zig are evaluated only at runtime, unless you use the <code>comptime</code> keyword explicitly to change this behaviour. You will learn more about this <code>comptime</code> keyword in <a href="10-stack-project.html#sec-comptime" class="quarto-xref"><span>Section 12.1</span></a>.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb16"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb16-2"><a href="#cb16-2" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
@@ -504,7 +506,8 @@ <h3 data-number="1.2.6" class="anchored" data-anchor-id="important-note-for-wind
 <span id="cb16-6"><a href="#cb16-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Hello</code></pre>
-<p>You can read more details about this Windows-specific limitation at a couple of GitHub issues opened at the official Zig repository. More specifically, the issues 17186 <a href="#fn7" class="footnote-ref" id="fnref7" role="doc-noteref"><sup>7</sup></a> and 19864 <a href="#fn8" class="footnote-ref" id="fnref8" role="doc-noteref"><sup>8</sup></a>.</p>
+<p>You can read more details about this Windows-specific limitation in a couple of GitHub issues opened at the official Zig repository. More specifically, the issues</p>
+<p>17186 <a href="#fn7" class="footnote-ref" id="fnref7" role="doc-noteref"><sup>7</sup></a> and 19864 <a href="#fn8" class="footnote-ref" id="fnref8" role="doc-noteref"><sup>8</sup></a>.</p>
 </section>
 <section id="sec-compile-project" class="level3" data-number="1.2.7">
 <h3 data-number="1.2.7" class="anchored" data-anchor-id="sec-compile-project"><span class="header-section-number">1.2.7</span> Compiling the entire project</h3>
@@ -552,7 +555,7 @@ <h2 data-number="1.3" class="anchored" data-anchor-id="how-to-learn-zig"><span c
 <li>Read the code written by one of the Zig core team members: <a href="https://github.com/kubkon" class="uri">https://github.com/kubkon</a>;</li>
 <li>Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <a href="https://www.youtube.com/@ZigSHOWTIME/videos" class="uri">https://www.youtube.com/@ZigSHOWTIME/videos</a>;</li>
 </ul>
-<p>Another great strategy to learn Zig, or honestly, to learn any language you want, is to practice it by solving exercises. For example, there is a famous repository in the Zig community called <a href="https://ziglings.org">Ziglings</a><a href="#fn18" class="footnote-ref" id="fnref18" role="doc-noteref"><sup>18</sup></a> , which contains more than 100 small exercises that you can solve. It is a repository of tiny programs written in Zig that are currently broken, and your responsibility is to fix these programs, and make them work again.</p>
+<p>Another great strategy to learn Zig, or honestly, to learn any language you want, is to practice it by solving exercises. For example, there is a famous repository in the Zig community called <a href="https://ziglings.org">Ziglings</a><a href="#fn18" class="footnote-ref" id="fnref18" role="doc-noteref"><sup>18</sup></a> , which contains more than 100 small exercises that you can solve. It’s a repository of tiny programs written in Zig that are currently broken, and your responsibility is to fix these programs, and make them work again.</p>
 <p>A famous tech YouTuber known as <em>The Primeagen</em> also posted some videos (on YouTube) where he solves these exercises from Ziglings. The first video is named <a href="https://www.youtube.com/watch?v=OPuztQfM3Fg&amp;t=2524s&amp;ab_channel=TheVimeagen">“Trying Zig Part 1”</a><a href="#fn19" class="footnote-ref" id="fnref19" role="doc-noteref"><sup>19</sup></a>.</p>
 <p>Another great alternative, is to solve the <a href="https://adventofcode.com/">Advent of Code exercises</a><a href="#fn20" class="footnote-ref" id="fnref20" role="doc-noteref"><sup>20</sup></a>. There are people that already took the time to learn and solve the exercises, and they posted their solutions on GitHub as well, so, in case you need some resource to compare while solving the exercises, you can look at these two repositories:</p>
 <ul>
@@ -561,7 +564,7 @@ <h2 data-number="1.3" class="anchored" data-anchor-id="how-to-learn-zig"><span c
 </ul>
 </section>
 <section id="sec-assignments" class="level2" data-number="1.4">
-<h2 data-number="1.4" class="anchored" data-anchor-id="sec-assignments"><span class="header-section-number">1.4</span> Creating new objects in Zig (i.e.&nbsp;identifiers)</h2>
+<h2 data-number="1.4" class="anchored" data-anchor-id="sec-assignments"><span class="header-section-number">1.4</span> Creating new objects in Zig (i.e., identifiers)</h2>
 <p>Let’s talk more about objects in Zig. Readers that have past experience with other programming languages might know this concept through a different name, such as: “variable” or “identifier”. In this book, I choose to use the term “object” to refer to this concept.</p>
 <p>To create a new object (or a new “identifier”) in Zig, we use the keywords <code>const</code> or <code>var</code>. These keywords specify if the object that you are creating is mutable or not. If you use <code>const</code>, then the object you are creating is a constant (or immutable) object, which means that once you declare this object, you can no longer change the value stored inside this object.</p>
 <p>On the other side, if you use <code>var</code>, then, you are creating a variable (or mutable) object. You can change the value of this object as many times you want. Using the keyword <code>var</code> in Zig is similar to using the keywords <code>let mut</code> in Rust.</p>
@@ -578,7 +581,7 @@ <h3 data-number="1.4.1" class="anchored" data-anchor-id="constant-objects-vs-var
     age = 25;
       ~~^~~</code></pre>
 <p>In contrast, if you use <code>var</code>, then, the object created is a variable object. With <code>var</code> you can declare this object in your source code, and then, change the value of this object how many times you want over future points in your source code.</p>
-<p>So, using the same code example exposed above, if I change the declaration of the <code>age</code> object to use the <code>var</code> keyword, then, the program gets compiled successfully. Because now, the <code>zig</code> compiler detects that we are changing the value of an object that allows this behaviour, because it is an “variable object”.</p>
+<p>So, using the same code example exposed above, if I change the declaration of the <code>age</code> object to use the <code>var</code> keyword, then, the program gets compiled successfully. Because now, the <code>zig</code> compiler detects that we are changing the value of an object that allows this behaviour, because it’s a “variable object”.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb23"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb23-1"><a href="#cb23-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> age: <span class="dt">u8</span> = <span class="dv">24</span>;</span>
 <span id="cb23-2"><a href="#cb23-2" aria-hidden="true" tabindex="-1"></a>age = <span class="dv">25</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
@@ -588,7 +591,7 @@ <h3 data-number="1.4.1" class="anchored" data-anchor-id="constant-objects-vs-var
 <h3 data-number="1.4.2" class="anchored" data-anchor-id="declaring-without-an-initial-value"><span class="header-section-number">1.4.2</span> Declaring without an initial value</h3>
 <p>By default, when you declare a new object in Zig, you must give it an initial value. In other words, this means that we have to declare, and, at the same time, initialize every object we create in our source code.</p>
 <p>On the other hand, you can, in fact, declare a new object in your source code, and not give it an explicit value. But we need to use a special keyword for that, which is the <code>undefined</code> keyword.</p>
-<p>Is important to emphasize that, you should avoid using <code>undefined</code> as much as possible. Because when you use this keyword, you leave your object uninitialized, and, as a consequence, if for some reason, your code use this object while it is uninitialized, then, you will definitely have undefined behaviour and major bugs in your program.</p>
+<p>It’s important to emphasize that, you should avoid using <code>undefined</code> as much as possible. Because when you use this keyword, you leave your object uninitialized, and, as a consequence, if for some reason, your code uses this object while it’s uninitialized, then, you will definitely have undefined behaviour and major bugs in your program.</p>
 <p>In the example below, I’m declaring the <code>age</code> object again. But this time, I do not give it an initial value. The variable is only initialized at the second line of code, where I store the number 25 in this object.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb24"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb24-1"><a href="#cb24-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> age: <span class="dt">u8</span> = <span class="cn">undefined</span>;</span>
@@ -599,7 +602,7 @@ <h3 data-number="1.4.2" class="anchored" data-anchor-id="declaring-without-an-in
 <section id="there-is-no-such-thing-as-unused-objects" class="level3" data-number="1.4.3">
 <h3 data-number="1.4.3" class="anchored" data-anchor-id="there-is-no-such-thing-as-unused-objects"><span class="header-section-number">1.4.3</span> There is no such thing as unused objects</h3>
 <p>Every object (being constant or variable) that you declare in Zig <strong>must be used in some way</strong>. You can give this object to a function call, as a function argument, or, you can use it in another expression to calculate the value of another object, or, you can call a method that belongs to this particular object.</p>
-<p>It doesn’t matter in which way you use it. As long as you use it. If you try to break this rule, i.e.&nbsp;if your try to declare a object, but not use it, the <code>zig</code> compiler will not compile your Zig source code, and it will issue a error message warning that you have unused objects in your code.</p>
+<p>It doesn’t matter in which way you use it. As long as you use it. If you try to break this rule, i.e., if your try to declare a object, but not use it, the <code>zig</code> compiler will not compile your Zig source code, and it will issue a error message warning that you have unused objects in your code.</p>
 <p>Let’s demonstrate this with an example. In the source code below, we declare a constant object called <code>age</code>. If you try to compile a simple Zig program with this line of code below, the compiler will return an error as demonstrated below:</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb25"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb25-1"><a href="#cb25-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> age = <span class="dv">15</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
@@ -619,7 +622,7 @@ <h3 data-number="1.4.3" class="anchored" data-anchor-id="there-is-no-such-thing-
 <span id="cb27-2"><a href="#cb27-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> age = <span class="dv">15</span>;</span>
 <span id="cb27-3"><a href="#cb27-3" aria-hidden="true" tabindex="-1"></a>_ = age;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>Now, remember, everytime you assign a particular object to the underscore, this object is essentially destroyed. It is discarded by the compiler. This means that you can no longer use this object further in your code. It doesn’t exist anymore.</p>
+<p>Now, remember, everytime you assign a particular object to the underscore, this object is essentially destroyed. It’s discarded by the compiler. This means that you can no longer use this object further in your code. It doesn’t exist anymore.</p>
 <p>So if you try to use the constant <code>age</code> in the example below, after we discarded it, you will get a loud error message from the compiler (talking about a “pointless discard”) warning you about this mistake.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb28"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb28-1"><a href="#cb28-1" aria-hidden="true" tabindex="-1"></a><span class="co">// It does not compile.</span></span>
@@ -630,7 +633,7 @@ <h3 data-number="1.4.3" class="anchored" data-anchor-id="there-is-no-such-thing-
 </div>
 <pre><code>t.zig:7:5: error: pointless discard
     of local constant</code></pre>
-<p>This same rule applies to variable objects. Every variable object must also be used in some way. And if you assign a variable object to the underscore, this object also get’s discarded, and you can no longer use this object.</p>
+<p>This same rule applies to variable objects. Every variable object must also be used in some way. And if you assign a variable object to the underscore, this object also gets discarded, and you can no longer use this object.</p>
 </section>
 <section id="you-must-mutate-every-variable-objects" class="level3" data-number="1.4.4">
 <h3 data-number="1.4.4" class="anchored" data-anchor-id="you-must-mutate-every-variable-objects"><span class="header-section-number">1.4.4</span> You must mutate every variable objects</h3>
@@ -660,7 +663,7 @@ <h2 data-number="1.5" class="anchored" data-anchor-id="sec-primitive-data-types"
 </section>
 <section id="sec-arrays" class="level2" data-number="1.6">
 <h2 data-number="1.6" class="anchored" data-anchor-id="sec-arrays"><span class="header-section-number">1.6</span> Arrays</h2>
-<p>You create arrays in Zig by using a syntax that resembles the C syntax. First, you specify the size of the array (i.e.&nbsp;the number of elements that will be stored in the array) you want to create inside a pair of brackets.</p>
+<p>You create arrays in Zig by using a syntax that resembles the C syntax. First, you specify the size of the array (i.e., the number of elements that will be stored in the array) you want to create inside a pair of brackets.</p>
 <p>Then, you specify the data type of the elements that will be stored inside this array. All elements present in an array in Zig must have the same data type. For example, you cannot mix elements of type <code>f32</code> with elements of type <code>i32</code> in the same array.</p>
 <p>After that, you simply list the values that you want to store in this array inside a pair of curly braces. In the example below, I am creating two constant objects that contain different arrays. The first object contains an array of 4 integer values, while the second object, an array of 3 floating point values.</p>
 <p>Now, you should notice that in the object <code>ls</code>, I am not explicitly specifying the size of the array inside of the brackets. Instead of using a literal value (like the value 4 that I used in the <code>ns</code> object), I am using the special character underscore (<code>_</code>). This syntax tells the <code>zig</code> compiler to fill this field with the number of elements listed inside of the curly braces. So, this syntax <code>[_]</code> is for lazy (or smart) programmers who leave the job of counting how many elements there are in the curly braces for the compiler.</p>
@@ -669,7 +672,7 @@ <h2 data-number="1.6" class="anchored" data-anchor-id="sec-arrays"><span class="
 <span id="cb32-2"><a href="#cb32-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ls = [_]<span class="dt">f64</span><span class="op">{</span><span class="fl">432.1</span>, <span class="fl">87.2</span>, <span class="fl">900.05</span><span class="op">}</span>;</span>
 <span id="cb32-3"><a href="#cb32-3" aria-hidden="true" tabindex="-1"></a>_ = ns; _ = ls;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>Is worth noting that these are static arrays, meaning that they cannot grow in size. Once you declare your array, you cannot change the size of it. This is very common in low level languages. Because low level languages normally wants to give you (the programmer) full control over memory, and the way in which arrays are expanded is tightly related to memory management.</p>
+<p>It’s worth noting that these are static arrays, meaning that they cannot grow in size. Once you declare your array, you cannot change the size of it. This is very common in low level languages. Because low level languages normally wants to give you (the programmer) full control over memory, and the way in which arrays are expanded is tightly related to memory management.</p>
 <section id="sec-select-array-elem" class="level3" data-number="1.6.1">
 <h3 data-number="1.6.1" class="anchored" data-anchor-id="sec-select-array-elem"><span class="header-section-number">1.6.1</span> Selecting elements of the array</h3>
 <p>One very common activity is to select specific portions of an array you have in your source code. In Zig, you can select a specific element from your array, by simply providing the index of this particular element inside brackets after the object name. In the example below, I am selecting the third element from the <code>ns</code> array. Notice that Zig is a “zero-index” based language, like C, C++, Rust, Python, and many other languages.</p>
@@ -688,7 +691,7 @@ <h3 data-number="1.6.1" class="anchored" data-anchor-id="sec-select-array-elem">
 <span id="cb35-3"><a href="#cb35-3" aria-hidden="true" tabindex="-1"></a>_ = sl;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>When you use the <code>start..end</code> syntax, the “end tail” of the range selector is non-inclusive, meaning that, the index at the end is not included in the range that is selected from the array. Therefore, the syntax <code>start..end</code> actually means <code>start..end - 1</code> in practice.</p>
-<p>You can for example, create a slice that goes from the first to the last elements of the array, by using <code>ar[0..ar.len]</code> syntax In other words, it is a slice that access all elements in the array.</p>
+<p>You can for example, create a slice that goes from the first to the last elements of the array, by using <code>ar[0..ar.len]</code> syntax In other words, it’s a slice that accesses all elements in the array.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb36"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb36-1"><a href="#cb36-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ar = [<span class="dv">4</span>]<span class="dt">u8</span><span class="op">{</span><span class="dv">48</span>, <span class="dv">24</span>, <span class="dv">12</span>, <span class="dv">6</span><span class="op">}</span>;</span>
 <span id="cb36-2"><a href="#cb36-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> sl = ar[<span class="dv">0</span>..ar.len];</span>
@@ -722,7 +725,7 @@ <h3 data-number="1.6.2" class="anchored" data-anchor-id="more-on-slices"><span c
 <section id="array-operators" class="level3" data-number="1.6.3">
 <h3 data-number="1.6.3" class="anchored" data-anchor-id="array-operators"><span class="header-section-number">1.6.3</span> Array operators</h3>
 <p>There are two array operators available in Zig that are very useful. The array concatenation operator (<code>++</code>), and the array multiplication operator (<code>**</code>). As the name suggests, these are array operators.</p>
-<p>One important detail about these two operators is that they work only when both operands have a size (or “length”) that is compile-time known. We are going to talk more about the differences between “compile-time known” and “runtime known” at <a href="01-memory.html#sec-compile-time" class="quarto-xref"><span>Section 3.1.1</span></a>. But for now, keep this information in mind, that you cannot use these operators in every situation.</p>
+<p>One important detail about these two operators is that they work only when both operands have a size (or “length”) that is compile-time known. We are going to talk more about the differences between “compile-time known” and “runtime known” in <a href="01-memory.html#sec-compile-time" class="quarto-xref"><span>Section 3.1.1</span></a>. But for now, keep this information in mind, that you cannot use these operators in every situation.</p>
 <p>In summary, the <code>++</code> operator creates a new array that is the concatenation, of both arrays provided as operands. So, the expression <code>a ++ b</code> produces a new array which contains all the elements from arrays <code>a</code> and <code>b</code>.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb40"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb40-1"><a href="#cb40-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> a = [_]<span class="dt">u8</span><span class="op">{</span><span class="dv">1</span>,<span class="dv">2</span>,<span class="dv">3</span><span class="op">}</span>;</span>
@@ -733,7 +736,7 @@ <h3 data-number="1.6.3" class="anchored" data-anchor-id="array-operators"><span
 <pre><code>{ 1, 2, 3, 4, 5 }</code></pre>
 </div>
 </div>
-<p>This <code>++</code> operator is particularly useful to concatenate strings together. Strings in Zig are described in depth at <a href="#sec-zig-strings" class="quarto-xref"><span>Section 1.8</span></a>. In summary, a string object in Zig is essentially an arrays of bytes. So, you can use this array concatenation operator to effectively concatenate strings together.</p>
+<p>This <code>++</code> operator is particularly useful to concatenate strings together. Strings in Zig are described in depth in <a href="#sec-zig-strings" class="quarto-xref"><span>Section 1.8</span></a>. In summary, a string object in Zig is essentially an arrays of bytes. So, you can use this array concatenation operator to effectively concatenate strings together.</p>
 <p>In contrast, the <code>**</code> operator is used to replicate an array multiple times. In other words, the expression <code>a ** 3</code> creates a new array which contains the elements of the array <code>a</code> repeated 3 times.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb42"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb42-1"><a href="#cb42-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> a = [_]<span class="dt">u8</span><span class="op">{</span><span class="dv">1</span>,<span class="dv">2</span>,<span class="dv">3</span><span class="op">}</span>;</span>
@@ -746,10 +749,10 @@ <h3 data-number="1.6.3" class="anchored" data-anchor-id="array-operators"><span
 </section>
 <section id="runtime-versus-compile-time-known-length-in-slices" class="level3" data-number="1.6.4">
 <h3 data-number="1.6.4" class="anchored" data-anchor-id="runtime-versus-compile-time-known-length-in-slices"><span class="header-section-number">1.6.4</span> Runtime versus compile-time known length in slices</h3>
-<p>We are going to talk a lot about the differences between compile-time known and runtime known across this book, especially at <a href="01-memory.html#sec-compile-time" class="quarto-xref"><span>Section 3.1.1</span></a>. But the basic idea is that a thing is compile-time known, when we know everything (the value, the attributes and the characteristics) about this thing at compile-time. In contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime. Therefore, we don’t know the value of this thing at compile-time, only at runtime.</p>
-<p>We have learned at <a href="#sec-select-array-elem" class="quarto-xref"><span>Section 1.6.1</span></a> that slices are created by using a <em>range selector</em>, which represents a range of indexes. When this “range of indexes” (i.e.&nbsp;the start and the end of this range) is known at compile-time, the slice object that get’s created is actually, under the hood, just a single-item pointer to an array.</p>
-<p>You don’t need to precisely understand what that means now. We are going to talk a lot about pointers at <a href="05-pointers.html" class="quarto-xref"><span>Chapter 6</span></a>. For now, just understand that, when the range of indexes is known at compile-time, the slice that get’s created is just a pointer to an array, accompanied by a length value that tells the size of the slice.</p>
-<p>If you have a slice object like this, i.e.&nbsp;a slice that has a compile-time known range, you can use common pointer operations over this slice object. For example, you can dereference the pointer of this slice, by using the <code>.*</code> method, like you would do on a normal pointer object.</p>
+<p>We are going to talk a lot about the differences between compile-time known and runtime known across this book, especially in <a href="01-memory.html#sec-compile-time" class="quarto-xref"><span>Section 3.1.1</span></a>. But the basic idea is that a thing is compile-time known, when we know everything (the value, the attributes and the characteristics) about this thing at compile-time. In contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime. Therefore, we don’t know the value of this thing at compile-time, only at runtime.</p>
+<p>We have learned in <a href="#sec-select-array-elem" class="quarto-xref"><span>Section 1.6.1</span></a> that slices are created by using a <em>range selector</em>, which represents a range of indexes. When this “range of indexes” (i.e., the start and the end of this range) is known at compile-time, the slice object that gets created is actually, under the hood, just a single-item pointer to an array.</p>
+<p>You don’t need to precisely understand what that means now. We are going to talk a lot about pointers in <a href="05-pointers.html" class="quarto-xref"><span>Chapter 6</span></a>. For now, just understand that, when the range of indexes is known at compile-time, the slice that gets created is just a pointer to an array, accompanied by a length value that tells the size of the slice.</p>
+<p>If you have a slice object like this, i.e., a slice that has a compile-time known range, you can use common pointer operations over this slice object. For example, you can dereference the pointer of this slice, by using the <code>.*</code> method, like you would do on a normal pointer object.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb44"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb44-1"><a href="#cb44-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> arr1 = [<span class="dv">10</span>]<span class="dt">u64</span> <span class="op">{</span></span>
 <span id="cb44-2"><a href="#cb44-2" aria-hidden="true" tabindex="-1"></a>    <span class="dv">1</span>, <span class="dv">2</span>, <span class="dv">3</span>, <span class="dv">4</span>, <span class="dv">5</span>,</span>
@@ -759,7 +762,7 @@ <h3 data-number="1.6.4" class="anchored" data-anchor-id="runtime-versus-compile-
 <span id="cb44-6"><a href="#cb44-6" aria-hidden="true" tabindex="-1"></a><span class="co">// Because we know both the start and end of the range.</span></span>
 <span id="cb44-7"><a href="#cb44-7" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> slice = arr1[<span class="dv">1</span>..<span class="dv">4</span>];</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>On the other hand, if the range of indexes is not known at compile time, then, the slice object that get’s created is not a pointer anymore, and, thus, it does not support pointer operations. For example, maybe the start index is known at compile time, but the end index is not. In such case, the range of the slice becomes runtime known only.</p>
+<p>On the other hand, if the range of indexes is not known at compile time, then, the slice object that gets created is not a pointer anymore, and, thus, it does not support pointer operations. For example, maybe the start index is known at compile time, but the end index is not. In such case, the range of the slice becomes runtime known only.</p>
 <p>In the example below, the <code>slice</code> object have a runtime known range, because the end index of the range is not known at compile time. In other words, the size of the array at <code>buffer</code> is not known at compile time. When we execute this program, the size of the array might be 10, or, it might be 12 depending on where we execute it. Therefore, we don’t know at compile time if the slice object have a range of size 10, or, a range of size 12.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb45"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb45-1"><a href="#cb45-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
@@ -786,7 +789,7 @@ <h2 data-number="1.7" class="anchored" data-anchor-id="sec-blocks"><span class="
 <p>Blocks are created in Zig by a pair of curly braces. A block is just a group of expressions (or statements) contained inside of a pair of curly braces. All of these expressions that are contained inside of this pair of curly braces belongs to the same scope.</p>
 <p>In other words, a block just delimits a scope in your code. The objects that you define inside the same block belongs to the same scope, and, therefore, are accessible from within this scope. At the same time, these objects are not accessible outside of this scope. So, you could also say that blocks are used to limit the scope of the objects that you create in your source code. In less technical terms, blocks are used to specify where in your source code you can access whatever object you have in your source code.</p>
 <p>So, a block is just a group of expressions contained inside a pair of curly braces. And every block have its own scope separated from the others. The body of a function is a classic example of a block. If statements, for and while loops (and any other structure in the language that uses the pair of curly braces) are also examples of blocks.</p>
-<p>This means that, every if statement, or for loop, etc., that you create in your source code have its own separate scope. That is why you can’t access the objects that you defined inside of your for loop (or if statement) in an outer scope, i.e.&nbsp;a scope outside of the for loop. Because you are trying to access an object that belongs to a scope that is different than your current scope.</p>
+<p>This means that, every if statement, or for loop, etc., that you create in your source code have its own separate scope. That is why you can’t access the objects that you defined inside of your for loop (or if statement) in an outer scope, i.e., a scope outside of the for loop. Because you are trying to access an object that belongs to a scope that is different than your current scope.</p>
 <p>You can create blocks within blocks, with multiple levels of nesting. You can also (if you want to) give a label to a particular block, with the colon character (<code>:</code>). Just write <code>label:</code> before you open the pair of curly braces that delimits your block. When you label a block in Zig, you can use the <code>break</code> keyword to return a value from this block, like as if it was a function’s body. You just write the <code>break</code> keyword, followed by the block label in the format <code>:label</code>, and the expression that defines the value that you want to return.</p>
 <p>Like in the example below, where we are returning the value from the <code>y</code> object from the block <code>add_one</code>, and saving the result inside the <code>x</code> object.</p>
 <div class="cell">
@@ -811,9 +814,9 @@ <h2 data-number="1.8" class="anchored" data-anchor-id="sec-zig-strings"><span cl
 <li>String literal values.</li>
 <li>String objects.</li>
 </ul>
-<p>A string literal value is just a pointer to a null-terminated array of bytes (i.e.&nbsp;similar to a C string). But in Zig, a string literal value also embeds the length of the string into the data type of the value itself. Therefore, a string literal value have a data type in the format <code>*const [n:0]u8</code>. The <code>n</code> in the data type indicates the size of the string.</p>
-<p>On the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes, or, in other words, a slice of <code>u8</code> values (slices were presented at <a href="#sec-arrays" class="quarto-xref"><span>Section 1.6</span></a>). Thus, a string object have a data type of <code>[]u8</code> or <code>[]const u8</code>, depending if the string object is marked as constant with <code>const</code>, or as variable with <code>var</code>.</p>
-<p>Because a string object is essentially a slice, it means that a string object always contains two things: a pointer to an array of bytes (i.e.&nbsp;<code>u8</code> values) that represents the string value; and also, a length value, which specifies the size of the slice, or, how many elements there is in the slice. Is worth to emphasize that the array of bytes in a string object is not null-terminated, like in a string literal value.</p>
+<p>A string literal value is just a pointer to a null-terminated array of bytes (i.e., similar to a C string). But in Zig, a string literal value also embeds the length of the string into the data type of the value itself. Therefore, a string literal value have a data type in the format <code>*const [n:0]u8</code>. The <code>n</code> in the data type indicates the size of the string.</p>
+<p>On the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes, or, in other words, a slice of <code>u8</code> values (slices were presented in <a href="#sec-arrays" class="quarto-xref"><span>Section 1.6</span></a>). Thus, a string object have a data type of <code>[]u8</code> or <code>[]const u8</code>, depending if the string object is marked as constant with <code>const</code>, or as variable with <code>var</code>.</p>
+<p>Because a string object is essentially a slice, it means that a string object always contains two things: a pointer to an array of bytes (i.e., <code>u8</code> values) that represents the string value; and also, a length value, which specifies the size of the slice, or, how many elements there is in the slice. It’s worth to emphasize that the array of bytes in a string object is not null-terminated, like in a string literal value.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb48"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb48-1"><a href="#cb48-1" aria-hidden="true" tabindex="-1"></a><span class="co">// This is a string literal value:</span></span>
 <span id="cb48-2"><a href="#cb48-2" aria-hidden="true" tabindex="-1"></a><span class="st">"A literal value"</span>;</span>
@@ -821,7 +824,7 @@ <h2 data-number="1.8" class="anchored" data-anchor-id="sec-zig-strings"><span cl
 <span id="cb48-4"><a href="#cb48-4" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> object: []<span class="kw">const</span> <span class="dt">u8</span> = <span class="st">"A string object"</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>Zig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every sequence of bytes you’re working with, but is not really Zig’s job to fix the encoding of your strings (you can use <a href="https://www.gnu.org/software/libiconv/"><code>iconv</code></a><a href="#fn22" class="footnote-ref" id="fnref22" role="doc-noteref"><sup>22</sup></a> for that). Today, most of the text in our modern world, especially on the web, should be UTF-8 encoded. So if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.</p>
-<p>Let’s take for example the word “Hello”. In UTF-8, this sequence of characters (H, e, l, l, o) is represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this sequence is <code>0x48</code>, <code>0x65</code>, <code>0x6C</code>, <code>0x6C</code>, <code>0x6F</code>. So if I take this sequence of hexadecimal values, and ask Zig to print this sequence of bytes as a sequence of characters (i.e.&nbsp;a string), then, the text “Hello” will be printed into the terminal:</p>
+<p>Let’s take for example the word “Hello”. In UTF-8, this sequence of characters (H, e, l, l, o) is represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this sequence is <code>0x48</code>, <code>0x65</code>, <code>0x6C</code>, <code>0x6C</code>, <code>0x6F</code>. So if I take this sequence of hexadecimal values, and ask Zig to print this sequence of bytes as a sequence of characters (i.e., a string), then, the text “Hello” will be printed into the terminal:</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb49"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb49-1"><a href="#cb49-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb49-2"><a href="#cb49-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
@@ -854,7 +857,7 @@ <h2 data-number="1.8" class="anchored" data-anchor-id="sec-zig-strings"><span cl
 <section id="strings-in-c" class="level3" data-number="1.8.1">
 <h3 data-number="1.8.1" class="anchored" data-anchor-id="strings-in-c"><span class="header-section-number">1.8.1</span> Strings in C</h3>
 <p>At first glance, a string literal value in Zig looks very similar to how C treats strings as well. In more details, string values in C are treated internally as an array of arbitrary bytes, and this array is also null-terminated.</p>
-<p>But one key difference between a Zig string literal and a C string, is that Zig also stores the length of the string inside the object itself. In the case of a string literal value, this length is stored in the data type of the value (i.e.&nbsp;the <code>n</code> variable in <code>[n:0]u8</code>). While, in a string object, the length is stored in the <code>len</code> attribute of the slice that represents the string object. This small detail makes your code safer, because it is much easier for the Zig compiler to check if you are trying to access an element that is “out of bounds”, i.e.&nbsp;if your trying to access memory that does not belong to you.</p>
+<p>But one key difference between a Zig string literal and a C string, is that Zig also stores the length of the string inside the object itself. In the case of a string literal value, this length is stored in the data type of the value (i.e., the <code>n</code> variable in <code>[n:0]u8</code>). While, in a string object, the length is stored in the <code>len</code> attribute of the slice that represents the string object. This small detail makes your code safer, because it’s much easier for the Zig compiler to check if you are trying to access an element that is “out of bounds”, i.e., if your trying to access memory that does not belong to you.</p>
 <p>To achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless. So getting this kind of safety is not automatic and much harder to do in C. For example, if you want to track the length of your string throughout your program in C, then, you first need to loop through the array of bytes that represents this string, and find the null element (<code>'\0'</code>) position to discover where exactly the array ends, or, in other words, to find how much elements the array of bytes contain.</p>
 <p>To do that, you would need something like this in C. In this example, the C string stored in the object <code>array</code> is 25 bytes long:</p>
 <div class="cell">
@@ -890,7 +893,7 @@ <h3 data-number="1.8.2" class="anchored" data-anchor-id="a-better-look-at-the-ob
 <p>Now, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the <code>@TypeOf()</code> function. If we look at the type of the <code>simple_array</code> object below, you will find that this object is an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type <code>i32</code> in Zig. That is what an object of type <code>[4]i32</code> is.</p>
 <p>But if we look closely at the type of the string literal value exposed below, you will find that this object is a constant pointer (hence the <code>*const</code> annotation) to an array of 16 elements (or 16 bytes). Each element is a single byte (more precisely, an unsigned 8 bit integer - <code>u8</code>), that is why we have the <code>[16:0]u8</code> portion of the type below. In other words, the string literal value exposed below is 16 bytes long.</p>
 <p>Now, if we create an pointer to the <code>simple_array</code> object, then, we get a constant pointer to an array of 4 elements (<code>*const [4]i32</code>), which is very similar to the type of the string literal value. This demonstrates that a string literal value in Zig is already a pointer to a null-terminated array of bytes.</p>
-<p>Furthermore, if we take a look at the type of the <code>string_obj</code> object, you will see that it is a slice object (hence the <code>[]</code> portion of the type) to a sequence of constant <code>u8</code> values (hence the <code>const u8</code> portion of the type).</p>
+<p>Furthermore, if we take a look at the type of the <code>string_obj</code> object, you will see that it’s a slice object (hence the <code>[]</code> portion of the type) to a sequence of constant <code>u8</code> values (hence the <code>const u8</code> portion of the type).</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb57"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb57-1"><a href="#cb57-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb57-2"><a href="#cb57-2" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
@@ -921,7 +924,7 @@ <h3 data-number="1.8.2" class="anchored" data-anchor-id="a-better-look-at-the-ob
 </section>
 <section id="byte-vs-unicode-points" class="level3" data-number="1.8.3">
 <h3 data-number="1.8.3" class="anchored" data-anchor-id="byte-vs-unicode-points"><span class="header-section-number">1.8.3</span> Byte vs unicode points</h3>
-<p>Is important to point out that each byte in the array is not necessarily a single character. This fact arises from the difference between a single byte and a single unicode point.</p>
+<p>It’s important to point out that each byte in the array is not necessarily a single character. This fact arises from the difference between a single byte and a single unicode point.</p>
 <p>The encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in the string. For example, the character “H” is stored in UTF-8 as the decimal number 72. This means that the number 72 is the unicode point for the character “H”. Each possible character that can appear in a UTF-8 encoded string have its own unicode point.</p>
 <p>For example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point) 570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which is 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why, the unicode point 570 is actually stored inside the computer’s memory as the bytes <code>C8 BA</code>.</p>
 <div class="cell">
@@ -1053,22 +1056,22 @@ <h2 data-number="1.9" class="anchored" data-anchor-id="safety-in-zig"><span clas
 <h2 data-number="1.10" class="anchored" data-anchor-id="other-parts-of-zig"><span class="header-section-number">1.10</span> Other parts of Zig</h2>
 <p>We already learned a lot about Zig’s syntax, and also, some pretty technical details about it. Just as a quick recap:</p>
 <ul>
-<li>We talked about how functions are written in Zig at <a href="#sec-root-file" class="quarto-xref"><span>Section 1.2.2</span></a> and <a href="#sec-main-file" class="quarto-xref"><span>Section 1.2.3</span></a>.</li>
-<li>How to create new objects/identifiers at <a href="#sec-root-file" class="quarto-xref"><span>Section 1.2.2</span></a> and especially at <a href="#sec-assignments" class="quarto-xref"><span>Section 1.4</span></a>.</li>
-<li>How strings work in Zig at <a href="#sec-zig-strings" class="quarto-xref"><span>Section 1.8</span></a>.</li>
-<li>How to use arrays and slices at <a href="#sec-arrays" class="quarto-xref"><span>Section 1.6</span></a>.</li>
-<li>How to import functionality from other Zig modules at <a href="#sec-root-file" class="quarto-xref"><span>Section 1.2.2</span></a>.</li>
+<li>We talked about how functions are written in Zig in <a href="#sec-root-file" class="quarto-xref"><span>Section 1.2.2</span></a> and <a href="#sec-main-file" class="quarto-xref"><span>Section 1.2.3</span></a>.</li>
+<li>How to create new objects/identifiers in <a href="#sec-root-file" class="quarto-xref"><span>Section 1.2.2</span></a> and especially in <a href="#sec-assignments" class="quarto-xref"><span>Section 1.4</span></a>.</li>
+<li>How strings work in Zig in <a href="#sec-zig-strings" class="quarto-xref"><span>Section 1.8</span></a>.</li>
+<li>How to use arrays and slices in <a href="#sec-arrays" class="quarto-xref"><span>Section 1.6</span></a>.</li>
+<li>How to import functionality from other Zig modules in <a href="#sec-root-file" class="quarto-xref"><span>Section 1.2.2</span></a>.</li>
 </ul>
 <p>But, for now, this amount of knowledge is enough for us to continue with this book. Later, over the next chapters we will still talk more about other parts of Zig’s syntax that are also equally important. Such as:</p>
 <ul>
-<li>How Object-Oriented programming can be done in Zig through <em>struct declarations</em> at <a href="03-structs.html#sec-structs-and-oop" class="quarto-xref"><span>Section 2.3</span></a>.</li>
-<li>Basic control flow syntax at <a href="03-structs.html#sec-zig-control-flow" class="quarto-xref"><span>Section 2.1</span></a>.</li>
-<li>Enums at <a href="04-http-server.html#sec-enum" class="quarto-xref"><span>Section 7.6</span></a>;</li>
-<li>Pointers and Optionals at <a href="05-pointers.html" class="quarto-xref"><span>Chapter 6</span></a>;</li>
-<li>Error handling with <code>try</code> and <code>catch</code> at <a href="09-error-handling.html" class="quarto-xref"><span>Chapter 10</span></a>;</li>
-<li>Unit tests at <a href="03-unittests.html" class="quarto-xref"><span>Chapter 8</span></a>;</li>
-<li>Vectors at <a href="15-vectors.html" class="quarto-xref"><span>Chapter 17</span></a>;</li>
-<li>Build System at <a href="07-build-system.html" class="quarto-xref"><span>Chapter 9</span></a>;</li>
+<li>How Object-Oriented programming can be done in Zig through <em>struct declarations</em> in <a href="03-structs.html#sec-structs-and-oop" class="quarto-xref"><span>Section 2.3</span></a>.</li>
+<li>Basic control flow syntax in <a href="03-structs.html#sec-zig-control-flow" class="quarto-xref"><span>Section 2.1</span></a>.</li>
+<li>Enums in <a href="04-http-server.html#sec-enum" class="quarto-xref"><span>Section 7.6</span></a>;</li>
+<li>Pointers and Optionals in <a href="05-pointers.html" class="quarto-xref"><span>Chapter 6</span></a>;</li>
+<li>Error handling with <code>try</code> and <code>catch</code> in <a href="09-error-handling.html" class="quarto-xref"><span>Chapter 10</span></a>;</li>
+<li>Unit tests in <a href="03-unittests.html" class="quarto-xref"><span>Chapter 8</span></a>;</li>
+<li>Vectors in <a href="15-vectors.html" class="quarto-xref"><span>Chapter 17</span></a>;</li>
+<li>Build System in <a href="07-build-system.html" class="quarto-xref"><span>Chapter 9</span></a>;</li>
 </ul>
 
 
diff --git a/docs/Chapters/02-debugging.html b/docs/Chapters/02-debugging.html
index 89a8ac20..c55d2296 100644
--- a/docs/Chapters/02-debugging.html
+++ b/docs/Chapters/02-debugging.html
@@ -314,8 +314,8 @@ <h1 class="title"><span class="chapter-number">5</span>&nbsp; <span class="chapt
 <section id="print-debugging" class="level2" data-number="5.1">
 <h2 data-number="5.1" class="anchored" data-anchor-id="print-debugging"><span class="header-section-number">5.1</span> Print debugging</h2>
 <p>We begin with the classic and battle-tested <em>print debugging</em> strategy. The key advantage that debugging offers you is <em>visibility</em>. With <em>print statements</em> you can easily see what results and objects are being produced by your application.</p>
-<p>That is the essence of <em>print debugging</em>. Is to use print expressions to see the values that are being generated by your program, and, as a result, get a much better understanding of how your program is behaving.</p>
-<p>Many programmers often resort to the print functions in Zig, such as the <code>stdout.print()</code>, or, the <code>std.debug.print()</code>, to get a better understanding of their programs. This is a known and old strategy that is very simple and effective, and it is better known within the programming community as <em>print debugging</em>. In Zig, you can print information to the <code>stdout</code> or <code>stderr</code> streams of your system.</p>
+<p>This is the essence of <em>print debugging</em> - using print expressions to see the values that are being generated by your program, and, as a result, get a much better understanding of how your program is behaving.</p>
+<p>Many programmers often resort to the print functions in Zig, such as the <code>stdout.print()</code>, or, the <code>std.debug.print()</code>, to get a better understanding of their programs. This is a known and old strategy that is very simple and effective, and it’s better known within the programming community as <em>print debugging</em>. In Zig, you can print information to the <code>stdout</code> or <code>stderr</code> streams of your system.</p>
 <p>Let’s begin with <code>stdout</code>. First, you need to get access to the <code>stdout</code>, by calling the <code>getStdOut()</code> method, from the Zig Standard Library. This method returns a <em>file descriptor</em> object, and, through this object you can read/write to the <code>stdout</code>. I recommend you to check out all methods available in this object, by <a href="https://ziglang.org/documentation/master/std/#std.fs.File">checking the page in the Zig Standard Library Official Reference for the type <code>File</code></a><a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>.</p>
 <p>For our purpose here, which is to write something to the <code>stdout</code>, especially to debug our program, I recommend you to use the <code>writer()</code> method, which gives you a <em>writer</em> object. This <em>writer</em> object offers some helper methods to write stuff into the file descriptor object that represents the <code>stdout</code> stream. In special, the <code>print()</code> method.</p>
 <p>The <code>print()</code> method from this <em>writer</em> object is a “print formatter” type of a function. In other words, this method works exactly like the <code>printf()</code> function from C, or, like <code>println!()</code> from Rust. In the first argument of the function, you specify a template string, and, in the second argument, you provide a list of values (or objects) that you want to insert into your template message.</p>
@@ -327,7 +327,7 @@ <h2 data-number="5.1" class="anchored" data-anchor-id="print-debugging"><span cl
 <li><code>s</code>: for printing strings.</li>
 <li><code>p</code>: for printing memory addresses.</li>
 <li><code>x</code>: for printing hexadecimal values.</li>
-<li><code>any</code>: use any compatible format specifier (i.e.&nbsp;it automatically selects a format specifier for you).</li>
+<li><code>any</code>: use any compatible format specifier (i.e., it automatically selects a format specifier for you).</li>
 </ul>
 <p>The code example below gives you an example of use of this <code>print()</code> method with the <code>d</code> format specifier.</p>
 <div class="cell">
@@ -345,7 +345,7 @@ <h2 data-number="5.1" class="anchored" data-anchor-id="print-debugging"><span cl
 <pre><code>Result: 50</code></pre>
 </div>
 </div>
-<p>It is important to emphasize that, the <code>stdout.print()</code> method, as you would expect, prints your template string into the <code>stdout</code> stream of your system. However, you can also print your template string into the <code>stderr</code> stream if your prefer. All you need to do, is to replace the <code>stdout.print()</code> call with the function <code>std.debug.print()</code>. Like this:</p>
+<p>It’s important to emphasize that, the <code>stdout.print()</code> method, as you would expect, prints your template string into the <code>stdout</code> stream of your system. However, you can also print your template string into the <code>stderr</code> stream if your prefer. All you need to do, is to replace the <code>stdout.print()</code> call with the function <code>std.debug.print()</code>. Like this:</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb3"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb3-2"><a href="#cb3-2" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> add(x: <span class="dt">u8</span>, y: <span class="dt">u8</span>) <span class="dt">u8</span> <span class="op">{</span></span>
@@ -371,11 +371,11 @@ <h2 data-number="5.1" class="anchored" data-anchor-id="print-debugging"><span cl
 <section id="debugging-through-debuggers" class="level2" data-number="5.2">
 <h2 data-number="5.2" class="anchored" data-anchor-id="debugging-through-debuggers"><span class="header-section-number">5.2</span> Debugging through debuggers</h2>
 <p>Although <em>print debugging</em> is a valid and very useful strategy, most programmers prefer to use a debugger to debug their programs. Since Zig is a low-level language, you can use either GDB (GNU Debugger), or LLDB (LLVM Project Debugger) as your debugger.</p>
-<p>Both debuggers can work with Zig code, and it’s a matter of taste here. You choose the debugger of your preference, and you work with it. In this book, I will use LLDB as my debugger on the examples.</p>
+<p>Both debuggers can work with Zig code, and it’s a matter of taste here. You choose the debugger of your preference, and you work with it. In this book, I will use LLDB as my debugger in the examples.</p>
 <section id="sec-compile-debug-mode" class="level3" data-number="5.2.1">
 <h3 data-number="5.2.1" class="anchored" data-anchor-id="sec-compile-debug-mode"><span class="header-section-number">5.2.1</span> Compile your source code in debug mode</h3>
 <p>In order to debug your program through a debugger, you must compile your source code in <code>Debug</code> mode. Because when you compile your source code in other modes (such as <code>Release</code>), the compiler usually strips out some essential information that is used by the debugger to read and track your program, like PDB (<em>Program Database</em>) files.</p>
-<p>By compiling your source code in <code>Debug</code> mode, you ensure that the debugger will find the necessary information in your program to debug it. By default, the compiler uses the <code>Debug</code> mode when compiling your code. Having this in mind, when you compile your program with the <code>build-exe</code> command (which was described at <a href="01-zig-weird.html#sec-compile-code" class="quarto-xref"><span>Section 1.2.4</span></a>), if you don’t specify an explicit mode through the <code>-O</code> command-line <a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a> argument, then, the compiler will compile your code in <code>Debug</code> mode.</p>
+<p>By compiling your source code in <code>Debug</code> mode, you ensure that the debugger will find the necessary information in your program to debug it. By default, the compiler uses the <code>Debug</code> mode when compiling your code. Having this in mind, when you compile your program with the <code>build-exe</code> command (which was described in <a href="01-zig-weird.html#sec-compile-code" class="quarto-xref"><span>Section 1.2.4</span></a>), if you don’t specify an explicit mode through the <code>-O</code> command-line <a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a> argument, then, the compiler will compile your code in <code>Debug</code> mode.</p>
 </section>
 <section id="lets-debug-a-program" class="level3" data-number="5.2.2">
 <h3 data-number="5.2.2" class="anchored" data-anchor-id="lets-debug-a-program"><span class="header-section-number">5.2.2</span> Let’s debug a program</h3>
@@ -399,11 +399,11 @@ <h3 data-number="5.2.2" class="anchored" data-anchor-id="lets-debug-a-program"><
 <pre><code>Result: 13!</code></pre>
 </div>
 </div>
-<p>There is nothing wrong with this program. But it is a good start for us. First, we need to compile this program with the <code>zig build-exe</code> command. For this example, suppose that I have compiled the above Zig code into a binary executable called <code>add_program</code>.</p>
+<p>There is nothing wrong with this program. But it’s a good start for us. First, we need to compile this program with the <code>zig build-exe</code> command. For this example, suppose that I have compiled the above Zig code into a binary executable called <code>add_program</code>.</p>
 <div class="sourceCode" id="cb8"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zig</span> build-exe add_program.zig</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <p>Now, we can start LLDB with <code>add_program</code>, like this:</p>
 <div class="sourceCode" id="cb9"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb9-1"><a href="#cb9-1" aria-hidden="true" tabindex="-1"></a><span class="ex">lldb</span> add_program</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
-<p>From now on, LLDB is started, and you can know that I’m executing LLDB commands by looking at the prefix <code>(lldb)</code>. If something is prefixed with <code>(lldb)</code>, then you know that it is a LLDB command.</p>
+<p>From now on, LLDB is started, and you can know that I’m executing LLDB commands by looking at the prefix <code>(lldb)</code>. If something is prefixed with <code>(lldb)</code>, then you know that it’s a LLDB command.</p>
 <p>The first thing I will do, is to set a breakpoint at the <code>main()</code> function, by executing <code>b main</code>. After that, I just start the execution of the program with <code>run</code>. You can see in the output below, that the execution stopped at the first line in the function <code>main()</code>, as we expected.</p>
 <div class="sourceCode" id="cb10"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">b</span> main</span>
 <span id="cb10-2"><a href="#cb10-2" aria-hidden="true" tabindex="-1"></a><span class="ex">Breakpoint</span> 1: where = debugging<span class="kw">`</span><span class="ex">debug1.main</span> + 22</span>
@@ -424,7 +424,7 @@ <h3 data-number="5.2.2" class="anchored" data-anchor-id="lets-debug-a-program"><
 <p>I can start navigating through the code, and checking the objects that are being generated. If you are not familiar with the commands available in LLDB, I recommend you to read the official documentation of the project<a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a>. You can also look for cheat sheets, which quickly describes all commands available for you<a href="#fn4" class="footnote-ref" id="fnref4" role="doc-noteref"><sup>4</sup></a>.</p>
 <p>Currently, we are in the first line at the <code>main()</code> function. In this line, we create the <code>n</code> object, by executing the <code>add_and_increment()</code> function. To execute the current line of code, and go to the next line, we can run the <code>n</code> LLDB command. Let’s execute this command.</p>
 <p>After we executed this line, we can also look at the value stored inside this <code>n</code> object by using the <code>p</code> LLDB command. The syntax for this command is <code>p &lt;name-of-object&gt;</code>.</p>
-<p>If we take a look at the value stored in the <code>n</code> object (<code>p n</code>), notice that it stores the hexadecimal value <code>0x06</code>, which is the number 6 in decimal. We can also see that this value has a type of <code>unsigned char</code>, which is an unsigned 8-bit integer. We have talked already about this at <a href="01-zig-weird.html#sec-zig-strings" class="quarto-xref"><span>Section 1.8</span></a>, that <code>u8</code> integers in Zig are equivalent to the C data type <code>unsigned char</code>.</p>
+<p>If we take a look at the value stored in the <code>n</code> object (<code>p n</code>), notice that it stores the hexadecimal value <code>0x06</code>, which is the number 6 in decimal. We can also see that this value has a type of <code>unsigned char</code>, which is an unsigned 8-bit integer. We have talked already about this in <a href="01-zig-weird.html#sec-zig-strings" class="quarto-xref"><span>Section 1.8</span></a>, that <code>u8</code> integers in Zig are equivalent to the C data type <code>unsigned char</code>.</p>
 <div class="sourceCode" id="cb11"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a><span class="kw">(</span><span class="ex">lldb</span><span class="kw">)</span> <span class="ex">n</span></span>
 <span id="cb11-2"><a href="#cb11-2" aria-hidden="true" tabindex="-1"></a><span class="ex">Process</span> 4798 stopped</span>
 <span id="cb11-3"><a href="#cb11-3" aria-hidden="true" tabindex="-1"></a><span class="ex">*</span> thread <span class="co">#1, name = 'debugging',</span></span>
diff --git a/docs/Chapters/03-structs.html b/docs/Chapters/03-structs.html
index 9a0d90ff..7c8203c7 100644
--- a/docs/Chapters/03-structs.html
+++ b/docs/Chapters/03-structs.html
@@ -398,7 +398,7 @@ <h4 data-number="2.1.2.1" class="anchored" data-anchor-id="switch-statements-mus
 </section>
 <section id="the-else-branch" class="level4" data-number="2.1.2.2">
 <h4 data-number="2.1.2.2" class="anchored" data-anchor-id="the-else-branch"><span class="header-section-number">2.1.2.2</span> The else branch</h4>
-<p>Take a look at the <code>dump_hex_fallible()</code> function below as an example. This function comes from the Zig Standard Library. More precisely, from the <a href="https://github.com/ziglang/zig/blob/master/lib/std/debug.zig"><code>debug.zig</code> module</a><a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>. There are multiple lines in this function, but I omitted them to focus solely on the switch statement found in this function. Notice that this switch statement has four possible cases (i.e.&nbsp;four explicit branches). Also, notice that we used an <code>else</code> branch in this case.</p>
+<p>Take a look at the <code>dump_hex_fallible()</code> function below as an example. This function comes from the Zig Standard Library. More precisely, from the <a href="https://github.com/ziglang/zig/blob/master/lib/std/debug.zig"><code>debug.zig</code> module</a><a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>. There are multiple lines in this function, but I omitted them to focus solely on the switch statement found in this function. Notice that this switch statement has four possible cases (i.e., four explicit branches). Also, notice that we used an <code>else</code> branch in this case.</p>
 <p>An <code>else</code> branch in a switch statement works as the “default branch”. Whenever you have multiple cases in your switch statement where you want to apply the exact same action, you can use an <code>else</code> branch to do that.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb5"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> dump_hex_fallible(bytes: []<span class="kw">const</span> <span class="dt">u8</span>) !<span class="dt">void</span> <span class="op">{</span></span>
@@ -432,7 +432,7 @@ <h4 data-number="2.1.2.2" class="anchored" data-anchor-id="the-else-branch"><spa
 </section>
 <section id="using-ranges-in-switch" class="level4" data-number="2.1.2.3">
 <h4 data-number="2.1.2.3" class="anchored" data-anchor-id="using-ranges-in-switch"><span class="header-section-number">2.1.2.3</span> Using ranges in switch</h4>
-<p>Furthermore, you can also use ranges of values in switch statements. That is, you can create a branch in your switch statement that is used whenever the input value is within the specified range. These “range expressions” are created with the operator <code>...</code>. It is important to emphasize that the ranges created by this operator are inclusive on both ends.</p>
+<p>Furthermore, you can also use ranges of values in switch statements. That is, you can create a branch in your switch statement that is used whenever the input value is within the specified range. These “range expressions” are created with the operator <code>...</code>. It’s important to emphasize that the ranges created by this operator are inclusive on both ends.</p>
 <p>For example, I could easily change the previous code example to support all levels between 0 and 100. Like this:</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb8"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> level: <span class="dt">u8</span> = <span class="dv">4</span>;</span>
@@ -499,7 +499,7 @@ <h3 data-number="2.1.3" class="anchored" data-anchor-id="sec-defer"><span class=
 <p>Therefore, we can use <code>defer</code> to declare an expression that is going to be executed when your code exits the current scope. Some programmers like to interpret the phrase “exit of the current scope” as “the end of the current scope”. But this interpretation might not be entirely correct, depending on what you consider as “the end of the current scope”.</p>
 <p>I mean, what do you consider as <strong>the end</strong> of the current scope? Is it the closing curly bracket (<code>}</code>) of the scope? Is it when the last expression in the function gets executed? Is it when the function returns to the previous scope? Etc. For example, it would not be correct to interpret the “exit of the current scope” as the closing curly bracket of the scope. Because the function might exit from an earlier position than this closing curly bracket (e.g.&nbsp;an error value was generated at a previous line inside the function; the function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.</p>
 <p>Now, if you remember of what we have discussed in <a href="01-zig-weird.html#sec-blocks" class="quarto-xref"><span>Section 1.7</span></a>, there are multiple structures in the language that create their own separate scopes. For/while loops, if/else statements, functions, normal blocks, etc. This also affects the interpretation of <code>defer</code>. For example, if you use <code>defer</code> inside a for loop, then, the given expression will be executed everytime this specific for loop exits its own scope.</p>
-<p>Before we continue, is worth emphasizing that the <code>defer</code> keyword is an “unconditional defer”. Which means that the given expression will be executed no matter how the code exits the current scope. For example, your code might exit the current scope because of an error value being generated, or, because of a return statement, or, a break statement, etc.</p>
+<p>Before we continue, it’s worth emphasizing that the <code>defer</code> keyword is an “unconditional defer”. Which means that the given expression will be executed no matter how the code exits the current scope. For example, your code might exit the current scope because of an error value being generated, or, because of a return statement, or, a break statement, etc.</p>
 </section>
 <section id="sec-errdefer1" class="level3" data-number="2.1.4">
 <h3 data-number="2.1.4" class="anchored" data-anchor-id="sec-errdefer1"><span class="header-section-number">2.1.4</span> The <code>errdefer</code> keyword</h3>
@@ -508,7 +508,7 @@ <h3 data-number="2.1.4" class="anchored" data-anchor-id="sec-errdefer1"><span cl
 <p>This makes the <code>errdefer</code> keyword one of the many tools available in Zig for error handling. In this section, we are more concerned with the control flow aspects around <code>errdefer</code>. But we are going to discuss <code>errdefer</code> later as a error handling tool in <a href="09-error-handling.html#sec-errdefer2" class="quarto-xref"><span>Section 10.2.4</span></a>.</p>
 <p>The code example below demonstrates three things:</p>
 <ul>
-<li>that <code>defer</code> is an “unconditional defer”, because the given expression get’s executed regardless of how the function <code>foo()</code> exits its own scope.</li>
+<li>that <code>defer</code> is an “unconditional defer”, because the given expression gets executed regardless of how the function <code>foo()</code> exits its own scope.</li>
 <li>that <code>errdefer</code> is executed because the function <code>foo()</code> returned an error value.</li>
 <li>that <code>defer</code> and <code>errdefer</code> expressions are executed in a LIFO (<em>last in, first out</em>) order.</li>
 </ul>
@@ -528,7 +528,7 @@ <h3 data-number="2.1.4" class="anchored" data-anchor-id="sec-errdefer1"><span cl
     return error.FooError;
     ^</code></pre>
 <p>When I say that “defer expressions” are executed in a LIFO order, what I want to say is that the last <code>defer</code> or <code>errdefer</code> expressions in the code are the first ones to be executed. You could also interpret this as: “defer expressions” are executed from bottom to top, or, from last to first.</p>
-<p>Therefore, if I change the order of the <code>defer</code> and <code>errdefer</code> expressions, you will notice that the value of <code>i</code> that get’s printed to the console changes to 1. This doesn’t mean that the <code>defer</code> expression was not executed in this case. This actually means that the <code>defer</code> expression was executed only after the <code>errdefer</code> expression. The code example below demonstrates this:</p>
+<p>Therefore, if I change the order of the <code>defer</code> and <code>errdefer</code> expressions, you will notice that the value of <code>i</code> that gets printed to the console changes to 1. This doesn’t mean that the <code>defer</code> expression was not executed in this case. This actually means that the <code>defer</code> expression was executed only after the <code>errdefer</code> expression. The code example below demonstrates this:</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb15"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb15-1"><a href="#cb15-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb15-2"><a href="#cb15-2" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> foo() !<span class="dt">void</span> <span class="op">{</span> <span class="kw">return</span> <span class="kw">error</span>.FooError; <span class="op">}</span></span>
@@ -604,9 +604,9 @@ <h3 data-number="2.1.6" class="anchored" data-anchor-id="while-loops"><span clas
 </section>
 <section id="using-break-and-continue" class="level3" data-number="2.1.7">
 <h3 data-number="2.1.7" class="anchored" data-anchor-id="using-break-and-continue"><span class="header-section-number">2.1.7</span> Using <code>break</code> and <code>continue</code></h3>
-<p>In Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using the keywords <code>break</code> and <code>continue</code>, respectively. The <code>while</code> loop presented in the next code example is, at first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to <code>true</code>. But what makes this <code>while</code> loop stop when the <code>i</code> object reaches the count 10? It is the <code>break</code> keyword!</p>
+<p>In Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using the keywords <code>break</code> and <code>continue</code>, respectively. The <code>while</code> loop presented in the next code example is, at first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to <code>true</code>. But what makes this <code>while</code> loop stop when the <code>i</code> object reaches the count 10? It’s the <code>break</code> keyword!</p>
 <p>Inside the while loop, we have an if statement that is constantly checking if the <code>i</code> variable is equal to 10. Since we are incrementing the value of <code>i</code> at each iteration of the while loop, this <code>i</code> object will eventually be equal to 10, and when it is, the if statement will execute the <code>break</code> expression, and, as a result, the execution of the while loop is stopped.</p>
-<p>Notice the use of the <code>expect()</code> function from the Zig Standard Library after the while loop. This <code>expect()</code> function is an “assert” type of function. This function checks if the logical test provided is equal to true. If so, the function do nothing. Otherwise (i.e.&nbsp;the logical test is equal to false), the function raises an assertion error.</p>
+<p>Notice the use of the <code>expect()</code> function from the Zig Standard Library after the while loop. This <code>expect()</code> function is an “assert” type of function. This function checks if the logical test provided is equal to true. If so, the function do nothing. Otherwise (i.e., the logical test is equal to false), the function raises an assertion error.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb26"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb26-1"><a href="#cb26-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> i: <span class="dt">usize</span> = <span class="dv">0</span>;</span>
 <span id="cb26-2"><a href="#cb26-2" aria-hidden="true" tabindex="-1"></a><span class="kw">while</span> (<span class="cn">true</span>) <span class="op">{</span></span>
@@ -642,7 +642,7 @@ <h2 data-number="2.2" class="anchored" data-anchor-id="sec-fun-pars"><span class
 <p>We have already discussed a lot of the syntax behind function declarations in <a href="01-zig-weird.html#sec-root-file" class="quarto-xref"><span>Section 1.2.2</span></a> and <a href="01-zig-weird.html#sec-main-file" class="quarto-xref"><span>Section 1.2.3</span></a>. But I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig. In summary, function parameters are immutable in Zig.</p>
 <p>Take the code example below, where we declare a simple function that just tries to add some amount to the input integer, and returns the result back. If you look closely at the body of this <code>add2()</code> function, you will notice that we try to save the result back into the <code>x</code> function argument.</p>
 <p>In other words, this function not only uses the value that it received through the function argument <code>x</code>, but it also tries to change the value of this function argument, by assigning the addition result into <code>x</code>. However, function arguments in Zig are immutable. You cannot change their values, or, you cannot assign values to them inside the body’s function.</p>
-<p>This is the reason why, the code example below does not compile successfully. If you try to compile this code example, you will get a compile error message about “trying to change the value of a immutable (i.e.&nbsp;constant) object”.</p>
+<p>This is the reason why, the code example below does not compile successfully. If you try to compile this code example, you will get a compile error message about “trying to change the value of a immutable (i.e., constant) object”.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb30"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb30-1"><a href="#cb30-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb30-2"><a href="#cb30-2" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> add2(x: <span class="dt">u32</span>) <span class="dt">u32</span> <span class="op">{</span></span>
@@ -667,7 +667,7 @@ <h3 data-number="2.2.1" class="anchored" data-anchor-id="a-free-optimization"><s
 <h3 data-number="2.2.2" class="anchored" data-anchor-id="how-to-overcome-this-barrier"><span class="header-section-number">2.2.2</span> How to overcome this barrier</h3>
 <p>There are some situations where you might need to change the value of your function argument directly inside the function’s body. This happens more often when we are passing C structs as inputs to Zig functions.</p>
 <p>In a situation like this, you can overcome this barrier by using a pointer. In other words, instead of passing a value as input to the argument, you can pass a “pointer to value” instead. You can change the value that the pointer points to, by dereferencing it.</p>
-<p>Therefore, if we take our previous <code>add2()</code> example, we can change the value of the function argument <code>x</code> inside the function’s body by marking the <code>x</code> argument as a “pointer to a <code>u32</code> value” (i.e.&nbsp;<code>*u32</code> data type), instead of a <code>u32</code> value. By making it a pointer, we can finally alter the value of this function argument directly inside the body of the <code>add2()</code> function. You can see that the code example below compiles successfully.</p>
+<p>Therefore, if we take our previous <code>add2()</code> example, we can change the value of the function argument <code>x</code> inside the function’s body by marking the <code>x</code> argument as a “pointer to a <code>u32</code> value” (i.e., <code>*u32</code> data type), instead of a <code>u32</code> value. By making it a pointer, we can finally alter the value of this function argument directly inside the body of the <code>add2()</code> function. You can see that the code example below compiles successfully.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb32"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb32-1"><a href="#cb32-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb32-2"><a href="#cb32-2" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> add2(x: *<span class="dt">u32</span>) <span class="dt">void</span> <span class="op">{</span></span>
@@ -770,7 +770,7 @@ <h3 data-number="2.3.2" class="anchored" data-anchor-id="struct-declarations-mus
 <section id="sec-self-arg" class="level3" data-number="2.3.3">
 <h3 data-number="2.3.3" class="anchored" data-anchor-id="sec-self-arg"><span class="header-section-number">2.3.3</span> The <code>self</code> method argument</h3>
 <p>In every language that have OOP, when we declare a method of some class or struct, we usually declare this method as a function that has a <code>self</code> argument. This <code>self</code> argument is the reference to the object itself from which the method is being called from.</p>
-<p>It is not mandatory to use this <code>self</code> argument. But why would you not use this <code>self</code> argument? There is no reason to not use it. Because the only way to get access to the data stored in the data members of your struct is to access them through this <code>self</code> argument. If you don’t need to use the data in the data members of your struct inside your method, you very likely don’t need a method. You can just declare this logic as a simple function, outside of your struct declaration.</p>
+<p>It’s not mandatory to use this <code>self</code> argument. But why would you not use this <code>self</code> argument? There is no reason to not use it. Because the only way to get access to the data stored in the data members of your struct is to access them through this <code>self</code> argument. If you don’t need to use the data in the data members of your struct inside your method, you very likely don’t need a method. You can just declare this logic as a simple function, outside of your struct declaration.</p>
 <p>Take the <code>Vec3</code> struct below. Inside this <code>Vec3</code> struct we declared a method named <code>distance()</code>. This method calculates the distance between two <code>Vec3</code> objects, by following the distance formula in euclidean space. Notice that this <code>distance()</code> method takes two <code>Vec3</code> objects as input, <code>self</code> and <code>other</code>.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb40"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb40-1"><a href="#cb40-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
@@ -809,7 +809,7 @@ <h3 data-number="2.3.4" class="anchored" data-anchor-id="about-the-struct-state"
 <p>Sometimes you don’t need to care about the state of your struct object. Sometimes, you just need to instantiate and use the objects, without altering their state. You can notice that when you have methods inside your struct declaration that might use the values that are present in the data members, but they do not alter the values in these data members of the struct in anyway.</p>
 <p>The <code>Vec3</code> struct that was presented in <a href="#sec-self-arg" class="quarto-xref"><span>Section 2.3.3</span></a> is an example of that. This struct have a single method named <code>distance()</code>, and this method does use the values present in all three data members of the struct (<code>x</code>, <code>y</code> and <code>z</code>). But at the same time, this method does not change the values of these data members at any point.</p>
 <p>As a result of that, when we create <code>Vec3</code> objects we usually create them as constant objects, like the <code>v1</code> and <code>v2</code> objects presented in <a href="#sec-self-arg" class="quarto-xref"><span>Section 2.3.3</span></a>. We can create them as variable objects with the <code>var</code> keyword, if we want to. But because the methods of this <code>Vec3</code> struct do not change the state of the objects in any point, it’s unnecessary to mark them as variable objects.</p>
-<p>But why? Why am I talking about this here? It’s because the <code>self</code> argument in the methods are affected depending on whether the methods present in a struct change or don’t change the state of the object itself. More specifically, when you have a method in a struct that changes the state of the object (i.e.&nbsp;changes the value of a data member), the <code>self</code> argument in this method must be annotated in a different manner.</p>
+<p>But why? Why am I talking about this here? It’s because the <code>self</code> argument in the methods are affected depending on whether the methods present in a struct change or don’t change the state of the object itself. More specifically, when you have a method in a struct that changes the state of the object (i.e., changes the value of a data member), the <code>self</code> argument in this method must be annotated in a different manner.</p>
 <p>As I described in <a href="#sec-self-arg" class="quarto-xref"><span>Section 2.3.3</span></a>, the <code>self</code> argument in methods of a struct is the argument that receives as input the object from which the method was called from. We usually annotate this argument in the methods by writing <code>self</code>, followed by the colon character (<code>:</code>), and the data type of the struct to which the method belongs to (e.g.&nbsp;<code>User</code>, <code>Vec3</code>, etc.).</p>
 <p>If we take the <code>Vec3</code> struct that we defined in the previous section as an example, we can see in the <code>distance()</code> method that this <code>self</code> argument is annotated as <code>self: Vec3</code>. Because the state of the <code>Vec3</code> object is never altered by this method.</p>
 <p>But what if we do have a method that alters the state of the object, by altering the values of its data members, how should we annotate <code>self</code> in this instance? The answer is: “we should annotate <code>self</code> as a pointer of <code>x</code>, instead of just <code>x</code>”. In other words, you should annotate <code>self</code> as <code>self: *x</code>, instead of annotating it as <code>self: x</code>.</p>
@@ -855,7 +855,7 @@ <h3 data-number="2.3.4" class="anchored" data-anchor-id="about-the-struct-state"
         ~~~~^~</code></pre>
 <p>This error message indicates that the <code>x</code> data member belongs to a constant object, and, because of that, it cannot be changed. Ultimately, this error message is telling us that the <code>self</code> argument is constant.</p>
 <p>If you take some time, and think hard about this error message, you will understand it. You already have the tools to understand why we are getting this error message. We have talked about it already in <a href="#sec-fun-pars" class="quarto-xref"><span>Section 2.2</span></a>. So remember, every function argument is immutable in Zig, and <code>self</code> is no exception to this rule.</p>
-<p>In this example, we marked the <code>v3</code> object as a variable object. But this does not matter. Because it is not about the input object, it is about the function argument.</p>
+<p>In this example, we marked the <code>v3</code> object as a variable object. But this does not matter. Because it’s not about the input object, it’s about the function argument.</p>
 <p>The problem begins when we try to alter the value of <code>self</code> directly, which is a function argument, and, every function argument is immutable by default. You may ask yourself how can we overcome this barrier, and once again, the solution was also discussed in <a href="#sec-fun-pars" class="quarto-xref"><span>Section 2.2</span></a>. We overcome this barrier, by explicitly marking the <code>self</code> argument as a pointer.</p>
 <div class="callout callout-style-default callout-note callout-titled">
 <div class="callout-header d-flex align-content-center">
@@ -877,12 +877,12 @@ <h3 data-number="2.3.4" class="anchored" data-anchor-id="about-the-struct-state"
 <h2 data-number="2.4" class="anchored" data-anchor-id="sec-type-inference"><span class="header-section-number">2.4</span> Type inference</h2>
 <p>Zig is a strongly typed language. But, there are some situations where you don’t have to explicitly write the type of every single object in your source code, as you would expect from a traditional strongly typed language, such as C and C++.</p>
 <p>In some situations, the <code>zig</code> compiler can use type inference to solve the data types for you, easing some of the burden that you carry as a developer. The most common way this happens is through function arguments that receive struct objects as input.</p>
-<p>In general, type inference in Zig is done by using the dot character (<code>.</code>). Everytime you see a dot character written before a struct literal, or before an enum value, or something like that, you know that this dot character is playing a special part in this place. More specifically, it is telling the <code>zig</code> compiler something along the lines of: “Hey! Can you infer the type of this value for me? Please!”. In other words, this dot character is playing a similar role as the <code>auto</code> keyword in C++.</p>
+<p>In general, type inference in Zig is done by using the dot character (<code>.</code>). Everytime you see a dot character written before a struct literal, or before an enum value, or something like that, you know that this dot character is playing a special part in this place. More specifically, it’s telling the <code>zig</code> compiler something along the lines of: “Hey! Can you infer the type of this value for me? Please!”. In other words, this dot character is playing a similar role as the <code>auto</code> keyword in C++.</p>
 <p>I gave you some examples of this in <a href="#sec-anonymous-struct-literals" class="quarto-xref"><span>Section 2.3.1</span></a>, where we used anonymous struct literals. Anonymous struct literals are, struct literals that use type inference to infer the exact type of this particular struct literal. This type inference is done by looking for some minimal hint of the correct data type to be used. You could say that the <code>zig</code> compiler looks for any neighbouring type annotation that might tell it what the correct type would be.</p>
 <p>Another common place where we use type inference in Zig is at switch statements (which we talked about in <a href="#sec-switch" class="quarto-xref"><span>Section 2.1.2</span></a>). I also gave some other examples of type inference in <a href="#sec-switch" class="quarto-xref"><span>Section 2.1.2</span></a>, where we were inferring the data types of enum values listed inside of switch statements (e.g.&nbsp;<code>.DE</code>). But as another example, take a look at this <code>fence()</code> function reproduced below, which comes from the <a href="https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig"><code>atomic.zig</code> module</a><a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a> of the Zig Standard Library.</p>
 <p>There are a lot of things in this function that we haven’t talked about yet, such as: what <code>comptime</code> means? <code>inline</code>? <code>extern</code>? Let’s just ignore all of these things, and focus solely on the switch statement that is inside this function.</p>
 <p>We can see that this switch statement uses the <code>order</code> object as input. This <code>order</code> object is one of the inputs of this <code>fence()</code> function, and we can see in the type annotation, that this object is of type <code>AtomicOrder</code>. We can also see a bunch of values inside the switch statements that begin with a dot character, such as <code>.release</code> and <code>.acquire</code>.</p>
-<p>Because these weird values contain a dot character before them, we are asking the <code>zig</code> compiler to infer the types of these values inside the switch statement. Then, the <code>zig</code> compiler is looking into the current context where these values are being used, and it is trying to infer the types of these values.</p>
+<p>Because these weird values contain a dot character before them, we are asking the <code>zig</code> compiler to infer the types of these values inside the switch statement. Then, the <code>zig</code> compiler is looking into the current context where these values are being used, and trying to infer the types of these values.</p>
 <p>Since they are being used inside a switch statement, the <code>zig</code> compiler looks into the type of the input object given to the switch statement, which is the <code>order</code> object in this case. Because this object have type <code>AtomicOrder</code>, the <code>zig</code> compiler infers that these values are data members from this type <code>AtomicOrder</code>.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb48"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb48-1"><a href="#cb48-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">inline</span> <span class="kw">fn</span> fence(self: *Self, <span class="kw">comptime</span> order: AtomicOrder) <span class="dt">void</span> <span class="op">{</span></span>
@@ -915,9 +915,9 @@ <h2 data-number="2.4" class="anchored" data-anchor-id="sec-type-inference"><span
 </section>
 <section id="sec-type-cast" class="level2" data-number="2.5">
 <h2 data-number="2.5" class="anchored" data-anchor-id="sec-type-cast"><span class="header-section-number">2.5</span> Type casting</h2>
-<p>In this section, I want to discuss type casting (or, type conversion) with you. We use type casting when we have an object of type “x”, and we want to convert it into an object of type “y”, i.e.&nbsp;we want to change the data type of the object.</p>
+<p>In this section, I want to discuss type casting (or, type conversion) with you. We use type casting when we have an object of type “x”, and we want to convert it into an object of type “y”, i.e., we want to change the data type of the object.</p>
 <p>Most languages have a formal way to perform type casting. In Rust for example, we normally use the keyword <code>as</code>, and in C, we normally use the type casting syntax, e.g.&nbsp;<code>(int) x</code>. In Zig, we use the <code>@as()</code> built-in function to cast an object of type “x”, into an object of type “y”.</p>
-<p>This <code>@as()</code> function is the preferred way to perform type conversion (or type casting) in Zig. Because it is explicit, and, it also performs the casting only if it is unambiguous and safe. To use this function, you just provide the target data type in the first argument, and, the object that you want cast as the second argument.</p>
+<p>This <code>@as()</code> function is the preferred way to perform type conversion (or type casting) in Zig. Because it’s explicit, and, it also performs the casting only if it is unambiguous and safe. To use this function, you just provide the target data type in the first argument, and, the object that you want cast as the second argument.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb49"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb49-1"><a href="#cb49-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb49-2"><a href="#cb49-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = std.testing.expect;</span>
@@ -927,11 +927,12 @@ <h2 data-number="2.5" class="anchored" data-anchor-id="sec-type-cast"><span clas
 <span id="cb49-6"><a href="#cb49-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(y) == <span class="dt">u32</span>);</span>
 <span id="cb49-7"><a href="#cb49-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file9f8940318094.test_0...OKAll 1 tests passed
+<pre><code>1/1 file79ce58134f59.test_0...OKAll 1 tests passed
   d.</code></pre>
 </div>
 </div>
-<p>This is the general way to perform type casting in Zig. But remember, <code>@as()</code> works only when casting is unambiguous and safe, and there are situations where these assumptions do not hold. For example, when casting an integer value into a float value, or vice-versa, it is not clear to the compiler how to perform this conversion safely.</p>
+<p>This is the general way to perform type casting in Zig. But remember, <code>@as()</code> works only when casting is unambiguous and safe. There are many situations where these assumptions do not hold. For example,</p>
+<p>when casting an integer value into a float value, or vice-versa, it’s not clear to the compiler how to perform this conversion safely.</p>
 <p>Therefore, we need to use specialized “casting functions” in such situations. For example, if you want to cast an integer value into a float value, then, you should use the <code>@floatFromInt()</code> function. In the inverse scenario, you should use the <code>@intFromFloat()</code> function.</p>
 <p>In these functions, you just provide the object that you want to cast as input. Then, the target data type of the “type casting operation” is determined by the type annotation of the object where you are saving the results. In the example below, we are casting the object <code>x</code> into a value of type <code>f32</code>, because the object <code>y</code>, which is where we are saving the results, is annotated as an object of type <code>f32</code>.</p>
 <div class="cell">
@@ -943,11 +944,11 @@ <h2 data-number="2.5" class="anchored" data-anchor-id="sec-type-cast"><span clas
 <span id="cb51-6"><a href="#cb51-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(y) == <span class="dt">f32</span>);</span>
 <span id="cb51-7"><a href="#cb51-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file9f8954828844.test_0...OKAll 1 tests passed
+<pre><code>1/1 file79ce286cee5b.test_0...OKAll 1 tests passed
   d.</code></pre>
 </div>
 </div>
-<p>Another built-in function that is very useful when performing type casting operations is <code>@ptrCast()</code>. In essence, we use the <code>@as()</code> built-in function when we want to explicit convert (or cast) a Zig value/object from a type “x” to a type “y”, etc. However, pointers (we are going to discuss pointers in more depth in <a href="05-pointers.html" class="quarto-xref"><span>Chapter 6</span></a>) are a special type of object in Zig, i.e.&nbsp;they are treated differently from “normal objects”.</p>
+<p>Another built-in function that is very useful when performing type casting operations is <code>@ptrCast()</code>. In essence, we use the <code>@as()</code> built-in function when we want to explicit convert (or cast) a Zig value/object from a type “x” to a type “y”, etc. However, pointers (we are going to discuss pointers in more depth in <a href="05-pointers.html" class="quarto-xref"><span>Chapter 6</span></a>) are a special type of object in Zig, i.e., they are treated differently from “normal objects”.</p>
 <p>Everytime a pointer is involved in some “type casting operation” in Zig, the <code>@ptrCast()</code> function is used. This function works similarly to <code>@floatFromInt()</code>. You just provide the pointer object that you want to cast as input to this function, and the target data type is, once again, determined by the type annotation of the object where the results are being stored.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb53"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb53-1"><a href="#cb53-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
@@ -960,19 +961,19 @@ <h2 data-number="2.5" class="anchored" data-anchor-id="sec-type-cast"><span clas
 <span id="cb53-8"><a href="#cb53-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(u32_ptr) == *<span class="kw">const</span> <span class="dt">u32</span>);</span>
 <span id="cb53-9"><a href="#cb53-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file9f8944ca02e1.test_0...OKAll 1 tests passed
+<pre><code>1/1 file79ce1e7313c8.test_0...OKAll 1 tests passed
   d.</code></pre>
 </div>
 </div>
 </section>
 <section id="modules" class="level2" data-number="2.6">
 <h2 data-number="2.6" class="anchored" data-anchor-id="modules"><span class="header-section-number">2.6</span> Modules</h2>
-<p>We already talked about what modules are, and also, how to import other modules into your current module via <em>import statements</em>. Every Zig module (i.e.&nbsp;a <code>.zig</code> file) that you write in your project is internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the Zig Standard Library into our current module.</p>
+<p>We already talked about what modules are, and also, how to import other modules into your current module via <em>import statements</em>. Every Zig module (i.e., a <code>.zig</code> file) that you write in your project is internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the Zig Standard Library into our current module.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb55"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb55-1"><a href="#cb55-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>When we want to access the functions and objects from the standard library, we are basically accessing the data members of the struct stored in the <code>std</code> object. That is why we use the same syntax that we use in normal structs, with the dot operator (<code>.</code>) to access the data members and methods of the struct.</p>
-<p>When this “import statement” get’s executed, the result of this expression is a struct object that contains the Zig Standard Library modules, global variables, functions, etc. And this struct object get’s saved (or stored) inside the constant object named <code>std</code>.</p>
+<p>When this “import statement” gets executed, the result of this expression is a struct object that contains the Zig Standard Library modules, global variables, functions, etc. And this struct object gets saved (or stored) inside the constant object named <code>std</code>.</p>
 <p>Take the <a href="https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig"><code>thread_pool.zig</code> module from the project <code>zap</code></a><a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a> as an example. This module is written as if it was a big struct. That is why we have a top-level and public <code>init()</code> method written in this module. The idea is that all top-level functions written in this module are methods from the struct, and all top-level objects and struct declarations are data members of this struct. The module is the struct itself.</p>
 <p>So you would import and use this module by doing something like this:</p>
 <div class="cell">
diff --git a/docs/Chapters/03-unittests.html b/docs/Chapters/03-unittests.html
index 42c0c02b..c41b4ef9 100644
--- a/docs/Chapters/03-unittests.html
+++ b/docs/Chapters/03-unittests.html
@@ -323,11 +323,11 @@ <h2 data-number="8.1" class="anchored" data-anchor-id="introducing-the-test-bloc
 <span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect((a + b) == <span class="dv">4</span>);</span>
 <span id="cb1-7"><a href="#cb1-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 filea5b06c1ec326.test.testing simple sum...OKA
+<pre><code>1/1 file81c21dbf264e.test.testing simple sum...OKA
   All 1 tests passed.</code></pre>
 </div>
 </div>
-<p>You can have multiple <code>test</code> blocks written on the same Zig module. Also, you can mix <code>test</code> blocks with your source code, with no problems or consequences. If you mix <code>test</code> blocks with your normal source code, when you execute the <code>build</code>, <code>build-exe</code>, <code>build-obj</code> or <code>build-lib</code> commands from the <code>zig</code> compiler that we exposed at <a href="01-zig-weird.html#sec-compile-code" class="quarto-xref"><span>Section 1.2.4</span></a>, these <code>test</code> blocks are automatically ignored by the compiler.</p>
+<p>You can have multiple <code>test</code> blocks written on the same Zig module. Also, you can mix <code>test</code> blocks with your source code, with no problems or consequences. If you mix <code>test</code> blocks with your normal source code, when you execute the <code>build</code>, <code>build-exe</code>, <code>build-obj</code> or <code>build-lib</code> commands from the <code>zig</code> compiler that we exposed in <a href="01-zig-weird.html#sec-compile-code" class="quarto-xref"><span>Section 1.2.4</span></a>, these <code>test</code> blocks are automatically ignored by the compiler.</p>
 <p>In other words, the <code>zig</code> compiler builds and execute your unit tests only when you ask it to. By default, the compiler always ignore <code>test</code> blocks written in your Zig modules. The compiler normally checks only if there are any syntax errors in these <code>test</code> blocks.</p>
 <p>If you take a look at the source code for most of the files present in the Zig Standard Library<a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>, you can see that the <code>test</code> blocks are written together with the normal source code of the library. You can see this for example, at the <a href="https://github.com/ziglang/zig/blob/master/lib/std/array_list.zig"><code>array_list</code> module</a><a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a>. So, the standard that the Zig developers decided to adopt is to keep their unit tests together with the source code of the functionality that they are testing.</p>
 <p>Each programmer might have a different opinion on this. Some of them might prefer to keep unit tests separate from the actual source code of their application. If that is your case, you can simply create a separate <code>tests</code> folder in your project, and start writing Zig modules that contains only unit tests (as you would normally do on a Python project with <code>pytest</code>, for example), and everything will work fine. It boils down to which is your preference here.</p>
@@ -342,8 +342,8 @@ <h2 data-number="8.2" class="anchored" data-anchor-id="how-to-run-your-tests"><s
 <section id="testing-memory-allocations" class="level2" data-number="8.3">
 <h2 data-number="8.3" class="anchored" data-anchor-id="testing-memory-allocations"><span class="header-section-number">8.3</span> Testing memory allocations</h2>
 <p>One of the advantages of Zig is that it offers great tools that help us, programmers, to avoid (but also detect) memory problems, such as memory leaks and double-frees. The <code>defer</code> keyword is especially helpful in this regard.</p>
-<p>When developing your source code, you, the programmer, is responsible for making sure that your code do not produce such problems. However, you can also use a special type of an allocator object in Zig that is capable of automatically detecting such problems for you. This is the <code>std.testing.allocator</code> object. This allocator object offers some basic memory safety detection features, which are capable of detecting memory leaks.</p>
-<p>As we described at <a href="01-memory.html#sec-heap" class="quarto-xref"><span>Section 3.1.5</span></a>, to allocate memory on the heap, you need to use an allocator object, and your functions that use these objects to allocate memory on the heap, should receive an allocator object as one of its inputs. Every memory on the heap that you allocate using these allocator objects, must also be freed using this same allocator object.</p>
+<p>When developing your source code, you, the programmer, are responsible for making sure that your code does not produce such problems. However, you can also use a special type of an allocator object in Zig that is capable of automatically detecting such problems for you. This is the <code>std.testing.allocator</code> object. This allocator object offers some basic memory safety detection features, which are capable of detecting memory leaks.</p>
+<p>As we described in <a href="01-memory.html#sec-heap" class="quarto-xref"><span>Section 3.1.5</span></a>, to allocate memory on the heap, you need to use an allocator object, and your functions that use these objects to allocate memory on the heap, should receive an allocator object as one of its inputs. Every memory on the heap that you allocate using these allocator objects, must also be freed using this same allocator object.</p>
 <p>So, if you want to test the memory allocations performed by your functions, and make sure that you don’t have problems in these allocations, you can simply write unit tests for these functions, where you provide the <code>std.testing.allocator</code> object as input to these functions.</p>
 <p>Look at the example below, where I’m defining a function that clearly causes a memory leak. Because we allocate memory, but, at the same time, we do not free this allocated memory at any point. So, when the function returns, we lose the reference to the <code>buffer</code> object, which contains the allocated memory, and, as a result, we can no longer free this memory.</p>
 <p>Notice that, inside a <code>test</code> block I execute this function with the <code>std.testing.allocator</code>. The allocator object was capable of looking deeper in our program, and detecting the memory leak. As a result, this allocator object returns an error message of “memory leaked”, and also, a stack trace showing the exact point where the memory was leaked.</p>
@@ -363,7 +363,7 @@ <h2 data-number="8.3" class="anchored" data-anchor-id="testing-memory-allocation
 <span id="cb5-13"><a href="#cb5-13" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Test [1/1] leak_memory.test.memory leak...
-    [gpa] (err): memory address 0x7c1fddf39000 leaked: 
+    [gpa] (err): memory address 0x7c1fddf39000 leaked:
 ./ZigExamples/debugging/leak_memory.zig:4:39: 0x10395f2
     const buffer = try allocator.alloc(u32, 10);
                                       ^
@@ -396,7 +396,7 @@ <h2 data-number="8.4" class="anchored" data-anchor-id="testing-errors"><span cla
 <span id="cb7-14"><a href="#cb7-14" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expectError(<span class="kw">error</span>.OutOfMemory, alloc_error(allocator));</span>
 <span id="cb7-15"><a href="#cb7-15" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 filea5b059c00874.test.testing error...OKAll 1 
+<pre><code>1/1 file81c24fea00d1.test.testing error...OKAll 1 
    tests passed.</code></pre>
 </div>
 </div>
@@ -433,8 +433,8 @@ <h2 data-number="8.5" class="anchored" data-anchor-id="testing-simple-equalities
 <span id="cb11-7"><a href="#cb11-7" aria-hidden="true" tabindex="-1"></a>    );</span>
 <span id="cb11-8"><a href="#cb11-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 filea5b054e42b80.test.arrays are equal?...OKAl
-  ll 1 tests passed.</code></pre>
+<pre><code>1/1 file81c25513148.test.arrays are equal?...OKAll
+  l 1 tests passed.</code></pre>
 </div>
 </div>
 <p>At last, you might also want to use the <code>expectEqualStrings()</code> function. As the name suggests, you can use this function to test if two strings are equal or not. Just provide the two string objects that you want to compare, as inputs to the function.</p>
@@ -449,7 +449,7 @@ <h2 data-number="8.5" class="anchored" data-anchor-id="testing-simple-equalities
 <span id="cb13-7"><a href="#cb13-7" aria-hidden="true" tabindex="-1"></a>    );</span>
 <span id="cb13-8"><a href="#cb13-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<pre><code>1/1 t.test.strings are equal?... 
+<pre><code>1/1 t.test.strings are equal?...
 ====== expected this output: =========
 hello, world!␃
 ======== instead found this: =========
diff --git a/docs/Chapters/04-http-server.html b/docs/Chapters/04-http-server.html
index 9b222d8b..48b876ef 100644
--- a/docs/Chapters/04-http-server.html
+++ b/docs/Chapters/04-http-server.html
@@ -350,7 +350,7 @@ <h1 class="title"><span class="chapter-number">7</span>&nbsp; <span class="chapt
 <section id="what-is-a-http-server" class="level2" data-number="7.1">
 <h2 data-number="7.1" class="anchored" data-anchor-id="what-is-a-http-server"><span class="header-section-number">7.1</span> What is a HTTP Server?</h2>
 <p>First of all, what is a HTTP Server? A HTTP server, as any other type of server, is essentially a program that runs indefinitely, on an infinite loop, waiting for incoming connections from clients. Once the server receives an incoming connection, it will accept this connection, and it will send messages back-and-forth to the client through this connection.</p>
-<p>But the messages that are transmitted inside this connection are in a specific format. They are HTTP messages (i.e.&nbsp;messages that use the HTTP Protocol specification). The HTTP Protocol is the backbone of the modern web. The world wide web as we know it today, would not exist without the HTTP Protocol.</p>
+<p>But the messages that are transmitted inside this connection are in a specific format. They are HTTP messages (i.e., messages that use the HTTP Protocol specification). The HTTP Protocol is the backbone of the modern web. The world wide web as we know it today, would not exist without the HTTP Protocol.</p>
 <p>So, Web servers (which is just a fancy name to HTTP Servers) are servers that exchange HTTP messages with clients. And these HTTP servers and the HTTP Protocol specification are essential to the operation of the world wide web today.</p>
 <p>That is the whole picture of the process. Again, we have two subjects involved here, a server (which is a program that is running indefinitely, waiting to receive incoming connections), and a client (which is someone that wants to connect to the server, and exchange HTTP messages with it).</p>
 <p>You may find the material about the <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview">HTTP Protocol available at the Mozilla MDN Docs</a><a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a> , a great resource for you to also look at. It gives you a great overview on how HTTP works, and what role the server plays in this matter.</p>
@@ -362,7 +362,7 @@ <h2 data-number="7.2" class="anchored" data-anchor-id="sec-how-http-works"><span
 <p>After this entire process of dealing with the customer (searching for available apartments, receiving payment, handing over the keys), the receptionist goes back to what he was doing earlier, which is to wait. Wait for new customers to arrive.</p>
 <p>That is, in a nutshell, what a HTTP Server do. It waits for clients to connect to the server. When a client attempts to connect to the server, the server accepts this connection, and it starts to exchange messages with the client through this connection. The first message that happens inside this connection is always a message from the client to the server. This message is called the <em>HTTP Request</em>.</p>
 <p>This HTTP Request is a HTTP message that contains what the client wants from the server. It is literally a request. The client that connected to the server is asking this server to do something for him.</p>
-<p>There are different “types of request” that a client can send to a HTTP Server. But the most basic type of request, is when a client ask to the HTTP Server to serve (i.e.&nbsp;to send) some specific web page (which is a HTML file) to him. When you type <code>google.com</code> in your web browser, you are essentially sending a HTTP Request to Google’s HTTP servers. This request is asking these servers to send the Google webpage to you.</p>
+<p>There are different “types of request” that a client can send to a HTTP Server. But the most basic type of request, is when a client ask to the HTTP Server to serve (i.e., to send) some specific web page (which is a HTML file) to him. When you type <code>google.com</code> in your web browser, you are essentially sending a HTTP Request to Google’s HTTP servers. This request is asking these servers to send the Google webpage to you.</p>
 <p>Nonetheless, when the server receives this first message, the <em>HTTP Request</em>, it analyzes this request, to understand: who the client is? What he wants the server to do? This client has provided all the necessary information to perform the action that he asked? Etc.</p>
 <p>Once the server understands what the client wants, he simply perform the action that was requested, and, to finish the whole process, the server sends back a HTTP message to the client, informing if the action performed was successful or not, and, at last, the server ends (or closes) the connection with the client.</p>
 <p>This last HTTP message sent from the server to the client, is called the <em>HTTP Response</em>. Because the server is responding to the action that was requested by the client. The main objective of this response message is let the client know if the action requested was successful or not, before the server closes the connection.</p>
@@ -378,7 +378,7 @@ <h2 data-number="7.3" class="anchored" data-anchor-id="sec-http-how-impl"><span
 <li>When a connection arrive, we accept this connection, and we exchange the HTTP messages (HTTP Request and HTTP Response).</li>
 <li>Then, we simply close this connection.</li>
 </ol>
-<p>A socket object is essentially a channel of communication. You are creating a channel where people can send messages through. When you create a socket object, this object is not binded to any particular address. This means that with this object you have a representation of a channel of communication in your hands. But this channel is not currently available, or, it is not currently accessible, because it do not have a known address where you can find it.</p>
+<p>A socket object is essentially a channel of communication. You are creating a channel where people can send messages through. When you create a socket object, this object is not binded to any particular address. This means that with this object you have a representation of a channel of communication in your hands. But this channel is not currently available, or, it is not currently accessible, because it does not have a known address where you can find it.</p>
 <p>That is what the “bind” operation do. It binds a name (or more specifically, an address) to this socket object, or, this channel of communication, so that it becomes available, or, accessible through this address. While the “listen” operation makes the socket object to listen for incoming connections in this address. In other words, the “listen” operation makes the socket to wait for incoming connections. currently Now, when a client actually attempts to connect to the server through the socket address that we have specified, in order to establish this connection with the client, the socket object needs to accept this incoming connection. Thus, when we accept an incoming connection, the client and the server become connected to each other, and they can start reading or writing messages into this established connection.</p>
 <p>After we receive the HTTP Request from the client, analyze it, and send the HTTP Response to the client, we can then close the connection, and end this communication.</p>
 </section>
@@ -387,8 +387,8 @@ <h2 data-number="7.4" class="anchored" data-anchor-id="implementing-the-server--
 <section id="sec-create-socket" class="level3" data-number="7.4.1">
 <h3 data-number="7.4.1" class="anchored" data-anchor-id="sec-create-socket"><span class="header-section-number">7.4.1</span> Creating the socket object</h3>
 <p>Let’s begin with creating the socket object for our server. Just to make things shorter, I will create this socket object in a separate Zig module. I will name it <code>config.zig</code>.</p>
-<p>In Zig, we can create a web socket using the <code>std.posix.socket()</code> function, from the Zig Standard Library. As I mentioned earlier at <a href="#sec-http-how-impl" class="quarto-xref"><span>Section 7.3</span></a>, every socket object that we create represents a communication channel, and we need to bind this channel to a specific address. An “address” is defined as an IP address, or, more specifically, an IPv4 address<a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a>. Every IPv4 address is composed by two components. The first component is the host, which is a sequence of 4 numbers separated by dot characters (<code>.</code>) that identifies the machine used. While the second component is a port number, which identifies the specific door, or, the specific port to use in the host machine.</p>
-<p>The sequence of 4 numbers (i.e.&nbsp;the host) identifies the machine (i.e.&nbsp;the computer itself) where this socket will live in. Every computer normally have multiple “doors” available inside of him, because this allows the computer to receive and work with multiple connections at the same time. He simply use a single door for each connection. So the port number, is essentially a number that identifies the specific door in the computer that will be responsible for receiving the connection. That is, it identifies the “door” in the computer that the socket will use to receive incoming connections.</p>
+<p>In Zig, we can create a web socket using the <code>std.posix.socket()</code> function, from the Zig Standard Library. As I mentioned earlier in <a href="#sec-http-how-impl" class="quarto-xref"><span>Section 7.3</span></a>, every socket object that we create represents a communication channel, and we need to bind this channel to a specific address. An “address” is defined as an IP address, or, more specifically, an IPv4 address<a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a>. Every IPv4 address is composed by two components. The first component is the host, which is a sequence of 4 numbers separated by dot characters (<code>.</code>) that identifies the machine used. While the second component is a port number, which identifies the specific door, or, the specific port to use in the host machine.</p>
+<p>The sequence of 4 numbers (i.e., the host) identifies the machine (i.e., the computer itself) where this socket will live in. Every computer normally have multiple “doors” available inside of him, because this allows the computer to receive and work with multiple connections at the same time. He simply use a single door for each connection. So the port number, is essentially a number that identifies the specific door in the computer that will be responsible for receiving the connection. That is, it identifies the “door” in the computer that the socket will use to receive incoming connections.</p>
 <p>To make things simpler, I will use an IP address that identifies our current machine in this example. This means that, our socket object will reside on the same computer that we are currently using (this is also known as the “localhost”) to write this Zig source code.</p>
 <p>By convention, the IP address that identifies the “localhost”, which is the current machine we are using, is the IP <code>127.0.0.1</code>. So, that is the IP address we are going to use in our server. I can declare it in Zig by using an array of 4 integers, like this:</p>
 <div class="cell">
@@ -425,11 +425,11 @@ <h3 data-number="7.4.1" class="anchored" data-anchor-id="sec-create-socket"><spa
 </section>
 <section id="listening-and-receiving-connections" class="level3" data-number="7.4.2">
 <h3 data-number="7.4.2" class="anchored" data-anchor-id="listening-and-receiving-connections"><span class="header-section-number">7.4.2</span> Listening and receiving connections</h3>
-<p>Remember that we stored the <code>Socket</code> struct declaration that we built at <a href="#sec-create-socket" class="quarto-xref"><span>Section 7.4.1</span></a> inside a Zig module named <code>config.zig</code>. This is why I imported this module into our main module (<code>main.zig</code>) in the example below, as the <code>SocketConf</code> object, to access the <code>Socket</code> struct.</p>
+<p>Remember that we stored the <code>Socket</code> struct declaration that we built in <a href="#sec-create-socket" class="quarto-xref"><span>Section 7.4.1</span></a> inside a Zig module named <code>config.zig</code>. This is why I imported this module into our main module (<code>main.zig</code>) in the example below, as the <code>SocketConf</code> object, to access the <code>Socket</code> struct.</p>
 <p>Once we created our socket object, we can focus now on making this socket object listen and receive new incoming connections. We do that, by calling the <code>listen()</code> method from the <code>Address</code> object that is contained inside the socket object, and then, we call the <code>accept()</code> method over the result.</p>
 <p>The <code>listen()</code> method from the <code>Address</code> object produces a server object, which is an object that will stay open and running indefinitely, waiting to receive an incoming connection. Therefore, if you try to run the code example below, by calling the <code>run</code> command from the <code>zig</code> compiler, you will notice that the programs keeps running indefinitely, without a clear end.</p>
-<p>This happens, because the program is waiting for something to happen. It is waiting for someone to try to connect to the address (<code>http://127.0.0.1:3490</code>) where the server is running and listening for incoming connections. This is what the <code>listen()</code> method do, it makes the socket to be active waiting for someone to connect.</p>
-<p>On the other side, the <code>accept()</code> method is the function that establishes the connection when someone tries to connect to the socket. This means that, the <code>accept()</code> method returns a new connection object as a result. And you can use this connection object to read or write messages from or to the client. For now, we are not doing anything with this connection object. But we are going to use it on the next section.</p>
+<p>This happens, because the program is waiting for something to happen. It’s waiting for someone to try to connect to the address (<code>http://127.0.0.1:3490</code>) where the server is running and listening for incoming connections. This is what the <code>listen()</code> method do, it makes the socket to be active waiting for someone to connect.</p>
+<p>On the other side, the <code>accept()</code> method is the function that establishes the connection when someone tries to connect to the socket. This means that, the <code>accept()</code> method returns a new connection object as a result. And you can use this connection object to read or write messages from or to the client. For now, we are not doing anything with this connection object. But we are going to use it in the next section.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb3"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb3-2"><a href="#cb3-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> SocketConf = <span class="bu">@import</span>(<span class="st">"config.zig"</span>);</span>
@@ -444,13 +444,13 @@ <h3 data-number="7.4.2" class="anchored" data-anchor-id="listening-and-receiving
 <span id="cb3-11"><a href="#cb3-11" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>This code example allows one single connection. In other words, the server will wait for one incoming connection, and as soon as the server is done with this first connection that it establishes, the program ends, and the server stops.</p>
-<p>This is not the norm on the real world. Most people that write a HTTP server like this, usually put the <code>accept()</code> method inside a <code>while</code> (infinite) loop, where if a connection is created with <code>accept()</code>, a new thread of execution is created to deal with this new connection and the client. That is, real-world examples of HTTP Servers normally rely on parallel computing to work.</p>
+<p>This is not the norm in the real world. Most people that write a HTTP server like this, usually put the <code>accept()</code> method inside a <code>while</code> (infinite) loop, where if a connection is created with <code>accept()</code>, a new thread of execution is created to deal with this new connection and the client. That is, real-world examples of HTTP Servers normally rely on parallel computing to work.</p>
 <p>With this design, the server simply accepts the connection, and the whole process of dealing with the client, and receiving the HTTP Request, and sending the HTTP Response, all of this is done in the background, on a separate execution thread.</p>
 <p>So, as soon as the server accepts the connection, and creates the separate thread, the server goes back to what he was doing earlier, which is to wait indefinitely for a new connection to accept. Having this in mind, the code example exposed above, is a server that serves only a single client. Because the program terminates as soon as the connection is accepted.</p>
 </section>
 <section id="sec-read-http-message" class="level3" data-number="7.4.3">
 <h3 data-number="7.4.3" class="anchored" data-anchor-id="sec-read-http-message"><span class="header-section-number">7.4.3</span> Reading the message from the client</h3>
-<p>Now that we have a connection established, i.e.&nbsp;the connection object that we created through the <code>accept()</code> function, we can now use this connection object to read any messages that the client send to our server. But we can also use it to send messages back to the client.</p>
+<p>Now that we have a connection established, i.e., the connection object that we created through the <code>accept()</code> function, we can now use this connection object to read any messages that the client send to our server. But we can also use it to send messages back to the client.</p>
 <p>The basic idea is, if we <strong>write</strong> any data into this connection object, then, we are sending data to the client, and if we <strong>read</strong> the data present in this connection object, then, we are reading any data that the client sent to us, through this connection object. So, just have this logic in mind. “Read” is for reading messages from the client, and “write” is to send a message to the client.</p>
 <p>Remember from <a href="#sec-how-http-works" class="quarto-xref"><span>Section 7.2</span></a> that, the first thing that we need to do is to read the HTTP Request sent by the client to our server. Because it is the first message that happens inside the established connection, and, as a consequence, it is the first thing that we need to deal with.</p>
 <p>That is why, I’m going to create a new Zig module in this small project, named <code>request.zig</code> to keep all functions related to the HTTP Request together. Then, I will create a new function named <code>read_request()</code> that will use our connection object to read the message sent by the client, which is the HTTP Request.</p>
@@ -495,7 +495,7 @@ <h2 data-number="7.5" class="anchored" data-anchor-id="looking-at-the-current-st
 </div>
 <p>Now, I’m going to execute this program, with the <code>run</code> command from the <code>zig</code> compiler. But remember, as we sad earlier, as soon as I execute this program, it will hang indefinitely, because the program is waiting for a client trying to connect to the server.</p>
 <p>More specifically, the program will pause at the line with the <code>accept()</code> call. As soon as a client try to connect to the server, then, the execution will “unpause”, and the <code>accept()</code> function will finally be executed to create the connection object that we need, and the remaining of the program will run.</p>
-<p>You can see that at <a href="#fig-print-zigrun1" class="quarto-xref">Figure&nbsp;<span>7.1</span></a>. The message <code>Server Addr: 127.0.0.1:3490</code> is printed to the console, and the program is now waiting for an incoming connection.</p>
+<p>You can see that in <a href="#fig-print-zigrun1" class="quarto-xref">Figure&nbsp;<span>7.1</span></a>. The message <code>Server Addr: 127.0.0.1:3490</code> is printed to the console, and the program is now waiting for an incoming connection.</p>
 <div id="fig-print-zigrun1" class="quarto-float quarto-figure quarto-figure-center anchored">
 <figure class="quarto-float quarto-float-fig figure">
 <div aria-describedby="fig-print-zigrun1-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
@@ -512,7 +512,7 @@ <h2 data-number="7.5" class="anchored" data-anchor-id="looking-at-the-current-st
 <p>Or, we could also open any web browser of our preference, and type the URL <code>localhost:3490</code>. OBS: <code>localhost</code> is the same thing as the IP <code>127.0.0.1</code>. When you press enter, and your web browser go to this address, first, the browser will probably print a message saying that “this page isn’t working”, and, then, it will probably change to a new message saying that “the site can’t be reached”.</p>
 <p>You get these “error messages” in the web browser, because it got no response back from the server. In other words, when the web browser connected to our server, it did send the HTTP Request through the established connection. Then, the web browser was expecting to receive a HTTP Response back, but it got no response from the server (we didn’t implemented the HTTP Response logic yet).</p>
 <p>But that is okay. We have achieved the result that we wanted for now, which is to connect to the server, and see the HTTP Request that was sent by the web browser (or by the Python script) to the server.</p>
-<p>If you comeback to the console that you left open when you have executed the program, you will see that the program finished its execution, and, a new message is printed in the console, which is the actual HTTP Request message that was sent by the web browser to the server. You can see this message at <a href="#fig-print-zigrun2" class="quarto-xref">Figure&nbsp;<span>7.2</span></a>.</p>
+<p>If you comeback to the console that you left open when you have executed the program, you will see that the program finished its execution, and, a new message is printed in the console, which is the actual HTTP Request message that was sent by the web browser to the server. You can see this message in <a href="#fig-print-zigrun2" class="quarto-xref">Figure&nbsp;<span>7.2</span></a>.</p>
 <div id="fig-print-zigrun2" class="quarto-float quarto-figure quarto-figure-center anchored">
 <figure class="quarto-float quarto-float-fig figure">
 <div aria-describedby="fig-print-zigrun2-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
@@ -544,7 +544,7 @@ <h2 data-number="7.6" class="anchored" data-anchor-id="sec-enum"><span class="he
     const acolor = PrimaryColorRGB.MAGENTA;
                                    ^~~~~~~</code></pre>
 <p>Behind the hood, enums in Zig work the same way that enums work in C. Each enum value is essentially represented as an integer. The first value in the set is represented as zero, then, the second value is one, … etc.</p>
-<p>One thing that we are going to learn on the next section is that enums can have methods in them. Wait… What? This is amazing! Yes, enums in Zig are similar to structs, and they can have private and public methods inside them.</p>
+<p>One thing that we are going to learn in the next section is that enums can have methods in them. Wait… What? This is amazing! Yes, enums in Zig are similar to structs, and they can have private and public methods inside them.</p>
 </section>
 <section id="implementing-the-server---part-2" class="level2" data-number="7.7">
 <h2 data-number="7.7" class="anchored" data-anchor-id="implementing-the-server---part-2"><span class="header-section-number">7.7</span> Implementing the server - Part 2</h2>
@@ -557,7 +557,7 @@ <h2 data-number="7.7" class="anchored" data-anchor-id="implementing-the-server--
 <section id="the-top-level-header" class="level3" data-number="7.7.1">
 <h3 data-number="7.7.1" class="anchored" data-anchor-id="the-top-level-header"><span class="header-section-number">7.7.1</span> The top-level header</h3>
 <p>The first line of text in a HTTP Request always come with the three most essential information about the request. These three key attributes of the HTTP Request are separated by a simple space in this first line of the request. The first information is the HTTP method that is being used in the request, second, we have the URI to which this HTTP Request is being sent to, and third, we have the version of the HTTP protocol that is being used in this HTTP Request.</p>
-<p>In the snippet below, you can find an example of this first line in a HTTP Request. First, we have the HTTP method of this request (<code>GET</code>). Many programmers refer to the URI component (<code>/users/list</code>) as the “API endpoint” to which the HTTP Request is being sent to. In the context of this specific request, since it is a GET request, you could also say that the URI component is the path to the resource we want to access, or, the path to the document (or the file) that we want to retrieve from the server.</p>
+<p>In the snippet below, you can find an example of this first line in a HTTP Request. First, we have the HTTP method of this request (<code>GET</code>). Many programmers refer to the URI component (<code>/users/list</code>) as the “API endpoint” to which the HTTP Request is being sent to. In the context of this specific request, since it’s a GET request, you could also say that the URI component is the path to the resource we want to access, or, the path to the document (or the file) that we want to retrieve from the server.</p>
 <pre><code>GET /users/list HTTP/1.1</code></pre>
 <p>Also, notice that this HTTP Request is using the version 1.1 of the HTTP protocol, which is the most popular version of the protocol used in the web.</p>
 </section>
@@ -570,7 +570,7 @@ <h3 data-number="7.7.2" class="anchored" data-anchor-id="the-list-of-http-header
 </section>
 <section id="the-body" class="level3" data-number="7.7.3">
 <h3 data-number="7.7.3" class="anchored" data-anchor-id="the-body"><span class="header-section-number">7.7.3</span> The body</h3>
-<p>The body comes after the list of HTTP headers, and it is an optional section of the HTTP Request, meaning that, not all HTTP Request will come with a body in it. For example, every HTTP Request that uses the GET method usually do not come with a body.</p>
+<p>The body comes after the list of HTTP headers, and it’s an optional section of the HTTP Request, meaning that, not all HTTP Requests will come with a body in them. For example, every HTTP Request that uses the GET method usually does not come with a body.</p>
 <p>Because a GET request is used to request data, instead of sending it to the server. So, the body section is more related to the POST method, which is a method that involves sending data to the server, to be processed and stored.</p>
 <p>Since we are going to support only the GET method in this project, it means that we also do not need to care about the body of the request.</p>
 </section>
@@ -585,7 +585,7 @@ <h3 data-number="7.7.4" class="anchored" data-anchor-id="creating-the-http-metho
 <li>DELETE;</li>
 <li>and some other methods.</li>
 </ul>
-<p>Each HTTP method is used for a specific type of task. The POST method for example is normally used to post some data into the destination. In other words, it is used to send some data to the HTTP server, so that it can be processed and stored by the server.</p>
+<p>Each HTTP method is used for a specific type of task. The POST method for example is normally used to post some data into the destination. In other words, it’s used to send some data to the HTTP server, so that it can be processed and stored by the server.</p>
 <p>As another example, the GET method is normally used to get content from the server. In other words, we use this method whenever we want the server to send some content back to us. It can be any type of content. It can be a web page, a document file, or some data in a JSON format.</p>
 <p>When a client sends a POST HTTP Request, the HTTP Response sent by the server normally have the sole purpose of letting the client know if the server processed and stored the data successfully. In contrast, when the server receives a GET HTTP Request, then, the server sends the content that the client asked for in the HTTP Response itself. This demonstrates that the method associated with the HTTP Request changes a lot on the dynamics and the roles that each party plays in the whole process.</p>
 <p>Since the HTTP method of the HTTP Request is identified by this very small and specific set of words, it would be interesting to create an enum structure to represent a HTTP method. This way, we can easily check if the HTTP Request we receive from the client is a HTTP method that we currently support in our small HTTP server project.</p>
@@ -596,9 +596,9 @@ <h3 data-number="7.7.4" class="anchored" data-anchor-id="creating-the-http-metho
 <span id="cb11-3"><a href="#cb11-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>Now, I think we should add two methods to this enum structure. One method is <code>is_supported()</code>, which will be a function that returns a boolean value, indicating if the input HTTP method is supported or not by our HTTP Server. The other is <code>init()</code>, which is a constructor function that takes a string as input, and tries to convert it into a <code>Method</code> value.</p>
-<p>But in order to build these functions, I will use a functionality from the Zig Standard Library, called <code>StaticStringMap()</code>. This function allows us to create a simple map from strings to enum values. In other words, we can use this map structure to map a string to the respective enum value. To some extent, this specific structure from the standard library works almost like a “hashtable” structure, and it is optimized for small sets of words, or, small sets of keys, which is our case here. We are going to talk more about hashtables in Zig at <a href="09-data-structures.html#sec-maps-hashtables" class="quarto-xref"><span>Section 11.2</span></a>.</p>
+<p>But in order to build these functions, I will use a functionality from the Zig Standard Library, called <code>StaticStringMap()</code>. This function allows us to create a simple map from strings to enum values. In other words, we can use this map structure to map a string to the respective enum value. To some extent, this specific structure from the standard library works almost like a “hashtable” structure, and it’s optimized for small sets of words, or, small sets of keys, which is our case here. We are going to talk more about hashtables in Zig in <a href="09-data-structures.html#sec-maps-hashtables" class="quarto-xref"><span>Section 11.2</span></a>.</p>
 <p>To use this “static string map” structure, you have to import it from the <code>std.static_string_map</code> module of the Zig Standard Library. Just to make things shorter and easier to type, I am going to import this function through a different and shorter name (<code>Map</code>).</p>
-<p>With <code>Map()</code> imported, we can just apply this function over the enum structure that we are going to use in the resulting map. In our case here, it is the <code>Method</code> enum structure that we declared at the last code example. Then, I call the <code>initComptime()</code> method with the map, i.e.&nbsp;the list of key-value pairs that we are going to use.</p>
+<p>With <code>Map()</code> imported, we can just apply this function over the enum structure that we are going to use in the resulting map. In our case here, it’s the <code>Method</code> enum structure that we declared at the last code example. Then, I call the <code>initComptime()</code> method with the map, i.e., the list of key-value pairs that we are going to use.</p>
 <p>You can see in the example below that I wrote this map using multiple anonymous struct literals. Inside the first (or “top-level”) struct literal, we have a list (or a sequence) of struct literals. Each struct literal in this list represents a separate key-value pair. The first element (or the key) in each key-value pair should always be a string value. While the second element should be a value from the enum structure that you have used inside the <code>Map()</code> function.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb12"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Map = std.static_string_map.StaticStringMap;</span>
@@ -630,7 +630,7 @@ <h3 data-number="7.7.4" class="anchored" data-anchor-id="creating-the-http-metho
 <section id="writing-the-parse-request-function" class="level3" data-number="7.7.5">
 <h3 data-number="7.7.5" class="anchored" data-anchor-id="writing-the-parse-request-function"><span class="header-section-number">7.7.5</span> Writing the parse request function</h3>
 <p>Now that we created the enum that represents our HTTP method, we should start to write the function responsible for actually parsing the HTTP Request.</p>
-<p>The first thing we can do, is to write a struct to represent the HTTP Request. Take the <code>Request</code> struct below as an example. It contains the three essential information from the “top-level” header (i.e.&nbsp;the first line) in the HTTP Request.</p>
+<p>The first thing we can do, is to write a struct to represent the HTTP Request. Take the <code>Request</code> struct below as an example. It contains the three essential information from the “top-level” header (i.e., the first line) in the HTTP Request.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb14"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Request = <span class="kw">struct</span> <span class="op">{</span></span>
 <span id="cb14-2"><a href="#cb14-2" aria-hidden="true" tabindex="-1"></a>    method: Method,</span>
@@ -650,7 +650,7 @@ <h3 data-number="7.7.5" class="anchored" data-anchor-id="writing-the-parse-reque
 <p>The <code>parse_request()</code> function should receive a string as input. This input string contains the entire HTTP Request message, and the parsing function should read and understand the individual parts of this message.</p>
 <p>Now, remember that for the purpose of this chapter, we care only about the first line in this message, which contains the “top-level header”, or, the three essential attributes about the HTTP Request, which are the HTTP method used, the URI and the HTTP version.</p>
 <p>Notice that I use the function <code>indexOfScalar()</code> in <code>parse_request()</code>. This function from the Zig Standard Library returns the first index where the scalar value that we provide happens in a string. In this case, I’m looking at the first occurrence of the new line character (<code>\n</code>). Because once again, we care only about the first line in the HTTP Request message. This is the line where we have the three information that we want to parse (version of HTTP, the HTTP method and the URI).</p>
-<p>Therefore, we are using this <code>indexOfScalar()</code> function to limit our parsing process to the first line in the message. Is also worth mentioning that, the <code>indexOfScalar()</code> function returns an optional value. That is why I use the <code>orelse</code> keyword to provide an alternative value, in case the value returned by the function is a null value.</p>
+<p>Therefore, we are using this <code>indexOfScalar()</code> function to limit our parsing process to the first line in the message. It’s also worth mentioning that, the <code>indexOfScalar()</code> function returns an optional value. That is why I use the <code>orelse</code> keyword to provide an alternative value, in case the value returned by the function is a null value.</p>
 <p>Since each of these three attributes are separated by a simple space, we could use the function <code>splitScalar()</code> from the Zig Standard Library to split the input string into sections by looking for every position that appears a simple space. In other words, this <code>splitScalar()</code> function is equivalent to the <code>split()</code> method in Python, or, the <code>std::getline()</code> function from C++, or the <code>strtok()</code> function in C.</p>
 <p>When you use this <code>splitScalar()</code> function, you get an iterator as the result. This iterator have a <code>next()</code> method that you can use to advance the iterator to the next position, or, to the next section of the splitted string. Note that, when you use <code>next()</code>, the method not only advances the iterator, but it also returns a slice to the current section of the splitted string as result.</p>
 <p>Now, if you want to get a slice to the current section of the splitted string, but not advance the iterator to the next position, you can use the <code>peek()</code> method. Both <code>next()</code> and <code>peek()</code> methods return an optional value, that is why I use the <code>?</code> method to unwrap these optional values.</p>
@@ -669,7 +669,7 @@ <h3 data-number="7.7.5" class="anchored" data-anchor-id="writing-the-parse-reque
 <span id="cb15-12"><a href="#cb15-12" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> request;</span>
 <span id="cb15-13"><a href="#cb15-13" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>As I described at <a href="01-zig-weird.html#sec-zig-strings" class="quarto-xref"><span>Section 1.8</span></a>, strings in Zig are simply arrays of bytes in the language. So, you will find lots of excellent utility functions to work directly with strings inside this <code>mem</code> module from the Zig Standard Library. We have described some of these useful utility functions already at <a href="01-zig-weird.html#sec-strings-useful-funs" class="quarto-xref"><span>Section 1.8.4</span></a>.</p>
+<p>As I described in <a href="01-zig-weird.html#sec-zig-strings" class="quarto-xref"><span>Section 1.8</span></a>, strings in Zig are simply arrays of bytes in the language. So, you will find lots of excellent utility functions to work directly with strings inside this <code>mem</code> module from the Zig Standard Library. We have described some of these useful utility functions already in <a href="01-zig-weird.html#sec-strings-useful-funs" class="quarto-xref"><span>Section 1.8.4</span></a>.</p>
 </section>
 <section id="using-the-parse-request-function" class="level3" data-number="7.7.6">
 <h3 data-number="7.7.6" class="anchored" data-anchor-id="using-the-parse-request-function"><span class="header-section-number">7.7.6</span> Using the parse request function</h3>
@@ -735,7 +735,7 @@ <h3 data-number="7.7.7" class="anchored" data-anchor-id="sending-the-http-respon
 <span id="cb18-20"><a href="#cb18-20" aria-hidden="true" tabindex="-1"></a>    _ = <span class="kw">try</span> conn.stream.write(message);</span>
 <span id="cb18-21"><a href="#cb18-21" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>Notice that both functions receives the connection object as input, and use the <code>write()</code> method to write the HTTP Response message directly into this communication channel. As result, the party in the other side of the connection (i.e.&nbsp;the client), will receive such message.</p>
+<p>Notice that both functions receives the connection object as input, and use the <code>write()</code> method to write the HTTP Response message directly into this communication channel. As result, the party in the other side of the connection (i.e., the client), will receive such message.</p>
 <p>Most real-world HTTP Servers will have a single function (or a single struct) to effectively handle the response. It gets the HTTP Request already parsed as input, and then, it tries to build the HTTP Response bit by bit, before the function sends it over the connection.</p>
 <p>We would also have a specialized struct to represent a HTTP Response, and a lot of methods that would be used to build each part or component of the response object. Take the <code>Response</code> struct created by the Javascript runtime Bun as an example. You can find this struct in the <a href="https://github.com/oven-sh/bun/blob/main/src/bun.js/webcore/response.zig"><code>response.zig</code> module</a><a href="#fn4" class="footnote-ref" id="fnref4" role="doc-noteref"><sup>4</sup></a> in their GitHub project.</p>
 </section>
@@ -744,7 +744,7 @@ <h3 data-number="7.7.7" class="anchored" data-anchor-id="sending-the-http-respon
 <h2 data-number="7.8" class="anchored" data-anchor-id="the-end-result"><span class="header-section-number">7.8</span> The end result</h2>
 <p>We can now, update once again our <code>main()</code> function to incorporate our new functions from the <code>response.zig</code> module. First, I need to import this module into our <code>main.zig</code> module, then, I add the function calls to <code>send_200()</code> and <code>send_404()</code>.</p>
 <p>Notice that I’m using if statements to decide which “response function” to call, based especially on the URI present in the HTTP Request. If the user asked for a content (or a document) that is not present in our server, we should respond with a 404 status code. But since we have just a simple HTTP server, with no real documents to send, we can just check if the URI is the root path (<code>/</code>) or not to decide which function to call.</p>
-<p>Also, notice that I’m using the function <code>std.mem.eql()</code> from the Zig Standard Library to check if the string from <code>uri</code> is equal or not the string <code>"/"</code>. We have described this function already at <a href="01-zig-weird.html#sec-strings-useful-funs" class="quarto-xref"><span>Section 1.8.4</span></a>, so, comeback to that section if you are not familiar yet with this function.</p>
+<p>Also, notice that I’m using the function <code>std.mem.eql()</code> from the Zig Standard Library to check if the string from <code>uri</code> is equal or not the string <code>"/"</code>. We have described this function already in <a href="01-zig-weird.html#sec-strings-useful-funs" class="quarto-xref"><span>Section 1.8.4</span></a>, so, comeback to that section if you are not familiar yet with this function.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb19"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb19-1"><a href="#cb19-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb19-2"><a href="#cb19-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> SocketConf = <span class="bu">@import</span>(<span class="st">"config.zig"</span>);</span>
diff --git a/docs/Chapters/05-pointers.html b/docs/Chapters/05-pointers.html
index 1bc398f2..25812334 100644
--- a/docs/Chapters/05-pointers.html
+++ b/docs/Chapters/05-pointers.html
@@ -333,8 +333,8 @@ <h1 class="title"><span id="sec-pointer" class="quarto-section-identifier"><span
 
 
 <p>On our next project we are going to build a HTTP server from scratch. But in order to do that, we need to learn more about pointers and how they work in Zig. Pointers in Zig are similar to pointers in C. But they come with some extra advantages in Zig.</p>
-<p>A pointer is an object that contains a memory address. This memory address is the address where a particular value is stored in memory. It can be any value. Most of the times, it is a value that comes from another object (or variable) present in our code.</p>
-<p>In the example below, I’m creating two objects (<code>number</code> and <code>pointer</code>). The <code>pointer</code> object contains the memory address where the value of the <code>number</code> object (the number 5) is stored. So, that is a pointer in a nutshell. It is a memory address that points to a particular existing value in the memory. You could also say, that, the <code>pointer</code> object points to the memory address where the <code>number</code> object is stored.</p>
+<p>A pointer is an object that contains a memory address. This memory address is the address where a particular value is stored in memory. It can be any value. Most of the times, it’s a value that comes from another object (or variable) present in our code.</p>
+<p>In the example below, I’m creating two objects (<code>number</code> and <code>pointer</code>). The <code>pointer</code> object contains the memory address where the value of the <code>number</code> object (the number 5) is stored. So, that is a pointer in a nutshell. It’s a memory address that points to a particular existing value in the memory. You could also say, that, the <code>pointer</code> object points to the memory address where the <code>number</code> object is stored.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb1"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> number: <span class="dt">u8</span> = <span class="dv">5</span>;</span>
 <span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> pointer = &amp;number;</span>
@@ -351,7 +351,7 @@ <h1 class="title"><span id="sec-pointer" class="quarto-section-identifier"><span
 <pre><code>10</code></pre>
 </div>
 </div>
-<p>This syntax to dereference the pointer is nice. Because we can easily chain it with methods of the value pointed by the pointer. We can use the <code>User</code> struct that we have created at <a href="03-structs.html#sec-structs-and-oop" class="quarto-xref"><span>Section 2.3</span></a> as an example. If you comeback to that section, you will see that this struct have a method named <code>print_name()</code>.</p>
+<p>This syntax to dereference the pointer is nice. Because we can easily chain it with methods of the value pointed by the pointer. We can use the <code>User</code> struct that we have created in <a href="03-structs.html#sec-structs-and-oop" class="quarto-xref"><span>Section 2.3</span></a> as an example. If you comeback to that section, you will see that this struct have a method named <code>print_name()</code>.</p>
 <p>So, for example, if we have an user object, and a pointer that points to this user object, we can use the pointer to access this user object, and, at the same time, call the method <code>print_name()</code> on it, by chaining the dereference method (<code>*</code>) with the <code>print_name()</code> method. Like in the example below:</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb4"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> u = User.init(<span class="dv">1</span>, <span class="st">"pedro"</span>, <span class="st">"email@gmail.com"</span>);</span>
@@ -369,12 +369,12 @@ <h1 class="title"><span id="sec-pointer" class="quarto-section-identifier"><span
 <pre><code>6</code></pre>
 </div>
 </div>
-<p>Therefore, as I mentioned earlier, people use pointers as an alternative way to access a particular value. And they use it especially when they do not want to “move” these values around. There are situations where, you want to access a particular value in a different scope (i.e.&nbsp;a different location) of your code, but you do not want to “move” this value to this new scope (or location) that you are in.</p>
+<p>Therefore, as I mentioned earlier, people use pointers as an alternative way to access a particular value. And they use it especially when they do not want to “move” these values around. There are situations where, you want to access a particular value in a different scope (i.e., a different location) of your code, but you do not want to “move” this value to this new scope (or location) that you are in.</p>
 <p>This matters especially if this value is big in size. Because if it is, then, moving this value becomes an expensive operation to do. The computer will have to spend a considerable amount of time copying this value to this new location.</p>
 <p>Therefore, many programmers prefer to avoid this heavy operation of copying the value to the new location, by accessing this value through pointers. We are going to talk more about this “moving operation” over the next sections. For now, just keep in mind that avoiding this “move operation” is one of main reasons why pointers are used in programming languages.</p>
 <section id="sec-pointer-var" class="level2" data-number="6.1">
 <h2 data-number="6.1" class="anchored" data-anchor-id="sec-pointer-var"><span class="header-section-number">6.1</span> Constant objects vs variable objects</h2>
-<p>You can have a pointer that points to a constant object, or, a pointer that points to a variable object. But regardless of who this pointer is, a pointer <strong>must always respect the characteristics of the object that it points to</strong>. As a consequence, if the pointer points to a constant object, then, you cannot use this pointer to change the value that it points to. Because it points to a value that is constant. As we discussed at <a href="01-zig-weird.html#sec-assignments" class="quarto-xref"><span>Section 1.4</span></a>, you cannot change a value that is constant.</p>
+<p>You can have a pointer that points to a constant object, or, a pointer that points to a variable object. But regardless of who this pointer is, a pointer <strong>must always respect the characteristics of the object that it points to</strong>. As a consequence, if the pointer points to a constant object, then, you cannot use this pointer to change the value that it points to. Because it points to a value that is constant. As we discussed in <a href="01-zig-weird.html#sec-assignments" class="quarto-xref"><span>Section 1.4</span></a>, you cannot change a value that is constant.</p>
 <p>For example, if I have a <code>number</code> object, which is constant, I cannot execute the expression below where I’m trying to change the value of <code>number</code> to 6 through the <code>pointer</code> object. As demonstrated below, when you try to do something like that, you get a compile time error:</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb8"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> number = <span class="dv">5</span>;</span>
@@ -396,7 +396,7 @@ <h2 data-number="6.1" class="anchored" data-anchor-id="sec-pointer-var"><span cl
 <p>You can see this relationship between “constant versus variable” on the data type of your pointer object. In other words, the data type of a pointer object already gives you some clues about whether the value that it points to is constant or not.</p>
 <p>When a pointer object points to a constant value, then, this pointer have a data type <code>*const T</code>, which means “a pointer to a constant value of type <code>T</code>”. In contrast, if the pointer points to a variable value, then, the type of the pointer is usually <code>*T</code>, which is simply “a pointer to a value of type <code>T</code>”. Hence, whenever you see a pointer object whose data type is in the format <code>*const T</code>, then, you know that you cannot use this pointer to change the value that it points to. Because this pointer points to a constant value of type <code>T</code>.</p>
 <p>We have talked about the value pointed by the pointer being constant or not, and the consequences that arises from it. But, what about the pointer object itself? I mean, what happens if the pointer object itself is constant or not? Think about it. We can have a constant pointer that points to a constant value. But we can also have a variable pointer that points to a constant value. And vice-versa.</p>
-<p>Until this point, the <code>pointer</code> object was always constant, but what this means for us? What is the consequence of the <code>pointer</code> object being constant? The consequence is that we cannot change the pointer object, because it is constant. We can use the pointer object in multiple ways, but we cannot change the memory address that is inside this pointer object.</p>
+<p>Until this point, the <code>pointer</code> object was always constant, but what does this mean for us? What is the consequence of the <code>pointer</code> object being constant? The consequence is that we cannot change the pointer object, because it is constant. We can use the pointer object in multiple ways, but we cannot change the memory address that is inside this pointer object.</p>
 <p>However, if we mark the <code>pointer</code> object as a variable object, then, we can change the memory address pointed by this <code>pointer</code> object. The example below demonstrates that. Notice that the object pointed by the <code>pointer</code> object changes from <code>c1</code> to <code>c2</code>.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb12"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> c1: <span class="dt">u8</span> = <span class="dv">5</span>;</span>
@@ -437,9 +437,9 @@ <h2 data-number="6.3" class="anchored" data-anchor-id="pointer-arithmetic"><span
 <pre><code>1
 2
 3</code></pre>
-<p>Although you can create a pointer to an array like that, and start to walk through this array by using pointer arithmetic, in Zig, we prefer to use slices, which were presented at <a href="01-zig-weird.html#sec-arrays" class="quarto-xref"><span>Section 1.6</span></a>.</p>
+<p>Although you can create a pointer to an array like that, and start to walk through this array by using pointer arithmetic, in Zig, we prefer to use slices, which were presented in <a href="01-zig-weird.html#sec-arrays" class="quarto-xref"><span>Section 1.6</span></a>.</p>
 <p>Behind the hood, slices already are pointers, and they also come with the <code>len</code> property, which indicates how many elements are in the slice. This is good because the <code>zig</code> compiler can use it to check for potential buffer overflows, and other problems like that.</p>
-<p>Also, you don’t need to use pointer arithmetic to walk through the elements of a slice. You can simply use the <code>slice[index]</code> syntax to directly access any element you want in the slice. As I mentioned at <a href="01-zig-weird.html#sec-arrays" class="quarto-xref"><span>Section 1.6</span></a>, you can get a slice from an array by using a range selector inside brackets. In the example below, I’m creating a slice (<code>sl</code>) that covers the entire <code>ar</code> array. I can access any element of <code>ar</code> from this slice, and, the slice itself already is a pointer behind the hood.</p>
+<p>Also, you don’t need to use pointer arithmetic to walk through the elements of a slice. You can simply use the <code>slice[index]</code> syntax to directly access any element you want in the slice. As I mentioned in <a href="01-zig-weird.html#sec-arrays" class="quarto-xref"><span>Section 1.6</span></a>, you can get a slice from an array by using a range selector inside brackets. In the example below, I’m creating a slice (<code>sl</code>) that covers the entire <code>ar</code> array. I can access any element of <code>ar</code> from this slice, and, the slice itself already is a pointer behind the hood.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb16"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ar = [_]<span class="dt">i32</span><span class="op">{</span><span class="dv">1</span>,<span class="dv">2</span>,<span class="dv">3</span>,<span class="dv">4</span><span class="op">}</span>;</span>
 <span id="cb16-2"><a href="#cb16-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> sl = ar[<span class="dv">0</span>..ar.len];</span>
@@ -474,7 +474,7 @@ <h3 data-number="6.4.1" class="anchored" data-anchor-id="what-are-optionals"><sp
 <section id="optional-pointers" class="level3" data-number="6.4.2">
 <h3 data-number="6.4.2" class="anchored" data-anchor-id="optional-pointers"><span class="header-section-number">6.4.2</span> Optional pointers</h3>
 <p>You can also mark a pointer object as an optional pointer, meaning that, this object contains either a null value, or, a pointer that points to a value. When you mark a pointer as optional, the data type of this pointer object becomes <code>?*const T</code> or <code>?*T</code>, depending if the value pointed by the pointer is a constant value or not. The <code>?</code> identifies the object as optional, while the <code>*</code> identifies it as a pointer object.</p>
-<p>In the example below, we are creating a variable object named <code>num</code>, and an optional pointer object named <code>ptr</code>. Notice that the data type of the object <code>ptr</code> indicates that it is either a null value, or a pointer to an <code>i32</code> value. Also, notice that the pointer object (<code>ptr</code>) can be marked as optional, even if the object <code>num</code> is not optional.</p>
+<p>In the example below, we are creating a variable object named <code>num</code>, and an optional pointer object named <code>ptr</code>. Notice that the data type of the object <code>ptr</code> indicates that it’s either a null value, or a pointer to an <code>i32</code> value. Also, notice that the pointer object (<code>ptr</code>) can be marked as optional, even if the object <code>num</code> is not optional.</p>
 <p>What this code tells us is that, the <code>num</code> variable will never contain a null value. This variable will always contain a valid <code>i32</code> value. But in contrast, the <code>ptr</code> object might contain either a null value, or, a pointer to an <code>i32</code> value.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb20"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb20-1"><a href="#cb20-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> num: <span class="dt">i32</span> = <span class="dv">5</span>;</span>
@@ -493,7 +493,7 @@ <h3 data-number="6.4.2" class="anchored" data-anchor-id="optional-pointers"><spa
 </section>
 <section id="sec-null-handling" class="level3" data-number="6.4.3">
 <h3 data-number="6.4.3" class="anchored" data-anchor-id="sec-null-handling"><span class="header-section-number">6.4.3</span> Null handling in optionals</h3>
-<p>When you have an optional object in your Zig code, you have to explicitly handle the possibility of this object being null. It is like error-handling with <code>try</code> and <code>catch</code>. In Zig you also have to handle null values like if they were a type of error.</p>
+<p>When you have an optional object in your Zig code, you have to explicitly handle the possibility of this object being null. It’s like error-handling with <code>try</code> and <code>catch</code>. In Zig you also have to handle null values like if they were a type of error.</p>
 <p>We can do that, by using either:</p>
 <ul>
 <li>an if statement, like you would do in C.</li>
diff --git a/docs/Chapters/07-build-system.html b/docs/Chapters/07-build-system.html
index 1ea868f0..ed90246f 100644
--- a/docs/Chapters/07-build-system.html
+++ b/docs/Chapters/07-build-system.html
@@ -322,11 +322,11 @@ <h1 class="title"><span id="sec-build-system" class="quarto-section-identifier">
 
 
 <p>In this chapter, we are going to talk about the build system, and how an entire project is built in Zig. One key advantage of Zig is that it includes a build system embedded in the language itself. This is great, because then you do not have to depend on an external system, separated from the compiler, to build your code.</p>
-<p>You can find a good description of Zig’s build system on the <a href="https://ziglang.org/learn/build-system/#user-provided-options">article entitled “Build System”</a><a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a> from the official Zig’s website. We also have the excellent <a href="https://zig.news/xq/zig-build-explained-part-1-59lf">series of posts written by Felix</a><a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a>. Hence, this chapter represents an extra resource for you to consult and rely on.</p>
+<p>You can find a good description of Zig’s build system in the <a href="https://ziglang.org/learn/build-system/#user-provided-options">article entitled “Build System”</a><a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a> from the official Zig’s website. We also have the excellent <a href="https://zig.news/xq/zig-build-explained-part-1-59lf">series of posts written by Felix</a><a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a>. Hence, this chapter represents an extra resource for you to consult and rely on.</p>
 <p>Building code is one of the things that Zig is best at. One thing that is particularly difficult in C/C++ and even in Rust, is to cross-compile source code to multiple targets (e.g.&nbsp;multiple computer architectures and operating systems), and the <code>zig</code> compiler is known for being one of the best existing pieces of software for this particular task.</p>
 <section id="how-source-code-is-built" class="level2" data-number="9.1">
 <h2 data-number="9.1" class="anchored" data-anchor-id="how-source-code-is-built"><span class="header-section-number">9.1</span> How source code is built?</h2>
-<p>We already have talked about the challenges of building source code in low-level languages at <a href="01-zig-weird.html#sec-project-files" class="quarto-xref"><span>Section 1.2.1</span></a>. As we described at that section, programmers invented Build Systems to surpass these challenges on the process of building source code in low-level languages.</p>
+<p>We already have talked about the challenges of building source code in low-level languages in <a href="01-zig-weird.html#sec-project-files" class="quarto-xref"><span>Section 1.2.1</span></a>. As we described at that section, programmers invented Build Systems to surpass these challenges on the process of building source code in low-level languages.</p>
 <p>Low-level languages uses a compiler to compile (or to build) your source code into binary instructions. In C and C++, we normally use compilers like <code>gcc</code>, <code>g++</code> or <code>clang</code> to compile our C and C++ source code into these instructions. Every language have its own compiler, and this is no different in Zig.</p>
 <p>In Zig, we have the <code>zig</code> compiler to compile our Zig source code into binary instructions that can be executed by our computer. In Zig, the compilation (or the build) process involves the following components:</p>
 <ul>
@@ -335,7 +335,7 @@ <h2 data-number="9.1" class="anchored" data-anchor-id="how-source-code-is-built"
 <li>Compiler flags that tailors the build process to your needs.</li>
 </ul>
 <p>These are the things that you need to connect together in order to build your source code in Zig. In C and C++, you would have an extra component, which are the header files of the libraries that you are using. But header files do not exist in Zig, so, you only need to care about them if you are linking your Zig source code with a C library. If that is not your case, you can forget about it.</p>
-<p>Your build process is usually organized in a build script. In Zig, we normally write this build script into a Zig module in the root directory of our project, named as <code>build.zig</code>. You write this build script, then, when you run it, your project get’s built into binary files that you can use and distribute to your users.</p>
+<p>Your build process is usually organized in a build script. In Zig, we normally write this build script into a Zig module in the root directory of our project, named as <code>build.zig</code>. You write this build script, then, when you run it, your project gets built into binary files that you can use and distribute to your users.</p>
 <p>This build script is normally organized around <em>target objects</em>. A target is simply something to be built, or, in other words, it’s something that you want the <code>zig</code> compiler to build for you. This concept of “targets” is present in most Build Systems, especially in CMake<a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a>.</p>
 <p>There are four types of target objects that you can build in Zig, which are:</p>
 <ul>
@@ -344,11 +344,11 @@ <h2 data-number="9.1" class="anchored" data-anchor-id="how-source-code-is-built"
 <li>A static library (e.g.&nbsp;a <code>.a</code> file in Linux or a <code>.lib</code> file on Windows).</li>
 <li>An executable file that executes only unit tests (or, a “unit tests executable”).</li>
 </ul>
-<p>We are going to talk more about these target objects at <a href="#sec-targets" class="quarto-xref"><span>Section 9.3</span></a>.</p>
+<p>We are going to talk more about these target objects in <a href="#sec-targets" class="quarto-xref"><span>Section 9.3</span></a>.</p>
 </section>
 <section id="sec-build-fun" class="level2" data-number="9.2">
 <h2 data-number="9.2" class="anchored" data-anchor-id="sec-build-fun"><span class="header-section-number">9.2</span> The <code>build()</code> function</h2>
-<p>A build script in Zig always contains a public (and top-level) <code>build()</code> function declared. It is like the <code>main()</code> function on the main Zig module of your project, that we discussed at <a href="01-zig-weird.html#sec-main-file" class="quarto-xref"><span>Section 1.2.3</span></a>. But instead of creating the entrypoint to your code, this <code>build()</code> function is the entrypoint to the build process.</p>
+<p>A build script in Zig always contains a public (and top-level) <code>build()</code> function declared. It’s like the <code>main()</code> function in the main Zig module of your project, that we discussed in <a href="01-zig-weird.html#sec-main-file" class="quarto-xref"><span>Section 1.2.3</span></a>. But instead of creating the entrypoint to your code, this <code>build()</code> function is the entrypoint to the build process.</p>
 <p>This <code>build()</code> function should accept a pointer to a <code>Build</code> object as input, and it should use this “build object” to perform the necessary steps to build your project. The return type of this function is always <code>void</code>, and this <code>Build</code> struct comes directly from the Zig Standard Library (<code>std.Build</code>). So, you can access this struct by just importing the Zig Standard Library into your <code>build.zig</code> module.</p>
 <p>Just as a very simple example, here you can see the source code necessary to build an executable file from the <code>hello.zig</code> Zig module.</p>
 <div class="cell">
@@ -368,7 +368,7 @@ <h2 data-number="9.2" class="anchored" data-anchor-id="sec-build-fun"><span clas
 <h2 data-number="9.3" class="anchored" data-anchor-id="sec-targets"><span class="header-section-number">9.3</span> Target objects</h2>
 <p>As we described over the previous sections, a build script is composed around target objects. Each target object is normally a binary file (or an output) that you want to get from the build process. You can list multiple target objects in your build script, so that the build process generates multiple binary files for you at once.</p>
 <p>For example, maybe you are a developer working in a cross-platform application, and, because this application is cross-platform, you probably need to release binary files of your software for each OS supported by your application to your end users. Thus, you can define a different target object in your build script for each OS (Windows, Linux, etc.) where you want to publish your software. This will make the <code>zig</code> compiler to build your project to multiple target OS’s at once. The Zig Build System official documentation have a <a href="https://ziglang.org/learn/build-system/#handy-examples">great code example that demonstrates this strategy</a><a href="#fn4" class="footnote-ref" id="fnref4" role="doc-noteref"><sup>4</sup></a>.</p>
-<p>A target object is created by the following methods of the <code>Build</code> struct that we introduced at <a href="#sec-build-fun" class="quarto-xref"><span>Section 9.2</span></a>:</p>
+<p>A target object is created by the following methods of the <code>Build</code> struct that we introduced in <a href="#sec-build-fun" class="quarto-xref"><span>Section 9.2</span></a>:</p>
 <ul>
 <li><code>addExecutable()</code> creates an executable file;</li>
 <li><code>addSharedLibrary()</code> creates a shared library file;</li>
@@ -384,11 +384,11 @@ <h2 data-number="9.3" class="anchored" data-anchor-id="sec-targets"><span class=
 <span id="cb2-4"><a href="#cb2-4" aria-hidden="true" tabindex="-1"></a>    .target = b.host,</span>
 <span id="cb2-5"><a href="#cb2-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>The <code>name</code> option specify the name that you want to give to the binary file defined by this target object. So, in this example, we are building an executable file named <code>hello</code>. Is common to set this <code>name</code> option to the name of your project.</p>
+<p>The <code>name</code> option specify the name that you want to give to the binary file defined by this target object. So, in this example, we are building an executable file named <code>hello</code>. It’s common to set this <code>name</code> option to the name of your project.</p>
 <p>Furthermore, the <code>target</code> option specify the target computer architecture (or the target operating system) of this binary file. For example, if you want this target object to run on a Windows machine that uses a <code>x86_64</code> architecture, you can set this <code>target</code> option to <code>x86_64-windows-gnu</code> for example. This will make the <code>zig</code> compiler to compile the project to run on a <code>x86_64</code> Windows machine. You can see the full list of architectures and OS’s that the <code>zig</code> compiler supports by running the <code>zig targets</code> command in the terminal.</p>
 <p>Now, if you are building the project to run on the current machine that you are using to run this build script, you can set this <code>target</code> option to the <code>host</code> method of the <code>Build</code> object, like we did in the example above. This <code>host</code> method identifies the current machine where you are currently running the <code>zig</code> compiler.</p>
-<p>At last, the <code>root_source_file</code> option specifies the root Zig module of your project. That is the Zig module that contains the entrypoint to your application (i.e.&nbsp;the <code>main()</code> function), or, the main API of your library. This also means that, all the Zig modules that compose your project are automatically discovered from the import statements you have inside this “root source file”. The <code>zig</code> compiler can detect when a Zig module depends on the other through the import statements, and, as a result, it can discover the entire map of Zig modules used in your project.</p>
-<p>This is handy, and it is different from what happens in other build systems. In CMake for example, you have to explicitly list the paths to all source files that you want to include in your build process. This is probably a symptom of the “lack of conditional compilation” in the C and C++ compilers. Since they lack this feature, you have to explicitly choose which source files should be sent to the C/C++ compiler, because not every C/C++ code is portable or supported in every operating system, and, therefore, would cause a compilation error in the C/C++ compiler.</p>
+<p>At last, the <code>root_source_file</code> option specifies the root Zig module of your project. That is the Zig module that contains the entrypoint to your application (i.e., the <code>main()</code> function), or, the main API of your library. This also means that, all the Zig modules that compose your project are automatically discovered from the import statements you have inside this “root source file”. The <code>zig</code> compiler can detect when a Zig module depends on the other through the import statements, and, as a result, it can discover the entire map of Zig modules used in your project.</p>
+<p>This is handy, and it’s different from what happens in other build systems. In CMake for example, you have to explicitly list the paths to all source files that you want to include in your build process. This is probably a symptom of the “lack of conditional compilation” in the C and C++ compilers. Since they lack this feature, you have to explicitly choose which source files should be sent to the C/C++ compiler, because not every C/C++ code is portable or supported in every operating system, and, therefore, would cause a compilation error in the C/C++ compiler.</p>
 <p>Now, one important detail about the build process is that, you have to <strong>explicitly install the target objects that you create in your build script</strong>, by using the <code>installArtifact()</code> method of the <code>Build</code> struct.</p>
 <p>Everytime you invoke the build process of your project, by calling the <code>build</code> command of the <code>zig</code> compiler, a new directory named <code>zig-out</code> is created in the root directory of your project. This new directory contains the outputs of the build process, that is, the binary files built from your source code.</p>
 <p>What the <code>installArtifact()</code> method do is to install (or copy) the built target objects that you defined to this <code>zig-out</code> directory. This means that, if you do not install the target objects you define in your build script, these target objects are essentially discarded at the end of the build process.</p>
@@ -407,9 +407,9 @@ <h2 data-number="9.3" class="anchored" data-anchor-id="sec-targets"><span class=
 <section id="setting-the-build-mode" class="level2" data-number="9.4">
 <h2 data-number="9.4" class="anchored" data-anchor-id="setting-the-build-mode"><span class="header-section-number">9.4</span> Setting the build mode</h2>
 <p>We have talked about the three essential options that are set when you create a new target object. But there is also a fourth option that you can use to set the build mode of this target object, which is the <code>optimize</code> option. This option is called this way, because the build modes in Zig are treated more of an “optimization vs safety” problem. So optimization plays an important role here. Don’t worry, I’m going back to this question very soon.</p>
-<p>In Zig, we have four build modes (which are listed below). Each one of these build modes offer different advantages and characteristics. As we described at <a href="02-debugging.html#sec-compile-debug-mode" class="quarto-xref"><span>Section 5.2.1</span></a>, the <code>zig</code> compiler uses the <code>Debug</code> build mode by default, when you don’t explicitly choose a build mode.</p>
+<p>In Zig, we have four build modes (which are listed below). Each one of these build modes offer different advantages and characteristics. As we described in <a href="02-debugging.html#sec-compile-debug-mode" class="quarto-xref"><span>Section 5.2.1</span></a>, the <code>zig</code> compiler uses the <code>Debug</code> build mode by default, when you don’t explicitly choose a build mode.</p>
 <ul>
-<li><code>Debug</code>, mode that produces and includes debugging information in the output of the build process (i.e.&nbsp;the binary file defined by the target object);</li>
+<li><code>Debug</code>, mode that produces and includes debugging information in the output of the build process (i.e., the binary file defined by the target object);</li>
 <li><code>ReleaseSmall</code>, mode that tries to produce a binary file that is small in size;</li>
 <li><code>ReleaseFast</code>, mode that tries to optimize your code, in order to produce a binary file that is as fast as possible;</li>
 <li><code>ReleaseSafe</code>, mode that tries to make your code as safe as possible, by including safeguards when possible.</li>
@@ -444,7 +444,7 @@ <h2 data-number="9.5" class="anchored" data-anchor-id="setting-the-version-of-yo
 </section>
 <section id="sec-detect-os" class="level2" data-number="9.6">
 <h2 data-number="9.6" class="anchored" data-anchor-id="sec-detect-os"><span class="header-section-number">9.6</span> Detecting the OS in your build script</h2>
-<p>Is very common in Build Systems to use different options, or, to include different modules, or, to link against different libraries depending on the Operational System (OS) that you are targeting in the build process.</p>
+<p>It’s very common in Build Systems to use different options, or, to include different modules, or, to link against different libraries depending on the Operational System (OS) that you are targeting in the build process.</p>
 <p>In Zig, you can detect the target OS of the build process, by looking at the <code>os.tag</code> inside the <code>builtin</code> module from the Zig library. In the example below, we are using an if statement to run some arbitrary code when the target of the build process is a Windows system.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb6"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> builtin = <span class="bu">@import</span>(<span class="st">"builtin"</span>);</span>
@@ -456,7 +456,7 @@ <h2 data-number="9.6" class="anchored" data-anchor-id="sec-detect-os"><span clas
 </section>
 <section id="adding-a-run-step-to-your-build-process" class="level2" data-number="9.7">
 <h2 data-number="9.7" class="anchored" data-anchor-id="adding-a-run-step-to-your-build-process"><span class="header-section-number">9.7</span> Adding a run step to your build process</h2>
-<p>One thing that is neat in Rust is that you can compile and run your source code with one single command (<code>cargo run</code>) from the Rust compiler. We saw at <a href="01-zig-weird.html#sec-compile-run-code" class="quarto-xref"><span>Section 1.2.5</span></a> how can we perform a similar job in Zig, by building and running our Zig source code through the <code>run</code> command from the <code>zig</code> compiler.</p>
+<p>One thing that is neat in Rust is that you can compile and run your source code with one single command (<code>cargo run</code>) from the Rust compiler. We saw in <a href="01-zig-weird.html#sec-compile-run-code" class="quarto-xref"><span>Section 1.2.5</span></a> how can we perform a similar job in Zig, by building and running our Zig source code through the <code>run</code> command from the <code>zig</code> compiler.</p>
 <p>But how can we, at the same time, build and run the binary file specified by a target object in our build script? The answer is by including a “run artifact” in our build script. A run artifact is created through the <code>addRunArtifact()</code> method from the <code>Build</code> struct. We simply provide as input to this function the target object that describes the binary file that we want to execute. As a result, this function creates a run artifact that is capable of executing this binary file.</p>
 <p>In the example below, we are defining an executable binary file named <code>hello</code>, and we use this <code>addRunArtifact()</code> method to create a run artifact that will execute this <code>hello</code> executable file.</p>
 <div class="cell">
@@ -492,8 +492,8 @@ <h2 data-number="9.7" class="anchored" data-anchor-id="adding-a-run-step-to-your
 </section>
 <section id="build-unit-tests-in-your-project" class="level2" data-number="9.8">
 <h2 data-number="9.8" class="anchored" data-anchor-id="build-unit-tests-in-your-project"><span class="header-section-number">9.8</span> Build unit tests in your project</h2>
-<p>We have talked at length about writing unit tests in Zig at <a href="03-unittests.html" class="quarto-xref"><span>Chapter 8</span></a>, and we also have talked about how to execute these unit tests through the <code>test</code> command of the <code>zig</code> compiler. However, as we did with the <code>run</code> command on the previous section, we also might want to include some commands in our build script to also build and execute the unit tests in our project.</p>
-<p>So, once again, we are going to discuss how a specific built-in command from the <code>zig</code> compiler, (in this case, the <code>test</code> command) can be used in a build script in Zig. Here is where a “test target object” comes into play. As was described at <a href="#sec-targets" class="quarto-xref"><span>Section 9.3</span></a>, we can create a test target object by using the <code>addTest()</code> method of the <code>Build</code> struct. The first thing that we need to do is to declare a test target object in our build script.</p>
+<p>We have talked at length about writing unit tests in Zig in <a href="03-unittests.html" class="quarto-xref"><span>Chapter 8</span></a>, and we also have talked about how to execute these unit tests through the <code>test</code> command of the <code>zig</code> compiler. However, as we did with the <code>run</code> command on the previous section, we also might want to include some commands in our build script to also build and execute the unit tests in our project.</p>
+<p>So, once again, we are going to discuss how a specific built-in command from the <code>zig</code> compiler, (in this case, the <code>test</code> command) can be used in a build script in Zig. Here is where a “test target object” comes into play. As was described in <a href="#sec-targets" class="quarto-xref"><span>Section 9.3</span></a>, we can create a test target object by using the <code>addTest()</code> method of the <code>Build</code> struct. The first thing that we need to do is to declare a test target object in our build script.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb13"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> test_exe = b.addTest(.<span class="op">{</span></span>
 <span id="cb13-2"><a href="#cb13-2" aria-hidden="true" tabindex="-1"></a>    .name = <span class="st">"unit_tests"</span>,</span>
@@ -502,7 +502,7 @@ <h2 data-number="9.8" class="anchored" data-anchor-id="build-unit-tests-in-your-
 <span id="cb13-5"><a href="#cb13-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>);</span>
 <span id="cb13-6"><a href="#cb13-6" aria-hidden="true" tabindex="-1"></a>b.installArtifact(test_exe);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>A test target object essentially selects all <code>test</code> blocks in all Zig modules across your project, and builds only the source code present inside these <code>test</code> blocks in your project. As a result, this target object creates an executable file that contains only the source code present in all of these <code>test</code> blocks (i.e.&nbsp;the unit tests) in your project.</p>
+<p>A test target object essentially selects all <code>test</code> blocks in all Zig modules across your project, and builds only the source code present inside these <code>test</code> blocks in your project. As a result, this target object creates an executable file that contains only the source code present in all of these <code>test</code> blocks (i.e., the unit tests) in your project.</p>
 <p>Perfect! Now that we have declared this test target object, an executable file named <code>unit_tests</code> is built by the <code>zig</code> compiler when we trigger the build script with the <code>build</code> command. After the build process is finished, we can simply execute this <code>unit_tests</code> executable in the terminal.</p>
 <p>However, if you remember the previous section, we already learned how can we create a run step in our build script, to execute an executable file built by the build script.</p>
 <p>So, we could simply add a run step in our build script to run these unit tests from a single command in the <code>zig</code> compiler, to make our lifes easier. In the example below, we demonstrate the commands to register a new build step called “tests” in our build script to run these unit tests.</p>
@@ -543,7 +543,7 @@ <h2 data-number="9.9" class="anchored" data-anchor-id="tailoring-your-build-proc
 <section id="linking-to-external-libraries" class="level2" data-number="9.10">
 <h2 data-number="9.10" class="anchored" data-anchor-id="linking-to-external-libraries"><span class="header-section-number">9.10</span> Linking to external libraries</h2>
 <p>One essential part of every build process is the linking stage. This stage is responsible for combining the multiple object files that represent your code, into a single executable file. It also links this executable file to external libraries, if you use any in your code.</p>
-<p>In Zig, we have two notions of a “library”, which are: 1) a system’s library; 2) a local library. A system’s library is just a library that already is installed in your system. While a local library is a library that belongs to the current project. Is a library that is present in your project directory, and that you are building together with your project source code.</p>
+<p>In Zig, we have two notions of a “library”, which are: 1) a system’s library; 2) a local library. A system’s library is just a library that is already installed in your system. While a local library is a library that belongs to the current project; a library that is present in your project directory, and that you are building together with your project source code.</p>
 <p>The basic difference between the two, is that a system’s library is already built and installed in your system, supposedly, and all you need to do is to link your source code to this library to start using it. We do that by using the <code>linkSystemLibrary()</code> method from a <code>Compile</code> object. This method accepts the name of the library in a string as input. Remember from <a href="#sec-targets" class="quarto-xref"><span>Section 9.3</span></a> that a <code>Compile</code> object is a target object that you declare in your build script.</p>
 <p>When you link a particular target object with a system’s library, the <code>zig</code> compiler will use <code>pkg-config</code> to find where are the binary files and also the header files of this library in your system. When it finds these files, the linker present in the <code>zig</code> compiler will link your object files with the files of this library to produce a single binary file for you.</p>
 <p>In the example below, we are creating an executable file named <code>image_filter</code>, and, we are linking this executable file to the C Standard Library with the method <code>linkLibC()</code>, but we also are linking this executable file to the C library <code>libpng</code> that is currently installed in my system.</p>
@@ -588,7 +588,7 @@ <h2 data-number="9.10" class="anchored" data-anchor-id="linking-to-external-libr
 <section id="sec-building-c-code" class="level2" data-number="9.11">
 <h2 data-number="9.11" class="anchored" data-anchor-id="sec-building-c-code"><span class="header-section-number">9.11</span> Building C code</h2>
 <p>The <code>zig</code> compiler comes with a C compiler embedded in it. In other words, you can use the <code>zig</code> compiler to build C projects. This C compiler is available through the <code>cc</code> command of the <code>zig</code> compiler.</p>
-<p>As an example, let’s use the famous <a href="https://freetype.org/">FreeType library</a><a href="#fn9" class="footnote-ref" id="fnref9" role="doc-noteref"><sup>9</sup></a>. FreeType is one of the most widely used pieces of software in the world. It is a C library designed to produce high-quality fonts. But it is also heavily used in the industry to natively render text and fonts in the screen of your computer.</p>
+<p>As an example, let’s use the famous <a href="https://freetype.org/">FreeType library</a><a href="#fn9" class="footnote-ref" id="fnref9" role="doc-noteref"><sup>9</sup></a>. FreeType is one of the most widely used pieces of software in the world. It’s a C library designed to produce high-quality fonts. But it’s also heavily used in the industry to natively render text and fonts in the screen of your computer.</p>
 <p>In this section, we are going to write a build script, piece by piece, that is capable of building the FreeType project from source. You can find the source code of this build script on the <a href="https://github.com/pedropark99/freetype-zig/tree/main"><code>freetype-zig</code> repository</a><a href="#fn10" class="footnote-ref" id="fnref10" role="doc-noteref"><sup>10</sup></a> available at GitHub.</p>
 <p>After you download the source code of FreeType from the official website<a href="#fn11" class="footnote-ref" id="fnref11" role="doc-noteref"><sup>11</sup></a>, you can start writing the <code>build.zig</code> module. We begin by defining the target object that defines the binary file that we want to compile.</p>
 <p>As an example, I will build the project as a static library file using the <code>addStaticLibrary()</code> method to create the target object. Also, since FreeType is a C library, I will also link the library against <code>libc</code> through the <code>linkLibC()</code> method, to guarantee that any use of the C Standard Library is covered in the compilation process.</p>
@@ -613,7 +613,7 @@ <h3 data-number="9.11.1" class="anchored" data-anchor-id="creating-c-compiler-fl
 <span id="cb21-4"><a href="#cb21-4" aria-hidden="true" tabindex="-1"></a>    <span class="st">"-Werror"</span>,</span>
 <span id="cb21-5"><a href="#cb21-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>In theory, there is nothing stopping you from using this array to add “include paths” (with the <code>-I</code> flag) or “library paths” (with the <code>-L</code> flag) to the compilation process. But there are formal ways in Zig to add these types of paths in the compilation process. Both are discussed at <a href="#sec-include-paths" class="quarto-xref"><span>Section 9.11.5</span></a> and <a href="#sec-library-paths" class="quarto-xref"><span>Section 9.11.4</span></a>.</p>
+<p>In theory, there is nothing stopping you from using this array to add “include paths” (with the <code>-I</code> flag) or “library paths” (with the <code>-L</code> flag) to the compilation process. But there are formal ways in Zig to add these types of paths in the compilation process. Both are discussed in <a href="#sec-include-paths" class="quarto-xref"><span>Section 9.11.5</span></a> and <a href="#sec-library-paths" class="quarto-xref"><span>Section 9.11.4</span></a>.</p>
 <p>Anyway, in Zig, we add C flags to the build process together with the C files that we want to compile, by using the <code>addCSourceFile()</code> and <code>addCSourceFiles()</code> methods. In the example above, we have just declared the C flags that we want to use. But we haven’t added them to the build process yet. To do that, we also need to list the C files to be compiled.</p>
 </section>
 <section id="listing-your-c-files" class="level3" data-number="9.11.2">
@@ -638,8 +638,8 @@ <h3 data-number="9.11.2" class="anchored" data-anchor-id="listing-your-c-files">
 <span id="cb23-8"><a href="#cb23-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>Now that we declared both the files that we want to include and the C compiler flags to be used, we can add them to the target object that describes the FreeType library, by using the <code>addCSourceFile()</code> and <code>addCSourceFiles()</code> methods.</p>
-<p>Both of these functions are methods from a <code>Compile</code> object (i.e.&nbsp;a target object). The <code>addCSourceFile()</code> method is capable of adding a single C file to the target object, while the <code>addCSourceFiles()</code> method is used to add multiple C files in a single command. You might prefer to use <code>addCSourceFile()</code> when you need to use different compiler flags on specific C files in your project. But, if you can use the same compiler flags across all C files, then, you will probably find <code>addCSourceFiles()</code> a better choice.</p>
-<p>Notice that we are using the <code>addCSourceFiles()</code> method in the example below, to add both the C files and the C compiler flags. Also notice that we are using the <code>os.tag</code> that we learned about at <a href="#sec-detect-os" class="quarto-xref"><span>Section 9.6</span></a>, to add the platform-specific C files.</p>
+<p>Both of these functions are methods from a <code>Compile</code> object (i.e., a target object). The <code>addCSourceFile()</code> method is capable of adding a single C file to the target object, while the <code>addCSourceFiles()</code> method is used to add multiple C files in a single command. You might prefer to use <code>addCSourceFile()</code> when you need to use different compiler flags on specific C files in your project. But, if you can use the same compiler flags across all C files, then, you will probably find <code>addCSourceFiles()</code> a better choice.</p>
+<p>Notice that we are using the <code>addCSourceFiles()</code> method in the example below, to add both the C files and the C compiler flags. Also notice that we are using the <code>os.tag</code> that we learned about in <a href="#sec-detect-os" class="quarto-xref"><span>Section 9.6</span></a>, to add the platform-specific C files.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb24"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb24-1"><a href="#cb24-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> builtin = <span class="bu">@import</span>(<span class="st">"builtin"</span>);</span>
 <span id="cb24-2"><a href="#cb24-2" aria-hidden="true" tabindex="-1"></a>lib.addCSourceFiles(</span>
@@ -666,7 +666,7 @@ <h3 data-number="9.11.2" class="anchored" data-anchor-id="listing-your-c-files">
 <section id="defining-c-macros" class="level3" data-number="9.11.3">
 <h3 data-number="9.11.3" class="anchored" data-anchor-id="defining-c-macros"><span class="header-section-number">9.11.3</span> Defining C Macros</h3>
 <p>C Macros are an essential part of the C programming language, and they are commonly defined through the <code>-D</code> flag from a C compiler. In Zig, you can define a C Macro to be used in your build process by using the <code>defineCMacro()</code> method from the target object that defines the binary file that you are building.</p>
-<p>In the example below, we are using the <code>lib</code> object that we have defined on the previous sections to define some C Macros used by the FreeType project in the compilation process. These C Macros specify if FreeType should (or should not) include functionalities from different external libraries.</p>
+<p>In the example below, we are using the <code>lib</code> object that we have defined in the previous sections to define some C Macros used by the FreeType project in the compilation process. These C Macros specify if FreeType should (or should not) include functionalities from different external libraries.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb25"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb25-1"><a href="#cb25-1" aria-hidden="true" tabindex="-1"></a>lib.defineCMacro(<span class="st">"FT_DISABLE_ZLIB"</span>, <span class="st">"TRUE"</span>);</span>
 <span id="cb25-2"><a href="#cb25-2" aria-hidden="true" tabindex="-1"></a>lib.defineCMacro(<span class="st">"FT_DISABLE_PNG"</span>, <span class="st">"TRUE"</span>);</span>
@@ -690,7 +690,7 @@ <h3 data-number="9.11.4" class="anchored" data-anchor-id="sec-library-paths"><sp
 </section>
 <section id="sec-include-paths" class="level3" data-number="9.11.5">
 <h3 data-number="9.11.5" class="anchored" data-anchor-id="sec-include-paths"><span class="header-section-number">9.11.5</span> Adding include paths</h3>
-<p>The preprocessor search path is a popular concept from the C community, but it is also known by many C programmers as “include paths”, because the paths in this “search path” relate to the <code>#include</code> statements found in the C files.</p>
+<p>The preprocessor search path is a popular concept from the C community, but it’s also known by many C programmers as “include paths”, because the paths in this “search path” relate to the <code>#include</code> statements found in the C files.</p>
 <p>Include paths are similar to library paths. They are a set of pre-defined places in your computer where the C compiler will look for files during the compilation process. But instead of looking for library files, the include paths are places where the compiler looks for header files included in your C source code. This is why many C programmers prefer to call these paths as the “preprocessor search path”. Because header files are processed during the preprocessor stage of the compilation process.</p>
 <p>So, every header file that you include in your C source code, through a <code>#include</code> statements needs to be found somewhere, and the C compiler will search for this header file across the paths listed in this “include paths” set. Include paths are added to the compilation process through the <code>-I</code> flag.</p>
 <p>In Zig, you can add new paths to this pre-defined set of paths, by using the <code>addIncludePath()</code> method from your target object. This method also accepts a <code>LazyPath</code> object as input.</p>
diff --git a/docs/Chapters/09-data-structures.html b/docs/Chapters/09-data-structures.html
index 75cbf5a3..12765e04 100644
--- a/docs/Chapters/09-data-structures.html
+++ b/docs/Chapters/09-data-structures.html
@@ -384,7 +384,7 @@ <h3 data-number="11.1.1" class="anchored" data-anchor-id="capacity-vs-length"><s
 <p>When we talk about dynamic arrays, we usually have two similar concepts that are very essential to how a dynamic array works behind the hood. These concepts are <em>capacity</em> and <em>length</em>. In some contexts, especially in C++, <em>length</em> is also called of <em>size</em>.</p>
 <p>Although they look similar, these concepts represent different things in the context of a dynamic array. <em>Capacity</em> is the number of items (or elements) that your dynamic array can currently hold without the need to allocate more memory.</p>
 <p>In contrast, the <em>length</em> refers to how many elements in the array are currently being used, or, in other words, how many elements in this array that you have assigned a value to. Every dynamic array works around a block of allocated memory, which represents an array with total capacity for <span class="math inline">\(n\)</span> elements. However, only a portion of these <span class="math inline">\(n\)</span> elements are being used most of the time. This portion of <span class="math inline">\(n\)</span> is the <em>length</em> of the array. So every time you append a new value to the array, you are incrementing its <em>length</em> by one.</p>
-<p>This means that a dynamic array usually works with an extra margin, or, an extra space which is currently empty, but it is waiting and ready to be used. This “extra space” is essentially the difference between <em>capacity</em> and <em>length</em>. <em>Capacity</em> represents the total number of elements that the array can hold without the need to re-allocate or re-expand the array, while the <em>length</em> represents how much of this capacity is currently being used to hold/store values.</p>
+<p>This means that a dynamic array usually works with an extra margin, or an extra space that is currently empty, but waiting and ready to be used. This “extra space” is essentially the difference between <em>capacity</em> and <em>length</em>. <em>Capacity</em> represents the total number of elements that the array can hold without the need to re-allocate or re-expand the array, while the <em>length</em> represents how much of this capacity is currently being used to hold/store values.</p>
 <p><a href="#fig-capacity-length" class="quarto-xref">Figure&nbsp;<span>11.1</span></a> presents this idea visually. Notice that, at first, the capacity of the array is greater than the length of the array. So, the dynamic array have extra space that is currently empty, but it is ready to receive a value to be stored.</p>
 <div id="fig-capacity-length" class="quarto-float quarto-figure quarto-figure-center anchored">
 <figure class="quarto-float quarto-float-fig figure">
@@ -396,9 +396,9 @@ <h3 data-number="11.1.1" class="anchored" data-anchor-id="capacity-vs-length"><s
 </figcaption>
 </figure>
 </div>
-<p>We can also see at <a href="#fig-capacity-length" class="quarto-xref">Figure&nbsp;<span>11.1</span></a> that, when <em>length</em> and <em>capacity</em> are equal, it means that the array have no space left. We have reached the ceiling of our capacity, and because of that, if we want to store more values in this array, we need to expand it. We need to get a bigger space that can hold more values than what we currently have.</p>
-<p>A dynamic array works by expanding the underlying array, whenever the <em>length</em> becomes equal to the <em>capacity</em> of the array. It basically allocates a new contiguous block of memory that is bigger than the previous one, then, it copies all values that are currently being stored to this new location (i.e.&nbsp;this new block of memory), then, it frees the previous block of memory. At the end of this process, the new underlying array have a bigger <em>capacity</em>, and, therefore, the <em>length</em> becomes, once again, smaller than the <em>capacity</em> of the array.</p>
-<p>This is the cycle of an dynamic array. Notice that, throughout this cycle, the <em>capacity</em> is always either equal to or higher than the <em>length</em> of the array. If youh have an <code>ArrayList</code> object (let’s suppose you named it <code>buffer</code>), you can check the current capacity of your array by accessing the <code>capacity</code> attribute of your <code>ArrayList</code> object, while the current <em>length</em> of it is available at the <code>items.len</code> attribute.</p>
+<p>We can also see in <a href="#fig-capacity-length" class="quarto-xref">Figure&nbsp;<span>11.1</span></a> that, when <em>length</em> and <em>capacity</em> are equal, it means that the array have no space left. We have reached the ceiling of our capacity, and because of that, if we want to store more values in this array, we need to expand it. We need to get a bigger space that can hold more values than what we currently have.</p>
+<p>A dynamic array works by expanding the underlying array, whenever the <em>length</em> becomes equal to the <em>capacity</em> of the array. It basically allocates a new contiguous block of memory that is bigger than the previous one, then, it copies all values that are currently being stored to this new location (i.e., this new block of memory), then, it frees the previous block of memory. At the end of this process, the new underlying array have a bigger <em>capacity</em>, and, therefore, the <em>length</em> becomes, once again, smaller than the <em>capacity</em> of the array.</p>
+<p>This is the cycle of a dynamic array. Notice that, throughout this cycle, the <em>capacity</em> is always either equal to or higher than the <em>length</em> of the array. If you have an <code>ArrayList</code> object (let’s suppose you named it <code>buffer</code>), you can check the current capacity of your array by accessing the <code>capacity</code> attribute of your <code>ArrayList</code> object, while the current <em>length</em> of it is available at the <code>items.len</code> attribute.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb1"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="co">// Check capacity</span></span>
 <span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a>buffer.capacity;</span>
@@ -408,7 +408,7 @@ <h3 data-number="11.1.1" class="anchored" data-anchor-id="capacity-vs-length"><s
 </section>
 <section id="creating-an-arraylist-object" class="level3" data-number="11.1.2">
 <h3 data-number="11.1.2" class="anchored" data-anchor-id="creating-an-arraylist-object"><span class="header-section-number">11.1.2</span> Creating an <code>ArrayList</code> object</h3>
-<p>In order to use <code>ArrayList</code>, you must provide an allocator object to it. Remember, Zig does not have a default memory allocator. And as I described at <a href="01-memory.html#sec-allocators" class="quarto-xref"><span>Section 3.3</span></a>, all memory allocations must be done by an allocator object that you define, that you have control over. In our example here, I’m going to use a general purpose allocator, but you can use any other allocator of your preference.</p>
+<p>In order to use <code>ArrayList</code>, you must provide an allocator object to it. Remember, Zig does not have a default memory allocator. And as I described in <a href="01-memory.html#sec-allocators" class="quarto-xref"><span>Section 3.3</span></a>, all memory allocations must be done by an allocator object that you define, that you have control over. In our example here, I’m going to use a general purpose allocator, but you can use any other allocator of your preference.</p>
 <p>When you initialize an <code>ArrayList</code> object, you must provide the data type of the elements of the array. In other words, this defines the type of data that this array (or container) will store. Therefore, if I provide the <code>u8</code> type to it, then, I will create a dynamic array of <code>u8</code> values. However, if I provide a struct that I have defined instead, like the struct <code>User</code> from <a href="03-structs.html#sec-structs-and-oop" class="quarto-xref"><span>Section 2.3</span></a>, then, a dynamic array of <code>User</code> values will be created. In the example below, with the expression <code>ArrayList(u8)</code> we are creating a dynamic array of <code>u8</code> values.</p>
 <p>After you provide the data type of the elements of the array, you can initialize an <code>ArrayList</code> object by either using the <code>init()</code> or the <code>initCapacity()</code> methods. The former method receives only the allocator object as input, while the latter method receives both the allocator object and a capacity number as inputs. With the latter method, you not only initialize the struct, but you also set the starting capacity of the allocated array.</p>
 <p>Using the <code>initCapacity()</code> method is the preferred way to initialize your dynamic array. Because reallocations, or, in other words, the process of expanding the capacity of the array, is always a high cost operation. You should take any possible opportunity to avoid reallocations in your array. If you know how much space your array needs to occupy at the beginning, you should always use <code>initCapacity()</code> to create your dynamic array.</p>
@@ -424,7 +424,7 @@ <h3 data-number="11.1.2" class="anchored" data-anchor-id="creating-an-arraylist-
 <section id="adding-new-elements-to-the-array" class="level3" data-number="11.1.3">
 <h3 data-number="11.1.3" class="anchored" data-anchor-id="adding-new-elements-to-the-array"><span class="header-section-number">11.1.3</span> Adding new elements to the array</h3>
 <p>Now that we have created our dynamic array, we can start to use it. You can append (a.k.a “add”) new values to this array by using the <code>append()</code> method. This method works the same way as the <code>append()</code> method from a Python list, or, the <code>emplace_back()</code> method from <code>std::vector</code> of C++. You provide a single value to this method, and the method appends this value to the array.</p>
-<p>You can also use the <code>appendSlice()</code> method to append multiple values at once. You provide a slice (slices were described at <a href="01-zig-weird.html#sec-arrays" class="quarto-xref"><span>Section 1.6</span></a>) to this method, and the method adds all values present in this slice to your dynamic array.</p>
+<p>You can also use the <code>appendSlice()</code> method to append multiple values at once. You provide a slice (slices were described in <a href="01-zig-weird.html#sec-arrays" class="quarto-xref"><span>Section 1.6</span></a>) to this method, and the method adds all values present in this slice to your dynamic array.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb3"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> buffer.append(<span class="ch">'H'</span>);</span>
 <span id="cb3-2"><a href="#cb3-2" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> buffer.append(<span class="ch">'e'</span>);</span>
@@ -436,8 +436,8 @@ <h3 data-number="11.1.3" class="anchored" data-anchor-id="adding-new-elements-to
 </section>
 <section id="sec-dynamic-array-remove" class="level3" data-number="11.1.4">
 <h3 data-number="11.1.4" class="anchored" data-anchor-id="sec-dynamic-array-remove"><span class="header-section-number">11.1.4</span> Removing elements from the array</h3>
-<p>You can use the <code>pop()</code> method to “pop” or remove the last element in the array. Is worth noting that this method do not change the capacity of the array. It just deletes or erases the last value stored in the array.</p>
-<p>Also, this method returns as result the value that got deleted. That is, you can use this method to both get the last value in the array, and also, remove it from the array. It is a “get and remove value” type of method.</p>
+<p>You can use the <code>pop()</code> method to “pop” or remove the last element in the array. It’s worth noting that this method do not change the capacity of the array. It just deletes or erases the last value stored in the array.</p>
+<p>Also, this method returns as result the value that got deleted. That is, you can use this method to both get the last value in the array, and also, remove it from the array. It’s a “get and remove value” type of method.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb4"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> exclamation_mark = buffer.pop();</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
@@ -504,7 +504,7 @@ <h2 data-number="11.2" class="anchored" data-anchor-id="sec-maps-hashtables"><sp
 <h3 data-number="11.2.1" class="anchored" data-anchor-id="what-is-a-hashtable"><span class="header-section-number">11.2.1</span> What is a hashtable?</h3>
 <p>A hashtable is a data structure based on key-value pairs. You provide a key and a value to this structure, then, the hashtable will store the input value at a location that can be identified by the input key that you provided. It does that by using an underlying array and a hash function. These two components are essential to how a hashtable works.</p>
 <p>Under the hood, the hashtable contains an array. This array is where the values are stored, and the elements of this array are usually called of <em>buckets</em>. So the values that you provide to the hashtable are stored inside buckets, and you access each bucket by using an index.</p>
-<p>When you provide a key to a hashtable, it passes this key to the hash function. This hash function uses some sort of hashing algorithm to transform this key into an index. This index is actually an array index. It is a position in the underlying array of the hashtable. This is how a key identifies a specific position (or location) inside the hashtable structure.</p>
+<p>When you provide a key to a hashtable, it passes this key to the hash function. This hash function uses some sort of hashing algorithm to transform this key into an index. This index is actually an array index. It’s a position in the underlying array of the hashtable. This is how a key identifies a specific position (or location) inside the hashtable structure.</p>
 <p>Therefore, you provide a key to the hashtable, and this key identifies a specific location inside the hashtable, then, the hashtable takes the input value that you provided, and stores this value in the location identified by this input key. You could say that the key maps to the value stored in the hashtable. You find the value, by using the key that identifies the location where the value is stored. The <a href="#fig-hashtable" class="quarto-xref">Figure&nbsp;<span>11.2</span></a> presents this process visually.</p>
 <div id="fig-hashtable" class="quarto-float quarto-figure quarto-figure-center anchored">
 <figure class="quarto-float quarto-float-fig figure">
@@ -516,16 +516,16 @@ <h3 data-number="11.2.1" class="anchored" data-anchor-id="what-is-a-hashtable"><
 </figcaption>
 </figure>
 </div>
-<p>The operation described in the previous paragraph is normally called an <em>insertion</em> operation. Because you are inserting new values into the hashtable. But there are other types of operations in hashtables such as <em>delete</em> and <em>lookup</em>. Delete is self describing, it is when you delete (or remove) a value from the hashtable. While lookup corresponds to when you look at a value that is stored in the hashtable, by using the key that identifies the location where this value is stored.</p>
-<p>Sometimes, instead of storing the values directly, the underlying array of the hashtable might be an array of pointers, i.e.&nbsp;the buckets of the array stores pointers that points to the value, or also, may be an array of linked lists. These cases are common on hashtables that allows duplicate keys, or, in other words, on hashtables that effectively handle “collisions” that may arise from the hash function.</p>
-<p>Duplicate keys, or this “collision” thing that I’m talking about, is when you have two different keys that points to the same location (i.e.&nbsp;to the same index) in the underlying array of the hashtable. This might happen depending on the characteristics of the hash function that is being used in the hashtable. Some implementations of the hashtable will actively deal with collisions, meaning that, they will handle this case in some way. For example, the hashtable might transform all buckets into linked lists. Because with a linked list you can store multiple values into a single bucket.</p>
-<p>There are different techniques to handle collisions in hashtables, which I will not describe in this book, because it is not our main scope here. But you can find a good description of some of the most common techniques at the Wikipedia page of hashtables <span class="citation" data-cites="wikipedia_hashtables">(<a href="../references.html#ref-wikipedia_hashtables" role="doc-biblioref">Wikipedia 2024</a>)</span>.</p>
+<p>The operation described in the previous paragraph is normally called an <em>insertion</em> operation. Because you are inserting new values into the hashtable. But there are other types of operations in hashtables such as <em>delete</em> and <em>lookup</em>. Delete is self describing, it’s when you delete (or remove) a value from the hashtable. While lookup corresponds to when you look at a value that is stored in the hashtable, by using the key that identifies the location where this value is stored.</p>
+<p>Sometimes, instead of storing the values directly, the underlying array of the hashtable might be an array of pointers, i.e., the buckets of the array stores pointers that points to the value, or also, may be an array of linked lists. These cases are common on hashtables that allows duplicate keys, or, in other words, on hashtables that effectively handle “collisions” that may arise from the hash function.</p>
+<p>Duplicate keys, or this “collision” thing that I’m talking about, is when you have two different keys that points to the same location (i.e., to the same index) in the underlying array of the hashtable. This might happen depending on the characteristics of the hash function that is being used in the hashtable. Some implementations of the hashtable will actively deal with collisions, meaning that, they will handle this case in some way. For example, the hashtable might transform all buckets into linked lists. Because with a linked list you can store multiple values into a single bucket.</p>
+<p>There are different techniques to handle collisions in hashtables, which I will not describe in this book, because it’s not our main scope here. But you can find a good description of some of the most common techniques at the Wikipedia page of hashtables <span class="citation" data-cites="wikipedia_hashtables">(<a href="../references.html#ref-wikipedia_hashtables" role="doc-biblioref">Wikipedia 2024</a>)</span>.</p>
 </section>
 <section id="sec-hashmap" class="level3" data-number="11.2.2">
 <h3 data-number="11.2.2" class="anchored" data-anchor-id="sec-hashmap"><span class="header-section-number">11.2.2</span> Hashtables in Zig</h3>
 <p>The Zig Standard Library provides different implementations of a hashtable. Each implementation have its own cons and pros, which we will discuss later on, and all of them are available through the <code>std.hash_map</code> module.</p>
 <p>The <code>HashMap</code> struct is a general-purpose hashtable, which have very fast operations (lookup, insertion, delete), and also, quite high load factors for low memory usage. You can create and provide a context object to the <code>HashMap</code> constructor. This context object allows you to tailor the behaviour of the hashtable itself, because you can provide a hash function implementation to be used by the hashtable through this context object.</p>
-<p>But let’s not worry about this context object now, because it is meant to be used by “experts in the field of hashtables”. Since we are most likely not experts in this field, we are going to take the easy way to create a hashtable. Which is by using the <code>AutoHashMap()</code> function.</p>
+<p>But let’s not worry about this context object now, because it’s meant to be used by “experts in the field of hashtables”. Since we are most likely not experts in this field, we are going to take the easy way to create a hashtable. Which is by using the <code>AutoHashMap()</code> function.</p>
 <p>This <code>AutoHashMap()</code> function is essentially a “create a hashtable object that uses the default settings” type of function. It automatically chooses a context object, and, therefore, a hash function implementation, for you. This function receives two data types as input, the first input is the data type of the keys that will be used in this hashtable, while the second input is the data type of the data that will be stored inside the hashtable, that is, the data type of the values to be stored.</p>
 <p>In the example below, we are providing the data type <code>u32</code> in the first argument, and <code>u16</code> in the second argument of this function. This means that we are going to use <code>u32</code> values as keys in this hashtable, while <code>u16</code> values are the actual values that are going to be stored into this hashtable. At the end of this process, the <code>hash_table</code> object contains a <code>HashMap</code> object that uses the default settings and context.</p>
 <div class="cell">
@@ -569,12 +569,12 @@ <h3 data-number="11.2.2" class="anchored" data-anchor-id="sec-hashmap"><span cla
 <p>You can add/put new values into the hashtable by using the <code>put()</code> method. The first argument is the key to be used, and the second argument is the actual value that you want to store inside the hashtable. In the example below, we first add the value 89 using the key 54321, next, we add the value 55 using the key 50050, etc.</p>
 <p>Notice that we have used the method <code>count()</code> to see how many values are currently stored in the hashtable. After that, we also use the <code>get()</code> method to access (or look) at the value stored in the position identified by the key 500050. The output of this <code>get()</code> method is an optional value. This is why we use the <code>?</code> method at the end to get the actual value.</p>
 <p>Also notice that we can remove (or delete) values from the hashtable by using the <code>remove()</code> method. You provide the key that identifies the value that you want to delete, then, the method will delete this value and return a <code>true</code> value as output. This <code>true</code> value essentially tells us that the method successfully deleted the value.</p>
-<p>But this delete operation might not be always successful. For example, you might provide the wrong key to this method. I mean, maybe you provide (either intentionally or unintentionally) a key that points to an empty bucket, i.e.&nbsp;a bucket that still doesn’t have a value in it. In this case, the <code>remove()</code> method would return a <code>false</code> value.</p>
+<p>But this delete operation might not be always successful. For example, you might provide the wrong key to this method. I mean, maybe you provide (either intentionally or unintentionally) a key that points to an empty bucket, i.e., a bucket that still doesn’t have a value in it. In this case, the <code>remove()</code> method would return a <code>false</code> value.</p>
 </section>
 <section id="iterating-through-the-hashtable" class="level3" data-number="11.2.3">
 <h3 data-number="11.2.3" class="anchored" data-anchor-id="iterating-through-the-hashtable"><span class="header-section-number">11.2.3</span> Iterating through the hashtable</h3>
 <p>Iterating through the keys and values that are currently being stored in the hashtable is a very common necessity. You can do that in Zig by using an iterator object that can iterate through the elements of your hashtable object.</p>
-<p>This iterator object works like any other iterator object that you would find in languages such as C++ and Rust. It is basically a pointer object that points to some value in the container, and has a <code>next()</code> method that you can use to navigate (or iterate) through the values in the container.</p>
+<p>This iterator object works like any other iterator object that you would find in languages such as C++ and Rust. It’s basically a pointer object that points to some value in the container, and has a <code>next()</code> method that you can use to navigate (or iterate) through the values in the container.</p>
 <p>You can create such iterator object by using the <code>iterator()</code> method of the hashtable object. This method returns an iterator object, from which you can use the <code>next()</code> method in conjunction with a while loop to iterate through the elements of your hashtable. The <code>next()</code> method returns an optional <code>Entry</code> value, and therefore, you must unwrap this optional value to get the actual <code>Entry</code> value from which you can access the key and also the value identified by this key.</p>
 <p>With this <code>Entry</code> value at hand, you can access the key of this current entry by using the <code>key_ptr</code> attribute and dereferencing the pointer that lives inside of it, while the value identified by this key is accessed through the <code>value_ptr</code> attribute instead, which is also a pointer to be dereferenced. The code example below demonstrates the use of these elements:</p>
 <div class="cell">
@@ -620,15 +620,15 @@ <h3 data-number="11.2.4" class="anchored" data-anchor-id="sec-array-map"><span c
 <p>If you need to iterate through the elements of your hashtable constantly, you might want to use the <code>ArrayHashMap</code> struct for your specific case, instead of going with the usual and general-purpose <code>HashMap</code> struct.</p>
 <p>The <code>ArrayHashMap</code> struct creates a hashtable that is faster to iterate over. That is why this specific type of hashtable might be valuable to you. Some other properties of a <code>ArrayHashMap</code> hashtable are:</p>
 <ul>
-<li>the order of insertion is preserved, i.e.&nbsp;the order of the values that you find while iterating through this hashtable is actually the order in which these values were inserted in the hashtable.</li>
+<li>the order of insertion is preserved, i.e., the order of the values that you find while iterating through this hashtable is actually the order in which these values were inserted in the hashtable.</li>
 <li>the key-value pairs are stored sequentially, one after another.</li>
 </ul>
-<p>You can create an <code>ArrayHashMap</code> object by using, once again, a helper function that chooses automatically for you a hash function implementation. This is the <code>AutoArrayHashMap()</code> function, which works very similarly to the <code>AutoHashMap()</code> function that we presented at <a href="#sec-hashmap" class="quarto-xref"><span>Section 11.2.2</span></a>.</p>
+<p>You can create an <code>ArrayHashMap</code> object by using, once again, a helper function that chooses automatically for you a hash function implementation. This is the <code>AutoArrayHashMap()</code> function, which works very similarly to the <code>AutoHashMap()</code> function that we presented in <a href="#sec-hashmap" class="quarto-xref"><span>Section 11.2.2</span></a>.</p>
 <p>You provide two data types to this function. The data type of the keys that will be used in this hashtable, and the data type of the values that will be stored in this hashtable.</p>
 <p>An <code>ArrayHashMap</code> object have essentially the exact same methods from the <code>HashMap</code> struct. So you can insert new values into the hashtable by using the <code>put()</code> method, and you can look (or get) a value from the hashtable by using the <code>get()</code> method. But the <code>remove()</code> method is not available in this specific type of hashtable.</p>
-<p>In order to delete values from the hashtable, you would use the same methods that you find in an <code>ArrayList</code> object, i.e.&nbsp;a dynamic array. I presented these methods at <a href="#sec-dynamic-array-remove" class="quarto-xref"><span>Section 11.1.4</span></a>, which are the <code>swapRemove()</code> and <code>orderedRemove()</code> methods. These methods have the same meaning here, or, the same effect that they have in an <code>ArrayList</code> object.</p>
+<p>In order to delete values from the hashtable, you would use the same methods that you find in an <code>ArrayList</code> object, i.e., a dynamic array. I presented these methods in <a href="#sec-dynamic-array-remove" class="quarto-xref"><span>Section 11.1.4</span></a>, which are the <code>swapRemove()</code> and <code>orderedRemove()</code> methods. These methods have the same meaning here, or, the same effect that they have in an <code>ArrayList</code> object.</p>
 <p>This means that, with <code>swapRemove()</code> you remove the value from the hashtable, but you do not preserve the order in which the values were inserted into the structure. While <code>orderedRemove()</code> is able to retain the order in which these values were inserted.</p>
-<p>But instead of providing an index as input to <code>swapRemove()</code> or <code>orderedRemove()</code>, like I described at <a href="#sec-dynamic-array-remove" class="quarto-xref"><span>Section 11.1.4</span></a>, these methods here in an <code>ArrayHashMap</code> take a key as input, like the <code>remove()</code> method from a <code>HashMap</code> object. If you want to provide an index as input, instead of a key, you should use the <code>swapRemoveAt()</code> and <code>orderedRemoveAt()</code> methods.</p>
+<p>But instead of providing an index as input to <code>swapRemove()</code> or <code>orderedRemove()</code>, like I described in <a href="#sec-dynamic-array-remove" class="quarto-xref"><span>Section 11.1.4</span></a>, these methods here in an <code>ArrayHashMap</code> take a key as input, like the <code>remove()</code> method from a <code>HashMap</code> object. If you want to provide an index as input, instead of a key, you should use the <code>swapRemoveAt()</code> and <code>orderedRemoveAt()</code> methods.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb15"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb15-1"><a href="#cb15-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> hash_table = AutoArrayHashMap(<span class="dt">u32</span>, <span class="dt">u16</span>)</span>
 <span id="cb15-2"><a href="#cb15-2" aria-hidden="true" tabindex="-1"></a>    .init(allocator);</span>
@@ -638,7 +638,7 @@ <h3 data-number="11.2.4" class="anchored" data-anchor-id="sec-array-map"><span c
 <section id="sec-string-hash-map" class="level3" data-number="11.2.5">
 <h3 data-number="11.2.5" class="anchored" data-anchor-id="sec-string-hash-map"><span class="header-section-number">11.2.5</span> The <code>StringHashMap</code> hashtable</h3>
 <p>One thing that you will notice in the other two types of hashtables that I have presented over the last sections, is that neither of them accepts a slice data type in their keys. What this means is that you cannot use a slice value to represent a key in these types of hashtable.</p>
-<p>The most obvious consequence of this, is that you cannot use strings as keys in these hashtables. But it is extremely common to use strings as keys in hashtables.</p>
+<p>The most obvious consequence of this, is that you cannot use strings as keys in these hashtables. But it’s extremely common to use strings as keys in hashtables.</p>
 <p>Take this very simple Javascript code snippet as an example. We are creating a simple hashtable object named <code>people</code>. Then, we add a new entry to this hashtable, which is identified by the string <code>'Pedro'</code>. This string is the key in this case, while the object containing different personal information such as age, height and city, is the value to be stored in the hashtable.</p>
 <div class="sourceCode" id="cb16"><pre class="sourceCode js code-with-copy"><code class="sourceCode javascript"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> people <span class="op">=</span> <span class="kw">new</span> <span class="bu">Object</span>()<span class="op">;</span></span>
 <span id="cb16-2"><a href="#cb16-2" aria-hidden="true" tabindex="-1"></a>people[<span class="st">'Pedro'</span>] <span class="op">=</span> {</span>
@@ -675,9 +675,9 @@ <h3 data-number="11.2.5" class="anchored" data-anchor-id="sec-string-hash-map"><
 <section id="the-stringarrayhashmap-hashtable" class="level3" data-number="11.2.6">
 <h3 data-number="11.2.6" class="anchored" data-anchor-id="the-stringarrayhashmap-hashtable"><span class="header-section-number">11.2.6</span> The <code>StringArrayHashMap</code> hashtable</h3>
 <p>The Zig Standard Library also provides a type of hashtable that mix the cons and pros of the <code>StringHashMap</code> and <code>ArrayHashMap</code> together. That is, a hashtable that uses strings as keys, but also have the advantages from <code>ArrayHashMap</code>. In other words, you can have a hashtable that is fast to iterate over, that preserves insertion order, and also, that uses strings as keys.</p>
-<p>You can create such type of hashtable by using the <code>StringArrayHashMap()</code> function. This function accepts a data type as input, which is the data type of the values that are going to be stored inside this hashtable, in the same style as the function presented at <a href="#sec-string-hash-map" class="quarto-xref"><span>Section 11.2.5</span></a>.</p>
-<p>You can insert new values into this hashtable by using the same <code>put()</code> method that we have discussed at <a href="#sec-string-hash-map" class="quarto-xref"><span>Section 11.2.5</span></a>. And you can also get values from the hashtable by using the same <code>get()</code> method. Like its <code>ArrayHashMap</code> brother, to delete values from this specific type of hashtable, we also use the <code>orderedRemove()</code> and <code>swapRemove()</code> methods, with the same effects that I have described at <a href="#sec-array-map" class="quarto-xref"><span>Section 11.2.4</span></a>.</p>
-<p>If we take the code example that was exposed at <a href="#sec-string-hash-map" class="quarto-xref"><span>Section 11.2.5</span></a>, we can achieve the exact same result with <code>StringArrayHashMap()</code>:</p>
+<p>You can create such type of hashtable by using the <code>StringArrayHashMap()</code> function. This function accepts a data type as input, which is the data type of the values that are going to be stored inside this hashtable, in the same style as the function presented in <a href="#sec-string-hash-map" class="quarto-xref"><span>Section 11.2.5</span></a>.</p>
+<p>You can insert new values into this hashtable by using the same <code>put()</code> method that we have discussed in <a href="#sec-string-hash-map" class="quarto-xref"><span>Section 11.2.5</span></a>. And you can also get values from the hashtable by using the same <code>get()</code> method. Like its <code>ArrayHashMap</code> brother, to delete values from this specific type of hashtable, we also use the <code>orderedRemove()</code> and <code>swapRemove()</code> methods, with the same effects that I have described in <a href="#sec-array-map" class="quarto-xref"><span>Section 11.2.4</span></a>.</p>
+<p>If we take the code example that was exposed in <a href="#sec-string-hash-map" class="quarto-xref"><span>Section 11.2.5</span></a>, we can achieve the exact same result with <code>StringArrayHashMap()</code>:</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb19"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb19-1"><a href="#cb19-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> ages = std.StringArrayHashMap(<span class="dt">u8</span>).init(allocator);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
@@ -687,7 +687,7 @@ <h3 data-number="11.2.6" class="anchored" data-anchor-id="the-stringarrayhashmap
 <h2 data-number="11.3" class="anchored" data-anchor-id="linked-lists"><span class="header-section-number">11.3</span> Linked lists</h2>
 <p>The Zig Standard Library provides an implementation for both singly and doubly linked lists. A linked list is a linear data structure that looks like a chain, or, a rope. The main advantage of this data structure is that you normally have very fast insertion and deletion operations. But, as a disadvantage, iterating through this data structure is usually not so fast as iterating through an array.</p>
 <p>The idea behind a linked list is to build a structure that consists of a sequence of nodes connected to each other by pointers. This means that linked lists are usually not contiguous in memory, because each node might be anywhere in memory. They do not need to be close to one another.</p>
-<p>At <a href="#fig-linked-list" class="quarto-xref">Figure&nbsp;<span>11.3</span></a> we can see a diagram of a singly linked list. We begin at the first node (which is usually called “the head of the linked list”). Then, from this first node we uncover the remaining nodes in the structure, by following the locations pointed by the pointers found in each node.</p>
+<p>In <a href="#fig-linked-list" class="quarto-xref">Figure&nbsp;<span>11.3</span></a> we can see a diagram of a singly linked list. We begin at the first node (which is usually called “the head of the linked list”). Then, from this first node we uncover the remaining nodes in the structure, by following the locations pointed by the pointers found in each node.</p>
 <p>Each node has two things in it. It has the value that is stored in the current node , and also, a pointer. This pointer points to the next node in the list. If this pointer is null, then, it means that we have reached the end of our linked list.</p>
 <div id="fig-linked-list" class="quarto-float quarto-figure quarto-figure-center anchored">
 <figure class="quarto-float quarto-float-fig figure">
@@ -699,7 +699,7 @@ <h2 data-number="11.3" class="anchored" data-anchor-id="linked-lists"><span clas
 </figcaption>
 </figure>
 </div>
-<p>At <a href="#fig-linked-list2" class="quarto-xref">Figure&nbsp;<span>11.4</span></a> we can see a diagram of a doubly linked list. The only thing that really changes now is that every node in the linked list has both a pointer to the previous node, and, a pointer to the next node. So every node in a doubly linked list has two pointers in it. These are usually called the <code>prev</code> (for “previous”) and the <code>next</code> (for “next”) pointers of the node.</p>
+<p>In <a href="#fig-linked-list2" class="quarto-xref">Figure&nbsp;<span>11.4</span></a> we can see a diagram of a doubly linked list. The only thing that really changes now is that every node in the linked list has both a pointer to the previous node, and, a pointer to the next node. So every node in a doubly linked list has two pointers in it. These are usually called the <code>prev</code> (for “previous”) and the <code>next</code> (for “next”) pointers of the node.</p>
 <p>In the singly linked list example, we had only one single pointer in each node, and this singular pointer was always pointing to the next node in the sequence. This means that singly linked lists normally have only the <code>next</code> pointer in them.</p>
 <div id="fig-linked-list2" class="quarto-float quarto-figure quarto-figure-center anchored">
 <figure class="quarto-float quarto-float-fig figure">
@@ -711,14 +711,14 @@ <h2 data-number="11.3" class="anchored" data-anchor-id="linked-lists"><span clas
 </figcaption>
 </figure>
 </div>
-<p>Linked lists are available in Zig through the functions <code>SinglyLinkedList()</code> and <code>DoublyLinkedList()</code>, for “singly linked lists” and “doubly linked lists”, respectively. These functions are actually generic functions, which we are going to talk more about at <a href="10-stack-project.html#sec-generic-fun" class="quarto-xref"><span>Section 12.2.1</span></a>.</p>
+<p>Linked lists are available in Zig through the functions <code>SinglyLinkedList()</code> and <code>DoublyLinkedList()</code>, for “singly linked lists” and “doubly linked lists”, respectively. These functions are actually generic functions, which we are going to talk more about in <a href="10-stack-project.html#sec-generic-fun" class="quarto-xref"><span>Section 12.2.1</span></a>.</p>
 <p>For now, just understand that, in order to create a linked list object, we begin by providing a data type to these functions. This data type defines the type of data that each node in this linked list will store. In the example below, we are creating a singly linked list of <code>u32</code> values. So each node in this linked list will store a <code>u32</code> value.</p>
-<p>Both the <code>SinglyLinkedList()</code> and <code>DoublyLinkedList()</code> functions returns a type, i.e.&nbsp;a struct definition, as output. Therefore, the object <code>Lu32</code> is actually a struct definition. It defines the type “singly linked list of <code>u32</code> values”.</p>
+<p>Both the <code>SinglyLinkedList()</code> and <code>DoublyLinkedList()</code> functions returns a type, i.e., a struct definition, as output. Therefore, the object <code>Lu32</code> is actually a struct definition. It defines the type “singly linked list of <code>u32</code> values”.</p>
 <p>Now that we have the definition of the struct, we need to instantiate a <code>Lu32</code> object. We normally instantiate struct objects in Zig by using an <code>init()</code> method. But in this case, we are instantiating the struct directly, by using an empty <code>struct</code> literal, in the expression <code>Lu32{}</code>.</p>
 <p>In this example, we first create multiple node objects, and after we create them, we start to insert and connect these nodes to build the linked list, using the <code>prepend()</code> and <code>insertAfter()</code> methods. Notice that the <code>prepend()</code> method is a method from the linked list object, while the <code>insertAfter()</code> is a method present in the node objects.</p>
 <p>In essence, the <code>prepend()</code> method inserts a node at the beginning of the linked list. In other words, the node that you provide to this method, becomes the new “head node” of the linked list. It becomes the first node in the list (see <a href="#fig-linked-list" class="quarto-xref">Figure&nbsp;<span>11.3</span></a>).</p>
 <p>On the other side, the <code>insertAfter()</code> method is used to basically connect two nodes together. When you provide a node to this method, it creates a pointer to this input node, and stores this pointer in the <code>next</code> attribute of the current node, from which the method was called from.</p>
-<p>Because doubly linked lists have both a <code>next</code> and a <code>prev</code> attributes in each node (as described at <a href="#fig-linked-list2" class="quarto-xref">Figure&nbsp;<span>11.4</span></a>), a node object created from a <code>DoublyLinkedList</code> object have both an <code>insertBefore()</code> (for <code>prev</code>) and an <code>insertAfter()</code> (for <code>next</code>) methods available.</p>
+<p>Because doubly linked lists have both a <code>next</code> and a <code>prev</code> attributes in each node (as described in <a href="#fig-linked-list2" class="quarto-xref">Figure&nbsp;<span>11.4</span></a>), a node object created from a <code>DoublyLinkedList</code> object have both an <code>insertBefore()</code> (for <code>prev</code>) and an <code>insertAfter()</code> (for <code>next</code>) methods available.</p>
 <p>Thus, if we have used a doubly linked list, we can use the <code>insertBefore()</code> method to store the pointer to the input node in the <code>prev</code> attribute. This would put the input node as the “previous node”, or, the node before the current node. In contrast, the <code>insertAfter()</code> method puts the pointer created to the input node in the <code>next</code> attribute of the current node, and as result, the input node becomes the “next node” of the current node.</p>
 <p>Since we are using a singly linked list in this example, we have only the <code>insertAfter()</code> method available in the node objects that we create from our <code>Lu32</code> type.</p>
 <div class="cell">
@@ -746,14 +746,14 @@ <h2 data-number="11.3" class="anchored" data-anchor-id="linked-lists"><span clas
 <li><code>remove()</code> to remove a specific node from the linked list.</li>
 <li>if singly linked list, <code>len()</code> to count how many nodes there is in the linked list.</li>
 <li>if doubly linked list, checkout the <code>len</code> attribute to see how many nodes there is in the linked list.</li>
-<li>if singly linked list, <code>popFirst()</code> to remove the first node (i.e.&nbsp;the “head”) from the linked list.</li>
+<li>if singly linked list, <code>popFirst()</code> to remove the first node (i.e., the “head”) from the linked list.</li>
 <li>if doubly linked list, <code>pop()</code> and <code>popFirst()</code> to remove the last and first nodes from the linked list, respectively.</li>
-<li>if doubly linked list, <code>append()</code> to add a new node to end of the linked list (i.e.&nbsp;inverse of <code>prepend()</code>).</li>
+<li>if doubly linked list, <code>append()</code> to add a new node to end of the linked list (i.e., inverse of <code>prepend()</code>).</li>
 </ul>
 </section>
 <section id="multi-array-structure" class="level2" data-number="11.4">
 <h2 data-number="11.4" class="anchored" data-anchor-id="multi-array-structure"><span class="header-section-number">11.4</span> Multi array structure</h2>
-<p>Zig introduces a new data structure called <code>MultiArrayList()</code>. It is a different version of the dynamic array that we have introduced at <a href="#sec-dynamic-array" class="quarto-xref"><span>Section 11.1</span></a>. The difference between this structure and the <code>ArrayList()</code> that we know from <a href="#sec-dynamic-array" class="quarto-xref"><span>Section 11.1</span></a>, is that <code>MultiArrayList()</code> creates a separate dynamic array for each field of the struct that you provide as input.</p>
+<p>Zig introduces a new data structure called <code>MultiArrayList()</code>. It’s a different version of the dynamic array that we have introduced in <a href="#sec-dynamic-array" class="quarto-xref"><span>Section 11.1</span></a>. The difference between this structure and the <code>ArrayList()</code> that we know from <a href="#sec-dynamic-array" class="quarto-xref"><span>Section 11.1</span></a>, is that <code>MultiArrayList()</code> creates a separate dynamic array for each field of the struct that you provide as input.</p>
 <p>Consider the following code example. We create a new custom struct called <code>Person</code>. This struct contains three different data members, or, three different fields. As consequence, when we provide this <code>Person</code> data type as input to <code>MultiArrayList()</code>, this creates a “struct of three different arrays” called <code>PersonArray</code>. In other words, this <code>PersonArray</code> is a struct that contains three internal dynamic arrays in it. One array for each field found in the <code>Person</code> struct definition.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb21"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb21-1"><a href="#cb21-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
@@ -803,8 +803,8 @@ <h2 data-number="11.4" class="anchored" data-anchor-id="multi-array-structure"><
 Age: 26
 Age: 64</code></pre>
 <p>In the above example, we are iterating over the values of the <code>.age</code> array, or, the internal array of the <code>PersonArray</code> object that contains the values of the <code>age</code> data member from the <code>Person</code> values that were added to the multi array struct.</p>
-<p>In this example we are calling the <code>items()</code> method directly from the <code>PersonArray</code> object. However, it is recommended on most situations to call this <code>items()</code> method from a “slice object”, which you can create from the <code>slice()</code> method. The reason for this is that calling <code>items()</code> multiple times have better performance if you use a slice object.</p>
-<p>Therefore, if you are planning to access only one of the internal arrays from your “multi array struct”, it is fine to call <code>items()</code> directly from the multi array object. But if you need to access many of the internal arrays from your “multi array struct”, then, you will likely need to call <code>items()</code> more than once, and, in such circumstance, is better to call <code>items()</code> through a slice object. The example below demonstrates the use of such object:</p>
+<p>In this example we are calling the <code>items()</code> method directly from the <code>PersonArray</code> object. However, in most situations it’s recommened to call this <code>items()</code> method from a “slice object”, which you can create from the <code>slice()</code> method. The reason for this is that calling <code>items()</code> multiple times have better performance if you use a slice object.</p>
+<p>Therefore, if you are planning to access only one of the internal arrays from your “multi array struct”, it’s fine to call <code>items()</code> directly from the multi array object. But if you need to access many of the internal arrays from your “multi array struct”, then, you will likely need to call <code>items()</code> more than once, and, in such circumstance, is better to call <code>items()</code> through a slice object. The example below demonstrates the use of such object:</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb24"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb24-1"><a href="#cb24-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> slice = people.slice();</span>
 <span id="cb24-2"><a href="#cb24-2" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (slice.items(.age)) |*age| <span class="op">{</span></span>
diff --git a/docs/Chapters/09-error-handling.html b/docs/Chapters/09-error-handling.html
index e026d192..e621d0b4 100644
--- a/docs/Chapters/09-error-handling.html
+++ b/docs/Chapters/09-error-handling.html
@@ -366,7 +366,7 @@ <h1 class="title"><span id="sec-error-handling" class="quarto-section-identifier
 </header>
 
 
-<p>In this chapter, I want to discuss how error handling is done in Zig. We already briefly learned about one of the available strategies to handle errors in Zig, which is the <code>try</code> keyword presented at <a href="01-zig-weird.html#sec-main-file" class="quarto-xref"><span>Section 1.2.3</span></a>. But we still haven’t learned about the other methods, such as the <code>catch</code> keyword. I also want to discuss in this chapter how union types are created in Zig.</p>
+<p>In this chapter, I want to discuss how error handling is done in Zig. We already briefly learned about one of the available strategies to handle errors in Zig, which is the <code>try</code> keyword presented in <a href="01-zig-weird.html#sec-main-file" class="quarto-xref"><span>Section 1.2.3</span></a>. But we still haven’t learned about the other methods, such as the <code>catch</code> keyword. I also want to discuss in this chapter how union types are created in Zig.</p>
 <section id="learning-more-about-errors-in-zig" class="level2" data-number="10.1">
 <h2 data-number="10.1" class="anchored" data-anchor-id="learning-more-about-errors-in-zig"><span class="header-section-number">10.1</span> Learning more about errors in Zig</h2>
 <p>Before we get into how error handling is done, we need to learn more about what errors are in Zig. An error is actually a value in Zig <span class="citation" data-cites="zigoverview">(<a href="../references.html#ref-zigoverview" role="doc-biblioref">Zig Software Foundation 2024a</a>)</span>. In other words, when an error occurs inside your Zig program, it means that somewhere in your Zig codebase, an error value is being generated. An error value is similar to any integer value that you create in your Zig code. You can take an error value and pass it as input to a function, and you can also cast (or coerce) it into a different type of an error value.</p>
@@ -382,7 +382,7 @@ <h2 data-number="10.1" class="anchored" data-anchor-id="learning-more-about-erro
 t.zig:8:17: note: consider using 'try', 'catch', or 'if'</code></pre>
 <section id="returning-errors-from-functions" class="level3" data-number="10.1.1">
 <h3 data-number="10.1.1" class="anchored" data-anchor-id="returning-errors-from-functions"><span class="header-section-number">10.1.1</span> Returning errors from functions</h3>
-<p>As we described at <a href="01-zig-weird.html#sec-main-file" class="quarto-xref"><span>Section 1.2.3</span></a>, when we have a function that might return an error value, this function normally includes an exclamation mark (<code>!</code>) in its return type annotation. The presence of this exclamation mark indicates that this function might return an error value as result, and, the <code>zig</code> compiler forces you to always handle explicitly the case of this function returning an error value.</p>
+<p>As we described in <a href="01-zig-weird.html#sec-main-file" class="quarto-xref"><span>Section 1.2.3</span></a>, when we have a function that might return an error value, this function normally includes an exclamation mark (<code>!</code>) in its return type annotation. The presence of this exclamation mark indicates that this function might return an error value as result, and, the <code>zig</code> compiler forces you to always handle explicitly the case of this function returning an error value.</p>
 <p>Take a look at the <code>print_name()</code> function below. This function might return an error in the <code>stdout.print()</code> function call, and, as a consequence, its return type (<code>!void</code>) includes an exclamation mark in it.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb3"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> print_name() !<span class="dt">void</span> <span class="op">{</span></span>
@@ -390,22 +390,22 @@ <h3 data-number="10.1.1" class="anchored" data-anchor-id="returning-errors-from-
 <span id="cb3-3"><a href="#cb3-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"My name is Pedro!"</span>, .<span class="op">{}</span>);</span>
 <span id="cb3-4"><a href="#cb3-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>In the example above, we are using the exclamation mark to tell the <code>zig</code> compiler that this function might return some error. But which error exactly is returned from this function? For now, we are not specifying a specific error value. We only known for now that some error value (whatever it is) might be returned.</p>
+<p>In the example above, we are using the exclamation mark to tell the <code>zig</code> compiler that this function might return some error. But which error exactly is returned from this function? For now, we are not specifying a specific error value. For now, we only know that some error value (whatever it is) might be returned.</p>
 <p>But in fact, you can (if you want to) specify clearly which exact error values might be returned from this function. There are lot of examples of this in the Zig Standard Library. Take this <code>fill()</code> function from the <code>http.Client</code> module as an example. This function returns either a error value of type <code>ReadError</code>, or <code>void</code>.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb4"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> fill(conn: *Connection) ReadError!<span class="dt">void</span> <span class="op">{</span></span>
 <span id="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a>    <span class="co">// The body of this function ...</span></span>
 <span id="cb4-3"><a href="#cb4-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>This idea of specifying the exact error values that you expect to be returned from the function is interesting. Because they automatically become some sort of documentation of your function, and also, it allows the <code>zig</code> compiler to perform some extra checks over your code. Because it can check if there is any other type of error value that is being generated inside your function, and, that it is not being accounted for in this return type annotation.</p>
+<p>This idea of specifying the exact error values that you expect to be returned from the function is interesting. Because they automatically become some sort of documentation of your function, and also, this allows the <code>zig</code> compiler to perform some extra checks over your code. Because the compiler can check if there is any other type of error value that is being generated inside your function, and, that it’s not being accounted for in this return type annotation.</p>
 <p>Anyway, you can list the types of errors that can be returned from the function by listing them on the left side of the exclamation mark. While the valid values stay on the right side of the exclamation mark. So the syntax format become:</p>
 <pre><code>&lt;error-value&gt;!&lt;valid-value&gt;</code></pre>
 </section>
 <section id="error-sets" class="level3" data-number="10.1.2">
 <h3 data-number="10.1.2" class="anchored" data-anchor-id="error-sets"><span class="header-section-number">10.1.2</span> Error sets</h3>
 <p>But what about when we have a single function that might return different types of errors? When you have such a function, you can list all of these different types of errors that can be returned from this function, through a structure in Zig that we call of an <em>error set</em>.</p>
-<p>An error set is a special case of an union type. It is an union that contains error values in it. Not all programming languages have a notion of an “union object”. But in summary, an union is just a set of data types. Unions are used to allow an object to have multiple data types. For example, a union of <code>x</code>, <code>y</code> and <code>z</code>, means that an object can be either of type <code>x</code>, or type <code>y</code> or type <code>z</code>.</p>
-<p>We are going to talk in more depth about unions at <a href="#sec-unions" class="quarto-xref"><span>Section 10.3</span></a>. But you can write an error set by writing the keyword <code>error</code> before a pair of curly braces, then you list the error values that can be returned from the function inside this pair of curly braces.</p>
+<p>An error set is a special case of a union type. It’s a union that contains error values in it. Not all programming languages have a notion of a “union object”. But in summary, a union is just a set of data types. Unions are used to allow an object to have multiple data types. For example, a union of <code>x</code>, <code>y</code> and <code>z</code>, means that an object can be either of type <code>x</code>, or type <code>y</code> or type <code>z</code>.</p>
+<p>We are going to talk in more depth about unions in <a href="#sec-unions" class="quarto-xref"><span>Section 10.3</span></a>. But you can write an error set by writing the keyword <code>error</code> before a pair of curly braces, then you list the error values that can be returned from the function inside this pair of curly braces.</p>
 <p>Take the <code>resolvePath()</code> function below as an example, which comes from the <code>introspect.zig</code> module of the Zig Standard Library. We can see in its return type annotation, that this function return either: 1) a valid slice of <code>u8</code> values (<code>[]u8</code>); or, 2) one of the three different types of error values listed inside the error set (<code>OutOfMemory</code>, <code>Unexpected</code>, etc.). This is an usage example of an error set.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb6"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> resolvePath(</span>
@@ -420,7 +420,7 @@ <h3 data-number="10.1.2" class="anchored" data-anchor-id="error-sets"><span clas
 <span id="cb6-10"><a href="#cb6-10" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>This is a valid way of annotating the return value of a Zig function. But, if you navigate through the modules that composes the Zig Standard Library, you will notice that, for the majority of cases, the programmers prefer to give a descriptive name to this error set, and then, use this name (or this “label”) of the error set in the return type annotation, instead of using the error set directly.</p>
-<p>We can see that in the <code>ReadError</code> error set that we showed earlier in the <code>fill()</code> function, which is defined in the <code>http.Client</code> module. So yes, I presented the <code>ReadError</code> as if it was just a standard and single error value, but in fact, it is an error set defined in the <code>http.Client</code> module, and therefore, it actually represents a set of different error values that might happen inside the <code>fill()</code> function.</p>
+<p>We can see that in the <code>ReadError</code> error set that we showed earlier in the <code>fill()</code> function, which is defined in the <code>http.Client</code> module. So yes, I presented the <code>ReadError</code> as if it was just a standard and single error value, but in fact, it’s an error set defined in the <code>http.Client</code> module, and therefore, it actually represents a set of different error values that might happen inside the <code>fill()</code> function.</p>
 <p>Take a look at the <code>ReadError</code> definition reproduced below. Notice that we are grouping all of these different error values into a single object, and then, we use this object into the return type annotation of the function. Like the <code>fill()</code> function that we showed earlier, or, the <code>readvDirect()</code> function from the same module, which is reproduced below.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb7"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">const</span> ReadError = <span class="kw">error</span><span class="op">{</span></span>
@@ -469,7 +469,7 @@ <h3 data-number="10.1.3" class="anchored" data-anchor-id="casting-error-values">
 <span id="cb8-20"><a href="#cb8-20" aria-hidden="true" tabindex="-1"></a>    );</span>
 <span id="cb8-21"><a href="#cb8-21" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 filea64e1da1167c.test.coerce error value...OKA
+<pre><code>1/1 file826379a872a1.test.coerce error value...OKA
   All 1 tests passed.</code></pre>
 </div>
 </div>
@@ -487,7 +487,7 @@ <h2 data-number="10.2" class="anchored" data-anchor-id="how-to-handle-errors"><s
 <section id="what-try-means" class="level3" data-number="10.2.1">
 <h3 data-number="10.2.1" class="anchored" data-anchor-id="what-try-means"><span class="header-section-number">10.2.1</span> What <code>try</code> means?</h3>
 <p>As I described over the previous sections, when we say that an expression might return an error, we are basically referring to an expression that have a return type in the format <code>!T</code>. The <code>!</code> indicates that this expression returns either an error value, or a value of type <code>T</code>.</p>
-<p>At <a href="01-zig-weird.html#sec-main-file" class="quarto-xref"><span>Section 1.2.3</span></a>, I presented the <code>try</code> keyword and where to use it. But I did not talked about what exactly this keyword does to your code, or, in other words, I have not explained yet what <code>try</code> means in your code.</p>
+<p>In <a href="01-zig-weird.html#sec-main-file" class="quarto-xref"><span>Section 1.2.3</span></a>, I presented the <code>try</code> keyword and where to use it. But I did not talked about what exactly this keyword does to your code, or, in other words, I have not explained yet what <code>try</code> means in your code.</p>
 <p>In essence, when you use the <code>try</code> keyword in an expression, you are telling the <code>zig</code> compiler the following: “Hey! Execute this expression for me, and, if this expression return an error, please, return this error for me and stop the execution of my program. But if this expression return a valid value, then, return this value, and move on”.</p>
 <p>In other words, the <code>try</code> keyword is essentially, a strategy to enter in panic mode, and stop the execution of your program in case an error occurs. With the <code>try</code> keyword, you are telling the <code>zig</code> compiler, that stopping the execution of your program is the most reasonable strategy to take if an error occurs in that particular expression.</p>
 </section>
@@ -511,7 +511,7 @@ <h3 data-number="10.2.2" class="anchored" data-anchor-id="the-catch-keyword"><sp
 <p>Therefore, we use <code>catch</code> to create a block of expressions that will handle the error. I can return the error value from this block of expressions, like I did in the above example, which, will make the program enter in panic mode, and, stop the execution. But I could also, return a valid value from this block of code, which would be stored in the <code>file</code> object.</p>
 <p>Notice that, instead of writing the keyword before the expression that might return the error, like we do with <code>try</code>, we write <code>catch</code> after the expression. We can open the pair of pipes (<code>|</code>), which captures the error value returned by the expression, and makes this error value available in the scope of the <code>catch</code> block as the object named <code>err</code>. In other words, because I wrote <code>|err|</code> in the code, I can access the error value returned by the expression, by using the <code>err</code> object.</p>
 <p>Although this being the most common use of <code>catch</code>, you can also use this keyword to handle the error in a “default value” style. That is, if the expression returns an error, we use the default value instead. Otherwise, we use the valid value returned by the expression.</p>
-<p>The Zig official language reference, provides a great example of this “default value” strategy with <code>catch</code>. This example is reproduced below. Notice that we are trying to parse some unsigned integer from a string object named <code>str</code>. In other words, this function is trying to transform an object of type <code>[]const u8</code> (i.e.&nbsp;an array of characters, a string, etc.) into an object of type <code>u64</code>.</p>
+<p>The Zig official language reference, provides a great example of this “default value” strategy with <code>catch</code>. This example is reproduced below. Notice that we are trying to parse some unsigned integer from a string object named <code>str</code>. In other words, this function is trying to transform an object of type <code>[]const u8</code> (i.e., an array of characters, a string, etc.) into an object of type <code>u64</code>.</p>
 <p>But this parsing process done by the function <code>parseU64()</code> may fail, resulting in a runtime error. The <code>catch</code> keyword used in this example provides an alternative value (13) to be used in case this <code>parseU64()</code> function raises an error. So, the expression below essentially means: “Hey! Please, parse this string into a <code>u64</code> for me, and store the results into the object <code>number</code>. But, if an error occurs, then, use the value <code>13</code> instead”.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb11"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> number = parseU64(str, <span class="dv">10</span>) <span class="kw">catch</span> <span class="dv">13</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
@@ -522,7 +522,7 @@ <h3 data-number="10.2.2" class="anchored" data-anchor-id="the-catch-keyword"><sp
 <h3 data-number="10.2.3" class="anchored" data-anchor-id="using-if-statements"><span class="header-section-number">10.2.3</span> Using if statements</h3>
 <p>Now, you can also use if statements to handle errors in your Zig code. In the example below, I’m reproducing the previous example, where we try to parse an integer value from an input string with a function named <code>parseU64()</code>.</p>
 <p>We execute the expression inside the “if”. If this expression returns an error value, the “if branch” (or, the “true branch”) of the if statement is not executed. But if this expression returns a valid value instead, then, this value is unwrapped into the <code>number</code> object.</p>
-<p>This means that, if the <code>parseU64()</code> expression returns a valid value, this value becomes available inside the scope of this “if branch” (i.e.&nbsp;the “true branch”) through the object that we listed inside the pair of pipe character (<code>|</code>), which is the object <code>number</code>.</p>
+<p>This means that, if the <code>parseU64()</code> expression returns a valid value, this value becomes available inside the scope of this “if branch” (i.e., the “true branch”) through the object that we listed inside the pair of pipe character (<code>|</code>), which is the object <code>number</code>.</p>
 <p>If an error occurs, we can use an “else branch” (or the “false branch”) of the if statement to handle the error. In the example below, we are using the <code>else</code> in the if statement to unwrap the error value (that was returned by <code>parseU64()</code>) into the <code>err</code> object, and handle the error.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb12"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a><span class="kw">if</span> (parseU64(str, <span class="dv">10</span>)) |number| <span class="op">{</span></span>
@@ -554,9 +554,9 @@ <h3 data-number="10.2.3" class="anchored" data-anchor-id="using-if-statements"><
 <section id="sec-errdefer2" class="level3" data-number="10.2.4">
 <h3 data-number="10.2.4" class="anchored" data-anchor-id="sec-errdefer2"><span class="header-section-number">10.2.4</span> The <code>errdefer</code> keyword</h3>
 <p>A common pattern in C programs in general, is to clean resources when an error occurs during the execution of the program. In other words, one common way to handle errors, is to perform “cleanup actions” before we exit our program. This guarantees that a runtime error does not make our program to leak resources of the system.</p>
-<p>The <code>errdefer</code> keyword is a tool to perform such “cleanup actions” in hostile situations. This keyword is commonly used to clean (or to free) allocated resources, before the execution of our program get’s stopped because of an error value being generated.</p>
-<p>The basic idea is to provide an expression to the <code>errdefer</code> keyword. Then, <code>errdefer</code> executes this expression if, and only if, an error occurs during the execution of the current scope. In the example below, we are using an allocator object (that we have presented at <a href="01-memory.html#sec-allocators" class="quarto-xref"><span>Section 3.3</span></a>) to create a new <code>User</code> object. If we are successful in creating and registering this new user, this <code>create_user()</code> function will return this new <code>User</code> object as its return value.</p>
-<p>However, if for some reason, an error value is generated by some expression that is after the <code>errdefer</code> line, for example, in the <code>db.add(user)</code> expression, the expression registered by <code>errdefer</code> get’s executed before the error value is returned from the function, and before the program enters in panic mode and stops the current execution.</p>
+<p>The <code>errdefer</code> keyword is a tool to perform such “cleanup actions” in hostile situations. This keyword is commonly used to clean (or to free) allocated resources, before the execution of our program gets stopped because of an error value being generated.</p>
+<p>The basic idea is to provide an expression to the <code>errdefer</code> keyword. Then, <code>errdefer</code> executes this expression if, and only if, an error occurs during the execution of the current scope. In the example below, we are using an allocator object (that we have presented in <a href="01-memory.html#sec-allocators" class="quarto-xref"><span>Section 3.3</span></a>) to create a new <code>User</code> object. If we are successful in creating and registering this new user, this <code>create_user()</code> function will return this new <code>User</code> object as its return value.</p>
+<p>However, if for some reason, an error value is generated by some expression that is after the <code>errdefer</code> line, for example, in the <code>db.add(user)</code> expression, the expression registered by <code>errdefer</code> gets executed before the error value is returned from the function, and before the program enters in panic mode and stops the current execution.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb14"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> create_user(db: Database, allocator: Allocator) !User <span class="op">{</span></span>
 <span id="cb14-2"><a href="#cb14-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> user = <span class="kw">try</span> allocator.create(User);</span>
@@ -567,19 +567,19 @@ <h3 data-number="10.2.4" class="anchored" data-anchor-id="sec-errdefer2"><span c
 <span id="cb14-7"><a href="#cb14-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> user;</span>
 <span id="cb14-8"><a href="#cb14-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>By using <code>errdefer</code> to destroy the <code>user</code> object that we have just created, we guarantee that the memory allocated for this <code>user</code> object get’s freed, before the execution of the program stops. Because if the expression <code>try db.add(user)</code> returns an error value, the execution of our program stops, and we lose all references and control over the memory that we have allocated for the <code>user</code> object. As a result, if we do not free the memory associated with the <code>user</code> object before the program stops, we cannot free this memory anymore. We simply lose our chance to do the right thing. That is why <code>errdefer</code> is essential in this situation.</p>
-<p>Just to state clearly the differences between <code>defer</code> and <code>errdefer</code> (which I described at <a href="03-structs.html#sec-defer" class="quarto-xref"><span>Section 2.1.3</span></a> and <a href="03-structs.html#sec-errdefer1" class="quarto-xref"><span>Section 2.1.4</span></a>), it might be worth to discuss the subject a bit further. You might still have the question “why use <code>errdefer</code> if we can use <code>defer</code> instead?” in your mind.</p>
-<p>Although being similar, the key difference between <code>errdefer</code> and <code>defer</code> keyword is when the provided expression get’s executed. The <code>defer</code> keyword always execute the provided expression at the end of the current scope, no matter how your code exits this scope. In contrast, <code>errdefer</code> executes the provided expression only when an error occurs in the current scope.</p>
-<p>This becomes important if a resource that you allocate in the current scope get’s freed later in your code, in a different scope. The <code>create_user()</code> functions is an example of this. If you think closely about this function, you will notice that this function returns the <code>user</code> object as the result.</p>
+<p>By using <code>errdefer</code> to destroy the <code>user</code> object that we have just created, we guarantee that the memory allocated for this <code>user</code> object gets freed, before the execution of the program stops. Because if the expression <code>try db.add(user)</code> returns an error value, the execution of our program stops, and we lose all references and control over the memory that we have allocated for the <code>user</code> object. As a result, if we do not free the memory associated with the <code>user</code> object before the program stops, we cannot free this memory anymore. We simply lose our chance to do the right thing. That is why <code>errdefer</code> is essential in this situation.</p>
+<p>Just to state clearly the differences between <code>defer</code> and <code>errdefer</code> (which I described in <a href="03-structs.html#sec-defer" class="quarto-xref"><span>Section 2.1.3</span></a> and <a href="03-structs.html#sec-errdefer1" class="quarto-xref"><span>Section 2.1.4</span></a>), it might be worth to discuss the subject a bit further. You might still have the question “why use <code>errdefer</code> if we can use <code>defer</code> instead?” in your mind.</p>
+<p>Although being similar, the key difference between <code>errdefer</code> and <code>defer</code> keyword is when the provided expression gets executed. The <code>defer</code> keyword always execute the provided expression at the end of the current scope, no matter how your code exits this scope. In contrast, <code>errdefer</code> executes the provided expression only when an error occurs in the current scope.</p>
+<p>This becomes important if a resource that you allocate in the current scope gets freed later in your code, in a different scope. The <code>create_user()</code> functions is an example of this. If you think closely about this function, you will notice that this function returns the <code>user</code> object as the result.</p>
 <p>In other words, the allocated memory for the <code>user</code> object does not get freed inside the <code>create_user()</code> function, if it returns successfully. So, if an error does not occur inside this function, the <code>user</code> object is returned from the function, and probably, the code that runs after this <code>create_user()</code> function will be responsible for freeing the memory of the <code>user</code> object.</p>
 <p>But what if an error occurs inside the <code>create_user()</code> function? What happens then? This would mean that the execution of your code would stop in this <code>create_user()</code> function, and, as a consequence, the code that runs after this <code>create_user()</code> function would simply not run, and, as a result, the memory of the <code>user</code> object would not be freed before your program stops.</p>
 <p>This is the perfect scenario for <code>errdefer</code>. We use this keyword to guarantee that our program will free the allocated memory for the <code>user</code> object, even if an error occurs inside the <code>create_user()</code> function.</p>
-<p>If you allocate and free some memory for an object inside the same scope, then, just use <code>defer</code> and be happy, i.e.&nbsp;<code>errdefer</code> have no use for you in such situation. But if you allocate some memory in a scope A, but you only free this memory later, in a scope B for example, then, <code>errdefer</code> becomes useful to avoid leaking memory in sketchy situations.</p>
+<p>If you allocate and free some memory for an object inside the same scope, then, just use <code>defer</code> and be happy, i.e., <code>errdefer</code> have no use for you in such situation. But if you allocate some memory in a scope A, but you only free this memory later, in a scope B for example, then, <code>errdefer</code> becomes useful to avoid leaking memory in sketchy situations.</p>
 </section>
 </section>
 <section id="sec-unions" class="level2" data-number="10.3">
 <h2 data-number="10.3" class="anchored" data-anchor-id="sec-unions"><span class="header-section-number">10.3</span> Union type in Zig</h2>
-<p>An union type defines a set of types that an object can be. It is like a list of options. Each option is a type that an object can assume. Therefore, unions in Zig have the same meaning, or, the same role as unions in C. They are used for the same purpose. You could also say that unions in Zig produces a similar effect to <a href="https://docs.python.org/3/library/typing.html#typing.Union">using <code>typing.Union</code> in Python</a><a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>.</p>
+<p>A union type defines a set of types that an object can be. It’s like a list of options. Each option is a type that an object can assume. Therefore, unions in Zig have the same meaning, or, the same role as unions in C. They are used for the same purpose. You could also say that unions in Zig produces a similar effect to <a href="https://docs.python.org/3/library/typing.html#typing.Union">using <code>typing.Union</code> in Python</a><a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>.</p>
 <p>For example, you might be creating an API that sends data to a data lake, hosted in some private cloud infrastructure. Suppose you have created different structs in your codebase, to store the necessary information that you need, in order to connect to the services of each mainstream data lake service (Amazon S3, Azure Blob, etc.).</p>
 <p>Now, suppose you also have a function named <code>send_event()</code> that receives an event as input, and, a target data lake, and it sends the input event to the data lake specified in the target data lake argument. But this target data lake could be any of the three mainstream data lakes services (Amazon S3, Azure Blob, etc.). Here is where an union can help you.</p>
 <p>The union <code>LakeTarget</code> defined below allows the <code>lake_target</code> argument of <code>send_event()</code> to be either an object of type <code>AzureBlob</code>, or type <code>AmazonS3</code>, or type <code>GoogleGCP</code>. This union allows the <code>send_event()</code> function to receive an object of any of these three types as input in the <code>lake_target</code> argument.</p>
@@ -599,7 +599,7 @@ <h2 data-number="10.3" class="anchored" data-anchor-id="sec-unions"><span class=
 <span id="cb15-12"><a href="#cb15-12" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>An union definition is composed by a list of data members. Each data member is of a specific data type. In the example above, the <code>LakeTarget</code> union have three data members (<code>azure</code>, <code>amazon</code>, <code>google</code>). When you instantiate an object that uses an union type, you can only use one of its data members in this instantiation.</p>
-<p>You could also interpret this as: only one data member of an union type can be activated at a time, the other data members remain deactivated and unaccessible. For example, if you create a <code>LakeTarget</code> object that uses the <code>azure</code> data member, you can no longer use or access the data members <code>google</code> or <code>amazon</code>. It is like if these other data members didn’t exist at all in the <code>LakeTarget</code> type.</p>
+<p>You could also interpret this as: only one data member of an union type can be activated at a time, the other data members remain deactivated and unaccessible. For example, if you create a <code>LakeTarget</code> object that uses the <code>azure</code> data member, you can no longer use or access the data members <code>google</code> or <code>amazon</code>. It’s like if these other data members didn’t exist at all in the <code>LakeTarget</code> type.</p>
 <p>You can see this logic in the example below. Notice that, we first instantiate the union object using the <code>azure</code> data member. As a result, this <code>target</code> object contains only the <code>azure</code> data member inside of it. Only this data member is active in this object. That is why the last line in this code example is invalid. Because we are trying to instantiate the data member <code>google</code>, which is currently inactive for this <code>target</code> object, and as a result, the program enters in panic mode warning us about this mistake through a loud error message.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb16"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> target = LakeTarget <span class="op">{</span></span>
@@ -624,7 +624,7 @@ <h2 data-number="10.3" class="anchored" data-anchor-id="sec-unions"><span class=
 <span id="cb18-5"><a href="#cb18-5" aria-hidden="true" tabindex="-1"></a>    .google = GoogleGCP.init()</span>
 <span id="cb18-6"><a href="#cb18-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>A curious fact about union types, is that, at first, you cannot use them in switch statements (which were presented at <a href="03-structs.html#sec-switch" class="quarto-xref"><span>Section 2.1.2</span></a>). In other words, if you have an object of type <code>LakeTarget</code> for example, you cannot give this object as input to a switch statement.</p>
+<p>A curious fact about union types, is that, at first, you cannot use them in switch statements (which were presented in <a href="03-structs.html#sec-switch" class="quarto-xref"><span>Section 2.1.2</span></a>). In other words, if you have an object of type <code>LakeTarget</code> for example, you cannot give this object as input to a switch statement.</p>
 <p>But what if you really need to do so? What if you actually need to provide an “union object” to a switch statement? The answer to this question relies on another special type in Zig, which are the <em>tagged unions</em>. To create a tagged union, all you have to do is to add an enum type into your union declaration.</p>
 <p>As an example of a tagged union in Zig, take the <code>Registry</code> type exposed below. This type comes from the <a href="https://github.com/ziglang/zig/blob/30b4a87db711c368853b3eff8e214ab681810ef9/tools/spirv/grammar.zig"><code>grammar.zig</code> module</a><a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a> from the Zig repository. This union type lists different types of registries. But notice this time, the use of <code>(enum)</code> after the <code>union</code> keyword. This is what makes this union type a tagged union. By being a tagged union, an object of this <code>Registry</code> type can be used as input in a switch statement. This is all you have to do. Just add <code>(enum)</code> to your <code>union</code> declaration, and you can use it in switch statements.</p>
 <div class="cell">
diff --git a/docs/Chapters/10-stack-project.html b/docs/Chapters/10-stack-project.html
index bd3e9cbb..5476994b 100644
--- a/docs/Chapters/10-stack-project.html
+++ b/docs/Chapters/10-stack-project.html
@@ -348,8 +348,8 @@ <h1 class="title"><span class="chapter-number">12</span>&nbsp; <span class="chap
 <p>But before we get into building the stack data structure, we first need to understand what the <code>comptime</code> keyword does to your code, and after that, we also need to learn about how generics work in Zig.</p>
 <section id="sec-comptime" class="level2" data-number="12.1">
 <h2 data-number="12.1" class="anchored" data-anchor-id="sec-comptime"><span class="header-section-number">12.1</span> Understanding <code>comptime</code> in Zig</h2>
-<p>One of the key features of Zig is <code>comptime</code>. This keyword introduces a whole new concept and paradigm, that is tightly connected with the compilation process. At <a href="01-memory.html#sec-compile-time" class="quarto-xref"><span>Section 3.1.1</span></a> we have described the importance and the role that “compile-time versus runtime” plays into Zig. At that section, we learned that the rules applied to a value/object change a lot depending on whether this value is known at compile-time, or just at runtime.</p>
-<p>The <code>comptime</code> keyword is strongly related to these two spaces in time (compile-time and runtime). Let’s quickly recap the differences. Compile-time is the period of time when your Zig source code is being compiled by the <code>zig</code> compiler, while the runtime is the period of time when your Zig program is being executed, i.e.&nbsp;when we execute the binary files that were generated by the <code>zig</code> compiler.</p>
+<p>One of the key features of Zig is <code>comptime</code>. This keyword introduces a whole new concept and paradigm, that is tightly connected with the compilation process. In <a href="01-memory.html#sec-compile-time" class="quarto-xref"><span>Section 3.1.1</span></a> we have described the importance and the role that “compile-time versus runtime” plays into Zig. In that section, we learned that the rules applied to a value/object change a lot depending on whether this value is known at compile-time, or just at runtime.</p>
+<p>The <code>comptime</code> keyword is strongly related to these two spaces in time (compile-time and runtime). Let’s quickly recap the differences. Compile-time is the period of time when your Zig source code is being compiled by the <code>zig</code> compiler, while the runtime is the period of time when your Zig program is being executed, i.e., when we execute the binary files that were generated by the <code>zig</code> compiler.</p>
 <p>There are three ways in which you can apply the <code>comptime</code> keyword, which are:</p>
 <ul>
 <li>apply <code>comptime</code> on a function argument.</li>
@@ -358,7 +358,7 @@ <h2 data-number="12.1" class="anchored" data-anchor-id="sec-comptime"><span clas
 </ul>
 <section id="applying-over-a-function-argument" class="level3" data-number="12.1.1">
 <h3 data-number="12.1.1" class="anchored" data-anchor-id="applying-over-a-function-argument"><span class="header-section-number">12.1.1</span> Applying over a function argument</h3>
-<p>When you apply the <code>comptime</code> keyword on a function argument, you are saying to the <code>zig</code> compiler that the value assigned to that particular function argument must be known at compile-time. We explained in details at <a href="01-memory.html#sec-compile-time" class="quarto-xref"><span>Section 3.1.1</span></a> what exactly “value known at compile-time” means, so, in case you have doubts about this idea, come back to that section.</p>
+<p>When you apply the <code>comptime</code> keyword on a function argument, you are saying to the <code>zig</code> compiler that the value assigned to that particular function argument must be known at compile-time. We explained in detail in <a href="01-memory.html#sec-compile-time" class="quarto-xref"><span>Section 3.1.1</span></a> what exactly “value known at compile-time” means. So if you have any doubts about this idea, refer back to that section.</p>
 <p>Now let’s think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement to that particular function argument. If the programmer accidentally tries to give a value to this function argument that is not known at compile time, the <code>zig</code> compiler will notice this problem, and as a consequence, it will raise a compilation error saying that it cannot compile your program. Because you are providing a value that is “runtime known” to a function argument that must be “compile-time known”.</p>
 <p>Take a look at this very simple example below, where we define a <code>twice()</code> function, that simply doubles the input value named <code>num</code>. Notice that we use the <code>comptime</code> keyword before the name of the function argument. This keyword is marking the function argument <code>num</code> as a “comptime argument”.</p>
 <p>That is a function argument whose value must be compile-time known. This is why the expression <code>twice(5678)</code> is valid, and no compilation errors are raised. Because the value <code>5678</code> is compile-time known, so this is the expected behaviour for this function.</p>
@@ -370,7 +370,7 @@ <h3 data-number="12.1.1" class="anchored" data-anchor-id="applying-over-a-functi
 <span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a>    _ = twice(<span class="dv">5678</span>);</span>
 <span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 filea72d248f97f8.test.test comptime...OKAll 1 
+<pre><code>1/1 file833f3ad20be9.test.test comptime...OKAll 1 
    tests passed.</code></pre>
 </div>
 </div>
@@ -391,26 +391,26 @@ <h3 data-number="12.1.1" class="anchored" data-anchor-id="applying-over-a-functi
 <span id="cb3-12"><a href="#cb3-12" aria-hidden="true" tabindex="-1"></a>    _ = twice(n);</span>
 <span id="cb3-13"><a href="#cb3-13" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<pre><code>t.zig:12:16: error: runtime-known argument passed to comptime parameter </code></pre>
-<p>Comptime arguments are frequently used on functions that return some sort of generic structure. In fact, <code>comptime</code> is the essence (or the basis) to make generics in Zig. We are going to talk more about generics at <a href="#sec-generics" class="quarto-xref"><span>Section 12.2</span></a>.</p>
-<p>For now, let’s take a look at this code example from <span class="citation" data-cites="karlseguin_generics">Seguin (<a href="../references.html#ref-karlseguin_generics" role="doc-biblioref">2024</a>)</span>. You can see that this <code>IntArray()</code> function have one argument named <code>length</code>. This argument is marked as comptime, and receives a value of type <code>usize</code> as input. So the value given to this argument must be compile-time known. We can also see that this function returns an array of <code>i64</code> values as output.</p>
+<pre><code>t.zig:12:16: error: runtime-known argument passed to comptime parameter</code></pre>
+<p>Comptime arguments are frequently used on functions that return some sort of generic structure. In fact, <code>comptime</code> is the essence (or the basis) to make generics in Zig. We are going to talk more about generics in <a href="#sec-generics" class="quarto-xref"><span>Section 12.2</span></a>.</p>
+<p>For now, let’s take a look at this code example from <span class="citation" data-cites="karlseguin_generics">Seguin (<a href="../references.html#ref-karlseguin_generics" role="doc-biblioref">2024</a>)</span>. You can see that this <code>IntArray()</code> function has one argument named <code>length</code>. This argument is marked as comptime, and receives a value of type <code>usize</code> as input. So the value given to this argument must be compile-time known. We can also see that this function returns an array of <code>i64</code> values as output.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb5"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> IntArray(<span class="kw">comptime</span> length: <span class="dt">usize</span>) <span class="dt">type</span> <span class="op">{</span></span>
 <span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> [length]<span class="dt">i64</span>;</span>
 <span id="cb5-3"><a href="#cb5-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>Now, the key component of this function is the <code>length</code> argument. This argument is used to determine the size of the array that is produced by the function. Let’s think about the consequences of that. If the size of the array is dependent on the value assigned to the <code>length</code> argument, this means that the data type of the output of the function depends on the value of this <code>length</code> argument.</p>
-<p>Let this statement sink for a bit in your mind. As I described at <a href="01-zig-weird.html#sec-root-file" class="quarto-xref"><span>Section 1.2.2</span></a>, Zig is a strongly-typed language, especially on function declarations. So every time we write a function in Zig, we have to annotate the data type of the value returned by the function. But how can we do that, if this data type depends on the value given to the argument of the function?</p>
+<p>Let this statement sink for a bit in your mind. As I described in <a href="01-zig-weird.html#sec-root-file" class="quarto-xref"><span>Section 1.2.2</span></a>, Zig is a strongly-typed language, especially on function declarations. So every time we write a function in Zig, we have to annotate the data type of the value returned by the function. But how can we do that, if this data type depends on the value given to the argument of the function?</p>
 <p>Think about this for a second. If <code>length</code> is equal to 3 for example, then, the return type of the function is <code>[3]i64</code>. But if <code>length</code> is equal to 40, then, the return type becomes <code>[40]i64</code>. At this point the <code>zig</code> compiler would be confused, and raise a compilation error, saying something like this:</p>
 <blockquote class="blockquote">
 <p>Hey! You have annotated that this function should return a <code>[3]i64</code> value, but I got a <code>[40]i64</code> value instead! This doesn’t look right!</p>
 </blockquote>
-<p>So how can you solve this problem? How do we overcome this barrier? This is when the <code>type</code> keyword comes in. This <code>type</code> keyword is basically saying to the <code>zig</code> compiler that this function will return some data type as output, but it doesn’t know yet what exactly data type that is. We will talk more about this at <a href="#sec-generics" class="quarto-xref"><span>Section 12.2</span></a>.</p>
+<p>So how can you solve this problem? How do we overcome this barrier? This is when the <code>type</code> keyword comes in. This <code>type</code> keyword is basically saying to the <code>zig</code> compiler that this function will return some data type as output, but it doesn’t know yet what exactly data type that is. We will talk more about this in <a href="#sec-generics" class="quarto-xref"><span>Section 12.2</span></a>.</p>
 </section>
 <section id="applying-over-an-expression" class="level3" data-number="12.1.2">
 <h3 data-number="12.1.2" class="anchored" data-anchor-id="applying-over-an-expression"><span class="header-section-number">12.1.2</span> Applying over an expression</h3>
 <p>When you apply the <code>comptime</code> keyword over an expression, then, it is guaranteed that the <code>zig</code> compiler will execute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time (e.g.&nbsp;for example, maybe this expression depends on a value that is only known at runtime), then, the <code>zig</code> compiler will raise a compilation error.</p>
-<p>Take this example from the official documentation of Zig <span class="citation" data-cites="zigdocs">(<a href="../references.html#ref-zigdocs" role="doc-biblioref">Zig Software Foundation 2024</a>)</span>. We are executing the same <code>fibonacci()</code> function both at runtime, and, at compile-time. The function is by default executed at runtime, but because we use the <code>comptime</code> keyword at the second “try expression”, this expression is executed at compile-time.</p>
+<p>Take this example from the official documentation of Zig <span class="citation" data-cites="zigdocs">(<a href="../references.html#ref-zigdocs" role="doc-biblioref">Zig Software Foundation 2024</a>)</span>. We are executing the same <code>fibonacci()</code> function both at runtime, and, at compile-time. The function is executed by default at runtime, but because we use the <code>comptime</code> keyword in the second “try expression”, this expression is executed at compile-time.</p>
 <p>This might be a bit confusing for some people. Yes! When I say that this expression is executed at compile-time, I mean that this expression is compiled and executed while the <code>zig</code> compiler is compiling your Zig source code.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb6"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = <span class="bu">@import</span>(<span class="st">"std"</span>).testing.expect;</span>
@@ -426,16 +426,16 @@ <h3 data-number="12.1.2" class="anchored" data-anchor-id="applying-over-an-expre
 <span id="cb6-11"><a href="#cb6-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> <span class="kw">comptime</span> expect(fibonacci(<span class="dv">7</span>) == <span class="dv">13</span>);</span>
 <span id="cb6-12"><a href="#cb6-12" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 filea72d3cf7abe2.test.fibonacci...OKAll 1 test
+<pre><code>1/1 file833f119d55a3.test.fibonacci...OKAll 1 test
   ts passed.</code></pre>
 </div>
 </div>
-<p>A lot of your Zig source code might be potentially executed at compile-time, because the <code>zig</code> compiler can figure it out the output of some expressions. Especially if these expressions depends only at compile-time known values. We have talked about this at <a href="01-memory.html#sec-compile-time" class="quarto-xref"><span>Section 3.1.1</span></a>.</p>
+<p>A lot of your Zig source code might be potentially executed at compile-time, because the <code>zig</code> compiler can figure out the output of some expressions. Especially if these expressions depend only on compile-time known values. We have talked about this in <a href="01-memory.html#sec-compile-time" class="quarto-xref"><span>Section 3.1.1</span></a>.</p>
 <p>But when you use the <code>comptime</code> keyword on an expression, there is no “it might be executed at compile-time” anymore. With the <code>comptime</code> keyword you are ordering the <code>zig</code> compiler to execute this expression at compile-time. You are imposing this rule, it is guaranteed that the compiler will always execute it at compile-time. Or, at least, the compiler will try to execute it. If the compiler cannot execute the expression for whatever reason, the compiler will raise a compilation error.</p>
 </section>
 <section id="applying-over-a-block" class="level3" data-number="12.1.3">
 <h3 data-number="12.1.3" class="anchored" data-anchor-id="applying-over-a-block"><span class="header-section-number">12.1.3</span> Applying over a block</h3>
-<p>Blocks were described at <a href="01-zig-weird.html#sec-blocks" class="quarto-xref"><span>Section 1.7</span></a>. When you apply the <code>comptime</code> keyword over a block of expressions, you get essentially the same effect when you apply this keyword to a single expression. That is, the entire block of expressions is executed at compile-time by the <code>zig</code> compiler.</p>
+<p>Blocks were described in <a href="01-zig-weird.html#sec-blocks" class="quarto-xref"><span>Section 1.7</span></a>. When you apply the <code>comptime</code> keyword to a block of expressions, you get essentially the same effect as when you apply this keyword to a single expression. That is, the entire block of expressions is executed at compile-time by the <code>zig</code> compiler.</p>
 <p>In the example below, we mark the block labeled of <code>blk</code> as a comptime block, and, therefore, the expressions inside this block are executed at compile-time.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb8"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = <span class="bu">@import</span>(<span class="st">"std"</span>).testing.expect;</span>
@@ -455,7 +455,7 @@ <h3 data-number="12.1.3" class="anchored" data-anchor-id="applying-over-a-block"
 <span id="cb8-15"><a href="#cb8-15" aria-hidden="true" tabindex="-1"></a>    _ = x;</span>
 <span id="cb8-16"><a href="#cb8-16" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 filea72d6353d586.test.fibonacci in a block...O
+<pre><code>1/1 file833f6ccf145c.test.fibonacci in a block...O
   OKAll 1 tests passed.</code></pre>
 </div>
 </div>
@@ -463,13 +463,13 @@ <h3 data-number="12.1.3" class="anchored" data-anchor-id="applying-over-a-block"
 </section>
 <section id="sec-generics" class="level2" data-number="12.2">
 <h2 data-number="12.2" class="anchored" data-anchor-id="sec-generics"><span class="header-section-number">12.2</span> Introducing Generics</h2>
-<p>First of all, what is a generic? Generic is the idea to allow a type (<code>f64</code>, <code>u8</code>, <code>u32</code>, <code>bool</code>, and also, user-defined types, like the <code>User</code> struct that we defined at <a href="03-structs.html#sec-structs-and-oop" class="quarto-xref"><span>Section 2.3</span></a>) to be a parameter to methods, classes and interfaces <span class="citation" data-cites="geeks_generics">(<a href="../references.html#ref-geeks_generics" role="doc-biblioref">Geeks for Geeks 2024</a>)</span>. In other words, a “generic” is a class (or a method) that can work with multiple data types.</p>
+<p>First of all, what is a generic? Generic is the idea to allow a type (<code>f64</code>, <code>u8</code>, <code>u32</code>, <code>bool</code>, and also, user-defined types, like the <code>User</code> struct that we defined in <a href="03-structs.html#sec-structs-and-oop" class="quarto-xref"><span>Section 2.3</span></a>) to be a parameter to methods, classes and interfaces <span class="citation" data-cites="geeks_generics">(<a href="../references.html#ref-geeks_generics" role="doc-biblioref">Geeks for Geeks 2024</a>)</span>. In other words, a “generic” is a class (or a method) that can work with multiple data types.</p>
 <p>For example, in Java, generics are created through the operator <code>&lt;&gt;</code>. With this operator, a Java class is capable of receiving a data type as input, and therefore, the class can fit its features according to this input data type. As another example, generics in C++ are supported through the concept of templates. Class templates in C++ are generics.</p>
 <p>In Zig, generics are implemented through <code>comptime</code>. The <code>comptime</code> keyword allows us to collect a data type at compile time, and pass this data type as input to a piece of code.</p>
 <section id="sec-generic-fun" class="level3" data-number="12.2.1">
 <h3 data-number="12.2.1" class="anchored" data-anchor-id="sec-generic-fun"><span class="header-section-number">12.2.1</span> A generic function</h3>
-<p>Take the <code>max()</code> function exposed below as a first example. This function is essentially a “generic function”. In this function, we have a comptime function argument named <code>T</code>. Notice that this <code>T</code> argument have a data type of <code>type</code>. Weird right? This <code>type</code> keyword is the “father of all types”, or, “the type of types” in Zig.</p>
-<p>Because we have used this <code>type</code> keyword in the <code>T</code> argument, we are telling the <code>zig</code> compiler that this <code>T</code> argument will receive some data type as input. Also notice the use of the <code>comptime</code> keyword in this argument. As I described at <a href="#sec-comptime" class="quarto-xref"><span>Section 12.1</span></a>, every time you use this keyword in a function argument, this means that the value of this argument must be known at compile-time. This makes sense, right? Because there is no data type that is not known at compile-time.</p>
+<p>Take the <code>max()</code> function exposed below as a first example. This function is essentially a “generic function”. In this function, we have a comptime function argument named <code>T</code>. Notice that this <code>T</code> argument has a data type of <code>type</code>. Weird right? This <code>type</code> keyword is the “father of all types”, or, “the type of types” in Zig.</p>
+<p>Because we have used this <code>type</code> keyword in the <code>T</code> argument, we are telling the <code>zig</code> compiler that this <code>T</code> argument will receive some data type as input. Also notice the use of the <code>comptime</code> keyword in this argument. As I described in <a href="#sec-comptime" class="quarto-xref"><span>Section 12.1</span></a>, every time you use this keyword in a function argument, this means that the value of this argument must be known at compile-time. This makes sense, right? Because there is no data type that is not known at compile-time.</p>
 <p>Think about this. Every data type that you will ever write is always known at compile-time. Especially because data types are an essential information for the compiler to actually compile your source code. Having this in mind, makes sense to mark this argument as a comptime argument.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb10"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> max(<span class="kw">comptime</span> T: <span class="dt">type</span>, a: T, b: T) T <span class="op">{</span></span>
@@ -477,7 +477,7 @@ <h3 data-number="12.2.1" class="anchored" data-anchor-id="sec-generic-fun"><span
 <span id="cb10-3"><a href="#cb10-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>Also notice that the value of the <code>T</code> argument is actually used to define the data type of the other arguments in the function, <code>a</code> and <code>b</code>, and also at the return type annotation of the function. That is, the data type of these arguments (<code>a</code> and <code>b</code>), and, the return data type of the function itself, are determined by the input value given to the <code>T</code> argument.</p>
-<p>As a result, we have a generic function that works with different data types. For example, I can provide <code>u8</code> values to this <code>max()</code> function, and it will work as expected. But if I provide <code>f64</code> values instead, it will also work as expected. Without a generic function, I would have to write a different <code>max()</code> function for each one of the data types that I wanted to use. This generic function provides a very useful shortcut for us.</p>
+<p>As a result, we have a generic function that works with different data types. For example, I can provide <code>u8</code> values to this <code>max()</code> function, and it will work as expected. But if I provide <code>f64</code> values instead, it will also work as expected. Without a generic function, I would have to write a different <code>max()</code> function for each data type I wanted to use. This generic function provides a very useful shortcut for us.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb11"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb11-2"><a href="#cb11-2" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> max(<span class="kw">comptime</span> T: <span class="dt">type</span>, a: T, b: T) T <span class="op">{</span></span>
@@ -496,9 +496,9 @@ <h3 data-number="12.2.1" class="anchored" data-anchor-id="sec-generic-fun"><span
 <section id="sec-generic-struct" class="level3" data-number="12.2.2">
 <h3 data-number="12.2.2" class="anchored" data-anchor-id="sec-generic-struct"><span class="header-section-number">12.2.2</span> A generic data structure</h3>
 <p>Every data structure that you find in the Zig Standard Library (e.g.&nbsp;<code>ArrayList</code>, <code>HashMap</code>, etc.) is essentially a generic data structure. These data structures are generic in the sense that they work with any data type you want. You just say which is the data type of the values that are going to be stored in this data structure, and they just work as expected.</p>
-<p>A generic data structure in Zig is how you replicate a generic class from Java, or, a class template from C++. But you may quest yourself: how do we build a generic data structure in Zig?</p>
+<p>A generic data structure in Zig is how you replicate a generic class from Java, or, a class template from C++. But you may ask yourself: how do we build a generic data structure in Zig?</p>
 <p>The basic idea is to write a generic function that creates the data structure definition for the specific type we want. In other words, this generic function behaves as a “factory of data structures”. The generic function outputs the <code>struct</code> definition that defines this data structure for a specific data type.</p>
-<p>To create such function, we need to add a comptime argument to this function that receives a data type as input. We already learned how to do this at the previous section (<a href="#sec-generic-fun" class="quarto-xref"><span>Section 12.2.1</span></a>). I think the best way to demonstrate how to create a generic data structure is to actually write one. This where we go into our next small project in this book. This one is a very small project, which is to write a generic stack data structure.</p>
+<p>To create such function, we need to add a comptime argument to this function that receives a data type as input. We already learned how to do this in the previous section (<a href="#sec-generic-fun" class="quarto-xref"><span>Section 12.2.1</span></a>). I think the best way to demonstrate how to create a generic data structure is to actually write one. This where we go into our next small project in this book. This one is a very small project, which is to write a generic stack data structure.</p>
 </section>
 </section>
 <section id="sec-what-stack" class="level2" data-number="12.3">
@@ -522,7 +522,7 @@ <h2 data-number="12.3" class="anchored" data-anchor-id="sec-what-stack"><span cl
 <section id="writing-the-stack-data-structure" class="level2" data-number="12.4">
 <h2 data-number="12.4" class="anchored" data-anchor-id="writing-the-stack-data-structure"><span class="header-section-number">12.4</span> Writing the stack data structure</h2>
 <p>We are going to write the stack data structure in two steps. First, we are going to implement a stack that can only store <code>u32</code> values. Then, after that, we are going to extend our implementation to make it generic, so that it works with any data type we want.</p>
-<p>First, we need to decide how the values will be stored inside the stack. There are multiple ways to implement the storage behind a stack structure. Some people prefer to use a doubly linked list, some others prefer to use a dynamic array, etc. In this example we are going to use an array behind the hood, to store the values in the stack, which is the <code>items</code> data member of our <code>Stack</code> struct definition.</p>
+<p>First, we need to decide how the values will be stored inside the stack. There are multiple ways to implement the storage behind a stack structure. Some people prefer to use a doubly linked list, others prefer to use a dynamic array, etc. In this example we are going to use an array behind the hood, to store the values in the stack, which is the <code>items</code> data member of our <code>Stack</code> struct definition.</p>
 <p>Also notice in our <code>Stack</code> struct that we have three other data members: <code>capacity</code>, <code>length</code> and <code>allocator</code>. The <code>capacity</code> member contains the capacity of the underlying array that stores the values in the stack. The <code>length</code> contains the number of values that are currently being stored in the stack. And the <code>allocator</code> contains the allocator object that will be used by the stack structure whenever it needs to allocate more space for the values that are being stored.</p>
 <p>We begin by defining an <code>init()</code> method of this struct, which is going to be responsible for instantiating a <code>Stack</code> object. Notice that, inside this <code>init()</code> method, we start by allocating an array with the capacity specified in the <code>capacity</code> argument.</p>
 <div class="cell">
@@ -548,10 +548,10 @@ <h2 data-number="12.4" class="anchored" data-anchor-id="writing-the-stack-data-s
 <section id="implementing-the-push-operation" class="level3" data-number="12.4.1">
 <h3 data-number="12.4.1" class="anchored" data-anchor-id="implementing-the-push-operation"><span class="header-section-number">12.4.1</span> Implementing the <code>push</code> operation</h3>
 <p>Now that we have written the basic logic to create a new <code>Stack</code> object, we can start writing the logic responsible for performing a push operation. Remember, a push operation in a stack data structure is the operation responsible for adding a new value to the stack.</p>
-<p>So how can we add a new value to the <code>Stack</code> object that we have? The <code>push()</code> function exposed below is a possible answer to this question. Remember from what we discussed at <a href="#sec-what-stack" class="quarto-xref"><span>Section 12.3</span></a> that values are always added to the top of the stack. This means that this <code>push()</code> function must always find the element in the underlying array that currently represents the top position of the stack, and then, add the input value there.</p>
+<p>So how can we add a new value to the <code>Stack</code> object that we have? The <code>push()</code> function exposed below is a possible answer to this question. Remember from what we discussed in <a href="#sec-what-stack" class="quarto-xref"><span>Section 12.3</span></a> that values are always added to the top of the stack. This means that this <code>push()</code> function must always find the element in the underlying array that currently represents the top position of the stack, and then, add the input value there.</p>
 <p>First, we have an if statement in this function. This if statement is checking whether we need to expand the underlying array to store this new value that we are adding to the stack. In other words, maybe the underlying array does not have enough capacity to store this new value, and, in this case, we need to expand our array to get the capacity that we need.</p>
 <p>So, if the logical test in this if statement returns true, it means that the array does not have enough capacity, and we need to expand it before we store this new value. So inside this if statement we are executing the necessary expressions to expand the underlying array. Notice that we use the allocator object to allocate a new array that is twice as bigger than the current array (<code>self.capacity * 2</code>).</p>
-<p>After that, we use a different built-in function named <code>@memcpy()</code>. This built-in function is equivalent to the <code>memcpy()</code> function from the C Standard Library<a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>. It is used to copy the values from one block of memory to another block of memory. In other words, you can use this function to copy the values from one array into another array.</p>
+<p>After that, we use a different built-in function named <code>@memcpy()</code>. This built-in function is equivalent to the <code>memcpy()</code> function from the C Standard Library<a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>. It’s used to copy the values from one block of memory to another block of memory. In other words, you can use this function to copy the values from one array into another array.</p>
 <p>We are using this <code>@memcpy()</code> built-in function to copy the values that are currently stored in the underlying array of the stack object (<code>self.items</code>) into our new and bigger array that we have allocated (<code>new_buf</code>). After we execute this function, the <code>new_buf</code> contains a copy of the values that are present at <code>self.items</code>.</p>
 <p>Now that we have secured a copy of our current values in the <code>new_buf</code> object, we can now free the memory currently allocated at <code>self.items</code>. After that, we just need to assign our new and bigger array to <code>self.items</code>. This is the sequence of steps necessary to expand our array.</p>
 <div class="cell">
@@ -602,11 +602,11 @@ <h3 data-number="12.4.3" class="anchored" data-anchor-id="implementing-the-deini
 </section>
 <section id="making-it-generic" class="level2" data-number="12.5">
 <h2 data-number="12.5" class="anchored" data-anchor-id="making-it-generic"><span class="header-section-number">12.5</span> Making it generic</h2>
-<p>Now that we have implemented the basic skeleton of our stack data structure, we can now focus on discussing how can we make it generic. How can we make this basic skeleton to work not only with <code>u32</code> values, but also, with any other data type we want? For example, we might need to create a stack object to store <code>User</code> values in it. How can we make this possible? The answer lies on the use of generics and <code>comptime</code>.</p>
-<p>As I described at <a href="#sec-generic-struct" class="quarto-xref"><span>Section 12.2.2</span></a>, the basic idea is to write a generic function that returns a struct definition as output. In theory, we do not need much to transform our <code>Stack</code> struct into a generic data structure. All that we need to do is to transform the underlying array of the stack into a generic array.</p>
-<p>In other words, this underlying array needs to be a “chameleon”. It needs to adapt, and transform it into an array of any data type that we want. For example, if we need to create a stack that will store <code>u8</code> values, then, this underlying array needs to be a <code>u8</code> array (i.e.&nbsp;<code>[]u8</code>). But if we need to store <code>User</code> values instead, then, this array needs to be a <code>User</code> array (i.e.&nbsp;<code>[]User</code>). Etc.</p>
+<p>Now that we have implemented the basic skeleton of our stack data structure, we can now focus on discussing how we can make it generic. How can we make this basic skeleton to work not only with <code>u32</code> values, but also with any other data type we want? For example, we might need to create a stack object to store <code>User</code> values in it. How can we make this possible? The answer lies in the use of generics and <code>comptime</code>.</p>
+<p>As I described in <a href="#sec-generic-struct" class="quarto-xref"><span>Section 12.2.2</span></a>, the basic idea is to write a generic function that returns a struct definition as output. In theory, we do not need much to transform our <code>Stack</code> struct into a generic data structure. All that we need to do is to transform the underlying array of the stack into a generic array.</p>
+<p>In other words, this underlying array needs to be a “chameleon”. It needs to adapt, and transform it into an array of any data type that we want. For example, if we need to create a stack that will store <code>u8</code> values, then this underlying array needs to be a <code>u8</code> array (i.e., <code>[]u8</code>). But if we need to store <code>User</code> values instead, then, this array needs to be a <code>User</code> array (i.e., <code>[]User</code>). Etc.</p>
 <p>We do that by using a generic function. Because a generic function can receive a data type as input, and we can pass this data type to the struct definition of our <code>Stack</code> object. Therefore, we can use the generic function to create a <code>Stack</code> object that can store the data type we want. If we want to create a stack structure that stores <code>User</code> values, we pass the <code>User</code> data type to this generic function, and it will create for us the struct definition that describes a <code>Stack</code> object that can store <code>User</code> values in it.</p>
-<p>Look at the code example below. I have omitted some parts of the <code>Stack</code> struct definition for brevity reasons. However, if a specific part of our <code>Stack</code> struct is not exposed here in this example, then it is because this part did not change from the previous example. It remains the same.</p>
+<p>Look at the code example below. I have omitted some parts of the <code>Stack</code> struct definition for brevity. However, if a specific part of our <code>Stack</code> struct is not exposed here in this example, then it’s because this part did not change from the previous example. It remains the same.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb17"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> Stack(<span class="kw">comptime</span> T: <span class="dt">type</span>) <span class="dt">type</span> <span class="op">{</span></span>
 <span id="cb17-2"><a href="#cb17-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> <span class="kw">struct</span> <span class="op">{</span></span>
@@ -633,7 +633,7 @@ <h2 data-number="12.5" class="anchored" data-anchor-id="making-it-generic"><span
 <span id="cb17-23"><a href="#cb17-23" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>Notice that we have created a function in this example named <code>Stack()</code>. This function takes a type as input, and passes this type to the struct definition of our <code>Stack</code> object. The data member <code>items</code> is now, an array of type <code>T</code>, which is the data type that we have provided as input to the function. The function argument <code>val</code> in the <code>push()</code> function is now a value of type <code>T</code> too.</p>
-<p>We can just provide a data type to this function, and it will create a definition of a <code>Stack</code> object that can store values of the data type that we have provided. In the example below, we are creating the definition of a <code>Stack</code> object that can store <code>u8</code> values in it. This definition is stored at the <code>Stacku8</code> object. This <code>Stacku8</code> object becomes our new struct, it is the struct that we are going to use to create our <code>Stack</code> object.</p>
+<p>We can just provide a data type to this function, and it will create a definition of a <code>Stack</code> object that can store values of the data type that we have provided. In the example below, we are creating the definition of a <code>Stack</code> object that can store <code>u8</code> values in it. This definition is stored at the <code>Stacku8</code> object. This <code>Stacku8</code> object becomes our new struct, that we are going to use to create our <code>Stack</code> object.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb18"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb18-1"><a href="#cb18-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> gpa = std.heap.GeneralPurposeAllocator(.<span class="op">{}</span>)<span class="op">{}</span>;</span>
 <span id="cb18-2"><a href="#cb18-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> allocator = gpa.allocator();</span>
@@ -668,7 +668,7 @@ <h2 data-number="12.5" class="anchored" data-anchor-id="making-it-generic"><span
 </section>
 <section id="conclusion" class="level2" data-number="12.6">
 <h2 data-number="12.6" class="anchored" data-anchor-id="conclusion"><span class="header-section-number">12.6</span> Conclusion</h2>
-<p>The full source code of the stack structure discussed in this chapter is freely available at the official repository of this book. Just checkout the <a href="https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig"><code>stack.zig</code></a><a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a> for the <code>u32</code> version of our stack, and the <a href="https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig"><code>generic_stack.zig</code></a><a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a> for the generic version, available inside the <code>ZigExamples</code> folder of the repository.</p>
+<p>The full source code of the stack structure discussed in this chapter is freely available in the official repository of this book. Just checkout the <a href="https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig"><code>stack.zig</code></a><a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a> for the <code>u32</code> version of our stack, and the <a href="https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig"><code>generic_stack.zig</code></a><a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a> for the generic version, available inside the <code>ZigExamples</code> folder of the repository.</p>
 
 
 <div id="refs" class="references csl-bib-body hanging-indent" data-entry-spacing="0" role="list" style="display: none">
diff --git a/docs/Chapters/12-file-op.html b/docs/Chapters/12-file-op.html
index e00c2578..916de07c 100644
--- a/docs/Chapters/12-file-op.html
+++ b/docs/Chapters/12-file-op.html
@@ -396,7 +396,7 @@ <h2 data-number="13.1" class="anchored" data-anchor-id="sec-io-basics"><span cla
 <p>If you have some experience in a high-level language, you have certainly used these input and output functionalities before in this language. In other words, you certainly have been in a situation where you needed to sent some output to the user, or, to receive an input from the user.</p>
 <p>For example, in Python we can receive some input from the user by using the <code>input()</code> built-in function. But we can also print (or “show”) some output to the user by using the <code>print()</code> built-in function. So yes, if you have programmed before in Python, you certainly have used these functions once before.</p>
 <p>But do you know how these functions relate back to your operating system (OS)? How exactly they are interacting with the resources of your OS to receive or sent some input/output. In essence, these input/output functions from high-level languages are just abstractions over the <em>standard output</em> and <em>standard input</em> channels of your operating system.</p>
-<p>This means that we receive an input, or send some output, through the operating system. It is the OS that makes the bridge between the user and your program. Your program does not have a direct access to the user. It is the OS that intermediates every message exchanged between your program and the user.</p>
+<p>This means that we receive an input, or send some output, through the operating system. It’s the OS that makes the bridge between the user and your program. Your program does not have a direct access to the user. It’s the OS that intermediates every message exchanged between your program and the user.</p>
 <p>The <em>standard output</em> and <em>standard input</em> channels of your OS are commonly known as the <code>stdout</code> and <code>stdin</code> channels of your OS, respectively. In some contexts, they are also called the <em>standard output device</em> and the <em>standard input device</em>. As the name suggests, the <em>standard output</em> is the channel through which output flows, while the <em>standard input</em> is the channel in which input flows.</p>
 <p>Furthermore, OS’s also normally create a dedicated channel for exchanging error messages, which is known as the <em>standard error</em> channel, or, the <code>stderr</code> channel. This is the channel to which error and warning messages are usually sent to. These are the messages that are normally displayed in red-like or orange-like colors into your terminal.</p>
 <p>Normally, every OS (e.g.&nbsp;Windows, macOS, Linux, etc.) creates a dedicated and separate set of <em>standard output</em>, <em>standard error</em> and <em>standard input</em> channels for every single program (or process) that runs in your computer. This means that every program you write have a dedicated <code>stdin</code>, <code>stderr</code> and <code>stdout</code> that are separate from the <code>stdin</code>, <code>stderr</code> and <code>stdout</code> of other programs and processes that are currently running.</p>
@@ -406,12 +406,12 @@ <h3 data-number="13.1.1" class="anchored" data-anchor-id="sec-writer-reader"><sp
 <p>In Zig, there is a pattern around input/output (IO). I (the author of this book) don’t know if there is an official name for this pattern. But here, in this book, I will call it the “writer and reader pattern”. In essence, every IO operation in Zig is made through either a <code>GenericReader</code> or a <code>GenericWriter</code> object<a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>.</p>
 <p>These two data types come from the <code>std.io</code> module of the Zig Standard Library. As their names suggests, a <code>GenericReader</code> is an object that offers tools to read data from “something” (or “somewhere”), while a <code>GenericWriter</code> offers tools to write data into this “something”. This “something” might be different things: like a file that exists in your filesystem; or, it might be a network socket in your system<a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a>; or, a continuous stream of data, like a standard input device from your system, that might be constantly receiving new data from users, or, as another example, a live chat in a game that is constantly receiving and displaying new messages from the players of the game.</p>
 <p>So, if you want to <strong>read</strong> data from something, or somewhere, it means that you need to use a <code>GenericReader</code> object. But if you need instead, to <strong>write</strong> data into this “something”, then, you need to use a <code>GenericWriter</code> object instead. Both of these objects are normally created from a file descriptor object. More specifically, through the <code>writer()</code> and <code>reader()</code> methods of this file descriptor object. If you are not familiar with this type of object, go to the next section.</p>
-<p>Every <code>GenericWriter</code> object have methods like <code>print()</code>, which allows you to write/send a formatted string (i.e.&nbsp;this formatted string is like a <code>f</code> string in Python, or, similar to the <code>printf()</code> C function) into the “something” (file, socket, stream, etc.) that you are using. It also have a <code>writeAll()</code> method, which allows you to write a string, or, an array of bytes into the “something”.</p>
-<p>Likewise, every <code>GenericReader</code> object have methods like <code>readAll()</code>, which allows you to read the data from the “something” (file, socket, stream, etc.) until it fills a particular array (i.e.&nbsp;a “buffer”) object. In other words, if you provide an array object of 300 <code>u8</code> values to <code>readAll()</code>, then, this method attempts to read 300 bytes of data from the “something”, and it stores them into the array object that you have provided.</p>
-<p>We also have other methods, like the <code>readAtLeast()</code> method, which allows you to specify how many bytes exactly you want to read from the “something”. In more details, if you give the number <span class="math inline">\(n\)</span> as input to this method, then, it will attempt to read at least <span class="math inline">\(n\)</span> bytes of data from the “something”. The “something” might have less than <span class="math inline">\(n\)</span> bytes of data available for you to read, so, it is not guaranteed that you will get precisely <span class="math inline">\(n\)</span> bytes as result.</p>
+<p>Every <code>GenericWriter</code> object have methods like <code>print()</code>, which allows you to write/send a formatted string (i.e., this formatted string is like a <code>f</code> string in Python, or, similar to the <code>printf()</code> C function) into the “something” (file, socket, stream, etc.) that you are using. It also have a <code>writeAll()</code> method, which allows you to write a string, or, an array of bytes into the “something”.</p>
+<p>Likewise, every <code>GenericReader</code> object have methods like <code>readAll()</code>, which allows you to read the data from the “something” (file, socket, stream, etc.) until it fills a particular array (i.e., a “buffer”) object. In other words, if you provide an array object of 300 <code>u8</code> values to <code>readAll()</code>, then, this method attempts to read 300 bytes of data from the “something”, and it stores them into the array object that you have provided.</p>
+<p>We also have other methods, like the <code>readAtLeast()</code> method, which allows you to specify how many bytes exactly you want to read from the “something”. In more details, if you give the number <span class="math inline">\(n\)</span> as input to this method, then, it will attempt to read at least <span class="math inline">\(n\)</span> bytes of data from the “something”. The “something” might have less than <span class="math inline">\(n\)</span> bytes of data available for you to read, so, it’s not guaranteed that you will get precisely <span class="math inline">\(n\)</span> bytes as result.</p>
 <p>Another useful method is <code>readUntilDelimiterOrEof()</code>. In this method, you specify a “delimiter character”. The idea is that this function will attempt to read as many bytes of data as possible from the “something”, until it encounters the end of the stream, or, it encounters the “delimiter character” that you have specified.</p>
 <p>If you don’t know exactly how many bytes will come from the “something”, you may find the <code>readAllAlloc()</code> method useful. In essence, you provide an allocator object to this method, so that it can allocate more space if needed. As consequence, this method will try to read all bytes of the “something”, and, if it runs out of space at some point during the “reading process”, it uses the allocator object to allocate more space to continue reading the bytes. As result, this method returns a slice to the array object containing all the bytes read.</p>
-<p>This is just a quick description of the methods present in these types of objects. But I recommend you to read the official docs, both for <a href="https://ziglang.org/documentation/master/std/#std.io.GenericWriter"><code>GenericWriter</code></a><a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a> and <a href="https://ziglang.org/documentation/master/std/#std.io.GenericReader"><code>GenericReader</code></a><a href="#fn4" class="footnote-ref" id="fnref4" role="doc-noteref"><sup>4</sup></a>. I also think it is a good idea to read the source code of the modules in the Zig Standard Library that defines the methods present in these objects, which are the <a href="https://github.com/ziglang/zig/blob/master/lib/std/io/Reader.zig"><code>Reader.zig</code></a><a href="#fn5" class="footnote-ref" id="fnref5" role="doc-noteref"><sup>5</sup></a> and <a href=""><code>Writer.zig</code></a><a href="#fn6" class="footnote-ref" id="fnref6" role="doc-noteref"><sup>6</sup></a>.</p>
+<p>This is just a quick description of the methods present in these types of objects. But I recommend you to read the official docs, both for <a href="https://ziglang.org/documentation/master/std/#std.io.GenericWriter"><code>GenericWriter</code></a><a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a> and <a href="https://ziglang.org/documentation/master/std/#std.io.GenericReader"><code>GenericReader</code></a><a href="#fn4" class="footnote-ref" id="fnref4" role="doc-noteref"><sup>4</sup></a>. I also think it’s a good idea to read the source code of the modules in the Zig Standard Library that defines the methods present in these objects, which are the <a href="https://github.com/ziglang/zig/blob/master/lib/std/io/Reader.zig"><code>Reader.zig</code></a><a href="#fn5" class="footnote-ref" id="fnref5" role="doc-noteref"><sup>5</sup></a> and <a href=""><code>Writer.zig</code></a><a href="#fn6" class="footnote-ref" id="fnref6" role="doc-noteref"><sup>6</sup></a>.</p>
 </section>
 <section id="sec-file-descriptor" class="level3" data-number="13.1.2">
 <h3 data-number="13.1.2" class="anchored" data-anchor-id="sec-file-descriptor"><span class="header-section-number">13.1.2</span> Introducing file descriptors</h3>
@@ -425,7 +425,7 @@ <h3 data-number="13.1.2" class="anchored" data-anchor-id="sec-file-descriptor"><
 <p>From the bullet points listed above, we know that although the term “file” is present, a “file descriptor” might describe something more than just a file. This concept of a “file descriptor” comes from the Portable Operating System Interface (POSIX) API, which is a set of standards that guide how operating systems across the world should be implemented, to maintain compatibility between them.</p>
 <p>A file descriptor not only identifies the input/output resource that you are using to receive or send some data, but it also describes where this resource is, and also, which IO mode this resource is currently using. For example, this IO resource might be using only the “read” IO mode, which means that this resource is open to “read operations”, while “write operations” are not authorized. These IO modes are essentially the modes that you provide to the argument <code>mode</code> from the <code>fopen()</code> C function, and also, from the <code>open()</code> Python built-in function.</p>
 <p>In C, a “file descriptor” is a <code>FILE</code> pointer, but, in Zig, a file descriptor is a <code>File</code> object. This data type (<code>File</code>) is described in the <code>std.fs</code> module of the Zig Standard Library. We normally don’t create a <code>File</code> object directly in our Zig code. Instead, we normally get such object as result when we open an IO resource. In other words, we normally ask our OS to open a particular IO resource for us, and, if the OS do open successfully this IO resource, the OS normally handles back to us a file descriptor to this particular IO resource.</p>
-<p>So you usually get a <code>File</code> object by using functions and methods from the Zig Standard Library that asks the OS to open some IO resource, like the <code>openFile()</code> method that opens a file in the filesystem. The <code>net.Stream</code> object that we have created at <a href="04-http-server.html#sec-create-socket" class="quarto-xref"><span>Section 7.4.1</span></a> is also a type of file descriptor object.</p>
+<p>So you usually get a <code>File</code> object by using functions and methods from the Zig Standard Library that asks the OS to open some IO resource, like the <code>openFile()</code> method that opens a file in the filesystem. The <code>net.Stream</code> object that we have created in <a href="04-http-server.html#sec-create-socket" class="quarto-xref"><span>Section 7.4.1</span></a> is also a type of file descriptor object.</p>
 </section>
 <section id="the-standard-output" class="level3" data-number="13.1.3">
 <h3 data-number="13.1.3" class="anchored" data-anchor-id="the-standard-output"><span class="header-section-number">13.1.3</span> The <em>standard output</em></h3>
@@ -449,7 +449,7 @@ <h3 data-number="13.1.3" class="anchored" data-anchor-id="the-standard-output"><
 </section>
 <section id="the-standard-input" class="level3" data-number="13.1.4">
 <h3 data-number="13.1.4" class="anchored" data-anchor-id="the-standard-input"><span class="header-section-number">13.1.4</span> The <em>standard input</em></h3>
-<p>You can access the <em>standard input</em> (i.e.&nbsp;<code>stdin</code>) in Zig by using the <code>getStdIn()</code> function from the <code>std.io</code> module. Like its brother (<code>getStdOut()</code>), this function also returns a file descriptor object that describes the <code>stdin</code> channel of your OS.</p>
+<p>You can access the <em>standard input</em> (i.e., <code>stdin</code>) in Zig by using the <code>getStdIn()</code> function from the <code>std.io</code> module. Like its brother (<code>getStdOut()</code>), this function also returns a file descriptor object that describes the <code>stdin</code> channel of your OS.</p>
 <p>Because we want to receive some input from the user, the key verb here becomes <strong>receive</strong>, and, as consequence, we usually want to <strong>read</strong> data from the <code>stdin</code> channel, instead of writing data into it. So, we normally use the <code>reader()</code> method of the file descriptor object returned by <code>getStdIn()</code>, to get access to a <code>GenericReader</code> object that we can use to read data from <code>stdin</code>.</p>
 <p>In the example below, we are creating a small buffer capable of holding 20 characters. Then, we try to read the data from the <code>stdin</code> with the <code>readUntilDelimiterOrEof()</code> method, and save this data into the <code>buffer</code> object. Also notice that we are reading the data from the <code>stdin</code> until we hit a new line character (<code>'\n'</code>).</p>
 <p>If you execute this program, you will notice that it stops the execution, ands start to wait indefinitely for some input from the user. In other words, you need to type your name into the terminal, and then, you press Enter to send your name to <code>stdin</code>. After you send your name to <code>stdin</code>, the program reads this input, and continues with the execution, by printing the given name to <code>stdout</code>. In the example below, I typed my name (Pedro) into the terminal, and then, pressed Enter.</p>
@@ -476,14 +476,14 @@ <h3 data-number="13.1.5" class="anchored" data-anchor-id="the-standard-error"><s
 </section>
 <section id="buffered-io" class="level2" data-number="13.2">
 <h2 data-number="13.2" class="anchored" data-anchor-id="buffered-io"><span class="header-section-number">13.2</span> Buffered IO</h2>
-<p>As we described at <a href="#sec-io-basics" class="quarto-xref"><span>Section 13.1</span></a>, input/output (IO) operations are made directly by the operating system. It is the OS that manages the IO resource that you want to use for your IO operations. The consequence of this fact is that IO operations are heavily based on system calls (i.e.&nbsp;calling the operating system directly).</p>
+<p>As we described in <a href="#sec-io-basics" class="quarto-xref"><span>Section 13.1</span></a>, input/output (IO) operations are made directly by the operating system. It’s the OS that manages the IO resource that you want to use for your IO operations. The consequence of this fact is that IO operations are heavily based on system calls (i.e., calling the operating system directly).</p>
 <p>Just to be clear, there is nothing particularly wrong with system calls. We use them all the time on any serious codebase written in any low-level programming language. However, system calls are always orders of magnitude slower than many different types of operations.</p>
-<p>So is perfectly fine to use a system call once in a while. But when these system calls are used often, you can clearly notice most of the time the loss of performance in your application. So, the good rule of thumbs is to use a system call only when it is needed, and also, only in infrequent situations, to reduce the number of system calls performed to a minimum.</p>
+<p>So is perfectly fine to use a system call once in a while. But when these system calls are used often, you can clearly notice most of the time the loss of performance in your application. So, the good rule of thumb is to use a system call only when it’s needed, and also, only in infrequent situations, to reduce the number of system calls performed to a minimum.</p>
 <section id="understanding-how-buffered-io-works" class="level3" data-number="13.2.1">
 <h3 data-number="13.2.1" class="anchored" data-anchor-id="understanding-how-buffered-io-works"><span class="header-section-number">13.2.1</span> Understanding how buffered IO works</h3>
-<p>Buffered IO is a strategy to achieve better performance. It is used to reduce the number of system calls made by IO operations, and, as consequence, achieve a much higher performance. At <a href="#fig-unbuffered-io" class="quarto-xref">Figure&nbsp;<span>13.1</span></a> and <a href="#fig-buffered-io" class="quarto-xref">Figure&nbsp;<span>13.2</span></a> you can find two different diagrams which presents the difference between read operations performed in an unbuffered IO environment versus a buffered IO environment.</p>
-<p>To give a better context to these diagrams, let’s suppose that we have a text file that contains the famous Lorem ipsum text<a href="#fn8" class="footnote-ref" id="fnref8" role="doc-noteref"><sup>8</sup></a> in our filesystem. Let’s also suppose that these diagrams at <a href="#fig-unbuffered-io" class="quarto-xref">Figure&nbsp;<span>13.1</span></a> and <a href="#fig-buffered-io" class="quarto-xref">Figure&nbsp;<span>13.2</span></a> are showing the read operations that we are performing to read the Lorem ipsum text from this text file. The first thing you will notice when looking at these diagrams, is that in an unbuffered environment the read operations leads to many system calls. More precisely, in the diagram exposed at <a href="#fig-unbuffered-io" class="quarto-xref">Figure&nbsp;<span>13.1</span></a> we get one system call per each byte that we read from the text file. On the other hand, at <a href="#fig-buffered-io" class="quarto-xref">Figure&nbsp;<span>13.2</span></a> we have only one system call at the very beginning.</p>
-<p>When we use a buffered IO system, at the first read operation we perform, instead of sending one single byte directly to our program, the OS first sends a chunk of bytes from the file to a buffer object (i.e.&nbsp;an array). This chunk of bytes are cached/stored inside this buffer object.</p>
+<p>Buffered IO is a strategy to achieve better performance. It’s used to reduce the number of system calls made by IO operations, and, as consequence, achieve a much higher performance. In <a href="#fig-unbuffered-io" class="quarto-xref">Figure&nbsp;<span>13.1</span></a> and <a href="#fig-buffered-io" class="quarto-xref">Figure&nbsp;<span>13.2</span></a> you can find two different diagrams which presents the difference between read operations performed in an unbuffered IO environment versus a buffered IO environment.</p>
+<p>To give a better context to these diagrams, let’s suppose that we have a text file that contains the famous Lorem ipsum text<a href="#fn8" class="footnote-ref" id="fnref8" role="doc-noteref"><sup>8</sup></a> in our filesystem. Let’s also suppose that these diagrams in <a href="#fig-unbuffered-io" class="quarto-xref">Figure&nbsp;<span>13.1</span></a> and <a href="#fig-buffered-io" class="quarto-xref">Figure&nbsp;<span>13.2</span></a> are showing the read operations that we are performing to read the Lorem ipsum text from this text file. The first thing you will notice when looking at these diagrams, is that in an unbuffered environment the read operations leads to many system calls. More precisely, in the diagram exposed in <a href="#fig-unbuffered-io" class="quarto-xref">Figure&nbsp;<span>13.1</span></a> we get one system call per each byte that we read from the text file. On the other hand, in <a href="#fig-buffered-io" class="quarto-xref">Figure&nbsp;<span>13.2</span></a> we have only one system call at the very beginning.</p>
+<p>When we use a buffered IO system, at the first read operation we perform, instead of sending one single byte directly to our program, the OS first sends a chunk of bytes from the file to a buffer object (i.e., an array). This chunk of bytes are cached/stored inside this buffer object.</p>
 <p>Therefore, from now on, for every new read operation that you perform, instead of making a new system call to ask for the next byte in the file to the OS, this read operation is redirected to the buffer object, that have this next byte already cached and ready to go.</p>
 <div id="fig-unbuffered-io" class="quarto-float quarto-figure quarto-figure-center anchored">
 <figure class="quarto-float quarto-float-fig figure">
@@ -505,20 +505,20 @@ <h3 data-number="13.2.1" class="anchored" data-anchor-id="understanding-how-buff
 </figcaption>
 </figure>
 </div>
-<p>This is the basic logic behind buffered IO systems. The size of the buffer object depends on multiple factors. But it is usually equal to the size of a full page of memory (4096 bytes). If we follow this logic, then, the OS reads the first 4096 bytes of the file and caches it into the buffer object. As long as your program does not consume all of these 4096 bytes from the buffer, you will not create new system calls.</p>
+<p>This is the basic logic behind buffered IO systems. The size of the buffer object depends on multiple factors. But it’s usually equal to the size of a full page of memory (4096 bytes). If we follow this logic, then, the OS reads the first 4096 bytes of the file and caches it into the buffer object. As long as your program does not consume all of these 4096 bytes from the buffer, you will not create new system calls.</p>
 <p>However, as soon as you consume all of these 4096 bytes from the buffer, it means that there is no bytes left in the buffer. In this situation, a new system call is made to ask the OS to send the next 4096 bytes in the file, and once again, these bytes are cached into the buffer object, and the cycle starts once again.</p>
 </section>
 <section id="buffered-io-across-different-languages" class="level3" data-number="13.2.2">
 <h3 data-number="13.2.2" class="anchored" data-anchor-id="buffered-io-across-different-languages"><span class="header-section-number">13.2.2</span> Buffered IO across different languages</h3>
 <p>IO operations made through a <code>FILE</code> pointer in C are buffered by default, so, at least in C, you don’t need to worry about this subject. But in contrast, IO operations in both Rust and Zig are not buffered depending on which functions from the standard libraries that you are using.</p>
-<p>For example, in Rust, buffered IO is implemented through the <code>BufReader</code> and <code>BufWriter</code> structs, while in Zig, it is implemented through the <code>BufferedReader</code> and <code>BufferedWriter</code> structs. So any IO operation that you perform through the <code>GenericWriter</code> and <code>GenericReader</code> objects that I presented at <a href="#sec-writer-reader" class="quarto-xref"><span>Section 13.1.1</span></a> are not buffered, which means that these objects might create a lot of system calls depending on the situation.</p>
+<p>For example, in Rust, buffered IO is implemented through the <code>BufReader</code> and <code>BufWriter</code> structs, while in Zig, it’s implemented through the <code>BufferedReader</code> and <code>BufferedWriter</code> structs. So any IO operation that you perform through the <code>GenericWriter</code> and <code>GenericReader</code> objects that I presented in <a href="#sec-writer-reader" class="quarto-xref"><span>Section 13.1.1</span></a> are not buffered, which means that these objects might create a lot of system calls depending on the situation.</p>
 </section>
 <section id="using-buffered-io-in-zig" class="level3" data-number="13.2.3">
 <h3 data-number="13.2.3" class="anchored" data-anchor-id="using-buffered-io-in-zig"><span class="header-section-number">13.2.3</span> Using buffered IO in Zig</h3>
 <p>Using buffered IO in Zig is actually very easy. All you have to do is to just give the <code>GenericWriter</code> object to the <code>bufferedWriter()</code> function, or, to give the <code>GenericReader</code> object to the <code>bufferedReader()</code> function. These functions come from the <code>std.io</code> module, and they will construct the <code>BufferedWriter</code> or <code>BufferedReader</code> object for you.</p>
 <p>After you create this new <code>BufferedWriter</code> or <code>BufferedReader</code> object, you can call the <code>writer()</code> or <code>reader()</code> method of this new object, to get access to a new (and buffered) generic reader or generic writer.</p>
 <p>Let’s describe the process once again. Every time that you have a file descriptor object, you first get the generic writer or generic reader object from it, by calling the <code>writer()</code> or <code>reader()</code> methods of this file descriptor object. Then, you provide this generic writer or generic reader to the <code>bufferedWriter()</code> or <code>bufferedReader()</code> function, which creates a new <code>BufferedWriter</code> or <code>BufferedReader</code> object. Then, you call the <code>writer()</code> or <code>reader()</code> methods of this buffered writer or buffered reader object, which gives you access to a generic writer or a generic reader object that is buffered.</p>
-<p>Take this program as an example. This program is demonstrating the process exposed at <a href="#fig-buffered-io" class="quarto-xref">Figure&nbsp;<span>13.2</span></a>. We are simply opening a text file that contains the Lorem ipsum text, and then, we create a buffered IO reader object at <code>bufreader</code>, and we use this <code>bufreader</code> object to read the contents of this file into a buffer object, then, we end the program by printing this buffer to <code>stdout</code>.</p>
+<p>Take this program as an example. This program is demonstrating the process exposed in <a href="#fig-buffered-io" class="quarto-xref">Figure&nbsp;<span>13.2</span></a>. We are simply opening a text file that contains the Lorem ipsum text, and then, we create a buffered IO reader object at <code>bufreader</code>, and we use this <code>bufreader</code> object to read the contents of this file into a buffer object, then, we end the program by printing this buffer to <code>stdout</code>.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb5"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> file = <span class="kw">try</span> std.fs.cwd().openFile(</span>
 <span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a>    <span class="st">"ZigExamples/file-io/lorem.txt"</span>, .<span class="op">{}</span></span>
@@ -549,7 +549,7 @@ <h3 data-number="13.2.3" class="anchored" data-anchor-id="using-buffered-io-in-z
 in finibus libero feugiat eget. Etiam vel ante at urna tincidunt
 posuere sit amet ut felis. Maecenas finibus suscipit tristique.
 Donec viverra non sapien id suscipit.</code></pre>
-<p>Despite being a buffered IO reader, this <code>bufreader</code> object is similar to any other <code>GenericReader</code> object, and have the exact same methods. So, although these two types of objects perform very different IO operations, they have the same interface, so you, the programmer, can interchangeably use them without the need to change anything in your source code. So a buffered IO reader or a buffered IO writer objects have the same methods than its generic and unbuffered brothers, i.e.&nbsp;the generic reader and generic writer objects that I presented at <a href="#sec-writer-reader" class="quarto-xref"><span>Section 13.1.1</span></a>.</p>
+<p>Despite being a buffered IO reader, this <code>bufreader</code> object is similar to any other <code>GenericReader</code> object, and have the exact same methods. So, although these two types of objects perform very different IO operations, they have the same interface, so you, the programmer, can interchangeably use them without the need to change anything in your source code. So a buffered IO reader or a buffered IO writer objects have the same methods than its generic and unbuffered brothers, i.e., the generic reader and generic writer objects that I presented in <a href="#sec-writer-reader" class="quarto-xref"><span>Section 13.1.1</span></a>.</p>
 <div class="callout callout-style-default callout-tip callout-titled">
 <div class="callout-header d-flex align-content-center">
 <div class="callout-icon-container">
@@ -567,12 +567,12 @@ <h3 data-number="13.2.3" class="anchored" data-anchor-id="using-buffered-io-in-z
 </section>
 <section id="filesystem-basics" class="level2" data-number="13.3">
 <h2 data-number="13.3" class="anchored" data-anchor-id="filesystem-basics"><span class="header-section-number">13.3</span> Filesystem basics</h2>
-<p>Now that we have discussed the basics around Input/Output operations in Zig, we need to talk about the basics around filesystems, which is another core part of any operating system. Also, filesystems are related to input/output, because the files that we store and create in our computer are considered an IO resource, as we described at <a href="#sec-file-descriptor" class="quarto-xref"><span>Section 13.1.2</span></a>.</p>
+<p>Now that we have discussed the basics around Input/Output operations in Zig, we need to talk about the basics around filesystems, which is another core part of any operating system. Also, filesystems are related to input/output, because the files that we store and create in our computer are considered an IO resource, as we described in <a href="#sec-file-descriptor" class="quarto-xref"><span>Section 13.1.2</span></a>.</p>
 <section id="the-concept-of-current-working-directory-cwd" class="level3" data-number="13.3.1">
 <h3 data-number="13.3.1" class="anchored" data-anchor-id="the-concept-of-current-working-directory-cwd"><span class="header-section-number">13.3.1</span> The concept of current working directory (CWD)</h3>
-<p>The working directory is the folder on your computer where you are currently rooted at. In other words, it is the folder that your program is currently looking at. Therefore, whenever you are executing a program, this program is always working with a specific folder on your computer. It is always in this folder that the program will initially look for the files you require, and it is also in this folder that the program will initially save all the files you ask it to save.</p>
-<p>The working directory is determined by the folder from which you invoke your program in the terminal. In other words, if you are in the terminal of your OS, and you execute a binary file (i.e.&nbsp;a program) from this terminal, the folder to which your terminal is pointing at is the current working directory of your program that is being executed.</p>
-<p>At <a href="#fig-cwd" class="quarto-xref">Figure&nbsp;<span>13.3</span></a> we have an example of me executing a program from the terminal. We are executing the program outputted by the <code>zig</code> compiler by compiling the Zig module named <code>hello.zig</code>. The CWD in this case is the <code>zig-book</code> folder. In other words, while the <code>hello.zig</code> program is executing, it will be looking at the <code>zig-book</code> folder, and any file operation that we perform inside this program, will be using this <code>zig-book</code> folder as the “starting point”, or, as the “central focus”.</p>
+<p>The working directory is the folder on your computer where you are currently rooted at. In other words, it’s the folder that your program is currently looking at. Therefore, whenever you are executing a program, this program is always working with a specific folder on your computer. It’s always in this folder that the program will initially look for the files you require, and it’s also in this folder that the program will initially save all the files you ask it to save.</p>
+<p>The working directory is determined by the folder from which you invoke your program in the terminal. In other words, if you are in the terminal of your OS, and you execute a binary file (i.e., a program) from this terminal, the folder to which your terminal is pointing at is the current working directory of your program that is being executed.</p>
+<p>In <a href="#fig-cwd" class="quarto-xref">Figure&nbsp;<span>13.3</span></a> we have an example of me executing a program from the terminal. We are executing the program outputted by the <code>zig</code> compiler by compiling the Zig module named <code>hello.zig</code>. The CWD in this case is the <code>zig-book</code> folder. In other words, while the <code>hello.zig</code> program is executing, it will be looking at the <code>zig-book</code> folder, and any file operation that we perform inside this program, will be using this <code>zig-book</code> folder as the “starting point”, or, as the “central focus”.</p>
 <div id="fig-cwd" class="quarto-float quarto-figure quarto-figure-center anchored">
 <figure class="quarto-float quarto-float-fig figure">
 <div aria-describedby="fig-cwd-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
@@ -587,10 +587,10 @@ <h3 data-number="13.3.1" class="anchored" data-anchor-id="the-concept-of-current
 </section>
 <section id="the-concept-of-paths" class="level3" data-number="13.3.2">
 <h3 data-number="13.3.2" class="anchored" data-anchor-id="the-concept-of-paths"><span class="header-section-number">13.3.2</span> The concept of paths</h3>
-<p>A path is essentially a location. It points to a location in your filesystem. We use paths to describe the location of files and folders in our computer. One important aspect about paths is that they are always written inside strings, i.e.&nbsp;they are always provided as text values.</p>
-<p>There are two types of paths that you can provide to any program in any OS: a relative path, or an absolute path. Absolute paths are paths that start at the root of your filesystem, and go all the way to the file name or the specific folder that you are referring to. This type of path is called absolute, because it points to an unique and absolute location on your computer. That is, there is no other existing location on your computer that corresponds to this path. It is an unique identifier.</p>
+<p>A path is essentially a location. It points to a location in your filesystem. We use paths to describe the location of files and folders in our computer. One important aspect about paths is that they are always written inside strings, i.e., they are always provided as text values.</p>
+<p>There are two types of paths that you can provide to any program in any OS: a relative path, or an absolute path. Absolute paths are paths that start at the root of your filesystem, and go all the way to the file name or the specific folder that you are referring to. This type of path is called absolute, because it points to an unique and absolute location on your computer. That is, there is no other existing location on your computer that corresponds to this path. It’s an unique identifier.</p>
 <p>In Windows, an absolute path is a path that starts with a hard disk identifier (e.g.&nbsp;<code>C:/Users/pedro</code>). On the other hand, absolute paths in Linux and macOS, are paths that start with a forward slash character (e.g.&nbsp;<code>/usr/local/bin</code>). Notice that a path is composed by “segments”. Each segment is connected to each other by a slash character (<code>\</code> or <code>/</code>). On Windows, the backward slash (<code>\</code>) is normally used to connect the path segments. While on Linux and macOS, the forward slash (<code>/</code>) is the character used to connect path segments.</p>
-<p>A relative path is a path that start at the CWD. In other words, a relative path is “relative to the CWD”. The path used to access the <code>hello.zig</code> file at <a href="#fig-cwd" class="quarto-xref">Figure&nbsp;<span>13.3</span></a> is an example of a relative path. This path is reproduced below. This path begins at the CWD, which in the context of <a href="#fig-cwd" class="quarto-xref">Figure&nbsp;<span>13.3</span></a>, is the <code>zig-book</code> folder, then, it goes to the <code>ZigExamples</code> folder, then, into <code>zig-basics</code>, then, to the <code>hello.zig</code> file.</p>
+<p>A relative path is a path that start at the CWD. In other words, a relative path is “relative to the CWD”. The path used to access the <code>hello.zig</code> file in <a href="#fig-cwd" class="quarto-xref">Figure&nbsp;<span>13.3</span></a> is an example of a relative path. This path is reproduced below. This path begins at the CWD, which in the context of <a href="#fig-cwd" class="quarto-xref">Figure&nbsp;<span>13.3</span></a>, is the <code>zig-book</code> folder, then, it goes to the <code>ZigExamples</code> folder, then, into <code>zig-basics</code>, then, to the <code>hello.zig</code> file.</p>
 <pre><code>ZigExamples/zig-basics/hello_world.zig</code></pre>
 </section>
 <section id="path-wildcards" class="level3" data-number="13.3.3">
@@ -614,7 +614,7 @@ <h2 data-number="13.5" class="anchored" data-anchor-id="file-operations"><span c
 <section id="sec-creating-files" class="level3" data-number="13.5.1">
 <h3 data-number="13.5.1" class="anchored" data-anchor-id="sec-creating-files"><span class="header-section-number">13.5.1</span> Creating files</h3>
 <p>We create new files by using the <code>createFile()</code> method from the <code>Dir</code> object. Just provide the name of the file that you want to create, and this function will do the necessary steps to create such file. You can also provide a relative path to this function, and it will create the file by following this path, which is relative to the CWD.</p>
-<p>This function might return an error, so, you should use <code>try</code>, <code>catch</code>, or any of the other methods presented at <a href="09-error-handling.html" class="quarto-xref"><span>Chapter 10</span></a> to handle the possible error. But if everything goes well, this <code>createFile()</code> method returns a file descriptor object (i.e.&nbsp;a <code>File</code> object) as result, through which you can add content to the file with the IO operations that I presented before.</p>
+<p>This function might return an error, so, you should use <code>try</code>, <code>catch</code>, or any of the other methods presented in <a href="09-error-handling.html" class="quarto-xref"><span>Chapter 10</span></a> to handle the possible error. But if everything goes well, this <code>createFile()</code> method returns a file descriptor object (i.e., a <code>File</code> object) as result, through which you can add content to the file with the IO operations that I presented before.</p>
 <p>Take this code example below. In this example, we are creating a new text file named <code>foo.txt</code>. If the function <code>createFile()</code> succeeds, the object named <code>file</code> will contain a file descriptor object, which we can use to write (or add) new content to the file, like we do in this example, by using a buffered writer object to write a new line of text to the file.</p>
 <p>Now, a quick note, when we create a file descriptor object in C, by using a C function like <code>fopen()</code>, we must always close the file at the end of our program, or, as soon as we complete all operations that we wanted to perform on the file. In Zig, this is no different. So everytime we create a new file, this file remains “open”, waiting for some operation to be performed. As soon as we are done with it, we always have to close this file, to free the resources associated with it. In Zig, we do this by calling the method <code>close()</code> from the file descriptor object.</p>
 <div class="cell">
@@ -629,9 +629,9 @@ <h3 data-number="13.5.1" class="anchored" data-anchor-id="sec-creating-files"><s
 <span id="cb9-9"><a href="#cb9-9" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>So, in this example we not only have created a file into the filesystem, but we also wrote some data into this file, using the file descriptor object returned by <code>createFile()</code>. If the file that you are trying to create already exists in your filesystem, this <code>createFile()</code> call will overwrite the contents of the file, or, in other words, it will in erase all the contents of the existing file.</p>
-<p>If you don’t want this to happen, meaning, that you don’t want to overwrite the contents of the existing file, but you want to write data to this file anyway (i.e.&nbsp;you want to append data to the file), you should use the <code>openFile()</code> method from the <code>Dir</code> object.</p>
+<p>If you don’t want this to happen, meaning, that you don’t want to overwrite the contents of the existing file, but you want to write data to this file anyway (i.e., you want to append data to the file), you should use the <code>openFile()</code> method from the <code>Dir</code> object.</p>
 <p>Another important aspect about <code>createFile()</code> is that this method creates a file that is not open to read operations by default. It means that you cannot read this file. You are not allowed to. So for example, you might want to write some stuff into this file at the beginning of the execution of your program. Then, at a future point in your program you might need to read what you wrote in this file. If you try to read data from this file, you will likely get a <code>NotOpenForReading</code> error as result.</p>
-<p>But how can you overcome this barrier? How can you create a file that is open to read operations? All you have to do, is to set the <code>read</code> flag to true in the second argument of <code>createFile()</code>. When you set this flag to true, then the file get’s create with “read permissions”, and, as consequence, a program like this one below becomes valid:</p>
+<p>But how can you overcome this barrier? How can you create a file that is open to read operations? All you have to do, is to set the <code>read</code> flag to true in the second argument of <code>createFile()</code>. When you set this flag to true, then the file gets create with “read permissions”, and, as consequence, a program like this one below becomes valid:</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb10"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> cwd = std.fs.cwd();</span>
 <span id="cb10-2"><a href="#cb10-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> file = <span class="kw">try</span> cwd.createFile(</span>
@@ -651,18 +651,18 @@ <h3 data-number="13.5.1" class="anchored" data-anchor-id="sec-creating-files"><s
 <span id="cb10-16"><a href="#cb10-16" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{s}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>buffer<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>We are going to read this line</code></pre>
-<p>If you are not familiar with position indicators, you might not recognize the method <code>seekTo()</code>. If that is your case, do not worry, we are going to talk more about this method at <a href="#sec-indicators" class="quarto-xref"><span>Section 13.6</span></a>. But essentially this method is moving the position indicator back to the beginning of the file, so that we can read the contents of the file from the beginning.</p>
+<p>If you are not familiar with position indicators, you might not recognize the method <code>seekTo()</code>. If that is your case, do not worry, we are going to talk more about this method in <a href="#sec-indicators" class="quarto-xref"><span>Section 13.6</span></a>. But essentially this method is moving the position indicator back to the beginning of the file, so that we can read the contents of the file from the beginning.</p>
 </section>
 <section id="opening-files-and-appending-data-to-it" class="level3" data-number="13.5.2">
 <h3 data-number="13.5.2" class="anchored" data-anchor-id="opening-files-and-appending-data-to-it"><span class="header-section-number">13.5.2</span> Opening files and appending data to it</h3>
 <p>Opening files is easy. Just use the <code>openFile()</code> method instead of <code>createFile()</code>. In the first argument of <code>openFile()</code> you provide the path to the file that you want to open. Then, on the second argument you provide the flags (or, the options) that dictates how the file is opened.</p>
-<p>You can see the full list of options for <code>openFile()</code> by visiting the documentation for <a href="https://ziglang.org/documentation/master/std/#std.fs.File.OpenFlags"><code>OpenFlags</code></a><a href="#fn9" class="footnote-ref" id="fnref9" role="doc-noteref"><sup>9</sup></a>. But the main flag that you will most certainly use is the <code>mode</code> flag. This flag specifies the IO mode that the file will be using when it get’s opened. There are three IO modes, or, three values that you can provide to this flag, which are:</p>
+<p>You can see the full list of options for <code>openFile()</code> by visiting the documentation for <a href="https://ziglang.org/documentation/master/std/#std.fs.File.OpenFlags"><code>OpenFlags</code></a><a href="#fn9" class="footnote-ref" id="fnref9" role="doc-noteref"><sup>9</sup></a>. But the main flag that you will most certainly use is the <code>mode</code> flag. This flag specifies the IO mode that the file will be using when it gets opened. There are three IO modes, or, three values that you can provide to this flag, which are:</p>
 <ul>
 <li><code>read_only</code>, allows only read operations on the file. All write operations are blocked.</li>
 <li><code>write_only</code>, allows only write operations on the file. All read operations are blocked.</li>
 <li><code>read_write</code>, allows both write and read operations on the file.</li>
 </ul>
-<p>These modes are similar to the modes that you provide to the <code>mode</code> argument of the <code>open()</code> Python built-in function<a href="#fn10" class="footnote-ref" id="fnref10" role="doc-noteref"><sup>10</sup></a>, or, the <code>mode</code> argument of the <code>fopen()</code> C function<a href="#fn11" class="footnote-ref" id="fnref11" role="doc-noteref"><sup>11</sup></a>. In the code example below, we are opening the <code>foo.txt</code> text file with a <code>write_only</code> mode, and appending a new line of text to the end of the file. We use <code>seekFromEnd()</code> this time to guarantee that we are going to append the text to the end of the file. Once again, methods such as <code>seekFromEnd()</code> are described in more depth at <a href="#sec-indicators" class="quarto-xref"><span>Section 13.6</span></a>.</p>
+<p>These modes are similar to the modes that you provide to the <code>mode</code> argument of the <code>open()</code> Python built-in function<a href="#fn10" class="footnote-ref" id="fnref10" role="doc-noteref"><sup>10</sup></a>, or, the <code>mode</code> argument of the <code>fopen()</code> C function<a href="#fn11" class="footnote-ref" id="fnref11" role="doc-noteref"><sup>11</sup></a>. In the code example below, we are opening the <code>foo.txt</code> text file with a <code>write_only</code> mode, and appending a new line of text to the end of the file. We use <code>seekFromEnd()</code> this time to guarantee that we are going to append the text to the end of the file. Once again, methods such as <code>seekFromEnd()</code> are described in more depth in <a href="#sec-indicators" class="quarto-xref"><span>Section 13.6</span></a>.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb12"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> cwd = std.fs.cwd();</span>
 <span id="cb12-2"><a href="#cb12-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> file = <span class="kw">try</span> cwd.openFile(</span>
@@ -684,7 +684,7 @@ <h3 data-number="13.5.3" class="anchored" data-anchor-id="deleting-files"><span
 </section>
 <section id="copying-files" class="level3" data-number="13.5.4">
 <h3 data-number="13.5.4" class="anchored" data-anchor-id="copying-files"><span class="header-section-number">13.5.4</span> Copying files</h3>
-<p>To copy existing files, we use the <code>copyFile()</code> method. The first argument in this method is the path to the file that you want to copy. The second argument is a <code>Dir</code> object, i.e.&nbsp;a directory handler, more specifically, a <code>Dir</code> object that points to the folder in your computer where you want to copy the file to. The third argument is the new path of the file, or, in other words, the new location of the file. The fourth argument is the options (or flags) to be used in the copy operation.</p>
+<p>To copy existing files, we use the <code>copyFile()</code> method. The first argument in this method is the path to the file that you want to copy. The second argument is a <code>Dir</code> object, i.e., a directory handler, more specifically, a <code>Dir</code> object that points to the folder in your computer where you want to copy the file to. The third argument is the new path of the file, or, in other words, the new location of the file. The fourth argument is the options (or flags) to be used in the copy operation.</p>
 <p>The <code>Dir</code> object that you provide as input to this method will be used to copy the file to the new location. You may create this <code>Dir</code> object before calling the <code>copyFile()</code> method. Maybe you are planning to copy the file to a completely different location in your computer, so it might be worth to create a directory handler to that location. But if you are copying the file to a subfolder of your CWD, then, you can just simply pass the CWD handler to this argument.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb14"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> cwd = std.fs.cwd();</span>
@@ -705,7 +705,7 @@ <h3 data-number="13.5.5" class="anchored" data-anchor-id="read-the-docs"><span c
 <h2 data-number="13.6" class="anchored" data-anchor-id="sec-indicators"><span class="header-section-number">13.6</span> Position indicators</h2>
 <p>A position indicator is like a type of cursor, or, an index. This “index” identifies the current location in the file (or, in the data stream) that the file descriptor object that you have is currently looking at. When you create a file descriptor, the position indicator starts at the beginning of the file, or, at the beginning of the stream. When you read from or write into the file (or socket, or data stream, etc.) described by this file descriptor object, you end up moving the position indicator.</p>
 <p>In other words, any IO operation have a common side effect, which is to move the position indicator. For example, suppose that we have a file of 300 bytes total in size. If you read 100 bytes from the file, then, the position indicator moves 100 bytes forward. If you try to write 50 bytes into this same file, these 50 bytes will be written from the current position indicated by the position indicator. Since the indicator is at a 100 bytes forward from the beginning of the file, these 50 bytes would be written in the middle of the file.</p>
-<p>This is why we have used the <code>seekTo()</code> method at the last code example presented at <a href="#sec-creating-files" class="quarto-xref"><span>Section 13.5.1</span></a>. We have used this method to move the position indicator back to the beginning of the file, which would make sure that we would write the text that we wanted to write from the beginning of the file, instead of writing it from the middle of the file. Because before the write operation, we had performed a read operation, which means that the position indicator was moved in this read operation.</p>
+<p>This is why we have used the <code>seekTo()</code> method at the last code example presented in <a href="#sec-creating-files" class="quarto-xref"><span>Section 13.5.1</span></a>. We have used this method to move the position indicator back to the beginning of the file, which would make sure that we would write the text that we wanted to write from the beginning of the file, instead of writing it from the middle of the file. Because before the write operation, we had performed a read operation, which means that the position indicator was moved in this read operation.</p>
 <p>The position indicators of a file descriptor object can be changed (or altered) by using the “seek” methods from this file descriptor, which are: <code>seekTo()</code>, <code>seekFromEnd()</code> and <code>seekBy()</code>. These methods have the same effect, or, the same responsibility that the <a href="https://en.cppreference.com/w/c/io/fseek"><code>fseek()</code></a><a href="#fn13" class="footnote-ref" id="fnref13" role="doc-noteref"><sup>13</sup></a> C function.</p>
 <p>Considering that <code>offset</code> refers to the index that you provide as input to these “seek” methods, the bullet points below summarises what is the effect of each of these methods. As a quick note, in the case of <code>seekFromEnd()</code> and <code>seekBy()</code>, the <code>offset</code> provided can be either a positive or a negative index.</p>
 <ul>
@@ -781,7 +781,7 @@ <h2 data-number="13.8" class="anchored" data-anchor-id="conclusion"><span class=
 <hr>
 <ol>
 <li id="fn1"><p>Previously, these objects were known as the <code>Reader</code> and <code>Writer</code> objects.<a href="#fnref1" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn2"><p>The socket objects that we have created at <a href="04-http-server.html#sec-create-socket" class="quarto-xref"><span>Section 7.4.1</span></a>, are examples of network sockets.<a href="#fnref2" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn2"><p>The socket objects that we have created in <a href="04-http-server.html#sec-create-socket" class="quarto-xref"><span>Section 7.4.1</span></a>, are examples of network sockets.<a href="#fnref2" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
 <li id="fn3"><p><a href="https://ziglang.org/documentation/master/std/#std.io.GenericWriter" class="uri">https://ziglang.org/documentation/master/std/#std.io.GenericWriter</a>.<a href="#fnref3" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
 <li id="fn4"><p><a href="https://ziglang.org/documentation/master/std/#std.io.GenericReader" class="uri">https://ziglang.org/documentation/master/std/#std.io.GenericReader</a>.<a href="#fnref4" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
 <li id="fn5"><p><a href="https://github.com/ziglang/zig/blob/master/lib/std/io/Reader.zig" class="uri">https://github.com/ziglang/zig/blob/master/lib/std/io/Reader.zig</a>.<a href="#fnref5" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
diff --git a/docs/Chapters/13-image-filter.html b/docs/Chapters/13-image-filter.html
index 58efbfaa..8c893a3c 100644
--- a/docs/Chapters/13-image-filter.html
+++ b/docs/Chapters/13-image-filter.html
@@ -370,7 +370,7 @@ <h1 class="title"><span class="chapter-number">15</span>&nbsp; <span class="chap
 
 
 <p>In this chapter we are going to build a new project. The objective of this project is to write a program that applies a filter over an image. More specifically, a “grayscale filter”, which transforms any color image into a grayscale image.</p>
-<p>We are going to use the image displayed at <a href="#fig-pascal" class="quarto-xref">Figure&nbsp;<span>15.1</span></a> in this project. In other words, we want to transform this colored image into a grayscale image, by using our “image filter program” written in Zig.</p>
+<p>We are going to use the image displayed in <a href="#fig-pascal" class="quarto-xref">Figure&nbsp;<span>15.1</span></a> in this project. In other words, we want to transform this colored image into a grayscale image, by using our “image filter program” written in Zig.</p>
 <div id="fig-pascal" class="quarto-float quarto-figure quarto-figure-center anchored">
 <figure class="quarto-float quarto-float-fig figure">
 <div aria-describedby="fig-pascal-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
@@ -382,7 +382,7 @@ <h1 class="title"><span class="chapter-number">15</span>&nbsp; <span class="chap
 </figure>
 </div>
 <p>We don’t need to write a lot of code to build such “image filter program”. However, we first need to understand how digital images work. That is why we begin this chapter by explaining the theory behind digital images and how colors are represented in modern computers. We also give a brief explanation about the PNG (Portable Network Graphics) file format, which is the format used in the example images.</p>
-<p>At the end of this chapter, we should have a full example of a program that takes the PNG image displayed at <a href="#fig-pascal" class="quarto-xref">Figure&nbsp;<span>15.1</span></a> as input, and writes a new image to the current working directory that is the grayscale version of this input image. This grayscale version of <a href="#fig-pascal" class="quarto-xref">Figure&nbsp;<span>15.1</span></a> is exposed at <a href="#fig-pascal-gray" class="quarto-xref">Figure&nbsp;<span>15.2</span></a>. You can find the full source code of this small project at the <code>ZigExamples/image_filter</code> <a href="https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter">folder at the official repository of this book</a><a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>.</p>
+<p>At the end of this chapter, we should have a full example of a program that takes the PNG image displayed in <a href="#fig-pascal" class="quarto-xref">Figure&nbsp;<span>15.1</span></a> as input, and writes a new image to the current working directory that is the grayscale version of this input image. This grayscale version of <a href="#fig-pascal" class="quarto-xref">Figure&nbsp;<span>15.1</span></a> is exposed in <a href="#fig-pascal-gray" class="quarto-xref">Figure&nbsp;<span>15.2</span></a>. You can find the full source code of this small project at the <code>ZigExamples/image_filter</code> <a href="https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter">folder at the official repository of this book</a><a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>.</p>
 <div id="fig-pascal-gray" class="quarto-float quarto-figure quarto-figure-center anchored">
 <figure class="quarto-float quarto-float-fig figure">
 <div aria-describedby="fig-pascal-gray-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
@@ -429,9 +429,9 @@ <h2 data-number="15.2" class="anchored" data-anchor-id="sec-digital-img"><span c
 <p>Most digital images we see in our modern world uses the RGB color model. RGB stands for (red, green and blue). So the color of each pixel in these raster images are usually represented as a mixture of red, green and blue, just like in our eyes. That is, the color of each pixel is identified by a set of three different integer values. Each integer value identifies the “amount” of each color (red, green and blue). For example, the set <code>(199, 78, 70)</code> identifies a color that is more close to red. We have 199 of red, 78 of green, and 70 of blue. In contrast, the set <code>(129, 77, 250)</code> describes a color that is more close to purple. Et cetera.</p>
 <section id="images-are-displayed-from-top-to-bottom" class="level3" data-number="15.2.1">
 <h3 data-number="15.2.1" class="anchored" data-anchor-id="images-are-displayed-from-top-to-bottom"><span class="header-section-number">15.2.1</span> Images are displayed from top to bottom</h3>
-<p>This is not a rule written in stone, but the big majority of digital images are displayed from top to bottom and left to right. Most computers screens also follow this pattern. So, the first pixels in the image are the ones that are at the top and left corner of the image. You can find a visual representation of this logic at <a href="#fig-img-display" class="quarto-xref">Figure&nbsp;<span>15.4</span></a>.</p>
+<p>This is not a rule written in stone, but the big majority of digital images are displayed from top to bottom and left to right. Most computers screens also follow this pattern. So, the first pixels in the image are the ones that are at the top and left corner of the image. You can find a visual representation of this logic in <a href="#fig-img-display" class="quarto-xref">Figure&nbsp;<span>15.4</span></a>.</p>
 <p>Also notice in <a href="#fig-img-display" class="quarto-xref">Figure&nbsp;<span>15.4</span></a> that, because a raster image is essentially a 2D matrix of pixels, the image is organized into rows and columns of pixels. The columns are defined by the horizontal x axis, while the rows are defined by the vertical y axis.</p>
-<p>Each pixel (i.e.&nbsp;the gray rectangles) exposed at <a href="#fig-img-display" class="quarto-xref">Figure&nbsp;<span>15.4</span></a> contains a number inside of it. These numbers are the indexes of the pixels. You can notice that the first pixels are in the top and left corner, and also, that the indexes of these pixels “grow to the sides”, or, in other words, they grow in the direction of the horizontal x axis. Most raster images are organized as rows of pixels. Thus, when these digital images are displayed, the screen display the first row of pixels, then, the second row, then, the third row, etc.</p>
+<p>Each pixel (i.e., the gray rectangles) exposed in <a href="#fig-img-display" class="quarto-xref">Figure&nbsp;<span>15.4</span></a> contains a number inside of it. These numbers are the indexes of the pixels. You can notice that the first pixels are in the top and left corner, and also, that the indexes of these pixels “grow to the sides”, or, in other words, they grow in the direction of the horizontal x axis. Most raster images are organized as rows of pixels. Thus, when these digital images are displayed, the screen display the first row of pixels, then, the second row, then, the third row, etc.</p>
 <div id="fig-img-display" class="quarto-float quarto-figure quarto-figure-center anchored">
 <figure class="quarto-float quarto-float-fig figure">
 <div aria-describedby="fig-img-display-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
@@ -447,7 +447,7 @@ <h3 data-number="15.2.1" class="anchored" data-anchor-id="images-are-displayed-f
 <h3 data-number="15.2.2" class="anchored" data-anchor-id="sec-pixel-repr"><span class="header-section-number">15.2.2</span> Representing the matrix of pixels in code</h3>
 <p>Ok, we know already that raster images are represented as 2D matrices of pixels. But we do not have a notion of a 2D matrix in Zig. Actually, most low-level languages in general (Zig, C, Rust, etc.) do not have such notion. So how can we represent such matrix of pixels in Zig, or any other low-level language? The strategy that most programmers choose in this situation is to just use a normal 1D array to store the values of this 2D matrix. In other words, you just create an normal 1D array, and store all values from both dimensions into this 1D array.</p>
 <p>As an example, suppose we have a very small image of dimensions 4x3. Since a raster image is represented as a 2D matrix of pixels, and each pixel is represented by 3 “unsigned 8-bit” integer values, we have 12 pixels in total in this image, which are represented by <span class="math inline">\(3 \times 12 = 36\)</span> integer values. Therefore, we need to create an array of 36 <code>u8</code> values to store this small image.</p>
-<p>The reason why unsigned 8-bit integer (<code>u8</code>) values are used to represent the amounts of each color, instead of any other integer type, is because they take the minimum amount of space as possible, or, the minimum amount of bits as possible. Which helps to reduces the binary size of the image, i.e.&nbsp;the 2D matrix. Also, they convey a good amount of precision and detail about the colors, even though they can represent a relatively small range (from 0 to 255) of “color amounts”.</p>
+<p>The reason why unsigned 8-bit integer (<code>u8</code>) values are used to represent the amounts of each color, instead of any other integer type, is because they take the minimum amount of space as possible, or, the minimum amount of bits as possible. Which helps to reduces the binary size of the image, i.e., the 2D matrix. Also, they convey a good amount of precision and detail about the colors, even though they can represent a relatively small range (from 0 to 255) of “color amounts”.</p>
 <p>Coming back to our initial example of a 4x3 image, the <code>matrix</code> object exposed below could be an example of an 1D array that stores the data that represents this 4x3 image.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb1"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> matrix = [_]<span class="dt">u8</span><span class="op">{</span></span>
@@ -467,16 +467,16 @@ <h3 data-number="15.2.2" class="anchored" data-anchor-id="sec-pixel-repr"><span
 </section>
 <section id="the-png-library-that-we-are-going-to-use" class="level2" data-number="15.3">
 <h2 data-number="15.3" class="anchored" data-anchor-id="the-png-library-that-we-are-going-to-use"><span class="header-section-number">15.3</span> The PNG library that we are going to use</h2>
-<p>Let’s begin our project by focusing on writing the necessary Zig code to read the data from the PNG file. In other words, we want to read the PNG file exposed at <a href="#fig-pascal" class="quarto-xref">Figure&nbsp;<span>15.1</span></a>, and parse its data to extract the 2D matrix of pixels that represents the image.</p>
-<p>As we have discussed at <a href="#sec-pixel-repr" class="quarto-xref"><span>Section 15.2.2</span></a>, the image that we are using as example here is a PNG file that uses the RGBA color model, and, therefore, each pixel of the image is represented by 4 integer values. You can download this image by visiting the <code>ZigExamples/image_filter</code> <a href="https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter">folder at the official repository of this book</a><a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a>. You can also find in this folder the complete source code of this small project that we are developing here.</p>
-<p>There are some C libraries available that we can use to read and parse PNG files. The most famous and used of all is <code>libpng</code>, which is the “official library” for reading and writing PNG files. Although this library is available on most operating system, it is well known for being complex and hard to use.</p>
-<p>That is why, I’m going to use a more modern alternative here in this project, which is the <code>libspng</code> library. I choose to use this C library here, because it is much, much simpler to use than <code>libpng</code>, and it also offers very good performance for all operations. You can checkout the <a href="https://libspng.org/">official website of the library</a><a href="#fn4" class="footnote-ref" id="fnref4" role="doc-noteref"><sup>4</sup></a> to know more about it. You will also find there some documentation that might help you to understand and follow the code examples exposed here.</p>
+<p>Let’s begin our project by focusing on writing the necessary Zig code to read the data from the PNG file. In other words, we want to read the PNG file exposed in <a href="#fig-pascal" class="quarto-xref">Figure&nbsp;<span>15.1</span></a>, and parse its data to extract the 2D matrix of pixels that represents the image.</p>
+<p>As we have discussed in <a href="#sec-pixel-repr" class="quarto-xref"><span>Section 15.2.2</span></a>, the image that we are using as example here is a PNG file that uses the RGBA color model, and, therefore, each pixel of the image is represented by 4 integer values. You can download this image by visiting the <code>ZigExamples/image_filter</code> <a href="https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter">folder at the official repository of this book</a><a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a>. You can also find in this folder the complete source code of this small project that we are developing here.</p>
+<p>There are some C libraries available that we can use to read and parse PNG files. The most famous and used of all is <code>libpng</code>, which is the “official library” for reading and writing PNG files. Although this library is available on most operating system, it’s well known for being complex and hard to use.</p>
+<p>That is why, I’m going to use a more modern alternative here in this project, which is the <code>libspng</code> library. I choose to use this C library here, because it’s much, much simpler to use than <code>libpng</code>, and it also offers very good performance for all operations. You can checkout the <a href="https://libspng.org/">official website of the library</a><a href="#fn4" class="footnote-ref" id="fnref4" role="doc-noteref"><sup>4</sup></a> to know more about it. You will also find there some documentation that might help you to understand and follow the code examples exposed here.</p>
 <p>First of all, remember to build and install this <code>libspng</code> into your system. Because if you don’t do this step, the <code>zig</code> compiler will not be able to find the files and resources of this library in your computer, and link them with the Zig source code that we are writing together here. There is good information about how to build and install the library at the <a href="https://libspng.org/docs/build/">build section of the library documentation</a><a href="#fn5" class="footnote-ref" id="fnref5" role="doc-noteref"><sup>5</sup></a>.</p>
 </section>
 <section id="reading-the-png-file" class="level2" data-number="15.4">
 <h2 data-number="15.4" class="anchored" data-anchor-id="reading-the-png-file"><span class="header-section-number">15.4</span> Reading the PNG file</h2>
 <p>In order to extract the pixel data from the PNG file, we need to read and decode the file. A PNG file is just a binary file written in the “PNG format”. Luckily, the <code>libspng</code> library offers a function called <code>spng_decode_image()</code> that does all this heavy work for us.</p>
-<p>Now, since <code>libspng</code> is a C library, most of the file and I/O operations in this library are made by using a <code>FILE</code> C pointer. Because of that, is probably a better idea to use the <code>fopen()</code> C function to open our PNG file, instead of using the <code>openFile()</code> method that I introduced at <a href="12-file-op.html" class="quarto-xref"><span>Chapter 13</span></a>. That is why I’m importing the <code>stdio.h</code> C header in this project, and using the <code>fopen()</code> C function to open the file.</p>
+<p>Now, since <code>libspng</code> is a C library, most of the file and I/O operations in this library are made by using a <code>FILE</code> C pointer. Because of that, is probably a better idea to use the <code>fopen()</code> C function to open our PNG file, instead of using the <code>openFile()</code> method that I introduced in <a href="12-file-op.html" class="quarto-xref"><span>Chapter 13</span></a>. That is why I’m importing the <code>stdio.h</code> C header in this project, and using the <code>fopen()</code> C function to open the file.</p>
 <p>If you look at the snippet below, you can see that we are:</p>
 <ol type="1">
 <li>opening the PNG file with <code>fopen()</code>.</li>
@@ -511,7 +511,7 @@ <h2 data-number="15.4" class="anchored" data-anchor-id="reading-the-png-file"><s
 <h3 data-number="15.4.1" class="anchored" data-anchor-id="reading-the-image-header-section"><span class="header-section-number">15.4.1</span> Reading the image header section</h3>
 <p>Now, the context object <code>ctx</code> is aware of our PNG file <code>pedro_pascal.png</code>, because it has access to a file descriptor object to this file. The first thing that we are going to do is to read the “image header section” of the PNG file. This “image header section” is the section of the file that contains some basic information about the PNG file, like, the bit depth of the pixel data of the image, the color model used in the file, the dimensions of the image (height and width in number of pixels), etc.</p>
 <p>To make things easier, I will encapsulate this “read image header” operation into a nice and small function called <code>get_image_header()</code>. All that this function needs to do is to call the <code>spng_get_ihdr()</code> function. This function from <code>libspng</code> is responsible for reading the image header data, and storing it into a C struct named <code>spng_ihdr</code>. Thus, an object of type <code>spng_ihdr</code> is a C struct that contains the data from the image header section of the PNG file.</p>
-<p>Since this Zig function is receiving a C object (the <code>libspng</code> context object) as input, I marked the function argument <code>ctx</code> as “a pointer to the context object” (<code>*c.spng_ctx</code>), following the recommendations that we have discussed at <a href="14-zig-c-interop.html#sec-pass-c-structs" class="quarto-xref"><span>Section 14.5</span></a>.</p>
+<p>Since this Zig function is receiving a C object (the <code>libspng</code> context object) as input, I marked the function argument <code>ctx</code> as “a pointer to the context object” (<code>*c.spng_ctx</code>), following the recommendations that we have discussed in <a href="14-zig-c-interop.html#sec-pass-c-structs" class="quarto-xref"><span>Section 14.5</span></a>.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb4"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> get_image_header(ctx: *c.spng_ctx) !c.spng_ihdr <span class="op">{</span></span>
 <span id="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> image_header: c.spng_ihdr = <span class="cn">undefined</span>;</span>
@@ -579,7 +579,7 @@ <h3 data-number="15.4.4" class="anchored" data-anchor-id="looking-at-the-pixel-d
 <p>Now that we have the pixel data stored in our “buffer object”, we can take a quick look at the bytes. In the example below, we are looking at the first 12 bytes in the decoded pixel data.</p>
 <p>If you take a close look at these values, you might notice that every 4 bytes in the sequence is 255. Which, coincidentally is the maximum possible integer value to be represented by a <code>u8</code> value. So, if the range from 0 to 255, which is the range of integer values that can be represented by an <code>u8</code> value, can be represented as a scale from 0% to 100%, these 255 values are essentially 100% in that scale.</p>
 <p>If you recall from <a href="#sec-pixel-repr" class="quarto-xref"><span>Section 15.2.2</span></a>, I have described in that section that our <code>pedro_pascal.png</code> PNG file uses the RGBA color model, which adds an alpha (or transparency) byte to each pixel in the image. As consequence, each pixel in the image is represented by 4 bytes. Since we are looking here are the first 12 bytes in the image, it means that we are looking at the data from the first <span class="math inline">\(12 / 4 = 3\)</span> pixels in the image.</p>
-<p>So, based on how these first 12 bytes (or these 3 pixels) look, with these 255 values at every 4 bytes, we can say that is likely that every pixel in the image have alpha (or transparency) setted to 100%. This might not be true, but, is the most likely possibility. Also, if we look at the image itself, which if your recall is exposed at <a href="#fig-pascal" class="quarto-xref">Figure&nbsp;<span>15.1</span></a>, we can see that the transparency does not change across the image, which enforces this theory.</p>
+<p>So, based on how these first 12 bytes (or these 3 pixels) look, with these 255 values at every 4 bytes, we can say that is likely that every pixel in the image have alpha (or transparency) setted to 100%. This might not be true, but, is the most likely possibility. Also, if we look at the image itself, which if your recall is exposed in <a href="#fig-pascal" class="quarto-xref">Figure&nbsp;<span>15.1</span></a>, we can see that the transparency does not change across the image, which enforces this theory.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb9"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb9-1"><a href="#cb9-1" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{any}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>buffer[<span class="dv">0</span>..<span class="dv">12</span>]<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
@@ -597,7 +597,7 @@ <h2 data-number="15.5" class="anchored" data-anchor-id="applying-the-image-filte
 <p><span id="eq-grayscale"><span class="math display">\[
     p' = (0.2126 \times r) + (0.7152 \times g) + (0.0722 \times b)
 \tag{15.1}\]</span></span></p>
-<p>This <a href="#eq-grayscale" class="quarto-xref">Equation&nbsp;<span>15.1</span></a> is the formula to calculate the linear luminance of a pixel. Is worth noting that this formula works only for images whose pixels are using the sRGB color space, which is the standard color space for the web. Thus, ideally, all images on the web should use this color space. Luckily, this is our case here, i.e.&nbsp;the <code>pedro_pascal.png</code> image is using this sRGB color space, and, as consequence, we can use the <a href="#eq-grayscale" class="quarto-xref">Equation&nbsp;<span>15.1</span></a>. You can read more about this formula at the Wikipedia page for grayscale <span class="citation" data-cites="wiki_grayscale">(<a href="../references.html#ref-wiki_grayscale" role="doc-biblioref">Wikipedia 2024</a>)</span>.</p>
+<p>This <a href="#eq-grayscale" class="quarto-xref">Equation&nbsp;<span>15.1</span></a> is the formula to calculate the linear luminance of a pixel. It’s worth noting that this formula works only for images whose pixels are using the sRGB color space, which is the standard color space for the web. Thus, ideally, all images on the web should use this color space. Luckily, this is our case here, i.e., the <code>pedro_pascal.png</code> image is using this sRGB color space, and, as consequence, we can use the <a href="#eq-grayscale" class="quarto-xref">Equation&nbsp;<span>15.1</span></a>. You can read more about this formula at the Wikipedia page for grayscale <span class="citation" data-cites="wiki_grayscale">(<a href="../references.html#ref-wiki_grayscale" role="doc-biblioref">Wikipedia 2024</a>)</span>.</p>
 <p>The <code>apply_image_filter()</code> function exposed below summarises the necessary steps to apply <a href="#eq-grayscale" class="quarto-xref">Equation&nbsp;<span>15.1</span></a> over the pixels in the image. We just apply this function over our buffer object that contains our pixel data, and, as result, the pixel data stored in this buffer object should now represent the grayscale version of our image.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb11"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> apply_image_filter(buffer:[]<span class="dt">u8</span>) !<span class="dt">void</span> <span class="op">{</span></span>
@@ -663,7 +663,7 @@ <h2 data-number="15.6" class="anchored" data-anchor-id="saving-the-grayscale-ver
 <span id="cb12-29"><a href="#cb12-29" aria-hidden="true" tabindex="-1"></a></span>
 <span id="cb12-30"><a href="#cb12-30" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> save_png(&amp;image_header, buffer[<span class="dv">0</span>..]);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>After we execute this <code>save_png()</code> function, we should have a new PNG file inside our CWD, named <code>pedro_pascal_filter.png</code>. If we open this PNG file, we will see the same image exposed at <a href="#fig-pascal-gray" class="quarto-xref">Figure&nbsp;<span>15.2</span></a>.</p>
+<p>After we execute this <code>save_png()</code> function, we should have a new PNG file inside our CWD, named <code>pedro_pascal_filter.png</code>. If we open this PNG file, we will see the same image exposed in <a href="#fig-pascal-gray" class="quarto-xref">Figure&nbsp;<span>15.2</span></a>.</p>
 </section>
 <section id="building-our-project" class="level2" data-number="15.7">
 <h2 data-number="15.7" class="anchored" data-anchor-id="building-our-project"><span class="header-section-number">15.7</span> Building our project</h2>
diff --git a/docs/Chapters/14-threads.html b/docs/Chapters/14-threads.html
index 9dac90fb..6bfb842d 100644
--- a/docs/Chapters/14-threads.html
+++ b/docs/Chapters/14-threads.html
@@ -385,10 +385,10 @@ <h1 class="title"><span id="sec-thread" class="quarto-section-identifier"><span
 <h2 data-number="16.1" class="anchored" data-anchor-id="sec-what-thread"><span class="header-section-number">16.1</span> What are threads?</h2>
 <p>A thread is basically a separate context of execution. We use threads to introduce parallelism into our program, which in most cases, makes the program run faster, because we have multiple tasks being performed at the same time, parallel to each other.</p>
 <p>Programs are normally single-threaded by default. Which means that each program usually runs on a single thread, or, a single context of execution. When we have only one thread running, we have no parallelism. And when we don’t have parallelism, the commands are executed sequentially, that is, only one command is executed at a time, one after another. By creating multiple threads inside our program, we start to execute multiple commands at the same time.</p>
-<p>Programs that create multiple threads are very common on the wild. Because many different types of applications are well suited for parallelism. Good examples are video and photo-editing applications (e.g.&nbsp;Adobe Photoshop or DaVinci Resolve), games (e.g.&nbsp;The Witcher 3), and also web browsers (e.g.&nbsp;Google Chrome, Firefox, Microsoft Edge, etc). For example, in web browsers, threads are normally used to implement tabs. The tabs in a web browsers usually run as separate threads in the main process of the web browser. That is, each new tab that you open in your web browser, usually runs on a separate thread of execution.</p>
-<p>By running each tab in a separate thread, we allow all open tabs in the browser to run at the same time, and independently from each other. For example, you might have YouTube, or Spotify, currently opened in a tab, and you are listening to some podcast in that tab, while, at the same time, you are working in another tab, writing an essay on Google Docs. Even if you are not looking into the YouTube tab, you can still hear the podcast only because this YouTube tab is running in parallel with the other tab where Google Docs is running.</p>
-<p>Without threads, the other alternative would be to run each tab as a completely separate process in your computer. But that would be a bad choice, because just a few tabs would already consume too much power and resources from your computer. In other words, is very expensive to create a completely new process, compared to creating a new thread of execution. Also, the chances of you experiencing lag and overhead while using the browser would be significant. Threads are faster to create, and they also consume much, much less resources from the computer, especially because they share some resources with the main process.</p>
-<p>Therefore, is the use of threads in modern web browsers that allows you to hear the podcast at the same time while you are writing something on Google Docs. Without threads, a web browser would probably be limited to just one single tab.</p>
+<p>Programs that create multiple threads are very common in the wild. Because many different types of applications are well suited for parallelism. Good examples are video and photo-editing applications (e.g.&nbsp;Adobe Photoshop or DaVinci Resolve), games (e.g.&nbsp;The Witcher 3), and also web browsers (e.g.&nbsp;Google Chrome, Firefox, Microsoft Edge, etc). For example, in web browsers, threads are normally used to implement tabs. The tabs in a web browsers usually run as separate threads in the main process of the web browser. That is, each new tab that you open in your web browser usually runs on a separate thread of execution.</p>
+<p>By running each tab in a separate thread, we allow all open tabs in the browser to run at the same time, and independently from each other. For example, you might have YouTube or Spotify currently open in a tab, and you are listening to some podcast in that tab while at the same time working in another tab, writing an essay on Google Docs. Even if you are not looking into the YouTube tab, you can still hear the podcast only because this YouTube tab is running in parallel with the other tab where Google Docs is running.</p>
+<p>Without threads, the other alternative would be to run each tab as a completely separate process in your computer. But that would be a bad choice because just a few tabs would already consume too much power and resources from your computer. In other words, it’s very expensive to create a completely new process, compared to creating a new thread of execution. Also, the chances of you experiencing lag and overhead while using the browser would be significant. Threads are faster to create, and they also consume much, much less resources from the computer, especially because they share some resources with the main process.</p>
+<p>Therefore, it’s the use of threads in modern web browsers that allow you to hear the podcast at the same time while you are writing something on Google Docs. Without threads, a web browser would probably be limited to just one single tab.</p>
 <p>Threads are also well-suited for anything that involves serving requests or orders. Because serving a request takes time, and usually involves a lot of “waiting time”. In other words, we spend a lot of time in idle, waiting for something to complete. For example, consider a restaurant. Serving orders in a restaurant usually involves the following steps:</p>
 <ol type="1">
 <li>receive order from the client.</li>
@@ -396,8 +396,8 @@ <h2 data-number="16.1" class="anchored" data-anchor-id="sec-what-thread"><span c
 <li>start cooking the food in the kitchen.</li>
 <li>when the food is fully cooked deliver this food to the client.</li>
 </ol>
-<p>If you think about the bullet points above, you will notice that one big moment of waiting time is present in this whole process, which is while the food is being cooked inside the kitchen. While the food is being prepped, both the waiter and the client itself are waiting for the food to be ready and delivered.</p>
-<p>If we write a program to represent this restaurant, more specifically, a single-threaded program, then, this program would be very inefficient. Because the program would stay in idle, waiting for a considerable amount of time on the “check if food is ready” step. Consider the code snippet exposed below that could potentially represent such program.</p>
+<p>If you think about the bullet points above, you will notice that one big moment of waiting time is present in this whole process, which is while the food is being cooked inside the kitchen. While the food is being prepped, both the waiter and the client themselves are waiting for the food to be ready and delivered.</p>
+<p>If we write a program to represent this restaurant, more specifically, a single-threaded program, then this program would be very inefficient. Because the program would stay in idle, waiting for a considerable amount of time on the “check if food is ready” step. Consider the code snippet exposed below that could potentially represent such program.</p>
 <p>The problem with this program is the while loop. This program will spend a lot of time waiting on the while loop, doing nothing more than just checking if the food is ready. This is a waste of time. Instead of waiting for something to happen, the waiter could just send the order to the kitchen, and just move on, and continue with receiving more orders from other clients, and sending more orders to the kitchen, instead of doing nothing and waiting for the food to be ready.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb1"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> order = Order.init(<span class="st">"Pizza Margherita"</span>, n = <span class="dv">1</span>);</span>
@@ -413,7 +413,7 @@ <h2 data-number="16.1" class="anchored" data-anchor-id="sec-what-thread"><span c
 </div>
 <p>This is why threads would be a great fit for this program. We could use threads to free the waiters from their “waiting duties”, so they can go on with their other tasks, and receive more orders. Take a look at the next example, where I have re-written the above program into a different program that uses threads to cook and deliver the orders.</p>
 <p>You can see in this program that when a waiter receives a new order from a client, this waiter executes the <code>send_order()</code> function. The only thing that this function does is to create a new thread and detaches it. Since creating a thread is a very fast operation, this <code>send_order()</code> function returns almost immediately, so the waiter spends almost no time worrying about the order, and just move on and tries to get the next order from the clients.</p>
-<p>Inside the new thread created, the order get’s cooked by a chef, and when the food is ready, it is delivered to the client’s table.</p>
+<p>Inside the new thread created, the order gets cooked by a chef, and when the food is ready, it’s delivered to the client’s table.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb2"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> cook_and_deliver_order(order: *Order) <span class="dt">void</span> <span class="op">{</span></span>
 <span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> chef = Chef.init();</span>
@@ -442,27 +442,27 @@ <h2 data-number="16.2" class="anchored" data-anchor-id="threads-versus-processes
 <p>This also means that every thread that we create is always associated with a particular process in our computer. In other words, a thread is always a subset (or a children) of an existing process. All threads share some of the resources associated with the process from which they were created. And because threads share resources with the process, they are very good for making communication between tasks easier.</p>
 <p>For example, suppose that you were developing a big and complex application that would be much simpler if you could split it in two, and make these two separate pieces talk with each other. Some programmers opt to effectively write these two pieces of the codebase as two completely separate programs, and then, they use IPC (<em>inter-process communication</em>) to make these two separate programs/processes talk to each other, and make them work together.</p>
 <p>However, some programmers find IPC hard to deal with, and, as consequence, they prefer to write one piece of the codebase as the “main part of the program”, or, as the part of the code that runs as the process in the operating system, while the other piece of the codebase is written as a task to be executed in a new thread. A process and a thread can easily comunicate with each other through both control flow, and also, through data, because they share and have access to the same standard file descriptors (<code>stdout</code>, <code>stdin</code>, <code>stderr</code>), and also to the same memory space on the heap and global data section.</p>
-<p>In more details, each thread that you create have a separate stack frame reserved just for that thread, which essentially means that each local object that you create inside this thread, is local to that thread, i.e.&nbsp;the other threads cannot see this local object. Unless this object that you have created is an object that lives on the heap. In other words, if the memory associated with this object is on the heap, then, the other threads can potentially access this object.</p>
-<p>Therefore, objects that are stored in the stack are local to the thread where they were created. But objects that are stored on the heap are potentially accessible to other threads. All of this means that, each thread have its own separate stack frame, but, at the same time, all threads share the same heap, the same standard file descriptors (which means that they share the same <code>stdout</code>, <code>stdin</code>, <code>stderr</code>), and the same global data section in the program.</p>
+<p>In more details, each thread that you create have a separate stack frame reserved just for that thread, which essentially means that each local object that you create inside this thread, is local to that thread, i.e., the other threads cannot see this local object. Unless this object that you have created is an object that lives on the heap. In other words, if the memory associated with this object is on the heap, then, the other threads can potentially access this object.</p>
+<p>Therefore, objects that are stored in the stack are local to the thread where they were created. But objects that are stored on the heap are potentially accessible to other threads. All of this means that, each thread has its own separate stack frame, but, at the same time, all threads share the same heap, the same standard file descriptors (which means that they share the same <code>stdout</code>, <code>stdin</code>, <code>stderr</code>), and the same global data section in the program.</p>
 </section>
 <section id="creating-a-thread" class="level2" data-number="16.3">
 <h2 data-number="16.3" class="anchored" data-anchor-id="creating-a-thread"><span class="header-section-number">16.3</span> Creating a thread</h2>
-<p>We create new threads in Zig, by first, importing the <code>Thread</code> struct into our current Zig module, and then, calling the <code>spawn()</code> method of this struct, which creates (or, “spawns”) a new thread of execution from our current process. This method have three arguments, which are, respectively:</p>
+<p>We create new threads in Zig by first importing the <code>Thread</code> struct into our current Zig module and then calling the <code>spawn()</code> method of this struct, which creates (or “spawns”) a new thread of execution from our current process. This method has three arguments, which are, respectively:</p>
 <ol type="1">
 <li>a <code>SpawnConfig</code> object, which contains configurations for the spawn process.</li>
-<li>the name of the function that is going to be executed (or, that is going to be “called”) inside this new thread.</li>
+<li>the name of the function that is going to be executed (or that is going to be “called”) inside this new thread.</li>
 <li>a list of arguments (or inputs) to be passed to the function provided in the second argument.</li>
 </ol>
-<p>With these three arguments, you can control how the thread get’s created, and also, specify which work (or “tasks”) will be performed inside this new thread. A thread is just a separate context of execution, and we usually create new threads in our code, because we want to perform some work inside this new context of execution. And we specify which exact work, or, which exact steps that are going to be performed inside this context, by providing the name of a function on the second argument of the <code>spawn()</code> method.</p>
-<p>Thus, when this new thread get’s created, this function that you provided as input to the <code>spawn()</code> method get’s called, or, get’s executed inside this new thread. You can control the arguments, or, the inputs that are passed to this function when it get’s called, by providing a list of arguments (or a list of inputs) on the third argument of the <code>spawn()</code> method. These arguments are passed to the function in the same order that they are provided to <code>spawn()</code>.</p>
+<p>With these three arguments, you can control how the thread gets created, and also, specify which work (or “tasks”) will be performed inside this new thread. A thread is just a separate context of execution, and we usually create new threads in our code because we want to perform some work inside this new context of execution. And we specify which exact work, or which exact steps that are going to be performed inside this context by providing the name of a function as the second argument of the <code>spawn()</code> method.</p>
+<p>Thus, when this new thread gets created, this function that you provided as input to the <code>spawn()</code> method gets called, or gets executed inside this new thread. You can control the arguments, or the inputs that are passed to this function when it gets called by providing a list of arguments (or a list of inputs) in the third argument of the <code>spawn()</code> method. These arguments are passed to the function in the same order that they are provided to <code>spawn()</code>.</p>
 <p>Furthermore, the <code>SpawnConfig</code> is a struct object with only two possible fields, or, two possible members, that you can set to tailor the spawn behaviour. These fields are:</p>
 <ul>
-<li><code>stack_size</code>: you can provide an <code>usize</code> value to specify the size (in bytes) of the thread’s stack frame. By default, this value is: <span class="math inline">\(16 \times 1024 \times 1024\)</span>.</li>
+<li><code>stack_size</code>: you can provide a <code>usize</code> value to specify the size (in bytes) of the thread’s stack frame. By default, this value is: <span class="math inline">\(16 \times 1024 \times 1024\)</span>.</li>
 <li><code>allocator</code>: you can provide an allocator object to be used when allocating memory for the thread.</li>
 </ul>
-<p>To use one of these two fields (or, “configs”) you just have to create a new object of type <code>SpawnConfig</code>, and provide this object as input to the <code>spawn()</code> method. But, if you are not interested in using one of these configs, and you are ok with using just the defaults, you can just provide an anonymous struct literal (<code>.{}</code>) in the place of this <code>SpawnConfig</code> argument.</p>
+<p>To use one of these two fields (or “configs”), you just have to create a new object of type <code>SpawnConfig</code>, and provide this object as input to the <code>spawn()</code> method. But, if you are not interested in using one of these configs, and you are ok with using just the defaults, you can just provide an anonymous struct literal (<code>.{}</code>) in place of this <code>SpawnConfig</code> argument.</p>
 <p>As our first, and very simple example, consider the code exposed below. Inside the same program, you can create multiple threads of execution if you want to. But, in this first example, we are creating just a single thread of execution, because we call <code>spawn()</code> only once.</p>
-<p>Also, notice in this example that we are executing the function <code>do_some_work()</code> inside the new thread. Since this function receives no inputs, because it has no arguments, we have passed an empty list in this instance, or, more precisely, an empty and anonymous struct (<code>.{}</code>) in the third argument of <code>spawn()</code>.</p>
+<p>Also, notice in this example that we are executing the function <code>do_some_work()</code> inside the new thread. Since this function receives no inputs, because it has no arguments, we have passed an empty list in this instance, or more precisely, an empty, anonymous struct (<code>.{}</code>) in the third argument of <code>spawn()</code>.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb3"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb3-2"><a href="#cb3-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
@@ -481,30 +481,30 @@ <h2 data-number="16.3" class="anchored" data-anchor-id="creating-a-thread"><span
 <pre><code>Starting the work.Finishing the work.</code></pre>
 </div>
 </div>
-<p>Notice the use of <code>try</code> when calling the <code>spawn()</code> method. This means that this method can return an error in some circumstances. One circumstance in particular is when you attempt to create a new thread, when you have already created too much (i.e.&nbsp;you have exceeded the quota of concurrent threads in your system).</p>
+<p>Notice the use of <code>try</code> when calling the <code>spawn()</code> method. This means that this method can return an error in some circumstances. One circumstance in particular is when you attempt to create a new thread, when you have already created too much (i.e., you have exceeded the quota of concurrent threads in your system).</p>
 <p>But, if the new thread is successfully created, the <code>spawn()</code> method returns a handler object (which is just an object of type <code>Thread</code>) to this new thread. You can use this handler object to effectively control all aspects of the thread.</p>
-<p>When the thread get’s created, the function that you provided as input to <code>spawn()</code> get’s invoked (i.e.&nbsp;get’s called) to start the execution on this new thread. In other words, everytime you call <code>spawn()</code>, not only a new thread get’s created, but also, the “start work button” of this thread get’s automatically pressed. So the work being performed in this thread starts at the moment that the thread is created. This is similar to how <code>pthread_create()</code> from the <code>pthreads</code> library in C works, which also starts the execution at the moment that the thread get’s created.</p>
+<p>When the thread gets created, the function that you provided as input to <code>spawn()</code> gets invoked (i.e., gets called) to start the execution on this new thread. In other words, every time you call <code>spawn()</code>, not only is a new thread created, but the “start work button” of this thread is also automatically pressed. So the work being performed in this thread starts as soon as the thread is created. This is similar to how <code>pthread_create()</code> from the <code>pthreads</code> library in C works, which also starts the execution as soon as the thread is created.</p>
 </section>
 <section id="returning-from-a-thread" class="level2" data-number="16.4">
 <h2 data-number="16.4" class="anchored" data-anchor-id="returning-from-a-thread"><span class="header-section-number">16.4</span> Returning from a thread</h2>
-<p>We have learned on the previous section that the execution of the thread starts at the moment that the thread get’s created. Now, we will learn how to “join” or “detach” a thread in Zig. “Join” and “detach” are operations that control how the thread returns to the main thread, or, to the main process in our program.</p>
-<p>We perform these operations by using the methods <code>join()</code> and <code>detach()</code> from the thread handler object. Every thread that you create can be marked as either <em>joinable</em> or <em>detached</em> <span class="citation" data-cites="linux_pthread_create">(<a href="../references.html#ref-linux_pthread_create" role="doc-biblioref">Linux man-pages 2024</a>)</span>. You can turn a thread into a <em>detached</em> thread by calling the <code>detach()</code> method from the thread handler object. But if you call the <code>join()</code> method instead, then, this thread becomes a <em>joinable</em> thread.</p>
-<p>A thread cannot be both <em>joinable</em> and <em>detached</em>. Which in general means that you cannot call both <code>join()</code> and <code>detach()</code> on the same thread. But a thread must be one of the two, meaning that, you should always call either <code>join()</code> or <code>detach()</code> over a thread. If you don’t call one of these two methods over your thread, you introduce undefined behaviour into your program, which is described at <a href="#sec-not-call-join-detach" class="quarto-xref"><span>Section 16.9.2</span></a>.</p>
+<p>We have learned in the previous section that the execution of the thread starts as soon as the thread is created. Now, we will learn how to “join” or “detach” a thread in Zig. “Join” and “detach” are operations that control how the thread returns to the main thread, or to the main process in our program.</p>
+<p>We perform these operations by using the methods <code>join()</code> and <code>detach()</code> from the thread handler object. Every thread that you create can be marked as either <em>joinable</em> or <em>detached</em> <span class="citation" data-cites="linux_pthread_create">(<a href="../references.html#ref-linux_pthread_create" role="doc-biblioref">Linux man-pages 2024</a>)</span>. You can turn a thread into a <em>detached</em> thread by calling the <code>detach()</code> method from the thread handler object. But if you call the <code>join()</code> method instead, then this thread becomes a <em>joinable</em> thread.</p>
+<p>A thread cannot be both <em>joinable</em> and <em>detached</em>. Which in general means that you cannot call both <code>join()</code> and <code>detach()</code> on the same thread. But a thread must be one of the two, meaning that, you should always call either <code>join()</code> or <code>detach()</code> over a thread. If you don’t call one of these two methods over your thread, you introduce undefined behaviour into your program, which is described in <a href="#sec-not-call-join-detach" class="quarto-xref"><span>Section 16.9.2</span></a>.</p>
 <p>Now, let’s describe what each of these two methods do to your thread.</p>
 <section id="joining-a-thread" class="level3" data-number="16.4.1">
 <h3 data-number="16.4.1" class="anchored" data-anchor-id="joining-a-thread"><span class="header-section-number">16.4.1</span> Joining a thread</h3>
-<p>When you join a thread, you are essentially saying: “Hey! Could you please wait for the thread to finish, before you continue with your execution?”. For example, if we comeback to our first and simpliest example of a thread in Zig, in that example we have created a single thread inside the <code>main()</code> function of our program, and just called <code>join()</code> over this thread at the end. This section of the code example is reproduced below.</p>
-<p>Because we are joining this new thread inside the <code>main()</code>’s scope, it means that the execution of the <code>main()</code> function is temporarily stopped, to wait for the execution of the thread to finish. That is, the execution of <code>main()</code> stops temporarily at the line where <code>join()</code> get’s called, and it will continue only after the thread has finished its tasks.</p>
+<p>When you join a thread, you are essentially saying: “Hey! Could you please wait for the thread to finish, before you continue with your execution?”. For example, if we come back to our first and simplest example of a thread in Zig, we created a single thread inside the <code>main()</code> function of our program and just called <code>join()</code> on this thread at the end. This section of the code example is reproduced below.</p>
+<p>Because we are joining this new thread inside the <code>main()</code>’s scope, it means that the execution of the <code>main()</code> function is temporarily stopped, to wait for the execution of the thread to finish. That is, the execution of <code>main()</code> stops temporarily at the line where <code>join()</code> gets called, and it will continue only after the thread has finished its tasks.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb5"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
 <span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> thread = <span class="kw">try</span> Thread.spawn(.<span class="op">{}</span>, do_some_work, .<span class="op">{}</span>);</span>
 <span id="cb5-3"><a href="#cb5-3" aria-hidden="true" tabindex="-1"></a>    thread.join();</span>
 <span id="cb5-4"><a href="#cb5-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>Because we have joined this new thread inside the <code>main()</code> scope, we have a guarantee that this new thread will finish before the end of the execution of <code>main()</code>. Because it is guaranteed that <code>main()</code> will wait for the thread to finish its tasks.</p>
+<p>Because we have joined this new thread inside the <code>main()</code> scope, we have a guarantee that this new thread will finish before the end of the execution of <code>main()</code>. Because it’s guaranteed that <code>main()</code> will wait for the thread to finish its tasks.</p>
 <p>In the example above, there are no more expressions after the <code>join()</code> call. We just have the end of the <code>main()</code>’s scope, and, therefore, the execution of our program just ends after the thread finishes its tasks, since there is nothing more to do. But what if we had more stuff to do after the join call?</p>
 <p>To demonstrate this other possibility, consider the next example exposed below. Here, we create a <code>print_id()</code> function, that just receives an id as input, and prints it to <code>stdout</code>. In this example, we are creating two new threads, one after another. Then, we join the first thread, then, we wait for two whole seconds, then, at last, we join the second thread.</p>
-<p>The idea behind this example is that the last <code>join()</code> call is executed only after the first thread finishes its task (i.e.&nbsp;the first <code>join()</code> call), and also, after the two seconds of delay. If you compile and run this example, you will notice that most messages are quickly printed to <code>stdout</code>, i.e.&nbsp;they appear almost instantly on your screen. However, the last message (“Joining thread 2”) takes around 2 seconds to appear in the screen.</p>
+<p>The idea behind this example is that the last <code>join()</code> call is executed only after the first thread finishes its task (i.e., the first <code>join()</code> call), and the two-second delay. If you compile and run this example, you will notice that most messages are quickly printed to <code>stdout</code>, i.e., they appear almost instantly on your screen. However, the last message (“Joining thread 2”) takes around 2 seconds to appear on the screen.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb6"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> print_id(id: *<span class="kw">const</span> <span class="dt">u8</span>) !<span class="dt">void</span> <span class="op">{</span></span>
 <span id="cb6-2"><a href="#cb6-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"Thread ID: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>id.*<span class="op">}</span>);</span>
@@ -527,18 +527,18 @@ <h3 data-number="16.4.1" class="anchored" data-anchor-id="joining-a-thread"><spa
 1
 Thread ID: 2
 Joining thread 2</code></pre>
-<p>This demonstrates that both threads finish their work (i.e.&nbsp;printing the IDs) very fast, before the two seconds of delay end. Because of that, the last <code>join()</code> call returns pretty much instantly. Because when this last <code>join()</code> call happens, the second thread have already finished its task.</p>
+<p>This demonstrates that both threads finish their work (i.e., printing the IDs) very fast, before the two seconds of delay end. Because of that, the last <code>join()</code> call returns pretty much instantly. Because when this last <code>join()</code> call happens, the second thread has already finished its task.</p>
 <p>Now, if you compile and run this example, you will also notice that, in some cases, the messages intertwine with each other. In other words, you might see the message “Joining thread 1” inserted in the middle of the message “Thread 1”, or vice-versa. This happens because:</p>
 <ul>
-<li>the threads are executing basically at the same time as the main process of the program (i.e.&nbsp;the <code>main()</code> function).</li>
+<li>the threads are executing basically at the same time as the main process of the program (i.e., the <code>main()</code> function).</li>
 <li>the threads share the same <code>stdout</code> from the main process of the program, which means that the messages that the threads produce are sent to exact same place as the messages produced by the main process.</li>
 </ul>
-<p>Both of these points were described previously at <a href="#sec-what-thread" class="quarto-xref"><span>Section 16.1</span></a>. So the messages might get intertwined because they are being produced and sent to the same <code>stdout</code> roughly at the same time. Anyway, when you call <code>join()</code> over a thread, the current process will wait for the thread to finish before it continues, and, when the thread does finishes its task, the resources associated with this thread are automatically freed, and, the current process continues with its execution.</p>
+<p>Both of these points were described previously in <a href="#sec-what-thread" class="quarto-xref"><span>Section 16.1</span></a>. So the messages might get intertwined because they are being produced and sent to the same <code>stdout</code> roughly at the same time. Anyway, when you call <code>join()</code> over a thread, the current process will wait for the thread to finish before it continues, and, when the thread finishes its task, the resources associated with this thread are automatically freed, and the current process continues with its execution.</p>
 </section>
 <section id="detaching-a-thread" class="level3" data-number="16.4.2">
 <h3 data-number="16.4.2" class="anchored" data-anchor-id="detaching-a-thread"><span class="header-section-number">16.4.2</span> Detaching a thread</h3>
 <p>When you detach a thread, the resources associated with this thread are automatically released back to the system, without the need for another thread to join with this terminated thread.</p>
-<p>In other words, when you call <code>detach()</code> over a thread it’s like when your children becomes adults, i.e.&nbsp;they become independent from you. A detached thread frees itself, and when this thread finishes its tasks, it does not report the results back to you. Thus, you normally mark a thread as <em>detached</em> when you don’t need to use the return value of the thread, or, when you don’t care about when exactly the thread finishes its job, i.e.&nbsp;the thread solves everything by itself.</p>
+<p>In other words, when you call <code>detach()</code> on a thread it’s like when your children become adults, i.e., they become independent from you. A detached thread frees itself, and when this thread finishes its tasks, it does not report the results back to you. Thus, you normally mark a thread as <em>detached</em> when you don’t need to use the return value of the thread, or when you don’t care about when exactly the thread finishes its job, i.e., the thread solves everything by itself.</p>
 <p>Take the code example below. We create a new thread, detach it, and then, we just print a final message before we end our program. We use the same <code>print_id()</code> function that we have used over the previous examples.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb8"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> print_id(id: *<span class="kw">const</span> <span class="dt">u8</span>) !<span class="dt">void</span> <span class="op">{</span></span>
@@ -553,15 +553,15 @@ <h3 data-number="16.4.2" class="anchored" data-anchor-id="detaching-a-thread"><s
 <span id="cb8-10"><a href="#cb8-10" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Finish main</code></pre>
-<p>Now, if you look closely at the output of this code example, you will notice that only the final message in main was printed to the console. The message that was supposed to be printed by <code>print_id()</code> did not appear in the console. Why? Is because the main process of our program has finished first, before the thread was able to say anything.</p>
-<p>And that is perfectly ok behaviour, because the thread was detached, so, it was able to free itself, without the need to wait for the main process. If you ask main to sleep (or “wait”) for some extra nanoseconds, before it ends, you will likely see the message printed by <code>print_id()</code>, because you give enough time for the thread to finish before the main process ends.</p>
+<p>Now, if you look closely at the output of this code example, you will notice that only the final message in main was printed to the console. The message that was supposed to be printed by <code>print_id()</code> did not appear in the console. Why? It’s because the main process of our program has finished first, before the thread was able to say anything.</p>
+<p>And that is perfectly ok behaviour, because the thread was detached, so it was able to free itself, without the need to wait for the main process. If you ask main to sleep (or “wait”) for some extra nanoseconds, before it ends, you will likely see the message printed by <code>print_id()</code>, because you give enough time for the thread to finish before the main process ends.</p>
 </section>
 </section>
 <section id="thread-pools" class="level2" data-number="16.5">
 <h2 data-number="16.5" class="anchored" data-anchor-id="thread-pools"><span class="header-section-number">16.5</span> Thread pools</h2>
-<p>Thread pools is a very popular programming pattern, which is used especially on servers and daemons processes. A thread pool is just a set of threads, or, a “pool” of threads. Many programmers like to use this pattern, because it makes easier to manage and use multiple threads in your program, instead of manually creating the threads when you need them.</p>
+<p>Thread pools is a very popular programming pattern, which is used especially on servers and daemons processes. A thread pool is just a set of threads, or a “pool” of threads. Many programmers like to use this pattern because it makes it easier to manage and use multiple threads in your program, instead of manually creating the threads when you need them.</p>
 <p>Also, using thread pools might increase performance as well in your program, especially if your program is constantly creating threads to perform short-lived tasks. In such instance, a thread pool might cause an increase in performance because you do not have be constantly creating and destroying threads all the time, so you don’t face a lot of the overhead involved in this constant process of creating and destroying threads.</p>
-<p>The main idea behind a thread pool is to have a set of threads already created and ready to perform tasks at all times. You create a set of threads at the moment that your program starts, and keep these threads alive while your program runs. Each of these threads will be either performing a task, or, waiting for a task to be assigned. Every time a new task emerges in your program, this task is added to a “queue of tasks”, and the moment that a thread becomes available and ready to perform a new task, this thread takes the next task from the “queue of tasks”, and it simply performs the task.</p>
+<p>The main idea behind a thread pool is to have a set of threads already created and ready to perform tasks at all times. You create a set of threads at the moment that your program starts, and keep these threads alive while your program runs. Each of these threads will be either performing a task, or waiting for a task to be assigned. Every time a new task emerges in your program, this task is added to a “queue of tasks”, and the moment that a thread becomes available and ready to perform a new task, this thread takes the next task from the “queue of tasks”, and it simply performs the task.</p>
 <p>The Zig Standard Library offers a thread pool implementation on the <code>std.Thread.Pool</code> struct. You create a new instance of a <code>Pool</code> object by providing a <code>Pool.Options</code> object as input to the <code>init()</code> method of this struct. A <code>Pool.Options</code> object, is a struct object that contains configurations for the pool of threads. The most important settings in this struct object are the members <code>n_jobs</code> and <code>allocator</code>. As the name suggests, the member <code>allocator</code> should receive an allocator object, while the member <code>n_jobs</code> specifies the number of threads to be created and maintained in this pool.</p>
 <p>Consider the example exposed below, that demonstrates how can we create a new thread pool object. Here, we create a <code>Pool.Options</code> object that contains a general purpose allocator object, and also, the <code>n_jobs</code> member was set to 4, which means that the thread pool will create and use 4 threads.</p>
 <p>Also notice that the <code>pool</code> object was initially set to <code>undefined</code>. This allow us to initially declare the thread pool object, but not properly instantiate the underlying memory of the object. You have to initially declare your thread pool object by using <code>undefined</code> like this, because the <code>init()</code> method of <code>Pool</code> needs to have an initial pointer to properly instantiate the object.</p>
@@ -577,13 +577,13 @@ <h2 data-number="16.5" class="anchored" data-anchor-id="thread-pools"><span clas
 <span id="cb10-8"><a href="#cb10-8" aria-hidden="true" tabindex="-1"></a>        .allocator = allocator,</span>
 <span id="cb10-9"><a href="#cb10-9" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>;</span>
 <span id="cb10-10"><a href="#cb10-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> pool: Pool = <span class="cn">undefined</span>;</span>
-<span id="cb10-11"><a href="#cb10-11" aria-hidden="true" tabindex="-1"></a>    _ = <span class="kw">try</span> pool.init(opt);</span>
+<span id="cb10-11"><a href="#cb10-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> pool.init(opt);</span>
 <span id="cb10-12"><a href="#cb10-12" aria-hidden="true" tabindex="-1"></a>    <span class="kw">defer</span> pool.deinit();</span>
 <span id="cb10-13"><a href="#cb10-13" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>Now that we know how to create <code>Pool</code> objects, we have to understand how to assign tasks to be executed by the threads in this pool object. To assign a task to be performed by a thread, we need to call the <code>spawn()</code> method from the thread pool object.</p>
-<p>This <code>spawn()</code> method works identical to the <code>spawn()</code> method from the <code>Thread</code> object. The method have almost the same arguments as the previous one, more precisely, we don’t have to provide a <code>SpawnConfig</code> object in this case. But instead of creating a new thread, this <code>spawn()</code> method from the thread pool object just register a new task in the internal “queue of tasks” to be performed, and any available thread in the pool will get this task, and it will simply perform the task.</p>
-<p>In the example below, we are using our previous <code>print_id()</code> function once again. But you may notice that the <code>print_id()</code> function is a little different this time, because now we are using <code>catch</code> instead of <code>try</code> in the <code>print()</code> call. Currently, the <code>Pool</code> struct only supports functions that don’t return errors as tasks. Thus, when assigning tasks to threads in a thread pool, is essential to use functions that don’t return errors. That is why we are using <code>catch</code> here, so that the <code>print_id()</code> function don’t return an error.</p>
+<p>This <code>spawn()</code> method works identical to the <code>spawn()</code> method from the <code>Thread</code> object. The method has almost the same arguments as the previous one, more precisely, we don’t have to provide a <code>SpawnConfig</code> object in this case. But instead of creating a new thread, this <code>spawn()</code> method from the thread pool object just registers a new task in the internal “queue of tasks” to be performed, and any available thread in the pool will get this task, and it will simply perform the task.</p>
+<p>In the example below, we are using our previous <code>print_id()</code> function once again. But you may notice that the <code>print_id()</code> function is a little different this time, because now we are using <code>catch</code> instead of <code>try</code> in the <code>print()</code> call. Currently, the <code>Pool</code> struct only supports functions that don’t return errors as tasks. Thus, when assigning tasks to threads in a thread pool, it is essential to use functions that don’t return errors. That is why we are using <code>catch</code> here, so that the <code>print_id()</code> function don’t return an error.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb11"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> print_id(id: *<span class="kw">const</span> <span class="dt">u8</span>) <span class="dt">void</span> <span class="op">{</span></span>
 <span id="cb11-2"><a href="#cb11-2" aria-hidden="true" tabindex="-1"></a>    _ = stdout.print(<span class="st">"Thread ID: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>id.*<span class="op">}</span>)</span>
@@ -594,7 +594,7 @@ <h2 data-number="16.5" class="anchored" data-anchor-id="thread-pools"><span clas
 <span id="cb11-7"><a href="#cb11-7" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> pool.spawn(print_id, .<span class="op">{</span>&amp;id1<span class="op">}</span>);</span>
 <span id="cb11-8"><a href="#cb11-8" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> pool.spawn(print_id, .<span class="op">{</span>&amp;id2<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>This limitation should probably not exist, and, in fact, it is already on the radar of the Zig team to fix this issue, and it is being tracked on an <a href="https://github.com/ziglang/zig/issues/18810">open issue</a><a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>. So, if you do need to provide a function that might return an error as the task to be performed by the threads in the thread pool, then, you are either limited to:</p>
+<p>This limitation should probably not exist, and, in fact, it’s already on the radar of the Zig team to fix this issue, and it’s being tracked in an <a href="https://github.com/ziglang/zig/issues/18810">open issue</a><a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>. So, if you do need to provide a function that might return an error as the task to be performed by the threads in the thread pool, then, you are either limited to:</p>
 <ul>
 <li>implementing your own thread pool that does not have this limitation.</li>
 <li>wait for the Zig team to actually fix this issue.</li>
@@ -603,14 +603,14 @@ <h2 data-number="16.5" class="anchored" data-anchor-id="thread-pools"><span clas
 <section id="mutexes" class="level2" data-number="16.6">
 <h2 data-number="16.6" class="anchored" data-anchor-id="mutexes"><span class="header-section-number">16.6</span> Mutexes</h2>
 <p>Mutexes are a classic component of every thread library. In essence, a mutex is a <em>Mutually Exclusive Flag</em>, and this flag acts like a type of “lock”, or as a gate keeper to a particular section of your code. Mutexes are related to thread synchronization, more specifically, they prevent you from having some classic race conditions in your program, and, therefore, major bugs and undefined behaviour that are usually difficult to track and understand.</p>
-<p>The main idea behind a mutex is to help us to control the execution of a particular section of the code, and to prevent two or more threads from executing this particular section of the code at the same time. Many programmers like to compare a mutex to a bathroom door (which usually have a lock). When a thread locks its own mutex object, it is like if the bathroom door was locked, and, therefore, the other people (in this case, the other threads) that wants to use the same bathroom at the same time have to be patient, and simply wait for the other person (or the other thread) to unlock the door and get out of the bathroom.</p>
-<p>Some other programmers also like to explain mutexes by using the analogy of “each person will have their turn to speak”. This is the analogy used on the <a href="https://www.youtube.com/watch?v=7ENFeb-J75k&amp;ab_channel=Computerphile"><em>Multithreading Code</em> video from the Computerphile project</a><a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a>. Imagine if you are in a conversation circle. There is a moderator in this circle, which is the person that decides who have the right to speak at that particular moment. The moderator gives a green card (or some sort of an authorization card) to the person that is going to speak, and, as a result, everyone else must be silent and hear this person that has the green card. When the person finishes talking, it gives the green card back to the moderator, and the moderator decides who is going to talk next, and delivers the green card to that person. And the cycle goes on like this.</p>
-<p>A mutex acts like the moderator in this conversation circle. The mutex authorizes one single thread to execute a specific section of the code, and it also blocks the other threads from executing this same section of the code. If these other threads want to execute this same piece of the code, they are forced to wait for the the authorized thread to finish first. When the authorized thread finishes executing this code, the mutex authorizes the next thread to execute this code, and the other threads are still blocked. Therefore, a mutex is like a moderator that does a “each thread will have their turn to execute this section of the code” type of control.</p>
+<p>The main idea behind a mutex is to help us to control the execution of a particular section of the code, and to prevent two or more threads from executing this particular section of the code at the same time. Many programmers like to compare a mutex to a bathroom door (which typically has a lock). When a thread locks its own mutex object, it’s like if the bathroom door was locked. Therefore, other people (in this case, other threads) who want to use the same bathroom at the same time must be patient and simply wait for the current occupant (or thread) to unlock the door and get out of the bathroom.</p>
+<p>Some other programmers also like to explain mutexes by using the analogy of “each person will have their turn to speak”. This is the analogy used in the <a href="https://www.youtube.com/watch?v=7ENFeb-J75k&amp;ab_channel=Computerphile"><em>Multithreading Code</em> video from the Computerphile project</a><a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a>. Imagine if you are in a conversation circle. There is a moderator in this circle, which is the person that decides who has the right to speak at that particular moment. The moderator gives a green card (or some sort of an authorization card) to the person that is going to speak, and, as a result, everyone else must be silent and hear this person that has the green card. When the person finishes talking, they give the green card back to the moderator, and the moderator decides who is going to talk next, and delivers the green card to that person. And the cycle goes on like this.</p>
+<p>A mutex acts like the moderator in this conversation circle. The mutex authorizes one single thread to execute a specific section of the code, and it also blocks the other threads from executing this same section of the code. If these other threads want to execute this same piece of the code, they are forced to wait for the the authorized thread to finish first. When the authorized thread finishes executing this code, the mutex authorizes the next thread to execute this code, while the remaining threads remain blocked. Therefore, a mutex is like a moderator that does a “each thread will have their turn to execute this section of the code” type of control.</p>
 <p>Mutexes are especially used to prevent data race problems from happening. A data race problem happens when two or more threads are trying to read from or write to the same shared object at the same time. So, when you have an object that is shared will all threads, and, you want to avoid two or more threads from accessing this same object at the same time, you can use a mutex to lock the part of the code that access this specific object. When a thread tries to run this code that is locked by a mutex, this thread stops its execution, and patiently waits for this section of the codebase to be unlocked to continue.</p>
-<p>Notice that mutexes are normally used to lock areas of the codebase that access/modify data that is <strong>shared</strong> with all threads, i.e.&nbsp;objects that are either stored in the global data section, or, in the heap space of your program. So mutexes are not normally used on areas of the codebase that access/modify objects that are local to the thread.</p>
+<p>Notice that mutexes are normally used to lock areas of the codebase that access/modify data that is <strong>shared</strong> with all threads, i.e., objects that are either stored in the global data section, or in the heap space of your program. So mutexes are not normally used on areas of the codebase that access/modify objects that are local to the thread.</p>
 <section id="sec-critical-section" class="level3" data-number="16.6.1">
 <h3 data-number="16.6.1" class="anchored" data-anchor-id="sec-critical-section"><span class="header-section-number">16.6.1</span> Critical section</h3>
-<p>Critical section is a concept commonly associated with mutexes and thread synchronization. In essence, a critical section is the section of the program that a thread access/modify a shared resource (i.e.&nbsp;an object, a file descriptor, something that all threads have access to). In other words, a critical section is the section of the program where race conditions might happen, and, therefore, where undefined behaviour can be introduced into the program.</p>
+<p>Critical section is a concept commonly associated with mutexes and thread synchronization. In essence, a critical section is the section of the program that a thread access/modify a shared resource (i.e., an object, a file descriptor, something that all threads have access to). In other words, a critical section is the section of the program where race conditions might happen, and, therefore, where undefined behaviour can be introduced into the program.</p>
 <p>When we use mutexes in our program, the critical section defines the area of the codebase that we want to lock. So we normally lock the mutex object at the beginning of the critical section, and then, we unlock it at the end of the critical section. The two bullet points exposed below comes from the “Critical Section” article from GeekFromGeeks, and they summarise well the role that a critical section plays in the thread synchronization problem <span class="citation" data-cites="geeks_critical_section">(<a href="../references.html#ref-geeks_critical_section" role="doc-biblioref">Geeks for Geeks 2024</a>)</span>.</p>
 <ol type="1">
 <li>The critical section must be executed as an atomic operation, which means that once one thread or process has entered the critical section, all other threads or processes must wait until the executing thread or process exits the critical section. The purpose of synchronization mechanisms is to ensure that only one thread or process can execute the critical section at a time.</li>
@@ -619,19 +619,19 @@ <h3 data-number="16.6.1" class="anchored" data-anchor-id="sec-critical-section">
 </section>
 <section id="sec-atomic-operation" class="level3" data-number="16.6.2">
 <h3 data-number="16.6.2" class="anchored" data-anchor-id="sec-atomic-operation"><span class="header-section-number">16.6.2</span> Atomic operations</h3>
-<p>You will also see the term “atomic operation” a lot when reading about threads, race conditions and mutexes. In summary, an operation is categorized as “atomic”, when there is no way to happen a context switch in the middle of this operation. In other words, this operation is always done from beginning to end, without interruptions of another process or operation in the middle of its execution phase.</p>
-<p>Not many operations today are atomic. But why atomic operations matters here? Is because data races (which is a type of a race condition) cannot happen on operations that are atomic. So if a particular line in your code performs an atomic operation, then, this line will never suffer from a data race problem. Therefore, programmers sometimes use an atomic operation to protect themselves from data race problems in their code.</p>
-<p>When you have an operation that is compiled into just one single assembly instruction, this operation might be atomic, because it is just one assembly instruction. But this is not guaranteed. This is usually true for old CPU architectures (such as <code>x86</code>). But nowadays, most assembly instructions in modern CPU architectures turn into multiple micro-tasks, which inherently makes the operation not atomic anymore, even though it has just one single assembly instruction.</p>
-<p>The Zig Standard Library offers some atomic functionality at the <code>std.atomic</code> module. In this module, you will find a public and generic function called <code>Value()</code>. With this function we create an “atomic object”, which is a value that contains some native atomic operations, most notably, a <code>load()</code> and a <code>fetchAdd()</code> operation. If you have experience with multithreading in C++, you probably have recognized this pattern. So yes, this generic “atomic object” in Zig is essentially identical to the template struct <code>std::atomic</code> from the C++ Standard Library. Is important to emphasize that only primitive data types (i.e.&nbsp;the types presented at <a href="01-zig-weird.html#sec-primitive-data-types" class="quarto-xref"><span>Section 1.5</span></a>) are supported by these atomic operations in Zig.</p>
+<p>You will also see the term “atomic operation” a lot when reading about threads, race conditions and mutexes. In summary, an operation is categorized as “atomic” when a context switch cannot occur in the middle of the operation. In other words, this operation is always done from beginning to end, without interruptions of another process or operation in the middle of its execution phase.</p>
+<p>Not many operations today are atomic. But why do atomic operations matter here? It’s because data races (which is a type of a race condition) cannot happen on operations that are atomic. So if a particular line in your code performs an atomic operation, then this line will never suffer from a data race problem. Therefore, programmers sometimes use an atomic operation to protect themselves from data race problems in their code.</p>
+<p>When you have an operation that is compiled into just one single assembly instruction, this operation might be atomic, because it’s just one assembly instruction. But this is not guaranteed. This is usually true for old CPU architectures (such as <code>x86</code>). But nowadays, most assembly instructions in modern CPU architectures are broken down into multiple micro-tasks, which inherently makes the operation non-atomic, even if it consists of a single assembly instruction.</p>
+<p>The Zig Standard Library offers some atomic functionality in the <code>std.atomic</code> module. In this module, you will find a public and generic function called <code>Value()</code>. With this function we create an “atomic object”, which is a value that contains some native atomic operations, most notably, a <code>load()</code> and a <code>fetchAdd()</code> operation. If you have experience with multithreading in C++, you probably have recognized this pattern. So yes, this generic “atomic object” in Zig is essentially identical to the template struct <code>std::atomic</code> from the C++ Standard Library. It’s important to emphasize that only primitive data types (i.e., the types presented in <a href="01-zig-weird.html#sec-primitive-data-types" class="quarto-xref"><span>Section 1.5</span></a>) are supported by these atomic operations in Zig.</p>
 </section>
 <section id="data-races-and-race-conditions" class="level3" data-number="16.6.3">
 <h3 data-number="16.6.3" class="anchored" data-anchor-id="data-races-and-race-conditions"><span class="header-section-number">16.6.3</span> Data races and race conditions</h3>
-<p>To understand why mutexes are used, we need to understand better the problem that they seek to solve, which can be summarized into data races problems. A data race problem is a type of a race condition, which happens when one thread is accessing a particular memory location (i.e.&nbsp;a particular shared object) at the same time that another thread is trying to write/save new data into this same memory location (i.e.&nbsp;the same shared object).</p>
-<p>We can simply define a race condition as any type of bug in your program that is based on a “who get’s there first” problem. A data race problem is a type of a race condition, because it occurs when two or more parties are trying to read and write into the same memory location at the same time, and, therefore, the end result of this operation depends completely on who get’s to this memory location first. As consequence, a program that have a data race problem will likely produce a different result each time that we execute it.</p>
-<p>Thus, race conditions produce undefined behaviour and unpredictability because the program produces a different answer in each time that a different person get’s to the target location first than the others. And we have no easy way to either predict or control who is getting to this target location first. In other words, in each execution of your program, you get a different answer, because a different person, or, a different function, or, a different part of the code is finishing its tasks first than the others.</p>
+<p>To understand why mutexes are used, we need to understand better the problem that they seek to solve, which can be summarized into data race problems. A data race problem is a type of a race condition, which happens when one thread is accessing a particular memory location (i.e., a particular shared object) at the same time that another thread is trying to write/save new data into this same memory location (i.e., the same shared object).</p>
+<p>We can simply define a race condition as any type of bug in your program that is based on a “who gets there first” problem. A data race problem is a type of a race condition, because it occurs when two or more parties are trying to read and write into the same memory location at the same time, and, therefore, the end result of this operation depends completely on who gets to this memory location first. As a consequence, a program that has a data race problem will likely produce a different result each time that we execute it.</p>
+<p>Thus, race conditions produce undefined behaviour and unpredictability because the program produces a different answer each time a different person gets to the target location before the others. And, we have no easy way to either predict or control who is getting to this target location first. In other words, each time your program runs, you may get a different answer because a different person, function, or part of the code finishes its tasks before the others.</p>
 <p>As an example, consider the code snippet exposed below. In this example, we create a global counter variable, and we also create an <code>increment()</code> function, whose job is to just increment this global counter variable in a for loop.</p>
 <p>Since the for loop iterates 1 hundred thousand times, and, we create two separate threads in this code example, what number do you expect to see in the final message printed to <code>stdout</code>? The answer should be 2 hundred thousand. Right? Well, in theory, this program was supposed to print 2 hundred thousand at the end, but in practice, every time that I execute this program I get a different answer.</p>
-<p>In the example exposed below, you can see that this time the end result was 117254, instead of the expected 200000. The second time I have executed this program, I got the number 108592 as result. So the end result of this program is varying, but it never gets to the expected 200000 that we want.</p>
+<p>In the example exposed below, you can see that this time the end result was 117254, instead of the expected 200000. The second time I executed this program, I got the number 108592 as the result. So the end result of this program is varying, but it never gets to the expected 200000 that we want.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb12"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a><span class="co">// Global counter variable</span></span>
 <span id="cb12-2"><a href="#cb12-2" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> counter: <span class="dt">usize</span> = <span class="dv">0</span>;</span>
@@ -651,15 +651,15 @@ <h3 data-number="16.6.3" class="anchored" data-anchor-id="data-races-and-race-co
 <span id="cb12-16"><a href="#cb12-16" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Couter value: 117254</code></pre>
-<p>Why this is happening? The answer is: because this program contains a data race problem. This program would print the correct number 200000, if, and only if the first thread finishes its tasks before the second thread starts to execute. But that is very unlikely to happen. Because the process of creating the thread is too fast, and therefore, both threads starts to execute roughly at the same time. If you change this code to add some nanoseconds of sleep between the first and the second calls to <code>spawn()</code>, you will increase the chances of the program producing the “correct result”.</p>
-<p>So the data race problem happens, because both threads are reading and writing to the same memory location at roughly the same time. In this example, each thread is essentially performing three basic operations at each iteration of the for loop, which are:</p>
+<p>Why this is happening? The answer is: because this program contains a data race problem. This program would print the correct number 200000 if and only if the first thread finishes its tasks before the second thread starts to execute. But that is very unlikely to happen. Because the process of creating the thread is too fast, and therefore, both threads start to execute roughly at the same time. If you change this code to add some nanoseconds of sleep between the first and the second calls to <code>spawn()</code>, you will increase the chances of the program producing the “correct result”.</p>
+<p>So the data race problem happens because both threads are reading and writing to the same memory location at roughly the same time. In this example, each thread is essentially performing three basic operations at each iteration of the for loop, which are:</p>
 <ol type="1">
 <li>reading the current value of <code>count</code>.</li>
 <li>incrementing this value by 1.</li>
 <li>writing the result back into <code>count</code>.</li>
 </ol>
-<p>Ideally, a thread B should read the value of <code>count</code>, only after the other thread A has finished writing the incremented value back into the <code>count</code> object. Therefore, in the ideal scenario, which is demonstrated at <a href="#tbl-data-race-ideal" class="quarto-xref">Table&nbsp;<span>16.1</span></a>, the threads should work in sync with each other. But the reality is that these threads are out of sync, and because of that, they suffer from a data race problem, which is demonstrated at <a href="#tbl-data-race-not" class="quarto-xref">Table&nbsp;<span>16.2</span></a>.</p>
-<p>Notice that, in the data race scenario (<a href="#tbl-data-race-not" class="quarto-xref">Table&nbsp;<span>16.2</span></a>), the read performed by a thread B happens before the write operation of thread A, and that ultimately leads to wrong results at the end of the program. Because when the thread B reads the value from the <code>count</code> variable, the thread A is still processing the initial value from <code>count</code>, and it did not write the new and incremented value into <code>count</code> yet. So what happens is that thread B ends up reading the same initial value (the “old” value) from <code>count</code>, instead of reading the new and incremented version of this value that would be calculated by thread A.</p>
+<p>Ideally, a thread B should read the value of <code>count</code>, only after the other thread A has finished writing the incremented value back into the <code>count</code> object. Therefore, in the ideal scenario, which is demonstrated in <a href="#tbl-data-race-ideal" class="quarto-xref">Table&nbsp;<span>16.1</span></a>, the threads should work in sync with each other. But the reality is that these threads are out of sync, and because of that, they suffer from a data race problem, which is demonstrated in <a href="#tbl-data-race-not" class="quarto-xref">Table&nbsp;<span>16.2</span></a>.</p>
+<p>Notice that, in the data race scenario (<a href="#tbl-data-race-not" class="quarto-xref">Table&nbsp;<span>16.2</span></a>), the read performed by a thread B happens before the write operation of thread A, and that ultimately leads to wrong results at the end of the program. Because when thread B reads the value of the <code>count</code> variable, thread A is still processing the initial value from <code>count</code>, and has not yet written the new, incremented value back to <code>count</code>. As a result, thread B ends up reading the same initial (or “old”) value from <code>count</code> instead of the updated, incremented value that thread A would have written.</p>
 <div id="tbl-data-race-ideal" class="quarto-float quarto-figure quarto-figure-center anchored">
 <figure class="quarto-float quarto-float-tbl figure">
 <figcaption class="quarto-float-caption-top quarto-float-caption quarto-float-tbl" id="tbl-data-race-ideal-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
@@ -760,13 +760,13 @@ <h3 data-number="16.6.3" class="anchored" data-anchor-id="data-races-and-race-co
 </div>
 </figure>
 </div>
-<p>If you think about these diagrams exposed in form of tables, you will notice that they relate back to our discussion of atomic operations at <a href="#sec-atomic-operation" class="quarto-xref"><span>Section 16.6.2</span></a>. Remember, atomic operations are operations that the CPU executes from beginning to end, without interruptions from other threads or processes. So, the scenario exposed at <a href="#tbl-data-race-ideal" class="quarto-xref">Table&nbsp;<span>16.1</span></a> do not suffer from a data race, because the operations performed by thread A are not interrupted in the middle by the operations from thread B.</p>
-<p>If we also think about the discussion of critical section from <a href="#sec-critical-section" class="quarto-xref"><span>Section 16.6.1</span></a>, we can identify the section that representes the critical section of the program, which is the section that is vulnerable to data race conditions. In this example, the critical section of the program is the line where we increment the <code>counter</code> variable (<code>counter += 1</code>). So, ideally, we want to use a mutex, and lock right before this line, and then, unlock right after this line.</p>
+<p>If you think about these diagrams exposed in form of tables, you will notice that they relate back to our discussion of atomic operations in <a href="#sec-atomic-operation" class="quarto-xref"><span>Section 16.6.2</span></a>. Remember, atomic operations are operations that the CPU executes from beginning to end, without interruptions from other threads or processes. So, the scenario exposed in <a href="#tbl-data-race-ideal" class="quarto-xref">Table&nbsp;<span>16.1</span></a> does not suffer from a data race, because the operations performed by thread A are not interrupted in the middle by the operations from thread B.</p>
+<p>If we also think about the discussion of critical section from <a href="#sec-critical-section" class="quarto-xref"><span>Section 16.6.1</span></a>, we can identify the section that representes the critical section of the program, which is the section that is vulnerable to data race conditions. In this example, the critical section of the program is the line where we increment the <code>counter</code> variable (<code>counter += 1</code>). So, ideally, we want to use a mutex, and lock right before this line, and then unlock right after this line.</p>
 </section>
 <section id="using-mutexes-in-zig" class="level3" data-number="16.6.4">
 <h3 data-number="16.6.4" class="anchored" data-anchor-id="using-mutexes-in-zig"><span class="header-section-number">16.6.4</span> Using mutexes in Zig</h3>
-<p>Now that we know the problem that mutexes seek to solve, we can learn how to use them in Zig. Mutexes in Zig are available through the <code>std.Thread.Mutex</code> struct from the Zig Standard Library. If we take the same code example from the previous example, and improve it with mutexes, to solve our data race problem, we get the code example exposed below.</p>
-<p>Notice that we had this time to alter the <code>increment()</code> function to receive a pointer to the <code>Mutex</code> object as input. All that we need to do, to make this program safe against data race problems, is to call the <code>lock()</code> method at the beginning of the critical section, and then, call <code>unlock()</code> at the end of the critical section. Notice that the output of this program is now the correct number of 200000.</p>
+<p>Now that we know the problem that mutexes seek to solve, we can learn how to use them in Zig. Mutexes in Zig are available through the <code>std.Thread.Mutex</code> struct from the Zig Standard Library. If we take the same code from the previous example, and improve it with mutexes, to solve our data race problem, we get the code example below.</p>
+<p>Notice that this time, we had to alter the <code>increment()</code> function to receive a pointer to the <code>Mutex</code> object as input. All that we need to do, to make this program safe against data race problems, is to call the <code>lock()</code> method at the beginning of the critical section, and then, call <code>unlock()</code> at the end of the critical section. Notice that the output of this program is now the correct number of 200000.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb14"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb14-2"><a href="#cb14-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
@@ -797,31 +797,31 @@ <h3 data-number="16.6.4" class="anchored" data-anchor-id="using-mutexes-in-zig">
 </section>
 <section id="readwrite-locks" class="level2" data-number="16.7">
 <h2 data-number="16.7" class="anchored" data-anchor-id="readwrite-locks"><span class="header-section-number">16.7</span> Read/Write locks</h2>
-<p>Mutexes are normally used when is always not safe to have two or more threads running the same piece of code at the same time. In contrast, read/write locks are normally used in situations where you have a mixture of scenarios, i.e.&nbsp;there are some pieces of the codebase that are safe to run in parallel, and other pieces that are not safe.</p>
-<p>For example, suppose that you have multiple threads that uses the same shared file in the filesystem to store some configurations, or, statistics. If two or more threads try to read the data from this same file at the same time, nothing bad happens. So this part of the codebase is perfectly safe to be executed in parallel, with multiple threads reading the same file at the same time.</p>
-<p>However, if two or more threads try to write data into this same file at the same time, then, we cause some race conditions problems. So this other part of the codebase is not safe to be executed in parallel. More specifically, a thread might end up writing data in the middle of the data written by the other thread. This process of two or more threads writing to the same location, might lead to data corruption. This specific situation is usually called of a <em>torn write</em>.</p>
-<p>Thus, what we can extract from this example is that there is certain types of operations that causes a race condition, but there are also, other types of operations that do not cause a race condition problem. You could also say that, there are types of operations that are susceptible to race condition problems, and there are other types of operations that are not.</p>
-<p>A read/write lock is a type of lock that acknowledges the existance of this specific scenario, and you can use this type of lock to control which parts of the codebase are safe to run in parallel, and which parts are not safe.</p>
+<p>Mutexes are normally used when it’s not always safe for two or more threads running the same piece of code at the same time. In contrast, read/write locks are normally used in situations where you have a mixture of scenarios, i.e., there are some pieces of the codebase that are safe to run in parallel, and other pieces that are not safe.</p>
+<p>For example, suppose that you have multiple threads that uses the same shared file in the filesystem to store some configurations, or statistics. If two or more threads try to read the data from this same file at the same time, nothing bad happens. So this part of the codebase is perfectly safe to be executed in parallel, with multiple threads reading the same file at the same time.</p>
+<p>However, if two or more threads try to write data into this same file at the same time, then we cause some race condition problems. So this other part of the codebase is not safe to be executed in parallel. More specifically, a thread might end up writing data in the middle of the data written by the other thread. This process of two or more threads writing to the same location might lead to data corruption. This specific situation is usually called a <em>torn write</em>.</p>
+<p>Thus, what we can extract from this example is that there are certain types of operations that cause a race condition, but there are also other types of operations that do not cause a race condition problem. You could also say that there are types of operations that are susceptible to race condition problems, and there are other types of operations that are not.</p>
+<p>A read/write lock is a type of lock that acknowledges the existence of this specific scenario, and you can use this type of lock to control which parts of the codebase are safe to run in parallel and which parts are not.</p>
 <section id="exclusive-lock-vs-shared-lock" class="level3" data-number="16.7.1">
 <h3 data-number="16.7.1" class="anchored" data-anchor-id="exclusive-lock-vs-shared-lock"><span class="header-section-number">16.7.1</span> Exclusive lock vs shared lock</h3>
-<p>Therefore, a read/write lock is a little different from a mutex. Because a mutex is always an <em>exclusive lock</em>, meaning that, only one thread is allowed to execute at all times. With an exclusive lock, the other threads are always “excluded”, i.e.&nbsp;they are always blocked from executing. But in a read/write lock, the other threads might be authorized to run at the same time, depending on the type of lock that they acquire.</p>
+<p>Therefore, a read/write lock is a little different from a mutex. Because a mutex is always an <em>exclusive lock</em>, meaning that, only one thread is allowed to execute at all times. With an exclusive lock, the other threads are always “excluded”, i.e., they are always blocked from executing. But in a read/write lock, the other threads might be authorized to run at the same time, depending on the type of lock that they acquire.</p>
 <p>We have two types of locks in a read/write lock, which are: an exclusive lock and a shared lock. An exclusive lock works exactly the same as a mutex, while a shared lock is a lock that does not block the other threads from running at the same time. In the <code>pthreads</code> C library, read/write locks are available through the <code>pthread_rwlock_t</code> C struct. With this C struct, you can create:</p>
 <ul>
 <li>a “write lock”, which corresponds to an exclusive lock.</li>
 <li>a “read lock”, which corresponds to a shared lock.</li>
 </ul>
 <p>The terminology might be a little different compared to Zig. But the meaning is still the same. Therefore, just remember this relationship, write locks are exclusive locks, while read locks are shared locks.</p>
-<p>When a thread tries to acquire a read lock (i.e.&nbsp;a shared lock), this thread get’s the shared lock if, and only if another thread does not currently holds a write lock (i.e.&nbsp;an exclusive lock), and also, if there are no other threads that are already in the queue, waiting for their turn to acquire a write lock. In other words, the thread in the queue have attempted to get a write lock earlier, but this thread was blocked because there was another thread running that already had a write lock. As consequence, this thread is on the queue to get a write lock, and it’s currently waiting for the other thread with a write lock to finish its execution.</p>
-<p>When a thread tries to acquire a read lock, but it fails in acquiring this read lock, either because there is a thread with a write lock already running, or, because there is a thread in the queue to get a write lock, the execution of this thread is instantly blocked, i.e.&nbsp;paused. This thread will indefinitely attempt to get the read lock, and its execution will be unblocked (or unpaused) only after this thread successfully acquires the read lock.</p>
-<p>If you think deeply about this dynamic between read locks versus write locks, you might notice that a read lock is basically a safety mechanism. More specifically, it is a way for us to allow a particular thread to run together with the other threads, only when it’s safe to. In other words, if there is currently a thread with a write lock running, then, it is very likely not safe for the thread that is trying to acquire the read lock to run now. As consequence, the read lock protects this thread from running into dangerous waters, and patiently waits for the “write lock” thread to finishes its tasks before it continues.</p>
-<p>On the other hand, if there are only “read lock” (i.e.&nbsp;“shared lock”) threads currently running (i.e.&nbsp;not a single “write lock” thread currently exists), then, is perfectly safe for this thread that is acquiring the read lock to run in parallel with the other threads. As a result, the read lock just allows for this thread to run together with the other threads.</p>
+<p>When a thread tries to acquire a read lock (i.e., a shared lock), this thread gets the shared lock if and only if another thread does not currently hold a write lock (i.e., an exclusive lock), and also if there are no other threads already in the queue, waiting for their turn to acquire a write lock. In other words, the thread in the queue has attempted to get a write lock earlier, but this thread was blocked because there was another thread running that already had a write lock. As a consequence, this thread is in the queue to get a write lock, and it’s currently waiting for the other thread with a write lock to finish its execution.</p>
+<p>When a thread tries to acquire a read lock, but it fails in acquiring this read lock, either because there is a thread with a write lock already running, or because there is a thread in the queue to get a write lock, the execution of this thread is instantly blocked, i.e., paused. This thread will indefinitely attempt to get the read lock, and its execution will be unblocked (or unpaused) only after this thread successfully acquires the read lock.</p>
+<p>If you think deeply about this dynamic between read locks versus write locks, you might notice that a read lock is basically a safety mechanism. More specifically, it’s a way for us to allow a particular thread to run together with the other threads only when it’s safe to. In other words, if there is currently a thread with a write lock running, then it’s very likely not safe for the thread that is trying to acquire the read lock to run now. As a consequence, the read lock protects this thread from running into dangerous waters, and patiently waits for the “write lock” thread to finishes its tasks before it continues.</p>
+<p>On the other hand, if there are only “read lock” (i.e., “shared lock”) threads currently running (i.e., not a single “write lock” thread currently exists), then it is perfectly safe for this thread that is acquiring the read lock to run in parallel with the other threads. As a result, the read lock just allows for this thread to run together with the other threads.</p>
 <p>Thus, by using read locks (shared locks) in conjunction with write locks (exclusive locks), we can control which regions or sections of our multithreaded code is safe to have parallelism, and which sections are not safe to have parallelism.</p>
 </section>
 <section id="using-readwrite-locks-in-zig" class="level3" data-number="16.7.2">
 <h3 data-number="16.7.2" class="anchored" data-anchor-id="using-readwrite-locks-in-zig"><span class="header-section-number">16.7.2</span> Using read/write locks in Zig</h3>
-<p>The Zig Standard Library supports read/write locks through the <code>std.Thread.RwLock</code> module. If you want to a particular thread to acquire a shared lock (i.e.&nbsp;a read lock), you should call the <code>lockShared()</code> method from the <code>RwLock</code> object. But, if you want for this thread to acquire an exclusive lock (i.e.&nbsp;a write lock) instead, then, you should call the <code>lock()</code> method from the <code>RwLock</code> object.</p>
+<p>The Zig Standard Library supports read/write locks through the <code>std.Thread.RwLock</code> module. If you want a particular thread to acquire a shared lock (i.e., a read lock), you should call the <code>lockShared()</code> method from the <code>RwLock</code> object. But, if you want this thread to acquire an exclusive lock (i.e., a write lock) instead, then you should call the <code>lock()</code> method from the <code>RwLock</code> object.</p>
 <p>As with mutexes, we also have to unlock the shared or exclusive locks that we acquire through a read/write lock object, once we are at the end of our “critical section”. If you have acquired an exclusive lock, then, you unlock this exclusive lock by calling the <code>unlock()</code> method from the read/write lock object. In contrast, if you have acquired a shared lock instead, then, call <code>unlockShared()</code> to unlock this shared lock.</p>
-<p>As a simple example, the snippet exposed below creates three separate threads responsible for reading the current value in a <code>counter</code> object, and it also creates another thread, responsible for writing new data into the <code>counter</code> object (incrementing it, more specifically).</p>
+<p>As a simple example, the snippet below creates three separate threads responsible for reading the current value in a <code>counter</code> object, and it also creates another thread responsible for writing new data into the <code>counter</code> object (incrementing it, more specifically).</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb16"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> counter: <span class="dt">u32</span> = <span class="dv">0</span>;</span>
 <span id="cb16-2"><a href="#cb16-2" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> reader(lock: *RwLock) !<span class="dt">void</span> <span class="op">{</span></span>
@@ -859,9 +859,9 @@ <h3 data-number="16.7.2" class="anchored" data-anchor-id="using-readwrite-locks-
 </section>
 <section id="yielding-a-thread" class="level2" data-number="16.8">
 <h2 data-number="16.8" class="anchored" data-anchor-id="yielding-a-thread"><span class="header-section-number">16.8</span> Yielding a thread</h2>
-<p>The <code>Thread</code> struct supports yielding through the <code>yield()</code> method. Yielding a thread means that the execution of the thread is temporarily stopped, and the thread comes back to the end of the queue of priority of the scheduler from your operating system.</p>
+<p>The <code>Thread</code> struct supports yielding through the <code>yield()</code> method. Yielding a thread means that the execution of the thread is temporarily stopped, and it moves to the end of the priority queue managed by the scheduler of your operating system.</p>
 <p>That is, when you yield a thread, you are essentially saying the following to your OS: “Hey! Could you please stop executing this thread for now, and comeback to continue it later?”. You could also interpret this yield operation as: “Could you please deprioritize this thread, to focus on doing other things instead?”. So this yield operation is also a way for you to stop a particular thread, so that you can work and prioritize other threads instead.</p>
-<p>Is important to say that, yielding a thread is a “not so common” thread operation these days. In other words, not many programmers use yielding in production, simply because is hard to use this operation and make it work properly, and also, there are better alternatives. Most programmers prefer to use <code>join()</code> instead. In fact, most of the times, when you see somebody using this “yield” operation in some code example, they are mostly using it to help them debug race conditions in their applications. That is, this “yield” operation is mostly used as a debug tool nowadays.</p>
+<p>It’s important to say that, yielding a thread is a “not so common” thread operation these days. In other words, not many programmers use yielding in production, simply because it’s hard to use this operation and make it work properly, and also, there are better alternatives. Most programmers prefer to use <code>join()</code> instead. In fact, most of the time, when you see someone using this “yield” operation in some code example, they are usually doing so to help debug race conditions in their applications. That is, this “yield” operation is mostly used as a debug tool nowadays.</p>
 <p>Anyway, if you want to yield a thread, just call the <code>yield()</code> method from it, like this:</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb17"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true" tabindex="-1"></a>thread.yield();</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
@@ -874,8 +874,8 @@ <h3 data-number="16.9.1" class="anchored" data-anchor-id="deadlocks"><span class
 <p>A deadlock occurs when two or more threads are blocked forever, waiting for each other to release a resource. This usually happens when multiple locks are involved, and the order of acquiring them is not well managed.</p>
 <p>The code example below demonstrates a deadlock situation. We have two different threads that execute two different functions (<code>work1()</code> and <code>work2()</code>) in this example. And we also have two separate mutexes. If you compile and run this code example, you will notice that the program just runs indefinitely, without ending.</p>
 <p>When we look into the first thread, which executes the <code>work1()</code> function, we can notice that this function acquires the <code>mut1</code> lock first. Because this is the first operation that is executed inside this thread, which is the first thread created in the program. After that, the function sleeps for 1 second, to simulate some type of work, and then, the function tries to acquire the <code>mut2</code> lock.</p>
-<p>On the other hand, when we look into the second thread, which executes the <code>work2()</code> function, we can see that this function acquires the <code>mut2</code> lock first. Because when this thread get’s created and it tries to acquire this <code>mut2</code> lock, the first thread is still sleeping on that “sleep 1 second” line. After acquiring <code>mut2</code>, the <code>work2()</code> function also sleeps for 1 second, to simulate some type of work, and then, the function tries to acquire the <code>mut1</code> lock.</p>
-<p>This creates a deadlock situation, because after the “sleep for 1 second” line in both threads, the thread 1 is trying to acquire the <code>mut2</code> lock, but this lock is currently being used by thread 2. However, at this moment, the thread 2 is also trying to acquire the <code>mut1</code> lock, which is currently being used by thread 1. Therefore, both threads end up waiting for ever. Waiting for their peer to free the lock that they want to acquire.</p>
+<p>On the other hand, when we look into the second thread, which executes the <code>work2()</code> function, we can see that this function acquires the <code>mut2</code> lock first. Because when this thread gets created and it tries to acquire this <code>mut2</code> lock, the first thread is still sleeping on that “sleep 1 second” line. After acquiring <code>mut2</code>, the <code>work2()</code> function also sleeps for 1 second, to simulate some type of work, and then the function tries to acquire the <code>mut1</code> lock.</p>
+<p>This creates a deadlock situation, because after the “sleep for 1 second” line in both threads, thread 1 is trying to acquire the <code>mut2</code> lock, but this lock is currently being used by thread 2. However, at this moment, thread 2 is also trying to acquire the <code>mut1</code> lock, which is currently being used by thread 1. Therefore, both threads end up waiting for ever. Waiting for their peer to free the lock that they want to acquire.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb18"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb18-1"><a href="#cb18-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> mut1: Mutex = .<span class="op">{}</span>; <span class="kw">var</span> mut2: Mutex = .<span class="op">{}</span>;</span>
 <span id="cb18-2"><a href="#cb18-2" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> work1() !<span class="dt">void</span> <span class="op">{</span></span>
@@ -904,14 +904,14 @@ <h3 data-number="16.9.1" class="anchored" data-anchor-id="deadlocks"><span class
 </section>
 <section id="sec-not-call-join-detach" class="level3" data-number="16.9.2">
 <h3 data-number="16.9.2" class="anchored" data-anchor-id="sec-not-call-join-detach"><span class="header-section-number">16.9.2</span> Not calling <code>join()</code> or <code>detach()</code></h3>
-<p>When you do not call either <code>join()</code> or <code>detach()</code> over a thread, then, this thread becomes a “zombie thread”, because it does not have a clear “return point”. You could also interpret this as: “nobody is properly responsible for managing the thread”. When we don’t establish if a thread is either <em>joinable</em> or <em>detached</em>, nobody becomes responsible for dealing with the return value of this thread, and also, nobody becomes responsible for clearing (or freeing) the resources associated with this thread.</p>
-<p>You don’t want to be in this situation, so remember to always use <code>join()</code> or <code>detach()</code> on the threads that you create. When you don’t use one of these methods, we lose control over the thread, and its resources are never freed (i.e.&nbsp;you have leaked resources in the system).</p>
+<p>When you do not call either <code>join()</code> or <code>detach()</code> over a thread, then this thread becomes a “zombie thread”, because it does not have a clear “return point”. You could also interpret this as: “nobody is properly responsible for managing the thread”. When we don’t establish if a thread is either <em>joinable</em> or <em>detached</em>, nobody becomes responsible for dealing with the return value of this thread, and also, nobody becomes responsible for clearing (or freeing) the resources associated with this thread.</p>
+<p>You don’t want to be in this situation, so remember to always use <code>join()</code> or <code>detach()</code> on the threads that you create. When you don’t use one of these methods, we lose control over the thread, and its resources are never freed (i.e., you have leaked resources in the system).</p>
 </section>
 <section id="cancelling-or-killing-a-particular-thread" class="level3" data-number="16.9.3">
 <h3 data-number="16.9.3" class="anchored" data-anchor-id="cancelling-or-killing-a-particular-thread"><span class="header-section-number">16.9.3</span> Cancelling or killing a particular thread</h3>
-<p>When we think about the <code>pthreads</code> C library, there is a possible way to asynchronously kill or cancel a thread, which is by sending a <code>SIGTERM</code> signal to the thread through the <code>pthread_kill()</code> function. But canceling a thread like this is bad. Is dangerously bad. As consequence, the Zig implementation of threads does not have a similar function, or, a similar way to asynchronously cancel or kill a thread.</p>
-<p>Therefore, if you want to cancel a thread in the middle of its execution in Zig, then, one good strategy that you can take is to use control flow in conjunction with <code>join()</code>. More specifically, you can design your thread around a while loop, that is constantly checking if the thread should continue running. If is time to cancel the thread, we could make the while loop break, and join the thread with the main thread by calling <code>join()</code>.</p>
-<p>The code example below demonstrates to some extent this strategy. Here, we are using control flow to break the while loop, and exit the thread earlier than what we have initially planned to. This example also demonstrates how can we use atomic objects in Zig with the <code>Value()</code> generic function that we have mentioned at <a href="#sec-atomic-operation" class="quarto-xref"><span>Section 16.6.2</span></a>.</p>
+<p>When we think about the <code>pthreads</code> C library, there is a possible way to asynchronously kill or cancel a thread, which is by sending a <code>SIGTERM</code> signal to the thread through the <code>pthread_kill()</code> function. But canceling a thread like this is bad. It’s dangerously bad. As a consequence, the Zig implementation of threads does not have a similar function, or, a similar way to asynchronously cancel or kill a thread.</p>
+<p>Therefore, if you want to cancel a thread in the middle of its execution in Zig, then one good strategy that you can take is to use control flow in conjunction with <code>join()</code>. More specifically, you can design your thread around a while loop that is constantly checking if the thread should continue running. If it’s time to cancel the thread, we could make the while loop break, and join the thread with the main thread by calling <code>join()</code>.</p>
+<p>The code example below demonstrates to some extent this strategy. Here, we are using control flow to break the while loop, and exit the thread earlier than what we have initially planned to. This example also demonstrates how can we use atomic objects in Zig with the <code>Value()</code> generic function that we have mentioned in <a href="#sec-atomic-operation" class="quarto-xref"><span>Section 16.6.2</span></a>.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb19"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb19-1"><a href="#cb19-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb19-2"><a href="#cb19-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Thread = std.Thread;</span>
diff --git a/docs/Chapters/14-zig-c-interop.html b/docs/Chapters/14-zig-c-interop.html
index 50c66ae8..6cfe4421 100644
--- a/docs/Chapters/14-zig-c-interop.html
+++ b/docs/Chapters/14-zig-c-interop.html
@@ -320,11 +320,11 @@ <h1 class="title"><span class="chapter-number">14</span>&nbsp; <span class="chap
 </header>
 
 
-<p>In this chapter, we are going to discuss the interoperability of Zig with C. We have discussed at <a href="07-build-system.html#sec-building-c-code" class="quarto-xref"><span>Section 9.11</span></a> how you can use the <code>zig</code> compiler to build C code. But we haven’t discussed yet how to actually use C code in Zig. In other words, we haven’t discussed yet how to call and use C code from Zig.</p>
+<p>In this chapter, we are going to discuss the interoperability of Zig with C. We have discussed in <a href="07-build-system.html#sec-building-c-code" class="quarto-xref"><span>Section 9.11</span></a> how you can use the <code>zig</code> compiler to build C code. But we haven’t discussed yet how to actually use C code in Zig. In other words, we haven’t discussed yet how to call and use C code from Zig.</p>
 <p>This is the main subject of this chapter. Also, in our next small project in this book, we are going to use a C library in it. As consequence, we will put in practice a lot of the knowledge discussed here on this next project.</p>
 <section id="how-to-call-c-code-from-zig" class="level2" data-number="14.1">
 <h2 data-number="14.1" class="anchored" data-anchor-id="how-to-call-c-code-from-zig"><span class="header-section-number">14.1</span> How to call C code from Zig</h2>
-<p>Interoperability with C is not something new. Most high-level programming languages have FFI (foreign function interfaces), which can be used to call C code. For example, Python have Cython, R have <code>.Call()</code>, Javascript have <code>ccall()</code>, etc. But Zig integrates with C in a deeper level, which affects not only the way that C code get’s called, but also, how this C code is compiled and incorporated into your Zig project.</p>
+<p>Interoperability with C is not something new. Most high-level programming languages have FFI (foreign function interfaces), which can be used to call C code. For example, Python have Cython, R have <code>.Call()</code>, Javascript have <code>ccall()</code>, etc. But Zig integrates with C in a deeper level, which affects not only the way that C code gets called, but also, how this C code is compiled and incorporated into your Zig project.</p>
 <p>In summary, Zig have great interoperability with C. If you want to call any C code from Zig, you have to perform the following steps:</p>
 <ul>
 <li>import a C header file into your Zig code.</li>
@@ -353,7 +353,7 @@ <h3 data-number="14.1.2" class="anchored" data-anchor-id="sec-linking-c"><span c
 </section>
 <section id="sec-import-c-header" class="level2" data-number="14.2">
 <h2 data-number="14.2" class="anchored" data-anchor-id="sec-import-c-header"><span class="header-section-number">14.2</span> Importing C header files</h2>
-<p>At <a href="#sec-strategy-c" class="quarto-xref"><span>Section 14.1.1</span></a>, we have described that, currently, there are two different paths that you can take to import a C header file into your Zig modules, <code>translate-c</code> or <code>@cImport()</code>. This section describes each strategy separately in more details.</p>
+<p>In <a href="#sec-strategy-c" class="quarto-xref"><span>Section 14.1.1</span></a>, we have described that, currently, there are two different paths that you can take to import a C header file into your Zig modules, <code>translate-c</code> or <code>@cImport()</code>. This section describes each strategy separately in more details.</p>
 <section id="strategy-1-using-translate-c" class="level3" data-number="14.2.1">
 <h3 data-number="14.2.1" class="anchored" data-anchor-id="strategy-1-using-translate-c"><span class="header-section-number">14.2.1</span> Strategy 1: using <code>translate-c</code></h3>
 <p>When we choose this strategy, we first need to use the <code>translate-c</code> tool to translate the C header files that we want to use into Zig code. For example, suppose we wanted to use the <code>fopen()</code> C function from the <code>stdio.h</code> C header file. We can translate the <code>stdio.h</code> C header file through the bash command below:</p>
@@ -361,7 +361,7 @@ <h3 data-number="14.2.1" class="anchored" data-anchor-id="strategy-1-using-trans
 <span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a>    <span class="at">-lc</span> <span class="at">-I</span>/usr/include <span class="dt">\</span></span>
 <span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a>    <span class="at">-D_NO_CRT_STDIO_INLINE</span><span class="op">=</span>1 <span class="op">&gt;</span> c.zig <span class="dt">\</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <p>Notice that, in this bash command, we are passing the necessary compiler flags (<code>-D</code> to define macros, <code>-l</code> to link libraries, <code>-I</code> to add an “include path”) to compile and use the <code>stdio.h</code> header file. Also notice that we are saving the results of the translation process inside a Zig module called <code>c.zig</code>.</p>
-<p>Therefore, after running this command, all we have to do is to import this <code>c.zig</code> module, and start calling the C functions that you want to call from it. The example below demonstrates that. Is important to remember what we’ve discussed at <a href="#sec-linking-c" class="quarto-xref"><span>Section 14.1.2</span></a>. In order to compile this example you have to link this code with <code>libc</code>, by passing the flag <code>-lc</code> to the <code>zig</code> compiler.</p>
+<p>Therefore, after running this command, all we have to do is to import this <code>c.zig</code> module, and start calling the C functions that you want to call from it. The example below demonstrates that. It’s important to remember what we’ve discussed in <a href="#sec-linking-c" class="quarto-xref"><span>Section 14.1.2</span></a>. In order to compile this example you have to link this code with <code>libc</code>, by passing the flag <code>-lc</code> to the <code>zig</code> compiler.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb2"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> c = <span class="bu">@import</span>(<span class="st">"c.zig"</span>);</span>
 <span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
@@ -395,19 +395,19 @@ <h3 data-number="14.2.2" class="anchored" data-anchor-id="strategy-2-using-cimpo
 </section>
 <section id="sec-zig-obj-to-c" class="level2" data-number="14.3">
 <h2 data-number="14.3" class="anchored" data-anchor-id="sec-zig-obj-to-c"><span class="header-section-number">14.3</span> About passing Zig values to C functions</h2>
-<p>Zig objects have some intrinsic differences between their C equivalents. Probably the most noticeable one is the difference between C strings and Zig strings, which I described at <a href="01-zig-weird.html#sec-zig-strings" class="quarto-xref"><span>Section 1.8</span></a>. Zig strings are objects that contains both an array of arbitrary bytes and a length value. On the other hand, a C string is usually just a pointer to a null-terminated array of arbitrary bytes.</p>
+<p>Zig objects have some intrinsic differences between their C equivalents. Probably the most noticeable one is the difference between C strings and Zig strings, which I described in <a href="01-zig-weird.html#sec-zig-strings" class="quarto-xref"><span>Section 1.8</span></a>. Zig strings are objects that contains both an array of arbitrary bytes and a length value. On the other hand, a C string is usually just a pointer to a null-terminated array of arbitrary bytes.</p>
 <p>Because of these intrinsic differences, in some specific cases, you cannot pass Zig objects directly as inputs to C functions before you convert them into C compatible values. However, in some other cases, you are allowed to pass Zig objects and Zig literal values directly as inputs to C functions, and everything will work just fine, because the <code>zig</code> compiler will handle everything for you.</p>
 <p>So we have two different scenarios being described here. Let’s call them “auto-conversion” and “need-conversion”. The “auto-conversion” scenario is when the <code>zig</code> compiler handles everything for you, and automatically convert your Zig objects/values into C compatible values. In contrast, the “need-conversion” scenario is when you, the programmer, have the responsibility of converting that Zig object into a C compatible value, before passing it to C code.</p>
-<p>There is also a third scenario that is not being described here, which is when you create a C object, or, a C struct, or a C compatible value in your Zig code, and you pass this C object/value as input to a C function in your Zig code. This scenario will be described later at <a href="#sec-c-inputs" class="quarto-xref"><span>Section 14.4</span></a>. In this section, we are focused on the scenarios where we are passing Zig objects/values to C code, instead of C objects/values being passed to C code.</p>
+<p>There is also a third scenario that is not being described here, which is when you create a C object, or, a C struct, or a C compatible value in your Zig code, and you pass this C object/value as input to a C function in your Zig code. This scenario will be described later in <a href="#sec-c-inputs" class="quarto-xref"><span>Section 14.4</span></a>. In this section, we are focused on the scenarios where we are passing Zig objects/values to C code, instead of C objects/values being passed to C code.</p>
 <section id="the-auto-conversion-scenario" class="level3" data-number="14.3.1">
 <h3 data-number="14.3.1" class="anchored" data-anchor-id="the-auto-conversion-scenario"><span class="header-section-number">14.3.1</span> The “auto-conversion” scenario</h3>
 <p>An “auto-conversion” scenario is when the <code>zig</code> compiler automatically converts our Zig objects into C compatible values for us. This specific scenario happens mostly in two instances:</p>
 <ul>
 <li>with string literal values;</li>
-<li>with any of the primitive data types that were introduced at <a href="01-zig-weird.html#sec-primitive-data-types" class="quarto-xref"><span>Section 1.5</span></a>.</li>
+<li>with any of the primitive data types that were introduced in <a href="01-zig-weird.html#sec-primitive-data-types" class="quarto-xref"><span>Section 1.5</span></a>.</li>
 </ul>
 <p>When we think about the second instance described above, the <code>zig</code> compiler does automatically convert any of the primitive data types into their C equivalents, because the compiler knows how to properly convert a <code>i16</code> into a <code>signed short</code>, or, a <code>u8</code> into a <code>unsigned char</code>, etc. Now, when we think about string literal values, they can be automatically converted into C strings as well, especially because the <code>zig</code> compiler does not forces a specific Zig data type into a string literal at first glance, unless you store this string literal into a Zig object, and explicitly annotate the data type of this object.</p>
-<p>Thus, with string literal values, the <code>zig</code> compiler have more freedom to infer which is the appropriate data type to be used in each situation. You could say that the string literal value “inherits its data type” depending on the context that it is used. Most of the times, this data type is going to be the type that we commonly associate with Zig strings (<code>[]const u8</code>). But it might be a different type depending on the situation. When the <code>zig</code> compiler detects that you are providing a string literal value as input to some C function, the compiler automatically interprets this string literal as a C string value.</p>
+<p>Thus, with string literal values, the <code>zig</code> compiler has more freedom to infer which is the appropriate data type to be used in each situation. You could say that the string literal value “inherits its data type” depending on the context that it’s used in. Most of the times, this data type is going to be the type that we commonly associate with Zig strings (<code>[]const u8</code>). But it might be a different type depending on the situation. When the <code>zig</code> compiler detects that you are providing a string literal value as input to some C function, the compiler automatically interprets this string literal as a C string value.</p>
 <p>As an example, look at the code exposed below. Here we are using the <code>fopen()</code> C function to simply open and close a file. If you do not know how this <code>fopen()</code> function works in C, it takes two C strings as input. But in this code example below, we are passing some string literals written in our Zig code directly as inputs to this <code>fopen()</code> C function.</p>
 <p>In other words, we are not doing any conversion from a Zig string to a C string. We are just passing the Zig string literals directly as inputs to the C function. And it works just fine! Because the compiler interprets the string <code>"foo.txt"</code> as a C string given the current context.</p>
 <div class="cell">
@@ -444,7 +444,7 @@ <h3 data-number="14.3.1" class="anchored" data-anchor-id="the-auto-conversion-sc
     const file = c.fopen(path, "rb");
                          ^~~~</code></pre>
 <p>Therefore, when we talk exclusively about string literal values, as long as you don’t give an explicit data type to these string literal values, the <code>zig</code> compiler should be capable of automatically converting them into C strings as needed.</p>
-<p>But what about using one of the primitive data types that were introduced at <a href="01-zig-weird.html#sec-primitive-data-types" class="quarto-xref"><span>Section 1.5</span></a>? Let’s take code exposed below as an example of that. Here, we are giving some float literal values as input to the C function <code>powf()</code>. Notice that this code example compiles and runs successfully.</p>
+<p>But what about using one of the primitive data types that were introduced in <a href="01-zig-weird.html#sec-primitive-data-types" class="quarto-xref"><span>Section 1.5</span></a>? Let’s take code exposed below as an example of that. Here, we are giving some float literal values as input to the C function <code>powf()</code>. Notice that this code example compiles and runs successfully.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb10"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb10-2"><a href="#cb10-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
@@ -485,8 +485,8 @@ <h3 data-number="14.3.2" class="anchored" data-anchor-id="the-need-conversion-sc
 <span id="cb16-2"><a href="#cb16-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> file = c.fopen(path.ptr, <span class="st">"rb"</span>);</span>
 <span id="cb16-3"><a href="#cb16-3" aria-hidden="true" tabindex="-1"></a>    <span class="co">// Remainder of the program</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>This strategy works because this pointer to the underlying array found in the <code>ptr</code> property, is semantically identical to a C pointer to an array of bytes, i.e.&nbsp;a C object of type <code>*unsigned char</code>. This is why this option also solves the problem of converting the Zig string into a C string.</p>
-<p>Another option is to explicitly convert the Zig string object into a C pointer by using the built-in function <code>@ptrCast()</code>. With this function we can convert an object of type <code>[]const u8</code> into an object of type <code>[*c]const u8</code>. As I described at the previous section, the <code>[*c]</code> portion of the type means that it is a C pointer. This strategy is not-recommended. But it is useful to demonstrate the use of <code>@ptrCast()</code>.</p>
+<p>This strategy works because this pointer to the underlying array found in the <code>ptr</code> property, is semantically identical to a C pointer to an array of bytes, i.e., a C object of type <code>*unsigned char</code>. This is why this option also solves the problem of converting the Zig string into a C string.</p>
+<p>Another option is to explicitly convert the Zig string object into a C pointer by using the built-in function <code>@ptrCast()</code>. With this function we can convert an object of type <code>[]const u8</code> into an object of type <code>[*c]const u8</code>. As I described at the previous section, the <code>[*c]</code> portion of the type means that it’s a C pointer. This strategy is not-recommended. But it’s useful to demonstrate the use of <code>@ptrCast()</code>.</p>
 <p>You may recall of <code>@as()</code> and <code>@ptrCast()</code> from <a href="03-structs.html#sec-type-cast" class="quarto-xref"><span>Section 2.5</span></a>. Just as a recap, the <code>@as()</code> built-in function is used to explicitly convert (or cast) a Zig value from a type “x” into a value of type “y”. But in our case here, we are converting a pointer object. Everytime a pointer is involved in some “type casting operation” in Zig, the <code>@ptrCast()</code> function is involved.</p>
 <p>In the example below, we are using this function to cast our <code>path</code> object into a C pointer to an array of bytes. Then, we pass this C pointer as input to the <code>fopen()</code> function. Notice that this code example compiles successfully with no errors.</p>
 <div class="cell">
@@ -499,7 +499,7 @@ <h3 data-number="14.3.2" class="anchored" data-anchor-id="the-need-conversion-sc
 </section>
 <section id="sec-c-inputs" class="level2" data-number="14.4">
 <h2 data-number="14.4" class="anchored" data-anchor-id="sec-c-inputs"><span class="header-section-number">14.4</span> Creating C objects in Zig</h2>
-<p>Creating C objects, or, in other words, creating instances of C structs in your Zig code is actually something quite easy to do. You first need to import the C header file (like I described at <a href="#sec-import-c-header" class="quarto-xref"><span>Section 14.2</span></a>) that defines the C struct that you are trying to instantiate in your Zig code. After that, you can just create a new object in your Zig code, and annotate it with the data type of the C struct.</p>
+<p>Creating C objects, or, in other words, creating instances of C structs in your Zig code is actually something quite easy to do. You first need to import the C header file (like I described in <a href="#sec-import-c-header" class="quarto-xref"><span>Section 14.2</span></a>) that defines the C struct that you are trying to instantiate in your Zig code. After that, you can just create a new object in your Zig code, and annotate it with the data type of the C struct.</p>
 <p>For example, suppose we have a C header file called <code>user.h</code>, and that this header file is declaring a new struct named <code>User</code>. This C header file is exposed below:</p>
 <div class="sourceCode" id="cb18"><pre class="sourceCode c code-with-copy"><code class="sourceCode c"><span id="cb18-1"><a href="#cb18-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im">&lt;stdint.h&gt;</span></span>
 <span id="cb18-2"><a href="#cb18-2" aria-hidden="true" tabindex="-1"></a></span>
@@ -508,8 +508,8 @@ <h2 data-number="14.4" class="anchored" data-anchor-id="sec-c-inputs"><span clas
 <span id="cb18-5"><a href="#cb18-5" aria-hidden="true" tabindex="-1"></a>    <span class="dt">char</span><span class="op">*</span> name<span class="op">;</span></span>
 <span id="cb18-6"><a href="#cb18-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span> User<span class="op">;</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <p>This <code>User</code> C struct have two distinct fields, or two struct members, named <code>id</code> and <code>name</code>. The field <code>id</code> is an unsigned 64-bit integer value, while the field <code>name</code> is just a standard C string. Now, suppose that I want to create an instance of this <code>User</code> struct in my Zig code. I can do that by importing this <code>user.h</code> header file into my Zig code, and creating a new object with type <code>User</code>. These steps are reproduced in the code example below.</p>
-<p>Notice that I have used the keyword <code>undefined</code> in this example. This allows me to create the <code>new_user</code> object without the need to provide an initial value to the object. As consequence, the underlying memory associated with this <code>new_user</code> object is uninitialized, i.e.&nbsp;the memory is currently populated with “garbage” values. Thus, this expression have the exact same effect of the expression <code>User new_user;</code> in C, which means “declare a new object named <code>new_user</code> of type <code>User</code>”.</p>
-<p>Is our responsibility to properly initialize this memory associated with this <code>new_user</code> object, by assigning valid values to the members (or the fields) of the C struct. In the example below, I’m assigning the integer 1 to the member <code>id</code>. I am also saving the string <code>"pedropark99"</code> into the member <code>name</code>. Notice in this example that I manually add the null character (zero byte) to the end of the allocated array for this string. This null character marks the end of the array in C.</p>
+<p>Notice that I have used the keyword <code>undefined</code> in this example. This allows me to create the <code>new_user</code> object without the need to provide an initial value to the object. As consequence, the underlying memory associated with this <code>new_user</code> object is uninitialized, i.e., the memory is currently populated with “garbage” values. Thus, this expression have the exact same effect of the expression <code>User new_user;</code> in C, which means “declare a new object named <code>new_user</code> of type <code>User</code>”.</p>
+<p>It’s our responsibility to properly initialize this memory associated with this <code>new_user</code> object, by assigning valid values to the members (or the fields) of the C struct. In the example below, I’m assigning the integer 1 to the member <code>id</code>. I am also saving the string <code>"pedropark99"</code> into the member <code>name</code>. Notice in this example that I manually add the null character (zero byte) to the end of the allocated array for this string. This null character marks the end of the array in C.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb19"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb19-1"><a href="#cb19-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb19-2"><a href="#cb19-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
@@ -544,9 +544,9 @@ <h2 data-number="14.4" class="anchored" data-anchor-id="sec-c-inputs"><span clas
 </section>
 <section id="sec-pass-c-structs" class="level2" data-number="14.5">
 <h2 data-number="14.5" class="anchored" data-anchor-id="sec-pass-c-structs"><span class="header-section-number">14.5</span> Passing C structs across Zig functions</h2>
-<p>Now that we have learned how to create/declare C objects in our Zig code, we need to learn how to pass these C objects as inputs to Zig functions. As I described at <a href="#sec-c-inputs" class="quarto-xref"><span>Section 14.4</span></a>, we can freely pass these C objects as inputs to C code that we call from our Zig code. But what about passing these C objects to Zig functions?</p>
+<p>Now that we have learned how to create/declare C objects in our Zig code, we need to learn how to pass these C objects as inputs to Zig functions. As I described in <a href="#sec-c-inputs" class="quarto-xref"><span>Section 14.4</span></a>, we can freely pass these C objects as inputs to C code that we call from our Zig code. But what about passing these C objects to Zig functions?</p>
 <p>In essence, this specific case requires one small adjustment in the Zig function declaration. All you need to do, is to make sure that you pass your C object <em>by reference</em> to the function, instead of passing it <em>by value</em>. To do that, you have to annotate the data type of the function argument that is receiving this C object as “a pointer to the C struct”, instead of annotating it as “an instance of the C struct”.</p>
-<p>Let’s consider the C struct <code>User</code> from the <code>user.h</code> C header file that we have used at <a href="#sec-c-inputs" class="quarto-xref"><span>Section 14.4</span></a>. Now, consider that we want to create a Zig function that sets the value of the <code>id</code> field in this C struct, like the <code>set_user_id()</code> function declared below. Notice that the <code>user</code> argument in this function is annotated as a pointer (<code>*</code>) to a <code>c.User</code> object.</p>
+<p>Let’s consider the C struct <code>User</code> from the <code>user.h</code> C header file that we have used in <a href="#sec-c-inputs" class="quarto-xref"><span>Section 14.4</span></a>. Now, consider that we want to create a Zig function that sets the value of the <code>id</code> field in this C struct, like the <code>set_user_id()</code> function declared below. Notice that the <code>user</code> argument in this function is annotated as a pointer (<code>*</code>) to a <code>c.User</code> object.</p>
 <p>Therefore, all you have to do when passing C objects to Zig functions, is to add <code>*</code> to the data type of the function argument that is receiving the C object. This will make sure that the C object is passed <em>by reference</em> to the function.</p>
 <p>Because we have transformed the function argument into a pointer, everytime that you have to access the value pointed by this input pointer inside the function body, for whatever reason (e.g.&nbsp;you want to read, update, or delete this value), you have to dereference the pointer with the <code>.*</code> syntax that we learned from <a href="05-pointers.html" class="quarto-xref"><span>Chapter 6</span></a>. Notice that the <code>set_user_id()</code> function is using this syntax to alter the value in the <code>id</code> field of the <code>User</code> struct pointed by the input pointer.</p>
 <div class="cell">
diff --git a/docs/Chapters/15-vectors.html b/docs/Chapters/15-vectors.html
index 8a8d01dd..708d14bb 100644
--- a/docs/Chapters/15-vectors.html
+++ b/docs/Chapters/15-vectors.html
@@ -339,12 +339,12 @@ <h1 class="title"><span id="sec-vectors-simd" class="quarto-section-identifier">
 </header>
 
 
-<p>In this chapter, I want to discuss vectors in Zig, which are related to SIMD operations (i.e.&nbsp;they have no relationship with the <code>std::vector</code> class from C++).</p>
+<p>In this chapter, I want to discuss vectors in Zig, which are related to SIMD operations (i.e., they have no relationship with the <code>std::vector</code> class from C++).</p>
 <section id="what-is-simd" class="level2" data-number="17.1">
 <h2 data-number="17.1" class="anchored" data-anchor-id="what-is-simd"><span class="header-section-number">17.1</span> What is SIMD?</h2>
 <p>SIMD (<em>Single Instruction/Multiple Data</em>) is a group of operations that are widely used on video/audio editing programs, and also in graphics applications. SIMD is not a new technology, but the massive use of SIMD on normal desktop computers is somewhat recent. In the old days, SIMD was only used on “supercomputer models”.</p>
-<p>Most modern CPU models (from AMD, Intel, etc.) these days (either in a desktop or in a notebook model) have support for SIMD operations. So, if you have a very old CPU model installed in your computer, then, is possible that you have no support for SIMD operations in your computer.</p>
-<p>Why people have started using SIMD on their software? The answer is performance. But what SIMD precisely do to achieve better performance? Well, in essence, SIMD operations are a different strategy to get parallel computing in your program, and therefore, make faster calculations.</p>
+<p>Most modern CPU models (from AMD, Intel, etc.) these days (either in a desktop or in a notebook model) have support for SIMD operations. So, if you have a very old CPU model installed in your computer, then, it’s possible that you have no support for SIMD operations in your computer.</p>
+<p>Why have people started using SIMD in their software? The answer is performance. But what does SIMD precisely do to achieve better performance? Well, in essence, SIMD operations are a different strategy to get parallel computing in your program, and therefore, make faster calculations.</p>
 <p>The basic idea behind SIMD is to have a single instruction that operates over multiple data at the same time. When you perform a normal scalar operation, like for example, four add instructions, each addition is performed separately, one after another. But with SIMD, these four add instructions are translated into a single instruction, and, as consequence, the four additions are performed in parallel, at the same time.</p>
 <p>Currently, the <code>zig</code> compiler allows you to apply the following group of operators on vector objects. When you apply one of these operators on vector objects, SIMD is used to make the calculations, and, therefore, these operators are applied element-wise and in parallel by default.</p>
 <ul>
@@ -356,7 +356,7 @@ <h2 data-number="17.1" class="anchored" data-anchor-id="what-is-simd"><span clas
 <section id="sec-what-vectors" class="level2" data-number="17.2">
 <h2 data-number="17.2" class="anchored" data-anchor-id="sec-what-vectors"><span class="header-section-number">17.2</span> Vectors</h2>
 <p>A SIMD operation is usually performed through a <em>SIMD intrinsic</em>, which is just a fancy name for a function that performs a SIMD operation. These SIMD intrinsics (or “SIMD functions”) always operate over a special type of object, which are called “vectors”. So, in order to use SIMD, you have to create a “vector object”.</p>
-<p>A vector object is usually a fixed-sized block of 128 bits (16 bytes). As consequence, most vectors that you find in the wild are essentially arrays that contains 2 values of 8 bytes each, or, 4 values of 4 bytes each, or, 8 values of 2 bytes each, etc. However, different CPU models may have different extensions (or, “implementations”) of SIMD, which may offer more types of vector objects that are bigger in size (256 bits or 512 bits) to accomodate more data into a single vector object.</p>
+<p>A vector object is usually a fixed-sized block of 128 bits (16 bytes). As a consequence, most vectors that you find in the wild are essentially arrays that contains 2 values of 8 bytes each, or, 4 values of 4 bytes each, or, 8 values of 2 bytes each, etc. However, different CPU models may have different extensions (or, “implementations”) of SIMD, which may offer more types of vector objects that are bigger in size (256 bits or 512 bits) to accomodate more data into a single vector object.</p>
 <p>You can create a new vector object in Zig by using the <code>@Vector()</code> built-in function. Inside this function, you specify the vector length (number of elements in the vector), and the data type of the elements of the vector. Only primitive data types are supported in these vector objects. In the example below, I’m creating two vector objects (<code>v1</code> and <code>v2</code>) of 4 elements of type <code>u32</code> each.</p>
 <p>Also notice in the example below, that a third vector object (<code>v3</code>) is created from the sum of the previous two vector objects (<code>v1</code> plus <code>v2</code>). Therefore, math operations over vector objects take place element-wise by default, because the same operation (in this case, addition) is transformed into a single instruction that is replicated in parallel, across all elements of the vectors.</p>
 <div class="cell">
@@ -369,7 +369,7 @@ <h2 data-number="17.2" class="anchored" data-anchor-id="sec-what-vectors"><span
 </div>
 </div>
 <p>This is how SIMD introduces more performance in your program. Instead of using a for loop to iterate through the elements of <code>v1</code> and <code>v2</code>, and adding them together, one element at a time, we enjoy the benefits of SIMD, which performs all 4 additions in parallel, at the same time.</p>
-<p>Therefore, the <code>@Vector</code> structure is essentially the Zig representation of SIMD vector objects. The elements on these vector objects will be operated in parallel, if, and only if your current CPU model supports SIMD operations. If your CPU model does not have support for SIMD, then, the <code>@Vector</code> structure will likely produce a similar performance from a “for loop solution”.</p>
+<p>Therefore, the <code>@Vector</code> structure is essentially the Zig representation of SIMD vector objects. The elements in these vector objects will be operated in parallel, if, and only if your current CPU model supports SIMD operations. If your CPU model does not have support for SIMD, then, the <code>@Vector</code> structure will likely produce a similar performance from a “for loop solution”.</p>
 <section id="transforming-arrays-into-vectors" class="level3" data-number="17.2.1">
 <h3 data-number="17.2.1" class="anchored" data-anchor-id="transforming-arrays-into-vectors"><span class="header-section-number">17.2.1</span> Transforming arrays into vectors</h3>
 <p>There are different ways to transform a normal array into a vector object. You can either use implicit conversion (which is when you assign the array to a vector object directly), or, use slices to create a vector object from a normal array.</p>
@@ -381,7 +381,7 @@ <h3 data-number="17.2.1" class="anchored" data-anchor-id="transforming-arrays-in
 <span id="cb3-3"><a href="#cb3-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> v2: <span class="bu">@Vector</span>(<span class="dv">2</span>, <span class="dt">u32</span>) = a1[<span class="dv">1</span>..<span class="dv">3</span>].*;</span>
 <span id="cb3-4"><a href="#cb3-4" aria-hidden="true" tabindex="-1"></a>_ = v1; _ = v2;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>Is worth emphasizing that only arrays and slices whose sizes are compile-time known can be transformed into vectors. Vectors in general are structures that work only with compile-time known sizes. Therefore, if you have an array whose size is runtime known, then, you first need to copy it into an array with a compile-time known size, before transforming it into a vector.</p>
+<p>It’s worth emphasizing that only arrays and slices whose sizes are compile-time known can be transformed into vectors. Vectors in general are structures that work only with compile-time known sizes. Therefore, if you have an array whose size is runtime known, then, you first need to copy it into an array with a compile-time known size, before transforming it into a vector.</p>
 </section>
 <section id="the-splat-function" class="level3" data-number="17.2.2">
 <h3 data-number="17.2.2" class="anchored" data-anchor-id="the-splat-function"><span class="header-section-number">17.2.2</span> The <code>@splat()</code> function</h3>
@@ -397,8 +397,8 @@ <h3 data-number="17.2.2" class="anchored" data-anchor-id="the-splat-function"><s
 </section>
 <section id="careful-with-vectors-that-are-too-big" class="level3" data-number="17.2.3">
 <h3 data-number="17.2.3" class="anchored" data-anchor-id="careful-with-vectors-that-are-too-big"><span class="header-section-number">17.2.3</span> Careful with vectors that are too big</h3>
-<p>As I described at <a href="#sec-what-vectors" class="quarto-xref"><span>Section 17.2</span></a>, each vector object is usually a small block of 128, 256 or 512 bits. This means that a vector object is usually small in size, and when you try to go in the opposite direction, by creating a vector object that is very big in size (i.e.&nbsp;sizes that are close to <span class="math inline">\(2^{20}\)</span>), you usually end up with crashes and loud errors from the compiler.</p>
-<p>For example, if you try to compile the program below, you will likely face segmentation faults, or, LLVM errors during the build process. Just be careful to not create vector objects that are too big in size.</p>
+<p>As I described in <a href="#sec-what-vectors" class="quarto-xref"><span>Section 17.2</span></a>, each vector object is usually a small block of 128, 256 or 512 bits. This means that a vector object is usually small in size, and when you try to go in the opposite direction, by creating a vector object that is very big in size (i.e., sizes that are close to <span class="math inline">\(2^{20}\)</span>), you usually end up with crashes and loud errors from the compiler.</p>
+<p>For example, if you try to compile the program below, you will likely face segmentation faults, or LLVM errors during the build process. Just be careful to not create vector objects that are too big in size.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb6"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> v1: <span class="bu">@Vector</span>(<span class="dv">1000000</span>, <span class="dt">u32</span>) = <span class="bu">@splat</span>(<span class="dv">16</span>);</span>
 <span id="cb6-2"><a href="#cb6-2" aria-hidden="true" tabindex="-1"></a>_ = v1;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
diff --git a/docs/index.html b/docs/index.html
index 6012b60d..80cde802 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -7,7 +7,7 @@
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 <meta name="author" content="Pedro Duarte Faria">
-<meta name="dcterms.date" content="2025-02-16">
+<meta name="dcterms.date" content="2025-03-06">
 
 <title>Introduction to Zig</title>
 <style>
@@ -287,7 +287,7 @@ <h1 class="title">Introduction to Zig</h1>
     <div>
     <div class="quarto-title-meta-heading">Published</div>
     <div class="quarto-title-meta-contents">
-      <p class="date">February 16, 2025</p>
+      <p class="date">March 6, 2025</p>
     </div>
   </div>
   
@@ -391,7 +391,7 @@ <h3 class="anchored" data-anchor-id="revolut">Revolut</h3>
 </section>
 <section id="about-this-book" class="level2 unnumbered">
 <h2 class="unnumbered anchored" data-anchor-id="about-this-book">About this book</h2>
-<p>This an open (i.e.&nbsp;it is open-source), technical and introductory book for the <a href="https://ziglang.org/">Zig programming language</a>, which is a new general purpose, and low-level programming language for building optimal and robust software.</p>
+<p>This an open (i.e., open-source), technical and introductory book for the <a href="https://ziglang.org/">Zig programming language</a>, which is a new general purpose, and low-level programming language for building optimal and robust software.</p>
 <p>Official repository of the book: <a href="https://github.com/pedropark99/zig-book" class="uri">https://github.com/pedropark99/zig-book</a>.</p>
 <p>This book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small and simple projects (in a similar style to the famous “Python Crash Course” book from Eric Matthes). Some of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.</p>
 <p>As you work through the book, you will learn:</p>
@@ -454,7 +454,7 @@ <h2 class="unnumbered anchored" data-anchor-id="corresponding-author-and-maintai
 <section id="acknowledgments" class="level2 unnumbered">
 <h2 class="unnumbered anchored" data-anchor-id="acknowledgments">Acknowledgments</h2>
 <p>This book is also a product of many conversations and exchanges that we had with different people from the Zig community. I (Pedro Duarte Faria) am incredibly grateful for these conversations, and also, for some direct contributions that we had. Below we have a list of the people involved (name of the person with their usename in GitHub):</p>
-<p>Calin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang), Tommaso Ricci (@Zorgatone), Primo Sabatini (@primos63), Santiago Fernandez (@santif), Hamza Wahed (@HamzaWahed), mwilbur (@mwilbur), Dima Budaragin (@dbud), Jorge Jímenez (@jorge-j1m), Alexander (@alexwheezy), Maarten Coopens (@maarteNNNN), Niklas Johansson (@Raphexion)</p>
+<p>Calin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang), Tommaso Ricci (@Zorgatone), Primo Sabatini (@primos63), Santiago Fernandez (@santif), Hamza Wahed (@HamzaWahed), mwilbur (@mwilbur), Dima Budaragin (@dbud), Jorge Jímenez (@jorge-j1m), Alexander (@alexwheezy), Maarten Coopens (@maarteNNNN), Niklas Johansson (@Raphexion), glystik (@glystik), Michael Lynch (@mtlynch)</p>
 
 
 </section>
diff --git a/docs/search.json b/docs/search.json
index 0a1da144..e709a39f 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -24,7 +24,7 @@
     "href": "index.html#about-this-book",
     "title": "Introduction to Zig",
     "section": "About this book",
-    "text": "About this book\nThis an open (i.e. it is open-source), technical and introductory book for the Zig programming language, which is a new general purpose, and low-level programming language for building optimal and robust software.\nOfficial repository of the book: https://github.com/pedropark99/zig-book.\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small and simple projects (in a similar style to the famous “Python Crash Course” book from Eric Matthes). Some of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\nAs you work through the book, you will learn:\n\nThe syntax of the language, and how it compares to C, C++ and Rust.\nData structures, memory allocators, filesystem and I/O.\nOptionals as a new paradigm to handle nullability.\nHow to test and debug a Zig application.\nErrors as values, and how to handle them.\nHow to build C and Zig code with the build system that is embedded into the language.\nZig interoperability with C.\nParallelism with threads and SIMD.\nAnd more.",
+    "text": "About this book\nThis an open (i.e., open-source), technical and introductory book for the Zig programming language, which is a new general purpose, and low-level programming language for building optimal and robust software.\nOfficial repository of the book: https://github.com/pedropark99/zig-book.\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small and simple projects (in a similar style to the famous “Python Crash Course” book from Eric Matthes). Some of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\nAs you work through the book, you will learn:\n\nThe syntax of the language, and how it compares to C, C++ and Rust.\nData structures, memory allocators, filesystem and I/O.\nOptionals as a new paradigm to handle nullability.\nHow to test and debug a Zig application.\nErrors as values, and how to handle them.\nHow to build C and Zig code with the build system that is embedded into the language.\nZig interoperability with C.\nParallelism with threads and SIMD.\nAnd more.",
     "crumbs": [
       "Welcome"
     ]
@@ -84,7 +84,7 @@
     "href": "index.html#acknowledgments",
     "title": "Introduction to Zig",
     "section": "Acknowledgments",
-    "text": "Acknowledgments\nThis book is also a product of many conversations and exchanges that we had with different people from the Zig community. I (Pedro Duarte Faria) am incredibly grateful for these conversations, and also, for some direct contributions that we had. Below we have a list of the people involved (name of the person with their usename in GitHub):\nCalin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang), Tommaso Ricci (@Zorgatone), Primo Sabatini (@primos63), Santiago Fernandez (@santif), Hamza Wahed (@HamzaWahed), mwilbur (@mwilbur), Dima Budaragin (@dbud), Jorge Jímenez (@jorge-j1m), Alexander (@alexwheezy), Maarten Coopens (@maarteNNNN), Niklas Johansson (@Raphexion)",
+    "text": "Acknowledgments\nThis book is also a product of many conversations and exchanges that we had with different people from the Zig community. I (Pedro Duarte Faria) am incredibly grateful for these conversations, and also, for some direct contributions that we had. Below we have a list of the people involved (name of the person with their usename in GitHub):\nCalin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang), Tommaso Ricci (@Zorgatone), Primo Sabatini (@primos63), Santiago Fernandez (@santif), Hamza Wahed (@HamzaWahed), mwilbur (@mwilbur), Dima Budaragin (@dbud), Jorge Jímenez (@jorge-j1m), Alexander (@alexwheezy), Maarten Coopens (@maarteNNNN), Niklas Johansson (@Raphexion), glystik (@glystik), Michael Lynch (@mtlynch)",
     "crumbs": [
       "Welcome"
     ]
@@ -104,7 +104,7 @@
     "href": "Chapters/01-zig-weird.html",
     "title": "1  Introducing Zig",
     "section": "",
-    "text": "1.1 What is Zig?\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of Zig as a modern and better version of C.\nIn the author’s personal interpretation, Zig is tightly connected with “less is more”. Instead of trying to become a modern language by adding more and more features, many of the core improvements that Zig brings to the table are actually about removing annoying behaviours/features from C and C++. In other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour. As a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\nThis philosophy becomes clear with the following phrase from the official website of Zig:\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language, with tons of features, and also, there are lots of different “flavors of C++”. These elements are what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction. Zig is a very simple language, more closely related to other simple languages such as C and Go.\nThe phrase above is still important for C programmers too. Because, even C being a simple language, it is still hard sometimes to read and understand C code. For example, pre-processor macros in C are a frequent source of confusion. They really make it sometimes hard to debug C programs. Because macros are essentially a second language embedded in C that obscures your C code. With macros, you are no longer 100% sure about which pieces of the code are being sent to the compiler, i.e. they obscure the actual source code that you wrote.\nYou don’t have macros in Zig. In Zig, the code you write, is the actual code that get’s compiled by the compiler. You also don’t have a hidden control flow happening behind the scenes. And, you also don’t have functions or operators from the standard library that make hidden memory allocations behind your back.\nBy being a simpler language, Zig becomes much more clear and easier to read/write, but at the same time, it also achieves a much more robust state, with more consistent behaviour in edge situations. Once again, less is more.",
+    "text": "1.1 What is Zig?\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of Zig as a modern and better version of C.\nIn the author’s personal interpretation, Zig is tightly connected with “less is more”. Instead of trying to become a modern language by adding more and more features, many of the core improvements that Zig brings to the table are actually about removing annoying behaviours/features from C and C++. In other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour. As a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\nThis philosophy becomes clear with the following phrase from the official website of Zig:\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language, with tons of features, and also, there are lots of different “flavors of C++”. These elements are what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction. Zig is a very simple language, more closely related to other simple languages such as C and Go.\nThe phrase above is still important for C programmers too. Because, even C being a simple\nlanguage, it’s still hard sometimes to read and understand C code. For example, pre-processor macros in C are a frequent source of confusion. Sometimes, they really make it hard to debug\nC programs. Because macros are essentially a second language embedded in C that obscures your C code. With macros, you are no longer 100% sure about which pieces of the code are being sent to the compiler, i.e. they obscure the actual source code that you wrote.\nYou don’t have macros in Zig. In Zig, the code you write, is the actual code that gets compiled by the compiler. You also don’t have a hidden control flow happening behind the scenes. And, you also don’t have functions or operators from the standard library that make hidden memory allocations behind your back.\nBy being a simpler language, Zig becomes much more clear and easier to read/write, but at the same time, it also achieves a much more robust state, with more consistent behaviour in edge situations. Once again, less is more.",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -124,7 +124,7 @@
     "href": "Chapters/01-zig-weird.html#hello-world-in-zig",
     "title": "1  Introducing Zig",
     "section": "1.2 Hello world in Zig",
-    "text": "1.2 Hello world in Zig\nWe begin our journey in Zig by creating a small “Hello World” program. To start a new Zig project in your computer, you simply call the init command from the zig compiler. Just create a new directory in your computer, then, init a new Zig project inside this directory, like this:\nmkdir hello_world\ncd hello_world\nzig init\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n\n1.2.1 Understanding the project files\nAfter you run the init command from the zig compiler, some new files are created inside of your current directory. First, a “source” (src) directory is created, containing two files, main.zig and root.zig. Each .zig file is a separate Zig module, which is simply a text file that contains some Zig code.\nBy convention, the main.zig module is where your main function lives. Thus, if you are building an executable program in Zig, you need to declare a main() function, which represents the entrypoint of your program, i.e. it is where the execution of your program begins.\nHowever, if you are building a library (instead of an executable program), then, the normal procedure is to delete this main.zig file and start with the root.zig module. By convention, the root.zig module is the root source file of your library.\ntree .\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\nThe init command also creates two additional files in our working directory: build.zig and build.zig.zon. The first file (build.zig) represents a build script written in Zig. This script is executed when you call the build command from the zig compiler. In other words, this file contain Zig code that executes the necessary steps to build the entire project.\nLow-level languages normally use a compiler to build your source code into binary executables or binary libraries. Nevertheless, this process of compiling your source code and building binary executables or binary libraries from it, became a real challenge in the programming world, once the projects became bigger and bigger. As a result, programmers created “build systems”, which are a second set of tools designed to make this process of compiling and building complex projects, easier.\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja, which are used to build complex C and C++ projects. With these systems, you can write scripts, which are called “build scripts”. They simply are scripts that describes the necessary steps to compile/build your project.\nHowever, these are separate tools, that do not belong to C/C++ compilers, like gcc or clang. As a result, in C/C++ projects, you have not only to install and manage your C/C++ compilers, but you also have to install and manage these build systems separately.\nIn Zig, we don’t need to use a separate set of tools to build our projects, because a build system is embedded inside the language itself. Therefore, Zig contains a native build system in it, and we can use this build system to write small scripts in Zig, which describes the necessary steps to build/compile our Zig project1. So, everything you need to build a complex Zig project is the zig compiler, and nothing more.\nThe second generated file (build.zig.zon) is a JSON-like file, in which you can describe your project, and also, declare a set of dependencies of your project that you want to fetch from the internet. In other words, you can use this build.zig.zon file to include a list of external libraries in your project.\nOne possible way to include an external Zig library in your project, is to manually build and install the library in your system, and just link your source code with the library at the build step of your project.\nHowever, if this external Zig library is available on GitHub for example, and it has a valid build.zig.zon file in root folder of the project, which describes the project, you can easily include this library in your project by simply listing this external library in your build.zig.zon file.\nIn other words, this build.zig.zon file works similarly to the package.json file in Javascript projects, or the Pipfile file in Python projects, or the Cargo.toml file in Rust projects. You can read more about this specific file in a couple of articles on the internet23, and you can also see the expected schema for this build.zig.zon file in a documentation file inside the official repository of Zig4.\n\n\n1.2.2 The file root.zig\nLet’s take a look into the root.zig file. You might have noticed that every line of code with an expression ends with a semicolon (;). This follows the syntax of a C-family programming language5.\nAlso, notice the @import() call at the first line. We use this built-in function to import functionality from other Zig modules into our current module. This @import() function works similarly to the #include pre-processor in C or C++, or, to the import statement in Python or Javascript code. In this example, we are importing the std module, which gives you access to the Zig Standard Library.\nIn this root.zig file, we can also see how assignments (i.e. creating new objects) are made in Zig. You can create a new object in Zig by using the following syntax (const|var) name = value;. In the example below, we are creating two constant objects (std and testing). At Section 1.4 we talk more about objects in general.\n\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n\nFunctions in Zig are declared using the fn keyword. In this root.zig module, we are declaring a function called add(), which has two arguments named a and b. The function returns an integer of the type i32 as result.\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit the type of an object in your code, if this type can be inferred by the zig compiler (we talk more about that at Section 2.4). But there are other situations where you do need to be explicit. For example, you do have to explicitly specify the type of each function argument, and also, the return type of every function that you create in Zig.\nWe specify the type of an object or a function argument in Zig by using a colon character (:) followed by the type after the name of this object/function argument. With the expressions a: i32 and b: i32, we know that both a and b arguments have type i32, which is a signed 32 bit integer. In this part, the syntax in Zig is identical to the syntax in Rust, which also specifies types by using the colon character.\nLastly, we have the return type of the function at the end of the line, before we open the curly braces to start writing the function’s body. In the example above, this type is also a signed 32 bit integer (i32) value.\nNotice that we also have an export keyword before the function declaration. This keyword is similar to the extern keyword in C. It exposes the function to make it available in the library API. Therefore, if you are writing a library for other people to use, you have to expose the functions you write in the public API of this library by using this export keyword. If we removed the export keyword from the add() function declaration, then, this function would be no longer exposed in the library object built by the zig compiler.\n\n\n1.2.3 The main.zig file\nNow that we have learned a lot about Zig’s syntax from the root.zig file, let’s take a look at the main.zig file. A lot of the elements we saw in root.zig are also present in main.zig. But there are some other elements that we haven’t seen yet, so let’s dive in.\nFirst, look at the return type of the main() function in this file. We can see a small change. The return type of the function (void) is accompanied by an exclamation mark (!). This exclamation mark tells us that this main() function might return an error.\nIs worth noting that, a main() function in Zig is allowed to return nothing (void), or an unsigned 8-bit integer (u8) value6, or an error. In other words, you can write your main() function in Zig to return essentially nothing (void), or, if you prefer, you can also write a more C-like main() function, which returns an integer value that usually serves as a “status code” for the process.\nIn this example, the return type annotation of main() indicates that this function can either return nothing (void), or return an error. This exclamation mark in the return type annotation is an interesting and powerful feature of Zig. In summary, if you write a function and something inside the body of this function might return an error, then, you are forced to:\n\neither add the exclamation mark to the return type of the function and make it clear that this function might return an error.\nexplicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through a try catch pattern. Zig does have both try and catch keywords. But they work a little differently than what you’re probably used to in other languages.\nIf we look at the main() function below, you can see that we do have a try keyword on the 5th line. But we do not have a catch keyword in this code. In Zig, we use the try keyword to execute an expression that might return an error, which, in this example, is the stdout.print() expression.\nIn essence, the try keyword executes the expression stdout.print(). If this expression returns a valid value, then, the try keyword does absolutely nothing. It only passes the value forward. It is like if this try keyword was never there. However, if the expression does return an error, then, the try keyword will unwrap the error value, then, it returns this error from the function and also prints the current stack trace to stderr.\nThis might sound weird to you if you come from a high-level language. Because in high-level languages, such as Python, if an error occurs somewhere, this error is automatically returned and the execution of your program will automatically stop even if you don’t want to stop the execution. You are obligated to face the error.\n\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n\nAnother thing that you might have noticed in this code example, is that the main() function is marked with the pub keyword. It marks the main() function as a public function from this module. Every function in your Zig module is by default private to this Zig module and can only be called from within the module. Unless, you explicitly mark this function as a public function with the pub keyword.\nIf you think about it, this pub keyword in Zig does essentially the opposite of what the static keyword do in C/C++. By making a function “public” you allow other Zig modules to access and call this function. A calling Zig module imports another module by using the @import() built-in function, which makes all public functions from the imported module visible to the calling Zig module.\n\n\n1.2.4 Compiling your source code\nYou can compile your Zig modules into a binary executable by running the build-exe command from the zig compiler. You simply list all the Zig modules that you want to build after the build-exe command, separated by spaces. In the example below, we are compiling the module main.zig.\nzig build-exe src/main.zig\nSince we are building an executable, the zig compiler will look for a main() function declared in any of the files that you list after the build-exe command. If the compiler does not find a main() function declared somewhere, a compilation error will be raised, warning about this mistake.\nThe zig compiler also offers a build-lib and build-obj commands, which work the exact same way as the build-exe command. The only difference is that, they compile your Zig modules into a portable C ABI library, or, into object files, respectively.\nIn the case of the build-exe command, a binary executable file is created by the zig compiler in the root directory of your project. If we take a look now at the contents of our current directory, with a simple ls command, we can see the binary file called main that was created by the compiler.\nls\nbuild.zig  build.zig.zon  main  src\nIf I execute this binary executable, I get the “Hello World” message in the terminal , as we expected.\n./main\nHello, world!\n\n\n1.2.5 Compile and execute at the same time\nIn the previous section, I presented the zig build-exe command, which compiles Zig modules into an executable file. However, this means that, in order to execute the executable file, we have to run two different commands. First, the zig build-exe command, and then, we call the executable file created by the compiler.\nBut what if we wanted to perform these two steps, all at once, in a single command? We can do that by using the zig run command.\nzig run src/main.zig\nHello, world!\n\n\n1.2.6 Important note for Windows users\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other operating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that includes some global variables whose initialization rely on runtime resources, then, you might have some troubles while trying to compile this Zig code on Windows.\nAn example of that is accessing the stdout (i.e. the standard output of your system), which is usually done in Zig by using the expression std.io.getStdOut(). Thus, if you use this expression to instantiate a global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows, with a “unable to evaluate comptime expression” error message.\nThis failure in the compilation process happens because all global variables in Zig are initialized at compile-time. However, operations like accessing the stdout (or opening a file) on Windows depends on resources that are available only at runtime (you will learn more about compile-time versus runtime at Section 3.1.1).\nFor example, if you try to compile this code example on Windows, you will likely get the error message exposed below:\n\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerge from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\nTo avoid this problem on Windows, we need to force the zig compiler to instantiate this stdout object only at runtime, instead of instantiating it at compile-time. We can achieve that by simply moving the expression to a function body.\nThis solves the problem because all expressions that are inside a function body in Zig are evaluated only at runtime, unless you use the comptime keyword explicitly to change this behaviour. You will learn more about this comptime keyword at Section 12.1.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nHello\nYou can read more details about this Windows-specific limitation at a couple of GitHub issues opened at the official Zig repository. More specifically, the issues 17186 7 and 19864 8.\n\n\n1.2.7 Compiling the entire project\nJust as I described in Section 1.2.1, as our project grows in size and complexity, we usually prefer to organize the compilation and build process of the project into a build script, using some sort of “build system”.\nIn other words, as our project grows in size and complexity, the build-exe, build-lib and build-obj commands become harder to use directly. Because then, we start to list multiple and multiple modules at the same time. We also start to add built-in compilation flags to customize the build process for our needs, etc. It becomes a lot of work to write the necessary commands by hand.\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, Makefile or configure scripts to organize this process. However, in Zig, we have a native build system in the language itself. So, we can write build scripts in Zig to compile and build Zig projects. Then, all we need to do, is to call the zig build command to build our project.\nSo, when you execute the zig build command, the zig compiler will search for a Zig module named build.zig inside your current directory, which should be your build script, containing the necessary code to compile and build your project. If the compiler does find this build.zig file in your directory, then, the compiler will essentially execute a zig run command over this build.zig file, to compile and execute this build script, which in turn, will compile and build your entire project.\nzig build\nAfter you execute this “build project” command, a zig-out directory is created in the root of your project directory, where you can find the binary executables and libraries created from your Zig modules accordingly to the build commands that you specified at build.zig. We will talk more about the build system in Zig later in this book.\nIn the example below, I’m executing the binary executable named hello_world that was generated by the compiler after the zig build command.\n./zig-out/bin/hello_world\nHello, world!",
+    "text": "1.2 Hello world in Zig\nWe begin our journey in Zig by creating a small “Hello World” program. To start a new Zig project in your computer, you simply call the init command from the zig compiler. Just create a new directory in your computer, then, init a new Zig project inside this directory, like this:\nmkdir hello_world\ncd hello_world\nzig init\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n\n1.2.1 Understanding the project files\nAfter you run the init command from the zig compiler, some new files are created inside of your current directory. First, a “source” (src) directory is created, containing two files, main.zig and root.zig. Each .zig file is a separate Zig module, which is simply a text file that contains some Zig code.\nBy convention, the main.zig module is where your main function lives. Thus, if you are building an executable program in Zig, you need to declare a main() function, which represents the entrypoint of your program, i.e., where the execution of your program begins.\nHowever, if you are building a library (instead of an executable program), then, the normal procedure is to delete this main.zig file and start with the root.zig module. By convention, the root.zig module is the root source file of your library.\ntree .\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\nThe init command also creates two additional files in our working directory: build.zig and build.zig.zon. The first file (build.zig) represents a build script written in Zig. This script is executed when you call the build command from the zig compiler. In other words, this file contains Zig code that executes the necessary steps to build the entire project.\nLow-level languages normally use a compiler to build your source code into binary executables or binary libraries. Nevertheless, this process of compiling your source code and building binary executables or binary libraries from it, became a real challenge in the programming world, once the projects became bigger and bigger. As a result, programmers created “build systems”, which are a second set of tools designed to make this process of compiling and building complex projects, easier.\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja, which are used to build complex C and C++ projects. With these systems, you can write scripts, which are called “build scripts”. They simply are scripts that describes the necessary steps to compile/build your project.\nHowever, these are separate tools, that do not belong to C/C++ compilers, like gcc or clang. As a result, in C/C++ projects, you have not only to install and manage your C/C++ compilers, but you also have to install and manage these build systems separately.\nIn Zig, we don’t need to use a separate set of tools to build our projects, because a build system is embedded inside the language itself. We can use this build system to write small scripts in Zig, which describe the necessary steps to build/compile our Zig project1. So, everything you need to build a complex Zig project is the zig compiler, and nothing more.\nThe second generated file (build.zig.zon) is a JSON-like file, in which you can describe your project, and also, declare a set of dependencies of your project that you want to fetch from the internet. In other words, you can use this build.zig.zon file to include a list of external libraries in your project.\nOne possible way to include an external Zig library in your project, is to manually build and install the library in your system, and just link your source code with the library at the build step of your project.\nHowever, if this external Zig library is available on GitHub for example, and it has a valid build.zig.zon file in root folder of the project, which describes the project, you can easily include this library in your project by simply listing this external library in your build.zig.zon file.\nIn other words, this build.zig.zon file works similarly to the package.json file in Javascript projects, or the Pipfile file in Python projects, or the Cargo.toml file in Rust projects. You can read more about this specific file in a couple of articles on the internet23, and you can also see the expected schema for this build.zig.zon file in a documentation file inside the official repository of Zig4.\n\n\n1.2.2 The file root.zig\nLet’s take a look into the root.zig file. You might have noticed that every line of code with an expression ends with a semicolon (;). This follows the syntax of a C-family programming language5.\nAlso, notice the @import() call at the first line. We use this built-in function to import functionality from other Zig modules into our current module. This @import() function works similarly to the #include pre-processor in C or C++, or, to the import statement in Python or Javascript code. In this example, we are importing the std module, which gives you access to the Zig Standard Library.\nIn this root.zig file, we can also see how assignments (i.e., creating new objects) are made in Zig. You can create a new object in Zig by using the syntax (const|var) name = value;. In the example below, we are creating two constant objects (std and testing). In Section 1.4 we talk more about objects in general.\n\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n\nFunctions in Zig are declared using the fn keyword. In this root.zig module, we are declaring a function called add(), which has two arguments named a and b. The function returns an integer of the type i32 as result.\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit the type of an object in your code, if this type can be inferred by the zig compiler (we talk more about that in Section 2.4). But there are other situations where you do need to be explicit. For example, you do have to explicitly specify the type of each function argument, and also, the return type of every function that you create in Zig.\nWe specify the type of an object or a function argument in Zig by using a colon character (:) followed by the type after the name of this object/function argument. With the expressions a: i32 and b: i32, we know that both a and b arguments have type i32, which is a signed 32 bit integer. In this part, the syntax in Zig is identical to the syntax in Rust, which also specifies types by using the colon character.\nLastly, we have the return type of the function at the end of the line, before we open the curly braces to start writing the function’s body. In the example above, this type is also a signed 32 bit integer (i32) value.\nNotice that we also have an export keyword before the function declaration. This keyword is similar to the extern keyword in C. It exposes the function to make it available in the library API. Therefore, if you are writing a library for other people to use, you have to expose the functions you write in the public API of this library by using this export keyword. If we removed the export keyword from the add() function declaration, then, this function would be no longer exposed in the library object built by the zig compiler.\n\n\n1.2.3 The main.zig file\nNow that we have learned a lot about Zig’s syntax from the root.zig file, let’s take a look at the main.zig file. A lot of the elements we saw in root.zig are also present in main.zig. But there are some other elements that we haven’t seen yet, so let’s dive in.\nFirst, look at the return type of the main() function in this file. We can see a small change. The return type of the function (void) is accompanied by an exclamation mark (!). This exclamation mark tells us that this main() function might return an error.\nIt’s worth noting that, a main() function in Zig is allowed to return nothing (void), or an unsigned 8-bit integer (u8) value6, or an error. In other words, you can write your main() function in Zig to return essentially nothing (void), or, if you prefer, you can also write a more C-like main() function, which returns an integer value that usually serves as a “status code” for the process.\nIn this example, the return type annotation of main() indicates that this function can either return nothing (void), or return an error. This exclamation mark in the return type annotation is an interesting and powerful feature of Zig. In summary, if you write a function and something inside the body of this function might return an error, then, you are forced to:\n\neither add the exclamation mark to the return type of the function and make it clear that this function might return an error.\nexplicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through a try catch pattern. Zig does have both try and catch keywords. But they work a little differently than what you’re probably used to in other languages.\nIf we look at the main() function below, you can see that we do have a try keyword on the 5th line. But we do not have a catch keyword in this code. In Zig, we use the try keyword to execute an expression that might return an error, which, in this example, is the stdout.print() expression.\nIn essence, the try keyword executes the expression stdout.print(). If this expression returns a valid value, then, the try keyword does absolutely nothing. It only passes the value forward. It’s like if this try keyword was never there. However, if the expression does return an error, then, the try keyword will unwrap the error value, then, it returns this error from the function and also prints the current stack trace to stderr.\nThis might sound weird to you if you come from a high-level language. Because in high-level languages, such as Python, if an error occurs somewhere, this error is automatically returned and the execution of your program will automatically stop even if you don’t want to stop the execution. You are obligated to face the error.\n\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n\nAnother thing that you might have noticed in this code example, is that the main() function is marked with the pub keyword. It marks the main() function as a public function from this module. Every function in your Zig module is by default private to this Zig module and can only be called from within the module. Unless, you explicitly mark this function as a public function with the pub keyword.\nIf you think about it, this pub keyword in Zig does essentially the opposite of what the static keyword do in C/C++. By making a function “public” you allow other Zig modules to access and call this function. A calling Zig module imports another module by using the @import() built-in function, which makes all public functions from the imported module visible to the calling Zig module.\n\n\n1.2.4 Compiling your source code\nYou can compile your Zig modules into a binary executable by running the build-exe command from the zig compiler. You simply list all the Zig modules that you want to build after the build-exe command, separated by spaces. In the example below, we are compiling the module main.zig.\nzig build-exe src/main.zig\nSince we are building an executable, the zig compiler will look for a main() function declared in any of the files that you list after the build-exe command. If the compiler does not find a main() function declared somewhere, a compilation error will be raised, warning about this mistake.\nThe zig compiler also offers a build-lib and build-obj commands, which work the exact same way as the build-exe command. The only difference is that, they compile your Zig modules into a portable C ABI library, or, into object files, respectively.\nIn the case of the build-exe command, a binary executable file is created by the zig compiler in the root directory of your project. If we take a look now at the contents of our current directory, with a simple ls command, we can see the binary file called main that was created by the compiler.\nls\nbuild.zig  build.zig.zon  main  src\nIf I execute this binary executable, I get the “Hello World” message in the terminal , as we expected.\n./main\nHello, world!\n\n\n1.2.5 Compile and execute at the same time\nIn the previous section, I presented the zig build-exe command, which compiles Zig modules into an executable file. However, this means that, in order to execute the executable file, we have to run two different commands. First, the zig build-exe command, and then, we call the executable file created by the compiler.\nBut what if we wanted to perform these two steps, all at once, in a single command? We can do that by using the zig run command.\nzig run src/main.zig\nHello, world!\n\n\n1.2.6 Important note for Windows users\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other operating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that includes some global variables whose initialization rely on runtime resources, then, you might have some troubles while trying to compile this Zig code on Windows.\nAn example of that is accessing the stdout (i.e., the standard output of your system), which is usually done in Zig by using the expression std.io.getStdOut(). If you use this expression to instantiate a global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows, with an “unable to evaluate comptime expression” error message.\nThis failure in the compilation process happens because all global variables in Zig are initialized at compile-time. However, on Windows, operations like accessing the stdout (or opening a file) depend on resources that are available only at runtime (you will learn more about compile-time versus runtime in Section 3.1.1).\nFor example, if you try to compile this code example on Windows, you will likely get the error message exposed below:\n\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerges from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\nTo avoid this problem on Windows, we need to force the zig compiler to instantiate this stdout object only at runtime, instead of instantiating it at compile-time. We can achieve that by simply moving the expression to a function body.\nThis solves the problem because all expressions that are inside a function body in Zig are evaluated only at runtime, unless you use the comptime keyword explicitly to change this behaviour. You will learn more about this comptime keyword in Section 12.1.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nHello\nYou can read more details about this Windows-specific limitation in a couple of GitHub issues opened at the official Zig repository. More specifically, the issues\n17186 7 and 19864 8.\n\n\n1.2.7 Compiling the entire project\nJust as I described in Section 1.2.1, as our project grows in size and complexity, we usually prefer to organize the compilation and build process of the project into a build script, using some sort of “build system”.\nIn other words, as our project grows in size and complexity, the build-exe, build-lib and build-obj commands become harder to use directly. Because then, we start to list multiple and multiple modules at the same time. We also start to add built-in compilation flags to customize the build process for our needs, etc. It becomes a lot of work to write the necessary commands by hand.\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, Makefile or configure scripts to organize this process. However, in Zig, we have a native build system in the language itself. So, we can write build scripts in Zig to compile and build Zig projects. Then, all we need to do, is to call the zig build command to build our project.\nSo, when you execute the zig build command, the zig compiler will search for a Zig module named build.zig inside your current directory, which should be your build script, containing the necessary code to compile and build your project. If the compiler does find this build.zig file in your directory, then, the compiler will essentially execute a zig run command over this build.zig file, to compile and execute this build script, which in turn, will compile and build your entire project.\nzig build\nAfter you execute this “build project” command, a zig-out directory is created in the root of your project directory, where you can find the binary executables and libraries created from your Zig modules accordingly to the build commands that you specified at build.zig. We will talk more about the build system in Zig later in this book.\nIn the example below, I’m executing the binary executable named hello_world that was generated by the compiler after the zig build command.\n./zig-out/bin/hello_world\nHello, world!",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -134,7 +134,7 @@
     "href": "Chapters/01-zig-weird.html#how-to-learn-zig",
     "title": "1  Introducing Zig",
     "section": "1.3 How to learn Zig?",
-    "text": "1.3 How to learn Zig?\nWhat are the best strategies to learn Zig? First of all, of course this book will help you a lot on your journey through Zig. But you will also need some extra resources if you want to be really good at Zig.\nAs a first tip, you can join a community with Zig programmers to get some help , when you need it:\n\nReddit forum: https://www.reddit.com/r/Zig/;\nZiggit community: https://ziggit.dev/;\nDiscord, Slack, Telegram, and others: https://github.com/ziglang/zig/wiki/Community;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try to read Zig code often, and things will become more clear. A C/C++ programmer would also probably give you this same tip. Because this strategy really works!\nNow, where can you find Zig code to read? I personally think that, the best way of reading Zig code is to read the source code of the Zig Standard Library. The Zig Standard Library is available at the lib/std folder9 on the official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\nAlso, a great alternative is to read code from other large Zig codebases, such as:\n\nthe Javascript runtime Bun10.\nthe game engine Mach11.\na LLama 2 LLM model implementation in Zig12.\nthe financial transactions database tigerbeetle13.\nthe command-line arguments parser zig-clap14.\nthe UI framework capy15.\nthe Language Protocol implementation for Zig, zls16.\nthe event-loop library libxev17.\n\nAll these assets are available on GitHub, and this is great, because we can use the GitHub search bar to our advantage, to find Zig code that fits our description. For example, you can always include lang:Zig in the GitHub search bar when you are searching for a particular pattern. This will limit the search to only Zig modules.\nAlso, a great alternative is to consult online resources and documentation. Here is a quick list of resources that I personally use from time to time to learn more about the language each day:\n\nZig Language Reference: https://ziglang.org/documentation/master/;\nZig Standard Library Reference: https://ziglang.org/documentation/master/std/;\nZig Guide: https://zig.guide/;\nKarl Seguin Blog: https://www.openmymind.net/;\nZig News: https://zig.news/;\nRead the code written by one of the Zig core team members: https://github.com/kubkon;\nSome livecoding sessions are transmitted in the Zig Showtime Youtube Channel: https://www.youtube.com/@ZigSHOWTIME/videos;\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want, is to practice it by solving exercises. For example, there is a famous repository in the Zig community called Ziglings18 , which contains more than 100 small exercises that you can solve. It is a repository of tiny programs written in Zig that are currently broken, and your responsibility is to fix these programs, and make them work again.\nA famous tech YouTuber known as The Primeagen also posted some videos (on YouTube) where he solves these exercises from Ziglings. The first video is named “Trying Zig Part 1”19.\nAnother great alternative, is to solve the Advent of Code exercises20. There are people that already took the time to learn and solve the exercises, and they posted their solutions on GitHub as well, so, in case you need some resource to compare while solving the exercises, you can look at these two repositories:\n\nhttps://github.com/SpexGuy/Zig-AoC-Template;\nhttps://github.com/fjebaker/advent-of-code-2022;",
+    "text": "1.3 How to learn Zig?\nWhat are the best strategies to learn Zig? First of all, of course this book will help you a lot on your journey through Zig. But you will also need some extra resources if you want to be really good at Zig.\nAs a first tip, you can join a community with Zig programmers to get some help , when you need it:\n\nReddit forum: https://www.reddit.com/r/Zig/;\nZiggit community: https://ziggit.dev/;\nDiscord, Slack, Telegram, and others: https://github.com/ziglang/zig/wiki/Community;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try to read Zig code often, and things will become more clear. A C/C++ programmer would also probably give you this same tip. Because this strategy really works!\nNow, where can you find Zig code to read? I personally think that, the best way of reading Zig code is to read the source code of the Zig Standard Library. The Zig Standard Library is available at the lib/std folder9 on the official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\nAlso, a great alternative is to read code from other large Zig codebases, such as:\n\nthe Javascript runtime Bun10.\nthe game engine Mach11.\na LLama 2 LLM model implementation in Zig12.\nthe financial transactions database tigerbeetle13.\nthe command-line arguments parser zig-clap14.\nthe UI framework capy15.\nthe Language Protocol implementation for Zig, zls16.\nthe event-loop library libxev17.\n\nAll these assets are available on GitHub, and this is great, because we can use the GitHub search bar to our advantage, to find Zig code that fits our description. For example, you can always include lang:Zig in the GitHub search bar when you are searching for a particular pattern. This will limit the search to only Zig modules.\nAlso, a great alternative is to consult online resources and documentation. Here is a quick list of resources that I personally use from time to time to learn more about the language each day:\n\nZig Language Reference: https://ziglang.org/documentation/master/;\nZig Standard Library Reference: https://ziglang.org/documentation/master/std/;\nZig Guide: https://zig.guide/;\nKarl Seguin Blog: https://www.openmymind.net/;\nZig News: https://zig.news/;\nRead the code written by one of the Zig core team members: https://github.com/kubkon;\nSome livecoding sessions are transmitted in the Zig Showtime Youtube Channel: https://www.youtube.com/@ZigSHOWTIME/videos;\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want, is to practice it by solving exercises. For example, there is a famous repository in the Zig community called Ziglings18 , which contains more than 100 small exercises that you can solve. It’s a repository of tiny programs written in Zig that are currently broken, and your responsibility is to fix these programs, and make them work again.\nA famous tech YouTuber known as The Primeagen also posted some videos (on YouTube) where he solves these exercises from Ziglings. The first video is named “Trying Zig Part 1”19.\nAnother great alternative, is to solve the Advent of Code exercises20. There are people that already took the time to learn and solve the exercises, and they posted their solutions on GitHub as well, so, in case you need some resource to compare while solving the exercises, you can look at these two repositories:\n\nhttps://github.com/SpexGuy/Zig-AoC-Template;\nhttps://github.com/fjebaker/advent-of-code-2022;",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -143,8 +143,8 @@
     "objectID": "Chapters/01-zig-weird.html#sec-assignments",
     "href": "Chapters/01-zig-weird.html#sec-assignments",
     "title": "1  Introducing Zig",
-    "section": "1.4 Creating new objects in Zig (i.e. identifiers)",
-    "text": "1.4 Creating new objects in Zig (i.e. identifiers)\nLet’s talk more about objects in Zig. Readers that have past experience with other programming languages might know this concept through a different name, such as: “variable” or “identifier”. In this book, I choose to use the term “object” to refer to this concept.\nTo create a new object (or a new “identifier”) in Zig, we use the keywords const or var. These keywords specify if the object that you are creating is mutable or not. If you use const, then the object you are creating is a constant (or immutable) object, which means that once you declare this object, you can no longer change the value stored inside this object.\nOn the other side, if you use var, then, you are creating a variable (or mutable) object. You can change the value of this object as many times you want. Using the keyword var in Zig is similar to using the keywords let mut in Rust.\n\n1.4.1 Constant objects vs variable objects\nIn the code example below, we are creating a new constant object called age. This object stores a number representing the age of someone. However, this code example does not compile successfully. Because on the next line of code, we are trying to change the value of the object age to 25.\nThe zig compiler detects that we are trying to change the value of an object/identifier that is constant, and because of that, the compiler will raise a compilation error, warning us about the mistake.\n\nconst age = 24;\n// The line below is not valid!\nage = 25;\n\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\nIn contrast, if you use var, then, the object created is a variable object. With var you can declare this object in your source code, and then, change the value of this object how many times you want over future points in your source code.\nSo, using the same code example exposed above, if I change the declaration of the age object to use the var keyword, then, the program gets compiled successfully. Because now, the zig compiler detects that we are changing the value of an object that allows this behaviour, because it is an “variable object”.\n\nvar age: u8 = 24;\nage = 25;\n\n\n\n1.4.2 Declaring without an initial value\nBy default, when you declare a new object in Zig, you must give it an initial value. In other words, this means that we have to declare, and, at the same time, initialize every object we create in our source code.\nOn the other hand, you can, in fact, declare a new object in your source code, and not give it an explicit value. But we need to use a special keyword for that, which is the undefined keyword.\nIs important to emphasize that, you should avoid using undefined as much as possible. Because when you use this keyword, you leave your object uninitialized, and, as a consequence, if for some reason, your code use this object while it is uninitialized, then, you will definitely have undefined behaviour and major bugs in your program.\nIn the example below, I’m declaring the age object again. But this time, I do not give it an initial value. The variable is only initialized at the second line of code, where I store the number 25 in this object.\n\nvar age: u8 = undefined;\nage = 25;\n\nHaving these points in mind, just remember that you should avoid as much as possible to use undefined in your code. Always declare and initialize your objects. Because this gives you much more safety in your program. But in case you really need to declare an object without initializing it… the undefined keyword is the way to do it in Zig.\n\n\n1.4.3 There is no such thing as unused objects\nEvery object (being constant or variable) that you declare in Zig must be used in some way. You can give this object to a function call, as a function argument, or, you can use it in another expression to calculate the value of another object, or, you can call a method that belongs to this particular object.\nIt doesn’t matter in which way you use it. As long as you use it. If you try to break this rule, i.e. if your try to declare a object, but not use it, the zig compiler will not compile your Zig source code, and it will issue a error message warning that you have unused objects in your code.\nLet’s demonstrate this with an example. In the source code below, we declare a constant object called age. If you try to compile a simple Zig program with this line of code below, the compiler will return an error as demonstrated below:\n\nconst age = 15;\n\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\nEverytime you declare a new object in Zig, you have two choices:\n\nyou either use the value of this object;\nor you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign this object to a special character in Zig, which is the underscore (_). When you assign an object to a underscore, like in the example below, the zig compiler will automatically discard the value of this particular object.\nYou can see in the example below that, this time, the compiler did not complain about any “unused constant”, and successfully compiled our source code.\n\n// It compiles!\nconst age = 15;\n_ = age;\n\nNow, remember, everytime you assign a particular object to the underscore, this object is essentially destroyed. It is discarded by the compiler. This means that you can no longer use this object further in your code. It doesn’t exist anymore.\nSo if you try to use the constant age in the example below, after we discarded it, you will get a loud error message from the compiler (talking about a “pointless discard”) warning you about this mistake.\n\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n\nt.zig:7:5: error: pointless discard\n    of local constant\nThis same rule applies to variable objects. Every variable object must also be used in some way. And if you assign a variable object to the underscore, this object also get’s discarded, and you can no longer use this object.\n\n\n1.4.4 You must mutate every variable objects\nEvery variable object that you create in your source code must be mutated at some point. In other words, if you declare an object as a variable object, with the keyword var, and you do not change the value of this object at some point in the future, the zig compiler will detect this, and it will raise an error warning you about this mistake.\nThe concept behind this is that every object you create in Zig should be preferably a constant object, unless you really need an object whose value will change during the execution of your program.\nSo, if I try to declare a variable object such as where_i_live below, and I do not change the value of this object in some way, the zig compiler raises an error message with the phrase “variable is never mutated”.\n\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'",
+    "section": "1.4 Creating new objects in Zig (i.e., identifiers)",
+    "text": "1.4 Creating new objects in Zig (i.e., identifiers)\nLet’s talk more about objects in Zig. Readers that have past experience with other programming languages might know this concept through a different name, such as: “variable” or “identifier”. In this book, I choose to use the term “object” to refer to this concept.\nTo create a new object (or a new “identifier”) in Zig, we use the keywords const or var. These keywords specify if the object that you are creating is mutable or not. If you use const, then the object you are creating is a constant (or immutable) object, which means that once you declare this object, you can no longer change the value stored inside this object.\nOn the other side, if you use var, then, you are creating a variable (or mutable) object. You can change the value of this object as many times you want. Using the keyword var in Zig is similar to using the keywords let mut in Rust.\n\n1.4.1 Constant objects vs variable objects\nIn the code example below, we are creating a new constant object called age. This object stores a number representing the age of someone. However, this code example does not compile successfully. Because on the next line of code, we are trying to change the value of the object age to 25.\nThe zig compiler detects that we are trying to change the value of an object/identifier that is constant, and because of that, the compiler will raise a compilation error, warning us about the mistake.\n\nconst age = 24;\n// The line below is not valid!\nage = 25;\n\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\nIn contrast, if you use var, then, the object created is a variable object. With var you can declare this object in your source code, and then, change the value of this object how many times you want over future points in your source code.\nSo, using the same code example exposed above, if I change the declaration of the age object to use the var keyword, then, the program gets compiled successfully. Because now, the zig compiler detects that we are changing the value of an object that allows this behaviour, because it’s a “variable object”.\n\nvar age: u8 = 24;\nage = 25;\n\n\n\n1.4.2 Declaring without an initial value\nBy default, when you declare a new object in Zig, you must give it an initial value. In other words, this means that we have to declare, and, at the same time, initialize every object we create in our source code.\nOn the other hand, you can, in fact, declare a new object in your source code, and not give it an explicit value. But we need to use a special keyword for that, which is the undefined keyword.\nIt’s important to emphasize that, you should avoid using undefined as much as possible. Because when you use this keyword, you leave your object uninitialized, and, as a consequence, if for some reason, your code uses this object while it’s uninitialized, then, you will definitely have undefined behaviour and major bugs in your program.\nIn the example below, I’m declaring the age object again. But this time, I do not give it an initial value. The variable is only initialized at the second line of code, where I store the number 25 in this object.\n\nvar age: u8 = undefined;\nage = 25;\n\nHaving these points in mind, just remember that you should avoid as much as possible to use undefined in your code. Always declare and initialize your objects. Because this gives you much more safety in your program. But in case you really need to declare an object without initializing it… the undefined keyword is the way to do it in Zig.\n\n\n1.4.3 There is no such thing as unused objects\nEvery object (being constant or variable) that you declare in Zig must be used in some way. You can give this object to a function call, as a function argument, or, you can use it in another expression to calculate the value of another object, or, you can call a method that belongs to this particular object.\nIt doesn’t matter in which way you use it. As long as you use it. If you try to break this rule, i.e., if your try to declare a object, but not use it, the zig compiler will not compile your Zig source code, and it will issue a error message warning that you have unused objects in your code.\nLet’s demonstrate this with an example. In the source code below, we declare a constant object called age. If you try to compile a simple Zig program with this line of code below, the compiler will return an error as demonstrated below:\n\nconst age = 15;\n\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\nEverytime you declare a new object in Zig, you have two choices:\n\nyou either use the value of this object;\nor you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign this object to a special character in Zig, which is the underscore (_). When you assign an object to a underscore, like in the example below, the zig compiler will automatically discard the value of this particular object.\nYou can see in the example below that, this time, the compiler did not complain about any “unused constant”, and successfully compiled our source code.\n\n// It compiles!\nconst age = 15;\n_ = age;\n\nNow, remember, everytime you assign a particular object to the underscore, this object is essentially destroyed. It’s discarded by the compiler. This means that you can no longer use this object further in your code. It doesn’t exist anymore.\nSo if you try to use the constant age in the example below, after we discarded it, you will get a loud error message from the compiler (talking about a “pointless discard”) warning you about this mistake.\n\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n\nt.zig:7:5: error: pointless discard\n    of local constant\nThis same rule applies to variable objects. Every variable object must also be used in some way. And if you assign a variable object to the underscore, this object also gets discarded, and you can no longer use this object.\n\n\n1.4.4 You must mutate every variable objects\nEvery variable object that you create in your source code must be mutated at some point. In other words, if you declare an object as a variable object, with the keyword var, and you do not change the value of this object at some point in the future, the zig compiler will detect this, and it will raise an error warning you about this mistake.\nThe concept behind this is that every object you create in Zig should be preferably a constant object, unless you really need an object whose value will change during the execution of your program.\nSo, if I try to declare a variable object such as where_i_live below, and I do not change the value of this object in some way, the zig compiler raises an error message with the phrase “variable is never mutated”.\n\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -164,7 +164,7 @@
     "href": "Chapters/01-zig-weird.html#sec-arrays",
     "title": "1  Introducing Zig",
     "section": "1.6 Arrays",
-    "text": "1.6 Arrays\nYou create arrays in Zig by using a syntax that resembles the C syntax. First, you specify the size of the array (i.e. the number of elements that will be stored in the array) you want to create inside a pair of brackets.\nThen, you specify the data type of the elements that will be stored inside this array. All elements present in an array in Zig must have the same data type. For example, you cannot mix elements of type f32 with elements of type i32 in the same array.\nAfter that, you simply list the values that you want to store in this array inside a pair of curly braces. In the example below, I am creating two constant objects that contain different arrays. The first object contains an array of 4 integer values, while the second object, an array of 3 floating point values.\nNow, you should notice that in the object ls, I am not explicitly specifying the size of the array inside of the brackets. Instead of using a literal value (like the value 4 that I used in the ns object), I am using the special character underscore (_). This syntax tells the zig compiler to fill this field with the number of elements listed inside of the curly braces. So, this syntax [_] is for lazy (or smart) programmers who leave the job of counting how many elements there are in the curly braces for the compiler.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n\nIs worth noting that these are static arrays, meaning that they cannot grow in size. Once you declare your array, you cannot change the size of it. This is very common in low level languages. Because low level languages normally wants to give you (the programmer) full control over memory, and the way in which arrays are expanded is tightly related to memory management.\n\n1.6.1 Selecting elements of the array\nOne very common activity is to select specific portions of an array you have in your source code. In Zig, you can select a specific element from your array, by simply providing the index of this particular element inside brackets after the object name. In the example below, I am selecting the third element from the ns array. Notice that Zig is a “zero-index” based language, like C, C++, Rust, Python, and many other languages.\n\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n\n12\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a range selector. Some programmers also call these selectors of “slice selectors”, and they also exist in Rust, and have the exact same syntax as in Zig. Anyway, a range selector is a special expression in Zig that defines a range of indexes, and it have the syntax start..end.\nIn the example below, at the second line of code, the sl object stores a slice (or a portion) of the ns array. More precisely, the elements at index 1 and 2 in the ns array.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n\nWhen you use the start..end syntax, the “end tail” of the range selector is non-inclusive, meaning that, the index at the end is not included in the range that is selected from the array. Therefore, the syntax start..end actually means start..end - 1 in practice.\nYou can for example, create a slice that goes from the first to the last elements of the array, by using ar[0..ar.len] syntax In other words, it is a slice that access all elements in the array.\n\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n\nYou can also use the syntax start.. in your range selector. Which tells the zig compiler to select the portion of the array that begins at the start index until the last element of the array. In the example below, we are selecting the range from index 1 until the end of the array.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n\n\n\n1.6.2 More on slices\nAs we discussed before, in Zig, you can select specific portions of an existing array. This is called slicing in Zig (Sobeston 2024), because when you select a portion of an array, you are creating a slice object from that array.\nA slice object is essentially a pointer object accompanied by a length number. The pointer object points to the first element in the slice, and the length number tells the zig compiler how many elements there are in this slice.\n\nSlices can be thought of as a pair of [*]T (the pointer to the data) and a usize (the element count) (Sobeston 2024).\n\nThrough the pointer contained inside the slice you can access the elements (or values) that are inside this range (or portion) that you selected from the original array. But the length number (which you can access through the len property of your slice object) is the really big improvement (over C arrays for example) that Zig brings to the table here.\nBecause with this length number the zig compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice, or, if you are causing any buffer overflow problems. In the example below, we access the len property of the slice sl, which tells us that this slice have 2 elements in it.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n\n2\n\n\n\n\n1.6.3 Array operators\nThere are two array operators available in Zig that are very useful. The array concatenation operator (++), and the array multiplication operator (**). As the name suggests, these are array operators.\nOne important detail about these two operators is that they work only when both operands have a size (or “length”) that is compile-time known. We are going to talk more about the differences between “compile-time known” and “runtime known” at Section 3.1.1. But for now, keep this information in mind, that you cannot use these operators in every situation.\nIn summary, the ++ operator creates a new array that is the concatenation, of both arrays provided as operands. So, the expression a ++ b produces a new array which contains all the elements from arrays a and b.\n\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n\n{ 1, 2, 3, 4, 5 }\n\n\nThis ++ operator is particularly useful to concatenate strings together. Strings in Zig are described in depth at Section 1.8. In summary, a string object in Zig is essentially an arrays of bytes. So, you can use this array concatenation operator to effectively concatenate strings together.\nIn contrast, the ** operator is used to replicate an array multiple times. In other words, the expression a ** 3 creates a new array which contains the elements of the array a repeated 3 times.\n\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n\n{ 1, 2, 3, 1, 2, 3 }\n\n\n\n\n1.6.4 Runtime versus compile-time known length in slices\nWe are going to talk a lot about the differences between compile-time known and runtime known across this book, especially at Section 3.1.1. But the basic idea is that a thing is compile-time known, when we know everything (the value, the attributes and the characteristics) about this thing at compile-time. In contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime. Therefore, we don’t know the value of this thing at compile-time, only at runtime.\nWe have learned at Section 1.6.1 that slices are created by using a range selector, which represents a range of indexes. When this “range of indexes” (i.e. the start and the end of this range) is known at compile-time, the slice object that get’s created is actually, under the hood, just a single-item pointer to an array.\nYou don’t need to precisely understand what that means now. We are going to talk a lot about pointers at Chapter 6. For now, just understand that, when the range of indexes is known at compile-time, the slice that get’s created is just a pointer to an array, accompanied by a length value that tells the size of the slice.\nIf you have a slice object like this, i.e. a slice that has a compile-time known range, you can use common pointer operations over this slice object. For example, you can dereference the pointer of this slice, by using the .* method, like you would do on a normal pointer object.\n\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object that get’s created is not a pointer anymore, and, thus, it does not support pointer operations. For example, maybe the start index is known at compile time, but the end index is not. In such case, the range of the slice becomes runtime known only.\nIn the example below, the slice object have a runtime known range, because the end index of the range is not known at compile time. In other words, the size of the array at buffer is not known at compile time. When we execute this program, the size of the array might be 10, or, it might be 12 depending on where we execute it. Therefore, we don’t know at compile time if the slice object have a range of size 10, or, a range of size 12.\n\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}",
+    "text": "1.6 Arrays\nYou create arrays in Zig by using a syntax that resembles the C syntax. First, you specify the size of the array (i.e., the number of elements that will be stored in the array) you want to create inside a pair of brackets.\nThen, you specify the data type of the elements that will be stored inside this array. All elements present in an array in Zig must have the same data type. For example, you cannot mix elements of type f32 with elements of type i32 in the same array.\nAfter that, you simply list the values that you want to store in this array inside a pair of curly braces. In the example below, I am creating two constant objects that contain different arrays. The first object contains an array of 4 integer values, while the second object, an array of 3 floating point values.\nNow, you should notice that in the object ls, I am not explicitly specifying the size of the array inside of the brackets. Instead of using a literal value (like the value 4 that I used in the ns object), I am using the special character underscore (_). This syntax tells the zig compiler to fill this field with the number of elements listed inside of the curly braces. So, this syntax [_] is for lazy (or smart) programmers who leave the job of counting how many elements there are in the curly braces for the compiler.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n\nIt’s worth noting that these are static arrays, meaning that they cannot grow in size. Once you declare your array, you cannot change the size of it. This is very common in low level languages. Because low level languages normally wants to give you (the programmer) full control over memory, and the way in which arrays are expanded is tightly related to memory management.\n\n1.6.1 Selecting elements of the array\nOne very common activity is to select specific portions of an array you have in your source code. In Zig, you can select a specific element from your array, by simply providing the index of this particular element inside brackets after the object name. In the example below, I am selecting the third element from the ns array. Notice that Zig is a “zero-index” based language, like C, C++, Rust, Python, and many other languages.\n\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n\n12\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a range selector. Some programmers also call these selectors of “slice selectors”, and they also exist in Rust, and have the exact same syntax as in Zig. Anyway, a range selector is a special expression in Zig that defines a range of indexes, and it have the syntax start..end.\nIn the example below, at the second line of code, the sl object stores a slice (or a portion) of the ns array. More precisely, the elements at index 1 and 2 in the ns array.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n\nWhen you use the start..end syntax, the “end tail” of the range selector is non-inclusive, meaning that, the index at the end is not included in the range that is selected from the array. Therefore, the syntax start..end actually means start..end - 1 in practice.\nYou can for example, create a slice that goes from the first to the last elements of the array, by using ar[0..ar.len] syntax In other words, it’s a slice that accesses all elements in the array.\n\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n\nYou can also use the syntax start.. in your range selector. Which tells the zig compiler to select the portion of the array that begins at the start index until the last element of the array. In the example below, we are selecting the range from index 1 until the end of the array.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n\n\n\n1.6.2 More on slices\nAs we discussed before, in Zig, you can select specific portions of an existing array. This is called slicing in Zig (Sobeston 2024), because when you select a portion of an array, you are creating a slice object from that array.\nA slice object is essentially a pointer object accompanied by a length number. The pointer object points to the first element in the slice, and the length number tells the zig compiler how many elements there are in this slice.\n\nSlices can be thought of as a pair of [*]T (the pointer to the data) and a usize (the element count) (Sobeston 2024).\n\nThrough the pointer contained inside the slice you can access the elements (or values) that are inside this range (or portion) that you selected from the original array. But the length number (which you can access through the len property of your slice object) is the really big improvement (over C arrays for example) that Zig brings to the table here.\nBecause with this length number the zig compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice, or, if you are causing any buffer overflow problems. In the example below, we access the len property of the slice sl, which tells us that this slice have 2 elements in it.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n\n2\n\n\n\n\n1.6.3 Array operators\nThere are two array operators available in Zig that are very useful. The array concatenation operator (++), and the array multiplication operator (**). As the name suggests, these are array operators.\nOne important detail about these two operators is that they work only when both operands have a size (or “length”) that is compile-time known. We are going to talk more about the differences between “compile-time known” and “runtime known” in Section 3.1.1. But for now, keep this information in mind, that you cannot use these operators in every situation.\nIn summary, the ++ operator creates a new array that is the concatenation, of both arrays provided as operands. So, the expression a ++ b produces a new array which contains all the elements from arrays a and b.\n\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n\n{ 1, 2, 3, 4, 5 }\n\n\nThis ++ operator is particularly useful to concatenate strings together. Strings in Zig are described in depth in Section 1.8. In summary, a string object in Zig is essentially an arrays of bytes. So, you can use this array concatenation operator to effectively concatenate strings together.\nIn contrast, the ** operator is used to replicate an array multiple times. In other words, the expression a ** 3 creates a new array which contains the elements of the array a repeated 3 times.\n\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n\n{ 1, 2, 3, 1, 2, 3 }\n\n\n\n\n1.6.4 Runtime versus compile-time known length in slices\nWe are going to talk a lot about the differences between compile-time known and runtime known across this book, especially in Section 3.1.1. But the basic idea is that a thing is compile-time known, when we know everything (the value, the attributes and the characteristics) about this thing at compile-time. In contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime. Therefore, we don’t know the value of this thing at compile-time, only at runtime.\nWe have learned in Section 1.6.1 that slices are created by using a range selector, which represents a range of indexes. When this “range of indexes” (i.e., the start and the end of this range) is known at compile-time, the slice object that gets created is actually, under the hood, just a single-item pointer to an array.\nYou don’t need to precisely understand what that means now. We are going to talk a lot about pointers in Chapter 6. For now, just understand that, when the range of indexes is known at compile-time, the slice that gets created is just a pointer to an array, accompanied by a length value that tells the size of the slice.\nIf you have a slice object like this, i.e., a slice that has a compile-time known range, you can use common pointer operations over this slice object. For example, you can dereference the pointer of this slice, by using the .* method, like you would do on a normal pointer object.\n\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object that gets created is not a pointer anymore, and, thus, it does not support pointer operations. For example, maybe the start index is known at compile time, but the end index is not. In such case, the range of the slice becomes runtime known only.\nIn the example below, the slice object have a runtime known range, because the end index of the range is not known at compile time. In other words, the size of the array at buffer is not known at compile time. When we execute this program, the size of the array might be 10, or, it might be 12 depending on where we execute it. Therefore, we don’t know at compile time if the slice object have a range of size 10, or, a range of size 12.\n\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -174,7 +174,7 @@
     "href": "Chapters/01-zig-weird.html#sec-blocks",
     "title": "1  Introducing Zig",
     "section": "1.7 Blocks and scopes",
-    "text": "1.7 Blocks and scopes\nBlocks are created in Zig by a pair of curly braces. A block is just a group of expressions (or statements) contained inside of a pair of curly braces. All of these expressions that are contained inside of this pair of curly braces belongs to the same scope.\nIn other words, a block just delimits a scope in your code. The objects that you define inside the same block belongs to the same scope, and, therefore, are accessible from within this scope. At the same time, these objects are not accessible outside of this scope. So, you could also say that blocks are used to limit the scope of the objects that you create in your source code. In less technical terms, blocks are used to specify where in your source code you can access whatever object you have in your source code.\nSo, a block is just a group of expressions contained inside a pair of curly braces. And every block have its own scope separated from the others. The body of a function is a classic example of a block. If statements, for and while loops (and any other structure in the language that uses the pair of curly braces) are also examples of blocks.\nThis means that, every if statement, or for loop, etc., that you create in your source code have its own separate scope. That is why you can’t access the objects that you defined inside of your for loop (or if statement) in an outer scope, i.e. a scope outside of the for loop. Because you are trying to access an object that belongs to a scope that is different than your current scope.\nYou can create blocks within blocks, with multiple levels of nesting. You can also (if you want to) give a label to a particular block, with the colon character (:). Just write label: before you open the pair of curly braces that delimits your block. When you label a block in Zig, you can use the break keyword to return a value from this block, like as if it was a function’s body. You just write the break keyword, followed by the block label in the format :label, and the expression that defines the value that you want to return.\nLike in the example below, where we are returning the value from the y object from the block add_one, and saving the result inside the x object.\n\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n\nHey!",
+    "text": "1.7 Blocks and scopes\nBlocks are created in Zig by a pair of curly braces. A block is just a group of expressions (or statements) contained inside of a pair of curly braces. All of these expressions that are contained inside of this pair of curly braces belongs to the same scope.\nIn other words, a block just delimits a scope in your code. The objects that you define inside the same block belongs to the same scope, and, therefore, are accessible from within this scope. At the same time, these objects are not accessible outside of this scope. So, you could also say that blocks are used to limit the scope of the objects that you create in your source code. In less technical terms, blocks are used to specify where in your source code you can access whatever object you have in your source code.\nSo, a block is just a group of expressions contained inside a pair of curly braces. And every block have its own scope separated from the others. The body of a function is a classic example of a block. If statements, for and while loops (and any other structure in the language that uses the pair of curly braces) are also examples of blocks.\nThis means that, every if statement, or for loop, etc., that you create in your source code have its own separate scope. That is why you can’t access the objects that you defined inside of your for loop (or if statement) in an outer scope, i.e., a scope outside of the for loop. Because you are trying to access an object that belongs to a scope that is different than your current scope.\nYou can create blocks within blocks, with multiple levels of nesting. You can also (if you want to) give a label to a particular block, with the colon character (:). Just write label: before you open the pair of curly braces that delimits your block. When you label a block in Zig, you can use the break keyword to return a value from this block, like as if it was a function’s body. You just write the break keyword, followed by the block label in the format :label, and the expression that defines the value that you want to return.\nLike in the example below, where we are returning the value from the y object from the block add_one, and saving the result inside the x object.\n\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n\nHey!",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -184,7 +184,7 @@
     "href": "Chapters/01-zig-weird.html#sec-zig-strings",
     "title": "1  Introducing Zig",
     "section": "1.8 How strings work in Zig?",
-    "text": "1.8 How strings work in Zig?\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (Chapter 4). But in order for us to build such a thing, we need to get a better understanding on how strings work in Zig. So let’s discuss this specific aspect of Zig.\nIn summary, there are two types of string values that you care about in Zig, which are:\n\nString literal values.\nString objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e. similar to a C string). But in Zig, a string literal value also embeds the length of the string into the data type of the value itself. Therefore, a string literal value have a data type in the format *const [n:0]u8. The n in the data type indicates the size of the string.\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes, or, in other words, a slice of u8 values (slices were presented at Section 1.6). Thus, a string object have a data type of []u8 or []const u8, depending if the string object is marked as constant with const, or as variable with var.\nBecause a string object is essentially a slice, it means that a string object always contains two things: a pointer to an array of bytes (i.e. u8 values) that represents the string value; and also, a length value, which specifies the size of the slice, or, how many elements there is in the slice. Is worth to emphasize that the array of bytes in a string object is not null-terminated, like in a string literal value.\n\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every sequence of bytes you’re working with, but is not really Zig’s job to fix the encoding of your strings (you can use iconv22 for that). Today, most of the text in our modern world, especially on the web, should be UTF-8 encoded. So if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\nLet’s take for example the word “Hello”. In UTF-8, this sequence of characters (H, e, l, l, o) is represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this sequence is 0x48, 0x65, 0x6C, 0x6C, 0x6F. So if I take this sequence of hexadecimal values, and ask Zig to print this sequence of bytes as a sequence of characters (i.e. a string), then, the text “Hello” will be printed into the terminal:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n\nHello\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use a for loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal value to the terminal. You do that by using a print() statement with the X formatting specifier, like you would normally do with the printf() function23 in C.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n\n\n\n1.8.1 Strings in C\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well. In more details, string values in C are treated internally as an array of arbitrary bytes, and this array is also null-terminated.\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of the string inside the object itself. In the case of a string literal value, this length is stored in the data type of the value (i.e. the n variable in [n:0]u8). While, in a string object, the length is stored in the len attribute of the slice that represents the string object. This small detail makes your code safer, because it is much easier for the Zig compiler to check if you are trying to access an element that is “out of bounds”, i.e. if your trying to access memory that does not belong to you.\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless. So getting this kind of safety is not automatic and much harder to do in C. For example, if you want to track the length of your string throughout your program in C, then, you first need to loop through the array of bytes that represents this string, and find the null element ('\\0') position to discover where exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\nTo do that, you would need something like this in C. In this example, the C string stored in the object array is 25 bytes long:\n\n#include &lt;stdio.h&gt;\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n\nNumber of elements in the array: 25\nYou don’t have this kind of work in Zig. Because the length of the string is always present and accessible. In a string object for example, you can easily access the length of the string through the len attribute. As an example, the string_object object below is 43 bytes long:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n\n43\n\n\n\n\n1.8.2 A better look at the object type\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the @TypeOf() function. If we look at the type of the simple_array object below, you will find that this object is an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type i32 in Zig. That is what an object of type [4]i32 is.\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a constant pointer (hence the *const annotation) to an array of 16 elements (or 16 bytes). Each element is a single byte (more precisely, an unsigned 8 bit integer - u8), that is why we have the [16:0]u8 portion of the type below. In other words, the string literal value exposed below is 16 bytes long.\nNow, if we create an pointer to the simple_array object, then, we get a constant pointer to an array of 4 elements (*const [4]i32), which is very similar to the type of the string literal value. This demonstrates that a string literal value in Zig is already a pointer to a null-terminated array of bytes.\nFurthermore, if we take a look at the type of the string_obj object, you will see that it is a slice object (hence the [] portion of the type) to a sequence of constant u8 values (hence the const u8 portion of the type).\n\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n\n\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n\n\n1.8.3 Byte vs unicode points\nIs important to point out that each byte in the array is not necessarily a single character. This fact arises from the difference between a single byte and a single unicode point.\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in the string. For example, the character “H” is stored in UTF-8 as the decimal number 72. This means that the number 72 is the unicode point for the character “H”. Each possible character that can appear in a UTF-8 encoded string have its own unicode point.\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point) 570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which is 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why, the unicode point 570 is actually stored inside the computer’s memory as the bytes C8 BA.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n\nBytes that represents the string object: C8 BA \n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together to represent the number 570. That is why the relationship between bytes and unicode points is not always 1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds to a single unicode point.\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the bytes that represents that string, and not through the characters of that string. In the Ⱥ example above, the for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a consequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because the number of bytes will be equal to the number of characters in that string. In other words, in this specific situation, the relationship between bytes and unicode points is 1 to 1.\nBut on the other side, if your string contains other types of letters… for example, you might be working with text data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent your UTF-8 string will likely be much higher than the number of characters in that string.\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the std.unicode.Utf8View struct to create an iterator that iterates through the unicode points of your string.\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in this string is represented by three bytes. But the for loop iterates four times, one iteration for each character/unicode point in this string:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n\n\n1.8.4 Some useful functions for strings\nIn this section, I just want to quickly describe some functions from the Zig Standard Library that are very useful to use when working with strings. Most notably:\n\nstd.mem.eql(): to compare if two strings are equal.\nstd.mem.splitScalar(): to split a string into an array of substrings given a delimiter value.\nstd.mem.splitSequence(): to split a string into an array of substrings given a substring delimiter.\nstd.mem.startsWith(): to check if string starts with substring.\nstd.mem.endsWith(): to check if string ends with substring.\nstd.mem.trim(): to remove specific values from both start and end of the string.\nstd.mem.concat(): to concatenate strings together.\nstd.mem.count(): to count the occurrences of substring in the string.\nstd.mem.replace(): to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the mem module of the Zig Standard Library. This module contains multiple functions and methods that are useful to work with memory and sequences of bytes in general.\nThe eql() function is used to check if two arrays of data are equal or not. Since strings are just arbitrary arrays of bytes, we can use this function to compare two strings together. This function returns a boolean value indicating if the two strings are equal or not. The first argument of this function is the data type of the elements of the arrays that are being compared.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n\ntrue\n\n\nThe splitScalar() and splitSequence() functions are useful to split a string into multiple fragments, like the split() method from Python strings. The difference between these two methods is that the splitScalar() uses a single character as the separator to split the string, while splitSequence() uses a sequence of characters (a.k.a. a substring) as the separator. There is a practical example of these functions later in the book.\nThe startsWith() and endsWith() functions are pretty straightforward. They return a boolean value indicating if the string (or, more precisely, if the array of data) begins (startsWith) or ends (endsWith) with the sequence provided.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n\ntrue\n\n\nThe concat() function, as the name suggests, concatenate two or more strings together. Because the process of concatenating the strings involves allocating enough space to accomodate all the strings together, this concat() function receives an allocator object as input.\n\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n\nAs you can imagine, the replace() function is used to replace substrings in a string by another substring. This function works very similarly to the replace() method from Python strings. Therefore, you provide a substring to search, and every time that the replace() function finds this substring within the input string, it replaces this substring with the “replacement substring” that you provided as input.\nIn the example below, we are taking the input string “Hello”, and replacing all occurrences of the substring “el” inside this input string with “34”, and saving the results inside the buffer object. As result, the replace() function returns an usize value that indicates how many replacements were performed.\n\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n\nNew string: H34lo\nN of replacements: 1",
+    "text": "1.8 How strings work in Zig?\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (Chapter 4). But in order for us to build such a thing, we need to get a better understanding on how strings work in Zig. So let’s discuss this specific aspect of Zig.\nIn summary, there are two types of string values that you care about in Zig, which are:\n\nString literal values.\nString objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e., similar to a C string). But in Zig, a string literal value also embeds the length of the string into the data type of the value itself. Therefore, a string literal value have a data type in the format *const [n:0]u8. The n in the data type indicates the size of the string.\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes, or, in other words, a slice of u8 values (slices were presented in Section 1.6). Thus, a string object have a data type of []u8 or []const u8, depending if the string object is marked as constant with const, or as variable with var.\nBecause a string object is essentially a slice, it means that a string object always contains two things: a pointer to an array of bytes (i.e., u8 values) that represents the string value; and also, a length value, which specifies the size of the slice, or, how many elements there is in the slice. It’s worth to emphasize that the array of bytes in a string object is not null-terminated, like in a string literal value.\n\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every sequence of bytes you’re working with, but is not really Zig’s job to fix the encoding of your strings (you can use iconv22 for that). Today, most of the text in our modern world, especially on the web, should be UTF-8 encoded. So if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\nLet’s take for example the word “Hello”. In UTF-8, this sequence of characters (H, e, l, l, o) is represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this sequence is 0x48, 0x65, 0x6C, 0x6C, 0x6F. So if I take this sequence of hexadecimal values, and ask Zig to print this sequence of bytes as a sequence of characters (i.e., a string), then, the text “Hello” will be printed into the terminal:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n\nHello\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use a for loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal value to the terminal. You do that by using a print() statement with the X formatting specifier, like you would normally do with the printf() function23 in C.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n\n\n\n1.8.1 Strings in C\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well. In more details, string values in C are treated internally as an array of arbitrary bytes, and this array is also null-terminated.\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of the string inside the object itself. In the case of a string literal value, this length is stored in the data type of the value (i.e., the n variable in [n:0]u8). While, in a string object, the length is stored in the len attribute of the slice that represents the string object. This small detail makes your code safer, because it’s much easier for the Zig compiler to check if you are trying to access an element that is “out of bounds”, i.e., if your trying to access memory that does not belong to you.\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless. So getting this kind of safety is not automatic and much harder to do in C. For example, if you want to track the length of your string throughout your program in C, then, you first need to loop through the array of bytes that represents this string, and find the null element ('\\0') position to discover where exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\nTo do that, you would need something like this in C. In this example, the C string stored in the object array is 25 bytes long:\n\n#include &lt;stdio.h&gt;\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n\nNumber of elements in the array: 25\nYou don’t have this kind of work in Zig. Because the length of the string is always present and accessible. In a string object for example, you can easily access the length of the string through the len attribute. As an example, the string_object object below is 43 bytes long:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n\n43\n\n\n\n\n1.8.2 A better look at the object type\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the @TypeOf() function. If we look at the type of the simple_array object below, you will find that this object is an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type i32 in Zig. That is what an object of type [4]i32 is.\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a constant pointer (hence the *const annotation) to an array of 16 elements (or 16 bytes). Each element is a single byte (more precisely, an unsigned 8 bit integer - u8), that is why we have the [16:0]u8 portion of the type below. In other words, the string literal value exposed below is 16 bytes long.\nNow, if we create an pointer to the simple_array object, then, we get a constant pointer to an array of 4 elements (*const [4]i32), which is very similar to the type of the string literal value. This demonstrates that a string literal value in Zig is already a pointer to a null-terminated array of bytes.\nFurthermore, if we take a look at the type of the string_obj object, you will see that it’s a slice object (hence the [] portion of the type) to a sequence of constant u8 values (hence the const u8 portion of the type).\n\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n\n\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n\n\n1.8.3 Byte vs unicode points\nIt’s important to point out that each byte in the array is not necessarily a single character. This fact arises from the difference between a single byte and a single unicode point.\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in the string. For example, the character “H” is stored in UTF-8 as the decimal number 72. This means that the number 72 is the unicode point for the character “H”. Each possible character that can appear in a UTF-8 encoded string have its own unicode point.\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point) 570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which is 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why, the unicode point 570 is actually stored inside the computer’s memory as the bytes C8 BA.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n\nBytes that represents the string object: C8 BA \n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together to represent the number 570. That is why the relationship between bytes and unicode points is not always 1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds to a single unicode point.\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the bytes that represents that string, and not through the characters of that string. In the Ⱥ example above, the for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a consequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because the number of bytes will be equal to the number of characters in that string. In other words, in this specific situation, the relationship between bytes and unicode points is 1 to 1.\nBut on the other side, if your string contains other types of letters… for example, you might be working with text data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent your UTF-8 string will likely be much higher than the number of characters in that string.\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the std.unicode.Utf8View struct to create an iterator that iterates through the unicode points of your string.\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in this string is represented by three bytes. But the for loop iterates four times, one iteration for each character/unicode point in this string:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n\n\n1.8.4 Some useful functions for strings\nIn this section, I just want to quickly describe some functions from the Zig Standard Library that are very useful to use when working with strings. Most notably:\n\nstd.mem.eql(): to compare if two strings are equal.\nstd.mem.splitScalar(): to split a string into an array of substrings given a delimiter value.\nstd.mem.splitSequence(): to split a string into an array of substrings given a substring delimiter.\nstd.mem.startsWith(): to check if string starts with substring.\nstd.mem.endsWith(): to check if string ends with substring.\nstd.mem.trim(): to remove specific values from both start and end of the string.\nstd.mem.concat(): to concatenate strings together.\nstd.mem.count(): to count the occurrences of substring in the string.\nstd.mem.replace(): to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the mem module of the Zig Standard Library. This module contains multiple functions and methods that are useful to work with memory and sequences of bytes in general.\nThe eql() function is used to check if two arrays of data are equal or not. Since strings are just arbitrary arrays of bytes, we can use this function to compare two strings together. This function returns a boolean value indicating if the two strings are equal or not. The first argument of this function is the data type of the elements of the arrays that are being compared.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n\ntrue\n\n\nThe splitScalar() and splitSequence() functions are useful to split a string into multiple fragments, like the split() method from Python strings. The difference between these two methods is that the splitScalar() uses a single character as the separator to split the string, while splitSequence() uses a sequence of characters (a.k.a. a substring) as the separator. There is a practical example of these functions later in the book.\nThe startsWith() and endsWith() functions are pretty straightforward. They return a boolean value indicating if the string (or, more precisely, if the array of data) begins (startsWith) or ends (endsWith) with the sequence provided.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n\ntrue\n\n\nThe concat() function, as the name suggests, concatenate two or more strings together. Because the process of concatenating the strings involves allocating enough space to accomodate all the strings together, this concat() function receives an allocator object as input.\n\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n\nAs you can imagine, the replace() function is used to replace substrings in a string by another substring. This function works very similarly to the replace() method from Python strings. Therefore, you provide a substring to search, and every time that the replace() function finds this substring within the input string, it replaces this substring with the “replacement substring” that you provided as input.\nIn the example below, we are taking the input string “Hello”, and replacing all occurrences of the substring “el” inside this input string with “34”, and saving the results inside the buffer object. As result, the replace() function returns an usize value that indicates how many replacements were performed.\n\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n\nNew string: H34lo\nN of replacements: 1",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -204,7 +204,7 @@
     "href": "Chapters/01-zig-weird.html#other-parts-of-zig",
     "title": "1  Introducing Zig",
     "section": "1.10 Other parts of Zig",
-    "text": "1.10 Other parts of Zig\nWe already learned a lot about Zig’s syntax, and also, some pretty technical details about it. Just as a quick recap:\n\nWe talked about how functions are written in Zig at Section 1.2.2 and Section 1.2.3.\nHow to create new objects/identifiers at Section 1.2.2 and especially at Section 1.4.\nHow strings work in Zig at Section 1.8.\nHow to use arrays and slices at Section 1.6.\nHow to import functionality from other Zig modules at Section 1.2.2.\n\nBut, for now, this amount of knowledge is enough for us to continue with this book. Later, over the next chapters we will still talk more about other parts of Zig’s syntax that are also equally important. Such as:\n\nHow Object-Oriented programming can be done in Zig through struct declarations at Section 2.3.\nBasic control flow syntax at Section 2.1.\nEnums at Section 7.6;\nPointers and Optionals at Chapter 6;\nError handling with try and catch at Chapter 10;\nUnit tests at Chapter 8;\nVectors at Chapter 17;\nBuild System at Chapter 9;\n\n\n\n\n\nKim, Juhee, Jinbum Park, Sihyeon Roh, Jaeyoung Chung, Youngjoo Lee, Taesoo Kim, and Byoungyoung Lee. 2024. “TikTag: Breaking ARM’s Memory Tagging Extension with Speculative Execution.” https://arxiv.org/abs/2406.08719.\n\n\nSobeston. 2024. “Zig Guide.” https://zig.guide/.",
+    "text": "1.10 Other parts of Zig\nWe already learned a lot about Zig’s syntax, and also, some pretty technical details about it. Just as a quick recap:\n\nWe talked about how functions are written in Zig in Section 1.2.2 and Section 1.2.3.\nHow to create new objects/identifiers in Section 1.2.2 and especially in Section 1.4.\nHow strings work in Zig in Section 1.8.\nHow to use arrays and slices in Section 1.6.\nHow to import functionality from other Zig modules in Section 1.2.2.\n\nBut, for now, this amount of knowledge is enough for us to continue with this book. Later, over the next chapters we will still talk more about other parts of Zig’s syntax that are also equally important. Such as:\n\nHow Object-Oriented programming can be done in Zig through struct declarations in Section 2.3.\nBasic control flow syntax in Section 2.1.\nEnums in Section 7.6;\nPointers and Optionals in Chapter 6;\nError handling with try and catch in Chapter 10;\nUnit tests in Chapter 8;\nVectors in Chapter 17;\nBuild System in Chapter 9;\n\n\n\n\n\nKim, Juhee, Jinbum Park, Sihyeon Roh, Jaeyoung Chung, Youngjoo Lee, Taesoo Kim, and Byoungyoung Lee. 2024. “TikTag: Breaking ARM’s Memory Tagging Extension with Speculative Execution.” https://arxiv.org/abs/2406.08719.\n\n\nSobeston. 2024. “Zig Guide.” https://zig.guide/.",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -234,7 +234,7 @@
     "href": "Chapters/03-structs.html#sec-zig-control-flow",
     "title": "2  Control flow, structs, modules and types",
     "section": "",
-    "text": "2.1.1 If/else statements\nAn if/else statement performs a “conditional flow operation”. A conditional flow control (or choice control) allows you to execute or ignore a certain block of commands based on a logical condition. Many programmers and computer science professionals also use the term “branching” in this case. In essence, an if/else statement allow us to use the result of a logical test to decide whether or not to execute a given block of commands.\nIn Zig, we write if/else statements by using the keywords if and else. We start with the if keyword followed by a logical test inside a pair of parentheses, followed by a pair of curly braces which contains the lines of code to be executed in case the logical test returns the value true.\nAfter that, you can optionally add an else statement. To do that, just add the else keyword followed by a pair of curly braces, with the lines of code to executed in case the logical test defined at if returns false.\nIn the example below, we are testing if the object x contains a number that is greater than 10. Judging by the output printed to the console, we know that this logical test returned false. Because the output in the console is compatible with the line of code present in the else branch of the if/else statement.\n\nconst x = 5;\nif (x &gt; 10) {\n    try stdout.print(\n        \"x &gt; 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x &lt;= 10!\\n\", .{}\n    );\n}\n\nx &lt;= 10!\n\n\n\n\n2.1.2 Switch statements\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust. As you would expect, to write a switch statement in Zig we use the switch keyword. We provide the value that we want to “switch over” inside a pair of parentheses. Then, we list the possible combinations (or “branches”) inside a pair of curly braces.\nLet’s take a look at the code example below. You can see that I’m creating an enum type called Role. We talk more about enums in Section 7.6. But in summary, this Role type is listing different types of roles in a fictitious company, like SE for Software Engineer, DE for Data Engineer, PM for Product Manager, etc.\nNotice that we are using the value from the role object in the switch statement, to discover which exact area we need to store in the area variable object. Also notice that we are using type inference inside the switch statement, with the dot character, as we are going to describe in Section 2.4. This makes the zig compiler infer the correct data type of the values (PM, SE, etc.) for us.\nAlso notice that, we are grouping multiple values in the same branch of the switch statement. We just separate each possible value with a comma. For example, if role contains either DE or DA, the area variable would contain the value \"Data & Analytics\", instead of \"Platform\" or \"Sales\".\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO =&gt; {\n            area = \"Platform\";\n        },\n        .DE, .DA =&gt; {\n            area = \"Data & Analytics\";\n        },\n        .KS =&gt; {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n\nPlatform\n\n\n\n2.1.2.1 Switch statements must exhaust all possibilities\nOne very important aspect about switch statements in Zig is that they must exhaust all existing possibilities. In other words, all possible values that could be found inside the role object must be explicitly handled in this switch statement.\nSince the role object has type Role, the only possible values to be found inside this object are PM, SE, DPE, PO, DE, DA and KS. There are no other possible values to be stored in this role object. Thus, the switch statements must have a combination (branch) for each one of these values. This is what “exhaust all existing possibilities” means. The switch statement covers every possible case.\nTherefore, you cannot write a switch statement in Zig, and leave an edge case with no explicit action to be taken. This is a similar behaviour to switch statements in Rust, which also have to handle all possible cases.\n\n\n2.1.2.2 The else branch\nTake a look at the dump_hex_fallible() function below as an example. This function comes from the Zig Standard Library. More precisely, from the debug.zig module1. There are multiple lines in this function, but I omitted them to focus solely on the switch statement found in this function. Notice that this switch statement has four possible cases (i.e. four explicit branches). Also, notice that we used an else branch in this case.\nAn else branch in a switch statement works as the “default branch”. Whenever you have multiple cases in your switch statement where you want to apply the exact same action, you can use an else branch to do that.\n\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' =&gt; try writer.writeAll(\"␊\"),\n        '\\r' =&gt; try writer.writeAll(\"␍\"),\n        '\\t' =&gt; try writer.writeAll(\"␉\"),\n        else =&gt; try writer.writeByte('.'),\n    }\n}\n\nMany programmers would also use an else branch to handle a “not supported” case. That is, a case that cannot be properly handled by your code, or, just a case that should not be “fixed”. Therefore, you can use an else branch to panic (or raise an error) in your program to stop the current execution.\nTake the code example below. We can see that, we are handling the cases for the level object being either 1, 2, or 3. All other possible cases are not supported by default, and, as consequence, we raise a runtime error in such cases through the @panic() built-in function.\nAlso notice that, we are assigning the result of the switch statement to a new object called category. This is another thing that you can do with switch statements in Zig. If a branch outputs a value as result, you can store the result value of the switch statement into a new object.\n\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 =&gt; \"beginner\",\n    3 =&gt; \"professional\",\n    else =&gt; {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n\n\n2.1.2.3 Using ranges in switch\nFurthermore, you can also use ranges of values in switch statements. That is, you can create a branch in your switch statement that is used whenever the input value is within the specified range. These “range expressions” are created with the operator .... It is important to emphasize that the ranges created by this operator are inclusive on both ends.\nFor example, I could easily change the previous code example to support all levels between 0 and 100. Like this:\n\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 =&gt; \"beginner\",\n    26...75 =&gt; \"intermediary\",\n    76...100 =&gt; \"professional\",\n    else =&gt; {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n\nbeginner\n\n\nThis is neat, and it works with character ranges too. That is, I could simply write 'a'...'z', to match any character value that is a lowercase letter, and it would work fine.\n\n\n2.1.2.4 Labeled switch statements\nIn Section 1.7 we have talked about labeling blocks, and also, about using these labels to return a value from the block. Well, from version 0.14.0 and onwards of the zig compiler, you can also apply labels over switch statements, which makes it possible to almost implement a “C goto” like pattern.\nFor example, if you give the label xsw to a switch statement, you can use this label in conjunction with the continue keyword to go back to the beginning of the switch statement. In the example below, the execution goes back to the beginning of the switch statement two times, before ending at the 3 branch.\n\nxsw: switch (@as(u8, 1)) {\n    1 =&gt; {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 =&gt; continue :xsw 3,\n    3 =&gt; return,\n    4 =&gt; {},\n    else =&gt; {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n\n\n\n\n2.1.3 The defer keyword\nWith the defer keyword you can register an expression to be executed when you exit the current scope. Therefore, this keyword has a similar functionality as the on.exit() function from R. Take the foo() function below as an example. When we execute this foo() function, the expression that prints the message “Exiting function …” is getting executed only when the function exits its scope.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n\nAdding some numbers ...\nMultiplying ...\nExiting function ...\nTherefore, we can use defer to declare an expression that is going to be executed when your code exits the current scope. Some programmers like to interpret the phrase “exit of the current scope” as “the end of the current scope”. But this interpretation might not be entirely correct, depending on what you consider as “the end of the current scope”.\nI mean, what do you consider as the end of the current scope? Is it the closing curly bracket (}) of the scope? Is it when the last expression in the function gets executed? Is it when the function returns to the previous scope? Etc. For example, it would not be correct to interpret the “exit of the current scope” as the closing curly bracket of the scope. Because the function might exit from an earlier position than this closing curly bracket (e.g. an error value was generated at a previous line inside the function; the function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\nNow, if you remember of what we have discussed in Section 1.7, there are multiple structures in the language that create their own separate scopes. For/while loops, if/else statements, functions, normal blocks, etc. This also affects the interpretation of defer. For example, if you use defer inside a for loop, then, the given expression will be executed everytime this specific for loop exits its own scope.\nBefore we continue, is worth emphasizing that the defer keyword is an “unconditional defer”. Which means that the given expression will be executed no matter how the code exits the current scope. For example, your code might exit the current scope because of an error value being generated, or, because of a return statement, or, a break statement, etc.\n\n\n2.1.4 The errdefer keyword\nOn the previous section, we have discussed the defer keyword, which you can use to register an expression to be executed at the exit of the current scope. But this keyword has a brother, which is the errdefer keyword. While defer is an “unconditional defer”, the errdefer keyword is a “conditional defer”. Which means that the given expression is executed only when you exit the current scope on a very specific circumstance.\nIn more details, the expression given to errdefer is executed only when an error occurs in the current scope. Therefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope in a normal situation, without errors, the expression given to errdefer is not executed.\nThis makes the errdefer keyword one of the many tools available in Zig for error handling. In this section, we are more concerned with the control flow aspects around errdefer. But we are going to discuss errdefer later as a error handling tool in Section 10.2.4.\nThe code example below demonstrates three things:\n\nthat defer is an “unconditional defer”, because the given expression get’s executed regardless of how the function foo() exits its own scope.\nthat errdefer is executed because the function foo() returned an error value.\nthat defer and errdefer expressions are executed in a LIFO (last in, first out) order.\n\n\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\nWhen I say that “defer expressions” are executed in a LIFO order, what I want to say is that the last defer or errdefer expressions in the code are the first ones to be executed. You could also interpret this as: “defer expressions” are executed from bottom to top, or, from last to first.\nTherefore, if I change the order of the defer and errdefer expressions, you will notice that the value of i that get’s printed to the console changes to 1. This doesn’t mean that the defer expression was not executed in this case. This actually means that the defer expression was executed only after the errdefer expression. The code example below demonstrates this:\n\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n\n\n2.1.5 For loops\nA loop allows you to execute the same lines of code multiple times, thus, creating a “repetition space” in the execution flow of your program. Loops are particularly useful when we want to replicate the same function (or the same set of commands) over different inputs.\nThere are different types of loops available in Zig. But the most essential of them all is probably the for loop. A for loop is used to apply the same piece of code over the elements of a slice, or, an array.\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from other languages. You start with the for keyword, then, you list the items that you want to iterate over inside a pair of parentheses. Then, inside of a pair of pipes (|) you should declare an identifier that will serve as your iterator, or, the “repetition index of the loop”.\n\nfor (items) |value| {\n    // code to execute\n}\n\nTherefore, instead of using a (value in items) syntax, in Zig, for loops use the syntax (items) |value|. In the example below, you can see that we are looping through the items of the array stored at the object name, and printing to the console the decimal representation of each character in this array.\nIf we wanted, we could also iterate through a slice (or a portion) of the array, instead of iterating through the entire array stored in the name object. Just use a range selector to select the section you want. For example, I could provide the expression name[0..3] to the for loop, to iterate just through the first 3 elements in the array.\n\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n\n80 | 101 | 100 | 114 | 111 | \n\n\nIn the above example we are using the value itself of each element in the array as our iterator. But there are many situations where we need to use an index instead of the actual values of the items.\nYou can do that by providing a second set of items to iterate over. More precisely, you provide the range selector 0.. to the for loop. So, yes, you can use two different iterators at the same time in a for loop in Zig.\nBut remember from Section 1.4 that, every object you create in Zig must be used in some way. So if you declare two iterators in your for loop, you must use both iterators inside the for loop body. But if you want to use just the index iterator, and not use the “value iterator”, then, you can discard the value iterator by maching the value items to the underscore character, like in the example below:\n\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n\n0 | 1 | 2 | 3 | 4 |\n\n\n2.1.6 While loops\nA while loop is created from the while keyword. A for loop iterates through the items of an array, but a while loop will loop continuously, and infinitely, until a logical test (specified by you) becomes false.\nYou start with the while keyword, then, you define a logical expression inside a pair of parentheses, and the body of the loop is provided inside a pair of curly braces, like in the example below:\n\nvar i: u8 = 1;\nwhile (i &lt; 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n\n1 | 2 | 3 | 4 | \n\n\nYou can also specify the increment expression to be used at the beginning of a while loop. To do that, we write the increment expression inside a pair of parentheses after a colon character (:). The code example below demonstrates this other pattern.\n\nvar i: u8 = 1;\nwhile (i &lt; 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n\n1 | 2 | 3 | 4 | \n\n\n\n\n2.1.7 Using break and continue\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using the keywords break and continue, respectively. The while loop presented in the next code example is, at first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to true. But what makes this while loop stop when the i object reaches the count 10? It is the break keyword!\nInside the while loop, we have an if statement that is constantly checking if the i variable is equal to 10. Since we are incrementing the value of i at each iteration of the while loop, this i object will eventually be equal to 10, and when it is, the if statement will execute the break expression, and, as a result, the execution of the while loop is stopped.\nNotice the use of the expect() function from the Zig Standard Library after the while loop. This expect() function is an “assert” type of function. This function checks if the logical test provided is equal to true. If so, the function do nothing. Otherwise (i.e. the logical test is equal to false), the function raises an assertion error.\n\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n\nEverything worked!\n\n\nSince this code example was executed successfully by the zig compiler, without raising any errors, we known that, after the execution of the while loop, the i object is equal to 10. Because if it wasn’t equal to 10, an error would have been raised by expect().\nNow, in the next example, we have a use case for the continue keyword. The if statement is constantly checking if the current index is a multiple of 2. If it is, we jump to the next iteration of the loop. Otherwise, the loop just prints the current index to the console.\n\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n\n1 | 3 | 5 |",
+    "text": "2.1.1 If/else statements\nAn if/else statement performs a “conditional flow operation”. A conditional flow control (or choice control) allows you to execute or ignore a certain block of commands based on a logical condition. Many programmers and computer science professionals also use the term “branching” in this case. In essence, an if/else statement allow us to use the result of a logical test to decide whether or not to execute a given block of commands.\nIn Zig, we write if/else statements by using the keywords if and else. We start with the if keyword followed by a logical test inside a pair of parentheses, followed by a pair of curly braces which contains the lines of code to be executed in case the logical test returns the value true.\nAfter that, you can optionally add an else statement. To do that, just add the else keyword followed by a pair of curly braces, with the lines of code to executed in case the logical test defined at if returns false.\nIn the example below, we are testing if the object x contains a number that is greater than 10. Judging by the output printed to the console, we know that this logical test returned false. Because the output in the console is compatible with the line of code present in the else branch of the if/else statement.\n\nconst x = 5;\nif (x &gt; 10) {\n    try stdout.print(\n        \"x &gt; 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x &lt;= 10!\\n\", .{}\n    );\n}\n\nx &lt;= 10!\n\n\n\n\n2.1.2 Switch statements\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust. As you would expect, to write a switch statement in Zig we use the switch keyword. We provide the value that we want to “switch over” inside a pair of parentheses. Then, we list the possible combinations (or “branches”) inside a pair of curly braces.\nLet’s take a look at the code example below. You can see that I’m creating an enum type called Role. We talk more about enums in Section 7.6. But in summary, this Role type is listing different types of roles in a fictitious company, like SE for Software Engineer, DE for Data Engineer, PM for Product Manager, etc.\nNotice that we are using the value from the role object in the switch statement, to discover which exact area we need to store in the area variable object. Also notice that we are using type inference inside the switch statement, with the dot character, as we are going to describe in Section 2.4. This makes the zig compiler infer the correct data type of the values (PM, SE, etc.) for us.\nAlso notice that, we are grouping multiple values in the same branch of the switch statement. We just separate each possible value with a comma. For example, if role contains either DE or DA, the area variable would contain the value \"Data & Analytics\", instead of \"Platform\" or \"Sales\".\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO =&gt; {\n            area = \"Platform\";\n        },\n        .DE, .DA =&gt; {\n            area = \"Data & Analytics\";\n        },\n        .KS =&gt; {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n\nPlatform\n\n\n\n2.1.2.1 Switch statements must exhaust all possibilities\nOne very important aspect about switch statements in Zig is that they must exhaust all existing possibilities. In other words, all possible values that could be found inside the role object must be explicitly handled in this switch statement.\nSince the role object has type Role, the only possible values to be found inside this object are PM, SE, DPE, PO, DE, DA and KS. There are no other possible values to be stored in this role object. Thus, the switch statements must have a combination (branch) for each one of these values. This is what “exhaust all existing possibilities” means. The switch statement covers every possible case.\nTherefore, you cannot write a switch statement in Zig, and leave an edge case with no explicit action to be taken. This is a similar behaviour to switch statements in Rust, which also have to handle all possible cases.\n\n\n2.1.2.2 The else branch\nTake a look at the dump_hex_fallible() function below as an example. This function comes from the Zig Standard Library. More precisely, from the debug.zig module1. There are multiple lines in this function, but I omitted them to focus solely on the switch statement found in this function. Notice that this switch statement has four possible cases (i.e., four explicit branches). Also, notice that we used an else branch in this case.\nAn else branch in a switch statement works as the “default branch”. Whenever you have multiple cases in your switch statement where you want to apply the exact same action, you can use an else branch to do that.\n\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' =&gt; try writer.writeAll(\"␊\"),\n        '\\r' =&gt; try writer.writeAll(\"␍\"),\n        '\\t' =&gt; try writer.writeAll(\"␉\"),\n        else =&gt; try writer.writeByte('.'),\n    }\n}\n\nMany programmers would also use an else branch to handle a “not supported” case. That is, a case that cannot be properly handled by your code, or, just a case that should not be “fixed”. Therefore, you can use an else branch to panic (or raise an error) in your program to stop the current execution.\nTake the code example below. We can see that, we are handling the cases for the level object being either 1, 2, or 3. All other possible cases are not supported by default, and, as consequence, we raise a runtime error in such cases through the @panic() built-in function.\nAlso notice that, we are assigning the result of the switch statement to a new object called category. This is another thing that you can do with switch statements in Zig. If a branch outputs a value as result, you can store the result value of the switch statement into a new object.\n\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 =&gt; \"beginner\",\n    3 =&gt; \"professional\",\n    else =&gt; {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n\n\n2.1.2.3 Using ranges in switch\nFurthermore, you can also use ranges of values in switch statements. That is, you can create a branch in your switch statement that is used whenever the input value is within the specified range. These “range expressions” are created with the operator .... It’s important to emphasize that the ranges created by this operator are inclusive on both ends.\nFor example, I could easily change the previous code example to support all levels between 0 and 100. Like this:\n\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 =&gt; \"beginner\",\n    26...75 =&gt; \"intermediary\",\n    76...100 =&gt; \"professional\",\n    else =&gt; {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n\nbeginner\n\n\nThis is neat, and it works with character ranges too. That is, I could simply write 'a'...'z', to match any character value that is a lowercase letter, and it would work fine.\n\n\n2.1.2.4 Labeled switch statements\nIn Section 1.7 we have talked about labeling blocks, and also, about using these labels to return a value from the block. Well, from version 0.14.0 and onwards of the zig compiler, you can also apply labels over switch statements, which makes it possible to almost implement a “C goto” like pattern.\nFor example, if you give the label xsw to a switch statement, you can use this label in conjunction with the continue keyword to go back to the beginning of the switch statement. In the example below, the execution goes back to the beginning of the switch statement two times, before ending at the 3 branch.\n\nxsw: switch (@as(u8, 1)) {\n    1 =&gt; {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 =&gt; continue :xsw 3,\n    3 =&gt; return,\n    4 =&gt; {},\n    else =&gt; {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n\n\n\n\n2.1.3 The defer keyword\nWith the defer keyword you can register an expression to be executed when you exit the current scope. Therefore, this keyword has a similar functionality as the on.exit() function from R. Take the foo() function below as an example. When we execute this foo() function, the expression that prints the message “Exiting function …” is getting executed only when the function exits its scope.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n\nAdding some numbers ...\nMultiplying ...\nExiting function ...\nTherefore, we can use defer to declare an expression that is going to be executed when your code exits the current scope. Some programmers like to interpret the phrase “exit of the current scope” as “the end of the current scope”. But this interpretation might not be entirely correct, depending on what you consider as “the end of the current scope”.\nI mean, what do you consider as the end of the current scope? Is it the closing curly bracket (}) of the scope? Is it when the last expression in the function gets executed? Is it when the function returns to the previous scope? Etc. For example, it would not be correct to interpret the “exit of the current scope” as the closing curly bracket of the scope. Because the function might exit from an earlier position than this closing curly bracket (e.g. an error value was generated at a previous line inside the function; the function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\nNow, if you remember of what we have discussed in Section 1.7, there are multiple structures in the language that create their own separate scopes. For/while loops, if/else statements, functions, normal blocks, etc. This also affects the interpretation of defer. For example, if you use defer inside a for loop, then, the given expression will be executed everytime this specific for loop exits its own scope.\nBefore we continue, it’s worth emphasizing that the defer keyword is an “unconditional defer”. Which means that the given expression will be executed no matter how the code exits the current scope. For example, your code might exit the current scope because of an error value being generated, or, because of a return statement, or, a break statement, etc.\n\n\n2.1.4 The errdefer keyword\nOn the previous section, we have discussed the defer keyword, which you can use to register an expression to be executed at the exit of the current scope. But this keyword has a brother, which is the errdefer keyword. While defer is an “unconditional defer”, the errdefer keyword is a “conditional defer”. Which means that the given expression is executed only when you exit the current scope on a very specific circumstance.\nIn more details, the expression given to errdefer is executed only when an error occurs in the current scope. Therefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope in a normal situation, without errors, the expression given to errdefer is not executed.\nThis makes the errdefer keyword one of the many tools available in Zig for error handling. In this section, we are more concerned with the control flow aspects around errdefer. But we are going to discuss errdefer later as a error handling tool in Section 10.2.4.\nThe code example below demonstrates three things:\n\nthat defer is an “unconditional defer”, because the given expression gets executed regardless of how the function foo() exits its own scope.\nthat errdefer is executed because the function foo() returned an error value.\nthat defer and errdefer expressions are executed in a LIFO (last in, first out) order.\n\n\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\nWhen I say that “defer expressions” are executed in a LIFO order, what I want to say is that the last defer or errdefer expressions in the code are the first ones to be executed. You could also interpret this as: “defer expressions” are executed from bottom to top, or, from last to first.\nTherefore, if I change the order of the defer and errdefer expressions, you will notice that the value of i that gets printed to the console changes to 1. This doesn’t mean that the defer expression was not executed in this case. This actually means that the defer expression was executed only after the errdefer expression. The code example below demonstrates this:\n\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n\n\n2.1.5 For loops\nA loop allows you to execute the same lines of code multiple times, thus, creating a “repetition space” in the execution flow of your program. Loops are particularly useful when we want to replicate the same function (or the same set of commands) over different inputs.\nThere are different types of loops available in Zig. But the most essential of them all is probably the for loop. A for loop is used to apply the same piece of code over the elements of a slice, or, an array.\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from other languages. You start with the for keyword, then, you list the items that you want to iterate over inside a pair of parentheses. Then, inside of a pair of pipes (|) you should declare an identifier that will serve as your iterator, or, the “repetition index of the loop”.\n\nfor (items) |value| {\n    // code to execute\n}\n\nTherefore, instead of using a (value in items) syntax, in Zig, for loops use the syntax (items) |value|. In the example below, you can see that we are looping through the items of the array stored at the object name, and printing to the console the decimal representation of each character in this array.\nIf we wanted, we could also iterate through a slice (or a portion) of the array, instead of iterating through the entire array stored in the name object. Just use a range selector to select the section you want. For example, I could provide the expression name[0..3] to the for loop, to iterate just through the first 3 elements in the array.\n\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n\n80 | 101 | 100 | 114 | 111 | \n\n\nIn the above example we are using the value itself of each element in the array as our iterator. But there are many situations where we need to use an index instead of the actual values of the items.\nYou can do that by providing a second set of items to iterate over. More precisely, you provide the range selector 0.. to the for loop. So, yes, you can use two different iterators at the same time in a for loop in Zig.\nBut remember from Section 1.4 that, every object you create in Zig must be used in some way. So if you declare two iterators in your for loop, you must use both iterators inside the for loop body. But if you want to use just the index iterator, and not use the “value iterator”, then, you can discard the value iterator by maching the value items to the underscore character, like in the example below:\n\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n\n0 | 1 | 2 | 3 | 4 |\n\n\n2.1.6 While loops\nA while loop is created from the while keyword. A for loop iterates through the items of an array, but a while loop will loop continuously, and infinitely, until a logical test (specified by you) becomes false.\nYou start with the while keyword, then, you define a logical expression inside a pair of parentheses, and the body of the loop is provided inside a pair of curly braces, like in the example below:\n\nvar i: u8 = 1;\nwhile (i &lt; 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n\n1 | 2 | 3 | 4 | \n\n\nYou can also specify the increment expression to be used at the beginning of a while loop. To do that, we write the increment expression inside a pair of parentheses after a colon character (:). The code example below demonstrates this other pattern.\n\nvar i: u8 = 1;\nwhile (i &lt; 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n\n1 | 2 | 3 | 4 | \n\n\n\n\n2.1.7 Using break and continue\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using the keywords break and continue, respectively. The while loop presented in the next code example is, at first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to true. But what makes this while loop stop when the i object reaches the count 10? It’s the break keyword!\nInside the while loop, we have an if statement that is constantly checking if the i variable is equal to 10. Since we are incrementing the value of i at each iteration of the while loop, this i object will eventually be equal to 10, and when it is, the if statement will execute the break expression, and, as a result, the execution of the while loop is stopped.\nNotice the use of the expect() function from the Zig Standard Library after the while loop. This expect() function is an “assert” type of function. This function checks if the logical test provided is equal to true. If so, the function do nothing. Otherwise (i.e., the logical test is equal to false), the function raises an assertion error.\n\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n\nEverything worked!\n\n\nSince this code example was executed successfully by the zig compiler, without raising any errors, we known that, after the execution of the while loop, the i object is equal to 10. Because if it wasn’t equal to 10, an error would have been raised by expect().\nNow, in the next example, we have a use case for the continue keyword. The if statement is constantly checking if the current index is a multiple of 2. If it is, we jump to the next iteration of the loop. Otherwise, the loop just prints the current index to the console.\n\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n\n1 | 3 | 5 |",
     "crumbs": [
       "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
     ]
@@ -244,7 +244,7 @@
     "href": "Chapters/03-structs.html#sec-fun-pars",
     "title": "2  Control flow, structs, modules and types",
     "section": "2.2 Function parameters are immutable",
-    "text": "2.2 Function parameters are immutable\nWe have already discussed a lot of the syntax behind function declarations in Section 1.2.2 and Section 1.2.3. But I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig. In summary, function parameters are immutable in Zig.\nTake the code example below, where we declare a simple function that just tries to add some amount to the input integer, and returns the result back. If you look closely at the body of this add2() function, you will notice that we try to save the result back into the x function argument.\nIn other words, this function not only uses the value that it received through the function argument x, but it also tries to change the value of this function argument, by assigning the addition result into x. However, function arguments in Zig are immutable. You cannot change their values, or, you cannot assign values to them inside the body’s function.\nThis is the reason why, the code example below does not compile successfully. If you try to compile this code example, you will get a compile error message about “trying to change the value of a immutable (i.e. constant) object”.\n\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n\n2.2.1 A free optimization\nIf a function argument receives as input an object whose data type is any of the primitive types that we have listed in Section 1.5, this object is always passed by value to the function. In other words, this object is copied into the function stack frame.\nHowever, if the input object have a more complex data type, for example, it might be a struct instance, or an array, or an union value, etc., in cases like that, the zig compiler will take the liberty of deciding for you which strategy is best. Thus, the zig compiler will pass your object to the function either by value, or by reference. The compiler will always choose the strategy that is faster for you. This optimization that you get for free is possible only because function arguments are immutable in Zig.\n\n\n2.2.2 How to overcome this barrier\nThere are some situations where you might need to change the value of your function argument directly inside the function’s body. This happens more often when we are passing C structs as inputs to Zig functions.\nIn a situation like this, you can overcome this barrier by using a pointer. In other words, instead of passing a value as input to the argument, you can pass a “pointer to value” instead. You can change the value that the pointer points to, by dereferencing it.\nTherefore, if we take our previous add2() example, we can change the value of the function argument x inside the function’s body by marking the x argument as a “pointer to a u32 value” (i.e. *u32 data type), instead of a u32 value. By making it a pointer, we can finally alter the value of this function argument directly inside the body of the add2() function. You can see that the code example below compiles successfully.\n\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n\nResult: 6\nEven in this code example above, the x argument is still immutable. Which means that the pointer itself is immutable. Therefore, you cannot change the memory address that it points to. However, you can dereference the pointer to access the value that it points to, and also, to change this value, if you need to.",
+    "text": "2.2 Function parameters are immutable\nWe have already discussed a lot of the syntax behind function declarations in Section 1.2.2 and Section 1.2.3. But I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig. In summary, function parameters are immutable in Zig.\nTake the code example below, where we declare a simple function that just tries to add some amount to the input integer, and returns the result back. If you look closely at the body of this add2() function, you will notice that we try to save the result back into the x function argument.\nIn other words, this function not only uses the value that it received through the function argument x, but it also tries to change the value of this function argument, by assigning the addition result into x. However, function arguments in Zig are immutable. You cannot change their values, or, you cannot assign values to them inside the body’s function.\nThis is the reason why, the code example below does not compile successfully. If you try to compile this code example, you will get a compile error message about “trying to change the value of a immutable (i.e., constant) object”.\n\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n\n2.2.1 A free optimization\nIf a function argument receives as input an object whose data type is any of the primitive types that we have listed in Section 1.5, this object is always passed by value to the function. In other words, this object is copied into the function stack frame.\nHowever, if the input object have a more complex data type, for example, it might be a struct instance, or an array, or an union value, etc., in cases like that, the zig compiler will take the liberty of deciding for you which strategy is best. Thus, the zig compiler will pass your object to the function either by value, or by reference. The compiler will always choose the strategy that is faster for you. This optimization that you get for free is possible only because function arguments are immutable in Zig.\n\n\n2.2.2 How to overcome this barrier\nThere are some situations where you might need to change the value of your function argument directly inside the function’s body. This happens more often when we are passing C structs as inputs to Zig functions.\nIn a situation like this, you can overcome this barrier by using a pointer. In other words, instead of passing a value as input to the argument, you can pass a “pointer to value” instead. You can change the value that the pointer points to, by dereferencing it.\nTherefore, if we take our previous add2() example, we can change the value of the function argument x inside the function’s body by marking the x argument as a “pointer to a u32 value” (i.e., *u32 data type), instead of a u32 value. By making it a pointer, we can finally alter the value of this function argument directly inside the body of the add2() function. You can see that the code example below compiles successfully.\n\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n\nResult: 6\nEven in this code example above, the x argument is still immutable. Which means that the pointer itself is immutable. Therefore, you cannot change the memory address that it points to. However, you can dereference the pointer to access the value that it points to, and also, to change this value, if you need to.",
     "crumbs": [
       "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
     ]
@@ -254,7 +254,7 @@
     "href": "Chapters/03-structs.html#sec-structs-and-oop",
     "title": "2  Control flow, structs, modules and types",
     "section": "2.3 Structs and OOP",
-    "text": "2.3 Structs and OOP\nZig is a language more closely related to C (which is a procedural language), than it is to C++ or Java (which are object-oriented languages). Because of that, you do not have advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or class inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C. You give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can also register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object that you create with this new type, will always have these methods available and associated with them.\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which is used to construct (or, to instantiate) every object of this particular class, and we also have a destructor method (or a destructor function), which is the function responsible for destroying every object of this class.\nIn Zig, we normally declare the constructor and the destructor methods of our structs, by declaring an init() and a deinit() methods inside the struct. This is just a naming convention that you will find across the entire Zig Standard Library. So, in Zig, the init() method of a struct is normally the constructor method of the class represented by this struct. While the deinit() method is the method used for destroying an existing instance of that struct.\nThe init() and deinit() methods are both used extensively in Zig code, and you will see both of them being used when we talk about allocators in Section 3.3. But, as another example, let’s build a simple User struct to represent a user of some sort of system.\nIf you look at the User struct below, you can see the struct keyword. Notice the data members of this struct: id, name and email. Every data member has its type explicitly annotated, with the colon character (:) syntax that we described earlier in Section 1.2.2. But also notice that every line in the struct body that describes a data member, ends with a comma character (,). So every time you declare a data member in your Zig code, always end the line with a comma character, instead of ending it with the traditional semicolon character (;).\nNext, we have registered an init() function as a method of this User struct. This init() method is the constructor method that we will use to instantiate every new User object. That is why this init() function returns a new User object as result.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    pub fn init(id: u64,\n                name: []const u8,\n                email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    pub fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n\npedro\n\n\nThe pub keyword plays an important role in struct declarations, and OOP in Zig. Every method that you declare in your struct that is marked with the keyword pub, becomes a public method of this particular struct.\nSo every method that you create inside your struct, is, at first, a private method of that struct. Meaning that, this method can only be called from within this struct. But, if you mark this method as public, with the keyword pub, then, you can call the method directly from an instance of the User struct.\nIn other words, the functions marked by the keyword pub are members of the public API of that struct. For example, if I did not mark the print_name() method as public, then, I could not execute the line u.print_name(). Because I would not be authorized to call this method directly in my code.\n\n2.3.1 Anonymous struct literals\nYou can declare a struct object as a literal value. When we do that, we normally specify the data type of this struct literal by writing its data type just before the opening curly brace. For example, I could write a struct literal value of the type User that we have defined in the previous section like this:\n\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a struct literal, but not specify explicitly the type of this particular struct. An anonymous struct is written by using the syntax .{}. So, we essentially replaced the explicit type of the struct literal with a dot character (.).\nAs we described in Section 2.4, when you put a dot before a struct literal, the type of this struct literal is automatically inferred by the zig compiler. In essence, the zig compiler will look for some hint of what is the type of that struct. This hint can be the type annotation of a function argument, or the return type annotation of the function that you are using, or the type annotation of an existing object. If the compiler does find such type annotation, it will use this type in your literal struct.\nAnonymous structs are very commonly used as inputs to function arguments in Zig. One example that you have seen already constantly, is the print() function from the stdout object. This function takes two arguments. The first argument, is a template string, which should contain string format specifiers in it, which tells how the values provided in the second argument should be printed into the message.\nWhile the second argument is a struct literal that lists the values to be printed into the template message specified in the first argument. You normally want to use an anonymous struct literal here, so that the zig compiler do the job of specifying the type of this particular anonymous struct for you.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n\nHello, world!\n\n\n\n\n2.3.2 Struct declarations must be constant\nTypes in Zig must be const or comptime (we are going to talk more about comptime in Section 12.1). What this means is that you cannot create a new data type, and mark it as variable with the var keyword. So struct declarations are always constant. You cannot declare a new struct type using the var keyword. It must be const.\nIn the Vec3 example below, this declaration is allowed because I’m using the const keyword to declare this new data type.\n\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n\n\n\n2.3.3 The self method argument\nIn every language that have OOP, when we declare a method of some class or struct, we usually declare this method as a function that has a self argument. This self argument is the reference to the object itself from which the method is being called from.\nIt is not mandatory to use this self argument. But why would you not use this self argument? There is no reason to not use it. Because the only way to get access to the data stored in the data members of your struct is to access them through this self argument. If you don’t need to use the data in the data members of your struct inside your method, you very likely don’t need a method. You can just declare this logic as a simple function, outside of your struct declaration.\nTake the Vec3 struct below. Inside this Vec3 struct we declared a method named distance(). This method calculates the distance between two Vec3 objects, by following the distance formula in euclidean space. Notice that this distance() method takes two Vec3 objects as input, self and other.\n\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n\nThe self argument corresponds to the Vec3 object from which this distance() method is being called from. While the other is a separate Vec3 object that is given as input to this method. In the example below, the self argument corresponds to the object v1, because the distance() method is being called from the v1 object, while the other argument corresponds to the object v2.\n\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n\nDistance: 3.3970575502926055\n\n\n2.3.4 About the struct state\nSometimes you don’t need to care about the state of your struct object. Sometimes, you just need to instantiate and use the objects, without altering their state. You can notice that when you have methods inside your struct declaration that might use the values that are present in the data members, but they do not alter the values in these data members of the struct in anyway.\nThe Vec3 struct that was presented in Section 2.3.3 is an example of that. This struct have a single method named distance(), and this method does use the values present in all three data members of the struct (x, y and z). But at the same time, this method does not change the values of these data members at any point.\nAs a result of that, when we create Vec3 objects we usually create them as constant objects, like the v1 and v2 objects presented in Section 2.3.3. We can create them as variable objects with the var keyword, if we want to. But because the methods of this Vec3 struct do not change the state of the objects in any point, it’s unnecessary to mark them as variable objects.\nBut why? Why am I talking about this here? It’s because the self argument in the methods are affected depending on whether the methods present in a struct change or don’t change the state of the object itself. More specifically, when you have a method in a struct that changes the state of the object (i.e. changes the value of a data member), the self argument in this method must be annotated in a different manner.\nAs I described in Section 2.3.3, the self argument in methods of a struct is the argument that receives as input the object from which the method was called from. We usually annotate this argument in the methods by writing self, followed by the colon character (:), and the data type of the struct to which the method belongs to (e.g. User, Vec3, etc.).\nIf we take the Vec3 struct that we defined in the previous section as an example, we can see in the distance() method that this self argument is annotated as self: Vec3. Because the state of the Vec3 object is never altered by this method.\nBut what if we do have a method that alters the state of the object, by altering the values of its data members, how should we annotate self in this instance? The answer is: “we should annotate self as a pointer of x, instead of just x”. In other words, you should annotate self as self: *x, instead of annotating it as self: x.\nIf we create a new method inside the Vec3 object that, for example, expands the vector by multiplying its coordinates by a factor of two, then, we need to follow this rule specified in the previous paragraph. The code example below demonstrates this idea:\n\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n\nNotice in the code example above that we have added a new method to our Vec3 struct named twice(). This method doubles the coordinate values of our vector object. In the case of the twice() method, we annotated the self argument as *Vec3, indicating that this argument receives a pointer (or a reference, if you prefer to call it this way) to a Vec3 object as input.\n\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n\nDoubled: 8.4\nNow, if you change the self argument in this twice() method to self: Vec3, like in the distance() method, you will get the compiler error exposed below as result. Notice that this error message is showing a line from the twice() method body, indicating that you cannot alter the value of the x data member.\n\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\nThis error message indicates that the x data member belongs to a constant object, and, because of that, it cannot be changed. Ultimately, this error message is telling us that the self argument is constant.\nIf you take some time, and think hard about this error message, you will understand it. You already have the tools to understand why we are getting this error message. We have talked about it already in Section 2.2. So remember, every function argument is immutable in Zig, and self is no exception to this rule.\nIn this example, we marked the v3 object as a variable object. But this does not matter. Because it is not about the input object, it is about the function argument.\nThe problem begins when we try to alter the value of self directly, which is a function argument, and, every function argument is immutable by default. You may ask yourself how can we overcome this barrier, and once again, the solution was also discussed in Section 2.2. We overcome this barrier, by explicitly marking the self argument as a pointer.\n\n\n\n\n\n\nNote\n\n\n\nIf a method of your x struct alters the state of the object, by changing the value of any data member, then, remember to use self: *x, instead of self: x in the function signature of this method.\n\n\nYou could also interpret the content discussed in this section as: “if you need to alter the state of your x struct object in one of its methods, you must explicitly pass the x struct object by reference to the self argument of this method”.",
+    "text": "2.3 Structs and OOP\nZig is a language more closely related to C (which is a procedural language), than it is to C++ or Java (which are object-oriented languages). Because of that, you do not have advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or class inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C. You give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can also register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object that you create with this new type, will always have these methods available and associated with them.\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which is used to construct (or, to instantiate) every object of this particular class, and we also have a destructor method (or a destructor function), which is the function responsible for destroying every object of this class.\nIn Zig, we normally declare the constructor and the destructor methods of our structs, by declaring an init() and a deinit() methods inside the struct. This is just a naming convention that you will find across the entire Zig Standard Library. So, in Zig, the init() method of a struct is normally the constructor method of the class represented by this struct. While the deinit() method is the method used for destroying an existing instance of that struct.\nThe init() and deinit() methods are both used extensively in Zig code, and you will see both of them being used when we talk about allocators in Section 3.3. But, as another example, let’s build a simple User struct to represent a user of some sort of system.\nIf you look at the User struct below, you can see the struct keyword. Notice the data members of this struct: id, name and email. Every data member has its type explicitly annotated, with the colon character (:) syntax that we described earlier in Section 1.2.2. But also notice that every line in the struct body that describes a data member, ends with a comma character (,). So every time you declare a data member in your Zig code, always end the line with a comma character, instead of ending it with the traditional semicolon character (;).\nNext, we have registered an init() function as a method of this User struct. This init() method is the constructor method that we will use to instantiate every new User object. That is why this init() function returns a new User object as result.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    pub fn init(id: u64,\n                name: []const u8,\n                email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    pub fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n\npedro\n\n\nThe pub keyword plays an important role in struct declarations, and OOP in Zig. Every method that you declare in your struct that is marked with the keyword pub, becomes a public method of this particular struct.\nSo every method that you create inside your struct, is, at first, a private method of that struct. Meaning that, this method can only be called from within this struct. But, if you mark this method as public, with the keyword pub, then, you can call the method directly from an instance of the User struct.\nIn other words, the functions marked by the keyword pub are members of the public API of that struct. For example, if I did not mark the print_name() method as public, then, I could not execute the line u.print_name(). Because I would not be authorized to call this method directly in my code.\n\n2.3.1 Anonymous struct literals\nYou can declare a struct object as a literal value. When we do that, we normally specify the data type of this struct literal by writing its data type just before the opening curly brace. For example, I could write a struct literal value of the type User that we have defined in the previous section like this:\n\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a struct literal, but not specify explicitly the type of this particular struct. An anonymous struct is written by using the syntax .{}. So, we essentially replaced the explicit type of the struct literal with a dot character (.).\nAs we described in Section 2.4, when you put a dot before a struct literal, the type of this struct literal is automatically inferred by the zig compiler. In essence, the zig compiler will look for some hint of what is the type of that struct. This hint can be the type annotation of a function argument, or the return type annotation of the function that you are using, or the type annotation of an existing object. If the compiler does find such type annotation, it will use this type in your literal struct.\nAnonymous structs are very commonly used as inputs to function arguments in Zig. One example that you have seen already constantly, is the print() function from the stdout object. This function takes two arguments. The first argument, is a template string, which should contain string format specifiers in it, which tells how the values provided in the second argument should be printed into the message.\nWhile the second argument is a struct literal that lists the values to be printed into the template message specified in the first argument. You normally want to use an anonymous struct literal here, so that the zig compiler do the job of specifying the type of this particular anonymous struct for you.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n\nHello, world!\n\n\n\n\n2.3.2 Struct declarations must be constant\nTypes in Zig must be const or comptime (we are going to talk more about comptime in Section 12.1). What this means is that you cannot create a new data type, and mark it as variable with the var keyword. So struct declarations are always constant. You cannot declare a new struct type using the var keyword. It must be const.\nIn the Vec3 example below, this declaration is allowed because I’m using the const keyword to declare this new data type.\n\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n\n\n\n2.3.3 The self method argument\nIn every language that have OOP, when we declare a method of some class or struct, we usually declare this method as a function that has a self argument. This self argument is the reference to the object itself from which the method is being called from.\nIt’s not mandatory to use this self argument. But why would you not use this self argument? There is no reason to not use it. Because the only way to get access to the data stored in the data members of your struct is to access them through this self argument. If you don’t need to use the data in the data members of your struct inside your method, you very likely don’t need a method. You can just declare this logic as a simple function, outside of your struct declaration.\nTake the Vec3 struct below. Inside this Vec3 struct we declared a method named distance(). This method calculates the distance between two Vec3 objects, by following the distance formula in euclidean space. Notice that this distance() method takes two Vec3 objects as input, self and other.\n\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n\nThe self argument corresponds to the Vec3 object from which this distance() method is being called from. While the other is a separate Vec3 object that is given as input to this method. In the example below, the self argument corresponds to the object v1, because the distance() method is being called from the v1 object, while the other argument corresponds to the object v2.\n\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n\nDistance: 3.3970575502926055\n\n\n2.3.4 About the struct state\nSometimes you don’t need to care about the state of your struct object. Sometimes, you just need to instantiate and use the objects, without altering their state. You can notice that when you have methods inside your struct declaration that might use the values that are present in the data members, but they do not alter the values in these data members of the struct in anyway.\nThe Vec3 struct that was presented in Section 2.3.3 is an example of that. This struct have a single method named distance(), and this method does use the values present in all three data members of the struct (x, y and z). But at the same time, this method does not change the values of these data members at any point.\nAs a result of that, when we create Vec3 objects we usually create them as constant objects, like the v1 and v2 objects presented in Section 2.3.3. We can create them as variable objects with the var keyword, if we want to. But because the methods of this Vec3 struct do not change the state of the objects in any point, it’s unnecessary to mark them as variable objects.\nBut why? Why am I talking about this here? It’s because the self argument in the methods are affected depending on whether the methods present in a struct change or don’t change the state of the object itself. More specifically, when you have a method in a struct that changes the state of the object (i.e., changes the value of a data member), the self argument in this method must be annotated in a different manner.\nAs I described in Section 2.3.3, the self argument in methods of a struct is the argument that receives as input the object from which the method was called from. We usually annotate this argument in the methods by writing self, followed by the colon character (:), and the data type of the struct to which the method belongs to (e.g. User, Vec3, etc.).\nIf we take the Vec3 struct that we defined in the previous section as an example, we can see in the distance() method that this self argument is annotated as self: Vec3. Because the state of the Vec3 object is never altered by this method.\nBut what if we do have a method that alters the state of the object, by altering the values of its data members, how should we annotate self in this instance? The answer is: “we should annotate self as a pointer of x, instead of just x”. In other words, you should annotate self as self: *x, instead of annotating it as self: x.\nIf we create a new method inside the Vec3 object that, for example, expands the vector by multiplying its coordinates by a factor of two, then, we need to follow this rule specified in the previous paragraph. The code example below demonstrates this idea:\n\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n\nNotice in the code example above that we have added a new method to our Vec3 struct named twice(). This method doubles the coordinate values of our vector object. In the case of the twice() method, we annotated the self argument as *Vec3, indicating that this argument receives a pointer (or a reference, if you prefer to call it this way) to a Vec3 object as input.\n\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n\nDoubled: 8.4\nNow, if you change the self argument in this twice() method to self: Vec3, like in the distance() method, you will get the compiler error exposed below as result. Notice that this error message is showing a line from the twice() method body, indicating that you cannot alter the value of the x data member.\n\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\nThis error message indicates that the x data member belongs to a constant object, and, because of that, it cannot be changed. Ultimately, this error message is telling us that the self argument is constant.\nIf you take some time, and think hard about this error message, you will understand it. You already have the tools to understand why we are getting this error message. We have talked about it already in Section 2.2. So remember, every function argument is immutable in Zig, and self is no exception to this rule.\nIn this example, we marked the v3 object as a variable object. But this does not matter. Because it’s not about the input object, it’s about the function argument.\nThe problem begins when we try to alter the value of self directly, which is a function argument, and, every function argument is immutable by default. You may ask yourself how can we overcome this barrier, and once again, the solution was also discussed in Section 2.2. We overcome this barrier, by explicitly marking the self argument as a pointer.\n\n\n\n\n\n\nNote\n\n\n\nIf a method of your x struct alters the state of the object, by changing the value of any data member, then, remember to use self: *x, instead of self: x in the function signature of this method.\n\n\nYou could also interpret the content discussed in this section as: “if you need to alter the state of your x struct object in one of its methods, you must explicitly pass the x struct object by reference to the self argument of this method”.",
     "crumbs": [
       "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
     ]
@@ -264,7 +264,7 @@
     "href": "Chapters/03-structs.html#sec-type-inference",
     "title": "2  Control flow, structs, modules and types",
     "section": "2.4 Type inference",
-    "text": "2.4 Type inference\nZig is a strongly typed language. But, there are some situations where you don’t have to explicitly write the type of every single object in your source code, as you would expect from a traditional strongly typed language, such as C and C++.\nIn some situations, the zig compiler can use type inference to solve the data types for you, easing some of the burden that you carry as a developer. The most common way this happens is through function arguments that receive struct objects as input.\nIn general, type inference in Zig is done by using the dot character (.). Everytime you see a dot character written before a struct literal, or before an enum value, or something like that, you know that this dot character is playing a special part in this place. More specifically, it is telling the zig compiler something along the lines of: “Hey! Can you infer the type of this value for me? Please!”. In other words, this dot character is playing a similar role as the auto keyword in C++.\nI gave you some examples of this in Section 2.3.1, where we used anonymous struct literals. Anonymous struct literals are, struct literals that use type inference to infer the exact type of this particular struct literal. This type inference is done by looking for some minimal hint of the correct data type to be used. You could say that the zig compiler looks for any neighbouring type annotation that might tell it what the correct type would be.\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in Section 2.1.2). I also gave some other examples of type inference in Section 2.1.2, where we were inferring the data types of enum values listed inside of switch statements (e.g. .DE). But as another example, take a look at this fence() function reproduced below, which comes from the atomic.zig module2 of the Zig Standard Library.\nThere are a lot of things in this function that we haven’t talked about yet, such as: what comptime means? inline? extern? Let’s just ignore all of these things, and focus solely on the switch statement that is inside this function.\nWe can see that this switch statement uses the order object as input. This order object is one of the inputs of this fence() function, and we can see in the type annotation, that this object is of type AtomicOrder. We can also see a bunch of values inside the switch statements that begin with a dot character, such as .release and .acquire.\nBecause these weird values contain a dot character before them, we are asking the zig compiler to infer the types of these values inside the switch statement. Then, the zig compiler is looking into the current context where these values are being used, and it is trying to infer the types of these values.\nSince they are being used inside a switch statement, the zig compiler looks into the type of the input object given to the switch statement, which is the order object in this case. Because this object have type AtomicOrder, the zig compiler infers that these values are data members from this type AtomicOrder.\n\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic =&gt; @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire =&gt; tsan.__tsan_acquire(addr),\n            .release =&gt; tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst =&gt; {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n\nThis is how basic type inference is done in Zig. If we didn’t use the dot character before the values inside this switch statement, then, we would be forced to explicitly write the data types of these values. For example, instead of writing .release we would have to write AtomicOrder.release. We would have to do this for every single value in this switch statement, and this is a lot of work. That is why type inference is commonly used on switch statements in Zig.",
+    "text": "2.4 Type inference\nZig is a strongly typed language. But, there are some situations where you don’t have to explicitly write the type of every single object in your source code, as you would expect from a traditional strongly typed language, such as C and C++.\nIn some situations, the zig compiler can use type inference to solve the data types for you, easing some of the burden that you carry as a developer. The most common way this happens is through function arguments that receive struct objects as input.\nIn general, type inference in Zig is done by using the dot character (.). Everytime you see a dot character written before a struct literal, or before an enum value, or something like that, you know that this dot character is playing a special part in this place. More specifically, it’s telling the zig compiler something along the lines of: “Hey! Can you infer the type of this value for me? Please!”. In other words, this dot character is playing a similar role as the auto keyword in C++.\nI gave you some examples of this in Section 2.3.1, where we used anonymous struct literals. Anonymous struct literals are, struct literals that use type inference to infer the exact type of this particular struct literal. This type inference is done by looking for some minimal hint of the correct data type to be used. You could say that the zig compiler looks for any neighbouring type annotation that might tell it what the correct type would be.\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in Section 2.1.2). I also gave some other examples of type inference in Section 2.1.2, where we were inferring the data types of enum values listed inside of switch statements (e.g. .DE). But as another example, take a look at this fence() function reproduced below, which comes from the atomic.zig module2 of the Zig Standard Library.\nThere are a lot of things in this function that we haven’t talked about yet, such as: what comptime means? inline? extern? Let’s just ignore all of these things, and focus solely on the switch statement that is inside this function.\nWe can see that this switch statement uses the order object as input. This order object is one of the inputs of this fence() function, and we can see in the type annotation, that this object is of type AtomicOrder. We can also see a bunch of values inside the switch statements that begin with a dot character, such as .release and .acquire.\nBecause these weird values contain a dot character before them, we are asking the zig compiler to infer the types of these values inside the switch statement. Then, the zig compiler is looking into the current context where these values are being used, and trying to infer the types of these values.\nSince they are being used inside a switch statement, the zig compiler looks into the type of the input object given to the switch statement, which is the order object in this case. Because this object have type AtomicOrder, the zig compiler infers that these values are data members from this type AtomicOrder.\n\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic =&gt; @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire =&gt; tsan.__tsan_acquire(addr),\n            .release =&gt; tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst =&gt; {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n\nThis is how basic type inference is done in Zig. If we didn’t use the dot character before the values inside this switch statement, then, we would be forced to explicitly write the data types of these values. For example, instead of writing .release we would have to write AtomicOrder.release. We would have to do this for every single value in this switch statement, and this is a lot of work. That is why type inference is commonly used on switch statements in Zig.",
     "crumbs": [
       "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
     ]
@@ -274,7 +274,7 @@
     "href": "Chapters/03-structs.html#sec-type-cast",
     "title": "2  Control flow, structs, modules and types",
     "section": "2.5 Type casting",
-    "text": "2.5 Type casting\nIn this section, I want to discuss type casting (or, type conversion) with you. We use type casting when we have an object of type “x”, and we want to convert it into an object of type “y”, i.e. we want to change the data type of the object.\nMost languages have a formal way to perform type casting. In Rust for example, we normally use the keyword as, and in C, we normally use the type casting syntax, e.g. (int) x. In Zig, we use the @as() built-in function to cast an object of type “x”, into an object of type “y”.\nThis @as() function is the preferred way to perform type conversion (or type casting) in Zig. Because it is explicit, and, it also performs the casting only if it is unambiguous and safe. To use this function, you just provide the target data type in the first argument, and, the object that you want cast as the second argument.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n\n1/1 file9f8940318094.test_0...OKAll 1 tests passed\n  d.\n\n\nThis is the general way to perform type casting in Zig. But remember, @as() works only when casting is unambiguous and safe, and there are situations where these assumptions do not hold. For example, when casting an integer value into a float value, or vice-versa, it is not clear to the compiler how to perform this conversion safely.\nTherefore, we need to use specialized “casting functions” in such situations. For example, if you want to cast an integer value into a float value, then, you should use the @floatFromInt() function. In the inverse scenario, you should use the @intFromFloat() function.\nIn these functions, you just provide the object that you want to cast as input. Then, the target data type of the “type casting operation” is determined by the type annotation of the object where you are saving the results. In the example below, we are casting the object x into a value of type f32, because the object y, which is where we are saving the results, is annotated as an object of type f32.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n\n1/1 file9f8954828844.test_0...OKAll 1 tests passed\n  d.\n\n\nAnother built-in function that is very useful when performing type casting operations is @ptrCast(). In essence, we use the @as() built-in function when we want to explicit convert (or cast) a Zig value/object from a type “x” to a type “y”, etc. However, pointers (we are going to discuss pointers in more depth in Chapter 6) are a special type of object in Zig, i.e. they are treated differently from “normal objects”.\nEverytime a pointer is involved in some “type casting operation” in Zig, the @ptrCast() function is used. This function works similarly to @floatFromInt(). You just provide the pointer object that you want to cast as input to this function, and the target data type is, once again, determined by the type annotation of the object where the results are being stored.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n\n1/1 file9f8944ca02e1.test_0...OKAll 1 tests passed\n  d.",
+    "text": "2.5 Type casting\nIn this section, I want to discuss type casting (or, type conversion) with you. We use type casting when we have an object of type “x”, and we want to convert it into an object of type “y”, i.e., we want to change the data type of the object.\nMost languages have a formal way to perform type casting. In Rust for example, we normally use the keyword as, and in C, we normally use the type casting syntax, e.g. (int) x. In Zig, we use the @as() built-in function to cast an object of type “x”, into an object of type “y”.\nThis @as() function is the preferred way to perform type conversion (or type casting) in Zig. Because it’s explicit, and, it also performs the casting only if it is unambiguous and safe. To use this function, you just provide the target data type in the first argument, and, the object that you want cast as the second argument.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n\n1/1 file79ce58134f59.test_0...OKAll 1 tests passed\n  d.\n\n\nThis is the general way to perform type casting in Zig. But remember, @as() works only when casting is unambiguous and safe. There are many situations where these assumptions do not hold. For example,\nwhen casting an integer value into a float value, or vice-versa, it’s not clear to the compiler how to perform this conversion safely.\nTherefore, we need to use specialized “casting functions” in such situations. For example, if you want to cast an integer value into a float value, then, you should use the @floatFromInt() function. In the inverse scenario, you should use the @intFromFloat() function.\nIn these functions, you just provide the object that you want to cast as input. Then, the target data type of the “type casting operation” is determined by the type annotation of the object where you are saving the results. In the example below, we are casting the object x into a value of type f32, because the object y, which is where we are saving the results, is annotated as an object of type f32.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n\n1/1 file79ce286cee5b.test_0...OKAll 1 tests passed\n  d.\n\n\nAnother built-in function that is very useful when performing type casting operations is @ptrCast(). In essence, we use the @as() built-in function when we want to explicit convert (or cast) a Zig value/object from a type “x” to a type “y”, etc. However, pointers (we are going to discuss pointers in more depth in Chapter 6) are a special type of object in Zig, i.e., they are treated differently from “normal objects”.\nEverytime a pointer is involved in some “type casting operation” in Zig, the @ptrCast() function is used. This function works similarly to @floatFromInt(). You just provide the pointer object that you want to cast as input to this function, and the target data type is, once again, determined by the type annotation of the object where the results are being stored.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n\n1/1 file79ce1e7313c8.test_0...OKAll 1 tests passed\n  d.",
     "crumbs": [
       "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
     ]
@@ -284,7 +284,7 @@
     "href": "Chapters/03-structs.html#modules",
     "title": "2  Control flow, structs, modules and types",
     "section": "2.6 Modules",
-    "text": "2.6 Modules\nWe already talked about what modules are, and also, how to import other modules into your current module via import statements. Every Zig module (i.e. a .zig file) that you write in your project is internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the Zig Standard Library into our current module.\n\nconst std = @import(\"std\");\n\nWhen we want to access the functions and objects from the standard library, we are basically accessing the data members of the struct stored in the std object. That is why we use the same syntax that we use in normal structs, with the dot operator (.) to access the data members and methods of the struct.\nWhen this “import statement” get’s executed, the result of this expression is a struct object that contains the Zig Standard Library modules, global variables, functions, etc. And this struct object get’s saved (or stored) inside the constant object named std.\nTake the thread_pool.zig module from the project zap3 as an example. This module is written as if it was a big struct. That is why we have a top-level and public init() method written in this module. The idea is that all top-level functions written in this module are methods from the struct, and all top-level objects and struct declarations are data members of this struct. The module is the struct itself.\nSo you would import and use this module by doing something like this:\n\nconst std = @import(\"std\");\nconst ThreadPool = @import(\"thread_pool.zig\");\nconst num_cpus = std.Thread.getCpuCount()\n    catch @panic(\"failed to get cpu core count\");\nconst num_threads = std.math.cast(u16, num_cpus)\n    catch std.math.maxInt(u16);\nconst pool = ThreadPool.init(\n    .{ .max_threads = num_threads }\n);",
+    "text": "2.6 Modules\nWe already talked about what modules are, and also, how to import other modules into your current module via import statements. Every Zig module (i.e., a .zig file) that you write in your project is internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the Zig Standard Library into our current module.\n\nconst std = @import(\"std\");\n\nWhen we want to access the functions and objects from the standard library, we are basically accessing the data members of the struct stored in the std object. That is why we use the same syntax that we use in normal structs, with the dot operator (.) to access the data members and methods of the struct.\nWhen this “import statement” gets executed, the result of this expression is a struct object that contains the Zig Standard Library modules, global variables, functions, etc. And this struct object gets saved (or stored) inside the constant object named std.\nTake the thread_pool.zig module from the project zap3 as an example. This module is written as if it was a big struct. That is why we have a top-level and public init() method written in this module. The idea is that all top-level functions written in this module are methods from the struct, and all top-level objects and struct declarations are data members of this struct. The module is the struct itself.\nSo you would import and use this module by doing something like this:\n\nconst std = @import(\"std\");\nconst ThreadPool = @import(\"thread_pool.zig\");\nconst num_cpus = std.Thread.getCpuCount()\n    catch @panic(\"failed to get cpu core count\");\nconst num_threads = std.math.cast(u16, num_cpus)\n    catch std.math.maxInt(u16);\nconst pool = ThreadPool.init(\n    .{ .max_threads = num_threads }\n);",
     "crumbs": [
       "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
     ]
@@ -314,7 +314,7 @@
     "href": "Chapters/01-memory.html#memory-spaces",
     "title": "3  Memory and Allocators",
     "section": "",
-    "text": "Global data register (or the “global data section”);\nStack;\nHeap;\n\n\n3.1.1 Compile-time known versus runtime known\nOne strategy that Zig uses to decide where it will store each object that you declare, is by looking at the value of this particular object. More specifically, by investigating if this value is known at “compile-time” or at “runtime”.\nWhen you write a program in Zig, the values of some of the objects that you write in your program are known at compile time. Meaning that, when you compile your Zig source code, during the compilation process, the zig compiler can figure out the exact value of a particular object that exists in your source code. Knowing the length (or the size) of each object is also important. So the length (or the size) of each object that you write in your program is, in some cases, known at compile time.\nThe zig compiler cares more about knowing the length (or the size) of a particular object , than to know its actual value. But, if the zig compiler knows the value of the object, then, it automatically knows the size of this object. Because it can simply calculate the size of the object by looking at the size of the value.\nTherefore, the priority for the zig compiler is to discover the size of each object in your source code. If the value of the object in question is known at compile-time, then, the zig compiler automatically knows the size/length of this object. But if the value of this object is not known at compile-time, then, the size of this object is only known at compile-time if, and only if, the type of this object has a known fixed size.\nIn order for a type to have a known fixed size, this type must have data members whose size is fixed. If this type includes, for example, a variable sized array in it, then, this type does not have a known fixed size. Because this array can have any size at runtime (i.e. it can be an array of 2 elements, or 50 elements, or 1 thousand elements, etc.).\nFor example, a string object, which internally is an array of constant u8 values ([]const u8) has a variable size. It can be a string object with 100 or 500 characters in it. If we do not know at compile-time, which exact string will be stored inside this string object, then, we cannot calculate the size of this string object at compile-time. So, any type, or any struct declaration that you make, that includes a string data member that does not have an explicit fixed size, makes this type, or this new struct that you are declaring, a type that does not have a known fixed size at compile-time.\nIn contrast, if the type of this struct that you are declaring, includes a data member that is an array, but this array has a known fixed size, like [60]u8 (which declares an array of 60 u8 values), then, this type, or, this struct that you are declaring, becomes a type with a known fixed size at compile-time. And because of that, in this case, the zig compiler does not need to know at compile-time the exact value of any object of this type. Since the compiler can find the necessary size to store this object by looking at the size of its type.\nLet’s look at an example. In the source code below, we have two constant objects (name and array) declared. Because the values of these particular objects are written down, in the source code itself (\"Pedro\" and the number sequence from 1 to 4), the zig compiler can easily discover the values of these constant objects (name and array) during the compilation process. This is what “known at compile time” means. It refers to any object that you have in your Zig source code whose value can be identified at compile time.\n\nfn input_length(input: []const u8) usize {\n    const n = input.len;\n    return n;\n}\n\npub fn main() !void {\n    const name = \"Pedro\";\n    const array = [_]u8{1, 2, 3, 4};\n    _ = name; _ = array;\n}\n\nThe other side of the spectrum are objects whose values are not known at compile time. Function arguments are a classic example of this. Because the value of each function argument depends on the value that you assign to this particular argument, when you call the function.\nFor example, the function input_length() contains an argument named input, which is an array of constant u8 integers ([]const u8). It is impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length of this particular argument. Because it is an array that do not have a fixed size specified explicitly in the argument type annotation.\nSo, we know that this input argument will be an array of u8 integers. But we do not know at compile-time, its value, and neither its size. This information is known only at runtime, which is the period of time when you program is executed. As a consequence, the value of the expression input.len is also known only at runtime. This is an intrinsic characteristic of any function. Just remember that the value of function arguments is usually not “compile-time known”.\nHowever, as I mentioned earlier, what really matters to the compiler is to know the size of the object at compile-time, and not necessarily its value. So, although we don’t know the value of the object n, which is the result of the expression input.len, at compile-time, we do know its size. Because the expression input.len always returns a value of type usize, and the type usize has a known fixed size.\n\n\n3.1.2 Global data register\nThe global data register is a specific section of the executable of your Zig program, that is responsible for storing any value that is known at compile time.\nEvery constant object whose value is known at compile time that you declare in your source code, is stored in the global data register. Also, every literal value that you write in your source code, such as the string \"this is a string\", or the integer 10, or a boolean value such as true, is also stored in the global data register.\nHonestly, you don’t need to care much about this memory space. Because you can’t control it, you can’t deliberately access it or use it for your own purposes. Also, this memory space does not affect the logic of your program. It simply exists in your program.\n\n\n3.1.3 Stack vs Heap\nIf you are familiar with systems programming, or just low-level programming in general, you probably have heard of the “duel” between Stack vs Heap. These are two different types of memory, or different memory spaces, which are both available in Zig.\nThese two types of memory don’t actually duel with each other. This is a common mistake that beginners have, when seeing “x vs y” styles of tabloid headlines. These two types of memory are actually complementary to each other. So, in almost every Zig program that you ever write, you will likely use a combination of both. I will describe each memory space in detail over the next sections. But for now, I just want to stablish the main difference between these two types of memory.\nIn essence, the stack memory is normally used to store values whose length is fixed and known at compile time. In contrast, the heap memory is a dynamic type of memory space, meaning that, it is used to store values whose length might grow during the execution (runtime) of your program (Chen and Guo 2022).\nLengths that grow during runtime are intrinsically associated with “runtime known” type of values. In other words, if you have an object whose length might grow during runtime, then, the length of this object becomes not known at compile time. If the length is not known at compile-time, the value of this object also becomes not known at compile-time. These types of objects should be stored in the heap memory space, which is a dynamic memory space, which can grow or shrink to fit the size of your objects.\n\n\n3.1.4 Stack\nThe stack is a type of memory that uses the power of the stack data structure, hence the name. A “stack” is a type of data structure that uses a “last in, first out” (LIFO) mechanism to store the values you give it to. I imagine you are familiar with this data structure. But, if you are not, the Wikipedia page1 , or, the Geeks For Geeks page2 are both excellent and easy resources to fully understand how this data structure works.\nSo, the stack memory space is a type of memory that stores values using a stack data structure. It adds and removes values from the memory by following a “last in, first out” (LIFO) principle.\nEvery time you make a function call in Zig, an amount of space in the stack is reserved for this particular function call (Chen and Guo 2022; Zig Software Foundation 2024). The value of each function argument given to the function in this function call is stored in this stack space. Also, every local object that you declare inside the function scope is usually stored in this same stack space.\nLooking at the example below, the object result is a local object declared inside the scope of the add() function. Because of that, this object is stored inside the stack space reserved for the add() function. The r object (which is declared outside of the add() function scope) is also stored in the stack. But since it is declared in the “outer” scope, this object is stored in the stack space that belongs to this outer scope.\n\nfn add(x: u8, y: u8) u8 {\n    const result = x + y;\n    return result;\n}\n\npub fn main() !void {\n    const r = add(5, 27);\n    _ = r;\n}\n\nSo, any object that you declare inside the scope of a function is always stored inside the space that was reserved for that particular function in the stack memory. This also counts for any object declared inside the scope of your main() function for example. As you would expect, in this case, they are stored inside the stack space reserved for the main() function.\nOne very important detail about the stack memory is that it frees itself automatically. This is very important, remember that. When objects are stored in the stack memory, you don’t have the work (or the responsibility) of freeing/destroying these objects. Because they will be automatically destroyed once the stack space is freed at the end of the function scope.\nSo, once the function call returns (or ends, if you prefer to call it this way) the space that was reserved in the stack is destroyed, and all of the objects that were in that space goes away with it. This mechanism exists because this space, and the objects within it, are not necessary anymore, since the function “finished its business”. Using the add() function that we exposed above as an example, it means that the object result is automatically destroyed once the function returns.\n\n\n\n\n\n\nImportant\n\n\n\nLocal objects that are stored in the stack space of a function are automatically freed/destroyed at the end of the function scope.\n\n\nThis same logic applies to any other special structure in Zig that has its own scope by surrounding it with curly braces ({}). For loops, while loops, if else statements, etc. For example, if you declare any local object in the scope of a for loop, this local object is accessible only within the scope of this particular for loop. Because once the scope of this for loop ends, the space in the stack reserved for this for loop is freed. The example below demonstrates this idea.\n\n// This does not compile successfully!\nconst a = [_]u8{0, 1, 2, 3, 4};\nfor (0..a.len) |i| {\n    const index = i;\n    _ = index;\n}\n// Trying to use an object that was\n// declared in the for loop scope,\n// and that does not exist anymore.\nstd.debug.print(\"{d}\\n\", .{index});\n\nOne important consequence of this mechanism is that, once the function returns, you can no longer access any memory address that was inside the space in the stack reserved for this particular function. Because this space was destroyed. This means that, if this local object is stored in the stack, you cannot make a function that returns a pointer to this object.\nThink about that for a second. If all local objects in the stack are destroyed at the end of the function scope, why would you even consider returning a pointer to one of these objects? This pointer is at best, invalid, or, more likely, “undefined”.\nConclusion, it is totally fine to write a function that returns the local object itself as result, because then, you return the value of that object as the result. But, if this local object is stored in the stack, you should never write a function that returns a pointer to this local object. Because the memory address pointed by the pointer no longer exists.\nSo, using again the add() function as an example, if you rewrite this function so that it returns a pointer to the local object result, the zig compiler will actually compile your program, with no warnings or errors. At first glance, it looks that this is good code that works as expected. But this is a lie!\nIf you try to take a look at the value inside of the r object, or, if you try to use this r object in another expression or function call, then, you would have undefined behaviour, and major bugs in your program (Zig Software Foundation 2024, see “Lifetime and Ownership”3 and “Undefined Behaviour”4 sections).\n\nfn add(x: u8, y: u8) *const u8 {\n    const result = x + y;\n    return &result;\n}\n\npub fn main() !void {\n    // This code compiles successfully. But it has\n    // undefined behaviour. Never do this!!!\n    // The `r` object is undefined!\n    const r = add(5, 27); _ = r;\n}\n\nThis “invalid pointer to stack variable” problem is well known across many programming language communities. If you try to do the same thing, for example, in a C or C++ program (i.e. returning an address to a local object stored in the stack), you would also get undefined behaviour in the program.\n\n\n\n\n\n\nImportant\n\n\n\nIf a local object in your function is stored in the stack, you should never return a pointer to this local object from the function. Because this pointer will always become undefined after the function returns, since the stack space of the function is destroyed at the end of its scope.\n\n\nBut what if you really need to use this local object in some way after your function returns? How can you do this? The answer is: “in the same way you would do if this were a C or C++ program. By returning an address to an object stored in the heap”. The heap memory has a much more flexible lifecycle, and allows you to get a valid pointer to a local object of a function that already returned from its scope.\n\n\n3.1.5 Heap\nOne important limitation of the stack, is that, only objects whose length/size is known at compile-time can be stored in it. In contrast, the heap is a much more dynamic (and flexible) type of memory. It is the perfect type of memory to use for objects whose size/length might grow during the execution of your program.\nVirtually any application that behaves as a server is a classic use case of the heap. A HTTP server, a SSH server, a DNS server, a LSP server, … any type of server. In summary, a server is a type of application that runs for long periods of time, and that serves (or “deals with”) any incoming request that reaches this particular server.\nThe heap is a good choice for this type of system, mainly because the server does not know upfront how many requests it will receive from users, while it is active. It could be a single request, 5 thousand requests, or even zero requests. The server needs to have the ability to allocate and manage its memory according to how many requests it receives.\nAnother key difference between the stack and the heap, is that the heap is a type of memory that you, the programmer, have complete control over. This makes the heap a more flexible type of memory, but it also makes it harder to work with. Because you, the programmer, is responsible for managing everything related to it. Including where the memory is allocated, how much memory is allocated, and where this memory is freed.\n\nUnlike stack memory, heap memory is allocated explicitly by programmers and it won’t be deallocated until it is explicitly freed (Chen and Guo 2022).\n\nTo store an object in the heap, you, the programmer, needs to explicitly tells Zig to do so, by using an allocator to allocate some space in the heap. At Section 3.3, I will present how you can use allocators to allocate memory in Zig.\n\n\n\n\n\n\nImportant\n\n\n\nEvery memory you allocate in the heap needs to be explicitly freed by you, the programmer.\n\n\nThe majority of allocators in Zig do allocate memory on the heap. But some exceptions to this rule are ArenaAllocator() and FixedBufferAllocator(). The ArenaAllocator() is a special type of allocator that works in conjunction with a second type of allocator. On the other side, the FixedBufferAllocator() is an allocator that works based on buffer objects created on the stack. This means that the FixedBufferAllocator() makes allocations only on the stack.\n\n\n3.1.6 Summary\nAfter discussing all of these boring details, we can quickly recap what we learned. In summary, the Zig compiler will use the following rules to decide where each object you declare is stored:\n\nevery literal value (such as \"this is string\", 10, or true) is stored in the global data section.\nevery constant object (const) whose value is known at compile-time is also stored in the global data section.\nevery object (constant or not) whose length/size is known at compile time is stored in the stack space for the current scope.\nif an object is created with the method alloc() or create() of an allocator object, this object is stored in the memory space used by this particular allocator object. Most of allocators available in Zig use the heap memory, so, this object is likely stored in the heap (FixedBufferAllocator() is an exception to that).\nthe heap can only be accessed through allocators. If your object was not created through the alloc() or create() methods of an allocator object, then, it is most certainly not an object stored in the heap.",
+    "text": "Global data register (or the “global data section”);\nStack;\nHeap;\n\n\n3.1.1 Compile-time known versus runtime known\nOne strategy that Zig uses to decide where it will store each object that you declare, is by looking at the value of this particular object. More specifically, by investigating if this value is known at “compile-time” or at “runtime”.\nWhen you write a program in Zig, the values of some of the objects that you write in your program are known at compile time. Meaning that, when you compile your Zig source code, during the compilation process, the zig compiler can figure out the exact value of a particular object that exists in your source code. Knowing the length (or the size) of each object is also important. So the length (or the size) of each object that you write in your program is, in some cases, known at compile time.\nThe zig compiler cares more about knowing the length (or the size) of a particular object , than to know its actual value. But, if the zig compiler knows the value of the object, then, it automatically knows the size of this object. Because it can simply calculate the size of the object by looking at the size of the value.\nTherefore, the priority for the zig compiler is to discover the size of each object in your source code. If the value of the object in question is known at compile-time, then, the zig compiler automatically knows the size/length of this object. But if the value of this object is not known at compile-time, then, the size of this object is only known at compile-time if, and only if, the type of this object has a known fixed size.\nIn order for a type to have a known fixed size, this type must have data members whose size is fixed. If this type includes, for example, a variable sized array in it, then, this type does not have a known fixed size. Because this array can have any size at runtime (i.e., it can be an array of 2 elements, or 50 elements, or 1 thousand elements, etc.).\nFor example, a string object, which internally is an array of constant u8 values ([]const u8) has a variable size. It can be a string object with 100 or 500 characters in it. If we do not know at compile-time, which exact string will be stored inside this string object, then, we cannot calculate the size of this string object at compile-time. So, any type, or any struct declaration that you make, that includes a string data member that does not have an explicit fixed size, makes this type, or this new struct that you are declaring, a type that does not have a known fixed size at compile-time.\nIn contrast, if the type of this struct that you are declaring, includes a data member that is an array, but this array has a known fixed size, like [60]u8 (which declares an array of 60 u8 values), then, this type, or, this struct that you are declaring, becomes a type with a known fixed size at compile-time. And because of that, in this case, the zig compiler does not need to know at compile-time the exact value of any object of this type. Since the compiler can find the necessary size to store this object by looking at the size of its type.\nLet’s look at an example. In the source code below, we have two constant objects (name and array) declared. Because the values of these particular objects are written down, in the source code itself (\"Pedro\" and the number sequence from 1 to 4), the zig compiler can easily discover the values of these constant objects (name and array) during the compilation process. This is what “known at compile time” means. It refers to any object that you have in your Zig source code whose value can be identified at compile time.\n\nfn input_length(input: []const u8) usize {\n    const n = input.len;\n    return n;\n}\n\npub fn main() !void {\n    const name = \"Pedro\";\n    const array = [_]u8{1, 2, 3, 4};\n    _ = name; _ = array;\n}\n\nThe other side of the spectrum are objects whose values are not known at compile time. Function arguments are a classic example of this. Because the value of each function argument depends on the value that you assign to this particular argument, when you call the function.\nFor example, the function input_length() contains an argument named input, which is an array of constant u8 integers ([]const u8). It’s impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length of this particular argument. Because it’s an array that does not have a fixed size specified explicitly in the argument type annotation.\nSo, we know that this input argument will be an array of u8 integers. But we do not know at compile-time, its value, and neither its size. This information is known only at runtime, which is the period of time when you program is executed. As a consequence, the value of the expression input.len is also known only at runtime. This is an intrinsic characteristic of any function. Just remember that the value of function arguments is usually not “compile-time known”.\nHowever, as I mentioned earlier, what really matters to the compiler is to know the size of the object at compile-time, and not necessarily its value. So, although we don’t know the value of the object n, which is the result of the expression input.len, at compile-time, we do know its size. Because the expression input.len always returns a value of type usize, and the type usize has a known fixed size.\n\n\n3.1.2 Global data register\nThe global data register is a specific section of the executable of your Zig program, that is responsible for storing any value that is known at compile time.\nEvery constant object whose value is known at compile time that you declare in your source code, is stored in the global data register. Also, every literal value that you write in your source code, such as the string \"this is a string\", or the integer 10, or a boolean value such as true, is also stored in the global data register.\nHonestly, you don’t need to care much about this memory space. Because you can’t control it, you can’t deliberately access it or use it for your own purposes. Also, this memory space does not affect the logic of your program. It simply exists in your program.\n\n\n3.1.3 Stack vs Heap\nIf you are familiar with systems programming, or just low-level programming in general, you probably have heard of the “duel” between Stack vs Heap. These are two different types of memory, or different memory spaces, which are both available in Zig.\nThese two types of memory don’t actually duel with each other. This is a common mistake that beginners have, when seeing “x vs y” styles of tabloid headlines. These two types of memory are actually complementary to each other. So, in almost every Zig program that you ever write, you will likely use a combination of both. I will describe each memory space in detail over the next sections. But for now, I just want to stablish the main difference between these two types of memory.\nIn essence, the stack memory is normally used to store values whose length is fixed and known at compile time. In contrast, the heap memory is a dynamic type of memory space, meaning that, it’s used to store values whose length might grow during the execution (runtime) of your program (Chen and Guo 2022).\nLengths that grow during runtime are intrinsically associated with “runtime known” type of values. In other words, if you have an object whose length might grow during runtime, then, the length of this object becomes not known at compile time. If the length is not known at compile-time, the value of this object also becomes not known at compile-time. These types of objects should be stored in the heap memory space, which is a dynamic memory space, which can grow or shrink to fit the size of your objects.\n\n\n3.1.4 Stack\nThe stack is a type of memory that uses the power of the stack data structure, hence the name. A “stack” is a type of data structure that uses a “last in, first out” (LIFO) mechanism to store the values you give it to. I imagine you are familiar with this data structure. But, if you are not, the Wikipedia page1 , or, the Geeks For Geeks page2 are both excellent and easy resources to fully understand how this data structure works.\nSo, the stack memory space is a type of memory that stores values using a stack data structure. It adds and removes values from the memory by following a “last in, first out” (LIFO) principle.\nEvery time you make a function call in Zig, an amount of space in the stack is reserved for this particular function call (Chen and Guo 2022; Zig Software Foundation 2024). The value of each function argument given to the function in this function call is stored in this stack space. Also, every local object that you declare inside the function scope is usually stored in this same stack space.\nLooking at the example below, the object result is a local object declared inside the scope of the add() function. Because of that, this object is stored inside the stack space reserved for the add() function. The r object (which is declared outside of the add() function scope) is also stored in the stack. But since it’s declared in the “outer” scope, this object is stored in the stack space that belongs to this outer scope.\n\nfn add(x: u8, y: u8) u8 {\n    const result = x + y;\n    return result;\n}\n\npub fn main() !void {\n    const r = add(5, 27);\n    _ = r;\n}\n\nSo, any object that you declare inside the scope of a function is always stored inside the space that was reserved for that particular function in the stack memory. This also counts for any object declared inside the scope of your main() function for example. As you would expect, in this case, they are stored inside the stack space reserved for the main() function.\nOne very important detail about the stack memory is that it frees itself automatically. This is very important, remember that. When objects are stored in the stack memory, you don’t have the work (or the responsibility) of freeing/destroying these objects. Because they will be automatically destroyed once the stack space is freed at the end of the function scope.\nSo, once the function call returns (or ends, if you prefer to call it this way) the space that was reserved in the stack is destroyed, and all of the objects that were in that space goes away with it. This mechanism exists because this space, and the objects within it, are not necessary anymore, since the function “finished its business”. Using the add() function that we exposed above as an example, it means that the object result is automatically destroyed once the function returns.\n\n\n\n\n\n\nImportant\n\n\n\nLocal objects that are stored in the stack space of a function are automatically freed/destroyed at the end of the function scope.\n\n\nThis same logic applies to any other special structure in Zig that has its own scope by surrounding it with curly braces ({}). For loops, while loops, if else statements, etc. For example, if you declare any local object in the scope of a for loop, this local object is accessible only within the scope of this particular for loop. Because once the scope of this for loop ends, the space in the stack reserved for this for loop is freed. The example below demonstrates this idea.\n\n// This does not compile successfully!\nconst a = [_]u8{0, 1, 2, 3, 4};\nfor (0..a.len) |i| {\n    const index = i;\n    _ = index;\n}\n// Trying to use an object that was\n// declared in the for loop scope,\n// and that does not exist anymore.\nstd.debug.print(\"{d}\\n\", .{index});\n\nOne important consequence of this mechanism is that, once the function returns, you can no longer access any memory address that was inside the space in the stack reserved for this particular function. Because this space was destroyed. This means that, if this local object is stored in the stack, you cannot make a function that returns a pointer to this object.\nThink about that for a second. If all local objects in the stack are destroyed at the end of the function scope, why would you even consider returning a pointer to one of these objects? This pointer is at best, invalid, or, more likely, “undefined”.\nIn conclusion, it’s totally fine to write a function that returns the local object itself as result, because then, you return the value of that object as the result. But, if this local object is stored in the stack, you should never write a function that returns a pointer to this local object. Because the memory address pointed by the pointer no longer exists.\nSo, using again the add() function as an example, if you rewrite this function so that it returns a pointer to the local object result, the zig compiler will actually compile your program, with no warnings or errors. At first glance, it looks like this is good code that works as expected. But this is a lie!\nIf you try to take a look at the value inside of the r object, or, if you try to use this r object in another expression or function call, then, you would have undefined behaviour, and major bugs in your program (Zig Software Foundation 2024, see “Lifetime and Ownership”3 and “Undefined Behaviour”4 sections).\n\nfn add(x: u8, y: u8) *const u8 {\n    const result = x + y;\n    return &result;\n}\n\npub fn main() !void {\n    // This code compiles successfully. But it has\n    // undefined behaviour. Never do this!!!\n    // The `r` object is undefined!\n    const r = add(5, 27); _ = r;\n}\n\nThis “invalid pointer to stack variable” problem is well known across many programming language communities. If you try to do the same thing, for example, in a C or C++ program (i.e., returning an address to a local object stored in the stack), you would also get undefined behaviour in the program.\n\n\n\n\n\n\nImportant\n\n\n\nIf a local object in your function is stored in the stack, you should never return a pointer to this local object from the function. Because this pointer will always become undefined after the function returns, since the stack space of the function is destroyed at the end of its scope.\n\n\nBut what if you really need to use this local object in some way after your function returns? How can you do this? The answer is: “in the same way you would do if this were a C or C++ program. By returning an address to an object stored in the heap”. The heap memory has a much more flexible lifecycle, and allows you to get a valid pointer to a local object of a function that already returned from its scope.\n\n\n3.1.5 Heap\nOne important limitation of the stack, is that, only objects whose length/size is known at compile-time can be stored in it. In contrast, the heap is a much more dynamic (and flexible) type of memory. It’s the perfect type of memory to use for objects whose size/length might grow during the execution of your program.\nVirtually any application that behaves as a server is a classic use case of the heap. A HTTP server, a SSH server, a DNS server, a LSP server, … any type of server. In summary, a server is a type of application that runs for long periods of time, and that serves (or “deals with”) any incoming request that reaches this particular server.\nThe heap is a good choice for this type of system, mainly because the server does not know upfront how many requests it will receive from users, while it is active. It could be a single request, 5 thousand requests, or even zero requests. The server needs to have the ability to allocate and manage its memory according to how many requests it receives.\nAnother key difference between the stack and the heap, is that the heap is a type of memory that you, the programmer, have complete control over. This makes the heap a more flexible type of memory, but it also makes it harder to work with. Because you, the programmer, is responsible for managing everything related to it. Including where the memory is allocated, how much memory is allocated, and where this memory is freed.\n\nUnlike stack memory, heap memory is allocated explicitly by programmers and it won’t be deallocated until it is explicitly freed (Chen and Guo 2022).\n\nTo store an object in the heap, you, the programmer, needs to explicitly tells Zig to do so, by using an allocator to allocate some space in the heap. In Section 3.3, I will present how you can use allocators to allocate memory in Zig.\n\n\n\n\n\n\nImportant\n\n\n\nEvery memory you allocate in the heap needs to be explicitly freed by you, the programmer.\n\n\nThe majority of allocators in Zig do allocate memory on the heap. But some exceptions to this rule are ArenaAllocator() and FixedBufferAllocator(). The ArenaAllocator() is a special type of allocator that works in conjunction with a second type of allocator. On the other side, the FixedBufferAllocator() is an allocator that works based on buffer objects created on the stack. This means that the FixedBufferAllocator() makes allocations only on the stack.\n\n\n3.1.6 Summary\nAfter discussing all of these boring details, we can quickly recap what we learned. In summary, the Zig compiler will use the following rules to decide where each object you declare is stored:\n\nevery literal value (such as \"this is string\", 10, or true) is stored in the global data section.\nevery constant object (const) whose value is known at compile-time is also stored in the global data section.\nevery object (constant or not) whose length/size is known at compile time is stored in the stack space for the current scope.\nif an object is created with the method alloc() or create() of an allocator object, this object is stored in the memory space used by this particular allocator object. Most of allocators available in Zig use the heap memory, so, this object is likely stored in the heap (FixedBufferAllocator() is an exception to that).\nthe heap can only be accessed through allocators. If your object was not created through the alloc() or create() methods of an allocator object, then, it is most certainly not an object stored in the heap.",
     "crumbs": [
       "<span class='chapter-number'>3</span>  <span class='chapter-title'>Memory and Allocators</span>"
     ]
@@ -324,7 +324,7 @@
     "href": "Chapters/01-memory.html#sec-stack-overflow",
     "title": "3  Memory and Allocators",
     "section": "3.2 Stack overflows",
-    "text": "3.2 Stack overflows\nAllocating memory on the stack is generally faster than allocating it on the heap. But this better performance comes with many restrictions. We have already discussed many of these restrictions of the stack at Section 3.1.4. But there is one more important limitation that I want to talk about, which is the size of the stack itself.\nThe stack is limited in size. This size varies from computer to computer, and it depends on a lot of things (the computer architecture, the operating system, etc.). Nevertheless, this size is usually not that big. This is why we normally use the stack to store only temporary and small objects in memory.\nIn essence, if you try to make an allocation on the stack, that is so big that exceeds the stack size limit, a stack overflow happens, and your program just crashes as a result of that. In other words, a stack overflow happens when you attempt to use more space than is available on the stack.\nThis type of problem is very similar to a buffer overflow, i.e. you are trying to use more space than is available in the “buffer object”. However, a stack overflow always causes your program to crash, while a buffer overflow does not always cause your program to crash (although it often does).\nYou can see an example of a stack overflow in the example below. We are trying to allocate a very big array of u64 values on the stack. You can see below that this program does not run successfully, because it crashed with a “segmentation fault” error message.\n\nvar very_big_alloc: [1000 * 1000 * 24]u64 = undefined;\n@memset(very_big_alloc[0..], 0);\n\nSegmentation fault (core dumped)\nThis segmentation fault error is a result of the stack overflow that was caused by the big memory allocation made on the stack, to store the very_big_alloc object. This is why very big objects are usually stored on the heap, instead of the stack.",
+    "text": "3.2 Stack overflows\nAllocating memory on the stack is generally faster than allocating it on the heap. But this better performance comes with many restrictions. We have already discussed many of these restrictions of the stack in Section 3.1.4. But there is one more important limitation that I want to talk about, which is the size of the stack itself.\nThe stack is limited in size. This size varies from computer to computer, and it depends on a lot of things (the computer architecture, the operating system, etc.). Nevertheless, this size is usually not that big. This is why we normally use the stack to store only temporary and small objects in memory.\nIn essence, if you try to make an allocation on the stack, that is so big that exceeds the stack size limit, a stack overflow happens, and your program just crashes as a result of that. In other words, a stack overflow happens when you attempt to use more space than is available on the stack.\nThis type of problem is very similar to a buffer overflow, i.e., you are trying to use more space than is available in the “buffer object”. However, a stack overflow always causes your program to crash, while a buffer overflow does not always cause your program to crash (although it often does).\nYou can see an example of a stack overflow in the example below. We are trying to allocate a very big array of u64 values on the stack. You can see below that this program does not run successfully, because it crashed with a “segmentation fault” error message.\n\nvar very_big_alloc: [1000 * 1000 * 24]u64 = undefined;\n@memset(very_big_alloc[0..], 0);\n\nSegmentation fault (core dumped)\nThis segmentation fault error is a result of the stack overflow that was caused by the big memory allocation made on the stack, to store the very_big_alloc object. This is why very big objects are usually stored on the heap, instead of the stack.",
     "crumbs": [
       "<span class='chapter-number'>3</span>  <span class='chapter-title'>Memory and Allocators</span>"
     ]
@@ -334,7 +334,7 @@
     "href": "Chapters/01-memory.html#sec-allocators",
     "title": "3  Memory and Allocators",
     "section": "3.3 Allocators",
-    "text": "3.3 Allocators\nOne key aspect about Zig, is that there are “no hidden-memory allocations” in Zig. What that really means, is that “no allocations happen behind your back in the standard library” (Sobeston 2024).\nThis is a known problem, especially in C++. Because in C++, there are some operators that do allocate memory behind the scene, and there is no way for you to know that, until you actually read the source code of these operators, and find the memory allocation calls. Many programmers find this behaviour annoying and hard to keep track of.\nBut, in Zig, if a function, an operator, or anything from the standard library needs to allocate some memory during its execution, then, this function/operator needs to receive (as input) an allocator provided by the user, to actually be able to allocate the memory it needs.\nThis creates a clear distinction between functions that “do not” from those that “actually do” allocate memory. Just look at the arguments of this function. If a function, or operator, has an allocator object as one of its inputs/arguments, then, you know for sure that this function/operator will allocate some memory during its execution.\nAn example is the allocPrint() function from the Zig Standard Library. With this function, you can write a new string using format specifiers. So, this function is, for example, very similar to the function sprintf() in C. In order to write such a new string, the allocPrint() function needs to allocate some memory to store the output string.\nThat is why, the first argument of this function is an allocator object that you, the user/programmer, gives as input to the function. In the example below, I am using the GeneralPurposeAllocator() as my allocator object. But I could easily use any other type of allocator object from the Zig Standard Library.\n\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst name = \"Pedro\";\nconst output = try std.fmt.allocPrint(\n    allocator,\n    \"Hello {s}!!!\",\n    .{name}\n);\ntry stdout.print(\"{s}\\n\", .{output});\n\nHello Pedro!!!\n\n\nYou get a lot of control over where and how much memory this function can allocate. Because it is you, the user/programmer, that provides the allocator for the function to use. This makes “total control” over memory management easier to achieve in Zig.\n\n3.3.1 What are allocators?\nAllocators in Zig are objects that you can use to allocate memory for your program. They are similar to the memory allocating functions in C, like malloc() and calloc(). So, if you need to use more memory than you initially have, during the execution of your program, you can simply ask for more memory by using an allocator object.\nZig offers different types of allocators, and they are usually available through the std.heap module of the standard library. Thus, just import the Zig Standard Library into your Zig module (with @import(\"std\")), and you can start using these allocators in your code.\nFurthermore, every allocator object is built on top of the Allocator interface in Zig. This means that, every allocator object you find in Zig must have the methods alloc(), create(), free() and destroy(). So, you can change the type of allocator you are using, but you don’t need to change the function calls to the methods that do the memory allocation (and the free memory operations) for your program.\n\n\n3.3.2 Why you need an allocator?\nAs we described at Section 3.1.4, everytime you make a function call in Zig, a space in the stack is reserved for this function call. But the stack has a key limitation which is: every object stored in the stack has a known fixed length.\nBut in reality, there are two very common instances where this “fixed length limitation” of the stack is a deal braker:\n\nthe objects that you create inside your function might grow in size during the execution of the function.\nsometimes, it is impossible to know upfront how many inputs you will receive, or how big this input will be.\n\nAlso, there is another instance where you might want to use an allocator, which is when you want to write a function that returns a pointer to a local object. As I described at Section 3.1.4, you cannot do that if this local object is stored in the stack. However, if this object is stored in the heap, then, you can return a pointer to this object at the end of the function. Because you (the programmer) control the lifetime of any heap memory that you allocate. You decide when this memory gets destroyed/freed.\nThese are common situations for which the stack is not good. That is why you need a different memory management strategy to store these objects inside your function. You need to use a memory type that can grow together with your objects, or that you can control the lifetime of this memory. The heap fits this description.\nAllocating memory on the heap is commonly known as dynamic memory management. As the objects you create grow in size during the execution of your program, you grow the amount of memory you have by allocating more memory in the heap to store these objects. And you do that in Zig, by using an allocator object.\n\n\n3.3.3 The different types of allocators\nAt the moment of the writing of this book, in Zig, we have 6 different allocators available in the standard library:\n\nGeneralPurposeAllocator().\npage_allocator().\nFixedBufferAllocator() and ThreadSafeFixedBufferAllocator().\nArenaAllocator().\nc_allocator() (requires you to link to libc).\n\nEach allocator has its own perks and limitations. All allocators, except FixedBufferAllocator() and ArenaAllocator(), are allocators that use the heap memory. So any memory that you allocate with these allocators, will be placed in the heap.\n\n\n3.3.4 General-purpose allocators\nThe GeneralPurposeAllocator(), as the name suggests, is a “general purpose” allocator. You can use it for every type of task. In the example below, I’m allocating enough space to store a single integer in the object some_number.\n\nconst std = @import(\"std\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const some_number = try allocator.create(u32);\n    defer allocator.destroy(some_number);\n\n    some_number.* = @as(u32, 45);\n}\n\nWhile useful, you might want to use the c_allocator(), which is a alias to the C standard allocator malloc(). So, yes, you can use malloc() in Zig if you want to. Just use the c_allocator() from the Zig standard library. However, if you do use c_allocator(), you must link to Libc when compiling your source code with the zig compiler, by including the flag -lc in your compilation process. If you do not link your source code to Libc, Zig will not be able to find the malloc() implementation in your system.\n\n\n3.3.5 Page allocator\nThe page_allocator() is an allocator that allocates full pages of memory in the heap. In other words, every time you allocate memory with page_allocator(), a full page of memory in the heap is allocated, instead of just a small piece of it.\nThe size of this page depends on the system you are using. Most systems use a page size of 4KB in the heap, so, that is the amount of memory that is normally allocated in each call by page_allocator(). That is why, page_allocator() is considered a fast, but also “wasteful” allocator in Zig. Because it allocates a big amount of memory in each call, and you most likely will not need that much memory in your program.\n\n\n3.3.6 Buffer allocators\nThe FixedBufferAllocator() and ThreadSafeFixedBufferAllocator() are allocator objects that work with a fixed sized buffer object at the back. In other words, they use a fixed sized buffer object as the basis for the memory. When you ask these allocator objects to allocate some memory for you, they are essentially reserving some amount of space inside this fixed sized buffer object for you to use.\nThis means that, in order to use these allocators, you must first create a buffer object in your code, and then, give this buffer object as an input to these allocators.\nThis also means that, these allocator objects can allocate memory both in the stack or in the heap. Everything depends on where the buffer object that you provide lives. If this buffer object lives in the stack, then, the memory allocated is “stack-based”. But if it lives on the heap, then, the memory allocated is “heap-based”.\nIn the example below, I’m creating a buffer object on the stack that is 10 elements long. Notice that I give this buffer object to the FixedBufferAllocator() constructor. Now, because this buffer object is 10 elements long, this means that I am limited to this space. I cannot allocate more than 10 elements with this allocator object. If I try to allocate more than that, the alloc() method will return an OutOfMemory error value.\n\nvar buffer: [10]u8 = undefined;\nfor (0..buffer.len) |i| {\n    buffer[i] = 0; // Initialize to zero\n}\n\nvar fba = std.heap.FixedBufferAllocator.init(&buffer);\nconst allocator = fba.allocator();\nconst input = try allocator.alloc(u8, 5);\ndefer allocator.free(input);\n\nRemember, the memory allocated by these allocator objects can be either from the stack, or, from the heap. It all depends on where the buffer object that you provide lives. In the above example, the buffer object lives in the stack, and, therefore, the memory allocated is based in the stack. But what if it was based on the heap?\nAs we described at Section 3.2, one of the main reasons why you would use the heap, instead of the stack, is to allocate huge amounts of space to store very big objects. Thus, let’s suppose you wanted to use a very big buffer object as the basis for your allocator objects. You would have to allocate this very big buffer object on the heap. The example below demonstrates this case.\n\nconst heap = std.heap.page_allocator;\nconst memory_buffer = try heap.alloc(\n    u8, 100 * 1024 * 1024 // 100 MB memory\n);\ndefer heap.free(memory_buffer);\nvar fba = std.heap.FixedBufferAllocator.init(\n    memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst input = try allocator.alloc(u8, 1000);\ndefer allocator.free(input);\n\n\n\n3.3.7 Arena allocator\nThe ArenaAllocator() is an allocator object that takes a child allocator as input. The idea behind the ArenaAllocator() in Zig is similar to the concept of “arenas” in the programming language Go5. It is an allocator object that allows you to allocate memory as many times you want, but free all memory only once. In other words, if you have, for example, called 5 times the method alloc() of an ArenaAllocator() object, you can free all the memory you allocated over these 5 calls at once, by simply calling the deinit() method of the same ArenaAllocator() object.\nIf you give, for example, a GeneralPurposeAllocator() object as input to the ArenaAllocator() constructor, like in the example below, then, the allocations you perform with alloc() will actually be made with the underlying object GeneralPurposeAllocator() that was passed. So, with an arena allocator, any new memory you ask for is allocated by the child allocator. The only thing that an arena allocator really does is help you to free all the memory you allocated multiple times with just a single command. In the example below, I called alloc() 3 times. So, if I did not use an arena allocator, then, I would need to call free() 3 times to free all the allocated memory.\n\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nvar aa = std.heap.ArenaAllocator.init(gpa.allocator());\ndefer aa.deinit();\nconst allocator = aa.allocator();\n\nconst in1 = try allocator.alloc(u8, 5);\nconst in2 = try allocator.alloc(u8, 10);\nconst in3 = try allocator.alloc(u8, 15);\n_ = in1; _ = in2; _ = in3;\n\n\n\n3.3.8 The alloc() and free() methods\nIn the code example below, we are accessing the stdin, which is the standard input channel, to receive an input from the user. We read the input given by the user with the readUntilDelimiterOrEof() method.\nNow, after reading the input of the user, we need to store this input somewhere in our program. That is why I use an allocator in this example. I use it to allocate some amount of memory to store this input given by the user. More specifically, the method alloc() of the allocator object is used to allocate an array capable of storing 50 u8 values.\nNotice that this alloc() method receives two inputs. The first one, is a type. This defines what type of values the allocated array will store. In the example below, we are allocating an array of unsigned 8-bit integers (u8). But you can create an array to store any type of value you want. Next, on the second argument, we define the size of the allocated array, by specifying how many elements this array will contain. In the case below, we are allocating an array of 50 elements.\nAt Section 1.8 we described that strings in Zig are simply arrays of characters. Each character is represented by a u8 value. So, this means that the array that was allocated in the object input is capable of storing a string that is 50-characters long.\nSo, in essence, the expression var input: [50]u8 = undefined would create an array for 50 u8 values in the stack of the current scope. But, you can allocate the same array in the heap by using the expression var input = try allocator.alloc(u8, 50).\n\nconst std = @import(\"std\");\nconst stdin = std.io.getStdIn();\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var input = try allocator.alloc(u8, 50);\n    defer allocator.free(input);\n    for (0..input.len) |i| {\n        input[i] = 0; // initialize all fields to zero.\n    }\n    // read user input\n    const input_reader = stdin.reader();\n    _ = try input_reader.readUntilDelimiterOrEof(\n        input,\n        '\\n'\n    );\n    std.debug.print(\"{s}\\n\", .{input});\n}\n\nAlso, notice that in this example, we use the defer keyword (which I described at Section 2.1.3) to run a small piece of code at the end of the current scope, which is the expression allocator.free(input). When you execute this expression, the allocator will free the memory that it allocated for the input object.\nWe have talked about this at Section 3.1.5. You should always explicitly free any memory that you allocate using an allocator! You do that by using the free() method of the same allocator object you used to allocate this memory. The defer keyword is used in this example only to help us execute this free operation at the end of the current scope.\n\n\n3.3.9 The create() and destroy() methods\nWith the alloc() and free() methods, you can allocate memory to store multiple elements at once. In other words, with these methods, we always allocate an array to store multiple elements at once. But what if you need enough space to store just a single item? Should you allocate an array of a single element through alloc()?\nThe answer is no! In this case, you should use the create() method of the allocator object. Every allocator object offers the create() and destroy() methods, which are used to allocate and free memory for a single item, respectively.\nSo, in essence, if you want to allocate memory to store an array of elements, you should use alloc() and free(). But if you need to store just a single item, then, the create() and destroy() methods are ideal for you.\nIn the example below, I’m defining a struct to represent an user of some sort. It could be a user for a game, or software to manage resources, it doesn’t mater. Notice that I use the create() method this time, to store a single User object in the program. Also notice that I use the destroy() method to free the memory used by this object at the end of the scope.\n\nconst std = @import(\"std\");\nconst User = struct {\n    id: usize,\n    name: []const u8,\n\n    pub fn init(id: usize, name: []const u8) User {\n        return .{ .id = id, .name = name };\n    }\n};\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const user = try allocator.create(User);\n    defer allocator.destroy(user);\n\n    user.* = User.init(0, \"Pedro\");\n}\n\n\n\n\n\nChen, Jenny, and Ruohao Guo. 2022. “Stack and Heap Memory.” Introduction to Data Structures and Algorithms with C++. https://courses.engr.illinois.edu/cs225/fa2022/resources/stack-heap/.\n\n\nSobeston. 2024. “Zig Guide.” https://zig.guide/.\n\n\nZig Software Foundation. 2024. “Language Reference.” Zig Software Foundation. https://ziglang.org/documentation/master/.",
+    "text": "3.3 Allocators\nOne key aspect about Zig, is that there are “no hidden-memory allocations” in Zig. What that really means, is that “no allocations happen behind your back in the standard library” (Sobeston 2024).\nThis is a known problem, especially in C++. Because in C++, there are some operators that do allocate memory behind the scene, and there is no way for you to know that, until you actually read the source code of these operators, and find the memory allocation calls. Many programmers find this behaviour annoying and hard to keep track of.\nBut, in Zig, if a function, an operator, or anything from the standard library needs to allocate some memory during its execution, then, this function/operator needs to receive (as input) an allocator provided by the user, to actually be able to allocate the memory it needs.\nThis creates a clear distinction between functions that “do not” from those that “actually do” allocate memory. Just look at the arguments of this function. If a function, or operator, has an allocator object as one of its inputs/arguments, then, you know for sure that this function/operator will allocate some memory during its execution.\nAn example is the allocPrint() function from the Zig Standard Library. With this function, you can write a new string using format specifiers. So, this function is, for example, very similar to the function sprintf() in C. In order to write such a new string, the allocPrint() function needs to allocate some memory to store the output string.\nThat is why, the first argument of this function is an allocator object that you, the user/programmer, gives as input to the function. In the example below, I am using the GeneralPurposeAllocator() as my allocator object. But I could easily use any other type of allocator object from the Zig Standard Library.\n\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst name = \"Pedro\";\nconst output = try std.fmt.allocPrint(\n    allocator,\n    \"Hello {s}!!!\",\n    .{name}\n);\ntry stdout.print(\"{s}\\n\", .{output});\n\nHello Pedro!!!\n\n\nYou get a lot of control over where and how much memory this function can allocate. Because it is you, the user/programmer, that provides the allocator for the function to use. This makes “total control” over memory management easier to achieve in Zig.\n\n3.3.1 What are allocators?\nAllocators in Zig are objects that you can use to allocate memory for your program. They are similar to the memory allocating functions in C, like malloc() and calloc(). So, if you need to use more memory than you initially have, during the execution of your program, you can simply ask for more memory by using an allocator object.\nZig offers different types of allocators, and they are usually available through the std.heap module of the standard library. Thus, just import the Zig Standard Library into your Zig module (with @import(\"std\")), and you can start using these allocators in your code.\nFurthermore, every allocator object is built on top of the Allocator interface in Zig. This means that, every allocator object you find in Zig must have the methods alloc(), create(), free() and destroy(). So, you can change the type of allocator you are using, but you don’t need to change the function calls to the methods that do the memory allocation (and the free memory operations) for your program.\n\n\n3.3.2 Why you need an allocator?\nAs we described in Section 3.1.4, everytime you make a function call in Zig, a space in the stack is reserved for this function call. But the stack has a key limitation which is: every object stored in the stack has a known fixed length.\nBut in reality, there are two very common instances where this “fixed length limitation” of the stack is a deal braker:\n\nthe objects that you create inside your function might grow in size during the execution of the function.\nsometimes, it’s impossible to know upfront how many inputs you will receive, or how big this input will be.\n\nAlso, there is another instance where you might want to use an allocator, which is when you want to write a function that returns a pointer to a local object. As I described in Section 3.1.4, you cannot do that if this local object is stored in the stack. However, if this object is stored in the heap, then, you can return a pointer to this object at the end of the function. Because you (the programmer) control the lifetime of any heap memory that you allocate. You decide when this memory gets destroyed/freed.\nThese are common situations for which the stack is not good. That is why you need a different memory management strategy to store these objects inside your function. You need to use a memory type that can grow together with your objects, or that you can control the lifetime of this memory. The heap fits this description.\nAllocating memory on the heap is commonly known as dynamic memory management. As the objects you create grow in size during the execution of your program, you grow the amount of memory you have by allocating more memory in the heap to store these objects. And you do that in Zig, by using an allocator object.\n\n\n3.3.3 The different types of allocators\nAt the moment of the writing of this book, in Zig, we have 6 different allocators available in the standard library:\n\nGeneralPurposeAllocator().\npage_allocator().\nFixedBufferAllocator() and ThreadSafeFixedBufferAllocator().\nArenaAllocator().\nc_allocator() (requires you to link to libc).\n\nEach allocator has its own perks and limitations. All allocators, except FixedBufferAllocator() and ArenaAllocator(), are allocators that use the heap memory. So any memory that you allocate with these allocators, will be placed in the heap.\n\n\n3.3.4 General-purpose allocators\nThe GeneralPurposeAllocator(), as the name suggests, is a “general purpose” allocator. You can use it for every type of task. In the example below, I’m allocating enough space to store a single integer in the object some_number.\n\nconst std = @import(\"std\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const some_number = try allocator.create(u32);\n    defer allocator.destroy(some_number);\n\n    some_number.* = @as(u32, 45);\n}\n\nWhile useful, you might want to use the c_allocator(), which is a alias to the C standard allocator malloc(). So, yes, you can use malloc() in Zig if you want to. Just use the c_allocator() from the Zig standard library. However, if you do use c_allocator(), you must link to Libc when compiling your source code with the zig compiler, by including the flag -lc in your compilation process. If you do not link your source code to Libc, Zig will not be able to find the malloc() implementation in your system.\n\n\n3.3.5 Page allocator\nThe page_allocator() is an allocator that allocates full pages of memory in the heap. In other words, every time you allocate memory with page_allocator(), a full page of memory in the heap is allocated, instead of just a small piece of it.\nThe size of this page depends on the system you are using. Most systems use a page size of 4KB in the heap, so, that is the amount of memory that is normally allocated in each call by page_allocator(). That is why, page_allocator() is considered a fast, but also “wasteful” allocator in Zig. Because it allocates a big amount of memory in each call, and you most likely will not need that much memory in your program.\n\n\n3.3.6 Buffer allocators\nThe FixedBufferAllocator() and ThreadSafeFixedBufferAllocator() are allocator objects that work with a fixed sized buffer object at the back. In other words, they use a fixed sized buffer object as the basis for the memory. When you ask these allocator objects to allocate some memory for you, they are essentially reserving some amount of space inside this fixed sized buffer object for you to use.\nThis means that, in order to use these allocators, you must first create a buffer object in your code, and then, give this buffer object as an input to these allocators.\nThis also means that, these allocator objects can allocate memory both in the stack or in the heap. Everything depends on where the buffer object that you provide lives. If this buffer object lives in the stack, then, the memory allocated is “stack-based”. But if it lives on the heap, then, the memory allocated is “heap-based”.\nIn the example below, I’m creating a buffer object on the stack that is 10 elements long. Notice that I give this buffer object to the FixedBufferAllocator() constructor. Now, because this buffer object is 10 elements long, this means that I am limited to this space. I cannot allocate more than 10 elements with this allocator object. If I try to allocate more than that, the alloc() method will return an OutOfMemory error value.\n\nvar buffer: [10]u8 = undefined;\nfor (0..buffer.len) |i| {\n    buffer[i] = 0; // Initialize to zero\n}\n\nvar fba = std.heap.FixedBufferAllocator.init(&buffer);\nconst allocator = fba.allocator();\nconst input = try allocator.alloc(u8, 5);\ndefer allocator.free(input);\n\nRemember, the memory allocated by these allocator objects can be either from the stack, or, from the heap. It all depends on where the buffer object that you provide lives. In the above example, the buffer object lives in the stack, and, therefore, the memory allocated is based in the stack. But what if it was based on the heap?\nAs we described in Section 3.2, one of the main reasons why you would use the heap, instead of the stack, is to allocate huge amounts of space to store very big objects. Thus, let’s suppose you wanted to use a very big buffer object as the basis for your allocator objects. You would have to allocate this very big buffer object on the heap. The example below demonstrates this case.\n\nconst heap = std.heap.page_allocator;\nconst memory_buffer = try heap.alloc(\n    u8, 100 * 1024 * 1024 // 100 MB memory\n);\ndefer heap.free(memory_buffer);\nvar fba = std.heap.FixedBufferAllocator.init(\n    memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst input = try allocator.alloc(u8, 1000);\ndefer allocator.free(input);\n\n\n\n3.3.7 Arena allocator\nThe ArenaAllocator() is an allocator object that takes a child allocator as input. The idea behind the ArenaAllocator() in Zig is similar to the concept of “arenas” in the programming language Go5. It’s an allocator object that allows you to allocate memory as many times you want, but free all memory only once. In other words, if you have, for example, called 5 times the method alloc() of an ArenaAllocator() object, you can free all the memory you allocated over these 5 calls at once, by simply calling the deinit() method of the same ArenaAllocator() object.\nIf you give, for example, a GeneralPurposeAllocator() object as input to the ArenaAllocator() constructor, like in the example below, then, the allocations you perform with alloc() will actually be made with the underlying object GeneralPurposeAllocator() that was passed. So, with an arena allocator, any new memory you ask for is allocated by the child allocator. The only thing that an arena allocator really does is help you to free all the memory you allocated multiple times with just a single command. In the example below, I called alloc() 3 times. So, if I did not use an arena allocator, then, I would need to call free() 3 times to free all the allocated memory.\n\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nvar aa = std.heap.ArenaAllocator.init(gpa.allocator());\ndefer aa.deinit();\nconst allocator = aa.allocator();\n\nconst in1 = try allocator.alloc(u8, 5);\nconst in2 = try allocator.alloc(u8, 10);\nconst in3 = try allocator.alloc(u8, 15);\n_ = in1; _ = in2; _ = in3;\n\n\n\n3.3.8 The alloc() and free() methods\nIn the code example below, we are accessing the stdin, which is the standard input channel, to receive an input from the user. We read the input given by the user with the readUntilDelimiterOrEof() method.\nNow, after reading the input of the user, we need to store this input somewhere in our program. That is why I use an allocator in this example. I use it to allocate some amount of memory to store this input given by the user. More specifically, the method alloc() of the allocator object is used to allocate an array capable of storing 50 u8 values.\nNotice that this alloc() method receives two inputs. The first one, is a type. This defines what type of values the allocated array will store. In the example below, we are allocating an array of unsigned 8-bit integers (u8). But you can create an array to store any type of value you want. Next, in the second argument, we define the size of the allocated array, by specifying how many elements this array will contain. In the case below, we are allocating an array of 50 elements.\nIn Section 1.8 we described that strings in Zig are simply arrays of characters. Each character is represented by a u8 value. So, this means that the array that was allocated in the object input is capable of storing a string that is 50-characters long.\nSo, in essence, the expression var input: [50]u8 = undefined would create an array for 50 u8 values in the stack of the current scope. But, you can allocate the same array in the heap by using the expression var input = try allocator.alloc(u8, 50).\n\nconst std = @import(\"std\");\nconst stdin = std.io.getStdIn();\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var input = try allocator.alloc(u8, 50);\n    defer allocator.free(input);\n    for (0..input.len) |i| {\n        input[i] = 0; // initialize all fields to zero.\n    }\n    // read user input\n    const input_reader = stdin.reader();\n    _ = try input_reader.readUntilDelimiterOrEof(\n        input,\n        '\\n'\n    );\n    std.debug.print(\"{s}\\n\", .{input});\n}\n\nAlso, notice that in this example, we use the defer keyword (which I described in Section 2.1.3) to run a small piece of code at the end of the current scope, which is the expression allocator.free(input). When you execute this expression, the allocator will free the memory that it allocated for the input object.\nWe have talked about this in Section 3.1.5. You should always explicitly free any memory that you allocate using an allocator! You do that by using the free() method of the same allocator object you used to allocate this memory. The defer keyword is used in this example only to help us execute this free operation at the end of the current scope.\n\n\n3.3.9 The create() and destroy() methods\nWith the alloc() and free() methods, you can allocate memory to store multiple elements at once. In other words, with these methods, we always allocate an array to store multiple elements at once. But what if you need enough space to store just a single item? Should you allocate an array of a single element through alloc()?\nThe answer is no! In this case, you should use the create() method of the allocator object. Every allocator object offers the create() and destroy() methods, which are used to allocate and free memory for a single item, respectively.\nSo, in essence, if you want to allocate memory to store an array of elements, you should use alloc() and free(). But if you need to store just a single item, then, the create() and destroy() methods are ideal for you.\nIn the example below, I’m defining a struct to represent an user of some sort. It could be a user for a game, or software to manage resources, it doesn’t mater. Notice that I use the create() method this time, to store a single User object in the program. Also notice that I use the destroy() method to free the memory used by this object at the end of the scope.\n\nconst std = @import(\"std\");\nconst User = struct {\n    id: usize,\n    name: []const u8,\n\n    pub fn init(id: usize, name: []const u8) User {\n        return .{ .id = id, .name = name };\n    }\n};\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const user = try allocator.create(User);\n    defer allocator.destroy(user);\n\n    user.* = User.init(0, \"Pedro\");\n}\n\n\n\n\n\nChen, Jenny, and Ruohao Guo. 2022. “Stack and Heap Memory.” Introduction to Data Structures and Algorithms with C++. https://courses.engr.illinois.edu/cs225/fa2022/resources/stack-heap/.\n\n\nSobeston. 2024. “Zig Guide.” https://zig.guide/.\n\n\nZig Software Foundation. 2024. “Language Reference.” Zig Software Foundation. https://ziglang.org/documentation/master/.",
     "crumbs": [
       "<span class='chapter-number'>3</span>  <span class='chapter-title'>Memory and Allocators</span>"
     ]
@@ -364,7 +364,7 @@
     "href": "Chapters/01-base64.html#how-the-base64-algorithm-work",
     "title": "4  Project 1 - Building a base64 encoder/decoder",
     "section": "",
-    "text": "4.1.1 The base64 scale\nThe base64 encoding system is based on a scale that goes from 0 to 63 (hence the name). Each index in this scale is represented by a character (it is a scale of 64 characters). So, in order to convert some binary data, to the base64 encoding, we need to convert each binary number to the corresponding character in this “scale of 64 characters”.\nThe base64 scale starts with all ASCII uppercase letters (A to Z) which represents the first 25 indexes in this scale (0 to 25). After that, we have all ASCII lowercase letters (a to z), which represents the range 26 to 51 in the scale. After that, we have the one digit numbers (0 to 9), which represents the indexes from 52 to 61 in the scale. Finally, the last two indexes in the scale (62 and 63) are represented by the characters + and /, respectively.\nThese are the 64 characters that compose the base64 scale. The equal sign character (=) is not part of the scale itself, but it is a special character in the base64 encoding system. This character is used solely as a suffix, to mark the end of the character sequence, or, to mark the end of meaningful characters in the sequence.\nThe bullet points below summarises the base64 scale:\n\nrange 0 to 25 is represented by: ASCII uppercase letters -&gt; [A-Z];\nrange 26 to 51 is represented by: ASCII lowercase letters -&gt; [a-z];\nrange 52 to 61 is represented by: one digit numbers -&gt; [0-9];\nindex 62 and 63 are represented by the characters + and /, respectively;\nthe character = represents the end of meaningful characters in the sequence;\n\n\n\n4.1.2 Creating the scale as a lookup table\nThe best way to represent this scale in code, is to represent it as a lookup table. Lookup tables are a classic strategy in computer science to speed up calculations. The basic idea is to replace a runtime calculation (which can take a long time to be done) with a basic array indexing operation.\nInstead of calculating the results everytime you need them, you calculate all possible results at once, and then, you store them in an array (which behaves lake a “table”). Then, every time you need to use one of the characters in the base64 scale, instead of using many resources to calculate the exact character to be used, you simply retrieve this character from the array where you stored all the possible characters in the base64 scale. We retrieve the character that we need directly from memory.\nWe can start building a Zig struct to store our base64 decoder/encoder logic. We start with the Base64 struct below. For now, we only have one single data member in this struct, i.e. the member _table, which represents our lookup table. We also have an init() method, to create a new instance of a Base64 object, and, a _char_at() method, which is a “get character at index \\(x\\)” type of function.\n\nconst Base64 = struct {\n    _table: *const [64]u8,\n\n    pub fn init() Base64 {\n        const upper = \"ABCDEFGHIJKLMNOPQRSTUVWXYZ\";\n        const lower = \"abcdefghijklmnopqrstuvwxyz\";\n        const numbers_symb = \"0123456789+/\";\n        return Base64{\n            ._table = upper ++ lower ++ numbers_symb,\n        };\n    }\n\n    pub fn _char_at(self: Base64, index: usize) u8 {\n        return self._table[index];\n    }\n};\n\nIn other words, the _char_at() method is responsible for getting the character in the lookup table (i.e. the _table struct data member) that corresponds to a particular index in the “base64 scale”. So, in the example below, we know that the character that corresponds to the index 28 in the “base64 scale” is the character “c”.\n\nconst base64 = Base64.init();\ntry stdout.print(\n    \"Character at index 28: {c}\\n\",\n    .{base64._char_at(28)}\n);\n\nCharacter at index 28: c\n\n\n4.1.3 A base64 encoder\nThe algorithm behind a base64 encoder usually works on a window of 3 bytes. Because each byte has 8 bits, so, 3 bytes forms a set of \\(8 \\times 3 = 24\\) bits. This is desirable for the base64 algorithm, because 24 bits is divisible by 6, which forms \\(24 / 6 = 4\\) groups of 6 bits each.\nTherefore, the base64 algorithm works by converting 3 bytes at a time into 4 characters from the base64 scale. It keeps iterating through the input string, 3 bytes at a time, and converting them into the base64 scale, producing 4 characters per iteration. It keeps iterating, and producing these “new characters” until it hits the end of the input string.\nNow, you may think, what if you have a particular string that have a number of bytes that is not divisible by 3? What happens? For example, if you have a string that contains only two characters/bytes, such as “Hi”. How the algorithm would behave in such situation? You find the answer at Figure 4.1. You can see at Figure 4.1 that the string “Hi”, when converted to base64, becomes the string “SGk=”:\n\n\n\n\n\n\nFigure 4.1: The logic behind a base64 encoder\n\n\n\nTaking the string “Hi” as an example, we have 2 bytes, or, 16 bits in total. So, we lack a full byte (8 bits) to complete the window of 24 bits that the base64 algorithm likes to work on. The first thing that the algorithm does, is to check how to divide the input bytes into groups of 6 bits.\nIf the algorithm notices that there is a group of 6 bits that, have some bits in it, but, at the same time, it is not full (in other words, \\(0 &lt; nbits &lt; 6\\), being \\(nbits\\) the number of bits), meaning that, it lacks some bits to fill the 6-bits requirement, the algorithm simply add extra zeros in this group to fill the space that it needs. That is why at Figure 4.1, on the third group after the 6-bit transformation, 2 extra zeros were added to fill the gap in this group.\nWhen we have a 6-bit group that is not completely full, like the third group, extra zeros are added to fill the gap. But what about when an entire 6-bit group is empty, or, it simply doesn’t exist? This is the case of the fourth 6-bit group exposed at Figure 4.1.\nThis fourth group is necessary, because the algorithm works on 4 groups of 6 bits. But the input string does not have enough bytes to create a fourth 6-bit group. Every time this happens, where an entire group of 6 bits is empty, this group becomes a “padding group”. Every “padding group” is mapped to the character = (equal sign), which represents “null”, or, the end of meaningful characters in the sequence. Hence, everytime that the algorithm produces a “padding group”, this group is automatically mapped to =.\nAs another example, if you give the string “0” as input to a base64 encoder, this string is translated into the base64 sequence “MA==”. The character “0” is, in binary, the sequence 001100001. So, with the 6-bit transformation exposed at Figure 4.1, this single character would produce these two 6-bit groups: 001100, 000000. The remaining two 6-bit groups become “padding groups”. That is why the last two characters in the output sequence (MA==) are ==.\n\n\n4.1.4 A base64 decoder\nThe algorithm behind a base64 decoder is essentially the inverse process of a base64 encoder. A base64 decoder needs to translate base64 messages back into their original meaning, i.e. into the original sequence of binary data.\nA base64 decoder usually works on a window of 4 bytes. Because it wants to convert these 4 bytes back into the original sequence of 3 bytes, that was converted into 4 groups of 6 bits by the base64 encoder. Remember, in a base64 decoder we are essentially reverting the process made by the base64 encoder.\nEach byte in the input string (the base64 encoded string) normally contributes to re-create two different bytes in the output (the original binary data). In other words, each byte that comes out of a base64 decoder is created by transforming merging two different bytes in the input together. You can visualize this relationship at Figure 4.2:\n\n\n\n\n\n\nFigure 4.2: The logic behind a base64 decoder\n\n\n\nThe exact transformations, or, the exact steps applied to each byte from the input to transform them into the bytes of the output, are a bit tricky to visualize in a figure like this. Because of that, I have summarized these transformations as “Some bit shifting and additions …” in the figure. These transformations will be described in depth later.\nBesides that, if you look again at Figure 4.2, you will notice that the character = was completely ignored by the algorithm. Remember, this is just a special character that marks the end of meaningful characters in the base64 sequence. So, every = character in a base64 encoded sequence should be ignored by a base64 decoder.",
+    "text": "4.1.1 The base64 scale\nThe base64 encoding system is based on a scale that goes from 0 to 63 (hence the name). Each index in this scale is represented by a character (it’s a scale of 64 characters). So, in order to convert some binary data, to the base64 encoding, we need to convert each binary number to the corresponding character in this “scale of 64 characters”.\nThe base64 scale starts with all ASCII uppercase letters (A to Z) which represents the first 25 indexes in this scale (0 to 25). After that, we have all ASCII lowercase letters (a to z), which represents the range 26 to 51 in the scale. After that, we have the one digit numbers (0 to 9), which represents the indexes from 52 to 61 in the scale. Finally, the last two indexes in the scale (62 and 63) are represented by the characters + and /, respectively.\nThese are the 64 characters that compose the base64 scale. The equal sign character (=) is not part of the scale itself, but it is a special character in the base64 encoding system. This character is used solely as a suffix, to mark the end of the character sequence, or, to mark the end of meaningful characters in the sequence.\nThe bullet points below summarises the base64 scale:\n\nrange 0 to 25 is represented by: ASCII uppercase letters -&gt; [A-Z];\nrange 26 to 51 is represented by: ASCII lowercase letters -&gt; [a-z];\nrange 52 to 61 is represented by: one digit numbers -&gt; [0-9];\nindex 62 and 63 are represented by the characters + and /, respectively;\nthe character = represents the end of meaningful characters in the sequence;\n\n\n\n4.1.2 Creating the scale as a lookup table\nThe best way to represent this scale in code, is to represent it as a lookup table. Lookup tables are a classic strategy in computer science to speed up calculations. The basic idea is to replace a runtime calculation (which can take a long time to be done) with a basic array indexing operation.\nInstead of calculating the results everytime you need them, you calculate all possible results at once, and then, you store them in an array (which behaves lake a “table”). Then, every time you need to use one of the characters in the base64 scale, instead of using many resources to calculate the exact character to be used, you simply retrieve this character from the array where you stored all the possible characters in the base64 scale. We retrieve the character that we need directly from memory.\nWe can start building a Zig struct to store our base64 decoder/encoder logic. We start with the Base64 struct below. For now, we only have one single data member in this struct, i.e., the member _table, which represents our lookup table. We also have an init() method, to create a new instance of a Base64 object, and, a _char_at() method, which is a “get character at index \\(x\\)” type of function.\n\nconst Base64 = struct {\n    _table: *const [64]u8,\n\n    pub fn init() Base64 {\n        const upper = \"ABCDEFGHIJKLMNOPQRSTUVWXYZ\";\n        const lower = \"abcdefghijklmnopqrstuvwxyz\";\n        const numbers_symb = \"0123456789+/\";\n        return Base64{\n            ._table = upper ++ lower ++ numbers_symb,\n        };\n    }\n\n    pub fn _char_at(self: Base64, index: usize) u8 {\n        return self._table[index];\n    }\n};\n\nIn other words, the _char_at() method is responsible for getting the character in the lookup table (i.e., the _table struct data member) that corresponds to a particular index in the “base64 scale”. So, in the example below, we know that the character that corresponds to the index 28 in the “base64 scale” is the character “c”.\n\nconst base64 = Base64.init();\ntry stdout.print(\n    \"Character at index 28: {c}\\n\",\n    .{base64._char_at(28)}\n);\n\nCharacter at index 28: c\n\n\n4.1.3 A base64 encoder\nThe algorithm behind a base64 encoder usually works on a window of 3 bytes. Because each byte has 8 bits, so, 3 bytes forms a set of \\(8 \\times 3 = 24\\) bits. This is desirable for the base64 algorithm, because 24 bits is divisible by 6, which forms \\(24 / 6 = 4\\) groups of 6 bits each.\nTherefore, the base64 algorithm works by converting 3 bytes at a time into 4 characters from the base64 scale. It keeps iterating through the input string, 3 bytes at a time, and converting them into the base64 scale, producing 4 characters per iteration. It keeps iterating, and producing these “new characters” until it hits the end of the input string.\nNow you may think, what if you have a particular string that has a number of bytes that is not divisible by 3 - what happens? For example, if you have a string that contains only two characters/bytes, such as “Hi”. How would the algorithm behave in such situation? You find the answer in Figure 4.1. You can see in Figure 4.1 that the string “Hi”, when converted to base64, becomes the string “SGk=”:\n\n\n\n\n\n\nFigure 4.1: The logic behind a base64 encoder\n\n\n\nTaking the string “Hi” as an example, we have 2 bytes, or, 16 bits in total. So, we lack a full byte (8 bits) to complete the window of 24 bits that the base64 algorithm likes to work on. The first thing that the algorithm does, is to check how to divide the input bytes into groups of 6 bits.\nIf the algorithm notices that there is a group of 6 bits that it’s not complete, meaning that, this group contains \\(nbits\\), where \\(0 &lt; nbits &lt; 6\\),\nthe algorithm simply adds extra zeros in this group to fill the space that it needs. That is why in Figure 4.1, in the third group after the 6-bit transformation, 2 extra zeros were added to fill the gap.\nWhen we have a 6-bit group that is not completely full, like the third group, extra zeros are added to fill the gap. But what about when an entire 6-bit group is empty, or, it simply doesn’t exist? This is the case of the fourth 6-bit group exposed at Figure 4.1.\nThis fourth group is necessary, because the algorithm works on 4 groups of 6 bits. But the input string does not have enough bytes to create a fourth 6-bit group. Every time this happens, where an entire group of 6 bits is empty, this group becomes a “padding group”. Every “padding group” is mapped to the character = (equal sign), which represents “null”, or, the end of meaningful characters in the sequence. Hence, everytime that the algorithm produces a “padding group”, this group is automatically mapped to =.\nAs another example, if you give the string “0” as input to a base64 encoder, this string is translated into the base64 sequence “MA==”. The character “0” is, in binary, the sequence 001100001. So, with the 6-bit transformation exposed in Figure 4.1, this single character would produce these two 6-bit groups: 001100, 000000. The remaining two 6-bit groups become “padding groups”. That is why the last two characters in the output sequence (MA==) are ==.\n\n\n4.1.4 A base64 decoder\nThe algorithm behind a base64 decoder is essentially the inverse process of a base64 encoder. A base64 decoder needs to translate base64 messages back into their original meaning, i.e., into the original sequence of binary data.\nA base64 decoder usually works on a window of 4 bytes. Because it wants to convert these 4 bytes back into the original sequence of 3 bytes, that was converted into 4 groups of 6 bits by the base64 encoder. Remember, in a base64 decoder we are essentially reverting the process made by the base64 encoder.\nEach byte in the input string (the base64 encoded string) normally contributes to re-create two different bytes in the output (the original binary data). In other words, each byte that comes out of a base64 decoder is created by transforming merging two different bytes in the input together. You can visualize this relationship in Figure 4.2:\n\n\n\n\n\n\nFigure 4.2: The logic behind a base64 decoder\n\n\n\nThe exact transformations, or, the exact steps applied to each byte from the input to transform them into the bytes of the output, are a bit tricky to visualize in a figure like this. Because of that, I have summarized these transformations as “Some bit shifting and additions …” in the figure. These transformations will be described in depth later.\nBesides that, if you look again in Figure 4.2, you will notice that the character = was completely ignored by the algorithm. Remember, this is just a special character that marks the end of meaningful characters in the base64 sequence. So, every = character in a base64 encoded sequence should be ignored by a base64 decoder.",
     "crumbs": [
       "<span class='chapter-number'>4</span>  <span class='chapter-title'>Project 1 - Building a base64 encoder/decoder</span>"
     ]
@@ -374,7 +374,7 @@
     "href": "Chapters/01-base64.html#sec-encode-vs-decode",
     "title": "4  Project 1 - Building a base64 encoder/decoder",
     "section": "4.2 Difference between encode and decode",
-    "text": "4.2 Difference between encode and decode\nIf you don’t have any previous experience with base64, you might not understand the differences between “encode” and “decode”. Essentially, the terms “encode” and “decode” here have the exact same meaning as they have in the field of encryption (i.e. they mean the same thing as “encode” and “decode” in hashing algorithms, like the MD5 algorithm).\nThus, “encode” means that we want to encode, or, in other words, we want to translate some message into the base64 encoding system. We want to produce the sequence of base64 characters that represent this original message in the base64 encoding system.\nIn contrast, “decode” represents the inverse process. We want to decode, or, in other words, translate a base64 message back to its original content. So, in this process we get a sequence of base64 characters as input, and produce as output, the binary data that is represented by this sequence of base64 characters.\nAny base64 library is normally composed of these two parts: 1) the encoder, which is a function that encodes (i.e. it converts) any sequence of binary data into a sequence of base64 characters; 2) the decoder, which is a function that converts a sequence of base64 characters back into the original sequence of binary data.",
+    "text": "4.2 Difference between encode and decode\nIf you don’t have any previous experience with base64, you might not understand the differences between “encode” and “decode”. Essentially, the terms “encode” and “decode” here have the exact same meaning as they have in the field of encryption (i.e., they mean the same thing as “encode” and “decode” in hashing algorithms, like the MD5 algorithm).\nThus, “encode” means that we want to encode, or, in other words, we want to translate some message into the base64 encoding system. We want to produce the sequence of base64 characters that represent this original message in the base64 encoding system.\nIn contrast, “decode” represents the inverse process. We want to decode, or, in other words, translate a base64 message back to its original content. So, in this process we get a sequence of base64 characters as input, and produce as output, the binary data that is represented by this sequence of base64 characters.\nAny base64 library is normally composed of these two parts: 1) the encoder, which is a function that encodes (i.e., it converts) any sequence of binary data into a sequence of base64 characters; 2) the decoder, which is a function that converts a sequence of base64 characters back into the original sequence of binary data.",
     "crumbs": [
       "<span class='chapter-number'>4</span>  <span class='chapter-title'>Project 1 - Building a base64 encoder/decoder</span>"
     ]
@@ -384,7 +384,7 @@
     "href": "Chapters/01-base64.html#sec-base64-length-out",
     "title": "4  Project 1 - Building a base64 encoder/decoder",
     "section": "4.3 Calculating the size of the output",
-    "text": "4.3 Calculating the size of the output\nOne task that we need to do is to calculate how much space we need to reserve for the output, both of the encoder and decoder. This is simple math, and can be done easily in Zig because every array has its length (its number of elements) easily accesible by consulting the .len property of the array.\nFor the encoder, the logic is the following: for each 3 bytes that we find in the input, 4 new bytes are created in the output. So, we take the number of bytes in the input, divide it by 3, use a ceiling function, then, we multiply the result by 4. That way, we get the total number of bytes that will be produced by the encoder in its output.\nThe _calc_encode_length() function below encapsulates this logic. Inside this function, we take the length of the input array, we divide it by 3, and apply a ceil operation over the result by using the divCeil() function from the Zig Standard Library. Lastly, we multiply the end result by 4 to get the answer we need.\n\nconst std = @import(\"std\");\nfn _calc_encode_length(input: []const u8) !usize {\n    if (input.len &lt; 3) {\n        const n_output: usize = 4;\n        return n_output;\n    }\n    const n_output: usize = try std.math.divCeil(\n        usize, input.len, 3\n    );\n    return n_output * 4;\n}\n\nAlso, you might have notice that, if the input length is less than 3 bytes, then, the output length of the encoder is always 4 bytes. This is the case for every input with less than 3 bytes, because, as I described at Section 4.1.3, the algorithm always produces enough “padding-groups” in the end result, to complete the 4 bytes window.\nNow, for the decoder, we just need to apply the inverse logic: for each 4 bytes in the input, 3 bytes will be produced in the output of the decoder. I mean, this is roughly true, because we also need to take the = character into account, which is always ignored by the decoder, as we described at Section 4.1.4, and, at Figure 4.2. But we can ignore this fact for now, just to keep things simple.\nThe function _calc_decode_length() exposed below summarizes this logic that we described. It is very similar to the function _calc_encode_length(). Only the division part is twisted, and also, in the special case where we have less than 4 bytes in the input to work on. Also notice that this time, we apply a floor operation over the output of the division, by using the divFloor() function (instead of a ceiling operation with divCeil()).\n\nconst std = @import(\"std\");\nfn _calc_decode_length(input: []const u8) !usize {\n    if (input.len &lt; 4) {\n        const n_output: usize = 3;\n        return n_output;\n    }\n    const n_output: usize = try std.math.divFloor(\n        usize, input.len, 4\n    );\n    return n_output * 3;\n}",
+    "text": "4.3 Calculating the size of the output\nOne task that we need to do is to calculate how much space we need to reserve for the output, both of the encoder and decoder. This is simple math, and can be done easily in Zig because every array has its length (its number of elements) easily accesible by consulting the .len property of the array.\nFor the encoder, the logic is the following: for each 3 bytes that we find in the input, 4 new bytes are created in the output. So, we take the number of bytes in the input, divide it by 3, use a ceiling function, then, we multiply the result by 4. That way, we get the total number of bytes that will be produced by the encoder in its output.\nThe _calc_encode_length() function below encapsulates this logic. Inside this function, we take the length of the input array, we divide it by 3, and apply a ceil operation over the result by using the divCeil() function from the Zig Standard Library. Lastly, we multiply the end result by 4 to get the answer we need.\n\nconst std = @import(\"std\");\nfn _calc_encode_length(input: []const u8) !usize {\n    if (input.len &lt; 3) {\n        const n_output: usize = 4;\n        return n_output;\n    }\n    const n_output: usize = try std.math.divCeil(\n        usize, input.len, 3\n    );\n    return n_output * 4;\n}\n\nAlso, you might have notice that, if the input length is less than 3 bytes, then, the output length of the encoder is always 4 bytes. This is the case for every input with less than 3 bytes, because, as I described in Section 4.1.3, the algorithm always produces enough “padding-groups” in the end result, to complete the 4 bytes window.\nNow, for the decoder, we just need to apply the inverse logic: for each 4 bytes in the input, 3 bytes will be produced in the output of the decoder. I mean, this is roughly true, because we also need to take the = character into account, which is always ignored by the decoder, as we described in Section 4.1.4, and, in Figure 4.2. But we can ignore this fact for now, just to keep things simple.\nThe function _calc_decode_length() exposed below summarizes this logic that we described. It’s very similar to the function _calc_encode_length(). Only the division part is twisted, and also, in the special case where we have less than 4 bytes in the input to work on. Also notice that this time, we apply a floor operation over the output of the division, by using the divFloor() function (instead of a ceiling operation with divCeil()).\n\nconst std = @import(\"std\");\nfn _calc_decode_length(input: []const u8) !usize {\n    if (input.len &lt; 4) {\n        const n_output: usize = 3;\n        return n_output;\n    }\n    const n_output: usize = try std.math.divFloor(\n        usize, input.len, 4\n    );\n    return n_output * 3;\n}",
     "crumbs": [
       "<span class='chapter-number'>4</span>  <span class='chapter-title'>Project 1 - Building a base64 encoder/decoder</span>"
     ]
@@ -394,7 +394,7 @@
     "href": "Chapters/01-base64.html#sec-encoder-logic",
     "title": "4  Project 1 - Building a base64 encoder/decoder",
     "section": "4.4 Building the encoder logic",
-    "text": "4.4 Building the encoder logic\nIn this section, we can start building the logic behind the encode() function, which will be responsible for encoding messages into the base64 encoding system. If you are an anxious person, and you want to see now the full source code of the implementation for this base64 encoder/decoder, you can find it at the ZigExamples folder in the official repository of this book2.\n\n4.4.1 The 6-bit transformation\nThe 6-bit transformation presented at Figure 4.1 is the core part of the base64 encoder algorithm. By understanding how this transformation is made in code, the rest of the algorithm becomes much simpler to comprehend.\nIn essence, this 6-bit transformation is made with the help of bitwise operators. Bitwise operators are essential to any type of low-level operation that is done at the bit-level. For the specific case of the base64 algorithm, the operators bif shift to the left (&lt;&lt;), bit shift to the right (&gt;&gt;), and the bitwise and (&) are used. They are the core solution for the 6-bit transformation.\nThere are 3 different scenarios that we need to take into account in this transformation. First, is the perfect scenario, where we have the perfect window of 3 bytes to work on. Second, we have the scenario where we have a window of only two bytes to work with. And last, we have the scenario where we have a window of one single byte.\nIn each of these 3 scenarios, the 6-bit transformation works a bit differently. To make the explanation easier, I will use the variable output to refer to the bytes in the output of the base64 encoder, and the variable input to refer to the bytes in the input of the encoder.\nSo, if you have the perfect window of 3 bytes, these are steps for the 6-bit transformation:\n\noutput[0] is produced by moving the bits from input[0] two positions to the right.\noutput[1] is produced by summing two components. First, take the last two bits from input[0], then, move them four positions to the left. Second, move the bits from input[1] four positions to the right. Sum these two components.\noutput[2] is produced by summing two components. First, take the last four bits from input[1], then, move them two positions to the left. Second, move the bits from input[2] six positions to the right. Sum these two components.\noutput[3] is produced by taking the last six bits from input[2].\n\nThis is the perfect scenario, where we have a full window of 3 bytes to work on. Just to make things as clear as possible, the Figure 4.3 demonstrates visually how the step 2 mentioned above works. So the 2nd byte in the output of the encoder, is made by taking the 1st byte (dark purple) and the 2nd byte (orange) from the input. You can see that, at the end of the process, we get a new byte that contains the last 2 bits from the 1st byte in the input, and the first 4 bits from the 2nd byte in the input.\n\n\n\n\n\n\nFigure 4.3: How the 2nd byte in the output of the encoder is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input.\n\n\n\nOn the other hand, we must be prepared for the instances where we do not have the perfect window of 3 bytes. If you have a window of 2 bytes, then, the steps 3 and 4, which produces the bytes output[2] and output[3], change a little bit, and they become:\n\noutput[2] is produced by taking the last 4 bits from input[1], then, move them two positions to the left.\noutput[3] is the character '='.\n\nFinally, if you have a window of a single byte, then, the steps 2 to 4, which produces the bytes output[1], output[2] and output[3] change, becoming:\n\noutput[1] is produced by taking the last two bits from input[0], then, move them four positions to the left.\noutput[2] and output[3] are the character =.\n\nIf these bullet points were a bit confusing for you, you may find the Table 4.1 more intuitive. This table unifies all this logic into a simple table. Notice that this table also provides the exact expression in Zig that creates the corresponding byte in the output.\n\n\n\nTable 4.1: How the 6-bit transformation translates into code in different window settings.\n\n\n\n\n\n\n\n\n\n\nNumber of bytes in the window\nByte index in the output\nIn code\n\n\n\n\n3\n0\ninput[0] &gt;&gt; 2\n\n\n3\n1\n((input[0] & 0x03) &lt;&lt; 4) + (input[1] &gt;&gt; 4)\n\n\n3\n2\n((input[1] & 0x0f) &lt;&lt; 2) + (input[2] &gt;&gt; 6)\n\n\n3\n3\ninput[2] & 0x3f\n\n\n2\n0\ninput[0] &gt;&gt; 2\n\n\n2\n1\n((input[0] & 0x03) &lt;&lt; 4) + (input[1] &gt;&gt; 4)\n\n\n2\n2\n((input[1] & 0x0f) &lt;&lt; 2)\n\n\n2\n3\n‘=’\n\n\n1\n0\ninput[0] &gt;&gt; 2\n\n\n1\n1\n((input[0] & 0x03) &lt;&lt; 4)\n\n\n1\n2\n‘=’\n\n\n1\n3\n‘=’\n\n\n\n\n\n\n\n\n4.4.2 Bit-shifting in Zig\nBit-shifting in Zig works similarly to bit-shifting in C. All bitwise operators that exist in C are available in Zig. Here, in the base64 encoder algorithm, they are essential to produce the result we want.\nFor those who are not familiar with these operators, they are operators that operates at the bit-level of your values. This means that these operators takes the bits that form the value you have, and change them in some way. This ultimately also changes the value itself, because the binary representation of this value changes.\nWe have already seen at Figure 4.3 the effect produced by a bit-shift. But let’s use the first byte in the output of the base64 encoder as another example of what bit-shifting means. This is the easiest byte of the 4 bytes in the output to build. Because we only need to move the bits from the first byte in the input two positions to the right, with the bit shift to the right (&gt;&gt;) operator.\nIf we take the string “Hi” that we used at Figure 4.1 as an example, the first byte in this string is “H”, which is the sequence 01001000 in binary. If we move the bits of this byte, two places to the right, we get the sequence 00010010 as result. This binary sequence is the value 18 in decimal, and also, the value 0x12 in hexadecimal. Notice that the first 6 bits of “H” were moved to the end of the byte. With this operation, we get the first byte of the output.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const input = \"Hi\";\n    try stdout.print(\"{d}\\n\", .{input[0] &gt;&gt; 2});\n}\n\n18\n\n\nIf you recall Figure 4.1, the first byte present in the output should be equivalent to the 6-bit group 010010. Although being visually different, the sequences 010010 and 00010010 are semantically equal. They mean the same thing. They both represent the number 18 in decimal, and the value 0x12 in hexadecimal.\nSo, don’t take the “6-bit group” factor so seriously. We do not need necessarily to get a 6-bit sequence as result. As long as the meaning of the 8-bit sequence we get is the same of the 6-bit sequence, we are in the clear.\n\n\n4.4.3 Selecting specific bits with the & operator\nIf you comeback to Section 4.4.1, you will see that, in order to produce the second and third bytes in the output, we need to select specific bits from the first and second bytes in the input string. But how can we do that? The answer relies on the bitwise and (&) operator.\nThe Figure 4.3 already showed you what effect this & operator produces in the bits of its operands. But let’s make a clear description of it.\nIn summary, the & operator performs a logical conjunction operation between the bits of its operands. In more details, the operator & compares each bit of the first operand to the corresponding bit of the second operand. If both bits are 1, the corresponding result bit is set to 1. Otherwise, the corresponding result bit is set to 0 (Microsoft 2021).\nSo, if we apply this operator to the binary sequences 1000100 and 00001101 the result of this operation is the binary sequence 00000100. Because only at the sixth position in both binary sequences we had a 1 value. So any position where we do not have both binary sequences setted to 1, we get a 0 bit in the resulting binary sequence.\nWe lose information about the original bit values from both sequences in this case. Because we no longer know if this 0 bit in the resulting binary sequence was produced by combining 0 with 0, or 1 with 0, or 0 with 1.\nAs an example, suppose you have the binary sequence 10010111, which is the number 151 in decimal. How can we get a new binary sequence which contains only the third and fourth bits of this sequence?\nWe just need to combine this sequence with 00110000 (is 0x30 in hexadecimal) using the & operator. Notice that only the third and fourth positions in this binary sequence is setted to 1. As a consequence, only the third and fourth values of both binary sequences are potentially preserved in the output. All the remaining positions are setted to zero in the output sequence, which is 00010000 (is the number 16 in decimal).\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const bits = 0b10010111;\n    try stdout.print(\"{d}\\n\", .{bits & 0b00110000});\n}\n\n16\n\n\n\n\n4.4.4 Allocating space for the output\nAs I described at Section 3.1.4, to store an object in the stack, this object needs to have a known and fixed length at compile-time. This is an important limitation for our base64 encoder/decoder case. Because the size of the output (from both the encoder and decoder) depends directly on the size of the input.\nHaving this in mind, we cannot know at compile time which is the size of the output for both the encoder and decoder. So, if we can’t know the size of the output at compile time, this means that we cannot store the output for both the encoder and decoder in the stack.\nConsequently, we need to store this output on the heap, and, as I commented at Section 3.1.5, we can only store objects in the heap by using allocator objects. So, one the arguments to both the encode() and decode() functions, needs to be an allocator object, because we know for sure that, at some point inside the body of these functions, we need to allocate space on the heap to store the output of these functions.\nThat is why, both the encode() and decode() functions that I present in this book, have an argument called allocator, which receives a allocator object as input, identified by the type std.mem.Allocator from the Zig Standard Library.\n\n\n4.4.5 Writing the encode() function\nNow that we have a basic understanding on how the bitwise operators work, and how exactly they help us to achieve the result we want to achieve. We can now encapsulate all the logic that we have described at Figure 4.1 and Table 4.1 into a nice function that we can add to our Base64 struct definition, that we started at Section 4.1.2.\nYou can find the encode() function below. Notice that the first argument of this function, is the Base64 struct itself. Therefore, this argument clearly signals that this function is a method from the Base64 struct.\nBecause the encode() function itself is fairly long, I intentionally omitted the Base64 struct definition in this source code, just for brevity reasons. So, just remember that this function is a public function (or a public method) from the Base64 struct.\nFurthermore, this encode() function has two other arguments:\n\ninput is the input sequence of characters that you want to encode in base64;\nallocator is an allocator object to use in the necessary memory allocations.\n\nI described everything you need to know about allocator objects at Section 3.3. So, if you are not familiar with them, I highly recommend you to comeback to that section, and read it. By looking at the encode() function, you will see that we use this allocator object to allocate enough memory to store the output of the encoding process.\nThe main for loop in the function is responsible for iterating through the entire input string. In every iteration, we use a count variable to count how many iterations we had at the moment. When count reaches 3, then, we try to encode the 3 characters (or bytes) that we have accumulated in the temporary buffer object (buf).\nAfter encoding these 3 characters and storing the result in the output variable, we reset the count variable to zero, and start to count again on the next iteration of the loop. If the loop hits the end of the string, and, the count variable is less than 3, then, it means that the temporary buffer contains the last 1 or 2 bytes from the input. That is why we have two if statements after the for loop. To deal which each possible case.\n\npub fn encode(self: Base64,\n              allocator: std.mem.Allocator,\n              input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n\n    const n_out = try _calc_encode_length(input);\n    var out = try allocator.alloc(u8, n_out);\n    var buf = [3]u8{ 0, 0, 0 };\n    var count: u8 = 0;\n    var iout: u64 = 0;\n\n    for (input, 0..) |_, i| {\n        buf[count] = input[i];\n        count += 1;\n        if (count == 3) {\n            out[iout] = self._char_at(buf[0] &gt;&gt; 2);\n            out[iout + 1] = self._char_at(\n                ((buf[0] & 0x03) &lt;&lt; 4) + (buf[1] &gt;&gt; 4)\n            );\n            out[iout + 2] = self._char_at(\n                ((buf[1] & 0x0f) &lt;&lt; 2) + (buf[2] &gt;&gt; 6)\n            );\n            out[iout + 3] = self._char_at(buf[2] & 0x3f);\n            iout += 4;\n            count = 0;\n        }\n    }\n\n    if (count == 1) {\n        out[iout] = self._char_at(buf[0] &gt;&gt; 2);\n        out[iout + 1] = self._char_at(\n            (buf[0] & 0x03) &lt;&lt; 4\n        );\n        out[iout + 2] = '=';\n        out[iout + 3] = '=';\n    }\n\n    if (count == 2) {\n        out[iout] = self._char_at(buf[0] &gt;&gt; 2);\n        out[iout + 1] = self._char_at(\n            ((buf[0] & 0x03) &lt;&lt; 4) + (buf[1] &gt;&gt; 4)\n        );\n        out[iout + 2] = self._char_at(\n            (buf[1] & 0x0f) &lt;&lt; 2\n        );\n        out[iout + 3] = '=';\n        iout += 4;\n    }\n\n    return out;\n}",
+    "text": "4.4 Building the encoder logic\nIn this section, we can start building the logic behind the encode() function, which will be responsible for encoding messages into the base64 encoding system. If you are an anxious person, and you want to see now the full source code of the implementation for this base64 encoder/decoder, you can find it at the ZigExamples folder in the official repository of this book2.\n\n4.4.1 The 6-bit transformation\nThe 6-bit transformation presented in Figure 4.1 is the core part of the base64 encoder algorithm. By understanding how this transformation is made in code, the rest of the algorithm becomes much simpler to comprehend.\nIn essence, this 6-bit transformation is made with the help of bitwise operators. Bitwise operators are essential to any type of low-level operation that is done at the bit-level. For the specific case of the base64 algorithm, the operators bif shift to the left (&lt;&lt;), bit shift to the right (&gt;&gt;), and the bitwise and (&) are used. They are the core solution for the 6-bit transformation.\nThere are 3 different scenarios that we need to take into account in this transformation. First, is the perfect scenario, where we have the perfect window of 3 bytes to work on. Second, we have the scenario where we have a window of only two bytes to work with. And last, we have the scenario where we have a window of one single byte.\nIn each of these 3 scenarios, the 6-bit transformation works a bit differently. To make the explanation easier, I will use the variable output to refer to the bytes in the output of the base64 encoder, and the variable input to refer to the bytes in the input of the encoder.\nSo, if you have the perfect window of 3 bytes, these are steps for the 6-bit transformation:\n\noutput[0] is produced by moving the bits from input[0] two positions to the right.\noutput[1] is produced by summing two components. First, take the last two bits from input[0], then, move them four positions to the left. Second, move the bits from input[1] four positions to the right. Sum these two components.\noutput[2] is produced by summing two components. First, take the last four bits from input[1], then, move them two positions to the left. Second, move the bits from input[2] six positions to the right. Sum these two components.\noutput[3] is produced by taking the last six bits from input[2].\n\nThis is the perfect scenario, where we have a full window of 3 bytes to work on. Just to make things as clear as possible, the Figure 4.3 demonstrates visually how the step 2 mentioned above works. So the 2nd byte in the output of the encoder, is made by taking the 1st byte (dark purple) and the 2nd byte (orange) from the input. You can see that, at the end of the process, we get a new byte that contains the last 2 bits from the 1st byte in the input, and the first 4 bits from the 2nd byte in the input.\n\n\n\n\n\n\nFigure 4.3: How the 2nd byte in the output of the encoder is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input.\n\n\n\nOn the other hand, we must be prepared for the instances where we do not have the perfect window of 3 bytes. If you have a window of 2 bytes, then, the steps 3 and 4, which produces the bytes output[2] and output[3], change a little bit, and they become:\n\noutput[2] is produced by taking the last 4 bits from input[1], then, move them two positions to the left.\noutput[3] is the character '='.\n\nFinally, if you have a window of a single byte, then, the steps 2 to 4, which produces the bytes output[1], output[2] and output[3] change, becoming:\n\noutput[1] is produced by taking the last two bits from input[0], then, move them four positions to the left.\noutput[2] and output[3] are the character =.\n\nIf these bullet points were a bit confusing for you, you may find the Table 4.1 more intuitive. This table unifies all this logic into a simple table. Notice that this table also provides the exact expression in Zig that creates the corresponding byte in the output.\n\n\n\nTable 4.1: How the 6-bit transformation translates into code in different window settings.\n\n\n\n\n\n\n\n\n\n\nNumber of bytes in the window\nByte index in the output\nIn code\n\n\n\n\n3\n0\ninput[0] &gt;&gt; 2\n\n\n3\n1\n((input[0] & 0x03) &lt;&lt; 4) + (input[1] &gt;&gt; 4)\n\n\n3\n2\n((input[1] & 0x0f) &lt;&lt; 2) + (input[2] &gt;&gt; 6)\n\n\n3\n3\ninput[2] & 0x3f\n\n\n2\n0\ninput[0] &gt;&gt; 2\n\n\n2\n1\n((input[0] & 0x03) &lt;&lt; 4) + (input[1] &gt;&gt; 4)\n\n\n2\n2\n((input[1] & 0x0f) &lt;&lt; 2)\n\n\n2\n3\n‘=’\n\n\n1\n0\ninput[0] &gt;&gt; 2\n\n\n1\n1\n((input[0] & 0x03) &lt;&lt; 4)\n\n\n1\n2\n‘=’\n\n\n1\n3\n‘=’\n\n\n\n\n\n\n\n\n4.4.2 Bit-shifting in Zig\nBit-shifting in Zig works similarly to bit-shifting in C. All bitwise operators that exist in C are available in Zig. Here, in the base64 encoder algorithm, they are essential to produce the result we want.\nFor those who are not familiar with these operators, they are operators that operates at the bit-level of your values. This means that these operators takes the bits that form the value you have, and change them in some way. This ultimately also changes the value itself, because the binary representation of this value changes.\nWe have already seen in Figure 4.3 the effect produced by a bit-shift. But let’s use the first byte in the output of the base64 encoder as another example of what bit-shifting means. This is the easiest byte of the 4 bytes in the output to build. Because we only need to move the bits from the first byte in the input two positions to the right, with the bit shift to the right (&gt;&gt;) operator.\nIf we take the string “Hi” that we used in Figure 4.1 as an example, the first byte in this string is “H”, which is the sequence 01001000 in binary. If we move the bits of this byte, two places to the right, we get the sequence 00010010 as result. This binary sequence is the value 18 in decimal, and also, the value 0x12 in hexadecimal. Notice that the first 6 bits of “H” were moved to the end of the byte. With this operation, we get the first byte of the output.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const input = \"Hi\";\n    try stdout.print(\"{d}\\n\", .{input[0] &gt;&gt; 2});\n}\n\n18\n\n\nIf you recall Figure 4.1, the first byte present in the output should be equivalent to the 6-bit group 010010. Although being visually different, the sequences 010010 and 00010010 are semantically equal. They mean the same thing. They both represent the number 18 in decimal, and the value 0x12 in hexadecimal.\nSo, don’t take the “6-bit group” factor so seriously. We do not need necessarily to get a 6-bit sequence as result. As long as the meaning of the 8-bit sequence we get is the same of the 6-bit sequence, we are in the clear.\n\n\n4.4.3 Selecting specific bits with the & operator\nIf you comeback to Section 4.4.1, you will see that, in order to produce the second and third bytes in the output, we need to select specific bits from the first and second bytes in the input string. But how can we do that? The answer relies on the bitwise and (&) operator.\nThe Figure 4.3 already showed you what effect this & operator produces in the bits of its operands. But let’s make a clear description of it.\nIn summary, the & operator performs a logical conjunction operation between the bits of its operands. In more details, the operator & compares each bit of the first operand to the corresponding bit of the second operand. If both bits are 1, the corresponding result bit is set to 1. Otherwise, the corresponding result bit is set to 0 (Microsoft 2021).\nSo, if we apply this operator to the binary sequences 1000100 and 00001101 the result of this operation is the binary sequence 00000100. Because only at the sixth position in both binary sequences we had a 1 value. So any position where we do not have both binary sequences setted to 1, we get a 0 bit in the resulting binary sequence.\nWe lose information about the original bit values from both sequences in this case. Because we no longer know if this 0 bit in the resulting binary sequence was produced by combining 0 with 0, or 1 with 0, or 0 with 1.\nAs an example, suppose you have the binary sequence 10010111, which is the number 151 in decimal. How can we get a new binary sequence which contains only the third and fourth bits of this sequence?\nWe just need to combine this sequence with 00110000 (is 0x30 in hexadecimal) using the & operator. Notice that only the third and fourth positions in this binary sequence is setted to 1. As a consequence, only the third and fourth values of both binary sequences are potentially preserved in the output. All the remaining positions are setted to zero in the output sequence, which is 00010000 (is the number 16 in decimal).\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const bits = 0b10010111;\n    try stdout.print(\"{d}\\n\", .{bits & 0b00110000});\n}\n\n16\n\n\n\n\n4.4.4 Allocating space for the output\nAs I described in Section 3.1.4, to store an object in the stack, this object needs to have a known and fixed length at compile-time. This is an important limitation for our base64 encoder/decoder case. Because the size of the output (from both the encoder and decoder) depends directly on the size of the input.\nHaving this in mind, we cannot know at compile time which is the size of the output for both the encoder and decoder. So, if we can’t know the size of the output at compile time, this means that we cannot store the output for both the encoder and decoder in the stack.\nConsequently, we need to store this output on the heap, and, as I commented in Section 3.1.5, we can only store objects in the heap by using allocator objects. So, one the arguments to both the encode() and decode() functions, needs to be an allocator object, because we know for sure that, at some point inside the body of these functions, we need to allocate space on the heap to store the output of these functions.\nThat is why, both the encode() and decode() functions that I present in this book, have an argument called allocator, which receives a allocator object as input, identified by the type std.mem.Allocator from the Zig Standard Library.\n\n\n4.4.5 Writing the encode() function\nNow that we have a basic understanding on how the bitwise operators work, and how exactly they help us to achieve the result we want to achieve. We can now encapsulate all the logic that we have described in Figure 4.1 and Table 4.1 into a nice function that we can add to our Base64 struct definition, that we started in Section 4.1.2.\nYou can find the encode() function below. Notice that the first argument of this function, is the Base64 struct itself. Therefore, this argument clearly signals that this function is a method from the Base64 struct.\nBecause the encode() function itself is fairly long, I intentionally omitted the Base64 struct definition in this source code, just for brevity reasons. So, just remember that this function is a public function (or a public method) from the Base64 struct.\nFurthermore, this encode() function has two other arguments:\n\ninput is the input sequence of characters that you want to encode in base64;\nallocator is an allocator object to use in the necessary memory allocations.\n\nI described everything you need to know about allocator objects in Section 3.3. So, if you are not familiar with them, I highly recommend you to comeback to that section, and read it. By looking at the encode() function, you will see that we use this allocator object to allocate enough memory to store the output of the encoding process.\nThe main for loop in the function is responsible for iterating through the entire input string. In every iteration, we use a count variable to count how many iterations we had at the moment. When count reaches 3, then, we try to encode the 3 characters (or bytes) that we have accumulated in the temporary buffer object (buf).\nAfter encoding these 3 characters and storing the result in the output variable, we reset the count variable to zero, and start to count again on the next iteration of the loop. If the loop hits the end of the string, and, the count variable is less than 3, then, it means that the temporary buffer contains the last 1 or 2 bytes from the input. That is why we have two if statements after the for loop. To deal which each possible case.\n\npub fn encode(self: Base64,\n              allocator: std.mem.Allocator,\n              input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n\n    const n_out = try _calc_encode_length(input);\n    var out = try allocator.alloc(u8, n_out);\n    var buf = [3]u8{ 0, 0, 0 };\n    var count: u8 = 0;\n    var iout: u64 = 0;\n\n    for (input, 0..) |_, i| {\n        buf[count] = input[i];\n        count += 1;\n        if (count == 3) {\n            out[iout] = self._char_at(buf[0] &gt;&gt; 2);\n            out[iout + 1] = self._char_at(\n                ((buf[0] & 0x03) &lt;&lt; 4) + (buf[1] &gt;&gt; 4)\n            );\n            out[iout + 2] = self._char_at(\n                ((buf[1] & 0x0f) &lt;&lt; 2) + (buf[2] &gt;&gt; 6)\n            );\n            out[iout + 3] = self._char_at(buf[2] & 0x3f);\n            iout += 4;\n            count = 0;\n        }\n    }\n\n    if (count == 1) {\n        out[iout] = self._char_at(buf[0] &gt;&gt; 2);\n        out[iout + 1] = self._char_at(\n            (buf[0] & 0x03) &lt;&lt; 4\n        );\n        out[iout + 2] = '=';\n        out[iout + 3] = '=';\n    }\n\n    if (count == 2) {\n        out[iout] = self._char_at(buf[0] &gt;&gt; 2);\n        out[iout + 1] = self._char_at(\n            ((buf[0] & 0x03) &lt;&lt; 4) + (buf[1] &gt;&gt; 4)\n        );\n        out[iout + 2] = self._char_at(\n            (buf[1] & 0x0f) &lt;&lt; 2\n        );\n        out[iout + 3] = '=';\n        iout += 4;\n    }\n\n    return out;\n}",
     "crumbs": [
       "<span class='chapter-number'>4</span>  <span class='chapter-title'>Project 1 - Building a base64 encoder/decoder</span>"
     ]
@@ -404,7 +404,7 @@
     "href": "Chapters/01-base64.html#sec-decoder-logic",
     "title": "4  Project 1 - Building a base64 encoder/decoder",
     "section": "4.5 Building the decoder logic",
-    "text": "4.5 Building the decoder logic\nNow, we can focus on writing the base64 decoder logic. Remember from Figure 4.2 that, a base64 decoder does the inverse process of an encoder. So, all we need to do, is to write a decode() function that performs the inverse process that I exposed at Section 4.4.\n\n4.5.1 Mapping base64 characters to their indexes\nOne thing that we need to do, in order to decode a base64-encoded message, is to calculate the index in the base64 scale of every base64 character that we encounter in the decoder input.\nIn other words, the decoder receives as input, a sequence of base64 characters. We need to translate this sequence of characters into a sequence of indexes. These indexes are the index of each character in the base64 scale. This way, we get the value/byte that was calculated in the 6-bit transformation step of the encoder process.\nThere are probably better/faster ways to calculate this, especially using a “divide and conquer” type of strategy. But for now, I am satisfied with a simple and “brute force” type of strategy. The _char_index() function below contains this strategy.\nWe are essentially looping through the lookup table with the base64 scale, and comparing the character we got with each character in the base64 scale. If these characters match, then, we return the index of this character in the base64 scale as the result.\nNotice that, if the input character is '=', the function returns the index 64, which is “out of range” in the scale. But, as I described at Section 4.1.1, the character '=' does not belong to the base64 scale itself. It is a special and meaningless character in base64.\nAlso notice that this _char_index() function is a method from our Base64 struct, because of the self argument. Again, I have omitted the Base64 struct definition in this example for brevity reasons.\n\nfn _char_index(self: Base64, char: u8) u8 {\n    if (char == '=')\n        return 64;\n    var index: u8 = 0;\n    for (0..63) |i| {\n        if (self._char_at(i) == char)\n            break;\n        index += 1;\n    }\n\n    return index;\n}\n\n\n\n4.5.2 The 6-bit transformation\nOnce again, the core part of the algorithm is the 6-bit transformation. If we understand the necessary steps to perform this transformation, the rest of the algorithm becomes much easier.\nFirst of all, before we actually go to the 6-bit transformation, we need to make sure that we use _char_index() to convert the sequence of base64 characters into a sequence of indexes. So the snippet below is important for the job that will be done. The result of _char_index() is stored in a temporary buffer, and this temporary buffer is what we are going to use in the 6-bit transformation, instead of the actual input object.\n\nfor (0..input.len) |i| {\n    buf[i] = self._char_index(input[i]);\n}\n\nNow, instead of producing 4 bytes (or 4 characters) as output per each window of 3 characters in the input, a base64 decoder produces 3 bytes (or 3 characters) as output per each window of 4 characters in the input. Once again, is the inverse process.\nSo, the steps to produce the 3 bytes in the output are:\n\noutput[0] is produced by summing two components. First, move the bits from buf[0] two positions to the left. Second, move the bits from buf[1] 4 positions to the right. Then, sum these two components.\noutput[1] is produced by summing two components. First, move the bits from buf[1] four positions to the left. Second, move the bits from buf[2] 2 positions to the right. Then, sum these two components.\noutput[2] is produced by summing two components. First, move the bits from buf[2] six positions to the left. Then, you sum the result with buf[3].\n\nBefore we continue, let’s try to visualize how these transformations make the original bytes that we had before the encoding process. First, think back to the 6-bit transformation performed by the encoder exposed at Section 4.4. The first byte in the output of the encoder is produced by moving the bits in the first byte of the input two positions to the right.\nIf for example the first byte in the input of the encoder was the sequence ABCDEFGH, then, the first byte in the output of the encoder would be 00ABCDEF (this sequence would be the first byte in the input of the decoder). Now, if the second byte in the input of the encoder was the sequence IJKLMNOP, then, the second byte in the encoder output would be 00GHIJKL (as we demonstrated at Figure 4.3).\nHence, if the sequences 00ABCDEF and 00GHIJKL are the first and second bytes, respectively, in the input of the decoder, the Figure 4.4 demonstrates visually how these two bytes are transformed into the first byte of the output of the decoder. Notice that the output byte is the sequence ABCDEFGH, which is the original byte from the input of the encoder.\n\n\n\n\n\n\nFigure 4.4: How the 1st byte in the decoder output is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input\n\n\n\nThe Table 4.2 presents how the three steps described earlier translate into Zig code:\n\n\n\nTable 4.2: The necessary steps for the 6-transformation in the decode process.\n\n\n\n\n\nByte index in the output\nIn code\n\n\n\n\n0\n(buf[0] &lt;&lt; 2) + (buf[1] &gt;&gt; 4)\n\n\n1\n(buf[1] &lt;&lt; 4) + (buf[2] &gt;&gt; 2)\n\n\n2\n(buf[2] &lt;&lt; 6) + buf[3]\n\n\n\n\n\n\n\n\n4.5.3 Writing the decode() function\nThe decode() function below contains the entire decoding process. We first calculate the size of the output, with _calc_decode_length(), then, we allocate enough memory for this output with the allocator object.\nThree temporary variables are created: 1) count, to hold the window count in each iteration of the for loop; 2) iout, to hold the current index in the output; 3) buf, which is the temporary buffer that holds the base64 indexes to be converted through the 6-bit transformation.\nThen, in each iteration of the for loop we fill the temporary buffer with the current window of bytes. When count hits the number 4, then, we have a full window of indexes in buf to be converted, and then, we apply the 6-bit transformation over the temporary buffer.\nNotice that we check if the indexes 2 and 3 in the temporary buffer are the number 64, which, if you recall from Section 4.5.1, is when the _calc_index() function receives a '=' character as input. So, if these indexes are equal to the number 64, the decode() function knows that it can simply ignore these indexes. They are not converted because, as I described before, the character '=' has no meaning, despite being the end of meaningful characters in the sequence. So we can safely ignore them when they appear in the sequence.\n\nfn decode(self: Base64,\n          allocator: std.mem.Allocator,\n          input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n    const n_output = try _calc_decode_length(input);\n    var output = try allocator.alloc(u8, n_output);\n    var count: u8 = 0;\n    var iout: u64 = 0;\n    var buf = [4]u8{ 0, 0, 0, 0 };\n\n    for (0..input.len) |i| {\n        buf[count] = self._char_index(input[i]);\n        count += 1;\n        if (count == 4) {\n            output[iout] = (buf[0] &lt;&lt; 2) + (buf[1] &gt;&gt; 4);\n            if (buf[2] != 64) {\n                output[iout + 1] = (buf[1] &lt;&lt; 4) + (buf[2] &gt;&gt; 2);\n            }\n            if (buf[3] != 64) {\n                output[iout + 2] = (buf[2] &lt;&lt; 6) + buf[3];\n            }\n            iout += 3;\n            count = 0;\n        }\n    }\n\n    return output;\n}",
+    "text": "4.5 Building the decoder logic\nNow, we can focus on writing the base64 decoder logic. Remember from Figure 4.2 that, a base64 decoder does the inverse process of an encoder. So, all we need to do, is to write a decode() function that performs the inverse process that I exposed in Section 4.4.\n\n4.5.1 Mapping base64 characters to their indexes\nOne thing that we need to do, in order to decode a base64-encoded message, is to calculate the index in the base64 scale of every base64 character that we encounter in the decoder input.\nIn other words, the decoder receives as input, a sequence of base64 characters. We need to translate this sequence of characters into a sequence of indexes. These indexes are the index of each character in the base64 scale. This way, we get the value/byte that was calculated in the 6-bit transformation step of the encoder process.\nThere are probably better/faster ways to calculate this, especially using a “divide and conquer” type of strategy. But for now, I am satisfied with a simple and “brute force” type of strategy. The _char_index() function below contains this strategy.\nWe are essentially looping through the lookup table with the base64 scale, and comparing the character we got with each character in the base64 scale. If these characters match, then, we return the index of this character in the base64 scale as the result.\nNotice that, if the input character is '=', the function returns the index 64, which is “out of range” in the scale. But, as I described in Section 4.1.1, the character '=' does not belong to the base64 scale itself. It’s a special and meaningless character in base64.\nAlso notice that this _char_index() function is a method from our Base64 struct, because of the self argument. Again, I have omitted the Base64 struct definition in this example for brevity reasons.\n\nfn _char_index(self: Base64, char: u8) u8 {\n    if (char == '=')\n        return 64;\n    var index: u8 = 0;\n    for (0..63) |i| {\n        if (self._char_at(i) == char)\n            break;\n        index += 1;\n    }\n\n    return index;\n}\n\n\n\n4.5.2 The 6-bit transformation\nOnce again, the core part of the algorithm is the 6-bit transformation. If we understand the necessary steps to perform this transformation, the rest of the algorithm becomes much easier.\nFirst of all, before we actually go to the 6-bit transformation, we need to make sure that we use _char_index() to convert the sequence of base64 characters into a sequence of indexes. So the snippet below is important for the job that will be done. The result of _char_index() is stored in a temporary buffer, and this temporary buffer is what we are going to use in the 6-bit transformation, instead of the actual input object.\n\nfor (0..input.len) |i| {\n    buf[i] = self._char_index(input[i]);\n}\n\nNow, instead of producing 4 bytes (or 4 characters) as output per each window of 3 characters in the input, a base64 decoder produces 3 bytes (or 3 characters) as output per each window of 4 characters in the input. Once again, is the inverse process.\nSo, the steps to produce the 3 bytes in the output are:\n\noutput[0] is produced by summing two components. First, move the bits from buf[0] two positions to the left. Second, move the bits from buf[1] 4 positions to the right. Then, sum these two components.\noutput[1] is produced by summing two components. First, move the bits from buf[1] four positions to the left. Second, move the bits from buf[2] 2 positions to the right. Then, sum these two components.\noutput[2] is produced by summing two components. First, move the bits from buf[2] six positions to the left. Then, you sum the result with buf[3].\n\nBefore we continue, let’s try to visualize how these transformations make the original bytes that we had before the encoding process. First, think back to the 6-bit transformation performed by the encoder exposed in Section 4.4. The first byte in the output of the encoder is produced by moving the bits in the first byte of the input two positions to the right.\nIf for example the first byte in the input of the encoder was the sequence ABCDEFGH, then, the first byte in the output of the encoder would be 00ABCDEF (this sequence would be the first byte in the input of the decoder). Now, if the second byte in the input of the encoder was the sequence IJKLMNOP, then, the second byte in the encoder output would be 00GHIJKL (as we demonstrated in Figure 4.3).\nHence, if the sequences 00ABCDEF and 00GHIJKL are the first and second bytes, respectively, in the input of the decoder, the Figure 4.4 demonstrates visually how these two bytes are transformed into the first byte of the output of the decoder. Notice that the output byte is the sequence ABCDEFGH, which is the original byte from the input of the encoder.\n\n\n\n\n\n\nFigure 4.4: How the 1st byte in the decoder output is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input\n\n\n\nThe Table 4.2 presents how the three steps described earlier translate into Zig code:\n\n\n\nTable 4.2: The necessary steps for the 6-transformation in the decode process.\n\n\n\n\n\nByte index in the output\nIn code\n\n\n\n\n0\n(buf[0] &lt;&lt; 2) + (buf[1] &gt;&gt; 4)\n\n\n1\n(buf[1] &lt;&lt; 4) + (buf[2] &gt;&gt; 2)\n\n\n2\n(buf[2] &lt;&lt; 6) + buf[3]\n\n\n\n\n\n\n\n\n4.5.3 Writing the decode() function\nThe decode() function below contains the entire decoding process. We first calculate the size of the output, with _calc_decode_length(), then, we allocate enough memory for this output with the allocator object.\nThree temporary variables are created: 1) count, to hold the window count in each iteration of the for loop; 2) iout, to hold the current index in the output; 3) buf, which is the temporary buffer that holds the base64 indexes to be converted through the 6-bit transformation.\nThen, in each iteration of the for loop we fill the temporary buffer with the current window of bytes. When count hits the number 4, then, we have a full window of indexes in buf to be converted, and then, we apply the 6-bit transformation over the temporary buffer.\nNotice that we check if the indexes 2 and 3 in the temporary buffer are the number 64, which, if you recall from Section 4.5.1, is when the _calc_index() function receives a '=' character as input. So, if these indexes are equal to the number 64, the decode() function knows that it can simply ignore these indexes. They are not converted because, as I described before, the character '=' has no meaning, despite being the end of meaningful characters in the sequence. So we can safely ignore them when they appear in the sequence.\n\nfn decode(self: Base64,\n          allocator: std.mem.Allocator,\n          input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n    const n_output = try _calc_decode_length(input);\n    var output = try allocator.alloc(u8, n_output);\n    var count: u8 = 0;\n    var iout: u64 = 0;\n    var buf = [4]u8{ 0, 0, 0, 0 };\n\n    for (0..input.len) |i| {\n        buf[count] = self._char_index(input[i]);\n        count += 1;\n        if (count == 4) {\n            output[iout] = (buf[0] &lt;&lt; 2) + (buf[1] &gt;&gt; 4);\n            if (buf[2] != 64) {\n                output[iout + 1] = (buf[1] &lt;&lt; 4) + (buf[2] &gt;&gt; 2);\n            }\n            if (buf[3] != 64) {\n                output[iout + 2] = (buf[2] &lt;&lt; 6) + buf[3];\n            }\n            iout += 3;\n            count = 0;\n        }\n    }\n\n    return output;\n}",
     "crumbs": [
       "<span class='chapter-number'>4</span>  <span class='chapter-title'>Project 1 - Building a base64 encoder/decoder</span>"
     ]
@@ -434,7 +434,7 @@
     "href": "Chapters/02-debugging.html",
     "title": "5  Debugging Zig applications",
     "section": "",
-    "text": "5.1 Print debugging\nWe begin with the classic and battle-tested print debugging strategy. The key advantage that debugging offers you is visibility. With print statements you can easily see what results and objects are being produced by your application.\nThat is the essence of print debugging. Is to use print expressions to see the values that are being generated by your program, and, as a result, get a much better understanding of how your program is behaving.\nMany programmers often resort to the print functions in Zig, such as the stdout.print(), or, the std.debug.print(), to get a better understanding of their programs. This is a known and old strategy that is very simple and effective, and it is better known within the programming community as print debugging. In Zig, you can print information to the stdout or stderr streams of your system.\nLet’s begin with stdout. First, you need to get access to the stdout, by calling the getStdOut() method, from the Zig Standard Library. This method returns a file descriptor object, and, through this object you can read/write to the stdout. I recommend you to check out all methods available in this object, by checking the page in the Zig Standard Library Official Reference for the type File1.\nFor our purpose here, which is to write something to the stdout, especially to debug our program, I recommend you to use the writer() method, which gives you a writer object. This writer object offers some helper methods to write stuff into the file descriptor object that represents the stdout stream. In special, the print() method.\nThe print() method from this writer object is a “print formatter” type of a function. In other words, this method works exactly like the printf() function from C, or, like println!() from Rust. In the first argument of the function, you specify a template string, and, in the second argument, you provide a list of values (or objects) that you want to insert into your template message.\nIdeally, the template string in the first argument should contain some format specifier. Each format specifier is matched to a value (or object) that you have listed in the second argument. So, if you provided 5 different objects in the second argument, then, the template string should contain 5 format specifiers, one for each object provided.\nEach format specifier is represented by a single letter, and you provide this format specifier inside a pair of curly braces. So, if you want to format your object using the string specifier (s), then, you can insert the text {s} in your template string. Here is a quick list of the most used format specifiers:\nThe code example below gives you an example of use of this print() method with the d format specifier.\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    try stdout.print(\"Result: {d}\", .{result});\n}\n\nResult: 50\nIt is important to emphasize that, the stdout.print() method, as you would expect, prints your template string into the stdout stream of your system. However, you can also print your template string into the stderr stream if your prefer. All you need to do, is to replace the stdout.print() call with the function std.debug.print(). Like this:\nconst std = @import(\"std\");\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    std.debug.print(\"Result: {d}\\n\", .{result});\n}\n\nResult: 50\nYou could also achieve the exact same result by getting a file descriptor object to stderr, then, creating a writer object to stderr, then, using the print() method of this writer object, like in the example below:\nconst std = @import(\"std\");\nconst stderr = std.io.getStdErr().writer();\n// some more lines ...\ntry stderr.print(\"Result: {d}\", .{result});",
+    "text": "5.1 Print debugging\nWe begin with the classic and battle-tested print debugging strategy. The key advantage that debugging offers you is visibility. With print statements you can easily see what results and objects are being produced by your application.\nThis is the essence of print debugging - using print expressions to see the values that are being generated by your program, and, as a result, get a much better understanding of how your program is behaving.\nMany programmers often resort to the print functions in Zig, such as the stdout.print(), or, the std.debug.print(), to get a better understanding of their programs. This is a known and old strategy that is very simple and effective, and it’s better known within the programming community as print debugging. In Zig, you can print information to the stdout or stderr streams of your system.\nLet’s begin with stdout. First, you need to get access to the stdout, by calling the getStdOut() method, from the Zig Standard Library. This method returns a file descriptor object, and, through this object you can read/write to the stdout. I recommend you to check out all methods available in this object, by checking the page in the Zig Standard Library Official Reference for the type File1.\nFor our purpose here, which is to write something to the stdout, especially to debug our program, I recommend you to use the writer() method, which gives you a writer object. This writer object offers some helper methods to write stuff into the file descriptor object that represents the stdout stream. In special, the print() method.\nThe print() method from this writer object is a “print formatter” type of a function. In other words, this method works exactly like the printf() function from C, or, like println!() from Rust. In the first argument of the function, you specify a template string, and, in the second argument, you provide a list of values (or objects) that you want to insert into your template message.\nIdeally, the template string in the first argument should contain some format specifier. Each format specifier is matched to a value (or object) that you have listed in the second argument. So, if you provided 5 different objects in the second argument, then, the template string should contain 5 format specifiers, one for each object provided.\nEach format specifier is represented by a single letter, and you provide this format specifier inside a pair of curly braces. So, if you want to format your object using the string specifier (s), then, you can insert the text {s} in your template string. Here is a quick list of the most used format specifiers:\nThe code example below gives you an example of use of this print() method with the d format specifier.\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    try stdout.print(\"Result: {d}\", .{result});\n}\n\nResult: 50\nIt’s important to emphasize that, the stdout.print() method, as you would expect, prints your template string into the stdout stream of your system. However, you can also print your template string into the stderr stream if your prefer. All you need to do, is to replace the stdout.print() call with the function std.debug.print(). Like this:\nconst std = @import(\"std\");\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    std.debug.print(\"Result: {d}\\n\", .{result});\n}\n\nResult: 50\nYou could also achieve the exact same result by getting a file descriptor object to stderr, then, creating a writer object to stderr, then, using the print() method of this writer object, like in the example below:\nconst std = @import(\"std\");\nconst stderr = std.io.getStdErr().writer();\n// some more lines ...\ntry stderr.print(\"Result: {d}\", .{result});",
     "crumbs": [
       "<span class='chapter-number'>5</span>  <span class='chapter-title'>Debugging Zig applications</span>"
     ]
@@ -444,7 +444,7 @@
     "href": "Chapters/02-debugging.html#print-debugging",
     "title": "5  Debugging Zig applications",
     "section": "",
-    "text": "d: for printing integers and floating-point numbers.\nc: for printing characters.\ns: for printing strings.\np: for printing memory addresses.\nx: for printing hexadecimal values.\nany: use any compatible format specifier (i.e. it automatically selects a format specifier for you).",
+    "text": "d: for printing integers and floating-point numbers.\nc: for printing characters.\ns: for printing strings.\np: for printing memory addresses.\nx: for printing hexadecimal values.\nany: use any compatible format specifier (i.e., it automatically selects a format specifier for you).",
     "crumbs": [
       "<span class='chapter-number'>5</span>  <span class='chapter-title'>Debugging Zig applications</span>"
     ]
@@ -454,7 +454,7 @@
     "href": "Chapters/02-debugging.html#debugging-through-debuggers",
     "title": "5  Debugging Zig applications",
     "section": "5.2 Debugging through debuggers",
-    "text": "5.2 Debugging through debuggers\nAlthough print debugging is a valid and very useful strategy, most programmers prefer to use a debugger to debug their programs. Since Zig is a low-level language, you can use either GDB (GNU Debugger), or LLDB (LLVM Project Debugger) as your debugger.\nBoth debuggers can work with Zig code, and it’s a matter of taste here. You choose the debugger of your preference, and you work with it. In this book, I will use LLDB as my debugger on the examples.\n\n5.2.1 Compile your source code in debug mode\nIn order to debug your program through a debugger, you must compile your source code in Debug mode. Because when you compile your source code in other modes (such as Release), the compiler usually strips out some essential information that is used by the debugger to read and track your program, like PDB (Program Database) files.\nBy compiling your source code in Debug mode, you ensure that the debugger will find the necessary information in your program to debug it. By default, the compiler uses the Debug mode when compiling your code. Having this in mind, when you compile your program with the build-exe command (which was described at Section 1.2.4), if you don’t specify an explicit mode through the -O command-line 2 argument, then, the compiler will compile your code in Debug mode.\n\n\n5.2.2 Let’s debug a program\nAs an example, let’s use LLDB to navigate and investigate the following piece of Zig code:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\nfn add_and_increment(a: u8, b: u8) u8 {\n    const sum = a + b;\n    const incremented = sum + 1;\n    return incremented;\n}\n\npub fn main() !void {\n    var n = add_and_increment(2, 3);\n    n = add_and_increment(n, n);\n    try stdout.print(\"Result: {d}!\\n\", .{n});\n}\n\nResult: 13!\n\n\nThere is nothing wrong with this program. But it is a good start for us. First, we need to compile this program with the zig build-exe command. For this example, suppose that I have compiled the above Zig code into a binary executable called add_program.\nzig build-exe add_program.zig\nNow, we can start LLDB with add_program, like this:\nlldb add_program\nFrom now on, LLDB is started, and you can know that I’m executing LLDB commands by looking at the prefix (lldb). If something is prefixed with (lldb), then you know that it is a LLDB command.\nThe first thing I will do, is to set a breakpoint at the main() function, by executing b main. After that, I just start the execution of the program with run. You can see in the output below, that the execution stopped at the first line in the function main(), as we expected.\n(lldb) b main\nBreakpoint 1: where = debugging`debug1.main + 22\n    at debug1.zig:11:30, address = 0x00000000010341a6\n(lldb) run\nProcess 8654 launched: 'add_program' (x86_64)\nProcess 8654 stopped\n* thread #1, name = 'add_program',\n    stop reason = breakpoint 1.1 frame #0: 0x10341a6\n    add_program`debug1.main at add_program.zig:11:30\n   8    }\n   9\n   10   pub fn main() !void {\n-&gt; 11       var n = add_and_increment(2, 3);\n   12       n = add_and_increment(n, n);\n   13       try stdout.print(\"Result: {d}!\\n\", .{n});\n   14   }\nI can start navigating through the code, and checking the objects that are being generated. If you are not familiar with the commands available in LLDB, I recommend you to read the official documentation of the project3. You can also look for cheat sheets, which quickly describes all commands available for you4.\nCurrently, we are in the first line at the main() function. In this line, we create the n object, by executing the add_and_increment() function. To execute the current line of code, and go to the next line, we can run the n LLDB command. Let’s execute this command.\nAfter we executed this line, we can also look at the value stored inside this n object by using the p LLDB command. The syntax for this command is p &lt;name-of-object&gt;.\nIf we take a look at the value stored in the n object (p n), notice that it stores the hexadecimal value 0x06, which is the number 6 in decimal. We can also see that this value has a type of unsigned char, which is an unsigned 8-bit integer. We have talked already about this at Section 1.8, that u8 integers in Zig are equivalent to the C data type unsigned char.\n(lldb) n\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step over frame #0: 0x10341ae\n    debugging`debug1.main at debug1.zig:12:26\n   9\n   10   pub fn main() !void {\n   11       var n = add_and_increment(2, 3);\n-&gt; 12       n = add_and_increment(n, n);\n   13       try stdout.print(\"Result: {d}!\\n\", .{n});\n   14   }\n(lldb) p n\n(unsigned char) $1 = '\\x06'\nNow, on the next line of code, we are executing the add_and_increment() function once again. Why not step inside this function? Shall we? We can do that, by executing the s LLDB command. Notice in the example below that, after executing this command, we have entered into the context of the add_and_increment() function.\nAlso notice in the example below that, I have walked two more lines in the function’s body, then, I execute the frame variable LLDB command, to see at once, the value stored in each of the variables that were created inside the current scope.\nYou can see in the output below that, the object sum stores the value \\f, which represents the form feed character. This character in the ASCII table, corresponds to the hexadecimal value 0x0C, or, in decimal, the number 12. So, this means that the result of the expression a + b executed at line 5, resulted in the number 12.\n(lldb) s\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step in frame #0: 0x10342de\n    debugging`debug1.add_and_increment(a='\\x02', b='\\x03')\n    at debug1.zig:4:39\n-&gt; 4    fn add_and_increment(a: u8, b: u8) u8 {\n   5        const sum = a + b;\n   6        const incremented = sum + 1;\n   7        return incremented;\n(lldb) n\n(lldb) n\n(lldb) frame variable\n(unsigned char) a = '\\x06'\n(unsigned char) b = '\\x06'\n(unsigned char) sum = '\\f'\n(unsigned char) incremented = '\\x06'",
+    "text": "5.2 Debugging through debuggers\nAlthough print debugging is a valid and very useful strategy, most programmers prefer to use a debugger to debug their programs. Since Zig is a low-level language, you can use either GDB (GNU Debugger), or LLDB (LLVM Project Debugger) as your debugger.\nBoth debuggers can work with Zig code, and it’s a matter of taste here. You choose the debugger of your preference, and you work with it. In this book, I will use LLDB as my debugger in the examples.\n\n5.2.1 Compile your source code in debug mode\nIn order to debug your program through a debugger, you must compile your source code in Debug mode. Because when you compile your source code in other modes (such as Release), the compiler usually strips out some essential information that is used by the debugger to read and track your program, like PDB (Program Database) files.\nBy compiling your source code in Debug mode, you ensure that the debugger will find the necessary information in your program to debug it. By default, the compiler uses the Debug mode when compiling your code. Having this in mind, when you compile your program with the build-exe command (which was described in Section 1.2.4), if you don’t specify an explicit mode through the -O command-line 2 argument, then, the compiler will compile your code in Debug mode.\n\n\n5.2.2 Let’s debug a program\nAs an example, let’s use LLDB to navigate and investigate the following piece of Zig code:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\nfn add_and_increment(a: u8, b: u8) u8 {\n    const sum = a + b;\n    const incremented = sum + 1;\n    return incremented;\n}\n\npub fn main() !void {\n    var n = add_and_increment(2, 3);\n    n = add_and_increment(n, n);\n    try stdout.print(\"Result: {d}!\\n\", .{n});\n}\n\nResult: 13!\n\n\nThere is nothing wrong with this program. But it’s a good start for us. First, we need to compile this program with the zig build-exe command. For this example, suppose that I have compiled the above Zig code into a binary executable called add_program.\nzig build-exe add_program.zig\nNow, we can start LLDB with add_program, like this:\nlldb add_program\nFrom now on, LLDB is started, and you can know that I’m executing LLDB commands by looking at the prefix (lldb). If something is prefixed with (lldb), then you know that it’s a LLDB command.\nThe first thing I will do, is to set a breakpoint at the main() function, by executing b main. After that, I just start the execution of the program with run. You can see in the output below, that the execution stopped at the first line in the function main(), as we expected.\n(lldb) b main\nBreakpoint 1: where = debugging`debug1.main + 22\n    at debug1.zig:11:30, address = 0x00000000010341a6\n(lldb) run\nProcess 8654 launched: 'add_program' (x86_64)\nProcess 8654 stopped\n* thread #1, name = 'add_program',\n    stop reason = breakpoint 1.1 frame #0: 0x10341a6\n    add_program`debug1.main at add_program.zig:11:30\n   8    }\n   9\n   10   pub fn main() !void {\n-&gt; 11       var n = add_and_increment(2, 3);\n   12       n = add_and_increment(n, n);\n   13       try stdout.print(\"Result: {d}!\\n\", .{n});\n   14   }\nI can start navigating through the code, and checking the objects that are being generated. If you are not familiar with the commands available in LLDB, I recommend you to read the official documentation of the project3. You can also look for cheat sheets, which quickly describes all commands available for you4.\nCurrently, we are in the first line at the main() function. In this line, we create the n object, by executing the add_and_increment() function. To execute the current line of code, and go to the next line, we can run the n LLDB command. Let’s execute this command.\nAfter we executed this line, we can also look at the value stored inside this n object by using the p LLDB command. The syntax for this command is p &lt;name-of-object&gt;.\nIf we take a look at the value stored in the n object (p n), notice that it stores the hexadecimal value 0x06, which is the number 6 in decimal. We can also see that this value has a type of unsigned char, which is an unsigned 8-bit integer. We have talked already about this in Section 1.8, that u8 integers in Zig are equivalent to the C data type unsigned char.\n(lldb) n\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step over frame #0: 0x10341ae\n    debugging`debug1.main at debug1.zig:12:26\n   9\n   10   pub fn main() !void {\n   11       var n = add_and_increment(2, 3);\n-&gt; 12       n = add_and_increment(n, n);\n   13       try stdout.print(\"Result: {d}!\\n\", .{n});\n   14   }\n(lldb) p n\n(unsigned char) $1 = '\\x06'\nNow, on the next line of code, we are executing the add_and_increment() function once again. Why not step inside this function? Shall we? We can do that, by executing the s LLDB command. Notice in the example below that, after executing this command, we have entered into the context of the add_and_increment() function.\nAlso notice in the example below that, I have walked two more lines in the function’s body, then, I execute the frame variable LLDB command, to see at once, the value stored in each of the variables that were created inside the current scope.\nYou can see in the output below that, the object sum stores the value \\f, which represents the form feed character. This character in the ASCII table, corresponds to the hexadecimal value 0x0C, or, in decimal, the number 12. So, this means that the result of the expression a + b executed at line 5, resulted in the number 12.\n(lldb) s\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step in frame #0: 0x10342de\n    debugging`debug1.add_and_increment(a='\\x02', b='\\x03')\n    at debug1.zig:4:39\n-&gt; 4    fn add_and_increment(a: u8, b: u8) u8 {\n   5        const sum = a + b;\n   6        const incremented = sum + 1;\n   7        return incremented;\n(lldb) n\n(lldb) n\n(lldb) frame variable\n(unsigned char) a = '\\x06'\n(unsigned char) b = '\\x06'\n(unsigned char) sum = '\\f'\n(unsigned char) incremented = '\\x06'",
     "crumbs": [
       "<span class='chapter-number'>5</span>  <span class='chapter-title'>Debugging Zig applications</span>"
     ]
@@ -484,7 +484,7 @@
     "href": "Chapters/05-pointers.html",
     "title": "6  Pointers and Optionals",
     "section": "",
-    "text": "6.1 Constant objects vs variable objects\nYou can have a pointer that points to a constant object, or, a pointer that points to a variable object. But regardless of who this pointer is, a pointer must always respect the characteristics of the object that it points to. As a consequence, if the pointer points to a constant object, then, you cannot use this pointer to change the value that it points to. Because it points to a value that is constant. As we discussed at Section 1.4, you cannot change a value that is constant.\nFor example, if I have a number object, which is constant, I cannot execute the expression below where I’m trying to change the value of number to 6 through the pointer object. As demonstrated below, when you try to do something like that, you get a compile time error:\nconst number = 5;\nconst pointer = &number;\npointer.* = 6;\nIf I change the number object to be a variable object, by introducing the var keyword, then, I can successfully change the value of this object through a pointer, as demonstrated below:\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n\n6\nYou can see this relationship between “constant versus variable” on the data type of your pointer object. In other words, the data type of a pointer object already gives you some clues about whether the value that it points to is constant or not.\nWhen a pointer object points to a constant value, then, this pointer have a data type *const T, which means “a pointer to a constant value of type T”. In contrast, if the pointer points to a variable value, then, the type of the pointer is usually *T, which is simply “a pointer to a value of type T”. Hence, whenever you see a pointer object whose data type is in the format *const T, then, you know that you cannot use this pointer to change the value that it points to. Because this pointer points to a constant value of type T.\nWe have talked about the value pointed by the pointer being constant or not, and the consequences that arises from it. But, what about the pointer object itself? I mean, what happens if the pointer object itself is constant or not? Think about it. We can have a constant pointer that points to a constant value. But we can also have a variable pointer that points to a constant value. And vice-versa.\nUntil this point, the pointer object was always constant, but what this means for us? What is the consequence of the pointer object being constant? The consequence is that we cannot change the pointer object, because it is constant. We can use the pointer object in multiple ways, but we cannot change the memory address that is inside this pointer object.\nHowever, if we mark the pointer object as a variable object, then, we can change the memory address pointed by this pointer object. The example below demonstrates that. Notice that the object pointed by the pointer object changes from c1 to c2.\nconst c1: u8 = 5;\nconst c2: u8 = 6;\nvar pointer = &c1;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\npointer = &c2;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\nThus, by setting the pointer object to a var or const object, you specify if the memory address contained in this pointer object can change or not in your program. On the other side, you can change the value pointed by the pointer, if, and only if this value is stored in a variable object. If this value is in a constant object, then, you cannot change this value through a pointer.",
+    "text": "6.1 Constant objects vs variable objects\nYou can have a pointer that points to a constant object, or, a pointer that points to a variable object. But regardless of who this pointer is, a pointer must always respect the characteristics of the object that it points to. As a consequence, if the pointer points to a constant object, then, you cannot use this pointer to change the value that it points to. Because it points to a value that is constant. As we discussed in Section 1.4, you cannot change a value that is constant.\nFor example, if I have a number object, which is constant, I cannot execute the expression below where I’m trying to change the value of number to 6 through the pointer object. As demonstrated below, when you try to do something like that, you get a compile time error:\nconst number = 5;\nconst pointer = &number;\npointer.* = 6;\nIf I change the number object to be a variable object, by introducing the var keyword, then, I can successfully change the value of this object through a pointer, as demonstrated below:\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n\n6\nYou can see this relationship between “constant versus variable” on the data type of your pointer object. In other words, the data type of a pointer object already gives you some clues about whether the value that it points to is constant or not.\nWhen a pointer object points to a constant value, then, this pointer have a data type *const T, which means “a pointer to a constant value of type T”. In contrast, if the pointer points to a variable value, then, the type of the pointer is usually *T, which is simply “a pointer to a value of type T”. Hence, whenever you see a pointer object whose data type is in the format *const T, then, you know that you cannot use this pointer to change the value that it points to. Because this pointer points to a constant value of type T.\nWe have talked about the value pointed by the pointer being constant or not, and the consequences that arises from it. But, what about the pointer object itself? I mean, what happens if the pointer object itself is constant or not? Think about it. We can have a constant pointer that points to a constant value. But we can also have a variable pointer that points to a constant value. And vice-versa.\nUntil this point, the pointer object was always constant, but what does this mean for us? What is the consequence of the pointer object being constant? The consequence is that we cannot change the pointer object, because it is constant. We can use the pointer object in multiple ways, but we cannot change the memory address that is inside this pointer object.\nHowever, if we mark the pointer object as a variable object, then, we can change the memory address pointed by this pointer object. The example below demonstrates that. Notice that the object pointed by the pointer object changes from c1 to c2.\nconst c1: u8 = 5;\nconst c2: u8 = 6;\nvar pointer = &c1;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\npointer = &c2;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\nThus, by setting the pointer object to a var or const object, you specify if the memory address contained in this pointer object can change or not in your program. On the other side, you can change the value pointed by the pointer, if, and only if this value is stored in a variable object. If this value is in a constant object, then, you cannot change this value through a pointer.",
     "crumbs": [
       "<span class='chapter-number'>6</span>  <span class='chapter-title'>Pointers and Optionals</span>"
     ]
@@ -514,7 +514,7 @@
     "href": "Chapters/05-pointers.html#pointer-arithmetic",
     "title": "6  Pointers and Optionals",
     "section": "6.3 Pointer arithmetic",
-    "text": "6.3 Pointer arithmetic\nPointer arithmetic is available in Zig, and they work the same way they work in C. When you have a pointer that points to an array, the pointer usually points to the first element in the array, and you can use pointer arithmetic to advance this pointer and access the other elements in the array.\nNotice in the example below, that initially, the ptr object was pointing to the first element in the array ar. But then, I started to walk through the array, by advancing the pointer with simple pointer arithmetic.\n\nconst ar = [_]i32{ 1, 2, 3, 4 };\nvar ptr: [*]const i32 = &ar;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\n\n1\n2\n3\nAlthough you can create a pointer to an array like that, and start to walk through this array by using pointer arithmetic, in Zig, we prefer to use slices, which were presented at Section 1.6.\nBehind the hood, slices already are pointers, and they also come with the len property, which indicates how many elements are in the slice. This is good because the zig compiler can use it to check for potential buffer overflows, and other problems like that.\nAlso, you don’t need to use pointer arithmetic to walk through the elements of a slice. You can simply use the slice[index] syntax to directly access any element you want in the slice. As I mentioned at Section 1.6, you can get a slice from an array by using a range selector inside brackets. In the example below, I’m creating a slice (sl) that covers the entire ar array. I can access any element of ar from this slice, and, the slice itself already is a pointer behind the hood.\n\nconst ar = [_]i32{1,2,3,4};\nconst sl = ar[0..ar.len];\n_ = sl;",
+    "text": "6.3 Pointer arithmetic\nPointer arithmetic is available in Zig, and they work the same way they work in C. When you have a pointer that points to an array, the pointer usually points to the first element in the array, and you can use pointer arithmetic to advance this pointer and access the other elements in the array.\nNotice in the example below, that initially, the ptr object was pointing to the first element in the array ar. But then, I started to walk through the array, by advancing the pointer with simple pointer arithmetic.\n\nconst ar = [_]i32{ 1, 2, 3, 4 };\nvar ptr: [*]const i32 = &ar;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\n\n1\n2\n3\nAlthough you can create a pointer to an array like that, and start to walk through this array by using pointer arithmetic, in Zig, we prefer to use slices, which were presented in Section 1.6.\nBehind the hood, slices already are pointers, and they also come with the len property, which indicates how many elements are in the slice. This is good because the zig compiler can use it to check for potential buffer overflows, and other problems like that.\nAlso, you don’t need to use pointer arithmetic to walk through the elements of a slice. You can simply use the slice[index] syntax to directly access any element you want in the slice. As I mentioned in Section 1.6, you can get a slice from an array by using a range selector inside brackets. In the example below, I’m creating a slice (sl) that covers the entire ar array. I can access any element of ar from this slice, and, the slice itself already is a pointer behind the hood.\n\nconst ar = [_]i32{1,2,3,4};\nconst sl = ar[0..ar.len];\n_ = sl;",
     "crumbs": [
       "<span class='chapter-number'>6</span>  <span class='chapter-title'>Pointers and Optionals</span>"
     ]
@@ -524,7 +524,7 @@
     "href": "Chapters/05-pointers.html#optionals-and-optional-pointers",
     "title": "6  Pointers and Optionals",
     "section": "6.4 Optionals and Optional Pointers",
-    "text": "6.4 Optionals and Optional Pointers\nLet’s talk about optionals and how they relate to pointers in Zig. By default, objects in Zig are non-nullable. This means that, in Zig, you can safely assume that any object in your source code is not null.\nThis is a powerful feature of Zig when you compare it to the developer experience in C. Because in C, any object can be null at any point, and, as consequence, a pointer in C might point to a null value. This is a common source of undefined behaviour in C. When programmers work with pointers in C, they have to constantly check if their pointers are pointing to null values or not.\nIf for some reason, your Zig code produces a null value somewhere, and, this null value ends up in an object that is non-nullable, a runtime error is always raised by your Zig program. Take the program below as an example. The zig compiler can see the null value at compile time, and, as result, it raises a compile time error. But, if a null value is raised during runtime, a runtime error is also raised by the Zig program, with a “attempt to use null value” message.\n\nvar number: u8 = 5;\nnumber = null;\n\np5.zig:5:14: error: expected type 'u8',\n        found '@TypeOf(null)'\n    number = null;\n             ^~~~\nYou don’t get this type of safety in C. In C, you don’t get warnings or errors about null values being produced in your program. If for some reason, your code produces a null value in C, most of the times, you end up getting a segmentation fault error as result, which can mean many things. That is why programmers have to constantly check for null values in C.\nPointers in Zig are also, by default, non-nullable. This is another amazing feature in Zig. So, you can safely assume that any pointer that you create in your Zig code is pointing to a non-null value. Therefore, you don’t have this heavy work of checking if the pointers you create in Zig are pointing to a null value.\n\n6.4.1 What are optionals?\nOk, we know now that all objects are non-nullable by default in Zig. But what if we actually need to use an object that might receive a null value? Here is where optionals come in.\nAn optional object in Zig is an object that can be null. To mark an object as optional, we use the ? operator. When you put this ? operator right before the data type of an object, you transform this data type into an optional data type, and the object becomes an optional object.\nTake the snippet below as an example. We are creating a new variable object called num. This object have the data type ?i32, which means that, this object contains either a signed 32-bit integer (i32), or, a null value. Both alternatives are valid values to the num object. That is why, I can actually change the value of this object to null, and, no errors are raised by the zig compiler, as demonstrated below:\n\nvar num: ?i32 = 5;\nnum = null;\n\n\n\n6.4.2 Optional pointers\nYou can also mark a pointer object as an optional pointer, meaning that, this object contains either a null value, or, a pointer that points to a value. When you mark a pointer as optional, the data type of this pointer object becomes ?*const T or ?*T, depending if the value pointed by the pointer is a constant value or not. The ? identifies the object as optional, while the * identifies it as a pointer object.\nIn the example below, we are creating a variable object named num, and an optional pointer object named ptr. Notice that the data type of the object ptr indicates that it is either a null value, or a pointer to an i32 value. Also, notice that the pointer object (ptr) can be marked as optional, even if the object num is not optional.\nWhat this code tells us is that, the num variable will never contain a null value. This variable will always contain a valid i32 value. But in contrast, the ptr object might contain either a null value, or, a pointer to an i32 value.\n\nvar num: i32 = 5;\nvar ptr: ?*i32 = &num;\nptr = null;\nnum = 6;\n\nBut what happens if we turn the table, and mark the num object as optional, instead of the pointer object. If we do that, then, the pointer object is not optional anymore. It would be a similar (although different) result. Because then, we would have a pointer to an optional value. In other words, a pointer to a value that is either a null value, or, a not-null value.\nIn the example below, we are recreating this idea. Now, the ptr object have a data type of *?i32, instead of ?*i32. Notice that the * symbol comes before of ? this time. So now, we have a pointer that points to a value that is either null , or, a signed 32-bit integer.\n\nvar num: ?i32 = 5;\n// ptr have type `*?i32`, instead of `?*i32`.\nconst ptr = &num;\n_ = ptr;\n\n\n\n6.4.3 Null handling in optionals\nWhen you have an optional object in your Zig code, you have to explicitly handle the possibility of this object being null. It is like error-handling with try and catch. In Zig you also have to handle null values like if they were a type of error.\nWe can do that, by using either:\n\nan if statement, like you would do in C.\nthe orelse keyword.\nunwrap the optional value with the ? method.\n\nWhen you use an if statement, you use a pair of pipes to unwrap the optional value, and use this “unwrapped object” inside the if block. Using the example below as a reference, if the object num is null, then, the code inside the if statement is not executed. Otherwise, the if statement will unwrap the object num into the not_null_num object. This not_null_num object is guaranteed to be not null inside the scope of the if statement.\n\nconst num: ?i32 = 5;\nif (num) |not_null_num| {\n    try stdout.print(\"{d}\\n\", .{not_null_num});\n}\n\n5\n\n\nNow, the orelse keyword behaves like a binary operator. You connect two expressions with this keyword. On the left side of orelse, you provide the expression that might result in a null value, and on the right side of orelse, you provide another expression that will not result in a null value.\nThe idea behind the orelse keyword is: if the expression on the left side result in a not-null value, then, this not-null value is used. However, if this expression on the left side result in a null value, then, the value of the expression on the right side is used instead.\nLooking at the example below, since the x object is currently null, the orelse decided to use the alternative value, which is the number 15.\n\nconst x: ?i32 = null;\nconst dbl = (x orelse 15) * 2;\ntry stdout.print(\"{d}\\n\", .{dbl});\n\n30\n\n\nYou can use the if statement or the orelse keyword, when you want to solve (or deal with) this null value. However, if there is no clear solution to this null value, and the most logic and sane path is to simply panic and raise a loud error in your program when this null value is encountered, you can use the ? method of your optional object.\nIn essence, when you use this ? method, the optional object is unwrapped. If a not-null value is found in the optional object, then, this not-null value is used. Otherwise, the unreachable keyword is used. You can read more about this unreacheable keyword at the official documentation1. But in essence, when you build your Zig source code using the build modes ReleaseSafe or Debug, this unreacheable keyword causes the program to panic and raise an error during runtime, like in the example below:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn return_null(n: i32) ?i32 {\n    if (n == 5) return null;\n    return n;\n}\n\npub fn main() !void {\n    const x: i32 = 5;\n    const y: ?i32 = return_null(x);\n    try stdout.print(\"{d}\\n\", .{y.?});\n}\n\nthread 12767 panic: attempt to use null value\np7.zig:12:34: 0x103419d in main (p7):\n    try stdout.print(\"{d}\\n\", .{y.?});\n                                 ^\n\n\n\n\nZig Software Foundation. 2024. “Language Reference.” Zig Software Foundation. https://ziglang.org/documentation/master/.",
+    "text": "6.4 Optionals and Optional Pointers\nLet’s talk about optionals and how they relate to pointers in Zig. By default, objects in Zig are non-nullable. This means that, in Zig, you can safely assume that any object in your source code is not null.\nThis is a powerful feature of Zig when you compare it to the developer experience in C. Because in C, any object can be null at any point, and, as consequence, a pointer in C might point to a null value. This is a common source of undefined behaviour in C. When programmers work with pointers in C, they have to constantly check if their pointers are pointing to null values or not.\nIf for some reason, your Zig code produces a null value somewhere, and, this null value ends up in an object that is non-nullable, a runtime error is always raised by your Zig program. Take the program below as an example. The zig compiler can see the null value at compile time, and, as result, it raises a compile time error. But, if a null value is raised during runtime, a runtime error is also raised by the Zig program, with a “attempt to use null value” message.\n\nvar number: u8 = 5;\nnumber = null;\n\np5.zig:5:14: error: expected type 'u8',\n        found '@TypeOf(null)'\n    number = null;\n             ^~~~\nYou don’t get this type of safety in C. In C, you don’t get warnings or errors about null values being produced in your program. If for some reason, your code produces a null value in C, most of the times, you end up getting a segmentation fault error as result, which can mean many things. That is why programmers have to constantly check for null values in C.\nPointers in Zig are also, by default, non-nullable. This is another amazing feature in Zig. So, you can safely assume that any pointer that you create in your Zig code is pointing to a non-null value. Therefore, you don’t have this heavy work of checking if the pointers you create in Zig are pointing to a null value.\n\n6.4.1 What are optionals?\nOk, we know now that all objects are non-nullable by default in Zig. But what if we actually need to use an object that might receive a null value? Here is where optionals come in.\nAn optional object in Zig is an object that can be null. To mark an object as optional, we use the ? operator. When you put this ? operator right before the data type of an object, you transform this data type into an optional data type, and the object becomes an optional object.\nTake the snippet below as an example. We are creating a new variable object called num. This object have the data type ?i32, which means that, this object contains either a signed 32-bit integer (i32), or, a null value. Both alternatives are valid values to the num object. That is why, I can actually change the value of this object to null, and, no errors are raised by the zig compiler, as demonstrated below:\n\nvar num: ?i32 = 5;\nnum = null;\n\n\n\n6.4.2 Optional pointers\nYou can also mark a pointer object as an optional pointer, meaning that, this object contains either a null value, or, a pointer that points to a value. When you mark a pointer as optional, the data type of this pointer object becomes ?*const T or ?*T, depending if the value pointed by the pointer is a constant value or not. The ? identifies the object as optional, while the * identifies it as a pointer object.\nIn the example below, we are creating a variable object named num, and an optional pointer object named ptr. Notice that the data type of the object ptr indicates that it’s either a null value, or a pointer to an i32 value. Also, notice that the pointer object (ptr) can be marked as optional, even if the object num is not optional.\nWhat this code tells us is that, the num variable will never contain a null value. This variable will always contain a valid i32 value. But in contrast, the ptr object might contain either a null value, or, a pointer to an i32 value.\n\nvar num: i32 = 5;\nvar ptr: ?*i32 = &num;\nptr = null;\nnum = 6;\n\nBut what happens if we turn the table, and mark the num object as optional, instead of the pointer object. If we do that, then, the pointer object is not optional anymore. It would be a similar (although different) result. Because then, we would have a pointer to an optional value. In other words, a pointer to a value that is either a null value, or, a not-null value.\nIn the example below, we are recreating this idea. Now, the ptr object have a data type of *?i32, instead of ?*i32. Notice that the * symbol comes before of ? this time. So now, we have a pointer that points to a value that is either null , or, a signed 32-bit integer.\n\nvar num: ?i32 = 5;\n// ptr have type `*?i32`, instead of `?*i32`.\nconst ptr = &num;\n_ = ptr;\n\n\n\n6.4.3 Null handling in optionals\nWhen you have an optional object in your Zig code, you have to explicitly handle the possibility of this object being null. It’s like error-handling with try and catch. In Zig you also have to handle null values like if they were a type of error.\nWe can do that, by using either:\n\nan if statement, like you would do in C.\nthe orelse keyword.\nunwrap the optional value with the ? method.\n\nWhen you use an if statement, you use a pair of pipes to unwrap the optional value, and use this “unwrapped object” inside the if block. Using the example below as a reference, if the object num is null, then, the code inside the if statement is not executed. Otherwise, the if statement will unwrap the object num into the not_null_num object. This not_null_num object is guaranteed to be not null inside the scope of the if statement.\n\nconst num: ?i32 = 5;\nif (num) |not_null_num| {\n    try stdout.print(\"{d}\\n\", .{not_null_num});\n}\n\n5\n\n\nNow, the orelse keyword behaves like a binary operator. You connect two expressions with this keyword. On the left side of orelse, you provide the expression that might result in a null value, and on the right side of orelse, you provide another expression that will not result in a null value.\nThe idea behind the orelse keyword is: if the expression on the left side result in a not-null value, then, this not-null value is used. However, if this expression on the left side result in a null value, then, the value of the expression on the right side is used instead.\nLooking at the example below, since the x object is currently null, the orelse decided to use the alternative value, which is the number 15.\n\nconst x: ?i32 = null;\nconst dbl = (x orelse 15) * 2;\ntry stdout.print(\"{d}\\n\", .{dbl});\n\n30\n\n\nYou can use the if statement or the orelse keyword, when you want to solve (or deal with) this null value. However, if there is no clear solution to this null value, and the most logic and sane path is to simply panic and raise a loud error in your program when this null value is encountered, you can use the ? method of your optional object.\nIn essence, when you use this ? method, the optional object is unwrapped. If a not-null value is found in the optional object, then, this not-null value is used. Otherwise, the unreachable keyword is used. You can read more about this unreacheable keyword at the official documentation1. But in essence, when you build your Zig source code using the build modes ReleaseSafe or Debug, this unreacheable keyword causes the program to panic and raise an error during runtime, like in the example below:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn return_null(n: i32) ?i32 {\n    if (n == 5) return null;\n    return n;\n}\n\npub fn main() !void {\n    const x: i32 = 5;\n    const y: ?i32 = return_null(x);\n    try stdout.print(\"{d}\\n\", .{y.?});\n}\n\nthread 12767 panic: attempt to use null value\np7.zig:12:34: 0x103419d in main (p7):\n    try stdout.print(\"{d}\\n\", .{y.?});\n                                 ^\n\n\n\n\nZig Software Foundation. 2024. “Language Reference.” Zig Software Foundation. https://ziglang.org/documentation/master/.",
     "crumbs": [
       "<span class='chapter-number'>6</span>  <span class='chapter-title'>Pointers and Optionals</span>"
     ]
@@ -544,7 +544,7 @@
     "href": "Chapters/04-http-server.html",
     "title": "7  Project 2 - Building a HTTP Server from scratch",
     "section": "",
-    "text": "7.1 What is a HTTP Server?\nFirst of all, what is a HTTP Server? A HTTP server, as any other type of server, is essentially a program that runs indefinitely, on an infinite loop, waiting for incoming connections from clients. Once the server receives an incoming connection, it will accept this connection, and it will send messages back-and-forth to the client through this connection.\nBut the messages that are transmitted inside this connection are in a specific format. They are HTTP messages (i.e. messages that use the HTTP Protocol specification). The HTTP Protocol is the backbone of the modern web. The world wide web as we know it today, would not exist without the HTTP Protocol.\nSo, Web servers (which is just a fancy name to HTTP Servers) are servers that exchange HTTP messages with clients. And these HTTP servers and the HTTP Protocol specification are essential to the operation of the world wide web today.\nThat is the whole picture of the process. Again, we have two subjects involved here, a server (which is a program that is running indefinitely, waiting to receive incoming connections), and a client (which is someone that wants to connect to the server, and exchange HTTP messages with it).\nYou may find the material about the HTTP Protocol available at the Mozilla MDN Docs1 , a great resource for you to also look at. It gives you a great overview on how HTTP works, and what role the server plays in this matter.",
+    "text": "7.1 What is a HTTP Server?\nFirst of all, what is a HTTP Server? A HTTP server, as any other type of server, is essentially a program that runs indefinitely, on an infinite loop, waiting for incoming connections from clients. Once the server receives an incoming connection, it will accept this connection, and it will send messages back-and-forth to the client through this connection.\nBut the messages that are transmitted inside this connection are in a specific format. They are HTTP messages (i.e., messages that use the HTTP Protocol specification). The HTTP Protocol is the backbone of the modern web. The world wide web as we know it today, would not exist without the HTTP Protocol.\nSo, Web servers (which is just a fancy name to HTTP Servers) are servers that exchange HTTP messages with clients. And these HTTP servers and the HTTP Protocol specification are essential to the operation of the world wide web today.\nThat is the whole picture of the process. Again, we have two subjects involved here, a server (which is a program that is running indefinitely, waiting to receive incoming connections), and a client (which is someone that wants to connect to the server, and exchange HTTP messages with it).\nYou may find the material about the HTTP Protocol available at the Mozilla MDN Docs1 , a great resource for you to also look at. It gives you a great overview on how HTTP works, and what role the server plays in this matter.",
     "crumbs": [
       "<span class='chapter-number'>7</span>  <span class='chapter-title'>Project 2 - Building a HTTP Server from scratch</span>"
     ]
@@ -554,7 +554,7 @@
     "href": "Chapters/04-http-server.html#sec-how-http-works",
     "title": "7  Project 2 - Building a HTTP Server from scratch",
     "section": "7.2 How a HTTP Server works?",
-    "text": "7.2 How a HTTP Server works?\nImagine a HTTP Server as if it were the receptionist of a large hotel. In a hotel, you have a reception, and inside that reception there is a receptionist waiting for customers to arrive. A HTTP Server is essentially a receptionist that is indefinitely waiting for new customers (or, in the context of HTTP, new clients) to arrive in the hotel.\nWhen a customer arrives at the hotel, that customer starts a conversation with the receptionist. He tells the receptionist how many days he wants to stay at the hotel. Then, the receptionist search for an available apartment. If there is an available apartment at the moment, the customer pays the hotel fees, then, he gets the keys to the apartment, and then, he goes to the apartment to rest.\nAfter this entire process of dealing with the customer (searching for available apartments, receiving payment, handing over the keys), the receptionist goes back to what he was doing earlier, which is to wait. Wait for new customers to arrive.\nThat is, in a nutshell, what a HTTP Server do. It waits for clients to connect to the server. When a client attempts to connect to the server, the server accepts this connection, and it starts to exchange messages with the client through this connection. The first message that happens inside this connection is always a message from the client to the server. This message is called the HTTP Request.\nThis HTTP Request is a HTTP message that contains what the client wants from the server. It is literally a request. The client that connected to the server is asking this server to do something for him.\nThere are different “types of request” that a client can send to a HTTP Server. But the most basic type of request, is when a client ask to the HTTP Server to serve (i.e. to send) some specific web page (which is a HTML file) to him. When you type google.com in your web browser, you are essentially sending a HTTP Request to Google’s HTTP servers. This request is asking these servers to send the Google webpage to you.\nNonetheless, when the server receives this first message, the HTTP Request, it analyzes this request, to understand: who the client is? What he wants the server to do? This client has provided all the necessary information to perform the action that he asked? Etc.\nOnce the server understands what the client wants, he simply perform the action that was requested, and, to finish the whole process, the server sends back a HTTP message to the client, informing if the action performed was successful or not, and, at last, the server ends (or closes) the connection with the client.\nThis last HTTP message sent from the server to the client, is called the HTTP Response. Because the server is responding to the action that was requested by the client. The main objective of this response message is let the client know if the action requested was successful or not, before the server closes the connection.",
+    "text": "7.2 How a HTTP Server works?\nImagine a HTTP Server as if it were the receptionist of a large hotel. In a hotel, you have a reception, and inside that reception there is a receptionist waiting for customers to arrive. A HTTP Server is essentially a receptionist that is indefinitely waiting for new customers (or, in the context of HTTP, new clients) to arrive in the hotel.\nWhen a customer arrives at the hotel, that customer starts a conversation with the receptionist. He tells the receptionist how many days he wants to stay at the hotel. Then, the receptionist search for an available apartment. If there is an available apartment at the moment, the customer pays the hotel fees, then, he gets the keys to the apartment, and then, he goes to the apartment to rest.\nAfter this entire process of dealing with the customer (searching for available apartments, receiving payment, handing over the keys), the receptionist goes back to what he was doing earlier, which is to wait. Wait for new customers to arrive.\nThat is, in a nutshell, what a HTTP Server do. It waits for clients to connect to the server. When a client attempts to connect to the server, the server accepts this connection, and it starts to exchange messages with the client through this connection. The first message that happens inside this connection is always a message from the client to the server. This message is called the HTTP Request.\nThis HTTP Request is a HTTP message that contains what the client wants from the server. It is literally a request. The client that connected to the server is asking this server to do something for him.\nThere are different “types of request” that a client can send to a HTTP Server. But the most basic type of request, is when a client ask to the HTTP Server to serve (i.e., to send) some specific web page (which is a HTML file) to him. When you type google.com in your web browser, you are essentially sending a HTTP Request to Google’s HTTP servers. This request is asking these servers to send the Google webpage to you.\nNonetheless, when the server receives this first message, the HTTP Request, it analyzes this request, to understand: who the client is? What he wants the server to do? This client has provided all the necessary information to perform the action that he asked? Etc.\nOnce the server understands what the client wants, he simply perform the action that was requested, and, to finish the whole process, the server sends back a HTTP message to the client, informing if the action performed was successful or not, and, at last, the server ends (or closes) the connection with the client.\nThis last HTTP message sent from the server to the client, is called the HTTP Response. Because the server is responding to the action that was requested by the client. The main objective of this response message is let the client know if the action requested was successful or not, before the server closes the connection.",
     "crumbs": [
       "<span class='chapter-number'>7</span>  <span class='chapter-title'>Project 2 - Building a HTTP Server from scratch</span>"
     ]
@@ -564,7 +564,7 @@
     "href": "Chapters/04-http-server.html#sec-http-how-impl",
     "title": "7  Project 2 - Building a HTTP Server from scratch",
     "section": "7.3 How a HTTP server is normally implemented?",
-    "text": "7.3 How a HTTP server is normally implemented?\nLet’s use the C language as an example. There are many materials teaching how to write a simple HTTP server in C code, like Yu (2023), or Weerasiri (2023), or Meehan (2021). Having this in mind, I will not show C code examples here, because you can find them on the internet. But I will describe the theory behind the necessary steps to create such HTTP server in C.\nIn essence, we normally implement a HTTP server in C by using WebSocket technology, which involves the following steps:\n\nCreate a socket object.\nBind a name (or more specifically, an address) to this socket object.\nMake this socket object to start listening and waiting for incoming connections.\nWhen a connection arrive, we accept this connection, and we exchange the HTTP messages (HTTP Request and HTTP Response).\nThen, we simply close this connection.\n\nA socket object is essentially a channel of communication. You are creating a channel where people can send messages through. When you create a socket object, this object is not binded to any particular address. This means that with this object you have a representation of a channel of communication in your hands. But this channel is not currently available, or, it is not currently accessible, because it do not have a known address where you can find it.\nThat is what the “bind” operation do. It binds a name (or more specifically, an address) to this socket object, or, this channel of communication, so that it becomes available, or, accessible through this address. While the “listen” operation makes the socket object to listen for incoming connections in this address. In other words, the “listen” operation makes the socket to wait for incoming connections. currently Now, when a client actually attempts to connect to the server through the socket address that we have specified, in order to establish this connection with the client, the socket object needs to accept this incoming connection. Thus, when we accept an incoming connection, the client and the server become connected to each other, and they can start reading or writing messages into this established connection.\nAfter we receive the HTTP Request from the client, analyze it, and send the HTTP Response to the client, we can then close the connection, and end this communication.",
+    "text": "7.3 How a HTTP server is normally implemented?\nLet’s use the C language as an example. There are many materials teaching how to write a simple HTTP server in C code, like Yu (2023), or Weerasiri (2023), or Meehan (2021). Having this in mind, I will not show C code examples here, because you can find them on the internet. But I will describe the theory behind the necessary steps to create such HTTP server in C.\nIn essence, we normally implement a HTTP server in C by using WebSocket technology, which involves the following steps:\n\nCreate a socket object.\nBind a name (or more specifically, an address) to this socket object.\nMake this socket object to start listening and waiting for incoming connections.\nWhen a connection arrive, we accept this connection, and we exchange the HTTP messages (HTTP Request and HTTP Response).\nThen, we simply close this connection.\n\nA socket object is essentially a channel of communication. You are creating a channel where people can send messages through. When you create a socket object, this object is not binded to any particular address. This means that with this object you have a representation of a channel of communication in your hands. But this channel is not currently available, or, it is not currently accessible, because it does not have a known address where you can find it.\nThat is what the “bind” operation do. It binds a name (or more specifically, an address) to this socket object, or, this channel of communication, so that it becomes available, or, accessible through this address. While the “listen” operation makes the socket object to listen for incoming connections in this address. In other words, the “listen” operation makes the socket to wait for incoming connections. currently Now, when a client actually attempts to connect to the server through the socket address that we have specified, in order to establish this connection with the client, the socket object needs to accept this incoming connection. Thus, when we accept an incoming connection, the client and the server become connected to each other, and they can start reading or writing messages into this established connection.\nAfter we receive the HTTP Request from the client, analyze it, and send the HTTP Response to the client, we can then close the connection, and end this communication.",
     "crumbs": [
       "<span class='chapter-number'>7</span>  <span class='chapter-title'>Project 2 - Building a HTTP Server from scratch</span>"
     ]
@@ -574,7 +574,7 @@
     "href": "Chapters/04-http-server.html#implementing-the-server---part-1",
     "title": "7  Project 2 - Building a HTTP Server from scratch",
     "section": "7.4 Implementing the server - Part 1",
-    "text": "7.4 Implementing the server - Part 1\n\n7.4.1 Creating the socket object\nLet’s begin with creating the socket object for our server. Just to make things shorter, I will create this socket object in a separate Zig module. I will name it config.zig.\nIn Zig, we can create a web socket using the std.posix.socket() function, from the Zig Standard Library. As I mentioned earlier at Section 7.3, every socket object that we create represents a communication channel, and we need to bind this channel to a specific address. An “address” is defined as an IP address, or, more specifically, an IPv4 address2. Every IPv4 address is composed by two components. The first component is the host, which is a sequence of 4 numbers separated by dot characters (.) that identifies the machine used. While the second component is a port number, which identifies the specific door, or, the specific port to use in the host machine.\nThe sequence of 4 numbers (i.e. the host) identifies the machine (i.e. the computer itself) where this socket will live in. Every computer normally have multiple “doors” available inside of him, because this allows the computer to receive and work with multiple connections at the same time. He simply use a single door for each connection. So the port number, is essentially a number that identifies the specific door in the computer that will be responsible for receiving the connection. That is, it identifies the “door” in the computer that the socket will use to receive incoming connections.\nTo make things simpler, I will use an IP address that identifies our current machine in this example. This means that, our socket object will reside on the same computer that we are currently using (this is also known as the “localhost”) to write this Zig source code.\nBy convention, the IP address that identifies the “localhost”, which is the current machine we are using, is the IP 127.0.0.1. So, that is the IP address we are going to use in our server. I can declare it in Zig by using an array of 4 integers, like this:\n\nconst localhost = [4]u8{ 127, 0, 0, 1 };\n_ = localhost;\n\nNow, we need to decide which port number to use. By convention, there are some port numbers that are reserved, meaning that, we cannot use them for our own purposes, like the port 22 (which is normally used for SSH connections). For TCP connections, which is our case here, a port number is a 16-bit unsigned integer (type u16 in Zig), thus ranging from 0 to 65535 (Wikipedia 2024). So, we can choose a number from 0 to 65535 for our port number. In the example of this book, I will use the port number 3490 (just a random number).\nNow that we have these two informations at hand, I can finally create our socket object, using the std.posix.socket() function. First, we use the host and the port number to create an Address object, with the std.net.Address.initIp4() function, like in the example below. After that, I use this address object inside the socket() function to create our socket object.\nThe Socket struct defined below summarizes all the logic behind this process. In this struct, we have two data members, which are: 1) the address object; 2) and a stream object, which is the object we will use to read and write the messages into any connection we establish.\nNotice that, inside the constructor method of this struct, when we create the socket object, we are using the IPROTO.TCP property as an input to tell the function to create a socket for TCP connections.\n\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\nconst net = @import(\"std\").net;\n\npub const Socket = struct {\n    _address: std.net.Address,\n    _stream: std.net.Stream,\n\n    pub fn init() !Socket {\n        const host = [4]u8{ 127, 0, 0, 1 };\n        const port = 3490;\n        const addr = net.Address.initIp4(host, port);\n        const socket = try std.posix.socket(\n            addr.any.family,\n            std.posix.SOCK.STREAM,\n            std.posix.IPPROTO.TCP\n        );\n        const stream = net.Stream{ .handle = socket };\n        return Socket{ ._address = addr, ._stream = stream };\n    }\n};\n\n\n\n7.4.2 Listening and receiving connections\nRemember that we stored the Socket struct declaration that we built at Section 7.4.1 inside a Zig module named config.zig. This is why I imported this module into our main module (main.zig) in the example below, as the SocketConf object, to access the Socket struct.\nOnce we created our socket object, we can focus now on making this socket object listen and receive new incoming connections. We do that, by calling the listen() method from the Address object that is contained inside the socket object, and then, we call the accept() method over the result.\nThe listen() method from the Address object produces a server object, which is an object that will stay open and running indefinitely, waiting to receive an incoming connection. Therefore, if you try to run the code example below, by calling the run command from the zig compiler, you will notice that the programs keeps running indefinitely, without a clear end.\nThis happens, because the program is waiting for something to happen. It is waiting for someone to try to connect to the address (http://127.0.0.1:3490) where the server is running and listening for incoming connections. This is what the listen() method do, it makes the socket to be active waiting for someone to connect.\nOn the other side, the accept() method is the function that establishes the connection when someone tries to connect to the socket. This means that, the accept() method returns a new connection object as a result. And you can use this connection object to read or write messages from or to the client. For now, we are not doing anything with this connection object. But we are going to use it on the next section.\n\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n    _ = connection;\n}\n\nThis code example allows one single connection. In other words, the server will wait for one incoming connection, and as soon as the server is done with this first connection that it establishes, the program ends, and the server stops.\nThis is not the norm on the real world. Most people that write a HTTP server like this, usually put the accept() method inside a while (infinite) loop, where if a connection is created with accept(), a new thread of execution is created to deal with this new connection and the client. That is, real-world examples of HTTP Servers normally rely on parallel computing to work.\nWith this design, the server simply accepts the connection, and the whole process of dealing with the client, and receiving the HTTP Request, and sending the HTTP Response, all of this is done in the background, on a separate execution thread.\nSo, as soon as the server accepts the connection, and creates the separate thread, the server goes back to what he was doing earlier, which is to wait indefinitely for a new connection to accept. Having this in mind, the code example exposed above, is a server that serves only a single client. Because the program terminates as soon as the connection is accepted.\n\n\n7.4.3 Reading the message from the client\nNow that we have a connection established, i.e. the connection object that we created through the accept() function, we can now use this connection object to read any messages that the client send to our server. But we can also use it to send messages back to the client.\nThe basic idea is, if we write any data into this connection object, then, we are sending data to the client, and if we read the data present in this connection object, then, we are reading any data that the client sent to us, through this connection object. So, just have this logic in mind. “Read” is for reading messages from the client, and “write” is to send a message to the client.\nRemember from Section 7.2 that, the first thing that we need to do is to read the HTTP Request sent by the client to our server. Because it is the first message that happens inside the established connection, and, as a consequence, it is the first thing that we need to deal with.\nThat is why, I’m going to create a new Zig module in this small project, named request.zig to keep all functions related to the HTTP Request together. Then, I will create a new function named read_request() that will use our connection object to read the message sent by the client, which is the HTTP Request.\n\nconst std = @import(\"std\");\nconst Connection = std.net.Server.Connection;\npub fn read_request(conn: Connection,\n                    buffer: []u8) !void {\n    const reader = conn.stream.reader();\n    _ = try reader.read(buffer);\n}\n\nThis function accepts a slice object which behaves as a buffer. The read_request() function reads the message sent into the connection object, and saves this message into this buffer object that we have provided as input.\nNotice that I’m using the connection object that we created to read the message from the client. I first access the reader object that lives inside the connection object. Then, I call the read() method of this reader object to effectively read and save the data sent by the client into the buffer object that we created earlier. I’m discarding the return value of the read() method, by assigning it to the underscore character (_), because this return value is not useful for us right now.",
+    "text": "7.4 Implementing the server - Part 1\n\n7.4.1 Creating the socket object\nLet’s begin with creating the socket object for our server. Just to make things shorter, I will create this socket object in a separate Zig module. I will name it config.zig.\nIn Zig, we can create a web socket using the std.posix.socket() function, from the Zig Standard Library. As I mentioned earlier in Section 7.3, every socket object that we create represents a communication channel, and we need to bind this channel to a specific address. An “address” is defined as an IP address, or, more specifically, an IPv4 address2. Every IPv4 address is composed by two components. The first component is the host, which is a sequence of 4 numbers separated by dot characters (.) that identifies the machine used. While the second component is a port number, which identifies the specific door, or, the specific port to use in the host machine.\nThe sequence of 4 numbers (i.e., the host) identifies the machine (i.e., the computer itself) where this socket will live in. Every computer normally have multiple “doors” available inside of him, because this allows the computer to receive and work with multiple connections at the same time. He simply use a single door for each connection. So the port number, is essentially a number that identifies the specific door in the computer that will be responsible for receiving the connection. That is, it identifies the “door” in the computer that the socket will use to receive incoming connections.\nTo make things simpler, I will use an IP address that identifies our current machine in this example. This means that, our socket object will reside on the same computer that we are currently using (this is also known as the “localhost”) to write this Zig source code.\nBy convention, the IP address that identifies the “localhost”, which is the current machine we are using, is the IP 127.0.0.1. So, that is the IP address we are going to use in our server. I can declare it in Zig by using an array of 4 integers, like this:\n\nconst localhost = [4]u8{ 127, 0, 0, 1 };\n_ = localhost;\n\nNow, we need to decide which port number to use. By convention, there are some port numbers that are reserved, meaning that, we cannot use them for our own purposes, like the port 22 (which is normally used for SSH connections). For TCP connections, which is our case here, a port number is a 16-bit unsigned integer (type u16 in Zig), thus ranging from 0 to 65535 (Wikipedia 2024). So, we can choose a number from 0 to 65535 for our port number. In the example of this book, I will use the port number 3490 (just a random number).\nNow that we have these two informations at hand, I can finally create our socket object, using the std.posix.socket() function. First, we use the host and the port number to create an Address object, with the std.net.Address.initIp4() function, like in the example below. After that, I use this address object inside the socket() function to create our socket object.\nThe Socket struct defined below summarizes all the logic behind this process. In this struct, we have two data members, which are: 1) the address object; 2) and a stream object, which is the object we will use to read and write the messages into any connection we establish.\nNotice that, inside the constructor method of this struct, when we create the socket object, we are using the IPROTO.TCP property as an input to tell the function to create a socket for TCP connections.\n\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\nconst net = @import(\"std\").net;\n\npub const Socket = struct {\n    _address: std.net.Address,\n    _stream: std.net.Stream,\n\n    pub fn init() !Socket {\n        const host = [4]u8{ 127, 0, 0, 1 };\n        const port = 3490;\n        const addr = net.Address.initIp4(host, port);\n        const socket = try std.posix.socket(\n            addr.any.family,\n            std.posix.SOCK.STREAM,\n            std.posix.IPPROTO.TCP\n        );\n        const stream = net.Stream{ .handle = socket };\n        return Socket{ ._address = addr, ._stream = stream };\n    }\n};\n\n\n\n7.4.2 Listening and receiving connections\nRemember that we stored the Socket struct declaration that we built in Section 7.4.1 inside a Zig module named config.zig. This is why I imported this module into our main module (main.zig) in the example below, as the SocketConf object, to access the Socket struct.\nOnce we created our socket object, we can focus now on making this socket object listen and receive new incoming connections. We do that, by calling the listen() method from the Address object that is contained inside the socket object, and then, we call the accept() method over the result.\nThe listen() method from the Address object produces a server object, which is an object that will stay open and running indefinitely, waiting to receive an incoming connection. Therefore, if you try to run the code example below, by calling the run command from the zig compiler, you will notice that the programs keeps running indefinitely, without a clear end.\nThis happens, because the program is waiting for something to happen. It’s waiting for someone to try to connect to the address (http://127.0.0.1:3490) where the server is running and listening for incoming connections. This is what the listen() method do, it makes the socket to be active waiting for someone to connect.\nOn the other side, the accept() method is the function that establishes the connection when someone tries to connect to the socket. This means that, the accept() method returns a new connection object as a result. And you can use this connection object to read or write messages from or to the client. For now, we are not doing anything with this connection object. But we are going to use it in the next section.\n\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n    _ = connection;\n}\n\nThis code example allows one single connection. In other words, the server will wait for one incoming connection, and as soon as the server is done with this first connection that it establishes, the program ends, and the server stops.\nThis is not the norm in the real world. Most people that write a HTTP server like this, usually put the accept() method inside a while (infinite) loop, where if a connection is created with accept(), a new thread of execution is created to deal with this new connection and the client. That is, real-world examples of HTTP Servers normally rely on parallel computing to work.\nWith this design, the server simply accepts the connection, and the whole process of dealing with the client, and receiving the HTTP Request, and sending the HTTP Response, all of this is done in the background, on a separate execution thread.\nSo, as soon as the server accepts the connection, and creates the separate thread, the server goes back to what he was doing earlier, which is to wait indefinitely for a new connection to accept. Having this in mind, the code example exposed above, is a server that serves only a single client. Because the program terminates as soon as the connection is accepted.\n\n\n7.4.3 Reading the message from the client\nNow that we have a connection established, i.e., the connection object that we created through the accept() function, we can now use this connection object to read any messages that the client send to our server. But we can also use it to send messages back to the client.\nThe basic idea is, if we write any data into this connection object, then, we are sending data to the client, and if we read the data present in this connection object, then, we are reading any data that the client sent to us, through this connection object. So, just have this logic in mind. “Read” is for reading messages from the client, and “write” is to send a message to the client.\nRemember from Section 7.2 that, the first thing that we need to do is to read the HTTP Request sent by the client to our server. Because it is the first message that happens inside the established connection, and, as a consequence, it is the first thing that we need to deal with.\nThat is why, I’m going to create a new Zig module in this small project, named request.zig to keep all functions related to the HTTP Request together. Then, I will create a new function named read_request() that will use our connection object to read the message sent by the client, which is the HTTP Request.\n\nconst std = @import(\"std\");\nconst Connection = std.net.Server.Connection;\npub fn read_request(conn: Connection,\n                    buffer: []u8) !void {\n    const reader = conn.stream.reader();\n    _ = try reader.read(buffer);\n}\n\nThis function accepts a slice object which behaves as a buffer. The read_request() function reads the message sent into the connection object, and saves this message into this buffer object that we have provided as input.\nNotice that I’m using the connection object that we created to read the message from the client. I first access the reader object that lives inside the connection object. Then, I call the read() method of this reader object to effectively read and save the data sent by the client into the buffer object that we created earlier. I’m discarding the return value of the read() method, by assigning it to the underscore character (_), because this return value is not useful for us right now.",
     "crumbs": [
       "<span class='chapter-number'>7</span>  <span class='chapter-title'>Project 2 - Building a HTTP Server from scratch</span>"
     ]
@@ -584,7 +584,7 @@
     "href": "Chapters/04-http-server.html#looking-at-the-current-state-of-the-program",
     "title": "7  Project 2 - Building a HTTP Server from scratch",
     "section": "7.5 Looking at the current state of the program",
-    "text": "7.5 Looking at the current state of the program\nI think now is a good time to see how our program is currently working. Shall we? So, the first thing I will do is to update the main.zig module in our small Zig project, so that the main() function call this new read_request() function that we have just created. I will also add a print statement at the end of the main() function, just so that you can see what the HTTP Request that we have just loaded into the buffer object looks like.\nAlso, I’m creating the buffer object in the main() function, which will be responsible for storing the message sent by the client, and, I’m also using a for loop to initialize all fields of this buffer object to the number zero. This is important to make sure that we don’t have uninitialized memory in this object. Because uninitialized memory may cause undefined behaviour in our program.\nSince the read_request() function should receive as input the buffer object as a slice object ([]u8), I am using the syntax array[0..array.len] to get access to a slice of this buffer object.\n\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    _ = try Request.read_request(\n        connection, buffer[0..buffer.len]\n    );\n    try stdout.print(\"{s}\\n\", .{buffer});\n}\n\nNow, I’m going to execute this program, with the run command from the zig compiler. But remember, as we sad earlier, as soon as I execute this program, it will hang indefinitely, because the program is waiting for a client trying to connect to the server.\nMore specifically, the program will pause at the line with the accept() call. As soon as a client try to connect to the server, then, the execution will “unpause”, and the accept() function will finally be executed to create the connection object that we need, and the remaining of the program will run.\nYou can see that at Figure 7.1. The message Server Addr: 127.0.0.1:3490 is printed to the console, and the program is now waiting for an incoming connection.\n\n\n\n\n\n\nFigure 7.1: A screenshot of running the program\n\n\n\nWe can finally try to connect to this server, and there are several ways we can do this. For example, we could use the following Python script:\nimport requests\nrequests.get(\"http://127.0.0.1:3490\")\nOr, we could also open any web browser of our preference, and type the URL localhost:3490. OBS: localhost is the same thing as the IP 127.0.0.1. When you press enter, and your web browser go to this address, first, the browser will probably print a message saying that “this page isn’t working”, and, then, it will probably change to a new message saying that “the site can’t be reached”.\nYou get these “error messages” in the web browser, because it got no response back from the server. In other words, when the web browser connected to our server, it did send the HTTP Request through the established connection. Then, the web browser was expecting to receive a HTTP Response back, but it got no response from the server (we didn’t implemented the HTTP Response logic yet).\nBut that is okay. We have achieved the result that we wanted for now, which is to connect to the server, and see the HTTP Request that was sent by the web browser (or by the Python script) to the server.\nIf you comeback to the console that you left open when you have executed the program, you will see that the program finished its execution, and, a new message is printed in the console, which is the actual HTTP Request message that was sent by the web browser to the server. You can see this message at Figure 7.2.\n\n\n\n\n\n\nFigure 7.2: A screenshot of the HTTP Request sent by the web browser",
+    "text": "7.5 Looking at the current state of the program\nI think now is a good time to see how our program is currently working. Shall we? So, the first thing I will do is to update the main.zig module in our small Zig project, so that the main() function call this new read_request() function that we have just created. I will also add a print statement at the end of the main() function, just so that you can see what the HTTP Request that we have just loaded into the buffer object looks like.\nAlso, I’m creating the buffer object in the main() function, which will be responsible for storing the message sent by the client, and, I’m also using a for loop to initialize all fields of this buffer object to the number zero. This is important to make sure that we don’t have uninitialized memory in this object. Because uninitialized memory may cause undefined behaviour in our program.\nSince the read_request() function should receive as input the buffer object as a slice object ([]u8), I am using the syntax array[0..array.len] to get access to a slice of this buffer object.\n\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    _ = try Request.read_request(\n        connection, buffer[0..buffer.len]\n    );\n    try stdout.print(\"{s}\\n\", .{buffer});\n}\n\nNow, I’m going to execute this program, with the run command from the zig compiler. But remember, as we sad earlier, as soon as I execute this program, it will hang indefinitely, because the program is waiting for a client trying to connect to the server.\nMore specifically, the program will pause at the line with the accept() call. As soon as a client try to connect to the server, then, the execution will “unpause”, and the accept() function will finally be executed to create the connection object that we need, and the remaining of the program will run.\nYou can see that in Figure 7.1. The message Server Addr: 127.0.0.1:3490 is printed to the console, and the program is now waiting for an incoming connection.\n\n\n\n\n\n\nFigure 7.1: A screenshot of running the program\n\n\n\nWe can finally try to connect to this server, and there are several ways we can do this. For example, we could use the following Python script:\nimport requests\nrequests.get(\"http://127.0.0.1:3490\")\nOr, we could also open any web browser of our preference, and type the URL localhost:3490. OBS: localhost is the same thing as the IP 127.0.0.1. When you press enter, and your web browser go to this address, first, the browser will probably print a message saying that “this page isn’t working”, and, then, it will probably change to a new message saying that “the site can’t be reached”.\nYou get these “error messages” in the web browser, because it got no response back from the server. In other words, when the web browser connected to our server, it did send the HTTP Request through the established connection. Then, the web browser was expecting to receive a HTTP Response back, but it got no response from the server (we didn’t implemented the HTTP Response logic yet).\nBut that is okay. We have achieved the result that we wanted for now, which is to connect to the server, and see the HTTP Request that was sent by the web browser (or by the Python script) to the server.\nIf you comeback to the console that you left open when you have executed the program, you will see that the program finished its execution, and, a new message is printed in the console, which is the actual HTTP Request message that was sent by the web browser to the server. You can see this message in Figure 7.2.\n\n\n\n\n\n\nFigure 7.2: A screenshot of the HTTP Request sent by the web browser",
     "crumbs": [
       "<span class='chapter-number'>7</span>  <span class='chapter-title'>Project 2 - Building a HTTP Server from scratch</span>"
     ]
@@ -594,7 +594,7 @@
     "href": "Chapters/04-http-server.html#sec-enum",
     "title": "7  Project 2 - Building a HTTP Server from scratch",
     "section": "7.6 Learning about Enums in Zig",
-    "text": "7.6 Learning about Enums in Zig\nEnums structures are available in Zig through the enum keyword. An enum (short for “enumeration”) is a special structure that represents a group of constant values. So, if you have a variable which can assume a short and known set of values, you might want to associate this variable to an enum structure, to make sure that this variable only assumes a value from this set.\nA classic example for enums are primary colors. If for some reason, your program needs to represent one of the primary colors, you can create an enum that represents one of these colors. In the example below, we are creating the enum PrimaryColorRGB, which represents a primary color from the RGB color system. By using this enum, I am guaranteed that the acolor object for example, will contain one of these three values: RED, GREEN or BLUE.\n\nconst PrimaryColorRGB = enum {\n    RED, GREEN, BLUE\n};\nconst acolor = PrimaryColorRGB.RED;\n_ = acolor;\n\nIf for some reason, my code tries to save in acolor, a value that is not in this set, I will get an error message warning me that a value such as “MAGENTA” do not exist inside the PrimaryColorRGB enum. Then I can easily fix my mistake.\n\nconst acolor = PrimaryColorRGB.MAGENTA;\n\ne1.zig:5:36: error: enum 'PrimaryColorRGB' has\n        no member named 'MAGENTA':\n    const acolor = PrimaryColorRGB.MAGENTA;\n                                   ^~~~~~~\nBehind the hood, enums in Zig work the same way that enums work in C. Each enum value is essentially represented as an integer. The first value in the set is represented as zero, then, the second value is one, … etc.\nOne thing that we are going to learn on the next section is that enums can have methods in them. Wait… What? This is amazing! Yes, enums in Zig are similar to structs, and they can have private and public methods inside them.",
+    "text": "7.6 Learning about Enums in Zig\nEnums structures are available in Zig through the enum keyword. An enum (short for “enumeration”) is a special structure that represents a group of constant values. So, if you have a variable which can assume a short and known set of values, you might want to associate this variable to an enum structure, to make sure that this variable only assumes a value from this set.\nA classic example for enums are primary colors. If for some reason, your program needs to represent one of the primary colors, you can create an enum that represents one of these colors. In the example below, we are creating the enum PrimaryColorRGB, which represents a primary color from the RGB color system. By using this enum, I am guaranteed that the acolor object for example, will contain one of these three values: RED, GREEN or BLUE.\n\nconst PrimaryColorRGB = enum {\n    RED, GREEN, BLUE\n};\nconst acolor = PrimaryColorRGB.RED;\n_ = acolor;\n\nIf for some reason, my code tries to save in acolor, a value that is not in this set, I will get an error message warning me that a value such as “MAGENTA” do not exist inside the PrimaryColorRGB enum. Then I can easily fix my mistake.\n\nconst acolor = PrimaryColorRGB.MAGENTA;\n\ne1.zig:5:36: error: enum 'PrimaryColorRGB' has\n        no member named 'MAGENTA':\n    const acolor = PrimaryColorRGB.MAGENTA;\n                                   ^~~~~~~\nBehind the hood, enums in Zig work the same way that enums work in C. Each enum value is essentially represented as an integer. The first value in the set is represented as zero, then, the second value is one, … etc.\nOne thing that we are going to learn in the next section is that enums can have methods in them. Wait… What? This is amazing! Yes, enums in Zig are similar to structs, and they can have private and public methods inside them.",
     "crumbs": [
       "<span class='chapter-number'>7</span>  <span class='chapter-title'>Project 2 - Building a HTTP Server from scratch</span>"
     ]
@@ -604,7 +604,7 @@
     "href": "Chapters/04-http-server.html#implementing-the-server---part-2",
     "title": "7  Project 2 - Building a HTTP Server from scratch",
     "section": "7.7 Implementing the server - Part 2",
-    "text": "7.7 Implementing the server - Part 2\nNow, on this section, I want to focus on parsing the HTTP Request that we received from the client. However, to effectively parse a HTTP Request message, we first need to understand its structure. In summary, a HTTP Request is a text message that is divided into 3 different sections (or parts):\n\nThe top-level header indicating the method of the HTTP Request, the URI, and the HTTP version used in the message.\nA list of HTTP Headers.\nThe body of the HTTP Request.\n\n\n7.7.1 The top-level header\nThe first line of text in a HTTP Request always come with the three most essential information about the request. These three key attributes of the HTTP Request are separated by a simple space in this first line of the request. The first information is the HTTP method that is being used in the request, second, we have the URI to which this HTTP Request is being sent to, and third, we have the version of the HTTP protocol that is being used in this HTTP Request.\nIn the snippet below, you can find an example of this first line in a HTTP Request. First, we have the HTTP method of this request (GET). Many programmers refer to the URI component (/users/list) as the “API endpoint” to which the HTTP Request is being sent to. In the context of this specific request, since it is a GET request, you could also say that the URI component is the path to the resource we want to access, or, the path to the document (or the file) that we want to retrieve from the server.\nGET /users/list HTTP/1.1\nAlso, notice that this HTTP Request is using the version 1.1 of the HTTP protocol, which is the most popular version of the protocol used in the web.\n\n\n7.7.2 The list of HTTP headers\nMost HTTP Requests also include a section of HTTP Headers, which is just a list of attributes or key-value pairs associated with this particular request. This section always comes right after the “top-level header” of the request.\nFor our purpose in this chapter, which is to build a simple HTTP Server, we are going to ignore this section of the HTTP Request, for simplicity. But most HTTP servers that exist in the wild parses and use these HTTP headers to change the way that the server responds to the request sent by the client.\nFor example, many requests we encounter in the real-world comes with a HTTP header called Accept. In this header, we find a list of MIME types3. This list indicates the file formats that the client can read, or parse, or interpret. In other words, you also interpret this header as the client saying the following phrase to the server: “Hey! Look, I can read only HTML documents, so please, send me back a document that is in a HTML format.”.\nIf the HTTP server can read and use this Accept header, then, the server can identify which is the best file format for the document to be sent to the client. Maybe the HTTP server have the same document in multiple formats, for example, in JSON, in XML, in HTML and in PDF, but the client can only understand documents in the HTML format. That is the purpose of this Accept header.\n\n\n7.7.3 The body\nThe body comes after the list of HTTP headers, and it is an optional section of the HTTP Request, meaning that, not all HTTP Request will come with a body in it. For example, every HTTP Request that uses the GET method usually do not come with a body.\nBecause a GET request is used to request data, instead of sending it to the server. So, the body section is more related to the POST method, which is a method that involves sending data to the server, to be processed and stored.\nSince we are going to support only the GET method in this project, it means that we also do not need to care about the body of the request.\n\n\n7.7.4 Creating the HTTP Method enum\nEvery HTTP Request comes with a explicit method. The method used in a HTTP Request is identified by one these words:\n\nGET;\nPOST;\nOPTIONS;\nPATCH;\nDELETE;\nand some other methods.\n\nEach HTTP method is used for a specific type of task. The POST method for example is normally used to post some data into the destination. In other words, it is used to send some data to the HTTP server, so that it can be processed and stored by the server.\nAs another example, the GET method is normally used to get content from the server. In other words, we use this method whenever we want the server to send some content back to us. It can be any type of content. It can be a web page, a document file, or some data in a JSON format.\nWhen a client sends a POST HTTP Request, the HTTP Response sent by the server normally have the sole purpose of letting the client know if the server processed and stored the data successfully. In contrast, when the server receives a GET HTTP Request, then, the server sends the content that the client asked for in the HTTP Response itself. This demonstrates that the method associated with the HTTP Request changes a lot on the dynamics and the roles that each party plays in the whole process.\nSince the HTTP method of the HTTP Request is identified by this very small and specific set of words, it would be interesting to create an enum structure to represent a HTTP method. This way, we can easily check if the HTTP Request we receive from the client is a HTTP method that we currently support in our small HTTP server project.\nThe Method structure below represents this enumeration. Notice that, for now, only the GET HTTP method is included in this enumeration. Because, for the purpose of this chapter, I want to implement only the GET HTTP method. That is why I am not including the other HTTP methods in this enumeration.\n\npub const Method = enum {\n    GET\n};\n\nNow, I think we should add two methods to this enum structure. One method is is_supported(), which will be a function that returns a boolean value, indicating if the input HTTP method is supported or not by our HTTP Server. The other is init(), which is a constructor function that takes a string as input, and tries to convert it into a Method value.\nBut in order to build these functions, I will use a functionality from the Zig Standard Library, called StaticStringMap(). This function allows us to create a simple map from strings to enum values. In other words, we can use this map structure to map a string to the respective enum value. To some extent, this specific structure from the standard library works almost like a “hashtable” structure, and it is optimized for small sets of words, or, small sets of keys, which is our case here. We are going to talk more about hashtables in Zig at Section 11.2.\nTo use this “static string map” structure, you have to import it from the std.static_string_map module of the Zig Standard Library. Just to make things shorter and easier to type, I am going to import this function through a different and shorter name (Map).\nWith Map() imported, we can just apply this function over the enum structure that we are going to use in the resulting map. In our case here, it is the Method enum structure that we declared at the last code example. Then, I call the initComptime() method with the map, i.e. the list of key-value pairs that we are going to use.\nYou can see in the example below that I wrote this map using multiple anonymous struct literals. Inside the first (or “top-level”) struct literal, we have a list (or a sequence) of struct literals. Each struct literal in this list represents a separate key-value pair. The first element (or the key) in each key-value pair should always be a string value. While the second element should be a value from the enum structure that you have used inside the Map() function.\n\nconst Map = std.static_string_map.StaticStringMap;\nconst MethodMap = Map(Method).initComptime(.{\n    .{ \"GET\", Method.GET },\n});\n\nTherefore, the MethodMap object is basically a std::map object from C++, or, a dict object from Python. You can retrieve (or get) the enum value that corresponds to a particular key, by using the get() method from the map object. This method returns an optional value, so, the get() method might result in a null value.\nWe can use this in our advantage to detect if a particular HTTP method is supported or not in our HTTP server. Because, if the get() method returns null, it means that it did not found the method that we provided inside the MethodMap object, and, as a consequence, this method is not supported by our HTTP server.\nThe init() method below, takes a string value as input, and then, it simply passes this string value to the get() method of our MethodMap object. As consequence, we should get the enum value that corresponds to this input string.\nNotice in the example below that, the init() method returns either an error (which might happen if the ? method returns unreacheable, checkout Section 6.4.3 for more details) or a Method object as result. Since GET is currently the only value in our Method enum structure, it means that, the init() method will most likely return the value Method.GET as result.\nAlso notice that, in the is_supported() method, we are using the optional value returned by the get() method from our MethodMap object. The if statement unwraps the optional value returned by this method, and returns true in case this optional value is a not-null value. Otherwise, it simply returns false.\n\npub const Method = enum {\n    GET,\n    pub fn init(text: []const u8) !Method {\n        return MethodMap.get(text).?;\n    }\n    pub fn is_supported(m: []const u8) bool {\n        const method = MethodMap.get(m);\n        if (method) |_| {\n            return true;\n        }\n        return false;\n    }\n};\n\n\n\n7.7.5 Writing the parse request function\nNow that we created the enum that represents our HTTP method, we should start to write the function responsible for actually parsing the HTTP Request.\nThe first thing we can do, is to write a struct to represent the HTTP Request. Take the Request struct below as an example. It contains the three essential information from the “top-level” header (i.e. the first line) in the HTTP Request.\n\nconst Request = struct {\n    method: Method,\n    version: []const u8,\n    uri: []const u8,\n    pub fn init(method: Method,\n                uri: []const u8,\n                version: []const u8) Request {\n        return Request{\n            .method = method,\n            .uri = uri,\n            .version = version,\n        };\n    }\n};\n\nThe parse_request() function should receive a string as input. This input string contains the entire HTTP Request message, and the parsing function should read and understand the individual parts of this message.\nNow, remember that for the purpose of this chapter, we care only about the first line in this message, which contains the “top-level header”, or, the three essential attributes about the HTTP Request, which are the HTTP method used, the URI and the HTTP version.\nNotice that I use the function indexOfScalar() in parse_request(). This function from the Zig Standard Library returns the first index where the scalar value that we provide happens in a string. In this case, I’m looking at the first occurrence of the new line character (\\n). Because once again, we care only about the first line in the HTTP Request message. This is the line where we have the three information that we want to parse (version of HTTP, the HTTP method and the URI).\nTherefore, we are using this indexOfScalar() function to limit our parsing process to the first line in the message. Is also worth mentioning that, the indexOfScalar() function returns an optional value. That is why I use the orelse keyword to provide an alternative value, in case the value returned by the function is a null value.\nSince each of these three attributes are separated by a simple space, we could use the function splitScalar() from the Zig Standard Library to split the input string into sections by looking for every position that appears a simple space. In other words, this splitScalar() function is equivalent to the split() method in Python, or, the std::getline() function from C++, or the strtok() function in C.\nWhen you use this splitScalar() function, you get an iterator as the result. This iterator have a next() method that you can use to advance the iterator to the next position, or, to the next section of the splitted string. Note that, when you use next(), the method not only advances the iterator, but it also returns a slice to the current section of the splitted string as result.\nNow, if you want to get a slice to the current section of the splitted string, but not advance the iterator to the next position, you can use the peek() method. Both next() and peek() methods return an optional value, that is why I use the ? method to unwrap these optional values.\n\npub fn parse_request(text: []u8) Request {\n    const line_index = std.mem.indexOfScalar(\n        u8, text, '\\n'\n    ) orelse text.len;\n    var iterator = std.mem.splitScalar(\n        u8, text[0..line_index], ' '\n    );\n    const method = try Method.init(iterator.next().?);\n    const uri = iterator.next().?;\n    const version = iterator.next().?;\n    const request = Request.init(method, uri, version);\n    return request;\n}\n\nAs I described at Section 1.8, strings in Zig are simply arrays of bytes in the language. So, you will find lots of excellent utility functions to work directly with strings inside this mem module from the Zig Standard Library. We have described some of these useful utility functions already at Section 1.8.4.\n\n\n7.7.6 Using the parse request function\nNow that we wrote the function responsible for parsing the HTTP Request, we can add the function call to parse_request() in the main() function of our program.\nAfter that, is a good idea to test once again the state of our program. I execute this program again with the run command from the zig compiler, then, I use my web browser to connect once again to the server through the URL localhost:3490, and finally, the end result of our Request object is printed to the console.\nA quick observation, since I have used the any format specifier in the print statement, the data members version and uri of the Request struct were printed as raw integer values. String data being printed as integer values is common in Zig, and remember, these integer values are just the decimal representation of the bytes that form the string in question.\nIn the result below, the sequence of decimal values 72, 84, 84, 80, 47, 49, 46, 49, and 13, are the bytes that form the text “HTTP/1.1”. And the integer 47, is the decimal value of the character /, which represents our URI in this request.\n\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    try Request.read_request(\n        connection, buffer[0..buffer.len]\n    );\n    const request = Request.parse_request(\n        buffer[0..buffer.len]\n    );\n    try stdout.print(\"{any}\\n\", .{request});\n}\n\nrequest.Request{\n    .method = request.Method.GET,\n    .version = {72, 84, 84, 80, 47, 49, 46, 49, 13},\n    .uri = {47}\n}\n\n\n7.7.7 Sending the HTTP Response to the client\nIn this last part, we are going to write the logic responsible for sending the HTTP Response from the server to the client. To make things simple, the server in this project will send just a simple web page containing the text “Hello world”.\nFirst, I create a new Zig module in the project, named response.zig. In this module, I will declare just two functions. Each function corresponds to a specific status code in the HTTP Response. The send_200() function will send a HTTP Response with status code 200 (which means “Success”) to the client. While the send_404() function sends a response with status code 404 (which means “Not found”).\nThis is definitely not the most ergonomic and adequate way of handling the HTTP Response, but it works for our case here. We are just building toy projects in this book after all, therefore, the source code that we write do not need to be perfect. It just needs to work!\n\nconst std = @import(\"std\");\nconst Connection = std.net.Server.Connection;\npub fn send_200(conn: Connection) !void {\n    const message = (\n        \"HTTP/1.1 200 OK\\nContent-Length: 48\"\n        ++ \"\\nContent-Type: text/html\\n\"\n        ++ \"Connection: Closed\\n\\n&lt;html&gt;&lt;body&gt;\"\n        ++ \"&lt;h1&gt;Hello, World!&lt;/h1&gt;&lt;/body&gt;&lt;/html&gt;\"\n    );\n    _ = try conn.stream.write(message);\n}\n\npub fn send_404(conn: Connection) !void {\n    const message = (\n        \"HTTP/1.1 404 Not Found\\nContent-Length: 50\"\n        ++ \"\\nContent-Type: text/html\\n\"\n        ++ \"Connection: Closed\\n\\n&lt;html&gt;&lt;body&gt;\"\n        ++ \"&lt;h1&gt;File not found!&lt;/h1&gt;&lt;/body&gt;&lt;/html&gt;\"\n    );\n    _ = try conn.stream.write(message);\n}\n\nNotice that both functions receives the connection object as input, and use the write() method to write the HTTP Response message directly into this communication channel. As result, the party in the other side of the connection (i.e. the client), will receive such message.\nMost real-world HTTP Servers will have a single function (or a single struct) to effectively handle the response. It gets the HTTP Request already parsed as input, and then, it tries to build the HTTP Response bit by bit, before the function sends it over the connection.\nWe would also have a specialized struct to represent a HTTP Response, and a lot of methods that would be used to build each part or component of the response object. Take the Response struct created by the Javascript runtime Bun as an example. You can find this struct in the response.zig module4 in their GitHub project.",
+    "text": "7.7 Implementing the server - Part 2\nNow, on this section, I want to focus on parsing the HTTP Request that we received from the client. However, to effectively parse a HTTP Request message, we first need to understand its structure. In summary, a HTTP Request is a text message that is divided into 3 different sections (or parts):\n\nThe top-level header indicating the method of the HTTP Request, the URI, and the HTTP version used in the message.\nA list of HTTP Headers.\nThe body of the HTTP Request.\n\n\n7.7.1 The top-level header\nThe first line of text in a HTTP Request always come with the three most essential information about the request. These three key attributes of the HTTP Request are separated by a simple space in this first line of the request. The first information is the HTTP method that is being used in the request, second, we have the URI to which this HTTP Request is being sent to, and third, we have the version of the HTTP protocol that is being used in this HTTP Request.\nIn the snippet below, you can find an example of this first line in a HTTP Request. First, we have the HTTP method of this request (GET). Many programmers refer to the URI component (/users/list) as the “API endpoint” to which the HTTP Request is being sent to. In the context of this specific request, since it’s a GET request, you could also say that the URI component is the path to the resource we want to access, or, the path to the document (or the file) that we want to retrieve from the server.\nGET /users/list HTTP/1.1\nAlso, notice that this HTTP Request is using the version 1.1 of the HTTP protocol, which is the most popular version of the protocol used in the web.\n\n\n7.7.2 The list of HTTP headers\nMost HTTP Requests also include a section of HTTP Headers, which is just a list of attributes or key-value pairs associated with this particular request. This section always comes right after the “top-level header” of the request.\nFor our purpose in this chapter, which is to build a simple HTTP Server, we are going to ignore this section of the HTTP Request, for simplicity. But most HTTP servers that exist in the wild parses and use these HTTP headers to change the way that the server responds to the request sent by the client.\nFor example, many requests we encounter in the real-world comes with a HTTP header called Accept. In this header, we find a list of MIME types3. This list indicates the file formats that the client can read, or parse, or interpret. In other words, you also interpret this header as the client saying the following phrase to the server: “Hey! Look, I can read only HTML documents, so please, send me back a document that is in a HTML format.”.\nIf the HTTP server can read and use this Accept header, then, the server can identify which is the best file format for the document to be sent to the client. Maybe the HTTP server have the same document in multiple formats, for example, in JSON, in XML, in HTML and in PDF, but the client can only understand documents in the HTML format. That is the purpose of this Accept header.\n\n\n7.7.3 The body\nThe body comes after the list of HTTP headers, and it’s an optional section of the HTTP Request, meaning that, not all HTTP Requests will come with a body in them. For example, every HTTP Request that uses the GET method usually does not come with a body.\nBecause a GET request is used to request data, instead of sending it to the server. So, the body section is more related to the POST method, which is a method that involves sending data to the server, to be processed and stored.\nSince we are going to support only the GET method in this project, it means that we also do not need to care about the body of the request.\n\n\n7.7.4 Creating the HTTP Method enum\nEvery HTTP Request comes with a explicit method. The method used in a HTTP Request is identified by one these words:\n\nGET;\nPOST;\nOPTIONS;\nPATCH;\nDELETE;\nand some other methods.\n\nEach HTTP method is used for a specific type of task. The POST method for example is normally used to post some data into the destination. In other words, it’s used to send some data to the HTTP server, so that it can be processed and stored by the server.\nAs another example, the GET method is normally used to get content from the server. In other words, we use this method whenever we want the server to send some content back to us. It can be any type of content. It can be a web page, a document file, or some data in a JSON format.\nWhen a client sends a POST HTTP Request, the HTTP Response sent by the server normally have the sole purpose of letting the client know if the server processed and stored the data successfully. In contrast, when the server receives a GET HTTP Request, then, the server sends the content that the client asked for in the HTTP Response itself. This demonstrates that the method associated with the HTTP Request changes a lot on the dynamics and the roles that each party plays in the whole process.\nSince the HTTP method of the HTTP Request is identified by this very small and specific set of words, it would be interesting to create an enum structure to represent a HTTP method. This way, we can easily check if the HTTP Request we receive from the client is a HTTP method that we currently support in our small HTTP server project.\nThe Method structure below represents this enumeration. Notice that, for now, only the GET HTTP method is included in this enumeration. Because, for the purpose of this chapter, I want to implement only the GET HTTP method. That is why I am not including the other HTTP methods in this enumeration.\n\npub const Method = enum {\n    GET\n};\n\nNow, I think we should add two methods to this enum structure. One method is is_supported(), which will be a function that returns a boolean value, indicating if the input HTTP method is supported or not by our HTTP Server. The other is init(), which is a constructor function that takes a string as input, and tries to convert it into a Method value.\nBut in order to build these functions, I will use a functionality from the Zig Standard Library, called StaticStringMap(). This function allows us to create a simple map from strings to enum values. In other words, we can use this map structure to map a string to the respective enum value. To some extent, this specific structure from the standard library works almost like a “hashtable” structure, and it’s optimized for small sets of words, or, small sets of keys, which is our case here. We are going to talk more about hashtables in Zig in Section 11.2.\nTo use this “static string map” structure, you have to import it from the std.static_string_map module of the Zig Standard Library. Just to make things shorter and easier to type, I am going to import this function through a different and shorter name (Map).\nWith Map() imported, we can just apply this function over the enum structure that we are going to use in the resulting map. In our case here, it’s the Method enum structure that we declared at the last code example. Then, I call the initComptime() method with the map, i.e., the list of key-value pairs that we are going to use.\nYou can see in the example below that I wrote this map using multiple anonymous struct literals. Inside the first (or “top-level”) struct literal, we have a list (or a sequence) of struct literals. Each struct literal in this list represents a separate key-value pair. The first element (or the key) in each key-value pair should always be a string value. While the second element should be a value from the enum structure that you have used inside the Map() function.\n\nconst Map = std.static_string_map.StaticStringMap;\nconst MethodMap = Map(Method).initComptime(.{\n    .{ \"GET\", Method.GET },\n});\n\nTherefore, the MethodMap object is basically a std::map object from C++, or, a dict object from Python. You can retrieve (or get) the enum value that corresponds to a particular key, by using the get() method from the map object. This method returns an optional value, so, the get() method might result in a null value.\nWe can use this in our advantage to detect if a particular HTTP method is supported or not in our HTTP server. Because, if the get() method returns null, it means that it did not found the method that we provided inside the MethodMap object, and, as a consequence, this method is not supported by our HTTP server.\nThe init() method below, takes a string value as input, and then, it simply passes this string value to the get() method of our MethodMap object. As consequence, we should get the enum value that corresponds to this input string.\nNotice in the example below that, the init() method returns either an error (which might happen if the ? method returns unreacheable, checkout Section 6.4.3 for more details) or a Method object as result. Since GET is currently the only value in our Method enum structure, it means that, the init() method will most likely return the value Method.GET as result.\nAlso notice that, in the is_supported() method, we are using the optional value returned by the get() method from our MethodMap object. The if statement unwraps the optional value returned by this method, and returns true in case this optional value is a not-null value. Otherwise, it simply returns false.\n\npub const Method = enum {\n    GET,\n    pub fn init(text: []const u8) !Method {\n        return MethodMap.get(text).?;\n    }\n    pub fn is_supported(m: []const u8) bool {\n        const method = MethodMap.get(m);\n        if (method) |_| {\n            return true;\n        }\n        return false;\n    }\n};\n\n\n\n7.7.5 Writing the parse request function\nNow that we created the enum that represents our HTTP method, we should start to write the function responsible for actually parsing the HTTP Request.\nThe first thing we can do, is to write a struct to represent the HTTP Request. Take the Request struct below as an example. It contains the three essential information from the “top-level” header (i.e., the first line) in the HTTP Request.\n\nconst Request = struct {\n    method: Method,\n    version: []const u8,\n    uri: []const u8,\n    pub fn init(method: Method,\n                uri: []const u8,\n                version: []const u8) Request {\n        return Request{\n            .method = method,\n            .uri = uri,\n            .version = version,\n        };\n    }\n};\n\nThe parse_request() function should receive a string as input. This input string contains the entire HTTP Request message, and the parsing function should read and understand the individual parts of this message.\nNow, remember that for the purpose of this chapter, we care only about the first line in this message, which contains the “top-level header”, or, the three essential attributes about the HTTP Request, which are the HTTP method used, the URI and the HTTP version.\nNotice that I use the function indexOfScalar() in parse_request(). This function from the Zig Standard Library returns the first index where the scalar value that we provide happens in a string. In this case, I’m looking at the first occurrence of the new line character (\\n). Because once again, we care only about the first line in the HTTP Request message. This is the line where we have the three information that we want to parse (version of HTTP, the HTTP method and the URI).\nTherefore, we are using this indexOfScalar() function to limit our parsing process to the first line in the message. It’s also worth mentioning that, the indexOfScalar() function returns an optional value. That is why I use the orelse keyword to provide an alternative value, in case the value returned by the function is a null value.\nSince each of these three attributes are separated by a simple space, we could use the function splitScalar() from the Zig Standard Library to split the input string into sections by looking for every position that appears a simple space. In other words, this splitScalar() function is equivalent to the split() method in Python, or, the std::getline() function from C++, or the strtok() function in C.\nWhen you use this splitScalar() function, you get an iterator as the result. This iterator have a next() method that you can use to advance the iterator to the next position, or, to the next section of the splitted string. Note that, when you use next(), the method not only advances the iterator, but it also returns a slice to the current section of the splitted string as result.\nNow, if you want to get a slice to the current section of the splitted string, but not advance the iterator to the next position, you can use the peek() method. Both next() and peek() methods return an optional value, that is why I use the ? method to unwrap these optional values.\n\npub fn parse_request(text: []u8) Request {\n    const line_index = std.mem.indexOfScalar(\n        u8, text, '\\n'\n    ) orelse text.len;\n    var iterator = std.mem.splitScalar(\n        u8, text[0..line_index], ' '\n    );\n    const method = try Method.init(iterator.next().?);\n    const uri = iterator.next().?;\n    const version = iterator.next().?;\n    const request = Request.init(method, uri, version);\n    return request;\n}\n\nAs I described in Section 1.8, strings in Zig are simply arrays of bytes in the language. So, you will find lots of excellent utility functions to work directly with strings inside this mem module from the Zig Standard Library. We have described some of these useful utility functions already in Section 1.8.4.\n\n\n7.7.6 Using the parse request function\nNow that we wrote the function responsible for parsing the HTTP Request, we can add the function call to parse_request() in the main() function of our program.\nAfter that, is a good idea to test once again the state of our program. I execute this program again with the run command from the zig compiler, then, I use my web browser to connect once again to the server through the URL localhost:3490, and finally, the end result of our Request object is printed to the console.\nA quick observation, since I have used the any format specifier in the print statement, the data members version and uri of the Request struct were printed as raw integer values. String data being printed as integer values is common in Zig, and remember, these integer values are just the decimal representation of the bytes that form the string in question.\nIn the result below, the sequence of decimal values 72, 84, 84, 80, 47, 49, 46, 49, and 13, are the bytes that form the text “HTTP/1.1”. And the integer 47, is the decimal value of the character /, which represents our URI in this request.\n\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    try Request.read_request(\n        connection, buffer[0..buffer.len]\n    );\n    const request = Request.parse_request(\n        buffer[0..buffer.len]\n    );\n    try stdout.print(\"{any}\\n\", .{request});\n}\n\nrequest.Request{\n    .method = request.Method.GET,\n    .version = {72, 84, 84, 80, 47, 49, 46, 49, 13},\n    .uri = {47}\n}\n\n\n7.7.7 Sending the HTTP Response to the client\nIn this last part, we are going to write the logic responsible for sending the HTTP Response from the server to the client. To make things simple, the server in this project will send just a simple web page containing the text “Hello world”.\nFirst, I create a new Zig module in the project, named response.zig. In this module, I will declare just two functions. Each function corresponds to a specific status code in the HTTP Response. The send_200() function will send a HTTP Response with status code 200 (which means “Success”) to the client. While the send_404() function sends a response with status code 404 (which means “Not found”).\nThis is definitely not the most ergonomic and adequate way of handling the HTTP Response, but it works for our case here. We are just building toy projects in this book after all, therefore, the source code that we write do not need to be perfect. It just needs to work!\n\nconst std = @import(\"std\");\nconst Connection = std.net.Server.Connection;\npub fn send_200(conn: Connection) !void {\n    const message = (\n        \"HTTP/1.1 200 OK\\nContent-Length: 48\"\n        ++ \"\\nContent-Type: text/html\\n\"\n        ++ \"Connection: Closed\\n\\n&lt;html&gt;&lt;body&gt;\"\n        ++ \"&lt;h1&gt;Hello, World!&lt;/h1&gt;&lt;/body&gt;&lt;/html&gt;\"\n    );\n    _ = try conn.stream.write(message);\n}\n\npub fn send_404(conn: Connection) !void {\n    const message = (\n        \"HTTP/1.1 404 Not Found\\nContent-Length: 50\"\n        ++ \"\\nContent-Type: text/html\\n\"\n        ++ \"Connection: Closed\\n\\n&lt;html&gt;&lt;body&gt;\"\n        ++ \"&lt;h1&gt;File not found!&lt;/h1&gt;&lt;/body&gt;&lt;/html&gt;\"\n    );\n    _ = try conn.stream.write(message);\n}\n\nNotice that both functions receives the connection object as input, and use the write() method to write the HTTP Response message directly into this communication channel. As result, the party in the other side of the connection (i.e., the client), will receive such message.\nMost real-world HTTP Servers will have a single function (or a single struct) to effectively handle the response. It gets the HTTP Request already parsed as input, and then, it tries to build the HTTP Response bit by bit, before the function sends it over the connection.\nWe would also have a specialized struct to represent a HTTP Response, and a lot of methods that would be used to build each part or component of the response object. Take the Response struct created by the Javascript runtime Bun as an example. You can find this struct in the response.zig module4 in their GitHub project.",
     "crumbs": [
       "<span class='chapter-number'>7</span>  <span class='chapter-title'>Project 2 - Building a HTTP Server from scratch</span>"
     ]
@@ -614,7 +614,7 @@
     "href": "Chapters/04-http-server.html#the-end-result",
     "title": "7  Project 2 - Building a HTTP Server from scratch",
     "section": "7.8 The end result",
-    "text": "7.8 The end result\nWe can now, update once again our main() function to incorporate our new functions from the response.zig module. First, I need to import this module into our main.zig module, then, I add the function calls to send_200() and send_404().\nNotice that I’m using if statements to decide which “response function” to call, based especially on the URI present in the HTTP Request. If the user asked for a content (or a document) that is not present in our server, we should respond with a 404 status code. But since we have just a simple HTTP server, with no real documents to send, we can just check if the URI is the root path (/) or not to decide which function to call.\nAlso, notice that I’m using the function std.mem.eql() from the Zig Standard Library to check if the string from uri is equal or not the string \"/\". We have described this function already at Section 1.8.4, so, comeback to that section if you are not familiar yet with this function.\n\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst Response = @import(\"response.zig\");\nconst Method = Request.Method;\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    try Request.read_request(connection, buffer[0..buffer.len]);\n    const request = Request.parse_request(\n        buffer[0..buffer.len]\n    );\n    if (request.method == Method.GET) {\n        if (std.mem.eql(u8, request.uri, \"/\")) {\n            try Response.send_200(connection);\n        } else {\n            try Response.send_404(connection);\n        }\n    }\n}\n\nNow that we adjusted our main() function, I can now execute our program, and see the effects of these last changes. First, I execute the program once again, with the run command of the zig compiler. The program will hang, waiting for a client to connect.\nThen, I open my web browser, and try to connect to the server again, using the URL localhost:3490. This time, instead of getting some sort of an error message from the browser, you will get the message “Hello World” printed into your web browser. Because this time, the server sended the HTTP Response successfully to the web browser, as demonstrated by Figure 7.3.\n\n\n\n\n\n\nFigure 7.3: The Hello World message sent in the HTTP Response\n\n\n\n\n\n\n\nMeehan, Eric. 2021. “Creating a Web Server from Scratch in c.” Youtube. https://www.youtube.com/watch?v=gk6NL1pZi1M&ab_channel=EricOMeehan.\n\n\nWeerasiri, Nipun Chamikara. 2023. “A Simple Web Server Written in c.” Medium. https://medium.com/@nipunweerasiri/a-simple-web-server-written-in-c-cf7445002e6.\n\n\nWikipedia. 2024. “Port (Computer Networking).” Wikipedia. https://en.wikipedia.org/wiki/Port_(computer_networking).\n\n\nYu, Jeffrey. 2023. “How i Built a Simple HTTP Server from Scratch Using c.” DEV Community. https://dev.to/jeffreythecoder/how-i-built-a-simple-http-server-from-scratch-using-c-739.",
+    "text": "7.8 The end result\nWe can now, update once again our main() function to incorporate our new functions from the response.zig module. First, I need to import this module into our main.zig module, then, I add the function calls to send_200() and send_404().\nNotice that I’m using if statements to decide which “response function” to call, based especially on the URI present in the HTTP Request. If the user asked for a content (or a document) that is not present in our server, we should respond with a 404 status code. But since we have just a simple HTTP server, with no real documents to send, we can just check if the URI is the root path (/) or not to decide which function to call.\nAlso, notice that I’m using the function std.mem.eql() from the Zig Standard Library to check if the string from uri is equal or not the string \"/\". We have described this function already in Section 1.8.4, so, comeback to that section if you are not familiar yet with this function.\n\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst Response = @import(\"response.zig\");\nconst Method = Request.Method;\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    try Request.read_request(connection, buffer[0..buffer.len]);\n    const request = Request.parse_request(\n        buffer[0..buffer.len]\n    );\n    if (request.method == Method.GET) {\n        if (std.mem.eql(u8, request.uri, \"/\")) {\n            try Response.send_200(connection);\n        } else {\n            try Response.send_404(connection);\n        }\n    }\n}\n\nNow that we adjusted our main() function, I can now execute our program, and see the effects of these last changes. First, I execute the program once again, with the run command of the zig compiler. The program will hang, waiting for a client to connect.\nThen, I open my web browser, and try to connect to the server again, using the URL localhost:3490. This time, instead of getting some sort of an error message from the browser, you will get the message “Hello World” printed into your web browser. Because this time, the server sended the HTTP Response successfully to the web browser, as demonstrated by Figure 7.3.\n\n\n\n\n\n\nFigure 7.3: The Hello World message sent in the HTTP Response\n\n\n\n\n\n\n\nMeehan, Eric. 2021. “Creating a Web Server from Scratch in c.” Youtube. https://www.youtube.com/watch?v=gk6NL1pZi1M&ab_channel=EricOMeehan.\n\n\nWeerasiri, Nipun Chamikara. 2023. “A Simple Web Server Written in c.” Medium. https://medium.com/@nipunweerasiri/a-simple-web-server-written-in-c-cf7445002e6.\n\n\nWikipedia. 2024. “Port (Computer Networking).” Wikipedia. https://en.wikipedia.org/wiki/Port_(computer_networking).\n\n\nYu, Jeffrey. 2023. “How i Built a Simple HTTP Server from Scratch Using c.” DEV Community. https://dev.to/jeffreythecoder/how-i-built-a-simple-http-server-from-scratch-using-c-739.",
     "crumbs": [
       "<span class='chapter-number'>7</span>  <span class='chapter-title'>Project 2 - Building a HTTP Server from scratch</span>"
     ]
@@ -634,7 +634,7 @@
     "href": "Chapters/03-unittests.html",
     "title": "8  Unit tests",
     "section": "",
-    "text": "8.1 Introducing the test block\nIn Zig, unit tests are written inside a test declaration, or, how I prefer to call it, inside a test block. Every test block is written by using the keyword test. You can optionally use a string literal to write a label, which is responsible for identifying the specific group of unit tests that you are writing inside this specific test block.\nIn the example below, we are testing if the sum of two objects (a and b) is equal to 4. The expect() function from the Zig Standard Library is a function that receives a logical test as input. If this logical test results in true, then, the test passes. But if it results in false, then, the test fails.\nYou can write any Zig code you want inside a test block. Part of this code might be some necessary commands to setup your testing environment, or just initializing some objects that you need to use in your unit tests.\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest \"testing simple sum\" {\n    const a: u8 = 2;\n    const b: u8 = 2;\n    try expect((a + b) == 4);\n}\n\n1/1 filea5b06c1ec326.test.testing simple sum...OKA\n  All 1 tests passed.\nYou can have multiple test blocks written on the same Zig module. Also, you can mix test blocks with your source code, with no problems or consequences. If you mix test blocks with your normal source code, when you execute the build, build-exe, build-obj or build-lib commands from the zig compiler that we exposed at Section 1.2.4, these test blocks are automatically ignored by the compiler.\nIn other words, the zig compiler builds and execute your unit tests only when you ask it to. By default, the compiler always ignore test blocks written in your Zig modules. The compiler normally checks only if there are any syntax errors in these test blocks.\nIf you take a look at the source code for most of the files present in the Zig Standard Library1, you can see that the test blocks are written together with the normal source code of the library. You can see this for example, at the array_list module2. So, the standard that the Zig developers decided to adopt is to keep their unit tests together with the source code of the functionality that they are testing.\nEach programmer might have a different opinion on this. Some of them might prefer to keep unit tests separate from the actual source code of their application. If that is your case, you can simply create a separate tests folder in your project, and start writing Zig modules that contains only unit tests (as you would normally do on a Python project with pytest, for example), and everything will work fine. It boils down to which is your preference here.",
+    "text": "8.1 Introducing the test block\nIn Zig, unit tests are written inside a test declaration, or, how I prefer to call it, inside a test block. Every test block is written by using the keyword test. You can optionally use a string literal to write a label, which is responsible for identifying the specific group of unit tests that you are writing inside this specific test block.\nIn the example below, we are testing if the sum of two objects (a and b) is equal to 4. The expect() function from the Zig Standard Library is a function that receives a logical test as input. If this logical test results in true, then, the test passes. But if it results in false, then, the test fails.\nYou can write any Zig code you want inside a test block. Part of this code might be some necessary commands to setup your testing environment, or just initializing some objects that you need to use in your unit tests.\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest \"testing simple sum\" {\n    const a: u8 = 2;\n    const b: u8 = 2;\n    try expect((a + b) == 4);\n}\n\n1/1 file81c21dbf264e.test.testing simple sum...OKA\n  All 1 tests passed.\nYou can have multiple test blocks written on the same Zig module. Also, you can mix test blocks with your source code, with no problems or consequences. If you mix test blocks with your normal source code, when you execute the build, build-exe, build-obj or build-lib commands from the zig compiler that we exposed in Section 1.2.4, these test blocks are automatically ignored by the compiler.\nIn other words, the zig compiler builds and execute your unit tests only when you ask it to. By default, the compiler always ignore test blocks written in your Zig modules. The compiler normally checks only if there are any syntax errors in these test blocks.\nIf you take a look at the source code for most of the files present in the Zig Standard Library1, you can see that the test blocks are written together with the normal source code of the library. You can see this for example, at the array_list module2. So, the standard that the Zig developers decided to adopt is to keep their unit tests together with the source code of the functionality that they are testing.\nEach programmer might have a different opinion on this. Some of them might prefer to keep unit tests separate from the actual source code of their application. If that is your case, you can simply create a separate tests folder in your project, and start writing Zig modules that contains only unit tests (as you would normally do on a Python project with pytest, for example), and everything will work fine. It boils down to which is your preference here.",
     "crumbs": [
       "<span class='chapter-number'>8</span>  <span class='chapter-title'>Unit tests</span>"
     ]
@@ -654,7 +654,7 @@
     "href": "Chapters/03-unittests.html#testing-memory-allocations",
     "title": "8  Unit tests",
     "section": "8.3 Testing memory allocations",
-    "text": "8.3 Testing memory allocations\nOne of the advantages of Zig is that it offers great tools that help us, programmers, to avoid (but also detect) memory problems, such as memory leaks and double-frees. The defer keyword is especially helpful in this regard.\nWhen developing your source code, you, the programmer, is responsible for making sure that your code do not produce such problems. However, you can also use a special type of an allocator object in Zig that is capable of automatically detecting such problems for you. This is the std.testing.allocator object. This allocator object offers some basic memory safety detection features, which are capable of detecting memory leaks.\nAs we described at Section 3.1.5, to allocate memory on the heap, you need to use an allocator object, and your functions that use these objects to allocate memory on the heap, should receive an allocator object as one of its inputs. Every memory on the heap that you allocate using these allocator objects, must also be freed using this same allocator object.\nSo, if you want to test the memory allocations performed by your functions, and make sure that you don’t have problems in these allocations, you can simply write unit tests for these functions, where you provide the std.testing.allocator object as input to these functions.\nLook at the example below, where I’m defining a function that clearly causes a memory leak. Because we allocate memory, but, at the same time, we do not free this allocated memory at any point. So, when the function returns, we lose the reference to the buffer object, which contains the allocated memory, and, as a result, we can no longer free this memory.\nNotice that, inside a test block I execute this function with the std.testing.allocator. The allocator object was capable of looking deeper in our program, and detecting the memory leak. As a result, this allocator object returns an error message of “memory leaked”, and also, a stack trace showing the exact point where the memory was leaked.\n\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nfn some_memory_leak(allocator: Allocator) !void {\n    const buffer = try allocator.alloc(u32, 10);\n    _ = buffer;\n    // Return without freeing the\n    // allocated memory\n}\n\ntest \"memory leak\" {\n    const allocator = std.testing.allocator;\n    try some_memory_leak(allocator);\n}\n\nTest [1/1] leak_memory.test.memory leak...\n    [gpa] (err): memory address 0x7c1fddf39000 leaked: \n./ZigExamples/debugging/leak_memory.zig:4:39: 0x10395f2\n    const buffer = try allocator.alloc(u32, 10);\n                                      ^\n./ZigExamples/debugging/leak_memory.zig:12:25: 0x10398ea\n    try some_memory_leak(allocator);\n\n... more stack trace",
+    "text": "8.3 Testing memory allocations\nOne of the advantages of Zig is that it offers great tools that help us, programmers, to avoid (but also detect) memory problems, such as memory leaks and double-frees. The defer keyword is especially helpful in this regard.\nWhen developing your source code, you, the programmer, are responsible for making sure that your code does not produce such problems. However, you can also use a special type of an allocator object in Zig that is capable of automatically detecting such problems for you. This is the std.testing.allocator object. This allocator object offers some basic memory safety detection features, which are capable of detecting memory leaks.\nAs we described in Section 3.1.5, to allocate memory on the heap, you need to use an allocator object, and your functions that use these objects to allocate memory on the heap, should receive an allocator object as one of its inputs. Every memory on the heap that you allocate using these allocator objects, must also be freed using this same allocator object.\nSo, if you want to test the memory allocations performed by your functions, and make sure that you don’t have problems in these allocations, you can simply write unit tests for these functions, where you provide the std.testing.allocator object as input to these functions.\nLook at the example below, where I’m defining a function that clearly causes a memory leak. Because we allocate memory, but, at the same time, we do not free this allocated memory at any point. So, when the function returns, we lose the reference to the buffer object, which contains the allocated memory, and, as a result, we can no longer free this memory.\nNotice that, inside a test block I execute this function with the std.testing.allocator. The allocator object was capable of looking deeper in our program, and detecting the memory leak. As a result, this allocator object returns an error message of “memory leaked”, and also, a stack trace showing the exact point where the memory was leaked.\n\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nfn some_memory_leak(allocator: Allocator) !void {\n    const buffer = try allocator.alloc(u32, 10);\n    _ = buffer;\n    // Return without freeing the\n    // allocated memory\n}\n\ntest \"memory leak\" {\n    const allocator = std.testing.allocator;\n    try some_memory_leak(allocator);\n}\n\nTest [1/1] leak_memory.test.memory leak...\n    [gpa] (err): memory address 0x7c1fddf39000 leaked:\n./ZigExamples/debugging/leak_memory.zig:4:39: 0x10395f2\n    const buffer = try allocator.alloc(u32, 10);\n                                      ^\n./ZigExamples/debugging/leak_memory.zig:12:25: 0x10398ea\n    try some_memory_leak(allocator);\n\n... more stack trace",
     "crumbs": [
       "<span class='chapter-number'>8</span>  <span class='chapter-title'>Unit tests</span>"
     ]
@@ -664,7 +664,7 @@
     "href": "Chapters/03-unittests.html#testing-errors",
     "title": "8  Unit tests",
     "section": "8.4 Testing errors",
-    "text": "8.4 Testing errors\nOne common style of unit tests are those that look for specific errors in your functions. In other words, you write a unit test that tries to assert if a specific function call returns any error, or a specific type of error.\nIn C++ you would normally write this style of unit tests using, for example, the functions REQUIRE_THROWS() or CHECK_THROWS() from the Catch2 test framework3. In the case of a Python project, you would probably use the raises() function from pytest4. While in Rust, you would probably use assert_eq!() in conjunction with Err().\nBut in Zig, we use the expectError() function, from the std.testing module. With this function, you can test if a specific function call returns the exact type of error that you expect it to return. To use this function, you first write try expectError(). Then, on the first argument, you provide the type of error that you are expecting from the function call. Then, on the second argument, you write the function call that you expect to fail.\nThe code example below demonstrates such type of unit test in Zig. Notice that, inside the function alloc_error() we are allocating 100 bytes of memory, or, an array of 100 elements, for the object ibuffer. However, in the test block, we are using the FixedBufferAllocator() allocator object, which is limited to 10 bytes of space, because the object buffer, which we provided to the allocator object, have only 10 bytes of space.\nThat is why, the alloc_error() function raises an OutOfMemory error on this case. Because this function is trying to allocate more space than the allocator object allows. So, in essence, we are testing for a specific type of error, which is OutOfMemory. If the alloc_error() function returns any other type of error, then, the expectError() function would make the entire test fail.\n\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst expectError = std.testing.expectError;\nfn alloc_error(allocator: Allocator) !void {\n    var ibuffer = try allocator.alloc(u8, 100);\n    defer allocator.free(ibuffer);\n    ibuffer[0] = 2;\n}\n\ntest \"testing error\" {\n    var buffer: [10]u8 = undefined;\n    var fba = std.heap.FixedBufferAllocator.init(&buffer);\n    const allocator = fba.allocator();\n    try expectError(error.OutOfMemory, alloc_error(allocator));\n}\n\n1/1 filea5b059c00874.test.testing error...OKAll 1 \n   tests passed.",
+    "text": "8.4 Testing errors\nOne common style of unit tests are those that look for specific errors in your functions. In other words, you write a unit test that tries to assert if a specific function call returns any error, or a specific type of error.\nIn C++ you would normally write this style of unit tests using, for example, the functions REQUIRE_THROWS() or CHECK_THROWS() from the Catch2 test framework3. In the case of a Python project, you would probably use the raises() function from pytest4. While in Rust, you would probably use assert_eq!() in conjunction with Err().\nBut in Zig, we use the expectError() function, from the std.testing module. With this function, you can test if a specific function call returns the exact type of error that you expect it to return. To use this function, you first write try expectError(). Then, on the first argument, you provide the type of error that you are expecting from the function call. Then, on the second argument, you write the function call that you expect to fail.\nThe code example below demonstrates such type of unit test in Zig. Notice that, inside the function alloc_error() we are allocating 100 bytes of memory, or, an array of 100 elements, for the object ibuffer. However, in the test block, we are using the FixedBufferAllocator() allocator object, which is limited to 10 bytes of space, because the object buffer, which we provided to the allocator object, have only 10 bytes of space.\nThat is why, the alloc_error() function raises an OutOfMemory error on this case. Because this function is trying to allocate more space than the allocator object allows. So, in essence, we are testing for a specific type of error, which is OutOfMemory. If the alloc_error() function returns any other type of error, then, the expectError() function would make the entire test fail.\n\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst expectError = std.testing.expectError;\nfn alloc_error(allocator: Allocator) !void {\n    var ibuffer = try allocator.alloc(u8, 100);\n    defer allocator.free(ibuffer);\n    ibuffer[0] = 2;\n}\n\ntest \"testing error\" {\n    var buffer: [10]u8 = undefined;\n    var fba = std.heap.FixedBufferAllocator.init(&buffer);\n    const allocator = fba.allocator();\n    try expectError(error.OutOfMemory, alloc_error(allocator));\n}\n\n1/1 file81c24fea00d1.test.testing error...OKAll 1 \n   tests passed.",
     "crumbs": [
       "<span class='chapter-number'>8</span>  <span class='chapter-title'>Unit tests</span>"
     ]
@@ -674,7 +674,7 @@
     "href": "Chapters/03-unittests.html#testing-simple-equalities",
     "title": "8  Unit tests",
     "section": "8.5 Testing simple equalities",
-    "text": "8.5 Testing simple equalities\nIn Zig, there are some different ways you can test for an equality. You already saw that we can use expect() with the logical operator == to essentially reproduce an equality test. But we also have some other helper functions that you should know about, especially expectEqual(), expectEqualSlices() and expectEqualStrings().\nThe expectEqual() function, as the name suggests, is a classic test equality function. It receives two objects as input. The first object is the value that you expect to be in the second object. While second object is the object you have, or, the object that your application produced as result. So, with expectEqual() you are essentially testing if the values stored inside these two objects are equal or not.\nYou can see in the example below that, the test performed by expectEqual() failed. Because the objects v1 and v2 contain different values in them.\n\nconst std = @import(\"std\");\ntest \"values are equal?\" {\n    const v1 = 15;\n    const v2 = 18;\n    try std.testing.expectEqual(v1, v2);\n}\n\n1/1 ve.test.values are equal?...\n    expected 15, found 18\n    FAIL (TestExpectedEqual)\nve.zig:5:5: test.values are equal? (test)\n    try std.testing.expectEqual(v1, v2);\n    ^\n0 passed; 0 skipped; 1 failed.\nAlthough useful, the expectEqual() function does not work with arrays. For testing if two arrays are equal, you should use the expectEqualSlices() function instead. This function have three arguments. First, you provide the data type contained in both arrays that you are trying to compare. While the second and third arguments corresponds to the array objects that you want to compare.\nIn the example below, we are using this function to test if two array objects (array1 and array2) are equal or not. Since they are in fact equal, the unit test passed with no errors.\n\nconst std = @import(\"std\");\ntest \"arrays are equal?\" {\n    const array1 = [3]u32{1, 2, 3};\n    const array2 = [3]u32{1, 2, 3};\n    try std.testing.expectEqualSlices(\n        u32, &array1, &array2\n    );\n}\n\n1/1 filea5b054e42b80.test.arrays are equal?...OKAl\n  ll 1 tests passed.\n\n\nAt last, you might also want to use the expectEqualStrings() function. As the name suggests, you can use this function to test if two strings are equal or not. Just provide the two string objects that you want to compare, as inputs to the function.\nIf the function finds any existing differences between the two strings, then, the function will raise an error, and also, print an error message that shows the exact difference between the two string objects provided, as the example below demonstrates:\n\nconst std = @import(\"std\");\ntest \"strings are equal?\" {\n    const str1 = \"hello, world!\";\n    const str2 = \"Hello, world!\";\n    try std.testing.expectEqualStrings(\n        str1, str2\n    );\n}\n\n1/1 t.test.strings are equal?... \n====== expected this output: =========\nhello, world!␃\n======== instead found this: =========\nHello, world!␃\n======================================\nFirst difference occurs on line 1:\nexpected:\nhello, world!\n^ ('\\x68')\nfound:\nHello, world!\n^ ('\\x48')",
+    "text": "8.5 Testing simple equalities\nIn Zig, there are some different ways you can test for an equality. You already saw that we can use expect() with the logical operator == to essentially reproduce an equality test. But we also have some other helper functions that you should know about, especially expectEqual(), expectEqualSlices() and expectEqualStrings().\nThe expectEqual() function, as the name suggests, is a classic test equality function. It receives two objects as input. The first object is the value that you expect to be in the second object. While second object is the object you have, or, the object that your application produced as result. So, with expectEqual() you are essentially testing if the values stored inside these two objects are equal or not.\nYou can see in the example below that, the test performed by expectEqual() failed. Because the objects v1 and v2 contain different values in them.\n\nconst std = @import(\"std\");\ntest \"values are equal?\" {\n    const v1 = 15;\n    const v2 = 18;\n    try std.testing.expectEqual(v1, v2);\n}\n\n1/1 ve.test.values are equal?...\n    expected 15, found 18\n    FAIL (TestExpectedEqual)\nve.zig:5:5: test.values are equal? (test)\n    try std.testing.expectEqual(v1, v2);\n    ^\n0 passed; 0 skipped; 1 failed.\nAlthough useful, the expectEqual() function does not work with arrays. For testing if two arrays are equal, you should use the expectEqualSlices() function instead. This function have three arguments. First, you provide the data type contained in both arrays that you are trying to compare. While the second and third arguments corresponds to the array objects that you want to compare.\nIn the example below, we are using this function to test if two array objects (array1 and array2) are equal or not. Since they are in fact equal, the unit test passed with no errors.\n\nconst std = @import(\"std\");\ntest \"arrays are equal?\" {\n    const array1 = [3]u32{1, 2, 3};\n    const array2 = [3]u32{1, 2, 3};\n    try std.testing.expectEqualSlices(\n        u32, &array1, &array2\n    );\n}\n\n1/1 file81c25513148.test.arrays are equal?...OKAll\n  l 1 tests passed.\n\n\nAt last, you might also want to use the expectEqualStrings() function. As the name suggests, you can use this function to test if two strings are equal or not. Just provide the two string objects that you want to compare, as inputs to the function.\nIf the function finds any existing differences between the two strings, then, the function will raise an error, and also, print an error message that shows the exact difference between the two string objects provided, as the example below demonstrates:\n\nconst std = @import(\"std\");\ntest \"strings are equal?\" {\n    const str1 = \"hello, world!\";\n    const str2 = \"Hello, world!\";\n    try std.testing.expectEqualStrings(\n        str1, str2\n    );\n}\n\n1/1 t.test.strings are equal?...\n====== expected this output: =========\nhello, world!␃\n======== instead found this: =========\nHello, world!␃\n======================================\nFirst difference occurs on line 1:\nexpected:\nhello, world!\n^ ('\\x68')\nfound:\nHello, world!\n^ ('\\x48')",
     "crumbs": [
       "<span class='chapter-number'>8</span>  <span class='chapter-title'>Unit tests</span>"
     ]
@@ -694,7 +694,7 @@
     "href": "Chapters/07-build-system.html",
     "title": "9  Build System",
     "section": "",
-    "text": "9.1 How source code is built?\nWe already have talked about the challenges of building source code in low-level languages at Section 1.2.1. As we described at that section, programmers invented Build Systems to surpass these challenges on the process of building source code in low-level languages.\nLow-level languages uses a compiler to compile (or to build) your source code into binary instructions. In C and C++, we normally use compilers like gcc, g++ or clang to compile our C and C++ source code into these instructions. Every language have its own compiler, and this is no different in Zig.\nIn Zig, we have the zig compiler to compile our Zig source code into binary instructions that can be executed by our computer. In Zig, the compilation (or the build) process involves the following components:\nThese are the things that you need to connect together in order to build your source code in Zig. In C and C++, you would have an extra component, which are the header files of the libraries that you are using. But header files do not exist in Zig, so, you only need to care about them if you are linking your Zig source code with a C library. If that is not your case, you can forget about it.\nYour build process is usually organized in a build script. In Zig, we normally write this build script into a Zig module in the root directory of our project, named as build.zig. You write this build script, then, when you run it, your project get’s built into binary files that you can use and distribute to your users.\nThis build script is normally organized around target objects. A target is simply something to be built, or, in other words, it’s something that you want the zig compiler to build for you. This concept of “targets” is present in most Build Systems, especially in CMake3.\nThere are four types of target objects that you can build in Zig, which are:\nWe are going to talk more about these target objects at Section 9.3.",
+    "text": "9.1 How source code is built?\nWe already have talked about the challenges of building source code in low-level languages in Section 1.2.1. As we described at that section, programmers invented Build Systems to surpass these challenges on the process of building source code in low-level languages.\nLow-level languages uses a compiler to compile (or to build) your source code into binary instructions. In C and C++, we normally use compilers like gcc, g++ or clang to compile our C and C++ source code into these instructions. Every language have its own compiler, and this is no different in Zig.\nIn Zig, we have the zig compiler to compile our Zig source code into binary instructions that can be executed by our computer. In Zig, the compilation (or the build) process involves the following components:\nThese are the things that you need to connect together in order to build your source code in Zig. In C and C++, you would have an extra component, which are the header files of the libraries that you are using. But header files do not exist in Zig, so, you only need to care about them if you are linking your Zig source code with a C library. If that is not your case, you can forget about it.\nYour build process is usually organized in a build script. In Zig, we normally write this build script into a Zig module in the root directory of our project, named as build.zig. You write this build script, then, when you run it, your project gets built into binary files that you can use and distribute to your users.\nThis build script is normally organized around target objects. A target is simply something to be built, or, in other words, it’s something that you want the zig compiler to build for you. This concept of “targets” is present in most Build Systems, especially in CMake3.\nThere are four types of target objects that you can build in Zig, which are:\nWe are going to talk more about these target objects in Section 9.3.",
     "crumbs": [
       "<span class='chapter-number'>9</span>  <span class='chapter-title'>Build System</span>"
     ]
@@ -714,7 +714,7 @@
     "href": "Chapters/07-build-system.html#sec-build-fun",
     "title": "9  Build System",
     "section": "9.2 The build() function",
-    "text": "9.2 The build() function\nA build script in Zig always contains a public (and top-level) build() function declared. It is like the main() function on the main Zig module of your project, that we discussed at Section 1.2.3. But instead of creating the entrypoint to your code, this build() function is the entrypoint to the build process.\nThis build() function should accept a pointer to a Build object as input, and it should use this “build object” to perform the necessary steps to build your project. The return type of this function is always void, and this Build struct comes directly from the Zig Standard Library (std.Build). So, you can access this struct by just importing the Zig Standard Library into your build.zig module.\nJust as a very simple example, here you can see the source code necessary to build an executable file from the hello.zig Zig module.\n\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"hello.zig\"),\n        .target = b.host,\n    });\n    b.installArtifact(exe);\n}\n\nYou can define and use other functions and objects in this build script. You can also import other Zig modules as you would normally do in any other module of your project. The only real requirement for this build script, is to have a public and top-level build() function defined, that accepts a pointer to a Build struct as input.",
+    "text": "9.2 The build() function\nA build script in Zig always contains a public (and top-level) build() function declared. It’s like the main() function in the main Zig module of your project, that we discussed in Section 1.2.3. But instead of creating the entrypoint to your code, this build() function is the entrypoint to the build process.\nThis build() function should accept a pointer to a Build object as input, and it should use this “build object” to perform the necessary steps to build your project. The return type of this function is always void, and this Build struct comes directly from the Zig Standard Library (std.Build). So, you can access this struct by just importing the Zig Standard Library into your build.zig module.\nJust as a very simple example, here you can see the source code necessary to build an executable file from the hello.zig Zig module.\n\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"hello.zig\"),\n        .target = b.host,\n    });\n    b.installArtifact(exe);\n}\n\nYou can define and use other functions and objects in this build script. You can also import other Zig modules as you would normally do in any other module of your project. The only real requirement for this build script, is to have a public and top-level build() function defined, that accepts a pointer to a Build struct as input.",
     "crumbs": [
       "<span class='chapter-number'>9</span>  <span class='chapter-title'>Build System</span>"
     ]
@@ -724,7 +724,7 @@
     "href": "Chapters/07-build-system.html#sec-targets",
     "title": "9  Build System",
     "section": "9.3 Target objects",
-    "text": "9.3 Target objects\nAs we described over the previous sections, a build script is composed around target objects. Each target object is normally a binary file (or an output) that you want to get from the build process. You can list multiple target objects in your build script, so that the build process generates multiple binary files for you at once.\nFor example, maybe you are a developer working in a cross-platform application, and, because this application is cross-platform, you probably need to release binary files of your software for each OS supported by your application to your end users. Thus, you can define a different target object in your build script for each OS (Windows, Linux, etc.) where you want to publish your software. This will make the zig compiler to build your project to multiple target OS’s at once. The Zig Build System official documentation have a great code example that demonstrates this strategy4.\nA target object is created by the following methods of the Build struct that we introduced at Section 9.2:\n\naddExecutable() creates an executable file;\naddSharedLibrary() creates a shared library file;\naddStaticLibrary() creates a static library file;\naddTest() creates an executable file that executes unit tests.\n\nThese functions are methods from the Build struct that you receive as input of the build() function. All of them, create as output a Compile object, which represents a target object to be compiled by the zig compiler. All of these functions accept a similar struct literal as input. This struct literal defines three essential specs about this target object that you are building: name, target and root_source_file.\nWe have already seen these three options being used on the previous example, where we used the addExecutable() method to create an executable target object. This example is reproduced below. Notice the use of the path() method from the Build struct, to define a path in the root_source_file option.\n\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nThe name option specify the name that you want to give to the binary file defined by this target object. So, in this example, we are building an executable file named hello. Is common to set this name option to the name of your project.\nFurthermore, the target option specify the target computer architecture (or the target operating system) of this binary file. For example, if you want this target object to run on a Windows machine that uses a x86_64 architecture, you can set this target option to x86_64-windows-gnu for example. This will make the zig compiler to compile the project to run on a x86_64 Windows machine. You can see the full list of architectures and OS’s that the zig compiler supports by running the zig targets command in the terminal.\nNow, if you are building the project to run on the current machine that you are using to run this build script, you can set this target option to the host method of the Build object, like we did in the example above. This host method identifies the current machine where you are currently running the zig compiler.\nAt last, the root_source_file option specifies the root Zig module of your project. That is the Zig module that contains the entrypoint to your application (i.e. the main() function), or, the main API of your library. This also means that, all the Zig modules that compose your project are automatically discovered from the import statements you have inside this “root source file”. The zig compiler can detect when a Zig module depends on the other through the import statements, and, as a result, it can discover the entire map of Zig modules used in your project.\nThis is handy, and it is different from what happens in other build systems. In CMake for example, you have to explicitly list the paths to all source files that you want to include in your build process. This is probably a symptom of the “lack of conditional compilation” in the C and C++ compilers. Since they lack this feature, you have to explicitly choose which source files should be sent to the C/C++ compiler, because not every C/C++ code is portable or supported in every operating system, and, therefore, would cause a compilation error in the C/C++ compiler.\nNow, one important detail about the build process is that, you have to explicitly install the target objects that you create in your build script, by using the installArtifact() method of the Build struct.\nEverytime you invoke the build process of your project, by calling the build command of the zig compiler, a new directory named zig-out is created in the root directory of your project. This new directory contains the outputs of the build process, that is, the binary files built from your source code.\nWhat the installArtifact() method do is to install (or copy) the built target objects that you defined to this zig-out directory. This means that, if you do not install the target objects you define in your build script, these target objects are essentially discarded at the end of the build process.\nFor example, you might be building a project that uses a third party library that is built together with the project. So, when you build your project, you would need first, to build the third party library, and then, you link it with the source code of your project. So, in this case, we have two binary files that are generated in the build process (the executable file of your project, and the third party library). But only one is of interest, which is the executable file of our project. We can discard the binary file of the third party library, by simply not installing it into this zig-out directory.\nThis installArtifact() method is pretty straightforward. Just remember to apply it to every target object that you want to save into the zig-out directory, like in the example below:\n\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nb.installArtifact(exe);",
+    "text": "9.3 Target objects\nAs we described over the previous sections, a build script is composed around target objects. Each target object is normally a binary file (or an output) that you want to get from the build process. You can list multiple target objects in your build script, so that the build process generates multiple binary files for you at once.\nFor example, maybe you are a developer working in a cross-platform application, and, because this application is cross-platform, you probably need to release binary files of your software for each OS supported by your application to your end users. Thus, you can define a different target object in your build script for each OS (Windows, Linux, etc.) where you want to publish your software. This will make the zig compiler to build your project to multiple target OS’s at once. The Zig Build System official documentation have a great code example that demonstrates this strategy4.\nA target object is created by the following methods of the Build struct that we introduced in Section 9.2:\n\naddExecutable() creates an executable file;\naddSharedLibrary() creates a shared library file;\naddStaticLibrary() creates a static library file;\naddTest() creates an executable file that executes unit tests.\n\nThese functions are methods from the Build struct that you receive as input of the build() function. All of them, create as output a Compile object, which represents a target object to be compiled by the zig compiler. All of these functions accept a similar struct literal as input. This struct literal defines three essential specs about this target object that you are building: name, target and root_source_file.\nWe have already seen these three options being used on the previous example, where we used the addExecutable() method to create an executable target object. This example is reproduced below. Notice the use of the path() method from the Build struct, to define a path in the root_source_file option.\n\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nThe name option specify the name that you want to give to the binary file defined by this target object. So, in this example, we are building an executable file named hello. It’s common to set this name option to the name of your project.\nFurthermore, the target option specify the target computer architecture (or the target operating system) of this binary file. For example, if you want this target object to run on a Windows machine that uses a x86_64 architecture, you can set this target option to x86_64-windows-gnu for example. This will make the zig compiler to compile the project to run on a x86_64 Windows machine. You can see the full list of architectures and OS’s that the zig compiler supports by running the zig targets command in the terminal.\nNow, if you are building the project to run on the current machine that you are using to run this build script, you can set this target option to the host method of the Build object, like we did in the example above. This host method identifies the current machine where you are currently running the zig compiler.\nAt last, the root_source_file option specifies the root Zig module of your project. That is the Zig module that contains the entrypoint to your application (i.e., the main() function), or, the main API of your library. This also means that, all the Zig modules that compose your project are automatically discovered from the import statements you have inside this “root source file”. The zig compiler can detect when a Zig module depends on the other through the import statements, and, as a result, it can discover the entire map of Zig modules used in your project.\nThis is handy, and it’s different from what happens in other build systems. In CMake for example, you have to explicitly list the paths to all source files that you want to include in your build process. This is probably a symptom of the “lack of conditional compilation” in the C and C++ compilers. Since they lack this feature, you have to explicitly choose which source files should be sent to the C/C++ compiler, because not every C/C++ code is portable or supported in every operating system, and, therefore, would cause a compilation error in the C/C++ compiler.\nNow, one important detail about the build process is that, you have to explicitly install the target objects that you create in your build script, by using the installArtifact() method of the Build struct.\nEverytime you invoke the build process of your project, by calling the build command of the zig compiler, a new directory named zig-out is created in the root directory of your project. This new directory contains the outputs of the build process, that is, the binary files built from your source code.\nWhat the installArtifact() method do is to install (or copy) the built target objects that you defined to this zig-out directory. This means that, if you do not install the target objects you define in your build script, these target objects are essentially discarded at the end of the build process.\nFor example, you might be building a project that uses a third party library that is built together with the project. So, when you build your project, you would need first, to build the third party library, and then, you link it with the source code of your project. So, in this case, we have two binary files that are generated in the build process (the executable file of your project, and the third party library). But only one is of interest, which is the executable file of our project. We can discard the binary file of the third party library, by simply not installing it into this zig-out directory.\nThis installArtifact() method is pretty straightforward. Just remember to apply it to every target object that you want to save into the zig-out directory, like in the example below:\n\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nb.installArtifact(exe);",
     "crumbs": [
       "<span class='chapter-number'>9</span>  <span class='chapter-title'>Build System</span>"
     ]
@@ -734,7 +734,7 @@
     "href": "Chapters/07-build-system.html#setting-the-build-mode",
     "title": "9  Build System",
     "section": "9.4 Setting the build mode",
-    "text": "9.4 Setting the build mode\nWe have talked about the three essential options that are set when you create a new target object. But there is also a fourth option that you can use to set the build mode of this target object, which is the optimize option. This option is called this way, because the build modes in Zig are treated more of an “optimization vs safety” problem. So optimization plays an important role here. Don’t worry, I’m going back to this question very soon.\nIn Zig, we have four build modes (which are listed below). Each one of these build modes offer different advantages and characteristics. As we described at Section 5.2.1, the zig compiler uses the Debug build mode by default, when you don’t explicitly choose a build mode.\n\nDebug, mode that produces and includes debugging information in the output of the build process (i.e. the binary file defined by the target object);\nReleaseSmall, mode that tries to produce a binary file that is small in size;\nReleaseFast, mode that tries to optimize your code, in order to produce a binary file that is as fast as possible;\nReleaseSafe, mode that tries to make your code as safe as possible, by including safeguards when possible.\n\nSo, when you build your project, you can set the build mode of your target object to ReleaseFast for example, which will tell the zig compiler to apply important optimizations in your code. This creates a binary file that simply runs faster on most contexts, because it contains a more optimized version of your code. However, as a result, we often lose some safety features in our code. Because some safety checks are removed from the final binary file, which makes your code run faster, but in a less safe manner.\nThis choice depends on your current priorities. If you are building a cryptography or banking system, you might prefer to prioritize safety in your code, so, you would choose the ReleaseSafe build mode, which is a little slower to run, but much more secure, because it includes all possible runtime safety checks in the binary file built in the build process. In the other hand, if you are writing a game for example, you might prefer to prioritize performance over safety, by using the ReleaseFast build mode, so that your users can experience faster frame rates in your game.\nIn the example below, we are creating the same target object that we have used on previous examples. But this time, we are specifying the build mode of this target object to the ReleaseSafe mode.\n\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .optimize = .ReleaseSafe\n});\nb.installArtifact(exe);",
+    "text": "9.4 Setting the build mode\nWe have talked about the three essential options that are set when you create a new target object. But there is also a fourth option that you can use to set the build mode of this target object, which is the optimize option. This option is called this way, because the build modes in Zig are treated more of an “optimization vs safety” problem. So optimization plays an important role here. Don’t worry, I’m going back to this question very soon.\nIn Zig, we have four build modes (which are listed below). Each one of these build modes offer different advantages and characteristics. As we described in Section 5.2.1, the zig compiler uses the Debug build mode by default, when you don’t explicitly choose a build mode.\n\nDebug, mode that produces and includes debugging information in the output of the build process (i.e., the binary file defined by the target object);\nReleaseSmall, mode that tries to produce a binary file that is small in size;\nReleaseFast, mode that tries to optimize your code, in order to produce a binary file that is as fast as possible;\nReleaseSafe, mode that tries to make your code as safe as possible, by including safeguards when possible.\n\nSo, when you build your project, you can set the build mode of your target object to ReleaseFast for example, which will tell the zig compiler to apply important optimizations in your code. This creates a binary file that simply runs faster on most contexts, because it contains a more optimized version of your code. However, as a result, we often lose some safety features in our code. Because some safety checks are removed from the final binary file, which makes your code run faster, but in a less safe manner.\nThis choice depends on your current priorities. If you are building a cryptography or banking system, you might prefer to prioritize safety in your code, so, you would choose the ReleaseSafe build mode, which is a little slower to run, but much more secure, because it includes all possible runtime safety checks in the binary file built in the build process. In the other hand, if you are writing a game for example, you might prefer to prioritize performance over safety, by using the ReleaseFast build mode, so that your users can experience faster frame rates in your game.\nIn the example below, we are creating the same target object that we have used on previous examples. But this time, we are specifying the build mode of this target object to the ReleaseSafe mode.\n\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .optimize = .ReleaseSafe\n});\nb.installArtifact(exe);",
     "crumbs": [
       "<span class='chapter-number'>9</span>  <span class='chapter-title'>Build System</span>"
     ]
@@ -754,7 +754,7 @@
     "href": "Chapters/07-build-system.html#sec-detect-os",
     "title": "9  Build System",
     "section": "9.6 Detecting the OS in your build script",
-    "text": "9.6 Detecting the OS in your build script\nIs very common in Build Systems to use different options, or, to include different modules, or, to link against different libraries depending on the Operational System (OS) that you are targeting in the build process.\nIn Zig, you can detect the target OS of the build process, by looking at the os.tag inside the builtin module from the Zig library. In the example below, we are using an if statement to run some arbitrary code when the target of the build process is a Windows system.\n\nconst builtin = @import(\"builtin\");\nif (builtin.target.os.tag == .windows) {\n    // Code that runs only when the target of\n    // the compilation process is Windows.\n}",
+    "text": "9.6 Detecting the OS in your build script\nIt’s very common in Build Systems to use different options, or, to include different modules, or, to link against different libraries depending on the Operational System (OS) that you are targeting in the build process.\nIn Zig, you can detect the target OS of the build process, by looking at the os.tag inside the builtin module from the Zig library. In the example below, we are using an if statement to run some arbitrary code when the target of the build process is a Windows system.\n\nconst builtin = @import(\"builtin\");\nif (builtin.target.os.tag == .windows) {\n    // Code that runs only when the target of\n    // the compilation process is Windows.\n}",
     "crumbs": [
       "<span class='chapter-number'>9</span>  <span class='chapter-title'>Build System</span>"
     ]
@@ -764,7 +764,7 @@
     "href": "Chapters/07-build-system.html#adding-a-run-step-to-your-build-process",
     "title": "9  Build System",
     "section": "9.7 Adding a run step to your build process",
-    "text": "9.7 Adding a run step to your build process\nOne thing that is neat in Rust is that you can compile and run your source code with one single command (cargo run) from the Rust compiler. We saw at Section 1.2.5 how can we perform a similar job in Zig, by building and running our Zig source code through the run command from the zig compiler.\nBut how can we, at the same time, build and run the binary file specified by a target object in our build script? The answer is by including a “run artifact” in our build script. A run artifact is created through the addRunArtifact() method from the Build struct. We simply provide as input to this function the target object that describes the binary file that we want to execute. As a result, this function creates a run artifact that is capable of executing this binary file.\nIn the example below, we are defining an executable binary file named hello, and we use this addRunArtifact() method to create a run artifact that will execute this hello executable file.\n\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"src/hello.zig\"),\n    .target = b.host\n});\nb.installArtifact(exe);\nconst run_arti = b.addRunArtifact(exe);\n\nNow that we have created this run artifact, we need to include it in the build process. We do that by declaring a new step in our build script to call this artifact, through the step() method of the Build struct.\nWe can give any name we want to this step, but, for our context here, I’m going to name this step as “run”. Also, I give it a brief description to this step (“Run the project”).\n\nconst run_step = b.step(\n    \"run\", \"Run the project\"\n);\n\nNow that we have declared this “run step” we need to tell Zig that this “run step” depends on the run artifact. In other words, a run artifact always depends on a “step” to effectively be executed. By creating this dependency we finally stablish the necessary commands to build and run the executable file from the build script.\nWe can establish a dependency between the run step and the run artifact by using the dependsOn() method from the run step. So, we first create the run step, and then, we link it with the run artifact, by using this dependsOn() method from the run step.\n\nrun_step.dependOn(&run_arti.step);\n\nThe entire source code of this specific build script that we wrote, piece by piece, in this section, is available in the build_and_run.zig module. You can see this module by visiting the official repository of this book 6.\nWhen you declare a new step in your build script, this step becomes available through the build command in the zig compiler. You can actually see this step by running zig build --help in the terminal, like in the example below, where we can see that this new “run” step that we declared in the build script appeared in the output.\nzig build --help\nSteps:\n  ...\n  run   Run the project\n  ...\nNow, everything that we need to is to call this “run” step that we created in our build script. We call it by using the name that we gave to this step after the build command from the zig compiler. This will cause the compiler to build our executable file and execute it at the same time.\nzig build run",
+    "text": "9.7 Adding a run step to your build process\nOne thing that is neat in Rust is that you can compile and run your source code with one single command (cargo run) from the Rust compiler. We saw in Section 1.2.5 how can we perform a similar job in Zig, by building and running our Zig source code through the run command from the zig compiler.\nBut how can we, at the same time, build and run the binary file specified by a target object in our build script? The answer is by including a “run artifact” in our build script. A run artifact is created through the addRunArtifact() method from the Build struct. We simply provide as input to this function the target object that describes the binary file that we want to execute. As a result, this function creates a run artifact that is capable of executing this binary file.\nIn the example below, we are defining an executable binary file named hello, and we use this addRunArtifact() method to create a run artifact that will execute this hello executable file.\n\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"src/hello.zig\"),\n    .target = b.host\n});\nb.installArtifact(exe);\nconst run_arti = b.addRunArtifact(exe);\n\nNow that we have created this run artifact, we need to include it in the build process. We do that by declaring a new step in our build script to call this artifact, through the step() method of the Build struct.\nWe can give any name we want to this step, but, for our context here, I’m going to name this step as “run”. Also, I give it a brief description to this step (“Run the project”).\n\nconst run_step = b.step(\n    \"run\", \"Run the project\"\n);\n\nNow that we have declared this “run step” we need to tell Zig that this “run step” depends on the run artifact. In other words, a run artifact always depends on a “step” to effectively be executed. By creating this dependency we finally stablish the necessary commands to build and run the executable file from the build script.\nWe can establish a dependency between the run step and the run artifact by using the dependsOn() method from the run step. So, we first create the run step, and then, we link it with the run artifact, by using this dependsOn() method from the run step.\n\nrun_step.dependOn(&run_arti.step);\n\nThe entire source code of this specific build script that we wrote, piece by piece, in this section, is available in the build_and_run.zig module. You can see this module by visiting the official repository of this book 6.\nWhen you declare a new step in your build script, this step becomes available through the build command in the zig compiler. You can actually see this step by running zig build --help in the terminal, like in the example below, where we can see that this new “run” step that we declared in the build script appeared in the output.\nzig build --help\nSteps:\n  ...\n  run   Run the project\n  ...\nNow, everything that we need to is to call this “run” step that we created in our build script. We call it by using the name that we gave to this step after the build command from the zig compiler. This will cause the compiler to build our executable file and execute it at the same time.\nzig build run",
     "crumbs": [
       "<span class='chapter-number'>9</span>  <span class='chapter-title'>Build System</span>"
     ]
@@ -774,7 +774,7 @@
     "href": "Chapters/07-build-system.html#build-unit-tests-in-your-project",
     "title": "9  Build System",
     "section": "9.8 Build unit tests in your project",
-    "text": "9.8 Build unit tests in your project\nWe have talked at length about writing unit tests in Zig at Chapter 8, and we also have talked about how to execute these unit tests through the test command of the zig compiler. However, as we did with the run command on the previous section, we also might want to include some commands in our build script to also build and execute the unit tests in our project.\nSo, once again, we are going to discuss how a specific built-in command from the zig compiler, (in this case, the test command) can be used in a build script in Zig. Here is where a “test target object” comes into play. As was described at Section 9.3, we can create a test target object by using the addTest() method of the Build struct. The first thing that we need to do is to declare a test target object in our build script.\n\nconst test_exe = b.addTest(.{\n    .name = \"unit_tests\",\n    .root_source_file = b.path(\"src/main.zig\"),\n    .target = b.host,\n});\nb.installArtifact(test_exe);\n\nA test target object essentially selects all test blocks in all Zig modules across your project, and builds only the source code present inside these test blocks in your project. As a result, this target object creates an executable file that contains only the source code present in all of these test blocks (i.e. the unit tests) in your project.\nPerfect! Now that we have declared this test target object, an executable file named unit_tests is built by the zig compiler when we trigger the build script with the build command. After the build process is finished, we can simply execute this unit_tests executable in the terminal.\nHowever, if you remember the previous section, we already learned how can we create a run step in our build script, to execute an executable file built by the build script.\nSo, we could simply add a run step in our build script to run these unit tests from a single command in the zig compiler, to make our lifes easier. In the example below, we demonstrate the commands to register a new build step called “tests” in our build script to run these unit tests.\n\nconst run_arti = b.addRunArtifact(test_exe);\nconst run_step = b.step(\"tests\", \"Run unit tests\");\nrun_step.dependOn(&run_arti.step);\n\nNow that we registered this new build step, we can trigger it by calling the command below in the terminal. You can also checkout the complete source code for this specific build script at the build_tests.zig module at the official repository of this book 7.\nzig build tests",
+    "text": "9.8 Build unit tests in your project\nWe have talked at length about writing unit tests in Zig in Chapter 8, and we also have talked about how to execute these unit tests through the test command of the zig compiler. However, as we did with the run command on the previous section, we also might want to include some commands in our build script to also build and execute the unit tests in our project.\nSo, once again, we are going to discuss how a specific built-in command from the zig compiler, (in this case, the test command) can be used in a build script in Zig. Here is where a “test target object” comes into play. As was described in Section 9.3, we can create a test target object by using the addTest() method of the Build struct. The first thing that we need to do is to declare a test target object in our build script.\n\nconst test_exe = b.addTest(.{\n    .name = \"unit_tests\",\n    .root_source_file = b.path(\"src/main.zig\"),\n    .target = b.host,\n});\nb.installArtifact(test_exe);\n\nA test target object essentially selects all test blocks in all Zig modules across your project, and builds only the source code present inside these test blocks in your project. As a result, this target object creates an executable file that contains only the source code present in all of these test blocks (i.e., the unit tests) in your project.\nPerfect! Now that we have declared this test target object, an executable file named unit_tests is built by the zig compiler when we trigger the build script with the build command. After the build process is finished, we can simply execute this unit_tests executable in the terminal.\nHowever, if you remember the previous section, we already learned how can we create a run step in our build script, to execute an executable file built by the build script.\nSo, we could simply add a run step in our build script to run these unit tests from a single command in the zig compiler, to make our lifes easier. In the example below, we demonstrate the commands to register a new build step called “tests” in our build script to run these unit tests.\n\nconst run_arti = b.addRunArtifact(test_exe);\nconst run_step = b.step(\"tests\", \"Run unit tests\");\nrun_step.dependOn(&run_arti.step);\n\nNow that we registered this new build step, we can trigger it by calling the command below in the terminal. You can also checkout the complete source code for this specific build script at the build_tests.zig module at the official repository of this book 7.\nzig build tests",
     "crumbs": [
       "<span class='chapter-number'>9</span>  <span class='chapter-title'>Build System</span>"
     ]
@@ -794,7 +794,7 @@
     "href": "Chapters/07-build-system.html#linking-to-external-libraries",
     "title": "9  Build System",
     "section": "9.10 Linking to external libraries",
-    "text": "9.10 Linking to external libraries\nOne essential part of every build process is the linking stage. This stage is responsible for combining the multiple object files that represent your code, into a single executable file. It also links this executable file to external libraries, if you use any in your code.\nIn Zig, we have two notions of a “library”, which are: 1) a system’s library; 2) a local library. A system’s library is just a library that already is installed in your system. While a local library is a library that belongs to the current project. Is a library that is present in your project directory, and that you are building together with your project source code.\nThe basic difference between the two, is that a system’s library is already built and installed in your system, supposedly, and all you need to do is to link your source code to this library to start using it. We do that by using the linkSystemLibrary() method from a Compile object. This method accepts the name of the library in a string as input. Remember from Section 9.3 that a Compile object is a target object that you declare in your build script.\nWhen you link a particular target object with a system’s library, the zig compiler will use pkg-config to find where are the binary files and also the header files of this library in your system. When it finds these files, the linker present in the zig compiler will link your object files with the files of this library to produce a single binary file for you.\nIn the example below, we are creating an executable file named image_filter, and, we are linking this executable file to the C Standard Library with the method linkLibC(), but we also are linking this executable file to the C library libpng that is currently installed in my system.\n\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"image_filter\",\n        .root_source_file = b.path(\"src/main.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n    exe.linkLibC();\n    exe.linkSystemLibrary(\"png\");\n    b.installArtifact(exe);\n}\n\nIf you are linking with a C library in your project, is generally a good idea to also link your code with the C Standard Library. Because is very likely that this C library uses some functionality of the C Standard Library at some point. The same goes to C++ libraries. So, if you are linking with C++ libraries, is a good idea to link your project with the C++ Standard Library by using the linkLibCpp() method.\nOn the order side, when you want to link with a local library, you should use the linkLibrary() method of a Compile object. This method expects to receive another Compile object as input. That is, another target object defined in your build script, using either the addStaticLibrary() or addSharedLibrary() methods which defines a library to be built.\nAs we discussed earlier, a local library is a library that is local to your project, and that is being built together with your project. So, you need to create a target object in your build script to build this local library. Then, you link the target objects of interest in your project, with this target object that identifies this local library.\nTake a look at this example extracted from the build script of the libxev library8. You can see in this snippet that we are declaring a shared library file, from the c_api.zig module. Then, later in the build script, we declare an executable file named \"dynamic-binding-test\", which links to this shared library that we defined earlier in the script.\n\nconst optimize = b.standardOptimizeOption(.{});\nconst target = b.standardTargetOptions(.{});\n\nconst dynamic_lib = b.addSharedLibrary(.{\n    .name = dynamic_lib_name,\n    .root_source_file = b.path(\"src/c_api.zig\"),\n    .target = target,\n    .optimize = optimize,\n});\nb.installArtifact(dynamic_lib);\n// ... more lines in the script\nconst dynamic_binding_test = b.addExecutable(.{\n    .name = \"dynamic-binding-test\",\n    .target = target,\n    .optimize = optimize,\n});\ndynamic_binding_test.linkLibrary(dynamic_lib);",
+    "text": "9.10 Linking to external libraries\nOne essential part of every build process is the linking stage. This stage is responsible for combining the multiple object files that represent your code, into a single executable file. It also links this executable file to external libraries, if you use any in your code.\nIn Zig, we have two notions of a “library”, which are: 1) a system’s library; 2) a local library. A system’s library is just a library that is already installed in your system. While a local library is a library that belongs to the current project; a library that is present in your project directory, and that you are building together with your project source code.\nThe basic difference between the two, is that a system’s library is already built and installed in your system, supposedly, and all you need to do is to link your source code to this library to start using it. We do that by using the linkSystemLibrary() method from a Compile object. This method accepts the name of the library in a string as input. Remember from Section 9.3 that a Compile object is a target object that you declare in your build script.\nWhen you link a particular target object with a system’s library, the zig compiler will use pkg-config to find where are the binary files and also the header files of this library in your system. When it finds these files, the linker present in the zig compiler will link your object files with the files of this library to produce a single binary file for you.\nIn the example below, we are creating an executable file named image_filter, and, we are linking this executable file to the C Standard Library with the method linkLibC(), but we also are linking this executable file to the C library libpng that is currently installed in my system.\n\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"image_filter\",\n        .root_source_file = b.path(\"src/main.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n    exe.linkLibC();\n    exe.linkSystemLibrary(\"png\");\n    b.installArtifact(exe);\n}\n\nIf you are linking with a C library in your project, is generally a good idea to also link your code with the C Standard Library. Because is very likely that this C library uses some functionality of the C Standard Library at some point. The same goes to C++ libraries. So, if you are linking with C++ libraries, is a good idea to link your project with the C++ Standard Library by using the linkLibCpp() method.\nOn the order side, when you want to link with a local library, you should use the linkLibrary() method of a Compile object. This method expects to receive another Compile object as input. That is, another target object defined in your build script, using either the addStaticLibrary() or addSharedLibrary() methods which defines a library to be built.\nAs we discussed earlier, a local library is a library that is local to your project, and that is being built together with your project. So, you need to create a target object in your build script to build this local library. Then, you link the target objects of interest in your project, with this target object that identifies this local library.\nTake a look at this example extracted from the build script of the libxev library8. You can see in this snippet that we are declaring a shared library file, from the c_api.zig module. Then, later in the build script, we declare an executable file named \"dynamic-binding-test\", which links to this shared library that we defined earlier in the script.\n\nconst optimize = b.standardOptimizeOption(.{});\nconst target = b.standardTargetOptions(.{});\n\nconst dynamic_lib = b.addSharedLibrary(.{\n    .name = dynamic_lib_name,\n    .root_source_file = b.path(\"src/c_api.zig\"),\n    .target = target,\n    .optimize = optimize,\n});\nb.installArtifact(dynamic_lib);\n// ... more lines in the script\nconst dynamic_binding_test = b.addExecutable(.{\n    .name = \"dynamic-binding-test\",\n    .target = target,\n    .optimize = optimize,\n});\ndynamic_binding_test.linkLibrary(dynamic_lib);",
     "crumbs": [
       "<span class='chapter-number'>9</span>  <span class='chapter-title'>Build System</span>"
     ]
@@ -804,7 +804,7 @@
     "href": "Chapters/07-build-system.html#sec-building-c-code",
     "title": "9  Build System",
     "section": "9.11 Building C code",
-    "text": "9.11 Building C code\nThe zig compiler comes with a C compiler embedded in it. In other words, you can use the zig compiler to build C projects. This C compiler is available through the cc command of the zig compiler.\nAs an example, let’s use the famous FreeType library9. FreeType is one of the most widely used pieces of software in the world. It is a C library designed to produce high-quality fonts. But it is also heavily used in the industry to natively render text and fonts in the screen of your computer.\nIn this section, we are going to write a build script, piece by piece, that is capable of building the FreeType project from source. You can find the source code of this build script on the freetype-zig repository10 available at GitHub.\nAfter you download the source code of FreeType from the official website11, you can start writing the build.zig module. We begin by defining the target object that defines the binary file that we want to compile.\nAs an example, I will build the project as a static library file using the addStaticLibrary() method to create the target object. Also, since FreeType is a C library, I will also link the library against libc through the linkLibC() method, to guarantee that any use of the C Standard Library is covered in the compilation process.\n\nconst target = b.standardTargetOptions(.{});\nconst opti = b.standardOptimizeOption(.{});\nconst lib = b.addStaticLibrary(.{\n    .name = \"freetype\",\n    .optimize = opti,\n    .target = target,\n});\nlib.linkLibC();\n\n\n9.11.1 Creating C compiler flags\nCompiler flags are also known as “compiler options” by many programmers, or also, as “command options” in the GCC official documentation. It’s fair to also call them as the “command-line arguments” of the C compiler. In general, we use compiler flags to turn on (or turn off) some features from the compiler, or to tweak the compilation process to fit the needs of our project.\nIn build scripts written in Zig, we normally list the C compiler flags to be used in the compilation process in a simple array, like in the example below.\n\nconst c_flags = [_][]const u8{\n    \"-Wall\",\n    \"-Wextra\",\n    \"-Werror\",\n};\n\nIn theory, there is nothing stopping you from using this array to add “include paths” (with the -I flag) or “library paths” (with the -L flag) to the compilation process. But there are formal ways in Zig to add these types of paths in the compilation process. Both are discussed at Section 9.11.5 and Section 9.11.4.\nAnyway, in Zig, we add C flags to the build process together with the C files that we want to compile, by using the addCSourceFile() and addCSourceFiles() methods. In the example above, we have just declared the C flags that we want to use. But we haven’t added them to the build process yet. To do that, we also need to list the C files to be compiled.\n\n\n9.11.2 Listing your C files\nThe C files that contains “cross-platform” source code are listed in the c_source_files object below. These are the C files that are included by default in every platform supported by the FreeType library. Now, since the amount of C files in the FreeType library is big, I have omitted the rest of the files in the code example below, for brevity purposes.\n\nconst c_source_files = [_][]const u8{\n    \"src/autofit/autofit.c\",\n    \"src/base/ftbase.c\",\n    // ... and many other C files.\n};\n\nNow, in addition to “cross-platform” source code, we also have some C files in the FreeType project that are platform-specific, meaning that, they contain source code that can only be compiled in specific platforms, and, as a result, they are only included in the build process on these specific target platforms. The objects that list these C files are exposed in the code example below.\n\nconst windows_c_source_files = [_][]const u8{\n    \"builds/windows/ftdebug.c\",\n    \"builds/windows/ftsystem.c\"\n};\nconst linux_c_source_files = [_][]const u8{\n    \"src/base/ftsystem.c\",\n    \"src/base/ftdebug.c\"\n};\n\nNow that we declared both the files that we want to include and the C compiler flags to be used, we can add them to the target object that describes the FreeType library, by using the addCSourceFile() and addCSourceFiles() methods.\nBoth of these functions are methods from a Compile object (i.e. a target object). The addCSourceFile() method is capable of adding a single C file to the target object, while the addCSourceFiles() method is used to add multiple C files in a single command. You might prefer to use addCSourceFile() when you need to use different compiler flags on specific C files in your project. But, if you can use the same compiler flags across all C files, then, you will probably find addCSourceFiles() a better choice.\nNotice that we are using the addCSourceFiles() method in the example below, to add both the C files and the C compiler flags. Also notice that we are using the os.tag that we learned about at Section 9.6, to add the platform-specific C files.\n\nconst builtin = @import(\"builtin\");\nlib.addCSourceFiles(\n    &c_source_files, &c_flags\n);\n\nswitch (builtin.target.os.tag) {\n    .windows =&gt; {\n        lib.addCSourceFiles(\n            &windows_c_source_files,\n            &c_flags\n        );\n    },\n    .linux =&gt; {\n        lib.addCSourceFiles(\n            &linux_c_source_files,\n            &c_flags\n        );\n    },\n    else =&gt; {},\n}\n\n\n\n9.11.3 Defining C Macros\nC Macros are an essential part of the C programming language, and they are commonly defined through the -D flag from a C compiler. In Zig, you can define a C Macro to be used in your build process by using the defineCMacro() method from the target object that defines the binary file that you are building.\nIn the example below, we are using the lib object that we have defined on the previous sections to define some C Macros used by the FreeType project in the compilation process. These C Macros specify if FreeType should (or should not) include functionalities from different external libraries.\n\nlib.defineCMacro(\"FT_DISABLE_ZLIB\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_PNG\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_HARFBUZZ\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BZIP2\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BROTLI\", \"TRUE\");\nlib.defineCMacro(\"FT2_BUILD_LIBRARY\", \"TRUE\");\n\n\n\n9.11.4 Adding library paths\nLibrary paths are paths in your computer where the C compiler will look (or search) for library files to link against your source code. In other words, when you use a library in your C source code, and you ask the C compiler to link your source code against this library, the C compiler will search for the binary files of this library across the paths listed in this “library paths” set.\nThese paths are platform specific, and, by default, the C compiler starts by looking at a pre-defined set of places in your computer. But you can add more paths (or more places) to this list. For example, you may have a library installed in a non-conventional place of your computer, and you can make the C compiler “see” this “non-conventional place” by adding this path to this list of pre-defined paths.\nIn Zig, you can add more paths to this set by using the addLibraryPath() method from your target object. First, you defined a LazyPath object, containing the path you want to add, then, you provide this object as input to the addLibraryPath() method, like in the example below:\n\nconst lib_path: std.Build.LazyPath = .{\n    .cwd_relative = \"/usr/local/lib/\"\n};\nlib.addLibraryPath(lib_path);\n\n\n\n9.11.5 Adding include paths\nThe preprocessor search path is a popular concept from the C community, but it is also known by many C programmers as “include paths”, because the paths in this “search path” relate to the #include statements found in the C files.\nInclude paths are similar to library paths. They are a set of pre-defined places in your computer where the C compiler will look for files during the compilation process. But instead of looking for library files, the include paths are places where the compiler looks for header files included in your C source code. This is why many C programmers prefer to call these paths as the “preprocessor search path”. Because header files are processed during the preprocessor stage of the compilation process.\nSo, every header file that you include in your C source code, through a #include statements needs to be found somewhere, and the C compiler will search for this header file across the paths listed in this “include paths” set. Include paths are added to the compilation process through the -I flag.\nIn Zig, you can add new paths to this pre-defined set of paths, by using the addIncludePath() method from your target object. This method also accepts a LazyPath object as input.\n\nconst inc_path: std.Build.LazyPath = .{\n    .path = \"./include\"\n};\nlib.addIncludePath(inc_path);",
+    "text": "9.11 Building C code\nThe zig compiler comes with a C compiler embedded in it. In other words, you can use the zig compiler to build C projects. This C compiler is available through the cc command of the zig compiler.\nAs an example, let’s use the famous FreeType library9. FreeType is one of the most widely used pieces of software in the world. It’s a C library designed to produce high-quality fonts. But it’s also heavily used in the industry to natively render text and fonts in the screen of your computer.\nIn this section, we are going to write a build script, piece by piece, that is capable of building the FreeType project from source. You can find the source code of this build script on the freetype-zig repository10 available at GitHub.\nAfter you download the source code of FreeType from the official website11, you can start writing the build.zig module. We begin by defining the target object that defines the binary file that we want to compile.\nAs an example, I will build the project as a static library file using the addStaticLibrary() method to create the target object. Also, since FreeType is a C library, I will also link the library against libc through the linkLibC() method, to guarantee that any use of the C Standard Library is covered in the compilation process.\n\nconst target = b.standardTargetOptions(.{});\nconst opti = b.standardOptimizeOption(.{});\nconst lib = b.addStaticLibrary(.{\n    .name = \"freetype\",\n    .optimize = opti,\n    .target = target,\n});\nlib.linkLibC();\n\n\n9.11.1 Creating C compiler flags\nCompiler flags are also known as “compiler options” by many programmers, or also, as “command options” in the GCC official documentation. It’s fair to also call them as the “command-line arguments” of the C compiler. In general, we use compiler flags to turn on (or turn off) some features from the compiler, or to tweak the compilation process to fit the needs of our project.\nIn build scripts written in Zig, we normally list the C compiler flags to be used in the compilation process in a simple array, like in the example below.\n\nconst c_flags = [_][]const u8{\n    \"-Wall\",\n    \"-Wextra\",\n    \"-Werror\",\n};\n\nIn theory, there is nothing stopping you from using this array to add “include paths” (with the -I flag) or “library paths” (with the -L flag) to the compilation process. But there are formal ways in Zig to add these types of paths in the compilation process. Both are discussed in Section 9.11.5 and Section 9.11.4.\nAnyway, in Zig, we add C flags to the build process together with the C files that we want to compile, by using the addCSourceFile() and addCSourceFiles() methods. In the example above, we have just declared the C flags that we want to use. But we haven’t added them to the build process yet. To do that, we also need to list the C files to be compiled.\n\n\n9.11.2 Listing your C files\nThe C files that contains “cross-platform” source code are listed in the c_source_files object below. These are the C files that are included by default in every platform supported by the FreeType library. Now, since the amount of C files in the FreeType library is big, I have omitted the rest of the files in the code example below, for brevity purposes.\n\nconst c_source_files = [_][]const u8{\n    \"src/autofit/autofit.c\",\n    \"src/base/ftbase.c\",\n    // ... and many other C files.\n};\n\nNow, in addition to “cross-platform” source code, we also have some C files in the FreeType project that are platform-specific, meaning that, they contain source code that can only be compiled in specific platforms, and, as a result, they are only included in the build process on these specific target platforms. The objects that list these C files are exposed in the code example below.\n\nconst windows_c_source_files = [_][]const u8{\n    \"builds/windows/ftdebug.c\",\n    \"builds/windows/ftsystem.c\"\n};\nconst linux_c_source_files = [_][]const u8{\n    \"src/base/ftsystem.c\",\n    \"src/base/ftdebug.c\"\n};\n\nNow that we declared both the files that we want to include and the C compiler flags to be used, we can add them to the target object that describes the FreeType library, by using the addCSourceFile() and addCSourceFiles() methods.\nBoth of these functions are methods from a Compile object (i.e., a target object). The addCSourceFile() method is capable of adding a single C file to the target object, while the addCSourceFiles() method is used to add multiple C files in a single command. You might prefer to use addCSourceFile() when you need to use different compiler flags on specific C files in your project. But, if you can use the same compiler flags across all C files, then, you will probably find addCSourceFiles() a better choice.\nNotice that we are using the addCSourceFiles() method in the example below, to add both the C files and the C compiler flags. Also notice that we are using the os.tag that we learned about in Section 9.6, to add the platform-specific C files.\n\nconst builtin = @import(\"builtin\");\nlib.addCSourceFiles(\n    &c_source_files, &c_flags\n);\n\nswitch (builtin.target.os.tag) {\n    .windows =&gt; {\n        lib.addCSourceFiles(\n            &windows_c_source_files,\n            &c_flags\n        );\n    },\n    .linux =&gt; {\n        lib.addCSourceFiles(\n            &linux_c_source_files,\n            &c_flags\n        );\n    },\n    else =&gt; {},\n}\n\n\n\n9.11.3 Defining C Macros\nC Macros are an essential part of the C programming language, and they are commonly defined through the -D flag from a C compiler. In Zig, you can define a C Macro to be used in your build process by using the defineCMacro() method from the target object that defines the binary file that you are building.\nIn the example below, we are using the lib object that we have defined in the previous sections to define some C Macros used by the FreeType project in the compilation process. These C Macros specify if FreeType should (or should not) include functionalities from different external libraries.\n\nlib.defineCMacro(\"FT_DISABLE_ZLIB\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_PNG\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_HARFBUZZ\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BZIP2\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BROTLI\", \"TRUE\");\nlib.defineCMacro(\"FT2_BUILD_LIBRARY\", \"TRUE\");\n\n\n\n9.11.4 Adding library paths\nLibrary paths are paths in your computer where the C compiler will look (or search) for library files to link against your source code. In other words, when you use a library in your C source code, and you ask the C compiler to link your source code against this library, the C compiler will search for the binary files of this library across the paths listed in this “library paths” set.\nThese paths are platform specific, and, by default, the C compiler starts by looking at a pre-defined set of places in your computer. But you can add more paths (or more places) to this list. For example, you may have a library installed in a non-conventional place of your computer, and you can make the C compiler “see” this “non-conventional place” by adding this path to this list of pre-defined paths.\nIn Zig, you can add more paths to this set by using the addLibraryPath() method from your target object. First, you defined a LazyPath object, containing the path you want to add, then, you provide this object as input to the addLibraryPath() method, like in the example below:\n\nconst lib_path: std.Build.LazyPath = .{\n    .cwd_relative = \"/usr/local/lib/\"\n};\nlib.addLibraryPath(lib_path);\n\n\n\n9.11.5 Adding include paths\nThe preprocessor search path is a popular concept from the C community, but it’s also known by many C programmers as “include paths”, because the paths in this “search path” relate to the #include statements found in the C files.\nInclude paths are similar to library paths. They are a set of pre-defined places in your computer where the C compiler will look for files during the compilation process. But instead of looking for library files, the include paths are places where the compiler looks for header files included in your C source code. This is why many C programmers prefer to call these paths as the “preprocessor search path”. Because header files are processed during the preprocessor stage of the compilation process.\nSo, every header file that you include in your C source code, through a #include statements needs to be found somewhere, and the C compiler will search for this header file across the paths listed in this “include paths” set. Include paths are added to the compilation process through the -I flag.\nIn Zig, you can add new paths to this pre-defined set of paths, by using the addIncludePath() method from your target object. This method also accepts a LazyPath object as input.\n\nconst inc_path: std.Build.LazyPath = .{\n    .path = \"./include\"\n};\nlib.addIncludePath(inc_path);",
     "crumbs": [
       "<span class='chapter-number'>9</span>  <span class='chapter-title'>Build System</span>"
     ]
@@ -834,7 +834,7 @@
     "href": "Chapters/09-error-handling.html#learning-more-about-errors-in-zig",
     "title": "10  Error handling and unions",
     "section": "",
-    "text": "t.zig:8:17: error: error set is discarded\nt.zig:8:17: note: consider using 'try', 'catch', or 'if'\n\n10.1.1 Returning errors from functions\nAs we described at Section 1.2.3, when we have a function that might return an error value, this function normally includes an exclamation mark (!) in its return type annotation. The presence of this exclamation mark indicates that this function might return an error value as result, and, the zig compiler forces you to always handle explicitly the case of this function returning an error value.\nTake a look at the print_name() function below. This function might return an error in the stdout.print() function call, and, as a consequence, its return type (!void) includes an exclamation mark in it.\n\nfn print_name() !void {\n    const stdout = std.getStdOut().writer();\n    try stdout.print(\"My name is Pedro!\", .{});\n}\n\nIn the example above, we are using the exclamation mark to tell the zig compiler that this function might return some error. But which error exactly is returned from this function? For now, we are not specifying a specific error value. We only known for now that some error value (whatever it is) might be returned.\nBut in fact, you can (if you want to) specify clearly which exact error values might be returned from this function. There are lot of examples of this in the Zig Standard Library. Take this fill() function from the http.Client module as an example. This function returns either a error value of type ReadError, or void.\n\npub fn fill(conn: *Connection) ReadError!void {\n    // The body of this function ...\n}\n\nThis idea of specifying the exact error values that you expect to be returned from the function is interesting. Because they automatically become some sort of documentation of your function, and also, it allows the zig compiler to perform some extra checks over your code. Because it can check if there is any other type of error value that is being generated inside your function, and, that it is not being accounted for in this return type annotation.\nAnyway, you can list the types of errors that can be returned from the function by listing them on the left side of the exclamation mark. While the valid values stay on the right side of the exclamation mark. So the syntax format become:\n&lt;error-value&gt;!&lt;valid-value&gt;\n\n\n10.1.2 Error sets\nBut what about when we have a single function that might return different types of errors? When you have such a function, you can list all of these different types of errors that can be returned from this function, through a structure in Zig that we call of an error set.\nAn error set is a special case of an union type. It is an union that contains error values in it. Not all programming languages have a notion of an “union object”. But in summary, an union is just a set of data types. Unions are used to allow an object to have multiple data types. For example, a union of x, y and z, means that an object can be either of type x, or type y or type z.\nWe are going to talk in more depth about unions at Section 10.3. But you can write an error set by writing the keyword error before a pair of curly braces, then you list the error values that can be returned from the function inside this pair of curly braces.\nTake the resolvePath() function below as an example, which comes from the introspect.zig module of the Zig Standard Library. We can see in its return type annotation, that this function return either: 1) a valid slice of u8 values ([]u8); or, 2) one of the three different types of error values listed inside the error set (OutOfMemory, Unexpected, etc.). This is an usage example of an error set.\n\npub fn resolvePath(\n    ally: mem.Allocator,\n    p: []const u8,\n) error{\n    OutOfMemory,\n    CurrentWorkingDirectoryUnlinked,\n    Unexpected,\n}![]u8 {\n    // The body of the function ...\n}\n\nThis is a valid way of annotating the return value of a Zig function. But, if you navigate through the modules that composes the Zig Standard Library, you will notice that, for the majority of cases, the programmers prefer to give a descriptive name to this error set, and then, use this name (or this “label”) of the error set in the return type annotation, instead of using the error set directly.\nWe can see that in the ReadError error set that we showed earlier in the fill() function, which is defined in the http.Client module. So yes, I presented the ReadError as if it was just a standard and single error value, but in fact, it is an error set defined in the http.Client module, and therefore, it actually represents a set of different error values that might happen inside the fill() function.\nTake a look at the ReadError definition reproduced below. Notice that we are grouping all of these different error values into a single object, and then, we use this object into the return type annotation of the function. Like the fill() function that we showed earlier, or, the readvDirect() function from the same module, which is reproduced below.\n\npub const ReadError = error{\n    TlsFailure,\n    TlsAlert,\n    ConnectionTimedOut,\n    ConnectionResetByPeer,\n    UnexpectedReadFailure,\n    EndOfStream,\n};\n// Some lines of code\npub fn readvDirect(\n        conn: *Connection,\n        buffers: []std.posix.iovec\n    ) ReadError!usize {\n    // The body of the function ...\n}\n\nSo, an error set is just a convenient way of grouping a set of possible error values into a single object, or a single type of an error value.\n\n\n10.1.3 Casting error values\nLet’s suppose you have two different error sets, named A and B. If error set A is a superset of error set B, then, you can cast (or coerce) error values from B into error values of A.\nError sets are just a set of error values. So, if the error set A contains all error values from the error set B, then A becomes a superset of B. You could also say that the error set B is a subset of error set A.\nThe example below demonstrates this idea. Because A contains all values from B, A is a superset of B. In math notation, we would say that \\(A \\supset B\\). As a consequence, we can give an error value from B as input to the cast() function, and, implicitly cast this input into the same error value, but from the A set.\n\nconst std = @import(\"std\");\nconst A = error{\n    ConnectionTimeoutError,\n    DatabaseNotFound,\n    OutOfMemory,\n    InvalidToken,\n};\nconst B = error {\n    OutOfMemory,\n};\n\nfn cast(err: B) A {\n    return err;\n}\n\ntest \"coerce error value\" {\n    const error_value = cast(B.OutOfMemory);\n    try std.testing.expect(\n        error_value == A.OutOfMemory\n    );\n}\n\n1/1 filea64e1da1167c.test.coerce error value...OKA\n  All 1 tests passed.",
+    "text": "t.zig:8:17: error: error set is discarded\nt.zig:8:17: note: consider using 'try', 'catch', or 'if'\n\n10.1.1 Returning errors from functions\nAs we described in Section 1.2.3, when we have a function that might return an error value, this function normally includes an exclamation mark (!) in its return type annotation. The presence of this exclamation mark indicates that this function might return an error value as result, and, the zig compiler forces you to always handle explicitly the case of this function returning an error value.\nTake a look at the print_name() function below. This function might return an error in the stdout.print() function call, and, as a consequence, its return type (!void) includes an exclamation mark in it.\n\nfn print_name() !void {\n    const stdout = std.getStdOut().writer();\n    try stdout.print(\"My name is Pedro!\", .{});\n}\n\nIn the example above, we are using the exclamation mark to tell the zig compiler that this function might return some error. But which error exactly is returned from this function? For now, we are not specifying a specific error value. For now, we only know that some error value (whatever it is) might be returned.\nBut in fact, you can (if you want to) specify clearly which exact error values might be returned from this function. There are lot of examples of this in the Zig Standard Library. Take this fill() function from the http.Client module as an example. This function returns either a error value of type ReadError, or void.\n\npub fn fill(conn: *Connection) ReadError!void {\n    // The body of this function ...\n}\n\nThis idea of specifying the exact error values that you expect to be returned from the function is interesting. Because they automatically become some sort of documentation of your function, and also, this allows the zig compiler to perform some extra checks over your code. Because the compiler can check if there is any other type of error value that is being generated inside your function, and, that it’s not being accounted for in this return type annotation.\nAnyway, you can list the types of errors that can be returned from the function by listing them on the left side of the exclamation mark. While the valid values stay on the right side of the exclamation mark. So the syntax format become:\n&lt;error-value&gt;!&lt;valid-value&gt;\n\n\n10.1.2 Error sets\nBut what about when we have a single function that might return different types of errors? When you have such a function, you can list all of these different types of errors that can be returned from this function, through a structure in Zig that we call of an error set.\nAn error set is a special case of a union type. It’s a union that contains error values in it. Not all programming languages have a notion of a “union object”. But in summary, a union is just a set of data types. Unions are used to allow an object to have multiple data types. For example, a union of x, y and z, means that an object can be either of type x, or type y or type z.\nWe are going to talk in more depth about unions in Section 10.3. But you can write an error set by writing the keyword error before a pair of curly braces, then you list the error values that can be returned from the function inside this pair of curly braces.\nTake the resolvePath() function below as an example, which comes from the introspect.zig module of the Zig Standard Library. We can see in its return type annotation, that this function return either: 1) a valid slice of u8 values ([]u8); or, 2) one of the three different types of error values listed inside the error set (OutOfMemory, Unexpected, etc.). This is an usage example of an error set.\n\npub fn resolvePath(\n    ally: mem.Allocator,\n    p: []const u8,\n) error{\n    OutOfMemory,\n    CurrentWorkingDirectoryUnlinked,\n    Unexpected,\n}![]u8 {\n    // The body of the function ...\n}\n\nThis is a valid way of annotating the return value of a Zig function. But, if you navigate through the modules that composes the Zig Standard Library, you will notice that, for the majority of cases, the programmers prefer to give a descriptive name to this error set, and then, use this name (or this “label”) of the error set in the return type annotation, instead of using the error set directly.\nWe can see that in the ReadError error set that we showed earlier in the fill() function, which is defined in the http.Client module. So yes, I presented the ReadError as if it was just a standard and single error value, but in fact, it’s an error set defined in the http.Client module, and therefore, it actually represents a set of different error values that might happen inside the fill() function.\nTake a look at the ReadError definition reproduced below. Notice that we are grouping all of these different error values into a single object, and then, we use this object into the return type annotation of the function. Like the fill() function that we showed earlier, or, the readvDirect() function from the same module, which is reproduced below.\n\npub const ReadError = error{\n    TlsFailure,\n    TlsAlert,\n    ConnectionTimedOut,\n    ConnectionResetByPeer,\n    UnexpectedReadFailure,\n    EndOfStream,\n};\n// Some lines of code\npub fn readvDirect(\n        conn: *Connection,\n        buffers: []std.posix.iovec\n    ) ReadError!usize {\n    // The body of the function ...\n}\n\nSo, an error set is just a convenient way of grouping a set of possible error values into a single object, or a single type of an error value.\n\n\n10.1.3 Casting error values\nLet’s suppose you have two different error sets, named A and B. If error set A is a superset of error set B, then, you can cast (or coerce) error values from B into error values of A.\nError sets are just a set of error values. So, if the error set A contains all error values from the error set B, then A becomes a superset of B. You could also say that the error set B is a subset of error set A.\nThe example below demonstrates this idea. Because A contains all values from B, A is a superset of B. In math notation, we would say that \\(A \\supset B\\). As a consequence, we can give an error value from B as input to the cast() function, and, implicitly cast this input into the same error value, but from the A set.\n\nconst std = @import(\"std\");\nconst A = error{\n    ConnectionTimeoutError,\n    DatabaseNotFound,\n    OutOfMemory,\n    InvalidToken,\n};\nconst B = error {\n    OutOfMemory,\n};\n\nfn cast(err: B) A {\n    return err;\n}\n\ntest \"coerce error value\" {\n    const error_value = cast(B.OutOfMemory);\n    try std.testing.expect(\n        error_value == A.OutOfMemory\n    );\n}\n\n1/1 file826379a872a1.test.coerce error value...OKA\n  All 1 tests passed.",
     "crumbs": [
       "<span class='chapter-number'>10</span>  <span class='chapter-title'>Error handling and unions</span>"
     ]
@@ -844,7 +844,7 @@
     "href": "Chapters/09-error-handling.html#how-to-handle-errors",
     "title": "10  Error handling and unions",
     "section": "10.2 How to handle errors",
-    "text": "10.2 How to handle errors\nNow that we learned more about what errors are in Zig, let’s discuss the available strategies to handle these errors, which are:\n\ntry keyword;\ncatch keyword;\nan if statement;\nerrdefer keyword;\n\n\n10.2.1 What try means?\nAs I described over the previous sections, when we say that an expression might return an error, we are basically referring to an expression that have a return type in the format !T. The ! indicates that this expression returns either an error value, or a value of type T.\nAt Section 1.2.3, I presented the try keyword and where to use it. But I did not talked about what exactly this keyword does to your code, or, in other words, I have not explained yet what try means in your code.\nIn essence, when you use the try keyword in an expression, you are telling the zig compiler the following: “Hey! Execute this expression for me, and, if this expression return an error, please, return this error for me and stop the execution of my program. But if this expression return a valid value, then, return this value, and move on”.\nIn other words, the try keyword is essentially, a strategy to enter in panic mode, and stop the execution of your program in case an error occurs. With the try keyword, you are telling the zig compiler, that stopping the execution of your program is the most reasonable strategy to take if an error occurs in that particular expression.\n\n\n10.2.2 The catch keyword\nOk, now that we understand properly what try means, let’s discuss catch now. One important detail here, is that you can use try or catch to handle your errors, but you cannot use try and catch together. In other words, try and catch are different and completely separate strategies in the Zig language.\nThis is uncommon, and different than what happens in other languages. Most programming languages that adopts the try catch pattern (such as C++, R, Python, Javascript, etc.), normally use these two keywords together to form the complete logic to properly handle the errors. Anyway, Zig tries a different approach in the try catch pattern.\nSo, we learned already about what try means, and we also known that both try and catch should be used alone, separate from each other. But what exactly catch do in Zig? With catch, we can construct a block of logic to handle the error value, in case it happens in the current expression.\nLook at the code example below. Once again, we go back to the previous example where we were trying to open a file that doesn’t exist in my computer, but this time, I use catch to actually implement a logic to handle the error, instead of just stopping the execution right away.\nMore specifically, in this example, I’m using a logger object to record some logs into the system, before I return the error, and stop the execution of the program. For example, this could be some part of the codebase of a complex system that I do not have full control over, and I want to record these logs before the program crashes, so that I can debug it later (e.g. maybe I cannot compile the full program, and properly debug it with a debugger. So, these logs might be a valid strategy to surpass this barrier).\n\nconst dir = std.fs.cwd();\nconst file = dir.openFile(\n    \"doesnt_exist.txt\", .{}\n) catch |err| {\n    logger.record_context();\n    logger.log_error(err);\n    return err;\n};\n\nTherefore, we use catch to create a block of expressions that will handle the error. I can return the error value from this block of expressions, like I did in the above example, which, will make the program enter in panic mode, and, stop the execution. But I could also, return a valid value from this block of code, which would be stored in the file object.\nNotice that, instead of writing the keyword before the expression that might return the error, like we do with try, we write catch after the expression. We can open the pair of pipes (|), which captures the error value returned by the expression, and makes this error value available in the scope of the catch block as the object named err. In other words, because I wrote |err| in the code, I can access the error value returned by the expression, by using the err object.\nAlthough this being the most common use of catch, you can also use this keyword to handle the error in a “default value” style. That is, if the expression returns an error, we use the default value instead. Otherwise, we use the valid value returned by the expression.\nThe Zig official language reference, provides a great example of this “default value” strategy with catch. This example is reproduced below. Notice that we are trying to parse some unsigned integer from a string object named str. In other words, this function is trying to transform an object of type []const u8 (i.e. an array of characters, a string, etc.) into an object of type u64.\nBut this parsing process done by the function parseU64() may fail, resulting in a runtime error. The catch keyword used in this example provides an alternative value (13) to be used in case this parseU64() function raises an error. So, the expression below essentially means: “Hey! Please, parse this string into a u64 for me, and store the results into the object number. But, if an error occurs, then, use the value 13 instead”.\n\nconst number = parseU64(str, 10) catch 13;\n\nSo, at the end of this process, the object number will contain either a u64 integer that was parsed successfully from the input string str, or, if an error occurs in the parsing process, it will contain the u64 value 13 that was provided by the catch keyword as the “default”, or, the “alternative” value.\n\n\n10.2.3 Using if statements\nNow, you can also use if statements to handle errors in your Zig code. In the example below, I’m reproducing the previous example, where we try to parse an integer value from an input string with a function named parseU64().\nWe execute the expression inside the “if”. If this expression returns an error value, the “if branch” (or, the “true branch”) of the if statement is not executed. But if this expression returns a valid value instead, then, this value is unwrapped into the number object.\nThis means that, if the parseU64() expression returns a valid value, this value becomes available inside the scope of this “if branch” (i.e. the “true branch”) through the object that we listed inside the pair of pipe character (|), which is the object number.\nIf an error occurs, we can use an “else branch” (or the “false branch”) of the if statement to handle the error. In the example below, we are using the else in the if statement to unwrap the error value (that was returned by parseU64()) into the err object, and handle the error.\n\nif (parseU64(str, 10)) |number| {\n    // do something with `number` here\n} else |err| {\n    // handle the error value.\n}\n\nNow, if the expression that you are executing returns different types of error values, and you want to take a different action in each of these types of error values, the try and catch keywords, and the if statement strategy, becomes limited.\nFor this type of situation, the official documentation of the language suggests the use of a switch statement together with an if statement (Zig Software Foundation 2024b). The basic idea is, to use the if statement to execute the expression, and use the “else branch” to pass the error value to a switch statement, where you define a different action for each type of error value that might be returned by the expression executed in the if statement.\nThe example below demonstrates this idea. We first try to add (or register) a set of tasks to a queue. If this “registration process” occurs well, we then try to distribute these tasks across the workers of our system. But if this “registration process” returns an error value, we then use a switch statement in the “else branch” to handle each possible error value.\n\nif (add_tasks_to_queue(&queue, tasks)) |_| {\n    distribute_tasks(&queue);\n} else |err| switch (err) {\n    error.InvalidTaskName =&gt; {\n        // do something\n    },\n    error.TimeoutTooBig =&gt; {\n        // do something\n    },\n    error.QueueNotFound =&gt; {\n        // do something\n    },\n    // and all the other error options ...\n}\n\n\n\n10.2.4 The errdefer keyword\nA common pattern in C programs in general, is to clean resources when an error occurs during the execution of the program. In other words, one common way to handle errors, is to perform “cleanup actions” before we exit our program. This guarantees that a runtime error does not make our program to leak resources of the system.\nThe errdefer keyword is a tool to perform such “cleanup actions” in hostile situations. This keyword is commonly used to clean (or to free) allocated resources, before the execution of our program get’s stopped because of an error value being generated.\nThe basic idea is to provide an expression to the errdefer keyword. Then, errdefer executes this expression if, and only if, an error occurs during the execution of the current scope. In the example below, we are using an allocator object (that we have presented at Section 3.3) to create a new User object. If we are successful in creating and registering this new user, this create_user() function will return this new User object as its return value.\nHowever, if for some reason, an error value is generated by some expression that is after the errdefer line, for example, in the db.add(user) expression, the expression registered by errdefer get’s executed before the error value is returned from the function, and before the program enters in panic mode and stops the current execution.\n\nfn create_user(db: Database, allocator: Allocator) !User {\n    const user = try allocator.create(User);\n    errdefer allocator.destroy(user);\n\n    // Register new user in the Database.\n    _ = try db.register_user(user);\n    return user;\n}\n\nBy using errdefer to destroy the user object that we have just created, we guarantee that the memory allocated for this user object get’s freed, before the execution of the program stops. Because if the expression try db.add(user) returns an error value, the execution of our program stops, and we lose all references and control over the memory that we have allocated for the user object. As a result, if we do not free the memory associated with the user object before the program stops, we cannot free this memory anymore. We simply lose our chance to do the right thing. That is why errdefer is essential in this situation.\nJust to state clearly the differences between defer and errdefer (which I described at Section 2.1.3 and Section 2.1.4), it might be worth to discuss the subject a bit further. You might still have the question “why use errdefer if we can use defer instead?” in your mind.\nAlthough being similar, the key difference between errdefer and defer keyword is when the provided expression get’s executed. The defer keyword always execute the provided expression at the end of the current scope, no matter how your code exits this scope. In contrast, errdefer executes the provided expression only when an error occurs in the current scope.\nThis becomes important if a resource that you allocate in the current scope get’s freed later in your code, in a different scope. The create_user() functions is an example of this. If you think closely about this function, you will notice that this function returns the user object as the result.\nIn other words, the allocated memory for the user object does not get freed inside the create_user() function, if it returns successfully. So, if an error does not occur inside this function, the user object is returned from the function, and probably, the code that runs after this create_user() function will be responsible for freeing the memory of the user object.\nBut what if an error occurs inside the create_user() function? What happens then? This would mean that the execution of your code would stop in this create_user() function, and, as a consequence, the code that runs after this create_user() function would simply not run, and, as a result, the memory of the user object would not be freed before your program stops.\nThis is the perfect scenario for errdefer. We use this keyword to guarantee that our program will free the allocated memory for the user object, even if an error occurs inside the create_user() function.\nIf you allocate and free some memory for an object inside the same scope, then, just use defer and be happy, i.e. errdefer have no use for you in such situation. But if you allocate some memory in a scope A, but you only free this memory later, in a scope B for example, then, errdefer becomes useful to avoid leaking memory in sketchy situations.",
+    "text": "10.2 How to handle errors\nNow that we learned more about what errors are in Zig, let’s discuss the available strategies to handle these errors, which are:\n\ntry keyword;\ncatch keyword;\nan if statement;\nerrdefer keyword;\n\n\n10.2.1 What try means?\nAs I described over the previous sections, when we say that an expression might return an error, we are basically referring to an expression that have a return type in the format !T. The ! indicates that this expression returns either an error value, or a value of type T.\nIn Section 1.2.3, I presented the try keyword and where to use it. But I did not talked about what exactly this keyword does to your code, or, in other words, I have not explained yet what try means in your code.\nIn essence, when you use the try keyword in an expression, you are telling the zig compiler the following: “Hey! Execute this expression for me, and, if this expression return an error, please, return this error for me and stop the execution of my program. But if this expression return a valid value, then, return this value, and move on”.\nIn other words, the try keyword is essentially, a strategy to enter in panic mode, and stop the execution of your program in case an error occurs. With the try keyword, you are telling the zig compiler, that stopping the execution of your program is the most reasonable strategy to take if an error occurs in that particular expression.\n\n\n10.2.2 The catch keyword\nOk, now that we understand properly what try means, let’s discuss catch now. One important detail here, is that you can use try or catch to handle your errors, but you cannot use try and catch together. In other words, try and catch are different and completely separate strategies in the Zig language.\nThis is uncommon, and different than what happens in other languages. Most programming languages that adopts the try catch pattern (such as C++, R, Python, Javascript, etc.), normally use these two keywords together to form the complete logic to properly handle the errors. Anyway, Zig tries a different approach in the try catch pattern.\nSo, we learned already about what try means, and we also known that both try and catch should be used alone, separate from each other. But what exactly catch do in Zig? With catch, we can construct a block of logic to handle the error value, in case it happens in the current expression.\nLook at the code example below. Once again, we go back to the previous example where we were trying to open a file that doesn’t exist in my computer, but this time, I use catch to actually implement a logic to handle the error, instead of just stopping the execution right away.\nMore specifically, in this example, I’m using a logger object to record some logs into the system, before I return the error, and stop the execution of the program. For example, this could be some part of the codebase of a complex system that I do not have full control over, and I want to record these logs before the program crashes, so that I can debug it later (e.g. maybe I cannot compile the full program, and properly debug it with a debugger. So, these logs might be a valid strategy to surpass this barrier).\n\nconst dir = std.fs.cwd();\nconst file = dir.openFile(\n    \"doesnt_exist.txt\", .{}\n) catch |err| {\n    logger.record_context();\n    logger.log_error(err);\n    return err;\n};\n\nTherefore, we use catch to create a block of expressions that will handle the error. I can return the error value from this block of expressions, like I did in the above example, which, will make the program enter in panic mode, and, stop the execution. But I could also, return a valid value from this block of code, which would be stored in the file object.\nNotice that, instead of writing the keyword before the expression that might return the error, like we do with try, we write catch after the expression. We can open the pair of pipes (|), which captures the error value returned by the expression, and makes this error value available in the scope of the catch block as the object named err. In other words, because I wrote |err| in the code, I can access the error value returned by the expression, by using the err object.\nAlthough this being the most common use of catch, you can also use this keyword to handle the error in a “default value” style. That is, if the expression returns an error, we use the default value instead. Otherwise, we use the valid value returned by the expression.\nThe Zig official language reference, provides a great example of this “default value” strategy with catch. This example is reproduced below. Notice that we are trying to parse some unsigned integer from a string object named str. In other words, this function is trying to transform an object of type []const u8 (i.e., an array of characters, a string, etc.) into an object of type u64.\nBut this parsing process done by the function parseU64() may fail, resulting in a runtime error. The catch keyword used in this example provides an alternative value (13) to be used in case this parseU64() function raises an error. So, the expression below essentially means: “Hey! Please, parse this string into a u64 for me, and store the results into the object number. But, if an error occurs, then, use the value 13 instead”.\n\nconst number = parseU64(str, 10) catch 13;\n\nSo, at the end of this process, the object number will contain either a u64 integer that was parsed successfully from the input string str, or, if an error occurs in the parsing process, it will contain the u64 value 13 that was provided by the catch keyword as the “default”, or, the “alternative” value.\n\n\n10.2.3 Using if statements\nNow, you can also use if statements to handle errors in your Zig code. In the example below, I’m reproducing the previous example, where we try to parse an integer value from an input string with a function named parseU64().\nWe execute the expression inside the “if”. If this expression returns an error value, the “if branch” (or, the “true branch”) of the if statement is not executed. But if this expression returns a valid value instead, then, this value is unwrapped into the number object.\nThis means that, if the parseU64() expression returns a valid value, this value becomes available inside the scope of this “if branch” (i.e., the “true branch”) through the object that we listed inside the pair of pipe character (|), which is the object number.\nIf an error occurs, we can use an “else branch” (or the “false branch”) of the if statement to handle the error. In the example below, we are using the else in the if statement to unwrap the error value (that was returned by parseU64()) into the err object, and handle the error.\n\nif (parseU64(str, 10)) |number| {\n    // do something with `number` here\n} else |err| {\n    // handle the error value.\n}\n\nNow, if the expression that you are executing returns different types of error values, and you want to take a different action in each of these types of error values, the try and catch keywords, and the if statement strategy, becomes limited.\nFor this type of situation, the official documentation of the language suggests the use of a switch statement together with an if statement (Zig Software Foundation 2024b). The basic idea is, to use the if statement to execute the expression, and use the “else branch” to pass the error value to a switch statement, where you define a different action for each type of error value that might be returned by the expression executed in the if statement.\nThe example below demonstrates this idea. We first try to add (or register) a set of tasks to a queue. If this “registration process” occurs well, we then try to distribute these tasks across the workers of our system. But if this “registration process” returns an error value, we then use a switch statement in the “else branch” to handle each possible error value.\n\nif (add_tasks_to_queue(&queue, tasks)) |_| {\n    distribute_tasks(&queue);\n} else |err| switch (err) {\n    error.InvalidTaskName =&gt; {\n        // do something\n    },\n    error.TimeoutTooBig =&gt; {\n        // do something\n    },\n    error.QueueNotFound =&gt; {\n        // do something\n    },\n    // and all the other error options ...\n}\n\n\n\n10.2.4 The errdefer keyword\nA common pattern in C programs in general, is to clean resources when an error occurs during the execution of the program. In other words, one common way to handle errors, is to perform “cleanup actions” before we exit our program. This guarantees that a runtime error does not make our program to leak resources of the system.\nThe errdefer keyword is a tool to perform such “cleanup actions” in hostile situations. This keyword is commonly used to clean (or to free) allocated resources, before the execution of our program gets stopped because of an error value being generated.\nThe basic idea is to provide an expression to the errdefer keyword. Then, errdefer executes this expression if, and only if, an error occurs during the execution of the current scope. In the example below, we are using an allocator object (that we have presented in Section 3.3) to create a new User object. If we are successful in creating and registering this new user, this create_user() function will return this new User object as its return value.\nHowever, if for some reason, an error value is generated by some expression that is after the errdefer line, for example, in the db.add(user) expression, the expression registered by errdefer gets executed before the error value is returned from the function, and before the program enters in panic mode and stops the current execution.\n\nfn create_user(db: Database, allocator: Allocator) !User {\n    const user = try allocator.create(User);\n    errdefer allocator.destroy(user);\n\n    // Register new user in the Database.\n    _ = try db.register_user(user);\n    return user;\n}\n\nBy using errdefer to destroy the user object that we have just created, we guarantee that the memory allocated for this user object gets freed, before the execution of the program stops. Because if the expression try db.add(user) returns an error value, the execution of our program stops, and we lose all references and control over the memory that we have allocated for the user object. As a result, if we do not free the memory associated with the user object before the program stops, we cannot free this memory anymore. We simply lose our chance to do the right thing. That is why errdefer is essential in this situation.\nJust to state clearly the differences between defer and errdefer (which I described in Section 2.1.3 and Section 2.1.4), it might be worth to discuss the subject a bit further. You might still have the question “why use errdefer if we can use defer instead?” in your mind.\nAlthough being similar, the key difference between errdefer and defer keyword is when the provided expression gets executed. The defer keyword always execute the provided expression at the end of the current scope, no matter how your code exits this scope. In contrast, errdefer executes the provided expression only when an error occurs in the current scope.\nThis becomes important if a resource that you allocate in the current scope gets freed later in your code, in a different scope. The create_user() functions is an example of this. If you think closely about this function, you will notice that this function returns the user object as the result.\nIn other words, the allocated memory for the user object does not get freed inside the create_user() function, if it returns successfully. So, if an error does not occur inside this function, the user object is returned from the function, and probably, the code that runs after this create_user() function will be responsible for freeing the memory of the user object.\nBut what if an error occurs inside the create_user() function? What happens then? This would mean that the execution of your code would stop in this create_user() function, and, as a consequence, the code that runs after this create_user() function would simply not run, and, as a result, the memory of the user object would not be freed before your program stops.\nThis is the perfect scenario for errdefer. We use this keyword to guarantee that our program will free the allocated memory for the user object, even if an error occurs inside the create_user() function.\nIf you allocate and free some memory for an object inside the same scope, then, just use defer and be happy, i.e., errdefer have no use for you in such situation. But if you allocate some memory in a scope A, but you only free this memory later, in a scope B for example, then, errdefer becomes useful to avoid leaking memory in sketchy situations.",
     "crumbs": [
       "<span class='chapter-number'>10</span>  <span class='chapter-title'>Error handling and unions</span>"
     ]
@@ -854,7 +854,7 @@
     "href": "Chapters/09-error-handling.html#sec-unions",
     "title": "10  Error handling and unions",
     "section": "10.3 Union type in Zig",
-    "text": "10.3 Union type in Zig\nAn union type defines a set of types that an object can be. It is like a list of options. Each option is a type that an object can assume. Therefore, unions in Zig have the same meaning, or, the same role as unions in C. They are used for the same purpose. You could also say that unions in Zig produces a similar effect to using typing.Union in Python1.\nFor example, you might be creating an API that sends data to a data lake, hosted in some private cloud infrastructure. Suppose you have created different structs in your codebase, to store the necessary information that you need, in order to connect to the services of each mainstream data lake service (Amazon S3, Azure Blob, etc.).\nNow, suppose you also have a function named send_event() that receives an event as input, and, a target data lake, and it sends the input event to the data lake specified in the target data lake argument. But this target data lake could be any of the three mainstream data lakes services (Amazon S3, Azure Blob, etc.). Here is where an union can help you.\nThe union LakeTarget defined below allows the lake_target argument of send_event() to be either an object of type AzureBlob, or type AmazonS3, or type GoogleGCP. This union allows the send_event() function to receive an object of any of these three types as input in the lake_target argument.\nRemember that each of these three types (AmazonS3, GoogleGCP and AzureBlob) are separate structs that we have defined in our source code. So, at first glance, they are separate data types in our source code. But is the union keyword that unifies them into a single data type called LakeTarget.\n\nconst LakeTarget = union {\n    azure: AzureBlob,\n    amazon: AmazonS3,\n    google: GoogleGCP,\n};\n\nfn send_event(\n    event: Event,\n    lake_target: LakeTarget\n) bool {\n    // body of the function ...\n}\n\nAn union definition is composed by a list of data members. Each data member is of a specific data type. In the example above, the LakeTarget union have three data members (azure, amazon, google). When you instantiate an object that uses an union type, you can only use one of its data members in this instantiation.\nYou could also interpret this as: only one data member of an union type can be activated at a time, the other data members remain deactivated and unaccessible. For example, if you create a LakeTarget object that uses the azure data member, you can no longer use or access the data members google or amazon. It is like if these other data members didn’t exist at all in the LakeTarget type.\nYou can see this logic in the example below. Notice that, we first instantiate the union object using the azure data member. As a result, this target object contains only the azure data member inside of it. Only this data member is active in this object. That is why the last line in this code example is invalid. Because we are trying to instantiate the data member google, which is currently inactive for this target object, and as a result, the program enters in panic mode warning us about this mistake through a loud error message.\n\nvar target = LakeTarget {\n    .azure = AzureBlob.init()\n};\n// Only the `azure` data member exist inside\n// the `target` object, and, as a result, this\n// line below is invalid:\ntarget.google = GoogleGCP.init();\n\nthread 2177312 panic: access of union field 'google' while\n    field 'azure' is active:\n    target.google = GoogleGCP.init();\n          ^\nSo, when you instantiate an union object, you must choose one of the data types (or, one of the data members) listed in the union type. In the example above, I choose to use the azure data member, and, as a result, all other data members were automatically deactivated, and you can no longer use them after you instantiate the object.\nYou can activate another data member by completely redefining the entire enum object. In the example below, I initially use the azure data member. But then, I redefine the target object to use a new LakeTarget object, which uses the google data member.\n\nvar target = LakeTarget {\n    .azure = AzureBlob.init()\n};\ntarget = LakeTarget {\n    .google = GoogleGCP.init()\n};\n\nA curious fact about union types, is that, at first, you cannot use them in switch statements (which were presented at Section 2.1.2). In other words, if you have an object of type LakeTarget for example, you cannot give this object as input to a switch statement.\nBut what if you really need to do so? What if you actually need to provide an “union object” to a switch statement? The answer to this question relies on another special type in Zig, which are the tagged unions. To create a tagged union, all you have to do is to add an enum type into your union declaration.\nAs an example of a tagged union in Zig, take the Registry type exposed below. This type comes from the grammar.zig module2 from the Zig repository. This union type lists different types of registries. But notice this time, the use of (enum) after the union keyword. This is what makes this union type a tagged union. By being a tagged union, an object of this Registry type can be used as input in a switch statement. This is all you have to do. Just add (enum) to your union declaration, and you can use it in switch statements.\n\npub const Registry = union(enum) {\n    core: CoreRegistry,\n    extension: ExtensionRegistry,\n};\n\n\n\n\n\nZig Software Foundation. 2024a. “In-Depth Overview.” Zig Software Foundation. https://ziglang.org/learn/overview/.\n\n\n———. 2024b. “Language Reference.” Zig Software Foundation. https://ziglang.org/documentation/master/.",
+    "text": "10.3 Union type in Zig\nA union type defines a set of types that an object can be. It’s like a list of options. Each option is a type that an object can assume. Therefore, unions in Zig have the same meaning, or, the same role as unions in C. They are used for the same purpose. You could also say that unions in Zig produces a similar effect to using typing.Union in Python1.\nFor example, you might be creating an API that sends data to a data lake, hosted in some private cloud infrastructure. Suppose you have created different structs in your codebase, to store the necessary information that you need, in order to connect to the services of each mainstream data lake service (Amazon S3, Azure Blob, etc.).\nNow, suppose you also have a function named send_event() that receives an event as input, and, a target data lake, and it sends the input event to the data lake specified in the target data lake argument. But this target data lake could be any of the three mainstream data lakes services (Amazon S3, Azure Blob, etc.). Here is where an union can help you.\nThe union LakeTarget defined below allows the lake_target argument of send_event() to be either an object of type AzureBlob, or type AmazonS3, or type GoogleGCP. This union allows the send_event() function to receive an object of any of these three types as input in the lake_target argument.\nRemember that each of these three types (AmazonS3, GoogleGCP and AzureBlob) are separate structs that we have defined in our source code. So, at first glance, they are separate data types in our source code. But is the union keyword that unifies them into a single data type called LakeTarget.\n\nconst LakeTarget = union {\n    azure: AzureBlob,\n    amazon: AmazonS3,\n    google: GoogleGCP,\n};\n\nfn send_event(\n    event: Event,\n    lake_target: LakeTarget\n) bool {\n    // body of the function ...\n}\n\nAn union definition is composed by a list of data members. Each data member is of a specific data type. In the example above, the LakeTarget union have three data members (azure, amazon, google). When you instantiate an object that uses an union type, you can only use one of its data members in this instantiation.\nYou could also interpret this as: only one data member of an union type can be activated at a time, the other data members remain deactivated and unaccessible. For example, if you create a LakeTarget object that uses the azure data member, you can no longer use or access the data members google or amazon. It’s like if these other data members didn’t exist at all in the LakeTarget type.\nYou can see this logic in the example below. Notice that, we first instantiate the union object using the azure data member. As a result, this target object contains only the azure data member inside of it. Only this data member is active in this object. That is why the last line in this code example is invalid. Because we are trying to instantiate the data member google, which is currently inactive for this target object, and as a result, the program enters in panic mode warning us about this mistake through a loud error message.\n\nvar target = LakeTarget {\n    .azure = AzureBlob.init()\n};\n// Only the `azure` data member exist inside\n// the `target` object, and, as a result, this\n// line below is invalid:\ntarget.google = GoogleGCP.init();\n\nthread 2177312 panic: access of union field 'google' while\n    field 'azure' is active:\n    target.google = GoogleGCP.init();\n          ^\nSo, when you instantiate an union object, you must choose one of the data types (or, one of the data members) listed in the union type. In the example above, I choose to use the azure data member, and, as a result, all other data members were automatically deactivated, and you can no longer use them after you instantiate the object.\nYou can activate another data member by completely redefining the entire enum object. In the example below, I initially use the azure data member. But then, I redefine the target object to use a new LakeTarget object, which uses the google data member.\n\nvar target = LakeTarget {\n    .azure = AzureBlob.init()\n};\ntarget = LakeTarget {\n    .google = GoogleGCP.init()\n};\n\nA curious fact about union types, is that, at first, you cannot use them in switch statements (which were presented in Section 2.1.2). In other words, if you have an object of type LakeTarget for example, you cannot give this object as input to a switch statement.\nBut what if you really need to do so? What if you actually need to provide an “union object” to a switch statement? The answer to this question relies on another special type in Zig, which are the tagged unions. To create a tagged union, all you have to do is to add an enum type into your union declaration.\nAs an example of a tagged union in Zig, take the Registry type exposed below. This type comes from the grammar.zig module2 from the Zig repository. This union type lists different types of registries. But notice this time, the use of (enum) after the union keyword. This is what makes this union type a tagged union. By being a tagged union, an object of this Registry type can be used as input in a switch statement. This is all you have to do. Just add (enum) to your union declaration, and you can use it in switch statements.\n\npub const Registry = union(enum) {\n    core: CoreRegistry,\n    extension: ExtensionRegistry,\n};\n\n\n\n\n\nZig Software Foundation. 2024a. “In-Depth Overview.” Zig Software Foundation. https://ziglang.org/learn/overview/.\n\n\n———. 2024b. “Language Reference.” Zig Software Foundation. https://ziglang.org/documentation/master/.",
     "crumbs": [
       "<span class='chapter-number'>10</span>  <span class='chapter-title'>Error handling and unions</span>"
     ]
@@ -884,7 +884,7 @@
     "href": "Chapters/09-data-structures.html#sec-dynamic-array",
     "title": "11  Data Structures",
     "section": "",
-    "text": "11.1.1 Capacity vs Length\nWhen we talk about dynamic arrays, we usually have two similar concepts that are very essential to how a dynamic array works behind the hood. These concepts are capacity and length. In some contexts, especially in C++, length is also called of size.\nAlthough they look similar, these concepts represent different things in the context of a dynamic array. Capacity is the number of items (or elements) that your dynamic array can currently hold without the need to allocate more memory.\nIn contrast, the length refers to how many elements in the array are currently being used, or, in other words, how many elements in this array that you have assigned a value to. Every dynamic array works around a block of allocated memory, which represents an array with total capacity for \\(n\\) elements. However, only a portion of these \\(n\\) elements are being used most of the time. This portion of \\(n\\) is the length of the array. So every time you append a new value to the array, you are incrementing its length by one.\nThis means that a dynamic array usually works with an extra margin, or, an extra space which is currently empty, but it is waiting and ready to be used. This “extra space” is essentially the difference between capacity and length. Capacity represents the total number of elements that the array can hold without the need to re-allocate or re-expand the array, while the length represents how much of this capacity is currently being used to hold/store values.\nFigure 11.1 presents this idea visually. Notice that, at first, the capacity of the array is greater than the length of the array. So, the dynamic array have extra space that is currently empty, but it is ready to receive a value to be stored.\n\n\n\n\n\n\nFigure 11.1: Difference between capacity and length in a dynamic array\n\n\n\nWe can also see at Figure 11.1 that, when length and capacity are equal, it means that the array have no space left. We have reached the ceiling of our capacity, and because of that, if we want to store more values in this array, we need to expand it. We need to get a bigger space that can hold more values than what we currently have.\nA dynamic array works by expanding the underlying array, whenever the length becomes equal to the capacity of the array. It basically allocates a new contiguous block of memory that is bigger than the previous one, then, it copies all values that are currently being stored to this new location (i.e. this new block of memory), then, it frees the previous block of memory. At the end of this process, the new underlying array have a bigger capacity, and, therefore, the length becomes, once again, smaller than the capacity of the array.\nThis is the cycle of an dynamic array. Notice that, throughout this cycle, the capacity is always either equal to or higher than the length of the array. If youh have an ArrayList object (let’s suppose you named it buffer), you can check the current capacity of your array by accessing the capacity attribute of your ArrayList object, while the current length of it is available at the items.len attribute.\n\n// Check capacity\nbuffer.capacity;\n// Check length\nbuffer.items.len;\n\n\n\n11.1.2 Creating an ArrayList object\nIn order to use ArrayList, you must provide an allocator object to it. Remember, Zig does not have a default memory allocator. And as I described at Section 3.3, all memory allocations must be done by an allocator object that you define, that you have control over. In our example here, I’m going to use a general purpose allocator, but you can use any other allocator of your preference.\nWhen you initialize an ArrayList object, you must provide the data type of the elements of the array. In other words, this defines the type of data that this array (or container) will store. Therefore, if I provide the u8 type to it, then, I will create a dynamic array of u8 values. However, if I provide a struct that I have defined instead, like the struct User from Section 2.3, then, a dynamic array of User values will be created. In the example below, with the expression ArrayList(u8) we are creating a dynamic array of u8 values.\nAfter you provide the data type of the elements of the array, you can initialize an ArrayList object by either using the init() or the initCapacity() methods. The former method receives only the allocator object as input, while the latter method receives both the allocator object and a capacity number as inputs. With the latter method, you not only initialize the struct, but you also set the starting capacity of the allocated array.\nUsing the initCapacity() method is the preferred way to initialize your dynamic array. Because reallocations, or, in other words, the process of expanding the capacity of the array, is always a high cost operation. You should take any possible opportunity to avoid reallocations in your array. If you know how much space your array needs to occupy at the beginning, you should always use initCapacity() to create your dynamic array.\n\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n\nIn the example above, the buffer object starts as an array of 100 elements. If this buffer object needs to create more space to accomodate more elements during the runtime of your program, the ArrayList internals will perform the necessary actions for you automatically. Also notice the deinit() method being used to destroy the buffer object at the end of the current scope, by freeing all the memory that was allocated for the dynamic array stored in this buffer object.\n\n\n11.1.3 Adding new elements to the array\nNow that we have created our dynamic array, we can start to use it. You can append (a.k.a “add”) new values to this array by using the append() method. This method works the same way as the append() method from a Python list, or, the emplace_back() method from std::vector of C++. You provide a single value to this method, and the method appends this value to the array.\nYou can also use the appendSlice() method to append multiple values at once. You provide a slice (slices were described at Section 1.6) to this method, and the method adds all values present in this slice to your dynamic array.\n\ntry buffer.append('H');\ntry buffer.append('e');\ntry buffer.append('l');\ntry buffer.append('l');\ntry buffer.append('o');\ntry buffer.appendSlice(\" World!\");\n\n\n\n11.1.4 Removing elements from the array\nYou can use the pop() method to “pop” or remove the last element in the array. Is worth noting that this method do not change the capacity of the array. It just deletes or erases the last value stored in the array.\nAlso, this method returns as result the value that got deleted. That is, you can use this method to both get the last value in the array, and also, remove it from the array. It is a “get and remove value” type of method.\n\nconst exclamation_mark = buffer.pop();\n\nNow, if you want to remove specific elements from specific positions of your array, you can use the orderedRemove() method from your ArrayList object. With this method, you can provide an index as input, then, the method will delete the value that is at this index in the array. You are effectively reducing the length of the array everytime you execute an orderedRemove() operation.\nIn the example below, we first create an ArrayList object, and we fill it with numbers. Then, we use orderedRemove() to remove the value at index 3 in the array, two consecutive times.\nAlso, notice that we are assigning the result of orderedRemove() to the underscore character. So we are discarding the result value of this method. The orderedRemove() method returns the value that got deleted, in a similar style to the pop() method.\n\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n\nfor (0..10) |i| {\n    const index: u8 = @intCast(i);\n    try buffer.append(index);\n}\n\nstd.debug.print(\n    \"{any}\\n\", .{buffer.items}\n);\n_ = buffer.orderedRemove(3);\n_ = buffer.orderedRemove(3);\n\nstd.debug.print(\"{any}\\n\", .{buffer.items});\nstd.debug.print(\"{any}\\n\", .{buffer.items.len});\n\n{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }\n{ 0, 1, 2, 5, 6, 7, 8, 9 }\n8\nOne key characteristic about orderedRemove() is that it preserves the order of the values in the array. So, it deletes the value that you asked it to remove, but it also makes sure that the order of the values that remain in the array stay the same as before.\nNow, if you don’t care about the order of the values, for example, maybe you want to treat your dynamic array as a set of values, like the std::unordered_set structure from C++, you can use the swapRemove() method instead. This method works similarly to the orderedRemove() method. You give an index to this method, then, it deletes the value that is at this index in the array. But this method does not preserve the original order of the values that remain in the array. As a result, swapRemove() is, in general, faster than orderedRemove().\n\n\n11.1.5 Inserting elements at specific indexes\nWhen you need to insert values in the middle of your array, instead of just appending them to the end of the array, you need to use the insert() and insertSlice() methods, instead of the append() and appendSlice() methods.\nThese two methods work very similarly to insert() and insert_range() from the C++ std::vector class. You provide an index to these methods, and they insert the values that you provide at that index in the array.\n\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 10);\ndefer buffer.deinit();\n\ntry buffer.appendSlice(\"My Pedro\");\ntry buffer.insert(4, '3');\ntry buffer.insertSlice(2, \" name\");\nfor (buffer.items) |char| {\n    try stdout.print(\"{c}\", .{char});\n}\n\nMy name P3edro\n\n\n11.1.6 Conclusion\nIf you feel the lack of some other method, I recommend you to read the official documentation for the ArrayListAligned1 struct, which describes most of the methods available through the ArrayList object.\nYou will notice that there is a lot of other methods in this page that I did not described here, and I recommend you to explore these methods, and understand how they work.",
+    "text": "11.1.1 Capacity vs Length\nWhen we talk about dynamic arrays, we usually have two similar concepts that are very essential to how a dynamic array works behind the hood. These concepts are capacity and length. In some contexts, especially in C++, length is also called of size.\nAlthough they look similar, these concepts represent different things in the context of a dynamic array. Capacity is the number of items (or elements) that your dynamic array can currently hold without the need to allocate more memory.\nIn contrast, the length refers to how many elements in the array are currently being used, or, in other words, how many elements in this array that you have assigned a value to. Every dynamic array works around a block of allocated memory, which represents an array with total capacity for \\(n\\) elements. However, only a portion of these \\(n\\) elements are being used most of the time. This portion of \\(n\\) is the length of the array. So every time you append a new value to the array, you are incrementing its length by one.\nThis means that a dynamic array usually works with an extra margin, or an extra space that is currently empty, but waiting and ready to be used. This “extra space” is essentially the difference between capacity and length. Capacity represents the total number of elements that the array can hold without the need to re-allocate or re-expand the array, while the length represents how much of this capacity is currently being used to hold/store values.\nFigure 11.1 presents this idea visually. Notice that, at first, the capacity of the array is greater than the length of the array. So, the dynamic array have extra space that is currently empty, but it is ready to receive a value to be stored.\n\n\n\n\n\n\nFigure 11.1: Difference between capacity and length in a dynamic array\n\n\n\nWe can also see in Figure 11.1 that, when length and capacity are equal, it means that the array have no space left. We have reached the ceiling of our capacity, and because of that, if we want to store more values in this array, we need to expand it. We need to get a bigger space that can hold more values than what we currently have.\nA dynamic array works by expanding the underlying array, whenever the length becomes equal to the capacity of the array. It basically allocates a new contiguous block of memory that is bigger than the previous one, then, it copies all values that are currently being stored to this new location (i.e., this new block of memory), then, it frees the previous block of memory. At the end of this process, the new underlying array have a bigger capacity, and, therefore, the length becomes, once again, smaller than the capacity of the array.\nThis is the cycle of a dynamic array. Notice that, throughout this cycle, the capacity is always either equal to or higher than the length of the array. If you have an ArrayList object (let’s suppose you named it buffer), you can check the current capacity of your array by accessing the capacity attribute of your ArrayList object, while the current length of it is available at the items.len attribute.\n\n// Check capacity\nbuffer.capacity;\n// Check length\nbuffer.items.len;\n\n\n\n11.1.2 Creating an ArrayList object\nIn order to use ArrayList, you must provide an allocator object to it. Remember, Zig does not have a default memory allocator. And as I described in Section 3.3, all memory allocations must be done by an allocator object that you define, that you have control over. In our example here, I’m going to use a general purpose allocator, but you can use any other allocator of your preference.\nWhen you initialize an ArrayList object, you must provide the data type of the elements of the array. In other words, this defines the type of data that this array (or container) will store. Therefore, if I provide the u8 type to it, then, I will create a dynamic array of u8 values. However, if I provide a struct that I have defined instead, like the struct User from Section 2.3, then, a dynamic array of User values will be created. In the example below, with the expression ArrayList(u8) we are creating a dynamic array of u8 values.\nAfter you provide the data type of the elements of the array, you can initialize an ArrayList object by either using the init() or the initCapacity() methods. The former method receives only the allocator object as input, while the latter method receives both the allocator object and a capacity number as inputs. With the latter method, you not only initialize the struct, but you also set the starting capacity of the allocated array.\nUsing the initCapacity() method is the preferred way to initialize your dynamic array. Because reallocations, or, in other words, the process of expanding the capacity of the array, is always a high cost operation. You should take any possible opportunity to avoid reallocations in your array. If you know how much space your array needs to occupy at the beginning, you should always use initCapacity() to create your dynamic array.\n\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n\nIn the example above, the buffer object starts as an array of 100 elements. If this buffer object needs to create more space to accomodate more elements during the runtime of your program, the ArrayList internals will perform the necessary actions for you automatically. Also notice the deinit() method being used to destroy the buffer object at the end of the current scope, by freeing all the memory that was allocated for the dynamic array stored in this buffer object.\n\n\n11.1.3 Adding new elements to the array\nNow that we have created our dynamic array, we can start to use it. You can append (a.k.a “add”) new values to this array by using the append() method. This method works the same way as the append() method from a Python list, or, the emplace_back() method from std::vector of C++. You provide a single value to this method, and the method appends this value to the array.\nYou can also use the appendSlice() method to append multiple values at once. You provide a slice (slices were described in Section 1.6) to this method, and the method adds all values present in this slice to your dynamic array.\n\ntry buffer.append('H');\ntry buffer.append('e');\ntry buffer.append('l');\ntry buffer.append('l');\ntry buffer.append('o');\ntry buffer.appendSlice(\" World!\");\n\n\n\n11.1.4 Removing elements from the array\nYou can use the pop() method to “pop” or remove the last element in the array. It’s worth noting that this method do not change the capacity of the array. It just deletes or erases the last value stored in the array.\nAlso, this method returns as result the value that got deleted. That is, you can use this method to both get the last value in the array, and also, remove it from the array. It’s a “get and remove value” type of method.\n\nconst exclamation_mark = buffer.pop();\n\nNow, if you want to remove specific elements from specific positions of your array, you can use the orderedRemove() method from your ArrayList object. With this method, you can provide an index as input, then, the method will delete the value that is at this index in the array. You are effectively reducing the length of the array everytime you execute an orderedRemove() operation.\nIn the example below, we first create an ArrayList object, and we fill it with numbers. Then, we use orderedRemove() to remove the value at index 3 in the array, two consecutive times.\nAlso, notice that we are assigning the result of orderedRemove() to the underscore character. So we are discarding the result value of this method. The orderedRemove() method returns the value that got deleted, in a similar style to the pop() method.\n\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n\nfor (0..10) |i| {\n    const index: u8 = @intCast(i);\n    try buffer.append(index);\n}\n\nstd.debug.print(\n    \"{any}\\n\", .{buffer.items}\n);\n_ = buffer.orderedRemove(3);\n_ = buffer.orderedRemove(3);\n\nstd.debug.print(\"{any}\\n\", .{buffer.items});\nstd.debug.print(\"{any}\\n\", .{buffer.items.len});\n\n{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }\n{ 0, 1, 2, 5, 6, 7, 8, 9 }\n8\nOne key characteristic about orderedRemove() is that it preserves the order of the values in the array. So, it deletes the value that you asked it to remove, but it also makes sure that the order of the values that remain in the array stay the same as before.\nNow, if you don’t care about the order of the values, for example, maybe you want to treat your dynamic array as a set of values, like the std::unordered_set structure from C++, you can use the swapRemove() method instead. This method works similarly to the orderedRemove() method. You give an index to this method, then, it deletes the value that is at this index in the array. But this method does not preserve the original order of the values that remain in the array. As a result, swapRemove() is, in general, faster than orderedRemove().\n\n\n11.1.5 Inserting elements at specific indexes\nWhen you need to insert values in the middle of your array, instead of just appending them to the end of the array, you need to use the insert() and insertSlice() methods, instead of the append() and appendSlice() methods.\nThese two methods work very similarly to insert() and insert_range() from the C++ std::vector class. You provide an index to these methods, and they insert the values that you provide at that index in the array.\n\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 10);\ndefer buffer.deinit();\n\ntry buffer.appendSlice(\"My Pedro\");\ntry buffer.insert(4, '3');\ntry buffer.insertSlice(2, \" name\");\nfor (buffer.items) |char| {\n    try stdout.print(\"{c}\", .{char});\n}\n\nMy name P3edro\n\n\n11.1.6 Conclusion\nIf you feel the lack of some other method, I recommend you to read the official documentation for the ArrayListAligned1 struct, which describes most of the methods available through the ArrayList object.\nYou will notice that there is a lot of other methods in this page that I did not described here, and I recommend you to explore these methods, and understand how they work.",
     "crumbs": [
       "<span class='chapter-number'>11</span>  <span class='chapter-title'>Data Structures</span>"
     ]
@@ -894,7 +894,7 @@
     "href": "Chapters/09-data-structures.html#sec-maps-hashtables",
     "title": "11  Data Structures",
     "section": "11.2 Maps or HashTables",
-    "text": "11.2 Maps or HashTables\nSome professionals know this type of data structure by different terms, like “map”, “hashmap” or “associative arrays”. But the most common term used is hashtable. Every programming language normally have some implementation of a hashtable in their standard libraries. Python have dict(), C++ have std::map and std::unordered_map, Rust have HashMap, Javascript have Object() and Map(), etc.\n\n11.2.1 What is a hashtable?\nA hashtable is a data structure based on key-value pairs. You provide a key and a value to this structure, then, the hashtable will store the input value at a location that can be identified by the input key that you provided. It does that by using an underlying array and a hash function. These two components are essential to how a hashtable works.\nUnder the hood, the hashtable contains an array. This array is where the values are stored, and the elements of this array are usually called of buckets. So the values that you provide to the hashtable are stored inside buckets, and you access each bucket by using an index.\nWhen you provide a key to a hashtable, it passes this key to the hash function. This hash function uses some sort of hashing algorithm to transform this key into an index. This index is actually an array index. It is a position in the underlying array of the hashtable. This is how a key identifies a specific position (or location) inside the hashtable structure.\nTherefore, you provide a key to the hashtable, and this key identifies a specific location inside the hashtable, then, the hashtable takes the input value that you provided, and stores this value in the location identified by this input key. You could say that the key maps to the value stored in the hashtable. You find the value, by using the key that identifies the location where the value is stored. The Figure 11.2 presents this process visually.\n\n\n\n\n\n\nFigure 11.2: A diagram of a Hashtable. Source: Wikipedia, the free encyclopedia.\n\n\n\nThe operation described in the previous paragraph is normally called an insertion operation. Because you are inserting new values into the hashtable. But there are other types of operations in hashtables such as delete and lookup. Delete is self describing, it is when you delete (or remove) a value from the hashtable. While lookup corresponds to when you look at a value that is stored in the hashtable, by using the key that identifies the location where this value is stored.\nSometimes, instead of storing the values directly, the underlying array of the hashtable might be an array of pointers, i.e. the buckets of the array stores pointers that points to the value, or also, may be an array of linked lists. These cases are common on hashtables that allows duplicate keys, or, in other words, on hashtables that effectively handle “collisions” that may arise from the hash function.\nDuplicate keys, or this “collision” thing that I’m talking about, is when you have two different keys that points to the same location (i.e. to the same index) in the underlying array of the hashtable. This might happen depending on the characteristics of the hash function that is being used in the hashtable. Some implementations of the hashtable will actively deal with collisions, meaning that, they will handle this case in some way. For example, the hashtable might transform all buckets into linked lists. Because with a linked list you can store multiple values into a single bucket.\nThere are different techniques to handle collisions in hashtables, which I will not describe in this book, because it is not our main scope here. But you can find a good description of some of the most common techniques at the Wikipedia page of hashtables (Wikipedia 2024).\n\n\n11.2.2 Hashtables in Zig\nThe Zig Standard Library provides different implementations of a hashtable. Each implementation have its own cons and pros, which we will discuss later on, and all of them are available through the std.hash_map module.\nThe HashMap struct is a general-purpose hashtable, which have very fast operations (lookup, insertion, delete), and also, quite high load factors for low memory usage. You can create and provide a context object to the HashMap constructor. This context object allows you to tailor the behaviour of the hashtable itself, because you can provide a hash function implementation to be used by the hashtable through this context object.\nBut let’s not worry about this context object now, because it is meant to be used by “experts in the field of hashtables”. Since we are most likely not experts in this field, we are going to take the easy way to create a hashtable. Which is by using the AutoHashMap() function.\nThis AutoHashMap() function is essentially a “create a hashtable object that uses the default settings” type of function. It automatically chooses a context object, and, therefore, a hash function implementation, for you. This function receives two data types as input, the first input is the data type of the keys that will be used in this hashtable, while the second input is the data type of the data that will be stored inside the hashtable, that is, the data type of the values to be stored.\nIn the example below, we are providing the data type u32 in the first argument, and u16 in the second argument of this function. This means that we are going to use u32 values as keys in this hashtable, while u16 values are the actual values that are going to be stored into this hashtable. At the end of this process, the hash_table object contains a HashMap object that uses the default settings and context.\n\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n    std.debug.print(\n        \"Value at key 50050: {d}\\n\",\n        .{hash_table.get(50050).?}\n    );\n\n    if (hash_table.remove(57709)) {\n        std.debug.print(\n            \"Value at key 57709 successfully removed!\\n\",\n            .{}\n        );\n    }\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n}\n\nN of values stored: 3\nValue at key 50050: 55\nValue at key 57709 successfully removed!\nN of values stored: 2\nYou can add/put new values into the hashtable by using the put() method. The first argument is the key to be used, and the second argument is the actual value that you want to store inside the hashtable. In the example below, we first add the value 89 using the key 54321, next, we add the value 55 using the key 50050, etc.\nNotice that we have used the method count() to see how many values are currently stored in the hashtable. After that, we also use the get() method to access (or look) at the value stored in the position identified by the key 500050. The output of this get() method is an optional value. This is why we use the ? method at the end to get the actual value.\nAlso notice that we can remove (or delete) values from the hashtable by using the remove() method. You provide the key that identifies the value that you want to delete, then, the method will delete this value and return a true value as output. This true value essentially tells us that the method successfully deleted the value.\nBut this delete operation might not be always successful. For example, you might provide the wrong key to this method. I mean, maybe you provide (either intentionally or unintentionally) a key that points to an empty bucket, i.e. a bucket that still doesn’t have a value in it. In this case, the remove() method would return a false value.\n\n\n11.2.3 Iterating through the hashtable\nIterating through the keys and values that are currently being stored in the hashtable is a very common necessity. You can do that in Zig by using an iterator object that can iterate through the elements of your hashtable object.\nThis iterator object works like any other iterator object that you would find in languages such as C++ and Rust. It is basically a pointer object that points to some value in the container, and has a next() method that you can use to navigate (or iterate) through the values in the container.\nYou can create such iterator object by using the iterator() method of the hashtable object. This method returns an iterator object, from which you can use the next() method in conjunction with a while loop to iterate through the elements of your hashtable. The next() method returns an optional Entry value, and therefore, you must unwrap this optional value to get the actual Entry value from which you can access the key and also the value identified by this key.\nWith this Entry value at hand, you can access the key of this current entry by using the key_ptr attribute and dereferencing the pointer that lives inside of it, while the value identified by this key is accessed through the value_ptr attribute instead, which is also a pointer to be dereferenced. The code example below demonstrates the use of these elements:\n\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n\n    var it = hash_table.iterator();\n    while (it.next()) |kv| {\n        // Access the current key\n        std.debug.print(\"Key: {d} | \", .{kv.key_ptr.*});\n        // Access the current value\n        std.debug.print(\"Value: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n\nKey: 54321 | Value: 89\nKey: 50050 | Value: 55\nKey: 57709 | Value: 41\nIf you want to iterate specifically through the values or the keys of your hashtable, you can create a key iterator or a value iterator object. These are also iterator objects, which have the same next() method that you can use to iterate through the hashtable.\nKey iterators are created from the keyIterator() method of your hashtable object, while value iterators are created from the valueIterator() method. All you have to do is to unwrap the value from the next() method and deference it directly to access the key or the value that you are iterating over. The code example below demonstrates the use of a key iterator, but you can replicate the same logic to a value iterator.\n\nvar kit = hash_table.keyIterator();\nwhile (kit.next()) |key| {\n    std.debug.print(\"Key: {d}\\n\", .{key.*});\n}\n\nKey: 54321\nKey: 50050\nKey: 57709\n\n\n11.2.4 The ArrayHashMap hashtable\nIf you need to iterate through the elements of your hashtable constantly, you might want to use the ArrayHashMap struct for your specific case, instead of going with the usual and general-purpose HashMap struct.\nThe ArrayHashMap struct creates a hashtable that is faster to iterate over. That is why this specific type of hashtable might be valuable to you. Some other properties of a ArrayHashMap hashtable are:\n\nthe order of insertion is preserved, i.e. the order of the values that you find while iterating through this hashtable is actually the order in which these values were inserted in the hashtable.\nthe key-value pairs are stored sequentially, one after another.\n\nYou can create an ArrayHashMap object by using, once again, a helper function that chooses automatically for you a hash function implementation. This is the AutoArrayHashMap() function, which works very similarly to the AutoHashMap() function that we presented at Section 11.2.2.\nYou provide two data types to this function. The data type of the keys that will be used in this hashtable, and the data type of the values that will be stored in this hashtable.\nAn ArrayHashMap object have essentially the exact same methods from the HashMap struct. So you can insert new values into the hashtable by using the put() method, and you can look (or get) a value from the hashtable by using the get() method. But the remove() method is not available in this specific type of hashtable.\nIn order to delete values from the hashtable, you would use the same methods that you find in an ArrayList object, i.e. a dynamic array. I presented these methods at Section 11.1.4, which are the swapRemove() and orderedRemove() methods. These methods have the same meaning here, or, the same effect that they have in an ArrayList object.\nThis means that, with swapRemove() you remove the value from the hashtable, but you do not preserve the order in which the values were inserted into the structure. While orderedRemove() is able to retain the order in which these values were inserted.\nBut instead of providing an index as input to swapRemove() or orderedRemove(), like I described at Section 11.1.4, these methods here in an ArrayHashMap take a key as input, like the remove() method from a HashMap object. If you want to provide an index as input, instead of a key, you should use the swapRemoveAt() and orderedRemoveAt() methods.\n\nvar hash_table = AutoArrayHashMap(u32, u16)\n    .init(allocator);\ndefer hash_table.deinit();\n\n\n\n11.2.5 The StringHashMap hashtable\nOne thing that you will notice in the other two types of hashtables that I have presented over the last sections, is that neither of them accepts a slice data type in their keys. What this means is that you cannot use a slice value to represent a key in these types of hashtable.\nThe most obvious consequence of this, is that you cannot use strings as keys in these hashtables. But it is extremely common to use strings as keys in hashtables.\nTake this very simple Javascript code snippet as an example. We are creating a simple hashtable object named people. Then, we add a new entry to this hashtable, which is identified by the string 'Pedro'. This string is the key in this case, while the object containing different personal information such as age, height and city, is the value to be stored in the hashtable.\nvar people = new Object();\npeople['Pedro'] = {\n    'age': 25,\n    'height': 1.67,\n    'city': 'Belo Horizonte'\n};\nThis pattern of using strings as keys is very common in all sorts of situations. That is why the Zig Standard Library offers a specific type of hashtable for this purpose, which is created through the StringHashMap() function. This function creates a hashtable that uses strings as keys. The only input of this function is the data type of the values that will be stored into this hashtable.\nIn the example below, I’m creating a hashtable to store the ages of different people. Each key in this hashtable is represented by the name of each person, while the value stored in the hashtable is the age of this person identified by the key.\nThat is why I provide the u8 data type (which is the data type used by the age values) as input to this StringHashMap() function. As the result, it creates a hashtable that uses string values as keys, and, that stores u8 values in it. Notice that an allocator object is provided at the init() method of the resulting object from the StringHashMap() function.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var ages = std.StringHashMap(u8).init(allocator);\n    defer ages.deinit();\n\n    try ages.put(\"Pedro\", 25);\n    try ages.put(\"Matheus\", 21);\n    try ages.put(\"Abgail\", 42);\n\n    var it = ages.iterator();\n    while (it.next()) |kv| {\n        std.debug.print(\"Key: {s} | \", .{kv.key_ptr.*});\n        std.debug.print(\"Age: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n\nKey: Pedro | Age: 25\nKey: Abgail | Age: 42\nKey: Matheus | Age: 21\n\n\n11.2.6 The StringArrayHashMap hashtable\nThe Zig Standard Library also provides a type of hashtable that mix the cons and pros of the StringHashMap and ArrayHashMap together. That is, a hashtable that uses strings as keys, but also have the advantages from ArrayHashMap. In other words, you can have a hashtable that is fast to iterate over, that preserves insertion order, and also, that uses strings as keys.\nYou can create such type of hashtable by using the StringArrayHashMap() function. This function accepts a data type as input, which is the data type of the values that are going to be stored inside this hashtable, in the same style as the function presented at Section 11.2.5.\nYou can insert new values into this hashtable by using the same put() method that we have discussed at Section 11.2.5. And you can also get values from the hashtable by using the same get() method. Like its ArrayHashMap brother, to delete values from this specific type of hashtable, we also use the orderedRemove() and swapRemove() methods, with the same effects that I have described at Section 11.2.4.\nIf we take the code example that was exposed at Section 11.2.5, we can achieve the exact same result with StringArrayHashMap():\n\nvar ages = std.StringArrayHashMap(u8).init(allocator);",
+    "text": "11.2 Maps or HashTables\nSome professionals know this type of data structure by different terms, like “map”, “hashmap” or “associative arrays”. But the most common term used is hashtable. Every programming language normally have some implementation of a hashtable in their standard libraries. Python have dict(), C++ have std::map and std::unordered_map, Rust have HashMap, Javascript have Object() and Map(), etc.\n\n11.2.1 What is a hashtable?\nA hashtable is a data structure based on key-value pairs. You provide a key and a value to this structure, then, the hashtable will store the input value at a location that can be identified by the input key that you provided. It does that by using an underlying array and a hash function. These two components are essential to how a hashtable works.\nUnder the hood, the hashtable contains an array. This array is where the values are stored, and the elements of this array are usually called of buckets. So the values that you provide to the hashtable are stored inside buckets, and you access each bucket by using an index.\nWhen you provide a key to a hashtable, it passes this key to the hash function. This hash function uses some sort of hashing algorithm to transform this key into an index. This index is actually an array index. It’s a position in the underlying array of the hashtable. This is how a key identifies a specific position (or location) inside the hashtable structure.\nTherefore, you provide a key to the hashtable, and this key identifies a specific location inside the hashtable, then, the hashtable takes the input value that you provided, and stores this value in the location identified by this input key. You could say that the key maps to the value stored in the hashtable. You find the value, by using the key that identifies the location where the value is stored. The Figure 11.2 presents this process visually.\n\n\n\n\n\n\nFigure 11.2: A diagram of a Hashtable. Source: Wikipedia, the free encyclopedia.\n\n\n\nThe operation described in the previous paragraph is normally called an insertion operation. Because you are inserting new values into the hashtable. But there are other types of operations in hashtables such as delete and lookup. Delete is self describing, it’s when you delete (or remove) a value from the hashtable. While lookup corresponds to when you look at a value that is stored in the hashtable, by using the key that identifies the location where this value is stored.\nSometimes, instead of storing the values directly, the underlying array of the hashtable might be an array of pointers, i.e., the buckets of the array stores pointers that points to the value, or also, may be an array of linked lists. These cases are common on hashtables that allows duplicate keys, or, in other words, on hashtables that effectively handle “collisions” that may arise from the hash function.\nDuplicate keys, or this “collision” thing that I’m talking about, is when you have two different keys that points to the same location (i.e., to the same index) in the underlying array of the hashtable. This might happen depending on the characteristics of the hash function that is being used in the hashtable. Some implementations of the hashtable will actively deal with collisions, meaning that, they will handle this case in some way. For example, the hashtable might transform all buckets into linked lists. Because with a linked list you can store multiple values into a single bucket.\nThere are different techniques to handle collisions in hashtables, which I will not describe in this book, because it’s not our main scope here. But you can find a good description of some of the most common techniques at the Wikipedia page of hashtables (Wikipedia 2024).\n\n\n11.2.2 Hashtables in Zig\nThe Zig Standard Library provides different implementations of a hashtable. Each implementation have its own cons and pros, which we will discuss later on, and all of them are available through the std.hash_map module.\nThe HashMap struct is a general-purpose hashtable, which have very fast operations (lookup, insertion, delete), and also, quite high load factors for low memory usage. You can create and provide a context object to the HashMap constructor. This context object allows you to tailor the behaviour of the hashtable itself, because you can provide a hash function implementation to be used by the hashtable through this context object.\nBut let’s not worry about this context object now, because it’s meant to be used by “experts in the field of hashtables”. Since we are most likely not experts in this field, we are going to take the easy way to create a hashtable. Which is by using the AutoHashMap() function.\nThis AutoHashMap() function is essentially a “create a hashtable object that uses the default settings” type of function. It automatically chooses a context object, and, therefore, a hash function implementation, for you. This function receives two data types as input, the first input is the data type of the keys that will be used in this hashtable, while the second input is the data type of the data that will be stored inside the hashtable, that is, the data type of the values to be stored.\nIn the example below, we are providing the data type u32 in the first argument, and u16 in the second argument of this function. This means that we are going to use u32 values as keys in this hashtable, while u16 values are the actual values that are going to be stored into this hashtable. At the end of this process, the hash_table object contains a HashMap object that uses the default settings and context.\n\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n    std.debug.print(\n        \"Value at key 50050: {d}\\n\",\n        .{hash_table.get(50050).?}\n    );\n\n    if (hash_table.remove(57709)) {\n        std.debug.print(\n            \"Value at key 57709 successfully removed!\\n\",\n            .{}\n        );\n    }\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n}\n\nN of values stored: 3\nValue at key 50050: 55\nValue at key 57709 successfully removed!\nN of values stored: 2\nYou can add/put new values into the hashtable by using the put() method. The first argument is the key to be used, and the second argument is the actual value that you want to store inside the hashtable. In the example below, we first add the value 89 using the key 54321, next, we add the value 55 using the key 50050, etc.\nNotice that we have used the method count() to see how many values are currently stored in the hashtable. After that, we also use the get() method to access (or look) at the value stored in the position identified by the key 500050. The output of this get() method is an optional value. This is why we use the ? method at the end to get the actual value.\nAlso notice that we can remove (or delete) values from the hashtable by using the remove() method. You provide the key that identifies the value that you want to delete, then, the method will delete this value and return a true value as output. This true value essentially tells us that the method successfully deleted the value.\nBut this delete operation might not be always successful. For example, you might provide the wrong key to this method. I mean, maybe you provide (either intentionally or unintentionally) a key that points to an empty bucket, i.e., a bucket that still doesn’t have a value in it. In this case, the remove() method would return a false value.\n\n\n11.2.3 Iterating through the hashtable\nIterating through the keys and values that are currently being stored in the hashtable is a very common necessity. You can do that in Zig by using an iterator object that can iterate through the elements of your hashtable object.\nThis iterator object works like any other iterator object that you would find in languages such as C++ and Rust. It’s basically a pointer object that points to some value in the container, and has a next() method that you can use to navigate (or iterate) through the values in the container.\nYou can create such iterator object by using the iterator() method of the hashtable object. This method returns an iterator object, from which you can use the next() method in conjunction with a while loop to iterate through the elements of your hashtable. The next() method returns an optional Entry value, and therefore, you must unwrap this optional value to get the actual Entry value from which you can access the key and also the value identified by this key.\nWith this Entry value at hand, you can access the key of this current entry by using the key_ptr attribute and dereferencing the pointer that lives inside of it, while the value identified by this key is accessed through the value_ptr attribute instead, which is also a pointer to be dereferenced. The code example below demonstrates the use of these elements:\n\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n\n    var it = hash_table.iterator();\n    while (it.next()) |kv| {\n        // Access the current key\n        std.debug.print(\"Key: {d} | \", .{kv.key_ptr.*});\n        // Access the current value\n        std.debug.print(\"Value: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n\nKey: 54321 | Value: 89\nKey: 50050 | Value: 55\nKey: 57709 | Value: 41\nIf you want to iterate specifically through the values or the keys of your hashtable, you can create a key iterator or a value iterator object. These are also iterator objects, which have the same next() method that you can use to iterate through the hashtable.\nKey iterators are created from the keyIterator() method of your hashtable object, while value iterators are created from the valueIterator() method. All you have to do is to unwrap the value from the next() method and deference it directly to access the key or the value that you are iterating over. The code example below demonstrates the use of a key iterator, but you can replicate the same logic to a value iterator.\n\nvar kit = hash_table.keyIterator();\nwhile (kit.next()) |key| {\n    std.debug.print(\"Key: {d}\\n\", .{key.*});\n}\n\nKey: 54321\nKey: 50050\nKey: 57709\n\n\n11.2.4 The ArrayHashMap hashtable\nIf you need to iterate through the elements of your hashtable constantly, you might want to use the ArrayHashMap struct for your specific case, instead of going with the usual and general-purpose HashMap struct.\nThe ArrayHashMap struct creates a hashtable that is faster to iterate over. That is why this specific type of hashtable might be valuable to you. Some other properties of a ArrayHashMap hashtable are:\n\nthe order of insertion is preserved, i.e., the order of the values that you find while iterating through this hashtable is actually the order in which these values were inserted in the hashtable.\nthe key-value pairs are stored sequentially, one after another.\n\nYou can create an ArrayHashMap object by using, once again, a helper function that chooses automatically for you a hash function implementation. This is the AutoArrayHashMap() function, which works very similarly to the AutoHashMap() function that we presented in Section 11.2.2.\nYou provide two data types to this function. The data type of the keys that will be used in this hashtable, and the data type of the values that will be stored in this hashtable.\nAn ArrayHashMap object have essentially the exact same methods from the HashMap struct. So you can insert new values into the hashtable by using the put() method, and you can look (or get) a value from the hashtable by using the get() method. But the remove() method is not available in this specific type of hashtable.\nIn order to delete values from the hashtable, you would use the same methods that you find in an ArrayList object, i.e., a dynamic array. I presented these methods in Section 11.1.4, which are the swapRemove() and orderedRemove() methods. These methods have the same meaning here, or, the same effect that they have in an ArrayList object.\nThis means that, with swapRemove() you remove the value from the hashtable, but you do not preserve the order in which the values were inserted into the structure. While orderedRemove() is able to retain the order in which these values were inserted.\nBut instead of providing an index as input to swapRemove() or orderedRemove(), like I described in Section 11.1.4, these methods here in an ArrayHashMap take a key as input, like the remove() method from a HashMap object. If you want to provide an index as input, instead of a key, you should use the swapRemoveAt() and orderedRemoveAt() methods.\n\nvar hash_table = AutoArrayHashMap(u32, u16)\n    .init(allocator);\ndefer hash_table.deinit();\n\n\n\n11.2.5 The StringHashMap hashtable\nOne thing that you will notice in the other two types of hashtables that I have presented over the last sections, is that neither of them accepts a slice data type in their keys. What this means is that you cannot use a slice value to represent a key in these types of hashtable.\nThe most obvious consequence of this, is that you cannot use strings as keys in these hashtables. But it’s extremely common to use strings as keys in hashtables.\nTake this very simple Javascript code snippet as an example. We are creating a simple hashtable object named people. Then, we add a new entry to this hashtable, which is identified by the string 'Pedro'. This string is the key in this case, while the object containing different personal information such as age, height and city, is the value to be stored in the hashtable.\nvar people = new Object();\npeople['Pedro'] = {\n    'age': 25,\n    'height': 1.67,\n    'city': 'Belo Horizonte'\n};\nThis pattern of using strings as keys is very common in all sorts of situations. That is why the Zig Standard Library offers a specific type of hashtable for this purpose, which is created through the StringHashMap() function. This function creates a hashtable that uses strings as keys. The only input of this function is the data type of the values that will be stored into this hashtable.\nIn the example below, I’m creating a hashtable to store the ages of different people. Each key in this hashtable is represented by the name of each person, while the value stored in the hashtable is the age of this person identified by the key.\nThat is why I provide the u8 data type (which is the data type used by the age values) as input to this StringHashMap() function. As the result, it creates a hashtable that uses string values as keys, and, that stores u8 values in it. Notice that an allocator object is provided at the init() method of the resulting object from the StringHashMap() function.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var ages = std.StringHashMap(u8).init(allocator);\n    defer ages.deinit();\n\n    try ages.put(\"Pedro\", 25);\n    try ages.put(\"Matheus\", 21);\n    try ages.put(\"Abgail\", 42);\n\n    var it = ages.iterator();\n    while (it.next()) |kv| {\n        std.debug.print(\"Key: {s} | \", .{kv.key_ptr.*});\n        std.debug.print(\"Age: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n\nKey: Pedro | Age: 25\nKey: Abgail | Age: 42\nKey: Matheus | Age: 21\n\n\n11.2.6 The StringArrayHashMap hashtable\nThe Zig Standard Library also provides a type of hashtable that mix the cons and pros of the StringHashMap and ArrayHashMap together. That is, a hashtable that uses strings as keys, but also have the advantages from ArrayHashMap. In other words, you can have a hashtable that is fast to iterate over, that preserves insertion order, and also, that uses strings as keys.\nYou can create such type of hashtable by using the StringArrayHashMap() function. This function accepts a data type as input, which is the data type of the values that are going to be stored inside this hashtable, in the same style as the function presented in Section 11.2.5.\nYou can insert new values into this hashtable by using the same put() method that we have discussed in Section 11.2.5. And you can also get values from the hashtable by using the same get() method. Like its ArrayHashMap brother, to delete values from this specific type of hashtable, we also use the orderedRemove() and swapRemove() methods, with the same effects that I have described in Section 11.2.4.\nIf we take the code example that was exposed in Section 11.2.5, we can achieve the exact same result with StringArrayHashMap():\n\nvar ages = std.StringArrayHashMap(u8).init(allocator);",
     "crumbs": [
       "<span class='chapter-number'>11</span>  <span class='chapter-title'>Data Structures</span>"
     ]
@@ -904,7 +904,7 @@
     "href": "Chapters/09-data-structures.html#linked-lists",
     "title": "11  Data Structures",
     "section": "11.3 Linked lists",
-    "text": "11.3 Linked lists\nThe Zig Standard Library provides an implementation for both singly and doubly linked lists. A linked list is a linear data structure that looks like a chain, or, a rope. The main advantage of this data structure is that you normally have very fast insertion and deletion operations. But, as a disadvantage, iterating through this data structure is usually not so fast as iterating through an array.\nThe idea behind a linked list is to build a structure that consists of a sequence of nodes connected to each other by pointers. This means that linked lists are usually not contiguous in memory, because each node might be anywhere in memory. They do not need to be close to one another.\nAt Figure 11.3 we can see a diagram of a singly linked list. We begin at the first node (which is usually called “the head of the linked list”). Then, from this first node we uncover the remaining nodes in the structure, by following the locations pointed by the pointers found in each node.\nEach node has two things in it. It has the value that is stored in the current node , and also, a pointer. This pointer points to the next node in the list. If this pointer is null, then, it means that we have reached the end of our linked list.\n\n\n\n\n\n\nFigure 11.3: A diagram of a singly linked list.\n\n\n\nAt Figure 11.4 we can see a diagram of a doubly linked list. The only thing that really changes now is that every node in the linked list has both a pointer to the previous node, and, a pointer to the next node. So every node in a doubly linked list has two pointers in it. These are usually called the prev (for “previous”) and the next (for “next”) pointers of the node.\nIn the singly linked list example, we had only one single pointer in each node, and this singular pointer was always pointing to the next node in the sequence. This means that singly linked lists normally have only the next pointer in them.\n\n\n\n\n\n\nFigure 11.4: A diagram of a doubly linked list.\n\n\n\nLinked lists are available in Zig through the functions SinglyLinkedList() and DoublyLinkedList(), for “singly linked lists” and “doubly linked lists”, respectively. These functions are actually generic functions, which we are going to talk more about at Section 12.2.1.\nFor now, just understand that, in order to create a linked list object, we begin by providing a data type to these functions. This data type defines the type of data that each node in this linked list will store. In the example below, we are creating a singly linked list of u32 values. So each node in this linked list will store a u32 value.\nBoth the SinglyLinkedList() and DoublyLinkedList() functions returns a type, i.e. a struct definition, as output. Therefore, the object Lu32 is actually a struct definition. It defines the type “singly linked list of u32 values”.\nNow that we have the definition of the struct, we need to instantiate a Lu32 object. We normally instantiate struct objects in Zig by using an init() method. But in this case, we are instantiating the struct directly, by using an empty struct literal, in the expression Lu32{}.\nIn this example, we first create multiple node objects, and after we create them, we start to insert and connect these nodes to build the linked list, using the prepend() and insertAfter() methods. Notice that the prepend() method is a method from the linked list object, while the insertAfter() is a method present in the node objects.\nIn essence, the prepend() method inserts a node at the beginning of the linked list. In other words, the node that you provide to this method, becomes the new “head node” of the linked list. It becomes the first node in the list (see Figure 11.3).\nOn the other side, the insertAfter() method is used to basically connect two nodes together. When you provide a node to this method, it creates a pointer to this input node, and stores this pointer in the next attribute of the current node, from which the method was called from.\nBecause doubly linked lists have both a next and a prev attributes in each node (as described at Figure 11.4), a node object created from a DoublyLinkedList object have both an insertBefore() (for prev) and an insertAfter() (for next) methods available.\nThus, if we have used a doubly linked list, we can use the insertBefore() method to store the pointer to the input node in the prev attribute. This would put the input node as the “previous node”, or, the node before the current node. In contrast, the insertAfter() method puts the pointer created to the input node in the next attribute of the current node, and as result, the input node becomes the “next node” of the current node.\nSince we are using a singly linked list in this example, we have only the insertAfter() method available in the node objects that we create from our Lu32 type.\n\nconst std = @import(\"std\");\nconst SinglyLinkedList = std.SinglyLinkedList;\nconst Lu32 = SinglyLinkedList(u32);\n\npub fn main() !void {\n    var list = Lu32{};\n    var one = Lu32.Node{ .data = 1 };\n    var two = Lu32.Node{ .data = 2 };\n    var three = Lu32.Node{ .data = 3 };\n    var four = Lu32.Node{ .data = 4 };\n    var five = Lu32.Node{ .data = 5 };\n\n    list.prepend(&two); // {2}\n    two.insertAfter(&five); // {2, 5}\n    list.prepend(&one); // {1, 2, 5}\n    two.insertAfter(&three); // {1, 2, 3, 5}\n    three.insertAfter(&four); // {1, 2, 3, 4, 5}\n}\n\nThere are other methods available from the linked list object, depending if this object is a singly linked list or a doubly linked list, that might be very useful for you. You can find a summary of them in the bullet points below:\n\nremove() to remove a specific node from the linked list.\nif singly linked list, len() to count how many nodes there is in the linked list.\nif doubly linked list, checkout the len attribute to see how many nodes there is in the linked list.\nif singly linked list, popFirst() to remove the first node (i.e. the “head”) from the linked list.\nif doubly linked list, pop() and popFirst() to remove the last and first nodes from the linked list, respectively.\nif doubly linked list, append() to add a new node to end of the linked list (i.e. inverse of prepend()).",
+    "text": "11.3 Linked lists\nThe Zig Standard Library provides an implementation for both singly and doubly linked lists. A linked list is a linear data structure that looks like a chain, or, a rope. The main advantage of this data structure is that you normally have very fast insertion and deletion operations. But, as a disadvantage, iterating through this data structure is usually not so fast as iterating through an array.\nThe idea behind a linked list is to build a structure that consists of a sequence of nodes connected to each other by pointers. This means that linked lists are usually not contiguous in memory, because each node might be anywhere in memory. They do not need to be close to one another.\nIn Figure 11.3 we can see a diagram of a singly linked list. We begin at the first node (which is usually called “the head of the linked list”). Then, from this first node we uncover the remaining nodes in the structure, by following the locations pointed by the pointers found in each node.\nEach node has two things in it. It has the value that is stored in the current node , and also, a pointer. This pointer points to the next node in the list. If this pointer is null, then, it means that we have reached the end of our linked list.\n\n\n\n\n\n\nFigure 11.3: A diagram of a singly linked list.\n\n\n\nIn Figure 11.4 we can see a diagram of a doubly linked list. The only thing that really changes now is that every node in the linked list has both a pointer to the previous node, and, a pointer to the next node. So every node in a doubly linked list has two pointers in it. These are usually called the prev (for “previous”) and the next (for “next”) pointers of the node.\nIn the singly linked list example, we had only one single pointer in each node, and this singular pointer was always pointing to the next node in the sequence. This means that singly linked lists normally have only the next pointer in them.\n\n\n\n\n\n\nFigure 11.4: A diagram of a doubly linked list.\n\n\n\nLinked lists are available in Zig through the functions SinglyLinkedList() and DoublyLinkedList(), for “singly linked lists” and “doubly linked lists”, respectively. These functions are actually generic functions, which we are going to talk more about in Section 12.2.1.\nFor now, just understand that, in order to create a linked list object, we begin by providing a data type to these functions. This data type defines the type of data that each node in this linked list will store. In the example below, we are creating a singly linked list of u32 values. So each node in this linked list will store a u32 value.\nBoth the SinglyLinkedList() and DoublyLinkedList() functions returns a type, i.e., a struct definition, as output. Therefore, the object Lu32 is actually a struct definition. It defines the type “singly linked list of u32 values”.\nNow that we have the definition of the struct, we need to instantiate a Lu32 object. We normally instantiate struct objects in Zig by using an init() method. But in this case, we are instantiating the struct directly, by using an empty struct literal, in the expression Lu32{}.\nIn this example, we first create multiple node objects, and after we create them, we start to insert and connect these nodes to build the linked list, using the prepend() and insertAfter() methods. Notice that the prepend() method is a method from the linked list object, while the insertAfter() is a method present in the node objects.\nIn essence, the prepend() method inserts a node at the beginning of the linked list. In other words, the node that you provide to this method, becomes the new “head node” of the linked list. It becomes the first node in the list (see Figure 11.3).\nOn the other side, the insertAfter() method is used to basically connect two nodes together. When you provide a node to this method, it creates a pointer to this input node, and stores this pointer in the next attribute of the current node, from which the method was called from.\nBecause doubly linked lists have both a next and a prev attributes in each node (as described in Figure 11.4), a node object created from a DoublyLinkedList object have both an insertBefore() (for prev) and an insertAfter() (for next) methods available.\nThus, if we have used a doubly linked list, we can use the insertBefore() method to store the pointer to the input node in the prev attribute. This would put the input node as the “previous node”, or, the node before the current node. In contrast, the insertAfter() method puts the pointer created to the input node in the next attribute of the current node, and as result, the input node becomes the “next node” of the current node.\nSince we are using a singly linked list in this example, we have only the insertAfter() method available in the node objects that we create from our Lu32 type.\n\nconst std = @import(\"std\");\nconst SinglyLinkedList = std.SinglyLinkedList;\nconst Lu32 = SinglyLinkedList(u32);\n\npub fn main() !void {\n    var list = Lu32{};\n    var one = Lu32.Node{ .data = 1 };\n    var two = Lu32.Node{ .data = 2 };\n    var three = Lu32.Node{ .data = 3 };\n    var four = Lu32.Node{ .data = 4 };\n    var five = Lu32.Node{ .data = 5 };\n\n    list.prepend(&two); // {2}\n    two.insertAfter(&five); // {2, 5}\n    list.prepend(&one); // {1, 2, 5}\n    two.insertAfter(&three); // {1, 2, 3, 5}\n    three.insertAfter(&four); // {1, 2, 3, 4, 5}\n}\n\nThere are other methods available from the linked list object, depending if this object is a singly linked list or a doubly linked list, that might be very useful for you. You can find a summary of them in the bullet points below:\n\nremove() to remove a specific node from the linked list.\nif singly linked list, len() to count how many nodes there is in the linked list.\nif doubly linked list, checkout the len attribute to see how many nodes there is in the linked list.\nif singly linked list, popFirst() to remove the first node (i.e., the “head”) from the linked list.\nif doubly linked list, pop() and popFirst() to remove the last and first nodes from the linked list, respectively.\nif doubly linked list, append() to add a new node to end of the linked list (i.e., inverse of prepend()).",
     "crumbs": [
       "<span class='chapter-number'>11</span>  <span class='chapter-title'>Data Structures</span>"
     ]
@@ -914,7 +914,7 @@
     "href": "Chapters/09-data-structures.html#multi-array-structure",
     "title": "11  Data Structures",
     "section": "11.4 Multi array structure",
-    "text": "11.4 Multi array structure\nZig introduces a new data structure called MultiArrayList(). It is a different version of the dynamic array that we have introduced at Section 11.1. The difference between this structure and the ArrayList() that we know from Section 11.1, is that MultiArrayList() creates a separate dynamic array for each field of the struct that you provide as input.\nConsider the following code example. We create a new custom struct called Person. This struct contains three different data members, or, three different fields. As consequence, when we provide this Person data type as input to MultiArrayList(), this creates a “struct of three different arrays” called PersonArray. In other words, this PersonArray is a struct that contains three internal dynamic arrays in it. One array for each field found in the Person struct definition.\n\nconst std = @import(\"std\");\nconst Person = struct {\n    name: []const u8,\n    age: u8,\n    height: f32,\n};\nconst PersonArray = std.MultiArrayList(Person);\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var people = PersonArray{};\n    defer people.deinit(allocator);\n\n    try people.append(allocator, .{\n        .name = \"Auguste\", .age = 15, .height = 1.54\n    });\n    try people.append(allocator, .{\n        .name = \"Elena\", .age = 26, .height = 1.65\n    });\n    try people.append(allocator, .{\n        .name = \"Michael\", .age = 64, .height = 1.87\n    });\n}\n\nIn other words, instead of creating an array of “persons”, the MultiArrayList() function creates a “struct of arrays”. Each data member of this struct is a different array that stores the values of a specific field from the Person values that were added (or, appended) to this “struct of arrays”. One important detail is that each of these separate internal arrays stored inside PersonArray are dynamic arrays. This means that these arrays can grow in capacity automatically as needed, to accomodate more values.\nThe Figure 11.5 exposed below presents a diagram that describes the PersonArray struct that we have created in the previous code example. Notice that the values of the data members present in each of the three Person values that we have appended into the PersonArray object , are scattered across three different internal arrays of the PersonArray object.\n\n\n\n\n\n\nFigure 11.5: A diagram of the PersonArray struct.\n\n\n\nYou can easily access each of these arrays separately, and iterate over the values of each array. For that, you will need to call the items() method from the PersonArray object, and provide as input to this method, the name of the field that you want to iterate over. If you want to iterate through the .age array for example, then, you need to call items(.age) from the PersonArray object, like in the example below:\n\nfor (people.items(.age)) |*age| {\n    try stdout.print(\"Age: {d}\\n\", .{age.*});\n}\n\nAge: 15\nAge: 26\nAge: 64\nIn the above example, we are iterating over the values of the .age array, or, the internal array of the PersonArray object that contains the values of the age data member from the Person values that were added to the multi array struct.\nIn this example we are calling the items() method directly from the PersonArray object. However, it is recommended on most situations to call this items() method from a “slice object”, which you can create from the slice() method. The reason for this is that calling items() multiple times have better performance if you use a slice object.\nTherefore, if you are planning to access only one of the internal arrays from your “multi array struct”, it is fine to call items() directly from the multi array object. But if you need to access many of the internal arrays from your “multi array struct”, then, you will likely need to call items() more than once, and, in such circumstance, is better to call items() through a slice object. The example below demonstrates the use of such object:\n\nvar slice = people.slice();\nfor (slice.items(.age)) |*age| {\n    age.* += 10;\n}\nfor (slice.items(.name), slice.items(.age)) |*n,*a| {\n    try stdout.print(\n        \"Name: {s}, Age: {d}\\n\", .{n.*, a.*}\n    );\n}\n\nName: Auguste, Age: 25\nName: Elena, Age: 36\nName: Michael, Age: 74",
+    "text": "11.4 Multi array structure\nZig introduces a new data structure called MultiArrayList(). It’s a different version of the dynamic array that we have introduced in Section 11.1. The difference between this structure and the ArrayList() that we know from Section 11.1, is that MultiArrayList() creates a separate dynamic array for each field of the struct that you provide as input.\nConsider the following code example. We create a new custom struct called Person. This struct contains three different data members, or, three different fields. As consequence, when we provide this Person data type as input to MultiArrayList(), this creates a “struct of three different arrays” called PersonArray. In other words, this PersonArray is a struct that contains three internal dynamic arrays in it. One array for each field found in the Person struct definition.\n\nconst std = @import(\"std\");\nconst Person = struct {\n    name: []const u8,\n    age: u8,\n    height: f32,\n};\nconst PersonArray = std.MultiArrayList(Person);\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var people = PersonArray{};\n    defer people.deinit(allocator);\n\n    try people.append(allocator, .{\n        .name = \"Auguste\", .age = 15, .height = 1.54\n    });\n    try people.append(allocator, .{\n        .name = \"Elena\", .age = 26, .height = 1.65\n    });\n    try people.append(allocator, .{\n        .name = \"Michael\", .age = 64, .height = 1.87\n    });\n}\n\nIn other words, instead of creating an array of “persons”, the MultiArrayList() function creates a “struct of arrays”. Each data member of this struct is a different array that stores the values of a specific field from the Person values that were added (or, appended) to this “struct of arrays”. One important detail is that each of these separate internal arrays stored inside PersonArray are dynamic arrays. This means that these arrays can grow in capacity automatically as needed, to accomodate more values.\nThe Figure 11.5 exposed below presents a diagram that describes the PersonArray struct that we have created in the previous code example. Notice that the values of the data members present in each of the three Person values that we have appended into the PersonArray object , are scattered across three different internal arrays of the PersonArray object.\n\n\n\n\n\n\nFigure 11.5: A diagram of the PersonArray struct.\n\n\n\nYou can easily access each of these arrays separately, and iterate over the values of each array. For that, you will need to call the items() method from the PersonArray object, and provide as input to this method, the name of the field that you want to iterate over. If you want to iterate through the .age array for example, then, you need to call items(.age) from the PersonArray object, like in the example below:\n\nfor (people.items(.age)) |*age| {\n    try stdout.print(\"Age: {d}\\n\", .{age.*});\n}\n\nAge: 15\nAge: 26\nAge: 64\nIn the above example, we are iterating over the values of the .age array, or, the internal array of the PersonArray object that contains the values of the age data member from the Person values that were added to the multi array struct.\nIn this example we are calling the items() method directly from the PersonArray object. However, in most situations it’s recommened to call this items() method from a “slice object”, which you can create from the slice() method. The reason for this is that calling items() multiple times have better performance if you use a slice object.\nTherefore, if you are planning to access only one of the internal arrays from your “multi array struct”, it’s fine to call items() directly from the multi array object. But if you need to access many of the internal arrays from your “multi array struct”, then, you will likely need to call items() more than once, and, in such circumstance, is better to call items() through a slice object. The example below demonstrates the use of such object:\n\nvar slice = people.slice();\nfor (slice.items(.age)) |*age| {\n    age.* += 10;\n}\nfor (slice.items(.name), slice.items(.age)) |*n,*a| {\n    try stdout.print(\n        \"Name: {s}, Age: {d}\\n\", .{n.*, a.*}\n    );\n}\n\nName: Auguste, Age: 25\nName: Elena, Age: 36\nName: Michael, Age: 74",
     "crumbs": [
       "<span class='chapter-number'>11</span>  <span class='chapter-title'>Data Structures</span>"
     ]
@@ -944,7 +944,7 @@
     "href": "Chapters/10-stack-project.html",
     "title": "12  Project 3 - Building a stack data structure",
     "section": "",
-    "text": "12.1 Understanding comptime in Zig\nOne of the key features of Zig is comptime. This keyword introduces a whole new concept and paradigm, that is tightly connected with the compilation process. At Section 3.1.1 we have described the importance and the role that “compile-time versus runtime” plays into Zig. At that section, we learned that the rules applied to a value/object change a lot depending on whether this value is known at compile-time, or just at runtime.\nThe comptime keyword is strongly related to these two spaces in time (compile-time and runtime). Let’s quickly recap the differences. Compile-time is the period of time when your Zig source code is being compiled by the zig compiler, while the runtime is the period of time when your Zig program is being executed, i.e. when we execute the binary files that were generated by the zig compiler.\nThere are three ways in which you can apply the comptime keyword, which are:",
+    "text": "12.1 Understanding comptime in Zig\nOne of the key features of Zig is comptime. This keyword introduces a whole new concept and paradigm, that is tightly connected with the compilation process. In Section 3.1.1 we have described the importance and the role that “compile-time versus runtime” plays into Zig. In that section, we learned that the rules applied to a value/object change a lot depending on whether this value is known at compile-time, or just at runtime.\nThe comptime keyword is strongly related to these two spaces in time (compile-time and runtime). Let’s quickly recap the differences. Compile-time is the period of time when your Zig source code is being compiled by the zig compiler, while the runtime is the period of time when your Zig program is being executed, i.e., when we execute the binary files that were generated by the zig compiler.\nThere are three ways in which you can apply the comptime keyword, which are:",
     "crumbs": [
       "<span class='chapter-number'>12</span>  <span class='chapter-title'>Project 3 - Building a stack data structure</span>"
     ]
@@ -954,7 +954,7 @@
     "href": "Chapters/10-stack-project.html#sec-comptime",
     "title": "12  Project 3 - Building a stack data structure",
     "section": "",
-    "text": "apply comptime on a function argument.\napply comptime on an object.\napply comptime on a block of expressions.\n\n\n12.1.1 Applying over a function argument\nWhen you apply the comptime keyword on a function argument, you are saying to the zig compiler that the value assigned to that particular function argument must be known at compile-time. We explained in details at Section 3.1.1 what exactly “value known at compile-time” means, so, in case you have doubts about this idea, come back to that section.\nNow let’s think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement to that particular function argument. If the programmer accidentally tries to give a value to this function argument that is not known at compile time, the zig compiler will notice this problem, and as a consequence, it will raise a compilation error saying that it cannot compile your program. Because you are providing a value that is “runtime known” to a function argument that must be “compile-time known”.\nTake a look at this very simple example below, where we define a twice() function, that simply doubles the input value named num. Notice that we use the comptime keyword before the name of the function argument. This keyword is marking the function argument num as a “comptime argument”.\nThat is a function argument whose value must be compile-time known. This is why the expression twice(5678) is valid, and no compilation errors are raised. Because the value 5678 is compile-time known, so this is the expected behaviour for this function.\n\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n\n1/1 filea72d248f97f8.test.test comptime...OKAll 1 \n   tests passed.\n\n\nBut what if we provide a number that is not compile-time known to this function? For example, we might provide a different input value to this function depending on the target OS of our compilation process. The code example below demonstrates such case.\nBecause the value of the object n is determined at runtime, we cannot provide this object as input to the twice() function. The zig compiler will not allow it, because we marked the num argument as a “comptime argument”. That is why the zig compiler raises the compile-time error exposed below:\n\nconst builtin = @import(\"builtin\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    var n: u32 = undefined;\n    if (builtin.target.os.tag == .windows) {\n        n = 1234;\n    } else {\n        n = 5678;\n    }\n    _ = twice(n);\n}\n\nt.zig:12:16: error: runtime-known argument passed to comptime parameter \nComptime arguments are frequently used on functions that return some sort of generic structure. In fact, comptime is the essence (or the basis) to make generics in Zig. We are going to talk more about generics at Section 12.2.\nFor now, let’s take a look at this code example from Seguin (2024). You can see that this IntArray() function have one argument named length. This argument is marked as comptime, and receives a value of type usize as input. So the value given to this argument must be compile-time known. We can also see that this function returns an array of i64 values as output.\n\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n\nNow, the key component of this function is the length argument. This argument is used to determine the size of the array that is produced by the function. Let’s think about the consequences of that. If the size of the array is dependent on the value assigned to the length argument, this means that the data type of the output of the function depends on the value of this length argument.\nLet this statement sink for a bit in your mind. As I described at Section 1.2.2, Zig is a strongly-typed language, especially on function declarations. So every time we write a function in Zig, we have to annotate the data type of the value returned by the function. But how can we do that, if this data type depends on the value given to the argument of the function?\nThink about this for a second. If length is equal to 3 for example, then, the return type of the function is [3]i64. But if length is equal to 40, then, the return type becomes [40]i64. At this point the zig compiler would be confused, and raise a compilation error, saying something like this:\n\nHey! You have annotated that this function should return a [3]i64 value, but I got a [40]i64 value instead! This doesn’t look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when the type keyword comes in. This type keyword is basically saying to the zig compiler that this function will return some data type as output, but it doesn’t know yet what exactly data type that is. We will talk more about this at Section 12.2.\n\n\n12.1.2 Applying over an expression\nWhen you apply the comptime keyword over an expression, then, it is guaranteed that the zig compiler will execute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time (e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the zig compiler will raise a compilation error.\nTake this example from the official documentation of Zig (Zig Software Foundation 2024). We are executing the same fibonacci() function both at runtime, and, at compile-time. The function is by default executed at runtime, but because we use the comptime keyword at the second “try expression”, this expression is executed at compile-time.\nThis might be a bit confusing for some people. Yes! When I say that this expression is executed at compile-time, I mean that this expression is compiled and executed while the zig compiler is compiling your Zig source code.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n\n1/1 filea72d3cf7abe2.test.fibonacci...OKAll 1 test\n  ts passed.\n\n\nA lot of your Zig source code might be potentially executed at compile-time, because the zig compiler can figure it out the output of some expressions. Especially if these expressions depends only at compile-time known values. We have talked about this at Section 3.1.1.\nBut when you use the comptime keyword on an expression, there is no “it might be executed at compile-time” anymore. With the comptime keyword you are ordering the zig compiler to execute this expression at compile-time. You are imposing this rule, it is guaranteed that the compiler will always execute it at compile-time. Or, at least, the compiler will try to execute it. If the compiler cannot execute the expression for whatever reason, the compiler will raise a compilation error.\n\n\n12.1.3 Applying over a block\nBlocks were described at Section 1.7. When you apply the comptime keyword over a block of expressions, you get essentially the same effect when you apply this keyword to a single expression. That is, the entire block of expressions is executed at compile-time by the zig compiler.\nIn the example below, we mark the block labeled of blk as a comptime block, and, therefore, the expressions inside this block are executed at compile-time.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n\n1/1 filea72d6353d586.test.fibonacci in a block...O\n  OKAll 1 tests passed.",
+    "text": "apply comptime on a function argument.\napply comptime on an object.\napply comptime on a block of expressions.\n\n\n12.1.1 Applying over a function argument\nWhen you apply the comptime keyword on a function argument, you are saying to the zig compiler that the value assigned to that particular function argument must be known at compile-time. We explained in detail in Section 3.1.1 what exactly “value known at compile-time” means. So if you have any doubts about this idea, refer back to that section.\nNow let’s think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement to that particular function argument. If the programmer accidentally tries to give a value to this function argument that is not known at compile time, the zig compiler will notice this problem, and as a consequence, it will raise a compilation error saying that it cannot compile your program. Because you are providing a value that is “runtime known” to a function argument that must be “compile-time known”.\nTake a look at this very simple example below, where we define a twice() function, that simply doubles the input value named num. Notice that we use the comptime keyword before the name of the function argument. This keyword is marking the function argument num as a “comptime argument”.\nThat is a function argument whose value must be compile-time known. This is why the expression twice(5678) is valid, and no compilation errors are raised. Because the value 5678 is compile-time known, so this is the expected behaviour for this function.\n\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n\n1/1 file833f3ad20be9.test.test comptime...OKAll 1 \n   tests passed.\n\n\nBut what if we provide a number that is not compile-time known to this function? For example, we might provide a different input value to this function depending on the target OS of our compilation process. The code example below demonstrates such case.\nBecause the value of the object n is determined at runtime, we cannot provide this object as input to the twice() function. The zig compiler will not allow it, because we marked the num argument as a “comptime argument”. That is why the zig compiler raises the compile-time error exposed below:\n\nconst builtin = @import(\"builtin\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    var n: u32 = undefined;\n    if (builtin.target.os.tag == .windows) {\n        n = 1234;\n    } else {\n        n = 5678;\n    }\n    _ = twice(n);\n}\n\nt.zig:12:16: error: runtime-known argument passed to comptime parameter\nComptime arguments are frequently used on functions that return some sort of generic structure. In fact, comptime is the essence (or the basis) to make generics in Zig. We are going to talk more about generics in Section 12.2.\nFor now, let’s take a look at this code example from Seguin (2024). You can see that this IntArray() function has one argument named length. This argument is marked as comptime, and receives a value of type usize as input. So the value given to this argument must be compile-time known. We can also see that this function returns an array of i64 values as output.\n\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n\nNow, the key component of this function is the length argument. This argument is used to determine the size of the array that is produced by the function. Let’s think about the consequences of that. If the size of the array is dependent on the value assigned to the length argument, this means that the data type of the output of the function depends on the value of this length argument.\nLet this statement sink for a bit in your mind. As I described in Section 1.2.2, Zig is a strongly-typed language, especially on function declarations. So every time we write a function in Zig, we have to annotate the data type of the value returned by the function. But how can we do that, if this data type depends on the value given to the argument of the function?\nThink about this for a second. If length is equal to 3 for example, then, the return type of the function is [3]i64. But if length is equal to 40, then, the return type becomes [40]i64. At this point the zig compiler would be confused, and raise a compilation error, saying something like this:\n\nHey! You have annotated that this function should return a [3]i64 value, but I got a [40]i64 value instead! This doesn’t look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when the type keyword comes in. This type keyword is basically saying to the zig compiler that this function will return some data type as output, but it doesn’t know yet what exactly data type that is. We will talk more about this in Section 12.2.\n\n\n12.1.2 Applying over an expression\nWhen you apply the comptime keyword over an expression, then, it is guaranteed that the zig compiler will execute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time (e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the zig compiler will raise a compilation error.\nTake this example from the official documentation of Zig (Zig Software Foundation 2024). We are executing the same fibonacci() function both at runtime, and, at compile-time. The function is executed by default at runtime, but because we use the comptime keyword in the second “try expression”, this expression is executed at compile-time.\nThis might be a bit confusing for some people. Yes! When I say that this expression is executed at compile-time, I mean that this expression is compiled and executed while the zig compiler is compiling your Zig source code.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n\n1/1 file833f119d55a3.test.fibonacci...OKAll 1 test\n  ts passed.\n\n\nA lot of your Zig source code might be potentially executed at compile-time, because the zig compiler can figure out the output of some expressions. Especially if these expressions depend only on compile-time known values. We have talked about this in Section 3.1.1.\nBut when you use the comptime keyword on an expression, there is no “it might be executed at compile-time” anymore. With the comptime keyword you are ordering the zig compiler to execute this expression at compile-time. You are imposing this rule, it is guaranteed that the compiler will always execute it at compile-time. Or, at least, the compiler will try to execute it. If the compiler cannot execute the expression for whatever reason, the compiler will raise a compilation error.\n\n\n12.1.3 Applying over a block\nBlocks were described in Section 1.7. When you apply the comptime keyword to a block of expressions, you get essentially the same effect as when you apply this keyword to a single expression. That is, the entire block of expressions is executed at compile-time by the zig compiler.\nIn the example below, we mark the block labeled of blk as a comptime block, and, therefore, the expressions inside this block are executed at compile-time.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n\n1/1 file833f6ccf145c.test.fibonacci in a block...O\n  OKAll 1 tests passed.",
     "crumbs": [
       "<span class='chapter-number'>12</span>  <span class='chapter-title'>Project 3 - Building a stack data structure</span>"
     ]
@@ -964,7 +964,7 @@
     "href": "Chapters/10-stack-project.html#sec-generics",
     "title": "12  Project 3 - Building a stack data structure",
     "section": "12.2 Introducing Generics",
-    "text": "12.2 Introducing Generics\nFirst of all, what is a generic? Generic is the idea to allow a type (f64, u8, u32, bool, and also, user-defined types, like the User struct that we defined at Section 2.3) to be a parameter to methods, classes and interfaces (Geeks for Geeks 2024). In other words, a “generic” is a class (or a method) that can work with multiple data types.\nFor example, in Java, generics are created through the operator &lt;&gt;. With this operator, a Java class is capable of receiving a data type as input, and therefore, the class can fit its features according to this input data type. As another example, generics in C++ are supported through the concept of templates. Class templates in C++ are generics.\nIn Zig, generics are implemented through comptime. The comptime keyword allows us to collect a data type at compile time, and pass this data type as input to a piece of code.\n\n12.2.1 A generic function\nTake the max() function exposed below as a first example. This function is essentially a “generic function”. In this function, we have a comptime function argument named T. Notice that this T argument have a data type of type. Weird right? This type keyword is the “father of all types”, or, “the type of types” in Zig.\nBecause we have used this type keyword in the T argument, we are telling the zig compiler that this T argument will receive some data type as input. Also notice the use of the comptime keyword in this argument. As I described at Section 12.1, every time you use this keyword in a function argument, this means that the value of this argument must be known at compile-time. This makes sense, right? Because there is no data type that is not known at compile-time.\nThink about this. Every data type that you will ever write is always known at compile-time. Especially because data types are an essential information for the compiler to actually compile your source code. Having this in mind, makes sense to mark this argument as a comptime argument.\n\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a &gt; b) a else b;\n}\n\nAlso notice that the value of the T argument is actually used to define the data type of the other arguments in the function, a and b, and also at the return type annotation of the function. That is, the data type of these arguments (a and b), and, the return data type of the function itself, are determined by the input value given to the T argument.\nAs a result, we have a generic function that works with different data types. For example, I can provide u8 values to this max() function, and it will work as expected. But if I provide f64 values instead, it will also work as expected. Without a generic function, I would have to write a different max() function for each one of the data types that I wanted to use. This generic function provides a very useful shortcut for us.\n\nconst std = @import(\"std\");\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a &gt; b) a else b;\n}\ntest \"test max\" {\n    const n1 = max(u8, 4, 10);\n    std.debug.print(\"Max n1: {d}\\n\", .{n1});\n    const n2 = max(f64, 89.24, 64.001);\n    std.debug.print(\"Max n2: {d}\\n\", .{n2});\n}\n\nMax n1: 10\nMax n2: 89.24\n\n\n12.2.2 A generic data structure\nEvery data structure that you find in the Zig Standard Library (e.g. ArrayList, HashMap, etc.) is essentially a generic data structure. These data structures are generic in the sense that they work with any data type you want. You just say which is the data type of the values that are going to be stored in this data structure, and they just work as expected.\nA generic data structure in Zig is how you replicate a generic class from Java, or, a class template from C++. But you may quest yourself: how do we build a generic data structure in Zig?\nThe basic idea is to write a generic function that creates the data structure definition for the specific type we want. In other words, this generic function behaves as a “factory of data structures”. The generic function outputs the struct definition that defines this data structure for a specific data type.\nTo create such function, we need to add a comptime argument to this function that receives a data type as input. We already learned how to do this at the previous section (Section 12.2.1). I think the best way to demonstrate how to create a generic data structure is to actually write one. This where we go into our next small project in this book. This one is a very small project, which is to write a generic stack data structure.",
+    "text": "12.2 Introducing Generics\nFirst of all, what is a generic? Generic is the idea to allow a type (f64, u8, u32, bool, and also, user-defined types, like the User struct that we defined in Section 2.3) to be a parameter to methods, classes and interfaces (Geeks for Geeks 2024). In other words, a “generic” is a class (or a method) that can work with multiple data types.\nFor example, in Java, generics are created through the operator &lt;&gt;. With this operator, a Java class is capable of receiving a data type as input, and therefore, the class can fit its features according to this input data type. As another example, generics in C++ are supported through the concept of templates. Class templates in C++ are generics.\nIn Zig, generics are implemented through comptime. The comptime keyword allows us to collect a data type at compile time, and pass this data type as input to a piece of code.\n\n12.2.1 A generic function\nTake the max() function exposed below as a first example. This function is essentially a “generic function”. In this function, we have a comptime function argument named T. Notice that this T argument has a data type of type. Weird right? This type keyword is the “father of all types”, or, “the type of types” in Zig.\nBecause we have used this type keyword in the T argument, we are telling the zig compiler that this T argument will receive some data type as input. Also notice the use of the comptime keyword in this argument. As I described in Section 12.1, every time you use this keyword in a function argument, this means that the value of this argument must be known at compile-time. This makes sense, right? Because there is no data type that is not known at compile-time.\nThink about this. Every data type that you will ever write is always known at compile-time. Especially because data types are an essential information for the compiler to actually compile your source code. Having this in mind, makes sense to mark this argument as a comptime argument.\n\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a &gt; b) a else b;\n}\n\nAlso notice that the value of the T argument is actually used to define the data type of the other arguments in the function, a and b, and also at the return type annotation of the function. That is, the data type of these arguments (a and b), and, the return data type of the function itself, are determined by the input value given to the T argument.\nAs a result, we have a generic function that works with different data types. For example, I can provide u8 values to this max() function, and it will work as expected. But if I provide f64 values instead, it will also work as expected. Without a generic function, I would have to write a different max() function for each data type I wanted to use. This generic function provides a very useful shortcut for us.\n\nconst std = @import(\"std\");\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a &gt; b) a else b;\n}\ntest \"test max\" {\n    const n1 = max(u8, 4, 10);\n    std.debug.print(\"Max n1: {d}\\n\", .{n1});\n    const n2 = max(f64, 89.24, 64.001);\n    std.debug.print(\"Max n2: {d}\\n\", .{n2});\n}\n\nMax n1: 10\nMax n2: 89.24\n\n\n12.2.2 A generic data structure\nEvery data structure that you find in the Zig Standard Library (e.g. ArrayList, HashMap, etc.) is essentially a generic data structure. These data structures are generic in the sense that they work with any data type you want. You just say which is the data type of the values that are going to be stored in this data structure, and they just work as expected.\nA generic data structure in Zig is how you replicate a generic class from Java, or, a class template from C++. But you may ask yourself: how do we build a generic data structure in Zig?\nThe basic idea is to write a generic function that creates the data structure definition for the specific type we want. In other words, this generic function behaves as a “factory of data structures”. The generic function outputs the struct definition that defines this data structure for a specific data type.\nTo create such function, we need to add a comptime argument to this function that receives a data type as input. We already learned how to do this in the previous section (Section 12.2.1). I think the best way to demonstrate how to create a generic data structure is to actually write one. This where we go into our next small project in this book. This one is a very small project, which is to write a generic stack data structure.",
     "crumbs": [
       "<span class='chapter-number'>12</span>  <span class='chapter-title'>Project 3 - Building a stack data structure</span>"
     ]
@@ -984,7 +984,7 @@
     "href": "Chapters/10-stack-project.html#writing-the-stack-data-structure",
     "title": "12  Project 3 - Building a stack data structure",
     "section": "12.4 Writing the stack data structure",
-    "text": "12.4 Writing the stack data structure\nWe are going to write the stack data structure in two steps. First, we are going to implement a stack that can only store u32 values. Then, after that, we are going to extend our implementation to make it generic, so that it works with any data type we want.\nFirst, we need to decide how the values will be stored inside the stack. There are multiple ways to implement the storage behind a stack structure. Some people prefer to use a doubly linked list, some others prefer to use a dynamic array, etc. In this example we are going to use an array behind the hood, to store the values in the stack, which is the items data member of our Stack struct definition.\nAlso notice in our Stack struct that we have three other data members: capacity, length and allocator. The capacity member contains the capacity of the underlying array that stores the values in the stack. The length contains the number of values that are currently being stored in the stack. And the allocator contains the allocator object that will be used by the stack structure whenever it needs to allocate more space for the values that are being stored.\nWe begin by defining an init() method of this struct, which is going to be responsible for instantiating a Stack object. Notice that, inside this init() method, we start by allocating an array with the capacity specified in the capacity argument.\n\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst Stack = struct {\n    items: []u32,\n    capacity: usize,\n    length: usize,\n    allocator: Allocator,\n\n    pub fn init(allocator: Allocator, capacity: usize) !Stack {\n        var buf = try allocator.alloc(u32, capacity);\n        return .{\n            .items = buf[0..],\n            .capacity = capacity,\n            .length = 0,\n            .allocator = allocator,\n        };\n    }\n};\n\n\n12.4.1 Implementing the push operation\nNow that we have written the basic logic to create a new Stack object, we can start writing the logic responsible for performing a push operation. Remember, a push operation in a stack data structure is the operation responsible for adding a new value to the stack.\nSo how can we add a new value to the Stack object that we have? The push() function exposed below is a possible answer to this question. Remember from what we discussed at Section 12.3 that values are always added to the top of the stack. This means that this push() function must always find the element in the underlying array that currently represents the top position of the stack, and then, add the input value there.\nFirst, we have an if statement in this function. This if statement is checking whether we need to expand the underlying array to store this new value that we are adding to the stack. In other words, maybe the underlying array does not have enough capacity to store this new value, and, in this case, we need to expand our array to get the capacity that we need.\nSo, if the logical test in this if statement returns true, it means that the array does not have enough capacity, and we need to expand it before we store this new value. So inside this if statement we are executing the necessary expressions to expand the underlying array. Notice that we use the allocator object to allocate a new array that is twice as bigger than the current array (self.capacity * 2).\nAfter that, we use a different built-in function named @memcpy(). This built-in function is equivalent to the memcpy() function from the C Standard Library1. It is used to copy the values from one block of memory to another block of memory. In other words, you can use this function to copy the values from one array into another array.\nWe are using this @memcpy() built-in function to copy the values that are currently stored in the underlying array of the stack object (self.items) into our new and bigger array that we have allocated (new_buf). After we execute this function, the new_buf contains a copy of the values that are present at self.items.\nNow that we have secured a copy of our current values in the new_buf object, we can now free the memory currently allocated at self.items. After that, we just need to assign our new and bigger array to self.items. This is the sequence of steps necessary to expand our array.\n\npub fn push(self: *Stack, val: u32) !void {\n    if ((self.length + 1) &gt; self.capacity) {\n        var new_buf = try self.allocator.alloc(\n            u32, self.capacity * 2\n        );\n        @memcpy(\n            new_buf[0..self.capacity], self.items\n        );\n        self.allocator.free(self.items);\n        self.items = new_buf;\n        self.capacity = self.capacity * 2;\n    }\n\n    self.items[self.length] = val;\n    self.length += 1;\n}\n\nAfter we make sure that we have enough room to store this new value that we are adding to the stack, all we have to do is to assign this value to the top element in this stack, and, increase the value of the length attribute by one. We find the top element in the stack by using the length attribute.\n\n\n12.4.2 Implementing the pop operation\nNow we can implement the pop operation of our stack object. This is a much easier operation to implement, and the pop() method below summarises all the logic that is needed.\nWe just have to find the element in the underlying array that currently represents the top of the stack, and set this element to “undefined”, to indicate that this element is “empty”. After that, we also need to decrease the length attribute of the stack by one.\nIf the current length of the stack is zero, it means that there is no values being stored in the stack currently. So, in this case, we could just return from the function and do nothing really. This is what the if statement inside this function is checking for.\n\npub fn pop(self: *Stack) void {\n    if (self.length == 0) return;\n\n    self.items[self.length - 1] = undefined;\n    self.length -= 1;\n}\n\n\n\n12.4.3 Implementing the deinit method\nWe have implemented the methods responsible for the two main operations associated with the stack data structure, which is pop() and push(), and we also have implemented the method responsible for instantiating a new Stack object, which is the init() method.\nBut now, we need to implement also the method responsible for destroying a Stack object. In Zig, this task is commonly associated with the method named deinit(). Most struct objects in Zig have such method, and it is commonly nicknamed “the destructor method”.\nIn theory, all we have to do to destroy the Stack object is to make sure that we free the allocated memory for the underlying array, using the allocator object that is stored inside the Stack object. This is what the deinit() method below is doing.\n\npub fn deinit(self: *Stack) void {\n    self.allocator.free(self.items);\n}",
+    "text": "12.4 Writing the stack data structure\nWe are going to write the stack data structure in two steps. First, we are going to implement a stack that can only store u32 values. Then, after that, we are going to extend our implementation to make it generic, so that it works with any data type we want.\nFirst, we need to decide how the values will be stored inside the stack. There are multiple ways to implement the storage behind a stack structure. Some people prefer to use a doubly linked list, others prefer to use a dynamic array, etc. In this example we are going to use an array behind the hood, to store the values in the stack, which is the items data member of our Stack struct definition.\nAlso notice in our Stack struct that we have three other data members: capacity, length and allocator. The capacity member contains the capacity of the underlying array that stores the values in the stack. The length contains the number of values that are currently being stored in the stack. And the allocator contains the allocator object that will be used by the stack structure whenever it needs to allocate more space for the values that are being stored.\nWe begin by defining an init() method of this struct, which is going to be responsible for instantiating a Stack object. Notice that, inside this init() method, we start by allocating an array with the capacity specified in the capacity argument.\n\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst Stack = struct {\n    items: []u32,\n    capacity: usize,\n    length: usize,\n    allocator: Allocator,\n\n    pub fn init(allocator: Allocator, capacity: usize) !Stack {\n        var buf = try allocator.alloc(u32, capacity);\n        return .{\n            .items = buf[0..],\n            .capacity = capacity,\n            .length = 0,\n            .allocator = allocator,\n        };\n    }\n};\n\n\n12.4.1 Implementing the push operation\nNow that we have written the basic logic to create a new Stack object, we can start writing the logic responsible for performing a push operation. Remember, a push operation in a stack data structure is the operation responsible for adding a new value to the stack.\nSo how can we add a new value to the Stack object that we have? The push() function exposed below is a possible answer to this question. Remember from what we discussed in Section 12.3 that values are always added to the top of the stack. This means that this push() function must always find the element in the underlying array that currently represents the top position of the stack, and then, add the input value there.\nFirst, we have an if statement in this function. This if statement is checking whether we need to expand the underlying array to store this new value that we are adding to the stack. In other words, maybe the underlying array does not have enough capacity to store this new value, and, in this case, we need to expand our array to get the capacity that we need.\nSo, if the logical test in this if statement returns true, it means that the array does not have enough capacity, and we need to expand it before we store this new value. So inside this if statement we are executing the necessary expressions to expand the underlying array. Notice that we use the allocator object to allocate a new array that is twice as bigger than the current array (self.capacity * 2).\nAfter that, we use a different built-in function named @memcpy(). This built-in function is equivalent to the memcpy() function from the C Standard Library1. It’s used to copy the values from one block of memory to another block of memory. In other words, you can use this function to copy the values from one array into another array.\nWe are using this @memcpy() built-in function to copy the values that are currently stored in the underlying array of the stack object (self.items) into our new and bigger array that we have allocated (new_buf). After we execute this function, the new_buf contains a copy of the values that are present at self.items.\nNow that we have secured a copy of our current values in the new_buf object, we can now free the memory currently allocated at self.items. After that, we just need to assign our new and bigger array to self.items. This is the sequence of steps necessary to expand our array.\n\npub fn push(self: *Stack, val: u32) !void {\n    if ((self.length + 1) &gt; self.capacity) {\n        var new_buf = try self.allocator.alloc(\n            u32, self.capacity * 2\n        );\n        @memcpy(\n            new_buf[0..self.capacity], self.items\n        );\n        self.allocator.free(self.items);\n        self.items = new_buf;\n        self.capacity = self.capacity * 2;\n    }\n\n    self.items[self.length] = val;\n    self.length += 1;\n}\n\nAfter we make sure that we have enough room to store this new value that we are adding to the stack, all we have to do is to assign this value to the top element in this stack, and, increase the value of the length attribute by one. We find the top element in the stack by using the length attribute.\n\n\n12.4.2 Implementing the pop operation\nNow we can implement the pop operation of our stack object. This is a much easier operation to implement, and the pop() method below summarises all the logic that is needed.\nWe just have to find the element in the underlying array that currently represents the top of the stack, and set this element to “undefined”, to indicate that this element is “empty”. After that, we also need to decrease the length attribute of the stack by one.\nIf the current length of the stack is zero, it means that there is no values being stored in the stack currently. So, in this case, we could just return from the function and do nothing really. This is what the if statement inside this function is checking for.\n\npub fn pop(self: *Stack) void {\n    if (self.length == 0) return;\n\n    self.items[self.length - 1] = undefined;\n    self.length -= 1;\n}\n\n\n\n12.4.3 Implementing the deinit method\nWe have implemented the methods responsible for the two main operations associated with the stack data structure, which is pop() and push(), and we also have implemented the method responsible for instantiating a new Stack object, which is the init() method.\nBut now, we need to implement also the method responsible for destroying a Stack object. In Zig, this task is commonly associated with the method named deinit(). Most struct objects in Zig have such method, and it is commonly nicknamed “the destructor method”.\nIn theory, all we have to do to destroy the Stack object is to make sure that we free the allocated memory for the underlying array, using the allocator object that is stored inside the Stack object. This is what the deinit() method below is doing.\n\npub fn deinit(self: *Stack) void {\n    self.allocator.free(self.items);\n}",
     "crumbs": [
       "<span class='chapter-number'>12</span>  <span class='chapter-title'>Project 3 - Building a stack data structure</span>"
     ]
@@ -994,7 +994,7 @@
     "href": "Chapters/10-stack-project.html#making-it-generic",
     "title": "12  Project 3 - Building a stack data structure",
     "section": "12.5 Making it generic",
-    "text": "12.5 Making it generic\nNow that we have implemented the basic skeleton of our stack data structure, we can now focus on discussing how can we make it generic. How can we make this basic skeleton to work not only with u32 values, but also, with any other data type we want? For example, we might need to create a stack object to store User values in it. How can we make this possible? The answer lies on the use of generics and comptime.\nAs I described at Section 12.2.2, the basic idea is to write a generic function that returns a struct definition as output. In theory, we do not need much to transform our Stack struct into a generic data structure. All that we need to do is to transform the underlying array of the stack into a generic array.\nIn other words, this underlying array needs to be a “chameleon”. It needs to adapt, and transform it into an array of any data type that we want. For example, if we need to create a stack that will store u8 values, then, this underlying array needs to be a u8 array (i.e. []u8). But if we need to store User values instead, then, this array needs to be a User array (i.e. []User). Etc.\nWe do that by using a generic function. Because a generic function can receive a data type as input, and we can pass this data type to the struct definition of our Stack object. Therefore, we can use the generic function to create a Stack object that can store the data type we want. If we want to create a stack structure that stores User values, we pass the User data type to this generic function, and it will create for us the struct definition that describes a Stack object that can store User values in it.\nLook at the code example below. I have omitted some parts of the Stack struct definition for brevity reasons. However, if a specific part of our Stack struct is not exposed here in this example, then it is because this part did not change from the previous example. It remains the same.\n\nfn Stack(comptime T: type) type {\n    return struct {\n        items: []T,\n        capacity: usize,\n        length: usize,\n        allocator: Allocator,\n        const Self = @This();\n\n        pub fn init(allocator: Allocator,\n                    capacity: usize) !Stack(T) {\n            var buf = try allocator.alloc(T, capacity);\n            return .{\n                .items = buf[0..],\n                .capacity = capacity,\n                .length = 0,\n                .allocator = allocator,\n            };\n        }\n\n        pub fn push(self: *Self, val: T) !void {\n        // Truncate the rest of the struct\n    };\n}\n\nNotice that we have created a function in this example named Stack(). This function takes a type as input, and passes this type to the struct definition of our Stack object. The data member items is now, an array of type T, which is the data type that we have provided as input to the function. The function argument val in the push() function is now a value of type T too.\nWe can just provide a data type to this function, and it will create a definition of a Stack object that can store values of the data type that we have provided. In the example below, we are creating the definition of a Stack object that can store u8 values in it. This definition is stored at the Stacku8 object. This Stacku8 object becomes our new struct, it is the struct that we are going to use to create our Stack object.\n\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst Stacku8 = Stack(u8);\nvar stack = try Stacku8.init(allocator, 10);\ndefer stack.deinit();\ntry stack.push(1);\ntry stack.push(2);\ntry stack.push(3);\ntry stack.push(4);\ntry stack.push(5);\ntry stack.push(6);\n\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\"Stack capacity: {d}\\n\", .{stack.capacity});\n\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\n    \"Stack state: {any}\\n\",\n    .{stack.items[0..stack.length]}\n);\n\nStack len: 6\nStack capacity: 10\nStack len: 5\nStack len: 4\nStack state: { 1, 2, 3, 4, 0, 0, 0, 0, 0, 0 }\nEvery generic data structure in the Zig Standard Library (ArrayList, HashMap, SinlyLinkedList, etc.) is implemented through this logic. They use a generic function to create the struct definition that can work with the data type that you provided as input.",
+    "text": "12.5 Making it generic\nNow that we have implemented the basic skeleton of our stack data structure, we can now focus on discussing how we can make it generic. How can we make this basic skeleton to work not only with u32 values, but also with any other data type we want? For example, we might need to create a stack object to store User values in it. How can we make this possible? The answer lies in the use of generics and comptime.\nAs I described in Section 12.2.2, the basic idea is to write a generic function that returns a struct definition as output. In theory, we do not need much to transform our Stack struct into a generic data structure. All that we need to do is to transform the underlying array of the stack into a generic array.\nIn other words, this underlying array needs to be a “chameleon”. It needs to adapt, and transform it into an array of any data type that we want. For example, if we need to create a stack that will store u8 values, then this underlying array needs to be a u8 array (i.e., []u8). But if we need to store User values instead, then, this array needs to be a User array (i.e., []User). Etc.\nWe do that by using a generic function. Because a generic function can receive a data type as input, and we can pass this data type to the struct definition of our Stack object. Therefore, we can use the generic function to create a Stack object that can store the data type we want. If we want to create a stack structure that stores User values, we pass the User data type to this generic function, and it will create for us the struct definition that describes a Stack object that can store User values in it.\nLook at the code example below. I have omitted some parts of the Stack struct definition for brevity. However, if a specific part of our Stack struct is not exposed here in this example, then it’s because this part did not change from the previous example. It remains the same.\n\nfn Stack(comptime T: type) type {\n    return struct {\n        items: []T,\n        capacity: usize,\n        length: usize,\n        allocator: Allocator,\n        const Self = @This();\n\n        pub fn init(allocator: Allocator,\n                    capacity: usize) !Stack(T) {\n            var buf = try allocator.alloc(T, capacity);\n            return .{\n                .items = buf[0..],\n                .capacity = capacity,\n                .length = 0,\n                .allocator = allocator,\n            };\n        }\n\n        pub fn push(self: *Self, val: T) !void {\n        // Truncate the rest of the struct\n    };\n}\n\nNotice that we have created a function in this example named Stack(). This function takes a type as input, and passes this type to the struct definition of our Stack object. The data member items is now, an array of type T, which is the data type that we have provided as input to the function. The function argument val in the push() function is now a value of type T too.\nWe can just provide a data type to this function, and it will create a definition of a Stack object that can store values of the data type that we have provided. In the example below, we are creating the definition of a Stack object that can store u8 values in it. This definition is stored at the Stacku8 object. This Stacku8 object becomes our new struct, that we are going to use to create our Stack object.\n\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst Stacku8 = Stack(u8);\nvar stack = try Stacku8.init(allocator, 10);\ndefer stack.deinit();\ntry stack.push(1);\ntry stack.push(2);\ntry stack.push(3);\ntry stack.push(4);\ntry stack.push(5);\ntry stack.push(6);\n\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\"Stack capacity: {d}\\n\", .{stack.capacity});\n\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\n    \"Stack state: {any}\\n\",\n    .{stack.items[0..stack.length]}\n);\n\nStack len: 6\nStack capacity: 10\nStack len: 5\nStack len: 4\nStack state: { 1, 2, 3, 4, 0, 0, 0, 0, 0, 0 }\nEvery generic data structure in the Zig Standard Library (ArrayList, HashMap, SinlyLinkedList, etc.) is implemented through this logic. They use a generic function to create the struct definition that can work with the data type that you provided as input.",
     "crumbs": [
       "<span class='chapter-number'>12</span>  <span class='chapter-title'>Project 3 - Building a stack data structure</span>"
     ]
@@ -1004,7 +1004,7 @@
     "href": "Chapters/10-stack-project.html#conclusion",
     "title": "12  Project 3 - Building a stack data structure",
     "section": "12.6 Conclusion",
-    "text": "12.6 Conclusion\nThe full source code of the stack structure discussed in this chapter is freely available at the official repository of this book. Just checkout the stack.zig2 for the u32 version of our stack, and the generic_stack.zig3 for the generic version, available inside the ZigExamples folder of the repository.\n\n\n\n\nGeeks for Geeks. 2024. “Generics in c++.” Geeks for Geeks. https://www.geeksforgeeks.org/generics-in-c/.\n\n\nSeguin, Karl. 2024. “Generics.” https://www.openmymind.net/learning_zig/generics/.\n\n\nZig Software Foundation. 2024. “Language Reference.” Zig Software Foundation. https://ziglang.org/documentation/master/.",
+    "text": "12.6 Conclusion\nThe full source code of the stack structure discussed in this chapter is freely available in the official repository of this book. Just checkout the stack.zig2 for the u32 version of our stack, and the generic_stack.zig3 for the generic version, available inside the ZigExamples folder of the repository.\n\n\n\n\nGeeks for Geeks. 2024. “Generics in c++.” Geeks for Geeks. https://www.geeksforgeeks.org/generics-in-c/.\n\n\nSeguin, Karl. 2024. “Generics.” https://www.openmymind.net/learning_zig/generics/.\n\n\nZig Software Foundation. 2024. “Language Reference.” Zig Software Foundation. https://ziglang.org/documentation/master/.",
     "crumbs": [
       "<span class='chapter-number'>12</span>  <span class='chapter-title'>Project 3 - Building a stack data structure</span>"
     ]
@@ -1024,7 +1024,7 @@
     "href": "Chapters/12-file-op.html",
     "title": "13  Filesystem and Input/Output (IO)",
     "section": "",
-    "text": "13.1 Input/Output basics\nIf you have some experience in a high-level language, you have certainly used these input and output functionalities before in this language. In other words, you certainly have been in a situation where you needed to sent some output to the user, or, to receive an input from the user.\nFor example, in Python we can receive some input from the user by using the input() built-in function. But we can also print (or “show”) some output to the user by using the print() built-in function. So yes, if you have programmed before in Python, you certainly have used these functions once before.\nBut do you know how these functions relate back to your operating system (OS)? How exactly they are interacting with the resources of your OS to receive or sent some input/output. In essence, these input/output functions from high-level languages are just abstractions over the standard output and standard input channels of your operating system.\nThis means that we receive an input, or send some output, through the operating system. It is the OS that makes the bridge between the user and your program. Your program does not have a direct access to the user. It is the OS that intermediates every message exchanged between your program and the user.\nThe standard output and standard input channels of your OS are commonly known as the stdout and stdin channels of your OS, respectively. In some contexts, they are also called the standard output device and the standard input device. As the name suggests, the standard output is the channel through which output flows, while the standard input is the channel in which input flows.\nFurthermore, OS’s also normally create a dedicated channel for exchanging error messages, which is known as the standard error channel, or, the stderr channel. This is the channel to which error and warning messages are usually sent to. These are the messages that are normally displayed in red-like or orange-like colors into your terminal.\nNormally, every OS (e.g. Windows, macOS, Linux, etc.) creates a dedicated and separate set of standard output, standard error and standard input channels for every single program (or process) that runs in your computer. This means that every program you write have a dedicated stdin, stderr and stdout that are separate from the stdin, stderr and stdout of other programs and processes that are currently running.\nThis is a behaviour from your OS. This does not come from the programming language that you are using. Because as I sad earlier, input and output in programming languages, especially in high-level ones, are just a simple abstraction over the stdin, stderr and stdout from your current OS. That is, your OS is the intermediary between every input/output operation made in your program, regardless of the programming language that you are using.",
+    "text": "13.1 Input/Output basics\nIf you have some experience in a high-level language, you have certainly used these input and output functionalities before in this language. In other words, you certainly have been in a situation where you needed to sent some output to the user, or, to receive an input from the user.\nFor example, in Python we can receive some input from the user by using the input() built-in function. But we can also print (or “show”) some output to the user by using the print() built-in function. So yes, if you have programmed before in Python, you certainly have used these functions once before.\nBut do you know how these functions relate back to your operating system (OS)? How exactly they are interacting with the resources of your OS to receive or sent some input/output. In essence, these input/output functions from high-level languages are just abstractions over the standard output and standard input channels of your operating system.\nThis means that we receive an input, or send some output, through the operating system. It’s the OS that makes the bridge between the user and your program. Your program does not have a direct access to the user. It’s the OS that intermediates every message exchanged between your program and the user.\nThe standard output and standard input channels of your OS are commonly known as the stdout and stdin channels of your OS, respectively. In some contexts, they are also called the standard output device and the standard input device. As the name suggests, the standard output is the channel through which output flows, while the standard input is the channel in which input flows.\nFurthermore, OS’s also normally create a dedicated channel for exchanging error messages, which is known as the standard error channel, or, the stderr channel. This is the channel to which error and warning messages are usually sent to. These are the messages that are normally displayed in red-like or orange-like colors into your terminal.\nNormally, every OS (e.g. Windows, macOS, Linux, etc.) creates a dedicated and separate set of standard output, standard error and standard input channels for every single program (or process) that runs in your computer. This means that every program you write have a dedicated stdin, stderr and stdout that are separate from the stdin, stderr and stdout of other programs and processes that are currently running.\nThis is a behaviour from your OS. This does not come from the programming language that you are using. Because as I sad earlier, input and output in programming languages, especially in high-level ones, are just a simple abstraction over the stdin, stderr and stdout from your current OS. That is, your OS is the intermediary between every input/output operation made in your program, regardless of the programming language that you are using.",
     "crumbs": [
       "<span class='chapter-number'>13</span>  <span class='chapter-title'>Filesystem and Input/Output (IO)</span>"
     ]
@@ -1034,7 +1034,7 @@
     "href": "Chapters/12-file-op.html#sec-io-basics",
     "title": "13  Filesystem and Input/Output (IO)",
     "section": "",
-    "text": "13.1.1 The writer and reader pattern\nIn Zig, there is a pattern around input/output (IO). I (the author of this book) don’t know if there is an official name for this pattern. But here, in this book, I will call it the “writer and reader pattern”. In essence, every IO operation in Zig is made through either a GenericReader or a GenericWriter object1.\nThese two data types come from the std.io module of the Zig Standard Library. As their names suggests, a GenericReader is an object that offers tools to read data from “something” (or “somewhere”), while a GenericWriter offers tools to write data into this “something”. This “something” might be different things: like a file that exists in your filesystem; or, it might be a network socket in your system2; or, a continuous stream of data, like a standard input device from your system, that might be constantly receiving new data from users, or, as another example, a live chat in a game that is constantly receiving and displaying new messages from the players of the game.\nSo, if you want to read data from something, or somewhere, it means that you need to use a GenericReader object. But if you need instead, to write data into this “something”, then, you need to use a GenericWriter object instead. Both of these objects are normally created from a file descriptor object. More specifically, through the writer() and reader() methods of this file descriptor object. If you are not familiar with this type of object, go to the next section.\nEvery GenericWriter object have methods like print(), which allows you to write/send a formatted string (i.e. this formatted string is like a f string in Python, or, similar to the printf() C function) into the “something” (file, socket, stream, etc.) that you are using. It also have a writeAll() method, which allows you to write a string, or, an array of bytes into the “something”.\nLikewise, every GenericReader object have methods like readAll(), which allows you to read the data from the “something” (file, socket, stream, etc.) until it fills a particular array (i.e. a “buffer”) object. In other words, if you provide an array object of 300 u8 values to readAll(), then, this method attempts to read 300 bytes of data from the “something”, and it stores them into the array object that you have provided.\nWe also have other methods, like the readAtLeast() method, which allows you to specify how many bytes exactly you want to read from the “something”. In more details, if you give the number \\(n\\) as input to this method, then, it will attempt to read at least \\(n\\) bytes of data from the “something”. The “something” might have less than \\(n\\) bytes of data available for you to read, so, it is not guaranteed that you will get precisely \\(n\\) bytes as result.\nAnother useful method is readUntilDelimiterOrEof(). In this method, you specify a “delimiter character”. The idea is that this function will attempt to read as many bytes of data as possible from the “something”, until it encounters the end of the stream, or, it encounters the “delimiter character” that you have specified.\nIf you don’t know exactly how many bytes will come from the “something”, you may find the readAllAlloc() method useful. In essence, you provide an allocator object to this method, so that it can allocate more space if needed. As consequence, this method will try to read all bytes of the “something”, and, if it runs out of space at some point during the “reading process”, it uses the allocator object to allocate more space to continue reading the bytes. As result, this method returns a slice to the array object containing all the bytes read.\nThis is just a quick description of the methods present in these types of objects. But I recommend you to read the official docs, both for GenericWriter3 and GenericReader4. I also think it is a good idea to read the source code of the modules in the Zig Standard Library that defines the methods present in these objects, which are the Reader.zig5 and Writer.zig6.\n\n\n13.1.2 Introducing file descriptors\nA “file descriptor” object is a core component behind every IO operation that is made in any operating system (OS). Such object is an identifier for a particular input/output (IO) resource from your OS (Wikipedia 2024). It describes and identifies this particular resource. An IO resource might be:\n\nan existing file in your filesystem.\nan existing network socket.\nother types of stream channels.\na pipeline (or just “pipe”) in your terminal7.\n\nFrom the bullet points listed above, we know that although the term “file” is present, a “file descriptor” might describe something more than just a file. This concept of a “file descriptor” comes from the Portable Operating System Interface (POSIX) API, which is a set of standards that guide how operating systems across the world should be implemented, to maintain compatibility between them.\nA file descriptor not only identifies the input/output resource that you are using to receive or send some data, but it also describes where this resource is, and also, which IO mode this resource is currently using. For example, this IO resource might be using only the “read” IO mode, which means that this resource is open to “read operations”, while “write operations” are not authorized. These IO modes are essentially the modes that you provide to the argument mode from the fopen() C function, and also, from the open() Python built-in function.\nIn C, a “file descriptor” is a FILE pointer, but, in Zig, a file descriptor is a File object. This data type (File) is described in the std.fs module of the Zig Standard Library. We normally don’t create a File object directly in our Zig code. Instead, we normally get such object as result when we open an IO resource. In other words, we normally ask our OS to open a particular IO resource for us, and, if the OS do open successfully this IO resource, the OS normally handles back to us a file descriptor to this particular IO resource.\nSo you usually get a File object by using functions and methods from the Zig Standard Library that asks the OS to open some IO resource, like the openFile() method that opens a file in the filesystem. The net.Stream object that we have created at Section 7.4.1 is also a type of file descriptor object.\n\n\n13.1.3 The standard output\nYou already saw across this book, how can we access and use specifically the stdout in Zig to send some output to the user. For that, we use the getStdOut() function from the std.io module. This function returns a file descriptor that describes the stdout channel of your current OS. Through this file descriptor object, we can read from or write stuff to the stdout of our program.\nAlthough we can read stuff recorded into the stdout channel, we normally only write to (or “print”) stuff into this channel. The reason is very similar to what we discussed at Section 7.4.3, when we were discussing what “reading from” versus “writing to” the connection object from our small HTTP Server project would mean.\nWhen we write stuff into a channel, we are essentially sending data to the other end of this channel. In contrast, when we read stuff from this channel, we are essentially reading the data that was sent through this channel. Since the stdout is a channel to send output to the user, the key verb here is send. We want to send something to someone, and, as consequence, we want to write something into some channel.\nThat is why, when we use getStdOut(), most of the times, we also use the writer() method from the stdout file descriptor, to get access to a writer object that we can use to write stuff into this stdout channel. More specifically, this writer() method returns a GenericWriter object. One of the main methods of this GenericWriter object is the print() method that we have used before to write (or “print”) a formatted string into the stdout channel.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    try stdout.writeAll(\n        \"This message was written into stdout.\\n\"\n    );\n}\n\nThis message was written into stdout.\n\n\nThis GenericWriter object is like any other generic writer object that you would normally get from a file descriptor object. So, the same methods from a generic writer object that you would use while writing files to the filesystem for example, you could also use them here, from the file descriptor object of stdout, and vice-versa.\n\n\n13.1.4 The standard input\nYou can access the standard input (i.e. stdin) in Zig by using the getStdIn() function from the std.io module. Like its brother (getStdOut()), this function also returns a file descriptor object that describes the stdin channel of your OS.\nBecause we want to receive some input from the user, the key verb here becomes receive, and, as consequence, we usually want to read data from the stdin channel, instead of writing data into it. So, we normally use the reader() method of the file descriptor object returned by getStdIn(), to get access to a GenericReader object that we can use to read data from stdin.\nIn the example below, we are creating a small buffer capable of holding 20 characters. Then, we try to read the data from the stdin with the readUntilDelimiterOrEof() method, and save this data into the buffer object. Also notice that we are reading the data from the stdin until we hit a new line character ('\\n').\nIf you execute this program, you will notice that it stops the execution, ands start to wait indefinitely for some input from the user. In other words, you need to type your name into the terminal, and then, you press Enter to send your name to stdin. After you send your name to stdin, the program reads this input, and continues with the execution, by printing the given name to stdout. In the example below, I typed my name (Pedro) into the terminal, and then, pressed Enter.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst stdin = std.io.getStdIn().reader();\npub fn main() !void {\n    try stdout.writeAll(\"Type your name\\n\");\n    var buffer: [20]u8 = undefined;\n    @memset(buffer[0..], 0);\n    _ = try stdin.readUntilDelimiterOrEof(buffer[0..], '\\n');\n    try stdout.print(\"Your name is: {s}\\n\", .{buffer});\n}\n\nType your name\nYour name is: Pedro\n\n\n\n13.1.5 The standard error\nThe standard error (a.k.a. the stderr) works exactly the same as stdout and stdin. You just call the getStdErr() function from the std.io module, and you get the file descriptor to stderr. Ideally, you should write only error or warning messages to stderr, because this is the purpose of this channel.",
+    "text": "13.1.1 The writer and reader pattern\nIn Zig, there is a pattern around input/output (IO). I (the author of this book) don’t know if there is an official name for this pattern. But here, in this book, I will call it the “writer and reader pattern”. In essence, every IO operation in Zig is made through either a GenericReader or a GenericWriter object1.\nThese two data types come from the std.io module of the Zig Standard Library. As their names suggests, a GenericReader is an object that offers tools to read data from “something” (or “somewhere”), while a GenericWriter offers tools to write data into this “something”. This “something” might be different things: like a file that exists in your filesystem; or, it might be a network socket in your system2; or, a continuous stream of data, like a standard input device from your system, that might be constantly receiving new data from users, or, as another example, a live chat in a game that is constantly receiving and displaying new messages from the players of the game.\nSo, if you want to read data from something, or somewhere, it means that you need to use a GenericReader object. But if you need instead, to write data into this “something”, then, you need to use a GenericWriter object instead. Both of these objects are normally created from a file descriptor object. More specifically, through the writer() and reader() methods of this file descriptor object. If you are not familiar with this type of object, go to the next section.\nEvery GenericWriter object have methods like print(), which allows you to write/send a formatted string (i.e., this formatted string is like a f string in Python, or, similar to the printf() C function) into the “something” (file, socket, stream, etc.) that you are using. It also have a writeAll() method, which allows you to write a string, or, an array of bytes into the “something”.\nLikewise, every GenericReader object have methods like readAll(), which allows you to read the data from the “something” (file, socket, stream, etc.) until it fills a particular array (i.e., a “buffer”) object. In other words, if you provide an array object of 300 u8 values to readAll(), then, this method attempts to read 300 bytes of data from the “something”, and it stores them into the array object that you have provided.\nWe also have other methods, like the readAtLeast() method, which allows you to specify how many bytes exactly you want to read from the “something”. In more details, if you give the number \\(n\\) as input to this method, then, it will attempt to read at least \\(n\\) bytes of data from the “something”. The “something” might have less than \\(n\\) bytes of data available for you to read, so, it’s not guaranteed that you will get precisely \\(n\\) bytes as result.\nAnother useful method is readUntilDelimiterOrEof(). In this method, you specify a “delimiter character”. The idea is that this function will attempt to read as many bytes of data as possible from the “something”, until it encounters the end of the stream, or, it encounters the “delimiter character” that you have specified.\nIf you don’t know exactly how many bytes will come from the “something”, you may find the readAllAlloc() method useful. In essence, you provide an allocator object to this method, so that it can allocate more space if needed. As consequence, this method will try to read all bytes of the “something”, and, if it runs out of space at some point during the “reading process”, it uses the allocator object to allocate more space to continue reading the bytes. As result, this method returns a slice to the array object containing all the bytes read.\nThis is just a quick description of the methods present in these types of objects. But I recommend you to read the official docs, both for GenericWriter3 and GenericReader4. I also think it’s a good idea to read the source code of the modules in the Zig Standard Library that defines the methods present in these objects, which are the Reader.zig5 and Writer.zig6.\n\n\n13.1.2 Introducing file descriptors\nA “file descriptor” object is a core component behind every IO operation that is made in any operating system (OS). Such object is an identifier for a particular input/output (IO) resource from your OS (Wikipedia 2024). It describes and identifies this particular resource. An IO resource might be:\n\nan existing file in your filesystem.\nan existing network socket.\nother types of stream channels.\na pipeline (or just “pipe”) in your terminal7.\n\nFrom the bullet points listed above, we know that although the term “file” is present, a “file descriptor” might describe something more than just a file. This concept of a “file descriptor” comes from the Portable Operating System Interface (POSIX) API, which is a set of standards that guide how operating systems across the world should be implemented, to maintain compatibility between them.\nA file descriptor not only identifies the input/output resource that you are using to receive or send some data, but it also describes where this resource is, and also, which IO mode this resource is currently using. For example, this IO resource might be using only the “read” IO mode, which means that this resource is open to “read operations”, while “write operations” are not authorized. These IO modes are essentially the modes that you provide to the argument mode from the fopen() C function, and also, from the open() Python built-in function.\nIn C, a “file descriptor” is a FILE pointer, but, in Zig, a file descriptor is a File object. This data type (File) is described in the std.fs module of the Zig Standard Library. We normally don’t create a File object directly in our Zig code. Instead, we normally get such object as result when we open an IO resource. In other words, we normally ask our OS to open a particular IO resource for us, and, if the OS do open successfully this IO resource, the OS normally handles back to us a file descriptor to this particular IO resource.\nSo you usually get a File object by using functions and methods from the Zig Standard Library that asks the OS to open some IO resource, like the openFile() method that opens a file in the filesystem. The net.Stream object that we have created in Section 7.4.1 is also a type of file descriptor object.\n\n\n13.1.3 The standard output\nYou already saw across this book, how can we access and use specifically the stdout in Zig to send some output to the user. For that, we use the getStdOut() function from the std.io module. This function returns a file descriptor that describes the stdout channel of your current OS. Through this file descriptor object, we can read from or write stuff to the stdout of our program.\nAlthough we can read stuff recorded into the stdout channel, we normally only write to (or “print”) stuff into this channel. The reason is very similar to what we discussed at Section 7.4.3, when we were discussing what “reading from” versus “writing to” the connection object from our small HTTP Server project would mean.\nWhen we write stuff into a channel, we are essentially sending data to the other end of this channel. In contrast, when we read stuff from this channel, we are essentially reading the data that was sent through this channel. Since the stdout is a channel to send output to the user, the key verb here is send. We want to send something to someone, and, as consequence, we want to write something into some channel.\nThat is why, when we use getStdOut(), most of the times, we also use the writer() method from the stdout file descriptor, to get access to a writer object that we can use to write stuff into this stdout channel. More specifically, this writer() method returns a GenericWriter object. One of the main methods of this GenericWriter object is the print() method that we have used before to write (or “print”) a formatted string into the stdout channel.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    try stdout.writeAll(\n        \"This message was written into stdout.\\n\"\n    );\n}\n\nThis message was written into stdout.\n\n\nThis GenericWriter object is like any other generic writer object that you would normally get from a file descriptor object. So, the same methods from a generic writer object that you would use while writing files to the filesystem for example, you could also use them here, from the file descriptor object of stdout, and vice-versa.\n\n\n13.1.4 The standard input\nYou can access the standard input (i.e., stdin) in Zig by using the getStdIn() function from the std.io module. Like its brother (getStdOut()), this function also returns a file descriptor object that describes the stdin channel of your OS.\nBecause we want to receive some input from the user, the key verb here becomes receive, and, as consequence, we usually want to read data from the stdin channel, instead of writing data into it. So, we normally use the reader() method of the file descriptor object returned by getStdIn(), to get access to a GenericReader object that we can use to read data from stdin.\nIn the example below, we are creating a small buffer capable of holding 20 characters. Then, we try to read the data from the stdin with the readUntilDelimiterOrEof() method, and save this data into the buffer object. Also notice that we are reading the data from the stdin until we hit a new line character ('\\n').\nIf you execute this program, you will notice that it stops the execution, ands start to wait indefinitely for some input from the user. In other words, you need to type your name into the terminal, and then, you press Enter to send your name to stdin. After you send your name to stdin, the program reads this input, and continues with the execution, by printing the given name to stdout. In the example below, I typed my name (Pedro) into the terminal, and then, pressed Enter.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst stdin = std.io.getStdIn().reader();\npub fn main() !void {\n    try stdout.writeAll(\"Type your name\\n\");\n    var buffer: [20]u8 = undefined;\n    @memset(buffer[0..], 0);\n    _ = try stdin.readUntilDelimiterOrEof(buffer[0..], '\\n');\n    try stdout.print(\"Your name is: {s}\\n\", .{buffer});\n}\n\nType your name\nYour name is: Pedro\n\n\n\n13.1.5 The standard error\nThe standard error (a.k.a. the stderr) works exactly the same as stdout and stdin. You just call the getStdErr() function from the std.io module, and you get the file descriptor to stderr. Ideally, you should write only error or warning messages to stderr, because this is the purpose of this channel.",
     "crumbs": [
       "<span class='chapter-number'>13</span>  <span class='chapter-title'>Filesystem and Input/Output (IO)</span>"
     ]
@@ -1044,7 +1044,7 @@
     "href": "Chapters/12-file-op.html#buffered-io",
     "title": "13  Filesystem and Input/Output (IO)",
     "section": "13.2 Buffered IO",
-    "text": "13.2 Buffered IO\nAs we described at Section 13.1, input/output (IO) operations are made directly by the operating system. It is the OS that manages the IO resource that you want to use for your IO operations. The consequence of this fact is that IO operations are heavily based on system calls (i.e. calling the operating system directly).\nJust to be clear, there is nothing particularly wrong with system calls. We use them all the time on any serious codebase written in any low-level programming language. However, system calls are always orders of magnitude slower than many different types of operations.\nSo is perfectly fine to use a system call once in a while. But when these system calls are used often, you can clearly notice most of the time the loss of performance in your application. So, the good rule of thumbs is to use a system call only when it is needed, and also, only in infrequent situations, to reduce the number of system calls performed to a minimum.\n\n13.2.1 Understanding how buffered IO works\nBuffered IO is a strategy to achieve better performance. It is used to reduce the number of system calls made by IO operations, and, as consequence, achieve a much higher performance. At Figure 13.1 and Figure 13.2 you can find two different diagrams which presents the difference between read operations performed in an unbuffered IO environment versus a buffered IO environment.\nTo give a better context to these diagrams, let’s suppose that we have a text file that contains the famous Lorem ipsum text8 in our filesystem. Let’s also suppose that these diagrams at Figure 13.1 and Figure 13.2 are showing the read operations that we are performing to read the Lorem ipsum text from this text file. The first thing you will notice when looking at these diagrams, is that in an unbuffered environment the read operations leads to many system calls. More precisely, in the diagram exposed at Figure 13.1 we get one system call per each byte that we read from the text file. On the other hand, at Figure 13.2 we have only one system call at the very beginning.\nWhen we use a buffered IO system, at the first read operation we perform, instead of sending one single byte directly to our program, the OS first sends a chunk of bytes from the file to a buffer object (i.e. an array). This chunk of bytes are cached/stored inside this buffer object.\nTherefore, from now on, for every new read operation that you perform, instead of making a new system call to ask for the next byte in the file to the OS, this read operation is redirected to the buffer object, that have this next byte already cached and ready to go.\n\n\n\n\n\n\nFigure 13.1: Unbuffered IO\n\n\n\n\n\n\n\n\n\nFigure 13.2: Buffered IO\n\n\n\nThis is the basic logic behind buffered IO systems. The size of the buffer object depends on multiple factors. But it is usually equal to the size of a full page of memory (4096 bytes). If we follow this logic, then, the OS reads the first 4096 bytes of the file and caches it into the buffer object. As long as your program does not consume all of these 4096 bytes from the buffer, you will not create new system calls.\nHowever, as soon as you consume all of these 4096 bytes from the buffer, it means that there is no bytes left in the buffer. In this situation, a new system call is made to ask the OS to send the next 4096 bytes in the file, and once again, these bytes are cached into the buffer object, and the cycle starts once again.\n\n\n13.2.2 Buffered IO across different languages\nIO operations made through a FILE pointer in C are buffered by default, so, at least in C, you don’t need to worry about this subject. But in contrast, IO operations in both Rust and Zig are not buffered depending on which functions from the standard libraries that you are using.\nFor example, in Rust, buffered IO is implemented through the BufReader and BufWriter structs, while in Zig, it is implemented through the BufferedReader and BufferedWriter structs. So any IO operation that you perform through the GenericWriter and GenericReader objects that I presented at Section 13.1.1 are not buffered, which means that these objects might create a lot of system calls depending on the situation.\n\n\n13.2.3 Using buffered IO in Zig\nUsing buffered IO in Zig is actually very easy. All you have to do is to just give the GenericWriter object to the bufferedWriter() function, or, to give the GenericReader object to the bufferedReader() function. These functions come from the std.io module, and they will construct the BufferedWriter or BufferedReader object for you.\nAfter you create this new BufferedWriter or BufferedReader object, you can call the writer() or reader() method of this new object, to get access to a new (and buffered) generic reader or generic writer.\nLet’s describe the process once again. Every time that you have a file descriptor object, you first get the generic writer or generic reader object from it, by calling the writer() or reader() methods of this file descriptor object. Then, you provide this generic writer or generic reader to the bufferedWriter() or bufferedReader() function, which creates a new BufferedWriter or BufferedReader object. Then, you call the writer() or reader() methods of this buffered writer or buffered reader object, which gives you access to a generic writer or a generic reader object that is buffered.\nTake this program as an example. This program is demonstrating the process exposed at Figure 13.2. We are simply opening a text file that contains the Lorem ipsum text, and then, we create a buffered IO reader object at bufreader, and we use this bufreader object to read the contents of this file into a buffer object, then, we end the program by printing this buffer to stdout.\n\nvar file = try std.fs.cwd().openFile(\n    \"ZigExamples/file-io/lorem.txt\", .{}\n);\ndefer file.close();\nvar buffered = std.io.bufferedReader(file.reader());\nvar bufreader = buffered.reader();\n\nvar buffer: [1000]u8 = undefined;\n@memset(buffer[0..], 0);\n\n_ = try bufreader.readUntilDelimiterOrEof(\n    buffer[0..], '\\n'\n);\ntry stdout.print(\"{s}\\n\", .{buffer});\n\nLorem ipsum dolor sit amet, consectetur\nadipiscing elit. Sed tincidunt erat sed nulla ornare, nec\naliquet ex laoreet. Ut nec rhoncus nunc. Integer magna metus,\nultrices eleifend porttitor ut, finibus ut tortor. Maecenas\nsapien justo, finibus tincidunt dictum ac, semper et lectus.\nVivamus molestie egestas orci ac viverra. Pellentesque nec\narcu facilisis, euismod eros eu, sodales nisl. Ut egestas\nsagittis arcu, in accumsan sapien rhoncus sit amet. Aenean\nneque lectus, imperdiet ac lobortis a, ullamcorper sed massa.\nNullam porttitor porttitor erat nec dapibus. Ut vel dui nec\nnulla vulputate molestie eget non nunc. Ut commodo luctus ipsum,\nin finibus libero feugiat eget. Etiam vel ante at urna tincidunt\nposuere sit amet ut felis. Maecenas finibus suscipit tristique.\nDonec viverra non sapien id suscipit.\nDespite being a buffered IO reader, this bufreader object is similar to any other GenericReader object, and have the exact same methods. So, although these two types of objects perform very different IO operations, they have the same interface, so you, the programmer, can interchangeably use them without the need to change anything in your source code. So a buffered IO reader or a buffered IO writer objects have the same methods than its generic and unbuffered brothers, i.e. the generic reader and generic writer objects that I presented at Section 13.1.1.\n\n\n\n\n\n\nTip\n\n\n\nIn general, you should always use a buffered IO reader or a buffered IO writer object to perform IO operations in Zig. Because they deliver better performance to your IO operations.",
+    "text": "13.2 Buffered IO\nAs we described in Section 13.1, input/output (IO) operations are made directly by the operating system. It’s the OS that manages the IO resource that you want to use for your IO operations. The consequence of this fact is that IO operations are heavily based on system calls (i.e., calling the operating system directly).\nJust to be clear, there is nothing particularly wrong with system calls. We use them all the time on any serious codebase written in any low-level programming language. However, system calls are always orders of magnitude slower than many different types of operations.\nSo is perfectly fine to use a system call once in a while. But when these system calls are used often, you can clearly notice most of the time the loss of performance in your application. So, the good rule of thumb is to use a system call only when it’s needed, and also, only in infrequent situations, to reduce the number of system calls performed to a minimum.\n\n13.2.1 Understanding how buffered IO works\nBuffered IO is a strategy to achieve better performance. It’s used to reduce the number of system calls made by IO operations, and, as consequence, achieve a much higher performance. In Figure 13.1 and Figure 13.2 you can find two different diagrams which presents the difference between read operations performed in an unbuffered IO environment versus a buffered IO environment.\nTo give a better context to these diagrams, let’s suppose that we have a text file that contains the famous Lorem ipsum text8 in our filesystem. Let’s also suppose that these diagrams in Figure 13.1 and Figure 13.2 are showing the read operations that we are performing to read the Lorem ipsum text from this text file. The first thing you will notice when looking at these diagrams, is that in an unbuffered environment the read operations leads to many system calls. More precisely, in the diagram exposed in Figure 13.1 we get one system call per each byte that we read from the text file. On the other hand, in Figure 13.2 we have only one system call at the very beginning.\nWhen we use a buffered IO system, at the first read operation we perform, instead of sending one single byte directly to our program, the OS first sends a chunk of bytes from the file to a buffer object (i.e., an array). This chunk of bytes are cached/stored inside this buffer object.\nTherefore, from now on, for every new read operation that you perform, instead of making a new system call to ask for the next byte in the file to the OS, this read operation is redirected to the buffer object, that have this next byte already cached and ready to go.\n\n\n\n\n\n\nFigure 13.1: Unbuffered IO\n\n\n\n\n\n\n\n\n\nFigure 13.2: Buffered IO\n\n\n\nThis is the basic logic behind buffered IO systems. The size of the buffer object depends on multiple factors. But it’s usually equal to the size of a full page of memory (4096 bytes). If we follow this logic, then, the OS reads the first 4096 bytes of the file and caches it into the buffer object. As long as your program does not consume all of these 4096 bytes from the buffer, you will not create new system calls.\nHowever, as soon as you consume all of these 4096 bytes from the buffer, it means that there is no bytes left in the buffer. In this situation, a new system call is made to ask the OS to send the next 4096 bytes in the file, and once again, these bytes are cached into the buffer object, and the cycle starts once again.\n\n\n13.2.2 Buffered IO across different languages\nIO operations made through a FILE pointer in C are buffered by default, so, at least in C, you don’t need to worry about this subject. But in contrast, IO operations in both Rust and Zig are not buffered depending on which functions from the standard libraries that you are using.\nFor example, in Rust, buffered IO is implemented through the BufReader and BufWriter structs, while in Zig, it’s implemented through the BufferedReader and BufferedWriter structs. So any IO operation that you perform through the GenericWriter and GenericReader objects that I presented in Section 13.1.1 are not buffered, which means that these objects might create a lot of system calls depending on the situation.\n\n\n13.2.3 Using buffered IO in Zig\nUsing buffered IO in Zig is actually very easy. All you have to do is to just give the GenericWriter object to the bufferedWriter() function, or, to give the GenericReader object to the bufferedReader() function. These functions come from the std.io module, and they will construct the BufferedWriter or BufferedReader object for you.\nAfter you create this new BufferedWriter or BufferedReader object, you can call the writer() or reader() method of this new object, to get access to a new (and buffered) generic reader or generic writer.\nLet’s describe the process once again. Every time that you have a file descriptor object, you first get the generic writer or generic reader object from it, by calling the writer() or reader() methods of this file descriptor object. Then, you provide this generic writer or generic reader to the bufferedWriter() or bufferedReader() function, which creates a new BufferedWriter or BufferedReader object. Then, you call the writer() or reader() methods of this buffered writer or buffered reader object, which gives you access to a generic writer or a generic reader object that is buffered.\nTake this program as an example. This program is demonstrating the process exposed in Figure 13.2. We are simply opening a text file that contains the Lorem ipsum text, and then, we create a buffered IO reader object at bufreader, and we use this bufreader object to read the contents of this file into a buffer object, then, we end the program by printing this buffer to stdout.\n\nvar file = try std.fs.cwd().openFile(\n    \"ZigExamples/file-io/lorem.txt\", .{}\n);\ndefer file.close();\nvar buffered = std.io.bufferedReader(file.reader());\nvar bufreader = buffered.reader();\n\nvar buffer: [1000]u8 = undefined;\n@memset(buffer[0..], 0);\n\n_ = try bufreader.readUntilDelimiterOrEof(\n    buffer[0..], '\\n'\n);\ntry stdout.print(\"{s}\\n\", .{buffer});\n\nLorem ipsum dolor sit amet, consectetur\nadipiscing elit. Sed tincidunt erat sed nulla ornare, nec\naliquet ex laoreet. Ut nec rhoncus nunc. Integer magna metus,\nultrices eleifend porttitor ut, finibus ut tortor. Maecenas\nsapien justo, finibus tincidunt dictum ac, semper et lectus.\nVivamus molestie egestas orci ac viverra. Pellentesque nec\narcu facilisis, euismod eros eu, sodales nisl. Ut egestas\nsagittis arcu, in accumsan sapien rhoncus sit amet. Aenean\nneque lectus, imperdiet ac lobortis a, ullamcorper sed massa.\nNullam porttitor porttitor erat nec dapibus. Ut vel dui nec\nnulla vulputate molestie eget non nunc. Ut commodo luctus ipsum,\nin finibus libero feugiat eget. Etiam vel ante at urna tincidunt\nposuere sit amet ut felis. Maecenas finibus suscipit tristique.\nDonec viverra non sapien id suscipit.\nDespite being a buffered IO reader, this bufreader object is similar to any other GenericReader object, and have the exact same methods. So, although these two types of objects perform very different IO operations, they have the same interface, so you, the programmer, can interchangeably use them without the need to change anything in your source code. So a buffered IO reader or a buffered IO writer objects have the same methods than its generic and unbuffered brothers, i.e., the generic reader and generic writer objects that I presented in Section 13.1.1.\n\n\n\n\n\n\nTip\n\n\n\nIn general, you should always use a buffered IO reader or a buffered IO writer object to perform IO operations in Zig. Because they deliver better performance to your IO operations.",
     "crumbs": [
       "<span class='chapter-number'>13</span>  <span class='chapter-title'>Filesystem and Input/Output (IO)</span>"
     ]
@@ -1054,7 +1054,7 @@
     "href": "Chapters/12-file-op.html#filesystem-basics",
     "title": "13  Filesystem and Input/Output (IO)",
     "section": "13.3 Filesystem basics",
-    "text": "13.3 Filesystem basics\nNow that we have discussed the basics around Input/Output operations in Zig, we need to talk about the basics around filesystems, which is another core part of any operating system. Also, filesystems are related to input/output, because the files that we store and create in our computer are considered an IO resource, as we described at Section 13.1.2.\n\n13.3.1 The concept of current working directory (CWD)\nThe working directory is the folder on your computer where you are currently rooted at. In other words, it is the folder that your program is currently looking at. Therefore, whenever you are executing a program, this program is always working with a specific folder on your computer. It is always in this folder that the program will initially look for the files you require, and it is also in this folder that the program will initially save all the files you ask it to save.\nThe working directory is determined by the folder from which you invoke your program in the terminal. In other words, if you are in the terminal of your OS, and you execute a binary file (i.e. a program) from this terminal, the folder to which your terminal is pointing at is the current working directory of your program that is being executed.\nAt Figure 13.3 we have an example of me executing a program from the terminal. We are executing the program outputted by the zig compiler by compiling the Zig module named hello.zig. The CWD in this case is the zig-book folder. In other words, while the hello.zig program is executing, it will be looking at the zig-book folder, and any file operation that we perform inside this program, will be using this zig-book folder as the “starting point”, or, as the “central focus”.\n\n\n\n\n\n\nFigure 13.3: Executing a program from the terminal\n\n\n\nJust because we are rooted inside a particular folder (in the case of Figure 13.3, the zig-book folder) of our computer, it doesn’t mean that we cannot access or write resources in other locations of our computer. The current working directory (CWD) mechanism just defines where your program will look first for the files you ask for. This does not prevent you from accessing files that are located elsewhere on your computer. However, to access any file that is in a folder other than your current working directory, you must provide a path to that file or folder.\n\n\n13.3.2 The concept of paths\nA path is essentially a location. It points to a location in your filesystem. We use paths to describe the location of files and folders in our computer. One important aspect about paths is that they are always written inside strings, i.e. they are always provided as text values.\nThere are two types of paths that you can provide to any program in any OS: a relative path, or an absolute path. Absolute paths are paths that start at the root of your filesystem, and go all the way to the file name or the specific folder that you are referring to. This type of path is called absolute, because it points to an unique and absolute location on your computer. That is, there is no other existing location on your computer that corresponds to this path. It is an unique identifier.\nIn Windows, an absolute path is a path that starts with a hard disk identifier (e.g. C:/Users/pedro). On the other hand, absolute paths in Linux and macOS, are paths that start with a forward slash character (e.g. /usr/local/bin). Notice that a path is composed by “segments”. Each segment is connected to each other by a slash character (\\ or /). On Windows, the backward slash (\\) is normally used to connect the path segments. While on Linux and macOS, the forward slash (/) is the character used to connect path segments.\nA relative path is a path that start at the CWD. In other words, a relative path is “relative to the CWD”. The path used to access the hello.zig file at Figure 13.3 is an example of a relative path. This path is reproduced below. This path begins at the CWD, which in the context of Figure 13.3, is the zig-book folder, then, it goes to the ZigExamples folder, then, into zig-basics, then, to the hello.zig file.\nZigExamples/zig-basics/hello_world.zig\n\n\n13.3.3 Path wildcards\nWhen providing paths, especially relative paths, you have the option of using a wildcard. There are two commonly used wildcards in paths, which are “one period” (.) and “two periods” (..). In other words, these two specific characters have special meanings when used in paths, and can be used on any operating system (Mac, Windows, Linux, etc.). That is, they are “cross platform”.\nThe “one period” represents an alias for the current directory. This means that the relative paths \"./Course/Data/covid.csv\" and \"Course/Data/covid.csv\" are equivalent. On the other hand, the “two periods” refers to the previous directory. For example, the path \"Course/..\" is equivalent to the path \".\", that is, the current working directory.\nTherefore, the path \"Course/..\" refers to the folder before the Course folder. As another example, the path \"src/writexml/../xml.cpp\" refers to the file xml.cpp that is inside the folder before the writexml folder, which in this example is the src folder. Therefore, this path is equivalent to \"src/xml.cpp\".",
+    "text": "13.3 Filesystem basics\nNow that we have discussed the basics around Input/Output operations in Zig, we need to talk about the basics around filesystems, which is another core part of any operating system. Also, filesystems are related to input/output, because the files that we store and create in our computer are considered an IO resource, as we described in Section 13.1.2.\n\n13.3.1 The concept of current working directory (CWD)\nThe working directory is the folder on your computer where you are currently rooted at. In other words, it’s the folder that your program is currently looking at. Therefore, whenever you are executing a program, this program is always working with a specific folder on your computer. It’s always in this folder that the program will initially look for the files you require, and it’s also in this folder that the program will initially save all the files you ask it to save.\nThe working directory is determined by the folder from which you invoke your program in the terminal. In other words, if you are in the terminal of your OS, and you execute a binary file (i.e., a program) from this terminal, the folder to which your terminal is pointing at is the current working directory of your program that is being executed.\nIn Figure 13.3 we have an example of me executing a program from the terminal. We are executing the program outputted by the zig compiler by compiling the Zig module named hello.zig. The CWD in this case is the zig-book folder. In other words, while the hello.zig program is executing, it will be looking at the zig-book folder, and any file operation that we perform inside this program, will be using this zig-book folder as the “starting point”, or, as the “central focus”.\n\n\n\n\n\n\nFigure 13.3: Executing a program from the terminal\n\n\n\nJust because we are rooted inside a particular folder (in the case of Figure 13.3, the zig-book folder) of our computer, it doesn’t mean that we cannot access or write resources in other locations of our computer. The current working directory (CWD) mechanism just defines where your program will look first for the files you ask for. This does not prevent you from accessing files that are located elsewhere on your computer. However, to access any file that is in a folder other than your current working directory, you must provide a path to that file or folder.\n\n\n13.3.2 The concept of paths\nA path is essentially a location. It points to a location in your filesystem. We use paths to describe the location of files and folders in our computer. One important aspect about paths is that they are always written inside strings, i.e., they are always provided as text values.\nThere are two types of paths that you can provide to any program in any OS: a relative path, or an absolute path. Absolute paths are paths that start at the root of your filesystem, and go all the way to the file name or the specific folder that you are referring to. This type of path is called absolute, because it points to an unique and absolute location on your computer. That is, there is no other existing location on your computer that corresponds to this path. It’s an unique identifier.\nIn Windows, an absolute path is a path that starts with a hard disk identifier (e.g. C:/Users/pedro). On the other hand, absolute paths in Linux and macOS, are paths that start with a forward slash character (e.g. /usr/local/bin). Notice that a path is composed by “segments”. Each segment is connected to each other by a slash character (\\ or /). On Windows, the backward slash (\\) is normally used to connect the path segments. While on Linux and macOS, the forward slash (/) is the character used to connect path segments.\nA relative path is a path that start at the CWD. In other words, a relative path is “relative to the CWD”. The path used to access the hello.zig file in Figure 13.3 is an example of a relative path. This path is reproduced below. This path begins at the CWD, which in the context of Figure 13.3, is the zig-book folder, then, it goes to the ZigExamples folder, then, into zig-basics, then, to the hello.zig file.\nZigExamples/zig-basics/hello_world.zig\n\n\n13.3.3 Path wildcards\nWhen providing paths, especially relative paths, you have the option of using a wildcard. There are two commonly used wildcards in paths, which are “one period” (.) and “two periods” (..). In other words, these two specific characters have special meanings when used in paths, and can be used on any operating system (Mac, Windows, Linux, etc.). That is, they are “cross platform”.\nThe “one period” represents an alias for the current directory. This means that the relative paths \"./Course/Data/covid.csv\" and \"Course/Data/covid.csv\" are equivalent. On the other hand, the “two periods” refers to the previous directory. For example, the path \"Course/..\" is equivalent to the path \".\", that is, the current working directory.\nTherefore, the path \"Course/..\" refers to the folder before the Course folder. As another example, the path \"src/writexml/../xml.cpp\" refers to the file xml.cpp that is inside the folder before the writexml folder, which in this example is the src folder. Therefore, this path is equivalent to \"src/xml.cpp\".",
     "crumbs": [
       "<span class='chapter-number'>13</span>  <span class='chapter-title'>Filesystem and Input/Output (IO)</span>"
     ]
@@ -1074,7 +1074,7 @@
     "href": "Chapters/12-file-op.html#file-operations",
     "title": "13  Filesystem and Input/Output (IO)",
     "section": "13.5 File operations",
-    "text": "13.5 File operations\n\n13.5.1 Creating files\nWe create new files by using the createFile() method from the Dir object. Just provide the name of the file that you want to create, and this function will do the necessary steps to create such file. You can also provide a relative path to this function, and it will create the file by following this path, which is relative to the CWD.\nThis function might return an error, so, you should use try, catch, or any of the other methods presented at Chapter 10 to handle the possible error. But if everything goes well, this createFile() method returns a file descriptor object (i.e. a File object) as result, through which you can add content to the file with the IO operations that I presented before.\nTake this code example below. In this example, we are creating a new text file named foo.txt. If the function createFile() succeeds, the object named file will contain a file descriptor object, which we can use to write (or add) new content to the file, like we do in this example, by using a buffered writer object to write a new line of text to the file.\nNow, a quick note, when we create a file descriptor object in C, by using a C function like fopen(), we must always close the file at the end of our program, or, as soon as we complete all operations that we wanted to perform on the file. In Zig, this is no different. So everytime we create a new file, this file remains “open”, waiting for some operation to be performed. As soon as we are done with it, we always have to close this file, to free the resources associated with it. In Zig, we do this by calling the method close() from the file descriptor object.\n\nconst cwd = std.fs.cwd();\nconst file = try cwd.createFile(\"foo.txt\", .{});\n// Don't forget to close the file at the end.\ndefer file.close();\n// Do things with the file ...\nvar fw = file.writer();\n_ = try fw.writeAll(\n    \"Writing this line to the file\\n\"\n);\n\nSo, in this example we not only have created a file into the filesystem, but we also wrote some data into this file, using the file descriptor object returned by createFile(). If the file that you are trying to create already exists in your filesystem, this createFile() call will overwrite the contents of the file, or, in other words, it will in erase all the contents of the existing file.\nIf you don’t want this to happen, meaning, that you don’t want to overwrite the contents of the existing file, but you want to write data to this file anyway (i.e. you want to append data to the file), you should use the openFile() method from the Dir object.\nAnother important aspect about createFile() is that this method creates a file that is not open to read operations by default. It means that you cannot read this file. You are not allowed to. So for example, you might want to write some stuff into this file at the beginning of the execution of your program. Then, at a future point in your program you might need to read what you wrote in this file. If you try to read data from this file, you will likely get a NotOpenForReading error as result.\nBut how can you overcome this barrier? How can you create a file that is open to read operations? All you have to do, is to set the read flag to true in the second argument of createFile(). When you set this flag to true, then the file get’s create with “read permissions”, and, as consequence, a program like this one below becomes valid:\n\nconst cwd = std.fs.cwd();\nconst file = try cwd.createFile(\n    \"foo.txt\",\n    .{ .read = true }\n);\ndefer file.close();\n\nvar fw = file.writer();\n_ = try fw.writeAll(\"We are going to read this line\\n\");\n\nvar buffer: [300]u8 = undefined;\n@memset(buffer[0..], 0);\ntry file.seekTo(0);\nvar fr = file.reader();\n_ = try fr.readAll(buffer[0..]);\ntry stdout.print(\"{s}\\n\", .{buffer});\n\nWe are going to read this line\nIf you are not familiar with position indicators, you might not recognize the method seekTo(). If that is your case, do not worry, we are going to talk more about this method at Section 13.6. But essentially this method is moving the position indicator back to the beginning of the file, so that we can read the contents of the file from the beginning.\n\n\n13.5.2 Opening files and appending data to it\nOpening files is easy. Just use the openFile() method instead of createFile(). In the first argument of openFile() you provide the path to the file that you want to open. Then, on the second argument you provide the flags (or, the options) that dictates how the file is opened.\nYou can see the full list of options for openFile() by visiting the documentation for OpenFlags9. But the main flag that you will most certainly use is the mode flag. This flag specifies the IO mode that the file will be using when it get’s opened. There are three IO modes, or, three values that you can provide to this flag, which are:\n\nread_only, allows only read operations on the file. All write operations are blocked.\nwrite_only, allows only write operations on the file. All read operations are blocked.\nread_write, allows both write and read operations on the file.\n\nThese modes are similar to the modes that you provide to the mode argument of the open() Python built-in function10, or, the mode argument of the fopen() C function11. In the code example below, we are opening the foo.txt text file with a write_only mode, and appending a new line of text to the end of the file. We use seekFromEnd() this time to guarantee that we are going to append the text to the end of the file. Once again, methods such as seekFromEnd() are described in more depth at Section 13.6.\n\nconst cwd = std.fs.cwd();\nconst file = try cwd.openFile(\n    \"foo.txt\", .{ .mode = .write_only }\n);\ndefer file.close();\ntry file.seekFromEnd(0);\nvar fw = file.writer();\n_ = try fw.writeAll(\"Some random text to write\\n\");\n\n\n\n13.5.3 Deleting files\nSometimes, we just need to delete/remove the files that we have. To do that, we use the deleteFile() method. You just provide the path of the file that you want to delete, and this method will try to delete the file located at this path.\n\nconst cwd = std.fs.cwd();\ntry cwd.deleteFile(\"foo.txt\");\n\n\n\n13.5.4 Copying files\nTo copy existing files, we use the copyFile() method. The first argument in this method is the path to the file that you want to copy. The second argument is a Dir object, i.e. a directory handler, more specifically, a Dir object that points to the folder in your computer where you want to copy the file to. The third argument is the new path of the file, or, in other words, the new location of the file. The fourth argument is the options (or flags) to be used in the copy operation.\nThe Dir object that you provide as input to this method will be used to copy the file to the new location. You may create this Dir object before calling the copyFile() method. Maybe you are planning to copy the file to a completely different location in your computer, so it might be worth to create a directory handler to that location. But if you are copying the file to a subfolder of your CWD, then, you can just simply pass the CWD handler to this argument.\n\nconst cwd = std.fs.cwd();\ntry cwd.copyFile(\n    \"foo.txt\",\n    cwd,\n    \"ZigExamples/file-io/foo.txt\",\n    .{}\n);\n\n\n\n13.5.5 Read the docs!\nThere are some other useful methods for file operations available at Dir objects, such as the writeFile() method, but I recommend you to read the docs for the Dir type12 to explore the other available methods, since I already talked too much about them.",
+    "text": "13.5 File operations\n\n13.5.1 Creating files\nWe create new files by using the createFile() method from the Dir object. Just provide the name of the file that you want to create, and this function will do the necessary steps to create such file. You can also provide a relative path to this function, and it will create the file by following this path, which is relative to the CWD.\nThis function might return an error, so, you should use try, catch, or any of the other methods presented in Chapter 10 to handle the possible error. But if everything goes well, this createFile() method returns a file descriptor object (i.e., a File object) as result, through which you can add content to the file with the IO operations that I presented before.\nTake this code example below. In this example, we are creating a new text file named foo.txt. If the function createFile() succeeds, the object named file will contain a file descriptor object, which we can use to write (or add) new content to the file, like we do in this example, by using a buffered writer object to write a new line of text to the file.\nNow, a quick note, when we create a file descriptor object in C, by using a C function like fopen(), we must always close the file at the end of our program, or, as soon as we complete all operations that we wanted to perform on the file. In Zig, this is no different. So everytime we create a new file, this file remains “open”, waiting for some operation to be performed. As soon as we are done with it, we always have to close this file, to free the resources associated with it. In Zig, we do this by calling the method close() from the file descriptor object.\n\nconst cwd = std.fs.cwd();\nconst file = try cwd.createFile(\"foo.txt\", .{});\n// Don't forget to close the file at the end.\ndefer file.close();\n// Do things with the file ...\nvar fw = file.writer();\n_ = try fw.writeAll(\n    \"Writing this line to the file\\n\"\n);\n\nSo, in this example we not only have created a file into the filesystem, but we also wrote some data into this file, using the file descriptor object returned by createFile(). If the file that you are trying to create already exists in your filesystem, this createFile() call will overwrite the contents of the file, or, in other words, it will in erase all the contents of the existing file.\nIf you don’t want this to happen, meaning, that you don’t want to overwrite the contents of the existing file, but you want to write data to this file anyway (i.e., you want to append data to the file), you should use the openFile() method from the Dir object.\nAnother important aspect about createFile() is that this method creates a file that is not open to read operations by default. It means that you cannot read this file. You are not allowed to. So for example, you might want to write some stuff into this file at the beginning of the execution of your program. Then, at a future point in your program you might need to read what you wrote in this file. If you try to read data from this file, you will likely get a NotOpenForReading error as result.\nBut how can you overcome this barrier? How can you create a file that is open to read operations? All you have to do, is to set the read flag to true in the second argument of createFile(). When you set this flag to true, then the file gets create with “read permissions”, and, as consequence, a program like this one below becomes valid:\n\nconst cwd = std.fs.cwd();\nconst file = try cwd.createFile(\n    \"foo.txt\",\n    .{ .read = true }\n);\ndefer file.close();\n\nvar fw = file.writer();\n_ = try fw.writeAll(\"We are going to read this line\\n\");\n\nvar buffer: [300]u8 = undefined;\n@memset(buffer[0..], 0);\ntry file.seekTo(0);\nvar fr = file.reader();\n_ = try fr.readAll(buffer[0..]);\ntry stdout.print(\"{s}\\n\", .{buffer});\n\nWe are going to read this line\nIf you are not familiar with position indicators, you might not recognize the method seekTo(). If that is your case, do not worry, we are going to talk more about this method in Section 13.6. But essentially this method is moving the position indicator back to the beginning of the file, so that we can read the contents of the file from the beginning.\n\n\n13.5.2 Opening files and appending data to it\nOpening files is easy. Just use the openFile() method instead of createFile(). In the first argument of openFile() you provide the path to the file that you want to open. Then, on the second argument you provide the flags (or, the options) that dictates how the file is opened.\nYou can see the full list of options for openFile() by visiting the documentation for OpenFlags9. But the main flag that you will most certainly use is the mode flag. This flag specifies the IO mode that the file will be using when it gets opened. There are three IO modes, or, three values that you can provide to this flag, which are:\n\nread_only, allows only read operations on the file. All write operations are blocked.\nwrite_only, allows only write operations on the file. All read operations are blocked.\nread_write, allows both write and read operations on the file.\n\nThese modes are similar to the modes that you provide to the mode argument of the open() Python built-in function10, or, the mode argument of the fopen() C function11. In the code example below, we are opening the foo.txt text file with a write_only mode, and appending a new line of text to the end of the file. We use seekFromEnd() this time to guarantee that we are going to append the text to the end of the file. Once again, methods such as seekFromEnd() are described in more depth in Section 13.6.\n\nconst cwd = std.fs.cwd();\nconst file = try cwd.openFile(\n    \"foo.txt\", .{ .mode = .write_only }\n);\ndefer file.close();\ntry file.seekFromEnd(0);\nvar fw = file.writer();\n_ = try fw.writeAll(\"Some random text to write\\n\");\n\n\n\n13.5.3 Deleting files\nSometimes, we just need to delete/remove the files that we have. To do that, we use the deleteFile() method. You just provide the path of the file that you want to delete, and this method will try to delete the file located at this path.\n\nconst cwd = std.fs.cwd();\ntry cwd.deleteFile(\"foo.txt\");\n\n\n\n13.5.4 Copying files\nTo copy existing files, we use the copyFile() method. The first argument in this method is the path to the file that you want to copy. The second argument is a Dir object, i.e., a directory handler, more specifically, a Dir object that points to the folder in your computer where you want to copy the file to. The third argument is the new path of the file, or, in other words, the new location of the file. The fourth argument is the options (or flags) to be used in the copy operation.\nThe Dir object that you provide as input to this method will be used to copy the file to the new location. You may create this Dir object before calling the copyFile() method. Maybe you are planning to copy the file to a completely different location in your computer, so it might be worth to create a directory handler to that location. But if you are copying the file to a subfolder of your CWD, then, you can just simply pass the CWD handler to this argument.\n\nconst cwd = std.fs.cwd();\ntry cwd.copyFile(\n    \"foo.txt\",\n    cwd,\n    \"ZigExamples/file-io/foo.txt\",\n    .{}\n);\n\n\n\n13.5.5 Read the docs!\nThere are some other useful methods for file operations available at Dir objects, such as the writeFile() method, but I recommend you to read the docs for the Dir type12 to explore the other available methods, since I already talked too much about them.",
     "crumbs": [
       "<span class='chapter-number'>13</span>  <span class='chapter-title'>Filesystem and Input/Output (IO)</span>"
     ]
@@ -1084,7 +1084,7 @@
     "href": "Chapters/12-file-op.html#sec-indicators",
     "title": "13  Filesystem and Input/Output (IO)",
     "section": "13.6 Position indicators",
-    "text": "13.6 Position indicators\nA position indicator is like a type of cursor, or, an index. This “index” identifies the current location in the file (or, in the data stream) that the file descriptor object that you have is currently looking at. When you create a file descriptor, the position indicator starts at the beginning of the file, or, at the beginning of the stream. When you read from or write into the file (or socket, or data stream, etc.) described by this file descriptor object, you end up moving the position indicator.\nIn other words, any IO operation have a common side effect, which is to move the position indicator. For example, suppose that we have a file of 300 bytes total in size. If you read 100 bytes from the file, then, the position indicator moves 100 bytes forward. If you try to write 50 bytes into this same file, these 50 bytes will be written from the current position indicated by the position indicator. Since the indicator is at a 100 bytes forward from the beginning of the file, these 50 bytes would be written in the middle of the file.\nThis is why we have used the seekTo() method at the last code example presented at Section 13.5.1. We have used this method to move the position indicator back to the beginning of the file, which would make sure that we would write the text that we wanted to write from the beginning of the file, instead of writing it from the middle of the file. Because before the write operation, we had performed a read operation, which means that the position indicator was moved in this read operation.\nThe position indicators of a file descriptor object can be changed (or altered) by using the “seek” methods from this file descriptor, which are: seekTo(), seekFromEnd() and seekBy(). These methods have the same effect, or, the same responsibility that the fseek()13 C function.\nConsidering that offset refers to the index that you provide as input to these “seek” methods, the bullet points below summarises what is the effect of each of these methods. As a quick note, in the case of seekFromEnd() and seekBy(), the offset provided can be either a positive or a negative index.\n\nseekTo() will move the position indicator to the location that is offset bytes from the beginning of the file.\nseekFromEnd() will move the position indicator to the location that is offset bytes from the end of the file.\nseekBy() will move the position indicator to the location that is offset bytes from the current position in the file.",
+    "text": "13.6 Position indicators\nA position indicator is like a type of cursor, or, an index. This “index” identifies the current location in the file (or, in the data stream) that the file descriptor object that you have is currently looking at. When you create a file descriptor, the position indicator starts at the beginning of the file, or, at the beginning of the stream. When you read from or write into the file (or socket, or data stream, etc.) described by this file descriptor object, you end up moving the position indicator.\nIn other words, any IO operation have a common side effect, which is to move the position indicator. For example, suppose that we have a file of 300 bytes total in size. If you read 100 bytes from the file, then, the position indicator moves 100 bytes forward. If you try to write 50 bytes into this same file, these 50 bytes will be written from the current position indicated by the position indicator. Since the indicator is at a 100 bytes forward from the beginning of the file, these 50 bytes would be written in the middle of the file.\nThis is why we have used the seekTo() method at the last code example presented in Section 13.5.1. We have used this method to move the position indicator back to the beginning of the file, which would make sure that we would write the text that we wanted to write from the beginning of the file, instead of writing it from the middle of the file. Because before the write operation, we had performed a read operation, which means that the position indicator was moved in this read operation.\nThe position indicators of a file descriptor object can be changed (or altered) by using the “seek” methods from this file descriptor, which are: seekTo(), seekFromEnd() and seekBy(). These methods have the same effect, or, the same responsibility that the fseek()13 C function.\nConsidering that offset refers to the index that you provide as input to these “seek” methods, the bullet points below summarises what is the effect of each of these methods. As a quick note, in the case of seekFromEnd() and seekBy(), the offset provided can be either a positive or a negative index.\n\nseekTo() will move the position indicator to the location that is offset bytes from the beginning of the file.\nseekFromEnd() will move the position indicator to the location that is offset bytes from the end of the file.\nseekBy() will move the position indicator to the location that is offset bytes from the current position in the file.",
     "crumbs": [
       "<span class='chapter-number'>13</span>  <span class='chapter-title'>Filesystem and Input/Output (IO)</span>"
     ]
@@ -1114,7 +1114,7 @@
     "href": "Chapters/12-file-op.html#footnotes",
     "title": "13  Filesystem and Input/Output (IO)",
     "section": "",
-    "text": "Previously, these objects were known as the Reader and Writer objects.↩︎\nThe socket objects that we have created at Section 7.4.1, are examples of network sockets.↩︎\nhttps://ziglang.org/documentation/master/std/#std.io.GenericWriter.↩︎\nhttps://ziglang.org/documentation/master/std/#std.io.GenericReader.↩︎\nhttps://github.com/ziglang/zig/blob/master/lib/std/io/Reader.zig.↩︎\nhttps://github.com/ziglang/zig/blob/master/lib/std/io/Writer.zig.↩︎\nA pipeline is a mechanism for inter-process communication, or, inter-process IO. You could also interpret a pipeline as a “set of processes that are chained together, through the standard input/output devices of the system”. At Linux for example, a pipeline is created inside a terminal, by connecting two or more terminal commands with the “pipe” character (|).↩︎\nhttps://www.lipsum.com/.↩︎\nhttps://ziglang.org/documentation/master/std/#std.fs.File.OpenFlags↩︎\nhttps://docs.python.org/3/tutorial/inputoutput.html#reading-and-writing-files↩︎\nhttps://www.tutorialspoint.com/c_standard_library/c_function_fopen.htm↩︎\nhttps://ziglang.org/documentation/master/std/#std.fs.Dir↩︎\nhttps://en.cppreference.com/w/c/io/fseek↩︎\nhttps://ziglang.org/documentation/master/std/#std.fs.Dir↩︎",
+    "text": "Previously, these objects were known as the Reader and Writer objects.↩︎\nThe socket objects that we have created in Section 7.4.1, are examples of network sockets.↩︎\nhttps://ziglang.org/documentation/master/std/#std.io.GenericWriter.↩︎\nhttps://ziglang.org/documentation/master/std/#std.io.GenericReader.↩︎\nhttps://github.com/ziglang/zig/blob/master/lib/std/io/Reader.zig.↩︎\nhttps://github.com/ziglang/zig/blob/master/lib/std/io/Writer.zig.↩︎\nA pipeline is a mechanism for inter-process communication, or, inter-process IO. You could also interpret a pipeline as a “set of processes that are chained together, through the standard input/output devices of the system”. At Linux for example, a pipeline is created inside a terminal, by connecting two or more terminal commands with the “pipe” character (|).↩︎\nhttps://www.lipsum.com/.↩︎\nhttps://ziglang.org/documentation/master/std/#std.fs.File.OpenFlags↩︎\nhttps://docs.python.org/3/tutorial/inputoutput.html#reading-and-writing-files↩︎\nhttps://www.tutorialspoint.com/c_standard_library/c_function_fopen.htm↩︎\nhttps://ziglang.org/documentation/master/std/#std.fs.Dir↩︎\nhttps://en.cppreference.com/w/c/io/fseek↩︎\nhttps://ziglang.org/documentation/master/std/#std.fs.Dir↩︎",
     "crumbs": [
       "<span class='chapter-number'>13</span>  <span class='chapter-title'>Filesystem and Input/Output (IO)</span>"
     ]
@@ -1124,7 +1124,7 @@
     "href": "Chapters/14-zig-c-interop.html",
     "title": "14  Zig interoperability with C",
     "section": "",
-    "text": "14.1 How to call C code from Zig\nInteroperability with C is not something new. Most high-level programming languages have FFI (foreign function interfaces), which can be used to call C code. For example, Python have Cython, R have .Call(), Javascript have ccall(), etc. But Zig integrates with C in a deeper level, which affects not only the way that C code get’s called, but also, how this C code is compiled and incorporated into your Zig project.\nIn summary, Zig have great interoperability with C. If you want to call any C code from Zig, you have to perform the following steps:",
+    "text": "14.1 How to call C code from Zig\nInteroperability with C is not something new. Most high-level programming languages have FFI (foreign function interfaces), which can be used to call C code. For example, Python have Cython, R have .Call(), Javascript have ccall(), etc. But Zig integrates with C in a deeper level, which affects not only the way that C code gets called, but also, how this C code is compiled and incorporated into your Zig project.\nIn summary, Zig have great interoperability with C. If you want to call any C code from Zig, you have to perform the following steps:",
     "crumbs": [
       "<span class='chapter-number'>14</span>  <span class='chapter-title'>Zig interoperability with C</span>"
     ]
@@ -1144,7 +1144,7 @@
     "href": "Chapters/14-zig-c-interop.html#sec-import-c-header",
     "title": "14  Zig interoperability with C",
     "section": "14.2 Importing C header files",
-    "text": "14.2 Importing C header files\nAt Section 14.1.1, we have described that, currently, there are two different paths that you can take to import a C header file into your Zig modules, translate-c or @cImport(). This section describes each strategy separately in more details.\n\n14.2.1 Strategy 1: using translate-c\nWhen we choose this strategy, we first need to use the translate-c tool to translate the C header files that we want to use into Zig code. For example, suppose we wanted to use the fopen() C function from the stdio.h C header file. We can translate the stdio.h C header file through the bash command below:\nzig translate-c /usr/include/stdio.h \\\n    -lc -I/usr/include \\\n    -D_NO_CRT_STDIO_INLINE=1 &gt; c.zig \\\nNotice that, in this bash command, we are passing the necessary compiler flags (-D to define macros, -l to link libraries, -I to add an “include path”) to compile and use the stdio.h header file. Also notice that we are saving the results of the translation process inside a Zig module called c.zig.\nTherefore, after running this command, all we have to do is to import this c.zig module, and start calling the C functions that you want to call from it. The example below demonstrates that. Is important to remember what we’ve discussed at Section 14.1.2. In order to compile this example you have to link this code with libc, by passing the flag -lc to the zig compiler.\n\nconst c = @import(\"c.zig\");\npub fn main() !void {\n    const x: f32 = 1772.94122;\n    _ = c.printf(\"%.3f\\n\", x);\n}\n\n1772.941\n\n\n14.2.2 Strategy 2: using @cImport()\nTo import a C header file into our Zig code, we can use the built-in functions @cInclude() and @cImport(). Inside the @cImport() function, we open a block (with a pair of curly braces). Inside this block we can (if we need to) include multiple @cDefine() calls to define C macros when including this specific C header file. But for the most part, you will probably need to use just a single call inside this block, which is a call to @cInclude().\nThis @cInclude() function is equivalent to the #include statement in C. You provide the name of the C header that you want to include as input to this @cInclude() function, then, in conjunction with @cImport(), it will perform the necessary steps to include this C header file into your Zig code.\nYou should bind the result of @cImport() to a constant object, pretty much like you would do with @import(). You just assign the result to a constant object in your Zig code, and, as consequence, all C functions, C structs, C macros, etc. that are defined inside the C header files will be available through this constant object.\nLook at the code example below, where we are importing the Standard I/O C Library (stdio.h), and calling the printf()3 C function. Notice that we have also used in this example the C function powf()4, which comes from the C Math Library (math.h). In order to compile this example, you have to link this Zig code with both the C Standard Library and the C Math Library, by passing the flags -lc and -lm to the zig compiler.\n\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n    @cInclude(\"math.h\");\n});\n\npub fn main() !void {\n    const x: f32 = 15.2;\n    const y = c.powf(x, @as(f32, 2.6));\n    _ = c.printf(\"%.3f\\n\", y);\n}\n\n1182.478",
+    "text": "14.2 Importing C header files\nIn Section 14.1.1, we have described that, currently, there are two different paths that you can take to import a C header file into your Zig modules, translate-c or @cImport(). This section describes each strategy separately in more details.\n\n14.2.1 Strategy 1: using translate-c\nWhen we choose this strategy, we first need to use the translate-c tool to translate the C header files that we want to use into Zig code. For example, suppose we wanted to use the fopen() C function from the stdio.h C header file. We can translate the stdio.h C header file through the bash command below:\nzig translate-c /usr/include/stdio.h \\\n    -lc -I/usr/include \\\n    -D_NO_CRT_STDIO_INLINE=1 &gt; c.zig \\\nNotice that, in this bash command, we are passing the necessary compiler flags (-D to define macros, -l to link libraries, -I to add an “include path”) to compile and use the stdio.h header file. Also notice that we are saving the results of the translation process inside a Zig module called c.zig.\nTherefore, after running this command, all we have to do is to import this c.zig module, and start calling the C functions that you want to call from it. The example below demonstrates that. It’s important to remember what we’ve discussed in Section 14.1.2. In order to compile this example you have to link this code with libc, by passing the flag -lc to the zig compiler.\n\nconst c = @import(\"c.zig\");\npub fn main() !void {\n    const x: f32 = 1772.94122;\n    _ = c.printf(\"%.3f\\n\", x);\n}\n\n1772.941\n\n\n14.2.2 Strategy 2: using @cImport()\nTo import a C header file into our Zig code, we can use the built-in functions @cInclude() and @cImport(). Inside the @cImport() function, we open a block (with a pair of curly braces). Inside this block we can (if we need to) include multiple @cDefine() calls to define C macros when including this specific C header file. But for the most part, you will probably need to use just a single call inside this block, which is a call to @cInclude().\nThis @cInclude() function is equivalent to the #include statement in C. You provide the name of the C header that you want to include as input to this @cInclude() function, then, in conjunction with @cImport(), it will perform the necessary steps to include this C header file into your Zig code.\nYou should bind the result of @cImport() to a constant object, pretty much like you would do with @import(). You just assign the result to a constant object in your Zig code, and, as consequence, all C functions, C structs, C macros, etc. that are defined inside the C header files will be available through this constant object.\nLook at the code example below, where we are importing the Standard I/O C Library (stdio.h), and calling the printf()3 C function. Notice that we have also used in this example the C function powf()4, which comes from the C Math Library (math.h). In order to compile this example, you have to link this Zig code with both the C Standard Library and the C Math Library, by passing the flags -lc and -lm to the zig compiler.\n\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n    @cInclude(\"math.h\");\n});\n\npub fn main() !void {\n    const x: f32 = 15.2;\n    const y = c.powf(x, @as(f32, 2.6));\n    _ = c.printf(\"%.3f\\n\", y);\n}\n\n1182.478",
     "crumbs": [
       "<span class='chapter-number'>14</span>  <span class='chapter-title'>Zig interoperability with C</span>"
     ]
@@ -1154,7 +1154,7 @@
     "href": "Chapters/14-zig-c-interop.html#sec-zig-obj-to-c",
     "title": "14  Zig interoperability with C",
     "section": "14.3 About passing Zig values to C functions",
-    "text": "14.3 About passing Zig values to C functions\nZig objects have some intrinsic differences between their C equivalents. Probably the most noticeable one is the difference between C strings and Zig strings, which I described at Section 1.8. Zig strings are objects that contains both an array of arbitrary bytes and a length value. On the other hand, a C string is usually just a pointer to a null-terminated array of arbitrary bytes.\nBecause of these intrinsic differences, in some specific cases, you cannot pass Zig objects directly as inputs to C functions before you convert them into C compatible values. However, in some other cases, you are allowed to pass Zig objects and Zig literal values directly as inputs to C functions, and everything will work just fine, because the zig compiler will handle everything for you.\nSo we have two different scenarios being described here. Let’s call them “auto-conversion” and “need-conversion”. The “auto-conversion” scenario is when the zig compiler handles everything for you, and automatically convert your Zig objects/values into C compatible values. In contrast, the “need-conversion” scenario is when you, the programmer, have the responsibility of converting that Zig object into a C compatible value, before passing it to C code.\nThere is also a third scenario that is not being described here, which is when you create a C object, or, a C struct, or a C compatible value in your Zig code, and you pass this C object/value as input to a C function in your Zig code. This scenario will be described later at Section 14.4. In this section, we are focused on the scenarios where we are passing Zig objects/values to C code, instead of C objects/values being passed to C code.\n\n14.3.1 The “auto-conversion” scenario\nAn “auto-conversion” scenario is when the zig compiler automatically converts our Zig objects into C compatible values for us. This specific scenario happens mostly in two instances:\n\nwith string literal values;\nwith any of the primitive data types that were introduced at Section 1.5.\n\nWhen we think about the second instance described above, the zig compiler does automatically convert any of the primitive data types into their C equivalents, because the compiler knows how to properly convert a i16 into a signed short, or, a u8 into a unsigned char, etc. Now, when we think about string literal values, they can be automatically converted into C strings as well, especially because the zig compiler does not forces a specific Zig data type into a string literal at first glance, unless you store this string literal into a Zig object, and explicitly annotate the data type of this object.\nThus, with string literal values, the zig compiler have more freedom to infer which is the appropriate data type to be used in each situation. You could say that the string literal value “inherits its data type” depending on the context that it is used. Most of the times, this data type is going to be the type that we commonly associate with Zig strings ([]const u8). But it might be a different type depending on the situation. When the zig compiler detects that you are providing a string literal value as input to some C function, the compiler automatically interprets this string literal as a C string value.\nAs an example, look at the code exposed below. Here we are using the fopen() C function to simply open and close a file. If you do not know how this fopen() function works in C, it takes two C strings as input. But in this code example below, we are passing some string literals written in our Zig code directly as inputs to this fopen() C function.\nIn other words, we are not doing any conversion from a Zig string to a C string. We are just passing the Zig string literals directly as inputs to the C function. And it works just fine! Because the compiler interprets the string \"foo.txt\" as a C string given the current context.\n\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n});\n\npub fn main() !void {\n    const file = c.fopen(\"foo.txt\", \"rb\");\n    if (file == null) {\n        @panic(\"Could not open file!\");\n    }\n    if (c.fclose(file) != 0) {\n        return error.CouldNotCloseFileDescriptor;\n    }\n}\n\nLet’s make some experiments, by writing the same code in different manners, and we see how this affects the program. As a starting point, let’s store the \"foo.txt\" string inside a Zig object, like the path object below, and then, we pass this Zig object as input to the fopen() C function.\nIf we do this, the program still compiles and runs successfully. Notice that I have omitted most of the code in this example below. This is just for brevity reasons, because the remainder of the program is still the same. The only difference between this example and the previous one is just these two lines exposed below.\n\n    const path = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n\nNow, what happens if you give an explicit data type to the path object? Well, if I force the zig compiler to interpret this path object as a Zig string object, by annotating the path object with the data type []const u8, then, I actually get a compile error as demonstrated below. We get this compile error because now I’m forcing the zig compiler to interpret path as a Zig string object.\nAccording to the error message, the fopen() C function was expecting to receive an input value of type [*c]const u8 (C string) instead of a value of type []const u8 (Zig string). In more details, the type [*c]const u8 is actually the Zig type representation of a C string. The [*c] portion of this type identifies a C pointer. So, this Zig type essentially means: a C pointer to an array ([*c]) of constant bytes (const u8).\n\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n\nt.zig:2:7 error: expected type '[*c]const u8', found '[]const u8':\n    const file = c.fopen(path, \"rb\");\n                         ^~~~\nTherefore, when we talk exclusively about string literal values, as long as you don’t give an explicit data type to these string literal values, the zig compiler should be capable of automatically converting them into C strings as needed.\nBut what about using one of the primitive data types that were introduced at Section 1.5? Let’s take code exposed below as an example of that. Here, we are giving some float literal values as input to the C function powf(). Notice that this code example compiles and runs successfully.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst cmath = @cImport({\n    @cInclude(\"math.h\");\n});\n\npub fn main() !void {\n    const y = cmath.powf(15.68, 2.32);\n    try stdout.print(\"{d}\\n\", .{y});\n}\n\n593.2023\nOnce again, because the zig compiler does not associate a specific data type with the literal values 15.68 and 2.32 at first glance, the compiler can automatically convert these values into their C float (or double) equivalents, before it passes to the powf() C function. Now, even if I give an explicit Zig data type to these literal values, by storing them into a Zig object, and explicit annotating the type of these objects, the code still compiles and runs successfully.\n\n    const x: f32 = 15.68;\n    const y = cmath.powf(x, 2.32);\n    // The remainder of the program\n\n593.2023\n\n\n14.3.2 The “need-conversion” scenario\nA “need-conversion” scenario is when we need to manually convert our Zig objects into C compatible values before passing them as input to C functions. You will fall in this scenario, when passing Zig string objects to C functions.\nWe have already seen this specific circumstance in the last fopen() example, which is reproduced below. You can see in this example, that we have given an explicit Zig data type ([]const u8) to our path object, and, as a consequence of that, we have forced the zig compiler to see this path object, as a Zig string object. Therefore, we need now to manually convert this path object into a C string before we pass it to fopen().\n\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n\nt.zig:10:26: error: expected type '[*c]const u8', found '[]const u8'\n    const file = c.fopen(path, \"rb\");\n                         ^~~~\nThere are different ways to convert a Zig string object into a C string. One way to solve this problem is to provide the pointer to the underlying array of bytes, instead of providing the Zig object directly as input. You can access this pointer by using the ptr property of the Zig string object.\nThe code example below demonstrates this strategy. Notice that, by giving the pointer to the underlying array in path through the ptr property, we get no compile errors as result while using the fopen() C function.\n\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path.ptr, \"rb\");\n    // Remainder of the program\n\nThis strategy works because this pointer to the underlying array found in the ptr property, is semantically identical to a C pointer to an array of bytes, i.e. a C object of type *unsigned char. This is why this option also solves the problem of converting the Zig string into a C string.\nAnother option is to explicitly convert the Zig string object into a C pointer by using the built-in function @ptrCast(). With this function we can convert an object of type []const u8 into an object of type [*c]const u8. As I described at the previous section, the [*c] portion of the type means that it is a C pointer. This strategy is not-recommended. But it is useful to demonstrate the use of @ptrCast().\nYou may recall of @as() and @ptrCast() from Section 2.5. Just as a recap, the @as() built-in function is used to explicitly convert (or cast) a Zig value from a type “x” into a value of type “y”. But in our case here, we are converting a pointer object. Everytime a pointer is involved in some “type casting operation” in Zig, the @ptrCast() function is involved.\nIn the example below, we are using this function to cast our path object into a C pointer to an array of bytes. Then, we pass this C pointer as input to the fopen() function. Notice that this code example compiles successfully with no errors.\n\n    const path: []const u8 = \"foo.txt\";\n    const c_path: [*c]const u8 = @ptrCast(path);\n    const file = c.fopen(c_path, \"rb\");\n    // Remainder of the program",
+    "text": "14.3 About passing Zig values to C functions\nZig objects have some intrinsic differences between their C equivalents. Probably the most noticeable one is the difference between C strings and Zig strings, which I described in Section 1.8. Zig strings are objects that contains both an array of arbitrary bytes and a length value. On the other hand, a C string is usually just a pointer to a null-terminated array of arbitrary bytes.\nBecause of these intrinsic differences, in some specific cases, you cannot pass Zig objects directly as inputs to C functions before you convert them into C compatible values. However, in some other cases, you are allowed to pass Zig objects and Zig literal values directly as inputs to C functions, and everything will work just fine, because the zig compiler will handle everything for you.\nSo we have two different scenarios being described here. Let’s call them “auto-conversion” and “need-conversion”. The “auto-conversion” scenario is when the zig compiler handles everything for you, and automatically convert your Zig objects/values into C compatible values. In contrast, the “need-conversion” scenario is when you, the programmer, have the responsibility of converting that Zig object into a C compatible value, before passing it to C code.\nThere is also a third scenario that is not being described here, which is when you create a C object, or, a C struct, or a C compatible value in your Zig code, and you pass this C object/value as input to a C function in your Zig code. This scenario will be described later in Section 14.4. In this section, we are focused on the scenarios where we are passing Zig objects/values to C code, instead of C objects/values being passed to C code.\n\n14.3.1 The “auto-conversion” scenario\nAn “auto-conversion” scenario is when the zig compiler automatically converts our Zig objects into C compatible values for us. This specific scenario happens mostly in two instances:\n\nwith string literal values;\nwith any of the primitive data types that were introduced in Section 1.5.\n\nWhen we think about the second instance described above, the zig compiler does automatically convert any of the primitive data types into their C equivalents, because the compiler knows how to properly convert a i16 into a signed short, or, a u8 into a unsigned char, etc. Now, when we think about string literal values, they can be automatically converted into C strings as well, especially because the zig compiler does not forces a specific Zig data type into a string literal at first glance, unless you store this string literal into a Zig object, and explicitly annotate the data type of this object.\nThus, with string literal values, the zig compiler has more freedom to infer which is the appropriate data type to be used in each situation. You could say that the string literal value “inherits its data type” depending on the context that it’s used in. Most of the times, this data type is going to be the type that we commonly associate with Zig strings ([]const u8). But it might be a different type depending on the situation. When the zig compiler detects that you are providing a string literal value as input to some C function, the compiler automatically interprets this string literal as a C string value.\nAs an example, look at the code exposed below. Here we are using the fopen() C function to simply open and close a file. If you do not know how this fopen() function works in C, it takes two C strings as input. But in this code example below, we are passing some string literals written in our Zig code directly as inputs to this fopen() C function.\nIn other words, we are not doing any conversion from a Zig string to a C string. We are just passing the Zig string literals directly as inputs to the C function. And it works just fine! Because the compiler interprets the string \"foo.txt\" as a C string given the current context.\n\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n});\n\npub fn main() !void {\n    const file = c.fopen(\"foo.txt\", \"rb\");\n    if (file == null) {\n        @panic(\"Could not open file!\");\n    }\n    if (c.fclose(file) != 0) {\n        return error.CouldNotCloseFileDescriptor;\n    }\n}\n\nLet’s make some experiments, by writing the same code in different manners, and we see how this affects the program. As a starting point, let’s store the \"foo.txt\" string inside a Zig object, like the path object below, and then, we pass this Zig object as input to the fopen() C function.\nIf we do this, the program still compiles and runs successfully. Notice that I have omitted most of the code in this example below. This is just for brevity reasons, because the remainder of the program is still the same. The only difference between this example and the previous one is just these two lines exposed below.\n\n    const path = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n\nNow, what happens if you give an explicit data type to the path object? Well, if I force the zig compiler to interpret this path object as a Zig string object, by annotating the path object with the data type []const u8, then, I actually get a compile error as demonstrated below. We get this compile error because now I’m forcing the zig compiler to interpret path as a Zig string object.\nAccording to the error message, the fopen() C function was expecting to receive an input value of type [*c]const u8 (C string) instead of a value of type []const u8 (Zig string). In more details, the type [*c]const u8 is actually the Zig type representation of a C string. The [*c] portion of this type identifies a C pointer. So, this Zig type essentially means: a C pointer to an array ([*c]) of constant bytes (const u8).\n\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n\nt.zig:2:7 error: expected type '[*c]const u8', found '[]const u8':\n    const file = c.fopen(path, \"rb\");\n                         ^~~~\nTherefore, when we talk exclusively about string literal values, as long as you don’t give an explicit data type to these string literal values, the zig compiler should be capable of automatically converting them into C strings as needed.\nBut what about using one of the primitive data types that were introduced in Section 1.5? Let’s take code exposed below as an example of that. Here, we are giving some float literal values as input to the C function powf(). Notice that this code example compiles and runs successfully.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst cmath = @cImport({\n    @cInclude(\"math.h\");\n});\n\npub fn main() !void {\n    const y = cmath.powf(15.68, 2.32);\n    try stdout.print(\"{d}\\n\", .{y});\n}\n\n593.2023\nOnce again, because the zig compiler does not associate a specific data type with the literal values 15.68 and 2.32 at first glance, the compiler can automatically convert these values into their C float (or double) equivalents, before it passes to the powf() C function. Now, even if I give an explicit Zig data type to these literal values, by storing them into a Zig object, and explicit annotating the type of these objects, the code still compiles and runs successfully.\n\n    const x: f32 = 15.68;\n    const y = cmath.powf(x, 2.32);\n    // The remainder of the program\n\n593.2023\n\n\n14.3.2 The “need-conversion” scenario\nA “need-conversion” scenario is when we need to manually convert our Zig objects into C compatible values before passing them as input to C functions. You will fall in this scenario, when passing Zig string objects to C functions.\nWe have already seen this specific circumstance in the last fopen() example, which is reproduced below. You can see in this example, that we have given an explicit Zig data type ([]const u8) to our path object, and, as a consequence of that, we have forced the zig compiler to see this path object, as a Zig string object. Therefore, we need now to manually convert this path object into a C string before we pass it to fopen().\n\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n\nt.zig:10:26: error: expected type '[*c]const u8', found '[]const u8'\n    const file = c.fopen(path, \"rb\");\n                         ^~~~\nThere are different ways to convert a Zig string object into a C string. One way to solve this problem is to provide the pointer to the underlying array of bytes, instead of providing the Zig object directly as input. You can access this pointer by using the ptr property of the Zig string object.\nThe code example below demonstrates this strategy. Notice that, by giving the pointer to the underlying array in path through the ptr property, we get no compile errors as result while using the fopen() C function.\n\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path.ptr, \"rb\");\n    // Remainder of the program\n\nThis strategy works because this pointer to the underlying array found in the ptr property, is semantically identical to a C pointer to an array of bytes, i.e., a C object of type *unsigned char. This is why this option also solves the problem of converting the Zig string into a C string.\nAnother option is to explicitly convert the Zig string object into a C pointer by using the built-in function @ptrCast(). With this function we can convert an object of type []const u8 into an object of type [*c]const u8. As I described at the previous section, the [*c] portion of the type means that it’s a C pointer. This strategy is not-recommended. But it’s useful to demonstrate the use of @ptrCast().\nYou may recall of @as() and @ptrCast() from Section 2.5. Just as a recap, the @as() built-in function is used to explicitly convert (or cast) a Zig value from a type “x” into a value of type “y”. But in our case here, we are converting a pointer object. Everytime a pointer is involved in some “type casting operation” in Zig, the @ptrCast() function is involved.\nIn the example below, we are using this function to cast our path object into a C pointer to an array of bytes. Then, we pass this C pointer as input to the fopen() function. Notice that this code example compiles successfully with no errors.\n\n    const path: []const u8 = \"foo.txt\";\n    const c_path: [*c]const u8 = @ptrCast(path);\n    const file = c.fopen(c_path, \"rb\");\n    // Remainder of the program",
     "crumbs": [
       "<span class='chapter-number'>14</span>  <span class='chapter-title'>Zig interoperability with C</span>"
     ]
@@ -1164,7 +1164,7 @@
     "href": "Chapters/14-zig-c-interop.html#sec-c-inputs",
     "title": "14  Zig interoperability with C",
     "section": "14.4 Creating C objects in Zig",
-    "text": "14.4 Creating C objects in Zig\nCreating C objects, or, in other words, creating instances of C structs in your Zig code is actually something quite easy to do. You first need to import the C header file (like I described at Section 14.2) that defines the C struct that you are trying to instantiate in your Zig code. After that, you can just create a new object in your Zig code, and annotate it with the data type of the C struct.\nFor example, suppose we have a C header file called user.h, and that this header file is declaring a new struct named User. This C header file is exposed below:\n#include &lt;stdint.h&gt;\n\ntypedef struct {\n    uint64_t id;\n    char* name;\n} User;\nThis User C struct have two distinct fields, or two struct members, named id and name. The field id is an unsigned 64-bit integer value, while the field name is just a standard C string. Now, suppose that I want to create an instance of this User struct in my Zig code. I can do that by importing this user.h header file into my Zig code, and creating a new object with type User. These steps are reproduced in the code example below.\nNotice that I have used the keyword undefined in this example. This allows me to create the new_user object without the need to provide an initial value to the object. As consequence, the underlying memory associated with this new_user object is uninitialized, i.e. the memory is currently populated with “garbage” values. Thus, this expression have the exact same effect of the expression User new_user; in C, which means “declare a new object named new_user of type User”.\nIs our responsibility to properly initialize this memory associated with this new_user object, by assigning valid values to the members (or the fields) of the C struct. In the example below, I’m assigning the integer 1 to the member id. I am also saving the string \"pedropark99\" into the member name. Notice in this example that I manually add the null character (zero byte) to the end of the allocated array for this string. This null character marks the end of the array in C.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst c = @cImport({\n    @cInclude(\"user.h\");\n});\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n\n    var new_user: c.User = undefined;\n    new_user.id = 1;\n    var user_name = try allocator.alloc(u8, 12);\n    defer allocator.free(user_name);\n    @memcpy(user_name[0..(user_name.len - 1)], \"pedropark99\");\n    user_name[user_name.len - 1] = 0;\n    new_user.name = user_name.ptr;\n}\n\nSo, in this example above, we are manually initializing each field of the C struct. We could say that, in this instance, we are “manually instantiating the C struct object”. However, when we use C libraries in our Zig code, we rarely need to manually instantiate the C structs like that. Only because C libraries usually provide a “constructor function” in their public APIs. As consequence, we normally rely on these constructor functions to properly initialize the C structs, and the struct fields for us.\nFor example, consider the Harfbuzz C library. This a text shaping C library, and it works around a “buffer object”, or, more specifically, an instance of the C struct hb_buffer_t. Therefore, we need to create an instance of this C struct if we want to use this C library. Luckily, this library offers the function hb_buffer_create(), which we can use to create such object. So the Zig code necessary to create such object would probably look something like this:\n\nconst c = @cImport({\n    @cInclude(\"hb.h\");\n});\nvar buf: c.hb_buffer_t = c.hb_buffer_create();\n// Do stuff with the \"buffer object\"\n\nTherefore, we do not need to manually create an instance of the C struct hb_buffer_t here, and manually assign valid values to each field in this C struct. Because the constructor function hb_buffer_create() is doing this heavy job for us.\nSince this buf object, and also, the new_user object from previous examples, are instances of C structs, these objects are by themselves C compatible values. They are C objects defined in our Zig code. As consequence, you can freely pass these objects as input to any C function that expects to receive this type of C struct as input. You do not need to use any special syntax, or, to convert them in any special manner to use them in C code. This is how we create and use C objects in our Zig code.",
+    "text": "14.4 Creating C objects in Zig\nCreating C objects, or, in other words, creating instances of C structs in your Zig code is actually something quite easy to do. You first need to import the C header file (like I described in Section 14.2) that defines the C struct that you are trying to instantiate in your Zig code. After that, you can just create a new object in your Zig code, and annotate it with the data type of the C struct.\nFor example, suppose we have a C header file called user.h, and that this header file is declaring a new struct named User. This C header file is exposed below:\n#include &lt;stdint.h&gt;\n\ntypedef struct {\n    uint64_t id;\n    char* name;\n} User;\nThis User C struct have two distinct fields, or two struct members, named id and name. The field id is an unsigned 64-bit integer value, while the field name is just a standard C string. Now, suppose that I want to create an instance of this User struct in my Zig code. I can do that by importing this user.h header file into my Zig code, and creating a new object with type User. These steps are reproduced in the code example below.\nNotice that I have used the keyword undefined in this example. This allows me to create the new_user object without the need to provide an initial value to the object. As consequence, the underlying memory associated with this new_user object is uninitialized, i.e., the memory is currently populated with “garbage” values. Thus, this expression have the exact same effect of the expression User new_user; in C, which means “declare a new object named new_user of type User”.\nIt’s our responsibility to properly initialize this memory associated with this new_user object, by assigning valid values to the members (or the fields) of the C struct. In the example below, I’m assigning the integer 1 to the member id. I am also saving the string \"pedropark99\" into the member name. Notice in this example that I manually add the null character (zero byte) to the end of the allocated array for this string. This null character marks the end of the array in C.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst c = @cImport({\n    @cInclude(\"user.h\");\n});\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n\n    var new_user: c.User = undefined;\n    new_user.id = 1;\n    var user_name = try allocator.alloc(u8, 12);\n    defer allocator.free(user_name);\n    @memcpy(user_name[0..(user_name.len - 1)], \"pedropark99\");\n    user_name[user_name.len - 1] = 0;\n    new_user.name = user_name.ptr;\n}\n\nSo, in this example above, we are manually initializing each field of the C struct. We could say that, in this instance, we are “manually instantiating the C struct object”. However, when we use C libraries in our Zig code, we rarely need to manually instantiate the C structs like that. Only because C libraries usually provide a “constructor function” in their public APIs. As consequence, we normally rely on these constructor functions to properly initialize the C structs, and the struct fields for us.\nFor example, consider the Harfbuzz C library. This a text shaping C library, and it works around a “buffer object”, or, more specifically, an instance of the C struct hb_buffer_t. Therefore, we need to create an instance of this C struct if we want to use this C library. Luckily, this library offers the function hb_buffer_create(), which we can use to create such object. So the Zig code necessary to create such object would probably look something like this:\n\nconst c = @cImport({\n    @cInclude(\"hb.h\");\n});\nvar buf: c.hb_buffer_t = c.hb_buffer_create();\n// Do stuff with the \"buffer object\"\n\nTherefore, we do not need to manually create an instance of the C struct hb_buffer_t here, and manually assign valid values to each field in this C struct. Because the constructor function hb_buffer_create() is doing this heavy job for us.\nSince this buf object, and also, the new_user object from previous examples, are instances of C structs, these objects are by themselves C compatible values. They are C objects defined in our Zig code. As consequence, you can freely pass these objects as input to any C function that expects to receive this type of C struct as input. You do not need to use any special syntax, or, to convert them in any special manner to use them in C code. This is how we create and use C objects in our Zig code.",
     "crumbs": [
       "<span class='chapter-number'>14</span>  <span class='chapter-title'>Zig interoperability with C</span>"
     ]
@@ -1174,7 +1174,7 @@
     "href": "Chapters/14-zig-c-interop.html#sec-pass-c-structs",
     "title": "14  Zig interoperability with C",
     "section": "14.5 Passing C structs across Zig functions",
-    "text": "14.5 Passing C structs across Zig functions\nNow that we have learned how to create/declare C objects in our Zig code, we need to learn how to pass these C objects as inputs to Zig functions. As I described at Section 14.4, we can freely pass these C objects as inputs to C code that we call from our Zig code. But what about passing these C objects to Zig functions?\nIn essence, this specific case requires one small adjustment in the Zig function declaration. All you need to do, is to make sure that you pass your C object by reference to the function, instead of passing it by value. To do that, you have to annotate the data type of the function argument that is receiving this C object as “a pointer to the C struct”, instead of annotating it as “an instance of the C struct”.\nLet’s consider the C struct User from the user.h C header file that we have used at Section 14.4. Now, consider that we want to create a Zig function that sets the value of the id field in this C struct, like the set_user_id() function declared below. Notice that the user argument in this function is annotated as a pointer (*) to a c.User object.\nTherefore, all you have to do when passing C objects to Zig functions, is to add * to the data type of the function argument that is receiving the C object. This will make sure that the C object is passed by reference to the function.\nBecause we have transformed the function argument into a pointer, everytime that you have to access the value pointed by this input pointer inside the function body, for whatever reason (e.g. you want to read, update, or delete this value), you have to dereference the pointer with the .* syntax that we learned from Chapter 6. Notice that the set_user_id() function is using this syntax to alter the value in the id field of the User struct pointed by the input pointer.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst c = @cImport({\n    @cInclude(\"user.h\");\n});\nfn set_user_id(id: u64, user: *c.User) void {\n    user.*.id = id;\n}\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n\n    var new_user: c.User = undefined;\n    new_user.id = 1;\n    var user_name = try allocator.alloc(u8, 12);\n    defer allocator.free(user_name);\n    @memcpy(user_name[0..(user_name.len - 1)], \"pedropark99\");\n    user_name[user_name.len - 1] = 0;\n    new_user.name = user_name.ptr;\n\n    set_user_id(25, &new_user);\n    try stdout.print(\"New ID: {any}\\n\", .{new_user.id});\n}\n\nNew ID: 25",
+    "text": "14.5 Passing C structs across Zig functions\nNow that we have learned how to create/declare C objects in our Zig code, we need to learn how to pass these C objects as inputs to Zig functions. As I described in Section 14.4, we can freely pass these C objects as inputs to C code that we call from our Zig code. But what about passing these C objects to Zig functions?\nIn essence, this specific case requires one small adjustment in the Zig function declaration. All you need to do, is to make sure that you pass your C object by reference to the function, instead of passing it by value. To do that, you have to annotate the data type of the function argument that is receiving this C object as “a pointer to the C struct”, instead of annotating it as “an instance of the C struct”.\nLet’s consider the C struct User from the user.h C header file that we have used in Section 14.4. Now, consider that we want to create a Zig function that sets the value of the id field in this C struct, like the set_user_id() function declared below. Notice that the user argument in this function is annotated as a pointer (*) to a c.User object.\nTherefore, all you have to do when passing C objects to Zig functions, is to add * to the data type of the function argument that is receiving the C object. This will make sure that the C object is passed by reference to the function.\nBecause we have transformed the function argument into a pointer, everytime that you have to access the value pointed by this input pointer inside the function body, for whatever reason (e.g. you want to read, update, or delete this value), you have to dereference the pointer with the .* syntax that we learned from Chapter 6. Notice that the set_user_id() function is using this syntax to alter the value in the id field of the User struct pointed by the input pointer.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst c = @cImport({\n    @cInclude(\"user.h\");\n});\nfn set_user_id(id: u64, user: *c.User) void {\n    user.*.id = id;\n}\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n\n    var new_user: c.User = undefined;\n    new_user.id = 1;\n    var user_name = try allocator.alloc(u8, 12);\n    defer allocator.free(user_name);\n    @memcpy(user_name[0..(user_name.len - 1)], \"pedropark99\");\n    user_name[user_name.len - 1] = 0;\n    new_user.name = user_name.ptr;\n\n    set_user_id(25, &new_user);\n    try stdout.print(\"New ID: {any}\\n\", .{new_user.id});\n}\n\nNew ID: 25",
     "crumbs": [
       "<span class='chapter-number'>14</span>  <span class='chapter-title'>Zig interoperability with C</span>"
     ]
@@ -1214,7 +1214,7 @@
     "href": "Chapters/13-image-filter.html#sec-digital-img",
     "title": "15  Project 4 - Developing an image filter",
     "section": "15.2 How digital images work?",
-    "text": "15.2 How digital images work?\nA digital image is a “digital representation” of an image that we see with our eyes. In other words, a digital image is a “digital representation” of the colors that we see and perceive through the light. In the digital world, we have two types of images, which are: vector images and raster images. Vector images are not described here. So just remember that the content discussed here is related solely to raster images, and not vector images.\nA raster image is a type of digital image that is represented as a 2D (two dimensional) matrix of pixels. In other words, every raster image is basically a rectangle of pixels, and each pixel have a particular color. So, a raster image is just a rectangle of pixels, and each of these pixels are displayed in the screen of your computer (or the screen of any other device, e.g. laptop, tablet, smartphone, etc.) as a color.\nFigure 15.3 demonstrates this idea. If you take any raster image, and you zoom into it very hard, you will see the actual pixels of the image. JPEG, TIFF and PNG are file formats that are commonly used to store raster images.\n\n\n\n\n\n\nFigure 15.3: Zooming over a raster image to see the pixels. Source: Google Images.\n\n\n\nThe more pixels the image has, the more information and detail we can include in the image. The more accurate, sharp and pretty the image will look. This is why photographic cameras usually produce big raster images, with several megapixels of resolution, to include as much detail as possible into the final image. As an example, a digital image with dimensions of 1920 pixels wide and 1080 pixels high, would be a image that contains \\(1920 \\times 1080 = 2073600\\) pixels in total. You could also say that the “total area” of the image is of 2073600 pixels, although the concept of “area” is not really used here in computer graphics.\nMost digital images we see in our modern world uses the RGB color model. RGB stands for (red, green and blue). So the color of each pixel in these raster images are usually represented as a mixture of red, green and blue, just like in our eyes. That is, the color of each pixel is identified by a set of three different integer values. Each integer value identifies the “amount” of each color (red, green and blue). For example, the set (199, 78, 70) identifies a color that is more close to red. We have 199 of red, 78 of green, and 70 of blue. In contrast, the set (129, 77, 250) describes a color that is more close to purple. Et cetera.\n\n15.2.1 Images are displayed from top to bottom\nThis is not a rule written in stone, but the big majority of digital images are displayed from top to bottom and left to right. Most computers screens also follow this pattern. So, the first pixels in the image are the ones that are at the top and left corner of the image. You can find a visual representation of this logic at Figure 15.4.\nAlso notice in Figure 15.4 that, because a raster image is essentially a 2D matrix of pixels, the image is organized into rows and columns of pixels. The columns are defined by the horizontal x axis, while the rows are defined by the vertical y axis.\nEach pixel (i.e. the gray rectangles) exposed at Figure 15.4 contains a number inside of it. These numbers are the indexes of the pixels. You can notice that the first pixels are in the top and left corner, and also, that the indexes of these pixels “grow to the sides”, or, in other words, they grow in the direction of the horizontal x axis. Most raster images are organized as rows of pixels. Thus, when these digital images are displayed, the screen display the first row of pixels, then, the second row, then, the third row, etc.\n\n\n\n\n\n\nFigure 15.4: How the pixels of raster images are displayed.\n\n\n\n\n\n15.2.2 Representing the matrix of pixels in code\nOk, we know already that raster images are represented as 2D matrices of pixels. But we do not have a notion of a 2D matrix in Zig. Actually, most low-level languages in general (Zig, C, Rust, etc.) do not have such notion. So how can we represent such matrix of pixels in Zig, or any other low-level language? The strategy that most programmers choose in this situation is to just use a normal 1D array to store the values of this 2D matrix. In other words, you just create an normal 1D array, and store all values from both dimensions into this 1D array.\nAs an example, suppose we have a very small image of dimensions 4x3. Since a raster image is represented as a 2D matrix of pixels, and each pixel is represented by 3 “unsigned 8-bit” integer values, we have 12 pixels in total in this image, which are represented by \\(3 \\times 12 = 36\\) integer values. Therefore, we need to create an array of 36 u8 values to store this small image.\nThe reason why unsigned 8-bit integer (u8) values are used to represent the amounts of each color, instead of any other integer type, is because they take the minimum amount of space as possible, or, the minimum amount of bits as possible. Which helps to reduces the binary size of the image, i.e. the 2D matrix. Also, they convey a good amount of precision and detail about the colors, even though they can represent a relatively small range (from 0 to 255) of “color amounts”.\nComing back to our initial example of a 4x3 image, the matrix object exposed below could be an example of an 1D array that stores the data that represents this 4x3 image.\n\nconst matrix = [_]u8{\n    201, 10, 25, 185, 65, 70,\n    65, 120, 110, 65, 120, 117,\n    98, 95, 12, 213, 26, 88,\n    143, 112, 65, 97, 99, 205,\n    234, 105, 56, 43, 44, 216,\n    45, 59, 243, 211, 209, 54,\n};\n\nThe first three integer values in this array are the color amounts of the first pixel in the image. The next three integers are the colors amounts for the second pixel. And the sequence goes on in this pattern. Having that in mind, the size of the array that stores a raster image is usually a multiple of 3. In this case, the array have a size of 36.\nI mean, the size of the array is usually a multiple of 3, because in specific circumstances, it can also be a multiple of 4. This happens when a transparency amount is also included into the raster image. In other words, there are some types of raster images that uses a different color model, which is the RGBA (red, green, blue and alpha) color model. The “alpha” corresponds to an amount of transparency in the pixel. So every pixel in a RGBA image is represented by a red, green, blue and alpha values.\nMost raster images uses the standard RGB model, so, for the most part, you will see arrays sizes that are multiples of 3. But some images, especially the ones that are stored in PNG files, might be using the RGBA model, and, therefore, are represented by an array whose size is a multiple of 4.\nIn our case here, the example image of our project (Figure 15.1) is a raster image stored in a PNG file, and this specific image is using the RGBA color model. Therefore, each pixel in the image is represented by 4 different integer values, and, as consequence, to store this image in our Zig code, we need to create an array whose size is a multiple of 4.",
+    "text": "15.2 How digital images work?\nA digital image is a “digital representation” of an image that we see with our eyes. In other words, a digital image is a “digital representation” of the colors that we see and perceive through the light. In the digital world, we have two types of images, which are: vector images and raster images. Vector images are not described here. So just remember that the content discussed here is related solely to raster images, and not vector images.\nA raster image is a type of digital image that is represented as a 2D (two dimensional) matrix of pixels. In other words, every raster image is basically a rectangle of pixels, and each pixel have a particular color. So, a raster image is just a rectangle of pixels, and each of these pixels are displayed in the screen of your computer (or the screen of any other device, e.g. laptop, tablet, smartphone, etc.) as a color.\nFigure 15.3 demonstrates this idea. If you take any raster image, and you zoom into it very hard, you will see the actual pixels of the image. JPEG, TIFF and PNG are file formats that are commonly used to store raster images.\n\n\n\n\n\n\nFigure 15.3: Zooming over a raster image to see the pixels. Source: Google Images.\n\n\n\nThe more pixels the image has, the more information and detail we can include in the image. The more accurate, sharp and pretty the image will look. This is why photographic cameras usually produce big raster images, with several megapixels of resolution, to include as much detail as possible into the final image. As an example, a digital image with dimensions of 1920 pixels wide and 1080 pixels high, would be a image that contains \\(1920 \\times 1080 = 2073600\\) pixels in total. You could also say that the “total area” of the image is of 2073600 pixels, although the concept of “area” is not really used here in computer graphics.\nMost digital images we see in our modern world uses the RGB color model. RGB stands for (red, green and blue). So the color of each pixel in these raster images are usually represented as a mixture of red, green and blue, just like in our eyes. That is, the color of each pixel is identified by a set of three different integer values. Each integer value identifies the “amount” of each color (red, green and blue). For example, the set (199, 78, 70) identifies a color that is more close to red. We have 199 of red, 78 of green, and 70 of blue. In contrast, the set (129, 77, 250) describes a color that is more close to purple. Et cetera.\n\n15.2.1 Images are displayed from top to bottom\nThis is not a rule written in stone, but the big majority of digital images are displayed from top to bottom and left to right. Most computers screens also follow this pattern. So, the first pixels in the image are the ones that are at the top and left corner of the image. You can find a visual representation of this logic in Figure 15.4.\nAlso notice in Figure 15.4 that, because a raster image is essentially a 2D matrix of pixels, the image is organized into rows and columns of pixels. The columns are defined by the horizontal x axis, while the rows are defined by the vertical y axis.\nEach pixel (i.e., the gray rectangles) exposed in Figure 15.4 contains a number inside of it. These numbers are the indexes of the pixels. You can notice that the first pixels are in the top and left corner, and also, that the indexes of these pixels “grow to the sides”, or, in other words, they grow in the direction of the horizontal x axis. Most raster images are organized as rows of pixels. Thus, when these digital images are displayed, the screen display the first row of pixels, then, the second row, then, the third row, etc.\n\n\n\n\n\n\nFigure 15.4: How the pixels of raster images are displayed.\n\n\n\n\n\n15.2.2 Representing the matrix of pixels in code\nOk, we know already that raster images are represented as 2D matrices of pixels. But we do not have a notion of a 2D matrix in Zig. Actually, most low-level languages in general (Zig, C, Rust, etc.) do not have such notion. So how can we represent such matrix of pixels in Zig, or any other low-level language? The strategy that most programmers choose in this situation is to just use a normal 1D array to store the values of this 2D matrix. In other words, you just create an normal 1D array, and store all values from both dimensions into this 1D array.\nAs an example, suppose we have a very small image of dimensions 4x3. Since a raster image is represented as a 2D matrix of pixels, and each pixel is represented by 3 “unsigned 8-bit” integer values, we have 12 pixels in total in this image, which are represented by \\(3 \\times 12 = 36\\) integer values. Therefore, we need to create an array of 36 u8 values to store this small image.\nThe reason why unsigned 8-bit integer (u8) values are used to represent the amounts of each color, instead of any other integer type, is because they take the minimum amount of space as possible, or, the minimum amount of bits as possible. Which helps to reduces the binary size of the image, i.e., the 2D matrix. Also, they convey a good amount of precision and detail about the colors, even though they can represent a relatively small range (from 0 to 255) of “color amounts”.\nComing back to our initial example of a 4x3 image, the matrix object exposed below could be an example of an 1D array that stores the data that represents this 4x3 image.\n\nconst matrix = [_]u8{\n    201, 10, 25, 185, 65, 70,\n    65, 120, 110, 65, 120, 117,\n    98, 95, 12, 213, 26, 88,\n    143, 112, 65, 97, 99, 205,\n    234, 105, 56, 43, 44, 216,\n    45, 59, 243, 211, 209, 54,\n};\n\nThe first three integer values in this array are the color amounts of the first pixel in the image. The next three integers are the colors amounts for the second pixel. And the sequence goes on in this pattern. Having that in mind, the size of the array that stores a raster image is usually a multiple of 3. In this case, the array have a size of 36.\nI mean, the size of the array is usually a multiple of 3, because in specific circumstances, it can also be a multiple of 4. This happens when a transparency amount is also included into the raster image. In other words, there are some types of raster images that uses a different color model, which is the RGBA (red, green, blue and alpha) color model. The “alpha” corresponds to an amount of transparency in the pixel. So every pixel in a RGBA image is represented by a red, green, blue and alpha values.\nMost raster images uses the standard RGB model, so, for the most part, you will see arrays sizes that are multiples of 3. But some images, especially the ones that are stored in PNG files, might be using the RGBA model, and, therefore, are represented by an array whose size is a multiple of 4.\nIn our case here, the example image of our project (Figure 15.1) is a raster image stored in a PNG file, and this specific image is using the RGBA color model. Therefore, each pixel in the image is represented by 4 different integer values, and, as consequence, to store this image in our Zig code, we need to create an array whose size is a multiple of 4.",
     "crumbs": [
       "<span class='chapter-number'>15</span>  <span class='chapter-title'>Project 4 - Developing an image filter</span>"
     ]
@@ -1224,7 +1224,7 @@
     "href": "Chapters/13-image-filter.html#the-png-library-that-we-are-going-to-use",
     "title": "15  Project 4 - Developing an image filter",
     "section": "15.3 The PNG library that we are going to use",
-    "text": "15.3 The PNG library that we are going to use\nLet’s begin our project by focusing on writing the necessary Zig code to read the data from the PNG file. In other words, we want to read the PNG file exposed at Figure 15.1, and parse its data to extract the 2D matrix of pixels that represents the image.\nAs we have discussed at Section 15.2.2, the image that we are using as example here is a PNG file that uses the RGBA color model, and, therefore, each pixel of the image is represented by 4 integer values. You can download this image by visiting the ZigExamples/image_filter folder at the official repository of this book3. You can also find in this folder the complete source code of this small project that we are developing here.\nThere are some C libraries available that we can use to read and parse PNG files. The most famous and used of all is libpng, which is the “official library” for reading and writing PNG files. Although this library is available on most operating system, it is well known for being complex and hard to use.\nThat is why, I’m going to use a more modern alternative here in this project, which is the libspng library. I choose to use this C library here, because it is much, much simpler to use than libpng, and it also offers very good performance for all operations. You can checkout the official website of the library4 to know more about it. You will also find there some documentation that might help you to understand and follow the code examples exposed here.\nFirst of all, remember to build and install this libspng into your system. Because if you don’t do this step, the zig compiler will not be able to find the files and resources of this library in your computer, and link them with the Zig source code that we are writing together here. There is good information about how to build and install the library at the build section of the library documentation5.",
+    "text": "15.3 The PNG library that we are going to use\nLet’s begin our project by focusing on writing the necessary Zig code to read the data from the PNG file. In other words, we want to read the PNG file exposed in Figure 15.1, and parse its data to extract the 2D matrix of pixels that represents the image.\nAs we have discussed in Section 15.2.2, the image that we are using as example here is a PNG file that uses the RGBA color model, and, therefore, each pixel of the image is represented by 4 integer values. You can download this image by visiting the ZigExamples/image_filter folder at the official repository of this book3. You can also find in this folder the complete source code of this small project that we are developing here.\nThere are some C libraries available that we can use to read and parse PNG files. The most famous and used of all is libpng, which is the “official library” for reading and writing PNG files. Although this library is available on most operating system, it’s well known for being complex and hard to use.\nThat is why, I’m going to use a more modern alternative here in this project, which is the libspng library. I choose to use this C library here, because it’s much, much simpler to use than libpng, and it also offers very good performance for all operations. You can checkout the official website of the library4 to know more about it. You will also find there some documentation that might help you to understand and follow the code examples exposed here.\nFirst of all, remember to build and install this libspng into your system. Because if you don’t do this step, the zig compiler will not be able to find the files and resources of this library in your computer, and link them with the Zig source code that we are writing together here. There is good information about how to build and install the library at the build section of the library documentation5.",
     "crumbs": [
       "<span class='chapter-number'>15</span>  <span class='chapter-title'>Project 4 - Developing an image filter</span>"
     ]
@@ -1234,7 +1234,7 @@
     "href": "Chapters/13-image-filter.html#reading-the-png-file",
     "title": "15  Project 4 - Developing an image filter",
     "section": "15.4 Reading the PNG file",
-    "text": "15.4 Reading the PNG file\nIn order to extract the pixel data from the PNG file, we need to read and decode the file. A PNG file is just a binary file written in the “PNG format”. Luckily, the libspng library offers a function called spng_decode_image() that does all this heavy work for us.\nNow, since libspng is a C library, most of the file and I/O operations in this library are made by using a FILE C pointer. Because of that, is probably a better idea to use the fopen() C function to open our PNG file, instead of using the openFile() method that I introduced at Chapter 13. That is why I’m importing the stdio.h C header in this project, and using the fopen() C function to open the file.\nIf you look at the snippet below, you can see that we are:\n\nopening the PNG file with fopen().\ncreating the libspng context with spng_ctx_new().\nusing spng_set_png_file() to specify the FILE object that reads the PNG file that we are going to use.\n\nEvery operation in libspng is made through a “context object”. In our snippet below, this object is ctx. Also, to perform an operation over a PNG file, we need to specify which exact PNG file we are referring to. This is the job of spng_set_png_file(). We are using this function to specify the file descriptor object that reads the PNG file that we want to use.\n\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n    @cInclude(\"spng.h\");\n});\n\nconst path = \"pedro_pascal.png\";\nconst file_descriptor = c.fopen(path, \"rb\");\nif (file_descriptor == null) {\n    @panic(\"Could not open file!\");\n}\nconst ctx = c.spng_ctx_new(0) orelse unreachable;\n_ = c.spng_set_png_file(\n    ctx, @ptrCast(file_descriptor)\n);\n\nBefore we continue, is important to emphasize the following: since we have opened the file with fopen(), we have to remember to close the file at the end of the program, with fclose(). In other words, after we have done everything that we wanted to do with the PNG file pedro_pascal.png, we need to close this file, by applying fclose() over the file descriptor object. We could use also the defer keyword to help us in this task, if we want to. This code snippet below demonstrates this step:\n\nif (c.fclose(file_descriptor) != 0) {\n    return error.CouldNotCloseFileDescriptor;\n}\n\n\n15.4.1 Reading the image header section\nNow, the context object ctx is aware of our PNG file pedro_pascal.png, because it has access to a file descriptor object to this file. The first thing that we are going to do is to read the “image header section” of the PNG file. This “image header section” is the section of the file that contains some basic information about the PNG file, like, the bit depth of the pixel data of the image, the color model used in the file, the dimensions of the image (height and width in number of pixels), etc.\nTo make things easier, I will encapsulate this “read image header” operation into a nice and small function called get_image_header(). All that this function needs to do is to call the spng_get_ihdr() function. This function from libspng is responsible for reading the image header data, and storing it into a C struct named spng_ihdr. Thus, an object of type spng_ihdr is a C struct that contains the data from the image header section of the PNG file.\nSince this Zig function is receiving a C object (the libspng context object) as input, I marked the function argument ctx as “a pointer to the context object” (*c.spng_ctx), following the recommendations that we have discussed at Section 14.5.\n\nfn get_image_header(ctx: *c.spng_ctx) !c.spng_ihdr {\n    var image_header: c.spng_ihdr = undefined;\n    if (c.spng_get_ihdr(ctx, &image_header) != 0) {\n        return error.CouldNotGetImageHeader;\n    }\n\n    return image_header;\n}\n\nvar image_header = try get_image_header(ctx);\n\nAlso notice in this function, that I’m checking if the spng_get_ihdr() function call have returned or not an integer value that is different than zero. Most functions from the libspng library return a code status as result, and the code status “zero” means “success”. So any code status that is different than zero means that an error occurred while running spng_get_ihdr(). This is why I’m returning an error value from the function in case the code status returned by the function is different than zero.\n\n\n15.4.2 Allocating space for the pixel data\nBefore we read the pixel data from the PNG file, we need to allocate enough space to hold this data. But in order to allocate such space, we first need to know how much space we need to allocate. The dimensions of the image are obviously needed to calculate the size of this space. But there are other elements that also affect this number, such as the color model used in the image, the bit depth, and others.\nAnyway, all of this means that calculating the size of the space that we need, is not a simple task. That is why the libspng library offers an utility function named spng_decoded_image_size() to calculate this size for us. Once again, I’m going to encapsulate the logic around this C function into a nice and small Zig function named calc_output_size(). You can see below that this function returns a nice integer value as result, informing the size of the space that we need to allocate.\n\nfn calc_output_size(ctx: *c.spng_ctx) !u64 {\n    var output_size: u64 = 0;\n    const status = c.spng_decoded_image_size(\n        ctx, c.SPNG_FMT_RGBA8, &output_size\n    );\n    if (status != 0) {\n        return error.CouldNotCalcOutputSize;\n    }\n    return output_size;\n}\n\nYou might quest yourself what the value SPNG_FMT_RGBA8 means. This value is actually an enum value defined in the spng.h C header file. This enum is used to identify a “PNG format”. More precisely, it identifies a PNG file that uses the RGBA color model and 8 bit depth. So, by providing this enum value as input to the spng_decoded_image_size() function, we are saying to this function to calculate the size of the decoded pixel data, by considering a PNG file that follows this “RGBA color model with 8 bit depth” format.\nHaving this function, we can use it in conjunction with an allocator object, to allocate an array of bytes (u8 values) that is big enough to store the decoded pixel data of the image. Notice that I’m using @memset() to initialize the entire array to zero.\n\nconst output_size = try calc_output_size(ctx);\nvar buffer = try allocator.alloc(u8, output_size);\n@memset(buffer[0..], 0);\n\n\n\n15.4.3 Decoding the image data\nNow that we have the necessary space to store the decoded pixel data of the image, we can start to actually decode and extract this pixel data from the image, by using the spng_decode_image() C function.\nThe read_data_to_buffer() Zig function exposed below summarises the necessary steps to read this decoded pixel data, and store it into an input buffer. Notice that this function is encapsulating the logic around the spng_decode_image() function. Also, we are using the SPNG_FMT_RGBA8 enum value once again to inform the corresponding function, that the PNG image being decoded, uses the RGBA color model and 8 bit depth.\n\nfn read_data_to_buffer(ctx: *c.spng_ctx, buffer: []u8) !void {\n    const status = c.spng_decode_image(\n        ctx,\n        buffer.ptr,\n        buffer.len,\n        c.SPNG_FMT_RGBA8,\n        0\n    );\n\n    if (status != 0) {\n        return error.CouldNotDecodeImage;\n    }\n}\n\nHaving this function at hand, we can apply it over our context object, and also, over the buffer object that we have allocated in the previous section to hold the decoded pixel data of the image:\n\ntry read_data_to_buffer(ctx, buffer[0..]);\n\n\n\n15.4.4 Looking at the pixel data\nNow that we have the pixel data stored in our “buffer object”, we can take a quick look at the bytes. In the example below, we are looking at the first 12 bytes in the decoded pixel data.\nIf you take a close look at these values, you might notice that every 4 bytes in the sequence is 255. Which, coincidentally is the maximum possible integer value to be represented by a u8 value. So, if the range from 0 to 255, which is the range of integer values that can be represented by an u8 value, can be represented as a scale from 0% to 100%, these 255 values are essentially 100% in that scale.\nIf you recall from Section 15.2.2, I have described in that section that our pedro_pascal.png PNG file uses the RGBA color model, which adds an alpha (or transparency) byte to each pixel in the image. As consequence, each pixel in the image is represented by 4 bytes. Since we are looking here are the first 12 bytes in the image, it means that we are looking at the data from the first \\(12 / 4 = 3\\) pixels in the image.\nSo, based on how these first 12 bytes (or these 3 pixels) look, with these 255 values at every 4 bytes, we can say that is likely that every pixel in the image have alpha (or transparency) setted to 100%. This might not be true, but, is the most likely possibility. Also, if we look at the image itself, which if your recall is exposed at Figure 15.1, we can see that the transparency does not change across the image, which enforces this theory.\n\ntry stdout.print(\"{any}\\n\", .{buffer[0..12]});\n\n{\n    200, 194, 216, 255, 203, 197,\n    219, 255, 206, 200, 223, 255\n}\nWe can see in the above result that the first pixel in this image have 200 of red, 194 of green, and 216 of blue. How do I know the order in which the colors appears in the sequence? If you have not guessed that yet, is because of the acronym RGB. First RED, then GREEN, then BLUE. If we scale these integer values according to our scale of 0% to 100% (0 to 255), we get 78% of red, 76% of green and 85% of blue.",
+    "text": "15.4 Reading the PNG file\nIn order to extract the pixel data from the PNG file, we need to read and decode the file. A PNG file is just a binary file written in the “PNG format”. Luckily, the libspng library offers a function called spng_decode_image() that does all this heavy work for us.\nNow, since libspng is a C library, most of the file and I/O operations in this library are made by using a FILE C pointer. Because of that, is probably a better idea to use the fopen() C function to open our PNG file, instead of using the openFile() method that I introduced in Chapter 13. That is why I’m importing the stdio.h C header in this project, and using the fopen() C function to open the file.\nIf you look at the snippet below, you can see that we are:\n\nopening the PNG file with fopen().\ncreating the libspng context with spng_ctx_new().\nusing spng_set_png_file() to specify the FILE object that reads the PNG file that we are going to use.\n\nEvery operation in libspng is made through a “context object”. In our snippet below, this object is ctx. Also, to perform an operation over a PNG file, we need to specify which exact PNG file we are referring to. This is the job of spng_set_png_file(). We are using this function to specify the file descriptor object that reads the PNG file that we want to use.\n\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n    @cInclude(\"spng.h\");\n});\n\nconst path = \"pedro_pascal.png\";\nconst file_descriptor = c.fopen(path, \"rb\");\nif (file_descriptor == null) {\n    @panic(\"Could not open file!\");\n}\nconst ctx = c.spng_ctx_new(0) orelse unreachable;\n_ = c.spng_set_png_file(\n    ctx, @ptrCast(file_descriptor)\n);\n\nBefore we continue, is important to emphasize the following: since we have opened the file with fopen(), we have to remember to close the file at the end of the program, with fclose(). In other words, after we have done everything that we wanted to do with the PNG file pedro_pascal.png, we need to close this file, by applying fclose() over the file descriptor object. We could use also the defer keyword to help us in this task, if we want to. This code snippet below demonstrates this step:\n\nif (c.fclose(file_descriptor) != 0) {\n    return error.CouldNotCloseFileDescriptor;\n}\n\n\n15.4.1 Reading the image header section\nNow, the context object ctx is aware of our PNG file pedro_pascal.png, because it has access to a file descriptor object to this file. The first thing that we are going to do is to read the “image header section” of the PNG file. This “image header section” is the section of the file that contains some basic information about the PNG file, like, the bit depth of the pixel data of the image, the color model used in the file, the dimensions of the image (height and width in number of pixels), etc.\nTo make things easier, I will encapsulate this “read image header” operation into a nice and small function called get_image_header(). All that this function needs to do is to call the spng_get_ihdr() function. This function from libspng is responsible for reading the image header data, and storing it into a C struct named spng_ihdr. Thus, an object of type spng_ihdr is a C struct that contains the data from the image header section of the PNG file.\nSince this Zig function is receiving a C object (the libspng context object) as input, I marked the function argument ctx as “a pointer to the context object” (*c.spng_ctx), following the recommendations that we have discussed in Section 14.5.\n\nfn get_image_header(ctx: *c.spng_ctx) !c.spng_ihdr {\n    var image_header: c.spng_ihdr = undefined;\n    if (c.spng_get_ihdr(ctx, &image_header) != 0) {\n        return error.CouldNotGetImageHeader;\n    }\n\n    return image_header;\n}\n\nvar image_header = try get_image_header(ctx);\n\nAlso notice in this function, that I’m checking if the spng_get_ihdr() function call have returned or not an integer value that is different than zero. Most functions from the libspng library return a code status as result, and the code status “zero” means “success”. So any code status that is different than zero means that an error occurred while running spng_get_ihdr(). This is why I’m returning an error value from the function in case the code status returned by the function is different than zero.\n\n\n15.4.2 Allocating space for the pixel data\nBefore we read the pixel data from the PNG file, we need to allocate enough space to hold this data. But in order to allocate such space, we first need to know how much space we need to allocate. The dimensions of the image are obviously needed to calculate the size of this space. But there are other elements that also affect this number, such as the color model used in the image, the bit depth, and others.\nAnyway, all of this means that calculating the size of the space that we need, is not a simple task. That is why the libspng library offers an utility function named spng_decoded_image_size() to calculate this size for us. Once again, I’m going to encapsulate the logic around this C function into a nice and small Zig function named calc_output_size(). You can see below that this function returns a nice integer value as result, informing the size of the space that we need to allocate.\n\nfn calc_output_size(ctx: *c.spng_ctx) !u64 {\n    var output_size: u64 = 0;\n    const status = c.spng_decoded_image_size(\n        ctx, c.SPNG_FMT_RGBA8, &output_size\n    );\n    if (status != 0) {\n        return error.CouldNotCalcOutputSize;\n    }\n    return output_size;\n}\n\nYou might quest yourself what the value SPNG_FMT_RGBA8 means. This value is actually an enum value defined in the spng.h C header file. This enum is used to identify a “PNG format”. More precisely, it identifies a PNG file that uses the RGBA color model and 8 bit depth. So, by providing this enum value as input to the spng_decoded_image_size() function, we are saying to this function to calculate the size of the decoded pixel data, by considering a PNG file that follows this “RGBA color model with 8 bit depth” format.\nHaving this function, we can use it in conjunction with an allocator object, to allocate an array of bytes (u8 values) that is big enough to store the decoded pixel data of the image. Notice that I’m using @memset() to initialize the entire array to zero.\n\nconst output_size = try calc_output_size(ctx);\nvar buffer = try allocator.alloc(u8, output_size);\n@memset(buffer[0..], 0);\n\n\n\n15.4.3 Decoding the image data\nNow that we have the necessary space to store the decoded pixel data of the image, we can start to actually decode and extract this pixel data from the image, by using the spng_decode_image() C function.\nThe read_data_to_buffer() Zig function exposed below summarises the necessary steps to read this decoded pixel data, and store it into an input buffer. Notice that this function is encapsulating the logic around the spng_decode_image() function. Also, we are using the SPNG_FMT_RGBA8 enum value once again to inform the corresponding function, that the PNG image being decoded, uses the RGBA color model and 8 bit depth.\n\nfn read_data_to_buffer(ctx: *c.spng_ctx, buffer: []u8) !void {\n    const status = c.spng_decode_image(\n        ctx,\n        buffer.ptr,\n        buffer.len,\n        c.SPNG_FMT_RGBA8,\n        0\n    );\n\n    if (status != 0) {\n        return error.CouldNotDecodeImage;\n    }\n}\n\nHaving this function at hand, we can apply it over our context object, and also, over the buffer object that we have allocated in the previous section to hold the decoded pixel data of the image:\n\ntry read_data_to_buffer(ctx, buffer[0..]);\n\n\n\n15.4.4 Looking at the pixel data\nNow that we have the pixel data stored in our “buffer object”, we can take a quick look at the bytes. In the example below, we are looking at the first 12 bytes in the decoded pixel data.\nIf you take a close look at these values, you might notice that every 4 bytes in the sequence is 255. Which, coincidentally is the maximum possible integer value to be represented by a u8 value. So, if the range from 0 to 255, which is the range of integer values that can be represented by an u8 value, can be represented as a scale from 0% to 100%, these 255 values are essentially 100% in that scale.\nIf you recall from Section 15.2.2, I have described in that section that our pedro_pascal.png PNG file uses the RGBA color model, which adds an alpha (or transparency) byte to each pixel in the image. As consequence, each pixel in the image is represented by 4 bytes. Since we are looking here are the first 12 bytes in the image, it means that we are looking at the data from the first \\(12 / 4 = 3\\) pixels in the image.\nSo, based on how these first 12 bytes (or these 3 pixels) look, with these 255 values at every 4 bytes, we can say that is likely that every pixel in the image have alpha (or transparency) setted to 100%. This might not be true, but, is the most likely possibility. Also, if we look at the image itself, which if your recall is exposed in Figure 15.1, we can see that the transparency does not change across the image, which enforces this theory.\n\ntry stdout.print(\"{any}\\n\", .{buffer[0..12]});\n\n{\n    200, 194, 216, 255, 203, 197,\n    219, 255, 206, 200, 223, 255\n}\nWe can see in the above result that the first pixel in this image have 200 of red, 194 of green, and 216 of blue. How do I know the order in which the colors appears in the sequence? If you have not guessed that yet, is because of the acronym RGB. First RED, then GREEN, then BLUE. If we scale these integer values according to our scale of 0% to 100% (0 to 255), we get 78% of red, 76% of green and 85% of blue.",
     "crumbs": [
       "<span class='chapter-number'>15</span>  <span class='chapter-title'>Project 4 - Developing an image filter</span>"
     ]
@@ -1244,7 +1244,7 @@
     "href": "Chapters/13-image-filter.html#applying-the-image-filter",
     "title": "15  Project 4 - Developing an image filter",
     "section": "15.5 Applying the image filter",
-    "text": "15.5 Applying the image filter\nNow that we have the data of each pixel in the image, we can focus on applying our image filter over these pixels. Remember, our objective here is to apply a grayscale filter over the image. A grayscale filter is a filter that transforms a colored image into a grayscale image.\nThere are different formulas and strategies to transform a colored image into a grayscale image. But all of these different strategies normally involve applying some math over the colors of each pixel. In this project, we are going to use the most general formula, which is exposed below. This formula considers \\(r\\) as the red of the pixel, \\(g\\) as the green, \\(b\\) as the blue, and \\(p'\\) as the linear luminance of the pixel.\n\\[\n    p' = (0.2126 \\times r) + (0.7152 \\times g) + (0.0722 \\times b)\n\\tag{15.1}\\]\nThis Equation 15.1 is the formula to calculate the linear luminance of a pixel. Is worth noting that this formula works only for images whose pixels are using the sRGB color space, which is the standard color space for the web. Thus, ideally, all images on the web should use this color space. Luckily, this is our case here, i.e. the pedro_pascal.png image is using this sRGB color space, and, as consequence, we can use the Equation 15.1. You can read more about this formula at the Wikipedia page for grayscale (Wikipedia 2024).\nThe apply_image_filter() function exposed below summarises the necessary steps to apply Equation 15.1 over the pixels in the image. We just apply this function over our buffer object that contains our pixel data, and, as result, the pixel data stored in this buffer object should now represent the grayscale version of our image.\n\nfn apply_image_filter(buffer:[]u8) !void {\n    const len = buffer.len;\n    const red_factor: f16 = 0.2126;\n    const green_factor: f16 = 0.7152;\n    const blue_factor: f16 = 0.0722;\n    var index: u64 = 0;\n    while (index &lt; len) : (index += 4) {\n        const rf: f16 = @floatFromInt(buffer[index]);\n        const gf: f16 = @floatFromInt(buffer[index + 1]);\n        const bf: f16 = @floatFromInt(buffer[index + 2]);\n        const y_linear: f16 = (\n            (rf * red_factor) + (gf * green_factor)\n            + (bf * blue_factor)\n        );\n        buffer[index] = @intFromFloat(y_linear);\n        buffer[index + 1] = @intFromFloat(y_linear);\n        buffer[index + 2] = @intFromFloat(y_linear);\n    }\n}\n\ntry apply_image_filter(buffer[0..]);",
+    "text": "15.5 Applying the image filter\nNow that we have the data of each pixel in the image, we can focus on applying our image filter over these pixels. Remember, our objective here is to apply a grayscale filter over the image. A grayscale filter is a filter that transforms a colored image into a grayscale image.\nThere are different formulas and strategies to transform a colored image into a grayscale image. But all of these different strategies normally involve applying some math over the colors of each pixel. In this project, we are going to use the most general formula, which is exposed below. This formula considers \\(r\\) as the red of the pixel, \\(g\\) as the green, \\(b\\) as the blue, and \\(p'\\) as the linear luminance of the pixel.\n\\[\n    p' = (0.2126 \\times r) + (0.7152 \\times g) + (0.0722 \\times b)\n\\tag{15.1}\\]\nThis Equation 15.1 is the formula to calculate the linear luminance of a pixel. It’s worth noting that this formula works only for images whose pixels are using the sRGB color space, which is the standard color space for the web. Thus, ideally, all images on the web should use this color space. Luckily, this is our case here, i.e., the pedro_pascal.png image is using this sRGB color space, and, as consequence, we can use the Equation 15.1. You can read more about this formula at the Wikipedia page for grayscale (Wikipedia 2024).\nThe apply_image_filter() function exposed below summarises the necessary steps to apply Equation 15.1 over the pixels in the image. We just apply this function over our buffer object that contains our pixel data, and, as result, the pixel data stored in this buffer object should now represent the grayscale version of our image.\n\nfn apply_image_filter(buffer:[]u8) !void {\n    const len = buffer.len;\n    const red_factor: f16 = 0.2126;\n    const green_factor: f16 = 0.7152;\n    const blue_factor: f16 = 0.0722;\n    var index: u64 = 0;\n    while (index &lt; len) : (index += 4) {\n        const rf: f16 = @floatFromInt(buffer[index]);\n        const gf: f16 = @floatFromInt(buffer[index + 1]);\n        const bf: f16 = @floatFromInt(buffer[index + 2]);\n        const y_linear: f16 = (\n            (rf * red_factor) + (gf * green_factor)\n            + (bf * blue_factor)\n        );\n        buffer[index] = @intFromFloat(y_linear);\n        buffer[index + 1] = @intFromFloat(y_linear);\n        buffer[index + 2] = @intFromFloat(y_linear);\n    }\n}\n\ntry apply_image_filter(buffer[0..]);",
     "crumbs": [
       "<span class='chapter-number'>15</span>  <span class='chapter-title'>Project 4 - Developing an image filter</span>"
     ]
@@ -1254,7 +1254,7 @@
     "href": "Chapters/13-image-filter.html#saving-the-grayscale-version-of-the-image",
     "title": "15  Project 4 - Developing an image filter",
     "section": "15.6 Saving the grayscale version of the image",
-    "text": "15.6 Saving the grayscale version of the image\nSince we have now the grayscale version of our image stored in our buffer object, we need to encode this buffer object back into the “PNG format”, and save the encoded data into a new PNG file in our filesystem, so that we can access and see the grayscale version of our image that was produced by our small program.\nTo do that, the libspng library help us once again by offering an “encode data to PNG” type of function, which is the spng_encode_image() function. But in order to “encode data to PNG” with libspng, we need to create a new context object. This new context object must use an “encoder context”, which is identified by the enum value SPNG_CTX_ENCODER.\nThe save_png() function exposed below, summarises all the necessary steps to save the grayscale version of our image into a new PNG file in the filesystem. By default, this function will save the grayscale image into a file named pedro_pascal_filter.png in the CWD.\nNotice in this code example that we are using the same image header object (image_header) that we have collected previously with the get_image_header() function. Remember, this image header object is a C struct (spng_ihdr) that contains basic information about our PNG file, such as the dimensions of the image, the color model used, etc.\nIf we wanted to save a very different image in this new PNG file, e.g. an image with different dimensions, or, an image that uses a different color model, a different bit depth, etc. we would have to create a new image header (spng_ihdr) object that describes the properties of this new image.\nBut we are essentially saving the same image that we have begin with here (the dimensions of the image, the color model, etc. are all still the same). The only difference between the two images are the colors of the pixels, which are now “shades of gray”. As consequence, we can safely use the exact same image header data in this new PNG file.\n\nfn save_png(image_header: *c.spng_ihdr, buffer: []u8) !void {\n    const path = \"pedro_pascal_filter.png\";\n    const file_descriptor = c.fopen(path.ptr, \"wb\");\n    if (file_descriptor == null) {\n        return error.CouldNotOpenFile;\n    }\n    const ctx = (\n        c.spng_ctx_new(c.SPNG_CTX_ENCODER)\n        orelse unreachable\n    );\n    defer c.spng_ctx_free(ctx);\n    _ = c.spng_set_png_file(ctx, @ptrCast(file_descriptor));\n    _ = c.spng_set_ihdr(ctx, image_header);\n\n    const encode_status = c.spng_encode_image(\n        ctx,\n        buffer.ptr,\n        buffer.len,\n        c.SPNG_FMT_PNG,\n        c.SPNG_ENCODE_FINALIZE\n    );\n    if (encode_status != 0) {\n        return error.CouldNotEncodeImage;\n    }\n    if (c.fclose(file_descriptor) != 0) {\n        return error.CouldNotCloseFileDescriptor;\n    }\n}\n\ntry save_png(&image_header, buffer[0..]);\n\nAfter we execute this save_png() function, we should have a new PNG file inside our CWD, named pedro_pascal_filter.png. If we open this PNG file, we will see the same image exposed at Figure 15.2.",
+    "text": "15.6 Saving the grayscale version of the image\nSince we have now the grayscale version of our image stored in our buffer object, we need to encode this buffer object back into the “PNG format”, and save the encoded data into a new PNG file in our filesystem, so that we can access and see the grayscale version of our image that was produced by our small program.\nTo do that, the libspng library help us once again by offering an “encode data to PNG” type of function, which is the spng_encode_image() function. But in order to “encode data to PNG” with libspng, we need to create a new context object. This new context object must use an “encoder context”, which is identified by the enum value SPNG_CTX_ENCODER.\nThe save_png() function exposed below, summarises all the necessary steps to save the grayscale version of our image into a new PNG file in the filesystem. By default, this function will save the grayscale image into a file named pedro_pascal_filter.png in the CWD.\nNotice in this code example that we are using the same image header object (image_header) that we have collected previously with the get_image_header() function. Remember, this image header object is a C struct (spng_ihdr) that contains basic information about our PNG file, such as the dimensions of the image, the color model used, etc.\nIf we wanted to save a very different image in this new PNG file, e.g. an image with different dimensions, or, an image that uses a different color model, a different bit depth, etc. we would have to create a new image header (spng_ihdr) object that describes the properties of this new image.\nBut we are essentially saving the same image that we have begin with here (the dimensions of the image, the color model, etc. are all still the same). The only difference between the two images are the colors of the pixels, which are now “shades of gray”. As consequence, we can safely use the exact same image header data in this new PNG file.\n\nfn save_png(image_header: *c.spng_ihdr, buffer: []u8) !void {\n    const path = \"pedro_pascal_filter.png\";\n    const file_descriptor = c.fopen(path.ptr, \"wb\");\n    if (file_descriptor == null) {\n        return error.CouldNotOpenFile;\n    }\n    const ctx = (\n        c.spng_ctx_new(c.SPNG_CTX_ENCODER)\n        orelse unreachable\n    );\n    defer c.spng_ctx_free(ctx);\n    _ = c.spng_set_png_file(ctx, @ptrCast(file_descriptor));\n    _ = c.spng_set_ihdr(ctx, image_header);\n\n    const encode_status = c.spng_encode_image(\n        ctx,\n        buffer.ptr,\n        buffer.len,\n        c.SPNG_FMT_PNG,\n        c.SPNG_ENCODE_FINALIZE\n    );\n    if (encode_status != 0) {\n        return error.CouldNotEncodeImage;\n    }\n    if (c.fclose(file_descriptor) != 0) {\n        return error.CouldNotCloseFileDescriptor;\n    }\n}\n\ntry save_png(&image_header, buffer[0..]);\n\nAfter we execute this save_png() function, we should have a new PNG file inside our CWD, named pedro_pascal_filter.png. If we open this PNG file, we will see the same image exposed in Figure 15.2.",
     "crumbs": [
       "<span class='chapter-number'>15</span>  <span class='chapter-title'>Project 4 - Developing an image filter</span>"
     ]
@@ -1284,7 +1284,7 @@
     "href": "Chapters/14-threads.html",
     "title": "16  Introducing threads and parallelism in Zig",
     "section": "",
-    "text": "16.1 What are threads?\nA thread is basically a separate context of execution. We use threads to introduce parallelism into our program, which in most cases, makes the program run faster, because we have multiple tasks being performed at the same time, parallel to each other.\nPrograms are normally single-threaded by default. Which means that each program usually runs on a single thread, or, a single context of execution. When we have only one thread running, we have no parallelism. And when we don’t have parallelism, the commands are executed sequentially, that is, only one command is executed at a time, one after another. By creating multiple threads inside our program, we start to execute multiple commands at the same time.\nPrograms that create multiple threads are very common on the wild. Because many different types of applications are well suited for parallelism. Good examples are video and photo-editing applications (e.g. Adobe Photoshop or DaVinci Resolve), games (e.g. The Witcher 3), and also web browsers (e.g. Google Chrome, Firefox, Microsoft Edge, etc). For example, in web browsers, threads are normally used to implement tabs. The tabs in a web browsers usually run as separate threads in the main process of the web browser. That is, each new tab that you open in your web browser, usually runs on a separate thread of execution.\nBy running each tab in a separate thread, we allow all open tabs in the browser to run at the same time, and independently from each other. For example, you might have YouTube, or Spotify, currently opened in a tab, and you are listening to some podcast in that tab, while, at the same time, you are working in another tab, writing an essay on Google Docs. Even if you are not looking into the YouTube tab, you can still hear the podcast only because this YouTube tab is running in parallel with the other tab where Google Docs is running.\nWithout threads, the other alternative would be to run each tab as a completely separate process in your computer. But that would be a bad choice, because just a few tabs would already consume too much power and resources from your computer. In other words, is very expensive to create a completely new process, compared to creating a new thread of execution. Also, the chances of you experiencing lag and overhead while using the browser would be significant. Threads are faster to create, and they also consume much, much less resources from the computer, especially because they share some resources with the main process.\nTherefore, is the use of threads in modern web browsers that allows you to hear the podcast at the same time while you are writing something on Google Docs. Without threads, a web browser would probably be limited to just one single tab.\nThreads are also well-suited for anything that involves serving requests or orders. Because serving a request takes time, and usually involves a lot of “waiting time”. In other words, we spend a lot of time in idle, waiting for something to complete. For example, consider a restaurant. Serving orders in a restaurant usually involves the following steps:\nIf you think about the bullet points above, you will notice that one big moment of waiting time is present in this whole process, which is while the food is being cooked inside the kitchen. While the food is being prepped, both the waiter and the client itself are waiting for the food to be ready and delivered.\nIf we write a program to represent this restaurant, more specifically, a single-threaded program, then, this program would be very inefficient. Because the program would stay in idle, waiting for a considerable amount of time on the “check if food is ready” step. Consider the code snippet exposed below that could potentially represent such program.\nThe problem with this program is the while loop. This program will spend a lot of time waiting on the while loop, doing nothing more than just checking if the food is ready. This is a waste of time. Instead of waiting for something to happen, the waiter could just send the order to the kitchen, and just move on, and continue with receiving more orders from other clients, and sending more orders to the kitchen, instead of doing nothing and waiting for the food to be ready.\nconst order = Order.init(\"Pizza Margherita\", n = 1);\nconst waiter = Waiter.init();\nwaiter.receive_order(order);\nwaiter.ask_kitchen_to_cook();\nvar food_not_ready = true;\nwhile (food_not_ready) {\n    food_not_ready = waiter.is_food_ready();\n}\nconst food = waiter.get_food_from_kitchen();\nwaiter.send_food_to_client(food);\nThis is why threads would be a great fit for this program. We could use threads to free the waiters from their “waiting duties”, so they can go on with their other tasks, and receive more orders. Take a look at the next example, where I have re-written the above program into a different program that uses threads to cook and deliver the orders.\nYou can see in this program that when a waiter receives a new order from a client, this waiter executes the send_order() function. The only thing that this function does is to create a new thread and detaches it. Since creating a thread is a very fast operation, this send_order() function returns almost immediately, so the waiter spends almost no time worrying about the order, and just move on and tries to get the next order from the clients.\nInside the new thread created, the order get’s cooked by a chef, and when the food is ready, it is delivered to the client’s table.\nfn cook_and_deliver_order(order: *Order) void {\n    const chef = Chef.init();\n    const food = chef.cook(order.*);\n    chef.deliver_food(food);\n}\nfn send_order(order: Order) void {\n    const cook_thread = Thread.spawn(\n        .{}, cook_and_deliver_order, .{&order}\n    );\n    cook_thread.detach();\n}\n\nconst waiter = Waiter.init();\nwhile (true) {\n    const order = waiter.get_new_order();\n    if (order) {\n        send_order(order);\n    }\n}",
+    "text": "16.1 What are threads?\nA thread is basically a separate context of execution. We use threads to introduce parallelism into our program, which in most cases, makes the program run faster, because we have multiple tasks being performed at the same time, parallel to each other.\nPrograms are normally single-threaded by default. Which means that each program usually runs on a single thread, or, a single context of execution. When we have only one thread running, we have no parallelism. And when we don’t have parallelism, the commands are executed sequentially, that is, only one command is executed at a time, one after another. By creating multiple threads inside our program, we start to execute multiple commands at the same time.\nPrograms that create multiple threads are very common in the wild. Because many different types of applications are well suited for parallelism. Good examples are video and photo-editing applications (e.g. Adobe Photoshop or DaVinci Resolve), games (e.g. The Witcher 3), and also web browsers (e.g. Google Chrome, Firefox, Microsoft Edge, etc). For example, in web browsers, threads are normally used to implement tabs. The tabs in a web browsers usually run as separate threads in the main process of the web browser. That is, each new tab that you open in your web browser usually runs on a separate thread of execution.\nBy running each tab in a separate thread, we allow all open tabs in the browser to run at the same time, and independently from each other. For example, you might have YouTube or Spotify currently open in a tab, and you are listening to some podcast in that tab while at the same time working in another tab, writing an essay on Google Docs. Even if you are not looking into the YouTube tab, you can still hear the podcast only because this YouTube tab is running in parallel with the other tab where Google Docs is running.\nWithout threads, the other alternative would be to run each tab as a completely separate process in your computer. But that would be a bad choice because just a few tabs would already consume too much power and resources from your computer. In other words, it’s very expensive to create a completely new process, compared to creating a new thread of execution. Also, the chances of you experiencing lag and overhead while using the browser would be significant. Threads are faster to create, and they also consume much, much less resources from the computer, especially because they share some resources with the main process.\nTherefore, it’s the use of threads in modern web browsers that allow you to hear the podcast at the same time while you are writing something on Google Docs. Without threads, a web browser would probably be limited to just one single tab.\nThreads are also well-suited for anything that involves serving requests or orders. Because serving a request takes time, and usually involves a lot of “waiting time”. In other words, we spend a lot of time in idle, waiting for something to complete. For example, consider a restaurant. Serving orders in a restaurant usually involves the following steps:\nIf you think about the bullet points above, you will notice that one big moment of waiting time is present in this whole process, which is while the food is being cooked inside the kitchen. While the food is being prepped, both the waiter and the client themselves are waiting for the food to be ready and delivered.\nIf we write a program to represent this restaurant, more specifically, a single-threaded program, then this program would be very inefficient. Because the program would stay in idle, waiting for a considerable amount of time on the “check if food is ready” step. Consider the code snippet exposed below that could potentially represent such program.\nThe problem with this program is the while loop. This program will spend a lot of time waiting on the while loop, doing nothing more than just checking if the food is ready. This is a waste of time. Instead of waiting for something to happen, the waiter could just send the order to the kitchen, and just move on, and continue with receiving more orders from other clients, and sending more orders to the kitchen, instead of doing nothing and waiting for the food to be ready.\nconst order = Order.init(\"Pizza Margherita\", n = 1);\nconst waiter = Waiter.init();\nwaiter.receive_order(order);\nwaiter.ask_kitchen_to_cook();\nvar food_not_ready = true;\nwhile (food_not_ready) {\n    food_not_ready = waiter.is_food_ready();\n}\nconst food = waiter.get_food_from_kitchen();\nwaiter.send_food_to_client(food);\nThis is why threads would be a great fit for this program. We could use threads to free the waiters from their “waiting duties”, so they can go on with their other tasks, and receive more orders. Take a look at the next example, where I have re-written the above program into a different program that uses threads to cook and deliver the orders.\nYou can see in this program that when a waiter receives a new order from a client, this waiter executes the send_order() function. The only thing that this function does is to create a new thread and detaches it. Since creating a thread is a very fast operation, this send_order() function returns almost immediately, so the waiter spends almost no time worrying about the order, and just move on and tries to get the next order from the clients.\nInside the new thread created, the order gets cooked by a chef, and when the food is ready, it’s delivered to the client’s table.\nfn cook_and_deliver_order(order: *Order) void {\n    const chef = Chef.init();\n    const food = chef.cook(order.*);\n    chef.deliver_food(food);\n}\nfn send_order(order: Order) void {\n    const cook_thread = Thread.spawn(\n        .{}, cook_and_deliver_order, .{&order}\n    );\n    cook_thread.detach();\n}\n\nconst waiter = Waiter.init();\nwhile (true) {\n    const order = waiter.get_new_order();\n    if (order) {\n        send_order(order);\n    }\n}",
     "crumbs": [
       "<span class='chapter-number'>16</span>  <span class='chapter-title'>Introducing threads and parallelism in Zig</span>"
     ]
@@ -1304,7 +1304,7 @@
     "href": "Chapters/14-threads.html#threads-versus-processes",
     "title": "16  Introducing threads and parallelism in Zig",
     "section": "16.2 Threads versus processes",
-    "text": "16.2 Threads versus processes\nWhen we run a program, this program is executed as a process in the operating system. This is a one to one relationship, each program or application that you execute is a separate process in the operating system. But each program, or each process, can create and contain multiple threads inside of it. Therefore, processes and threads have a one to many relationship.\nThis also means that every thread that we create is always associated with a particular process in our computer. In other words, a thread is always a subset (or a children) of an existing process. All threads share some of the resources associated with the process from which they were created. And because threads share resources with the process, they are very good for making communication between tasks easier.\nFor example, suppose that you were developing a big and complex application that would be much simpler if you could split it in two, and make these two separate pieces talk with each other. Some programmers opt to effectively write these two pieces of the codebase as two completely separate programs, and then, they use IPC (inter-process communication) to make these two separate programs/processes talk to each other, and make them work together.\nHowever, some programmers find IPC hard to deal with, and, as consequence, they prefer to write one piece of the codebase as the “main part of the program”, or, as the part of the code that runs as the process in the operating system, while the other piece of the codebase is written as a task to be executed in a new thread. A process and a thread can easily comunicate with each other through both control flow, and also, through data, because they share and have access to the same standard file descriptors (stdout, stdin, stderr), and also to the same memory space on the heap and global data section.\nIn more details, each thread that you create have a separate stack frame reserved just for that thread, which essentially means that each local object that you create inside this thread, is local to that thread, i.e. the other threads cannot see this local object. Unless this object that you have created is an object that lives on the heap. In other words, if the memory associated with this object is on the heap, then, the other threads can potentially access this object.\nTherefore, objects that are stored in the stack are local to the thread where they were created. But objects that are stored on the heap are potentially accessible to other threads. All of this means that, each thread have its own separate stack frame, but, at the same time, all threads share the same heap, the same standard file descriptors (which means that they share the same stdout, stdin, stderr), and the same global data section in the program.",
+    "text": "16.2 Threads versus processes\nWhen we run a program, this program is executed as a process in the operating system. This is a one to one relationship, each program or application that you execute is a separate process in the operating system. But each program, or each process, can create and contain multiple threads inside of it. Therefore, processes and threads have a one to many relationship.\nThis also means that every thread that we create is always associated with a particular process in our computer. In other words, a thread is always a subset (or a children) of an existing process. All threads share some of the resources associated with the process from which they were created. And because threads share resources with the process, they are very good for making communication between tasks easier.\nFor example, suppose that you were developing a big and complex application that would be much simpler if you could split it in two, and make these two separate pieces talk with each other. Some programmers opt to effectively write these two pieces of the codebase as two completely separate programs, and then, they use IPC (inter-process communication) to make these two separate programs/processes talk to each other, and make them work together.\nHowever, some programmers find IPC hard to deal with, and, as consequence, they prefer to write one piece of the codebase as the “main part of the program”, or, as the part of the code that runs as the process in the operating system, while the other piece of the codebase is written as a task to be executed in a new thread. A process and a thread can easily comunicate with each other through both control flow, and also, through data, because they share and have access to the same standard file descriptors (stdout, stdin, stderr), and also to the same memory space on the heap and global data section.\nIn more details, each thread that you create have a separate stack frame reserved just for that thread, which essentially means that each local object that you create inside this thread, is local to that thread, i.e., the other threads cannot see this local object. Unless this object that you have created is an object that lives on the heap. In other words, if the memory associated with this object is on the heap, then, the other threads can potentially access this object.\nTherefore, objects that are stored in the stack are local to the thread where they were created. But objects that are stored on the heap are potentially accessible to other threads. All of this means that, each thread has its own separate stack frame, but, at the same time, all threads share the same heap, the same standard file descriptors (which means that they share the same stdout, stdin, stderr), and the same global data section in the program.",
     "crumbs": [
       "<span class='chapter-number'>16</span>  <span class='chapter-title'>Introducing threads and parallelism in Zig</span>"
     ]
@@ -1314,7 +1314,7 @@
     "href": "Chapters/14-threads.html#creating-a-thread",
     "title": "16  Introducing threads and parallelism in Zig",
     "section": "16.3 Creating a thread",
-    "text": "16.3 Creating a thread\nWe create new threads in Zig, by first, importing the Thread struct into our current Zig module, and then, calling the spawn() method of this struct, which creates (or, “spawns”) a new thread of execution from our current process. This method have three arguments, which are, respectively:\n\na SpawnConfig object, which contains configurations for the spawn process.\nthe name of the function that is going to be executed (or, that is going to be “called”) inside this new thread.\na list of arguments (or inputs) to be passed to the function provided in the second argument.\n\nWith these three arguments, you can control how the thread get’s created, and also, specify which work (or “tasks”) will be performed inside this new thread. A thread is just a separate context of execution, and we usually create new threads in our code, because we want to perform some work inside this new context of execution. And we specify which exact work, or, which exact steps that are going to be performed inside this context, by providing the name of a function on the second argument of the spawn() method.\nThus, when this new thread get’s created, this function that you provided as input to the spawn() method get’s called, or, get’s executed inside this new thread. You can control the arguments, or, the inputs that are passed to this function when it get’s called, by providing a list of arguments (or a list of inputs) on the third argument of the spawn() method. These arguments are passed to the function in the same order that they are provided to spawn().\nFurthermore, the SpawnConfig is a struct object with only two possible fields, or, two possible members, that you can set to tailor the spawn behaviour. These fields are:\n\nstack_size: you can provide an usize value to specify the size (in bytes) of the thread’s stack frame. By default, this value is: \\(16 \\times 1024 \\times 1024\\).\nallocator: you can provide an allocator object to be used when allocating memory for the thread.\n\nTo use one of these two fields (or, “configs”) you just have to create a new object of type SpawnConfig, and provide this object as input to the spawn() method. But, if you are not interested in using one of these configs, and you are ok with using just the defaults, you can just provide an anonymous struct literal (.{}) in the place of this SpawnConfig argument.\nAs our first, and very simple example, consider the code exposed below. Inside the same program, you can create multiple threads of execution if you want to. But, in this first example, we are creating just a single thread of execution, because we call spawn() only once.\nAlso, notice in this example that we are executing the function do_some_work() inside the new thread. Since this function receives no inputs, because it has no arguments, we have passed an empty list in this instance, or, more precisely, an empty and anonymous struct (.{}) in the third argument of spawn().\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Thread = std.Thread;\nfn do_some_work() !void {\n    _ = try stdout.write(\"Starting the work.\\n\");\n    std.time.sleep(100 * std.time.ns_per_ms);\n    _ = try stdout.write(\"Finishing the work.\\n\");\n}\n\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, do_some_work, .{});\n    thread.join();\n}\n\nStarting the work.Finishing the work.\n\n\nNotice the use of try when calling the spawn() method. This means that this method can return an error in some circumstances. One circumstance in particular is when you attempt to create a new thread, when you have already created too much (i.e. you have exceeded the quota of concurrent threads in your system).\nBut, if the new thread is successfully created, the spawn() method returns a handler object (which is just an object of type Thread) to this new thread. You can use this handler object to effectively control all aspects of the thread.\nWhen the thread get’s created, the function that you provided as input to spawn() get’s invoked (i.e. get’s called) to start the execution on this new thread. In other words, everytime you call spawn(), not only a new thread get’s created, but also, the “start work button” of this thread get’s automatically pressed. So the work being performed in this thread starts at the moment that the thread is created. This is similar to how pthread_create() from the pthreads library in C works, which also starts the execution at the moment that the thread get’s created.",
+    "text": "16.3 Creating a thread\nWe create new threads in Zig by first importing the Thread struct into our current Zig module and then calling the spawn() method of this struct, which creates (or “spawns”) a new thread of execution from our current process. This method has three arguments, which are, respectively:\n\na SpawnConfig object, which contains configurations for the spawn process.\nthe name of the function that is going to be executed (or that is going to be “called”) inside this new thread.\na list of arguments (or inputs) to be passed to the function provided in the second argument.\n\nWith these three arguments, you can control how the thread gets created, and also, specify which work (or “tasks”) will be performed inside this new thread. A thread is just a separate context of execution, and we usually create new threads in our code because we want to perform some work inside this new context of execution. And we specify which exact work, or which exact steps that are going to be performed inside this context by providing the name of a function as the second argument of the spawn() method.\nThus, when this new thread gets created, this function that you provided as input to the spawn() method gets called, or gets executed inside this new thread. You can control the arguments, or the inputs that are passed to this function when it gets called by providing a list of arguments (or a list of inputs) in the third argument of the spawn() method. These arguments are passed to the function in the same order that they are provided to spawn().\nFurthermore, the SpawnConfig is a struct object with only two possible fields, or, two possible members, that you can set to tailor the spawn behaviour. These fields are:\n\nstack_size: you can provide a usize value to specify the size (in bytes) of the thread’s stack frame. By default, this value is: \\(16 \\times 1024 \\times 1024\\).\nallocator: you can provide an allocator object to be used when allocating memory for the thread.\n\nTo use one of these two fields (or “configs”), you just have to create a new object of type SpawnConfig, and provide this object as input to the spawn() method. But, if you are not interested in using one of these configs, and you are ok with using just the defaults, you can just provide an anonymous struct literal (.{}) in place of this SpawnConfig argument.\nAs our first, and very simple example, consider the code exposed below. Inside the same program, you can create multiple threads of execution if you want to. But, in this first example, we are creating just a single thread of execution, because we call spawn() only once.\nAlso, notice in this example that we are executing the function do_some_work() inside the new thread. Since this function receives no inputs, because it has no arguments, we have passed an empty list in this instance, or more precisely, an empty, anonymous struct (.{}) in the third argument of spawn().\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Thread = std.Thread;\nfn do_some_work() !void {\n    _ = try stdout.write(\"Starting the work.\\n\");\n    std.time.sleep(100 * std.time.ns_per_ms);\n    _ = try stdout.write(\"Finishing the work.\\n\");\n}\n\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, do_some_work, .{});\n    thread.join();\n}\n\nStarting the work.Finishing the work.\n\n\nNotice the use of try when calling the spawn() method. This means that this method can return an error in some circumstances. One circumstance in particular is when you attempt to create a new thread, when you have already created too much (i.e., you have exceeded the quota of concurrent threads in your system).\nBut, if the new thread is successfully created, the spawn() method returns a handler object (which is just an object of type Thread) to this new thread. You can use this handler object to effectively control all aspects of the thread.\nWhen the thread gets created, the function that you provided as input to spawn() gets invoked (i.e., gets called) to start the execution on this new thread. In other words, every time you call spawn(), not only is a new thread created, but the “start work button” of this thread is also automatically pressed. So the work being performed in this thread starts as soon as the thread is created. This is similar to how pthread_create() from the pthreads library in C works, which also starts the execution as soon as the thread is created.",
     "crumbs": [
       "<span class='chapter-number'>16</span>  <span class='chapter-title'>Introducing threads and parallelism in Zig</span>"
     ]
@@ -1324,7 +1324,7 @@
     "href": "Chapters/14-threads.html#returning-from-a-thread",
     "title": "16  Introducing threads and parallelism in Zig",
     "section": "16.4 Returning from a thread",
-    "text": "16.4 Returning from a thread\nWe have learned on the previous section that the execution of the thread starts at the moment that the thread get’s created. Now, we will learn how to “join” or “detach” a thread in Zig. “Join” and “detach” are operations that control how the thread returns to the main thread, or, to the main process in our program.\nWe perform these operations by using the methods join() and detach() from the thread handler object. Every thread that you create can be marked as either joinable or detached (Linux man-pages 2024). You can turn a thread into a detached thread by calling the detach() method from the thread handler object. But if you call the join() method instead, then, this thread becomes a joinable thread.\nA thread cannot be both joinable and detached. Which in general means that you cannot call both join() and detach() on the same thread. But a thread must be one of the two, meaning that, you should always call either join() or detach() over a thread. If you don’t call one of these two methods over your thread, you introduce undefined behaviour into your program, which is described at Section 16.9.2.\nNow, let’s describe what each of these two methods do to your thread.\n\n16.4.1 Joining a thread\nWhen you join a thread, you are essentially saying: “Hey! Could you please wait for the thread to finish, before you continue with your execution?”. For example, if we comeback to our first and simpliest example of a thread in Zig, in that example we have created a single thread inside the main() function of our program, and just called join() over this thread at the end. This section of the code example is reproduced below.\nBecause we are joining this new thread inside the main()’s scope, it means that the execution of the main() function is temporarily stopped, to wait for the execution of the thread to finish. That is, the execution of main() stops temporarily at the line where join() get’s called, and it will continue only after the thread has finished its tasks.\n\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, do_some_work, .{});\n    thread.join();\n}\n\nBecause we have joined this new thread inside the main() scope, we have a guarantee that this new thread will finish before the end of the execution of main(). Because it is guaranteed that main() will wait for the thread to finish its tasks.\nIn the example above, there are no more expressions after the join() call. We just have the end of the main()’s scope, and, therefore, the execution of our program just ends after the thread finishes its tasks, since there is nothing more to do. But what if we had more stuff to do after the join call?\nTo demonstrate this other possibility, consider the next example exposed below. Here, we create a print_id() function, that just receives an id as input, and prints it to stdout. In this example, we are creating two new threads, one after another. Then, we join the first thread, then, we wait for two whole seconds, then, at last, we join the second thread.\nThe idea behind this example is that the last join() call is executed only after the first thread finishes its task (i.e. the first join() call), and also, after the two seconds of delay. If you compile and run this example, you will notice that most messages are quickly printed to stdout, i.e. they appear almost instantly on your screen. However, the last message (“Joining thread 2”) takes around 2 seconds to appear in the screen.\n\nfn print_id(id: *const u8) !void {\n    try stdout.print(\"Thread ID: {d}\\n\", .{id.*});\n}\n\npub fn main() !void {\n    const id1: u8 = 1;\n    const id2: u8 = 2;\n    const thread1 = try Thread.spawn(.{}, print_id, .{&id1});\n    const thread2 = try Thread.spawn(.{}, print_id, .{&id2});\n\n    _ = try stdout.write(\"Joining thread 1\\n\");\n    thread1.join();\n    std.time.sleep(2 * std.time.ns_per_s);\n    _ = try stdout.write(\"Joining thread 2\\n\");\n    thread2.join();\n}\n\nThread ID: Joining thread 1\n1\nThread ID: 2\nJoining thread 2\nThis demonstrates that both threads finish their work (i.e. printing the IDs) very fast, before the two seconds of delay end. Because of that, the last join() call returns pretty much instantly. Because when this last join() call happens, the second thread have already finished its task.\nNow, if you compile and run this example, you will also notice that, in some cases, the messages intertwine with each other. In other words, you might see the message “Joining thread 1” inserted in the middle of the message “Thread 1”, or vice-versa. This happens because:\n\nthe threads are executing basically at the same time as the main process of the program (i.e. the main() function).\nthe threads share the same stdout from the main process of the program, which means that the messages that the threads produce are sent to exact same place as the messages produced by the main process.\n\nBoth of these points were described previously at Section 16.1. So the messages might get intertwined because they are being produced and sent to the same stdout roughly at the same time. Anyway, when you call join() over a thread, the current process will wait for the thread to finish before it continues, and, when the thread does finishes its task, the resources associated with this thread are automatically freed, and, the current process continues with its execution.\n\n\n16.4.2 Detaching a thread\nWhen you detach a thread, the resources associated with this thread are automatically released back to the system, without the need for another thread to join with this terminated thread.\nIn other words, when you call detach() over a thread it’s like when your children becomes adults, i.e. they become independent from you. A detached thread frees itself, and when this thread finishes its tasks, it does not report the results back to you. Thus, you normally mark a thread as detached when you don’t need to use the return value of the thread, or, when you don’t care about when exactly the thread finishes its job, i.e. the thread solves everything by itself.\nTake the code example below. We create a new thread, detach it, and then, we just print a final message before we end our program. We use the same print_id() function that we have used over the previous examples.\n\nfn print_id(id: *const u8) !void {\n    try stdout.print(\"Thread ID: {d}\\n\", .{id.*});\n}\n\npub fn main() !void {\n    const id1: u8 = 1;\n    const thread1 = try Thread.spawn(.{}, print_id, .{&id1});\n    thread1.detach();\n    _ = try stdout.write(\"Finish main\\n\");\n}\n\nFinish main\nNow, if you look closely at the output of this code example, you will notice that only the final message in main was printed to the console. The message that was supposed to be printed by print_id() did not appear in the console. Why? Is because the main process of our program has finished first, before the thread was able to say anything.\nAnd that is perfectly ok behaviour, because the thread was detached, so, it was able to free itself, without the need to wait for the main process. If you ask main to sleep (or “wait”) for some extra nanoseconds, before it ends, you will likely see the message printed by print_id(), because you give enough time for the thread to finish before the main process ends.",
+    "text": "16.4 Returning from a thread\nWe have learned in the previous section that the execution of the thread starts as soon as the thread is created. Now, we will learn how to “join” or “detach” a thread in Zig. “Join” and “detach” are operations that control how the thread returns to the main thread, or to the main process in our program.\nWe perform these operations by using the methods join() and detach() from the thread handler object. Every thread that you create can be marked as either joinable or detached (Linux man-pages 2024). You can turn a thread into a detached thread by calling the detach() method from the thread handler object. But if you call the join() method instead, then this thread becomes a joinable thread.\nA thread cannot be both joinable and detached. Which in general means that you cannot call both join() and detach() on the same thread. But a thread must be one of the two, meaning that, you should always call either join() or detach() over a thread. If you don’t call one of these two methods over your thread, you introduce undefined behaviour into your program, which is described in Section 16.9.2.\nNow, let’s describe what each of these two methods do to your thread.\n\n16.4.1 Joining a thread\nWhen you join a thread, you are essentially saying: “Hey! Could you please wait for the thread to finish, before you continue with your execution?”. For example, if we come back to our first and simplest example of a thread in Zig, we created a single thread inside the main() function of our program and just called join() on this thread at the end. This section of the code example is reproduced below.\nBecause we are joining this new thread inside the main()’s scope, it means that the execution of the main() function is temporarily stopped, to wait for the execution of the thread to finish. That is, the execution of main() stops temporarily at the line where join() gets called, and it will continue only after the thread has finished its tasks.\n\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, do_some_work, .{});\n    thread.join();\n}\n\nBecause we have joined this new thread inside the main() scope, we have a guarantee that this new thread will finish before the end of the execution of main(). Because it’s guaranteed that main() will wait for the thread to finish its tasks.\nIn the example above, there are no more expressions after the join() call. We just have the end of the main()’s scope, and, therefore, the execution of our program just ends after the thread finishes its tasks, since there is nothing more to do. But what if we had more stuff to do after the join call?\nTo demonstrate this other possibility, consider the next example exposed below. Here, we create a print_id() function, that just receives an id as input, and prints it to stdout. In this example, we are creating two new threads, one after another. Then, we join the first thread, then, we wait for two whole seconds, then, at last, we join the second thread.\nThe idea behind this example is that the last join() call is executed only after the first thread finishes its task (i.e., the first join() call), and the two-second delay. If you compile and run this example, you will notice that most messages are quickly printed to stdout, i.e., they appear almost instantly on your screen. However, the last message (“Joining thread 2”) takes around 2 seconds to appear on the screen.\n\nfn print_id(id: *const u8) !void {\n    try stdout.print(\"Thread ID: {d}\\n\", .{id.*});\n}\n\npub fn main() !void {\n    const id1: u8 = 1;\n    const id2: u8 = 2;\n    const thread1 = try Thread.spawn(.{}, print_id, .{&id1});\n    const thread2 = try Thread.spawn(.{}, print_id, .{&id2});\n\n    _ = try stdout.write(\"Joining thread 1\\n\");\n    thread1.join();\n    std.time.sleep(2 * std.time.ns_per_s);\n    _ = try stdout.write(\"Joining thread 2\\n\");\n    thread2.join();\n}\n\nThread ID: Joining thread 1\n1\nThread ID: 2\nJoining thread 2\nThis demonstrates that both threads finish their work (i.e., printing the IDs) very fast, before the two seconds of delay end. Because of that, the last join() call returns pretty much instantly. Because when this last join() call happens, the second thread has already finished its task.\nNow, if you compile and run this example, you will also notice that, in some cases, the messages intertwine with each other. In other words, you might see the message “Joining thread 1” inserted in the middle of the message “Thread 1”, or vice-versa. This happens because:\n\nthe threads are executing basically at the same time as the main process of the program (i.e., the main() function).\nthe threads share the same stdout from the main process of the program, which means that the messages that the threads produce are sent to exact same place as the messages produced by the main process.\n\nBoth of these points were described previously in Section 16.1. So the messages might get intertwined because they are being produced and sent to the same stdout roughly at the same time. Anyway, when you call join() over a thread, the current process will wait for the thread to finish before it continues, and, when the thread finishes its task, the resources associated with this thread are automatically freed, and the current process continues with its execution.\n\n\n16.4.2 Detaching a thread\nWhen you detach a thread, the resources associated with this thread are automatically released back to the system, without the need for another thread to join with this terminated thread.\nIn other words, when you call detach() on a thread it’s like when your children become adults, i.e., they become independent from you. A detached thread frees itself, and when this thread finishes its tasks, it does not report the results back to you. Thus, you normally mark a thread as detached when you don’t need to use the return value of the thread, or when you don’t care about when exactly the thread finishes its job, i.e., the thread solves everything by itself.\nTake the code example below. We create a new thread, detach it, and then, we just print a final message before we end our program. We use the same print_id() function that we have used over the previous examples.\n\nfn print_id(id: *const u8) !void {\n    try stdout.print(\"Thread ID: {d}\\n\", .{id.*});\n}\n\npub fn main() !void {\n    const id1: u8 = 1;\n    const thread1 = try Thread.spawn(.{}, print_id, .{&id1});\n    thread1.detach();\n    _ = try stdout.write(\"Finish main\\n\");\n}\n\nFinish main\nNow, if you look closely at the output of this code example, you will notice that only the final message in main was printed to the console. The message that was supposed to be printed by print_id() did not appear in the console. Why? It’s because the main process of our program has finished first, before the thread was able to say anything.\nAnd that is perfectly ok behaviour, because the thread was detached, so it was able to free itself, without the need to wait for the main process. If you ask main to sleep (or “wait”) for some extra nanoseconds, before it ends, you will likely see the message printed by print_id(), because you give enough time for the thread to finish before the main process ends.",
     "crumbs": [
       "<span class='chapter-number'>16</span>  <span class='chapter-title'>Introducing threads and parallelism in Zig</span>"
     ]
@@ -1334,7 +1334,7 @@
     "href": "Chapters/14-threads.html#thread-pools",
     "title": "16  Introducing threads and parallelism in Zig",
     "section": "16.5 Thread pools",
-    "text": "16.5 Thread pools\nThread pools is a very popular programming pattern, which is used especially on servers and daemons processes. A thread pool is just a set of threads, or, a “pool” of threads. Many programmers like to use this pattern, because it makes easier to manage and use multiple threads in your program, instead of manually creating the threads when you need them.\nAlso, using thread pools might increase performance as well in your program, especially if your program is constantly creating threads to perform short-lived tasks. In such instance, a thread pool might cause an increase in performance because you do not have be constantly creating and destroying threads all the time, so you don’t face a lot of the overhead involved in this constant process of creating and destroying threads.\nThe main idea behind a thread pool is to have a set of threads already created and ready to perform tasks at all times. You create a set of threads at the moment that your program starts, and keep these threads alive while your program runs. Each of these threads will be either performing a task, or, waiting for a task to be assigned. Every time a new task emerges in your program, this task is added to a “queue of tasks”, and the moment that a thread becomes available and ready to perform a new task, this thread takes the next task from the “queue of tasks”, and it simply performs the task.\nThe Zig Standard Library offers a thread pool implementation on the std.Thread.Pool struct. You create a new instance of a Pool object by providing a Pool.Options object as input to the init() method of this struct. A Pool.Options object, is a struct object that contains configurations for the pool of threads. The most important settings in this struct object are the members n_jobs and allocator. As the name suggests, the member allocator should receive an allocator object, while the member n_jobs specifies the number of threads to be created and maintained in this pool.\nConsider the example exposed below, that demonstrates how can we create a new thread pool object. Here, we create a Pool.Options object that contains a general purpose allocator object, and also, the n_jobs member was set to 4, which means that the thread pool will create and use 4 threads.\nAlso notice that the pool object was initially set to undefined. This allow us to initially declare the thread pool object, but not properly instantiate the underlying memory of the object. You have to initially declare your thread pool object by using undefined like this, because the init() method of Pool needs to have an initial pointer to properly instantiate the object.\nSo, just remember to create your thread pool object by using undefined, and then, after that, you call the init() method over the object. You should also not forget to call the deinit() method over the thread pool object, once you are done with it, to release the resources allocated for the thread pool. Otherwise, you will have a memory leak in your program.\n\nconst std = @import(\"std\");\nconst Pool = std.Thread.Pool;\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const opt = Pool.Options{\n        .n_jobs = 4,\n        .allocator = allocator,\n    };\n    var pool: Pool = undefined;\n    _ = try pool.init(opt);\n    defer pool.deinit();\n}\n\nNow that we know how to create Pool objects, we have to understand how to assign tasks to be executed by the threads in this pool object. To assign a task to be performed by a thread, we need to call the spawn() method from the thread pool object.\nThis spawn() method works identical to the spawn() method from the Thread object. The method have almost the same arguments as the previous one, more precisely, we don’t have to provide a SpawnConfig object in this case. But instead of creating a new thread, this spawn() method from the thread pool object just register a new task in the internal “queue of tasks” to be performed, and any available thread in the pool will get this task, and it will simply perform the task.\nIn the example below, we are using our previous print_id() function once again. But you may notice that the print_id() function is a little different this time, because now we are using catch instead of try in the print() call. Currently, the Pool struct only supports functions that don’t return errors as tasks. Thus, when assigning tasks to threads in a thread pool, is essential to use functions that don’t return errors. That is why we are using catch here, so that the print_id() function don’t return an error.\n\nfn print_id(id: *const u8) void {\n    _ = stdout.print(\"Thread ID: {d}\\n\", .{id.*})\n        catch void;\n}\nconst id1: u8 = 1;\nconst id2: u8 = 2;\ntry pool.spawn(print_id, .{&id1});\ntry pool.spawn(print_id, .{&id2});\n\nThis limitation should probably not exist, and, in fact, it is already on the radar of the Zig team to fix this issue, and it is being tracked on an open issue1. So, if you do need to provide a function that might return an error as the task to be performed by the threads in the thread pool, then, you are either limited to:\n\nimplementing your own thread pool that does not have this limitation.\nwait for the Zig team to actually fix this issue.",
+    "text": "16.5 Thread pools\nThread pools is a very popular programming pattern, which is used especially on servers and daemons processes. A thread pool is just a set of threads, or a “pool” of threads. Many programmers like to use this pattern because it makes it easier to manage and use multiple threads in your program, instead of manually creating the threads when you need them.\nAlso, using thread pools might increase performance as well in your program, especially if your program is constantly creating threads to perform short-lived tasks. In such instance, a thread pool might cause an increase in performance because you do not have be constantly creating and destroying threads all the time, so you don’t face a lot of the overhead involved in this constant process of creating and destroying threads.\nThe main idea behind a thread pool is to have a set of threads already created and ready to perform tasks at all times. You create a set of threads at the moment that your program starts, and keep these threads alive while your program runs. Each of these threads will be either performing a task, or waiting for a task to be assigned. Every time a new task emerges in your program, this task is added to a “queue of tasks”, and the moment that a thread becomes available and ready to perform a new task, this thread takes the next task from the “queue of tasks”, and it simply performs the task.\nThe Zig Standard Library offers a thread pool implementation on the std.Thread.Pool struct. You create a new instance of a Pool object by providing a Pool.Options object as input to the init() method of this struct. A Pool.Options object, is a struct object that contains configurations for the pool of threads. The most important settings in this struct object are the members n_jobs and allocator. As the name suggests, the member allocator should receive an allocator object, while the member n_jobs specifies the number of threads to be created and maintained in this pool.\nConsider the example exposed below, that demonstrates how can we create a new thread pool object. Here, we create a Pool.Options object that contains a general purpose allocator object, and also, the n_jobs member was set to 4, which means that the thread pool will create and use 4 threads.\nAlso notice that the pool object was initially set to undefined. This allow us to initially declare the thread pool object, but not properly instantiate the underlying memory of the object. You have to initially declare your thread pool object by using undefined like this, because the init() method of Pool needs to have an initial pointer to properly instantiate the object.\nSo, just remember to create your thread pool object by using undefined, and then, after that, you call the init() method over the object. You should also not forget to call the deinit() method over the thread pool object, once you are done with it, to release the resources allocated for the thread pool. Otherwise, you will have a memory leak in your program.\n\nconst std = @import(\"std\");\nconst Pool = std.Thread.Pool;\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const opt = Pool.Options{\n        .n_jobs = 4,\n        .allocator = allocator,\n    };\n    var pool: Pool = undefined;\n    try pool.init(opt);\n    defer pool.deinit();\n}\n\nNow that we know how to create Pool objects, we have to understand how to assign tasks to be executed by the threads in this pool object. To assign a task to be performed by a thread, we need to call the spawn() method from the thread pool object.\nThis spawn() method works identical to the spawn() method from the Thread object. The method has almost the same arguments as the previous one, more precisely, we don’t have to provide a SpawnConfig object in this case. But instead of creating a new thread, this spawn() method from the thread pool object just registers a new task in the internal “queue of tasks” to be performed, and any available thread in the pool will get this task, and it will simply perform the task.\nIn the example below, we are using our previous print_id() function once again. But you may notice that the print_id() function is a little different this time, because now we are using catch instead of try in the print() call. Currently, the Pool struct only supports functions that don’t return errors as tasks. Thus, when assigning tasks to threads in a thread pool, it is essential to use functions that don’t return errors. That is why we are using catch here, so that the print_id() function don’t return an error.\n\nfn print_id(id: *const u8) void {\n    _ = stdout.print(\"Thread ID: {d}\\n\", .{id.*})\n        catch void;\n}\nconst id1: u8 = 1;\nconst id2: u8 = 2;\ntry pool.spawn(print_id, .{&id1});\ntry pool.spawn(print_id, .{&id2});\n\nThis limitation should probably not exist, and, in fact, it’s already on the radar of the Zig team to fix this issue, and it’s being tracked in an open issue1. So, if you do need to provide a function that might return an error as the task to be performed by the threads in the thread pool, then, you are either limited to:\n\nimplementing your own thread pool that does not have this limitation.\nwait for the Zig team to actually fix this issue.",
     "crumbs": [
       "<span class='chapter-number'>16</span>  <span class='chapter-title'>Introducing threads and parallelism in Zig</span>"
     ]
@@ -1344,7 +1344,7 @@
     "href": "Chapters/14-threads.html#mutexes",
     "title": "16  Introducing threads and parallelism in Zig",
     "section": "16.6 Mutexes",
-    "text": "16.6 Mutexes\nMutexes are a classic component of every thread library. In essence, a mutex is a Mutually Exclusive Flag, and this flag acts like a type of “lock”, or as a gate keeper to a particular section of your code. Mutexes are related to thread synchronization, more specifically, they prevent you from having some classic race conditions in your program, and, therefore, major bugs and undefined behaviour that are usually difficult to track and understand.\nThe main idea behind a mutex is to help us to control the execution of a particular section of the code, and to prevent two or more threads from executing this particular section of the code at the same time. Many programmers like to compare a mutex to a bathroom door (which usually have a lock). When a thread locks its own mutex object, it is like if the bathroom door was locked, and, therefore, the other people (in this case, the other threads) that wants to use the same bathroom at the same time have to be patient, and simply wait for the other person (or the other thread) to unlock the door and get out of the bathroom.\nSome other programmers also like to explain mutexes by using the analogy of “each person will have their turn to speak”. This is the analogy used on the Multithreading Code video from the Computerphile project2. Imagine if you are in a conversation circle. There is a moderator in this circle, which is the person that decides who have the right to speak at that particular moment. The moderator gives a green card (or some sort of an authorization card) to the person that is going to speak, and, as a result, everyone else must be silent and hear this person that has the green card. When the person finishes talking, it gives the green card back to the moderator, and the moderator decides who is going to talk next, and delivers the green card to that person. And the cycle goes on like this.\nA mutex acts like the moderator in this conversation circle. The mutex authorizes one single thread to execute a specific section of the code, and it also blocks the other threads from executing this same section of the code. If these other threads want to execute this same piece of the code, they are forced to wait for the the authorized thread to finish first. When the authorized thread finishes executing this code, the mutex authorizes the next thread to execute this code, and the other threads are still blocked. Therefore, a mutex is like a moderator that does a “each thread will have their turn to execute this section of the code” type of control.\nMutexes are especially used to prevent data race problems from happening. A data race problem happens when two or more threads are trying to read from or write to the same shared object at the same time. So, when you have an object that is shared will all threads, and, you want to avoid two or more threads from accessing this same object at the same time, you can use a mutex to lock the part of the code that access this specific object. When a thread tries to run this code that is locked by a mutex, this thread stops its execution, and patiently waits for this section of the codebase to be unlocked to continue.\nNotice that mutexes are normally used to lock areas of the codebase that access/modify data that is shared with all threads, i.e. objects that are either stored in the global data section, or, in the heap space of your program. So mutexes are not normally used on areas of the codebase that access/modify objects that are local to the thread.\n\n16.6.1 Critical section\nCritical section is a concept commonly associated with mutexes and thread synchronization. In essence, a critical section is the section of the program that a thread access/modify a shared resource (i.e. an object, a file descriptor, something that all threads have access to). In other words, a critical section is the section of the program where race conditions might happen, and, therefore, where undefined behaviour can be introduced into the program.\nWhen we use mutexes in our program, the critical section defines the area of the codebase that we want to lock. So we normally lock the mutex object at the beginning of the critical section, and then, we unlock it at the end of the critical section. The two bullet points exposed below comes from the “Critical Section” article from GeekFromGeeks, and they summarise well the role that a critical section plays in the thread synchronization problem (Geeks for Geeks 2024).\n\nThe critical section must be executed as an atomic operation, which means that once one thread or process has entered the critical section, all other threads or processes must wait until the executing thread or process exits the critical section. The purpose of synchronization mechanisms is to ensure that only one thread or process can execute the critical section at a time.\nThe concept of a critical section is central to synchronization in computer systems, as it is necessary to ensure that multiple threads or processes can execute concurrently without interfering with each other. Various synchronization mechanisms such as semaphores, mutexes, monitors, and condition variables are used to implement critical sections and ensure that shared resources are accessed in a mutually exclusive manner.\n\n\n\n16.6.2 Atomic operations\nYou will also see the term “atomic operation” a lot when reading about threads, race conditions and mutexes. In summary, an operation is categorized as “atomic”, when there is no way to happen a context switch in the middle of this operation. In other words, this operation is always done from beginning to end, without interruptions of another process or operation in the middle of its execution phase.\nNot many operations today are atomic. But why atomic operations matters here? Is because data races (which is a type of a race condition) cannot happen on operations that are atomic. So if a particular line in your code performs an atomic operation, then, this line will never suffer from a data race problem. Therefore, programmers sometimes use an atomic operation to protect themselves from data race problems in their code.\nWhen you have an operation that is compiled into just one single assembly instruction, this operation might be atomic, because it is just one assembly instruction. But this is not guaranteed. This is usually true for old CPU architectures (such as x86). But nowadays, most assembly instructions in modern CPU architectures turn into multiple micro-tasks, which inherently makes the operation not atomic anymore, even though it has just one single assembly instruction.\nThe Zig Standard Library offers some atomic functionality at the std.atomic module. In this module, you will find a public and generic function called Value(). With this function we create an “atomic object”, which is a value that contains some native atomic operations, most notably, a load() and a fetchAdd() operation. If you have experience with multithreading in C++, you probably have recognized this pattern. So yes, this generic “atomic object” in Zig is essentially identical to the template struct std::atomic from the C++ Standard Library. Is important to emphasize that only primitive data types (i.e. the types presented at Section 1.5) are supported by these atomic operations in Zig.\n\n\n16.6.3 Data races and race conditions\nTo understand why mutexes are used, we need to understand better the problem that they seek to solve, which can be summarized into data races problems. A data race problem is a type of a race condition, which happens when one thread is accessing a particular memory location (i.e. a particular shared object) at the same time that another thread is trying to write/save new data into this same memory location (i.e. the same shared object).\nWe can simply define a race condition as any type of bug in your program that is based on a “who get’s there first” problem. A data race problem is a type of a race condition, because it occurs when two or more parties are trying to read and write into the same memory location at the same time, and, therefore, the end result of this operation depends completely on who get’s to this memory location first. As consequence, a program that have a data race problem will likely produce a different result each time that we execute it.\nThus, race conditions produce undefined behaviour and unpredictability because the program produces a different answer in each time that a different person get’s to the target location first than the others. And we have no easy way to either predict or control who is getting to this target location first. In other words, in each execution of your program, you get a different answer, because a different person, or, a different function, or, a different part of the code is finishing its tasks first than the others.\nAs an example, consider the code snippet exposed below. In this example, we create a global counter variable, and we also create an increment() function, whose job is to just increment this global counter variable in a for loop.\nSince the for loop iterates 1 hundred thousand times, and, we create two separate threads in this code example, what number do you expect to see in the final message printed to stdout? The answer should be 2 hundred thousand. Right? Well, in theory, this program was supposed to print 2 hundred thousand at the end, but in practice, every time that I execute this program I get a different answer.\nIn the example exposed below, you can see that this time the end result was 117254, instead of the expected 200000. The second time I have executed this program, I got the number 108592 as result. So the end result of this program is varying, but it never gets to the expected 200000 that we want.\n\n// Global counter variable\nvar counter: usize = 0;\n// Function to increment the counter\nfn increment() void {\n    for (0..100000) |_| {\n        counter += 1;\n    }\n}\n\npub fn main() !void {\n    const thr1 = try Thread.spawn(.{}, increment, .{});\n    const thr2 = try Thread.spawn(.{}, increment, .{});\n    thr1.join();\n    thr2.join();\n    try stdout.print(\"Couter value: {d}\\n\", .{counter});\n}\n\nCouter value: 117254\nWhy this is happening? The answer is: because this program contains a data race problem. This program would print the correct number 200000, if, and only if the first thread finishes its tasks before the second thread starts to execute. But that is very unlikely to happen. Because the process of creating the thread is too fast, and therefore, both threads starts to execute roughly at the same time. If you change this code to add some nanoseconds of sleep between the first and the second calls to spawn(), you will increase the chances of the program producing the “correct result”.\nSo the data race problem happens, because both threads are reading and writing to the same memory location at roughly the same time. In this example, each thread is essentially performing three basic operations at each iteration of the for loop, which are:\n\nreading the current value of count.\nincrementing this value by 1.\nwriting the result back into count.\n\nIdeally, a thread B should read the value of count, only after the other thread A has finished writing the incremented value back into the count object. Therefore, in the ideal scenario, which is demonstrated at Table 16.1, the threads should work in sync with each other. But the reality is that these threads are out of sync, and because of that, they suffer from a data race problem, which is demonstrated at Table 16.2.\nNotice that, in the data race scenario (Table 16.2), the read performed by a thread B happens before the write operation of thread A, and that ultimately leads to wrong results at the end of the program. Because when the thread B reads the value from the count variable, the thread A is still processing the initial value from count, and it did not write the new and incremented value into count yet. So what happens is that thread B ends up reading the same initial value (the “old” value) from count, instead of reading the new and incremented version of this value that would be calculated by thread A.\n\n\n\nTable 16.1: An ideal scenario for two threads incrementing the same integer value\n\n\n\n\n\nThread 1\nThread 2\nInteger value\n\n\n\n\nread value\n\n0\n\n\nincrement\n\n1\n\n\nwrite value\n\n1\n\n\n\nread value\n1\n\n\n\nincrement\n2\n\n\n\nwrite value\n2\n\n\n\n\n\n\n\n\n\nTable 16.2: A data race scenario when two threads are incrementing the same integer value\n\n\n\n\n\nThread 1\nThread 2\nInteger value\n\n\n\n\nread value\n\n0\n\n\n\nread value\n0\n\n\nincrement\n\n1\n\n\n\nincrement\n1\n\n\nwrite value\n\n1\n\n\n\nwrite value\n1\n\n\n\n\n\n\nIf you think about these diagrams exposed in form of tables, you will notice that they relate back to our discussion of atomic operations at Section 16.6.2. Remember, atomic operations are operations that the CPU executes from beginning to end, without interruptions from other threads or processes. So, the scenario exposed at Table 16.1 do not suffer from a data race, because the operations performed by thread A are not interrupted in the middle by the operations from thread B.\nIf we also think about the discussion of critical section from Section 16.6.1, we can identify the section that representes the critical section of the program, which is the section that is vulnerable to data race conditions. In this example, the critical section of the program is the line where we increment the counter variable (counter += 1). So, ideally, we want to use a mutex, and lock right before this line, and then, unlock right after this line.\n\n\n16.6.4 Using mutexes in Zig\nNow that we know the problem that mutexes seek to solve, we can learn how to use them in Zig. Mutexes in Zig are available through the std.Thread.Mutex struct from the Zig Standard Library. If we take the same code example from the previous example, and improve it with mutexes, to solve our data race problem, we get the code example exposed below.\nNotice that we had this time to alter the increment() function to receive a pointer to the Mutex object as input. All that we need to do, to make this program safe against data race problems, is to call the lock() method at the beginning of the critical section, and then, call unlock() at the end of the critical section. Notice that the output of this program is now the correct number of 200000.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Thread = std.Thread;\nconst Mutex = std.Thread.Mutex;\nvar counter: usize = 0;\nfn increment(mutex: *Mutex) void {\n    for (0..100000) |_| {\n        mutex.lock();\n        counter += 1;\n        mutex.unlock();\n    }\n}\n\npub fn main() !void {\n    var mutex: Mutex = .{};\n    const thr1 = try Thread.spawn(.{}, increment, .{&mutex});\n    const thr2 = try Thread.spawn(.{}, increment, .{&mutex});\n    thr1.join();\n    thr2.join();\n    try stdout.print(\"Couter value: {d}\\n\", .{counter});\n}\n\nCouter value: 200000",
+    "text": "16.6 Mutexes\nMutexes are a classic component of every thread library. In essence, a mutex is a Mutually Exclusive Flag, and this flag acts like a type of “lock”, or as a gate keeper to a particular section of your code. Mutexes are related to thread synchronization, more specifically, they prevent you from having some classic race conditions in your program, and, therefore, major bugs and undefined behaviour that are usually difficult to track and understand.\nThe main idea behind a mutex is to help us to control the execution of a particular section of the code, and to prevent two or more threads from executing this particular section of the code at the same time. Many programmers like to compare a mutex to a bathroom door (which typically has a lock). When a thread locks its own mutex object, it’s like if the bathroom door was locked. Therefore, other people (in this case, other threads) who want to use the same bathroom at the same time must be patient and simply wait for the current occupant (or thread) to unlock the door and get out of the bathroom.\nSome other programmers also like to explain mutexes by using the analogy of “each person will have their turn to speak”. This is the analogy used in the Multithreading Code video from the Computerphile project2. Imagine if you are in a conversation circle. There is a moderator in this circle, which is the person that decides who has the right to speak at that particular moment. The moderator gives a green card (or some sort of an authorization card) to the person that is going to speak, and, as a result, everyone else must be silent and hear this person that has the green card. When the person finishes talking, they give the green card back to the moderator, and the moderator decides who is going to talk next, and delivers the green card to that person. And the cycle goes on like this.\nA mutex acts like the moderator in this conversation circle. The mutex authorizes one single thread to execute a specific section of the code, and it also blocks the other threads from executing this same section of the code. If these other threads want to execute this same piece of the code, they are forced to wait for the the authorized thread to finish first. When the authorized thread finishes executing this code, the mutex authorizes the next thread to execute this code, while the remaining threads remain blocked. Therefore, a mutex is like a moderator that does a “each thread will have their turn to execute this section of the code” type of control.\nMutexes are especially used to prevent data race problems from happening. A data race problem happens when two or more threads are trying to read from or write to the same shared object at the same time. So, when you have an object that is shared will all threads, and, you want to avoid two or more threads from accessing this same object at the same time, you can use a mutex to lock the part of the code that access this specific object. When a thread tries to run this code that is locked by a mutex, this thread stops its execution, and patiently waits for this section of the codebase to be unlocked to continue.\nNotice that mutexes are normally used to lock areas of the codebase that access/modify data that is shared with all threads, i.e., objects that are either stored in the global data section, or in the heap space of your program. So mutexes are not normally used on areas of the codebase that access/modify objects that are local to the thread.\n\n16.6.1 Critical section\nCritical section is a concept commonly associated with mutexes and thread synchronization. In essence, a critical section is the section of the program that a thread access/modify a shared resource (i.e., an object, a file descriptor, something that all threads have access to). In other words, a critical section is the section of the program where race conditions might happen, and, therefore, where undefined behaviour can be introduced into the program.\nWhen we use mutexes in our program, the critical section defines the area of the codebase that we want to lock. So we normally lock the mutex object at the beginning of the critical section, and then, we unlock it at the end of the critical section. The two bullet points exposed below comes from the “Critical Section” article from GeekFromGeeks, and they summarise well the role that a critical section plays in the thread synchronization problem (Geeks for Geeks 2024).\n\nThe critical section must be executed as an atomic operation, which means that once one thread or process has entered the critical section, all other threads or processes must wait until the executing thread or process exits the critical section. The purpose of synchronization mechanisms is to ensure that only one thread or process can execute the critical section at a time.\nThe concept of a critical section is central to synchronization in computer systems, as it is necessary to ensure that multiple threads or processes can execute concurrently without interfering with each other. Various synchronization mechanisms such as semaphores, mutexes, monitors, and condition variables are used to implement critical sections and ensure that shared resources are accessed in a mutually exclusive manner.\n\n\n\n16.6.2 Atomic operations\nYou will also see the term “atomic operation” a lot when reading about threads, race conditions and mutexes. In summary, an operation is categorized as “atomic” when a context switch cannot occur in the middle of the operation. In other words, this operation is always done from beginning to end, without interruptions of another process or operation in the middle of its execution phase.\nNot many operations today are atomic. But why do atomic operations matter here? It’s because data races (which is a type of a race condition) cannot happen on operations that are atomic. So if a particular line in your code performs an atomic operation, then this line will never suffer from a data race problem. Therefore, programmers sometimes use an atomic operation to protect themselves from data race problems in their code.\nWhen you have an operation that is compiled into just one single assembly instruction, this operation might be atomic, because it’s just one assembly instruction. But this is not guaranteed. This is usually true for old CPU architectures (such as x86). But nowadays, most assembly instructions in modern CPU architectures are broken down into multiple micro-tasks, which inherently makes the operation non-atomic, even if it consists of a single assembly instruction.\nThe Zig Standard Library offers some atomic functionality in the std.atomic module. In this module, you will find a public and generic function called Value(). With this function we create an “atomic object”, which is a value that contains some native atomic operations, most notably, a load() and a fetchAdd() operation. If you have experience with multithreading in C++, you probably have recognized this pattern. So yes, this generic “atomic object” in Zig is essentially identical to the template struct std::atomic from the C++ Standard Library. It’s important to emphasize that only primitive data types (i.e., the types presented in Section 1.5) are supported by these atomic operations in Zig.\n\n\n16.6.3 Data races and race conditions\nTo understand why mutexes are used, we need to understand better the problem that they seek to solve, which can be summarized into data race problems. A data race problem is a type of a race condition, which happens when one thread is accessing a particular memory location (i.e., a particular shared object) at the same time that another thread is trying to write/save new data into this same memory location (i.e., the same shared object).\nWe can simply define a race condition as any type of bug in your program that is based on a “who gets there first” problem. A data race problem is a type of a race condition, because it occurs when two or more parties are trying to read and write into the same memory location at the same time, and, therefore, the end result of this operation depends completely on who gets to this memory location first. As a consequence, a program that has a data race problem will likely produce a different result each time that we execute it.\nThus, race conditions produce undefined behaviour and unpredictability because the program produces a different answer each time a different person gets to the target location before the others. And, we have no easy way to either predict or control who is getting to this target location first. In other words, each time your program runs, you may get a different answer because a different person, function, or part of the code finishes its tasks before the others.\nAs an example, consider the code snippet exposed below. In this example, we create a global counter variable, and we also create an increment() function, whose job is to just increment this global counter variable in a for loop.\nSince the for loop iterates 1 hundred thousand times, and, we create two separate threads in this code example, what number do you expect to see in the final message printed to stdout? The answer should be 2 hundred thousand. Right? Well, in theory, this program was supposed to print 2 hundred thousand at the end, but in practice, every time that I execute this program I get a different answer.\nIn the example exposed below, you can see that this time the end result was 117254, instead of the expected 200000. The second time I executed this program, I got the number 108592 as the result. So the end result of this program is varying, but it never gets to the expected 200000 that we want.\n\n// Global counter variable\nvar counter: usize = 0;\n// Function to increment the counter\nfn increment() void {\n    for (0..100000) |_| {\n        counter += 1;\n    }\n}\n\npub fn main() !void {\n    const thr1 = try Thread.spawn(.{}, increment, .{});\n    const thr2 = try Thread.spawn(.{}, increment, .{});\n    thr1.join();\n    thr2.join();\n    try stdout.print(\"Couter value: {d}\\n\", .{counter});\n}\n\nCouter value: 117254\nWhy this is happening? The answer is: because this program contains a data race problem. This program would print the correct number 200000 if and only if the first thread finishes its tasks before the second thread starts to execute. But that is very unlikely to happen. Because the process of creating the thread is too fast, and therefore, both threads start to execute roughly at the same time. If you change this code to add some nanoseconds of sleep between the first and the second calls to spawn(), you will increase the chances of the program producing the “correct result”.\nSo the data race problem happens because both threads are reading and writing to the same memory location at roughly the same time. In this example, each thread is essentially performing three basic operations at each iteration of the for loop, which are:\n\nreading the current value of count.\nincrementing this value by 1.\nwriting the result back into count.\n\nIdeally, a thread B should read the value of count, only after the other thread A has finished writing the incremented value back into the count object. Therefore, in the ideal scenario, which is demonstrated in Table 16.1, the threads should work in sync with each other. But the reality is that these threads are out of sync, and because of that, they suffer from a data race problem, which is demonstrated in Table 16.2.\nNotice that, in the data race scenario (Table 16.2), the read performed by a thread B happens before the write operation of thread A, and that ultimately leads to wrong results at the end of the program. Because when thread B reads the value of the count variable, thread A is still processing the initial value from count, and has not yet written the new, incremented value back to count. As a result, thread B ends up reading the same initial (or “old”) value from count instead of the updated, incremented value that thread A would have written.\n\n\n\nTable 16.1: An ideal scenario for two threads incrementing the same integer value\n\n\n\n\n\nThread 1\nThread 2\nInteger value\n\n\n\n\nread value\n\n0\n\n\nincrement\n\n1\n\n\nwrite value\n\n1\n\n\n\nread value\n1\n\n\n\nincrement\n2\n\n\n\nwrite value\n2\n\n\n\n\n\n\n\n\n\nTable 16.2: A data race scenario when two threads are incrementing the same integer value\n\n\n\n\n\nThread 1\nThread 2\nInteger value\n\n\n\n\nread value\n\n0\n\n\n\nread value\n0\n\n\nincrement\n\n1\n\n\n\nincrement\n1\n\n\nwrite value\n\n1\n\n\n\nwrite value\n1\n\n\n\n\n\n\nIf you think about these diagrams exposed in form of tables, you will notice that they relate back to our discussion of atomic operations in Section 16.6.2. Remember, atomic operations are operations that the CPU executes from beginning to end, without interruptions from other threads or processes. So, the scenario exposed in Table 16.1 does not suffer from a data race, because the operations performed by thread A are not interrupted in the middle by the operations from thread B.\nIf we also think about the discussion of critical section from Section 16.6.1, we can identify the section that representes the critical section of the program, which is the section that is vulnerable to data race conditions. In this example, the critical section of the program is the line where we increment the counter variable (counter += 1). So, ideally, we want to use a mutex, and lock right before this line, and then unlock right after this line.\n\n\n16.6.4 Using mutexes in Zig\nNow that we know the problem that mutexes seek to solve, we can learn how to use them in Zig. Mutexes in Zig are available through the std.Thread.Mutex struct from the Zig Standard Library. If we take the same code from the previous example, and improve it with mutexes, to solve our data race problem, we get the code example below.\nNotice that this time, we had to alter the increment() function to receive a pointer to the Mutex object as input. All that we need to do, to make this program safe against data race problems, is to call the lock() method at the beginning of the critical section, and then, call unlock() at the end of the critical section. Notice that the output of this program is now the correct number of 200000.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Thread = std.Thread;\nconst Mutex = std.Thread.Mutex;\nvar counter: usize = 0;\nfn increment(mutex: *Mutex) void {\n    for (0..100000) |_| {\n        mutex.lock();\n        counter += 1;\n        mutex.unlock();\n    }\n}\n\npub fn main() !void {\n    var mutex: Mutex = .{};\n    const thr1 = try Thread.spawn(.{}, increment, .{&mutex});\n    const thr2 = try Thread.spawn(.{}, increment, .{&mutex});\n    thr1.join();\n    thr2.join();\n    try stdout.print(\"Couter value: {d}\\n\", .{counter});\n}\n\nCouter value: 200000",
     "crumbs": [
       "<span class='chapter-number'>16</span>  <span class='chapter-title'>Introducing threads and parallelism in Zig</span>"
     ]
@@ -1354,7 +1354,7 @@
     "href": "Chapters/14-threads.html#readwrite-locks",
     "title": "16  Introducing threads and parallelism in Zig",
     "section": "16.7 Read/Write locks",
-    "text": "16.7 Read/Write locks\nMutexes are normally used when is always not safe to have two or more threads running the same piece of code at the same time. In contrast, read/write locks are normally used in situations where you have a mixture of scenarios, i.e. there are some pieces of the codebase that are safe to run in parallel, and other pieces that are not safe.\nFor example, suppose that you have multiple threads that uses the same shared file in the filesystem to store some configurations, or, statistics. If two or more threads try to read the data from this same file at the same time, nothing bad happens. So this part of the codebase is perfectly safe to be executed in parallel, with multiple threads reading the same file at the same time.\nHowever, if two or more threads try to write data into this same file at the same time, then, we cause some race conditions problems. So this other part of the codebase is not safe to be executed in parallel. More specifically, a thread might end up writing data in the middle of the data written by the other thread. This process of two or more threads writing to the same location, might lead to data corruption. This specific situation is usually called of a torn write.\nThus, what we can extract from this example is that there is certain types of operations that causes a race condition, but there are also, other types of operations that do not cause a race condition problem. You could also say that, there are types of operations that are susceptible to race condition problems, and there are other types of operations that are not.\nA read/write lock is a type of lock that acknowledges the existance of this specific scenario, and you can use this type of lock to control which parts of the codebase are safe to run in parallel, and which parts are not safe.\n\n16.7.1 Exclusive lock vs shared lock\nTherefore, a read/write lock is a little different from a mutex. Because a mutex is always an exclusive lock, meaning that, only one thread is allowed to execute at all times. With an exclusive lock, the other threads are always “excluded”, i.e. they are always blocked from executing. But in a read/write lock, the other threads might be authorized to run at the same time, depending on the type of lock that they acquire.\nWe have two types of locks in a read/write lock, which are: an exclusive lock and a shared lock. An exclusive lock works exactly the same as a mutex, while a shared lock is a lock that does not block the other threads from running at the same time. In the pthreads C library, read/write locks are available through the pthread_rwlock_t C struct. With this C struct, you can create:\n\na “write lock”, which corresponds to an exclusive lock.\na “read lock”, which corresponds to a shared lock.\n\nThe terminology might be a little different compared to Zig. But the meaning is still the same. Therefore, just remember this relationship, write locks are exclusive locks, while read locks are shared locks.\nWhen a thread tries to acquire a read lock (i.e. a shared lock), this thread get’s the shared lock if, and only if another thread does not currently holds a write lock (i.e. an exclusive lock), and also, if there are no other threads that are already in the queue, waiting for their turn to acquire a write lock. In other words, the thread in the queue have attempted to get a write lock earlier, but this thread was blocked because there was another thread running that already had a write lock. As consequence, this thread is on the queue to get a write lock, and it’s currently waiting for the other thread with a write lock to finish its execution.\nWhen a thread tries to acquire a read lock, but it fails in acquiring this read lock, either because there is a thread with a write lock already running, or, because there is a thread in the queue to get a write lock, the execution of this thread is instantly blocked, i.e. paused. This thread will indefinitely attempt to get the read lock, and its execution will be unblocked (or unpaused) only after this thread successfully acquires the read lock.\nIf you think deeply about this dynamic between read locks versus write locks, you might notice that a read lock is basically a safety mechanism. More specifically, it is a way for us to allow a particular thread to run together with the other threads, only when it’s safe to. In other words, if there is currently a thread with a write lock running, then, it is very likely not safe for the thread that is trying to acquire the read lock to run now. As consequence, the read lock protects this thread from running into dangerous waters, and patiently waits for the “write lock” thread to finishes its tasks before it continues.\nOn the other hand, if there are only “read lock” (i.e. “shared lock”) threads currently running (i.e. not a single “write lock” thread currently exists), then, is perfectly safe for this thread that is acquiring the read lock to run in parallel with the other threads. As a result, the read lock just allows for this thread to run together with the other threads.\nThus, by using read locks (shared locks) in conjunction with write locks (exclusive locks), we can control which regions or sections of our multithreaded code is safe to have parallelism, and which sections are not safe to have parallelism.\n\n\n16.7.2 Using read/write locks in Zig\nThe Zig Standard Library supports read/write locks through the std.Thread.RwLock module. If you want to a particular thread to acquire a shared lock (i.e. a read lock), you should call the lockShared() method from the RwLock object. But, if you want for this thread to acquire an exclusive lock (i.e. a write lock) instead, then, you should call the lock() method from the RwLock object.\nAs with mutexes, we also have to unlock the shared or exclusive locks that we acquire through a read/write lock object, once we are at the end of our “critical section”. If you have acquired an exclusive lock, then, you unlock this exclusive lock by calling the unlock() method from the read/write lock object. In contrast, if you have acquired a shared lock instead, then, call unlockShared() to unlock this shared lock.\nAs a simple example, the snippet exposed below creates three separate threads responsible for reading the current value in a counter object, and it also creates another thread, responsible for writing new data into the counter object (incrementing it, more specifically).\n\nvar counter: u32 = 0;\nfn reader(lock: *RwLock) !void {\n    while (true) {\n        lock.lockShared();\n        const v: u32 = counter;\n        try stdout.print(\"{d}\", .{v});\n        lock.unlockShared();\n        std.time.sleep(2 * std.time.ns_per_s);\n    }\n}\nfn writer(lock: *RwLock) void {\n    while (true) {\n        lock.lock();\n        counter += 1;\n        lock.unlock();\n        std.time.sleep(2 * std.time.ns_per_s);\n    }\n}\n\npub fn main() !void {\n    var lock: RwLock = .{};\n    const thr1 = try Thread.spawn(.{}, reader, .{&lock});\n    const thr2 = try Thread.spawn(.{}, reader, .{&lock});\n    const thr3 = try Thread.spawn(.{}, reader, .{&lock});\n    const wthread = try Thread.spawn(.{}, writer, .{&lock});\n\n    thr1.join();\n    thr2.join();\n    thr3.join();\n    wthread.join();\n}",
+    "text": "16.7 Read/Write locks\nMutexes are normally used when it’s not always safe for two or more threads running the same piece of code at the same time. In contrast, read/write locks are normally used in situations where you have a mixture of scenarios, i.e., there are some pieces of the codebase that are safe to run in parallel, and other pieces that are not safe.\nFor example, suppose that you have multiple threads that uses the same shared file in the filesystem to store some configurations, or statistics. If two or more threads try to read the data from this same file at the same time, nothing bad happens. So this part of the codebase is perfectly safe to be executed in parallel, with multiple threads reading the same file at the same time.\nHowever, if two or more threads try to write data into this same file at the same time, then we cause some race condition problems. So this other part of the codebase is not safe to be executed in parallel. More specifically, a thread might end up writing data in the middle of the data written by the other thread. This process of two or more threads writing to the same location might lead to data corruption. This specific situation is usually called a torn write.\nThus, what we can extract from this example is that there are certain types of operations that cause a race condition, but there are also other types of operations that do not cause a race condition problem. You could also say that there are types of operations that are susceptible to race condition problems, and there are other types of operations that are not.\nA read/write lock is a type of lock that acknowledges the existence of this specific scenario, and you can use this type of lock to control which parts of the codebase are safe to run in parallel and which parts are not.\n\n16.7.1 Exclusive lock vs shared lock\nTherefore, a read/write lock is a little different from a mutex. Because a mutex is always an exclusive lock, meaning that, only one thread is allowed to execute at all times. With an exclusive lock, the other threads are always “excluded”, i.e., they are always blocked from executing. But in a read/write lock, the other threads might be authorized to run at the same time, depending on the type of lock that they acquire.\nWe have two types of locks in a read/write lock, which are: an exclusive lock and a shared lock. An exclusive lock works exactly the same as a mutex, while a shared lock is a lock that does not block the other threads from running at the same time. In the pthreads C library, read/write locks are available through the pthread_rwlock_t C struct. With this C struct, you can create:\n\na “write lock”, which corresponds to an exclusive lock.\na “read lock”, which corresponds to a shared lock.\n\nThe terminology might be a little different compared to Zig. But the meaning is still the same. Therefore, just remember this relationship, write locks are exclusive locks, while read locks are shared locks.\nWhen a thread tries to acquire a read lock (i.e., a shared lock), this thread gets the shared lock if and only if another thread does not currently hold a write lock (i.e., an exclusive lock), and also if there are no other threads already in the queue, waiting for their turn to acquire a write lock. In other words, the thread in the queue has attempted to get a write lock earlier, but this thread was blocked because there was another thread running that already had a write lock. As a consequence, this thread is in the queue to get a write lock, and it’s currently waiting for the other thread with a write lock to finish its execution.\nWhen a thread tries to acquire a read lock, but it fails in acquiring this read lock, either because there is a thread with a write lock already running, or because there is a thread in the queue to get a write lock, the execution of this thread is instantly blocked, i.e., paused. This thread will indefinitely attempt to get the read lock, and its execution will be unblocked (or unpaused) only after this thread successfully acquires the read lock.\nIf you think deeply about this dynamic between read locks versus write locks, you might notice that a read lock is basically a safety mechanism. More specifically, it’s a way for us to allow a particular thread to run together with the other threads only when it’s safe to. In other words, if there is currently a thread with a write lock running, then it’s very likely not safe for the thread that is trying to acquire the read lock to run now. As a consequence, the read lock protects this thread from running into dangerous waters, and patiently waits for the “write lock” thread to finishes its tasks before it continues.\nOn the other hand, if there are only “read lock” (i.e., “shared lock”) threads currently running (i.e., not a single “write lock” thread currently exists), then it is perfectly safe for this thread that is acquiring the read lock to run in parallel with the other threads. As a result, the read lock just allows for this thread to run together with the other threads.\nThus, by using read locks (shared locks) in conjunction with write locks (exclusive locks), we can control which regions or sections of our multithreaded code is safe to have parallelism, and which sections are not safe to have parallelism.\n\n\n16.7.2 Using read/write locks in Zig\nThe Zig Standard Library supports read/write locks through the std.Thread.RwLock module. If you want a particular thread to acquire a shared lock (i.e., a read lock), you should call the lockShared() method from the RwLock object. But, if you want this thread to acquire an exclusive lock (i.e., a write lock) instead, then you should call the lock() method from the RwLock object.\nAs with mutexes, we also have to unlock the shared or exclusive locks that we acquire through a read/write lock object, once we are at the end of our “critical section”. If you have acquired an exclusive lock, then, you unlock this exclusive lock by calling the unlock() method from the read/write lock object. In contrast, if you have acquired a shared lock instead, then, call unlockShared() to unlock this shared lock.\nAs a simple example, the snippet below creates three separate threads responsible for reading the current value in a counter object, and it also creates another thread responsible for writing new data into the counter object (incrementing it, more specifically).\n\nvar counter: u32 = 0;\nfn reader(lock: *RwLock) !void {\n    while (true) {\n        lock.lockShared();\n        const v: u32 = counter;\n        try stdout.print(\"{d}\", .{v});\n        lock.unlockShared();\n        std.time.sleep(2 * std.time.ns_per_s);\n    }\n}\nfn writer(lock: *RwLock) void {\n    while (true) {\n        lock.lock();\n        counter += 1;\n        lock.unlock();\n        std.time.sleep(2 * std.time.ns_per_s);\n    }\n}\n\npub fn main() !void {\n    var lock: RwLock = .{};\n    const thr1 = try Thread.spawn(.{}, reader, .{&lock});\n    const thr2 = try Thread.spawn(.{}, reader, .{&lock});\n    const thr3 = try Thread.spawn(.{}, reader, .{&lock});\n    const wthread = try Thread.spawn(.{}, writer, .{&lock});\n\n    thr1.join();\n    thr2.join();\n    thr3.join();\n    wthread.join();\n}",
     "crumbs": [
       "<span class='chapter-number'>16</span>  <span class='chapter-title'>Introducing threads and parallelism in Zig</span>"
     ]
@@ -1364,7 +1364,7 @@
     "href": "Chapters/14-threads.html#yielding-a-thread",
     "title": "16  Introducing threads and parallelism in Zig",
     "section": "16.8 Yielding a thread",
-    "text": "16.8 Yielding a thread\nThe Thread struct supports yielding through the yield() method. Yielding a thread means that the execution of the thread is temporarily stopped, and the thread comes back to the end of the queue of priority of the scheduler from your operating system.\nThat is, when you yield a thread, you are essentially saying the following to your OS: “Hey! Could you please stop executing this thread for now, and comeback to continue it later?”. You could also interpret this yield operation as: “Could you please deprioritize this thread, to focus on doing other things instead?”. So this yield operation is also a way for you to stop a particular thread, so that you can work and prioritize other threads instead.\nIs important to say that, yielding a thread is a “not so common” thread operation these days. In other words, not many programmers use yielding in production, simply because is hard to use this operation and make it work properly, and also, there are better alternatives. Most programmers prefer to use join() instead. In fact, most of the times, when you see somebody using this “yield” operation in some code example, they are mostly using it to help them debug race conditions in their applications. That is, this “yield” operation is mostly used as a debug tool nowadays.\nAnyway, if you want to yield a thread, just call the yield() method from it, like this:\n\nthread.yield();",
+    "text": "16.8 Yielding a thread\nThe Thread struct supports yielding through the yield() method. Yielding a thread means that the execution of the thread is temporarily stopped, and it moves to the end of the priority queue managed by the scheduler of your operating system.\nThat is, when you yield a thread, you are essentially saying the following to your OS: “Hey! Could you please stop executing this thread for now, and comeback to continue it later?”. You could also interpret this yield operation as: “Could you please deprioritize this thread, to focus on doing other things instead?”. So this yield operation is also a way for you to stop a particular thread, so that you can work and prioritize other threads instead.\nIt’s important to say that, yielding a thread is a “not so common” thread operation these days. In other words, not many programmers use yielding in production, simply because it’s hard to use this operation and make it work properly, and also, there are better alternatives. Most programmers prefer to use join() instead. In fact, most of the time, when you see someone using this “yield” operation in some code example, they are usually doing so to help debug race conditions in their applications. That is, this “yield” operation is mostly used as a debug tool nowadays.\nAnyway, if you want to yield a thread, just call the yield() method from it, like this:\n\nthread.yield();",
     "crumbs": [
       "<span class='chapter-number'>16</span>  <span class='chapter-title'>Introducing threads and parallelism in Zig</span>"
     ]
@@ -1374,7 +1374,7 @@
     "href": "Chapters/14-threads.html#common-problems-in-threads",
     "title": "16  Introducing threads and parallelism in Zig",
     "section": "16.9 Common problems in threads",
-    "text": "16.9 Common problems in threads\n\n16.9.1 Deadlocks\nA deadlock occurs when two or more threads are blocked forever, waiting for each other to release a resource. This usually happens when multiple locks are involved, and the order of acquiring them is not well managed.\nThe code example below demonstrates a deadlock situation. We have two different threads that execute two different functions (work1() and work2()) in this example. And we also have two separate mutexes. If you compile and run this code example, you will notice that the program just runs indefinitely, without ending.\nWhen we look into the first thread, which executes the work1() function, we can notice that this function acquires the mut1 lock first. Because this is the first operation that is executed inside this thread, which is the first thread created in the program. After that, the function sleeps for 1 second, to simulate some type of work, and then, the function tries to acquire the mut2 lock.\nOn the other hand, when we look into the second thread, which executes the work2() function, we can see that this function acquires the mut2 lock first. Because when this thread get’s created and it tries to acquire this mut2 lock, the first thread is still sleeping on that “sleep 1 second” line. After acquiring mut2, the work2() function also sleeps for 1 second, to simulate some type of work, and then, the function tries to acquire the mut1 lock.\nThis creates a deadlock situation, because after the “sleep for 1 second” line in both threads, the thread 1 is trying to acquire the mut2 lock, but this lock is currently being used by thread 2. However, at this moment, the thread 2 is also trying to acquire the mut1 lock, which is currently being used by thread 1. Therefore, both threads end up waiting for ever. Waiting for their peer to free the lock that they want to acquire.\n\nvar mut1: Mutex = .{}; var mut2: Mutex = .{};\nfn work1() !void {\n    mut1.lock();\n    std.time.sleep(1 * std.time.ns_per_s);\n    mut2.lock();\n    _ = try stdout.write(\"Doing some work 1\\n\");\n    mut2.unlock(); mut1.unlock();\n}\n\nfn work2() !void {\n    mut2.lock();\n    std.time.sleep(1 * std.time.ns_per_s);\n    mut1.lock();\n    _ = try stdout.write(\"Doing some work 1\\n\");\n    mut1.unlock(); mut2.unlock();\n}\n\npub fn main() !void {\n    const thr1 = try Thread.spawn(.{}, work1, .{});\n    const thr2 = try Thread.spawn(.{}, work2, .{});\n    thr1.join();\n    thr2.join();\n}\n\n\n\n16.9.2 Not calling join() or detach()\nWhen you do not call either join() or detach() over a thread, then, this thread becomes a “zombie thread”, because it does not have a clear “return point”. You could also interpret this as: “nobody is properly responsible for managing the thread”. When we don’t establish if a thread is either joinable or detached, nobody becomes responsible for dealing with the return value of this thread, and also, nobody becomes responsible for clearing (or freeing) the resources associated with this thread.\nYou don’t want to be in this situation, so remember to always use join() or detach() on the threads that you create. When you don’t use one of these methods, we lose control over the thread, and its resources are never freed (i.e. you have leaked resources in the system).\n\n\n16.9.3 Cancelling or killing a particular thread\nWhen we think about the pthreads C library, there is a possible way to asynchronously kill or cancel a thread, which is by sending a SIGTERM signal to the thread through the pthread_kill() function. But canceling a thread like this is bad. Is dangerously bad. As consequence, the Zig implementation of threads does not have a similar function, or, a similar way to asynchronously cancel or kill a thread.\nTherefore, if you want to cancel a thread in the middle of its execution in Zig, then, one good strategy that you can take is to use control flow in conjunction with join(). More specifically, you can design your thread around a while loop, that is constantly checking if the thread should continue running. If is time to cancel the thread, we could make the while loop break, and join the thread with the main thread by calling join().\nThe code example below demonstrates to some extent this strategy. Here, we are using control flow to break the while loop, and exit the thread earlier than what we have initially planned to. This example also demonstrates how can we use atomic objects in Zig with the Value() generic function that we have mentioned at Section 16.6.2.\n\nconst std = @import(\"std\");\nconst Thread = std.Thread;\nconst stdout = std.io.getStdOut().writer();\nvar running = std.atomic.Value(bool).init(true);\nvar counter: u64 = 0;\nfn do_more_work() void {\n    std.time.sleep(2 * std.time.ns_per_s);\n}\nfn work() !void {\n    while (running.load(.monotonic)) {\n        for (0..10000) |_| { counter += 1; }\n        if (counter &lt; 15000) {\n            _ = try stdout.write(\n                \"Time to cancel the thread.\\n\"\n            );\n            running.store(false, .monotonic);\n        } else {\n            _ = try stdout.write(\"Time to do more work.\\n\");\n            do_more_work();\n            running.store(false, .monotonic);\n        }\n    }\n}\n\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, work, .{});\n    thread.join();\n}\n\nTime to cancel the thread.\n\n\n\n\n\n\nGeeks for Geeks. 2024. “Critical Section.” Geeks for Geeks. https://www.geeksforgeeks.org/g-fact-70/.\n\n\nLinux man-pages. 2024. “Pthread_create(3) — Linux Manual Page.” https://man7.org/linux/man-pages/man3/pthread_create.3.html.",
+    "text": "16.9 Common problems in threads\n\n16.9.1 Deadlocks\nA deadlock occurs when two or more threads are blocked forever, waiting for each other to release a resource. This usually happens when multiple locks are involved, and the order of acquiring them is not well managed.\nThe code example below demonstrates a deadlock situation. We have two different threads that execute two different functions (work1() and work2()) in this example. And we also have two separate mutexes. If you compile and run this code example, you will notice that the program just runs indefinitely, without ending.\nWhen we look into the first thread, which executes the work1() function, we can notice that this function acquires the mut1 lock first. Because this is the first operation that is executed inside this thread, which is the first thread created in the program. After that, the function sleeps for 1 second, to simulate some type of work, and then, the function tries to acquire the mut2 lock.\nOn the other hand, when we look into the second thread, which executes the work2() function, we can see that this function acquires the mut2 lock first. Because when this thread gets created and it tries to acquire this mut2 lock, the first thread is still sleeping on that “sleep 1 second” line. After acquiring mut2, the work2() function also sleeps for 1 second, to simulate some type of work, and then the function tries to acquire the mut1 lock.\nThis creates a deadlock situation, because after the “sleep for 1 second” line in both threads, thread 1 is trying to acquire the mut2 lock, but this lock is currently being used by thread 2. However, at this moment, thread 2 is also trying to acquire the mut1 lock, which is currently being used by thread 1. Therefore, both threads end up waiting for ever. Waiting for their peer to free the lock that they want to acquire.\n\nvar mut1: Mutex = .{}; var mut2: Mutex = .{};\nfn work1() !void {\n    mut1.lock();\n    std.time.sleep(1 * std.time.ns_per_s);\n    mut2.lock();\n    _ = try stdout.write(\"Doing some work 1\\n\");\n    mut2.unlock(); mut1.unlock();\n}\n\nfn work2() !void {\n    mut2.lock();\n    std.time.sleep(1 * std.time.ns_per_s);\n    mut1.lock();\n    _ = try stdout.write(\"Doing some work 1\\n\");\n    mut1.unlock(); mut2.unlock();\n}\n\npub fn main() !void {\n    const thr1 = try Thread.spawn(.{}, work1, .{});\n    const thr2 = try Thread.spawn(.{}, work2, .{});\n    thr1.join();\n    thr2.join();\n}\n\n\n\n16.9.2 Not calling join() or detach()\nWhen you do not call either join() or detach() over a thread, then this thread becomes a “zombie thread”, because it does not have a clear “return point”. You could also interpret this as: “nobody is properly responsible for managing the thread”. When we don’t establish if a thread is either joinable or detached, nobody becomes responsible for dealing with the return value of this thread, and also, nobody becomes responsible for clearing (or freeing) the resources associated with this thread.\nYou don’t want to be in this situation, so remember to always use join() or detach() on the threads that you create. When you don’t use one of these methods, we lose control over the thread, and its resources are never freed (i.e., you have leaked resources in the system).\n\n\n16.9.3 Cancelling or killing a particular thread\nWhen we think about the pthreads C library, there is a possible way to asynchronously kill or cancel a thread, which is by sending a SIGTERM signal to the thread through the pthread_kill() function. But canceling a thread like this is bad. It’s dangerously bad. As a consequence, the Zig implementation of threads does not have a similar function, or, a similar way to asynchronously cancel or kill a thread.\nTherefore, if you want to cancel a thread in the middle of its execution in Zig, then one good strategy that you can take is to use control flow in conjunction with join(). More specifically, you can design your thread around a while loop that is constantly checking if the thread should continue running. If it’s time to cancel the thread, we could make the while loop break, and join the thread with the main thread by calling join().\nThe code example below demonstrates to some extent this strategy. Here, we are using control flow to break the while loop, and exit the thread earlier than what we have initially planned to. This example also demonstrates how can we use atomic objects in Zig with the Value() generic function that we have mentioned in Section 16.6.2.\n\nconst std = @import(\"std\");\nconst Thread = std.Thread;\nconst stdout = std.io.getStdOut().writer();\nvar running = std.atomic.Value(bool).init(true);\nvar counter: u64 = 0;\nfn do_more_work() void {\n    std.time.sleep(2 * std.time.ns_per_s);\n}\nfn work() !void {\n    while (running.load(.monotonic)) {\n        for (0..10000) |_| { counter += 1; }\n        if (counter &lt; 15000) {\n            _ = try stdout.write(\n                \"Time to cancel the thread.\\n\"\n            );\n            running.store(false, .monotonic);\n        } else {\n            _ = try stdout.write(\"Time to do more work.\\n\");\n            do_more_work();\n            running.store(false, .monotonic);\n        }\n    }\n}\n\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, work, .{});\n    thread.join();\n}\n\nTime to cancel the thread.\n\n\n\n\n\n\nGeeks for Geeks. 2024. “Critical Section.” Geeks for Geeks. https://www.geeksforgeeks.org/g-fact-70/.\n\n\nLinux man-pages. 2024. “Pthread_create(3) — Linux Manual Page.” https://man7.org/linux/man-pages/man3/pthread_create.3.html.",
     "crumbs": [
       "<span class='chapter-number'>16</span>  <span class='chapter-title'>Introducing threads and parallelism in Zig</span>"
     ]
@@ -1394,7 +1394,7 @@
     "href": "Chapters/15-vectors.html",
     "title": "17  Introducing Vectors and SIMD",
     "section": "",
-    "text": "17.1 What is SIMD?\nSIMD (Single Instruction/Multiple Data) is a group of operations that are widely used on video/audio editing programs, and also in graphics applications. SIMD is not a new technology, but the massive use of SIMD on normal desktop computers is somewhat recent. In the old days, SIMD was only used on “supercomputer models”.\nMost modern CPU models (from AMD, Intel, etc.) these days (either in a desktop or in a notebook model) have support for SIMD operations. So, if you have a very old CPU model installed in your computer, then, is possible that you have no support for SIMD operations in your computer.\nWhy people have started using SIMD on their software? The answer is performance. But what SIMD precisely do to achieve better performance? Well, in essence, SIMD operations are a different strategy to get parallel computing in your program, and therefore, make faster calculations.\nThe basic idea behind SIMD is to have a single instruction that operates over multiple data at the same time. When you perform a normal scalar operation, like for example, four add instructions, each addition is performed separately, one after another. But with SIMD, these four add instructions are translated into a single instruction, and, as consequence, the four additions are performed in parallel, at the same time.\nCurrently, the zig compiler allows you to apply the following group of operators on vector objects. When you apply one of these operators on vector objects, SIMD is used to make the calculations, and, therefore, these operators are applied element-wise and in parallel by default.",
+    "text": "17.1 What is SIMD?\nSIMD (Single Instruction/Multiple Data) is a group of operations that are widely used on video/audio editing programs, and also in graphics applications. SIMD is not a new technology, but the massive use of SIMD on normal desktop computers is somewhat recent. In the old days, SIMD was only used on “supercomputer models”.\nMost modern CPU models (from AMD, Intel, etc.) these days (either in a desktop or in a notebook model) have support for SIMD operations. So, if you have a very old CPU model installed in your computer, then, it’s possible that you have no support for SIMD operations in your computer.\nWhy have people started using SIMD in their software? The answer is performance. But what does SIMD precisely do to achieve better performance? Well, in essence, SIMD operations are a different strategy to get parallel computing in your program, and therefore, make faster calculations.\nThe basic idea behind SIMD is to have a single instruction that operates over multiple data at the same time. When you perform a normal scalar operation, like for example, four add instructions, each addition is performed separately, one after another. But with SIMD, these four add instructions are translated into a single instruction, and, as consequence, the four additions are performed in parallel, at the same time.\nCurrently, the zig compiler allows you to apply the following group of operators on vector objects. When you apply one of these operators on vector objects, SIMD is used to make the calculations, and, therefore, these operators are applied element-wise and in parallel by default.",
     "crumbs": [
       "<span class='chapter-number'>17</span>  <span class='chapter-title'>Introducing Vectors and SIMD</span>"
     ]
@@ -1414,7 +1414,7 @@
     "href": "Chapters/15-vectors.html#sec-what-vectors",
     "title": "17  Introducing Vectors and SIMD",
     "section": "17.2 Vectors",
-    "text": "17.2 Vectors\nA SIMD operation is usually performed through a SIMD intrinsic, which is just a fancy name for a function that performs a SIMD operation. These SIMD intrinsics (or “SIMD functions”) always operate over a special type of object, which are called “vectors”. So, in order to use SIMD, you have to create a “vector object”.\nA vector object is usually a fixed-sized block of 128 bits (16 bytes). As consequence, most vectors that you find in the wild are essentially arrays that contains 2 values of 8 bytes each, or, 4 values of 4 bytes each, or, 8 values of 2 bytes each, etc. However, different CPU models may have different extensions (or, “implementations”) of SIMD, which may offer more types of vector objects that are bigger in size (256 bits or 512 bits) to accomodate more data into a single vector object.\nYou can create a new vector object in Zig by using the @Vector() built-in function. Inside this function, you specify the vector length (number of elements in the vector), and the data type of the elements of the vector. Only primitive data types are supported in these vector objects. In the example below, I’m creating two vector objects (v1 and v2) of 4 elements of type u32 each.\nAlso notice in the example below, that a third vector object (v3) is created from the sum of the previous two vector objects (v1 plus v2). Therefore, math operations over vector objects take place element-wise by default, because the same operation (in this case, addition) is transformed into a single instruction that is replicated in parallel, across all elements of the vectors.\n\nconst v1 = @Vector(4, u32){4, 12, 37, 9};\nconst v2 = @Vector(4, u32){10, 22, 5, 12};\nconst v3 = v1 + v2;\ntry stdout.print(\"{any}\\n\", .{v3});\n\n{ 14, 34, 42, 21 }\n\n\nThis is how SIMD introduces more performance in your program. Instead of using a for loop to iterate through the elements of v1 and v2, and adding them together, one element at a time, we enjoy the benefits of SIMD, which performs all 4 additions in parallel, at the same time.\nTherefore, the @Vector structure is essentially the Zig representation of SIMD vector objects. The elements on these vector objects will be operated in parallel, if, and only if your current CPU model supports SIMD operations. If your CPU model does not have support for SIMD, then, the @Vector structure will likely produce a similar performance from a “for loop solution”.\n\n17.2.1 Transforming arrays into vectors\nThere are different ways to transform a normal array into a vector object. You can either use implicit conversion (which is when you assign the array to a vector object directly), or, use slices to create a vector object from a normal array.\nIn the example below, we are implicitly converting the array a1 into a vector object (v1) of length 4. We first explicitly annotate the data type of the vector object, and then, we assign the array object to this vector object.\nAlso notice in the example below, that a second vector object (v2) is also created by taking a slice of the array object (a1), and then, storing the pointer to this slice (.*) into this vector object.\n\nconst a1 = [4]u32{4, 12, 37, 9};\nconst v1: @Vector(4, u32) = a1;\nconst v2: @Vector(2, u32) = a1[1..3].*;\n_ = v1; _ = v2;\n\nIs worth emphasizing that only arrays and slices whose sizes are compile-time known can be transformed into vectors. Vectors in general are structures that work only with compile-time known sizes. Therefore, if you have an array whose size is runtime known, then, you first need to copy it into an array with a compile-time known size, before transforming it into a vector.\n\n\n17.2.2 The @splat() function\nYou can use the @splat() built-in function to create a vector object that is filled with the same value across all of its elements. This function was created to offer a quick and easy way to directly convert a scalar value (a.k.a. a single value, like a single character, or a single integer, etc.) into a vector object.\nThus, we can use @splat() to convert a single value, like the integer 16 into a vector object of length 1. But we can also use this function to convert the same integer 16 into a vector object of length 10, that is filled with 10 16 values. The example below demonstrates this idea.\n\nconst v1: @Vector(10, u32) = @splat(16);\ntry stdout.print(\"{any}\\n\", .{v1});\n\n{ 16, 16, 16, 16, 16, 16, 16, 16, 16, 16 }\n\n\n\n\n17.2.3 Careful with vectors that are too big\nAs I described at Section 17.2, each vector object is usually a small block of 128, 256 or 512 bits. This means that a vector object is usually small in size, and when you try to go in the opposite direction, by creating a vector object that is very big in size (i.e. sizes that are close to \\(2^{20}\\)), you usually end up with crashes and loud errors from the compiler.\nFor example, if you try to compile the program below, you will likely face segmentation faults, or, LLVM errors during the build process. Just be careful to not create vector objects that are too big in size.\n\nconst v1: @Vector(1000000, u32) = @splat(16);\n_ = v1;\n\nSegmentation fault (core dumped)",
+    "text": "17.2 Vectors\nA SIMD operation is usually performed through a SIMD intrinsic, which is just a fancy name for a function that performs a SIMD operation. These SIMD intrinsics (or “SIMD functions”) always operate over a special type of object, which are called “vectors”. So, in order to use SIMD, you have to create a “vector object”.\nA vector object is usually a fixed-sized block of 128 bits (16 bytes). As a consequence, most vectors that you find in the wild are essentially arrays that contains 2 values of 8 bytes each, or, 4 values of 4 bytes each, or, 8 values of 2 bytes each, etc. However, different CPU models may have different extensions (or, “implementations”) of SIMD, which may offer more types of vector objects that are bigger in size (256 bits or 512 bits) to accomodate more data into a single vector object.\nYou can create a new vector object in Zig by using the @Vector() built-in function. Inside this function, you specify the vector length (number of elements in the vector), and the data type of the elements of the vector. Only primitive data types are supported in these vector objects. In the example below, I’m creating two vector objects (v1 and v2) of 4 elements of type u32 each.\nAlso notice in the example below, that a third vector object (v3) is created from the sum of the previous two vector objects (v1 plus v2). Therefore, math operations over vector objects take place element-wise by default, because the same operation (in this case, addition) is transformed into a single instruction that is replicated in parallel, across all elements of the vectors.\n\nconst v1 = @Vector(4, u32){4, 12, 37, 9};\nconst v2 = @Vector(4, u32){10, 22, 5, 12};\nconst v3 = v1 + v2;\ntry stdout.print(\"{any}\\n\", .{v3});\n\n{ 14, 34, 42, 21 }\n\n\nThis is how SIMD introduces more performance in your program. Instead of using a for loop to iterate through the elements of v1 and v2, and adding them together, one element at a time, we enjoy the benefits of SIMD, which performs all 4 additions in parallel, at the same time.\nTherefore, the @Vector structure is essentially the Zig representation of SIMD vector objects. The elements in these vector objects will be operated in parallel, if, and only if your current CPU model supports SIMD operations. If your CPU model does not have support for SIMD, then, the @Vector structure will likely produce a similar performance from a “for loop solution”.\n\n17.2.1 Transforming arrays into vectors\nThere are different ways to transform a normal array into a vector object. You can either use implicit conversion (which is when you assign the array to a vector object directly), or, use slices to create a vector object from a normal array.\nIn the example below, we are implicitly converting the array a1 into a vector object (v1) of length 4. We first explicitly annotate the data type of the vector object, and then, we assign the array object to this vector object.\nAlso notice in the example below, that a second vector object (v2) is also created by taking a slice of the array object (a1), and then, storing the pointer to this slice (.*) into this vector object.\n\nconst a1 = [4]u32{4, 12, 37, 9};\nconst v1: @Vector(4, u32) = a1;\nconst v2: @Vector(2, u32) = a1[1..3].*;\n_ = v1; _ = v2;\n\nIt’s worth emphasizing that only arrays and slices whose sizes are compile-time known can be transformed into vectors. Vectors in general are structures that work only with compile-time known sizes. Therefore, if you have an array whose size is runtime known, then, you first need to copy it into an array with a compile-time known size, before transforming it into a vector.\n\n\n17.2.2 The @splat() function\nYou can use the @splat() built-in function to create a vector object that is filled with the same value across all of its elements. This function was created to offer a quick and easy way to directly convert a scalar value (a.k.a. a single value, like a single character, or a single integer, etc.) into a vector object.\nThus, we can use @splat() to convert a single value, like the integer 16 into a vector object of length 1. But we can also use this function to convert the same integer 16 into a vector object of length 10, that is filled with 10 16 values. The example below demonstrates this idea.\n\nconst v1: @Vector(10, u32) = @splat(16);\ntry stdout.print(\"{any}\\n\", .{v1});\n\n{ 16, 16, 16, 16, 16, 16, 16, 16, 16, 16 }\n\n\n\n\n17.2.3 Careful with vectors that are too big\nAs I described in Section 17.2, each vector object is usually a small block of 128, 256 or 512 bits. This means that a vector object is usually small in size, and when you try to go in the opposite direction, by creating a vector object that is very big in size (i.e., sizes that are close to \\(2^{20}\\)), you usually end up with crashes and loud errors from the compiler.\nFor example, if you try to compile the program below, you will likely face segmentation faults, or LLVM errors during the build process. Just be careful to not create vector objects that are too big in size.\n\nconst v1: @Vector(1000000, u32) = @splat(16);\n_ = v1;\n\nSegmentation fault (core dumped)",
     "crumbs": [
       "<span class='chapter-number'>17</span>  <span class='chapter-title'>Introducing Vectors and SIMD</span>"
     ]

From bf90d36c6e29ce0409cc7fc6d5088159a2033ef7 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sat, 8 Mar 2025 09:49:10 -0300
Subject: [PATCH 114/151] Fix references to socket

---
 Chapters/04-http-server.qmd                            | 10 +++++-----
 .../Chapters/04-http-server/execute-results/html.json  |  4 ++--
 docs/Chapters/04-http-server.html                      |  9 +++++----
 docs/index.html                                        |  4 ++--
 docs/search.json                                       |  4 ++--
 5 files changed, 16 insertions(+), 15 deletions(-)

diff --git a/Chapters/04-http-server.qmd b/Chapters/04-http-server.qmd
index 06e115e6..3f8a5247 100644
--- a/Chapters/04-http-server.qmd
+++ b/Chapters/04-http-server.qmd
@@ -122,10 +122,10 @@ But I will describe the theory behind the necessary steps to create
 such HTTP server in C.
 
 
-In essence, we normally implement a HTTP server in C by using WebSocket technology,
+In essence, we normally implement a HTTP server in C by using a TCP socket,
 which involves the following steps:
 
-1. Create a socket object.
+1. Create a TCP socket object.
 1. Bind a name (or more specifically, an address) to this socket object.
 1. Make this socket object to start listening and waiting for incoming connections.
 1. When a connection arrive, we accept this connection, and we exchange the HTTP messages (HTTP Request and HTTP Response).
@@ -143,8 +143,8 @@ That is what the "bind" operation do. It binds a name (or more specifically, an
 this socket object, or, this channel of communication, so that it becomes available,
 or, accessible through this address. While the "listen" operation makes the socket object to
 listen for incoming connections in this address. In other words, the "listen" operation
-makes the socket to wait for incoming connections.
-currently
+makes the socket wait for incoming connections.
+
 Now, when a client actually attempts to connect to the server through the socket address
 that we have specified, in order to establish this connection with the client,
 the socket object needs to accept this incoming connection. Thus, when we
@@ -164,7 +164,7 @@ Let's begin with creating the socket object for our server.
 Just to make things shorter, I will create this socket object in
 a separate Zig module. I will name it `config.zig`.
 
-In Zig, we can create a web socket using
+In Zig, we can create a TCP socket using
 the `std.posix.socket()` function, from the Zig Standard Library.
 As I mentioned earlier in @sec-http-how-impl, every socket object that we create
 represents a communication channel, and we need to bind this channel to a specific address.
diff --git a/_freeze/Chapters/04-http-server/execute-results/html.json b/_freeze/Chapters/04-http-server/execute-results/html.json
index 09b85ed5..b09291c7 100644
--- a/_freeze/Chapters/04-http-server/execute-results/html.json
+++ b/_freeze/Chapters/04-http-server/execute-results/html.json
@@ -1,8 +1,8 @@
 {
-  "hash": "d35b08ad233c0b9a03e30bed4b1982f2",
+  "hash": "f64c88659b4b19943ce530d1245b8add",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 2 - Building a HTTP Server from scratch\n\nIn this chapter, I want to implement a new\nsmall project with you. This time, we are going\nto implement a basic HTTP Server from scratch.\n\nThe Zig Standard Library already have a HTTP Server\nimplemented, which is available at `std.http.Server`.\nBut again, our objective here in this chapter, is to implement\nit **from scratch**. So we can't use this server object available\nfrom the Zig Standard Library.\n\n## What is a HTTP Server?\n\nFirst of all, what is a HTTP Server?\nA HTTP server, as any other type of server, is essentially\na program that runs indefinitely, on an infinite loop, waiting for incoming connections\nfrom clients. Once the server receives an incoming connection, it will\naccept this connection, and it will send messages back-and-forth to the client\nthrough this connection.\n\nBut the messages that are transmitted inside this connection are in a\nspecific format. They are HTTP messages\n(i.e., messages that use the HTTP Protocol specification).\nThe HTTP Protocol is the backbone of the modern web.\nThe world wide web as we know it today, would not exist without the\nHTTP Protocol.\n\nSo, Web servers (which is just a fancy name to\nHTTP Servers) are servers that exchange HTTP messages with clients.\nAnd these HTTP servers and the HTTP Protocol specification\nare essential to the operation of the world wide web today.\n\nThat is the whole picture of the process.\nAgain, we have two subjects involved here, a server (which is\na program that is running indefinitely, waiting to receive incoming connections),\nand a client (which is someone that wants to connect to the server,\nand exchange HTTP messages with it).\n\nYou may find the material about the [HTTP Protocol available at the Mozilla MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview)[^mdn-http]\n, a great resource for you to also look at. It gives you a great overview on how\nHTTP works, and what role the server plays in this matter.\n\n[^mdn-http]: <https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview>.\n\n\n## How a HTTP Server works? {#sec-how-http-works}\n\nImagine a HTTP Server as if it were the receptionist of a large hotel. In a hotel,\nyou have a reception, and inside that reception there is a receptionist\nwaiting for customers to arrive. A HTTP Server is essentially a receptionist\nthat is indefinitely waiting for new customers (or, in the context of HTTP, new clients)\nto arrive in the hotel.\n\nWhen a customer arrives at the hotel, that customer starts a conversation with the\nreceptionist. He tells the receptionist how many days he wants to stay at the hotel.\nThen, the receptionist search for an available apartment. If there is an available apartment\nat the moment, the customer pays the hotel fees, then, he gets the keys to the apartment,\nand then, he goes to the apartment to rest.\n\nAfter this entire process of dealing with the customer (searching for available apartments,\nreceiving payment, handing over the keys), the receptionist goes back to what he was\ndoing earlier, which is to wait. Wait for new customers to arrive.\n\nThat is, in a nutshell, what a HTTP Server do. It waits for clients to connect to the\nserver. When a client attempts to connect to the server, the server accepts this connection,\nand it starts to exchange messages with the client through this connection.\nThe first message that happens inside this connection is always a message from the client\nto the server. This message is called the *HTTP Request*.\n\nThis HTTP Request is a HTTP message that contains what\nthe client wants from the server. It is literally a request. The client\nthat connected to the server is asking this server to do something for him.\n\nThere are different \"types of request\" that a client can send to a HTTP Server.\nBut the most basic type of request, is when a client ask to the\nHTTP Server to serve (i.e., to send) some specific web page (which is a HTML file) to him.\nWhen you type `google.com` in your web browser, you are essentially sending a HTTP Request to Google's\nHTTP servers. This request is asking these servers to send the Google webpage to you.\n\nNonetheless, when the server receives this first message, the *HTTP Request*, it\nanalyzes this request, to understand: who the client is? What he wants the server to do?\nThis client has provided all the necessary information to perform the action that he\nasked? Etc.\n\nOnce the server understands what the client wants, he simply perform the action\nthat was requested, and, to finish the whole process, the server sends back\na HTTP message to the client, informing if the action performed was successful or not,\nand, at last, the server ends (or closes) the connection with the client.\n\nThis last HTTP message sent from the server to the client, is called the *HTTP Response*.\nBecause the server is responding to the action that was requested by the client.\nThe main objective of this response message is let the client know if the\naction requested was successful or not, before the server closes the connection.\n\n\n## How a HTTP server is normally implemented? {#sec-http-how-impl}\n\nLet's use the C language as an example. There are many materials\nteaching how to write a simple HTTP server in C code, like @jeffrey_http,\nor @nipun_http, or @eric_http.\nHaving this in mind, I will not show C code examples here, because you\ncan find them on the internet.\nBut I will describe the theory behind the necessary steps to create\nsuch HTTP server in C.\n\n\nIn essence, we normally implement a HTTP server in C by using WebSocket technology,\nwhich involves the following steps:\n\n1. Create a socket object.\n1. Bind a name (or more specifically, an address) to this socket object.\n1. Make this socket object to start listening and waiting for incoming connections.\n1. When a connection arrive, we accept this connection, and we exchange the HTTP messages (HTTP Request and HTTP Response).\n1. Then, we simply close this connection.\n\n\nA socket object is essentially a channel of communication.\nYou are creating a channel where people can send messages through.\nWhen you create a socket object, this object is not binded to any particular\naddress. This means that with this object you have a representation of a channel of communication\nin your hands. But this channel is not currently available, or, it is not currently accessible,\nbecause it does not have a known address where you can find it.\n\nThat is what the \"bind\" operation do. It binds a name (or more specifically, an address) to\nthis socket object, or, this channel of communication, so that it becomes available,\nor, accessible through this address. While the \"listen\" operation makes the socket object to\nlisten for incoming connections in this address. In other words, the \"listen\" operation\nmakes the socket to wait for incoming connections.\ncurrently\nNow, when a client actually attempts to connect to the server through the socket address\nthat we have specified, in order to establish this connection with the client,\nthe socket object needs to accept this incoming connection. Thus, when we\naccept an incoming connection, the client and the server become\nconnected to each other, and they can start reading or writing messages into this\nestablished connection.\n\nAfter we receive the HTTP Request from the client, analyze it, and send the HTTP Response\nto the client, we can then close the connection, and end this communication.\n\n\n## Implementing the server - Part 1\n\n### Creating the socket object {#sec-create-socket}\n\nLet's begin with creating the socket object for our server.\nJust to make things shorter, I will create this socket object in\na separate Zig module. I will name it `config.zig`.\n\nIn Zig, we can create a web socket using\nthe `std.posix.socket()` function, from the Zig Standard Library.\nAs I mentioned earlier in @sec-http-how-impl, every socket object that we create\nrepresents a communication channel, and we need to bind this channel to a specific address.\nAn \"address\" is defined as an IP address, or, more specifically, an IPv4 address^[It can be also an IPv6 address. But normally, we use a IPv4 address for that.].\nEvery IPv4 address is composed by two components. The first component is the host,\nwhich is a sequence of 4 numbers separated by dot characters (`.`) that identifies the machine used.\nWhile the second component is a port number, which identifies the specific\ndoor, or, the specific port to use in the host machine.\n\nThe sequence of 4 numbers (i.e., the host) identifies the machine (i.e., the computer itself) where\nthis socket will live in. Every computer normally have multiple \"doors\" available inside of him, because\nthis allows the computer to receive and work with multiple connections at the same time.\nHe simply use a single door for each connection. So the port number, is\nessentially a number that identifies the specific door in the computer that will be responsible\nfor receiving the connection. That is, it identifies the \"door\" in the computer that the socket will use\nto receive incoming connections.\n\nTo make things simpler, I will use an IP address that identifies our current machine in this example.\nThis means that, our socket object will reside on the same computer that we are currently using\n(this is also known as the \"localhost\") to write this Zig source code.\n\nBy convention, the IP address that identifies the \"localhost\", which is the current machine we\nare using, is the IP `127.0.0.1`. So, that is the IP\naddress we are going to use in our server. I can declare it in Zig\nby using an array of 4 integers, like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst localhost = [4]u8{ 127, 0, 0, 1 };\n_ = localhost;\n```\n:::\n\n\n\n\nNow, we need to decide which port number to use. By convention, there are some\nport numbers that are reserved, meaning that, we cannot use them for our own\npurposes, like the port 22 (which is normally used for SSH connections).\nFor TCP connections, which is our case here,\na port number is a 16-bit unsigned integer (type `u16` in Zig),\nthus ranging from 0 to 65535 [@wikipedia_port].\nSo, we can choose\na number from 0 to 65535 for our port number. In the\nexample of this book, I will use the port number 3490\n(just a random number).\n\n\nNow that we have these two informations at hand, I can\nfinally create our socket object, using the `std.posix.socket()` function.\nFirst, we use the host and the port number to create an `Address` object,\nwith the `std.net.Address.initIp4()` function, like in the example below.\nAfter that, I use this address object inside the `socket()` function\nto create our socket object.\n\nThe `Socket` struct defined below summarizes all the logic behind\nthis process. In this struct, we have two data members, which are:\n1)  the address object; 2) and a stream object, which is\nthe object we will use to read and write the messages into any connection we establish.\n\nNotice that, inside the constructor method of this struct,\nwhen we create the socket object, we are using the `IPROTO.TCP` property as an input to\ntell the function to create a socket for TCP connections.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\nconst net = @import(\"std\").net;\n\npub const Socket = struct {\n    _address: std.net.Address,\n    _stream: std.net.Stream,\n\n    pub fn init() !Socket {\n        const host = [4]u8{ 127, 0, 0, 1 };\n        const port = 3490;\n        const addr = net.Address.initIp4(host, port);\n        const socket = try std.posix.socket(\n            addr.any.family,\n            std.posix.SOCK.STREAM,\n            std.posix.IPPROTO.TCP\n        );\n        const stream = net.Stream{ .handle = socket };\n        return Socket{ ._address = addr, ._stream = stream };\n    }\n};\n```\n:::\n\n\n\n\n\n### Listening and receiving connections\n\nRemember that we stored the `Socket` struct\ndeclaration that we built in @sec-create-socket inside a Zig module named `config.zig`.\nThis is why I imported this module into our main module (`main.zig`) in the example below, as the `SocketConf` object,\nto access the `Socket` struct.\n\nOnce we created our socket object, we can focus now on making this socket object\nlisten and receive new incoming connections. We do that, by calling the `listen()`\nmethod from the `Address` object that is contained inside the socket object, and then,\nwe call the `accept()` method over the result.\n\nThe `listen()` method from the `Address` object produces a server object,\nwhich is an object that will stay open and running indefinitely, waiting\nto receive an incoming connection. Therefore, if you try to run the code\nexample below, by calling the `run` command from the `zig` compiler,\nyou will notice that the programs keeps running indefinitely,\nwithout a clear end.\n\nThis happens, because the program is waiting for something to happen.\nIt's waiting for someone to try to connect to the address (`http://127.0.0.1:3490`) where\nthe server is running and listening for incoming connections. This is what\nthe `listen()` method do, it makes the socket to be active waiting for someone\nto connect.\n\nOn the other side, the `accept()` method is the function that establishes the connection\nwhen someone tries to connect to the socket. This means that, the `accept()` method\nreturns a new connection object as a result. And you can use this connection object\nto read or write messages from or to the client.\nFor now, we are not doing anything with this connection object.\nBut we are going to use it in the next section.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n    _ = connection;\n}\n```\n:::\n\n\n\n\nThis code example allows one single connection. In other words, the\nserver will wait for one incoming connection, and as soon as the\nserver is done with this first connection that it establishes, the\nprogram ends, and the server stops.\n\nThis is not the norm in the real world. Most people that write\na HTTP server like this, usually put the `accept()` method\ninside a `while` (infinite) loop, where if a connection\nis created with `accept()`, a new thread of execution is created to deal with\nthis new connection and the client. That is, real-world examples of HTTP Servers\nnormally rely on parallel computing to work.\n\nWith this design, the server simply accepts the connection,\nand the whole process of dealing with the client, and receiving\nthe HTTP Request, and sending the HTTP Response, all of this\nis done in the background, on a separate execution thread.\n\nSo, as soon as the server accepts the connection, and creates\nthe separate thread, the server goes back to what he was doing earlier,\nwhich is to wait indefinitely for a new connection to accept.\nHaving this in mind, the code example exposed above, is a\nserver that serves only a single client. Because the program\nterminates as soon as the connection is accepted.\n\n\n\n### Reading the message from the client {#sec-read-http-message}\n\nNow that we have a connection established, i.e., the connection\nobject that we created through the `accept()` function, we can now\nuse this connection object to read any messages that the client\nsend to our server. But we can also use it to send messages back\nto the client.\n\nThe basic idea is, if we **write** any data into this connection object,\nthen, we are sending data to the client, and if we **read** the data present in\nthis connection object, then, we are reading any data that the\nclient sent to us, through this connection object. So, just\nhave this logic in mind. \"Read\" is for reading messages from the client,\nand \"write\" is to send a message to the client.\n\nRemember from @sec-how-http-works that, the first thing that we need to do is to read the HTTP Request\nsent by the client to our server. Because it is the first message that happens\ninside the established connection, and, as a consequence, it is the first\nthing that we need to deal with.\n\nThat is why, I'm going to create a new Zig module in this small project, named `request.zig`\nto keep all functions related to the HTTP Request\ntogether. Then, I will create a new function named `read_request()` that will\nuse our connection object to read the message sent by the client,\nwhich is the HTTP Request.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Connection = std.net.Server.Connection;\npub fn read_request(conn: Connection,\n                    buffer: []u8) !void {\n    const reader = conn.stream.reader();\n    _ = try reader.read(buffer);\n}\n```\n:::\n\n\n\n\n\nThis function accepts a slice object which behaves as a buffer.\nThe `read_request()` function reads the message sent into\nthe connection object, and saves this message into this buffer object that\nwe have provided as input.\n\nNotice that I'm using the connection object that we created to read\nthe message from the client. I first access the `reader` object that lives inside the\nconnection object. Then, I call the `read()` method of this `reader` object\nto effectively read and save the data sent by the client into the buffer object\nthat we created earlier. I'm discarding the return value\nof the `read()` method, by assigning it to the underscore character (`_`),\nbecause this return value is not useful for us right now.\n\n\n\n## Looking at the current state of the program\n\n\nI think now is a good time to see how our program is currently working. Shall we?\nSo, the first thing I will do is to update the `main.zig` module in our small Zig project,\nso that the `main()` function call this new `read_request()` function that we have just created.\nI will also add a print statement at the end of the `main()` function,\njust so that you can see what the HTTP Request that we have just loaded into the buffer object\nlooks like.\n\nAlso, I'm creating the buffer object in the `main()` function, which will be\nresponsible for storing the message sent by the client, and, I'm also\nusing a `for` loop to initialize all fields of this buffer object to the number zero.\nThis is important to make sure that we don't have uninitialized memory in\nthis object. Because uninitialized memory may cause undefined behaviour in our program.\n\nSince the `read_request()` function should receive as input the buffer object as a slice object (`[]u8`),\nI am using the syntax `array[0..array.len]` to get access to a slice of this `buffer` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    _ = try Request.read_request(\n        connection, buffer[0..buffer.len]\n    );\n    try stdout.print(\"{s}\\n\", .{buffer});\n}\n```\n:::\n\n\n\n\nNow, I'm going to execute this program, with the `run` command from the\n`zig` compiler. But remember, as we sad earlier, as soon as I execute this program, it will\nhang indefinitely, because the program is waiting for a client trying to\nconnect to the server.\n\nMore specifically, the program will pause at the line\nwith the `accept()` call. As soon as a client try to connect to the\nserver, then, the execution will \"unpause\", and the `accept()` function\nwill finally be executed to create the\nconnection object that we need, and the remaining of the program\nwill run.\n\nYou can see that in @fig-print-zigrun1. The message `Server Addr: 127.0.0.1:3490`\nis printed to the console, and the program is now waiting for an incoming connection.\n\n![A screenshot of running the program](./../Figures/print-zigrun1.png){#fig-print-zigrun1}\n\n\nWe can finally try to connect to this server, and there are several ways we can do this.\nFor example, we could use the following Python script:\n\n```python\nimport requests\nrequests.get(\"http://127.0.0.1:3490\")\n```\n\nOr, we could also open any web browser of our preference, and type\nthe URL `localhost:3490`. OBS: `localhost` is the same thing as the\nIP `127.0.0.1`. When you press enter, and your web browser go\nto this address, first, the browser will probably print a message\nsaying that \"this page isn't working\", and, then, it will\nprobably change to a new message saying that \"the site can't be\nreached\".\n\nYou get these \"error messages\" in the web browser, because\nit got no response back from the server. In other words, when the web\nbrowser connected to our server, it did send the HTTP Request through the established connection.\nThen, the web browser was expecting to receive a HTTP Response back, but\nit got no response from the server (we didn't implemented the HTTP Response logic yet).\n\nBut that is okay. We have achieved the result that we wanted for now,\nwhich is to connect to the server, and see the HTTP Request\nthat was sent by the web browser (or by the Python script)\nto the server.\n\nIf you comeback to the console that you left open\nwhen you have executed the program, you will see that the\nprogram finished its execution, and, a new message is\nprinted in the console, which is the actual HTTP Request\nmessage that was sent by the web browser to the server.\nYou can see this message in @fig-print-zigrun2.\n\n![A screenshot of the HTTP Request sent by the web browser](./../Figures/print-zigrun2.png){#fig-print-zigrun2}\n\n\n\n\n## Learning about Enums in Zig {#sec-enum}\n\nEnums structures are available in Zig through the `enum` keyword.\nAn enum (short for \"enumeration\") is a special structure that represents a group of constant values.\nSo, if you have a variable which can assume a short and known\nset of values, you might want to associate this variable to an enum structure,\nto make sure that this variable only assumes a value from this set.\n\nA classic example for enums are primary colors. If for some reason, your program\nneeds to represent one of the primary colors, you can create an enum\nthat represents one of these colors.\nIn the example below, we are creating the enum `PrimaryColorRGB`, which\nrepresents a primary color from the RGB color system. By using this enum,\nI am guaranteed that the `acolor` object for example, will contain\none of these three values: `RED`, `GREEN` or `BLUE`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst PrimaryColorRGB = enum {\n    RED, GREEN, BLUE\n};\nconst acolor = PrimaryColorRGB.RED;\n_ = acolor;\n```\n:::\n\n\n\n\nIf for some reason, my code tries to save in `acolor`,\na value that is not in this set, I will get an error message\nwarning me that a value such as \"MAGENTA\" do not exist\ninside the `PrimaryColorRGB` enum.\nThen I can easily fix my mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst acolor = PrimaryColorRGB.MAGENTA;\n```\n:::\n\n\n\n\n```\ne1.zig:5:36: error: enum 'PrimaryColorRGB' has\n        no member named 'MAGENTA':\n    const acolor = PrimaryColorRGB.MAGENTA;\n                                   ^~~~~~~\n```\n\nBehind the hood, enums in Zig work the same way that enums\nwork in C. Each enum value is essentially represented as an integer.\nThe first value in the set is represented as zero,\nthen, the second value is one, ... etc.\n\nOne thing that we are going to learn in the next section is that\nenums can have methods in them. Wait... What? This is amazing!\nYes, enums in Zig are similar to structs, and they can have\nprivate and public methods inside them.\n\n\n\n\n\n\n\n## Implementing the server - Part 2\n\nNow, on this section, I want to focus on parsing\nthe HTTP Request that we received from the client.\nHowever, to effectively parse a HTTP Request message, we first need to understand its\nstructure.\nIn summary, a HTTP Request is a text message that is divided into 3 different\nsections (or parts):\n\n- The top-level header indicating the method of the HTTP Request, the URI, and the HTTP version used in the message.\n- A list of HTTP Headers.\n- The body of the HTTP Request.\n\n### The top-level header\n\nThe first line of text in a HTTP Request always come with the three most essential\ninformation about the request. These three key attributes of the HTTP Request\nare separated by a simple space in this first line of the request.\nThe first information is the HTTP method that is being\nused in the request, second, we have the URI to which this HTTP Request is being sent to,\nand third, we have the version of the HTTP protocol that is being used in this HTTP Request.\n\nIn the snippet below, you can find an example of this first line in a HTTP Request.\nFirst, we have the HTTP method of this request (`GET`). Many programmers\nrefer to the URI component (`/users/list`) as the \"API endpoint\" to which the HTTP Request\nis being sent to. In the context of this specific request, since it's a GET request,\nyou could also say that the URI component is the path to the resource we want to access,\nor, the path to the document (or the file) that we want to retrieve from the server.\n\n```\nGET /users/list HTTP/1.1\n```\n\nAlso, notice that this HTTP Request is using the version 1.1 of the HTTP protocol,\nwhich is the most popular version of the protocol used in the web.\n\n\n\n### The list of HTTP headers\n\nMost HTTP Requests also include a section of HTTP Headers,\nwhich is just a list of attributes or key-value pairs associated with this\nparticular request. This section always comes right after the \"top-level header\" of the request.\n\nFor our purpose in this chapter, which is to build a simple HTTP Server,\nwe are going to ignore this section of the HTTP Request, for simplicity.\nBut most HTTP servers that exist in the wild parses and use these\nHTTP headers to change the way that the server responds to the request\nsent by the client.\n\nFor example, many requests we encounter in the real-world comes with\na HTTP header called `Accept`. In this header, we find a list of [MIME types](https://en.wikipedia.org/wiki/Media_type)[^mime].\nThis list indicates the file formats that the client can read, or parse, or interpret.\nIn other words, you also interpret this header as the client saying the following phrase\nto the server: \"Hey! Look, I can read only HTML documents, so please, send me back\na document that is in a HTML format.\".\n\n[^mime]: <https://en.wikipedia.org/wiki/Media_type>.\n\nIf the HTTP server can read and use this `Accept` header, then, the server can identify\nwhich is the best file format for the document to be sent to the client. Maybe the HTTP server have\nthe same document in multiple formats, for example, in JSON, in XML, in HTML and in PDF,\nbut the client can only understand documents in the HTML format. That is the purpose\nof this `Accept` header.\n\n\n### The body\n\nThe body comes after the list of HTTP headers, and it's an optional section of the HTTP Request, meaning that, not\nall HTTP Requests will come with a body in them. For example, every HTTP Request that uses the\nGET method usually does not come with a body.\n\nBecause a GET request is used to request data, instead of sending it to the server.\nSo, the body section is more related to the POST method, which is a method that involves\nsending data to the server, to be processed and stored.\n\nSince we are going to support only the GET method in this project, it means that\nwe also do not need to care about the body of the request.\n\n\n\n### Creating the HTTP Method enum\n\nEvery HTTP Request comes with a explicit method. The method used in a HTTP Request\nis identified by one these words:\n\n- GET;\n- POST;\n- OPTIONS;\n- PATCH;\n- DELETE;\n- and some other methods.\n\nEach HTTP method is used for a specific type of task. The POST method for example is normally\nused to post some data into the destination. In other words, it's used\nto send some data to the HTTP server, so that it can be processed and stored by the server.\n\nAs another example, the GET method is normally used to get content from the server.\nIn other words, we use this method whenever we want the server to send some\ncontent back to us. It can be any type of content. It can be a web page,\na document file, or some data in a JSON format.\n\nWhen a client sends a POST HTTP Request, the HTTP Response sent by the server normally have the sole purpose of\nletting the client know if the server processed and stored the data successfully.\nIn contrast, when the server receives a GET HTTP Request, then, the server sends the content\nthat the client asked for in the HTTP Response itself. This demonstrates that the method associated\nwith the HTTP Request changes a lot on the dynamics and the roles that each party\nplays in the whole process.\n\nSince the HTTP method of the HTTP Request is identified by this very small and specific\nset of words, it would be interesting to create an enum structure to represent a HTTP method.\nThis way, we can easily check if the HTTP Request we receive from the client is a\nHTTP method that we currently support in our small HTTP server project.\n\nThe `Method` structure below represents this enumeration.\nNotice that, for now, only the GET HTTP method is included in this\nenumeration. Because, for the purpose of this chapter, I want to\nimplement only the GET HTTP method. That is why I am not\nincluding the other HTTP methods in this enumeration.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const Method = enum {\n    GET\n};\n```\n:::\n\n\n\n\n\nNow, I think we should add two methods to this enum structure. One method is `is_supported()`,\nwhich will be a function that returns a boolean value, indicating if the input HTTP method is supported\nor not by our HTTP Server. The other is `init()`, which is a constructor function that takes a string as input,\nand tries to convert it into a `Method` value.\n\n\nBut in order to build these functions, I will use a functionality from the Zig Standard Library, called\n`StaticStringMap()`. This function allows us to create a simple map from strings to enum values.\nIn other words, we can use this map structure to map a string to the respective enum value.\nTo some extent, this specific structure from the standard library works almost like a \"hashtable\" structure,\nand it's optimized for small sets of words, or, small sets of keys, which is our case here.\nWe are going to talk more about hashtables in Zig in @sec-maps-hashtables.\n\nTo use this \"static string map\" structure, you have to import it from the `std.static_string_map` module\nof the Zig Standard Library. Just to make things shorter and easier to type, I am going to import this\nfunction through a different and shorter name (`Map`).\n\nWith `Map()` imported, we can just apply this function over the enum structure\nthat we are going to use in the resulting map. In our case here, it's the `Method` enum structure\nthat we declared at the last code example. Then, I call the `initComptime()` method with the\nmap, i.e., the list of key-value pairs that we are going to use.\n\nYou can see in the example below that I wrote this map using multiple anonymous struct literals.\nInside the first (or \"top-level\") struct literal, we have a list (or a sequence) of struct literals.\nEach struct literal in this list represents a separate key-value pair. The first element (or the key)\nin each key-value pair should always be a string value. While the second element should\nbe a value from the enum structure that you have used inside the `Map()` function.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Map = std.static_string_map.StaticStringMap;\nconst MethodMap = Map(Method).initComptime(.{\n    .{ \"GET\", Method.GET },\n});\n```\n:::\n\n\n\n\nTherefore, the `MethodMap` object is basically a `std::map` object from C++, or,\na `dict` object from Python. You can retrieve (or get) the enum value that\ncorresponds to a particular key, by using the `get()` method from the map\nobject. This method returns an optional value, so, the `get()` method might\nresult in a null value.\n\nWe can use this in our advantage to detect if a particular HTTP method is\nsupported or not in our HTTP server. Because, if the `get()` method returns null,\nit means that it did not found the method that we provided inside the `MethodMap` object, and,\nas a consequence, this method is not supported by our HTTP server.\n\nThe `init()` method below, takes a string value as input, and then, it simply passes this string value\nto the `get()` method of our `MethodMap` object. As consequence, we should get the enum value that corresponds\nto this input string.\n\nNotice in the example below that, the `init()` method returns either an error\n(which might happen if the `?` method returns `unreacheable`, checkout @sec-null-handling for more details)\nor a `Method` object as result. Since `GET` is currently the only value in our `Method` enum\nstructure, it means that, the `init()` method will most likely return the value `Method.GET` as result.\n\nAlso notice that, in the `is_supported()` method, we are using the optional value returned\nby the `get()` method from our `MethodMap` object. The if statement unwraps the optional value\nreturned by this method, and returns `true` in case this optional value is a not-null value.\nOtherwise, it simply returns `false`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const Method = enum {\n    GET,\n    pub fn init(text: []const u8) !Method {\n        return MethodMap.get(text).?;\n    }\n    pub fn is_supported(m: []const u8) bool {\n        const method = MethodMap.get(m);\n        if (method) |_| {\n            return true;\n        }\n        return false;\n    }\n};\n```\n:::\n\n\n\n\n\n\n\n\n\n\n### Writing the parse request function\n\nNow that we created the enum that represents our HTTP method,\nwe should start to write the function responsible for\nactually parsing the HTTP Request.\n\nThe first thing we can do, is to write a struct to represent the HTTP Request.\nTake the `Request` struct below as an example. It contains the three\nessential information from the \"top-level\" header (i.e., the first line)\nin the HTTP Request.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Request = struct {\n    method: Method,\n    version: []const u8,\n    uri: []const u8,\n    pub fn init(method: Method,\n                uri: []const u8,\n                version: []const u8) Request {\n        return Request{\n            .method = method,\n            .uri = uri,\n            .version = version,\n        };\n    }\n};\n```\n:::\n\n\n\n\n\nThe `parse_request()` function should receive a string as input. This input string\ncontains the entire HTTP Request message, and the parsing function should\nread and understand the individual parts of this message.\n\nNow, remember that for the purpose of this chapter, we care only about the first\nline in this message, which contains the \"top-level header\", or, the three essential attributes about the HTTP Request,\nwhich are the HTTP method used, the URI and the HTTP version.\n\nNotice that I use the function `indexOfScalar()` in `parse_request()`. This function from the\nZig Standard Library returns the first index where the scalar value that we provide\nhappens in a string. In this case, I'm looking at the first occurrence of the new line character (`\\n`).\nBecause once again, we care only about the first line in the HTTP Request message.\nThis is the line where we have the three information that we want to parse\n(version of HTTP, the HTTP method and the URI).\n\nTherefore, we are using this `indexOfScalar()` function\nto limit our parsing process to the first line in the message.\nIt's also worth mentioning that, the `indexOfScalar()` function returns an optional value.\nThat is why I use the `orelse` keyword to provide an alternative value, in case\nthe value returned by the function is a null value.\n\nSince each of these three attributes are separated by a simple space, we\ncould use the function `splitScalar()` from the Zig Standard Library to split\nthe input string into sections by looking for every position that appears\na simple space. In other words, this `splitScalar()` function is equivalent\nto the `split()` method in Python, or, the `std::getline()` function from C++,\nor the `strtok()` function in C.\n\nWhen you use this `splitScalar()` function, you get an iterator as the result.\nThis iterator have a `next()` method that you can use to advance the iterator\nto the next position, or, to the next section of the splitted string.\nNote that, when you use `next()`, the method not only advances the iterator,\nbut it also returns a slice to the current section of the splitted\nstring as result.\n\nNow, if you want to get a slice to the current section of the splitted\nstring, but not advance the iterator to the next position, you can use\nthe `peek()` method. Both `next()` and `peek()` methods return an optional value, that is\nwhy I use the `?` method to unwrap these optional values.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn parse_request(text: []u8) Request {\n    const line_index = std.mem.indexOfScalar(\n        u8, text, '\\n'\n    ) orelse text.len;\n    var iterator = std.mem.splitScalar(\n        u8, text[0..line_index], ' '\n    );\n    const method = try Method.init(iterator.next().?);\n    const uri = iterator.next().?;\n    const version = iterator.next().?;\n    const request = Request.init(method, uri, version);\n    return request;\n}\n```\n:::\n\n\n\n\n\nAs I described in @sec-zig-strings, strings in Zig are simply arrays of bytes in the language.\nSo, you will find lots of excellent utility functions to work directly with strings\ninside this `mem` module from the Zig Standard Library.\nWe have described some of these useful utility functions already\nin @sec-strings-useful-funs.\n\n\n\n### Using the parse request function\n\nNow that we wrote the function responsible for parsing the HTTP Request,\nwe can add the function call to `parse_request()` in\nthe `main()` function of our program.\n\nAfter that, is a good idea to test once again the state of our program.\nI execute this program again with the `run` command from the `zig` compiler,\nthen, I use my web browser to connect once again to the server through the URL `localhost:3490`, and finally,\nthe end result of our `Request` object is printed to the console.\n\nA quick observation, since I have used the `any` format specifier in the\nprint statement, the data members `version` and `uri` of the `Request`\nstruct were printed as raw integer values. String data being printed\nas integer values is common in Zig, and remember, these integer values are just the decimal representation of\nthe bytes that form the string in question.\n\nIn the result below, the sequence of decimal values 72, 84, 84, 80, 47, 49, 46, 49, and 13,\nare the bytes that form the text \"HTTP/1.1\". And the integer 47, is the decimal value of\nthe character `/`, which represents our URI in this request.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    try Request.read_request(\n        connection, buffer[0..buffer.len]\n    );\n    const request = Request.parse_request(\n        buffer[0..buffer.len]\n    );\n    try stdout.print(\"{any}\\n\", .{request});\n}\n```\n:::\n\n\n\n\n```\nrequest.Request{\n    .method = request.Method.GET,\n    .version = {72, 84, 84, 80, 47, 49, 46, 49, 13},\n    .uri = {47}\n}\n```\n\n\n\n### Sending the HTTP Response to the client\n\nIn this last part, we are going to write the logic responsible for\nsending the HTTP Response from the server to the client. To make things\nsimple, the server in this project will send just a simple web page\ncontaining the text \"Hello world\".\n\nFirst, I create a new Zig module in the project, named `response.zig`.\nIn this module, I will declare just two functions. Each function\ncorresponds to a specific status code in the HTTP Response.\nThe `send_200()` function will send a HTTP Response with status code 200\n(which means \"Success\") to the client. While the `send_404()` function sends a response\nwith status code 404 (which means \"Not found\").\n\nThis is definitely not the most ergonomic and adequate way of handling the\nHTTP Response, but it works for our case here. We are just building toy projects\nin this book after all, therefore, the source code that we write do not need to be perfect.\nIt just needs to work!\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Connection = std.net.Server.Connection;\npub fn send_200(conn: Connection) !void {\n    const message = (\n        \"HTTP/1.1 200 OK\\nContent-Length: 48\"\n        ++ \"\\nContent-Type: text/html\\n\"\n        ++ \"Connection: Closed\\n\\n<html><body>\"\n        ++ \"<h1>Hello, World!</h1></body></html>\"\n    );\n    _ = try conn.stream.write(message);\n}\n\npub fn send_404(conn: Connection) !void {\n    const message = (\n        \"HTTP/1.1 404 Not Found\\nContent-Length: 50\"\n        ++ \"\\nContent-Type: text/html\\n\"\n        ++ \"Connection: Closed\\n\\n<html><body>\"\n        ++ \"<h1>File not found!</h1></body></html>\"\n    );\n    _ = try conn.stream.write(message);\n}\n```\n:::\n\n\n\n\nNotice that both functions receives the connection object as input, and\nuse the `write()` method to write the HTTP Response message directly\ninto this communication channel. As result, the party in the other\nside of the connection (i.e., the client), will receive such message.\n\nMost real-world HTTP Servers will have a single function (or a single struct) to effectively handle\nthe response. It gets the HTTP Request already parsed as input, and then, it tries to build\nthe HTTP Response bit by bit, before the function sends it over the connection.\n\nWe would also have a specialized struct to represent a HTTP Response, and\na lot of methods that would be used to build each part or component of the response object.\nTake the `Response` struct created by the Javascript runtime Bun as an example.\nYou can find this struct in the [`response.zig` module](https://github.com/oven-sh/bun/blob/main/src/bun.js/webcore/response.zig)[^bun-resp]\nin their GitHub project.\n\n[^bun-resp]: <https://github.com/oven-sh/bun/blob/main/src/bun.js/webcore/response.zig>.\n\n\n## The end result\n\nWe can now, update once again our `main()` function to incorporate our new\nfunctions from the `response.zig` module. First, I need to import this module\ninto our `main.zig` module, then, I add the function calls to `send_200()`\nand `send_404()`.\n\nNotice that I'm using if statements to decide which \"response function\" to call,\nbased especially on the URI present in the HTTP Request. If the user asked for\na content (or a document) that is not present in our server, we should respond\nwith a 404 status code. But since we have just a simple HTTP server, with no\nreal documents to send, we can just check if the URI is the root path (`/`)\nor not to decide which function to call.\n\nAlso, notice that I'm using the function `std.mem.eql()` from the Zig Standard Library\nto check if the string from `uri` is equal or not the string `\"/\"`. We have\ndescribed this function already in @sec-strings-useful-funs, so, comeback to\nthat section if you are not familiar yet with this function.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst Response = @import(\"response.zig\");\nconst Method = Request.Method;\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    try Request.read_request(connection, buffer[0..buffer.len]);\n    const request = Request.parse_request(\n        buffer[0..buffer.len]\n    );\n    if (request.method == Method.GET) {\n        if (std.mem.eql(u8, request.uri, \"/\")) {\n            try Response.send_200(connection);\n        } else {\n            try Response.send_404(connection);\n        }\n    }\n}\n```\n:::\n\n\n\n\n\nNow that we adjusted our `main()` function, I can now execute our program, and\nsee the effects of these last changes. First, I execute the program once again, with the\n`run` command of the `zig` compiler. The program will hang, waiting for a client to connect.\n\nThen, I open my web browser, and try to connect to the server again, using the URL `localhost:3490`.\nThis time, instead of getting some sort of an error message from the browser, you will get the message\n\"Hello World\" printed into your web browser. Because this time, the server sended the HTTP Response\nsuccessfully to the web browser, as demonstrated by @fig-print-zigrun3.\n\n\n![The Hello World message sent in the HTTP Response](./../Figures/print-zigrun3.png){#fig-print-zigrun3}\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 2 - Building a HTTP Server from scratch\n\nIn this chapter, I want to implement a new\nsmall project with you. This time, we are going\nto implement a basic HTTP Server from scratch.\n\nThe Zig Standard Library already have a HTTP Server\nimplemented, which is available at `std.http.Server`.\nBut again, our objective here in this chapter, is to implement\nit **from scratch**. So we can't use this server object available\nfrom the Zig Standard Library.\n\n## What is a HTTP Server?\n\nFirst of all, what is a HTTP Server?\nA HTTP server, as any other type of server, is essentially\na program that runs indefinitely, on an infinite loop, waiting for incoming connections\nfrom clients. Once the server receives an incoming connection, it will\naccept this connection, and it will send messages back-and-forth to the client\nthrough this connection.\n\nBut the messages that are transmitted inside this connection are in a\nspecific format. They are HTTP messages\n(i.e., messages that use the HTTP Protocol specification).\nThe HTTP Protocol is the backbone of the modern web.\nThe world wide web as we know it today, would not exist without the\nHTTP Protocol.\n\nSo, Web servers (which is just a fancy name to\nHTTP Servers) are servers that exchange HTTP messages with clients.\nAnd these HTTP servers and the HTTP Protocol specification\nare essential to the operation of the world wide web today.\n\nThat is the whole picture of the process.\nAgain, we have two subjects involved here, a server (which is\na program that is running indefinitely, waiting to receive incoming connections),\nand a client (which is someone that wants to connect to the server,\nand exchange HTTP messages with it).\n\nYou may find the material about the [HTTP Protocol available at the Mozilla MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview)[^mdn-http]\n, a great resource for you to also look at. It gives you a great overview on how\nHTTP works, and what role the server plays in this matter.\n\n[^mdn-http]: <https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview>.\n\n\n## How a HTTP Server works? {#sec-how-http-works}\n\nImagine a HTTP Server as if it were the receptionist of a large hotel. In a hotel,\nyou have a reception, and inside that reception there is a receptionist\nwaiting for customers to arrive. A HTTP Server is essentially a receptionist\nthat is indefinitely waiting for new customers (or, in the context of HTTP, new clients)\nto arrive in the hotel.\n\nWhen a customer arrives at the hotel, that customer starts a conversation with the\nreceptionist. He tells the receptionist how many days he wants to stay at the hotel.\nThen, the receptionist search for an available apartment. If there is an available apartment\nat the moment, the customer pays the hotel fees, then, he gets the keys to the apartment,\nand then, he goes to the apartment to rest.\n\nAfter this entire process of dealing with the customer (searching for available apartments,\nreceiving payment, handing over the keys), the receptionist goes back to what he was\ndoing earlier, which is to wait. Wait for new customers to arrive.\n\nThat is, in a nutshell, what a HTTP Server do. It waits for clients to connect to the\nserver. When a client attempts to connect to the server, the server accepts this connection,\nand it starts to exchange messages with the client through this connection.\nThe first message that happens inside this connection is always a message from the client\nto the server. This message is called the *HTTP Request*.\n\nThis HTTP Request is a HTTP message that contains what\nthe client wants from the server. It is literally a request. The client\nthat connected to the server is asking this server to do something for him.\n\nThere are different \"types of request\" that a client can send to a HTTP Server.\nBut the most basic type of request, is when a client ask to the\nHTTP Server to serve (i.e., to send) some specific web page (which is a HTML file) to him.\nWhen you type `google.com` in your web browser, you are essentially sending a HTTP Request to Google's\nHTTP servers. This request is asking these servers to send the Google webpage to you.\n\nNonetheless, when the server receives this first message, the *HTTP Request*, it\nanalyzes this request, to understand: who the client is? What he wants the server to do?\nThis client has provided all the necessary information to perform the action that he\nasked? Etc.\n\nOnce the server understands what the client wants, he simply perform the action\nthat was requested, and, to finish the whole process, the server sends back\na HTTP message to the client, informing if the action performed was successful or not,\nand, at last, the server ends (or closes) the connection with the client.\n\nThis last HTTP message sent from the server to the client, is called the *HTTP Response*.\nBecause the server is responding to the action that was requested by the client.\nThe main objective of this response message is let the client know if the\naction requested was successful or not, before the server closes the connection.\n\n\n## How a HTTP server is normally implemented? {#sec-http-how-impl}\n\nLet's use the C language as an example. There are many materials\nteaching how to write a simple HTTP server in C code, like @jeffrey_http,\nor @nipun_http, or @eric_http.\nHaving this in mind, I will not show C code examples here, because you\ncan find them on the internet.\nBut I will describe the theory behind the necessary steps to create\nsuch HTTP server in C.\n\n\nIn essence, we normally implement a HTTP server in C by using a TCP socket,\nwhich involves the following steps:\n\n1. Create a TCP socket object.\n1. Bind a name (or more specifically, an address) to this socket object.\n1. Make this socket object to start listening and waiting for incoming connections.\n1. When a connection arrive, we accept this connection, and we exchange the HTTP messages (HTTP Request and HTTP Response).\n1. Then, we simply close this connection.\n\n\nA socket object is essentially a channel of communication.\nYou are creating a channel where people can send messages through.\nWhen you create a socket object, this object is not binded to any particular\naddress. This means that with this object you have a representation of a channel of communication\nin your hands. But this channel is not currently available, or, it is not currently accessible,\nbecause it does not have a known address where you can find it.\n\nThat is what the \"bind\" operation do. It binds a name (or more specifically, an address) to\nthis socket object, or, this channel of communication, so that it becomes available,\nor, accessible through this address. While the \"listen\" operation makes the socket object to\nlisten for incoming connections in this address. In other words, the \"listen\" operation\nmakes the socket wait for incoming connections.\n\nNow, when a client actually attempts to connect to the server through the socket address\nthat we have specified, in order to establish this connection with the client,\nthe socket object needs to accept this incoming connection. Thus, when we\naccept an incoming connection, the client and the server become\nconnected to each other, and they can start reading or writing messages into this\nestablished connection.\n\nAfter we receive the HTTP Request from the client, analyze it, and send the HTTP Response\nto the client, we can then close the connection, and end this communication.\n\n\n## Implementing the server - Part 1\n\n### Creating the socket object {#sec-create-socket}\n\nLet's begin with creating the socket object for our server.\nJust to make things shorter, I will create this socket object in\na separate Zig module. I will name it `config.zig`.\n\nIn Zig, we can create a TCP socket using\nthe `std.posix.socket()` function, from the Zig Standard Library.\nAs I mentioned earlier in @sec-http-how-impl, every socket object that we create\nrepresents a communication channel, and we need to bind this channel to a specific address.\nAn \"address\" is defined as an IP address, or, more specifically, an IPv4 address^[It can be also an IPv6 address. But normally, we use a IPv4 address for that.].\nEvery IPv4 address is composed by two components. The first component is the host,\nwhich is a sequence of 4 numbers separated by dot characters (`.`) that identifies the machine used.\nWhile the second component is a port number, which identifies the specific\ndoor, or, the specific port to use in the host machine.\n\nThe sequence of 4 numbers (i.e., the host) identifies the machine (i.e., the computer itself) where\nthis socket will live in. Every computer normally have multiple \"doors\" available inside of him, because\nthis allows the computer to receive and work with multiple connections at the same time.\nHe simply use a single door for each connection. So the port number, is\nessentially a number that identifies the specific door in the computer that will be responsible\nfor receiving the connection. That is, it identifies the \"door\" in the computer that the socket will use\nto receive incoming connections.\n\nTo make things simpler, I will use an IP address that identifies our current machine in this example.\nThis means that, our socket object will reside on the same computer that we are currently using\n(this is also known as the \"localhost\") to write this Zig source code.\n\nBy convention, the IP address that identifies the \"localhost\", which is the current machine we\nare using, is the IP `127.0.0.1`. So, that is the IP\naddress we are going to use in our server. I can declare it in Zig\nby using an array of 4 integers, like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst localhost = [4]u8{ 127, 0, 0, 1 };\n_ = localhost;\n```\n:::\n\n\n\n\nNow, we need to decide which port number to use. By convention, there are some\nport numbers that are reserved, meaning that, we cannot use them for our own\npurposes, like the port 22 (which is normally used for SSH connections).\nFor TCP connections, which is our case here,\na port number is a 16-bit unsigned integer (type `u16` in Zig),\nthus ranging from 0 to 65535 [@wikipedia_port].\nSo, we can choose\na number from 0 to 65535 for our port number. In the\nexample of this book, I will use the port number 3490\n(just a random number).\n\n\nNow that we have these two informations at hand, I can\nfinally create our socket object, using the `std.posix.socket()` function.\nFirst, we use the host and the port number to create an `Address` object,\nwith the `std.net.Address.initIp4()` function, like in the example below.\nAfter that, I use this address object inside the `socket()` function\nto create our socket object.\n\nThe `Socket` struct defined below summarizes all the logic behind\nthis process. In this struct, we have two data members, which are:\n1)  the address object; 2) and a stream object, which is\nthe object we will use to read and write the messages into any connection we establish.\n\nNotice that, inside the constructor method of this struct,\nwhen we create the socket object, we are using the `IPROTO.TCP` property as an input to\ntell the function to create a socket for TCP connections.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\nconst net = @import(\"std\").net;\n\npub const Socket = struct {\n    _address: std.net.Address,\n    _stream: std.net.Stream,\n\n    pub fn init() !Socket {\n        const host = [4]u8{ 127, 0, 0, 1 };\n        const port = 3490;\n        const addr = net.Address.initIp4(host, port);\n        const socket = try std.posix.socket(\n            addr.any.family,\n            std.posix.SOCK.STREAM,\n            std.posix.IPPROTO.TCP\n        );\n        const stream = net.Stream{ .handle = socket };\n        return Socket{ ._address = addr, ._stream = stream };\n    }\n};\n```\n:::\n\n\n\n\n\n### Listening and receiving connections\n\nRemember that we stored the `Socket` struct\ndeclaration that we built in @sec-create-socket inside a Zig module named `config.zig`.\nThis is why I imported this module into our main module (`main.zig`) in the example below, as the `SocketConf` object,\nto access the `Socket` struct.\n\nOnce we created our socket object, we can focus now on making this socket object\nlisten and receive new incoming connections. We do that, by calling the `listen()`\nmethod from the `Address` object that is contained inside the socket object, and then,\nwe call the `accept()` method over the result.\n\nThe `listen()` method from the `Address` object produces a server object,\nwhich is an object that will stay open and running indefinitely, waiting\nto receive an incoming connection. Therefore, if you try to run the code\nexample below, by calling the `run` command from the `zig` compiler,\nyou will notice that the programs keeps running indefinitely,\nwithout a clear end.\n\nThis happens, because the program is waiting for something to happen.\nIt's waiting for someone to try to connect to the address (`http://127.0.0.1:3490`) where\nthe server is running and listening for incoming connections. This is what\nthe `listen()` method do, it makes the socket to be active waiting for someone\nto connect.\n\nOn the other side, the `accept()` method is the function that establishes the connection\nwhen someone tries to connect to the socket. This means that, the `accept()` method\nreturns a new connection object as a result. And you can use this connection object\nto read or write messages from or to the client.\nFor now, we are not doing anything with this connection object.\nBut we are going to use it in the next section.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n    _ = connection;\n}\n```\n:::\n\n\n\n\nThis code example allows one single connection. In other words, the\nserver will wait for one incoming connection, and as soon as the\nserver is done with this first connection that it establishes, the\nprogram ends, and the server stops.\n\nThis is not the norm in the real world. Most people that write\na HTTP server like this, usually put the `accept()` method\ninside a `while` (infinite) loop, where if a connection\nis created with `accept()`, a new thread of execution is created to deal with\nthis new connection and the client. That is, real-world examples of HTTP Servers\nnormally rely on parallel computing to work.\n\nWith this design, the server simply accepts the connection,\nand the whole process of dealing with the client, and receiving\nthe HTTP Request, and sending the HTTP Response, all of this\nis done in the background, on a separate execution thread.\n\nSo, as soon as the server accepts the connection, and creates\nthe separate thread, the server goes back to what he was doing earlier,\nwhich is to wait indefinitely for a new connection to accept.\nHaving this in mind, the code example exposed above, is a\nserver that serves only a single client. Because the program\nterminates as soon as the connection is accepted.\n\n\n\n### Reading the message from the client {#sec-read-http-message}\n\nNow that we have a connection established, i.e., the connection\nobject that we created through the `accept()` function, we can now\nuse this connection object to read any messages that the client\nsend to our server. But we can also use it to send messages back\nto the client.\n\nThe basic idea is, if we **write** any data into this connection object,\nthen, we are sending data to the client, and if we **read** the data present in\nthis connection object, then, we are reading any data that the\nclient sent to us, through this connection object. So, just\nhave this logic in mind. \"Read\" is for reading messages from the client,\nand \"write\" is to send a message to the client.\n\nRemember from @sec-how-http-works that, the first thing that we need to do is to read the HTTP Request\nsent by the client to our server. Because it is the first message that happens\ninside the established connection, and, as a consequence, it is the first\nthing that we need to deal with.\n\nThat is why, I'm going to create a new Zig module in this small project, named `request.zig`\nto keep all functions related to the HTTP Request\ntogether. Then, I will create a new function named `read_request()` that will\nuse our connection object to read the message sent by the client,\nwhich is the HTTP Request.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Connection = std.net.Server.Connection;\npub fn read_request(conn: Connection,\n                    buffer: []u8) !void {\n    const reader = conn.stream.reader();\n    _ = try reader.read(buffer);\n}\n```\n:::\n\n\n\n\n\nThis function accepts a slice object which behaves as a buffer.\nThe `read_request()` function reads the message sent into\nthe connection object, and saves this message into this buffer object that\nwe have provided as input.\n\nNotice that I'm using the connection object that we created to read\nthe message from the client. I first access the `reader` object that lives inside the\nconnection object. Then, I call the `read()` method of this `reader` object\nto effectively read and save the data sent by the client into the buffer object\nthat we created earlier. I'm discarding the return value\nof the `read()` method, by assigning it to the underscore character (`_`),\nbecause this return value is not useful for us right now.\n\n\n\n## Looking at the current state of the program\n\n\nI think now is a good time to see how our program is currently working. Shall we?\nSo, the first thing I will do is to update the `main.zig` module in our small Zig project,\nso that the `main()` function call this new `read_request()` function that we have just created.\nI will also add a print statement at the end of the `main()` function,\njust so that you can see what the HTTP Request that we have just loaded into the buffer object\nlooks like.\n\nAlso, I'm creating the buffer object in the `main()` function, which will be\nresponsible for storing the message sent by the client, and, I'm also\nusing a `for` loop to initialize all fields of this buffer object to the number zero.\nThis is important to make sure that we don't have uninitialized memory in\nthis object. Because uninitialized memory may cause undefined behaviour in our program.\n\nSince the `read_request()` function should receive as input the buffer object as a slice object (`[]u8`),\nI am using the syntax `array[0..array.len]` to get access to a slice of this `buffer` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    _ = try Request.read_request(\n        connection, buffer[0..buffer.len]\n    );\n    try stdout.print(\"{s}\\n\", .{buffer});\n}\n```\n:::\n\n\n\n\nNow, I'm going to execute this program, with the `run` command from the\n`zig` compiler. But remember, as we sad earlier, as soon as I execute this program, it will\nhang indefinitely, because the program is waiting for a client trying to\nconnect to the server.\n\nMore specifically, the program will pause at the line\nwith the `accept()` call. As soon as a client try to connect to the\nserver, then, the execution will \"unpause\", and the `accept()` function\nwill finally be executed to create the\nconnection object that we need, and the remaining of the program\nwill run.\n\nYou can see that in @fig-print-zigrun1. The message `Server Addr: 127.0.0.1:3490`\nis printed to the console, and the program is now waiting for an incoming connection.\n\n![A screenshot of running the program](./../Figures/print-zigrun1.png){#fig-print-zigrun1}\n\n\nWe can finally try to connect to this server, and there are several ways we can do this.\nFor example, we could use the following Python script:\n\n```python\nimport requests\nrequests.get(\"http://127.0.0.1:3490\")\n```\n\nOr, we could also open any web browser of our preference, and type\nthe URL `localhost:3490`. OBS: `localhost` is the same thing as the\nIP `127.0.0.1`. When you press enter, and your web browser go\nto this address, first, the browser will probably print a message\nsaying that \"this page isn't working\", and, then, it will\nprobably change to a new message saying that \"the site can't be\nreached\".\n\nYou get these \"error messages\" in the web browser, because\nit got no response back from the server. In other words, when the web\nbrowser connected to our server, it did send the HTTP Request through the established connection.\nThen, the web browser was expecting to receive a HTTP Response back, but\nit got no response from the server (we didn't implemented the HTTP Response logic yet).\n\nBut that is okay. We have achieved the result that we wanted for now,\nwhich is to connect to the server, and see the HTTP Request\nthat was sent by the web browser (or by the Python script)\nto the server.\n\nIf you comeback to the console that you left open\nwhen you have executed the program, you will see that the\nprogram finished its execution, and, a new message is\nprinted in the console, which is the actual HTTP Request\nmessage that was sent by the web browser to the server.\nYou can see this message in @fig-print-zigrun2.\n\n![A screenshot of the HTTP Request sent by the web browser](./../Figures/print-zigrun2.png){#fig-print-zigrun2}\n\n\n\n\n## Learning about Enums in Zig {#sec-enum}\n\nEnums structures are available in Zig through the `enum` keyword.\nAn enum (short for \"enumeration\") is a special structure that represents a group of constant values.\nSo, if you have a variable which can assume a short and known\nset of values, you might want to associate this variable to an enum structure,\nto make sure that this variable only assumes a value from this set.\n\nA classic example for enums are primary colors. If for some reason, your program\nneeds to represent one of the primary colors, you can create an enum\nthat represents one of these colors.\nIn the example below, we are creating the enum `PrimaryColorRGB`, which\nrepresents a primary color from the RGB color system. By using this enum,\nI am guaranteed that the `acolor` object for example, will contain\none of these three values: `RED`, `GREEN` or `BLUE`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst PrimaryColorRGB = enum {\n    RED, GREEN, BLUE\n};\nconst acolor = PrimaryColorRGB.RED;\n_ = acolor;\n```\n:::\n\n\n\n\nIf for some reason, my code tries to save in `acolor`,\na value that is not in this set, I will get an error message\nwarning me that a value such as \"MAGENTA\" do not exist\ninside the `PrimaryColorRGB` enum.\nThen I can easily fix my mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst acolor = PrimaryColorRGB.MAGENTA;\n```\n:::\n\n\n\n\n```\ne1.zig:5:36: error: enum 'PrimaryColorRGB' has\n        no member named 'MAGENTA':\n    const acolor = PrimaryColorRGB.MAGENTA;\n                                   ^~~~~~~\n```\n\nBehind the hood, enums in Zig work the same way that enums\nwork in C. Each enum value is essentially represented as an integer.\nThe first value in the set is represented as zero,\nthen, the second value is one, ... etc.\n\nOne thing that we are going to learn in the next section is that\nenums can have methods in them. Wait... What? This is amazing!\nYes, enums in Zig are similar to structs, and they can have\nprivate and public methods inside them.\n\n\n\n\n\n\n\n## Implementing the server - Part 2\n\nNow, on this section, I want to focus on parsing\nthe HTTP Request that we received from the client.\nHowever, to effectively parse a HTTP Request message, we first need to understand its\nstructure.\nIn summary, a HTTP Request is a text message that is divided into 3 different\nsections (or parts):\n\n- The top-level header indicating the method of the HTTP Request, the URI, and the HTTP version used in the message.\n- A list of HTTP Headers.\n- The body of the HTTP Request.\n\n### The top-level header\n\nThe first line of text in a HTTP Request always come with the three most essential\ninformation about the request. These three key attributes of the HTTP Request\nare separated by a simple space in this first line of the request.\nThe first information is the HTTP method that is being\nused in the request, second, we have the URI to which this HTTP Request is being sent to,\nand third, we have the version of the HTTP protocol that is being used in this HTTP Request.\n\nIn the snippet below, you can find an example of this first line in a HTTP Request.\nFirst, we have the HTTP method of this request (`GET`). Many programmers\nrefer to the URI component (`/users/list`) as the \"API endpoint\" to which the HTTP Request\nis being sent to. In the context of this specific request, since it's a GET request,\nyou could also say that the URI component is the path to the resource we want to access,\nor, the path to the document (or the file) that we want to retrieve from the server.\n\n```\nGET /users/list HTTP/1.1\n```\n\nAlso, notice that this HTTP Request is using the version 1.1 of the HTTP protocol,\nwhich is the most popular version of the protocol used in the web.\n\n\n\n### The list of HTTP headers\n\nMost HTTP Requests also include a section of HTTP Headers,\nwhich is just a list of attributes or key-value pairs associated with this\nparticular request. This section always comes right after the \"top-level header\" of the request.\n\nFor our purpose in this chapter, which is to build a simple HTTP Server,\nwe are going to ignore this section of the HTTP Request, for simplicity.\nBut most HTTP servers that exist in the wild parses and use these\nHTTP headers to change the way that the server responds to the request\nsent by the client.\n\nFor example, many requests we encounter in the real-world comes with\na HTTP header called `Accept`. In this header, we find a list of [MIME types](https://en.wikipedia.org/wiki/Media_type)[^mime].\nThis list indicates the file formats that the client can read, or parse, or interpret.\nIn other words, you also interpret this header as the client saying the following phrase\nto the server: \"Hey! Look, I can read only HTML documents, so please, send me back\na document that is in a HTML format.\".\n\n[^mime]: <https://en.wikipedia.org/wiki/Media_type>.\n\nIf the HTTP server can read and use this `Accept` header, then, the server can identify\nwhich is the best file format for the document to be sent to the client. Maybe the HTTP server have\nthe same document in multiple formats, for example, in JSON, in XML, in HTML and in PDF,\nbut the client can only understand documents in the HTML format. That is the purpose\nof this `Accept` header.\n\n\n### The body\n\nThe body comes after the list of HTTP headers, and it's an optional section of the HTTP Request, meaning that, not\nall HTTP Requests will come with a body in them. For example, every HTTP Request that uses the\nGET method usually does not come with a body.\n\nBecause a GET request is used to request data, instead of sending it to the server.\nSo, the body section is more related to the POST method, which is a method that involves\nsending data to the server, to be processed and stored.\n\nSince we are going to support only the GET method in this project, it means that\nwe also do not need to care about the body of the request.\n\n\n\n### Creating the HTTP Method enum\n\nEvery HTTP Request comes with a explicit method. The method used in a HTTP Request\nis identified by one these words:\n\n- GET;\n- POST;\n- OPTIONS;\n- PATCH;\n- DELETE;\n- and some other methods.\n\nEach HTTP method is used for a specific type of task. The POST method for example is normally\nused to post some data into the destination. In other words, it's used\nto send some data to the HTTP server, so that it can be processed and stored by the server.\n\nAs another example, the GET method is normally used to get content from the server.\nIn other words, we use this method whenever we want the server to send some\ncontent back to us. It can be any type of content. It can be a web page,\na document file, or some data in a JSON format.\n\nWhen a client sends a POST HTTP Request, the HTTP Response sent by the server normally have the sole purpose of\nletting the client know if the server processed and stored the data successfully.\nIn contrast, when the server receives a GET HTTP Request, then, the server sends the content\nthat the client asked for in the HTTP Response itself. This demonstrates that the method associated\nwith the HTTP Request changes a lot on the dynamics and the roles that each party\nplays in the whole process.\n\nSince the HTTP method of the HTTP Request is identified by this very small and specific\nset of words, it would be interesting to create an enum structure to represent a HTTP method.\nThis way, we can easily check if the HTTP Request we receive from the client is a\nHTTP method that we currently support in our small HTTP server project.\n\nThe `Method` structure below represents this enumeration.\nNotice that, for now, only the GET HTTP method is included in this\nenumeration. Because, for the purpose of this chapter, I want to\nimplement only the GET HTTP method. That is why I am not\nincluding the other HTTP methods in this enumeration.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const Method = enum {\n    GET\n};\n```\n:::\n\n\n\n\n\nNow, I think we should add two methods to this enum structure. One method is `is_supported()`,\nwhich will be a function that returns a boolean value, indicating if the input HTTP method is supported\nor not by our HTTP Server. The other is `init()`, which is a constructor function that takes a string as input,\nand tries to convert it into a `Method` value.\n\n\nBut in order to build these functions, I will use a functionality from the Zig Standard Library, called\n`StaticStringMap()`. This function allows us to create a simple map from strings to enum values.\nIn other words, we can use this map structure to map a string to the respective enum value.\nTo some extent, this specific structure from the standard library works almost like a \"hashtable\" structure,\nand it's optimized for small sets of words, or, small sets of keys, which is our case here.\nWe are going to talk more about hashtables in Zig in @sec-maps-hashtables.\n\nTo use this \"static string map\" structure, you have to import it from the `std.static_string_map` module\nof the Zig Standard Library. Just to make things shorter and easier to type, I am going to import this\nfunction through a different and shorter name (`Map`).\n\nWith `Map()` imported, we can just apply this function over the enum structure\nthat we are going to use in the resulting map. In our case here, it's the `Method` enum structure\nthat we declared at the last code example. Then, I call the `initComptime()` method with the\nmap, i.e., the list of key-value pairs that we are going to use.\n\nYou can see in the example below that I wrote this map using multiple anonymous struct literals.\nInside the first (or \"top-level\") struct literal, we have a list (or a sequence) of struct literals.\nEach struct literal in this list represents a separate key-value pair. The first element (or the key)\nin each key-value pair should always be a string value. While the second element should\nbe a value from the enum structure that you have used inside the `Map()` function.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Map = std.static_string_map.StaticStringMap;\nconst MethodMap = Map(Method).initComptime(.{\n    .{ \"GET\", Method.GET },\n});\n```\n:::\n\n\n\n\nTherefore, the `MethodMap` object is basically a `std::map` object from C++, or,\na `dict` object from Python. You can retrieve (or get) the enum value that\ncorresponds to a particular key, by using the `get()` method from the map\nobject. This method returns an optional value, so, the `get()` method might\nresult in a null value.\n\nWe can use this in our advantage to detect if a particular HTTP method is\nsupported or not in our HTTP server. Because, if the `get()` method returns null,\nit means that it did not found the method that we provided inside the `MethodMap` object, and,\nas a consequence, this method is not supported by our HTTP server.\n\nThe `init()` method below, takes a string value as input, and then, it simply passes this string value\nto the `get()` method of our `MethodMap` object. As consequence, we should get the enum value that corresponds\nto this input string.\n\nNotice in the example below that, the `init()` method returns either an error\n(which might happen if the `?` method returns `unreacheable`, checkout @sec-null-handling for more details)\nor a `Method` object as result. Since `GET` is currently the only value in our `Method` enum\nstructure, it means that, the `init()` method will most likely return the value `Method.GET` as result.\n\nAlso notice that, in the `is_supported()` method, we are using the optional value returned\nby the `get()` method from our `MethodMap` object. The if statement unwraps the optional value\nreturned by this method, and returns `true` in case this optional value is a not-null value.\nOtherwise, it simply returns `false`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const Method = enum {\n    GET,\n    pub fn init(text: []const u8) !Method {\n        return MethodMap.get(text).?;\n    }\n    pub fn is_supported(m: []const u8) bool {\n        const method = MethodMap.get(m);\n        if (method) |_| {\n            return true;\n        }\n        return false;\n    }\n};\n```\n:::\n\n\n\n\n\n\n\n\n\n\n### Writing the parse request function\n\nNow that we created the enum that represents our HTTP method,\nwe should start to write the function responsible for\nactually parsing the HTTP Request.\n\nThe first thing we can do, is to write a struct to represent the HTTP Request.\nTake the `Request` struct below as an example. It contains the three\nessential information from the \"top-level\" header (i.e., the first line)\nin the HTTP Request.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Request = struct {\n    method: Method,\n    version: []const u8,\n    uri: []const u8,\n    pub fn init(method: Method,\n                uri: []const u8,\n                version: []const u8) Request {\n        return Request{\n            .method = method,\n            .uri = uri,\n            .version = version,\n        };\n    }\n};\n```\n:::\n\n\n\n\n\nThe `parse_request()` function should receive a string as input. This input string\ncontains the entire HTTP Request message, and the parsing function should\nread and understand the individual parts of this message.\n\nNow, remember that for the purpose of this chapter, we care only about the first\nline in this message, which contains the \"top-level header\", or, the three essential attributes about the HTTP Request,\nwhich are the HTTP method used, the URI and the HTTP version.\n\nNotice that I use the function `indexOfScalar()` in `parse_request()`. This function from the\nZig Standard Library returns the first index where the scalar value that we provide\nhappens in a string. In this case, I'm looking at the first occurrence of the new line character (`\\n`).\nBecause once again, we care only about the first line in the HTTP Request message.\nThis is the line where we have the three information that we want to parse\n(version of HTTP, the HTTP method and the URI).\n\nTherefore, we are using this `indexOfScalar()` function\nto limit our parsing process to the first line in the message.\nIt's also worth mentioning that, the `indexOfScalar()` function returns an optional value.\nThat is why I use the `orelse` keyword to provide an alternative value, in case\nthe value returned by the function is a null value.\n\nSince each of these three attributes are separated by a simple space, we\ncould use the function `splitScalar()` from the Zig Standard Library to split\nthe input string into sections by looking for every position that appears\na simple space. In other words, this `splitScalar()` function is equivalent\nto the `split()` method in Python, or, the `std::getline()` function from C++,\nor the `strtok()` function in C.\n\nWhen you use this `splitScalar()` function, you get an iterator as the result.\nThis iterator have a `next()` method that you can use to advance the iterator\nto the next position, or, to the next section of the splitted string.\nNote that, when you use `next()`, the method not only advances the iterator,\nbut it also returns a slice to the current section of the splitted\nstring as result.\n\nNow, if you want to get a slice to the current section of the splitted\nstring, but not advance the iterator to the next position, you can use\nthe `peek()` method. Both `next()` and `peek()` methods return an optional value, that is\nwhy I use the `?` method to unwrap these optional values.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn parse_request(text: []u8) Request {\n    const line_index = std.mem.indexOfScalar(\n        u8, text, '\\n'\n    ) orelse text.len;\n    var iterator = std.mem.splitScalar(\n        u8, text[0..line_index], ' '\n    );\n    const method = try Method.init(iterator.next().?);\n    const uri = iterator.next().?;\n    const version = iterator.next().?;\n    const request = Request.init(method, uri, version);\n    return request;\n}\n```\n:::\n\n\n\n\n\nAs I described in @sec-zig-strings, strings in Zig are simply arrays of bytes in the language.\nSo, you will find lots of excellent utility functions to work directly with strings\ninside this `mem` module from the Zig Standard Library.\nWe have described some of these useful utility functions already\nin @sec-strings-useful-funs.\n\n\n\n### Using the parse request function\n\nNow that we wrote the function responsible for parsing the HTTP Request,\nwe can add the function call to `parse_request()` in\nthe `main()` function of our program.\n\nAfter that, is a good idea to test once again the state of our program.\nI execute this program again with the `run` command from the `zig` compiler,\nthen, I use my web browser to connect once again to the server through the URL `localhost:3490`, and finally,\nthe end result of our `Request` object is printed to the console.\n\nA quick observation, since I have used the `any` format specifier in the\nprint statement, the data members `version` and `uri` of the `Request`\nstruct were printed as raw integer values. String data being printed\nas integer values is common in Zig, and remember, these integer values are just the decimal representation of\nthe bytes that form the string in question.\n\nIn the result below, the sequence of decimal values 72, 84, 84, 80, 47, 49, 46, 49, and 13,\nare the bytes that form the text \"HTTP/1.1\". And the integer 47, is the decimal value of\nthe character `/`, which represents our URI in this request.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    try Request.read_request(\n        connection, buffer[0..buffer.len]\n    );\n    const request = Request.parse_request(\n        buffer[0..buffer.len]\n    );\n    try stdout.print(\"{any}\\n\", .{request});\n}\n```\n:::\n\n\n\n\n```\nrequest.Request{\n    .method = request.Method.GET,\n    .version = {72, 84, 84, 80, 47, 49, 46, 49, 13},\n    .uri = {47}\n}\n```\n\n\n\n### Sending the HTTP Response to the client\n\nIn this last part, we are going to write the logic responsible for\nsending the HTTP Response from the server to the client. To make things\nsimple, the server in this project will send just a simple web page\ncontaining the text \"Hello world\".\n\nFirst, I create a new Zig module in the project, named `response.zig`.\nIn this module, I will declare just two functions. Each function\ncorresponds to a specific status code in the HTTP Response.\nThe `send_200()` function will send a HTTP Response with status code 200\n(which means \"Success\") to the client. While the `send_404()` function sends a response\nwith status code 404 (which means \"Not found\").\n\nThis is definitely not the most ergonomic and adequate way of handling the\nHTTP Response, but it works for our case here. We are just building toy projects\nin this book after all, therefore, the source code that we write do not need to be perfect.\nIt just needs to work!\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Connection = std.net.Server.Connection;\npub fn send_200(conn: Connection) !void {\n    const message = (\n        \"HTTP/1.1 200 OK\\nContent-Length: 48\"\n        ++ \"\\nContent-Type: text/html\\n\"\n        ++ \"Connection: Closed\\n\\n<html><body>\"\n        ++ \"<h1>Hello, World!</h1></body></html>\"\n    );\n    _ = try conn.stream.write(message);\n}\n\npub fn send_404(conn: Connection) !void {\n    const message = (\n        \"HTTP/1.1 404 Not Found\\nContent-Length: 50\"\n        ++ \"\\nContent-Type: text/html\\n\"\n        ++ \"Connection: Closed\\n\\n<html><body>\"\n        ++ \"<h1>File not found!</h1></body></html>\"\n    );\n    _ = try conn.stream.write(message);\n}\n```\n:::\n\n\n\n\nNotice that both functions receives the connection object as input, and\nuse the `write()` method to write the HTTP Response message directly\ninto this communication channel. As result, the party in the other\nside of the connection (i.e., the client), will receive such message.\n\nMost real-world HTTP Servers will have a single function (or a single struct) to effectively handle\nthe response. It gets the HTTP Request already parsed as input, and then, it tries to build\nthe HTTP Response bit by bit, before the function sends it over the connection.\n\nWe would also have a specialized struct to represent a HTTP Response, and\na lot of methods that would be used to build each part or component of the response object.\nTake the `Response` struct created by the Javascript runtime Bun as an example.\nYou can find this struct in the [`response.zig` module](https://github.com/oven-sh/bun/blob/main/src/bun.js/webcore/response.zig)[^bun-resp]\nin their GitHub project.\n\n[^bun-resp]: <https://github.com/oven-sh/bun/blob/main/src/bun.js/webcore/response.zig>.\n\n\n## The end result\n\nWe can now, update once again our `main()` function to incorporate our new\nfunctions from the `response.zig` module. First, I need to import this module\ninto our `main.zig` module, then, I add the function calls to `send_200()`\nand `send_404()`.\n\nNotice that I'm using if statements to decide which \"response function\" to call,\nbased especially on the URI present in the HTTP Request. If the user asked for\na content (or a document) that is not present in our server, we should respond\nwith a 404 status code. But since we have just a simple HTTP server, with no\nreal documents to send, we can just check if the URI is the root path (`/`)\nor not to decide which function to call.\n\nAlso, notice that I'm using the function `std.mem.eql()` from the Zig Standard Library\nto check if the string from `uri` is equal or not the string `\"/\"`. We have\ndescribed this function already in @sec-strings-useful-funs, so, comeback to\nthat section if you are not familiar yet with this function.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst Response = @import(\"response.zig\");\nconst Method = Request.Method;\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    try Request.read_request(connection, buffer[0..buffer.len]);\n    const request = Request.parse_request(\n        buffer[0..buffer.len]\n    );\n    if (request.method == Method.GET) {\n        if (std.mem.eql(u8, request.uri, \"/\")) {\n            try Response.send_200(connection);\n        } else {\n            try Response.send_404(connection);\n        }\n    }\n}\n```\n:::\n\n\n\n\n\nNow that we adjusted our `main()` function, I can now execute our program, and\nsee the effects of these last changes. First, I execute the program once again, with the\n`run` command of the `zig` compiler. The program will hang, waiting for a client to connect.\n\nThen, I open my web browser, and try to connect to the server again, using the URL `localhost:3490`.\nThis time, instead of getting some sort of an error message from the browser, you will get the message\n\"Hello World\" printed into your web browser. Because this time, the server sended the HTTP Response\nsuccessfully to the web browser, as demonstrated by @fig-print-zigrun3.\n\n\n![The Hello World message sent in the HTTP Response](./../Figures/print-zigrun3.png){#fig-print-zigrun3}\n",
     "supporting": [
       "04-http-server_files"
     ],
diff --git a/docs/Chapters/04-http-server.html b/docs/Chapters/04-http-server.html
index 48b876ef..81801ad0 100644
--- a/docs/Chapters/04-http-server.html
+++ b/docs/Chapters/04-http-server.html
@@ -370,16 +370,17 @@ <h2 data-number="7.2" class="anchored" data-anchor-id="sec-how-http-works"><span
 <section id="sec-http-how-impl" class="level2" data-number="7.3">
 <h2 data-number="7.3" class="anchored" data-anchor-id="sec-http-how-impl"><span class="header-section-number">7.3</span> How a HTTP server is normally implemented?</h2>
 <p>Let’s use the C language as an example. There are many materials teaching how to write a simple HTTP server in C code, like <span class="citation" data-cites="jeffrey_http">Yu (<a href="../references.html#ref-jeffrey_http" role="doc-biblioref">2023</a>)</span>, or <span class="citation" data-cites="nipun_http">Weerasiri (<a href="../references.html#ref-nipun_http" role="doc-biblioref">2023</a>)</span>, or <span class="citation" data-cites="eric_http">Meehan (<a href="../references.html#ref-eric_http" role="doc-biblioref">2021</a>)</span>. Having this in mind, I will not show C code examples here, because you can find them on the internet. But I will describe the theory behind the necessary steps to create such HTTP server in C.</p>
-<p>In essence, we normally implement a HTTP server in C by using WebSocket technology, which involves the following steps:</p>
+<p>In essence, we normally implement a HTTP server in C by using a TCP socket, which involves the following steps:</p>
 <ol type="1">
-<li>Create a socket object.</li>
+<li>Create a TCP socket object.</li>
 <li>Bind a name (or more specifically, an address) to this socket object.</li>
 <li>Make this socket object to start listening and waiting for incoming connections.</li>
 <li>When a connection arrive, we accept this connection, and we exchange the HTTP messages (HTTP Request and HTTP Response).</li>
 <li>Then, we simply close this connection.</li>
 </ol>
 <p>A socket object is essentially a channel of communication. You are creating a channel where people can send messages through. When you create a socket object, this object is not binded to any particular address. This means that with this object you have a representation of a channel of communication in your hands. But this channel is not currently available, or, it is not currently accessible, because it does not have a known address where you can find it.</p>
-<p>That is what the “bind” operation do. It binds a name (or more specifically, an address) to this socket object, or, this channel of communication, so that it becomes available, or, accessible through this address. While the “listen” operation makes the socket object to listen for incoming connections in this address. In other words, the “listen” operation makes the socket to wait for incoming connections. currently Now, when a client actually attempts to connect to the server through the socket address that we have specified, in order to establish this connection with the client, the socket object needs to accept this incoming connection. Thus, when we accept an incoming connection, the client and the server become connected to each other, and they can start reading or writing messages into this established connection.</p>
+<p>That is what the “bind” operation do. It binds a name (or more specifically, an address) to this socket object, or, this channel of communication, so that it becomes available, or, accessible through this address. While the “listen” operation makes the socket object to listen for incoming connections in this address. In other words, the “listen” operation makes the socket wait for incoming connections.</p>
+<p>Now, when a client actually attempts to connect to the server through the socket address that we have specified, in order to establish this connection with the client, the socket object needs to accept this incoming connection. Thus, when we accept an incoming connection, the client and the server become connected to each other, and they can start reading or writing messages into this established connection.</p>
 <p>After we receive the HTTP Request from the client, analyze it, and send the HTTP Response to the client, we can then close the connection, and end this communication.</p>
 </section>
 <section id="implementing-the-server---part-1" class="level2" data-number="7.4">
@@ -387,7 +388,7 @@ <h2 data-number="7.4" class="anchored" data-anchor-id="implementing-the-server--
 <section id="sec-create-socket" class="level3" data-number="7.4.1">
 <h3 data-number="7.4.1" class="anchored" data-anchor-id="sec-create-socket"><span class="header-section-number">7.4.1</span> Creating the socket object</h3>
 <p>Let’s begin with creating the socket object for our server. Just to make things shorter, I will create this socket object in a separate Zig module. I will name it <code>config.zig</code>.</p>
-<p>In Zig, we can create a web socket using the <code>std.posix.socket()</code> function, from the Zig Standard Library. As I mentioned earlier in <a href="#sec-http-how-impl" class="quarto-xref"><span>Section 7.3</span></a>, every socket object that we create represents a communication channel, and we need to bind this channel to a specific address. An “address” is defined as an IP address, or, more specifically, an IPv4 address<a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a>. Every IPv4 address is composed by two components. The first component is the host, which is a sequence of 4 numbers separated by dot characters (<code>.</code>) that identifies the machine used. While the second component is a port number, which identifies the specific door, or, the specific port to use in the host machine.</p>
+<p>In Zig, we can create a TCP socket using the <code>std.posix.socket()</code> function, from the Zig Standard Library. As I mentioned earlier in <a href="#sec-http-how-impl" class="quarto-xref"><span>Section 7.3</span></a>, every socket object that we create represents a communication channel, and we need to bind this channel to a specific address. An “address” is defined as an IP address, or, more specifically, an IPv4 address<a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a>. Every IPv4 address is composed by two components. The first component is the host, which is a sequence of 4 numbers separated by dot characters (<code>.</code>) that identifies the machine used. While the second component is a port number, which identifies the specific door, or, the specific port to use in the host machine.</p>
 <p>The sequence of 4 numbers (i.e., the host) identifies the machine (i.e., the computer itself) where this socket will live in. Every computer normally have multiple “doors” available inside of him, because this allows the computer to receive and work with multiple connections at the same time. He simply use a single door for each connection. So the port number, is essentially a number that identifies the specific door in the computer that will be responsible for receiving the connection. That is, it identifies the “door” in the computer that the socket will use to receive incoming connections.</p>
 <p>To make things simpler, I will use an IP address that identifies our current machine in this example. This means that, our socket object will reside on the same computer that we are currently using (this is also known as the “localhost”) to write this Zig source code.</p>
 <p>By convention, the IP address that identifies the “localhost”, which is the current machine we are using, is the IP <code>127.0.0.1</code>. So, that is the IP address we are going to use in our server. I can declare it in Zig by using an array of 4 integers, like this:</p>
diff --git a/docs/index.html b/docs/index.html
index 80cde802..10e83b3b 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -7,7 +7,7 @@
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 <meta name="author" content="Pedro Duarte Faria">
-<meta name="dcterms.date" content="2025-03-06">
+<meta name="dcterms.date" content="2025-03-08">
 
 <title>Introduction to Zig</title>
 <style>
@@ -287,7 +287,7 @@ <h1 class="title">Introduction to Zig</h1>
     <div>
     <div class="quarto-title-meta-heading">Published</div>
     <div class="quarto-title-meta-contents">
-      <p class="date">March 6, 2025</p>
+      <p class="date">March 8, 2025</p>
     </div>
   </div>
   
diff --git a/docs/search.json b/docs/search.json
index e709a39f..49383209 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -564,7 +564,7 @@
     "href": "Chapters/04-http-server.html#sec-http-how-impl",
     "title": "7  Project 2 - Building a HTTP Server from scratch",
     "section": "7.3 How a HTTP server is normally implemented?",
-    "text": "7.3 How a HTTP server is normally implemented?\nLet’s use the C language as an example. There are many materials teaching how to write a simple HTTP server in C code, like Yu (2023), or Weerasiri (2023), or Meehan (2021). Having this in mind, I will not show C code examples here, because you can find them on the internet. But I will describe the theory behind the necessary steps to create such HTTP server in C.\nIn essence, we normally implement a HTTP server in C by using WebSocket technology, which involves the following steps:\n\nCreate a socket object.\nBind a name (or more specifically, an address) to this socket object.\nMake this socket object to start listening and waiting for incoming connections.\nWhen a connection arrive, we accept this connection, and we exchange the HTTP messages (HTTP Request and HTTP Response).\nThen, we simply close this connection.\n\nA socket object is essentially a channel of communication. You are creating a channel where people can send messages through. When you create a socket object, this object is not binded to any particular address. This means that with this object you have a representation of a channel of communication in your hands. But this channel is not currently available, or, it is not currently accessible, because it does not have a known address where you can find it.\nThat is what the “bind” operation do. It binds a name (or more specifically, an address) to this socket object, or, this channel of communication, so that it becomes available, or, accessible through this address. While the “listen” operation makes the socket object to listen for incoming connections in this address. In other words, the “listen” operation makes the socket to wait for incoming connections. currently Now, when a client actually attempts to connect to the server through the socket address that we have specified, in order to establish this connection with the client, the socket object needs to accept this incoming connection. Thus, when we accept an incoming connection, the client and the server become connected to each other, and they can start reading or writing messages into this established connection.\nAfter we receive the HTTP Request from the client, analyze it, and send the HTTP Response to the client, we can then close the connection, and end this communication.",
+    "text": "7.3 How a HTTP server is normally implemented?\nLet’s use the C language as an example. There are many materials teaching how to write a simple HTTP server in C code, like Yu (2023), or Weerasiri (2023), or Meehan (2021). Having this in mind, I will not show C code examples here, because you can find them on the internet. But I will describe the theory behind the necessary steps to create such HTTP server in C.\nIn essence, we normally implement a HTTP server in C by using a TCP socket, which involves the following steps:\n\nCreate a TCP socket object.\nBind a name (or more specifically, an address) to this socket object.\nMake this socket object to start listening and waiting for incoming connections.\nWhen a connection arrive, we accept this connection, and we exchange the HTTP messages (HTTP Request and HTTP Response).\nThen, we simply close this connection.\n\nA socket object is essentially a channel of communication. You are creating a channel where people can send messages through. When you create a socket object, this object is not binded to any particular address. This means that with this object you have a representation of a channel of communication in your hands. But this channel is not currently available, or, it is not currently accessible, because it does not have a known address where you can find it.\nThat is what the “bind” operation do. It binds a name (or more specifically, an address) to this socket object, or, this channel of communication, so that it becomes available, or, accessible through this address. While the “listen” operation makes the socket object to listen for incoming connections in this address. In other words, the “listen” operation makes the socket wait for incoming connections.\nNow, when a client actually attempts to connect to the server through the socket address that we have specified, in order to establish this connection with the client, the socket object needs to accept this incoming connection. Thus, when we accept an incoming connection, the client and the server become connected to each other, and they can start reading or writing messages into this established connection.\nAfter we receive the HTTP Request from the client, analyze it, and send the HTTP Response to the client, we can then close the connection, and end this communication.",
     "crumbs": [
       "<span class='chapter-number'>7</span>  <span class='chapter-title'>Project 2 - Building a HTTP Server from scratch</span>"
     ]
@@ -574,7 +574,7 @@
     "href": "Chapters/04-http-server.html#implementing-the-server---part-1",
     "title": "7  Project 2 - Building a HTTP Server from scratch",
     "section": "7.4 Implementing the server - Part 1",
-    "text": "7.4 Implementing the server - Part 1\n\n7.4.1 Creating the socket object\nLet’s begin with creating the socket object for our server. Just to make things shorter, I will create this socket object in a separate Zig module. I will name it config.zig.\nIn Zig, we can create a web socket using the std.posix.socket() function, from the Zig Standard Library. As I mentioned earlier in Section 7.3, every socket object that we create represents a communication channel, and we need to bind this channel to a specific address. An “address” is defined as an IP address, or, more specifically, an IPv4 address2. Every IPv4 address is composed by two components. The first component is the host, which is a sequence of 4 numbers separated by dot characters (.) that identifies the machine used. While the second component is a port number, which identifies the specific door, or, the specific port to use in the host machine.\nThe sequence of 4 numbers (i.e., the host) identifies the machine (i.e., the computer itself) where this socket will live in. Every computer normally have multiple “doors” available inside of him, because this allows the computer to receive and work with multiple connections at the same time. He simply use a single door for each connection. So the port number, is essentially a number that identifies the specific door in the computer that will be responsible for receiving the connection. That is, it identifies the “door” in the computer that the socket will use to receive incoming connections.\nTo make things simpler, I will use an IP address that identifies our current machine in this example. This means that, our socket object will reside on the same computer that we are currently using (this is also known as the “localhost”) to write this Zig source code.\nBy convention, the IP address that identifies the “localhost”, which is the current machine we are using, is the IP 127.0.0.1. So, that is the IP address we are going to use in our server. I can declare it in Zig by using an array of 4 integers, like this:\n\nconst localhost = [4]u8{ 127, 0, 0, 1 };\n_ = localhost;\n\nNow, we need to decide which port number to use. By convention, there are some port numbers that are reserved, meaning that, we cannot use them for our own purposes, like the port 22 (which is normally used for SSH connections). For TCP connections, which is our case here, a port number is a 16-bit unsigned integer (type u16 in Zig), thus ranging from 0 to 65535 (Wikipedia 2024). So, we can choose a number from 0 to 65535 for our port number. In the example of this book, I will use the port number 3490 (just a random number).\nNow that we have these two informations at hand, I can finally create our socket object, using the std.posix.socket() function. First, we use the host and the port number to create an Address object, with the std.net.Address.initIp4() function, like in the example below. After that, I use this address object inside the socket() function to create our socket object.\nThe Socket struct defined below summarizes all the logic behind this process. In this struct, we have two data members, which are: 1) the address object; 2) and a stream object, which is the object we will use to read and write the messages into any connection we establish.\nNotice that, inside the constructor method of this struct, when we create the socket object, we are using the IPROTO.TCP property as an input to tell the function to create a socket for TCP connections.\n\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\nconst net = @import(\"std\").net;\n\npub const Socket = struct {\n    _address: std.net.Address,\n    _stream: std.net.Stream,\n\n    pub fn init() !Socket {\n        const host = [4]u8{ 127, 0, 0, 1 };\n        const port = 3490;\n        const addr = net.Address.initIp4(host, port);\n        const socket = try std.posix.socket(\n            addr.any.family,\n            std.posix.SOCK.STREAM,\n            std.posix.IPPROTO.TCP\n        );\n        const stream = net.Stream{ .handle = socket };\n        return Socket{ ._address = addr, ._stream = stream };\n    }\n};\n\n\n\n7.4.2 Listening and receiving connections\nRemember that we stored the Socket struct declaration that we built in Section 7.4.1 inside a Zig module named config.zig. This is why I imported this module into our main module (main.zig) in the example below, as the SocketConf object, to access the Socket struct.\nOnce we created our socket object, we can focus now on making this socket object listen and receive new incoming connections. We do that, by calling the listen() method from the Address object that is contained inside the socket object, and then, we call the accept() method over the result.\nThe listen() method from the Address object produces a server object, which is an object that will stay open and running indefinitely, waiting to receive an incoming connection. Therefore, if you try to run the code example below, by calling the run command from the zig compiler, you will notice that the programs keeps running indefinitely, without a clear end.\nThis happens, because the program is waiting for something to happen. It’s waiting for someone to try to connect to the address (http://127.0.0.1:3490) where the server is running and listening for incoming connections. This is what the listen() method do, it makes the socket to be active waiting for someone to connect.\nOn the other side, the accept() method is the function that establishes the connection when someone tries to connect to the socket. This means that, the accept() method returns a new connection object as a result. And you can use this connection object to read or write messages from or to the client. For now, we are not doing anything with this connection object. But we are going to use it in the next section.\n\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n    _ = connection;\n}\n\nThis code example allows one single connection. In other words, the server will wait for one incoming connection, and as soon as the server is done with this first connection that it establishes, the program ends, and the server stops.\nThis is not the norm in the real world. Most people that write a HTTP server like this, usually put the accept() method inside a while (infinite) loop, where if a connection is created with accept(), a new thread of execution is created to deal with this new connection and the client. That is, real-world examples of HTTP Servers normally rely on parallel computing to work.\nWith this design, the server simply accepts the connection, and the whole process of dealing with the client, and receiving the HTTP Request, and sending the HTTP Response, all of this is done in the background, on a separate execution thread.\nSo, as soon as the server accepts the connection, and creates the separate thread, the server goes back to what he was doing earlier, which is to wait indefinitely for a new connection to accept. Having this in mind, the code example exposed above, is a server that serves only a single client. Because the program terminates as soon as the connection is accepted.\n\n\n7.4.3 Reading the message from the client\nNow that we have a connection established, i.e., the connection object that we created through the accept() function, we can now use this connection object to read any messages that the client send to our server. But we can also use it to send messages back to the client.\nThe basic idea is, if we write any data into this connection object, then, we are sending data to the client, and if we read the data present in this connection object, then, we are reading any data that the client sent to us, through this connection object. So, just have this logic in mind. “Read” is for reading messages from the client, and “write” is to send a message to the client.\nRemember from Section 7.2 that, the first thing that we need to do is to read the HTTP Request sent by the client to our server. Because it is the first message that happens inside the established connection, and, as a consequence, it is the first thing that we need to deal with.\nThat is why, I’m going to create a new Zig module in this small project, named request.zig to keep all functions related to the HTTP Request together. Then, I will create a new function named read_request() that will use our connection object to read the message sent by the client, which is the HTTP Request.\n\nconst std = @import(\"std\");\nconst Connection = std.net.Server.Connection;\npub fn read_request(conn: Connection,\n                    buffer: []u8) !void {\n    const reader = conn.stream.reader();\n    _ = try reader.read(buffer);\n}\n\nThis function accepts a slice object which behaves as a buffer. The read_request() function reads the message sent into the connection object, and saves this message into this buffer object that we have provided as input.\nNotice that I’m using the connection object that we created to read the message from the client. I first access the reader object that lives inside the connection object. Then, I call the read() method of this reader object to effectively read and save the data sent by the client into the buffer object that we created earlier. I’m discarding the return value of the read() method, by assigning it to the underscore character (_), because this return value is not useful for us right now.",
+    "text": "7.4 Implementing the server - Part 1\n\n7.4.1 Creating the socket object\nLet’s begin with creating the socket object for our server. Just to make things shorter, I will create this socket object in a separate Zig module. I will name it config.zig.\nIn Zig, we can create a TCP socket using the std.posix.socket() function, from the Zig Standard Library. As I mentioned earlier in Section 7.3, every socket object that we create represents a communication channel, and we need to bind this channel to a specific address. An “address” is defined as an IP address, or, more specifically, an IPv4 address2. Every IPv4 address is composed by two components. The first component is the host, which is a sequence of 4 numbers separated by dot characters (.) that identifies the machine used. While the second component is a port number, which identifies the specific door, or, the specific port to use in the host machine.\nThe sequence of 4 numbers (i.e., the host) identifies the machine (i.e., the computer itself) where this socket will live in. Every computer normally have multiple “doors” available inside of him, because this allows the computer to receive and work with multiple connections at the same time. He simply use a single door for each connection. So the port number, is essentially a number that identifies the specific door in the computer that will be responsible for receiving the connection. That is, it identifies the “door” in the computer that the socket will use to receive incoming connections.\nTo make things simpler, I will use an IP address that identifies our current machine in this example. This means that, our socket object will reside on the same computer that we are currently using (this is also known as the “localhost”) to write this Zig source code.\nBy convention, the IP address that identifies the “localhost”, which is the current machine we are using, is the IP 127.0.0.1. So, that is the IP address we are going to use in our server. I can declare it in Zig by using an array of 4 integers, like this:\n\nconst localhost = [4]u8{ 127, 0, 0, 1 };\n_ = localhost;\n\nNow, we need to decide which port number to use. By convention, there are some port numbers that are reserved, meaning that, we cannot use them for our own purposes, like the port 22 (which is normally used for SSH connections). For TCP connections, which is our case here, a port number is a 16-bit unsigned integer (type u16 in Zig), thus ranging from 0 to 65535 (Wikipedia 2024). So, we can choose a number from 0 to 65535 for our port number. In the example of this book, I will use the port number 3490 (just a random number).\nNow that we have these two informations at hand, I can finally create our socket object, using the std.posix.socket() function. First, we use the host and the port number to create an Address object, with the std.net.Address.initIp4() function, like in the example below. After that, I use this address object inside the socket() function to create our socket object.\nThe Socket struct defined below summarizes all the logic behind this process. In this struct, we have two data members, which are: 1) the address object; 2) and a stream object, which is the object we will use to read and write the messages into any connection we establish.\nNotice that, inside the constructor method of this struct, when we create the socket object, we are using the IPROTO.TCP property as an input to tell the function to create a socket for TCP connections.\n\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\nconst net = @import(\"std\").net;\n\npub const Socket = struct {\n    _address: std.net.Address,\n    _stream: std.net.Stream,\n\n    pub fn init() !Socket {\n        const host = [4]u8{ 127, 0, 0, 1 };\n        const port = 3490;\n        const addr = net.Address.initIp4(host, port);\n        const socket = try std.posix.socket(\n            addr.any.family,\n            std.posix.SOCK.STREAM,\n            std.posix.IPPROTO.TCP\n        );\n        const stream = net.Stream{ .handle = socket };\n        return Socket{ ._address = addr, ._stream = stream };\n    }\n};\n\n\n\n7.4.2 Listening and receiving connections\nRemember that we stored the Socket struct declaration that we built in Section 7.4.1 inside a Zig module named config.zig. This is why I imported this module into our main module (main.zig) in the example below, as the SocketConf object, to access the Socket struct.\nOnce we created our socket object, we can focus now on making this socket object listen and receive new incoming connections. We do that, by calling the listen() method from the Address object that is contained inside the socket object, and then, we call the accept() method over the result.\nThe listen() method from the Address object produces a server object, which is an object that will stay open and running indefinitely, waiting to receive an incoming connection. Therefore, if you try to run the code example below, by calling the run command from the zig compiler, you will notice that the programs keeps running indefinitely, without a clear end.\nThis happens, because the program is waiting for something to happen. It’s waiting for someone to try to connect to the address (http://127.0.0.1:3490) where the server is running and listening for incoming connections. This is what the listen() method do, it makes the socket to be active waiting for someone to connect.\nOn the other side, the accept() method is the function that establishes the connection when someone tries to connect to the socket. This means that, the accept() method returns a new connection object as a result. And you can use this connection object to read or write messages from or to the client. For now, we are not doing anything with this connection object. But we are going to use it in the next section.\n\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n    _ = connection;\n}\n\nThis code example allows one single connection. In other words, the server will wait for one incoming connection, and as soon as the server is done with this first connection that it establishes, the program ends, and the server stops.\nThis is not the norm in the real world. Most people that write a HTTP server like this, usually put the accept() method inside a while (infinite) loop, where if a connection is created with accept(), a new thread of execution is created to deal with this new connection and the client. That is, real-world examples of HTTP Servers normally rely on parallel computing to work.\nWith this design, the server simply accepts the connection, and the whole process of dealing with the client, and receiving the HTTP Request, and sending the HTTP Response, all of this is done in the background, on a separate execution thread.\nSo, as soon as the server accepts the connection, and creates the separate thread, the server goes back to what he was doing earlier, which is to wait indefinitely for a new connection to accept. Having this in mind, the code example exposed above, is a server that serves only a single client. Because the program terminates as soon as the connection is accepted.\n\n\n7.4.3 Reading the message from the client\nNow that we have a connection established, i.e., the connection object that we created through the accept() function, we can now use this connection object to read any messages that the client send to our server. But we can also use it to send messages back to the client.\nThe basic idea is, if we write any data into this connection object, then, we are sending data to the client, and if we read the data present in this connection object, then, we are reading any data that the client sent to us, through this connection object. So, just have this logic in mind. “Read” is for reading messages from the client, and “write” is to send a message to the client.\nRemember from Section 7.2 that, the first thing that we need to do is to read the HTTP Request sent by the client to our server. Because it is the first message that happens inside the established connection, and, as a consequence, it is the first thing that we need to deal with.\nThat is why, I’m going to create a new Zig module in this small project, named request.zig to keep all functions related to the HTTP Request together. Then, I will create a new function named read_request() that will use our connection object to read the message sent by the client, which is the HTTP Request.\n\nconst std = @import(\"std\");\nconst Connection = std.net.Server.Connection;\npub fn read_request(conn: Connection,\n                    buffer: []u8) !void {\n    const reader = conn.stream.reader();\n    _ = try reader.read(buffer);\n}\n\nThis function accepts a slice object which behaves as a buffer. The read_request() function reads the message sent into the connection object, and saves this message into this buffer object that we have provided as input.\nNotice that I’m using the connection object that we created to read the message from the client. I first access the reader object that lives inside the connection object. Then, I call the read() method of this reader object to effectively read and save the data sent by the client into the buffer object that we created earlier. I’m discarding the return value of the read() method, by assigning it to the underscore character (_), because this return value is not useful for us right now.",
     "crumbs": [
       "<span class='chapter-number'>7</span>  <span class='chapter-title'>Project 2 - Building a HTTP Server from scratch</span>"
     ]

From 567e6f22d7a419c948cb0d5debe28cd34892cf34 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sat, 8 Mar 2025 10:40:12 -0300
Subject: [PATCH 115/151] Add function to check compiler version

---
 _freeze/index/execute-results/html.json |   2 +-
 docs/index.html                         |   2 +-
 docs/search.json                        |   2 +-
 zig_engine.R                            | 110 ++++++++++++++++++++++++
 4 files changed, 113 insertions(+), 3 deletions(-)

diff --git a/_freeze/index/execute-results/html.json b/_freeze/index/execute-results/html.json
index 9f591c93..abf34f7d 100644
--- a/_freeze/index/execute-results/html.json
+++ b/_freeze/index/execute-results/html.json
@@ -2,7 +2,7 @@
   "hash": "335ac568e17c5057352e05da9521e5ae",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy a PDF, eBook or a physical copy\nof the book, either at Amazon, or at Leanpub:\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://leanpub.com/introductiontozigaproject-basedbook\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Leanpub!\n    </button>\n</a>\n\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e., open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.\nCurrently, he is a Data Platform Engineer at [Blip](https://www.blip.ai/en/)[^blip], and\na Databricks Certified Associate Developer for Apache Spark 3.0.\n\n[^blip]: <https://www.blip.ai/en/>\n\n\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nBrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer who loves to learn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2025 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n\n\n- System version: Linux, 6.8.0-52-generic, NA, x86_64.\n- Zig version: 0.14.0-dev.3046+08d661fcf.\n- Quarto version: 1.5.57.\n\n\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang), Tommaso Ricci (\\@Zorgatone), Primo Sabatini (\\@primos63), Santiago Fernandez (\\@santif), Hamza Wahed (\\@HamzaWahed), mwilbur (\\@mwilbur), Dima Budaragin (\\@dbud), Jorge Jímenez (\\@jorge-j1m), Alexander (\\@alexwheezy), Maarten Coopens (\\@maarteNNNN), Niklas Johansson (\\@Raphexion), glystik (\\@glystik), Michael Lynch (\\@mtlynch)\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy a PDF, eBook or a physical copy\nof the book, either at Amazon, or at Leanpub:\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://leanpub.com/introductiontozigaproject-basedbook\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Leanpub!\n    </button>\n</a>\n\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e., open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.\nCurrently, he is a Data Platform Engineer at [Blip](https://www.blip.ai/en/)[^blip], and\na Databricks Certified Associate Developer for Apache Spark 3.0.\n\n[^blip]: <https://www.blip.ai/en/>\n\n\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nBrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer who loves to learn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2025 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n\n- System version: Linux, 6.11.0-19-generic, 24.04.1-Ubuntu, x86_64.\n- Zig version: 0.14.0-dev.3046+08d661fcf.\n- Quarto version: 1.5.57.\n\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang), Tommaso Ricci (\\@Zorgatone), Primo Sabatini (\\@primos63), Santiago Fernandez (\\@santif), Hamza Wahed (\\@HamzaWahed), mwilbur (\\@mwilbur), Dima Budaragin (\\@dbud), Jorge Jímenez (\\@jorge-j1m), Alexander (\\@alexwheezy), Maarten Coopens (\\@maarteNNNN), Niklas Johansson (\\@Raphexion), glystik (\\@glystik), Michael Lynch (\\@mtlynch)\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
diff --git a/docs/index.html b/docs/index.html
index 10e83b3b..34e98809 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -426,7 +426,7 @@ <h2 class="unnumbered anchored" data-anchor-id="license">License</h2>
 <h2 class="unnumbered anchored" data-anchor-id="book-compilation-metadata">Book compilation metadata</h2>
 <p>This book was compiled using the following versions of <a href="https://ziglang.org">Zig</a> and <a href="https://quarto.org">Quarto</a>:</p>
 <ul>
-<li>System version: Linux, 6.8.0-52-generic, NA, x86_64.</li>
+<li>System version: Linux, 6.11.0-19-generic, 24.04.1-Ubuntu, x86_64.</li>
 <li>Zig version: 0.14.0-dev.3046+08d661fcf.</li>
 <li>Quarto version: 1.5.57.</li>
 </ul>
diff --git a/docs/search.json b/docs/search.json
index 49383209..616ae938 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -54,7 +54,7 @@
     "href": "index.html#book-compilation-metadata",
     "title": "Introduction to Zig",
     "section": "Book compilation metadata",
-    "text": "Book compilation metadata\nThis book was compiled using the following versions of Zig and Quarto:\n\nSystem version: Linux, 6.8.0-52-generic, NA, x86_64.\nZig version: 0.14.0-dev.3046+08d661fcf.\nQuarto version: 1.5.57.",
+    "text": "Book compilation metadata\nThis book was compiled using the following versions of Zig and Quarto:\n\nSystem version: Linux, 6.11.0-19-generic, 24.04.1-Ubuntu, x86_64.\nZig version: 0.14.0-dev.3046+08d661fcf.\nQuarto version: 1.5.57.",
     "crumbs": [
       "Welcome"
     ]
diff --git a/zig_engine.R b/zig_engine.R
index 1f76d880..151e2168 100644
--- a/zig_engine.R
+++ b/zig_engine.R
@@ -2,6 +2,14 @@ library(knitr)
 library(readr)
 library(stringr)
 
+
+minimum_zig_compiler_version <- list(
+  maj_version = 0,
+  min_version = 14,
+  patch_version = 0
+)
+
+
 #' Find path to the Zig compiler in the current machine.
 #'
 #' This function is used to find the full path to the Zig compiler
@@ -61,11 +69,113 @@ find_in_path_ <- function() {
 }
 
 
+
+#' Check Zig compiler version.
+#'
+#' This function will check if the Zig compiler that was found
+#' in the current machine have the minimum required version to
+#' compiler the book.
+check_zig_compiler_version <- function() {
+  fv <- get_zig_compiler_version()
+  ev <- minimum_zig_compiler_version
+  if (fv$maj_version > ev$maj_version) {
+    return()
+  }
+
+  if (fv$maj_version == ev$maj_version) {
+    if (fv$min_version > ev$min_version) {
+      return()
+    }
+
+    if (fv$min_version == ev$min_version
+        && fv$patch_version >= ev$patch_version) {
+      return()
+    }
+  }
+
+  fvmsg <- sprintf(
+    "compiler have a version of %d.%d.%d, ",
+    fv$maj_version, fv$min_version, fv$patch_version
+  )
+  evmsg <- sprintf(
+    "but we expected a compiler with minimum version of %d.%d.%d ",
+    ev$maj_version, ev$min_version, ev$patch_version
+  )
+
+  msg <- paste(
+    c(
+      "[ERROR]: We found a Zig compiler in your computer. However, this ",
+      fvmsg, evmsg,
+      "to compile this book."
+    ),
+    sep = "",
+    collapse = ""
+  )
+
+  stop(msg)
+}
+
+
+
+
+#' Get Zig compiler version.
+#'
+#' This function can be used to get the version of the Zig
+#' compiler that was found in the current machine.
+get_zig_compiler_version <- function() {
+  zig_cmd_path <- getOption("zig_exe_path")
+  output <- system2(
+    zig_cmd_path,
+    shQuote("version"),
+    stdout = TRUE,
+    stderr = TRUE
+  )
+  version <- parse_semantic_version(output)
+  return(version)
+}
+
+
+
+#' Parse a semantic version value.
+#'
+#' This function can be used to parse a semantic version value.
+#'
+#' @param input A string containing the semantic version value to parse.
+parse_semantic_version <- function(input) {
+  regex_str <- "^([0-9])[.]([0-9]+)[.]([0-9]+)"
+  maj_version <- str_extract(input, regex_str, group = 1)
+  min_version <- str_extract(input, regex_str, group = 2)
+  patch_version <- str_extract(input, regex_str, group = 3)
+
+  return(list(
+    maj_version = as.integer(maj_version),
+    min_version = as.integer(min_version),
+    patch_version = as.integer(patch_version)
+  ))
+}
+
+
+
+
+
+
+
+
+
 # The full path to the Zig compiler is registered in the R process
 # inside the global option `zig_exe_path`. And you can retrieve the
 # value registered in this option with `getOption("zig_exe_path")`.
 options(zig_exe_path = find_zig_())
 options(width = 50)
+check_zig_compiler_version()
+
+
+
+
+
+
+
+
 
 
 

From 8a8c47dda4ef3dc8da836936f068a550c3ac1718 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sat, 8 Mar 2025 12:04:23 -0300
Subject: [PATCH 116/151] Add new section to explain pub keyword

---
 Chapters/03-structs.qmd                       | 130 ++++++-
 .../zig-basics/import-non-pub-struct.zig      |   5 +
 ZigExamples/zig-basics/pub-keyword.zig        |  20 +
 .../03-structs/execute-results/html.json      |   8 +-
 docs/Chapters/03-structs.html                 | 362 ++++++++++--------
 docs/search.json                              |   6 +-
 6 files changed, 359 insertions(+), 172 deletions(-)
 create mode 100644 ZigExamples/zig-basics/import-non-pub-struct.zig
 create mode 100644 ZigExamples/zig-basics/pub-keyword.zig

diff --git a/Chapters/03-structs.qmd b/Chapters/03-structs.qmd
index 59280306..ba5f7069 100644
--- a/Chapters/03-structs.qmd
+++ b/Chapters/03-structs.qmd
@@ -759,7 +759,7 @@ const User = struct {
     name: []const u8,
     email: []const u8,
 
-    pub fn init(id: u64,
+    fn init(id: u64,
                 name: []const u8,
                 email: []const u8) User {
 
@@ -770,7 +770,7 @@ const User = struct {
         };
     }
 
-    pub fn print_name(self: User) !void {
+    fn print_name(self: User) !void {
         try stdout.print("{s}\n", .{self.name});
     }
 };
@@ -781,21 +781,125 @@ pub fn main() !void {
 }
 ```
 
+
+
+### The `pub` keyword
+
 The `pub` keyword plays an important role in struct declarations, and OOP in Zig.
-Every method that you declare in your struct that is marked with the keyword `pub`,
-becomes a public method of this particular struct.
+In essence, this keyword is short for "public", and it makes an item/component available outside of the
+module where this item/component is declared. In other words, if I don't apply the `pub` keyword on
+something, it means that this "something" is available to be called/used only from within the module
+where this "something" is declared.
+
+To demonstrate the effect of this keyword let's focus again on the `User` struct that we have
+declared on the previous section. For our example here, let's suppose that this `User` struct is declared inside
+a Zig module named `user.zig`. If I don't use the `pub` keyword on the `User` struct, it means that I can create
+an `User` object, and call it's methods (`print_name()` and `init()`) only from within the module where the `User`
+struct is declared, which in this case is the `user.zig` module.
+
+This is why the previous code example works fine. Because we declare and also use the `User` struct
+inside the same module. But problems start to arise when we try to import and call/use this struct
+from another module. For example, if I create a new module called `register.zig`, and import the `user.zig`
+module into it, and try to annotate any variable with the `User` type, I get an error from the compiler.
+
+```zig
+// register.zig
+const user = @import("user.zig");
+pub fn main() !void {
+    const u: user.User = undefined;
+    _ = u;
+}
+```
+
+```
+register.zig:3:18: error: 'User' is not marked 'pub'
+    const u: user.User = undefined;
+             ~~~~^~~~~
+user.zig:3:1: note: declared here
+const User = struct {
+^~~~~
+```
+
+Therefore, if you want to use something outside of the module where this "something" is declared,
+you have to mark it with the `pub` keyword. This "something" can be a module,
+a struct, a function, an object, etc.
+
+For our example here, if we go back to the `user.zig` module, and add the `pub` keyword
+to the `User` struct declaration, then, I can successfully compile the `register.zig` module.
+
+```zig
+// user.zig
+// Added the `pub` keyword to `User`
+pub const User = struct {
+// ...
+```
+
+```zig
+// register.zig
+// This works fine now!
+const user = @import("user.zig");
+pub fn main() !void {
+    const u: user.User = undefined;
+    _ = u;
+}
+```
 
-So every method that you create inside your struct, is, at first, a private method
-of that struct. Meaning that, this method can only be called from within this
-struct. But, if you mark this method as public, with the keyword `pub`, then,
-you can call the method directly from an instance of the `User` struct.
 
-In other words, the functions marked by the keyword `pub`
-are members of the public API of that struct.
-For example, if I did not mark the `print_name()` method as public,
-then, I could not execute the line `u.print_name()`. Because I would
-not be authorized to call this method directly in my code.
+Now, what do you think it will happen if I try to actually call from `register.zig` any of the methods
+of the `User` struct? For example, if I try to call the `init()` method? The answer is: I get a similar error message,
+warning me that the `init()` method is not marked as `pub`, as you can see below:
 
+```zig
+const user = @import("user.zig");
+pub fn main() !void {
+    const u: user.User = user.User.init(
+        1, "pedro", "email@gmail.com"
+    );
+    _ = u;
+}
+```
+
+```
+register.zig:3:35: error: 'init' is not marked 'pub'
+    const u: user.User = user.User.init(
+                         ~~~~~~~~~^~~~~
+user.zig:8:5: note: declared here
+    fn init(id: u64,
+    ^~~~~~~
+```
+
+Thus, just because we have applied the `pub` keyword on the struct declaration,
+this does not make the methods of that struct public as well. If we want to use
+any method from a struct (such as the `init()` method) outside of the module
+where this struct is declared, we have to mark this method with the `pub` keyword
+as well.
+
+Going back to the `user.zig` module, and marking both the `init()` and `print_name()`
+methods with the `pub` keyword, makes them both available to the outside world, and,
+as consequence, makes the previous code example work.
+
+
+```zig
+// user.zig
+// Added the `pub` keyword to `User.init`
+    pub fn init(
+// ...
+// Added the `pub` keyword to `User.print_name`
+    pub fn print_name(self: User) !void {
+// ...
+```
+
+```zig
+// register.zig
+// This works fine now!
+const user = @import("user.zig");
+pub fn main() !void {
+    const u: user.User = user.User.init(
+        1, "pedro", "email@gmail.com"
+    );
+    _ = u;
+}
+```
 
 
 ### Anonymous struct literals {#sec-anonymous-struct-literals}
diff --git a/ZigExamples/zig-basics/import-non-pub-struct.zig b/ZigExamples/zig-basics/import-non-pub-struct.zig
new file mode 100644
index 00000000..d327c347
--- /dev/null
+++ b/ZigExamples/zig-basics/import-non-pub-struct.zig
@@ -0,0 +1,5 @@
+const user = @import("pub-keyword.zig");
+pub fn main() !void {
+    const u: user.User = user.User.init(1, "pedro", "email@gmail.com");
+    _ = u;
+}
diff --git a/ZigExamples/zig-basics/pub-keyword.zig b/ZigExamples/zig-basics/pub-keyword.zig
new file mode 100644
index 00000000..c9a60c5b
--- /dev/null
+++ b/ZigExamples/zig-basics/pub-keyword.zig
@@ -0,0 +1,20 @@
+const std = @import("std");
+const stdout = std.io.getStdOut().writer();
+pub const User = struct {
+    id: u64,
+    name: []const u8,
+    email: []const u8,
+
+    pub fn init(id: u64, name: []const u8, email: []const u8) User {
+        return User{ .id = id, .name = name, .email = email };
+    }
+
+    pub fn print_name(self: User) !void {
+        try stdout.print("{s}\n", .{self.name});
+    }
+};
+
+pub fn main() !void {
+    const u = User.init(1, "pedro", "email@gmail.com");
+    try u.print_name();
+}
diff --git a/_freeze/Chapters/03-structs/execute-results/html.json b/_freeze/Chapters/03-structs/execute-results/html.json
index 8781660b..fbe83947 100644
--- a/_freeze/Chapters/03-structs/execute-results/html.json
+++ b/_freeze/Chapters/03-structs/execute-results/html.json
@@ -1,11 +1,9 @@
 {
-  "hash": "ec9ff8aaff4376d4eab0dd3ee150d725",
+  "hash": "10ffcb221f40a28afe7a41688091c355",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Control flow, structs, modules and types\n\nWe have discussed a lot of Zig's syntax in the last chapter,\nespecially in @sec-root-file and @sec-main-file.\nBut we still need to discuss some other very important\nelements of the language. Elements that you will use constantly on your day-to-day\nroutine.\n\nWe begin this chapter by discussing the different keywords and structures\nin Zig related to control flow (e.g. loops and if statements).\nThen, we talk about structs and how they can be used to do some\nbasic Object-Oriented (OOP) patterns in Zig. We also talk about\ntype inference and type casting.\nFinally, we end this chapter by discussing modules, and how they relate\nto structs.\n\n\n\n## Control flow {#sec-zig-control-flow}\n\nSometimes, you need to make decisions in your program. Maybe you need to decide\nwhether or not to execute a specific piece of code. Or maybe,\nyou need to apply the same operation over a sequence of values. These kinds of tasks,\ninvolve using structures that are capable of changing the \"control flow\" of our program.\n\nIn computer science, the term \"control flow\" usually refers to the order in which expressions (or commands)\nare evaluated in a given language or program. But this term is also used to refer\nto structures that are capable of changing this \"evaluation order\" of the commands\nexecuted by a given language/program.\n\nThese structures are better known\nby a set of terms, such as: loops, if/else statements, switch statements, among others. So,\nloops and if/else statements are examples of structures that can change the \"control\nflow\" of our program. The keywords `continue` and `break` are also examples of symbols\nthat can change the order of evaluation, since they can move our program to the next iteration\nof a loop, or make the loop stop completely.\n\n\n### If/else statements\n\nAn if/else statement performs a \"conditional flow operation\".\nA conditional flow control (or choice control) allows you to execute\nor ignore a certain block of commands based on a logical condition.\nMany programmers and computer science professionals also use\nthe term \"branching\" in this case.\nIn essence, an if/else statement allow us to use the result of a logical test\nto decide whether or not to execute a given block of commands.\n\nIn Zig, we write if/else statements by using the keywords `if` and `else`.\nWe start with the `if` keyword followed by a logical test inside a pair\nof parentheses, followed by a pair of curly braces which contains the lines\nof code to be executed in case the logical test returns the value `true`.\n\nAfter that, you can optionally add an `else` statement. To do that, just add the `else`\nkeyword followed by a pair of curly braces, with the lines of code\nto executed in case the logical test defined at `if` returns `false`.\n\nIn the example below, we are testing if the object `x` contains a number\nthat is greater than 10. Judging by the output printed to the console,\nwe know that this logical test returned `false`. Because the output\nin the console is compatible with the line of code present in the\n`else` branch of the if/else statement.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x = 5;\nif (x > 10) {\n    try stdout.print(\n        \"x > 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x <= 10!\\n\", .{}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nx <= 10!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Switch statements {#sec-switch}\n\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust.\nAs you would expect, to write a switch statement in Zig we use the `switch` keyword.\nWe provide the value that we want to \"switch over\" inside a\npair of parentheses. Then, we list the possible combinations (or \"branches\")\ninside a pair of curly braces.\n\nLet's take a look at the code example below. You can see that\nI'm creating an enum type called `Role`. We talk more about enums in @sec-enum.\nBut in summary, this `Role` type is listing different types of roles in a fictitious\ncompany, like `SE` for Software Engineer, `DE` for Data Engineer, `PM` for Product Manager,\netc.\n\nNotice that we are using the value from the `role` object in the\nswitch statement, to discover which exact area we need to store in the `area` variable object.\nAlso notice that we are using type inference inside the switch statement, with the dot character,\nas we are going to describe in @sec-type-inference.\nThis makes the `zig` compiler infer the correct data type of the values (`PM`, `SE`, etc.) for us.\n\nAlso notice that, we are grouping multiple values in the same branch of the switch statement.\nWe just separate each possible value with a comma. For example, if `role` contains either `DE` or `DA`,\nthe `area` variable would contain the value `\"Data & Analytics\"`, instead of `\"Platform\"` or `\"Sales\"`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO => {\n            area = \"Platform\";\n        },\n        .DE, .DA => {\n            area = \"Data & Analytics\";\n        },\n        .KS => {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nPlatform\n```\n\n\n:::\n:::\n\n\n\n\n\n#### Switch statements must exhaust all possibilities\n\nOne very important aspect about switch statements in Zig\nis that they must exhaust all existing possibilities.\nIn other words, all possible values that could be found inside the `role`\nobject must be explicitly handled in this switch statement.\n\nSince the `role` object has type `Role`, the only possible values to\nbe found inside this object are `PM`, `SE`, `DPE`, `PO`, `DE`, `DA` and `KS`.\nThere are no other possible values to be stored in this `role` object.\nThus, the switch statements must have a combination (branch) for each one of these values.\nThis is what \"exhaust all existing possibilities\" means. The switch statement covers\nevery possible case.\n\nTherefore, you cannot write a switch statement in Zig, and leave an edge case\nwith no explicit action to be taken.\nThis is a similar behaviour to switch statements in Rust, which also have to\nhandle all possible cases.\n\n\n\n#### The else branch\n\nTake a look at the `dump_hex_fallible()` function below as an example. This function\ncomes from the Zig Standard Library. More precisely, from the\n[`debug.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/debug.zig)[^debug-mod].\nThere are multiple lines in this function, but I omitted them to focus solely on the\nswitch statement found in this function. Notice that this switch statement has four\npossible cases (i.e., four explicit branches). Also, notice that we used an `else` branch\nin this case.\n\nAn `else` branch in a switch statement works as the \"default branch\".\nWhenever you have multiple cases in your switch statement where\nyou want to apply the exact same action, you can use an `else` branch to do that.\n\n[^debug-mod]: <https://github.com/ziglang/zig/blob/master/lib/std/debug.zig>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' => try writer.writeAll(\"␊\"),\n        '\\r' => try writer.writeAll(\"␍\"),\n        '\\t' => try writer.writeAll(\"␉\"),\n        else => try writer.writeByte('.'),\n    }\n}\n```\n:::\n\n\n\n\nMany programmers would also use an `else` branch to handle a \"not supported\" case.\nThat is, a case that cannot be properly handled by your code, or, just a case that\nshould not be \"fixed\". Therefore, you can use an `else` branch to panic (or raise an error)\nin your program to stop the current execution.\n\nTake the code example below. We can see that, we are handling the cases\nfor the `level` object being either 1, 2, or 3. All other possible cases are not supported by default,\nand, as consequence, we raise a runtime error in such cases through the `@panic()` built-in function.\n\nAlso notice that, we are assigning the result of the switch statement to a new object called `category`.\nThis is another thing that you can do with switch statements in Zig. If a branch\noutputs a value as result, you can store the result value of the switch statement into\na new object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 => \"beginner\",\n    3 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n:::\n\n\n\n\n```\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n```\n\n\n\n#### Using ranges in switch\n\nFurthermore, you can also use ranges of values in switch statements.\nThat is, you can create a branch in your switch statement that is used\nwhenever the input value is within the specified range. These \"range expressions\"\nare created with the operator `...`. It's important\nto emphasize that the ranges created by this operator are\ninclusive on both ends.\n\nFor example, I could easily change the previous code example to support all\nlevels between 0 and 100. Like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 => \"beginner\",\n    26...75 => \"intermediary\",\n    76...100 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nbeginner\n```\n\n\n:::\n:::\n\n\n\n\nThis is neat, and it works with character ranges too. That is, I could\nsimply write `'a'...'z'`, to match any character value that is a\nlowercase letter, and it would work fine.\n\n\n#### Labeled switch statements\n\nIn @sec-blocks we have talked about labeling blocks, and also, about using these labels\nto return a value from the block. Well, from version 0.14.0 and onwards of the `zig` compiler,\nyou can also apply labels over switch statements, which makes it possible to almost implement a\n\"C `goto`\" like pattern.\n\nFor example, if you give the label `xsw` to a switch statement, you can use this\nlabel in conjunction with the `continue` keyword to go back to the beginning of the switch\nstatement. In the example below, the execution goes back to the beginning of the\nswitch statement two times, before ending at the `3` branch.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nxsw: switch (@as(u8, 1)) {\n    1 => {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 => continue :xsw 3,\n    3 => return,\n    4 => {},\n    else => {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n```\n:::\n\n\n\n\n\n### The `defer` keyword {#sec-defer}\n\nWith the `defer` keyword you can register an expression to be executed when you exit the current scope.\nTherefore, this keyword has a similar functionality as the `on.exit()` function from R.\nTake the `foo()` function below as an example. When we execute this `foo()` function, the expression\nthat prints the message \"Exiting function ...\" is getting executed only when the function exits\nits scope.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nAdding some numbers ...\nMultiplying ...\nExiting function ...\n```\n\nTherefore, we can use `defer` to declare an expression that is going to be executed\nwhen your code exits the current scope. Some programmers like to interpret the phrase \"exit of the current scope\"\nas \"the end of the current scope\". But this interpretation might not be entirely correct, depending\non what you consider as \"the end of the current scope\".\n\nI mean, what do you consider as **the end** of the current scope? Is it the closing curly bracket (`}`) of the scope?\nIs it when the last expression in the function gets executed? Is it when the function returns to the previous scope?\nEtc. For example, it would not be correct to interpret the \"exit of the current scope\" as the closing\ncurly bracket of the scope. Because the function might exit from an earlier position than this\nclosing curly bracket (e.g. an error value was generated at a previous line inside the function;\nthe function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\n\nNow, if you remember of what we have discussed in @sec-blocks, there are multiple structures in the language\nthat create their own separate scopes. For/while loops, if/else statements,\nfunctions, normal blocks, etc. This also affects the interpretation of `defer`.\nFor example, if you use `defer` inside a for loop, then, the given expression\nwill be executed everytime this specific for loop exits its own scope.\n\nBefore we continue, it's worth emphasizing that the `defer` keyword is an \"unconditional defer\".\nWhich means that the given expression will be executed no matter how the code exits\nthe current scope. For example, your code might exit the current scope because of an error value\nbeing generated, or, because of a return statement, or, a break statement, etc.\n\n\n\n### The `errdefer` keyword {#sec-errdefer1}\n\nOn the previous section, we have discussed the `defer` keyword, which you can use to\nregister an expression to be executed at the exit of the current scope.\nBut this keyword has a brother, which is the `errdefer` keyword. While `defer`\nis an \"unconditional defer\", the `errdefer` keyword is a \"conditional defer\".\nWhich means that the given expression is executed only when you exit the current\nscope on a very specific circumstance.\n\nIn more details, the expression given to `errdefer` is executed only when an error occurs in the current scope.\nTherefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope\nin a normal situation, without errors, the expression given to `errdefer` is not executed.\n\nThis makes the `errdefer` keyword one of the many tools available in Zig for error handling.\nIn this section, we are more concerned with the control flow aspects around `errdefer`.\nBut we are going to discuss `errdefer` later as a error handling tool in @sec-errdefer2.\n\nThe code example below demonstrates three things:\n\n- that `defer` is an \"unconditional defer\", because the given expression gets executed regardless of how the function `foo()` exits its own scope.\n- that `errdefer` is executed because the function `foo()` returned an error value.\n- that `defer` and `errdefer` expressions are executed in a LIFO (*last in, first out*) order.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\nWhen I say that \"defer expressions\" are executed in a LIFO order, what I want to say is that\nthe last `defer` or `errdefer` expressions in the code are the first ones to be executed.\nYou could also interpret this as: \"defer expressions\" are executed from bottom to top, or,\nfrom last to first.\n\nTherefore, if I change the order of the `defer` and `errdefer` expressions, you will notice that\nthe value of `i` that gets printed to the console changes to 1. This doesn't mean that the\n`defer` expression was not executed in this case. This actually means that the `defer` expression\nwas executed only after the `errdefer` expression. The code example below demonstrates this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n```\n:::\n\n\n\n\n```\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\n\n\n### For loops\n\nA loop allows you to execute the same lines of code multiple times,\nthus, creating a \"repetition space\" in the execution flow of your program.\nLoops are particularly useful when we want to replicate the same function\n(or the same set of commands) over different inputs.\n\nThere are different types of loops available in Zig. But the most\nessential of them all is probably the *for loop*. A for loop is\nused to apply the same piece of code over the elements of a slice, or, an array.\n\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from\nother languages. You start with the `for` keyword, then, you\nlist the items that you want to iterate\nover inside a pair of parentheses. Then, inside of a pair of pipes (`|`)\nyou should declare an identifier that will serve as your iterator, or,\nthe \"repetition index of the loop\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (items) |value| {\n    // code to execute\n}\n```\n:::\n\n\n\n\nTherefore, instead of using a `(value in items)` syntax,\nin Zig, for loops use the syntax `(items) |value|`. In the example\nbelow, you can see that we are looping through the items\nof the array stored at the object `name`, and printing to the\nconsole the decimal representation of each character in this array.\n\nIf we wanted, we could also iterate through a slice (or a portion) of\nthe array, instead of iterating through the entire array stored in the `name` object.\nJust use a range selector to select the section you want. For example,\nI could provide the expression `name[0..3]` to the for loop, to iterate\njust through the first 3 elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n80 | 101 | 100 | 114 | 111 | \n```\n\n\n:::\n:::\n\n\n\n\nIn the above example we are using the value itself of each\nelement in the array as our iterator. But there are many situations where\nwe need to use an index instead of the actual values of the items.\n\nYou can do that by providing a second set of items to iterate over.\nMore precisely, you provide the range selector `0..` to the for loop. So,\nyes, you can use two different iterators at the same time in a for\nloop in Zig.\n\nBut remember from @sec-assignments that, every object\nyou create in Zig must be used in some way. So if you declare two iterators\nin your for loop, you must use both iterators inside the for loop body.\nBut if you want to use just the index iterator, and not use the \"value iterator\",\nthen, you can discard the value iterator by maching the\nvalue items to the underscore character, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n:::\n\n\n\n\n```\n0 | 1 | 2 | 3 | 4 |\n```\n\n\n### While loops\n\nA while loop is created from the `while` keyword. A `for` loop\niterates through the items of an array, but a `while` loop\nwill loop continuously, and infinitely, until a logical test\n(specified by you) becomes false.\n\nYou start with the `while` keyword, then, you define a logical\nexpression inside a pair of parentheses, and the body of the\nloop is provided inside a pair of curly braces, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\nYou can also specify the increment expression to be used at the beginning of a while loop.\nTo do that, we write the increment expression inside a pair of parentheses after a colon character (`:`).\nThe code example below demonstrates this other pattern.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\n### Using `break` and `continue`\n\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using\nthe keywords `break` and `continue`, respectively. The `while` loop presented in the next code example is,\nat first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to `true`.\nBut what makes this `while` loop stop when the `i` object reaches the count\n10? It's the `break` keyword!\n\nInside the while loop, we have an if statement that is constantly checking if the `i` variable\nis equal to 10. Since we are incrementing the value of `i` at each iteration of the\nwhile loop, this `i` object will eventually be equal to 10, and when it is, the if statement\nwill execute the `break` expression, and, as a result, the execution of the while loop is stopped.\n\nNotice the use of the `expect()` function from the Zig Standard Library after the while loop.\nThis `expect()` function is an \"assert\" type of function.\nThis function checks if the logical test provided is equal to true. If so, the function do nothing.\nOtherwise (i.e., the logical test is equal to false), the function raises an assertion error.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nEverything worked!\n```\n\n\n:::\n:::\n\n\n\n\nSince this code example was executed successfully by the `zig` compiler,\nwithout raising any errors, we known that, after the execution of the while loop,\nthe `i` object is equal to 10. Because if it wasn't equal to 10, an error would have\nbeen raised by `expect()`.\n\nNow, in the next example, we have a use case for\nthe `continue` keyword. The if statement is constantly\nchecking if the current index is a multiple of 2. If\nit is, we jump to the next iteration of the loop.\nOtherwise, the loop just prints the current index to the console.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 3 | 5 | \n```\n\n\n:::\n:::\n\n\n\n\n\n\n## Function parameters are immutable {#sec-fun-pars}\n\nWe have already discussed a lot of the syntax behind function declarations in @sec-root-file and @sec-main-file.\nBut I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig.\nIn summary, function parameters are immutable in Zig.\n\nTake the code example below, where we declare a simple function that just tries to add\nsome amount to the input integer, and returns the result back. If you look closely\nat the body of this `add2()` function, you will notice that we try\nto save the result back into the `x` function argument.\n\nIn other words, this function not only uses the value that it received through the function argument\n`x`, but it also tries to change the value of this function argument, by assigning the addition result\ninto `x`. However, function arguments in Zig are immutable. You cannot change their values, or, you\ncannot assign values to them inside the body's function.\n\nThis is the reason why, the code example below does not compile successfully. If you try to compile\nthis code example, you will get a compile error message about \"trying to change the value of a\nimmutable (i.e., constant) object\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n\n\n```\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n```\n\n\n### A free optimization\n\nIf a function argument receives as input an object whose data type is\nany of the primitive types that we have listed in @sec-primitive-data-types,\nthis object is always passed by value to the function. In other words, this object\nis copied into the function stack frame.\n\nHowever, if the input object have a more complex data type, for example, it might\nbe a struct instance, or an array, or an union value, etc., in cases like that, the `zig` compiler\nwill take the liberty of deciding for you which strategy is best. Thus, the `zig` compiler will\npass your object to the function either by value, or by reference. The compiler will always\nchoose the strategy that is faster for you.\nThis optimization that you get for free is possible only because function arguments are\nimmutable in Zig.\n\n\n### How to overcome this barrier\n\nThere are some situations where you might need to change the value of your function argument\ndirectly inside the function's body. This happens more often when we are passing\nC structs as inputs to Zig functions.\n\nIn a situation like this, you can overcome this barrier by using a pointer. In other words,\ninstead of passing a value as input to the argument, you can pass a \"pointer to value\" instead.\nYou can change the value that the pointer points to, by dereferencing it.\n\nTherefore, if we take our previous `add2()` example, we can change the value of the\nfunction argument `x` inside the function's body by marking the `x` argument as a\n\"pointer to a `u32` value\" (i.e., `*u32` data type), instead of a `u32` value.\nBy making it a pointer, we can finally alter the value of this function argument directly inside\nthe body of the `add2()` function. You can see that the code example below compiles successfully.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n```\n:::\n\n\n\n\n```\nResult: 6\n```\n\n\nEven in this code example above, the `x` argument is still immutable. Which means that the pointer itself is immutable.\nTherefore, you cannot change the memory address that it points to. However, you can dereference the pointer\nto access the value that it points to, and also, to change this value, if you need to.\n\n\n\n\n\n## Structs and OOP {#sec-structs-and-oop}\n\nZig is a language more closely related to C (which is a procedural language),\nthan it is to C++ or Java (which are object-oriented languages). Because of that, you do not\nhave advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or\nclass inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\n\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C.\nYou give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can\nalso register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object\nthat you create with this new type, will always have these methods available and associated with them.\n\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which\nis used to construct (or, to instantiate) every object of this particular class, and we also have\na destructor method (or a destructor function), which is the function responsible for destroying\nevery object of this class.\n\nIn Zig, we normally declare the constructor and the destructor methods\nof our structs, by declaring an `init()` and a `deinit()` methods inside the struct.\nThis is just a naming convention that you will find across the entire Zig Standard Library.\nSo, in Zig, the `init()` method of a struct is normally the constructor method of the class represented by this struct.\nWhile the `deinit()` method is the method used for destroying an existing instance of that struct.\n\nThe `init()` and `deinit()` methods are both used extensively in Zig code, and you will see both of\nthem being used when we talk about allocators in @sec-allocators.\nBut, as another example, let's build a simple `User` struct to represent a user of some sort of system.\n\nIf you look at the `User` struct below, you can see the `struct` keyword.\nNotice the data members of this struct: `id`, `name` and `email`. Every data member has its\ntype explicitly annotated, with the colon character (`:`) syntax that we described earlier in @sec-root-file.\nBut also notice that every line in the struct body that describes a data member, ends with a comma character (`,`).\nSo every time you declare a data member in your Zig code, always end the line with a comma character, instead\nof ending it with the traditional semicolon character (`;`).\n\nNext, we have registered an `init()` function as a method\nof this `User` struct. This `init()` method is the constructor method that we will use to instantiate\nevery new `User` object. That is why this `init()` function returns a new `User` object as result.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    pub fn init(id: u64,\n                name: []const u8,\n                email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    pub fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\npedro\n```\n\n\n:::\n:::\n\n\n\n\nThe `pub` keyword plays an important role in struct declarations, and OOP in Zig.\nEvery method that you declare in your struct that is marked with the keyword `pub`,\nbecomes a public method of this particular struct.\n\nSo every method that you create inside your struct, is, at first, a private method\nof that struct. Meaning that, this method can only be called from within this\nstruct. But, if you mark this method as public, with the keyword `pub`, then,\nyou can call the method directly from an instance of the `User` struct.\n\nIn other words, the functions marked by the keyword `pub`\nare members of the public API of that struct.\nFor example, if I did not mark the `print_name()` method as public,\nthen, I could not execute the line `u.print_name()`. Because I would\nnot be authorized to call this method directly in my code.\n\n\n\n### Anonymous struct literals {#sec-anonymous-struct-literals}\n\nYou can declare a struct object as a literal value. When we do that, we normally specify the\ndata type of this struct literal by writing its data type just before the opening curly brace.\nFor example, I could write a struct literal value of the type `User` that we have defined\nin the previous section like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n```\n:::\n\n\n\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a\nstruct literal, but not specify explicitly the type of this particular struct.\nAn anonymous struct is written by using the syntax `.{}`. So, we essentially\nreplaced the explicit type of the struct literal with a dot character (`.`).\n\nAs we described in @sec-type-inference, when you put a dot before a struct literal,\nthe type of this struct literal is automatically inferred by the `zig` compiler.\nIn essence, the `zig` compiler will look for some hint of what is the type of that struct.\nThis hint can be the type annotation of a function argument,\nor the return type annotation of the function that you are using, or the type annotation\nof an existing object.\nIf the compiler does find such type annotation, it will use this\ntype in your literal struct.\n\nAnonymous structs are very commonly used as inputs to function arguments in Zig.\nOne example that you have seen already constantly, is the `print()`\nfunction from the `stdout` object.\nThis function takes two arguments.\nThe first argument, is a template string, which should\ncontain string format specifiers in it, which tells how the values provided\nin the second argument should be printed into the message.\n\nWhile the second argument is a struct literal that lists the values\nto be printed into the template message specified in the first argument.\nYou normally want to use an anonymous struct literal here, so that the\n`zig` compiler do the job of specifying the type of this particular\nanonymous struct for you.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello, world!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Struct declarations must be constant\n\nTypes in Zig must be `const` or `comptime` (we are going to talk more about comptime in @sec-comptime).\nWhat this means is that you cannot create a new data type, and mark it as variable with the `var` keyword.\nSo struct declarations are always constant. You cannot declare a new struct type using the `var` keyword.\nIt must be `const`.\n\nIn the `Vec3` example below, this declaration is allowed because I'm using the `const` keyword\nto declare this new data type.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n```\n:::\n\n\n\n\n\n### The `self` method argument {#sec-self-arg}\n\nIn every language that have OOP, when we declare a method of some class or struct, we\nusually declare this method as a function that has a `self` argument.\nThis `self` argument is the reference to the object itself from which the method\nis being called from.\n\nIt's not mandatory to use this `self` argument. But why would you not use this `self` argument?\nThere is no reason to not use it. Because the only way to get access to the data stored in the\ndata members of your struct is to access them through this `self` argument.\nIf you don't need to use the data in the data members of your struct inside your method, you very likely don't need\na method. You can just declare this logic as a simple function, outside of your\nstruct declaration.\n\n\nTake the `Vec3` struct below. Inside this `Vec3` struct we declared a method named `distance()`.\nThis method calculates the distance between two `Vec3` objects, by following the distance\nformula in euclidean space. Notice that this `distance()` method takes two `Vec3` objects\nas input, `self` and `other`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n```\n:::\n\n\n\n\n\nThe `self` argument corresponds to the `Vec3` object from which this `distance()` method\nis being called from. While the `other` is a separate `Vec3` object that is given as input\nto this method. In the example below, the `self` argument corresponds to the object\n`v1`, because the `distance()` method is being called from the `v1` object,\nwhile the `other` argument corresponds to the object `v2`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n```\n:::\n\n\n\n\n```\nDistance: 3.3970575502926055\n```\n\n\n\n### About the struct state\n\nSometimes you don't need to care about the state of your struct object. Sometimes, you just need\nto instantiate and use the objects, without altering their state. You can notice that when you have methods\ninside your struct declaration that might use the values that are present in the data members, but they\ndo not alter the values in these data members of the struct in anyway.\n\nThe `Vec3` struct that was presented in @sec-self-arg is an example of that.\nThis struct have a single method named `distance()`, and this method does use the values\npresent in all three data members of the struct (`x`, `y` and `z`). But at the same time,\nthis method does not change the values of these data members at any point.\n\nAs a result of that, when we create `Vec3` objects we usually create them as\nconstant objects, like the `v1` and `v2` objects presented in @sec-self-arg.\nWe can create them as variable objects with the `var` keyword,\nif we want to. But because the methods of this `Vec3` struct do not change\nthe state of the objects in any point, it's unnecessary to mark them\nas variable objects.\n\nBut why? Why am I talking about this here? It's because the `self` argument\nin the methods are affected depending on whether the\nmethods present in a struct change or don't change the state of the object itself.\nMore specifically, when you have a method in a struct that changes the state\nof the object (i.e., changes the value of a data member), the `self` argument\nin this method must be annotated in a different manner.\n\nAs I described in @sec-self-arg, the `self` argument in methods of\na struct is the argument that receives as input the object from which the method\nwas called from. We usually annotate this argument in the methods by writing `self`,\nfollowed by the colon character (`:`), and the data type of the struct to which\nthe method belongs to (e.g. `User`, `Vec3`, etc.).\n\nIf we take the `Vec3` struct that we defined in the previous section as an example,\nwe can see in the `distance()` method that this `self` argument is annotated as\n`self: Vec3`. Because the state of the `Vec3` object is never altered by this\nmethod.\n\nBut what if we do have a method that alters the state of the object, by altering the\nvalues of its data members, how should we annotate `self` in this instance? The answer is:\n\"we should annotate `self` as a pointer of `x`, instead of just `x`\".\nIn other words, you should annotate `self` as `self: *x`, instead of annotating it\nas `self: x`.\n\nIf we create a new method inside the `Vec3` object that, for example, expands the\nvector by multiplying its coordinates by a factor of two, then, we need to follow\nthis rule specified in the previous paragraph. The code example below demonstrates\nthis idea:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n```\n:::\n\n\n\n\nNotice in the code example above that we have added a new method\nto our `Vec3` struct named `twice()`. This method doubles the\ncoordinate values of our vector object. In the\ncase of the `twice()` method, we annotated the `self` argument as `*Vec3`,\nindicating that this argument receives a pointer (or a reference, if you prefer to call it this way)\nto a `Vec3` object as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n```\n:::\n\n\n\n\n```\nDoubled: 8.4\n```\n\n\n\nNow, if you change the `self` argument in this `twice()` method to `self: Vec3`, like in the\n`distance()` method, you will get the compiler error exposed below as result. Notice that this\nerror message is showing a line from the `twice()` method body,\nindicating that you cannot alter the value of the `x` data member.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n```\n:::\n\n\n\n\n```\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\n```\n\nThis error message indicates that the `x` data member belongs to a constant object,\nand, because of that, it cannot be changed. Ultimately, this error message\nis telling us that the `self` argument is constant.\n\nIf you take some time, and think hard about this error message, you will understand it.\nYou already have the tools to understand why we are getting this error message.\nWe have talked about it already in @sec-fun-pars.\nSo remember, every function argument is immutable in Zig, and `self`\nis no exception to this rule.\n\nIn this example, we marked the `v3` object as a variable object.\nBut this does not matter. Because it's not about the input object, it's about\nthe function argument.\n\nThe problem begins when we try to alter the value of `self` directly, which is a function argument,\nand, every function argument is immutable by default. You may ask yourself how can we overcome\nthis barrier, and once again, the solution was also discussed in @sec-fun-pars.\nWe overcome this barrier, by explicitly marking the `self` argument as a pointer.\n\n\n::: {.callout-note}\nIf a method of your `x` struct alters the state of the object, by\nchanging the value of any data member, then, remember to use `self: *x`,\ninstead of `self: x` in the function signature of this method.\n:::\n\n\nYou could also interpret the content discussed in this section as:\n\"if you need to alter the state of your `x` struct object in one of its methods,\nyou must explicitly pass the `x` struct object by reference to the `self` argument of this method\".\n\n\n\n## Type inference {#sec-type-inference}\n\nZig is a strongly typed language. But, there are some situations\nwhere you don't have to explicitly write the type of every single object in your source code,\nas you would expect from a traditional strongly typed language, such as C and C++.\n\nIn some situations, the `zig` compiler can use type inference to solve the data types for you, easing some of\nthe burden that you carry as a developer.\nThe most common way this happens is through function arguments that receive struct objects\nas input.\n\nIn general, type inference in Zig is done by using the dot character (`.`).\nEverytime you see a dot character written before a struct literal, or before an enum value, or something like that,\nyou know that this dot character is playing a special part in this place. More specifically, it's\ntelling the `zig` compiler something along the lines of: \"Hey! Can you infer the type of this\nvalue for me? Please!\". In other words, this dot character is playing a similar role as the `auto` keyword in C++.\n\nI gave you some examples of this in @sec-anonymous-struct-literals, where we used anonymous struct literals.\nAnonymous struct literals are, struct literals that use type inference to\ninfer the exact type of this particular struct literal.\nThis type inference is done by looking for some minimal hint of the correct data type to be used.\nYou could say that the `zig` compiler looks for any neighbouring type annotation that might tell it\nwhat the correct type would be.\n\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in @sec-switch).\nI also gave some other examples of type inference in @sec-switch, where we were inferring the data types of enum values listed inside\nof switch statements (e.g. `.DE`).\nBut as another example, take a look at this `fence()` function reproduced below,\nwhich comes from the [`atomic.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig)[^fence-fn]\nof the Zig Standard Library.\n\n[^fence-fn]: <https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig>.\n\nThere are a lot of things in this function that we haven't talked about yet, such as:\nwhat `comptime` means? `inline`? `extern`?\nLet's just ignore all of these things, and focus solely on the switch statement\nthat is inside this function.\n\nWe can see that this switch statement uses the `order` object as input. This `order`\nobject is one of the inputs of this `fence()` function, and we can see in the type annotation,\nthat this object is of type `AtomicOrder`. We can also see a bunch of values inside the\nswitch statements that begin with a dot character, such as `.release` and `.acquire`.\n\nBecause these weird values contain a dot character before them, we are asking the `zig`\ncompiler to infer the types of these values inside the switch statement. Then, the `zig`\ncompiler is looking into the current context where these values are being used, and trying\nto infer the types of these values.\n\nSince they are being used inside a switch statement, the `zig` compiler looks into the type\nof the input object given to the switch statement, which is the `order` object in this case.\nBecause this object have type `AtomicOrder`, the `zig` compiler infers that these values\nare data members from this type `AtomicOrder`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic => @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire => tsan.__tsan_acquire(addr),\n            .release => tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst => {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n```\n:::\n\n\n\n\nThis is how basic type inference is done in Zig. If we didn't use the dot character before\nthe values inside this switch statement, then, we would be forced to explicitly write\nthe data types of these values. For example, instead of writing `.release` we would have to\nwrite `AtomicOrder.release`. We would have to do this for every single value\nin this switch statement, and this is a lot of work. That is why type inference\nis commonly used on switch statements in Zig.\n\n\n\n## Type casting {#sec-type-cast}\n\nIn this section, I want to discuss type casting (or, type conversion) with you.\nWe use type casting when we have an object of type \"x\", and we want to convert\nit into an object of type \"y\", i.e., we want to change the data type of the object.\n\nMost languages have a formal way to perform type casting. In Rust for example, we normally\nuse the keyword `as`, and in C, we normally use the type casting syntax, e.g. `(int) x`.\nIn Zig, we use the `@as()` built-in function to cast an object of type \"x\", into\nan object of type \"y\".\n\nThis `@as()` function is the preferred way to perform type conversion (or type casting)\nin Zig. Because it's explicit, and, it also performs the casting only if it\nis unambiguous and safe. To use this function, you just provide the target data type\nin the first argument, and, the object that you want cast as the second argument.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file79ce58134f59.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\nThis is the general way to perform type casting in Zig. But remember, `@as()` works only when casting\nis unambiguous and safe. There are many situations where these assumptions do not hold. For example,\n\nwhen casting an integer value into a float value, or vice-versa, it's not clear to the compiler\nhow to perform this conversion safely.\n\nTherefore, we need to use specialized \"casting functions\" in such situations.\nFor example, if you want to cast an integer value into a float value, then, you\nshould use the `@floatFromInt()` function. In the inverse scenario, you should use\nthe `@intFromFloat()` function.\n\nIn these functions, you just provide the object that you want to\ncast as input. Then, the target data type of the \"type casting operation\" is determined by\nthe type annotation of the object where you are saving the results.\nIn the example below, we are casting the object `x` into a value of type `f32`,\nbecause the object `y`, which is where we are saving the results, is annotated\nas an object of type `f32`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file79ce286cee5b.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\nAnother built-in function that is very useful when performing type casting operations is `@ptrCast()`.\nIn essence, we use the `@as()` built-in function when we want to explicit convert (or cast) a Zig value/object\nfrom a type \"x\" to a type \"y\", etc. However, pointers (we are going to discuss pointers\nin more depth in @sec-pointer) are a special type of object in Zig,\ni.e., they are treated differently from \"normal objects\".\n\nEverytime a pointer is involved in some \"type casting operation\" in Zig, the `@ptrCast()` function is used.\nThis function works similarly to `@floatFromInt()`.\nYou just provide the pointer object that you want to cast as input to this function, and the\ntarget data type is, once again, determined by the type annotation of the object where the results are being\nstored.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file79ce1e7313c8.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## Modules\n\nWe already talked about what modules are, and also, how to import other modules into\nyour current module via *import statements*. Every Zig module (i.e., a `.zig` file) that you write in your project\nis internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the\nZig Standard Library into our current module.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n```\n:::\n\n\n\n\nWhen we want to access the functions and objects from the standard library, we\nare basically accessing the data members of the struct stored in the `std`\nobject. That is why we use the same syntax that we use in normal structs, with the dot operator (`.`)\nto access the data members and methods of the struct.\n\nWhen this \"import statement\" gets executed, the result of this expression is a struct\nobject that contains the Zig Standard Library modules, global variables, functions, etc.\nAnd this struct object gets saved (or stored) inside the constant object named `std`.\n\n\nTake the [`thread_pool.zig` module from the project `zap`](https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig)[^thread]\nas an example. This module is written as if it was\na big struct. That is why we have a top-level and public `init()` method\nwritten in this module. The idea is that all top-level functions written in this\nmodule are methods from the struct, and all top-level objects and struct declarations\nare data members of this struct. The module is the struct itself.\n\n[^thread]: <https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig>\n\n\nSo you would import and use this module by doing something like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst ThreadPool = @import(\"thread_pool.zig\");\nconst num_cpus = std.Thread.getCpuCount()\n    catch @panic(\"failed to get cpu core count\");\nconst num_threads = std.math.cast(u16, num_cpus)\n    catch std.math.maxInt(u16);\nconst pool = ThreadPool.init(\n    .{ .max_threads = num_threads }\n);\n```\n:::\n",
-    "supporting": [
-      "03-structs_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Control flow, structs, modules and types\n\nWe have discussed a lot of Zig's syntax in the last chapter,\nespecially in @sec-root-file and @sec-main-file.\nBut we still need to discuss some other very important\nelements of the language. Elements that you will use constantly on your day-to-day\nroutine.\n\nWe begin this chapter by discussing the different keywords and structures\nin Zig related to control flow (e.g. loops and if statements).\nThen, we talk about structs and how they can be used to do some\nbasic Object-Oriented (OOP) patterns in Zig. We also talk about\ntype inference and type casting.\nFinally, we end this chapter by discussing modules, and how they relate\nto structs.\n\n\n\n## Control flow {#sec-zig-control-flow}\n\nSometimes, you need to make decisions in your program. Maybe you need to decide\nwhether or not to execute a specific piece of code. Or maybe,\nyou need to apply the same operation over a sequence of values. These kinds of tasks,\ninvolve using structures that are capable of changing the \"control flow\" of our program.\n\nIn computer science, the term \"control flow\" usually refers to the order in which expressions (or commands)\nare evaluated in a given language or program. But this term is also used to refer\nto structures that are capable of changing this \"evaluation order\" of the commands\nexecuted by a given language/program.\n\nThese structures are better known\nby a set of terms, such as: loops, if/else statements, switch statements, among others. So,\nloops and if/else statements are examples of structures that can change the \"control\nflow\" of our program. The keywords `continue` and `break` are also examples of symbols\nthat can change the order of evaluation, since they can move our program to the next iteration\nof a loop, or make the loop stop completely.\n\n\n### If/else statements\n\nAn if/else statement performs a \"conditional flow operation\".\nA conditional flow control (or choice control) allows you to execute\nor ignore a certain block of commands based on a logical condition.\nMany programmers and computer science professionals also use\nthe term \"branching\" in this case.\nIn essence, an if/else statement allow us to use the result of a logical test\nto decide whether or not to execute a given block of commands.\n\nIn Zig, we write if/else statements by using the keywords `if` and `else`.\nWe start with the `if` keyword followed by a logical test inside a pair\nof parentheses, followed by a pair of curly braces which contains the lines\nof code to be executed in case the logical test returns the value `true`.\n\nAfter that, you can optionally add an `else` statement. To do that, just add the `else`\nkeyword followed by a pair of curly braces, with the lines of code\nto executed in case the logical test defined at `if` returns `false`.\n\nIn the example below, we are testing if the object `x` contains a number\nthat is greater than 10. Judging by the output printed to the console,\nwe know that this logical test returned `false`. Because the output\nin the console is compatible with the line of code present in the\n`else` branch of the if/else statement.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x = 5;\nif (x > 10) {\n    try stdout.print(\n        \"x > 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x <= 10!\\n\", .{}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nx <= 10!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n### Switch statements {#sec-switch}\n\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust.\nAs you would expect, to write a switch statement in Zig we use the `switch` keyword.\nWe provide the value that we want to \"switch over\" inside a\npair of parentheses. Then, we list the possible combinations (or \"branches\")\ninside a pair of curly braces.\n\nLet's take a look at the code example below. You can see that\nI'm creating an enum type called `Role`. We talk more about enums in @sec-enum.\nBut in summary, this `Role` type is listing different types of roles in a fictitious\ncompany, like `SE` for Software Engineer, `DE` for Data Engineer, `PM` for Product Manager,\netc.\n\nNotice that we are using the value from the `role` object in the\nswitch statement, to discover which exact area we need to store in the `area` variable object.\nAlso notice that we are using type inference inside the switch statement, with the dot character,\nas we are going to describe in @sec-type-inference.\nThis makes the `zig` compiler infer the correct data type of the values (`PM`, `SE`, etc.) for us.\n\nAlso notice that, we are grouping multiple values in the same branch of the switch statement.\nWe just separate each possible value with a comma. For example, if `role` contains either `DE` or `DA`,\nthe `area` variable would contain the value `\"Data & Analytics\"`, instead of `\"Platform\"` or `\"Sales\"`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO => {\n            area = \"Platform\";\n        },\n        .DE, .DA => {\n            area = \"Data & Analytics\";\n        },\n        .KS => {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nPlatform\n```\n\n\n:::\n:::\n\n\n\n\n\n\n#### Switch statements must exhaust all possibilities\n\nOne very important aspect about switch statements in Zig\nis that they must exhaust all existing possibilities.\nIn other words, all possible values that could be found inside the `role`\nobject must be explicitly handled in this switch statement.\n\nSince the `role` object has type `Role`, the only possible values to\nbe found inside this object are `PM`, `SE`, `DPE`, `PO`, `DE`, `DA` and `KS`.\nThere are no other possible values to be stored in this `role` object.\nThus, the switch statements must have a combination (branch) for each one of these values.\nThis is what \"exhaust all existing possibilities\" means. The switch statement covers\nevery possible case.\n\nTherefore, you cannot write a switch statement in Zig, and leave an edge case\nwith no explicit action to be taken.\nThis is a similar behaviour to switch statements in Rust, which also have to\nhandle all possible cases.\n\n\n\n#### The else branch\n\nTake a look at the `dump_hex_fallible()` function below as an example. This function\ncomes from the Zig Standard Library. More precisely, from the\n[`debug.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/debug.zig)[^debug-mod].\nThere are multiple lines in this function, but I omitted them to focus solely on the\nswitch statement found in this function. Notice that this switch statement has four\npossible cases (i.e., four explicit branches). Also, notice that we used an `else` branch\nin this case.\n\nAn `else` branch in a switch statement works as the \"default branch\".\nWhenever you have multiple cases in your switch statement where\nyou want to apply the exact same action, you can use an `else` branch to do that.\n\n[^debug-mod]: <https://github.com/ziglang/zig/blob/master/lib/std/debug.zig>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' => try writer.writeAll(\"␊\"),\n        '\\r' => try writer.writeAll(\"␍\"),\n        '\\t' => try writer.writeAll(\"␉\"),\n        else => try writer.writeByte('.'),\n    }\n}\n```\n:::\n\n\n\n\n\nMany programmers would also use an `else` branch to handle a \"not supported\" case.\nThat is, a case that cannot be properly handled by your code, or, just a case that\nshould not be \"fixed\". Therefore, you can use an `else` branch to panic (or raise an error)\nin your program to stop the current execution.\n\nTake the code example below. We can see that, we are handling the cases\nfor the `level` object being either 1, 2, or 3. All other possible cases are not supported by default,\nand, as consequence, we raise a runtime error in such cases through the `@panic()` built-in function.\n\nAlso notice that, we are assigning the result of the switch statement to a new object called `category`.\nThis is another thing that you can do with switch statements in Zig. If a branch\noutputs a value as result, you can store the result value of the switch statement into\na new object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 => \"beginner\",\n    3 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n:::\n\n\n\n\n\n```\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n```\n\n\n\n#### Using ranges in switch\n\nFurthermore, you can also use ranges of values in switch statements.\nThat is, you can create a branch in your switch statement that is used\nwhenever the input value is within the specified range. These \"range expressions\"\nare created with the operator `...`. It's important\nto emphasize that the ranges created by this operator are\ninclusive on both ends.\n\nFor example, I could easily change the previous code example to support all\nlevels between 0 and 100. Like this:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 => \"beginner\",\n    26...75 => \"intermediary\",\n    76...100 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nbeginner\n```\n\n\n:::\n:::\n\n\n\n\n\nThis is neat, and it works with character ranges too. That is, I could\nsimply write `'a'...'z'`, to match any character value that is a\nlowercase letter, and it would work fine.\n\n\n#### Labeled switch statements\n\nIn @sec-blocks we have talked about labeling blocks, and also, about using these labels\nto return a value from the block. Well, from version 0.14.0 and onwards of the `zig` compiler,\nyou can also apply labels over switch statements, which makes it possible to almost implement a\n\"C `goto`\" like pattern.\n\nFor example, if you give the label `xsw` to a switch statement, you can use this\nlabel in conjunction with the `continue` keyword to go back to the beginning of the switch\nstatement. In the example below, the execution goes back to the beginning of the\nswitch statement two times, before ending at the `3` branch.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nxsw: switch (@as(u8, 1)) {\n    1 => {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 => continue :xsw 3,\n    3 => return,\n    4 => {},\n    else => {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n```\n:::\n\n\n\n\n\n\n### The `defer` keyword {#sec-defer}\n\nWith the `defer` keyword you can register an expression to be executed when you exit the current scope.\nTherefore, this keyword has a similar functionality as the `on.exit()` function from R.\nTake the `foo()` function below as an example. When we execute this `foo()` function, the expression\nthat prints the message \"Exiting function ...\" is getting executed only when the function exits\nits scope.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n```\n:::\n\n\n\n\n\n```\nAdding some numbers ...\nMultiplying ...\nExiting function ...\n```\n\nTherefore, we can use `defer` to declare an expression that is going to be executed\nwhen your code exits the current scope. Some programmers like to interpret the phrase \"exit of the current scope\"\nas \"the end of the current scope\". But this interpretation might not be entirely correct, depending\non what you consider as \"the end of the current scope\".\n\nI mean, what do you consider as **the end** of the current scope? Is it the closing curly bracket (`}`) of the scope?\nIs it when the last expression in the function gets executed? Is it when the function returns to the previous scope?\nEtc. For example, it would not be correct to interpret the \"exit of the current scope\" as the closing\ncurly bracket of the scope. Because the function might exit from an earlier position than this\nclosing curly bracket (e.g. an error value was generated at a previous line inside the function;\nthe function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\n\nNow, if you remember of what we have discussed in @sec-blocks, there are multiple structures in the language\nthat create their own separate scopes. For/while loops, if/else statements,\nfunctions, normal blocks, etc. This also affects the interpretation of `defer`.\nFor example, if you use `defer` inside a for loop, then, the given expression\nwill be executed everytime this specific for loop exits its own scope.\n\nBefore we continue, it's worth emphasizing that the `defer` keyword is an \"unconditional defer\".\nWhich means that the given expression will be executed no matter how the code exits\nthe current scope. For example, your code might exit the current scope because of an error value\nbeing generated, or, because of a return statement, or, a break statement, etc.\n\n\n\n### The `errdefer` keyword {#sec-errdefer1}\n\nOn the previous section, we have discussed the `defer` keyword, which you can use to\nregister an expression to be executed at the exit of the current scope.\nBut this keyword has a brother, which is the `errdefer` keyword. While `defer`\nis an \"unconditional defer\", the `errdefer` keyword is a \"conditional defer\".\nWhich means that the given expression is executed only when you exit the current\nscope on a very specific circumstance.\n\nIn more details, the expression given to `errdefer` is executed only when an error occurs in the current scope.\nTherefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope\nin a normal situation, without errors, the expression given to `errdefer` is not executed.\n\nThis makes the `errdefer` keyword one of the many tools available in Zig for error handling.\nIn this section, we are more concerned with the control flow aspects around `errdefer`.\nBut we are going to discuss `errdefer` later as a error handling tool in @sec-errdefer2.\n\nThe code example below demonstrates three things:\n\n- that `defer` is an \"unconditional defer\", because the given expression gets executed regardless of how the function `foo()` exits its own scope.\n- that `errdefer` is executed because the function `foo()` returned an error value.\n- that `defer` and `errdefer` expressions are executed in a LIFO (*last in, first out*) order.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n```\n:::\n\n\n\n\n\n```\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\nWhen I say that \"defer expressions\" are executed in a LIFO order, what I want to say is that\nthe last `defer` or `errdefer` expressions in the code are the first ones to be executed.\nYou could also interpret this as: \"defer expressions\" are executed from bottom to top, or,\nfrom last to first.\n\nTherefore, if I change the order of the `defer` and `errdefer` expressions, you will notice that\nthe value of `i` that gets printed to the console changes to 1. This doesn't mean that the\n`defer` expression was not executed in this case. This actually means that the `defer` expression\nwas executed only after the `errdefer` expression. The code example below demonstrates this:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n```\n:::\n\n\n\n\n\n```\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\n\n\n### For loops\n\nA loop allows you to execute the same lines of code multiple times,\nthus, creating a \"repetition space\" in the execution flow of your program.\nLoops are particularly useful when we want to replicate the same function\n(or the same set of commands) over different inputs.\n\nThere are different types of loops available in Zig. But the most\nessential of them all is probably the *for loop*. A for loop is\nused to apply the same piece of code over the elements of a slice, or, an array.\n\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from\nother languages. You start with the `for` keyword, then, you\nlist the items that you want to iterate\nover inside a pair of parentheses. Then, inside of a pair of pipes (`|`)\nyou should declare an identifier that will serve as your iterator, or,\nthe \"repetition index of the loop\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (items) |value| {\n    // code to execute\n}\n```\n:::\n\n\n\n\n\nTherefore, instead of using a `(value in items)` syntax,\nin Zig, for loops use the syntax `(items) |value|`. In the example\nbelow, you can see that we are looping through the items\nof the array stored at the object `name`, and printing to the\nconsole the decimal representation of each character in this array.\n\nIf we wanted, we could also iterate through a slice (or a portion) of\nthe array, instead of iterating through the entire array stored in the `name` object.\nJust use a range selector to select the section you want. For example,\nI could provide the expression `name[0..3]` to the for loop, to iterate\njust through the first 3 elements in the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n80 | 101 | 100 | 114 | 111 | \n```\n\n\n:::\n:::\n\n\n\n\n\nIn the above example we are using the value itself of each\nelement in the array as our iterator. But there are many situations where\nwe need to use an index instead of the actual values of the items.\n\nYou can do that by providing a second set of items to iterate over.\nMore precisely, you provide the range selector `0..` to the for loop. So,\nyes, you can use two different iterators at the same time in a for\nloop in Zig.\n\nBut remember from @sec-assignments that, every object\nyou create in Zig must be used in some way. So if you declare two iterators\nin your for loop, you must use both iterators inside the for loop body.\nBut if you want to use just the index iterator, and not use the \"value iterator\",\nthen, you can discard the value iterator by maching the\nvalue items to the underscore character, like in the example below:\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n:::\n\n\n\n\n\n```\n0 | 1 | 2 | 3 | 4 |\n```\n\n\n### While loops\n\nA while loop is created from the `while` keyword. A `for` loop\niterates through the items of an array, but a `while` loop\nwill loop continuously, and infinitely, until a logical test\n(specified by you) becomes false.\n\nYou start with the `while` keyword, then, you define a logical\nexpression inside a pair of parentheses, and the body of the\nloop is provided inside a pair of curly braces, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\n\nYou can also specify the increment expression to be used at the beginning of a while loop.\nTo do that, we write the increment expression inside a pair of parentheses after a colon character (`:`).\nThe code example below demonstrates this other pattern.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\n\n### Using `break` and `continue`\n\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using\nthe keywords `break` and `continue`, respectively. The `while` loop presented in the next code example is,\nat first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to `true`.\nBut what makes this `while` loop stop when the `i` object reaches the count\n10? It's the `break` keyword!\n\nInside the while loop, we have an if statement that is constantly checking if the `i` variable\nis equal to 10. Since we are incrementing the value of `i` at each iteration of the\nwhile loop, this `i` object will eventually be equal to 10, and when it is, the if statement\nwill execute the `break` expression, and, as a result, the execution of the while loop is stopped.\n\nNotice the use of the `expect()` function from the Zig Standard Library after the while loop.\nThis `expect()` function is an \"assert\" type of function.\nThis function checks if the logical test provided is equal to true. If so, the function do nothing.\nOtherwise (i.e., the logical test is equal to false), the function raises an assertion error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nEverything worked!\n```\n\n\n:::\n:::\n\n\n\n\n\nSince this code example was executed successfully by the `zig` compiler,\nwithout raising any errors, we known that, after the execution of the while loop,\nthe `i` object is equal to 10. Because if it wasn't equal to 10, an error would have\nbeen raised by `expect()`.\n\nNow, in the next example, we have a use case for\nthe `continue` keyword. The if statement is constantly\nchecking if the current index is a multiple of 2. If\nit is, we jump to the next iteration of the loop.\nOtherwise, the loop just prints the current index to the console.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 3 | 5 | \n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n## Function parameters are immutable {#sec-fun-pars}\n\nWe have already discussed a lot of the syntax behind function declarations in @sec-root-file and @sec-main-file.\nBut I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig.\nIn summary, function parameters are immutable in Zig.\n\nTake the code example below, where we declare a simple function that just tries to add\nsome amount to the input integer, and returns the result back. If you look closely\nat the body of this `add2()` function, you will notice that we try\nto save the result back into the `x` function argument.\n\nIn other words, this function not only uses the value that it received through the function argument\n`x`, but it also tries to change the value of this function argument, by assigning the addition result\ninto `x`. However, function arguments in Zig are immutable. You cannot change their values, or, you\ncannot assign values to them inside the body's function.\n\nThis is the reason why, the code example below does not compile successfully. If you try to compile\nthis code example, you will get a compile error message about \"trying to change the value of a\nimmutable (i.e., constant) object\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n\n\n\n```\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n```\n\n\n### A free optimization\n\nIf a function argument receives as input an object whose data type is\nany of the primitive types that we have listed in @sec-primitive-data-types,\nthis object is always passed by value to the function. In other words, this object\nis copied into the function stack frame.\n\nHowever, if the input object have a more complex data type, for example, it might\nbe a struct instance, or an array, or an union value, etc., in cases like that, the `zig` compiler\nwill take the liberty of deciding for you which strategy is best. Thus, the `zig` compiler will\npass your object to the function either by value, or by reference. The compiler will always\nchoose the strategy that is faster for you.\nThis optimization that you get for free is possible only because function arguments are\nimmutable in Zig.\n\n\n### How to overcome this barrier\n\nThere are some situations where you might need to change the value of your function argument\ndirectly inside the function's body. This happens more often when we are passing\nC structs as inputs to Zig functions.\n\nIn a situation like this, you can overcome this barrier by using a pointer. In other words,\ninstead of passing a value as input to the argument, you can pass a \"pointer to value\" instead.\nYou can change the value that the pointer points to, by dereferencing it.\n\nTherefore, if we take our previous `add2()` example, we can change the value of the\nfunction argument `x` inside the function's body by marking the `x` argument as a\n\"pointer to a `u32` value\" (i.e., `*u32` data type), instead of a `u32` value.\nBy making it a pointer, we can finally alter the value of this function argument directly inside\nthe body of the `add2()` function. You can see that the code example below compiles successfully.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n```\n:::\n\n\n\n\n\n```\nResult: 6\n```\n\n\nEven in this code example above, the `x` argument is still immutable. Which means that the pointer itself is immutable.\nTherefore, you cannot change the memory address that it points to. However, you can dereference the pointer\nto access the value that it points to, and also, to change this value, if you need to.\n\n\n\n\n\n## Structs and OOP {#sec-structs-and-oop}\n\nZig is a language more closely related to C (which is a procedural language),\nthan it is to C++ or Java (which are object-oriented languages). Because of that, you do not\nhave advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or\nclass inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\n\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C.\nYou give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can\nalso register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object\nthat you create with this new type, will always have these methods available and associated with them.\n\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which\nis used to construct (or, to instantiate) every object of this particular class, and we also have\na destructor method (or a destructor function), which is the function responsible for destroying\nevery object of this class.\n\nIn Zig, we normally declare the constructor and the destructor methods\nof our structs, by declaring an `init()` and a `deinit()` methods inside the struct.\nThis is just a naming convention that you will find across the entire Zig Standard Library.\nSo, in Zig, the `init()` method of a struct is normally the constructor method of the class represented by this struct.\nWhile the `deinit()` method is the method used for destroying an existing instance of that struct.\n\nThe `init()` and `deinit()` methods are both used extensively in Zig code, and you will see both of\nthem being used when we talk about allocators in @sec-allocators.\nBut, as another example, let's build a simple `User` struct to represent a user of some sort of system.\n\nIf you look at the `User` struct below, you can see the `struct` keyword.\nNotice the data members of this struct: `id`, `name` and `email`. Every data member has its\ntype explicitly annotated, with the colon character (`:`) syntax that we described earlier in @sec-root-file.\nBut also notice that every line in the struct body that describes a data member, ends with a comma character (`,`).\nSo every time you declare a data member in your Zig code, always end the line with a comma character, instead\nof ending it with the traditional semicolon character (`;`).\n\nNext, we have registered an `init()` function as a method\nof this `User` struct. This `init()` method is the constructor method that we will use to instantiate\nevery new `User` object. That is why this `init()` function returns a new `User` object as result.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    fn init(id: u64,\n                name: []const u8,\n                email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\npedro\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n### The `pub` keyword\n\nThe `pub` keyword plays an important role in struct declarations, and OOP in Zig.\nIn essence, this keyword is short for \"public\", and it makes an item/component available outside of the\nmodule where this item/component is declared. In other words, if I don't apply the `pub` keyword on\nsomething, it means that this \"something\" is available to be called/used only from within the module\nwhere this \"something\" is declared.\n\nTo demonstrate the effect of this keyword let's focus again on the `User` struct that we have\ndeclared on the previous section. For our example here, let's suppose that this `User` struct is declared inside\na Zig module named `user.zig`. If I don't use the `pub` keyword on the `User` struct, it means that I can create\nan `User` object, and call it's methods (`print_name()` and `init()`) only from within the module where the `User`\nstruct is declared, which in this case is the `user.zig` module.\n\nThis is why the previous code example works fine. Because we declare and also use the `User` struct\ninside the same module. But problems start to arise when we try to import and call/use this struct\nfrom another module. For example, if I create a new module called `register.zig`, and import the `user.zig`\nmodule into it, and try to annotate any variable with the `User` type, I get an error from the compiler.\n\n```zig\n// register.zig\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = undefined;\n    _ = u;\n}\n```\n\n```\nregister.zig:3:18: error: 'User' is not marked 'pub'\n    const u: user.User = undefined;\n             ~~~~^~~~~\nuser.zig:3:1: note: declared here\nconst User = struct {\n^~~~~\n```\n\nTherefore, if you want to use something outside of the module where this \"something\" is declared,\nyou have to mark it with the `pub` keyword. This \"something\" can be a module,\na struct, a function, an object, etc.\n\nFor our example here, if we go back to the `user.zig` module, and add the `pub` keyword\nto the `User` struct declaration, then, I can successfully compile the `register.zig` module.\n\n```zig\n// user.zig\n// Added the `pub` keyword to `User`\npub const User = struct {\n// ...\n```\n\n```zig\n// register.zig\n// This works fine now!\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = undefined;\n    _ = u;\n}\n```\n\n\nNow, what do you think it will happen if I try to actually call from `register.zig` any of the methods\nof the `User` struct? For example, if I try to call the `init()` method? The answer is: I get a similar error message,\nwarning me that the `init()` method is not marked as `pub`, as you can see below:\n\n```zig\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = user.User.init(\n        1, \"pedro\", \"email@gmail.com\"\n    );\n    _ = u;\n}\n```\n\n```\nregister.zig:3:35: error: 'init' is not marked 'pub'\n    const u: user.User = user.User.init(\n                         ~~~~~~~~~^~~~~\nuser.zig:8:5: note: declared here\n    fn init(id: u64,\n    ^~~~~~~\n```\n\nThus, just because we have applied the `pub` keyword on the struct declaration,\nthis does not make the methods of that struct public as well. If we want to use\nany method from a struct (such as the `init()` method) outside of the module\nwhere this struct is declared, we have to mark this method with the `pub` keyword\nas well.\n\nGoing back to the `user.zig` module, and marking both the `init()` and `print_name()`\nmethods with the `pub` keyword, makes them both available to the outside world, and,\nas consequence, makes the previous code example work.\n\n\n```zig\n// user.zig\n// Added the `pub` keyword to `User.init`\n    pub fn init(\n// ...\n// Added the `pub` keyword to `User.print_name`\n    pub fn print_name(self: User) !void {\n// ...\n```\n\n```zig\n// register.zig\n// This works fine now!\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = user.User.init(\n        1, \"pedro\", \"email@gmail.com\"\n    );\n    _ = u;\n}\n```\n\n\n### Anonymous struct literals {#sec-anonymous-struct-literals}\n\nYou can declare a struct object as a literal value. When we do that, we normally specify the\ndata type of this struct literal by writing its data type just before the opening curly brace.\nFor example, I could write a struct literal value of the type `User` that we have defined\nin the previous section like this:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n```\n:::\n\n\n\n\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a\nstruct literal, but not specify explicitly the type of this particular struct.\nAn anonymous struct is written by using the syntax `.{}`. So, we essentially\nreplaced the explicit type of the struct literal with a dot character (`.`).\n\nAs we described in @sec-type-inference, when you put a dot before a struct literal,\nthe type of this struct literal is automatically inferred by the `zig` compiler.\nIn essence, the `zig` compiler will look for some hint of what is the type of that struct.\nThis hint can be the type annotation of a function argument,\nor the return type annotation of the function that you are using, or the type annotation\nof an existing object.\nIf the compiler does find such type annotation, it will use this\ntype in your literal struct.\n\nAnonymous structs are very commonly used as inputs to function arguments in Zig.\nOne example that you have seen already constantly, is the `print()`\nfunction from the `stdout` object.\nThis function takes two arguments.\nThe first argument, is a template string, which should\ncontain string format specifiers in it, which tells how the values provided\nin the second argument should be printed into the message.\n\nWhile the second argument is a struct literal that lists the values\nto be printed into the template message specified in the first argument.\nYou normally want to use an anonymous struct literal here, so that the\n`zig` compiler do the job of specifying the type of this particular\nanonymous struct for you.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello, world!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n### Struct declarations must be constant\n\nTypes in Zig must be `const` or `comptime` (we are going to talk more about comptime in @sec-comptime).\nWhat this means is that you cannot create a new data type, and mark it as variable with the `var` keyword.\nSo struct declarations are always constant. You cannot declare a new struct type using the `var` keyword.\nIt must be `const`.\n\nIn the `Vec3` example below, this declaration is allowed because I'm using the `const` keyword\nto declare this new data type.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n```\n:::\n\n\n\n\n\n\n### The `self` method argument {#sec-self-arg}\n\nIn every language that have OOP, when we declare a method of some class or struct, we\nusually declare this method as a function that has a `self` argument.\nThis `self` argument is the reference to the object itself from which the method\nis being called from.\n\nIt's not mandatory to use this `self` argument. But why would you not use this `self` argument?\nThere is no reason to not use it. Because the only way to get access to the data stored in the\ndata members of your struct is to access them through this `self` argument.\nIf you don't need to use the data in the data members of your struct inside your method, you very likely don't need\na method. You can just declare this logic as a simple function, outside of your\nstruct declaration.\n\n\nTake the `Vec3` struct below. Inside this `Vec3` struct we declared a method named `distance()`.\nThis method calculates the distance between two `Vec3` objects, by following the distance\nformula in euclidean space. Notice that this `distance()` method takes two `Vec3` objects\nas input, `self` and `other`.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n```\n:::\n\n\n\n\n\n\nThe `self` argument corresponds to the `Vec3` object from which this `distance()` method\nis being called from. While the `other` is a separate `Vec3` object that is given as input\nto this method. In the example below, the `self` argument corresponds to the object\n`v1`, because the `distance()` method is being called from the `v1` object,\nwhile the `other` argument corresponds to the object `v2`.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n```\n:::\n\n\n\n\n\n```\nDistance: 3.3970575502926055\n```\n\n\n\n### About the struct state\n\nSometimes you don't need to care about the state of your struct object. Sometimes, you just need\nto instantiate and use the objects, without altering their state. You can notice that when you have methods\ninside your struct declaration that might use the values that are present in the data members, but they\ndo not alter the values in these data members of the struct in anyway.\n\nThe `Vec3` struct that was presented in @sec-self-arg is an example of that.\nThis struct have a single method named `distance()`, and this method does use the values\npresent in all three data members of the struct (`x`, `y` and `z`). But at the same time,\nthis method does not change the values of these data members at any point.\n\nAs a result of that, when we create `Vec3` objects we usually create them as\nconstant objects, like the `v1` and `v2` objects presented in @sec-self-arg.\nWe can create them as variable objects with the `var` keyword,\nif we want to. But because the methods of this `Vec3` struct do not change\nthe state of the objects in any point, it's unnecessary to mark them\nas variable objects.\n\nBut why? Why am I talking about this here? It's because the `self` argument\nin the methods are affected depending on whether the\nmethods present in a struct change or don't change the state of the object itself.\nMore specifically, when you have a method in a struct that changes the state\nof the object (i.e., changes the value of a data member), the `self` argument\nin this method must be annotated in a different manner.\n\nAs I described in @sec-self-arg, the `self` argument in methods of\na struct is the argument that receives as input the object from which the method\nwas called from. We usually annotate this argument in the methods by writing `self`,\nfollowed by the colon character (`:`), and the data type of the struct to which\nthe method belongs to (e.g. `User`, `Vec3`, etc.).\n\nIf we take the `Vec3` struct that we defined in the previous section as an example,\nwe can see in the `distance()` method that this `self` argument is annotated as\n`self: Vec3`. Because the state of the `Vec3` object is never altered by this\nmethod.\n\nBut what if we do have a method that alters the state of the object, by altering the\nvalues of its data members, how should we annotate `self` in this instance? The answer is:\n\"we should annotate `self` as a pointer of `x`, instead of just `x`\".\nIn other words, you should annotate `self` as `self: *x`, instead of annotating it\nas `self: x`.\n\nIf we create a new method inside the `Vec3` object that, for example, expands the\nvector by multiplying its coordinates by a factor of two, then, we need to follow\nthis rule specified in the previous paragraph. The code example below demonstrates\nthis idea:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n```\n:::\n\n\n\n\n\nNotice in the code example above that we have added a new method\nto our `Vec3` struct named `twice()`. This method doubles the\ncoordinate values of our vector object. In the\ncase of the `twice()` method, we annotated the `self` argument as `*Vec3`,\nindicating that this argument receives a pointer (or a reference, if you prefer to call it this way)\nto a `Vec3` object as input.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n```\n:::\n\n\n\n\n\n```\nDoubled: 8.4\n```\n\n\n\nNow, if you change the `self` argument in this `twice()` method to `self: Vec3`, like in the\n`distance()` method, you will get the compiler error exposed below as result. Notice that this\nerror message is showing a line from the `twice()` method body,\nindicating that you cannot alter the value of the `x` data member.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n```\n:::\n\n\n\n\n\n```\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\n```\n\nThis error message indicates that the `x` data member belongs to a constant object,\nand, because of that, it cannot be changed. Ultimately, this error message\nis telling us that the `self` argument is constant.\n\nIf you take some time, and think hard about this error message, you will understand it.\nYou already have the tools to understand why we are getting this error message.\nWe have talked about it already in @sec-fun-pars.\nSo remember, every function argument is immutable in Zig, and `self`\nis no exception to this rule.\n\nIn this example, we marked the `v3` object as a variable object.\nBut this does not matter. Because it's not about the input object, it's about\nthe function argument.\n\nThe problem begins when we try to alter the value of `self` directly, which is a function argument,\nand, every function argument is immutable by default. You may ask yourself how can we overcome\nthis barrier, and once again, the solution was also discussed in @sec-fun-pars.\nWe overcome this barrier, by explicitly marking the `self` argument as a pointer.\n\n\n::: {.callout-note}\nIf a method of your `x` struct alters the state of the object, by\nchanging the value of any data member, then, remember to use `self: *x`,\ninstead of `self: x` in the function signature of this method.\n:::\n\n\nYou could also interpret the content discussed in this section as:\n\"if you need to alter the state of your `x` struct object in one of its methods,\nyou must explicitly pass the `x` struct object by reference to the `self` argument of this method\".\n\n\n\n## Type inference {#sec-type-inference}\n\nZig is a strongly typed language. But, there are some situations\nwhere you don't have to explicitly write the type of every single object in your source code,\nas you would expect from a traditional strongly typed language, such as C and C++.\n\nIn some situations, the `zig` compiler can use type inference to solve the data types for you, easing some of\nthe burden that you carry as a developer.\nThe most common way this happens is through function arguments that receive struct objects\nas input.\n\nIn general, type inference in Zig is done by using the dot character (`.`).\nEverytime you see a dot character written before a struct literal, or before an enum value, or something like that,\nyou know that this dot character is playing a special part in this place. More specifically, it's\ntelling the `zig` compiler something along the lines of: \"Hey! Can you infer the type of this\nvalue for me? Please!\". In other words, this dot character is playing a similar role as the `auto` keyword in C++.\n\nI gave you some examples of this in @sec-anonymous-struct-literals, where we used anonymous struct literals.\nAnonymous struct literals are, struct literals that use type inference to\ninfer the exact type of this particular struct literal.\nThis type inference is done by looking for some minimal hint of the correct data type to be used.\nYou could say that the `zig` compiler looks for any neighbouring type annotation that might tell it\nwhat the correct type would be.\n\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in @sec-switch).\nI also gave some other examples of type inference in @sec-switch, where we were inferring the data types of enum values listed inside\nof switch statements (e.g. `.DE`).\nBut as another example, take a look at this `fence()` function reproduced below,\nwhich comes from the [`atomic.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig)[^fence-fn]\nof the Zig Standard Library.\n\n[^fence-fn]: <https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig>.\n\nThere are a lot of things in this function that we haven't talked about yet, such as:\nwhat `comptime` means? `inline`? `extern`?\nLet's just ignore all of these things, and focus solely on the switch statement\nthat is inside this function.\n\nWe can see that this switch statement uses the `order` object as input. This `order`\nobject is one of the inputs of this `fence()` function, and we can see in the type annotation,\nthat this object is of type `AtomicOrder`. We can also see a bunch of values inside the\nswitch statements that begin with a dot character, such as `.release` and `.acquire`.\n\nBecause these weird values contain a dot character before them, we are asking the `zig`\ncompiler to infer the types of these values inside the switch statement. Then, the `zig`\ncompiler is looking into the current context where these values are being used, and trying\nto infer the types of these values.\n\nSince they are being used inside a switch statement, the `zig` compiler looks into the type\nof the input object given to the switch statement, which is the `order` object in this case.\nBecause this object have type `AtomicOrder`, the `zig` compiler infers that these values\nare data members from this type `AtomicOrder`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic => @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire => tsan.__tsan_acquire(addr),\n            .release => tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst => {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n```\n:::\n\n\n\n\n\nThis is how basic type inference is done in Zig. If we didn't use the dot character before\nthe values inside this switch statement, then, we would be forced to explicitly write\nthe data types of these values. For example, instead of writing `.release` we would have to\nwrite `AtomicOrder.release`. We would have to do this for every single value\nin this switch statement, and this is a lot of work. That is why type inference\nis commonly used on switch statements in Zig.\n\n\n\n## Type casting {#sec-type-cast}\n\nIn this section, I want to discuss type casting (or, type conversion) with you.\nWe use type casting when we have an object of type \"x\", and we want to convert\nit into an object of type \"y\", i.e., we want to change the data type of the object.\n\nMost languages have a formal way to perform type casting. In Rust for example, we normally\nuse the keyword `as`, and in C, we normally use the type casting syntax, e.g. `(int) x`.\nIn Zig, we use the `@as()` built-in function to cast an object of type \"x\", into\nan object of type \"y\".\n\nThis `@as()` function is the preferred way to perform type conversion (or type casting)\nin Zig. Because it's explicit, and, it also performs the casting only if it\nis unambiguous and safe. To use this function, you just provide the target data type\nin the first argument, and, the object that you want cast as the second argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file3c448aa9d5f.test_0...OKAll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\nThis is the general way to perform type casting in Zig. But remember, `@as()` works only when casting\nis unambiguous and safe. There are many situations where these assumptions do not hold. For example,\n\nwhen casting an integer value into a float value, or vice-versa, it's not clear to the compiler\nhow to perform this conversion safely.\n\nTherefore, we need to use specialized \"casting functions\" in such situations.\nFor example, if you want to cast an integer value into a float value, then, you\nshould use the `@floatFromInt()` function. In the inverse scenario, you should use\nthe `@intFromFloat()` function.\n\nIn these functions, you just provide the object that you want to\ncast as input. Then, the target data type of the \"type casting operation\" is determined by\nthe type annotation of the object where you are saving the results.\nIn the example below, we are casting the object `x` into a value of type `f32`,\nbecause the object `y`, which is where we are saving the results, is annotated\nas an object of type `f32`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file3c4427337b66.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\n\nAnother built-in function that is very useful when performing type casting operations is `@ptrCast()`.\nIn essence, we use the `@as()` built-in function when we want to explicit convert (or cast) a Zig value/object\nfrom a type \"x\" to a type \"y\", etc. However, pointers (we are going to discuss pointers\nin more depth in @sec-pointer) are a special type of object in Zig,\ni.e., they are treated differently from \"normal objects\".\n\nEverytime a pointer is involved in some \"type casting operation\" in Zig, the `@ptrCast()` function is used.\nThis function works similarly to `@floatFromInt()`.\nYou just provide the pointer object that you want to cast as input to this function, and the\ntarget data type is, once again, determined by the type annotation of the object where the results are being\nstored.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file3c4479f1f6f8.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n\n## Modules\n\nWe already talked about what modules are, and also, how to import other modules into\nyour current module via *import statements*. Every Zig module (i.e., a `.zig` file) that you write in your project\nis internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the\nZig Standard Library into our current module.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n```\n:::\n\n\n\n\n\nWhen we want to access the functions and objects from the standard library, we\nare basically accessing the data members of the struct stored in the `std`\nobject. That is why we use the same syntax that we use in normal structs, with the dot operator (`.`)\nto access the data members and methods of the struct.\n\nWhen this \"import statement\" gets executed, the result of this expression is a struct\nobject that contains the Zig Standard Library modules, global variables, functions, etc.\nAnd this struct object gets saved (or stored) inside the constant object named `std`.\n\n\nTake the [`thread_pool.zig` module from the project `zap`](https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig)[^thread]\nas an example. This module is written as if it was\na big struct. That is why we have a top-level and public `init()` method\nwritten in this module. The idea is that all top-level functions written in this\nmodule are methods from the struct, and all top-level objects and struct declarations\nare data members of this struct. The module is the struct itself.\n\n[^thread]: <https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig>\n\n\nSo you would import and use this module by doing something like this:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst ThreadPool = @import(\"thread_pool.zig\");\nconst num_cpus = std.Thread.getCpuCount()\n    catch @panic(\"failed to get cpu core count\");\nconst num_threads = std.math.cast(u16, num_cpus)\n    catch std.math.maxInt(u16);\nconst pool = ThreadPool.init(\n    .{ .max_threads = num_threads }\n);\n```\n:::\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/docs/Chapters/03-structs.html b/docs/Chapters/03-structs.html
index 7c8203c7..5c0fd596 100644
--- a/docs/Chapters/03-structs.html
+++ b/docs/Chapters/03-structs.html
@@ -295,10 +295,11 @@ <h2 id="toc-title">Table of contents</h2>
   </ul></li>
   <li><a href="#sec-structs-and-oop" id="toc-sec-structs-and-oop" class="nav-link" data-scroll-target="#sec-structs-and-oop"><span class="header-section-number">2.3</span> Structs and OOP</a>
   <ul class="collapse">
-  <li><a href="#sec-anonymous-struct-literals" id="toc-sec-anonymous-struct-literals" class="nav-link" data-scroll-target="#sec-anonymous-struct-literals"><span class="header-section-number">2.3.1</span> Anonymous struct literals</a></li>
-  <li><a href="#struct-declarations-must-be-constant" id="toc-struct-declarations-must-be-constant" class="nav-link" data-scroll-target="#struct-declarations-must-be-constant"><span class="header-section-number">2.3.2</span> Struct declarations must be constant</a></li>
-  <li><a href="#sec-self-arg" id="toc-sec-self-arg" class="nav-link" data-scroll-target="#sec-self-arg"><span class="header-section-number">2.3.3</span> The <code>self</code> method argument</a></li>
-  <li><a href="#about-the-struct-state" id="toc-about-the-struct-state" class="nav-link" data-scroll-target="#about-the-struct-state"><span class="header-section-number">2.3.4</span> About the struct state</a></li>
+  <li><a href="#the-pub-keyword" id="toc-the-pub-keyword" class="nav-link" data-scroll-target="#the-pub-keyword"><span class="header-section-number">2.3.1</span> The <code>pub</code> keyword</a></li>
+  <li><a href="#sec-anonymous-struct-literals" id="toc-sec-anonymous-struct-literals" class="nav-link" data-scroll-target="#sec-anonymous-struct-literals"><span class="header-section-number">2.3.2</span> Anonymous struct literals</a></li>
+  <li><a href="#struct-declarations-must-be-constant" id="toc-struct-declarations-must-be-constant" class="nav-link" data-scroll-target="#struct-declarations-must-be-constant"><span class="header-section-number">2.3.3</span> Struct declarations must be constant</a></li>
+  <li><a href="#sec-self-arg" id="toc-sec-self-arg" class="nav-link" data-scroll-target="#sec-self-arg"><span class="header-section-number">2.3.4</span> The <code>self</code> method argument</a></li>
+  <li><a href="#about-the-struct-state" id="toc-about-the-struct-state" class="nav-link" data-scroll-target="#about-the-struct-state"><span class="header-section-number">2.3.5</span> About the struct state</a></li>
   </ul></li>
   <li><a href="#sec-type-inference" id="toc-sec-type-inference" class="nav-link" data-scroll-target="#sec-type-inference"><span class="header-section-number">2.4</span> Type inference</a></li>
   <li><a href="#sec-type-cast" id="toc-sec-type-cast" class="nav-link" data-scroll-target="#sec-type-cast"><span class="header-section-number">2.5</span> Type casting</a></li>
@@ -702,7 +703,7 @@ <h2 data-number="2.3" class="anchored" data-anchor-id="sec-structs-and-oop"><spa
 <span id="cb34-5"><a href="#cb34-5" aria-hidden="true" tabindex="-1"></a>    name: []<span class="kw">const</span> <span class="dt">u8</span>,</span>
 <span id="cb34-6"><a href="#cb34-6" aria-hidden="true" tabindex="-1"></a>    email: []<span class="kw">const</span> <span class="dt">u8</span>,</span>
 <span id="cb34-7"><a href="#cb34-7" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb34-8"><a href="#cb34-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> init(id: <span class="dt">u64</span>,</span>
+<span id="cb34-8"><a href="#cb34-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">fn</span> init(id: <span class="dt">u64</span>,</span>
 <span id="cb34-9"><a href="#cb34-9" aria-hidden="true" tabindex="-1"></a>                name: []<span class="kw">const</span> <span class="dt">u8</span>,</span>
 <span id="cb34-10"><a href="#cb34-10" aria-hidden="true" tabindex="-1"></a>                email: []<span class="kw">const</span> <span class="dt">u8</span>) User <span class="op">{</span></span>
 <span id="cb34-11"><a href="#cb34-11" aria-hidden="true" tabindex="-1"></a></span>
@@ -713,7 +714,7 @@ <h2 data-number="2.3" class="anchored" data-anchor-id="sec-structs-and-oop"><spa
 <span id="cb34-16"><a href="#cb34-16" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span>;</span>
 <span id="cb34-17"><a href="#cb34-17" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
 <span id="cb34-18"><a href="#cb34-18" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb34-19"><a href="#cb34-19" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> print_name(self: User) !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb34-19"><a href="#cb34-19" aria-hidden="true" tabindex="-1"></a>    <span class="kw">fn</span> print_name(self: User) !<span class="dt">void</span> <span class="op">{</span></span>
 <span id="cb34-20"><a href="#cb34-20" aria-hidden="true" tabindex="-1"></a>        <span class="kw">try</span> stdout.print(<span class="st">"{s}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>self.name<span class="op">}</span>);</span>
 <span id="cb34-21"><a href="#cb34-21" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
 <span id="cb34-22"><a href="#cb34-22" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
@@ -726,129 +727,189 @@ <h2 data-number="2.3" class="anchored" data-anchor-id="sec-structs-and-oop"><spa
 <pre><code>pedro</code></pre>
 </div>
 </div>
-<p>The <code>pub</code> keyword plays an important role in struct declarations, and OOP in Zig. Every method that you declare in your struct that is marked with the keyword <code>pub</code>, becomes a public method of this particular struct.</p>
-<p>So every method that you create inside your struct, is, at first, a private method of that struct. Meaning that, this method can only be called from within this struct. But, if you mark this method as public, with the keyword <code>pub</code>, then, you can call the method directly from an instance of the <code>User</code> struct.</p>
-<p>In other words, the functions marked by the keyword <code>pub</code> are members of the public API of that struct. For example, if I did not mark the <code>print_name()</code> method as public, then, I could not execute the line <code>u.print_name()</code>. Because I would not be authorized to call this method directly in my code.</p>
-<section id="sec-anonymous-struct-literals" class="level3" data-number="2.3.1">
-<h3 data-number="2.3.1" class="anchored" data-anchor-id="sec-anonymous-struct-literals"><span class="header-section-number">2.3.1</span> Anonymous struct literals</h3>
+<section id="the-pub-keyword" class="level3" data-number="2.3.1">
+<h3 data-number="2.3.1" class="anchored" data-anchor-id="the-pub-keyword"><span class="header-section-number">2.3.1</span> The <code>pub</code> keyword</h3>
+<p>The <code>pub</code> keyword plays an important role in struct declarations, and OOP in Zig. In essence, this keyword is short for “public”, and it makes an item/component available outside of the module where this item/component is declared. In other words, if I don’t apply the <code>pub</code> keyword on something, it means that this “something” is available to be called/used only from within the module where this “something” is declared.</p>
+<p>To demonstrate the effect of this keyword let’s focus again on the <code>User</code> struct that we have declared on the previous section. For our example here, let’s suppose that this <code>User</code> struct is declared inside a Zig module named <code>user.zig</code>. If I don’t use the <code>pub</code> keyword on the <code>User</code> struct, it means that I can create an <code>User</code> object, and call it’s methods (<code>print_name()</code> and <code>init()</code>) only from within the module where the <code>User</code> struct is declared, which in this case is the <code>user.zig</code> module.</p>
+<p>This is why the previous code example works fine. Because we declare and also use the <code>User</code> struct inside the same module. But problems start to arise when we try to import and call/use this struct from another module. For example, if I create a new module called <code>register.zig</code>, and import the <code>user.zig</code> module into it, and try to annotate any variable with the <code>User</code> type, I get an error from the compiler.</p>
+<div class="sourceCode" id="cb36"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb36-1"><a href="#cb36-1" aria-hidden="true" tabindex="-1"></a><span class="co">// register.zig</span></span>
+<span id="cb36-2"><a href="#cb36-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> user = <span class="bu">@import</span>(<span class="st">"user.zig"</span>);</span>
+<span id="cb36-3"><a href="#cb36-3" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb36-4"><a href="#cb36-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> u: user.User = <span class="cn">undefined</span>;</span>
+<span id="cb36-5"><a href="#cb36-5" aria-hidden="true" tabindex="-1"></a>    _ = u;</span>
+<span id="cb36-6"><a href="#cb36-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<pre><code>register.zig:3:18: error: 'User' is not marked 'pub'
+    const u: user.User = undefined;
+             ~~~~^~~~~
+user.zig:3:1: note: declared here
+const User = struct {
+^~~~~</code></pre>
+<p>Therefore, if you want to use something outside of the module where this “something” is declared, you have to mark it with the <code>pub</code> keyword. This “something” can be a module, a struct, a function, an object, etc.</p>
+<p>For our example here, if we go back to the <code>user.zig</code> module, and add the <code>pub</code> keyword to the <code>User</code> struct declaration, then, I can successfully compile the <code>register.zig</code> module.</p>
+<div class="sourceCode" id="cb38"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb38-1"><a href="#cb38-1" aria-hidden="true" tabindex="-1"></a><span class="co">// user.zig</span></span>
+<span id="cb38-2"><a href="#cb38-2" aria-hidden="true" tabindex="-1"></a><span class="co">// Added the `pub` keyword to `User`</span></span>
+<span id="cb38-3"><a href="#cb38-3" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">const</span> User = <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb38-4"><a href="#cb38-4" aria-hidden="true" tabindex="-1"></a><span class="co">// ...</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode" id="cb39"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb39-1"><a href="#cb39-1" aria-hidden="true" tabindex="-1"></a><span class="co">// register.zig</span></span>
+<span id="cb39-2"><a href="#cb39-2" aria-hidden="true" tabindex="-1"></a><span class="co">// This works fine now!</span></span>
+<span id="cb39-3"><a href="#cb39-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> user = <span class="bu">@import</span>(<span class="st">"user.zig"</span>);</span>
+<span id="cb39-4"><a href="#cb39-4" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb39-5"><a href="#cb39-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> u: user.User = <span class="cn">undefined</span>;</span>
+<span id="cb39-6"><a href="#cb39-6" aria-hidden="true" tabindex="-1"></a>    _ = u;</span>
+<span id="cb39-7"><a href="#cb39-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<p>Now, what do you think it will happen if I try to actually call from <code>register.zig</code> any of the methods of the <code>User</code> struct? For example, if I try to call the <code>init()</code> method? The answer is: I get a similar error message, warning me that the <code>init()</code> method is not marked as <code>pub</code>, as you can see below:</p>
+<div class="sourceCode" id="cb40"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb40-1"><a href="#cb40-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> user = <span class="bu">@import</span>(<span class="st">"user.zig"</span>);</span>
+<span id="cb40-2"><a href="#cb40-2" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb40-3"><a href="#cb40-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> u: user.User = user.User.init(</span>
+<span id="cb40-4"><a href="#cb40-4" aria-hidden="true" tabindex="-1"></a>        <span class="dv">1</span>, <span class="st">"pedro"</span>, <span class="st">"email@gmail.com"</span></span>
+<span id="cb40-5"><a href="#cb40-5" aria-hidden="true" tabindex="-1"></a>    );</span>
+<span id="cb40-6"><a href="#cb40-6" aria-hidden="true" tabindex="-1"></a>    _ = u;</span>
+<span id="cb40-7"><a href="#cb40-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<pre><code>register.zig:3:35: error: 'init' is not marked 'pub'
+    const u: user.User = user.User.init(
+                         ~~~~~~~~~^~~~~
+user.zig:8:5: note: declared here
+    fn init(id: u64,
+    ^~~~~~~</code></pre>
+<p>Thus, just because we have applied the <code>pub</code> keyword on the struct declaration, this does not make the methods of that struct public as well. If we want to use any method from a struct (such as the <code>init()</code> method) outside of the module where this struct is declared, we have to mark this method with the <code>pub</code> keyword as well.</p>
+<p>Going back to the <code>user.zig</code> module, and marking both the <code>init()</code> and <code>print_name()</code> methods with the <code>pub</code> keyword, makes them both available to the outside world, and, as consequence, makes the previous code example work.</p>
+<div class="sourceCode" id="cb42"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb42-1"><a href="#cb42-1" aria-hidden="true" tabindex="-1"></a><span class="co">// user.zig</span></span>
+<span id="cb42-2"><a href="#cb42-2" aria-hidden="true" tabindex="-1"></a><span class="co">// Added the `pub` keyword to `User.init`</span></span>
+<span id="cb42-3"><a href="#cb42-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> init(</span>
+<span id="cb42-4"><a href="#cb42-4" aria-hidden="true" tabindex="-1"></a><span class="co">// ...</span></span>
+<span id="cb42-5"><a href="#cb42-5" aria-hidden="true" tabindex="-1"></a><span class="co">// Added the `pub` keyword to `User.print_name`</span></span>
+<span id="cb42-6"><a href="#cb42-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> print_name(self: User) !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb42-7"><a href="#cb42-7" aria-hidden="true" tabindex="-1"></a><span class="co">// ...</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode" id="cb43"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb43-1"><a href="#cb43-1" aria-hidden="true" tabindex="-1"></a><span class="co">// register.zig</span></span>
+<span id="cb43-2"><a href="#cb43-2" aria-hidden="true" tabindex="-1"></a><span class="co">// This works fine now!</span></span>
+<span id="cb43-3"><a href="#cb43-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> user = <span class="bu">@import</span>(<span class="st">"user.zig"</span>);</span>
+<span id="cb43-4"><a href="#cb43-4" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb43-5"><a href="#cb43-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> u: user.User = user.User.init(</span>
+<span id="cb43-6"><a href="#cb43-6" aria-hidden="true" tabindex="-1"></a>        <span class="dv">1</span>, <span class="st">"pedro"</span>, <span class="st">"email@gmail.com"</span></span>
+<span id="cb43-7"><a href="#cb43-7" aria-hidden="true" tabindex="-1"></a>    );</span>
+<span id="cb43-8"><a href="#cb43-8" aria-hidden="true" tabindex="-1"></a>    _ = u;</span>
+<span id="cb43-9"><a href="#cb43-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+</section>
+<section id="sec-anonymous-struct-literals" class="level3" data-number="2.3.2">
+<h3 data-number="2.3.2" class="anchored" data-anchor-id="sec-anonymous-struct-literals"><span class="header-section-number">2.3.2</span> Anonymous struct literals</h3>
 <p>You can declare a struct object as a literal value. When we do that, we normally specify the data type of this struct literal by writing its data type just before the opening curly brace. For example, I could write a struct literal value of the type <code>User</code> that we have defined in the previous section like this:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb36"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb36-1"><a href="#cb36-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> eu = User <span class="op">{</span></span>
-<span id="cb36-2"><a href="#cb36-2" aria-hidden="true" tabindex="-1"></a>    .id = <span class="dv">1</span>,</span>
-<span id="cb36-3"><a href="#cb36-3" aria-hidden="true" tabindex="-1"></a>    .name = <span class="st">"Pedro"</span>,</span>
-<span id="cb36-4"><a href="#cb36-4" aria-hidden="true" tabindex="-1"></a>    .email = <span class="st">"someemail@gmail.com"</span></span>
-<span id="cb36-5"><a href="#cb36-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
-<span id="cb36-6"><a href="#cb36-6" aria-hidden="true" tabindex="-1"></a>_ = eu;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb44"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb44-1"><a href="#cb44-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> eu = User <span class="op">{</span></span>
+<span id="cb44-2"><a href="#cb44-2" aria-hidden="true" tabindex="-1"></a>    .id = <span class="dv">1</span>,</span>
+<span id="cb44-3"><a href="#cb44-3" aria-hidden="true" tabindex="-1"></a>    .name = <span class="st">"Pedro"</span>,</span>
+<span id="cb44-4"><a href="#cb44-4" aria-hidden="true" tabindex="-1"></a>    .email = <span class="st">"someemail@gmail.com"</span></span>
+<span id="cb44-5"><a href="#cb44-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
+<span id="cb44-6"><a href="#cb44-6" aria-hidden="true" tabindex="-1"></a>_ = eu;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>However, in Zig, we can also write an anonymous struct literal. That is, you can write a struct literal, but not specify explicitly the type of this particular struct. An anonymous struct is written by using the syntax <code>.{}</code>. So, we essentially replaced the explicit type of the struct literal with a dot character (<code>.</code>).</p>
 <p>As we described in <a href="#sec-type-inference" class="quarto-xref"><span>Section 2.4</span></a>, when you put a dot before a struct literal, the type of this struct literal is automatically inferred by the <code>zig</code> compiler. In essence, the <code>zig</code> compiler will look for some hint of what is the type of that struct. This hint can be the type annotation of a function argument, or the return type annotation of the function that you are using, or the type annotation of an existing object. If the compiler does find such type annotation, it will use this type in your literal struct.</p>
 <p>Anonymous structs are very commonly used as inputs to function arguments in Zig. One example that you have seen already constantly, is the <code>print()</code> function from the <code>stdout</code> object. This function takes two arguments. The first argument, is a template string, which should contain string format specifiers in it, which tells how the values provided in the second argument should be printed into the message.</p>
 <p>While the second argument is a struct literal that lists the values to be printed into the template message specified in the first argument. You normally want to use an anonymous struct literal here, so that the <code>zig</code> compiler do the job of specifying the type of this particular anonymous struct for you.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb37"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb37-1"><a href="#cb37-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb37-2"><a href="#cb37-2" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb37-3"><a href="#cb37-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
-<span id="cb37-4"><a href="#cb37-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"Hello, {s}!</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="st">"world"</span><span class="op">}</span>);</span>
-<span id="cb37-5"><a href="#cb37-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb45"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb45-1"><a href="#cb45-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb45-2"><a href="#cb45-2" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb45-3"><a href="#cb45-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
+<span id="cb45-4"><a href="#cb45-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"Hello, {s}!</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="st">"world"</span><span class="op">}</span>);</span>
+<span id="cb45-5"><a href="#cb45-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>Hello, world!</code></pre>
 </div>
 </div>
 </section>
-<section id="struct-declarations-must-be-constant" class="level3" data-number="2.3.2">
-<h3 data-number="2.3.2" class="anchored" data-anchor-id="struct-declarations-must-be-constant"><span class="header-section-number">2.3.2</span> Struct declarations must be constant</h3>
+<section id="struct-declarations-must-be-constant" class="level3" data-number="2.3.3">
+<h3 data-number="2.3.3" class="anchored" data-anchor-id="struct-declarations-must-be-constant"><span class="header-section-number">2.3.3</span> Struct declarations must be constant</h3>
 <p>Types in Zig must be <code>const</code> or <code>comptime</code> (we are going to talk more about comptime in <a href="10-stack-project.html#sec-comptime" class="quarto-xref"><span>Section 12.1</span></a>). What this means is that you cannot create a new data type, and mark it as variable with the <code>var</code> keyword. So struct declarations are always constant. You cannot declare a new struct type using the <code>var</code> keyword. It must be <code>const</code>.</p>
 <p>In the <code>Vec3</code> example below, this declaration is allowed because I’m using the <code>const</code> keyword to declare this new data type.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb39"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb39-1"><a href="#cb39-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Vec3 = <span class="kw">struct</span> <span class="op">{</span></span>
-<span id="cb39-2"><a href="#cb39-2" aria-hidden="true" tabindex="-1"></a>    x: <span class="dt">f64</span>,</span>
-<span id="cb39-3"><a href="#cb39-3" aria-hidden="true" tabindex="-1"></a>    y: <span class="dt">f64</span>,</span>
-<span id="cb39-4"><a href="#cb39-4" aria-hidden="true" tabindex="-1"></a>    z: <span class="dt">f64</span>,</span>
-<span id="cb39-5"><a href="#cb39-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb47"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb47-1"><a href="#cb47-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Vec3 = <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb47-2"><a href="#cb47-2" aria-hidden="true" tabindex="-1"></a>    x: <span class="dt">f64</span>,</span>
+<span id="cb47-3"><a href="#cb47-3" aria-hidden="true" tabindex="-1"></a>    y: <span class="dt">f64</span>,</span>
+<span id="cb47-4"><a href="#cb47-4" aria-hidden="true" tabindex="-1"></a>    z: <span class="dt">f64</span>,</span>
+<span id="cb47-5"><a href="#cb47-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
-<section id="sec-self-arg" class="level3" data-number="2.3.3">
-<h3 data-number="2.3.3" class="anchored" data-anchor-id="sec-self-arg"><span class="header-section-number">2.3.3</span> The <code>self</code> method argument</h3>
+<section id="sec-self-arg" class="level3" data-number="2.3.4">
+<h3 data-number="2.3.4" class="anchored" data-anchor-id="sec-self-arg"><span class="header-section-number">2.3.4</span> The <code>self</code> method argument</h3>
 <p>In every language that have OOP, when we declare a method of some class or struct, we usually declare this method as a function that has a <code>self</code> argument. This <code>self</code> argument is the reference to the object itself from which the method is being called from.</p>
 <p>It’s not mandatory to use this <code>self</code> argument. But why would you not use this <code>self</code> argument? There is no reason to not use it. Because the only way to get access to the data stored in the data members of your struct is to access them through this <code>self</code> argument. If you don’t need to use the data in the data members of your struct inside your method, you very likely don’t need a method. You can just declare this logic as a simple function, outside of your struct declaration.</p>
 <p>Take the <code>Vec3</code> struct below. Inside this <code>Vec3</code> struct we declared a method named <code>distance()</code>. This method calculates the distance between two <code>Vec3</code> objects, by following the distance formula in euclidean space. Notice that this <code>distance()</code> method takes two <code>Vec3</code> objects as input, <code>self</code> and <code>other</code>.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb40"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb40-1"><a href="#cb40-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb40-2"><a href="#cb40-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> m = std.math;</span>
-<span id="cb40-3"><a href="#cb40-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Vec3 = <span class="kw">struct</span> <span class="op">{</span></span>
-<span id="cb40-4"><a href="#cb40-4" aria-hidden="true" tabindex="-1"></a>    x: <span class="dt">f64</span>,</span>
-<span id="cb40-5"><a href="#cb40-5" aria-hidden="true" tabindex="-1"></a>    y: <span class="dt">f64</span>,</span>
-<span id="cb40-6"><a href="#cb40-6" aria-hidden="true" tabindex="-1"></a>    z: <span class="dt">f64</span>,</span>
-<span id="cb40-7"><a href="#cb40-7" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb40-8"><a href="#cb40-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> distance(self: Vec3, other: Vec3) <span class="dt">f64</span> <span class="op">{</span></span>
-<span id="cb40-9"><a href="#cb40-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> xd = m.pow(<span class="dt">f64</span>, self.x - other.x, <span class="fl">2.0</span>);</span>
-<span id="cb40-10"><a href="#cb40-10" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> yd = m.pow(<span class="dt">f64</span>, self.y - other.y, <span class="fl">2.0</span>);</span>
-<span id="cb40-11"><a href="#cb40-11" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> zd = m.pow(<span class="dt">f64</span>, self.z - other.z, <span class="fl">2.0</span>);</span>
-<span id="cb40-12"><a href="#cb40-12" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> m.sqrt(xd + yd + zd);</span>
-<span id="cb40-13"><a href="#cb40-13" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb40-14"><a href="#cb40-14" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb48"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb48-1"><a href="#cb48-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb48-2"><a href="#cb48-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> m = std.math;</span>
+<span id="cb48-3"><a href="#cb48-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Vec3 = <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb48-4"><a href="#cb48-4" aria-hidden="true" tabindex="-1"></a>    x: <span class="dt">f64</span>,</span>
+<span id="cb48-5"><a href="#cb48-5" aria-hidden="true" tabindex="-1"></a>    y: <span class="dt">f64</span>,</span>
+<span id="cb48-6"><a href="#cb48-6" aria-hidden="true" tabindex="-1"></a>    z: <span class="dt">f64</span>,</span>
+<span id="cb48-7"><a href="#cb48-7" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb48-8"><a href="#cb48-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> distance(self: Vec3, other: Vec3) <span class="dt">f64</span> <span class="op">{</span></span>
+<span id="cb48-9"><a href="#cb48-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> xd = m.pow(<span class="dt">f64</span>, self.x - other.x, <span class="fl">2.0</span>);</span>
+<span id="cb48-10"><a href="#cb48-10" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> yd = m.pow(<span class="dt">f64</span>, self.y - other.y, <span class="fl">2.0</span>);</span>
+<span id="cb48-11"><a href="#cb48-11" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> zd = m.pow(<span class="dt">f64</span>, self.z - other.z, <span class="fl">2.0</span>);</span>
+<span id="cb48-12"><a href="#cb48-12" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> m.sqrt(xd + yd + zd);</span>
+<span id="cb48-13"><a href="#cb48-13" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb48-14"><a href="#cb48-14" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>The <code>self</code> argument corresponds to the <code>Vec3</code> object from which this <code>distance()</code> method is being called from. While the <code>other</code> is a separate <code>Vec3</code> object that is given as input to this method. In the example below, the <code>self</code> argument corresponds to the object <code>v1</code>, because the <code>distance()</code> method is being called from the <code>v1</code> object, while the <code>other</code> argument corresponds to the object <code>v2</code>.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb41"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb41-1"><a href="#cb41-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> v1 = Vec3 <span class="op">{</span></span>
-<span id="cb41-2"><a href="#cb41-2" aria-hidden="true" tabindex="-1"></a>    .x = <span class="fl">4.2</span>, .y = <span class="fl">2.4</span>, .z = <span class="fl">0.9</span></span>
-<span id="cb41-3"><a href="#cb41-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
-<span id="cb41-4"><a href="#cb41-4" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> v2 = Vec3 <span class="op">{</span></span>
-<span id="cb41-5"><a href="#cb41-5" aria-hidden="true" tabindex="-1"></a>    .x = <span class="fl">5.1</span>, .y = <span class="fl">5.6</span>, .z = <span class="fl">1.6</span></span>
-<span id="cb41-6"><a href="#cb41-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
-<span id="cb41-7"><a href="#cb41-7" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb41-8"><a href="#cb41-8" aria-hidden="true" tabindex="-1"></a>std.debug.print(</span>
-<span id="cb41-9"><a href="#cb41-9" aria-hidden="true" tabindex="-1"></a>    <span class="st">"Distance: {d}</span><span class="sc">\n</span><span class="st">"</span>,</span>
-<span id="cb41-10"><a href="#cb41-10" aria-hidden="true" tabindex="-1"></a>    .<span class="op">{</span>v1.distance(v2)<span class="op">}</span></span>
-<span id="cb41-11"><a href="#cb41-11" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb49"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb49-1"><a href="#cb49-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> v1 = Vec3 <span class="op">{</span></span>
+<span id="cb49-2"><a href="#cb49-2" aria-hidden="true" tabindex="-1"></a>    .x = <span class="fl">4.2</span>, .y = <span class="fl">2.4</span>, .z = <span class="fl">0.9</span></span>
+<span id="cb49-3"><a href="#cb49-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
+<span id="cb49-4"><a href="#cb49-4" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> v2 = Vec3 <span class="op">{</span></span>
+<span id="cb49-5"><a href="#cb49-5" aria-hidden="true" tabindex="-1"></a>    .x = <span class="fl">5.1</span>, .y = <span class="fl">5.6</span>, .z = <span class="fl">1.6</span></span>
+<span id="cb49-6"><a href="#cb49-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
+<span id="cb49-7"><a href="#cb49-7" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb49-8"><a href="#cb49-8" aria-hidden="true" tabindex="-1"></a>std.debug.print(</span>
+<span id="cb49-9"><a href="#cb49-9" aria-hidden="true" tabindex="-1"></a>    <span class="st">"Distance: {d}</span><span class="sc">\n</span><span class="st">"</span>,</span>
+<span id="cb49-10"><a href="#cb49-10" aria-hidden="true" tabindex="-1"></a>    .<span class="op">{</span>v1.distance(v2)<span class="op">}</span></span>
+<span id="cb49-11"><a href="#cb49-11" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Distance: 3.3970575502926055</code></pre>
 </section>
-<section id="about-the-struct-state" class="level3" data-number="2.3.4">
-<h3 data-number="2.3.4" class="anchored" data-anchor-id="about-the-struct-state"><span class="header-section-number">2.3.4</span> About the struct state</h3>
+<section id="about-the-struct-state" class="level3" data-number="2.3.5">
+<h3 data-number="2.3.5" class="anchored" data-anchor-id="about-the-struct-state"><span class="header-section-number">2.3.5</span> About the struct state</h3>
 <p>Sometimes you don’t need to care about the state of your struct object. Sometimes, you just need to instantiate and use the objects, without altering their state. You can notice that when you have methods inside your struct declaration that might use the values that are present in the data members, but they do not alter the values in these data members of the struct in anyway.</p>
-<p>The <code>Vec3</code> struct that was presented in <a href="#sec-self-arg" class="quarto-xref"><span>Section 2.3.3</span></a> is an example of that. This struct have a single method named <code>distance()</code>, and this method does use the values present in all three data members of the struct (<code>x</code>, <code>y</code> and <code>z</code>). But at the same time, this method does not change the values of these data members at any point.</p>
-<p>As a result of that, when we create <code>Vec3</code> objects we usually create them as constant objects, like the <code>v1</code> and <code>v2</code> objects presented in <a href="#sec-self-arg" class="quarto-xref"><span>Section 2.3.3</span></a>. We can create them as variable objects with the <code>var</code> keyword, if we want to. But because the methods of this <code>Vec3</code> struct do not change the state of the objects in any point, it’s unnecessary to mark them as variable objects.</p>
+<p>The <code>Vec3</code> struct that was presented in <a href="#sec-self-arg" class="quarto-xref"><span>Section 2.3.4</span></a> is an example of that. This struct have a single method named <code>distance()</code>, and this method does use the values present in all three data members of the struct (<code>x</code>, <code>y</code> and <code>z</code>). But at the same time, this method does not change the values of these data members at any point.</p>
+<p>As a result of that, when we create <code>Vec3</code> objects we usually create them as constant objects, like the <code>v1</code> and <code>v2</code> objects presented in <a href="#sec-self-arg" class="quarto-xref"><span>Section 2.3.4</span></a>. We can create them as variable objects with the <code>var</code> keyword, if we want to. But because the methods of this <code>Vec3</code> struct do not change the state of the objects in any point, it’s unnecessary to mark them as variable objects.</p>
 <p>But why? Why am I talking about this here? It’s because the <code>self</code> argument in the methods are affected depending on whether the methods present in a struct change or don’t change the state of the object itself. More specifically, when you have a method in a struct that changes the state of the object (i.e., changes the value of a data member), the <code>self</code> argument in this method must be annotated in a different manner.</p>
-<p>As I described in <a href="#sec-self-arg" class="quarto-xref"><span>Section 2.3.3</span></a>, the <code>self</code> argument in methods of a struct is the argument that receives as input the object from which the method was called from. We usually annotate this argument in the methods by writing <code>self</code>, followed by the colon character (<code>:</code>), and the data type of the struct to which the method belongs to (e.g.&nbsp;<code>User</code>, <code>Vec3</code>, etc.).</p>
+<p>As I described in <a href="#sec-self-arg" class="quarto-xref"><span>Section 2.3.4</span></a>, the <code>self</code> argument in methods of a struct is the argument that receives as input the object from which the method was called from. We usually annotate this argument in the methods by writing <code>self</code>, followed by the colon character (<code>:</code>), and the data type of the struct to which the method belongs to (e.g.&nbsp;<code>User</code>, <code>Vec3</code>, etc.).</p>
 <p>If we take the <code>Vec3</code> struct that we defined in the previous section as an example, we can see in the <code>distance()</code> method that this <code>self</code> argument is annotated as <code>self: Vec3</code>. Because the state of the <code>Vec3</code> object is never altered by this method.</p>
 <p>But what if we do have a method that alters the state of the object, by altering the values of its data members, how should we annotate <code>self</code> in this instance? The answer is: “we should annotate <code>self</code> as a pointer of <code>x</code>, instead of just <code>x</code>”. In other words, you should annotate <code>self</code> as <code>self: *x</code>, instead of annotating it as <code>self: x</code>.</p>
 <p>If we create a new method inside the <code>Vec3</code> object that, for example, expands the vector by multiplying its coordinates by a factor of two, then, we need to follow this rule specified in the previous paragraph. The code example below demonstrates this idea:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb43"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb43-1"><a href="#cb43-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb43-2"><a href="#cb43-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> m = std.math;</span>
-<span id="cb43-3"><a href="#cb43-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Vec3 = <span class="kw">struct</span> <span class="op">{</span></span>
-<span id="cb43-4"><a href="#cb43-4" aria-hidden="true" tabindex="-1"></a>    x: <span class="dt">f64</span>,</span>
-<span id="cb43-5"><a href="#cb43-5" aria-hidden="true" tabindex="-1"></a>    y: <span class="dt">f64</span>,</span>
-<span id="cb43-6"><a href="#cb43-6" aria-hidden="true" tabindex="-1"></a>    z: <span class="dt">f64</span>,</span>
-<span id="cb43-7"><a href="#cb43-7" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb43-8"><a href="#cb43-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> distance(self: Vec3, other: Vec3) <span class="dt">f64</span> <span class="op">{</span></span>
-<span id="cb43-9"><a href="#cb43-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> xd = m.pow(<span class="dt">f64</span>, self.x - other.x, <span class="fl">2.0</span>);</span>
-<span id="cb43-10"><a href="#cb43-10" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> yd = m.pow(<span class="dt">f64</span>, self.y - other.y, <span class="fl">2.0</span>);</span>
-<span id="cb43-11"><a href="#cb43-11" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> zd = m.pow(<span class="dt">f64</span>, self.z - other.z, <span class="fl">2.0</span>);</span>
-<span id="cb43-12"><a href="#cb43-12" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> m.sqrt(xd + yd + zd);</span>
-<span id="cb43-13"><a href="#cb43-13" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb43-14"><a href="#cb43-14" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb43-15"><a href="#cb43-15" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> twice(self: *Vec3) <span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb43-16"><a href="#cb43-16" aria-hidden="true" tabindex="-1"></a>        self.x = self.x * <span class="fl">2.0</span>;</span>
-<span id="cb43-17"><a href="#cb43-17" aria-hidden="true" tabindex="-1"></a>        self.y = self.y * <span class="fl">2.0</span>;</span>
-<span id="cb43-18"><a href="#cb43-18" aria-hidden="true" tabindex="-1"></a>        self.z = self.z * <span class="fl">2.0</span>;</span>
-<span id="cb43-19"><a href="#cb43-19" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb43-20"><a href="#cb43-20" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb51"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb51-1"><a href="#cb51-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb51-2"><a href="#cb51-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> m = std.math;</span>
+<span id="cb51-3"><a href="#cb51-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Vec3 = <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb51-4"><a href="#cb51-4" aria-hidden="true" tabindex="-1"></a>    x: <span class="dt">f64</span>,</span>
+<span id="cb51-5"><a href="#cb51-5" aria-hidden="true" tabindex="-1"></a>    y: <span class="dt">f64</span>,</span>
+<span id="cb51-6"><a href="#cb51-6" aria-hidden="true" tabindex="-1"></a>    z: <span class="dt">f64</span>,</span>
+<span id="cb51-7"><a href="#cb51-7" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb51-8"><a href="#cb51-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> distance(self: Vec3, other: Vec3) <span class="dt">f64</span> <span class="op">{</span></span>
+<span id="cb51-9"><a href="#cb51-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> xd = m.pow(<span class="dt">f64</span>, self.x - other.x, <span class="fl">2.0</span>);</span>
+<span id="cb51-10"><a href="#cb51-10" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> yd = m.pow(<span class="dt">f64</span>, self.y - other.y, <span class="fl">2.0</span>);</span>
+<span id="cb51-11"><a href="#cb51-11" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> zd = m.pow(<span class="dt">f64</span>, self.z - other.z, <span class="fl">2.0</span>);</span>
+<span id="cb51-12"><a href="#cb51-12" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> m.sqrt(xd + yd + zd);</span>
+<span id="cb51-13"><a href="#cb51-13" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb51-14"><a href="#cb51-14" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb51-15"><a href="#cb51-15" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> twice(self: *Vec3) <span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb51-16"><a href="#cb51-16" aria-hidden="true" tabindex="-1"></a>        self.x = self.x * <span class="fl">2.0</span>;</span>
+<span id="cb51-17"><a href="#cb51-17" aria-hidden="true" tabindex="-1"></a>        self.y = self.y * <span class="fl">2.0</span>;</span>
+<span id="cb51-18"><a href="#cb51-18" aria-hidden="true" tabindex="-1"></a>        self.z = self.z * <span class="fl">2.0</span>;</span>
+<span id="cb51-19"><a href="#cb51-19" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb51-20"><a href="#cb51-20" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>Notice in the code example above that we have added a new method to our <code>Vec3</code> struct named <code>twice()</code>. This method doubles the coordinate values of our vector object. In the case of the <code>twice()</code> method, we annotated the <code>self</code> argument as <code>*Vec3</code>, indicating that this argument receives a pointer (or a reference, if you prefer to call it this way) to a <code>Vec3</code> object as input.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb44"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb44-1"><a href="#cb44-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> v3 = Vec3 <span class="op">{</span></span>
-<span id="cb44-2"><a href="#cb44-2" aria-hidden="true" tabindex="-1"></a>    .x = <span class="fl">4.2</span>, .y = <span class="fl">2.4</span>, .z = <span class="fl">0.9</span></span>
-<span id="cb44-3"><a href="#cb44-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
-<span id="cb44-4"><a href="#cb44-4" aria-hidden="true" tabindex="-1"></a>v3.twice();</span>
-<span id="cb44-5"><a href="#cb44-5" aria-hidden="true" tabindex="-1"></a>std.debug.print(<span class="st">"Doubled: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>v3.x<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb52"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb52-1"><a href="#cb52-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> v3 = Vec3 <span class="op">{</span></span>
+<span id="cb52-2"><a href="#cb52-2" aria-hidden="true" tabindex="-1"></a>    .x = <span class="fl">4.2</span>, .y = <span class="fl">2.4</span>, .z = <span class="fl">0.9</span></span>
+<span id="cb52-3"><a href="#cb52-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
+<span id="cb52-4"><a href="#cb52-4" aria-hidden="true" tabindex="-1"></a>v3.twice();</span>
+<span id="cb52-5"><a href="#cb52-5" aria-hidden="true" tabindex="-1"></a>std.debug.print(<span class="st">"Doubled: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>v3.x<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Doubled: 8.4</code></pre>
 <p>Now, if you change the <code>self</code> argument in this <code>twice()</code> method to <code>self: Vec3</code>, like in the <code>distance()</code> method, you will get the compiler error exposed below as result. Notice that this error message is showing a line from the <code>twice()</code> method body, indicating that you cannot alter the value of the <code>x</code> data member.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb46"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb46-1"><a href="#cb46-1" aria-hidden="true" tabindex="-1"></a><span class="co">// If we change the function signature of double to:</span></span>
-<span id="cb46-2"><a href="#cb46-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> twice(self: Vec3) <span class="dt">void</span> <span class="op">{</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb54"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb54-1"><a href="#cb54-1" aria-hidden="true" tabindex="-1"></a><span class="co">// If we change the function signature of double to:</span></span>
+<span id="cb54-2"><a href="#cb54-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">pub</span> <span class="kw">fn</span> twice(self: Vec3) <span class="dt">void</span> <span class="op">{</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>t.zig:16:13: error: cannot assign to constant
         self.x = self.x * 2.0;
@@ -878,38 +939,38 @@ <h2 data-number="2.4" class="anchored" data-anchor-id="sec-type-inference"><span
 <p>Zig is a strongly typed language. But, there are some situations where you don’t have to explicitly write the type of every single object in your source code, as you would expect from a traditional strongly typed language, such as C and C++.</p>
 <p>In some situations, the <code>zig</code> compiler can use type inference to solve the data types for you, easing some of the burden that you carry as a developer. The most common way this happens is through function arguments that receive struct objects as input.</p>
 <p>In general, type inference in Zig is done by using the dot character (<code>.</code>). Everytime you see a dot character written before a struct literal, or before an enum value, or something like that, you know that this dot character is playing a special part in this place. More specifically, it’s telling the <code>zig</code> compiler something along the lines of: “Hey! Can you infer the type of this value for me? Please!”. In other words, this dot character is playing a similar role as the <code>auto</code> keyword in C++.</p>
-<p>I gave you some examples of this in <a href="#sec-anonymous-struct-literals" class="quarto-xref"><span>Section 2.3.1</span></a>, where we used anonymous struct literals. Anonymous struct literals are, struct literals that use type inference to infer the exact type of this particular struct literal. This type inference is done by looking for some minimal hint of the correct data type to be used. You could say that the <code>zig</code> compiler looks for any neighbouring type annotation that might tell it what the correct type would be.</p>
+<p>I gave you some examples of this in <a href="#sec-anonymous-struct-literals" class="quarto-xref"><span>Section 2.3.2</span></a>, where we used anonymous struct literals. Anonymous struct literals are, struct literals that use type inference to infer the exact type of this particular struct literal. This type inference is done by looking for some minimal hint of the correct data type to be used. You could say that the <code>zig</code> compiler looks for any neighbouring type annotation that might tell it what the correct type would be.</p>
 <p>Another common place where we use type inference in Zig is at switch statements (which we talked about in <a href="#sec-switch" class="quarto-xref"><span>Section 2.1.2</span></a>). I also gave some other examples of type inference in <a href="#sec-switch" class="quarto-xref"><span>Section 2.1.2</span></a>, where we were inferring the data types of enum values listed inside of switch statements (e.g.&nbsp;<code>.DE</code>). But as another example, take a look at this <code>fence()</code> function reproduced below, which comes from the <a href="https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig"><code>atomic.zig</code> module</a><a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a> of the Zig Standard Library.</p>
 <p>There are a lot of things in this function that we haven’t talked about yet, such as: what <code>comptime</code> means? <code>inline</code>? <code>extern</code>? Let’s just ignore all of these things, and focus solely on the switch statement that is inside this function.</p>
 <p>We can see that this switch statement uses the <code>order</code> object as input. This <code>order</code> object is one of the inputs of this <code>fence()</code> function, and we can see in the type annotation, that this object is of type <code>AtomicOrder</code>. We can also see a bunch of values inside the switch statements that begin with a dot character, such as <code>.release</code> and <code>.acquire</code>.</p>
 <p>Because these weird values contain a dot character before them, we are asking the <code>zig</code> compiler to infer the types of these values inside the switch statement. Then, the <code>zig</code> compiler is looking into the current context where these values are being used, and trying to infer the types of these values.</p>
 <p>Since they are being used inside a switch statement, the <code>zig</code> compiler looks into the type of the input object given to the switch statement, which is the <code>order</code> object in this case. Because this object have type <code>AtomicOrder</code>, the <code>zig</code> compiler infers that these values are data members from this type <code>AtomicOrder</code>.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb48"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb48-1"><a href="#cb48-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">inline</span> <span class="kw">fn</span> fence(self: *Self, <span class="kw">comptime</span> order: AtomicOrder) <span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb48-2"><a href="#cb48-2" aria-hidden="true" tabindex="-1"></a>    <span class="co">// many lines of code ...</span></span>
-<span id="cb48-3"><a href="#cb48-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> (builtin.sanitize_thread) <span class="op">{</span></span>
-<span id="cb48-4"><a href="#cb48-4" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> tsan = <span class="kw">struct</span> <span class="op">{</span></span>
-<span id="cb48-5"><a href="#cb48-5" aria-hidden="true" tabindex="-1"></a>            <span class="kw">extern</span> <span class="st">"c"</span> <span class="kw">fn</span> __tsan_acquire(addr: *anyopaque) <span class="dt">void</span>;</span>
-<span id="cb48-6"><a href="#cb48-6" aria-hidden="true" tabindex="-1"></a>            <span class="kw">extern</span> <span class="st">"c"</span> <span class="kw">fn</span> __tsan_release(addr: *anyopaque) <span class="dt">void</span>;</span>
-<span id="cb48-7"><a href="#cb48-7" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span>;</span>
-<span id="cb48-8"><a href="#cb48-8" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb48-9"><a href="#cb48-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> addr: *anyopaque = self;</span>
-<span id="cb48-10"><a href="#cb48-10" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> <span class="kw">switch</span> (order) <span class="op">{</span></span>
-<span id="cb48-11"><a href="#cb48-11" aria-hidden="true" tabindex="-1"></a>            .unordered, .monotonic =&gt; <span class="bu">@compileError</span>(</span>
-<span id="cb48-12"><a href="#cb48-12" aria-hidden="true" tabindex="-1"></a>                <span class="bu">@tagName</span>(order)</span>
-<span id="cb48-13"><a href="#cb48-13" aria-hidden="true" tabindex="-1"></a>                ++ <span class="st">" only applies to atomic loads and stores"</span></span>
-<span id="cb48-14"><a href="#cb48-14" aria-hidden="true" tabindex="-1"></a>            ),</span>
-<span id="cb48-15"><a href="#cb48-15" aria-hidden="true" tabindex="-1"></a>            .acquire =&gt; tsan.__tsan_acquire(addr),</span>
-<span id="cb48-16"><a href="#cb48-16" aria-hidden="true" tabindex="-1"></a>            .release =&gt; tsan.__tsan_release(addr),</span>
-<span id="cb48-17"><a href="#cb48-17" aria-hidden="true" tabindex="-1"></a>            .acq_rel, .seq_cst =&gt; <span class="op">{</span></span>
-<span id="cb48-18"><a href="#cb48-18" aria-hidden="true" tabindex="-1"></a>                tsan.__tsan_acquire(addr);</span>
-<span id="cb48-19"><a href="#cb48-19" aria-hidden="true" tabindex="-1"></a>                tsan.__tsan_release(addr);</span>
-<span id="cb48-20"><a href="#cb48-20" aria-hidden="true" tabindex="-1"></a>            <span class="op">}</span>,</span>
-<span id="cb48-21"><a href="#cb48-21" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span>;</span>
-<span id="cb48-22"><a href="#cb48-22" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb48-23"><a href="#cb48-23" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb48-24"><a href="#cb48-24" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> <span class="bu">@fence</span>(order);</span>
-<span id="cb48-25"><a href="#cb48-25" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb56"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb56-1"><a href="#cb56-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">inline</span> <span class="kw">fn</span> fence(self: *Self, <span class="kw">comptime</span> order: AtomicOrder) <span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb56-2"><a href="#cb56-2" aria-hidden="true" tabindex="-1"></a>    <span class="co">// many lines of code ...</span></span>
+<span id="cb56-3"><a href="#cb56-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> (builtin.sanitize_thread) <span class="op">{</span></span>
+<span id="cb56-4"><a href="#cb56-4" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> tsan = <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb56-5"><a href="#cb56-5" aria-hidden="true" tabindex="-1"></a>            <span class="kw">extern</span> <span class="st">"c"</span> <span class="kw">fn</span> __tsan_acquire(addr: *anyopaque) <span class="dt">void</span>;</span>
+<span id="cb56-6"><a href="#cb56-6" aria-hidden="true" tabindex="-1"></a>            <span class="kw">extern</span> <span class="st">"c"</span> <span class="kw">fn</span> __tsan_release(addr: *anyopaque) <span class="dt">void</span>;</span>
+<span id="cb56-7"><a href="#cb56-7" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span>;</span>
+<span id="cb56-8"><a href="#cb56-8" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb56-9"><a href="#cb56-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> addr: *anyopaque = self;</span>
+<span id="cb56-10"><a href="#cb56-10" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> <span class="kw">switch</span> (order) <span class="op">{</span></span>
+<span id="cb56-11"><a href="#cb56-11" aria-hidden="true" tabindex="-1"></a>            .unordered, .monotonic =&gt; <span class="bu">@compileError</span>(</span>
+<span id="cb56-12"><a href="#cb56-12" aria-hidden="true" tabindex="-1"></a>                <span class="bu">@tagName</span>(order)</span>
+<span id="cb56-13"><a href="#cb56-13" aria-hidden="true" tabindex="-1"></a>                ++ <span class="st">" only applies to atomic loads and stores"</span></span>
+<span id="cb56-14"><a href="#cb56-14" aria-hidden="true" tabindex="-1"></a>            ),</span>
+<span id="cb56-15"><a href="#cb56-15" aria-hidden="true" tabindex="-1"></a>            .acquire =&gt; tsan.__tsan_acquire(addr),</span>
+<span id="cb56-16"><a href="#cb56-16" aria-hidden="true" tabindex="-1"></a>            .release =&gt; tsan.__tsan_release(addr),</span>
+<span id="cb56-17"><a href="#cb56-17" aria-hidden="true" tabindex="-1"></a>            .acq_rel, .seq_cst =&gt; <span class="op">{</span></span>
+<span id="cb56-18"><a href="#cb56-18" aria-hidden="true" tabindex="-1"></a>                tsan.__tsan_acquire(addr);</span>
+<span id="cb56-19"><a href="#cb56-19" aria-hidden="true" tabindex="-1"></a>                tsan.__tsan_release(addr);</span>
+<span id="cb56-20"><a href="#cb56-20" aria-hidden="true" tabindex="-1"></a>            <span class="op">}</span>,</span>
+<span id="cb56-21"><a href="#cb56-21" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span>;</span>
+<span id="cb56-22"><a href="#cb56-22" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb56-23"><a href="#cb56-23" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb56-24"><a href="#cb56-24" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> <span class="bu">@fence</span>(order);</span>
+<span id="cb56-25"><a href="#cb56-25" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>This is how basic type inference is done in Zig. If we didn’t use the dot character before the values inside this switch statement, then, we would be forced to explicitly write the data types of these values. For example, instead of writing <code>.release</code> we would have to write <code>AtomicOrder.release</code>. We would have to do this for every single value in this switch statement, and this is a lot of work. That is why type inference is commonly used on switch statements in Zig.</p>
 </section>
@@ -919,16 +980,15 @@ <h2 data-number="2.5" class="anchored" data-anchor-id="sec-type-cast"><span clas
 <p>Most languages have a formal way to perform type casting. In Rust for example, we normally use the keyword <code>as</code>, and in C, we normally use the type casting syntax, e.g.&nbsp;<code>(int) x</code>. In Zig, we use the <code>@as()</code> built-in function to cast an object of type “x”, into an object of type “y”.</p>
 <p>This <code>@as()</code> function is the preferred way to perform type conversion (or type casting) in Zig. Because it’s explicit, and, it also performs the casting only if it is unambiguous and safe. To use this function, you just provide the target data type in the first argument, and, the object that you want cast as the second argument.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb49"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb49-1"><a href="#cb49-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb49-2"><a href="#cb49-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = std.testing.expect;</span>
-<span id="cb49-3"><a href="#cb49-3" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="op">{</span></span>
-<span id="cb49-4"><a href="#cb49-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> x: <span class="dt">usize</span> = <span class="dv">500</span>;</span>
-<span id="cb49-5"><a href="#cb49-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> y = <span class="bu">@as</span>(<span class="dt">u32</span>, x);</span>
-<span id="cb49-6"><a href="#cb49-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(y) == <span class="dt">u32</span>);</span>
-<span id="cb49-7"><a href="#cb49-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb57"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb57-1"><a href="#cb57-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb57-2"><a href="#cb57-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = std.testing.expect;</span>
+<span id="cb57-3"><a href="#cb57-3" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="op">{</span></span>
+<span id="cb57-4"><a href="#cb57-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> x: <span class="dt">usize</span> = <span class="dv">500</span>;</span>
+<span id="cb57-5"><a href="#cb57-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> y = <span class="bu">@as</span>(<span class="dt">u32</span>, x);</span>
+<span id="cb57-6"><a href="#cb57-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(y) == <span class="dt">u32</span>);</span>
+<span id="cb57-7"><a href="#cb57-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file79ce58134f59.test_0...OKAll 1 tests passed
-  d.</code></pre>
+<pre><code>1/1 file3c448aa9d5f.test_0...OKAll 1 tests passed.</code></pre>
 </div>
 </div>
 <p>This is the general way to perform type casting in Zig. But remember, <code>@as()</code> works only when casting is unambiguous and safe. There are many situations where these assumptions do not hold. For example,</p>
@@ -936,32 +996,32 @@ <h2 data-number="2.5" class="anchored" data-anchor-id="sec-type-cast"><span clas
 <p>Therefore, we need to use specialized “casting functions” in such situations. For example, if you want to cast an integer value into a float value, then, you should use the <code>@floatFromInt()</code> function. In the inverse scenario, you should use the <code>@intFromFloat()</code> function.</p>
 <p>In these functions, you just provide the object that you want to cast as input. Then, the target data type of the “type casting operation” is determined by the type annotation of the object where you are saving the results. In the example below, we are casting the object <code>x</code> into a value of type <code>f32</code>, because the object <code>y</code>, which is where we are saving the results, is annotated as an object of type <code>f32</code>.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb51"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb51-1"><a href="#cb51-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb51-2"><a href="#cb51-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = std.testing.expect;</span>
-<span id="cb51-3"><a href="#cb51-3" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="op">{</span></span>
-<span id="cb51-4"><a href="#cb51-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> x: <span class="dt">usize</span> = <span class="dv">565</span>;</span>
-<span id="cb51-5"><a href="#cb51-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> y: <span class="dt">f32</span> = <span class="bu">@floatFromInt</span>(x);</span>
-<span id="cb51-6"><a href="#cb51-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(y) == <span class="dt">f32</span>);</span>
-<span id="cb51-7"><a href="#cb51-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb59"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb59-1"><a href="#cb59-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb59-2"><a href="#cb59-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = std.testing.expect;</span>
+<span id="cb59-3"><a href="#cb59-3" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="op">{</span></span>
+<span id="cb59-4"><a href="#cb59-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> x: <span class="dt">usize</span> = <span class="dv">565</span>;</span>
+<span id="cb59-5"><a href="#cb59-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> y: <span class="dt">f32</span> = <span class="bu">@floatFromInt</span>(x);</span>
+<span id="cb59-6"><a href="#cb59-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(y) == <span class="dt">f32</span>);</span>
+<span id="cb59-7"><a href="#cb59-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file79ce286cee5b.test_0...OKAll 1 tests passed
+<pre><code>1/1 file3c4427337b66.test_0...OKAll 1 tests passed
   d.</code></pre>
 </div>
 </div>
 <p>Another built-in function that is very useful when performing type casting operations is <code>@ptrCast()</code>. In essence, we use the <code>@as()</code> built-in function when we want to explicit convert (or cast) a Zig value/object from a type “x” to a type “y”, etc. However, pointers (we are going to discuss pointers in more depth in <a href="05-pointers.html" class="quarto-xref"><span>Chapter 6</span></a>) are a special type of object in Zig, i.e., they are treated differently from “normal objects”.</p>
 <p>Everytime a pointer is involved in some “type casting operation” in Zig, the <code>@ptrCast()</code> function is used. This function works similarly to <code>@floatFromInt()</code>. You just provide the pointer object that you want to cast as input to this function, and the target data type is, once again, determined by the type annotation of the object where the results are being stored.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb53"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb53-1"><a href="#cb53-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb53-2"><a href="#cb53-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = std.testing.expect;</span>
-<span id="cb53-3"><a href="#cb53-3" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="op">{</span></span>
-<span id="cb53-4"><a href="#cb53-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> bytes <span class="kw">align</span>(<span class="bu">@alignOf</span>(<span class="dt">u32</span>)) = [_]<span class="dt">u8</span><span class="op">{</span></span>
-<span id="cb53-5"><a href="#cb53-5" aria-hidden="true" tabindex="-1"></a>        <span class="bn">0x12</span>, <span class="bn">0x12</span>, <span class="bn">0x12</span>, <span class="bn">0x12</span></span>
-<span id="cb53-6"><a href="#cb53-6" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>;</span>
-<span id="cb53-7"><a href="#cb53-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> u32_ptr: *<span class="kw">const</span> <span class="dt">u32</span> = <span class="bu">@ptrCast</span>(&amp;bytes);</span>
-<span id="cb53-8"><a href="#cb53-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(u32_ptr) == *<span class="kw">const</span> <span class="dt">u32</span>);</span>
-<span id="cb53-9"><a href="#cb53-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb61"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb61-1"><a href="#cb61-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb61-2"><a href="#cb61-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> expect = std.testing.expect;</span>
+<span id="cb61-3"><a href="#cb61-3" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="op">{</span></span>
+<span id="cb61-4"><a href="#cb61-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> bytes <span class="kw">align</span>(<span class="bu">@alignOf</span>(<span class="dt">u32</span>)) = [_]<span class="dt">u8</span><span class="op">{</span></span>
+<span id="cb61-5"><a href="#cb61-5" aria-hidden="true" tabindex="-1"></a>        <span class="bn">0x12</span>, <span class="bn">0x12</span>, <span class="bn">0x12</span>, <span class="bn">0x12</span></span>
+<span id="cb61-6"><a href="#cb61-6" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>;</span>
+<span id="cb61-7"><a href="#cb61-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> u32_ptr: *<span class="kw">const</span> <span class="dt">u32</span> = <span class="bu">@ptrCast</span>(&amp;bytes);</span>
+<span id="cb61-8"><a href="#cb61-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(u32_ptr) == *<span class="kw">const</span> <span class="dt">u32</span>);</span>
+<span id="cb61-9"><a href="#cb61-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file79ce1e7313c8.test_0...OKAll 1 tests passed
+<pre><code>1/1 file3c4479f1f6f8.test_0...OKAll 1 tests passed
   d.</code></pre>
 </div>
 </div>
@@ -970,22 +1030,22 @@ <h2 data-number="2.5" class="anchored" data-anchor-id="sec-type-cast"><span clas
 <h2 data-number="2.6" class="anchored" data-anchor-id="modules"><span class="header-section-number">2.6</span> Modules</h2>
 <p>We already talked about what modules are, and also, how to import other modules into your current module via <em>import statements</em>. Every Zig module (i.e., a <code>.zig</code> file) that you write in your project is internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the Zig Standard Library into our current module.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb55"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb55-1"><a href="#cb55-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb63"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb63-1"><a href="#cb63-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>When we want to access the functions and objects from the standard library, we are basically accessing the data members of the struct stored in the <code>std</code> object. That is why we use the same syntax that we use in normal structs, with the dot operator (<code>.</code>) to access the data members and methods of the struct.</p>
 <p>When this “import statement” gets executed, the result of this expression is a struct object that contains the Zig Standard Library modules, global variables, functions, etc. And this struct object gets saved (or stored) inside the constant object named <code>std</code>.</p>
 <p>Take the <a href="https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig"><code>thread_pool.zig</code> module from the project <code>zap</code></a><a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a> as an example. This module is written as if it was a big struct. That is why we have a top-level and public <code>init()</code> method written in this module. The idea is that all top-level functions written in this module are methods from the struct, and all top-level objects and struct declarations are data members of this struct. The module is the struct itself.</p>
 <p>So you would import and use this module by doing something like this:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb56"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb56-1"><a href="#cb56-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb56-2"><a href="#cb56-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ThreadPool = <span class="bu">@import</span>(<span class="st">"thread_pool.zig"</span>);</span>
-<span id="cb56-3"><a href="#cb56-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> num_cpus = std.Thread.getCpuCount()</span>
-<span id="cb56-4"><a href="#cb56-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">catch</span> <span class="bu">@panic</span>(<span class="st">"failed to get cpu core count"</span>);</span>
-<span id="cb56-5"><a href="#cb56-5" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> num_threads = std.math.cast(<span class="dt">u16</span>, num_cpus)</span>
-<span id="cb56-6"><a href="#cb56-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">catch</span> std.math.maxInt(<span class="dt">u16</span>);</span>
-<span id="cb56-7"><a href="#cb56-7" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> pool = ThreadPool.init(</span>
-<span id="cb56-8"><a href="#cb56-8" aria-hidden="true" tabindex="-1"></a>    .<span class="op">{</span> .max_threads = num_threads <span class="op">}</span></span>
-<span id="cb56-9"><a href="#cb56-9" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb64"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb64-1"><a href="#cb64-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb64-2"><a href="#cb64-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ThreadPool = <span class="bu">@import</span>(<span class="st">"thread_pool.zig"</span>);</span>
+<span id="cb64-3"><a href="#cb64-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> num_cpus = std.Thread.getCpuCount()</span>
+<span id="cb64-4"><a href="#cb64-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">catch</span> <span class="bu">@panic</span>(<span class="st">"failed to get cpu core count"</span>);</span>
+<span id="cb64-5"><a href="#cb64-5" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> num_threads = std.math.cast(<span class="dt">u16</span>, num_cpus)</span>
+<span id="cb64-6"><a href="#cb64-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">catch</span> std.math.maxInt(<span class="dt">u16</span>);</span>
+<span id="cb64-7"><a href="#cb64-7" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> pool = ThreadPool.init(</span>
+<span id="cb64-8"><a href="#cb64-8" aria-hidden="true" tabindex="-1"></a>    .<span class="op">{</span> .max_threads = num_threads <span class="op">}</span></span>
+<span id="cb64-9"><a href="#cb64-9" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 
 
diff --git a/docs/search.json b/docs/search.json
index 616ae938..2c6e11fa 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -254,7 +254,7 @@
     "href": "Chapters/03-structs.html#sec-structs-and-oop",
     "title": "2  Control flow, structs, modules and types",
     "section": "2.3 Structs and OOP",
-    "text": "2.3 Structs and OOP\nZig is a language more closely related to C (which is a procedural language), than it is to C++ or Java (which are object-oriented languages). Because of that, you do not have advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or class inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C. You give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can also register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object that you create with this new type, will always have these methods available and associated with them.\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which is used to construct (or, to instantiate) every object of this particular class, and we also have a destructor method (or a destructor function), which is the function responsible for destroying every object of this class.\nIn Zig, we normally declare the constructor and the destructor methods of our structs, by declaring an init() and a deinit() methods inside the struct. This is just a naming convention that you will find across the entire Zig Standard Library. So, in Zig, the init() method of a struct is normally the constructor method of the class represented by this struct. While the deinit() method is the method used for destroying an existing instance of that struct.\nThe init() and deinit() methods are both used extensively in Zig code, and you will see both of them being used when we talk about allocators in Section 3.3. But, as another example, let’s build a simple User struct to represent a user of some sort of system.\nIf you look at the User struct below, you can see the struct keyword. Notice the data members of this struct: id, name and email. Every data member has its type explicitly annotated, with the colon character (:) syntax that we described earlier in Section 1.2.2. But also notice that every line in the struct body that describes a data member, ends with a comma character (,). So every time you declare a data member in your Zig code, always end the line with a comma character, instead of ending it with the traditional semicolon character (;).\nNext, we have registered an init() function as a method of this User struct. This init() method is the constructor method that we will use to instantiate every new User object. That is why this init() function returns a new User object as result.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    pub fn init(id: u64,\n                name: []const u8,\n                email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    pub fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n\npedro\n\n\nThe pub keyword plays an important role in struct declarations, and OOP in Zig. Every method that you declare in your struct that is marked with the keyword pub, becomes a public method of this particular struct.\nSo every method that you create inside your struct, is, at first, a private method of that struct. Meaning that, this method can only be called from within this struct. But, if you mark this method as public, with the keyword pub, then, you can call the method directly from an instance of the User struct.\nIn other words, the functions marked by the keyword pub are members of the public API of that struct. For example, if I did not mark the print_name() method as public, then, I could not execute the line u.print_name(). Because I would not be authorized to call this method directly in my code.\n\n2.3.1 Anonymous struct literals\nYou can declare a struct object as a literal value. When we do that, we normally specify the data type of this struct literal by writing its data type just before the opening curly brace. For example, I could write a struct literal value of the type User that we have defined in the previous section like this:\n\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a struct literal, but not specify explicitly the type of this particular struct. An anonymous struct is written by using the syntax .{}. So, we essentially replaced the explicit type of the struct literal with a dot character (.).\nAs we described in Section 2.4, when you put a dot before a struct literal, the type of this struct literal is automatically inferred by the zig compiler. In essence, the zig compiler will look for some hint of what is the type of that struct. This hint can be the type annotation of a function argument, or the return type annotation of the function that you are using, or the type annotation of an existing object. If the compiler does find such type annotation, it will use this type in your literal struct.\nAnonymous structs are very commonly used as inputs to function arguments in Zig. One example that you have seen already constantly, is the print() function from the stdout object. This function takes two arguments. The first argument, is a template string, which should contain string format specifiers in it, which tells how the values provided in the second argument should be printed into the message.\nWhile the second argument is a struct literal that lists the values to be printed into the template message specified in the first argument. You normally want to use an anonymous struct literal here, so that the zig compiler do the job of specifying the type of this particular anonymous struct for you.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n\nHello, world!\n\n\n\n\n2.3.2 Struct declarations must be constant\nTypes in Zig must be const or comptime (we are going to talk more about comptime in Section 12.1). What this means is that you cannot create a new data type, and mark it as variable with the var keyword. So struct declarations are always constant. You cannot declare a new struct type using the var keyword. It must be const.\nIn the Vec3 example below, this declaration is allowed because I’m using the const keyword to declare this new data type.\n\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n\n\n\n2.3.3 The self method argument\nIn every language that have OOP, when we declare a method of some class or struct, we usually declare this method as a function that has a self argument. This self argument is the reference to the object itself from which the method is being called from.\nIt’s not mandatory to use this self argument. But why would you not use this self argument? There is no reason to not use it. Because the only way to get access to the data stored in the data members of your struct is to access them through this self argument. If you don’t need to use the data in the data members of your struct inside your method, you very likely don’t need a method. You can just declare this logic as a simple function, outside of your struct declaration.\nTake the Vec3 struct below. Inside this Vec3 struct we declared a method named distance(). This method calculates the distance between two Vec3 objects, by following the distance formula in euclidean space. Notice that this distance() method takes two Vec3 objects as input, self and other.\n\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n\nThe self argument corresponds to the Vec3 object from which this distance() method is being called from. While the other is a separate Vec3 object that is given as input to this method. In the example below, the self argument corresponds to the object v1, because the distance() method is being called from the v1 object, while the other argument corresponds to the object v2.\n\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n\nDistance: 3.3970575502926055\n\n\n2.3.4 About the struct state\nSometimes you don’t need to care about the state of your struct object. Sometimes, you just need to instantiate and use the objects, without altering their state. You can notice that when you have methods inside your struct declaration that might use the values that are present in the data members, but they do not alter the values in these data members of the struct in anyway.\nThe Vec3 struct that was presented in Section 2.3.3 is an example of that. This struct have a single method named distance(), and this method does use the values present in all three data members of the struct (x, y and z). But at the same time, this method does not change the values of these data members at any point.\nAs a result of that, when we create Vec3 objects we usually create them as constant objects, like the v1 and v2 objects presented in Section 2.3.3. We can create them as variable objects with the var keyword, if we want to. But because the methods of this Vec3 struct do not change the state of the objects in any point, it’s unnecessary to mark them as variable objects.\nBut why? Why am I talking about this here? It’s because the self argument in the methods are affected depending on whether the methods present in a struct change or don’t change the state of the object itself. More specifically, when you have a method in a struct that changes the state of the object (i.e., changes the value of a data member), the self argument in this method must be annotated in a different manner.\nAs I described in Section 2.3.3, the self argument in methods of a struct is the argument that receives as input the object from which the method was called from. We usually annotate this argument in the methods by writing self, followed by the colon character (:), and the data type of the struct to which the method belongs to (e.g. User, Vec3, etc.).\nIf we take the Vec3 struct that we defined in the previous section as an example, we can see in the distance() method that this self argument is annotated as self: Vec3. Because the state of the Vec3 object is never altered by this method.\nBut what if we do have a method that alters the state of the object, by altering the values of its data members, how should we annotate self in this instance? The answer is: “we should annotate self as a pointer of x, instead of just x”. In other words, you should annotate self as self: *x, instead of annotating it as self: x.\nIf we create a new method inside the Vec3 object that, for example, expands the vector by multiplying its coordinates by a factor of two, then, we need to follow this rule specified in the previous paragraph. The code example below demonstrates this idea:\n\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n\nNotice in the code example above that we have added a new method to our Vec3 struct named twice(). This method doubles the coordinate values of our vector object. In the case of the twice() method, we annotated the self argument as *Vec3, indicating that this argument receives a pointer (or a reference, if you prefer to call it this way) to a Vec3 object as input.\n\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n\nDoubled: 8.4\nNow, if you change the self argument in this twice() method to self: Vec3, like in the distance() method, you will get the compiler error exposed below as result. Notice that this error message is showing a line from the twice() method body, indicating that you cannot alter the value of the x data member.\n\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\nThis error message indicates that the x data member belongs to a constant object, and, because of that, it cannot be changed. Ultimately, this error message is telling us that the self argument is constant.\nIf you take some time, and think hard about this error message, you will understand it. You already have the tools to understand why we are getting this error message. We have talked about it already in Section 2.2. So remember, every function argument is immutable in Zig, and self is no exception to this rule.\nIn this example, we marked the v3 object as a variable object. But this does not matter. Because it’s not about the input object, it’s about the function argument.\nThe problem begins when we try to alter the value of self directly, which is a function argument, and, every function argument is immutable by default. You may ask yourself how can we overcome this barrier, and once again, the solution was also discussed in Section 2.2. We overcome this barrier, by explicitly marking the self argument as a pointer.\n\n\n\n\n\n\nNote\n\n\n\nIf a method of your x struct alters the state of the object, by changing the value of any data member, then, remember to use self: *x, instead of self: x in the function signature of this method.\n\n\nYou could also interpret the content discussed in this section as: “if you need to alter the state of your x struct object in one of its methods, you must explicitly pass the x struct object by reference to the self argument of this method”.",
+    "text": "2.3 Structs and OOP\nZig is a language more closely related to C (which is a procedural language), than it is to C++ or Java (which are object-oriented languages). Because of that, you do not have advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or class inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C. You give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can also register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object that you create with this new type, will always have these methods available and associated with them.\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which is used to construct (or, to instantiate) every object of this particular class, and we also have a destructor method (or a destructor function), which is the function responsible for destroying every object of this class.\nIn Zig, we normally declare the constructor and the destructor methods of our structs, by declaring an init() and a deinit() methods inside the struct. This is just a naming convention that you will find across the entire Zig Standard Library. So, in Zig, the init() method of a struct is normally the constructor method of the class represented by this struct. While the deinit() method is the method used for destroying an existing instance of that struct.\nThe init() and deinit() methods are both used extensively in Zig code, and you will see both of them being used when we talk about allocators in Section 3.3. But, as another example, let’s build a simple User struct to represent a user of some sort of system.\nIf you look at the User struct below, you can see the struct keyword. Notice the data members of this struct: id, name and email. Every data member has its type explicitly annotated, with the colon character (:) syntax that we described earlier in Section 1.2.2. But also notice that every line in the struct body that describes a data member, ends with a comma character (,). So every time you declare a data member in your Zig code, always end the line with a comma character, instead of ending it with the traditional semicolon character (;).\nNext, we have registered an init() function as a method of this User struct. This init() method is the constructor method that we will use to instantiate every new User object. That is why this init() function returns a new User object as result.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    fn init(id: u64,\n                name: []const u8,\n                email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n\npedro\n\n\n\n2.3.1 The pub keyword\nThe pub keyword plays an important role in struct declarations, and OOP in Zig. In essence, this keyword is short for “public”, and it makes an item/component available outside of the module where this item/component is declared. In other words, if I don’t apply the pub keyword on something, it means that this “something” is available to be called/used only from within the module where this “something” is declared.\nTo demonstrate the effect of this keyword let’s focus again on the User struct that we have declared on the previous section. For our example here, let’s suppose that this User struct is declared inside a Zig module named user.zig. If I don’t use the pub keyword on the User struct, it means that I can create an User object, and call it’s methods (print_name() and init()) only from within the module where the User struct is declared, which in this case is the user.zig module.\nThis is why the previous code example works fine. Because we declare and also use the User struct inside the same module. But problems start to arise when we try to import and call/use this struct from another module. For example, if I create a new module called register.zig, and import the user.zig module into it, and try to annotate any variable with the User type, I get an error from the compiler.\n// register.zig\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = undefined;\n    _ = u;\n}\nregister.zig:3:18: error: 'User' is not marked 'pub'\n    const u: user.User = undefined;\n             ~~~~^~~~~\nuser.zig:3:1: note: declared here\nconst User = struct {\n^~~~~\nTherefore, if you want to use something outside of the module where this “something” is declared, you have to mark it with the pub keyword. This “something” can be a module, a struct, a function, an object, etc.\nFor our example here, if we go back to the user.zig module, and add the pub keyword to the User struct declaration, then, I can successfully compile the register.zig module.\n// user.zig\n// Added the `pub` keyword to `User`\npub const User = struct {\n// ...\n// register.zig\n// This works fine now!\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = undefined;\n    _ = u;\n}\nNow, what do you think it will happen if I try to actually call from register.zig any of the methods of the User struct? For example, if I try to call the init() method? The answer is: I get a similar error message, warning me that the init() method is not marked as pub, as you can see below:\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = user.User.init(\n        1, \"pedro\", \"email@gmail.com\"\n    );\n    _ = u;\n}\nregister.zig:3:35: error: 'init' is not marked 'pub'\n    const u: user.User = user.User.init(\n                         ~~~~~~~~~^~~~~\nuser.zig:8:5: note: declared here\n    fn init(id: u64,\n    ^~~~~~~\nThus, just because we have applied the pub keyword on the struct declaration, this does not make the methods of that struct public as well. If we want to use any method from a struct (such as the init() method) outside of the module where this struct is declared, we have to mark this method with the pub keyword as well.\nGoing back to the user.zig module, and marking both the init() and print_name() methods with the pub keyword, makes them both available to the outside world, and, as consequence, makes the previous code example work.\n// user.zig\n// Added the `pub` keyword to `User.init`\n    pub fn init(\n// ...\n// Added the `pub` keyword to `User.print_name`\n    pub fn print_name(self: User) !void {\n// ...\n// register.zig\n// This works fine now!\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = user.User.init(\n        1, \"pedro\", \"email@gmail.com\"\n    );\n    _ = u;\n}\n\n\n2.3.2 Anonymous struct literals\nYou can declare a struct object as a literal value. When we do that, we normally specify the data type of this struct literal by writing its data type just before the opening curly brace. For example, I could write a struct literal value of the type User that we have defined in the previous section like this:\n\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a struct literal, but not specify explicitly the type of this particular struct. An anonymous struct is written by using the syntax .{}. So, we essentially replaced the explicit type of the struct literal with a dot character (.).\nAs we described in Section 2.4, when you put a dot before a struct literal, the type of this struct literal is automatically inferred by the zig compiler. In essence, the zig compiler will look for some hint of what is the type of that struct. This hint can be the type annotation of a function argument, or the return type annotation of the function that you are using, or the type annotation of an existing object. If the compiler does find such type annotation, it will use this type in your literal struct.\nAnonymous structs are very commonly used as inputs to function arguments in Zig. One example that you have seen already constantly, is the print() function from the stdout object. This function takes two arguments. The first argument, is a template string, which should contain string format specifiers in it, which tells how the values provided in the second argument should be printed into the message.\nWhile the second argument is a struct literal that lists the values to be printed into the template message specified in the first argument. You normally want to use an anonymous struct literal here, so that the zig compiler do the job of specifying the type of this particular anonymous struct for you.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n\nHello, world!\n\n\n\n\n2.3.3 Struct declarations must be constant\nTypes in Zig must be const or comptime (we are going to talk more about comptime in Section 12.1). What this means is that you cannot create a new data type, and mark it as variable with the var keyword. So struct declarations are always constant. You cannot declare a new struct type using the var keyword. It must be const.\nIn the Vec3 example below, this declaration is allowed because I’m using the const keyword to declare this new data type.\n\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n\n\n\n2.3.4 The self method argument\nIn every language that have OOP, when we declare a method of some class or struct, we usually declare this method as a function that has a self argument. This self argument is the reference to the object itself from which the method is being called from.\nIt’s not mandatory to use this self argument. But why would you not use this self argument? There is no reason to not use it. Because the only way to get access to the data stored in the data members of your struct is to access them through this self argument. If you don’t need to use the data in the data members of your struct inside your method, you very likely don’t need a method. You can just declare this logic as a simple function, outside of your struct declaration.\nTake the Vec3 struct below. Inside this Vec3 struct we declared a method named distance(). This method calculates the distance between two Vec3 objects, by following the distance formula in euclidean space. Notice that this distance() method takes two Vec3 objects as input, self and other.\n\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n\nThe self argument corresponds to the Vec3 object from which this distance() method is being called from. While the other is a separate Vec3 object that is given as input to this method. In the example below, the self argument corresponds to the object v1, because the distance() method is being called from the v1 object, while the other argument corresponds to the object v2.\n\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n\nDistance: 3.3970575502926055\n\n\n2.3.5 About the struct state\nSometimes you don’t need to care about the state of your struct object. Sometimes, you just need to instantiate and use the objects, without altering their state. You can notice that when you have methods inside your struct declaration that might use the values that are present in the data members, but they do not alter the values in these data members of the struct in anyway.\nThe Vec3 struct that was presented in Section 2.3.4 is an example of that. This struct have a single method named distance(), and this method does use the values present in all three data members of the struct (x, y and z). But at the same time, this method does not change the values of these data members at any point.\nAs a result of that, when we create Vec3 objects we usually create them as constant objects, like the v1 and v2 objects presented in Section 2.3.4. We can create them as variable objects with the var keyword, if we want to. But because the methods of this Vec3 struct do not change the state of the objects in any point, it’s unnecessary to mark them as variable objects.\nBut why? Why am I talking about this here? It’s because the self argument in the methods are affected depending on whether the methods present in a struct change or don’t change the state of the object itself. More specifically, when you have a method in a struct that changes the state of the object (i.e., changes the value of a data member), the self argument in this method must be annotated in a different manner.\nAs I described in Section 2.3.4, the self argument in methods of a struct is the argument that receives as input the object from which the method was called from. We usually annotate this argument in the methods by writing self, followed by the colon character (:), and the data type of the struct to which the method belongs to (e.g. User, Vec3, etc.).\nIf we take the Vec3 struct that we defined in the previous section as an example, we can see in the distance() method that this self argument is annotated as self: Vec3. Because the state of the Vec3 object is never altered by this method.\nBut what if we do have a method that alters the state of the object, by altering the values of its data members, how should we annotate self in this instance? The answer is: “we should annotate self as a pointer of x, instead of just x”. In other words, you should annotate self as self: *x, instead of annotating it as self: x.\nIf we create a new method inside the Vec3 object that, for example, expands the vector by multiplying its coordinates by a factor of two, then, we need to follow this rule specified in the previous paragraph. The code example below demonstrates this idea:\n\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n\nNotice in the code example above that we have added a new method to our Vec3 struct named twice(). This method doubles the coordinate values of our vector object. In the case of the twice() method, we annotated the self argument as *Vec3, indicating that this argument receives a pointer (or a reference, if you prefer to call it this way) to a Vec3 object as input.\n\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n\nDoubled: 8.4\nNow, if you change the self argument in this twice() method to self: Vec3, like in the distance() method, you will get the compiler error exposed below as result. Notice that this error message is showing a line from the twice() method body, indicating that you cannot alter the value of the x data member.\n\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\nThis error message indicates that the x data member belongs to a constant object, and, because of that, it cannot be changed. Ultimately, this error message is telling us that the self argument is constant.\nIf you take some time, and think hard about this error message, you will understand it. You already have the tools to understand why we are getting this error message. We have talked about it already in Section 2.2. So remember, every function argument is immutable in Zig, and self is no exception to this rule.\nIn this example, we marked the v3 object as a variable object. But this does not matter. Because it’s not about the input object, it’s about the function argument.\nThe problem begins when we try to alter the value of self directly, which is a function argument, and, every function argument is immutable by default. You may ask yourself how can we overcome this barrier, and once again, the solution was also discussed in Section 2.2. We overcome this barrier, by explicitly marking the self argument as a pointer.\n\n\n\n\n\n\nNote\n\n\n\nIf a method of your x struct alters the state of the object, by changing the value of any data member, then, remember to use self: *x, instead of self: x in the function signature of this method.\n\n\nYou could also interpret the content discussed in this section as: “if you need to alter the state of your x struct object in one of its methods, you must explicitly pass the x struct object by reference to the self argument of this method”.",
     "crumbs": [
       "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
     ]
@@ -264,7 +264,7 @@
     "href": "Chapters/03-structs.html#sec-type-inference",
     "title": "2  Control flow, structs, modules and types",
     "section": "2.4 Type inference",
-    "text": "2.4 Type inference\nZig is a strongly typed language. But, there are some situations where you don’t have to explicitly write the type of every single object in your source code, as you would expect from a traditional strongly typed language, such as C and C++.\nIn some situations, the zig compiler can use type inference to solve the data types for you, easing some of the burden that you carry as a developer. The most common way this happens is through function arguments that receive struct objects as input.\nIn general, type inference in Zig is done by using the dot character (.). Everytime you see a dot character written before a struct literal, or before an enum value, or something like that, you know that this dot character is playing a special part in this place. More specifically, it’s telling the zig compiler something along the lines of: “Hey! Can you infer the type of this value for me? Please!”. In other words, this dot character is playing a similar role as the auto keyword in C++.\nI gave you some examples of this in Section 2.3.1, where we used anonymous struct literals. Anonymous struct literals are, struct literals that use type inference to infer the exact type of this particular struct literal. This type inference is done by looking for some minimal hint of the correct data type to be used. You could say that the zig compiler looks for any neighbouring type annotation that might tell it what the correct type would be.\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in Section 2.1.2). I also gave some other examples of type inference in Section 2.1.2, where we were inferring the data types of enum values listed inside of switch statements (e.g. .DE). But as another example, take a look at this fence() function reproduced below, which comes from the atomic.zig module2 of the Zig Standard Library.\nThere are a lot of things in this function that we haven’t talked about yet, such as: what comptime means? inline? extern? Let’s just ignore all of these things, and focus solely on the switch statement that is inside this function.\nWe can see that this switch statement uses the order object as input. This order object is one of the inputs of this fence() function, and we can see in the type annotation, that this object is of type AtomicOrder. We can also see a bunch of values inside the switch statements that begin with a dot character, such as .release and .acquire.\nBecause these weird values contain a dot character before them, we are asking the zig compiler to infer the types of these values inside the switch statement. Then, the zig compiler is looking into the current context where these values are being used, and trying to infer the types of these values.\nSince they are being used inside a switch statement, the zig compiler looks into the type of the input object given to the switch statement, which is the order object in this case. Because this object have type AtomicOrder, the zig compiler infers that these values are data members from this type AtomicOrder.\n\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic =&gt; @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire =&gt; tsan.__tsan_acquire(addr),\n            .release =&gt; tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst =&gt; {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n\nThis is how basic type inference is done in Zig. If we didn’t use the dot character before the values inside this switch statement, then, we would be forced to explicitly write the data types of these values. For example, instead of writing .release we would have to write AtomicOrder.release. We would have to do this for every single value in this switch statement, and this is a lot of work. That is why type inference is commonly used on switch statements in Zig.",
+    "text": "2.4 Type inference\nZig is a strongly typed language. But, there are some situations where you don’t have to explicitly write the type of every single object in your source code, as you would expect from a traditional strongly typed language, such as C and C++.\nIn some situations, the zig compiler can use type inference to solve the data types for you, easing some of the burden that you carry as a developer. The most common way this happens is through function arguments that receive struct objects as input.\nIn general, type inference in Zig is done by using the dot character (.). Everytime you see a dot character written before a struct literal, or before an enum value, or something like that, you know that this dot character is playing a special part in this place. More specifically, it’s telling the zig compiler something along the lines of: “Hey! Can you infer the type of this value for me? Please!”. In other words, this dot character is playing a similar role as the auto keyword in C++.\nI gave you some examples of this in Section 2.3.2, where we used anonymous struct literals. Anonymous struct literals are, struct literals that use type inference to infer the exact type of this particular struct literal. This type inference is done by looking for some minimal hint of the correct data type to be used. You could say that the zig compiler looks for any neighbouring type annotation that might tell it what the correct type would be.\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in Section 2.1.2). I also gave some other examples of type inference in Section 2.1.2, where we were inferring the data types of enum values listed inside of switch statements (e.g. .DE). But as another example, take a look at this fence() function reproduced below, which comes from the atomic.zig module2 of the Zig Standard Library.\nThere are a lot of things in this function that we haven’t talked about yet, such as: what comptime means? inline? extern? Let’s just ignore all of these things, and focus solely on the switch statement that is inside this function.\nWe can see that this switch statement uses the order object as input. This order object is one of the inputs of this fence() function, and we can see in the type annotation, that this object is of type AtomicOrder. We can also see a bunch of values inside the switch statements that begin with a dot character, such as .release and .acquire.\nBecause these weird values contain a dot character before them, we are asking the zig compiler to infer the types of these values inside the switch statement. Then, the zig compiler is looking into the current context where these values are being used, and trying to infer the types of these values.\nSince they are being used inside a switch statement, the zig compiler looks into the type of the input object given to the switch statement, which is the order object in this case. Because this object have type AtomicOrder, the zig compiler infers that these values are data members from this type AtomicOrder.\n\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic =&gt; @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire =&gt; tsan.__tsan_acquire(addr),\n            .release =&gt; tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst =&gt; {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n\nThis is how basic type inference is done in Zig. If we didn’t use the dot character before the values inside this switch statement, then, we would be forced to explicitly write the data types of these values. For example, instead of writing .release we would have to write AtomicOrder.release. We would have to do this for every single value in this switch statement, and this is a lot of work. That is why type inference is commonly used on switch statements in Zig.",
     "crumbs": [
       "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
     ]
@@ -274,7 +274,7 @@
     "href": "Chapters/03-structs.html#sec-type-cast",
     "title": "2  Control flow, structs, modules and types",
     "section": "2.5 Type casting",
-    "text": "2.5 Type casting\nIn this section, I want to discuss type casting (or, type conversion) with you. We use type casting when we have an object of type “x”, and we want to convert it into an object of type “y”, i.e., we want to change the data type of the object.\nMost languages have a formal way to perform type casting. In Rust for example, we normally use the keyword as, and in C, we normally use the type casting syntax, e.g. (int) x. In Zig, we use the @as() built-in function to cast an object of type “x”, into an object of type “y”.\nThis @as() function is the preferred way to perform type conversion (or type casting) in Zig. Because it’s explicit, and, it also performs the casting only if it is unambiguous and safe. To use this function, you just provide the target data type in the first argument, and, the object that you want cast as the second argument.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n\n1/1 file79ce58134f59.test_0...OKAll 1 tests passed\n  d.\n\n\nThis is the general way to perform type casting in Zig. But remember, @as() works only when casting is unambiguous and safe. There are many situations where these assumptions do not hold. For example,\nwhen casting an integer value into a float value, or vice-versa, it’s not clear to the compiler how to perform this conversion safely.\nTherefore, we need to use specialized “casting functions” in such situations. For example, if you want to cast an integer value into a float value, then, you should use the @floatFromInt() function. In the inverse scenario, you should use the @intFromFloat() function.\nIn these functions, you just provide the object that you want to cast as input. Then, the target data type of the “type casting operation” is determined by the type annotation of the object where you are saving the results. In the example below, we are casting the object x into a value of type f32, because the object y, which is where we are saving the results, is annotated as an object of type f32.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n\n1/1 file79ce286cee5b.test_0...OKAll 1 tests passed\n  d.\n\n\nAnother built-in function that is very useful when performing type casting operations is @ptrCast(). In essence, we use the @as() built-in function when we want to explicit convert (or cast) a Zig value/object from a type “x” to a type “y”, etc. However, pointers (we are going to discuss pointers in more depth in Chapter 6) are a special type of object in Zig, i.e., they are treated differently from “normal objects”.\nEverytime a pointer is involved in some “type casting operation” in Zig, the @ptrCast() function is used. This function works similarly to @floatFromInt(). You just provide the pointer object that you want to cast as input to this function, and the target data type is, once again, determined by the type annotation of the object where the results are being stored.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n\n1/1 file79ce1e7313c8.test_0...OKAll 1 tests passed\n  d.",
+    "text": "2.5 Type casting\nIn this section, I want to discuss type casting (or, type conversion) with you. We use type casting when we have an object of type “x”, and we want to convert it into an object of type “y”, i.e., we want to change the data type of the object.\nMost languages have a formal way to perform type casting. In Rust for example, we normally use the keyword as, and in C, we normally use the type casting syntax, e.g. (int) x. In Zig, we use the @as() built-in function to cast an object of type “x”, into an object of type “y”.\nThis @as() function is the preferred way to perform type conversion (or type casting) in Zig. Because it’s explicit, and, it also performs the casting only if it is unambiguous and safe. To use this function, you just provide the target data type in the first argument, and, the object that you want cast as the second argument.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n\n1/1 file3c448aa9d5f.test_0...OKAll 1 tests passed.\n\n\nThis is the general way to perform type casting in Zig. But remember, @as() works only when casting is unambiguous and safe. There are many situations where these assumptions do not hold. For example,\nwhen casting an integer value into a float value, or vice-versa, it’s not clear to the compiler how to perform this conversion safely.\nTherefore, we need to use specialized “casting functions” in such situations. For example, if you want to cast an integer value into a float value, then, you should use the @floatFromInt() function. In the inverse scenario, you should use the @intFromFloat() function.\nIn these functions, you just provide the object that you want to cast as input. Then, the target data type of the “type casting operation” is determined by the type annotation of the object where you are saving the results. In the example below, we are casting the object x into a value of type f32, because the object y, which is where we are saving the results, is annotated as an object of type f32.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n\n1/1 file3c4427337b66.test_0...OKAll 1 tests passed\n  d.\n\n\nAnother built-in function that is very useful when performing type casting operations is @ptrCast(). In essence, we use the @as() built-in function when we want to explicit convert (or cast) a Zig value/object from a type “x” to a type “y”, etc. However, pointers (we are going to discuss pointers in more depth in Chapter 6) are a special type of object in Zig, i.e., they are treated differently from “normal objects”.\nEverytime a pointer is involved in some “type casting operation” in Zig, the @ptrCast() function is used. This function works similarly to @floatFromInt(). You just provide the pointer object that you want to cast as input to this function, and the target data type is, once again, determined by the type annotation of the object where the results are being stored.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n\n1/1 file3c4479f1f6f8.test_0...OKAll 1 tests passed\n  d.",
     "crumbs": [
       "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
     ]

From dc1d0863a231ba0dd2d7435d522cb1a678c34dfb Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sat, 8 Mar 2025 12:07:28 -0300
Subject: [PATCH 117/151] Fix indentation

---
 Chapters/03-structs.qmd                               |  4 ++--
 _freeze/Chapters/03-structs/execute-results/html.json |  4 ++--
 docs/Chapters/03-structs.html                         | 11 ++++++-----
 docs/search.json                                      |  4 ++--
 4 files changed, 12 insertions(+), 11 deletions(-)

diff --git a/Chapters/03-structs.qmd b/Chapters/03-structs.qmd
index ba5f7069..56c67e00 100644
--- a/Chapters/03-structs.qmd
+++ b/Chapters/03-structs.qmd
@@ -760,8 +760,8 @@ const User = struct {
     email: []const u8,
 
     fn init(id: u64,
-                name: []const u8,
-                email: []const u8) User {
+            name: []const u8,
+            email: []const u8) User {
 
         return User {
             .id = id,
diff --git a/_freeze/Chapters/03-structs/execute-results/html.json b/_freeze/Chapters/03-structs/execute-results/html.json
index fbe83947..a05f2337 100644
--- a/_freeze/Chapters/03-structs/execute-results/html.json
+++ b/_freeze/Chapters/03-structs/execute-results/html.json
@@ -1,8 +1,8 @@
 {
-  "hash": "10ffcb221f40a28afe7a41688091c355",
+  "hash": "eb1d22d8dc0121e7c7768b70c606a801",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Control flow, structs, modules and types\n\nWe have discussed a lot of Zig's syntax in the last chapter,\nespecially in @sec-root-file and @sec-main-file.\nBut we still need to discuss some other very important\nelements of the language. Elements that you will use constantly on your day-to-day\nroutine.\n\nWe begin this chapter by discussing the different keywords and structures\nin Zig related to control flow (e.g. loops and if statements).\nThen, we talk about structs and how they can be used to do some\nbasic Object-Oriented (OOP) patterns in Zig. We also talk about\ntype inference and type casting.\nFinally, we end this chapter by discussing modules, and how they relate\nto structs.\n\n\n\n## Control flow {#sec-zig-control-flow}\n\nSometimes, you need to make decisions in your program. Maybe you need to decide\nwhether or not to execute a specific piece of code. Or maybe,\nyou need to apply the same operation over a sequence of values. These kinds of tasks,\ninvolve using structures that are capable of changing the \"control flow\" of our program.\n\nIn computer science, the term \"control flow\" usually refers to the order in which expressions (or commands)\nare evaluated in a given language or program. But this term is also used to refer\nto structures that are capable of changing this \"evaluation order\" of the commands\nexecuted by a given language/program.\n\nThese structures are better known\nby a set of terms, such as: loops, if/else statements, switch statements, among others. So,\nloops and if/else statements are examples of structures that can change the \"control\nflow\" of our program. The keywords `continue` and `break` are also examples of symbols\nthat can change the order of evaluation, since they can move our program to the next iteration\nof a loop, or make the loop stop completely.\n\n\n### If/else statements\n\nAn if/else statement performs a \"conditional flow operation\".\nA conditional flow control (or choice control) allows you to execute\nor ignore a certain block of commands based on a logical condition.\nMany programmers and computer science professionals also use\nthe term \"branching\" in this case.\nIn essence, an if/else statement allow us to use the result of a logical test\nto decide whether or not to execute a given block of commands.\n\nIn Zig, we write if/else statements by using the keywords `if` and `else`.\nWe start with the `if` keyword followed by a logical test inside a pair\nof parentheses, followed by a pair of curly braces which contains the lines\nof code to be executed in case the logical test returns the value `true`.\n\nAfter that, you can optionally add an `else` statement. To do that, just add the `else`\nkeyword followed by a pair of curly braces, with the lines of code\nto executed in case the logical test defined at `if` returns `false`.\n\nIn the example below, we are testing if the object `x` contains a number\nthat is greater than 10. Judging by the output printed to the console,\nwe know that this logical test returned `false`. Because the output\nin the console is compatible with the line of code present in the\n`else` branch of the if/else statement.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x = 5;\nif (x > 10) {\n    try stdout.print(\n        \"x > 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x <= 10!\\n\", .{}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nx <= 10!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n### Switch statements {#sec-switch}\n\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust.\nAs you would expect, to write a switch statement in Zig we use the `switch` keyword.\nWe provide the value that we want to \"switch over\" inside a\npair of parentheses. Then, we list the possible combinations (or \"branches\")\ninside a pair of curly braces.\n\nLet's take a look at the code example below. You can see that\nI'm creating an enum type called `Role`. We talk more about enums in @sec-enum.\nBut in summary, this `Role` type is listing different types of roles in a fictitious\ncompany, like `SE` for Software Engineer, `DE` for Data Engineer, `PM` for Product Manager,\netc.\n\nNotice that we are using the value from the `role` object in the\nswitch statement, to discover which exact area we need to store in the `area` variable object.\nAlso notice that we are using type inference inside the switch statement, with the dot character,\nas we are going to describe in @sec-type-inference.\nThis makes the `zig` compiler infer the correct data type of the values (`PM`, `SE`, etc.) for us.\n\nAlso notice that, we are grouping multiple values in the same branch of the switch statement.\nWe just separate each possible value with a comma. For example, if `role` contains either `DE` or `DA`,\nthe `area` variable would contain the value `\"Data & Analytics\"`, instead of `\"Platform\"` or `\"Sales\"`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO => {\n            area = \"Platform\";\n        },\n        .DE, .DA => {\n            area = \"Data & Analytics\";\n        },\n        .KS => {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nPlatform\n```\n\n\n:::\n:::\n\n\n\n\n\n\n#### Switch statements must exhaust all possibilities\n\nOne very important aspect about switch statements in Zig\nis that they must exhaust all existing possibilities.\nIn other words, all possible values that could be found inside the `role`\nobject must be explicitly handled in this switch statement.\n\nSince the `role` object has type `Role`, the only possible values to\nbe found inside this object are `PM`, `SE`, `DPE`, `PO`, `DE`, `DA` and `KS`.\nThere are no other possible values to be stored in this `role` object.\nThus, the switch statements must have a combination (branch) for each one of these values.\nThis is what \"exhaust all existing possibilities\" means. The switch statement covers\nevery possible case.\n\nTherefore, you cannot write a switch statement in Zig, and leave an edge case\nwith no explicit action to be taken.\nThis is a similar behaviour to switch statements in Rust, which also have to\nhandle all possible cases.\n\n\n\n#### The else branch\n\nTake a look at the `dump_hex_fallible()` function below as an example. This function\ncomes from the Zig Standard Library. More precisely, from the\n[`debug.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/debug.zig)[^debug-mod].\nThere are multiple lines in this function, but I omitted them to focus solely on the\nswitch statement found in this function. Notice that this switch statement has four\npossible cases (i.e., four explicit branches). Also, notice that we used an `else` branch\nin this case.\n\nAn `else` branch in a switch statement works as the \"default branch\".\nWhenever you have multiple cases in your switch statement where\nyou want to apply the exact same action, you can use an `else` branch to do that.\n\n[^debug-mod]: <https://github.com/ziglang/zig/blob/master/lib/std/debug.zig>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' => try writer.writeAll(\"␊\"),\n        '\\r' => try writer.writeAll(\"␍\"),\n        '\\t' => try writer.writeAll(\"␉\"),\n        else => try writer.writeByte('.'),\n    }\n}\n```\n:::\n\n\n\n\n\nMany programmers would also use an `else` branch to handle a \"not supported\" case.\nThat is, a case that cannot be properly handled by your code, or, just a case that\nshould not be \"fixed\". Therefore, you can use an `else` branch to panic (or raise an error)\nin your program to stop the current execution.\n\nTake the code example below. We can see that, we are handling the cases\nfor the `level` object being either 1, 2, or 3. All other possible cases are not supported by default,\nand, as consequence, we raise a runtime error in such cases through the `@panic()` built-in function.\n\nAlso notice that, we are assigning the result of the switch statement to a new object called `category`.\nThis is another thing that you can do with switch statements in Zig. If a branch\noutputs a value as result, you can store the result value of the switch statement into\na new object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 => \"beginner\",\n    3 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n:::\n\n\n\n\n\n```\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n```\n\n\n\n#### Using ranges in switch\n\nFurthermore, you can also use ranges of values in switch statements.\nThat is, you can create a branch in your switch statement that is used\nwhenever the input value is within the specified range. These \"range expressions\"\nare created with the operator `...`. It's important\nto emphasize that the ranges created by this operator are\ninclusive on both ends.\n\nFor example, I could easily change the previous code example to support all\nlevels between 0 and 100. Like this:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 => \"beginner\",\n    26...75 => \"intermediary\",\n    76...100 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nbeginner\n```\n\n\n:::\n:::\n\n\n\n\n\nThis is neat, and it works with character ranges too. That is, I could\nsimply write `'a'...'z'`, to match any character value that is a\nlowercase letter, and it would work fine.\n\n\n#### Labeled switch statements\n\nIn @sec-blocks we have talked about labeling blocks, and also, about using these labels\nto return a value from the block. Well, from version 0.14.0 and onwards of the `zig` compiler,\nyou can also apply labels over switch statements, which makes it possible to almost implement a\n\"C `goto`\" like pattern.\n\nFor example, if you give the label `xsw` to a switch statement, you can use this\nlabel in conjunction with the `continue` keyword to go back to the beginning of the switch\nstatement. In the example below, the execution goes back to the beginning of the\nswitch statement two times, before ending at the `3` branch.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nxsw: switch (@as(u8, 1)) {\n    1 => {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 => continue :xsw 3,\n    3 => return,\n    4 => {},\n    else => {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n```\n:::\n\n\n\n\n\n\n### The `defer` keyword {#sec-defer}\n\nWith the `defer` keyword you can register an expression to be executed when you exit the current scope.\nTherefore, this keyword has a similar functionality as the `on.exit()` function from R.\nTake the `foo()` function below as an example. When we execute this `foo()` function, the expression\nthat prints the message \"Exiting function ...\" is getting executed only when the function exits\nits scope.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n```\n:::\n\n\n\n\n\n```\nAdding some numbers ...\nMultiplying ...\nExiting function ...\n```\n\nTherefore, we can use `defer` to declare an expression that is going to be executed\nwhen your code exits the current scope. Some programmers like to interpret the phrase \"exit of the current scope\"\nas \"the end of the current scope\". But this interpretation might not be entirely correct, depending\non what you consider as \"the end of the current scope\".\n\nI mean, what do you consider as **the end** of the current scope? Is it the closing curly bracket (`}`) of the scope?\nIs it when the last expression in the function gets executed? Is it when the function returns to the previous scope?\nEtc. For example, it would not be correct to interpret the \"exit of the current scope\" as the closing\ncurly bracket of the scope. Because the function might exit from an earlier position than this\nclosing curly bracket (e.g. an error value was generated at a previous line inside the function;\nthe function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\n\nNow, if you remember of what we have discussed in @sec-blocks, there are multiple structures in the language\nthat create their own separate scopes. For/while loops, if/else statements,\nfunctions, normal blocks, etc. This also affects the interpretation of `defer`.\nFor example, if you use `defer` inside a for loop, then, the given expression\nwill be executed everytime this specific for loop exits its own scope.\n\nBefore we continue, it's worth emphasizing that the `defer` keyword is an \"unconditional defer\".\nWhich means that the given expression will be executed no matter how the code exits\nthe current scope. For example, your code might exit the current scope because of an error value\nbeing generated, or, because of a return statement, or, a break statement, etc.\n\n\n\n### The `errdefer` keyword {#sec-errdefer1}\n\nOn the previous section, we have discussed the `defer` keyword, which you can use to\nregister an expression to be executed at the exit of the current scope.\nBut this keyword has a brother, which is the `errdefer` keyword. While `defer`\nis an \"unconditional defer\", the `errdefer` keyword is a \"conditional defer\".\nWhich means that the given expression is executed only when you exit the current\nscope on a very specific circumstance.\n\nIn more details, the expression given to `errdefer` is executed only when an error occurs in the current scope.\nTherefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope\nin a normal situation, without errors, the expression given to `errdefer` is not executed.\n\nThis makes the `errdefer` keyword one of the many tools available in Zig for error handling.\nIn this section, we are more concerned with the control flow aspects around `errdefer`.\nBut we are going to discuss `errdefer` later as a error handling tool in @sec-errdefer2.\n\nThe code example below demonstrates three things:\n\n- that `defer` is an \"unconditional defer\", because the given expression gets executed regardless of how the function `foo()` exits its own scope.\n- that `errdefer` is executed because the function `foo()` returned an error value.\n- that `defer` and `errdefer` expressions are executed in a LIFO (*last in, first out*) order.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n```\n:::\n\n\n\n\n\n```\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\nWhen I say that \"defer expressions\" are executed in a LIFO order, what I want to say is that\nthe last `defer` or `errdefer` expressions in the code are the first ones to be executed.\nYou could also interpret this as: \"defer expressions\" are executed from bottom to top, or,\nfrom last to first.\n\nTherefore, if I change the order of the `defer` and `errdefer` expressions, you will notice that\nthe value of `i` that gets printed to the console changes to 1. This doesn't mean that the\n`defer` expression was not executed in this case. This actually means that the `defer` expression\nwas executed only after the `errdefer` expression. The code example below demonstrates this:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n```\n:::\n\n\n\n\n\n```\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\n\n\n### For loops\n\nA loop allows you to execute the same lines of code multiple times,\nthus, creating a \"repetition space\" in the execution flow of your program.\nLoops are particularly useful when we want to replicate the same function\n(or the same set of commands) over different inputs.\n\nThere are different types of loops available in Zig. But the most\nessential of them all is probably the *for loop*. A for loop is\nused to apply the same piece of code over the elements of a slice, or, an array.\n\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from\nother languages. You start with the `for` keyword, then, you\nlist the items that you want to iterate\nover inside a pair of parentheses. Then, inside of a pair of pipes (`|`)\nyou should declare an identifier that will serve as your iterator, or,\nthe \"repetition index of the loop\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (items) |value| {\n    // code to execute\n}\n```\n:::\n\n\n\n\n\nTherefore, instead of using a `(value in items)` syntax,\nin Zig, for loops use the syntax `(items) |value|`. In the example\nbelow, you can see that we are looping through the items\nof the array stored at the object `name`, and printing to the\nconsole the decimal representation of each character in this array.\n\nIf we wanted, we could also iterate through a slice (or a portion) of\nthe array, instead of iterating through the entire array stored in the `name` object.\nJust use a range selector to select the section you want. For example,\nI could provide the expression `name[0..3]` to the for loop, to iterate\njust through the first 3 elements in the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n80 | 101 | 100 | 114 | 111 | \n```\n\n\n:::\n:::\n\n\n\n\n\nIn the above example we are using the value itself of each\nelement in the array as our iterator. But there are many situations where\nwe need to use an index instead of the actual values of the items.\n\nYou can do that by providing a second set of items to iterate over.\nMore precisely, you provide the range selector `0..` to the for loop. So,\nyes, you can use two different iterators at the same time in a for\nloop in Zig.\n\nBut remember from @sec-assignments that, every object\nyou create in Zig must be used in some way. So if you declare two iterators\nin your for loop, you must use both iterators inside the for loop body.\nBut if you want to use just the index iterator, and not use the \"value iterator\",\nthen, you can discard the value iterator by maching the\nvalue items to the underscore character, like in the example below:\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n:::\n\n\n\n\n\n```\n0 | 1 | 2 | 3 | 4 |\n```\n\n\n### While loops\n\nA while loop is created from the `while` keyword. A `for` loop\niterates through the items of an array, but a `while` loop\nwill loop continuously, and infinitely, until a logical test\n(specified by you) becomes false.\n\nYou start with the `while` keyword, then, you define a logical\nexpression inside a pair of parentheses, and the body of the\nloop is provided inside a pair of curly braces, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\n\nYou can also specify the increment expression to be used at the beginning of a while loop.\nTo do that, we write the increment expression inside a pair of parentheses after a colon character (`:`).\nThe code example below demonstrates this other pattern.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\n\n### Using `break` and `continue`\n\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using\nthe keywords `break` and `continue`, respectively. The `while` loop presented in the next code example is,\nat first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to `true`.\nBut what makes this `while` loop stop when the `i` object reaches the count\n10? It's the `break` keyword!\n\nInside the while loop, we have an if statement that is constantly checking if the `i` variable\nis equal to 10. Since we are incrementing the value of `i` at each iteration of the\nwhile loop, this `i` object will eventually be equal to 10, and when it is, the if statement\nwill execute the `break` expression, and, as a result, the execution of the while loop is stopped.\n\nNotice the use of the `expect()` function from the Zig Standard Library after the while loop.\nThis `expect()` function is an \"assert\" type of function.\nThis function checks if the logical test provided is equal to true. If so, the function do nothing.\nOtherwise (i.e., the logical test is equal to false), the function raises an assertion error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nEverything worked!\n```\n\n\n:::\n:::\n\n\n\n\n\nSince this code example was executed successfully by the `zig` compiler,\nwithout raising any errors, we known that, after the execution of the while loop,\nthe `i` object is equal to 10. Because if it wasn't equal to 10, an error would have\nbeen raised by `expect()`.\n\nNow, in the next example, we have a use case for\nthe `continue` keyword. The if statement is constantly\nchecking if the current index is a multiple of 2. If\nit is, we jump to the next iteration of the loop.\nOtherwise, the loop just prints the current index to the console.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 3 | 5 | \n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n## Function parameters are immutable {#sec-fun-pars}\n\nWe have already discussed a lot of the syntax behind function declarations in @sec-root-file and @sec-main-file.\nBut I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig.\nIn summary, function parameters are immutable in Zig.\n\nTake the code example below, where we declare a simple function that just tries to add\nsome amount to the input integer, and returns the result back. If you look closely\nat the body of this `add2()` function, you will notice that we try\nto save the result back into the `x` function argument.\n\nIn other words, this function not only uses the value that it received through the function argument\n`x`, but it also tries to change the value of this function argument, by assigning the addition result\ninto `x`. However, function arguments in Zig are immutable. You cannot change their values, or, you\ncannot assign values to them inside the body's function.\n\nThis is the reason why, the code example below does not compile successfully. If you try to compile\nthis code example, you will get a compile error message about \"trying to change the value of a\nimmutable (i.e., constant) object\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n\n\n\n```\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n```\n\n\n### A free optimization\n\nIf a function argument receives as input an object whose data type is\nany of the primitive types that we have listed in @sec-primitive-data-types,\nthis object is always passed by value to the function. In other words, this object\nis copied into the function stack frame.\n\nHowever, if the input object have a more complex data type, for example, it might\nbe a struct instance, or an array, or an union value, etc., in cases like that, the `zig` compiler\nwill take the liberty of deciding for you which strategy is best. Thus, the `zig` compiler will\npass your object to the function either by value, or by reference. The compiler will always\nchoose the strategy that is faster for you.\nThis optimization that you get for free is possible only because function arguments are\nimmutable in Zig.\n\n\n### How to overcome this barrier\n\nThere are some situations where you might need to change the value of your function argument\ndirectly inside the function's body. This happens more often when we are passing\nC structs as inputs to Zig functions.\n\nIn a situation like this, you can overcome this barrier by using a pointer. In other words,\ninstead of passing a value as input to the argument, you can pass a \"pointer to value\" instead.\nYou can change the value that the pointer points to, by dereferencing it.\n\nTherefore, if we take our previous `add2()` example, we can change the value of the\nfunction argument `x` inside the function's body by marking the `x` argument as a\n\"pointer to a `u32` value\" (i.e., `*u32` data type), instead of a `u32` value.\nBy making it a pointer, we can finally alter the value of this function argument directly inside\nthe body of the `add2()` function. You can see that the code example below compiles successfully.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n```\n:::\n\n\n\n\n\n```\nResult: 6\n```\n\n\nEven in this code example above, the `x` argument is still immutable. Which means that the pointer itself is immutable.\nTherefore, you cannot change the memory address that it points to. However, you can dereference the pointer\nto access the value that it points to, and also, to change this value, if you need to.\n\n\n\n\n\n## Structs and OOP {#sec-structs-and-oop}\n\nZig is a language more closely related to C (which is a procedural language),\nthan it is to C++ or Java (which are object-oriented languages). Because of that, you do not\nhave advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or\nclass inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\n\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C.\nYou give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can\nalso register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object\nthat you create with this new type, will always have these methods available and associated with them.\n\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which\nis used to construct (or, to instantiate) every object of this particular class, and we also have\na destructor method (or a destructor function), which is the function responsible for destroying\nevery object of this class.\n\nIn Zig, we normally declare the constructor and the destructor methods\nof our structs, by declaring an `init()` and a `deinit()` methods inside the struct.\nThis is just a naming convention that you will find across the entire Zig Standard Library.\nSo, in Zig, the `init()` method of a struct is normally the constructor method of the class represented by this struct.\nWhile the `deinit()` method is the method used for destroying an existing instance of that struct.\n\nThe `init()` and `deinit()` methods are both used extensively in Zig code, and you will see both of\nthem being used when we talk about allocators in @sec-allocators.\nBut, as another example, let's build a simple `User` struct to represent a user of some sort of system.\n\nIf you look at the `User` struct below, you can see the `struct` keyword.\nNotice the data members of this struct: `id`, `name` and `email`. Every data member has its\ntype explicitly annotated, with the colon character (`:`) syntax that we described earlier in @sec-root-file.\nBut also notice that every line in the struct body that describes a data member, ends with a comma character (`,`).\nSo every time you declare a data member in your Zig code, always end the line with a comma character, instead\nof ending it with the traditional semicolon character (`;`).\n\nNext, we have registered an `init()` function as a method\nof this `User` struct. This `init()` method is the constructor method that we will use to instantiate\nevery new `User` object. That is why this `init()` function returns a new `User` object as result.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    fn init(id: u64,\n                name: []const u8,\n                email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\npedro\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n### The `pub` keyword\n\nThe `pub` keyword plays an important role in struct declarations, and OOP in Zig.\nIn essence, this keyword is short for \"public\", and it makes an item/component available outside of the\nmodule where this item/component is declared. In other words, if I don't apply the `pub` keyword on\nsomething, it means that this \"something\" is available to be called/used only from within the module\nwhere this \"something\" is declared.\n\nTo demonstrate the effect of this keyword let's focus again on the `User` struct that we have\ndeclared on the previous section. For our example here, let's suppose that this `User` struct is declared inside\na Zig module named `user.zig`. If I don't use the `pub` keyword on the `User` struct, it means that I can create\nan `User` object, and call it's methods (`print_name()` and `init()`) only from within the module where the `User`\nstruct is declared, which in this case is the `user.zig` module.\n\nThis is why the previous code example works fine. Because we declare and also use the `User` struct\ninside the same module. But problems start to arise when we try to import and call/use this struct\nfrom another module. For example, if I create a new module called `register.zig`, and import the `user.zig`\nmodule into it, and try to annotate any variable with the `User` type, I get an error from the compiler.\n\n```zig\n// register.zig\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = undefined;\n    _ = u;\n}\n```\n\n```\nregister.zig:3:18: error: 'User' is not marked 'pub'\n    const u: user.User = undefined;\n             ~~~~^~~~~\nuser.zig:3:1: note: declared here\nconst User = struct {\n^~~~~\n```\n\nTherefore, if you want to use something outside of the module where this \"something\" is declared,\nyou have to mark it with the `pub` keyword. This \"something\" can be a module,\na struct, a function, an object, etc.\n\nFor our example here, if we go back to the `user.zig` module, and add the `pub` keyword\nto the `User` struct declaration, then, I can successfully compile the `register.zig` module.\n\n```zig\n// user.zig\n// Added the `pub` keyword to `User`\npub const User = struct {\n// ...\n```\n\n```zig\n// register.zig\n// This works fine now!\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = undefined;\n    _ = u;\n}\n```\n\n\nNow, what do you think it will happen if I try to actually call from `register.zig` any of the methods\nof the `User` struct? For example, if I try to call the `init()` method? The answer is: I get a similar error message,\nwarning me that the `init()` method is not marked as `pub`, as you can see below:\n\n```zig\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = user.User.init(\n        1, \"pedro\", \"email@gmail.com\"\n    );\n    _ = u;\n}\n```\n\n```\nregister.zig:3:35: error: 'init' is not marked 'pub'\n    const u: user.User = user.User.init(\n                         ~~~~~~~~~^~~~~\nuser.zig:8:5: note: declared here\n    fn init(id: u64,\n    ^~~~~~~\n```\n\nThus, just because we have applied the `pub` keyword on the struct declaration,\nthis does not make the methods of that struct public as well. If we want to use\nany method from a struct (such as the `init()` method) outside of the module\nwhere this struct is declared, we have to mark this method with the `pub` keyword\nas well.\n\nGoing back to the `user.zig` module, and marking both the `init()` and `print_name()`\nmethods with the `pub` keyword, makes them both available to the outside world, and,\nas consequence, makes the previous code example work.\n\n\n```zig\n// user.zig\n// Added the `pub` keyword to `User.init`\n    pub fn init(\n// ...\n// Added the `pub` keyword to `User.print_name`\n    pub fn print_name(self: User) !void {\n// ...\n```\n\n```zig\n// register.zig\n// This works fine now!\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = user.User.init(\n        1, \"pedro\", \"email@gmail.com\"\n    );\n    _ = u;\n}\n```\n\n\n### Anonymous struct literals {#sec-anonymous-struct-literals}\n\nYou can declare a struct object as a literal value. When we do that, we normally specify the\ndata type of this struct literal by writing its data type just before the opening curly brace.\nFor example, I could write a struct literal value of the type `User` that we have defined\nin the previous section like this:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n```\n:::\n\n\n\n\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a\nstruct literal, but not specify explicitly the type of this particular struct.\nAn anonymous struct is written by using the syntax `.{}`. So, we essentially\nreplaced the explicit type of the struct literal with a dot character (`.`).\n\nAs we described in @sec-type-inference, when you put a dot before a struct literal,\nthe type of this struct literal is automatically inferred by the `zig` compiler.\nIn essence, the `zig` compiler will look for some hint of what is the type of that struct.\nThis hint can be the type annotation of a function argument,\nor the return type annotation of the function that you are using, or the type annotation\nof an existing object.\nIf the compiler does find such type annotation, it will use this\ntype in your literal struct.\n\nAnonymous structs are very commonly used as inputs to function arguments in Zig.\nOne example that you have seen already constantly, is the `print()`\nfunction from the `stdout` object.\nThis function takes two arguments.\nThe first argument, is a template string, which should\ncontain string format specifiers in it, which tells how the values provided\nin the second argument should be printed into the message.\n\nWhile the second argument is a struct literal that lists the values\nto be printed into the template message specified in the first argument.\nYou normally want to use an anonymous struct literal here, so that the\n`zig` compiler do the job of specifying the type of this particular\nanonymous struct for you.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello, world!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n### Struct declarations must be constant\n\nTypes in Zig must be `const` or `comptime` (we are going to talk more about comptime in @sec-comptime).\nWhat this means is that you cannot create a new data type, and mark it as variable with the `var` keyword.\nSo struct declarations are always constant. You cannot declare a new struct type using the `var` keyword.\nIt must be `const`.\n\nIn the `Vec3` example below, this declaration is allowed because I'm using the `const` keyword\nto declare this new data type.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n```\n:::\n\n\n\n\n\n\n### The `self` method argument {#sec-self-arg}\n\nIn every language that have OOP, when we declare a method of some class or struct, we\nusually declare this method as a function that has a `self` argument.\nThis `self` argument is the reference to the object itself from which the method\nis being called from.\n\nIt's not mandatory to use this `self` argument. But why would you not use this `self` argument?\nThere is no reason to not use it. Because the only way to get access to the data stored in the\ndata members of your struct is to access them through this `self` argument.\nIf you don't need to use the data in the data members of your struct inside your method, you very likely don't need\na method. You can just declare this logic as a simple function, outside of your\nstruct declaration.\n\n\nTake the `Vec3` struct below. Inside this `Vec3` struct we declared a method named `distance()`.\nThis method calculates the distance between two `Vec3` objects, by following the distance\nformula in euclidean space. Notice that this `distance()` method takes two `Vec3` objects\nas input, `self` and `other`.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n```\n:::\n\n\n\n\n\n\nThe `self` argument corresponds to the `Vec3` object from which this `distance()` method\nis being called from. While the `other` is a separate `Vec3` object that is given as input\nto this method. In the example below, the `self` argument corresponds to the object\n`v1`, because the `distance()` method is being called from the `v1` object,\nwhile the `other` argument corresponds to the object `v2`.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n```\n:::\n\n\n\n\n\n```\nDistance: 3.3970575502926055\n```\n\n\n\n### About the struct state\n\nSometimes you don't need to care about the state of your struct object. Sometimes, you just need\nto instantiate and use the objects, without altering their state. You can notice that when you have methods\ninside your struct declaration that might use the values that are present in the data members, but they\ndo not alter the values in these data members of the struct in anyway.\n\nThe `Vec3` struct that was presented in @sec-self-arg is an example of that.\nThis struct have a single method named `distance()`, and this method does use the values\npresent in all three data members of the struct (`x`, `y` and `z`). But at the same time,\nthis method does not change the values of these data members at any point.\n\nAs a result of that, when we create `Vec3` objects we usually create them as\nconstant objects, like the `v1` and `v2` objects presented in @sec-self-arg.\nWe can create them as variable objects with the `var` keyword,\nif we want to. But because the methods of this `Vec3` struct do not change\nthe state of the objects in any point, it's unnecessary to mark them\nas variable objects.\n\nBut why? Why am I talking about this here? It's because the `self` argument\nin the methods are affected depending on whether the\nmethods present in a struct change or don't change the state of the object itself.\nMore specifically, when you have a method in a struct that changes the state\nof the object (i.e., changes the value of a data member), the `self` argument\nin this method must be annotated in a different manner.\n\nAs I described in @sec-self-arg, the `self` argument in methods of\na struct is the argument that receives as input the object from which the method\nwas called from. We usually annotate this argument in the methods by writing `self`,\nfollowed by the colon character (`:`), and the data type of the struct to which\nthe method belongs to (e.g. `User`, `Vec3`, etc.).\n\nIf we take the `Vec3` struct that we defined in the previous section as an example,\nwe can see in the `distance()` method that this `self` argument is annotated as\n`self: Vec3`. Because the state of the `Vec3` object is never altered by this\nmethod.\n\nBut what if we do have a method that alters the state of the object, by altering the\nvalues of its data members, how should we annotate `self` in this instance? The answer is:\n\"we should annotate `self` as a pointer of `x`, instead of just `x`\".\nIn other words, you should annotate `self` as `self: *x`, instead of annotating it\nas `self: x`.\n\nIf we create a new method inside the `Vec3` object that, for example, expands the\nvector by multiplying its coordinates by a factor of two, then, we need to follow\nthis rule specified in the previous paragraph. The code example below demonstrates\nthis idea:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n```\n:::\n\n\n\n\n\nNotice in the code example above that we have added a new method\nto our `Vec3` struct named `twice()`. This method doubles the\ncoordinate values of our vector object. In the\ncase of the `twice()` method, we annotated the `self` argument as `*Vec3`,\nindicating that this argument receives a pointer (or a reference, if you prefer to call it this way)\nto a `Vec3` object as input.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n```\n:::\n\n\n\n\n\n```\nDoubled: 8.4\n```\n\n\n\nNow, if you change the `self` argument in this `twice()` method to `self: Vec3`, like in the\n`distance()` method, you will get the compiler error exposed below as result. Notice that this\nerror message is showing a line from the `twice()` method body,\nindicating that you cannot alter the value of the `x` data member.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n```\n:::\n\n\n\n\n\n```\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\n```\n\nThis error message indicates that the `x` data member belongs to a constant object,\nand, because of that, it cannot be changed. Ultimately, this error message\nis telling us that the `self` argument is constant.\n\nIf you take some time, and think hard about this error message, you will understand it.\nYou already have the tools to understand why we are getting this error message.\nWe have talked about it already in @sec-fun-pars.\nSo remember, every function argument is immutable in Zig, and `self`\nis no exception to this rule.\n\nIn this example, we marked the `v3` object as a variable object.\nBut this does not matter. Because it's not about the input object, it's about\nthe function argument.\n\nThe problem begins when we try to alter the value of `self` directly, which is a function argument,\nand, every function argument is immutable by default. You may ask yourself how can we overcome\nthis barrier, and once again, the solution was also discussed in @sec-fun-pars.\nWe overcome this barrier, by explicitly marking the `self` argument as a pointer.\n\n\n::: {.callout-note}\nIf a method of your `x` struct alters the state of the object, by\nchanging the value of any data member, then, remember to use `self: *x`,\ninstead of `self: x` in the function signature of this method.\n:::\n\n\nYou could also interpret the content discussed in this section as:\n\"if you need to alter the state of your `x` struct object in one of its methods,\nyou must explicitly pass the `x` struct object by reference to the `self` argument of this method\".\n\n\n\n## Type inference {#sec-type-inference}\n\nZig is a strongly typed language. But, there are some situations\nwhere you don't have to explicitly write the type of every single object in your source code,\nas you would expect from a traditional strongly typed language, such as C and C++.\n\nIn some situations, the `zig` compiler can use type inference to solve the data types for you, easing some of\nthe burden that you carry as a developer.\nThe most common way this happens is through function arguments that receive struct objects\nas input.\n\nIn general, type inference in Zig is done by using the dot character (`.`).\nEverytime you see a dot character written before a struct literal, or before an enum value, or something like that,\nyou know that this dot character is playing a special part in this place. More specifically, it's\ntelling the `zig` compiler something along the lines of: \"Hey! Can you infer the type of this\nvalue for me? Please!\". In other words, this dot character is playing a similar role as the `auto` keyword in C++.\n\nI gave you some examples of this in @sec-anonymous-struct-literals, where we used anonymous struct literals.\nAnonymous struct literals are, struct literals that use type inference to\ninfer the exact type of this particular struct literal.\nThis type inference is done by looking for some minimal hint of the correct data type to be used.\nYou could say that the `zig` compiler looks for any neighbouring type annotation that might tell it\nwhat the correct type would be.\n\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in @sec-switch).\nI also gave some other examples of type inference in @sec-switch, where we were inferring the data types of enum values listed inside\nof switch statements (e.g. `.DE`).\nBut as another example, take a look at this `fence()` function reproduced below,\nwhich comes from the [`atomic.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig)[^fence-fn]\nof the Zig Standard Library.\n\n[^fence-fn]: <https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig>.\n\nThere are a lot of things in this function that we haven't talked about yet, such as:\nwhat `comptime` means? `inline`? `extern`?\nLet's just ignore all of these things, and focus solely on the switch statement\nthat is inside this function.\n\nWe can see that this switch statement uses the `order` object as input. This `order`\nobject is one of the inputs of this `fence()` function, and we can see in the type annotation,\nthat this object is of type `AtomicOrder`. We can also see a bunch of values inside the\nswitch statements that begin with a dot character, such as `.release` and `.acquire`.\n\nBecause these weird values contain a dot character before them, we are asking the `zig`\ncompiler to infer the types of these values inside the switch statement. Then, the `zig`\ncompiler is looking into the current context where these values are being used, and trying\nto infer the types of these values.\n\nSince they are being used inside a switch statement, the `zig` compiler looks into the type\nof the input object given to the switch statement, which is the `order` object in this case.\nBecause this object have type `AtomicOrder`, the `zig` compiler infers that these values\nare data members from this type `AtomicOrder`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic => @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire => tsan.__tsan_acquire(addr),\n            .release => tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst => {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n```\n:::\n\n\n\n\n\nThis is how basic type inference is done in Zig. If we didn't use the dot character before\nthe values inside this switch statement, then, we would be forced to explicitly write\nthe data types of these values. For example, instead of writing `.release` we would have to\nwrite `AtomicOrder.release`. We would have to do this for every single value\nin this switch statement, and this is a lot of work. That is why type inference\nis commonly used on switch statements in Zig.\n\n\n\n## Type casting {#sec-type-cast}\n\nIn this section, I want to discuss type casting (or, type conversion) with you.\nWe use type casting when we have an object of type \"x\", and we want to convert\nit into an object of type \"y\", i.e., we want to change the data type of the object.\n\nMost languages have a formal way to perform type casting. In Rust for example, we normally\nuse the keyword `as`, and in C, we normally use the type casting syntax, e.g. `(int) x`.\nIn Zig, we use the `@as()` built-in function to cast an object of type \"x\", into\nan object of type \"y\".\n\nThis `@as()` function is the preferred way to perform type conversion (or type casting)\nin Zig. Because it's explicit, and, it also performs the casting only if it\nis unambiguous and safe. To use this function, you just provide the target data type\nin the first argument, and, the object that you want cast as the second argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file3c448aa9d5f.test_0...OKAll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\nThis is the general way to perform type casting in Zig. But remember, `@as()` works only when casting\nis unambiguous and safe. There are many situations where these assumptions do not hold. For example,\n\nwhen casting an integer value into a float value, or vice-versa, it's not clear to the compiler\nhow to perform this conversion safely.\n\nTherefore, we need to use specialized \"casting functions\" in such situations.\nFor example, if you want to cast an integer value into a float value, then, you\nshould use the `@floatFromInt()` function. In the inverse scenario, you should use\nthe `@intFromFloat()` function.\n\nIn these functions, you just provide the object that you want to\ncast as input. Then, the target data type of the \"type casting operation\" is determined by\nthe type annotation of the object where you are saving the results.\nIn the example below, we are casting the object `x` into a value of type `f32`,\nbecause the object `y`, which is where we are saving the results, is annotated\nas an object of type `f32`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file3c4427337b66.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\n\nAnother built-in function that is very useful when performing type casting operations is `@ptrCast()`.\nIn essence, we use the `@as()` built-in function when we want to explicit convert (or cast) a Zig value/object\nfrom a type \"x\" to a type \"y\", etc. However, pointers (we are going to discuss pointers\nin more depth in @sec-pointer) are a special type of object in Zig,\ni.e., they are treated differently from \"normal objects\".\n\nEverytime a pointer is involved in some \"type casting operation\" in Zig, the `@ptrCast()` function is used.\nThis function works similarly to `@floatFromInt()`.\nYou just provide the pointer object that you want to cast as input to this function, and the\ntarget data type is, once again, determined by the type annotation of the object where the results are being\nstored.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file3c4479f1f6f8.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n\n## Modules\n\nWe already talked about what modules are, and also, how to import other modules into\nyour current module via *import statements*. Every Zig module (i.e., a `.zig` file) that you write in your project\nis internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the\nZig Standard Library into our current module.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n```\n:::\n\n\n\n\n\nWhen we want to access the functions and objects from the standard library, we\nare basically accessing the data members of the struct stored in the `std`\nobject. That is why we use the same syntax that we use in normal structs, with the dot operator (`.`)\nto access the data members and methods of the struct.\n\nWhen this \"import statement\" gets executed, the result of this expression is a struct\nobject that contains the Zig Standard Library modules, global variables, functions, etc.\nAnd this struct object gets saved (or stored) inside the constant object named `std`.\n\n\nTake the [`thread_pool.zig` module from the project `zap`](https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig)[^thread]\nas an example. This module is written as if it was\na big struct. That is why we have a top-level and public `init()` method\nwritten in this module. The idea is that all top-level functions written in this\nmodule are methods from the struct, and all top-level objects and struct declarations\nare data members of this struct. The module is the struct itself.\n\n[^thread]: <https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig>\n\n\nSo you would import and use this module by doing something like this:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst ThreadPool = @import(\"thread_pool.zig\");\nconst num_cpus = std.Thread.getCpuCount()\n    catch @panic(\"failed to get cpu core count\");\nconst num_threads = std.math.cast(u16, num_cpus)\n    catch std.math.maxInt(u16);\nconst pool = ThreadPool.init(\n    .{ .max_threads = num_threads }\n);\n```\n:::\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Control flow, structs, modules and types\n\nWe have discussed a lot of Zig's syntax in the last chapter,\nespecially in @sec-root-file and @sec-main-file.\nBut we still need to discuss some other very important\nelements of the language. Elements that you will use constantly on your day-to-day\nroutine.\n\nWe begin this chapter by discussing the different keywords and structures\nin Zig related to control flow (e.g. loops and if statements).\nThen, we talk about structs and how they can be used to do some\nbasic Object-Oriented (OOP) patterns in Zig. We also talk about\ntype inference and type casting.\nFinally, we end this chapter by discussing modules, and how they relate\nto structs.\n\n\n\n## Control flow {#sec-zig-control-flow}\n\nSometimes, you need to make decisions in your program. Maybe you need to decide\nwhether or not to execute a specific piece of code. Or maybe,\nyou need to apply the same operation over a sequence of values. These kinds of tasks,\ninvolve using structures that are capable of changing the \"control flow\" of our program.\n\nIn computer science, the term \"control flow\" usually refers to the order in which expressions (or commands)\nare evaluated in a given language or program. But this term is also used to refer\nto structures that are capable of changing this \"evaluation order\" of the commands\nexecuted by a given language/program.\n\nThese structures are better known\nby a set of terms, such as: loops, if/else statements, switch statements, among others. So,\nloops and if/else statements are examples of structures that can change the \"control\nflow\" of our program. The keywords `continue` and `break` are also examples of symbols\nthat can change the order of evaluation, since they can move our program to the next iteration\nof a loop, or make the loop stop completely.\n\n\n### If/else statements\n\nAn if/else statement performs a \"conditional flow operation\".\nA conditional flow control (or choice control) allows you to execute\nor ignore a certain block of commands based on a logical condition.\nMany programmers and computer science professionals also use\nthe term \"branching\" in this case.\nIn essence, an if/else statement allow us to use the result of a logical test\nto decide whether or not to execute a given block of commands.\n\nIn Zig, we write if/else statements by using the keywords `if` and `else`.\nWe start with the `if` keyword followed by a logical test inside a pair\nof parentheses, followed by a pair of curly braces which contains the lines\nof code to be executed in case the logical test returns the value `true`.\n\nAfter that, you can optionally add an `else` statement. To do that, just add the `else`\nkeyword followed by a pair of curly braces, with the lines of code\nto executed in case the logical test defined at `if` returns `false`.\n\nIn the example below, we are testing if the object `x` contains a number\nthat is greater than 10. Judging by the output printed to the console,\nwe know that this logical test returned `false`. Because the output\nin the console is compatible with the line of code present in the\n`else` branch of the if/else statement.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x = 5;\nif (x > 10) {\n    try stdout.print(\n        \"x > 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x <= 10!\\n\", .{}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nx <= 10!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n### Switch statements {#sec-switch}\n\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust.\nAs you would expect, to write a switch statement in Zig we use the `switch` keyword.\nWe provide the value that we want to \"switch over\" inside a\npair of parentheses. Then, we list the possible combinations (or \"branches\")\ninside a pair of curly braces.\n\nLet's take a look at the code example below. You can see that\nI'm creating an enum type called `Role`. We talk more about enums in @sec-enum.\nBut in summary, this `Role` type is listing different types of roles in a fictitious\ncompany, like `SE` for Software Engineer, `DE` for Data Engineer, `PM` for Product Manager,\netc.\n\nNotice that we are using the value from the `role` object in the\nswitch statement, to discover which exact area we need to store in the `area` variable object.\nAlso notice that we are using type inference inside the switch statement, with the dot character,\nas we are going to describe in @sec-type-inference.\nThis makes the `zig` compiler infer the correct data type of the values (`PM`, `SE`, etc.) for us.\n\nAlso notice that, we are grouping multiple values in the same branch of the switch statement.\nWe just separate each possible value with a comma. For example, if `role` contains either `DE` or `DA`,\nthe `area` variable would contain the value `\"Data & Analytics\"`, instead of `\"Platform\"` or `\"Sales\"`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO => {\n            area = \"Platform\";\n        },\n        .DE, .DA => {\n            area = \"Data & Analytics\";\n        },\n        .KS => {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nPlatform\n```\n\n\n:::\n:::\n\n\n\n\n\n\n#### Switch statements must exhaust all possibilities\n\nOne very important aspect about switch statements in Zig\nis that they must exhaust all existing possibilities.\nIn other words, all possible values that could be found inside the `role`\nobject must be explicitly handled in this switch statement.\n\nSince the `role` object has type `Role`, the only possible values to\nbe found inside this object are `PM`, `SE`, `DPE`, `PO`, `DE`, `DA` and `KS`.\nThere are no other possible values to be stored in this `role` object.\nThus, the switch statements must have a combination (branch) for each one of these values.\nThis is what \"exhaust all existing possibilities\" means. The switch statement covers\nevery possible case.\n\nTherefore, you cannot write a switch statement in Zig, and leave an edge case\nwith no explicit action to be taken.\nThis is a similar behaviour to switch statements in Rust, which also have to\nhandle all possible cases.\n\n\n\n#### The else branch\n\nTake a look at the `dump_hex_fallible()` function below as an example. This function\ncomes from the Zig Standard Library. More precisely, from the\n[`debug.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/debug.zig)[^debug-mod].\nThere are multiple lines in this function, but I omitted them to focus solely on the\nswitch statement found in this function. Notice that this switch statement has four\npossible cases (i.e., four explicit branches). Also, notice that we used an `else` branch\nin this case.\n\nAn `else` branch in a switch statement works as the \"default branch\".\nWhenever you have multiple cases in your switch statement where\nyou want to apply the exact same action, you can use an `else` branch to do that.\n\n[^debug-mod]: <https://github.com/ziglang/zig/blob/master/lib/std/debug.zig>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' => try writer.writeAll(\"␊\"),\n        '\\r' => try writer.writeAll(\"␍\"),\n        '\\t' => try writer.writeAll(\"␉\"),\n        else => try writer.writeByte('.'),\n    }\n}\n```\n:::\n\n\n\n\n\nMany programmers would also use an `else` branch to handle a \"not supported\" case.\nThat is, a case that cannot be properly handled by your code, or, just a case that\nshould not be \"fixed\". Therefore, you can use an `else` branch to panic (or raise an error)\nin your program to stop the current execution.\n\nTake the code example below. We can see that, we are handling the cases\nfor the `level` object being either 1, 2, or 3. All other possible cases are not supported by default,\nand, as consequence, we raise a runtime error in such cases through the `@panic()` built-in function.\n\nAlso notice that, we are assigning the result of the switch statement to a new object called `category`.\nThis is another thing that you can do with switch statements in Zig. If a branch\noutputs a value as result, you can store the result value of the switch statement into\na new object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 => \"beginner\",\n    3 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n:::\n\n\n\n\n\n```\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n```\n\n\n\n#### Using ranges in switch\n\nFurthermore, you can also use ranges of values in switch statements.\nThat is, you can create a branch in your switch statement that is used\nwhenever the input value is within the specified range. These \"range expressions\"\nare created with the operator `...`. It's important\nto emphasize that the ranges created by this operator are\ninclusive on both ends.\n\nFor example, I could easily change the previous code example to support all\nlevels between 0 and 100. Like this:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 => \"beginner\",\n    26...75 => \"intermediary\",\n    76...100 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nbeginner\n```\n\n\n:::\n:::\n\n\n\n\n\nThis is neat, and it works with character ranges too. That is, I could\nsimply write `'a'...'z'`, to match any character value that is a\nlowercase letter, and it would work fine.\n\n\n#### Labeled switch statements\n\nIn @sec-blocks we have talked about labeling blocks, and also, about using these labels\nto return a value from the block. Well, from version 0.14.0 and onwards of the `zig` compiler,\nyou can also apply labels over switch statements, which makes it possible to almost implement a\n\"C `goto`\" like pattern.\n\nFor example, if you give the label `xsw` to a switch statement, you can use this\nlabel in conjunction with the `continue` keyword to go back to the beginning of the switch\nstatement. In the example below, the execution goes back to the beginning of the\nswitch statement two times, before ending at the `3` branch.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nxsw: switch (@as(u8, 1)) {\n    1 => {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 => continue :xsw 3,\n    3 => return,\n    4 => {},\n    else => {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n```\n:::\n\n\n\n\n\n\n### The `defer` keyword {#sec-defer}\n\nWith the `defer` keyword you can register an expression to be executed when you exit the current scope.\nTherefore, this keyword has a similar functionality as the `on.exit()` function from R.\nTake the `foo()` function below as an example. When we execute this `foo()` function, the expression\nthat prints the message \"Exiting function ...\" is getting executed only when the function exits\nits scope.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n```\n:::\n\n\n\n\n\n```\nAdding some numbers ...\nMultiplying ...\nExiting function ...\n```\n\nTherefore, we can use `defer` to declare an expression that is going to be executed\nwhen your code exits the current scope. Some programmers like to interpret the phrase \"exit of the current scope\"\nas \"the end of the current scope\". But this interpretation might not be entirely correct, depending\non what you consider as \"the end of the current scope\".\n\nI mean, what do you consider as **the end** of the current scope? Is it the closing curly bracket (`}`) of the scope?\nIs it when the last expression in the function gets executed? Is it when the function returns to the previous scope?\nEtc. For example, it would not be correct to interpret the \"exit of the current scope\" as the closing\ncurly bracket of the scope. Because the function might exit from an earlier position than this\nclosing curly bracket (e.g. an error value was generated at a previous line inside the function;\nthe function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\n\nNow, if you remember of what we have discussed in @sec-blocks, there are multiple structures in the language\nthat create their own separate scopes. For/while loops, if/else statements,\nfunctions, normal blocks, etc. This also affects the interpretation of `defer`.\nFor example, if you use `defer` inside a for loop, then, the given expression\nwill be executed everytime this specific for loop exits its own scope.\n\nBefore we continue, it's worth emphasizing that the `defer` keyword is an \"unconditional defer\".\nWhich means that the given expression will be executed no matter how the code exits\nthe current scope. For example, your code might exit the current scope because of an error value\nbeing generated, or, because of a return statement, or, a break statement, etc.\n\n\n\n### The `errdefer` keyword {#sec-errdefer1}\n\nOn the previous section, we have discussed the `defer` keyword, which you can use to\nregister an expression to be executed at the exit of the current scope.\nBut this keyword has a brother, which is the `errdefer` keyword. While `defer`\nis an \"unconditional defer\", the `errdefer` keyword is a \"conditional defer\".\nWhich means that the given expression is executed only when you exit the current\nscope on a very specific circumstance.\n\nIn more details, the expression given to `errdefer` is executed only when an error occurs in the current scope.\nTherefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope\nin a normal situation, without errors, the expression given to `errdefer` is not executed.\n\nThis makes the `errdefer` keyword one of the many tools available in Zig for error handling.\nIn this section, we are more concerned with the control flow aspects around `errdefer`.\nBut we are going to discuss `errdefer` later as a error handling tool in @sec-errdefer2.\n\nThe code example below demonstrates three things:\n\n- that `defer` is an \"unconditional defer\", because the given expression gets executed regardless of how the function `foo()` exits its own scope.\n- that `errdefer` is executed because the function `foo()` returned an error value.\n- that `defer` and `errdefer` expressions are executed in a LIFO (*last in, first out*) order.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n```\n:::\n\n\n\n\n\n```\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\nWhen I say that \"defer expressions\" are executed in a LIFO order, what I want to say is that\nthe last `defer` or `errdefer` expressions in the code are the first ones to be executed.\nYou could also interpret this as: \"defer expressions\" are executed from bottom to top, or,\nfrom last to first.\n\nTherefore, if I change the order of the `defer` and `errdefer` expressions, you will notice that\nthe value of `i` that gets printed to the console changes to 1. This doesn't mean that the\n`defer` expression was not executed in this case. This actually means that the `defer` expression\nwas executed only after the `errdefer` expression. The code example below demonstrates this:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n```\n:::\n\n\n\n\n\n```\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\n\n\n### For loops\n\nA loop allows you to execute the same lines of code multiple times,\nthus, creating a \"repetition space\" in the execution flow of your program.\nLoops are particularly useful when we want to replicate the same function\n(or the same set of commands) over different inputs.\n\nThere are different types of loops available in Zig. But the most\nessential of them all is probably the *for loop*. A for loop is\nused to apply the same piece of code over the elements of a slice, or, an array.\n\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from\nother languages. You start with the `for` keyword, then, you\nlist the items that you want to iterate\nover inside a pair of parentheses. Then, inside of a pair of pipes (`|`)\nyou should declare an identifier that will serve as your iterator, or,\nthe \"repetition index of the loop\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (items) |value| {\n    // code to execute\n}\n```\n:::\n\n\n\n\n\nTherefore, instead of using a `(value in items)` syntax,\nin Zig, for loops use the syntax `(items) |value|`. In the example\nbelow, you can see that we are looping through the items\nof the array stored at the object `name`, and printing to the\nconsole the decimal representation of each character in this array.\n\nIf we wanted, we could also iterate through a slice (or a portion) of\nthe array, instead of iterating through the entire array stored in the `name` object.\nJust use a range selector to select the section you want. For example,\nI could provide the expression `name[0..3]` to the for loop, to iterate\njust through the first 3 elements in the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n80 | 101 | 100 | 114 | 111 | \n```\n\n\n:::\n:::\n\n\n\n\n\nIn the above example we are using the value itself of each\nelement in the array as our iterator. But there are many situations where\nwe need to use an index instead of the actual values of the items.\n\nYou can do that by providing a second set of items to iterate over.\nMore precisely, you provide the range selector `0..` to the for loop. So,\nyes, you can use two different iterators at the same time in a for\nloop in Zig.\n\nBut remember from @sec-assignments that, every object\nyou create in Zig must be used in some way. So if you declare two iterators\nin your for loop, you must use both iterators inside the for loop body.\nBut if you want to use just the index iterator, and not use the \"value iterator\",\nthen, you can discard the value iterator by maching the\nvalue items to the underscore character, like in the example below:\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n:::\n\n\n\n\n\n```\n0 | 1 | 2 | 3 | 4 |\n```\n\n\n### While loops\n\nA while loop is created from the `while` keyword. A `for` loop\niterates through the items of an array, but a `while` loop\nwill loop continuously, and infinitely, until a logical test\n(specified by you) becomes false.\n\nYou start with the `while` keyword, then, you define a logical\nexpression inside a pair of parentheses, and the body of the\nloop is provided inside a pair of curly braces, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\n\nYou can also specify the increment expression to be used at the beginning of a while loop.\nTo do that, we write the increment expression inside a pair of parentheses after a colon character (`:`).\nThe code example below demonstrates this other pattern.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\n\n### Using `break` and `continue`\n\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using\nthe keywords `break` and `continue`, respectively. The `while` loop presented in the next code example is,\nat first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to `true`.\nBut what makes this `while` loop stop when the `i` object reaches the count\n10? It's the `break` keyword!\n\nInside the while loop, we have an if statement that is constantly checking if the `i` variable\nis equal to 10. Since we are incrementing the value of `i` at each iteration of the\nwhile loop, this `i` object will eventually be equal to 10, and when it is, the if statement\nwill execute the `break` expression, and, as a result, the execution of the while loop is stopped.\n\nNotice the use of the `expect()` function from the Zig Standard Library after the while loop.\nThis `expect()` function is an \"assert\" type of function.\nThis function checks if the logical test provided is equal to true. If so, the function do nothing.\nOtherwise (i.e., the logical test is equal to false), the function raises an assertion error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nEverything worked!\n```\n\n\n:::\n:::\n\n\n\n\n\nSince this code example was executed successfully by the `zig` compiler,\nwithout raising any errors, we known that, after the execution of the while loop,\nthe `i` object is equal to 10. Because if it wasn't equal to 10, an error would have\nbeen raised by `expect()`.\n\nNow, in the next example, we have a use case for\nthe `continue` keyword. The if statement is constantly\nchecking if the current index is a multiple of 2. If\nit is, we jump to the next iteration of the loop.\nOtherwise, the loop just prints the current index to the console.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 3 | 5 | \n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n## Function parameters are immutable {#sec-fun-pars}\n\nWe have already discussed a lot of the syntax behind function declarations in @sec-root-file and @sec-main-file.\nBut I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig.\nIn summary, function parameters are immutable in Zig.\n\nTake the code example below, where we declare a simple function that just tries to add\nsome amount to the input integer, and returns the result back. If you look closely\nat the body of this `add2()` function, you will notice that we try\nto save the result back into the `x` function argument.\n\nIn other words, this function not only uses the value that it received through the function argument\n`x`, but it also tries to change the value of this function argument, by assigning the addition result\ninto `x`. However, function arguments in Zig are immutable. You cannot change their values, or, you\ncannot assign values to them inside the body's function.\n\nThis is the reason why, the code example below does not compile successfully. If you try to compile\nthis code example, you will get a compile error message about \"trying to change the value of a\nimmutable (i.e., constant) object\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n\n\n\n```\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n```\n\n\n### A free optimization\n\nIf a function argument receives as input an object whose data type is\nany of the primitive types that we have listed in @sec-primitive-data-types,\nthis object is always passed by value to the function. In other words, this object\nis copied into the function stack frame.\n\nHowever, if the input object have a more complex data type, for example, it might\nbe a struct instance, or an array, or an union value, etc., in cases like that, the `zig` compiler\nwill take the liberty of deciding for you which strategy is best. Thus, the `zig` compiler will\npass your object to the function either by value, or by reference. The compiler will always\nchoose the strategy that is faster for you.\nThis optimization that you get for free is possible only because function arguments are\nimmutable in Zig.\n\n\n### How to overcome this barrier\n\nThere are some situations where you might need to change the value of your function argument\ndirectly inside the function's body. This happens more often when we are passing\nC structs as inputs to Zig functions.\n\nIn a situation like this, you can overcome this barrier by using a pointer. In other words,\ninstead of passing a value as input to the argument, you can pass a \"pointer to value\" instead.\nYou can change the value that the pointer points to, by dereferencing it.\n\nTherefore, if we take our previous `add2()` example, we can change the value of the\nfunction argument `x` inside the function's body by marking the `x` argument as a\n\"pointer to a `u32` value\" (i.e., `*u32` data type), instead of a `u32` value.\nBy making it a pointer, we can finally alter the value of this function argument directly inside\nthe body of the `add2()` function. You can see that the code example below compiles successfully.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n```\n:::\n\n\n\n\n\n```\nResult: 6\n```\n\n\nEven in this code example above, the `x` argument is still immutable. Which means that the pointer itself is immutable.\nTherefore, you cannot change the memory address that it points to. However, you can dereference the pointer\nto access the value that it points to, and also, to change this value, if you need to.\n\n\n\n\n\n## Structs and OOP {#sec-structs-and-oop}\n\nZig is a language more closely related to C (which is a procedural language),\nthan it is to C++ or Java (which are object-oriented languages). Because of that, you do not\nhave advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or\nclass inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\n\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C.\nYou give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can\nalso register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object\nthat you create with this new type, will always have these methods available and associated with them.\n\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which\nis used to construct (or, to instantiate) every object of this particular class, and we also have\na destructor method (or a destructor function), which is the function responsible for destroying\nevery object of this class.\n\nIn Zig, we normally declare the constructor and the destructor methods\nof our structs, by declaring an `init()` and a `deinit()` methods inside the struct.\nThis is just a naming convention that you will find across the entire Zig Standard Library.\nSo, in Zig, the `init()` method of a struct is normally the constructor method of the class represented by this struct.\nWhile the `deinit()` method is the method used for destroying an existing instance of that struct.\n\nThe `init()` and `deinit()` methods are both used extensively in Zig code, and you will see both of\nthem being used when we talk about allocators in @sec-allocators.\nBut, as another example, let's build a simple `User` struct to represent a user of some sort of system.\n\nIf you look at the `User` struct below, you can see the `struct` keyword.\nNotice the data members of this struct: `id`, `name` and `email`. Every data member has its\ntype explicitly annotated, with the colon character (`:`) syntax that we described earlier in @sec-root-file.\nBut also notice that every line in the struct body that describes a data member, ends with a comma character (`,`).\nSo every time you declare a data member in your Zig code, always end the line with a comma character, instead\nof ending it with the traditional semicolon character (`;`).\n\nNext, we have registered an `init()` function as a method\nof this `User` struct. This `init()` method is the constructor method that we will use to instantiate\nevery new `User` object. That is why this `init()` function returns a new `User` object as result.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    fn init(id: u64,\n            name: []const u8,\n            email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\npedro\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n### The `pub` keyword\n\nThe `pub` keyword plays an important role in struct declarations, and OOP in Zig.\nIn essence, this keyword is short for \"public\", and it makes an item/component available outside of the\nmodule where this item/component is declared. In other words, if I don't apply the `pub` keyword on\nsomething, it means that this \"something\" is available to be called/used only from within the module\nwhere this \"something\" is declared.\n\nTo demonstrate the effect of this keyword let's focus again on the `User` struct that we have\ndeclared on the previous section. For our example here, let's suppose that this `User` struct is declared inside\na Zig module named `user.zig`. If I don't use the `pub` keyword on the `User` struct, it means that I can create\nan `User` object, and call it's methods (`print_name()` and `init()`) only from within the module where the `User`\nstruct is declared, which in this case is the `user.zig` module.\n\nThis is why the previous code example works fine. Because we declare and also use the `User` struct\ninside the same module. But problems start to arise when we try to import and call/use this struct\nfrom another module. For example, if I create a new module called `register.zig`, and import the `user.zig`\nmodule into it, and try to annotate any variable with the `User` type, I get an error from the compiler.\n\n```zig\n// register.zig\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = undefined;\n    _ = u;\n}\n```\n\n```\nregister.zig:3:18: error: 'User' is not marked 'pub'\n    const u: user.User = undefined;\n             ~~~~^~~~~\nuser.zig:3:1: note: declared here\nconst User = struct {\n^~~~~\n```\n\nTherefore, if you want to use something outside of the module where this \"something\" is declared,\nyou have to mark it with the `pub` keyword. This \"something\" can be a module,\na struct, a function, an object, etc.\n\nFor our example here, if we go back to the `user.zig` module, and add the `pub` keyword\nto the `User` struct declaration, then, I can successfully compile the `register.zig` module.\n\n```zig\n// user.zig\n// Added the `pub` keyword to `User`\npub const User = struct {\n// ...\n```\n\n```zig\n// register.zig\n// This works fine now!\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = undefined;\n    _ = u;\n}\n```\n\n\nNow, what do you think it will happen if I try to actually call from `register.zig` any of the methods\nof the `User` struct? For example, if I try to call the `init()` method? The answer is: I get a similar error message,\nwarning me that the `init()` method is not marked as `pub`, as you can see below:\n\n```zig\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = user.User.init(\n        1, \"pedro\", \"email@gmail.com\"\n    );\n    _ = u;\n}\n```\n\n```\nregister.zig:3:35: error: 'init' is not marked 'pub'\n    const u: user.User = user.User.init(\n                         ~~~~~~~~~^~~~~\nuser.zig:8:5: note: declared here\n    fn init(id: u64,\n    ^~~~~~~\n```\n\nThus, just because we have applied the `pub` keyword on the struct declaration,\nthis does not make the methods of that struct public as well. If we want to use\nany method from a struct (such as the `init()` method) outside of the module\nwhere this struct is declared, we have to mark this method with the `pub` keyword\nas well.\n\nGoing back to the `user.zig` module, and marking both the `init()` and `print_name()`\nmethods with the `pub` keyword, makes them both available to the outside world, and,\nas consequence, makes the previous code example work.\n\n\n```zig\n// user.zig\n// Added the `pub` keyword to `User.init`\n    pub fn init(\n// ...\n// Added the `pub` keyword to `User.print_name`\n    pub fn print_name(self: User) !void {\n// ...\n```\n\n```zig\n// register.zig\n// This works fine now!\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = user.User.init(\n        1, \"pedro\", \"email@gmail.com\"\n    );\n    _ = u;\n}\n```\n\n\n### Anonymous struct literals {#sec-anonymous-struct-literals}\n\nYou can declare a struct object as a literal value. When we do that, we normally specify the\ndata type of this struct literal by writing its data type just before the opening curly brace.\nFor example, I could write a struct literal value of the type `User` that we have defined\nin the previous section like this:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n```\n:::\n\n\n\n\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a\nstruct literal, but not specify explicitly the type of this particular struct.\nAn anonymous struct is written by using the syntax `.{}`. So, we essentially\nreplaced the explicit type of the struct literal with a dot character (`.`).\n\nAs we described in @sec-type-inference, when you put a dot before a struct literal,\nthe type of this struct literal is automatically inferred by the `zig` compiler.\nIn essence, the `zig` compiler will look for some hint of what is the type of that struct.\nThis hint can be the type annotation of a function argument,\nor the return type annotation of the function that you are using, or the type annotation\nof an existing object.\nIf the compiler does find such type annotation, it will use this\ntype in your literal struct.\n\nAnonymous structs are very commonly used as inputs to function arguments in Zig.\nOne example that you have seen already constantly, is the `print()`\nfunction from the `stdout` object.\nThis function takes two arguments.\nThe first argument, is a template string, which should\ncontain string format specifiers in it, which tells how the values provided\nin the second argument should be printed into the message.\n\nWhile the second argument is a struct literal that lists the values\nto be printed into the template message specified in the first argument.\nYou normally want to use an anonymous struct literal here, so that the\n`zig` compiler do the job of specifying the type of this particular\nanonymous struct for you.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello, world!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n### Struct declarations must be constant\n\nTypes in Zig must be `const` or `comptime` (we are going to talk more about comptime in @sec-comptime).\nWhat this means is that you cannot create a new data type, and mark it as variable with the `var` keyword.\nSo struct declarations are always constant. You cannot declare a new struct type using the `var` keyword.\nIt must be `const`.\n\nIn the `Vec3` example below, this declaration is allowed because I'm using the `const` keyword\nto declare this new data type.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n```\n:::\n\n\n\n\n\n\n### The `self` method argument {#sec-self-arg}\n\nIn every language that have OOP, when we declare a method of some class or struct, we\nusually declare this method as a function that has a `self` argument.\nThis `self` argument is the reference to the object itself from which the method\nis being called from.\n\nIt's not mandatory to use this `self` argument. But why would you not use this `self` argument?\nThere is no reason to not use it. Because the only way to get access to the data stored in the\ndata members of your struct is to access them through this `self` argument.\nIf you don't need to use the data in the data members of your struct inside your method, you very likely don't need\na method. You can just declare this logic as a simple function, outside of your\nstruct declaration.\n\n\nTake the `Vec3` struct below. Inside this `Vec3` struct we declared a method named `distance()`.\nThis method calculates the distance between two `Vec3` objects, by following the distance\nformula in euclidean space. Notice that this `distance()` method takes two `Vec3` objects\nas input, `self` and `other`.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n```\n:::\n\n\n\n\n\n\nThe `self` argument corresponds to the `Vec3` object from which this `distance()` method\nis being called from. While the `other` is a separate `Vec3` object that is given as input\nto this method. In the example below, the `self` argument corresponds to the object\n`v1`, because the `distance()` method is being called from the `v1` object,\nwhile the `other` argument corresponds to the object `v2`.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n```\n:::\n\n\n\n\n\n```\nDistance: 3.3970575502926055\n```\n\n\n\n### About the struct state\n\nSometimes you don't need to care about the state of your struct object. Sometimes, you just need\nto instantiate and use the objects, without altering their state. You can notice that when you have methods\ninside your struct declaration that might use the values that are present in the data members, but they\ndo not alter the values in these data members of the struct in anyway.\n\nThe `Vec3` struct that was presented in @sec-self-arg is an example of that.\nThis struct have a single method named `distance()`, and this method does use the values\npresent in all three data members of the struct (`x`, `y` and `z`). But at the same time,\nthis method does not change the values of these data members at any point.\n\nAs a result of that, when we create `Vec3` objects we usually create them as\nconstant objects, like the `v1` and `v2` objects presented in @sec-self-arg.\nWe can create them as variable objects with the `var` keyword,\nif we want to. But because the methods of this `Vec3` struct do not change\nthe state of the objects in any point, it's unnecessary to mark them\nas variable objects.\n\nBut why? Why am I talking about this here? It's because the `self` argument\nin the methods are affected depending on whether the\nmethods present in a struct change or don't change the state of the object itself.\nMore specifically, when you have a method in a struct that changes the state\nof the object (i.e., changes the value of a data member), the `self` argument\nin this method must be annotated in a different manner.\n\nAs I described in @sec-self-arg, the `self` argument in methods of\na struct is the argument that receives as input the object from which the method\nwas called from. We usually annotate this argument in the methods by writing `self`,\nfollowed by the colon character (`:`), and the data type of the struct to which\nthe method belongs to (e.g. `User`, `Vec3`, etc.).\n\nIf we take the `Vec3` struct that we defined in the previous section as an example,\nwe can see in the `distance()` method that this `self` argument is annotated as\n`self: Vec3`. Because the state of the `Vec3` object is never altered by this\nmethod.\n\nBut what if we do have a method that alters the state of the object, by altering the\nvalues of its data members, how should we annotate `self` in this instance? The answer is:\n\"we should annotate `self` as a pointer of `x`, instead of just `x`\".\nIn other words, you should annotate `self` as `self: *x`, instead of annotating it\nas `self: x`.\n\nIf we create a new method inside the `Vec3` object that, for example, expands the\nvector by multiplying its coordinates by a factor of two, then, we need to follow\nthis rule specified in the previous paragraph. The code example below demonstrates\nthis idea:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n```\n:::\n\n\n\n\n\nNotice in the code example above that we have added a new method\nto our `Vec3` struct named `twice()`. This method doubles the\ncoordinate values of our vector object. In the\ncase of the `twice()` method, we annotated the `self` argument as `*Vec3`,\nindicating that this argument receives a pointer (or a reference, if you prefer to call it this way)\nto a `Vec3` object as input.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n```\n:::\n\n\n\n\n\n```\nDoubled: 8.4\n```\n\n\n\nNow, if you change the `self` argument in this `twice()` method to `self: Vec3`, like in the\n`distance()` method, you will get the compiler error exposed below as result. Notice that this\nerror message is showing a line from the `twice()` method body,\nindicating that you cannot alter the value of the `x` data member.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n```\n:::\n\n\n\n\n\n```\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\n```\n\nThis error message indicates that the `x` data member belongs to a constant object,\nand, because of that, it cannot be changed. Ultimately, this error message\nis telling us that the `self` argument is constant.\n\nIf you take some time, and think hard about this error message, you will understand it.\nYou already have the tools to understand why we are getting this error message.\nWe have talked about it already in @sec-fun-pars.\nSo remember, every function argument is immutable in Zig, and `self`\nis no exception to this rule.\n\nIn this example, we marked the `v3` object as a variable object.\nBut this does not matter. Because it's not about the input object, it's about\nthe function argument.\n\nThe problem begins when we try to alter the value of `self` directly, which is a function argument,\nand, every function argument is immutable by default. You may ask yourself how can we overcome\nthis barrier, and once again, the solution was also discussed in @sec-fun-pars.\nWe overcome this barrier, by explicitly marking the `self` argument as a pointer.\n\n\n::: {.callout-note}\nIf a method of your `x` struct alters the state of the object, by\nchanging the value of any data member, then, remember to use `self: *x`,\ninstead of `self: x` in the function signature of this method.\n:::\n\n\nYou could also interpret the content discussed in this section as:\n\"if you need to alter the state of your `x` struct object in one of its methods,\nyou must explicitly pass the `x` struct object by reference to the `self` argument of this method\".\n\n\n\n## Type inference {#sec-type-inference}\n\nZig is a strongly typed language. But, there are some situations\nwhere you don't have to explicitly write the type of every single object in your source code,\nas you would expect from a traditional strongly typed language, such as C and C++.\n\nIn some situations, the `zig` compiler can use type inference to solve the data types for you, easing some of\nthe burden that you carry as a developer.\nThe most common way this happens is through function arguments that receive struct objects\nas input.\n\nIn general, type inference in Zig is done by using the dot character (`.`).\nEverytime you see a dot character written before a struct literal, or before an enum value, or something like that,\nyou know that this dot character is playing a special part in this place. More specifically, it's\ntelling the `zig` compiler something along the lines of: \"Hey! Can you infer the type of this\nvalue for me? Please!\". In other words, this dot character is playing a similar role as the `auto` keyword in C++.\n\nI gave you some examples of this in @sec-anonymous-struct-literals, where we used anonymous struct literals.\nAnonymous struct literals are, struct literals that use type inference to\ninfer the exact type of this particular struct literal.\nThis type inference is done by looking for some minimal hint of the correct data type to be used.\nYou could say that the `zig` compiler looks for any neighbouring type annotation that might tell it\nwhat the correct type would be.\n\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in @sec-switch).\nI also gave some other examples of type inference in @sec-switch, where we were inferring the data types of enum values listed inside\nof switch statements (e.g. `.DE`).\nBut as another example, take a look at this `fence()` function reproduced below,\nwhich comes from the [`atomic.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig)[^fence-fn]\nof the Zig Standard Library.\n\n[^fence-fn]: <https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig>.\n\nThere are a lot of things in this function that we haven't talked about yet, such as:\nwhat `comptime` means? `inline`? `extern`?\nLet's just ignore all of these things, and focus solely on the switch statement\nthat is inside this function.\n\nWe can see that this switch statement uses the `order` object as input. This `order`\nobject is one of the inputs of this `fence()` function, and we can see in the type annotation,\nthat this object is of type `AtomicOrder`. We can also see a bunch of values inside the\nswitch statements that begin with a dot character, such as `.release` and `.acquire`.\n\nBecause these weird values contain a dot character before them, we are asking the `zig`\ncompiler to infer the types of these values inside the switch statement. Then, the `zig`\ncompiler is looking into the current context where these values are being used, and trying\nto infer the types of these values.\n\nSince they are being used inside a switch statement, the `zig` compiler looks into the type\nof the input object given to the switch statement, which is the `order` object in this case.\nBecause this object have type `AtomicOrder`, the `zig` compiler infers that these values\nare data members from this type `AtomicOrder`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic => @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire => tsan.__tsan_acquire(addr),\n            .release => tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst => {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n```\n:::\n\n\n\n\n\nThis is how basic type inference is done in Zig. If we didn't use the dot character before\nthe values inside this switch statement, then, we would be forced to explicitly write\nthe data types of these values. For example, instead of writing `.release` we would have to\nwrite `AtomicOrder.release`. We would have to do this for every single value\nin this switch statement, and this is a lot of work. That is why type inference\nis commonly used on switch statements in Zig.\n\n\n\n## Type casting {#sec-type-cast}\n\nIn this section, I want to discuss type casting (or, type conversion) with you.\nWe use type casting when we have an object of type \"x\", and we want to convert\nit into an object of type \"y\", i.e., we want to change the data type of the object.\n\nMost languages have a formal way to perform type casting. In Rust for example, we normally\nuse the keyword `as`, and in C, we normally use the type casting syntax, e.g. `(int) x`.\nIn Zig, we use the `@as()` built-in function to cast an object of type \"x\", into\nan object of type \"y\".\n\nThis `@as()` function is the preferred way to perform type conversion (or type casting)\nin Zig. Because it's explicit, and, it also performs the casting only if it\nis unambiguous and safe. To use this function, you just provide the target data type\nin the first argument, and, the object that you want cast as the second argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file3fc93b4ea641.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\n\nThis is the general way to perform type casting in Zig. But remember, `@as()` works only when casting\nis unambiguous and safe. There are many situations where these assumptions do not hold. For example,\n\nwhen casting an integer value into a float value, or vice-versa, it's not clear to the compiler\nhow to perform this conversion safely.\n\nTherefore, we need to use specialized \"casting functions\" in such situations.\nFor example, if you want to cast an integer value into a float value, then, you\nshould use the `@floatFromInt()` function. In the inverse scenario, you should use\nthe `@intFromFloat()` function.\n\nIn these functions, you just provide the object that you want to\ncast as input. Then, the target data type of the \"type casting operation\" is determined by\nthe type annotation of the object where you are saving the results.\nIn the example below, we are casting the object `x` into a value of type `f32`,\nbecause the object `y`, which is where we are saving the results, is annotated\nas an object of type `f32`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file3fc91795a712.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\n\nAnother built-in function that is very useful when performing type casting operations is `@ptrCast()`.\nIn essence, we use the `@as()` built-in function when we want to explicit convert (or cast) a Zig value/object\nfrom a type \"x\" to a type \"y\", etc. However, pointers (we are going to discuss pointers\nin more depth in @sec-pointer) are a special type of object in Zig,\ni.e., they are treated differently from \"normal objects\".\n\nEverytime a pointer is involved in some \"type casting operation\" in Zig, the `@ptrCast()` function is used.\nThis function works similarly to `@floatFromInt()`.\nYou just provide the pointer object that you want to cast as input to this function, and the\ntarget data type is, once again, determined by the type annotation of the object where the results are being\nstored.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file3fc945f8b4b0.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n\n## Modules\n\nWe already talked about what modules are, and also, how to import other modules into\nyour current module via *import statements*. Every Zig module (i.e., a `.zig` file) that you write in your project\nis internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the\nZig Standard Library into our current module.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n```\n:::\n\n\n\n\n\nWhen we want to access the functions and objects from the standard library, we\nare basically accessing the data members of the struct stored in the `std`\nobject. That is why we use the same syntax that we use in normal structs, with the dot operator (`.`)\nto access the data members and methods of the struct.\n\nWhen this \"import statement\" gets executed, the result of this expression is a struct\nobject that contains the Zig Standard Library modules, global variables, functions, etc.\nAnd this struct object gets saved (or stored) inside the constant object named `std`.\n\n\nTake the [`thread_pool.zig` module from the project `zap`](https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig)[^thread]\nas an example. This module is written as if it was\na big struct. That is why we have a top-level and public `init()` method\nwritten in this module. The idea is that all top-level functions written in this\nmodule are methods from the struct, and all top-level objects and struct declarations\nare data members of this struct. The module is the struct itself.\n\n[^thread]: <https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig>\n\n\nSo you would import and use this module by doing something like this:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst ThreadPool = @import(\"thread_pool.zig\");\nconst num_cpus = std.Thread.getCpuCount()\n    catch @panic(\"failed to get cpu core count\");\nconst num_threads = std.math.cast(u16, num_cpus)\n    catch std.math.maxInt(u16);\nconst pool = ThreadPool.init(\n    .{ .max_threads = num_threads }\n);\n```\n:::\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
diff --git a/docs/Chapters/03-structs.html b/docs/Chapters/03-structs.html
index 5c0fd596..bc77ada2 100644
--- a/docs/Chapters/03-structs.html
+++ b/docs/Chapters/03-structs.html
@@ -704,8 +704,8 @@ <h2 data-number="2.3" class="anchored" data-anchor-id="sec-structs-and-oop"><spa
 <span id="cb34-6"><a href="#cb34-6" aria-hidden="true" tabindex="-1"></a>    email: []<span class="kw">const</span> <span class="dt">u8</span>,</span>
 <span id="cb34-7"><a href="#cb34-7" aria-hidden="true" tabindex="-1"></a></span>
 <span id="cb34-8"><a href="#cb34-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">fn</span> init(id: <span class="dt">u64</span>,</span>
-<span id="cb34-9"><a href="#cb34-9" aria-hidden="true" tabindex="-1"></a>                name: []<span class="kw">const</span> <span class="dt">u8</span>,</span>
-<span id="cb34-10"><a href="#cb34-10" aria-hidden="true" tabindex="-1"></a>                email: []<span class="kw">const</span> <span class="dt">u8</span>) User <span class="op">{</span></span>
+<span id="cb34-9"><a href="#cb34-9" aria-hidden="true" tabindex="-1"></a>            name: []<span class="kw">const</span> <span class="dt">u8</span>,</span>
+<span id="cb34-10"><a href="#cb34-10" aria-hidden="true" tabindex="-1"></a>            email: []<span class="kw">const</span> <span class="dt">u8</span>) User <span class="op">{</span></span>
 <span id="cb34-11"><a href="#cb34-11" aria-hidden="true" tabindex="-1"></a></span>
 <span id="cb34-12"><a href="#cb34-12" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> User <span class="op">{</span></span>
 <span id="cb34-13"><a href="#cb34-13" aria-hidden="true" tabindex="-1"></a>            .id = id,</span>
@@ -988,7 +988,8 @@ <h2 data-number="2.5" class="anchored" data-anchor-id="sec-type-cast"><span clas
 <span id="cb57-6"><a href="#cb57-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(y) == <span class="dt">u32</span>);</span>
 <span id="cb57-7"><a href="#cb57-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file3c448aa9d5f.test_0...OKAll 1 tests passed.</code></pre>
+<pre><code>1/1 file3fc93b4ea641.test_0...OKAll 1 tests passed
+  d.</code></pre>
 </div>
 </div>
 <p>This is the general way to perform type casting in Zig. But remember, <code>@as()</code> works only when casting is unambiguous and safe. There are many situations where these assumptions do not hold. For example,</p>
@@ -1004,7 +1005,7 @@ <h2 data-number="2.5" class="anchored" data-anchor-id="sec-type-cast"><span clas
 <span id="cb59-6"><a href="#cb59-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(y) == <span class="dt">f32</span>);</span>
 <span id="cb59-7"><a href="#cb59-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file3c4427337b66.test_0...OKAll 1 tests passed
+<pre><code>1/1 file3fc91795a712.test_0...OKAll 1 tests passed
   d.</code></pre>
 </div>
 </div>
@@ -1021,7 +1022,7 @@ <h2 data-number="2.5" class="anchored" data-anchor-id="sec-type-cast"><span clas
 <span id="cb61-8"><a href="#cb61-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(u32_ptr) == *<span class="kw">const</span> <span class="dt">u32</span>);</span>
 <span id="cb61-9"><a href="#cb61-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file3c4479f1f6f8.test_0...OKAll 1 tests passed
+<pre><code>1/1 file3fc945f8b4b0.test_0...OKAll 1 tests passed
   d.</code></pre>
 </div>
 </div>
diff --git a/docs/search.json b/docs/search.json
index 2c6e11fa..960167a2 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -254,7 +254,7 @@
     "href": "Chapters/03-structs.html#sec-structs-and-oop",
     "title": "2  Control flow, structs, modules and types",
     "section": "2.3 Structs and OOP",
-    "text": "2.3 Structs and OOP\nZig is a language more closely related to C (which is a procedural language), than it is to C++ or Java (which are object-oriented languages). Because of that, you do not have advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or class inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C. You give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can also register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object that you create with this new type, will always have these methods available and associated with them.\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which is used to construct (or, to instantiate) every object of this particular class, and we also have a destructor method (or a destructor function), which is the function responsible for destroying every object of this class.\nIn Zig, we normally declare the constructor and the destructor methods of our structs, by declaring an init() and a deinit() methods inside the struct. This is just a naming convention that you will find across the entire Zig Standard Library. So, in Zig, the init() method of a struct is normally the constructor method of the class represented by this struct. While the deinit() method is the method used for destroying an existing instance of that struct.\nThe init() and deinit() methods are both used extensively in Zig code, and you will see both of them being used when we talk about allocators in Section 3.3. But, as another example, let’s build a simple User struct to represent a user of some sort of system.\nIf you look at the User struct below, you can see the struct keyword. Notice the data members of this struct: id, name and email. Every data member has its type explicitly annotated, with the colon character (:) syntax that we described earlier in Section 1.2.2. But also notice that every line in the struct body that describes a data member, ends with a comma character (,). So every time you declare a data member in your Zig code, always end the line with a comma character, instead of ending it with the traditional semicolon character (;).\nNext, we have registered an init() function as a method of this User struct. This init() method is the constructor method that we will use to instantiate every new User object. That is why this init() function returns a new User object as result.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    fn init(id: u64,\n                name: []const u8,\n                email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n\npedro\n\n\n\n2.3.1 The pub keyword\nThe pub keyword plays an important role in struct declarations, and OOP in Zig. In essence, this keyword is short for “public”, and it makes an item/component available outside of the module where this item/component is declared. In other words, if I don’t apply the pub keyword on something, it means that this “something” is available to be called/used only from within the module where this “something” is declared.\nTo demonstrate the effect of this keyword let’s focus again on the User struct that we have declared on the previous section. For our example here, let’s suppose that this User struct is declared inside a Zig module named user.zig. If I don’t use the pub keyword on the User struct, it means that I can create an User object, and call it’s methods (print_name() and init()) only from within the module where the User struct is declared, which in this case is the user.zig module.\nThis is why the previous code example works fine. Because we declare and also use the User struct inside the same module. But problems start to arise when we try to import and call/use this struct from another module. For example, if I create a new module called register.zig, and import the user.zig module into it, and try to annotate any variable with the User type, I get an error from the compiler.\n// register.zig\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = undefined;\n    _ = u;\n}\nregister.zig:3:18: error: 'User' is not marked 'pub'\n    const u: user.User = undefined;\n             ~~~~^~~~~\nuser.zig:3:1: note: declared here\nconst User = struct {\n^~~~~\nTherefore, if you want to use something outside of the module where this “something” is declared, you have to mark it with the pub keyword. This “something” can be a module, a struct, a function, an object, etc.\nFor our example here, if we go back to the user.zig module, and add the pub keyword to the User struct declaration, then, I can successfully compile the register.zig module.\n// user.zig\n// Added the `pub` keyword to `User`\npub const User = struct {\n// ...\n// register.zig\n// This works fine now!\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = undefined;\n    _ = u;\n}\nNow, what do you think it will happen if I try to actually call from register.zig any of the methods of the User struct? For example, if I try to call the init() method? The answer is: I get a similar error message, warning me that the init() method is not marked as pub, as you can see below:\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = user.User.init(\n        1, \"pedro\", \"email@gmail.com\"\n    );\n    _ = u;\n}\nregister.zig:3:35: error: 'init' is not marked 'pub'\n    const u: user.User = user.User.init(\n                         ~~~~~~~~~^~~~~\nuser.zig:8:5: note: declared here\n    fn init(id: u64,\n    ^~~~~~~\nThus, just because we have applied the pub keyword on the struct declaration, this does not make the methods of that struct public as well. If we want to use any method from a struct (such as the init() method) outside of the module where this struct is declared, we have to mark this method with the pub keyword as well.\nGoing back to the user.zig module, and marking both the init() and print_name() methods with the pub keyword, makes them both available to the outside world, and, as consequence, makes the previous code example work.\n// user.zig\n// Added the `pub` keyword to `User.init`\n    pub fn init(\n// ...\n// Added the `pub` keyword to `User.print_name`\n    pub fn print_name(self: User) !void {\n// ...\n// register.zig\n// This works fine now!\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = user.User.init(\n        1, \"pedro\", \"email@gmail.com\"\n    );\n    _ = u;\n}\n\n\n2.3.2 Anonymous struct literals\nYou can declare a struct object as a literal value. When we do that, we normally specify the data type of this struct literal by writing its data type just before the opening curly brace. For example, I could write a struct literal value of the type User that we have defined in the previous section like this:\n\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a struct literal, but not specify explicitly the type of this particular struct. An anonymous struct is written by using the syntax .{}. So, we essentially replaced the explicit type of the struct literal with a dot character (.).\nAs we described in Section 2.4, when you put a dot before a struct literal, the type of this struct literal is automatically inferred by the zig compiler. In essence, the zig compiler will look for some hint of what is the type of that struct. This hint can be the type annotation of a function argument, or the return type annotation of the function that you are using, or the type annotation of an existing object. If the compiler does find such type annotation, it will use this type in your literal struct.\nAnonymous structs are very commonly used as inputs to function arguments in Zig. One example that you have seen already constantly, is the print() function from the stdout object. This function takes two arguments. The first argument, is a template string, which should contain string format specifiers in it, which tells how the values provided in the second argument should be printed into the message.\nWhile the second argument is a struct literal that lists the values to be printed into the template message specified in the first argument. You normally want to use an anonymous struct literal here, so that the zig compiler do the job of specifying the type of this particular anonymous struct for you.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n\nHello, world!\n\n\n\n\n2.3.3 Struct declarations must be constant\nTypes in Zig must be const or comptime (we are going to talk more about comptime in Section 12.1). What this means is that you cannot create a new data type, and mark it as variable with the var keyword. So struct declarations are always constant. You cannot declare a new struct type using the var keyword. It must be const.\nIn the Vec3 example below, this declaration is allowed because I’m using the const keyword to declare this new data type.\n\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n\n\n\n2.3.4 The self method argument\nIn every language that have OOP, when we declare a method of some class or struct, we usually declare this method as a function that has a self argument. This self argument is the reference to the object itself from which the method is being called from.\nIt’s not mandatory to use this self argument. But why would you not use this self argument? There is no reason to not use it. Because the only way to get access to the data stored in the data members of your struct is to access them through this self argument. If you don’t need to use the data in the data members of your struct inside your method, you very likely don’t need a method. You can just declare this logic as a simple function, outside of your struct declaration.\nTake the Vec3 struct below. Inside this Vec3 struct we declared a method named distance(). This method calculates the distance between two Vec3 objects, by following the distance formula in euclidean space. Notice that this distance() method takes two Vec3 objects as input, self and other.\n\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n\nThe self argument corresponds to the Vec3 object from which this distance() method is being called from. While the other is a separate Vec3 object that is given as input to this method. In the example below, the self argument corresponds to the object v1, because the distance() method is being called from the v1 object, while the other argument corresponds to the object v2.\n\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n\nDistance: 3.3970575502926055\n\n\n2.3.5 About the struct state\nSometimes you don’t need to care about the state of your struct object. Sometimes, you just need to instantiate and use the objects, without altering their state. You can notice that when you have methods inside your struct declaration that might use the values that are present in the data members, but they do not alter the values in these data members of the struct in anyway.\nThe Vec3 struct that was presented in Section 2.3.4 is an example of that. This struct have a single method named distance(), and this method does use the values present in all three data members of the struct (x, y and z). But at the same time, this method does not change the values of these data members at any point.\nAs a result of that, when we create Vec3 objects we usually create them as constant objects, like the v1 and v2 objects presented in Section 2.3.4. We can create them as variable objects with the var keyword, if we want to. But because the methods of this Vec3 struct do not change the state of the objects in any point, it’s unnecessary to mark them as variable objects.\nBut why? Why am I talking about this here? It’s because the self argument in the methods are affected depending on whether the methods present in a struct change or don’t change the state of the object itself. More specifically, when you have a method in a struct that changes the state of the object (i.e., changes the value of a data member), the self argument in this method must be annotated in a different manner.\nAs I described in Section 2.3.4, the self argument in methods of a struct is the argument that receives as input the object from which the method was called from. We usually annotate this argument in the methods by writing self, followed by the colon character (:), and the data type of the struct to which the method belongs to (e.g. User, Vec3, etc.).\nIf we take the Vec3 struct that we defined in the previous section as an example, we can see in the distance() method that this self argument is annotated as self: Vec3. Because the state of the Vec3 object is never altered by this method.\nBut what if we do have a method that alters the state of the object, by altering the values of its data members, how should we annotate self in this instance? The answer is: “we should annotate self as a pointer of x, instead of just x”. In other words, you should annotate self as self: *x, instead of annotating it as self: x.\nIf we create a new method inside the Vec3 object that, for example, expands the vector by multiplying its coordinates by a factor of two, then, we need to follow this rule specified in the previous paragraph. The code example below demonstrates this idea:\n\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n\nNotice in the code example above that we have added a new method to our Vec3 struct named twice(). This method doubles the coordinate values of our vector object. In the case of the twice() method, we annotated the self argument as *Vec3, indicating that this argument receives a pointer (or a reference, if you prefer to call it this way) to a Vec3 object as input.\n\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n\nDoubled: 8.4\nNow, if you change the self argument in this twice() method to self: Vec3, like in the distance() method, you will get the compiler error exposed below as result. Notice that this error message is showing a line from the twice() method body, indicating that you cannot alter the value of the x data member.\n\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\nThis error message indicates that the x data member belongs to a constant object, and, because of that, it cannot be changed. Ultimately, this error message is telling us that the self argument is constant.\nIf you take some time, and think hard about this error message, you will understand it. You already have the tools to understand why we are getting this error message. We have talked about it already in Section 2.2. So remember, every function argument is immutable in Zig, and self is no exception to this rule.\nIn this example, we marked the v3 object as a variable object. But this does not matter. Because it’s not about the input object, it’s about the function argument.\nThe problem begins when we try to alter the value of self directly, which is a function argument, and, every function argument is immutable by default. You may ask yourself how can we overcome this barrier, and once again, the solution was also discussed in Section 2.2. We overcome this barrier, by explicitly marking the self argument as a pointer.\n\n\n\n\n\n\nNote\n\n\n\nIf a method of your x struct alters the state of the object, by changing the value of any data member, then, remember to use self: *x, instead of self: x in the function signature of this method.\n\n\nYou could also interpret the content discussed in this section as: “if you need to alter the state of your x struct object in one of its methods, you must explicitly pass the x struct object by reference to the self argument of this method”.",
+    "text": "2.3 Structs and OOP\nZig is a language more closely related to C (which is a procedural language), than it is to C++ or Java (which are object-oriented languages). Because of that, you do not have advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or class inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C. You give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can also register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object that you create with this new type, will always have these methods available and associated with them.\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which is used to construct (or, to instantiate) every object of this particular class, and we also have a destructor method (or a destructor function), which is the function responsible for destroying every object of this class.\nIn Zig, we normally declare the constructor and the destructor methods of our structs, by declaring an init() and a deinit() methods inside the struct. This is just a naming convention that you will find across the entire Zig Standard Library. So, in Zig, the init() method of a struct is normally the constructor method of the class represented by this struct. While the deinit() method is the method used for destroying an existing instance of that struct.\nThe init() and deinit() methods are both used extensively in Zig code, and you will see both of them being used when we talk about allocators in Section 3.3. But, as another example, let’s build a simple User struct to represent a user of some sort of system.\nIf you look at the User struct below, you can see the struct keyword. Notice the data members of this struct: id, name and email. Every data member has its type explicitly annotated, with the colon character (:) syntax that we described earlier in Section 1.2.2. But also notice that every line in the struct body that describes a data member, ends with a comma character (,). So every time you declare a data member in your Zig code, always end the line with a comma character, instead of ending it with the traditional semicolon character (;).\nNext, we have registered an init() function as a method of this User struct. This init() method is the constructor method that we will use to instantiate every new User object. That is why this init() function returns a new User object as result.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    fn init(id: u64,\n            name: []const u8,\n            email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n\npedro\n\n\n\n2.3.1 The pub keyword\nThe pub keyword plays an important role in struct declarations, and OOP in Zig. In essence, this keyword is short for “public”, and it makes an item/component available outside of the module where this item/component is declared. In other words, if I don’t apply the pub keyword on something, it means that this “something” is available to be called/used only from within the module where this “something” is declared.\nTo demonstrate the effect of this keyword let’s focus again on the User struct that we have declared on the previous section. For our example here, let’s suppose that this User struct is declared inside a Zig module named user.zig. If I don’t use the pub keyword on the User struct, it means that I can create an User object, and call it’s methods (print_name() and init()) only from within the module where the User struct is declared, which in this case is the user.zig module.\nThis is why the previous code example works fine. Because we declare and also use the User struct inside the same module. But problems start to arise when we try to import and call/use this struct from another module. For example, if I create a new module called register.zig, and import the user.zig module into it, and try to annotate any variable with the User type, I get an error from the compiler.\n// register.zig\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = undefined;\n    _ = u;\n}\nregister.zig:3:18: error: 'User' is not marked 'pub'\n    const u: user.User = undefined;\n             ~~~~^~~~~\nuser.zig:3:1: note: declared here\nconst User = struct {\n^~~~~\nTherefore, if you want to use something outside of the module where this “something” is declared, you have to mark it with the pub keyword. This “something” can be a module, a struct, a function, an object, etc.\nFor our example here, if we go back to the user.zig module, and add the pub keyword to the User struct declaration, then, I can successfully compile the register.zig module.\n// user.zig\n// Added the `pub` keyword to `User`\npub const User = struct {\n// ...\n// register.zig\n// This works fine now!\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = undefined;\n    _ = u;\n}\nNow, what do you think it will happen if I try to actually call from register.zig any of the methods of the User struct? For example, if I try to call the init() method? The answer is: I get a similar error message, warning me that the init() method is not marked as pub, as you can see below:\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = user.User.init(\n        1, \"pedro\", \"email@gmail.com\"\n    );\n    _ = u;\n}\nregister.zig:3:35: error: 'init' is not marked 'pub'\n    const u: user.User = user.User.init(\n                         ~~~~~~~~~^~~~~\nuser.zig:8:5: note: declared here\n    fn init(id: u64,\n    ^~~~~~~\nThus, just because we have applied the pub keyword on the struct declaration, this does not make the methods of that struct public as well. If we want to use any method from a struct (such as the init() method) outside of the module where this struct is declared, we have to mark this method with the pub keyword as well.\nGoing back to the user.zig module, and marking both the init() and print_name() methods with the pub keyword, makes them both available to the outside world, and, as consequence, makes the previous code example work.\n// user.zig\n// Added the `pub` keyword to `User.init`\n    pub fn init(\n// ...\n// Added the `pub` keyword to `User.print_name`\n    pub fn print_name(self: User) !void {\n// ...\n// register.zig\n// This works fine now!\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = user.User.init(\n        1, \"pedro\", \"email@gmail.com\"\n    );\n    _ = u;\n}\n\n\n2.3.2 Anonymous struct literals\nYou can declare a struct object as a literal value. When we do that, we normally specify the data type of this struct literal by writing its data type just before the opening curly brace. For example, I could write a struct literal value of the type User that we have defined in the previous section like this:\n\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a struct literal, but not specify explicitly the type of this particular struct. An anonymous struct is written by using the syntax .{}. So, we essentially replaced the explicit type of the struct literal with a dot character (.).\nAs we described in Section 2.4, when you put a dot before a struct literal, the type of this struct literal is automatically inferred by the zig compiler. In essence, the zig compiler will look for some hint of what is the type of that struct. This hint can be the type annotation of a function argument, or the return type annotation of the function that you are using, or the type annotation of an existing object. If the compiler does find such type annotation, it will use this type in your literal struct.\nAnonymous structs are very commonly used as inputs to function arguments in Zig. One example that you have seen already constantly, is the print() function from the stdout object. This function takes two arguments. The first argument, is a template string, which should contain string format specifiers in it, which tells how the values provided in the second argument should be printed into the message.\nWhile the second argument is a struct literal that lists the values to be printed into the template message specified in the first argument. You normally want to use an anonymous struct literal here, so that the zig compiler do the job of specifying the type of this particular anonymous struct for you.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n\nHello, world!\n\n\n\n\n2.3.3 Struct declarations must be constant\nTypes in Zig must be const or comptime (we are going to talk more about comptime in Section 12.1). What this means is that you cannot create a new data type, and mark it as variable with the var keyword. So struct declarations are always constant. You cannot declare a new struct type using the var keyword. It must be const.\nIn the Vec3 example below, this declaration is allowed because I’m using the const keyword to declare this new data type.\n\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n\n\n\n2.3.4 The self method argument\nIn every language that have OOP, when we declare a method of some class or struct, we usually declare this method as a function that has a self argument. This self argument is the reference to the object itself from which the method is being called from.\nIt’s not mandatory to use this self argument. But why would you not use this self argument? There is no reason to not use it. Because the only way to get access to the data stored in the data members of your struct is to access them through this self argument. If you don’t need to use the data in the data members of your struct inside your method, you very likely don’t need a method. You can just declare this logic as a simple function, outside of your struct declaration.\nTake the Vec3 struct below. Inside this Vec3 struct we declared a method named distance(). This method calculates the distance between two Vec3 objects, by following the distance formula in euclidean space. Notice that this distance() method takes two Vec3 objects as input, self and other.\n\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n\nThe self argument corresponds to the Vec3 object from which this distance() method is being called from. While the other is a separate Vec3 object that is given as input to this method. In the example below, the self argument corresponds to the object v1, because the distance() method is being called from the v1 object, while the other argument corresponds to the object v2.\n\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n\nDistance: 3.3970575502926055\n\n\n2.3.5 About the struct state\nSometimes you don’t need to care about the state of your struct object. Sometimes, you just need to instantiate and use the objects, without altering their state. You can notice that when you have methods inside your struct declaration that might use the values that are present in the data members, but they do not alter the values in these data members of the struct in anyway.\nThe Vec3 struct that was presented in Section 2.3.4 is an example of that. This struct have a single method named distance(), and this method does use the values present in all three data members of the struct (x, y and z). But at the same time, this method does not change the values of these data members at any point.\nAs a result of that, when we create Vec3 objects we usually create them as constant objects, like the v1 and v2 objects presented in Section 2.3.4. We can create them as variable objects with the var keyword, if we want to. But because the methods of this Vec3 struct do not change the state of the objects in any point, it’s unnecessary to mark them as variable objects.\nBut why? Why am I talking about this here? It’s because the self argument in the methods are affected depending on whether the methods present in a struct change or don’t change the state of the object itself. More specifically, when you have a method in a struct that changes the state of the object (i.e., changes the value of a data member), the self argument in this method must be annotated in a different manner.\nAs I described in Section 2.3.4, the self argument in methods of a struct is the argument that receives as input the object from which the method was called from. We usually annotate this argument in the methods by writing self, followed by the colon character (:), and the data type of the struct to which the method belongs to (e.g. User, Vec3, etc.).\nIf we take the Vec3 struct that we defined in the previous section as an example, we can see in the distance() method that this self argument is annotated as self: Vec3. Because the state of the Vec3 object is never altered by this method.\nBut what if we do have a method that alters the state of the object, by altering the values of its data members, how should we annotate self in this instance? The answer is: “we should annotate self as a pointer of x, instead of just x”. In other words, you should annotate self as self: *x, instead of annotating it as self: x.\nIf we create a new method inside the Vec3 object that, for example, expands the vector by multiplying its coordinates by a factor of two, then, we need to follow this rule specified in the previous paragraph. The code example below demonstrates this idea:\n\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n\nNotice in the code example above that we have added a new method to our Vec3 struct named twice(). This method doubles the coordinate values of our vector object. In the case of the twice() method, we annotated the self argument as *Vec3, indicating that this argument receives a pointer (or a reference, if you prefer to call it this way) to a Vec3 object as input.\n\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n\nDoubled: 8.4\nNow, if you change the self argument in this twice() method to self: Vec3, like in the distance() method, you will get the compiler error exposed below as result. Notice that this error message is showing a line from the twice() method body, indicating that you cannot alter the value of the x data member.\n\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\nThis error message indicates that the x data member belongs to a constant object, and, because of that, it cannot be changed. Ultimately, this error message is telling us that the self argument is constant.\nIf you take some time, and think hard about this error message, you will understand it. You already have the tools to understand why we are getting this error message. We have talked about it already in Section 2.2. So remember, every function argument is immutable in Zig, and self is no exception to this rule.\nIn this example, we marked the v3 object as a variable object. But this does not matter. Because it’s not about the input object, it’s about the function argument.\nThe problem begins when we try to alter the value of self directly, which is a function argument, and, every function argument is immutable by default. You may ask yourself how can we overcome this barrier, and once again, the solution was also discussed in Section 2.2. We overcome this barrier, by explicitly marking the self argument as a pointer.\n\n\n\n\n\n\nNote\n\n\n\nIf a method of your x struct alters the state of the object, by changing the value of any data member, then, remember to use self: *x, instead of self: x in the function signature of this method.\n\n\nYou could also interpret the content discussed in this section as: “if you need to alter the state of your x struct object in one of its methods, you must explicitly pass the x struct object by reference to the self argument of this method”.",
     "crumbs": [
       "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
     ]
@@ -274,7 +274,7 @@
     "href": "Chapters/03-structs.html#sec-type-cast",
     "title": "2  Control flow, structs, modules and types",
     "section": "2.5 Type casting",
-    "text": "2.5 Type casting\nIn this section, I want to discuss type casting (or, type conversion) with you. We use type casting when we have an object of type “x”, and we want to convert it into an object of type “y”, i.e., we want to change the data type of the object.\nMost languages have a formal way to perform type casting. In Rust for example, we normally use the keyword as, and in C, we normally use the type casting syntax, e.g. (int) x. In Zig, we use the @as() built-in function to cast an object of type “x”, into an object of type “y”.\nThis @as() function is the preferred way to perform type conversion (or type casting) in Zig. Because it’s explicit, and, it also performs the casting only if it is unambiguous and safe. To use this function, you just provide the target data type in the first argument, and, the object that you want cast as the second argument.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n\n1/1 file3c448aa9d5f.test_0...OKAll 1 tests passed.\n\n\nThis is the general way to perform type casting in Zig. But remember, @as() works only when casting is unambiguous and safe. There are many situations where these assumptions do not hold. For example,\nwhen casting an integer value into a float value, or vice-versa, it’s not clear to the compiler how to perform this conversion safely.\nTherefore, we need to use specialized “casting functions” in such situations. For example, if you want to cast an integer value into a float value, then, you should use the @floatFromInt() function. In the inverse scenario, you should use the @intFromFloat() function.\nIn these functions, you just provide the object that you want to cast as input. Then, the target data type of the “type casting operation” is determined by the type annotation of the object where you are saving the results. In the example below, we are casting the object x into a value of type f32, because the object y, which is where we are saving the results, is annotated as an object of type f32.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n\n1/1 file3c4427337b66.test_0...OKAll 1 tests passed\n  d.\n\n\nAnother built-in function that is very useful when performing type casting operations is @ptrCast(). In essence, we use the @as() built-in function when we want to explicit convert (or cast) a Zig value/object from a type “x” to a type “y”, etc. However, pointers (we are going to discuss pointers in more depth in Chapter 6) are a special type of object in Zig, i.e., they are treated differently from “normal objects”.\nEverytime a pointer is involved in some “type casting operation” in Zig, the @ptrCast() function is used. This function works similarly to @floatFromInt(). You just provide the pointer object that you want to cast as input to this function, and the target data type is, once again, determined by the type annotation of the object where the results are being stored.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n\n1/1 file3c4479f1f6f8.test_0...OKAll 1 tests passed\n  d.",
+    "text": "2.5 Type casting\nIn this section, I want to discuss type casting (or, type conversion) with you. We use type casting when we have an object of type “x”, and we want to convert it into an object of type “y”, i.e., we want to change the data type of the object.\nMost languages have a formal way to perform type casting. In Rust for example, we normally use the keyword as, and in C, we normally use the type casting syntax, e.g. (int) x. In Zig, we use the @as() built-in function to cast an object of type “x”, into an object of type “y”.\nThis @as() function is the preferred way to perform type conversion (or type casting) in Zig. Because it’s explicit, and, it also performs the casting only if it is unambiguous and safe. To use this function, you just provide the target data type in the first argument, and, the object that you want cast as the second argument.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n\n1/1 file3fc93b4ea641.test_0...OKAll 1 tests passed\n  d.\n\n\nThis is the general way to perform type casting in Zig. But remember, @as() works only when casting is unambiguous and safe. There are many situations where these assumptions do not hold. For example,\nwhen casting an integer value into a float value, or vice-versa, it’s not clear to the compiler how to perform this conversion safely.\nTherefore, we need to use specialized “casting functions” in such situations. For example, if you want to cast an integer value into a float value, then, you should use the @floatFromInt() function. In the inverse scenario, you should use the @intFromFloat() function.\nIn these functions, you just provide the object that you want to cast as input. Then, the target data type of the “type casting operation” is determined by the type annotation of the object where you are saving the results. In the example below, we are casting the object x into a value of type f32, because the object y, which is where we are saving the results, is annotated as an object of type f32.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n\n1/1 file3fc91795a712.test_0...OKAll 1 tests passed\n  d.\n\n\nAnother built-in function that is very useful when performing type casting operations is @ptrCast(). In essence, we use the @as() built-in function when we want to explicit convert (or cast) a Zig value/object from a type “x” to a type “y”, etc. However, pointers (we are going to discuss pointers in more depth in Chapter 6) are a special type of object in Zig, i.e., they are treated differently from “normal objects”.\nEverytime a pointer is involved in some “type casting operation” in Zig, the @ptrCast() function is used. This function works similarly to @floatFromInt(). You just provide the pointer object that you want to cast as input to this function, and the target data type is, once again, determined by the type annotation of the object where the results are being stored.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n\n1/1 file3fc945f8b4b0.test_0...OKAll 1 tests passed\n  d.",
     "crumbs": [
       "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
     ]

From 8f5a53feb455fa3b0ad50ab516b94897cb44cad9 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Thu, 20 Mar 2025 19:36:14 -0300
Subject: [PATCH 118/151] Update index

---
 _freeze/index/execute-results/html.json | 4 ++--
 docs/index.html                         | 8 ++++----
 docs/search.json                        | 4 ++--
 index.qmd                               | 4 ++--
 4 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/_freeze/index/execute-results/html.json b/_freeze/index/execute-results/html.json
index abf34f7d..16283e0b 100644
--- a/_freeze/index/execute-results/html.json
+++ b/_freeze/index/execute-results/html.json
@@ -1,8 +1,8 @@
 {
-  "hash": "335ac568e17c5057352e05da9521e5ae",
+  "hash": "0b80ffe49bae68e2641a31569b9e19df",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy a PDF, eBook or a physical copy\nof the book, either at Amazon, or at Leanpub:\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://leanpub.com/introductiontozigaproject-basedbook\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Leanpub!\n    </button>\n</a>\n\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e., open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.\nCurrently, he is a Data Platform Engineer at [Blip](https://www.blip.ai/en/)[^blip], and\na Databricks Certified Associate Developer for Apache Spark 3.0.\n\n[^blip]: <https://www.blip.ai/en/>\n\n\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nBrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer who loves to learn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2025 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n\n- System version: Linux, 6.11.0-19-generic, 24.04.1-Ubuntu, x86_64.\n- Zig version: 0.14.0-dev.3046+08d661fcf.\n- Quarto version: 1.5.57.\n\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang), Tommaso Ricci (\\@Zorgatone), Primo Sabatini (\\@primos63), Santiago Fernandez (\\@santif), Hamza Wahed (\\@HamzaWahed), mwilbur (\\@mwilbur), Dima Budaragin (\\@dbud), Jorge Jímenez (\\@jorge-j1m), Alexander (\\@alexwheezy), Maarten Coopens (\\@maarteNNNN), Niklas Johansson (\\@Raphexion), glystik (\\@glystik), Michael Lynch (\\@mtlynch)\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy a PDF, eBook or a physical copy\nof the book, either at Amazon, or at Leanpub:\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://leanpub.com/introductiontozigaproject-basedbook\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Leanpub!\n    </button>\n</a>\n\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e., open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.\nCurrently, he is a Senior Data Engineer at [DSM-Firmenich](https://www.dsm-firmenich.com)[^dsm], and\na Databricks Certified Associate Developer for Apache Spark 3.0.\n\n[^dsm]: <https://www.dsm-firmenich.com>\n\n\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nBrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer who loves to learn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2025 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n\n\n- System version: Linux, 6.11.0-19-generic, 24.04.1-Ubuntu, x86_64.\n- Zig version: 0.14.0-dev.3046+08d661fcf.\n- Quarto version: 1.5.57.\n\n\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang), Tommaso Ricci (\\@Zorgatone), Primo Sabatini (\\@primos63), Santiago Fernandez (\\@santif), Hamza Wahed (\\@HamzaWahed), mwilbur (\\@mwilbur), Dima Budaragin (\\@dbud), Jorge Jímenez (\\@jorge-j1m), Alexander (\\@alexwheezy), Maarten Coopens (\\@maarteNNNN), Niklas Johansson (\\@Raphexion), glystik (\\@glystik), Michael Lynch (\\@mtlynch)\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
diff --git a/docs/index.html b/docs/index.html
index 34e98809..846deca6 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -7,7 +7,7 @@
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 <meta name="author" content="Pedro Duarte Faria">
-<meta name="dcterms.date" content="2025-03-08">
+<meta name="dcterms.date" content="2025-03-20">
 
 <title>Introduction to Zig</title>
 <style>
@@ -287,7 +287,7 @@ <h1 class="title">Introduction to Zig</h1>
     <div>
     <div class="quarto-title-meta-heading">Published</div>
     <div class="quarto-title-meta-contents">
-      <p class="date">March 8, 2025</p>
+      <p class="date">March 20, 2025</p>
     </div>
   </div>
   
@@ -409,7 +409,7 @@ <h2 class="unnumbered anchored" data-anchor-id="about-this-book">About this book
 </section>
 <section id="about-the-author" class="level2 unnumbered">
 <h2 class="unnumbered anchored" data-anchor-id="about-the-author">About the author</h2>
-<p>Pedro Duarte Faria has a bachelor’s degree in Economics from the Federal University of Ouro Preto - Brazil. Currently, he is a Data Platform Engineer at <a href="https://www.blip.ai/en/">Blip</a><a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>, and a Databricks Certified Associate Developer for Apache Spark 3.0.</p>
+<p>Pedro Duarte Faria has a bachelor’s degree in Economics from the Federal University of Ouro Preto - Brazil. Currently, he is a Senior Data Engineer at <a href="https://www.dsm-firmenich.com">DSM-Firmenich</a><a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>, and a Databricks Certified Associate Developer for Apache Spark 3.0.</p>
 <p>The author has more than 4 years of experience in the data industry, developing data products, pipelines, reports and analysis for research institutions and some of the largest companies in the Brazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.</p>
 <p>But Pedro is also a passionate software developer who loves to learn and teach about programming. Although Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several lectures and courses about it, inside graduate centers (such as PPEA-UFOP<a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a>), in addition to federal and state organizations (such as FJP-MG<a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a>).</p>
 <p>Personal Website: <a href="https://pedro-faria.netlify.app/" class="uri">https://pedro-faria.netlify.app/</a></p>
@@ -462,7 +462,7 @@ <h2 class="unnumbered anchored" data-anchor-id="acknowledgments">Acknowledgments
 <section id="footnotes" class="footnotes footnotes-end-of-document" role="doc-endnotes">
 <hr>
 <ol>
-<li id="fn1"><p><a href="https://www.blip.ai/en/" class="uri">https://www.blip.ai/en/</a><a href="#fnref1" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn1"><p><a href="https://www.dsm-firmenich.com" class="uri">https://www.dsm-firmenich.com</a><a href="#fnref1" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
 <li id="fn2"><p><a href="https://ppea.ufop.br/" class="uri">https://ppea.ufop.br/</a><a href="#fnref2" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
 <li id="fn3"><p><a href="http://fjp.mg.gov.br/" class="uri">http://fjp.mg.gov.br/</a><a href="#fnref3" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
 <li id="fn4"><p><a href="https://creativecommons.org/licenses/by/4.0/" class="uri">https://creativecommons.org/licenses/by/4.0/</a><a href="#fnref4" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
diff --git a/docs/search.json b/docs/search.json
index 960167a2..bd4e81c0 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -34,7 +34,7 @@
     "href": "index.html#about-the-author",
     "title": "Introduction to Zig",
     "section": "About the author",
-    "text": "About the author\nPedro Duarte Faria has a bachelor’s degree in Economics from the Federal University of Ouro Preto - Brazil. Currently, he is a Data Platform Engineer at Blip1, and a Databricks Certified Associate Developer for Apache Spark 3.0.\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines, reports and analysis for research institutions and some of the largest companies in the Brazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\nBut Pedro is also a passionate software developer who loves to learn and teach about programming. Although Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several lectures and courses about it, inside graduate centers (such as PPEA-UFOP2), in addition to federal and state organizations (such as FJP-MG3).\nPersonal Website: https://pedro-faria.netlify.app/\nLinkedin: https://www.linkedin.com/in/pedro-faria-a68140209/\nMastodon: @pedropark99@fosstodon.org\nTwitter (X): @PedroPark9",
+    "text": "About the author\nPedro Duarte Faria has a bachelor’s degree in Economics from the Federal University of Ouro Preto - Brazil. Currently, he is a Senior Data Engineer at DSM-Firmenich1, and a Databricks Certified Associate Developer for Apache Spark 3.0.\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines, reports and analysis for research institutions and some of the largest companies in the Brazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\nBut Pedro is also a passionate software developer who loves to learn and teach about programming. Although Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several lectures and courses about it, inside graduate centers (such as PPEA-UFOP2), in addition to federal and state organizations (such as FJP-MG3).\nPersonal Website: https://pedro-faria.netlify.app/\nLinkedin: https://www.linkedin.com/in/pedro-faria-a68140209/\nMastodon: @pedropark99@fosstodon.org\nTwitter (X): @PedroPark9",
     "crumbs": [
       "Welcome"
     ]
@@ -94,7 +94,7 @@
     "href": "index.html#footnotes",
     "title": "Introduction to Zig",
     "section": "",
-    "text": "https://www.blip.ai/en/↩︎\nhttps://ppea.ufop.br/↩︎\nhttp://fjp.mg.gov.br/↩︎\nhttps://creativecommons.org/licenses/by/4.0/↩︎",
+    "text": "https://www.dsm-firmenich.com↩︎\nhttps://ppea.ufop.br/↩︎\nhttp://fjp.mg.gov.br/↩︎\nhttps://creativecommons.org/licenses/by/4.0/↩︎",
     "crumbs": [
       "Welcome"
     ]
diff --git a/index.qmd b/index.qmd
index a63df77b..734973c3 100644
--- a/index.qmd
+++ b/index.qmd
@@ -95,10 +95,10 @@ As you work through the book, you will learn:
 ## About the author {.unnumbered}
 
 Pedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.
-Currently, he is a Data Platform Engineer at [Blip](https://www.blip.ai/en/)[^blip], and
+Currently, he is a Senior Data Engineer at [DSM-Firmenich](https://www.dsm-firmenich.com)[^dsm], and
 a Databricks Certified Associate Developer for Apache Spark 3.0.
 
-[^blip]: <https://www.blip.ai/en/>
+[^dsm]: <https://www.dsm-firmenich.com>
 
 
 The author has more than 4 years of experience in the data industry, developing data products, pipelines,

From f2fe9904d0a0d41701ba721a57012c6f552f5218 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Mon, 7 Apr 2025 10:38:21 -0300
Subject: [PATCH 119/151] Add small paragraph to identifiers section

---
 Chapters/01-zig-weird.qmd                           | 13 ++++++++++++-
 .../Chapters/01-zig-weird/execute-results/html.json |  4 ++--
 docs/Chapters/01-zig-weird.html                     |  4 +++-
 docs/index.html                                     |  4 ++--
 docs/search.json                                    |  2 +-
 5 files changed, 20 insertions(+), 7 deletions(-)

diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index 4c9d4f68..2b1ed767 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -648,7 +648,7 @@ t.zig:10:5: error: cannot assign to constant
       ~~^~~
 ```
 
-In contrast, if you use `var`, then, the object created is a variable object.
+In contrast, if you use `var`, then, the object created is a variable (or "mutable") object.
 With `var` you can declare this object in your source code, and then,
 change the value of this object how many times you want over future points
 in your source code.
@@ -658,6 +658,17 @@ So, using the same code example exposed above, if I change the declaration of th
 Because now, the `zig` compiler detects that we are changing the value of an
 object that allows this behaviour, because it's a "variable object".
 
+Also, notice in the example below that we have explicitly annotated the data type
+of the `age` object with the `u8` type. The basic idea is, when we use a variable/mutable object,
+the Zig compiler ask for us to be more explicit with what we want, to be more clear
+about what our code does.
+
+Therefore, if you transform your object into a variable/mutable object, just remember to always
+annotate the type of the object explicitly in your code. Otherwise, the Zig compiler might raise
+a compilation error, asking you to transform your object back into a `const` object, or,
+to give your object an "explicit type".
+
+
 ```{zig}
 #| build_type: "run"
 #| auto_main: true
diff --git a/_freeze/Chapters/01-zig-weird/execute-results/html.json b/_freeze/Chapters/01-zig-weird/execute-results/html.json
index 5bdb8502..bf9024d1 100644
--- a/_freeze/Chapters/01-zig-weird/execute-results/html.json
+++ b/_freeze/Chapters/01-zig-weird/execute-results/html.json
@@ -1,8 +1,8 @@
 {
-  "hash": "686bec0276a3623e1397e1b7ecac1bfa",
+  "hash": "7e77940b6c0b71d5a70d87e19225e353",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\n\nlanguage, it's still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. Sometimes, they really make it hard to debug\n\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscure the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that gets compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e., where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contains Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nWe can use this build system to write small scripts in Zig,\nwhich describe the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e., creating new objects)\nare made in Zig. You can create a new object in Zig by using the syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). In @sec-assignments we talk more about objects in general.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that in @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIt's worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt's like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portable C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nIn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e., the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. If you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith an \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, on Windows, operations like accessing the `stdout` (or opening a file) depend on\nresources that are available only at *runtime* (you will learn more about compile-time versus runtime\nin @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerges from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword in @sec-comptime.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation in a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues\n\n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described in @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig later in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig?\nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar to our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentation.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It's a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (on YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e., identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nIn contrast, if you use `var`, then, the object created is a variable object.\nWith `var` you can declare this object in your source code, and then,\nchange the value of this object how many times you want over future points\nin your source code.\n\nSo, using the same code example exposed above, if I change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it's a \"variable object\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIt's important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code uses this object while it's uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object.\n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e., if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to a special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It's discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also gets discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e., the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\nIt's worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it's a slice that\naccesses all elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" in @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth in @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially in @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned in @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e., the start and the end of this range)\nis known at compile-time, the slice object that gets created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nin @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that gets created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e., a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can\ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n```\n:::\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat gets created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, the `slice` object have a runtime known range, because the end index of the range\nis not known at compile time. In other words, the size of the array at `buffer` is not known\nat compile time. When we execute this program, the size of the array might be 10, or, it might be 12\ndepending on where we execute it. Therefore, we don't know at compile time if\nthe slice object have a range of size 10, or, a range of size 12.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e., a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e., similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented in @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e., `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIt's worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e., a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e., the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause it's much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e., if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it's a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIt's important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig in @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers in @sec-root-file and especially in @sec-assignments.\n- How strings work in Zig in @sec-zig-strings.\n- How to use arrays and slices in @sec-arrays.\n- How to import functionality from other Zig modules in @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* in @sec-structs-and-oop.\n- Basic control flow syntax in @sec-zig-control-flow.\n- Enums in @sec-enum;\n- Pointers and Optionals in @sec-pointer;\n- Error handling with `try` and `catch` in @sec-error-handling;\n- Unit tests in @sec-unittests;\n- Vectors in @sec-vectors-simd;\n- Build System in @sec-build-system;\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\n\nlanguage, it's still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. Sometimes, they really make it hard to debug\n\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscure the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that gets compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e., where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contains Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nWe can use this build system to write small scripts in Zig,\nwhich describe the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e., creating new objects)\nare made in Zig. You can create a new object in Zig by using the syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). In @sec-assignments we talk more about objects in general.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that in @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIt's worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt's like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portable C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nIn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e., the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. If you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith an \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, on Windows, operations like accessing the `stdout` (or opening a file) depend on\nresources that are available only at *runtime* (you will learn more about compile-time versus runtime\nin @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerges from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword in @sec-comptime.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation in a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues\n\n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described in @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig later in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig?\nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar to our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentation.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It's a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (on YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e., identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nIn contrast, if you use `var`, then, the object created is a variable (or \"mutable\") object.\nWith `var` you can declare this object in your source code, and then,\nchange the value of this object how many times you want over future points\nin your source code.\n\nSo, using the same code example exposed above, if I change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it's a \"variable object\".\n\nAlso, notice in the example below that we have explicitly annotated the data type\nof the `age` object with the `u8` type. The basic idea is, when we use a variable/mutable object,\nthe Zig compiler ask for us to be more explicit with what we want, to be more clear\nabout what our code does.\n\nTherefore, if you transform your object into a variable/mutable object, just remember to always\nannotate the type of the object explicitly in your code. Otherwise, the Zig compiler might raise\na compilation error, asking you to transform your object back into a `const` object, or,\nto give your object an \"explicit type\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIt's important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code uses this object while it's uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object.\n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e., if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to a special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It's discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also gets discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e., the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\nIt's worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it's a slice that\naccesses all elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" in @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth in @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially in @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned in @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e., the start and the end of this range)\nis known at compile-time, the slice object that gets created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nin @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that gets created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e., a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can\ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n```\n:::\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat gets created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, the `slice` object have a runtime known range, because the end index of the range\nis not known at compile time. In other words, the size of the array at `buffer` is not known\nat compile time. When we execute this program, the size of the array might be 10, or, it might be 12\ndepending on where we execute it. Therefore, we don't know at compile time if\nthe slice object have a range of size 10, or, a range of size 12.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e., a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e., similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented in @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e., `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIt's worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e., a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e., the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause it's much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e., if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it's a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIt's important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig in @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers in @sec-root-file and especially in @sec-assignments.\n- How strings work in Zig in @sec-zig-strings.\n- How to use arrays and slices in @sec-arrays.\n- How to import functionality from other Zig modules in @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* in @sec-structs-and-oop.\n- Basic control flow syntax in @sec-zig-control-flow.\n- Enums in @sec-enum;\n- Pointers and Optionals in @sec-pointer;\n- Error handling with `try` and `catch` in @sec-error-handling;\n- Unit tests in @sec-unittests;\n- Vectors in @sec-vectors-simd;\n- Build System in @sec-build-system;\n",
     "supporting": [
       "01-zig-weird_files"
     ],
diff --git a/docs/Chapters/01-zig-weird.html b/docs/Chapters/01-zig-weird.html
index 43f740f4..4b7fac7d 100644
--- a/docs/Chapters/01-zig-weird.html
+++ b/docs/Chapters/01-zig-weird.html
@@ -580,8 +580,10 @@ <h3 data-number="1.4.1" class="anchored" data-anchor-id="constant-objects-vs-var
 <pre><code>t.zig:10:5: error: cannot assign to constant
     age = 25;
       ~~^~~</code></pre>
-<p>In contrast, if you use <code>var</code>, then, the object created is a variable object. With <code>var</code> you can declare this object in your source code, and then, change the value of this object how many times you want over future points in your source code.</p>
+<p>In contrast, if you use <code>var</code>, then, the object created is a variable (or “mutable”) object. With <code>var</code> you can declare this object in your source code, and then, change the value of this object how many times you want over future points in your source code.</p>
 <p>So, using the same code example exposed above, if I change the declaration of the <code>age</code> object to use the <code>var</code> keyword, then, the program gets compiled successfully. Because now, the <code>zig</code> compiler detects that we are changing the value of an object that allows this behaviour, because it’s a “variable object”.</p>
+<p>Also, notice in the example below that we have explicitly annotated the data type of the <code>age</code> object with the <code>u8</code> type. The basic idea is, when we use a variable/mutable object, the Zig compiler ask for us to be more explicit with what we want, to be more clear about what our code does.</p>
+<p>Therefore, if you transform your object into a variable/mutable object, just remember to always annotate the type of the object explicitly in your code. Otherwise, the Zig compiler might raise a compilation error, asking you to transform your object back into a <code>const</code> object, or, to give your object an “explicit type”.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb23"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb23-1"><a href="#cb23-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> age: <span class="dt">u8</span> = <span class="dv">24</span>;</span>
 <span id="cb23-2"><a href="#cb23-2" aria-hidden="true" tabindex="-1"></a>age = <span class="dv">25</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
diff --git a/docs/index.html b/docs/index.html
index 846deca6..e8b33e08 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -7,7 +7,7 @@
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 <meta name="author" content="Pedro Duarte Faria">
-<meta name="dcterms.date" content="2025-03-20">
+<meta name="dcterms.date" content="2025-04-07">
 
 <title>Introduction to Zig</title>
 <style>
@@ -287,7 +287,7 @@ <h1 class="title">Introduction to Zig</h1>
     <div>
     <div class="quarto-title-meta-heading">Published</div>
     <div class="quarto-title-meta-contents">
-      <p class="date">March 20, 2025</p>
+      <p class="date">April 7, 2025</p>
     </div>
   </div>
   
diff --git a/docs/search.json b/docs/search.json
index bd4e81c0..571402f4 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -144,7 +144,7 @@
     "href": "Chapters/01-zig-weird.html#sec-assignments",
     "title": "1  Introducing Zig",
     "section": "1.4 Creating new objects in Zig (i.e., identifiers)",
-    "text": "1.4 Creating new objects in Zig (i.e., identifiers)\nLet’s talk more about objects in Zig. Readers that have past experience with other programming languages might know this concept through a different name, such as: “variable” or “identifier”. In this book, I choose to use the term “object” to refer to this concept.\nTo create a new object (or a new “identifier”) in Zig, we use the keywords const or var. These keywords specify if the object that you are creating is mutable or not. If you use const, then the object you are creating is a constant (or immutable) object, which means that once you declare this object, you can no longer change the value stored inside this object.\nOn the other side, if you use var, then, you are creating a variable (or mutable) object. You can change the value of this object as many times you want. Using the keyword var in Zig is similar to using the keywords let mut in Rust.\n\n1.4.1 Constant objects vs variable objects\nIn the code example below, we are creating a new constant object called age. This object stores a number representing the age of someone. However, this code example does not compile successfully. Because on the next line of code, we are trying to change the value of the object age to 25.\nThe zig compiler detects that we are trying to change the value of an object/identifier that is constant, and because of that, the compiler will raise a compilation error, warning us about the mistake.\n\nconst age = 24;\n// The line below is not valid!\nage = 25;\n\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\nIn contrast, if you use var, then, the object created is a variable object. With var you can declare this object in your source code, and then, change the value of this object how many times you want over future points in your source code.\nSo, using the same code example exposed above, if I change the declaration of the age object to use the var keyword, then, the program gets compiled successfully. Because now, the zig compiler detects that we are changing the value of an object that allows this behaviour, because it’s a “variable object”.\n\nvar age: u8 = 24;\nage = 25;\n\n\n\n1.4.2 Declaring without an initial value\nBy default, when you declare a new object in Zig, you must give it an initial value. In other words, this means that we have to declare, and, at the same time, initialize every object we create in our source code.\nOn the other hand, you can, in fact, declare a new object in your source code, and not give it an explicit value. But we need to use a special keyword for that, which is the undefined keyword.\nIt’s important to emphasize that, you should avoid using undefined as much as possible. Because when you use this keyword, you leave your object uninitialized, and, as a consequence, if for some reason, your code uses this object while it’s uninitialized, then, you will definitely have undefined behaviour and major bugs in your program.\nIn the example below, I’m declaring the age object again. But this time, I do not give it an initial value. The variable is only initialized at the second line of code, where I store the number 25 in this object.\n\nvar age: u8 = undefined;\nage = 25;\n\nHaving these points in mind, just remember that you should avoid as much as possible to use undefined in your code. Always declare and initialize your objects. Because this gives you much more safety in your program. But in case you really need to declare an object without initializing it… the undefined keyword is the way to do it in Zig.\n\n\n1.4.3 There is no such thing as unused objects\nEvery object (being constant or variable) that you declare in Zig must be used in some way. You can give this object to a function call, as a function argument, or, you can use it in another expression to calculate the value of another object, or, you can call a method that belongs to this particular object.\nIt doesn’t matter in which way you use it. As long as you use it. If you try to break this rule, i.e., if your try to declare a object, but not use it, the zig compiler will not compile your Zig source code, and it will issue a error message warning that you have unused objects in your code.\nLet’s demonstrate this with an example. In the source code below, we declare a constant object called age. If you try to compile a simple Zig program with this line of code below, the compiler will return an error as demonstrated below:\n\nconst age = 15;\n\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\nEverytime you declare a new object in Zig, you have two choices:\n\nyou either use the value of this object;\nor you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign this object to a special character in Zig, which is the underscore (_). When you assign an object to a underscore, like in the example below, the zig compiler will automatically discard the value of this particular object.\nYou can see in the example below that, this time, the compiler did not complain about any “unused constant”, and successfully compiled our source code.\n\n// It compiles!\nconst age = 15;\n_ = age;\n\nNow, remember, everytime you assign a particular object to the underscore, this object is essentially destroyed. It’s discarded by the compiler. This means that you can no longer use this object further in your code. It doesn’t exist anymore.\nSo if you try to use the constant age in the example below, after we discarded it, you will get a loud error message from the compiler (talking about a “pointless discard”) warning you about this mistake.\n\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n\nt.zig:7:5: error: pointless discard\n    of local constant\nThis same rule applies to variable objects. Every variable object must also be used in some way. And if you assign a variable object to the underscore, this object also gets discarded, and you can no longer use this object.\n\n\n1.4.4 You must mutate every variable objects\nEvery variable object that you create in your source code must be mutated at some point. In other words, if you declare an object as a variable object, with the keyword var, and you do not change the value of this object at some point in the future, the zig compiler will detect this, and it will raise an error warning you about this mistake.\nThe concept behind this is that every object you create in Zig should be preferably a constant object, unless you really need an object whose value will change during the execution of your program.\nSo, if I try to declare a variable object such as where_i_live below, and I do not change the value of this object in some way, the zig compiler raises an error message with the phrase “variable is never mutated”.\n\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'",
+    "text": "1.4 Creating new objects in Zig (i.e., identifiers)\nLet’s talk more about objects in Zig. Readers that have past experience with other programming languages might know this concept through a different name, such as: “variable” or “identifier”. In this book, I choose to use the term “object” to refer to this concept.\nTo create a new object (or a new “identifier”) in Zig, we use the keywords const or var. These keywords specify if the object that you are creating is mutable or not. If you use const, then the object you are creating is a constant (or immutable) object, which means that once you declare this object, you can no longer change the value stored inside this object.\nOn the other side, if you use var, then, you are creating a variable (or mutable) object. You can change the value of this object as many times you want. Using the keyword var in Zig is similar to using the keywords let mut in Rust.\n\n1.4.1 Constant objects vs variable objects\nIn the code example below, we are creating a new constant object called age. This object stores a number representing the age of someone. However, this code example does not compile successfully. Because on the next line of code, we are trying to change the value of the object age to 25.\nThe zig compiler detects that we are trying to change the value of an object/identifier that is constant, and because of that, the compiler will raise a compilation error, warning us about the mistake.\n\nconst age = 24;\n// The line below is not valid!\nage = 25;\n\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\nIn contrast, if you use var, then, the object created is a variable (or “mutable”) object. With var you can declare this object in your source code, and then, change the value of this object how many times you want over future points in your source code.\nSo, using the same code example exposed above, if I change the declaration of the age object to use the var keyword, then, the program gets compiled successfully. Because now, the zig compiler detects that we are changing the value of an object that allows this behaviour, because it’s a “variable object”.\nAlso, notice in the example below that we have explicitly annotated the data type of the age object with the u8 type. The basic idea is, when we use a variable/mutable object, the Zig compiler ask for us to be more explicit with what we want, to be more clear about what our code does.\nTherefore, if you transform your object into a variable/mutable object, just remember to always annotate the type of the object explicitly in your code. Otherwise, the Zig compiler might raise a compilation error, asking you to transform your object back into a const object, or, to give your object an “explicit type”.\n\nvar age: u8 = 24;\nage = 25;\n\n\n\n1.4.2 Declaring without an initial value\nBy default, when you declare a new object in Zig, you must give it an initial value. In other words, this means that we have to declare, and, at the same time, initialize every object we create in our source code.\nOn the other hand, you can, in fact, declare a new object in your source code, and not give it an explicit value. But we need to use a special keyword for that, which is the undefined keyword.\nIt’s important to emphasize that, you should avoid using undefined as much as possible. Because when you use this keyword, you leave your object uninitialized, and, as a consequence, if for some reason, your code uses this object while it’s uninitialized, then, you will definitely have undefined behaviour and major bugs in your program.\nIn the example below, I’m declaring the age object again. But this time, I do not give it an initial value. The variable is only initialized at the second line of code, where I store the number 25 in this object.\n\nvar age: u8 = undefined;\nage = 25;\n\nHaving these points in mind, just remember that you should avoid as much as possible to use undefined in your code. Always declare and initialize your objects. Because this gives you much more safety in your program. But in case you really need to declare an object without initializing it… the undefined keyword is the way to do it in Zig.\n\n\n1.4.3 There is no such thing as unused objects\nEvery object (being constant or variable) that you declare in Zig must be used in some way. You can give this object to a function call, as a function argument, or, you can use it in another expression to calculate the value of another object, or, you can call a method that belongs to this particular object.\nIt doesn’t matter in which way you use it. As long as you use it. If you try to break this rule, i.e., if your try to declare a object, but not use it, the zig compiler will not compile your Zig source code, and it will issue a error message warning that you have unused objects in your code.\nLet’s demonstrate this with an example. In the source code below, we declare a constant object called age. If you try to compile a simple Zig program with this line of code below, the compiler will return an error as demonstrated below:\n\nconst age = 15;\n\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\nEverytime you declare a new object in Zig, you have two choices:\n\nyou either use the value of this object;\nor you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign this object to a special character in Zig, which is the underscore (_). When you assign an object to a underscore, like in the example below, the zig compiler will automatically discard the value of this particular object.\nYou can see in the example below that, this time, the compiler did not complain about any “unused constant”, and successfully compiled our source code.\n\n// It compiles!\nconst age = 15;\n_ = age;\n\nNow, remember, everytime you assign a particular object to the underscore, this object is essentially destroyed. It’s discarded by the compiler. This means that you can no longer use this object further in your code. It doesn’t exist anymore.\nSo if you try to use the constant age in the example below, after we discarded it, you will get a loud error message from the compiler (talking about a “pointless discard”) warning you about this mistake.\n\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n\nt.zig:7:5: error: pointless discard\n    of local constant\nThis same rule applies to variable objects. Every variable object must also be used in some way. And if you assign a variable object to the underscore, this object also gets discarded, and you can no longer use this object.\n\n\n1.4.4 You must mutate every variable objects\nEvery variable object that you create in your source code must be mutated at some point. In other words, if you declare an object as a variable object, with the keyword var, and you do not change the value of this object at some point in the future, the zig compiler will detect this, and it will raise an error warning you about this mistake.\nThe concept behind this is that every object you create in Zig should be preferably a constant object, unless you really need an object whose value will change during the execution of your program.\nSo, if I try to declare a variable object such as where_i_live below, and I do not change the value of this object in some way, the zig compiler raises an error message with the phrase “variable is never mutated”.\n\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]

From 7c27838a07ee6e79a76baa04f126a53dc24764cb Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Mon, 7 Apr 2025 10:48:26 -0300
Subject: [PATCH 120/151] Add more changes

---
 Chapters/01-zig-weird.qmd                      | 18 ++++++++++--------
 .../01-zig-weird/execute-results/html.json     |  4 ++--
 docs/Chapters/01-zig-weird.html                |  6 +++---
 docs/search.json                               |  2 +-
 4 files changed, 16 insertions(+), 14 deletions(-)

diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index 2b1ed767..392f6d0f 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -648,20 +648,22 @@ t.zig:10:5: error: cannot assign to constant
       ~~^~~
 ```
 
-In contrast, if you use `var`, then, the object created is a variable (or "mutable") object.
-With `var` you can declare this object in your source code, and then,
-change the value of this object how many times you want over future points
-in your source code.
+So, if you want to change the value of your object, you need to transform your immutable (or "constant")
+object into a mutable (or "variable") object. You can do that by using the `var` keyword.
+This keyword stands for "variable", and when you apply this keyword to some object, you are
+telling the Zig compiler that the value associated with this object might change at some point.
 
-So, using the same code example exposed above, if I change the declaration of the
+Thus, if we come back to the previous example, and change the declaration of the
 `age` object to use the `var` keyword, then, the program gets compiled successfully.
 Because now, the `zig` compiler detects that we are changing the value of an
 object that allows this behaviour, because it's a "variable object".
 
-Also, notice in the example below that we have explicitly annotated the data type
-of the `age` object with the `u8` type. The basic idea is, when we use a variable/mutable object,
+However, if you take a look at the example below, you will notice that we have not only declared the
+`age` object with the `var` keyword, but we also have explicitly annotated the data type
+of the `age` object with the `u8` type this time. The basic idea is, when we use a variable/mutable object,
 the Zig compiler ask for us to be more explicit with what we want, to be more clear
-about what our code does.
+about what our code does. This translates into being more explicit about the data types that we want
+to use in our objects.
 
 Therefore, if you transform your object into a variable/mutable object, just remember to always
 annotate the type of the object explicitly in your code. Otherwise, the Zig compiler might raise
diff --git a/_freeze/Chapters/01-zig-weird/execute-results/html.json b/_freeze/Chapters/01-zig-weird/execute-results/html.json
index bf9024d1..8cfa1d22 100644
--- a/_freeze/Chapters/01-zig-weird/execute-results/html.json
+++ b/_freeze/Chapters/01-zig-weird/execute-results/html.json
@@ -1,8 +1,8 @@
 {
-  "hash": "7e77940b6c0b71d5a70d87e19225e353",
+  "hash": "a69e849b0a1064ab89848935f7b05538",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\n\nlanguage, it's still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. Sometimes, they really make it hard to debug\n\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscure the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that gets compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e., where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contains Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nWe can use this build system to write small scripts in Zig,\nwhich describe the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e., creating new objects)\nare made in Zig. You can create a new object in Zig by using the syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). In @sec-assignments we talk more about objects in general.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that in @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIt's worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt's like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portable C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nIn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e., the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. If you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith an \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, on Windows, operations like accessing the `stdout` (or opening a file) depend on\nresources that are available only at *runtime* (you will learn more about compile-time versus runtime\nin @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerges from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword in @sec-comptime.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation in a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues\n\n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described in @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig later in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig?\nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar to our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentation.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It's a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (on YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e., identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nIn contrast, if you use `var`, then, the object created is a variable (or \"mutable\") object.\nWith `var` you can declare this object in your source code, and then,\nchange the value of this object how many times you want over future points\nin your source code.\n\nSo, using the same code example exposed above, if I change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it's a \"variable object\".\n\nAlso, notice in the example below that we have explicitly annotated the data type\nof the `age` object with the `u8` type. The basic idea is, when we use a variable/mutable object,\nthe Zig compiler ask for us to be more explicit with what we want, to be more clear\nabout what our code does.\n\nTherefore, if you transform your object into a variable/mutable object, just remember to always\nannotate the type of the object explicitly in your code. Otherwise, the Zig compiler might raise\na compilation error, asking you to transform your object back into a `const` object, or,\nto give your object an \"explicit type\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIt's important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code uses this object while it's uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object.\n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e., if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to a special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It's discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also gets discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e., the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\nIt's worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it's a slice that\naccesses all elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" in @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth in @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially in @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned in @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e., the start and the end of this range)\nis known at compile-time, the slice object that gets created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nin @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that gets created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e., a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can\ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n```\n:::\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat gets created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, the `slice` object have a runtime known range, because the end index of the range\nis not known at compile time. In other words, the size of the array at `buffer` is not known\nat compile time. When we execute this program, the size of the array might be 10, or, it might be 12\ndepending on where we execute it. Therefore, we don't know at compile time if\nthe slice object have a range of size 10, or, a range of size 12.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e., a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e., similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented in @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e., `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIt's worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e., a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e., the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause it's much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e., if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it's a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIt's important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig in @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers in @sec-root-file and especially in @sec-assignments.\n- How strings work in Zig in @sec-zig-strings.\n- How to use arrays and slices in @sec-arrays.\n- How to import functionality from other Zig modules in @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* in @sec-structs-and-oop.\n- Basic control flow syntax in @sec-zig-control-flow.\n- Enums in @sec-enum;\n- Pointers and Optionals in @sec-pointer;\n- Error handling with `try` and `catch` in @sec-error-handling;\n- Unit tests in @sec-unittests;\n- Vectors in @sec-vectors-simd;\n- Build System in @sec-build-system;\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\n\nlanguage, it's still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. Sometimes, they really make it hard to debug\n\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscure the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that gets compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e., where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contains Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nWe can use this build system to write small scripts in Zig,\nwhich describe the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e., creating new objects)\nare made in Zig. You can create a new object in Zig by using the syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). In @sec-assignments we talk more about objects in general.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that in @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIt's worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt's like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portable C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nIn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e., the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. If you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith an \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, on Windows, operations like accessing the `stdout` (or opening a file) depend on\nresources that are available only at *runtime* (you will learn more about compile-time versus runtime\nin @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerges from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword in @sec-comptime.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation in a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues\n\n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described in @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig later in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig?\nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar to our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentation.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It's a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (on YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e., identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nSo, if you want to change the value of your object, you need to transform your immutable (or \"constant\")\nobject into a mutable (or \"variable\") object. You can do that by using the `var` keyword.\nThis keyword stands for \"variable\", and when you apply this keyword to some object, you are\ntelling the Zig compiler that the value associated with this object might change at some point.\n\nThus, if we come back to the previous example, and change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it's a \"variable object\".\n\nHowever, if you take a look at the example below, you will notice that we have not only declared the\n`age` object with the `var` keyword, but we also have explicitly annotated the data type\nof the `age` object with the `u8` type this time. The basic idea is, when we use a variable/mutable object,\nthe Zig compiler ask for us to be more explicit with what we want, to be more clear\nabout what our code does. This translates into being more explicit about the data types that we want\nto use in our objects.\n\nTherefore, if you transform your object into a variable/mutable object, just remember to always\nannotate the type of the object explicitly in your code. Otherwise, the Zig compiler might raise\na compilation error, asking you to transform your object back into a `const` object, or,\nto give your object an \"explicit type\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIt's important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code uses this object while it's uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object.\n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e., if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to a special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It's discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also gets discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e., the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\nIt's worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it's a slice that\naccesses all elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" in @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth in @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially in @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned in @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e., the start and the end of this range)\nis known at compile-time, the slice object that gets created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nin @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that gets created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e., a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can\ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n```\n:::\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat gets created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, the `slice` object have a runtime known range, because the end index of the range\nis not known at compile time. In other words, the size of the array at `buffer` is not known\nat compile time. When we execute this program, the size of the array might be 10, or, it might be 12\ndepending on where we execute it. Therefore, we don't know at compile time if\nthe slice object have a range of size 10, or, a range of size 12.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e., a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e., similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented in @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e., `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIt's worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e., a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e., the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause it's much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e., if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it's a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIt's important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig in @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers in @sec-root-file and especially in @sec-assignments.\n- How strings work in Zig in @sec-zig-strings.\n- How to use arrays and slices in @sec-arrays.\n- How to import functionality from other Zig modules in @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* in @sec-structs-and-oop.\n- Basic control flow syntax in @sec-zig-control-flow.\n- Enums in @sec-enum;\n- Pointers and Optionals in @sec-pointer;\n- Error handling with `try` and `catch` in @sec-error-handling;\n- Unit tests in @sec-unittests;\n- Vectors in @sec-vectors-simd;\n- Build System in @sec-build-system;\n",
     "supporting": [
       "01-zig-weird_files"
     ],
diff --git a/docs/Chapters/01-zig-weird.html b/docs/Chapters/01-zig-weird.html
index 4b7fac7d..354d6f86 100644
--- a/docs/Chapters/01-zig-weird.html
+++ b/docs/Chapters/01-zig-weird.html
@@ -580,9 +580,9 @@ <h3 data-number="1.4.1" class="anchored" data-anchor-id="constant-objects-vs-var
 <pre><code>t.zig:10:5: error: cannot assign to constant
     age = 25;
       ~~^~~</code></pre>
-<p>In contrast, if you use <code>var</code>, then, the object created is a variable (or “mutable”) object. With <code>var</code> you can declare this object in your source code, and then, change the value of this object how many times you want over future points in your source code.</p>
-<p>So, using the same code example exposed above, if I change the declaration of the <code>age</code> object to use the <code>var</code> keyword, then, the program gets compiled successfully. Because now, the <code>zig</code> compiler detects that we are changing the value of an object that allows this behaviour, because it’s a “variable object”.</p>
-<p>Also, notice in the example below that we have explicitly annotated the data type of the <code>age</code> object with the <code>u8</code> type. The basic idea is, when we use a variable/mutable object, the Zig compiler ask for us to be more explicit with what we want, to be more clear about what our code does.</p>
+<p>So, if you want to change the value of your object, you need to transform your immutable (or “constant”) object into a mutable (or “variable”) object. You can do that by using the <code>var</code> keyword. This keyword stands for “variable”, and when you apply this keyword to some object, you are telling the Zig compiler that the value associated with this object might change at some point.</p>
+<p>Thus, if we come back to the previous example, and change the declaration of the <code>age</code> object to use the <code>var</code> keyword, then, the program gets compiled successfully. Because now, the <code>zig</code> compiler detects that we are changing the value of an object that allows this behaviour, because it’s a “variable object”.</p>
+<p>However, if you take a look at the example below, you will notice that we have not only declared the <code>age</code> object with the <code>var</code> keyword, but we also have explicitly annotated the data type of the <code>age</code> object with the <code>u8</code> type this time. The basic idea is, when we use a variable/mutable object, the Zig compiler ask for us to be more explicit with what we want, to be more clear about what our code does. This translates into being more explicit about the data types that we want to use in our objects.</p>
 <p>Therefore, if you transform your object into a variable/mutable object, just remember to always annotate the type of the object explicitly in your code. Otherwise, the Zig compiler might raise a compilation error, asking you to transform your object back into a <code>const</code> object, or, to give your object an “explicit type”.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb23"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb23-1"><a href="#cb23-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> age: <span class="dt">u8</span> = <span class="dv">24</span>;</span>
diff --git a/docs/search.json b/docs/search.json
index 571402f4..6640f23d 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -144,7 +144,7 @@
     "href": "Chapters/01-zig-weird.html#sec-assignments",
     "title": "1  Introducing Zig",
     "section": "1.4 Creating new objects in Zig (i.e., identifiers)",
-    "text": "1.4 Creating new objects in Zig (i.e., identifiers)\nLet’s talk more about objects in Zig. Readers that have past experience with other programming languages might know this concept through a different name, such as: “variable” or “identifier”. In this book, I choose to use the term “object” to refer to this concept.\nTo create a new object (or a new “identifier”) in Zig, we use the keywords const or var. These keywords specify if the object that you are creating is mutable or not. If you use const, then the object you are creating is a constant (or immutable) object, which means that once you declare this object, you can no longer change the value stored inside this object.\nOn the other side, if you use var, then, you are creating a variable (or mutable) object. You can change the value of this object as many times you want. Using the keyword var in Zig is similar to using the keywords let mut in Rust.\n\n1.4.1 Constant objects vs variable objects\nIn the code example below, we are creating a new constant object called age. This object stores a number representing the age of someone. However, this code example does not compile successfully. Because on the next line of code, we are trying to change the value of the object age to 25.\nThe zig compiler detects that we are trying to change the value of an object/identifier that is constant, and because of that, the compiler will raise a compilation error, warning us about the mistake.\n\nconst age = 24;\n// The line below is not valid!\nage = 25;\n\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\nIn contrast, if you use var, then, the object created is a variable (or “mutable”) object. With var you can declare this object in your source code, and then, change the value of this object how many times you want over future points in your source code.\nSo, using the same code example exposed above, if I change the declaration of the age object to use the var keyword, then, the program gets compiled successfully. Because now, the zig compiler detects that we are changing the value of an object that allows this behaviour, because it’s a “variable object”.\nAlso, notice in the example below that we have explicitly annotated the data type of the age object with the u8 type. The basic idea is, when we use a variable/mutable object, the Zig compiler ask for us to be more explicit with what we want, to be more clear about what our code does.\nTherefore, if you transform your object into a variable/mutable object, just remember to always annotate the type of the object explicitly in your code. Otherwise, the Zig compiler might raise a compilation error, asking you to transform your object back into a const object, or, to give your object an “explicit type”.\n\nvar age: u8 = 24;\nage = 25;\n\n\n\n1.4.2 Declaring without an initial value\nBy default, when you declare a new object in Zig, you must give it an initial value. In other words, this means that we have to declare, and, at the same time, initialize every object we create in our source code.\nOn the other hand, you can, in fact, declare a new object in your source code, and not give it an explicit value. But we need to use a special keyword for that, which is the undefined keyword.\nIt’s important to emphasize that, you should avoid using undefined as much as possible. Because when you use this keyword, you leave your object uninitialized, and, as a consequence, if for some reason, your code uses this object while it’s uninitialized, then, you will definitely have undefined behaviour and major bugs in your program.\nIn the example below, I’m declaring the age object again. But this time, I do not give it an initial value. The variable is only initialized at the second line of code, where I store the number 25 in this object.\n\nvar age: u8 = undefined;\nage = 25;\n\nHaving these points in mind, just remember that you should avoid as much as possible to use undefined in your code. Always declare and initialize your objects. Because this gives you much more safety in your program. But in case you really need to declare an object without initializing it… the undefined keyword is the way to do it in Zig.\n\n\n1.4.3 There is no such thing as unused objects\nEvery object (being constant or variable) that you declare in Zig must be used in some way. You can give this object to a function call, as a function argument, or, you can use it in another expression to calculate the value of another object, or, you can call a method that belongs to this particular object.\nIt doesn’t matter in which way you use it. As long as you use it. If you try to break this rule, i.e., if your try to declare a object, but not use it, the zig compiler will not compile your Zig source code, and it will issue a error message warning that you have unused objects in your code.\nLet’s demonstrate this with an example. In the source code below, we declare a constant object called age. If you try to compile a simple Zig program with this line of code below, the compiler will return an error as demonstrated below:\n\nconst age = 15;\n\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\nEverytime you declare a new object in Zig, you have two choices:\n\nyou either use the value of this object;\nor you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign this object to a special character in Zig, which is the underscore (_). When you assign an object to a underscore, like in the example below, the zig compiler will automatically discard the value of this particular object.\nYou can see in the example below that, this time, the compiler did not complain about any “unused constant”, and successfully compiled our source code.\n\n// It compiles!\nconst age = 15;\n_ = age;\n\nNow, remember, everytime you assign a particular object to the underscore, this object is essentially destroyed. It’s discarded by the compiler. This means that you can no longer use this object further in your code. It doesn’t exist anymore.\nSo if you try to use the constant age in the example below, after we discarded it, you will get a loud error message from the compiler (talking about a “pointless discard”) warning you about this mistake.\n\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n\nt.zig:7:5: error: pointless discard\n    of local constant\nThis same rule applies to variable objects. Every variable object must also be used in some way. And if you assign a variable object to the underscore, this object also gets discarded, and you can no longer use this object.\n\n\n1.4.4 You must mutate every variable objects\nEvery variable object that you create in your source code must be mutated at some point. In other words, if you declare an object as a variable object, with the keyword var, and you do not change the value of this object at some point in the future, the zig compiler will detect this, and it will raise an error warning you about this mistake.\nThe concept behind this is that every object you create in Zig should be preferably a constant object, unless you really need an object whose value will change during the execution of your program.\nSo, if I try to declare a variable object such as where_i_live below, and I do not change the value of this object in some way, the zig compiler raises an error message with the phrase “variable is never mutated”.\n\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'",
+    "text": "1.4 Creating new objects in Zig (i.e., identifiers)\nLet’s talk more about objects in Zig. Readers that have past experience with other programming languages might know this concept through a different name, such as: “variable” or “identifier”. In this book, I choose to use the term “object” to refer to this concept.\nTo create a new object (or a new “identifier”) in Zig, we use the keywords const or var. These keywords specify if the object that you are creating is mutable or not. If you use const, then the object you are creating is a constant (or immutable) object, which means that once you declare this object, you can no longer change the value stored inside this object.\nOn the other side, if you use var, then, you are creating a variable (or mutable) object. You can change the value of this object as many times you want. Using the keyword var in Zig is similar to using the keywords let mut in Rust.\n\n1.4.1 Constant objects vs variable objects\nIn the code example below, we are creating a new constant object called age. This object stores a number representing the age of someone. However, this code example does not compile successfully. Because on the next line of code, we are trying to change the value of the object age to 25.\nThe zig compiler detects that we are trying to change the value of an object/identifier that is constant, and because of that, the compiler will raise a compilation error, warning us about the mistake.\n\nconst age = 24;\n// The line below is not valid!\nage = 25;\n\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\nSo, if you want to change the value of your object, you need to transform your immutable (or “constant”) object into a mutable (or “variable”) object. You can do that by using the var keyword. This keyword stands for “variable”, and when you apply this keyword to some object, you are telling the Zig compiler that the value associated with this object might change at some point.\nThus, if we come back to the previous example, and change the declaration of the age object to use the var keyword, then, the program gets compiled successfully. Because now, the zig compiler detects that we are changing the value of an object that allows this behaviour, because it’s a “variable object”.\nHowever, if you take a look at the example below, you will notice that we have not only declared the age object with the var keyword, but we also have explicitly annotated the data type of the age object with the u8 type this time. The basic idea is, when we use a variable/mutable object, the Zig compiler ask for us to be more explicit with what we want, to be more clear about what our code does. This translates into being more explicit about the data types that we want to use in our objects.\nTherefore, if you transform your object into a variable/mutable object, just remember to always annotate the type of the object explicitly in your code. Otherwise, the Zig compiler might raise a compilation error, asking you to transform your object back into a const object, or, to give your object an “explicit type”.\n\nvar age: u8 = 24;\nage = 25;\n\n\n\n1.4.2 Declaring without an initial value\nBy default, when you declare a new object in Zig, you must give it an initial value. In other words, this means that we have to declare, and, at the same time, initialize every object we create in our source code.\nOn the other hand, you can, in fact, declare a new object in your source code, and not give it an explicit value. But we need to use a special keyword for that, which is the undefined keyword.\nIt’s important to emphasize that, you should avoid using undefined as much as possible. Because when you use this keyword, you leave your object uninitialized, and, as a consequence, if for some reason, your code uses this object while it’s uninitialized, then, you will definitely have undefined behaviour and major bugs in your program.\nIn the example below, I’m declaring the age object again. But this time, I do not give it an initial value. The variable is only initialized at the second line of code, where I store the number 25 in this object.\n\nvar age: u8 = undefined;\nage = 25;\n\nHaving these points in mind, just remember that you should avoid as much as possible to use undefined in your code. Always declare and initialize your objects. Because this gives you much more safety in your program. But in case you really need to declare an object without initializing it… the undefined keyword is the way to do it in Zig.\n\n\n1.4.3 There is no such thing as unused objects\nEvery object (being constant or variable) that you declare in Zig must be used in some way. You can give this object to a function call, as a function argument, or, you can use it in another expression to calculate the value of another object, or, you can call a method that belongs to this particular object.\nIt doesn’t matter in which way you use it. As long as you use it. If you try to break this rule, i.e., if your try to declare a object, but not use it, the zig compiler will not compile your Zig source code, and it will issue a error message warning that you have unused objects in your code.\nLet’s demonstrate this with an example. In the source code below, we declare a constant object called age. If you try to compile a simple Zig program with this line of code below, the compiler will return an error as demonstrated below:\n\nconst age = 15;\n\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\nEverytime you declare a new object in Zig, you have two choices:\n\nyou either use the value of this object;\nor you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign this object to a special character in Zig, which is the underscore (_). When you assign an object to a underscore, like in the example below, the zig compiler will automatically discard the value of this particular object.\nYou can see in the example below that, this time, the compiler did not complain about any “unused constant”, and successfully compiled our source code.\n\n// It compiles!\nconst age = 15;\n_ = age;\n\nNow, remember, everytime you assign a particular object to the underscore, this object is essentially destroyed. It’s discarded by the compiler. This means that you can no longer use this object further in your code. It doesn’t exist anymore.\nSo if you try to use the constant age in the example below, after we discarded it, you will get a loud error message from the compiler (talking about a “pointless discard”) warning you about this mistake.\n\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n\nt.zig:7:5: error: pointless discard\n    of local constant\nThis same rule applies to variable objects. Every variable object must also be used in some way. And if you assign a variable object to the underscore, this object also gets discarded, and you can no longer use this object.\n\n\n1.4.4 You must mutate every variable objects\nEvery variable object that you create in your source code must be mutated at some point. In other words, if you declare an object as a variable object, with the keyword var, and you do not change the value of this object at some point in the future, the zig compiler will detect this, and it will raise an error warning you about this mistake.\nThe concept behind this is that every object you create in Zig should be preferably a constant object, unless you really need an object whose value will change during the execution of your program.\nSo, if I try to declare a variable object such as where_i_live below, and I do not change the value of this object in some way, the zig compiler raises an error message with the phrase “variable is never mutated”.\n\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]

From 203d3e8652148409e4681fc1c7f4527f8696e164 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Mon, 7 Apr 2025 18:57:58 -0300
Subject: [PATCH 121/151] Add fix for base64 decode length

---
 Chapters/01-base64.qmd                        | 49 ++++++++++++-------
 ZigExamples/base64/base64_basic.zig           | 29 ++++++++---
 .../01-base64/execute-results/html.json       |  4 +-
 docs/Chapters/01-base64.html                  | 44 ++++++++++-------
 docs/search.json                              |  2 +-
 5 files changed, 82 insertions(+), 46 deletions(-)

diff --git a/Chapters/01-base64.qmd b/Chapters/01-base64.qmd
index d2c4f28e..023250f3 100644
--- a/Chapters/01-base64.qmd
+++ b/Chapters/01-base64.qmd
@@ -265,35 +265,38 @@ we divide it by 3, and apply a ceil operation over the result by using the
 `divCeil()` function from the Zig Standard Library. Lastly, we multiply
 the end result by 4 to get the answer we need.
 
+Also, you might have notice that, if the input length is less than 3 bytes, then, the output length of the encoder is
+always 4 bytes. This is the case for every input with less than 3 bytes, because, as I described in @sec-base64-encoder-algo,
+the algorithm always produces enough "padding-groups" in the end result, to complete the 4 bytes window.
+
 ```{zig}
 #| auto_main: false
 #| build_type: "lib"
 const std = @import("std");
 fn _calc_encode_length(input: []const u8) !usize {
     if (input.len < 3) {
-        const n_output: usize = 4;
-        return n_output;
+        return 4;
     }
-    const n_output: usize = try std.math.divCeil(
+    const n_groups: usize = try std.math.divCeil(
         usize, input.len, 3
     );
-    return n_output * 4;
+    return n_groups * 4;
 }
 ```
 
 
-Also, you might have notice that, if the input length is less than 3 bytes, then, the output length of the encoder is
-always 4 bytes. This is the case for every input with less than 3 bytes, because, as I described in @sec-base64-encoder-algo,
-the algorithm always produces enough "padding-groups" in the end result, to complete the 4 bytes window.
-
-Now, for the decoder, we just need to apply the inverse logic: for each 4 bytes in the input, 3 bytes
-will be produced in the output of the decoder. I mean, this is roughly true, because we also need to
+Now, the logic to calculate the length of the output from the decoder is a little bit more complicated. But, it is basically
+just the inverse logic that we've used for the encoder: for each 4 bytes in the input, 3 bytes
+will be produced in the output of the decoder. However, this time we need to
 take the `=` character into account, which is always ignored by the decoder, as we described in @sec-base64-decoder-algo, and,
-in @fig-base64-algo2. But we can ignore this fact for now, just to keep things simple.
+in @fig-base64-algo2.
+
+In essence, we take the length of the input and divide it by 4, then we apply a floor function on the result, then
+we multiply the result by 3, and then, we subtract from the result how much times the character `=` is found
+in the input.
 
-The function `_calc_decode_length()` exposed below summarizes this logic that we described. It's very similar
-to the function `_calc_encode_length()`. Only the division part is twisted, and also, in the special
-case where we have less than 4 bytes in the input to work on. Also notice that this time, we apply
+The function `_calc_decode_length()` exposed below summarizes this logic that we described. It's similar
+to the function `_calc_encode_length()`. Notice that the division part is twisted. Also notice that this time, we apply
 a floor operation over the output of the division, by using the `divFloor()`
 function (instead of a ceiling operation with `divCeil()`).
 
@@ -304,13 +307,23 @@ function (instead of a ceiling operation with `divCeil()`).
 const std = @import("std");
 fn _calc_decode_length(input: []const u8) !usize {
     if (input.len < 4) {
-        const n_output: usize = 3;
-        return n_output;
+        return 3;
     }
-    const n_output: usize = try std.math.divFloor(
+
+    const n_groups: usize = try std.math.divFloor(
         usize, input.len, 4
     );
-    return n_output * 3;
+    var multiple_groups: usize = n_groups * 3;
+    var i: usize = input.len - 1;
+    while (i > 0) : (i -= 1) {
+        if (input[i] == '=') {
+            multiple_groups -= 1;
+        } else {
+            break;
+        }
+    }
+
+    return multiple_groups;
 }
 ```
 
diff --git a/ZigExamples/base64/base64_basic.zig b/ZigExamples/base64/base64_basic.zig
index 13fd2302..5d395a58 100644
--- a/ZigExamples/base64/base64_basic.zig
+++ b/ZigExamples/base64/base64_basic.zig
@@ -111,8 +111,7 @@ const Base64 = struct {
 
 fn _calc_encode_length(input: []const u8) !usize {
     if (input.len < 3) {
-        const n_output: usize = 4;
-        return n_output;
+        return 4;
     }
 
     const n_output: usize = try std.math.divCeil(usize, input.len, 3);
@@ -121,11 +120,22 @@ fn _calc_encode_length(input: []const u8) !usize {
 
 fn _calc_decode_length(input: []const u8) !usize {
     if (input.len < 4) {
-        const n_output: usize = 3;
-        return n_output;
+        return 3;
     }
-    const n_output: usize = try std.math.divFloor(usize, input.len, 4);
-    return n_output * 3;
+
+    const n_groups: usize = try std.math.divFloor(usize, input.len, 4);
+    var multiple_groups: usize = n_groups * 3;
+
+    var i: usize = input.len - 1;
+    while (i > 0) : (i -= 1) {
+        if (input[i] == '=') {
+            multiple_groups -= 1;
+        } else {
+            break;
+        }
+    }
+
+    return multiple_groups;
 }
 
 pub fn main() !void {
@@ -133,11 +143,14 @@ pub fn main() !void {
     var fba = std.heap.FixedBufferAllocator.init(&memory_buffer);
     const allocator = fba.allocator();
 
-    const text = "Testing some more shit";
-    const etext = "VGVzdGluZyBzb21lIG1vcmUgc2hpdA==";
+    const text = "Testing some more stuff";
+    const etext = "VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=";
     const base64 = Base64.init();
     const encoded_text = try base64.encode(text, allocator);
     const decoded_text = try base64.decode(etext, allocator);
+
     try stdout.print("Encoded text: {s}\n", .{encoded_text});
     try stdout.print("Decoded text: {s}\n", .{decoded_text});
+    try stdout.print("Encoded length: {d}\n", .{encoded_text.len});
+    try stdout.print("Decoded length: {d}\n", .{decoded_text.len});
 }
diff --git a/_freeze/Chapters/01-base64/execute-results/html.json b/_freeze/Chapters/01-base64/execute-results/html.json
index 78be8b28..7f1a2b90 100644
--- a/_freeze/Chapters/01-base64/execute-results/html.json
+++ b/_freeze/Chapters/01-base64/execute-results/html.json
@@ -1,8 +1,8 @@
 {
-  "hash": "d5c0ae1b8bb17e483184003ae042e212",
+  "hash": "378ceb7f207e1c24d8ca75cf94cd22bf",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 1 - Building a base64 encoder/decoder {#sec-base64}\n\nAs our first small project, I want to implement a base64 encoder/decoder with you.\nBase64 is an encoding system which translates binary data to text.\nA big chunk of the web uses base64 to deliver binary data to systems\nthat can only read text data.\n\nThe most common example of a modern use case for base64 is essentially any email system,\nlike GMail, Outlook, etc. Because email systems normally use\nthe Simple Mail Transfer Protocol (SMTP), which is a web protocol\nthat supports only text data. So, if you need, for any reason, to\nsend a binary file (like for example, a PDF, or an Excel file) as\nan attachment in your email, these binary files are normally\nconverted to base64, before they are included in the SMTP message.\nSo, the base64 encoding is largely used in these email systems to include\nbinary data into the SMTP message.\n\n\n\n\n\n\n## How the base64 algorithm work?\n\nBut how exactly does the algorithm behind the base64 encoding work? Let's discuss that. First, I will\nexplain the base64 scale, which is the 64-character scale that is the basis for\nthe base64 encoding system.\n\nAfter that, I explain the algorithm behind a base64 encoder, which is the part of the algorithm that is responsible for encoding messages\ninto the base64 encoding system. Then, after that, I explain the algorithm behind a base64 decoder, which is\nthe part of the algorithm that is responsible for translating base64 messages back into their original meaning.\n\nIf you are unsure about the differences between an \"encoder\" and a \"decoder\",\ntake a look at @sec-encode-vs-decode.\n\n\n### The base64 scale {#sec-base64-scale}\n\nThe base64 encoding system is based on a scale that goes from 0 to 63 (hence the name).\nEach index in this scale is represented by a character (it's a scale of 64 characters).\nSo, in order to convert some binary data, to the base64 encoding, we need to convert each binary number to the corresponding\ncharacter in this \"scale of 64 characters\".\n\nThe base64 scale starts with all ASCII uppercase letters (A to Z) which represents\nthe first 25 indexes in this scale (0 to 25). After that, we have all ASCII lowercase letters\n(a to z), which represents the range 26 to 51 in the scale. After that, we\nhave the one digit numbers (0 to 9), which represents the indexes from 52 to 61 in the scale.\nFinally, the last two indexes in the scale (62 and 63) are represented by the characters `+` and `/`,\nrespectively.\n\nThese are the 64 characters that compose the base64 scale. The equal sign character (`=`) is not part of the scale itself,\nbut it is a special character in the base64 encoding system. This character is used solely as a suffix, to mark the end of the character sequence,\nor, to mark the end of meaningful characters in the sequence.\n\nThe bullet points below summarises the base64 scale:\n\n- range 0 to 25 is represented by: ASCII uppercase letters `-> [A-Z]`;\n- range 26 to 51 is represented by: ASCII lowercase letters `-> [a-z]`;\n- range 52 to 61 is represented by: one digit numbers `-> [0-9]`;\n- index 62 and 63 are represented by the characters `+` and `/`, respectively;\n- the character `=` represents the end of meaningful characters in the sequence;\n\n\n\n\n### Creating the scale as a lookup table {#sec-base64-table}\n\nThe best way to represent this scale in code, is to represent it as a *lookup table*.\nLookup tables are a classic strategy in computer science to speed up calculations. The basic idea\nis to replace a runtime calculation (which can take a long time to be done) with a basic array indexing\noperation.\n\nInstead of calculating the results everytime you need them, you calculate all possible results at once, and then, you store them in an array\n(which behaves lake a \"table\"). Then, every time you need to use one of the characters in the base64 scale, instead of\nusing many resources to calculate the exact character to be used, you simply retrieve this character\nfrom the array where you stored all the possible characters in the base64 scale.\nWe retrieve the character that we need directly from memory.\n\nWe can start building a Zig struct to store our base64 decoder/encoder logic.\nWe start with the `Base64` struct below. For now, we only have one single data member in this\nstruct, i.e., the member `_table`, which represents our lookup table. We also have an `init()` method,\nto create a new instance of a `Base64` object, and, a `_char_at()` method, which is a\n\"get character at index $x$\" type of function.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Base64 = struct {\n    _table: *const [64]u8,\n\n    pub fn init() Base64 {\n        const upper = \"ABCDEFGHIJKLMNOPQRSTUVWXYZ\";\n        const lower = \"abcdefghijklmnopqrstuvwxyz\";\n        const numbers_symb = \"0123456789+/\";\n        return Base64{\n            ._table = upper ++ lower ++ numbers_symb,\n        };\n    }\n\n    pub fn _char_at(self: Base64, index: usize) u8 {\n        return self._table[index];\n    }\n};\n```\n:::\n\n\n\n\n\nIn other words, the `_char_at()` method is responsible for getting the character in the lookup\ntable (i.e., the `_table` struct data member) that corresponds to a particular index in the\n\"base64 scale\". So, in the example below, we know that the character that corresponds to the\nindex 28 in the \"base64 scale\" is the character \"c\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst base64 = Base64.init();\ntry stdout.print(\n    \"Character at index 28: {c}\\n\",\n    .{base64._char_at(28)}\n);\n```\n:::\n\n\n\n\n```\nCharacter at index 28: c\n```\n\n\n\n### A base64 encoder {#sec-base64-encoder-algo}\n\nThe algorithm behind a base64 encoder usually works on a window of 3 bytes. Because each byte has\n8 bits, so, 3 bytes forms a set of $8 \\times 3 = 24$ bits. This is desirable for the base64 algorithm, because\n24 bits is divisible by 6, which forms $24 / 6 = 4$ groups of 6 bits each.\n\nTherefore, the base64 algorithm works by converting 3 bytes at a time\ninto 4 characters from the base64 scale. It keeps iterating through the input string,\n3 bytes at a time, and converting them into the base64 scale, producing 4 characters\nper iteration. It keeps iterating, and producing these \"new characters\"\nuntil it hits the end of the input string.\n\nNow you may think, what if you have a particular string that has a number of bytes\nthat is not divisible by 3 - what happens? For example, if you have a string\nthat contains only two characters/bytes, such as \"Hi\". How would the algorithm\nbehave in such situation? You find the answer in @fig-base64-algo1.\nYou can see in @fig-base64-algo1 that the string \"Hi\", when converted to base64,\nbecomes the string \"SGk=\":\n\n![The logic behind a base64 encoder](./../Figures/base64-encoder-flow.png){#fig-base64-algo1}\n\nTaking the string \"Hi\" as an example, we have 2 bytes, or, 16 bits in total. So, we lack a full byte (8 bits)\nto complete the window of 24 bits that the base64 algorithm likes to work on. The first thing that\nthe algorithm does, is to check how to divide the input bytes into groups of 6 bits.\n\nIf the algorithm notices that there is a group of 6 bits that it's not complete, meaning that, this group contains $nbits$, where $0 < nbits < 6$,\n\nthe algorithm simply adds extra zeros in this group to fill the space that it needs.\nThat is why in @fig-base64-algo1, in the third group after the 6-bit transformation,\n2 extra zeros were added to fill the gap.\n\nWhen we have a 6-bit group that is not completely full, like the third group, extra zeros\nare added to fill the gap. But what about when an entire 6-bit group is empty, or, it\nsimply doesn't exist? This is the case of the fourth 6-bit group exposed at\n@fig-base64-algo1.\n\nThis fourth group is necessary, because the algorithm works on 4 groups of 6 bits.\nBut the input string does not have enough bytes to create a fourth 6-bit group.\nEvery time this happens, where an entire group of 6 bits is empty,\nthis group becomes a \"padding group\". Every \"padding group\" is mapped to\nthe character `=` (equal sign), which represents \"null\", or, the end\nof meaningful characters in the sequence. Hence, everytime that the algorithm produces a\n\"padding group\", this group is automatically mapped to `=`.\n\nAs another example, if you give the string \"0\" as input to a base64 encoder, this string is\ntranslated into the base64 sequence \"MA==\".\nThe character \"0\" is, in binary, the sequence `00110000`[^zero-note]. So, with the 6-bit transformation\nexposed in @fig-base64-algo1, this single character would produce these two 6-bit groups: `001100`, `000000`.\nThe remaining two 6-bit groups become \"padding groups\". That is why the last\ntwo characters in the output sequence (MA==) are `==`.\n\n\n[^zero-note]: Notice that, the character \"0\" is different than the actual number 0, which is simply zero in binary.\n\n### A base64 decoder {#sec-base64-decoder-algo}\n\nThe algorithm behind a base64 decoder is essentially the inverse process of a base64 encoder.\nA base64 decoder needs to translate base64 messages back into their original meaning,\ni.e., into the original sequence of binary data.\n\nA base64 decoder usually works on a window of 4 bytes. Because it wants to convert these 4 bytes\nback into the original sequence of 3 bytes, that was converted into 4 groups of 6 bits by the\nbase64 encoder. Remember, in a base64 decoder we are essentially reverting the process made\nby the base64 encoder.\n\nEach byte in the input string (the base64 encoded string) normally contributes to re-create\ntwo different bytes in the output (the original binary data).\nIn other words, each byte that comes out of a base64 decoder is created by transforming merging two different\nbytes in the input together. You can visualize this relationship in @fig-base64-algo2:\n\n![The logic behind a base64 decoder](./../Figures/base64-decoder-flow.png){#fig-base64-algo2}\n\nThe exact transformations, or, the exact steps applied to each byte from the input to transform them\ninto the bytes of the output, are a bit tricky to visualize in a figure like this. Because of that, I have\nsummarized these transformations as \"Some bit shifting and additions ...\" in the figure. These transformations\nwill be described in depth later.\n\nBesides that, if you look again in @fig-base64-algo2, you will notice that the character `=` was completely\nignored by the algorithm. Remember, this is just a special character that marks the end of meaningful characters\nin the base64 sequence. So, every `=` character in a base64 encoded sequence should be ignored by a base64 decoder.\n\n\n## Difference between encode and decode {#sec-encode-vs-decode}\n\nIf you don't have any previous experience with base64, you might not understand the differences\nbetween \"encode\" and \"decode\". Essentially, the terms \"encode\" and \"decode\" here\nhave the exact same meaning as they have in the field of encryption (i.e., they mean the same thing as \"encode\" and \"decode\" in hashing\nalgorithms, like the MD5 algorithm).\n\nThus, \"encode\" means that we want to encode, or, in other words, we want to translate some message into\nthe base64 encoding system. We want to produce the sequence of base64 characters that represent this\noriginal message in the base64 encoding system.\n\nIn contrast, \"decode\" represents the inverse process.\nWe want to decode, or, in other words, translate a base64 message back to its original content.\nSo, in this process we get a sequence of base64 characters as input, and produce as output,\nthe binary data that is represented by this sequence of base64 characters.\n\nAny base64 library is normally composed of these two parts: 1) the encoder, which is a function that encodes\n(i.e., it converts) any sequence of binary data into a sequence of base64 characters; 2) the decoder, which is a function\nthat converts a sequence of base64 characters back into the original sequence of binary data.\n\n\n\n## Calculating the size of the output {#sec-base64-length-out}\n\nOne task that we need to do is to calculate how much space we need to reserve for the\noutput, both of the encoder and decoder. This is simple math, and can be done easily in Zig\nbecause every array has its length (its number of elements) easily accesible by consulting\nthe `.len` property of the array.\n\nFor the encoder, the logic is the following: for each 3 bytes that we find in the input,\n4 new bytes are created in the output. So, we take the number of bytes in the input, divide it\nby 3, use a ceiling function, then, we multiply the result by 4. That way, we get the total\nnumber of bytes that will be produced by the encoder in its output.\n\nThe `_calc_encode_length()` function below encapsulates this logic.\nInside this function, we take the length of the input array,\nwe divide it by 3, and apply a ceil operation over the result by using the\n`divCeil()` function from the Zig Standard Library. Lastly, we multiply\nthe end result by 4 to get the answer we need.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_encode_length(input: []const u8) !usize {\n    if (input.len < 3) {\n        const n_output: usize = 4;\n        return n_output;\n    }\n    const n_output: usize = try std.math.divCeil(\n        usize, input.len, 3\n    );\n    return n_output * 4;\n}\n```\n:::\n\n\n\n\n\nAlso, you might have notice that, if the input length is less than 3 bytes, then, the output length of the encoder is\nalways 4 bytes. This is the case for every input with less than 3 bytes, because, as I described in @sec-base64-encoder-algo,\nthe algorithm always produces enough \"padding-groups\" in the end result, to complete the 4 bytes window.\n\nNow, for the decoder, we just need to apply the inverse logic: for each 4 bytes in the input, 3 bytes\nwill be produced in the output of the decoder. I mean, this is roughly true, because we also need to\ntake the `=` character into account, which is always ignored by the decoder, as we described in @sec-base64-decoder-algo, and,\nin @fig-base64-algo2. But we can ignore this fact for now, just to keep things simple.\n\nThe function `_calc_decode_length()` exposed below summarizes this logic that we described. It's very similar\nto the function `_calc_encode_length()`. Only the division part is twisted, and also, in the special\ncase where we have less than 4 bytes in the input to work on. Also notice that this time, we apply\na floor operation over the output of the division, by using the `divFloor()`\nfunction (instead of a ceiling operation with `divCeil()`).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_decode_length(input: []const u8) !usize {\n    if (input.len < 4) {\n        const n_output: usize = 3;\n        return n_output;\n    }\n    const n_output: usize = try std.math.divFloor(\n        usize, input.len, 4\n    );\n    return n_output * 3;\n}\n```\n:::\n\n\n\n\n\n## Building the encoder logic {#sec-encoder-logic}\n\nIn this section, we can start building the logic behind the `encode()` function, which\nwill be responsible for encoding messages into the base64 encoding system.\nIf you are an anxious person, and you want to see now the full source code of the implementation\nfor this base64 encoder/decoder, you can find it at the `ZigExamples` folder in the official repository of\nthis book[^zig-base64-algo].\n\n[^zig-base64-algo]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/base64/base64_basic.zig>.\n\n\n\n### The 6-bit transformation {#sec-6bit-transf}\n\nThe 6-bit transformation presented in @fig-base64-algo1 is the core part of the base64 encoder algorithm.\nBy understanding how this transformation is made in code, the rest of the algorithm becomes much simpler\nto comprehend.\n\nIn essence, this 6-bit transformation is made with the help of bitwise operators.\nBitwise operators are essential to any type of low-level operation that is done at the bit-level. For the specific case of the base64 algorithm,\nthe operators *bif shift to the left* (`<<`), *bit shift to the right* (`>>`), and the *bitwise and* (`&`) are used. They\nare the core solution for the 6-bit transformation.\n\nThere are 3 different scenarios that we need to take into account in this transformation. First, is the perfect scenario,\nwhere we have the perfect window of 3 bytes to work on. Second, we have the scenario where we have a window of only\ntwo bytes to work with. And last, we have the scenario where we have a window of one single byte.\n\nIn each of these 3 scenarios, the 6-bit transformation works a bit differently. To make the explanation\neasier, I will use the variable `output` to refer to the bytes in the output of the base64 encoder,\nand the variable `input` to refer to the bytes in the input of the encoder.\n\n\nSo, if you have the perfect window of 3 bytes, these are steps for the 6-bit transformation:\n\n1. `output[0]` is produced by moving the bits from `input[0]` two positions to the right.\n1. `output[1]` is produced by summing two components. First, take the last two bits from `input[0]`, then, move them four positions to the left. Second, move the bits from `input[1]` four positions to the right. Sum these two components.\n1. `output[2]` is produced by summing two components. First, take the last four bits from `input[1]`, then, move them two positions to the left. Second, move the bits from `input[2]` six positions to the right. Sum these two components.\n1. `output[3]` is produced by taking the last six bits from `input[2]`.\n\n\nThis is the perfect scenario, where we have a full window of 3 bytes to work on.\nJust to make things as clear as possible, the @fig-encoder-bitshift demonstrates visually how\nthe step 2 mentioned above works. So the 2nd byte in the `output` of the encoder, is made by taking the 1st byte (dark purple)\nand the 2nd byte (orange) from the input. You can see that, at the end of the process, we get a new\nbyte that contains the last 2 bits from the 1st byte in the `input`, and the first 4 bits\nfrom the 2nd byte in the `input`.\n\n![How the 2nd byte in the output of the encoder is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input.](../Figures/base64-encoder-bit-shift.png){#fig-encoder-bitshift}\n\nOn the other hand, we must be prepared for the instances where we do not have the perfect window of 3 bytes.\nIf you have a window of 2 bytes, then, the steps 3 and 4, which produces the bytes `output[2]` and `output[3]`, change a little bit,\nand they become:\n\n- `output[2]` is produced by taking the last 4 bits from `input[1]`, then, move them two positions to the left.\n- `output[3]` is the character `'='`.\n\n\nFinally, if you have a window of a single byte, then, the steps 2 to 4, which produces the bytes `output[1]`, `output[2]` and `output[3]` change,\nbecoming:\n\n- `output[1]` is produced by taking the last two bits from `input[0]`, then, move them four positions to the left.\n- `output[2]` and `output[3]` are the character `=`.\n\n\nIf these bullet points were a bit confusing for you, you may find the @tbl-transf-6bit more intuitive.\nThis table unifies all this logic into a simple table. Notice that\nthis table also provides the exact expression in Zig that creates the corresponding\nbyte in the output.\n\n\n::: {#tbl-transf-6bit}\n\n| Number of bytes in the window | Byte index in the output | In code                                    |\n|-------------------------------|--------------------------|--------------------------------------------|\n| 3                             | 0                        | input[0] >> 2                              |\n| 3                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 3                             | 2                        | ((input[1] & 0x0f) << 2) + (input[2] >> 6) |\n| 3                             | 3                        | input[2] & 0x3f                            |\n| 2                             | 0                        | input[0] >> 2                              |\n| 2                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 2                             | 2                        | ((input[1] & 0x0f) << 2)                   |\n| 2                             | 3                        | '='                                        |\n| 1                             | 0                        | input[0] >> 2                              |\n| 1                             | 1                        | ((input[0] & 0x03) << 4)                   |\n| 1                             | 2                        | '='                                        |\n| 1                             | 3                        | '='                                        |\n\n: How the 6-bit transformation translates into code in different window settings.\n\n:::\n\n\n\n\n\n\n### Bit-shifting in Zig\n\nBit-shifting in Zig works similarly to bit-shifting in C.\nAll bitwise operators that exist in C are available in Zig.\nHere, in the base64 encoder algorithm, they are essential\nto produce the result we want.\n\nFor those who are not familiar with these operators, they are\noperators that operates at the bit-level of your values.\nThis means that these operators takes the bits that form the value\nyou have, and change them in some way. This ultimately also changes\nthe value itself, because the binary representation of this value\nchanges.\n\nWe have already seen in @fig-encoder-bitshift the effect produced by a bit-shift.\nBut let's use the first byte in the output of the base64 encoder as another example of what\nbit-shifting means. This is the easiest byte of the 4 bytes in the output\nto build. Because we only need to move the bits from the first byte in the input two positions to the right,\nwith the *bit shift to the right* (`>>`) operator.\n\nIf we take the string \"Hi\" that we used in @fig-base64-algo1 as an example, the first byte in\nthis string is \"H\", which is the sequence `01001000` in binary.\nIf we move the bits of this byte, two places to the right, we get the sequence `00010010` as result.\nThis binary sequence is the value `18` in decimal, and also, the value `0x12` in hexadecimal.\nNotice that the first 6 bits of \"H\" were moved to the end of the byte.\nWith this operation, we get the first byte of the output.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const input = \"Hi\";\n    try stdout.print(\"{d}\\n\", .{input[0] >> 2});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n18\n```\n\n\n:::\n:::\n\n\n\n\nIf you recall @fig-base64-algo1, the first byte present in the output should\nbe equivalent to the 6-bit group `010010`. Although being visually different, the\nsequences `010010` and `00010010` are semantically equal. They mean the same thing.\nThey both represent the number 18 in decimal, and the value `0x12` in hexadecimal.\n\nSo, don't take the \"6-bit group\" factor so seriously. We do not need necessarily to\nget a 6-bit sequence as result. As long as the meaning of the 8-bit sequence we get is the same\nof the 6-bit sequence, we are in the clear.\n\n\n\n### Selecting specific bits with the `&` operator\n\nIf you comeback to @sec-6bit-transf, you will see that, in order to produce\nthe second and third bytes in the output, we need to select specific\nbits from the first and second bytes in the input string. But how\ncan we do that? The answer relies on the *bitwise and* (`&`) operator.\n\nThe @fig-encoder-bitshift already showed you what effect this `&` operator\nproduces in the bits of its operands. But let's make a clear description of it.\n\nIn summary, the `&` operator performs a logical conjunction operation\nbetween the bits of its operands. In more details, the operator `&`\ncompares each bit of the first operand to the corresponding bit of the second operand.\nIf both bits are 1, the corresponding result bit is set to 1.\nOtherwise, the corresponding result bit is set to 0 [@microsoftbitwiseand].\n\nSo, if we apply this operator to the binary sequences `1000100` and `00001101`\nthe result of this operation is the binary sequence `00000100`. Because only\nat the sixth position in both binary sequences we had a 1 value. So any\nposition where we do not have both binary sequences setted to 1, we get\na 0 bit in the resulting binary sequence.\n\nWe lose information about the original bit values\nfrom both sequences in this case. Because we no longer know\nif this 0 bit in the resulting binary sequence was produced by\ncombining 0 with 0, or 1 with 0, or 0 with 1.\n\nAs an example, suppose you have the binary sequence `10010111`, which is the number 151 in decimal. How\ncan we get a new binary sequence which contains only the third and\nfourth bits of this sequence?\n\nWe just need to combine this sequence with `00110000` (is `0x30` in hexadecimal) using the `&` operator.\nNotice that only the third and fourth positions in this binary sequence is setted to 1. As a consequence, only the\nthird and fourth values of both binary sequences are potentially preserved in the output. All the remaining positions\nare setted to zero in the output sequence, which is `00010000` (is the number 16 in decimal).\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const bits = 0b10010111;\n    try stdout.print(\"{d}\\n\", .{bits & 0b00110000});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n16\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Allocating space for the output\n\nAs I described in @sec-stack, to store an object in the stack,\nthis object needs to have a known and fixed length at compile-time. This is an important\nlimitation for our base64 encoder/decoder case. Because the size of\nthe output (from both the encoder and decoder) depends\ndirectly on the size of the input.\n\nHaving this in mind, we cannot know at compile time which is\nthe size of the output for both the encoder and decoder.\nSo, if we can't know the size of the output at compile time,\nthis means that we cannot store the output for both the encoder\nand decoder in the stack.\n\nConsequently, we need to store this output on the heap,\nand, as I commented in @sec-heap, we can only\nstore objects in the heap by using allocator objects.\nSo, one the arguments to both the `encode()` and `decode()`\nfunctions, needs to be an allocator object, because\nwe know for sure that, at some point inside the body of these\nfunctions, we need to allocate space on the heap to\nstore the output of these functions.\n\nThat is why, both the `encode()` and `decode()` functions that I\npresent in this book, have an argument called `allocator`,\nwhich receives a allocator object as input, identified by\nthe type `std.mem.Allocator` from the Zig Standard Library.\n\n\n\n### Writing the `encode()` function\n\nNow that we have a basic understanding on how the bitwise operators work, and how\nexactly they help us to achieve the result we want to achieve. We can now encapsulate\nall the logic that we have described in @fig-base64-algo1 and @tbl-transf-6bit into a nice\nfunction that we can add to our `Base64` struct definition, that we started in @sec-base64-table.\n\nYou can find the `encode()` function below. Notice that the first argument of this function,\nis the `Base64` struct itself. Therefore, this argument clearly signals\nthat this function is a method from the `Base64` struct.\n\nBecause the `encode()` function itself is fairly long,\nI intentionally omitted the `Base64` struct definition in this source code,\njust for brevity reasons. So, just remember that this function is a public function (or a public method) from the\n`Base64` struct.\n\nFurthermore, this `encode()` function has two other arguments:\n\n1. `input` is the input sequence of characters that you want to encode in base64;\n1. `allocator` is an allocator object to use in the necessary memory allocations.\n\nI described everything you need to know about allocator objects in @sec-allocators.\nSo, if you are not familiar with them, I highly recommend you to comeback to\nthat section, and read it.\nBy looking at the `encode()` function, you will see that we use this\nallocator object to allocate enough memory to store the output of\nthe encoding process.\n\nThe main for loop in the function is responsible for iterating through the entire input string.\nIn every iteration, we use a `count` variable to count how many iterations we had at the\nmoment. When `count` reaches 3, then, we try to encode the 3 characters (or bytes) that we have accumulated\nin the temporary buffer object (`buf`).\n\nAfter encoding these 3 characters and storing the result in the `output` variable, we reset\nthe `count` variable to zero, and start to count again on the next iteration of the loop.\nIf the loop hits the end of the string, and, the `count` variable is less than 3, then, it means that\nthe temporary buffer contains the last 1 or 2 bytes from the input.\nThat is why we have two `if` statements after the for loop. To deal which each possible case.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn encode(self: Base64,\n              allocator: std.mem.Allocator,\n              input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n\n    const n_out = try _calc_encode_length(input);\n    var out = try allocator.alloc(u8, n_out);\n    var buf = [3]u8{ 0, 0, 0 };\n    var count: u8 = 0;\n    var iout: u64 = 0;\n\n    for (input, 0..) |_, i| {\n        buf[count] = input[i];\n        count += 1;\n        if (count == 3) {\n            out[iout] = self._char_at(buf[0] >> 2);\n            out[iout + 1] = self._char_at(\n                ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n            );\n            out[iout + 2] = self._char_at(\n                ((buf[1] & 0x0f) << 2) + (buf[2] >> 6)\n            );\n            out[iout + 3] = self._char_at(buf[2] & 0x3f);\n            iout += 4;\n            count = 0;\n        }\n    }\n\n    if (count == 1) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            (buf[0] & 0x03) << 4\n        );\n        out[iout + 2] = '=';\n        out[iout + 3] = '=';\n    }\n\n    if (count == 2) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n        );\n        out[iout + 2] = self._char_at(\n            (buf[1] & 0x0f) << 2\n        );\n        out[iout + 3] = '=';\n        iout += 4;\n    }\n\n    return out;\n}\n```\n:::\n\n\n\n\n\n\n## Building the decoder logic {#sec-decoder-logic}\n\nNow, we can focus on writing the base64 decoder logic. Remember from @fig-base64-algo2 that,\na base64 decoder does the inverse process of an encoder. So, all we need to do, is to\nwrite a `decode()` function that performs the inverse process that I exposed in @sec-encoder-logic.\n\n\n### Mapping base64 characters to their indexes {#sec-map-base64-index}\n\nOne thing that we need to do, in order to decode a base64-encoded message, is to calculate\nthe index in the base64 scale of every base64 character that we encounter in the decoder input.\n\nIn other words, the decoder receives as input, a sequence of base64 characters. We need\nto translate this sequence of characters into a sequence of indexes. These indexes\nare the index of each character in the base64 scale. This way, we get the value/byte\nthat was calculated in the 6-bit transformation step of the encoder process.\n\nThere are probably better/faster ways to calculate this, especially using a \"divide and conquer\"\ntype of strategy. But for now, I am satisfied with a simple and \"brute force\" type of strategy.\nThe `_char_index()` function below contains this strategy.\n\nWe are essentially looping through the *lookup table* with the base64 scale,\nand comparing the character we got with each character in the base64 scale.\nIf these characters match, then, we return the index of this character in the\nbase64 scale as the result.\n\nNotice that, if the input character is `'='`, the function returns the index 64, which is\n\"out of range\" in the scale. But, as I described in @sec-base64-scale,\nthe character `'='` does not belong to the base64 scale itself.\nIt's a special and meaningless character in base64.\n\nAlso notice that this `_char_index()` function is a method from our `Base64` struct,\nbecause of the `self` argument. Again, I have omitted the `Base64` struct definition in this example\nfor brevity reasons.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn _char_index(self: Base64, char: u8) u8 {\n    if (char == '=')\n        return 64;\n    var index: u8 = 0;\n    for (0..63) |i| {\n        if (self._char_at(i) == char)\n            break;\n        index += 1;\n    }\n\n    return index;\n}\n```\n:::\n\n\n\n\n\n\n### The 6-bit transformation\n\nOnce again, the core part of the algorithm is the 6-bit transformation.\nIf we understand the necessary steps to perform this transformation, the rest\nof the algorithm becomes much easier.\n\nFirst of all, before we actually go to the 6-bit transformation,\nwe need to make sure that we use `_char_index()` to convert the sequence of base64 characters\ninto a sequence of indexes. So the snippet below is important for the job that will be done.\nThe result of `_char_index()` is stored in a temporary buffer, and this temporary buffer\nis what we are going to use in the 6-bit transformation, instead of the actual `input` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (0..input.len) |i| {\n    buf[i] = self._char_index(input[i]);\n}\n```\n:::\n\n\n\n\nNow, instead of producing 4 bytes (or 4 characters) as output per each window of 3 characters in the input,\na base64 decoder produces 3 bytes (or 3 characters) as output per each window of 4 characters in the input.\nOnce again, is the inverse process.\n\nSo, the steps to produce the 3 bytes in the output are:\n\n1. `output[0]` is produced by summing two components. First, move the bits from `buf[0]` two positions to the left. Second, move the bits from `buf[1]` 4 positions to the right. Then, sum these two components.\n1. `output[1]` is produced by summing two components. First, move the bits from `buf[1]` four positions to the left. Second, move the bits from `buf[2]` 2 positions to the right. Then, sum these two components.\n1. `output[2]` is produced by summing two components. First, move the bits from `buf[2]` six positions to the left. Then, you sum the result with `buf[3]`.\n\n\nBefore we continue, let's try to visualize how these transformations make the original bytes that we had\nbefore the encoding process. First, think back to the 6-bit transformation performed by the encoder exposed in @sec-encoder-logic.\nThe first byte in the output of the encoder is produced by moving the bits in the first byte of the input two positions to the right.\n\nIf for example the first byte in the input of the encoder was the sequence `ABCDEFGH`, then, the first byte in the output of the encoder would be\n`00ABCDEF` (this sequence would be the first byte in the input of the decoder). Now, if the second byte in the input of the encoder was the sequence\n`IJKLMNOP`, then, the second byte in the encoder output would be `00GHIJKL` (as we demonstrated in @fig-encoder-bitshift).\n\nHence, if the sequences `00ABCDEF` and `00GHIJKL` are the first and second bytes, respectively, in the input of the decoder, the\n@fig-decoder-bitshift demonstrates visually how these two bytes are transformed into the first byte of the output of the decoder.\nNotice that the output byte is the sequence `ABCDEFGH`, which is the original byte from the input of the encoder.\n\n![How the 1st byte in the decoder output is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input](../Figures/base64-decoder-bit-shift.png){#fig-decoder-bitshift}\n\nThe @tbl-6bit-decode presents how the three steps described earlier translate into Zig code:\n\n\n\n::: {#tbl-6bit-decode}\n\n| Byte index in the output | In code                       |\n|--------------------------|-------------------------------|\n| 0                        | (buf[0] << 2) + (buf[1] >> 4) |\n| 1                        | (buf[1] << 4) + (buf[2] >> 2) |\n| 2                        | (buf[2] << 6) + buf[3]        |\n\n: The necessary steps for the 6-transformation in the decode process.\n\n\n:::\n\n\n\n\n\n\n\n### Writing the `decode()` function\n\nThe `decode()` function below contains the entire decoding process.\nWe first calculate the size of the output, with\n`_calc_decode_length()`, then, we allocate enough memory for this output with\nthe allocator object.\n\nThree temporary variables are created: 1) `count`, to hold the window count\nin each iteration of the for loop; 2) `iout`, to hold the current index in the output;\n3) `buf`, which is the temporary buffer that holds the base64 indexes to be\nconverted through the 6-bit transformation.\n\nThen, in each iteration of the for loop we fill the temporary buffer with the current\nwindow of bytes. When `count` hits the number 4, then, we have a full window of\nindexes in `buf` to be converted, and then, we apply the 6-bit transformation\nover the temporary buffer.\n\nNotice that we check if the indexes 2 and 3 in the temporary buffer are the number 64, which, if you recall\nfrom @sec-map-base64-index, is when the `_calc_index()` function receives a `'='` character\nas input. So, if these indexes are equal to the number 64, the `decode()` function knows\nthat it can simply ignore these indexes. They are not converted because, as I described before,\nthe character `'='` has no meaning, despite being the end of meaningful characters in the sequence.\nSo we can safely ignore them when they appear in the sequence.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn decode(self: Base64,\n          allocator: std.mem.Allocator,\n          input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n    const n_output = try _calc_decode_length(input);\n    var output = try allocator.alloc(u8, n_output);\n    var count: u8 = 0;\n    var iout: u64 = 0;\n    var buf = [4]u8{ 0, 0, 0, 0 };\n\n    for (0..input.len) |i| {\n        buf[count] = self._char_index(input[i]);\n        count += 1;\n        if (count == 4) {\n            output[iout] = (buf[0] << 2) + (buf[1] >> 4);\n            if (buf[2] != 64) {\n                output[iout + 1] = (buf[1] << 4) + (buf[2] >> 2);\n            }\n            if (buf[3] != 64) {\n                output[iout + 2] = (buf[2] << 6) + buf[3];\n            }\n            iout += 3;\n            count = 0;\n        }\n    }\n\n    return output;\n}\n```\n:::\n\n\n\n\n\n## The end result\n\nNow that we have both `decode()` and `encode()` implemented. We have a fully functioning\nbase64 encoder/decoder implemented in Zig. Here is an usage example of our\n`Base64` struct with the `encode()` and `decode()` methods that we have implemented.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar memory_buffer: [1000]u8 = undefined;\nvar fba = std.heap.FixedBufferAllocator.init(\n    &memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst text = \"Testing some more stuff\";\nconst etext = \"VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=\";\nconst base64 = Base64.init();\nconst encoded_text = try base64.encode(\n    allocator, text\n);\nconst decoded_text = try base64.decode(\n    allocator, etext\n);\ntry stdout.print(\n    \"Encoded text: {s}\\n\", .{encoded_text}\n);\ntry stdout.print(\n    \"Decoded text: {s}\\n\", .{decoded_text}\n);\n```\n:::\n\n\n\n\n```\nEncoded text: VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=\nDecoded text: Testing some more stuff\n```\n\nYou can also see the full source code at once, by visiting the official repository of this book[^repo].\nMore precisely inside the `ZigExamples` folder[^zig-base64-algo].\n\n[^repo]: <https://github.com/pedropark99/zig-book>\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 1 - Building a base64 encoder/decoder {#sec-base64}\n\nAs our first small project, I want to implement a base64 encoder/decoder with you.\nBase64 is an encoding system which translates binary data to text.\nA big chunk of the web uses base64 to deliver binary data to systems\nthat can only read text data.\n\nThe most common example of a modern use case for base64 is essentially any email system,\nlike GMail, Outlook, etc. Because email systems normally use\nthe Simple Mail Transfer Protocol (SMTP), which is a web protocol\nthat supports only text data. So, if you need, for any reason, to\nsend a binary file (like for example, a PDF, or an Excel file) as\nan attachment in your email, these binary files are normally\nconverted to base64, before they are included in the SMTP message.\nSo, the base64 encoding is largely used in these email systems to include\nbinary data into the SMTP message.\n\n\n\n\n\n\n## How the base64 algorithm work?\n\nBut how exactly does the algorithm behind the base64 encoding work? Let's discuss that. First, I will\nexplain the base64 scale, which is the 64-character scale that is the basis for\nthe base64 encoding system.\n\nAfter that, I explain the algorithm behind a base64 encoder, which is the part of the algorithm that is responsible for encoding messages\ninto the base64 encoding system. Then, after that, I explain the algorithm behind a base64 decoder, which is\nthe part of the algorithm that is responsible for translating base64 messages back into their original meaning.\n\nIf you are unsure about the differences between an \"encoder\" and a \"decoder\",\ntake a look at @sec-encode-vs-decode.\n\n\n### The base64 scale {#sec-base64-scale}\n\nThe base64 encoding system is based on a scale that goes from 0 to 63 (hence the name).\nEach index in this scale is represented by a character (it's a scale of 64 characters).\nSo, in order to convert some binary data, to the base64 encoding, we need to convert each binary number to the corresponding\ncharacter in this \"scale of 64 characters\".\n\nThe base64 scale starts with all ASCII uppercase letters (A to Z) which represents\nthe first 25 indexes in this scale (0 to 25). After that, we have all ASCII lowercase letters\n(a to z), which represents the range 26 to 51 in the scale. After that, we\nhave the one digit numbers (0 to 9), which represents the indexes from 52 to 61 in the scale.\nFinally, the last two indexes in the scale (62 and 63) are represented by the characters `+` and `/`,\nrespectively.\n\nThese are the 64 characters that compose the base64 scale. The equal sign character (`=`) is not part of the scale itself,\nbut it is a special character in the base64 encoding system. This character is used solely as a suffix, to mark the end of the character sequence,\nor, to mark the end of meaningful characters in the sequence.\n\nThe bullet points below summarises the base64 scale:\n\n- range 0 to 25 is represented by: ASCII uppercase letters `-> [A-Z]`;\n- range 26 to 51 is represented by: ASCII lowercase letters `-> [a-z]`;\n- range 52 to 61 is represented by: one digit numbers `-> [0-9]`;\n- index 62 and 63 are represented by the characters `+` and `/`, respectively;\n- the character `=` represents the end of meaningful characters in the sequence;\n\n\n\n\n### Creating the scale as a lookup table {#sec-base64-table}\n\nThe best way to represent this scale in code, is to represent it as a *lookup table*.\nLookup tables are a classic strategy in computer science to speed up calculations. The basic idea\nis to replace a runtime calculation (which can take a long time to be done) with a basic array indexing\noperation.\n\nInstead of calculating the results everytime you need them, you calculate all possible results at once, and then, you store them in an array\n(which behaves lake a \"table\"). Then, every time you need to use one of the characters in the base64 scale, instead of\nusing many resources to calculate the exact character to be used, you simply retrieve this character\nfrom the array where you stored all the possible characters in the base64 scale.\nWe retrieve the character that we need directly from memory.\n\nWe can start building a Zig struct to store our base64 decoder/encoder logic.\nWe start with the `Base64` struct below. For now, we only have one single data member in this\nstruct, i.e., the member `_table`, which represents our lookup table. We also have an `init()` method,\nto create a new instance of a `Base64` object, and, a `_char_at()` method, which is a\n\"get character at index $x$\" type of function.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Base64 = struct {\n    _table: *const [64]u8,\n\n    pub fn init() Base64 {\n        const upper = \"ABCDEFGHIJKLMNOPQRSTUVWXYZ\";\n        const lower = \"abcdefghijklmnopqrstuvwxyz\";\n        const numbers_symb = \"0123456789+/\";\n        return Base64{\n            ._table = upper ++ lower ++ numbers_symb,\n        };\n    }\n\n    pub fn _char_at(self: Base64, index: usize) u8 {\n        return self._table[index];\n    }\n};\n```\n:::\n\n\n\n\n\nIn other words, the `_char_at()` method is responsible for getting the character in the lookup\ntable (i.e., the `_table` struct data member) that corresponds to a particular index in the\n\"base64 scale\". So, in the example below, we know that the character that corresponds to the\nindex 28 in the \"base64 scale\" is the character \"c\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst base64 = Base64.init();\ntry stdout.print(\n    \"Character at index 28: {c}\\n\",\n    .{base64._char_at(28)}\n);\n```\n:::\n\n\n\n\n```\nCharacter at index 28: c\n```\n\n\n\n### A base64 encoder {#sec-base64-encoder-algo}\n\nThe algorithm behind a base64 encoder usually works on a window of 3 bytes. Because each byte has\n8 bits, so, 3 bytes forms a set of $8 \\times 3 = 24$ bits. This is desirable for the base64 algorithm, because\n24 bits is divisible by 6, which forms $24 / 6 = 4$ groups of 6 bits each.\n\nTherefore, the base64 algorithm works by converting 3 bytes at a time\ninto 4 characters from the base64 scale. It keeps iterating through the input string,\n3 bytes at a time, and converting them into the base64 scale, producing 4 characters\nper iteration. It keeps iterating, and producing these \"new characters\"\nuntil it hits the end of the input string.\n\nNow you may think, what if you have a particular string that has a number of bytes\nthat is not divisible by 3 - what happens? For example, if you have a string\nthat contains only two characters/bytes, such as \"Hi\". How would the algorithm\nbehave in such situation? You find the answer in @fig-base64-algo1.\nYou can see in @fig-base64-algo1 that the string \"Hi\", when converted to base64,\nbecomes the string \"SGk=\":\n\n![The logic behind a base64 encoder](./../Figures/base64-encoder-flow.png){#fig-base64-algo1}\n\nTaking the string \"Hi\" as an example, we have 2 bytes, or, 16 bits in total. So, we lack a full byte (8 bits)\nto complete the window of 24 bits that the base64 algorithm likes to work on. The first thing that\nthe algorithm does, is to check how to divide the input bytes into groups of 6 bits.\n\nIf the algorithm notices that there is a group of 6 bits that it's not complete, meaning that, this group contains $nbits$, where $0 < nbits < 6$,\n\nthe algorithm simply adds extra zeros in this group to fill the space that it needs.\nThat is why in @fig-base64-algo1, in the third group after the 6-bit transformation,\n2 extra zeros were added to fill the gap.\n\nWhen we have a 6-bit group that is not completely full, like the third group, extra zeros\nare added to fill the gap. But what about when an entire 6-bit group is empty, or, it\nsimply doesn't exist? This is the case of the fourth 6-bit group exposed at\n@fig-base64-algo1.\n\nThis fourth group is necessary, because the algorithm works on 4 groups of 6 bits.\nBut the input string does not have enough bytes to create a fourth 6-bit group.\nEvery time this happens, where an entire group of 6 bits is empty,\nthis group becomes a \"padding group\". Every \"padding group\" is mapped to\nthe character `=` (equal sign), which represents \"null\", or, the end\nof meaningful characters in the sequence. Hence, everytime that the algorithm produces a\n\"padding group\", this group is automatically mapped to `=`.\n\nAs another example, if you give the string \"0\" as input to a base64 encoder, this string is\ntranslated into the base64 sequence \"MA==\".\nThe character \"0\" is, in binary, the sequence `00110000`[^zero-note]. So, with the 6-bit transformation\nexposed in @fig-base64-algo1, this single character would produce these two 6-bit groups: `001100`, `000000`.\nThe remaining two 6-bit groups become \"padding groups\". That is why the last\ntwo characters in the output sequence (MA==) are `==`.\n\n\n[^zero-note]: Notice that, the character \"0\" is different than the actual number 0, which is simply zero in binary.\n\n### A base64 decoder {#sec-base64-decoder-algo}\n\nThe algorithm behind a base64 decoder is essentially the inverse process of a base64 encoder.\nA base64 decoder needs to translate base64 messages back into their original meaning,\ni.e., into the original sequence of binary data.\n\nA base64 decoder usually works on a window of 4 bytes. Because it wants to convert these 4 bytes\nback into the original sequence of 3 bytes, that was converted into 4 groups of 6 bits by the\nbase64 encoder. Remember, in a base64 decoder we are essentially reverting the process made\nby the base64 encoder.\n\nEach byte in the input string (the base64 encoded string) normally contributes to re-create\ntwo different bytes in the output (the original binary data).\nIn other words, each byte that comes out of a base64 decoder is created by transforming merging two different\nbytes in the input together. You can visualize this relationship in @fig-base64-algo2:\n\n![The logic behind a base64 decoder](./../Figures/base64-decoder-flow.png){#fig-base64-algo2}\n\nThe exact transformations, or, the exact steps applied to each byte from the input to transform them\ninto the bytes of the output, are a bit tricky to visualize in a figure like this. Because of that, I have\nsummarized these transformations as \"Some bit shifting and additions ...\" in the figure. These transformations\nwill be described in depth later.\n\nBesides that, if you look again in @fig-base64-algo2, you will notice that the character `=` was completely\nignored by the algorithm. Remember, this is just a special character that marks the end of meaningful characters\nin the base64 sequence. So, every `=` character in a base64 encoded sequence should be ignored by a base64 decoder.\n\n\n## Difference between encode and decode {#sec-encode-vs-decode}\n\nIf you don't have any previous experience with base64, you might not understand the differences\nbetween \"encode\" and \"decode\". Essentially, the terms \"encode\" and \"decode\" here\nhave the exact same meaning as they have in the field of encryption (i.e., they mean the same thing as \"encode\" and \"decode\" in hashing\nalgorithms, like the MD5 algorithm).\n\nThus, \"encode\" means that we want to encode, or, in other words, we want to translate some message into\nthe base64 encoding system. We want to produce the sequence of base64 characters that represent this\noriginal message in the base64 encoding system.\n\nIn contrast, \"decode\" represents the inverse process.\nWe want to decode, or, in other words, translate a base64 message back to its original content.\nSo, in this process we get a sequence of base64 characters as input, and produce as output,\nthe binary data that is represented by this sequence of base64 characters.\n\nAny base64 library is normally composed of these two parts: 1) the encoder, which is a function that encodes\n(i.e., it converts) any sequence of binary data into a sequence of base64 characters; 2) the decoder, which is a function\nthat converts a sequence of base64 characters back into the original sequence of binary data.\n\n\n\n## Calculating the size of the output {#sec-base64-length-out}\n\nOne task that we need to do is to calculate how much space we need to reserve for the\noutput, both of the encoder and decoder. This is simple math, and can be done easily in Zig\nbecause every array has its length (its number of elements) easily accesible by consulting\nthe `.len` property of the array.\n\nFor the encoder, the logic is the following: for each 3 bytes that we find in the input,\n4 new bytes are created in the output. So, we take the number of bytes in the input, divide it\nby 3, use a ceiling function, then, we multiply the result by 4. That way, we get the total\nnumber of bytes that will be produced by the encoder in its output.\n\nThe `_calc_encode_length()` function below encapsulates this logic.\nInside this function, we take the length of the input array,\nwe divide it by 3, and apply a ceil operation over the result by using the\n`divCeil()` function from the Zig Standard Library. Lastly, we multiply\nthe end result by 4 to get the answer we need.\n\nAlso, you might have notice that, if the input length is less than 3 bytes, then, the output length of the encoder is\nalways 4 bytes. This is the case for every input with less than 3 bytes, because, as I described in @sec-base64-encoder-algo,\nthe algorithm always produces enough \"padding-groups\" in the end result, to complete the 4 bytes window.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_encode_length(input: []const u8) !usize {\n    if (input.len < 3) {\n        return 4;\n    }\n    const n_groups: usize = try std.math.divCeil(\n        usize, input.len, 3\n    );\n    return n_groups * 4;\n}\n```\n:::\n\n\n\n\n\nNow, the logic to calculate the length of the output from the decoder is a little bit more complicated. But, it is basically\njust the inverse logic that we've used for the encoder: for each 4 bytes in the input, 3 bytes\nwill be produced in the output of the decoder. However, this time we need to\ntake the `=` character into account, which is always ignored by the decoder, as we described in @sec-base64-decoder-algo, and,\nin @fig-base64-algo2.\n\nIn essence, we take the length of the input and divide it by 4, then we apply a floor function on the result, then\nwe multiply the result by 3, and then, we subtract from the result how much times the character `=` is found\nin the input.\n\nThe function `_calc_decode_length()` exposed below summarizes this logic that we described. It's similar\nto the function `_calc_encode_length()`. Notice that the division part is twisted. Also notice that this time, we apply\na floor operation over the output of the division, by using the `divFloor()`\nfunction (instead of a ceiling operation with `divCeil()`).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_decode_length(input: []const u8) !usize {\n    if (input.len < 4) {\n        return 3;\n    }\n\n    const n_groups: usize = try std.math.divFloor(\n        usize, input.len, 4\n    );\n    var multiple_groups: usize = n_groups * 3;\n    var i: usize = input.len - 1;\n    while (i > 0) : (i -= 1) {\n        if (input[i] == '=') {\n            multiple_groups -= 1;\n        } else {\n            break;\n        }\n    }\n\n    return multiple_groups;\n}\n```\n:::\n\n\n\n\n\n## Building the encoder logic {#sec-encoder-logic}\n\nIn this section, we can start building the logic behind the `encode()` function, which\nwill be responsible for encoding messages into the base64 encoding system.\nIf you are an anxious person, and you want to see now the full source code of the implementation\nfor this base64 encoder/decoder, you can find it at the `ZigExamples` folder in the official repository of\nthis book[^zig-base64-algo].\n\n[^zig-base64-algo]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/base64/base64_basic.zig>.\n\n\n\n### The 6-bit transformation {#sec-6bit-transf}\n\nThe 6-bit transformation presented in @fig-base64-algo1 is the core part of the base64 encoder algorithm.\nBy understanding how this transformation is made in code, the rest of the algorithm becomes much simpler\nto comprehend.\n\nIn essence, this 6-bit transformation is made with the help of bitwise operators.\nBitwise operators are essential to any type of low-level operation that is done at the bit-level. For the specific case of the base64 algorithm,\nthe operators *bif shift to the left* (`<<`), *bit shift to the right* (`>>`), and the *bitwise and* (`&`) are used. They\nare the core solution for the 6-bit transformation.\n\nThere are 3 different scenarios that we need to take into account in this transformation. First, is the perfect scenario,\nwhere we have the perfect window of 3 bytes to work on. Second, we have the scenario where we have a window of only\ntwo bytes to work with. And last, we have the scenario where we have a window of one single byte.\n\nIn each of these 3 scenarios, the 6-bit transformation works a bit differently. To make the explanation\neasier, I will use the variable `output` to refer to the bytes in the output of the base64 encoder,\nand the variable `input` to refer to the bytes in the input of the encoder.\n\n\nSo, if you have the perfect window of 3 bytes, these are steps for the 6-bit transformation:\n\n1. `output[0]` is produced by moving the bits from `input[0]` two positions to the right.\n1. `output[1]` is produced by summing two components. First, take the last two bits from `input[0]`, then, move them four positions to the left. Second, move the bits from `input[1]` four positions to the right. Sum these two components.\n1. `output[2]` is produced by summing two components. First, take the last four bits from `input[1]`, then, move them two positions to the left. Second, move the bits from `input[2]` six positions to the right. Sum these two components.\n1. `output[3]` is produced by taking the last six bits from `input[2]`.\n\n\nThis is the perfect scenario, where we have a full window of 3 bytes to work on.\nJust to make things as clear as possible, the @fig-encoder-bitshift demonstrates visually how\nthe step 2 mentioned above works. So the 2nd byte in the `output` of the encoder, is made by taking the 1st byte (dark purple)\nand the 2nd byte (orange) from the input. You can see that, at the end of the process, we get a new\nbyte that contains the last 2 bits from the 1st byte in the `input`, and the first 4 bits\nfrom the 2nd byte in the `input`.\n\n![How the 2nd byte in the output of the encoder is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input.](../Figures/base64-encoder-bit-shift.png){#fig-encoder-bitshift}\n\nOn the other hand, we must be prepared for the instances where we do not have the perfect window of 3 bytes.\nIf you have a window of 2 bytes, then, the steps 3 and 4, which produces the bytes `output[2]` and `output[3]`, change a little bit,\nand they become:\n\n- `output[2]` is produced by taking the last 4 bits from `input[1]`, then, move them two positions to the left.\n- `output[3]` is the character `'='`.\n\n\nFinally, if you have a window of a single byte, then, the steps 2 to 4, which produces the bytes `output[1]`, `output[2]` and `output[3]` change,\nbecoming:\n\n- `output[1]` is produced by taking the last two bits from `input[0]`, then, move them four positions to the left.\n- `output[2]` and `output[3]` are the character `=`.\n\n\nIf these bullet points were a bit confusing for you, you may find the @tbl-transf-6bit more intuitive.\nThis table unifies all this logic into a simple table. Notice that\nthis table also provides the exact expression in Zig that creates the corresponding\nbyte in the output.\n\n\n::: {#tbl-transf-6bit}\n\n| Number of bytes in the window | Byte index in the output | In code                                    |\n|-------------------------------|--------------------------|--------------------------------------------|\n| 3                             | 0                        | input[0] >> 2                              |\n| 3                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 3                             | 2                        | ((input[1] & 0x0f) << 2) + (input[2] >> 6) |\n| 3                             | 3                        | input[2] & 0x3f                            |\n| 2                             | 0                        | input[0] >> 2                              |\n| 2                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 2                             | 2                        | ((input[1] & 0x0f) << 2)                   |\n| 2                             | 3                        | '='                                        |\n| 1                             | 0                        | input[0] >> 2                              |\n| 1                             | 1                        | ((input[0] & 0x03) << 4)                   |\n| 1                             | 2                        | '='                                        |\n| 1                             | 3                        | '='                                        |\n\n: How the 6-bit transformation translates into code in different window settings.\n\n:::\n\n\n\n\n\n\n### Bit-shifting in Zig\n\nBit-shifting in Zig works similarly to bit-shifting in C.\nAll bitwise operators that exist in C are available in Zig.\nHere, in the base64 encoder algorithm, they are essential\nto produce the result we want.\n\nFor those who are not familiar with these operators, they are\noperators that operates at the bit-level of your values.\nThis means that these operators takes the bits that form the value\nyou have, and change them in some way. This ultimately also changes\nthe value itself, because the binary representation of this value\nchanges.\n\nWe have already seen in @fig-encoder-bitshift the effect produced by a bit-shift.\nBut let's use the first byte in the output of the base64 encoder as another example of what\nbit-shifting means. This is the easiest byte of the 4 bytes in the output\nto build. Because we only need to move the bits from the first byte in the input two positions to the right,\nwith the *bit shift to the right* (`>>`) operator.\n\nIf we take the string \"Hi\" that we used in @fig-base64-algo1 as an example, the first byte in\nthis string is \"H\", which is the sequence `01001000` in binary.\nIf we move the bits of this byte, two places to the right, we get the sequence `00010010` as result.\nThis binary sequence is the value `18` in decimal, and also, the value `0x12` in hexadecimal.\nNotice that the first 6 bits of \"H\" were moved to the end of the byte.\nWith this operation, we get the first byte of the output.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const input = \"Hi\";\n    try stdout.print(\"{d}\\n\", .{input[0] >> 2});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n18\n```\n\n\n:::\n:::\n\n\n\n\nIf you recall @fig-base64-algo1, the first byte present in the output should\nbe equivalent to the 6-bit group `010010`. Although being visually different, the\nsequences `010010` and `00010010` are semantically equal. They mean the same thing.\nThey both represent the number 18 in decimal, and the value `0x12` in hexadecimal.\n\nSo, don't take the \"6-bit group\" factor so seriously. We do not need necessarily to\nget a 6-bit sequence as result. As long as the meaning of the 8-bit sequence we get is the same\nof the 6-bit sequence, we are in the clear.\n\n\n\n### Selecting specific bits with the `&` operator\n\nIf you comeback to @sec-6bit-transf, you will see that, in order to produce\nthe second and third bytes in the output, we need to select specific\nbits from the first and second bytes in the input string. But how\ncan we do that? The answer relies on the *bitwise and* (`&`) operator.\n\nThe @fig-encoder-bitshift already showed you what effect this `&` operator\nproduces in the bits of its operands. But let's make a clear description of it.\n\nIn summary, the `&` operator performs a logical conjunction operation\nbetween the bits of its operands. In more details, the operator `&`\ncompares each bit of the first operand to the corresponding bit of the second operand.\nIf both bits are 1, the corresponding result bit is set to 1.\nOtherwise, the corresponding result bit is set to 0 [@microsoftbitwiseand].\n\nSo, if we apply this operator to the binary sequences `1000100` and `00001101`\nthe result of this operation is the binary sequence `00000100`. Because only\nat the sixth position in both binary sequences we had a 1 value. So any\nposition where we do not have both binary sequences setted to 1, we get\na 0 bit in the resulting binary sequence.\n\nWe lose information about the original bit values\nfrom both sequences in this case. Because we no longer know\nif this 0 bit in the resulting binary sequence was produced by\ncombining 0 with 0, or 1 with 0, or 0 with 1.\n\nAs an example, suppose you have the binary sequence `10010111`, which is the number 151 in decimal. How\ncan we get a new binary sequence which contains only the third and\nfourth bits of this sequence?\n\nWe just need to combine this sequence with `00110000` (is `0x30` in hexadecimal) using the `&` operator.\nNotice that only the third and fourth positions in this binary sequence is setted to 1. As a consequence, only the\nthird and fourth values of both binary sequences are potentially preserved in the output. All the remaining positions\nare setted to zero in the output sequence, which is `00010000` (is the number 16 in decimal).\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const bits = 0b10010111;\n    try stdout.print(\"{d}\\n\", .{bits & 0b00110000});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n16\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Allocating space for the output\n\nAs I described in @sec-stack, to store an object in the stack,\nthis object needs to have a known and fixed length at compile-time. This is an important\nlimitation for our base64 encoder/decoder case. Because the size of\nthe output (from both the encoder and decoder) depends\ndirectly on the size of the input.\n\nHaving this in mind, we cannot know at compile time which is\nthe size of the output for both the encoder and decoder.\nSo, if we can't know the size of the output at compile time,\nthis means that we cannot store the output for both the encoder\nand decoder in the stack.\n\nConsequently, we need to store this output on the heap,\nand, as I commented in @sec-heap, we can only\nstore objects in the heap by using allocator objects.\nSo, one the arguments to both the `encode()` and `decode()`\nfunctions, needs to be an allocator object, because\nwe know for sure that, at some point inside the body of these\nfunctions, we need to allocate space on the heap to\nstore the output of these functions.\n\nThat is why, both the `encode()` and `decode()` functions that I\npresent in this book, have an argument called `allocator`,\nwhich receives a allocator object as input, identified by\nthe type `std.mem.Allocator` from the Zig Standard Library.\n\n\n\n### Writing the `encode()` function\n\nNow that we have a basic understanding on how the bitwise operators work, and how\nexactly they help us to achieve the result we want to achieve. We can now encapsulate\nall the logic that we have described in @fig-base64-algo1 and @tbl-transf-6bit into a nice\nfunction that we can add to our `Base64` struct definition, that we started in @sec-base64-table.\n\nYou can find the `encode()` function below. Notice that the first argument of this function,\nis the `Base64` struct itself. Therefore, this argument clearly signals\nthat this function is a method from the `Base64` struct.\n\nBecause the `encode()` function itself is fairly long,\nI intentionally omitted the `Base64` struct definition in this source code,\njust for brevity reasons. So, just remember that this function is a public function (or a public method) from the\n`Base64` struct.\n\nFurthermore, this `encode()` function has two other arguments:\n\n1. `input` is the input sequence of characters that you want to encode in base64;\n1. `allocator` is an allocator object to use in the necessary memory allocations.\n\nI described everything you need to know about allocator objects in @sec-allocators.\nSo, if you are not familiar with them, I highly recommend you to comeback to\nthat section, and read it.\nBy looking at the `encode()` function, you will see that we use this\nallocator object to allocate enough memory to store the output of\nthe encoding process.\n\nThe main for loop in the function is responsible for iterating through the entire input string.\nIn every iteration, we use a `count` variable to count how many iterations we had at the\nmoment. When `count` reaches 3, then, we try to encode the 3 characters (or bytes) that we have accumulated\nin the temporary buffer object (`buf`).\n\nAfter encoding these 3 characters and storing the result in the `output` variable, we reset\nthe `count` variable to zero, and start to count again on the next iteration of the loop.\nIf the loop hits the end of the string, and, the `count` variable is less than 3, then, it means that\nthe temporary buffer contains the last 1 or 2 bytes from the input.\nThat is why we have two `if` statements after the for loop. To deal which each possible case.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn encode(self: Base64,\n              allocator: std.mem.Allocator,\n              input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n\n    const n_out = try _calc_encode_length(input);\n    var out = try allocator.alloc(u8, n_out);\n    var buf = [3]u8{ 0, 0, 0 };\n    var count: u8 = 0;\n    var iout: u64 = 0;\n\n    for (input, 0..) |_, i| {\n        buf[count] = input[i];\n        count += 1;\n        if (count == 3) {\n            out[iout] = self._char_at(buf[0] >> 2);\n            out[iout + 1] = self._char_at(\n                ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n            );\n            out[iout + 2] = self._char_at(\n                ((buf[1] & 0x0f) << 2) + (buf[2] >> 6)\n            );\n            out[iout + 3] = self._char_at(buf[2] & 0x3f);\n            iout += 4;\n            count = 0;\n        }\n    }\n\n    if (count == 1) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            (buf[0] & 0x03) << 4\n        );\n        out[iout + 2] = '=';\n        out[iout + 3] = '=';\n    }\n\n    if (count == 2) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n        );\n        out[iout + 2] = self._char_at(\n            (buf[1] & 0x0f) << 2\n        );\n        out[iout + 3] = '=';\n        iout += 4;\n    }\n\n    return out;\n}\n```\n:::\n\n\n\n\n\n\n## Building the decoder logic {#sec-decoder-logic}\n\nNow, we can focus on writing the base64 decoder logic. Remember from @fig-base64-algo2 that,\na base64 decoder does the inverse process of an encoder. So, all we need to do, is to\nwrite a `decode()` function that performs the inverse process that I exposed in @sec-encoder-logic.\n\n\n### Mapping base64 characters to their indexes {#sec-map-base64-index}\n\nOne thing that we need to do, in order to decode a base64-encoded message, is to calculate\nthe index in the base64 scale of every base64 character that we encounter in the decoder input.\n\nIn other words, the decoder receives as input, a sequence of base64 characters. We need\nto translate this sequence of characters into a sequence of indexes. These indexes\nare the index of each character in the base64 scale. This way, we get the value/byte\nthat was calculated in the 6-bit transformation step of the encoder process.\n\nThere are probably better/faster ways to calculate this, especially using a \"divide and conquer\"\ntype of strategy. But for now, I am satisfied with a simple and \"brute force\" type of strategy.\nThe `_char_index()` function below contains this strategy.\n\nWe are essentially looping through the *lookup table* with the base64 scale,\nand comparing the character we got with each character in the base64 scale.\nIf these characters match, then, we return the index of this character in the\nbase64 scale as the result.\n\nNotice that, if the input character is `'='`, the function returns the index 64, which is\n\"out of range\" in the scale. But, as I described in @sec-base64-scale,\nthe character `'='` does not belong to the base64 scale itself.\nIt's a special and meaningless character in base64.\n\nAlso notice that this `_char_index()` function is a method from our `Base64` struct,\nbecause of the `self` argument. Again, I have omitted the `Base64` struct definition in this example\nfor brevity reasons.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn _char_index(self: Base64, char: u8) u8 {\n    if (char == '=')\n        return 64;\n    var index: u8 = 0;\n    for (0..63) |i| {\n        if (self._char_at(i) == char)\n            break;\n        index += 1;\n    }\n\n    return index;\n}\n```\n:::\n\n\n\n\n\n\n### The 6-bit transformation\n\nOnce again, the core part of the algorithm is the 6-bit transformation.\nIf we understand the necessary steps to perform this transformation, the rest\nof the algorithm becomes much easier.\n\nFirst of all, before we actually go to the 6-bit transformation,\nwe need to make sure that we use `_char_index()` to convert the sequence of base64 characters\ninto a sequence of indexes. So the snippet below is important for the job that will be done.\nThe result of `_char_index()` is stored in a temporary buffer, and this temporary buffer\nis what we are going to use in the 6-bit transformation, instead of the actual `input` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (0..input.len) |i| {\n    buf[i] = self._char_index(input[i]);\n}\n```\n:::\n\n\n\n\nNow, instead of producing 4 bytes (or 4 characters) as output per each window of 3 characters in the input,\na base64 decoder produces 3 bytes (or 3 characters) as output per each window of 4 characters in the input.\nOnce again, is the inverse process.\n\nSo, the steps to produce the 3 bytes in the output are:\n\n1. `output[0]` is produced by summing two components. First, move the bits from `buf[0]` two positions to the left. Second, move the bits from `buf[1]` 4 positions to the right. Then, sum these two components.\n1. `output[1]` is produced by summing two components. First, move the bits from `buf[1]` four positions to the left. Second, move the bits from `buf[2]` 2 positions to the right. Then, sum these two components.\n1. `output[2]` is produced by summing two components. First, move the bits from `buf[2]` six positions to the left. Then, you sum the result with `buf[3]`.\n\n\nBefore we continue, let's try to visualize how these transformations make the original bytes that we had\nbefore the encoding process. First, think back to the 6-bit transformation performed by the encoder exposed in @sec-encoder-logic.\nThe first byte in the output of the encoder is produced by moving the bits in the first byte of the input two positions to the right.\n\nIf for example the first byte in the input of the encoder was the sequence `ABCDEFGH`, then, the first byte in the output of the encoder would be\n`00ABCDEF` (this sequence would be the first byte in the input of the decoder). Now, if the second byte in the input of the encoder was the sequence\n`IJKLMNOP`, then, the second byte in the encoder output would be `00GHIJKL` (as we demonstrated in @fig-encoder-bitshift).\n\nHence, if the sequences `00ABCDEF` and `00GHIJKL` are the first and second bytes, respectively, in the input of the decoder, the\n@fig-decoder-bitshift demonstrates visually how these two bytes are transformed into the first byte of the output of the decoder.\nNotice that the output byte is the sequence `ABCDEFGH`, which is the original byte from the input of the encoder.\n\n![How the 1st byte in the decoder output is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input](../Figures/base64-decoder-bit-shift.png){#fig-decoder-bitshift}\n\nThe @tbl-6bit-decode presents how the three steps described earlier translate into Zig code:\n\n\n\n::: {#tbl-6bit-decode}\n\n| Byte index in the output | In code                       |\n|--------------------------|-------------------------------|\n| 0                        | (buf[0] << 2) + (buf[1] >> 4) |\n| 1                        | (buf[1] << 4) + (buf[2] >> 2) |\n| 2                        | (buf[2] << 6) + buf[3]        |\n\n: The necessary steps for the 6-transformation in the decode process.\n\n\n:::\n\n\n\n\n\n\n\n### Writing the `decode()` function\n\nThe `decode()` function below contains the entire decoding process.\nWe first calculate the size of the output, with\n`_calc_decode_length()`, then, we allocate enough memory for this output with\nthe allocator object.\n\nThree temporary variables are created: 1) `count`, to hold the window count\nin each iteration of the for loop; 2) `iout`, to hold the current index in the output;\n3) `buf`, which is the temporary buffer that holds the base64 indexes to be\nconverted through the 6-bit transformation.\n\nThen, in each iteration of the for loop we fill the temporary buffer with the current\nwindow of bytes. When `count` hits the number 4, then, we have a full window of\nindexes in `buf` to be converted, and then, we apply the 6-bit transformation\nover the temporary buffer.\n\nNotice that we check if the indexes 2 and 3 in the temporary buffer are the number 64, which, if you recall\nfrom @sec-map-base64-index, is when the `_calc_index()` function receives a `'='` character\nas input. So, if these indexes are equal to the number 64, the `decode()` function knows\nthat it can simply ignore these indexes. They are not converted because, as I described before,\nthe character `'='` has no meaning, despite being the end of meaningful characters in the sequence.\nSo we can safely ignore them when they appear in the sequence.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn decode(self: Base64,\n          allocator: std.mem.Allocator,\n          input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n    const n_output = try _calc_decode_length(input);\n    var output = try allocator.alloc(u8, n_output);\n    var count: u8 = 0;\n    var iout: u64 = 0;\n    var buf = [4]u8{ 0, 0, 0, 0 };\n\n    for (0..input.len) |i| {\n        buf[count] = self._char_index(input[i]);\n        count += 1;\n        if (count == 4) {\n            output[iout] = (buf[0] << 2) + (buf[1] >> 4);\n            if (buf[2] != 64) {\n                output[iout + 1] = (buf[1] << 4) + (buf[2] >> 2);\n            }\n            if (buf[3] != 64) {\n                output[iout + 2] = (buf[2] << 6) + buf[3];\n            }\n            iout += 3;\n            count = 0;\n        }\n    }\n\n    return output;\n}\n```\n:::\n\n\n\n\n\n## The end result\n\nNow that we have both `decode()` and `encode()` implemented. We have a fully functioning\nbase64 encoder/decoder implemented in Zig. Here is an usage example of our\n`Base64` struct with the `encode()` and `decode()` methods that we have implemented.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar memory_buffer: [1000]u8 = undefined;\nvar fba = std.heap.FixedBufferAllocator.init(\n    &memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst text = \"Testing some more stuff\";\nconst etext = \"VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=\";\nconst base64 = Base64.init();\nconst encoded_text = try base64.encode(\n    allocator, text\n);\nconst decoded_text = try base64.decode(\n    allocator, etext\n);\ntry stdout.print(\n    \"Encoded text: {s}\\n\", .{encoded_text}\n);\ntry stdout.print(\n    \"Decoded text: {s}\\n\", .{decoded_text}\n);\n```\n:::\n\n\n\n\n```\nEncoded text: VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=\nDecoded text: Testing some more stuff\n```\n\nYou can also see the full source code at once, by visiting the official repository of this book[^repo].\nMore precisely inside the `ZigExamples` folder[^zig-base64-algo].\n\n[^repo]: <https://github.com/pedropark99/zig-book>\n",
     "supporting": [
       "01-base64_files"
     ],
diff --git a/docs/Chapters/01-base64.html b/docs/Chapters/01-base64.html
index e32e01a4..131de842 100644
--- a/docs/Chapters/01-base64.html
+++ b/docs/Chapters/01-base64.html
@@ -483,34 +483,44 @@ <h2 data-number="4.3" class="anchored" data-anchor-id="sec-base64-length-out"><s
 <p>One task that we need to do is to calculate how much space we need to reserve for the output, both of the encoder and decoder. This is simple math, and can be done easily in Zig because every array has its length (its number of elements) easily accesible by consulting the <code>.len</code> property of the array.</p>
 <p>For the encoder, the logic is the following: for each 3 bytes that we find in the input, 4 new bytes are created in the output. So, we take the number of bytes in the input, divide it by 3, use a ceiling function, then, we multiply the result by 4. That way, we get the total number of bytes that will be produced by the encoder in its output.</p>
 <p>The <code>_calc_encode_length()</code> function below encapsulates this logic. Inside this function, we take the length of the input array, we divide it by 3, and apply a ceil operation over the result by using the <code>divCeil()</code> function from the Zig Standard Library. Lastly, we multiply the end result by 4 to get the answer we need.</p>
+<p>Also, you might have notice that, if the input length is less than 3 bytes, then, the output length of the encoder is always 4 bytes. This is the case for every input with less than 3 bytes, because, as I described in <a href="#sec-base64-encoder-algo" class="quarto-xref"><span>Section 4.1.3</span></a>, the algorithm always produces enough “padding-groups” in the end result, to complete the 4 bytes window.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb4"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> _calc_encode_length(input: []<span class="kw">const</span> <span class="dt">u8</span>) !<span class="dt">usize</span> <span class="op">{</span></span>
 <span id="cb4-3"><a href="#cb4-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> (input.len &lt; <span class="dv">3</span>) <span class="op">{</span></span>
-<span id="cb4-4"><a href="#cb4-4" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> n_output: <span class="dt">usize</span> = <span class="dv">4</span>;</span>
-<span id="cb4-5"><a href="#cb4-5" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> n_output;</span>
-<span id="cb4-6"><a href="#cb4-6" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb4-7"><a href="#cb4-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> n_output: <span class="dt">usize</span> = <span class="kw">try</span> std.math.divCeil(</span>
-<span id="cb4-8"><a href="#cb4-8" aria-hidden="true" tabindex="-1"></a>        <span class="dt">usize</span>, input.len, <span class="dv">3</span></span>
-<span id="cb4-9"><a href="#cb4-9" aria-hidden="true" tabindex="-1"></a>    );</span>
-<span id="cb4-10"><a href="#cb4-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> n_output * <span class="dv">4</span>;</span>
-<span id="cb4-11"><a href="#cb4-11" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<span id="cb4-4"><a href="#cb4-4" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> <span class="dv">4</span>;</span>
+<span id="cb4-5"><a href="#cb4-5" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb4-6"><a href="#cb4-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> n_groups: <span class="dt">usize</span> = <span class="kw">try</span> std.math.divCeil(</span>
+<span id="cb4-7"><a href="#cb4-7" aria-hidden="true" tabindex="-1"></a>        <span class="dt">usize</span>, input.len, <span class="dv">3</span></span>
+<span id="cb4-8"><a href="#cb4-8" aria-hidden="true" tabindex="-1"></a>    );</span>
+<span id="cb4-9"><a href="#cb4-9" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> n_groups * <span class="dv">4</span>;</span>
+<span id="cb4-10"><a href="#cb4-10" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>Also, you might have notice that, if the input length is less than 3 bytes, then, the output length of the encoder is always 4 bytes. This is the case for every input with less than 3 bytes, because, as I described in <a href="#sec-base64-encoder-algo" class="quarto-xref"><span>Section 4.1.3</span></a>, the algorithm always produces enough “padding-groups” in the end result, to complete the 4 bytes window.</p>
-<p>Now, for the decoder, we just need to apply the inverse logic: for each 4 bytes in the input, 3 bytes will be produced in the output of the decoder. I mean, this is roughly true, because we also need to take the <code>=</code> character into account, which is always ignored by the decoder, as we described in <a href="#sec-base64-decoder-algo" class="quarto-xref"><span>Section 4.1.4</span></a>, and, in <a href="#fig-base64-algo2" class="quarto-xref">Figure&nbsp;<span>4.2</span></a>. But we can ignore this fact for now, just to keep things simple.</p>
-<p>The function <code>_calc_decode_length()</code> exposed below summarizes this logic that we described. It’s very similar to the function <code>_calc_encode_length()</code>. Only the division part is twisted, and also, in the special case where we have less than 4 bytes in the input to work on. Also notice that this time, we apply a floor operation over the output of the division, by using the <code>divFloor()</code> function (instead of a ceiling operation with <code>divCeil()</code>).</p>
+<p>Now, the logic to calculate the length of the output from the decoder is a little bit more complicated. But, it is basically just the inverse logic that we’ve used for the encoder: for each 4 bytes in the input, 3 bytes will be produced in the output of the decoder. However, this time we need to take the <code>=</code> character into account, which is always ignored by the decoder, as we described in <a href="#sec-base64-decoder-algo" class="quarto-xref"><span>Section 4.1.4</span></a>, and, in <a href="#fig-base64-algo2" class="quarto-xref">Figure&nbsp;<span>4.2</span></a>.</p>
+<p>In essence, we take the length of the input and divide it by 4, then we apply a floor function on the result, then we multiply the result by 3, and then, we subtract from the result how much times the character <code>=</code> is found in the input.</p>
+<p>The function <code>_calc_decode_length()</code> exposed below summarizes this logic that we described. It’s similar to the function <code>_calc_encode_length()</code>. Notice that the division part is twisted. Also notice that this time, we apply a floor operation over the output of the division, by using the <code>divFloor()</code> function (instead of a ceiling operation with <code>divCeil()</code>).</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb5"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> _calc_decode_length(input: []<span class="kw">const</span> <span class="dt">u8</span>) !<span class="dt">usize</span> <span class="op">{</span></span>
 <span id="cb5-3"><a href="#cb5-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> (input.len &lt; <span class="dv">4</span>) <span class="op">{</span></span>
-<span id="cb5-4"><a href="#cb5-4" aria-hidden="true" tabindex="-1"></a>        <span class="kw">const</span> n_output: <span class="dt">usize</span> = <span class="dv">3</span>;</span>
-<span id="cb5-5"><a href="#cb5-5" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> n_output;</span>
-<span id="cb5-6"><a href="#cb5-6" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb5-7"><a href="#cb5-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> n_output: <span class="dt">usize</span> = <span class="kw">try</span> std.math.divFloor(</span>
+<span id="cb5-4"><a href="#cb5-4" aria-hidden="true" tabindex="-1"></a>        <span class="kw">return</span> <span class="dv">3</span>;</span>
+<span id="cb5-5"><a href="#cb5-5" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb5-6"><a href="#cb5-6" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb5-7"><a href="#cb5-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> n_groups: <span class="dt">usize</span> = <span class="kw">try</span> std.math.divFloor(</span>
 <span id="cb5-8"><a href="#cb5-8" aria-hidden="true" tabindex="-1"></a>        <span class="dt">usize</span>, input.len, <span class="dv">4</span></span>
 <span id="cb5-9"><a href="#cb5-9" aria-hidden="true" tabindex="-1"></a>    );</span>
-<span id="cb5-10"><a href="#cb5-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> n_output * <span class="dv">3</span>;</span>
-<span id="cb5-11"><a href="#cb5-11" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<span id="cb5-10"><a href="#cb5-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> multiple_groups: <span class="dt">usize</span> = n_groups * <span class="dv">3</span>;</span>
+<span id="cb5-11"><a href="#cb5-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> i: <span class="dt">usize</span> = input.len - <span class="dv">1</span>;</span>
+<span id="cb5-12"><a href="#cb5-12" aria-hidden="true" tabindex="-1"></a>    <span class="kw">while</span> (i &gt; <span class="dv">0</span>) : (i -= <span class="dv">1</span>) <span class="op">{</span></span>
+<span id="cb5-13"><a href="#cb5-13" aria-hidden="true" tabindex="-1"></a>        <span class="kw">if</span> (input[i] == <span class="ch">'='</span>) <span class="op">{</span></span>
+<span id="cb5-14"><a href="#cb5-14" aria-hidden="true" tabindex="-1"></a>            multiple_groups -= <span class="dv">1</span>;</span>
+<span id="cb5-15"><a href="#cb5-15" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span> <span class="kw">else</span> <span class="op">{</span></span>
+<span id="cb5-16"><a href="#cb5-16" aria-hidden="true" tabindex="-1"></a>            <span class="kw">break</span>;</span>
+<span id="cb5-17"><a href="#cb5-17" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span></span>
+<span id="cb5-18"><a href="#cb5-18" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb5-19"><a href="#cb5-19" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb5-20"><a href="#cb5-20" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> multiple_groups;</span>
+<span id="cb5-21"><a href="#cb5-21" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
 <section id="sec-encoder-logic" class="level2" data-number="4.4">
diff --git a/docs/search.json b/docs/search.json
index 6640f23d..5a611b6c 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -384,7 +384,7 @@
     "href": "Chapters/01-base64.html#sec-base64-length-out",
     "title": "4  Project 1 - Building a base64 encoder/decoder",
     "section": "4.3 Calculating the size of the output",
-    "text": "4.3 Calculating the size of the output\nOne task that we need to do is to calculate how much space we need to reserve for the output, both of the encoder and decoder. This is simple math, and can be done easily in Zig because every array has its length (its number of elements) easily accesible by consulting the .len property of the array.\nFor the encoder, the logic is the following: for each 3 bytes that we find in the input, 4 new bytes are created in the output. So, we take the number of bytes in the input, divide it by 3, use a ceiling function, then, we multiply the result by 4. That way, we get the total number of bytes that will be produced by the encoder in its output.\nThe _calc_encode_length() function below encapsulates this logic. Inside this function, we take the length of the input array, we divide it by 3, and apply a ceil operation over the result by using the divCeil() function from the Zig Standard Library. Lastly, we multiply the end result by 4 to get the answer we need.\n\nconst std = @import(\"std\");\nfn _calc_encode_length(input: []const u8) !usize {\n    if (input.len &lt; 3) {\n        const n_output: usize = 4;\n        return n_output;\n    }\n    const n_output: usize = try std.math.divCeil(\n        usize, input.len, 3\n    );\n    return n_output * 4;\n}\n\nAlso, you might have notice that, if the input length is less than 3 bytes, then, the output length of the encoder is always 4 bytes. This is the case for every input with less than 3 bytes, because, as I described in Section 4.1.3, the algorithm always produces enough “padding-groups” in the end result, to complete the 4 bytes window.\nNow, for the decoder, we just need to apply the inverse logic: for each 4 bytes in the input, 3 bytes will be produced in the output of the decoder. I mean, this is roughly true, because we also need to take the = character into account, which is always ignored by the decoder, as we described in Section 4.1.4, and, in Figure 4.2. But we can ignore this fact for now, just to keep things simple.\nThe function _calc_decode_length() exposed below summarizes this logic that we described. It’s very similar to the function _calc_encode_length(). Only the division part is twisted, and also, in the special case where we have less than 4 bytes in the input to work on. Also notice that this time, we apply a floor operation over the output of the division, by using the divFloor() function (instead of a ceiling operation with divCeil()).\n\nconst std = @import(\"std\");\nfn _calc_decode_length(input: []const u8) !usize {\n    if (input.len &lt; 4) {\n        const n_output: usize = 3;\n        return n_output;\n    }\n    const n_output: usize = try std.math.divFloor(\n        usize, input.len, 4\n    );\n    return n_output * 3;\n}",
+    "text": "4.3 Calculating the size of the output\nOne task that we need to do is to calculate how much space we need to reserve for the output, both of the encoder and decoder. This is simple math, and can be done easily in Zig because every array has its length (its number of elements) easily accesible by consulting the .len property of the array.\nFor the encoder, the logic is the following: for each 3 bytes that we find in the input, 4 new bytes are created in the output. So, we take the number of bytes in the input, divide it by 3, use a ceiling function, then, we multiply the result by 4. That way, we get the total number of bytes that will be produced by the encoder in its output.\nThe _calc_encode_length() function below encapsulates this logic. Inside this function, we take the length of the input array, we divide it by 3, and apply a ceil operation over the result by using the divCeil() function from the Zig Standard Library. Lastly, we multiply the end result by 4 to get the answer we need.\nAlso, you might have notice that, if the input length is less than 3 bytes, then, the output length of the encoder is always 4 bytes. This is the case for every input with less than 3 bytes, because, as I described in Section 4.1.3, the algorithm always produces enough “padding-groups” in the end result, to complete the 4 bytes window.\n\nconst std = @import(\"std\");\nfn _calc_encode_length(input: []const u8) !usize {\n    if (input.len &lt; 3) {\n        return 4;\n    }\n    const n_groups: usize = try std.math.divCeil(\n        usize, input.len, 3\n    );\n    return n_groups * 4;\n}\n\nNow, the logic to calculate the length of the output from the decoder is a little bit more complicated. But, it is basically just the inverse logic that we’ve used for the encoder: for each 4 bytes in the input, 3 bytes will be produced in the output of the decoder. However, this time we need to take the = character into account, which is always ignored by the decoder, as we described in Section 4.1.4, and, in Figure 4.2.\nIn essence, we take the length of the input and divide it by 4, then we apply a floor function on the result, then we multiply the result by 3, and then, we subtract from the result how much times the character = is found in the input.\nThe function _calc_decode_length() exposed below summarizes this logic that we described. It’s similar to the function _calc_encode_length(). Notice that the division part is twisted. Also notice that this time, we apply a floor operation over the output of the division, by using the divFloor() function (instead of a ceiling operation with divCeil()).\n\nconst std = @import(\"std\");\nfn _calc_decode_length(input: []const u8) !usize {\n    if (input.len &lt; 4) {\n        return 3;\n    }\n\n    const n_groups: usize = try std.math.divFloor(\n        usize, input.len, 4\n    );\n    var multiple_groups: usize = n_groups * 3;\n    var i: usize = input.len - 1;\n    while (i &gt; 0) : (i -= 1) {\n        if (input[i] == '=') {\n            multiple_groups -= 1;\n        } else {\n            break;\n        }\n    }\n\n    return multiple_groups;\n}",
     "crumbs": [
       "<span class='chapter-number'>4</span>  <span class='chapter-title'>Project 1 - Building a base64 encoder/decoder</span>"
     ]

From 1cbf790176c0ba50a30ef3378cdbb76b3937464a Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Mon, 7 Apr 2025 21:20:09 -0300
Subject: [PATCH 122/151] Improve runtime vs comptime example

---
 Chapters/01-zig-weird.qmd                     | 47 ++++++++++++-------
 ZigExamples/file-io/read_file.zig             | 18 +++++++
 ZigExamples/file-io/shop-list.txt             |  5 ++
 .../01-zig-weird/execute-results/html.json    |  4 +-
 docs/Chapters/01-zig-weird.html               | 35 ++++++++------
 docs/search.json                              |  2 +-
 6 files changed, 77 insertions(+), 34 deletions(-)
 create mode 100644 ZigExamples/file-io/read_file.zig
 create mode 100644 ZigExamples/file-io/shop-list.txt

diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index 392f6d0f..3f8bc356 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -1037,7 +1037,7 @@ In contrast, a runtime known thing is when the exact value of a thing is calcula
 Therefore, we don't know the value of this thing at compile-time, only at runtime.
 
 We have learned in @sec-select-array-elem that slices are created by using a *range selector*,
-which represents a range of indexes. When this "range of indexes" (i.e., the start and the end of this range)
+which represents a range of indexes. When this "range of indexes" (i.e., both the start and the end of this range)
 is known at compile-time, the slice object that gets created is actually, under the hood, just
 a single-item pointer to an array.
 
@@ -1052,8 +1052,8 @@ dereference the pointer of this slice, by using the `.*` method, like you would
 do on a normal pointer object.
 
 ```{zig}
-#| auto_main: false
-#| build_type: "ast"
+#| auto_main: true
+#| build_type: "run"
 const arr1 = [10]u64 {
     1, 2, 3, 4, 5,
     6, 7, 8, 9, 10
@@ -1061,6 +1061,7 @@ const arr1 = [10]u64 {
 // This slice have a compile-time known range.
 // Because we know both the start and end of the range.
 const slice = arr1[1..4];
+_ = slice;
 ```
 
 
@@ -1069,11 +1070,22 @@ that gets created is not a pointer anymore, and, thus, it does not support point
 For example, maybe the start index is known at compile time, but the end index is not. In such
 case, the range of the slice becomes runtime known only.
 
-In the example below, the `slice` object have a runtime known range, because the end index of the range
-is not known at compile time. In other words, the size of the array at `buffer` is not known
-at compile time. When we execute this program, the size of the array might be 10, or, it might be 12
-depending on where we execute it. Therefore, we don't know at compile time if
-the slice object have a range of size 10, or, a range of size 12.
+In the example below, we are reading a file, and then, we try to create a slice object
+that covers the entire buffer that contains the contents of this file. This is obviously
+an example of a runtime known range, because the end index of the range
+is not known at compile time.
+
+In other words, the end index of the range is the size of
+the array `file_contents`. However, the size of `file_contents` is not known at compile time.
+Because we don't know how many bytes are stored inside this `shop-list.txt` file.
+And because this is a file, someone might edit this file tomorrow and add more lines
+or remove lines from it. Therefore, the size of this file might vary drastically from one execution to another.
+
+Now, if the file size can vary from one run to another, then, we can conclude that the value of the expression
+`file_contents.len` exposed in the example below can also vary from one run to another. As consequence,
+the value of the expression `file_contents.len` is runtime-known only, and, as a consequence of that,
+the range `0..file_contents.len` is also runtime-known only.
+
 
 ```{zig}
 #| auto_main: false
@@ -1081,17 +1093,20 @@ the slice object have a range of size 10, or, a range of size 12.
 const std = @import("std");
 const builtin = @import("builtin");
 
+fn read_file(allocator: std.mem.Allocator, path: []const u8) ![]u8 {
+    const file = try std.fs.cwd().openFile(path, .{});
+    defer file.close();
+    return try file.reader().readAllAlloc(
+        allocator, std.math.maxInt(usize)
+    );
+}
+
 pub fn main() !void {
     var gpa = std.heap.GeneralPurposeAllocator(.{}){};
     const allocator = gpa.allocator();
-    var n: usize = 0;
-    if (builtin.target.os.tag == .windows) {
-        n = 10;
-    } else {
-        n = 12;
-    }
-    const buffer = try allocator.alloc(u64, n);
-    const slice = buffer[0..];
+    const path = "../ZigExamples/file-io/shop-list.txt";
+    const file_contents = try read_file(allocator, path);
+    const slice = file_contents[0..file_contents.len];
     _ = slice;
 }
 ```
diff --git a/ZigExamples/file-io/read_file.zig b/ZigExamples/file-io/read_file.zig
new file mode 100644
index 00000000..6782d428
--- /dev/null
+++ b/ZigExamples/file-io/read_file.zig
@@ -0,0 +1,18 @@
+const std = @import("std");
+const builtin = @import("builtin");
+
+fn read_file(allocator: std.mem.Allocator, path: []const u8) ![]u8 {
+    const file = try std.fs.cwd().openFile(path, .{});
+    defer file.close();
+
+    return try file.reader().readAllAlloc(allocator, std.math.maxInt(usize));
+}
+
+pub fn main() !void {
+    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
+    const allocator = gpa.allocator();
+    const path = "./ZigExamples/file-io/shop-list.txt";
+    const file_contents = try read_file(allocator, path);
+    const slice = file_contents[0..file_contents.len];
+    _ = slice;
+}
diff --git a/ZigExamples/file-io/shop-list.txt b/ZigExamples/file-io/shop-list.txt
new file mode 100644
index 00000000..72392352
--- /dev/null
+++ b/ZigExamples/file-io/shop-list.txt
@@ -0,0 +1,5 @@
+title,author,price
+O Hobbit,J. R. R. Tolkien,40.7
+Matemática para Economistas,Carl P. Simon and Lawrence Blume,140
+Microeconomia: uma Abordagem Moderna,Hal R. Varian,141
+A Luneta Âmbar,Philip Pullman,42.9
diff --git a/_freeze/Chapters/01-zig-weird/execute-results/html.json b/_freeze/Chapters/01-zig-weird/execute-results/html.json
index 8cfa1d22..0829c937 100644
--- a/_freeze/Chapters/01-zig-weird/execute-results/html.json
+++ b/_freeze/Chapters/01-zig-weird/execute-results/html.json
@@ -1,8 +1,8 @@
 {
-  "hash": "a69e849b0a1064ab89848935f7b05538",
+  "hash": "4a815fdfe6659e89535145dcadd0892e",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\n\nlanguage, it's still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. Sometimes, they really make it hard to debug\n\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscure the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that gets compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e., where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contains Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nWe can use this build system to write small scripts in Zig,\nwhich describe the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e., creating new objects)\nare made in Zig. You can create a new object in Zig by using the syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). In @sec-assignments we talk more about objects in general.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that in @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIt's worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt's like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portable C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nIn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e., the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. If you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith an \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, on Windows, operations like accessing the `stdout` (or opening a file) depend on\nresources that are available only at *runtime* (you will learn more about compile-time versus runtime\nin @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerges from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword in @sec-comptime.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation in a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues\n\n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described in @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig later in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig?\nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar to our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentation.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It's a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (on YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e., identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nSo, if you want to change the value of your object, you need to transform your immutable (or \"constant\")\nobject into a mutable (or \"variable\") object. You can do that by using the `var` keyword.\nThis keyword stands for \"variable\", and when you apply this keyword to some object, you are\ntelling the Zig compiler that the value associated with this object might change at some point.\n\nThus, if we come back to the previous example, and change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it's a \"variable object\".\n\nHowever, if you take a look at the example below, you will notice that we have not only declared the\n`age` object with the `var` keyword, but we also have explicitly annotated the data type\nof the `age` object with the `u8` type this time. The basic idea is, when we use a variable/mutable object,\nthe Zig compiler ask for us to be more explicit with what we want, to be more clear\nabout what our code does. This translates into being more explicit about the data types that we want\nto use in our objects.\n\nTherefore, if you transform your object into a variable/mutable object, just remember to always\nannotate the type of the object explicitly in your code. Otherwise, the Zig compiler might raise\na compilation error, asking you to transform your object back into a `const` object, or,\nto give your object an \"explicit type\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIt's important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code uses this object while it's uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object.\n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e., if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to a special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It's discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also gets discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e., the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\nIt's worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it's a slice that\naccesses all elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" in @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth in @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially in @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned in @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e., the start and the end of this range)\nis known at compile-time, the slice object that gets created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nin @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that gets created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e., a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can\ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n```\n:::\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat gets created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, the `slice` object have a runtime known range, because the end index of the range\nis not known at compile time. In other words, the size of the array at `buffer` is not known\nat compile time. When we execute this program, the size of the array might be 10, or, it might be 12\ndepending on where we execute it. Therefore, we don't know at compile time if\nthe slice object have a range of size 10, or, a range of size 12.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e., a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e., similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented in @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e., `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIt's worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e., a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e., the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause it's much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e., if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it's a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIt's important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig in @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers in @sec-root-file and especially in @sec-assignments.\n- How strings work in Zig in @sec-zig-strings.\n- How to use arrays and slices in @sec-arrays.\n- How to import functionality from other Zig modules in @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* in @sec-structs-and-oop.\n- Basic control flow syntax in @sec-zig-control-flow.\n- Enums in @sec-enum;\n- Pointers and Optionals in @sec-pointer;\n- Error handling with `try` and `catch` in @sec-error-handling;\n- Unit tests in @sec-unittests;\n- Vectors in @sec-vectors-simd;\n- Build System in @sec-build-system;\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\n\nlanguage, it's still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. Sometimes, they really make it hard to debug\n\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscure the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that gets compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e., where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contains Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nWe can use this build system to write small scripts in Zig,\nwhich describe the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e., creating new objects)\nare made in Zig. You can create a new object in Zig by using the syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). In @sec-assignments we talk more about objects in general.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that in @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIt's worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt's like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portable C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nIn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e., the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. If you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith an \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, on Windows, operations like accessing the `stdout` (or opening a file) depend on\nresources that are available only at *runtime* (you will learn more about compile-time versus runtime\nin @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerges from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword in @sec-comptime.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation in a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues\n\n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described in @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig later in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig?\nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar to our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentation.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It's a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (on YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e., identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nSo, if you want to change the value of your object, you need to transform your immutable (or \"constant\")\nobject into a mutable (or \"variable\") object. You can do that by using the `var` keyword.\nThis keyword stands for \"variable\", and when you apply this keyword to some object, you are\ntelling the Zig compiler that the value associated with this object might change at some point.\n\nThus, if we come back to the previous example, and change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it's a \"variable object\".\n\nHowever, if you take a look at the example below, you will notice that we have not only declared the\n`age` object with the `var` keyword, but we also have explicitly annotated the data type\nof the `age` object with the `u8` type this time. The basic idea is, when we use a variable/mutable object,\nthe Zig compiler ask for us to be more explicit with what we want, to be more clear\nabout what our code does. This translates into being more explicit about the data types that we want\nto use in our objects.\n\nTherefore, if you transform your object into a variable/mutable object, just remember to always\nannotate the type of the object explicitly in your code. Otherwise, the Zig compiler might raise\na compilation error, asking you to transform your object back into a `const` object, or,\nto give your object an \"explicit type\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIt's important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code uses this object while it's uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object.\n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e., if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to a special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It's discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also gets discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e., the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\nIt's worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it's a slice that\naccesses all elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" in @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth in @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially in @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned in @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e., both the start and the end of this range)\nis known at compile-time, the slice object that gets created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nin @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that gets created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e., a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can\ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n_ = slice;\n```\n:::\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat gets created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, the `slice` object have a runtime known range, because the end index of the range\nis not known at compile time. In other words, the size of the array at `buffer` is not known\nat compile time. When we execute this program, the size of the array might be 10, or, it might be 12\ndepending on where we execute it. Therefore, we don't know at compile time if\nthe slice object have a range of size 10, or, a range of size 12.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\nfn read_file(allocator: std.mem.Allocator, path: []const u8) ![]u8 {\n    const file = try std.fs.cwd().openFile(path, .{});\n    defer file.close();\n\n    return try file.reader().readAllAlloc(\n        allocator, std.math.maxInt(usize)\n    );\n}\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const path = \"../ZigExamples/file-io/shop-list.txt\";\n    const file_contents = try read_file(allocator, path);\n    const slice = file_contents[0..file_contents.len];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e., a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e., similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented in @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e., `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIt's worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e., a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e., the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause it's much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e., if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it's a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIt's important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig in @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers in @sec-root-file and especially in @sec-assignments.\n- How strings work in Zig in @sec-zig-strings.\n- How to use arrays and slices in @sec-arrays.\n- How to import functionality from other Zig modules in @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* in @sec-structs-and-oop.\n- Basic control flow syntax in @sec-zig-control-flow.\n- Enums in @sec-enum;\n- Pointers and Optionals in @sec-pointer;\n- Error handling with `try` and `catch` in @sec-error-handling;\n- Unit tests in @sec-unittests;\n- Vectors in @sec-vectors-simd;\n- Build System in @sec-build-system;\n",
     "supporting": [
       "01-zig-weird_files"
     ],
diff --git a/docs/Chapters/01-zig-weird.html b/docs/Chapters/01-zig-weird.html
index 354d6f86..f10d7032 100644
--- a/docs/Chapters/01-zig-weird.html
+++ b/docs/Chapters/01-zig-weird.html
@@ -752,7 +752,7 @@ <h3 data-number="1.6.3" class="anchored" data-anchor-id="array-operators"><span
 <section id="runtime-versus-compile-time-known-length-in-slices" class="level3" data-number="1.6.4">
 <h3 data-number="1.6.4" class="anchored" data-anchor-id="runtime-versus-compile-time-known-length-in-slices"><span class="header-section-number">1.6.4</span> Runtime versus compile-time known length in slices</h3>
 <p>We are going to talk a lot about the differences between compile-time known and runtime known across this book, especially in <a href="01-memory.html#sec-compile-time" class="quarto-xref"><span>Section 3.1.1</span></a>. But the basic idea is that a thing is compile-time known, when we know everything (the value, the attributes and the characteristics) about this thing at compile-time. In contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime. Therefore, we don’t know the value of this thing at compile-time, only at runtime.</p>
-<p>We have learned in <a href="#sec-select-array-elem" class="quarto-xref"><span>Section 1.6.1</span></a> that slices are created by using a <em>range selector</em>, which represents a range of indexes. When this “range of indexes” (i.e., the start and the end of this range) is known at compile-time, the slice object that gets created is actually, under the hood, just a single-item pointer to an array.</p>
+<p>We have learned in <a href="#sec-select-array-elem" class="quarto-xref"><span>Section 1.6.1</span></a> that slices are created by using a <em>range selector</em>, which represents a range of indexes. When this “range of indexes” (i.e., both the start and the end of this range) is known at compile-time, the slice object that gets created is actually, under the hood, just a single-item pointer to an array.</p>
 <p>You don’t need to precisely understand what that means now. We are going to talk a lot about pointers in <a href="05-pointers.html" class="quarto-xref"><span>Chapter 6</span></a>. For now, just understand that, when the range of indexes is known at compile-time, the slice that gets created is just a pointer to an array, accompanied by a length value that tells the size of the slice.</p>
 <p>If you have a slice object like this, i.e., a slice that has a compile-time known range, you can use common pointer operations over this slice object. For example, you can dereference the pointer of this slice, by using the <code>.*</code> method, like you would do on a normal pointer object.</p>
 <div class="cell">
@@ -762,7 +762,8 @@ <h3 data-number="1.6.4" class="anchored" data-anchor-id="runtime-versus-compile-
 <span id="cb44-4"><a href="#cb44-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
 <span id="cb44-5"><a href="#cb44-5" aria-hidden="true" tabindex="-1"></a><span class="co">// This slice have a compile-time known range.</span></span>
 <span id="cb44-6"><a href="#cb44-6" aria-hidden="true" tabindex="-1"></a><span class="co">// Because we know both the start and end of the range.</span></span>
-<span id="cb44-7"><a href="#cb44-7" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> slice = arr1[<span class="dv">1</span>..<span class="dv">4</span>];</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<span id="cb44-7"><a href="#cb44-7" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> slice = arr1[<span class="dv">1</span>..<span class="dv">4</span>];</span>
+<span id="cb44-8"><a href="#cb44-8" aria-hidden="true" tabindex="-1"></a>_ = slice;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>On the other hand, if the range of indexes is not known at compile time, then, the slice object that gets created is not a pointer anymore, and, thus, it does not support pointer operations. For example, maybe the start index is known at compile time, but the end index is not. In such case, the range of the slice becomes runtime known only.</p>
 <p>In the example below, the <code>slice</code> object have a runtime known range, because the end index of the range is not known at compile time. In other words, the size of the array at <code>buffer</code> is not known at compile time. When we execute this program, the size of the array might be 10, or, it might be 12 depending on where we execute it. Therefore, we don’t know at compile time if the slice object have a range of size 10, or, a range of size 12.</p>
@@ -770,19 +771,23 @@ <h3 data-number="1.6.4" class="anchored" data-anchor-id="runtime-versus-compile-
 <div class="sourceCode cell-code" id="cb45"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb45-1"><a href="#cb45-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb45-2"><a href="#cb45-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> builtin = <span class="bu">@import</span>(<span class="st">"builtin"</span>);</span>
 <span id="cb45-3"><a href="#cb45-3" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb45-4"><a href="#cb45-4" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb45-5"><a href="#cb45-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> gpa = std.heap.GeneralPurposeAllocator(.<span class="op">{}</span>)<span class="op">{}</span>;</span>
-<span id="cb45-6"><a href="#cb45-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> allocator = gpa.allocator();</span>
-<span id="cb45-7"><a href="#cb45-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> n: <span class="dt">usize</span> = <span class="dv">0</span>;</span>
-<span id="cb45-8"><a href="#cb45-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> (builtin.target.os.tag == .windows) <span class="op">{</span></span>
-<span id="cb45-9"><a href="#cb45-9" aria-hidden="true" tabindex="-1"></a>        n = <span class="dv">10</span>;</span>
-<span id="cb45-10"><a href="#cb45-10" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span> <span class="kw">else</span> <span class="op">{</span></span>
-<span id="cb45-11"><a href="#cb45-11" aria-hidden="true" tabindex="-1"></a>        n = <span class="dv">12</span>;</span>
-<span id="cb45-12"><a href="#cb45-12" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb45-13"><a href="#cb45-13" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> buffer = <span class="kw">try</span> allocator.alloc(<span class="dt">u64</span>, n);</span>
-<span id="cb45-14"><a href="#cb45-14" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> slice = buffer[<span class="dv">0</span>..];</span>
-<span id="cb45-15"><a href="#cb45-15" aria-hidden="true" tabindex="-1"></a>    _ = slice;</span>
-<span id="cb45-16"><a href="#cb45-16" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<span id="cb45-4"><a href="#cb45-4" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> read_file(allocator: std.mem.Allocator, path: []<span class="kw">const</span> <span class="dt">u8</span>) ![]<span class="dt">u8</span> <span class="op">{</span></span>
+<span id="cb45-5"><a href="#cb45-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> file = <span class="kw">try</span> std.fs.cwd().openFile(path, .<span class="op">{}</span>);</span>
+<span id="cb45-6"><a href="#cb45-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">defer</span> file.close();</span>
+<span id="cb45-7"><a href="#cb45-7" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb45-8"><a href="#cb45-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> <span class="kw">try</span> file.reader().readAllAlloc(</span>
+<span id="cb45-9"><a href="#cb45-9" aria-hidden="true" tabindex="-1"></a>        allocator, std.math.maxInt(<span class="dt">usize</span>)</span>
+<span id="cb45-10"><a href="#cb45-10" aria-hidden="true" tabindex="-1"></a>    );</span>
+<span id="cb45-11"><a href="#cb45-11" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
+<span id="cb45-12"><a href="#cb45-12" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb45-13"><a href="#cb45-13" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb45-14"><a href="#cb45-14" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> gpa = std.heap.GeneralPurposeAllocator(.<span class="op">{}</span>)<span class="op">{}</span>;</span>
+<span id="cb45-15"><a href="#cb45-15" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> allocator = gpa.allocator();</span>
+<span id="cb45-16"><a href="#cb45-16" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> path = <span class="st">"../ZigExamples/file-io/shop-list.txt"</span>;</span>
+<span id="cb45-17"><a href="#cb45-17" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> file_contents = <span class="kw">try</span> read_file(allocator, path);</span>
+<span id="cb45-18"><a href="#cb45-18" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> slice = file_contents[<span class="dv">0</span>..file_contents.len];</span>
+<span id="cb45-19"><a href="#cb45-19" aria-hidden="true" tabindex="-1"></a>    _ = slice;</span>
+<span id="cb45-20"><a href="#cb45-20" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
 </section>
diff --git a/docs/search.json b/docs/search.json
index 5a611b6c..9c21c93a 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -164,7 +164,7 @@
     "href": "Chapters/01-zig-weird.html#sec-arrays",
     "title": "1  Introducing Zig",
     "section": "1.6 Arrays",
-    "text": "1.6 Arrays\nYou create arrays in Zig by using a syntax that resembles the C syntax. First, you specify the size of the array (i.e., the number of elements that will be stored in the array) you want to create inside a pair of brackets.\nThen, you specify the data type of the elements that will be stored inside this array. All elements present in an array in Zig must have the same data type. For example, you cannot mix elements of type f32 with elements of type i32 in the same array.\nAfter that, you simply list the values that you want to store in this array inside a pair of curly braces. In the example below, I am creating two constant objects that contain different arrays. The first object contains an array of 4 integer values, while the second object, an array of 3 floating point values.\nNow, you should notice that in the object ls, I am not explicitly specifying the size of the array inside of the brackets. Instead of using a literal value (like the value 4 that I used in the ns object), I am using the special character underscore (_). This syntax tells the zig compiler to fill this field with the number of elements listed inside of the curly braces. So, this syntax [_] is for lazy (or smart) programmers who leave the job of counting how many elements there are in the curly braces for the compiler.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n\nIt’s worth noting that these are static arrays, meaning that they cannot grow in size. Once you declare your array, you cannot change the size of it. This is very common in low level languages. Because low level languages normally wants to give you (the programmer) full control over memory, and the way in which arrays are expanded is tightly related to memory management.\n\n1.6.1 Selecting elements of the array\nOne very common activity is to select specific portions of an array you have in your source code. In Zig, you can select a specific element from your array, by simply providing the index of this particular element inside brackets after the object name. In the example below, I am selecting the third element from the ns array. Notice that Zig is a “zero-index” based language, like C, C++, Rust, Python, and many other languages.\n\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n\n12\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a range selector. Some programmers also call these selectors of “slice selectors”, and they also exist in Rust, and have the exact same syntax as in Zig. Anyway, a range selector is a special expression in Zig that defines a range of indexes, and it have the syntax start..end.\nIn the example below, at the second line of code, the sl object stores a slice (or a portion) of the ns array. More precisely, the elements at index 1 and 2 in the ns array.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n\nWhen you use the start..end syntax, the “end tail” of the range selector is non-inclusive, meaning that, the index at the end is not included in the range that is selected from the array. Therefore, the syntax start..end actually means start..end - 1 in practice.\nYou can for example, create a slice that goes from the first to the last elements of the array, by using ar[0..ar.len] syntax In other words, it’s a slice that accesses all elements in the array.\n\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n\nYou can also use the syntax start.. in your range selector. Which tells the zig compiler to select the portion of the array that begins at the start index until the last element of the array. In the example below, we are selecting the range from index 1 until the end of the array.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n\n\n\n1.6.2 More on slices\nAs we discussed before, in Zig, you can select specific portions of an existing array. This is called slicing in Zig (Sobeston 2024), because when you select a portion of an array, you are creating a slice object from that array.\nA slice object is essentially a pointer object accompanied by a length number. The pointer object points to the first element in the slice, and the length number tells the zig compiler how many elements there are in this slice.\n\nSlices can be thought of as a pair of [*]T (the pointer to the data) and a usize (the element count) (Sobeston 2024).\n\nThrough the pointer contained inside the slice you can access the elements (or values) that are inside this range (or portion) that you selected from the original array. But the length number (which you can access through the len property of your slice object) is the really big improvement (over C arrays for example) that Zig brings to the table here.\nBecause with this length number the zig compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice, or, if you are causing any buffer overflow problems. In the example below, we access the len property of the slice sl, which tells us that this slice have 2 elements in it.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n\n2\n\n\n\n\n1.6.3 Array operators\nThere are two array operators available in Zig that are very useful. The array concatenation operator (++), and the array multiplication operator (**). As the name suggests, these are array operators.\nOne important detail about these two operators is that they work only when both operands have a size (or “length”) that is compile-time known. We are going to talk more about the differences between “compile-time known” and “runtime known” in Section 3.1.1. But for now, keep this information in mind, that you cannot use these operators in every situation.\nIn summary, the ++ operator creates a new array that is the concatenation, of both arrays provided as operands. So, the expression a ++ b produces a new array which contains all the elements from arrays a and b.\n\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n\n{ 1, 2, 3, 4, 5 }\n\n\nThis ++ operator is particularly useful to concatenate strings together. Strings in Zig are described in depth in Section 1.8. In summary, a string object in Zig is essentially an arrays of bytes. So, you can use this array concatenation operator to effectively concatenate strings together.\nIn contrast, the ** operator is used to replicate an array multiple times. In other words, the expression a ** 3 creates a new array which contains the elements of the array a repeated 3 times.\n\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n\n{ 1, 2, 3, 1, 2, 3 }\n\n\n\n\n1.6.4 Runtime versus compile-time known length in slices\nWe are going to talk a lot about the differences between compile-time known and runtime known across this book, especially in Section 3.1.1. But the basic idea is that a thing is compile-time known, when we know everything (the value, the attributes and the characteristics) about this thing at compile-time. In contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime. Therefore, we don’t know the value of this thing at compile-time, only at runtime.\nWe have learned in Section 1.6.1 that slices are created by using a range selector, which represents a range of indexes. When this “range of indexes” (i.e., the start and the end of this range) is known at compile-time, the slice object that gets created is actually, under the hood, just a single-item pointer to an array.\nYou don’t need to precisely understand what that means now. We are going to talk a lot about pointers in Chapter 6. For now, just understand that, when the range of indexes is known at compile-time, the slice that gets created is just a pointer to an array, accompanied by a length value that tells the size of the slice.\nIf you have a slice object like this, i.e., a slice that has a compile-time known range, you can use common pointer operations over this slice object. For example, you can dereference the pointer of this slice, by using the .* method, like you would do on a normal pointer object.\n\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object that gets created is not a pointer anymore, and, thus, it does not support pointer operations. For example, maybe the start index is known at compile time, but the end index is not. In such case, the range of the slice becomes runtime known only.\nIn the example below, the slice object have a runtime known range, because the end index of the range is not known at compile time. In other words, the size of the array at buffer is not known at compile time. When we execute this program, the size of the array might be 10, or, it might be 12 depending on where we execute it. Therefore, we don’t know at compile time if the slice object have a range of size 10, or, a range of size 12.\n\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var n: usize = 0;\n    if (builtin.target.os.tag == .windows) {\n        n = 10;\n    } else {\n        n = 12;\n    }\n    const buffer = try allocator.alloc(u64, n);\n    const slice = buffer[0..];\n    _ = slice;\n}",
+    "text": "1.6 Arrays\nYou create arrays in Zig by using a syntax that resembles the C syntax. First, you specify the size of the array (i.e., the number of elements that will be stored in the array) you want to create inside a pair of brackets.\nThen, you specify the data type of the elements that will be stored inside this array. All elements present in an array in Zig must have the same data type. For example, you cannot mix elements of type f32 with elements of type i32 in the same array.\nAfter that, you simply list the values that you want to store in this array inside a pair of curly braces. In the example below, I am creating two constant objects that contain different arrays. The first object contains an array of 4 integer values, while the second object, an array of 3 floating point values.\nNow, you should notice that in the object ls, I am not explicitly specifying the size of the array inside of the brackets. Instead of using a literal value (like the value 4 that I used in the ns object), I am using the special character underscore (_). This syntax tells the zig compiler to fill this field with the number of elements listed inside of the curly braces. So, this syntax [_] is for lazy (or smart) programmers who leave the job of counting how many elements there are in the curly braces for the compiler.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n\nIt’s worth noting that these are static arrays, meaning that they cannot grow in size. Once you declare your array, you cannot change the size of it. This is very common in low level languages. Because low level languages normally wants to give you (the programmer) full control over memory, and the way in which arrays are expanded is tightly related to memory management.\n\n1.6.1 Selecting elements of the array\nOne very common activity is to select specific portions of an array you have in your source code. In Zig, you can select a specific element from your array, by simply providing the index of this particular element inside brackets after the object name. In the example below, I am selecting the third element from the ns array. Notice that Zig is a “zero-index” based language, like C, C++, Rust, Python, and many other languages.\n\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n\n12\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a range selector. Some programmers also call these selectors of “slice selectors”, and they also exist in Rust, and have the exact same syntax as in Zig. Anyway, a range selector is a special expression in Zig that defines a range of indexes, and it have the syntax start..end.\nIn the example below, at the second line of code, the sl object stores a slice (or a portion) of the ns array. More precisely, the elements at index 1 and 2 in the ns array.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n\nWhen you use the start..end syntax, the “end tail” of the range selector is non-inclusive, meaning that, the index at the end is not included in the range that is selected from the array. Therefore, the syntax start..end actually means start..end - 1 in practice.\nYou can for example, create a slice that goes from the first to the last elements of the array, by using ar[0..ar.len] syntax In other words, it’s a slice that accesses all elements in the array.\n\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n\nYou can also use the syntax start.. in your range selector. Which tells the zig compiler to select the portion of the array that begins at the start index until the last element of the array. In the example below, we are selecting the range from index 1 until the end of the array.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n\n\n\n1.6.2 More on slices\nAs we discussed before, in Zig, you can select specific portions of an existing array. This is called slicing in Zig (Sobeston 2024), because when you select a portion of an array, you are creating a slice object from that array.\nA slice object is essentially a pointer object accompanied by a length number. The pointer object points to the first element in the slice, and the length number tells the zig compiler how many elements there are in this slice.\n\nSlices can be thought of as a pair of [*]T (the pointer to the data) and a usize (the element count) (Sobeston 2024).\n\nThrough the pointer contained inside the slice you can access the elements (or values) that are inside this range (or portion) that you selected from the original array. But the length number (which you can access through the len property of your slice object) is the really big improvement (over C arrays for example) that Zig brings to the table here.\nBecause with this length number the zig compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice, or, if you are causing any buffer overflow problems. In the example below, we access the len property of the slice sl, which tells us that this slice have 2 elements in it.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n\n2\n\n\n\n\n1.6.3 Array operators\nThere are two array operators available in Zig that are very useful. The array concatenation operator (++), and the array multiplication operator (**). As the name suggests, these are array operators.\nOne important detail about these two operators is that they work only when both operands have a size (or “length”) that is compile-time known. We are going to talk more about the differences between “compile-time known” and “runtime known” in Section 3.1.1. But for now, keep this information in mind, that you cannot use these operators in every situation.\nIn summary, the ++ operator creates a new array that is the concatenation, of both arrays provided as operands. So, the expression a ++ b produces a new array which contains all the elements from arrays a and b.\n\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n\n{ 1, 2, 3, 4, 5 }\n\n\nThis ++ operator is particularly useful to concatenate strings together. Strings in Zig are described in depth in Section 1.8. In summary, a string object in Zig is essentially an arrays of bytes. So, you can use this array concatenation operator to effectively concatenate strings together.\nIn contrast, the ** operator is used to replicate an array multiple times. In other words, the expression a ** 3 creates a new array which contains the elements of the array a repeated 3 times.\n\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n\n{ 1, 2, 3, 1, 2, 3 }\n\n\n\n\n1.6.4 Runtime versus compile-time known length in slices\nWe are going to talk a lot about the differences between compile-time known and runtime known across this book, especially in Section 3.1.1. But the basic idea is that a thing is compile-time known, when we know everything (the value, the attributes and the characteristics) about this thing at compile-time. In contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime. Therefore, we don’t know the value of this thing at compile-time, only at runtime.\nWe have learned in Section 1.6.1 that slices are created by using a range selector, which represents a range of indexes. When this “range of indexes” (i.e., both the start and the end of this range) is known at compile-time, the slice object that gets created is actually, under the hood, just a single-item pointer to an array.\nYou don’t need to precisely understand what that means now. We are going to talk a lot about pointers in Chapter 6. For now, just understand that, when the range of indexes is known at compile-time, the slice that gets created is just a pointer to an array, accompanied by a length value that tells the size of the slice.\nIf you have a slice object like this, i.e., a slice that has a compile-time known range, you can use common pointer operations over this slice object. For example, you can dereference the pointer of this slice, by using the .* method, like you would do on a normal pointer object.\n\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n_ = slice;\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object that gets created is not a pointer anymore, and, thus, it does not support pointer operations. For example, maybe the start index is known at compile time, but the end index is not. In such case, the range of the slice becomes runtime known only.\nIn the example below, the slice object have a runtime known range, because the end index of the range is not known at compile time. In other words, the size of the array at buffer is not known at compile time. When we execute this program, the size of the array might be 10, or, it might be 12 depending on where we execute it. Therefore, we don’t know at compile time if the slice object have a range of size 10, or, a range of size 12.\n\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\nfn read_file(allocator: std.mem.Allocator, path: []const u8) ![]u8 {\n    const file = try std.fs.cwd().openFile(path, .{});\n    defer file.close();\n\n    return try file.reader().readAllAlloc(\n        allocator, std.math.maxInt(usize)\n    );\n}\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const path = \"../ZigExamples/file-io/shop-list.txt\";\n    const file_contents = try read_file(allocator, path);\n    const slice = file_contents[0..file_contents.len];\n    _ = slice;\n}",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]

From dd99f9b0d9c476dd68db96ce7bbe70e236e2a104 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Mon, 7 Apr 2025 22:01:46 -0300
Subject: [PATCH 123/151] Improve runtime vs comptime example

---
 Chapters/10-stack-project.qmd                 | 46 +++++++++++++------
 .../comptime/comptime_arg_runtime_error.zig   | 17 +++++++
 .../01-zig-weird/execute-results/html.json    |  4 +-
 .../execute-results/html.json                 |  4 +-
 docs/Chapters/01-zig-weird.html               | 31 +++++++------
 docs/Chapters/10-stack-project.html           | 43 ++++++++++-------
 docs/search.json                              |  4 +-
 7 files changed, 96 insertions(+), 53 deletions(-)
 create mode 100644 ZigExamples/comptime/comptime_arg_runtime_error.zig

diff --git a/Chapters/10-stack-project.qmd b/Chapters/10-stack-project.qmd
index 8dc43567..7a05b66b 100644
--- a/Chapters/10-stack-project.qmd
+++ b/Chapters/10-stack-project.qmd
@@ -88,33 +88,49 @@ test "test comptime" {
 ```
 
 But what if we provide a number that is not compile-time known to this function?
-For example, we might provide a different input value to this function depending
-on the target OS of our compilation process. The code example below demonstrates such case.
-
-Because the value of the object `n` is determined at runtime, we cannot provide this object
-as input to the `twice()` function. The `zig` compiler will not allow it, because we marked
+For example, your program might receive some input from the user through the `stdin`
+channel of your system. This input from the user might be many different things,
+and cannot be predicted at compile-time. These circumstances make this "input
+from the user" a value that is runtime-known only.
+
+In the example below, this "input from the user" is initially received as a string,
+which is then parsed and transformed into a integer value, and the result of this operation
+is stored inside the `n` object.
+
+Because the "input of the user" is known only at runtime, the value of the object `n` is determined only at runtime.
+As consequence, we cannot provide this object as input to the `twice()` function.
+The `zig` compiler will not allow it, because we marked
 the `num` argument as a "comptime argument". That is why the `zig` compiler raises
 the compile-time error exposed below:
 
 ```{zig}
+#| auto_main: false
 #| eval: false
-const builtin = @import("builtin");
+const std = @import("std");
 fn twice(comptime num: u32) u32 {
     return num * 2;
 }
-test "test comptime" {
-    var n: u32 = undefined;
-    if (builtin.target.os.tag == .windows) {
-        n = 1234;
-    } else {
-        n = 5678;
-    }
-    _ = twice(n);
+
+pub fn main() !void {
+    var buffer: [5]u8 = .{ 0, 0, 0, 0, 0 };
+    const stdout = std.io.getStdOut().writer();
+    const stdin = std.io.getStdIn().reader();
+    _ = try stdout.write("Please write a 4-digit integer number\n");
+    _ = try stdin.readUntilDelimiter(&buffer, '\n');
+
+    try stdout.print("Input: {s}", .{buffer});
+    const n: u32 = try std.fmt.parseInt(
+        u32, buffer[0 .. buffer.len - 1], 10
+    );
+    const twice_result = twice(n);
+    try stdout.print("Result: {d}\n", .{twice_result});
 }
 ```
 
 ```
-t.zig:12:16: error: runtime-known argument passed to comptime parameter
+t.zig:12:16: error: unable to resolve comptime value
+    const twice_result = twice(n);
+                               ^
 ```
 
 Comptime arguments are frequently used on functions that return some sort
diff --git a/ZigExamples/comptime/comptime_arg_runtime_error.zig b/ZigExamples/comptime/comptime_arg_runtime_error.zig
new file mode 100644
index 00000000..517bb9db
--- /dev/null
+++ b/ZigExamples/comptime/comptime_arg_runtime_error.zig
@@ -0,0 +1,17 @@
+const std = @import("std");
+fn twice(comptime num: u32) u32 {
+    return num * 2;
+}
+
+pub fn main() !void {
+    var buffer: [5]u8 = .{ 0, 0, 0, 0, 0 };
+    const stdout = std.io.getStdOut().writer();
+    const stdin = std.io.getStdIn().reader();
+    _ = try stdout.write("Please write a 4-digit integer number\n");
+    _ = try stdin.readUntilDelimiter(&buffer, '\n');
+
+    try stdout.print("Input: {s}", .{buffer});
+    const n: u32 = try std.fmt.parseInt(u32, buffer[0 .. buffer.len - 1], 10);
+    const twice_result = twice(n);
+    try stdout.print("Result: {d}\n", .{twice_result});
+}
diff --git a/_freeze/Chapters/01-zig-weird/execute-results/html.json b/_freeze/Chapters/01-zig-weird/execute-results/html.json
index 0829c937..baa58ef3 100644
--- a/_freeze/Chapters/01-zig-weird/execute-results/html.json
+++ b/_freeze/Chapters/01-zig-weird/execute-results/html.json
@@ -1,8 +1,8 @@
 {
-  "hash": "4a815fdfe6659e89535145dcadd0892e",
+  "hash": "06a3119bbdf9be9d02679617c65c9d79",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\n\nlanguage, it's still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. Sometimes, they really make it hard to debug\n\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscure the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that gets compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e., where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contains Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nWe can use this build system to write small scripts in Zig,\nwhich describe the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e., creating new objects)\nare made in Zig. You can create a new object in Zig by using the syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). In @sec-assignments we talk more about objects in general.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that in @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIt's worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt's like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portable C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nIn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e., the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. If you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith an \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, on Windows, operations like accessing the `stdout` (or opening a file) depend on\nresources that are available only at *runtime* (you will learn more about compile-time versus runtime\nin @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerges from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword in @sec-comptime.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation in a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues\n\n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described in @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig later in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig?\nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar to our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentation.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It's a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (on YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e., identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nSo, if you want to change the value of your object, you need to transform your immutable (or \"constant\")\nobject into a mutable (or \"variable\") object. You can do that by using the `var` keyword.\nThis keyword stands for \"variable\", and when you apply this keyword to some object, you are\ntelling the Zig compiler that the value associated with this object might change at some point.\n\nThus, if we come back to the previous example, and change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it's a \"variable object\".\n\nHowever, if you take a look at the example below, you will notice that we have not only declared the\n`age` object with the `var` keyword, but we also have explicitly annotated the data type\nof the `age` object with the `u8` type this time. The basic idea is, when we use a variable/mutable object,\nthe Zig compiler ask for us to be more explicit with what we want, to be more clear\nabout what our code does. This translates into being more explicit about the data types that we want\nto use in our objects.\n\nTherefore, if you transform your object into a variable/mutable object, just remember to always\nannotate the type of the object explicitly in your code. Otherwise, the Zig compiler might raise\na compilation error, asking you to transform your object back into a `const` object, or,\nto give your object an \"explicit type\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIt's important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code uses this object while it's uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object.\n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e., if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to a special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It's discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also gets discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e., the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\nIt's worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it's a slice that\naccesses all elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" in @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth in @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially in @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned in @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e., both the start and the end of this range)\nis known at compile-time, the slice object that gets created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nin @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that gets created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e., a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can\ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n_ = slice;\n```\n:::\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat gets created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, the `slice` object have a runtime known range, because the end index of the range\nis not known at compile time. In other words, the size of the array at `buffer` is not known\nat compile time. When we execute this program, the size of the array might be 10, or, it might be 12\ndepending on where we execute it. Therefore, we don't know at compile time if\nthe slice object have a range of size 10, or, a range of size 12.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\nfn read_file(allocator: std.mem.Allocator, path: []const u8) ![]u8 {\n    const file = try std.fs.cwd().openFile(path, .{});\n    defer file.close();\n\n    return try file.reader().readAllAlloc(\n        allocator, std.math.maxInt(usize)\n    );\n}\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const path = \"../ZigExamples/file-io/shop-list.txt\";\n    const file_contents = try read_file(allocator, path);\n    const slice = file_contents[0..file_contents.len];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e., a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e., similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented in @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e., `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIt's worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e., a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e., the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause it's much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e., if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it's a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIt's important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig in @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers in @sec-root-file and especially in @sec-assignments.\n- How strings work in Zig in @sec-zig-strings.\n- How to use arrays and slices in @sec-arrays.\n- How to import functionality from other Zig modules in @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* in @sec-structs-and-oop.\n- Basic control flow syntax in @sec-zig-control-flow.\n- Enums in @sec-enum;\n- Pointers and Optionals in @sec-pointer;\n- Error handling with `try` and `catch` in @sec-error-handling;\n- Unit tests in @sec-unittests;\n- Vectors in @sec-vectors-simd;\n- Build System in @sec-build-system;\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\n\nlanguage, it's still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. Sometimes, they really make it hard to debug\n\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscure the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that gets compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e., where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contains Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nWe can use this build system to write small scripts in Zig,\nwhich describe the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e., creating new objects)\nare made in Zig. You can create a new object in Zig by using the syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). In @sec-assignments we talk more about objects in general.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that in @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIt's worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt's like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portable C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nIn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e., the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. If you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith an \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, on Windows, operations like accessing the `stdout` (or opening a file) depend on\nresources that are available only at *runtime* (you will learn more about compile-time versus runtime\nin @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerges from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword in @sec-comptime.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation in a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues\n\n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described in @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig later in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig?\nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar to our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentation.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It's a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (on YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e., identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nSo, if you want to change the value of your object, you need to transform your immutable (or \"constant\")\nobject into a mutable (or \"variable\") object. You can do that by using the `var` keyword.\nThis keyword stands for \"variable\", and when you apply this keyword to some object, you are\ntelling the Zig compiler that the value associated with this object might change at some point.\n\nThus, if we come back to the previous example, and change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it's a \"variable object\".\n\nHowever, if you take a look at the example below, you will notice that we have not only declared the\n`age` object with the `var` keyword, but we also have explicitly annotated the data type\nof the `age` object with the `u8` type this time. The basic idea is, when we use a variable/mutable object,\nthe Zig compiler ask for us to be more explicit with what we want, to be more clear\nabout what our code does. This translates into being more explicit about the data types that we want\nto use in our objects.\n\nTherefore, if you transform your object into a variable/mutable object, just remember to always\nannotate the type of the object explicitly in your code. Otherwise, the Zig compiler might raise\na compilation error, asking you to transform your object back into a `const` object, or,\nto give your object an \"explicit type\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIt's important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code uses this object while it's uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object.\n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e., if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to a special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It's discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also gets discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e., the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\nIt's worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it's a slice that\naccesses all elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" in @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth in @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially in @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned in @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e., both the start and the end of this range)\nis known at compile-time, the slice object that gets created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nin @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that gets created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e., a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can\ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n_ = slice;\n```\n:::\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat gets created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, we are reading a file, and then, we try to create a slice object\nthat covers the entire buffer that contains the contents of this file. This is obviously\nan example of a runtime known range, because the end index of the range\nis not known at compile time.\n\nIn other words, the end index of the range is the size of\nthe array `file_contents`. However, the size of `file_contents` is not known at compile time.\nBecause we don't know how many bytes are stored inside this `shop-list.txt` file.\nAnd because this is a file, someone might edit this file tomorrow and add more lines\nor remove lines from it. Therefore, the size of this file might vary drastically from one execution to another.\n\nNow, if the file size can vary from one run to another, then, we can conclude that the value of the expression\n`file_contents.len` exposed in the example below can also vary from one run to another. As consequence,\nthe value of the expression `file_contents.len` is runtime-known only, and, as a consequence of that,\nthe range `0..file_contents.len` is also runtime-known only.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\nfn read_file(allocator: std.mem.Allocator, path: []const u8) ![]u8 {\n    const file = try std.fs.cwd().openFile(path, .{});\n    defer file.close();\n    return try file.reader().readAllAlloc(\n        allocator, std.math.maxInt(usize)\n    );\n}\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const path = \"../ZigExamples/file-io/shop-list.txt\";\n    const file_contents = try read_file(allocator, path);\n    const slice = file_contents[0..file_contents.len];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e., a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e., similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented in @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e., `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIt's worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e., a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e., the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause it's much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e., if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it's a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIt's important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig in @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers in @sec-root-file and especially in @sec-assignments.\n- How strings work in Zig in @sec-zig-strings.\n- How to use arrays and slices in @sec-arrays.\n- How to import functionality from other Zig modules in @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* in @sec-structs-and-oop.\n- Basic control flow syntax in @sec-zig-control-flow.\n- Enums in @sec-enum;\n- Pointers and Optionals in @sec-pointer;\n- Error handling with `try` and `catch` in @sec-error-handling;\n- Unit tests in @sec-unittests;\n- Vectors in @sec-vectors-simd;\n- Build System in @sec-build-system;\n",
     "supporting": [
       "01-zig-weird_files"
     ],
diff --git a/_freeze/Chapters/10-stack-project/execute-results/html.json b/_freeze/Chapters/10-stack-project/execute-results/html.json
index 398f20fc..91cbf4a5 100644
--- a/_freeze/Chapters/10-stack-project/execute-results/html.json
+++ b/_freeze/Chapters/10-stack-project/execute-results/html.json
@@ -1,8 +1,8 @@
 {
-  "hash": "fe2d7fa4c6d4bcadd97ff3ab647083a0",
+  "hash": "801c378f39cbcf646c40a137880aa3b8",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 3 - Building a stack data structure\n\nIn this chapter we are going to implement a stack data structure as our next small project\nin this book. Implementing basic data structures in any language is kind of a\n\"kindergarten task\" (if this term even exist) in computer science (CS), because\nwe normally learn and implement them in the first semesters of CS.\n\nBut this is actually good! Since this should be a very easy task, we don't need much to explain\nwhat a stack is, then, we can concentrate on what is really important here, which is learning\nhow the concept of \"generics\" is implemented in the Zig language, and how one of the key\nfeatures of Zig, which is comptime, works, and use the stack data structure to demonstrate\nthese concepts on the fly.\n\nBut before we get into building the stack data structure, we first need to understand\nwhat the `comptime` keyword does to your code, and after that, we also need to learn about\nhow generics work in Zig.\n\n\n## Understanding `comptime` in Zig {#sec-comptime}\n\nOne of the key features of Zig is `comptime`. This keyword introduces a whole\nnew concept and paradigm, that is tightly connected with the compilation process.\nIn @sec-compile-time we have described the importance and the role that \"compile-time versus runtime\"\nplays into Zig. In that section, we learned that the rules applied to a value/object change\na lot depending on whether this value is known at compile-time, or just at runtime.\n\nThe `comptime` keyword is strongly related to these two spaces in time (compile-time and runtime).\nLet's quickly recap the differences. Compile-time is the period of time when your\nZig source code is being compiled by the `zig` compiler, while the runtime is\nthe period of time when your Zig program is being executed, i.e., when we execute\nthe binary files that were generated by the `zig` compiler.\n\nThere are three ways in which you can apply the `comptime` keyword, which are:\n\n- apply `comptime` on a function argument.\n- apply `comptime` on an object.\n- apply `comptime` on a block of expressions.\n\n\n\n### Applying over a function argument\n\nWhen you apply the `comptime` keyword on a function argument, you are saying to the `zig` compiler\nthat the value assigned to that particular function argument must be known at compile-time.\nWe explained in detail in @sec-compile-time what exactly \"value known at compile-time\" means. So\nif you have any doubts about this idea, refer back to that section.\n\nNow let's think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement\nto that particular function argument. If the programmer accidentally tries to give a value to this\nfunction argument that is not known at compile time, the `zig` compiler will notice this problem, and\nas a consequence, it will raise a compilation error saying that it cannot compile your program. Because\nyou are providing a value that is \"runtime known\" to a function argument that must be \"compile-time known\".\n\nTake a look at this very simple example below, where we define a `twice()` function, that simply\ndoubles the input value named `num`. Notice that we use the `comptime` keyword before the name\nof the function argument. This keyword is marking the function argument `num` as a \"comptime argument\".\n\nThat is a function argument whose value must be compile-time known. This is why the expression\n`twice(5678)` is valid, and no compilation errors are raised. Because the value `5678`\nis compile-time known, so this is the expected behaviour for this function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file833f3ad20be9.test.test comptime...OKAll 1 \n   tests passed.\n```\n\n\n:::\n:::\n\n\n\n\nBut what if we provide a number that is not compile-time known to this function?\nFor example, we might provide a different input value to this function depending\non the target OS of our compilation process. The code example below demonstrates such case.\n\nBecause the value of the object `n` is determined at runtime, we cannot provide this object\nas input to the `twice()` function. The `zig` compiler will not allow it, because we marked\nthe `num` argument as a \"comptime argument\". That is why the `zig` compiler raises\nthe compile-time error exposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    var n: u32 = undefined;\n    if (builtin.target.os.tag == .windows) {\n        n = 1234;\n    } else {\n        n = 5678;\n    }\n    _ = twice(n);\n}\n```\n:::\n\n\n\n\n```\nt.zig:12:16: error: runtime-known argument passed to comptime parameter\n```\n\nComptime arguments are frequently used on functions that return some sort\nof generic structure. In fact, `comptime` is the essence (or the basis) to make generics in Zig.\nWe are going to talk more about generics in @sec-generics.\n\nFor now, let's take a look at this code example from @karlseguin_generics. You\ncan see that this `IntArray()` function has one argument named `length`.\nThis argument is marked as comptime, and receives a value of type `usize` as input. So the value given to this argument\nmust be compile-time known.\nWe can also see that this function returns an array of `i64` values as output.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n```\n:::\n\n\n\n\nNow, the key component of this function is the `length` argument. This argument\nis used to determine the size of the array that is produced by the function. Let's\nthink about the consequences of that. If the size of the array is dependent on\nthe value assigned to the `length` argument, this means that the data type of the\noutput of the function depends on the value of this `length` argument.\n\nLet this statement sink for a bit in your mind. As I described in @sec-root-file,\nZig is a strongly-typed language, especially on function declarations.\nSo every time we write a function in Zig, we have to annotate the data type of\nthe value returned by the function. But how can we do that, if this data type\ndepends on the value given to the argument of the function?\n\nThink about this for a second. If `length` is equal to 3 for example, then, the\nreturn type of the function is `[3]i64`. But if `length` is equal to 40, then,\nthe return type becomes `[40]i64`. At this point the `zig` compiler would be confused,\nand raise a compilation error, saying something like this:\n\n> Hey! You have annotated that this function should return a `[3]i64` value, but I got a `[40]i64` value instead! This doesn't look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when\nthe `type` keyword comes in. This `type` keyword is basically saying to the\n`zig` compiler that this function will return some data type as output, but it doesn't know yet\nwhat exactly data type that is. We will talk more about this in @sec-generics.\n\n\n\n### Applying over an expression\n\nWhen you apply the `comptime` keyword over an expression, then, it is guaranteed that the `zig` compiler will\nexecute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time\n(e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the `zig` compiler\nwill raise a compilation error.\n\nTake this example from the official documentation of Zig [@zigdocs]. We\nare executing the same `fibonacci()` function both at runtime, and, at compile-time.\nThe function is executed by default at runtime, but because we use the `comptime`\nkeyword in the second \"try expression\", this expression is executed at compile-time.\n\nThis might be a bit confusing for some people. Yes! When I say that this expression\nis executed at compile-time, I mean that this expression is compiled and executed\nwhile the `zig` compiler is compiling your Zig source code.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file833f119d55a3.test.fibonacci...OKAll 1 test\n  ts passed.\n```\n\n\n:::\n:::\n\n\n\n\nA lot of your Zig source code might be potentially executed at compile-time,\nbecause the `zig` compiler can figure out the output of some expressions.\nEspecially if these expressions depend only on compile-time known values.\nWe have talked about this in @sec-compile-time.\n\nBut when you use the `comptime` keyword on an expression, there is no \"it might be executed\nat compile-time\" anymore. With the `comptime` keyword you are ordering the `zig` compiler\nto execute this expression at compile-time. You are imposing this rule, it is guaranteed\nthat the compiler will always execute it at compile-time. Or, at least, the compiler\nwill try to execute it. If the compiler cannot execute the expression for whatever reason,\nthe compiler will raise a compilation error.\n\n\n### Applying over a block\n\nBlocks were described in @sec-blocks. When you apply the `comptime` keyword to a\nblock of expressions, you get essentially the same effect as when you apply this keyword to\na single expression. That is, the entire block of expressions is executed at\ncompile-time by the `zig` compiler.\n\nIn the example below, we mark the block labeled of `blk` as a comptime block,\nand, therefore, the expressions inside this block are executed at compile-time.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file833f6ccf145c.test.fibonacci in a block...O\n  OKAll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## Introducing Generics {#sec-generics}\n\nFirst of all, what is a generic? Generic is the idea to allow a type\n(`f64`, `u8`, `u32`, `bool`, and also, user-defined types, like the `User` struct\nthat we defined in @sec-structs-and-oop) to be a parameter to methods, classes and\ninterfaces [@geeks_generics]. In other words, a \"generic\" is a class (or a method) that can work\nwith multiple data types.\n\nFor example, in Java, generics are created through the operator `<>`. With this operator,\na Java class is capable of receiving a data type as input, and therefore, the class can fit\nits features according to this input data type.\nAs another example, generics in C++ are supported through the concept of templates.\nClass templates in C++ are generics.\n\nIn Zig, generics are implemented through `comptime`. The `comptime` keyword\nallows us to collect a data type at compile time, and pass this data type as\ninput to a piece of code.\n\n\n### A generic function {#sec-generic-fun}\n\nTake the `max()` function exposed below as a first example.\nThis function is essentially a \"generic function\".\nIn this function, we have a comptime function argument named `T`.\nNotice that this `T` argument has a data type of `type`. Weird right? This `type` keyword is the\n\"father of all types\", or, \"the type of types\" in Zig.\n\nBecause we have used this `type` keyword in the `T` argument, we are telling\nthe `zig` compiler that this `T` argument will receive some data type as input.\nAlso notice the use of the `comptime` keyword in this argument.\nAs I described in @sec-comptime, every time you use this keyword in a function argument,\nthis means that the value of this argument must be known at compile-time.\nThis makes sense, right? Because there is no data type that is not known at compile-time.\n\nThink about this. Every data type that you will ever write is always\nknown at compile-time. Especially because data types are an essential\ninformation for the compiler to actually compile your source code.\nHaving this in mind, makes sense to mark this argument as a comptime argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\n```\n:::\n\n\n\n\nAlso notice that the value of the `T` argument is actually used\nto define the data type of the other arguments in the function, `a` and `b`, and also at the\nreturn type annotation of the function.\nThat is, the data type of these arguments (`a` and `b`), and, the return data type of the function itself,\nare determined by the input value given to the `T` argument.\n\nAs a result, we have a generic function that works with different data types.\nFor example, I can provide `u8` values to this `max()` function, and it will work as expected.\nBut if I provide `f64` values instead, it will also work as expected.\nWithout a generic function, I would have to write a different `max()` function\nfor each data type I wanted to use.\nThis generic function provides a very useful shortcut for us.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\ntest \"test max\" {\n    const n1 = max(u8, 4, 10);\n    std.debug.print(\"Max n1: {d}\\n\", .{n1});\n    const n2 = max(f64, 89.24, 64.001);\n    std.debug.print(\"Max n2: {d}\\n\", .{n2});\n}\n```\n:::\n\n\n\n\n```\nMax n1: 10\nMax n2: 89.24\n```\n\n\n### A generic data structure {#sec-generic-struct}\n\nEvery data structure that you find in the Zig Standard Library (e.g. `ArrayList`, `HashMap`, etc.)\nis essentially a generic data structure.\nThese data structures are generic in the sense that they work with any data type you want.\nYou just say which is the data type of the values that are going to be stored in this data\nstructure, and they just work as expected.\n\nA generic data structure in Zig is how you replicate a generic class from Java,\nor, a class template from C++. But you may ask yourself: how do we build a\ngeneric data structure in Zig?\n\nThe basic idea is to write a generic function that creates the data structure definition\nfor the specific type we want. In other words, this generic function behaves as a \"factory of data structures\".\nThe generic function outputs the `struct` definition that defines this data structure for a\nspecific data type.\n\nTo create such function, we need to add a comptime argument to this function that receives a data type\nas input. We already learned how to do this in the previous section (@sec-generic-fun).\nI think the best way to demonstrate how to create a generic data structure is to actually write one.\nThis where we go into our next small project in this book. This one is a very small project,\nwhich is to write a generic stack data structure.\n\n\n\n\n## What is a stack? {#sec-what-stack}\n\nA stack data structure is a structure that follows a LIFO (*last in, first out*) principle.\nOnly two operations are normally supported in a stack data structure, which are `push` and `pop`.\nThe `push` operation is used to add new values to the stack, while `pop` is used to remove\nvalues from the stack.\n\nWhen people try to explain how the stack data structure works, the most common analogy\nthat they use is a stack of plates. Imagine that you have a stack of plates,\nfor example, a stack of 10 plates in your table. Each plate represents a value that\nis currently stored in this stack.\n\nWe begin with a stack of 10 different values, or 10 different plates. Now, imagine that you want to\nadd a new plate (or a new value) to this stack, which translates to the `push` operation.\nYou would add this plate (or this value) by just putting the new plate\non the top of the stack. Then, you would increase the stack to 11 plates.\n\nBut how would you remove plates (or remove values) from this stack (a.k.a. the `pop` operation) ?\nTo do that, we would have to remove the plate on the top of the stack, and, as a result, we would\nhave, once again, 10 plates in the stack.\n\nThis demonstrates the LIFO concept, because the first plate in the stack, which is the plate\nin the bottom of the stack, is always the last plate to get out of the stack. Think about it. In order\nto remove this specific plate from the stack, we have to remove all plates in the\nstack. So every operation in the stack, either insertion or deletion, is always made at the top of the stack.\nThe @fig-stack below exposes this logic visually:\n\n![A diagram of a stack structure. Source: Wikipedia, the free encyclopedia.](./../Figures/lifo-stack.svg){#fig-stack}\n\n\n\n## Writing the stack data structure\n\nWe are going to write the stack data structure in two steps. First, we are going\nto implement a stack that can only store `u32` values. Then, after that, we are going\nto extend our implementation to make it generic, so that it works with any data type\nwe want.\n\nFirst, we need to decide how the values will be stored inside the stack. There are multiple\nways to implement the storage behind a stack structure. Some people prefer to use a doubly linked list,\nothers prefer to use a dynamic array, etc. In this example we are going to use an array behind the hood,\nto store the values in the stack, which is the `items` data member of our `Stack` struct definition.\n\nAlso notice in our `Stack` struct that we have three other data members: `capacity`, `length` and `allocator`.\nThe `capacity` member contains the capacity of the underlying array that stores the values in the stack.\nThe `length` contains the number of values that are currently being stored in the stack.\nAnd the `allocator` contains the allocator object that will be used by the stack structure whenever it\nneeds to allocate more space for the values that are being stored.\n\nWe begin by defining an `init()` method of this struct, which is going to be\nresponsible for instantiating a `Stack` object. Notice that, inside this\n`init()` method, we start by allocating an array with the capacity specified\nin the `capacity` argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst Stack = struct {\n    items: []u32,\n    capacity: usize,\n    length: usize,\n    allocator: Allocator,\n\n    pub fn init(allocator: Allocator, capacity: usize) !Stack {\n        var buf = try allocator.alloc(u32, capacity);\n        return .{\n            .items = buf[0..],\n            .capacity = capacity,\n            .length = 0,\n            .allocator = allocator,\n        };\n    }\n};\n```\n:::\n\n\n\n\n\n### Implementing the `push` operation\n\nNow that we have written the basic logic to create a new `Stack` object,\nwe can start writing the logic responsible for performing a push operation.\nRemember, a push operation in a stack data structure is the operation\nresponsible for adding a new value to the stack.\n\nSo how can we add a new value to the `Stack` object that we have?\nThe `push()` function exposed below is a possible answer to this question.\nRemember from what we discussed in @sec-what-stack that values are always added to the top of the stack.\nThis means that this `push()` function must always find the element in the underlying array\nthat currently represents the top position of the stack, and then, add the input value there.\n\nFirst, we have an if statement in this function. This if statement is\nchecking whether we need to expand the underlying array to store\nthis new value that we are adding to the stack. In other words, maybe\nthe underlying array does not have enough capacity to store this new\nvalue, and, in this case, we need to expand our array to get the capacity that we need.\n\nSo, if the logical test in this if statement returns true, it means that the array\ndoes not have enough capacity, and we need to expand it before we store this new value.\nSo inside this if statement we are executing the necessary expressions to expand the underlying array.\nNotice that we use the allocator object to allocate a new array that is twice as bigger\nthan the current array (`self.capacity * 2`).\n\nAfter that, we use a different built-in function named `@memcpy()`. This built-in function\nis equivalent to the `memcpy()` function from the C Standard Library[^cmemcpy]. It's used to\ncopy the values from one block of memory to another block of memory. In other words,\nyou can use this function to copy the values from one array into another array.\n\n[^cmemcpy]: <https://www.tutorialspoint.com/c_standard_library/c_function_memcpy.htm>\n\nWe are using this `@memcpy()` built-in function to copy the values that are currently stored\nin the underlying array of the stack object (`self.items`) into our new and bigger array that\nwe have allocated (`new_buf`). After we execute this function, the `new_buf` contains a copy\nof the values that are present at `self.items`.\n\nNow that we have secured a copy of our current values in the `new_buf` object, we\ncan now free the memory currently allocated at `self.items`. After that, we just need\nto assign our new and bigger array to `self.items`. This is the sequence\nof steps necessary to expand our array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn push(self: *Stack, val: u32) !void {\n    if ((self.length + 1) > self.capacity) {\n        var new_buf = try self.allocator.alloc(\n            u32, self.capacity * 2\n        );\n        @memcpy(\n            new_buf[0..self.capacity], self.items\n        );\n        self.allocator.free(self.items);\n        self.items = new_buf;\n        self.capacity = self.capacity * 2;\n    }\n\n    self.items[self.length] = val;\n    self.length += 1;\n}\n```\n:::\n\n\n\n\nAfter we make sure that we have enough room to store this new value\nthat we are adding to the stack, all we have to do is to assign\nthis value to the top element in this stack, and, increase the\nvalue of the `length` attribute by one. We find the top element\nin the stack by using the `length` attribute.\n\n\n\n### Implementing the `pop` operation\n\nNow we can implement the pop operation of our stack object.\nThis is a much easier operation to implement, and the `pop()` method below summarises\nall the logic that is needed.\n\nWe just have to find the element in the underlying array that currently represents the top\nof the stack, and set this element to \"undefined\", to indicate that\nthis element is \"empty\". After that, we also need to decrease\nthe `length` attribute of the stack by one.\n\nIf the current length of the stack is zero, it means that there is\nno values being stored in the stack currently. So, in this case,\nwe could just return from the function and do nothing really.\nThis is what the if statement inside this function is checking for.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn pop(self: *Stack) void {\n    if (self.length == 0) return;\n\n    self.items[self.length - 1] = undefined;\n    self.length -= 1;\n}\n```\n:::\n\n\n\n\n\n\n### Implementing the `deinit` method\n\nWe have implemented the methods responsible for the two main operations\nassociated with the stack data structure, which is `pop()` and `push()`,\nand we also have implemented the method responsible for instantiating\na new `Stack` object, which is the `init()` method.\n\nBut now, we need to implement also the method responsible for destroying\na `Stack` object. In Zig, this task is commonly associated with the method\nnamed `deinit()`. Most struct objects in Zig have such method, and it\nis commonly nicknamed \"the destructor method\".\n\nIn theory, all we have to do to destroy the `Stack` object is to make\nsure that we free the allocated memory for the underlying array, using\nthe allocator object that is stored inside the `Stack` object.\nThis is what the `deinit()` method below is doing.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn deinit(self: *Stack) void {\n    self.allocator.free(self.items);\n}\n```\n:::\n\n\n\n\n\n\n\n## Making it generic\n\nNow that we have implemented the basic skeleton of our stack data structure,\nwe can now focus on discussing how we can make it generic. How can we make\nthis basic skeleton to work not only with `u32` values, but also with any other\ndata type we want?\nFor example, we might need to create a stack object to store `User` values\nin it. How can we make this possible? The answer lies in the use of generics\nand `comptime`.\n\nAs I described in @sec-generic-struct, the basic idea is to write a generic\nfunction that returns a struct definition as output.\nIn theory, we do not need much to transform our `Stack` struct into a generic\ndata structure. All that we need to do is to transform the underlying array\nof the stack into a generic array.\n\nIn other words, this underlying array needs to be a \"chameleon\". It needs to adapt,\nand transform it into an array of any data type that we want. For example, if we need to create\na stack that will store `u8` values, then this underlying array needs to be\na `u8` array (i.e., `[]u8`). But if we need to store `User` values instead, then,\nthis array needs to be a `User` array (i.e., `[]User`). Etc.\n\nWe do that by using a generic function. Because a generic function can receive a data type\nas input, and we can pass this data type to the struct definition of our `Stack` object.\nTherefore, we can use the generic function to create a `Stack` object that can store\nthe data type we want. If we want to create a stack structure that stores `User` values,\nwe pass the `User` data type to this generic function, and it will create for us\nthe struct definition that describes a `Stack` object that can store `User` values in it.\n\nLook at the code example below. I have omitted some parts of the `Stack` struct definition\nfor brevity. However, if a specific part of our `Stack` struct is not exposed here\nin this example, then it's because this part did not change from the previous example.\nIt remains the same.\n\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn Stack(comptime T: type) type {\n    return struct {\n        items: []T,\n        capacity: usize,\n        length: usize,\n        allocator: Allocator,\n        const Self = @This();\n\n        pub fn init(allocator: Allocator,\n                    capacity: usize) !Stack(T) {\n            var buf = try allocator.alloc(T, capacity);\n            return .{\n                .items = buf[0..],\n                .capacity = capacity,\n                .length = 0,\n                .allocator = allocator,\n            };\n        }\n\n        pub fn push(self: *Self, val: T) !void {\n        // Truncate the rest of the struct\n    };\n}\n```\n:::\n\n\n\n\nNotice that we have created a function in this example named `Stack()`. This function\ntakes a type as input, and passes this type to the struct definition of our\n`Stack` object. The data member `items` is now, an array of type `T`, which is the\ndata type that we have provided as input to the function. The function argument\n`val` in the `push()` function is now a value of type `T` too.\n\nWe can just provide a data type to this function, and it will create a definition of a\n`Stack` object that can store values of the data type that we have provided. In the example below, we are creating\nthe definition of a\n`Stack` object that can store `u8` values in it. This definition is stored at the `Stacku8` object.\nThis `Stacku8` object becomes our new struct, that we are going to use\nto create our `Stack` object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst Stacku8 = Stack(u8);\nvar stack = try Stacku8.init(allocator, 10);\ndefer stack.deinit();\ntry stack.push(1);\ntry stack.push(2);\ntry stack.push(3);\ntry stack.push(4);\ntry stack.push(5);\ntry stack.push(6);\n\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\"Stack capacity: {d}\\n\", .{stack.capacity});\n\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\n    \"Stack state: {any}\\n\",\n    .{stack.items[0..stack.length]}\n);\n```\n:::\n\n\n\n\n```\nStack len: 6\nStack capacity: 10\nStack len: 5\nStack len: 4\nStack state: { 1, 2, 3, 4, 0, 0, 0, 0, 0, 0 }\n```\n\nEvery generic data structure in the Zig Standard Library (`ArrayList`, `HashMap`, `SinlyLinkedList`, etc.)\nis implemented through this logic. They use a generic function to create the struct definition that can work\nwith the data type that you provided as input.\n\n\n\n\n## Conclusion\n\nThe full source code of the stack structure discussed in this chapter is freely available in the official\nrepository of this book. Just checkout the [`stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig)[^zig-stack]\nfor the `u32` version of our stack,\nand the [`generic_stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig)[^zig-stack2]\nfor the generic version, available inside the `ZigExamples` folder of the repository.\n\n\n[^zig-stack]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig>\n[^zig-stack2]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig>\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 3 - Building a stack data structure\n\nIn this chapter we are going to implement a stack data structure as our next small project\nin this book. Implementing basic data structures in any language is kind of a\n\"kindergarten task\" (if this term even exist) in computer science (CS), because\nwe normally learn and implement them in the first semesters of CS.\n\nBut this is actually good! Since this should be a very easy task, we don't need much to explain\nwhat a stack is, then, we can concentrate on what is really important here, which is learning\nhow the concept of \"generics\" is implemented in the Zig language, and how one of the key\nfeatures of Zig, which is comptime, works, and use the stack data structure to demonstrate\nthese concepts on the fly.\n\nBut before we get into building the stack data structure, we first need to understand\nwhat the `comptime` keyword does to your code, and after that, we also need to learn about\nhow generics work in Zig.\n\n\n## Understanding `comptime` in Zig {#sec-comptime}\n\nOne of the key features of Zig is `comptime`. This keyword introduces a whole\nnew concept and paradigm, that is tightly connected with the compilation process.\nIn @sec-compile-time we have described the importance and the role that \"compile-time versus runtime\"\nplays into Zig. In that section, we learned that the rules applied to a value/object change\na lot depending on whether this value is known at compile-time, or just at runtime.\n\nThe `comptime` keyword is strongly related to these two spaces in time (compile-time and runtime).\nLet's quickly recap the differences. Compile-time is the period of time when your\nZig source code is being compiled by the `zig` compiler, while the runtime is\nthe period of time when your Zig program is being executed, i.e., when we execute\nthe binary files that were generated by the `zig` compiler.\n\nThere are three ways in which you can apply the `comptime` keyword, which are:\n\n- apply `comptime` on a function argument.\n- apply `comptime` on an object.\n- apply `comptime` on a block of expressions.\n\n\n\n### Applying over a function argument\n\nWhen you apply the `comptime` keyword on a function argument, you are saying to the `zig` compiler\nthat the value assigned to that particular function argument must be known at compile-time.\nWe explained in detail in @sec-compile-time what exactly \"value known at compile-time\" means. So\nif you have any doubts about this idea, refer back to that section.\n\nNow let's think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement\nto that particular function argument. If the programmer accidentally tries to give a value to this\nfunction argument that is not known at compile time, the `zig` compiler will notice this problem, and\nas a consequence, it will raise a compilation error saying that it cannot compile your program. Because\nyou are providing a value that is \"runtime known\" to a function argument that must be \"compile-time known\".\n\nTake a look at this very simple example below, where we define a `twice()` function, that simply\ndoubles the input value named `num`. Notice that we use the `comptime` keyword before the name\nof the function argument. This keyword is marking the function argument `num` as a \"comptime argument\".\n\nThat is a function argument whose value must be compile-time known. This is why the expression\n`twice(5678)` is valid, and no compilation errors are raised. Because the value `5678`\nis compile-time known, so this is the expected behaviour for this function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filee87436f6bc4a.test.test comptime...OKAll 1 \n   tests passed.\n```\n\n\n:::\n:::\n\n\n\n\nBut what if we provide a number that is not compile-time known to this function?\nFor example, your program might receive some input from the user through the `stdin`\nchannel of your system. This input from the user might be many different things,\nand cannot be predicted at compile-time. These circumstances make this \"input\nfrom the user\" a value that is runtime-known only.\n\nIn the example below, this \"input from the user\" is initially received as a string,\nwhich is then parsed and transformed into a integer value, and the result of this operation\nis stored inside the `n` object.\n\nBecause the \"input of the user\" is known only at runtime, the value of the object `n` is determined only at runtime.\nAs consequence, we cannot provide this object as input to the `twice()` function.\nThe `zig` compiler will not allow it, because we marked\nthe `num` argument as a \"comptime argument\". That is why the `zig` compiler raises\nthe compile-time error exposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\n\npub fn main() !void {\n    var buffer: [5]u8 = .{ 0, 0, 0, 0, 0 };\n    const stdout = std.io.getStdOut().writer();\n    const stdin = std.io.getStdIn().reader();\n    _ = try stdout.write(\"Please write a 4-digit integer number\\n\");\n    _ = try stdin.readUntilDelimiter(&buffer, '\\n');\n\n    try stdout.print(\"Input: {s}\", .{buffer});\n    const n: u32 = try std.fmt.parseInt(\n        u32, buffer[0 .. buffer.len - 1], 10\n    );\n    const twice_result = twice(n);\n    try stdout.print(\"Result: {d}\\n\", .{twice_result});\n}\n```\n:::\n\n\n\n\n```\nt.zig:12:16: error: unable to resolve comptime value\n    const twice_result = twice(n);\n                               ^\n```\n\nComptime arguments are frequently used on functions that return some sort\nof generic structure. In fact, `comptime` is the essence (or the basis) to make generics in Zig.\nWe are going to talk more about generics in @sec-generics.\n\nFor now, let's take a look at this code example from @karlseguin_generics. You\ncan see that this `IntArray()` function has one argument named `length`.\nThis argument is marked as comptime, and receives a value of type `usize` as input. So the value given to this argument\nmust be compile-time known.\nWe can also see that this function returns an array of `i64` values as output.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n```\n:::\n\n\n\n\nNow, the key component of this function is the `length` argument. This argument\nis used to determine the size of the array that is produced by the function. Let's\nthink about the consequences of that. If the size of the array is dependent on\nthe value assigned to the `length` argument, this means that the data type of the\noutput of the function depends on the value of this `length` argument.\n\nLet this statement sink for a bit in your mind. As I described in @sec-root-file,\nZig is a strongly-typed language, especially on function declarations.\nSo every time we write a function in Zig, we have to annotate the data type of\nthe value returned by the function. But how can we do that, if this data type\ndepends on the value given to the argument of the function?\n\nThink about this for a second. If `length` is equal to 3 for example, then, the\nreturn type of the function is `[3]i64`. But if `length` is equal to 40, then,\nthe return type becomes `[40]i64`. At this point the `zig` compiler would be confused,\nand raise a compilation error, saying something like this:\n\n> Hey! You have annotated that this function should return a `[3]i64` value, but I got a `[40]i64` value instead! This doesn't look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when\nthe `type` keyword comes in. This `type` keyword is basically saying to the\n`zig` compiler that this function will return some data type as output, but it doesn't know yet\nwhat exactly data type that is. We will talk more about this in @sec-generics.\n\n\n\n### Applying over an expression\n\nWhen you apply the `comptime` keyword over an expression, then, it is guaranteed that the `zig` compiler will\nexecute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time\n(e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the `zig` compiler\nwill raise a compilation error.\n\nTake this example from the official documentation of Zig [@zigdocs]. We\nare executing the same `fibonacci()` function both at runtime, and, at compile-time.\nThe function is executed by default at runtime, but because we use the `comptime`\nkeyword in the second \"try expression\", this expression is executed at compile-time.\n\nThis might be a bit confusing for some people. Yes! When I say that this expression\nis executed at compile-time, I mean that this expression is compiled and executed\nwhile the `zig` compiler is compiling your Zig source code.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filee874b9644b4.test.fibonacci...OKAll 1 tests\n  s passed.\n```\n\n\n:::\n:::\n\n\n\n\nA lot of your Zig source code might be potentially executed at compile-time,\nbecause the `zig` compiler can figure out the output of some expressions.\nEspecially if these expressions depend only on compile-time known values.\nWe have talked about this in @sec-compile-time.\n\nBut when you use the `comptime` keyword on an expression, there is no \"it might be executed\nat compile-time\" anymore. With the `comptime` keyword you are ordering the `zig` compiler\nto execute this expression at compile-time. You are imposing this rule, it is guaranteed\nthat the compiler will always execute it at compile-time. Or, at least, the compiler\nwill try to execute it. If the compiler cannot execute the expression for whatever reason,\nthe compiler will raise a compilation error.\n\n\n### Applying over a block\n\nBlocks were described in @sec-blocks. When you apply the `comptime` keyword to a\nblock of expressions, you get essentially the same effect as when you apply this keyword to\na single expression. That is, the entire block of expressions is executed at\ncompile-time by the `zig` compiler.\n\nIn the example below, we mark the block labeled of `blk` as a comptime block,\nand, therefore, the expressions inside this block are executed at compile-time.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filee8746560ae87.test.fibonacci in a block...O\n  OKAll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## Introducing Generics {#sec-generics}\n\nFirst of all, what is a generic? Generic is the idea to allow a type\n(`f64`, `u8`, `u32`, `bool`, and also, user-defined types, like the `User` struct\nthat we defined in @sec-structs-and-oop) to be a parameter to methods, classes and\ninterfaces [@geeks_generics]. In other words, a \"generic\" is a class (or a method) that can work\nwith multiple data types.\n\nFor example, in Java, generics are created through the operator `<>`. With this operator,\na Java class is capable of receiving a data type as input, and therefore, the class can fit\nits features according to this input data type.\nAs another example, generics in C++ are supported through the concept of templates.\nClass templates in C++ are generics.\n\nIn Zig, generics are implemented through `comptime`. The `comptime` keyword\nallows us to collect a data type at compile time, and pass this data type as\ninput to a piece of code.\n\n\n### A generic function {#sec-generic-fun}\n\nTake the `max()` function exposed below as a first example.\nThis function is essentially a \"generic function\".\nIn this function, we have a comptime function argument named `T`.\nNotice that this `T` argument has a data type of `type`. Weird right? This `type` keyword is the\n\"father of all types\", or, \"the type of types\" in Zig.\n\nBecause we have used this `type` keyword in the `T` argument, we are telling\nthe `zig` compiler that this `T` argument will receive some data type as input.\nAlso notice the use of the `comptime` keyword in this argument.\nAs I described in @sec-comptime, every time you use this keyword in a function argument,\nthis means that the value of this argument must be known at compile-time.\nThis makes sense, right? Because there is no data type that is not known at compile-time.\n\nThink about this. Every data type that you will ever write is always\nknown at compile-time. Especially because data types are an essential\ninformation for the compiler to actually compile your source code.\nHaving this in mind, makes sense to mark this argument as a comptime argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\n```\n:::\n\n\n\n\nAlso notice that the value of the `T` argument is actually used\nto define the data type of the other arguments in the function, `a` and `b`, and also at the\nreturn type annotation of the function.\nThat is, the data type of these arguments (`a` and `b`), and, the return data type of the function itself,\nare determined by the input value given to the `T` argument.\n\nAs a result, we have a generic function that works with different data types.\nFor example, I can provide `u8` values to this `max()` function, and it will work as expected.\nBut if I provide `f64` values instead, it will also work as expected.\nWithout a generic function, I would have to write a different `max()` function\nfor each data type I wanted to use.\nThis generic function provides a very useful shortcut for us.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\ntest \"test max\" {\n    const n1 = max(u8, 4, 10);\n    std.debug.print(\"Max n1: {d}\\n\", .{n1});\n    const n2 = max(f64, 89.24, 64.001);\n    std.debug.print(\"Max n2: {d}\\n\", .{n2});\n}\n```\n:::\n\n\n\n\n```\nMax n1: 10\nMax n2: 89.24\n```\n\n\n### A generic data structure {#sec-generic-struct}\n\nEvery data structure that you find in the Zig Standard Library (e.g. `ArrayList`, `HashMap`, etc.)\nis essentially a generic data structure.\nThese data structures are generic in the sense that they work with any data type you want.\nYou just say which is the data type of the values that are going to be stored in this data\nstructure, and they just work as expected.\n\nA generic data structure in Zig is how you replicate a generic class from Java,\nor, a class template from C++. But you may ask yourself: how do we build a\ngeneric data structure in Zig?\n\nThe basic idea is to write a generic function that creates the data structure definition\nfor the specific type we want. In other words, this generic function behaves as a \"factory of data structures\".\nThe generic function outputs the `struct` definition that defines this data structure for a\nspecific data type.\n\nTo create such function, we need to add a comptime argument to this function that receives a data type\nas input. We already learned how to do this in the previous section (@sec-generic-fun).\nI think the best way to demonstrate how to create a generic data structure is to actually write one.\nThis where we go into our next small project in this book. This one is a very small project,\nwhich is to write a generic stack data structure.\n\n\n\n\n## What is a stack? {#sec-what-stack}\n\nA stack data structure is a structure that follows a LIFO (*last in, first out*) principle.\nOnly two operations are normally supported in a stack data structure, which are `push` and `pop`.\nThe `push` operation is used to add new values to the stack, while `pop` is used to remove\nvalues from the stack.\n\nWhen people try to explain how the stack data structure works, the most common analogy\nthat they use is a stack of plates. Imagine that you have a stack of plates,\nfor example, a stack of 10 plates in your table. Each plate represents a value that\nis currently stored in this stack.\n\nWe begin with a stack of 10 different values, or 10 different plates. Now, imagine that you want to\nadd a new plate (or a new value) to this stack, which translates to the `push` operation.\nYou would add this plate (or this value) by just putting the new plate\non the top of the stack. Then, you would increase the stack to 11 plates.\n\nBut how would you remove plates (or remove values) from this stack (a.k.a. the `pop` operation) ?\nTo do that, we would have to remove the plate on the top of the stack, and, as a result, we would\nhave, once again, 10 plates in the stack.\n\nThis demonstrates the LIFO concept, because the first plate in the stack, which is the plate\nin the bottom of the stack, is always the last plate to get out of the stack. Think about it. In order\nto remove this specific plate from the stack, we have to remove all plates in the\nstack. So every operation in the stack, either insertion or deletion, is always made at the top of the stack.\nThe @fig-stack below exposes this logic visually:\n\n![A diagram of a stack structure. Source: Wikipedia, the free encyclopedia.](./../Figures/lifo-stack.svg){#fig-stack}\n\n\n\n## Writing the stack data structure\n\nWe are going to write the stack data structure in two steps. First, we are going\nto implement a stack that can only store `u32` values. Then, after that, we are going\nto extend our implementation to make it generic, so that it works with any data type\nwe want.\n\nFirst, we need to decide how the values will be stored inside the stack. There are multiple\nways to implement the storage behind a stack structure. Some people prefer to use a doubly linked list,\nothers prefer to use a dynamic array, etc. In this example we are going to use an array behind the hood,\nto store the values in the stack, which is the `items` data member of our `Stack` struct definition.\n\nAlso notice in our `Stack` struct that we have three other data members: `capacity`, `length` and `allocator`.\nThe `capacity` member contains the capacity of the underlying array that stores the values in the stack.\nThe `length` contains the number of values that are currently being stored in the stack.\nAnd the `allocator` contains the allocator object that will be used by the stack structure whenever it\nneeds to allocate more space for the values that are being stored.\n\nWe begin by defining an `init()` method of this struct, which is going to be\nresponsible for instantiating a `Stack` object. Notice that, inside this\n`init()` method, we start by allocating an array with the capacity specified\nin the `capacity` argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst Stack = struct {\n    items: []u32,\n    capacity: usize,\n    length: usize,\n    allocator: Allocator,\n\n    pub fn init(allocator: Allocator, capacity: usize) !Stack {\n        var buf = try allocator.alloc(u32, capacity);\n        return .{\n            .items = buf[0..],\n            .capacity = capacity,\n            .length = 0,\n            .allocator = allocator,\n        };\n    }\n};\n```\n:::\n\n\n\n\n\n### Implementing the `push` operation\n\nNow that we have written the basic logic to create a new `Stack` object,\nwe can start writing the logic responsible for performing a push operation.\nRemember, a push operation in a stack data structure is the operation\nresponsible for adding a new value to the stack.\n\nSo how can we add a new value to the `Stack` object that we have?\nThe `push()` function exposed below is a possible answer to this question.\nRemember from what we discussed in @sec-what-stack that values are always added to the top of the stack.\nThis means that this `push()` function must always find the element in the underlying array\nthat currently represents the top position of the stack, and then, add the input value there.\n\nFirst, we have an if statement in this function. This if statement is\nchecking whether we need to expand the underlying array to store\nthis new value that we are adding to the stack. In other words, maybe\nthe underlying array does not have enough capacity to store this new\nvalue, and, in this case, we need to expand our array to get the capacity that we need.\n\nSo, if the logical test in this if statement returns true, it means that the array\ndoes not have enough capacity, and we need to expand it before we store this new value.\nSo inside this if statement we are executing the necessary expressions to expand the underlying array.\nNotice that we use the allocator object to allocate a new array that is twice as bigger\nthan the current array (`self.capacity * 2`).\n\nAfter that, we use a different built-in function named `@memcpy()`. This built-in function\nis equivalent to the `memcpy()` function from the C Standard Library[^cmemcpy]. It's used to\ncopy the values from one block of memory to another block of memory. In other words,\nyou can use this function to copy the values from one array into another array.\n\n[^cmemcpy]: <https://www.tutorialspoint.com/c_standard_library/c_function_memcpy.htm>\n\nWe are using this `@memcpy()` built-in function to copy the values that are currently stored\nin the underlying array of the stack object (`self.items`) into our new and bigger array that\nwe have allocated (`new_buf`). After we execute this function, the `new_buf` contains a copy\nof the values that are present at `self.items`.\n\nNow that we have secured a copy of our current values in the `new_buf` object, we\ncan now free the memory currently allocated at `self.items`. After that, we just need\nto assign our new and bigger array to `self.items`. This is the sequence\nof steps necessary to expand our array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn push(self: *Stack, val: u32) !void {\n    if ((self.length + 1) > self.capacity) {\n        var new_buf = try self.allocator.alloc(\n            u32, self.capacity * 2\n        );\n        @memcpy(\n            new_buf[0..self.capacity], self.items\n        );\n        self.allocator.free(self.items);\n        self.items = new_buf;\n        self.capacity = self.capacity * 2;\n    }\n\n    self.items[self.length] = val;\n    self.length += 1;\n}\n```\n:::\n\n\n\n\nAfter we make sure that we have enough room to store this new value\nthat we are adding to the stack, all we have to do is to assign\nthis value to the top element in this stack, and, increase the\nvalue of the `length` attribute by one. We find the top element\nin the stack by using the `length` attribute.\n\n\n\n### Implementing the `pop` operation\n\nNow we can implement the pop operation of our stack object.\nThis is a much easier operation to implement, and the `pop()` method below summarises\nall the logic that is needed.\n\nWe just have to find the element in the underlying array that currently represents the top\nof the stack, and set this element to \"undefined\", to indicate that\nthis element is \"empty\". After that, we also need to decrease\nthe `length` attribute of the stack by one.\n\nIf the current length of the stack is zero, it means that there is\nno values being stored in the stack currently. So, in this case,\nwe could just return from the function and do nothing really.\nThis is what the if statement inside this function is checking for.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn pop(self: *Stack) void {\n    if (self.length == 0) return;\n\n    self.items[self.length - 1] = undefined;\n    self.length -= 1;\n}\n```\n:::\n\n\n\n\n\n\n### Implementing the `deinit` method\n\nWe have implemented the methods responsible for the two main operations\nassociated with the stack data structure, which is `pop()` and `push()`,\nand we also have implemented the method responsible for instantiating\na new `Stack` object, which is the `init()` method.\n\nBut now, we need to implement also the method responsible for destroying\na `Stack` object. In Zig, this task is commonly associated with the method\nnamed `deinit()`. Most struct objects in Zig have such method, and it\nis commonly nicknamed \"the destructor method\".\n\nIn theory, all we have to do to destroy the `Stack` object is to make\nsure that we free the allocated memory for the underlying array, using\nthe allocator object that is stored inside the `Stack` object.\nThis is what the `deinit()` method below is doing.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn deinit(self: *Stack) void {\n    self.allocator.free(self.items);\n}\n```\n:::\n\n\n\n\n\n\n\n## Making it generic\n\nNow that we have implemented the basic skeleton of our stack data structure,\nwe can now focus on discussing how we can make it generic. How can we make\nthis basic skeleton to work not only with `u32` values, but also with any other\ndata type we want?\nFor example, we might need to create a stack object to store `User` values\nin it. How can we make this possible? The answer lies in the use of generics\nand `comptime`.\n\nAs I described in @sec-generic-struct, the basic idea is to write a generic\nfunction that returns a struct definition as output.\nIn theory, we do not need much to transform our `Stack` struct into a generic\ndata structure. All that we need to do is to transform the underlying array\nof the stack into a generic array.\n\nIn other words, this underlying array needs to be a \"chameleon\". It needs to adapt,\nand transform it into an array of any data type that we want. For example, if we need to create\na stack that will store `u8` values, then this underlying array needs to be\na `u8` array (i.e., `[]u8`). But if we need to store `User` values instead, then,\nthis array needs to be a `User` array (i.e., `[]User`). Etc.\n\nWe do that by using a generic function. Because a generic function can receive a data type\nas input, and we can pass this data type to the struct definition of our `Stack` object.\nTherefore, we can use the generic function to create a `Stack` object that can store\nthe data type we want. If we want to create a stack structure that stores `User` values,\nwe pass the `User` data type to this generic function, and it will create for us\nthe struct definition that describes a `Stack` object that can store `User` values in it.\n\nLook at the code example below. I have omitted some parts of the `Stack` struct definition\nfor brevity. However, if a specific part of our `Stack` struct is not exposed here\nin this example, then it's because this part did not change from the previous example.\nIt remains the same.\n\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn Stack(comptime T: type) type {\n    return struct {\n        items: []T,\n        capacity: usize,\n        length: usize,\n        allocator: Allocator,\n        const Self = @This();\n\n        pub fn init(allocator: Allocator,\n                    capacity: usize) !Stack(T) {\n            var buf = try allocator.alloc(T, capacity);\n            return .{\n                .items = buf[0..],\n                .capacity = capacity,\n                .length = 0,\n                .allocator = allocator,\n            };\n        }\n\n        pub fn push(self: *Self, val: T) !void {\n        // Truncate the rest of the struct\n    };\n}\n```\n:::\n\n\n\n\nNotice that we have created a function in this example named `Stack()`. This function\ntakes a type as input, and passes this type to the struct definition of our\n`Stack` object. The data member `items` is now, an array of type `T`, which is the\ndata type that we have provided as input to the function. The function argument\n`val` in the `push()` function is now a value of type `T` too.\n\nWe can just provide a data type to this function, and it will create a definition of a\n`Stack` object that can store values of the data type that we have provided. In the example below, we are creating\nthe definition of a\n`Stack` object that can store `u8` values in it. This definition is stored at the `Stacku8` object.\nThis `Stacku8` object becomes our new struct, that we are going to use\nto create our `Stack` object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst Stacku8 = Stack(u8);\nvar stack = try Stacku8.init(allocator, 10);\ndefer stack.deinit();\ntry stack.push(1);\ntry stack.push(2);\ntry stack.push(3);\ntry stack.push(4);\ntry stack.push(5);\ntry stack.push(6);\n\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\"Stack capacity: {d}\\n\", .{stack.capacity});\n\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\n    \"Stack state: {any}\\n\",\n    .{stack.items[0..stack.length]}\n);\n```\n:::\n\n\n\n\n```\nStack len: 6\nStack capacity: 10\nStack len: 5\nStack len: 4\nStack state: { 1, 2, 3, 4, 0, 0, 0, 0, 0, 0 }\n```\n\nEvery generic data structure in the Zig Standard Library (`ArrayList`, `HashMap`, `SinlyLinkedList`, etc.)\nis implemented through this logic. They use a generic function to create the struct definition that can work\nwith the data type that you provided as input.\n\n\n\n\n## Conclusion\n\nThe full source code of the stack structure discussed in this chapter is freely available in the official\nrepository of this book. Just checkout the [`stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig)[^zig-stack]\nfor the `u32` version of our stack,\nand the [`generic_stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig)[^zig-stack2]\nfor the generic version, available inside the `ZigExamples` folder of the repository.\n\n\n[^zig-stack]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig>\n[^zig-stack2]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig>\n",
     "supporting": [
       "10-stack-project_files"
     ],
diff --git a/docs/Chapters/01-zig-weird.html b/docs/Chapters/01-zig-weird.html
index f10d7032..34c1d875 100644
--- a/docs/Chapters/01-zig-weird.html
+++ b/docs/Chapters/01-zig-weird.html
@@ -766,7 +766,9 @@ <h3 data-number="1.6.4" class="anchored" data-anchor-id="runtime-versus-compile-
 <span id="cb44-8"><a href="#cb44-8" aria-hidden="true" tabindex="-1"></a>_ = slice;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>On the other hand, if the range of indexes is not known at compile time, then, the slice object that gets created is not a pointer anymore, and, thus, it does not support pointer operations. For example, maybe the start index is known at compile time, but the end index is not. In such case, the range of the slice becomes runtime known only.</p>
-<p>In the example below, the <code>slice</code> object have a runtime known range, because the end index of the range is not known at compile time. In other words, the size of the array at <code>buffer</code> is not known at compile time. When we execute this program, the size of the array might be 10, or, it might be 12 depending on where we execute it. Therefore, we don’t know at compile time if the slice object have a range of size 10, or, a range of size 12.</p>
+<p>In the example below, we are reading a file, and then, we try to create a slice object that covers the entire buffer that contains the contents of this file. This is obviously an example of a runtime known range, because the end index of the range is not known at compile time.</p>
+<p>In other words, the end index of the range is the size of the array <code>file_contents</code>. However, the size of <code>file_contents</code> is not known at compile time. Because we don’t know how many bytes are stored inside this <code>shop-list.txt</code> file. And because this is a file, someone might edit this file tomorrow and add more lines or remove lines from it. Therefore, the size of this file might vary drastically from one execution to another.</p>
+<p>Now, if the file size can vary from one run to another, then, we can conclude that the value of the expression <code>file_contents.len</code> exposed in the example below can also vary from one run to another. As consequence, the value of the expression <code>file_contents.len</code> is runtime-known only, and, as a consequence of that, the range <code>0..file_contents.len</code> is also runtime-known only.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb45"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb45-1"><a href="#cb45-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb45-2"><a href="#cb45-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> builtin = <span class="bu">@import</span>(<span class="st">"builtin"</span>);</span>
@@ -774,20 +776,19 @@ <h3 data-number="1.6.4" class="anchored" data-anchor-id="runtime-versus-compile-
 <span id="cb45-4"><a href="#cb45-4" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> read_file(allocator: std.mem.Allocator, path: []<span class="kw">const</span> <span class="dt">u8</span>) ![]<span class="dt">u8</span> <span class="op">{</span></span>
 <span id="cb45-5"><a href="#cb45-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> file = <span class="kw">try</span> std.fs.cwd().openFile(path, .<span class="op">{}</span>);</span>
 <span id="cb45-6"><a href="#cb45-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">defer</span> file.close();</span>
-<span id="cb45-7"><a href="#cb45-7" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb45-8"><a href="#cb45-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> <span class="kw">try</span> file.reader().readAllAlloc(</span>
-<span id="cb45-9"><a href="#cb45-9" aria-hidden="true" tabindex="-1"></a>        allocator, std.math.maxInt(<span class="dt">usize</span>)</span>
-<span id="cb45-10"><a href="#cb45-10" aria-hidden="true" tabindex="-1"></a>    );</span>
-<span id="cb45-11"><a href="#cb45-11" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
-<span id="cb45-12"><a href="#cb45-12" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb45-13"><a href="#cb45-13" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb45-14"><a href="#cb45-14" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> gpa = std.heap.GeneralPurposeAllocator(.<span class="op">{}</span>)<span class="op">{}</span>;</span>
-<span id="cb45-15"><a href="#cb45-15" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> allocator = gpa.allocator();</span>
-<span id="cb45-16"><a href="#cb45-16" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> path = <span class="st">"../ZigExamples/file-io/shop-list.txt"</span>;</span>
-<span id="cb45-17"><a href="#cb45-17" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> file_contents = <span class="kw">try</span> read_file(allocator, path);</span>
-<span id="cb45-18"><a href="#cb45-18" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> slice = file_contents[<span class="dv">0</span>..file_contents.len];</span>
-<span id="cb45-19"><a href="#cb45-19" aria-hidden="true" tabindex="-1"></a>    _ = slice;</span>
-<span id="cb45-20"><a href="#cb45-20" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<span id="cb45-7"><a href="#cb45-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> <span class="kw">try</span> file.reader().readAllAlloc(</span>
+<span id="cb45-8"><a href="#cb45-8" aria-hidden="true" tabindex="-1"></a>        allocator, std.math.maxInt(<span class="dt">usize</span>)</span>
+<span id="cb45-9"><a href="#cb45-9" aria-hidden="true" tabindex="-1"></a>    );</span>
+<span id="cb45-10"><a href="#cb45-10" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
+<span id="cb45-11"><a href="#cb45-11" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb45-12"><a href="#cb45-12" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb45-13"><a href="#cb45-13" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> gpa = std.heap.GeneralPurposeAllocator(.<span class="op">{}</span>)<span class="op">{}</span>;</span>
+<span id="cb45-14"><a href="#cb45-14" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> allocator = gpa.allocator();</span>
+<span id="cb45-15"><a href="#cb45-15" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> path = <span class="st">"../ZigExamples/file-io/shop-list.txt"</span>;</span>
+<span id="cb45-16"><a href="#cb45-16" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> file_contents = <span class="kw">try</span> read_file(allocator, path);</span>
+<span id="cb45-17"><a href="#cb45-17" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> slice = file_contents[<span class="dv">0</span>..file_contents.len];</span>
+<span id="cb45-18"><a href="#cb45-18" aria-hidden="true" tabindex="-1"></a>    _ = slice;</span>
+<span id="cb45-19"><a href="#cb45-19" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 </section>
 </section>
diff --git a/docs/Chapters/10-stack-project.html b/docs/Chapters/10-stack-project.html
index 5476994b..03d8a07b 100644
--- a/docs/Chapters/10-stack-project.html
+++ b/docs/Chapters/10-stack-project.html
@@ -370,28 +370,37 @@ <h3 data-number="12.1.1" class="anchored" data-anchor-id="applying-over-a-functi
 <span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a>    _ = twice(<span class="dv">5678</span>);</span>
 <span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file833f3ad20be9.test.test comptime...OKAll 1 
+<pre><code>1/1 filee87436f6bc4a.test.test comptime...OKAll 1 
    tests passed.</code></pre>
 </div>
 </div>
-<p>But what if we provide a number that is not compile-time known to this function? For example, we might provide a different input value to this function depending on the target OS of our compilation process. The code example below demonstrates such case.</p>
-<p>Because the value of the object <code>n</code> is determined at runtime, we cannot provide this object as input to the <code>twice()</code> function. The <code>zig</code> compiler will not allow it, because we marked the <code>num</code> argument as a “comptime argument”. That is why the <code>zig</code> compiler raises the compile-time error exposed below:</p>
+<p>But what if we provide a number that is not compile-time known to this function? For example, your program might receive some input from the user through the <code>stdin</code> channel of your system. This input from the user might be many different things, and cannot be predicted at compile-time. These circumstances make this “input from the user” a value that is runtime-known only.</p>
+<p>In the example below, this “input from the user” is initially received as a string, which is then parsed and transformed into a integer value, and the result of this operation is stored inside the <code>n</code> object.</p>
+<p>Because the “input of the user” is known only at runtime, the value of the object <code>n</code> is determined only at runtime. As consequence, we cannot provide this object as input to the <code>twice()</code> function. The <code>zig</code> compiler will not allow it, because we marked the <code>num</code> argument as a “comptime argument”. That is why the <code>zig</code> compiler raises the compile-time error exposed below:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb3"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> builtin = <span class="bu">@import</span>(<span class="st">"builtin"</span>);</span>
+<div class="sourceCode cell-code" id="cb3"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb3-2"><a href="#cb3-2" aria-hidden="true" tabindex="-1"></a><span class="kw">fn</span> twice(<span class="kw">comptime</span> num: <span class="dt">u32</span>) <span class="dt">u32</span> <span class="op">{</span></span>
 <span id="cb3-3"><a href="#cb3-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> num * <span class="dv">2</span>;</span>
 <span id="cb3-4"><a href="#cb3-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
-<span id="cb3-5"><a href="#cb3-5" aria-hidden="true" tabindex="-1"></a><span class="kw">test</span> <span class="st">"test comptime"</span> <span class="op">{</span></span>
-<span id="cb3-6"><a href="#cb3-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> n: <span class="dt">u32</span> = <span class="cn">undefined</span>;</span>
-<span id="cb3-7"><a href="#cb3-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">if</span> (builtin.target.os.tag == .windows) <span class="op">{</span></span>
-<span id="cb3-8"><a href="#cb3-8" aria-hidden="true" tabindex="-1"></a>        n = <span class="dv">1234</span>;</span>
-<span id="cb3-9"><a href="#cb3-9" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span> <span class="kw">else</span> <span class="op">{</span></span>
-<span id="cb3-10"><a href="#cb3-10" aria-hidden="true" tabindex="-1"></a>        n = <span class="dv">5678</span>;</span>
-<span id="cb3-11"><a href="#cb3-11" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb3-12"><a href="#cb3-12" aria-hidden="true" tabindex="-1"></a>    _ = twice(n);</span>
-<span id="cb3-13"><a href="#cb3-13" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<span id="cb3-5"><a href="#cb3-5" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb3-6"><a href="#cb3-6" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb3-7"><a href="#cb3-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> buffer: [<span class="dv">5</span>]<span class="dt">u8</span> = .<span class="op">{</span> <span class="dv">0</span>, <span class="dv">0</span>, <span class="dv">0</span>, <span class="dv">0</span>, <span class="dv">0</span> <span class="op">}</span>;</span>
+<span id="cb3-8"><a href="#cb3-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
+<span id="cb3-9"><a href="#cb3-9" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> stdin = std.io.getStdIn().reader();</span>
+<span id="cb3-10"><a href="#cb3-10" aria-hidden="true" tabindex="-1"></a>    _ = <span class="kw">try</span> stdout.write(<span class="st">"Please write a 4-digit integer number</span><span class="sc">\n</span><span class="st">"</span>);</span>
+<span id="cb3-11"><a href="#cb3-11" aria-hidden="true" tabindex="-1"></a>    _ = <span class="kw">try</span> stdin.readUntilDelimiter(&amp;buffer, <span class="ch">'\n'</span>);</span>
+<span id="cb3-12"><a href="#cb3-12" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb3-13"><a href="#cb3-13" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"Input: {s}"</span>, .<span class="op">{</span>buffer<span class="op">}</span>);</span>
+<span id="cb3-14"><a href="#cb3-14" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> n: <span class="dt">u32</span> = <span class="kw">try</span> std.fmt.parseInt(</span>
+<span id="cb3-15"><a href="#cb3-15" aria-hidden="true" tabindex="-1"></a>        <span class="dt">u32</span>, buffer[<span class="dv">0</span> .. buffer.len - <span class="dv">1</span>], <span class="dv">10</span></span>
+<span id="cb3-16"><a href="#cb3-16" aria-hidden="true" tabindex="-1"></a>    );</span>
+<span id="cb3-17"><a href="#cb3-17" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> twice_result = twice(n);</span>
+<span id="cb3-18"><a href="#cb3-18" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"Result: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>twice_result<span class="op">}</span>);</span>
+<span id="cb3-19"><a href="#cb3-19" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<pre><code>t.zig:12:16: error: runtime-known argument passed to comptime parameter</code></pre>
+<pre><code>t.zig:12:16: error: unable to resolve comptime value
+    const twice_result = twice(n);
+                               ^</code></pre>
 <p>Comptime arguments are frequently used on functions that return some sort of generic structure. In fact, <code>comptime</code> is the essence (or the basis) to make generics in Zig. We are going to talk more about generics in <a href="#sec-generics" class="quarto-xref"><span>Section 12.2</span></a>.</p>
 <p>For now, let’s take a look at this code example from <span class="citation" data-cites="karlseguin_generics">Seguin (<a href="../references.html#ref-karlseguin_generics" role="doc-biblioref">2024</a>)</span>. You can see that this <code>IntArray()</code> function has one argument named <code>length</code>. This argument is marked as comptime, and receives a value of type <code>usize</code> as input. So the value given to this argument must be compile-time known. We can also see that this function returns an array of <code>i64</code> values as output.</p>
 <div class="cell">
@@ -426,8 +435,8 @@ <h3 data-number="12.1.2" class="anchored" data-anchor-id="applying-over-an-expre
 <span id="cb6-11"><a href="#cb6-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> <span class="kw">comptime</span> expect(fibonacci(<span class="dv">7</span>) == <span class="dv">13</span>);</span>
 <span id="cb6-12"><a href="#cb6-12" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file833f119d55a3.test.fibonacci...OKAll 1 test
-  ts passed.</code></pre>
+<pre><code>1/1 filee874b9644b4.test.fibonacci...OKAll 1 tests
+  s passed.</code></pre>
 </div>
 </div>
 <p>A lot of your Zig source code might be potentially executed at compile-time, because the <code>zig</code> compiler can figure out the output of some expressions. Especially if these expressions depend only on compile-time known values. We have talked about this in <a href="01-memory.html#sec-compile-time" class="quarto-xref"><span>Section 3.1.1</span></a>.</p>
@@ -455,7 +464,7 @@ <h3 data-number="12.1.3" class="anchored" data-anchor-id="applying-over-a-block"
 <span id="cb8-15"><a href="#cb8-15" aria-hidden="true" tabindex="-1"></a>    _ = x;</span>
 <span id="cb8-16"><a href="#cb8-16" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file833f6ccf145c.test.fibonacci in a block...O
+<pre><code>1/1 filee8746560ae87.test.fibonacci in a block...O
   OKAll 1 tests passed.</code></pre>
 </div>
 </div>
diff --git a/docs/search.json b/docs/search.json
index 9c21c93a..c0032af0 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -164,7 +164,7 @@
     "href": "Chapters/01-zig-weird.html#sec-arrays",
     "title": "1  Introducing Zig",
     "section": "1.6 Arrays",
-    "text": "1.6 Arrays\nYou create arrays in Zig by using a syntax that resembles the C syntax. First, you specify the size of the array (i.e., the number of elements that will be stored in the array) you want to create inside a pair of brackets.\nThen, you specify the data type of the elements that will be stored inside this array. All elements present in an array in Zig must have the same data type. For example, you cannot mix elements of type f32 with elements of type i32 in the same array.\nAfter that, you simply list the values that you want to store in this array inside a pair of curly braces. In the example below, I am creating two constant objects that contain different arrays. The first object contains an array of 4 integer values, while the second object, an array of 3 floating point values.\nNow, you should notice that in the object ls, I am not explicitly specifying the size of the array inside of the brackets. Instead of using a literal value (like the value 4 that I used in the ns object), I am using the special character underscore (_). This syntax tells the zig compiler to fill this field with the number of elements listed inside of the curly braces. So, this syntax [_] is for lazy (or smart) programmers who leave the job of counting how many elements there are in the curly braces for the compiler.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n\nIt’s worth noting that these are static arrays, meaning that they cannot grow in size. Once you declare your array, you cannot change the size of it. This is very common in low level languages. Because low level languages normally wants to give you (the programmer) full control over memory, and the way in which arrays are expanded is tightly related to memory management.\n\n1.6.1 Selecting elements of the array\nOne very common activity is to select specific portions of an array you have in your source code. In Zig, you can select a specific element from your array, by simply providing the index of this particular element inside brackets after the object name. In the example below, I am selecting the third element from the ns array. Notice that Zig is a “zero-index” based language, like C, C++, Rust, Python, and many other languages.\n\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n\n12\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a range selector. Some programmers also call these selectors of “slice selectors”, and they also exist in Rust, and have the exact same syntax as in Zig. Anyway, a range selector is a special expression in Zig that defines a range of indexes, and it have the syntax start..end.\nIn the example below, at the second line of code, the sl object stores a slice (or a portion) of the ns array. More precisely, the elements at index 1 and 2 in the ns array.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n\nWhen you use the start..end syntax, the “end tail” of the range selector is non-inclusive, meaning that, the index at the end is not included in the range that is selected from the array. Therefore, the syntax start..end actually means start..end - 1 in practice.\nYou can for example, create a slice that goes from the first to the last elements of the array, by using ar[0..ar.len] syntax In other words, it’s a slice that accesses all elements in the array.\n\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n\nYou can also use the syntax start.. in your range selector. Which tells the zig compiler to select the portion of the array that begins at the start index until the last element of the array. In the example below, we are selecting the range from index 1 until the end of the array.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n\n\n\n1.6.2 More on slices\nAs we discussed before, in Zig, you can select specific portions of an existing array. This is called slicing in Zig (Sobeston 2024), because when you select a portion of an array, you are creating a slice object from that array.\nA slice object is essentially a pointer object accompanied by a length number. The pointer object points to the first element in the slice, and the length number tells the zig compiler how many elements there are in this slice.\n\nSlices can be thought of as a pair of [*]T (the pointer to the data) and a usize (the element count) (Sobeston 2024).\n\nThrough the pointer contained inside the slice you can access the elements (or values) that are inside this range (or portion) that you selected from the original array. But the length number (which you can access through the len property of your slice object) is the really big improvement (over C arrays for example) that Zig brings to the table here.\nBecause with this length number the zig compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice, or, if you are causing any buffer overflow problems. In the example below, we access the len property of the slice sl, which tells us that this slice have 2 elements in it.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n\n2\n\n\n\n\n1.6.3 Array operators\nThere are two array operators available in Zig that are very useful. The array concatenation operator (++), and the array multiplication operator (**). As the name suggests, these are array operators.\nOne important detail about these two operators is that they work only when both operands have a size (or “length”) that is compile-time known. We are going to talk more about the differences between “compile-time known” and “runtime known” in Section 3.1.1. But for now, keep this information in mind, that you cannot use these operators in every situation.\nIn summary, the ++ operator creates a new array that is the concatenation, of both arrays provided as operands. So, the expression a ++ b produces a new array which contains all the elements from arrays a and b.\n\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n\n{ 1, 2, 3, 4, 5 }\n\n\nThis ++ operator is particularly useful to concatenate strings together. Strings in Zig are described in depth in Section 1.8. In summary, a string object in Zig is essentially an arrays of bytes. So, you can use this array concatenation operator to effectively concatenate strings together.\nIn contrast, the ** operator is used to replicate an array multiple times. In other words, the expression a ** 3 creates a new array which contains the elements of the array a repeated 3 times.\n\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n\n{ 1, 2, 3, 1, 2, 3 }\n\n\n\n\n1.6.4 Runtime versus compile-time known length in slices\nWe are going to talk a lot about the differences between compile-time known and runtime known across this book, especially in Section 3.1.1. But the basic idea is that a thing is compile-time known, when we know everything (the value, the attributes and the characteristics) about this thing at compile-time. In contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime. Therefore, we don’t know the value of this thing at compile-time, only at runtime.\nWe have learned in Section 1.6.1 that slices are created by using a range selector, which represents a range of indexes. When this “range of indexes” (i.e., both the start and the end of this range) is known at compile-time, the slice object that gets created is actually, under the hood, just a single-item pointer to an array.\nYou don’t need to precisely understand what that means now. We are going to talk a lot about pointers in Chapter 6. For now, just understand that, when the range of indexes is known at compile-time, the slice that gets created is just a pointer to an array, accompanied by a length value that tells the size of the slice.\nIf you have a slice object like this, i.e., a slice that has a compile-time known range, you can use common pointer operations over this slice object. For example, you can dereference the pointer of this slice, by using the .* method, like you would do on a normal pointer object.\n\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n_ = slice;\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object that gets created is not a pointer anymore, and, thus, it does not support pointer operations. For example, maybe the start index is known at compile time, but the end index is not. In such case, the range of the slice becomes runtime known only.\nIn the example below, the slice object have a runtime known range, because the end index of the range is not known at compile time. In other words, the size of the array at buffer is not known at compile time. When we execute this program, the size of the array might be 10, or, it might be 12 depending on where we execute it. Therefore, we don’t know at compile time if the slice object have a range of size 10, or, a range of size 12.\n\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\nfn read_file(allocator: std.mem.Allocator, path: []const u8) ![]u8 {\n    const file = try std.fs.cwd().openFile(path, .{});\n    defer file.close();\n\n    return try file.reader().readAllAlloc(\n        allocator, std.math.maxInt(usize)\n    );\n}\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const path = \"../ZigExamples/file-io/shop-list.txt\";\n    const file_contents = try read_file(allocator, path);\n    const slice = file_contents[0..file_contents.len];\n    _ = slice;\n}",
+    "text": "1.6 Arrays\nYou create arrays in Zig by using a syntax that resembles the C syntax. First, you specify the size of the array (i.e., the number of elements that will be stored in the array) you want to create inside a pair of brackets.\nThen, you specify the data type of the elements that will be stored inside this array. All elements present in an array in Zig must have the same data type. For example, you cannot mix elements of type f32 with elements of type i32 in the same array.\nAfter that, you simply list the values that you want to store in this array inside a pair of curly braces. In the example below, I am creating two constant objects that contain different arrays. The first object contains an array of 4 integer values, while the second object, an array of 3 floating point values.\nNow, you should notice that in the object ls, I am not explicitly specifying the size of the array inside of the brackets. Instead of using a literal value (like the value 4 that I used in the ns object), I am using the special character underscore (_). This syntax tells the zig compiler to fill this field with the number of elements listed inside of the curly braces. So, this syntax [_] is for lazy (or smart) programmers who leave the job of counting how many elements there are in the curly braces for the compiler.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n\nIt’s worth noting that these are static arrays, meaning that they cannot grow in size. Once you declare your array, you cannot change the size of it. This is very common in low level languages. Because low level languages normally wants to give you (the programmer) full control over memory, and the way in which arrays are expanded is tightly related to memory management.\n\n1.6.1 Selecting elements of the array\nOne very common activity is to select specific portions of an array you have in your source code. In Zig, you can select a specific element from your array, by simply providing the index of this particular element inside brackets after the object name. In the example below, I am selecting the third element from the ns array. Notice that Zig is a “zero-index” based language, like C, C++, Rust, Python, and many other languages.\n\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n\n12\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a range selector. Some programmers also call these selectors of “slice selectors”, and they also exist in Rust, and have the exact same syntax as in Zig. Anyway, a range selector is a special expression in Zig that defines a range of indexes, and it have the syntax start..end.\nIn the example below, at the second line of code, the sl object stores a slice (or a portion) of the ns array. More precisely, the elements at index 1 and 2 in the ns array.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n\nWhen you use the start..end syntax, the “end tail” of the range selector is non-inclusive, meaning that, the index at the end is not included in the range that is selected from the array. Therefore, the syntax start..end actually means start..end - 1 in practice.\nYou can for example, create a slice that goes from the first to the last elements of the array, by using ar[0..ar.len] syntax In other words, it’s a slice that accesses all elements in the array.\n\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n\nYou can also use the syntax start.. in your range selector. Which tells the zig compiler to select the portion of the array that begins at the start index until the last element of the array. In the example below, we are selecting the range from index 1 until the end of the array.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n\n\n\n1.6.2 More on slices\nAs we discussed before, in Zig, you can select specific portions of an existing array. This is called slicing in Zig (Sobeston 2024), because when you select a portion of an array, you are creating a slice object from that array.\nA slice object is essentially a pointer object accompanied by a length number. The pointer object points to the first element in the slice, and the length number tells the zig compiler how many elements there are in this slice.\n\nSlices can be thought of as a pair of [*]T (the pointer to the data) and a usize (the element count) (Sobeston 2024).\n\nThrough the pointer contained inside the slice you can access the elements (or values) that are inside this range (or portion) that you selected from the original array. But the length number (which you can access through the len property of your slice object) is the really big improvement (over C arrays for example) that Zig brings to the table here.\nBecause with this length number the zig compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice, or, if you are causing any buffer overflow problems. In the example below, we access the len property of the slice sl, which tells us that this slice have 2 elements in it.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n\n2\n\n\n\n\n1.6.3 Array operators\nThere are two array operators available in Zig that are very useful. The array concatenation operator (++), and the array multiplication operator (**). As the name suggests, these are array operators.\nOne important detail about these two operators is that they work only when both operands have a size (or “length”) that is compile-time known. We are going to talk more about the differences between “compile-time known” and “runtime known” in Section 3.1.1. But for now, keep this information in mind, that you cannot use these operators in every situation.\nIn summary, the ++ operator creates a new array that is the concatenation, of both arrays provided as operands. So, the expression a ++ b produces a new array which contains all the elements from arrays a and b.\n\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n\n{ 1, 2, 3, 4, 5 }\n\n\nThis ++ operator is particularly useful to concatenate strings together. Strings in Zig are described in depth in Section 1.8. In summary, a string object in Zig is essentially an arrays of bytes. So, you can use this array concatenation operator to effectively concatenate strings together.\nIn contrast, the ** operator is used to replicate an array multiple times. In other words, the expression a ** 3 creates a new array which contains the elements of the array a repeated 3 times.\n\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n\n{ 1, 2, 3, 1, 2, 3 }\n\n\n\n\n1.6.4 Runtime versus compile-time known length in slices\nWe are going to talk a lot about the differences between compile-time known and runtime known across this book, especially in Section 3.1.1. But the basic idea is that a thing is compile-time known, when we know everything (the value, the attributes and the characteristics) about this thing at compile-time. In contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime. Therefore, we don’t know the value of this thing at compile-time, only at runtime.\nWe have learned in Section 1.6.1 that slices are created by using a range selector, which represents a range of indexes. When this “range of indexes” (i.e., both the start and the end of this range) is known at compile-time, the slice object that gets created is actually, under the hood, just a single-item pointer to an array.\nYou don’t need to precisely understand what that means now. We are going to talk a lot about pointers in Chapter 6. For now, just understand that, when the range of indexes is known at compile-time, the slice that gets created is just a pointer to an array, accompanied by a length value that tells the size of the slice.\nIf you have a slice object like this, i.e., a slice that has a compile-time known range, you can use common pointer operations over this slice object. For example, you can dereference the pointer of this slice, by using the .* method, like you would do on a normal pointer object.\n\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n_ = slice;\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object that gets created is not a pointer anymore, and, thus, it does not support pointer operations. For example, maybe the start index is known at compile time, but the end index is not. In such case, the range of the slice becomes runtime known only.\nIn the example below, we are reading a file, and then, we try to create a slice object that covers the entire buffer that contains the contents of this file. This is obviously an example of a runtime known range, because the end index of the range is not known at compile time.\nIn other words, the end index of the range is the size of the array file_contents. However, the size of file_contents is not known at compile time. Because we don’t know how many bytes are stored inside this shop-list.txt file. And because this is a file, someone might edit this file tomorrow and add more lines or remove lines from it. Therefore, the size of this file might vary drastically from one execution to another.\nNow, if the file size can vary from one run to another, then, we can conclude that the value of the expression file_contents.len exposed in the example below can also vary from one run to another. As consequence, the value of the expression file_contents.len is runtime-known only, and, as a consequence of that, the range 0..file_contents.len is also runtime-known only.\n\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\nfn read_file(allocator: std.mem.Allocator, path: []const u8) ![]u8 {\n    const file = try std.fs.cwd().openFile(path, .{});\n    defer file.close();\n    return try file.reader().readAllAlloc(\n        allocator, std.math.maxInt(usize)\n    );\n}\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const path = \"../ZigExamples/file-io/shop-list.txt\";\n    const file_contents = try read_file(allocator, path);\n    const slice = file_contents[0..file_contents.len];\n    _ = slice;\n}",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -954,7 +954,7 @@
     "href": "Chapters/10-stack-project.html#sec-comptime",
     "title": "12  Project 3 - Building a stack data structure",
     "section": "",
-    "text": "apply comptime on a function argument.\napply comptime on an object.\napply comptime on a block of expressions.\n\n\n12.1.1 Applying over a function argument\nWhen you apply the comptime keyword on a function argument, you are saying to the zig compiler that the value assigned to that particular function argument must be known at compile-time. We explained in detail in Section 3.1.1 what exactly “value known at compile-time” means. So if you have any doubts about this idea, refer back to that section.\nNow let’s think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement to that particular function argument. If the programmer accidentally tries to give a value to this function argument that is not known at compile time, the zig compiler will notice this problem, and as a consequence, it will raise a compilation error saying that it cannot compile your program. Because you are providing a value that is “runtime known” to a function argument that must be “compile-time known”.\nTake a look at this very simple example below, where we define a twice() function, that simply doubles the input value named num. Notice that we use the comptime keyword before the name of the function argument. This keyword is marking the function argument num as a “comptime argument”.\nThat is a function argument whose value must be compile-time known. This is why the expression twice(5678) is valid, and no compilation errors are raised. Because the value 5678 is compile-time known, so this is the expected behaviour for this function.\n\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n\n1/1 file833f3ad20be9.test.test comptime...OKAll 1 \n   tests passed.\n\n\nBut what if we provide a number that is not compile-time known to this function? For example, we might provide a different input value to this function depending on the target OS of our compilation process. The code example below demonstrates such case.\nBecause the value of the object n is determined at runtime, we cannot provide this object as input to the twice() function. The zig compiler will not allow it, because we marked the num argument as a “comptime argument”. That is why the zig compiler raises the compile-time error exposed below:\n\nconst builtin = @import(\"builtin\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    var n: u32 = undefined;\n    if (builtin.target.os.tag == .windows) {\n        n = 1234;\n    } else {\n        n = 5678;\n    }\n    _ = twice(n);\n}\n\nt.zig:12:16: error: runtime-known argument passed to comptime parameter\nComptime arguments are frequently used on functions that return some sort of generic structure. In fact, comptime is the essence (or the basis) to make generics in Zig. We are going to talk more about generics in Section 12.2.\nFor now, let’s take a look at this code example from Seguin (2024). You can see that this IntArray() function has one argument named length. This argument is marked as comptime, and receives a value of type usize as input. So the value given to this argument must be compile-time known. We can also see that this function returns an array of i64 values as output.\n\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n\nNow, the key component of this function is the length argument. This argument is used to determine the size of the array that is produced by the function. Let’s think about the consequences of that. If the size of the array is dependent on the value assigned to the length argument, this means that the data type of the output of the function depends on the value of this length argument.\nLet this statement sink for a bit in your mind. As I described in Section 1.2.2, Zig is a strongly-typed language, especially on function declarations. So every time we write a function in Zig, we have to annotate the data type of the value returned by the function. But how can we do that, if this data type depends on the value given to the argument of the function?\nThink about this for a second. If length is equal to 3 for example, then, the return type of the function is [3]i64. But if length is equal to 40, then, the return type becomes [40]i64. At this point the zig compiler would be confused, and raise a compilation error, saying something like this:\n\nHey! You have annotated that this function should return a [3]i64 value, but I got a [40]i64 value instead! This doesn’t look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when the type keyword comes in. This type keyword is basically saying to the zig compiler that this function will return some data type as output, but it doesn’t know yet what exactly data type that is. We will talk more about this in Section 12.2.\n\n\n12.1.2 Applying over an expression\nWhen you apply the comptime keyword over an expression, then, it is guaranteed that the zig compiler will execute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time (e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the zig compiler will raise a compilation error.\nTake this example from the official documentation of Zig (Zig Software Foundation 2024). We are executing the same fibonacci() function both at runtime, and, at compile-time. The function is executed by default at runtime, but because we use the comptime keyword in the second “try expression”, this expression is executed at compile-time.\nThis might be a bit confusing for some people. Yes! When I say that this expression is executed at compile-time, I mean that this expression is compiled and executed while the zig compiler is compiling your Zig source code.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n\n1/1 file833f119d55a3.test.fibonacci...OKAll 1 test\n  ts passed.\n\n\nA lot of your Zig source code might be potentially executed at compile-time, because the zig compiler can figure out the output of some expressions. Especially if these expressions depend only on compile-time known values. We have talked about this in Section 3.1.1.\nBut when you use the comptime keyword on an expression, there is no “it might be executed at compile-time” anymore. With the comptime keyword you are ordering the zig compiler to execute this expression at compile-time. You are imposing this rule, it is guaranteed that the compiler will always execute it at compile-time. Or, at least, the compiler will try to execute it. If the compiler cannot execute the expression for whatever reason, the compiler will raise a compilation error.\n\n\n12.1.3 Applying over a block\nBlocks were described in Section 1.7. When you apply the comptime keyword to a block of expressions, you get essentially the same effect as when you apply this keyword to a single expression. That is, the entire block of expressions is executed at compile-time by the zig compiler.\nIn the example below, we mark the block labeled of blk as a comptime block, and, therefore, the expressions inside this block are executed at compile-time.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n\n1/1 file833f6ccf145c.test.fibonacci in a block...O\n  OKAll 1 tests passed.",
+    "text": "apply comptime on a function argument.\napply comptime on an object.\napply comptime on a block of expressions.\n\n\n12.1.1 Applying over a function argument\nWhen you apply the comptime keyword on a function argument, you are saying to the zig compiler that the value assigned to that particular function argument must be known at compile-time. We explained in detail in Section 3.1.1 what exactly “value known at compile-time” means. So if you have any doubts about this idea, refer back to that section.\nNow let’s think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement to that particular function argument. If the programmer accidentally tries to give a value to this function argument that is not known at compile time, the zig compiler will notice this problem, and as a consequence, it will raise a compilation error saying that it cannot compile your program. Because you are providing a value that is “runtime known” to a function argument that must be “compile-time known”.\nTake a look at this very simple example below, where we define a twice() function, that simply doubles the input value named num. Notice that we use the comptime keyword before the name of the function argument. This keyword is marking the function argument num as a “comptime argument”.\nThat is a function argument whose value must be compile-time known. This is why the expression twice(5678) is valid, and no compilation errors are raised. Because the value 5678 is compile-time known, so this is the expected behaviour for this function.\n\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n\n1/1 filee87436f6bc4a.test.test comptime...OKAll 1 \n   tests passed.\n\n\nBut what if we provide a number that is not compile-time known to this function? For example, your program might receive some input from the user through the stdin channel of your system. This input from the user might be many different things, and cannot be predicted at compile-time. These circumstances make this “input from the user” a value that is runtime-known only.\nIn the example below, this “input from the user” is initially received as a string, which is then parsed and transformed into a integer value, and the result of this operation is stored inside the n object.\nBecause the “input of the user” is known only at runtime, the value of the object n is determined only at runtime. As consequence, we cannot provide this object as input to the twice() function. The zig compiler will not allow it, because we marked the num argument as a “comptime argument”. That is why the zig compiler raises the compile-time error exposed below:\n\nconst std = @import(\"std\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\n\npub fn main() !void {\n    var buffer: [5]u8 = .{ 0, 0, 0, 0, 0 };\n    const stdout = std.io.getStdOut().writer();\n    const stdin = std.io.getStdIn().reader();\n    _ = try stdout.write(\"Please write a 4-digit integer number\\n\");\n    _ = try stdin.readUntilDelimiter(&buffer, '\\n');\n\n    try stdout.print(\"Input: {s}\", .{buffer});\n    const n: u32 = try std.fmt.parseInt(\n        u32, buffer[0 .. buffer.len - 1], 10\n    );\n    const twice_result = twice(n);\n    try stdout.print(\"Result: {d}\\n\", .{twice_result});\n}\n\nt.zig:12:16: error: unable to resolve comptime value\n    const twice_result = twice(n);\n                               ^\nComptime arguments are frequently used on functions that return some sort of generic structure. In fact, comptime is the essence (or the basis) to make generics in Zig. We are going to talk more about generics in Section 12.2.\nFor now, let’s take a look at this code example from Seguin (2024). You can see that this IntArray() function has one argument named length. This argument is marked as comptime, and receives a value of type usize as input. So the value given to this argument must be compile-time known. We can also see that this function returns an array of i64 values as output.\n\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n\nNow, the key component of this function is the length argument. This argument is used to determine the size of the array that is produced by the function. Let’s think about the consequences of that. If the size of the array is dependent on the value assigned to the length argument, this means that the data type of the output of the function depends on the value of this length argument.\nLet this statement sink for a bit in your mind. As I described in Section 1.2.2, Zig is a strongly-typed language, especially on function declarations. So every time we write a function in Zig, we have to annotate the data type of the value returned by the function. But how can we do that, if this data type depends on the value given to the argument of the function?\nThink about this for a second. If length is equal to 3 for example, then, the return type of the function is [3]i64. But if length is equal to 40, then, the return type becomes [40]i64. At this point the zig compiler would be confused, and raise a compilation error, saying something like this:\n\nHey! You have annotated that this function should return a [3]i64 value, but I got a [40]i64 value instead! This doesn’t look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when the type keyword comes in. This type keyword is basically saying to the zig compiler that this function will return some data type as output, but it doesn’t know yet what exactly data type that is. We will talk more about this in Section 12.2.\n\n\n12.1.2 Applying over an expression\nWhen you apply the comptime keyword over an expression, then, it is guaranteed that the zig compiler will execute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time (e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the zig compiler will raise a compilation error.\nTake this example from the official documentation of Zig (Zig Software Foundation 2024). We are executing the same fibonacci() function both at runtime, and, at compile-time. The function is executed by default at runtime, but because we use the comptime keyword in the second “try expression”, this expression is executed at compile-time.\nThis might be a bit confusing for some people. Yes! When I say that this expression is executed at compile-time, I mean that this expression is compiled and executed while the zig compiler is compiling your Zig source code.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n\n1/1 filee874b9644b4.test.fibonacci...OKAll 1 tests\n  s passed.\n\n\nA lot of your Zig source code might be potentially executed at compile-time, because the zig compiler can figure out the output of some expressions. Especially if these expressions depend only on compile-time known values. We have talked about this in Section 3.1.1.\nBut when you use the comptime keyword on an expression, there is no “it might be executed at compile-time” anymore. With the comptime keyword you are ordering the zig compiler to execute this expression at compile-time. You are imposing this rule, it is guaranteed that the compiler will always execute it at compile-time. Or, at least, the compiler will try to execute it. If the compiler cannot execute the expression for whatever reason, the compiler will raise a compilation error.\n\n\n12.1.3 Applying over a block\nBlocks were described in Section 1.7. When you apply the comptime keyword to a block of expressions, you get essentially the same effect as when you apply this keyword to a single expression. That is, the entire block of expressions is executed at compile-time by the zig compiler.\nIn the example below, we mark the block labeled of blk as a comptime block, and, therefore, the expressions inside this block are executed at compile-time.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n\n1/1 filee8746560ae87.test.fibonacci in a block...O\n  OKAll 1 tests passed.",
     "crumbs": [
       "<span class='chapter-number'>12</span>  <span class='chapter-title'>Project 3 - Building a stack data structure</span>"
     ]

From a7a9383ad1d4fc089ca5a694d97dd121f21c9cd0 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Mon, 7 Apr 2025 22:11:49 -0300
Subject: [PATCH 124/151] Recompile stack chapter

---
 _freeze/Chapters/01-zig-weird/execute-results/html.json   | 6 ++----
 .../Chapters/10-stack-project/execute-results/html.json   | 6 ++----
 docs/Chapters/10-stack-project.html                       | 8 ++++----
 docs/search.json                                          | 2 +-
 4 files changed, 9 insertions(+), 13 deletions(-)

diff --git a/_freeze/Chapters/01-zig-weird/execute-results/html.json b/_freeze/Chapters/01-zig-weird/execute-results/html.json
index baa58ef3..0444b72e 100644
--- a/_freeze/Chapters/01-zig-weird/execute-results/html.json
+++ b/_freeze/Chapters/01-zig-weird/execute-results/html.json
@@ -2,10 +2,8 @@
   "hash": "06a3119bbdf9be9d02679617c65c9d79",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\n\nlanguage, it's still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. Sometimes, they really make it hard to debug\n\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscure the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that gets compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e., where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contains Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nWe can use this build system to write small scripts in Zig,\nwhich describe the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e., creating new objects)\nare made in Zig. You can create a new object in Zig by using the syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). In @sec-assignments we talk more about objects in general.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that in @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIt's worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt's like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portable C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nIn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e., the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. If you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith an \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, on Windows, operations like accessing the `stdout` (or opening a file) depend on\nresources that are available only at *runtime* (you will learn more about compile-time versus runtime\nin @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerges from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword in @sec-comptime.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation in a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues\n\n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described in @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig later in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig?\nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar to our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentation.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It's a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (on YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e., identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nSo, if you want to change the value of your object, you need to transform your immutable (or \"constant\")\nobject into a mutable (or \"variable\") object. You can do that by using the `var` keyword.\nThis keyword stands for \"variable\", and when you apply this keyword to some object, you are\ntelling the Zig compiler that the value associated with this object might change at some point.\n\nThus, if we come back to the previous example, and change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it's a \"variable object\".\n\nHowever, if you take a look at the example below, you will notice that we have not only declared the\n`age` object with the `var` keyword, but we also have explicitly annotated the data type\nof the `age` object with the `u8` type this time. The basic idea is, when we use a variable/mutable object,\nthe Zig compiler ask for us to be more explicit with what we want, to be more clear\nabout what our code does. This translates into being more explicit about the data types that we want\nto use in our objects.\n\nTherefore, if you transform your object into a variable/mutable object, just remember to always\nannotate the type of the object explicitly in your code. Otherwise, the Zig compiler might raise\na compilation error, asking you to transform your object back into a `const` object, or,\nto give your object an \"explicit type\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIt's important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code uses this object while it's uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object.\n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e., if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to a special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It's discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also gets discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e., the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\nIt's worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it's a slice that\naccesses all elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" in @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth in @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially in @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned in @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e., both the start and the end of this range)\nis known at compile-time, the slice object that gets created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nin @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that gets created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e., a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can\ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n_ = slice;\n```\n:::\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat gets created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, we are reading a file, and then, we try to create a slice object\nthat covers the entire buffer that contains the contents of this file. This is obviously\nan example of a runtime known range, because the end index of the range\nis not known at compile time.\n\nIn other words, the end index of the range is the size of\nthe array `file_contents`. However, the size of `file_contents` is not known at compile time.\nBecause we don't know how many bytes are stored inside this `shop-list.txt` file.\nAnd because this is a file, someone might edit this file tomorrow and add more lines\nor remove lines from it. Therefore, the size of this file might vary drastically from one execution to another.\n\nNow, if the file size can vary from one run to another, then, we can conclude that the value of the expression\n`file_contents.len` exposed in the example below can also vary from one run to another. As consequence,\nthe value of the expression `file_contents.len` is runtime-known only, and, as a consequence of that,\nthe range `0..file_contents.len` is also runtime-known only.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\nfn read_file(allocator: std.mem.Allocator, path: []const u8) ![]u8 {\n    const file = try std.fs.cwd().openFile(path, .{});\n    defer file.close();\n    return try file.reader().readAllAlloc(\n        allocator, std.math.maxInt(usize)\n    );\n}\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const path = \"../ZigExamples/file-io/shop-list.txt\";\n    const file_contents = try read_file(allocator, path);\n    const slice = file_contents[0..file_contents.len];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e., a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e., similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented in @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e., `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIt's worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e., a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e., the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause it's much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e., if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it's a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIt's important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig in @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers in @sec-root-file and especially in @sec-assignments.\n- How strings work in Zig in @sec-zig-strings.\n- How to use arrays and slices in @sec-arrays.\n- How to import functionality from other Zig modules in @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* in @sec-structs-and-oop.\n- Basic control flow syntax in @sec-zig-control-flow.\n- Enums in @sec-enum;\n- Pointers and Optionals in @sec-pointer;\n- Error handling with `try` and `catch` in @sec-error-handling;\n- Unit tests in @sec-unittests;\n- Vectors in @sec-vectors-simd;\n- Build System in @sec-build-system;\n",
-    "supporting": [
-      "01-zig-weird_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\n\nlanguage, it's still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. Sometimes, they really make it hard to debug\n\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscure the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that gets compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e., where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contains Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nWe can use this build system to write small scripts in Zig,\nwhich describe the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e., creating new objects)\nare made in Zig. You can create a new object in Zig by using the syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). In @sec-assignments we talk more about objects in general.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that in @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIt's worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt's like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portable C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nIn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e., the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. If you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith an \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, on Windows, operations like accessing the `stdout` (or opening a file) depend on\nresources that are available only at *runtime* (you will learn more about compile-time versus runtime\nin @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerges from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword in @sec-comptime.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation in a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues\n\n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described in @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig later in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig?\nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar to our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentation.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It's a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (on YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e., identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nSo, if you want to change the value of your object, you need to transform your immutable (or \"constant\")\nobject into a mutable (or \"variable\") object. You can do that by using the `var` keyword.\nThis keyword stands for \"variable\", and when you apply this keyword to some object, you are\ntelling the Zig compiler that the value associated with this object might change at some point.\n\nThus, if we come back to the previous example, and change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it's a \"variable object\".\n\nHowever, if you take a look at the example below, you will notice that we have not only declared the\n`age` object with the `var` keyword, but we also have explicitly annotated the data type\nof the `age` object with the `u8` type this time. The basic idea is, when we use a variable/mutable object,\nthe Zig compiler ask for us to be more explicit with what we want, to be more clear\nabout what our code does. This translates into being more explicit about the data types that we want\nto use in our objects.\n\nTherefore, if you transform your object into a variable/mutable object, just remember to always\nannotate the type of the object explicitly in your code. Otherwise, the Zig compiler might raise\na compilation error, asking you to transform your object back into a `const` object, or,\nto give your object an \"explicit type\".\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIt's important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code uses this object while it's uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object.\n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e., if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to a special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It's discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also gets discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e., the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\n\nIt's worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it's a slice that\naccesses all elements in the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" in @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth in @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially in @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned in @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e., both the start and the end of this range)\nis known at compile-time, the slice object that gets created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nin @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that gets created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e., a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can\ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n_ = slice;\n```\n:::\n\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat gets created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, we are reading a file, and then, we try to create a slice object\nthat covers the entire buffer that contains the contents of this file. This is obviously\nan example of a runtime known range, because the end index of the range\nis not known at compile time.\n\nIn other words, the end index of the range is the size of\nthe array `file_contents`. However, the size of `file_contents` is not known at compile time.\nBecause we don't know how many bytes are stored inside this `shop-list.txt` file.\nAnd because this is a file, someone might edit this file tomorrow and add more lines\nor remove lines from it. Therefore, the size of this file might vary drastically from one execution to another.\n\nNow, if the file size can vary from one run to another, then, we can conclude that the value of the expression\n`file_contents.len` exposed in the example below can also vary from one run to another. As consequence,\nthe value of the expression `file_contents.len` is runtime-known only, and, as a consequence of that,\nthe range `0..file_contents.len` is also runtime-known only.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\nfn read_file(allocator: std.mem.Allocator, path: []const u8) ![]u8 {\n    const file = try std.fs.cwd().openFile(path, .{});\n    defer file.close();\n    return try file.reader().readAllAlloc(\n        allocator, std.math.maxInt(usize)\n    );\n}\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const path = \"../ZigExamples/file-io/shop-list.txt\";\n    const file_contents = try read_file(allocator, path);\n    const slice = file_contents[0..file_contents.len];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e., a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e., similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented in @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e., `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIt's worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e., a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e., the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause it's much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e., if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it's a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIt's important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig in @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers in @sec-root-file and especially in @sec-assignments.\n- How strings work in Zig in @sec-zig-strings.\n- How to use arrays and slices in @sec-arrays.\n- How to import functionality from other Zig modules in @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* in @sec-structs-and-oop.\n- Basic control flow syntax in @sec-zig-control-flow.\n- Enums in @sec-enum;\n- Pointers and Optionals in @sec-pointer;\n- Error handling with `try` and `catch` in @sec-error-handling;\n- Unit tests in @sec-unittests;\n- Vectors in @sec-vectors-simd;\n- Build System in @sec-build-system;\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/10-stack-project/execute-results/html.json b/_freeze/Chapters/10-stack-project/execute-results/html.json
index 91cbf4a5..4afe632d 100644
--- a/_freeze/Chapters/10-stack-project/execute-results/html.json
+++ b/_freeze/Chapters/10-stack-project/execute-results/html.json
@@ -2,10 +2,8 @@
   "hash": "801c378f39cbcf646c40a137880aa3b8",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 3 - Building a stack data structure\n\nIn this chapter we are going to implement a stack data structure as our next small project\nin this book. Implementing basic data structures in any language is kind of a\n\"kindergarten task\" (if this term even exist) in computer science (CS), because\nwe normally learn and implement them in the first semesters of CS.\n\nBut this is actually good! Since this should be a very easy task, we don't need much to explain\nwhat a stack is, then, we can concentrate on what is really important here, which is learning\nhow the concept of \"generics\" is implemented in the Zig language, and how one of the key\nfeatures of Zig, which is comptime, works, and use the stack data structure to demonstrate\nthese concepts on the fly.\n\nBut before we get into building the stack data structure, we first need to understand\nwhat the `comptime` keyword does to your code, and after that, we also need to learn about\nhow generics work in Zig.\n\n\n## Understanding `comptime` in Zig {#sec-comptime}\n\nOne of the key features of Zig is `comptime`. This keyword introduces a whole\nnew concept and paradigm, that is tightly connected with the compilation process.\nIn @sec-compile-time we have described the importance and the role that \"compile-time versus runtime\"\nplays into Zig. In that section, we learned that the rules applied to a value/object change\na lot depending on whether this value is known at compile-time, or just at runtime.\n\nThe `comptime` keyword is strongly related to these two spaces in time (compile-time and runtime).\nLet's quickly recap the differences. Compile-time is the period of time when your\nZig source code is being compiled by the `zig` compiler, while the runtime is\nthe period of time when your Zig program is being executed, i.e., when we execute\nthe binary files that were generated by the `zig` compiler.\n\nThere are three ways in which you can apply the `comptime` keyword, which are:\n\n- apply `comptime` on a function argument.\n- apply `comptime` on an object.\n- apply `comptime` on a block of expressions.\n\n\n\n### Applying over a function argument\n\nWhen you apply the `comptime` keyword on a function argument, you are saying to the `zig` compiler\nthat the value assigned to that particular function argument must be known at compile-time.\nWe explained in detail in @sec-compile-time what exactly \"value known at compile-time\" means. So\nif you have any doubts about this idea, refer back to that section.\n\nNow let's think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement\nto that particular function argument. If the programmer accidentally tries to give a value to this\nfunction argument that is not known at compile time, the `zig` compiler will notice this problem, and\nas a consequence, it will raise a compilation error saying that it cannot compile your program. Because\nyou are providing a value that is \"runtime known\" to a function argument that must be \"compile-time known\".\n\nTake a look at this very simple example below, where we define a `twice()` function, that simply\ndoubles the input value named `num`. Notice that we use the `comptime` keyword before the name\nof the function argument. This keyword is marking the function argument `num` as a \"comptime argument\".\n\nThat is a function argument whose value must be compile-time known. This is why the expression\n`twice(5678)` is valid, and no compilation errors are raised. Because the value `5678`\nis compile-time known, so this is the expected behaviour for this function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filee87436f6bc4a.test.test comptime...OKAll 1 \n   tests passed.\n```\n\n\n:::\n:::\n\n\n\n\nBut what if we provide a number that is not compile-time known to this function?\nFor example, your program might receive some input from the user through the `stdin`\nchannel of your system. This input from the user might be many different things,\nand cannot be predicted at compile-time. These circumstances make this \"input\nfrom the user\" a value that is runtime-known only.\n\nIn the example below, this \"input from the user\" is initially received as a string,\nwhich is then parsed and transformed into a integer value, and the result of this operation\nis stored inside the `n` object.\n\nBecause the \"input of the user\" is known only at runtime, the value of the object `n` is determined only at runtime.\nAs consequence, we cannot provide this object as input to the `twice()` function.\nThe `zig` compiler will not allow it, because we marked\nthe `num` argument as a \"comptime argument\". That is why the `zig` compiler raises\nthe compile-time error exposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\n\npub fn main() !void {\n    var buffer: [5]u8 = .{ 0, 0, 0, 0, 0 };\n    const stdout = std.io.getStdOut().writer();\n    const stdin = std.io.getStdIn().reader();\n    _ = try stdout.write(\"Please write a 4-digit integer number\\n\");\n    _ = try stdin.readUntilDelimiter(&buffer, '\\n');\n\n    try stdout.print(\"Input: {s}\", .{buffer});\n    const n: u32 = try std.fmt.parseInt(\n        u32, buffer[0 .. buffer.len - 1], 10\n    );\n    const twice_result = twice(n);\n    try stdout.print(\"Result: {d}\\n\", .{twice_result});\n}\n```\n:::\n\n\n\n\n```\nt.zig:12:16: error: unable to resolve comptime value\n    const twice_result = twice(n);\n                               ^\n```\n\nComptime arguments are frequently used on functions that return some sort\nof generic structure. In fact, `comptime` is the essence (or the basis) to make generics in Zig.\nWe are going to talk more about generics in @sec-generics.\n\nFor now, let's take a look at this code example from @karlseguin_generics. You\ncan see that this `IntArray()` function has one argument named `length`.\nThis argument is marked as comptime, and receives a value of type `usize` as input. So the value given to this argument\nmust be compile-time known.\nWe can also see that this function returns an array of `i64` values as output.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n```\n:::\n\n\n\n\nNow, the key component of this function is the `length` argument. This argument\nis used to determine the size of the array that is produced by the function. Let's\nthink about the consequences of that. If the size of the array is dependent on\nthe value assigned to the `length` argument, this means that the data type of the\noutput of the function depends on the value of this `length` argument.\n\nLet this statement sink for a bit in your mind. As I described in @sec-root-file,\nZig is a strongly-typed language, especially on function declarations.\nSo every time we write a function in Zig, we have to annotate the data type of\nthe value returned by the function. But how can we do that, if this data type\ndepends on the value given to the argument of the function?\n\nThink about this for a second. If `length` is equal to 3 for example, then, the\nreturn type of the function is `[3]i64`. But if `length` is equal to 40, then,\nthe return type becomes `[40]i64`. At this point the `zig` compiler would be confused,\nand raise a compilation error, saying something like this:\n\n> Hey! You have annotated that this function should return a `[3]i64` value, but I got a `[40]i64` value instead! This doesn't look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when\nthe `type` keyword comes in. This `type` keyword is basically saying to the\n`zig` compiler that this function will return some data type as output, but it doesn't know yet\nwhat exactly data type that is. We will talk more about this in @sec-generics.\n\n\n\n### Applying over an expression\n\nWhen you apply the `comptime` keyword over an expression, then, it is guaranteed that the `zig` compiler will\nexecute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time\n(e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the `zig` compiler\nwill raise a compilation error.\n\nTake this example from the official documentation of Zig [@zigdocs]. We\nare executing the same `fibonacci()` function both at runtime, and, at compile-time.\nThe function is executed by default at runtime, but because we use the `comptime`\nkeyword in the second \"try expression\", this expression is executed at compile-time.\n\nThis might be a bit confusing for some people. Yes! When I say that this expression\nis executed at compile-time, I mean that this expression is compiled and executed\nwhile the `zig` compiler is compiling your Zig source code.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filee874b9644b4.test.fibonacci...OKAll 1 tests\n  s passed.\n```\n\n\n:::\n:::\n\n\n\n\nA lot of your Zig source code might be potentially executed at compile-time,\nbecause the `zig` compiler can figure out the output of some expressions.\nEspecially if these expressions depend only on compile-time known values.\nWe have talked about this in @sec-compile-time.\n\nBut when you use the `comptime` keyword on an expression, there is no \"it might be executed\nat compile-time\" anymore. With the `comptime` keyword you are ordering the `zig` compiler\nto execute this expression at compile-time. You are imposing this rule, it is guaranteed\nthat the compiler will always execute it at compile-time. Or, at least, the compiler\nwill try to execute it. If the compiler cannot execute the expression for whatever reason,\nthe compiler will raise a compilation error.\n\n\n### Applying over a block\n\nBlocks were described in @sec-blocks. When you apply the `comptime` keyword to a\nblock of expressions, you get essentially the same effect as when you apply this keyword to\na single expression. That is, the entire block of expressions is executed at\ncompile-time by the `zig` compiler.\n\nIn the example below, we mark the block labeled of `blk` as a comptime block,\nand, therefore, the expressions inside this block are executed at compile-time.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filee8746560ae87.test.fibonacci in a block...O\n  OKAll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## Introducing Generics {#sec-generics}\n\nFirst of all, what is a generic? Generic is the idea to allow a type\n(`f64`, `u8`, `u32`, `bool`, and also, user-defined types, like the `User` struct\nthat we defined in @sec-structs-and-oop) to be a parameter to methods, classes and\ninterfaces [@geeks_generics]. In other words, a \"generic\" is a class (or a method) that can work\nwith multiple data types.\n\nFor example, in Java, generics are created through the operator `<>`. With this operator,\na Java class is capable of receiving a data type as input, and therefore, the class can fit\nits features according to this input data type.\nAs another example, generics in C++ are supported through the concept of templates.\nClass templates in C++ are generics.\n\nIn Zig, generics are implemented through `comptime`. The `comptime` keyword\nallows us to collect a data type at compile time, and pass this data type as\ninput to a piece of code.\n\n\n### A generic function {#sec-generic-fun}\n\nTake the `max()` function exposed below as a first example.\nThis function is essentially a \"generic function\".\nIn this function, we have a comptime function argument named `T`.\nNotice that this `T` argument has a data type of `type`. Weird right? This `type` keyword is the\n\"father of all types\", or, \"the type of types\" in Zig.\n\nBecause we have used this `type` keyword in the `T` argument, we are telling\nthe `zig` compiler that this `T` argument will receive some data type as input.\nAlso notice the use of the `comptime` keyword in this argument.\nAs I described in @sec-comptime, every time you use this keyword in a function argument,\nthis means that the value of this argument must be known at compile-time.\nThis makes sense, right? Because there is no data type that is not known at compile-time.\n\nThink about this. Every data type that you will ever write is always\nknown at compile-time. Especially because data types are an essential\ninformation for the compiler to actually compile your source code.\nHaving this in mind, makes sense to mark this argument as a comptime argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\n```\n:::\n\n\n\n\nAlso notice that the value of the `T` argument is actually used\nto define the data type of the other arguments in the function, `a` and `b`, and also at the\nreturn type annotation of the function.\nThat is, the data type of these arguments (`a` and `b`), and, the return data type of the function itself,\nare determined by the input value given to the `T` argument.\n\nAs a result, we have a generic function that works with different data types.\nFor example, I can provide `u8` values to this `max()` function, and it will work as expected.\nBut if I provide `f64` values instead, it will also work as expected.\nWithout a generic function, I would have to write a different `max()` function\nfor each data type I wanted to use.\nThis generic function provides a very useful shortcut for us.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\ntest \"test max\" {\n    const n1 = max(u8, 4, 10);\n    std.debug.print(\"Max n1: {d}\\n\", .{n1});\n    const n2 = max(f64, 89.24, 64.001);\n    std.debug.print(\"Max n2: {d}\\n\", .{n2});\n}\n```\n:::\n\n\n\n\n```\nMax n1: 10\nMax n2: 89.24\n```\n\n\n### A generic data structure {#sec-generic-struct}\n\nEvery data structure that you find in the Zig Standard Library (e.g. `ArrayList`, `HashMap`, etc.)\nis essentially a generic data structure.\nThese data structures are generic in the sense that they work with any data type you want.\nYou just say which is the data type of the values that are going to be stored in this data\nstructure, and they just work as expected.\n\nA generic data structure in Zig is how you replicate a generic class from Java,\nor, a class template from C++. But you may ask yourself: how do we build a\ngeneric data structure in Zig?\n\nThe basic idea is to write a generic function that creates the data structure definition\nfor the specific type we want. In other words, this generic function behaves as a \"factory of data structures\".\nThe generic function outputs the `struct` definition that defines this data structure for a\nspecific data type.\n\nTo create such function, we need to add a comptime argument to this function that receives a data type\nas input. We already learned how to do this in the previous section (@sec-generic-fun).\nI think the best way to demonstrate how to create a generic data structure is to actually write one.\nThis where we go into our next small project in this book. This one is a very small project,\nwhich is to write a generic stack data structure.\n\n\n\n\n## What is a stack? {#sec-what-stack}\n\nA stack data structure is a structure that follows a LIFO (*last in, first out*) principle.\nOnly two operations are normally supported in a stack data structure, which are `push` and `pop`.\nThe `push` operation is used to add new values to the stack, while `pop` is used to remove\nvalues from the stack.\n\nWhen people try to explain how the stack data structure works, the most common analogy\nthat they use is a stack of plates. Imagine that you have a stack of plates,\nfor example, a stack of 10 plates in your table. Each plate represents a value that\nis currently stored in this stack.\n\nWe begin with a stack of 10 different values, or 10 different plates. Now, imagine that you want to\nadd a new plate (or a new value) to this stack, which translates to the `push` operation.\nYou would add this plate (or this value) by just putting the new plate\non the top of the stack. Then, you would increase the stack to 11 plates.\n\nBut how would you remove plates (or remove values) from this stack (a.k.a. the `pop` operation) ?\nTo do that, we would have to remove the plate on the top of the stack, and, as a result, we would\nhave, once again, 10 plates in the stack.\n\nThis demonstrates the LIFO concept, because the first plate in the stack, which is the plate\nin the bottom of the stack, is always the last plate to get out of the stack. Think about it. In order\nto remove this specific plate from the stack, we have to remove all plates in the\nstack. So every operation in the stack, either insertion or deletion, is always made at the top of the stack.\nThe @fig-stack below exposes this logic visually:\n\n![A diagram of a stack structure. Source: Wikipedia, the free encyclopedia.](./../Figures/lifo-stack.svg){#fig-stack}\n\n\n\n## Writing the stack data structure\n\nWe are going to write the stack data structure in two steps. First, we are going\nto implement a stack that can only store `u32` values. Then, after that, we are going\nto extend our implementation to make it generic, so that it works with any data type\nwe want.\n\nFirst, we need to decide how the values will be stored inside the stack. There are multiple\nways to implement the storage behind a stack structure. Some people prefer to use a doubly linked list,\nothers prefer to use a dynamic array, etc. In this example we are going to use an array behind the hood,\nto store the values in the stack, which is the `items` data member of our `Stack` struct definition.\n\nAlso notice in our `Stack` struct that we have three other data members: `capacity`, `length` and `allocator`.\nThe `capacity` member contains the capacity of the underlying array that stores the values in the stack.\nThe `length` contains the number of values that are currently being stored in the stack.\nAnd the `allocator` contains the allocator object that will be used by the stack structure whenever it\nneeds to allocate more space for the values that are being stored.\n\nWe begin by defining an `init()` method of this struct, which is going to be\nresponsible for instantiating a `Stack` object. Notice that, inside this\n`init()` method, we start by allocating an array with the capacity specified\nin the `capacity` argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst Stack = struct {\n    items: []u32,\n    capacity: usize,\n    length: usize,\n    allocator: Allocator,\n\n    pub fn init(allocator: Allocator, capacity: usize) !Stack {\n        var buf = try allocator.alloc(u32, capacity);\n        return .{\n            .items = buf[0..],\n            .capacity = capacity,\n            .length = 0,\n            .allocator = allocator,\n        };\n    }\n};\n```\n:::\n\n\n\n\n\n### Implementing the `push` operation\n\nNow that we have written the basic logic to create a new `Stack` object,\nwe can start writing the logic responsible for performing a push operation.\nRemember, a push operation in a stack data structure is the operation\nresponsible for adding a new value to the stack.\n\nSo how can we add a new value to the `Stack` object that we have?\nThe `push()` function exposed below is a possible answer to this question.\nRemember from what we discussed in @sec-what-stack that values are always added to the top of the stack.\nThis means that this `push()` function must always find the element in the underlying array\nthat currently represents the top position of the stack, and then, add the input value there.\n\nFirst, we have an if statement in this function. This if statement is\nchecking whether we need to expand the underlying array to store\nthis new value that we are adding to the stack. In other words, maybe\nthe underlying array does not have enough capacity to store this new\nvalue, and, in this case, we need to expand our array to get the capacity that we need.\n\nSo, if the logical test in this if statement returns true, it means that the array\ndoes not have enough capacity, and we need to expand it before we store this new value.\nSo inside this if statement we are executing the necessary expressions to expand the underlying array.\nNotice that we use the allocator object to allocate a new array that is twice as bigger\nthan the current array (`self.capacity * 2`).\n\nAfter that, we use a different built-in function named `@memcpy()`. This built-in function\nis equivalent to the `memcpy()` function from the C Standard Library[^cmemcpy]. It's used to\ncopy the values from one block of memory to another block of memory. In other words,\nyou can use this function to copy the values from one array into another array.\n\n[^cmemcpy]: <https://www.tutorialspoint.com/c_standard_library/c_function_memcpy.htm>\n\nWe are using this `@memcpy()` built-in function to copy the values that are currently stored\nin the underlying array of the stack object (`self.items`) into our new and bigger array that\nwe have allocated (`new_buf`). After we execute this function, the `new_buf` contains a copy\nof the values that are present at `self.items`.\n\nNow that we have secured a copy of our current values in the `new_buf` object, we\ncan now free the memory currently allocated at `self.items`. After that, we just need\nto assign our new and bigger array to `self.items`. This is the sequence\nof steps necessary to expand our array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn push(self: *Stack, val: u32) !void {\n    if ((self.length + 1) > self.capacity) {\n        var new_buf = try self.allocator.alloc(\n            u32, self.capacity * 2\n        );\n        @memcpy(\n            new_buf[0..self.capacity], self.items\n        );\n        self.allocator.free(self.items);\n        self.items = new_buf;\n        self.capacity = self.capacity * 2;\n    }\n\n    self.items[self.length] = val;\n    self.length += 1;\n}\n```\n:::\n\n\n\n\nAfter we make sure that we have enough room to store this new value\nthat we are adding to the stack, all we have to do is to assign\nthis value to the top element in this stack, and, increase the\nvalue of the `length` attribute by one. We find the top element\nin the stack by using the `length` attribute.\n\n\n\n### Implementing the `pop` operation\n\nNow we can implement the pop operation of our stack object.\nThis is a much easier operation to implement, and the `pop()` method below summarises\nall the logic that is needed.\n\nWe just have to find the element in the underlying array that currently represents the top\nof the stack, and set this element to \"undefined\", to indicate that\nthis element is \"empty\". After that, we also need to decrease\nthe `length` attribute of the stack by one.\n\nIf the current length of the stack is zero, it means that there is\nno values being stored in the stack currently. So, in this case,\nwe could just return from the function and do nothing really.\nThis is what the if statement inside this function is checking for.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn pop(self: *Stack) void {\n    if (self.length == 0) return;\n\n    self.items[self.length - 1] = undefined;\n    self.length -= 1;\n}\n```\n:::\n\n\n\n\n\n\n### Implementing the `deinit` method\n\nWe have implemented the methods responsible for the two main operations\nassociated with the stack data structure, which is `pop()` and `push()`,\nand we also have implemented the method responsible for instantiating\na new `Stack` object, which is the `init()` method.\n\nBut now, we need to implement also the method responsible for destroying\na `Stack` object. In Zig, this task is commonly associated with the method\nnamed `deinit()`. Most struct objects in Zig have such method, and it\nis commonly nicknamed \"the destructor method\".\n\nIn theory, all we have to do to destroy the `Stack` object is to make\nsure that we free the allocated memory for the underlying array, using\nthe allocator object that is stored inside the `Stack` object.\nThis is what the `deinit()` method below is doing.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn deinit(self: *Stack) void {\n    self.allocator.free(self.items);\n}\n```\n:::\n\n\n\n\n\n\n\n## Making it generic\n\nNow that we have implemented the basic skeleton of our stack data structure,\nwe can now focus on discussing how we can make it generic. How can we make\nthis basic skeleton to work not only with `u32` values, but also with any other\ndata type we want?\nFor example, we might need to create a stack object to store `User` values\nin it. How can we make this possible? The answer lies in the use of generics\nand `comptime`.\n\nAs I described in @sec-generic-struct, the basic idea is to write a generic\nfunction that returns a struct definition as output.\nIn theory, we do not need much to transform our `Stack` struct into a generic\ndata structure. All that we need to do is to transform the underlying array\nof the stack into a generic array.\n\nIn other words, this underlying array needs to be a \"chameleon\". It needs to adapt,\nand transform it into an array of any data type that we want. For example, if we need to create\na stack that will store `u8` values, then this underlying array needs to be\na `u8` array (i.e., `[]u8`). But if we need to store `User` values instead, then,\nthis array needs to be a `User` array (i.e., `[]User`). Etc.\n\nWe do that by using a generic function. Because a generic function can receive a data type\nas input, and we can pass this data type to the struct definition of our `Stack` object.\nTherefore, we can use the generic function to create a `Stack` object that can store\nthe data type we want. If we want to create a stack structure that stores `User` values,\nwe pass the `User` data type to this generic function, and it will create for us\nthe struct definition that describes a `Stack` object that can store `User` values in it.\n\nLook at the code example below. I have omitted some parts of the `Stack` struct definition\nfor brevity. However, if a specific part of our `Stack` struct is not exposed here\nin this example, then it's because this part did not change from the previous example.\nIt remains the same.\n\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn Stack(comptime T: type) type {\n    return struct {\n        items: []T,\n        capacity: usize,\n        length: usize,\n        allocator: Allocator,\n        const Self = @This();\n\n        pub fn init(allocator: Allocator,\n                    capacity: usize) !Stack(T) {\n            var buf = try allocator.alloc(T, capacity);\n            return .{\n                .items = buf[0..],\n                .capacity = capacity,\n                .length = 0,\n                .allocator = allocator,\n            };\n        }\n\n        pub fn push(self: *Self, val: T) !void {\n        // Truncate the rest of the struct\n    };\n}\n```\n:::\n\n\n\n\nNotice that we have created a function in this example named `Stack()`. This function\ntakes a type as input, and passes this type to the struct definition of our\n`Stack` object. The data member `items` is now, an array of type `T`, which is the\ndata type that we have provided as input to the function. The function argument\n`val` in the `push()` function is now a value of type `T` too.\n\nWe can just provide a data type to this function, and it will create a definition of a\n`Stack` object that can store values of the data type that we have provided. In the example below, we are creating\nthe definition of a\n`Stack` object that can store `u8` values in it. This definition is stored at the `Stacku8` object.\nThis `Stacku8` object becomes our new struct, that we are going to use\nto create our `Stack` object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst Stacku8 = Stack(u8);\nvar stack = try Stacku8.init(allocator, 10);\ndefer stack.deinit();\ntry stack.push(1);\ntry stack.push(2);\ntry stack.push(3);\ntry stack.push(4);\ntry stack.push(5);\ntry stack.push(6);\n\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\"Stack capacity: {d}\\n\", .{stack.capacity});\n\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\n    \"Stack state: {any}\\n\",\n    .{stack.items[0..stack.length]}\n);\n```\n:::\n\n\n\n\n```\nStack len: 6\nStack capacity: 10\nStack len: 5\nStack len: 4\nStack state: { 1, 2, 3, 4, 0, 0, 0, 0, 0, 0 }\n```\n\nEvery generic data structure in the Zig Standard Library (`ArrayList`, `HashMap`, `SinlyLinkedList`, etc.)\nis implemented through this logic. They use a generic function to create the struct definition that can work\nwith the data type that you provided as input.\n\n\n\n\n## Conclusion\n\nThe full source code of the stack structure discussed in this chapter is freely available in the official\nrepository of this book. Just checkout the [`stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig)[^zig-stack]\nfor the `u32` version of our stack,\nand the [`generic_stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig)[^zig-stack2]\nfor the generic version, available inside the `ZigExamples` folder of the repository.\n\n\n[^zig-stack]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig>\n[^zig-stack2]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig>\n",
-    "supporting": [
-      "10-stack-project_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 3 - Building a stack data structure\n\nIn this chapter we are going to implement a stack data structure as our next small project\nin this book. Implementing basic data structures in any language is kind of a\n\"kindergarten task\" (if this term even exist) in computer science (CS), because\nwe normally learn and implement them in the first semesters of CS.\n\nBut this is actually good! Since this should be a very easy task, we don't need much to explain\nwhat a stack is, then, we can concentrate on what is really important here, which is learning\nhow the concept of \"generics\" is implemented in the Zig language, and how one of the key\nfeatures of Zig, which is comptime, works, and use the stack data structure to demonstrate\nthese concepts on the fly.\n\nBut before we get into building the stack data structure, we first need to understand\nwhat the `comptime` keyword does to your code, and after that, we also need to learn about\nhow generics work in Zig.\n\n\n## Understanding `comptime` in Zig {#sec-comptime}\n\nOne of the key features of Zig is `comptime`. This keyword introduces a whole\nnew concept and paradigm, that is tightly connected with the compilation process.\nIn @sec-compile-time we have described the importance and the role that \"compile-time versus runtime\"\nplays into Zig. In that section, we learned that the rules applied to a value/object change\na lot depending on whether this value is known at compile-time, or just at runtime.\n\nThe `comptime` keyword is strongly related to these two spaces in time (compile-time and runtime).\nLet's quickly recap the differences. Compile-time is the period of time when your\nZig source code is being compiled by the `zig` compiler, while the runtime is\nthe period of time when your Zig program is being executed, i.e., when we execute\nthe binary files that were generated by the `zig` compiler.\n\nThere are three ways in which you can apply the `comptime` keyword, which are:\n\n- apply `comptime` on a function argument.\n- apply `comptime` on an object.\n- apply `comptime` on a block of expressions.\n\n\n\n### Applying over a function argument\n\nWhen you apply the `comptime` keyword on a function argument, you are saying to the `zig` compiler\nthat the value assigned to that particular function argument must be known at compile-time.\nWe explained in detail in @sec-compile-time what exactly \"value known at compile-time\" means. So\nif you have any doubts about this idea, refer back to that section.\n\nNow let's think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement\nto that particular function argument. If the programmer accidentally tries to give a value to this\nfunction argument that is not known at compile time, the `zig` compiler will notice this problem, and\nas a consequence, it will raise a compilation error saying that it cannot compile your program. Because\nyou are providing a value that is \"runtime known\" to a function argument that must be \"compile-time known\".\n\nTake a look at this very simple example below, where we define a `twice()` function, that simply\ndoubles the input value named `num`. Notice that we use the `comptime` keyword before the name\nof the function argument. This keyword is marking the function argument `num` as a \"comptime argument\".\n\nThat is a function argument whose value must be compile-time known. This is why the expression\n`twice(5678)` is valid, and no compilation errors are raised. Because the value `5678`\nis compile-time known, so this is the expected behaviour for this function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filef044375a1f16.test.test comptime...OKAll 1 \n   tests passed.\n```\n\n\n:::\n:::\n\n\n\n\nBut what if we provide a number that is not compile-time known to this function?\nFor example, your program might receive some input from the user through the `stdin`\nchannel of your system. This input from the user might be many different things,\nand cannot be predicted at compile-time. These circumstances make this \"input\nfrom the user\" a value that is runtime-known only.\n\nIn the example below, this \"input from the user\" is initially received as a string,\nwhich is then parsed and transformed into a integer value, and the result of this operation\nis stored inside the `n` object.\n\nBecause the \"input of the user\" is known only at runtime, the value of the object `n` is determined only at runtime.\nAs consequence, we cannot provide this object as input to the `twice()` function.\nThe `zig` compiler will not allow it, because we marked\nthe `num` argument as a \"comptime argument\". That is why the `zig` compiler raises\nthe compile-time error exposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\n\npub fn main() !void {\n    var buffer: [5]u8 = .{ 0, 0, 0, 0, 0 };\n    const stdout = std.io.getStdOut().writer();\n    const stdin = std.io.getStdIn().reader();\n    _ = try stdout.write(\"Please write a 4-digit integer number\\n\");\n    _ = try stdin.readUntilDelimiter(&buffer, '\\n');\n\n    try stdout.print(\"Input: {s}\", .{buffer});\n    const n: u32 = try std.fmt.parseInt(\n        u32, buffer[0 .. buffer.len - 1], 10\n    );\n    const twice_result = twice(n);\n    try stdout.print(\"Result: {d}\\n\", .{twice_result});\n}\n```\n:::\n\n\n\n\n```\nt.zig:12:16: error: unable to resolve comptime value\n    const twice_result = twice(n);\n                               ^\n```\n\nComptime arguments are frequently used on functions that return some sort\nof generic structure. In fact, `comptime` is the essence (or the basis) to make generics in Zig.\nWe are going to talk more about generics in @sec-generics.\n\nFor now, let's take a look at this code example from @karlseguin_generics. You\ncan see that this `IntArray()` function has one argument named `length`.\nThis argument is marked as comptime, and receives a value of type `usize` as input. So the value given to this argument\nmust be compile-time known.\nWe can also see that this function returns an array of `i64` values as output.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n```\n:::\n\n\n\n\nNow, the key component of this function is the `length` argument. This argument\nis used to determine the size of the array that is produced by the function. Let's\nthink about the consequences of that. If the size of the array is dependent on\nthe value assigned to the `length` argument, this means that the data type of the\noutput of the function depends on the value of this `length` argument.\n\nLet this statement sink for a bit in your mind. As I described in @sec-root-file,\nZig is a strongly-typed language, especially on function declarations.\nSo every time we write a function in Zig, we have to annotate the data type of\nthe value returned by the function. But how can we do that, if this data type\ndepends on the value given to the argument of the function?\n\nThink about this for a second. If `length` is equal to 3 for example, then, the\nreturn type of the function is `[3]i64`. But if `length` is equal to 40, then,\nthe return type becomes `[40]i64`. At this point the `zig` compiler would be confused,\nand raise a compilation error, saying something like this:\n\n> Hey! You have annotated that this function should return a `[3]i64` value, but I got a `[40]i64` value instead! This doesn't look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when\nthe `type` keyword comes in. This `type` keyword is basically saying to the\n`zig` compiler that this function will return some data type as output, but it doesn't know yet\nwhat exactly data type that is. We will talk more about this in @sec-generics.\n\n\n\n### Applying over an expression\n\nWhen you apply the `comptime` keyword over an expression, then, it is guaranteed that the `zig` compiler will\nexecute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time\n(e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the `zig` compiler\nwill raise a compilation error.\n\nTake this example from the official documentation of Zig [@zigdocs]. We\nare executing the same `fibonacci()` function both at runtime, and, at compile-time.\nThe function is executed by default at runtime, but because we use the `comptime`\nkeyword in the second \"try expression\", this expression is executed at compile-time.\n\nThis might be a bit confusing for some people. Yes! When I say that this expression\nis executed at compile-time, I mean that this expression is compiled and executed\nwhile the `zig` compiler is compiling your Zig source code.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filef0447cb16f4d.test.fibonacci...OKAll 1 test\n  ts passed.\n```\n\n\n:::\n:::\n\n\n\n\nA lot of your Zig source code might be potentially executed at compile-time,\nbecause the `zig` compiler can figure out the output of some expressions.\nEspecially if these expressions depend only on compile-time known values.\nWe have talked about this in @sec-compile-time.\n\nBut when you use the `comptime` keyword on an expression, there is no \"it might be executed\nat compile-time\" anymore. With the `comptime` keyword you are ordering the `zig` compiler\nto execute this expression at compile-time. You are imposing this rule, it is guaranteed\nthat the compiler will always execute it at compile-time. Or, at least, the compiler\nwill try to execute it. If the compiler cannot execute the expression for whatever reason,\nthe compiler will raise a compilation error.\n\n\n### Applying over a block\n\nBlocks were described in @sec-blocks. When you apply the `comptime` keyword to a\nblock of expressions, you get essentially the same effect as when you apply this keyword to\na single expression. That is, the entire block of expressions is executed at\ncompile-time by the `zig` compiler.\n\nIn the example below, we mark the block labeled of `blk` as a comptime block,\nand, therefore, the expressions inside this block are executed at compile-time.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filef044524d5e27.test.fibonacci in a block...O\n  OKAll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## Introducing Generics {#sec-generics}\n\nFirst of all, what is a generic? Generic is the idea to allow a type\n(`f64`, `u8`, `u32`, `bool`, and also, user-defined types, like the `User` struct\nthat we defined in @sec-structs-and-oop) to be a parameter to methods, classes and\ninterfaces [@geeks_generics]. In other words, a \"generic\" is a class (or a method) that can work\nwith multiple data types.\n\nFor example, in Java, generics are created through the operator `<>`. With this operator,\na Java class is capable of receiving a data type as input, and therefore, the class can fit\nits features according to this input data type.\nAs another example, generics in C++ are supported through the concept of templates.\nClass templates in C++ are generics.\n\nIn Zig, generics are implemented through `comptime`. The `comptime` keyword\nallows us to collect a data type at compile time, and pass this data type as\ninput to a piece of code.\n\n\n### A generic function {#sec-generic-fun}\n\nTake the `max()` function exposed below as a first example.\nThis function is essentially a \"generic function\".\nIn this function, we have a comptime function argument named `T`.\nNotice that this `T` argument has a data type of `type`. Weird right? This `type` keyword is the\n\"father of all types\", or, \"the type of types\" in Zig.\n\nBecause we have used this `type` keyword in the `T` argument, we are telling\nthe `zig` compiler that this `T` argument will receive some data type as input.\nAlso notice the use of the `comptime` keyword in this argument.\nAs I described in @sec-comptime, every time you use this keyword in a function argument,\nthis means that the value of this argument must be known at compile-time.\nThis makes sense, right? Because there is no data type that is not known at compile-time.\n\nThink about this. Every data type that you will ever write is always\nknown at compile-time. Especially because data types are an essential\ninformation for the compiler to actually compile your source code.\nHaving this in mind, makes sense to mark this argument as a comptime argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\n```\n:::\n\n\n\n\nAlso notice that the value of the `T` argument is actually used\nto define the data type of the other arguments in the function, `a` and `b`, and also at the\nreturn type annotation of the function.\nThat is, the data type of these arguments (`a` and `b`), and, the return data type of the function itself,\nare determined by the input value given to the `T` argument.\n\nAs a result, we have a generic function that works with different data types.\nFor example, I can provide `u8` values to this `max()` function, and it will work as expected.\nBut if I provide `f64` values instead, it will also work as expected.\nWithout a generic function, I would have to write a different `max()` function\nfor each data type I wanted to use.\nThis generic function provides a very useful shortcut for us.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\ntest \"test max\" {\n    const n1 = max(u8, 4, 10);\n    std.debug.print(\"Max n1: {d}\\n\", .{n1});\n    const n2 = max(f64, 89.24, 64.001);\n    std.debug.print(\"Max n2: {d}\\n\", .{n2});\n}\n```\n:::\n\n\n\n\n```\nMax n1: 10\nMax n2: 89.24\n```\n\n\n### A generic data structure {#sec-generic-struct}\n\nEvery data structure that you find in the Zig Standard Library (e.g. `ArrayList`, `HashMap`, etc.)\nis essentially a generic data structure.\nThese data structures are generic in the sense that they work with any data type you want.\nYou just say which is the data type of the values that are going to be stored in this data\nstructure, and they just work as expected.\n\nA generic data structure in Zig is how you replicate a generic class from Java,\nor, a class template from C++. But you may ask yourself: how do we build a\ngeneric data structure in Zig?\n\nThe basic idea is to write a generic function that creates the data structure definition\nfor the specific type we want. In other words, this generic function behaves as a \"factory of data structures\".\nThe generic function outputs the `struct` definition that defines this data structure for a\nspecific data type.\n\nTo create such function, we need to add a comptime argument to this function that receives a data type\nas input. We already learned how to do this in the previous section (@sec-generic-fun).\nI think the best way to demonstrate how to create a generic data structure is to actually write one.\nThis where we go into our next small project in this book. This one is a very small project,\nwhich is to write a generic stack data structure.\n\n\n\n\n## What is a stack? {#sec-what-stack}\n\nA stack data structure is a structure that follows a LIFO (*last in, first out*) principle.\nOnly two operations are normally supported in a stack data structure, which are `push` and `pop`.\nThe `push` operation is used to add new values to the stack, while `pop` is used to remove\nvalues from the stack.\n\nWhen people try to explain how the stack data structure works, the most common analogy\nthat they use is a stack of plates. Imagine that you have a stack of plates,\nfor example, a stack of 10 plates in your table. Each plate represents a value that\nis currently stored in this stack.\n\nWe begin with a stack of 10 different values, or 10 different plates. Now, imagine that you want to\nadd a new plate (or a new value) to this stack, which translates to the `push` operation.\nYou would add this plate (or this value) by just putting the new plate\non the top of the stack. Then, you would increase the stack to 11 plates.\n\nBut how would you remove plates (or remove values) from this stack (a.k.a. the `pop` operation) ?\nTo do that, we would have to remove the plate on the top of the stack, and, as a result, we would\nhave, once again, 10 plates in the stack.\n\nThis demonstrates the LIFO concept, because the first plate in the stack, which is the plate\nin the bottom of the stack, is always the last plate to get out of the stack. Think about it. In order\nto remove this specific plate from the stack, we have to remove all plates in the\nstack. So every operation in the stack, either insertion or deletion, is always made at the top of the stack.\nThe @fig-stack below exposes this logic visually:\n\n![A diagram of a stack structure. Source: Wikipedia, the free encyclopedia.](./../Figures/lifo-stack.svg){#fig-stack}\n\n\n\n## Writing the stack data structure\n\nWe are going to write the stack data structure in two steps. First, we are going\nto implement a stack that can only store `u32` values. Then, after that, we are going\nto extend our implementation to make it generic, so that it works with any data type\nwe want.\n\nFirst, we need to decide how the values will be stored inside the stack. There are multiple\nways to implement the storage behind a stack structure. Some people prefer to use a doubly linked list,\nothers prefer to use a dynamic array, etc. In this example we are going to use an array behind the hood,\nto store the values in the stack, which is the `items` data member of our `Stack` struct definition.\n\nAlso notice in our `Stack` struct that we have three other data members: `capacity`, `length` and `allocator`.\nThe `capacity` member contains the capacity of the underlying array that stores the values in the stack.\nThe `length` contains the number of values that are currently being stored in the stack.\nAnd the `allocator` contains the allocator object that will be used by the stack structure whenever it\nneeds to allocate more space for the values that are being stored.\n\nWe begin by defining an `init()` method of this struct, which is going to be\nresponsible for instantiating a `Stack` object. Notice that, inside this\n`init()` method, we start by allocating an array with the capacity specified\nin the `capacity` argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst Stack = struct {\n    items: []u32,\n    capacity: usize,\n    length: usize,\n    allocator: Allocator,\n\n    pub fn init(allocator: Allocator, capacity: usize) !Stack {\n        var buf = try allocator.alloc(u32, capacity);\n        return .{\n            .items = buf[0..],\n            .capacity = capacity,\n            .length = 0,\n            .allocator = allocator,\n        };\n    }\n};\n```\n:::\n\n\n\n\n\n### Implementing the `push` operation\n\nNow that we have written the basic logic to create a new `Stack` object,\nwe can start writing the logic responsible for performing a push operation.\nRemember, a push operation in a stack data structure is the operation\nresponsible for adding a new value to the stack.\n\nSo how can we add a new value to the `Stack` object that we have?\nThe `push()` function exposed below is a possible answer to this question.\nRemember from what we discussed in @sec-what-stack that values are always added to the top of the stack.\nThis means that this `push()` function must always find the element in the underlying array\nthat currently represents the top position of the stack, and then, add the input value there.\n\nFirst, we have an if statement in this function. This if statement is\nchecking whether we need to expand the underlying array to store\nthis new value that we are adding to the stack. In other words, maybe\nthe underlying array does not have enough capacity to store this new\nvalue, and, in this case, we need to expand our array to get the capacity that we need.\n\nSo, if the logical test in this if statement returns true, it means that the array\ndoes not have enough capacity, and we need to expand it before we store this new value.\nSo inside this if statement we are executing the necessary expressions to expand the underlying array.\nNotice that we use the allocator object to allocate a new array that is twice as bigger\nthan the current array (`self.capacity * 2`).\n\nAfter that, we use a different built-in function named `@memcpy()`. This built-in function\nis equivalent to the `memcpy()` function from the C Standard Library[^cmemcpy]. It's used to\ncopy the values from one block of memory to another block of memory. In other words,\nyou can use this function to copy the values from one array into another array.\n\n[^cmemcpy]: <https://www.tutorialspoint.com/c_standard_library/c_function_memcpy.htm>\n\nWe are using this `@memcpy()` built-in function to copy the values that are currently stored\nin the underlying array of the stack object (`self.items`) into our new and bigger array that\nwe have allocated (`new_buf`). After we execute this function, the `new_buf` contains a copy\nof the values that are present at `self.items`.\n\nNow that we have secured a copy of our current values in the `new_buf` object, we\ncan now free the memory currently allocated at `self.items`. After that, we just need\nto assign our new and bigger array to `self.items`. This is the sequence\nof steps necessary to expand our array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn push(self: *Stack, val: u32) !void {\n    if ((self.length + 1) > self.capacity) {\n        var new_buf = try self.allocator.alloc(\n            u32, self.capacity * 2\n        );\n        @memcpy(\n            new_buf[0..self.capacity], self.items\n        );\n        self.allocator.free(self.items);\n        self.items = new_buf;\n        self.capacity = self.capacity * 2;\n    }\n\n    self.items[self.length] = val;\n    self.length += 1;\n}\n```\n:::\n\n\n\n\nAfter we make sure that we have enough room to store this new value\nthat we are adding to the stack, all we have to do is to assign\nthis value to the top element in this stack, and, increase the\nvalue of the `length` attribute by one. We find the top element\nin the stack by using the `length` attribute.\n\n\n\n### Implementing the `pop` operation\n\nNow we can implement the pop operation of our stack object.\nThis is a much easier operation to implement, and the `pop()` method below summarises\nall the logic that is needed.\n\nWe just have to find the element in the underlying array that currently represents the top\nof the stack, and set this element to \"undefined\", to indicate that\nthis element is \"empty\". After that, we also need to decrease\nthe `length` attribute of the stack by one.\n\nIf the current length of the stack is zero, it means that there is\nno values being stored in the stack currently. So, in this case,\nwe could just return from the function and do nothing really.\nThis is what the if statement inside this function is checking for.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn pop(self: *Stack) void {\n    if (self.length == 0) return;\n\n    self.items[self.length - 1] = undefined;\n    self.length -= 1;\n}\n```\n:::\n\n\n\n\n\n\n### Implementing the `deinit` method\n\nWe have implemented the methods responsible for the two main operations\nassociated with the stack data structure, which is `pop()` and `push()`,\nand we also have implemented the method responsible for instantiating\na new `Stack` object, which is the `init()` method.\n\nBut now, we need to implement also the method responsible for destroying\na `Stack` object. In Zig, this task is commonly associated with the method\nnamed `deinit()`. Most struct objects in Zig have such method, and it\nis commonly nicknamed \"the destructor method\".\n\nIn theory, all we have to do to destroy the `Stack` object is to make\nsure that we free the allocated memory for the underlying array, using\nthe allocator object that is stored inside the `Stack` object.\nThis is what the `deinit()` method below is doing.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn deinit(self: *Stack) void {\n    self.allocator.free(self.items);\n}\n```\n:::\n\n\n\n\n\n\n\n## Making it generic\n\nNow that we have implemented the basic skeleton of our stack data structure,\nwe can now focus on discussing how we can make it generic. How can we make\nthis basic skeleton to work not only with `u32` values, but also with any other\ndata type we want?\nFor example, we might need to create a stack object to store `User` values\nin it. How can we make this possible? The answer lies in the use of generics\nand `comptime`.\n\nAs I described in @sec-generic-struct, the basic idea is to write a generic\nfunction that returns a struct definition as output.\nIn theory, we do not need much to transform our `Stack` struct into a generic\ndata structure. All that we need to do is to transform the underlying array\nof the stack into a generic array.\n\nIn other words, this underlying array needs to be a \"chameleon\". It needs to adapt,\nand transform it into an array of any data type that we want. For example, if we need to create\na stack that will store `u8` values, then this underlying array needs to be\na `u8` array (i.e., `[]u8`). But if we need to store `User` values instead, then,\nthis array needs to be a `User` array (i.e., `[]User`). Etc.\n\nWe do that by using a generic function. Because a generic function can receive a data type\nas input, and we can pass this data type to the struct definition of our `Stack` object.\nTherefore, we can use the generic function to create a `Stack` object that can store\nthe data type we want. If we want to create a stack structure that stores `User` values,\nwe pass the `User` data type to this generic function, and it will create for us\nthe struct definition that describes a `Stack` object that can store `User` values in it.\n\nLook at the code example below. I have omitted some parts of the `Stack` struct definition\nfor brevity. However, if a specific part of our `Stack` struct is not exposed here\nin this example, then it's because this part did not change from the previous example.\nIt remains the same.\n\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn Stack(comptime T: type) type {\n    return struct {\n        items: []T,\n        capacity: usize,\n        length: usize,\n        allocator: Allocator,\n        const Self = @This();\n\n        pub fn init(allocator: Allocator,\n                    capacity: usize) !Stack(T) {\n            var buf = try allocator.alloc(T, capacity);\n            return .{\n                .items = buf[0..],\n                .capacity = capacity,\n                .length = 0,\n                .allocator = allocator,\n            };\n        }\n\n        pub fn push(self: *Self, val: T) !void {\n        // Truncate the rest of the struct\n    };\n}\n```\n:::\n\n\n\n\nNotice that we have created a function in this example named `Stack()`. This function\ntakes a type as input, and passes this type to the struct definition of our\n`Stack` object. The data member `items` is now, an array of type `T`, which is the\ndata type that we have provided as input to the function. The function argument\n`val` in the `push()` function is now a value of type `T` too.\n\nWe can just provide a data type to this function, and it will create a definition of a\n`Stack` object that can store values of the data type that we have provided. In the example below, we are creating\nthe definition of a\n`Stack` object that can store `u8` values in it. This definition is stored at the `Stacku8` object.\nThis `Stacku8` object becomes our new struct, that we are going to use\nto create our `Stack` object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst Stacku8 = Stack(u8);\nvar stack = try Stacku8.init(allocator, 10);\ndefer stack.deinit();\ntry stack.push(1);\ntry stack.push(2);\ntry stack.push(3);\ntry stack.push(4);\ntry stack.push(5);\ntry stack.push(6);\n\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\"Stack capacity: {d}\\n\", .{stack.capacity});\n\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\n    \"Stack state: {any}\\n\",\n    .{stack.items[0..stack.length]}\n);\n```\n:::\n\n\n\n\n```\nStack len: 6\nStack capacity: 10\nStack len: 5\nStack len: 4\nStack state: { 1, 2, 3, 4, 0, 0, 0, 0, 0, 0 }\n```\n\nEvery generic data structure in the Zig Standard Library (`ArrayList`, `HashMap`, `SinlyLinkedList`, etc.)\nis implemented through this logic. They use a generic function to create the struct definition that can work\nwith the data type that you provided as input.\n\n\n\n\n## Conclusion\n\nThe full source code of the stack structure discussed in this chapter is freely available in the official\nrepository of this book. Just checkout the [`stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig)[^zig-stack]\nfor the `u32` version of our stack,\nand the [`generic_stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig)[^zig-stack2]\nfor the generic version, available inside the `ZigExamples` folder of the repository.\n\n\n[^zig-stack]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig>\n[^zig-stack2]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig>\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/docs/Chapters/10-stack-project.html b/docs/Chapters/10-stack-project.html
index 03d8a07b..e7242888 100644
--- a/docs/Chapters/10-stack-project.html
+++ b/docs/Chapters/10-stack-project.html
@@ -370,7 +370,7 @@ <h3 data-number="12.1.1" class="anchored" data-anchor-id="applying-over-a-functi
 <span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a>    _ = twice(<span class="dv">5678</span>);</span>
 <span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 filee87436f6bc4a.test.test comptime...OKAll 1 
+<pre><code>1/1 filef044375a1f16.test.test comptime...OKAll 1 
    tests passed.</code></pre>
 </div>
 </div>
@@ -435,8 +435,8 @@ <h3 data-number="12.1.2" class="anchored" data-anchor-id="applying-over-an-expre
 <span id="cb6-11"><a href="#cb6-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> <span class="kw">comptime</span> expect(fibonacci(<span class="dv">7</span>) == <span class="dv">13</span>);</span>
 <span id="cb6-12"><a href="#cb6-12" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 filee874b9644b4.test.fibonacci...OKAll 1 tests
-  s passed.</code></pre>
+<pre><code>1/1 filef0447cb16f4d.test.fibonacci...OKAll 1 test
+  ts passed.</code></pre>
 </div>
 </div>
 <p>A lot of your Zig source code might be potentially executed at compile-time, because the <code>zig</code> compiler can figure out the output of some expressions. Especially if these expressions depend only on compile-time known values. We have talked about this in <a href="01-memory.html#sec-compile-time" class="quarto-xref"><span>Section 3.1.1</span></a>.</p>
@@ -464,7 +464,7 @@ <h3 data-number="12.1.3" class="anchored" data-anchor-id="applying-over-a-block"
 <span id="cb8-15"><a href="#cb8-15" aria-hidden="true" tabindex="-1"></a>    _ = x;</span>
 <span id="cb8-16"><a href="#cb8-16" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 filee8746560ae87.test.fibonacci in a block...O
+<pre><code>1/1 filef044524d5e27.test.fibonacci in a block...O
   OKAll 1 tests passed.</code></pre>
 </div>
 </div>
diff --git a/docs/search.json b/docs/search.json
index c0032af0..3a49ec73 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -954,7 +954,7 @@
     "href": "Chapters/10-stack-project.html#sec-comptime",
     "title": "12  Project 3 - Building a stack data structure",
     "section": "",
-    "text": "apply comptime on a function argument.\napply comptime on an object.\napply comptime on a block of expressions.\n\n\n12.1.1 Applying over a function argument\nWhen you apply the comptime keyword on a function argument, you are saying to the zig compiler that the value assigned to that particular function argument must be known at compile-time. We explained in detail in Section 3.1.1 what exactly “value known at compile-time” means. So if you have any doubts about this idea, refer back to that section.\nNow let’s think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement to that particular function argument. If the programmer accidentally tries to give a value to this function argument that is not known at compile time, the zig compiler will notice this problem, and as a consequence, it will raise a compilation error saying that it cannot compile your program. Because you are providing a value that is “runtime known” to a function argument that must be “compile-time known”.\nTake a look at this very simple example below, where we define a twice() function, that simply doubles the input value named num. Notice that we use the comptime keyword before the name of the function argument. This keyword is marking the function argument num as a “comptime argument”.\nThat is a function argument whose value must be compile-time known. This is why the expression twice(5678) is valid, and no compilation errors are raised. Because the value 5678 is compile-time known, so this is the expected behaviour for this function.\n\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n\n1/1 filee87436f6bc4a.test.test comptime...OKAll 1 \n   tests passed.\n\n\nBut what if we provide a number that is not compile-time known to this function? For example, your program might receive some input from the user through the stdin channel of your system. This input from the user might be many different things, and cannot be predicted at compile-time. These circumstances make this “input from the user” a value that is runtime-known only.\nIn the example below, this “input from the user” is initially received as a string, which is then parsed and transformed into a integer value, and the result of this operation is stored inside the n object.\nBecause the “input of the user” is known only at runtime, the value of the object n is determined only at runtime. As consequence, we cannot provide this object as input to the twice() function. The zig compiler will not allow it, because we marked the num argument as a “comptime argument”. That is why the zig compiler raises the compile-time error exposed below:\n\nconst std = @import(\"std\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\n\npub fn main() !void {\n    var buffer: [5]u8 = .{ 0, 0, 0, 0, 0 };\n    const stdout = std.io.getStdOut().writer();\n    const stdin = std.io.getStdIn().reader();\n    _ = try stdout.write(\"Please write a 4-digit integer number\\n\");\n    _ = try stdin.readUntilDelimiter(&buffer, '\\n');\n\n    try stdout.print(\"Input: {s}\", .{buffer});\n    const n: u32 = try std.fmt.parseInt(\n        u32, buffer[0 .. buffer.len - 1], 10\n    );\n    const twice_result = twice(n);\n    try stdout.print(\"Result: {d}\\n\", .{twice_result});\n}\n\nt.zig:12:16: error: unable to resolve comptime value\n    const twice_result = twice(n);\n                               ^\nComptime arguments are frequently used on functions that return some sort of generic structure. In fact, comptime is the essence (or the basis) to make generics in Zig. We are going to talk more about generics in Section 12.2.\nFor now, let’s take a look at this code example from Seguin (2024). You can see that this IntArray() function has one argument named length. This argument is marked as comptime, and receives a value of type usize as input. So the value given to this argument must be compile-time known. We can also see that this function returns an array of i64 values as output.\n\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n\nNow, the key component of this function is the length argument. This argument is used to determine the size of the array that is produced by the function. Let’s think about the consequences of that. If the size of the array is dependent on the value assigned to the length argument, this means that the data type of the output of the function depends on the value of this length argument.\nLet this statement sink for a bit in your mind. As I described in Section 1.2.2, Zig is a strongly-typed language, especially on function declarations. So every time we write a function in Zig, we have to annotate the data type of the value returned by the function. But how can we do that, if this data type depends on the value given to the argument of the function?\nThink about this for a second. If length is equal to 3 for example, then, the return type of the function is [3]i64. But if length is equal to 40, then, the return type becomes [40]i64. At this point the zig compiler would be confused, and raise a compilation error, saying something like this:\n\nHey! You have annotated that this function should return a [3]i64 value, but I got a [40]i64 value instead! This doesn’t look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when the type keyword comes in. This type keyword is basically saying to the zig compiler that this function will return some data type as output, but it doesn’t know yet what exactly data type that is. We will talk more about this in Section 12.2.\n\n\n12.1.2 Applying over an expression\nWhen you apply the comptime keyword over an expression, then, it is guaranteed that the zig compiler will execute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time (e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the zig compiler will raise a compilation error.\nTake this example from the official documentation of Zig (Zig Software Foundation 2024). We are executing the same fibonacci() function both at runtime, and, at compile-time. The function is executed by default at runtime, but because we use the comptime keyword in the second “try expression”, this expression is executed at compile-time.\nThis might be a bit confusing for some people. Yes! When I say that this expression is executed at compile-time, I mean that this expression is compiled and executed while the zig compiler is compiling your Zig source code.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n\n1/1 filee874b9644b4.test.fibonacci...OKAll 1 tests\n  s passed.\n\n\nA lot of your Zig source code might be potentially executed at compile-time, because the zig compiler can figure out the output of some expressions. Especially if these expressions depend only on compile-time known values. We have talked about this in Section 3.1.1.\nBut when you use the comptime keyword on an expression, there is no “it might be executed at compile-time” anymore. With the comptime keyword you are ordering the zig compiler to execute this expression at compile-time. You are imposing this rule, it is guaranteed that the compiler will always execute it at compile-time. Or, at least, the compiler will try to execute it. If the compiler cannot execute the expression for whatever reason, the compiler will raise a compilation error.\n\n\n12.1.3 Applying over a block\nBlocks were described in Section 1.7. When you apply the comptime keyword to a block of expressions, you get essentially the same effect as when you apply this keyword to a single expression. That is, the entire block of expressions is executed at compile-time by the zig compiler.\nIn the example below, we mark the block labeled of blk as a comptime block, and, therefore, the expressions inside this block are executed at compile-time.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n\n1/1 filee8746560ae87.test.fibonacci in a block...O\n  OKAll 1 tests passed.",
+    "text": "apply comptime on a function argument.\napply comptime on an object.\napply comptime on a block of expressions.\n\n\n12.1.1 Applying over a function argument\nWhen you apply the comptime keyword on a function argument, you are saying to the zig compiler that the value assigned to that particular function argument must be known at compile-time. We explained in detail in Section 3.1.1 what exactly “value known at compile-time” means. So if you have any doubts about this idea, refer back to that section.\nNow let’s think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement to that particular function argument. If the programmer accidentally tries to give a value to this function argument that is not known at compile time, the zig compiler will notice this problem, and as a consequence, it will raise a compilation error saying that it cannot compile your program. Because you are providing a value that is “runtime known” to a function argument that must be “compile-time known”.\nTake a look at this very simple example below, where we define a twice() function, that simply doubles the input value named num. Notice that we use the comptime keyword before the name of the function argument. This keyword is marking the function argument num as a “comptime argument”.\nThat is a function argument whose value must be compile-time known. This is why the expression twice(5678) is valid, and no compilation errors are raised. Because the value 5678 is compile-time known, so this is the expected behaviour for this function.\n\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n\n1/1 filef044375a1f16.test.test comptime...OKAll 1 \n   tests passed.\n\n\nBut what if we provide a number that is not compile-time known to this function? For example, your program might receive some input from the user through the stdin channel of your system. This input from the user might be many different things, and cannot be predicted at compile-time. These circumstances make this “input from the user” a value that is runtime-known only.\nIn the example below, this “input from the user” is initially received as a string, which is then parsed and transformed into a integer value, and the result of this operation is stored inside the n object.\nBecause the “input of the user” is known only at runtime, the value of the object n is determined only at runtime. As consequence, we cannot provide this object as input to the twice() function. The zig compiler will not allow it, because we marked the num argument as a “comptime argument”. That is why the zig compiler raises the compile-time error exposed below:\n\nconst std = @import(\"std\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\n\npub fn main() !void {\n    var buffer: [5]u8 = .{ 0, 0, 0, 0, 0 };\n    const stdout = std.io.getStdOut().writer();\n    const stdin = std.io.getStdIn().reader();\n    _ = try stdout.write(\"Please write a 4-digit integer number\\n\");\n    _ = try stdin.readUntilDelimiter(&buffer, '\\n');\n\n    try stdout.print(\"Input: {s}\", .{buffer});\n    const n: u32 = try std.fmt.parseInt(\n        u32, buffer[0 .. buffer.len - 1], 10\n    );\n    const twice_result = twice(n);\n    try stdout.print(\"Result: {d}\\n\", .{twice_result});\n}\n\nt.zig:12:16: error: unable to resolve comptime value\n    const twice_result = twice(n);\n                               ^\nComptime arguments are frequently used on functions that return some sort of generic structure. In fact, comptime is the essence (or the basis) to make generics in Zig. We are going to talk more about generics in Section 12.2.\nFor now, let’s take a look at this code example from Seguin (2024). You can see that this IntArray() function has one argument named length. This argument is marked as comptime, and receives a value of type usize as input. So the value given to this argument must be compile-time known. We can also see that this function returns an array of i64 values as output.\n\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n\nNow, the key component of this function is the length argument. This argument is used to determine the size of the array that is produced by the function. Let’s think about the consequences of that. If the size of the array is dependent on the value assigned to the length argument, this means that the data type of the output of the function depends on the value of this length argument.\nLet this statement sink for a bit in your mind. As I described in Section 1.2.2, Zig is a strongly-typed language, especially on function declarations. So every time we write a function in Zig, we have to annotate the data type of the value returned by the function. But how can we do that, if this data type depends on the value given to the argument of the function?\nThink about this for a second. If length is equal to 3 for example, then, the return type of the function is [3]i64. But if length is equal to 40, then, the return type becomes [40]i64. At this point the zig compiler would be confused, and raise a compilation error, saying something like this:\n\nHey! You have annotated that this function should return a [3]i64 value, but I got a [40]i64 value instead! This doesn’t look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when the type keyword comes in. This type keyword is basically saying to the zig compiler that this function will return some data type as output, but it doesn’t know yet what exactly data type that is. We will talk more about this in Section 12.2.\n\n\n12.1.2 Applying over an expression\nWhen you apply the comptime keyword over an expression, then, it is guaranteed that the zig compiler will execute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time (e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the zig compiler will raise a compilation error.\nTake this example from the official documentation of Zig (Zig Software Foundation 2024). We are executing the same fibonacci() function both at runtime, and, at compile-time. The function is executed by default at runtime, but because we use the comptime keyword in the second “try expression”, this expression is executed at compile-time.\nThis might be a bit confusing for some people. Yes! When I say that this expression is executed at compile-time, I mean that this expression is compiled and executed while the zig compiler is compiling your Zig source code.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n\n1/1 filef0447cb16f4d.test.fibonacci...OKAll 1 test\n  ts passed.\n\n\nA lot of your Zig source code might be potentially executed at compile-time, because the zig compiler can figure out the output of some expressions. Especially if these expressions depend only on compile-time known values. We have talked about this in Section 3.1.1.\nBut when you use the comptime keyword on an expression, there is no “it might be executed at compile-time” anymore. With the comptime keyword you are ordering the zig compiler to execute this expression at compile-time. You are imposing this rule, it is guaranteed that the compiler will always execute it at compile-time. Or, at least, the compiler will try to execute it. If the compiler cannot execute the expression for whatever reason, the compiler will raise a compilation error.\n\n\n12.1.3 Applying over a block\nBlocks were described in Section 1.7. When you apply the comptime keyword to a block of expressions, you get essentially the same effect as when you apply this keyword to a single expression. That is, the entire block of expressions is executed at compile-time by the zig compiler.\nIn the example below, we mark the block labeled of blk as a comptime block, and, therefore, the expressions inside this block are executed at compile-time.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n\n1/1 filef044524d5e27.test.fibonacci in a block...O\n  OKAll 1 tests passed.",
     "crumbs": [
       "<span class='chapter-number'>12</span>  <span class='chapter-title'>Project 3 - Building a stack data structure</span>"
     ]

From a0d00dcc12a50f13edded2086af361d5261d076d Mon Sep 17 00:00:00 2001
From: Yashank <37672190+stickyburn@users.noreply.github.com>
Date: Tue, 8 Apr 2025 15:35:07 -0400
Subject: [PATCH 125/151] fix: has/have grammar and typo

Fixes a few grammatical errors to ensure a smooth reading experience. Thanks for the great book!
---
 Chapters/01-zig-weird.qmd | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index 3f8bc356..a3f25733 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -819,7 +819,7 @@ t.zig:7:5: note: consider using 'const'
 
 ## Primitive Data Types {#sec-primitive-data-types}
 
-Zig have many different primitive data types available for you to use.
+Zig has many different primitive data types available for you to use.
 You can see the full list of available data types at the official
 [Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].
 
@@ -903,7 +903,7 @@ In contrast, you can also select specific slices (or sections) of your array, by
 range selector. Some programmers also call these selectors of "slice selectors",
 and they also exist in Rust, and have the exact same syntax as in Zig.
 Anyway, a range selector is a special expression in Zig that defines
-a range of indexes, and it have the syntax `start..end`.
+a range of indexes, and it has the syntax `start..end`.
 
 In the example below, at the second line of code,
 the `sl` object stores a slice (or a portion) of the
@@ -973,7 +973,7 @@ Because with this length number
 the `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,
 or, if you are causing any buffer overflow problems. In the example below,
 we access the `len` property of the slice `sl`, which tells us that this slice
-have 2 elements in it.
+has 2 elements in it.
 
 ```{zig}
 #| auto_main: true
@@ -1058,7 +1058,7 @@ const arr1 = [10]u64 {
     1, 2, 3, 4, 5,
     6, 7, 8, 9, 10
 };
-// This slice have a compile-time known range.
+// This slice has a compile-time known range.
 // Because we know both the start and end of the range.
 const slice = arr1[1..4];
 _ = slice;
@@ -1133,7 +1133,7 @@ The body of a function is a classic example of a block. If statements, for and w
 are also examples of blocks.
 
 This means that, every if statement, or for loop,
-etc., that you create in your source code have its own separate scope.
+etc., that you create in your source code has its own separate scope.
 That is why you can't access the objects that you defined inside
 of your for loop (or if statement) in an outer scope, i.e., a scope outside of the for loop.
 Because you are trying to access an object that belongs to a scope that is different
@@ -1180,12 +1180,12 @@ In summary, there are two types of string values that you care about in Zig, whi
 
 A string literal value is just a pointer to a null-terminated array of bytes (i.e., similar to a C string).
 But in Zig, a string literal value also embeds the length of the string into the data type of the value itself.
-Therefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type
+Therefore, a string literal value has a data type in the format `*const [n:0]u8`. The `n` in the data type
 indicates the size of the string.
 
 On the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,
 or, in other words, a slice of `u8` values (slices were presented in @sec-arrays). Thus,
-a string object have a data type of `[]u8` or `[]const u8`, depending if the string object is
+a string object has a data type of `[]u8` or `[]const u8`, depending if the string object is
 marked as constant with `const`, or as variable with `var`.
 
 Because a string object is essentially a slice, it means that a string object always contains two things:
@@ -1402,7 +1402,7 @@ to represent the number 570. That is why the relationship between bytes and unic
 1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds
 to a single unicode point.
 
-All of this means that if you loop trough the elements of a string in Zig, you will be looping through the
+All of this means that if you loop through the elements of a string in Zig, you will be looping through the
 bytes that represents that string, and not through the characters of that string. In the Ⱥ example above,
 the for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.
 

From 2367f083acd9598d8b40a2c341c015624793af68 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Wed, 9 Apr 2025 19:48:26 -0300
Subject: [PATCH 126/151] Publish fixes on string section

---
 Chapters/01-zig-weird.qmd                     | 205 +++++++-----
 .../01-zig-weird/execute-results/html.json    |   8 +-
 docs/Chapters/01-zig-weird.html               | 306 ++++++++++--------
 docs/Chapters/04-http-server.html             |   4 +-
 docs/index.html                               |   4 +-
 docs/search.json                              |  10 +-
 6 files changed, 305 insertions(+), 232 deletions(-)

diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index 3f8bc356..9edd7e35 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -1173,36 +1173,68 @@ The first project that we are going to build and discuss in this book is a base6
 But in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.
 So let's discuss this specific aspect of Zig.
 
-In summary, there are two types of string values that you care about in Zig, which are:
+Strings in Zig work very similarly to strings in C, but they come with some extra caveats which adds more safety
+and efficiency to them. You could also say that Zig simply uses a more modern and safe approach to manage
+and use strings.
 
-- String literal values.
-- String objects.
+A string in Zig is essentially an array of arbitrary bytes, or, more specifically, an array of `u8` values.
+This very similar to a string in C, which is also interpreted as an array of arbitrary bytes, or, in the case
+of C, an array of `char` (which usually represents an unsigned 8-bit integer value in most systems) values.
 
-A string literal value is just a pointer to a null-terminated array of bytes (i.e., similar to a C string).
-But in Zig, a string literal value also embeds the length of the string into the data type of the value itself.
-Therefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type
-indicates the size of the string.
+Now, because a string in Zig is an array, you automatically
+get the length of the string (i.e. the length of the array) embedded in the value itself. This makes
+all the difference! Because now, the Zig compiler can use the length value that is embedded in the string to
+check for "buffer overflow" or "wrong memory access" problems in your code.
 
-On the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,
-or, in other words, a slice of `u8` values (slices were presented in @sec-arrays). Thus,
-a string object have a data type of `[]u8` or `[]const u8`, depending if the string object is
-marked as constant with `const`, or as variable with `var`.
 
-Because a string object is essentially a slice, it means that a string object always contains two things:
-a pointer to an array of bytes (i.e., `u8` values) that represents the string value; and also, a length value,
-which specifies the size of the slice, or, how many elements there is in the slice.
-It's worth to emphasize that the array of bytes in a string object is not null-terminated, like in a
-string literal value.
+To achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.
+So getting this kind of safety is not automatic and much harder to do in C. For example, if you want
+to track the length of your string throughout your program in C, then, you first need to loop through
+the array of bytes that represents this string, and find the null element (`'\0'`) position to discover
+where exactly the array ends, or, in other words, to find how much elements the array of bytes contain.
 
-```{zig}
+To do that, you would need to do something like this in C. In this example, the C string stored in
+the object `array` is 25 bytes long:
+
+```{c}
 #| eval: false
-// This is a string literal value:
-"A literal value";
-// This is a string object:
-const object: []const u8 = "A string object";
+#include <stdio.h>
+int main() {
+    char* array = "An example of string in C";
+    int index = 0;
+    while (1) {
+        if (array[index] == '\0') {
+            break;
+        }
+        index++;
+    }
+    printf("Number of elements in the array: %d\n", index);
+}
+```
+
+```
+Number of elements in the array: 25
+```
+
+
+You don't have this kind of work in Zig. Because the length of the string is always
+present and accessible in the string value itself. You can easily access the length of the string
+through the `len` attribute. As an example, the `string_object` object below is 43 bytes long:
+
+
+```{zig}
+#| auto_main: false
+#| build_type: "run"
+const std = @import("std");
+const stdout = std.io.getStdOut().writer();
+pub fn main() !void {
+    const string_object = "This is an example of string literal in Zig";
+    try stdout.print("{d}\n", .{string_object.len});
+}
 ```
 
-Zig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every
+
+Another point is that Zig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every
 sequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings
 (you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).
 Today, most of the text in our modern world, especially on the web, should be UTF-8 encoded.
@@ -1229,76 +1261,86 @@ pub fn main() !void {
 ```
 
 
-If you want to see the actual bytes that represents a string in Zig, you can use
-a `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal
-value to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,
-like you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.
 
-[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>
+### Using a slice versus a sentinel-terminated array
+
+In memory, all string values in Zig are always stored in the same way.
+They are simply stored as sequences/arrays of arbitrary bytes. But you can use and access
+this sequence of bytes in two different ways. You can access this sequence of bytes as:
+
+- a sentinel-terminated array of `u8` values.
+- or as a slice of `u8` values.
+
+
+#### Sentinel-terminated arrays
+
+Sentinel-terminated arrays in Zig are described in the Language Reference of Zig[^sentinel].
+In summary a sentinel-terminated array is just a normal array, but, the difference is that they
+contain a "sentinel value" at the last index/element of the array. With a sentinel-terminated array
+you embed both the length of the array, and also, the sentinel value in the type itself of your object.
+
+[^sentinel]: <https://ziglang.org/documentation/master/#Sentinel-Terminated-Arrays>.
+
+For example, if you write a string literal value in your code, and ask Zig to print the data type of this value,
+you usually get a data type in the format `*const [n:0]u8`. The `n` in the data type indicates the size of
+the string (that is the length of the array). The zero after the `n:` part of the data type is the sentinel
+value itself.
 
 ```{zig}
-#| auto_main: false
+#| eval: true
+#| auto_main: true
 #| build_type: "run"
-const std = @import("std");
-const stdout = std.io.getStdOut().writer();
-pub fn main() !void {
-    const string_object = "This is an example";
-    try stdout.print("Bytes that represents the string object: ", .{});
-    for (string_object) |byte| {
-        try stdout.print("{X} ", .{byte});
-    }
-    try stdout.print("\n", .{});
-}
+// This is a string literal value:
+_ = "A literal value";
+try stdout.print("{any}\n", .{@TypeOf("A literal value")});
 ```
 
 
-### Strings in C
+So, with this data type `*const [n:0]u8` you are essentially saying that you have an array of `u8` values
+of length `n`, where, the element at the index corresponding to the length `n` in the array is the
+number zero. If you really think about this description, you will notice that this is just a fancy way to
+describe a string in C, which is a null-terminated array of bytes. The `NULL` value in C is the number
+zero. So, an array that ends in a null/zero value in C is essentially a sentinel-terminated array in Zig,
+where the sentinel value of the array is the number zero.
 
-At first glance, a string literal value in Zig looks very similar to how C treats strings as well.
-In more details, string values in C are treated internally as an array of arbitrary bytes,
-and this array is also null-terminated.
+Therefore, a string literal value in Zig is just a pointer to a null-terminated array of bytes (i.e., similar to a C string).
+But in Zig, a string literal value also embeds the length of the string, and also, the fact that they are "NULL terminated",
+into the data type of the value itself.
 
-But one key difference between a Zig string literal and a C string, is that Zig also stores the length of
-the string inside the object itself. In the case of a string literal value, this length is stored in the
-data type of the value (i.e., the `n` variable in `[n:0]u8`). While, in a string object, the length is stored
-in the `len` attribute of the slice that represents the string object. This small detail makes your code safer,
-because it's much easier for the Zig compiler to check if you are trying to access an element that is
-"out of bounds", i.e., if your trying to access memory that does not belong to you.
 
-To achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.
-So getting this kind of safety is not automatic and much harder to do in C. For example, if you want
-to track the length of your string throughout your program in C, then, you first need to loop through
-the array of bytes that represents this string, and find the null element (`'\0'`) position to discover
-where exactly the array ends, or, in other words, to find how much elements the array of bytes contain.
 
-To do that, you would need something like this in C. In this example, the C string stored in
-the object `array` is 25 bytes long:
+#### Slice
 
-```{c}
-#| eval: false
-#include <stdio.h>
-int main() {
-    char* array = "An example of string in C";
-    int index = 0;
-    while (1) {
-        if (array[index] == '\0') {
-            break;
-        }
-        index++;
-    }
-    printf("Number of elements in the array: %d\n", index);
-}
-```
+You can also access and use the arbitrary sequence of bytes that represent your string as a slice of `u8` values.
+The majority of functions from the Zig standard library usually receive strings as inputs as slices of
+`u8` values (slices were presented in @sec-arrays).
 
-```
-Number of elements in the array: 25
+Thus, you will see a lot of string values with a data type of `[]u8` or `[]const u8`, depending if the object
+where this string is stored is marked as constant with `const`, or as variable with `var`. Now, because
+the string in this case is being interpreted as a slice, this slice is not necessarilly null-terminated,
+because now, the sentinel value is not mandatory. You can include the null/zero value in the slice if you
+want to, but there is no need to do it.
+
+```{zig}
+#| eval: true
+#| build_type: "run"
+#| auto_main: true
+// This is a string value being
+// interpreted as a slice.
+const str: []const u8 = "A string value";
+try stdout.print("{any}\n", .{@TypeOf(str)});
 ```
 
 
-You don't have this kind of work in Zig. Because the length of the string is always
-present and accessible. In a string object for example, you can easily access the length of the string
-through the `len` attribute. As an example, the `string_object` object below is 43 bytes long:
 
+### Iterating through the string
+
+If you want to see the actual bytes that represents a string in Zig, you can use
+a `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal
+value to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,
+like you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.
+
+[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>
 
 ```{zig}
 #| auto_main: false
@@ -1306,12 +1348,17 @@ through the `len` attribute. As an example, the `string_object` object below is
 const std = @import("std");
 const stdout = std.io.getStdOut().writer();
 pub fn main() !void {
-    const string_object = "This is an example of string literal in Zig";
-    try stdout.print("{d}\n", .{string_object.len});
+    const string_object = "This is an example";
+    try stdout.print("Bytes that represents the string object: ", .{});
+    for (string_object) |byte| {
+        try stdout.print("{X} ", .{byte});
+    }
+    try stdout.print("\n", .{});
 }
 ```
 
 
+
 ### A better look at the object type
 
 Now, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the
@@ -1321,7 +1368,8 @@ That is what an object of type `[4]i32` is.
 
 But if we look closely at the type of the string literal value exposed below, you will find that this object is a
 constant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a
-single byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.
+single byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below,
+and also, you can see that this is a null-terminated array, because of the zero value after the `:` character in the data type.
 In other words, the string literal value exposed below is 16 bytes long.
 
 Now, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),
@@ -1337,6 +1385,7 @@ the `const u8` portion of the type).
 #| build_type: "run"
 #| auto_main: false
 #| eval: true
+#| results: "hide"
 const std = @import("std");
 pub fn main() !void {
     const simple_array = [_]i32{1, 2, 3, 4};
diff --git a/_freeze/Chapters/01-zig-weird/execute-results/html.json b/_freeze/Chapters/01-zig-weird/execute-results/html.json
index 0444b72e..4f120244 100644
--- a/_freeze/Chapters/01-zig-weird/execute-results/html.json
+++ b/_freeze/Chapters/01-zig-weird/execute-results/html.json
@@ -1,9 +1,11 @@
 {
-  "hash": "06a3119bbdf9be9d02679617c65c9d79",
+  "hash": "569cc4cd11b03e6a2e83a391821389ed",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\n\nlanguage, it's still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. Sometimes, they really make it hard to debug\n\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscure the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that gets compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e., where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contains Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nWe can use this build system to write small scripts in Zig,\nwhich describe the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e., creating new objects)\nare made in Zig. You can create a new object in Zig by using the syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). In @sec-assignments we talk more about objects in general.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that in @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIt's worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt's like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portable C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nIn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e., the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. If you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith an \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, on Windows, operations like accessing the `stdout` (or opening a file) depend on\nresources that are available only at *runtime* (you will learn more about compile-time versus runtime\nin @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerges from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword in @sec-comptime.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation in a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues\n\n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described in @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig later in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig?\nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar to our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentation.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It's a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (on YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e., identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nSo, if you want to change the value of your object, you need to transform your immutable (or \"constant\")\nobject into a mutable (or \"variable\") object. You can do that by using the `var` keyword.\nThis keyword stands for \"variable\", and when you apply this keyword to some object, you are\ntelling the Zig compiler that the value associated with this object might change at some point.\n\nThus, if we come back to the previous example, and change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it's a \"variable object\".\n\nHowever, if you take a look at the example below, you will notice that we have not only declared the\n`age` object with the `var` keyword, but we also have explicitly annotated the data type\nof the `age` object with the `u8` type this time. The basic idea is, when we use a variable/mutable object,\nthe Zig compiler ask for us to be more explicit with what we want, to be more clear\nabout what our code does. This translates into being more explicit about the data types that we want\nto use in our objects.\n\nTherefore, if you transform your object into a variable/mutable object, just remember to always\nannotate the type of the object explicitly in your code. Otherwise, the Zig compiler might raise\na compilation error, asking you to transform your object back into a `const` object, or,\nto give your object an \"explicit type\".\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIt's important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code uses this object while it's uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object.\n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e., if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to a special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It's discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also gets discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e., the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\n\nIt's worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it's a slice that\naccesses all elements in the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" in @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth in @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially in @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned in @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e., both the start and the end of this range)\nis known at compile-time, the slice object that gets created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nin @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that gets created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e., a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can\ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n_ = slice;\n```\n:::\n\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat gets created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, we are reading a file, and then, we try to create a slice object\nthat covers the entire buffer that contains the contents of this file. This is obviously\nan example of a runtime known range, because the end index of the range\nis not known at compile time.\n\nIn other words, the end index of the range is the size of\nthe array `file_contents`. However, the size of `file_contents` is not known at compile time.\nBecause we don't know how many bytes are stored inside this `shop-list.txt` file.\nAnd because this is a file, someone might edit this file tomorrow and add more lines\nor remove lines from it. Therefore, the size of this file might vary drastically from one execution to another.\n\nNow, if the file size can vary from one run to another, then, we can conclude that the value of the expression\n`file_contents.len` exposed in the example below can also vary from one run to another. As consequence,\nthe value of the expression `file_contents.len` is runtime-known only, and, as a consequence of that,\nthe range `0..file_contents.len` is also runtime-known only.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\nfn read_file(allocator: std.mem.Allocator, path: []const u8) ![]u8 {\n    const file = try std.fs.cwd().openFile(path, .{});\n    defer file.close();\n    return try file.reader().readAllAlloc(\n        allocator, std.math.maxInt(usize)\n    );\n}\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const path = \"../ZigExamples/file-io/shop-list.txt\";\n    const file_contents = try read_file(allocator, path);\n    const slice = file_contents[0..file_contents.len];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e., a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nIn summary, there are two types of string values that you care about in Zig, which are:\n\n- String literal values.\n- String objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e., similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string into the data type of the value itself.\nTherefore, a string literal value have a data type in the format `*const [n:0]u8`. The `n` in the data type\nindicates the size of the string.\n\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes,\nor, in other words, a slice of `u8` values (slices were presented in @sec-arrays). Thus,\na string object have a data type of `[]u8` or `[]const u8`, depending if the string object is\nmarked as constant with `const`, or as variable with `var`.\n\nBecause a string object is essentially a slice, it means that a string object always contains two things:\na pointer to an array of bytes (i.e., `u8` values) that represents the string value; and also, a length value,\nwhich specifies the size of the slice, or, how many elements there is in the slice.\nIt's worth to emphasize that the array of bytes in a string object is not null-terminated, like in a\nstring literal value.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n```\n:::\n\n\n\n\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e., a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Strings in C\n\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well.\nIn more details, string values in C are treated internally as an array of arbitrary bytes,\nand this array is also null-terminated.\n\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of\nthe string inside the object itself. In the case of a string literal value, this length is stored in the\ndata type of the value (i.e., the `n` variable in `[n:0]u8`). While, in a string object, the length is stored\nin the `len` attribute of the slice that represents the string object. This small detail makes your code safer,\nbecause it's much easier for the Zig compiler to check if you are trying to access an element that is\n\"out of bounds\", i.e., if your trying to access memory that does not belong to you.\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible. In a string object for example, you can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it's a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n```\n\n\n:::\n:::\n\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIt's important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig in @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers in @sec-root-file and especially in @sec-assignments.\n- How strings work in Zig in @sec-zig-strings.\n- How to use arrays and slices in @sec-arrays.\n- How to import functionality from other Zig modules in @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* in @sec-structs-and-oop.\n- Basic control flow syntax in @sec-zig-control-flow.\n- Enums in @sec-enum;\n- Pointers and Optionals in @sec-pointer;\n- Error handling with `try` and `catch` in @sec-error-handling;\n- Unit tests in @sec-unittests;\n- Vectors in @sec-vectors-simd;\n- Build System in @sec-build-system;\n",
-    "supporting": [],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\n\nlanguage, it's still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. Sometimes, they really make it hard to debug\n\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscure the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that gets compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e., where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contains Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nWe can use this build system to write small scripts in Zig,\nwhich describe the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e., creating new objects)\nare made in Zig. You can create a new object in Zig by using the syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). In @sec-assignments we talk more about objects in general.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that in @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIt's worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt's like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portable C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nIn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e., the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. If you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith an \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, on Windows, operations like accessing the `stdout` (or opening a file) depend on\nresources that are available only at *runtime* (you will learn more about compile-time versus runtime\nin @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerges from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword in @sec-comptime.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation in a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues\n\n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described in @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig later in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig?\nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar to our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentation.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It's a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (on YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e., identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nSo, if you want to change the value of your object, you need to transform your immutable (or \"constant\")\nobject into a mutable (or \"variable\") object. You can do that by using the `var` keyword.\nThis keyword stands for \"variable\", and when you apply this keyword to some object, you are\ntelling the Zig compiler that the value associated with this object might change at some point.\n\nThus, if we come back to the previous example, and change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it's a \"variable object\".\n\nHowever, if you take a look at the example below, you will notice that we have not only declared the\n`age` object with the `var` keyword, but we also have explicitly annotated the data type\nof the `age` object with the `u8` type this time. The basic idea is, when we use a variable/mutable object,\nthe Zig compiler ask for us to be more explicit with what we want, to be more clear\nabout what our code does. This translates into being more explicit about the data types that we want\nto use in our objects.\n\nTherefore, if you transform your object into a variable/mutable object, just remember to always\nannotate the type of the object explicitly in your code. Otherwise, the Zig compiler might raise\na compilation error, asking you to transform your object back into a `const` object, or,\nto give your object an \"explicit type\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIt's important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code uses this object while it's uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object.\n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e., if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to a special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It's discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also gets discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e., the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\nIt's worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it's a slice that\naccesses all elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" in @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth in @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially in @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned in @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e., both the start and the end of this range)\nis known at compile-time, the slice object that gets created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nin @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that gets created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e., a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can\ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n_ = slice;\n```\n:::\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat gets created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, we are reading a file, and then, we try to create a slice object\nthat covers the entire buffer that contains the contents of this file. This is obviously\nan example of a runtime known range, because the end index of the range\nis not known at compile time.\n\nIn other words, the end index of the range is the size of\nthe array `file_contents`. However, the size of `file_contents` is not known at compile time.\nBecause we don't know how many bytes are stored inside this `shop-list.txt` file.\nAnd because this is a file, someone might edit this file tomorrow and add more lines\nor remove lines from it. Therefore, the size of this file might vary drastically from one execution to another.\n\nNow, if the file size can vary from one run to another, then, we can conclude that the value of the expression\n`file_contents.len` exposed in the example below can also vary from one run to another. As consequence,\nthe value of the expression `file_contents.len` is runtime-known only, and, as a consequence of that,\nthe range `0..file_contents.len` is also runtime-known only.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\nfn read_file(allocator: std.mem.Allocator, path: []const u8) ![]u8 {\n    const file = try std.fs.cwd().openFile(path, .{});\n    defer file.close();\n    return try file.reader().readAllAlloc(\n        allocator, std.math.maxInt(usize)\n    );\n}\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const path = \"../ZigExamples/file-io/shop-list.txt\";\n    const file_contents = try read_file(allocator, path);\n    const slice = file_contents[0..file_contents.len];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e., a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nStrings in Zig work very similarly to strings in C, but they come with some extra caveats which adds more safety\nand efficiency to them. You could also say that Zig simply uses a more modern and safe approach to manage\nand use strings.\n\nA string in Zig is essentially an array of arbitrary bytes, or, more specifically, an array of `u8` values.\nThis very similar to a string in C, which is also interpreted as an array of arbitrary bytes, or, in the case\nof C, an array of `char` (which usually represents an unsigned 8-bit integer value in most systems) values.\n\nNow, because a string in Zig is an array, you automatically\nget the length of the string (i.e. the length of the array) embedded in the value itself. This makes\nall the difference! Because now, the Zig compiler can use the length value that is embedded in the string to\ncheck for \"buffer overflow\" or \"wrong memory access\" problems in your code.\n\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need to do something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible in the string value itself. You can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\nAnother point is that Zig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e., a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Using a slice versus a sentinel-terminated array\n\nIn memory, all string values in Zig are always stored in the same way.\nThey are simply stored as sequences/arrays of arbitrary bytes. But you can use and access\nthis sequence of bytes in two different ways. You can access this sequence of bytes as:\n\n- a sentinel-terminated array of `u8` values.\n- or as a slice of `u8` values.\n\n\n#### Sentinel-terminated arrays\n\nSentinel-terminated arrays in Zig are described in the Language Reference of Zig[^sentinel].\nIn summary a sentinel-terminated array is just a normal array, but, the difference is that they\ncontain a \"sentinel value\" at the last index/element of the array. With a sentinel-terminated array\nyou embed both the length of the array, and also, the sentinel value in the type itself of your object.\n\n[^sentinel]: <https://ziglang.org/documentation/master/#Sentinel-Terminated-Arrays>.\n\nFor example, if you write a string literal value in your code, and ask Zig to print the data type of this value,\nyou usually get a data type in the format `*const [n:0]u8`. The `n` in the data type indicates the size of\nthe string (that is the length of the array). The zero after the `n:` part of the data type is the sentinel\nvalue itself.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n_ = \"A literal value\";\ntry stdout.print(\"{any}\\n\", .{@TypeOf(\"A literal value\")});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n*const [15:0]u8\n```\n\n\n:::\n:::\n\n\n\n\n\nSo, with this data type `*const [n:0]u8` you are essentially saying that you have an array of `u8` values\nof length `n`, where, the element at the index corresponding to the length `n` in the array is the\nnumber zero. If you really think about this description, you will notice that this is just a fancy way to\ndescribe a string in C, which is a null-terminated array of bytes. The `NULL` value in C is the number\nzero. So, an array that ends in a null/zero value in C is essentially a sentinel-terminated array in Zig,\nwhere the sentinel value of the array is the number zero.\n\nTherefore, a string literal value in Zig is just a pointer to a null-terminated array of bytes (i.e., similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string, and also, the fact that they are \"NULL terminated\",\ninto the data type of the value itself.\n\n\n\n#### Slice\n\nYou can also access and use the arbitrary sequence of bytes that represent your string as a slice of `u8` values.\nThe majority of functions from the Zig standard library usually receive strings as inputs as slices of\n`u8` values (slices were presented in @sec-arrays).\n\nThus, you will see a lot of string values with a data type of `[]u8` or `[]const u8`, depending if the object\nwhere this string is stored is marked as constant with `const`, or as variable with `var`. Now, because\nthe string in this case is being interpreted as a slice, this slice is not necessarilly null-terminated,\nbecause now, the sentinel value is not mandatory. You can include the null/zero value in the slice if you\nwant to, but there is no need to do it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string value being\n// interpreted as a slice.\nconst str: []const u8 = \"A string value\";\ntry stdout.print(\"{any}\\n\", .{@TypeOf(str)});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n[]const u8\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Iterating through the string\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below,\nand also, you can see that this is a null-terminated array, because of the zero value after the `:` character in the data type.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it's a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n:::\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIt's important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig in @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers in @sec-root-file and especially in @sec-assignments.\n- How strings work in Zig in @sec-zig-strings.\n- How to use arrays and slices in @sec-arrays.\n- How to import functionality from other Zig modules in @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* in @sec-structs-and-oop.\n- Basic control flow syntax in @sec-zig-control-flow.\n- Enums in @sec-enum;\n- Pointers and Optionals in @sec-pointer;\n- Error handling with `try` and `catch` in @sec-error-handling;\n- Unit tests in @sec-unittests;\n- Vectors in @sec-vectors-simd;\n- Build System in @sec-build-system;\n",
+    "supporting": [
+      "01-zig-weird_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/docs/Chapters/01-zig-weird.html b/docs/Chapters/01-zig-weird.html
index 34c1d875..4c437852 100644
--- a/docs/Chapters/01-zig-weird.html
+++ b/docs/Chapters/01-zig-weird.html
@@ -328,10 +328,11 @@ <h2 id="toc-title">Table of contents</h2>
   <li><a href="#sec-blocks" id="toc-sec-blocks" class="nav-link" data-scroll-target="#sec-blocks"><span class="header-section-number">1.7</span> Blocks and scopes</a></li>
   <li><a href="#sec-zig-strings" id="toc-sec-zig-strings" class="nav-link" data-scroll-target="#sec-zig-strings"><span class="header-section-number">1.8</span> How strings work in Zig?</a>
   <ul class="collapse">
-  <li><a href="#strings-in-c" id="toc-strings-in-c" class="nav-link" data-scroll-target="#strings-in-c"><span class="header-section-number">1.8.1</span> Strings in C</a></li>
-  <li><a href="#a-better-look-at-the-object-type" id="toc-a-better-look-at-the-object-type" class="nav-link" data-scroll-target="#a-better-look-at-the-object-type"><span class="header-section-number">1.8.2</span> A better look at the object type</a></li>
-  <li><a href="#byte-vs-unicode-points" id="toc-byte-vs-unicode-points" class="nav-link" data-scroll-target="#byte-vs-unicode-points"><span class="header-section-number">1.8.3</span> Byte vs unicode points</a></li>
-  <li><a href="#sec-strings-useful-funs" id="toc-sec-strings-useful-funs" class="nav-link" data-scroll-target="#sec-strings-useful-funs"><span class="header-section-number">1.8.4</span> Some useful functions for strings</a></li>
+  <li><a href="#using-a-slice-versus-a-sentinel-terminated-array" id="toc-using-a-slice-versus-a-sentinel-terminated-array" class="nav-link" data-scroll-target="#using-a-slice-versus-a-sentinel-terminated-array"><span class="header-section-number">1.8.1</span> Using a slice versus a sentinel-terminated array</a></li>
+  <li><a href="#iterating-through-the-string" id="toc-iterating-through-the-string" class="nav-link" data-scroll-target="#iterating-through-the-string"><span class="header-section-number">1.8.2</span> Iterating through the string</a></li>
+  <li><a href="#a-better-look-at-the-object-type" id="toc-a-better-look-at-the-object-type" class="nav-link" data-scroll-target="#a-better-look-at-the-object-type"><span class="header-section-number">1.8.3</span> A better look at the object type</a></li>
+  <li><a href="#byte-vs-unicode-points" id="toc-byte-vs-unicode-points" class="nav-link" data-scroll-target="#byte-vs-unicode-points"><span class="header-section-number">1.8.4</span> Byte vs unicode points</a></li>
+  <li><a href="#sec-strings-useful-funs" id="toc-sec-strings-useful-funs" class="nav-link" data-scroll-target="#sec-strings-useful-funs"><span class="header-section-number">1.8.5</span> Some useful functions for strings</a></li>
   </ul></li>
   <li><a href="#safety-in-zig" id="toc-safety-in-zig" class="nav-link" data-scroll-target="#safety-in-zig"><span class="header-section-number">1.9</span> Safety in Zig</a></li>
   <li><a href="#other-parts-of-zig" id="toc-other-parts-of-zig" class="nav-link" data-scroll-target="#other-parts-of-zig"><span class="header-section-number">1.10</span> Other parts of Zig</a></li>
@@ -817,136 +818,156 @@ <h2 data-number="1.7" class="anchored" data-anchor-id="sec-blocks"><span class="
 <section id="sec-zig-strings" class="level2" data-number="1.8">
 <h2 data-number="1.8" class="anchored" data-anchor-id="sec-zig-strings"><span class="header-section-number">1.8</span> How strings work in Zig?</h2>
 <p>The first project that we are going to build and discuss in this book is a base64 encoder/decoder (<a href="01-base64.html" class="quarto-xref"><span>Chapter 4</span></a>). But in order for us to build such a thing, we need to get a better understanding on how strings work in Zig. So let’s discuss this specific aspect of Zig.</p>
-<p>In summary, there are two types of string values that you care about in Zig, which are:</p>
-<ul>
-<li>String literal values.</li>
-<li>String objects.</li>
-</ul>
-<p>A string literal value is just a pointer to a null-terminated array of bytes (i.e., similar to a C string). But in Zig, a string literal value also embeds the length of the string into the data type of the value itself. Therefore, a string literal value have a data type in the format <code>*const [n:0]u8</code>. The <code>n</code> in the data type indicates the size of the string.</p>
-<p>On the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes, or, in other words, a slice of <code>u8</code> values (slices were presented in <a href="#sec-arrays" class="quarto-xref"><span>Section 1.6</span></a>). Thus, a string object have a data type of <code>[]u8</code> or <code>[]const u8</code>, depending if the string object is marked as constant with <code>const</code>, or as variable with <code>var</code>.</p>
-<p>Because a string object is essentially a slice, it means that a string object always contains two things: a pointer to an array of bytes (i.e., <code>u8</code> values) that represents the string value; and also, a length value, which specifies the size of the slice, or, how many elements there is in the slice. It’s worth to emphasize that the array of bytes in a string object is not null-terminated, like in a string literal value.</p>
+<p>Strings in Zig work very similarly to strings in C, but they come with some extra caveats which adds more safety and efficiency to them. You could also say that Zig simply uses a more modern and safe approach to manage and use strings.</p>
+<p>A string in Zig is essentially an array of arbitrary bytes, or, more specifically, an array of <code>u8</code> values. This very similar to a string in C, which is also interpreted as an array of arbitrary bytes, or, in the case of C, an array of <code>char</code> (which usually represents an unsigned 8-bit integer value in most systems) values.</p>
+<p>Now, because a string in Zig is an array, you automatically get the length of the string (i.e.&nbsp;the length of the array) embedded in the value itself. This makes all the difference! Because now, the Zig compiler can use the length value that is embedded in the string to check for “buffer overflow” or “wrong memory access” problems in your code.</p>
+<p>To achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless. So getting this kind of safety is not automatic and much harder to do in C. For example, if you want to track the length of your string throughout your program in C, then, you first need to loop through the array of bytes that represents this string, and find the null element (<code>'\0'</code>) position to discover where exactly the array ends, or, in other words, to find how much elements the array of bytes contain.</p>
+<p>To do that, you would need to do something like this in C. In this example, the C string stored in the object <code>array</code> is 25 bytes long:</p>
+<div class="cell">
+<div class="sourceCode cell-code" id="cb48"><pre class="sourceCode c code-with-copy"><code class="sourceCode c"><span id="cb48-1"><a href="#cb48-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im">&lt;stdio.h&gt;</span></span>
+<span id="cb48-2"><a href="#cb48-2" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> main<span class="op">()</span> <span class="op">{</span></span>
+<span id="cb48-3"><a href="#cb48-3" aria-hidden="true" tabindex="-1"></a>    <span class="dt">char</span><span class="op">*</span> array <span class="op">=</span> <span class="st">"An example of string in C"</span><span class="op">;</span></span>
+<span id="cb48-4"><a href="#cb48-4" aria-hidden="true" tabindex="-1"></a>    <span class="dt">int</span> index <span class="op">=</span> <span class="dv">0</span><span class="op">;</span></span>
+<span id="cb48-5"><a href="#cb48-5" aria-hidden="true" tabindex="-1"></a>    <span class="cf">while</span> <span class="op">(</span><span class="dv">1</span><span class="op">)</span> <span class="op">{</span></span>
+<span id="cb48-6"><a href="#cb48-6" aria-hidden="true" tabindex="-1"></a>        <span class="cf">if</span> <span class="op">(</span>array<span class="op">[</span>index<span class="op">]</span> <span class="op">==</span> <span class="ch">'</span><span class="sc">\0</span><span class="ch">'</span><span class="op">)</span> <span class="op">{</span></span>
+<span id="cb48-7"><a href="#cb48-7" aria-hidden="true" tabindex="-1"></a>            <span class="cf">break</span><span class="op">;</span></span>
+<span id="cb48-8"><a href="#cb48-8" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span></span>
+<span id="cb48-9"><a href="#cb48-9" aria-hidden="true" tabindex="-1"></a>        index<span class="op">++;</span></span>
+<span id="cb48-10"><a href="#cb48-10" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb48-11"><a href="#cb48-11" aria-hidden="true" tabindex="-1"></a>    printf<span class="op">(</span><span class="st">"Number of elements in the array: </span><span class="sc">%d\n</span><span class="st">"</span><span class="op">,</span> index<span class="op">);</span></span>
+<span id="cb48-12"><a href="#cb48-12" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+</div>
+<pre><code>Number of elements in the array: 25</code></pre>
+<p>You don’t have this kind of work in Zig. Because the length of the string is always present and accessible in the string value itself. You can easily access the length of the string through the <code>len</code> attribute. As an example, the <code>string_object</code> object below is 43 bytes long:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb48"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb48-1"><a href="#cb48-1" aria-hidden="true" tabindex="-1"></a><span class="co">// This is a string literal value:</span></span>
-<span id="cb48-2"><a href="#cb48-2" aria-hidden="true" tabindex="-1"></a><span class="st">"A literal value"</span>;</span>
-<span id="cb48-3"><a href="#cb48-3" aria-hidden="true" tabindex="-1"></a><span class="co">// This is a string object:</span></span>
-<span id="cb48-4"><a href="#cb48-4" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> object: []<span class="kw">const</span> <span class="dt">u8</span> = <span class="st">"A string object"</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb50"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb50-1"><a href="#cb50-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb50-2"><a href="#cb50-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
+<span id="cb50-3"><a href="#cb50-3" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb50-4"><a href="#cb50-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> string_object = <span class="st">"This is an example of string literal in Zig"</span>;</span>
+<span id="cb50-5"><a href="#cb50-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>string_object.len<span class="op">}</span>);</span>
+<span id="cb50-6"><a href="#cb50-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="cell-output cell-output-stdout">
+<pre><code>43</code></pre>
 </div>
-<p>Zig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every sequence of bytes you’re working with, but is not really Zig’s job to fix the encoding of your strings (you can use <a href="https://www.gnu.org/software/libiconv/"><code>iconv</code></a><a href="#fn22" class="footnote-ref" id="fnref22" role="doc-noteref"><sup>22</sup></a> for that). Today, most of the text in our modern world, especially on the web, should be UTF-8 encoded. So if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.</p>
+</div>
+<p>Another point is that Zig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every sequence of bytes you’re working with, but is not really Zig’s job to fix the encoding of your strings (you can use <a href="https://www.gnu.org/software/libiconv/"><code>iconv</code></a><a href="#fn22" class="footnote-ref" id="fnref22" role="doc-noteref"><sup>22</sup></a> for that). Today, most of the text in our modern world, especially on the web, should be UTF-8 encoded. So if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.</p>
 <p>Let’s take for example the word “Hello”. In UTF-8, this sequence of characters (H, e, l, l, o) is represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this sequence is <code>0x48</code>, <code>0x65</code>, <code>0x6C</code>, <code>0x6C</code>, <code>0x6F</code>. So if I take this sequence of hexadecimal values, and ask Zig to print this sequence of bytes as a sequence of characters (i.e., a string), then, the text “Hello” will be printed into the terminal:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb49"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb49-1"><a href="#cb49-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb49-2"><a href="#cb49-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
-<span id="cb49-3"><a href="#cb49-3" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb49-4"><a href="#cb49-4" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb49-5"><a href="#cb49-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> bytes = [_]<span class="dt">u8</span><span class="op">{</span><span class="bn">0x48</span>, <span class="bn">0x65</span>, <span class="bn">0x6C</span>, <span class="bn">0x6C</span>, <span class="bn">0x6F</span><span class="op">}</span>;</span>
-<span id="cb49-6"><a href="#cb49-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"{s}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>bytes<span class="op">}</span>);</span>
-<span id="cb49-7"><a href="#cb49-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb52"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb52-1"><a href="#cb52-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb52-2"><a href="#cb52-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
+<span id="cb52-3"><a href="#cb52-3" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb52-4"><a href="#cb52-4" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb52-5"><a href="#cb52-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> bytes = [_]<span class="dt">u8</span><span class="op">{</span><span class="bn">0x48</span>, <span class="bn">0x65</span>, <span class="bn">0x6C</span>, <span class="bn">0x6C</span>, <span class="bn">0x6F</span><span class="op">}</span>;</span>
+<span id="cb52-6"><a href="#cb52-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"{s}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>bytes<span class="op">}</span>);</span>
+<span id="cb52-7"><a href="#cb52-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>Hello</code></pre>
 </div>
 </div>
-<p>If you want to see the actual bytes that represents a string in Zig, you can use a <code>for</code> loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal value to the terminal. You do that by using a <code>print()</code> statement with the <code>X</code> formatting specifier, like you would normally do with the <a href="https://cplusplus.com/reference/cstdio/printf/"><code>printf()</code> function</a><a href="#fn23" class="footnote-ref" id="fnref23" role="doc-noteref"><sup>23</sup></a> in C.</p>
+<section id="using-a-slice-versus-a-sentinel-terminated-array" class="level3" data-number="1.8.1">
+<h3 data-number="1.8.1" class="anchored" data-anchor-id="using-a-slice-versus-a-sentinel-terminated-array"><span class="header-section-number">1.8.1</span> Using a slice versus a sentinel-terminated array</h3>
+<p>In memory, all string values in Zig are always stored in the same way. They are simply stored as sequences/arrays of arbitrary bytes. But you can use and access this sequence of bytes in two different ways. You can access this sequence of bytes as:</p>
+<ul>
+<li>a sentinel-terminated array of <code>u8</code> values.</li>
+<li>or as a slice of <code>u8</code> values.</li>
+</ul>
+<section id="sentinel-terminated-arrays" class="level4" data-number="1.8.1.1">
+<h4 data-number="1.8.1.1" class="anchored" data-anchor-id="sentinel-terminated-arrays"><span class="header-section-number">1.8.1.1</span> Sentinel-terminated arrays</h4>
+<p>Sentinel-terminated arrays in Zig are described in the Language Reference of Zig<a href="#fn23" class="footnote-ref" id="fnref23" role="doc-noteref"><sup>23</sup></a>. In summary a sentinel-terminated array is just a normal array, but, the difference is that they contain a “sentinel value” at the last index/element of the array. With a sentinel-terminated array you embed both the length of the array, and also, the sentinel value in the type itself of your object.</p>
+<p>For example, if you write a string literal value in your code, and ask Zig to print the data type of this value, you usually get a data type in the format <code>*const [n:0]u8</code>. The <code>n</code> in the data type indicates the size of the string (that is the length of the array). The zero after the <code>n:</code> part of the data type is the sentinel value itself.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb51"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb51-1"><a href="#cb51-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb51-2"><a href="#cb51-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
-<span id="cb51-3"><a href="#cb51-3" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb51-4"><a href="#cb51-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> string_object = <span class="st">"This is an example"</span>;</span>
-<span id="cb51-5"><a href="#cb51-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"Bytes that represents the string object: "</span>, .<span class="op">{}</span>);</span>
-<span id="cb51-6"><a href="#cb51-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">for</span> (string_object) |byte| <span class="op">{</span></span>
-<span id="cb51-7"><a href="#cb51-7" aria-hidden="true" tabindex="-1"></a>        <span class="kw">try</span> stdout.print(<span class="st">"{X} "</span>, .<span class="op">{</span>byte<span class="op">}</span>);</span>
-<span id="cb51-8"><a href="#cb51-8" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb51-9"><a href="#cb51-9" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{}</span>);</span>
-<span id="cb51-10"><a href="#cb51-10" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb54"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb54-1"><a href="#cb54-1" aria-hidden="true" tabindex="-1"></a><span class="co">// This is a string literal value:</span></span>
+<span id="cb54-2"><a href="#cb54-2" aria-hidden="true" tabindex="-1"></a>_ = <span class="st">"A literal value"</span>;</span>
+<span id="cb54-3"><a href="#cb54-3" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{any}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="bu">@TypeOf</span>(<span class="st">"A literal value"</span>)<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>Bytes that represents the string object: 54 68 69 
-   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 </code></pre>
+<pre><code>*const [15:0]u8</code></pre>
 </div>
 </div>
-<section id="strings-in-c" class="level3" data-number="1.8.1">
-<h3 data-number="1.8.1" class="anchored" data-anchor-id="strings-in-c"><span class="header-section-number">1.8.1</span> Strings in C</h3>
-<p>At first glance, a string literal value in Zig looks very similar to how C treats strings as well. In more details, string values in C are treated internally as an array of arbitrary bytes, and this array is also null-terminated.</p>
-<p>But one key difference between a Zig string literal and a C string, is that Zig also stores the length of the string inside the object itself. In the case of a string literal value, this length is stored in the data type of the value (i.e., the <code>n</code> variable in <code>[n:0]u8</code>). While, in a string object, the length is stored in the <code>len</code> attribute of the slice that represents the string object. This small detail makes your code safer, because it’s much easier for the Zig compiler to check if you are trying to access an element that is “out of bounds”, i.e., if your trying to access memory that does not belong to you.</p>
-<p>To achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless. So getting this kind of safety is not automatic and much harder to do in C. For example, if you want to track the length of your string throughout your program in C, then, you first need to loop through the array of bytes that represents this string, and find the null element (<code>'\0'</code>) position to discover where exactly the array ends, or, in other words, to find how much elements the array of bytes contain.</p>
-<p>To do that, you would need something like this in C. In this example, the C string stored in the object <code>array</code> is 25 bytes long:</p>
+<p>So, with this data type <code>*const [n:0]u8</code> you are essentially saying that you have an array of <code>u8</code> values of length <code>n</code>, where, the element at the index corresponding to the length <code>n</code> in the array is the number zero. If you really think about this description, you will notice that this is just a fancy way to describe a string in C, which is a null-terminated array of bytes. The <code>NULL</code> value in C is the number zero. So, an array that ends in a null/zero value in C is essentially a sentinel-terminated array in Zig, where the sentinel value of the array is the number zero.</p>
+<p>Therefore, a string literal value in Zig is just a pointer to a null-terminated array of bytes (i.e., similar to a C string). But in Zig, a string literal value also embeds the length of the string, and also, the fact that they are “NULL terminated”, into the data type of the value itself.</p>
+</section>
+<section id="slice" class="level4" data-number="1.8.1.2">
+<h4 data-number="1.8.1.2" class="anchored" data-anchor-id="slice"><span class="header-section-number">1.8.1.2</span> Slice</h4>
+<p>You can also access and use the arbitrary sequence of bytes that represent your string as a slice of <code>u8</code> values. The majority of functions from the Zig standard library usually receive strings as inputs as slices of <code>u8</code> values (slices were presented in <a href="#sec-arrays" class="quarto-xref"><span>Section 1.6</span></a>).</p>
+<p>Thus, you will see a lot of string values with a data type of <code>[]u8</code> or <code>[]const u8</code>, depending if the object where this string is stored is marked as constant with <code>const</code>, or as variable with <code>var</code>. Now, because the string in this case is being interpreted as a slice, this slice is not necessarilly null-terminated, because now, the sentinel value is not mandatory. You can include the null/zero value in the slice if you want to, but there is no need to do it.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb53"><pre class="sourceCode c code-with-copy"><code class="sourceCode c"><span id="cb53-1"><a href="#cb53-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im">&lt;stdio.h&gt;</span></span>
-<span id="cb53-2"><a href="#cb53-2" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> main<span class="op">()</span> <span class="op">{</span></span>
-<span id="cb53-3"><a href="#cb53-3" aria-hidden="true" tabindex="-1"></a>    <span class="dt">char</span><span class="op">*</span> array <span class="op">=</span> <span class="st">"An example of string in C"</span><span class="op">;</span></span>
-<span id="cb53-4"><a href="#cb53-4" aria-hidden="true" tabindex="-1"></a>    <span class="dt">int</span> index <span class="op">=</span> <span class="dv">0</span><span class="op">;</span></span>
-<span id="cb53-5"><a href="#cb53-5" aria-hidden="true" tabindex="-1"></a>    <span class="cf">while</span> <span class="op">(</span><span class="dv">1</span><span class="op">)</span> <span class="op">{</span></span>
-<span id="cb53-6"><a href="#cb53-6" aria-hidden="true" tabindex="-1"></a>        <span class="cf">if</span> <span class="op">(</span>array<span class="op">[</span>index<span class="op">]</span> <span class="op">==</span> <span class="ch">'</span><span class="sc">\0</span><span class="ch">'</span><span class="op">)</span> <span class="op">{</span></span>
-<span id="cb53-7"><a href="#cb53-7" aria-hidden="true" tabindex="-1"></a>            <span class="cf">break</span><span class="op">;</span></span>
-<span id="cb53-8"><a href="#cb53-8" aria-hidden="true" tabindex="-1"></a>        <span class="op">}</span></span>
-<span id="cb53-9"><a href="#cb53-9" aria-hidden="true" tabindex="-1"></a>        index<span class="op">++;</span></span>
-<span id="cb53-10"><a href="#cb53-10" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb53-11"><a href="#cb53-11" aria-hidden="true" tabindex="-1"></a>    printf<span class="op">(</span><span class="st">"Number of elements in the array: </span><span class="sc">%d\n</span><span class="st">"</span><span class="op">,</span> index<span class="op">);</span></span>
-<span id="cb53-12"><a href="#cb53-12" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb56"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb56-1"><a href="#cb56-1" aria-hidden="true" tabindex="-1"></a><span class="co">// This is a string value being</span></span>
+<span id="cb56-2"><a href="#cb56-2" aria-hidden="true" tabindex="-1"></a><span class="co">// interpreted as a slice.</span></span>
+<span id="cb56-3"><a href="#cb56-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> str: []<span class="kw">const</span> <span class="dt">u8</span> = <span class="st">"A string value"</span>;</span>
+<span id="cb56-4"><a href="#cb56-4" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{any}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="bu">@TypeOf</span>(str)<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="cell-output cell-output-stdout">
+<pre><code>[]const u8</code></pre>
 </div>
-<pre><code>Number of elements in the array: 25</code></pre>
-<p>You don’t have this kind of work in Zig. Because the length of the string is always present and accessible. In a string object for example, you can easily access the length of the string through the <code>len</code> attribute. As an example, the <code>string_object</code> object below is 43 bytes long:</p>
+</div>
+</section>
+</section>
+<section id="iterating-through-the-string" class="level3" data-number="1.8.2">
+<h3 data-number="1.8.2" class="anchored" data-anchor-id="iterating-through-the-string"><span class="header-section-number">1.8.2</span> Iterating through the string</h3>
+<p>If you want to see the actual bytes that represents a string in Zig, you can use a <code>for</code> loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal value to the terminal. You do that by using a <code>print()</code> statement with the <code>X</code> formatting specifier, like you would normally do with the <a href="https://cplusplus.com/reference/cstdio/printf/"><code>printf()</code> function</a><a href="#fn24" class="footnote-ref" id="fnref24" role="doc-noteref"><sup>24</sup></a> in C.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb55"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb55-1"><a href="#cb55-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb55-2"><a href="#cb55-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
-<span id="cb55-3"><a href="#cb55-3" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb55-4"><a href="#cb55-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> string_object = <span class="st">"This is an example of string literal in Zig"</span>;</span>
-<span id="cb55-5"><a href="#cb55-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"{d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>string_object.len<span class="op">}</span>);</span>
-<span id="cb55-6"><a href="#cb55-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb58"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb58-1"><a href="#cb58-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb58-2"><a href="#cb58-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
+<span id="cb58-3"><a href="#cb58-3" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb58-4"><a href="#cb58-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> string_object = <span class="st">"This is an example"</span>;</span>
+<span id="cb58-5"><a href="#cb58-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"Bytes that represents the string object: "</span>, .<span class="op">{}</span>);</span>
+<span id="cb58-6"><a href="#cb58-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">for</span> (string_object) |byte| <span class="op">{</span></span>
+<span id="cb58-7"><a href="#cb58-7" aria-hidden="true" tabindex="-1"></a>        <span class="kw">try</span> stdout.print(<span class="st">"{X} "</span>, .<span class="op">{</span>byte<span class="op">}</span>);</span>
+<span id="cb58-8"><a href="#cb58-8" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb58-9"><a href="#cb58-9" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{}</span>);</span>
+<span id="cb58-10"><a href="#cb58-10" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>43</code></pre>
+<pre><code>Bytes that represents the string object: 54 68 69 
+   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 </code></pre>
 </div>
 </div>
 </section>
-<section id="a-better-look-at-the-object-type" class="level3" data-number="1.8.2">
-<h3 data-number="1.8.2" class="anchored" data-anchor-id="a-better-look-at-the-object-type"><span class="header-section-number">1.8.2</span> A better look at the object type</h3>
+<section id="a-better-look-at-the-object-type" class="level3" data-number="1.8.3">
+<h3 data-number="1.8.3" class="anchored" data-anchor-id="a-better-look-at-the-object-type"><span class="header-section-number">1.8.3</span> A better look at the object type</h3>
 <p>Now, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the <code>@TypeOf()</code> function. If we look at the type of the <code>simple_array</code> object below, you will find that this object is an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type <code>i32</code> in Zig. That is what an object of type <code>[4]i32</code> is.</p>
-<p>But if we look closely at the type of the string literal value exposed below, you will find that this object is a constant pointer (hence the <code>*const</code> annotation) to an array of 16 elements (or 16 bytes). Each element is a single byte (more precisely, an unsigned 8 bit integer - <code>u8</code>), that is why we have the <code>[16:0]u8</code> portion of the type below. In other words, the string literal value exposed below is 16 bytes long.</p>
+<p>But if we look closely at the type of the string literal value exposed below, you will find that this object is a constant pointer (hence the <code>*const</code> annotation) to an array of 16 elements (or 16 bytes). Each element is a single byte (more precisely, an unsigned 8 bit integer - <code>u8</code>), that is why we have the <code>[16:0]u8</code> portion of the type below, and also, you can see that this is a null-terminated array, because of the zero value after the <code>:</code> character in the data type. In other words, the string literal value exposed below is 16 bytes long.</p>
 <p>Now, if we create an pointer to the <code>simple_array</code> object, then, we get a constant pointer to an array of 4 elements (<code>*const [4]i32</code>), which is very similar to the type of the string literal value. This demonstrates that a string literal value in Zig is already a pointer to a null-terminated array of bytes.</p>
 <p>Furthermore, if we take a look at the type of the <code>string_obj</code> object, you will see that it’s a slice object (hence the <code>[]</code> portion of the type) to a sequence of constant <code>u8</code> values (hence the <code>const u8</code> portion of the type).</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb57"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb57-1"><a href="#cb57-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb57-2"><a href="#cb57-2" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb57-3"><a href="#cb57-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> simple_array = [_]<span class="dt">i32</span><span class="op">{</span><span class="dv">1</span>, <span class="dv">2</span>, <span class="dv">3</span>, <span class="dv">4</span><span class="op">}</span>;</span>
-<span id="cb57-4"><a href="#cb57-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> string_obj: []<span class="kw">const</span> <span class="dt">u8</span> = <span class="st">"A string object"</span>;</span>
-<span id="cb57-5"><a href="#cb57-5" aria-hidden="true" tabindex="-1"></a>    std.debug.print(</span>
-<span id="cb57-6"><a href="#cb57-6" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Type 1: {}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="bu">@TypeOf</span>(simple_array)<span class="op">}</span></span>
-<span id="cb57-7"><a href="#cb57-7" aria-hidden="true" tabindex="-1"></a>    );</span>
-<span id="cb57-8"><a href="#cb57-8" aria-hidden="true" tabindex="-1"></a>    std.debug.print(</span>
-<span id="cb57-9"><a href="#cb57-9" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Type 2: {}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="bu">@TypeOf</span>(<span class="st">"A string literal"</span>)<span class="op">}</span></span>
-<span id="cb57-10"><a href="#cb57-10" aria-hidden="true" tabindex="-1"></a>    );</span>
-<span id="cb57-11"><a href="#cb57-11" aria-hidden="true" tabindex="-1"></a>    std.debug.print(</span>
-<span id="cb57-12"><a href="#cb57-12" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Type 3: {}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="bu">@TypeOf</span>(&amp;simple_array)<span class="op">}</span></span>
-<span id="cb57-13"><a href="#cb57-13" aria-hidden="true" tabindex="-1"></a>    );</span>
-<span id="cb57-14"><a href="#cb57-14" aria-hidden="true" tabindex="-1"></a>    std.debug.print(</span>
-<span id="cb57-15"><a href="#cb57-15" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Type 4: {}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="bu">@TypeOf</span>(string_obj)<span class="op">}</span></span>
-<span id="cb57-16"><a href="#cb57-16" aria-hidden="true" tabindex="-1"></a>    );</span>
-<span id="cb57-17"><a href="#cb57-17" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
-<div class="cell-output cell-output-stdout">
-<pre><code>Type 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons
-  st [4]i32Type 4: []const u8</code></pre>
-</div>
+<div class="sourceCode cell-code" id="cb60"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb60-1"><a href="#cb60-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb60-2"><a href="#cb60-2" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb60-3"><a href="#cb60-3" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> simple_array = [_]<span class="dt">i32</span><span class="op">{</span><span class="dv">1</span>, <span class="dv">2</span>, <span class="dv">3</span>, <span class="dv">4</span><span class="op">}</span>;</span>
+<span id="cb60-4"><a href="#cb60-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> string_obj: []<span class="kw">const</span> <span class="dt">u8</span> = <span class="st">"A string object"</span>;</span>
+<span id="cb60-5"><a href="#cb60-5" aria-hidden="true" tabindex="-1"></a>    std.debug.print(</span>
+<span id="cb60-6"><a href="#cb60-6" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Type 1: {}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="bu">@TypeOf</span>(simple_array)<span class="op">}</span></span>
+<span id="cb60-7"><a href="#cb60-7" aria-hidden="true" tabindex="-1"></a>    );</span>
+<span id="cb60-8"><a href="#cb60-8" aria-hidden="true" tabindex="-1"></a>    std.debug.print(</span>
+<span id="cb60-9"><a href="#cb60-9" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Type 2: {}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="bu">@TypeOf</span>(<span class="st">"A string literal"</span>)<span class="op">}</span></span>
+<span id="cb60-10"><a href="#cb60-10" aria-hidden="true" tabindex="-1"></a>    );</span>
+<span id="cb60-11"><a href="#cb60-11" aria-hidden="true" tabindex="-1"></a>    std.debug.print(</span>
+<span id="cb60-12"><a href="#cb60-12" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Type 3: {}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="bu">@TypeOf</span>(&amp;simple_array)<span class="op">}</span></span>
+<span id="cb60-13"><a href="#cb60-13" aria-hidden="true" tabindex="-1"></a>    );</span>
+<span id="cb60-14"><a href="#cb60-14" aria-hidden="true" tabindex="-1"></a>    std.debug.print(</span>
+<span id="cb60-15"><a href="#cb60-15" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Type 4: {}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span><span class="bu">@TypeOf</span>(string_obj)<span class="op">}</span></span>
+<span id="cb60-16"><a href="#cb60-16" aria-hidden="true" tabindex="-1"></a>    );</span>
+<span id="cb60-17"><a href="#cb60-17" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Type 1: [4]i32
 Type 2: *const [16:0]u8
 Type 3: *const [4]i32
 Type 4: []const u8</code></pre>
 </section>
-<section id="byte-vs-unicode-points" class="level3" data-number="1.8.3">
-<h3 data-number="1.8.3" class="anchored" data-anchor-id="byte-vs-unicode-points"><span class="header-section-number">1.8.3</span> Byte vs unicode points</h3>
+<section id="byte-vs-unicode-points" class="level3" data-number="1.8.4">
+<h3 data-number="1.8.4" class="anchored" data-anchor-id="byte-vs-unicode-points"><span class="header-section-number">1.8.4</span> Byte vs unicode points</h3>
 <p>It’s important to point out that each byte in the array is not necessarily a single character. This fact arises from the difference between a single byte and a single unicode point.</p>
 <p>The encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in the string. For example, the character “H” is stored in UTF-8 as the decimal number 72. This means that the number 72 is the unicode point for the character “H”. Each possible character that can appear in a UTF-8 encoded string have its own unicode point.</p>
 <p>For example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point) 570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which is 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why, the unicode point 570 is actually stored inside the computer’s memory as the bytes <code>C8 BA</code>.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb60"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb60-1"><a href="#cb60-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb60-2"><a href="#cb60-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
-<span id="cb60-3"><a href="#cb60-3" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb60-4"><a href="#cb60-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> string_object = <span class="st">"Ⱥ"</span>;</span>
-<span id="cb60-5"><a href="#cb60-5" aria-hidden="true" tabindex="-1"></a>    _ = <span class="kw">try</span> stdout.write(</span>
-<span id="cb60-6"><a href="#cb60-6" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Bytes that represents the string object: "</span></span>
-<span id="cb60-7"><a href="#cb60-7" aria-hidden="true" tabindex="-1"></a>    );</span>
-<span id="cb60-8"><a href="#cb60-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">for</span> (string_object) |char| <span class="op">{</span></span>
-<span id="cb60-9"><a href="#cb60-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">try</span> stdout.print(<span class="st">"{X} "</span>, .<span class="op">{</span>char<span class="op">}</span>);</span>
-<span id="cb60-10"><a href="#cb60-10" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb60-11"><a href="#cb60-11" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb62"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb62-1"><a href="#cb62-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb62-2"><a href="#cb62-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
+<span id="cb62-3"><a href="#cb62-3" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb62-4"><a href="#cb62-4" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> string_object = <span class="st">"Ⱥ"</span>;</span>
+<span id="cb62-5"><a href="#cb62-5" aria-hidden="true" tabindex="-1"></a>    _ = <span class="kw">try</span> stdout.write(</span>
+<span id="cb62-6"><a href="#cb62-6" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Bytes that represents the string object: "</span></span>
+<span id="cb62-7"><a href="#cb62-7" aria-hidden="true" tabindex="-1"></a>    );</span>
+<span id="cb62-8"><a href="#cb62-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">for</span> (string_object) |char| <span class="op">{</span></span>
+<span id="cb62-9"><a href="#cb62-9" aria-hidden="true" tabindex="-1"></a>        <span class="kw">try</span> stdout.print(<span class="st">"{X} "</span>, .<span class="op">{</span>char<span class="op">}</span>);</span>
+<span id="cb62-10"><a href="#cb62-10" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb62-11"><a href="#cb62-11" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>Bytes that represents the string object: C8 BA </code></pre>
 </div>
@@ -958,27 +979,27 @@ <h3 data-number="1.8.3" class="anchored" data-anchor-id="byte-vs-unicode-points"
 <p>If you need to iterate through the characters of a string, instead of its bytes, then, you can use the <code>std.unicode.Utf8View</code> struct to create an iterator that iterates through the unicode points of your string.</p>
 <p>In the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in this string is represented by three bytes. But the for loop iterates four times, one iteration for each character/unicode point in this string:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb62"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb62-1"><a href="#cb62-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb62-2"><a href="#cb62-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
-<span id="cb62-3"><a href="#cb62-3" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb62-4"><a href="#cb62-4" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb62-5"><a href="#cb62-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> utf8 = <span class="kw">try</span> std.unicode.Utf8View.init(<span class="st">"アメリカ"</span>);</span>
-<span id="cb62-6"><a href="#cb62-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> iterator = utf8.iterator();</span>
-<span id="cb62-7"><a href="#cb62-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">while</span> (iterator.nextCodepointSlice()) |codepoint| <span class="op">{</span></span>
-<span id="cb62-8"><a href="#cb62-8" aria-hidden="true" tabindex="-1"></a>        <span class="kw">try</span> stdout.print(</span>
-<span id="cb62-9"><a href="#cb62-9" aria-hidden="true" tabindex="-1"></a>            <span class="st">"got codepoint {}</span><span class="sc">\n</span><span class="st">"</span>,</span>
-<span id="cb62-10"><a href="#cb62-10" aria-hidden="true" tabindex="-1"></a>            .<span class="op">{</span>std.fmt.fmtSliceHexUpper(codepoint)<span class="op">}</span>,</span>
-<span id="cb62-11"><a href="#cb62-11" aria-hidden="true" tabindex="-1"></a>        );</span>
-<span id="cb62-12"><a href="#cb62-12" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
-<span id="cb62-13"><a href="#cb62-13" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb64"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb64-1"><a href="#cb64-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb64-2"><a href="#cb64-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
+<span id="cb64-3"><a href="#cb64-3" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb64-4"><a href="#cb64-4" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb64-5"><a href="#cb64-5" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> utf8 = <span class="kw">try</span> std.unicode.Utf8View.init(<span class="st">"アメリカ"</span>);</span>
+<span id="cb64-6"><a href="#cb64-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> iterator = utf8.iterator();</span>
+<span id="cb64-7"><a href="#cb64-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">while</span> (iterator.nextCodepointSlice()) |codepoint| <span class="op">{</span></span>
+<span id="cb64-8"><a href="#cb64-8" aria-hidden="true" tabindex="-1"></a>        <span class="kw">try</span> stdout.print(</span>
+<span id="cb64-9"><a href="#cb64-9" aria-hidden="true" tabindex="-1"></a>            <span class="st">"got codepoint {}</span><span class="sc">\n</span><span class="st">"</span>,</span>
+<span id="cb64-10"><a href="#cb64-10" aria-hidden="true" tabindex="-1"></a>            .<span class="op">{</span>std.fmt.fmtSliceHexUpper(codepoint)<span class="op">}</span>,</span>
+<span id="cb64-11"><a href="#cb64-11" aria-hidden="true" tabindex="-1"></a>        );</span>
+<span id="cb64-12"><a href="#cb64-12" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span></span>
+<span id="cb64-13"><a href="#cb64-13" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>got codepoint E382A2
 got codepoint E383A1
 got codepoint E383AA
 got codepoint E382AB</code></pre>
 </section>
-<section id="sec-strings-useful-funs" class="level3" data-number="1.8.4">
-<h3 data-number="1.8.4" class="anchored" data-anchor-id="sec-strings-useful-funs"><span class="header-section-number">1.8.4</span> Some useful functions for strings</h3>
+<section id="sec-strings-useful-funs" class="level3" data-number="1.8.5">
+<h3 data-number="1.8.5" class="anchored" data-anchor-id="sec-strings-useful-funs"><span class="header-section-number">1.8.5</span> Some useful functions for strings</h3>
 <p>In this section, I just want to quickly describe some functions from the Zig Standard Library that are very useful to use when working with strings. Most notably:</p>
 <ul>
 <li><code>std.mem.eql()</code>: to compare if two strings are equal.</li>
@@ -994,10 +1015,10 @@ <h3 data-number="1.8.4" class="anchored" data-anchor-id="sec-strings-useful-funs
 <p>Notice that all of these functions come from the <code>mem</code> module of the Zig Standard Library. This module contains multiple functions and methods that are useful to work with memory and sequences of bytes in general.</p>
 <p>The <code>eql()</code> function is used to check if two arrays of data are equal or not. Since strings are just arbitrary arrays of bytes, we can use this function to compare two strings together. This function returns a boolean value indicating if the two strings are equal or not. The first argument of this function is the data type of the elements of the arrays that are being compared.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb64"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb64-1"><a href="#cb64-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> name: []<span class="kw">const</span> <span class="dt">u8</span> = <span class="st">"Pedro"</span>;</span>
-<span id="cb64-2"><a href="#cb64-2" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(</span>
-<span id="cb64-3"><a href="#cb64-3" aria-hidden="true" tabindex="-1"></a>    <span class="st">"{any}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>std.mem.eql(<span class="dt">u8</span>, name, <span class="st">"Pedro"</span>)<span class="op">}</span></span>
-<span id="cb64-4"><a href="#cb64-4" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb66"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb66-1"><a href="#cb66-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> name: []<span class="kw">const</span> <span class="dt">u8</span> = <span class="st">"Pedro"</span>;</span>
+<span id="cb66-2"><a href="#cb66-2" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(</span>
+<span id="cb66-3"><a href="#cb66-3" aria-hidden="true" tabindex="-1"></a>    <span class="st">"{any}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>std.mem.eql(<span class="dt">u8</span>, name, <span class="st">"Pedro"</span>)<span class="op">}</span></span>
+<span id="cb66-4"><a href="#cb66-4" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>true</code></pre>
 </div>
@@ -1005,33 +1026,33 @@ <h3 data-number="1.8.4" class="anchored" data-anchor-id="sec-strings-useful-funs
 <p>The <code>splitScalar()</code> and <code>splitSequence()</code> functions are useful to split a string into multiple fragments, like the <code>split()</code> method from Python strings. The difference between these two methods is that the <code>splitScalar()</code> uses a single character as the separator to split the string, while <code>splitSequence()</code> uses a sequence of characters (a.k.a. a substring) as the separator. There is a practical example of these functions later in the book.</p>
 <p>The <code>startsWith()</code> and <code>endsWith()</code> functions are pretty straightforward. They return a boolean value indicating if the string (or, more precisely, if the array of data) begins (<code>startsWith</code>) or ends (<code>endsWith</code>) with the sequence provided.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb66"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb66-1"><a href="#cb66-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> name: []<span class="kw">const</span> <span class="dt">u8</span> = <span class="st">"Pedro"</span>;</span>
-<span id="cb66-2"><a href="#cb66-2" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(</span>
-<span id="cb66-3"><a href="#cb66-3" aria-hidden="true" tabindex="-1"></a>    <span class="st">"{any}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>std.mem.startsWith(<span class="dt">u8</span>, name, <span class="st">"Pe"</span>)<span class="op">}</span></span>
-<span id="cb66-4"><a href="#cb66-4" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb68"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb68-1"><a href="#cb68-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> name: []<span class="kw">const</span> <span class="dt">u8</span> = <span class="st">"Pedro"</span>;</span>
+<span id="cb68-2"><a href="#cb68-2" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(</span>
+<span id="cb68-3"><a href="#cb68-3" aria-hidden="true" tabindex="-1"></a>    <span class="st">"{any}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>std.mem.startsWith(<span class="dt">u8</span>, name, <span class="st">"Pe"</span>)<span class="op">}</span></span>
+<span id="cb68-4"><a href="#cb68-4" aria-hidden="true" tabindex="-1"></a>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
 <pre><code>true</code></pre>
 </div>
 </div>
 <p>The <code>concat()</code> function, as the name suggests, concatenate two or more strings together. Because the process of concatenating the strings involves allocating enough space to accomodate all the strings together, this <code>concat()</code> function receives an allocator object as input.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb68"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb68-1"><a href="#cb68-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> str1 = <span class="st">"Hello"</span>;</span>
-<span id="cb68-2"><a href="#cb68-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> str2 = <span class="st">" you!"</span>;</span>
-<span id="cb68-3"><a href="#cb68-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> str3 = <span class="kw">try</span> std.mem.concat(</span>
-<span id="cb68-4"><a href="#cb68-4" aria-hidden="true" tabindex="-1"></a>    allocator, <span class="dt">u8</span>, &amp;[_][]<span class="kw">const</span> <span class="dt">u8</span><span class="op">{</span> str1, str2 <span class="op">}</span></span>
-<span id="cb68-5"><a href="#cb68-5" aria-hidden="true" tabindex="-1"></a>);</span>
-<span id="cb68-6"><a href="#cb68-6" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{s}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>str3<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb70"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb70-1"><a href="#cb70-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> str1 = <span class="st">"Hello"</span>;</span>
+<span id="cb70-2"><a href="#cb70-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> str2 = <span class="st">" you!"</span>;</span>
+<span id="cb70-3"><a href="#cb70-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> str3 = <span class="kw">try</span> std.mem.concat(</span>
+<span id="cb70-4"><a href="#cb70-4" aria-hidden="true" tabindex="-1"></a>    allocator, <span class="dt">u8</span>, &amp;[_][]<span class="kw">const</span> <span class="dt">u8</span><span class="op">{</span> str1, str2 <span class="op">}</span></span>
+<span id="cb70-5"><a href="#cb70-5" aria-hidden="true" tabindex="-1"></a>);</span>
+<span id="cb70-6"><a href="#cb70-6" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"{s}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>str3<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>As you can imagine, the <code>replace()</code> function is used to replace substrings in a string by another substring. This function works very similarly to the <code>replace()</code> method from Python strings. Therefore, you provide a substring to search, and every time that the <code>replace()</code> function finds this substring within the input string, it replaces this substring with the “replacement substring” that you provided as input.</p>
 <p>In the example below, we are taking the input string “Hello”, and replacing all occurrences of the substring “el” inside this input string with “34”, and saving the results inside the <code>buffer</code> object. As result, the <code>replace()</code> function returns an <code>usize</code> value that indicates how many replacements were performed.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb69"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb69-1"><a href="#cb69-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> str1 = <span class="st">"Hello"</span>;</span>
-<span id="cb69-2"><a href="#cb69-2" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> buffer: [<span class="dv">5</span>]<span class="dt">u8</span> = <span class="cn">undefined</span>;</span>
-<span id="cb69-3"><a href="#cb69-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> nrep = std.mem.replace(</span>
-<span id="cb69-4"><a href="#cb69-4" aria-hidden="true" tabindex="-1"></a>    <span class="dt">u8</span>, str1, <span class="st">"el"</span>, <span class="st">"34"</span>, buffer[<span class="dv">0</span>..]</span>
-<span id="cb69-5"><a href="#cb69-5" aria-hidden="true" tabindex="-1"></a>);</span>
-<span id="cb69-6"><a href="#cb69-6" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"New string: {s}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>buffer<span class="op">}</span>);</span>
-<span id="cb69-7"><a href="#cb69-7" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"N of replacements: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>nrep<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb71"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb71-1"><a href="#cb71-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> str1 = <span class="st">"Hello"</span>;</span>
+<span id="cb71-2"><a href="#cb71-2" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> buffer: [<span class="dv">5</span>]<span class="dt">u8</span> = <span class="cn">undefined</span>;</span>
+<span id="cb71-3"><a href="#cb71-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> nrep = std.mem.replace(</span>
+<span id="cb71-4"><a href="#cb71-4" aria-hidden="true" tabindex="-1"></a>    <span class="dt">u8</span>, str1, <span class="st">"el"</span>, <span class="st">"34"</span>, buffer[<span class="dv">0</span>..]</span>
+<span id="cb71-5"><a href="#cb71-5" aria-hidden="true" tabindex="-1"></a>);</span>
+<span id="cb71-6"><a href="#cb71-6" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"New string: {s}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>buffer<span class="op">}</span>);</span>
+<span id="cb71-7"><a href="#cb71-7" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"N of replacements: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>nrep<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>New string: H34lo
 N of replacements: 1</code></pre>
@@ -1041,9 +1062,9 @@ <h3 data-number="1.8.4" class="anchored" data-anchor-id="sec-strings-useful-funs
 <h2 data-number="1.9" class="anchored" data-anchor-id="safety-in-zig"><span class="header-section-number">1.9</span> Safety in Zig</h2>
 <p>A general trend in modern low-level programming languages is safety. As our modern world becomes more interconnected with technology and computers, the data produced by all of this technology becomes one of the most important (and also, one of the most dangerous) assets that we have.</p>
 <p>This is probably the main reason why modern low-level programming languages have been giving great attention to safety, especially memory safety, because memory corruption is still the main target for hackers to exploit. The reality is that we don’t have an easy solution for this problem. For now, we only have techniques and strategies that mitigates these problems.</p>
-<p>As Richard Feldman explains on his <a href="https://www.youtube.com/watch?v=jIZpKpLCOiU&amp;ab_channel=GOTOConferences">most recent GOTO conference talk</a><a href="#fn24" class="footnote-ref" id="fnref24" role="doc-noteref"><sup>24</sup></a> , we haven’t figured it out yet a way to achieve <strong>true safety in technology</strong>. In other words, we haven’t found a way to build software that won’t be exploited with 100% certainty. We can greatly reduce the risks of our software being exploited, by ensuring memory safety for example. But this is not enough to achieve “true safety” territory.</p>
+<p>As Richard Feldman explains on his <a href="https://www.youtube.com/watch?v=jIZpKpLCOiU&amp;ab_channel=GOTOConferences">most recent GOTO conference talk</a><a href="#fn25" class="footnote-ref" id="fnref25" role="doc-noteref"><sup>25</sup></a> , we haven’t figured it out yet a way to achieve <strong>true safety in technology</strong>. In other words, we haven’t found a way to build software that won’t be exploited with 100% certainty. We can greatly reduce the risks of our software being exploited, by ensuring memory safety for example. But this is not enough to achieve “true safety” territory.</p>
 <p>Because even if you write your program in a “safe language”, hackers can still exploit failures in the operating system where your program is running (e.g.&nbsp;maybe the system where your code is running has a “backdoor exploit” that can still affect your code in unexpected ways), or also, they can exploit the features from the architecture of your computer. A recently found exploit that involves memory invalidation through a feature of “memory tags” present in ARM chips is an example of that <span class="citation" data-cites="exploit1">(<a href="../references.html#ref-exploit1" role="doc-biblioref">Kim et al. 2024</a>)</span>.</p>
-<p>The question is: what have Zig and other languages been doing to mitigate this problem? If we take Rust as an example, Rust is, for the most part<a href="#fn25" class="footnote-ref" id="fnref25" role="doc-noteref"><sup>25</sup></a>, a memory safe language by enforcing specific rules to the developer. In other words, the key feature of Rust, the <em>borrow checker</em>, forces you to follow a specific logic when you are writing your Rust code, and the Rust compiler will always complain everytime you try to go out of this pattern.</p>
+<p>The question is: what have Zig and other languages been doing to mitigate this problem? If we take Rust as an example, Rust is, for the most part<a href="#fn26" class="footnote-ref" id="fnref26" role="doc-noteref"><sup>26</sup></a>, a memory safe language by enforcing specific rules to the developer. In other words, the key feature of Rust, the <em>borrow checker</em>, forces you to follow a specific logic when you are writing your Rust code, and the Rust compiler will always complain everytime you try to go out of this pattern.</p>
 <p>In contrast, the Zig language is not a memory safe language by default. There are some memory safety features that you get for free in Zig, especially in arrays and pointer objects. But there are other tools offered by the language, that are not used by default. In other words, the <code>zig</code> compiler does not obligate you to use such tools.</p>
 <p>The tools listed below are related to memory safety. That is, they help you to achieve memory safety in your Zig code:</p>
 <ul>
@@ -1117,9 +1138,10 @@ <h2 data-number="1.10" class="anchored" data-anchor-id="other-parts-of-zig"><spa
 <li id="fn20"><p><a href="https://adventofcode.com/" class="uri">https://adventofcode.com/</a><a href="#fnref20" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
 <li id="fn21"><p><a href="https://ziglang.org/documentation/master/#Primitive-Types" class="uri">https://ziglang.org/documentation/master/#Primitive-Types</a>.<a href="#fnref21" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
 <li id="fn22"><p><a href="https://www.gnu.org/software/libiconv/" class="uri">https://www.gnu.org/software/libiconv/</a><a href="#fnref22" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn23"><p><a href="https://cplusplus.com/reference/cstdio/printf/" class="uri">https://cplusplus.com/reference/cstdio/printf/</a><a href="#fnref23" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn24"><p><a href="https://www.youtube.com/watch?v=jIZpKpLCOiU&amp;ab_channel=GOTOConferences" class="uri">https://www.youtube.com/watch?v=jIZpKpLCOiU&amp;ab_channel=GOTOConferences</a><a href="#fnref24" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
-<li id="fn25"><p>Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (<em>foreign function interface</em>), which disables the borrow-checker features through the <code>unsafe</code> keyword.<a href="#fnref25" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn23"><p><a href="https://ziglang.org/documentation/master/#Sentinel-Terminated-Arrays" class="uri">https://ziglang.org/documentation/master/#Sentinel-Terminated-Arrays</a>.<a href="#fnref23" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn24"><p><a href="https://cplusplus.com/reference/cstdio/printf/" class="uri">https://cplusplus.com/reference/cstdio/printf/</a><a href="#fnref24" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn25"><p><a href="https://www.youtube.com/watch?v=jIZpKpLCOiU&amp;ab_channel=GOTOConferences" class="uri">https://www.youtube.com/watch?v=jIZpKpLCOiU&amp;ab_channel=GOTOConferences</a><a href="#fnref25" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn26"><p>Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (<em>foreign function interface</em>), which disables the borrow-checker features through the <code>unsafe</code> keyword.<a href="#fnref26" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
 </ol>
 </section>
 
diff --git a/docs/Chapters/04-http-server.html b/docs/Chapters/04-http-server.html
index 81801ad0..40f84d66 100644
--- a/docs/Chapters/04-http-server.html
+++ b/docs/Chapters/04-http-server.html
@@ -670,7 +670,7 @@ <h3 data-number="7.7.5" class="anchored" data-anchor-id="writing-the-parse-reque
 <span id="cb15-12"><a href="#cb15-12" aria-hidden="true" tabindex="-1"></a>    <span class="kw">return</span> request;</span>
 <span id="cb15-13"><a href="#cb15-13" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>As I described in <a href="01-zig-weird.html#sec-zig-strings" class="quarto-xref"><span>Section 1.8</span></a>, strings in Zig are simply arrays of bytes in the language. So, you will find lots of excellent utility functions to work directly with strings inside this <code>mem</code> module from the Zig Standard Library. We have described some of these useful utility functions already in <a href="01-zig-weird.html#sec-strings-useful-funs" class="quarto-xref"><span>Section 1.8.4</span></a>.</p>
+<p>As I described in <a href="01-zig-weird.html#sec-zig-strings" class="quarto-xref"><span>Section 1.8</span></a>, strings in Zig are simply arrays of bytes in the language. So, you will find lots of excellent utility functions to work directly with strings inside this <code>mem</code> module from the Zig Standard Library. We have described some of these useful utility functions already in <a href="01-zig-weird.html#sec-strings-useful-funs" class="quarto-xref"><span>Section 1.8.5</span></a>.</p>
 </section>
 <section id="using-the-parse-request-function" class="level3" data-number="7.7.6">
 <h3 data-number="7.7.6" class="anchored" data-anchor-id="using-the-parse-request-function"><span class="header-section-number">7.7.6</span> Using the parse request function</h3>
@@ -745,7 +745,7 @@ <h3 data-number="7.7.7" class="anchored" data-anchor-id="sending-the-http-respon
 <h2 data-number="7.8" class="anchored" data-anchor-id="the-end-result"><span class="header-section-number">7.8</span> The end result</h2>
 <p>We can now, update once again our <code>main()</code> function to incorporate our new functions from the <code>response.zig</code> module. First, I need to import this module into our <code>main.zig</code> module, then, I add the function calls to <code>send_200()</code> and <code>send_404()</code>.</p>
 <p>Notice that I’m using if statements to decide which “response function” to call, based especially on the URI present in the HTTP Request. If the user asked for a content (or a document) that is not present in our server, we should respond with a 404 status code. But since we have just a simple HTTP server, with no real documents to send, we can just check if the URI is the root path (<code>/</code>) or not to decide which function to call.</p>
-<p>Also, notice that I’m using the function <code>std.mem.eql()</code> from the Zig Standard Library to check if the string from <code>uri</code> is equal or not the string <code>"/"</code>. We have described this function already in <a href="01-zig-weird.html#sec-strings-useful-funs" class="quarto-xref"><span>Section 1.8.4</span></a>, so, comeback to that section if you are not familiar yet with this function.</p>
+<p>Also, notice that I’m using the function <code>std.mem.eql()</code> from the Zig Standard Library to check if the string from <code>uri</code> is equal or not the string <code>"/"</code>. We have described this function already in <a href="01-zig-weird.html#sec-strings-useful-funs" class="quarto-xref"><span>Section 1.8.5</span></a>, so, comeback to that section if you are not familiar yet with this function.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb19"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb19-1"><a href="#cb19-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb19-2"><a href="#cb19-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> SocketConf = <span class="bu">@import</span>(<span class="st">"config.zig"</span>);</span>
diff --git a/docs/index.html b/docs/index.html
index e8b33e08..63c5d147 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -7,7 +7,7 @@
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 <meta name="author" content="Pedro Duarte Faria">
-<meta name="dcterms.date" content="2025-04-07">
+<meta name="dcterms.date" content="2025-04-09">
 
 <title>Introduction to Zig</title>
 <style>
@@ -287,7 +287,7 @@ <h1 class="title">Introduction to Zig</h1>
     <div>
     <div class="quarto-title-meta-heading">Published</div>
     <div class="quarto-title-meta-contents">
-      <p class="date">April 7, 2025</p>
+      <p class="date">April 9, 2025</p>
     </div>
   </div>
   
diff --git a/docs/search.json b/docs/search.json
index 3a49ec73..29d18ab1 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -184,7 +184,7 @@
     "href": "Chapters/01-zig-weird.html#sec-zig-strings",
     "title": "1  Introducing Zig",
     "section": "1.8 How strings work in Zig?",
-    "text": "1.8 How strings work in Zig?\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (Chapter 4). But in order for us to build such a thing, we need to get a better understanding on how strings work in Zig. So let’s discuss this specific aspect of Zig.\nIn summary, there are two types of string values that you care about in Zig, which are:\n\nString literal values.\nString objects.\n\nA string literal value is just a pointer to a null-terminated array of bytes (i.e., similar to a C string). But in Zig, a string literal value also embeds the length of the string into the data type of the value itself. Therefore, a string literal value have a data type in the format *const [n:0]u8. The n in the data type indicates the size of the string.\nOn the other hand, a string object in Zig is basically a slice to an arbitrary sequence of bytes, or, in other words, a slice of u8 values (slices were presented in Section 1.6). Thus, a string object have a data type of []u8 or []const u8, depending if the string object is marked as constant with const, or as variable with var.\nBecause a string object is essentially a slice, it means that a string object always contains two things: a pointer to an array of bytes (i.e., u8 values) that represents the string value; and also, a length value, which specifies the size of the slice, or, how many elements there is in the slice. It’s worth to emphasize that the array of bytes in a string object is not null-terminated, like in a string literal value.\n\n// This is a string literal value:\n\"A literal value\";\n// This is a string object:\nconst object: []const u8 = \"A string object\";\n\nZig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every sequence of bytes you’re working with, but is not really Zig’s job to fix the encoding of your strings (you can use iconv22 for that). Today, most of the text in our modern world, especially on the web, should be UTF-8 encoded. So if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\nLet’s take for example the word “Hello”. In UTF-8, this sequence of characters (H, e, l, l, o) is represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this sequence is 0x48, 0x65, 0x6C, 0x6C, 0x6F. So if I take this sequence of hexadecimal values, and ask Zig to print this sequence of bytes as a sequence of characters (i.e., a string), then, the text “Hello” will be printed into the terminal:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n\nHello\n\n\nIf you want to see the actual bytes that represents a string in Zig, you can use a for loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal value to the terminal. You do that by using a print() statement with the X formatting specifier, like you would normally do with the printf() function23 in C.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n\n\n\n1.8.1 Strings in C\nAt first glance, a string literal value in Zig looks very similar to how C treats strings as well. In more details, string values in C are treated internally as an array of arbitrary bytes, and this array is also null-terminated.\nBut one key difference between a Zig string literal and a C string, is that Zig also stores the length of the string inside the object itself. In the case of a string literal value, this length is stored in the data type of the value (i.e., the n variable in [n:0]u8). While, in a string object, the length is stored in the len attribute of the slice that represents the string object. This small detail makes your code safer, because it’s much easier for the Zig compiler to check if you are trying to access an element that is “out of bounds”, i.e., if your trying to access memory that does not belong to you.\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless. So getting this kind of safety is not automatic and much harder to do in C. For example, if you want to track the length of your string throughout your program in C, then, you first need to loop through the array of bytes that represents this string, and find the null element ('\\0') position to discover where exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\nTo do that, you would need something like this in C. In this example, the C string stored in the object array is 25 bytes long:\n\n#include &lt;stdio.h&gt;\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n\nNumber of elements in the array: 25\nYou don’t have this kind of work in Zig. Because the length of the string is always present and accessible. In a string object for example, you can easily access the length of the string through the len attribute. As an example, the string_object object below is 43 bytes long:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n\n43\n\n\n\n\n1.8.2 A better look at the object type\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the @TypeOf() function. If we look at the type of the simple_array object below, you will find that this object is an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type i32 in Zig. That is what an object of type [4]i32 is.\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a constant pointer (hence the *const annotation) to an array of 16 elements (or 16 bytes). Each element is a single byte (more precisely, an unsigned 8 bit integer - u8), that is why we have the [16:0]u8 portion of the type below. In other words, the string literal value exposed below is 16 bytes long.\nNow, if we create an pointer to the simple_array object, then, we get a constant pointer to an array of 4 elements (*const [4]i32), which is very similar to the type of the string literal value. This demonstrates that a string literal value in Zig is already a pointer to a null-terminated array of bytes.\nFurthermore, if we take a look at the type of the string_obj object, you will see that it’s a slice object (hence the [] portion of the type) to a sequence of constant u8 values (hence the const u8 portion of the type).\n\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n\nType 1: [4]i32Type 2: *const [16:0]u8Type 3: *cons\n  st [4]i32Type 4: []const u8\n\n\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n\n\n1.8.3 Byte vs unicode points\nIt’s important to point out that each byte in the array is not necessarily a single character. This fact arises from the difference between a single byte and a single unicode point.\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in the string. For example, the character “H” is stored in UTF-8 as the decimal number 72. This means that the number 72 is the unicode point for the character “H”. Each possible character that can appear in a UTF-8 encoded string have its own unicode point.\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point) 570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which is 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why, the unicode point 570 is actually stored inside the computer’s memory as the bytes C8 BA.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n\nBytes that represents the string object: C8 BA \n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together to represent the number 570. That is why the relationship between bytes and unicode points is not always 1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds to a single unicode point.\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the bytes that represents that string, and not through the characters of that string. In the Ⱥ example above, the for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a consequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because the number of bytes will be equal to the number of characters in that string. In other words, in this specific situation, the relationship between bytes and unicode points is 1 to 1.\nBut on the other side, if your string contains other types of letters… for example, you might be working with text data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent your UTF-8 string will likely be much higher than the number of characters in that string.\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the std.unicode.Utf8View struct to create an iterator that iterates through the unicode points of your string.\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in this string is represented by three bytes. But the for loop iterates four times, one iteration for each character/unicode point in this string:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n\n\n1.8.4 Some useful functions for strings\nIn this section, I just want to quickly describe some functions from the Zig Standard Library that are very useful to use when working with strings. Most notably:\n\nstd.mem.eql(): to compare if two strings are equal.\nstd.mem.splitScalar(): to split a string into an array of substrings given a delimiter value.\nstd.mem.splitSequence(): to split a string into an array of substrings given a substring delimiter.\nstd.mem.startsWith(): to check if string starts with substring.\nstd.mem.endsWith(): to check if string ends with substring.\nstd.mem.trim(): to remove specific values from both start and end of the string.\nstd.mem.concat(): to concatenate strings together.\nstd.mem.count(): to count the occurrences of substring in the string.\nstd.mem.replace(): to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the mem module of the Zig Standard Library. This module contains multiple functions and methods that are useful to work with memory and sequences of bytes in general.\nThe eql() function is used to check if two arrays of data are equal or not. Since strings are just arbitrary arrays of bytes, we can use this function to compare two strings together. This function returns a boolean value indicating if the two strings are equal or not. The first argument of this function is the data type of the elements of the arrays that are being compared.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n\ntrue\n\n\nThe splitScalar() and splitSequence() functions are useful to split a string into multiple fragments, like the split() method from Python strings. The difference between these two methods is that the splitScalar() uses a single character as the separator to split the string, while splitSequence() uses a sequence of characters (a.k.a. a substring) as the separator. There is a practical example of these functions later in the book.\nThe startsWith() and endsWith() functions are pretty straightforward. They return a boolean value indicating if the string (or, more precisely, if the array of data) begins (startsWith) or ends (endsWith) with the sequence provided.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n\ntrue\n\n\nThe concat() function, as the name suggests, concatenate two or more strings together. Because the process of concatenating the strings involves allocating enough space to accomodate all the strings together, this concat() function receives an allocator object as input.\n\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n\nAs you can imagine, the replace() function is used to replace substrings in a string by another substring. This function works very similarly to the replace() method from Python strings. Therefore, you provide a substring to search, and every time that the replace() function finds this substring within the input string, it replaces this substring with the “replacement substring” that you provided as input.\nIn the example below, we are taking the input string “Hello”, and replacing all occurrences of the substring “el” inside this input string with “34”, and saving the results inside the buffer object. As result, the replace() function returns an usize value that indicates how many replacements were performed.\n\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n\nNew string: H34lo\nN of replacements: 1",
+    "text": "1.8 How strings work in Zig?\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (Chapter 4). But in order for us to build such a thing, we need to get a better understanding on how strings work in Zig. So let’s discuss this specific aspect of Zig.\nStrings in Zig work very similarly to strings in C, but they come with some extra caveats which adds more safety and efficiency to them. You could also say that Zig simply uses a more modern and safe approach to manage and use strings.\nA string in Zig is essentially an array of arbitrary bytes, or, more specifically, an array of u8 values. This very similar to a string in C, which is also interpreted as an array of arbitrary bytes, or, in the case of C, an array of char (which usually represents an unsigned 8-bit integer value in most systems) values.\nNow, because a string in Zig is an array, you automatically get the length of the string (i.e. the length of the array) embedded in the value itself. This makes all the difference! Because now, the Zig compiler can use the length value that is embedded in the string to check for “buffer overflow” or “wrong memory access” problems in your code.\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless. So getting this kind of safety is not automatic and much harder to do in C. For example, if you want to track the length of your string throughout your program in C, then, you first need to loop through the array of bytes that represents this string, and find the null element ('\\0') position to discover where exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\nTo do that, you would need to do something like this in C. In this example, the C string stored in the object array is 25 bytes long:\n\n#include &lt;stdio.h&gt;\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n\nNumber of elements in the array: 25\nYou don’t have this kind of work in Zig. Because the length of the string is always present and accessible in the string value itself. You can easily access the length of the string through the len attribute. As an example, the string_object object below is 43 bytes long:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n\n43\n\n\nAnother point is that Zig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every sequence of bytes you’re working with, but is not really Zig’s job to fix the encoding of your strings (you can use iconv22 for that). Today, most of the text in our modern world, especially on the web, should be UTF-8 encoded. So if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\nLet’s take for example the word “Hello”. In UTF-8, this sequence of characters (H, e, l, l, o) is represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this sequence is 0x48, 0x65, 0x6C, 0x6C, 0x6F. So if I take this sequence of hexadecimal values, and ask Zig to print this sequence of bytes as a sequence of characters (i.e., a string), then, the text “Hello” will be printed into the terminal:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n\nHello\n\n\n\n1.8.1 Using a slice versus a sentinel-terminated array\nIn memory, all string values in Zig are always stored in the same way. They are simply stored as sequences/arrays of arbitrary bytes. But you can use and access this sequence of bytes in two different ways. You can access this sequence of bytes as:\n\na sentinel-terminated array of u8 values.\nor as a slice of u8 values.\n\n\n1.8.1.1 Sentinel-terminated arrays\nSentinel-terminated arrays in Zig are described in the Language Reference of Zig23. In summary a sentinel-terminated array is just a normal array, but, the difference is that they contain a “sentinel value” at the last index/element of the array. With a sentinel-terminated array you embed both the length of the array, and also, the sentinel value in the type itself of your object.\nFor example, if you write a string literal value in your code, and ask Zig to print the data type of this value, you usually get a data type in the format *const [n:0]u8. The n in the data type indicates the size of the string (that is the length of the array). The zero after the n: part of the data type is the sentinel value itself.\n\n// This is a string literal value:\n_ = \"A literal value\";\ntry stdout.print(\"{any}\\n\", .{@TypeOf(\"A literal value\")});\n\n*const [15:0]u8\n\n\nSo, with this data type *const [n:0]u8 you are essentially saying that you have an array of u8 values of length n, where, the element at the index corresponding to the length n in the array is the number zero. If you really think about this description, you will notice that this is just a fancy way to describe a string in C, which is a null-terminated array of bytes. The NULL value in C is the number zero. So, an array that ends in a null/zero value in C is essentially a sentinel-terminated array in Zig, where the sentinel value of the array is the number zero.\nTherefore, a string literal value in Zig is just a pointer to a null-terminated array of bytes (i.e., similar to a C string). But in Zig, a string literal value also embeds the length of the string, and also, the fact that they are “NULL terminated”, into the data type of the value itself.\n\n\n1.8.1.2 Slice\nYou can also access and use the arbitrary sequence of bytes that represent your string as a slice of u8 values. The majority of functions from the Zig standard library usually receive strings as inputs as slices of u8 values (slices were presented in Section 1.6).\nThus, you will see a lot of string values with a data type of []u8 or []const u8, depending if the object where this string is stored is marked as constant with const, or as variable with var. Now, because the string in this case is being interpreted as a slice, this slice is not necessarilly null-terminated, because now, the sentinel value is not mandatory. You can include the null/zero value in the slice if you want to, but there is no need to do it.\n\n// This is a string value being\n// interpreted as a slice.\nconst str: []const u8 = \"A string value\";\ntry stdout.print(\"{any}\\n\", .{@TypeOf(str)});\n\n[]const u8\n\n\n\n\n\n1.8.2 Iterating through the string\nIf you want to see the actual bytes that represents a string in Zig, you can use a for loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal value to the terminal. You do that by using a print() statement with the X formatting specifier, like you would normally do with the printf() function24 in C.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n\n\n\n\n1.8.3 A better look at the object type\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the @TypeOf() function. If we look at the type of the simple_array object below, you will find that this object is an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type i32 in Zig. That is what an object of type [4]i32 is.\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a constant pointer (hence the *const annotation) to an array of 16 elements (or 16 bytes). Each element is a single byte (more precisely, an unsigned 8 bit integer - u8), that is why we have the [16:0]u8 portion of the type below, and also, you can see that this is a null-terminated array, because of the zero value after the : character in the data type. In other words, the string literal value exposed below is 16 bytes long.\nNow, if we create an pointer to the simple_array object, then, we get a constant pointer to an array of 4 elements (*const [4]i32), which is very similar to the type of the string literal value. This demonstrates that a string literal value in Zig is already a pointer to a null-terminated array of bytes.\nFurthermore, if we take a look at the type of the string_obj object, you will see that it’s a slice object (hence the [] portion of the type) to a sequence of constant u8 values (hence the const u8 portion of the type).\n\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n\n\n1.8.4 Byte vs unicode points\nIt’s important to point out that each byte in the array is not necessarily a single character. This fact arises from the difference between a single byte and a single unicode point.\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in the string. For example, the character “H” is stored in UTF-8 as the decimal number 72. This means that the number 72 is the unicode point for the character “H”. Each possible character that can appear in a UTF-8 encoded string have its own unicode point.\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point) 570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which is 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why, the unicode point 570 is actually stored inside the computer’s memory as the bytes C8 BA.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n\nBytes that represents the string object: C8 BA \n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together to represent the number 570. That is why the relationship between bytes and unicode points is not always 1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds to a single unicode point.\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the bytes that represents that string, and not through the characters of that string. In the Ⱥ example above, the for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a consequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because the number of bytes will be equal to the number of characters in that string. In other words, in this specific situation, the relationship between bytes and unicode points is 1 to 1.\nBut on the other side, if your string contains other types of letters… for example, you might be working with text data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent your UTF-8 string will likely be much higher than the number of characters in that string.\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the std.unicode.Utf8View struct to create an iterator that iterates through the unicode points of your string.\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in this string is represented by three bytes. But the for loop iterates four times, one iteration for each character/unicode point in this string:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n\n\n1.8.5 Some useful functions for strings\nIn this section, I just want to quickly describe some functions from the Zig Standard Library that are very useful to use when working with strings. Most notably:\n\nstd.mem.eql(): to compare if two strings are equal.\nstd.mem.splitScalar(): to split a string into an array of substrings given a delimiter value.\nstd.mem.splitSequence(): to split a string into an array of substrings given a substring delimiter.\nstd.mem.startsWith(): to check if string starts with substring.\nstd.mem.endsWith(): to check if string ends with substring.\nstd.mem.trim(): to remove specific values from both start and end of the string.\nstd.mem.concat(): to concatenate strings together.\nstd.mem.count(): to count the occurrences of substring in the string.\nstd.mem.replace(): to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the mem module of the Zig Standard Library. This module contains multiple functions and methods that are useful to work with memory and sequences of bytes in general.\nThe eql() function is used to check if two arrays of data are equal or not. Since strings are just arbitrary arrays of bytes, we can use this function to compare two strings together. This function returns a boolean value indicating if the two strings are equal or not. The first argument of this function is the data type of the elements of the arrays that are being compared.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n\ntrue\n\n\nThe splitScalar() and splitSequence() functions are useful to split a string into multiple fragments, like the split() method from Python strings. The difference between these two methods is that the splitScalar() uses a single character as the separator to split the string, while splitSequence() uses a sequence of characters (a.k.a. a substring) as the separator. There is a practical example of these functions later in the book.\nThe startsWith() and endsWith() functions are pretty straightforward. They return a boolean value indicating if the string (or, more precisely, if the array of data) begins (startsWith) or ends (endsWith) with the sequence provided.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n\ntrue\n\n\nThe concat() function, as the name suggests, concatenate two or more strings together. Because the process of concatenating the strings involves allocating enough space to accomodate all the strings together, this concat() function receives an allocator object as input.\n\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n\nAs you can imagine, the replace() function is used to replace substrings in a string by another substring. This function works very similarly to the replace() method from Python strings. Therefore, you provide a substring to search, and every time that the replace() function finds this substring within the input string, it replaces this substring with the “replacement substring” that you provided as input.\nIn the example below, we are taking the input string “Hello”, and replacing all occurrences of the substring “el” inside this input string with “34”, and saving the results inside the buffer object. As result, the replace() function returns an usize value that indicates how many replacements were performed.\n\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n\nNew string: H34lo\nN of replacements: 1",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -194,7 +194,7 @@
     "href": "Chapters/01-zig-weird.html#safety-in-zig",
     "title": "1  Introducing Zig",
     "section": "1.9 Safety in Zig",
-    "text": "1.9 Safety in Zig\nA general trend in modern low-level programming languages is safety. As our modern world becomes more interconnected with technology and computers, the data produced by all of this technology becomes one of the most important (and also, one of the most dangerous) assets that we have.\nThis is probably the main reason why modern low-level programming languages have been giving great attention to safety, especially memory safety, because memory corruption is still the main target for hackers to exploit. The reality is that we don’t have an easy solution for this problem. For now, we only have techniques and strategies that mitigates these problems.\nAs Richard Feldman explains on his most recent GOTO conference talk24 , we haven’t figured it out yet a way to achieve true safety in technology. In other words, we haven’t found a way to build software that won’t be exploited with 100% certainty. We can greatly reduce the risks of our software being exploited, by ensuring memory safety for example. But this is not enough to achieve “true safety” territory.\nBecause even if you write your program in a “safe language”, hackers can still exploit failures in the operating system where your program is running (e.g. maybe the system where your code is running has a “backdoor exploit” that can still affect your code in unexpected ways), or also, they can exploit the features from the architecture of your computer. A recently found exploit that involves memory invalidation through a feature of “memory tags” present in ARM chips is an example of that (Kim et al. 2024).\nThe question is: what have Zig and other languages been doing to mitigate this problem? If we take Rust as an example, Rust is, for the most part25, a memory safe language by enforcing specific rules to the developer. In other words, the key feature of Rust, the borrow checker, forces you to follow a specific logic when you are writing your Rust code, and the Rust compiler will always complain everytime you try to go out of this pattern.\nIn contrast, the Zig language is not a memory safe language by default. There are some memory safety features that you get for free in Zig, especially in arrays and pointer objects. But there are other tools offered by the language, that are not used by default. In other words, the zig compiler does not obligate you to use such tools.\nThe tools listed below are related to memory safety. That is, they help you to achieve memory safety in your Zig code:\n\ndefer allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, “use after free”, and also “double-free” problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\nerrdefer helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\npointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\nZig offers some native types of allocators (called “testing allocators”) that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\narrays and slices in Zig have their lengths embedded in the object itself, which makes the zig compiler very effective on detecting “index out-of-range” type of errors, and avoiding buffer overflows.\n\nDespite these features that Zig offers that are related to memory safety issues, the language also has some rules that help you to achieve another type of safety, which is more related to program logic safety. These rules are:\n\npointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\nswitch statements must exaust all possible options.\nthe zig compiler forces you to handle every possible error in your program.",
+    "text": "1.9 Safety in Zig\nA general trend in modern low-level programming languages is safety. As our modern world becomes more interconnected with technology and computers, the data produced by all of this technology becomes one of the most important (and also, one of the most dangerous) assets that we have.\nThis is probably the main reason why modern low-level programming languages have been giving great attention to safety, especially memory safety, because memory corruption is still the main target for hackers to exploit. The reality is that we don’t have an easy solution for this problem. For now, we only have techniques and strategies that mitigates these problems.\nAs Richard Feldman explains on his most recent GOTO conference talk25 , we haven’t figured it out yet a way to achieve true safety in technology. In other words, we haven’t found a way to build software that won’t be exploited with 100% certainty. We can greatly reduce the risks of our software being exploited, by ensuring memory safety for example. But this is not enough to achieve “true safety” territory.\nBecause even if you write your program in a “safe language”, hackers can still exploit failures in the operating system where your program is running (e.g. maybe the system where your code is running has a “backdoor exploit” that can still affect your code in unexpected ways), or also, they can exploit the features from the architecture of your computer. A recently found exploit that involves memory invalidation through a feature of “memory tags” present in ARM chips is an example of that (Kim et al. 2024).\nThe question is: what have Zig and other languages been doing to mitigate this problem? If we take Rust as an example, Rust is, for the most part26, a memory safe language by enforcing specific rules to the developer. In other words, the key feature of Rust, the borrow checker, forces you to follow a specific logic when you are writing your Rust code, and the Rust compiler will always complain everytime you try to go out of this pattern.\nIn contrast, the Zig language is not a memory safe language by default. There are some memory safety features that you get for free in Zig, especially in arrays and pointer objects. But there are other tools offered by the language, that are not used by default. In other words, the zig compiler does not obligate you to use such tools.\nThe tools listed below are related to memory safety. That is, they help you to achieve memory safety in your Zig code:\n\ndefer allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, “use after free”, and also “double-free” problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\nerrdefer helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\npointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\nZig offers some native types of allocators (called “testing allocators”) that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\narrays and slices in Zig have their lengths embedded in the object itself, which makes the zig compiler very effective on detecting “index out-of-range” type of errors, and avoiding buffer overflows.\n\nDespite these features that Zig offers that are related to memory safety issues, the language also has some rules that help you to achieve another type of safety, which is more related to program logic safety. These rules are:\n\npointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\nswitch statements must exaust all possible options.\nthe zig compiler forces you to handle every possible error in your program.",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -214,7 +214,7 @@
     "href": "Chapters/01-zig-weird.html#footnotes",
     "title": "1  Introducing Zig",
     "section": "",
-    "text": "https://ziglang.org/learn/overview/#zig-build-system.↩︎\nhttps://zig.news/edyu/zig-package-manager-wtf-is-zon-558e↩︎\nhttps://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1↩︎\nhttps://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md↩︎\nhttps://en.wikipedia.org/wiki/List_of_C-family_programming_languages↩︎\nYou can see an example of a main() function that returns an u8 value in the return-integer.zig file, https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig↩︎\nhttps://github.com/ziglang/zig/issues/17186↩︎\nhttps://github.com/ziglang/zig/issues/19864↩︎\nhttps://github.com/ziglang/zig/tree/master/lib/std↩︎\nhttps://github.com/oven-sh/bun.↩︎\nhttps://github.com/hexops/mach↩︎\nhttps://github.com/cgbur/llama2.zig/tree/main↩︎\nhttps://github.com/tigerbeetle/tigerbeetle↩︎\nhttps://github.com/Hejsil/zig-clap↩︎\nhttps://github.com/capy-ui/capy↩︎\nhttps://github.com/zigtools/zls↩︎\nhttps://github.com/mitchellh/libxev↩︎\nhttps://ziglings.org.↩︎\nhttps://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen.↩︎\nhttps://adventofcode.com/↩︎\nhttps://ziglang.org/documentation/master/#Primitive-Types.↩︎\nhttps://www.gnu.org/software/libiconv/↩︎\nhttps://cplusplus.com/reference/cstdio/printf/↩︎\nhttps://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences↩︎\nActually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (foreign function interface), which disables the borrow-checker features through the unsafe keyword.↩︎",
+    "text": "https://ziglang.org/learn/overview/#zig-build-system.↩︎\nhttps://zig.news/edyu/zig-package-manager-wtf-is-zon-558e↩︎\nhttps://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1↩︎\nhttps://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md↩︎\nhttps://en.wikipedia.org/wiki/List_of_C-family_programming_languages↩︎\nYou can see an example of a main() function that returns an u8 value in the return-integer.zig file, https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig↩︎\nhttps://github.com/ziglang/zig/issues/17186↩︎\nhttps://github.com/ziglang/zig/issues/19864↩︎\nhttps://github.com/ziglang/zig/tree/master/lib/std↩︎\nhttps://github.com/oven-sh/bun.↩︎\nhttps://github.com/hexops/mach↩︎\nhttps://github.com/cgbur/llama2.zig/tree/main↩︎\nhttps://github.com/tigerbeetle/tigerbeetle↩︎\nhttps://github.com/Hejsil/zig-clap↩︎\nhttps://github.com/capy-ui/capy↩︎\nhttps://github.com/zigtools/zls↩︎\nhttps://github.com/mitchellh/libxev↩︎\nhttps://ziglings.org.↩︎\nhttps://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen.↩︎\nhttps://adventofcode.com/↩︎\nhttps://ziglang.org/documentation/master/#Primitive-Types.↩︎\nhttps://www.gnu.org/software/libiconv/↩︎\nhttps://ziglang.org/documentation/master/#Sentinel-Terminated-Arrays.↩︎\nhttps://cplusplus.com/reference/cstdio/printf/↩︎\nhttps://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences↩︎\nActually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (foreign function interface), which disables the borrow-checker features through the unsafe keyword.↩︎",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -604,7 +604,7 @@
     "href": "Chapters/04-http-server.html#implementing-the-server---part-2",
     "title": "7  Project 2 - Building a HTTP Server from scratch",
     "section": "7.7 Implementing the server - Part 2",
-    "text": "7.7 Implementing the server - Part 2\nNow, on this section, I want to focus on parsing the HTTP Request that we received from the client. However, to effectively parse a HTTP Request message, we first need to understand its structure. In summary, a HTTP Request is a text message that is divided into 3 different sections (or parts):\n\nThe top-level header indicating the method of the HTTP Request, the URI, and the HTTP version used in the message.\nA list of HTTP Headers.\nThe body of the HTTP Request.\n\n\n7.7.1 The top-level header\nThe first line of text in a HTTP Request always come with the three most essential information about the request. These three key attributes of the HTTP Request are separated by a simple space in this first line of the request. The first information is the HTTP method that is being used in the request, second, we have the URI to which this HTTP Request is being sent to, and third, we have the version of the HTTP protocol that is being used in this HTTP Request.\nIn the snippet below, you can find an example of this first line in a HTTP Request. First, we have the HTTP method of this request (GET). Many programmers refer to the URI component (/users/list) as the “API endpoint” to which the HTTP Request is being sent to. In the context of this specific request, since it’s a GET request, you could also say that the URI component is the path to the resource we want to access, or, the path to the document (or the file) that we want to retrieve from the server.\nGET /users/list HTTP/1.1\nAlso, notice that this HTTP Request is using the version 1.1 of the HTTP protocol, which is the most popular version of the protocol used in the web.\n\n\n7.7.2 The list of HTTP headers\nMost HTTP Requests also include a section of HTTP Headers, which is just a list of attributes or key-value pairs associated with this particular request. This section always comes right after the “top-level header” of the request.\nFor our purpose in this chapter, which is to build a simple HTTP Server, we are going to ignore this section of the HTTP Request, for simplicity. But most HTTP servers that exist in the wild parses and use these HTTP headers to change the way that the server responds to the request sent by the client.\nFor example, many requests we encounter in the real-world comes with a HTTP header called Accept. In this header, we find a list of MIME types3. This list indicates the file formats that the client can read, or parse, or interpret. In other words, you also interpret this header as the client saying the following phrase to the server: “Hey! Look, I can read only HTML documents, so please, send me back a document that is in a HTML format.”.\nIf the HTTP server can read and use this Accept header, then, the server can identify which is the best file format for the document to be sent to the client. Maybe the HTTP server have the same document in multiple formats, for example, in JSON, in XML, in HTML and in PDF, but the client can only understand documents in the HTML format. That is the purpose of this Accept header.\n\n\n7.7.3 The body\nThe body comes after the list of HTTP headers, and it’s an optional section of the HTTP Request, meaning that, not all HTTP Requests will come with a body in them. For example, every HTTP Request that uses the GET method usually does not come with a body.\nBecause a GET request is used to request data, instead of sending it to the server. So, the body section is more related to the POST method, which is a method that involves sending data to the server, to be processed and stored.\nSince we are going to support only the GET method in this project, it means that we also do not need to care about the body of the request.\n\n\n7.7.4 Creating the HTTP Method enum\nEvery HTTP Request comes with a explicit method. The method used in a HTTP Request is identified by one these words:\n\nGET;\nPOST;\nOPTIONS;\nPATCH;\nDELETE;\nand some other methods.\n\nEach HTTP method is used for a specific type of task. The POST method for example is normally used to post some data into the destination. In other words, it’s used to send some data to the HTTP server, so that it can be processed and stored by the server.\nAs another example, the GET method is normally used to get content from the server. In other words, we use this method whenever we want the server to send some content back to us. It can be any type of content. It can be a web page, a document file, or some data in a JSON format.\nWhen a client sends a POST HTTP Request, the HTTP Response sent by the server normally have the sole purpose of letting the client know if the server processed and stored the data successfully. In contrast, when the server receives a GET HTTP Request, then, the server sends the content that the client asked for in the HTTP Response itself. This demonstrates that the method associated with the HTTP Request changes a lot on the dynamics and the roles that each party plays in the whole process.\nSince the HTTP method of the HTTP Request is identified by this very small and specific set of words, it would be interesting to create an enum structure to represent a HTTP method. This way, we can easily check if the HTTP Request we receive from the client is a HTTP method that we currently support in our small HTTP server project.\nThe Method structure below represents this enumeration. Notice that, for now, only the GET HTTP method is included in this enumeration. Because, for the purpose of this chapter, I want to implement only the GET HTTP method. That is why I am not including the other HTTP methods in this enumeration.\n\npub const Method = enum {\n    GET\n};\n\nNow, I think we should add two methods to this enum structure. One method is is_supported(), which will be a function that returns a boolean value, indicating if the input HTTP method is supported or not by our HTTP Server. The other is init(), which is a constructor function that takes a string as input, and tries to convert it into a Method value.\nBut in order to build these functions, I will use a functionality from the Zig Standard Library, called StaticStringMap(). This function allows us to create a simple map from strings to enum values. In other words, we can use this map structure to map a string to the respective enum value. To some extent, this specific structure from the standard library works almost like a “hashtable” structure, and it’s optimized for small sets of words, or, small sets of keys, which is our case here. We are going to talk more about hashtables in Zig in Section 11.2.\nTo use this “static string map” structure, you have to import it from the std.static_string_map module of the Zig Standard Library. Just to make things shorter and easier to type, I am going to import this function through a different and shorter name (Map).\nWith Map() imported, we can just apply this function over the enum structure that we are going to use in the resulting map. In our case here, it’s the Method enum structure that we declared at the last code example. Then, I call the initComptime() method with the map, i.e., the list of key-value pairs that we are going to use.\nYou can see in the example below that I wrote this map using multiple anonymous struct literals. Inside the first (or “top-level”) struct literal, we have a list (or a sequence) of struct literals. Each struct literal in this list represents a separate key-value pair. The first element (or the key) in each key-value pair should always be a string value. While the second element should be a value from the enum structure that you have used inside the Map() function.\n\nconst Map = std.static_string_map.StaticStringMap;\nconst MethodMap = Map(Method).initComptime(.{\n    .{ \"GET\", Method.GET },\n});\n\nTherefore, the MethodMap object is basically a std::map object from C++, or, a dict object from Python. You can retrieve (or get) the enum value that corresponds to a particular key, by using the get() method from the map object. This method returns an optional value, so, the get() method might result in a null value.\nWe can use this in our advantage to detect if a particular HTTP method is supported or not in our HTTP server. Because, if the get() method returns null, it means that it did not found the method that we provided inside the MethodMap object, and, as a consequence, this method is not supported by our HTTP server.\nThe init() method below, takes a string value as input, and then, it simply passes this string value to the get() method of our MethodMap object. As consequence, we should get the enum value that corresponds to this input string.\nNotice in the example below that, the init() method returns either an error (which might happen if the ? method returns unreacheable, checkout Section 6.4.3 for more details) or a Method object as result. Since GET is currently the only value in our Method enum structure, it means that, the init() method will most likely return the value Method.GET as result.\nAlso notice that, in the is_supported() method, we are using the optional value returned by the get() method from our MethodMap object. The if statement unwraps the optional value returned by this method, and returns true in case this optional value is a not-null value. Otherwise, it simply returns false.\n\npub const Method = enum {\n    GET,\n    pub fn init(text: []const u8) !Method {\n        return MethodMap.get(text).?;\n    }\n    pub fn is_supported(m: []const u8) bool {\n        const method = MethodMap.get(m);\n        if (method) |_| {\n            return true;\n        }\n        return false;\n    }\n};\n\n\n\n7.7.5 Writing the parse request function\nNow that we created the enum that represents our HTTP method, we should start to write the function responsible for actually parsing the HTTP Request.\nThe first thing we can do, is to write a struct to represent the HTTP Request. Take the Request struct below as an example. It contains the three essential information from the “top-level” header (i.e., the first line) in the HTTP Request.\n\nconst Request = struct {\n    method: Method,\n    version: []const u8,\n    uri: []const u8,\n    pub fn init(method: Method,\n                uri: []const u8,\n                version: []const u8) Request {\n        return Request{\n            .method = method,\n            .uri = uri,\n            .version = version,\n        };\n    }\n};\n\nThe parse_request() function should receive a string as input. This input string contains the entire HTTP Request message, and the parsing function should read and understand the individual parts of this message.\nNow, remember that for the purpose of this chapter, we care only about the first line in this message, which contains the “top-level header”, or, the three essential attributes about the HTTP Request, which are the HTTP method used, the URI and the HTTP version.\nNotice that I use the function indexOfScalar() in parse_request(). This function from the Zig Standard Library returns the first index where the scalar value that we provide happens in a string. In this case, I’m looking at the first occurrence of the new line character (\\n). Because once again, we care only about the first line in the HTTP Request message. This is the line where we have the three information that we want to parse (version of HTTP, the HTTP method and the URI).\nTherefore, we are using this indexOfScalar() function to limit our parsing process to the first line in the message. It’s also worth mentioning that, the indexOfScalar() function returns an optional value. That is why I use the orelse keyword to provide an alternative value, in case the value returned by the function is a null value.\nSince each of these three attributes are separated by a simple space, we could use the function splitScalar() from the Zig Standard Library to split the input string into sections by looking for every position that appears a simple space. In other words, this splitScalar() function is equivalent to the split() method in Python, or, the std::getline() function from C++, or the strtok() function in C.\nWhen you use this splitScalar() function, you get an iterator as the result. This iterator have a next() method that you can use to advance the iterator to the next position, or, to the next section of the splitted string. Note that, when you use next(), the method not only advances the iterator, but it also returns a slice to the current section of the splitted string as result.\nNow, if you want to get a slice to the current section of the splitted string, but not advance the iterator to the next position, you can use the peek() method. Both next() and peek() methods return an optional value, that is why I use the ? method to unwrap these optional values.\n\npub fn parse_request(text: []u8) Request {\n    const line_index = std.mem.indexOfScalar(\n        u8, text, '\\n'\n    ) orelse text.len;\n    var iterator = std.mem.splitScalar(\n        u8, text[0..line_index], ' '\n    );\n    const method = try Method.init(iterator.next().?);\n    const uri = iterator.next().?;\n    const version = iterator.next().?;\n    const request = Request.init(method, uri, version);\n    return request;\n}\n\nAs I described in Section 1.8, strings in Zig are simply arrays of bytes in the language. So, you will find lots of excellent utility functions to work directly with strings inside this mem module from the Zig Standard Library. We have described some of these useful utility functions already in Section 1.8.4.\n\n\n7.7.6 Using the parse request function\nNow that we wrote the function responsible for parsing the HTTP Request, we can add the function call to parse_request() in the main() function of our program.\nAfter that, is a good idea to test once again the state of our program. I execute this program again with the run command from the zig compiler, then, I use my web browser to connect once again to the server through the URL localhost:3490, and finally, the end result of our Request object is printed to the console.\nA quick observation, since I have used the any format specifier in the print statement, the data members version and uri of the Request struct were printed as raw integer values. String data being printed as integer values is common in Zig, and remember, these integer values are just the decimal representation of the bytes that form the string in question.\nIn the result below, the sequence of decimal values 72, 84, 84, 80, 47, 49, 46, 49, and 13, are the bytes that form the text “HTTP/1.1”. And the integer 47, is the decimal value of the character /, which represents our URI in this request.\n\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    try Request.read_request(\n        connection, buffer[0..buffer.len]\n    );\n    const request = Request.parse_request(\n        buffer[0..buffer.len]\n    );\n    try stdout.print(\"{any}\\n\", .{request});\n}\n\nrequest.Request{\n    .method = request.Method.GET,\n    .version = {72, 84, 84, 80, 47, 49, 46, 49, 13},\n    .uri = {47}\n}\n\n\n7.7.7 Sending the HTTP Response to the client\nIn this last part, we are going to write the logic responsible for sending the HTTP Response from the server to the client. To make things simple, the server in this project will send just a simple web page containing the text “Hello world”.\nFirst, I create a new Zig module in the project, named response.zig. In this module, I will declare just two functions. Each function corresponds to a specific status code in the HTTP Response. The send_200() function will send a HTTP Response with status code 200 (which means “Success”) to the client. While the send_404() function sends a response with status code 404 (which means “Not found”).\nThis is definitely not the most ergonomic and adequate way of handling the HTTP Response, but it works for our case here. We are just building toy projects in this book after all, therefore, the source code that we write do not need to be perfect. It just needs to work!\n\nconst std = @import(\"std\");\nconst Connection = std.net.Server.Connection;\npub fn send_200(conn: Connection) !void {\n    const message = (\n        \"HTTP/1.1 200 OK\\nContent-Length: 48\"\n        ++ \"\\nContent-Type: text/html\\n\"\n        ++ \"Connection: Closed\\n\\n&lt;html&gt;&lt;body&gt;\"\n        ++ \"&lt;h1&gt;Hello, World!&lt;/h1&gt;&lt;/body&gt;&lt;/html&gt;\"\n    );\n    _ = try conn.stream.write(message);\n}\n\npub fn send_404(conn: Connection) !void {\n    const message = (\n        \"HTTP/1.1 404 Not Found\\nContent-Length: 50\"\n        ++ \"\\nContent-Type: text/html\\n\"\n        ++ \"Connection: Closed\\n\\n&lt;html&gt;&lt;body&gt;\"\n        ++ \"&lt;h1&gt;File not found!&lt;/h1&gt;&lt;/body&gt;&lt;/html&gt;\"\n    );\n    _ = try conn.stream.write(message);\n}\n\nNotice that both functions receives the connection object as input, and use the write() method to write the HTTP Response message directly into this communication channel. As result, the party in the other side of the connection (i.e., the client), will receive such message.\nMost real-world HTTP Servers will have a single function (or a single struct) to effectively handle the response. It gets the HTTP Request already parsed as input, and then, it tries to build the HTTP Response bit by bit, before the function sends it over the connection.\nWe would also have a specialized struct to represent a HTTP Response, and a lot of methods that would be used to build each part or component of the response object. Take the Response struct created by the Javascript runtime Bun as an example. You can find this struct in the response.zig module4 in their GitHub project.",
+    "text": "7.7 Implementing the server - Part 2\nNow, on this section, I want to focus on parsing the HTTP Request that we received from the client. However, to effectively parse a HTTP Request message, we first need to understand its structure. In summary, a HTTP Request is a text message that is divided into 3 different sections (or parts):\n\nThe top-level header indicating the method of the HTTP Request, the URI, and the HTTP version used in the message.\nA list of HTTP Headers.\nThe body of the HTTP Request.\n\n\n7.7.1 The top-level header\nThe first line of text in a HTTP Request always come with the three most essential information about the request. These three key attributes of the HTTP Request are separated by a simple space in this first line of the request. The first information is the HTTP method that is being used in the request, second, we have the URI to which this HTTP Request is being sent to, and third, we have the version of the HTTP protocol that is being used in this HTTP Request.\nIn the snippet below, you can find an example of this first line in a HTTP Request. First, we have the HTTP method of this request (GET). Many programmers refer to the URI component (/users/list) as the “API endpoint” to which the HTTP Request is being sent to. In the context of this specific request, since it’s a GET request, you could also say that the URI component is the path to the resource we want to access, or, the path to the document (or the file) that we want to retrieve from the server.\nGET /users/list HTTP/1.1\nAlso, notice that this HTTP Request is using the version 1.1 of the HTTP protocol, which is the most popular version of the protocol used in the web.\n\n\n7.7.2 The list of HTTP headers\nMost HTTP Requests also include a section of HTTP Headers, which is just a list of attributes or key-value pairs associated with this particular request. This section always comes right after the “top-level header” of the request.\nFor our purpose in this chapter, which is to build a simple HTTP Server, we are going to ignore this section of the HTTP Request, for simplicity. But most HTTP servers that exist in the wild parses and use these HTTP headers to change the way that the server responds to the request sent by the client.\nFor example, many requests we encounter in the real-world comes with a HTTP header called Accept. In this header, we find a list of MIME types3. This list indicates the file formats that the client can read, or parse, or interpret. In other words, you also interpret this header as the client saying the following phrase to the server: “Hey! Look, I can read only HTML documents, so please, send me back a document that is in a HTML format.”.\nIf the HTTP server can read and use this Accept header, then, the server can identify which is the best file format for the document to be sent to the client. Maybe the HTTP server have the same document in multiple formats, for example, in JSON, in XML, in HTML and in PDF, but the client can only understand documents in the HTML format. That is the purpose of this Accept header.\n\n\n7.7.3 The body\nThe body comes after the list of HTTP headers, and it’s an optional section of the HTTP Request, meaning that, not all HTTP Requests will come with a body in them. For example, every HTTP Request that uses the GET method usually does not come with a body.\nBecause a GET request is used to request data, instead of sending it to the server. So, the body section is more related to the POST method, which is a method that involves sending data to the server, to be processed and stored.\nSince we are going to support only the GET method in this project, it means that we also do not need to care about the body of the request.\n\n\n7.7.4 Creating the HTTP Method enum\nEvery HTTP Request comes with a explicit method. The method used in a HTTP Request is identified by one these words:\n\nGET;\nPOST;\nOPTIONS;\nPATCH;\nDELETE;\nand some other methods.\n\nEach HTTP method is used for a specific type of task. The POST method for example is normally used to post some data into the destination. In other words, it’s used to send some data to the HTTP server, so that it can be processed and stored by the server.\nAs another example, the GET method is normally used to get content from the server. In other words, we use this method whenever we want the server to send some content back to us. It can be any type of content. It can be a web page, a document file, or some data in a JSON format.\nWhen a client sends a POST HTTP Request, the HTTP Response sent by the server normally have the sole purpose of letting the client know if the server processed and stored the data successfully. In contrast, when the server receives a GET HTTP Request, then, the server sends the content that the client asked for in the HTTP Response itself. This demonstrates that the method associated with the HTTP Request changes a lot on the dynamics and the roles that each party plays in the whole process.\nSince the HTTP method of the HTTP Request is identified by this very small and specific set of words, it would be interesting to create an enum structure to represent a HTTP method. This way, we can easily check if the HTTP Request we receive from the client is a HTTP method that we currently support in our small HTTP server project.\nThe Method structure below represents this enumeration. Notice that, for now, only the GET HTTP method is included in this enumeration. Because, for the purpose of this chapter, I want to implement only the GET HTTP method. That is why I am not including the other HTTP methods in this enumeration.\n\npub const Method = enum {\n    GET\n};\n\nNow, I think we should add two methods to this enum structure. One method is is_supported(), which will be a function that returns a boolean value, indicating if the input HTTP method is supported or not by our HTTP Server. The other is init(), which is a constructor function that takes a string as input, and tries to convert it into a Method value.\nBut in order to build these functions, I will use a functionality from the Zig Standard Library, called StaticStringMap(). This function allows us to create a simple map from strings to enum values. In other words, we can use this map structure to map a string to the respective enum value. To some extent, this specific structure from the standard library works almost like a “hashtable” structure, and it’s optimized for small sets of words, or, small sets of keys, which is our case here. We are going to talk more about hashtables in Zig in Section 11.2.\nTo use this “static string map” structure, you have to import it from the std.static_string_map module of the Zig Standard Library. Just to make things shorter and easier to type, I am going to import this function through a different and shorter name (Map).\nWith Map() imported, we can just apply this function over the enum structure that we are going to use in the resulting map. In our case here, it’s the Method enum structure that we declared at the last code example. Then, I call the initComptime() method with the map, i.e., the list of key-value pairs that we are going to use.\nYou can see in the example below that I wrote this map using multiple anonymous struct literals. Inside the first (or “top-level”) struct literal, we have a list (or a sequence) of struct literals. Each struct literal in this list represents a separate key-value pair. The first element (or the key) in each key-value pair should always be a string value. While the second element should be a value from the enum structure that you have used inside the Map() function.\n\nconst Map = std.static_string_map.StaticStringMap;\nconst MethodMap = Map(Method).initComptime(.{\n    .{ \"GET\", Method.GET },\n});\n\nTherefore, the MethodMap object is basically a std::map object from C++, or, a dict object from Python. You can retrieve (or get) the enum value that corresponds to a particular key, by using the get() method from the map object. This method returns an optional value, so, the get() method might result in a null value.\nWe can use this in our advantage to detect if a particular HTTP method is supported or not in our HTTP server. Because, if the get() method returns null, it means that it did not found the method that we provided inside the MethodMap object, and, as a consequence, this method is not supported by our HTTP server.\nThe init() method below, takes a string value as input, and then, it simply passes this string value to the get() method of our MethodMap object. As consequence, we should get the enum value that corresponds to this input string.\nNotice in the example below that, the init() method returns either an error (which might happen if the ? method returns unreacheable, checkout Section 6.4.3 for more details) or a Method object as result. Since GET is currently the only value in our Method enum structure, it means that, the init() method will most likely return the value Method.GET as result.\nAlso notice that, in the is_supported() method, we are using the optional value returned by the get() method from our MethodMap object. The if statement unwraps the optional value returned by this method, and returns true in case this optional value is a not-null value. Otherwise, it simply returns false.\n\npub const Method = enum {\n    GET,\n    pub fn init(text: []const u8) !Method {\n        return MethodMap.get(text).?;\n    }\n    pub fn is_supported(m: []const u8) bool {\n        const method = MethodMap.get(m);\n        if (method) |_| {\n            return true;\n        }\n        return false;\n    }\n};\n\n\n\n7.7.5 Writing the parse request function\nNow that we created the enum that represents our HTTP method, we should start to write the function responsible for actually parsing the HTTP Request.\nThe first thing we can do, is to write a struct to represent the HTTP Request. Take the Request struct below as an example. It contains the three essential information from the “top-level” header (i.e., the first line) in the HTTP Request.\n\nconst Request = struct {\n    method: Method,\n    version: []const u8,\n    uri: []const u8,\n    pub fn init(method: Method,\n                uri: []const u8,\n                version: []const u8) Request {\n        return Request{\n            .method = method,\n            .uri = uri,\n            .version = version,\n        };\n    }\n};\n\nThe parse_request() function should receive a string as input. This input string contains the entire HTTP Request message, and the parsing function should read and understand the individual parts of this message.\nNow, remember that for the purpose of this chapter, we care only about the first line in this message, which contains the “top-level header”, or, the three essential attributes about the HTTP Request, which are the HTTP method used, the URI and the HTTP version.\nNotice that I use the function indexOfScalar() in parse_request(). This function from the Zig Standard Library returns the first index where the scalar value that we provide happens in a string. In this case, I’m looking at the first occurrence of the new line character (\\n). Because once again, we care only about the first line in the HTTP Request message. This is the line where we have the three information that we want to parse (version of HTTP, the HTTP method and the URI).\nTherefore, we are using this indexOfScalar() function to limit our parsing process to the first line in the message. It’s also worth mentioning that, the indexOfScalar() function returns an optional value. That is why I use the orelse keyword to provide an alternative value, in case the value returned by the function is a null value.\nSince each of these three attributes are separated by a simple space, we could use the function splitScalar() from the Zig Standard Library to split the input string into sections by looking for every position that appears a simple space. In other words, this splitScalar() function is equivalent to the split() method in Python, or, the std::getline() function from C++, or the strtok() function in C.\nWhen you use this splitScalar() function, you get an iterator as the result. This iterator have a next() method that you can use to advance the iterator to the next position, or, to the next section of the splitted string. Note that, when you use next(), the method not only advances the iterator, but it also returns a slice to the current section of the splitted string as result.\nNow, if you want to get a slice to the current section of the splitted string, but not advance the iterator to the next position, you can use the peek() method. Both next() and peek() methods return an optional value, that is why I use the ? method to unwrap these optional values.\n\npub fn parse_request(text: []u8) Request {\n    const line_index = std.mem.indexOfScalar(\n        u8, text, '\\n'\n    ) orelse text.len;\n    var iterator = std.mem.splitScalar(\n        u8, text[0..line_index], ' '\n    );\n    const method = try Method.init(iterator.next().?);\n    const uri = iterator.next().?;\n    const version = iterator.next().?;\n    const request = Request.init(method, uri, version);\n    return request;\n}\n\nAs I described in Section 1.8, strings in Zig are simply arrays of bytes in the language. So, you will find lots of excellent utility functions to work directly with strings inside this mem module from the Zig Standard Library. We have described some of these useful utility functions already in Section 1.8.5.\n\n\n7.7.6 Using the parse request function\nNow that we wrote the function responsible for parsing the HTTP Request, we can add the function call to parse_request() in the main() function of our program.\nAfter that, is a good idea to test once again the state of our program. I execute this program again with the run command from the zig compiler, then, I use my web browser to connect once again to the server through the URL localhost:3490, and finally, the end result of our Request object is printed to the console.\nA quick observation, since I have used the any format specifier in the print statement, the data members version and uri of the Request struct were printed as raw integer values. String data being printed as integer values is common in Zig, and remember, these integer values are just the decimal representation of the bytes that form the string in question.\nIn the result below, the sequence of decimal values 72, 84, 84, 80, 47, 49, 46, 49, and 13, are the bytes that form the text “HTTP/1.1”. And the integer 47, is the decimal value of the character /, which represents our URI in this request.\n\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    try Request.read_request(\n        connection, buffer[0..buffer.len]\n    );\n    const request = Request.parse_request(\n        buffer[0..buffer.len]\n    );\n    try stdout.print(\"{any}\\n\", .{request});\n}\n\nrequest.Request{\n    .method = request.Method.GET,\n    .version = {72, 84, 84, 80, 47, 49, 46, 49, 13},\n    .uri = {47}\n}\n\n\n7.7.7 Sending the HTTP Response to the client\nIn this last part, we are going to write the logic responsible for sending the HTTP Response from the server to the client. To make things simple, the server in this project will send just a simple web page containing the text “Hello world”.\nFirst, I create a new Zig module in the project, named response.zig. In this module, I will declare just two functions. Each function corresponds to a specific status code in the HTTP Response. The send_200() function will send a HTTP Response with status code 200 (which means “Success”) to the client. While the send_404() function sends a response with status code 404 (which means “Not found”).\nThis is definitely not the most ergonomic and adequate way of handling the HTTP Response, but it works for our case here. We are just building toy projects in this book after all, therefore, the source code that we write do not need to be perfect. It just needs to work!\n\nconst std = @import(\"std\");\nconst Connection = std.net.Server.Connection;\npub fn send_200(conn: Connection) !void {\n    const message = (\n        \"HTTP/1.1 200 OK\\nContent-Length: 48\"\n        ++ \"\\nContent-Type: text/html\\n\"\n        ++ \"Connection: Closed\\n\\n&lt;html&gt;&lt;body&gt;\"\n        ++ \"&lt;h1&gt;Hello, World!&lt;/h1&gt;&lt;/body&gt;&lt;/html&gt;\"\n    );\n    _ = try conn.stream.write(message);\n}\n\npub fn send_404(conn: Connection) !void {\n    const message = (\n        \"HTTP/1.1 404 Not Found\\nContent-Length: 50\"\n        ++ \"\\nContent-Type: text/html\\n\"\n        ++ \"Connection: Closed\\n\\n&lt;html&gt;&lt;body&gt;\"\n        ++ \"&lt;h1&gt;File not found!&lt;/h1&gt;&lt;/body&gt;&lt;/html&gt;\"\n    );\n    _ = try conn.stream.write(message);\n}\n\nNotice that both functions receives the connection object as input, and use the write() method to write the HTTP Response message directly into this communication channel. As result, the party in the other side of the connection (i.e., the client), will receive such message.\nMost real-world HTTP Servers will have a single function (or a single struct) to effectively handle the response. It gets the HTTP Request already parsed as input, and then, it tries to build the HTTP Response bit by bit, before the function sends it over the connection.\nWe would also have a specialized struct to represent a HTTP Response, and a lot of methods that would be used to build each part or component of the response object. Take the Response struct created by the Javascript runtime Bun as an example. You can find this struct in the response.zig module4 in their GitHub project.",
     "crumbs": [
       "<span class='chapter-number'>7</span>  <span class='chapter-title'>Project 2 - Building a HTTP Server from scratch</span>"
     ]
@@ -614,7 +614,7 @@
     "href": "Chapters/04-http-server.html#the-end-result",
     "title": "7  Project 2 - Building a HTTP Server from scratch",
     "section": "7.8 The end result",
-    "text": "7.8 The end result\nWe can now, update once again our main() function to incorporate our new functions from the response.zig module. First, I need to import this module into our main.zig module, then, I add the function calls to send_200() and send_404().\nNotice that I’m using if statements to decide which “response function” to call, based especially on the URI present in the HTTP Request. If the user asked for a content (or a document) that is not present in our server, we should respond with a 404 status code. But since we have just a simple HTTP server, with no real documents to send, we can just check if the URI is the root path (/) or not to decide which function to call.\nAlso, notice that I’m using the function std.mem.eql() from the Zig Standard Library to check if the string from uri is equal or not the string \"/\". We have described this function already in Section 1.8.4, so, comeback to that section if you are not familiar yet with this function.\n\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst Response = @import(\"response.zig\");\nconst Method = Request.Method;\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    try Request.read_request(connection, buffer[0..buffer.len]);\n    const request = Request.parse_request(\n        buffer[0..buffer.len]\n    );\n    if (request.method == Method.GET) {\n        if (std.mem.eql(u8, request.uri, \"/\")) {\n            try Response.send_200(connection);\n        } else {\n            try Response.send_404(connection);\n        }\n    }\n}\n\nNow that we adjusted our main() function, I can now execute our program, and see the effects of these last changes. First, I execute the program once again, with the run command of the zig compiler. The program will hang, waiting for a client to connect.\nThen, I open my web browser, and try to connect to the server again, using the URL localhost:3490. This time, instead of getting some sort of an error message from the browser, you will get the message “Hello World” printed into your web browser. Because this time, the server sended the HTTP Response successfully to the web browser, as demonstrated by Figure 7.3.\n\n\n\n\n\n\nFigure 7.3: The Hello World message sent in the HTTP Response\n\n\n\n\n\n\n\nMeehan, Eric. 2021. “Creating a Web Server from Scratch in c.” Youtube. https://www.youtube.com/watch?v=gk6NL1pZi1M&ab_channel=EricOMeehan.\n\n\nWeerasiri, Nipun Chamikara. 2023. “A Simple Web Server Written in c.” Medium. https://medium.com/@nipunweerasiri/a-simple-web-server-written-in-c-cf7445002e6.\n\n\nWikipedia. 2024. “Port (Computer Networking).” Wikipedia. https://en.wikipedia.org/wiki/Port_(computer_networking).\n\n\nYu, Jeffrey. 2023. “How i Built a Simple HTTP Server from Scratch Using c.” DEV Community. https://dev.to/jeffreythecoder/how-i-built-a-simple-http-server-from-scratch-using-c-739.",
+    "text": "7.8 The end result\nWe can now, update once again our main() function to incorporate our new functions from the response.zig module. First, I need to import this module into our main.zig module, then, I add the function calls to send_200() and send_404().\nNotice that I’m using if statements to decide which “response function” to call, based especially on the URI present in the HTTP Request. If the user asked for a content (or a document) that is not present in our server, we should respond with a 404 status code. But since we have just a simple HTTP server, with no real documents to send, we can just check if the URI is the root path (/) or not to decide which function to call.\nAlso, notice that I’m using the function std.mem.eql() from the Zig Standard Library to check if the string from uri is equal or not the string \"/\". We have described this function already in Section 1.8.5, so, comeback to that section if you are not familiar yet with this function.\n\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst Response = @import(\"response.zig\");\nconst Method = Request.Method;\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    try Request.read_request(connection, buffer[0..buffer.len]);\n    const request = Request.parse_request(\n        buffer[0..buffer.len]\n    );\n    if (request.method == Method.GET) {\n        if (std.mem.eql(u8, request.uri, \"/\")) {\n            try Response.send_200(connection);\n        } else {\n            try Response.send_404(connection);\n        }\n    }\n}\n\nNow that we adjusted our main() function, I can now execute our program, and see the effects of these last changes. First, I execute the program once again, with the run command of the zig compiler. The program will hang, waiting for a client to connect.\nThen, I open my web browser, and try to connect to the server again, using the URL localhost:3490. This time, instead of getting some sort of an error message from the browser, you will get the message “Hello World” printed into your web browser. Because this time, the server sended the HTTP Response successfully to the web browser, as demonstrated by Figure 7.3.\n\n\n\n\n\n\nFigure 7.3: The Hello World message sent in the HTTP Response\n\n\n\n\n\n\n\nMeehan, Eric. 2021. “Creating a Web Server from Scratch in c.” Youtube. https://www.youtube.com/watch?v=gk6NL1pZi1M&ab_channel=EricOMeehan.\n\n\nWeerasiri, Nipun Chamikara. 2023. “A Simple Web Server Written in c.” Medium. https://medium.com/@nipunweerasiri/a-simple-web-server-written-in-c-cf7445002e6.\n\n\nWikipedia. 2024. “Port (Computer Networking).” Wikipedia. https://en.wikipedia.org/wiki/Port_(computer_networking).\n\n\nYu, Jeffrey. 2023. “How i Built a Simple HTTP Server from Scratch Using c.” DEV Community. https://dev.to/jeffreythecoder/how-i-built-a-simple-http-server-from-scratch-using-c-739.",
     "crumbs": [
       "<span class='chapter-number'>7</span>  <span class='chapter-title'>Project 2 - Building a HTTP Server from scratch</span>"
     ]

From 65ba5634c4c2aa289a2d390dd7a147d4ec60614a Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Wed, 9 Apr 2025 19:55:28 -0300
Subject: [PATCH 127/151] Add contributor

---
 _freeze/index/execute-results/html.json | 2 +-
 contributors.txt                        | 1 +
 docs/index.html                         | 4 ++--
 docs/search.json                        | 4 ++--
 4 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/_freeze/index/execute-results/html.json b/_freeze/index/execute-results/html.json
index 16283e0b..9e805cf2 100644
--- a/_freeze/index/execute-results/html.json
+++ b/_freeze/index/execute-results/html.json
@@ -2,7 +2,7 @@
   "hash": "0b80ffe49bae68e2641a31569b9e19df",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy a PDF, eBook or a physical copy\nof the book, either at Amazon, or at Leanpub:\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://leanpub.com/introductiontozigaproject-basedbook\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Leanpub!\n    </button>\n</a>\n\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e., open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.\nCurrently, he is a Senior Data Engineer at [DSM-Firmenich](https://www.dsm-firmenich.com)[^dsm], and\na Databricks Certified Associate Developer for Apache Spark 3.0.\n\n[^dsm]: <https://www.dsm-firmenich.com>\n\n\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nBrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer who loves to learn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2025 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n\n\n- System version: Linux, 6.11.0-19-generic, 24.04.1-Ubuntu, x86_64.\n- Zig version: 0.14.0-dev.3046+08d661fcf.\n- Quarto version: 1.5.57.\n\n\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang), Tommaso Ricci (\\@Zorgatone), Primo Sabatini (\\@primos63), Santiago Fernandez (\\@santif), Hamza Wahed (\\@HamzaWahed), mwilbur (\\@mwilbur), Dima Budaragin (\\@dbud), Jorge Jímenez (\\@jorge-j1m), Alexander (\\@alexwheezy), Maarten Coopens (\\@maarteNNNN), Niklas Johansson (\\@Raphexion), glystik (\\@glystik), Michael Lynch (\\@mtlynch)\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy a PDF, eBook or a physical copy\nof the book, either at Amazon, or at Leanpub:\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://leanpub.com/introductiontozigaproject-basedbook\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Leanpub!\n    </button>\n</a>\n\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e., open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.\nCurrently, he is a Senior Data Engineer at [DSM-Firmenich](https://www.dsm-firmenich.com)[^dsm], and\na Databricks Certified Associate Developer for Apache Spark 3.0.\n\n[^dsm]: <https://www.dsm-firmenich.com>\n\n\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nBrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer who loves to learn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2025 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n\n- System version: Linux, 6.11.0-21-generic, 24.04.1-Ubuntu, x86_64.\n- Zig version: 0.14.0-dev.3046+08d661fcf.\n- Quarto version: 1.5.57.\n\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang), Tommaso Ricci (\\@Zorgatone), Primo Sabatini (\\@primos63), Santiago Fernandez (\\@santif), Hamza Wahed (\\@HamzaWahed), mwilbur (\\@mwilbur), Dima Budaragin (\\@dbud), Jorge Jímenez (\\@jorge-j1m), Alexander (\\@alexwheezy), Maarten Coopens (\\@maarteNNNN), Niklas Johansson (\\@Raphexion), glystik (\\@glystik), Michael Lynch (\\@mtlynch), Yashank (\\@stickyburn)\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
diff --git a/contributors.txt b/contributors.txt
index 8a789f25..73ae3ac2 100644
--- a/contributors.txt
+++ b/contributors.txt
@@ -24,3 +24,4 @@ Maarten Coopens,@maarteNNNN
 Niklas Johansson,@Raphexion
 glystik,@glystik
 Michael Lynch,@mtlynch
+Yashank,@stickyburn
diff --git a/docs/index.html b/docs/index.html
index 63c5d147..ddb5b3ed 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -426,7 +426,7 @@ <h2 class="unnumbered anchored" data-anchor-id="license">License</h2>
 <h2 class="unnumbered anchored" data-anchor-id="book-compilation-metadata">Book compilation metadata</h2>
 <p>This book was compiled using the following versions of <a href="https://ziglang.org">Zig</a> and <a href="https://quarto.org">Quarto</a>:</p>
 <ul>
-<li>System version: Linux, 6.11.0-19-generic, 24.04.1-Ubuntu, x86_64.</li>
+<li>System version: Linux, 6.11.0-21-generic, 24.04.1-Ubuntu, x86_64.</li>
 <li>Zig version: 0.14.0-dev.3046+08d661fcf.</li>
 <li>Quarto version: 1.5.57.</li>
 </ul>
@@ -454,7 +454,7 @@ <h2 class="unnumbered anchored" data-anchor-id="corresponding-author-and-maintai
 <section id="acknowledgments" class="level2 unnumbered">
 <h2 class="unnumbered anchored" data-anchor-id="acknowledgments">Acknowledgments</h2>
 <p>This book is also a product of many conversations and exchanges that we had with different people from the Zig community. I (Pedro Duarte Faria) am incredibly grateful for these conversations, and also, for some direct contributions that we had. Below we have a list of the people involved (name of the person with their usename in GitHub):</p>
-<p>Calin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang), Tommaso Ricci (@Zorgatone), Primo Sabatini (@primos63), Santiago Fernandez (@santif), Hamza Wahed (@HamzaWahed), mwilbur (@mwilbur), Dima Budaragin (@dbud), Jorge Jímenez (@jorge-j1m), Alexander (@alexwheezy), Maarten Coopens (@maarteNNNN), Niklas Johansson (@Raphexion), glystik (@glystik), Michael Lynch (@mtlynch)</p>
+<p>Calin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang), Tommaso Ricci (@Zorgatone), Primo Sabatini (@primos63), Santiago Fernandez (@santif), Hamza Wahed (@HamzaWahed), mwilbur (@mwilbur), Dima Budaragin (@dbud), Jorge Jímenez (@jorge-j1m), Alexander (@alexwheezy), Maarten Coopens (@maarteNNNN), Niklas Johansson (@Raphexion), glystik (@glystik), Michael Lynch (@mtlynch), Yashank (@stickyburn)</p>
 
 
 </section>
diff --git a/docs/search.json b/docs/search.json
index 29d18ab1..07f2b577 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -54,7 +54,7 @@
     "href": "index.html#book-compilation-metadata",
     "title": "Introduction to Zig",
     "section": "Book compilation metadata",
-    "text": "Book compilation metadata\nThis book was compiled using the following versions of Zig and Quarto:\n\nSystem version: Linux, 6.11.0-19-generic, 24.04.1-Ubuntu, x86_64.\nZig version: 0.14.0-dev.3046+08d661fcf.\nQuarto version: 1.5.57.",
+    "text": "Book compilation metadata\nThis book was compiled using the following versions of Zig and Quarto:\n\nSystem version: Linux, 6.11.0-21-generic, 24.04.1-Ubuntu, x86_64.\nZig version: 0.14.0-dev.3046+08d661fcf.\nQuarto version: 1.5.57.",
     "crumbs": [
       "Welcome"
     ]
@@ -84,7 +84,7 @@
     "href": "index.html#acknowledgments",
     "title": "Introduction to Zig",
     "section": "Acknowledgments",
-    "text": "Acknowledgments\nThis book is also a product of many conversations and exchanges that we had with different people from the Zig community. I (Pedro Duarte Faria) am incredibly grateful for these conversations, and also, for some direct contributions that we had. Below we have a list of the people involved (name of the person with their usename in GitHub):\nCalin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang), Tommaso Ricci (@Zorgatone), Primo Sabatini (@primos63), Santiago Fernandez (@santif), Hamza Wahed (@HamzaWahed), mwilbur (@mwilbur), Dima Budaragin (@dbud), Jorge Jímenez (@jorge-j1m), Alexander (@alexwheezy), Maarten Coopens (@maarteNNNN), Niklas Johansson (@Raphexion), glystik (@glystik), Michael Lynch (@mtlynch)",
+    "text": "Acknowledgments\nThis book is also a product of many conversations and exchanges that we had with different people from the Zig community. I (Pedro Duarte Faria) am incredibly grateful for these conversations, and also, for some direct contributions that we had. Below we have a list of the people involved (name of the person with their usename in GitHub):\nCalin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang), Tommaso Ricci (@Zorgatone), Primo Sabatini (@primos63), Santiago Fernandez (@santif), Hamza Wahed (@HamzaWahed), mwilbur (@mwilbur), Dima Budaragin (@dbud), Jorge Jímenez (@jorge-j1m), Alexander (@alexwheezy), Maarten Coopens (@maarteNNNN), Niklas Johansson (@Raphexion), glystik (@glystik), Michael Lynch (@mtlynch), Yashank (@stickyburn)",
     "crumbs": [
       "Welcome"
     ]

From a007fc342a16645dd981d6c50e970caac4d44ce0 Mon Sep 17 00:00:00 2001
From: Pedro Faria <69123925+pedropark99@users.noreply.github.com>
Date: Sun, 13 Apr 2025 12:41:08 -0300
Subject: [PATCH 128/151] Update 01-zig-weird.qmd

---
 Chapters/01-zig-weird.qmd | 2 --
 1 file changed, 2 deletions(-)

diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index b37dcfe3..1f6a2c74 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -53,10 +53,8 @@ are what makes C++ so complex and hard to learn. Zig tries to go in the opposite
 Zig is a very simple language, more closely related to other simple languages such as C and Go.
 
 The phrase above is still important for C programmers too. Because, even C being a simple
-
 language, it's still hard sometimes to read and understand C code. For example, pre-processor macros in
 C are a frequent source of confusion. Sometimes, they really make it hard to debug
-
 C programs. Because macros are essentially a second language embedded in C that obscures
 your C code. With macros, you are no longer 100% sure about which pieces
 of the code are being sent to the compiler, i.e.

From 1563c613605e161b7ac1e6ea3de2885f9d3dd862 Mon Sep 17 00:00:00 2001
From: Pedro Faria <69123925+pedropark99@users.noreply.github.com>
Date: Sun, 13 Apr 2025 12:47:28 -0300
Subject: [PATCH 129/151] Update 01-zig-weird.qmd

---
 Chapters/01-zig-weird.qmd | 1 -
 1 file changed, 1 deletion(-)

diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index 1f6a2c74..99c710af 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -449,7 +449,6 @@ Hello
 
 You can read more details about this Windows-specific limitation in a couple of
 GitHub issues opened at the official Zig repository. More specifically, the issues
-
 17186 [^cissue1] and 19864 [^cissue2].
 
 [^cissue1]: <https://github.com/ziglang/zig/issues/17186>

From 00cd2f39ffe0aae9c0ba2476c5e179761abb1cf3 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sun, 13 Apr 2025 14:38:29 -0300
Subject: [PATCH 130/151] Recompile book with fixes

---
 .../01-zig-weird/execute-results/html.json    |  8 +++-----
 docs/Chapters/01-zig-weird.html               | 19 ++++++++-----------
 docs/search.json                              | 12 ++++++------
 3 files changed, 17 insertions(+), 22 deletions(-)

diff --git a/_freeze/Chapters/01-zig-weird/execute-results/html.json b/_freeze/Chapters/01-zig-weird/execute-results/html.json
index 4f120244..4920b2b5 100644
--- a/_freeze/Chapters/01-zig-weird/execute-results/html.json
+++ b/_freeze/Chapters/01-zig-weird/execute-results/html.json
@@ -1,11 +1,9 @@
 {
-  "hash": "569cc4cd11b03e6a2e83a391821389ed",
+  "hash": "4d435d48922c81726d4668b9e1fc1e4f",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\n\nlanguage, it's still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. Sometimes, they really make it hard to debug\n\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscure the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that gets compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e., where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contains Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nWe can use this build system to write small scripts in Zig,\nwhich describe the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e., creating new objects)\nare made in Zig. You can create a new object in Zig by using the syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). In @sec-assignments we talk more about objects in general.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that in @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIt's worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt's like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portable C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nIn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e., the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. If you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith an \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, on Windows, operations like accessing the `stdout` (or opening a file) depend on\nresources that are available only at *runtime* (you will learn more about compile-time versus runtime\nin @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerges from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword in @sec-comptime.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation in a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues\n\n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described in @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig later in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig?\nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar to our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentation.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It's a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (on YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e., identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nSo, if you want to change the value of your object, you need to transform your immutable (or \"constant\")\nobject into a mutable (or \"variable\") object. You can do that by using the `var` keyword.\nThis keyword stands for \"variable\", and when you apply this keyword to some object, you are\ntelling the Zig compiler that the value associated with this object might change at some point.\n\nThus, if we come back to the previous example, and change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it's a \"variable object\".\n\nHowever, if you take a look at the example below, you will notice that we have not only declared the\n`age` object with the `var` keyword, but we also have explicitly annotated the data type\nof the `age` object with the `u8` type this time. The basic idea is, when we use a variable/mutable object,\nthe Zig compiler ask for us to be more explicit with what we want, to be more clear\nabout what our code does. This translates into being more explicit about the data types that we want\nto use in our objects.\n\nTherefore, if you transform your object into a variable/mutable object, just remember to always\nannotate the type of the object explicitly in your code. Otherwise, the Zig compiler might raise\na compilation error, asking you to transform your object back into a `const` object, or,\nto give your object an \"explicit type\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIt's important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code uses this object while it's uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object.\n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e., if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to a special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It's discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also gets discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig have many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e., the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\nIt's worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it have the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it's a slice that\naccesses all elements in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhave 2 elements in it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" in @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth in @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially in @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned in @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e., both the start and the end of this range)\nis known at compile-time, the slice object that gets created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nin @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that gets created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e., a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can\ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n_ = slice;\n```\n:::\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat gets created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, we are reading a file, and then, we try to create a slice object\nthat covers the entire buffer that contains the contents of this file. This is obviously\nan example of a runtime known range, because the end index of the range\nis not known at compile time.\n\nIn other words, the end index of the range is the size of\nthe array `file_contents`. However, the size of `file_contents` is not known at compile time.\nBecause we don't know how many bytes are stored inside this `shop-list.txt` file.\nAnd because this is a file, someone might edit this file tomorrow and add more lines\nor remove lines from it. Therefore, the size of this file might vary drastically from one execution to another.\n\nNow, if the file size can vary from one run to another, then, we can conclude that the value of the expression\n`file_contents.len` exposed in the example below can also vary from one run to another. As consequence,\nthe value of the expression `file_contents.len` is runtime-known only, and, as a consequence of that,\nthe range `0..file_contents.len` is also runtime-known only.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\nfn read_file(allocator: std.mem.Allocator, path: []const u8) ![]u8 {\n    const file = try std.fs.cwd().openFile(path, .{});\n    defer file.close();\n    return try file.reader().readAllAlloc(\n        allocator, std.math.maxInt(usize)\n    );\n}\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const path = \"../ZigExamples/file-io/shop-list.txt\";\n    const file_contents = try read_file(allocator, path);\n    const slice = file_contents[0..file_contents.len];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code have its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e., a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nStrings in Zig work very similarly to strings in C, but they come with some extra caveats which adds more safety\nand efficiency to them. You could also say that Zig simply uses a more modern and safe approach to manage\nand use strings.\n\nA string in Zig is essentially an array of arbitrary bytes, or, more specifically, an array of `u8` values.\nThis very similar to a string in C, which is also interpreted as an array of arbitrary bytes, or, in the case\nof C, an array of `char` (which usually represents an unsigned 8-bit integer value in most systems) values.\n\nNow, because a string in Zig is an array, you automatically\nget the length of the string (i.e. the length of the array) embedded in the value itself. This makes\nall the difference! Because now, the Zig compiler can use the length value that is embedded in the string to\ncheck for \"buffer overflow\" or \"wrong memory access\" problems in your code.\n\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need to do something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible in the string value itself. You can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\nAnother point is that Zig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e., a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Using a slice versus a sentinel-terminated array\n\nIn memory, all string values in Zig are always stored in the same way.\nThey are simply stored as sequences/arrays of arbitrary bytes. But you can use and access\nthis sequence of bytes in two different ways. You can access this sequence of bytes as:\n\n- a sentinel-terminated array of `u8` values.\n- or as a slice of `u8` values.\n\n\n#### Sentinel-terminated arrays\n\nSentinel-terminated arrays in Zig are described in the Language Reference of Zig[^sentinel].\nIn summary a sentinel-terminated array is just a normal array, but, the difference is that they\ncontain a \"sentinel value\" at the last index/element of the array. With a sentinel-terminated array\nyou embed both the length of the array, and also, the sentinel value in the type itself of your object.\n\n[^sentinel]: <https://ziglang.org/documentation/master/#Sentinel-Terminated-Arrays>.\n\nFor example, if you write a string literal value in your code, and ask Zig to print the data type of this value,\nyou usually get a data type in the format `*const [n:0]u8`. The `n` in the data type indicates the size of\nthe string (that is the length of the array). The zero after the `n:` part of the data type is the sentinel\nvalue itself.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n_ = \"A literal value\";\ntry stdout.print(\"{any}\\n\", .{@TypeOf(\"A literal value\")});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n*const [15:0]u8\n```\n\n\n:::\n:::\n\n\n\n\n\nSo, with this data type `*const [n:0]u8` you are essentially saying that you have an array of `u8` values\nof length `n`, where, the element at the index corresponding to the length `n` in the array is the\nnumber zero. If you really think about this description, you will notice that this is just a fancy way to\ndescribe a string in C, which is a null-terminated array of bytes. The `NULL` value in C is the number\nzero. So, an array that ends in a null/zero value in C is essentially a sentinel-terminated array in Zig,\nwhere the sentinel value of the array is the number zero.\n\nTherefore, a string literal value in Zig is just a pointer to a null-terminated array of bytes (i.e., similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string, and also, the fact that they are \"NULL terminated\",\ninto the data type of the value itself.\n\n\n\n#### Slice\n\nYou can also access and use the arbitrary sequence of bytes that represent your string as a slice of `u8` values.\nThe majority of functions from the Zig standard library usually receive strings as inputs as slices of\n`u8` values (slices were presented in @sec-arrays).\n\nThus, you will see a lot of string values with a data type of `[]u8` or `[]const u8`, depending if the object\nwhere this string is stored is marked as constant with `const`, or as variable with `var`. Now, because\nthe string in this case is being interpreted as a slice, this slice is not necessarilly null-terminated,\nbecause now, the sentinel value is not mandatory. You can include the null/zero value in the slice if you\nwant to, but there is no need to do it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string value being\n// interpreted as a slice.\nconst str: []const u8 = \"A string value\";\ntry stdout.print(\"{any}\\n\", .{@TypeOf(str)});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n[]const u8\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Iterating through the string\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below,\nand also, you can see that this is a null-terminated array, because of the zero value after the `:` character in the data type.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it's a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n:::\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIt's important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig in @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers in @sec-root-file and especially in @sec-assignments.\n- How strings work in Zig in @sec-zig-strings.\n- How to use arrays and slices in @sec-arrays.\n- How to import functionality from other Zig modules in @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* in @sec-structs-and-oop.\n- Basic control flow syntax in @sec-zig-control-flow.\n- Enums in @sec-enum;\n- Pointers and Optionals in @sec-pointer;\n- Error handling with `try` and `catch` in @sec-error-handling;\n- Unit tests in @sec-unittests;\n- Vectors in @sec-vectors-simd;\n- Build System in @sec-build-system;\n",
-    "supporting": [
-      "01-zig-weird_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\nlanguage, it's still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. Sometimes, they really make it hard to debug\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscure the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that gets compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e., where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contains Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nWe can use this build system to write small scripts in Zig,\nwhich describe the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e., creating new objects)\nare made in Zig. You can create a new object in Zig by using the syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). In @sec-assignments we talk more about objects in general.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that in @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIt's worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt's like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portable C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nIn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e., the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. If you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith an \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, on Windows, operations like accessing the `stdout` (or opening a file) depend on\nresources that are available only at *runtime* (you will learn more about compile-time versus runtime\nin @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerges from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword in @sec-comptime.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation in a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues\n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described in @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig later in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig?\nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar to our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentation.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It's a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (on YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e., identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nSo, if you want to change the value of your object, you need to transform your immutable (or \"constant\")\nobject into a mutable (or \"variable\") object. You can do that by using the `var` keyword.\nThis keyword stands for \"variable\", and when you apply this keyword to some object, you are\ntelling the Zig compiler that the value associated with this object might change at some point.\n\nThus, if we come back to the previous example, and change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it's a \"variable object\".\n\nHowever, if you take a look at the example below, you will notice that we have not only declared the\n`age` object with the `var` keyword, but we also have explicitly annotated the data type\nof the `age` object with the `u8` type this time. The basic idea is, when we use a variable/mutable object,\nthe Zig compiler ask for us to be more explicit with what we want, to be more clear\nabout what our code does. This translates into being more explicit about the data types that we want\nto use in our objects.\n\nTherefore, if you transform your object into a variable/mutable object, just remember to always\nannotate the type of the object explicitly in your code. Otherwise, the Zig compiler might raise\na compilation error, asking you to transform your object back into a `const` object, or,\nto give your object an \"explicit type\".\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIt's important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code uses this object while it's uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object.\n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e., if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to a special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It's discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also gets discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig has many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e., the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\n\nIt's worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it has the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it's a slice that\naccesses all elements in the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhas 2 elements in it.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" in @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth in @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially in @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned in @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e., both the start and the end of this range)\nis known at compile-time, the slice object that gets created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nin @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that gets created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e., a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can\ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice has a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n_ = slice;\n```\n:::\n\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat gets created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, we are reading a file, and then, we try to create a slice object\nthat covers the entire buffer that contains the contents of this file. This is obviously\nan example of a runtime known range, because the end index of the range\nis not known at compile time.\n\nIn other words, the end index of the range is the size of\nthe array `file_contents`. However, the size of `file_contents` is not known at compile time.\nBecause we don't know how many bytes are stored inside this `shop-list.txt` file.\nAnd because this is a file, someone might edit this file tomorrow and add more lines\nor remove lines from it. Therefore, the size of this file might vary drastically from one execution to another.\n\nNow, if the file size can vary from one run to another, then, we can conclude that the value of the expression\n`file_contents.len` exposed in the example below can also vary from one run to another. As consequence,\nthe value of the expression `file_contents.len` is runtime-known only, and, as a consequence of that,\nthe range `0..file_contents.len` is also runtime-known only.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\nfn read_file(allocator: std.mem.Allocator, path: []const u8) ![]u8 {\n    const file = try std.fs.cwd().openFile(path, .{});\n    defer file.close();\n    return try file.reader().readAllAlloc(\n        allocator, std.math.maxInt(usize)\n    );\n}\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const path = \"../ZigExamples/file-io/shop-list.txt\";\n    const file_contents = try read_file(allocator, path);\n    const slice = file_contents[0..file_contents.len];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code has its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e., a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nStrings in Zig work very similarly to strings in C, but they come with some extra caveats which adds more safety\nand efficiency to them. You could also say that Zig simply uses a more modern and safe approach to manage\nand use strings.\n\nA string in Zig is essentially an array of arbitrary bytes, or, more specifically, an array of `u8` values.\nThis very similar to a string in C, which is also interpreted as an array of arbitrary bytes, or, in the case\nof C, an array of `char` (which usually represents an unsigned 8-bit integer value in most systems) values.\n\nNow, because a string in Zig is an array, you automatically\nget the length of the string (i.e. the length of the array) embedded in the value itself. This makes\nall the difference! Because now, the Zig compiler can use the length value that is embedded in the string to\ncheck for \"buffer overflow\" or \"wrong memory access\" problems in your code.\n\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need to do something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible in the string value itself. You can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n\nAnother point is that Zig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e., a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n### Using a slice versus a sentinel-terminated array\n\nIn memory, all string values in Zig are always stored in the same way.\nThey are simply stored as sequences/arrays of arbitrary bytes. But you can use and access\nthis sequence of bytes in two different ways. You can access this sequence of bytes as:\n\n- a sentinel-terminated array of `u8` values.\n- or as a slice of `u8` values.\n\n\n#### Sentinel-terminated arrays\n\nSentinel-terminated arrays in Zig are described in the Language Reference of Zig[^sentinel].\nIn summary a sentinel-terminated array is just a normal array, but, the difference is that they\ncontain a \"sentinel value\" at the last index/element of the array. With a sentinel-terminated array\nyou embed both the length of the array, and also, the sentinel value in the type itself of your object.\n\n[^sentinel]: <https://ziglang.org/documentation/master/#Sentinel-Terminated-Arrays>.\n\nFor example, if you write a string literal value in your code, and ask Zig to print the data type of this value,\nyou usually get a data type in the format `*const [n:0]u8`. The `n` in the data type indicates the size of\nthe string (that is the length of the array). The zero after the `n:` part of the data type is the sentinel\nvalue itself.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n_ = \"A literal value\";\ntry stdout.print(\"{any}\\n\", .{@TypeOf(\"A literal value\")});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n*const [15:0]u8\n```\n\n\n:::\n:::\n\n\n\n\n\n\nSo, with this data type `*const [n:0]u8` you are essentially saying that you have an array of `u8` values\nof length `n`, where, the element at the index corresponding to the length `n` in the array is the\nnumber zero. If you really think about this description, you will notice that this is just a fancy way to\ndescribe a string in C, which is a null-terminated array of bytes. The `NULL` value in C is the number\nzero. So, an array that ends in a null/zero value in C is essentially a sentinel-terminated array in Zig,\nwhere the sentinel value of the array is the number zero.\n\nTherefore, a string literal value in Zig is just a pointer to a null-terminated array of bytes (i.e., similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string, and also, the fact that they are \"NULL terminated\",\ninto the data type of the value itself.\n\n\n\n#### Slice\n\nYou can also access and use the arbitrary sequence of bytes that represent your string as a slice of `u8` values.\nThe majority of functions from the Zig standard library usually receive strings as inputs as slices of\n`u8` values (slices were presented in @sec-arrays).\n\nThus, you will see a lot of string values with a data type of `[]u8` or `[]const u8`, depending if the object\nwhere this string is stored is marked as constant with `const`, or as variable with `var`. Now, because\nthe string in this case is being interpreted as a slice, this slice is not necessarilly null-terminated,\nbecause now, the sentinel value is not mandatory. You can include the null/zero value in the slice if you\nwant to, but there is no need to do it.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string value being\n// interpreted as a slice.\nconst str: []const u8 = \"A string value\";\ntry stdout.print(\"{any}\\n\", .{@TypeOf(str)});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n[]const u8\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n### Iterating through the string\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below,\nand also, you can see that this is a null-terminated array, because of the zero value after the `:` character in the data type.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it's a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n:::\n\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIt's important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop through the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig in @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers in @sec-root-file and especially in @sec-assignments.\n- How strings work in Zig in @sec-zig-strings.\n- How to use arrays and slices in @sec-arrays.\n- How to import functionality from other Zig modules in @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* in @sec-structs-and-oop.\n- Basic control flow syntax in @sec-zig-control-flow.\n- Enums in @sec-enum;\n- Pointers and Optionals in @sec-pointer;\n- Error handling with `try` and `catch` in @sec-error-handling;\n- Unit tests in @sec-unittests;\n- Vectors in @sec-vectors-simd;\n- Build System in @sec-build-system;\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/docs/Chapters/01-zig-weird.html b/docs/Chapters/01-zig-weird.html
index 4c437852..50076fd1 100644
--- a/docs/Chapters/01-zig-weird.html
+++ b/docs/Chapters/01-zig-weird.html
@@ -372,9 +372,7 @@ <h2 data-number="1.1" class="anchored" data-anchor-id="what-is-zig"><span class=
 <p>“Focus on debugging your application rather than debugging your programming language knowledge”.</p>
 </blockquote>
 <p>This phrase is specially true for C++ programmers. Because C++ is a gigantic language, with tons of features, and also, there are lots of different “flavors of C++”. These elements are what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction. Zig is a very simple language, more closely related to other simple languages such as C and Go.</p>
-<p>The phrase above is still important for C programmers too. Because, even C being a simple</p>
-<p>language, it’s still hard sometimes to read and understand C code. For example, pre-processor macros in C are a frequent source of confusion. Sometimes, they really make it hard to debug</p>
-<p>C programs. Because macros are essentially a second language embedded in C that obscures your C code. With macros, you are no longer 100% sure about which pieces of the code are being sent to the compiler, i.e. they obscure the actual source code that you wrote.</p>
+<p>The phrase above is still important for C programmers too. Because, even C being a simple language, it’s still hard sometimes to read and understand C code. For example, pre-processor macros in C are a frequent source of confusion. Sometimes, they really make it hard to debug C programs. Because macros are essentially a second language embedded in C that obscures your C code. With macros, you are no longer 100% sure about which pieces of the code are being sent to the compiler, i.e. they obscure the actual source code that you wrote.</p>
 <p>You don’t have macros in Zig. In Zig, the code you write, is the actual code that gets compiled by the compiler. You also don’t have a hidden control flow happening behind the scenes. And, you also don’t have functions or operators from the standard library that make hidden memory allocations behind your back.</p>
 <p>By being a simpler language, Zig becomes much more clear and easier to read/write, but at the same time, it also achieves a much more robust state, with more consistent behaviour in edge situations. Once again, less is more.</p>
 </section>
@@ -507,8 +505,7 @@ <h3 data-number="1.2.6" class="anchored" data-anchor-id="important-note-for-wind
 <span id="cb16-6"><a href="#cb16-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Hello</code></pre>
-<p>You can read more details about this Windows-specific limitation in a couple of GitHub issues opened at the official Zig repository. More specifically, the issues</p>
-<p>17186 <a href="#fn7" class="footnote-ref" id="fnref7" role="doc-noteref"><sup>7</sup></a> and 19864 <a href="#fn8" class="footnote-ref" id="fnref8" role="doc-noteref"><sup>8</sup></a>.</p>
+<p>You can read more details about this Windows-specific limitation in a couple of GitHub issues opened at the official Zig repository. More specifically, the issues 17186 <a href="#fn7" class="footnote-ref" id="fnref7" role="doc-noteref"><sup>7</sup></a> and 19864 <a href="#fn8" class="footnote-ref" id="fnref8" role="doc-noteref"><sup>8</sup></a>.</p>
 </section>
 <section id="sec-compile-project" class="level3" data-number="1.2.7">
 <h3 data-number="1.2.7" class="anchored" data-anchor-id="sec-compile-project"><span class="header-section-number">1.2.7</span> Compiling the entire project</h3>
@@ -653,7 +650,7 @@ <h3 data-number="1.4.4" class="anchored" data-anchor-id="you-must-mutate-every-v
 </section>
 <section id="sec-primitive-data-types" class="level2" data-number="1.5">
 <h2 data-number="1.5" class="anchored" data-anchor-id="sec-primitive-data-types"><span class="header-section-number">1.5</span> Primitive Data Types</h2>
-<p>Zig have many different primitive data types available for you to use. You can see the full list of available data types at the official <a href="https://ziglang.org/documentation/master/#Primitive-Types">Language Reference page</a><a href="#fn21" class="footnote-ref" id="fnref21" role="doc-noteref"><sup>21</sup></a>.</p>
+<p>Zig has many different primitive data types available for you to use. You can see the full list of available data types at the official <a href="https://ziglang.org/documentation/master/#Primitive-Types">Language Reference page</a><a href="#fn21" class="footnote-ref" id="fnref21" role="doc-noteref"><sup>21</sup></a>.</p>
 <p>But here is a quick list:</p>
 <ul>
 <li>Unsigned integers: <code>u8</code>, 8-bit integer; <code>u16</code>, 16-bit integer; <code>u32</code>, 32-bit integer; <code>u64</code>, 64-bit integer; <code>u128</code>, 128-bit integer.</li>
@@ -686,7 +683,7 @@ <h3 data-number="1.6.1" class="anchored" data-anchor-id="sec-select-array-elem">
 <pre><code>12</code></pre>
 </div>
 </div>
-<p>In contrast, you can also select specific slices (or sections) of your array, by using a range selector. Some programmers also call these selectors of “slice selectors”, and they also exist in Rust, and have the exact same syntax as in Zig. Anyway, a range selector is a special expression in Zig that defines a range of indexes, and it have the syntax <code>start..end</code>.</p>
+<p>In contrast, you can also select specific slices (or sections) of your array, by using a range selector. Some programmers also call these selectors of “slice selectors”, and they also exist in Rust, and have the exact same syntax as in Zig. Anyway, a range selector is a special expression in Zig that defines a range of indexes, and it has the syntax <code>start..end</code>.</p>
 <p>In the example below, at the second line of code, the <code>sl</code> object stores a slice (or a portion) of the <code>ns</code> array. More precisely, the elements at index 1 and 2 in the <code>ns</code> array.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb35"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb35-1"><a href="#cb35-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ns = [<span class="dv">4</span>]<span class="dt">u8</span><span class="op">{</span><span class="dv">48</span>, <span class="dv">24</span>, <span class="dv">12</span>, <span class="dv">6</span><span class="op">}</span>;</span>
@@ -715,7 +712,7 @@ <h3 data-number="1.6.2" class="anchored" data-anchor-id="more-on-slices"><span c
 <p>Slices can be thought of as a pair of <code>[*]T</code> (the pointer to the data) and a <code>usize</code> (the element count) <span class="citation" data-cites="zigguide">(<a href="../references.html#ref-zigguide" role="doc-biblioref">Sobeston 2024</a>)</span>.</p>
 </blockquote>
 <p>Through the pointer contained inside the slice you can access the elements (or values) that are inside this range (or portion) that you selected from the original array. But the length number (which you can access through the <code>len</code> property of your slice object) is the really big improvement (over C arrays for example) that Zig brings to the table here.</p>
-<p>Because with this length number the <code>zig</code> compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice, or, if you are causing any buffer overflow problems. In the example below, we access the <code>len</code> property of the slice <code>sl</code>, which tells us that this slice have 2 elements in it.</p>
+<p>Because with this length number the <code>zig</code> compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice, or, if you are causing any buffer overflow problems. In the example below, we access the <code>len</code> property of the slice <code>sl</code>, which tells us that this slice has 2 elements in it.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb38"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb38-1"><a href="#cb38-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> ns = [<span class="dv">4</span>]<span class="dt">u8</span><span class="op">{</span><span class="dv">48</span>, <span class="dv">24</span>, <span class="dv">12</span>, <span class="dv">6</span><span class="op">}</span>;</span>
 <span id="cb38-2"><a href="#cb38-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> sl = ns[<span class="dv">1</span>..<span class="dv">3</span>];</span>
@@ -761,7 +758,7 @@ <h3 data-number="1.6.4" class="anchored" data-anchor-id="runtime-versus-compile-
 <span id="cb44-2"><a href="#cb44-2" aria-hidden="true" tabindex="-1"></a>    <span class="dv">1</span>, <span class="dv">2</span>, <span class="dv">3</span>, <span class="dv">4</span>, <span class="dv">5</span>,</span>
 <span id="cb44-3"><a href="#cb44-3" aria-hidden="true" tabindex="-1"></a>    <span class="dv">6</span>, <span class="dv">7</span>, <span class="dv">8</span>, <span class="dv">9</span>, <span class="dv">10</span></span>
 <span id="cb44-4"><a href="#cb44-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
-<span id="cb44-5"><a href="#cb44-5" aria-hidden="true" tabindex="-1"></a><span class="co">// This slice have a compile-time known range.</span></span>
+<span id="cb44-5"><a href="#cb44-5" aria-hidden="true" tabindex="-1"></a><span class="co">// This slice has a compile-time known range.</span></span>
 <span id="cb44-6"><a href="#cb44-6" aria-hidden="true" tabindex="-1"></a><span class="co">// Because we know both the start and end of the range.</span></span>
 <span id="cb44-7"><a href="#cb44-7" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> slice = arr1[<span class="dv">1</span>..<span class="dv">4</span>];</span>
 <span id="cb44-8"><a href="#cb44-8" aria-hidden="true" tabindex="-1"></a>_ = slice;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
@@ -798,7 +795,7 @@ <h2 data-number="1.7" class="anchored" data-anchor-id="sec-blocks"><span class="
 <p>Blocks are created in Zig by a pair of curly braces. A block is just a group of expressions (or statements) contained inside of a pair of curly braces. All of these expressions that are contained inside of this pair of curly braces belongs to the same scope.</p>
 <p>In other words, a block just delimits a scope in your code. The objects that you define inside the same block belongs to the same scope, and, therefore, are accessible from within this scope. At the same time, these objects are not accessible outside of this scope. So, you could also say that blocks are used to limit the scope of the objects that you create in your source code. In less technical terms, blocks are used to specify where in your source code you can access whatever object you have in your source code.</p>
 <p>So, a block is just a group of expressions contained inside a pair of curly braces. And every block have its own scope separated from the others. The body of a function is a classic example of a block. If statements, for and while loops (and any other structure in the language that uses the pair of curly braces) are also examples of blocks.</p>
-<p>This means that, every if statement, or for loop, etc., that you create in your source code have its own separate scope. That is why you can’t access the objects that you defined inside of your for loop (or if statement) in an outer scope, i.e., a scope outside of the for loop. Because you are trying to access an object that belongs to a scope that is different than your current scope.</p>
+<p>This means that, every if statement, or for loop, etc., that you create in your source code has its own separate scope. That is why you can’t access the objects that you defined inside of your for loop (or if statement) in an outer scope, i.e., a scope outside of the for loop. Because you are trying to access an object that belongs to a scope that is different than your current scope.</p>
 <p>You can create blocks within blocks, with multiple levels of nesting. You can also (if you want to) give a label to a particular block, with the colon character (<code>:</code>). Just write <code>label:</code> before you open the pair of curly braces that delimits your block. When you label a block in Zig, you can use the <code>break</code> keyword to return a value from this block, like as if it was a function’s body. You just write the <code>break</code> keyword, followed by the block label in the format <code>:label</code>, and the expression that defines the value that you want to return.</p>
 <p>Like in the example below, where we are returning the value from the <code>y</code> object from the block <code>add_one</code>, and saving the result inside the <code>x</code> object.</p>
 <div class="cell">
@@ -973,7 +970,7 @@ <h3 data-number="1.8.4" class="anchored" data-anchor-id="byte-vs-unicode-points"
 </div>
 </div>
 <p>This means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together to represent the number 570. That is why the relationship between bytes and unicode points is not always 1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds to a single unicode point.</p>
-<p>All of this means that if you loop trough the elements of a string in Zig, you will be looping through the bytes that represents that string, and not through the characters of that string. In the Ⱥ example above, the for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.</p>
+<p>All of this means that if you loop through the elements of a string in Zig, you will be looping through the bytes that represents that string, and not through the characters of that string. In the Ⱥ example above, the for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.</p>
 <p>Now, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a consequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because the number of bytes will be equal to the number of characters in that string. In other words, in this specific situation, the relationship between bytes and unicode points is 1 to 1.</p>
 <p>But on the other side, if your string contains other types of letters… for example, you might be working with text data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent your UTF-8 string will likely be much higher than the number of characters in that string.</p>
 <p>If you need to iterate through the characters of a string, instead of its bytes, then, you can use the <code>std.unicode.Utf8View</code> struct to create an iterator that iterates through the unicode points of your string.</p>
diff --git a/docs/search.json b/docs/search.json
index 07f2b577..fbcaa66e 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -104,7 +104,7 @@
     "href": "Chapters/01-zig-weird.html",
     "title": "1  Introducing Zig",
     "section": "",
-    "text": "1.1 What is Zig?\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of Zig as a modern and better version of C.\nIn the author’s personal interpretation, Zig is tightly connected with “less is more”. Instead of trying to become a modern language by adding more and more features, many of the core improvements that Zig brings to the table are actually about removing annoying behaviours/features from C and C++. In other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour. As a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\nThis philosophy becomes clear with the following phrase from the official website of Zig:\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language, with tons of features, and also, there are lots of different “flavors of C++”. These elements are what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction. Zig is a very simple language, more closely related to other simple languages such as C and Go.\nThe phrase above is still important for C programmers too. Because, even C being a simple\nlanguage, it’s still hard sometimes to read and understand C code. For example, pre-processor macros in C are a frequent source of confusion. Sometimes, they really make it hard to debug\nC programs. Because macros are essentially a second language embedded in C that obscures your C code. With macros, you are no longer 100% sure about which pieces of the code are being sent to the compiler, i.e. they obscure the actual source code that you wrote.\nYou don’t have macros in Zig. In Zig, the code you write, is the actual code that gets compiled by the compiler. You also don’t have a hidden control flow happening behind the scenes. And, you also don’t have functions or operators from the standard library that make hidden memory allocations behind your back.\nBy being a simpler language, Zig becomes much more clear and easier to read/write, but at the same time, it also achieves a much more robust state, with more consistent behaviour in edge situations. Once again, less is more.",
+    "text": "1.1 What is Zig?\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of Zig as a modern and better version of C.\nIn the author’s personal interpretation, Zig is tightly connected with “less is more”. Instead of trying to become a modern language by adding more and more features, many of the core improvements that Zig brings to the table are actually about removing annoying behaviours/features from C and C++. In other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour. As a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\nThis philosophy becomes clear with the following phrase from the official website of Zig:\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language, with tons of features, and also, there are lots of different “flavors of C++”. These elements are what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction. Zig is a very simple language, more closely related to other simple languages such as C and Go.\nThe phrase above is still important for C programmers too. Because, even C being a simple language, it’s still hard sometimes to read and understand C code. For example, pre-processor macros in C are a frequent source of confusion. Sometimes, they really make it hard to debug C programs. Because macros are essentially a second language embedded in C that obscures your C code. With macros, you are no longer 100% sure about which pieces of the code are being sent to the compiler, i.e. they obscure the actual source code that you wrote.\nYou don’t have macros in Zig. In Zig, the code you write, is the actual code that gets compiled by the compiler. You also don’t have a hidden control flow happening behind the scenes. And, you also don’t have functions or operators from the standard library that make hidden memory allocations behind your back.\nBy being a simpler language, Zig becomes much more clear and easier to read/write, but at the same time, it also achieves a much more robust state, with more consistent behaviour in edge situations. Once again, less is more.",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -124,7 +124,7 @@
     "href": "Chapters/01-zig-weird.html#hello-world-in-zig",
     "title": "1  Introducing Zig",
     "section": "1.2 Hello world in Zig",
-    "text": "1.2 Hello world in Zig\nWe begin our journey in Zig by creating a small “Hello World” program. To start a new Zig project in your computer, you simply call the init command from the zig compiler. Just create a new directory in your computer, then, init a new Zig project inside this directory, like this:\nmkdir hello_world\ncd hello_world\nzig init\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n\n1.2.1 Understanding the project files\nAfter you run the init command from the zig compiler, some new files are created inside of your current directory. First, a “source” (src) directory is created, containing two files, main.zig and root.zig. Each .zig file is a separate Zig module, which is simply a text file that contains some Zig code.\nBy convention, the main.zig module is where your main function lives. Thus, if you are building an executable program in Zig, you need to declare a main() function, which represents the entrypoint of your program, i.e., where the execution of your program begins.\nHowever, if you are building a library (instead of an executable program), then, the normal procedure is to delete this main.zig file and start with the root.zig module. By convention, the root.zig module is the root source file of your library.\ntree .\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\nThe init command also creates two additional files in our working directory: build.zig and build.zig.zon. The first file (build.zig) represents a build script written in Zig. This script is executed when you call the build command from the zig compiler. In other words, this file contains Zig code that executes the necessary steps to build the entire project.\nLow-level languages normally use a compiler to build your source code into binary executables or binary libraries. Nevertheless, this process of compiling your source code and building binary executables or binary libraries from it, became a real challenge in the programming world, once the projects became bigger and bigger. As a result, programmers created “build systems”, which are a second set of tools designed to make this process of compiling and building complex projects, easier.\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja, which are used to build complex C and C++ projects. With these systems, you can write scripts, which are called “build scripts”. They simply are scripts that describes the necessary steps to compile/build your project.\nHowever, these are separate tools, that do not belong to C/C++ compilers, like gcc or clang. As a result, in C/C++ projects, you have not only to install and manage your C/C++ compilers, but you also have to install and manage these build systems separately.\nIn Zig, we don’t need to use a separate set of tools to build our projects, because a build system is embedded inside the language itself. We can use this build system to write small scripts in Zig, which describe the necessary steps to build/compile our Zig project1. So, everything you need to build a complex Zig project is the zig compiler, and nothing more.\nThe second generated file (build.zig.zon) is a JSON-like file, in which you can describe your project, and also, declare a set of dependencies of your project that you want to fetch from the internet. In other words, you can use this build.zig.zon file to include a list of external libraries in your project.\nOne possible way to include an external Zig library in your project, is to manually build and install the library in your system, and just link your source code with the library at the build step of your project.\nHowever, if this external Zig library is available on GitHub for example, and it has a valid build.zig.zon file in root folder of the project, which describes the project, you can easily include this library in your project by simply listing this external library in your build.zig.zon file.\nIn other words, this build.zig.zon file works similarly to the package.json file in Javascript projects, or the Pipfile file in Python projects, or the Cargo.toml file in Rust projects. You can read more about this specific file in a couple of articles on the internet23, and you can also see the expected schema for this build.zig.zon file in a documentation file inside the official repository of Zig4.\n\n\n1.2.2 The file root.zig\nLet’s take a look into the root.zig file. You might have noticed that every line of code with an expression ends with a semicolon (;). This follows the syntax of a C-family programming language5.\nAlso, notice the @import() call at the first line. We use this built-in function to import functionality from other Zig modules into our current module. This @import() function works similarly to the #include pre-processor in C or C++, or, to the import statement in Python or Javascript code. In this example, we are importing the std module, which gives you access to the Zig Standard Library.\nIn this root.zig file, we can also see how assignments (i.e., creating new objects) are made in Zig. You can create a new object in Zig by using the syntax (const|var) name = value;. In the example below, we are creating two constant objects (std and testing). In Section 1.4 we talk more about objects in general.\n\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n\nFunctions in Zig are declared using the fn keyword. In this root.zig module, we are declaring a function called add(), which has two arguments named a and b. The function returns an integer of the type i32 as result.\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit the type of an object in your code, if this type can be inferred by the zig compiler (we talk more about that in Section 2.4). But there are other situations where you do need to be explicit. For example, you do have to explicitly specify the type of each function argument, and also, the return type of every function that you create in Zig.\nWe specify the type of an object or a function argument in Zig by using a colon character (:) followed by the type after the name of this object/function argument. With the expressions a: i32 and b: i32, we know that both a and b arguments have type i32, which is a signed 32 bit integer. In this part, the syntax in Zig is identical to the syntax in Rust, which also specifies types by using the colon character.\nLastly, we have the return type of the function at the end of the line, before we open the curly braces to start writing the function’s body. In the example above, this type is also a signed 32 bit integer (i32) value.\nNotice that we also have an export keyword before the function declaration. This keyword is similar to the extern keyword in C. It exposes the function to make it available in the library API. Therefore, if you are writing a library for other people to use, you have to expose the functions you write in the public API of this library by using this export keyword. If we removed the export keyword from the add() function declaration, then, this function would be no longer exposed in the library object built by the zig compiler.\n\n\n1.2.3 The main.zig file\nNow that we have learned a lot about Zig’s syntax from the root.zig file, let’s take a look at the main.zig file. A lot of the elements we saw in root.zig are also present in main.zig. But there are some other elements that we haven’t seen yet, so let’s dive in.\nFirst, look at the return type of the main() function in this file. We can see a small change. The return type of the function (void) is accompanied by an exclamation mark (!). This exclamation mark tells us that this main() function might return an error.\nIt’s worth noting that, a main() function in Zig is allowed to return nothing (void), or an unsigned 8-bit integer (u8) value6, or an error. In other words, you can write your main() function in Zig to return essentially nothing (void), or, if you prefer, you can also write a more C-like main() function, which returns an integer value that usually serves as a “status code” for the process.\nIn this example, the return type annotation of main() indicates that this function can either return nothing (void), or return an error. This exclamation mark in the return type annotation is an interesting and powerful feature of Zig. In summary, if you write a function and something inside the body of this function might return an error, then, you are forced to:\n\neither add the exclamation mark to the return type of the function and make it clear that this function might return an error.\nexplicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through a try catch pattern. Zig does have both try and catch keywords. But they work a little differently than what you’re probably used to in other languages.\nIf we look at the main() function below, you can see that we do have a try keyword on the 5th line. But we do not have a catch keyword in this code. In Zig, we use the try keyword to execute an expression that might return an error, which, in this example, is the stdout.print() expression.\nIn essence, the try keyword executes the expression stdout.print(). If this expression returns a valid value, then, the try keyword does absolutely nothing. It only passes the value forward. It’s like if this try keyword was never there. However, if the expression does return an error, then, the try keyword will unwrap the error value, then, it returns this error from the function and also prints the current stack trace to stderr.\nThis might sound weird to you if you come from a high-level language. Because in high-level languages, such as Python, if an error occurs somewhere, this error is automatically returned and the execution of your program will automatically stop even if you don’t want to stop the execution. You are obligated to face the error.\n\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n\nAnother thing that you might have noticed in this code example, is that the main() function is marked with the pub keyword. It marks the main() function as a public function from this module. Every function in your Zig module is by default private to this Zig module and can only be called from within the module. Unless, you explicitly mark this function as a public function with the pub keyword.\nIf you think about it, this pub keyword in Zig does essentially the opposite of what the static keyword do in C/C++. By making a function “public” you allow other Zig modules to access and call this function. A calling Zig module imports another module by using the @import() built-in function, which makes all public functions from the imported module visible to the calling Zig module.\n\n\n1.2.4 Compiling your source code\nYou can compile your Zig modules into a binary executable by running the build-exe command from the zig compiler. You simply list all the Zig modules that you want to build after the build-exe command, separated by spaces. In the example below, we are compiling the module main.zig.\nzig build-exe src/main.zig\nSince we are building an executable, the zig compiler will look for a main() function declared in any of the files that you list after the build-exe command. If the compiler does not find a main() function declared somewhere, a compilation error will be raised, warning about this mistake.\nThe zig compiler also offers a build-lib and build-obj commands, which work the exact same way as the build-exe command. The only difference is that, they compile your Zig modules into a portable C ABI library, or, into object files, respectively.\nIn the case of the build-exe command, a binary executable file is created by the zig compiler in the root directory of your project. If we take a look now at the contents of our current directory, with a simple ls command, we can see the binary file called main that was created by the compiler.\nls\nbuild.zig  build.zig.zon  main  src\nIf I execute this binary executable, I get the “Hello World” message in the terminal , as we expected.\n./main\nHello, world!\n\n\n1.2.5 Compile and execute at the same time\nIn the previous section, I presented the zig build-exe command, which compiles Zig modules into an executable file. However, this means that, in order to execute the executable file, we have to run two different commands. First, the zig build-exe command, and then, we call the executable file created by the compiler.\nBut what if we wanted to perform these two steps, all at once, in a single command? We can do that by using the zig run command.\nzig run src/main.zig\nHello, world!\n\n\n1.2.6 Important note for Windows users\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other operating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that includes some global variables whose initialization rely on runtime resources, then, you might have some troubles while trying to compile this Zig code on Windows.\nAn example of that is accessing the stdout (i.e., the standard output of your system), which is usually done in Zig by using the expression std.io.getStdOut(). If you use this expression to instantiate a global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows, with an “unable to evaluate comptime expression” error message.\nThis failure in the compilation process happens because all global variables in Zig are initialized at compile-time. However, on Windows, operations like accessing the stdout (or opening a file) depend on resources that are available only at runtime (you will learn more about compile-time versus runtime in Section 3.1.1).\nFor example, if you try to compile this code example on Windows, you will likely get the error message exposed below:\n\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerges from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\nTo avoid this problem on Windows, we need to force the zig compiler to instantiate this stdout object only at runtime, instead of instantiating it at compile-time. We can achieve that by simply moving the expression to a function body.\nThis solves the problem because all expressions that are inside a function body in Zig are evaluated only at runtime, unless you use the comptime keyword explicitly to change this behaviour. You will learn more about this comptime keyword in Section 12.1.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nHello\nYou can read more details about this Windows-specific limitation in a couple of GitHub issues opened at the official Zig repository. More specifically, the issues\n17186 7 and 19864 8.\n\n\n1.2.7 Compiling the entire project\nJust as I described in Section 1.2.1, as our project grows in size and complexity, we usually prefer to organize the compilation and build process of the project into a build script, using some sort of “build system”.\nIn other words, as our project grows in size and complexity, the build-exe, build-lib and build-obj commands become harder to use directly. Because then, we start to list multiple and multiple modules at the same time. We also start to add built-in compilation flags to customize the build process for our needs, etc. It becomes a lot of work to write the necessary commands by hand.\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, Makefile or configure scripts to organize this process. However, in Zig, we have a native build system in the language itself. So, we can write build scripts in Zig to compile and build Zig projects. Then, all we need to do, is to call the zig build command to build our project.\nSo, when you execute the zig build command, the zig compiler will search for a Zig module named build.zig inside your current directory, which should be your build script, containing the necessary code to compile and build your project. If the compiler does find this build.zig file in your directory, then, the compiler will essentially execute a zig run command over this build.zig file, to compile and execute this build script, which in turn, will compile and build your entire project.\nzig build\nAfter you execute this “build project” command, a zig-out directory is created in the root of your project directory, where you can find the binary executables and libraries created from your Zig modules accordingly to the build commands that you specified at build.zig. We will talk more about the build system in Zig later in this book.\nIn the example below, I’m executing the binary executable named hello_world that was generated by the compiler after the zig build command.\n./zig-out/bin/hello_world\nHello, world!",
+    "text": "1.2 Hello world in Zig\nWe begin our journey in Zig by creating a small “Hello World” program. To start a new Zig project in your computer, you simply call the init command from the zig compiler. Just create a new directory in your computer, then, init a new Zig project inside this directory, like this:\nmkdir hello_world\ncd hello_world\nzig init\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n\n1.2.1 Understanding the project files\nAfter you run the init command from the zig compiler, some new files are created inside of your current directory. First, a “source” (src) directory is created, containing two files, main.zig and root.zig. Each .zig file is a separate Zig module, which is simply a text file that contains some Zig code.\nBy convention, the main.zig module is where your main function lives. Thus, if you are building an executable program in Zig, you need to declare a main() function, which represents the entrypoint of your program, i.e., where the execution of your program begins.\nHowever, if you are building a library (instead of an executable program), then, the normal procedure is to delete this main.zig file and start with the root.zig module. By convention, the root.zig module is the root source file of your library.\ntree .\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\nThe init command also creates two additional files in our working directory: build.zig and build.zig.zon. The first file (build.zig) represents a build script written in Zig. This script is executed when you call the build command from the zig compiler. In other words, this file contains Zig code that executes the necessary steps to build the entire project.\nLow-level languages normally use a compiler to build your source code into binary executables or binary libraries. Nevertheless, this process of compiling your source code and building binary executables or binary libraries from it, became a real challenge in the programming world, once the projects became bigger and bigger. As a result, programmers created “build systems”, which are a second set of tools designed to make this process of compiling and building complex projects, easier.\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja, which are used to build complex C and C++ projects. With these systems, you can write scripts, which are called “build scripts”. They simply are scripts that describes the necessary steps to compile/build your project.\nHowever, these are separate tools, that do not belong to C/C++ compilers, like gcc or clang. As a result, in C/C++ projects, you have not only to install and manage your C/C++ compilers, but you also have to install and manage these build systems separately.\nIn Zig, we don’t need to use a separate set of tools to build our projects, because a build system is embedded inside the language itself. We can use this build system to write small scripts in Zig, which describe the necessary steps to build/compile our Zig project1. So, everything you need to build a complex Zig project is the zig compiler, and nothing more.\nThe second generated file (build.zig.zon) is a JSON-like file, in which you can describe your project, and also, declare a set of dependencies of your project that you want to fetch from the internet. In other words, you can use this build.zig.zon file to include a list of external libraries in your project.\nOne possible way to include an external Zig library in your project, is to manually build and install the library in your system, and just link your source code with the library at the build step of your project.\nHowever, if this external Zig library is available on GitHub for example, and it has a valid build.zig.zon file in root folder of the project, which describes the project, you can easily include this library in your project by simply listing this external library in your build.zig.zon file.\nIn other words, this build.zig.zon file works similarly to the package.json file in Javascript projects, or the Pipfile file in Python projects, or the Cargo.toml file in Rust projects. You can read more about this specific file in a couple of articles on the internet23, and you can also see the expected schema for this build.zig.zon file in a documentation file inside the official repository of Zig4.\n\n\n1.2.2 The file root.zig\nLet’s take a look into the root.zig file. You might have noticed that every line of code with an expression ends with a semicolon (;). This follows the syntax of a C-family programming language5.\nAlso, notice the @import() call at the first line. We use this built-in function to import functionality from other Zig modules into our current module. This @import() function works similarly to the #include pre-processor in C or C++, or, to the import statement in Python or Javascript code. In this example, we are importing the std module, which gives you access to the Zig Standard Library.\nIn this root.zig file, we can also see how assignments (i.e., creating new objects) are made in Zig. You can create a new object in Zig by using the syntax (const|var) name = value;. In the example below, we are creating two constant objects (std and testing). In Section 1.4 we talk more about objects in general.\n\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n\nFunctions in Zig are declared using the fn keyword. In this root.zig module, we are declaring a function called add(), which has two arguments named a and b. The function returns an integer of the type i32 as result.\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit the type of an object in your code, if this type can be inferred by the zig compiler (we talk more about that in Section 2.4). But there are other situations where you do need to be explicit. For example, you do have to explicitly specify the type of each function argument, and also, the return type of every function that you create in Zig.\nWe specify the type of an object or a function argument in Zig by using a colon character (:) followed by the type after the name of this object/function argument. With the expressions a: i32 and b: i32, we know that both a and b arguments have type i32, which is a signed 32 bit integer. In this part, the syntax in Zig is identical to the syntax in Rust, which also specifies types by using the colon character.\nLastly, we have the return type of the function at the end of the line, before we open the curly braces to start writing the function’s body. In the example above, this type is also a signed 32 bit integer (i32) value.\nNotice that we also have an export keyword before the function declaration. This keyword is similar to the extern keyword in C. It exposes the function to make it available in the library API. Therefore, if you are writing a library for other people to use, you have to expose the functions you write in the public API of this library by using this export keyword. If we removed the export keyword from the add() function declaration, then, this function would be no longer exposed in the library object built by the zig compiler.\n\n\n1.2.3 The main.zig file\nNow that we have learned a lot about Zig’s syntax from the root.zig file, let’s take a look at the main.zig file. A lot of the elements we saw in root.zig are also present in main.zig. But there are some other elements that we haven’t seen yet, so let’s dive in.\nFirst, look at the return type of the main() function in this file. We can see a small change. The return type of the function (void) is accompanied by an exclamation mark (!). This exclamation mark tells us that this main() function might return an error.\nIt’s worth noting that, a main() function in Zig is allowed to return nothing (void), or an unsigned 8-bit integer (u8) value6, or an error. In other words, you can write your main() function in Zig to return essentially nothing (void), or, if you prefer, you can also write a more C-like main() function, which returns an integer value that usually serves as a “status code” for the process.\nIn this example, the return type annotation of main() indicates that this function can either return nothing (void), or return an error. This exclamation mark in the return type annotation is an interesting and powerful feature of Zig. In summary, if you write a function and something inside the body of this function might return an error, then, you are forced to:\n\neither add the exclamation mark to the return type of the function and make it clear that this function might return an error.\nexplicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through a try catch pattern. Zig does have both try and catch keywords. But they work a little differently than what you’re probably used to in other languages.\nIf we look at the main() function below, you can see that we do have a try keyword on the 5th line. But we do not have a catch keyword in this code. In Zig, we use the try keyword to execute an expression that might return an error, which, in this example, is the stdout.print() expression.\nIn essence, the try keyword executes the expression stdout.print(). If this expression returns a valid value, then, the try keyword does absolutely nothing. It only passes the value forward. It’s like if this try keyword was never there. However, if the expression does return an error, then, the try keyword will unwrap the error value, then, it returns this error from the function and also prints the current stack trace to stderr.\nThis might sound weird to you if you come from a high-level language. Because in high-level languages, such as Python, if an error occurs somewhere, this error is automatically returned and the execution of your program will automatically stop even if you don’t want to stop the execution. You are obligated to face the error.\n\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n\nAnother thing that you might have noticed in this code example, is that the main() function is marked with the pub keyword. It marks the main() function as a public function from this module. Every function in your Zig module is by default private to this Zig module and can only be called from within the module. Unless, you explicitly mark this function as a public function with the pub keyword.\nIf you think about it, this pub keyword in Zig does essentially the opposite of what the static keyword do in C/C++. By making a function “public” you allow other Zig modules to access and call this function. A calling Zig module imports another module by using the @import() built-in function, which makes all public functions from the imported module visible to the calling Zig module.\n\n\n1.2.4 Compiling your source code\nYou can compile your Zig modules into a binary executable by running the build-exe command from the zig compiler. You simply list all the Zig modules that you want to build after the build-exe command, separated by spaces. In the example below, we are compiling the module main.zig.\nzig build-exe src/main.zig\nSince we are building an executable, the zig compiler will look for a main() function declared in any of the files that you list after the build-exe command. If the compiler does not find a main() function declared somewhere, a compilation error will be raised, warning about this mistake.\nThe zig compiler also offers a build-lib and build-obj commands, which work the exact same way as the build-exe command. The only difference is that, they compile your Zig modules into a portable C ABI library, or, into object files, respectively.\nIn the case of the build-exe command, a binary executable file is created by the zig compiler in the root directory of your project. If we take a look now at the contents of our current directory, with a simple ls command, we can see the binary file called main that was created by the compiler.\nls\nbuild.zig  build.zig.zon  main  src\nIf I execute this binary executable, I get the “Hello World” message in the terminal , as we expected.\n./main\nHello, world!\n\n\n1.2.5 Compile and execute at the same time\nIn the previous section, I presented the zig build-exe command, which compiles Zig modules into an executable file. However, this means that, in order to execute the executable file, we have to run two different commands. First, the zig build-exe command, and then, we call the executable file created by the compiler.\nBut what if we wanted to perform these two steps, all at once, in a single command? We can do that by using the zig run command.\nzig run src/main.zig\nHello, world!\n\n\n1.2.6 Important note for Windows users\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other operating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that includes some global variables whose initialization rely on runtime resources, then, you might have some troubles while trying to compile this Zig code on Windows.\nAn example of that is accessing the stdout (i.e., the standard output of your system), which is usually done in Zig by using the expression std.io.getStdOut(). If you use this expression to instantiate a global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows, with an “unable to evaluate comptime expression” error message.\nThis failure in the compilation process happens because all global variables in Zig are initialized at compile-time. However, on Windows, operations like accessing the stdout (or opening a file) depend on resources that are available only at runtime (you will learn more about compile-time versus runtime in Section 3.1.1).\nFor example, if you try to compile this code example on Windows, you will likely get the error message exposed below:\n\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerges from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\nTo avoid this problem on Windows, we need to force the zig compiler to instantiate this stdout object only at runtime, instead of instantiating it at compile-time. We can achieve that by simply moving the expression to a function body.\nThis solves the problem because all expressions that are inside a function body in Zig are evaluated only at runtime, unless you use the comptime keyword explicitly to change this behaviour. You will learn more about this comptime keyword in Section 12.1.\n\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n\nHello\nYou can read more details about this Windows-specific limitation in a couple of GitHub issues opened at the official Zig repository. More specifically, the issues 17186 7 and 19864 8.\n\n\n1.2.7 Compiling the entire project\nJust as I described in Section 1.2.1, as our project grows in size and complexity, we usually prefer to organize the compilation and build process of the project into a build script, using some sort of “build system”.\nIn other words, as our project grows in size and complexity, the build-exe, build-lib and build-obj commands become harder to use directly. Because then, we start to list multiple and multiple modules at the same time. We also start to add built-in compilation flags to customize the build process for our needs, etc. It becomes a lot of work to write the necessary commands by hand.\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, Makefile or configure scripts to organize this process. However, in Zig, we have a native build system in the language itself. So, we can write build scripts in Zig to compile and build Zig projects. Then, all we need to do, is to call the zig build command to build our project.\nSo, when you execute the zig build command, the zig compiler will search for a Zig module named build.zig inside your current directory, which should be your build script, containing the necessary code to compile and build your project. If the compiler does find this build.zig file in your directory, then, the compiler will essentially execute a zig run command over this build.zig file, to compile and execute this build script, which in turn, will compile and build your entire project.\nzig build\nAfter you execute this “build project” command, a zig-out directory is created in the root of your project directory, where you can find the binary executables and libraries created from your Zig modules accordingly to the build commands that you specified at build.zig. We will talk more about the build system in Zig later in this book.\nIn the example below, I’m executing the binary executable named hello_world that was generated by the compiler after the zig build command.\n./zig-out/bin/hello_world\nHello, world!",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -154,7 +154,7 @@
     "href": "Chapters/01-zig-weird.html#sec-primitive-data-types",
     "title": "1  Introducing Zig",
     "section": "1.5 Primitive Data Types",
-    "text": "1.5 Primitive Data Types\nZig have many different primitive data types available for you to use. You can see the full list of available data types at the official Language Reference page21.\nBut here is a quick list:\n\nUnsigned integers: u8, 8-bit integer; u16, 16-bit integer; u32, 32-bit integer; u64, 64-bit integer; u128, 128-bit integer.\nSigned integers: i8, 8-bit integer; i16, 16-bit integer; i32, 32-bit integer; i64, 64-bit integer; i128, 128-bit integer.\nFloat number: f16, 16-bit floating point; f32, 32-bit floating point; f64, 64-bit floating point; f128, 128-bit floating point;\nBoolean: bool, represents true or false values.\nC ABI compatible types: c_long, c_char, c_short, c_ushort, c_int, c_uint, and many others.\nPointer sized integers: isize and usize.",
+    "text": "1.5 Primitive Data Types\nZig has many different primitive data types available for you to use. You can see the full list of available data types at the official Language Reference page21.\nBut here is a quick list:\n\nUnsigned integers: u8, 8-bit integer; u16, 16-bit integer; u32, 32-bit integer; u64, 64-bit integer; u128, 128-bit integer.\nSigned integers: i8, 8-bit integer; i16, 16-bit integer; i32, 32-bit integer; i64, 64-bit integer; i128, 128-bit integer.\nFloat number: f16, 16-bit floating point; f32, 32-bit floating point; f64, 64-bit floating point; f128, 128-bit floating point;\nBoolean: bool, represents true or false values.\nC ABI compatible types: c_long, c_char, c_short, c_ushort, c_int, c_uint, and many others.\nPointer sized integers: isize and usize.",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -164,7 +164,7 @@
     "href": "Chapters/01-zig-weird.html#sec-arrays",
     "title": "1  Introducing Zig",
     "section": "1.6 Arrays",
-    "text": "1.6 Arrays\nYou create arrays in Zig by using a syntax that resembles the C syntax. First, you specify the size of the array (i.e., the number of elements that will be stored in the array) you want to create inside a pair of brackets.\nThen, you specify the data type of the elements that will be stored inside this array. All elements present in an array in Zig must have the same data type. For example, you cannot mix elements of type f32 with elements of type i32 in the same array.\nAfter that, you simply list the values that you want to store in this array inside a pair of curly braces. In the example below, I am creating two constant objects that contain different arrays. The first object contains an array of 4 integer values, while the second object, an array of 3 floating point values.\nNow, you should notice that in the object ls, I am not explicitly specifying the size of the array inside of the brackets. Instead of using a literal value (like the value 4 that I used in the ns object), I am using the special character underscore (_). This syntax tells the zig compiler to fill this field with the number of elements listed inside of the curly braces. So, this syntax [_] is for lazy (or smart) programmers who leave the job of counting how many elements there are in the curly braces for the compiler.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n\nIt’s worth noting that these are static arrays, meaning that they cannot grow in size. Once you declare your array, you cannot change the size of it. This is very common in low level languages. Because low level languages normally wants to give you (the programmer) full control over memory, and the way in which arrays are expanded is tightly related to memory management.\n\n1.6.1 Selecting elements of the array\nOne very common activity is to select specific portions of an array you have in your source code. In Zig, you can select a specific element from your array, by simply providing the index of this particular element inside brackets after the object name. In the example below, I am selecting the third element from the ns array. Notice that Zig is a “zero-index” based language, like C, C++, Rust, Python, and many other languages.\n\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n\n12\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a range selector. Some programmers also call these selectors of “slice selectors”, and they also exist in Rust, and have the exact same syntax as in Zig. Anyway, a range selector is a special expression in Zig that defines a range of indexes, and it have the syntax start..end.\nIn the example below, at the second line of code, the sl object stores a slice (or a portion) of the ns array. More precisely, the elements at index 1 and 2 in the ns array.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n\nWhen you use the start..end syntax, the “end tail” of the range selector is non-inclusive, meaning that, the index at the end is not included in the range that is selected from the array. Therefore, the syntax start..end actually means start..end - 1 in practice.\nYou can for example, create a slice that goes from the first to the last elements of the array, by using ar[0..ar.len] syntax In other words, it’s a slice that accesses all elements in the array.\n\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n\nYou can also use the syntax start.. in your range selector. Which tells the zig compiler to select the portion of the array that begins at the start index until the last element of the array. In the example below, we are selecting the range from index 1 until the end of the array.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n\n\n\n1.6.2 More on slices\nAs we discussed before, in Zig, you can select specific portions of an existing array. This is called slicing in Zig (Sobeston 2024), because when you select a portion of an array, you are creating a slice object from that array.\nA slice object is essentially a pointer object accompanied by a length number. The pointer object points to the first element in the slice, and the length number tells the zig compiler how many elements there are in this slice.\n\nSlices can be thought of as a pair of [*]T (the pointer to the data) and a usize (the element count) (Sobeston 2024).\n\nThrough the pointer contained inside the slice you can access the elements (or values) that are inside this range (or portion) that you selected from the original array. But the length number (which you can access through the len property of your slice object) is the really big improvement (over C arrays for example) that Zig brings to the table here.\nBecause with this length number the zig compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice, or, if you are causing any buffer overflow problems. In the example below, we access the len property of the slice sl, which tells us that this slice have 2 elements in it.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n\n2\n\n\n\n\n1.6.3 Array operators\nThere are two array operators available in Zig that are very useful. The array concatenation operator (++), and the array multiplication operator (**). As the name suggests, these are array operators.\nOne important detail about these two operators is that they work only when both operands have a size (or “length”) that is compile-time known. We are going to talk more about the differences between “compile-time known” and “runtime known” in Section 3.1.1. But for now, keep this information in mind, that you cannot use these operators in every situation.\nIn summary, the ++ operator creates a new array that is the concatenation, of both arrays provided as operands. So, the expression a ++ b produces a new array which contains all the elements from arrays a and b.\n\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n\n{ 1, 2, 3, 4, 5 }\n\n\nThis ++ operator is particularly useful to concatenate strings together. Strings in Zig are described in depth in Section 1.8. In summary, a string object in Zig is essentially an arrays of bytes. So, you can use this array concatenation operator to effectively concatenate strings together.\nIn contrast, the ** operator is used to replicate an array multiple times. In other words, the expression a ** 3 creates a new array which contains the elements of the array a repeated 3 times.\n\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n\n{ 1, 2, 3, 1, 2, 3 }\n\n\n\n\n1.6.4 Runtime versus compile-time known length in slices\nWe are going to talk a lot about the differences between compile-time known and runtime known across this book, especially in Section 3.1.1. But the basic idea is that a thing is compile-time known, when we know everything (the value, the attributes and the characteristics) about this thing at compile-time. In contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime. Therefore, we don’t know the value of this thing at compile-time, only at runtime.\nWe have learned in Section 1.6.1 that slices are created by using a range selector, which represents a range of indexes. When this “range of indexes” (i.e., both the start and the end of this range) is known at compile-time, the slice object that gets created is actually, under the hood, just a single-item pointer to an array.\nYou don’t need to precisely understand what that means now. We are going to talk a lot about pointers in Chapter 6. For now, just understand that, when the range of indexes is known at compile-time, the slice that gets created is just a pointer to an array, accompanied by a length value that tells the size of the slice.\nIf you have a slice object like this, i.e., a slice that has a compile-time known range, you can use common pointer operations over this slice object. For example, you can dereference the pointer of this slice, by using the .* method, like you would do on a normal pointer object.\n\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice have a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n_ = slice;\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object that gets created is not a pointer anymore, and, thus, it does not support pointer operations. For example, maybe the start index is known at compile time, but the end index is not. In such case, the range of the slice becomes runtime known only.\nIn the example below, we are reading a file, and then, we try to create a slice object that covers the entire buffer that contains the contents of this file. This is obviously an example of a runtime known range, because the end index of the range is not known at compile time.\nIn other words, the end index of the range is the size of the array file_contents. However, the size of file_contents is not known at compile time. Because we don’t know how many bytes are stored inside this shop-list.txt file. And because this is a file, someone might edit this file tomorrow and add more lines or remove lines from it. Therefore, the size of this file might vary drastically from one execution to another.\nNow, if the file size can vary from one run to another, then, we can conclude that the value of the expression file_contents.len exposed in the example below can also vary from one run to another. As consequence, the value of the expression file_contents.len is runtime-known only, and, as a consequence of that, the range 0..file_contents.len is also runtime-known only.\n\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\nfn read_file(allocator: std.mem.Allocator, path: []const u8) ![]u8 {\n    const file = try std.fs.cwd().openFile(path, .{});\n    defer file.close();\n    return try file.reader().readAllAlloc(\n        allocator, std.math.maxInt(usize)\n    );\n}\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const path = \"../ZigExamples/file-io/shop-list.txt\";\n    const file_contents = try read_file(allocator, path);\n    const slice = file_contents[0..file_contents.len];\n    _ = slice;\n}",
+    "text": "1.6 Arrays\nYou create arrays in Zig by using a syntax that resembles the C syntax. First, you specify the size of the array (i.e., the number of elements that will be stored in the array) you want to create inside a pair of brackets.\nThen, you specify the data type of the elements that will be stored inside this array. All elements present in an array in Zig must have the same data type. For example, you cannot mix elements of type f32 with elements of type i32 in the same array.\nAfter that, you simply list the values that you want to store in this array inside a pair of curly braces. In the example below, I am creating two constant objects that contain different arrays. The first object contains an array of 4 integer values, while the second object, an array of 3 floating point values.\nNow, you should notice that in the object ls, I am not explicitly specifying the size of the array inside of the brackets. Instead of using a literal value (like the value 4 that I used in the ns object), I am using the special character underscore (_). This syntax tells the zig compiler to fill this field with the number of elements listed inside of the curly braces. So, this syntax [_] is for lazy (or smart) programmers who leave the job of counting how many elements there are in the curly braces for the compiler.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n\nIt’s worth noting that these are static arrays, meaning that they cannot grow in size. Once you declare your array, you cannot change the size of it. This is very common in low level languages. Because low level languages normally wants to give you (the programmer) full control over memory, and the way in which arrays are expanded is tightly related to memory management.\n\n1.6.1 Selecting elements of the array\nOne very common activity is to select specific portions of an array you have in your source code. In Zig, you can select a specific element from your array, by simply providing the index of this particular element inside brackets after the object name. In the example below, I am selecting the third element from the ns array. Notice that Zig is a “zero-index” based language, like C, C++, Rust, Python, and many other languages.\n\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n\n12\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a range selector. Some programmers also call these selectors of “slice selectors”, and they also exist in Rust, and have the exact same syntax as in Zig. Anyway, a range selector is a special expression in Zig that defines a range of indexes, and it has the syntax start..end.\nIn the example below, at the second line of code, the sl object stores a slice (or a portion) of the ns array. More precisely, the elements at index 1 and 2 in the ns array.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n\nWhen you use the start..end syntax, the “end tail” of the range selector is non-inclusive, meaning that, the index at the end is not included in the range that is selected from the array. Therefore, the syntax start..end actually means start..end - 1 in practice.\nYou can for example, create a slice that goes from the first to the last elements of the array, by using ar[0..ar.len] syntax In other words, it’s a slice that accesses all elements in the array.\n\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n\nYou can also use the syntax start.. in your range selector. Which tells the zig compiler to select the portion of the array that begins at the start index until the last element of the array. In the example below, we are selecting the range from index 1 until the end of the array.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n\n\n\n1.6.2 More on slices\nAs we discussed before, in Zig, you can select specific portions of an existing array. This is called slicing in Zig (Sobeston 2024), because when you select a portion of an array, you are creating a slice object from that array.\nA slice object is essentially a pointer object accompanied by a length number. The pointer object points to the first element in the slice, and the length number tells the zig compiler how many elements there are in this slice.\n\nSlices can be thought of as a pair of [*]T (the pointer to the data) and a usize (the element count) (Sobeston 2024).\n\nThrough the pointer contained inside the slice you can access the elements (or values) that are inside this range (or portion) that you selected from the original array. But the length number (which you can access through the len property of your slice object) is the really big improvement (over C arrays for example) that Zig brings to the table here.\nBecause with this length number the zig compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice, or, if you are causing any buffer overflow problems. In the example below, we access the len property of the slice sl, which tells us that this slice has 2 elements in it.\n\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n\n2\n\n\n\n\n1.6.3 Array operators\nThere are two array operators available in Zig that are very useful. The array concatenation operator (++), and the array multiplication operator (**). As the name suggests, these are array operators.\nOne important detail about these two operators is that they work only when both operands have a size (or “length”) that is compile-time known. We are going to talk more about the differences between “compile-time known” and “runtime known” in Section 3.1.1. But for now, keep this information in mind, that you cannot use these operators in every situation.\nIn summary, the ++ operator creates a new array that is the concatenation, of both arrays provided as operands. So, the expression a ++ b produces a new array which contains all the elements from arrays a and b.\n\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n\n{ 1, 2, 3, 4, 5 }\n\n\nThis ++ operator is particularly useful to concatenate strings together. Strings in Zig are described in depth in Section 1.8. In summary, a string object in Zig is essentially an arrays of bytes. So, you can use this array concatenation operator to effectively concatenate strings together.\nIn contrast, the ** operator is used to replicate an array multiple times. In other words, the expression a ** 3 creates a new array which contains the elements of the array a repeated 3 times.\n\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n\n{ 1, 2, 3, 1, 2, 3 }\n\n\n\n\n1.6.4 Runtime versus compile-time known length in slices\nWe are going to talk a lot about the differences between compile-time known and runtime known across this book, especially in Section 3.1.1. But the basic idea is that a thing is compile-time known, when we know everything (the value, the attributes and the characteristics) about this thing at compile-time. In contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime. Therefore, we don’t know the value of this thing at compile-time, only at runtime.\nWe have learned in Section 1.6.1 that slices are created by using a range selector, which represents a range of indexes. When this “range of indexes” (i.e., both the start and the end of this range) is known at compile-time, the slice object that gets created is actually, under the hood, just a single-item pointer to an array.\nYou don’t need to precisely understand what that means now. We are going to talk a lot about pointers in Chapter 6. For now, just understand that, when the range of indexes is known at compile-time, the slice that gets created is just a pointer to an array, accompanied by a length value that tells the size of the slice.\nIf you have a slice object like this, i.e., a slice that has a compile-time known range, you can use common pointer operations over this slice object. For example, you can dereference the pointer of this slice, by using the .* method, like you would do on a normal pointer object.\n\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice has a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n_ = slice;\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object that gets created is not a pointer anymore, and, thus, it does not support pointer operations. For example, maybe the start index is known at compile time, but the end index is not. In such case, the range of the slice becomes runtime known only.\nIn the example below, we are reading a file, and then, we try to create a slice object that covers the entire buffer that contains the contents of this file. This is obviously an example of a runtime known range, because the end index of the range is not known at compile time.\nIn other words, the end index of the range is the size of the array file_contents. However, the size of file_contents is not known at compile time. Because we don’t know how many bytes are stored inside this shop-list.txt file. And because this is a file, someone might edit this file tomorrow and add more lines or remove lines from it. Therefore, the size of this file might vary drastically from one execution to another.\nNow, if the file size can vary from one run to another, then, we can conclude that the value of the expression file_contents.len exposed in the example below can also vary from one run to another. As consequence, the value of the expression file_contents.len is runtime-known only, and, as a consequence of that, the range 0..file_contents.len is also runtime-known only.\n\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\nfn read_file(allocator: std.mem.Allocator, path: []const u8) ![]u8 {\n    const file = try std.fs.cwd().openFile(path, .{});\n    defer file.close();\n    return try file.reader().readAllAlloc(\n        allocator, std.math.maxInt(usize)\n    );\n}\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const path = \"../ZigExamples/file-io/shop-list.txt\";\n    const file_contents = try read_file(allocator, path);\n    const slice = file_contents[0..file_contents.len];\n    _ = slice;\n}",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -174,7 +174,7 @@
     "href": "Chapters/01-zig-weird.html#sec-blocks",
     "title": "1  Introducing Zig",
     "section": "1.7 Blocks and scopes",
-    "text": "1.7 Blocks and scopes\nBlocks are created in Zig by a pair of curly braces. A block is just a group of expressions (or statements) contained inside of a pair of curly braces. All of these expressions that are contained inside of this pair of curly braces belongs to the same scope.\nIn other words, a block just delimits a scope in your code. The objects that you define inside the same block belongs to the same scope, and, therefore, are accessible from within this scope. At the same time, these objects are not accessible outside of this scope. So, you could also say that blocks are used to limit the scope of the objects that you create in your source code. In less technical terms, blocks are used to specify where in your source code you can access whatever object you have in your source code.\nSo, a block is just a group of expressions contained inside a pair of curly braces. And every block have its own scope separated from the others. The body of a function is a classic example of a block. If statements, for and while loops (and any other structure in the language that uses the pair of curly braces) are also examples of blocks.\nThis means that, every if statement, or for loop, etc., that you create in your source code have its own separate scope. That is why you can’t access the objects that you defined inside of your for loop (or if statement) in an outer scope, i.e., a scope outside of the for loop. Because you are trying to access an object that belongs to a scope that is different than your current scope.\nYou can create blocks within blocks, with multiple levels of nesting. You can also (if you want to) give a label to a particular block, with the colon character (:). Just write label: before you open the pair of curly braces that delimits your block. When you label a block in Zig, you can use the break keyword to return a value from this block, like as if it was a function’s body. You just write the break keyword, followed by the block label in the format :label, and the expression that defines the value that you want to return.\nLike in the example below, where we are returning the value from the y object from the block add_one, and saving the result inside the x object.\n\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n\nHey!",
+    "text": "1.7 Blocks and scopes\nBlocks are created in Zig by a pair of curly braces. A block is just a group of expressions (or statements) contained inside of a pair of curly braces. All of these expressions that are contained inside of this pair of curly braces belongs to the same scope.\nIn other words, a block just delimits a scope in your code. The objects that you define inside the same block belongs to the same scope, and, therefore, are accessible from within this scope. At the same time, these objects are not accessible outside of this scope. So, you could also say that blocks are used to limit the scope of the objects that you create in your source code. In less technical terms, blocks are used to specify where in your source code you can access whatever object you have in your source code.\nSo, a block is just a group of expressions contained inside a pair of curly braces. And every block have its own scope separated from the others. The body of a function is a classic example of a block. If statements, for and while loops (and any other structure in the language that uses the pair of curly braces) are also examples of blocks.\nThis means that, every if statement, or for loop, etc., that you create in your source code has its own separate scope. That is why you can’t access the objects that you defined inside of your for loop (or if statement) in an outer scope, i.e., a scope outside of the for loop. Because you are trying to access an object that belongs to a scope that is different than your current scope.\nYou can create blocks within blocks, with multiple levels of nesting. You can also (if you want to) give a label to a particular block, with the colon character (:). Just write label: before you open the pair of curly braces that delimits your block. When you label a block in Zig, you can use the break keyword to return a value from this block, like as if it was a function’s body. You just write the break keyword, followed by the block label in the format :label, and the expression that defines the value that you want to return.\nLike in the example below, where we are returning the value from the y object from the block add_one, and saving the result inside the x object.\n\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n\nHey!",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]
@@ -184,7 +184,7 @@
     "href": "Chapters/01-zig-weird.html#sec-zig-strings",
     "title": "1  Introducing Zig",
     "section": "1.8 How strings work in Zig?",
-    "text": "1.8 How strings work in Zig?\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (Chapter 4). But in order for us to build such a thing, we need to get a better understanding on how strings work in Zig. So let’s discuss this specific aspect of Zig.\nStrings in Zig work very similarly to strings in C, but they come with some extra caveats which adds more safety and efficiency to them. You could also say that Zig simply uses a more modern and safe approach to manage and use strings.\nA string in Zig is essentially an array of arbitrary bytes, or, more specifically, an array of u8 values. This very similar to a string in C, which is also interpreted as an array of arbitrary bytes, or, in the case of C, an array of char (which usually represents an unsigned 8-bit integer value in most systems) values.\nNow, because a string in Zig is an array, you automatically get the length of the string (i.e. the length of the array) embedded in the value itself. This makes all the difference! Because now, the Zig compiler can use the length value that is embedded in the string to check for “buffer overflow” or “wrong memory access” problems in your code.\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless. So getting this kind of safety is not automatic and much harder to do in C. For example, if you want to track the length of your string throughout your program in C, then, you first need to loop through the array of bytes that represents this string, and find the null element ('\\0') position to discover where exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\nTo do that, you would need to do something like this in C. In this example, the C string stored in the object array is 25 bytes long:\n\n#include &lt;stdio.h&gt;\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n\nNumber of elements in the array: 25\nYou don’t have this kind of work in Zig. Because the length of the string is always present and accessible in the string value itself. You can easily access the length of the string through the len attribute. As an example, the string_object object below is 43 bytes long:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n\n43\n\n\nAnother point is that Zig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every sequence of bytes you’re working with, but is not really Zig’s job to fix the encoding of your strings (you can use iconv22 for that). Today, most of the text in our modern world, especially on the web, should be UTF-8 encoded. So if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\nLet’s take for example the word “Hello”. In UTF-8, this sequence of characters (H, e, l, l, o) is represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this sequence is 0x48, 0x65, 0x6C, 0x6C, 0x6F. So if I take this sequence of hexadecimal values, and ask Zig to print this sequence of bytes as a sequence of characters (i.e., a string), then, the text “Hello” will be printed into the terminal:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n\nHello\n\n\n\n1.8.1 Using a slice versus a sentinel-terminated array\nIn memory, all string values in Zig are always stored in the same way. They are simply stored as sequences/arrays of arbitrary bytes. But you can use and access this sequence of bytes in two different ways. You can access this sequence of bytes as:\n\na sentinel-terminated array of u8 values.\nor as a slice of u8 values.\n\n\n1.8.1.1 Sentinel-terminated arrays\nSentinel-terminated arrays in Zig are described in the Language Reference of Zig23. In summary a sentinel-terminated array is just a normal array, but, the difference is that they contain a “sentinel value” at the last index/element of the array. With a sentinel-terminated array you embed both the length of the array, and also, the sentinel value in the type itself of your object.\nFor example, if you write a string literal value in your code, and ask Zig to print the data type of this value, you usually get a data type in the format *const [n:0]u8. The n in the data type indicates the size of the string (that is the length of the array). The zero after the n: part of the data type is the sentinel value itself.\n\n// This is a string literal value:\n_ = \"A literal value\";\ntry stdout.print(\"{any}\\n\", .{@TypeOf(\"A literal value\")});\n\n*const [15:0]u8\n\n\nSo, with this data type *const [n:0]u8 you are essentially saying that you have an array of u8 values of length n, where, the element at the index corresponding to the length n in the array is the number zero. If you really think about this description, you will notice that this is just a fancy way to describe a string in C, which is a null-terminated array of bytes. The NULL value in C is the number zero. So, an array that ends in a null/zero value in C is essentially a sentinel-terminated array in Zig, where the sentinel value of the array is the number zero.\nTherefore, a string literal value in Zig is just a pointer to a null-terminated array of bytes (i.e., similar to a C string). But in Zig, a string literal value also embeds the length of the string, and also, the fact that they are “NULL terminated”, into the data type of the value itself.\n\n\n1.8.1.2 Slice\nYou can also access and use the arbitrary sequence of bytes that represent your string as a slice of u8 values. The majority of functions from the Zig standard library usually receive strings as inputs as slices of u8 values (slices were presented in Section 1.6).\nThus, you will see a lot of string values with a data type of []u8 or []const u8, depending if the object where this string is stored is marked as constant with const, or as variable with var. Now, because the string in this case is being interpreted as a slice, this slice is not necessarilly null-terminated, because now, the sentinel value is not mandatory. You can include the null/zero value in the slice if you want to, but there is no need to do it.\n\n// This is a string value being\n// interpreted as a slice.\nconst str: []const u8 = \"A string value\";\ntry stdout.print(\"{any}\\n\", .{@TypeOf(str)});\n\n[]const u8\n\n\n\n\n\n1.8.2 Iterating through the string\nIf you want to see the actual bytes that represents a string in Zig, you can use a for loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal value to the terminal. You do that by using a print() statement with the X formatting specifier, like you would normally do with the printf() function24 in C.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n\n\n\n\n1.8.3 A better look at the object type\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the @TypeOf() function. If we look at the type of the simple_array object below, you will find that this object is an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type i32 in Zig. That is what an object of type [4]i32 is.\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a constant pointer (hence the *const annotation) to an array of 16 elements (or 16 bytes). Each element is a single byte (more precisely, an unsigned 8 bit integer - u8), that is why we have the [16:0]u8 portion of the type below, and also, you can see that this is a null-terminated array, because of the zero value after the : character in the data type. In other words, the string literal value exposed below is 16 bytes long.\nNow, if we create an pointer to the simple_array object, then, we get a constant pointer to an array of 4 elements (*const [4]i32), which is very similar to the type of the string literal value. This demonstrates that a string literal value in Zig is already a pointer to a null-terminated array of bytes.\nFurthermore, if we take a look at the type of the string_obj object, you will see that it’s a slice object (hence the [] portion of the type) to a sequence of constant u8 values (hence the const u8 portion of the type).\n\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n\n\n1.8.4 Byte vs unicode points\nIt’s important to point out that each byte in the array is not necessarily a single character. This fact arises from the difference between a single byte and a single unicode point.\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in the string. For example, the character “H” is stored in UTF-8 as the decimal number 72. This means that the number 72 is the unicode point for the character “H”. Each possible character that can appear in a UTF-8 encoded string have its own unicode point.\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point) 570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which is 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why, the unicode point 570 is actually stored inside the computer’s memory as the bytes C8 BA.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n\nBytes that represents the string object: C8 BA \n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together to represent the number 570. That is why the relationship between bytes and unicode points is not always 1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds to a single unicode point.\nAll of this means that if you loop trough the elements of a string in Zig, you will be looping through the bytes that represents that string, and not through the characters of that string. In the Ⱥ example above, the for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a consequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because the number of bytes will be equal to the number of characters in that string. In other words, in this specific situation, the relationship between bytes and unicode points is 1 to 1.\nBut on the other side, if your string contains other types of letters… for example, you might be working with text data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent your UTF-8 string will likely be much higher than the number of characters in that string.\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the std.unicode.Utf8View struct to create an iterator that iterates through the unicode points of your string.\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in this string is represented by three bytes. But the for loop iterates four times, one iteration for each character/unicode point in this string:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n\n\n1.8.5 Some useful functions for strings\nIn this section, I just want to quickly describe some functions from the Zig Standard Library that are very useful to use when working with strings. Most notably:\n\nstd.mem.eql(): to compare if two strings are equal.\nstd.mem.splitScalar(): to split a string into an array of substrings given a delimiter value.\nstd.mem.splitSequence(): to split a string into an array of substrings given a substring delimiter.\nstd.mem.startsWith(): to check if string starts with substring.\nstd.mem.endsWith(): to check if string ends with substring.\nstd.mem.trim(): to remove specific values from both start and end of the string.\nstd.mem.concat(): to concatenate strings together.\nstd.mem.count(): to count the occurrences of substring in the string.\nstd.mem.replace(): to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the mem module of the Zig Standard Library. This module contains multiple functions and methods that are useful to work with memory and sequences of bytes in general.\nThe eql() function is used to check if two arrays of data are equal or not. Since strings are just arbitrary arrays of bytes, we can use this function to compare two strings together. This function returns a boolean value indicating if the two strings are equal or not. The first argument of this function is the data type of the elements of the arrays that are being compared.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n\ntrue\n\n\nThe splitScalar() and splitSequence() functions are useful to split a string into multiple fragments, like the split() method from Python strings. The difference between these two methods is that the splitScalar() uses a single character as the separator to split the string, while splitSequence() uses a sequence of characters (a.k.a. a substring) as the separator. There is a practical example of these functions later in the book.\nThe startsWith() and endsWith() functions are pretty straightforward. They return a boolean value indicating if the string (or, more precisely, if the array of data) begins (startsWith) or ends (endsWith) with the sequence provided.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n\ntrue\n\n\nThe concat() function, as the name suggests, concatenate two or more strings together. Because the process of concatenating the strings involves allocating enough space to accomodate all the strings together, this concat() function receives an allocator object as input.\n\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n\nAs you can imagine, the replace() function is used to replace substrings in a string by another substring. This function works very similarly to the replace() method from Python strings. Therefore, you provide a substring to search, and every time that the replace() function finds this substring within the input string, it replaces this substring with the “replacement substring” that you provided as input.\nIn the example below, we are taking the input string “Hello”, and replacing all occurrences of the substring “el” inside this input string with “34”, and saving the results inside the buffer object. As result, the replace() function returns an usize value that indicates how many replacements were performed.\n\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n\nNew string: H34lo\nN of replacements: 1",
+    "text": "1.8 How strings work in Zig?\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (Chapter 4). But in order for us to build such a thing, we need to get a better understanding on how strings work in Zig. So let’s discuss this specific aspect of Zig.\nStrings in Zig work very similarly to strings in C, but they come with some extra caveats which adds more safety and efficiency to them. You could also say that Zig simply uses a more modern and safe approach to manage and use strings.\nA string in Zig is essentially an array of arbitrary bytes, or, more specifically, an array of u8 values. This very similar to a string in C, which is also interpreted as an array of arbitrary bytes, or, in the case of C, an array of char (which usually represents an unsigned 8-bit integer value in most systems) values.\nNow, because a string in Zig is an array, you automatically get the length of the string (i.e. the length of the array) embedded in the value itself. This makes all the difference! Because now, the Zig compiler can use the length value that is embedded in the string to check for “buffer overflow” or “wrong memory access” problems in your code.\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless. So getting this kind of safety is not automatic and much harder to do in C. For example, if you want to track the length of your string throughout your program in C, then, you first need to loop through the array of bytes that represents this string, and find the null element ('\\0') position to discover where exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\nTo do that, you would need to do something like this in C. In this example, the C string stored in the object array is 25 bytes long:\n\n#include &lt;stdio.h&gt;\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n\nNumber of elements in the array: 25\nYou don’t have this kind of work in Zig. Because the length of the string is always present and accessible in the string value itself. You can easily access the length of the string through the len attribute. As an example, the string_object object below is 43 bytes long:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n\n43\n\n\nAnother point is that Zig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every sequence of bytes you’re working with, but is not really Zig’s job to fix the encoding of your strings (you can use iconv22 for that). Today, most of the text in our modern world, especially on the web, should be UTF-8 encoded. So if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\nLet’s take for example the word “Hello”. In UTF-8, this sequence of characters (H, e, l, l, o) is represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this sequence is 0x48, 0x65, 0x6C, 0x6C, 0x6F. So if I take this sequence of hexadecimal values, and ask Zig to print this sequence of bytes as a sequence of characters (i.e., a string), then, the text “Hello” will be printed into the terminal:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n\nHello\n\n\n\n1.8.1 Using a slice versus a sentinel-terminated array\nIn memory, all string values in Zig are always stored in the same way. They are simply stored as sequences/arrays of arbitrary bytes. But you can use and access this sequence of bytes in two different ways. You can access this sequence of bytes as:\n\na sentinel-terminated array of u8 values.\nor as a slice of u8 values.\n\n\n1.8.1.1 Sentinel-terminated arrays\nSentinel-terminated arrays in Zig are described in the Language Reference of Zig23. In summary a sentinel-terminated array is just a normal array, but, the difference is that they contain a “sentinel value” at the last index/element of the array. With a sentinel-terminated array you embed both the length of the array, and also, the sentinel value in the type itself of your object.\nFor example, if you write a string literal value in your code, and ask Zig to print the data type of this value, you usually get a data type in the format *const [n:0]u8. The n in the data type indicates the size of the string (that is the length of the array). The zero after the n: part of the data type is the sentinel value itself.\n\n// This is a string literal value:\n_ = \"A literal value\";\ntry stdout.print(\"{any}\\n\", .{@TypeOf(\"A literal value\")});\n\n*const [15:0]u8\n\n\nSo, with this data type *const [n:0]u8 you are essentially saying that you have an array of u8 values of length n, where, the element at the index corresponding to the length n in the array is the number zero. If you really think about this description, you will notice that this is just a fancy way to describe a string in C, which is a null-terminated array of bytes. The NULL value in C is the number zero. So, an array that ends in a null/zero value in C is essentially a sentinel-terminated array in Zig, where the sentinel value of the array is the number zero.\nTherefore, a string literal value in Zig is just a pointer to a null-terminated array of bytes (i.e., similar to a C string). But in Zig, a string literal value also embeds the length of the string, and also, the fact that they are “NULL terminated”, into the data type of the value itself.\n\n\n1.8.1.2 Slice\nYou can also access and use the arbitrary sequence of bytes that represent your string as a slice of u8 values. The majority of functions from the Zig standard library usually receive strings as inputs as slices of u8 values (slices were presented in Section 1.6).\nThus, you will see a lot of string values with a data type of []u8 or []const u8, depending if the object where this string is stored is marked as constant with const, or as variable with var. Now, because the string in this case is being interpreted as a slice, this slice is not necessarilly null-terminated, because now, the sentinel value is not mandatory. You can include the null/zero value in the slice if you want to, but there is no need to do it.\n\n// This is a string value being\n// interpreted as a slice.\nconst str: []const u8 = \"A string value\";\ntry stdout.print(\"{any}\\n\", .{@TypeOf(str)});\n\n[]const u8\n\n\n\n\n\n1.8.2 Iterating through the string\nIf you want to see the actual bytes that represents a string in Zig, you can use a for loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal value to the terminal. You do that by using a print() statement with the X formatting specifier, like you would normally do with the printf() function24 in C.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n\n\n\n\n1.8.3 A better look at the object type\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the @TypeOf() function. If we look at the type of the simple_array object below, you will find that this object is an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type i32 in Zig. That is what an object of type [4]i32 is.\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a constant pointer (hence the *const annotation) to an array of 16 elements (or 16 bytes). Each element is a single byte (more precisely, an unsigned 8 bit integer - u8), that is why we have the [16:0]u8 portion of the type below, and also, you can see that this is a null-terminated array, because of the zero value after the : character in the data type. In other words, the string literal value exposed below is 16 bytes long.\nNow, if we create an pointer to the simple_array object, then, we get a constant pointer to an array of 4 elements (*const [4]i32), which is very similar to the type of the string literal value. This demonstrates that a string literal value in Zig is already a pointer to a null-terminated array of bytes.\nFurthermore, if we take a look at the type of the string_obj object, you will see that it’s a slice object (hence the [] portion of the type) to a sequence of constant u8 values (hence the const u8 portion of the type).\n\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n\n\n1.8.4 Byte vs unicode points\nIt’s important to point out that each byte in the array is not necessarily a single character. This fact arises from the difference between a single byte and a single unicode point.\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in the string. For example, the character “H” is stored in UTF-8 as the decimal number 72. This means that the number 72 is the unicode point for the character “H”. Each possible character that can appear in a UTF-8 encoded string have its own unicode point.\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point) 570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which is 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why, the unicode point 570 is actually stored inside the computer’s memory as the bytes C8 BA.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n\nBytes that represents the string object: C8 BA \n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together to represent the number 570. That is why the relationship between bytes and unicode points is not always 1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds to a single unicode point.\nAll of this means that if you loop through the elements of a string in Zig, you will be looping through the bytes that represents that string, and not through the characters of that string. In the Ⱥ example above, the for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a consequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because the number of bytes will be equal to the number of characters in that string. In other words, in this specific situation, the relationship between bytes and unicode points is 1 to 1.\nBut on the other side, if your string contains other types of letters… for example, you might be working with text data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent your UTF-8 string will likely be much higher than the number of characters in that string.\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the std.unicode.Utf8View struct to create an iterator that iterates through the unicode points of your string.\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in this string is represented by three bytes. But the for loop iterates four times, one iteration for each character/unicode point in this string:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n\n\n1.8.5 Some useful functions for strings\nIn this section, I just want to quickly describe some functions from the Zig Standard Library that are very useful to use when working with strings. Most notably:\n\nstd.mem.eql(): to compare if two strings are equal.\nstd.mem.splitScalar(): to split a string into an array of substrings given a delimiter value.\nstd.mem.splitSequence(): to split a string into an array of substrings given a substring delimiter.\nstd.mem.startsWith(): to check if string starts with substring.\nstd.mem.endsWith(): to check if string ends with substring.\nstd.mem.trim(): to remove specific values from both start and end of the string.\nstd.mem.concat(): to concatenate strings together.\nstd.mem.count(): to count the occurrences of substring in the string.\nstd.mem.replace(): to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the mem module of the Zig Standard Library. This module contains multiple functions and methods that are useful to work with memory and sequences of bytes in general.\nThe eql() function is used to check if two arrays of data are equal or not. Since strings are just arbitrary arrays of bytes, we can use this function to compare two strings together. This function returns a boolean value indicating if the two strings are equal or not. The first argument of this function is the data type of the elements of the arrays that are being compared.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n\ntrue\n\n\nThe splitScalar() and splitSequence() functions are useful to split a string into multiple fragments, like the split() method from Python strings. The difference between these two methods is that the splitScalar() uses a single character as the separator to split the string, while splitSequence() uses a sequence of characters (a.k.a. a substring) as the separator. There is a practical example of these functions later in the book.\nThe startsWith() and endsWith() functions are pretty straightforward. They return a boolean value indicating if the string (or, more precisely, if the array of data) begins (startsWith) or ends (endsWith) with the sequence provided.\n\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n\ntrue\n\n\nThe concat() function, as the name suggests, concatenate two or more strings together. Because the process of concatenating the strings involves allocating enough space to accomodate all the strings together, this concat() function receives an allocator object as input.\n\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n\nAs you can imagine, the replace() function is used to replace substrings in a string by another substring. This function works very similarly to the replace() method from Python strings. Therefore, you provide a substring to search, and every time that the replace() function finds this substring within the input string, it replaces this substring with the “replacement substring” that you provided as input.\nIn the example below, we are taking the input string “Hello”, and replacing all occurrences of the substring “el” inside this input string with “34”, and saving the results inside the buffer object. As result, the replace() function returns an usize value that indicates how many replacements were performed.\n\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n\nNew string: H34lo\nN of replacements: 1",
     "crumbs": [
       "<span class='chapter-number'>1</span>  <span class='chapter-title'>Introducing Zig</span>"
     ]

From a2c0dfe6ae54055532eb7ce01d62bcd3ad068e61 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sun, 25 May 2025 19:25:09 -0300
Subject: [PATCH 131/151] Add flake file from bengfrost

---
 flake.nix | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)
 create mode 100644 flake.nix

diff --git a/flake.nix b/flake.nix
new file mode 100644
index 00000000..ef0ddc39
--- /dev/null
+++ b/flake.nix
@@ -0,0 +1,86 @@
+{
+  description = "Dev shell for zig-book (HTML only) with Quarto, R, and user's Zig";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.05";
+    flake-utils.url = "github:numtide/flake-utils";
+  };
+
+  outputs = { self, nixpkgs, flake-utils, ... }:
+    flake-utils.lib.eachDefaultSystem (system:
+      let
+        pkgs = nixpkgs.legacyPackages.${system};
+
+        # R packages needed by the book (from dependencies.R)
+        # and common ones for Quarto R execution.
+        rPkgsList = with pkgs.rPackages; [
+          quarto   # The R package 'quarto'
+          bslib
+          downlit
+          xml2     # Needs libxml2
+          gistr    # Might need curl
+          knitr    # Usually needed for R chunks in Quarto
+          rmarkdown # Often a dependency for knitr/Quarto R features
+          # Add other R packages if the book's R code uses more:
+          # e.g., readr, stringr, dplyr, fs, jsonlite, hms
+          readr
+          stringr
+          dplyr
+          fs
+          jsonlite
+          hms
+        ];
+
+        # R environment with the specified packages
+        R_env = pkgs.rWrapper.override {
+          packages = rPkgsList;
+        };
+
+        # Native libraries that might be runtime dependencies for R packages
+        # or tools used by Quarto (excluding PDF-specific ones).
+        nativeDeps = with pkgs; [
+          libxml2 # For rPackages.xml2
+          curl    # For rPackages.gistr or other http functionality
+        ];
+
+        # REMOVED: localeDefinitions = pkgs.glibcLocalesUtf8;
+        # C.UTF-8 is generally available without needing full glibcLocales.
+
+      in {
+        devShells.default = pkgs.mkShell {
+          # Packages made available in the shell environment
+          buildInputs = [
+            R_env       # Provides R and Rscript
+            pkgs.quarto # The Quarto CLI
+            # REMOVED: localeDefinitions
+          ] ++ nativeDeps;
+
+          shellHook = ''
+            # QUARTO_R: Point Quarto to the Rscript from our Nix-provided R environment
+            unset QUARTO_R # Clear any pre-existing value
+            export QUARTO_R="${R_env}/bin/Rscript"
+
+            # --- GENERAL LOCALE SETUP ---
+            # Set a universally available, UTF-8 compatible locale.
+            # This prevents locale errors and ensures basic Unicode handling
+            # without imposing a specific language or requiring extra locale packages.
+            export LANG="C.UTF-8"
+            export LC_ALL="C.UTF-8"
+            # REMOVED: export LOCALE_ARCHIVE="${localeDefinitions}/lib/locale/locale-archive"
+            # C.UTF-8 does not need LOCALE_ARCHIVE to be explicitly set from glibcLocalesUtf8.
+
+            echo "--- Nix Shell Environment (HTML Only) ---"
+            echo "Locale set to C.UTF-8 for broad compatibility." # Added this line for clarity
+            echo "Zig is assumed to be available via \$PATH: $(which zig || echo 'Not found in PATH')"
+            echo "R environment configured."
+            echo "  To check R's library paths: R -e '.libPaths()'"
+            echo "  To list R packages: R -e 'installed.packages()[,1]'"
+            echo "QUARTO_R set to: $QUARTO_R"
+            # REMOVED: echo "LOCALE_ARCHIVE set to: $LOCALE_ARCHIVE"
+            echo ""
+            echo "To build HTML: quarto render"
+            echo "-----------------------------------------"
+          '';
+        };
+    });
+}
\ No newline at end of file

From 40bfb6d9db0fcd854ced279014a8b6508ecd0545 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sun, 25 May 2025 19:25:36 -0300
Subject: [PATCH 132/151] Add readme from bengfrost

---
 README.md | 297 +++++++++++++++++++++++++++++-------------------------
 1 file changed, 157 insertions(+), 140 deletions(-)

diff --git a/README.md b/README.md
index b8eb409c..567773ed 100644
--- a/README.md
+++ b/README.md
@@ -1,140 +1,157 @@
-# Introduction to Zig
-
-<a href=""><img src="Cover/cover-artv3.png" width="250" height="366" class="cover" align="right"/></a>
-
-Hey! This is the official repository for the book "Introduction to Zig: a project-based book", written by Pedro Duarte Faria.
-To know more about the book, checkout the [About this book](#about-this-book) section below.
-You can read the current version of the book in your web browser: <https://pedropark99.github.io/zig-book/>.
-
-The book is built using the publishing system [Quarto](https://quarto.org)
-in conjunction with a little bit of R code (`zig_engine.R`), that is responsible for calling
-the Zig compiler to compile and run the Zig code examples.
-
-
-## Support the project!
-
-If you like this project, and you want to support it, you can buy a PDF, eBook or a physical copy
-of the book, either at Amazon, or at Leanpub:
-
-- Amazon: <https://www.amazon.com/dp/B0DJYMDRLP>
-- Leanpub: <https://leanpub.com/introductiontozigaproject-basedbook>
-
-### Sending donations directly
-
-You can also donate some amount directly to the author of the project via:
-
-- PayPal Donation.
-- Revolut.
-
-These are good ways to support directly the author of the project, which helps to foster
-more contents like this, and it makes possible for the author to keep writing helpful tools and
-materials for the community.
-
-### PayPal
-
-[![PayPal](https://img.shields.io/badge/PayPal-003087?logo=paypal&logoColor=fff)](https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD)
-
-
-### Revolut
-
-You can send money via Swift Payment with the following bank and Swift details:
-
-```
-Recipient: Pedro Duarte Faria
-BIC/SWIFT Code: REVOSGS2
-Account number: 6124512226
-Name and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore
-Corresponding BIC: CHASGB2L
-```
-
-If you do have a Revolut account, you can scan the following QR code:
-
-<http://revolut.me/pedroduartefaria>
-
-
-
-
-## About this book
-
-This is an open (i.e., open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),
-which is a new general purpose, and low-level programming language for building optimal and robust software.
-
-Official repository of the book: <https://github.com/pedropark99/zig-book>.
-
-This book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small
-and simple projects (in a similar style to the famous "Python Crash Course" book from Eric Matthes).
-Some of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.
-
-As you work through the book, you will learn:
-
-- The syntax of the language, and how it compares to C, C++ and Rust.
-- Data structures, memory allocators, filesystem and I/O.
-- Optionals as a new paradigm to handle nullability.
-- How to test and debug a Zig application.
-- Errors as values, and how to handle them.
-- How to build C and Zig code with the build system that is embedded into the language.
-- Zig interoperability with C.
-- Parallelism with threads and SIMD.
-- And more.
-
-
-
-## How to build the book
-
-This book depends on the three main pieces of software:
-
-1. The [Zig compiler](https://ziglang.org/download/), which is responsible for compiling most of the code examples exposed in the book.
-2. The [R programming language](https://cran.r-project.org/), which provides some useful tools to collect the code examples exposed across the book, and send them to the zig compiler to be compiled and executed, and also, collect the results back to include them in the book.
-3. The [Quarto publishing system](https://quarto.org/docs/get-started/), which provides the useful tools to compile the book, creating internal links, references, a chapters structure, the HTML content of the book, etc.
-
-So, you first need to install these three pieces of software in your current machine.
-You can find instructions on how to install these pieces of software by clicking in the above hyperlinks.
-
-### Install R packages
-
-After you installed the three pieces of software listed above, you should run the `dependencies.R` R script, to install
-some R packages that are used across the book. Just run the command below in your terminal, and you should be fine.
-
-OBS: If you are on Linux or MacOS, this command will probably take some time to run, because every single dependency gets built from source.
-In Windows, this usually doesn't take that long because pre-built binaries are usually available.
-
-```bash
-Rscript dependencies.R
-```
-
-### Render the book
-
-If you installed Quarto correctly in your computer
-, you should be able to build the book by simply executing
-the following command in the terminal.
-
-```bash
-quarto render
-```
-
-### How the Zig compiler is found
-
-Some R code (`zig_engine.R`) is used to collect the Zig code examples
-found across the book, and send them to the Zig compiler, so that they
-can be compiled and executed.
-
-But in order to do that, this R code needs to find the Zig compiler installed
-in your machine. This search process is done in two stages.
-First, it uses the [`Sys.which()` function](https://www.rdocumentation.org/packages/base/versions/3.6.2/topics/Sys.which)
-to find the path to the Zig compiler in your computer, which is just a R interface to the `which` command line tool.
-
-This is a fast and easy approach, but, it doesn't work in all situations, specially if
-your Zig compiler is not installed in a "standard location" in your computer. That is
-why, a second strategy is applied, which is to search through the PATH environment variable.
-
-It gets the value of your PATH environment variable, and iterates through the directories listed
-in this variable, trying to find the Zig compiler in one of them. This approach is much
-slower than the first one, but is more garanteed to work.
-
-
-
-## License
-
-Copyright © 2024 Pedro Duarte Faria. This book is licensed by the CC-BY 4.0 Creative Commons Attribution 4.0 International Public License.
-
-<a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a>
+# Introduction to Zig
+
+<a href=""><img src="Cover/cover-artv3.png" width="250" height="366" class="cover" align="right"/></a>
+
+Hey! This is the official repository for the book "Introduction to Zig: a project-based book", written by Pedro Duarte Faria.
+To know more about the book, checkout the [About this book](#about-this-book) section below.
+You can read the current version of the book in your web browser: <https://pedropark99.github.io/zig-book/>.
+
+This book is crafted using a modern, reproducible publishing stack, leveraging the power of:
+
+<p align="center">
+  <a href="https://ziglang.org/" target="_blank"><img src="https://img.shields.io/badge/Zig-%23F7A41D.svg?style=flat&logo=zig&logoColor=black" alt="Zig"></a>
+  &nbsp;
+  <a href="https://quarto.org/" target="_blank"><img src="https://img.shields.io/badge/Quarto-%234D5891.svg?style=flat&logo=quarto&logoColor=white" alt="Quarto"></a>
+  &nbsp;
+  <a href="https://www.r-project.org/" target="_blank"><img src="https://img.shields.io/badge/R-%23276DC3.svg?style=flat&logo=r&logoColor=white" alt="R"></a>
+  &nbsp;
+  <a href="https://yihui.org/knitr/" target="_blank"><img src="https://img.shields.io/badge/Knitr-%23007ACC.svg?style=flat&logoColor=white&labelColor=555555&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0Ij48cGF0aCBmaWxsPSJ3aGl0ZSIgZD0iTTE4IDZjLTMuMzEgMC02IDIuNjktNiA2czIuNjkgNiA2IDZoMy4yOGwtNC4yNC01LjA5TDIxLjM0IDZIMTh6TTMgMTJoMy4yOEwzIDE3LjA5VjE0Yy4wMS0xLjA5LS4zMy0yLjE0LS45OS0zSDN2MW0zLTZjMy4zMSAwIDYgMi42OSA2IDZzLTIuNjkgNi02IDZIMi43Mkw2LjU3IDZjMCAwIDAtMyAwLTN6Ii8+PC9zdmc+" alt="Knitr"></a>
+  &nbsp;
+  <a href="https://pandoc.org/" target="_blank"><img src="https://img.shields.io/badge/Pandoc-%2323B5AF.svg?style=flat&logoColor=white&labelColor=555555&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0Ij48cGF0aCBmaWxsPSJ3aGl0ZSIgZD0iTTEzLjEgNC42bDQuNSA5LjJoLTNsLTEuNS0zLjFoLTNsLTEuNSA0LjFoLTNMMTAuMSA0LjZoM1ptLTYuMyAwaDMuM2wzLjYgNy41aC0zLjNsLTMuNi03LjV6TTkgMTUuNGgxMy4ybC0yLjEgNC4yaC05bC0yLjEtNC4yWiIvPjwvc3ZnPg==" alt="Pandoc"></a>
+  &nbsp;
+  <a href="https://nixos.org/nix/" target="_blank"><img src="https://img.shields.io/badge/Nix-%235277C3.svg?style=flat&logo=nixos&logoColor=white" alt="Nix"></a>
+</p>
+
+The core book content is built using the [Quarto](https://quarto.org) publishing system
+in conjunction with a little bit of R code (`zig_engine.R`), that is responsible for calling
+the Zig compiler to compile and run the Zig code examples.
+
+
+## Support the project!
+
+If you like this project, and you want to support it, you can buy a PDF, eBook or a physical copy
+of the book, either at Amazon, or at Leanpub:
+
+- Amazon: <https://www.amazon.com/dp/B0DJYMDRLP>
+- Leanpub: <https://leanpub.com/introductiontozigaproject-basedbook>
+
+### Sending donations directly
+
+You can also donate some amount directly to the author of the project via:
+
+- PayPal Donation.
+- Revolut.
+
+These are good ways to support directly the author of the project, which helps to foster
+more contents like this, and it makes possible for the author to keep writing helpful tools and
+materials for the community.
+
+### PayPal
+
+[![PayPal](https://img.shields.io/badge/PayPal-003087?style=flat&logo=paypal&logoColor=fff)](https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD)
+
+
+### Revolut
+
+You can send money via Swift Payment with the following bank and Swift details:
+
+```
+Recipient: Pedro Duarte Faria
+BIC/SWIFT Code: REVOSGS2
+Account number: 6124512226
+Name and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore
+Corresponding BIC: CHASGB2L
+```
+
+If you do have a Revolut account, you can scan the following QR code:
+
+<http://revolut.me/pedroduartefaria>
+
+
+
+
+## About this book
+
+This is an open (i.e., open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),
+which is a new general purpose, and low-level programming language for building optimal and robust software.
+
+Official repository of the book: <https://github.com/pedropark99/zig-book>.
+
+This book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small
+and simple projects (in a similar style to the famous "Python Crash Course" book from Eric Matthes).
+Some of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.
+
+As you work through the book, you will learn:
+
+- The syntax of the language, and how it compares to C, C++ and Rust.
+- Data structures, memory allocators, filesystem and I/O.
+- Optionals as a new paradigm to handle nullability.
+- How to test and debug a Zig application.
+- Errors as values, and how to handle them.
+- How to build C and Zig code with the build system that is embedded into the language.
+- Zig interoperability with C.
+- Parallelism with threads and SIMD.
+- And more.
+
+
+
+## How to build the book
+
+This book's creation relies on a powerful stack of open-source tools. Understanding these helps in appreciating the build process:
+
+1.  **The <a href="https://ziglang.org/download/" target="_blank"><img src="https://img.shields.io/badge/Zig-%23F7A41D.svg?style=social&logo=zig&logoColor=black" alt="Zig" valign="middle"> Zig compiler</a>**: The star of the show, responsible for compiling most of the code examples exposed in the book.
+2.  **The <a href="https://cran.r-project.org/" target="_blank"><img src="https://img.shields.io/badge/R-%23276DC3.svg?style=social&logo=r&logoColor=white" alt="R" valign="middle"> R programming language</a>**: Provides useful tools (via <a href="https://knitr.rstudio.com/" target="_blank"><img src="https://img.shields.io/badge/Knitr-%23007ACC.svg?style=social&logoColor=white&labelColor=555555&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0Ij48cGF0aCBmaWxsPSJ3aGl0ZSIgZD0iTTE4IDZjLTMuMzEgMC02IDIuNjktNiA2czIuNjkgNiA2IDZoMy4yOGwtNC4yNC01LjA5TDIxLjM0IDZIMTh6TTMgMTJoMy4yOEwzIDE3LjA5VjE0Yy4wMS0xLjA5LS4zMy0yLjE0LS45OS0zSDN2MW0zLTZjMy4zMSAwIDYgMi42OSA2IDZzLTIuNjkgNi02IDZIMi43Mkw2LjU3IDZjMCAwIDAtMyAwLTN6Ii8+PC9zdmc+" alt="Knitr" valign="middle"> Knitr</a>) to collect code examples, send them to the Zig compiler, and retrieve results.
+3.  **The <a href="https://quarto.org/docs/get-started/" target="_blank"><img src="https://img.shields.io/badge/Quarto-%234D5891.svg?style=social&logo=quarto&logoColor=white" alt="Quarto" valign="middle"> Quarto publishing system</a>**: Orchestrates the book compilation, leveraging <a href="https://pandoc.org/" target="_blank"><img src="https://img.shields.io/badge/Pandoc-%2323B5AF.svg?style=social&logoColor=white&labelColor=555555&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0Ij48cGF0aCBmaWxsPSJ3aGl0ZSIgZD0iTTEzLjEgNC42bDQuNSA5LjJoLTNsLTEuNS0zLjFoLTNsLTEuNSA0LjFoLTNMMTAuMSA0LjZoM1ptLTYuMyAwaDMuM2wzLjYgNy41aC0zLjNsLTMuNi03LjV6TTkgMTUuNGgxMy4ybC0yLjEgNC4yaC05bC0yLjEtNC4yWiIvPjwvc3ZnPg==" alt="Pandoc" valign="middle"> Pandoc</a> under the hood for creating internal links, references, chapter structure, and the final HTML content.
+4.  Optionally, the development environment can be managed using <a href="https://nixos.org/nix/" target="_blank"><img src="https://img.shields.io/badge/Nix-%235277C3.svg?style=social&logo=nixos&logoColor=white" alt="Nix" valign="middle"> Nix</a> for reproducible builds (if a `flake.nix` is provided).
+
+So, you first need to install these three primary pieces of software (Zig, R, Quarto) in your current machine.
+You can find instructions on how to install these pieces of software by clicking in the above hyperlinks.
+
+### Install R packages
+
+After you installed the three pieces of software listed above, you should run the `dependencies.R` R script, to install
+some R packages that are used across the book. Just run the command below in your terminal, and you should be fine.
+
+OBS: If you are on Linux or MacOS, this command will probably take some time to run, because every single dependency gets built from source.
+In Windows, this usually doesn't take that long because pre-built binaries are usually available.
+
+```bash
+Rscript dependencies.R
+```
+
+### Render the book
+
+If you installed Quarto correctly in your computer
+, you should be able to build the book by simply executing
+the following command in the terminal.
+
+```bash
+quarto render
+```
+
+### How the Zig compiler is found
+
+Some R code (`zig_engine.R`) is used to collect the Zig code examples
+found across the book, and send them to the Zig compiler, so that they
+can be compiled and executed.
+
+But in order to do that, this R code needs to find the Zig compiler installed
+in your machine. This search process is done in two stages.
+First, it uses the [`Sys.which()` function](https://www.rdocumentation.org/packages/base/versions/3.6.2/topics/Sys.which)
+to find the path to the Zig compiler in your computer, which is just a R interface to the `which` command line tool.
+
+This is a fast and easy approach, but, it doesn't work in all situations, specially if
+your Zig compiler is not installed in a "standard location" in your computer. That is
+why, a second strategy is applied, which is to search through the PATH environment variable.
+
+It gets the value of your PATH environment variable, and iterates through the directories listed
+in this variable, trying to find the Zig compiler in one of them. This approach is much
+slower than the first one, but is more garanteed to work.
+
+
+
+## License
+
+Copyright © 2024 Pedro Duarte Faria. This book is licensed by the CC-BY 4.0 Creative Commons Attribution 4.0 International Public License.
+
+<a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a>

From e0b83165e1661b3d8d0a968e4e39cea7e506d4f0 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sun, 25 May 2025 19:36:28 -0300
Subject: [PATCH 133/151] Remove expression

---
 flake.nix | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/flake.nix b/flake.nix
index ef0ddc39..1d6ede3f 100644
--- a/flake.nix
+++ b/flake.nix
@@ -66,7 +66,6 @@
             # without imposing a specific language or requiring extra locale packages.
             export LANG="C.UTF-8"
             export LC_ALL="C.UTF-8"
-            # REMOVED: export LOCALE_ARCHIVE="${localeDefinitions}/lib/locale/locale-archive"
             # C.UTF-8 does not need LOCALE_ARCHIVE to be explicitly set from glibcLocalesUtf8.
 
             echo "--- Nix Shell Environment (HTML Only) ---"
@@ -83,4 +82,4 @@
           '';
         };
     });
-}
\ No newline at end of file
+}

From 0e551421af8080021a076f34448b1c042d50cabb Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sun, 25 May 2025 20:11:05 -0300
Subject: [PATCH 134/151] Build the book with Nix to make sure that the
 environment is working

---
 README.md                                     | 51 ++++++++++++---
 docs/Chapters/01-base64.html                  | 63 ++++++++-----------
 docs/Chapters/01-memory.html                  | 47 ++++++--------
 docs/Chapters/01-zig-weird.html               | 47 ++++++--------
 docs/Chapters/02-debugging.html               | 47 ++++++--------
 docs/Chapters/03-structs.html                 | 47 ++++++--------
 docs/Chapters/03-unittests.html               | 47 ++++++--------
 docs/Chapters/04-http-server.html             | 53 +++++++---------
 docs/Chapters/05-pointers.html                | 47 ++++++--------
 docs/Chapters/07-build-system.html            | 47 ++++++--------
 docs/Chapters/09-data-structures.html         | 57 +++++++----------
 docs/Chapters/09-error-handling.html          | 47 ++++++--------
 docs/Chapters/10-stack-project.html           | 49 ++++++---------
 docs/Chapters/12-file-op.html                 | 53 +++++++---------
 docs/Chapters/13-image-filter.html            | 55 +++++++---------
 docs/Chapters/14-threads.html                 | 55 +++++++---------
 docs/Chapters/14-zig-c-interop.html           | 47 ++++++--------
 docs/Chapters/15-vectors.html                 | 47 ++++++--------
 docs/index.html                               | 49 ++++++---------
 docs/references.html                          | 49 ++++++---------
 .../bootstrap/bootstrap-dark.min.css          |  4 +-
 docs/site_libs/bootstrap/bootstrap.min.css    |  4 +-
 docs/site_libs/quarto-html/quarto.js          | 15 +----
 docs/site_libs/quarto-nav/quarto-nav.js       | 36 -----------
 docs/site_libs/quarto-search/quarto-search.js |  6 +-
 flake.lock                                    | 61 ++++++++++++++++++
 26 files changed, 482 insertions(+), 648 deletions(-)
 create mode 100644 flake.lock

diff --git a/README.md b/README.md
index 567773ed..8d934611 100644
--- a/README.md
+++ b/README.md
@@ -46,9 +46,11 @@ These are good ways to support directly the author of the project, which helps t
 more contents like this, and it makes possible for the author to keep writing helpful tools and
 materials for the community.
 
+
+
 ### PayPal
 
-[![PayPal](https://img.shields.io/badge/PayPal-003087?style=flat&logo=paypal&logoColor=fff)](https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD)
+[![PayPal](https://img.shields.io/badge/PayPal-003087?logo=paypal&logoColor=fff)](https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD)
 
 
 ### Revolut
@@ -97,17 +99,25 @@ As you work through the book, you will learn:
 
 ## How to build the book
 
-This book's creation relies on a powerful stack of open-source tools. Understanding these helps in appreciating the build process:
+First of all, you need to care about the dependencies of the project. This book is built using the following pieces of software:
+
+1. The [Zig compiler](https://ziglang.org/download/), which is responsible for compiling most of the code examples exposed in the book.
+2. The [R programming language](https://cran.r-project.org/), which provides some useful tools, specially `knitr` and `rmarkdown`, which are responsible for collecting the code examples exposed across the book, and sending them to the zig compiler to be compiled and executed, and also, collecting the results back to include them in the book.
+3. The [Quarto publishing system](https://quarto.org/docs/get-started/), which is responsible for compiling the book, creating internal links, references, a chapters structure, the HTML content of the book, etc.
+
+So, installing these three pieces of software (Zig, R, Quarto) in your current machine is the first step to build the book.
+There are two strategies that you can take here:
+
+1. You can install these three pieces of software manually (you can find instructions on how to install each piece by clicking in the above hyperlinks).
+2. Or, you can use the Nix Flake declared in the `flake.nix` file to create a reproducible environment that already comes with these pieces installed.
 
-1.  **The <a href="https://ziglang.org/download/" target="_blank"><img src="https://img.shields.io/badge/Zig-%23F7A41D.svg?style=social&logo=zig&logoColor=black" alt="Zig" valign="middle"> Zig compiler</a>**: The star of the show, responsible for compiling most of the code examples exposed in the book.
-2.  **The <a href="https://cran.r-project.org/" target="_blank"><img src="https://img.shields.io/badge/R-%23276DC3.svg?style=social&logo=r&logoColor=white" alt="R" valign="middle"> R programming language</a>**: Provides useful tools (via <a href="https://knitr.rstudio.com/" target="_blank"><img src="https://img.shields.io/badge/Knitr-%23007ACC.svg?style=social&logoColor=white&labelColor=555555&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0Ij48cGF0aCBmaWxsPSJ3aGl0ZSIgZD0iTTE4IDZjLTMuMzEgMC02IDIuNjktNiA2czIuNjkgNiA2IDZoMy4yOGwtNC4yNC01LjA5TDIxLjM0IDZIMTh6TTMgMTJoMy4yOEwzIDE3LjA5VjE0Yy4wMS0xLjA5LS4zMy0yLjE0LS45OS0zSDN2MW0zLTZjMy4zMSAwIDYgMi42OSA2IDZzLTIuNjkgNi02IDZIMi43Mkw2LjU3IDZjMCAwIDAtMyAwLTN6Ii8+PC9zdmc+" alt="Knitr" valign="middle"> Knitr</a>) to collect code examples, send them to the Zig compiler, and retrieve results.
-3.  **The <a href="https://quarto.org/docs/get-started/" target="_blank"><img src="https://img.shields.io/badge/Quarto-%234D5891.svg?style=social&logo=quarto&logoColor=white" alt="Quarto" valign="middle"> Quarto publishing system</a>**: Orchestrates the book compilation, leveraging <a href="https://pandoc.org/" target="_blank"><img src="https://img.shields.io/badge/Pandoc-%2323B5AF.svg?style=social&logoColor=white&labelColor=555555&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0Ij48cGF0aCBmaWxsPSJ3aGl0ZSIgZD0iTTEzLjEgNC42bDQuNSA5LjJoLTNsLTEuNS0zLjFoLTNsLTEuNSA0LjFoLTNMMTAuMSA0LjZoM1ptLTYuMyAwaDMuM2wzLjYgNy41aC0zLjNsLTMuNi03LjV6TTkgMTUuNGgxMy4ybC0yLjEgNC4yaC05bC0yLjEtNC4yWiIvPjwvc3ZnPg==" alt="Pandoc" valign="middle"> Pandoc</a> under the hood for creating internal links, references, chapter structure, and the final HTML content.
-4.  Optionally, the development environment can be managed using <a href="https://nixos.org/nix/" target="_blank"><img src="https://img.shields.io/badge/Nix-%235277C3.svg?style=social&logo=nixos&logoColor=white" alt="Nix" valign="middle"> Nix</a> for reproducible builds (if a `flake.nix` is provided).
 
-So, you first need to install these three primary pieces of software (Zig, R, Quarto) in your current machine.
-You can find instructions on how to install these pieces of software by clicking in the above hyperlinks.
+### Building the book manually
 
-### Install R packages
+If you decide to install the dependencies of the book manually, then, follow the "install instructions" that are present in the above hyperlinks,
+and, after you installed the three pieces (Zig, R and Quarto), follow the next instructions specified here.
+
+#### Install R packages
 
 After you installed the three pieces of software listed above, you should run the `dependencies.R` R script, to install
 some R packages that are used across the book. Just run the command below in your terminal, and you should be fine.
@@ -119,7 +129,7 @@ In Windows, this usually doesn't take that long because pre-built binaries are u
 Rscript dependencies.R
 ```
 
-### Render the book
+#### Render the book
 
 If you installed Quarto correctly in your computer
 , you should be able to build the book by simply executing
@@ -129,6 +139,27 @@ the following command in the terminal.
 quarto render
 ```
 
+
+
+### Building the book with Nix Flake
+
+If you choose to use the Nix Flake to create an environment that comes with the necessary dependencies, then, you need
+to open a terminal, and run the `nix develop` command on the root of the project:
+
+```bash
+nix develop
+```
+
+With this command, Onix will download the necessary packages and libraries, and then create a new bash session that points
+to a new environment that contains these packages and libraries in it. Then, inside this new bash session that is created
+by Nix, all you need to do is to run the `quarto render` command, which will kickstart Quarto, and make it build the book
+for you:
+
+```bash
+quarto render
+```
+
+
 ### How the Zig compiler is found
 
 Some R code (`zig_engine.R`) is used to collect the Zig code examples
diff --git a/docs/Chapters/01-base64.html b/docs/Chapters/01-base64.html
index 131de842..4fa946ca 100644
--- a/docs/Chapters/01-base64.html
+++ b/docs/Chapters/01-base64.html
@@ -2,12 +2,12 @@
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
 
 <meta charset="utf-8">
-<meta name="generator" content="quarto-1.5.57">
+<meta name="generator" content="quarto-1.4.554">
 
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 
-<title>4&nbsp; Project 1 - Building a base64 encoder/decoder – Introduction to Zig</title>
+<title>Introduction to Zig - 4&nbsp; Project 1 - Building a base64 encoder/decoder</title>
 <style>
 code{white-space: pre-wrap;}
 span.smallcaps{font-variant: small-caps;}
@@ -172,13 +172,13 @@
   <header id="quarto-header" class="headroom fixed-top">
   <nav class="quarto-secondary-nav">
     <div class="container-fluid d-flex">
-      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" role="button" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
+      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
         <i class="bi bi-layout-text-sidebar-reverse"></i>
       </button>
         <nav class="quarto-page-breadcrumbs" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item"><a href="../Chapters/01-base64.html"><span class="chapter-number">4</span>&nbsp; <span class="chapter-title">Project 1 - Building a base64 encoder/decoder</span></a></li></ol></nav>
-        <a class="flex-grow-1" role="navigation" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
+        <a class="flex-grow-1" role="button" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
         </a>
-      <button type="button" class="btn quarto-search-button" aria-label="Search" onclick="window.quartoOpenSearch();">
+      <button type="button" class="btn quarto-search-button" aria-label="" onclick="window.quartoOpenSearch();">
         <i class="bi bi-search"></i>
       </button>
     </div>
@@ -435,7 +435,7 @@ <h3 data-number="4.1.3" class="anchored" data-anchor-id="sec-base64-encoder-algo
 <p>The algorithm behind a base64 encoder usually works on a window of 3 bytes. Because each byte has 8 bits, so, 3 bytes forms a set of <span class="math inline">\(8 \times 3 = 24\)</span> bits. This is desirable for the base64 algorithm, because 24 bits is divisible by 6, which forms <span class="math inline">\(24 / 6 = 4\)</span> groups of 6 bits each.</p>
 <p>Therefore, the base64 algorithm works by converting 3 bytes at a time into 4 characters from the base64 scale. It keeps iterating through the input string, 3 bytes at a time, and converting them into the base64 scale, producing 4 characters per iteration. It keeps iterating, and producing these “new characters” until it hits the end of the input string.</p>
 <p>Now you may think, what if you have a particular string that has a number of bytes that is not divisible by 3 - what happens? For example, if you have a string that contains only two characters/bytes, such as “Hi”. How would the algorithm behave in such situation? You find the answer in <a href="#fig-base64-algo1" class="quarto-xref">Figure&nbsp;<span>4.1</span></a>. You can see in <a href="#fig-base64-algo1" class="quarto-xref">Figure&nbsp;<span>4.1</span></a> that the string “Hi”, when converted to base64, becomes the string “SGk=”:</p>
-<div id="fig-base64-algo1" class="quarto-float quarto-figure quarto-figure-center anchored">
+<div id="fig-base64-algo1" class="quarto-figure quarto-figure-center quarto-float anchored">
 <figure class="quarto-float quarto-float-fig figure">
 <div aria-describedby="fig-base64-algo1-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
 <img src="./../Figures/base64-encoder-flow.png" class="img-fluid figure-img">
@@ -457,7 +457,7 @@ <h3 data-number="4.1.4" class="anchored" data-anchor-id="sec-base64-decoder-algo
 <p>The algorithm behind a base64 decoder is essentially the inverse process of a base64 encoder. A base64 decoder needs to translate base64 messages back into their original meaning, i.e., into the original sequence of binary data.</p>
 <p>A base64 decoder usually works on a window of 4 bytes. Because it wants to convert these 4 bytes back into the original sequence of 3 bytes, that was converted into 4 groups of 6 bits by the base64 encoder. Remember, in a base64 decoder we are essentially reverting the process made by the base64 encoder.</p>
 <p>Each byte in the input string (the base64 encoded string) normally contributes to re-create two different bytes in the output (the original binary data). In other words, each byte that comes out of a base64 decoder is created by transforming merging two different bytes in the input together. You can visualize this relationship in <a href="#fig-base64-algo2" class="quarto-xref">Figure&nbsp;<span>4.2</span></a>:</p>
-<div id="fig-base64-algo2" class="quarto-float quarto-figure quarto-figure-center anchored">
+<div id="fig-base64-algo2" class="quarto-figure quarto-figure-center quarto-float anchored">
 <figure class="quarto-float quarto-float-fig figure">
 <div aria-describedby="fig-base64-algo2-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
 <img src="./../Figures/base64-decoder-flow.png" class="img-fluid figure-img">
@@ -540,7 +540,7 @@ <h3 data-number="4.4.1" class="anchored" data-anchor-id="sec-6bit-transf"><span
 <li><code>output[3]</code> is produced by taking the last six bits from <code>input[2]</code>.</li>
 </ol>
 <p>This is the perfect scenario, where we have a full window of 3 bytes to work on. Just to make things as clear as possible, the <a href="#fig-encoder-bitshift" class="quarto-xref">Figure&nbsp;<span>4.3</span></a> demonstrates visually how the step 2 mentioned above works. So the 2nd byte in the <code>output</code> of the encoder, is made by taking the 1st byte (dark purple) and the 2nd byte (orange) from the input. You can see that, at the end of the process, we get a new byte that contains the last 2 bits from the 1st byte in the <code>input</code>, and the first 4 bits from the 2nd byte in the <code>input</code>.</p>
-<div id="fig-encoder-bitshift" class="quarto-float quarto-figure quarto-figure-center anchored">
+<div id="fig-encoder-bitshift" class="quarto-figure quarto-figure-center quarto-float anchored">
 <figure class="quarto-float quarto-float-fig figure">
 <div aria-describedby="fig-encoder-bitshift-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
 <img src="../Figures/base64-encoder-bit-shift.png" class="img-fluid figure-img">
@@ -561,13 +561,13 @@ <h3 data-number="4.4.1" class="anchored" data-anchor-id="sec-6bit-transf"><span
 <li><code>output[2]</code> and <code>output[3]</code> are the character <code>=</code>.</li>
 </ul>
 <p>If these bullet points were a bit confusing for you, you may find the <a href="#tbl-transf-6bit" class="quarto-xref">Table&nbsp;<span>4.1</span></a> more intuitive. This table unifies all this logic into a simple table. Notice that this table also provides the exact expression in Zig that creates the corresponding byte in the output.</p>
-<div id="tbl-transf-6bit" class="quarto-float quarto-figure quarto-figure-center anchored">
+<div id="tbl-transf-6bit" class="quarto-float anchored">
 <figure class="quarto-float quarto-float-tbl figure">
 <figcaption class="quarto-float-caption-top quarto-float-caption quarto-float-tbl" id="tbl-transf-6bit-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
 Table&nbsp;4.1: How the 6-bit transformation translates into code in different window settings.
 </figcaption>
 <div aria-describedby="tbl-transf-6bit-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
-<table class="caption-top table">
+<table class="table">
 <colgroup>
 <col style="width: 30%">
 <col style="width: 25%">
@@ -811,7 +811,7 @@ <h3 data-number="4.5.2" class="anchored" data-anchor-id="the-6-bit-transformatio
 <p>Before we continue, let’s try to visualize how these transformations make the original bytes that we had before the encoding process. First, think back to the 6-bit transformation performed by the encoder exposed in <a href="#sec-encoder-logic" class="quarto-xref"><span>Section 4.4</span></a>. The first byte in the output of the encoder is produced by moving the bits in the first byte of the input two positions to the right.</p>
 <p>If for example the first byte in the input of the encoder was the sequence <code>ABCDEFGH</code>, then, the first byte in the output of the encoder would be <code>00ABCDEF</code> (this sequence would be the first byte in the input of the decoder). Now, if the second byte in the input of the encoder was the sequence <code>IJKLMNOP</code>, then, the second byte in the encoder output would be <code>00GHIJKL</code> (as we demonstrated in <a href="#fig-encoder-bitshift" class="quarto-xref">Figure&nbsp;<span>4.3</span></a>).</p>
 <p>Hence, if the sequences <code>00ABCDEF</code> and <code>00GHIJKL</code> are the first and second bytes, respectively, in the input of the decoder, the <a href="#fig-decoder-bitshift" class="quarto-xref">Figure&nbsp;<span>4.4</span></a> demonstrates visually how these two bytes are transformed into the first byte of the output of the decoder. Notice that the output byte is the sequence <code>ABCDEFGH</code>, which is the original byte from the input of the encoder.</p>
-<div id="fig-decoder-bitshift" class="quarto-float quarto-figure quarto-figure-center anchored">
+<div id="fig-decoder-bitshift" class="quarto-figure quarto-figure-center quarto-float anchored">
 <figure class="quarto-float quarto-float-fig figure">
 <div aria-describedby="fig-decoder-bitshift-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
 <img src="../Figures/base64-decoder-bit-shift.png" class="img-fluid figure-img">
@@ -822,13 +822,13 @@ <h3 data-number="4.5.2" class="anchored" data-anchor-id="the-6-bit-transformatio
 </figure>
 </div>
 <p>The <a href="#tbl-6bit-decode" class="quarto-xref">Table&nbsp;<span>4.2</span></a> presents how the three steps described earlier translate into Zig code:</p>
-<div id="tbl-6bit-decode" class="quarto-float quarto-figure quarto-figure-center anchored">
+<div id="tbl-6bit-decode" class="quarto-float anchored">
 <figure class="quarto-float quarto-float-tbl figure">
 <figcaption class="quarto-float-caption-top quarto-float-caption quarto-float-tbl" id="tbl-6bit-decode-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
 Table&nbsp;4.2: The necessary steps for the 6-transformation in the decode process.
 </figcaption>
 <div aria-describedby="tbl-6bit-decode-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
-<table class="caption-top table">
+<table class="table">
 <thead>
 <tr class="header">
 <th>Byte index in the output</th>
@@ -1122,7 +1122,18 @@ <h2 data-number="4.6" class="anchored" data-anchor-id="the-end-result"><span cla
     }
     return false;
   }
-  const onCopySuccess = function(e) {
+  const clipboard = new window.ClipboardJS('.code-copy-button', {
+    text: function(trigger) {
+      const codeEl = trigger.previousElementSibling.cloneNode(true);
+      for (const childEl of codeEl.children) {
+        if (isCodeAnnotation(childEl)) {
+          childEl.remove();
+        }
+      }
+      return codeEl.innerText;
+    }
+  });
+  clipboard.on('success', function(e) {
     // button target
     const button = e.trigger;
     // don't keep focus
@@ -1154,29 +1165,7 @@ <h2 data-number="4.6" class="anchored" data-anchor-id="the-end-result"><span cla
     }, 1000);
     // clear code selection
     e.clearSelection();
-  }
-  const getTextToCopy = function(trigger) {
-      const codeEl = trigger.previousElementSibling.cloneNode(true);
-      for (const childEl of codeEl.children) {
-        if (isCodeAnnotation(childEl)) {
-          childEl.remove();
-        }
-      }
-      return codeEl.innerText;
-  }
-  const clipboard = new window.ClipboardJS('.code-copy-button:not([data-in-quarto-modal])', {
-    text: getTextToCopy
   });
-  clipboard.on('success', onCopySuccess);
-  if (window.document.getElementById('quarto-embedded-source-code-modal')) {
-    // For code content inside modals, clipBoardJS needs to be initialized with a container option
-    // TODO: Check when it could be a function (https://github.com/zenorocha/clipboard.js/issues/860)
-    const clipboardModal = new window.ClipboardJS('.code-copy-button[data-in-quarto-modal]', {
-      text: getTextToCopy,
-      container: window.document.getElementById('quarto-embedded-source-code-modal')
-    });
-    clipboardModal.on('success', onCopySuccess);
-  }
     var localhostRegex = new RegExp(/^(?:http|https):\/\/localhost\:?[0-9]*\//);
     var mailtoRegex = new RegExp(/^mailto:/);
       var filterRegex = new RegExp('/' + window.location.host + '/');
@@ -1184,7 +1173,7 @@ <h2 data-number="4.6" class="anchored" data-anchor-id="the-end-result"><span cla
         return filterRegex.test(href) || localhostRegex.test(href) || mailtoRegex.test(href);
     }
     // Inspect non-navigation links and adorn them if external
- 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool):not(.about-link)');
+ 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool)');
     for (var i=0; i<links.length; i++) {
       const link = links[i];
       if (!isInternal(link.href)) {
diff --git a/docs/Chapters/01-memory.html b/docs/Chapters/01-memory.html
index e4c2e35d..ae5388b5 100644
--- a/docs/Chapters/01-memory.html
+++ b/docs/Chapters/01-memory.html
@@ -2,12 +2,12 @@
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
 
 <meta charset="utf-8">
-<meta name="generator" content="quarto-1.5.57">
+<meta name="generator" content="quarto-1.4.554">
 
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 
-<title>3&nbsp; Memory and Allocators – Introduction to Zig</title>
+<title>Introduction to Zig - 3&nbsp; Memory and Allocators</title>
 <style>
 code{white-space: pre-wrap;}
 span.smallcaps{font-variant: small-caps;}
@@ -143,13 +143,13 @@
   <header id="quarto-header" class="headroom fixed-top">
   <nav class="quarto-secondary-nav">
     <div class="container-fluid d-flex">
-      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" role="button" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
+      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
         <i class="bi bi-layout-text-sidebar-reverse"></i>
       </button>
         <nav class="quarto-page-breadcrumbs" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item"><a href="../Chapters/01-memory.html"><span class="chapter-number">3</span>&nbsp; <span class="chapter-title">Memory and Allocators</span></a></li></ol></nav>
-        <a class="flex-grow-1" role="navigation" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
+        <a class="flex-grow-1" role="button" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
         </a>
-      <button type="button" class="btn quarto-search-button" aria-label="Search" onclick="window.quartoOpenSearch();">
+      <button type="button" class="btn quarto-search-button" aria-label="" onclick="window.quartoOpenSearch();">
         <i class="bi bi-search"></i>
       </button>
     </div>
@@ -915,7 +915,18 @@ <h3 data-number="3.3.9" class="anchored" data-anchor-id="the-create-and-destroy-
     }
     return false;
   }
-  const onCopySuccess = function(e) {
+  const clipboard = new window.ClipboardJS('.code-copy-button', {
+    text: function(trigger) {
+      const codeEl = trigger.previousElementSibling.cloneNode(true);
+      for (const childEl of codeEl.children) {
+        if (isCodeAnnotation(childEl)) {
+          childEl.remove();
+        }
+      }
+      return codeEl.innerText;
+    }
+  });
+  clipboard.on('success', function(e) {
     // button target
     const button = e.trigger;
     // don't keep focus
@@ -947,29 +958,7 @@ <h3 data-number="3.3.9" class="anchored" data-anchor-id="the-create-and-destroy-
     }, 1000);
     // clear code selection
     e.clearSelection();
-  }
-  const getTextToCopy = function(trigger) {
-      const codeEl = trigger.previousElementSibling.cloneNode(true);
-      for (const childEl of codeEl.children) {
-        if (isCodeAnnotation(childEl)) {
-          childEl.remove();
-        }
-      }
-      return codeEl.innerText;
-  }
-  const clipboard = new window.ClipboardJS('.code-copy-button:not([data-in-quarto-modal])', {
-    text: getTextToCopy
   });
-  clipboard.on('success', onCopySuccess);
-  if (window.document.getElementById('quarto-embedded-source-code-modal')) {
-    // For code content inside modals, clipBoardJS needs to be initialized with a container option
-    // TODO: Check when it could be a function (https://github.com/zenorocha/clipboard.js/issues/860)
-    const clipboardModal = new window.ClipboardJS('.code-copy-button[data-in-quarto-modal]', {
-      text: getTextToCopy,
-      container: window.document.getElementById('quarto-embedded-source-code-modal')
-    });
-    clipboardModal.on('success', onCopySuccess);
-  }
     var localhostRegex = new RegExp(/^(?:http|https):\/\/localhost\:?[0-9]*\//);
     var mailtoRegex = new RegExp(/^mailto:/);
       var filterRegex = new RegExp('/' + window.location.host + '/');
@@ -977,7 +966,7 @@ <h3 data-number="3.3.9" class="anchored" data-anchor-id="the-create-and-destroy-
         return filterRegex.test(href) || localhostRegex.test(href) || mailtoRegex.test(href);
     }
     // Inspect non-navigation links and adorn them if external
- 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool):not(.about-link)');
+ 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool)');
     for (var i=0; i<links.length; i++) {
       const link = links[i];
       if (!isInternal(link.href)) {
diff --git a/docs/Chapters/01-zig-weird.html b/docs/Chapters/01-zig-weird.html
index 50076fd1..517d8c1a 100644
--- a/docs/Chapters/01-zig-weird.html
+++ b/docs/Chapters/01-zig-weird.html
@@ -2,12 +2,12 @@
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
 
 <meta charset="utf-8">
-<meta name="generator" content="quarto-1.5.57">
+<meta name="generator" content="quarto-1.4.554">
 
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 
-<title>1&nbsp; Introducing Zig – Introduction to Zig</title>
+<title>Introduction to Zig - 1&nbsp; Introducing Zig</title>
 <style>
 code{white-space: pre-wrap;}
 span.smallcaps{font-variant: small-caps;}
@@ -143,13 +143,13 @@
   <header id="quarto-header" class="headroom fixed-top">
   <nav class="quarto-secondary-nav">
     <div class="container-fluid d-flex">
-      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" role="button" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
+      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
         <i class="bi bi-layout-text-sidebar-reverse"></i>
       </button>
         <nav class="quarto-page-breadcrumbs" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item"><a href="../Chapters/01-zig-weird.html"><span class="chapter-number">1</span>&nbsp; <span class="chapter-title">Introducing Zig</span></a></li></ol></nav>
-        <a class="flex-grow-1" role="navigation" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
+        <a class="flex-grow-1" role="button" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
         </a>
-      <button type="button" class="btn quarto-search-button" aria-label="Search" onclick="window.quartoOpenSearch();">
+      <button type="button" class="btn quarto-search-button" aria-label="" onclick="window.quartoOpenSearch();">
         <i class="bi bi-search"></i>
       </button>
     </div>
@@ -1322,7 +1322,18 @@ <h2 data-number="1.10" class="anchored" data-anchor-id="other-parts-of-zig"><spa
     }
     return false;
   }
-  const onCopySuccess = function(e) {
+  const clipboard = new window.ClipboardJS('.code-copy-button', {
+    text: function(trigger) {
+      const codeEl = trigger.previousElementSibling.cloneNode(true);
+      for (const childEl of codeEl.children) {
+        if (isCodeAnnotation(childEl)) {
+          childEl.remove();
+        }
+      }
+      return codeEl.innerText;
+    }
+  });
+  clipboard.on('success', function(e) {
     // button target
     const button = e.trigger;
     // don't keep focus
@@ -1354,29 +1365,7 @@ <h2 data-number="1.10" class="anchored" data-anchor-id="other-parts-of-zig"><spa
     }, 1000);
     // clear code selection
     e.clearSelection();
-  }
-  const getTextToCopy = function(trigger) {
-      const codeEl = trigger.previousElementSibling.cloneNode(true);
-      for (const childEl of codeEl.children) {
-        if (isCodeAnnotation(childEl)) {
-          childEl.remove();
-        }
-      }
-      return codeEl.innerText;
-  }
-  const clipboard = new window.ClipboardJS('.code-copy-button:not([data-in-quarto-modal])', {
-    text: getTextToCopy
   });
-  clipboard.on('success', onCopySuccess);
-  if (window.document.getElementById('quarto-embedded-source-code-modal')) {
-    // For code content inside modals, clipBoardJS needs to be initialized with a container option
-    // TODO: Check when it could be a function (https://github.com/zenorocha/clipboard.js/issues/860)
-    const clipboardModal = new window.ClipboardJS('.code-copy-button[data-in-quarto-modal]', {
-      text: getTextToCopy,
-      container: window.document.getElementById('quarto-embedded-source-code-modal')
-    });
-    clipboardModal.on('success', onCopySuccess);
-  }
     var localhostRegex = new RegExp(/^(?:http|https):\/\/localhost\:?[0-9]*\//);
     var mailtoRegex = new RegExp(/^mailto:/);
       var filterRegex = new RegExp('/' + window.location.host + '/');
@@ -1384,7 +1373,7 @@ <h2 data-number="1.10" class="anchored" data-anchor-id="other-parts-of-zig"><spa
         return filterRegex.test(href) || localhostRegex.test(href) || mailtoRegex.test(href);
     }
     // Inspect non-navigation links and adorn them if external
- 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool):not(.about-link)');
+ 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool)');
     for (var i=0; i<links.length; i++) {
       const link = links[i];
       if (!isInternal(link.href)) {
diff --git a/docs/Chapters/02-debugging.html b/docs/Chapters/02-debugging.html
index c55d2296..3ba9f88b 100644
--- a/docs/Chapters/02-debugging.html
+++ b/docs/Chapters/02-debugging.html
@@ -2,12 +2,12 @@
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
 
 <meta charset="utf-8">
-<meta name="generator" content="quarto-1.5.57">
+<meta name="generator" content="quarto-1.4.554">
 
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 
-<title>5&nbsp; Debugging Zig applications – Introduction to Zig</title>
+<title>Introduction to Zig - 5&nbsp; Debugging Zig applications</title>
 <style>
 code{white-space: pre-wrap;}
 span.smallcaps{font-variant: small-caps;}
@@ -123,13 +123,13 @@
   <header id="quarto-header" class="headroom fixed-top">
   <nav class="quarto-secondary-nav">
     <div class="container-fluid d-flex">
-      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" role="button" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
+      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
         <i class="bi bi-layout-text-sidebar-reverse"></i>
       </button>
         <nav class="quarto-page-breadcrumbs" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item"><a href="../Chapters/02-debugging.html"><span class="chapter-number">5</span>&nbsp; <span class="chapter-title">Debugging Zig applications</span></a></li></ol></nav>
-        <a class="flex-grow-1" role="navigation" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
+        <a class="flex-grow-1" role="button" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
         </a>
-      <button type="button" class="btn quarto-search-button" aria-label="Search" onclick="window.quartoOpenSearch();">
+      <button type="button" class="btn quarto-search-button" aria-label="" onclick="window.quartoOpenSearch();">
         <i class="bi bi-search"></i>
       </button>
     </div>
@@ -673,7 +673,18 @@ <h2 data-number="5.3" class="anchored" data-anchor-id="how-to-investigate-the-da
     }
     return false;
   }
-  const onCopySuccess = function(e) {
+  const clipboard = new window.ClipboardJS('.code-copy-button', {
+    text: function(trigger) {
+      const codeEl = trigger.previousElementSibling.cloneNode(true);
+      for (const childEl of codeEl.children) {
+        if (isCodeAnnotation(childEl)) {
+          childEl.remove();
+        }
+      }
+      return codeEl.innerText;
+    }
+  });
+  clipboard.on('success', function(e) {
     // button target
     const button = e.trigger;
     // don't keep focus
@@ -705,29 +716,7 @@ <h2 data-number="5.3" class="anchored" data-anchor-id="how-to-investigate-the-da
     }, 1000);
     // clear code selection
     e.clearSelection();
-  }
-  const getTextToCopy = function(trigger) {
-      const codeEl = trigger.previousElementSibling.cloneNode(true);
-      for (const childEl of codeEl.children) {
-        if (isCodeAnnotation(childEl)) {
-          childEl.remove();
-        }
-      }
-      return codeEl.innerText;
-  }
-  const clipboard = new window.ClipboardJS('.code-copy-button:not([data-in-quarto-modal])', {
-    text: getTextToCopy
   });
-  clipboard.on('success', onCopySuccess);
-  if (window.document.getElementById('quarto-embedded-source-code-modal')) {
-    // For code content inside modals, clipBoardJS needs to be initialized with a container option
-    // TODO: Check when it could be a function (https://github.com/zenorocha/clipboard.js/issues/860)
-    const clipboardModal = new window.ClipboardJS('.code-copy-button[data-in-quarto-modal]', {
-      text: getTextToCopy,
-      container: window.document.getElementById('quarto-embedded-source-code-modal')
-    });
-    clipboardModal.on('success', onCopySuccess);
-  }
     var localhostRegex = new RegExp(/^(?:http|https):\/\/localhost\:?[0-9]*\//);
     var mailtoRegex = new RegExp(/^mailto:/);
       var filterRegex = new RegExp('/' + window.location.host + '/');
@@ -735,7 +724,7 @@ <h2 data-number="5.3" class="anchored" data-anchor-id="how-to-investigate-the-da
         return filterRegex.test(href) || localhostRegex.test(href) || mailtoRegex.test(href);
     }
     // Inspect non-navigation links and adorn them if external
- 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool):not(.about-link)');
+ 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool)');
     for (var i=0; i<links.length; i++) {
       const link = links[i];
       if (!isInternal(link.href)) {
diff --git a/docs/Chapters/03-structs.html b/docs/Chapters/03-structs.html
index bc77ada2..3be7925a 100644
--- a/docs/Chapters/03-structs.html
+++ b/docs/Chapters/03-structs.html
@@ -2,12 +2,12 @@
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
 
 <meta charset="utf-8">
-<meta name="generator" content="quarto-1.5.57">
+<meta name="generator" content="quarto-1.4.554">
 
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 
-<title>2&nbsp; Control flow, structs, modules and types – Introduction to Zig</title>
+<title>Introduction to Zig - 2&nbsp; Control flow, structs, modules and types</title>
 <style>
 code{white-space: pre-wrap;}
 span.smallcaps{font-variant: small-caps;}
@@ -123,13 +123,13 @@
   <header id="quarto-header" class="headroom fixed-top">
   <nav class="quarto-secondary-nav">
     <div class="container-fluid d-flex">
-      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" role="button" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
+      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
         <i class="bi bi-layout-text-sidebar-reverse"></i>
       </button>
         <nav class="quarto-page-breadcrumbs" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item"><a href="../Chapters/03-structs.html"><span class="chapter-number">2</span>&nbsp; <span class="chapter-title">Control flow, structs, modules and types</span></a></li></ol></nav>
-        <a class="flex-grow-1" role="navigation" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
+        <a class="flex-grow-1" role="button" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
         </a>
-      <button type="button" class="btn quarto-search-button" aria-label="Search" onclick="window.quartoOpenSearch();">
+      <button type="button" class="btn quarto-search-button" aria-label="" onclick="window.quartoOpenSearch();">
         <i class="bi bi-search"></i>
       </button>
     </div>
@@ -1240,7 +1240,18 @@ <h2 data-number="2.6" class="anchored" data-anchor-id="modules"><span class="hea
     }
     return false;
   }
-  const onCopySuccess = function(e) {
+  const clipboard = new window.ClipboardJS('.code-copy-button', {
+    text: function(trigger) {
+      const codeEl = trigger.previousElementSibling.cloneNode(true);
+      for (const childEl of codeEl.children) {
+        if (isCodeAnnotation(childEl)) {
+          childEl.remove();
+        }
+      }
+      return codeEl.innerText;
+    }
+  });
+  clipboard.on('success', function(e) {
     // button target
     const button = e.trigger;
     // don't keep focus
@@ -1272,29 +1283,7 @@ <h2 data-number="2.6" class="anchored" data-anchor-id="modules"><span class="hea
     }, 1000);
     // clear code selection
     e.clearSelection();
-  }
-  const getTextToCopy = function(trigger) {
-      const codeEl = trigger.previousElementSibling.cloneNode(true);
-      for (const childEl of codeEl.children) {
-        if (isCodeAnnotation(childEl)) {
-          childEl.remove();
-        }
-      }
-      return codeEl.innerText;
-  }
-  const clipboard = new window.ClipboardJS('.code-copy-button:not([data-in-quarto-modal])', {
-    text: getTextToCopy
   });
-  clipboard.on('success', onCopySuccess);
-  if (window.document.getElementById('quarto-embedded-source-code-modal')) {
-    // For code content inside modals, clipBoardJS needs to be initialized with a container option
-    // TODO: Check when it could be a function (https://github.com/zenorocha/clipboard.js/issues/860)
-    const clipboardModal = new window.ClipboardJS('.code-copy-button[data-in-quarto-modal]', {
-      text: getTextToCopy,
-      container: window.document.getElementById('quarto-embedded-source-code-modal')
-    });
-    clipboardModal.on('success', onCopySuccess);
-  }
     var localhostRegex = new RegExp(/^(?:http|https):\/\/localhost\:?[0-9]*\//);
     var mailtoRegex = new RegExp(/^mailto:/);
       var filterRegex = new RegExp('/' + window.location.host + '/');
@@ -1302,7 +1291,7 @@ <h2 data-number="2.6" class="anchored" data-anchor-id="modules"><span class="hea
         return filterRegex.test(href) || localhostRegex.test(href) || mailtoRegex.test(href);
     }
     // Inspect non-navigation links and adorn them if external
- 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool):not(.about-link)');
+ 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool)');
     for (var i=0; i<links.length; i++) {
       const link = links[i];
       if (!isInternal(link.href)) {
diff --git a/docs/Chapters/03-unittests.html b/docs/Chapters/03-unittests.html
index c41b4ef9..817670da 100644
--- a/docs/Chapters/03-unittests.html
+++ b/docs/Chapters/03-unittests.html
@@ -2,12 +2,12 @@
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
 
 <meta charset="utf-8">
-<meta name="generator" content="quarto-1.5.57">
+<meta name="generator" content="quarto-1.4.554">
 
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 
-<title>8&nbsp; Unit tests – Introduction to Zig</title>
+<title>Introduction to Zig - 8&nbsp; Unit tests</title>
 <style>
 code{white-space: pre-wrap;}
 span.smallcaps{font-variant: small-caps;}
@@ -123,13 +123,13 @@
   <header id="quarto-header" class="headroom fixed-top">
   <nav class="quarto-secondary-nav">
     <div class="container-fluid d-flex">
-      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" role="button" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
+      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
         <i class="bi bi-layout-text-sidebar-reverse"></i>
       </button>
         <nav class="quarto-page-breadcrumbs" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item"><a href="../Chapters/03-unittests.html"><span class="chapter-number">8</span>&nbsp; <span class="chapter-title">Unit tests</span></a></li></ol></nav>
-        <a class="flex-grow-1" role="navigation" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
+        <a class="flex-grow-1" role="button" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
         </a>
-      <button type="button" class="btn quarto-search-button" aria-label="Search" onclick="window.quartoOpenSearch();">
+      <button type="button" class="btn quarto-search-button" aria-label="" onclick="window.quartoOpenSearch();">
         <i class="bi bi-search"></i>
       </button>
     </div>
@@ -655,7 +655,18 @@ <h2 data-number="8.5" class="anchored" data-anchor-id="testing-simple-equalities
     }
     return false;
   }
-  const onCopySuccess = function(e) {
+  const clipboard = new window.ClipboardJS('.code-copy-button', {
+    text: function(trigger) {
+      const codeEl = trigger.previousElementSibling.cloneNode(true);
+      for (const childEl of codeEl.children) {
+        if (isCodeAnnotation(childEl)) {
+          childEl.remove();
+        }
+      }
+      return codeEl.innerText;
+    }
+  });
+  clipboard.on('success', function(e) {
     // button target
     const button = e.trigger;
     // don't keep focus
@@ -687,29 +698,7 @@ <h2 data-number="8.5" class="anchored" data-anchor-id="testing-simple-equalities
     }, 1000);
     // clear code selection
     e.clearSelection();
-  }
-  const getTextToCopy = function(trigger) {
-      const codeEl = trigger.previousElementSibling.cloneNode(true);
-      for (const childEl of codeEl.children) {
-        if (isCodeAnnotation(childEl)) {
-          childEl.remove();
-        }
-      }
-      return codeEl.innerText;
-  }
-  const clipboard = new window.ClipboardJS('.code-copy-button:not([data-in-quarto-modal])', {
-    text: getTextToCopy
   });
-  clipboard.on('success', onCopySuccess);
-  if (window.document.getElementById('quarto-embedded-source-code-modal')) {
-    // For code content inside modals, clipBoardJS needs to be initialized with a container option
-    // TODO: Check when it could be a function (https://github.com/zenorocha/clipboard.js/issues/860)
-    const clipboardModal = new window.ClipboardJS('.code-copy-button[data-in-quarto-modal]', {
-      text: getTextToCopy,
-      container: window.document.getElementById('quarto-embedded-source-code-modal')
-    });
-    clipboardModal.on('success', onCopySuccess);
-  }
     var localhostRegex = new RegExp(/^(?:http|https):\/\/localhost\:?[0-9]*\//);
     var mailtoRegex = new RegExp(/^mailto:/);
       var filterRegex = new RegExp('/' + window.location.host + '/');
@@ -717,7 +706,7 @@ <h2 data-number="8.5" class="anchored" data-anchor-id="testing-simple-equalities
         return filterRegex.test(href) || localhostRegex.test(href) || mailtoRegex.test(href);
     }
     // Inspect non-navigation links and adorn them if external
- 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool):not(.about-link)');
+ 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool)');
     for (var i=0; i<links.length; i++) {
       const link = links[i];
       if (!isInternal(link.href)) {
diff --git a/docs/Chapters/04-http-server.html b/docs/Chapters/04-http-server.html
index 40f84d66..951a7d16 100644
--- a/docs/Chapters/04-http-server.html
+++ b/docs/Chapters/04-http-server.html
@@ -2,12 +2,12 @@
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
 
 <meta charset="utf-8">
-<meta name="generator" content="quarto-1.5.57">
+<meta name="generator" content="quarto-1.4.554">
 
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 
-<title>7&nbsp; Project 2 - Building a HTTP Server from scratch – Introduction to Zig</title>
+<title>Introduction to Zig - 7&nbsp; Project 2 - Building a HTTP Server from scratch</title>
 <style>
 code{white-space: pre-wrap;}
 span.smallcaps{font-variant: small-caps;}
@@ -143,13 +143,13 @@
   <header id="quarto-header" class="headroom fixed-top">
   <nav class="quarto-secondary-nav">
     <div class="container-fluid d-flex">
-      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" role="button" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
+      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
         <i class="bi bi-layout-text-sidebar-reverse"></i>
       </button>
         <nav class="quarto-page-breadcrumbs" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item"><a href="../Chapters/04-http-server.html"><span class="chapter-number">7</span>&nbsp; <span class="chapter-title">Project 2 - Building a HTTP Server from scratch</span></a></li></ol></nav>
-        <a class="flex-grow-1" role="navigation" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
+        <a class="flex-grow-1" role="button" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
         </a>
-      <button type="button" class="btn quarto-search-button" aria-label="Search" onclick="window.quartoOpenSearch();">
+      <button type="button" class="btn quarto-search-button" aria-label="" onclick="window.quartoOpenSearch();">
         <i class="bi bi-search"></i>
       </button>
     </div>
@@ -497,7 +497,7 @@ <h2 data-number="7.5" class="anchored" data-anchor-id="looking-at-the-current-st
 <p>Now, I’m going to execute this program, with the <code>run</code> command from the <code>zig</code> compiler. But remember, as we sad earlier, as soon as I execute this program, it will hang indefinitely, because the program is waiting for a client trying to connect to the server.</p>
 <p>More specifically, the program will pause at the line with the <code>accept()</code> call. As soon as a client try to connect to the server, then, the execution will “unpause”, and the <code>accept()</code> function will finally be executed to create the connection object that we need, and the remaining of the program will run.</p>
 <p>You can see that in <a href="#fig-print-zigrun1" class="quarto-xref">Figure&nbsp;<span>7.1</span></a>. The message <code>Server Addr: 127.0.0.1:3490</code> is printed to the console, and the program is now waiting for an incoming connection.</p>
-<div id="fig-print-zigrun1" class="quarto-float quarto-figure quarto-figure-center anchored">
+<div id="fig-print-zigrun1" class="quarto-figure quarto-figure-center quarto-float anchored">
 <figure class="quarto-float quarto-float-fig figure">
 <div aria-describedby="fig-print-zigrun1-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
 <img src="./../Figures/print-zigrun1.png" class="img-fluid figure-img">
@@ -514,7 +514,7 @@ <h2 data-number="7.5" class="anchored" data-anchor-id="looking-at-the-current-st
 <p>You get these “error messages” in the web browser, because it got no response back from the server. In other words, when the web browser connected to our server, it did send the HTTP Request through the established connection. Then, the web browser was expecting to receive a HTTP Response back, but it got no response from the server (we didn’t implemented the HTTP Response logic yet).</p>
 <p>But that is okay. We have achieved the result that we wanted for now, which is to connect to the server, and see the HTTP Request that was sent by the web browser (or by the Python script) to the server.</p>
 <p>If you comeback to the console that you left open when you have executed the program, you will see that the program finished its execution, and, a new message is printed in the console, which is the actual HTTP Request message that was sent by the web browser to the server. You can see this message in <a href="#fig-print-zigrun2" class="quarto-xref">Figure&nbsp;<span>7.2</span></a>.</p>
-<div id="fig-print-zigrun2" class="quarto-float quarto-figure quarto-figure-center anchored">
+<div id="fig-print-zigrun2" class="quarto-figure quarto-figure-center quarto-float anchored">
 <figure class="quarto-float quarto-float-fig figure">
 <div aria-describedby="fig-print-zigrun2-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
 <img src="./../Figures/print-zigrun2.png" class="img-fluid figure-img">
@@ -779,7 +779,7 @@ <h2 data-number="7.8" class="anchored" data-anchor-id="the-end-result"><span cla
 </div>
 <p>Now that we adjusted our <code>main()</code> function, I can now execute our program, and see the effects of these last changes. First, I execute the program once again, with the <code>run</code> command of the <code>zig</code> compiler. The program will hang, waiting for a client to connect.</p>
 <p>Then, I open my web browser, and try to connect to the server again, using the URL <code>localhost:3490</code>. This time, instead of getting some sort of an error message from the browser, you will get the message “Hello World” printed into your web browser. Because this time, the server sended the HTTP Response successfully to the web browser, as demonstrated by <a href="#fig-print-zigrun3" class="quarto-xref">Figure&nbsp;<span>7.3</span></a>.</p>
-<div id="fig-print-zigrun3" class="quarto-float quarto-figure quarto-figure-center anchored">
+<div id="fig-print-zigrun3" class="quarto-figure quarto-figure-center quarto-float anchored">
 <figure class="quarto-float quarto-float-fig figure">
 <div aria-describedby="fig-print-zigrun3-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
 <img src="./../Figures/print-zigrun3.png" class="img-fluid figure-img">
@@ -996,7 +996,18 @@ <h2 data-number="7.8" class="anchored" data-anchor-id="the-end-result"><span cla
     }
     return false;
   }
-  const onCopySuccess = function(e) {
+  const clipboard = new window.ClipboardJS('.code-copy-button', {
+    text: function(trigger) {
+      const codeEl = trigger.previousElementSibling.cloneNode(true);
+      for (const childEl of codeEl.children) {
+        if (isCodeAnnotation(childEl)) {
+          childEl.remove();
+        }
+      }
+      return codeEl.innerText;
+    }
+  });
+  clipboard.on('success', function(e) {
     // button target
     const button = e.trigger;
     // don't keep focus
@@ -1028,29 +1039,7 @@ <h2 data-number="7.8" class="anchored" data-anchor-id="the-end-result"><span cla
     }, 1000);
     // clear code selection
     e.clearSelection();
-  }
-  const getTextToCopy = function(trigger) {
-      const codeEl = trigger.previousElementSibling.cloneNode(true);
-      for (const childEl of codeEl.children) {
-        if (isCodeAnnotation(childEl)) {
-          childEl.remove();
-        }
-      }
-      return codeEl.innerText;
-  }
-  const clipboard = new window.ClipboardJS('.code-copy-button:not([data-in-quarto-modal])', {
-    text: getTextToCopy
   });
-  clipboard.on('success', onCopySuccess);
-  if (window.document.getElementById('quarto-embedded-source-code-modal')) {
-    // For code content inside modals, clipBoardJS needs to be initialized with a container option
-    // TODO: Check when it could be a function (https://github.com/zenorocha/clipboard.js/issues/860)
-    const clipboardModal = new window.ClipboardJS('.code-copy-button[data-in-quarto-modal]', {
-      text: getTextToCopy,
-      container: window.document.getElementById('quarto-embedded-source-code-modal')
-    });
-    clipboardModal.on('success', onCopySuccess);
-  }
     var localhostRegex = new RegExp(/^(?:http|https):\/\/localhost\:?[0-9]*\//);
     var mailtoRegex = new RegExp(/^mailto:/);
       var filterRegex = new RegExp('/' + window.location.host + '/');
@@ -1058,7 +1047,7 @@ <h2 data-number="7.8" class="anchored" data-anchor-id="the-end-result"><span cla
         return filterRegex.test(href) || localhostRegex.test(href) || mailtoRegex.test(href);
     }
     // Inspect non-navigation links and adorn them if external
- 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool):not(.about-link)');
+ 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool)');
     for (var i=0; i<links.length; i++) {
       const link = links[i];
       if (!isInternal(link.href)) {
diff --git a/docs/Chapters/05-pointers.html b/docs/Chapters/05-pointers.html
index 25812334..6a2731b5 100644
--- a/docs/Chapters/05-pointers.html
+++ b/docs/Chapters/05-pointers.html
@@ -2,12 +2,12 @@
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
 
 <meta charset="utf-8">
-<meta name="generator" content="quarto-1.5.57">
+<meta name="generator" content="quarto-1.4.554">
 
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 
-<title>6&nbsp; Pointers and Optionals – Introduction to Zig</title>
+<title>Introduction to Zig - 6&nbsp; Pointers and Optionals</title>
 <style>
 code{white-space: pre-wrap;}
 span.smallcaps{font-variant: small-caps;}
@@ -143,13 +143,13 @@
   <header id="quarto-header" class="headroom fixed-top">
   <nav class="quarto-secondary-nav">
     <div class="container-fluid d-flex">
-      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" role="button" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
+      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
         <i class="bi bi-layout-text-sidebar-reverse"></i>
       </button>
         <nav class="quarto-page-breadcrumbs" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item"><a href="../Chapters/05-pointers.html"><span class="chapter-number">6</span>&nbsp; <span class="chapter-title">Pointers and Optionals</span></a></li></ol></nav>
-        <a class="flex-grow-1" role="navigation" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
+        <a class="flex-grow-1" role="button" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
         </a>
-      <button type="button" class="btn quarto-search-button" aria-label="Search" onclick="window.quartoOpenSearch();">
+      <button type="button" class="btn quarto-search-button" aria-label="" onclick="window.quartoOpenSearch();">
         <i class="bi bi-search"></i>
       </button>
     </div>
@@ -737,7 +737,18 @@ <h3 data-number="6.4.3" class="anchored" data-anchor-id="sec-null-handling"><spa
     }
     return false;
   }
-  const onCopySuccess = function(e) {
+  const clipboard = new window.ClipboardJS('.code-copy-button', {
+    text: function(trigger) {
+      const codeEl = trigger.previousElementSibling.cloneNode(true);
+      for (const childEl of codeEl.children) {
+        if (isCodeAnnotation(childEl)) {
+          childEl.remove();
+        }
+      }
+      return codeEl.innerText;
+    }
+  });
+  clipboard.on('success', function(e) {
     // button target
     const button = e.trigger;
     // don't keep focus
@@ -769,29 +780,7 @@ <h3 data-number="6.4.3" class="anchored" data-anchor-id="sec-null-handling"><spa
     }, 1000);
     // clear code selection
     e.clearSelection();
-  }
-  const getTextToCopy = function(trigger) {
-      const codeEl = trigger.previousElementSibling.cloneNode(true);
-      for (const childEl of codeEl.children) {
-        if (isCodeAnnotation(childEl)) {
-          childEl.remove();
-        }
-      }
-      return codeEl.innerText;
-  }
-  const clipboard = new window.ClipboardJS('.code-copy-button:not([data-in-quarto-modal])', {
-    text: getTextToCopy
   });
-  clipboard.on('success', onCopySuccess);
-  if (window.document.getElementById('quarto-embedded-source-code-modal')) {
-    // For code content inside modals, clipBoardJS needs to be initialized with a container option
-    // TODO: Check when it could be a function (https://github.com/zenorocha/clipboard.js/issues/860)
-    const clipboardModal = new window.ClipboardJS('.code-copy-button[data-in-quarto-modal]', {
-      text: getTextToCopy,
-      container: window.document.getElementById('quarto-embedded-source-code-modal')
-    });
-    clipboardModal.on('success', onCopySuccess);
-  }
     var localhostRegex = new RegExp(/^(?:http|https):\/\/localhost\:?[0-9]*\//);
     var mailtoRegex = new RegExp(/^mailto:/);
       var filterRegex = new RegExp('/' + window.location.host + '/');
@@ -799,7 +788,7 @@ <h3 data-number="6.4.3" class="anchored" data-anchor-id="sec-null-handling"><spa
         return filterRegex.test(href) || localhostRegex.test(href) || mailtoRegex.test(href);
     }
     // Inspect non-navigation links and adorn them if external
- 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool):not(.about-link)');
+ 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool)');
     for (var i=0; i<links.length; i++) {
       const link = links[i];
       if (!isInternal(link.href)) {
diff --git a/docs/Chapters/07-build-system.html b/docs/Chapters/07-build-system.html
index ed90246f..2cc21ac4 100644
--- a/docs/Chapters/07-build-system.html
+++ b/docs/Chapters/07-build-system.html
@@ -2,12 +2,12 @@
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
 
 <meta charset="utf-8">
-<meta name="generator" content="quarto-1.5.57">
+<meta name="generator" content="quarto-1.4.554">
 
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 
-<title>9&nbsp; Build System – Introduction to Zig</title>
+<title>Introduction to Zig - 9&nbsp; Build System</title>
 <style>
 code{white-space: pre-wrap;}
 span.smallcaps{font-variant: small-caps;}
@@ -123,13 +123,13 @@
   <header id="quarto-header" class="headroom fixed-top">
   <nav class="quarto-secondary-nav">
     <div class="container-fluid d-flex">
-      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" role="button" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
+      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
         <i class="bi bi-layout-text-sidebar-reverse"></i>
       </button>
         <nav class="quarto-page-breadcrumbs" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item"><a href="../Chapters/07-build-system.html"><span class="chapter-number">9</span>&nbsp; <span class="chapter-title">Build System</span></a></li></ol></nav>
-        <a class="flex-grow-1" role="navigation" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
+        <a class="flex-grow-1" role="button" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
         </a>
-      <button type="button" class="btn quarto-search-button" aria-label="Search" onclick="window.quartoOpenSearch();">
+      <button type="button" class="btn quarto-search-button" aria-label="" onclick="window.quartoOpenSearch();">
         <i class="bi bi-search"></i>
       </button>
     </div>
@@ -901,7 +901,18 @@ <h3 data-number="9.11.5" class="anchored" data-anchor-id="sec-include-paths"><sp
     }
     return false;
   }
-  const onCopySuccess = function(e) {
+  const clipboard = new window.ClipboardJS('.code-copy-button', {
+    text: function(trigger) {
+      const codeEl = trigger.previousElementSibling.cloneNode(true);
+      for (const childEl of codeEl.children) {
+        if (isCodeAnnotation(childEl)) {
+          childEl.remove();
+        }
+      }
+      return codeEl.innerText;
+    }
+  });
+  clipboard.on('success', function(e) {
     // button target
     const button = e.trigger;
     // don't keep focus
@@ -933,29 +944,7 @@ <h3 data-number="9.11.5" class="anchored" data-anchor-id="sec-include-paths"><sp
     }, 1000);
     // clear code selection
     e.clearSelection();
-  }
-  const getTextToCopy = function(trigger) {
-      const codeEl = trigger.previousElementSibling.cloneNode(true);
-      for (const childEl of codeEl.children) {
-        if (isCodeAnnotation(childEl)) {
-          childEl.remove();
-        }
-      }
-      return codeEl.innerText;
-  }
-  const clipboard = new window.ClipboardJS('.code-copy-button:not([data-in-quarto-modal])', {
-    text: getTextToCopy
   });
-  clipboard.on('success', onCopySuccess);
-  if (window.document.getElementById('quarto-embedded-source-code-modal')) {
-    // For code content inside modals, clipBoardJS needs to be initialized with a container option
-    // TODO: Check when it could be a function (https://github.com/zenorocha/clipboard.js/issues/860)
-    const clipboardModal = new window.ClipboardJS('.code-copy-button[data-in-quarto-modal]', {
-      text: getTextToCopy,
-      container: window.document.getElementById('quarto-embedded-source-code-modal')
-    });
-    clipboardModal.on('success', onCopySuccess);
-  }
     var localhostRegex = new RegExp(/^(?:http|https):\/\/localhost\:?[0-9]*\//);
     var mailtoRegex = new RegExp(/^mailto:/);
       var filterRegex = new RegExp('/' + window.location.host + '/');
@@ -963,7 +952,7 @@ <h3 data-number="9.11.5" class="anchored" data-anchor-id="sec-include-paths"><sp
         return filterRegex.test(href) || localhostRegex.test(href) || mailtoRegex.test(href);
     }
     // Inspect non-navigation links and adorn them if external
- 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool):not(.about-link)');
+ 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool)');
     for (var i=0; i<links.length; i++) {
       const link = links[i];
       if (!isInternal(link.href)) {
diff --git a/docs/Chapters/09-data-structures.html b/docs/Chapters/09-data-structures.html
index 12765e04..5f70ae35 100644
--- a/docs/Chapters/09-data-structures.html
+++ b/docs/Chapters/09-data-structures.html
@@ -2,12 +2,12 @@
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
 
 <meta charset="utf-8">
-<meta name="generator" content="quarto-1.5.57">
+<meta name="generator" content="quarto-1.4.554">
 
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 
-<title>11&nbsp; Data Structures – Introduction to Zig</title>
+<title>Introduction to Zig - 11&nbsp; Data Structures</title>
 <style>
 code{white-space: pre-wrap;}
 span.smallcaps{font-variant: small-caps;}
@@ -172,13 +172,13 @@
   <header id="quarto-header" class="headroom fixed-top">
   <nav class="quarto-secondary-nav">
     <div class="container-fluid d-flex">
-      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" role="button" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
+      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
         <i class="bi bi-layout-text-sidebar-reverse"></i>
       </button>
         <nav class="quarto-page-breadcrumbs" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item"><a href="../Chapters/09-data-structures.html"><span class="chapter-number">11</span>&nbsp; <span class="chapter-title">Data Structures</span></a></li></ol></nav>
-        <a class="flex-grow-1" role="navigation" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
+        <a class="flex-grow-1" role="button" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
         </a>
-      <button type="button" class="btn quarto-search-button" aria-label="Search" onclick="window.quartoOpenSearch();">
+      <button type="button" class="btn quarto-search-button" aria-label="" onclick="window.quartoOpenSearch();">
         <i class="bi bi-search"></i>
       </button>
     </div>
@@ -386,7 +386,7 @@ <h3 data-number="11.1.1" class="anchored" data-anchor-id="capacity-vs-length"><s
 <p>In contrast, the <em>length</em> refers to how many elements in the array are currently being used, or, in other words, how many elements in this array that you have assigned a value to. Every dynamic array works around a block of allocated memory, which represents an array with total capacity for <span class="math inline">\(n\)</span> elements. However, only a portion of these <span class="math inline">\(n\)</span> elements are being used most of the time. This portion of <span class="math inline">\(n\)</span> is the <em>length</em> of the array. So every time you append a new value to the array, you are incrementing its <em>length</em> by one.</p>
 <p>This means that a dynamic array usually works with an extra margin, or an extra space that is currently empty, but waiting and ready to be used. This “extra space” is essentially the difference between <em>capacity</em> and <em>length</em>. <em>Capacity</em> represents the total number of elements that the array can hold without the need to re-allocate or re-expand the array, while the <em>length</em> represents how much of this capacity is currently being used to hold/store values.</p>
 <p><a href="#fig-capacity-length" class="quarto-xref">Figure&nbsp;<span>11.1</span></a> presents this idea visually. Notice that, at first, the capacity of the array is greater than the length of the array. So, the dynamic array have extra space that is currently empty, but it is ready to receive a value to be stored.</p>
-<div id="fig-capacity-length" class="quarto-float quarto-figure quarto-figure-center anchored">
+<div id="fig-capacity-length" class="quarto-figure quarto-figure-center quarto-float anchored">
 <figure class="quarto-float quarto-float-fig figure">
 <div aria-describedby="fig-capacity-length-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
 <img src="./../Figures/dynamic-array.png" class="img-fluid figure-img">
@@ -506,7 +506,7 @@ <h3 data-number="11.2.1" class="anchored" data-anchor-id="what-is-a-hashtable"><
 <p>Under the hood, the hashtable contains an array. This array is where the values are stored, and the elements of this array are usually called of <em>buckets</em>. So the values that you provide to the hashtable are stored inside buckets, and you access each bucket by using an index.</p>
 <p>When you provide a key to a hashtable, it passes this key to the hash function. This hash function uses some sort of hashing algorithm to transform this key into an index. This index is actually an array index. It’s a position in the underlying array of the hashtable. This is how a key identifies a specific position (or location) inside the hashtable structure.</p>
 <p>Therefore, you provide a key to the hashtable, and this key identifies a specific location inside the hashtable, then, the hashtable takes the input value that you provided, and stores this value in the location identified by this input key. You could say that the key maps to the value stored in the hashtable. You find the value, by using the key that identifies the location where the value is stored. The <a href="#fig-hashtable" class="quarto-xref">Figure&nbsp;<span>11.2</span></a> presents this process visually.</p>
-<div id="fig-hashtable" class="quarto-float quarto-figure quarto-figure-center anchored">
+<div id="fig-hashtable" class="quarto-figure quarto-figure-center quarto-float anchored">
 <figure class="quarto-float quarto-float-fig figure">
 <div aria-describedby="fig-hashtable-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
 <img src="./../Figures/hashtable.svg" class="img-fluid figure-img">
@@ -689,7 +689,7 @@ <h2 data-number="11.3" class="anchored" data-anchor-id="linked-lists"><span clas
 <p>The idea behind a linked list is to build a structure that consists of a sequence of nodes connected to each other by pointers. This means that linked lists are usually not contiguous in memory, because each node might be anywhere in memory. They do not need to be close to one another.</p>
 <p>In <a href="#fig-linked-list" class="quarto-xref">Figure&nbsp;<span>11.3</span></a> we can see a diagram of a singly linked list. We begin at the first node (which is usually called “the head of the linked list”). Then, from this first node we uncover the remaining nodes in the structure, by following the locations pointed by the pointers found in each node.</p>
 <p>Each node has two things in it. It has the value that is stored in the current node , and also, a pointer. This pointer points to the next node in the list. If this pointer is null, then, it means that we have reached the end of our linked list.</p>
-<div id="fig-linked-list" class="quarto-float quarto-figure quarto-figure-center anchored">
+<div id="fig-linked-list" class="quarto-figure quarto-figure-center quarto-float anchored">
 <figure class="quarto-float quarto-float-fig figure">
 <div aria-describedby="fig-linked-list-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
 <img src="./../Figures/linked-list.png" class="img-fluid figure-img">
@@ -701,7 +701,7 @@ <h2 data-number="11.3" class="anchored" data-anchor-id="linked-lists"><span clas
 </div>
 <p>In <a href="#fig-linked-list2" class="quarto-xref">Figure&nbsp;<span>11.4</span></a> we can see a diagram of a doubly linked list. The only thing that really changes now is that every node in the linked list has both a pointer to the previous node, and, a pointer to the next node. So every node in a doubly linked list has two pointers in it. These are usually called the <code>prev</code> (for “previous”) and the <code>next</code> (for “next”) pointers of the node.</p>
 <p>In the singly linked list example, we had only one single pointer in each node, and this singular pointer was always pointing to the next node in the sequence. This means that singly linked lists normally have only the <code>next</code> pointer in them.</p>
-<div id="fig-linked-list2" class="quarto-float quarto-figure quarto-figure-center anchored">
+<div id="fig-linked-list2" class="quarto-figure quarto-figure-center quarto-float anchored">
 <figure class="quarto-float quarto-float-fig figure">
 <div aria-describedby="fig-linked-list2-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
 <img src="./../Figures/doubly-linked-list.png" class="img-fluid figure-img">
@@ -783,7 +783,7 @@ <h2 data-number="11.4" class="anchored" data-anchor-id="multi-array-structure"><
 </div>
 <p>In other words, instead of creating an array of “persons”, the <code>MultiArrayList()</code> function creates a “struct of arrays”. Each data member of this struct is a different array that stores the values of a specific field from the <code>Person</code> values that were added (or, appended) to this “struct of arrays”. One important detail is that each of these separate internal arrays stored inside <code>PersonArray</code> are dynamic arrays. This means that these arrays can grow in capacity automatically as needed, to accomodate more values.</p>
 <p>The <a href="#fig-multi-array" class="quarto-xref">Figure&nbsp;<span>11.5</span></a> exposed below presents a diagram that describes the <code>PersonArray</code> struct that we have created in the previous code example. Notice that the values of the data members present in each of the three <code>Person</code> values that we have appended into the <code>PersonArray</code> object , are scattered across three different internal arrays of the <code>PersonArray</code> object.</p>
-<div id="fig-multi-array" class="quarto-float quarto-figure quarto-figure-center anchored">
+<div id="fig-multi-array" class="quarto-figure quarto-figure-center quarto-float anchored">
 <figure class="quarto-float quarto-float-fig figure">
 <div aria-describedby="fig-multi-array-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
 <img src="./../Figures/multi-array.png" class="img-fluid figure-img">
@@ -1021,7 +1021,18 @@ <h2 data-number="11.5" class="anchored" data-anchor-id="conclusion-1"><span clas
     }
     return false;
   }
-  const onCopySuccess = function(e) {
+  const clipboard = new window.ClipboardJS('.code-copy-button', {
+    text: function(trigger) {
+      const codeEl = trigger.previousElementSibling.cloneNode(true);
+      for (const childEl of codeEl.children) {
+        if (isCodeAnnotation(childEl)) {
+          childEl.remove();
+        }
+      }
+      return codeEl.innerText;
+    }
+  });
+  clipboard.on('success', function(e) {
     // button target
     const button = e.trigger;
     // don't keep focus
@@ -1053,29 +1064,7 @@ <h2 data-number="11.5" class="anchored" data-anchor-id="conclusion-1"><span clas
     }, 1000);
     // clear code selection
     e.clearSelection();
-  }
-  const getTextToCopy = function(trigger) {
-      const codeEl = trigger.previousElementSibling.cloneNode(true);
-      for (const childEl of codeEl.children) {
-        if (isCodeAnnotation(childEl)) {
-          childEl.remove();
-        }
-      }
-      return codeEl.innerText;
-  }
-  const clipboard = new window.ClipboardJS('.code-copy-button:not([data-in-quarto-modal])', {
-    text: getTextToCopy
   });
-  clipboard.on('success', onCopySuccess);
-  if (window.document.getElementById('quarto-embedded-source-code-modal')) {
-    // For code content inside modals, clipBoardJS needs to be initialized with a container option
-    // TODO: Check when it could be a function (https://github.com/zenorocha/clipboard.js/issues/860)
-    const clipboardModal = new window.ClipboardJS('.code-copy-button[data-in-quarto-modal]', {
-      text: getTextToCopy,
-      container: window.document.getElementById('quarto-embedded-source-code-modal')
-    });
-    clipboardModal.on('success', onCopySuccess);
-  }
     var localhostRegex = new RegExp(/^(?:http|https):\/\/localhost\:?[0-9]*\//);
     var mailtoRegex = new RegExp(/^mailto:/);
       var filterRegex = new RegExp('/' + window.location.host + '/');
@@ -1083,7 +1072,7 @@ <h2 data-number="11.5" class="anchored" data-anchor-id="conclusion-1"><span clas
         return filterRegex.test(href) || localhostRegex.test(href) || mailtoRegex.test(href);
     }
     // Inspect non-navigation links and adorn them if external
- 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool):not(.about-link)');
+ 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool)');
     for (var i=0; i<links.length; i++) {
       const link = links[i];
       if (!isInternal(link.href)) {
diff --git a/docs/Chapters/09-error-handling.html b/docs/Chapters/09-error-handling.html
index e621d0b4..9ed073b5 100644
--- a/docs/Chapters/09-error-handling.html
+++ b/docs/Chapters/09-error-handling.html
@@ -2,12 +2,12 @@
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
 
 <meta charset="utf-8">
-<meta name="generator" content="quarto-1.5.57">
+<meta name="generator" content="quarto-1.4.554">
 
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 
-<title>10&nbsp; Error handling and unions – Introduction to Zig</title>
+<title>Introduction to Zig - 10&nbsp; Error handling and unions</title>
 <style>
 code{white-space: pre-wrap;}
 span.smallcaps{font-variant: small-caps;}
@@ -172,13 +172,13 @@
   <header id="quarto-header" class="headroom fixed-top">
   <nav class="quarto-secondary-nav">
     <div class="container-fluid d-flex">
-      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" role="button" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
+      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
         <i class="bi bi-layout-text-sidebar-reverse"></i>
       </button>
         <nav class="quarto-page-breadcrumbs" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item"><a href="../Chapters/09-error-handling.html"><span class="chapter-number">10</span>&nbsp; <span class="chapter-title">Error handling and unions</span></a></li></ol></nav>
-        <a class="flex-grow-1" role="navigation" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
+        <a class="flex-grow-1" role="button" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
         </a>
-      <button type="button" class="btn quarto-search-button" aria-label="Search" onclick="window.quartoOpenSearch();">
+      <button type="button" class="btn quarto-search-button" aria-label="" onclick="window.quartoOpenSearch();">
         <i class="bi bi-search"></i>
       </button>
     </div>
@@ -832,7 +832,18 @@ <h2 data-number="10.3" class="anchored" data-anchor-id="sec-unions"><span class=
     }
     return false;
   }
-  const onCopySuccess = function(e) {
+  const clipboard = new window.ClipboardJS('.code-copy-button', {
+    text: function(trigger) {
+      const codeEl = trigger.previousElementSibling.cloneNode(true);
+      for (const childEl of codeEl.children) {
+        if (isCodeAnnotation(childEl)) {
+          childEl.remove();
+        }
+      }
+      return codeEl.innerText;
+    }
+  });
+  clipboard.on('success', function(e) {
     // button target
     const button = e.trigger;
     // don't keep focus
@@ -864,29 +875,7 @@ <h2 data-number="10.3" class="anchored" data-anchor-id="sec-unions"><span class=
     }, 1000);
     // clear code selection
     e.clearSelection();
-  }
-  const getTextToCopy = function(trigger) {
-      const codeEl = trigger.previousElementSibling.cloneNode(true);
-      for (const childEl of codeEl.children) {
-        if (isCodeAnnotation(childEl)) {
-          childEl.remove();
-        }
-      }
-      return codeEl.innerText;
-  }
-  const clipboard = new window.ClipboardJS('.code-copy-button:not([data-in-quarto-modal])', {
-    text: getTextToCopy
   });
-  clipboard.on('success', onCopySuccess);
-  if (window.document.getElementById('quarto-embedded-source-code-modal')) {
-    // For code content inside modals, clipBoardJS needs to be initialized with a container option
-    // TODO: Check when it could be a function (https://github.com/zenorocha/clipboard.js/issues/860)
-    const clipboardModal = new window.ClipboardJS('.code-copy-button[data-in-quarto-modal]', {
-      text: getTextToCopy,
-      container: window.document.getElementById('quarto-embedded-source-code-modal')
-    });
-    clipboardModal.on('success', onCopySuccess);
-  }
     var localhostRegex = new RegExp(/^(?:http|https):\/\/localhost\:?[0-9]*\//);
     var mailtoRegex = new RegExp(/^mailto:/);
       var filterRegex = new RegExp('/' + window.location.host + '/');
@@ -894,7 +883,7 @@ <h2 data-number="10.3" class="anchored" data-anchor-id="sec-unions"><span class=
         return filterRegex.test(href) || localhostRegex.test(href) || mailtoRegex.test(href);
     }
     // Inspect non-navigation links and adorn them if external
- 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool):not(.about-link)');
+ 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool)');
     for (var i=0; i<links.length; i++) {
       const link = links[i];
       if (!isInternal(link.href)) {
diff --git a/docs/Chapters/10-stack-project.html b/docs/Chapters/10-stack-project.html
index e7242888..c9dddea2 100644
--- a/docs/Chapters/10-stack-project.html
+++ b/docs/Chapters/10-stack-project.html
@@ -2,12 +2,12 @@
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
 
 <meta charset="utf-8">
-<meta name="generator" content="quarto-1.5.57">
+<meta name="generator" content="quarto-1.4.554">
 
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 
-<title>12&nbsp; Project 3 - Building a stack data structure – Introduction to Zig</title>
+<title>Introduction to Zig - 12&nbsp; Project 3 - Building a stack data structure</title>
 <style>
 code{white-space: pre-wrap;}
 span.smallcaps{font-variant: small-caps;}
@@ -143,13 +143,13 @@
   <header id="quarto-header" class="headroom fixed-top">
   <nav class="quarto-secondary-nav">
     <div class="container-fluid d-flex">
-      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" role="button" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
+      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
         <i class="bi bi-layout-text-sidebar-reverse"></i>
       </button>
         <nav class="quarto-page-breadcrumbs" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item"><a href="../Chapters/10-stack-project.html"><span class="chapter-number">12</span>&nbsp; <span class="chapter-title">Project 3 - Building a stack data structure</span></a></li></ol></nav>
-        <a class="flex-grow-1" role="navigation" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
+        <a class="flex-grow-1" role="button" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
         </a>
-      <button type="button" class="btn quarto-search-button" aria-label="Search" onclick="window.quartoOpenSearch();">
+      <button type="button" class="btn quarto-search-button" aria-label="" onclick="window.quartoOpenSearch();">
         <i class="bi bi-search"></i>
       </button>
     </div>
@@ -517,7 +517,7 @@ <h2 data-number="12.3" class="anchored" data-anchor-id="sec-what-stack"><span cl
 <p>We begin with a stack of 10 different values, or 10 different plates. Now, imagine that you want to add a new plate (or a new value) to this stack, which translates to the <code>push</code> operation. You would add this plate (or this value) by just putting the new plate on the top of the stack. Then, you would increase the stack to 11 plates.</p>
 <p>But how would you remove plates (or remove values) from this stack (a.k.a. the <code>pop</code> operation) ? To do that, we would have to remove the plate on the top of the stack, and, as a result, we would have, once again, 10 plates in the stack.</p>
 <p>This demonstrates the LIFO concept, because the first plate in the stack, which is the plate in the bottom of the stack, is always the last plate to get out of the stack. Think about it. In order to remove this specific plate from the stack, we have to remove all plates in the stack. So every operation in the stack, either insertion or deletion, is always made at the top of the stack. The <a href="#fig-stack" class="quarto-xref">Figure&nbsp;<span>12.1</span></a> below exposes this logic visually:</p>
-<div id="fig-stack" class="quarto-float quarto-figure quarto-figure-center anchored">
+<div id="fig-stack" class="quarto-figure quarto-figure-center quarto-float anchored">
 <figure class="quarto-float quarto-float-fig figure">
 <div aria-describedby="fig-stack-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
 <img src="./../Figures/lifo-stack.svg" class="img-fluid figure-img">
@@ -881,7 +881,18 @@ <h2 data-number="12.6" class="anchored" data-anchor-id="conclusion"><span class=
     }
     return false;
   }
-  const onCopySuccess = function(e) {
+  const clipboard = new window.ClipboardJS('.code-copy-button', {
+    text: function(trigger) {
+      const codeEl = trigger.previousElementSibling.cloneNode(true);
+      for (const childEl of codeEl.children) {
+        if (isCodeAnnotation(childEl)) {
+          childEl.remove();
+        }
+      }
+      return codeEl.innerText;
+    }
+  });
+  clipboard.on('success', function(e) {
     // button target
     const button = e.trigger;
     // don't keep focus
@@ -913,29 +924,7 @@ <h2 data-number="12.6" class="anchored" data-anchor-id="conclusion"><span class=
     }, 1000);
     // clear code selection
     e.clearSelection();
-  }
-  const getTextToCopy = function(trigger) {
-      const codeEl = trigger.previousElementSibling.cloneNode(true);
-      for (const childEl of codeEl.children) {
-        if (isCodeAnnotation(childEl)) {
-          childEl.remove();
-        }
-      }
-      return codeEl.innerText;
-  }
-  const clipboard = new window.ClipboardJS('.code-copy-button:not([data-in-quarto-modal])', {
-    text: getTextToCopy
   });
-  clipboard.on('success', onCopySuccess);
-  if (window.document.getElementById('quarto-embedded-source-code-modal')) {
-    // For code content inside modals, clipBoardJS needs to be initialized with a container option
-    // TODO: Check when it could be a function (https://github.com/zenorocha/clipboard.js/issues/860)
-    const clipboardModal = new window.ClipboardJS('.code-copy-button[data-in-quarto-modal]', {
-      text: getTextToCopy,
-      container: window.document.getElementById('quarto-embedded-source-code-modal')
-    });
-    clipboardModal.on('success', onCopySuccess);
-  }
     var localhostRegex = new RegExp(/^(?:http|https):\/\/localhost\:?[0-9]*\//);
     var mailtoRegex = new RegExp(/^mailto:/);
       var filterRegex = new RegExp('/' + window.location.host + '/');
@@ -943,7 +932,7 @@ <h2 data-number="12.6" class="anchored" data-anchor-id="conclusion"><span class=
         return filterRegex.test(href) || localhostRegex.test(href) || mailtoRegex.test(href);
     }
     // Inspect non-navigation links and adorn them if external
- 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool):not(.about-link)');
+ 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool)');
     for (var i=0; i<links.length; i++) {
       const link = links[i];
       if (!isInternal(link.href)) {
diff --git a/docs/Chapters/12-file-op.html b/docs/Chapters/12-file-op.html
index 916de07c..d600efdc 100644
--- a/docs/Chapters/12-file-op.html
+++ b/docs/Chapters/12-file-op.html
@@ -2,12 +2,12 @@
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
 
 <meta charset="utf-8">
-<meta name="generator" content="quarto-1.5.57">
+<meta name="generator" content="quarto-1.4.554">
 
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 
-<title>13&nbsp; Filesystem and Input/Output (IO) – Introduction to Zig</title>
+<title>Introduction to Zig - 13&nbsp; Filesystem and Input/Output (IO)</title>
 <style>
 code{white-space: pre-wrap;}
 span.smallcaps{font-variant: small-caps;}
@@ -172,13 +172,13 @@
   <header id="quarto-header" class="headroom fixed-top">
   <nav class="quarto-secondary-nav">
     <div class="container-fluid d-flex">
-      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" role="button" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
+      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
         <i class="bi bi-layout-text-sidebar-reverse"></i>
       </button>
         <nav class="quarto-page-breadcrumbs" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item"><a href="../Chapters/12-file-op.html"><span class="chapter-number">13</span>&nbsp; <span class="chapter-title">Filesystem and Input/Output (IO)</span></a></li></ol></nav>
-        <a class="flex-grow-1" role="navigation" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
+        <a class="flex-grow-1" role="button" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
         </a>
-      <button type="button" class="btn quarto-search-button" aria-label="Search" onclick="window.quartoOpenSearch();">
+      <button type="button" class="btn quarto-search-button" aria-label="" onclick="window.quartoOpenSearch();">
         <i class="bi bi-search"></i>
       </button>
     </div>
@@ -485,7 +485,7 @@ <h3 data-number="13.2.1" class="anchored" data-anchor-id="understanding-how-buff
 <p>To give a better context to these diagrams, let’s suppose that we have a text file that contains the famous Lorem ipsum text<a href="#fn8" class="footnote-ref" id="fnref8" role="doc-noteref"><sup>8</sup></a> in our filesystem. Let’s also suppose that these diagrams in <a href="#fig-unbuffered-io" class="quarto-xref">Figure&nbsp;<span>13.1</span></a> and <a href="#fig-buffered-io" class="quarto-xref">Figure&nbsp;<span>13.2</span></a> are showing the read operations that we are performing to read the Lorem ipsum text from this text file. The first thing you will notice when looking at these diagrams, is that in an unbuffered environment the read operations leads to many system calls. More precisely, in the diagram exposed in <a href="#fig-unbuffered-io" class="quarto-xref">Figure&nbsp;<span>13.1</span></a> we get one system call per each byte that we read from the text file. On the other hand, in <a href="#fig-buffered-io" class="quarto-xref">Figure&nbsp;<span>13.2</span></a> we have only one system call at the very beginning.</p>
 <p>When we use a buffered IO system, at the first read operation we perform, instead of sending one single byte directly to our program, the OS first sends a chunk of bytes from the file to a buffer object (i.e., an array). This chunk of bytes are cached/stored inside this buffer object.</p>
 <p>Therefore, from now on, for every new read operation that you perform, instead of making a new system call to ask for the next byte in the file to the OS, this read operation is redirected to the buffer object, that have this next byte already cached and ready to go.</p>
-<div id="fig-unbuffered-io" class="quarto-float quarto-figure quarto-figure-center anchored">
+<div id="fig-unbuffered-io" class="quarto-figure quarto-figure-center quarto-float anchored">
 <figure class="quarto-float quarto-float-fig figure">
 <div aria-describedby="fig-unbuffered-io-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
 <img src="./../Figures/unbuffered-io.png" class="img-fluid figure-img" style="width:60.0%">
@@ -495,7 +495,7 @@ <h3 data-number="13.2.1" class="anchored" data-anchor-id="understanding-how-buff
 </figcaption>
 </figure>
 </div>
-<div id="fig-buffered-io" class="quarto-float quarto-figure quarto-figure-center anchored">
+<div id="fig-buffered-io" class="quarto-figure quarto-figure-center quarto-float anchored">
 <figure class="quarto-float quarto-float-fig figure">
 <div aria-describedby="fig-buffered-io-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
 <img src="./../Figures/buffered-io.png" class="img-fluid figure-img">
@@ -573,7 +573,7 @@ <h3 data-number="13.3.1" class="anchored" data-anchor-id="the-concept-of-current
 <p>The working directory is the folder on your computer where you are currently rooted at. In other words, it’s the folder that your program is currently looking at. Therefore, whenever you are executing a program, this program is always working with a specific folder on your computer. It’s always in this folder that the program will initially look for the files you require, and it’s also in this folder that the program will initially save all the files you ask it to save.</p>
 <p>The working directory is determined by the folder from which you invoke your program in the terminal. In other words, if you are in the terminal of your OS, and you execute a binary file (i.e., a program) from this terminal, the folder to which your terminal is pointing at is the current working directory of your program that is being executed.</p>
 <p>In <a href="#fig-cwd" class="quarto-xref">Figure&nbsp;<span>13.3</span></a> we have an example of me executing a program from the terminal. We are executing the program outputted by the <code>zig</code> compiler by compiling the Zig module named <code>hello.zig</code>. The CWD in this case is the <code>zig-book</code> folder. In other words, while the <code>hello.zig</code> program is executing, it will be looking at the <code>zig-book</code> folder, and any file operation that we perform inside this program, will be using this <code>zig-book</code> folder as the “starting point”, or, as the “central focus”.</p>
-<div id="fig-cwd" class="quarto-float quarto-figure quarto-figure-center anchored">
+<div id="fig-cwd" class="quarto-figure quarto-figure-center quarto-float anchored">
 <figure class="quarto-float quarto-float-fig figure">
 <div aria-describedby="fig-cwd-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
 <img src="./../Figures/cwd.png" class="img-fluid figure-img">
@@ -977,7 +977,18 @@ <h2 data-number="13.8" class="anchored" data-anchor-id="conclusion"><span class=
     }
     return false;
   }
-  const onCopySuccess = function(e) {
+  const clipboard = new window.ClipboardJS('.code-copy-button', {
+    text: function(trigger) {
+      const codeEl = trigger.previousElementSibling.cloneNode(true);
+      for (const childEl of codeEl.children) {
+        if (isCodeAnnotation(childEl)) {
+          childEl.remove();
+        }
+      }
+      return codeEl.innerText;
+    }
+  });
+  clipboard.on('success', function(e) {
     // button target
     const button = e.trigger;
     // don't keep focus
@@ -1009,29 +1020,7 @@ <h2 data-number="13.8" class="anchored" data-anchor-id="conclusion"><span class=
     }, 1000);
     // clear code selection
     e.clearSelection();
-  }
-  const getTextToCopy = function(trigger) {
-      const codeEl = trigger.previousElementSibling.cloneNode(true);
-      for (const childEl of codeEl.children) {
-        if (isCodeAnnotation(childEl)) {
-          childEl.remove();
-        }
-      }
-      return codeEl.innerText;
-  }
-  const clipboard = new window.ClipboardJS('.code-copy-button:not([data-in-quarto-modal])', {
-    text: getTextToCopy
   });
-  clipboard.on('success', onCopySuccess);
-  if (window.document.getElementById('quarto-embedded-source-code-modal')) {
-    // For code content inside modals, clipBoardJS needs to be initialized with a container option
-    // TODO: Check when it could be a function (https://github.com/zenorocha/clipboard.js/issues/860)
-    const clipboardModal = new window.ClipboardJS('.code-copy-button[data-in-quarto-modal]', {
-      text: getTextToCopy,
-      container: window.document.getElementById('quarto-embedded-source-code-modal')
-    });
-    clipboardModal.on('success', onCopySuccess);
-  }
     var localhostRegex = new RegExp(/^(?:http|https):\/\/localhost\:?[0-9]*\//);
     var mailtoRegex = new RegExp(/^mailto:/);
       var filterRegex = new RegExp('/' + window.location.host + '/');
@@ -1039,7 +1028,7 @@ <h2 data-number="13.8" class="anchored" data-anchor-id="conclusion"><span class=
         return filterRegex.test(href) || localhostRegex.test(href) || mailtoRegex.test(href);
     }
     // Inspect non-navigation links and adorn them if external
- 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool):not(.about-link)');
+ 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool)');
     for (var i=0; i<links.length; i++) {
       const link = links[i];
       if (!isInternal(link.href)) {
diff --git a/docs/Chapters/13-image-filter.html b/docs/Chapters/13-image-filter.html
index 8c893a3c..6bb099b3 100644
--- a/docs/Chapters/13-image-filter.html
+++ b/docs/Chapters/13-image-filter.html
@@ -2,12 +2,12 @@
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
 
 <meta charset="utf-8">
-<meta name="generator" content="quarto-1.5.57">
+<meta name="generator" content="quarto-1.4.554">
 
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 
-<title>15&nbsp; Project 4 - Developing an image filter – Introduction to Zig</title>
+<title>Introduction to Zig - 15&nbsp; Project 4 - Developing an image filter</title>
 <style>
 code{white-space: pre-wrap;}
 span.smallcaps{font-variant: small-caps;}
@@ -172,13 +172,13 @@
   <header id="quarto-header" class="headroom fixed-top">
   <nav class="quarto-secondary-nav">
     <div class="container-fluid d-flex">
-      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" role="button" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
+      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
         <i class="bi bi-layout-text-sidebar-reverse"></i>
       </button>
         <nav class="quarto-page-breadcrumbs" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item"><a href="../Chapters/13-image-filter.html"><span class="chapter-number">15</span>&nbsp; <span class="chapter-title">Project 4 - Developing an image filter</span></a></li></ol></nav>
-        <a class="flex-grow-1" role="navigation" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
+        <a class="flex-grow-1" role="button" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
         </a>
-      <button type="button" class="btn quarto-search-button" aria-label="Search" onclick="window.quartoOpenSearch();">
+      <button type="button" class="btn quarto-search-button" aria-label="" onclick="window.quartoOpenSearch();">
         <i class="bi bi-search"></i>
       </button>
     </div>
@@ -371,7 +371,7 @@ <h1 class="title"><span class="chapter-number">15</span>&nbsp; <span class="chap
 
 <p>In this chapter we are going to build a new project. The objective of this project is to write a program that applies a filter over an image. More specifically, a “grayscale filter”, which transforms any color image into a grayscale image.</p>
 <p>We are going to use the image displayed in <a href="#fig-pascal" class="quarto-xref">Figure&nbsp;<span>15.1</span></a> in this project. In other words, we want to transform this colored image into a grayscale image, by using our “image filter program” written in Zig.</p>
-<div id="fig-pascal" class="quarto-float quarto-figure quarto-figure-center anchored">
+<div id="fig-pascal" class="quarto-figure quarto-figure-center quarto-float anchored">
 <figure class="quarto-float quarto-float-fig figure">
 <div aria-describedby="fig-pascal-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
 <img src="../ZigExamples/image_filter/pedro_pascal.png" class="img-fluid figure-img">
@@ -383,7 +383,7 @@ <h1 class="title"><span class="chapter-number">15</span>&nbsp; <span class="chap
 </div>
 <p>We don’t need to write a lot of code to build such “image filter program”. However, we first need to understand how digital images work. That is why we begin this chapter by explaining the theory behind digital images and how colors are represented in modern computers. We also give a brief explanation about the PNG (Portable Network Graphics) file format, which is the format used in the example images.</p>
 <p>At the end of this chapter, we should have a full example of a program that takes the PNG image displayed in <a href="#fig-pascal" class="quarto-xref">Figure&nbsp;<span>15.1</span></a> as input, and writes a new image to the current working directory that is the grayscale version of this input image. This grayscale version of <a href="#fig-pascal" class="quarto-xref">Figure&nbsp;<span>15.1</span></a> is exposed in <a href="#fig-pascal-gray" class="quarto-xref">Figure&nbsp;<span>15.2</span></a>. You can find the full source code of this small project at the <code>ZigExamples/image_filter</code> <a href="https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter">folder at the official repository of this book</a><a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>.</p>
-<div id="fig-pascal-gray" class="quarto-float quarto-figure quarto-figure-center anchored">
+<div id="fig-pascal-gray" class="quarto-figure quarto-figure-center quarto-float anchored">
 <figure class="quarto-float quarto-float-fig figure">
 <div aria-describedby="fig-pascal-gray-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
 <img src="../ZigExamples/image_filter/pedro_pascal_filter.png" class="img-fluid figure-img">
@@ -415,7 +415,7 @@ <h2 data-number="15.2" class="anchored" data-anchor-id="sec-digital-img"><span c
 <p>A digital image is a “digital representation” of an image that we see with our eyes. In other words, a digital image is a “digital representation” of the colors that we see and perceive through the light. In the digital world, we have two types of images, which are: vector images and raster images. Vector images are not described here. So just remember that the content discussed here <strong>is related solely to raster images</strong>, and not vector images.</p>
 <p>A raster image is a type of digital image that is represented as a 2D (two dimensional) matrix of pixels. In other words, every raster image is basically a rectangle of pixels, and each pixel have a particular color. So, a raster image is just a rectangle of pixels, and each of these pixels are displayed in the screen of your computer (or the screen of any other device, e.g.&nbsp;laptop, tablet, smartphone, etc.) as a color.</p>
 <p><a href="#fig-raster" class="quarto-xref">Figure&nbsp;<span>15.3</span></a> demonstrates this idea. If you take any raster image, and you zoom into it very hard, you will see the actual pixels of the image. JPEG, TIFF and PNG are file formats that are commonly used to store raster images.</p>
-<div id="fig-raster" class="quarto-float quarto-figure quarto-figure-center anchored">
+<div id="fig-raster" class="quarto-figure quarto-figure-center quarto-float anchored">
 <figure class="quarto-float quarto-float-fig figure">
 <div aria-describedby="fig-raster-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
 <img src="../Figures/imagem-raster.png" class="img-fluid figure-img">
@@ -432,7 +432,7 @@ <h3 data-number="15.2.1" class="anchored" data-anchor-id="images-are-displayed-f
 <p>This is not a rule written in stone, but the big majority of digital images are displayed from top to bottom and left to right. Most computers screens also follow this pattern. So, the first pixels in the image are the ones that are at the top and left corner of the image. You can find a visual representation of this logic in <a href="#fig-img-display" class="quarto-xref">Figure&nbsp;<span>15.4</span></a>.</p>
 <p>Also notice in <a href="#fig-img-display" class="quarto-xref">Figure&nbsp;<span>15.4</span></a> that, because a raster image is essentially a 2D matrix of pixels, the image is organized into rows and columns of pixels. The columns are defined by the horizontal x axis, while the rows are defined by the vertical y axis.</p>
 <p>Each pixel (i.e., the gray rectangles) exposed in <a href="#fig-img-display" class="quarto-xref">Figure&nbsp;<span>15.4</span></a> contains a number inside of it. These numbers are the indexes of the pixels. You can notice that the first pixels are in the top and left corner, and also, that the indexes of these pixels “grow to the sides”, or, in other words, they grow in the direction of the horizontal x axis. Most raster images are organized as rows of pixels. Thus, when these digital images are displayed, the screen display the first row of pixels, then, the second row, then, the third row, etc.</p>
-<div id="fig-img-display" class="quarto-float quarto-figure quarto-figure-center anchored">
+<div id="fig-img-display" class="quarto-figure quarto-figure-center quarto-float anchored">
 <figure class="quarto-float quarto-float-fig figure">
 <div aria-describedby="fig-img-display-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
 <img src="./../Figures/image-display.png" class="img-fluid figure-img">
@@ -889,7 +889,18 @@ <h2 data-number="15.7" class="anchored" data-anchor-id="building-our-project"><s
     }
     return false;
   }
-  const onCopySuccess = function(e) {
+  const clipboard = new window.ClipboardJS('.code-copy-button', {
+    text: function(trigger) {
+      const codeEl = trigger.previousElementSibling.cloneNode(true);
+      for (const childEl of codeEl.children) {
+        if (isCodeAnnotation(childEl)) {
+          childEl.remove();
+        }
+      }
+      return codeEl.innerText;
+    }
+  });
+  clipboard.on('success', function(e) {
     // button target
     const button = e.trigger;
     // don't keep focus
@@ -921,29 +932,7 @@ <h2 data-number="15.7" class="anchored" data-anchor-id="building-our-project"><s
     }, 1000);
     // clear code selection
     e.clearSelection();
-  }
-  const getTextToCopy = function(trigger) {
-      const codeEl = trigger.previousElementSibling.cloneNode(true);
-      for (const childEl of codeEl.children) {
-        if (isCodeAnnotation(childEl)) {
-          childEl.remove();
-        }
-      }
-      return codeEl.innerText;
-  }
-  const clipboard = new window.ClipboardJS('.code-copy-button:not([data-in-quarto-modal])', {
-    text: getTextToCopy
   });
-  clipboard.on('success', onCopySuccess);
-  if (window.document.getElementById('quarto-embedded-source-code-modal')) {
-    // For code content inside modals, clipBoardJS needs to be initialized with a container option
-    // TODO: Check when it could be a function (https://github.com/zenorocha/clipboard.js/issues/860)
-    const clipboardModal = new window.ClipboardJS('.code-copy-button[data-in-quarto-modal]', {
-      text: getTextToCopy,
-      container: window.document.getElementById('quarto-embedded-source-code-modal')
-    });
-    clipboardModal.on('success', onCopySuccess);
-  }
     var localhostRegex = new RegExp(/^(?:http|https):\/\/localhost\:?[0-9]*\//);
     var mailtoRegex = new RegExp(/^mailto:/);
       var filterRegex = new RegExp('/' + window.location.host + '/');
@@ -951,7 +940,7 @@ <h2 data-number="15.7" class="anchored" data-anchor-id="building-our-project"><s
         return filterRegex.test(href) || localhostRegex.test(href) || mailtoRegex.test(href);
     }
     // Inspect non-navigation links and adorn them if external
- 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool):not(.about-link)');
+ 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool)');
     for (var i=0; i<links.length; i++) {
       const link = links[i];
       if (!isInternal(link.href)) {
diff --git a/docs/Chapters/14-threads.html b/docs/Chapters/14-threads.html
index 6bfb842d..08dffbd0 100644
--- a/docs/Chapters/14-threads.html
+++ b/docs/Chapters/14-threads.html
@@ -2,12 +2,12 @@
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
 
 <meta charset="utf-8">
-<meta name="generator" content="quarto-1.5.57">
+<meta name="generator" content="quarto-1.4.554">
 
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 
-<title>16&nbsp; Introducing threads and parallelism in Zig – Introduction to Zig</title>
+<title>Introduction to Zig - 16&nbsp; Introducing threads and parallelism in Zig</title>
 <style>
 code{white-space: pre-wrap;}
 span.smallcaps{font-variant: small-caps;}
@@ -172,13 +172,13 @@
   <header id="quarto-header" class="headroom fixed-top">
   <nav class="quarto-secondary-nav">
     <div class="container-fluid d-flex">
-      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" role="button" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
+      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
         <i class="bi bi-layout-text-sidebar-reverse"></i>
       </button>
         <nav class="quarto-page-breadcrumbs" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item"><a href="../Chapters/14-threads.html"><span class="chapter-number">16</span>&nbsp; <span class="chapter-title">Introducing threads and parallelism in Zig</span></a></li></ol></nav>
-        <a class="flex-grow-1" role="navigation" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
+        <a class="flex-grow-1" role="button" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
         </a>
-      <button type="button" class="btn quarto-search-button" aria-label="Search" onclick="window.quartoOpenSearch();">
+      <button type="button" class="btn quarto-search-button" aria-label="" onclick="window.quartoOpenSearch();">
         <i class="bi bi-search"></i>
       </button>
     </div>
@@ -660,13 +660,13 @@ <h3 data-number="16.6.3" class="anchored" data-anchor-id="data-races-and-race-co
 </ol>
 <p>Ideally, a thread B should read the value of <code>count</code>, only after the other thread A has finished writing the incremented value back into the <code>count</code> object. Therefore, in the ideal scenario, which is demonstrated in <a href="#tbl-data-race-ideal" class="quarto-xref">Table&nbsp;<span>16.1</span></a>, the threads should work in sync with each other. But the reality is that these threads are out of sync, and because of that, they suffer from a data race problem, which is demonstrated in <a href="#tbl-data-race-not" class="quarto-xref">Table&nbsp;<span>16.2</span></a>.</p>
 <p>Notice that, in the data race scenario (<a href="#tbl-data-race-not" class="quarto-xref">Table&nbsp;<span>16.2</span></a>), the read performed by a thread B happens before the write operation of thread A, and that ultimately leads to wrong results at the end of the program. Because when thread B reads the value of the <code>count</code> variable, thread A is still processing the initial value from <code>count</code>, and has not yet written the new, incremented value back to <code>count</code>. As a result, thread B ends up reading the same initial (or “old”) value from <code>count</code> instead of the updated, incremented value that thread A would have written.</p>
-<div id="tbl-data-race-ideal" class="quarto-float quarto-figure quarto-figure-center anchored">
+<div id="tbl-data-race-ideal" class="quarto-float anchored">
 <figure class="quarto-float quarto-float-tbl figure">
 <figcaption class="quarto-float-caption-top quarto-float-caption quarto-float-tbl" id="tbl-data-race-ideal-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
 Table&nbsp;16.1: An ideal scenario for two threads incrementing the same integer value
 </figcaption>
 <div aria-describedby="tbl-data-race-ideal-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
-<table class="caption-top table">
+<table class="table">
 <thead>
 <tr class="header">
 <th>Thread 1</th>
@@ -710,13 +710,13 @@ <h3 data-number="16.6.3" class="anchored" data-anchor-id="data-races-and-race-co
 </div>
 </figure>
 </div>
-<div id="tbl-data-race-not" class="quarto-float quarto-figure quarto-figure-center anchored">
+<div id="tbl-data-race-not" class="quarto-float anchored">
 <figure class="quarto-float quarto-float-tbl figure">
 <figcaption class="quarto-float-caption-top quarto-float-caption quarto-float-tbl" id="tbl-data-race-not-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
 Table&nbsp;16.2: A data race scenario when two threads are incrementing the same integer value
 </figcaption>
 <div aria-describedby="tbl-data-race-not-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
-<table class="caption-top table">
+<table class="table">
 <thead>
 <tr class="header">
 <th>Thread 1</th>
@@ -1145,7 +1145,18 @@ <h3 data-number="16.9.3" class="anchored" data-anchor-id="cancelling-or-killing-
     }
     return false;
   }
-  const onCopySuccess = function(e) {
+  const clipboard = new window.ClipboardJS('.code-copy-button', {
+    text: function(trigger) {
+      const codeEl = trigger.previousElementSibling.cloneNode(true);
+      for (const childEl of codeEl.children) {
+        if (isCodeAnnotation(childEl)) {
+          childEl.remove();
+        }
+      }
+      return codeEl.innerText;
+    }
+  });
+  clipboard.on('success', function(e) {
     // button target
     const button = e.trigger;
     // don't keep focus
@@ -1177,29 +1188,7 @@ <h3 data-number="16.9.3" class="anchored" data-anchor-id="cancelling-or-killing-
     }, 1000);
     // clear code selection
     e.clearSelection();
-  }
-  const getTextToCopy = function(trigger) {
-      const codeEl = trigger.previousElementSibling.cloneNode(true);
-      for (const childEl of codeEl.children) {
-        if (isCodeAnnotation(childEl)) {
-          childEl.remove();
-        }
-      }
-      return codeEl.innerText;
-  }
-  const clipboard = new window.ClipboardJS('.code-copy-button:not([data-in-quarto-modal])', {
-    text: getTextToCopy
   });
-  clipboard.on('success', onCopySuccess);
-  if (window.document.getElementById('quarto-embedded-source-code-modal')) {
-    // For code content inside modals, clipBoardJS needs to be initialized with a container option
-    // TODO: Check when it could be a function (https://github.com/zenorocha/clipboard.js/issues/860)
-    const clipboardModal = new window.ClipboardJS('.code-copy-button[data-in-quarto-modal]', {
-      text: getTextToCopy,
-      container: window.document.getElementById('quarto-embedded-source-code-modal')
-    });
-    clipboardModal.on('success', onCopySuccess);
-  }
     var localhostRegex = new RegExp(/^(?:http|https):\/\/localhost\:?[0-9]*\//);
     var mailtoRegex = new RegExp(/^mailto:/);
       var filterRegex = new RegExp('/' + window.location.host + '/');
@@ -1207,7 +1196,7 @@ <h3 data-number="16.9.3" class="anchored" data-anchor-id="cancelling-or-killing-
         return filterRegex.test(href) || localhostRegex.test(href) || mailtoRegex.test(href);
     }
     // Inspect non-navigation links and adorn them if external
- 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool):not(.about-link)');
+ 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool)');
     for (var i=0; i<links.length; i++) {
       const link = links[i];
       if (!isInternal(link.href)) {
diff --git a/docs/Chapters/14-zig-c-interop.html b/docs/Chapters/14-zig-c-interop.html
index 6cfe4421..daf651ad 100644
--- a/docs/Chapters/14-zig-c-interop.html
+++ b/docs/Chapters/14-zig-c-interop.html
@@ -2,12 +2,12 @@
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
 
 <meta charset="utf-8">
-<meta name="generator" content="quarto-1.5.57">
+<meta name="generator" content="quarto-1.4.554">
 
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 
-<title>14&nbsp; Zig interoperability with C – Introduction to Zig</title>
+<title>Introduction to Zig - 14&nbsp; Zig interoperability with C</title>
 <style>
 code{white-space: pre-wrap;}
 span.smallcaps{font-variant: small-caps;}
@@ -123,13 +123,13 @@
   <header id="quarto-header" class="headroom fixed-top">
   <nav class="quarto-secondary-nav">
     <div class="container-fluid d-flex">
-      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" role="button" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
+      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
         <i class="bi bi-layout-text-sidebar-reverse"></i>
       </button>
         <nav class="quarto-page-breadcrumbs" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item"><a href="../Chapters/14-zig-c-interop.html"><span class="chapter-number">14</span>&nbsp; <span class="chapter-title">Zig interoperability with C</span></a></li></ol></nav>
-        <a class="flex-grow-1" role="navigation" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
+        <a class="flex-grow-1" role="button" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
         </a>
-      <button type="button" class="btn quarto-search-button" aria-label="Search" onclick="window.quartoOpenSearch();">
+      <button type="button" class="btn quarto-search-button" aria-label="" onclick="window.quartoOpenSearch();">
         <i class="bi bi-search"></i>
       </button>
     </div>
@@ -769,7 +769,18 @@ <h2 data-number="14.5" class="anchored" data-anchor-id="sec-pass-c-structs"><spa
     }
     return false;
   }
-  const onCopySuccess = function(e) {
+  const clipboard = new window.ClipboardJS('.code-copy-button', {
+    text: function(trigger) {
+      const codeEl = trigger.previousElementSibling.cloneNode(true);
+      for (const childEl of codeEl.children) {
+        if (isCodeAnnotation(childEl)) {
+          childEl.remove();
+        }
+      }
+      return codeEl.innerText;
+    }
+  });
+  clipboard.on('success', function(e) {
     // button target
     const button = e.trigger;
     // don't keep focus
@@ -801,29 +812,7 @@ <h2 data-number="14.5" class="anchored" data-anchor-id="sec-pass-c-structs"><spa
     }, 1000);
     // clear code selection
     e.clearSelection();
-  }
-  const getTextToCopy = function(trigger) {
-      const codeEl = trigger.previousElementSibling.cloneNode(true);
-      for (const childEl of codeEl.children) {
-        if (isCodeAnnotation(childEl)) {
-          childEl.remove();
-        }
-      }
-      return codeEl.innerText;
-  }
-  const clipboard = new window.ClipboardJS('.code-copy-button:not([data-in-quarto-modal])', {
-    text: getTextToCopy
   });
-  clipboard.on('success', onCopySuccess);
-  if (window.document.getElementById('quarto-embedded-source-code-modal')) {
-    // For code content inside modals, clipBoardJS needs to be initialized with a container option
-    // TODO: Check when it could be a function (https://github.com/zenorocha/clipboard.js/issues/860)
-    const clipboardModal = new window.ClipboardJS('.code-copy-button[data-in-quarto-modal]', {
-      text: getTextToCopy,
-      container: window.document.getElementById('quarto-embedded-source-code-modal')
-    });
-    clipboardModal.on('success', onCopySuccess);
-  }
     var localhostRegex = new RegExp(/^(?:http|https):\/\/localhost\:?[0-9]*\//);
     var mailtoRegex = new RegExp(/^mailto:/);
       var filterRegex = new RegExp('/' + window.location.host + '/');
@@ -831,7 +820,7 @@ <h2 data-number="14.5" class="anchored" data-anchor-id="sec-pass-c-structs"><spa
         return filterRegex.test(href) || localhostRegex.test(href) || mailtoRegex.test(href);
     }
     // Inspect non-navigation links and adorn them if external
- 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool):not(.about-link)');
+ 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool)');
     for (var i=0; i<links.length; i++) {
       const link = links[i];
       if (!isInternal(link.href)) {
diff --git a/docs/Chapters/15-vectors.html b/docs/Chapters/15-vectors.html
index 708d14bb..1298bb04 100644
--- a/docs/Chapters/15-vectors.html
+++ b/docs/Chapters/15-vectors.html
@@ -2,12 +2,12 @@
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
 
 <meta charset="utf-8">
-<meta name="generator" content="quarto-1.5.57">
+<meta name="generator" content="quarto-1.4.554">
 
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 
-<title>17&nbsp; Introducing Vectors and SIMD – Introduction to Zig</title>
+<title>Introduction to Zig - 17&nbsp; Introducing Vectors and SIMD</title>
 <style>
 code{white-space: pre-wrap;}
 span.smallcaps{font-variant: small-caps;}
@@ -152,13 +152,13 @@
   <header id="quarto-header" class="headroom fixed-top">
   <nav class="quarto-secondary-nav">
     <div class="container-fluid d-flex">
-      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" role="button" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
+      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
         <i class="bi bi-layout-text-sidebar-reverse"></i>
       </button>
         <nav class="quarto-page-breadcrumbs" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item"><a href="../Chapters/15-vectors.html"><span class="chapter-number">17</span>&nbsp; <span class="chapter-title">Introducing Vectors and SIMD</span></a></li></ol></nav>
-        <a class="flex-grow-1" role="navigation" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
+        <a class="flex-grow-1" role="button" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
         </a>
-      <button type="button" class="btn quarto-search-button" aria-label="Search" onclick="window.quartoOpenSearch();">
+      <button type="button" class="btn quarto-search-button" aria-label="" onclick="window.quartoOpenSearch();">
         <i class="bi bi-search"></i>
       </button>
     </div>
@@ -589,7 +589,18 @@ <h3 data-number="17.2.3" class="anchored" data-anchor-id="careful-with-vectors-t
     }
     return false;
   }
-  const onCopySuccess = function(e) {
+  const clipboard = new window.ClipboardJS('.code-copy-button', {
+    text: function(trigger) {
+      const codeEl = trigger.previousElementSibling.cloneNode(true);
+      for (const childEl of codeEl.children) {
+        if (isCodeAnnotation(childEl)) {
+          childEl.remove();
+        }
+      }
+      return codeEl.innerText;
+    }
+  });
+  clipboard.on('success', function(e) {
     // button target
     const button = e.trigger;
     // don't keep focus
@@ -621,29 +632,7 @@ <h3 data-number="17.2.3" class="anchored" data-anchor-id="careful-with-vectors-t
     }, 1000);
     // clear code selection
     e.clearSelection();
-  }
-  const getTextToCopy = function(trigger) {
-      const codeEl = trigger.previousElementSibling.cloneNode(true);
-      for (const childEl of codeEl.children) {
-        if (isCodeAnnotation(childEl)) {
-          childEl.remove();
-        }
-      }
-      return codeEl.innerText;
-  }
-  const clipboard = new window.ClipboardJS('.code-copy-button:not([data-in-quarto-modal])', {
-    text: getTextToCopy
   });
-  clipboard.on('success', onCopySuccess);
-  if (window.document.getElementById('quarto-embedded-source-code-modal')) {
-    // For code content inside modals, clipBoardJS needs to be initialized with a container option
-    // TODO: Check when it could be a function (https://github.com/zenorocha/clipboard.js/issues/860)
-    const clipboardModal = new window.ClipboardJS('.code-copy-button[data-in-quarto-modal]', {
-      text: getTextToCopy,
-      container: window.document.getElementById('quarto-embedded-source-code-modal')
-    });
-    clipboardModal.on('success', onCopySuccess);
-  }
     var localhostRegex = new RegExp(/^(?:http|https):\/\/localhost\:?[0-9]*\//);
     var mailtoRegex = new RegExp(/^mailto:/);
       var filterRegex = new RegExp('/' + window.location.host + '/');
@@ -651,7 +640,7 @@ <h3 data-number="17.2.3" class="anchored" data-anchor-id="careful-with-vectors-t
         return filterRegex.test(href) || localhostRegex.test(href) || mailtoRegex.test(href);
     }
     // Inspect non-navigation links and adorn them if external
- 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool):not(.about-link)');
+ 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool)');
     for (var i=0; i<links.length; i++) {
       const link = links[i];
       if (!isInternal(link.href)) {
diff --git a/docs/index.html b/docs/index.html
index ddb5b3ed..224b605c 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -2,12 +2,12 @@
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
 
 <meta charset="utf-8">
-<meta name="generator" content="quarto-1.5.57">
+<meta name="generator" content="quarto-1.4.554">
 
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 <meta name="author" content="Pedro Duarte Faria">
-<meta name="dcterms.date" content="2025-04-09">
+<meta name="dcterms.date" content="2025-05-25">
 
 <title>Introduction to Zig</title>
 <style>
@@ -90,13 +90,13 @@
   <header id="quarto-header" class="headroom fixed-top">
   <nav class="quarto-secondary-nav">
     <div class="container-fluid d-flex">
-      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" role="button" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
+      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
         <i class="bi bi-layout-text-sidebar-reverse"></i>
       </button>
         <nav class="quarto-page-breadcrumbs" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item"><a href="./index.html">Welcome</a></li></ol></nav>
-        <a class="flex-grow-1" role="navigation" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
+        <a class="flex-grow-1" role="button" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
         </a>
-      <button type="button" class="btn quarto-search-button" aria-label="Search" onclick="window.quartoOpenSearch();">
+      <button type="button" class="btn quarto-search-button" aria-label="" onclick="window.quartoOpenSearch();">
         <i class="bi bi-search"></i>
       </button>
     </div>
@@ -287,7 +287,7 @@ <h1 class="title">Introduction to Zig</h1>
     <div>
     <div class="quarto-title-meta-heading">Published</div>
     <div class="quarto-title-meta-contents">
-      <p class="date">April 9, 2025</p>
+      <p class="date">May 25, 2025</p>
     </div>
   </div>
   
@@ -649,7 +649,18 @@ <h2 class="unnumbered anchored" data-anchor-id="acknowledgments">Acknowledgments
     }
     return false;
   }
-  const onCopySuccess = function(e) {
+  const clipboard = new window.ClipboardJS('.code-copy-button', {
+    text: function(trigger) {
+      const codeEl = trigger.previousElementSibling.cloneNode(true);
+      for (const childEl of codeEl.children) {
+        if (isCodeAnnotation(childEl)) {
+          childEl.remove();
+        }
+      }
+      return codeEl.innerText;
+    }
+  });
+  clipboard.on('success', function(e) {
     // button target
     const button = e.trigger;
     // don't keep focus
@@ -681,29 +692,7 @@ <h2 class="unnumbered anchored" data-anchor-id="acknowledgments">Acknowledgments
     }, 1000);
     // clear code selection
     e.clearSelection();
-  }
-  const getTextToCopy = function(trigger) {
-      const codeEl = trigger.previousElementSibling.cloneNode(true);
-      for (const childEl of codeEl.children) {
-        if (isCodeAnnotation(childEl)) {
-          childEl.remove();
-        }
-      }
-      return codeEl.innerText;
-  }
-  const clipboard = new window.ClipboardJS('.code-copy-button:not([data-in-quarto-modal])', {
-    text: getTextToCopy
   });
-  clipboard.on('success', onCopySuccess);
-  if (window.document.getElementById('quarto-embedded-source-code-modal')) {
-    // For code content inside modals, clipBoardJS needs to be initialized with a container option
-    // TODO: Check when it could be a function (https://github.com/zenorocha/clipboard.js/issues/860)
-    const clipboardModal = new window.ClipboardJS('.code-copy-button[data-in-quarto-modal]', {
-      text: getTextToCopy,
-      container: window.document.getElementById('quarto-embedded-source-code-modal')
-    });
-    clipboardModal.on('success', onCopySuccess);
-  }
     var localhostRegex = new RegExp(/^(?:http|https):\/\/localhost\:?[0-9]*\//);
     var mailtoRegex = new RegExp(/^mailto:/);
       var filterRegex = new RegExp('/' + window.location.host + '/');
@@ -711,7 +700,7 @@ <h2 class="unnumbered anchored" data-anchor-id="acknowledgments">Acknowledgments
         return filterRegex.test(href) || localhostRegex.test(href) || mailtoRegex.test(href);
     }
     // Inspect non-navigation links and adorn them if external
- 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool):not(.about-link)');
+ 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool)');
     for (var i=0; i<links.length; i++) {
       const link = links[i];
       if (!isInternal(link.href)) {
diff --git a/docs/references.html b/docs/references.html
index daed75ff..0c25f0f5 100644
--- a/docs/references.html
+++ b/docs/references.html
@@ -2,12 +2,12 @@
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
 
 <meta charset="utf-8">
-<meta name="generator" content="quarto-1.5.57">
+<meta name="generator" content="quarto-1.4.554">
 
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 
-<title>References – Introduction to Zig</title>
+<title>Introduction to Zig - References</title>
 <style>
 code{white-space: pre-wrap;}
 span.smallcaps{font-variant: small-caps;}
@@ -107,13 +107,13 @@
   <header id="quarto-header" class="headroom fixed-top">
   <nav class="quarto-secondary-nav">
     <div class="container-fluid d-flex">
-      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" role="button" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
+      <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
         <i class="bi bi-layout-text-sidebar-reverse"></i>
       </button>
         <nav class="quarto-page-breadcrumbs" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item"><a href="./references.html">References</a></li></ol></nav>
-        <a class="flex-grow-1" role="navigation" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
+        <a class="flex-grow-1" role="button" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
         </a>
-      <button type="button" class="btn quarto-search-button" aria-label="Search" onclick="window.quartoOpenSearch();">
+      <button type="button" class="btn quarto-search-button" aria-label="" onclick="window.quartoOpenSearch();">
         <i class="bi bi-search"></i>
       </button>
     </div>
@@ -257,7 +257,7 @@
 </nav>
 <div id="quarto-sidebar-glass" class="quarto-sidebar-collapse-item" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item"></div>
 <!-- margin-sidebar -->
-    <div id="quarto-margin-sidebar" class="sidebar margin-sidebar zindex-bottom">
+    <div id="quarto-margin-sidebar" class="sidebar margin-sidebar">
         
     </div>
 <!-- main -->
@@ -530,7 +530,18 @@ <h1 class="title">References</h1>
     }
     return false;
   }
-  const onCopySuccess = function(e) {
+  const clipboard = new window.ClipboardJS('.code-copy-button', {
+    text: function(trigger) {
+      const codeEl = trigger.previousElementSibling.cloneNode(true);
+      for (const childEl of codeEl.children) {
+        if (isCodeAnnotation(childEl)) {
+          childEl.remove();
+        }
+      }
+      return codeEl.innerText;
+    }
+  });
+  clipboard.on('success', function(e) {
     // button target
     const button = e.trigger;
     // don't keep focus
@@ -562,29 +573,7 @@ <h1 class="title">References</h1>
     }, 1000);
     // clear code selection
     e.clearSelection();
-  }
-  const getTextToCopy = function(trigger) {
-      const codeEl = trigger.previousElementSibling.cloneNode(true);
-      for (const childEl of codeEl.children) {
-        if (isCodeAnnotation(childEl)) {
-          childEl.remove();
-        }
-      }
-      return codeEl.innerText;
-  }
-  const clipboard = new window.ClipboardJS('.code-copy-button:not([data-in-quarto-modal])', {
-    text: getTextToCopy
   });
-  clipboard.on('success', onCopySuccess);
-  if (window.document.getElementById('quarto-embedded-source-code-modal')) {
-    // For code content inside modals, clipBoardJS needs to be initialized with a container option
-    // TODO: Check when it could be a function (https://github.com/zenorocha/clipboard.js/issues/860)
-    const clipboardModal = new window.ClipboardJS('.code-copy-button[data-in-quarto-modal]', {
-      text: getTextToCopy,
-      container: window.document.getElementById('quarto-embedded-source-code-modal')
-    });
-    clipboardModal.on('success', onCopySuccess);
-  }
     var localhostRegex = new RegExp(/^(?:http|https):\/\/localhost\:?[0-9]*\//);
     var mailtoRegex = new RegExp(/^mailto:/);
       var filterRegex = new RegExp('/' + window.location.host + '/');
@@ -592,7 +581,7 @@ <h1 class="title">References</h1>
         return filterRegex.test(href) || localhostRegex.test(href) || mailtoRegex.test(href);
     }
     // Inspect non-navigation links and adorn them if external
- 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool):not(.about-link)');
+ 	var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool)');
     for (var i=0; i<links.length; i++) {
       const link = links[i];
       if (!isInternal(link.href)) {
diff --git a/docs/site_libs/bootstrap/bootstrap-dark.min.css b/docs/site_libs/bootstrap/bootstrap-dark.min.css
index eca1fc59..cab2b096 100644
--- a/docs/site_libs/bootstrap/bootstrap-dark.min.css
+++ b/docs/site_libs/bootstrap/bootstrap-dark.min.css
@@ -2,11 +2,11 @@
  * Bootstrap  v5.3.1 (https://getbootstrap.com/)
  * Copyright 2011-2023 The Bootstrap Authors
  * Licensed under MIT (https://github.com/twbs/bootstrap/blob/main/LICENSE)
- */@import"https://fonts.googleapis.com/css2?family=Lato:ital,wght@0,400;0,700;1,400&display=swap";:root,[data-bs-theme=light]{--bs-blue: #375a7f;--bs-indigo: #6610f2;--bs-purple: #6f42c1;--bs-pink: #e83e8c;--bs-red: #e74c3c;--bs-orange: #fd7e14;--bs-yellow: #f39c12;--bs-green: #00bc8c;--bs-teal: #20c997;--bs-cyan: #3498db;--bs-black: #000;--bs-white: #fff;--bs-gray: #6c757d;--bs-gray-dark: #343a40;--bs-gray-100: #f8f9fa;--bs-gray-200: #ebebeb;--bs-gray-300: #dee2e6;--bs-gray-400: #ced4da;--bs-gray-500: #adb5bd;--bs-gray-600: #6c757d;--bs-gray-700: #444;--bs-gray-800: #343a40;--bs-gray-900: #222;--bs-default: #434343;--bs-primary: #375a7f;--bs-secondary: #434343;--bs-success: #00bc8c;--bs-info: #3498db;--bs-warning: #f39c12;--bs-danger: #e74c3c;--bs-light: #6f6f6f;--bs-dark: #2d2d2d;--bs-default-rgb: 67, 67, 67;--bs-primary-rgb: 55, 90, 127;--bs-secondary-rgb: 67, 67, 67;--bs-success-rgb: 0, 188, 140;--bs-info-rgb: 52, 152, 219;--bs-warning-rgb: 243, 156, 18;--bs-danger-rgb: 231, 76, 60;--bs-light-rgb: 111, 111, 111;--bs-dark-rgb: 45, 45, 45;--bs-primary-text-emphasis: #162433;--bs-secondary-text-emphasis: #1b1b1b;--bs-success-text-emphasis: #004b38;--bs-info-text-emphasis: #153d58;--bs-warning-text-emphasis: #613e07;--bs-danger-text-emphasis: #5c1e18;--bs-light-text-emphasis: #444;--bs-dark-text-emphasis: #444;--bs-primary-bg-subtle: #d7dee5;--bs-secondary-bg-subtle: #d9d9d9;--bs-success-bg-subtle: #ccf2e8;--bs-info-bg-subtle: #d6eaf8;--bs-warning-bg-subtle: #fdebd0;--bs-danger-bg-subtle: #fadbd8;--bs-light-bg-subtle: #fcfcfd;--bs-dark-bg-subtle: #ced4da;--bs-primary-border-subtle: #afbdcc;--bs-secondary-border-subtle: #b4b4b4;--bs-success-border-subtle: #99e4d1;--bs-info-border-subtle: #aed6f1;--bs-warning-border-subtle: #fad7a0;--bs-danger-border-subtle: #f5b7b1;--bs-light-border-subtle: #ebebeb;--bs-dark-border-subtle: #adb5bd;--bs-white-rgb: 255, 255, 255;--bs-black-rgb: 0, 0, 0;--bs-font-sans-serif: Lato, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";--bs-font-monospace: SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;--bs-gradient: linear-gradient(180deg, rgba(255, 255, 255, 0.15), rgba(255, 255, 255, 0));--bs-root-font-size: 17px;--bs-body-font-family: Lato, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";--bs-body-font-size:1rem;--bs-body-font-weight: 400;--bs-body-line-height: 1.5;--bs-body-color: #fff;--bs-body-color-rgb: 255, 255, 255;--bs-body-bg: #222;--bs-body-bg-rgb: 34, 34, 34;--bs-emphasis-color: #000;--bs-emphasis-color-rgb: 0, 0, 0;--bs-secondary-color: rgba(255, 255, 255, 0.75);--bs-secondary-color-rgb: 255, 255, 255;--bs-secondary-bg: #ebebeb;--bs-secondary-bg-rgb: 235, 235, 235;--bs-tertiary-color: rgba(255, 255, 255, 0.5);--bs-tertiary-color-rgb: 255, 255, 255;--bs-tertiary-bg: #f8f9fa;--bs-tertiary-bg-rgb: 248, 249, 250;--bs-heading-color: inherit;--bs-link-color: #00bc8c;--bs-link-color-rgb: 0, 188, 140;--bs-link-decoration: underline;--bs-link-hover-color: #009670;--bs-link-hover-color-rgb: 0, 150, 112;--bs-code-color: #7d12ba;--bs-highlight-bg: #fdebd0;--bs-border-width: 1px;--bs-border-style: solid;--bs-border-color: #dee2e6;--bs-border-color-translucent: rgba(0, 0, 0, 0.175);--bs-border-radius: 0.25rem;--bs-border-radius-sm: 0.2em;--bs-border-radius-lg: 0.5rem;--bs-border-radius-xl: 1rem;--bs-border-radius-xxl: 2rem;--bs-border-radius-2xl: var(--bs-border-radius-xxl);--bs-border-radius-pill: 50rem;--bs-box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);--bs-box-shadow-sm: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.075);--bs-box-shadow-lg: 0 1rem 3rem rgba(0, 0, 0, 0.175);--bs-box-shadow-inset: inset 0 1px 2px rgba(0, 0, 0, 0.075);--bs-focus-ring-width: 0.25rem;--bs-focus-ring-opacity: 0.25;--bs-focus-ring-color: rgba(55, 90, 127, 0.25);--bs-form-valid-color: #00bc8c;--bs-form-valid-border-color: #00bc8c;--bs-form-invalid-color: #e74c3c;--bs-form-invalid-border-color: #e74c3c}[data-bs-theme=dark]{color-scheme:dark;--bs-body-color: #dee2e6;--bs-body-color-rgb: 222, 226, 230;--bs-body-bg: #222;--bs-body-bg-rgb: 34, 34, 34;--bs-emphasis-color: #fff;--bs-emphasis-color-rgb: 255, 255, 255;--bs-secondary-color: rgba(222, 226, 230, 0.75);--bs-secondary-color-rgb: 222, 226, 230;--bs-secondary-bg: #343a40;--bs-secondary-bg-rgb: 52, 58, 64;--bs-tertiary-color: rgba(222, 226, 230, 0.5);--bs-tertiary-color-rgb: 222, 226, 230;--bs-tertiary-bg: #2b2e31;--bs-tertiary-bg-rgb: 43, 46, 49;--bs-primary-text-emphasis: #879cb2;--bs-secondary-text-emphasis: #8e8e8e;--bs-success-text-emphasis: #66d7ba;--bs-info-text-emphasis: #85c1e9;--bs-warning-text-emphasis: #f8c471;--bs-danger-text-emphasis: #f1948a;--bs-light-text-emphasis: #f8f9fa;--bs-dark-text-emphasis: #dee2e6;--bs-primary-bg-subtle: #0b1219;--bs-secondary-bg-subtle: #0d0d0d;--bs-success-bg-subtle: #00261c;--bs-info-bg-subtle: #0a1e2c;--bs-warning-bg-subtle: #311f04;--bs-danger-bg-subtle: #2e0f0c;--bs-light-bg-subtle: #343a40;--bs-dark-bg-subtle: #1a1d20;--bs-primary-border-subtle: #21364c;--bs-secondary-border-subtle: #282828;--bs-success-border-subtle: #007154;--bs-info-border-subtle: #1f5b83;--bs-warning-border-subtle: #925e0b;--bs-danger-border-subtle: #8b2e24;--bs-light-border-subtle: #444;--bs-dark-border-subtle: #343a40;--bs-heading-color: inherit;--bs-link-color: #879cb2;--bs-link-hover-color: #9fb0c1;--bs-link-color-rgb: 135, 156, 178;--bs-link-hover-color-rgb: 159, 176, 193;--bs-code-color: white;--bs-border-color: #444;--bs-border-color-translucent: rgba(255, 255, 255, 0.15);--bs-form-valid-color: #66d7ba;--bs-form-valid-border-color: #66d7ba;--bs-form-invalid-color: #f1948a;--bs-form-invalid-border-color: #f1948a}*,*::before,*::after{box-sizing:border-box}:root{font-size:var(--bs-root-font-size)}body{margin:0;font-family:var(--bs-body-font-family);font-size:var(--bs-body-font-size);font-weight:var(--bs-body-font-weight);line-height:var(--bs-body-line-height);color:var(--bs-body-color);text-align:var(--bs-body-text-align);background-color:var(--bs-body-bg);-webkit-text-size-adjust:100%;-webkit-tap-highlight-color:rgba(0,0,0,0)}hr{margin:1rem 0;color:inherit;border:0;border-top:1px solid;opacity:.25}h6,.h6,h5,.h5,h4,.h4,h3,.h3,h2,.h2,h1,.h1{margin-top:0;margin-bottom:.5rem;font-weight:500;line-height:1.2;color:var(--bs-heading-color)}h1,.h1{font-size:calc(1.325rem + 0.9vw)}@media(min-width: 1200px){h1,.h1{font-size:2rem}}h2,.h2{font-size:calc(1.29rem + 0.48vw)}@media(min-width: 1200px){h2,.h2{font-size:1.65rem}}h3,.h3{font-size:calc(1.27rem + 0.24vw)}@media(min-width: 1200px){h3,.h3{font-size:1.45rem}}h4,.h4{font-size:1.25rem}h5,.h5{font-size:1.1rem}h6,.h6{font-size:1rem}p{margin-top:0;margin-bottom:1rem}abbr[title]{text-decoration:underline dotted;-webkit-text-decoration:underline dotted;-moz-text-decoration:underline dotted;-ms-text-decoration:underline dotted;-o-text-decoration:underline dotted;cursor:help;text-decoration-skip-ink:none}address{margin-bottom:1rem;font-style:normal;line-height:inherit}ol,ul{padding-left:2rem}ol,ul,dl{margin-top:0;margin-bottom:1rem}ol ol,ul ul,ol ul,ul ol{margin-bottom:0}dt{font-weight:700}dd{margin-bottom:.5rem;margin-left:0}blockquote{margin:0 0 1rem;padding:.625rem 1.25rem;border-left:.25rem solid #ebebeb}blockquote p:last-child,blockquote ul:last-child,blockquote ol:last-child{margin-bottom:0}b,strong{font-weight:bolder}small,.small{font-size:0.875em}mark,.mark{padding:.1875em;background-color:var(--bs-highlight-bg)}sub,sup{position:relative;font-size:0.75em;line-height:0;vertical-align:baseline}sub{bottom:-0.25em}sup{top:-0.5em}a{color:rgba(var(--bs-link-color-rgb), var(--bs-link-opacity, 1));text-decoration:underline;-webkit-text-decoration:underline;-moz-text-decoration:underline;-ms-text-decoration:underline;-o-text-decoration:underline}a:hover{--bs-link-color-rgb: var(--bs-link-hover-color-rgb)}a:not([href]):not([class]),a:not([href]):not([class]):hover{color:inherit;text-decoration:none}pre,code,kbd,samp{font-family:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace;font-size:1em}pre{display:block;margin-top:0;margin-bottom:1rem;overflow:auto;font-size:0.875em;color:inherit;background-color:#f8f9fa;padding:.5rem;border:1px solid var(--bs-border-color, #dee2e6);border-radius:.25rem}pre code{background-color:rgba(0,0,0,0);font-size:inherit;color:inherit;word-break:normal}code{font-size:0.875em;color:var(--bs-code-color);background-color:#f8f9fa;border-radius:.25rem;padding:.125rem .25rem;word-wrap:break-word}a>code{color:inherit}kbd{padding:.4rem .4rem;font-size:0.875em;color:#222;background-color:#fff;border-radius:.2em}kbd kbd{padding:0;font-size:1em}figure{margin:0 0 1rem}img,svg{vertical-align:middle}table{caption-side:bottom;border-collapse:collapse}caption{padding-top:.5rem;padding-bottom:.5rem;color:rgba(255,255,255,.75);text-align:left}th{text-align:inherit;text-align:-webkit-match-parent}thead,tbody,tfoot,tr,td,th{border-color:inherit;border-style:solid;border-width:0}label{display:inline-block}button{border-radius:0}button:focus:not(:focus-visible){outline:0}input,button,select,optgroup,textarea{margin:0;font-family:inherit;font-size:inherit;line-height:inherit}button,select{text-transform:none}[role=button]{cursor:pointer}select{word-wrap:normal}select:disabled{opacity:1}[list]:not([type=date]):not([type=datetime-local]):not([type=month]):not([type=week]):not([type=time])::-webkit-calendar-picker-indicator{display:none !important}button,[type=button],[type=reset],[type=submit]{-webkit-appearance:button}button:not(:disabled),[type=button]:not(:disabled),[type=reset]:not(:disabled),[type=submit]:not(:disabled){cursor:pointer}::-moz-focus-inner{padding:0;border-style:none}textarea{resize:vertical}fieldset{min-width:0;padding:0;margin:0;border:0}legend{float:left;width:100%;padding:0;margin-bottom:.5rem;font-size:calc(1.275rem + 0.3vw);line-height:inherit}@media(min-width: 1200px){legend{font-size:1.5rem}}legend+*{clear:left}::-webkit-datetime-edit-fields-wrapper,::-webkit-datetime-edit-text,::-webkit-datetime-edit-minute,::-webkit-datetime-edit-hour-field,::-webkit-datetime-edit-day-field,::-webkit-datetime-edit-month-field,::-webkit-datetime-edit-year-field{padding:0}::-webkit-inner-spin-button{height:auto}[type=search]{-webkit-appearance:textfield;outline-offset:-2px}::-webkit-search-decoration{-webkit-appearance:none}::-webkit-color-swatch-wrapper{padding:0}::file-selector-button{font:inherit;-webkit-appearance:button}output{display:inline-block}iframe{border:0}summary{display:list-item;cursor:pointer}progress{vertical-align:baseline}[hidden]{display:none !important}.lead{font-size:1.25rem;font-weight:300}.display-1{font-size:calc(1.625rem + 4.5vw);font-weight:300;line-height:1.2}@media(min-width: 1200px){.display-1{font-size:5rem}}.display-2{font-size:calc(1.575rem + 3.9vw);font-weight:300;line-height:1.2}@media(min-width: 1200px){.display-2{font-size:4.5rem}}.display-3{font-size:calc(1.525rem + 3.3vw);font-weight:300;line-height:1.2}@media(min-width: 1200px){.display-3{font-size:4rem}}.display-4{font-size:calc(1.475rem + 2.7vw);font-weight:300;line-height:1.2}@media(min-width: 1200px){.display-4{font-size:3.5rem}}.display-5{font-size:calc(1.425rem + 2.1vw);font-weight:300;line-height:1.2}@media(min-width: 1200px){.display-5{font-size:3rem}}.display-6{font-size:calc(1.375rem + 1.5vw);font-weight:300;line-height:1.2}@media(min-width: 1200px){.display-6{font-size:2.5rem}}.list-unstyled{padding-left:0;list-style:none}.list-inline{padding-left:0;list-style:none}.list-inline-item{display:inline-block}.list-inline-item:not(:last-child){margin-right:.5rem}.initialism{font-size:0.875em;text-transform:uppercase}.blockquote{margin-bottom:1rem;font-size:1.25rem}.blockquote>:last-child{margin-bottom:0}.blockquote-footer{margin-top:-1rem;margin-bottom:1rem;font-size:0.875em;color:#6c757d}.blockquote-footer::before{content:"— "}.img-fluid{max-width:100%;height:auto}.img-thumbnail{padding:.25rem;background-color:#222;border:1px solid #dee2e6;border-radius:.25rem;max-width:100%;height:auto}.figure{display:inline-block}.figure-img{margin-bottom:.5rem;line-height:1}.figure-caption{font-size:0.875em;color:rgba(255,255,255,.75)}.container,.container-fluid,.container-xxl,.container-xl,.container-lg,.container-md,.container-sm{--bs-gutter-x: 1.5rem;--bs-gutter-y: 0;width:100%;padding-right:calc(var(--bs-gutter-x)*.5);padding-left:calc(var(--bs-gutter-x)*.5);margin-right:auto;margin-left:auto}@media(min-width: 576px){.container-sm,.container{max-width:540px}}@media(min-width: 768px){.container-md,.container-sm,.container{max-width:720px}}@media(min-width: 992px){.container-lg,.container-md,.container-sm,.container{max-width:960px}}@media(min-width: 1200px){.container-xl,.container-lg,.container-md,.container-sm,.container{max-width:1140px}}@media(min-width: 1400px){.container-xxl,.container-xl,.container-lg,.container-md,.container-sm,.container{max-width:1320px}}:root{--bs-breakpoint-xs: 0;--bs-breakpoint-sm: 576px;--bs-breakpoint-md: 768px;--bs-breakpoint-lg: 992px;--bs-breakpoint-xl: 1200px;--bs-breakpoint-xxl: 1400px}.grid{display:grid;grid-template-rows:repeat(var(--bs-rows, 1), 1fr);grid-template-columns:repeat(var(--bs-columns, 12), 1fr);gap:var(--bs-gap, 1.5rem)}.grid .g-col-1{grid-column:auto/span 1}.grid .g-col-2{grid-column:auto/span 2}.grid .g-col-3{grid-column:auto/span 3}.grid .g-col-4{grid-column:auto/span 4}.grid .g-col-5{grid-column:auto/span 5}.grid .g-col-6{grid-column:auto/span 6}.grid .g-col-7{grid-column:auto/span 7}.grid .g-col-8{grid-column:auto/span 8}.grid .g-col-9{grid-column:auto/span 9}.grid .g-col-10{grid-column:auto/span 10}.grid .g-col-11{grid-column:auto/span 11}.grid .g-col-12{grid-column:auto/span 12}.grid .g-start-1{grid-column-start:1}.grid .g-start-2{grid-column-start:2}.grid .g-start-3{grid-column-start:3}.grid .g-start-4{grid-column-start:4}.grid .g-start-5{grid-column-start:5}.grid .g-start-6{grid-column-start:6}.grid .g-start-7{grid-column-start:7}.grid .g-start-8{grid-column-start:8}.grid .g-start-9{grid-column-start:9}.grid .g-start-10{grid-column-start:10}.grid .g-start-11{grid-column-start:11}@media(min-width: 576px){.grid .g-col-sm-1{grid-column:auto/span 1}.grid .g-col-sm-2{grid-column:auto/span 2}.grid .g-col-sm-3{grid-column:auto/span 3}.grid .g-col-sm-4{grid-column:auto/span 4}.grid .g-col-sm-5{grid-column:auto/span 5}.grid .g-col-sm-6{grid-column:auto/span 6}.grid .g-col-sm-7{grid-column:auto/span 7}.grid .g-col-sm-8{grid-column:auto/span 8}.grid .g-col-sm-9{grid-column:auto/span 9}.grid .g-col-sm-10{grid-column:auto/span 10}.grid .g-col-sm-11{grid-column:auto/span 11}.grid .g-col-sm-12{grid-column:auto/span 12}.grid .g-start-sm-1{grid-column-start:1}.grid .g-start-sm-2{grid-column-start:2}.grid .g-start-sm-3{grid-column-start:3}.grid .g-start-sm-4{grid-column-start:4}.grid .g-start-sm-5{grid-column-start:5}.grid .g-start-sm-6{grid-column-start:6}.grid .g-start-sm-7{grid-column-start:7}.grid .g-start-sm-8{grid-column-start:8}.grid .g-start-sm-9{grid-column-start:9}.grid .g-start-sm-10{grid-column-start:10}.grid .g-start-sm-11{grid-column-start:11}}@media(min-width: 768px){.grid .g-col-md-1{grid-column:auto/span 1}.grid .g-col-md-2{grid-column:auto/span 2}.grid .g-col-md-3{grid-column:auto/span 3}.grid .g-col-md-4{grid-column:auto/span 4}.grid .g-col-md-5{grid-column:auto/span 5}.grid .g-col-md-6{grid-column:auto/span 6}.grid .g-col-md-7{grid-column:auto/span 7}.grid .g-col-md-8{grid-column:auto/span 8}.grid .g-col-md-9{grid-column:auto/span 9}.grid .g-col-md-10{grid-column:auto/span 10}.grid .g-col-md-11{grid-column:auto/span 11}.grid .g-col-md-12{grid-column:auto/span 12}.grid .g-start-md-1{grid-column-start:1}.grid .g-start-md-2{grid-column-start:2}.grid .g-start-md-3{grid-column-start:3}.grid .g-start-md-4{grid-column-start:4}.grid .g-start-md-5{grid-column-start:5}.grid .g-start-md-6{grid-column-start:6}.grid .g-start-md-7{grid-column-start:7}.grid .g-start-md-8{grid-column-start:8}.grid .g-start-md-9{grid-column-start:9}.grid .g-start-md-10{grid-column-start:10}.grid .g-start-md-11{grid-column-start:11}}@media(min-width: 992px){.grid .g-col-lg-1{grid-column:auto/span 1}.grid .g-col-lg-2{grid-column:auto/span 2}.grid .g-col-lg-3{grid-column:auto/span 3}.grid .g-col-lg-4{grid-column:auto/span 4}.grid .g-col-lg-5{grid-column:auto/span 5}.grid .g-col-lg-6{grid-column:auto/span 6}.grid .g-col-lg-7{grid-column:auto/span 7}.grid .g-col-lg-8{grid-column:auto/span 8}.grid .g-col-lg-9{grid-column:auto/span 9}.grid .g-col-lg-10{grid-column:auto/span 10}.grid .g-col-lg-11{grid-column:auto/span 11}.grid .g-col-lg-12{grid-column:auto/span 12}.grid .g-start-lg-1{grid-column-start:1}.grid .g-start-lg-2{grid-column-start:2}.grid .g-start-lg-3{grid-column-start:3}.grid .g-start-lg-4{grid-column-start:4}.grid .g-start-lg-5{grid-column-start:5}.grid .g-start-lg-6{grid-column-start:6}.grid .g-start-lg-7{grid-column-start:7}.grid .g-start-lg-8{grid-column-start:8}.grid .g-start-lg-9{grid-column-start:9}.grid .g-start-lg-10{grid-column-start:10}.grid .g-start-lg-11{grid-column-start:11}}@media(min-width: 1200px){.grid .g-col-xl-1{grid-column:auto/span 1}.grid .g-col-xl-2{grid-column:auto/span 2}.grid .g-col-xl-3{grid-column:auto/span 3}.grid .g-col-xl-4{grid-column:auto/span 4}.grid .g-col-xl-5{grid-column:auto/span 5}.grid .g-col-xl-6{grid-column:auto/span 6}.grid .g-col-xl-7{grid-column:auto/span 7}.grid .g-col-xl-8{grid-column:auto/span 8}.grid .g-col-xl-9{grid-column:auto/span 9}.grid .g-col-xl-10{grid-column:auto/span 10}.grid .g-col-xl-11{grid-column:auto/span 11}.grid .g-col-xl-12{grid-column:auto/span 12}.grid .g-start-xl-1{grid-column-start:1}.grid .g-start-xl-2{grid-column-start:2}.grid .g-start-xl-3{grid-column-start:3}.grid .g-start-xl-4{grid-column-start:4}.grid .g-start-xl-5{grid-column-start:5}.grid .g-start-xl-6{grid-column-start:6}.grid .g-start-xl-7{grid-column-start:7}.grid .g-start-xl-8{grid-column-start:8}.grid .g-start-xl-9{grid-column-start:9}.grid .g-start-xl-10{grid-column-start:10}.grid .g-start-xl-11{grid-column-start:11}}@media(min-width: 1400px){.grid .g-col-xxl-1{grid-column:auto/span 1}.grid .g-col-xxl-2{grid-column:auto/span 2}.grid .g-col-xxl-3{grid-column:auto/span 3}.grid .g-col-xxl-4{grid-column:auto/span 4}.grid .g-col-xxl-5{grid-column:auto/span 5}.grid .g-col-xxl-6{grid-column:auto/span 6}.grid .g-col-xxl-7{grid-column:auto/span 7}.grid .g-col-xxl-8{grid-column:auto/span 8}.grid .g-col-xxl-9{grid-column:auto/span 9}.grid .g-col-xxl-10{grid-column:auto/span 10}.grid .g-col-xxl-11{grid-column:auto/span 11}.grid .g-col-xxl-12{grid-column:auto/span 12}.grid .g-start-xxl-1{grid-column-start:1}.grid .g-start-xxl-2{grid-column-start:2}.grid .g-start-xxl-3{grid-column-start:3}.grid .g-start-xxl-4{grid-column-start:4}.grid .g-start-xxl-5{grid-column-start:5}.grid .g-start-xxl-6{grid-column-start:6}.grid .g-start-xxl-7{grid-column-start:7}.grid .g-start-xxl-8{grid-column-start:8}.grid .g-start-xxl-9{grid-column-start:9}.grid .g-start-xxl-10{grid-column-start:10}.grid .g-start-xxl-11{grid-column-start:11}}.table{--bs-table-color-type: initial;--bs-table-bg-type: initial;--bs-table-color-state: initial;--bs-table-bg-state: initial;--bs-table-color: #fff;--bs-table-bg: #222;--bs-table-border-color: #434343;--bs-table-accent-bg: transparent;--bs-table-striped-color: #fff;--bs-table-striped-bg: rgba(0, 0, 0, 0.05);--bs-table-active-color: #fff;--bs-table-active-bg: rgba(0, 0, 0, 0.1);--bs-table-hover-color: #fff;--bs-table-hover-bg: rgba(0, 0, 0, 0.075);width:100%;margin-bottom:1rem;vertical-align:top;border-color:var(--bs-table-border-color)}.table>:not(caption)>*>*{padding:.5rem .5rem;color:var(--bs-table-color-state, var(--bs-table-color-type, var(--bs-table-color)));background-color:var(--bs-table-bg);border-bottom-width:1px;box-shadow:inset 0 0 0 9999px var(--bs-table-bg-state, var(--bs-table-bg-type, var(--bs-table-accent-bg)))}.table>tbody{vertical-align:inherit}.table>thead{vertical-align:bottom}.table-group-divider{border-top:calc(1px*2) solid #fff}.caption-top{caption-side:top}.table-sm>:not(caption)>*>*{padding:.25rem .25rem}.table-bordered>:not(caption)>*{border-width:1px 0}.table-bordered>:not(caption)>*>*{border-width:0 1px}.table-borderless>:not(caption)>*>*{border-bottom-width:0}.table-borderless>:not(:first-child){border-top-width:0}.table-striped>tbody>tr:nth-of-type(odd)>*{--bs-table-color-type: var(--bs-table-striped-color);--bs-table-bg-type: var(--bs-table-striped-bg)}.table-striped-columns>:not(caption)>tr>:nth-child(even){--bs-table-color-type: var(--bs-table-striped-color);--bs-table-bg-type: var(--bs-table-striped-bg)}.table-active{--bs-table-color-state: var(--bs-table-active-color);--bs-table-bg-state: var(--bs-table-active-bg)}.table-hover>tbody>tr:hover>*{--bs-table-color-state: var(--bs-table-hover-color);--bs-table-bg-state: var(--bs-table-hover-bg)}.table-primary{--bs-table-color: #fff;--bs-table-bg: #375a7f;--bs-table-border-color: #4b6b8c;--bs-table-striped-bg: #416285;--bs-table-striped-color: #fff;--bs-table-active-bg: #4b6b8c;--bs-table-active-color: #fff;--bs-table-hover-bg: #466689;--bs-table-hover-color: #fff;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-secondary{--bs-table-color: #fff;--bs-table-bg: #434343;--bs-table-border-color: #565656;--bs-table-striped-bg: #4c4c4c;--bs-table-striped-color: #fff;--bs-table-active-bg: #565656;--bs-table-active-color: #fff;--bs-table-hover-bg: #515151;--bs-table-hover-color: #fff;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-success{--bs-table-color: #fff;--bs-table-bg: #00bc8c;--bs-table-border-color: #1ac398;--bs-table-striped-bg: #0dbf92;--bs-table-striped-color: #fff;--bs-table-active-bg: #1ac398;--bs-table-active-color: #fff;--bs-table-hover-bg: #13c195;--bs-table-hover-color: #fff;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-info{--bs-table-color: #fff;--bs-table-bg: #3498db;--bs-table-border-color: #48a2df;--bs-table-striped-bg: #3e9ddd;--bs-table-striped-color: #fff;--bs-table-active-bg: #48a2df;--bs-table-active-color: #fff;--bs-table-hover-bg: #43a0de;--bs-table-hover-color: #fff;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-warning{--bs-table-color: #fff;--bs-table-bg: #f39c12;--bs-table-border-color: #f4a62a;--bs-table-striped-bg: #f4a11e;--bs-table-striped-color: #fff;--bs-table-active-bg: #f4a62a;--bs-table-active-color: #fff;--bs-table-hover-bg: #f4a324;--bs-table-hover-color: #fff;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-danger{--bs-table-color: #fff;--bs-table-bg: #e74c3c;--bs-table-border-color: #e95e50;--bs-table-striped-bg: #e85546;--bs-table-striped-color: #fff;--bs-table-active-bg: #e95e50;--bs-table-active-color: #fff;--bs-table-hover-bg: #e9594b;--bs-table-hover-color: #fff;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-light{--bs-table-color: #fff;--bs-table-bg: #6f6f6f;--bs-table-border-color: #7d7d7d;--bs-table-striped-bg: #767676;--bs-table-striped-color: #fff;--bs-table-active-bg: #7d7d7d;--bs-table-active-color: #fff;--bs-table-hover-bg: #7a7a7a;--bs-table-hover-color: #fff;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-dark{--bs-table-color: #fff;--bs-table-bg: #2d2d2d;--bs-table-border-color: #424242;--bs-table-striped-bg: #383838;--bs-table-striped-color: #fff;--bs-table-active-bg: #424242;--bs-table-active-color: #fff;--bs-table-hover-bg: #3d3d3d;--bs-table-hover-color: #fff;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-responsive{overflow-x:auto;-webkit-overflow-scrolling:touch}@media(max-width: 575.98px){.table-responsive-sm{overflow-x:auto;-webkit-overflow-scrolling:touch}}@media(max-width: 767.98px){.table-responsive-md{overflow-x:auto;-webkit-overflow-scrolling:touch}}@media(max-width: 991.98px){.table-responsive-lg{overflow-x:auto;-webkit-overflow-scrolling:touch}}@media(max-width: 1199.98px){.table-responsive-xl{overflow-x:auto;-webkit-overflow-scrolling:touch}}@media(max-width: 1399.98px){.table-responsive-xxl{overflow-x:auto;-webkit-overflow-scrolling:touch}}.form-label,.shiny-input-container .control-label{margin-bottom:.5rem}.col-form-label{padding-top:calc(0.375rem + 1px);padding-bottom:calc(0.375rem + 1px);margin-bottom:0;font-size:inherit;line-height:1.5}.col-form-label-lg{padding-top:calc(0.5rem + 1px);padding-bottom:calc(0.5rem + 1px);font-size:1.25rem}.col-form-label-sm{padding-top:calc(0.25rem + 1px);padding-bottom:calc(0.25rem + 1px);font-size:0.875rem}.form-text{margin-top:.25rem;font-size:0.875em;color:rgba(255,255,255,.75)}.form-control{display:block;width:100%;padding:.375rem .75rem;font-size:1rem;font-weight:400;line-height:1.5;color:#2d2d2d;appearance:none;-webkit-appearance:none;-moz-appearance:none;-ms-appearance:none;-o-appearance:none;background-color:#fff;background-clip:padding-box;border:1px solid #adb5bd;border-radius:.25rem;transition:border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media(prefers-reduced-motion: reduce){.form-control{transition:none}}.form-control[type=file]{overflow:hidden}.form-control[type=file]:not(:disabled):not([readonly]){cursor:pointer}.form-control:focus{color:#2d2d2d;background-color:#fff;border-color:#9badbf;outline:0;box-shadow:0 0 0 .25rem rgba(55,90,127,.25)}.form-control::-webkit-date-and-time-value{min-width:85px;height:1.5em;margin:0}.form-control::-webkit-datetime-edit{display:block;padding:0}.form-control::placeholder{color:#595959;opacity:1}.form-control:disabled{background-color:#ebebeb;opacity:1}.form-control::file-selector-button{padding:.375rem .75rem;margin:-0.375rem -0.75rem;margin-inline-end:.75rem;color:#6f6f6f;background-color:#434343;pointer-events:none;border-color:inherit;border-style:solid;border-width:0;border-inline-end-width:1px;border-radius:0;transition:color .15s ease-in-out,background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media(prefers-reduced-motion: reduce){.form-control::file-selector-button{transition:none}}.form-control:hover:not(:disabled):not([readonly])::file-selector-button{background-color:#363636}.form-control-plaintext{display:block;width:100%;padding:.375rem 0;margin-bottom:0;line-height:1.5;color:#fff;background-color:rgba(0,0,0,0);border:solid rgba(0,0,0,0);border-width:1px 0}.form-control-plaintext:focus{outline:0}.form-control-plaintext.form-control-sm,.form-control-plaintext.form-control-lg{padding-right:0;padding-left:0}.form-control-sm{min-height:calc(1.5em + 0.5rem + calc(1px * 2));padding:.25rem .5rem;font-size:0.875rem;border-radius:.2em}.form-control-sm::file-selector-button{padding:.25rem .5rem;margin:-0.25rem -0.5rem;margin-inline-end:.5rem}.form-control-lg{min-height:calc(1.5em + 1rem + calc(1px * 2));padding:.5rem 1rem;font-size:1.25rem;border-radius:.5rem}.form-control-lg::file-selector-button{padding:.5rem 1rem;margin:-0.5rem -1rem;margin-inline-end:1rem}textarea.form-control{min-height:calc(1.5em + 0.75rem + calc(1px * 2))}textarea.form-control-sm{min-height:calc(1.5em + 0.5rem + calc(1px * 2))}textarea.form-control-lg{min-height:calc(1.5em + 1rem + calc(1px * 2))}.form-control-color{width:3rem;height:calc(1.5em + 0.75rem + calc(1px * 2));padding:.375rem}.form-control-color:not(:disabled):not([readonly]){cursor:pointer}.form-control-color::-moz-color-swatch{border:0 !important;border-radius:.25rem}.form-control-color::-webkit-color-swatch{border:0 !important;border-radius:.25rem}.form-control-color.form-control-sm{height:calc(1.5em + 0.5rem + calc(1px * 2))}.form-control-color.form-control-lg{height:calc(1.5em + 1rem + calc(1px * 2))}.form-select{--bs-form-select-bg-img: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3e%3cpath fill='none' stroke='%23343a40' stroke-linecap='round' stroke-linejoin='round' stroke-width='2' d='m2 5 6 6 6-6'/%3e%3c/svg%3e");display:block;width:100%;padding:.375rem 2.25rem .375rem .75rem;font-size:1rem;font-weight:400;line-height:1.5;color:#2d2d2d;appearance:none;-webkit-appearance:none;-moz-appearance:none;-ms-appearance:none;-o-appearance:none;background-color:#fff;background-image:var(--bs-form-select-bg-img),var(--bs-form-select-bg-icon, none);background-repeat:no-repeat;background-position:right .75rem center;background-size:16px 12px;border:1px solid #adb5bd;border-radius:.25rem;transition:border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media(prefers-reduced-motion: reduce){.form-select{transition:none}}.form-select:focus{border-color:#9badbf;outline:0;box-shadow:0 0 0 .25rem rgba(55,90,127,.25)}.form-select[multiple],.form-select[size]:not([size="1"]){padding-right:.75rem;background-image:none}.form-select:disabled{color:#595959;background-color:#ebebeb}.form-select:-moz-focusring{color:rgba(0,0,0,0);text-shadow:0 0 0 #2d2d2d}.form-select-sm{padding-top:.25rem;padding-bottom:.25rem;padding-left:.5rem;font-size:0.875rem;border-radius:.2em}.form-select-lg{padding-top:.5rem;padding-bottom:.5rem;padding-left:1rem;font-size:1.25rem;border-radius:.5rem}[data-bs-theme=dark] .form-select{--bs-form-select-bg-img: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3e%3cpath fill='none' stroke='%23dee2e6' stroke-linecap='round' stroke-linejoin='round' stroke-width='2' d='m2 5 6 6 6-6'/%3e%3c/svg%3e")}.form-check,.shiny-input-container .checkbox,.shiny-input-container .radio{display:block;min-height:1.5rem;padding-left:0;margin-bottom:.125rem}.form-check .form-check-input,.form-check .shiny-input-container .checkbox input,.form-check .shiny-input-container .radio input,.shiny-input-container .checkbox .form-check-input,.shiny-input-container .checkbox .shiny-input-container .checkbox input,.shiny-input-container .checkbox .shiny-input-container .radio input,.shiny-input-container .radio .form-check-input,.shiny-input-container .radio .shiny-input-container .checkbox input,.shiny-input-container .radio .shiny-input-container .radio input{float:left;margin-left:0}.form-check-reverse{padding-right:0;padding-left:0;text-align:right}.form-check-reverse .form-check-input{float:right;margin-right:0;margin-left:0}.form-check-input,.shiny-input-container .checkbox input,.shiny-input-container .checkbox-inline input,.shiny-input-container .radio input,.shiny-input-container .radio-inline input{--bs-form-check-bg: #fff;width:1em;height:1em;margin-top:.25em;vertical-align:top;appearance:none;-webkit-appearance:none;-moz-appearance:none;-ms-appearance:none;-o-appearance:none;background-color:var(--bs-form-check-bg);background-image:var(--bs-form-check-bg-image);background-repeat:no-repeat;background-position:center;background-size:contain;border:none;print-color-adjust:exact}.form-check-input[type=checkbox],.shiny-input-container .checkbox input[type=checkbox],.shiny-input-container .checkbox-inline input[type=checkbox],.shiny-input-container .radio input[type=checkbox],.shiny-input-container .radio-inline input[type=checkbox]{border-radius:.25em}.form-check-input[type=radio],.shiny-input-container .checkbox input[type=radio],.shiny-input-container .checkbox-inline input[type=radio],.shiny-input-container .radio input[type=radio],.shiny-input-container .radio-inline input[type=radio]{border-radius:50%}.form-check-input:active,.shiny-input-container .checkbox input:active,.shiny-input-container .checkbox-inline input:active,.shiny-input-container .radio input:active,.shiny-input-container .radio-inline input:active{filter:brightness(90%)}.form-check-input:focus,.shiny-input-container .checkbox input:focus,.shiny-input-container .checkbox-inline input:focus,.shiny-input-container .radio input:focus,.shiny-input-container .radio-inline input:focus{border-color:#9badbf;outline:0;box-shadow:0 0 0 .25rem rgba(55,90,127,.25)}.form-check-input:checked,.shiny-input-container .checkbox input:checked,.shiny-input-container .checkbox-inline input:checked,.shiny-input-container .radio input:checked,.shiny-input-container .radio-inline input:checked{background-color:#375a7f;border-color:#375a7f}.form-check-input:checked[type=checkbox],.shiny-input-container .checkbox input:checked[type=checkbox],.shiny-input-container .checkbox-inline input:checked[type=checkbox],.shiny-input-container .radio input:checked[type=checkbox],.shiny-input-container .radio-inline input:checked[type=checkbox]{--bs-form-check-bg-image: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20'%3e%3cpath fill='none' stroke='%23fff' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='m6 10 3 3 6-6'/%3e%3c/svg%3e")}.form-check-input:checked[type=radio],.shiny-input-container .checkbox input:checked[type=radio],.shiny-input-container .checkbox-inline input:checked[type=radio],.shiny-input-container .radio input:checked[type=radio],.shiny-input-container .radio-inline input:checked[type=radio]{--bs-form-check-bg-image: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='-4 -4 8 8'%3e%3ccircle r='2' fill='%23fff'/%3e%3c/svg%3e")}.form-check-input[type=checkbox]:indeterminate,.shiny-input-container .checkbox input[type=checkbox]:indeterminate,.shiny-input-container .checkbox-inline input[type=checkbox]:indeterminate,.shiny-input-container .radio input[type=checkbox]:indeterminate,.shiny-input-container .radio-inline input[type=checkbox]:indeterminate{background-color:#375a7f;border-color:#375a7f;--bs-form-check-bg-image: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20'%3e%3cpath fill='none' stroke='%23fff' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='M6 10h8'/%3e%3c/svg%3e")}.form-check-input:disabled,.shiny-input-container .checkbox input:disabled,.shiny-input-container .checkbox-inline input:disabled,.shiny-input-container .radio input:disabled,.shiny-input-container .radio-inline input:disabled{pointer-events:none;filter:none;opacity:.5}.form-check-input[disabled]~.form-check-label,.form-check-input[disabled]~span,.form-check-input:disabled~.form-check-label,.form-check-input:disabled~span,.shiny-input-container .checkbox input[disabled]~.form-check-label,.shiny-input-container .checkbox input[disabled]~span,.shiny-input-container .checkbox input:disabled~.form-check-label,.shiny-input-container .checkbox input:disabled~span,.shiny-input-container .checkbox-inline input[disabled]~.form-check-label,.shiny-input-container .checkbox-inline input[disabled]~span,.shiny-input-container .checkbox-inline input:disabled~.form-check-label,.shiny-input-container .checkbox-inline input:disabled~span,.shiny-input-container .radio input[disabled]~.form-check-label,.shiny-input-container .radio input[disabled]~span,.shiny-input-container .radio input:disabled~.form-check-label,.shiny-input-container .radio input:disabled~span,.shiny-input-container .radio-inline input[disabled]~.form-check-label,.shiny-input-container .radio-inline input[disabled]~span,.shiny-input-container .radio-inline input:disabled~.form-check-label,.shiny-input-container .radio-inline input:disabled~span{cursor:default;opacity:.5}.form-check-label,.shiny-input-container .checkbox label,.shiny-input-container .checkbox-inline label,.shiny-input-container .radio label,.shiny-input-container .radio-inline label{cursor:pointer}.form-switch{padding-left:2.5em}.form-switch .form-check-input{--bs-form-switch-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='-4 -4 8 8'%3e%3ccircle r='3' fill='rgba%280, 0, 0, 0.25%29'/%3e%3c/svg%3e");width:2em;margin-left:-2.5em;background-image:var(--bs-form-switch-bg);background-position:left center;border-radius:2em;transition:background-position .15s ease-in-out}@media(prefers-reduced-motion: reduce){.form-switch .form-check-input{transition:none}}.form-switch .form-check-input:focus{--bs-form-switch-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='-4 -4 8 8'%3e%3ccircle r='3' fill='%239badbf'/%3e%3c/svg%3e")}.form-switch .form-check-input:checked{background-position:right center;--bs-form-switch-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='-4 -4 8 8'%3e%3ccircle r='3' fill='%23fff'/%3e%3c/svg%3e")}.form-switch.form-check-reverse{padding-right:2.5em;padding-left:0}.form-switch.form-check-reverse .form-check-input{margin-right:-2.5em;margin-left:0}.form-check-inline{display:inline-block;margin-right:1rem}.btn-check{position:absolute;clip:rect(0, 0, 0, 0);pointer-events:none}.btn-check[disabled]+.btn,.btn-check:disabled+.btn{pointer-events:none;filter:none;opacity:.65}[data-bs-theme=dark] .form-switch .form-check-input:not(:checked):not(:focus){--bs-form-switch-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='-4 -4 8 8'%3e%3ccircle r='3' fill='rgba%28255, 255, 255, 0.25%29'/%3e%3c/svg%3e")}.form-range{width:100%;height:1.5rem;padding:0;appearance:none;-webkit-appearance:none;-moz-appearance:none;-ms-appearance:none;-o-appearance:none;background-color:rgba(0,0,0,0)}.form-range:focus{outline:0}.form-range:focus::-webkit-slider-thumb{box-shadow:0 0 0 1px #222,0 0 0 .25rem rgba(55,90,127,.25)}.form-range:focus::-moz-range-thumb{box-shadow:0 0 0 1px #222,0 0 0 .25rem rgba(55,90,127,.25)}.form-range::-moz-focus-outer{border:0}.form-range::-webkit-slider-thumb{width:1rem;height:1rem;margin-top:-0.25rem;appearance:none;-webkit-appearance:none;-moz-appearance:none;-ms-appearance:none;-o-appearance:none;background-color:#375a7f;border:0;border-radius:1rem;transition:background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media(prefers-reduced-motion: reduce){.form-range::-webkit-slider-thumb{transition:none}}.form-range::-webkit-slider-thumb:active{background-color:#c3ced9}.form-range::-webkit-slider-runnable-track{width:100%;height:.5rem;color:rgba(0,0,0,0);cursor:pointer;background-color:#f8f9fa;border-color:rgba(0,0,0,0);border-radius:1rem}.form-range::-moz-range-thumb{width:1rem;height:1rem;appearance:none;-webkit-appearance:none;-moz-appearance:none;-ms-appearance:none;-o-appearance:none;background-color:#375a7f;border:0;border-radius:1rem;transition:background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media(prefers-reduced-motion: reduce){.form-range::-moz-range-thumb{transition:none}}.form-range::-moz-range-thumb:active{background-color:#c3ced9}.form-range::-moz-range-track{width:100%;height:.5rem;color:rgba(0,0,0,0);cursor:pointer;background-color:#f8f9fa;border-color:rgba(0,0,0,0);border-radius:1rem}.form-range:disabled{pointer-events:none}.form-range:disabled::-webkit-slider-thumb{background-color:rgba(255,255,255,.75)}.form-range:disabled::-moz-range-thumb{background-color:rgba(255,255,255,.75)}.form-floating{position:relative}.form-floating>.form-control,.form-floating>.form-control-plaintext,.form-floating>.form-select{height:calc(3.5rem + calc(1px * 2));min-height:calc(3.5rem + calc(1px * 2));line-height:1.25}.form-floating>label{position:absolute;top:0;left:0;z-index:2;height:100%;padding:1rem .75rem;overflow:hidden;text-align:start;text-overflow:ellipsis;white-space:nowrap;pointer-events:none;border:1px solid rgba(0,0,0,0);transform-origin:0 0;transition:opacity .1s ease-in-out,transform .1s ease-in-out}@media(prefers-reduced-motion: reduce){.form-floating>label{transition:none}}.form-floating>.form-control,.form-floating>.form-control-plaintext{padding:1rem .75rem}.form-floating>.form-control::placeholder,.form-floating>.form-control-plaintext::placeholder{color:rgba(0,0,0,0)}.form-floating>.form-control:focus,.form-floating>.form-control:not(:placeholder-shown),.form-floating>.form-control-plaintext:focus,.form-floating>.form-control-plaintext:not(:placeholder-shown){padding-top:1.625rem;padding-bottom:.625rem}.form-floating>.form-control:-webkit-autofill,.form-floating>.form-control-plaintext:-webkit-autofill{padding-top:1.625rem;padding-bottom:.625rem}.form-floating>.form-select{padding-top:1.625rem;padding-bottom:.625rem}.form-floating>.form-control:focus~label,.form-floating>.form-control:not(:placeholder-shown)~label,.form-floating>.form-control-plaintext~label,.form-floating>.form-select~label{color:rgba(var(--bs-body-color-rgb), 0.65);transform:scale(0.85) translateY(-0.5rem) translateX(0.15rem)}.form-floating>.form-control:focus~label::after,.form-floating>.form-control:not(:placeholder-shown)~label::after,.form-floating>.form-control-plaintext~label::after,.form-floating>.form-select~label::after{position:absolute;inset:1rem .375rem;z-index:-1;height:1.5em;content:"";background-color:#fff;border-radius:.25rem}.form-floating>.form-control:-webkit-autofill~label{color:rgba(var(--bs-body-color-rgb), 0.65);transform:scale(0.85) translateY(-0.5rem) translateX(0.15rem)}.form-floating>.form-control-plaintext~label{border-width:1px 0}.form-floating>:disabled~label,.form-floating>.form-control:disabled~label{color:#6c757d}.form-floating>:disabled~label::after,.form-floating>.form-control:disabled~label::after{background-color:#ebebeb}.input-group{position:relative;display:flex;display:-webkit-flex;flex-wrap:wrap;-webkit-flex-wrap:wrap;align-items:stretch;-webkit-align-items:stretch;width:100%}.input-group>.form-control,.input-group>.form-select,.input-group>.form-floating{position:relative;flex:1 1 auto;-webkit-flex:1 1 auto;width:1%;min-width:0}.input-group>.form-control:focus,.input-group>.form-select:focus,.input-group>.form-floating:focus-within{z-index:5}.input-group .btn{position:relative;z-index:2}.input-group .btn:focus{z-index:5}.input-group-text{display:flex;display:-webkit-flex;align-items:center;-webkit-align-items:center;padding:.375rem .75rem;font-size:1rem;font-weight:400;line-height:1.5;color:#6f6f6f;text-align:center;white-space:nowrap;background-color:#434343;border:1px solid #adb5bd;border-radius:.25rem}.input-group-lg>.form-control,.input-group-lg>.form-select,.input-group-lg>.input-group-text,.input-group-lg>.btn{padding:.5rem 1rem;font-size:1.25rem;border-radius:.5rem}.input-group-sm>.form-control,.input-group-sm>.form-select,.input-group-sm>.input-group-text,.input-group-sm>.btn{padding:.25rem .5rem;font-size:0.875rem;border-radius:.2em}.input-group-lg>.form-select,.input-group-sm>.form-select{padding-right:3rem}.input-group:not(.has-validation)>:not(:last-child):not(.dropdown-toggle):not(.dropdown-menu):not(.form-floating),.input-group:not(.has-validation)>.dropdown-toggle:nth-last-child(n+3),.input-group:not(.has-validation)>.form-floating:not(:last-child)>.form-control,.input-group:not(.has-validation)>.form-floating:not(:last-child)>.form-select{border-top-right-radius:0;border-bottom-right-radius:0}.input-group.has-validation>:nth-last-child(n+3):not(.dropdown-toggle):not(.dropdown-menu):not(.form-floating),.input-group.has-validation>.dropdown-toggle:nth-last-child(n+4),.input-group.has-validation>.form-floating:nth-last-child(n+3)>.form-control,.input-group.has-validation>.form-floating:nth-last-child(n+3)>.form-select{border-top-right-radius:0;border-bottom-right-radius:0}.input-group>:not(:first-child):not(.dropdown-menu):not(.valid-tooltip):not(.valid-feedback):not(.invalid-tooltip):not(.invalid-feedback){margin-left:calc(1px*-1);border-top-left-radius:0;border-bottom-left-radius:0}.input-group>.form-floating:not(:first-child)>.form-control,.input-group>.form-floating:not(:first-child)>.form-select{border-top-left-radius:0;border-bottom-left-radius:0}.valid-feedback{display:none;width:100%;margin-top:.25rem;font-size:0.875em;color:#00bc8c}.valid-tooltip{position:absolute;top:100%;z-index:5;display:none;max-width:100%;padding:.25rem .5rem;margin-top:.1rem;font-size:0.875rem;color:#fff;background-color:#00bc8c;border-radius:.25rem}.was-validated :valid~.valid-feedback,.was-validated :valid~.valid-tooltip,.is-valid~.valid-feedback,.is-valid~.valid-tooltip{display:block}.was-validated .form-control:valid,.form-control.is-valid{border-color:#00bc8c;padding-right:calc(1.5em + 0.75rem);background-image:url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 8 8'%3e%3cpath fill='%2300bc8c' d='M2.3 6.73.6 4.53c-.4-1.04.46-1.4 1.1-.8l1.1 1.4 3.4-3.8c.6-.63 1.6-.27 1.2.7l-4 4.6c-.43.5-.8.4-1.1.1z'/%3e%3c/svg%3e");background-repeat:no-repeat;background-position:right calc(0.375em + 0.1875rem) center;background-size:calc(0.75em + 0.375rem) calc(0.75em + 0.375rem)}.was-validated .form-control:valid:focus,.form-control.is-valid:focus{border-color:#00bc8c;box-shadow:0 0 0 .25rem rgba(0,188,140,.25)}.was-validated textarea.form-control:valid,textarea.form-control.is-valid{padding-right:calc(1.5em + 0.75rem);background-position:top calc(0.375em + 0.1875rem) right calc(0.375em + 0.1875rem)}.was-validated .form-select:valid,.form-select.is-valid{border-color:#00bc8c}.was-validated .form-select:valid:not([multiple]):not([size]),.was-validated .form-select:valid:not([multiple])[size="1"],.form-select.is-valid:not([multiple]):not([size]),.form-select.is-valid:not([multiple])[size="1"]{--bs-form-select-bg-icon: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 8 8'%3e%3cpath fill='%2300bc8c' d='M2.3 6.73.6 4.53c-.4-1.04.46-1.4 1.1-.8l1.1 1.4 3.4-3.8c.6-.63 1.6-.27 1.2.7l-4 4.6c-.43.5-.8.4-1.1.1z'/%3e%3c/svg%3e");padding-right:4.125rem;background-position:right .75rem center,center right 2.25rem;background-size:16px 12px,calc(0.75em + 0.375rem) calc(0.75em + 0.375rem)}.was-validated .form-select:valid:focus,.form-select.is-valid:focus{border-color:#00bc8c;box-shadow:0 0 0 .25rem rgba(0,188,140,.25)}.was-validated .form-control-color:valid,.form-control-color.is-valid{width:calc(3rem + calc(1.5em + 0.75rem))}.was-validated .form-check-input:valid,.form-check-input.is-valid{border-color:#00bc8c}.was-validated .form-check-input:valid:checked,.form-check-input.is-valid:checked{background-color:#00bc8c}.was-validated .form-check-input:valid:focus,.form-check-input.is-valid:focus{box-shadow:0 0 0 .25rem rgba(0,188,140,.25)}.was-validated .form-check-input:valid~.form-check-label,.form-check-input.is-valid~.form-check-label{color:#00bc8c}.form-check-inline .form-check-input~.valid-feedback{margin-left:.5em}.was-validated .input-group>.form-control:not(:focus):valid,.input-group>.form-control:not(:focus).is-valid,.was-validated .input-group>.form-select:not(:focus):valid,.input-group>.form-select:not(:focus).is-valid,.was-validated .input-group>.form-floating:not(:focus-within):valid,.input-group>.form-floating:not(:focus-within).is-valid{z-index:3}.invalid-feedback{display:none;width:100%;margin-top:.25rem;font-size:0.875em;color:#e74c3c}.invalid-tooltip{position:absolute;top:100%;z-index:5;display:none;max-width:100%;padding:.25rem .5rem;margin-top:.1rem;font-size:0.875rem;color:#fff;background-color:#e74c3c;border-radius:.25rem}.was-validated :invalid~.invalid-feedback,.was-validated :invalid~.invalid-tooltip,.is-invalid~.invalid-feedback,.is-invalid~.invalid-tooltip{display:block}.was-validated .form-control:invalid,.form-control.is-invalid{border-color:#e74c3c;padding-right:calc(1.5em + 0.75rem);background-image:url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12' width='12' height='12' fill='none' stroke='%23e74c3c'%3e%3ccircle cx='6' cy='6' r='4.5'/%3e%3cpath stroke-linejoin='round' d='M5.8 3.6h.4L6 6.5z'/%3e%3ccircle cx='6' cy='8.2' r='.6' fill='%23e74c3c' stroke='none'/%3e%3c/svg%3e");background-repeat:no-repeat;background-position:right calc(0.375em + 0.1875rem) center;background-size:calc(0.75em + 0.375rem) calc(0.75em + 0.375rem)}.was-validated .form-control:invalid:focus,.form-control.is-invalid:focus{border-color:#e74c3c;box-shadow:0 0 0 .25rem rgba(231,76,60,.25)}.was-validated textarea.form-control:invalid,textarea.form-control.is-invalid{padding-right:calc(1.5em + 0.75rem);background-position:top calc(0.375em + 0.1875rem) right calc(0.375em + 0.1875rem)}.was-validated .form-select:invalid,.form-select.is-invalid{border-color:#e74c3c}.was-validated .form-select:invalid:not([multiple]):not([size]),.was-validated .form-select:invalid:not([multiple])[size="1"],.form-select.is-invalid:not([multiple]):not([size]),.form-select.is-invalid:not([multiple])[size="1"]{--bs-form-select-bg-icon: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12' width='12' height='12' fill='none' stroke='%23e74c3c'%3e%3ccircle cx='6' cy='6' r='4.5'/%3e%3cpath stroke-linejoin='round' d='M5.8 3.6h.4L6 6.5z'/%3e%3ccircle cx='6' cy='8.2' r='.6' fill='%23e74c3c' stroke='none'/%3e%3c/svg%3e");padding-right:4.125rem;background-position:right .75rem center,center right 2.25rem;background-size:16px 12px,calc(0.75em + 0.375rem) calc(0.75em + 0.375rem)}.was-validated .form-select:invalid:focus,.form-select.is-invalid:focus{border-color:#e74c3c;box-shadow:0 0 0 .25rem rgba(231,76,60,.25)}.was-validated .form-control-color:invalid,.form-control-color.is-invalid{width:calc(3rem + calc(1.5em + 0.75rem))}.was-validated .form-check-input:invalid,.form-check-input.is-invalid{border-color:#e74c3c}.was-validated .form-check-input:invalid:checked,.form-check-input.is-invalid:checked{background-color:#e74c3c}.was-validated .form-check-input:invalid:focus,.form-check-input.is-invalid:focus{box-shadow:0 0 0 .25rem rgba(231,76,60,.25)}.was-validated .form-check-input:invalid~.form-check-label,.form-check-input.is-invalid~.form-check-label{color:#e74c3c}.form-check-inline .form-check-input~.invalid-feedback{margin-left:.5em}.was-validated .input-group>.form-control:not(:focus):invalid,.input-group>.form-control:not(:focus).is-invalid,.was-validated .input-group>.form-select:not(:focus):invalid,.input-group>.form-select:not(:focus).is-invalid,.was-validated .input-group>.form-floating:not(:focus-within):invalid,.input-group>.form-floating:not(:focus-within).is-invalid{z-index:4}.btn{--bs-btn-padding-x: 0.75rem;--bs-btn-padding-y: 0.375rem;--bs-btn-font-family: ;--bs-btn-font-size:1rem;--bs-btn-font-weight: 400;--bs-btn-line-height: 1.5;--bs-btn-color: #fff;--bs-btn-bg: transparent;--bs-btn-border-width: 1px;--bs-btn-border-color: transparent;--bs-btn-border-radius: 0.25rem;--bs-btn-hover-border-color: transparent;--bs-btn-box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.15), 0 1px 1px rgba(0, 0, 0, 0.075);--bs-btn-disabled-opacity: 0.65;--bs-btn-focus-box-shadow: 0 0 0 0.25rem rgba(var(--bs-btn-focus-shadow-rgb), .5);display:inline-block;padding:var(--bs-btn-padding-y) var(--bs-btn-padding-x);font-family:var(--bs-btn-font-family);font-size:var(--bs-btn-font-size);font-weight:var(--bs-btn-font-weight);line-height:var(--bs-btn-line-height);color:var(--bs-btn-color);text-align:center;text-decoration:none;-webkit-text-decoration:none;-moz-text-decoration:none;-ms-text-decoration:none;-o-text-decoration:none;vertical-align:middle;cursor:pointer;user-select:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;-o-user-select:none;border:var(--bs-btn-border-width) solid var(--bs-btn-border-color);border-radius:var(--bs-btn-border-radius);background-color:var(--bs-btn-bg);transition:color .15s ease-in-out,background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media(prefers-reduced-motion: reduce){.btn{transition:none}}.btn:hover{color:var(--bs-btn-hover-color);background-color:var(--bs-btn-hover-bg);border-color:var(--bs-btn-hover-border-color)}.btn-check+.btn:hover{color:var(--bs-btn-color);background-color:var(--bs-btn-bg);border-color:var(--bs-btn-border-color)}.btn:focus-visible{color:var(--bs-btn-hover-color);background-color:var(--bs-btn-hover-bg);border-color:var(--bs-btn-hover-border-color);outline:0;box-shadow:var(--bs-btn-focus-box-shadow)}.btn-check:focus-visible+.btn{border-color:var(--bs-btn-hover-border-color);outline:0;box-shadow:var(--bs-btn-focus-box-shadow)}.btn-check:checked+.btn,:not(.btn-check)+.btn:active,.btn:first-child:active,.btn.active,.btn.show{color:var(--bs-btn-active-color);background-color:var(--bs-btn-active-bg);border-color:var(--bs-btn-active-border-color)}.btn-check:checked+.btn:focus-visible,:not(.btn-check)+.btn:active:focus-visible,.btn:first-child:active:focus-visible,.btn.active:focus-visible,.btn.show:focus-visible{box-shadow:var(--bs-btn-focus-box-shadow)}.btn:disabled,.btn.disabled,fieldset:disabled .btn{color:var(--bs-btn-disabled-color);pointer-events:none;background-color:var(--bs-btn-disabled-bg);border-color:var(--bs-btn-disabled-border-color);opacity:var(--bs-btn-disabled-opacity)}.btn-default{--bs-btn-color: #fff;--bs-btn-bg: #434343;--bs-btn-border-color: #434343;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #393939;--bs-btn-hover-border-color: #363636;--bs-btn-focus-shadow-rgb: 95, 95, 95;--bs-btn-active-color: #fff;--bs-btn-active-bg: #363636;--bs-btn-active-border-color: #323232;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #434343;--bs-btn-disabled-border-color: #434343}.btn-primary{--bs-btn-color: #fff;--bs-btn-bg: #375a7f;--bs-btn-border-color: #375a7f;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #2f4d6c;--bs-btn-hover-border-color: #2c4866;--bs-btn-focus-shadow-rgb: 85, 115, 146;--bs-btn-active-color: #fff;--bs-btn-active-bg: #2c4866;--bs-btn-active-border-color: #29445f;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #375a7f;--bs-btn-disabled-border-color: #375a7f}.btn-secondary{--bs-btn-color: #fff;--bs-btn-bg: #434343;--bs-btn-border-color: #434343;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #393939;--bs-btn-hover-border-color: #363636;--bs-btn-focus-shadow-rgb: 95, 95, 95;--bs-btn-active-color: #fff;--bs-btn-active-bg: #363636;--bs-btn-active-border-color: #323232;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #434343;--bs-btn-disabled-border-color: #434343}.btn-success{--bs-btn-color: #fff;--bs-btn-bg: #00bc8c;--bs-btn-border-color: #00bc8c;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #00a077;--bs-btn-hover-border-color: #009670;--bs-btn-focus-shadow-rgb: 38, 198, 157;--bs-btn-active-color: #fff;--bs-btn-active-bg: #009670;--bs-btn-active-border-color: #008d69;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #00bc8c;--bs-btn-disabled-border-color: #00bc8c}.btn-info{--bs-btn-color: #fff;--bs-btn-bg: #3498db;--bs-btn-border-color: #3498db;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #2c81ba;--bs-btn-hover-border-color: #2a7aaf;--bs-btn-focus-shadow-rgb: 82, 167, 224;--bs-btn-active-color: #fff;--bs-btn-active-bg: #2a7aaf;--bs-btn-active-border-color: #2772a4;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #3498db;--bs-btn-disabled-border-color: #3498db}.btn-warning{--bs-btn-color: #fff;--bs-btn-bg: #f39c12;--bs-btn-border-color: #f39c12;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #cf850f;--bs-btn-hover-border-color: #c27d0e;--bs-btn-focus-shadow-rgb: 245, 171, 54;--bs-btn-active-color: #fff;--bs-btn-active-bg: #c27d0e;--bs-btn-active-border-color: #b6750e;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #f39c12;--bs-btn-disabled-border-color: #f39c12}.btn-danger{--bs-btn-color: #fff;--bs-btn-bg: #e74c3c;--bs-btn-border-color: #e74c3c;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #c44133;--bs-btn-hover-border-color: #b93d30;--bs-btn-focus-shadow-rgb: 235, 103, 89;--bs-btn-active-color: #fff;--bs-btn-active-bg: #b93d30;--bs-btn-active-border-color: #ad392d;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #e74c3c;--bs-btn-disabled-border-color: #e74c3c}.btn-light{--bs-btn-color: #fff;--bs-btn-bg: #6f6f6f;--bs-btn-border-color: #6f6f6f;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #5e5e5e;--bs-btn-hover-border-color: #595959;--bs-btn-focus-shadow-rgb: 133, 133, 133;--bs-btn-active-color: #fff;--bs-btn-active-bg: #595959;--bs-btn-active-border-color: #535353;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #6f6f6f;--bs-btn-disabled-border-color: #6f6f6f}.btn-dark{--bs-btn-color: #fff;--bs-btn-bg: #2d2d2d;--bs-btn-border-color: #2d2d2d;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #4d4d4d;--bs-btn-hover-border-color: #424242;--bs-btn-focus-shadow-rgb: 77, 77, 77;--bs-btn-active-color: #fff;--bs-btn-active-bg: #575757;--bs-btn-active-border-color: #424242;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #2d2d2d;--bs-btn-disabled-border-color: #2d2d2d}.btn-outline-default{--bs-btn-color: #434343;--bs-btn-border-color: #434343;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #434343;--bs-btn-hover-border-color: #434343;--bs-btn-focus-shadow-rgb: 67, 67, 67;--bs-btn-active-color: #fff;--bs-btn-active-bg: #434343;--bs-btn-active-border-color: #434343;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #434343;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #434343;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-primary{--bs-btn-color: #375a7f;--bs-btn-border-color: #375a7f;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #375a7f;--bs-btn-hover-border-color: #375a7f;--bs-btn-focus-shadow-rgb: 55, 90, 127;--bs-btn-active-color: #fff;--bs-btn-active-bg: #375a7f;--bs-btn-active-border-color: #375a7f;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #375a7f;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #375a7f;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-secondary{--bs-btn-color: #434343;--bs-btn-border-color: #434343;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #434343;--bs-btn-hover-border-color: #434343;--bs-btn-focus-shadow-rgb: 67, 67, 67;--bs-btn-active-color: #fff;--bs-btn-active-bg: #434343;--bs-btn-active-border-color: #434343;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #434343;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #434343;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-success{--bs-btn-color: #00bc8c;--bs-btn-border-color: #00bc8c;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #00bc8c;--bs-btn-hover-border-color: #00bc8c;--bs-btn-focus-shadow-rgb: 0, 188, 140;--bs-btn-active-color: #fff;--bs-btn-active-bg: #00bc8c;--bs-btn-active-border-color: #00bc8c;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #00bc8c;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #00bc8c;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-info{--bs-btn-color: #3498db;--bs-btn-border-color: #3498db;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #3498db;--bs-btn-hover-border-color: #3498db;--bs-btn-focus-shadow-rgb: 52, 152, 219;--bs-btn-active-color: #fff;--bs-btn-active-bg: #3498db;--bs-btn-active-border-color: #3498db;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #3498db;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #3498db;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-warning{--bs-btn-color: #f39c12;--bs-btn-border-color: #f39c12;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #f39c12;--bs-btn-hover-border-color: #f39c12;--bs-btn-focus-shadow-rgb: 243, 156, 18;--bs-btn-active-color: #fff;--bs-btn-active-bg: #f39c12;--bs-btn-active-border-color: #f39c12;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #f39c12;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #f39c12;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-danger{--bs-btn-color: #e74c3c;--bs-btn-border-color: #e74c3c;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #e74c3c;--bs-btn-hover-border-color: #e74c3c;--bs-btn-focus-shadow-rgb: 231, 76, 60;--bs-btn-active-color: #fff;--bs-btn-active-bg: #e74c3c;--bs-btn-active-border-color: #e74c3c;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #e74c3c;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #e74c3c;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-light{--bs-btn-color: #6f6f6f;--bs-btn-border-color: #6f6f6f;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #6f6f6f;--bs-btn-hover-border-color: #6f6f6f;--bs-btn-focus-shadow-rgb: 111, 111, 111;--bs-btn-active-color: #fff;--bs-btn-active-bg: #6f6f6f;--bs-btn-active-border-color: #6f6f6f;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #6f6f6f;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #6f6f6f;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-dark{--bs-btn-color: #2d2d2d;--bs-btn-border-color: #2d2d2d;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #2d2d2d;--bs-btn-hover-border-color: #2d2d2d;--bs-btn-focus-shadow-rgb: 45, 45, 45;--bs-btn-active-color: #fff;--bs-btn-active-bg: #2d2d2d;--bs-btn-active-border-color: #2d2d2d;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #2d2d2d;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #2d2d2d;--bs-btn-bg: transparent;--bs-gradient: none}.btn-link{--bs-btn-font-weight: 400;--bs-btn-color: #00bc8c;--bs-btn-bg: transparent;--bs-btn-border-color: transparent;--bs-btn-hover-color: #009670;--bs-btn-hover-border-color: transparent;--bs-btn-active-color: #009670;--bs-btn-active-border-color: transparent;--bs-btn-disabled-color: #6c757d;--bs-btn-disabled-border-color: transparent;--bs-btn-box-shadow: 0 0 0 #000;--bs-btn-focus-shadow-rgb: 38, 198, 157;text-decoration:underline;-webkit-text-decoration:underline;-moz-text-decoration:underline;-ms-text-decoration:underline;-o-text-decoration:underline}.btn-link:focus-visible{color:var(--bs-btn-color)}.btn-link:hover{color:var(--bs-btn-hover-color)}.btn-lg,.btn-group-lg>.btn{--bs-btn-padding-y: 0.5rem;--bs-btn-padding-x: 1rem;--bs-btn-font-size:1.25rem;--bs-btn-border-radius: 0.5rem}.btn-sm,.btn-group-sm>.btn{--bs-btn-padding-y: 0.25rem;--bs-btn-padding-x: 0.5rem;--bs-btn-font-size:0.875rem;--bs-btn-border-radius: 0.2em}.fade{transition:opacity .15s linear}@media(prefers-reduced-motion: reduce){.fade{transition:none}}.fade:not(.show){opacity:0}.collapse:not(.show){display:none}.collapsing{height:0;overflow:hidden;transition:height .2s ease}@media(prefers-reduced-motion: reduce){.collapsing{transition:none}}.collapsing.collapse-horizontal{width:0;height:auto;transition:width .35s ease}@media(prefers-reduced-motion: reduce){.collapsing.collapse-horizontal{transition:none}}.dropup,.dropend,.dropdown,.dropstart,.dropup-center,.dropdown-center{position:relative}.dropdown-toggle{white-space:nowrap}.dropdown-toggle::after{display:inline-block;margin-left:.255em;vertical-align:.255em;content:"";border-top:.3em solid;border-right:.3em solid rgba(0,0,0,0);border-bottom:0;border-left:.3em solid rgba(0,0,0,0)}.dropdown-toggle:empty::after{margin-left:0}.dropdown-menu{--bs-dropdown-zindex: 1000;--bs-dropdown-min-width: 10rem;--bs-dropdown-padding-x: 0;--bs-dropdown-padding-y: 0.5rem;--bs-dropdown-spacer: 0.125rem;--bs-dropdown-font-size:1rem;--bs-dropdown-color: #fff;--bs-dropdown-bg: #222;--bs-dropdown-border-color: #434343;--bs-dropdown-border-radius: 0.25rem;--bs-dropdown-border-width: 1px;--bs-dropdown-inner-border-radius: calc(0.25rem - 1px);--bs-dropdown-divider-bg: #434343;--bs-dropdown-divider-margin-y: 0.5rem;--bs-dropdown-box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);--bs-dropdown-link-color: #fff;--bs-dropdown-link-hover-color: #fff;--bs-dropdown-link-hover-bg: #375a7f;--bs-dropdown-link-active-color: #fff;--bs-dropdown-link-active-bg: #375a7f;--bs-dropdown-link-disabled-color: rgba(255, 255, 255, 0.5);--bs-dropdown-item-padding-x: 1rem;--bs-dropdown-item-padding-y: 0.25rem;--bs-dropdown-header-color: #6c757d;--bs-dropdown-header-padding-x: 1rem;--bs-dropdown-header-padding-y: 0.5rem;position:absolute;z-index:var(--bs-dropdown-zindex);display:none;min-width:var(--bs-dropdown-min-width);padding:var(--bs-dropdown-padding-y) var(--bs-dropdown-padding-x);margin:0;font-size:var(--bs-dropdown-font-size);color:var(--bs-dropdown-color);text-align:left;list-style:none;background-color:var(--bs-dropdown-bg);background-clip:padding-box;border:var(--bs-dropdown-border-width) solid var(--bs-dropdown-border-color);border-radius:var(--bs-dropdown-border-radius)}.dropdown-menu[data-bs-popper]{top:100%;left:0;margin-top:var(--bs-dropdown-spacer)}.dropdown-menu-start{--bs-position: start}.dropdown-menu-start[data-bs-popper]{right:auto;left:0}.dropdown-menu-end{--bs-position: end}.dropdown-menu-end[data-bs-popper]{right:0;left:auto}@media(min-width: 576px){.dropdown-menu-sm-start{--bs-position: start}.dropdown-menu-sm-start[data-bs-popper]{right:auto;left:0}.dropdown-menu-sm-end{--bs-position: end}.dropdown-menu-sm-end[data-bs-popper]{right:0;left:auto}}@media(min-width: 768px){.dropdown-menu-md-start{--bs-position: start}.dropdown-menu-md-start[data-bs-popper]{right:auto;left:0}.dropdown-menu-md-end{--bs-position: end}.dropdown-menu-md-end[data-bs-popper]{right:0;left:auto}}@media(min-width: 992px){.dropdown-menu-lg-start{--bs-position: start}.dropdown-menu-lg-start[data-bs-popper]{right:auto;left:0}.dropdown-menu-lg-end{--bs-position: end}.dropdown-menu-lg-end[data-bs-popper]{right:0;left:auto}}@media(min-width: 1200px){.dropdown-menu-xl-start{--bs-position: start}.dropdown-menu-xl-start[data-bs-popper]{right:auto;left:0}.dropdown-menu-xl-end{--bs-position: end}.dropdown-menu-xl-end[data-bs-popper]{right:0;left:auto}}@media(min-width: 1400px){.dropdown-menu-xxl-start{--bs-position: start}.dropdown-menu-xxl-start[data-bs-popper]{right:auto;left:0}.dropdown-menu-xxl-end{--bs-position: end}.dropdown-menu-xxl-end[data-bs-popper]{right:0;left:auto}}.dropup .dropdown-menu[data-bs-popper]{top:auto;bottom:100%;margin-top:0;margin-bottom:var(--bs-dropdown-spacer)}.dropup .dropdown-toggle::after{display:inline-block;margin-left:.255em;vertical-align:.255em;content:"";border-top:0;border-right:.3em solid rgba(0,0,0,0);border-bottom:.3em solid;border-left:.3em solid rgba(0,0,0,0)}.dropup .dropdown-toggle:empty::after{margin-left:0}.dropend .dropdown-menu[data-bs-popper]{top:0;right:auto;left:100%;margin-top:0;margin-left:var(--bs-dropdown-spacer)}.dropend .dropdown-toggle::after{display:inline-block;margin-left:.255em;vertical-align:.255em;content:"";border-top:.3em solid rgba(0,0,0,0);border-right:0;border-bottom:.3em solid rgba(0,0,0,0);border-left:.3em solid}.dropend .dropdown-toggle:empty::after{margin-left:0}.dropend .dropdown-toggle::after{vertical-align:0}.dropstart .dropdown-menu[data-bs-popper]{top:0;right:100%;left:auto;margin-top:0;margin-right:var(--bs-dropdown-spacer)}.dropstart .dropdown-toggle::after{display:inline-block;margin-left:.255em;vertical-align:.255em;content:""}.dropstart .dropdown-toggle::after{display:none}.dropstart .dropdown-toggle::before{display:inline-block;margin-right:.255em;vertical-align:.255em;content:"";border-top:.3em solid rgba(0,0,0,0);border-right:.3em solid;border-bottom:.3em solid rgba(0,0,0,0)}.dropstart .dropdown-toggle:empty::after{margin-left:0}.dropstart .dropdown-toggle::before{vertical-align:0}.dropdown-divider{height:0;margin:var(--bs-dropdown-divider-margin-y) 0;overflow:hidden;border-top:1px solid var(--bs-dropdown-divider-bg);opacity:1}.dropdown-item{display:block;width:100%;padding:var(--bs-dropdown-item-padding-y) var(--bs-dropdown-item-padding-x);clear:both;font-weight:400;color:var(--bs-dropdown-link-color);text-align:inherit;text-decoration:none;-webkit-text-decoration:none;-moz-text-decoration:none;-ms-text-decoration:none;-o-text-decoration:none;white-space:nowrap;background-color:rgba(0,0,0,0);border:0;border-radius:var(--bs-dropdown-item-border-radius, 0)}.dropdown-item:hover,.dropdown-item:focus{color:var(--bs-dropdown-link-hover-color);background-color:var(--bs-dropdown-link-hover-bg)}.dropdown-item.active,.dropdown-item:active{color:var(--bs-dropdown-link-active-color);text-decoration:none;background-color:var(--bs-dropdown-link-active-bg)}.dropdown-item.disabled,.dropdown-item:disabled{color:var(--bs-dropdown-link-disabled-color);pointer-events:none;background-color:rgba(0,0,0,0)}.dropdown-menu.show{display:block}.dropdown-header{display:block;padding:var(--bs-dropdown-header-padding-y) var(--bs-dropdown-header-padding-x);margin-bottom:0;font-size:0.875rem;color:var(--bs-dropdown-header-color);white-space:nowrap}.dropdown-item-text{display:block;padding:var(--bs-dropdown-item-padding-y) var(--bs-dropdown-item-padding-x);color:var(--bs-dropdown-link-color)}.dropdown-menu-dark{--bs-dropdown-color: #dee2e6;--bs-dropdown-bg: #343a40;--bs-dropdown-border-color: #434343;--bs-dropdown-box-shadow: ;--bs-dropdown-link-color: #dee2e6;--bs-dropdown-link-hover-color: #fff;--bs-dropdown-divider-bg: #434343;--bs-dropdown-link-hover-bg: rgba(255, 255, 255, 0.15);--bs-dropdown-link-active-color: #fff;--bs-dropdown-link-active-bg: #375a7f;--bs-dropdown-link-disabled-color: #adb5bd;--bs-dropdown-header-color: #adb5bd}.btn-group,.btn-group-vertical{position:relative;display:inline-flex;vertical-align:middle}.btn-group>.btn,.btn-group-vertical>.btn{position:relative;flex:1 1 auto;-webkit-flex:1 1 auto}.btn-group>.btn-check:checked+.btn,.btn-group>.btn-check:focus+.btn,.btn-group>.btn:hover,.btn-group>.btn:focus,.btn-group>.btn:active,.btn-group>.btn.active,.btn-group-vertical>.btn-check:checked+.btn,.btn-group-vertical>.btn-check:focus+.btn,.btn-group-vertical>.btn:hover,.btn-group-vertical>.btn:focus,.btn-group-vertical>.btn:active,.btn-group-vertical>.btn.active{z-index:1}.btn-toolbar{display:flex;display:-webkit-flex;flex-wrap:wrap;-webkit-flex-wrap:wrap;justify-content:flex-start;-webkit-justify-content:flex-start}.btn-toolbar .input-group{width:auto}.btn-group{border-radius:.25rem}.btn-group>:not(.btn-check:first-child)+.btn,.btn-group>.btn-group:not(:first-child){margin-left:calc(1px*-1)}.btn-group>.btn:not(:last-child):not(.dropdown-toggle),.btn-group>.btn.dropdown-toggle-split:first-child,.btn-group>.btn-group:not(:last-child)>.btn{border-top-right-radius:0;border-bottom-right-radius:0}.btn-group>.btn:nth-child(n+3),.btn-group>:not(.btn-check)+.btn,.btn-group>.btn-group:not(:first-child)>.btn{border-top-left-radius:0;border-bottom-left-radius:0}.dropdown-toggle-split{padding-right:.5625rem;padding-left:.5625rem}.dropdown-toggle-split::after,.dropup .dropdown-toggle-split::after,.dropend .dropdown-toggle-split::after{margin-left:0}.dropstart .dropdown-toggle-split::before{margin-right:0}.btn-sm+.dropdown-toggle-split,.btn-group-sm>.btn+.dropdown-toggle-split{padding-right:.375rem;padding-left:.375rem}.btn-lg+.dropdown-toggle-split,.btn-group-lg>.btn+.dropdown-toggle-split{padding-right:.75rem;padding-left:.75rem}.btn-group-vertical{flex-direction:column;-webkit-flex-direction:column;align-items:flex-start;-webkit-align-items:flex-start;justify-content:center;-webkit-justify-content:center}.btn-group-vertical>.btn,.btn-group-vertical>.btn-group{width:100%}.btn-group-vertical>.btn:not(:first-child),.btn-group-vertical>.btn-group:not(:first-child){margin-top:calc(1px*-1)}.btn-group-vertical>.btn:not(:last-child):not(.dropdown-toggle),.btn-group-vertical>.btn-group:not(:last-child)>.btn{border-bottom-right-radius:0;border-bottom-left-radius:0}.btn-group-vertical>.btn~.btn,.btn-group-vertical>.btn-group:not(:first-child)>.btn{border-top-left-radius:0;border-top-right-radius:0}.nav{--bs-nav-link-padding-x: 2rem;--bs-nav-link-padding-y: 0.5rem;--bs-nav-link-font-weight: ;--bs-nav-link-color: #00bc8c;--bs-nav-link-hover-color: #009670;--bs-nav-link-disabled-color: #6f6f6f;display:flex;display:-webkit-flex;flex-wrap:wrap;-webkit-flex-wrap:wrap;padding-left:0;margin-bottom:0;list-style:none}.nav-link{display:block;padding:var(--bs-nav-link-padding-y) var(--bs-nav-link-padding-x);font-size:var(--bs-nav-link-font-size);font-weight:var(--bs-nav-link-font-weight);color:var(--bs-nav-link-color);text-decoration:none;-webkit-text-decoration:none;-moz-text-decoration:none;-ms-text-decoration:none;-o-text-decoration:none;background:none;border:0;transition:color .15s ease-in-out,background-color .15s ease-in-out,border-color .15s ease-in-out}@media(prefers-reduced-motion: reduce){.nav-link{transition:none}}.nav-link:hover,.nav-link:focus{color:var(--bs-nav-link-hover-color)}.nav-link:focus-visible{outline:0;box-shadow:0 0 0 .25rem rgba(55,90,127,.25)}.nav-link.disabled,.nav-link:disabled{color:var(--bs-nav-link-disabled-color);pointer-events:none;cursor:default}.nav-tabs{--bs-nav-tabs-border-width: 1px;--bs-nav-tabs-border-color: #434343;--bs-nav-tabs-border-radius: 0.25rem;--bs-nav-tabs-link-hover-border-color: #434343 #434343 transparent;--bs-nav-tabs-link-active-color: #fff;--bs-nav-tabs-link-active-bg: #222;--bs-nav-tabs-link-active-border-color: #434343 #434343 transparent;border-bottom:var(--bs-nav-tabs-border-width) solid var(--bs-nav-tabs-border-color)}.nav-tabs .nav-link{margin-bottom:calc(-1*var(--bs-nav-tabs-border-width));border:var(--bs-nav-tabs-border-width) solid rgba(0,0,0,0);border-top-left-radius:var(--bs-nav-tabs-border-radius);border-top-right-radius:var(--bs-nav-tabs-border-radius)}.nav-tabs .nav-link:hover,.nav-tabs .nav-link:focus{isolation:isolate;border-color:var(--bs-nav-tabs-link-hover-border-color)}.nav-tabs .nav-link.active,.nav-tabs .nav-item.show .nav-link{color:var(--bs-nav-tabs-link-active-color);background-color:var(--bs-nav-tabs-link-active-bg);border-color:var(--bs-nav-tabs-link-active-border-color)}.nav-tabs .dropdown-menu{margin-top:calc(-1*var(--bs-nav-tabs-border-width));border-top-left-radius:0;border-top-right-radius:0}.nav-pills{--bs-nav-pills-border-radius: 0.25rem;--bs-nav-pills-link-active-color: #fff;--bs-nav-pills-link-active-bg: #375a7f}.nav-pills .nav-link{border-radius:var(--bs-nav-pills-border-radius)}.nav-pills .nav-link.active,.nav-pills .show>.nav-link{color:var(--bs-nav-pills-link-active-color);background-color:var(--bs-nav-pills-link-active-bg)}.nav-underline{--bs-nav-underline-gap: 1rem;--bs-nav-underline-border-width: 0.125rem;--bs-nav-underline-link-active-color: #000;gap:var(--bs-nav-underline-gap)}.nav-underline .nav-link{padding-right:0;padding-left:0;border-bottom:var(--bs-nav-underline-border-width) solid rgba(0,0,0,0)}.nav-underline .nav-link:hover,.nav-underline .nav-link:focus{border-bottom-color:currentcolor}.nav-underline .nav-link.active,.nav-underline .show>.nav-link{font-weight:700;color:var(--bs-nav-underline-link-active-color);border-bottom-color:currentcolor}.nav-fill>.nav-link,.nav-fill .nav-item{flex:1 1 auto;-webkit-flex:1 1 auto;text-align:center}.nav-justified>.nav-link,.nav-justified .nav-item{flex-basis:0;-webkit-flex-basis:0;flex-grow:1;-webkit-flex-grow:1;text-align:center}.nav-fill .nav-item .nav-link,.nav-justified .nav-item .nav-link{width:100%}.tab-content>.tab-pane{display:none}.tab-content>.active{display:block}.navbar{--bs-navbar-padding-x: 0;--bs-navbar-padding-y: 1rem;--bs-navbar-color: #dee2e6;--bs-navbar-hover-color: rgba(255, 255, 255, 0.8);--bs-navbar-disabled-color: rgba(222, 226, 230, 0.75);--bs-navbar-active-color: #fff;--bs-navbar-brand-padding-y: 0.3125rem;--bs-navbar-brand-margin-end: 1rem;--bs-navbar-brand-font-size: 1.25rem;--bs-navbar-brand-color: #dee2e6;--bs-navbar-brand-hover-color: #fff;--bs-navbar-nav-link-padding-x: 0.5rem;--bs-navbar-toggler-padding-y: 0.25;--bs-navbar-toggler-padding-x: 0;--bs-navbar-toggler-font-size: 1.25rem;--bs-navbar-toggler-icon-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 30 30'%3e%3cpath stroke='%23dee2e6' stroke-linecap='round' stroke-miterlimit='10' stroke-width='2' d='M4 7h22M4 15h22M4 23h22'/%3e%3c/svg%3e");--bs-navbar-toggler-border-color: rgba(222, 226, 230, 0);--bs-navbar-toggler-border-radius: 0.25rem;--bs-navbar-toggler-focus-width: 0.25rem;--bs-navbar-toggler-transition: box-shadow 0.15s ease-in-out;position:relative;display:flex;display:-webkit-flex;flex-wrap:wrap;-webkit-flex-wrap:wrap;align-items:center;-webkit-align-items:center;justify-content:space-between;-webkit-justify-content:space-between;padding:var(--bs-navbar-padding-y) var(--bs-navbar-padding-x)}.navbar>.container,.navbar>.container-fluid,.navbar>.container-sm,.navbar>.container-md,.navbar>.container-lg,.navbar>.container-xl,.navbar>.container-xxl{display:flex;display:-webkit-flex;flex-wrap:inherit;-webkit-flex-wrap:inherit;align-items:center;-webkit-align-items:center;justify-content:space-between;-webkit-justify-content:space-between}.navbar-brand{padding-top:var(--bs-navbar-brand-padding-y);padding-bottom:var(--bs-navbar-brand-padding-y);margin-right:var(--bs-navbar-brand-margin-end);font-size:var(--bs-navbar-brand-font-size);color:var(--bs-navbar-brand-color);text-decoration:none;-webkit-text-decoration:none;-moz-text-decoration:none;-ms-text-decoration:none;-o-text-decoration:none;white-space:nowrap}.navbar-brand:hover,.navbar-brand:focus{color:var(--bs-navbar-brand-hover-color)}.navbar-nav{--bs-nav-link-padding-x: 0;--bs-nav-link-padding-y: 0.5rem;--bs-nav-link-font-weight: ;--bs-nav-link-color: var(--bs-navbar-color);--bs-nav-link-hover-color: var(--bs-navbar-hover-color);--bs-nav-link-disabled-color: var(--bs-navbar-disabled-color);display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;padding-left:0;margin-bottom:0;list-style:none}.navbar-nav .nav-link.active,.navbar-nav .nav-link.show{color:var(--bs-navbar-active-color)}.navbar-nav .dropdown-menu{position:static}.navbar-text{padding-top:.5rem;padding-bottom:.5rem;color:var(--bs-navbar-color)}.navbar-text a,.navbar-text a:hover,.navbar-text a:focus{color:var(--bs-navbar-active-color)}.navbar-collapse{flex-basis:100%;-webkit-flex-basis:100%;flex-grow:1;-webkit-flex-grow:1;align-items:center;-webkit-align-items:center}.navbar-toggler{padding:var(--bs-navbar-toggler-padding-y) var(--bs-navbar-toggler-padding-x);font-size:var(--bs-navbar-toggler-font-size);line-height:1;color:var(--bs-navbar-color);background-color:rgba(0,0,0,0);border:var(--bs-border-width) solid var(--bs-navbar-toggler-border-color);border-radius:var(--bs-navbar-toggler-border-radius);transition:var(--bs-navbar-toggler-transition)}@media(prefers-reduced-motion: reduce){.navbar-toggler{transition:none}}.navbar-toggler:hover{text-decoration:none}.navbar-toggler:focus{text-decoration:none;outline:0;box-shadow:0 0 0 var(--bs-navbar-toggler-focus-width)}.navbar-toggler-icon{display:inline-block;width:1.5em;height:1.5em;vertical-align:middle;background-image:var(--bs-navbar-toggler-icon-bg);background-repeat:no-repeat;background-position:center;background-size:100%}.navbar-nav-scroll{max-height:var(--bs-scroll-height, 75vh);overflow-y:auto}@media(min-width: 576px){.navbar-expand-sm{flex-wrap:nowrap;-webkit-flex-wrap:nowrap;justify-content:flex-start;-webkit-justify-content:flex-start}.navbar-expand-sm .navbar-nav{flex-direction:row;-webkit-flex-direction:row}.navbar-expand-sm .navbar-nav .dropdown-menu{position:absolute}.navbar-expand-sm .navbar-nav .nav-link{padding-right:var(--bs-navbar-nav-link-padding-x);padding-left:var(--bs-navbar-nav-link-padding-x)}.navbar-expand-sm .navbar-nav-scroll{overflow:visible}.navbar-expand-sm .navbar-collapse{display:flex !important;display:-webkit-flex !important;flex-basis:auto;-webkit-flex-basis:auto}.navbar-expand-sm .navbar-toggler{display:none}.navbar-expand-sm .offcanvas{position:static;z-index:auto;flex-grow:1;-webkit-flex-grow:1;width:auto !important;height:auto !important;visibility:visible !important;background-color:rgba(0,0,0,0) !important;border:0 !important;transform:none !important;transition:none}.navbar-expand-sm .offcanvas .offcanvas-header{display:none}.navbar-expand-sm .offcanvas .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible}}@media(min-width: 768px){.navbar-expand-md{flex-wrap:nowrap;-webkit-flex-wrap:nowrap;justify-content:flex-start;-webkit-justify-content:flex-start}.navbar-expand-md .navbar-nav{flex-direction:row;-webkit-flex-direction:row}.navbar-expand-md .navbar-nav .dropdown-menu{position:absolute}.navbar-expand-md .navbar-nav .nav-link{padding-right:var(--bs-navbar-nav-link-padding-x);padding-left:var(--bs-navbar-nav-link-padding-x)}.navbar-expand-md .navbar-nav-scroll{overflow:visible}.navbar-expand-md .navbar-collapse{display:flex !important;display:-webkit-flex !important;flex-basis:auto;-webkit-flex-basis:auto}.navbar-expand-md .navbar-toggler{display:none}.navbar-expand-md .offcanvas{position:static;z-index:auto;flex-grow:1;-webkit-flex-grow:1;width:auto !important;height:auto !important;visibility:visible !important;background-color:rgba(0,0,0,0) !important;border:0 !important;transform:none !important;transition:none}.navbar-expand-md .offcanvas .offcanvas-header{display:none}.navbar-expand-md .offcanvas .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible}}@media(min-width: 992px){.navbar-expand-lg{flex-wrap:nowrap;-webkit-flex-wrap:nowrap;justify-content:flex-start;-webkit-justify-content:flex-start}.navbar-expand-lg .navbar-nav{flex-direction:row;-webkit-flex-direction:row}.navbar-expand-lg .navbar-nav .dropdown-menu{position:absolute}.navbar-expand-lg .navbar-nav .nav-link{padding-right:var(--bs-navbar-nav-link-padding-x);padding-left:var(--bs-navbar-nav-link-padding-x)}.navbar-expand-lg .navbar-nav-scroll{overflow:visible}.navbar-expand-lg .navbar-collapse{display:flex !important;display:-webkit-flex !important;flex-basis:auto;-webkit-flex-basis:auto}.navbar-expand-lg .navbar-toggler{display:none}.navbar-expand-lg .offcanvas{position:static;z-index:auto;flex-grow:1;-webkit-flex-grow:1;width:auto !important;height:auto !important;visibility:visible !important;background-color:rgba(0,0,0,0) !important;border:0 !important;transform:none !important;transition:none}.navbar-expand-lg .offcanvas .offcanvas-header{display:none}.navbar-expand-lg .offcanvas .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible}}@media(min-width: 1200px){.navbar-expand-xl{flex-wrap:nowrap;-webkit-flex-wrap:nowrap;justify-content:flex-start;-webkit-justify-content:flex-start}.navbar-expand-xl .navbar-nav{flex-direction:row;-webkit-flex-direction:row}.navbar-expand-xl .navbar-nav .dropdown-menu{position:absolute}.navbar-expand-xl .navbar-nav .nav-link{padding-right:var(--bs-navbar-nav-link-padding-x);padding-left:var(--bs-navbar-nav-link-padding-x)}.navbar-expand-xl .navbar-nav-scroll{overflow:visible}.navbar-expand-xl .navbar-collapse{display:flex !important;display:-webkit-flex !important;flex-basis:auto;-webkit-flex-basis:auto}.navbar-expand-xl .navbar-toggler{display:none}.navbar-expand-xl .offcanvas{position:static;z-index:auto;flex-grow:1;-webkit-flex-grow:1;width:auto !important;height:auto !important;visibility:visible !important;background-color:rgba(0,0,0,0) !important;border:0 !important;transform:none !important;transition:none}.navbar-expand-xl .offcanvas .offcanvas-header{display:none}.navbar-expand-xl .offcanvas .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible}}@media(min-width: 1400px){.navbar-expand-xxl{flex-wrap:nowrap;-webkit-flex-wrap:nowrap;justify-content:flex-start;-webkit-justify-content:flex-start}.navbar-expand-xxl .navbar-nav{flex-direction:row;-webkit-flex-direction:row}.navbar-expand-xxl .navbar-nav .dropdown-menu{position:absolute}.navbar-expand-xxl .navbar-nav .nav-link{padding-right:var(--bs-navbar-nav-link-padding-x);padding-left:var(--bs-navbar-nav-link-padding-x)}.navbar-expand-xxl .navbar-nav-scroll{overflow:visible}.navbar-expand-xxl .navbar-collapse{display:flex !important;display:-webkit-flex !important;flex-basis:auto;-webkit-flex-basis:auto}.navbar-expand-xxl .navbar-toggler{display:none}.navbar-expand-xxl .offcanvas{position:static;z-index:auto;flex-grow:1;-webkit-flex-grow:1;width:auto !important;height:auto !important;visibility:visible !important;background-color:rgba(0,0,0,0) !important;border:0 !important;transform:none !important;transition:none}.navbar-expand-xxl .offcanvas .offcanvas-header{display:none}.navbar-expand-xxl .offcanvas .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible}}.navbar-expand{flex-wrap:nowrap;-webkit-flex-wrap:nowrap;justify-content:flex-start;-webkit-justify-content:flex-start}.navbar-expand .navbar-nav{flex-direction:row;-webkit-flex-direction:row}.navbar-expand .navbar-nav .dropdown-menu{position:absolute}.navbar-expand .navbar-nav .nav-link{padding-right:var(--bs-navbar-nav-link-padding-x);padding-left:var(--bs-navbar-nav-link-padding-x)}.navbar-expand .navbar-nav-scroll{overflow:visible}.navbar-expand .navbar-collapse{display:flex !important;display:-webkit-flex !important;flex-basis:auto;-webkit-flex-basis:auto}.navbar-expand .navbar-toggler{display:none}.navbar-expand .offcanvas{position:static;z-index:auto;flex-grow:1;-webkit-flex-grow:1;width:auto !important;height:auto !important;visibility:visible !important;background-color:rgba(0,0,0,0) !important;border:0 !important;transform:none !important;transition:none}.navbar-expand .offcanvas .offcanvas-header{display:none}.navbar-expand .offcanvas .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible}.navbar-dark,.navbar[data-bs-theme=dark]{--bs-navbar-color: #dee2e6;--bs-navbar-hover-color: rgba(255, 255, 255, 0.8);--bs-navbar-disabled-color: rgba(222, 226, 230, 0.75);--bs-navbar-active-color: #fff;--bs-navbar-brand-color: #dee2e6;--bs-navbar-brand-hover-color: #fff;--bs-navbar-toggler-border-color: rgba(222, 226, 230, 0);--bs-navbar-toggler-icon-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 30 30'%3e%3cpath stroke='%23dee2e6' stroke-linecap='round' stroke-miterlimit='10' stroke-width='2' d='M4 7h22M4 15h22M4 23h22'/%3e%3c/svg%3e")}[data-bs-theme=dark] .navbar-toggler-icon{--bs-navbar-toggler-icon-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 30 30'%3e%3cpath stroke='%23dee2e6' stroke-linecap='round' stroke-miterlimit='10' stroke-width='2' d='M4 7h22M4 15h22M4 23h22'/%3e%3c/svg%3e")}.card{--bs-card-spacer-y: 1rem;--bs-card-spacer-x: 1rem;--bs-card-title-spacer-y: 0.5rem;--bs-card-title-color: ;--bs-card-subtitle-color: ;--bs-card-border-width: 1px;--bs-card-border-color: rgba(0, 0, 0, 0.175);--bs-card-border-radius: 0.25rem;--bs-card-box-shadow: ;--bs-card-inner-border-radius: calc(0.25rem - 1px);--bs-card-cap-padding-y: 0.5rem;--bs-card-cap-padding-x: 1rem;--bs-card-cap-bg: rgba(52, 58, 64, 0.25);--bs-card-cap-color: ;--bs-card-height: ;--bs-card-color: ;--bs-card-bg: #2d2d2d;--bs-card-img-overlay-padding: 1rem;--bs-card-group-margin: 0.75rem;position:relative;display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;min-width:0;height:var(--bs-card-height);color:var(--bs-body-color);word-wrap:break-word;background-color:var(--bs-card-bg);background-clip:border-box;border:var(--bs-card-border-width) solid var(--bs-card-border-color);border-radius:var(--bs-card-border-radius)}.card>hr{margin-right:0;margin-left:0}.card>.list-group{border-top:inherit;border-bottom:inherit}.card>.list-group:first-child{border-top-width:0;border-top-left-radius:var(--bs-card-inner-border-radius);border-top-right-radius:var(--bs-card-inner-border-radius)}.card>.list-group:last-child{border-bottom-width:0;border-bottom-right-radius:var(--bs-card-inner-border-radius);border-bottom-left-radius:var(--bs-card-inner-border-radius)}.card>.card-header+.list-group,.card>.list-group+.card-footer{border-top:0}.card-body{flex:1 1 auto;-webkit-flex:1 1 auto;padding:var(--bs-card-spacer-y) var(--bs-card-spacer-x);color:var(--bs-card-color)}.card-title{margin-bottom:var(--bs-card-title-spacer-y);color:var(--bs-card-title-color)}.card-subtitle{margin-top:calc(-0.5*var(--bs-card-title-spacer-y));margin-bottom:0;color:var(--bs-card-subtitle-color)}.card-text:last-child{margin-bottom:0}.card-link+.card-link{margin-left:var(--bs-card-spacer-x)}.card-header{padding:var(--bs-card-cap-padding-y) var(--bs-card-cap-padding-x);margin-bottom:0;color:var(--bs-card-cap-color);background-color:var(--bs-card-cap-bg);border-bottom:var(--bs-card-border-width) solid var(--bs-card-border-color)}.card-header:first-child{border-radius:var(--bs-card-inner-border-radius) var(--bs-card-inner-border-radius) 0 0}.card-footer{padding:var(--bs-card-cap-padding-y) var(--bs-card-cap-padding-x);color:var(--bs-card-cap-color);background-color:var(--bs-card-cap-bg);border-top:var(--bs-card-border-width) solid var(--bs-card-border-color)}.card-footer:last-child{border-radius:0 0 var(--bs-card-inner-border-radius) var(--bs-card-inner-border-radius)}.card-header-tabs{margin-right:calc(-0.5*var(--bs-card-cap-padding-x));margin-bottom:calc(-1*var(--bs-card-cap-padding-y));margin-left:calc(-0.5*var(--bs-card-cap-padding-x));border-bottom:0}.card-header-tabs .nav-link.active{background-color:var(--bs-card-bg);border-bottom-color:var(--bs-card-bg)}.card-header-pills{margin-right:calc(-0.5*var(--bs-card-cap-padding-x));margin-left:calc(-0.5*var(--bs-card-cap-padding-x))}.card-img-overlay{position:absolute;top:0;right:0;bottom:0;left:0;padding:var(--bs-card-img-overlay-padding);border-radius:var(--bs-card-inner-border-radius)}.card-img,.card-img-top,.card-img-bottom{width:100%}.card-img,.card-img-top{border-top-left-radius:var(--bs-card-inner-border-radius);border-top-right-radius:var(--bs-card-inner-border-radius)}.card-img,.card-img-bottom{border-bottom-right-radius:var(--bs-card-inner-border-radius);border-bottom-left-radius:var(--bs-card-inner-border-radius)}.card-group>.card{margin-bottom:var(--bs-card-group-margin)}@media(min-width: 576px){.card-group{display:flex;display:-webkit-flex;flex-flow:row wrap;-webkit-flex-flow:row wrap}.card-group>.card{flex:1 0 0%;-webkit-flex:1 0 0%;margin-bottom:0}.card-group>.card+.card{margin-left:0;border-left:0}.card-group>.card:not(:last-child){border-top-right-radius:0;border-bottom-right-radius:0}.card-group>.card:not(:last-child) .card-img-top,.card-group>.card:not(:last-child) .card-header{border-top-right-radius:0}.card-group>.card:not(:last-child) .card-img-bottom,.card-group>.card:not(:last-child) .card-footer{border-bottom-right-radius:0}.card-group>.card:not(:first-child){border-top-left-radius:0;border-bottom-left-radius:0}.card-group>.card:not(:first-child) .card-img-top,.card-group>.card:not(:first-child) .card-header{border-top-left-radius:0}.card-group>.card:not(:first-child) .card-img-bottom,.card-group>.card:not(:first-child) .card-footer{border-bottom-left-radius:0}}.accordion{--bs-accordion-color: #fff;--bs-accordion-bg: #222;--bs-accordion-transition: color 0.15s ease-in-out, background-color 0.15s ease-in-out, border-color 0.15s ease-in-out, box-shadow 0.15s ease-in-out, border-radius 0.15s ease;--bs-accordion-border-color: #dee2e6;--bs-accordion-border-width: 1px;--bs-accordion-border-radius: 0.25rem;--bs-accordion-inner-border-radius: calc(0.25rem - 1px);--bs-accordion-btn-padding-x: 1.25rem;--bs-accordion-btn-padding-y: 1rem;--bs-accordion-btn-color: #fff;--bs-accordion-btn-bg: #222;--bs-accordion-btn-icon: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='%23fff'%3e%3cpath fill-rule='evenodd' d='M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z'/%3e%3c/svg%3e");--bs-accordion-btn-icon-width: 1.25rem;--bs-accordion-btn-icon-transform: rotate(-180deg);--bs-accordion-btn-icon-transition: transform 0.2s ease-in-out;--bs-accordion-btn-active-icon: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='%23162433'%3e%3cpath fill-rule='evenodd' d='M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z'/%3e%3c/svg%3e");--bs-accordion-btn-focus-border-color: #9badbf;--bs-accordion-btn-focus-box-shadow: 0 0 0 0.25rem rgba(55, 90, 127, 0.25);--bs-accordion-body-padding-x: 1.25rem;--bs-accordion-body-padding-y: 1rem;--bs-accordion-active-color: #162433;--bs-accordion-active-bg: #d7dee5}.accordion-button{position:relative;display:flex;display:-webkit-flex;align-items:center;-webkit-align-items:center;width:100%;padding:var(--bs-accordion-btn-padding-y) var(--bs-accordion-btn-padding-x);font-size:1rem;color:var(--bs-accordion-btn-color);text-align:left;background-color:var(--bs-accordion-btn-bg);border:0;border-radius:0;overflow-anchor:none;transition:var(--bs-accordion-transition)}@media(prefers-reduced-motion: reduce){.accordion-button{transition:none}}.accordion-button:not(.collapsed){color:var(--bs-accordion-active-color);background-color:var(--bs-accordion-active-bg);box-shadow:inset 0 calc(-1*var(--bs-accordion-border-width)) 0 var(--bs-accordion-border-color)}.accordion-button:not(.collapsed)::after{background-image:var(--bs-accordion-btn-active-icon);transform:var(--bs-accordion-btn-icon-transform)}.accordion-button::after{flex-shrink:0;-webkit-flex-shrink:0;width:var(--bs-accordion-btn-icon-width);height:var(--bs-accordion-btn-icon-width);margin-left:auto;content:"";background-image:var(--bs-accordion-btn-icon);background-repeat:no-repeat;background-size:var(--bs-accordion-btn-icon-width);transition:var(--bs-accordion-btn-icon-transition)}@media(prefers-reduced-motion: reduce){.accordion-button::after{transition:none}}.accordion-button:hover{z-index:2}.accordion-button:focus{z-index:3;border-color:var(--bs-accordion-btn-focus-border-color);outline:0;box-shadow:var(--bs-accordion-btn-focus-box-shadow)}.accordion-header{margin-bottom:0}.accordion-item{color:var(--bs-accordion-color);background-color:var(--bs-accordion-bg);border:var(--bs-accordion-border-width) solid var(--bs-accordion-border-color)}.accordion-item:first-of-type{border-top-left-radius:var(--bs-accordion-border-radius);border-top-right-radius:var(--bs-accordion-border-radius)}.accordion-item:first-of-type .accordion-button{border-top-left-radius:var(--bs-accordion-inner-border-radius);border-top-right-radius:var(--bs-accordion-inner-border-radius)}.accordion-item:not(:first-of-type){border-top:0}.accordion-item:last-of-type{border-bottom-right-radius:var(--bs-accordion-border-radius);border-bottom-left-radius:var(--bs-accordion-border-radius)}.accordion-item:last-of-type .accordion-button.collapsed{border-bottom-right-radius:var(--bs-accordion-inner-border-radius);border-bottom-left-radius:var(--bs-accordion-inner-border-radius)}.accordion-item:last-of-type .accordion-collapse{border-bottom-right-radius:var(--bs-accordion-border-radius);border-bottom-left-radius:var(--bs-accordion-border-radius)}.accordion-body{padding:var(--bs-accordion-body-padding-y) var(--bs-accordion-body-padding-x)}.accordion-flush .accordion-collapse{border-width:0}.accordion-flush .accordion-item{border-right:0;border-left:0;border-radius:0}.accordion-flush .accordion-item:first-child{border-top:0}.accordion-flush .accordion-item:last-child{border-bottom:0}.accordion-flush .accordion-item .accordion-button,.accordion-flush .accordion-item .accordion-button.collapsed{border-radius:0}[data-bs-theme=dark] .accordion-button::after{--bs-accordion-btn-icon: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='%23879cb2'%3e%3cpath fill-rule='evenodd' d='M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z'/%3e%3c/svg%3e");--bs-accordion-btn-active-icon: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='%23879cb2'%3e%3cpath fill-rule='evenodd' d='M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z'/%3e%3c/svg%3e")}.breadcrumb{--bs-breadcrumb-padding-x: 0.75rem;--bs-breadcrumb-padding-y: 0.375rem;--bs-breadcrumb-margin-bottom: 1rem;--bs-breadcrumb-bg: #434343;--bs-breadcrumb-border-radius: 0.25rem;--bs-breadcrumb-divider-color: rgba(255, 255, 255, 0.75);--bs-breadcrumb-item-padding-x: 0.5rem;--bs-breadcrumb-item-active-color: rgba(255, 255, 255, 0.75);display:flex;display:-webkit-flex;flex-wrap:wrap;-webkit-flex-wrap:wrap;padding:var(--bs-breadcrumb-padding-y) var(--bs-breadcrumb-padding-x);margin-bottom:var(--bs-breadcrumb-margin-bottom);font-size:var(--bs-breadcrumb-font-size);list-style:none;background-color:var(--bs-breadcrumb-bg);border-radius:var(--bs-breadcrumb-border-radius)}.breadcrumb-item+.breadcrumb-item{padding-left:var(--bs-breadcrumb-item-padding-x)}.breadcrumb-item+.breadcrumb-item::before{float:left;padding-right:var(--bs-breadcrumb-item-padding-x);color:var(--bs-breadcrumb-divider-color);content:var(--bs-breadcrumb-divider, ">") /* rtl: var(--bs-breadcrumb-divider, ">") */}.breadcrumb-item.active{color:var(--bs-breadcrumb-item-active-color)}.pagination{--bs-pagination-padding-x: 0.75rem;--bs-pagination-padding-y: 0.375rem;--bs-pagination-font-size:1rem;--bs-pagination-color: #fff;--bs-pagination-bg: #00bc8c;--bs-pagination-border-width: 0;--bs-pagination-border-color: transparent;--bs-pagination-border-radius: 0.25rem;--bs-pagination-hover-color: #fff;--bs-pagination-hover-bg: #00efb2;--bs-pagination-hover-border-color: transparent;--bs-pagination-focus-color: #009670;--bs-pagination-focus-bg: #ebebeb;--bs-pagination-focus-box-shadow: 0 0 0 0.25rem rgba(55, 90, 127, 0.25);--bs-pagination-active-color: #fff;--bs-pagination-active-bg: #00efb2;--bs-pagination-active-border-color: transparent;--bs-pagination-disabled-color: #fff;--bs-pagination-disabled-bg: #007053;--bs-pagination-disabled-border-color: transparent;display:flex;display:-webkit-flex;padding-left:0;list-style:none}.page-link{position:relative;display:block;padding:var(--bs-pagination-padding-y) var(--bs-pagination-padding-x);font-size:var(--bs-pagination-font-size);color:var(--bs-pagination-color);text-decoration:none;-webkit-text-decoration:none;-moz-text-decoration:none;-ms-text-decoration:none;-o-text-decoration:none;background-color:var(--bs-pagination-bg);border:var(--bs-pagination-border-width) solid var(--bs-pagination-border-color);transition:color .15s ease-in-out,background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media(prefers-reduced-motion: reduce){.page-link{transition:none}}.page-link:hover{z-index:2;color:var(--bs-pagination-hover-color);background-color:var(--bs-pagination-hover-bg);border-color:var(--bs-pagination-hover-border-color)}.page-link:focus{z-index:3;color:var(--bs-pagination-focus-color);background-color:var(--bs-pagination-focus-bg);outline:0;box-shadow:var(--bs-pagination-focus-box-shadow)}.page-link.active,.active>.page-link{z-index:3;color:var(--bs-pagination-active-color);background-color:var(--bs-pagination-active-bg);border-color:var(--bs-pagination-active-border-color)}.page-link.disabled,.disabled>.page-link{color:var(--bs-pagination-disabled-color);pointer-events:none;background-color:var(--bs-pagination-disabled-bg);border-color:var(--bs-pagination-disabled-border-color)}.page-item:not(:first-child) .page-link{margin-left:calc(0*-1)}.page-item:first-child .page-link{border-top-left-radius:var(--bs-pagination-border-radius);border-bottom-left-radius:var(--bs-pagination-border-radius)}.page-item:last-child .page-link{border-top-right-radius:var(--bs-pagination-border-radius);border-bottom-right-radius:var(--bs-pagination-border-radius)}.pagination-lg{--bs-pagination-padding-x: 1.5rem;--bs-pagination-padding-y: 0.75rem;--bs-pagination-font-size:1.25rem;--bs-pagination-border-radius: 0.5rem}.pagination-sm{--bs-pagination-padding-x: 0.5rem;--bs-pagination-padding-y: 0.25rem;--bs-pagination-font-size:0.875rem;--bs-pagination-border-radius: 0.2em}.badge{--bs-badge-padding-x: 0.65em;--bs-badge-padding-y: 0.35em;--bs-badge-font-size:0.75em;--bs-badge-font-weight: 700;--bs-badge-color: #fff;--bs-badge-border-radius: 0.25rem;display:inline-block;padding:var(--bs-badge-padding-y) var(--bs-badge-padding-x);font-size:var(--bs-badge-font-size);font-weight:var(--bs-badge-font-weight);line-height:1;color:var(--bs-badge-color);text-align:center;white-space:nowrap;vertical-align:baseline;border-radius:var(--bs-badge-border-radius)}.badge:empty{display:none}.btn .badge{position:relative;top:-1px}.alert{--bs-alert-bg: transparent;--bs-alert-padding-x: 1rem;--bs-alert-padding-y: 1rem;--bs-alert-margin-bottom: 1rem;--bs-alert-color: inherit;--bs-alert-border-color: transparent;--bs-alert-border: 1px solid var(--bs-alert-border-color);--bs-alert-border-radius: 0.25rem;--bs-alert-link-color: inherit;position:relative;padding:var(--bs-alert-padding-y) var(--bs-alert-padding-x);margin-bottom:var(--bs-alert-margin-bottom);color:var(--bs-alert-color);background-color:var(--bs-alert-bg);border:var(--bs-alert-border);border-radius:var(--bs-alert-border-radius)}.alert-heading{color:inherit}.alert-link{font-weight:700;color:var(--bs-alert-link-color)}.alert-dismissible{padding-right:3rem}.alert-dismissible .btn-close{position:absolute;top:0;right:0;z-index:2;padding:1.25rem 1rem}.alert-default{--bs-alert-color: var(--bs-default-text-emphasis);--bs-alert-bg: var(--bs-default-bg-subtle);--bs-alert-border-color: var(--bs-default-border-subtle);--bs-alert-link-color: var(--bs-default-text-emphasis)}.alert-primary{--bs-alert-color: var(--bs-primary-text-emphasis);--bs-alert-bg: var(--bs-primary-bg-subtle);--bs-alert-border-color: var(--bs-primary-border-subtle);--bs-alert-link-color: var(--bs-primary-text-emphasis)}.alert-secondary{--bs-alert-color: var(--bs-secondary-text-emphasis);--bs-alert-bg: var(--bs-secondary-bg-subtle);--bs-alert-border-color: var(--bs-secondary-border-subtle);--bs-alert-link-color: var(--bs-secondary-text-emphasis)}.alert-success{--bs-alert-color: var(--bs-success-text-emphasis);--bs-alert-bg: var(--bs-success-bg-subtle);--bs-alert-border-color: var(--bs-success-border-subtle);--bs-alert-link-color: var(--bs-success-text-emphasis)}.alert-info{--bs-alert-color: var(--bs-info-text-emphasis);--bs-alert-bg: var(--bs-info-bg-subtle);--bs-alert-border-color: var(--bs-info-border-subtle);--bs-alert-link-color: var(--bs-info-text-emphasis)}.alert-warning{--bs-alert-color: var(--bs-warning-text-emphasis);--bs-alert-bg: var(--bs-warning-bg-subtle);--bs-alert-border-color: var(--bs-warning-border-subtle);--bs-alert-link-color: var(--bs-warning-text-emphasis)}.alert-danger{--bs-alert-color: var(--bs-danger-text-emphasis);--bs-alert-bg: var(--bs-danger-bg-subtle);--bs-alert-border-color: var(--bs-danger-border-subtle);--bs-alert-link-color: var(--bs-danger-text-emphasis)}.alert-light{--bs-alert-color: var(--bs-light-text-emphasis);--bs-alert-bg: var(--bs-light-bg-subtle);--bs-alert-border-color: var(--bs-light-border-subtle);--bs-alert-link-color: var(--bs-light-text-emphasis)}.alert-dark{--bs-alert-color: var(--bs-dark-text-emphasis);--bs-alert-bg: var(--bs-dark-bg-subtle);--bs-alert-border-color: var(--bs-dark-border-subtle);--bs-alert-link-color: var(--bs-dark-text-emphasis)}@keyframes progress-bar-stripes{0%{background-position-x:1rem}}.progress,.progress-stacked{--bs-progress-height: 1rem;--bs-progress-font-size:0.75rem;--bs-progress-bg: #434343;--bs-progress-border-radius: 0.25rem;--bs-progress-box-shadow: inset 0 1px 2px rgba(0, 0, 0, 0.075);--bs-progress-bar-color: #fff;--bs-progress-bar-bg: #375a7f;--bs-progress-bar-transition: width 0.6s ease;display:flex;display:-webkit-flex;height:var(--bs-progress-height);overflow:hidden;font-size:var(--bs-progress-font-size);background-color:var(--bs-progress-bg);border-radius:var(--bs-progress-border-radius)}.progress-bar{display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;justify-content:center;-webkit-justify-content:center;overflow:hidden;color:var(--bs-progress-bar-color);text-align:center;white-space:nowrap;background-color:var(--bs-progress-bar-bg);transition:var(--bs-progress-bar-transition)}@media(prefers-reduced-motion: reduce){.progress-bar{transition:none}}.progress-bar-striped{background-image:linear-gradient(45deg, rgba(255, 255, 255, 0.15) 25%, transparent 25%, transparent 50%, rgba(255, 255, 255, 0.15) 50%, rgba(255, 255, 255, 0.15) 75%, transparent 75%, transparent);background-size:var(--bs-progress-height) var(--bs-progress-height)}.progress-stacked>.progress{overflow:visible}.progress-stacked>.progress>.progress-bar{width:100%}.progress-bar-animated{animation:1s linear infinite progress-bar-stripes}@media(prefers-reduced-motion: reduce){.progress-bar-animated{animation:none}}.list-group{--bs-list-group-color: #fff;--bs-list-group-bg: #2d2d2d;--bs-list-group-border-color: #434343;--bs-list-group-border-width: 1px;--bs-list-group-border-radius: 0.25rem;--bs-list-group-item-padding-x: 1rem;--bs-list-group-item-padding-y: 0.5rem;--bs-list-group-action-color: rgba(255, 255, 255, 0.75);--bs-list-group-action-hover-color: #fff;--bs-list-group-action-hover-bg: #434343;--bs-list-group-action-active-color: #fff;--bs-list-group-action-active-bg: #222;--bs-list-group-disabled-color: rgba(255, 255, 255, 0.75);--bs-list-group-disabled-bg: #2d2d2d;--bs-list-group-active-color: #fff;--bs-list-group-active-bg: #375a7f;--bs-list-group-active-border-color: #375a7f;display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;padding-left:0;margin-bottom:0;border-radius:var(--bs-list-group-border-radius)}.list-group-numbered{list-style-type:none;counter-reset:section}.list-group-numbered>.list-group-item::before{content:counters(section, ".") ". ";counter-increment:section}.list-group-item-action{width:100%;color:var(--bs-list-group-action-color);text-align:inherit}.list-group-item-action:hover,.list-group-item-action:focus{z-index:1;color:var(--bs-list-group-action-hover-color);text-decoration:none;background-color:var(--bs-list-group-action-hover-bg)}.list-group-item-action:active{color:var(--bs-list-group-action-active-color);background-color:var(--bs-list-group-action-active-bg)}.list-group-item{position:relative;display:block;padding:var(--bs-list-group-item-padding-y) var(--bs-list-group-item-padding-x);color:var(--bs-list-group-color);text-decoration:none;-webkit-text-decoration:none;-moz-text-decoration:none;-ms-text-decoration:none;-o-text-decoration:none;background-color:var(--bs-list-group-bg);border:var(--bs-list-group-border-width) solid var(--bs-list-group-border-color)}.list-group-item:first-child{border-top-left-radius:inherit;border-top-right-radius:inherit}.list-group-item:last-child{border-bottom-right-radius:inherit;border-bottom-left-radius:inherit}.list-group-item.disabled,.list-group-item:disabled{color:var(--bs-list-group-disabled-color);pointer-events:none;background-color:var(--bs-list-group-disabled-bg)}.list-group-item.active{z-index:2;color:var(--bs-list-group-active-color);background-color:var(--bs-list-group-active-bg);border-color:var(--bs-list-group-active-border-color)}.list-group-item+.list-group-item{border-top-width:0}.list-group-item+.list-group-item.active{margin-top:calc(-1*var(--bs-list-group-border-width));border-top-width:var(--bs-list-group-border-width)}.list-group-horizontal{flex-direction:row;-webkit-flex-direction:row}.list-group-horizontal>.list-group-item:first-child:not(:last-child){border-bottom-left-radius:var(--bs-list-group-border-radius);border-top-right-radius:0}.list-group-horizontal>.list-group-item:last-child:not(:first-child){border-top-right-radius:var(--bs-list-group-border-radius);border-bottom-left-radius:0}.list-group-horizontal>.list-group-item.active{margin-top:0}.list-group-horizontal>.list-group-item+.list-group-item{border-top-width:var(--bs-list-group-border-width);border-left-width:0}.list-group-horizontal>.list-group-item+.list-group-item.active{margin-left:calc(-1*var(--bs-list-group-border-width));border-left-width:var(--bs-list-group-border-width)}@media(min-width: 576px){.list-group-horizontal-sm{flex-direction:row;-webkit-flex-direction:row}.list-group-horizontal-sm>.list-group-item:first-child:not(:last-child){border-bottom-left-radius:var(--bs-list-group-border-radius);border-top-right-radius:0}.list-group-horizontal-sm>.list-group-item:last-child:not(:first-child){border-top-right-radius:var(--bs-list-group-border-radius);border-bottom-left-radius:0}.list-group-horizontal-sm>.list-group-item.active{margin-top:0}.list-group-horizontal-sm>.list-group-item+.list-group-item{border-top-width:var(--bs-list-group-border-width);border-left-width:0}.list-group-horizontal-sm>.list-group-item+.list-group-item.active{margin-left:calc(-1*var(--bs-list-group-border-width));border-left-width:var(--bs-list-group-border-width)}}@media(min-width: 768px){.list-group-horizontal-md{flex-direction:row;-webkit-flex-direction:row}.list-group-horizontal-md>.list-group-item:first-child:not(:last-child){border-bottom-left-radius:var(--bs-list-group-border-radius);border-top-right-radius:0}.list-group-horizontal-md>.list-group-item:last-child:not(:first-child){border-top-right-radius:var(--bs-list-group-border-radius);border-bottom-left-radius:0}.list-group-horizontal-md>.list-group-item.active{margin-top:0}.list-group-horizontal-md>.list-group-item+.list-group-item{border-top-width:var(--bs-list-group-border-width);border-left-width:0}.list-group-horizontal-md>.list-group-item+.list-group-item.active{margin-left:calc(-1*var(--bs-list-group-border-width));border-left-width:var(--bs-list-group-border-width)}}@media(min-width: 992px){.list-group-horizontal-lg{flex-direction:row;-webkit-flex-direction:row}.list-group-horizontal-lg>.list-group-item:first-child:not(:last-child){border-bottom-left-radius:var(--bs-list-group-border-radius);border-top-right-radius:0}.list-group-horizontal-lg>.list-group-item:last-child:not(:first-child){border-top-right-radius:var(--bs-list-group-border-radius);border-bottom-left-radius:0}.list-group-horizontal-lg>.list-group-item.active{margin-top:0}.list-group-horizontal-lg>.list-group-item+.list-group-item{border-top-width:var(--bs-list-group-border-width);border-left-width:0}.list-group-horizontal-lg>.list-group-item+.list-group-item.active{margin-left:calc(-1*var(--bs-list-group-border-width));border-left-width:var(--bs-list-group-border-width)}}@media(min-width: 1200px){.list-group-horizontal-xl{flex-direction:row;-webkit-flex-direction:row}.list-group-horizontal-xl>.list-group-item:first-child:not(:last-child){border-bottom-left-radius:var(--bs-list-group-border-radius);border-top-right-radius:0}.list-group-horizontal-xl>.list-group-item:last-child:not(:first-child){border-top-right-radius:var(--bs-list-group-border-radius);border-bottom-left-radius:0}.list-group-horizontal-xl>.list-group-item.active{margin-top:0}.list-group-horizontal-xl>.list-group-item+.list-group-item{border-top-width:var(--bs-list-group-border-width);border-left-width:0}.list-group-horizontal-xl>.list-group-item+.list-group-item.active{margin-left:calc(-1*var(--bs-list-group-border-width));border-left-width:var(--bs-list-group-border-width)}}@media(min-width: 1400px){.list-group-horizontal-xxl{flex-direction:row;-webkit-flex-direction:row}.list-group-horizontal-xxl>.list-group-item:first-child:not(:last-child){border-bottom-left-radius:var(--bs-list-group-border-radius);border-top-right-radius:0}.list-group-horizontal-xxl>.list-group-item:last-child:not(:first-child){border-top-right-radius:var(--bs-list-group-border-radius);border-bottom-left-radius:0}.list-group-horizontal-xxl>.list-group-item.active{margin-top:0}.list-group-horizontal-xxl>.list-group-item+.list-group-item{border-top-width:var(--bs-list-group-border-width);border-left-width:0}.list-group-horizontal-xxl>.list-group-item+.list-group-item.active{margin-left:calc(-1*var(--bs-list-group-border-width));border-left-width:var(--bs-list-group-border-width)}}.list-group-flush{border-radius:0}.list-group-flush>.list-group-item{border-width:0 0 var(--bs-list-group-border-width)}.list-group-flush>.list-group-item:last-child{border-bottom-width:0}.list-group-item-default{--bs-list-group-color: var(--bs-default-text-emphasis);--bs-list-group-bg: var(--bs-default-bg-subtle);--bs-list-group-border-color: var(--bs-default-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-default-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-default-border-subtle);--bs-list-group-active-color: var(--bs-default-bg-subtle);--bs-list-group-active-bg: var(--bs-default-text-emphasis);--bs-list-group-active-border-color: var(--bs-default-text-emphasis)}.list-group-item-primary{--bs-list-group-color: var(--bs-primary-text-emphasis);--bs-list-group-bg: var(--bs-primary-bg-subtle);--bs-list-group-border-color: var(--bs-primary-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-primary-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-primary-border-subtle);--bs-list-group-active-color: var(--bs-primary-bg-subtle);--bs-list-group-active-bg: var(--bs-primary-text-emphasis);--bs-list-group-active-border-color: var(--bs-primary-text-emphasis)}.list-group-item-secondary{--bs-list-group-color: var(--bs-secondary-text-emphasis);--bs-list-group-bg: var(--bs-secondary-bg-subtle);--bs-list-group-border-color: var(--bs-secondary-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-secondary-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-secondary-border-subtle);--bs-list-group-active-color: var(--bs-secondary-bg-subtle);--bs-list-group-active-bg: var(--bs-secondary-text-emphasis);--bs-list-group-active-border-color: var(--bs-secondary-text-emphasis)}.list-group-item-success{--bs-list-group-color: var(--bs-success-text-emphasis);--bs-list-group-bg: var(--bs-success-bg-subtle);--bs-list-group-border-color: var(--bs-success-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-success-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-success-border-subtle);--bs-list-group-active-color: var(--bs-success-bg-subtle);--bs-list-group-active-bg: var(--bs-success-text-emphasis);--bs-list-group-active-border-color: var(--bs-success-text-emphasis)}.list-group-item-info{--bs-list-group-color: var(--bs-info-text-emphasis);--bs-list-group-bg: var(--bs-info-bg-subtle);--bs-list-group-border-color: var(--bs-info-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-info-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-info-border-subtle);--bs-list-group-active-color: var(--bs-info-bg-subtle);--bs-list-group-active-bg: var(--bs-info-text-emphasis);--bs-list-group-active-border-color: var(--bs-info-text-emphasis)}.list-group-item-warning{--bs-list-group-color: var(--bs-warning-text-emphasis);--bs-list-group-bg: var(--bs-warning-bg-subtle);--bs-list-group-border-color: var(--bs-warning-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-warning-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-warning-border-subtle);--bs-list-group-active-color: var(--bs-warning-bg-subtle);--bs-list-group-active-bg: var(--bs-warning-text-emphasis);--bs-list-group-active-border-color: var(--bs-warning-text-emphasis)}.list-group-item-danger{--bs-list-group-color: var(--bs-danger-text-emphasis);--bs-list-group-bg: var(--bs-danger-bg-subtle);--bs-list-group-border-color: var(--bs-danger-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-danger-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-danger-border-subtle);--bs-list-group-active-color: var(--bs-danger-bg-subtle);--bs-list-group-active-bg: var(--bs-danger-text-emphasis);--bs-list-group-active-border-color: var(--bs-danger-text-emphasis)}.list-group-item-light{--bs-list-group-color: var(--bs-light-text-emphasis);--bs-list-group-bg: var(--bs-light-bg-subtle);--bs-list-group-border-color: var(--bs-light-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-light-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-light-border-subtle);--bs-list-group-active-color: var(--bs-light-bg-subtle);--bs-list-group-active-bg: var(--bs-light-text-emphasis);--bs-list-group-active-border-color: var(--bs-light-text-emphasis)}.list-group-item-dark{--bs-list-group-color: var(--bs-dark-text-emphasis);--bs-list-group-bg: var(--bs-dark-bg-subtle);--bs-list-group-border-color: var(--bs-dark-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-dark-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-dark-border-subtle);--bs-list-group-active-color: var(--bs-dark-bg-subtle);--bs-list-group-active-bg: var(--bs-dark-text-emphasis);--bs-list-group-active-border-color: var(--bs-dark-text-emphasis)}.btn-close{--bs-btn-close-color: #fff;--bs-btn-close-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='%23fff'%3e%3cpath d='M.293.293a1 1 0 0 1 1.414 0L8 6.586 14.293.293a1 1 0 1 1 1.414 1.414L9.414 8l6.293 6.293a1 1 0 0 1-1.414 1.414L8 9.414l-6.293 6.293a1 1 0 0 1-1.414-1.414L6.586 8 .293 1.707a1 1 0 0 1 0-1.414z'/%3e%3c/svg%3e");--bs-btn-close-opacity: 0.4;--bs-btn-close-hover-opacity: 1;--bs-btn-close-focus-shadow: 0 0 0 0.25rem rgba(55, 90, 127, 0.25);--bs-btn-close-focus-opacity: 1;--bs-btn-close-disabled-opacity: 0.25;--bs-btn-close-white-filter: invert(1) grayscale(100%) brightness(200%);box-sizing:content-box;width:1em;height:1em;padding:.25em .25em;color:var(--bs-btn-close-color);background:rgba(0,0,0,0) var(--bs-btn-close-bg) center/1em auto no-repeat;border:0;border-radius:.25rem;opacity:var(--bs-btn-close-opacity)}.btn-close:hover{color:var(--bs-btn-close-color);text-decoration:none;opacity:var(--bs-btn-close-hover-opacity)}.btn-close:focus{outline:0;box-shadow:var(--bs-btn-close-focus-shadow);opacity:var(--bs-btn-close-focus-opacity)}.btn-close:disabled,.btn-close.disabled{pointer-events:none;user-select:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;-o-user-select:none;opacity:var(--bs-btn-close-disabled-opacity)}.btn-close-white{filter:var(--bs-btn-close-white-filter)}[data-bs-theme=dark] .btn-close{filter:var(--bs-btn-close-white-filter)}.toast{--bs-toast-zindex: 1090;--bs-toast-padding-x: 0.75rem;--bs-toast-padding-y: 0.5rem;--bs-toast-spacing: 1.5rem;--bs-toast-max-width: 350px;--bs-toast-font-size:0.875rem;--bs-toast-color: ;--bs-toast-bg: #434343;--bs-toast-border-width: 1px;--bs-toast-border-color: rgba(0, 0, 0, 0.175);--bs-toast-border-radius: 0.25rem;--bs-toast-box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);--bs-toast-header-color: rgba(255, 255, 255, 0.75);--bs-toast-header-bg: #2d2d2d;--bs-toast-header-border-color: rgba(0, 0, 0, 0.175);width:var(--bs-toast-max-width);max-width:100%;font-size:var(--bs-toast-font-size);color:var(--bs-toast-color);pointer-events:auto;background-color:var(--bs-toast-bg);background-clip:padding-box;border:var(--bs-toast-border-width) solid var(--bs-toast-border-color);box-shadow:var(--bs-toast-box-shadow);border-radius:var(--bs-toast-border-radius)}.toast.showing{opacity:0}.toast:not(.show){display:none}.toast-container{--bs-toast-zindex: 1090;position:absolute;z-index:var(--bs-toast-zindex);width:max-content;width:-webkit-max-content;width:-moz-max-content;width:-ms-max-content;width:-o-max-content;max-width:100%;pointer-events:none}.toast-container>:not(:last-child){margin-bottom:var(--bs-toast-spacing)}.toast-header{display:flex;display:-webkit-flex;align-items:center;-webkit-align-items:center;padding:var(--bs-toast-padding-y) var(--bs-toast-padding-x);color:var(--bs-toast-header-color);background-color:var(--bs-toast-header-bg);background-clip:padding-box;border-bottom:var(--bs-toast-border-width) solid var(--bs-toast-header-border-color);border-top-left-radius:calc(var(--bs-toast-border-radius) - var(--bs-toast-border-width));border-top-right-radius:calc(var(--bs-toast-border-radius) - var(--bs-toast-border-width))}.toast-header .btn-close{margin-right:calc(-0.5*var(--bs-toast-padding-x));margin-left:var(--bs-toast-padding-x)}.toast-body{padding:var(--bs-toast-padding-x);word-wrap:break-word}.modal{--bs-modal-zindex: 1055;--bs-modal-width: 500px;--bs-modal-padding: 1rem;--bs-modal-margin: 0.5rem;--bs-modal-color: ;--bs-modal-bg: #2d2d2d;--bs-modal-border-color: #434343;--bs-modal-border-width: 1px;--bs-modal-border-radius: 0.5rem;--bs-modal-box-shadow: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.075);--bs-modal-inner-border-radius: calc(0.5rem - 1px);--bs-modal-header-padding-x: 1rem;--bs-modal-header-padding-y: 1rem;--bs-modal-header-padding: 1rem 1rem;--bs-modal-header-border-color: #434343;--bs-modal-header-border-width: 1px;--bs-modal-title-line-height: 1.5;--bs-modal-footer-gap: 0.5rem;--bs-modal-footer-bg: ;--bs-modal-footer-border-color: #434343;--bs-modal-footer-border-width: 1px;position:fixed;top:0;left:0;z-index:var(--bs-modal-zindex);display:none;width:100%;height:100%;overflow-x:hidden;overflow-y:auto;outline:0}.modal-dialog{position:relative;width:auto;margin:var(--bs-modal-margin);pointer-events:none}.modal.fade .modal-dialog{transition:transform .3s ease-out;transform:translate(0, -50px)}@media(prefers-reduced-motion: reduce){.modal.fade .modal-dialog{transition:none}}.modal.show .modal-dialog{transform:none}.modal.modal-static .modal-dialog{transform:scale(1.02)}.modal-dialog-scrollable{height:calc(100% - var(--bs-modal-margin)*2)}.modal-dialog-scrollable .modal-content{max-height:100%;overflow:hidden}.modal-dialog-scrollable .modal-body{overflow-y:auto}.modal-dialog-centered{display:flex;display:-webkit-flex;align-items:center;-webkit-align-items:center;min-height:calc(100% - var(--bs-modal-margin)*2)}.modal-content{position:relative;display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;width:100%;color:var(--bs-modal-color);pointer-events:auto;background-color:var(--bs-modal-bg);background-clip:padding-box;border:var(--bs-modal-border-width) solid var(--bs-modal-border-color);border-radius:var(--bs-modal-border-radius);outline:0}.modal-backdrop{--bs-backdrop-zindex: 1050;--bs-backdrop-bg: #000;--bs-backdrop-opacity: 0.5;position:fixed;top:0;left:0;z-index:var(--bs-backdrop-zindex);width:100vw;height:100vh;background-color:var(--bs-backdrop-bg)}.modal-backdrop.fade{opacity:0}.modal-backdrop.show{opacity:var(--bs-backdrop-opacity)}.modal-header{display:flex;display:-webkit-flex;flex-shrink:0;-webkit-flex-shrink:0;align-items:center;-webkit-align-items:center;justify-content:space-between;-webkit-justify-content:space-between;padding:var(--bs-modal-header-padding);border-bottom:var(--bs-modal-header-border-width) solid var(--bs-modal-header-border-color);border-top-left-radius:var(--bs-modal-inner-border-radius);border-top-right-radius:var(--bs-modal-inner-border-radius)}.modal-header .btn-close{padding:calc(var(--bs-modal-header-padding-y)*.5) calc(var(--bs-modal-header-padding-x)*.5);margin:calc(-0.5*var(--bs-modal-header-padding-y)) calc(-0.5*var(--bs-modal-header-padding-x)) calc(-0.5*var(--bs-modal-header-padding-y)) auto}.modal-title{margin-bottom:0;line-height:var(--bs-modal-title-line-height)}.modal-body{position:relative;flex:1 1 auto;-webkit-flex:1 1 auto;padding:var(--bs-modal-padding)}.modal-footer{display:flex;display:-webkit-flex;flex-shrink:0;-webkit-flex-shrink:0;flex-wrap:wrap;-webkit-flex-wrap:wrap;align-items:center;-webkit-align-items:center;justify-content:flex-end;-webkit-justify-content:flex-end;padding:calc(var(--bs-modal-padding) - var(--bs-modal-footer-gap)*.5);background-color:var(--bs-modal-footer-bg);border-top:var(--bs-modal-footer-border-width) solid var(--bs-modal-footer-border-color);border-bottom-right-radius:var(--bs-modal-inner-border-radius);border-bottom-left-radius:var(--bs-modal-inner-border-radius)}.modal-footer>*{margin:calc(var(--bs-modal-footer-gap)*.5)}@media(min-width: 576px){.modal{--bs-modal-margin: 1.75rem;--bs-modal-box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15)}.modal-dialog{max-width:var(--bs-modal-width);margin-right:auto;margin-left:auto}.modal-sm{--bs-modal-width: 300px}}@media(min-width: 992px){.modal-lg,.modal-xl{--bs-modal-width: 800px}}@media(min-width: 1200px){.modal-xl{--bs-modal-width: 1140px}}.modal-fullscreen{width:100vw;max-width:none;height:100%;margin:0}.modal-fullscreen .modal-content{height:100%;border:0;border-radius:0}.modal-fullscreen .modal-header,.modal-fullscreen .modal-footer{border-radius:0}.modal-fullscreen .modal-body{overflow-y:auto}@media(max-width: 575.98px){.modal-fullscreen-sm-down{width:100vw;max-width:none;height:100%;margin:0}.modal-fullscreen-sm-down .modal-content{height:100%;border:0;border-radius:0}.modal-fullscreen-sm-down .modal-header,.modal-fullscreen-sm-down .modal-footer{border-radius:0}.modal-fullscreen-sm-down .modal-body{overflow-y:auto}}@media(max-width: 767.98px){.modal-fullscreen-md-down{width:100vw;max-width:none;height:100%;margin:0}.modal-fullscreen-md-down .modal-content{height:100%;border:0;border-radius:0}.modal-fullscreen-md-down .modal-header,.modal-fullscreen-md-down .modal-footer{border-radius:0}.modal-fullscreen-md-down .modal-body{overflow-y:auto}}@media(max-width: 991.98px){.modal-fullscreen-lg-down{width:100vw;max-width:none;height:100%;margin:0}.modal-fullscreen-lg-down .modal-content{height:100%;border:0;border-radius:0}.modal-fullscreen-lg-down .modal-header,.modal-fullscreen-lg-down .modal-footer{border-radius:0}.modal-fullscreen-lg-down .modal-body{overflow-y:auto}}@media(max-width: 1199.98px){.modal-fullscreen-xl-down{width:100vw;max-width:none;height:100%;margin:0}.modal-fullscreen-xl-down .modal-content{height:100%;border:0;border-radius:0}.modal-fullscreen-xl-down .modal-header,.modal-fullscreen-xl-down .modal-footer{border-radius:0}.modal-fullscreen-xl-down .modal-body{overflow-y:auto}}@media(max-width: 1399.98px){.modal-fullscreen-xxl-down{width:100vw;max-width:none;height:100%;margin:0}.modal-fullscreen-xxl-down .modal-content{height:100%;border:0;border-radius:0}.modal-fullscreen-xxl-down .modal-header,.modal-fullscreen-xxl-down .modal-footer{border-radius:0}.modal-fullscreen-xxl-down .modal-body{overflow-y:auto}}.tooltip{--bs-tooltip-zindex: 1080;--bs-tooltip-max-width: 200px;--bs-tooltip-padding-x: 0.5rem;--bs-tooltip-padding-y: 0.25rem;--bs-tooltip-margin: ;--bs-tooltip-font-size:0.875rem;--bs-tooltip-color: #222;--bs-tooltip-bg: #000;--bs-tooltip-border-radius: 0.25rem;--bs-tooltip-opacity: 0.9;--bs-tooltip-arrow-width: 0.8rem;--bs-tooltip-arrow-height: 0.4rem;z-index:var(--bs-tooltip-zindex);display:block;margin:var(--bs-tooltip-margin);font-family:Lato,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol";font-style:normal;font-weight:400;line-height:1.5;text-align:left;text-align:start;text-decoration:none;text-shadow:none;text-transform:none;letter-spacing:normal;word-break:normal;white-space:normal;word-spacing:normal;line-break:auto;font-size:var(--bs-tooltip-font-size);word-wrap:break-word;opacity:0}.tooltip.show{opacity:var(--bs-tooltip-opacity)}.tooltip .tooltip-arrow{display:block;width:var(--bs-tooltip-arrow-width);height:var(--bs-tooltip-arrow-height)}.tooltip .tooltip-arrow::before{position:absolute;content:"";border-color:rgba(0,0,0,0);border-style:solid}.bs-tooltip-top .tooltip-arrow,.bs-tooltip-auto[data-popper-placement^=top] .tooltip-arrow{bottom:calc(-1*var(--bs-tooltip-arrow-height))}.bs-tooltip-top .tooltip-arrow::before,.bs-tooltip-auto[data-popper-placement^=top] .tooltip-arrow::before{top:-1px;border-width:var(--bs-tooltip-arrow-height) calc(var(--bs-tooltip-arrow-width)*.5) 0;border-top-color:var(--bs-tooltip-bg)}.bs-tooltip-end .tooltip-arrow,.bs-tooltip-auto[data-popper-placement^=right] .tooltip-arrow{left:calc(-1*var(--bs-tooltip-arrow-height));width:var(--bs-tooltip-arrow-height);height:var(--bs-tooltip-arrow-width)}.bs-tooltip-end .tooltip-arrow::before,.bs-tooltip-auto[data-popper-placement^=right] .tooltip-arrow::before{right:-1px;border-width:calc(var(--bs-tooltip-arrow-width)*.5) var(--bs-tooltip-arrow-height) calc(var(--bs-tooltip-arrow-width)*.5) 0;border-right-color:var(--bs-tooltip-bg)}.bs-tooltip-bottom .tooltip-arrow,.bs-tooltip-auto[data-popper-placement^=bottom] .tooltip-arrow{top:calc(-1*var(--bs-tooltip-arrow-height))}.bs-tooltip-bottom .tooltip-arrow::before,.bs-tooltip-auto[data-popper-placement^=bottom] .tooltip-arrow::before{bottom:-1px;border-width:0 calc(var(--bs-tooltip-arrow-width)*.5) var(--bs-tooltip-arrow-height);border-bottom-color:var(--bs-tooltip-bg)}.bs-tooltip-start .tooltip-arrow,.bs-tooltip-auto[data-popper-placement^=left] .tooltip-arrow{right:calc(-1*var(--bs-tooltip-arrow-height));width:var(--bs-tooltip-arrow-height);height:var(--bs-tooltip-arrow-width)}.bs-tooltip-start .tooltip-arrow::before,.bs-tooltip-auto[data-popper-placement^=left] .tooltip-arrow::before{left:-1px;border-width:calc(var(--bs-tooltip-arrow-width)*.5) 0 calc(var(--bs-tooltip-arrow-width)*.5) var(--bs-tooltip-arrow-height);border-left-color:var(--bs-tooltip-bg)}.tooltip-inner{max-width:var(--bs-tooltip-max-width);padding:var(--bs-tooltip-padding-y) var(--bs-tooltip-padding-x);color:var(--bs-tooltip-color);text-align:center;background-color:var(--bs-tooltip-bg);border-radius:var(--bs-tooltip-border-radius)}.popover{--bs-popover-zindex: 1070;--bs-popover-max-width: 276px;--bs-popover-font-size:0.875rem;--bs-popover-bg: #2d2d2d;--bs-popover-border-width: 1px;--bs-popover-border-color: rgba(0, 0, 0, 0.175);--bs-popover-border-radius: 0.5rem;--bs-popover-inner-border-radius: calc(0.5rem - 1px);--bs-popover-box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);--bs-popover-header-padding-x: 1rem;--bs-popover-header-padding-y: 0.5rem;--bs-popover-header-font-size:1rem;--bs-popover-header-color: inherit;--bs-popover-header-bg: #434343;--bs-popover-body-padding-x: 1rem;--bs-popover-body-padding-y: 1rem;--bs-popover-body-color: #fff;--bs-popover-arrow-width: 1rem;--bs-popover-arrow-height: 0.5rem;--bs-popover-arrow-border: var(--bs-popover-border-color);z-index:var(--bs-popover-zindex);display:block;max-width:var(--bs-popover-max-width);font-family:Lato,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol";font-style:normal;font-weight:400;line-height:1.5;text-align:left;text-align:start;text-decoration:none;text-shadow:none;text-transform:none;letter-spacing:normal;word-break:normal;white-space:normal;word-spacing:normal;line-break:auto;font-size:var(--bs-popover-font-size);word-wrap:break-word;background-color:var(--bs-popover-bg);background-clip:padding-box;border:var(--bs-popover-border-width) solid var(--bs-popover-border-color);border-radius:var(--bs-popover-border-radius)}.popover .popover-arrow{display:block;width:var(--bs-popover-arrow-width);height:var(--bs-popover-arrow-height)}.popover .popover-arrow::before,.popover .popover-arrow::after{position:absolute;display:block;content:"";border-color:rgba(0,0,0,0);border-style:solid;border-width:0}.bs-popover-top>.popover-arrow,.bs-popover-auto[data-popper-placement^=top]>.popover-arrow{bottom:calc(-1*(var(--bs-popover-arrow-height)) - var(--bs-popover-border-width))}.bs-popover-top>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=top]>.popover-arrow::before,.bs-popover-top>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=top]>.popover-arrow::after{border-width:var(--bs-popover-arrow-height) calc(var(--bs-popover-arrow-width)*.5) 0}.bs-popover-top>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=top]>.popover-arrow::before{bottom:0;border-top-color:var(--bs-popover-arrow-border)}.bs-popover-top>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=top]>.popover-arrow::after{bottom:var(--bs-popover-border-width);border-top-color:var(--bs-popover-bg)}.bs-popover-end>.popover-arrow,.bs-popover-auto[data-popper-placement^=right]>.popover-arrow{left:calc(-1*(var(--bs-popover-arrow-height)) - var(--bs-popover-border-width));width:var(--bs-popover-arrow-height);height:var(--bs-popover-arrow-width)}.bs-popover-end>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=right]>.popover-arrow::before,.bs-popover-end>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=right]>.popover-arrow::after{border-width:calc(var(--bs-popover-arrow-width)*.5) var(--bs-popover-arrow-height) calc(var(--bs-popover-arrow-width)*.5) 0}.bs-popover-end>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=right]>.popover-arrow::before{left:0;border-right-color:var(--bs-popover-arrow-border)}.bs-popover-end>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=right]>.popover-arrow::after{left:var(--bs-popover-border-width);border-right-color:var(--bs-popover-bg)}.bs-popover-bottom>.popover-arrow,.bs-popover-auto[data-popper-placement^=bottom]>.popover-arrow{top:calc(-1*(var(--bs-popover-arrow-height)) - var(--bs-popover-border-width))}.bs-popover-bottom>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=bottom]>.popover-arrow::before,.bs-popover-bottom>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=bottom]>.popover-arrow::after{border-width:0 calc(var(--bs-popover-arrow-width)*.5) var(--bs-popover-arrow-height)}.bs-popover-bottom>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=bottom]>.popover-arrow::before{top:0;border-bottom-color:var(--bs-popover-arrow-border)}.bs-popover-bottom>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=bottom]>.popover-arrow::after{top:var(--bs-popover-border-width);border-bottom-color:var(--bs-popover-bg)}.bs-popover-bottom .popover-header::before,.bs-popover-auto[data-popper-placement^=bottom] .popover-header::before{position:absolute;top:0;left:50%;display:block;width:var(--bs-popover-arrow-width);margin-left:calc(-0.5*var(--bs-popover-arrow-width));content:"";border-bottom:var(--bs-popover-border-width) solid var(--bs-popover-header-bg)}.bs-popover-start>.popover-arrow,.bs-popover-auto[data-popper-placement^=left]>.popover-arrow{right:calc(-1*(var(--bs-popover-arrow-height)) - var(--bs-popover-border-width));width:var(--bs-popover-arrow-height);height:var(--bs-popover-arrow-width)}.bs-popover-start>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=left]>.popover-arrow::before,.bs-popover-start>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=left]>.popover-arrow::after{border-width:calc(var(--bs-popover-arrow-width)*.5) 0 calc(var(--bs-popover-arrow-width)*.5) var(--bs-popover-arrow-height)}.bs-popover-start>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=left]>.popover-arrow::before{right:0;border-left-color:var(--bs-popover-arrow-border)}.bs-popover-start>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=left]>.popover-arrow::after{right:var(--bs-popover-border-width);border-left-color:var(--bs-popover-bg)}.popover-header{padding:var(--bs-popover-header-padding-y) var(--bs-popover-header-padding-x);margin-bottom:0;font-size:var(--bs-popover-header-font-size);color:var(--bs-popover-header-color);background-color:var(--bs-popover-header-bg);border-bottom:var(--bs-popover-border-width) solid var(--bs-popover-border-color);border-top-left-radius:var(--bs-popover-inner-border-radius);border-top-right-radius:var(--bs-popover-inner-border-radius)}.popover-header:empty{display:none}.popover-body{padding:var(--bs-popover-body-padding-y) var(--bs-popover-body-padding-x);color:var(--bs-popover-body-color)}.carousel{position:relative}.carousel.pointer-event{touch-action:pan-y;-webkit-touch-action:pan-y;-moz-touch-action:pan-y;-ms-touch-action:pan-y;-o-touch-action:pan-y}.carousel-inner{position:relative;width:100%;overflow:hidden}.carousel-inner::after{display:block;clear:both;content:""}.carousel-item{position:relative;display:none;float:left;width:100%;margin-right:-100%;backface-visibility:hidden;-webkit-backface-visibility:hidden;-moz-backface-visibility:hidden;-ms-backface-visibility:hidden;-o-backface-visibility:hidden;transition:transform .6s ease-in-out}@media(prefers-reduced-motion: reduce){.carousel-item{transition:none}}.carousel-item.active,.carousel-item-next,.carousel-item-prev{display:block}.carousel-item-next:not(.carousel-item-start),.active.carousel-item-end{transform:translateX(100%)}.carousel-item-prev:not(.carousel-item-end),.active.carousel-item-start{transform:translateX(-100%)}.carousel-fade .carousel-item{opacity:0;transition-property:opacity;transform:none}.carousel-fade .carousel-item.active,.carousel-fade .carousel-item-next.carousel-item-start,.carousel-fade .carousel-item-prev.carousel-item-end{z-index:1;opacity:1}.carousel-fade .active.carousel-item-start,.carousel-fade .active.carousel-item-end{z-index:0;opacity:0;transition:opacity 0s .6s}@media(prefers-reduced-motion: reduce){.carousel-fade .active.carousel-item-start,.carousel-fade .active.carousel-item-end{transition:none}}.carousel-control-prev,.carousel-control-next{position:absolute;top:0;bottom:0;z-index:1;display:flex;display:-webkit-flex;align-items:center;-webkit-align-items:center;justify-content:center;-webkit-justify-content:center;width:15%;padding:0;color:#fff;text-align:center;background:none;border:0;opacity:.5;transition:opacity .15s ease}@media(prefers-reduced-motion: reduce){.carousel-control-prev,.carousel-control-next{transition:none}}.carousel-control-prev:hover,.carousel-control-prev:focus,.carousel-control-next:hover,.carousel-control-next:focus{color:#fff;text-decoration:none;outline:0;opacity:.9}.carousel-control-prev{left:0}.carousel-control-next{right:0}.carousel-control-prev-icon,.carousel-control-next-icon{display:inline-block;width:2rem;height:2rem;background-repeat:no-repeat;background-position:50%;background-size:100% 100%}.carousel-control-prev-icon{background-image:url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='%23fff'%3e%3cpath d='M11.354 1.646a.5.5 0 0 1 0 .708L5.707 8l5.647 5.646a.5.5 0 0 1-.708.708l-6-6a.5.5 0 0 1 0-.708l6-6a.5.5 0 0 1 .708 0z'/%3e%3c/svg%3e")}.carousel-control-next-icon{background-image:url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='%23fff'%3e%3cpath d='M4.646 1.646a.5.5 0 0 1 .708 0l6 6a.5.5 0 0 1 0 .708l-6 6a.5.5 0 0 1-.708-.708L10.293 8 4.646 2.354a.5.5 0 0 1 0-.708z'/%3e%3c/svg%3e")}.carousel-indicators{position:absolute;right:0;bottom:0;left:0;z-index:2;display:flex;display:-webkit-flex;justify-content:center;-webkit-justify-content:center;padding:0;margin-right:15%;margin-bottom:1rem;margin-left:15%}.carousel-indicators [data-bs-target]{box-sizing:content-box;flex:0 1 auto;-webkit-flex:0 1 auto;width:30px;height:3px;padding:0;margin-right:3px;margin-left:3px;text-indent:-999px;cursor:pointer;background-color:#fff;background-clip:padding-box;border:0;border-top:10px solid rgba(0,0,0,0);border-bottom:10px solid rgba(0,0,0,0);opacity:.5;transition:opacity .6s ease}@media(prefers-reduced-motion: reduce){.carousel-indicators [data-bs-target]{transition:none}}.carousel-indicators .active{opacity:1}.carousel-caption{position:absolute;right:15%;bottom:1.25rem;left:15%;padding-top:1.25rem;padding-bottom:1.25rem;color:#fff;text-align:center}.carousel-dark .carousel-control-prev-icon,.carousel-dark .carousel-control-next-icon{filter:invert(1) grayscale(100)}.carousel-dark .carousel-indicators [data-bs-target]{background-color:#000}.carousel-dark .carousel-caption{color:#000}[data-bs-theme=dark] .carousel .carousel-control-prev-icon,[data-bs-theme=dark] .carousel .carousel-control-next-icon,[data-bs-theme=dark].carousel .carousel-control-prev-icon,[data-bs-theme=dark].carousel .carousel-control-next-icon{filter:invert(1) grayscale(100)}[data-bs-theme=dark] .carousel .carousel-indicators [data-bs-target],[data-bs-theme=dark].carousel .carousel-indicators [data-bs-target]{background-color:#000}[data-bs-theme=dark] .carousel .carousel-caption,[data-bs-theme=dark].carousel .carousel-caption{color:#000}.spinner-grow,.spinner-border{display:inline-block;width:var(--bs-spinner-width);height:var(--bs-spinner-height);vertical-align:var(--bs-spinner-vertical-align);border-radius:50%;animation:var(--bs-spinner-animation-speed) linear infinite var(--bs-spinner-animation-name)}@keyframes spinner-border{to{transform:rotate(360deg) /* rtl:ignore */}}.spinner-border{--bs-spinner-width: 2rem;--bs-spinner-height: 2rem;--bs-spinner-vertical-align: -0.125em;--bs-spinner-border-width: 0.25em;--bs-spinner-animation-speed: 0.75s;--bs-spinner-animation-name: spinner-border;border:var(--bs-spinner-border-width) solid currentcolor;border-right-color:rgba(0,0,0,0)}.spinner-border-sm{--bs-spinner-width: 1rem;--bs-spinner-height: 1rem;--bs-spinner-border-width: 0.2em}@keyframes spinner-grow{0%{transform:scale(0)}50%{opacity:1;transform:none}}.spinner-grow{--bs-spinner-width: 2rem;--bs-spinner-height: 2rem;--bs-spinner-vertical-align: -0.125em;--bs-spinner-animation-speed: 0.75s;--bs-spinner-animation-name: spinner-grow;background-color:currentcolor;opacity:0}.spinner-grow-sm{--bs-spinner-width: 1rem;--bs-spinner-height: 1rem}@media(prefers-reduced-motion: reduce){.spinner-border,.spinner-grow{--bs-spinner-animation-speed: 1.5s}}.offcanvas,.offcanvas-xxl,.offcanvas-xl,.offcanvas-lg,.offcanvas-md,.offcanvas-sm{--bs-offcanvas-zindex: 1045;--bs-offcanvas-width: 400px;--bs-offcanvas-height: 30vh;--bs-offcanvas-padding-x: 1rem;--bs-offcanvas-padding-y: 1rem;--bs-offcanvas-color: #fff;--bs-offcanvas-bg: #222;--bs-offcanvas-border-width: 1px;--bs-offcanvas-border-color: #434343;--bs-offcanvas-box-shadow: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.075);--bs-offcanvas-transition: transform 0.3s ease-in-out;--bs-offcanvas-title-line-height: 1.5}@media(max-width: 575.98px){.offcanvas-sm{position:fixed;bottom:0;z-index:var(--bs-offcanvas-zindex);display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;max-width:100%;color:var(--bs-offcanvas-color);visibility:hidden;background-color:var(--bs-offcanvas-bg);background-clip:padding-box;outline:0;transition:var(--bs-offcanvas-transition)}}@media(max-width: 575.98px)and (prefers-reduced-motion: reduce){.offcanvas-sm{transition:none}}@media(max-width: 575.98px){.offcanvas-sm.offcanvas-start{top:0;left:0;width:var(--bs-offcanvas-width);border-right:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(-100%)}.offcanvas-sm.offcanvas-end{top:0;right:0;width:var(--bs-offcanvas-width);border-left:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(100%)}.offcanvas-sm.offcanvas-top{top:0;right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-bottom:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(-100%)}.offcanvas-sm.offcanvas-bottom{right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-top:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(100%)}.offcanvas-sm.showing,.offcanvas-sm.show:not(.hiding){transform:none}.offcanvas-sm.showing,.offcanvas-sm.hiding,.offcanvas-sm.show{visibility:visible}}@media(min-width: 576px){.offcanvas-sm{--bs-offcanvas-height: auto;--bs-offcanvas-border-width: 0;background-color:rgba(0,0,0,0) !important}.offcanvas-sm .offcanvas-header{display:none}.offcanvas-sm .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible;background-color:rgba(0,0,0,0) !important}}@media(max-width: 767.98px){.offcanvas-md{position:fixed;bottom:0;z-index:var(--bs-offcanvas-zindex);display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;max-width:100%;color:var(--bs-offcanvas-color);visibility:hidden;background-color:var(--bs-offcanvas-bg);background-clip:padding-box;outline:0;transition:var(--bs-offcanvas-transition)}}@media(max-width: 767.98px)and (prefers-reduced-motion: reduce){.offcanvas-md{transition:none}}@media(max-width: 767.98px){.offcanvas-md.offcanvas-start{top:0;left:0;width:var(--bs-offcanvas-width);border-right:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(-100%)}.offcanvas-md.offcanvas-end{top:0;right:0;width:var(--bs-offcanvas-width);border-left:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(100%)}.offcanvas-md.offcanvas-top{top:0;right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-bottom:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(-100%)}.offcanvas-md.offcanvas-bottom{right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-top:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(100%)}.offcanvas-md.showing,.offcanvas-md.show:not(.hiding){transform:none}.offcanvas-md.showing,.offcanvas-md.hiding,.offcanvas-md.show{visibility:visible}}@media(min-width: 768px){.offcanvas-md{--bs-offcanvas-height: auto;--bs-offcanvas-border-width: 0;background-color:rgba(0,0,0,0) !important}.offcanvas-md .offcanvas-header{display:none}.offcanvas-md .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible;background-color:rgba(0,0,0,0) !important}}@media(max-width: 991.98px){.offcanvas-lg{position:fixed;bottom:0;z-index:var(--bs-offcanvas-zindex);display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;max-width:100%;color:var(--bs-offcanvas-color);visibility:hidden;background-color:var(--bs-offcanvas-bg);background-clip:padding-box;outline:0;transition:var(--bs-offcanvas-transition)}}@media(max-width: 991.98px)and (prefers-reduced-motion: reduce){.offcanvas-lg{transition:none}}@media(max-width: 991.98px){.offcanvas-lg.offcanvas-start{top:0;left:0;width:var(--bs-offcanvas-width);border-right:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(-100%)}.offcanvas-lg.offcanvas-end{top:0;right:0;width:var(--bs-offcanvas-width);border-left:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(100%)}.offcanvas-lg.offcanvas-top{top:0;right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-bottom:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(-100%)}.offcanvas-lg.offcanvas-bottom{right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-top:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(100%)}.offcanvas-lg.showing,.offcanvas-lg.show:not(.hiding){transform:none}.offcanvas-lg.showing,.offcanvas-lg.hiding,.offcanvas-lg.show{visibility:visible}}@media(min-width: 992px){.offcanvas-lg{--bs-offcanvas-height: auto;--bs-offcanvas-border-width: 0;background-color:rgba(0,0,0,0) !important}.offcanvas-lg .offcanvas-header{display:none}.offcanvas-lg .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible;background-color:rgba(0,0,0,0) !important}}@media(max-width: 1199.98px){.offcanvas-xl{position:fixed;bottom:0;z-index:var(--bs-offcanvas-zindex);display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;max-width:100%;color:var(--bs-offcanvas-color);visibility:hidden;background-color:var(--bs-offcanvas-bg);background-clip:padding-box;outline:0;transition:var(--bs-offcanvas-transition)}}@media(max-width: 1199.98px)and (prefers-reduced-motion: reduce){.offcanvas-xl{transition:none}}@media(max-width: 1199.98px){.offcanvas-xl.offcanvas-start{top:0;left:0;width:var(--bs-offcanvas-width);border-right:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(-100%)}.offcanvas-xl.offcanvas-end{top:0;right:0;width:var(--bs-offcanvas-width);border-left:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(100%)}.offcanvas-xl.offcanvas-top{top:0;right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-bottom:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(-100%)}.offcanvas-xl.offcanvas-bottom{right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-top:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(100%)}.offcanvas-xl.showing,.offcanvas-xl.show:not(.hiding){transform:none}.offcanvas-xl.showing,.offcanvas-xl.hiding,.offcanvas-xl.show{visibility:visible}}@media(min-width: 1200px){.offcanvas-xl{--bs-offcanvas-height: auto;--bs-offcanvas-border-width: 0;background-color:rgba(0,0,0,0) !important}.offcanvas-xl .offcanvas-header{display:none}.offcanvas-xl .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible;background-color:rgba(0,0,0,0) !important}}@media(max-width: 1399.98px){.offcanvas-xxl{position:fixed;bottom:0;z-index:var(--bs-offcanvas-zindex);display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;max-width:100%;color:var(--bs-offcanvas-color);visibility:hidden;background-color:var(--bs-offcanvas-bg);background-clip:padding-box;outline:0;transition:var(--bs-offcanvas-transition)}}@media(max-width: 1399.98px)and (prefers-reduced-motion: reduce){.offcanvas-xxl{transition:none}}@media(max-width: 1399.98px){.offcanvas-xxl.offcanvas-start{top:0;left:0;width:var(--bs-offcanvas-width);border-right:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(-100%)}.offcanvas-xxl.offcanvas-end{top:0;right:0;width:var(--bs-offcanvas-width);border-left:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(100%)}.offcanvas-xxl.offcanvas-top{top:0;right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-bottom:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(-100%)}.offcanvas-xxl.offcanvas-bottom{right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-top:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(100%)}.offcanvas-xxl.showing,.offcanvas-xxl.show:not(.hiding){transform:none}.offcanvas-xxl.showing,.offcanvas-xxl.hiding,.offcanvas-xxl.show{visibility:visible}}@media(min-width: 1400px){.offcanvas-xxl{--bs-offcanvas-height: auto;--bs-offcanvas-border-width: 0;background-color:rgba(0,0,0,0) !important}.offcanvas-xxl .offcanvas-header{display:none}.offcanvas-xxl .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible;background-color:rgba(0,0,0,0) !important}}.offcanvas{position:fixed;bottom:0;z-index:var(--bs-offcanvas-zindex);display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;max-width:100%;color:var(--bs-offcanvas-color);visibility:hidden;background-color:var(--bs-offcanvas-bg);background-clip:padding-box;outline:0;transition:var(--bs-offcanvas-transition)}@media(prefers-reduced-motion: reduce){.offcanvas{transition:none}}.offcanvas.offcanvas-start{top:0;left:0;width:var(--bs-offcanvas-width);border-right:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(-100%)}.offcanvas.offcanvas-end{top:0;right:0;width:var(--bs-offcanvas-width);border-left:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(100%)}.offcanvas.offcanvas-top{top:0;right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-bottom:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(-100%)}.offcanvas.offcanvas-bottom{right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-top:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(100%)}.offcanvas.showing,.offcanvas.show:not(.hiding){transform:none}.offcanvas.showing,.offcanvas.hiding,.offcanvas.show{visibility:visible}.offcanvas-backdrop{position:fixed;top:0;left:0;z-index:1040;width:100vw;height:100vh;background-color:#000}.offcanvas-backdrop.fade{opacity:0}.offcanvas-backdrop.show{opacity:.5}.offcanvas-header{display:flex;display:-webkit-flex;align-items:center;-webkit-align-items:center;justify-content:space-between;-webkit-justify-content:space-between;padding:var(--bs-offcanvas-padding-y) var(--bs-offcanvas-padding-x)}.offcanvas-header .btn-close{padding:calc(var(--bs-offcanvas-padding-y)*.5) calc(var(--bs-offcanvas-padding-x)*.5);margin-top:calc(-0.5*var(--bs-offcanvas-padding-y));margin-right:calc(-0.5*var(--bs-offcanvas-padding-x));margin-bottom:calc(-0.5*var(--bs-offcanvas-padding-y))}.offcanvas-title{margin-bottom:0;line-height:var(--bs-offcanvas-title-line-height)}.offcanvas-body{flex-grow:1;-webkit-flex-grow:1;padding:var(--bs-offcanvas-padding-y) var(--bs-offcanvas-padding-x);overflow-y:auto}.placeholder{display:inline-block;min-height:1em;vertical-align:middle;cursor:wait;background-color:currentcolor;opacity:.5}.placeholder.btn::before{display:inline-block;content:""}.placeholder-xs{min-height:.6em}.placeholder-sm{min-height:.8em}.placeholder-lg{min-height:1.2em}.placeholder-glow .placeholder{animation:placeholder-glow 2s ease-in-out infinite}@keyframes placeholder-glow{50%{opacity:.2}}.placeholder-wave{mask-image:linear-gradient(130deg, #000 55%, rgba(0, 0, 0, 0.8) 75%, #000 95%);-webkit-mask-image:linear-gradient(130deg, #000 55%, rgba(0, 0, 0, 0.8) 75%, #000 95%);mask-size:200% 100%;-webkit-mask-size:200% 100%;animation:placeholder-wave 2s linear infinite}@keyframes placeholder-wave{100%{mask-position:-200% 0%;-webkit-mask-position:-200% 0%}}.clearfix::after{display:block;clear:both;content:""}.text-bg-default{color:#fff !important;background-color:RGBA(var(--bs-default-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-primary{color:#fff !important;background-color:RGBA(var(--bs-primary-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-secondary{color:#fff !important;background-color:RGBA(var(--bs-secondary-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-success{color:#fff !important;background-color:RGBA(var(--bs-success-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-info{color:#fff !important;background-color:RGBA(var(--bs-info-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-warning{color:#fff !important;background-color:RGBA(var(--bs-warning-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-danger{color:#fff !important;background-color:RGBA(var(--bs-danger-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-light{color:#fff !important;background-color:RGBA(var(--bs-light-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-dark{color:#fff !important;background-color:RGBA(var(--bs-dark-rgb), var(--bs-bg-opacity, 1)) !important}.link-default{color:RGBA(var(--bs-default-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-default-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-default:hover,.link-default:focus{color:RGBA(54, 54, 54, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(54, 54, 54, var(--bs-link-underline-opacity, 1)) !important}.link-primary{color:RGBA(var(--bs-primary-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-primary-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-primary:hover,.link-primary:focus{color:RGBA(44, 72, 102, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(44, 72, 102, var(--bs-link-underline-opacity, 1)) !important}.link-secondary{color:RGBA(var(--bs-secondary-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-secondary-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-secondary:hover,.link-secondary:focus{color:RGBA(54, 54, 54, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(54, 54, 54, var(--bs-link-underline-opacity, 1)) !important}.link-success{color:RGBA(var(--bs-success-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-success-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-success:hover,.link-success:focus{color:RGBA(0, 150, 112, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(0, 150, 112, var(--bs-link-underline-opacity, 1)) !important}.link-info{color:RGBA(var(--bs-info-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-info-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-info:hover,.link-info:focus{color:RGBA(42, 122, 175, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(42, 122, 175, var(--bs-link-underline-opacity, 1)) !important}.link-warning{color:RGBA(var(--bs-warning-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-warning-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-warning:hover,.link-warning:focus{color:RGBA(194, 125, 14, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(194, 125, 14, var(--bs-link-underline-opacity, 1)) !important}.link-danger{color:RGBA(var(--bs-danger-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-danger-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-danger:hover,.link-danger:focus{color:RGBA(185, 61, 48, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(185, 61, 48, var(--bs-link-underline-opacity, 1)) !important}.link-light{color:RGBA(var(--bs-light-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-light-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-light:hover,.link-light:focus{color:RGBA(89, 89, 89, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(89, 89, 89, var(--bs-link-underline-opacity, 1)) !important}.link-dark{color:RGBA(var(--bs-dark-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-dark-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-dark:hover,.link-dark:focus{color:RGBA(36, 36, 36, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(36, 36, 36, var(--bs-link-underline-opacity, 1)) !important}.link-body-emphasis{color:RGBA(var(--bs-emphasis-color-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-emphasis-color-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-body-emphasis:hover,.link-body-emphasis:focus{color:RGBA(var(--bs-emphasis-color-rgb), var(--bs-link-opacity, 0.75)) !important;text-decoration-color:RGBA(var(--bs-emphasis-color-rgb), var(--bs-link-underline-opacity, 0.75)) !important}.focus-ring:focus{outline:0;box-shadow:var(--bs-focus-ring-x, 0) var(--bs-focus-ring-y, 0) var(--bs-focus-ring-blur, 0) var(--bs-focus-ring-width) var(--bs-focus-ring-color)}.icon-link{display:inline-flex;gap:.375rem;align-items:center;-webkit-align-items:center;text-decoration-color:rgba(var(--bs-link-color-rgb), var(--bs-link-opacity, 0.5));text-underline-offset:.25em;backface-visibility:hidden;-webkit-backface-visibility:hidden;-moz-backface-visibility:hidden;-ms-backface-visibility:hidden;-o-backface-visibility:hidden}.icon-link>.bi{flex-shrink:0;-webkit-flex-shrink:0;width:1em;height:1em;fill:currentcolor;transition:.2s ease-in-out transform}@media(prefers-reduced-motion: reduce){.icon-link>.bi{transition:none}}.icon-link-hover:hover>.bi,.icon-link-hover:focus-visible>.bi{transform:var(--bs-icon-link-transform, translate3d(0.25em, 0, 0))}.ratio{position:relative;width:100%}.ratio::before{display:block;padding-top:var(--bs-aspect-ratio);content:""}.ratio>*{position:absolute;top:0;left:0;width:100%;height:100%}.ratio-1x1{--bs-aspect-ratio: 100%}.ratio-4x3{--bs-aspect-ratio: 75%}.ratio-16x9{--bs-aspect-ratio: 56.25%}.ratio-21x9{--bs-aspect-ratio: 42.8571428571%}.fixed-top{position:fixed;top:0;right:0;left:0;z-index:1030}.fixed-bottom{position:fixed;right:0;bottom:0;left:0;z-index:1030}.sticky-top{position:sticky;top:0;z-index:1020}.sticky-bottom{position:sticky;bottom:0;z-index:1020}@media(min-width: 576px){.sticky-sm-top{position:sticky;top:0;z-index:1020}.sticky-sm-bottom{position:sticky;bottom:0;z-index:1020}}@media(min-width: 768px){.sticky-md-top{position:sticky;top:0;z-index:1020}.sticky-md-bottom{position:sticky;bottom:0;z-index:1020}}@media(min-width: 992px){.sticky-lg-top{position:sticky;top:0;z-index:1020}.sticky-lg-bottom{position:sticky;bottom:0;z-index:1020}}@media(min-width: 1200px){.sticky-xl-top{position:sticky;top:0;z-index:1020}.sticky-xl-bottom{position:sticky;bottom:0;z-index:1020}}@media(min-width: 1400px){.sticky-xxl-top{position:sticky;top:0;z-index:1020}.sticky-xxl-bottom{position:sticky;bottom:0;z-index:1020}}.hstack{display:flex;display:-webkit-flex;flex-direction:row;-webkit-flex-direction:row;align-items:center;-webkit-align-items:center;align-self:stretch;-webkit-align-self:stretch}.vstack{display:flex;display:-webkit-flex;flex:1 1 auto;-webkit-flex:1 1 auto;flex-direction:column;-webkit-flex-direction:column;align-self:stretch;-webkit-align-self:stretch}.visually-hidden,.visually-hidden-focusable:not(:focus):not(:focus-within){width:1px !important;height:1px !important;padding:0 !important;margin:-1px !important;overflow:hidden !important;clip:rect(0, 0, 0, 0) !important;white-space:nowrap !important;border:0 !important}.visually-hidden:not(caption),.visually-hidden-focusable:not(:focus):not(:focus-within):not(caption){position:absolute !important}.stretched-link::after{position:absolute;top:0;right:0;bottom:0;left:0;z-index:1;content:""}.text-truncate{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.vr{display:inline-block;align-self:stretch;-webkit-align-self:stretch;width:1px;min-height:1em;background-color:currentcolor;opacity:.25}.align-baseline{vertical-align:baseline !important}.align-top{vertical-align:top !important}.align-middle{vertical-align:middle !important}.align-bottom{vertical-align:bottom !important}.align-text-bottom{vertical-align:text-bottom !important}.align-text-top{vertical-align:text-top !important}.float-start{float:left !important}.float-end{float:right !important}.float-none{float:none !important}.object-fit-contain{object-fit:contain !important}.object-fit-cover{object-fit:cover !important}.object-fit-fill{object-fit:fill !important}.object-fit-scale{object-fit:scale-down !important}.object-fit-none{object-fit:none !important}.opacity-0{opacity:0 !important}.opacity-25{opacity:.25 !important}.opacity-50{opacity:.5 !important}.opacity-75{opacity:.75 !important}.opacity-100{opacity:1 !important}.overflow-auto{overflow:auto !important}.overflow-hidden{overflow:hidden !important}.overflow-visible{overflow:visible !important}.overflow-scroll{overflow:scroll !important}.overflow-x-auto{overflow-x:auto !important}.overflow-x-hidden{overflow-x:hidden !important}.overflow-x-visible{overflow-x:visible !important}.overflow-x-scroll{overflow-x:scroll !important}.overflow-y-auto{overflow-y:auto !important}.overflow-y-hidden{overflow-y:hidden !important}.overflow-y-visible{overflow-y:visible !important}.overflow-y-scroll{overflow-y:scroll !important}.d-inline{display:inline !important}.d-inline-block{display:inline-block !important}.d-block{display:block !important}.d-grid{display:grid !important}.d-inline-grid{display:inline-grid !important}.d-table{display:table !important}.d-table-row{display:table-row !important}.d-table-cell{display:table-cell !important}.d-flex{display:flex !important}.d-inline-flex{display:inline-flex !important}.d-none{display:none !important}.shadow{box-shadow:0 .5rem 1rem rgba(0,0,0,.15) !important}.shadow-sm{box-shadow:0 .125rem .25rem rgba(0,0,0,.075) !important}.shadow-lg{box-shadow:0 1rem 3rem rgba(0,0,0,.175) !important}.shadow-none{box-shadow:none !important}.focus-ring-default{--bs-focus-ring-color: rgba(var(--bs-default-rgb), var(--bs-focus-ring-opacity))}.focus-ring-primary{--bs-focus-ring-color: rgba(var(--bs-primary-rgb), var(--bs-focus-ring-opacity))}.focus-ring-secondary{--bs-focus-ring-color: rgba(var(--bs-secondary-rgb), var(--bs-focus-ring-opacity))}.focus-ring-success{--bs-focus-ring-color: rgba(var(--bs-success-rgb), var(--bs-focus-ring-opacity))}.focus-ring-info{--bs-focus-ring-color: rgba(var(--bs-info-rgb), var(--bs-focus-ring-opacity))}.focus-ring-warning{--bs-focus-ring-color: rgba(var(--bs-warning-rgb), var(--bs-focus-ring-opacity))}.focus-ring-danger{--bs-focus-ring-color: rgba(var(--bs-danger-rgb), var(--bs-focus-ring-opacity))}.focus-ring-light{--bs-focus-ring-color: rgba(var(--bs-light-rgb), var(--bs-focus-ring-opacity))}.focus-ring-dark{--bs-focus-ring-color: rgba(var(--bs-dark-rgb), var(--bs-focus-ring-opacity))}.position-static{position:static !important}.position-relative{position:relative !important}.position-absolute{position:absolute !important}.position-fixed{position:fixed !important}.position-sticky{position:sticky !important}.top-0{top:0 !important}.top-50{top:50% !important}.top-100{top:100% !important}.bottom-0{bottom:0 !important}.bottom-50{bottom:50% !important}.bottom-100{bottom:100% !important}.start-0{left:0 !important}.start-50{left:50% !important}.start-100{left:100% !important}.end-0{right:0 !important}.end-50{right:50% !important}.end-100{right:100% !important}.translate-middle{transform:translate(-50%, -50%) !important}.translate-middle-x{transform:translateX(-50%) !important}.translate-middle-y{transform:translateY(-50%) !important}.border{border:var(--bs-border-width) var(--bs-border-style) var(--bs-border-color) !important}.border-0{border:0 !important}.border-top{border-top:var(--bs-border-width) var(--bs-border-style) var(--bs-border-color) !important}.border-top-0{border-top:0 !important}.border-end{border-right:var(--bs-border-width) var(--bs-border-style) var(--bs-border-color) !important}.border-end-0{border-right:0 !important}.border-bottom{border-bottom:var(--bs-border-width) var(--bs-border-style) var(--bs-border-color) !important}.border-bottom-0{border-bottom:0 !important}.border-start{border-left:var(--bs-border-width) var(--bs-border-style) var(--bs-border-color) !important}.border-start-0{border-left:0 !important}.border-default{--bs-border-opacity: 1;border-color:rgba(var(--bs-default-rgb), var(--bs-border-opacity)) !important}.border-primary{--bs-border-opacity: 1;border-color:rgba(var(--bs-primary-rgb), var(--bs-border-opacity)) !important}.border-secondary{--bs-border-opacity: 1;border-color:rgba(var(--bs-secondary-rgb), var(--bs-border-opacity)) !important}.border-success{--bs-border-opacity: 1;border-color:rgba(var(--bs-success-rgb), var(--bs-border-opacity)) !important}.border-info{--bs-border-opacity: 1;border-color:rgba(var(--bs-info-rgb), var(--bs-border-opacity)) !important}.border-warning{--bs-border-opacity: 1;border-color:rgba(var(--bs-warning-rgb), var(--bs-border-opacity)) !important}.border-danger{--bs-border-opacity: 1;border-color:rgba(var(--bs-danger-rgb), var(--bs-border-opacity)) !important}.border-light{--bs-border-opacity: 1;border-color:rgba(var(--bs-light-rgb), var(--bs-border-opacity)) !important}.border-dark{--bs-border-opacity: 1;border-color:rgba(var(--bs-dark-rgb), var(--bs-border-opacity)) !important}.border-black{--bs-border-opacity: 1;border-color:rgba(var(--bs-black-rgb), var(--bs-border-opacity)) !important}.border-white{--bs-border-opacity: 1;border-color:rgba(var(--bs-white-rgb), var(--bs-border-opacity)) !important}.border-primary-subtle{border-color:var(--bs-primary-border-subtle) !important}.border-secondary-subtle{border-color:var(--bs-secondary-border-subtle) !important}.border-success-subtle{border-color:var(--bs-success-border-subtle) !important}.border-info-subtle{border-color:var(--bs-info-border-subtle) !important}.border-warning-subtle{border-color:var(--bs-warning-border-subtle) !important}.border-danger-subtle{border-color:var(--bs-danger-border-subtle) !important}.border-light-subtle{border-color:var(--bs-light-border-subtle) !important}.border-dark-subtle{border-color:var(--bs-dark-border-subtle) !important}.border-1{border-width:1px !important}.border-2{border-width:2px !important}.border-3{border-width:3px !important}.border-4{border-width:4px !important}.border-5{border-width:5px !important}.border-opacity-10{--bs-border-opacity: 0.1}.border-opacity-25{--bs-border-opacity: 0.25}.border-opacity-50{--bs-border-opacity: 0.5}.border-opacity-75{--bs-border-opacity: 0.75}.border-opacity-100{--bs-border-opacity: 1}.w-25{width:25% !important}.w-50{width:50% !important}.w-75{width:75% !important}.w-100{width:100% !important}.w-auto{width:auto !important}.mw-100{max-width:100% !important}.vw-100{width:100vw !important}.min-vw-100{min-width:100vw !important}.h-25{height:25% !important}.h-50{height:50% !important}.h-75{height:75% !important}.h-100{height:100% !important}.h-auto{height:auto !important}.mh-100{max-height:100% !important}.vh-100{height:100vh !important}.min-vh-100{min-height:100vh !important}.flex-fill{flex:1 1 auto !important}.flex-row{flex-direction:row !important}.flex-column{flex-direction:column !important}.flex-row-reverse{flex-direction:row-reverse !important}.flex-column-reverse{flex-direction:column-reverse !important}.flex-grow-0{flex-grow:0 !important}.flex-grow-1{flex-grow:1 !important}.flex-shrink-0{flex-shrink:0 !important}.flex-shrink-1{flex-shrink:1 !important}.flex-wrap{flex-wrap:wrap !important}.flex-nowrap{flex-wrap:nowrap !important}.flex-wrap-reverse{flex-wrap:wrap-reverse !important}.justify-content-start{justify-content:flex-start !important}.justify-content-end{justify-content:flex-end !important}.justify-content-center{justify-content:center !important}.justify-content-between{justify-content:space-between !important}.justify-content-around{justify-content:space-around !important}.justify-content-evenly{justify-content:space-evenly !important}.align-items-start{align-items:flex-start !important}.align-items-end{align-items:flex-end !important}.align-items-center{align-items:center !important}.align-items-baseline{align-items:baseline !important}.align-items-stretch{align-items:stretch !important}.align-content-start{align-content:flex-start !important}.align-content-end{align-content:flex-end !important}.align-content-center{align-content:center !important}.align-content-between{align-content:space-between !important}.align-content-around{align-content:space-around !important}.align-content-stretch{align-content:stretch !important}.align-self-auto{align-self:auto !important}.align-self-start{align-self:flex-start !important}.align-self-end{align-self:flex-end !important}.align-self-center{align-self:center !important}.align-self-baseline{align-self:baseline !important}.align-self-stretch{align-self:stretch !important}.order-first{order:-1 !important}.order-0{order:0 !important}.order-1{order:1 !important}.order-2{order:2 !important}.order-3{order:3 !important}.order-4{order:4 !important}.order-5{order:5 !important}.order-last{order:6 !important}.m-0{margin:0 !important}.m-1{margin:.25rem !important}.m-2{margin:.5rem !important}.m-3{margin:1rem !important}.m-4{margin:1.5rem !important}.m-5{margin:3rem !important}.m-auto{margin:auto !important}.mx-0{margin-right:0 !important;margin-left:0 !important}.mx-1{margin-right:.25rem !important;margin-left:.25rem !important}.mx-2{margin-right:.5rem !important;margin-left:.5rem !important}.mx-3{margin-right:1rem !important;margin-left:1rem !important}.mx-4{margin-right:1.5rem !important;margin-left:1.5rem !important}.mx-5{margin-right:3rem !important;margin-left:3rem !important}.mx-auto{margin-right:auto !important;margin-left:auto !important}.my-0{margin-top:0 !important;margin-bottom:0 !important}.my-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.my-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.my-3{margin-top:1rem !important;margin-bottom:1rem !important}.my-4{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.my-5{margin-top:3rem !important;margin-bottom:3rem !important}.my-auto{margin-top:auto !important;margin-bottom:auto !important}.mt-0{margin-top:0 !important}.mt-1{margin-top:.25rem !important}.mt-2{margin-top:.5rem !important}.mt-3{margin-top:1rem !important}.mt-4{margin-top:1.5rem !important}.mt-5{margin-top:3rem !important}.mt-auto{margin-top:auto !important}.me-0{margin-right:0 !important}.me-1{margin-right:.25rem !important}.me-2{margin-right:.5rem !important}.me-3{margin-right:1rem !important}.me-4{margin-right:1.5rem !important}.me-5{margin-right:3rem !important}.me-auto{margin-right:auto !important}.mb-0{margin-bottom:0 !important}.mb-1{margin-bottom:.25rem !important}.mb-2{margin-bottom:.5rem !important}.mb-3{margin-bottom:1rem !important}.mb-4{margin-bottom:1.5rem !important}.mb-5{margin-bottom:3rem !important}.mb-auto{margin-bottom:auto !important}.ms-0{margin-left:0 !important}.ms-1{margin-left:.25rem !important}.ms-2{margin-left:.5rem !important}.ms-3{margin-left:1rem !important}.ms-4{margin-left:1.5rem !important}.ms-5{margin-left:3rem !important}.ms-auto{margin-left:auto !important}.p-0{padding:0 !important}.p-1{padding:.25rem !important}.p-2{padding:.5rem !important}.p-3{padding:1rem !important}.p-4{padding:1.5rem !important}.p-5{padding:3rem !important}.px-0{padding-right:0 !important;padding-left:0 !important}.px-1{padding-right:.25rem !important;padding-left:.25rem !important}.px-2{padding-right:.5rem !important;padding-left:.5rem !important}.px-3{padding-right:1rem !important;padding-left:1rem !important}.px-4{padding-right:1.5rem !important;padding-left:1.5rem !important}.px-5{padding-right:3rem !important;padding-left:3rem !important}.py-0{padding-top:0 !important;padding-bottom:0 !important}.py-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.py-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.py-3{padding-top:1rem !important;padding-bottom:1rem !important}.py-4{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.py-5{padding-top:3rem !important;padding-bottom:3rem !important}.pt-0{padding-top:0 !important}.pt-1{padding-top:.25rem !important}.pt-2{padding-top:.5rem !important}.pt-3{padding-top:1rem !important}.pt-4{padding-top:1.5rem !important}.pt-5{padding-top:3rem !important}.pe-0{padding-right:0 !important}.pe-1{padding-right:.25rem !important}.pe-2{padding-right:.5rem !important}.pe-3{padding-right:1rem !important}.pe-4{padding-right:1.5rem !important}.pe-5{padding-right:3rem !important}.pb-0{padding-bottom:0 !important}.pb-1{padding-bottom:.25rem !important}.pb-2{padding-bottom:.5rem !important}.pb-3{padding-bottom:1rem !important}.pb-4{padding-bottom:1.5rem !important}.pb-5{padding-bottom:3rem !important}.ps-0{padding-left:0 !important}.ps-1{padding-left:.25rem !important}.ps-2{padding-left:.5rem !important}.ps-3{padding-left:1rem !important}.ps-4{padding-left:1.5rem !important}.ps-5{padding-left:3rem !important}.gap-0{gap:0 !important}.gap-1{gap:.25rem !important}.gap-2{gap:.5rem !important}.gap-3{gap:1rem !important}.gap-4{gap:1.5rem !important}.gap-5{gap:3rem !important}.row-gap-0{row-gap:0 !important}.row-gap-1{row-gap:.25rem !important}.row-gap-2{row-gap:.5rem !important}.row-gap-3{row-gap:1rem !important}.row-gap-4{row-gap:1.5rem !important}.row-gap-5{row-gap:3rem !important}.column-gap-0{column-gap:0 !important}.column-gap-1{column-gap:.25rem !important}.column-gap-2{column-gap:.5rem !important}.column-gap-3{column-gap:1rem !important}.column-gap-4{column-gap:1.5rem !important}.column-gap-5{column-gap:3rem !important}.font-monospace{font-family:var(--bs-font-monospace) !important}.fs-1{font-size:calc(1.325rem + 0.9vw) !important}.fs-2{font-size:calc(1.29rem + 0.48vw) !important}.fs-3{font-size:calc(1.27rem + 0.24vw) !important}.fs-4{font-size:1.25rem !important}.fs-5{font-size:1.1rem !important}.fs-6{font-size:1rem !important}.fst-italic{font-style:italic !important}.fst-normal{font-style:normal !important}.fw-lighter{font-weight:lighter !important}.fw-light{font-weight:300 !important}.fw-normal{font-weight:400 !important}.fw-medium{font-weight:500 !important}.fw-semibold{font-weight:600 !important}.fw-bold{font-weight:700 !important}.fw-bolder{font-weight:bolder !important}.lh-1{line-height:1 !important}.lh-sm{line-height:1.25 !important}.lh-base{line-height:1.5 !important}.lh-lg{line-height:2 !important}.text-start{text-align:left !important}.text-end{text-align:right !important}.text-center{text-align:center !important}.text-decoration-none{text-decoration:none !important}.text-decoration-underline{text-decoration:underline !important}.text-decoration-line-through{text-decoration:line-through !important}.text-lowercase{text-transform:lowercase !important}.text-uppercase{text-transform:uppercase !important}.text-capitalize{text-transform:capitalize !important}.text-wrap{white-space:normal !important}.text-nowrap{white-space:nowrap !important}.text-break{word-wrap:break-word !important;word-break:break-word !important}.text-default{--bs-text-opacity: 1;color:rgba(var(--bs-default-rgb), var(--bs-text-opacity)) !important}.text-primary{--bs-text-opacity: 1;color:rgba(var(--bs-primary-rgb), var(--bs-text-opacity)) !important}.text-secondary{--bs-text-opacity: 1;color:rgba(var(--bs-secondary-rgb), var(--bs-text-opacity)) !important}.text-success{--bs-text-opacity: 1;color:rgba(var(--bs-success-rgb), var(--bs-text-opacity)) !important}.text-info{--bs-text-opacity: 1;color:rgba(var(--bs-info-rgb), var(--bs-text-opacity)) !important}.text-warning{--bs-text-opacity: 1;color:rgba(var(--bs-warning-rgb), var(--bs-text-opacity)) !important}.text-danger{--bs-text-opacity: 1;color:rgba(var(--bs-danger-rgb), var(--bs-text-opacity)) !important}.text-light{--bs-text-opacity: 1;color:rgba(var(--bs-light-rgb), var(--bs-text-opacity)) !important}.text-dark{--bs-text-opacity: 1;color:rgba(var(--bs-dark-rgb), var(--bs-text-opacity)) !important}.text-black{--bs-text-opacity: 1;color:rgba(var(--bs-black-rgb), var(--bs-text-opacity)) !important}.text-white{--bs-text-opacity: 1;color:rgba(var(--bs-white-rgb), var(--bs-text-opacity)) !important}.text-body{--bs-text-opacity: 1;color:rgba(var(--bs-body-color-rgb), var(--bs-text-opacity)) !important}.text-muted{--bs-text-opacity: 1;color:var(--bs-secondary-color) !important}.text-black-50{--bs-text-opacity: 1;color:rgba(0,0,0,.5) !important}.text-white-50{--bs-text-opacity: 1;color:rgba(255,255,255,.5) !important}.text-body-secondary{--bs-text-opacity: 1;color:var(--bs-secondary-color) !important}.text-body-tertiary{--bs-text-opacity: 1;color:var(--bs-tertiary-color) !important}.text-body-emphasis{--bs-text-opacity: 1;color:var(--bs-emphasis-color) !important}.text-reset{--bs-text-opacity: 1;color:inherit !important}.text-opacity-25{--bs-text-opacity: 0.25}.text-opacity-50{--bs-text-opacity: 0.5}.text-opacity-75{--bs-text-opacity: 0.75}.text-opacity-100{--bs-text-opacity: 1}.text-primary-emphasis{color:var(--bs-primary-text-emphasis) !important}.text-secondary-emphasis{color:var(--bs-secondary-text-emphasis) !important}.text-success-emphasis{color:var(--bs-success-text-emphasis) !important}.text-info-emphasis{color:var(--bs-info-text-emphasis) !important}.text-warning-emphasis{color:var(--bs-warning-text-emphasis) !important}.text-danger-emphasis{color:var(--bs-danger-text-emphasis) !important}.text-light-emphasis{color:var(--bs-light-text-emphasis) !important}.text-dark-emphasis{color:var(--bs-dark-text-emphasis) !important}.link-opacity-10{--bs-link-opacity: 0.1}.link-opacity-10-hover:hover{--bs-link-opacity: 0.1}.link-opacity-25{--bs-link-opacity: 0.25}.link-opacity-25-hover:hover{--bs-link-opacity: 0.25}.link-opacity-50{--bs-link-opacity: 0.5}.link-opacity-50-hover:hover{--bs-link-opacity: 0.5}.link-opacity-75{--bs-link-opacity: 0.75}.link-opacity-75-hover:hover{--bs-link-opacity: 0.75}.link-opacity-100{--bs-link-opacity: 1}.link-opacity-100-hover:hover{--bs-link-opacity: 1}.link-offset-1{text-underline-offset:.125em !important}.link-offset-1-hover:hover{text-underline-offset:.125em !important}.link-offset-2{text-underline-offset:.25em !important}.link-offset-2-hover:hover{text-underline-offset:.25em !important}.link-offset-3{text-underline-offset:.375em !important}.link-offset-3-hover:hover{text-underline-offset:.375em !important}.link-underline-default{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-default-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-primary{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-primary-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-secondary{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-secondary-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-success{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-success-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-info{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-info-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-warning{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-warning-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-danger{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-danger-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-light{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-light-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-dark{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-dark-rgb), var(--bs-link-underline-opacity)) !important}.link-underline{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-link-color-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-underline-opacity-0{--bs-link-underline-opacity: 0}.link-underline-opacity-0-hover:hover{--bs-link-underline-opacity: 0}.link-underline-opacity-10{--bs-link-underline-opacity: 0.1}.link-underline-opacity-10-hover:hover{--bs-link-underline-opacity: 0.1}.link-underline-opacity-25{--bs-link-underline-opacity: 0.25}.link-underline-opacity-25-hover:hover{--bs-link-underline-opacity: 0.25}.link-underline-opacity-50{--bs-link-underline-opacity: 0.5}.link-underline-opacity-50-hover:hover{--bs-link-underline-opacity: 0.5}.link-underline-opacity-75{--bs-link-underline-opacity: 0.75}.link-underline-opacity-75-hover:hover{--bs-link-underline-opacity: 0.75}.link-underline-opacity-100{--bs-link-underline-opacity: 1}.link-underline-opacity-100-hover:hover{--bs-link-underline-opacity: 1}.bg-default{--bs-bg-opacity: 1;background-color:rgba(var(--bs-default-rgb), var(--bs-bg-opacity)) !important}.bg-primary{--bs-bg-opacity: 1;background-color:rgba(var(--bs-primary-rgb), var(--bs-bg-opacity)) !important}.bg-secondary{--bs-bg-opacity: 1;background-color:rgba(var(--bs-secondary-rgb), var(--bs-bg-opacity)) !important}.bg-success{--bs-bg-opacity: 1;background-color:rgba(var(--bs-success-rgb), var(--bs-bg-opacity)) !important}.bg-info{--bs-bg-opacity: 1;background-color:rgba(var(--bs-info-rgb), var(--bs-bg-opacity)) !important}.bg-warning{--bs-bg-opacity: 1;background-color:rgba(var(--bs-warning-rgb), var(--bs-bg-opacity)) !important}.bg-danger{--bs-bg-opacity: 1;background-color:rgba(var(--bs-danger-rgb), var(--bs-bg-opacity)) !important}.bg-light{--bs-bg-opacity: 1;background-color:rgba(var(--bs-light-rgb), var(--bs-bg-opacity)) !important}.bg-dark{--bs-bg-opacity: 1;background-color:rgba(var(--bs-dark-rgb), var(--bs-bg-opacity)) !important}.bg-black{--bs-bg-opacity: 1;background-color:rgba(var(--bs-black-rgb), var(--bs-bg-opacity)) !important}.bg-white{--bs-bg-opacity: 1;background-color:rgba(var(--bs-white-rgb), var(--bs-bg-opacity)) !important}.bg-body{--bs-bg-opacity: 1;background-color:rgba(var(--bs-body-bg-rgb), var(--bs-bg-opacity)) !important}.bg-transparent{--bs-bg-opacity: 1;background-color:rgba(0,0,0,0) !important}.bg-body-secondary{--bs-bg-opacity: 1;background-color:rgba(var(--bs-secondary-bg-rgb), var(--bs-bg-opacity)) !important}.bg-body-tertiary{--bs-bg-opacity: 1;background-color:rgba(var(--bs-tertiary-bg-rgb), var(--bs-bg-opacity)) !important}.bg-opacity-10{--bs-bg-opacity: 0.1}.bg-opacity-25{--bs-bg-opacity: 0.25}.bg-opacity-50{--bs-bg-opacity: 0.5}.bg-opacity-75{--bs-bg-opacity: 0.75}.bg-opacity-100{--bs-bg-opacity: 1}.bg-primary-subtle{background-color:var(--bs-primary-bg-subtle) !important}.bg-secondary-subtle{background-color:var(--bs-secondary-bg-subtle) !important}.bg-success-subtle{background-color:var(--bs-success-bg-subtle) !important}.bg-info-subtle{background-color:var(--bs-info-bg-subtle) !important}.bg-warning-subtle{background-color:var(--bs-warning-bg-subtle) !important}.bg-danger-subtle{background-color:var(--bs-danger-bg-subtle) !important}.bg-light-subtle{background-color:var(--bs-light-bg-subtle) !important}.bg-dark-subtle{background-color:var(--bs-dark-bg-subtle) !important}.bg-gradient{background-image:var(--bs-gradient) !important}.user-select-all{user-select:all !important}.user-select-auto{user-select:auto !important}.user-select-none{user-select:none !important}.pe-none{pointer-events:none !important}.pe-auto{pointer-events:auto !important}.rounded{border-radius:var(--bs-border-radius) !important}.rounded-0{border-radius:0 !important}.rounded-1{border-radius:var(--bs-border-radius-sm) !important}.rounded-2{border-radius:var(--bs-border-radius) !important}.rounded-3{border-radius:var(--bs-border-radius-lg) !important}.rounded-4{border-radius:var(--bs-border-radius-xl) !important}.rounded-5{border-radius:var(--bs-border-radius-xxl) !important}.rounded-circle{border-radius:50% !important}.rounded-pill{border-radius:var(--bs-border-radius-pill) !important}.rounded-top{border-top-left-radius:var(--bs-border-radius) !important;border-top-right-radius:var(--bs-border-radius) !important}.rounded-top-0{border-top-left-radius:0 !important;border-top-right-radius:0 !important}.rounded-top-1{border-top-left-radius:var(--bs-border-radius-sm) !important;border-top-right-radius:var(--bs-border-radius-sm) !important}.rounded-top-2{border-top-left-radius:var(--bs-border-radius) !important;border-top-right-radius:var(--bs-border-radius) !important}.rounded-top-3{border-top-left-radius:var(--bs-border-radius-lg) !important;border-top-right-radius:var(--bs-border-radius-lg) !important}.rounded-top-4{border-top-left-radius:var(--bs-border-radius-xl) !important;border-top-right-radius:var(--bs-border-radius-xl) !important}.rounded-top-5{border-top-left-radius:var(--bs-border-radius-xxl) !important;border-top-right-radius:var(--bs-border-radius-xxl) !important}.rounded-top-circle{border-top-left-radius:50% !important;border-top-right-radius:50% !important}.rounded-top-pill{border-top-left-radius:var(--bs-border-radius-pill) !important;border-top-right-radius:var(--bs-border-radius-pill) !important}.rounded-end{border-top-right-radius:var(--bs-border-radius) !important;border-bottom-right-radius:var(--bs-border-radius) !important}.rounded-end-0{border-top-right-radius:0 !important;border-bottom-right-radius:0 !important}.rounded-end-1{border-top-right-radius:var(--bs-border-radius-sm) !important;border-bottom-right-radius:var(--bs-border-radius-sm) !important}.rounded-end-2{border-top-right-radius:var(--bs-border-radius) !important;border-bottom-right-radius:var(--bs-border-radius) !important}.rounded-end-3{border-top-right-radius:var(--bs-border-radius-lg) !important;border-bottom-right-radius:var(--bs-border-radius-lg) !important}.rounded-end-4{border-top-right-radius:var(--bs-border-radius-xl) !important;border-bottom-right-radius:var(--bs-border-radius-xl) !important}.rounded-end-5{border-top-right-radius:var(--bs-border-radius-xxl) !important;border-bottom-right-radius:var(--bs-border-radius-xxl) !important}.rounded-end-circle{border-top-right-radius:50% !important;border-bottom-right-radius:50% !important}.rounded-end-pill{border-top-right-radius:var(--bs-border-radius-pill) !important;border-bottom-right-radius:var(--bs-border-radius-pill) !important}.rounded-bottom{border-bottom-right-radius:var(--bs-border-radius) !important;border-bottom-left-radius:var(--bs-border-radius) !important}.rounded-bottom-0{border-bottom-right-radius:0 !important;border-bottom-left-radius:0 !important}.rounded-bottom-1{border-bottom-right-radius:var(--bs-border-radius-sm) !important;border-bottom-left-radius:var(--bs-border-radius-sm) !important}.rounded-bottom-2{border-bottom-right-radius:var(--bs-border-radius) !important;border-bottom-left-radius:var(--bs-border-radius) !important}.rounded-bottom-3{border-bottom-right-radius:var(--bs-border-radius-lg) !important;border-bottom-left-radius:var(--bs-border-radius-lg) !important}.rounded-bottom-4{border-bottom-right-radius:var(--bs-border-radius-xl) !important;border-bottom-left-radius:var(--bs-border-radius-xl) !important}.rounded-bottom-5{border-bottom-right-radius:var(--bs-border-radius-xxl) !important;border-bottom-left-radius:var(--bs-border-radius-xxl) !important}.rounded-bottom-circle{border-bottom-right-radius:50% !important;border-bottom-left-radius:50% !important}.rounded-bottom-pill{border-bottom-right-radius:var(--bs-border-radius-pill) !important;border-bottom-left-radius:var(--bs-border-radius-pill) !important}.rounded-start{border-bottom-left-radius:var(--bs-border-radius) !important;border-top-left-radius:var(--bs-border-radius) !important}.rounded-start-0{border-bottom-left-radius:0 !important;border-top-left-radius:0 !important}.rounded-start-1{border-bottom-left-radius:var(--bs-border-radius-sm) !important;border-top-left-radius:var(--bs-border-radius-sm) !important}.rounded-start-2{border-bottom-left-radius:var(--bs-border-radius) !important;border-top-left-radius:var(--bs-border-radius) !important}.rounded-start-3{border-bottom-left-radius:var(--bs-border-radius-lg) !important;border-top-left-radius:var(--bs-border-radius-lg) !important}.rounded-start-4{border-bottom-left-radius:var(--bs-border-radius-xl) !important;border-top-left-radius:var(--bs-border-radius-xl) !important}.rounded-start-5{border-bottom-left-radius:var(--bs-border-radius-xxl) !important;border-top-left-radius:var(--bs-border-radius-xxl) !important}.rounded-start-circle{border-bottom-left-radius:50% !important;border-top-left-radius:50% !important}.rounded-start-pill{border-bottom-left-radius:var(--bs-border-radius-pill) !important;border-top-left-radius:var(--bs-border-radius-pill) !important}.visible{visibility:visible !important}.invisible{visibility:hidden !important}.z-n1{z-index:-1 !important}.z-0{z-index:0 !important}.z-1{z-index:1 !important}.z-2{z-index:2 !important}.z-3{z-index:3 !important}@media(min-width: 576px){.float-sm-start{float:left !important}.float-sm-end{float:right !important}.float-sm-none{float:none !important}.object-fit-sm-contain{object-fit:contain !important}.object-fit-sm-cover{object-fit:cover !important}.object-fit-sm-fill{object-fit:fill !important}.object-fit-sm-scale{object-fit:scale-down !important}.object-fit-sm-none{object-fit:none !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-block{display:block !important}.d-sm-grid{display:grid !important}.d-sm-inline-grid{display:inline-grid !important}.d-sm-table{display:table !important}.d-sm-table-row{display:table-row !important}.d-sm-table-cell{display:table-cell !important}.d-sm-flex{display:flex !important}.d-sm-inline-flex{display:inline-flex !important}.d-sm-none{display:none !important}.flex-sm-fill{flex:1 1 auto !important}.flex-sm-row{flex-direction:row !important}.flex-sm-column{flex-direction:column !important}.flex-sm-row-reverse{flex-direction:row-reverse !important}.flex-sm-column-reverse{flex-direction:column-reverse !important}.flex-sm-grow-0{flex-grow:0 !important}.flex-sm-grow-1{flex-grow:1 !important}.flex-sm-shrink-0{flex-shrink:0 !important}.flex-sm-shrink-1{flex-shrink:1 !important}.flex-sm-wrap{flex-wrap:wrap !important}.flex-sm-nowrap{flex-wrap:nowrap !important}.flex-sm-wrap-reverse{flex-wrap:wrap-reverse !important}.justify-content-sm-start{justify-content:flex-start !important}.justify-content-sm-end{justify-content:flex-end !important}.justify-content-sm-center{justify-content:center !important}.justify-content-sm-between{justify-content:space-between !important}.justify-content-sm-around{justify-content:space-around !important}.justify-content-sm-evenly{justify-content:space-evenly !important}.align-items-sm-start{align-items:flex-start !important}.align-items-sm-end{align-items:flex-end !important}.align-items-sm-center{align-items:center !important}.align-items-sm-baseline{align-items:baseline !important}.align-items-sm-stretch{align-items:stretch !important}.align-content-sm-start{align-content:flex-start !important}.align-content-sm-end{align-content:flex-end !important}.align-content-sm-center{align-content:center !important}.align-content-sm-between{align-content:space-between !important}.align-content-sm-around{align-content:space-around !important}.align-content-sm-stretch{align-content:stretch !important}.align-self-sm-auto{align-self:auto !important}.align-self-sm-start{align-self:flex-start !important}.align-self-sm-end{align-self:flex-end !important}.align-self-sm-center{align-self:center !important}.align-self-sm-baseline{align-self:baseline !important}.align-self-sm-stretch{align-self:stretch !important}.order-sm-first{order:-1 !important}.order-sm-0{order:0 !important}.order-sm-1{order:1 !important}.order-sm-2{order:2 !important}.order-sm-3{order:3 !important}.order-sm-4{order:4 !important}.order-sm-5{order:5 !important}.order-sm-last{order:6 !important}.m-sm-0{margin:0 !important}.m-sm-1{margin:.25rem !important}.m-sm-2{margin:.5rem !important}.m-sm-3{margin:1rem !important}.m-sm-4{margin:1.5rem !important}.m-sm-5{margin:3rem !important}.m-sm-auto{margin:auto !important}.mx-sm-0{margin-right:0 !important;margin-left:0 !important}.mx-sm-1{margin-right:.25rem !important;margin-left:.25rem !important}.mx-sm-2{margin-right:.5rem !important;margin-left:.5rem !important}.mx-sm-3{margin-right:1rem !important;margin-left:1rem !important}.mx-sm-4{margin-right:1.5rem !important;margin-left:1.5rem !important}.mx-sm-5{margin-right:3rem !important;margin-left:3rem !important}.mx-sm-auto{margin-right:auto !important;margin-left:auto !important}.my-sm-0{margin-top:0 !important;margin-bottom:0 !important}.my-sm-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.my-sm-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.my-sm-3{margin-top:1rem !important;margin-bottom:1rem !important}.my-sm-4{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.my-sm-5{margin-top:3rem !important;margin-bottom:3rem !important}.my-sm-auto{margin-top:auto !important;margin-bottom:auto !important}.mt-sm-0{margin-top:0 !important}.mt-sm-1{margin-top:.25rem !important}.mt-sm-2{margin-top:.5rem !important}.mt-sm-3{margin-top:1rem !important}.mt-sm-4{margin-top:1.5rem !important}.mt-sm-5{margin-top:3rem !important}.mt-sm-auto{margin-top:auto !important}.me-sm-0{margin-right:0 !important}.me-sm-1{margin-right:.25rem !important}.me-sm-2{margin-right:.5rem !important}.me-sm-3{margin-right:1rem !important}.me-sm-4{margin-right:1.5rem !important}.me-sm-5{margin-right:3rem !important}.me-sm-auto{margin-right:auto !important}.mb-sm-0{margin-bottom:0 !important}.mb-sm-1{margin-bottom:.25rem !important}.mb-sm-2{margin-bottom:.5rem !important}.mb-sm-3{margin-bottom:1rem !important}.mb-sm-4{margin-bottom:1.5rem !important}.mb-sm-5{margin-bottom:3rem !important}.mb-sm-auto{margin-bottom:auto !important}.ms-sm-0{margin-left:0 !important}.ms-sm-1{margin-left:.25rem !important}.ms-sm-2{margin-left:.5rem !important}.ms-sm-3{margin-left:1rem !important}.ms-sm-4{margin-left:1.5rem !important}.ms-sm-5{margin-left:3rem !important}.ms-sm-auto{margin-left:auto !important}.p-sm-0{padding:0 !important}.p-sm-1{padding:.25rem !important}.p-sm-2{padding:.5rem !important}.p-sm-3{padding:1rem !important}.p-sm-4{padding:1.5rem !important}.p-sm-5{padding:3rem !important}.px-sm-0{padding-right:0 !important;padding-left:0 !important}.px-sm-1{padding-right:.25rem !important;padding-left:.25rem !important}.px-sm-2{padding-right:.5rem !important;padding-left:.5rem !important}.px-sm-3{padding-right:1rem !important;padding-left:1rem !important}.px-sm-4{padding-right:1.5rem !important;padding-left:1.5rem !important}.px-sm-5{padding-right:3rem !important;padding-left:3rem !important}.py-sm-0{padding-top:0 !important;padding-bottom:0 !important}.py-sm-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.py-sm-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.py-sm-3{padding-top:1rem !important;padding-bottom:1rem !important}.py-sm-4{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.py-sm-5{padding-top:3rem !important;padding-bottom:3rem !important}.pt-sm-0{padding-top:0 !important}.pt-sm-1{padding-top:.25rem !important}.pt-sm-2{padding-top:.5rem !important}.pt-sm-3{padding-top:1rem !important}.pt-sm-4{padding-top:1.5rem !important}.pt-sm-5{padding-top:3rem !important}.pe-sm-0{padding-right:0 !important}.pe-sm-1{padding-right:.25rem !important}.pe-sm-2{padding-right:.5rem !important}.pe-sm-3{padding-right:1rem !important}.pe-sm-4{padding-right:1.5rem !important}.pe-sm-5{padding-right:3rem !important}.pb-sm-0{padding-bottom:0 !important}.pb-sm-1{padding-bottom:.25rem !important}.pb-sm-2{padding-bottom:.5rem !important}.pb-sm-3{padding-bottom:1rem !important}.pb-sm-4{padding-bottom:1.5rem !important}.pb-sm-5{padding-bottom:3rem !important}.ps-sm-0{padding-left:0 !important}.ps-sm-1{padding-left:.25rem !important}.ps-sm-2{padding-left:.5rem !important}.ps-sm-3{padding-left:1rem !important}.ps-sm-4{padding-left:1.5rem !important}.ps-sm-5{padding-left:3rem !important}.gap-sm-0{gap:0 !important}.gap-sm-1{gap:.25rem !important}.gap-sm-2{gap:.5rem !important}.gap-sm-3{gap:1rem !important}.gap-sm-4{gap:1.5rem !important}.gap-sm-5{gap:3rem !important}.row-gap-sm-0{row-gap:0 !important}.row-gap-sm-1{row-gap:.25rem !important}.row-gap-sm-2{row-gap:.5rem !important}.row-gap-sm-3{row-gap:1rem !important}.row-gap-sm-4{row-gap:1.5rem !important}.row-gap-sm-5{row-gap:3rem !important}.column-gap-sm-0{column-gap:0 !important}.column-gap-sm-1{column-gap:.25rem !important}.column-gap-sm-2{column-gap:.5rem !important}.column-gap-sm-3{column-gap:1rem !important}.column-gap-sm-4{column-gap:1.5rem !important}.column-gap-sm-5{column-gap:3rem !important}.text-sm-start{text-align:left !important}.text-sm-end{text-align:right !important}.text-sm-center{text-align:center !important}}@media(min-width: 768px){.float-md-start{float:left !important}.float-md-end{float:right !important}.float-md-none{float:none !important}.object-fit-md-contain{object-fit:contain !important}.object-fit-md-cover{object-fit:cover !important}.object-fit-md-fill{object-fit:fill !important}.object-fit-md-scale{object-fit:scale-down !important}.object-fit-md-none{object-fit:none !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-block{display:block !important}.d-md-grid{display:grid !important}.d-md-inline-grid{display:inline-grid !important}.d-md-table{display:table !important}.d-md-table-row{display:table-row !important}.d-md-table-cell{display:table-cell !important}.d-md-flex{display:flex !important}.d-md-inline-flex{display:inline-flex !important}.d-md-none{display:none !important}.flex-md-fill{flex:1 1 auto !important}.flex-md-row{flex-direction:row !important}.flex-md-column{flex-direction:column !important}.flex-md-row-reverse{flex-direction:row-reverse !important}.flex-md-column-reverse{flex-direction:column-reverse !important}.flex-md-grow-0{flex-grow:0 !important}.flex-md-grow-1{flex-grow:1 !important}.flex-md-shrink-0{flex-shrink:0 !important}.flex-md-shrink-1{flex-shrink:1 !important}.flex-md-wrap{flex-wrap:wrap !important}.flex-md-nowrap{flex-wrap:nowrap !important}.flex-md-wrap-reverse{flex-wrap:wrap-reverse !important}.justify-content-md-start{justify-content:flex-start !important}.justify-content-md-end{justify-content:flex-end !important}.justify-content-md-center{justify-content:center !important}.justify-content-md-between{justify-content:space-between !important}.justify-content-md-around{justify-content:space-around !important}.justify-content-md-evenly{justify-content:space-evenly !important}.align-items-md-start{align-items:flex-start !important}.align-items-md-end{align-items:flex-end !important}.align-items-md-center{align-items:center !important}.align-items-md-baseline{align-items:baseline !important}.align-items-md-stretch{align-items:stretch !important}.align-content-md-start{align-content:flex-start !important}.align-content-md-end{align-content:flex-end !important}.align-content-md-center{align-content:center !important}.align-content-md-between{align-content:space-between !important}.align-content-md-around{align-content:space-around !important}.align-content-md-stretch{align-content:stretch !important}.align-self-md-auto{align-self:auto !important}.align-self-md-start{align-self:flex-start !important}.align-self-md-end{align-self:flex-end !important}.align-self-md-center{align-self:center !important}.align-self-md-baseline{align-self:baseline !important}.align-self-md-stretch{align-self:stretch !important}.order-md-first{order:-1 !important}.order-md-0{order:0 !important}.order-md-1{order:1 !important}.order-md-2{order:2 !important}.order-md-3{order:3 !important}.order-md-4{order:4 !important}.order-md-5{order:5 !important}.order-md-last{order:6 !important}.m-md-0{margin:0 !important}.m-md-1{margin:.25rem !important}.m-md-2{margin:.5rem !important}.m-md-3{margin:1rem !important}.m-md-4{margin:1.5rem !important}.m-md-5{margin:3rem !important}.m-md-auto{margin:auto !important}.mx-md-0{margin-right:0 !important;margin-left:0 !important}.mx-md-1{margin-right:.25rem !important;margin-left:.25rem !important}.mx-md-2{margin-right:.5rem !important;margin-left:.5rem !important}.mx-md-3{margin-right:1rem !important;margin-left:1rem !important}.mx-md-4{margin-right:1.5rem !important;margin-left:1.5rem !important}.mx-md-5{margin-right:3rem !important;margin-left:3rem !important}.mx-md-auto{margin-right:auto !important;margin-left:auto !important}.my-md-0{margin-top:0 !important;margin-bottom:0 !important}.my-md-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.my-md-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.my-md-3{margin-top:1rem !important;margin-bottom:1rem !important}.my-md-4{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.my-md-5{margin-top:3rem !important;margin-bottom:3rem !important}.my-md-auto{margin-top:auto !important;margin-bottom:auto !important}.mt-md-0{margin-top:0 !important}.mt-md-1{margin-top:.25rem !important}.mt-md-2{margin-top:.5rem !important}.mt-md-3{margin-top:1rem !important}.mt-md-4{margin-top:1.5rem !important}.mt-md-5{margin-top:3rem !important}.mt-md-auto{margin-top:auto !important}.me-md-0{margin-right:0 !important}.me-md-1{margin-right:.25rem !important}.me-md-2{margin-right:.5rem !important}.me-md-3{margin-right:1rem !important}.me-md-4{margin-right:1.5rem !important}.me-md-5{margin-right:3rem !important}.me-md-auto{margin-right:auto !important}.mb-md-0{margin-bottom:0 !important}.mb-md-1{margin-bottom:.25rem !important}.mb-md-2{margin-bottom:.5rem !important}.mb-md-3{margin-bottom:1rem !important}.mb-md-4{margin-bottom:1.5rem !important}.mb-md-5{margin-bottom:3rem !important}.mb-md-auto{margin-bottom:auto !important}.ms-md-0{margin-left:0 !important}.ms-md-1{margin-left:.25rem !important}.ms-md-2{margin-left:.5rem !important}.ms-md-3{margin-left:1rem !important}.ms-md-4{margin-left:1.5rem !important}.ms-md-5{margin-left:3rem !important}.ms-md-auto{margin-left:auto !important}.p-md-0{padding:0 !important}.p-md-1{padding:.25rem !important}.p-md-2{padding:.5rem !important}.p-md-3{padding:1rem !important}.p-md-4{padding:1.5rem !important}.p-md-5{padding:3rem !important}.px-md-0{padding-right:0 !important;padding-left:0 !important}.px-md-1{padding-right:.25rem !important;padding-left:.25rem !important}.px-md-2{padding-right:.5rem !important;padding-left:.5rem !important}.px-md-3{padding-right:1rem !important;padding-left:1rem !important}.px-md-4{padding-right:1.5rem !important;padding-left:1.5rem !important}.px-md-5{padding-right:3rem !important;padding-left:3rem !important}.py-md-0{padding-top:0 !important;padding-bottom:0 !important}.py-md-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.py-md-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.py-md-3{padding-top:1rem !important;padding-bottom:1rem !important}.py-md-4{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.py-md-5{padding-top:3rem !important;padding-bottom:3rem !important}.pt-md-0{padding-top:0 !important}.pt-md-1{padding-top:.25rem !important}.pt-md-2{padding-top:.5rem !important}.pt-md-3{padding-top:1rem !important}.pt-md-4{padding-top:1.5rem !important}.pt-md-5{padding-top:3rem !important}.pe-md-0{padding-right:0 !important}.pe-md-1{padding-right:.25rem !important}.pe-md-2{padding-right:.5rem !important}.pe-md-3{padding-right:1rem !important}.pe-md-4{padding-right:1.5rem !important}.pe-md-5{padding-right:3rem !important}.pb-md-0{padding-bottom:0 !important}.pb-md-1{padding-bottom:.25rem !important}.pb-md-2{padding-bottom:.5rem !important}.pb-md-3{padding-bottom:1rem !important}.pb-md-4{padding-bottom:1.5rem !important}.pb-md-5{padding-bottom:3rem !important}.ps-md-0{padding-left:0 !important}.ps-md-1{padding-left:.25rem !important}.ps-md-2{padding-left:.5rem !important}.ps-md-3{padding-left:1rem !important}.ps-md-4{padding-left:1.5rem !important}.ps-md-5{padding-left:3rem !important}.gap-md-0{gap:0 !important}.gap-md-1{gap:.25rem !important}.gap-md-2{gap:.5rem !important}.gap-md-3{gap:1rem !important}.gap-md-4{gap:1.5rem !important}.gap-md-5{gap:3rem !important}.row-gap-md-0{row-gap:0 !important}.row-gap-md-1{row-gap:.25rem !important}.row-gap-md-2{row-gap:.5rem !important}.row-gap-md-3{row-gap:1rem !important}.row-gap-md-4{row-gap:1.5rem !important}.row-gap-md-5{row-gap:3rem !important}.column-gap-md-0{column-gap:0 !important}.column-gap-md-1{column-gap:.25rem !important}.column-gap-md-2{column-gap:.5rem !important}.column-gap-md-3{column-gap:1rem !important}.column-gap-md-4{column-gap:1.5rem !important}.column-gap-md-5{column-gap:3rem !important}.text-md-start{text-align:left !important}.text-md-end{text-align:right !important}.text-md-center{text-align:center !important}}@media(min-width: 992px){.float-lg-start{float:left !important}.float-lg-end{float:right !important}.float-lg-none{float:none !important}.object-fit-lg-contain{object-fit:contain !important}.object-fit-lg-cover{object-fit:cover !important}.object-fit-lg-fill{object-fit:fill !important}.object-fit-lg-scale{object-fit:scale-down !important}.object-fit-lg-none{object-fit:none !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-block{display:block !important}.d-lg-grid{display:grid !important}.d-lg-inline-grid{display:inline-grid !important}.d-lg-table{display:table !important}.d-lg-table-row{display:table-row !important}.d-lg-table-cell{display:table-cell !important}.d-lg-flex{display:flex !important}.d-lg-inline-flex{display:inline-flex !important}.d-lg-none{display:none !important}.flex-lg-fill{flex:1 1 auto !important}.flex-lg-row{flex-direction:row !important}.flex-lg-column{flex-direction:column !important}.flex-lg-row-reverse{flex-direction:row-reverse !important}.flex-lg-column-reverse{flex-direction:column-reverse !important}.flex-lg-grow-0{flex-grow:0 !important}.flex-lg-grow-1{flex-grow:1 !important}.flex-lg-shrink-0{flex-shrink:0 !important}.flex-lg-shrink-1{flex-shrink:1 !important}.flex-lg-wrap{flex-wrap:wrap !important}.flex-lg-nowrap{flex-wrap:nowrap !important}.flex-lg-wrap-reverse{flex-wrap:wrap-reverse !important}.justify-content-lg-start{justify-content:flex-start !important}.justify-content-lg-end{justify-content:flex-end !important}.justify-content-lg-center{justify-content:center !important}.justify-content-lg-between{justify-content:space-between !important}.justify-content-lg-around{justify-content:space-around !important}.justify-content-lg-evenly{justify-content:space-evenly !important}.align-items-lg-start{align-items:flex-start !important}.align-items-lg-end{align-items:flex-end !important}.align-items-lg-center{align-items:center !important}.align-items-lg-baseline{align-items:baseline !important}.align-items-lg-stretch{align-items:stretch !important}.align-content-lg-start{align-content:flex-start !important}.align-content-lg-end{align-content:flex-end !important}.align-content-lg-center{align-content:center !important}.align-content-lg-between{align-content:space-between !important}.align-content-lg-around{align-content:space-around !important}.align-content-lg-stretch{align-content:stretch !important}.align-self-lg-auto{align-self:auto !important}.align-self-lg-start{align-self:flex-start !important}.align-self-lg-end{align-self:flex-end !important}.align-self-lg-center{align-self:center !important}.align-self-lg-baseline{align-self:baseline !important}.align-self-lg-stretch{align-self:stretch !important}.order-lg-first{order:-1 !important}.order-lg-0{order:0 !important}.order-lg-1{order:1 !important}.order-lg-2{order:2 !important}.order-lg-3{order:3 !important}.order-lg-4{order:4 !important}.order-lg-5{order:5 !important}.order-lg-last{order:6 !important}.m-lg-0{margin:0 !important}.m-lg-1{margin:.25rem !important}.m-lg-2{margin:.5rem !important}.m-lg-3{margin:1rem !important}.m-lg-4{margin:1.5rem !important}.m-lg-5{margin:3rem !important}.m-lg-auto{margin:auto !important}.mx-lg-0{margin-right:0 !important;margin-left:0 !important}.mx-lg-1{margin-right:.25rem !important;margin-left:.25rem !important}.mx-lg-2{margin-right:.5rem !important;margin-left:.5rem !important}.mx-lg-3{margin-right:1rem !important;margin-left:1rem !important}.mx-lg-4{margin-right:1.5rem !important;margin-left:1.5rem !important}.mx-lg-5{margin-right:3rem !important;margin-left:3rem !important}.mx-lg-auto{margin-right:auto !important;margin-left:auto !important}.my-lg-0{margin-top:0 !important;margin-bottom:0 !important}.my-lg-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.my-lg-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.my-lg-3{margin-top:1rem !important;margin-bottom:1rem !important}.my-lg-4{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.my-lg-5{margin-top:3rem !important;margin-bottom:3rem !important}.my-lg-auto{margin-top:auto !important;margin-bottom:auto !important}.mt-lg-0{margin-top:0 !important}.mt-lg-1{margin-top:.25rem !important}.mt-lg-2{margin-top:.5rem !important}.mt-lg-3{margin-top:1rem !important}.mt-lg-4{margin-top:1.5rem !important}.mt-lg-5{margin-top:3rem !important}.mt-lg-auto{margin-top:auto !important}.me-lg-0{margin-right:0 !important}.me-lg-1{margin-right:.25rem !important}.me-lg-2{margin-right:.5rem !important}.me-lg-3{margin-right:1rem !important}.me-lg-4{margin-right:1.5rem !important}.me-lg-5{margin-right:3rem !important}.me-lg-auto{margin-right:auto !important}.mb-lg-0{margin-bottom:0 !important}.mb-lg-1{margin-bottom:.25rem !important}.mb-lg-2{margin-bottom:.5rem !important}.mb-lg-3{margin-bottom:1rem !important}.mb-lg-4{margin-bottom:1.5rem !important}.mb-lg-5{margin-bottom:3rem !important}.mb-lg-auto{margin-bottom:auto !important}.ms-lg-0{margin-left:0 !important}.ms-lg-1{margin-left:.25rem !important}.ms-lg-2{margin-left:.5rem !important}.ms-lg-3{margin-left:1rem !important}.ms-lg-4{margin-left:1.5rem !important}.ms-lg-5{margin-left:3rem !important}.ms-lg-auto{margin-left:auto !important}.p-lg-0{padding:0 !important}.p-lg-1{padding:.25rem !important}.p-lg-2{padding:.5rem !important}.p-lg-3{padding:1rem !important}.p-lg-4{padding:1.5rem !important}.p-lg-5{padding:3rem !important}.px-lg-0{padding-right:0 !important;padding-left:0 !important}.px-lg-1{padding-right:.25rem !important;padding-left:.25rem !important}.px-lg-2{padding-right:.5rem !important;padding-left:.5rem !important}.px-lg-3{padding-right:1rem !important;padding-left:1rem !important}.px-lg-4{padding-right:1.5rem !important;padding-left:1.5rem !important}.px-lg-5{padding-right:3rem !important;padding-left:3rem !important}.py-lg-0{padding-top:0 !important;padding-bottom:0 !important}.py-lg-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.py-lg-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.py-lg-3{padding-top:1rem !important;padding-bottom:1rem !important}.py-lg-4{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.py-lg-5{padding-top:3rem !important;padding-bottom:3rem !important}.pt-lg-0{padding-top:0 !important}.pt-lg-1{padding-top:.25rem !important}.pt-lg-2{padding-top:.5rem !important}.pt-lg-3{padding-top:1rem !important}.pt-lg-4{padding-top:1.5rem !important}.pt-lg-5{padding-top:3rem !important}.pe-lg-0{padding-right:0 !important}.pe-lg-1{padding-right:.25rem !important}.pe-lg-2{padding-right:.5rem !important}.pe-lg-3{padding-right:1rem !important}.pe-lg-4{padding-right:1.5rem !important}.pe-lg-5{padding-right:3rem !important}.pb-lg-0{padding-bottom:0 !important}.pb-lg-1{padding-bottom:.25rem !important}.pb-lg-2{padding-bottom:.5rem !important}.pb-lg-3{padding-bottom:1rem !important}.pb-lg-4{padding-bottom:1.5rem !important}.pb-lg-5{padding-bottom:3rem !important}.ps-lg-0{padding-left:0 !important}.ps-lg-1{padding-left:.25rem !important}.ps-lg-2{padding-left:.5rem !important}.ps-lg-3{padding-left:1rem !important}.ps-lg-4{padding-left:1.5rem !important}.ps-lg-5{padding-left:3rem !important}.gap-lg-0{gap:0 !important}.gap-lg-1{gap:.25rem !important}.gap-lg-2{gap:.5rem !important}.gap-lg-3{gap:1rem !important}.gap-lg-4{gap:1.5rem !important}.gap-lg-5{gap:3rem !important}.row-gap-lg-0{row-gap:0 !important}.row-gap-lg-1{row-gap:.25rem !important}.row-gap-lg-2{row-gap:.5rem !important}.row-gap-lg-3{row-gap:1rem !important}.row-gap-lg-4{row-gap:1.5rem !important}.row-gap-lg-5{row-gap:3rem !important}.column-gap-lg-0{column-gap:0 !important}.column-gap-lg-1{column-gap:.25rem !important}.column-gap-lg-2{column-gap:.5rem !important}.column-gap-lg-3{column-gap:1rem !important}.column-gap-lg-4{column-gap:1.5rem !important}.column-gap-lg-5{column-gap:3rem !important}.text-lg-start{text-align:left !important}.text-lg-end{text-align:right !important}.text-lg-center{text-align:center !important}}@media(min-width: 1200px){.float-xl-start{float:left !important}.float-xl-end{float:right !important}.float-xl-none{float:none !important}.object-fit-xl-contain{object-fit:contain !important}.object-fit-xl-cover{object-fit:cover !important}.object-fit-xl-fill{object-fit:fill !important}.object-fit-xl-scale{object-fit:scale-down !important}.object-fit-xl-none{object-fit:none !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-block{display:block !important}.d-xl-grid{display:grid !important}.d-xl-inline-grid{display:inline-grid !important}.d-xl-table{display:table !important}.d-xl-table-row{display:table-row !important}.d-xl-table-cell{display:table-cell !important}.d-xl-flex{display:flex !important}.d-xl-inline-flex{display:inline-flex !important}.d-xl-none{display:none !important}.flex-xl-fill{flex:1 1 auto !important}.flex-xl-row{flex-direction:row !important}.flex-xl-column{flex-direction:column !important}.flex-xl-row-reverse{flex-direction:row-reverse !important}.flex-xl-column-reverse{flex-direction:column-reverse !important}.flex-xl-grow-0{flex-grow:0 !important}.flex-xl-grow-1{flex-grow:1 !important}.flex-xl-shrink-0{flex-shrink:0 !important}.flex-xl-shrink-1{flex-shrink:1 !important}.flex-xl-wrap{flex-wrap:wrap !important}.flex-xl-nowrap{flex-wrap:nowrap !important}.flex-xl-wrap-reverse{flex-wrap:wrap-reverse !important}.justify-content-xl-start{justify-content:flex-start !important}.justify-content-xl-end{justify-content:flex-end !important}.justify-content-xl-center{justify-content:center !important}.justify-content-xl-between{justify-content:space-between !important}.justify-content-xl-around{justify-content:space-around !important}.justify-content-xl-evenly{justify-content:space-evenly !important}.align-items-xl-start{align-items:flex-start !important}.align-items-xl-end{align-items:flex-end !important}.align-items-xl-center{align-items:center !important}.align-items-xl-baseline{align-items:baseline !important}.align-items-xl-stretch{align-items:stretch !important}.align-content-xl-start{align-content:flex-start !important}.align-content-xl-end{align-content:flex-end !important}.align-content-xl-center{align-content:center !important}.align-content-xl-between{align-content:space-between !important}.align-content-xl-around{align-content:space-around !important}.align-content-xl-stretch{align-content:stretch !important}.align-self-xl-auto{align-self:auto !important}.align-self-xl-start{align-self:flex-start !important}.align-self-xl-end{align-self:flex-end !important}.align-self-xl-center{align-self:center !important}.align-self-xl-baseline{align-self:baseline !important}.align-self-xl-stretch{align-self:stretch !important}.order-xl-first{order:-1 !important}.order-xl-0{order:0 !important}.order-xl-1{order:1 !important}.order-xl-2{order:2 !important}.order-xl-3{order:3 !important}.order-xl-4{order:4 !important}.order-xl-5{order:5 !important}.order-xl-last{order:6 !important}.m-xl-0{margin:0 !important}.m-xl-1{margin:.25rem !important}.m-xl-2{margin:.5rem !important}.m-xl-3{margin:1rem !important}.m-xl-4{margin:1.5rem !important}.m-xl-5{margin:3rem !important}.m-xl-auto{margin:auto !important}.mx-xl-0{margin-right:0 !important;margin-left:0 !important}.mx-xl-1{margin-right:.25rem !important;margin-left:.25rem !important}.mx-xl-2{margin-right:.5rem !important;margin-left:.5rem !important}.mx-xl-3{margin-right:1rem !important;margin-left:1rem !important}.mx-xl-4{margin-right:1.5rem !important;margin-left:1.5rem !important}.mx-xl-5{margin-right:3rem !important;margin-left:3rem !important}.mx-xl-auto{margin-right:auto !important;margin-left:auto !important}.my-xl-0{margin-top:0 !important;margin-bottom:0 !important}.my-xl-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.my-xl-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.my-xl-3{margin-top:1rem !important;margin-bottom:1rem !important}.my-xl-4{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.my-xl-5{margin-top:3rem !important;margin-bottom:3rem !important}.my-xl-auto{margin-top:auto !important;margin-bottom:auto !important}.mt-xl-0{margin-top:0 !important}.mt-xl-1{margin-top:.25rem !important}.mt-xl-2{margin-top:.5rem !important}.mt-xl-3{margin-top:1rem !important}.mt-xl-4{margin-top:1.5rem !important}.mt-xl-5{margin-top:3rem !important}.mt-xl-auto{margin-top:auto !important}.me-xl-0{margin-right:0 !important}.me-xl-1{margin-right:.25rem !important}.me-xl-2{margin-right:.5rem !important}.me-xl-3{margin-right:1rem !important}.me-xl-4{margin-right:1.5rem !important}.me-xl-5{margin-right:3rem !important}.me-xl-auto{margin-right:auto !important}.mb-xl-0{margin-bottom:0 !important}.mb-xl-1{margin-bottom:.25rem !important}.mb-xl-2{margin-bottom:.5rem !important}.mb-xl-3{margin-bottom:1rem !important}.mb-xl-4{margin-bottom:1.5rem !important}.mb-xl-5{margin-bottom:3rem !important}.mb-xl-auto{margin-bottom:auto !important}.ms-xl-0{margin-left:0 !important}.ms-xl-1{margin-left:.25rem !important}.ms-xl-2{margin-left:.5rem !important}.ms-xl-3{margin-left:1rem !important}.ms-xl-4{margin-left:1.5rem !important}.ms-xl-5{margin-left:3rem !important}.ms-xl-auto{margin-left:auto !important}.p-xl-0{padding:0 !important}.p-xl-1{padding:.25rem !important}.p-xl-2{padding:.5rem !important}.p-xl-3{padding:1rem !important}.p-xl-4{padding:1.5rem !important}.p-xl-5{padding:3rem !important}.px-xl-0{padding-right:0 !important;padding-left:0 !important}.px-xl-1{padding-right:.25rem !important;padding-left:.25rem !important}.px-xl-2{padding-right:.5rem !important;padding-left:.5rem !important}.px-xl-3{padding-right:1rem !important;padding-left:1rem !important}.px-xl-4{padding-right:1.5rem !important;padding-left:1.5rem !important}.px-xl-5{padding-right:3rem !important;padding-left:3rem !important}.py-xl-0{padding-top:0 !important;padding-bottom:0 !important}.py-xl-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.py-xl-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.py-xl-3{padding-top:1rem !important;padding-bottom:1rem !important}.py-xl-4{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.py-xl-5{padding-top:3rem !important;padding-bottom:3rem !important}.pt-xl-0{padding-top:0 !important}.pt-xl-1{padding-top:.25rem !important}.pt-xl-2{padding-top:.5rem !important}.pt-xl-3{padding-top:1rem !important}.pt-xl-4{padding-top:1.5rem !important}.pt-xl-5{padding-top:3rem !important}.pe-xl-0{padding-right:0 !important}.pe-xl-1{padding-right:.25rem !important}.pe-xl-2{padding-right:.5rem !important}.pe-xl-3{padding-right:1rem !important}.pe-xl-4{padding-right:1.5rem !important}.pe-xl-5{padding-right:3rem !important}.pb-xl-0{padding-bottom:0 !important}.pb-xl-1{padding-bottom:.25rem !important}.pb-xl-2{padding-bottom:.5rem !important}.pb-xl-3{padding-bottom:1rem !important}.pb-xl-4{padding-bottom:1.5rem !important}.pb-xl-5{padding-bottom:3rem !important}.ps-xl-0{padding-left:0 !important}.ps-xl-1{padding-left:.25rem !important}.ps-xl-2{padding-left:.5rem !important}.ps-xl-3{padding-left:1rem !important}.ps-xl-4{padding-left:1.5rem !important}.ps-xl-5{padding-left:3rem !important}.gap-xl-0{gap:0 !important}.gap-xl-1{gap:.25rem !important}.gap-xl-2{gap:.5rem !important}.gap-xl-3{gap:1rem !important}.gap-xl-4{gap:1.5rem !important}.gap-xl-5{gap:3rem !important}.row-gap-xl-0{row-gap:0 !important}.row-gap-xl-1{row-gap:.25rem !important}.row-gap-xl-2{row-gap:.5rem !important}.row-gap-xl-3{row-gap:1rem !important}.row-gap-xl-4{row-gap:1.5rem !important}.row-gap-xl-5{row-gap:3rem !important}.column-gap-xl-0{column-gap:0 !important}.column-gap-xl-1{column-gap:.25rem !important}.column-gap-xl-2{column-gap:.5rem !important}.column-gap-xl-3{column-gap:1rem !important}.column-gap-xl-4{column-gap:1.5rem !important}.column-gap-xl-5{column-gap:3rem !important}.text-xl-start{text-align:left !important}.text-xl-end{text-align:right !important}.text-xl-center{text-align:center !important}}@media(min-width: 1400px){.float-xxl-start{float:left !important}.float-xxl-end{float:right !important}.float-xxl-none{float:none !important}.object-fit-xxl-contain{object-fit:contain !important}.object-fit-xxl-cover{object-fit:cover !important}.object-fit-xxl-fill{object-fit:fill !important}.object-fit-xxl-scale{object-fit:scale-down !important}.object-fit-xxl-none{object-fit:none !important}.d-xxl-inline{display:inline !important}.d-xxl-inline-block{display:inline-block !important}.d-xxl-block{display:block !important}.d-xxl-grid{display:grid !important}.d-xxl-inline-grid{display:inline-grid !important}.d-xxl-table{display:table !important}.d-xxl-table-row{display:table-row !important}.d-xxl-table-cell{display:table-cell !important}.d-xxl-flex{display:flex !important}.d-xxl-inline-flex{display:inline-flex !important}.d-xxl-none{display:none !important}.flex-xxl-fill{flex:1 1 auto !important}.flex-xxl-row{flex-direction:row !important}.flex-xxl-column{flex-direction:column !important}.flex-xxl-row-reverse{flex-direction:row-reverse !important}.flex-xxl-column-reverse{flex-direction:column-reverse !important}.flex-xxl-grow-0{flex-grow:0 !important}.flex-xxl-grow-1{flex-grow:1 !important}.flex-xxl-shrink-0{flex-shrink:0 !important}.flex-xxl-shrink-1{flex-shrink:1 !important}.flex-xxl-wrap{flex-wrap:wrap !important}.flex-xxl-nowrap{flex-wrap:nowrap !important}.flex-xxl-wrap-reverse{flex-wrap:wrap-reverse !important}.justify-content-xxl-start{justify-content:flex-start !important}.justify-content-xxl-end{justify-content:flex-end !important}.justify-content-xxl-center{justify-content:center !important}.justify-content-xxl-between{justify-content:space-between !important}.justify-content-xxl-around{justify-content:space-around !important}.justify-content-xxl-evenly{justify-content:space-evenly !important}.align-items-xxl-start{align-items:flex-start !important}.align-items-xxl-end{align-items:flex-end !important}.align-items-xxl-center{align-items:center !important}.align-items-xxl-baseline{align-items:baseline !important}.align-items-xxl-stretch{align-items:stretch !important}.align-content-xxl-start{align-content:flex-start !important}.align-content-xxl-end{align-content:flex-end !important}.align-content-xxl-center{align-content:center !important}.align-content-xxl-between{align-content:space-between !important}.align-content-xxl-around{align-content:space-around !important}.align-content-xxl-stretch{align-content:stretch !important}.align-self-xxl-auto{align-self:auto !important}.align-self-xxl-start{align-self:flex-start !important}.align-self-xxl-end{align-self:flex-end !important}.align-self-xxl-center{align-self:center !important}.align-self-xxl-baseline{align-self:baseline !important}.align-self-xxl-stretch{align-self:stretch !important}.order-xxl-first{order:-1 !important}.order-xxl-0{order:0 !important}.order-xxl-1{order:1 !important}.order-xxl-2{order:2 !important}.order-xxl-3{order:3 !important}.order-xxl-4{order:4 !important}.order-xxl-5{order:5 !important}.order-xxl-last{order:6 !important}.m-xxl-0{margin:0 !important}.m-xxl-1{margin:.25rem !important}.m-xxl-2{margin:.5rem !important}.m-xxl-3{margin:1rem !important}.m-xxl-4{margin:1.5rem !important}.m-xxl-5{margin:3rem !important}.m-xxl-auto{margin:auto !important}.mx-xxl-0{margin-right:0 !important;margin-left:0 !important}.mx-xxl-1{margin-right:.25rem !important;margin-left:.25rem !important}.mx-xxl-2{margin-right:.5rem !important;margin-left:.5rem !important}.mx-xxl-3{margin-right:1rem !important;margin-left:1rem !important}.mx-xxl-4{margin-right:1.5rem !important;margin-left:1.5rem !important}.mx-xxl-5{margin-right:3rem !important;margin-left:3rem !important}.mx-xxl-auto{margin-right:auto !important;margin-left:auto !important}.my-xxl-0{margin-top:0 !important;margin-bottom:0 !important}.my-xxl-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.my-xxl-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.my-xxl-3{margin-top:1rem !important;margin-bottom:1rem !important}.my-xxl-4{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.my-xxl-5{margin-top:3rem !important;margin-bottom:3rem !important}.my-xxl-auto{margin-top:auto !important;margin-bottom:auto !important}.mt-xxl-0{margin-top:0 !important}.mt-xxl-1{margin-top:.25rem !important}.mt-xxl-2{margin-top:.5rem !important}.mt-xxl-3{margin-top:1rem !important}.mt-xxl-4{margin-top:1.5rem !important}.mt-xxl-5{margin-top:3rem !important}.mt-xxl-auto{margin-top:auto !important}.me-xxl-0{margin-right:0 !important}.me-xxl-1{margin-right:.25rem !important}.me-xxl-2{margin-right:.5rem !important}.me-xxl-3{margin-right:1rem !important}.me-xxl-4{margin-right:1.5rem !important}.me-xxl-5{margin-right:3rem !important}.me-xxl-auto{margin-right:auto !important}.mb-xxl-0{margin-bottom:0 !important}.mb-xxl-1{margin-bottom:.25rem !important}.mb-xxl-2{margin-bottom:.5rem !important}.mb-xxl-3{margin-bottom:1rem !important}.mb-xxl-4{margin-bottom:1.5rem !important}.mb-xxl-5{margin-bottom:3rem !important}.mb-xxl-auto{margin-bottom:auto !important}.ms-xxl-0{margin-left:0 !important}.ms-xxl-1{margin-left:.25rem !important}.ms-xxl-2{margin-left:.5rem !important}.ms-xxl-3{margin-left:1rem !important}.ms-xxl-4{margin-left:1.5rem !important}.ms-xxl-5{margin-left:3rem !important}.ms-xxl-auto{margin-left:auto !important}.p-xxl-0{padding:0 !important}.p-xxl-1{padding:.25rem !important}.p-xxl-2{padding:.5rem !important}.p-xxl-3{padding:1rem !important}.p-xxl-4{padding:1.5rem !important}.p-xxl-5{padding:3rem !important}.px-xxl-0{padding-right:0 !important;padding-left:0 !important}.px-xxl-1{padding-right:.25rem !important;padding-left:.25rem !important}.px-xxl-2{padding-right:.5rem !important;padding-left:.5rem !important}.px-xxl-3{padding-right:1rem !important;padding-left:1rem !important}.px-xxl-4{padding-right:1.5rem !important;padding-left:1.5rem !important}.px-xxl-5{padding-right:3rem !important;padding-left:3rem !important}.py-xxl-0{padding-top:0 !important;padding-bottom:0 !important}.py-xxl-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.py-xxl-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.py-xxl-3{padding-top:1rem !important;padding-bottom:1rem !important}.py-xxl-4{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.py-xxl-5{padding-top:3rem !important;padding-bottom:3rem !important}.pt-xxl-0{padding-top:0 !important}.pt-xxl-1{padding-top:.25rem !important}.pt-xxl-2{padding-top:.5rem !important}.pt-xxl-3{padding-top:1rem !important}.pt-xxl-4{padding-top:1.5rem !important}.pt-xxl-5{padding-top:3rem !important}.pe-xxl-0{padding-right:0 !important}.pe-xxl-1{padding-right:.25rem !important}.pe-xxl-2{padding-right:.5rem !important}.pe-xxl-3{padding-right:1rem !important}.pe-xxl-4{padding-right:1.5rem !important}.pe-xxl-5{padding-right:3rem !important}.pb-xxl-0{padding-bottom:0 !important}.pb-xxl-1{padding-bottom:.25rem !important}.pb-xxl-2{padding-bottom:.5rem !important}.pb-xxl-3{padding-bottom:1rem !important}.pb-xxl-4{padding-bottom:1.5rem !important}.pb-xxl-5{padding-bottom:3rem !important}.ps-xxl-0{padding-left:0 !important}.ps-xxl-1{padding-left:.25rem !important}.ps-xxl-2{padding-left:.5rem !important}.ps-xxl-3{padding-left:1rem !important}.ps-xxl-4{padding-left:1.5rem !important}.ps-xxl-5{padding-left:3rem !important}.gap-xxl-0{gap:0 !important}.gap-xxl-1{gap:.25rem !important}.gap-xxl-2{gap:.5rem !important}.gap-xxl-3{gap:1rem !important}.gap-xxl-4{gap:1.5rem !important}.gap-xxl-5{gap:3rem !important}.row-gap-xxl-0{row-gap:0 !important}.row-gap-xxl-1{row-gap:.25rem !important}.row-gap-xxl-2{row-gap:.5rem !important}.row-gap-xxl-3{row-gap:1rem !important}.row-gap-xxl-4{row-gap:1.5rem !important}.row-gap-xxl-5{row-gap:3rem !important}.column-gap-xxl-0{column-gap:0 !important}.column-gap-xxl-1{column-gap:.25rem !important}.column-gap-xxl-2{column-gap:.5rem !important}.column-gap-xxl-3{column-gap:1rem !important}.column-gap-xxl-4{column-gap:1.5rem !important}.column-gap-xxl-5{column-gap:3rem !important}.text-xxl-start{text-align:left !important}.text-xxl-end{text-align:right !important}.text-xxl-center{text-align:center !important}}.bg-default{color:#fff}.bg-primary{color:#fff}.bg-secondary{color:#fff}.bg-success{color:#fff}.bg-info{color:#fff}.bg-warning{color:#fff}.bg-danger{color:#fff}.bg-light{color:#fff}.bg-dark{color:#fff}@media(min-width: 1200px){.fs-1{font-size:2rem !important}.fs-2{font-size:1.65rem !important}.fs-3{font-size:1.45rem !important}}@media print{.d-print-inline{display:inline !important}.d-print-inline-block{display:inline-block !important}.d-print-block{display:block !important}.d-print-grid{display:grid !important}.d-print-inline-grid{display:inline-grid !important}.d-print-table{display:table !important}.d-print-table-row{display:table-row !important}.d-print-table-cell{display:table-cell !important}.d-print-flex{display:flex !important}.d-print-inline-flex{display:inline-flex !important}.d-print-none{display:none !important}}.bg-blue{--bslib-color-bg: #375a7f;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-blue{--bslib-color-fg: #375a7f;color:var(--bslib-color-fg)}.bg-indigo{--bslib-color-bg: #6610f2;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-indigo{--bslib-color-fg: #6610f2;color:var(--bslib-color-fg)}.bg-purple{--bslib-color-bg: #6f42c1;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-purple{--bslib-color-fg: #6f42c1;color:var(--bslib-color-fg)}.bg-pink{--bslib-color-bg: #e83e8c;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-pink{--bslib-color-fg: #e83e8c;color:var(--bslib-color-fg)}.bg-red{--bslib-color-bg: #e74c3c;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-red{--bslib-color-fg: #e74c3c;color:var(--bslib-color-fg)}.bg-orange{--bslib-color-bg: #fd7e14;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-orange{--bslib-color-fg: #fd7e14;color:var(--bslib-color-fg)}.bg-yellow{--bslib-color-bg: #f39c12;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-yellow{--bslib-color-fg: #f39c12;color:var(--bslib-color-fg)}.bg-green{--bslib-color-bg: #00bc8c;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-green{--bslib-color-fg: #00bc8c;color:var(--bslib-color-fg)}.bg-teal{--bslib-color-bg: #20c997;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-teal{--bslib-color-fg: #20c997;color:var(--bslib-color-fg)}.bg-cyan{--bslib-color-bg: #3498db;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-cyan{--bslib-color-fg: #3498db;color:var(--bslib-color-fg)}.text-default{--bslib-color-fg: #434343}.bg-default{--bslib-color-bg: #434343;--bslib-color-fg: #fff}.text-primary{--bslib-color-fg: #375a7f}.bg-primary{--bslib-color-bg: #375a7f;--bslib-color-fg: #fff}.text-secondary{--bslib-color-fg: #434343}.bg-secondary{--bslib-color-bg: #434343;--bslib-color-fg: #fff}.text-success{--bslib-color-fg: #00bc8c}.bg-success{--bslib-color-bg: #00bc8c;--bslib-color-fg: #fff}.text-info{--bslib-color-fg: #3498db}.bg-info{--bslib-color-bg: #3498db;--bslib-color-fg: #fff}.text-warning{--bslib-color-fg: #f39c12}.bg-warning{--bslib-color-bg: #f39c12;--bslib-color-fg: #fff}.text-danger{--bslib-color-fg: #e74c3c}.bg-danger{--bslib-color-bg: #e74c3c;--bslib-color-fg: #fff}.text-light{--bslib-color-fg: #6f6f6f}.bg-light{--bslib-color-bg: #6f6f6f;--bslib-color-fg: #fff}.text-dark{--bslib-color-fg: #2d2d2d}.bg-dark{--bslib-color-bg: #2d2d2d;--bslib-color-fg: #fff}.bg-gradient-blue-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #4a3cad;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #4a3cad;color:#fff}.bg-gradient-blue-purple{--bslib-color-fg: #fff;--bslib-color-bg: #4d5099;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #4d5099;color:#fff}.bg-gradient-blue-pink{--bslib-color-fg: #fff;--bslib-color-bg: #7e4f84;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #7e4f84;color:#fff}.bg-gradient-blue-red{--bslib-color-fg: #fff;--bslib-color-bg: #7d5464;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #7d5464;color:#fff}.bg-gradient-blue-orange{--bslib-color-fg: #fff;--bslib-color-bg: #866854;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #866854;color:#fff}.bg-gradient-blue-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #827453;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #827453;color:#fff}.bg-gradient-blue-green{--bslib-color-fg: #fff;--bslib-color-bg: #218184;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #218184;color:#fff}.bg-gradient-blue-teal{--bslib-color-fg: #fff;--bslib-color-bg: #2e8689;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #2e8689;color:#fff}.bg-gradient-blue-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #3673a4;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #3673a4;color:#fff}.bg-gradient-indigo-blue{--bslib-color-fg: #fff;--bslib-color-bg: #532ec4;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #532ec4;color:#fff}.bg-gradient-indigo-purple{--bslib-color-fg: #fff;--bslib-color-bg: #6a24de;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #6a24de;color:#fff}.bg-gradient-indigo-pink{--bslib-color-fg: #fff;--bslib-color-bg: #9a22c9;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #9a22c9;color:#fff}.bg-gradient-indigo-red{--bslib-color-fg: #fff;--bslib-color-bg: #9a28a9;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #9a28a9;color:#fff}.bg-gradient-indigo-orange{--bslib-color-fg: #fff;--bslib-color-bg: #a23c99;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #a23c99;color:#fff}.bg-gradient-indigo-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #9e4898;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #9e4898;color:#fff}.bg-gradient-indigo-green{--bslib-color-fg: #fff;--bslib-color-bg: #3d55c9;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #3d55c9;color:#fff}.bg-gradient-indigo-teal{--bslib-color-fg: #fff;--bslib-color-bg: #4a5ace;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #4a5ace;color:#fff}.bg-gradient-indigo-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #5246e9;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #5246e9;color:#fff}.bg-gradient-purple-blue{--bslib-color-fg: #fff;--bslib-color-bg: #594ca7;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #594ca7;color:#fff}.bg-gradient-purple-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #6b2ed5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #6b2ed5;color:#fff}.bg-gradient-purple-pink{--bslib-color-fg: #fff;--bslib-color-bg: #9f40ac;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #9f40ac;color:#fff}.bg-gradient-purple-red{--bslib-color-fg: #fff;--bslib-color-bg: #9f468c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #9f468c;color:#fff}.bg-gradient-purple-orange{--bslib-color-fg: #fff;--bslib-color-bg: #a85a7c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #a85a7c;color:#fff}.bg-gradient-purple-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #a4667b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #a4667b;color:#fff}.bg-gradient-purple-green{--bslib-color-fg: #fff;--bslib-color-bg: #4373ac;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #4373ac;color:#fff}.bg-gradient-purple-teal{--bslib-color-fg: #fff;--bslib-color-bg: #4f78b0;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #4f78b0;color:#fff}.bg-gradient-purple-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #5764cb;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #5764cb;color:#fff}.bg-gradient-pink-blue{--bslib-color-fg: #fff;--bslib-color-bg: #a14987;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #a14987;color:#fff}.bg-gradient-pink-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #b42cb5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #b42cb5;color:#fff}.bg-gradient-pink-purple{--bslib-color-fg: #fff;--bslib-color-bg: #b840a1;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #b840a1;color:#fff}.bg-gradient-pink-red{--bslib-color-fg: #fff;--bslib-color-bg: #e8446c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #e8446c;color:#fff}.bg-gradient-pink-orange{--bslib-color-fg: #fff;--bslib-color-bg: #f0585c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #f0585c;color:#fff}.bg-gradient-pink-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #ec645b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #ec645b;color:#fff}.bg-gradient-pink-green{--bslib-color-fg: #fff;--bslib-color-bg: #8b708c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #8b708c;color:#fff}.bg-gradient-pink-teal{--bslib-color-fg: #fff;--bslib-color-bg: #987690;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #987690;color:#fff}.bg-gradient-pink-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #a062ac;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #a062ac;color:#fff}.bg-gradient-red-blue{--bslib-color-fg: #fff;--bslib-color-bg: #a15257;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #a15257;color:#fff}.bg-gradient-red-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #b33485;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #b33485;color:#fff}.bg-gradient-red-purple{--bslib-color-fg: #fff;--bslib-color-bg: #b74871;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #b74871;color:#fff}.bg-gradient-red-pink{--bslib-color-fg: #fff;--bslib-color-bg: #e7465c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #e7465c;color:#fff}.bg-gradient-red-orange{--bslib-color-fg: #fff;--bslib-color-bg: #f0602c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #f0602c;color:#fff}.bg-gradient-red-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #ec6c2b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #ec6c2b;color:#fff}.bg-gradient-red-green{--bslib-color-fg: #fff;--bslib-color-bg: #8b795c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #8b795c;color:#fff}.bg-gradient-red-teal{--bslib-color-fg: #fff;--bslib-color-bg: #977e60;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #977e60;color:#fff}.bg-gradient-red-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #9f6a7c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #9f6a7c;color:#fff}.bg-gradient-orange-blue{--bslib-color-fg: #fff;--bslib-color-bg: #ae703f;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #ae703f;color:#fff}.bg-gradient-orange-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #c1526d;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #c1526d;color:#fff}.bg-gradient-orange-purple{--bslib-color-fg: #fff;--bslib-color-bg: #c46659;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #c46659;color:#fff}.bg-gradient-orange-pink{--bslib-color-fg: #fff;--bslib-color-bg: #f56444;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #f56444;color:#fff}.bg-gradient-orange-red{--bslib-color-fg: #fff;--bslib-color-bg: #f46a24;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #f46a24;color:#fff}.bg-gradient-orange-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #f98a13;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #f98a13;color:#fff}.bg-gradient-orange-green{--bslib-color-fg: #fff;--bslib-color-bg: #989744;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #989744;color:#fff}.bg-gradient-orange-teal{--bslib-color-fg: #fff;--bslib-color-bg: #a59c48;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #a59c48;color:#fff}.bg-gradient-orange-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #ad8864;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #ad8864;color:#fff}.bg-gradient-yellow-blue{--bslib-color-fg: #fff;--bslib-color-bg: #a8823e;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #a8823e;color:#fff}.bg-gradient-yellow-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #bb646c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #bb646c;color:#fff}.bg-gradient-yellow-purple{--bslib-color-fg: #fff;--bslib-color-bg: #be7858;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #be7858;color:#fff}.bg-gradient-yellow-pink{--bslib-color-fg: #fff;--bslib-color-bg: #ef7643;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #ef7643;color:#fff}.bg-gradient-yellow-red{--bslib-color-fg: #fff;--bslib-color-bg: #ee7c23;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #ee7c23;color:#fff}.bg-gradient-yellow-orange{--bslib-color-fg: #fff;--bslib-color-bg: #f79013;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #f79013;color:#fff}.bg-gradient-yellow-green{--bslib-color-fg: #fff;--bslib-color-bg: #92a943;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #92a943;color:#fff}.bg-gradient-yellow-teal{--bslib-color-fg: #fff;--bslib-color-bg: #9fae47;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #9fae47;color:#fff}.bg-gradient-yellow-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #a79a62;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #a79a62;color:#fff}.bg-gradient-green-blue{--bslib-color-fg: #fff;--bslib-color-bg: #169587;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #169587;color:#fff}.bg-gradient-green-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #2977b5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #2977b5;color:#fff}.bg-gradient-green-purple{--bslib-color-fg: #fff;--bslib-color-bg: #2c8ba1;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #2c8ba1;color:#fff}.bg-gradient-green-pink{--bslib-color-fg: #fff;--bslib-color-bg: #5d8a8c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #5d8a8c;color:#fff}.bg-gradient-green-red{--bslib-color-fg: #fff;--bslib-color-bg: #5c8f6c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #5c8f6c;color:#fff}.bg-gradient-green-orange{--bslib-color-fg: #fff;--bslib-color-bg: #65a35c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #65a35c;color:#fff}.bg-gradient-green-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #61af5b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #61af5b;color:#fff}.bg-gradient-green-teal{--bslib-color-fg: #fff;--bslib-color-bg: #0dc190;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #0dc190;color:#fff}.bg-gradient-green-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #15aeac;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #15aeac;color:#fff}.bg-gradient-teal-blue{--bslib-color-fg: #fff;--bslib-color-bg: #299d8d;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #299d8d;color:#fff}.bg-gradient-teal-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #3c7fbb;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #3c7fbb;color:#fff}.bg-gradient-teal-purple{--bslib-color-fg: #fff;--bslib-color-bg: #4093a8;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #4093a8;color:#fff}.bg-gradient-teal-pink{--bslib-color-fg: #fff;--bslib-color-bg: #709193;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #709193;color:#fff}.bg-gradient-teal-red{--bslib-color-fg: #fff;--bslib-color-bg: #709773;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #709773;color:#fff}.bg-gradient-teal-orange{--bslib-color-fg: #fff;--bslib-color-bg: #78ab63;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #78ab63;color:#fff}.bg-gradient-teal-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #74b762;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #74b762;color:#fff}.bg-gradient-teal-green{--bslib-color-fg: #fff;--bslib-color-bg: #13c493;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #13c493;color:#fff}.bg-gradient-teal-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #28b5b2;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #28b5b2;color:#fff}.bg-gradient-cyan-blue{--bslib-color-fg: #fff;--bslib-color-bg: #357fb6;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #357fb6;color:#fff}.bg-gradient-cyan-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #4862e4;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #4862e4;color:#fff}.bg-gradient-cyan-purple{--bslib-color-fg: #fff;--bslib-color-bg: #4c76d1;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #4c76d1;color:#fff}.bg-gradient-cyan-pink{--bslib-color-fg: #fff;--bslib-color-bg: #7c74bb;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #7c74bb;color:#fff}.bg-gradient-cyan-red{--bslib-color-fg: #fff;--bslib-color-bg: #7c7a9b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #7c7a9b;color:#fff}.bg-gradient-cyan-orange{--bslib-color-fg: #fff;--bslib-color-bg: #848e8b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #848e8b;color:#fff}.bg-gradient-cyan-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #809a8b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #809a8b;color:#fff}.bg-gradient-cyan-green{--bslib-color-fg: #fff;--bslib-color-bg: #1fa6bb;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #1fa6bb;color:#fff}.bg-gradient-cyan-teal{--bslib-color-fg: #fff;--bslib-color-bg: #2cacc0;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #2cacc0;color:#fff}:root{--bslib-spacer: 1rem;--bslib-mb-spacer: var(--bslib-spacer, 1rem)}.bslib-mb-spacing{margin-bottom:var(--bslib-mb-spacer)}.bslib-gap-spacing{gap:var(--bslib-mb-spacer)}.bslib-gap-spacing>.bslib-mb-spacing,.bslib-gap-spacing>.form-group,.bslib-gap-spacing>p,.bslib-gap-spacing>pre{margin-bottom:0}.html-fill-container>.html-fill-item.bslib-mb-spacing{margin-bottom:0}.tab-content>.tab-pane.html-fill-container{display:none}.tab-content>.active.html-fill-container{display:flex}.tab-content.html-fill-container{padding:0}:root{--bslib-spacer: 1rem;--bslib-mb-spacer: var(--bslib-spacer, 1rem)}.bslib-mb-spacing{margin-bottom:var(--bslib-mb-spacer)}.bslib-gap-spacing{gap:var(--bslib-mb-spacer)}.bslib-gap-spacing>.bslib-mb-spacing,.bslib-gap-spacing>.form-group,.bslib-gap-spacing>p,.bslib-gap-spacing>pre{margin-bottom:0}.html-fill-container>.html-fill-item.bslib-mb-spacing{margin-bottom:0}.tab-content>.tab-pane.html-fill-container{display:none}.tab-content>.active.html-fill-container{display:flex}.tab-content.html-fill-container{padding:0}.bg-blue{--bslib-color-bg: #375a7f;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-blue{--bslib-color-fg: #375a7f;color:var(--bslib-color-fg)}.bg-indigo{--bslib-color-bg: #6610f2;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-indigo{--bslib-color-fg: #6610f2;color:var(--bslib-color-fg)}.bg-purple{--bslib-color-bg: #6f42c1;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-purple{--bslib-color-fg: #6f42c1;color:var(--bslib-color-fg)}.bg-pink{--bslib-color-bg: #e83e8c;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-pink{--bslib-color-fg: #e83e8c;color:var(--bslib-color-fg)}.bg-red{--bslib-color-bg: #e74c3c;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-red{--bslib-color-fg: #e74c3c;color:var(--bslib-color-fg)}.bg-orange{--bslib-color-bg: #fd7e14;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-orange{--bslib-color-fg: #fd7e14;color:var(--bslib-color-fg)}.bg-yellow{--bslib-color-bg: #f39c12;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-yellow{--bslib-color-fg: #f39c12;color:var(--bslib-color-fg)}.bg-green{--bslib-color-bg: #00bc8c;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-green{--bslib-color-fg: #00bc8c;color:var(--bslib-color-fg)}.bg-teal{--bslib-color-bg: #20c997;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-teal{--bslib-color-fg: #20c997;color:var(--bslib-color-fg)}.bg-cyan{--bslib-color-bg: #3498db;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-cyan{--bslib-color-fg: #3498db;color:var(--bslib-color-fg)}.text-default{--bslib-color-fg: #434343}.bg-default{--bslib-color-bg: #434343;--bslib-color-fg: #fff}.text-primary{--bslib-color-fg: #375a7f}.bg-primary{--bslib-color-bg: #375a7f;--bslib-color-fg: #fff}.text-secondary{--bslib-color-fg: #434343}.bg-secondary{--bslib-color-bg: #434343;--bslib-color-fg: #fff}.text-success{--bslib-color-fg: #00bc8c}.bg-success{--bslib-color-bg: #00bc8c;--bslib-color-fg: #fff}.text-info{--bslib-color-fg: #3498db}.bg-info{--bslib-color-bg: #3498db;--bslib-color-fg: #fff}.text-warning{--bslib-color-fg: #f39c12}.bg-warning{--bslib-color-bg: #f39c12;--bslib-color-fg: #fff}.text-danger{--bslib-color-fg: #e74c3c}.bg-danger{--bslib-color-bg: #e74c3c;--bslib-color-fg: #fff}.text-light{--bslib-color-fg: #6f6f6f}.bg-light{--bslib-color-bg: #6f6f6f;--bslib-color-fg: #fff}.text-dark{--bslib-color-fg: #2d2d2d}.bg-dark{--bslib-color-bg: #2d2d2d;--bslib-color-fg: #fff}.bg-gradient-blue-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #4a3cad;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #4a3cad;color:#fff}.bg-gradient-blue-purple{--bslib-color-fg: #fff;--bslib-color-bg: #4d5099;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #4d5099;color:#fff}.bg-gradient-blue-pink{--bslib-color-fg: #fff;--bslib-color-bg: #7e4f84;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #7e4f84;color:#fff}.bg-gradient-blue-red{--bslib-color-fg: #fff;--bslib-color-bg: #7d5464;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #7d5464;color:#fff}.bg-gradient-blue-orange{--bslib-color-fg: #fff;--bslib-color-bg: #866854;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #866854;color:#fff}.bg-gradient-blue-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #827453;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #827453;color:#fff}.bg-gradient-blue-green{--bslib-color-fg: #fff;--bslib-color-bg: #218184;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #218184;color:#fff}.bg-gradient-blue-teal{--bslib-color-fg: #fff;--bslib-color-bg: #2e8689;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #2e8689;color:#fff}.bg-gradient-blue-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #3673a4;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #3673a4;color:#fff}.bg-gradient-indigo-blue{--bslib-color-fg: #fff;--bslib-color-bg: #532ec4;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #532ec4;color:#fff}.bg-gradient-indigo-purple{--bslib-color-fg: #fff;--bslib-color-bg: #6a24de;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #6a24de;color:#fff}.bg-gradient-indigo-pink{--bslib-color-fg: #fff;--bslib-color-bg: #9a22c9;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #9a22c9;color:#fff}.bg-gradient-indigo-red{--bslib-color-fg: #fff;--bslib-color-bg: #9a28a9;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #9a28a9;color:#fff}.bg-gradient-indigo-orange{--bslib-color-fg: #fff;--bslib-color-bg: #a23c99;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #a23c99;color:#fff}.bg-gradient-indigo-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #9e4898;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #9e4898;color:#fff}.bg-gradient-indigo-green{--bslib-color-fg: #fff;--bslib-color-bg: #3d55c9;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #3d55c9;color:#fff}.bg-gradient-indigo-teal{--bslib-color-fg: #fff;--bslib-color-bg: #4a5ace;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #4a5ace;color:#fff}.bg-gradient-indigo-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #5246e9;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #5246e9;color:#fff}.bg-gradient-purple-blue{--bslib-color-fg: #fff;--bslib-color-bg: #594ca7;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #594ca7;color:#fff}.bg-gradient-purple-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #6b2ed5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #6b2ed5;color:#fff}.bg-gradient-purple-pink{--bslib-color-fg: #fff;--bslib-color-bg: #9f40ac;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #9f40ac;color:#fff}.bg-gradient-purple-red{--bslib-color-fg: #fff;--bslib-color-bg: #9f468c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #9f468c;color:#fff}.bg-gradient-purple-orange{--bslib-color-fg: #fff;--bslib-color-bg: #a85a7c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #a85a7c;color:#fff}.bg-gradient-purple-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #a4667b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #a4667b;color:#fff}.bg-gradient-purple-green{--bslib-color-fg: #fff;--bslib-color-bg: #4373ac;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #4373ac;color:#fff}.bg-gradient-purple-teal{--bslib-color-fg: #fff;--bslib-color-bg: #4f78b0;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #4f78b0;color:#fff}.bg-gradient-purple-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #5764cb;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #5764cb;color:#fff}.bg-gradient-pink-blue{--bslib-color-fg: #fff;--bslib-color-bg: #a14987;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #a14987;color:#fff}.bg-gradient-pink-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #b42cb5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #b42cb5;color:#fff}.bg-gradient-pink-purple{--bslib-color-fg: #fff;--bslib-color-bg: #b840a1;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #b840a1;color:#fff}.bg-gradient-pink-red{--bslib-color-fg: #fff;--bslib-color-bg: #e8446c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #e8446c;color:#fff}.bg-gradient-pink-orange{--bslib-color-fg: #fff;--bslib-color-bg: #f0585c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #f0585c;color:#fff}.bg-gradient-pink-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #ec645b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #ec645b;color:#fff}.bg-gradient-pink-green{--bslib-color-fg: #fff;--bslib-color-bg: #8b708c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #8b708c;color:#fff}.bg-gradient-pink-teal{--bslib-color-fg: #fff;--bslib-color-bg: #987690;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #987690;color:#fff}.bg-gradient-pink-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #a062ac;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #a062ac;color:#fff}.bg-gradient-red-blue{--bslib-color-fg: #fff;--bslib-color-bg: #a15257;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #a15257;color:#fff}.bg-gradient-red-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #b33485;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #b33485;color:#fff}.bg-gradient-red-purple{--bslib-color-fg: #fff;--bslib-color-bg: #b74871;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #b74871;color:#fff}.bg-gradient-red-pink{--bslib-color-fg: #fff;--bslib-color-bg: #e7465c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #e7465c;color:#fff}.bg-gradient-red-orange{--bslib-color-fg: #fff;--bslib-color-bg: #f0602c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #f0602c;color:#fff}.bg-gradient-red-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #ec6c2b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #ec6c2b;color:#fff}.bg-gradient-red-green{--bslib-color-fg: #fff;--bslib-color-bg: #8b795c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #8b795c;color:#fff}.bg-gradient-red-teal{--bslib-color-fg: #fff;--bslib-color-bg: #977e60;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #977e60;color:#fff}.bg-gradient-red-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #9f6a7c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #9f6a7c;color:#fff}.bg-gradient-orange-blue{--bslib-color-fg: #fff;--bslib-color-bg: #ae703f;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #ae703f;color:#fff}.bg-gradient-orange-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #c1526d;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #c1526d;color:#fff}.bg-gradient-orange-purple{--bslib-color-fg: #fff;--bslib-color-bg: #c46659;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #c46659;color:#fff}.bg-gradient-orange-pink{--bslib-color-fg: #fff;--bslib-color-bg: #f56444;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #f56444;color:#fff}.bg-gradient-orange-red{--bslib-color-fg: #fff;--bslib-color-bg: #f46a24;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #f46a24;color:#fff}.bg-gradient-orange-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #f98a13;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #f98a13;color:#fff}.bg-gradient-orange-green{--bslib-color-fg: #fff;--bslib-color-bg: #989744;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #989744;color:#fff}.bg-gradient-orange-teal{--bslib-color-fg: #fff;--bslib-color-bg: #a59c48;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #a59c48;color:#fff}.bg-gradient-orange-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #ad8864;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #ad8864;color:#fff}.bg-gradient-yellow-blue{--bslib-color-fg: #fff;--bslib-color-bg: #a8823e;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #a8823e;color:#fff}.bg-gradient-yellow-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #bb646c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #bb646c;color:#fff}.bg-gradient-yellow-purple{--bslib-color-fg: #fff;--bslib-color-bg: #be7858;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #be7858;color:#fff}.bg-gradient-yellow-pink{--bslib-color-fg: #fff;--bslib-color-bg: #ef7643;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #ef7643;color:#fff}.bg-gradient-yellow-red{--bslib-color-fg: #fff;--bslib-color-bg: #ee7c23;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #ee7c23;color:#fff}.bg-gradient-yellow-orange{--bslib-color-fg: #fff;--bslib-color-bg: #f79013;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #f79013;color:#fff}.bg-gradient-yellow-green{--bslib-color-fg: #fff;--bslib-color-bg: #92a943;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #92a943;color:#fff}.bg-gradient-yellow-teal{--bslib-color-fg: #fff;--bslib-color-bg: #9fae47;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #9fae47;color:#fff}.bg-gradient-yellow-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #a79a62;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #a79a62;color:#fff}.bg-gradient-green-blue{--bslib-color-fg: #fff;--bslib-color-bg: #169587;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #169587;color:#fff}.bg-gradient-green-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #2977b5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #2977b5;color:#fff}.bg-gradient-green-purple{--bslib-color-fg: #fff;--bslib-color-bg: #2c8ba1;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #2c8ba1;color:#fff}.bg-gradient-green-pink{--bslib-color-fg: #fff;--bslib-color-bg: #5d8a8c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #5d8a8c;color:#fff}.bg-gradient-green-red{--bslib-color-fg: #fff;--bslib-color-bg: #5c8f6c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #5c8f6c;color:#fff}.bg-gradient-green-orange{--bslib-color-fg: #fff;--bslib-color-bg: #65a35c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #65a35c;color:#fff}.bg-gradient-green-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #61af5b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #61af5b;color:#fff}.bg-gradient-green-teal{--bslib-color-fg: #fff;--bslib-color-bg: #0dc190;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #0dc190;color:#fff}.bg-gradient-green-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #15aeac;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #15aeac;color:#fff}.bg-gradient-teal-blue{--bslib-color-fg: #fff;--bslib-color-bg: #299d8d;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #299d8d;color:#fff}.bg-gradient-teal-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #3c7fbb;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #3c7fbb;color:#fff}.bg-gradient-teal-purple{--bslib-color-fg: #fff;--bslib-color-bg: #4093a8;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #4093a8;color:#fff}.bg-gradient-teal-pink{--bslib-color-fg: #fff;--bslib-color-bg: #709193;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #709193;color:#fff}.bg-gradient-teal-red{--bslib-color-fg: #fff;--bslib-color-bg: #709773;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #709773;color:#fff}.bg-gradient-teal-orange{--bslib-color-fg: #fff;--bslib-color-bg: #78ab63;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #78ab63;color:#fff}.bg-gradient-teal-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #74b762;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #74b762;color:#fff}.bg-gradient-teal-green{--bslib-color-fg: #fff;--bslib-color-bg: #13c493;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #13c493;color:#fff}.bg-gradient-teal-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #28b5b2;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #28b5b2;color:#fff}.bg-gradient-cyan-blue{--bslib-color-fg: #fff;--bslib-color-bg: #357fb6;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #357fb6;color:#fff}.bg-gradient-cyan-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #4862e4;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #4862e4;color:#fff}.bg-gradient-cyan-purple{--bslib-color-fg: #fff;--bslib-color-bg: #4c76d1;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #4c76d1;color:#fff}.bg-gradient-cyan-pink{--bslib-color-fg: #fff;--bslib-color-bg: #7c74bb;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #7c74bb;color:#fff}.bg-gradient-cyan-red{--bslib-color-fg: #fff;--bslib-color-bg: #7c7a9b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #7c7a9b;color:#fff}.bg-gradient-cyan-orange{--bslib-color-fg: #fff;--bslib-color-bg: #848e8b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #848e8b;color:#fff}.bg-gradient-cyan-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #809a8b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #809a8b;color:#fff}.bg-gradient-cyan-green{--bslib-color-fg: #fff;--bslib-color-bg: #1fa6bb;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #1fa6bb;color:#fff}.bg-gradient-cyan-teal{--bslib-color-fg: #fff;--bslib-color-bg: #2cacc0;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #2cacc0;color:#fff}:root{--bslib-value-box-shadow: none;--bslib-value-box-border-width-auto-yes: var(--bslib-value-box-border-width-baseline);--bslib-value-box-border-width-auto-no: 0;--bslib-value-box-border-width-baseline: 1px}.bslib-value-box{border-width:var(--bslib-value-box-border-width-auto-no, var(--bslib-value-box-border-width-baseline));container-name:bslib-value-box;container-type:inline-size}.bslib-value-box.card{box-shadow:var(--bslib-value-box-shadow)}.bslib-value-box.border-auto{border-width:var(--bslib-value-box-border-width-auto-yes, var(--bslib-value-box-border-width-baseline))}.bslib-value-box.default{--bslib-value-box-bg-default: var(--bs-card-bg, #222);--bslib-value-box-border-color-default: var(--bs-card-border-color, rgba(0, 0, 0, 0.175));color:var(--bslib-value-box-color);background-color:var(--bslib-value-box-bg, var(--bslib-value-box-bg-default));border-color:var(--bslib-value-box-border-color, var(--bslib-value-box-border-color-default))}.bslib-value-box .value-box-grid{display:grid;grid-template-areas:"left right";align-items:center;overflow:hidden}.bslib-value-box .value-box-showcase{height:100%;max-height:var(---bslib-value-box-showcase-max-h, 100%)}.bslib-value-box .value-box-showcase,.bslib-value-box .value-box-showcase>.html-fill-item{width:100%}.bslib-value-box[data-full-screen=true] .value-box-showcase{max-height:var(---bslib-value-box-showcase-max-h-fs, 100%)}@media screen and (min-width: 575.98px){@container bslib-value-box (max-width: 300px){.bslib-value-box:not(.showcase-bottom) .value-box-grid{grid-template-columns:1fr !important;grid-template-rows:auto auto;grid-template-areas:"top" "bottom"}.bslib-value-box:not(.showcase-bottom) .value-box-grid .value-box-showcase{grid-area:top !important}.bslib-value-box:not(.showcase-bottom) .value-box-grid .value-box-area{grid-area:bottom !important;justify-content:end}}}.bslib-value-box .value-box-area{justify-content:center;padding:1.5rem 1rem;font-size:.9rem;font-weight:500}.bslib-value-box .value-box-area *{margin-bottom:0;margin-top:0}.bslib-value-box .value-box-title{font-size:1rem;margin-top:0;margin-bottom:.5rem;font-weight:500;line-height:1.2}.bslib-value-box .value-box-title:empty::after{content:" "}.bslib-value-box .value-box-value{font-size:calc(1.29rem + 0.48vw);margin-top:0;margin-bottom:.5rem;font-weight:500;line-height:1.2}@media(min-width: 1200px){.bslib-value-box .value-box-value{font-size:1.65rem}}.bslib-value-box .value-box-value:empty::after{content:" "}.bslib-value-box .value-box-showcase{align-items:center;justify-content:center;margin-top:auto;margin-bottom:auto;padding:1rem}.bslib-value-box .value-box-showcase .bi,.bslib-value-box .value-box-showcase .fa,.bslib-value-box .value-box-showcase .fab,.bslib-value-box .value-box-showcase .fas,.bslib-value-box .value-box-showcase .far{opacity:.85;min-width:50px;max-width:125%}.bslib-value-box .value-box-showcase .bi,.bslib-value-box .value-box-showcase .fa,.bslib-value-box .value-box-showcase .fab,.bslib-value-box .value-box-showcase .fas,.bslib-value-box .value-box-showcase .far{font-size:4rem}.bslib-value-box.showcase-top-right .value-box-grid{grid-template-columns:1fr var(---bslib-value-box-showcase-w, 50%)}.bslib-value-box.showcase-top-right .value-box-grid .value-box-showcase{grid-area:right;margin-left:auto;align-self:start;align-items:end;padding-left:0;padding-bottom:0}.bslib-value-box.showcase-top-right .value-box-grid .value-box-area{grid-area:left;align-self:end}.bslib-value-box.showcase-top-right[data-full-screen=true] .value-box-grid{grid-template-columns:auto var(---bslib-value-box-showcase-w-fs, 1fr)}.bslib-value-box.showcase-top-right[data-full-screen=true] .value-box-grid>div{align-self:center}.bslib-value-box.showcase-top-right:not([data-full-screen=true]) .value-box-showcase{margin-top:0}@container bslib-value-box (max-width: 300px){.bslib-value-box.showcase-top-right:not([data-full-screen=true]) .value-box-grid .value-box-showcase{padding-left:1rem}}.bslib-value-box.showcase-left-center .value-box-grid{grid-template-columns:var(---bslib-value-box-showcase-w, 30%) auto}.bslib-value-box.showcase-left-center[data-full-screen=true] .value-box-grid{grid-template-columns:var(---bslib-value-box-showcase-w-fs, 1fr) auto}.bslib-value-box.showcase-left-center:not([data-fill-screen=true]) .value-box-grid .value-box-showcase{grid-area:left}.bslib-value-box.showcase-left-center:not([data-fill-screen=true]) .value-box-grid .value-box-area{grid-area:right}.bslib-value-box.showcase-bottom .value-box-grid{grid-template-columns:1fr;grid-template-rows:1fr var(---bslib-value-box-showcase-h, auto);grid-template-areas:"top" "bottom";overflow:hidden}.bslib-value-box.showcase-bottom .value-box-grid .value-box-showcase{grid-area:bottom;padding:0;margin:0}.bslib-value-box.showcase-bottom .value-box-grid .value-box-area{grid-area:top}.bslib-value-box.showcase-bottom[data-full-screen=true] .value-box-grid{grid-template-rows:1fr var(---bslib-value-box-showcase-h-fs, 2fr)}.bslib-value-box.showcase-bottom[data-full-screen=true] .value-box-grid .value-box-showcase{padding:1rem}[data-bs-theme=dark] .bslib-value-box{--bslib-value-box-shadow: 0 0.5rem 1rem rgb(0 0 0 / 50%)}.accordion .accordion-header{font-size:calc(1.29rem + 0.48vw);margin-top:0;margin-bottom:.5rem;font-weight:500;line-height:1.2;color:var(--bs-heading-color);margin-bottom:0}@media(min-width: 1200px){.accordion .accordion-header{font-size:1.65rem}}.accordion .accordion-icon:not(:empty){margin-right:.75rem;display:flex}.accordion .accordion-button:not(.collapsed){box-shadow:none}.accordion .accordion-button:not(.collapsed):focus{box-shadow:var(--bs-accordion-btn-focus-box-shadow)}.bslib-grid{display:grid !important;gap:var(--bslib-spacer, 1rem);height:var(--bslib-grid-height)}.bslib-grid.grid{grid-template-columns:repeat(var(--bs-columns, 12), minmax(0, 1fr));grid-template-rows:unset;grid-auto-rows:var(--bslib-grid--row-heights);--bslib-grid--row-heights--xs: unset;--bslib-grid--row-heights--sm: unset;--bslib-grid--row-heights--md: unset;--bslib-grid--row-heights--lg: unset;--bslib-grid--row-heights--xl: unset;--bslib-grid--row-heights--xxl: unset}.bslib-grid.grid.bslib-grid--row-heights--xs{--bslib-grid--row-heights: var(--bslib-grid--row-heights--xs)}@media(min-width: 576px){.bslib-grid.grid.bslib-grid--row-heights--sm{--bslib-grid--row-heights: var(--bslib-grid--row-heights--sm)}}@media(min-width: 768px){.bslib-grid.grid.bslib-grid--row-heights--md{--bslib-grid--row-heights: var(--bslib-grid--row-heights--md)}}@media(min-width: 992px){.bslib-grid.grid.bslib-grid--row-heights--lg{--bslib-grid--row-heights: var(--bslib-grid--row-heights--lg)}}@media(min-width: 1200px){.bslib-grid.grid.bslib-grid--row-heights--xl{--bslib-grid--row-heights: var(--bslib-grid--row-heights--xl)}}@media(min-width: 1400px){.bslib-grid.grid.bslib-grid--row-heights--xxl{--bslib-grid--row-heights: var(--bslib-grid--row-heights--xxl)}}.bslib-grid>*>.shiny-input-container{width:100%}.bslib-grid-item{grid-column:auto/span 1}@media(max-width: 767.98px){.bslib-grid-item{grid-column:1/-1}}@media(max-width: 575.98px){.bslib-grid{grid-template-columns:1fr !important;height:var(--bslib-grid-height-mobile)}.bslib-grid.grid{height:unset !important;grid-auto-rows:var(--bslib-grid--row-heights--xs, auto)}}.navbar+.container-fluid:has(>.tab-content>.tab-pane.active.html-fill-container),.navbar+.container-sm:has(>.tab-content>.tab-pane.active.html-fill-container),.navbar+.container-md:has(>.tab-content>.tab-pane.active.html-fill-container),.navbar+.container-lg:has(>.tab-content>.tab-pane.active.html-fill-container),.navbar+.container-xl:has(>.tab-content>.tab-pane.active.html-fill-container),.navbar+.container-xxl:has(>.tab-content>.tab-pane.active.html-fill-container){padding-left:0;padding-right:0}.navbar+.container-fluid>.tab-content>.tab-pane.active.html-fill-container,.navbar+.container-sm>.tab-content>.tab-pane.active.html-fill-container,.navbar+.container-md>.tab-content>.tab-pane.active.html-fill-container,.navbar+.container-lg>.tab-content>.tab-pane.active.html-fill-container,.navbar+.container-xl>.tab-content>.tab-pane.active.html-fill-container,.navbar+.container-xxl>.tab-content>.tab-pane.active.html-fill-container{padding:var(--bslib-spacer, 1rem);gap:var(--bslib-spacer, 1rem)}.navbar+.container-fluid>.tab-content>.tab-pane.active.html-fill-container:has(>.bslib-sidebar-layout:only-child),.navbar+.container-sm>.tab-content>.tab-pane.active.html-fill-container:has(>.bslib-sidebar-layout:only-child),.navbar+.container-md>.tab-content>.tab-pane.active.html-fill-container:has(>.bslib-sidebar-layout:only-child),.navbar+.container-lg>.tab-content>.tab-pane.active.html-fill-container:has(>.bslib-sidebar-layout:only-child),.navbar+.container-xl>.tab-content>.tab-pane.active.html-fill-container:has(>.bslib-sidebar-layout:only-child),.navbar+.container-xxl>.tab-content>.tab-pane.active.html-fill-container:has(>.bslib-sidebar-layout:only-child){padding:0}.navbar+.container-fluid>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border=true]),.navbar+.container-sm>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border=true]),.navbar+.container-md>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border=true]),.navbar+.container-lg>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border=true]),.navbar+.container-xl>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border=true]),.navbar+.container-xxl>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border=true]){border-left:none;border-right:none;border-bottom:none}.navbar+.container-fluid>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border-radius=true]),.navbar+.container-sm>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border-radius=true]),.navbar+.container-md>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border-radius=true]),.navbar+.container-lg>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border-radius=true]),.navbar+.container-xl>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border-radius=true]),.navbar+.container-xxl>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border-radius=true]){border-radius:0}.navbar+div>.bslib-sidebar-layout{border-top:var(--bslib-sidebar-border)}:root{--bslib-page-sidebar-title-bg: #375a7f;--bslib-page-sidebar-title-color: #fff}.bslib-page-title{background-color:var(--bslib-page-sidebar-title-bg);color:var(--bslib-page-sidebar-title-color);font-size:1.25rem;font-weight:300;padding:var(--bslib-spacer, 1rem);padding-left:1.5rem;margin-bottom:0;border-bottom:1px solid #dee2e6}@media(min-width: 576px){.nav:not(.nav-hidden){display:flex !important;display:-webkit-flex !important}.nav:not(.nav-hidden):not(.nav-stacked):not(.flex-column){float:none !important}.nav:not(.nav-hidden):not(.nav-stacked):not(.flex-column)>.bslib-nav-spacer{margin-left:auto !important}.nav:not(.nav-hidden):not(.nav-stacked):not(.flex-column)>.form-inline{margin-top:auto;margin-bottom:auto}.nav:not(.nav-hidden).nav-stacked{flex-direction:column;-webkit-flex-direction:column;height:100%}.nav:not(.nav-hidden).nav-stacked>.bslib-nav-spacer{margin-top:auto !important}}.bslib-sidebar-layout{--bslib-sidebar-transition-duration: 500ms;--bslib-sidebar-transition-easing-x: cubic-bezier(0.8, 0.78, 0.22, 1.07);--bslib-sidebar-border: var(--bs-card-border-width, 1px) solid var(--bs-card-border-color, rgba(0, 0, 0, 0.175));--bslib-sidebar-border-radius: var(--bs-border-radius);--bslib-sidebar-vert-border: var(--bs-card-border-width, 1px) solid var(--bs-card-border-color, rgba(0, 0, 0, 0.175));--bslib-sidebar-bg: rgba(var(--bs-emphasis-color-rgb, 0, 0, 0), 0.05);--bslib-sidebar-fg: var(--bs-emphasis-color, black);--bslib-sidebar-main-fg: var(--bs-card-color, var(--bs-body-color));--bslib-sidebar-main-bg: var(--bs-card-bg, var(--bs-body-bg));--bslib-sidebar-toggle-bg: rgba(var(--bs-emphasis-color-rgb, 0, 0, 0), 0.1);--bslib-sidebar-padding: calc(var(--bslib-spacer) * 1.5);--bslib-sidebar-icon-size: var(--bslib-spacer, 1rem);--bslib-sidebar-icon-button-size: calc(var(--bslib-sidebar-icon-size, 1rem) * 2);--bslib-sidebar-padding-icon: calc(var(--bslib-sidebar-icon-button-size, 2rem) * 1.5);--bslib-collapse-toggle-border-radius: var(--bs-border-radius, 0.25rem);--bslib-collapse-toggle-transform: 0deg;--bslib-sidebar-toggle-transition-easing: cubic-bezier(1, 0, 0, 1);--bslib-collapse-toggle-right-transform: 180deg;--bslib-sidebar-column-main: minmax(0, 1fr);display:grid !important;grid-template-columns:min(100% - var(--bslib-sidebar-icon-size),var(--bslib-sidebar-width, 250px)) var(--bslib-sidebar-column-main);position:relative;transition:grid-template-columns ease-in-out var(--bslib-sidebar-transition-duration);border:var(--bslib-sidebar-border);border-radius:var(--bslib-sidebar-border-radius)}@media(prefers-reduced-motion: reduce){.bslib-sidebar-layout{transition:none}}.bslib-sidebar-layout[data-bslib-sidebar-border=false]{border:none}.bslib-sidebar-layout[data-bslib-sidebar-border-radius=false]{border-radius:initial}.bslib-sidebar-layout>.main,.bslib-sidebar-layout>.sidebar{grid-row:1/2;border-radius:inherit;overflow:auto}.bslib-sidebar-layout>.main{grid-column:2/3;border-top-left-radius:0;border-bottom-left-radius:0;padding:var(--bslib-sidebar-padding);transition:padding var(--bslib-sidebar-transition-easing-x) var(--bslib-sidebar-transition-duration);color:var(--bslib-sidebar-main-fg);background-color:var(--bslib-sidebar-main-bg)}.bslib-sidebar-layout>.sidebar{grid-column:1/2;width:100%;height:100%;border-right:var(--bslib-sidebar-vert-border);border-top-right-radius:0;border-bottom-right-radius:0;color:var(--bslib-sidebar-fg);background-color:var(--bslib-sidebar-bg);backdrop-filter:blur(5px)}.bslib-sidebar-layout>.sidebar>.sidebar-content{display:flex;flex-direction:column;gap:var(--bslib-spacer, 1rem);padding:var(--bslib-sidebar-padding);padding-top:var(--bslib-sidebar-padding-icon)}.bslib-sidebar-layout>.sidebar>.sidebar-content>:last-child:not(.sidebar-title){margin-bottom:0}.bslib-sidebar-layout>.sidebar>.sidebar-content>.accordion{margin-left:calc(-1*var(--bslib-sidebar-padding));margin-right:calc(-1*var(--bslib-sidebar-padding))}.bslib-sidebar-layout>.sidebar>.sidebar-content>.accordion:last-child{margin-bottom:calc(-1*var(--bslib-sidebar-padding))}.bslib-sidebar-layout>.sidebar>.sidebar-content>.accordion:not(:last-child){margin-bottom:1rem}.bslib-sidebar-layout>.sidebar>.sidebar-content>.accordion .accordion-body{display:flex;flex-direction:column}.bslib-sidebar-layout>.sidebar>.sidebar-content>.accordion:not(:first-child) .accordion-item:first-child{border-top:var(--bs-accordion-border-width) solid var(--bs-accordion-border-color)}.bslib-sidebar-layout>.sidebar>.sidebar-content>.accordion:not(:last-child) .accordion-item:last-child{border-bottom:var(--bs-accordion-border-width) solid var(--bs-accordion-border-color)}.bslib-sidebar-layout>.sidebar>.sidebar-content.has-accordion>.sidebar-title{border-bottom:none;padding-bottom:0}.bslib-sidebar-layout>.sidebar .shiny-input-container{width:100%}.bslib-sidebar-layout[data-bslib-sidebar-open=always]>.sidebar>.sidebar-content{padding-top:var(--bslib-sidebar-padding)}.bslib-sidebar-layout>.collapse-toggle{grid-row:1/2;grid-column:1/2;display:inline-flex;align-items:center;position:absolute;right:calc(var(--bslib-sidebar-icon-size));top:calc(var(--bslib-sidebar-icon-size, 1rem)/2);border:none;border-radius:var(--bslib-collapse-toggle-border-radius);height:var(--bslib-sidebar-icon-button-size, 2rem);width:var(--bslib-sidebar-icon-button-size, 2rem);display:flex;align-items:center;justify-content:center;padding:0;color:var(--bslib-sidebar-fg);background-color:unset;transition:color var(--bslib-sidebar-transition-easing-x) var(--bslib-sidebar-transition-duration),top var(--bslib-sidebar-transition-easing-x) var(--bslib-sidebar-transition-duration),right var(--bslib-sidebar-transition-easing-x) var(--bslib-sidebar-transition-duration),left var(--bslib-sidebar-transition-easing-x) var(--bslib-sidebar-transition-duration)}.bslib-sidebar-layout>.collapse-toggle:hover{background-color:var(--bslib-sidebar-toggle-bg)}.bslib-sidebar-layout>.collapse-toggle>.collapse-icon{opacity:.8;width:var(--bslib-sidebar-icon-size);height:var(--bslib-sidebar-icon-size);transform:rotateY(var(--bslib-collapse-toggle-transform));transition:transform var(--bslib-sidebar-toggle-transition-easing) var(--bslib-sidebar-transition-duration)}.bslib-sidebar-layout>.collapse-toggle:hover>.collapse-icon{opacity:1}.bslib-sidebar-layout .sidebar-title{font-size:1.25rem;line-height:1.25;margin-top:0;margin-bottom:1rem;padding-bottom:1rem;border-bottom:var(--bslib-sidebar-border)}.bslib-sidebar-layout.sidebar-right{grid-template-columns:var(--bslib-sidebar-column-main) min(100% - var(--bslib-sidebar-icon-size),var(--bslib-sidebar-width, 250px))}.bslib-sidebar-layout.sidebar-right>.main{grid-column:1/2;border-top-right-radius:0;border-bottom-right-radius:0;border-top-left-radius:inherit;border-bottom-left-radius:inherit}.bslib-sidebar-layout.sidebar-right>.sidebar{grid-column:2/3;border-right:none;border-left:var(--bslib-sidebar-vert-border);border-top-left-radius:0;border-bottom-left-radius:0}.bslib-sidebar-layout.sidebar-right>.collapse-toggle{grid-column:2/3;left:var(--bslib-sidebar-icon-size);right:unset;border:var(--bslib-collapse-toggle-border)}.bslib-sidebar-layout.sidebar-right>.collapse-toggle>.collapse-icon{transform:rotateY(var(--bslib-collapse-toggle-right-transform))}.bslib-sidebar-layout.sidebar-collapsed{--bslib-collapse-toggle-transform: 180deg;--bslib-collapse-toggle-right-transform: 0deg;--bslib-sidebar-vert-border: none;grid-template-columns:0 minmax(0, 1fr)}.bslib-sidebar-layout.sidebar-collapsed.sidebar-right{grid-template-columns:minmax(0, 1fr) 0}.bslib-sidebar-layout.sidebar-collapsed:not(.transitioning)>.sidebar>*{display:none}.bslib-sidebar-layout.sidebar-collapsed>.main{border-radius:inherit}.bslib-sidebar-layout.sidebar-collapsed:not(.sidebar-right)>.main{padding-left:var(--bslib-sidebar-padding-icon)}.bslib-sidebar-layout.sidebar-collapsed.sidebar-right>.main{padding-right:var(--bslib-sidebar-padding-icon)}.bslib-sidebar-layout.sidebar-collapsed>.collapse-toggle{color:var(--bslib-sidebar-main-fg);top:calc(var(--bslib-sidebar-overlap-counter, 0)*(var(--bslib-sidebar-icon-size) + var(--bslib-sidebar-padding)) + var(--bslib-sidebar-icon-size, 1rem)/2);right:calc(-2.5*var(--bslib-sidebar-icon-size) - var(--bs-card-border-width, 1px))}.bslib-sidebar-layout.sidebar-collapsed.sidebar-right>.collapse-toggle{left:calc(-2.5*var(--bslib-sidebar-icon-size) - var(--bs-card-border-width, 1px));right:unset}@media(min-width: 576px){.bslib-sidebar-layout.transitioning>.sidebar>.sidebar-content{display:none}}@media(max-width: 575.98px){.bslib-sidebar-layout[data-bslib-sidebar-open=desktop]{--bslib-sidebar-js-init-collapsed: true}.bslib-sidebar-layout>.sidebar,.bslib-sidebar-layout.sidebar-right>.sidebar{border:none}.bslib-sidebar-layout>.main,.bslib-sidebar-layout.sidebar-right>.main{grid-column:1/3}.bslib-sidebar-layout[data-bslib-sidebar-open=always]{display:block !important}.bslib-sidebar-layout[data-bslib-sidebar-open=always]>.sidebar{max-height:var(--bslib-sidebar-max-height-mobile);overflow-y:auto;border-top:var(--bslib-sidebar-vert-border)}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]){grid-template-columns:100% 0}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]):not(.sidebar-collapsed)>.sidebar{z-index:1}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]):not(.sidebar-collapsed)>.collapse-toggle{z-index:1}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]).sidebar-right{grid-template-columns:0 100%}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]).sidebar-collapsed{grid-template-columns:0 100%}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]).sidebar-collapsed.sidebar-right{grid-template-columns:100% 0}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]):not(.sidebar-right)>.main{padding-left:var(--bslib-sidebar-padding-icon)}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]).sidebar-right>.main{padding-right:var(--bslib-sidebar-padding-icon)}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always])>.main{opacity:0;transition:opacity var(--bslib-sidebar-transition-easing-x) var(--bslib-sidebar-transition-duration)}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]).sidebar-collapsed>.main{opacity:1}}.bslib-card{overflow:auto}.bslib-card .card-body+.card-body{padding-top:0}.bslib-card .card-body{overflow:auto}.bslib-card .card-body p{margin-top:0}.bslib-card .card-body p:last-child{margin-bottom:0}.bslib-card .card-body{max-height:var(--bslib-card-body-max-height, none)}.bslib-card[data-full-screen=true]>.card-body{max-height:var(--bslib-card-body-max-height-full-screen, none)}.bslib-card .card-header .form-group{margin-bottom:0}.bslib-card .card-header .selectize-control{margin-bottom:0}.bslib-card .card-header .selectize-control .item{margin-right:1.15rem}.bslib-card .card-footer{margin-top:auto}.bslib-card .bslib-navs-card-title{display:flex;flex-wrap:wrap;justify-content:space-between;align-items:center}.bslib-card .bslib-navs-card-title .nav{margin-left:auto}.bslib-card .bslib-sidebar-layout:not([data-bslib-sidebar-border=true]){border:none}.bslib-card .bslib-sidebar-layout:not([data-bslib-sidebar-border-radius=true]){border-top-left-radius:0;border-top-right-radius:0}[data-full-screen=true]{position:fixed;inset:3.5rem 1rem 1rem;height:auto !important;max-height:none !important;width:auto !important;z-index:1070}.bslib-full-screen-enter{display:none;position:absolute;bottom:var(--bslib-full-screen-enter-bottom, 0.2rem);right:var(--bslib-full-screen-enter-right, 0);top:var(--bslib-full-screen-enter-top);left:var(--bslib-full-screen-enter-left);color:var(--bslib-color-fg, var(--bs-card-color));background-color:var(--bslib-color-bg, var(--bs-card-bg, var(--bs-body-bg)));border:var(--bs-card-border-width) solid var(--bslib-color-fg, var(--bs-card-border-color));box-shadow:0 2px 4px rgba(0,0,0,.15);margin:.2rem .4rem;padding:.55rem !important;font-size:.8rem;cursor:pointer;opacity:.7;z-index:1070}.bslib-full-screen-enter:hover{opacity:1}.card[data-full-screen=false]:hover>*>.bslib-full-screen-enter{display:block}.bslib-has-full-screen .card:hover>*>.bslib-full-screen-enter{display:none}@media(max-width: 575.98px){.bslib-full-screen-enter{display:none !important}}.bslib-full-screen-exit{position:relative;top:1.35rem;font-size:.9rem;cursor:pointer;text-decoration:none;display:flex;float:right;margin-right:2.15rem;align-items:center;color:rgba(var(--bs-body-bg-rgb), 0.8)}.bslib-full-screen-exit:hover{color:rgba(var(--bs-body-bg-rgb), 1)}.bslib-full-screen-exit svg{margin-left:.5rem;font-size:1.5rem}#bslib-full-screen-overlay{position:fixed;inset:0;background-color:rgba(var(--bs-body-color-rgb), 0.6);backdrop-filter:blur(2px);-webkit-backdrop-filter:blur(2px);z-index:1069;animation:bslib-full-screen-overlay-enter 400ms cubic-bezier(0.6, 0.02, 0.65, 1) forwards}@keyframes bslib-full-screen-overlay-enter{0%{opacity:0}100%{opacity:1}}html{height:100%}.bslib-page-fill{width:100%;height:100%;margin:0;padding:var(--bslib-spacer, 1rem);gap:var(--bslib-spacer, 1rem)}@media(max-width: 575.98px){.bslib-page-fill{height:var(--bslib-page-fill-mobile-height, auto)}}.html-fill-container{display:flex;flex-direction:column;min-height:0;min-width:0}.html-fill-container>.html-fill-item{flex:1 1 auto;min-height:0;min-width:0}.html-fill-container>:not(.html-fill-item){flex:0 0 auto}.sidebar-item .chapter-number{color:#fff}.quarto-container{min-height:calc(100vh - 132px)}body.hypothesis-enabled #quarto-header{margin-right:16px}footer.footer .nav-footer,#quarto-header>nav{padding-left:1em;padding-right:1em}footer.footer div.nav-footer p:first-child{margin-top:0}footer.footer div.nav-footer p:last-child{margin-bottom:0}#quarto-content>*{padding-top:14px}#quarto-content>#quarto-sidebar-glass{padding-top:0px}@media(max-width: 991.98px){#quarto-content>*{padding-top:0}#quarto-content .subtitle{padding-top:14px}#quarto-content section:first-of-type h2:first-of-type,#quarto-content section:first-of-type .h2:first-of-type{margin-top:1rem}}.headroom-target,header.headroom{will-change:transform;transition:position 200ms linear;transition:all 200ms linear}header.headroom--pinned{transform:translateY(0%)}header.headroom--unpinned{transform:translateY(-100%)}.navbar-container{width:100%}.navbar-brand{overflow:hidden;text-overflow:ellipsis}.navbar-brand-container{max-width:calc(100% - 115px);min-width:0;display:flex;align-items:center}@media(min-width: 992px){.navbar-brand-container{margin-right:1em}}.navbar-brand.navbar-brand-logo{margin-right:4px;display:inline-flex}.navbar-toggler{flex-basis:content;flex-shrink:0}.navbar .navbar-brand-container{order:2}.navbar .navbar-toggler{order:1}.navbar .navbar-container>.navbar-nav{order:20}.navbar .navbar-container>.navbar-brand-container{margin-left:0 !important;margin-right:0 !important}.navbar .navbar-collapse{order:20}.navbar #quarto-search{order:4;margin-left:auto}.navbar .navbar-toggler{margin-right:.5em}.navbar-collapse .quarto-navbar-tools{margin-left:.5em}.navbar-logo{max-height:24px;width:auto;padding-right:4px}nav .nav-item:not(.compact){padding-top:1px}nav .nav-link i,nav .dropdown-item i{padding-right:1px}.navbar-expand-lg .navbar-nav .nav-link{padding-left:.6rem;padding-right:.6rem}nav .nav-item.compact .nav-link{padding-left:.5rem;padding-right:.5rem;font-size:1.1rem}.navbar .quarto-navbar-tools{order:3}.navbar .quarto-navbar-tools div.dropdown{display:inline-block}.navbar .quarto-navbar-tools .quarto-navigation-tool{color:#dee2e6}.navbar .quarto-navbar-tools .quarto-navigation-tool:hover{color:#fff}.navbar-nav .dropdown-menu{min-width:220px;font-size:.9rem}.navbar .navbar-nav .nav-link.dropdown-toggle::after{opacity:.75;vertical-align:.175em}.navbar ul.dropdown-menu{padding-top:0;padding-bottom:0}.navbar .dropdown-header{text-transform:uppercase;font-size:.8rem;padding:0 .5rem}.navbar .dropdown-item{padding:.4rem .5rem}.navbar .dropdown-item>i.bi{margin-left:.1rem;margin-right:.25em}.sidebar #quarto-search{margin-top:-1px}.sidebar #quarto-search svg.aa-SubmitIcon{width:16px;height:16px}.sidebar-navigation a{color:inherit}.sidebar-title{margin-top:.25rem;padding-bottom:.5rem;font-size:1.3rem;line-height:1.6rem;visibility:visible}.sidebar-title>a{font-size:inherit;text-decoration:none}.sidebar-title .sidebar-tools-main{margin-top:-6px}@media(max-width: 991.98px){#quarto-sidebar div.sidebar-header{padding-top:.2em}}.sidebar-header-stacked .sidebar-title{margin-top:.6rem}.sidebar-logo{max-width:90%;padding-bottom:.5rem}.sidebar-logo-link{text-decoration:none}.sidebar-navigation li a{text-decoration:none}.sidebar-navigation .quarto-navigation-tool{opacity:.7;font-size:.875rem}#quarto-sidebar>nav>.sidebar-tools-main{margin-left:14px}.sidebar-tools-main{display:inline-flex;margin-left:0px;order:2}.sidebar-tools-main:not(.tools-wide){vertical-align:middle}.sidebar-navigation .quarto-navigation-tool.dropdown-toggle::after{display:none}.sidebar.sidebar-navigation>*{padding-top:1em}.sidebar-item{margin-bottom:.2em;line-height:1rem;margin-top:.4rem}.sidebar-section{padding-left:.5em;padding-bottom:.2em}.sidebar-item .sidebar-item-container{display:flex;justify-content:space-between;cursor:pointer}.sidebar-item-toggle:hover{cursor:pointer}.sidebar-item .sidebar-item-toggle .bi{font-size:.7rem;text-align:center}.sidebar-item .sidebar-item-toggle .bi-chevron-right::before{transition:transform 200ms ease}.sidebar-item .sidebar-item-toggle[aria-expanded=false] .bi-chevron-right::before{transform:none}.sidebar-item .sidebar-item-toggle[aria-expanded=true] .bi-chevron-right::before{transform:rotate(90deg)}.sidebar-item-text{width:100%}.sidebar-navigation .sidebar-divider{margin-left:0;margin-right:0;margin-top:.5rem;margin-bottom:.5rem}@media(max-width: 991.98px){.quarto-secondary-nav{display:block}.quarto-secondary-nav button.quarto-search-button{padding-right:0em;padding-left:2em}.quarto-secondary-nav button.quarto-btn-toggle{margin-left:-0.75rem;margin-right:.15rem}.quarto-secondary-nav nav.quarto-title-breadcrumbs{display:none}.quarto-secondary-nav nav.quarto-page-breadcrumbs{display:flex;align-items:center;padding-right:1em;margin-left:-0.25em}.quarto-secondary-nav nav.quarto-page-breadcrumbs a{text-decoration:none}.quarto-secondary-nav nav.quarto-page-breadcrumbs ol.breadcrumb{margin-bottom:0}}@media(min-width: 992px){.quarto-secondary-nav{display:none}}.quarto-title-breadcrumbs .breadcrumb{margin-bottom:.5em;font-size:.9rem}.quarto-title-breadcrumbs .breadcrumb li:last-of-type a{color:#6c757d}.quarto-secondary-nav .quarto-btn-toggle{color:#adadad}.quarto-secondary-nav[aria-expanded=false] .quarto-btn-toggle .bi-chevron-right::before{transform:none}.quarto-secondary-nav[aria-expanded=true] .quarto-btn-toggle .bi-chevron-right::before{transform:rotate(90deg)}.quarto-secondary-nav .quarto-btn-toggle .bi-chevron-right::before{transition:transform 200ms ease}.quarto-secondary-nav{cursor:pointer}.no-decor{text-decoration:none}.quarto-secondary-nav-title{margin-top:.3em;color:#adadad;padding-top:4px}.quarto-secondary-nav nav.quarto-page-breadcrumbs{color:#adadad}.quarto-secondary-nav nav.quarto-page-breadcrumbs a{color:#adadad}.quarto-secondary-nav nav.quarto-page-breadcrumbs a:hover{color:rgba(26,195,152,.8)}.quarto-secondary-nav nav.quarto-page-breadcrumbs .breadcrumb-item::before{color:#7a7a7a}.breadcrumb-item{line-height:1.2rem}div.sidebar-item-container{color:#adadad}div.sidebar-item-container:hover,div.sidebar-item-container:focus{color:rgba(26,195,152,.8)}div.sidebar-item-container.disabled{color:rgba(173,173,173,.75)}div.sidebar-item-container .active,div.sidebar-item-container .show>.nav-link,div.sidebar-item-container .sidebar-link>code{color:#1ac398}div.sidebar.sidebar-navigation.rollup.quarto-sidebar-toggle-contents,nav.sidebar.sidebar-navigation:not(.rollup){background-color:#222}@media(max-width: 991.98px){.sidebar-navigation .sidebar-item a,.nav-page .nav-page-text,.sidebar-navigation{font-size:1rem}.sidebar-navigation ul.sidebar-section.depth1 .sidebar-section-item{font-size:1.1rem}.sidebar-logo{display:none}.sidebar.sidebar-navigation{position:static;border-bottom:1px solid #434343}.sidebar.sidebar-navigation.collapsing{position:fixed;z-index:1000}.sidebar.sidebar-navigation.show{position:fixed;z-index:1000}.sidebar.sidebar-navigation{min-height:100%}nav.quarto-secondary-nav{background-color:#222;border-bottom:1px solid #434343}.quarto-banner nav.quarto-secondary-nav{background-color:#375a7f;color:#dee2e6;border-top:1px solid #434343}.sidebar .sidebar-footer{visibility:visible;padding-top:1rem;position:inherit}.sidebar-tools-collapse{display:block}}#quarto-sidebar{transition:width .15s ease-in}#quarto-sidebar>*{padding-right:1em}@media(max-width: 991.98px){#quarto-sidebar .sidebar-menu-container{white-space:nowrap;min-width:225px}#quarto-sidebar.show{transition:width .15s ease-out}}@media(min-width: 992px){#quarto-sidebar{display:flex;flex-direction:column}.nav-page .nav-page-text,.sidebar-navigation .sidebar-section .sidebar-item{font-size:.875rem}.sidebar-navigation .sidebar-item{font-size:.925rem}.sidebar.sidebar-navigation{display:block;position:sticky}.sidebar-search{width:100%}.sidebar .sidebar-footer{visibility:visible}}@media(min-width: 992px){#quarto-sidebar-glass{display:none}}@media(max-width: 991.98px){#quarto-sidebar-glass{position:fixed;top:0;bottom:0;left:0;right:0;background-color:rgba(255,255,255,0);transition:background-color .15s ease-in;z-index:-1}#quarto-sidebar-glass.collapsing{z-index:1000}#quarto-sidebar-glass.show{transition:background-color .15s ease-out;background-color:rgba(102,102,102,.4);z-index:1000}}.sidebar .sidebar-footer{padding:.5rem 1rem;align-self:flex-end;color:#6c757d;width:100%}.quarto-page-breadcrumbs .breadcrumb-item+.breadcrumb-item,.quarto-page-breadcrumbs .breadcrumb-item{padding-right:.33em;padding-left:0}.quarto-page-breadcrumbs .breadcrumb-item::before{padding-right:.33em}.quarto-sidebar-footer{font-size:.875em}.sidebar-section .bi-chevron-right{vertical-align:middle}.sidebar-section .bi-chevron-right::before{font-size:.9em}.notransition{-webkit-transition:none !important;-moz-transition:none !important;-o-transition:none !important;transition:none !important}.btn:focus:not(:focus-visible){box-shadow:none}.page-navigation{display:flex;justify-content:space-between}.nav-page{padding-bottom:.75em}.nav-page .bi{font-size:1.8rem;vertical-align:middle}.nav-page .nav-page-text{padding-left:.25em;padding-right:.25em}.nav-page a{color:#6c757d;text-decoration:none;display:flex;align-items:center}.nav-page a:hover{color:#009670}.nav-footer .toc-actions{padding-bottom:.5em;padding-top:.5em}.nav-footer .toc-actions a,.nav-footer .toc-actions a:hover{text-decoration:none}.nav-footer .toc-actions ul{display:flex;list-style:none}.nav-footer .toc-actions ul :first-child{margin-left:auto}.nav-footer .toc-actions ul :last-child{margin-right:auto}.nav-footer .toc-actions ul li{padding-right:1.5em}.nav-footer .toc-actions ul li i.bi{padding-right:.4em}.nav-footer .toc-actions ul li:last-of-type{padding-right:0}.nav-footer{display:flex;flex-direction:row;flex-wrap:wrap;justify-content:space-between;align-items:baseline;text-align:center;padding-top:.5rem;padding-bottom:.5rem;background-color:#222}body.nav-fixed{padding-top:82px}.nav-footer-contents{color:#6c757d;margin-top:.25rem}.nav-footer{min-height:3.5em;color:#8a8a8a}.nav-footer a{color:#8a8a8a}.nav-footer .nav-footer-left{font-size:.825em}.nav-footer .nav-footer-center{font-size:.825em}.nav-footer .nav-footer-right{font-size:.825em}.nav-footer-left .footer-items,.nav-footer-center .footer-items,.nav-footer-right .footer-items{display:inline-flex;padding-top:.3em;padding-bottom:.3em;margin-bottom:0em}.nav-footer-left .footer-items .nav-link,.nav-footer-center .footer-items .nav-link,.nav-footer-right .footer-items .nav-link{padding-left:.6em;padding-right:.6em}@media(min-width: 768px){.nav-footer-left{flex:1 1 0px;text-align:left}}@media(max-width: 575.98px){.nav-footer-left{margin-bottom:1em;flex:100%}}@media(min-width: 768px){.nav-footer-right{flex:1 1 0px;text-align:right}}@media(max-width: 575.98px){.nav-footer-right{margin-bottom:1em;flex:100%}}.nav-footer-center{text-align:center;min-height:3em}@media(min-width: 768px){.nav-footer-center{flex:1 1 0px}}.nav-footer-center .footer-items{justify-content:center}@media(max-width: 767.98px){.nav-footer-center{margin-bottom:1em;flex:100%}}@media(max-width: 767.98px){.nav-footer-center{margin-top:3em;order:10}}.navbar .quarto-reader-toggle.reader .quarto-reader-toggle-btn{background-color:#dee2e6;border-radius:3px}@media(max-width: 991.98px){.quarto-reader-toggle{display:none}}.quarto-reader-toggle.reader.quarto-navigation-tool .quarto-reader-toggle-btn{background-color:#adadad;border-radius:3px}.quarto-reader-toggle .quarto-reader-toggle-btn{display:inline-flex;padding-left:.2em;padding-right:.2em;margin-left:-0.2em;margin-right:-0.2em;text-align:center}.navbar .quarto-reader-toggle:not(.reader) .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(222, 226, 230, 1)" class="bi bi-body-text" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M0 .5A.5.5 0 0 1 .5 0h4a.5.5 0 0 1 0 1h-4A.5.5 0 0 1 0 .5Zm0 2A.5.5 0 0 1 .5 2h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm9 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-9 2A.5.5 0 0 1 .5 4h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm5 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm-12 2A.5.5 0 0 1 .5 6h6a.5.5 0 0 1 0 1h-6a.5.5 0 0 1-.5-.5Zm8 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-8 2A.5.5 0 0 1 .5 8h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm-7 2a.5.5 0 0 1 .5-.5h8a.5.5 0 0 1 0 1h-8a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h4a.5.5 0 0 1 0 1h-4a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h2a.5.5 0 0 1 0 1h-2a.5.5 0 0 1-.5-.5Z"/></svg>')}.navbar .quarto-reader-toggle.reader .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(55, 90, 127, 1)" class="bi bi-body-text" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M0 .5A.5.5 0 0 1 .5 0h4a.5.5 0 0 1 0 1h-4A.5.5 0 0 1 0 .5Zm0 2A.5.5 0 0 1 .5 2h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm9 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-9 2A.5.5 0 0 1 .5 4h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm5 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm-12 2A.5.5 0 0 1 .5 6h6a.5.5 0 0 1 0 1h-6a.5.5 0 0 1-.5-.5Zm8 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-8 2A.5.5 0 0 1 .5 8h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm-7 2a.5.5 0 0 1 .5-.5h8a.5.5 0 0 1 0 1h-8a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h4a.5.5 0 0 1 0 1h-4a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h2a.5.5 0 0 1 0 1h-2a.5.5 0 0 1-.5-.5Z"/></svg>')}.sidebar-navigation .quarto-reader-toggle:not(.reader) .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(173, 173, 173, 1)" class="bi bi-body-text" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M0 .5A.5.5 0 0 1 .5 0h4a.5.5 0 0 1 0 1h-4A.5.5 0 0 1 0 .5Zm0 2A.5.5 0 0 1 .5 2h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm9 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-9 2A.5.5 0 0 1 .5 4h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm5 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm-12 2A.5.5 0 0 1 .5 6h6a.5.5 0 0 1 0 1h-6a.5.5 0 0 1-.5-.5Zm8 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-8 2A.5.5 0 0 1 .5 8h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm-7 2a.5.5 0 0 1 .5-.5h8a.5.5 0 0 1 0 1h-8a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h4a.5.5 0 0 1 0 1h-4a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h2a.5.5 0 0 1 0 1h-2a.5.5 0 0 1-.5-.5Z"/></svg>')}.sidebar-navigation .quarto-reader-toggle.reader .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(34, 34, 34, 1)" class="bi bi-body-text" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M0 .5A.5.5 0 0 1 .5 0h4a.5.5 0 0 1 0 1h-4A.5.5 0 0 1 0 .5Zm0 2A.5.5 0 0 1 .5 2h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm9 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-9 2A.5.5 0 0 1 .5 4h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm5 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm-12 2A.5.5 0 0 1 .5 6h6a.5.5 0 0 1 0 1h-6a.5.5 0 0 1-.5-.5Zm8 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-8 2A.5.5 0 0 1 .5 8h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm-7 2a.5.5 0 0 1 .5-.5h8a.5.5 0 0 1 0 1h-8a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h4a.5.5 0 0 1 0 1h-4a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h2a.5.5 0 0 1 0 1h-2a.5.5 0 0 1-.5-.5Z"/></svg>')}#quarto-back-to-top{display:none;position:fixed;bottom:50px;background-color:#222;border-radius:.25rem;box-shadow:0 .2rem .5rem #6c757d,0 0 .05rem #6c757d;color:#6c757d;text-decoration:none;font-size:.9em;text-align:center;left:50%;padding:.4rem .8rem;transform:translate(-50%, 0)}#quarto-announcement{padding:.5em;display:flex;justify-content:space-between;margin-bottom:0;font-size:.9em}#quarto-announcement .quarto-announcement-content{margin-right:auto}#quarto-announcement .quarto-announcement-content p{margin-bottom:0}#quarto-announcement .quarto-announcement-icon{margin-right:.5em;font-size:1.2em;margin-top:-0.15em}#quarto-announcement .quarto-announcement-action{cursor:pointer}.aa-DetachedSearchButtonQuery{display:none}.aa-DetachedOverlay ul.aa-List,#quarto-search-results ul.aa-List{list-style:none;padding-left:0}.aa-DetachedOverlay .aa-Panel,#quarto-search-results .aa-Panel{background-color:#222;position:absolute;z-index:2000}#quarto-search-results .aa-Panel{max-width:400px}#quarto-search input{font-size:.925rem}@media(min-width: 992px){.navbar #quarto-search{margin-left:.25rem;order:999}}.navbar.navbar-expand-sm #quarto-search,.navbar.navbar-expand-md #quarto-search{order:999}@media(min-width: 992px){.navbar .quarto-navbar-tools{order:900}}@media(min-width: 992px){.navbar .quarto-navbar-tools.tools-end{margin-left:auto !important}}@media(max-width: 991.98px){#quarto-sidebar .sidebar-search{display:none}}#quarto-sidebar .sidebar-search .aa-Autocomplete{width:100%}.navbar .aa-Autocomplete .aa-Form{width:180px}.navbar #quarto-search.type-overlay .aa-Autocomplete{width:40px}.navbar #quarto-search.type-overlay .aa-Autocomplete .aa-Form{background-color:inherit;border:none}.navbar #quarto-search.type-overlay .aa-Autocomplete .aa-Form:focus-within{box-shadow:none;outline:none}.navbar #quarto-search.type-overlay .aa-Autocomplete .aa-Form .aa-InputWrapper{display:none}.navbar #quarto-search.type-overlay .aa-Autocomplete .aa-Form .aa-InputWrapper:focus-within{display:inherit}.navbar #quarto-search.type-overlay .aa-Autocomplete .aa-Form .aa-Label svg,.navbar #quarto-search.type-overlay .aa-Autocomplete .aa-Form .aa-LoadingIndicator svg{width:26px;height:26px;color:#dee2e6;opacity:1}.navbar #quarto-search.type-overlay .aa-Autocomplete svg.aa-SubmitIcon{width:26px;height:26px;color:#dee2e6;opacity:1}.aa-Autocomplete .aa-Form,.aa-DetachedFormContainer .aa-Form{align-items:center;background-color:#fff;border:1px solid #adb5bd;border-radius:.25rem;color:#2d2d2d;display:flex;line-height:1em;margin:0;position:relative;width:100%}.aa-Autocomplete .aa-Form:focus-within,.aa-DetachedFormContainer .aa-Form:focus-within{box-shadow:rgba(55,90,127,.6) 0 0 0 1px;outline:currentColor none medium}.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix{align-items:center;display:flex;flex-shrink:0;order:1}.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix .aa-Label,.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix .aa-Label,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator{cursor:initial;flex-shrink:0;padding:0;text-align:left}.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix .aa-Label svg,.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator svg,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix .aa-Label svg,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator svg{color:#2d2d2d;opacity:.5}.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix .aa-SubmitButton,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix .aa-SubmitButton{appearance:none;background:none;border:0;margin:0}.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator{align-items:center;display:flex;justify-content:center}.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator[hidden],.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator[hidden]{display:none}.aa-Autocomplete .aa-Form .aa-InputWrapper,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper{order:3;position:relative;width:100%}.aa-Autocomplete .aa-Form .aa-InputWrapper .aa-Input,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input{appearance:none;background:none;border:0;color:#2d2d2d;font:inherit;height:calc(1.5em + .1rem + 2px);padding:0;width:100%}.aa-Autocomplete .aa-Form .aa-InputWrapper .aa-Input::placeholder,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input::placeholder{color:#2d2d2d;opacity:.8}.aa-Autocomplete .aa-Form .aa-InputWrapper .aa-Input:focus,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input:focus{border-color:none;box-shadow:none;outline:none}.aa-Autocomplete .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-decoration,.aa-Autocomplete .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-cancel-button,.aa-Autocomplete .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-results-button,.aa-Autocomplete .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-results-decoration,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-decoration,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-cancel-button,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-results-button,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-results-decoration{display:none}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix{align-items:center;display:flex;order:4}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-ClearButton,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-ClearButton{align-items:center;background:none;border:0;color:#2d2d2d;opacity:.8;cursor:pointer;display:flex;margin:0;width:calc(1.5em + .1rem + 2px)}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-ClearButton:hover,.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-ClearButton:focus,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-ClearButton:hover,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-ClearButton:focus{color:#2d2d2d;opacity:.8}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-ClearButton[hidden],.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-ClearButton[hidden]{display:none}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-ClearButton svg,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-ClearButton svg{width:calc(1.5em + 0.75rem + calc(1px * 2))}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-CopyButton,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-CopyButton{border:none;align-items:center;background:none;color:#2d2d2d;opacity:.4;font-size:.7rem;cursor:pointer;display:none;margin:0;width:calc(1em + .1rem + 2px)}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-CopyButton:hover,.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-CopyButton:focus,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-CopyButton:hover,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-CopyButton:focus{color:#2d2d2d;opacity:.8}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-CopyButton[hidden],.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-CopyButton[hidden]{display:none}.aa-PanelLayout:empty{display:none}.quarto-search-no-results.no-query{display:none}.aa-Source:has(.no-query){display:none}#quarto-search-results .aa-Panel{border:solid #adb5bd 1px}#quarto-search-results .aa-SourceNoResults{width:398px}.aa-DetachedOverlay .aa-Panel,#quarto-search-results .aa-Panel{max-height:65vh;overflow-y:auto;font-size:.925rem}.aa-DetachedOverlay .aa-SourceNoResults,#quarto-search-results .aa-SourceNoResults{height:60px;display:flex;justify-content:center;align-items:center}.aa-DetachedOverlay .search-error,#quarto-search-results .search-error{padding-top:10px;padding-left:20px;padding-right:20px;cursor:default}.aa-DetachedOverlay .search-error .search-error-title,#quarto-search-results .search-error .search-error-title{font-size:1.1rem;margin-bottom:.5rem}.aa-DetachedOverlay .search-error .search-error-title .search-error-icon,#quarto-search-results .search-error .search-error-title .search-error-icon{margin-right:8px}.aa-DetachedOverlay .search-error .search-error-text,#quarto-search-results .search-error .search-error-text{font-weight:300}.aa-DetachedOverlay .search-result-text,#quarto-search-results .search-result-text{font-weight:300;overflow:hidden;text-overflow:ellipsis;display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;line-height:1.2rem;max-height:2.4rem}.aa-DetachedOverlay .aa-SourceHeader .search-result-header,#quarto-search-results .aa-SourceHeader .search-result-header{font-size:.875rem;background-color:#2f2f2f;padding-left:14px;padding-bottom:4px;padding-top:4px}.aa-DetachedOverlay .aa-SourceHeader .search-result-header-no-results,#quarto-search-results .aa-SourceHeader .search-result-header-no-results{display:none}.aa-DetachedOverlay .aa-SourceFooter .algolia-search-logo,#quarto-search-results .aa-SourceFooter .algolia-search-logo{width:110px;opacity:.85;margin:8px;float:right}.aa-DetachedOverlay .search-result-section,#quarto-search-results .search-result-section{font-size:.925em}.aa-DetachedOverlay a.search-result-link,#quarto-search-results a.search-result-link{color:inherit;text-decoration:none}.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item,#quarto-search-results li.aa-Item[aria-selected=true] .search-item{background-color:#375a7f}.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item.search-result-more,.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item .search-result-section,.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item .search-result-text,.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item .search-result-title-container,.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item .search-result-text-container,#quarto-search-results li.aa-Item[aria-selected=true] .search-item.search-result-more,#quarto-search-results li.aa-Item[aria-selected=true] .search-item .search-result-section,#quarto-search-results li.aa-Item[aria-selected=true] .search-item .search-result-text,#quarto-search-results li.aa-Item[aria-selected=true] .search-item .search-result-title-container,#quarto-search-results li.aa-Item[aria-selected=true] .search-item .search-result-text-container{color:#fff;background-color:#375a7f}.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item mark.search-match,.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item .search-match.mark,#quarto-search-results li.aa-Item[aria-selected=true] .search-item mark.search-match,#quarto-search-results li.aa-Item[aria-selected=true] .search-item .search-match.mark{color:#fff;background-color:#2b4663}.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item,#quarto-search-results li.aa-Item[aria-selected=false] .search-item{background-color:#2d2d2d}.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item.search-result-more,.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item .search-result-section,.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item .search-result-text,.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item .search-result-title-container,.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item .search-result-text-container,#quarto-search-results li.aa-Item[aria-selected=false] .search-item.search-result-more,#quarto-search-results li.aa-Item[aria-selected=false] .search-item .search-result-section,#quarto-search-results li.aa-Item[aria-selected=false] .search-item .search-result-text,#quarto-search-results li.aa-Item[aria-selected=false] .search-item .search-result-title-container,#quarto-search-results li.aa-Item[aria-selected=false] .search-item .search-result-text-container{color:#fff}.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item mark.search-match,.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item .search-match.mark,#quarto-search-results li.aa-Item[aria-selected=false] .search-item mark.search-match,#quarto-search-results li.aa-Item[aria-selected=false] .search-item .search-match.mark{color:inherit;background-color:#000}.aa-DetachedOverlay .aa-Item .search-result-doc:not(.document-selectable) .search-result-title-container,#quarto-search-results .aa-Item .search-result-doc:not(.document-selectable) .search-result-title-container{background-color:#2d2d2d;color:#fff}.aa-DetachedOverlay .aa-Item .search-result-doc:not(.document-selectable) .search-result-text-container,#quarto-search-results .aa-Item .search-result-doc:not(.document-selectable) .search-result-text-container{padding-top:0px}.aa-DetachedOverlay li.aa-Item .search-result-doc.document-selectable .search-result-text-container,#quarto-search-results li.aa-Item .search-result-doc.document-selectable .search-result-text-container{margin-top:-4px}.aa-DetachedOverlay .aa-Item,#quarto-search-results .aa-Item{cursor:pointer}.aa-DetachedOverlay .aa-Item .search-item,#quarto-search-results .aa-Item .search-item{border-left:none;border-right:none;border-top:none;background-color:#2d2d2d;border-color:#adb5bd;color:#fff}.aa-DetachedOverlay .aa-Item .search-item p,#quarto-search-results .aa-Item .search-item p{margin-top:0;margin-bottom:0}.aa-DetachedOverlay .aa-Item .search-item i.bi,#quarto-search-results .aa-Item .search-item i.bi{padding-left:8px;padding-right:8px;font-size:1.3em}.aa-DetachedOverlay .aa-Item .search-item .search-result-title,#quarto-search-results .aa-Item .search-item .search-result-title{margin-top:.3em;margin-bottom:0em}.aa-DetachedOverlay .aa-Item .search-item .search-result-crumbs,#quarto-search-results .aa-Item .search-item .search-result-crumbs{white-space:nowrap;text-overflow:ellipsis;font-size:.8em;font-weight:300;margin-right:1em}.aa-DetachedOverlay .aa-Item .search-item .search-result-crumbs:not(.search-result-crumbs-wrap),#quarto-search-results .aa-Item .search-item .search-result-crumbs:not(.search-result-crumbs-wrap){max-width:30%;margin-left:auto;margin-top:.5em;margin-bottom:.1rem}.aa-DetachedOverlay .aa-Item .search-item .search-result-crumbs.search-result-crumbs-wrap,#quarto-search-results .aa-Item .search-item .search-result-crumbs.search-result-crumbs-wrap{flex-basis:100%;margin-top:0em;margin-bottom:.2em;margin-left:37px}.aa-DetachedOverlay .aa-Item .search-result-title-container,#quarto-search-results .aa-Item .search-result-title-container{font-size:1em;display:flex;flex-wrap:wrap;padding:6px 4px 6px 4px}.aa-DetachedOverlay .aa-Item .search-result-text-container,#quarto-search-results .aa-Item .search-result-text-container{padding-bottom:8px;padding-right:8px;margin-left:42px}.aa-DetachedOverlay .aa-Item .search-result-doc-section,.aa-DetachedOverlay .aa-Item .search-result-more,#quarto-search-results .aa-Item .search-result-doc-section,#quarto-search-results .aa-Item .search-result-more{padding-top:8px;padding-bottom:8px;padding-left:44px}.aa-DetachedOverlay .aa-Item .search-result-more,#quarto-search-results .aa-Item .search-result-more{font-size:.8em;font-weight:400}.aa-DetachedOverlay .aa-Item .search-result-doc,#quarto-search-results .aa-Item .search-result-doc{border-top:1px solid #adb5bd}.aa-DetachedSearchButton{background:none;border:none}.aa-DetachedSearchButton .aa-DetachedSearchButtonPlaceholder{display:none}.navbar .aa-DetachedSearchButton .aa-DetachedSearchButtonIcon{color:#dee2e6}.sidebar-tools-collapse #quarto-search,.sidebar-tools-main #quarto-search{display:inline}.sidebar-tools-collapse #quarto-search .aa-Autocomplete,.sidebar-tools-main #quarto-search .aa-Autocomplete{display:inline}.sidebar-tools-collapse #quarto-search .aa-DetachedSearchButton,.sidebar-tools-main #quarto-search .aa-DetachedSearchButton{padding-left:4px;padding-right:4px}.sidebar-tools-collapse #quarto-search .aa-DetachedSearchButton .aa-DetachedSearchButtonIcon,.sidebar-tools-main #quarto-search .aa-DetachedSearchButton .aa-DetachedSearchButtonIcon{color:#adadad}.sidebar-tools-collapse #quarto-search .aa-DetachedSearchButton .aa-DetachedSearchButtonIcon .aa-SubmitIcon,.sidebar-tools-main #quarto-search .aa-DetachedSearchButton .aa-DetachedSearchButtonIcon .aa-SubmitIcon{margin-top:-3px}.aa-DetachedContainer{background:rgba(34,34,34,.65);width:90%;bottom:0;box-shadow:rgba(173,181,189,.6) 0 0 0 1px;outline:currentColor none medium;display:flex;flex-direction:column;left:0;margin:0;overflow:hidden;padding:0;position:fixed;right:0;top:0;z-index:1101}.aa-DetachedContainer::after{height:32px}.aa-DetachedContainer .aa-SourceHeader{margin:var(--aa-spacing-half) 0 var(--aa-spacing-half) 2px}.aa-DetachedContainer .aa-Panel{background-color:#222;border-radius:0;box-shadow:none;flex-grow:1;margin:0;padding:0;position:relative}.aa-DetachedContainer .aa-PanelLayout{bottom:0;box-shadow:none;left:0;margin:0;max-height:none;overflow-y:auto;position:absolute;right:0;top:0;width:100%}.aa-DetachedFormContainer{background-color:#222;border-bottom:1px solid #adb5bd;display:flex;flex-direction:row;justify-content:space-between;margin:0;padding:.5em}.aa-DetachedCancelButton{background:none;font-size:.8em;border:0;border-radius:3px;color:#fff;cursor:pointer;margin:0 0 0 .5em;padding:0 .5em}.aa-DetachedCancelButton:hover,.aa-DetachedCancelButton:focus{box-shadow:rgba(55,90,127,.6) 0 0 0 1px;outline:currentColor none medium}.aa-DetachedContainer--modal{bottom:inherit;height:auto;margin:0 auto;position:absolute;top:100px;border-radius:6px;max-width:850px}@media(max-width: 575.98px){.aa-DetachedContainer--modal{width:100%;top:0px;border-radius:0px;border:none}}.aa-DetachedContainer--modal .aa-PanelLayout{max-height:var(--aa-detached-modal-max-height);padding-bottom:var(--aa-spacing-half);position:static}.aa-Detached{height:100vh;overflow:hidden}.aa-DetachedOverlay{background-color:rgba(255,255,255,.4);position:fixed;left:0;right:0;top:0;margin:0;padding:0;height:100vh;z-index:1100}.quarto-dashboard.nav-fixed.dashboard-sidebar #quarto-content.quarto-dashboard-content{padding:0em}.quarto-dashboard #quarto-content.quarto-dashboard-content{padding:1em}.quarto-dashboard #quarto-content.quarto-dashboard-content>*{padding-top:0}@media(min-width: 576px){.quarto-dashboard{height:100%}}.quarto-dashboard .card.valuebox.bslib-card.bg-primary{background-color:#375a7f !important}.quarto-dashboard .card.valuebox.bslib-card.bg-secondary{background-color:#434343 !important}.quarto-dashboard .card.valuebox.bslib-card.bg-success{background-color:#00bc8c !important}.quarto-dashboard .card.valuebox.bslib-card.bg-info{background-color:#3498db !important}.quarto-dashboard .card.valuebox.bslib-card.bg-warning{background-color:#f39c12 !important}.quarto-dashboard .card.valuebox.bslib-card.bg-danger{background-color:#e74c3c !important}.quarto-dashboard .card.valuebox.bslib-card.bg-light{background-color:#6f6f6f !important}.quarto-dashboard .card.valuebox.bslib-card.bg-dark{background-color:#2d2d2d !important}.quarto-dashboard.dashboard-fill{display:flex;flex-direction:column}.quarto-dashboard #quarto-appendix{display:none}.quarto-dashboard #quarto-header #quarto-dashboard-header{border-top:solid 1px #4673a3;border-bottom:solid 1px #4673a3}.quarto-dashboard #quarto-header #quarto-dashboard-header>nav{padding-left:1em;padding-right:1em}.quarto-dashboard #quarto-header #quarto-dashboard-header>nav .navbar-brand-container{padding-left:0}.quarto-dashboard #quarto-header #quarto-dashboard-header .navbar-toggler{margin-right:0}.quarto-dashboard #quarto-header #quarto-dashboard-header .navbar-toggler-icon{height:1em;width:1em;background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(222, 226, 230)" class="bi bi-menu-button-wide" viewBox="0 0 16 16"><path d="M0 1.5A1.5 1.5 0 0 1 1.5 0h13A1.5 1.5 0 0 1 16 1.5v2A1.5 1.5 0 0 1 14.5 5h-13A1.5 1.5 0 0 1 0 3.5v-2zM1.5 1a.5.5 0 0 0-.5.5v2a.5.5 0 0 0 .5.5h13a.5.5 0 0 0 .5-.5v-2a.5.5 0 0 0-.5-.5h-13z"/><path d="M2 2.5a.5.5 0 0 1 .5-.5h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5zm10.823.323-.396-.396A.25.25 0 0 1 12.604 2h.792a.25.25 0 0 1 .177.427l-.396.396a.25.25 0 0 1-.354 0zM0 8a2 2 0 0 1 2-2h12a2 2 0 0 1 2 2v5a2 2 0 0 1-2 2H2a2 2 0 0 1-2-2V8zm1 3v2a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-2H1zm14-1V8a1 1 0 0 0-1-1H2a1 1 0 0 0-1 1v2h14zM2 8.5a.5.5 0 0 1 .5-.5h9a.5.5 0 0 1 0 1h-9a.5.5 0 0 1-.5-.5zm0 4a.5.5 0 0 1 .5-.5h6a.5.5 0 0 1 0 1h-6a.5.5 0 0 1-.5-.5z"/></svg>')}.quarto-dashboard #quarto-header #quarto-dashboard-header .navbar-brand-container{padding-right:1em}.quarto-dashboard #quarto-header #quarto-dashboard-header .navbar-title{font-size:1.1em}.quarto-dashboard #quarto-header #quarto-dashboard-header .navbar-nav{font-size:.9em}.quarto-dashboard #quarto-dashboard-header .navbar{padding:0}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-container{padding-left:1em}.quarto-dashboard #quarto-dashboard-header .navbar.slim .navbar-brand-container .nav-link,.quarto-dashboard #quarto-dashboard-header .navbar.slim .navbar-nav .nav-link{padding:.7em}.quarto-dashboard #quarto-dashboard-header .navbar .quarto-color-scheme-toggle{order:9}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-toggler{margin-left:.5em;order:10}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-nav .nav-link{padding:.5em;height:100%;display:flex;align-items:center}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-nav .active{background-color:#436e9b}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-brand-container{padding:.5em .5em .5em 0;display:flex;flex-direction:row;margin-right:2em;align-items:center}@media(max-width: 767.98px){.quarto-dashboard #quarto-dashboard-header .navbar .navbar-brand-container{margin-right:auto}}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-collapse{align-self:stretch}@media(min-width: 768px){.quarto-dashboard #quarto-dashboard-header .navbar .navbar-collapse{order:8}}@media(max-width: 767.98px){.quarto-dashboard #quarto-dashboard-header .navbar .navbar-collapse{order:1000;padding-bottom:.5em}}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-collapse .navbar-nav{align-self:stretch}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-title{font-size:1.25em;line-height:1.1em;display:flex;flex-direction:row;flex-wrap:wrap;align-items:baseline}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-title .navbar-title-text{margin-right:.4em}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-title a{text-decoration:none;color:inherit}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-subtitle,.quarto-dashboard #quarto-dashboard-header .navbar .navbar-author{font-size:.9rem;margin-right:.5em}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-author{margin-left:auto}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-logo{max-height:48px;min-height:30px;object-fit:cover;margin-right:1em}.quarto-dashboard #quarto-dashboard-header .navbar .quarto-dashboard-links{order:9;padding-right:1em}.quarto-dashboard #quarto-dashboard-header .navbar .quarto-dashboard-link-text{margin-left:.25em}.quarto-dashboard #quarto-dashboard-header .navbar .quarto-dashboard-link{padding-right:0em;padding-left:.7em;text-decoration:none;color:#dee2e6}.quarto-dashboard .page-layout-custom .tab-content{padding:0;border:none}.quarto-dashboard-img-contain{height:100%;width:100%;object-fit:contain}@media(max-width: 575.98px){.quarto-dashboard .bslib-grid{grid-template-rows:minmax(1em, max-content) !important}.quarto-dashboard .sidebar-content{height:inherit}.quarto-dashboard .page-layout-custom{min-height:100vh}}.quarto-dashboard.dashboard-toolbar>.page-layout-custom,.quarto-dashboard.dashboard-sidebar>.page-layout-custom{padding:0}.quarto-dashboard .quarto-dashboard-content.quarto-dashboard-pages{padding:0}.quarto-dashboard .callout{margin-bottom:0;margin-top:0}.quarto-dashboard .html-fill-container figure{overflow:hidden}.quarto-dashboard bslib-tooltip .rounded-pill{border:solid #6c757d 1px}.quarto-dashboard bslib-tooltip .rounded-pill .svg{fill:#fff}.quarto-dashboard .tabset .dashboard-card-no-title .nav-tabs{margin-left:0;margin-right:auto}.quarto-dashboard .tabset .tab-content{border:none}.quarto-dashboard .tabset .card-header .nav-link[role=tab]{margin-top:-6px;padding-top:6px;padding-bottom:6px}.quarto-dashboard .card.valuebox,.quarto-dashboard .card.bslib-value-box{min-height:3rem}.quarto-dashboard .card.valuebox .card-body,.quarto-dashboard .card.bslib-value-box .card-body{padding:0}.quarto-dashboard .bslib-value-box .value-box-value{font-size:clamp(.1em,15cqw,5em)}.quarto-dashboard .bslib-value-box .value-box-showcase .bi{font-size:clamp(.1em,max(18cqw,5.2cqh),5em);text-align:center;height:1em}.quarto-dashboard .bslib-value-box .value-box-showcase .bi::before{vertical-align:1em}.quarto-dashboard .bslib-value-box .value-box-area{margin-top:auto;margin-bottom:auto}.quarto-dashboard .card figure.quarto-float{display:flex;flex-direction:column;align-items:center}.quarto-dashboard .dashboard-scrolling{padding:1em}.quarto-dashboard .full-height{height:100%}.quarto-dashboard .showcase-bottom .value-box-grid{display:grid;grid-template-columns:1fr;grid-template-rows:1fr auto;grid-template-areas:"top" "bottom"}.quarto-dashboard .showcase-bottom .value-box-grid .value-box-showcase{grid-area:bottom;padding:0;margin:0}.quarto-dashboard .showcase-bottom .value-box-grid .value-box-showcase i.bi{font-size:4rem}.quarto-dashboard .showcase-bottom .value-box-grid .value-box-area{grid-area:top}.quarto-dashboard .tab-content{margin-bottom:0}.quarto-dashboard .bslib-card .bslib-navs-card-title{justify-content:stretch;align-items:end}.quarto-dashboard .card-header{display:flex;flex-wrap:wrap;justify-content:space-between}.quarto-dashboard .card-header .card-title{display:flex;flex-direction:column;justify-content:center;margin-bottom:0}.quarto-dashboard .tabset .card-toolbar{margin-bottom:1em}.quarto-dashboard .bslib-grid>.bslib-sidebar-layout{border:none;gap:var(--bslib-spacer, 1rem)}.quarto-dashboard .bslib-grid>.bslib-sidebar-layout>.main{padding:0}.quarto-dashboard .bslib-grid>.bslib-sidebar-layout>.sidebar{border-radius:.25rem;border:1px solid rgba(0,0,0,.175)}.quarto-dashboard .bslib-grid>.bslib-sidebar-layout>.collapse-toggle{display:none}@media(max-width: 767.98px){.quarto-dashboard .bslib-grid>.bslib-sidebar-layout{grid-template-columns:1fr;grid-template-rows:max-content 1fr}.quarto-dashboard .bslib-grid>.bslib-sidebar-layout>.main{grid-column:1;grid-row:2}.quarto-dashboard .bslib-grid>.bslib-sidebar-layout .sidebar{grid-column:1;grid-row:1}}.quarto-dashboard .sidebar-right .sidebar{padding-left:2.5em}.quarto-dashboard .sidebar-right .collapse-toggle{left:2px}.quarto-dashboard .quarto-dashboard .sidebar-right button.collapse-toggle:not(.transitioning){left:unset}.quarto-dashboard aside.sidebar{padding-left:1em;padding-right:1em;background-color:rgba(52,58,64,.25);color:#fff}.quarto-dashboard .bslib-sidebar-layout>div.main{padding:.7em}.quarto-dashboard .bslib-sidebar-layout button.collapse-toggle{margin-top:.3em}.quarto-dashboard .bslib-sidebar-layout .collapse-toggle{top:0}.quarto-dashboard .bslib-sidebar-layout.sidebar-collapsed:not(.transitioning):not(.sidebar-right) .collapse-toggle{left:2px}.quarto-dashboard .sidebar>section>.h3:first-of-type{margin-top:0em}.quarto-dashboard .sidebar .h3,.quarto-dashboard .sidebar .h4,.quarto-dashboard .sidebar .h5,.quarto-dashboard .sidebar .h6{margin-top:.5em}.quarto-dashboard .sidebar form{flex-direction:column;align-items:start;margin-bottom:1em}.quarto-dashboard .sidebar form div[class*=oi-][class$=-input]{flex-direction:column}.quarto-dashboard .sidebar form[class*=oi-][class$=-toggle]{flex-direction:row-reverse;align-items:center;justify-content:start}.quarto-dashboard .sidebar form input[type=range]{margin-top:.5em;margin-right:.8em;margin-left:1em}.quarto-dashboard .sidebar label{width:fit-content}.quarto-dashboard .sidebar .card-body{margin-bottom:2em}.quarto-dashboard .sidebar .shiny-input-container{margin-bottom:1em}.quarto-dashboard .sidebar .shiny-options-group{margin-top:0}.quarto-dashboard .sidebar .control-label{margin-bottom:.3em}.quarto-dashboard .card .card-body .quarto-layout-row{align-items:stretch}.quarto-dashboard .toolbar{font-size:.9em;display:flex;flex-direction:row;border-top:solid 1px silver;padding:1em;flex-wrap:wrap;background-color:rgba(52,58,64,.25)}.quarto-dashboard .toolbar .cell-output-display{display:flex}.quarto-dashboard .toolbar .shiny-input-container{padding-bottom:.5em;margin-bottom:.5em;width:inherit}.quarto-dashboard .toolbar .shiny-input-container>.checkbox:first-child{margin-top:6px}.quarto-dashboard .toolbar>*:last-child{margin-right:0}.quarto-dashboard .toolbar>*>*{margin-right:1em;align-items:baseline}.quarto-dashboard .toolbar>*>*>a{text-decoration:none;margin-top:auto;margin-bottom:auto}.quarto-dashboard .toolbar .shiny-input-container{padding-bottom:0;margin-bottom:0}.quarto-dashboard .toolbar .shiny-input-container>*{flex-shrink:0;flex-grow:0}.quarto-dashboard .toolbar .form-group.shiny-input-container:not([role=group])>label{margin-bottom:0}.quarto-dashboard .toolbar .shiny-input-container.no-baseline{align-items:start;padding-top:6px}.quarto-dashboard .toolbar .shiny-input-container{display:flex;align-items:baseline}.quarto-dashboard .toolbar .shiny-input-container label{padding-right:.4em}.quarto-dashboard .toolbar .shiny-input-container .bslib-input-switch{margin-top:6px}.quarto-dashboard .toolbar input[type=text]{line-height:1;width:inherit}.quarto-dashboard .toolbar .input-daterange{width:inherit}.quarto-dashboard .toolbar .input-daterange input[type=text]{height:2.4em;width:10em}.quarto-dashboard .toolbar .input-daterange .input-group-addon{height:auto;padding:0;margin-left:-5px !important;margin-right:-5px}.quarto-dashboard .toolbar .input-daterange .input-group-addon .input-group-text{padding-top:0;padding-bottom:0;height:100%}.quarto-dashboard .toolbar span.irs.irs--shiny{width:10em}.quarto-dashboard .toolbar span.irs.irs--shiny .irs-line{top:9px}.quarto-dashboard .toolbar span.irs.irs--shiny .irs-min,.quarto-dashboard .toolbar span.irs.irs--shiny .irs-max,.quarto-dashboard .toolbar span.irs.irs--shiny .irs-from,.quarto-dashboard .toolbar span.irs.irs--shiny .irs-to,.quarto-dashboard .toolbar span.irs.irs--shiny .irs-single{top:20px}.quarto-dashboard .toolbar span.irs.irs--shiny .irs-bar{top:8px}.quarto-dashboard .toolbar span.irs.irs--shiny .irs-handle{top:0px}.quarto-dashboard .toolbar .shiny-input-checkboxgroup>label{margin-top:6px}.quarto-dashboard .toolbar .shiny-input-checkboxgroup>.shiny-options-group{margin-top:0;align-items:baseline}.quarto-dashboard .toolbar .shiny-input-radiogroup>label{margin-top:6px}.quarto-dashboard .toolbar .shiny-input-radiogroup>.shiny-options-group{align-items:baseline;margin-top:0}.quarto-dashboard .toolbar .shiny-input-radiogroup>.shiny-options-group>.radio{margin-right:.3em}.quarto-dashboard .toolbar .form-select{padding-top:.2em;padding-bottom:.2em}.quarto-dashboard .toolbar .shiny-input-select{min-width:6em}.quarto-dashboard .toolbar div.checkbox{margin-bottom:0px}.quarto-dashboard .toolbar>.checkbox:first-child{margin-top:6px}.quarto-dashboard .toolbar form{width:fit-content}.quarto-dashboard .toolbar form label{padding-top:.2em;padding-bottom:.2em;width:fit-content}.quarto-dashboard .toolbar form input[type=date]{width:fit-content}.quarto-dashboard .toolbar form input[type=color]{width:3em}.quarto-dashboard .toolbar form button{padding:.4em}.quarto-dashboard .toolbar form select{width:fit-content}.quarto-dashboard .toolbar>*{font-size:.9em;flex-grow:0}.quarto-dashboard .toolbar .shiny-input-container label{margin-bottom:1px}.quarto-dashboard .toolbar-bottom{margin-top:1em;margin-bottom:0 !important;order:2}.quarto-dashboard .quarto-dashboard-content>.dashboard-toolbar-container>.toolbar-content>.tab-content>.tab-pane>*:not(.bslib-sidebar-layout){padding:1em}.quarto-dashboard .quarto-dashboard-content>.dashboard-toolbar-container>.toolbar-content>*:not(.tab-content){padding:1em}.quarto-dashboard .quarto-dashboard-content>.tab-content>.dashboard-page>.dashboard-toolbar-container>.toolbar-content,.quarto-dashboard .quarto-dashboard-content>.tab-content>.dashboard-page:not(.dashboard-sidebar-container)>*:not(.dashboard-toolbar-container){padding:1em}.quarto-dashboard .toolbar-content{padding:0}.quarto-dashboard .quarto-dashboard-content.quarto-dashboard-pages .tab-pane>.dashboard-toolbar-container .toolbar{border-radius:0;margin-bottom:0}.quarto-dashboard .dashboard-toolbar-container.toolbar-toplevel .toolbar{border-bottom:1px solid rgba(0,0,0,.175)}.quarto-dashboard .dashboard-toolbar-container.toolbar-toplevel .toolbar-bottom{margin-top:0}.quarto-dashboard .dashboard-toolbar-container:not(.toolbar-toplevel) .toolbar{margin-bottom:1em;border-top:none;border-radius:.25rem;border:1px solid rgba(0,0,0,.175)}.quarto-dashboard .vega-embed.has-actions details{width:1.7em;height:2em;position:absolute !important;top:0;right:0}.quarto-dashboard .dashboard-toolbar-container{padding:0}.quarto-dashboard .card .card-header p:last-child,.quarto-dashboard .card .card-footer p:last-child{margin-bottom:0}.quarto-dashboard .card .card-body>.h4:first-child{margin-top:0}.quarto-dashboard .card .card-body{z-index:4}@media(max-width: 767.98px){.quarto-dashboard .card .card-body .itables div.dataTables_wrapper div.dataTables_length,.quarto-dashboard .card .card-body .itables div.dataTables_wrapper div.dataTables_info,.quarto-dashboard .card .card-body .itables div.dataTables_wrapper div.dataTables_paginate{text-align:initial}.quarto-dashboard .card .card-body .itables div.dataTables_wrapper div.dataTables_filter{text-align:right}.quarto-dashboard .card .card-body .itables div.dataTables_wrapper div.dataTables_paginate ul.pagination{justify-content:initial}}.quarto-dashboard .card .card-body .itables .dataTables_wrapper{display:flex;flex-wrap:wrap;justify-content:space-between;align-items:center;padding-top:0}.quarto-dashboard .card .card-body .itables .dataTables_wrapper table{flex-shrink:0}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dt-buttons{margin-bottom:.5em;margin-left:auto;width:fit-content;float:right}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dt-buttons.btn-group{background:#222;border:none}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dt-buttons .btn-secondary{background-color:#222;background-image:none;border:solid #dee2e6 1px;padding:.2em .7em}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dt-buttons .btn span{font-size:.8em;color:#fff}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_info{margin-left:.5em;margin-bottom:.5em;padding-top:0}@media(min-width: 768px){.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_info{font-size:.875em}}@media(max-width: 767.98px){.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_info{font-size:.8em}}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_filter{margin-bottom:.5em;font-size:.875em}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_filter input[type=search]{padding:1px 5px 1px 5px;font-size:.875em}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_length{flex-basis:1 1 50%;margin-bottom:.5em;font-size:.875em}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_length select{padding:.4em 3em .4em .5em;font-size:.875em;margin-left:.2em;margin-right:.2em}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_paginate{flex-shrink:0}@media(min-width: 768px){.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_paginate{margin-left:auto}}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_paginate ul.pagination .paginate_button .page-link{font-size:.8em}.quarto-dashboard .card .card-footer{font-size:.9em}.quarto-dashboard .card .card-toolbar{display:flex;flex-grow:1;flex-direction:row;width:100%;flex-wrap:wrap}.quarto-dashboard .card .card-toolbar>*{font-size:.8em;flex-grow:0}.quarto-dashboard .card .card-toolbar>.card-title{font-size:1em;flex-grow:1;align-self:flex-start;margin-top:.1em}.quarto-dashboard .card .card-toolbar .cell-output-display{display:flex}.quarto-dashboard .card .card-toolbar .shiny-input-container{padding-bottom:.5em;margin-bottom:.5em;width:inherit}.quarto-dashboard .card .card-toolbar .shiny-input-container>.checkbox:first-child{margin-top:6px}.quarto-dashboard .card .card-toolbar>*:last-child{margin-right:0}.quarto-dashboard .card .card-toolbar>*>*{margin-right:1em;align-items:baseline}.quarto-dashboard .card .card-toolbar>*>*>a{text-decoration:none;margin-top:auto;margin-bottom:auto}.quarto-dashboard .card .card-toolbar form{width:fit-content}.quarto-dashboard .card .card-toolbar form label{padding-top:.2em;padding-bottom:.2em;width:fit-content}.quarto-dashboard .card .card-toolbar form input[type=date]{width:fit-content}.quarto-dashboard .card .card-toolbar form input[type=color]{width:3em}.quarto-dashboard .card .card-toolbar form button{padding:.4em}.quarto-dashboard .card .card-toolbar form select{width:fit-content}.quarto-dashboard .card .card-toolbar .cell-output-display{display:flex}.quarto-dashboard .card .card-toolbar .shiny-input-container{padding-bottom:.5em;margin-bottom:.5em;width:inherit}.quarto-dashboard .card .card-toolbar .shiny-input-container>.checkbox:first-child{margin-top:6px}.quarto-dashboard .card .card-toolbar>*:last-child{margin-right:0}.quarto-dashboard .card .card-toolbar>*>*{margin-right:1em;align-items:baseline}.quarto-dashboard .card .card-toolbar>*>*>a{text-decoration:none;margin-top:auto;margin-bottom:auto}.quarto-dashboard .card .card-toolbar .shiny-input-container{padding-bottom:0;margin-bottom:0}.quarto-dashboard .card .card-toolbar .shiny-input-container>*{flex-shrink:0;flex-grow:0}.quarto-dashboard .card .card-toolbar .form-group.shiny-input-container:not([role=group])>label{margin-bottom:0}.quarto-dashboard .card .card-toolbar .shiny-input-container.no-baseline{align-items:start;padding-top:6px}.quarto-dashboard .card .card-toolbar .shiny-input-container{display:flex;align-items:baseline}.quarto-dashboard .card .card-toolbar .shiny-input-container label{padding-right:.4em}.quarto-dashboard .card .card-toolbar .shiny-input-container .bslib-input-switch{margin-top:6px}.quarto-dashboard .card .card-toolbar input[type=text]{line-height:1;width:inherit}.quarto-dashboard .card .card-toolbar .input-daterange{width:inherit}.quarto-dashboard .card .card-toolbar .input-daterange input[type=text]{height:2.4em;width:10em}.quarto-dashboard .card .card-toolbar .input-daterange .input-group-addon{height:auto;padding:0;margin-left:-5px !important;margin-right:-5px}.quarto-dashboard .card .card-toolbar .input-daterange .input-group-addon .input-group-text{padding-top:0;padding-bottom:0;height:100%}.quarto-dashboard .card .card-toolbar span.irs.irs--shiny{width:10em}.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-line{top:9px}.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-min,.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-max,.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-from,.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-to,.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-single{top:20px}.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-bar{top:8px}.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-handle{top:0px}.quarto-dashboard .card .card-toolbar .shiny-input-checkboxgroup>label{margin-top:6px}.quarto-dashboard .card .card-toolbar .shiny-input-checkboxgroup>.shiny-options-group{margin-top:0;align-items:baseline}.quarto-dashboard .card .card-toolbar .shiny-input-radiogroup>label{margin-top:6px}.quarto-dashboard .card .card-toolbar .shiny-input-radiogroup>.shiny-options-group{align-items:baseline;margin-top:0}.quarto-dashboard .card .card-toolbar .shiny-input-radiogroup>.shiny-options-group>.radio{margin-right:.3em}.quarto-dashboard .card .card-toolbar .form-select{padding-top:.2em;padding-bottom:.2em}.quarto-dashboard .card .card-toolbar .shiny-input-select{min-width:6em}.quarto-dashboard .card .card-toolbar div.checkbox{margin-bottom:0px}.quarto-dashboard .card .card-toolbar>.checkbox:first-child{margin-top:6px}.quarto-dashboard .card-body>table>thead{border-top:none}.quarto-dashboard .card-body>.table>:not(caption)>*>*{background-color:#2d2d2d}.tableFloatingHeaderOriginal{background-color:#2d2d2d;position:sticky !important;top:0 !important}.dashboard-data-table{margin-top:-1px}div.value-box-area span.observablehq--number{font-size:calc(clamp(.1em,15cqw,5em)*1.25);line-height:1.2;color:inherit;font-family:var(--bs-body-font-family)}.quarto-listing{padding-bottom:1em}.listing-pagination{padding-top:.5em}ul.pagination{float:right;padding-left:8px;padding-top:.5em}ul.pagination li{padding-right:.75em}ul.pagination li.disabled a,ul.pagination li.active a{color:#fff;text-decoration:none}ul.pagination li:last-of-type{padding-right:0}.listing-actions-group{display:flex}.listing-actions-group .form-select,.listing-actions-group .form-control{background-color:#222;color:#fff}.quarto-listing-filter{margin-bottom:1em;width:200px;margin-left:auto}.quarto-listing-sort{margin-bottom:1em;margin-right:auto;width:auto}.quarto-listing-sort .input-group-text{font-size:.8em}.input-group-text{border-right:none}.quarto-listing-sort select.form-select{font-size:.8em}.listing-no-matching{text-align:center;padding-top:2em;padding-bottom:3em;font-size:1em}#quarto-margin-sidebar .quarto-listing-category{padding-top:0;font-size:1rem}#quarto-margin-sidebar .quarto-listing-category-title{cursor:pointer;font-weight:600;font-size:1rem}.quarto-listing-category .category{cursor:pointer}.quarto-listing-category .category.active{font-weight:600}.quarto-listing-category.category-cloud{display:flex;flex-wrap:wrap;align-items:baseline}.quarto-listing-category.category-cloud .category{padding-right:5px}.quarto-listing-category.category-cloud .category-cloud-1{font-size:.75em}.quarto-listing-category.category-cloud .category-cloud-2{font-size:.95em}.quarto-listing-category.category-cloud .category-cloud-3{font-size:1.15em}.quarto-listing-category.category-cloud .category-cloud-4{font-size:1.35em}.quarto-listing-category.category-cloud .category-cloud-5{font-size:1.55em}.quarto-listing-category.category-cloud .category-cloud-6{font-size:1.75em}.quarto-listing-category.category-cloud .category-cloud-7{font-size:1.95em}.quarto-listing-category.category-cloud .category-cloud-8{font-size:2.15em}.quarto-listing-category.category-cloud .category-cloud-9{font-size:2.35em}.quarto-listing-category.category-cloud .category-cloud-10{font-size:2.55em}.quarto-listing-cols-1{grid-template-columns:repeat(1, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-1{grid-template-columns:repeat(1, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-1{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-2{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-2{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-2{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-3{grid-template-columns:repeat(3, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-3{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-3{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-4{grid-template-columns:repeat(4, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-4{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-4{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-5{grid-template-columns:repeat(5, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-5{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-5{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-6{grid-template-columns:repeat(6, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-6{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-6{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-7{grid-template-columns:repeat(7, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-7{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-7{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-8{grid-template-columns:repeat(8, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-8{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-8{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-9{grid-template-columns:repeat(9, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-9{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-9{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-10{grid-template-columns:repeat(10, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-10{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-10{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-11{grid-template-columns:repeat(11, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-11{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-11{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-12{grid-template-columns:repeat(12, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-12{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-12{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-grid{gap:1.5em}.quarto-grid-item.borderless{border:none}.quarto-grid-item.borderless .listing-categories .listing-category:last-of-type,.quarto-grid-item.borderless .listing-categories .listing-category:first-of-type{padding-left:0}.quarto-grid-item.borderless .listing-categories .listing-category{border:0}.quarto-grid-link{text-decoration:none;color:inherit}.quarto-grid-link:hover{text-decoration:none;color:inherit}.quarto-grid-item h5.title,.quarto-grid-item .title.h5{margin-top:0;margin-bottom:0}.quarto-grid-item .card-footer{display:flex;justify-content:space-between;font-size:.8em}.quarto-grid-item .card-footer p{margin-bottom:0}.quarto-grid-item p.card-img-top{margin-bottom:0}.quarto-grid-item p.card-img-top>img{object-fit:cover}.quarto-grid-item .card-other-values{margin-top:.5em;font-size:.8em}.quarto-grid-item .card-other-values tr{margin-bottom:.5em}.quarto-grid-item .card-other-values tr>td:first-of-type{font-weight:600;padding-right:1em;padding-left:1em;vertical-align:top}.quarto-grid-item div.post-contents{display:flex;flex-direction:column;text-decoration:none;height:100%}.quarto-grid-item .listing-item-img-placeholder{background-color:rgba(52,58,64,.25);flex-shrink:0}.quarto-grid-item .card-attribution{padding-top:1em;display:flex;gap:1em;text-transform:uppercase;color:#6c757d;font-weight:500;flex-grow:10;align-items:flex-end}.quarto-grid-item .description{padding-bottom:1em}.quarto-grid-item .card-attribution .date{align-self:flex-end}.quarto-grid-item .card-attribution.justify{justify-content:space-between}.quarto-grid-item .card-attribution.start{justify-content:flex-start}.quarto-grid-item .card-attribution.end{justify-content:flex-end}.quarto-grid-item .card-title{margin-bottom:.1em}.quarto-grid-item .card-subtitle{padding-top:.25em}.quarto-grid-item .card-text{font-size:.9em}.quarto-grid-item .listing-reading-time{padding-bottom:.25em}.quarto-grid-item .card-text-small{font-size:.8em}.quarto-grid-item .card-subtitle.subtitle{font-size:.9em;font-weight:600;padding-bottom:.5em}.quarto-grid-item .listing-categories{display:flex;flex-wrap:wrap;padding-bottom:5px}.quarto-grid-item .listing-categories .listing-category{color:#6c757d;border:solid #6c757d 1px;border-radius:.25rem;text-transform:uppercase;font-size:.65em;padding-left:.5em;padding-right:.5em;padding-top:.15em;padding-bottom:.15em;cursor:pointer;margin-right:4px;margin-bottom:4px}.quarto-grid-item.card-right{text-align:right}.quarto-grid-item.card-right .listing-categories{justify-content:flex-end}.quarto-grid-item.card-left{text-align:left}.quarto-grid-item.card-center{text-align:center}.quarto-grid-item.card-center .listing-description{text-align:justify}.quarto-grid-item.card-center .listing-categories{justify-content:center}table.quarto-listing-table td.image{padding:0px}table.quarto-listing-table td.image img{width:100%;max-width:50px;object-fit:contain}table.quarto-listing-table a{text-decoration:none;word-break:keep-all}table.quarto-listing-table th a{color:inherit}table.quarto-listing-table th a.asc:after{margin-bottom:-2px;margin-left:5px;display:inline-block;height:1rem;width:1rem;background-repeat:no-repeat;background-size:1rem 1rem;background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-sort-up" viewBox="0 0 16 16"><path d="M3.5 12.5a.5.5 0 0 1-1 0V3.707L1.354 4.854a.5.5 0 1 1-.708-.708l2-1.999.007-.007a.498.498 0 0 1 .7.006l2 2a.5.5 0 1 1-.707.708L3.5 3.707V12.5zm3.5-9a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5zM7.5 6a.5.5 0 0 0 0 1h5a.5.5 0 0 0 0-1h-5zm0 3a.5.5 0 0 0 0 1h3a.5.5 0 0 0 0-1h-3zm0 3a.5.5 0 0 0 0 1h1a.5.5 0 0 0 0-1h-1z"/></svg>');content:""}table.quarto-listing-table th a.desc:after{margin-bottom:-2px;margin-left:5px;display:inline-block;height:1rem;width:1rem;background-repeat:no-repeat;background-size:1rem 1rem;background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-sort-down" viewBox="0 0 16 16"><path d="M3.5 2.5a.5.5 0 0 0-1 0v8.793l-1.146-1.147a.5.5 0 0 0-.708.708l2 1.999.007.007a.497.497 0 0 0 .7-.006l2-2a.5.5 0 0 0-.707-.708L3.5 11.293V2.5zm3.5 1a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5zM7.5 6a.5.5 0 0 0 0 1h5a.5.5 0 0 0 0-1h-5zm0 3a.5.5 0 0 0 0 1h3a.5.5 0 0 0 0-1h-3zm0 3a.5.5 0 0 0 0 1h1a.5.5 0 0 0 0-1h-1z"/></svg>');content:""}table.quarto-listing-table.table-hover td{cursor:pointer}.quarto-post.image-left{flex-direction:row}.quarto-post.image-right{flex-direction:row-reverse}@media(max-width: 767.98px){.quarto-post.image-right,.quarto-post.image-left{gap:0em;flex-direction:column}.quarto-post .metadata{padding-bottom:1em;order:2}.quarto-post .body{order:1}.quarto-post .thumbnail{order:3}}.list.quarto-listing-default div:last-of-type{border-bottom:none}@media(min-width: 992px){.quarto-listing-container-default{margin-right:2em}}div.quarto-post{display:flex;gap:2em;margin-bottom:1.5em;border-bottom:1px solid #dee2e6}@media(max-width: 767.98px){div.quarto-post{padding-bottom:1em}}div.quarto-post .metadata{flex-basis:20%;flex-grow:0;margin-top:.2em;flex-shrink:10}div.quarto-post .thumbnail{flex-basis:30%;flex-grow:0;flex-shrink:0}div.quarto-post .thumbnail img{margin-top:.4em;width:100%;object-fit:cover}div.quarto-post .body{flex-basis:45%;flex-grow:1;flex-shrink:0}div.quarto-post .body h3.listing-title,div.quarto-post .body .listing-title.h3{margin-top:0px;margin-bottom:0px;border-bottom:none}div.quarto-post .body .listing-subtitle{font-size:.875em;margin-bottom:.5em;margin-top:.2em}div.quarto-post .body .description{font-size:.9em}div.quarto-post .body pre code{white-space:pre-wrap}div.quarto-post a{color:#fff;text-decoration:none}div.quarto-post .metadata{display:flex;flex-direction:column;font-size:.8em;font-family:Lato,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol";flex-basis:33%}div.quarto-post .listing-categories{display:flex;flex-wrap:wrap;padding-bottom:5px}div.quarto-post .listing-categories .listing-category{color:#6c757d;border:solid #6c757d 1px;border-radius:.25rem;text-transform:uppercase;font-size:.65em;padding-left:.5em;padding-right:.5em;padding-top:.15em;padding-bottom:.15em;cursor:pointer;margin-right:4px;margin-bottom:4px}div.quarto-post .listing-description{margin-bottom:.5em}div.quarto-about-jolla{display:flex !important;flex-direction:column;align-items:center;margin-top:10%;padding-bottom:1em}div.quarto-about-jolla .about-image{object-fit:cover;margin-left:auto;margin-right:auto;margin-bottom:1.5em}div.quarto-about-jolla img.round{border-radius:50%}div.quarto-about-jolla img.rounded{border-radius:10px}div.quarto-about-jolla .quarto-title h1.title,div.quarto-about-jolla .quarto-title .title.h1{text-align:center}div.quarto-about-jolla .quarto-title .description{text-align:center}div.quarto-about-jolla h2,div.quarto-about-jolla .h2{border-bottom:none}div.quarto-about-jolla .about-sep{width:60%}div.quarto-about-jolla main{text-align:center}div.quarto-about-jolla .about-links{display:flex}@media(min-width: 992px){div.quarto-about-jolla .about-links{flex-direction:row;column-gap:.8em;row-gap:15px;flex-wrap:wrap}}@media(max-width: 991.98px){div.quarto-about-jolla .about-links{flex-direction:column;row-gap:1em;width:100%;padding-bottom:1.5em}}div.quarto-about-jolla .about-link{color:#fff;text-decoration:none;border:solid 1px}@media(min-width: 992px){div.quarto-about-jolla .about-link{font-size:.8em;padding:.25em .5em;border-radius:4px}}@media(max-width: 991.98px){div.quarto-about-jolla .about-link{font-size:1.1em;padding:.5em .5em;text-align:center;border-radius:6px}}div.quarto-about-jolla .about-link:hover{color:#00bc8c}div.quarto-about-jolla .about-link i.bi{margin-right:.15em}div.quarto-about-solana{display:flex !important;flex-direction:column;padding-top:3em !important;padding-bottom:1em}div.quarto-about-solana .about-entity{display:flex !important;align-items:start;justify-content:space-between}@media(min-width: 992px){div.quarto-about-solana .about-entity{flex-direction:row}}@media(max-width: 991.98px){div.quarto-about-solana .about-entity{flex-direction:column-reverse;align-items:center;text-align:center}}div.quarto-about-solana .about-entity .entity-contents{display:flex;flex-direction:column}@media(max-width: 767.98px){div.quarto-about-solana .about-entity .entity-contents{width:100%}}div.quarto-about-solana .about-entity .about-image{object-fit:cover}@media(max-width: 991.98px){div.quarto-about-solana .about-entity .about-image{margin-bottom:1.5em}}div.quarto-about-solana .about-entity img.round{border-radius:50%}div.quarto-about-solana .about-entity img.rounded{border-radius:10px}div.quarto-about-solana .about-entity .about-links{display:flex;justify-content:left;padding-bottom:1.2em}@media(min-width: 992px){div.quarto-about-solana .about-entity .about-links{flex-direction:row;column-gap:.8em;row-gap:15px;flex-wrap:wrap}}@media(max-width: 991.98px){div.quarto-about-solana .about-entity .about-links{flex-direction:column;row-gap:1em;width:100%;padding-bottom:1.5em}}div.quarto-about-solana .about-entity .about-link{color:#fff;text-decoration:none;border:solid 1px}@media(min-width: 992px){div.quarto-about-solana .about-entity .about-link{font-size:.8em;padding:.25em .5em;border-radius:4px}}@media(max-width: 991.98px){div.quarto-about-solana .about-entity .about-link{font-size:1.1em;padding:.5em .5em;text-align:center;border-radius:6px}}div.quarto-about-solana .about-entity .about-link:hover{color:#00bc8c}div.quarto-about-solana .about-entity .about-link i.bi{margin-right:.15em}div.quarto-about-solana .about-contents{padding-right:1.5em;flex-basis:0;flex-grow:1}div.quarto-about-solana .about-contents main.content{margin-top:0}div.quarto-about-solana .about-contents h2,div.quarto-about-solana .about-contents .h2{border-bottom:none}div.quarto-about-trestles{display:flex !important;flex-direction:row;padding-top:3em !important;padding-bottom:1em}@media(max-width: 991.98px){div.quarto-about-trestles{flex-direction:column;padding-top:0em !important}}div.quarto-about-trestles .about-entity{display:flex !important;flex-direction:column;align-items:center;text-align:center;padding-right:1em}@media(min-width: 992px){div.quarto-about-trestles .about-entity{flex:0 0 42%}}div.quarto-about-trestles .about-entity .about-image{object-fit:cover;margin-bottom:1.5em}div.quarto-about-trestles .about-entity img.round{border-radius:50%}div.quarto-about-trestles .about-entity img.rounded{border-radius:10px}div.quarto-about-trestles .about-entity .about-links{display:flex;justify-content:center}@media(min-width: 992px){div.quarto-about-trestles .about-entity .about-links{flex-direction:row;column-gap:.8em;row-gap:15px;flex-wrap:wrap}}@media(max-width: 991.98px){div.quarto-about-trestles .about-entity .about-links{flex-direction:column;row-gap:1em;width:100%;padding-bottom:1.5em}}div.quarto-about-trestles .about-entity .about-link{color:#fff;text-decoration:none;border:solid 1px}@media(min-width: 992px){div.quarto-about-trestles .about-entity .about-link{font-size:.8em;padding:.25em .5em;border-radius:4px}}@media(max-width: 991.98px){div.quarto-about-trestles .about-entity .about-link{font-size:1.1em;padding:.5em .5em;text-align:center;border-radius:6px}}div.quarto-about-trestles .about-entity .about-link:hover{color:#00bc8c}div.quarto-about-trestles .about-entity .about-link i.bi{margin-right:.15em}div.quarto-about-trestles .about-contents{flex-basis:0;flex-grow:1}div.quarto-about-trestles .about-contents h2,div.quarto-about-trestles .about-contents .h2{border-bottom:none}@media(min-width: 992px){div.quarto-about-trestles .about-contents{border-left:solid 1px #dee2e6;padding-left:1.5em}}div.quarto-about-trestles .about-contents main.content{margin-top:0}div.quarto-about-marquee{padding-bottom:1em}div.quarto-about-marquee .about-contents{display:flex;flex-direction:column}div.quarto-about-marquee .about-image{max-height:550px;margin-bottom:1.5em;object-fit:cover}div.quarto-about-marquee img.round{border-radius:50%}div.quarto-about-marquee img.rounded{border-radius:10px}div.quarto-about-marquee h2,div.quarto-about-marquee .h2{border-bottom:none}div.quarto-about-marquee .about-links{display:flex;justify-content:center;padding-top:1.5em}@media(min-width: 992px){div.quarto-about-marquee .about-links{flex-direction:row;column-gap:.8em;row-gap:15px;flex-wrap:wrap}}@media(max-width: 991.98px){div.quarto-about-marquee .about-links{flex-direction:column;row-gap:1em;width:100%;padding-bottom:1.5em}}div.quarto-about-marquee .about-link{color:#fff;text-decoration:none;border:solid 1px}@media(min-width: 992px){div.quarto-about-marquee .about-link{font-size:.8em;padding:.25em .5em;border-radius:4px}}@media(max-width: 991.98px){div.quarto-about-marquee .about-link{font-size:1.1em;padding:.5em .5em;text-align:center;border-radius:6px}}div.quarto-about-marquee .about-link:hover{color:#00bc8c}div.quarto-about-marquee .about-link i.bi{margin-right:.15em}@media(min-width: 992px){div.quarto-about-marquee .about-link{border:none}}div.quarto-about-broadside{display:flex;flex-direction:column;padding-bottom:1em}div.quarto-about-broadside .about-main{display:flex !important;padding-top:0 !important}@media(min-width: 992px){div.quarto-about-broadside .about-main{flex-direction:row;align-items:flex-start}}@media(max-width: 991.98px){div.quarto-about-broadside .about-main{flex-direction:column}}@media(max-width: 991.98px){div.quarto-about-broadside .about-main .about-entity{flex-shrink:0;width:100%;height:450px;margin-bottom:1.5em;background-size:cover;background-repeat:no-repeat}}@media(min-width: 992px){div.quarto-about-broadside .about-main .about-entity{flex:0 10 50%;margin-right:1.5em;width:100%;height:100%;background-size:100%;background-repeat:no-repeat}}div.quarto-about-broadside .about-main .about-contents{padding-top:14px;flex:0 0 50%}div.quarto-about-broadside h2,div.quarto-about-broadside .h2{border-bottom:none}div.quarto-about-broadside .about-sep{margin-top:1.5em;width:60%;align-self:center}div.quarto-about-broadside .about-links{display:flex;justify-content:center;column-gap:20px;padding-top:1.5em}@media(min-width: 992px){div.quarto-about-broadside .about-links{flex-direction:row;column-gap:.8em;row-gap:15px;flex-wrap:wrap}}@media(max-width: 991.98px){div.quarto-about-broadside .about-links{flex-direction:column;row-gap:1em;width:100%;padding-bottom:1.5em}}div.quarto-about-broadside .about-link{color:#fff;text-decoration:none;border:solid 1px}@media(min-width: 992px){div.quarto-about-broadside .about-link{font-size:.8em;padding:.25em .5em;border-radius:4px}}@media(max-width: 991.98px){div.quarto-about-broadside .about-link{font-size:1.1em;padding:.5em .5em;text-align:center;border-radius:6px}}div.quarto-about-broadside .about-link:hover{color:#00bc8c}div.quarto-about-broadside .about-link i.bi{margin-right:.15em}@media(min-width: 992px){div.quarto-about-broadside .about-link{border:none}}.tippy-box[data-theme~=quarto]{background-color:#222;border:solid 1px #dee2e6;border-radius:.25rem;color:#fff;font-size:.875rem}.tippy-box[data-theme~=quarto]>.tippy-backdrop{background-color:#222}.tippy-box[data-theme~=quarto]>.tippy-arrow:after,.tippy-box[data-theme~=quarto]>.tippy-svg-arrow:after{content:"";position:absolute;z-index:-1}.tippy-box[data-theme~=quarto]>.tippy-arrow:after{border-color:rgba(0,0,0,0);border-style:solid}.tippy-box[data-placement^=top]>.tippy-arrow:before{bottom:-6px}.tippy-box[data-placement^=bottom]>.tippy-arrow:before{top:-6px}.tippy-box[data-placement^=right]>.tippy-arrow:before{left:-6px}.tippy-box[data-placement^=left]>.tippy-arrow:before{right:-6px}.tippy-box[data-theme~=quarto][data-placement^=top]>.tippy-arrow:before{border-top-color:#222}.tippy-box[data-theme~=quarto][data-placement^=top]>.tippy-arrow:after{border-top-color:#dee2e6;border-width:7px 7px 0;top:17px;left:1px}.tippy-box[data-theme~=quarto][data-placement^=top]>.tippy-svg-arrow>svg{top:16px}.tippy-box[data-theme~=quarto][data-placement^=top]>.tippy-svg-arrow:after{top:17px}.tippy-box[data-theme~=quarto][data-placement^=bottom]>.tippy-arrow:before{border-bottom-color:#222;bottom:16px}.tippy-box[data-theme~=quarto][data-placement^=bottom]>.tippy-arrow:after{border-bottom-color:#dee2e6;border-width:0 7px 7px;bottom:17px;left:1px}.tippy-box[data-theme~=quarto][data-placement^=bottom]>.tippy-svg-arrow>svg{bottom:15px}.tippy-box[data-theme~=quarto][data-placement^=bottom]>.tippy-svg-arrow:after{bottom:17px}.tippy-box[data-theme~=quarto][data-placement^=left]>.tippy-arrow:before{border-left-color:#222}.tippy-box[data-theme~=quarto][data-placement^=left]>.tippy-arrow:after{border-left-color:#dee2e6;border-width:7px 0 7px 7px;left:17px;top:1px}.tippy-box[data-theme~=quarto][data-placement^=left]>.tippy-svg-arrow>svg{left:11px}.tippy-box[data-theme~=quarto][data-placement^=left]>.tippy-svg-arrow:after{left:12px}.tippy-box[data-theme~=quarto][data-placement^=right]>.tippy-arrow:before{border-right-color:#222;right:16px}.tippy-box[data-theme~=quarto][data-placement^=right]>.tippy-arrow:after{border-width:7px 7px 7px 0;right:17px;top:1px;border-right-color:#dee2e6}.tippy-box[data-theme~=quarto][data-placement^=right]>.tippy-svg-arrow>svg{right:11px}.tippy-box[data-theme~=quarto][data-placement^=right]>.tippy-svg-arrow:after{right:12px}.tippy-box[data-theme~=quarto]>.tippy-svg-arrow{fill:#fff}.tippy-box[data-theme~=quarto]>.tippy-svg-arrow:after{background-image:url(data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iNiIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBkPSJNMCA2czEuNzk2LS4wMTMgNC42Ny0zLjYxNUM1Ljg1MS45IDYuOTMuMDA2IDggMGMxLjA3LS4wMDYgMi4xNDguODg3IDMuMzQzIDIuMzg1QzE0LjIzMyA2LjAwNSAxNiA2IDE2IDZIMHoiIGZpbGw9InJnYmEoMCwgOCwgMTYsIDAuMikiLz48L3N2Zz4=);background-size:16px 6px;width:16px;height:6px}.top-right{position:absolute;top:1em;right:1em}.visually-hidden{border:0;clip:rect(0 0 0 0);height:auto;margin:0;overflow:hidden;padding:0;position:absolute;width:1px;white-space:nowrap}.hidden{display:none !important}.zindex-bottom{z-index:-1 !important}figure.figure{display:block}.quarto-layout-panel{margin-bottom:1em}.quarto-layout-panel>figure{width:100%}.quarto-layout-panel>figure>figcaption,.quarto-layout-panel>.panel-caption{margin-top:10pt}.quarto-layout-panel>.table-caption{margin-top:0px}.table-caption p{margin-bottom:.5em}.quarto-layout-row{display:flex;flex-direction:row;align-items:flex-start}.quarto-layout-valign-top{align-items:flex-start}.quarto-layout-valign-bottom{align-items:flex-end}.quarto-layout-valign-center{align-items:center}.quarto-layout-cell{position:relative;margin-right:20px}.quarto-layout-cell:last-child{margin-right:0}.quarto-layout-cell figure,.quarto-layout-cell>p{margin:.2em}.quarto-layout-cell img{max-width:100%}.quarto-layout-cell .html-widget{width:100% !important}.quarto-layout-cell div figure p{margin:0}.quarto-layout-cell figure{display:block;margin-inline-start:0;margin-inline-end:0}.quarto-layout-cell table{display:inline-table}.quarto-layout-cell-subref figcaption,figure .quarto-layout-row figure figcaption{text-align:center;font-style:italic}.quarto-figure{position:relative;margin-bottom:1em}.quarto-figure>figure{width:100%;margin-bottom:0}.quarto-figure-left>figure>p,.quarto-figure-left>figure>div{text-align:left}.quarto-figure-center>figure>p,.quarto-figure-center>figure>div{text-align:center}.quarto-figure-right>figure>p,.quarto-figure-right>figure>div{text-align:right}.quarto-figure>figure>div.cell-annotation,.quarto-figure>figure>div code{text-align:left}figure>p:empty{display:none}figure>p:first-child{margin-top:0;margin-bottom:0}figure>figcaption.quarto-float-caption-bottom{margin-bottom:.5em}figure>figcaption.quarto-float-caption-top{margin-top:.5em}div[id^=tbl-]{position:relative}.quarto-figure>.anchorjs-link{position:absolute;top:.6em;right:.5em}div[id^=tbl-]>.anchorjs-link{position:absolute;top:.7em;right:.3em}.quarto-figure:hover>.anchorjs-link,div[id^=tbl-]:hover>.anchorjs-link,h2:hover>.anchorjs-link,.h2:hover>.anchorjs-link,h3:hover>.anchorjs-link,.h3:hover>.anchorjs-link,h4:hover>.anchorjs-link,.h4:hover>.anchorjs-link,h5:hover>.anchorjs-link,.h5:hover>.anchorjs-link,h6:hover>.anchorjs-link,.h6:hover>.anchorjs-link,.reveal-anchorjs-link>.anchorjs-link{opacity:1}#title-block-header{margin-block-end:1rem;position:relative;margin-top:-1px}#title-block-header .abstract{margin-block-start:1rem}#title-block-header .abstract .abstract-title{font-weight:600}#title-block-header a{text-decoration:none}#title-block-header .author,#title-block-header .date,#title-block-header .doi{margin-block-end:.2rem}#title-block-header .quarto-title-block>div{display:flex}#title-block-header .quarto-title-block>div>h1,#title-block-header .quarto-title-block>div>.h1{flex-grow:1}#title-block-header .quarto-title-block>div>button{flex-shrink:0;height:2.25rem;margin-top:0}@media(min-width: 992px){#title-block-header .quarto-title-block>div>button{margin-top:5px}}tr.header>th>p:last-of-type{margin-bottom:0px}table,table.table{margin-top:.5rem;margin-bottom:.5rem}caption,.table-caption{padding-top:.5rem;padding-bottom:.5rem;text-align:center}figure.quarto-float-tbl figcaption.quarto-float-caption-top{margin-top:.5rem;margin-bottom:.25rem;text-align:center}figure.quarto-float-tbl figcaption.quarto-float-caption-bottom{padding-top:.25rem;margin-bottom:.5rem;text-align:center}.utterances{max-width:none;margin-left:-8px}iframe{margin-bottom:1em}details{margin-bottom:1em}details[show]{margin-bottom:0}details>summary{color:#6c757d}details>summary>p:only-child{display:inline}pre.sourceCode,code.sourceCode{position:relative}dd code:not(.sourceCode),p code:not(.sourceCode){white-space:pre-wrap}code{white-space:pre}@media print{code{white-space:pre-wrap}}pre>code{display:block}pre>code.sourceCode{white-space:pre}pre>code.sourceCode>span>a:first-child::before{text-decoration:none}pre.code-overflow-wrap>code.sourceCode{white-space:pre-wrap}pre.code-overflow-scroll>code.sourceCode{white-space:pre}code a:any-link{color:inherit;text-decoration:none}code a:hover{color:inherit;text-decoration:underline}ul.task-list{padding-left:1em}[data-tippy-root]{display:inline-block}.tippy-content .footnote-back{display:none}.footnote-back{margin-left:.2em}.tippy-content{overflow-x:auto}.quarto-embedded-source-code{display:none}.quarto-unresolved-ref{font-weight:600}.quarto-cover-image{max-width:35%;float:right;margin-left:30px}.cell-output-display .widget-subarea{margin-bottom:1em}.cell-output-display:not(.no-overflow-x),.knitsql-table:not(.no-overflow-x){overflow-x:auto}.panel-input{margin-bottom:1em}.panel-input>div,.panel-input>div>div{display:inline-block;vertical-align:top;padding-right:12px}.panel-input>p:last-child{margin-bottom:0}.layout-sidebar{margin-bottom:1em}.layout-sidebar .tab-content{border:none}.tab-content>.page-columns.active{display:grid}div.sourceCode>iframe{width:100%;height:300px;margin-bottom:-0.5em}a{text-underline-offset:3px}div.ansi-escaped-output{font-family:monospace;display:block}/*!
+ */@import"https://fonts.googleapis.com/css2?family=Lato:ital,wght@0,400;0,700;1,400&display=swap";:root,[data-bs-theme=light]{--bs-blue: #375a7f;--bs-indigo: #6610f2;--bs-purple: #6f42c1;--bs-pink: #e83e8c;--bs-red: #e74c3c;--bs-orange: #fd7e14;--bs-yellow: #f39c12;--bs-green: #00bc8c;--bs-teal: #20c997;--bs-cyan: #3498db;--bs-black: #000;--bs-white: #fff;--bs-gray: #6c757d;--bs-gray-dark: #343a40;--bs-gray-100: #f8f9fa;--bs-gray-200: #ebebeb;--bs-gray-300: #dee2e6;--bs-gray-400: #ced4da;--bs-gray-500: #adb5bd;--bs-gray-600: #6c757d;--bs-gray-700: #444;--bs-gray-800: #343a40;--bs-gray-900: #222;--bs-default: #434343;--bs-primary: #375a7f;--bs-secondary: #434343;--bs-success: #00bc8c;--bs-info: #3498db;--bs-warning: #f39c12;--bs-danger: #e74c3c;--bs-light: #6f6f6f;--bs-dark: #2d2d2d;--bs-default-rgb: 67, 67, 67;--bs-primary-rgb: 55, 90, 127;--bs-secondary-rgb: 67, 67, 67;--bs-success-rgb: 0, 188, 140;--bs-info-rgb: 52, 152, 219;--bs-warning-rgb: 243, 156, 18;--bs-danger-rgb: 231, 76, 60;--bs-light-rgb: 111, 111, 111;--bs-dark-rgb: 45, 45, 45;--bs-primary-text-emphasis: #162433;--bs-secondary-text-emphasis: #1b1b1b;--bs-success-text-emphasis: #004b38;--bs-info-text-emphasis: #153d58;--bs-warning-text-emphasis: #613e07;--bs-danger-text-emphasis: #5c1e18;--bs-light-text-emphasis: #444;--bs-dark-text-emphasis: #444;--bs-primary-bg-subtle: #d7dee5;--bs-secondary-bg-subtle: #d9d9d9;--bs-success-bg-subtle: #ccf2e8;--bs-info-bg-subtle: #d6eaf8;--bs-warning-bg-subtle: #fdebd0;--bs-danger-bg-subtle: #fadbd8;--bs-light-bg-subtle: #fcfcfd;--bs-dark-bg-subtle: #ced4da;--bs-primary-border-subtle: #afbdcc;--bs-secondary-border-subtle: #b4b4b4;--bs-success-border-subtle: #99e4d1;--bs-info-border-subtle: #aed6f1;--bs-warning-border-subtle: #fad7a0;--bs-danger-border-subtle: #f5b7b1;--bs-light-border-subtle: #ebebeb;--bs-dark-border-subtle: #adb5bd;--bs-white-rgb: 255, 255, 255;--bs-black-rgb: 0, 0, 0;--bs-font-sans-serif: Lato, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";--bs-font-monospace: SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;--bs-gradient: linear-gradient(180deg, rgba(255, 255, 255, 0.15), rgba(255, 255, 255, 0));--bs-root-font-size: 17px;--bs-body-font-family: Lato, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";--bs-body-font-size:1rem;--bs-body-font-weight: 400;--bs-body-line-height: 1.5;--bs-body-color: #fff;--bs-body-color-rgb: 255, 255, 255;--bs-body-bg: #222;--bs-body-bg-rgb: 34, 34, 34;--bs-emphasis-color: #000;--bs-emphasis-color-rgb: 0, 0, 0;--bs-secondary-color: rgba(255, 255, 255, 0.75);--bs-secondary-color-rgb: 255, 255, 255;--bs-secondary-bg: #ebebeb;--bs-secondary-bg-rgb: 235, 235, 235;--bs-tertiary-color: rgba(255, 255, 255, 0.5);--bs-tertiary-color-rgb: 255, 255, 255;--bs-tertiary-bg: #f8f9fa;--bs-tertiary-bg-rgb: 248, 249, 250;--bs-heading-color: inherit;--bs-link-color: #00bc8c;--bs-link-color-rgb: 0, 188, 140;--bs-link-decoration: underline;--bs-link-hover-color: #009670;--bs-link-hover-color-rgb: 0, 150, 112;--bs-code-color: #7d12ba;--bs-highlight-bg: #fdebd0;--bs-border-width: 1px;--bs-border-style: solid;--bs-border-color: #dee2e6;--bs-border-color-translucent: rgba(0, 0, 0, 0.175);--bs-border-radius: 0.25rem;--bs-border-radius-sm: 0.2em;--bs-border-radius-lg: 0.5rem;--bs-border-radius-xl: 1rem;--bs-border-radius-xxl: 2rem;--bs-border-radius-2xl: var(--bs-border-radius-xxl);--bs-border-radius-pill: 50rem;--bs-box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);--bs-box-shadow-sm: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.075);--bs-box-shadow-lg: 0 1rem 3rem rgba(0, 0, 0, 0.175);--bs-box-shadow-inset: inset 0 1px 2px rgba(0, 0, 0, 0.075);--bs-focus-ring-width: 0.25rem;--bs-focus-ring-opacity: 0.25;--bs-focus-ring-color: rgba(55, 90, 127, 0.25);--bs-form-valid-color: #00bc8c;--bs-form-valid-border-color: #00bc8c;--bs-form-invalid-color: #e74c3c;--bs-form-invalid-border-color: #e74c3c}[data-bs-theme=dark]{color-scheme:dark;--bs-body-color: #dee2e6;--bs-body-color-rgb: 222, 226, 230;--bs-body-bg: #222;--bs-body-bg-rgb: 34, 34, 34;--bs-emphasis-color: #fff;--bs-emphasis-color-rgb: 255, 255, 255;--bs-secondary-color: rgba(222, 226, 230, 0.75);--bs-secondary-color-rgb: 222, 226, 230;--bs-secondary-bg: #343a40;--bs-secondary-bg-rgb: 52, 58, 64;--bs-tertiary-color: rgba(222, 226, 230, 0.5);--bs-tertiary-color-rgb: 222, 226, 230;--bs-tertiary-bg: #2b2e31;--bs-tertiary-bg-rgb: 43, 46, 49;--bs-primary-text-emphasis: #879cb2;--bs-secondary-text-emphasis: #8e8e8e;--bs-success-text-emphasis: #66d7ba;--bs-info-text-emphasis: #85c1e9;--bs-warning-text-emphasis: #f8c471;--bs-danger-text-emphasis: #f1948a;--bs-light-text-emphasis: #f8f9fa;--bs-dark-text-emphasis: #dee2e6;--bs-primary-bg-subtle: #0b1219;--bs-secondary-bg-subtle: #0d0d0d;--bs-success-bg-subtle: #00261c;--bs-info-bg-subtle: #0a1e2c;--bs-warning-bg-subtle: #311f04;--bs-danger-bg-subtle: #2e0f0c;--bs-light-bg-subtle: #343a40;--bs-dark-bg-subtle: #1a1d20;--bs-primary-border-subtle: #21364c;--bs-secondary-border-subtle: #282828;--bs-success-border-subtle: #007154;--bs-info-border-subtle: #1f5b83;--bs-warning-border-subtle: #925e0b;--bs-danger-border-subtle: #8b2e24;--bs-light-border-subtle: #444;--bs-dark-border-subtle: #343a40;--bs-heading-color: inherit;--bs-link-color: #879cb2;--bs-link-hover-color: #9fb0c1;--bs-link-color-rgb: 135, 156, 178;--bs-link-hover-color-rgb: 159, 176, 193;--bs-code-color: white;--bs-border-color: #444;--bs-border-color-translucent: rgba(255, 255, 255, 0.15);--bs-form-valid-color: #66d7ba;--bs-form-valid-border-color: #66d7ba;--bs-form-invalid-color: #f1948a;--bs-form-invalid-border-color: #f1948a}*,*::before,*::after{box-sizing:border-box}:root{font-size:var(--bs-root-font-size)}body{margin:0;font-family:var(--bs-body-font-family);font-size:var(--bs-body-font-size);font-weight:var(--bs-body-font-weight);line-height:var(--bs-body-line-height);color:var(--bs-body-color);text-align:var(--bs-body-text-align);background-color:var(--bs-body-bg);-webkit-text-size-adjust:100%;-webkit-tap-highlight-color:rgba(0,0,0,0)}hr{margin:1rem 0;color:inherit;border:0;border-top:1px solid;opacity:.25}h6,.h6,h5,.h5,h4,.h4,h3,.h3,h2,.h2,h1,.h1{margin-top:0;margin-bottom:.5rem;font-weight:500;line-height:1.2;color:var(--bs-heading-color)}h1,.h1{font-size:calc(1.325rem + 0.9vw)}@media(min-width: 1200px){h1,.h1{font-size:2rem}}h2,.h2{font-size:calc(1.29rem + 0.48vw)}@media(min-width: 1200px){h2,.h2{font-size:1.65rem}}h3,.h3{font-size:calc(1.27rem + 0.24vw)}@media(min-width: 1200px){h3,.h3{font-size:1.45rem}}h4,.h4{font-size:1.25rem}h5,.h5{font-size:1.1rem}h6,.h6{font-size:1rem}p{margin-top:0;margin-bottom:1rem}abbr[title]{text-decoration:underline dotted;-webkit-text-decoration:underline dotted;-moz-text-decoration:underline dotted;-ms-text-decoration:underline dotted;-o-text-decoration:underline dotted;cursor:help;text-decoration-skip-ink:none}address{margin-bottom:1rem;font-style:normal;line-height:inherit}ol,ul{padding-left:2rem}ol,ul,dl{margin-top:0;margin-bottom:1rem}ol ol,ul ul,ol ul,ul ol{margin-bottom:0}dt{font-weight:700}dd{margin-bottom:.5rem;margin-left:0}blockquote{margin:0 0 1rem;padding:.625rem 1.25rem;border-left:.25rem solid #ebebeb}blockquote p:last-child,blockquote ul:last-child,blockquote ol:last-child{margin-bottom:0}b,strong{font-weight:bolder}small,.small{font-size:0.875em}mark,.mark{padding:.1875em;background-color:var(--bs-highlight-bg)}sub,sup{position:relative;font-size:0.75em;line-height:0;vertical-align:baseline}sub{bottom:-0.25em}sup{top:-0.5em}a{color:rgba(var(--bs-link-color-rgb), var(--bs-link-opacity, 1));text-decoration:underline;-webkit-text-decoration:underline;-moz-text-decoration:underline;-ms-text-decoration:underline;-o-text-decoration:underline}a:hover{--bs-link-color-rgb: var(--bs-link-hover-color-rgb)}a:not([href]):not([class]),a:not([href]):not([class]):hover{color:inherit;text-decoration:none}pre,code,kbd,samp{font-family:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace;font-size:1em}pre{display:block;margin-top:0;margin-bottom:1rem;overflow:auto;font-size:0.875em;color:inherit;background-color:#f8f9fa;padding:.5rem;border:1px solid var(--bs-border-color, #dee2e6);border-radius:.25rem}pre code{background-color:rgba(0,0,0,0);font-size:inherit;color:inherit;word-break:normal}code{font-size:0.875em;color:var(--bs-code-color);background-color:#f8f9fa;border-radius:.25rem;padding:.125rem .25rem;word-wrap:break-word}a>code{color:inherit}kbd{padding:.4rem .4rem;font-size:0.875em;color:#222;background-color:#fff;border-radius:.2em}kbd kbd{padding:0;font-size:1em}figure{margin:0 0 1rem}img,svg{vertical-align:middle}table{caption-side:bottom;border-collapse:collapse}caption{padding-top:.5rem;padding-bottom:.5rem;color:rgba(255,255,255,.75);text-align:left}th{text-align:inherit;text-align:-webkit-match-parent}thead,tbody,tfoot,tr,td,th{border-color:inherit;border-style:solid;border-width:0}label{display:inline-block}button{border-radius:0}button:focus:not(:focus-visible){outline:0}input,button,select,optgroup,textarea{margin:0;font-family:inherit;font-size:inherit;line-height:inherit}button,select{text-transform:none}[role=button]{cursor:pointer}select{word-wrap:normal}select:disabled{opacity:1}[list]:not([type=date]):not([type=datetime-local]):not([type=month]):not([type=week]):not([type=time])::-webkit-calendar-picker-indicator{display:none !important}button,[type=button],[type=reset],[type=submit]{-webkit-appearance:button}button:not(:disabled),[type=button]:not(:disabled),[type=reset]:not(:disabled),[type=submit]:not(:disabled){cursor:pointer}::-moz-focus-inner{padding:0;border-style:none}textarea{resize:vertical}fieldset{min-width:0;padding:0;margin:0;border:0}legend{float:left;width:100%;padding:0;margin-bottom:.5rem;font-size:calc(1.275rem + 0.3vw);line-height:inherit}@media(min-width: 1200px){legend{font-size:1.5rem}}legend+*{clear:left}::-webkit-datetime-edit-fields-wrapper,::-webkit-datetime-edit-text,::-webkit-datetime-edit-minute,::-webkit-datetime-edit-hour-field,::-webkit-datetime-edit-day-field,::-webkit-datetime-edit-month-field,::-webkit-datetime-edit-year-field{padding:0}::-webkit-inner-spin-button{height:auto}[type=search]{-webkit-appearance:textfield;outline-offset:-2px}::-webkit-search-decoration{-webkit-appearance:none}::-webkit-color-swatch-wrapper{padding:0}::file-selector-button{font:inherit;-webkit-appearance:button}output{display:inline-block}iframe{border:0}summary{display:list-item;cursor:pointer}progress{vertical-align:baseline}[hidden]{display:none !important}.lead{font-size:1.25rem;font-weight:300}.display-1{font-size:calc(1.625rem + 4.5vw);font-weight:300;line-height:1.2}@media(min-width: 1200px){.display-1{font-size:5rem}}.display-2{font-size:calc(1.575rem + 3.9vw);font-weight:300;line-height:1.2}@media(min-width: 1200px){.display-2{font-size:4.5rem}}.display-3{font-size:calc(1.525rem + 3.3vw);font-weight:300;line-height:1.2}@media(min-width: 1200px){.display-3{font-size:4rem}}.display-4{font-size:calc(1.475rem + 2.7vw);font-weight:300;line-height:1.2}@media(min-width: 1200px){.display-4{font-size:3.5rem}}.display-5{font-size:calc(1.425rem + 2.1vw);font-weight:300;line-height:1.2}@media(min-width: 1200px){.display-5{font-size:3rem}}.display-6{font-size:calc(1.375rem + 1.5vw);font-weight:300;line-height:1.2}@media(min-width: 1200px){.display-6{font-size:2.5rem}}.list-unstyled{padding-left:0;list-style:none}.list-inline{padding-left:0;list-style:none}.list-inline-item{display:inline-block}.list-inline-item:not(:last-child){margin-right:.5rem}.initialism{font-size:0.875em;text-transform:uppercase}.blockquote{margin-bottom:1rem;font-size:1.25rem}.blockquote>:last-child{margin-bottom:0}.blockquote-footer{margin-top:-1rem;margin-bottom:1rem;font-size:0.875em;color:#6c757d}.blockquote-footer::before{content:"— "}.img-fluid{max-width:100%;height:auto}.img-thumbnail{padding:.25rem;background-color:#222;border:1px solid #dee2e6;border-radius:.25rem;max-width:100%;height:auto}.figure{display:inline-block}.figure-img{margin-bottom:.5rem;line-height:1}.figure-caption{font-size:0.875em;color:rgba(255,255,255,.75)}.container,.container-fluid,.container-xxl,.container-xl,.container-lg,.container-md,.container-sm{--bs-gutter-x: 1.5rem;--bs-gutter-y: 0;width:100%;padding-right:calc(var(--bs-gutter-x)*.5);padding-left:calc(var(--bs-gutter-x)*.5);margin-right:auto;margin-left:auto}@media(min-width: 576px){.container-sm,.container{max-width:540px}}@media(min-width: 768px){.container-md,.container-sm,.container{max-width:720px}}@media(min-width: 992px){.container-lg,.container-md,.container-sm,.container{max-width:960px}}@media(min-width: 1200px){.container-xl,.container-lg,.container-md,.container-sm,.container{max-width:1140px}}@media(min-width: 1400px){.container-xxl,.container-xl,.container-lg,.container-md,.container-sm,.container{max-width:1320px}}:root{--bs-breakpoint-xs: 0;--bs-breakpoint-sm: 576px;--bs-breakpoint-md: 768px;--bs-breakpoint-lg: 992px;--bs-breakpoint-xl: 1200px;--bs-breakpoint-xxl: 1400px}.grid{display:grid;grid-template-rows:repeat(var(--bs-rows, 1), 1fr);grid-template-columns:repeat(var(--bs-columns, 12), 1fr);gap:var(--bs-gap, 1.5rem)}.grid .g-col-1{grid-column:auto/span 1}.grid .g-col-2{grid-column:auto/span 2}.grid .g-col-3{grid-column:auto/span 3}.grid .g-col-4{grid-column:auto/span 4}.grid .g-col-5{grid-column:auto/span 5}.grid .g-col-6{grid-column:auto/span 6}.grid .g-col-7{grid-column:auto/span 7}.grid .g-col-8{grid-column:auto/span 8}.grid .g-col-9{grid-column:auto/span 9}.grid .g-col-10{grid-column:auto/span 10}.grid .g-col-11{grid-column:auto/span 11}.grid .g-col-12{grid-column:auto/span 12}.grid .g-start-1{grid-column-start:1}.grid .g-start-2{grid-column-start:2}.grid .g-start-3{grid-column-start:3}.grid .g-start-4{grid-column-start:4}.grid .g-start-5{grid-column-start:5}.grid .g-start-6{grid-column-start:6}.grid .g-start-7{grid-column-start:7}.grid .g-start-8{grid-column-start:8}.grid .g-start-9{grid-column-start:9}.grid .g-start-10{grid-column-start:10}.grid .g-start-11{grid-column-start:11}@media(min-width: 576px){.grid .g-col-sm-1{grid-column:auto/span 1}.grid .g-col-sm-2{grid-column:auto/span 2}.grid .g-col-sm-3{grid-column:auto/span 3}.grid .g-col-sm-4{grid-column:auto/span 4}.grid .g-col-sm-5{grid-column:auto/span 5}.grid .g-col-sm-6{grid-column:auto/span 6}.grid .g-col-sm-7{grid-column:auto/span 7}.grid .g-col-sm-8{grid-column:auto/span 8}.grid .g-col-sm-9{grid-column:auto/span 9}.grid .g-col-sm-10{grid-column:auto/span 10}.grid .g-col-sm-11{grid-column:auto/span 11}.grid .g-col-sm-12{grid-column:auto/span 12}.grid .g-start-sm-1{grid-column-start:1}.grid .g-start-sm-2{grid-column-start:2}.grid .g-start-sm-3{grid-column-start:3}.grid .g-start-sm-4{grid-column-start:4}.grid .g-start-sm-5{grid-column-start:5}.grid .g-start-sm-6{grid-column-start:6}.grid .g-start-sm-7{grid-column-start:7}.grid .g-start-sm-8{grid-column-start:8}.grid .g-start-sm-9{grid-column-start:9}.grid .g-start-sm-10{grid-column-start:10}.grid .g-start-sm-11{grid-column-start:11}}@media(min-width: 768px){.grid .g-col-md-1{grid-column:auto/span 1}.grid .g-col-md-2{grid-column:auto/span 2}.grid .g-col-md-3{grid-column:auto/span 3}.grid .g-col-md-4{grid-column:auto/span 4}.grid .g-col-md-5{grid-column:auto/span 5}.grid .g-col-md-6{grid-column:auto/span 6}.grid .g-col-md-7{grid-column:auto/span 7}.grid .g-col-md-8{grid-column:auto/span 8}.grid .g-col-md-9{grid-column:auto/span 9}.grid .g-col-md-10{grid-column:auto/span 10}.grid .g-col-md-11{grid-column:auto/span 11}.grid .g-col-md-12{grid-column:auto/span 12}.grid .g-start-md-1{grid-column-start:1}.grid .g-start-md-2{grid-column-start:2}.grid .g-start-md-3{grid-column-start:3}.grid .g-start-md-4{grid-column-start:4}.grid .g-start-md-5{grid-column-start:5}.grid .g-start-md-6{grid-column-start:6}.grid .g-start-md-7{grid-column-start:7}.grid .g-start-md-8{grid-column-start:8}.grid .g-start-md-9{grid-column-start:9}.grid .g-start-md-10{grid-column-start:10}.grid .g-start-md-11{grid-column-start:11}}@media(min-width: 992px){.grid .g-col-lg-1{grid-column:auto/span 1}.grid .g-col-lg-2{grid-column:auto/span 2}.grid .g-col-lg-3{grid-column:auto/span 3}.grid .g-col-lg-4{grid-column:auto/span 4}.grid .g-col-lg-5{grid-column:auto/span 5}.grid .g-col-lg-6{grid-column:auto/span 6}.grid .g-col-lg-7{grid-column:auto/span 7}.grid .g-col-lg-8{grid-column:auto/span 8}.grid .g-col-lg-9{grid-column:auto/span 9}.grid .g-col-lg-10{grid-column:auto/span 10}.grid .g-col-lg-11{grid-column:auto/span 11}.grid .g-col-lg-12{grid-column:auto/span 12}.grid .g-start-lg-1{grid-column-start:1}.grid .g-start-lg-2{grid-column-start:2}.grid .g-start-lg-3{grid-column-start:3}.grid .g-start-lg-4{grid-column-start:4}.grid .g-start-lg-5{grid-column-start:5}.grid .g-start-lg-6{grid-column-start:6}.grid .g-start-lg-7{grid-column-start:7}.grid .g-start-lg-8{grid-column-start:8}.grid .g-start-lg-9{grid-column-start:9}.grid .g-start-lg-10{grid-column-start:10}.grid .g-start-lg-11{grid-column-start:11}}@media(min-width: 1200px){.grid .g-col-xl-1{grid-column:auto/span 1}.grid .g-col-xl-2{grid-column:auto/span 2}.grid .g-col-xl-3{grid-column:auto/span 3}.grid .g-col-xl-4{grid-column:auto/span 4}.grid .g-col-xl-5{grid-column:auto/span 5}.grid .g-col-xl-6{grid-column:auto/span 6}.grid .g-col-xl-7{grid-column:auto/span 7}.grid .g-col-xl-8{grid-column:auto/span 8}.grid .g-col-xl-9{grid-column:auto/span 9}.grid .g-col-xl-10{grid-column:auto/span 10}.grid .g-col-xl-11{grid-column:auto/span 11}.grid .g-col-xl-12{grid-column:auto/span 12}.grid .g-start-xl-1{grid-column-start:1}.grid .g-start-xl-2{grid-column-start:2}.grid .g-start-xl-3{grid-column-start:3}.grid .g-start-xl-4{grid-column-start:4}.grid .g-start-xl-5{grid-column-start:5}.grid .g-start-xl-6{grid-column-start:6}.grid .g-start-xl-7{grid-column-start:7}.grid .g-start-xl-8{grid-column-start:8}.grid .g-start-xl-9{grid-column-start:9}.grid .g-start-xl-10{grid-column-start:10}.grid .g-start-xl-11{grid-column-start:11}}@media(min-width: 1400px){.grid .g-col-xxl-1{grid-column:auto/span 1}.grid .g-col-xxl-2{grid-column:auto/span 2}.grid .g-col-xxl-3{grid-column:auto/span 3}.grid .g-col-xxl-4{grid-column:auto/span 4}.grid .g-col-xxl-5{grid-column:auto/span 5}.grid .g-col-xxl-6{grid-column:auto/span 6}.grid .g-col-xxl-7{grid-column:auto/span 7}.grid .g-col-xxl-8{grid-column:auto/span 8}.grid .g-col-xxl-9{grid-column:auto/span 9}.grid .g-col-xxl-10{grid-column:auto/span 10}.grid .g-col-xxl-11{grid-column:auto/span 11}.grid .g-col-xxl-12{grid-column:auto/span 12}.grid .g-start-xxl-1{grid-column-start:1}.grid .g-start-xxl-2{grid-column-start:2}.grid .g-start-xxl-3{grid-column-start:3}.grid .g-start-xxl-4{grid-column-start:4}.grid .g-start-xxl-5{grid-column-start:5}.grid .g-start-xxl-6{grid-column-start:6}.grid .g-start-xxl-7{grid-column-start:7}.grid .g-start-xxl-8{grid-column-start:8}.grid .g-start-xxl-9{grid-column-start:9}.grid .g-start-xxl-10{grid-column-start:10}.grid .g-start-xxl-11{grid-column-start:11}}.table{--bs-table-color-type: initial;--bs-table-bg-type: initial;--bs-table-color-state: initial;--bs-table-bg-state: initial;--bs-table-color: #fff;--bs-table-bg: #222;--bs-table-border-color: #434343;--bs-table-accent-bg: transparent;--bs-table-striped-color: #fff;--bs-table-striped-bg: rgba(0, 0, 0, 0.05);--bs-table-active-color: #fff;--bs-table-active-bg: rgba(0, 0, 0, 0.1);--bs-table-hover-color: #fff;--bs-table-hover-bg: rgba(0, 0, 0, 0.075);width:100%;margin-bottom:1rem;vertical-align:top;border-color:var(--bs-table-border-color)}.table>:not(caption)>*>*{padding:.5rem .5rem;color:var(--bs-table-color-state, var(--bs-table-color-type, var(--bs-table-color)));background-color:var(--bs-table-bg);border-bottom-width:1px;box-shadow:inset 0 0 0 9999px var(--bs-table-bg-state, var(--bs-table-bg-type, var(--bs-table-accent-bg)))}.table>tbody{vertical-align:inherit}.table>thead{vertical-align:bottom}.table-group-divider{border-top:calc(1px*2) solid #fff}.caption-top{caption-side:top}.table-sm>:not(caption)>*>*{padding:.25rem .25rem}.table-bordered>:not(caption)>*{border-width:1px 0}.table-bordered>:not(caption)>*>*{border-width:0 1px}.table-borderless>:not(caption)>*>*{border-bottom-width:0}.table-borderless>:not(:first-child){border-top-width:0}.table-striped>tbody>tr:nth-of-type(odd)>*{--bs-table-color-type: var(--bs-table-striped-color);--bs-table-bg-type: var(--bs-table-striped-bg)}.table-striped-columns>:not(caption)>tr>:nth-child(even){--bs-table-color-type: var(--bs-table-striped-color);--bs-table-bg-type: var(--bs-table-striped-bg)}.table-active{--bs-table-color-state: var(--bs-table-active-color);--bs-table-bg-state: var(--bs-table-active-bg)}.table-hover>tbody>tr:hover>*{--bs-table-color-state: var(--bs-table-hover-color);--bs-table-bg-state: var(--bs-table-hover-bg)}.table-primary{--bs-table-color: #fff;--bs-table-bg: #375a7f;--bs-table-border-color: #4b6b8c;--bs-table-striped-bg: #416285;--bs-table-striped-color: #fff;--bs-table-active-bg: #4b6b8c;--bs-table-active-color: #fff;--bs-table-hover-bg: #466689;--bs-table-hover-color: #fff;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-secondary{--bs-table-color: #fff;--bs-table-bg: #434343;--bs-table-border-color: #565656;--bs-table-striped-bg: #4c4c4c;--bs-table-striped-color: #fff;--bs-table-active-bg: #565656;--bs-table-active-color: #fff;--bs-table-hover-bg: #515151;--bs-table-hover-color: #fff;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-success{--bs-table-color: #fff;--bs-table-bg: #00bc8c;--bs-table-border-color: #1ac398;--bs-table-striped-bg: #0dbf92;--bs-table-striped-color: #fff;--bs-table-active-bg: #1ac398;--bs-table-active-color: #fff;--bs-table-hover-bg: #13c195;--bs-table-hover-color: #fff;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-info{--bs-table-color: #fff;--bs-table-bg: #3498db;--bs-table-border-color: #48a2df;--bs-table-striped-bg: #3e9ddd;--bs-table-striped-color: #fff;--bs-table-active-bg: #48a2df;--bs-table-active-color: #fff;--bs-table-hover-bg: #43a0de;--bs-table-hover-color: #fff;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-warning{--bs-table-color: #fff;--bs-table-bg: #f39c12;--bs-table-border-color: #f4a62a;--bs-table-striped-bg: #f4a11e;--bs-table-striped-color: #fff;--bs-table-active-bg: #f4a62a;--bs-table-active-color: #fff;--bs-table-hover-bg: #f4a324;--bs-table-hover-color: #fff;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-danger{--bs-table-color: #fff;--bs-table-bg: #e74c3c;--bs-table-border-color: #e95e50;--bs-table-striped-bg: #e85546;--bs-table-striped-color: #fff;--bs-table-active-bg: #e95e50;--bs-table-active-color: #fff;--bs-table-hover-bg: #e9594b;--bs-table-hover-color: #fff;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-light{--bs-table-color: #fff;--bs-table-bg: #6f6f6f;--bs-table-border-color: #7d7d7d;--bs-table-striped-bg: #767676;--bs-table-striped-color: #fff;--bs-table-active-bg: #7d7d7d;--bs-table-active-color: #fff;--bs-table-hover-bg: #7a7a7a;--bs-table-hover-color: #fff;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-dark{--bs-table-color: #fff;--bs-table-bg: #2d2d2d;--bs-table-border-color: #424242;--bs-table-striped-bg: #383838;--bs-table-striped-color: #fff;--bs-table-active-bg: #424242;--bs-table-active-color: #fff;--bs-table-hover-bg: #3d3d3d;--bs-table-hover-color: #fff;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-responsive{overflow-x:auto;-webkit-overflow-scrolling:touch}@media(max-width: 575.98px){.table-responsive-sm{overflow-x:auto;-webkit-overflow-scrolling:touch}}@media(max-width: 767.98px){.table-responsive-md{overflow-x:auto;-webkit-overflow-scrolling:touch}}@media(max-width: 991.98px){.table-responsive-lg{overflow-x:auto;-webkit-overflow-scrolling:touch}}@media(max-width: 1199.98px){.table-responsive-xl{overflow-x:auto;-webkit-overflow-scrolling:touch}}@media(max-width: 1399.98px){.table-responsive-xxl{overflow-x:auto;-webkit-overflow-scrolling:touch}}.form-label,.shiny-input-container .control-label{margin-bottom:.5rem}.col-form-label{padding-top:calc(0.375rem + 1px);padding-bottom:calc(0.375rem + 1px);margin-bottom:0;font-size:inherit;line-height:1.5}.col-form-label-lg{padding-top:calc(0.5rem + 1px);padding-bottom:calc(0.5rem + 1px);font-size:1.25rem}.col-form-label-sm{padding-top:calc(0.25rem + 1px);padding-bottom:calc(0.25rem + 1px);font-size:0.875rem}.form-text{margin-top:.25rem;font-size:0.875em;color:rgba(255,255,255,.75)}.form-control{display:block;width:100%;padding:.375rem .75rem;font-size:1rem;font-weight:400;line-height:1.5;color:#2d2d2d;appearance:none;-webkit-appearance:none;-moz-appearance:none;-ms-appearance:none;-o-appearance:none;background-color:#fff;background-clip:padding-box;border:1px solid #adb5bd;border-radius:.25rem;transition:border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media(prefers-reduced-motion: reduce){.form-control{transition:none}}.form-control[type=file]{overflow:hidden}.form-control[type=file]:not(:disabled):not([readonly]){cursor:pointer}.form-control:focus{color:#2d2d2d;background-color:#fff;border-color:#9badbf;outline:0;box-shadow:0 0 0 .25rem rgba(55,90,127,.25)}.form-control::-webkit-date-and-time-value{min-width:85px;height:1.5em;margin:0}.form-control::-webkit-datetime-edit{display:block;padding:0}.form-control::placeholder{color:#595959;opacity:1}.form-control:disabled{background-color:#ebebeb;opacity:1}.form-control::file-selector-button{padding:.375rem .75rem;margin:-0.375rem -0.75rem;margin-inline-end:.75rem;color:#6f6f6f;background-color:#434343;pointer-events:none;border-color:inherit;border-style:solid;border-width:0;border-inline-end-width:1px;border-radius:0;transition:color .15s ease-in-out,background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media(prefers-reduced-motion: reduce){.form-control::file-selector-button{transition:none}}.form-control:hover:not(:disabled):not([readonly])::file-selector-button{background-color:#363636}.form-control-plaintext{display:block;width:100%;padding:.375rem 0;margin-bottom:0;line-height:1.5;color:#fff;background-color:rgba(0,0,0,0);border:solid rgba(0,0,0,0);border-width:1px 0}.form-control-plaintext:focus{outline:0}.form-control-plaintext.form-control-sm,.form-control-plaintext.form-control-lg{padding-right:0;padding-left:0}.form-control-sm{min-height:calc(1.5em + 0.5rem + calc(1px * 2));padding:.25rem .5rem;font-size:0.875rem;border-radius:.2em}.form-control-sm::file-selector-button{padding:.25rem .5rem;margin:-0.25rem -0.5rem;margin-inline-end:.5rem}.form-control-lg{min-height:calc(1.5em + 1rem + calc(1px * 2));padding:.5rem 1rem;font-size:1.25rem;border-radius:.5rem}.form-control-lg::file-selector-button{padding:.5rem 1rem;margin:-0.5rem -1rem;margin-inline-end:1rem}textarea.form-control{min-height:calc(1.5em + 0.75rem + calc(1px * 2))}textarea.form-control-sm{min-height:calc(1.5em + 0.5rem + calc(1px * 2))}textarea.form-control-lg{min-height:calc(1.5em + 1rem + calc(1px * 2))}.form-control-color{width:3rem;height:calc(1.5em + 0.75rem + calc(1px * 2));padding:.375rem}.form-control-color:not(:disabled):not([readonly]){cursor:pointer}.form-control-color::-moz-color-swatch{border:0 !important;border-radius:.25rem}.form-control-color::-webkit-color-swatch{border:0 !important;border-radius:.25rem}.form-control-color.form-control-sm{height:calc(1.5em + 0.5rem + calc(1px * 2))}.form-control-color.form-control-lg{height:calc(1.5em + 1rem + calc(1px * 2))}.form-select{--bs-form-select-bg-img: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3e%3cpath fill='none' stroke='%23343a40' stroke-linecap='round' stroke-linejoin='round' stroke-width='2' d='m2 5 6 6 6-6'/%3e%3c/svg%3e");display:block;width:100%;padding:.375rem 2.25rem .375rem .75rem;font-size:1rem;font-weight:400;line-height:1.5;color:#2d2d2d;appearance:none;-webkit-appearance:none;-moz-appearance:none;-ms-appearance:none;-o-appearance:none;background-color:#fff;background-image:var(--bs-form-select-bg-img),var(--bs-form-select-bg-icon, none);background-repeat:no-repeat;background-position:right .75rem center;background-size:16px 12px;border:1px solid #adb5bd;border-radius:.25rem;transition:border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media(prefers-reduced-motion: reduce){.form-select{transition:none}}.form-select:focus{border-color:#9badbf;outline:0;box-shadow:0 0 0 .25rem rgba(55,90,127,.25)}.form-select[multiple],.form-select[size]:not([size="1"]){padding-right:.75rem;background-image:none}.form-select:disabled{color:#595959;background-color:#ebebeb}.form-select:-moz-focusring{color:rgba(0,0,0,0);text-shadow:0 0 0 #2d2d2d}.form-select-sm{padding-top:.25rem;padding-bottom:.25rem;padding-left:.5rem;font-size:0.875rem;border-radius:.2em}.form-select-lg{padding-top:.5rem;padding-bottom:.5rem;padding-left:1rem;font-size:1.25rem;border-radius:.5rem}[data-bs-theme=dark] .form-select{--bs-form-select-bg-img: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3e%3cpath fill='none' stroke='%23dee2e6' stroke-linecap='round' stroke-linejoin='round' stroke-width='2' d='m2 5 6 6 6-6'/%3e%3c/svg%3e")}.form-check,.shiny-input-container .checkbox,.shiny-input-container .radio{display:block;min-height:1.5rem;padding-left:0;margin-bottom:.125rem}.form-check .form-check-input,.form-check .shiny-input-container .checkbox input,.form-check .shiny-input-container .radio input,.shiny-input-container .checkbox .form-check-input,.shiny-input-container .checkbox .shiny-input-container .checkbox input,.shiny-input-container .checkbox .shiny-input-container .radio input,.shiny-input-container .radio .form-check-input,.shiny-input-container .radio .shiny-input-container .checkbox input,.shiny-input-container .radio .shiny-input-container .radio input{float:left;margin-left:0}.form-check-reverse{padding-right:0;padding-left:0;text-align:right}.form-check-reverse .form-check-input{float:right;margin-right:0;margin-left:0}.form-check-input,.shiny-input-container .checkbox input,.shiny-input-container .checkbox-inline input,.shiny-input-container .radio input,.shiny-input-container .radio-inline input{--bs-form-check-bg: #fff;width:1em;height:1em;margin-top:.25em;vertical-align:top;appearance:none;-webkit-appearance:none;-moz-appearance:none;-ms-appearance:none;-o-appearance:none;background-color:var(--bs-form-check-bg);background-image:var(--bs-form-check-bg-image);background-repeat:no-repeat;background-position:center;background-size:contain;border:none;print-color-adjust:exact}.form-check-input[type=checkbox],.shiny-input-container .checkbox input[type=checkbox],.shiny-input-container .checkbox-inline input[type=checkbox],.shiny-input-container .radio input[type=checkbox],.shiny-input-container .radio-inline input[type=checkbox]{border-radius:.25em}.form-check-input[type=radio],.shiny-input-container .checkbox input[type=radio],.shiny-input-container .checkbox-inline input[type=radio],.shiny-input-container .radio input[type=radio],.shiny-input-container .radio-inline input[type=radio]{border-radius:50%}.form-check-input:active,.shiny-input-container .checkbox input:active,.shiny-input-container .checkbox-inline input:active,.shiny-input-container .radio input:active,.shiny-input-container .radio-inline input:active{filter:brightness(90%)}.form-check-input:focus,.shiny-input-container .checkbox input:focus,.shiny-input-container .checkbox-inline input:focus,.shiny-input-container .radio input:focus,.shiny-input-container .radio-inline input:focus{border-color:#9badbf;outline:0;box-shadow:0 0 0 .25rem rgba(55,90,127,.25)}.form-check-input:checked,.shiny-input-container .checkbox input:checked,.shiny-input-container .checkbox-inline input:checked,.shiny-input-container .radio input:checked,.shiny-input-container .radio-inline input:checked{background-color:#375a7f;border-color:#375a7f}.form-check-input:checked[type=checkbox],.shiny-input-container .checkbox input:checked[type=checkbox],.shiny-input-container .checkbox-inline input:checked[type=checkbox],.shiny-input-container .radio input:checked[type=checkbox],.shiny-input-container .radio-inline input:checked[type=checkbox]{--bs-form-check-bg-image: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20'%3e%3cpath fill='none' stroke='%23fff' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='m6 10 3 3 6-6'/%3e%3c/svg%3e")}.form-check-input:checked[type=radio],.shiny-input-container .checkbox input:checked[type=radio],.shiny-input-container .checkbox-inline input:checked[type=radio],.shiny-input-container .radio input:checked[type=radio],.shiny-input-container .radio-inline input:checked[type=radio]{--bs-form-check-bg-image: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='-4 -4 8 8'%3e%3ccircle r='2' fill='%23fff'/%3e%3c/svg%3e")}.form-check-input[type=checkbox]:indeterminate,.shiny-input-container .checkbox input[type=checkbox]:indeterminate,.shiny-input-container .checkbox-inline input[type=checkbox]:indeterminate,.shiny-input-container .radio input[type=checkbox]:indeterminate,.shiny-input-container .radio-inline input[type=checkbox]:indeterminate{background-color:#375a7f;border-color:#375a7f;--bs-form-check-bg-image: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20'%3e%3cpath fill='none' stroke='%23fff' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='M6 10h8'/%3e%3c/svg%3e")}.form-check-input:disabled,.shiny-input-container .checkbox input:disabled,.shiny-input-container .checkbox-inline input:disabled,.shiny-input-container .radio input:disabled,.shiny-input-container .radio-inline input:disabled{pointer-events:none;filter:none;opacity:.5}.form-check-input[disabled]~.form-check-label,.form-check-input[disabled]~span,.form-check-input:disabled~.form-check-label,.form-check-input:disabled~span,.shiny-input-container .checkbox input[disabled]~.form-check-label,.shiny-input-container .checkbox input[disabled]~span,.shiny-input-container .checkbox input:disabled~.form-check-label,.shiny-input-container .checkbox input:disabled~span,.shiny-input-container .checkbox-inline input[disabled]~.form-check-label,.shiny-input-container .checkbox-inline input[disabled]~span,.shiny-input-container .checkbox-inline input:disabled~.form-check-label,.shiny-input-container .checkbox-inline input:disabled~span,.shiny-input-container .radio input[disabled]~.form-check-label,.shiny-input-container .radio input[disabled]~span,.shiny-input-container .radio input:disabled~.form-check-label,.shiny-input-container .radio input:disabled~span,.shiny-input-container .radio-inline input[disabled]~.form-check-label,.shiny-input-container .radio-inline input[disabled]~span,.shiny-input-container .radio-inline input:disabled~.form-check-label,.shiny-input-container .radio-inline input:disabled~span{cursor:default;opacity:.5}.form-check-label,.shiny-input-container .checkbox label,.shiny-input-container .checkbox-inline label,.shiny-input-container .radio label,.shiny-input-container .radio-inline label{cursor:pointer}.form-switch{padding-left:2.5em}.form-switch .form-check-input{--bs-form-switch-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='-4 -4 8 8'%3e%3ccircle r='3' fill='rgba%280, 0, 0, 0.25%29'/%3e%3c/svg%3e");width:2em;margin-left:-2.5em;background-image:var(--bs-form-switch-bg);background-position:left center;border-radius:2em;transition:background-position .15s ease-in-out}@media(prefers-reduced-motion: reduce){.form-switch .form-check-input{transition:none}}.form-switch .form-check-input:focus{--bs-form-switch-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='-4 -4 8 8'%3e%3ccircle r='3' fill='%239badbf'/%3e%3c/svg%3e")}.form-switch .form-check-input:checked{background-position:right center;--bs-form-switch-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='-4 -4 8 8'%3e%3ccircle r='3' fill='%23fff'/%3e%3c/svg%3e")}.form-switch.form-check-reverse{padding-right:2.5em;padding-left:0}.form-switch.form-check-reverse .form-check-input{margin-right:-2.5em;margin-left:0}.form-check-inline{display:inline-block;margin-right:1rem}.btn-check{position:absolute;clip:rect(0, 0, 0, 0);pointer-events:none}.btn-check[disabled]+.btn,.btn-check:disabled+.btn{pointer-events:none;filter:none;opacity:.65}[data-bs-theme=dark] .form-switch .form-check-input:not(:checked):not(:focus){--bs-form-switch-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='-4 -4 8 8'%3e%3ccircle r='3' fill='rgba%28255, 255, 255, 0.25%29'/%3e%3c/svg%3e")}.form-range{width:100%;height:1.5rem;padding:0;appearance:none;-webkit-appearance:none;-moz-appearance:none;-ms-appearance:none;-o-appearance:none;background-color:rgba(0,0,0,0)}.form-range:focus{outline:0}.form-range:focus::-webkit-slider-thumb{box-shadow:0 0 0 1px #222,0 0 0 .25rem rgba(55,90,127,.25)}.form-range:focus::-moz-range-thumb{box-shadow:0 0 0 1px #222,0 0 0 .25rem rgba(55,90,127,.25)}.form-range::-moz-focus-outer{border:0}.form-range::-webkit-slider-thumb{width:1rem;height:1rem;margin-top:-0.25rem;appearance:none;-webkit-appearance:none;-moz-appearance:none;-ms-appearance:none;-o-appearance:none;background-color:#375a7f;border:0;border-radius:1rem;transition:background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media(prefers-reduced-motion: reduce){.form-range::-webkit-slider-thumb{transition:none}}.form-range::-webkit-slider-thumb:active{background-color:#c3ced9}.form-range::-webkit-slider-runnable-track{width:100%;height:.5rem;color:rgba(0,0,0,0);cursor:pointer;background-color:#f8f9fa;border-color:rgba(0,0,0,0);border-radius:1rem}.form-range::-moz-range-thumb{width:1rem;height:1rem;appearance:none;-webkit-appearance:none;-moz-appearance:none;-ms-appearance:none;-o-appearance:none;background-color:#375a7f;border:0;border-radius:1rem;transition:background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media(prefers-reduced-motion: reduce){.form-range::-moz-range-thumb{transition:none}}.form-range::-moz-range-thumb:active{background-color:#c3ced9}.form-range::-moz-range-track{width:100%;height:.5rem;color:rgba(0,0,0,0);cursor:pointer;background-color:#f8f9fa;border-color:rgba(0,0,0,0);border-radius:1rem}.form-range:disabled{pointer-events:none}.form-range:disabled::-webkit-slider-thumb{background-color:rgba(255,255,255,.75)}.form-range:disabled::-moz-range-thumb{background-color:rgba(255,255,255,.75)}.form-floating{position:relative}.form-floating>.form-control,.form-floating>.form-control-plaintext,.form-floating>.form-select{height:calc(3.5rem + calc(1px * 2));min-height:calc(3.5rem + calc(1px * 2));line-height:1.25}.form-floating>label{position:absolute;top:0;left:0;z-index:2;height:100%;padding:1rem .75rem;overflow:hidden;text-align:start;text-overflow:ellipsis;white-space:nowrap;pointer-events:none;border:1px solid rgba(0,0,0,0);transform-origin:0 0;transition:opacity .1s ease-in-out,transform .1s ease-in-out}@media(prefers-reduced-motion: reduce){.form-floating>label{transition:none}}.form-floating>.form-control,.form-floating>.form-control-plaintext{padding:1rem .75rem}.form-floating>.form-control::placeholder,.form-floating>.form-control-plaintext::placeholder{color:rgba(0,0,0,0)}.form-floating>.form-control:focus,.form-floating>.form-control:not(:placeholder-shown),.form-floating>.form-control-plaintext:focus,.form-floating>.form-control-plaintext:not(:placeholder-shown){padding-top:1.625rem;padding-bottom:.625rem}.form-floating>.form-control:-webkit-autofill,.form-floating>.form-control-plaintext:-webkit-autofill{padding-top:1.625rem;padding-bottom:.625rem}.form-floating>.form-select{padding-top:1.625rem;padding-bottom:.625rem}.form-floating>.form-control:focus~label,.form-floating>.form-control:not(:placeholder-shown)~label,.form-floating>.form-control-plaintext~label,.form-floating>.form-select~label{color:rgba(var(--bs-body-color-rgb), 0.65);transform:scale(0.85) translateY(-0.5rem) translateX(0.15rem)}.form-floating>.form-control:focus~label::after,.form-floating>.form-control:not(:placeholder-shown)~label::after,.form-floating>.form-control-plaintext~label::after,.form-floating>.form-select~label::after{position:absolute;inset:1rem .375rem;z-index:-1;height:1.5em;content:"";background-color:#fff;border-radius:.25rem}.form-floating>.form-control:-webkit-autofill~label{color:rgba(var(--bs-body-color-rgb), 0.65);transform:scale(0.85) translateY(-0.5rem) translateX(0.15rem)}.form-floating>.form-control-plaintext~label{border-width:1px 0}.form-floating>:disabled~label,.form-floating>.form-control:disabled~label{color:#6c757d}.form-floating>:disabled~label::after,.form-floating>.form-control:disabled~label::after{background-color:#ebebeb}.input-group{position:relative;display:flex;display:-webkit-flex;flex-wrap:wrap;-webkit-flex-wrap:wrap;align-items:stretch;-webkit-align-items:stretch;width:100%}.input-group>.form-control,.input-group>.form-select,.input-group>.form-floating{position:relative;flex:1 1 auto;-webkit-flex:1 1 auto;width:1%;min-width:0}.input-group>.form-control:focus,.input-group>.form-select:focus,.input-group>.form-floating:focus-within{z-index:5}.input-group .btn{position:relative;z-index:2}.input-group .btn:focus{z-index:5}.input-group-text{display:flex;display:-webkit-flex;align-items:center;-webkit-align-items:center;padding:.375rem .75rem;font-size:1rem;font-weight:400;line-height:1.5;color:#6f6f6f;text-align:center;white-space:nowrap;background-color:#434343;border:1px solid #adb5bd;border-radius:.25rem}.input-group-lg>.form-control,.input-group-lg>.form-select,.input-group-lg>.input-group-text,.input-group-lg>.btn{padding:.5rem 1rem;font-size:1.25rem;border-radius:.5rem}.input-group-sm>.form-control,.input-group-sm>.form-select,.input-group-sm>.input-group-text,.input-group-sm>.btn{padding:.25rem .5rem;font-size:0.875rem;border-radius:.2em}.input-group-lg>.form-select,.input-group-sm>.form-select{padding-right:3rem}.input-group:not(.has-validation)>:not(:last-child):not(.dropdown-toggle):not(.dropdown-menu):not(.form-floating),.input-group:not(.has-validation)>.dropdown-toggle:nth-last-child(n+3),.input-group:not(.has-validation)>.form-floating:not(:last-child)>.form-control,.input-group:not(.has-validation)>.form-floating:not(:last-child)>.form-select{border-top-right-radius:0;border-bottom-right-radius:0}.input-group.has-validation>:nth-last-child(n+3):not(.dropdown-toggle):not(.dropdown-menu):not(.form-floating),.input-group.has-validation>.dropdown-toggle:nth-last-child(n+4),.input-group.has-validation>.form-floating:nth-last-child(n+3)>.form-control,.input-group.has-validation>.form-floating:nth-last-child(n+3)>.form-select{border-top-right-radius:0;border-bottom-right-radius:0}.input-group>:not(:first-child):not(.dropdown-menu):not(.valid-tooltip):not(.valid-feedback):not(.invalid-tooltip):not(.invalid-feedback){margin-left:calc(1px*-1);border-top-left-radius:0;border-bottom-left-radius:0}.input-group>.form-floating:not(:first-child)>.form-control,.input-group>.form-floating:not(:first-child)>.form-select{border-top-left-radius:0;border-bottom-left-radius:0}.valid-feedback{display:none;width:100%;margin-top:.25rem;font-size:0.875em;color:#00bc8c}.valid-tooltip{position:absolute;top:100%;z-index:5;display:none;max-width:100%;padding:.25rem .5rem;margin-top:.1rem;font-size:0.875rem;color:#fff;background-color:#00bc8c;border-radius:.25rem}.was-validated :valid~.valid-feedback,.was-validated :valid~.valid-tooltip,.is-valid~.valid-feedback,.is-valid~.valid-tooltip{display:block}.was-validated .form-control:valid,.form-control.is-valid{border-color:#00bc8c;padding-right:calc(1.5em + 0.75rem);background-image:url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 8 8'%3e%3cpath fill='%2300bc8c' d='M2.3 6.73.6 4.53c-.4-1.04.46-1.4 1.1-.8l1.1 1.4 3.4-3.8c.6-.63 1.6-.27 1.2.7l-4 4.6c-.43.5-.8.4-1.1.1z'/%3e%3c/svg%3e");background-repeat:no-repeat;background-position:right calc(0.375em + 0.1875rem) center;background-size:calc(0.75em + 0.375rem) calc(0.75em + 0.375rem)}.was-validated .form-control:valid:focus,.form-control.is-valid:focus{border-color:#00bc8c;box-shadow:0 0 0 .25rem rgba(0,188,140,.25)}.was-validated textarea.form-control:valid,textarea.form-control.is-valid{padding-right:calc(1.5em + 0.75rem);background-position:top calc(0.375em + 0.1875rem) right calc(0.375em + 0.1875rem)}.was-validated .form-select:valid,.form-select.is-valid{border-color:#00bc8c}.was-validated .form-select:valid:not([multiple]):not([size]),.was-validated .form-select:valid:not([multiple])[size="1"],.form-select.is-valid:not([multiple]):not([size]),.form-select.is-valid:not([multiple])[size="1"]{--bs-form-select-bg-icon: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 8 8'%3e%3cpath fill='%2300bc8c' d='M2.3 6.73.6 4.53c-.4-1.04.46-1.4 1.1-.8l1.1 1.4 3.4-3.8c.6-.63 1.6-.27 1.2.7l-4 4.6c-.43.5-.8.4-1.1.1z'/%3e%3c/svg%3e");padding-right:4.125rem;background-position:right .75rem center,center right 2.25rem;background-size:16px 12px,calc(0.75em + 0.375rem) calc(0.75em + 0.375rem)}.was-validated .form-select:valid:focus,.form-select.is-valid:focus{border-color:#00bc8c;box-shadow:0 0 0 .25rem rgba(0,188,140,.25)}.was-validated .form-control-color:valid,.form-control-color.is-valid{width:calc(3rem + calc(1.5em + 0.75rem))}.was-validated .form-check-input:valid,.form-check-input.is-valid{border-color:#00bc8c}.was-validated .form-check-input:valid:checked,.form-check-input.is-valid:checked{background-color:#00bc8c}.was-validated .form-check-input:valid:focus,.form-check-input.is-valid:focus{box-shadow:0 0 0 .25rem rgba(0,188,140,.25)}.was-validated .form-check-input:valid~.form-check-label,.form-check-input.is-valid~.form-check-label{color:#00bc8c}.form-check-inline .form-check-input~.valid-feedback{margin-left:.5em}.was-validated .input-group>.form-control:not(:focus):valid,.input-group>.form-control:not(:focus).is-valid,.was-validated .input-group>.form-select:not(:focus):valid,.input-group>.form-select:not(:focus).is-valid,.was-validated .input-group>.form-floating:not(:focus-within):valid,.input-group>.form-floating:not(:focus-within).is-valid{z-index:3}.invalid-feedback{display:none;width:100%;margin-top:.25rem;font-size:0.875em;color:#e74c3c}.invalid-tooltip{position:absolute;top:100%;z-index:5;display:none;max-width:100%;padding:.25rem .5rem;margin-top:.1rem;font-size:0.875rem;color:#fff;background-color:#e74c3c;border-radius:.25rem}.was-validated :invalid~.invalid-feedback,.was-validated :invalid~.invalid-tooltip,.is-invalid~.invalid-feedback,.is-invalid~.invalid-tooltip{display:block}.was-validated .form-control:invalid,.form-control.is-invalid{border-color:#e74c3c;padding-right:calc(1.5em + 0.75rem);background-image:url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12' width='12' height='12' fill='none' stroke='%23e74c3c'%3e%3ccircle cx='6' cy='6' r='4.5'/%3e%3cpath stroke-linejoin='round' d='M5.8 3.6h.4L6 6.5z'/%3e%3ccircle cx='6' cy='8.2' r='.6' fill='%23e74c3c' stroke='none'/%3e%3c/svg%3e");background-repeat:no-repeat;background-position:right calc(0.375em + 0.1875rem) center;background-size:calc(0.75em + 0.375rem) calc(0.75em + 0.375rem)}.was-validated .form-control:invalid:focus,.form-control.is-invalid:focus{border-color:#e74c3c;box-shadow:0 0 0 .25rem rgba(231,76,60,.25)}.was-validated textarea.form-control:invalid,textarea.form-control.is-invalid{padding-right:calc(1.5em + 0.75rem);background-position:top calc(0.375em + 0.1875rem) right calc(0.375em + 0.1875rem)}.was-validated .form-select:invalid,.form-select.is-invalid{border-color:#e74c3c}.was-validated .form-select:invalid:not([multiple]):not([size]),.was-validated .form-select:invalid:not([multiple])[size="1"],.form-select.is-invalid:not([multiple]):not([size]),.form-select.is-invalid:not([multiple])[size="1"]{--bs-form-select-bg-icon: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12' width='12' height='12' fill='none' stroke='%23e74c3c'%3e%3ccircle cx='6' cy='6' r='4.5'/%3e%3cpath stroke-linejoin='round' d='M5.8 3.6h.4L6 6.5z'/%3e%3ccircle cx='6' cy='8.2' r='.6' fill='%23e74c3c' stroke='none'/%3e%3c/svg%3e");padding-right:4.125rem;background-position:right .75rem center,center right 2.25rem;background-size:16px 12px,calc(0.75em + 0.375rem) calc(0.75em + 0.375rem)}.was-validated .form-select:invalid:focus,.form-select.is-invalid:focus{border-color:#e74c3c;box-shadow:0 0 0 .25rem rgba(231,76,60,.25)}.was-validated .form-control-color:invalid,.form-control-color.is-invalid{width:calc(3rem + calc(1.5em + 0.75rem))}.was-validated .form-check-input:invalid,.form-check-input.is-invalid{border-color:#e74c3c}.was-validated .form-check-input:invalid:checked,.form-check-input.is-invalid:checked{background-color:#e74c3c}.was-validated .form-check-input:invalid:focus,.form-check-input.is-invalid:focus{box-shadow:0 0 0 .25rem rgba(231,76,60,.25)}.was-validated .form-check-input:invalid~.form-check-label,.form-check-input.is-invalid~.form-check-label{color:#e74c3c}.form-check-inline .form-check-input~.invalid-feedback{margin-left:.5em}.was-validated .input-group>.form-control:not(:focus):invalid,.input-group>.form-control:not(:focus).is-invalid,.was-validated .input-group>.form-select:not(:focus):invalid,.input-group>.form-select:not(:focus).is-invalid,.was-validated .input-group>.form-floating:not(:focus-within):invalid,.input-group>.form-floating:not(:focus-within).is-invalid{z-index:4}.btn{--bs-btn-padding-x: 0.75rem;--bs-btn-padding-y: 0.375rem;--bs-btn-font-family: ;--bs-btn-font-size:1rem;--bs-btn-font-weight: 400;--bs-btn-line-height: 1.5;--bs-btn-color: #fff;--bs-btn-bg: transparent;--bs-btn-border-width: 1px;--bs-btn-border-color: transparent;--bs-btn-border-radius: 0.25rem;--bs-btn-hover-border-color: transparent;--bs-btn-box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.15), 0 1px 1px rgba(0, 0, 0, 0.075);--bs-btn-disabled-opacity: 0.65;--bs-btn-focus-box-shadow: 0 0 0 0.25rem rgba(var(--bs-btn-focus-shadow-rgb), .5);display:inline-block;padding:var(--bs-btn-padding-y) var(--bs-btn-padding-x);font-family:var(--bs-btn-font-family);font-size:var(--bs-btn-font-size);font-weight:var(--bs-btn-font-weight);line-height:var(--bs-btn-line-height);color:var(--bs-btn-color);text-align:center;text-decoration:none;-webkit-text-decoration:none;-moz-text-decoration:none;-ms-text-decoration:none;-o-text-decoration:none;vertical-align:middle;cursor:pointer;user-select:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;-o-user-select:none;border:var(--bs-btn-border-width) solid var(--bs-btn-border-color);border-radius:var(--bs-btn-border-radius);background-color:var(--bs-btn-bg);transition:color .15s ease-in-out,background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media(prefers-reduced-motion: reduce){.btn{transition:none}}.btn:hover{color:var(--bs-btn-hover-color);background-color:var(--bs-btn-hover-bg);border-color:var(--bs-btn-hover-border-color)}.btn-check+.btn:hover{color:var(--bs-btn-color);background-color:var(--bs-btn-bg);border-color:var(--bs-btn-border-color)}.btn:focus-visible{color:var(--bs-btn-hover-color);background-color:var(--bs-btn-hover-bg);border-color:var(--bs-btn-hover-border-color);outline:0;box-shadow:var(--bs-btn-focus-box-shadow)}.btn-check:focus-visible+.btn{border-color:var(--bs-btn-hover-border-color);outline:0;box-shadow:var(--bs-btn-focus-box-shadow)}.btn-check:checked+.btn,:not(.btn-check)+.btn:active,.btn:first-child:active,.btn.active,.btn.show{color:var(--bs-btn-active-color);background-color:var(--bs-btn-active-bg);border-color:var(--bs-btn-active-border-color)}.btn-check:checked+.btn:focus-visible,:not(.btn-check)+.btn:active:focus-visible,.btn:first-child:active:focus-visible,.btn.active:focus-visible,.btn.show:focus-visible{box-shadow:var(--bs-btn-focus-box-shadow)}.btn:disabled,.btn.disabled,fieldset:disabled .btn{color:var(--bs-btn-disabled-color);pointer-events:none;background-color:var(--bs-btn-disabled-bg);border-color:var(--bs-btn-disabled-border-color);opacity:var(--bs-btn-disabled-opacity)}.btn-default{--bs-btn-color: #fff;--bs-btn-bg: #434343;--bs-btn-border-color: #434343;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #393939;--bs-btn-hover-border-color: #363636;--bs-btn-focus-shadow-rgb: 95, 95, 95;--bs-btn-active-color: #fff;--bs-btn-active-bg: #363636;--bs-btn-active-border-color: #323232;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #434343;--bs-btn-disabled-border-color: #434343}.btn-primary{--bs-btn-color: #fff;--bs-btn-bg: #375a7f;--bs-btn-border-color: #375a7f;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #2f4d6c;--bs-btn-hover-border-color: #2c4866;--bs-btn-focus-shadow-rgb: 85, 115, 146;--bs-btn-active-color: #fff;--bs-btn-active-bg: #2c4866;--bs-btn-active-border-color: #29445f;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #375a7f;--bs-btn-disabled-border-color: #375a7f}.btn-secondary{--bs-btn-color: #fff;--bs-btn-bg: #434343;--bs-btn-border-color: #434343;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #393939;--bs-btn-hover-border-color: #363636;--bs-btn-focus-shadow-rgb: 95, 95, 95;--bs-btn-active-color: #fff;--bs-btn-active-bg: #363636;--bs-btn-active-border-color: #323232;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #434343;--bs-btn-disabled-border-color: #434343}.btn-success{--bs-btn-color: #fff;--bs-btn-bg: #00bc8c;--bs-btn-border-color: #00bc8c;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #00a077;--bs-btn-hover-border-color: #009670;--bs-btn-focus-shadow-rgb: 38, 198, 157;--bs-btn-active-color: #fff;--bs-btn-active-bg: #009670;--bs-btn-active-border-color: #008d69;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #00bc8c;--bs-btn-disabled-border-color: #00bc8c}.btn-info{--bs-btn-color: #fff;--bs-btn-bg: #3498db;--bs-btn-border-color: #3498db;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #2c81ba;--bs-btn-hover-border-color: #2a7aaf;--bs-btn-focus-shadow-rgb: 82, 167, 224;--bs-btn-active-color: #fff;--bs-btn-active-bg: #2a7aaf;--bs-btn-active-border-color: #2772a4;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #3498db;--bs-btn-disabled-border-color: #3498db}.btn-warning{--bs-btn-color: #fff;--bs-btn-bg: #f39c12;--bs-btn-border-color: #f39c12;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #cf850f;--bs-btn-hover-border-color: #c27d0e;--bs-btn-focus-shadow-rgb: 245, 171, 54;--bs-btn-active-color: #fff;--bs-btn-active-bg: #c27d0e;--bs-btn-active-border-color: #b6750e;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #f39c12;--bs-btn-disabled-border-color: #f39c12}.btn-danger{--bs-btn-color: #fff;--bs-btn-bg: #e74c3c;--bs-btn-border-color: #e74c3c;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #c44133;--bs-btn-hover-border-color: #b93d30;--bs-btn-focus-shadow-rgb: 235, 103, 89;--bs-btn-active-color: #fff;--bs-btn-active-bg: #b93d30;--bs-btn-active-border-color: #ad392d;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #e74c3c;--bs-btn-disabled-border-color: #e74c3c}.btn-light{--bs-btn-color: #fff;--bs-btn-bg: #6f6f6f;--bs-btn-border-color: #6f6f6f;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #5e5e5e;--bs-btn-hover-border-color: #595959;--bs-btn-focus-shadow-rgb: 133, 133, 133;--bs-btn-active-color: #fff;--bs-btn-active-bg: #595959;--bs-btn-active-border-color: #535353;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #6f6f6f;--bs-btn-disabled-border-color: #6f6f6f}.btn-dark{--bs-btn-color: #fff;--bs-btn-bg: #2d2d2d;--bs-btn-border-color: #2d2d2d;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #4d4d4d;--bs-btn-hover-border-color: #424242;--bs-btn-focus-shadow-rgb: 77, 77, 77;--bs-btn-active-color: #fff;--bs-btn-active-bg: #575757;--bs-btn-active-border-color: #424242;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #2d2d2d;--bs-btn-disabled-border-color: #2d2d2d}.btn-outline-default{--bs-btn-color: #434343;--bs-btn-border-color: #434343;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #434343;--bs-btn-hover-border-color: #434343;--bs-btn-focus-shadow-rgb: 67, 67, 67;--bs-btn-active-color: #fff;--bs-btn-active-bg: #434343;--bs-btn-active-border-color: #434343;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #434343;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #434343;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-primary{--bs-btn-color: #375a7f;--bs-btn-border-color: #375a7f;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #375a7f;--bs-btn-hover-border-color: #375a7f;--bs-btn-focus-shadow-rgb: 55, 90, 127;--bs-btn-active-color: #fff;--bs-btn-active-bg: #375a7f;--bs-btn-active-border-color: #375a7f;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #375a7f;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #375a7f;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-secondary{--bs-btn-color: #434343;--bs-btn-border-color: #434343;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #434343;--bs-btn-hover-border-color: #434343;--bs-btn-focus-shadow-rgb: 67, 67, 67;--bs-btn-active-color: #fff;--bs-btn-active-bg: #434343;--bs-btn-active-border-color: #434343;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #434343;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #434343;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-success{--bs-btn-color: #00bc8c;--bs-btn-border-color: #00bc8c;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #00bc8c;--bs-btn-hover-border-color: #00bc8c;--bs-btn-focus-shadow-rgb: 0, 188, 140;--bs-btn-active-color: #fff;--bs-btn-active-bg: #00bc8c;--bs-btn-active-border-color: #00bc8c;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #00bc8c;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #00bc8c;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-info{--bs-btn-color: #3498db;--bs-btn-border-color: #3498db;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #3498db;--bs-btn-hover-border-color: #3498db;--bs-btn-focus-shadow-rgb: 52, 152, 219;--bs-btn-active-color: #fff;--bs-btn-active-bg: #3498db;--bs-btn-active-border-color: #3498db;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #3498db;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #3498db;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-warning{--bs-btn-color: #f39c12;--bs-btn-border-color: #f39c12;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #f39c12;--bs-btn-hover-border-color: #f39c12;--bs-btn-focus-shadow-rgb: 243, 156, 18;--bs-btn-active-color: #fff;--bs-btn-active-bg: #f39c12;--bs-btn-active-border-color: #f39c12;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #f39c12;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #f39c12;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-danger{--bs-btn-color: #e74c3c;--bs-btn-border-color: #e74c3c;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #e74c3c;--bs-btn-hover-border-color: #e74c3c;--bs-btn-focus-shadow-rgb: 231, 76, 60;--bs-btn-active-color: #fff;--bs-btn-active-bg: #e74c3c;--bs-btn-active-border-color: #e74c3c;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #e74c3c;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #e74c3c;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-light{--bs-btn-color: #6f6f6f;--bs-btn-border-color: #6f6f6f;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #6f6f6f;--bs-btn-hover-border-color: #6f6f6f;--bs-btn-focus-shadow-rgb: 111, 111, 111;--bs-btn-active-color: #fff;--bs-btn-active-bg: #6f6f6f;--bs-btn-active-border-color: #6f6f6f;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #6f6f6f;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #6f6f6f;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-dark{--bs-btn-color: #2d2d2d;--bs-btn-border-color: #2d2d2d;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #2d2d2d;--bs-btn-hover-border-color: #2d2d2d;--bs-btn-focus-shadow-rgb: 45, 45, 45;--bs-btn-active-color: #fff;--bs-btn-active-bg: #2d2d2d;--bs-btn-active-border-color: #2d2d2d;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #2d2d2d;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #2d2d2d;--bs-btn-bg: transparent;--bs-gradient: none}.btn-link{--bs-btn-font-weight: 400;--bs-btn-color: #00bc8c;--bs-btn-bg: transparent;--bs-btn-border-color: transparent;--bs-btn-hover-color: #009670;--bs-btn-hover-border-color: transparent;--bs-btn-active-color: #009670;--bs-btn-active-border-color: transparent;--bs-btn-disabled-color: #6c757d;--bs-btn-disabled-border-color: transparent;--bs-btn-box-shadow: 0 0 0 #000;--bs-btn-focus-shadow-rgb: 38, 198, 157;text-decoration:underline;-webkit-text-decoration:underline;-moz-text-decoration:underline;-ms-text-decoration:underline;-o-text-decoration:underline}.btn-link:focus-visible{color:var(--bs-btn-color)}.btn-link:hover{color:var(--bs-btn-hover-color)}.btn-lg,.btn-group-lg>.btn{--bs-btn-padding-y: 0.5rem;--bs-btn-padding-x: 1rem;--bs-btn-font-size:1.25rem;--bs-btn-border-radius: 0.5rem}.btn-sm,.btn-group-sm>.btn{--bs-btn-padding-y: 0.25rem;--bs-btn-padding-x: 0.5rem;--bs-btn-font-size:0.875rem;--bs-btn-border-radius: 0.2em}.fade{transition:opacity .15s linear}@media(prefers-reduced-motion: reduce){.fade{transition:none}}.fade:not(.show){opacity:0}.collapse:not(.show){display:none}.collapsing{height:0;overflow:hidden;transition:height .2s ease}@media(prefers-reduced-motion: reduce){.collapsing{transition:none}}.collapsing.collapse-horizontal{width:0;height:auto;transition:width .35s ease}@media(prefers-reduced-motion: reduce){.collapsing.collapse-horizontal{transition:none}}.dropup,.dropend,.dropdown,.dropstart,.dropup-center,.dropdown-center{position:relative}.dropdown-toggle{white-space:nowrap}.dropdown-toggle::after{display:inline-block;margin-left:.255em;vertical-align:.255em;content:"";border-top:.3em solid;border-right:.3em solid rgba(0,0,0,0);border-bottom:0;border-left:.3em solid rgba(0,0,0,0)}.dropdown-toggle:empty::after{margin-left:0}.dropdown-menu{--bs-dropdown-zindex: 1000;--bs-dropdown-min-width: 10rem;--bs-dropdown-padding-x: 0;--bs-dropdown-padding-y: 0.5rem;--bs-dropdown-spacer: 0.125rem;--bs-dropdown-font-size:1rem;--bs-dropdown-color: #fff;--bs-dropdown-bg: #222;--bs-dropdown-border-color: #434343;--bs-dropdown-border-radius: 0.25rem;--bs-dropdown-border-width: 1px;--bs-dropdown-inner-border-radius: calc(0.25rem - 1px);--bs-dropdown-divider-bg: #434343;--bs-dropdown-divider-margin-y: 0.5rem;--bs-dropdown-box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);--bs-dropdown-link-color: #fff;--bs-dropdown-link-hover-color: #fff;--bs-dropdown-link-hover-bg: #375a7f;--bs-dropdown-link-active-color: #fff;--bs-dropdown-link-active-bg: #375a7f;--bs-dropdown-link-disabled-color: rgba(255, 255, 255, 0.5);--bs-dropdown-item-padding-x: 1rem;--bs-dropdown-item-padding-y: 0.25rem;--bs-dropdown-header-color: #6c757d;--bs-dropdown-header-padding-x: 1rem;--bs-dropdown-header-padding-y: 0.5rem;position:absolute;z-index:var(--bs-dropdown-zindex);display:none;min-width:var(--bs-dropdown-min-width);padding:var(--bs-dropdown-padding-y) var(--bs-dropdown-padding-x);margin:0;font-size:var(--bs-dropdown-font-size);color:var(--bs-dropdown-color);text-align:left;list-style:none;background-color:var(--bs-dropdown-bg);background-clip:padding-box;border:var(--bs-dropdown-border-width) solid var(--bs-dropdown-border-color);border-radius:var(--bs-dropdown-border-radius)}.dropdown-menu[data-bs-popper]{top:100%;left:0;margin-top:var(--bs-dropdown-spacer)}.dropdown-menu-start{--bs-position: start}.dropdown-menu-start[data-bs-popper]{right:auto;left:0}.dropdown-menu-end{--bs-position: end}.dropdown-menu-end[data-bs-popper]{right:0;left:auto}@media(min-width: 576px){.dropdown-menu-sm-start{--bs-position: start}.dropdown-menu-sm-start[data-bs-popper]{right:auto;left:0}.dropdown-menu-sm-end{--bs-position: end}.dropdown-menu-sm-end[data-bs-popper]{right:0;left:auto}}@media(min-width: 768px){.dropdown-menu-md-start{--bs-position: start}.dropdown-menu-md-start[data-bs-popper]{right:auto;left:0}.dropdown-menu-md-end{--bs-position: end}.dropdown-menu-md-end[data-bs-popper]{right:0;left:auto}}@media(min-width: 992px){.dropdown-menu-lg-start{--bs-position: start}.dropdown-menu-lg-start[data-bs-popper]{right:auto;left:0}.dropdown-menu-lg-end{--bs-position: end}.dropdown-menu-lg-end[data-bs-popper]{right:0;left:auto}}@media(min-width: 1200px){.dropdown-menu-xl-start{--bs-position: start}.dropdown-menu-xl-start[data-bs-popper]{right:auto;left:0}.dropdown-menu-xl-end{--bs-position: end}.dropdown-menu-xl-end[data-bs-popper]{right:0;left:auto}}@media(min-width: 1400px){.dropdown-menu-xxl-start{--bs-position: start}.dropdown-menu-xxl-start[data-bs-popper]{right:auto;left:0}.dropdown-menu-xxl-end{--bs-position: end}.dropdown-menu-xxl-end[data-bs-popper]{right:0;left:auto}}.dropup .dropdown-menu[data-bs-popper]{top:auto;bottom:100%;margin-top:0;margin-bottom:var(--bs-dropdown-spacer)}.dropup .dropdown-toggle::after{display:inline-block;margin-left:.255em;vertical-align:.255em;content:"";border-top:0;border-right:.3em solid rgba(0,0,0,0);border-bottom:.3em solid;border-left:.3em solid rgba(0,0,0,0)}.dropup .dropdown-toggle:empty::after{margin-left:0}.dropend .dropdown-menu[data-bs-popper]{top:0;right:auto;left:100%;margin-top:0;margin-left:var(--bs-dropdown-spacer)}.dropend .dropdown-toggle::after{display:inline-block;margin-left:.255em;vertical-align:.255em;content:"";border-top:.3em solid rgba(0,0,0,0);border-right:0;border-bottom:.3em solid rgba(0,0,0,0);border-left:.3em solid}.dropend .dropdown-toggle:empty::after{margin-left:0}.dropend .dropdown-toggle::after{vertical-align:0}.dropstart .dropdown-menu[data-bs-popper]{top:0;right:100%;left:auto;margin-top:0;margin-right:var(--bs-dropdown-spacer)}.dropstart .dropdown-toggle::after{display:inline-block;margin-left:.255em;vertical-align:.255em;content:""}.dropstart .dropdown-toggle::after{display:none}.dropstart .dropdown-toggle::before{display:inline-block;margin-right:.255em;vertical-align:.255em;content:"";border-top:.3em solid rgba(0,0,0,0);border-right:.3em solid;border-bottom:.3em solid rgba(0,0,0,0)}.dropstart .dropdown-toggle:empty::after{margin-left:0}.dropstart .dropdown-toggle::before{vertical-align:0}.dropdown-divider{height:0;margin:var(--bs-dropdown-divider-margin-y) 0;overflow:hidden;border-top:1px solid var(--bs-dropdown-divider-bg);opacity:1}.dropdown-item{display:block;width:100%;padding:var(--bs-dropdown-item-padding-y) var(--bs-dropdown-item-padding-x);clear:both;font-weight:400;color:var(--bs-dropdown-link-color);text-align:inherit;text-decoration:none;-webkit-text-decoration:none;-moz-text-decoration:none;-ms-text-decoration:none;-o-text-decoration:none;white-space:nowrap;background-color:rgba(0,0,0,0);border:0;border-radius:var(--bs-dropdown-item-border-radius, 0)}.dropdown-item:hover,.dropdown-item:focus{color:var(--bs-dropdown-link-hover-color);background-color:var(--bs-dropdown-link-hover-bg)}.dropdown-item.active,.dropdown-item:active{color:var(--bs-dropdown-link-active-color);text-decoration:none;background-color:var(--bs-dropdown-link-active-bg)}.dropdown-item.disabled,.dropdown-item:disabled{color:var(--bs-dropdown-link-disabled-color);pointer-events:none;background-color:rgba(0,0,0,0)}.dropdown-menu.show{display:block}.dropdown-header{display:block;padding:var(--bs-dropdown-header-padding-y) var(--bs-dropdown-header-padding-x);margin-bottom:0;font-size:0.875rem;color:var(--bs-dropdown-header-color);white-space:nowrap}.dropdown-item-text{display:block;padding:var(--bs-dropdown-item-padding-y) var(--bs-dropdown-item-padding-x);color:var(--bs-dropdown-link-color)}.dropdown-menu-dark{--bs-dropdown-color: #dee2e6;--bs-dropdown-bg: #343a40;--bs-dropdown-border-color: #434343;--bs-dropdown-box-shadow: ;--bs-dropdown-link-color: #dee2e6;--bs-dropdown-link-hover-color: #fff;--bs-dropdown-divider-bg: #434343;--bs-dropdown-link-hover-bg: rgba(255, 255, 255, 0.15);--bs-dropdown-link-active-color: #fff;--bs-dropdown-link-active-bg: #375a7f;--bs-dropdown-link-disabled-color: #adb5bd;--bs-dropdown-header-color: #adb5bd}.btn-group,.btn-group-vertical{position:relative;display:inline-flex;vertical-align:middle}.btn-group>.btn,.btn-group-vertical>.btn{position:relative;flex:1 1 auto;-webkit-flex:1 1 auto}.btn-group>.btn-check:checked+.btn,.btn-group>.btn-check:focus+.btn,.btn-group>.btn:hover,.btn-group>.btn:focus,.btn-group>.btn:active,.btn-group>.btn.active,.btn-group-vertical>.btn-check:checked+.btn,.btn-group-vertical>.btn-check:focus+.btn,.btn-group-vertical>.btn:hover,.btn-group-vertical>.btn:focus,.btn-group-vertical>.btn:active,.btn-group-vertical>.btn.active{z-index:1}.btn-toolbar{display:flex;display:-webkit-flex;flex-wrap:wrap;-webkit-flex-wrap:wrap;justify-content:flex-start;-webkit-justify-content:flex-start}.btn-toolbar .input-group{width:auto}.btn-group{border-radius:.25rem}.btn-group>:not(.btn-check:first-child)+.btn,.btn-group>.btn-group:not(:first-child){margin-left:calc(1px*-1)}.btn-group>.btn:not(:last-child):not(.dropdown-toggle),.btn-group>.btn.dropdown-toggle-split:first-child,.btn-group>.btn-group:not(:last-child)>.btn{border-top-right-radius:0;border-bottom-right-radius:0}.btn-group>.btn:nth-child(n+3),.btn-group>:not(.btn-check)+.btn,.btn-group>.btn-group:not(:first-child)>.btn{border-top-left-radius:0;border-bottom-left-radius:0}.dropdown-toggle-split{padding-right:.5625rem;padding-left:.5625rem}.dropdown-toggle-split::after,.dropup .dropdown-toggle-split::after,.dropend .dropdown-toggle-split::after{margin-left:0}.dropstart .dropdown-toggle-split::before{margin-right:0}.btn-sm+.dropdown-toggle-split,.btn-group-sm>.btn+.dropdown-toggle-split{padding-right:.375rem;padding-left:.375rem}.btn-lg+.dropdown-toggle-split,.btn-group-lg>.btn+.dropdown-toggle-split{padding-right:.75rem;padding-left:.75rem}.btn-group-vertical{flex-direction:column;-webkit-flex-direction:column;align-items:flex-start;-webkit-align-items:flex-start;justify-content:center;-webkit-justify-content:center}.btn-group-vertical>.btn,.btn-group-vertical>.btn-group{width:100%}.btn-group-vertical>.btn:not(:first-child),.btn-group-vertical>.btn-group:not(:first-child){margin-top:calc(1px*-1)}.btn-group-vertical>.btn:not(:last-child):not(.dropdown-toggle),.btn-group-vertical>.btn-group:not(:last-child)>.btn{border-bottom-right-radius:0;border-bottom-left-radius:0}.btn-group-vertical>.btn~.btn,.btn-group-vertical>.btn-group:not(:first-child)>.btn{border-top-left-radius:0;border-top-right-radius:0}.nav{--bs-nav-link-padding-x: 2rem;--bs-nav-link-padding-y: 0.5rem;--bs-nav-link-font-weight: ;--bs-nav-link-color: #00bc8c;--bs-nav-link-hover-color: #009670;--bs-nav-link-disabled-color: #6f6f6f;display:flex;display:-webkit-flex;flex-wrap:wrap;-webkit-flex-wrap:wrap;padding-left:0;margin-bottom:0;list-style:none}.nav-link{display:block;padding:var(--bs-nav-link-padding-y) var(--bs-nav-link-padding-x);font-size:var(--bs-nav-link-font-size);font-weight:var(--bs-nav-link-font-weight);color:var(--bs-nav-link-color);text-decoration:none;-webkit-text-decoration:none;-moz-text-decoration:none;-ms-text-decoration:none;-o-text-decoration:none;background:none;border:0;transition:color .15s ease-in-out,background-color .15s ease-in-out,border-color .15s ease-in-out}@media(prefers-reduced-motion: reduce){.nav-link{transition:none}}.nav-link:hover,.nav-link:focus{color:var(--bs-nav-link-hover-color)}.nav-link:focus-visible{outline:0;box-shadow:0 0 0 .25rem rgba(55,90,127,.25)}.nav-link.disabled,.nav-link:disabled{color:var(--bs-nav-link-disabled-color);pointer-events:none;cursor:default}.nav-tabs{--bs-nav-tabs-border-width: 1px;--bs-nav-tabs-border-color: #434343;--bs-nav-tabs-border-radius: 0.25rem;--bs-nav-tabs-link-hover-border-color: #434343 #434343 transparent;--bs-nav-tabs-link-active-color: #fff;--bs-nav-tabs-link-active-bg: #222;--bs-nav-tabs-link-active-border-color: #434343 #434343 transparent;border-bottom:var(--bs-nav-tabs-border-width) solid var(--bs-nav-tabs-border-color)}.nav-tabs .nav-link{margin-bottom:calc(-1*var(--bs-nav-tabs-border-width));border:var(--bs-nav-tabs-border-width) solid rgba(0,0,0,0);border-top-left-radius:var(--bs-nav-tabs-border-radius);border-top-right-radius:var(--bs-nav-tabs-border-radius)}.nav-tabs .nav-link:hover,.nav-tabs .nav-link:focus{isolation:isolate;border-color:var(--bs-nav-tabs-link-hover-border-color)}.nav-tabs .nav-link.active,.nav-tabs .nav-item.show .nav-link{color:var(--bs-nav-tabs-link-active-color);background-color:var(--bs-nav-tabs-link-active-bg);border-color:var(--bs-nav-tabs-link-active-border-color)}.nav-tabs .dropdown-menu{margin-top:calc(-1*var(--bs-nav-tabs-border-width));border-top-left-radius:0;border-top-right-radius:0}.nav-pills{--bs-nav-pills-border-radius: 0.25rem;--bs-nav-pills-link-active-color: #fff;--bs-nav-pills-link-active-bg: #375a7f}.nav-pills .nav-link{border-radius:var(--bs-nav-pills-border-radius)}.nav-pills .nav-link.active,.nav-pills .show>.nav-link{color:var(--bs-nav-pills-link-active-color);background-color:var(--bs-nav-pills-link-active-bg)}.nav-underline{--bs-nav-underline-gap: 1rem;--bs-nav-underline-border-width: 0.125rem;--bs-nav-underline-link-active-color: #000;gap:var(--bs-nav-underline-gap)}.nav-underline .nav-link{padding-right:0;padding-left:0;border-bottom:var(--bs-nav-underline-border-width) solid rgba(0,0,0,0)}.nav-underline .nav-link:hover,.nav-underline .nav-link:focus{border-bottom-color:currentcolor}.nav-underline .nav-link.active,.nav-underline .show>.nav-link{font-weight:700;color:var(--bs-nav-underline-link-active-color);border-bottom-color:currentcolor}.nav-fill>.nav-link,.nav-fill .nav-item{flex:1 1 auto;-webkit-flex:1 1 auto;text-align:center}.nav-justified>.nav-link,.nav-justified .nav-item{flex-basis:0;-webkit-flex-basis:0;flex-grow:1;-webkit-flex-grow:1;text-align:center}.nav-fill .nav-item .nav-link,.nav-justified .nav-item .nav-link{width:100%}.tab-content>.tab-pane{display:none}.tab-content>.active{display:block}.navbar{--bs-navbar-padding-x: 0;--bs-navbar-padding-y: 1rem;--bs-navbar-color: #dee2e6;--bs-navbar-hover-color: rgba(255, 255, 255, 0.8);--bs-navbar-disabled-color: rgba(222, 226, 230, 0.75);--bs-navbar-active-color: #fff;--bs-navbar-brand-padding-y: 0.3125rem;--bs-navbar-brand-margin-end: 1rem;--bs-navbar-brand-font-size: 1.25rem;--bs-navbar-brand-color: #dee2e6;--bs-navbar-brand-hover-color: #fff;--bs-navbar-nav-link-padding-x: 0.5rem;--bs-navbar-toggler-padding-y: 0.25;--bs-navbar-toggler-padding-x: 0;--bs-navbar-toggler-font-size: 1.25rem;--bs-navbar-toggler-icon-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 30 30'%3e%3cpath stroke='%23dee2e6' stroke-linecap='round' stroke-miterlimit='10' stroke-width='2' d='M4 7h22M4 15h22M4 23h22'/%3e%3c/svg%3e");--bs-navbar-toggler-border-color: rgba(222, 226, 230, 0);--bs-navbar-toggler-border-radius: 0.25rem;--bs-navbar-toggler-focus-width: 0.25rem;--bs-navbar-toggler-transition: box-shadow 0.15s ease-in-out;position:relative;display:flex;display:-webkit-flex;flex-wrap:wrap;-webkit-flex-wrap:wrap;align-items:center;-webkit-align-items:center;justify-content:space-between;-webkit-justify-content:space-between;padding:var(--bs-navbar-padding-y) var(--bs-navbar-padding-x)}.navbar>.container,.navbar>.container-fluid,.navbar>.container-sm,.navbar>.container-md,.navbar>.container-lg,.navbar>.container-xl,.navbar>.container-xxl{display:flex;display:-webkit-flex;flex-wrap:inherit;-webkit-flex-wrap:inherit;align-items:center;-webkit-align-items:center;justify-content:space-between;-webkit-justify-content:space-between}.navbar-brand{padding-top:var(--bs-navbar-brand-padding-y);padding-bottom:var(--bs-navbar-brand-padding-y);margin-right:var(--bs-navbar-brand-margin-end);font-size:var(--bs-navbar-brand-font-size);color:var(--bs-navbar-brand-color);text-decoration:none;-webkit-text-decoration:none;-moz-text-decoration:none;-ms-text-decoration:none;-o-text-decoration:none;white-space:nowrap}.navbar-brand:hover,.navbar-brand:focus{color:var(--bs-navbar-brand-hover-color)}.navbar-nav{--bs-nav-link-padding-x: 0;--bs-nav-link-padding-y: 0.5rem;--bs-nav-link-font-weight: ;--bs-nav-link-color: var(--bs-navbar-color);--bs-nav-link-hover-color: var(--bs-navbar-hover-color);--bs-nav-link-disabled-color: var(--bs-navbar-disabled-color);display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;padding-left:0;margin-bottom:0;list-style:none}.navbar-nav .nav-link.active,.navbar-nav .nav-link.show{color:var(--bs-navbar-active-color)}.navbar-nav .dropdown-menu{position:static}.navbar-text{padding-top:.5rem;padding-bottom:.5rem;color:var(--bs-navbar-color)}.navbar-text a,.navbar-text a:hover,.navbar-text a:focus{color:var(--bs-navbar-active-color)}.navbar-collapse{flex-basis:100%;-webkit-flex-basis:100%;flex-grow:1;-webkit-flex-grow:1;align-items:center;-webkit-align-items:center}.navbar-toggler{padding:var(--bs-navbar-toggler-padding-y) var(--bs-navbar-toggler-padding-x);font-size:var(--bs-navbar-toggler-font-size);line-height:1;color:var(--bs-navbar-color);background-color:rgba(0,0,0,0);border:var(--bs-border-width) solid var(--bs-navbar-toggler-border-color);border-radius:var(--bs-navbar-toggler-border-radius);transition:var(--bs-navbar-toggler-transition)}@media(prefers-reduced-motion: reduce){.navbar-toggler{transition:none}}.navbar-toggler:hover{text-decoration:none}.navbar-toggler:focus{text-decoration:none;outline:0;box-shadow:0 0 0 var(--bs-navbar-toggler-focus-width)}.navbar-toggler-icon{display:inline-block;width:1.5em;height:1.5em;vertical-align:middle;background-image:var(--bs-navbar-toggler-icon-bg);background-repeat:no-repeat;background-position:center;background-size:100%}.navbar-nav-scroll{max-height:var(--bs-scroll-height, 75vh);overflow-y:auto}@media(min-width: 576px){.navbar-expand-sm{flex-wrap:nowrap;-webkit-flex-wrap:nowrap;justify-content:flex-start;-webkit-justify-content:flex-start}.navbar-expand-sm .navbar-nav{flex-direction:row;-webkit-flex-direction:row}.navbar-expand-sm .navbar-nav .dropdown-menu{position:absolute}.navbar-expand-sm .navbar-nav .nav-link{padding-right:var(--bs-navbar-nav-link-padding-x);padding-left:var(--bs-navbar-nav-link-padding-x)}.navbar-expand-sm .navbar-nav-scroll{overflow:visible}.navbar-expand-sm .navbar-collapse{display:flex !important;display:-webkit-flex !important;flex-basis:auto;-webkit-flex-basis:auto}.navbar-expand-sm .navbar-toggler{display:none}.navbar-expand-sm .offcanvas{position:static;z-index:auto;flex-grow:1;-webkit-flex-grow:1;width:auto !important;height:auto !important;visibility:visible !important;background-color:rgba(0,0,0,0) !important;border:0 !important;transform:none !important;transition:none}.navbar-expand-sm .offcanvas .offcanvas-header{display:none}.navbar-expand-sm .offcanvas .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible}}@media(min-width: 768px){.navbar-expand-md{flex-wrap:nowrap;-webkit-flex-wrap:nowrap;justify-content:flex-start;-webkit-justify-content:flex-start}.navbar-expand-md .navbar-nav{flex-direction:row;-webkit-flex-direction:row}.navbar-expand-md .navbar-nav .dropdown-menu{position:absolute}.navbar-expand-md .navbar-nav .nav-link{padding-right:var(--bs-navbar-nav-link-padding-x);padding-left:var(--bs-navbar-nav-link-padding-x)}.navbar-expand-md .navbar-nav-scroll{overflow:visible}.navbar-expand-md .navbar-collapse{display:flex !important;display:-webkit-flex !important;flex-basis:auto;-webkit-flex-basis:auto}.navbar-expand-md .navbar-toggler{display:none}.navbar-expand-md .offcanvas{position:static;z-index:auto;flex-grow:1;-webkit-flex-grow:1;width:auto !important;height:auto !important;visibility:visible !important;background-color:rgba(0,0,0,0) !important;border:0 !important;transform:none !important;transition:none}.navbar-expand-md .offcanvas .offcanvas-header{display:none}.navbar-expand-md .offcanvas .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible}}@media(min-width: 992px){.navbar-expand-lg{flex-wrap:nowrap;-webkit-flex-wrap:nowrap;justify-content:flex-start;-webkit-justify-content:flex-start}.navbar-expand-lg .navbar-nav{flex-direction:row;-webkit-flex-direction:row}.navbar-expand-lg .navbar-nav .dropdown-menu{position:absolute}.navbar-expand-lg .navbar-nav .nav-link{padding-right:var(--bs-navbar-nav-link-padding-x);padding-left:var(--bs-navbar-nav-link-padding-x)}.navbar-expand-lg .navbar-nav-scroll{overflow:visible}.navbar-expand-lg .navbar-collapse{display:flex !important;display:-webkit-flex !important;flex-basis:auto;-webkit-flex-basis:auto}.navbar-expand-lg .navbar-toggler{display:none}.navbar-expand-lg .offcanvas{position:static;z-index:auto;flex-grow:1;-webkit-flex-grow:1;width:auto !important;height:auto !important;visibility:visible !important;background-color:rgba(0,0,0,0) !important;border:0 !important;transform:none !important;transition:none}.navbar-expand-lg .offcanvas .offcanvas-header{display:none}.navbar-expand-lg .offcanvas .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible}}@media(min-width: 1200px){.navbar-expand-xl{flex-wrap:nowrap;-webkit-flex-wrap:nowrap;justify-content:flex-start;-webkit-justify-content:flex-start}.navbar-expand-xl .navbar-nav{flex-direction:row;-webkit-flex-direction:row}.navbar-expand-xl .navbar-nav .dropdown-menu{position:absolute}.navbar-expand-xl .navbar-nav .nav-link{padding-right:var(--bs-navbar-nav-link-padding-x);padding-left:var(--bs-navbar-nav-link-padding-x)}.navbar-expand-xl .navbar-nav-scroll{overflow:visible}.navbar-expand-xl .navbar-collapse{display:flex !important;display:-webkit-flex !important;flex-basis:auto;-webkit-flex-basis:auto}.navbar-expand-xl .navbar-toggler{display:none}.navbar-expand-xl .offcanvas{position:static;z-index:auto;flex-grow:1;-webkit-flex-grow:1;width:auto !important;height:auto !important;visibility:visible !important;background-color:rgba(0,0,0,0) !important;border:0 !important;transform:none !important;transition:none}.navbar-expand-xl .offcanvas .offcanvas-header{display:none}.navbar-expand-xl .offcanvas .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible}}@media(min-width: 1400px){.navbar-expand-xxl{flex-wrap:nowrap;-webkit-flex-wrap:nowrap;justify-content:flex-start;-webkit-justify-content:flex-start}.navbar-expand-xxl .navbar-nav{flex-direction:row;-webkit-flex-direction:row}.navbar-expand-xxl .navbar-nav .dropdown-menu{position:absolute}.navbar-expand-xxl .navbar-nav .nav-link{padding-right:var(--bs-navbar-nav-link-padding-x);padding-left:var(--bs-navbar-nav-link-padding-x)}.navbar-expand-xxl .navbar-nav-scroll{overflow:visible}.navbar-expand-xxl .navbar-collapse{display:flex !important;display:-webkit-flex !important;flex-basis:auto;-webkit-flex-basis:auto}.navbar-expand-xxl .navbar-toggler{display:none}.navbar-expand-xxl .offcanvas{position:static;z-index:auto;flex-grow:1;-webkit-flex-grow:1;width:auto !important;height:auto !important;visibility:visible !important;background-color:rgba(0,0,0,0) !important;border:0 !important;transform:none !important;transition:none}.navbar-expand-xxl .offcanvas .offcanvas-header{display:none}.navbar-expand-xxl .offcanvas .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible}}.navbar-expand{flex-wrap:nowrap;-webkit-flex-wrap:nowrap;justify-content:flex-start;-webkit-justify-content:flex-start}.navbar-expand .navbar-nav{flex-direction:row;-webkit-flex-direction:row}.navbar-expand .navbar-nav .dropdown-menu{position:absolute}.navbar-expand .navbar-nav .nav-link{padding-right:var(--bs-navbar-nav-link-padding-x);padding-left:var(--bs-navbar-nav-link-padding-x)}.navbar-expand .navbar-nav-scroll{overflow:visible}.navbar-expand .navbar-collapse{display:flex !important;display:-webkit-flex !important;flex-basis:auto;-webkit-flex-basis:auto}.navbar-expand .navbar-toggler{display:none}.navbar-expand .offcanvas{position:static;z-index:auto;flex-grow:1;-webkit-flex-grow:1;width:auto !important;height:auto !important;visibility:visible !important;background-color:rgba(0,0,0,0) !important;border:0 !important;transform:none !important;transition:none}.navbar-expand .offcanvas .offcanvas-header{display:none}.navbar-expand .offcanvas .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible}.navbar-dark,.navbar[data-bs-theme=dark]{--bs-navbar-color: #dee2e6;--bs-navbar-hover-color: rgba(255, 255, 255, 0.8);--bs-navbar-disabled-color: rgba(222, 226, 230, 0.75);--bs-navbar-active-color: #fff;--bs-navbar-brand-color: #dee2e6;--bs-navbar-brand-hover-color: #fff;--bs-navbar-toggler-border-color: rgba(222, 226, 230, 0);--bs-navbar-toggler-icon-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 30 30'%3e%3cpath stroke='%23dee2e6' stroke-linecap='round' stroke-miterlimit='10' stroke-width='2' d='M4 7h22M4 15h22M4 23h22'/%3e%3c/svg%3e")}[data-bs-theme=dark] .navbar-toggler-icon{--bs-navbar-toggler-icon-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 30 30'%3e%3cpath stroke='%23dee2e6' stroke-linecap='round' stroke-miterlimit='10' stroke-width='2' d='M4 7h22M4 15h22M4 23h22'/%3e%3c/svg%3e")}.card{--bs-card-spacer-y: 1rem;--bs-card-spacer-x: 1rem;--bs-card-title-spacer-y: 0.5rem;--bs-card-title-color: ;--bs-card-subtitle-color: ;--bs-card-border-width: 1px;--bs-card-border-color: rgba(0, 0, 0, 0.175);--bs-card-border-radius: 0.25rem;--bs-card-box-shadow: ;--bs-card-inner-border-radius: calc(0.25rem - 1px);--bs-card-cap-padding-y: 0.5rem;--bs-card-cap-padding-x: 1rem;--bs-card-cap-bg: rgba(52, 58, 64, 0.25);--bs-card-cap-color: ;--bs-card-height: ;--bs-card-color: ;--bs-card-bg: #2d2d2d;--bs-card-img-overlay-padding: 1rem;--bs-card-group-margin: 0.75rem;position:relative;display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;min-width:0;height:var(--bs-card-height);color:var(--bs-body-color);word-wrap:break-word;background-color:var(--bs-card-bg);background-clip:border-box;border:var(--bs-card-border-width) solid var(--bs-card-border-color);border-radius:var(--bs-card-border-radius)}.card>hr{margin-right:0;margin-left:0}.card>.list-group{border-top:inherit;border-bottom:inherit}.card>.list-group:first-child{border-top-width:0;border-top-left-radius:var(--bs-card-inner-border-radius);border-top-right-radius:var(--bs-card-inner-border-radius)}.card>.list-group:last-child{border-bottom-width:0;border-bottom-right-radius:var(--bs-card-inner-border-radius);border-bottom-left-radius:var(--bs-card-inner-border-radius)}.card>.card-header+.list-group,.card>.list-group+.card-footer{border-top:0}.card-body{flex:1 1 auto;-webkit-flex:1 1 auto;padding:var(--bs-card-spacer-y) var(--bs-card-spacer-x);color:var(--bs-card-color)}.card-title{margin-bottom:var(--bs-card-title-spacer-y);color:var(--bs-card-title-color)}.card-subtitle{margin-top:calc(-0.5*var(--bs-card-title-spacer-y));margin-bottom:0;color:var(--bs-card-subtitle-color)}.card-text:last-child{margin-bottom:0}.card-link+.card-link{margin-left:var(--bs-card-spacer-x)}.card-header{padding:var(--bs-card-cap-padding-y) var(--bs-card-cap-padding-x);margin-bottom:0;color:var(--bs-card-cap-color);background-color:var(--bs-card-cap-bg);border-bottom:var(--bs-card-border-width) solid var(--bs-card-border-color)}.card-header:first-child{border-radius:var(--bs-card-inner-border-radius) var(--bs-card-inner-border-radius) 0 0}.card-footer{padding:var(--bs-card-cap-padding-y) var(--bs-card-cap-padding-x);color:var(--bs-card-cap-color);background-color:var(--bs-card-cap-bg);border-top:var(--bs-card-border-width) solid var(--bs-card-border-color)}.card-footer:last-child{border-radius:0 0 var(--bs-card-inner-border-radius) var(--bs-card-inner-border-radius)}.card-header-tabs{margin-right:calc(-0.5*var(--bs-card-cap-padding-x));margin-bottom:calc(-1*var(--bs-card-cap-padding-y));margin-left:calc(-0.5*var(--bs-card-cap-padding-x));border-bottom:0}.card-header-tabs .nav-link.active{background-color:var(--bs-card-bg);border-bottom-color:var(--bs-card-bg)}.card-header-pills{margin-right:calc(-0.5*var(--bs-card-cap-padding-x));margin-left:calc(-0.5*var(--bs-card-cap-padding-x))}.card-img-overlay{position:absolute;top:0;right:0;bottom:0;left:0;padding:var(--bs-card-img-overlay-padding);border-radius:var(--bs-card-inner-border-radius)}.card-img,.card-img-top,.card-img-bottom{width:100%}.card-img,.card-img-top{border-top-left-radius:var(--bs-card-inner-border-radius);border-top-right-radius:var(--bs-card-inner-border-radius)}.card-img,.card-img-bottom{border-bottom-right-radius:var(--bs-card-inner-border-radius);border-bottom-left-radius:var(--bs-card-inner-border-radius)}.card-group>.card{margin-bottom:var(--bs-card-group-margin)}@media(min-width: 576px){.card-group{display:flex;display:-webkit-flex;flex-flow:row wrap;-webkit-flex-flow:row wrap}.card-group>.card{flex:1 0 0%;-webkit-flex:1 0 0%;margin-bottom:0}.card-group>.card+.card{margin-left:0;border-left:0}.card-group>.card:not(:last-child){border-top-right-radius:0;border-bottom-right-radius:0}.card-group>.card:not(:last-child) .card-img-top,.card-group>.card:not(:last-child) .card-header{border-top-right-radius:0}.card-group>.card:not(:last-child) .card-img-bottom,.card-group>.card:not(:last-child) .card-footer{border-bottom-right-radius:0}.card-group>.card:not(:first-child){border-top-left-radius:0;border-bottom-left-radius:0}.card-group>.card:not(:first-child) .card-img-top,.card-group>.card:not(:first-child) .card-header{border-top-left-radius:0}.card-group>.card:not(:first-child) .card-img-bottom,.card-group>.card:not(:first-child) .card-footer{border-bottom-left-radius:0}}.accordion{--bs-accordion-color: #fff;--bs-accordion-bg: #222;--bs-accordion-transition: color 0.15s ease-in-out, background-color 0.15s ease-in-out, border-color 0.15s ease-in-out, box-shadow 0.15s ease-in-out, border-radius 0.15s ease;--bs-accordion-border-color: #dee2e6;--bs-accordion-border-width: 1px;--bs-accordion-border-radius: 0.25rem;--bs-accordion-inner-border-radius: calc(0.25rem - 1px);--bs-accordion-btn-padding-x: 1.25rem;--bs-accordion-btn-padding-y: 1rem;--bs-accordion-btn-color: #fff;--bs-accordion-btn-bg: #222;--bs-accordion-btn-icon: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='%23fff'%3e%3cpath fill-rule='evenodd' d='M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z'/%3e%3c/svg%3e");--bs-accordion-btn-icon-width: 1.25rem;--bs-accordion-btn-icon-transform: rotate(-180deg);--bs-accordion-btn-icon-transition: transform 0.2s ease-in-out;--bs-accordion-btn-active-icon: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='%23162433'%3e%3cpath fill-rule='evenodd' d='M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z'/%3e%3c/svg%3e");--bs-accordion-btn-focus-border-color: #9badbf;--bs-accordion-btn-focus-box-shadow: 0 0 0 0.25rem rgba(55, 90, 127, 0.25);--bs-accordion-body-padding-x: 1.25rem;--bs-accordion-body-padding-y: 1rem;--bs-accordion-active-color: #162433;--bs-accordion-active-bg: #d7dee5}.accordion-button{position:relative;display:flex;display:-webkit-flex;align-items:center;-webkit-align-items:center;width:100%;padding:var(--bs-accordion-btn-padding-y) var(--bs-accordion-btn-padding-x);font-size:1rem;color:var(--bs-accordion-btn-color);text-align:left;background-color:var(--bs-accordion-btn-bg);border:0;border-radius:0;overflow-anchor:none;transition:var(--bs-accordion-transition)}@media(prefers-reduced-motion: reduce){.accordion-button{transition:none}}.accordion-button:not(.collapsed){color:var(--bs-accordion-active-color);background-color:var(--bs-accordion-active-bg);box-shadow:inset 0 calc(-1*var(--bs-accordion-border-width)) 0 var(--bs-accordion-border-color)}.accordion-button:not(.collapsed)::after{background-image:var(--bs-accordion-btn-active-icon);transform:var(--bs-accordion-btn-icon-transform)}.accordion-button::after{flex-shrink:0;-webkit-flex-shrink:0;width:var(--bs-accordion-btn-icon-width);height:var(--bs-accordion-btn-icon-width);margin-left:auto;content:"";background-image:var(--bs-accordion-btn-icon);background-repeat:no-repeat;background-size:var(--bs-accordion-btn-icon-width);transition:var(--bs-accordion-btn-icon-transition)}@media(prefers-reduced-motion: reduce){.accordion-button::after{transition:none}}.accordion-button:hover{z-index:2}.accordion-button:focus{z-index:3;border-color:var(--bs-accordion-btn-focus-border-color);outline:0;box-shadow:var(--bs-accordion-btn-focus-box-shadow)}.accordion-header{margin-bottom:0}.accordion-item{color:var(--bs-accordion-color);background-color:var(--bs-accordion-bg);border:var(--bs-accordion-border-width) solid var(--bs-accordion-border-color)}.accordion-item:first-of-type{border-top-left-radius:var(--bs-accordion-border-radius);border-top-right-radius:var(--bs-accordion-border-radius)}.accordion-item:first-of-type .accordion-button{border-top-left-radius:var(--bs-accordion-inner-border-radius);border-top-right-radius:var(--bs-accordion-inner-border-radius)}.accordion-item:not(:first-of-type){border-top:0}.accordion-item:last-of-type{border-bottom-right-radius:var(--bs-accordion-border-radius);border-bottom-left-radius:var(--bs-accordion-border-radius)}.accordion-item:last-of-type .accordion-button.collapsed{border-bottom-right-radius:var(--bs-accordion-inner-border-radius);border-bottom-left-radius:var(--bs-accordion-inner-border-radius)}.accordion-item:last-of-type .accordion-collapse{border-bottom-right-radius:var(--bs-accordion-border-radius);border-bottom-left-radius:var(--bs-accordion-border-radius)}.accordion-body{padding:var(--bs-accordion-body-padding-y) var(--bs-accordion-body-padding-x)}.accordion-flush .accordion-collapse{border-width:0}.accordion-flush .accordion-item{border-right:0;border-left:0;border-radius:0}.accordion-flush .accordion-item:first-child{border-top:0}.accordion-flush .accordion-item:last-child{border-bottom:0}.accordion-flush .accordion-item .accordion-button,.accordion-flush .accordion-item .accordion-button.collapsed{border-radius:0}[data-bs-theme=dark] .accordion-button::after{--bs-accordion-btn-icon: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='%23879cb2'%3e%3cpath fill-rule='evenodd' d='M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z'/%3e%3c/svg%3e");--bs-accordion-btn-active-icon: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='%23879cb2'%3e%3cpath fill-rule='evenodd' d='M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z'/%3e%3c/svg%3e")}.breadcrumb{--bs-breadcrumb-padding-x: 0.75rem;--bs-breadcrumb-padding-y: 0.375rem;--bs-breadcrumb-margin-bottom: 1rem;--bs-breadcrumb-bg: #434343;--bs-breadcrumb-border-radius: 0.25rem;--bs-breadcrumb-divider-color: rgba(255, 255, 255, 0.75);--bs-breadcrumb-item-padding-x: 0.5rem;--bs-breadcrumb-item-active-color: rgba(255, 255, 255, 0.75);display:flex;display:-webkit-flex;flex-wrap:wrap;-webkit-flex-wrap:wrap;padding:var(--bs-breadcrumb-padding-y) var(--bs-breadcrumb-padding-x);margin-bottom:var(--bs-breadcrumb-margin-bottom);font-size:var(--bs-breadcrumb-font-size);list-style:none;background-color:var(--bs-breadcrumb-bg);border-radius:var(--bs-breadcrumb-border-radius)}.breadcrumb-item+.breadcrumb-item{padding-left:var(--bs-breadcrumb-item-padding-x)}.breadcrumb-item+.breadcrumb-item::before{float:left;padding-right:var(--bs-breadcrumb-item-padding-x);color:var(--bs-breadcrumb-divider-color);content:var(--bs-breadcrumb-divider, ">") /* rtl: var(--bs-breadcrumb-divider, ">") */}.breadcrumb-item.active{color:var(--bs-breadcrumb-item-active-color)}.pagination{--bs-pagination-padding-x: 0.75rem;--bs-pagination-padding-y: 0.375rem;--bs-pagination-font-size:1rem;--bs-pagination-color: #fff;--bs-pagination-bg: #00bc8c;--bs-pagination-border-width: 0;--bs-pagination-border-color: transparent;--bs-pagination-border-radius: 0.25rem;--bs-pagination-hover-color: #fff;--bs-pagination-hover-bg: #00efb2;--bs-pagination-hover-border-color: transparent;--bs-pagination-focus-color: #009670;--bs-pagination-focus-bg: #ebebeb;--bs-pagination-focus-box-shadow: 0 0 0 0.25rem rgba(55, 90, 127, 0.25);--bs-pagination-active-color: #fff;--bs-pagination-active-bg: #00efb2;--bs-pagination-active-border-color: transparent;--bs-pagination-disabled-color: #fff;--bs-pagination-disabled-bg: #007053;--bs-pagination-disabled-border-color: transparent;display:flex;display:-webkit-flex;padding-left:0;list-style:none}.page-link{position:relative;display:block;padding:var(--bs-pagination-padding-y) var(--bs-pagination-padding-x);font-size:var(--bs-pagination-font-size);color:var(--bs-pagination-color);text-decoration:none;-webkit-text-decoration:none;-moz-text-decoration:none;-ms-text-decoration:none;-o-text-decoration:none;background-color:var(--bs-pagination-bg);border:var(--bs-pagination-border-width) solid var(--bs-pagination-border-color);transition:color .15s ease-in-out,background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media(prefers-reduced-motion: reduce){.page-link{transition:none}}.page-link:hover{z-index:2;color:var(--bs-pagination-hover-color);background-color:var(--bs-pagination-hover-bg);border-color:var(--bs-pagination-hover-border-color)}.page-link:focus{z-index:3;color:var(--bs-pagination-focus-color);background-color:var(--bs-pagination-focus-bg);outline:0;box-shadow:var(--bs-pagination-focus-box-shadow)}.page-link.active,.active>.page-link{z-index:3;color:var(--bs-pagination-active-color);background-color:var(--bs-pagination-active-bg);border-color:var(--bs-pagination-active-border-color)}.page-link.disabled,.disabled>.page-link{color:var(--bs-pagination-disabled-color);pointer-events:none;background-color:var(--bs-pagination-disabled-bg);border-color:var(--bs-pagination-disabled-border-color)}.page-item:not(:first-child) .page-link{margin-left:calc(0*-1)}.page-item:first-child .page-link{border-top-left-radius:var(--bs-pagination-border-radius);border-bottom-left-radius:var(--bs-pagination-border-radius)}.page-item:last-child .page-link{border-top-right-radius:var(--bs-pagination-border-radius);border-bottom-right-radius:var(--bs-pagination-border-radius)}.pagination-lg{--bs-pagination-padding-x: 1.5rem;--bs-pagination-padding-y: 0.75rem;--bs-pagination-font-size:1.25rem;--bs-pagination-border-radius: 0.5rem}.pagination-sm{--bs-pagination-padding-x: 0.5rem;--bs-pagination-padding-y: 0.25rem;--bs-pagination-font-size:0.875rem;--bs-pagination-border-radius: 0.2em}.badge{--bs-badge-padding-x: 0.65em;--bs-badge-padding-y: 0.35em;--bs-badge-font-size:0.75em;--bs-badge-font-weight: 700;--bs-badge-color: #fff;--bs-badge-border-radius: 0.25rem;display:inline-block;padding:var(--bs-badge-padding-y) var(--bs-badge-padding-x);font-size:var(--bs-badge-font-size);font-weight:var(--bs-badge-font-weight);line-height:1;color:var(--bs-badge-color);text-align:center;white-space:nowrap;vertical-align:baseline;border-radius:var(--bs-badge-border-radius)}.badge:empty{display:none}.btn .badge{position:relative;top:-1px}.alert{--bs-alert-bg: transparent;--bs-alert-padding-x: 1rem;--bs-alert-padding-y: 1rem;--bs-alert-margin-bottom: 1rem;--bs-alert-color: inherit;--bs-alert-border-color: transparent;--bs-alert-border: 1px solid var(--bs-alert-border-color);--bs-alert-border-radius: 0.25rem;--bs-alert-link-color: inherit;position:relative;padding:var(--bs-alert-padding-y) var(--bs-alert-padding-x);margin-bottom:var(--bs-alert-margin-bottom);color:var(--bs-alert-color);background-color:var(--bs-alert-bg);border:var(--bs-alert-border);border-radius:var(--bs-alert-border-radius)}.alert-heading{color:inherit}.alert-link{font-weight:700;color:var(--bs-alert-link-color)}.alert-dismissible{padding-right:3rem}.alert-dismissible .btn-close{position:absolute;top:0;right:0;z-index:2;padding:1.25rem 1rem}.alert-default{--bs-alert-color: var(--bs-default-text-emphasis);--bs-alert-bg: var(--bs-default-bg-subtle);--bs-alert-border-color: var(--bs-default-border-subtle);--bs-alert-link-color: var(--bs-default-text-emphasis)}.alert-primary{--bs-alert-color: var(--bs-primary-text-emphasis);--bs-alert-bg: var(--bs-primary-bg-subtle);--bs-alert-border-color: var(--bs-primary-border-subtle);--bs-alert-link-color: var(--bs-primary-text-emphasis)}.alert-secondary{--bs-alert-color: var(--bs-secondary-text-emphasis);--bs-alert-bg: var(--bs-secondary-bg-subtle);--bs-alert-border-color: var(--bs-secondary-border-subtle);--bs-alert-link-color: var(--bs-secondary-text-emphasis)}.alert-success{--bs-alert-color: var(--bs-success-text-emphasis);--bs-alert-bg: var(--bs-success-bg-subtle);--bs-alert-border-color: var(--bs-success-border-subtle);--bs-alert-link-color: var(--bs-success-text-emphasis)}.alert-info{--bs-alert-color: var(--bs-info-text-emphasis);--bs-alert-bg: var(--bs-info-bg-subtle);--bs-alert-border-color: var(--bs-info-border-subtle);--bs-alert-link-color: var(--bs-info-text-emphasis)}.alert-warning{--bs-alert-color: var(--bs-warning-text-emphasis);--bs-alert-bg: var(--bs-warning-bg-subtle);--bs-alert-border-color: var(--bs-warning-border-subtle);--bs-alert-link-color: var(--bs-warning-text-emphasis)}.alert-danger{--bs-alert-color: var(--bs-danger-text-emphasis);--bs-alert-bg: var(--bs-danger-bg-subtle);--bs-alert-border-color: var(--bs-danger-border-subtle);--bs-alert-link-color: var(--bs-danger-text-emphasis)}.alert-light{--bs-alert-color: var(--bs-light-text-emphasis);--bs-alert-bg: var(--bs-light-bg-subtle);--bs-alert-border-color: var(--bs-light-border-subtle);--bs-alert-link-color: var(--bs-light-text-emphasis)}.alert-dark{--bs-alert-color: var(--bs-dark-text-emphasis);--bs-alert-bg: var(--bs-dark-bg-subtle);--bs-alert-border-color: var(--bs-dark-border-subtle);--bs-alert-link-color: var(--bs-dark-text-emphasis)}@keyframes progress-bar-stripes{0%{background-position-x:1rem}}.progress,.progress-stacked{--bs-progress-height: 1rem;--bs-progress-font-size:0.75rem;--bs-progress-bg: #434343;--bs-progress-border-radius: 0.25rem;--bs-progress-box-shadow: inset 0 1px 2px rgba(0, 0, 0, 0.075);--bs-progress-bar-color: #fff;--bs-progress-bar-bg: #375a7f;--bs-progress-bar-transition: width 0.6s ease;display:flex;display:-webkit-flex;height:var(--bs-progress-height);overflow:hidden;font-size:var(--bs-progress-font-size);background-color:var(--bs-progress-bg);border-radius:var(--bs-progress-border-radius)}.progress-bar{display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;justify-content:center;-webkit-justify-content:center;overflow:hidden;color:var(--bs-progress-bar-color);text-align:center;white-space:nowrap;background-color:var(--bs-progress-bar-bg);transition:var(--bs-progress-bar-transition)}@media(prefers-reduced-motion: reduce){.progress-bar{transition:none}}.progress-bar-striped{background-image:linear-gradient(45deg, rgba(255, 255, 255, 0.15) 25%, transparent 25%, transparent 50%, rgba(255, 255, 255, 0.15) 50%, rgba(255, 255, 255, 0.15) 75%, transparent 75%, transparent);background-size:var(--bs-progress-height) var(--bs-progress-height)}.progress-stacked>.progress{overflow:visible}.progress-stacked>.progress>.progress-bar{width:100%}.progress-bar-animated{animation:1s linear infinite progress-bar-stripes}@media(prefers-reduced-motion: reduce){.progress-bar-animated{animation:none}}.list-group{--bs-list-group-color: #fff;--bs-list-group-bg: #2d2d2d;--bs-list-group-border-color: #434343;--bs-list-group-border-width: 1px;--bs-list-group-border-radius: 0.25rem;--bs-list-group-item-padding-x: 1rem;--bs-list-group-item-padding-y: 0.5rem;--bs-list-group-action-color: rgba(255, 255, 255, 0.75);--bs-list-group-action-hover-color: #fff;--bs-list-group-action-hover-bg: #434343;--bs-list-group-action-active-color: #fff;--bs-list-group-action-active-bg: #222;--bs-list-group-disabled-color: rgba(255, 255, 255, 0.75);--bs-list-group-disabled-bg: #2d2d2d;--bs-list-group-active-color: #fff;--bs-list-group-active-bg: #375a7f;--bs-list-group-active-border-color: #375a7f;display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;padding-left:0;margin-bottom:0;border-radius:var(--bs-list-group-border-radius)}.list-group-numbered{list-style-type:none;counter-reset:section}.list-group-numbered>.list-group-item::before{content:counters(section, ".") ". ";counter-increment:section}.list-group-item-action{width:100%;color:var(--bs-list-group-action-color);text-align:inherit}.list-group-item-action:hover,.list-group-item-action:focus{z-index:1;color:var(--bs-list-group-action-hover-color);text-decoration:none;background-color:var(--bs-list-group-action-hover-bg)}.list-group-item-action:active{color:var(--bs-list-group-action-active-color);background-color:var(--bs-list-group-action-active-bg)}.list-group-item{position:relative;display:block;padding:var(--bs-list-group-item-padding-y) var(--bs-list-group-item-padding-x);color:var(--bs-list-group-color);text-decoration:none;-webkit-text-decoration:none;-moz-text-decoration:none;-ms-text-decoration:none;-o-text-decoration:none;background-color:var(--bs-list-group-bg);border:var(--bs-list-group-border-width) solid var(--bs-list-group-border-color)}.list-group-item:first-child{border-top-left-radius:inherit;border-top-right-radius:inherit}.list-group-item:last-child{border-bottom-right-radius:inherit;border-bottom-left-radius:inherit}.list-group-item.disabled,.list-group-item:disabled{color:var(--bs-list-group-disabled-color);pointer-events:none;background-color:var(--bs-list-group-disabled-bg)}.list-group-item.active{z-index:2;color:var(--bs-list-group-active-color);background-color:var(--bs-list-group-active-bg);border-color:var(--bs-list-group-active-border-color)}.list-group-item+.list-group-item{border-top-width:0}.list-group-item+.list-group-item.active{margin-top:calc(-1*var(--bs-list-group-border-width));border-top-width:var(--bs-list-group-border-width)}.list-group-horizontal{flex-direction:row;-webkit-flex-direction:row}.list-group-horizontal>.list-group-item:first-child:not(:last-child){border-bottom-left-radius:var(--bs-list-group-border-radius);border-top-right-radius:0}.list-group-horizontal>.list-group-item:last-child:not(:first-child){border-top-right-radius:var(--bs-list-group-border-radius);border-bottom-left-radius:0}.list-group-horizontal>.list-group-item.active{margin-top:0}.list-group-horizontal>.list-group-item+.list-group-item{border-top-width:var(--bs-list-group-border-width);border-left-width:0}.list-group-horizontal>.list-group-item+.list-group-item.active{margin-left:calc(-1*var(--bs-list-group-border-width));border-left-width:var(--bs-list-group-border-width)}@media(min-width: 576px){.list-group-horizontal-sm{flex-direction:row;-webkit-flex-direction:row}.list-group-horizontal-sm>.list-group-item:first-child:not(:last-child){border-bottom-left-radius:var(--bs-list-group-border-radius);border-top-right-radius:0}.list-group-horizontal-sm>.list-group-item:last-child:not(:first-child){border-top-right-radius:var(--bs-list-group-border-radius);border-bottom-left-radius:0}.list-group-horizontal-sm>.list-group-item.active{margin-top:0}.list-group-horizontal-sm>.list-group-item+.list-group-item{border-top-width:var(--bs-list-group-border-width);border-left-width:0}.list-group-horizontal-sm>.list-group-item+.list-group-item.active{margin-left:calc(-1*var(--bs-list-group-border-width));border-left-width:var(--bs-list-group-border-width)}}@media(min-width: 768px){.list-group-horizontal-md{flex-direction:row;-webkit-flex-direction:row}.list-group-horizontal-md>.list-group-item:first-child:not(:last-child){border-bottom-left-radius:var(--bs-list-group-border-radius);border-top-right-radius:0}.list-group-horizontal-md>.list-group-item:last-child:not(:first-child){border-top-right-radius:var(--bs-list-group-border-radius);border-bottom-left-radius:0}.list-group-horizontal-md>.list-group-item.active{margin-top:0}.list-group-horizontal-md>.list-group-item+.list-group-item{border-top-width:var(--bs-list-group-border-width);border-left-width:0}.list-group-horizontal-md>.list-group-item+.list-group-item.active{margin-left:calc(-1*var(--bs-list-group-border-width));border-left-width:var(--bs-list-group-border-width)}}@media(min-width: 992px){.list-group-horizontal-lg{flex-direction:row;-webkit-flex-direction:row}.list-group-horizontal-lg>.list-group-item:first-child:not(:last-child){border-bottom-left-radius:var(--bs-list-group-border-radius);border-top-right-radius:0}.list-group-horizontal-lg>.list-group-item:last-child:not(:first-child){border-top-right-radius:var(--bs-list-group-border-radius);border-bottom-left-radius:0}.list-group-horizontal-lg>.list-group-item.active{margin-top:0}.list-group-horizontal-lg>.list-group-item+.list-group-item{border-top-width:var(--bs-list-group-border-width);border-left-width:0}.list-group-horizontal-lg>.list-group-item+.list-group-item.active{margin-left:calc(-1*var(--bs-list-group-border-width));border-left-width:var(--bs-list-group-border-width)}}@media(min-width: 1200px){.list-group-horizontal-xl{flex-direction:row;-webkit-flex-direction:row}.list-group-horizontal-xl>.list-group-item:first-child:not(:last-child){border-bottom-left-radius:var(--bs-list-group-border-radius);border-top-right-radius:0}.list-group-horizontal-xl>.list-group-item:last-child:not(:first-child){border-top-right-radius:var(--bs-list-group-border-radius);border-bottom-left-radius:0}.list-group-horizontal-xl>.list-group-item.active{margin-top:0}.list-group-horizontal-xl>.list-group-item+.list-group-item{border-top-width:var(--bs-list-group-border-width);border-left-width:0}.list-group-horizontal-xl>.list-group-item+.list-group-item.active{margin-left:calc(-1*var(--bs-list-group-border-width));border-left-width:var(--bs-list-group-border-width)}}@media(min-width: 1400px){.list-group-horizontal-xxl{flex-direction:row;-webkit-flex-direction:row}.list-group-horizontal-xxl>.list-group-item:first-child:not(:last-child){border-bottom-left-radius:var(--bs-list-group-border-radius);border-top-right-radius:0}.list-group-horizontal-xxl>.list-group-item:last-child:not(:first-child){border-top-right-radius:var(--bs-list-group-border-radius);border-bottom-left-radius:0}.list-group-horizontal-xxl>.list-group-item.active{margin-top:0}.list-group-horizontal-xxl>.list-group-item+.list-group-item{border-top-width:var(--bs-list-group-border-width);border-left-width:0}.list-group-horizontal-xxl>.list-group-item+.list-group-item.active{margin-left:calc(-1*var(--bs-list-group-border-width));border-left-width:var(--bs-list-group-border-width)}}.list-group-flush{border-radius:0}.list-group-flush>.list-group-item{border-width:0 0 var(--bs-list-group-border-width)}.list-group-flush>.list-group-item:last-child{border-bottom-width:0}.list-group-item-default{--bs-list-group-color: var(--bs-default-text-emphasis);--bs-list-group-bg: var(--bs-default-bg-subtle);--bs-list-group-border-color: var(--bs-default-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-default-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-default-border-subtle);--bs-list-group-active-color: var(--bs-default-bg-subtle);--bs-list-group-active-bg: var(--bs-default-text-emphasis);--bs-list-group-active-border-color: var(--bs-default-text-emphasis)}.list-group-item-primary{--bs-list-group-color: var(--bs-primary-text-emphasis);--bs-list-group-bg: var(--bs-primary-bg-subtle);--bs-list-group-border-color: var(--bs-primary-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-primary-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-primary-border-subtle);--bs-list-group-active-color: var(--bs-primary-bg-subtle);--bs-list-group-active-bg: var(--bs-primary-text-emphasis);--bs-list-group-active-border-color: var(--bs-primary-text-emphasis)}.list-group-item-secondary{--bs-list-group-color: var(--bs-secondary-text-emphasis);--bs-list-group-bg: var(--bs-secondary-bg-subtle);--bs-list-group-border-color: var(--bs-secondary-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-secondary-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-secondary-border-subtle);--bs-list-group-active-color: var(--bs-secondary-bg-subtle);--bs-list-group-active-bg: var(--bs-secondary-text-emphasis);--bs-list-group-active-border-color: var(--bs-secondary-text-emphasis)}.list-group-item-success{--bs-list-group-color: var(--bs-success-text-emphasis);--bs-list-group-bg: var(--bs-success-bg-subtle);--bs-list-group-border-color: var(--bs-success-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-success-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-success-border-subtle);--bs-list-group-active-color: var(--bs-success-bg-subtle);--bs-list-group-active-bg: var(--bs-success-text-emphasis);--bs-list-group-active-border-color: var(--bs-success-text-emphasis)}.list-group-item-info{--bs-list-group-color: var(--bs-info-text-emphasis);--bs-list-group-bg: var(--bs-info-bg-subtle);--bs-list-group-border-color: var(--bs-info-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-info-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-info-border-subtle);--bs-list-group-active-color: var(--bs-info-bg-subtle);--bs-list-group-active-bg: var(--bs-info-text-emphasis);--bs-list-group-active-border-color: var(--bs-info-text-emphasis)}.list-group-item-warning{--bs-list-group-color: var(--bs-warning-text-emphasis);--bs-list-group-bg: var(--bs-warning-bg-subtle);--bs-list-group-border-color: var(--bs-warning-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-warning-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-warning-border-subtle);--bs-list-group-active-color: var(--bs-warning-bg-subtle);--bs-list-group-active-bg: var(--bs-warning-text-emphasis);--bs-list-group-active-border-color: var(--bs-warning-text-emphasis)}.list-group-item-danger{--bs-list-group-color: var(--bs-danger-text-emphasis);--bs-list-group-bg: var(--bs-danger-bg-subtle);--bs-list-group-border-color: var(--bs-danger-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-danger-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-danger-border-subtle);--bs-list-group-active-color: var(--bs-danger-bg-subtle);--bs-list-group-active-bg: var(--bs-danger-text-emphasis);--bs-list-group-active-border-color: var(--bs-danger-text-emphasis)}.list-group-item-light{--bs-list-group-color: var(--bs-light-text-emphasis);--bs-list-group-bg: var(--bs-light-bg-subtle);--bs-list-group-border-color: var(--bs-light-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-light-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-light-border-subtle);--bs-list-group-active-color: var(--bs-light-bg-subtle);--bs-list-group-active-bg: var(--bs-light-text-emphasis);--bs-list-group-active-border-color: var(--bs-light-text-emphasis)}.list-group-item-dark{--bs-list-group-color: var(--bs-dark-text-emphasis);--bs-list-group-bg: var(--bs-dark-bg-subtle);--bs-list-group-border-color: var(--bs-dark-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-dark-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-dark-border-subtle);--bs-list-group-active-color: var(--bs-dark-bg-subtle);--bs-list-group-active-bg: var(--bs-dark-text-emphasis);--bs-list-group-active-border-color: var(--bs-dark-text-emphasis)}.btn-close{--bs-btn-close-color: #fff;--bs-btn-close-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='%23fff'%3e%3cpath d='M.293.293a1 1 0 0 1 1.414 0L8 6.586 14.293.293a1 1 0 1 1 1.414 1.414L9.414 8l6.293 6.293a1 1 0 0 1-1.414 1.414L8 9.414l-6.293 6.293a1 1 0 0 1-1.414-1.414L6.586 8 .293 1.707a1 1 0 0 1 0-1.414z'/%3e%3c/svg%3e");--bs-btn-close-opacity: 0.4;--bs-btn-close-hover-opacity: 1;--bs-btn-close-focus-shadow: 0 0 0 0.25rem rgba(55, 90, 127, 0.25);--bs-btn-close-focus-opacity: 1;--bs-btn-close-disabled-opacity: 0.25;--bs-btn-close-white-filter: invert(1) grayscale(100%) brightness(200%);box-sizing:content-box;width:1em;height:1em;padding:.25em .25em;color:var(--bs-btn-close-color);background:rgba(0,0,0,0) var(--bs-btn-close-bg) center/1em auto no-repeat;border:0;border-radius:.25rem;opacity:var(--bs-btn-close-opacity)}.btn-close:hover{color:var(--bs-btn-close-color);text-decoration:none;opacity:var(--bs-btn-close-hover-opacity)}.btn-close:focus{outline:0;box-shadow:var(--bs-btn-close-focus-shadow);opacity:var(--bs-btn-close-focus-opacity)}.btn-close:disabled,.btn-close.disabled{pointer-events:none;user-select:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;-o-user-select:none;opacity:var(--bs-btn-close-disabled-opacity)}.btn-close-white{filter:var(--bs-btn-close-white-filter)}[data-bs-theme=dark] .btn-close{filter:var(--bs-btn-close-white-filter)}.toast{--bs-toast-zindex: 1090;--bs-toast-padding-x: 0.75rem;--bs-toast-padding-y: 0.5rem;--bs-toast-spacing: 1.5rem;--bs-toast-max-width: 350px;--bs-toast-font-size:0.875rem;--bs-toast-color: ;--bs-toast-bg: #434343;--bs-toast-border-width: 1px;--bs-toast-border-color: rgba(0, 0, 0, 0.175);--bs-toast-border-radius: 0.25rem;--bs-toast-box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);--bs-toast-header-color: rgba(255, 255, 255, 0.75);--bs-toast-header-bg: #2d2d2d;--bs-toast-header-border-color: rgba(0, 0, 0, 0.175);width:var(--bs-toast-max-width);max-width:100%;font-size:var(--bs-toast-font-size);color:var(--bs-toast-color);pointer-events:auto;background-color:var(--bs-toast-bg);background-clip:padding-box;border:var(--bs-toast-border-width) solid var(--bs-toast-border-color);box-shadow:var(--bs-toast-box-shadow);border-radius:var(--bs-toast-border-radius)}.toast.showing{opacity:0}.toast:not(.show){display:none}.toast-container{--bs-toast-zindex: 1090;position:absolute;z-index:var(--bs-toast-zindex);width:max-content;width:-webkit-max-content;width:-moz-max-content;width:-ms-max-content;width:-o-max-content;max-width:100%;pointer-events:none}.toast-container>:not(:last-child){margin-bottom:var(--bs-toast-spacing)}.toast-header{display:flex;display:-webkit-flex;align-items:center;-webkit-align-items:center;padding:var(--bs-toast-padding-y) var(--bs-toast-padding-x);color:var(--bs-toast-header-color);background-color:var(--bs-toast-header-bg);background-clip:padding-box;border-bottom:var(--bs-toast-border-width) solid var(--bs-toast-header-border-color);border-top-left-radius:calc(var(--bs-toast-border-radius) - var(--bs-toast-border-width));border-top-right-radius:calc(var(--bs-toast-border-radius) - var(--bs-toast-border-width))}.toast-header .btn-close{margin-right:calc(-0.5*var(--bs-toast-padding-x));margin-left:var(--bs-toast-padding-x)}.toast-body{padding:var(--bs-toast-padding-x);word-wrap:break-word}.modal{--bs-modal-zindex: 1055;--bs-modal-width: 500px;--bs-modal-padding: 1rem;--bs-modal-margin: 0.5rem;--bs-modal-color: ;--bs-modal-bg: #2d2d2d;--bs-modal-border-color: #434343;--bs-modal-border-width: 1px;--bs-modal-border-radius: 0.5rem;--bs-modal-box-shadow: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.075);--bs-modal-inner-border-radius: calc(0.5rem - 1px);--bs-modal-header-padding-x: 1rem;--bs-modal-header-padding-y: 1rem;--bs-modal-header-padding: 1rem 1rem;--bs-modal-header-border-color: #434343;--bs-modal-header-border-width: 1px;--bs-modal-title-line-height: 1.5;--bs-modal-footer-gap: 0.5rem;--bs-modal-footer-bg: ;--bs-modal-footer-border-color: #434343;--bs-modal-footer-border-width: 1px;position:fixed;top:0;left:0;z-index:var(--bs-modal-zindex);display:none;width:100%;height:100%;overflow-x:hidden;overflow-y:auto;outline:0}.modal-dialog{position:relative;width:auto;margin:var(--bs-modal-margin);pointer-events:none}.modal.fade .modal-dialog{transition:transform .3s ease-out;transform:translate(0, -50px)}@media(prefers-reduced-motion: reduce){.modal.fade .modal-dialog{transition:none}}.modal.show .modal-dialog{transform:none}.modal.modal-static .modal-dialog{transform:scale(1.02)}.modal-dialog-scrollable{height:calc(100% - var(--bs-modal-margin)*2)}.modal-dialog-scrollable .modal-content{max-height:100%;overflow:hidden}.modal-dialog-scrollable .modal-body{overflow-y:auto}.modal-dialog-centered{display:flex;display:-webkit-flex;align-items:center;-webkit-align-items:center;min-height:calc(100% - var(--bs-modal-margin)*2)}.modal-content{position:relative;display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;width:100%;color:var(--bs-modal-color);pointer-events:auto;background-color:var(--bs-modal-bg);background-clip:padding-box;border:var(--bs-modal-border-width) solid var(--bs-modal-border-color);border-radius:var(--bs-modal-border-radius);outline:0}.modal-backdrop{--bs-backdrop-zindex: 1050;--bs-backdrop-bg: #000;--bs-backdrop-opacity: 0.5;position:fixed;top:0;left:0;z-index:var(--bs-backdrop-zindex);width:100vw;height:100vh;background-color:var(--bs-backdrop-bg)}.modal-backdrop.fade{opacity:0}.modal-backdrop.show{opacity:var(--bs-backdrop-opacity)}.modal-header{display:flex;display:-webkit-flex;flex-shrink:0;-webkit-flex-shrink:0;align-items:center;-webkit-align-items:center;justify-content:space-between;-webkit-justify-content:space-between;padding:var(--bs-modal-header-padding);border-bottom:var(--bs-modal-header-border-width) solid var(--bs-modal-header-border-color);border-top-left-radius:var(--bs-modal-inner-border-radius);border-top-right-radius:var(--bs-modal-inner-border-radius)}.modal-header .btn-close{padding:calc(var(--bs-modal-header-padding-y)*.5) calc(var(--bs-modal-header-padding-x)*.5);margin:calc(-0.5*var(--bs-modal-header-padding-y)) calc(-0.5*var(--bs-modal-header-padding-x)) calc(-0.5*var(--bs-modal-header-padding-y)) auto}.modal-title{margin-bottom:0;line-height:var(--bs-modal-title-line-height)}.modal-body{position:relative;flex:1 1 auto;-webkit-flex:1 1 auto;padding:var(--bs-modal-padding)}.modal-footer{display:flex;display:-webkit-flex;flex-shrink:0;-webkit-flex-shrink:0;flex-wrap:wrap;-webkit-flex-wrap:wrap;align-items:center;-webkit-align-items:center;justify-content:flex-end;-webkit-justify-content:flex-end;padding:calc(var(--bs-modal-padding) - var(--bs-modal-footer-gap)*.5);background-color:var(--bs-modal-footer-bg);border-top:var(--bs-modal-footer-border-width) solid var(--bs-modal-footer-border-color);border-bottom-right-radius:var(--bs-modal-inner-border-radius);border-bottom-left-radius:var(--bs-modal-inner-border-radius)}.modal-footer>*{margin:calc(var(--bs-modal-footer-gap)*.5)}@media(min-width: 576px){.modal{--bs-modal-margin: 1.75rem;--bs-modal-box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15)}.modal-dialog{max-width:var(--bs-modal-width);margin-right:auto;margin-left:auto}.modal-sm{--bs-modal-width: 300px}}@media(min-width: 992px){.modal-lg,.modal-xl{--bs-modal-width: 800px}}@media(min-width: 1200px){.modal-xl{--bs-modal-width: 1140px}}.modal-fullscreen{width:100vw;max-width:none;height:100%;margin:0}.modal-fullscreen .modal-content{height:100%;border:0;border-radius:0}.modal-fullscreen .modal-header,.modal-fullscreen .modal-footer{border-radius:0}.modal-fullscreen .modal-body{overflow-y:auto}@media(max-width: 575.98px){.modal-fullscreen-sm-down{width:100vw;max-width:none;height:100%;margin:0}.modal-fullscreen-sm-down .modal-content{height:100%;border:0;border-radius:0}.modal-fullscreen-sm-down .modal-header,.modal-fullscreen-sm-down .modal-footer{border-radius:0}.modal-fullscreen-sm-down .modal-body{overflow-y:auto}}@media(max-width: 767.98px){.modal-fullscreen-md-down{width:100vw;max-width:none;height:100%;margin:0}.modal-fullscreen-md-down .modal-content{height:100%;border:0;border-radius:0}.modal-fullscreen-md-down .modal-header,.modal-fullscreen-md-down .modal-footer{border-radius:0}.modal-fullscreen-md-down .modal-body{overflow-y:auto}}@media(max-width: 991.98px){.modal-fullscreen-lg-down{width:100vw;max-width:none;height:100%;margin:0}.modal-fullscreen-lg-down .modal-content{height:100%;border:0;border-radius:0}.modal-fullscreen-lg-down .modal-header,.modal-fullscreen-lg-down .modal-footer{border-radius:0}.modal-fullscreen-lg-down .modal-body{overflow-y:auto}}@media(max-width: 1199.98px){.modal-fullscreen-xl-down{width:100vw;max-width:none;height:100%;margin:0}.modal-fullscreen-xl-down .modal-content{height:100%;border:0;border-radius:0}.modal-fullscreen-xl-down .modal-header,.modal-fullscreen-xl-down .modal-footer{border-radius:0}.modal-fullscreen-xl-down .modal-body{overflow-y:auto}}@media(max-width: 1399.98px){.modal-fullscreen-xxl-down{width:100vw;max-width:none;height:100%;margin:0}.modal-fullscreen-xxl-down .modal-content{height:100%;border:0;border-radius:0}.modal-fullscreen-xxl-down .modal-header,.modal-fullscreen-xxl-down .modal-footer{border-radius:0}.modal-fullscreen-xxl-down .modal-body{overflow-y:auto}}.tooltip{--bs-tooltip-zindex: 1080;--bs-tooltip-max-width: 200px;--bs-tooltip-padding-x: 0.5rem;--bs-tooltip-padding-y: 0.25rem;--bs-tooltip-margin: ;--bs-tooltip-font-size:0.875rem;--bs-tooltip-color: #222;--bs-tooltip-bg: #000;--bs-tooltip-border-radius: 0.25rem;--bs-tooltip-opacity: 0.9;--bs-tooltip-arrow-width: 0.8rem;--bs-tooltip-arrow-height: 0.4rem;z-index:var(--bs-tooltip-zindex);display:block;margin:var(--bs-tooltip-margin);font-family:Lato,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol";font-style:normal;font-weight:400;line-height:1.5;text-align:left;text-align:start;text-decoration:none;text-shadow:none;text-transform:none;letter-spacing:normal;word-break:normal;white-space:normal;word-spacing:normal;line-break:auto;font-size:var(--bs-tooltip-font-size);word-wrap:break-word;opacity:0}.tooltip.show{opacity:var(--bs-tooltip-opacity)}.tooltip .tooltip-arrow{display:block;width:var(--bs-tooltip-arrow-width);height:var(--bs-tooltip-arrow-height)}.tooltip .tooltip-arrow::before{position:absolute;content:"";border-color:rgba(0,0,0,0);border-style:solid}.bs-tooltip-top .tooltip-arrow,.bs-tooltip-auto[data-popper-placement^=top] .tooltip-arrow{bottom:calc(-1*var(--bs-tooltip-arrow-height))}.bs-tooltip-top .tooltip-arrow::before,.bs-tooltip-auto[data-popper-placement^=top] .tooltip-arrow::before{top:-1px;border-width:var(--bs-tooltip-arrow-height) calc(var(--bs-tooltip-arrow-width)*.5) 0;border-top-color:var(--bs-tooltip-bg)}.bs-tooltip-end .tooltip-arrow,.bs-tooltip-auto[data-popper-placement^=right] .tooltip-arrow{left:calc(-1*var(--bs-tooltip-arrow-height));width:var(--bs-tooltip-arrow-height);height:var(--bs-tooltip-arrow-width)}.bs-tooltip-end .tooltip-arrow::before,.bs-tooltip-auto[data-popper-placement^=right] .tooltip-arrow::before{right:-1px;border-width:calc(var(--bs-tooltip-arrow-width)*.5) var(--bs-tooltip-arrow-height) calc(var(--bs-tooltip-arrow-width)*.5) 0;border-right-color:var(--bs-tooltip-bg)}.bs-tooltip-bottom .tooltip-arrow,.bs-tooltip-auto[data-popper-placement^=bottom] .tooltip-arrow{top:calc(-1*var(--bs-tooltip-arrow-height))}.bs-tooltip-bottom .tooltip-arrow::before,.bs-tooltip-auto[data-popper-placement^=bottom] .tooltip-arrow::before{bottom:-1px;border-width:0 calc(var(--bs-tooltip-arrow-width)*.5) var(--bs-tooltip-arrow-height);border-bottom-color:var(--bs-tooltip-bg)}.bs-tooltip-start .tooltip-arrow,.bs-tooltip-auto[data-popper-placement^=left] .tooltip-arrow{right:calc(-1*var(--bs-tooltip-arrow-height));width:var(--bs-tooltip-arrow-height);height:var(--bs-tooltip-arrow-width)}.bs-tooltip-start .tooltip-arrow::before,.bs-tooltip-auto[data-popper-placement^=left] .tooltip-arrow::before{left:-1px;border-width:calc(var(--bs-tooltip-arrow-width)*.5) 0 calc(var(--bs-tooltip-arrow-width)*.5) var(--bs-tooltip-arrow-height);border-left-color:var(--bs-tooltip-bg)}.tooltip-inner{max-width:var(--bs-tooltip-max-width);padding:var(--bs-tooltip-padding-y) var(--bs-tooltip-padding-x);color:var(--bs-tooltip-color);text-align:center;background-color:var(--bs-tooltip-bg);border-radius:var(--bs-tooltip-border-radius)}.popover{--bs-popover-zindex: 1070;--bs-popover-max-width: 276px;--bs-popover-font-size:0.875rem;--bs-popover-bg: #2d2d2d;--bs-popover-border-width: 1px;--bs-popover-border-color: rgba(0, 0, 0, 0.175);--bs-popover-border-radius: 0.5rem;--bs-popover-inner-border-radius: calc(0.5rem - 1px);--bs-popover-box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);--bs-popover-header-padding-x: 1rem;--bs-popover-header-padding-y: 0.5rem;--bs-popover-header-font-size:1rem;--bs-popover-header-color: inherit;--bs-popover-header-bg: #434343;--bs-popover-body-padding-x: 1rem;--bs-popover-body-padding-y: 1rem;--bs-popover-body-color: #fff;--bs-popover-arrow-width: 1rem;--bs-popover-arrow-height: 0.5rem;--bs-popover-arrow-border: var(--bs-popover-border-color);z-index:var(--bs-popover-zindex);display:block;max-width:var(--bs-popover-max-width);font-family:Lato,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol";font-style:normal;font-weight:400;line-height:1.5;text-align:left;text-align:start;text-decoration:none;text-shadow:none;text-transform:none;letter-spacing:normal;word-break:normal;white-space:normal;word-spacing:normal;line-break:auto;font-size:var(--bs-popover-font-size);word-wrap:break-word;background-color:var(--bs-popover-bg);background-clip:padding-box;border:var(--bs-popover-border-width) solid var(--bs-popover-border-color);border-radius:var(--bs-popover-border-radius)}.popover .popover-arrow{display:block;width:var(--bs-popover-arrow-width);height:var(--bs-popover-arrow-height)}.popover .popover-arrow::before,.popover .popover-arrow::after{position:absolute;display:block;content:"";border-color:rgba(0,0,0,0);border-style:solid;border-width:0}.bs-popover-top>.popover-arrow,.bs-popover-auto[data-popper-placement^=top]>.popover-arrow{bottom:calc(-1*(var(--bs-popover-arrow-height)) - var(--bs-popover-border-width))}.bs-popover-top>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=top]>.popover-arrow::before,.bs-popover-top>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=top]>.popover-arrow::after{border-width:var(--bs-popover-arrow-height) calc(var(--bs-popover-arrow-width)*.5) 0}.bs-popover-top>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=top]>.popover-arrow::before{bottom:0;border-top-color:var(--bs-popover-arrow-border)}.bs-popover-top>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=top]>.popover-arrow::after{bottom:var(--bs-popover-border-width);border-top-color:var(--bs-popover-bg)}.bs-popover-end>.popover-arrow,.bs-popover-auto[data-popper-placement^=right]>.popover-arrow{left:calc(-1*(var(--bs-popover-arrow-height)) - var(--bs-popover-border-width));width:var(--bs-popover-arrow-height);height:var(--bs-popover-arrow-width)}.bs-popover-end>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=right]>.popover-arrow::before,.bs-popover-end>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=right]>.popover-arrow::after{border-width:calc(var(--bs-popover-arrow-width)*.5) var(--bs-popover-arrow-height) calc(var(--bs-popover-arrow-width)*.5) 0}.bs-popover-end>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=right]>.popover-arrow::before{left:0;border-right-color:var(--bs-popover-arrow-border)}.bs-popover-end>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=right]>.popover-arrow::after{left:var(--bs-popover-border-width);border-right-color:var(--bs-popover-bg)}.bs-popover-bottom>.popover-arrow,.bs-popover-auto[data-popper-placement^=bottom]>.popover-arrow{top:calc(-1*(var(--bs-popover-arrow-height)) - var(--bs-popover-border-width))}.bs-popover-bottom>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=bottom]>.popover-arrow::before,.bs-popover-bottom>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=bottom]>.popover-arrow::after{border-width:0 calc(var(--bs-popover-arrow-width)*.5) var(--bs-popover-arrow-height)}.bs-popover-bottom>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=bottom]>.popover-arrow::before{top:0;border-bottom-color:var(--bs-popover-arrow-border)}.bs-popover-bottom>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=bottom]>.popover-arrow::after{top:var(--bs-popover-border-width);border-bottom-color:var(--bs-popover-bg)}.bs-popover-bottom .popover-header::before,.bs-popover-auto[data-popper-placement^=bottom] .popover-header::before{position:absolute;top:0;left:50%;display:block;width:var(--bs-popover-arrow-width);margin-left:calc(-0.5*var(--bs-popover-arrow-width));content:"";border-bottom:var(--bs-popover-border-width) solid var(--bs-popover-header-bg)}.bs-popover-start>.popover-arrow,.bs-popover-auto[data-popper-placement^=left]>.popover-arrow{right:calc(-1*(var(--bs-popover-arrow-height)) - var(--bs-popover-border-width));width:var(--bs-popover-arrow-height);height:var(--bs-popover-arrow-width)}.bs-popover-start>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=left]>.popover-arrow::before,.bs-popover-start>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=left]>.popover-arrow::after{border-width:calc(var(--bs-popover-arrow-width)*.5) 0 calc(var(--bs-popover-arrow-width)*.5) var(--bs-popover-arrow-height)}.bs-popover-start>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=left]>.popover-arrow::before{right:0;border-left-color:var(--bs-popover-arrow-border)}.bs-popover-start>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=left]>.popover-arrow::after{right:var(--bs-popover-border-width);border-left-color:var(--bs-popover-bg)}.popover-header{padding:var(--bs-popover-header-padding-y) var(--bs-popover-header-padding-x);margin-bottom:0;font-size:var(--bs-popover-header-font-size);color:var(--bs-popover-header-color);background-color:var(--bs-popover-header-bg);border-bottom:var(--bs-popover-border-width) solid var(--bs-popover-border-color);border-top-left-radius:var(--bs-popover-inner-border-radius);border-top-right-radius:var(--bs-popover-inner-border-radius)}.popover-header:empty{display:none}.popover-body{padding:var(--bs-popover-body-padding-y) var(--bs-popover-body-padding-x);color:var(--bs-popover-body-color)}.carousel{position:relative}.carousel.pointer-event{touch-action:pan-y;-webkit-touch-action:pan-y;-moz-touch-action:pan-y;-ms-touch-action:pan-y;-o-touch-action:pan-y}.carousel-inner{position:relative;width:100%;overflow:hidden}.carousel-inner::after{display:block;clear:both;content:""}.carousel-item{position:relative;display:none;float:left;width:100%;margin-right:-100%;backface-visibility:hidden;-webkit-backface-visibility:hidden;-moz-backface-visibility:hidden;-ms-backface-visibility:hidden;-o-backface-visibility:hidden;transition:transform .6s ease-in-out}@media(prefers-reduced-motion: reduce){.carousel-item{transition:none}}.carousel-item.active,.carousel-item-next,.carousel-item-prev{display:block}.carousel-item-next:not(.carousel-item-start),.active.carousel-item-end{transform:translateX(100%)}.carousel-item-prev:not(.carousel-item-end),.active.carousel-item-start{transform:translateX(-100%)}.carousel-fade .carousel-item{opacity:0;transition-property:opacity;transform:none}.carousel-fade .carousel-item.active,.carousel-fade .carousel-item-next.carousel-item-start,.carousel-fade .carousel-item-prev.carousel-item-end{z-index:1;opacity:1}.carousel-fade .active.carousel-item-start,.carousel-fade .active.carousel-item-end{z-index:0;opacity:0;transition:opacity 0s .6s}@media(prefers-reduced-motion: reduce){.carousel-fade .active.carousel-item-start,.carousel-fade .active.carousel-item-end{transition:none}}.carousel-control-prev,.carousel-control-next{position:absolute;top:0;bottom:0;z-index:1;display:flex;display:-webkit-flex;align-items:center;-webkit-align-items:center;justify-content:center;-webkit-justify-content:center;width:15%;padding:0;color:#fff;text-align:center;background:none;border:0;opacity:.5;transition:opacity .15s ease}@media(prefers-reduced-motion: reduce){.carousel-control-prev,.carousel-control-next{transition:none}}.carousel-control-prev:hover,.carousel-control-prev:focus,.carousel-control-next:hover,.carousel-control-next:focus{color:#fff;text-decoration:none;outline:0;opacity:.9}.carousel-control-prev{left:0}.carousel-control-next{right:0}.carousel-control-prev-icon,.carousel-control-next-icon{display:inline-block;width:2rem;height:2rem;background-repeat:no-repeat;background-position:50%;background-size:100% 100%}.carousel-control-prev-icon{background-image:url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='%23fff'%3e%3cpath d='M11.354 1.646a.5.5 0 0 1 0 .708L5.707 8l5.647 5.646a.5.5 0 0 1-.708.708l-6-6a.5.5 0 0 1 0-.708l6-6a.5.5 0 0 1 .708 0z'/%3e%3c/svg%3e")}.carousel-control-next-icon{background-image:url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='%23fff'%3e%3cpath d='M4.646 1.646a.5.5 0 0 1 .708 0l6 6a.5.5 0 0 1 0 .708l-6 6a.5.5 0 0 1-.708-.708L10.293 8 4.646 2.354a.5.5 0 0 1 0-.708z'/%3e%3c/svg%3e")}.carousel-indicators{position:absolute;right:0;bottom:0;left:0;z-index:2;display:flex;display:-webkit-flex;justify-content:center;-webkit-justify-content:center;padding:0;margin-right:15%;margin-bottom:1rem;margin-left:15%}.carousel-indicators [data-bs-target]{box-sizing:content-box;flex:0 1 auto;-webkit-flex:0 1 auto;width:30px;height:3px;padding:0;margin-right:3px;margin-left:3px;text-indent:-999px;cursor:pointer;background-color:#fff;background-clip:padding-box;border:0;border-top:10px solid rgba(0,0,0,0);border-bottom:10px solid rgba(0,0,0,0);opacity:.5;transition:opacity .6s ease}@media(prefers-reduced-motion: reduce){.carousel-indicators [data-bs-target]{transition:none}}.carousel-indicators .active{opacity:1}.carousel-caption{position:absolute;right:15%;bottom:1.25rem;left:15%;padding-top:1.25rem;padding-bottom:1.25rem;color:#fff;text-align:center}.carousel-dark .carousel-control-prev-icon,.carousel-dark .carousel-control-next-icon{filter:invert(1) grayscale(100)}.carousel-dark .carousel-indicators [data-bs-target]{background-color:#000}.carousel-dark .carousel-caption{color:#000}[data-bs-theme=dark] .carousel .carousel-control-prev-icon,[data-bs-theme=dark] .carousel .carousel-control-next-icon,[data-bs-theme=dark].carousel .carousel-control-prev-icon,[data-bs-theme=dark].carousel .carousel-control-next-icon{filter:invert(1) grayscale(100)}[data-bs-theme=dark] .carousel .carousel-indicators [data-bs-target],[data-bs-theme=dark].carousel .carousel-indicators [data-bs-target]{background-color:#000}[data-bs-theme=dark] .carousel .carousel-caption,[data-bs-theme=dark].carousel .carousel-caption{color:#000}.spinner-grow,.spinner-border{display:inline-block;width:var(--bs-spinner-width);height:var(--bs-spinner-height);vertical-align:var(--bs-spinner-vertical-align);border-radius:50%;animation:var(--bs-spinner-animation-speed) linear infinite var(--bs-spinner-animation-name)}@keyframes spinner-border{to{transform:rotate(360deg) /* rtl:ignore */}}.spinner-border{--bs-spinner-width: 2rem;--bs-spinner-height: 2rem;--bs-spinner-vertical-align: -0.125em;--bs-spinner-border-width: 0.25em;--bs-spinner-animation-speed: 0.75s;--bs-spinner-animation-name: spinner-border;border:var(--bs-spinner-border-width) solid currentcolor;border-right-color:rgba(0,0,0,0)}.spinner-border-sm{--bs-spinner-width: 1rem;--bs-spinner-height: 1rem;--bs-spinner-border-width: 0.2em}@keyframes spinner-grow{0%{transform:scale(0)}50%{opacity:1;transform:none}}.spinner-grow{--bs-spinner-width: 2rem;--bs-spinner-height: 2rem;--bs-spinner-vertical-align: -0.125em;--bs-spinner-animation-speed: 0.75s;--bs-spinner-animation-name: spinner-grow;background-color:currentcolor;opacity:0}.spinner-grow-sm{--bs-spinner-width: 1rem;--bs-spinner-height: 1rem}@media(prefers-reduced-motion: reduce){.spinner-border,.spinner-grow{--bs-spinner-animation-speed: 1.5s}}.offcanvas,.offcanvas-xxl,.offcanvas-xl,.offcanvas-lg,.offcanvas-md,.offcanvas-sm{--bs-offcanvas-zindex: 1045;--bs-offcanvas-width: 400px;--bs-offcanvas-height: 30vh;--bs-offcanvas-padding-x: 1rem;--bs-offcanvas-padding-y: 1rem;--bs-offcanvas-color: #fff;--bs-offcanvas-bg: #222;--bs-offcanvas-border-width: 1px;--bs-offcanvas-border-color: #434343;--bs-offcanvas-box-shadow: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.075);--bs-offcanvas-transition: transform 0.3s ease-in-out;--bs-offcanvas-title-line-height: 1.5}@media(max-width: 575.98px){.offcanvas-sm{position:fixed;bottom:0;z-index:var(--bs-offcanvas-zindex);display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;max-width:100%;color:var(--bs-offcanvas-color);visibility:hidden;background-color:var(--bs-offcanvas-bg);background-clip:padding-box;outline:0;transition:var(--bs-offcanvas-transition)}}@media(max-width: 575.98px)and (prefers-reduced-motion: reduce){.offcanvas-sm{transition:none}}@media(max-width: 575.98px){.offcanvas-sm.offcanvas-start{top:0;left:0;width:var(--bs-offcanvas-width);border-right:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(-100%)}.offcanvas-sm.offcanvas-end{top:0;right:0;width:var(--bs-offcanvas-width);border-left:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(100%)}.offcanvas-sm.offcanvas-top{top:0;right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-bottom:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(-100%)}.offcanvas-sm.offcanvas-bottom{right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-top:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(100%)}.offcanvas-sm.showing,.offcanvas-sm.show:not(.hiding){transform:none}.offcanvas-sm.showing,.offcanvas-sm.hiding,.offcanvas-sm.show{visibility:visible}}@media(min-width: 576px){.offcanvas-sm{--bs-offcanvas-height: auto;--bs-offcanvas-border-width: 0;background-color:rgba(0,0,0,0) !important}.offcanvas-sm .offcanvas-header{display:none}.offcanvas-sm .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible;background-color:rgba(0,0,0,0) !important}}@media(max-width: 767.98px){.offcanvas-md{position:fixed;bottom:0;z-index:var(--bs-offcanvas-zindex);display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;max-width:100%;color:var(--bs-offcanvas-color);visibility:hidden;background-color:var(--bs-offcanvas-bg);background-clip:padding-box;outline:0;transition:var(--bs-offcanvas-transition)}}@media(max-width: 767.98px)and (prefers-reduced-motion: reduce){.offcanvas-md{transition:none}}@media(max-width: 767.98px){.offcanvas-md.offcanvas-start{top:0;left:0;width:var(--bs-offcanvas-width);border-right:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(-100%)}.offcanvas-md.offcanvas-end{top:0;right:0;width:var(--bs-offcanvas-width);border-left:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(100%)}.offcanvas-md.offcanvas-top{top:0;right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-bottom:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(-100%)}.offcanvas-md.offcanvas-bottom{right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-top:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(100%)}.offcanvas-md.showing,.offcanvas-md.show:not(.hiding){transform:none}.offcanvas-md.showing,.offcanvas-md.hiding,.offcanvas-md.show{visibility:visible}}@media(min-width: 768px){.offcanvas-md{--bs-offcanvas-height: auto;--bs-offcanvas-border-width: 0;background-color:rgba(0,0,0,0) !important}.offcanvas-md .offcanvas-header{display:none}.offcanvas-md .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible;background-color:rgba(0,0,0,0) !important}}@media(max-width: 991.98px){.offcanvas-lg{position:fixed;bottom:0;z-index:var(--bs-offcanvas-zindex);display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;max-width:100%;color:var(--bs-offcanvas-color);visibility:hidden;background-color:var(--bs-offcanvas-bg);background-clip:padding-box;outline:0;transition:var(--bs-offcanvas-transition)}}@media(max-width: 991.98px)and (prefers-reduced-motion: reduce){.offcanvas-lg{transition:none}}@media(max-width: 991.98px){.offcanvas-lg.offcanvas-start{top:0;left:0;width:var(--bs-offcanvas-width);border-right:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(-100%)}.offcanvas-lg.offcanvas-end{top:0;right:0;width:var(--bs-offcanvas-width);border-left:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(100%)}.offcanvas-lg.offcanvas-top{top:0;right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-bottom:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(-100%)}.offcanvas-lg.offcanvas-bottom{right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-top:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(100%)}.offcanvas-lg.showing,.offcanvas-lg.show:not(.hiding){transform:none}.offcanvas-lg.showing,.offcanvas-lg.hiding,.offcanvas-lg.show{visibility:visible}}@media(min-width: 992px){.offcanvas-lg{--bs-offcanvas-height: auto;--bs-offcanvas-border-width: 0;background-color:rgba(0,0,0,0) !important}.offcanvas-lg .offcanvas-header{display:none}.offcanvas-lg .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible;background-color:rgba(0,0,0,0) !important}}@media(max-width: 1199.98px){.offcanvas-xl{position:fixed;bottom:0;z-index:var(--bs-offcanvas-zindex);display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;max-width:100%;color:var(--bs-offcanvas-color);visibility:hidden;background-color:var(--bs-offcanvas-bg);background-clip:padding-box;outline:0;transition:var(--bs-offcanvas-transition)}}@media(max-width: 1199.98px)and (prefers-reduced-motion: reduce){.offcanvas-xl{transition:none}}@media(max-width: 1199.98px){.offcanvas-xl.offcanvas-start{top:0;left:0;width:var(--bs-offcanvas-width);border-right:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(-100%)}.offcanvas-xl.offcanvas-end{top:0;right:0;width:var(--bs-offcanvas-width);border-left:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(100%)}.offcanvas-xl.offcanvas-top{top:0;right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-bottom:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(-100%)}.offcanvas-xl.offcanvas-bottom{right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-top:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(100%)}.offcanvas-xl.showing,.offcanvas-xl.show:not(.hiding){transform:none}.offcanvas-xl.showing,.offcanvas-xl.hiding,.offcanvas-xl.show{visibility:visible}}@media(min-width: 1200px){.offcanvas-xl{--bs-offcanvas-height: auto;--bs-offcanvas-border-width: 0;background-color:rgba(0,0,0,0) !important}.offcanvas-xl .offcanvas-header{display:none}.offcanvas-xl .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible;background-color:rgba(0,0,0,0) !important}}@media(max-width: 1399.98px){.offcanvas-xxl{position:fixed;bottom:0;z-index:var(--bs-offcanvas-zindex);display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;max-width:100%;color:var(--bs-offcanvas-color);visibility:hidden;background-color:var(--bs-offcanvas-bg);background-clip:padding-box;outline:0;transition:var(--bs-offcanvas-transition)}}@media(max-width: 1399.98px)and (prefers-reduced-motion: reduce){.offcanvas-xxl{transition:none}}@media(max-width: 1399.98px){.offcanvas-xxl.offcanvas-start{top:0;left:0;width:var(--bs-offcanvas-width);border-right:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(-100%)}.offcanvas-xxl.offcanvas-end{top:0;right:0;width:var(--bs-offcanvas-width);border-left:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(100%)}.offcanvas-xxl.offcanvas-top{top:0;right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-bottom:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(-100%)}.offcanvas-xxl.offcanvas-bottom{right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-top:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(100%)}.offcanvas-xxl.showing,.offcanvas-xxl.show:not(.hiding){transform:none}.offcanvas-xxl.showing,.offcanvas-xxl.hiding,.offcanvas-xxl.show{visibility:visible}}@media(min-width: 1400px){.offcanvas-xxl{--bs-offcanvas-height: auto;--bs-offcanvas-border-width: 0;background-color:rgba(0,0,0,0) !important}.offcanvas-xxl .offcanvas-header{display:none}.offcanvas-xxl .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible;background-color:rgba(0,0,0,0) !important}}.offcanvas{position:fixed;bottom:0;z-index:var(--bs-offcanvas-zindex);display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;max-width:100%;color:var(--bs-offcanvas-color);visibility:hidden;background-color:var(--bs-offcanvas-bg);background-clip:padding-box;outline:0;transition:var(--bs-offcanvas-transition)}@media(prefers-reduced-motion: reduce){.offcanvas{transition:none}}.offcanvas.offcanvas-start{top:0;left:0;width:var(--bs-offcanvas-width);border-right:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(-100%)}.offcanvas.offcanvas-end{top:0;right:0;width:var(--bs-offcanvas-width);border-left:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(100%)}.offcanvas.offcanvas-top{top:0;right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-bottom:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(-100%)}.offcanvas.offcanvas-bottom{right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-top:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(100%)}.offcanvas.showing,.offcanvas.show:not(.hiding){transform:none}.offcanvas.showing,.offcanvas.hiding,.offcanvas.show{visibility:visible}.offcanvas-backdrop{position:fixed;top:0;left:0;z-index:1040;width:100vw;height:100vh;background-color:#000}.offcanvas-backdrop.fade{opacity:0}.offcanvas-backdrop.show{opacity:.5}.offcanvas-header{display:flex;display:-webkit-flex;align-items:center;-webkit-align-items:center;justify-content:space-between;-webkit-justify-content:space-between;padding:var(--bs-offcanvas-padding-y) var(--bs-offcanvas-padding-x)}.offcanvas-header .btn-close{padding:calc(var(--bs-offcanvas-padding-y)*.5) calc(var(--bs-offcanvas-padding-x)*.5);margin-top:calc(-0.5*var(--bs-offcanvas-padding-y));margin-right:calc(-0.5*var(--bs-offcanvas-padding-x));margin-bottom:calc(-0.5*var(--bs-offcanvas-padding-y))}.offcanvas-title{margin-bottom:0;line-height:var(--bs-offcanvas-title-line-height)}.offcanvas-body{flex-grow:1;-webkit-flex-grow:1;padding:var(--bs-offcanvas-padding-y) var(--bs-offcanvas-padding-x);overflow-y:auto}.placeholder{display:inline-block;min-height:1em;vertical-align:middle;cursor:wait;background-color:currentcolor;opacity:.5}.placeholder.btn::before{display:inline-block;content:""}.placeholder-xs{min-height:.6em}.placeholder-sm{min-height:.8em}.placeholder-lg{min-height:1.2em}.placeholder-glow .placeholder{animation:placeholder-glow 2s ease-in-out infinite}@keyframes placeholder-glow{50%{opacity:.2}}.placeholder-wave{mask-image:linear-gradient(130deg, #000 55%, rgba(0, 0, 0, 0.8) 75%, #000 95%);-webkit-mask-image:linear-gradient(130deg, #000 55%, rgba(0, 0, 0, 0.8) 75%, #000 95%);mask-size:200% 100%;-webkit-mask-size:200% 100%;animation:placeholder-wave 2s linear infinite}@keyframes placeholder-wave{100%{mask-position:-200% 0%;-webkit-mask-position:-200% 0%}}.clearfix::after{display:block;clear:both;content:""}.text-bg-default{color:#fff !important;background-color:RGBA(var(--bs-default-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-primary{color:#fff !important;background-color:RGBA(var(--bs-primary-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-secondary{color:#fff !important;background-color:RGBA(var(--bs-secondary-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-success{color:#fff !important;background-color:RGBA(var(--bs-success-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-info{color:#fff !important;background-color:RGBA(var(--bs-info-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-warning{color:#fff !important;background-color:RGBA(var(--bs-warning-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-danger{color:#fff !important;background-color:RGBA(var(--bs-danger-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-light{color:#fff !important;background-color:RGBA(var(--bs-light-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-dark{color:#fff !important;background-color:RGBA(var(--bs-dark-rgb), var(--bs-bg-opacity, 1)) !important}.link-default{color:RGBA(var(--bs-default-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-default-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-default:hover,.link-default:focus{color:RGBA(54, 54, 54, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(54, 54, 54, var(--bs-link-underline-opacity, 1)) !important}.link-primary{color:RGBA(var(--bs-primary-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-primary-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-primary:hover,.link-primary:focus{color:RGBA(44, 72, 102, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(44, 72, 102, var(--bs-link-underline-opacity, 1)) !important}.link-secondary{color:RGBA(var(--bs-secondary-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-secondary-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-secondary:hover,.link-secondary:focus{color:RGBA(54, 54, 54, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(54, 54, 54, var(--bs-link-underline-opacity, 1)) !important}.link-success{color:RGBA(var(--bs-success-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-success-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-success:hover,.link-success:focus{color:RGBA(0, 150, 112, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(0, 150, 112, var(--bs-link-underline-opacity, 1)) !important}.link-info{color:RGBA(var(--bs-info-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-info-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-info:hover,.link-info:focus{color:RGBA(42, 122, 175, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(42, 122, 175, var(--bs-link-underline-opacity, 1)) !important}.link-warning{color:RGBA(var(--bs-warning-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-warning-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-warning:hover,.link-warning:focus{color:RGBA(194, 125, 14, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(194, 125, 14, var(--bs-link-underline-opacity, 1)) !important}.link-danger{color:RGBA(var(--bs-danger-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-danger-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-danger:hover,.link-danger:focus{color:RGBA(185, 61, 48, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(185, 61, 48, var(--bs-link-underline-opacity, 1)) !important}.link-light{color:RGBA(var(--bs-light-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-light-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-light:hover,.link-light:focus{color:RGBA(89, 89, 89, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(89, 89, 89, var(--bs-link-underline-opacity, 1)) !important}.link-dark{color:RGBA(var(--bs-dark-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-dark-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-dark:hover,.link-dark:focus{color:RGBA(36, 36, 36, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(36, 36, 36, var(--bs-link-underline-opacity, 1)) !important}.link-body-emphasis{color:RGBA(var(--bs-emphasis-color-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-emphasis-color-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-body-emphasis:hover,.link-body-emphasis:focus{color:RGBA(var(--bs-emphasis-color-rgb), var(--bs-link-opacity, 0.75)) !important;text-decoration-color:RGBA(var(--bs-emphasis-color-rgb), var(--bs-link-underline-opacity, 0.75)) !important}.focus-ring:focus{outline:0;box-shadow:var(--bs-focus-ring-x, 0) var(--bs-focus-ring-y, 0) var(--bs-focus-ring-blur, 0) var(--bs-focus-ring-width) var(--bs-focus-ring-color)}.icon-link{display:inline-flex;gap:.375rem;align-items:center;-webkit-align-items:center;text-decoration-color:rgba(var(--bs-link-color-rgb), var(--bs-link-opacity, 0.5));text-underline-offset:.25em;backface-visibility:hidden;-webkit-backface-visibility:hidden;-moz-backface-visibility:hidden;-ms-backface-visibility:hidden;-o-backface-visibility:hidden}.icon-link>.bi{flex-shrink:0;-webkit-flex-shrink:0;width:1em;height:1em;fill:currentcolor;transition:.2s ease-in-out transform}@media(prefers-reduced-motion: reduce){.icon-link>.bi{transition:none}}.icon-link-hover:hover>.bi,.icon-link-hover:focus-visible>.bi{transform:var(--bs-icon-link-transform, translate3d(0.25em, 0, 0))}.ratio{position:relative;width:100%}.ratio::before{display:block;padding-top:var(--bs-aspect-ratio);content:""}.ratio>*{position:absolute;top:0;left:0;width:100%;height:100%}.ratio-1x1{--bs-aspect-ratio: 100%}.ratio-4x3{--bs-aspect-ratio: 75%}.ratio-16x9{--bs-aspect-ratio: 56.25%}.ratio-21x9{--bs-aspect-ratio: 42.8571428571%}.fixed-top{position:fixed;top:0;right:0;left:0;z-index:1030}.fixed-bottom{position:fixed;right:0;bottom:0;left:0;z-index:1030}.sticky-top{position:sticky;top:0;z-index:1020}.sticky-bottom{position:sticky;bottom:0;z-index:1020}@media(min-width: 576px){.sticky-sm-top{position:sticky;top:0;z-index:1020}.sticky-sm-bottom{position:sticky;bottom:0;z-index:1020}}@media(min-width: 768px){.sticky-md-top{position:sticky;top:0;z-index:1020}.sticky-md-bottom{position:sticky;bottom:0;z-index:1020}}@media(min-width: 992px){.sticky-lg-top{position:sticky;top:0;z-index:1020}.sticky-lg-bottom{position:sticky;bottom:0;z-index:1020}}@media(min-width: 1200px){.sticky-xl-top{position:sticky;top:0;z-index:1020}.sticky-xl-bottom{position:sticky;bottom:0;z-index:1020}}@media(min-width: 1400px){.sticky-xxl-top{position:sticky;top:0;z-index:1020}.sticky-xxl-bottom{position:sticky;bottom:0;z-index:1020}}.hstack{display:flex;display:-webkit-flex;flex-direction:row;-webkit-flex-direction:row;align-items:center;-webkit-align-items:center;align-self:stretch;-webkit-align-self:stretch}.vstack{display:flex;display:-webkit-flex;flex:1 1 auto;-webkit-flex:1 1 auto;flex-direction:column;-webkit-flex-direction:column;align-self:stretch;-webkit-align-self:stretch}.visually-hidden,.visually-hidden-focusable:not(:focus):not(:focus-within){width:1px !important;height:1px !important;padding:0 !important;margin:-1px !important;overflow:hidden !important;clip:rect(0, 0, 0, 0) !important;white-space:nowrap !important;border:0 !important}.visually-hidden:not(caption),.visually-hidden-focusable:not(:focus):not(:focus-within):not(caption){position:absolute !important}.stretched-link::after{position:absolute;top:0;right:0;bottom:0;left:0;z-index:1;content:""}.text-truncate{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.vr{display:inline-block;align-self:stretch;-webkit-align-self:stretch;width:1px;min-height:1em;background-color:currentcolor;opacity:.25}.align-baseline{vertical-align:baseline !important}.align-top{vertical-align:top !important}.align-middle{vertical-align:middle !important}.align-bottom{vertical-align:bottom !important}.align-text-bottom{vertical-align:text-bottom !important}.align-text-top{vertical-align:text-top !important}.float-start{float:left !important}.float-end{float:right !important}.float-none{float:none !important}.object-fit-contain{object-fit:contain !important}.object-fit-cover{object-fit:cover !important}.object-fit-fill{object-fit:fill !important}.object-fit-scale{object-fit:scale-down !important}.object-fit-none{object-fit:none !important}.opacity-0{opacity:0 !important}.opacity-25{opacity:.25 !important}.opacity-50{opacity:.5 !important}.opacity-75{opacity:.75 !important}.opacity-100{opacity:1 !important}.overflow-auto{overflow:auto !important}.overflow-hidden{overflow:hidden !important}.overflow-visible{overflow:visible !important}.overflow-scroll{overflow:scroll !important}.overflow-x-auto{overflow-x:auto !important}.overflow-x-hidden{overflow-x:hidden !important}.overflow-x-visible{overflow-x:visible !important}.overflow-x-scroll{overflow-x:scroll !important}.overflow-y-auto{overflow-y:auto !important}.overflow-y-hidden{overflow-y:hidden !important}.overflow-y-visible{overflow-y:visible !important}.overflow-y-scroll{overflow-y:scroll !important}.d-inline{display:inline !important}.d-inline-block{display:inline-block !important}.d-block{display:block !important}.d-grid{display:grid !important}.d-inline-grid{display:inline-grid !important}.d-table{display:table !important}.d-table-row{display:table-row !important}.d-table-cell{display:table-cell !important}.d-flex{display:flex !important}.d-inline-flex{display:inline-flex !important}.d-none{display:none !important}.shadow{box-shadow:0 .5rem 1rem rgba(0,0,0,.15) !important}.shadow-sm{box-shadow:0 .125rem .25rem rgba(0,0,0,.075) !important}.shadow-lg{box-shadow:0 1rem 3rem rgba(0,0,0,.175) !important}.shadow-none{box-shadow:none !important}.focus-ring-default{--bs-focus-ring-color: rgba(var(--bs-default-rgb), var(--bs-focus-ring-opacity))}.focus-ring-primary{--bs-focus-ring-color: rgba(var(--bs-primary-rgb), var(--bs-focus-ring-opacity))}.focus-ring-secondary{--bs-focus-ring-color: rgba(var(--bs-secondary-rgb), var(--bs-focus-ring-opacity))}.focus-ring-success{--bs-focus-ring-color: rgba(var(--bs-success-rgb), var(--bs-focus-ring-opacity))}.focus-ring-info{--bs-focus-ring-color: rgba(var(--bs-info-rgb), var(--bs-focus-ring-opacity))}.focus-ring-warning{--bs-focus-ring-color: rgba(var(--bs-warning-rgb), var(--bs-focus-ring-opacity))}.focus-ring-danger{--bs-focus-ring-color: rgba(var(--bs-danger-rgb), var(--bs-focus-ring-opacity))}.focus-ring-light{--bs-focus-ring-color: rgba(var(--bs-light-rgb), var(--bs-focus-ring-opacity))}.focus-ring-dark{--bs-focus-ring-color: rgba(var(--bs-dark-rgb), var(--bs-focus-ring-opacity))}.position-static{position:static !important}.position-relative{position:relative !important}.position-absolute{position:absolute !important}.position-fixed{position:fixed !important}.position-sticky{position:sticky !important}.top-0{top:0 !important}.top-50{top:50% !important}.top-100{top:100% !important}.bottom-0{bottom:0 !important}.bottom-50{bottom:50% !important}.bottom-100{bottom:100% !important}.start-0{left:0 !important}.start-50{left:50% !important}.start-100{left:100% !important}.end-0{right:0 !important}.end-50{right:50% !important}.end-100{right:100% !important}.translate-middle{transform:translate(-50%, -50%) !important}.translate-middle-x{transform:translateX(-50%) !important}.translate-middle-y{transform:translateY(-50%) !important}.border{border:var(--bs-border-width) var(--bs-border-style) var(--bs-border-color) !important}.border-0{border:0 !important}.border-top{border-top:var(--bs-border-width) var(--bs-border-style) var(--bs-border-color) !important}.border-top-0{border-top:0 !important}.border-end{border-right:var(--bs-border-width) var(--bs-border-style) var(--bs-border-color) !important}.border-end-0{border-right:0 !important}.border-bottom{border-bottom:var(--bs-border-width) var(--bs-border-style) var(--bs-border-color) !important}.border-bottom-0{border-bottom:0 !important}.border-start{border-left:var(--bs-border-width) var(--bs-border-style) var(--bs-border-color) !important}.border-start-0{border-left:0 !important}.border-default{--bs-border-opacity: 1;border-color:rgba(var(--bs-default-rgb), var(--bs-border-opacity)) !important}.border-primary{--bs-border-opacity: 1;border-color:rgba(var(--bs-primary-rgb), var(--bs-border-opacity)) !important}.border-secondary{--bs-border-opacity: 1;border-color:rgba(var(--bs-secondary-rgb), var(--bs-border-opacity)) !important}.border-success{--bs-border-opacity: 1;border-color:rgba(var(--bs-success-rgb), var(--bs-border-opacity)) !important}.border-info{--bs-border-opacity: 1;border-color:rgba(var(--bs-info-rgb), var(--bs-border-opacity)) !important}.border-warning{--bs-border-opacity: 1;border-color:rgba(var(--bs-warning-rgb), var(--bs-border-opacity)) !important}.border-danger{--bs-border-opacity: 1;border-color:rgba(var(--bs-danger-rgb), var(--bs-border-opacity)) !important}.border-light{--bs-border-opacity: 1;border-color:rgba(var(--bs-light-rgb), var(--bs-border-opacity)) !important}.border-dark{--bs-border-opacity: 1;border-color:rgba(var(--bs-dark-rgb), var(--bs-border-opacity)) !important}.border-black{--bs-border-opacity: 1;border-color:rgba(var(--bs-black-rgb), var(--bs-border-opacity)) !important}.border-white{--bs-border-opacity: 1;border-color:rgba(var(--bs-white-rgb), var(--bs-border-opacity)) !important}.border-primary-subtle{border-color:var(--bs-primary-border-subtle) !important}.border-secondary-subtle{border-color:var(--bs-secondary-border-subtle) !important}.border-success-subtle{border-color:var(--bs-success-border-subtle) !important}.border-info-subtle{border-color:var(--bs-info-border-subtle) !important}.border-warning-subtle{border-color:var(--bs-warning-border-subtle) !important}.border-danger-subtle{border-color:var(--bs-danger-border-subtle) !important}.border-light-subtle{border-color:var(--bs-light-border-subtle) !important}.border-dark-subtle{border-color:var(--bs-dark-border-subtle) !important}.border-1{border-width:1px !important}.border-2{border-width:2px !important}.border-3{border-width:3px !important}.border-4{border-width:4px !important}.border-5{border-width:5px !important}.border-opacity-10{--bs-border-opacity: 0.1}.border-opacity-25{--bs-border-opacity: 0.25}.border-opacity-50{--bs-border-opacity: 0.5}.border-opacity-75{--bs-border-opacity: 0.75}.border-opacity-100{--bs-border-opacity: 1}.w-25{width:25% !important}.w-50{width:50% !important}.w-75{width:75% !important}.w-100{width:100% !important}.w-auto{width:auto !important}.mw-100{max-width:100% !important}.vw-100{width:100vw !important}.min-vw-100{min-width:100vw !important}.h-25{height:25% !important}.h-50{height:50% !important}.h-75{height:75% !important}.h-100{height:100% !important}.h-auto{height:auto !important}.mh-100{max-height:100% !important}.vh-100{height:100vh !important}.min-vh-100{min-height:100vh !important}.flex-fill{flex:1 1 auto !important}.flex-row{flex-direction:row !important}.flex-column{flex-direction:column !important}.flex-row-reverse{flex-direction:row-reverse !important}.flex-column-reverse{flex-direction:column-reverse !important}.flex-grow-0{flex-grow:0 !important}.flex-grow-1{flex-grow:1 !important}.flex-shrink-0{flex-shrink:0 !important}.flex-shrink-1{flex-shrink:1 !important}.flex-wrap{flex-wrap:wrap !important}.flex-nowrap{flex-wrap:nowrap !important}.flex-wrap-reverse{flex-wrap:wrap-reverse !important}.justify-content-start{justify-content:flex-start !important}.justify-content-end{justify-content:flex-end !important}.justify-content-center{justify-content:center !important}.justify-content-between{justify-content:space-between !important}.justify-content-around{justify-content:space-around !important}.justify-content-evenly{justify-content:space-evenly !important}.align-items-start{align-items:flex-start !important}.align-items-end{align-items:flex-end !important}.align-items-center{align-items:center !important}.align-items-baseline{align-items:baseline !important}.align-items-stretch{align-items:stretch !important}.align-content-start{align-content:flex-start !important}.align-content-end{align-content:flex-end !important}.align-content-center{align-content:center !important}.align-content-between{align-content:space-between !important}.align-content-around{align-content:space-around !important}.align-content-stretch{align-content:stretch !important}.align-self-auto{align-self:auto !important}.align-self-start{align-self:flex-start !important}.align-self-end{align-self:flex-end !important}.align-self-center{align-self:center !important}.align-self-baseline{align-self:baseline !important}.align-self-stretch{align-self:stretch !important}.order-first{order:-1 !important}.order-0{order:0 !important}.order-1{order:1 !important}.order-2{order:2 !important}.order-3{order:3 !important}.order-4{order:4 !important}.order-5{order:5 !important}.order-last{order:6 !important}.m-0{margin:0 !important}.m-1{margin:.25rem !important}.m-2{margin:.5rem !important}.m-3{margin:1rem !important}.m-4{margin:1.5rem !important}.m-5{margin:3rem !important}.m-auto{margin:auto !important}.mx-0{margin-right:0 !important;margin-left:0 !important}.mx-1{margin-right:.25rem !important;margin-left:.25rem !important}.mx-2{margin-right:.5rem !important;margin-left:.5rem !important}.mx-3{margin-right:1rem !important;margin-left:1rem !important}.mx-4{margin-right:1.5rem !important;margin-left:1.5rem !important}.mx-5{margin-right:3rem !important;margin-left:3rem !important}.mx-auto{margin-right:auto !important;margin-left:auto !important}.my-0{margin-top:0 !important;margin-bottom:0 !important}.my-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.my-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.my-3{margin-top:1rem !important;margin-bottom:1rem !important}.my-4{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.my-5{margin-top:3rem !important;margin-bottom:3rem !important}.my-auto{margin-top:auto !important;margin-bottom:auto !important}.mt-0{margin-top:0 !important}.mt-1{margin-top:.25rem !important}.mt-2{margin-top:.5rem !important}.mt-3{margin-top:1rem !important}.mt-4{margin-top:1.5rem !important}.mt-5{margin-top:3rem !important}.mt-auto{margin-top:auto !important}.me-0{margin-right:0 !important}.me-1{margin-right:.25rem !important}.me-2{margin-right:.5rem !important}.me-3{margin-right:1rem !important}.me-4{margin-right:1.5rem !important}.me-5{margin-right:3rem !important}.me-auto{margin-right:auto !important}.mb-0{margin-bottom:0 !important}.mb-1{margin-bottom:.25rem !important}.mb-2{margin-bottom:.5rem !important}.mb-3{margin-bottom:1rem !important}.mb-4{margin-bottom:1.5rem !important}.mb-5{margin-bottom:3rem !important}.mb-auto{margin-bottom:auto !important}.ms-0{margin-left:0 !important}.ms-1{margin-left:.25rem !important}.ms-2{margin-left:.5rem !important}.ms-3{margin-left:1rem !important}.ms-4{margin-left:1.5rem !important}.ms-5{margin-left:3rem !important}.ms-auto{margin-left:auto !important}.p-0{padding:0 !important}.p-1{padding:.25rem !important}.p-2{padding:.5rem !important}.p-3{padding:1rem !important}.p-4{padding:1.5rem !important}.p-5{padding:3rem !important}.px-0{padding-right:0 !important;padding-left:0 !important}.px-1{padding-right:.25rem !important;padding-left:.25rem !important}.px-2{padding-right:.5rem !important;padding-left:.5rem !important}.px-3{padding-right:1rem !important;padding-left:1rem !important}.px-4{padding-right:1.5rem !important;padding-left:1.5rem !important}.px-5{padding-right:3rem !important;padding-left:3rem !important}.py-0{padding-top:0 !important;padding-bottom:0 !important}.py-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.py-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.py-3{padding-top:1rem !important;padding-bottom:1rem !important}.py-4{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.py-5{padding-top:3rem !important;padding-bottom:3rem !important}.pt-0{padding-top:0 !important}.pt-1{padding-top:.25rem !important}.pt-2{padding-top:.5rem !important}.pt-3{padding-top:1rem !important}.pt-4{padding-top:1.5rem !important}.pt-5{padding-top:3rem !important}.pe-0{padding-right:0 !important}.pe-1{padding-right:.25rem !important}.pe-2{padding-right:.5rem !important}.pe-3{padding-right:1rem !important}.pe-4{padding-right:1.5rem !important}.pe-5{padding-right:3rem !important}.pb-0{padding-bottom:0 !important}.pb-1{padding-bottom:.25rem !important}.pb-2{padding-bottom:.5rem !important}.pb-3{padding-bottom:1rem !important}.pb-4{padding-bottom:1.5rem !important}.pb-5{padding-bottom:3rem !important}.ps-0{padding-left:0 !important}.ps-1{padding-left:.25rem !important}.ps-2{padding-left:.5rem !important}.ps-3{padding-left:1rem !important}.ps-4{padding-left:1.5rem !important}.ps-5{padding-left:3rem !important}.gap-0{gap:0 !important}.gap-1{gap:.25rem !important}.gap-2{gap:.5rem !important}.gap-3{gap:1rem !important}.gap-4{gap:1.5rem !important}.gap-5{gap:3rem !important}.row-gap-0{row-gap:0 !important}.row-gap-1{row-gap:.25rem !important}.row-gap-2{row-gap:.5rem !important}.row-gap-3{row-gap:1rem !important}.row-gap-4{row-gap:1.5rem !important}.row-gap-5{row-gap:3rem !important}.column-gap-0{column-gap:0 !important}.column-gap-1{column-gap:.25rem !important}.column-gap-2{column-gap:.5rem !important}.column-gap-3{column-gap:1rem !important}.column-gap-4{column-gap:1.5rem !important}.column-gap-5{column-gap:3rem !important}.font-monospace{font-family:var(--bs-font-monospace) !important}.fs-1{font-size:calc(1.325rem + 0.9vw) !important}.fs-2{font-size:calc(1.29rem + 0.48vw) !important}.fs-3{font-size:calc(1.27rem + 0.24vw) !important}.fs-4{font-size:1.25rem !important}.fs-5{font-size:1.1rem !important}.fs-6{font-size:1rem !important}.fst-italic{font-style:italic !important}.fst-normal{font-style:normal !important}.fw-lighter{font-weight:lighter !important}.fw-light{font-weight:300 !important}.fw-normal{font-weight:400 !important}.fw-medium{font-weight:500 !important}.fw-semibold{font-weight:600 !important}.fw-bold{font-weight:700 !important}.fw-bolder{font-weight:bolder !important}.lh-1{line-height:1 !important}.lh-sm{line-height:1.25 !important}.lh-base{line-height:1.5 !important}.lh-lg{line-height:2 !important}.text-start{text-align:left !important}.text-end{text-align:right !important}.text-center{text-align:center !important}.text-decoration-none{text-decoration:none !important}.text-decoration-underline{text-decoration:underline !important}.text-decoration-line-through{text-decoration:line-through !important}.text-lowercase{text-transform:lowercase !important}.text-uppercase{text-transform:uppercase !important}.text-capitalize{text-transform:capitalize !important}.text-wrap{white-space:normal !important}.text-nowrap{white-space:nowrap !important}.text-break{word-wrap:break-word !important;word-break:break-word !important}.text-default{--bs-text-opacity: 1;color:rgba(var(--bs-default-rgb), var(--bs-text-opacity)) !important}.text-primary{--bs-text-opacity: 1;color:rgba(var(--bs-primary-rgb), var(--bs-text-opacity)) !important}.text-secondary{--bs-text-opacity: 1;color:rgba(var(--bs-secondary-rgb), var(--bs-text-opacity)) !important}.text-success{--bs-text-opacity: 1;color:rgba(var(--bs-success-rgb), var(--bs-text-opacity)) !important}.text-info{--bs-text-opacity: 1;color:rgba(var(--bs-info-rgb), var(--bs-text-opacity)) !important}.text-warning{--bs-text-opacity: 1;color:rgba(var(--bs-warning-rgb), var(--bs-text-opacity)) !important}.text-danger{--bs-text-opacity: 1;color:rgba(var(--bs-danger-rgb), var(--bs-text-opacity)) !important}.text-light{--bs-text-opacity: 1;color:rgba(var(--bs-light-rgb), var(--bs-text-opacity)) !important}.text-dark{--bs-text-opacity: 1;color:rgba(var(--bs-dark-rgb), var(--bs-text-opacity)) !important}.text-black{--bs-text-opacity: 1;color:rgba(var(--bs-black-rgb), var(--bs-text-opacity)) !important}.text-white{--bs-text-opacity: 1;color:rgba(var(--bs-white-rgb), var(--bs-text-opacity)) !important}.text-body{--bs-text-opacity: 1;color:rgba(var(--bs-body-color-rgb), var(--bs-text-opacity)) !important}.text-muted{--bs-text-opacity: 1;color:var(--bs-secondary-color) !important}.text-black-50{--bs-text-opacity: 1;color:rgba(0,0,0,.5) !important}.text-white-50{--bs-text-opacity: 1;color:rgba(255,255,255,.5) !important}.text-body-secondary{--bs-text-opacity: 1;color:var(--bs-secondary-color) !important}.text-body-tertiary{--bs-text-opacity: 1;color:var(--bs-tertiary-color) !important}.text-body-emphasis{--bs-text-opacity: 1;color:var(--bs-emphasis-color) !important}.text-reset{--bs-text-opacity: 1;color:inherit !important}.text-opacity-25{--bs-text-opacity: 0.25}.text-opacity-50{--bs-text-opacity: 0.5}.text-opacity-75{--bs-text-opacity: 0.75}.text-opacity-100{--bs-text-opacity: 1}.text-primary-emphasis{color:var(--bs-primary-text-emphasis) !important}.text-secondary-emphasis{color:var(--bs-secondary-text-emphasis) !important}.text-success-emphasis{color:var(--bs-success-text-emphasis) !important}.text-info-emphasis{color:var(--bs-info-text-emphasis) !important}.text-warning-emphasis{color:var(--bs-warning-text-emphasis) !important}.text-danger-emphasis{color:var(--bs-danger-text-emphasis) !important}.text-light-emphasis{color:var(--bs-light-text-emphasis) !important}.text-dark-emphasis{color:var(--bs-dark-text-emphasis) !important}.link-opacity-10{--bs-link-opacity: 0.1}.link-opacity-10-hover:hover{--bs-link-opacity: 0.1}.link-opacity-25{--bs-link-opacity: 0.25}.link-opacity-25-hover:hover{--bs-link-opacity: 0.25}.link-opacity-50{--bs-link-opacity: 0.5}.link-opacity-50-hover:hover{--bs-link-opacity: 0.5}.link-opacity-75{--bs-link-opacity: 0.75}.link-opacity-75-hover:hover{--bs-link-opacity: 0.75}.link-opacity-100{--bs-link-opacity: 1}.link-opacity-100-hover:hover{--bs-link-opacity: 1}.link-offset-1{text-underline-offset:.125em !important}.link-offset-1-hover:hover{text-underline-offset:.125em !important}.link-offset-2{text-underline-offset:.25em !important}.link-offset-2-hover:hover{text-underline-offset:.25em !important}.link-offset-3{text-underline-offset:.375em !important}.link-offset-3-hover:hover{text-underline-offset:.375em !important}.link-underline-default{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-default-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-primary{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-primary-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-secondary{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-secondary-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-success{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-success-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-info{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-info-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-warning{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-warning-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-danger{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-danger-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-light{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-light-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-dark{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-dark-rgb), var(--bs-link-underline-opacity)) !important}.link-underline{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-link-color-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-underline-opacity-0{--bs-link-underline-opacity: 0}.link-underline-opacity-0-hover:hover{--bs-link-underline-opacity: 0}.link-underline-opacity-10{--bs-link-underline-opacity: 0.1}.link-underline-opacity-10-hover:hover{--bs-link-underline-opacity: 0.1}.link-underline-opacity-25{--bs-link-underline-opacity: 0.25}.link-underline-opacity-25-hover:hover{--bs-link-underline-opacity: 0.25}.link-underline-opacity-50{--bs-link-underline-opacity: 0.5}.link-underline-opacity-50-hover:hover{--bs-link-underline-opacity: 0.5}.link-underline-opacity-75{--bs-link-underline-opacity: 0.75}.link-underline-opacity-75-hover:hover{--bs-link-underline-opacity: 0.75}.link-underline-opacity-100{--bs-link-underline-opacity: 1}.link-underline-opacity-100-hover:hover{--bs-link-underline-opacity: 1}.bg-default{--bs-bg-opacity: 1;background-color:rgba(var(--bs-default-rgb), var(--bs-bg-opacity)) !important}.bg-primary{--bs-bg-opacity: 1;background-color:rgba(var(--bs-primary-rgb), var(--bs-bg-opacity)) !important}.bg-secondary{--bs-bg-opacity: 1;background-color:rgba(var(--bs-secondary-rgb), var(--bs-bg-opacity)) !important}.bg-success{--bs-bg-opacity: 1;background-color:rgba(var(--bs-success-rgb), var(--bs-bg-opacity)) !important}.bg-info{--bs-bg-opacity: 1;background-color:rgba(var(--bs-info-rgb), var(--bs-bg-opacity)) !important}.bg-warning{--bs-bg-opacity: 1;background-color:rgba(var(--bs-warning-rgb), var(--bs-bg-opacity)) !important}.bg-danger{--bs-bg-opacity: 1;background-color:rgba(var(--bs-danger-rgb), var(--bs-bg-opacity)) !important}.bg-light{--bs-bg-opacity: 1;background-color:rgba(var(--bs-light-rgb), var(--bs-bg-opacity)) !important}.bg-dark{--bs-bg-opacity: 1;background-color:rgba(var(--bs-dark-rgb), var(--bs-bg-opacity)) !important}.bg-black{--bs-bg-opacity: 1;background-color:rgba(var(--bs-black-rgb), var(--bs-bg-opacity)) !important}.bg-white{--bs-bg-opacity: 1;background-color:rgba(var(--bs-white-rgb), var(--bs-bg-opacity)) !important}.bg-body{--bs-bg-opacity: 1;background-color:rgba(var(--bs-body-bg-rgb), var(--bs-bg-opacity)) !important}.bg-transparent{--bs-bg-opacity: 1;background-color:rgba(0,0,0,0) !important}.bg-body-secondary{--bs-bg-opacity: 1;background-color:rgba(var(--bs-secondary-bg-rgb), var(--bs-bg-opacity)) !important}.bg-body-tertiary{--bs-bg-opacity: 1;background-color:rgba(var(--bs-tertiary-bg-rgb), var(--bs-bg-opacity)) !important}.bg-opacity-10{--bs-bg-opacity: 0.1}.bg-opacity-25{--bs-bg-opacity: 0.25}.bg-opacity-50{--bs-bg-opacity: 0.5}.bg-opacity-75{--bs-bg-opacity: 0.75}.bg-opacity-100{--bs-bg-opacity: 1}.bg-primary-subtle{background-color:var(--bs-primary-bg-subtle) !important}.bg-secondary-subtle{background-color:var(--bs-secondary-bg-subtle) !important}.bg-success-subtle{background-color:var(--bs-success-bg-subtle) !important}.bg-info-subtle{background-color:var(--bs-info-bg-subtle) !important}.bg-warning-subtle{background-color:var(--bs-warning-bg-subtle) !important}.bg-danger-subtle{background-color:var(--bs-danger-bg-subtle) !important}.bg-light-subtle{background-color:var(--bs-light-bg-subtle) !important}.bg-dark-subtle{background-color:var(--bs-dark-bg-subtle) !important}.bg-gradient{background-image:var(--bs-gradient) !important}.user-select-all{user-select:all !important}.user-select-auto{user-select:auto !important}.user-select-none{user-select:none !important}.pe-none{pointer-events:none !important}.pe-auto{pointer-events:auto !important}.rounded{border-radius:var(--bs-border-radius) !important}.rounded-0{border-radius:0 !important}.rounded-1{border-radius:var(--bs-border-radius-sm) !important}.rounded-2{border-radius:var(--bs-border-radius) !important}.rounded-3{border-radius:var(--bs-border-radius-lg) !important}.rounded-4{border-radius:var(--bs-border-radius-xl) !important}.rounded-5{border-radius:var(--bs-border-radius-xxl) !important}.rounded-circle{border-radius:50% !important}.rounded-pill{border-radius:var(--bs-border-radius-pill) !important}.rounded-top{border-top-left-radius:var(--bs-border-radius) !important;border-top-right-radius:var(--bs-border-radius) !important}.rounded-top-0{border-top-left-radius:0 !important;border-top-right-radius:0 !important}.rounded-top-1{border-top-left-radius:var(--bs-border-radius-sm) !important;border-top-right-radius:var(--bs-border-radius-sm) !important}.rounded-top-2{border-top-left-radius:var(--bs-border-radius) !important;border-top-right-radius:var(--bs-border-radius) !important}.rounded-top-3{border-top-left-radius:var(--bs-border-radius-lg) !important;border-top-right-radius:var(--bs-border-radius-lg) !important}.rounded-top-4{border-top-left-radius:var(--bs-border-radius-xl) !important;border-top-right-radius:var(--bs-border-radius-xl) !important}.rounded-top-5{border-top-left-radius:var(--bs-border-radius-xxl) !important;border-top-right-radius:var(--bs-border-radius-xxl) !important}.rounded-top-circle{border-top-left-radius:50% !important;border-top-right-radius:50% !important}.rounded-top-pill{border-top-left-radius:var(--bs-border-radius-pill) !important;border-top-right-radius:var(--bs-border-radius-pill) !important}.rounded-end{border-top-right-radius:var(--bs-border-radius) !important;border-bottom-right-radius:var(--bs-border-radius) !important}.rounded-end-0{border-top-right-radius:0 !important;border-bottom-right-radius:0 !important}.rounded-end-1{border-top-right-radius:var(--bs-border-radius-sm) !important;border-bottom-right-radius:var(--bs-border-radius-sm) !important}.rounded-end-2{border-top-right-radius:var(--bs-border-radius) !important;border-bottom-right-radius:var(--bs-border-radius) !important}.rounded-end-3{border-top-right-radius:var(--bs-border-radius-lg) !important;border-bottom-right-radius:var(--bs-border-radius-lg) !important}.rounded-end-4{border-top-right-radius:var(--bs-border-radius-xl) !important;border-bottom-right-radius:var(--bs-border-radius-xl) !important}.rounded-end-5{border-top-right-radius:var(--bs-border-radius-xxl) !important;border-bottom-right-radius:var(--bs-border-radius-xxl) !important}.rounded-end-circle{border-top-right-radius:50% !important;border-bottom-right-radius:50% !important}.rounded-end-pill{border-top-right-radius:var(--bs-border-radius-pill) !important;border-bottom-right-radius:var(--bs-border-radius-pill) !important}.rounded-bottom{border-bottom-right-radius:var(--bs-border-radius) !important;border-bottom-left-radius:var(--bs-border-radius) !important}.rounded-bottom-0{border-bottom-right-radius:0 !important;border-bottom-left-radius:0 !important}.rounded-bottom-1{border-bottom-right-radius:var(--bs-border-radius-sm) !important;border-bottom-left-radius:var(--bs-border-radius-sm) !important}.rounded-bottom-2{border-bottom-right-radius:var(--bs-border-radius) !important;border-bottom-left-radius:var(--bs-border-radius) !important}.rounded-bottom-3{border-bottom-right-radius:var(--bs-border-radius-lg) !important;border-bottom-left-radius:var(--bs-border-radius-lg) !important}.rounded-bottom-4{border-bottom-right-radius:var(--bs-border-radius-xl) !important;border-bottom-left-radius:var(--bs-border-radius-xl) !important}.rounded-bottom-5{border-bottom-right-radius:var(--bs-border-radius-xxl) !important;border-bottom-left-radius:var(--bs-border-radius-xxl) !important}.rounded-bottom-circle{border-bottom-right-radius:50% !important;border-bottom-left-radius:50% !important}.rounded-bottom-pill{border-bottom-right-radius:var(--bs-border-radius-pill) !important;border-bottom-left-radius:var(--bs-border-radius-pill) !important}.rounded-start{border-bottom-left-radius:var(--bs-border-radius) !important;border-top-left-radius:var(--bs-border-radius) !important}.rounded-start-0{border-bottom-left-radius:0 !important;border-top-left-radius:0 !important}.rounded-start-1{border-bottom-left-radius:var(--bs-border-radius-sm) !important;border-top-left-radius:var(--bs-border-radius-sm) !important}.rounded-start-2{border-bottom-left-radius:var(--bs-border-radius) !important;border-top-left-radius:var(--bs-border-radius) !important}.rounded-start-3{border-bottom-left-radius:var(--bs-border-radius-lg) !important;border-top-left-radius:var(--bs-border-radius-lg) !important}.rounded-start-4{border-bottom-left-radius:var(--bs-border-radius-xl) !important;border-top-left-radius:var(--bs-border-radius-xl) !important}.rounded-start-5{border-bottom-left-radius:var(--bs-border-radius-xxl) !important;border-top-left-radius:var(--bs-border-radius-xxl) !important}.rounded-start-circle{border-bottom-left-radius:50% !important;border-top-left-radius:50% !important}.rounded-start-pill{border-bottom-left-radius:var(--bs-border-radius-pill) !important;border-top-left-radius:var(--bs-border-radius-pill) !important}.visible{visibility:visible !important}.invisible{visibility:hidden !important}.z-n1{z-index:-1 !important}.z-0{z-index:0 !important}.z-1{z-index:1 !important}.z-2{z-index:2 !important}.z-3{z-index:3 !important}@media(min-width: 576px){.float-sm-start{float:left !important}.float-sm-end{float:right !important}.float-sm-none{float:none !important}.object-fit-sm-contain{object-fit:contain !important}.object-fit-sm-cover{object-fit:cover !important}.object-fit-sm-fill{object-fit:fill !important}.object-fit-sm-scale{object-fit:scale-down !important}.object-fit-sm-none{object-fit:none !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-block{display:block !important}.d-sm-grid{display:grid !important}.d-sm-inline-grid{display:inline-grid !important}.d-sm-table{display:table !important}.d-sm-table-row{display:table-row !important}.d-sm-table-cell{display:table-cell !important}.d-sm-flex{display:flex !important}.d-sm-inline-flex{display:inline-flex !important}.d-sm-none{display:none !important}.flex-sm-fill{flex:1 1 auto !important}.flex-sm-row{flex-direction:row !important}.flex-sm-column{flex-direction:column !important}.flex-sm-row-reverse{flex-direction:row-reverse !important}.flex-sm-column-reverse{flex-direction:column-reverse !important}.flex-sm-grow-0{flex-grow:0 !important}.flex-sm-grow-1{flex-grow:1 !important}.flex-sm-shrink-0{flex-shrink:0 !important}.flex-sm-shrink-1{flex-shrink:1 !important}.flex-sm-wrap{flex-wrap:wrap !important}.flex-sm-nowrap{flex-wrap:nowrap !important}.flex-sm-wrap-reverse{flex-wrap:wrap-reverse !important}.justify-content-sm-start{justify-content:flex-start !important}.justify-content-sm-end{justify-content:flex-end !important}.justify-content-sm-center{justify-content:center !important}.justify-content-sm-between{justify-content:space-between !important}.justify-content-sm-around{justify-content:space-around !important}.justify-content-sm-evenly{justify-content:space-evenly !important}.align-items-sm-start{align-items:flex-start !important}.align-items-sm-end{align-items:flex-end !important}.align-items-sm-center{align-items:center !important}.align-items-sm-baseline{align-items:baseline !important}.align-items-sm-stretch{align-items:stretch !important}.align-content-sm-start{align-content:flex-start !important}.align-content-sm-end{align-content:flex-end !important}.align-content-sm-center{align-content:center !important}.align-content-sm-between{align-content:space-between !important}.align-content-sm-around{align-content:space-around !important}.align-content-sm-stretch{align-content:stretch !important}.align-self-sm-auto{align-self:auto !important}.align-self-sm-start{align-self:flex-start !important}.align-self-sm-end{align-self:flex-end !important}.align-self-sm-center{align-self:center !important}.align-self-sm-baseline{align-self:baseline !important}.align-self-sm-stretch{align-self:stretch !important}.order-sm-first{order:-1 !important}.order-sm-0{order:0 !important}.order-sm-1{order:1 !important}.order-sm-2{order:2 !important}.order-sm-3{order:3 !important}.order-sm-4{order:4 !important}.order-sm-5{order:5 !important}.order-sm-last{order:6 !important}.m-sm-0{margin:0 !important}.m-sm-1{margin:.25rem !important}.m-sm-2{margin:.5rem !important}.m-sm-3{margin:1rem !important}.m-sm-4{margin:1.5rem !important}.m-sm-5{margin:3rem !important}.m-sm-auto{margin:auto !important}.mx-sm-0{margin-right:0 !important;margin-left:0 !important}.mx-sm-1{margin-right:.25rem !important;margin-left:.25rem !important}.mx-sm-2{margin-right:.5rem !important;margin-left:.5rem !important}.mx-sm-3{margin-right:1rem !important;margin-left:1rem !important}.mx-sm-4{margin-right:1.5rem !important;margin-left:1.5rem !important}.mx-sm-5{margin-right:3rem !important;margin-left:3rem !important}.mx-sm-auto{margin-right:auto !important;margin-left:auto !important}.my-sm-0{margin-top:0 !important;margin-bottom:0 !important}.my-sm-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.my-sm-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.my-sm-3{margin-top:1rem !important;margin-bottom:1rem !important}.my-sm-4{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.my-sm-5{margin-top:3rem !important;margin-bottom:3rem !important}.my-sm-auto{margin-top:auto !important;margin-bottom:auto !important}.mt-sm-0{margin-top:0 !important}.mt-sm-1{margin-top:.25rem !important}.mt-sm-2{margin-top:.5rem !important}.mt-sm-3{margin-top:1rem !important}.mt-sm-4{margin-top:1.5rem !important}.mt-sm-5{margin-top:3rem !important}.mt-sm-auto{margin-top:auto !important}.me-sm-0{margin-right:0 !important}.me-sm-1{margin-right:.25rem !important}.me-sm-2{margin-right:.5rem !important}.me-sm-3{margin-right:1rem !important}.me-sm-4{margin-right:1.5rem !important}.me-sm-5{margin-right:3rem !important}.me-sm-auto{margin-right:auto !important}.mb-sm-0{margin-bottom:0 !important}.mb-sm-1{margin-bottom:.25rem !important}.mb-sm-2{margin-bottom:.5rem !important}.mb-sm-3{margin-bottom:1rem !important}.mb-sm-4{margin-bottom:1.5rem !important}.mb-sm-5{margin-bottom:3rem !important}.mb-sm-auto{margin-bottom:auto !important}.ms-sm-0{margin-left:0 !important}.ms-sm-1{margin-left:.25rem !important}.ms-sm-2{margin-left:.5rem !important}.ms-sm-3{margin-left:1rem !important}.ms-sm-4{margin-left:1.5rem !important}.ms-sm-5{margin-left:3rem !important}.ms-sm-auto{margin-left:auto !important}.p-sm-0{padding:0 !important}.p-sm-1{padding:.25rem !important}.p-sm-2{padding:.5rem !important}.p-sm-3{padding:1rem !important}.p-sm-4{padding:1.5rem !important}.p-sm-5{padding:3rem !important}.px-sm-0{padding-right:0 !important;padding-left:0 !important}.px-sm-1{padding-right:.25rem !important;padding-left:.25rem !important}.px-sm-2{padding-right:.5rem !important;padding-left:.5rem !important}.px-sm-3{padding-right:1rem !important;padding-left:1rem !important}.px-sm-4{padding-right:1.5rem !important;padding-left:1.5rem !important}.px-sm-5{padding-right:3rem !important;padding-left:3rem !important}.py-sm-0{padding-top:0 !important;padding-bottom:0 !important}.py-sm-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.py-sm-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.py-sm-3{padding-top:1rem !important;padding-bottom:1rem !important}.py-sm-4{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.py-sm-5{padding-top:3rem !important;padding-bottom:3rem !important}.pt-sm-0{padding-top:0 !important}.pt-sm-1{padding-top:.25rem !important}.pt-sm-2{padding-top:.5rem !important}.pt-sm-3{padding-top:1rem !important}.pt-sm-4{padding-top:1.5rem !important}.pt-sm-5{padding-top:3rem !important}.pe-sm-0{padding-right:0 !important}.pe-sm-1{padding-right:.25rem !important}.pe-sm-2{padding-right:.5rem !important}.pe-sm-3{padding-right:1rem !important}.pe-sm-4{padding-right:1.5rem !important}.pe-sm-5{padding-right:3rem !important}.pb-sm-0{padding-bottom:0 !important}.pb-sm-1{padding-bottom:.25rem !important}.pb-sm-2{padding-bottom:.5rem !important}.pb-sm-3{padding-bottom:1rem !important}.pb-sm-4{padding-bottom:1.5rem !important}.pb-sm-5{padding-bottom:3rem !important}.ps-sm-0{padding-left:0 !important}.ps-sm-1{padding-left:.25rem !important}.ps-sm-2{padding-left:.5rem !important}.ps-sm-3{padding-left:1rem !important}.ps-sm-4{padding-left:1.5rem !important}.ps-sm-5{padding-left:3rem !important}.gap-sm-0{gap:0 !important}.gap-sm-1{gap:.25rem !important}.gap-sm-2{gap:.5rem !important}.gap-sm-3{gap:1rem !important}.gap-sm-4{gap:1.5rem !important}.gap-sm-5{gap:3rem !important}.row-gap-sm-0{row-gap:0 !important}.row-gap-sm-1{row-gap:.25rem !important}.row-gap-sm-2{row-gap:.5rem !important}.row-gap-sm-3{row-gap:1rem !important}.row-gap-sm-4{row-gap:1.5rem !important}.row-gap-sm-5{row-gap:3rem !important}.column-gap-sm-0{column-gap:0 !important}.column-gap-sm-1{column-gap:.25rem !important}.column-gap-sm-2{column-gap:.5rem !important}.column-gap-sm-3{column-gap:1rem !important}.column-gap-sm-4{column-gap:1.5rem !important}.column-gap-sm-5{column-gap:3rem !important}.text-sm-start{text-align:left !important}.text-sm-end{text-align:right !important}.text-sm-center{text-align:center !important}}@media(min-width: 768px){.float-md-start{float:left !important}.float-md-end{float:right !important}.float-md-none{float:none !important}.object-fit-md-contain{object-fit:contain !important}.object-fit-md-cover{object-fit:cover !important}.object-fit-md-fill{object-fit:fill !important}.object-fit-md-scale{object-fit:scale-down !important}.object-fit-md-none{object-fit:none !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-block{display:block !important}.d-md-grid{display:grid !important}.d-md-inline-grid{display:inline-grid !important}.d-md-table{display:table !important}.d-md-table-row{display:table-row !important}.d-md-table-cell{display:table-cell !important}.d-md-flex{display:flex !important}.d-md-inline-flex{display:inline-flex !important}.d-md-none{display:none !important}.flex-md-fill{flex:1 1 auto !important}.flex-md-row{flex-direction:row !important}.flex-md-column{flex-direction:column !important}.flex-md-row-reverse{flex-direction:row-reverse !important}.flex-md-column-reverse{flex-direction:column-reverse !important}.flex-md-grow-0{flex-grow:0 !important}.flex-md-grow-1{flex-grow:1 !important}.flex-md-shrink-0{flex-shrink:0 !important}.flex-md-shrink-1{flex-shrink:1 !important}.flex-md-wrap{flex-wrap:wrap !important}.flex-md-nowrap{flex-wrap:nowrap !important}.flex-md-wrap-reverse{flex-wrap:wrap-reverse !important}.justify-content-md-start{justify-content:flex-start !important}.justify-content-md-end{justify-content:flex-end !important}.justify-content-md-center{justify-content:center !important}.justify-content-md-between{justify-content:space-between !important}.justify-content-md-around{justify-content:space-around !important}.justify-content-md-evenly{justify-content:space-evenly !important}.align-items-md-start{align-items:flex-start !important}.align-items-md-end{align-items:flex-end !important}.align-items-md-center{align-items:center !important}.align-items-md-baseline{align-items:baseline !important}.align-items-md-stretch{align-items:stretch !important}.align-content-md-start{align-content:flex-start !important}.align-content-md-end{align-content:flex-end !important}.align-content-md-center{align-content:center !important}.align-content-md-between{align-content:space-between !important}.align-content-md-around{align-content:space-around !important}.align-content-md-stretch{align-content:stretch !important}.align-self-md-auto{align-self:auto !important}.align-self-md-start{align-self:flex-start !important}.align-self-md-end{align-self:flex-end !important}.align-self-md-center{align-self:center !important}.align-self-md-baseline{align-self:baseline !important}.align-self-md-stretch{align-self:stretch !important}.order-md-first{order:-1 !important}.order-md-0{order:0 !important}.order-md-1{order:1 !important}.order-md-2{order:2 !important}.order-md-3{order:3 !important}.order-md-4{order:4 !important}.order-md-5{order:5 !important}.order-md-last{order:6 !important}.m-md-0{margin:0 !important}.m-md-1{margin:.25rem !important}.m-md-2{margin:.5rem !important}.m-md-3{margin:1rem !important}.m-md-4{margin:1.5rem !important}.m-md-5{margin:3rem !important}.m-md-auto{margin:auto !important}.mx-md-0{margin-right:0 !important;margin-left:0 !important}.mx-md-1{margin-right:.25rem !important;margin-left:.25rem !important}.mx-md-2{margin-right:.5rem !important;margin-left:.5rem !important}.mx-md-3{margin-right:1rem !important;margin-left:1rem !important}.mx-md-4{margin-right:1.5rem !important;margin-left:1.5rem !important}.mx-md-5{margin-right:3rem !important;margin-left:3rem !important}.mx-md-auto{margin-right:auto !important;margin-left:auto !important}.my-md-0{margin-top:0 !important;margin-bottom:0 !important}.my-md-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.my-md-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.my-md-3{margin-top:1rem !important;margin-bottom:1rem !important}.my-md-4{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.my-md-5{margin-top:3rem !important;margin-bottom:3rem !important}.my-md-auto{margin-top:auto !important;margin-bottom:auto !important}.mt-md-0{margin-top:0 !important}.mt-md-1{margin-top:.25rem !important}.mt-md-2{margin-top:.5rem !important}.mt-md-3{margin-top:1rem !important}.mt-md-4{margin-top:1.5rem !important}.mt-md-5{margin-top:3rem !important}.mt-md-auto{margin-top:auto !important}.me-md-0{margin-right:0 !important}.me-md-1{margin-right:.25rem !important}.me-md-2{margin-right:.5rem !important}.me-md-3{margin-right:1rem !important}.me-md-4{margin-right:1.5rem !important}.me-md-5{margin-right:3rem !important}.me-md-auto{margin-right:auto !important}.mb-md-0{margin-bottom:0 !important}.mb-md-1{margin-bottom:.25rem !important}.mb-md-2{margin-bottom:.5rem !important}.mb-md-3{margin-bottom:1rem !important}.mb-md-4{margin-bottom:1.5rem !important}.mb-md-5{margin-bottom:3rem !important}.mb-md-auto{margin-bottom:auto !important}.ms-md-0{margin-left:0 !important}.ms-md-1{margin-left:.25rem !important}.ms-md-2{margin-left:.5rem !important}.ms-md-3{margin-left:1rem !important}.ms-md-4{margin-left:1.5rem !important}.ms-md-5{margin-left:3rem !important}.ms-md-auto{margin-left:auto !important}.p-md-0{padding:0 !important}.p-md-1{padding:.25rem !important}.p-md-2{padding:.5rem !important}.p-md-3{padding:1rem !important}.p-md-4{padding:1.5rem !important}.p-md-5{padding:3rem !important}.px-md-0{padding-right:0 !important;padding-left:0 !important}.px-md-1{padding-right:.25rem !important;padding-left:.25rem !important}.px-md-2{padding-right:.5rem !important;padding-left:.5rem !important}.px-md-3{padding-right:1rem !important;padding-left:1rem !important}.px-md-4{padding-right:1.5rem !important;padding-left:1.5rem !important}.px-md-5{padding-right:3rem !important;padding-left:3rem !important}.py-md-0{padding-top:0 !important;padding-bottom:0 !important}.py-md-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.py-md-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.py-md-3{padding-top:1rem !important;padding-bottom:1rem !important}.py-md-4{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.py-md-5{padding-top:3rem !important;padding-bottom:3rem !important}.pt-md-0{padding-top:0 !important}.pt-md-1{padding-top:.25rem !important}.pt-md-2{padding-top:.5rem !important}.pt-md-3{padding-top:1rem !important}.pt-md-4{padding-top:1.5rem !important}.pt-md-5{padding-top:3rem !important}.pe-md-0{padding-right:0 !important}.pe-md-1{padding-right:.25rem !important}.pe-md-2{padding-right:.5rem !important}.pe-md-3{padding-right:1rem !important}.pe-md-4{padding-right:1.5rem !important}.pe-md-5{padding-right:3rem !important}.pb-md-0{padding-bottom:0 !important}.pb-md-1{padding-bottom:.25rem !important}.pb-md-2{padding-bottom:.5rem !important}.pb-md-3{padding-bottom:1rem !important}.pb-md-4{padding-bottom:1.5rem !important}.pb-md-5{padding-bottom:3rem !important}.ps-md-0{padding-left:0 !important}.ps-md-1{padding-left:.25rem !important}.ps-md-2{padding-left:.5rem !important}.ps-md-3{padding-left:1rem !important}.ps-md-4{padding-left:1.5rem !important}.ps-md-5{padding-left:3rem !important}.gap-md-0{gap:0 !important}.gap-md-1{gap:.25rem !important}.gap-md-2{gap:.5rem !important}.gap-md-3{gap:1rem !important}.gap-md-4{gap:1.5rem !important}.gap-md-5{gap:3rem !important}.row-gap-md-0{row-gap:0 !important}.row-gap-md-1{row-gap:.25rem !important}.row-gap-md-2{row-gap:.5rem !important}.row-gap-md-3{row-gap:1rem !important}.row-gap-md-4{row-gap:1.5rem !important}.row-gap-md-5{row-gap:3rem !important}.column-gap-md-0{column-gap:0 !important}.column-gap-md-1{column-gap:.25rem !important}.column-gap-md-2{column-gap:.5rem !important}.column-gap-md-3{column-gap:1rem !important}.column-gap-md-4{column-gap:1.5rem !important}.column-gap-md-5{column-gap:3rem !important}.text-md-start{text-align:left !important}.text-md-end{text-align:right !important}.text-md-center{text-align:center !important}}@media(min-width: 992px){.float-lg-start{float:left !important}.float-lg-end{float:right !important}.float-lg-none{float:none !important}.object-fit-lg-contain{object-fit:contain !important}.object-fit-lg-cover{object-fit:cover !important}.object-fit-lg-fill{object-fit:fill !important}.object-fit-lg-scale{object-fit:scale-down !important}.object-fit-lg-none{object-fit:none !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-block{display:block !important}.d-lg-grid{display:grid !important}.d-lg-inline-grid{display:inline-grid !important}.d-lg-table{display:table !important}.d-lg-table-row{display:table-row !important}.d-lg-table-cell{display:table-cell !important}.d-lg-flex{display:flex !important}.d-lg-inline-flex{display:inline-flex !important}.d-lg-none{display:none !important}.flex-lg-fill{flex:1 1 auto !important}.flex-lg-row{flex-direction:row !important}.flex-lg-column{flex-direction:column !important}.flex-lg-row-reverse{flex-direction:row-reverse !important}.flex-lg-column-reverse{flex-direction:column-reverse !important}.flex-lg-grow-0{flex-grow:0 !important}.flex-lg-grow-1{flex-grow:1 !important}.flex-lg-shrink-0{flex-shrink:0 !important}.flex-lg-shrink-1{flex-shrink:1 !important}.flex-lg-wrap{flex-wrap:wrap !important}.flex-lg-nowrap{flex-wrap:nowrap !important}.flex-lg-wrap-reverse{flex-wrap:wrap-reverse !important}.justify-content-lg-start{justify-content:flex-start !important}.justify-content-lg-end{justify-content:flex-end !important}.justify-content-lg-center{justify-content:center !important}.justify-content-lg-between{justify-content:space-between !important}.justify-content-lg-around{justify-content:space-around !important}.justify-content-lg-evenly{justify-content:space-evenly !important}.align-items-lg-start{align-items:flex-start !important}.align-items-lg-end{align-items:flex-end !important}.align-items-lg-center{align-items:center !important}.align-items-lg-baseline{align-items:baseline !important}.align-items-lg-stretch{align-items:stretch !important}.align-content-lg-start{align-content:flex-start !important}.align-content-lg-end{align-content:flex-end !important}.align-content-lg-center{align-content:center !important}.align-content-lg-between{align-content:space-between !important}.align-content-lg-around{align-content:space-around !important}.align-content-lg-stretch{align-content:stretch !important}.align-self-lg-auto{align-self:auto !important}.align-self-lg-start{align-self:flex-start !important}.align-self-lg-end{align-self:flex-end !important}.align-self-lg-center{align-self:center !important}.align-self-lg-baseline{align-self:baseline !important}.align-self-lg-stretch{align-self:stretch !important}.order-lg-first{order:-1 !important}.order-lg-0{order:0 !important}.order-lg-1{order:1 !important}.order-lg-2{order:2 !important}.order-lg-3{order:3 !important}.order-lg-4{order:4 !important}.order-lg-5{order:5 !important}.order-lg-last{order:6 !important}.m-lg-0{margin:0 !important}.m-lg-1{margin:.25rem !important}.m-lg-2{margin:.5rem !important}.m-lg-3{margin:1rem !important}.m-lg-4{margin:1.5rem !important}.m-lg-5{margin:3rem !important}.m-lg-auto{margin:auto !important}.mx-lg-0{margin-right:0 !important;margin-left:0 !important}.mx-lg-1{margin-right:.25rem !important;margin-left:.25rem !important}.mx-lg-2{margin-right:.5rem !important;margin-left:.5rem !important}.mx-lg-3{margin-right:1rem !important;margin-left:1rem !important}.mx-lg-4{margin-right:1.5rem !important;margin-left:1.5rem !important}.mx-lg-5{margin-right:3rem !important;margin-left:3rem !important}.mx-lg-auto{margin-right:auto !important;margin-left:auto !important}.my-lg-0{margin-top:0 !important;margin-bottom:0 !important}.my-lg-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.my-lg-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.my-lg-3{margin-top:1rem !important;margin-bottom:1rem !important}.my-lg-4{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.my-lg-5{margin-top:3rem !important;margin-bottom:3rem !important}.my-lg-auto{margin-top:auto !important;margin-bottom:auto !important}.mt-lg-0{margin-top:0 !important}.mt-lg-1{margin-top:.25rem !important}.mt-lg-2{margin-top:.5rem !important}.mt-lg-3{margin-top:1rem !important}.mt-lg-4{margin-top:1.5rem !important}.mt-lg-5{margin-top:3rem !important}.mt-lg-auto{margin-top:auto !important}.me-lg-0{margin-right:0 !important}.me-lg-1{margin-right:.25rem !important}.me-lg-2{margin-right:.5rem !important}.me-lg-3{margin-right:1rem !important}.me-lg-4{margin-right:1.5rem !important}.me-lg-5{margin-right:3rem !important}.me-lg-auto{margin-right:auto !important}.mb-lg-0{margin-bottom:0 !important}.mb-lg-1{margin-bottom:.25rem !important}.mb-lg-2{margin-bottom:.5rem !important}.mb-lg-3{margin-bottom:1rem !important}.mb-lg-4{margin-bottom:1.5rem !important}.mb-lg-5{margin-bottom:3rem !important}.mb-lg-auto{margin-bottom:auto !important}.ms-lg-0{margin-left:0 !important}.ms-lg-1{margin-left:.25rem !important}.ms-lg-2{margin-left:.5rem !important}.ms-lg-3{margin-left:1rem !important}.ms-lg-4{margin-left:1.5rem !important}.ms-lg-5{margin-left:3rem !important}.ms-lg-auto{margin-left:auto !important}.p-lg-0{padding:0 !important}.p-lg-1{padding:.25rem !important}.p-lg-2{padding:.5rem !important}.p-lg-3{padding:1rem !important}.p-lg-4{padding:1.5rem !important}.p-lg-5{padding:3rem !important}.px-lg-0{padding-right:0 !important;padding-left:0 !important}.px-lg-1{padding-right:.25rem !important;padding-left:.25rem !important}.px-lg-2{padding-right:.5rem !important;padding-left:.5rem !important}.px-lg-3{padding-right:1rem !important;padding-left:1rem !important}.px-lg-4{padding-right:1.5rem !important;padding-left:1.5rem !important}.px-lg-5{padding-right:3rem !important;padding-left:3rem !important}.py-lg-0{padding-top:0 !important;padding-bottom:0 !important}.py-lg-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.py-lg-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.py-lg-3{padding-top:1rem !important;padding-bottom:1rem !important}.py-lg-4{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.py-lg-5{padding-top:3rem !important;padding-bottom:3rem !important}.pt-lg-0{padding-top:0 !important}.pt-lg-1{padding-top:.25rem !important}.pt-lg-2{padding-top:.5rem !important}.pt-lg-3{padding-top:1rem !important}.pt-lg-4{padding-top:1.5rem !important}.pt-lg-5{padding-top:3rem !important}.pe-lg-0{padding-right:0 !important}.pe-lg-1{padding-right:.25rem !important}.pe-lg-2{padding-right:.5rem !important}.pe-lg-3{padding-right:1rem !important}.pe-lg-4{padding-right:1.5rem !important}.pe-lg-5{padding-right:3rem !important}.pb-lg-0{padding-bottom:0 !important}.pb-lg-1{padding-bottom:.25rem !important}.pb-lg-2{padding-bottom:.5rem !important}.pb-lg-3{padding-bottom:1rem !important}.pb-lg-4{padding-bottom:1.5rem !important}.pb-lg-5{padding-bottom:3rem !important}.ps-lg-0{padding-left:0 !important}.ps-lg-1{padding-left:.25rem !important}.ps-lg-2{padding-left:.5rem !important}.ps-lg-3{padding-left:1rem !important}.ps-lg-4{padding-left:1.5rem !important}.ps-lg-5{padding-left:3rem !important}.gap-lg-0{gap:0 !important}.gap-lg-1{gap:.25rem !important}.gap-lg-2{gap:.5rem !important}.gap-lg-3{gap:1rem !important}.gap-lg-4{gap:1.5rem !important}.gap-lg-5{gap:3rem !important}.row-gap-lg-0{row-gap:0 !important}.row-gap-lg-1{row-gap:.25rem !important}.row-gap-lg-2{row-gap:.5rem !important}.row-gap-lg-3{row-gap:1rem !important}.row-gap-lg-4{row-gap:1.5rem !important}.row-gap-lg-5{row-gap:3rem !important}.column-gap-lg-0{column-gap:0 !important}.column-gap-lg-1{column-gap:.25rem !important}.column-gap-lg-2{column-gap:.5rem !important}.column-gap-lg-3{column-gap:1rem !important}.column-gap-lg-4{column-gap:1.5rem !important}.column-gap-lg-5{column-gap:3rem !important}.text-lg-start{text-align:left !important}.text-lg-end{text-align:right !important}.text-lg-center{text-align:center !important}}@media(min-width: 1200px){.float-xl-start{float:left !important}.float-xl-end{float:right !important}.float-xl-none{float:none !important}.object-fit-xl-contain{object-fit:contain !important}.object-fit-xl-cover{object-fit:cover !important}.object-fit-xl-fill{object-fit:fill !important}.object-fit-xl-scale{object-fit:scale-down !important}.object-fit-xl-none{object-fit:none !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-block{display:block !important}.d-xl-grid{display:grid !important}.d-xl-inline-grid{display:inline-grid !important}.d-xl-table{display:table !important}.d-xl-table-row{display:table-row !important}.d-xl-table-cell{display:table-cell !important}.d-xl-flex{display:flex !important}.d-xl-inline-flex{display:inline-flex !important}.d-xl-none{display:none !important}.flex-xl-fill{flex:1 1 auto !important}.flex-xl-row{flex-direction:row !important}.flex-xl-column{flex-direction:column !important}.flex-xl-row-reverse{flex-direction:row-reverse !important}.flex-xl-column-reverse{flex-direction:column-reverse !important}.flex-xl-grow-0{flex-grow:0 !important}.flex-xl-grow-1{flex-grow:1 !important}.flex-xl-shrink-0{flex-shrink:0 !important}.flex-xl-shrink-1{flex-shrink:1 !important}.flex-xl-wrap{flex-wrap:wrap !important}.flex-xl-nowrap{flex-wrap:nowrap !important}.flex-xl-wrap-reverse{flex-wrap:wrap-reverse !important}.justify-content-xl-start{justify-content:flex-start !important}.justify-content-xl-end{justify-content:flex-end !important}.justify-content-xl-center{justify-content:center !important}.justify-content-xl-between{justify-content:space-between !important}.justify-content-xl-around{justify-content:space-around !important}.justify-content-xl-evenly{justify-content:space-evenly !important}.align-items-xl-start{align-items:flex-start !important}.align-items-xl-end{align-items:flex-end !important}.align-items-xl-center{align-items:center !important}.align-items-xl-baseline{align-items:baseline !important}.align-items-xl-stretch{align-items:stretch !important}.align-content-xl-start{align-content:flex-start !important}.align-content-xl-end{align-content:flex-end !important}.align-content-xl-center{align-content:center !important}.align-content-xl-between{align-content:space-between !important}.align-content-xl-around{align-content:space-around !important}.align-content-xl-stretch{align-content:stretch !important}.align-self-xl-auto{align-self:auto !important}.align-self-xl-start{align-self:flex-start !important}.align-self-xl-end{align-self:flex-end !important}.align-self-xl-center{align-self:center !important}.align-self-xl-baseline{align-self:baseline !important}.align-self-xl-stretch{align-self:stretch !important}.order-xl-first{order:-1 !important}.order-xl-0{order:0 !important}.order-xl-1{order:1 !important}.order-xl-2{order:2 !important}.order-xl-3{order:3 !important}.order-xl-4{order:4 !important}.order-xl-5{order:5 !important}.order-xl-last{order:6 !important}.m-xl-0{margin:0 !important}.m-xl-1{margin:.25rem !important}.m-xl-2{margin:.5rem !important}.m-xl-3{margin:1rem !important}.m-xl-4{margin:1.5rem !important}.m-xl-5{margin:3rem !important}.m-xl-auto{margin:auto !important}.mx-xl-0{margin-right:0 !important;margin-left:0 !important}.mx-xl-1{margin-right:.25rem !important;margin-left:.25rem !important}.mx-xl-2{margin-right:.5rem !important;margin-left:.5rem !important}.mx-xl-3{margin-right:1rem !important;margin-left:1rem !important}.mx-xl-4{margin-right:1.5rem !important;margin-left:1.5rem !important}.mx-xl-5{margin-right:3rem !important;margin-left:3rem !important}.mx-xl-auto{margin-right:auto !important;margin-left:auto !important}.my-xl-0{margin-top:0 !important;margin-bottom:0 !important}.my-xl-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.my-xl-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.my-xl-3{margin-top:1rem !important;margin-bottom:1rem !important}.my-xl-4{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.my-xl-5{margin-top:3rem !important;margin-bottom:3rem !important}.my-xl-auto{margin-top:auto !important;margin-bottom:auto !important}.mt-xl-0{margin-top:0 !important}.mt-xl-1{margin-top:.25rem !important}.mt-xl-2{margin-top:.5rem !important}.mt-xl-3{margin-top:1rem !important}.mt-xl-4{margin-top:1.5rem !important}.mt-xl-5{margin-top:3rem !important}.mt-xl-auto{margin-top:auto !important}.me-xl-0{margin-right:0 !important}.me-xl-1{margin-right:.25rem !important}.me-xl-2{margin-right:.5rem !important}.me-xl-3{margin-right:1rem !important}.me-xl-4{margin-right:1.5rem !important}.me-xl-5{margin-right:3rem !important}.me-xl-auto{margin-right:auto !important}.mb-xl-0{margin-bottom:0 !important}.mb-xl-1{margin-bottom:.25rem !important}.mb-xl-2{margin-bottom:.5rem !important}.mb-xl-3{margin-bottom:1rem !important}.mb-xl-4{margin-bottom:1.5rem !important}.mb-xl-5{margin-bottom:3rem !important}.mb-xl-auto{margin-bottom:auto !important}.ms-xl-0{margin-left:0 !important}.ms-xl-1{margin-left:.25rem !important}.ms-xl-2{margin-left:.5rem !important}.ms-xl-3{margin-left:1rem !important}.ms-xl-4{margin-left:1.5rem !important}.ms-xl-5{margin-left:3rem !important}.ms-xl-auto{margin-left:auto !important}.p-xl-0{padding:0 !important}.p-xl-1{padding:.25rem !important}.p-xl-2{padding:.5rem !important}.p-xl-3{padding:1rem !important}.p-xl-4{padding:1.5rem !important}.p-xl-5{padding:3rem !important}.px-xl-0{padding-right:0 !important;padding-left:0 !important}.px-xl-1{padding-right:.25rem !important;padding-left:.25rem !important}.px-xl-2{padding-right:.5rem !important;padding-left:.5rem !important}.px-xl-3{padding-right:1rem !important;padding-left:1rem !important}.px-xl-4{padding-right:1.5rem !important;padding-left:1.5rem !important}.px-xl-5{padding-right:3rem !important;padding-left:3rem !important}.py-xl-0{padding-top:0 !important;padding-bottom:0 !important}.py-xl-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.py-xl-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.py-xl-3{padding-top:1rem !important;padding-bottom:1rem !important}.py-xl-4{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.py-xl-5{padding-top:3rem !important;padding-bottom:3rem !important}.pt-xl-0{padding-top:0 !important}.pt-xl-1{padding-top:.25rem !important}.pt-xl-2{padding-top:.5rem !important}.pt-xl-3{padding-top:1rem !important}.pt-xl-4{padding-top:1.5rem !important}.pt-xl-5{padding-top:3rem !important}.pe-xl-0{padding-right:0 !important}.pe-xl-1{padding-right:.25rem !important}.pe-xl-2{padding-right:.5rem !important}.pe-xl-3{padding-right:1rem !important}.pe-xl-4{padding-right:1.5rem !important}.pe-xl-5{padding-right:3rem !important}.pb-xl-0{padding-bottom:0 !important}.pb-xl-1{padding-bottom:.25rem !important}.pb-xl-2{padding-bottom:.5rem !important}.pb-xl-3{padding-bottom:1rem !important}.pb-xl-4{padding-bottom:1.5rem !important}.pb-xl-5{padding-bottom:3rem !important}.ps-xl-0{padding-left:0 !important}.ps-xl-1{padding-left:.25rem !important}.ps-xl-2{padding-left:.5rem !important}.ps-xl-3{padding-left:1rem !important}.ps-xl-4{padding-left:1.5rem !important}.ps-xl-5{padding-left:3rem !important}.gap-xl-0{gap:0 !important}.gap-xl-1{gap:.25rem !important}.gap-xl-2{gap:.5rem !important}.gap-xl-3{gap:1rem !important}.gap-xl-4{gap:1.5rem !important}.gap-xl-5{gap:3rem !important}.row-gap-xl-0{row-gap:0 !important}.row-gap-xl-1{row-gap:.25rem !important}.row-gap-xl-2{row-gap:.5rem !important}.row-gap-xl-3{row-gap:1rem !important}.row-gap-xl-4{row-gap:1.5rem !important}.row-gap-xl-5{row-gap:3rem !important}.column-gap-xl-0{column-gap:0 !important}.column-gap-xl-1{column-gap:.25rem !important}.column-gap-xl-2{column-gap:.5rem !important}.column-gap-xl-3{column-gap:1rem !important}.column-gap-xl-4{column-gap:1.5rem !important}.column-gap-xl-5{column-gap:3rem !important}.text-xl-start{text-align:left !important}.text-xl-end{text-align:right !important}.text-xl-center{text-align:center !important}}@media(min-width: 1400px){.float-xxl-start{float:left !important}.float-xxl-end{float:right !important}.float-xxl-none{float:none !important}.object-fit-xxl-contain{object-fit:contain !important}.object-fit-xxl-cover{object-fit:cover !important}.object-fit-xxl-fill{object-fit:fill !important}.object-fit-xxl-scale{object-fit:scale-down !important}.object-fit-xxl-none{object-fit:none !important}.d-xxl-inline{display:inline !important}.d-xxl-inline-block{display:inline-block !important}.d-xxl-block{display:block !important}.d-xxl-grid{display:grid !important}.d-xxl-inline-grid{display:inline-grid !important}.d-xxl-table{display:table !important}.d-xxl-table-row{display:table-row !important}.d-xxl-table-cell{display:table-cell !important}.d-xxl-flex{display:flex !important}.d-xxl-inline-flex{display:inline-flex !important}.d-xxl-none{display:none !important}.flex-xxl-fill{flex:1 1 auto !important}.flex-xxl-row{flex-direction:row !important}.flex-xxl-column{flex-direction:column !important}.flex-xxl-row-reverse{flex-direction:row-reverse !important}.flex-xxl-column-reverse{flex-direction:column-reverse !important}.flex-xxl-grow-0{flex-grow:0 !important}.flex-xxl-grow-1{flex-grow:1 !important}.flex-xxl-shrink-0{flex-shrink:0 !important}.flex-xxl-shrink-1{flex-shrink:1 !important}.flex-xxl-wrap{flex-wrap:wrap !important}.flex-xxl-nowrap{flex-wrap:nowrap !important}.flex-xxl-wrap-reverse{flex-wrap:wrap-reverse !important}.justify-content-xxl-start{justify-content:flex-start !important}.justify-content-xxl-end{justify-content:flex-end !important}.justify-content-xxl-center{justify-content:center !important}.justify-content-xxl-between{justify-content:space-between !important}.justify-content-xxl-around{justify-content:space-around !important}.justify-content-xxl-evenly{justify-content:space-evenly !important}.align-items-xxl-start{align-items:flex-start !important}.align-items-xxl-end{align-items:flex-end !important}.align-items-xxl-center{align-items:center !important}.align-items-xxl-baseline{align-items:baseline !important}.align-items-xxl-stretch{align-items:stretch !important}.align-content-xxl-start{align-content:flex-start !important}.align-content-xxl-end{align-content:flex-end !important}.align-content-xxl-center{align-content:center !important}.align-content-xxl-between{align-content:space-between !important}.align-content-xxl-around{align-content:space-around !important}.align-content-xxl-stretch{align-content:stretch !important}.align-self-xxl-auto{align-self:auto !important}.align-self-xxl-start{align-self:flex-start !important}.align-self-xxl-end{align-self:flex-end !important}.align-self-xxl-center{align-self:center !important}.align-self-xxl-baseline{align-self:baseline !important}.align-self-xxl-stretch{align-self:stretch !important}.order-xxl-first{order:-1 !important}.order-xxl-0{order:0 !important}.order-xxl-1{order:1 !important}.order-xxl-2{order:2 !important}.order-xxl-3{order:3 !important}.order-xxl-4{order:4 !important}.order-xxl-5{order:5 !important}.order-xxl-last{order:6 !important}.m-xxl-0{margin:0 !important}.m-xxl-1{margin:.25rem !important}.m-xxl-2{margin:.5rem !important}.m-xxl-3{margin:1rem !important}.m-xxl-4{margin:1.5rem !important}.m-xxl-5{margin:3rem !important}.m-xxl-auto{margin:auto !important}.mx-xxl-0{margin-right:0 !important;margin-left:0 !important}.mx-xxl-1{margin-right:.25rem !important;margin-left:.25rem !important}.mx-xxl-2{margin-right:.5rem !important;margin-left:.5rem !important}.mx-xxl-3{margin-right:1rem !important;margin-left:1rem !important}.mx-xxl-4{margin-right:1.5rem !important;margin-left:1.5rem !important}.mx-xxl-5{margin-right:3rem !important;margin-left:3rem !important}.mx-xxl-auto{margin-right:auto !important;margin-left:auto !important}.my-xxl-0{margin-top:0 !important;margin-bottom:0 !important}.my-xxl-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.my-xxl-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.my-xxl-3{margin-top:1rem !important;margin-bottom:1rem !important}.my-xxl-4{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.my-xxl-5{margin-top:3rem !important;margin-bottom:3rem !important}.my-xxl-auto{margin-top:auto !important;margin-bottom:auto !important}.mt-xxl-0{margin-top:0 !important}.mt-xxl-1{margin-top:.25rem !important}.mt-xxl-2{margin-top:.5rem !important}.mt-xxl-3{margin-top:1rem !important}.mt-xxl-4{margin-top:1.5rem !important}.mt-xxl-5{margin-top:3rem !important}.mt-xxl-auto{margin-top:auto !important}.me-xxl-0{margin-right:0 !important}.me-xxl-1{margin-right:.25rem !important}.me-xxl-2{margin-right:.5rem !important}.me-xxl-3{margin-right:1rem !important}.me-xxl-4{margin-right:1.5rem !important}.me-xxl-5{margin-right:3rem !important}.me-xxl-auto{margin-right:auto !important}.mb-xxl-0{margin-bottom:0 !important}.mb-xxl-1{margin-bottom:.25rem !important}.mb-xxl-2{margin-bottom:.5rem !important}.mb-xxl-3{margin-bottom:1rem !important}.mb-xxl-4{margin-bottom:1.5rem !important}.mb-xxl-5{margin-bottom:3rem !important}.mb-xxl-auto{margin-bottom:auto !important}.ms-xxl-0{margin-left:0 !important}.ms-xxl-1{margin-left:.25rem !important}.ms-xxl-2{margin-left:.5rem !important}.ms-xxl-3{margin-left:1rem !important}.ms-xxl-4{margin-left:1.5rem !important}.ms-xxl-5{margin-left:3rem !important}.ms-xxl-auto{margin-left:auto !important}.p-xxl-0{padding:0 !important}.p-xxl-1{padding:.25rem !important}.p-xxl-2{padding:.5rem !important}.p-xxl-3{padding:1rem !important}.p-xxl-4{padding:1.5rem !important}.p-xxl-5{padding:3rem !important}.px-xxl-0{padding-right:0 !important;padding-left:0 !important}.px-xxl-1{padding-right:.25rem !important;padding-left:.25rem !important}.px-xxl-2{padding-right:.5rem !important;padding-left:.5rem !important}.px-xxl-3{padding-right:1rem !important;padding-left:1rem !important}.px-xxl-4{padding-right:1.5rem !important;padding-left:1.5rem !important}.px-xxl-5{padding-right:3rem !important;padding-left:3rem !important}.py-xxl-0{padding-top:0 !important;padding-bottom:0 !important}.py-xxl-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.py-xxl-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.py-xxl-3{padding-top:1rem !important;padding-bottom:1rem !important}.py-xxl-4{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.py-xxl-5{padding-top:3rem !important;padding-bottom:3rem !important}.pt-xxl-0{padding-top:0 !important}.pt-xxl-1{padding-top:.25rem !important}.pt-xxl-2{padding-top:.5rem !important}.pt-xxl-3{padding-top:1rem !important}.pt-xxl-4{padding-top:1.5rem !important}.pt-xxl-5{padding-top:3rem !important}.pe-xxl-0{padding-right:0 !important}.pe-xxl-1{padding-right:.25rem !important}.pe-xxl-2{padding-right:.5rem !important}.pe-xxl-3{padding-right:1rem !important}.pe-xxl-4{padding-right:1.5rem !important}.pe-xxl-5{padding-right:3rem !important}.pb-xxl-0{padding-bottom:0 !important}.pb-xxl-1{padding-bottom:.25rem !important}.pb-xxl-2{padding-bottom:.5rem !important}.pb-xxl-3{padding-bottom:1rem !important}.pb-xxl-4{padding-bottom:1.5rem !important}.pb-xxl-5{padding-bottom:3rem !important}.ps-xxl-0{padding-left:0 !important}.ps-xxl-1{padding-left:.25rem !important}.ps-xxl-2{padding-left:.5rem !important}.ps-xxl-3{padding-left:1rem !important}.ps-xxl-4{padding-left:1.5rem !important}.ps-xxl-5{padding-left:3rem !important}.gap-xxl-0{gap:0 !important}.gap-xxl-1{gap:.25rem !important}.gap-xxl-2{gap:.5rem !important}.gap-xxl-3{gap:1rem !important}.gap-xxl-4{gap:1.5rem !important}.gap-xxl-5{gap:3rem !important}.row-gap-xxl-0{row-gap:0 !important}.row-gap-xxl-1{row-gap:.25rem !important}.row-gap-xxl-2{row-gap:.5rem !important}.row-gap-xxl-3{row-gap:1rem !important}.row-gap-xxl-4{row-gap:1.5rem !important}.row-gap-xxl-5{row-gap:3rem !important}.column-gap-xxl-0{column-gap:0 !important}.column-gap-xxl-1{column-gap:.25rem !important}.column-gap-xxl-2{column-gap:.5rem !important}.column-gap-xxl-3{column-gap:1rem !important}.column-gap-xxl-4{column-gap:1.5rem !important}.column-gap-xxl-5{column-gap:3rem !important}.text-xxl-start{text-align:left !important}.text-xxl-end{text-align:right !important}.text-xxl-center{text-align:center !important}}.bg-default{color:#fff}.bg-primary{color:#fff}.bg-secondary{color:#fff}.bg-success{color:#fff}.bg-info{color:#fff}.bg-warning{color:#fff}.bg-danger{color:#fff}.bg-light{color:#fff}.bg-dark{color:#fff}@media(min-width: 1200px){.fs-1{font-size:2rem !important}.fs-2{font-size:1.65rem !important}.fs-3{font-size:1.45rem !important}}@media print{.d-print-inline{display:inline !important}.d-print-inline-block{display:inline-block !important}.d-print-block{display:block !important}.d-print-grid{display:grid !important}.d-print-inline-grid{display:inline-grid !important}.d-print-table{display:table !important}.d-print-table-row{display:table-row !important}.d-print-table-cell{display:table-cell !important}.d-print-flex{display:flex !important}.d-print-inline-flex{display:inline-flex !important}.d-print-none{display:none !important}}:root{--bslib-spacer: 1rem;--bslib-mb-spacer: var(--bslib-spacer, 1rem)}.bslib-mb-spacing{margin-bottom:var(--bslib-mb-spacer)}.bslib-gap-spacing{gap:var(--bslib-mb-spacer)}.bslib-gap-spacing>.bslib-mb-spacing,.bslib-gap-spacing>.form-group,.bslib-gap-spacing>p,.bslib-gap-spacing>pre{margin-bottom:0}.html-fill-container>.html-fill-item.bslib-mb-spacing{margin-bottom:0}.tab-content>.tab-pane.html-fill-container{display:none}.tab-content>.active.html-fill-container{display:flex}.tab-content.html-fill-container{padding:0}.bg-blue{--bslib-color-bg: #375a7f;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-blue{--bslib-color-fg: #375a7f;color:var(--bslib-color-fg)}.bg-indigo{--bslib-color-bg: #6610f2;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-indigo{--bslib-color-fg: #6610f2;color:var(--bslib-color-fg)}.bg-purple{--bslib-color-bg: #6f42c1;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-purple{--bslib-color-fg: #6f42c1;color:var(--bslib-color-fg)}.bg-pink{--bslib-color-bg: #e83e8c;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-pink{--bslib-color-fg: #e83e8c;color:var(--bslib-color-fg)}.bg-red{--bslib-color-bg: #e74c3c;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-red{--bslib-color-fg: #e74c3c;color:var(--bslib-color-fg)}.bg-orange{--bslib-color-bg: #fd7e14;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-orange{--bslib-color-fg: #fd7e14;color:var(--bslib-color-fg)}.bg-yellow{--bslib-color-bg: #f39c12;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-yellow{--bslib-color-fg: #f39c12;color:var(--bslib-color-fg)}.bg-green{--bslib-color-bg: #00bc8c;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-green{--bslib-color-fg: #00bc8c;color:var(--bslib-color-fg)}.bg-teal{--bslib-color-bg: #20c997;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-teal{--bslib-color-fg: #20c997;color:var(--bslib-color-fg)}.bg-cyan{--bslib-color-bg: #3498db;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-cyan{--bslib-color-fg: #3498db;color:var(--bslib-color-fg)}.text-default{--bslib-color-fg: #434343}.bg-default{--bslib-color-bg: #434343;--bslib-color-fg: #fff}.text-primary{--bslib-color-fg: #375a7f}.bg-primary{--bslib-color-bg: #375a7f;--bslib-color-fg: #fff}.text-secondary{--bslib-color-fg: #434343}.bg-secondary{--bslib-color-bg: #434343;--bslib-color-fg: #fff}.text-success{--bslib-color-fg: #00bc8c}.bg-success{--bslib-color-bg: #00bc8c;--bslib-color-fg: #fff}.text-info{--bslib-color-fg: #3498db}.bg-info{--bslib-color-bg: #3498db;--bslib-color-fg: #fff}.text-warning{--bslib-color-fg: #f39c12}.bg-warning{--bslib-color-bg: #f39c12;--bslib-color-fg: #fff}.text-danger{--bslib-color-fg: #e74c3c}.bg-danger{--bslib-color-bg: #e74c3c;--bslib-color-fg: #fff}.text-light{--bslib-color-fg: #6f6f6f}.bg-light{--bslib-color-bg: #6f6f6f;--bslib-color-fg: #fff}.text-dark{--bslib-color-fg: #2d2d2d}.bg-dark{--bslib-color-bg: #2d2d2d;--bslib-color-fg: #fff}.bg-gradient-blue-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #4a3cad;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #4a3cad;color:#fff}.bg-gradient-blue-purple{--bslib-color-fg: #fff;--bslib-color-bg: #4d5099;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #4d5099;color:#fff}.bg-gradient-blue-pink{--bslib-color-fg: #fff;--bslib-color-bg: #7e4f84;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #7e4f84;color:#fff}.bg-gradient-blue-red{--bslib-color-fg: #fff;--bslib-color-bg: #7d5464;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #7d5464;color:#fff}.bg-gradient-blue-orange{--bslib-color-fg: #fff;--bslib-color-bg: #866854;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #866854;color:#fff}.bg-gradient-blue-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #827453;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #827453;color:#fff}.bg-gradient-blue-green{--bslib-color-fg: #fff;--bslib-color-bg: #218184;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #218184;color:#fff}.bg-gradient-blue-teal{--bslib-color-fg: #fff;--bslib-color-bg: #2e8689;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #2e8689;color:#fff}.bg-gradient-blue-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #3673a4;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #3673a4;color:#fff}.bg-gradient-indigo-blue{--bslib-color-fg: #fff;--bslib-color-bg: #532ec4;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #532ec4;color:#fff}.bg-gradient-indigo-purple{--bslib-color-fg: #fff;--bslib-color-bg: #6a24de;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #6a24de;color:#fff}.bg-gradient-indigo-pink{--bslib-color-fg: #fff;--bslib-color-bg: #9a22c9;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #9a22c9;color:#fff}.bg-gradient-indigo-red{--bslib-color-fg: #fff;--bslib-color-bg: #9a28a9;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #9a28a9;color:#fff}.bg-gradient-indigo-orange{--bslib-color-fg: #fff;--bslib-color-bg: #a23c99;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #a23c99;color:#fff}.bg-gradient-indigo-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #9e4898;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #9e4898;color:#fff}.bg-gradient-indigo-green{--bslib-color-fg: #fff;--bslib-color-bg: #3d55c9;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #3d55c9;color:#fff}.bg-gradient-indigo-teal{--bslib-color-fg: #fff;--bslib-color-bg: #4a5ace;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #4a5ace;color:#fff}.bg-gradient-indigo-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #5246e9;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #5246e9;color:#fff}.bg-gradient-purple-blue{--bslib-color-fg: #fff;--bslib-color-bg: #594ca7;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #594ca7;color:#fff}.bg-gradient-purple-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #6b2ed5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #6b2ed5;color:#fff}.bg-gradient-purple-pink{--bslib-color-fg: #fff;--bslib-color-bg: #9f40ac;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #9f40ac;color:#fff}.bg-gradient-purple-red{--bslib-color-fg: #fff;--bslib-color-bg: #9f468c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #9f468c;color:#fff}.bg-gradient-purple-orange{--bslib-color-fg: #fff;--bslib-color-bg: #a85a7c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #a85a7c;color:#fff}.bg-gradient-purple-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #a4667b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #a4667b;color:#fff}.bg-gradient-purple-green{--bslib-color-fg: #fff;--bslib-color-bg: #4373ac;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #4373ac;color:#fff}.bg-gradient-purple-teal{--bslib-color-fg: #fff;--bslib-color-bg: #4f78b0;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #4f78b0;color:#fff}.bg-gradient-purple-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #5764cb;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #5764cb;color:#fff}.bg-gradient-pink-blue{--bslib-color-fg: #fff;--bslib-color-bg: #a14987;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #a14987;color:#fff}.bg-gradient-pink-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #b42cb5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #b42cb5;color:#fff}.bg-gradient-pink-purple{--bslib-color-fg: #fff;--bslib-color-bg: #b840a1;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #b840a1;color:#fff}.bg-gradient-pink-red{--bslib-color-fg: #fff;--bslib-color-bg: #e8446c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #e8446c;color:#fff}.bg-gradient-pink-orange{--bslib-color-fg: #fff;--bslib-color-bg: #f0585c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #f0585c;color:#fff}.bg-gradient-pink-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #ec645b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #ec645b;color:#fff}.bg-gradient-pink-green{--bslib-color-fg: #fff;--bslib-color-bg: #8b708c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #8b708c;color:#fff}.bg-gradient-pink-teal{--bslib-color-fg: #fff;--bslib-color-bg: #987690;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #987690;color:#fff}.bg-gradient-pink-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #a062ac;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #a062ac;color:#fff}.bg-gradient-red-blue{--bslib-color-fg: #fff;--bslib-color-bg: #a15257;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #a15257;color:#fff}.bg-gradient-red-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #b33485;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #b33485;color:#fff}.bg-gradient-red-purple{--bslib-color-fg: #fff;--bslib-color-bg: #b74871;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #b74871;color:#fff}.bg-gradient-red-pink{--bslib-color-fg: #fff;--bslib-color-bg: #e7465c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #e7465c;color:#fff}.bg-gradient-red-orange{--bslib-color-fg: #fff;--bslib-color-bg: #f0602c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #f0602c;color:#fff}.bg-gradient-red-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #ec6c2b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #ec6c2b;color:#fff}.bg-gradient-red-green{--bslib-color-fg: #fff;--bslib-color-bg: #8b795c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #8b795c;color:#fff}.bg-gradient-red-teal{--bslib-color-fg: #fff;--bslib-color-bg: #977e60;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #977e60;color:#fff}.bg-gradient-red-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #9f6a7c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #9f6a7c;color:#fff}.bg-gradient-orange-blue{--bslib-color-fg: #fff;--bslib-color-bg: #ae703f;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #ae703f;color:#fff}.bg-gradient-orange-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #c1526d;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #c1526d;color:#fff}.bg-gradient-orange-purple{--bslib-color-fg: #fff;--bslib-color-bg: #c46659;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #c46659;color:#fff}.bg-gradient-orange-pink{--bslib-color-fg: #fff;--bslib-color-bg: #f56444;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #f56444;color:#fff}.bg-gradient-orange-red{--bslib-color-fg: #fff;--bslib-color-bg: #f46a24;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #f46a24;color:#fff}.bg-gradient-orange-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #f98a13;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #f98a13;color:#fff}.bg-gradient-orange-green{--bslib-color-fg: #fff;--bslib-color-bg: #989744;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #989744;color:#fff}.bg-gradient-orange-teal{--bslib-color-fg: #fff;--bslib-color-bg: #a59c48;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #a59c48;color:#fff}.bg-gradient-orange-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #ad8864;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #ad8864;color:#fff}.bg-gradient-yellow-blue{--bslib-color-fg: #fff;--bslib-color-bg: #a8823e;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #a8823e;color:#fff}.bg-gradient-yellow-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #bb646c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #bb646c;color:#fff}.bg-gradient-yellow-purple{--bslib-color-fg: #fff;--bslib-color-bg: #be7858;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #be7858;color:#fff}.bg-gradient-yellow-pink{--bslib-color-fg: #fff;--bslib-color-bg: #ef7643;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #ef7643;color:#fff}.bg-gradient-yellow-red{--bslib-color-fg: #fff;--bslib-color-bg: #ee7c23;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #ee7c23;color:#fff}.bg-gradient-yellow-orange{--bslib-color-fg: #fff;--bslib-color-bg: #f79013;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #f79013;color:#fff}.bg-gradient-yellow-green{--bslib-color-fg: #fff;--bslib-color-bg: #92a943;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #92a943;color:#fff}.bg-gradient-yellow-teal{--bslib-color-fg: #fff;--bslib-color-bg: #9fae47;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #9fae47;color:#fff}.bg-gradient-yellow-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #a79a62;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #a79a62;color:#fff}.bg-gradient-green-blue{--bslib-color-fg: #fff;--bslib-color-bg: #169587;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #169587;color:#fff}.bg-gradient-green-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #2977b5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #2977b5;color:#fff}.bg-gradient-green-purple{--bslib-color-fg: #fff;--bslib-color-bg: #2c8ba1;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #2c8ba1;color:#fff}.bg-gradient-green-pink{--bslib-color-fg: #fff;--bslib-color-bg: #5d8a8c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #5d8a8c;color:#fff}.bg-gradient-green-red{--bslib-color-fg: #fff;--bslib-color-bg: #5c8f6c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #5c8f6c;color:#fff}.bg-gradient-green-orange{--bslib-color-fg: #fff;--bslib-color-bg: #65a35c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #65a35c;color:#fff}.bg-gradient-green-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #61af5b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #61af5b;color:#fff}.bg-gradient-green-teal{--bslib-color-fg: #fff;--bslib-color-bg: #0dc190;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #0dc190;color:#fff}.bg-gradient-green-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #15aeac;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #15aeac;color:#fff}.bg-gradient-teal-blue{--bslib-color-fg: #fff;--bslib-color-bg: #299d8d;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #299d8d;color:#fff}.bg-gradient-teal-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #3c7fbb;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #3c7fbb;color:#fff}.bg-gradient-teal-purple{--bslib-color-fg: #fff;--bslib-color-bg: #4093a8;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #4093a8;color:#fff}.bg-gradient-teal-pink{--bslib-color-fg: #fff;--bslib-color-bg: #709193;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #709193;color:#fff}.bg-gradient-teal-red{--bslib-color-fg: #fff;--bslib-color-bg: #709773;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #709773;color:#fff}.bg-gradient-teal-orange{--bslib-color-fg: #fff;--bslib-color-bg: #78ab63;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #78ab63;color:#fff}.bg-gradient-teal-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #74b762;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #74b762;color:#fff}.bg-gradient-teal-green{--bslib-color-fg: #fff;--bslib-color-bg: #13c493;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #13c493;color:#fff}.bg-gradient-teal-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #28b5b2;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #28b5b2;color:#fff}.bg-gradient-cyan-blue{--bslib-color-fg: #fff;--bslib-color-bg: #357fb6;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #357fb6;color:#fff}.bg-gradient-cyan-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #4862e4;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #4862e4;color:#fff}.bg-gradient-cyan-purple{--bslib-color-fg: #fff;--bslib-color-bg: #4c76d1;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #4c76d1;color:#fff}.bg-gradient-cyan-pink{--bslib-color-fg: #fff;--bslib-color-bg: #7c74bb;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #7c74bb;color:#fff}.bg-gradient-cyan-red{--bslib-color-fg: #fff;--bslib-color-bg: #7c7a9b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #7c7a9b;color:#fff}.bg-gradient-cyan-orange{--bslib-color-fg: #fff;--bslib-color-bg: #848e8b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #848e8b;color:#fff}.bg-gradient-cyan-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #809a8b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #809a8b;color:#fff}.bg-gradient-cyan-green{--bslib-color-fg: #fff;--bslib-color-bg: #1fa6bb;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #1fa6bb;color:#fff}.bg-gradient-cyan-teal{--bslib-color-fg: #fff;--bslib-color-bg: #2cacc0;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #2cacc0;color:#fff}.bg-blue{--bslib-color-bg: #375a7f;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-blue{--bslib-color-fg: #375a7f;color:var(--bslib-color-fg)}.bg-indigo{--bslib-color-bg: #6610f2;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-indigo{--bslib-color-fg: #6610f2;color:var(--bslib-color-fg)}.bg-purple{--bslib-color-bg: #6f42c1;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-purple{--bslib-color-fg: #6f42c1;color:var(--bslib-color-fg)}.bg-pink{--bslib-color-bg: #e83e8c;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-pink{--bslib-color-fg: #e83e8c;color:var(--bslib-color-fg)}.bg-red{--bslib-color-bg: #e74c3c;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-red{--bslib-color-fg: #e74c3c;color:var(--bslib-color-fg)}.bg-orange{--bslib-color-bg: #fd7e14;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-orange{--bslib-color-fg: #fd7e14;color:var(--bslib-color-fg)}.bg-yellow{--bslib-color-bg: #f39c12;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-yellow{--bslib-color-fg: #f39c12;color:var(--bslib-color-fg)}.bg-green{--bslib-color-bg: #00bc8c;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-green{--bslib-color-fg: #00bc8c;color:var(--bslib-color-fg)}.bg-teal{--bslib-color-bg: #20c997;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-teal{--bslib-color-fg: #20c997;color:var(--bslib-color-fg)}.bg-cyan{--bslib-color-bg: #3498db;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-cyan{--bslib-color-fg: #3498db;color:var(--bslib-color-fg)}.text-default{--bslib-color-fg: #434343}.bg-default{--bslib-color-bg: #434343;--bslib-color-fg: #fff}.text-primary{--bslib-color-fg: #375a7f}.bg-primary{--bslib-color-bg: #375a7f;--bslib-color-fg: #fff}.text-secondary{--bslib-color-fg: #434343}.bg-secondary{--bslib-color-bg: #434343;--bslib-color-fg: #fff}.text-success{--bslib-color-fg: #00bc8c}.bg-success{--bslib-color-bg: #00bc8c;--bslib-color-fg: #fff}.text-info{--bslib-color-fg: #3498db}.bg-info{--bslib-color-bg: #3498db;--bslib-color-fg: #fff}.text-warning{--bslib-color-fg: #f39c12}.bg-warning{--bslib-color-bg: #f39c12;--bslib-color-fg: #fff}.text-danger{--bslib-color-fg: #e74c3c}.bg-danger{--bslib-color-bg: #e74c3c;--bslib-color-fg: #fff}.text-light{--bslib-color-fg: #6f6f6f}.bg-light{--bslib-color-bg: #6f6f6f;--bslib-color-fg: #fff}.text-dark{--bslib-color-fg: #2d2d2d}.bg-dark{--bslib-color-bg: #2d2d2d;--bslib-color-fg: #fff}.bg-gradient-blue-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #4a3cad;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #4a3cad;color:#fff}.bg-gradient-blue-purple{--bslib-color-fg: #fff;--bslib-color-bg: #4d5099;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #4d5099;color:#fff}.bg-gradient-blue-pink{--bslib-color-fg: #fff;--bslib-color-bg: #7e4f84;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #7e4f84;color:#fff}.bg-gradient-blue-red{--bslib-color-fg: #fff;--bslib-color-bg: #7d5464;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #7d5464;color:#fff}.bg-gradient-blue-orange{--bslib-color-fg: #fff;--bslib-color-bg: #866854;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #866854;color:#fff}.bg-gradient-blue-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #827453;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #827453;color:#fff}.bg-gradient-blue-green{--bslib-color-fg: #fff;--bslib-color-bg: #218184;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #218184;color:#fff}.bg-gradient-blue-teal{--bslib-color-fg: #fff;--bslib-color-bg: #2e8689;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #2e8689;color:#fff}.bg-gradient-blue-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #3673a4;background:linear-gradient(var(--bg-gradient-deg, 140deg), #375a7f var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #3673a4;color:#fff}.bg-gradient-indigo-blue{--bslib-color-fg: #fff;--bslib-color-bg: #532ec4;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #532ec4;color:#fff}.bg-gradient-indigo-purple{--bslib-color-fg: #fff;--bslib-color-bg: #6a24de;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #6a24de;color:#fff}.bg-gradient-indigo-pink{--bslib-color-fg: #fff;--bslib-color-bg: #9a22c9;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #9a22c9;color:#fff}.bg-gradient-indigo-red{--bslib-color-fg: #fff;--bslib-color-bg: #9a28a9;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #9a28a9;color:#fff}.bg-gradient-indigo-orange{--bslib-color-fg: #fff;--bslib-color-bg: #a23c99;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #a23c99;color:#fff}.bg-gradient-indigo-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #9e4898;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #9e4898;color:#fff}.bg-gradient-indigo-green{--bslib-color-fg: #fff;--bslib-color-bg: #3d55c9;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #3d55c9;color:#fff}.bg-gradient-indigo-teal{--bslib-color-fg: #fff;--bslib-color-bg: #4a5ace;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #4a5ace;color:#fff}.bg-gradient-indigo-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #5246e9;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #5246e9;color:#fff}.bg-gradient-purple-blue{--bslib-color-fg: #fff;--bslib-color-bg: #594ca7;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #594ca7;color:#fff}.bg-gradient-purple-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #6b2ed5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #6b2ed5;color:#fff}.bg-gradient-purple-pink{--bslib-color-fg: #fff;--bslib-color-bg: #9f40ac;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #9f40ac;color:#fff}.bg-gradient-purple-red{--bslib-color-fg: #fff;--bslib-color-bg: #9f468c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #9f468c;color:#fff}.bg-gradient-purple-orange{--bslib-color-fg: #fff;--bslib-color-bg: #a85a7c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #a85a7c;color:#fff}.bg-gradient-purple-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #a4667b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #a4667b;color:#fff}.bg-gradient-purple-green{--bslib-color-fg: #fff;--bslib-color-bg: #4373ac;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #4373ac;color:#fff}.bg-gradient-purple-teal{--bslib-color-fg: #fff;--bslib-color-bg: #4f78b0;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #4f78b0;color:#fff}.bg-gradient-purple-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #5764cb;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6f42c1 var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #5764cb;color:#fff}.bg-gradient-pink-blue{--bslib-color-fg: #fff;--bslib-color-bg: #a14987;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #a14987;color:#fff}.bg-gradient-pink-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #b42cb5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #b42cb5;color:#fff}.bg-gradient-pink-purple{--bslib-color-fg: #fff;--bslib-color-bg: #b840a1;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #b840a1;color:#fff}.bg-gradient-pink-red{--bslib-color-fg: #fff;--bslib-color-bg: #e8446c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #e8446c;color:#fff}.bg-gradient-pink-orange{--bslib-color-fg: #fff;--bslib-color-bg: #f0585c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #f0585c;color:#fff}.bg-gradient-pink-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #ec645b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #ec645b;color:#fff}.bg-gradient-pink-green{--bslib-color-fg: #fff;--bslib-color-bg: #8b708c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #8b708c;color:#fff}.bg-gradient-pink-teal{--bslib-color-fg: #fff;--bslib-color-bg: #987690;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #987690;color:#fff}.bg-gradient-pink-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #a062ac;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #a062ac;color:#fff}.bg-gradient-red-blue{--bslib-color-fg: #fff;--bslib-color-bg: #a15257;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #a15257;color:#fff}.bg-gradient-red-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #b33485;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #b33485;color:#fff}.bg-gradient-red-purple{--bslib-color-fg: #fff;--bslib-color-bg: #b74871;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #b74871;color:#fff}.bg-gradient-red-pink{--bslib-color-fg: #fff;--bslib-color-bg: #e7465c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #e7465c;color:#fff}.bg-gradient-red-orange{--bslib-color-fg: #fff;--bslib-color-bg: #f0602c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #f0602c;color:#fff}.bg-gradient-red-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #ec6c2b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #ec6c2b;color:#fff}.bg-gradient-red-green{--bslib-color-fg: #fff;--bslib-color-bg: #8b795c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #8b795c;color:#fff}.bg-gradient-red-teal{--bslib-color-fg: #fff;--bslib-color-bg: #977e60;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #977e60;color:#fff}.bg-gradient-red-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #9f6a7c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e74c3c var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #9f6a7c;color:#fff}.bg-gradient-orange-blue{--bslib-color-fg: #fff;--bslib-color-bg: #ae703f;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #ae703f;color:#fff}.bg-gradient-orange-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #c1526d;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #c1526d;color:#fff}.bg-gradient-orange-purple{--bslib-color-fg: #fff;--bslib-color-bg: #c46659;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #c46659;color:#fff}.bg-gradient-orange-pink{--bslib-color-fg: #fff;--bslib-color-bg: #f56444;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #f56444;color:#fff}.bg-gradient-orange-red{--bslib-color-fg: #fff;--bslib-color-bg: #f46a24;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #f46a24;color:#fff}.bg-gradient-orange-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #f98a13;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #f98a13;color:#fff}.bg-gradient-orange-green{--bslib-color-fg: #fff;--bslib-color-bg: #989744;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #989744;color:#fff}.bg-gradient-orange-teal{--bslib-color-fg: #fff;--bslib-color-bg: #a59c48;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #a59c48;color:#fff}.bg-gradient-orange-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #ad8864;background:linear-gradient(var(--bg-gradient-deg, 140deg), #fd7e14 var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #ad8864;color:#fff}.bg-gradient-yellow-blue{--bslib-color-fg: #fff;--bslib-color-bg: #a8823e;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #a8823e;color:#fff}.bg-gradient-yellow-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #bb646c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #bb646c;color:#fff}.bg-gradient-yellow-purple{--bslib-color-fg: #fff;--bslib-color-bg: #be7858;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #be7858;color:#fff}.bg-gradient-yellow-pink{--bslib-color-fg: #fff;--bslib-color-bg: #ef7643;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #ef7643;color:#fff}.bg-gradient-yellow-red{--bslib-color-fg: #fff;--bslib-color-bg: #ee7c23;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #ee7c23;color:#fff}.bg-gradient-yellow-orange{--bslib-color-fg: #fff;--bslib-color-bg: #f79013;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #f79013;color:#fff}.bg-gradient-yellow-green{--bslib-color-fg: #fff;--bslib-color-bg: #92a943;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #92a943;color:#fff}.bg-gradient-yellow-teal{--bslib-color-fg: #fff;--bslib-color-bg: #9fae47;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #9fae47;color:#fff}.bg-gradient-yellow-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #a79a62;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f39c12 var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #a79a62;color:#fff}.bg-gradient-green-blue{--bslib-color-fg: #fff;--bslib-color-bg: #169587;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #169587;color:#fff}.bg-gradient-green-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #2977b5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #2977b5;color:#fff}.bg-gradient-green-purple{--bslib-color-fg: #fff;--bslib-color-bg: #2c8ba1;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #2c8ba1;color:#fff}.bg-gradient-green-pink{--bslib-color-fg: #fff;--bslib-color-bg: #5d8a8c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #5d8a8c;color:#fff}.bg-gradient-green-red{--bslib-color-fg: #fff;--bslib-color-bg: #5c8f6c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #5c8f6c;color:#fff}.bg-gradient-green-orange{--bslib-color-fg: #fff;--bslib-color-bg: #65a35c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #65a35c;color:#fff}.bg-gradient-green-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #61af5b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #61af5b;color:#fff}.bg-gradient-green-teal{--bslib-color-fg: #fff;--bslib-color-bg: #0dc190;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #0dc190;color:#fff}.bg-gradient-green-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #15aeac;background:linear-gradient(var(--bg-gradient-deg, 140deg), #00bc8c var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #15aeac;color:#fff}.bg-gradient-teal-blue{--bslib-color-fg: #fff;--bslib-color-bg: #299d8d;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #299d8d;color:#fff}.bg-gradient-teal-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #3c7fbb;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #3c7fbb;color:#fff}.bg-gradient-teal-purple{--bslib-color-fg: #fff;--bslib-color-bg: #4093a8;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #4093a8;color:#fff}.bg-gradient-teal-pink{--bslib-color-fg: #fff;--bslib-color-bg: #709193;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #709193;color:#fff}.bg-gradient-teal-red{--bslib-color-fg: #fff;--bslib-color-bg: #709773;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #709773;color:#fff}.bg-gradient-teal-orange{--bslib-color-fg: #fff;--bslib-color-bg: #78ab63;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #78ab63;color:#fff}.bg-gradient-teal-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #74b762;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #74b762;color:#fff}.bg-gradient-teal-green{--bslib-color-fg: #fff;--bslib-color-bg: #13c493;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #13c493;color:#fff}.bg-gradient-teal-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #28b5b2;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #3498db var(--bg-gradient-end, 180%)) #28b5b2;color:#fff}.bg-gradient-cyan-blue{--bslib-color-fg: #fff;--bslib-color-bg: #357fb6;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #375a7f var(--bg-gradient-end, 180%)) #357fb6;color:#fff}.bg-gradient-cyan-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #4862e4;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #4862e4;color:#fff}.bg-gradient-cyan-purple{--bslib-color-fg: #fff;--bslib-color-bg: #4c76d1;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #6f42c1 var(--bg-gradient-end, 180%)) #4c76d1;color:#fff}.bg-gradient-cyan-pink{--bslib-color-fg: #fff;--bslib-color-bg: #7c74bb;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #7c74bb;color:#fff}.bg-gradient-cyan-red{--bslib-color-fg: #fff;--bslib-color-bg: #7c7a9b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #e74c3c var(--bg-gradient-end, 180%)) #7c7a9b;color:#fff}.bg-gradient-cyan-orange{--bslib-color-fg: #fff;--bslib-color-bg: #848e8b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #fd7e14 var(--bg-gradient-end, 180%)) #848e8b;color:#fff}.bg-gradient-cyan-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #809a8b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #f39c12 var(--bg-gradient-end, 180%)) #809a8b;color:#fff}.bg-gradient-cyan-green{--bslib-color-fg: #fff;--bslib-color-bg: #1fa6bb;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #00bc8c var(--bg-gradient-end, 180%)) #1fa6bb;color:#fff}.bg-gradient-cyan-teal{--bslib-color-fg: #fff;--bslib-color-bg: #2cacc0;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3498db var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #2cacc0;color:#fff}:root{--bslib-spacer: 1rem;--bslib-mb-spacer: var(--bslib-spacer, 1rem)}.bslib-mb-spacing{margin-bottom:var(--bslib-mb-spacer)}.bslib-gap-spacing{gap:var(--bslib-mb-spacer)}.bslib-gap-spacing>.bslib-mb-spacing,.bslib-gap-spacing>.form-group,.bslib-gap-spacing>p,.bslib-gap-spacing>pre{margin-bottom:0}.html-fill-container>.html-fill-item.bslib-mb-spacing{margin-bottom:0}.tab-content>.tab-pane.html-fill-container{display:none}.tab-content>.active.html-fill-container{display:flex}.tab-content.html-fill-container{padding:0}.accordion .accordion-header{font-size:calc(1.29rem + 0.48vw);margin-top:0;margin-bottom:.5rem;font-weight:500;line-height:1.2;color:var(--bs-heading-color);margin-bottom:0}@media(min-width: 1200px){.accordion .accordion-header{font-size:1.65rem}}.accordion .accordion-icon:not(:empty){margin-right:.75rem;display:flex}.accordion .accordion-button:not(.collapsed){box-shadow:none}.accordion .accordion-button:not(.collapsed):focus{box-shadow:var(--bs-accordion-btn-focus-box-shadow)}.bslib-card{overflow:auto}.bslib-card .card-body+.card-body{padding-top:0}.bslib-card .card-body{overflow:auto}.bslib-card .card-body p{margin-top:0}.bslib-card .card-body p:last-child{margin-bottom:0}.bslib-card .card-body{max-height:var(--bslib-card-body-max-height, none)}.bslib-card[data-full-screen=true]>.card-body{max-height:var(--bslib-card-body-max-height-full-screen, none)}.bslib-card .card-header .form-group{margin-bottom:0}.bslib-card .card-header .selectize-control{margin-bottom:0}.bslib-card .card-header .selectize-control .item{margin-right:1.15rem}.bslib-card .card-footer{margin-top:auto}.bslib-card .bslib-navs-card-title{display:flex;flex-wrap:wrap;justify-content:space-between;align-items:center}.bslib-card .bslib-navs-card-title .nav{margin-left:auto}.bslib-card .bslib-sidebar-layout:not([data-bslib-sidebar-border=true]){border:none}.bslib-card .bslib-sidebar-layout:not([data-bslib-sidebar-border-radius=true]){border-top-left-radius:0;border-top-right-radius:0}[data-full-screen=true]{position:fixed;inset:3.5rem 1rem 1rem;height:auto !important;max-height:none !important;width:auto !important;z-index:1070}.bslib-full-screen-enter{display:none;position:absolute;bottom:var(--bslib-full-screen-enter-bottom, 0.2rem);right:var(--bslib-full-screen-enter-right, 0);top:var(--bslib-full-screen-enter-top);left:var(--bslib-full-screen-enter-left);color:var(--bslib-color-fg, var(--bs-card-color));background-color:var(--bslib-color-bg, var(--bs-card-bg, var(--bs-body-bg)));border:var(--bs-card-border-width) solid var(--bslib-color-fg, var(--bs-card-border-color));box-shadow:0 2px 4px rgba(0,0,0,.15);margin:.2rem .4rem;padding:.55rem !important;font-size:.8rem;cursor:pointer;opacity:.7;z-index:1070}.bslib-full-screen-enter:hover{opacity:1}.card[data-full-screen=false]:hover>*>.bslib-full-screen-enter{display:block}.bslib-has-full-screen .card:hover>*>.bslib-full-screen-enter{display:none}@media(max-width: 575.98px){.bslib-full-screen-enter{display:none !important}}.bslib-full-screen-exit{position:relative;top:1.35rem;font-size:.9rem;cursor:pointer;text-decoration:none;display:flex;float:right;margin-right:2.15rem;align-items:center;color:rgba(var(--bs-body-bg-rgb), 0.8)}.bslib-full-screen-exit:hover{color:rgba(var(--bs-body-bg-rgb), 1)}.bslib-full-screen-exit svg{margin-left:.5rem;font-size:1.5rem}#bslib-full-screen-overlay{position:fixed;inset:0;background-color:rgba(var(--bs-body-color-rgb), 0.6);backdrop-filter:blur(2px);-webkit-backdrop-filter:blur(2px);z-index:1069;animation:bslib-full-screen-overlay-enter 400ms cubic-bezier(0.6, 0.02, 0.65, 1) forwards}@keyframes bslib-full-screen-overlay-enter{0%{opacity:0}100%{opacity:1}}.bslib-grid{display:grid !important;gap:var(--bslib-spacer, 1rem);height:var(--bslib-grid-height)}.bslib-grid.grid{grid-template-columns:repeat(var(--bs-columns, 12), minmax(0, 1fr));grid-template-rows:unset;grid-auto-rows:var(--bslib-grid--row-heights);--bslib-grid--row-heights--xs: unset;--bslib-grid--row-heights--sm: unset;--bslib-grid--row-heights--md: unset;--bslib-grid--row-heights--lg: unset;--bslib-grid--row-heights--xl: unset;--bslib-grid--row-heights--xxl: unset}.bslib-grid.grid.bslib-grid--row-heights--xs{--bslib-grid--row-heights: var(--bslib-grid--row-heights--xs)}@media(min-width: 576px){.bslib-grid.grid.bslib-grid--row-heights--sm{--bslib-grid--row-heights: var(--bslib-grid--row-heights--sm)}}@media(min-width: 768px){.bslib-grid.grid.bslib-grid--row-heights--md{--bslib-grid--row-heights: var(--bslib-grid--row-heights--md)}}@media(min-width: 992px){.bslib-grid.grid.bslib-grid--row-heights--lg{--bslib-grid--row-heights: var(--bslib-grid--row-heights--lg)}}@media(min-width: 1200px){.bslib-grid.grid.bslib-grid--row-heights--xl{--bslib-grid--row-heights: var(--bslib-grid--row-heights--xl)}}@media(min-width: 1400px){.bslib-grid.grid.bslib-grid--row-heights--xxl{--bslib-grid--row-heights: var(--bslib-grid--row-heights--xxl)}}.bslib-grid>*>.shiny-input-container{width:100%}.bslib-grid-item{grid-column:auto/span 1}@media(max-width: 767.98px){.bslib-grid-item{grid-column:1/-1}}@media(max-width: 575.98px){.bslib-grid{grid-template-columns:1fr !important;height:var(--bslib-grid-height-mobile)}.bslib-grid.grid{height:unset !important;grid-auto-rows:var(--bslib-grid--row-heights--xs, auto)}}@media(min-width: 576px){.nav:not(.nav-hidden){display:flex !important;display:-webkit-flex !important}.nav:not(.nav-hidden):not(.nav-stacked):not(.flex-column){float:none !important}.nav:not(.nav-hidden):not(.nav-stacked):not(.flex-column)>.bslib-nav-spacer{margin-left:auto !important}.nav:not(.nav-hidden):not(.nav-stacked):not(.flex-column)>.form-inline{margin-top:auto;margin-bottom:auto}.nav:not(.nav-hidden).nav-stacked{flex-direction:column;-webkit-flex-direction:column;height:100%}.nav:not(.nav-hidden).nav-stacked>.bslib-nav-spacer{margin-top:auto !important}}html{height:100%}.bslib-page-fill{width:100%;height:100%;margin:0;padding:var(--bslib-spacer, 1rem);gap:var(--bslib-spacer, 1rem)}@media(max-width: 575.98px){.bslib-page-fill{height:var(--bslib-page-fill-mobile-height, auto)}}.navbar+.container-fluid:has(>.tab-content>.tab-pane.active.html-fill-container),.navbar+.container-sm:has(>.tab-content>.tab-pane.active.html-fill-container),.navbar+.container-md:has(>.tab-content>.tab-pane.active.html-fill-container),.navbar+.container-lg:has(>.tab-content>.tab-pane.active.html-fill-container),.navbar+.container-xl:has(>.tab-content>.tab-pane.active.html-fill-container),.navbar+.container-xxl:has(>.tab-content>.tab-pane.active.html-fill-container){padding-left:0;padding-right:0}.navbar+.container-fluid>.tab-content>.tab-pane.active.html-fill-container,.navbar+.container-sm>.tab-content>.tab-pane.active.html-fill-container,.navbar+.container-md>.tab-content>.tab-pane.active.html-fill-container,.navbar+.container-lg>.tab-content>.tab-pane.active.html-fill-container,.navbar+.container-xl>.tab-content>.tab-pane.active.html-fill-container,.navbar+.container-xxl>.tab-content>.tab-pane.active.html-fill-container{padding:var(--bslib-spacer, 1rem);gap:var(--bslib-spacer, 1rem)}.navbar+.container-fluid>.tab-content>.tab-pane.active.html-fill-container:has(>.bslib-sidebar-layout:only-child),.navbar+.container-sm>.tab-content>.tab-pane.active.html-fill-container:has(>.bslib-sidebar-layout:only-child),.navbar+.container-md>.tab-content>.tab-pane.active.html-fill-container:has(>.bslib-sidebar-layout:only-child),.navbar+.container-lg>.tab-content>.tab-pane.active.html-fill-container:has(>.bslib-sidebar-layout:only-child),.navbar+.container-xl>.tab-content>.tab-pane.active.html-fill-container:has(>.bslib-sidebar-layout:only-child),.navbar+.container-xxl>.tab-content>.tab-pane.active.html-fill-container:has(>.bslib-sidebar-layout:only-child){padding:0}.navbar+.container-fluid>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border=true]),.navbar+.container-sm>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border=true]),.navbar+.container-md>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border=true]),.navbar+.container-lg>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border=true]),.navbar+.container-xl>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border=true]),.navbar+.container-xxl>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border=true]){border-left:none;border-right:none;border-bottom:none}.navbar+.container-fluid>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border-radius=true]),.navbar+.container-sm>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border-radius=true]),.navbar+.container-md>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border-radius=true]),.navbar+.container-lg>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border-radius=true]),.navbar+.container-xl>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border-radius=true]),.navbar+.container-xxl>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border-radius=true]){border-radius:0}.navbar+div>.bslib-sidebar-layout{border-top:var(--bslib-sidebar-border)}:root{--bslib-page-sidebar-title-bg: #375a7f;--bslib-page-sidebar-title-color: #fff}.bslib-page-title{background-color:var(--bslib-page-sidebar-title-bg);color:var(--bslib-page-sidebar-title-color);font-size:1.25rem;font-weight:300;padding:var(--bslib-spacer, 1rem);padding-left:1.5rem;margin-bottom:0;border-bottom:1px solid #dee2e6}.bslib-sidebar-layout{--bslib-sidebar-transition-duration: 500ms;--bslib-sidebar-transition-easing-x: cubic-bezier(0.8, 0.78, 0.22, 1.07);--bslib-sidebar-border: var(--bs-card-border-width, 1px) solid var(--bs-card-border-color, rgba(0, 0, 0, 0.175));--bslib-sidebar-border-radius: var(--bs-border-radius);--bslib-sidebar-vert-border: var(--bs-card-border-width, 1px) solid var(--bs-card-border-color, rgba(0, 0, 0, 0.175));--bslib-sidebar-bg: rgba(var(--bs-emphasis-color-rgb, 0, 0, 0), 0.05);--bslib-sidebar-fg: var(--bs-emphasis-color, black);--bslib-sidebar-main-fg: var(--bs-card-color, var(--bs-body-color));--bslib-sidebar-main-bg: var(--bs-card-bg, var(--bs-body-bg));--bslib-sidebar-toggle-bg: rgba(var(--bs-emphasis-color-rgb, 0, 0, 0), 0.1);--bslib-sidebar-padding: calc(var(--bslib-spacer) * 1.5);--bslib-sidebar-icon-size: var(--bslib-spacer, 1rem);--bslib-sidebar-icon-button-size: calc(var(--bslib-sidebar-icon-size, 1rem) * 2);--bslib-sidebar-padding-icon: calc(var(--bslib-sidebar-icon-button-size, 2rem) * 1.5);--bslib-collapse-toggle-border-radius: var(--bs-border-radius, 0.25rem);--bslib-collapse-toggle-transform: 0deg;--bslib-sidebar-toggle-transition-easing: cubic-bezier(1, 0, 0, 1);--bslib-collapse-toggle-right-transform: 180deg;--bslib-sidebar-column-main: minmax(0, 1fr);display:grid !important;grid-template-columns:min(100% - var(--bslib-sidebar-icon-size),var(--bslib-sidebar-width, 250px)) var(--bslib-sidebar-column-main);position:relative;transition:grid-template-columns ease-in-out var(--bslib-sidebar-transition-duration);border:var(--bslib-sidebar-border);border-radius:var(--bslib-sidebar-border-radius)}@media(prefers-reduced-motion: reduce){.bslib-sidebar-layout{transition:none}}.bslib-sidebar-layout[data-bslib-sidebar-border=false]{border:none}.bslib-sidebar-layout[data-bslib-sidebar-border-radius=false]{border-radius:initial}.bslib-sidebar-layout>.main,.bslib-sidebar-layout>.sidebar{grid-row:1/2;border-radius:inherit;overflow:auto}.bslib-sidebar-layout>.main{grid-column:2/3;border-top-left-radius:0;border-bottom-left-radius:0;padding:var(--bslib-sidebar-padding);transition:padding var(--bslib-sidebar-transition-easing-x) var(--bslib-sidebar-transition-duration);color:var(--bslib-sidebar-main-fg);background-color:var(--bslib-sidebar-main-bg)}.bslib-sidebar-layout>.sidebar{grid-column:1/2;width:100%;height:100%;border-right:var(--bslib-sidebar-vert-border);border-top-right-radius:0;border-bottom-right-radius:0;color:var(--bslib-sidebar-fg);background-color:var(--bslib-sidebar-bg);backdrop-filter:blur(5px)}.bslib-sidebar-layout>.sidebar>.sidebar-content{display:flex;flex-direction:column;gap:var(--bslib-spacer, 1rem);padding:var(--bslib-sidebar-padding);padding-top:var(--bslib-sidebar-padding-icon)}.bslib-sidebar-layout>.sidebar>.sidebar-content>:last-child:not(.sidebar-title){margin-bottom:0}.bslib-sidebar-layout>.sidebar>.sidebar-content>.accordion{margin-left:calc(-1*var(--bslib-sidebar-padding));margin-right:calc(-1*var(--bslib-sidebar-padding))}.bslib-sidebar-layout>.sidebar>.sidebar-content>.accordion:last-child{margin-bottom:calc(-1*var(--bslib-sidebar-padding))}.bslib-sidebar-layout>.sidebar>.sidebar-content>.accordion:not(:last-child){margin-bottom:1rem}.bslib-sidebar-layout>.sidebar>.sidebar-content>.accordion .accordion-body{display:flex;flex-direction:column}.bslib-sidebar-layout>.sidebar>.sidebar-content>.accordion:not(:first-child) .accordion-item:first-child{border-top:var(--bs-accordion-border-width) solid var(--bs-accordion-border-color)}.bslib-sidebar-layout>.sidebar>.sidebar-content>.accordion:not(:last-child) .accordion-item:last-child{border-bottom:var(--bs-accordion-border-width) solid var(--bs-accordion-border-color)}.bslib-sidebar-layout>.sidebar>.sidebar-content.has-accordion>.sidebar-title{border-bottom:none;padding-bottom:0}.bslib-sidebar-layout>.sidebar .shiny-input-container{width:100%}.bslib-sidebar-layout[data-bslib-sidebar-open=always]>.sidebar>.sidebar-content{padding-top:var(--bslib-sidebar-padding)}.bslib-sidebar-layout>.collapse-toggle{grid-row:1/2;grid-column:1/2;display:inline-flex;align-items:center;position:absolute;right:calc(var(--bslib-sidebar-icon-size));top:calc(var(--bslib-sidebar-icon-size, 1rem)/2);border:none;border-radius:var(--bslib-collapse-toggle-border-radius);height:var(--bslib-sidebar-icon-button-size, 2rem);width:var(--bslib-sidebar-icon-button-size, 2rem);display:flex;align-items:center;justify-content:center;padding:0;color:var(--bslib-sidebar-fg);background-color:unset;transition:color var(--bslib-sidebar-transition-easing-x) var(--bslib-sidebar-transition-duration),top var(--bslib-sidebar-transition-easing-x) var(--bslib-sidebar-transition-duration),right var(--bslib-sidebar-transition-easing-x) var(--bslib-sidebar-transition-duration),left var(--bslib-sidebar-transition-easing-x) var(--bslib-sidebar-transition-duration)}.bslib-sidebar-layout>.collapse-toggle:hover{background-color:var(--bslib-sidebar-toggle-bg)}.bslib-sidebar-layout>.collapse-toggle>.collapse-icon{opacity:.8;width:var(--bslib-sidebar-icon-size);height:var(--bslib-sidebar-icon-size);transform:rotateY(var(--bslib-collapse-toggle-transform));transition:transform var(--bslib-sidebar-toggle-transition-easing) var(--bslib-sidebar-transition-duration)}.bslib-sidebar-layout>.collapse-toggle:hover>.collapse-icon{opacity:1}.bslib-sidebar-layout .sidebar-title{font-size:1.25rem;line-height:1.25;margin-top:0;margin-bottom:1rem;padding-bottom:1rem;border-bottom:var(--bslib-sidebar-border)}.bslib-sidebar-layout.sidebar-right{grid-template-columns:var(--bslib-sidebar-column-main) min(100% - var(--bslib-sidebar-icon-size),var(--bslib-sidebar-width, 250px))}.bslib-sidebar-layout.sidebar-right>.main{grid-column:1/2;border-top-right-radius:0;border-bottom-right-radius:0;border-top-left-radius:inherit;border-bottom-left-radius:inherit}.bslib-sidebar-layout.sidebar-right>.sidebar{grid-column:2/3;border-right:none;border-left:var(--bslib-sidebar-vert-border);border-top-left-radius:0;border-bottom-left-radius:0}.bslib-sidebar-layout.sidebar-right>.collapse-toggle{grid-column:2/3;left:var(--bslib-sidebar-icon-size);right:unset;border:var(--bslib-collapse-toggle-border)}.bslib-sidebar-layout.sidebar-right>.collapse-toggle>.collapse-icon{transform:rotateY(var(--bslib-collapse-toggle-right-transform))}.bslib-sidebar-layout.sidebar-collapsed{--bslib-collapse-toggle-transform: 180deg;--bslib-collapse-toggle-right-transform: 0deg;--bslib-sidebar-vert-border: none;grid-template-columns:0 minmax(0, 1fr)}.bslib-sidebar-layout.sidebar-collapsed.sidebar-right{grid-template-columns:minmax(0, 1fr) 0}.bslib-sidebar-layout.sidebar-collapsed:not(.transitioning)>.sidebar>*{display:none}.bslib-sidebar-layout.sidebar-collapsed>.main{border-radius:inherit}.bslib-sidebar-layout.sidebar-collapsed:not(.sidebar-right)>.main{padding-left:var(--bslib-sidebar-padding-icon)}.bslib-sidebar-layout.sidebar-collapsed.sidebar-right>.main{padding-right:var(--bslib-sidebar-padding-icon)}.bslib-sidebar-layout.sidebar-collapsed>.collapse-toggle{color:var(--bslib-sidebar-main-fg);top:calc(var(--bslib-sidebar-overlap-counter, 0)*(var(--bslib-sidebar-icon-size) + var(--bslib-sidebar-padding)) + var(--bslib-sidebar-icon-size, 1rem)/2);right:calc(-2.5*var(--bslib-sidebar-icon-size) - var(--bs-card-border-width, 1px))}.bslib-sidebar-layout.sidebar-collapsed.sidebar-right>.collapse-toggle{left:calc(-2.5*var(--bslib-sidebar-icon-size) - var(--bs-card-border-width, 1px));right:unset}@media(min-width: 576px){.bslib-sidebar-layout.transitioning>.sidebar>.sidebar-content{display:none}}@media(max-width: 575.98px){.bslib-sidebar-layout[data-bslib-sidebar-open=desktop]{--bslib-sidebar-js-init-collapsed: true}.bslib-sidebar-layout>.sidebar,.bslib-sidebar-layout.sidebar-right>.sidebar{border:none}.bslib-sidebar-layout>.main,.bslib-sidebar-layout.sidebar-right>.main{grid-column:1/3}.bslib-sidebar-layout[data-bslib-sidebar-open=always]{display:block !important}.bslib-sidebar-layout[data-bslib-sidebar-open=always]>.sidebar{max-height:var(--bslib-sidebar-max-height-mobile);overflow-y:auto;border-top:var(--bslib-sidebar-vert-border)}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]){grid-template-columns:100% 0}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]):not(.sidebar-collapsed)>.sidebar{z-index:1}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]):not(.sidebar-collapsed)>.collapse-toggle{z-index:1}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]).sidebar-right{grid-template-columns:0 100%}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]).sidebar-collapsed{grid-template-columns:0 100%}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]).sidebar-collapsed.sidebar-right{grid-template-columns:100% 0}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]):not(.sidebar-right)>.main{padding-left:var(--bslib-sidebar-padding-icon)}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]).sidebar-right>.main{padding-right:var(--bslib-sidebar-padding-icon)}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always])>.main{opacity:0;transition:opacity var(--bslib-sidebar-transition-easing-x) var(--bslib-sidebar-transition-duration)}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]).sidebar-collapsed>.main{opacity:1}}:root{--bslib-value-box-shadow: none;--bslib-value-box-border-width-auto-yes: var(--bslib-value-box-border-width-baseline);--bslib-value-box-border-width-auto-no: 0;--bslib-value-box-border-width-baseline: 1px}.bslib-value-box{border-width:var(--bslib-value-box-border-width-auto-no, var(--bslib-value-box-border-width-baseline));container-name:bslib-value-box;container-type:inline-size}.bslib-value-box.card{box-shadow:var(--bslib-value-box-shadow)}.bslib-value-box.border-auto{border-width:var(--bslib-value-box-border-width-auto-yes, var(--bslib-value-box-border-width-baseline))}.bslib-value-box.default{--bslib-value-box-bg-default: var(--bs-card-bg, #222);--bslib-value-box-border-color-default: var(--bs-card-border-color, rgba(0, 0, 0, 0.175));color:var(--bslib-value-box-color);background-color:var(--bslib-value-box-bg, var(--bslib-value-box-bg-default));border-color:var(--bslib-value-box-border-color, var(--bslib-value-box-border-color-default))}.bslib-value-box .value-box-grid{display:grid;grid-template-areas:"left right";align-items:center;overflow:hidden}.bslib-value-box .value-box-showcase{height:100%;max-height:var(---bslib-value-box-showcase-max-h, 100%)}.bslib-value-box .value-box-showcase,.bslib-value-box .value-box-showcase>.html-fill-item{width:100%}.bslib-value-box[data-full-screen=true] .value-box-showcase{max-height:var(---bslib-value-box-showcase-max-h-fs, 100%)}@media screen and (min-width: 575.98px){@container bslib-value-box (max-width: 300px){.bslib-value-box:not(.showcase-bottom) .value-box-grid{grid-template-columns:1fr !important;grid-template-rows:auto auto;grid-template-areas:"top" "bottom"}.bslib-value-box:not(.showcase-bottom) .value-box-grid .value-box-showcase{grid-area:top !important}.bslib-value-box:not(.showcase-bottom) .value-box-grid .value-box-area{grid-area:bottom !important;justify-content:end}}}.bslib-value-box .value-box-area{justify-content:center;padding:1.5rem 1rem;font-size:.9rem;font-weight:500}.bslib-value-box .value-box-area *{margin-bottom:0;margin-top:0}.bslib-value-box .value-box-title{font-size:1rem;margin-top:0;margin-bottom:.5rem;font-weight:500;line-height:1.2}.bslib-value-box .value-box-title:empty::after{content:" "}.bslib-value-box .value-box-value{font-size:calc(1.29rem + 0.48vw);margin-top:0;margin-bottom:.5rem;font-weight:500;line-height:1.2}@media(min-width: 1200px){.bslib-value-box .value-box-value{font-size:1.65rem}}.bslib-value-box .value-box-value:empty::after{content:" "}.bslib-value-box .value-box-showcase{align-items:center;justify-content:center;margin-top:auto;margin-bottom:auto;padding:1rem}.bslib-value-box .value-box-showcase .bi,.bslib-value-box .value-box-showcase .fa,.bslib-value-box .value-box-showcase .fab,.bslib-value-box .value-box-showcase .fas,.bslib-value-box .value-box-showcase .far{opacity:.85;min-width:50px;max-width:125%}.bslib-value-box .value-box-showcase .bi,.bslib-value-box .value-box-showcase .fa,.bslib-value-box .value-box-showcase .fab,.bslib-value-box .value-box-showcase .fas,.bslib-value-box .value-box-showcase .far{font-size:4rem}.bslib-value-box.showcase-top-right .value-box-grid{grid-template-columns:1fr var(---bslib-value-box-showcase-w, 50%)}.bslib-value-box.showcase-top-right .value-box-grid .value-box-showcase{grid-area:right;margin-left:auto;align-self:start;align-items:end;padding-left:0;padding-bottom:0}.bslib-value-box.showcase-top-right .value-box-grid .value-box-area{grid-area:left;align-self:end}.bslib-value-box.showcase-top-right[data-full-screen=true] .value-box-grid{grid-template-columns:auto var(---bslib-value-box-showcase-w-fs, 1fr)}.bslib-value-box.showcase-top-right[data-full-screen=true] .value-box-grid>div{align-self:center}.bslib-value-box.showcase-top-right:not([data-full-screen=true]) .value-box-showcase{margin-top:0}@container bslib-value-box (max-width: 300px){.bslib-value-box.showcase-top-right:not([data-full-screen=true]) .value-box-grid .value-box-showcase{padding-left:1rem}}.bslib-value-box.showcase-left-center .value-box-grid{grid-template-columns:var(---bslib-value-box-showcase-w, 30%) auto}.bslib-value-box.showcase-left-center[data-full-screen=true] .value-box-grid{grid-template-columns:var(---bslib-value-box-showcase-w-fs, 1fr) auto}.bslib-value-box.showcase-left-center:not([data-fill-screen=true]) .value-box-grid .value-box-showcase{grid-area:left}.bslib-value-box.showcase-left-center:not([data-fill-screen=true]) .value-box-grid .value-box-area{grid-area:right}.bslib-value-box.showcase-bottom .value-box-grid{grid-template-columns:1fr;grid-template-rows:1fr var(---bslib-value-box-showcase-h, auto);grid-template-areas:"top" "bottom";overflow:hidden}.bslib-value-box.showcase-bottom .value-box-grid .value-box-showcase{grid-area:bottom;padding:0;margin:0}.bslib-value-box.showcase-bottom .value-box-grid .value-box-area{grid-area:top}.bslib-value-box.showcase-bottom[data-full-screen=true] .value-box-grid{grid-template-rows:1fr var(---bslib-value-box-showcase-h-fs, 2fr)}.bslib-value-box.showcase-bottom[data-full-screen=true] .value-box-grid .value-box-showcase{padding:1rem}[data-bs-theme=dark] .bslib-value-box{--bslib-value-box-shadow: 0 0.5rem 1rem rgb(0 0 0 / 50%)}.html-fill-container{display:flex;flex-direction:column;min-height:0;min-width:0}.html-fill-container>.html-fill-item{flex:1 1 auto;min-height:0;min-width:0}.html-fill-container>:not(.html-fill-item){flex:0 0 auto}.sidebar-item .chapter-number{color:#fff}.quarto-container{min-height:calc(100vh - 132px)}body.hypothesis-enabled #quarto-header{margin-right:16px}footer.footer .nav-footer,#quarto-header>nav{padding-left:1em;padding-right:1em}footer.footer div.nav-footer p:first-child{margin-top:0}footer.footer div.nav-footer p:last-child{margin-bottom:0}#quarto-content>*{padding-top:14px}#quarto-content>#quarto-sidebar-glass{padding-top:0px}@media(max-width: 991.98px){#quarto-content>*{padding-top:0}#quarto-content .subtitle{padding-top:14px}#quarto-content section:first-of-type h2:first-of-type,#quarto-content section:first-of-type .h2:first-of-type{margin-top:1rem}}.headroom-target,header.headroom{will-change:transform;transition:position 200ms linear;transition:all 200ms linear}header.headroom--pinned{transform:translateY(0%)}header.headroom--unpinned{transform:translateY(-100%)}.navbar-container{width:100%}.navbar-brand{overflow:hidden;text-overflow:ellipsis}.navbar-brand-container{max-width:calc(100% - 115px);min-width:0;display:flex;align-items:center}@media(min-width: 992px){.navbar-brand-container{margin-right:1em}}.navbar-brand.navbar-brand-logo{margin-right:4px;display:inline-flex}.navbar-toggler{flex-basis:content;flex-shrink:0}.navbar .navbar-brand-container{order:2}.navbar .navbar-toggler{order:1}.navbar .navbar-container>.navbar-nav{order:20}.navbar .navbar-container>.navbar-brand-container{margin-left:0 !important;margin-right:0 !important}.navbar .navbar-collapse{order:20}.navbar #quarto-search{order:4;margin-left:auto}.navbar .navbar-toggler{margin-right:.5em}.navbar-logo{max-height:24px;width:auto;padding-right:4px}nav .nav-item:not(.compact){padding-top:1px}nav .nav-link i,nav .dropdown-item i{padding-right:1px}.navbar-expand-lg .navbar-nav .nav-link{padding-left:.6rem;padding-right:.6rem}nav .nav-item.compact .nav-link{padding-left:.5rem;padding-right:.5rem;font-size:1.1rem}.navbar .quarto-navbar-tools{order:3}.navbar .quarto-navbar-tools div.dropdown{display:inline-block}.navbar .quarto-navbar-tools .quarto-navigation-tool{color:#dee2e6}.navbar .quarto-navbar-tools .quarto-navigation-tool:hover{color:#fff}.navbar-nav .dropdown-menu{min-width:220px;font-size:.9rem}.navbar .navbar-nav .nav-link.dropdown-toggle::after{opacity:.75;vertical-align:.175em}.navbar ul.dropdown-menu{padding-top:0;padding-bottom:0}.navbar .dropdown-header{text-transform:uppercase;font-size:.8rem;padding:0 .5rem}.navbar .dropdown-item{padding:.4rem .5rem}.navbar .dropdown-item>i.bi{margin-left:.1rem;margin-right:.25em}.sidebar #quarto-search{margin-top:-1px}.sidebar #quarto-search svg.aa-SubmitIcon{width:16px;height:16px}.sidebar-navigation a{color:inherit}.sidebar-title{margin-top:.25rem;padding-bottom:.5rem;font-size:1.3rem;line-height:1.6rem;visibility:visible}.sidebar-title>a{font-size:inherit;text-decoration:none}.sidebar-title .sidebar-tools-main{margin-top:-6px}@media(max-width: 991.98px){#quarto-sidebar div.sidebar-header{padding-top:.2em}}.sidebar-header-stacked .sidebar-title{margin-top:.6rem}.sidebar-logo{max-width:90%;padding-bottom:.5rem}.sidebar-logo-link{text-decoration:none}.sidebar-navigation li a{text-decoration:none}.sidebar-navigation .quarto-navigation-tool{opacity:.7;font-size:.875rem}#quarto-sidebar>nav>.sidebar-tools-main{margin-left:14px}.sidebar-tools-main{display:inline-flex;margin-left:0px;order:2}.sidebar-tools-main:not(.tools-wide){vertical-align:middle}.sidebar-navigation .quarto-navigation-tool.dropdown-toggle::after{display:none}.sidebar.sidebar-navigation>*{padding-top:1em}.sidebar-item{margin-bottom:.2em;line-height:1rem;margin-top:.4rem}.sidebar-section{padding-left:.5em;padding-bottom:.2em}.sidebar-item .sidebar-item-container{display:flex;justify-content:space-between;cursor:pointer}.sidebar-item-toggle:hover{cursor:pointer}.sidebar-item .sidebar-item-toggle .bi{font-size:.7rem;text-align:center}.sidebar-item .sidebar-item-toggle .bi-chevron-right::before{transition:transform 200ms ease}.sidebar-item .sidebar-item-toggle[aria-expanded=false] .bi-chevron-right::before{transform:none}.sidebar-item .sidebar-item-toggle[aria-expanded=true] .bi-chevron-right::before{transform:rotate(90deg)}.sidebar-item-text{width:100%}.sidebar-navigation .sidebar-divider{margin-left:0;margin-right:0;margin-top:.5rem;margin-bottom:.5rem}@media(max-width: 991.98px){.quarto-secondary-nav{display:block}.quarto-secondary-nav button.quarto-search-button{padding-right:0em;padding-left:2em}.quarto-secondary-nav button.quarto-btn-toggle{margin-left:-0.75rem;margin-right:.15rem}.quarto-secondary-nav nav.quarto-title-breadcrumbs{display:none}.quarto-secondary-nav nav.quarto-page-breadcrumbs{display:flex;align-items:center;padding-right:1em;margin-left:-0.25em}.quarto-secondary-nav nav.quarto-page-breadcrumbs a{text-decoration:none}.quarto-secondary-nav nav.quarto-page-breadcrumbs ol.breadcrumb{margin-bottom:0}}@media(min-width: 992px){.quarto-secondary-nav{display:none}}.quarto-title-breadcrumbs .breadcrumb{margin-bottom:.5em;font-size:.9rem}.quarto-title-breadcrumbs .breadcrumb li:last-of-type a{color:#6c757d}.quarto-secondary-nav .quarto-btn-toggle{color:#adadad}.quarto-secondary-nav[aria-expanded=false] .quarto-btn-toggle .bi-chevron-right::before{transform:none}.quarto-secondary-nav[aria-expanded=true] .quarto-btn-toggle .bi-chevron-right::before{transform:rotate(90deg)}.quarto-secondary-nav .quarto-btn-toggle .bi-chevron-right::before{transition:transform 200ms ease}.quarto-secondary-nav{cursor:pointer}.no-decor{text-decoration:none}.quarto-secondary-nav-title{margin-top:.3em;color:#adadad;padding-top:4px}.quarto-secondary-nav nav.quarto-page-breadcrumbs{color:#adadad}.quarto-secondary-nav nav.quarto-page-breadcrumbs a{color:#adadad}.quarto-secondary-nav nav.quarto-page-breadcrumbs a:hover{color:rgba(26,195,152,.8)}.quarto-secondary-nav nav.quarto-page-breadcrumbs .breadcrumb-item::before{color:#7a7a7a}.breadcrumb-item{line-height:1.2rem}div.sidebar-item-container{color:#adadad}div.sidebar-item-container:hover,div.sidebar-item-container:focus{color:rgba(26,195,152,.8)}div.sidebar-item-container.disabled{color:rgba(173,173,173,.75)}div.sidebar-item-container .active,div.sidebar-item-container .show>.nav-link,div.sidebar-item-container .sidebar-link>code{color:#1ac398}div.sidebar.sidebar-navigation.rollup.quarto-sidebar-toggle-contents,nav.sidebar.sidebar-navigation:not(.rollup){background-color:#222}@media(max-width: 991.98px){.sidebar-navigation .sidebar-item a,.nav-page .nav-page-text,.sidebar-navigation{font-size:1rem}.sidebar-navigation ul.sidebar-section.depth1 .sidebar-section-item{font-size:1.1rem}.sidebar-logo{display:none}.sidebar.sidebar-navigation{position:static;border-bottom:1px solid #434343}.sidebar.sidebar-navigation.collapsing{position:fixed;z-index:1000}.sidebar.sidebar-navigation.show{position:fixed;z-index:1000}.sidebar.sidebar-navigation{min-height:100%}nav.quarto-secondary-nav{background-color:#222;border-bottom:1px solid #434343}.quarto-banner nav.quarto-secondary-nav{background-color:#375a7f;color:#dee2e6;border-top:1px solid #434343}.sidebar .sidebar-footer{visibility:visible;padding-top:1rem;position:inherit}.sidebar-tools-collapse{display:block}}#quarto-sidebar{transition:width .15s ease-in}#quarto-sidebar>*{padding-right:1em}@media(max-width: 991.98px){#quarto-sidebar .sidebar-menu-container{white-space:nowrap;min-width:225px}#quarto-sidebar.show{transition:width .15s ease-out}}@media(min-width: 992px){#quarto-sidebar{display:flex;flex-direction:column}.nav-page .nav-page-text,.sidebar-navigation .sidebar-section .sidebar-item{font-size:.875rem}.sidebar-navigation .sidebar-item{font-size:.925rem}.sidebar.sidebar-navigation{display:block;position:sticky}.sidebar-search{width:100%}.sidebar .sidebar-footer{visibility:visible}}@media(max-width: 991.98px){#quarto-sidebar-glass{position:fixed;top:0;bottom:0;left:0;right:0;background-color:rgba(255,255,255,0);transition:background-color .15s ease-in;z-index:-1}#quarto-sidebar-glass.collapsing{z-index:1000}#quarto-sidebar-glass.show{transition:background-color .15s ease-out;background-color:rgba(102,102,102,.4);z-index:1000}}.sidebar .sidebar-footer{padding:.5rem 1rem;align-self:flex-end;color:#6c757d;width:100%}.quarto-page-breadcrumbs .breadcrumb-item+.breadcrumb-item,.quarto-page-breadcrumbs .breadcrumb-item{padding-right:.33em;padding-left:0}.quarto-page-breadcrumbs .breadcrumb-item::before{padding-right:.33em}.quarto-sidebar-footer{font-size:.875em}.sidebar-section .bi-chevron-right{vertical-align:middle}.sidebar-section .bi-chevron-right::before{font-size:.9em}.notransition{-webkit-transition:none !important;-moz-transition:none !important;-o-transition:none !important;transition:none !important}.btn:focus:not(:focus-visible){box-shadow:none}.page-navigation{display:flex;justify-content:space-between}.nav-page{padding-bottom:.75em}.nav-page .bi{font-size:1.8rem;vertical-align:middle}.nav-page .nav-page-text{padding-left:.25em;padding-right:.25em}.nav-page a{color:#6c757d;text-decoration:none;display:flex;align-items:center}.nav-page a:hover{color:#009670}.nav-footer .toc-actions{padding-bottom:.5em;padding-top:.5em}.nav-footer .toc-actions a,.nav-footer .toc-actions a:hover{text-decoration:none}.nav-footer .toc-actions ul{display:flex;list-style:none}.nav-footer .toc-actions ul :first-child{margin-left:auto}.nav-footer .toc-actions ul :last-child{margin-right:auto}.nav-footer .toc-actions ul li{padding-right:1.5em}.nav-footer .toc-actions ul li i.bi{padding-right:.4em}.nav-footer .toc-actions ul li:last-of-type{padding-right:0}.nav-footer{display:flex;flex-direction:row;flex-wrap:wrap;justify-content:space-between;align-items:baseline;text-align:center;padding-top:.5rem;padding-bottom:.5rem;background-color:#222}body.nav-fixed{padding-top:82px}.nav-footer-contents{color:#6c757d;margin-top:.25rem}.nav-footer{min-height:3.5em;color:#8a8a8a}.nav-footer a{color:#8a8a8a}.nav-footer .nav-footer-left{font-size:.825em}.nav-footer .nav-footer-center{font-size:.825em}.nav-footer .nav-footer-right{font-size:.825em}.nav-footer-left .footer-items,.nav-footer-center .footer-items,.nav-footer-right .footer-items{display:inline-flex;padding-top:.3em;padding-bottom:.3em;margin-bottom:0em}.nav-footer-left .footer-items .nav-link,.nav-footer-center .footer-items .nav-link,.nav-footer-right .footer-items .nav-link{padding-left:.6em;padding-right:.6em}.nav-footer-left{flex:1 1 0px;text-align:left}.nav-footer-right{flex:1 1 0px;text-align:right}.nav-footer-center{flex:1 1 0px;min-height:3em;text-align:center}.nav-footer-center .footer-items{justify-content:center}@media(max-width: 767.98px){.nav-footer-center{margin-top:3em}}.navbar .quarto-reader-toggle.reader .quarto-reader-toggle-btn{background-color:#dee2e6;border-radius:3px}@media(max-width: 991.98px){.quarto-reader-toggle{display:none}}.quarto-reader-toggle.reader.quarto-navigation-tool .quarto-reader-toggle-btn{background-color:#adadad;border-radius:3px}.quarto-reader-toggle .quarto-reader-toggle-btn{display:inline-flex;padding-left:.2em;padding-right:.2em;margin-left:-0.2em;margin-right:-0.2em;text-align:center}.navbar .quarto-reader-toggle:not(.reader) .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(222, 226, 230, 1)" class="bi bi-body-text" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M0 .5A.5.5 0 0 1 .5 0h4a.5.5 0 0 1 0 1h-4A.5.5 0 0 1 0 .5Zm0 2A.5.5 0 0 1 .5 2h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm9 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-9 2A.5.5 0 0 1 .5 4h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm5 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm-12 2A.5.5 0 0 1 .5 6h6a.5.5 0 0 1 0 1h-6a.5.5 0 0 1-.5-.5Zm8 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-8 2A.5.5 0 0 1 .5 8h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm-7 2a.5.5 0 0 1 .5-.5h8a.5.5 0 0 1 0 1h-8a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h4a.5.5 0 0 1 0 1h-4a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h2a.5.5 0 0 1 0 1h-2a.5.5 0 0 1-.5-.5Z"/></svg>')}.navbar .quarto-reader-toggle.reader .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(55, 90, 127, 1)" class="bi bi-body-text" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M0 .5A.5.5 0 0 1 .5 0h4a.5.5 0 0 1 0 1h-4A.5.5 0 0 1 0 .5Zm0 2A.5.5 0 0 1 .5 2h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm9 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-9 2A.5.5 0 0 1 .5 4h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm5 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm-12 2A.5.5 0 0 1 .5 6h6a.5.5 0 0 1 0 1h-6a.5.5 0 0 1-.5-.5Zm8 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-8 2A.5.5 0 0 1 .5 8h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm-7 2a.5.5 0 0 1 .5-.5h8a.5.5 0 0 1 0 1h-8a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h4a.5.5 0 0 1 0 1h-4a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h2a.5.5 0 0 1 0 1h-2a.5.5 0 0 1-.5-.5Z"/></svg>')}.sidebar-navigation .quarto-reader-toggle:not(.reader) .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(173, 173, 173, 1)" class="bi bi-body-text" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M0 .5A.5.5 0 0 1 .5 0h4a.5.5 0 0 1 0 1h-4A.5.5 0 0 1 0 .5Zm0 2A.5.5 0 0 1 .5 2h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm9 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-9 2A.5.5 0 0 1 .5 4h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm5 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm-12 2A.5.5 0 0 1 .5 6h6a.5.5 0 0 1 0 1h-6a.5.5 0 0 1-.5-.5Zm8 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-8 2A.5.5 0 0 1 .5 8h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm-7 2a.5.5 0 0 1 .5-.5h8a.5.5 0 0 1 0 1h-8a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h4a.5.5 0 0 1 0 1h-4a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h2a.5.5 0 0 1 0 1h-2a.5.5 0 0 1-.5-.5Z"/></svg>')}.sidebar-navigation .quarto-reader-toggle.reader .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(34, 34, 34, 1)" class="bi bi-body-text" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M0 .5A.5.5 0 0 1 .5 0h4a.5.5 0 0 1 0 1h-4A.5.5 0 0 1 0 .5Zm0 2A.5.5 0 0 1 .5 2h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm9 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-9 2A.5.5 0 0 1 .5 4h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm5 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm-12 2A.5.5 0 0 1 .5 6h6a.5.5 0 0 1 0 1h-6a.5.5 0 0 1-.5-.5Zm8 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-8 2A.5.5 0 0 1 .5 8h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm-7 2a.5.5 0 0 1 .5-.5h8a.5.5 0 0 1 0 1h-8a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h4a.5.5 0 0 1 0 1h-4a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h2a.5.5 0 0 1 0 1h-2a.5.5 0 0 1-.5-.5Z"/></svg>')}#quarto-back-to-top{display:none;position:fixed;bottom:50px;background-color:#222;border-radius:.25rem;box-shadow:0 .2rem .5rem #6c757d,0 0 .05rem #6c757d;color:#6c757d;text-decoration:none;font-size:.9em;text-align:center;left:50%;padding:.4rem .8rem;transform:translate(-50%, 0)}.aa-DetachedSearchButtonQuery{display:none}.aa-DetachedOverlay ul.aa-List,#quarto-search-results ul.aa-List{list-style:none;padding-left:0}.aa-DetachedOverlay .aa-Panel,#quarto-search-results .aa-Panel{background-color:#222;position:absolute;z-index:2000}#quarto-search-results .aa-Panel{max-width:400px}#quarto-search input{font-size:.925rem}@media(min-width: 992px){.navbar #quarto-search{margin-left:.25rem;order:999}}.navbar.navbar-expand-sm #quarto-search,.navbar.navbar-expand-md #quarto-search{order:999}@media(min-width: 992px){.navbar .quarto-navbar-tools{order:900}}@media(min-width: 992px){.navbar .quarto-navbar-tools.tools-end{margin-left:auto !important}}@media(max-width: 991.98px){#quarto-sidebar .sidebar-search{display:none}}#quarto-sidebar .sidebar-search .aa-Autocomplete{width:100%}.navbar .aa-Autocomplete .aa-Form{width:180px}.navbar #quarto-search.type-overlay .aa-Autocomplete{width:40px}.navbar #quarto-search.type-overlay .aa-Autocomplete .aa-Form{background-color:inherit;border:none}.navbar #quarto-search.type-overlay .aa-Autocomplete .aa-Form:focus-within{box-shadow:none;outline:none}.navbar #quarto-search.type-overlay .aa-Autocomplete .aa-Form .aa-InputWrapper{display:none}.navbar #quarto-search.type-overlay .aa-Autocomplete .aa-Form .aa-InputWrapper:focus-within{display:inherit}.navbar #quarto-search.type-overlay .aa-Autocomplete .aa-Form .aa-Label svg,.navbar #quarto-search.type-overlay .aa-Autocomplete .aa-Form .aa-LoadingIndicator svg{width:26px;height:26px;color:#dee2e6;opacity:1}.navbar #quarto-search.type-overlay .aa-Autocomplete svg.aa-SubmitIcon{width:26px;height:26px;color:#dee2e6;opacity:1}.aa-Autocomplete .aa-Form,.aa-DetachedFormContainer .aa-Form{align-items:center;background-color:#fff;border:1px solid #adb5bd;border-radius:.25rem;color:#2d2d2d;display:flex;line-height:1em;margin:0;position:relative;width:100%}.aa-Autocomplete .aa-Form:focus-within,.aa-DetachedFormContainer .aa-Form:focus-within{box-shadow:rgba(55,90,127,.6) 0 0 0 1px;outline:currentColor none medium}.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix{align-items:center;display:flex;flex-shrink:0;order:1}.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix .aa-Label,.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix .aa-Label,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator{cursor:initial;flex-shrink:0;padding:0;text-align:left}.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix .aa-Label svg,.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator svg,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix .aa-Label svg,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator svg{color:#2d2d2d;opacity:.5}.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix .aa-SubmitButton,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix .aa-SubmitButton{appearance:none;background:none;border:0;margin:0}.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator{align-items:center;display:flex;justify-content:center}.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator[hidden],.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator[hidden]{display:none}.aa-Autocomplete .aa-Form .aa-InputWrapper,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper{order:3;position:relative;width:100%}.aa-Autocomplete .aa-Form .aa-InputWrapper .aa-Input,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input{appearance:none;background:none;border:0;color:#2d2d2d;font:inherit;height:calc(1.5em + .1rem + 2px);padding:0;width:100%}.aa-Autocomplete .aa-Form .aa-InputWrapper .aa-Input::placeholder,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input::placeholder{color:#2d2d2d;opacity:.8}.aa-Autocomplete .aa-Form .aa-InputWrapper .aa-Input:focus,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input:focus{border-color:none;box-shadow:none;outline:none}.aa-Autocomplete .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-decoration,.aa-Autocomplete .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-cancel-button,.aa-Autocomplete .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-results-button,.aa-Autocomplete .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-results-decoration,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-decoration,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-cancel-button,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-results-button,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-results-decoration{display:none}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix{align-items:center;display:flex;order:4}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-ClearButton,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-ClearButton{align-items:center;background:none;border:0;color:#2d2d2d;opacity:.8;cursor:pointer;display:flex;margin:0;width:calc(1.5em + .1rem + 2px)}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-ClearButton:hover,.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-ClearButton:focus,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-ClearButton:hover,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-ClearButton:focus{color:#2d2d2d;opacity:.8}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-ClearButton[hidden],.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-ClearButton[hidden]{display:none}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-ClearButton svg,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-ClearButton svg{width:calc(1.5em + 0.75rem + calc(1px * 2))}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-CopyButton,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-CopyButton{border:none;align-items:center;background:none;color:#2d2d2d;opacity:.4;font-size:.7rem;cursor:pointer;display:none;margin:0;width:calc(1em + .1rem + 2px)}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-CopyButton:hover,.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-CopyButton:focus,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-CopyButton:hover,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-CopyButton:focus{color:#2d2d2d;opacity:.8}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-CopyButton[hidden],.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-CopyButton[hidden]{display:none}.aa-PanelLayout:empty{display:none}.quarto-search-no-results.no-query{display:none}.aa-Source:has(.no-query){display:none}#quarto-search-results .aa-Panel{border:solid #adb5bd 1px}#quarto-search-results .aa-SourceNoResults{width:398px}.aa-DetachedOverlay .aa-Panel,#quarto-search-results .aa-Panel{max-height:65vh;overflow-y:auto;font-size:.925rem}.aa-DetachedOverlay .aa-SourceNoResults,#quarto-search-results .aa-SourceNoResults{height:60px;display:flex;justify-content:center;align-items:center}.aa-DetachedOverlay .search-error,#quarto-search-results .search-error{padding-top:10px;padding-left:20px;padding-right:20px;cursor:default}.aa-DetachedOverlay .search-error .search-error-title,#quarto-search-results .search-error .search-error-title{font-size:1.1rem;margin-bottom:.5rem}.aa-DetachedOverlay .search-error .search-error-title .search-error-icon,#quarto-search-results .search-error .search-error-title .search-error-icon{margin-right:8px}.aa-DetachedOverlay .search-error .search-error-text,#quarto-search-results .search-error .search-error-text{font-weight:300}.aa-DetachedOverlay .search-result-text,#quarto-search-results .search-result-text{font-weight:300;overflow:hidden;text-overflow:ellipsis;display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;line-height:1.2rem;max-height:2.4rem}.aa-DetachedOverlay .aa-SourceHeader .search-result-header,#quarto-search-results .aa-SourceHeader .search-result-header{font-size:.875rem;background-color:#2f2f2f;padding-left:14px;padding-bottom:4px;padding-top:4px}.aa-DetachedOverlay .aa-SourceHeader .search-result-header-no-results,#quarto-search-results .aa-SourceHeader .search-result-header-no-results{display:none}.aa-DetachedOverlay .aa-SourceFooter .algolia-search-logo,#quarto-search-results .aa-SourceFooter .algolia-search-logo{width:110px;opacity:.85;margin:8px;float:right}.aa-DetachedOverlay .search-result-section,#quarto-search-results .search-result-section{font-size:.925em}.aa-DetachedOverlay a.search-result-link,#quarto-search-results a.search-result-link{color:inherit;text-decoration:none}.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item,#quarto-search-results li.aa-Item[aria-selected=true] .search-item{background-color:#375a7f}.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item.search-result-more,.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item .search-result-section,.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item .search-result-text,.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item .search-result-title-container,.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item .search-result-text-container,#quarto-search-results li.aa-Item[aria-selected=true] .search-item.search-result-more,#quarto-search-results li.aa-Item[aria-selected=true] .search-item .search-result-section,#quarto-search-results li.aa-Item[aria-selected=true] .search-item .search-result-text,#quarto-search-results li.aa-Item[aria-selected=true] .search-item .search-result-title-container,#quarto-search-results li.aa-Item[aria-selected=true] .search-item .search-result-text-container{color:#fff;background-color:#375a7f}.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item mark.search-match,.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item .search-match.mark,#quarto-search-results li.aa-Item[aria-selected=true] .search-item mark.search-match,#quarto-search-results li.aa-Item[aria-selected=true] .search-item .search-match.mark{color:#fff;background-color:#2b4663}.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item,#quarto-search-results li.aa-Item[aria-selected=false] .search-item{background-color:#2d2d2d}.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item.search-result-more,.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item .search-result-section,.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item .search-result-text,.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item .search-result-title-container,.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item .search-result-text-container,#quarto-search-results li.aa-Item[aria-selected=false] .search-item.search-result-more,#quarto-search-results li.aa-Item[aria-selected=false] .search-item .search-result-section,#quarto-search-results li.aa-Item[aria-selected=false] .search-item .search-result-text,#quarto-search-results li.aa-Item[aria-selected=false] .search-item .search-result-title-container,#quarto-search-results li.aa-Item[aria-selected=false] .search-item .search-result-text-container{color:#fff}.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item mark.search-match,.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item .search-match.mark,#quarto-search-results li.aa-Item[aria-selected=false] .search-item mark.search-match,#quarto-search-results li.aa-Item[aria-selected=false] .search-item .search-match.mark{color:inherit;background-color:#000}.aa-DetachedOverlay .aa-Item .search-result-doc:not(.document-selectable) .search-result-title-container,#quarto-search-results .aa-Item .search-result-doc:not(.document-selectable) .search-result-title-container{background-color:#2d2d2d;color:#fff}.aa-DetachedOverlay .aa-Item .search-result-doc:not(.document-selectable) .search-result-text-container,#quarto-search-results .aa-Item .search-result-doc:not(.document-selectable) .search-result-text-container{padding-top:0px}.aa-DetachedOverlay li.aa-Item .search-result-doc.document-selectable .search-result-text-container,#quarto-search-results li.aa-Item .search-result-doc.document-selectable .search-result-text-container{margin-top:-4px}.aa-DetachedOverlay .aa-Item,#quarto-search-results .aa-Item{cursor:pointer}.aa-DetachedOverlay .aa-Item .search-item,#quarto-search-results .aa-Item .search-item{border-left:none;border-right:none;border-top:none;background-color:#2d2d2d;border-color:#adb5bd;color:#fff}.aa-DetachedOverlay .aa-Item .search-item p,#quarto-search-results .aa-Item .search-item p{margin-top:0;margin-bottom:0}.aa-DetachedOverlay .aa-Item .search-item i.bi,#quarto-search-results .aa-Item .search-item i.bi{padding-left:8px;padding-right:8px;font-size:1.3em}.aa-DetachedOverlay .aa-Item .search-item .search-result-title,#quarto-search-results .aa-Item .search-item .search-result-title{margin-top:.3em;margin-bottom:0em}.aa-DetachedOverlay .aa-Item .search-item .search-result-crumbs,#quarto-search-results .aa-Item .search-item .search-result-crumbs{white-space:nowrap;text-overflow:ellipsis;font-size:.8em;font-weight:300;margin-right:1em}.aa-DetachedOverlay .aa-Item .search-item .search-result-crumbs:not(.search-result-crumbs-wrap),#quarto-search-results .aa-Item .search-item .search-result-crumbs:not(.search-result-crumbs-wrap){max-width:30%;margin-left:auto;margin-top:.5em;margin-bottom:.1rem}.aa-DetachedOverlay .aa-Item .search-item .search-result-crumbs.search-result-crumbs-wrap,#quarto-search-results .aa-Item .search-item .search-result-crumbs.search-result-crumbs-wrap{flex-basis:100%;margin-top:0em;margin-bottom:.2em;margin-left:37px}.aa-DetachedOverlay .aa-Item .search-result-title-container,#quarto-search-results .aa-Item .search-result-title-container{font-size:1em;display:flex;flex-wrap:wrap;padding:6px 4px 6px 4px}.aa-DetachedOverlay .aa-Item .search-result-text-container,#quarto-search-results .aa-Item .search-result-text-container{padding-bottom:8px;padding-right:8px;margin-left:42px}.aa-DetachedOverlay .aa-Item .search-result-doc-section,.aa-DetachedOverlay .aa-Item .search-result-more,#quarto-search-results .aa-Item .search-result-doc-section,#quarto-search-results .aa-Item .search-result-more{padding-top:8px;padding-bottom:8px;padding-left:44px}.aa-DetachedOverlay .aa-Item .search-result-more,#quarto-search-results .aa-Item .search-result-more{font-size:.8em;font-weight:400}.aa-DetachedOverlay .aa-Item .search-result-doc,#quarto-search-results .aa-Item .search-result-doc{border-top:1px solid #adb5bd}.aa-DetachedSearchButton{background:none;border:none}.aa-DetachedSearchButton .aa-DetachedSearchButtonPlaceholder{display:none}.navbar .aa-DetachedSearchButton .aa-DetachedSearchButtonIcon{color:#dee2e6}.sidebar-tools-collapse #quarto-search,.sidebar-tools-main #quarto-search{display:inline}.sidebar-tools-collapse #quarto-search .aa-Autocomplete,.sidebar-tools-main #quarto-search .aa-Autocomplete{display:inline}.sidebar-tools-collapse #quarto-search .aa-DetachedSearchButton,.sidebar-tools-main #quarto-search .aa-DetachedSearchButton{padding-left:4px;padding-right:4px}.sidebar-tools-collapse #quarto-search .aa-DetachedSearchButton .aa-DetachedSearchButtonIcon,.sidebar-tools-main #quarto-search .aa-DetachedSearchButton .aa-DetachedSearchButtonIcon{color:#adadad}.sidebar-tools-collapse #quarto-search .aa-DetachedSearchButton .aa-DetachedSearchButtonIcon .aa-SubmitIcon,.sidebar-tools-main #quarto-search .aa-DetachedSearchButton .aa-DetachedSearchButtonIcon .aa-SubmitIcon{margin-top:-3px}.aa-DetachedContainer{background:rgba(34,34,34,.65);width:90%;bottom:0;box-shadow:rgba(173,181,189,.6) 0 0 0 1px;outline:currentColor none medium;display:flex;flex-direction:column;left:0;margin:0;overflow:hidden;padding:0;position:fixed;right:0;top:0;z-index:1101}.aa-DetachedContainer::after{height:32px}.aa-DetachedContainer .aa-SourceHeader{margin:var(--aa-spacing-half) 0 var(--aa-spacing-half) 2px}.aa-DetachedContainer .aa-Panel{background-color:#222;border-radius:0;box-shadow:none;flex-grow:1;margin:0;padding:0;position:relative}.aa-DetachedContainer .aa-PanelLayout{bottom:0;box-shadow:none;left:0;margin:0;max-height:none;overflow-y:auto;position:absolute;right:0;top:0;width:100%}.aa-DetachedFormContainer{background-color:#222;border-bottom:1px solid #adb5bd;display:flex;flex-direction:row;justify-content:space-between;margin:0;padding:.5em}.aa-DetachedCancelButton{background:none;font-size:.8em;border:0;border-radius:3px;color:#fff;cursor:pointer;margin:0 0 0 .5em;padding:0 .5em}.aa-DetachedCancelButton:hover,.aa-DetachedCancelButton:focus{box-shadow:rgba(55,90,127,.6) 0 0 0 1px;outline:currentColor none medium}.aa-DetachedContainer--modal{bottom:inherit;height:auto;margin:0 auto;position:absolute;top:100px;border-radius:6px;max-width:850px}@media(max-width: 575.98px){.aa-DetachedContainer--modal{width:100%;top:0px;border-radius:0px;border:none}}.aa-DetachedContainer--modal .aa-PanelLayout{max-height:var(--aa-detached-modal-max-height);padding-bottom:var(--aa-spacing-half);position:static}.aa-Detached{height:100vh;overflow:hidden}.aa-DetachedOverlay{background-color:rgba(255,255,255,.4);position:fixed;left:0;right:0;top:0;margin:0;padding:0;height:100vh;z-index:1100}.quarto-dashboard.nav-fixed.dashboard-sidebar #quarto-content.quarto-dashboard-content{padding:0em}.quarto-dashboard #quarto-content.quarto-dashboard-content{padding:1em}.quarto-dashboard #quarto-content.quarto-dashboard-content>*{padding-top:0}@media(min-width: 576px){.quarto-dashboard{height:100%}}.quarto-dashboard .card.valuebox.bslib-card.bg-primary{background-color:#375a7f !important}.quarto-dashboard .card.valuebox.bslib-card.bg-secondary{background-color:#434343 !important}.quarto-dashboard .card.valuebox.bslib-card.bg-success{background-color:#00bc8c !important}.quarto-dashboard .card.valuebox.bslib-card.bg-info{background-color:#3498db !important}.quarto-dashboard .card.valuebox.bslib-card.bg-warning{background-color:#f39c12 !important}.quarto-dashboard .card.valuebox.bslib-card.bg-danger{background-color:#e74c3c !important}.quarto-dashboard .card.valuebox.bslib-card.bg-light{background-color:#6f6f6f !important}.quarto-dashboard .card.valuebox.bslib-card.bg-dark{background-color:#2d2d2d !important}.quarto-dashboard.dashboard-fill{display:flex;flex-direction:column}.quarto-dashboard #quarto-appendix{display:none}.quarto-dashboard #quarto-header #quarto-dashboard-header{border-top:solid 1px #4673a3;border-bottom:solid 1px #4673a3}.quarto-dashboard #quarto-header #quarto-dashboard-header>nav{padding-left:1em;padding-right:1em}.quarto-dashboard #quarto-header #quarto-dashboard-header>nav .navbar-brand-container{padding-left:0}.quarto-dashboard #quarto-header #quarto-dashboard-header .navbar-toggler{margin-right:0}.quarto-dashboard #quarto-header #quarto-dashboard-header .navbar-toggler-icon{height:1em;width:1em;background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(222, 226, 230)" class="bi bi-menu-button-wide" viewBox="0 0 16 16"><path d="M0 1.5A1.5 1.5 0 0 1 1.5 0h13A1.5 1.5 0 0 1 16 1.5v2A1.5 1.5 0 0 1 14.5 5h-13A1.5 1.5 0 0 1 0 3.5v-2zM1.5 1a.5.5 0 0 0-.5.5v2a.5.5 0 0 0 .5.5h13a.5.5 0 0 0 .5-.5v-2a.5.5 0 0 0-.5-.5h-13z"/><path d="M2 2.5a.5.5 0 0 1 .5-.5h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5zm10.823.323-.396-.396A.25.25 0 0 1 12.604 2h.792a.25.25 0 0 1 .177.427l-.396.396a.25.25 0 0 1-.354 0zM0 8a2 2 0 0 1 2-2h12a2 2 0 0 1 2 2v5a2 2 0 0 1-2 2H2a2 2 0 0 1-2-2V8zm1 3v2a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-2H1zm14-1V8a1 1 0 0 0-1-1H2a1 1 0 0 0-1 1v2h14zM2 8.5a.5.5 0 0 1 .5-.5h9a.5.5 0 0 1 0 1h-9a.5.5 0 0 1-.5-.5zm0 4a.5.5 0 0 1 .5-.5h6a.5.5 0 0 1 0 1h-6a.5.5 0 0 1-.5-.5z"/></svg>')}.quarto-dashboard #quarto-header #quarto-dashboard-header .navbar-brand-container{padding-right:1em}.quarto-dashboard #quarto-header #quarto-dashboard-header .navbar-title{font-size:1.1em}.quarto-dashboard #quarto-header #quarto-dashboard-header .navbar-nav{font-size:.9em}.quarto-dashboard #quarto-dashboard-header .navbar{padding:0}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-container{padding-left:1em}.quarto-dashboard #quarto-dashboard-header .navbar.slim .navbar-brand-container .nav-link,.quarto-dashboard #quarto-dashboard-header .navbar.slim .navbar-nav .nav-link{padding:.7em}.quarto-dashboard #quarto-dashboard-header .navbar .quarto-color-scheme-toggle{order:9}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-toggler{margin-left:.5em;order:10}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-nav .nav-link{padding:.5em;height:100%;display:flex;align-items:center}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-nav .active{background-color:#436e9b}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-brand-container{padding:.5em .5em .5em 0;display:flex;flex-direction:row;margin-right:2em;align-items:center}@media(max-width: 767.98px){.quarto-dashboard #quarto-dashboard-header .navbar .navbar-brand-container{margin-right:auto}}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-collapse{align-self:stretch}@media(min-width: 768px){.quarto-dashboard #quarto-dashboard-header .navbar .navbar-collapse{order:8}}@media(max-width: 767.98px){.quarto-dashboard #quarto-dashboard-header .navbar .navbar-collapse{order:1000;padding-bottom:.5em}}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-collapse .navbar-nav{align-self:stretch}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-title{font-size:1.25em;line-height:1.1em;display:flex;flex-direction:row;flex-wrap:wrap;align-items:baseline}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-title .navbar-title-text{margin-right:.4em}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-title a{text-decoration:none;color:inherit}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-subtitle,.quarto-dashboard #quarto-dashboard-header .navbar .navbar-author{font-size:.9rem;margin-right:.5em}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-author{margin-left:auto}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-logo{max-height:48px;min-height:30px;object-fit:cover;margin-right:1em}.quarto-dashboard #quarto-dashboard-header .navbar .quarto-dashboard-links{order:9;padding-right:1em}.quarto-dashboard #quarto-dashboard-header .navbar .quarto-dashboard-link-text{margin-left:.25em}.quarto-dashboard #quarto-dashboard-header .navbar .quarto-dashboard-link{padding-right:0em;padding-left:.7em;text-decoration:none;color:#dee2e6}.quarto-dashboard .page-layout-custom .tab-content{padding:0;border:none}.quarto-dashboard-img-contain{height:100%;width:100%;object-fit:contain}@media(max-width: 575.98px){.quarto-dashboard .bslib-grid{grid-template-rows:minmax(1em, max-content) !important}.quarto-dashboard .sidebar-content{height:inherit}.quarto-dashboard .page-layout-custom{min-height:100vh}}.quarto-dashboard.dashboard-toolbar>.page-layout-custom,.quarto-dashboard.dashboard-sidebar>.page-layout-custom{padding:0}.quarto-dashboard .quarto-dashboard-content.quarto-dashboard-pages{padding:0}.quarto-dashboard .callout{margin-bottom:0;margin-top:0}.quarto-dashboard .html-fill-container figure{overflow:hidden}.quarto-dashboard bslib-tooltip .rounded-pill{border:solid #6c757d 1px}.quarto-dashboard bslib-tooltip .rounded-pill .svg{fill:#fff}.quarto-dashboard .tabset .dashboard-card-no-title .nav-tabs{margin-left:0;margin-right:auto}.quarto-dashboard .tabset .tab-content{border:none}.quarto-dashboard .tabset .card-header .nav-link[role=tab]{margin-top:-6px;padding-top:6px;padding-bottom:6px}.quarto-dashboard .card.valuebox,.quarto-dashboard .card.bslib-value-box{min-height:3rem}.quarto-dashboard .card.valuebox .card-body,.quarto-dashboard .card.bslib-value-box .card-body{padding:0}.quarto-dashboard .bslib-value-box .value-box-value{font-size:clamp(.1em,15cqw,5em)}.quarto-dashboard .bslib-value-box .value-box-showcase .bi{font-size:clamp(.1em,max(18cqw,5.2cqh),5em);text-align:center;height:1em}.quarto-dashboard .bslib-value-box .value-box-showcase .bi::before{vertical-align:1em}.quarto-dashboard .bslib-value-box .value-box-area{margin-top:auto;margin-bottom:auto}.quarto-dashboard .card figure.quarto-float{display:flex;flex-direction:column;align-items:center}.quarto-dashboard .dashboard-scrolling{padding:1em}.quarto-dashboard .full-height{height:100%}.quarto-dashboard .showcase-bottom .value-box-grid{display:grid;grid-template-columns:1fr;grid-template-rows:1fr auto;grid-template-areas:"top" "bottom"}.quarto-dashboard .showcase-bottom .value-box-grid .value-box-showcase{grid-area:bottom;padding:0;margin:0}.quarto-dashboard .showcase-bottom .value-box-grid .value-box-showcase i.bi{font-size:4rem}.quarto-dashboard .showcase-bottom .value-box-grid .value-box-area{grid-area:top}.quarto-dashboard .tab-content{margin-bottom:0}.quarto-dashboard .bslib-card .bslib-navs-card-title{justify-content:stretch;align-items:end}.quarto-dashboard .card-header{display:flex;flex-wrap:wrap;justify-content:space-between}.quarto-dashboard .card-header .card-title{display:flex;flex-direction:column;justify-content:center;margin-bottom:0}.quarto-dashboard .tabset .card-toolbar{margin-bottom:1em}.quarto-dashboard .bslib-grid>.bslib-sidebar-layout{border:none;gap:var(--bslib-spacer, 1rem)}.quarto-dashboard .bslib-grid>.bslib-sidebar-layout>.main{padding:0}.quarto-dashboard .bslib-grid>.bslib-sidebar-layout>.sidebar{border-radius:.25rem;border:1px solid rgba(0,0,0,.175)}.quarto-dashboard .bslib-grid>.bslib-sidebar-layout>.collapse-toggle{display:none}@media(max-width: 767.98px){.quarto-dashboard .bslib-grid>.bslib-sidebar-layout{grid-template-columns:1fr;grid-template-rows:max-content 1fr}.quarto-dashboard .bslib-grid>.bslib-sidebar-layout>.main{grid-column:1;grid-row:2}.quarto-dashboard .bslib-grid>.bslib-sidebar-layout .sidebar{grid-column:1;grid-row:1}}.quarto-dashboard .sidebar-right .sidebar{padding-left:2.5em}.quarto-dashboard .sidebar-right .collapse-toggle{left:2px}.quarto-dashboard .quarto-dashboard .sidebar-right button.collapse-toggle:not(.transitioning){left:unset}.quarto-dashboard aside.sidebar{padding-left:1em;padding-right:1em;background-color:rgba(52,58,64,.25);color:#fff}.quarto-dashboard .bslib-sidebar-layout>div.main{padding:.7em}.quarto-dashboard .bslib-sidebar-layout button.collapse-toggle{margin-top:.3em}.quarto-dashboard .bslib-sidebar-layout .collapse-toggle{top:0}.quarto-dashboard .bslib-sidebar-layout.sidebar-collapsed:not(.transitioning):not(.sidebar-right) .collapse-toggle{left:2px}.quarto-dashboard .sidebar>section>.h3:first-of-type{margin-top:0em}.quarto-dashboard .sidebar .h3,.quarto-dashboard .sidebar .h4,.quarto-dashboard .sidebar .h5,.quarto-dashboard .sidebar .h6{margin-top:.5em}.quarto-dashboard .sidebar form{flex-direction:column;align-items:start;margin-bottom:1em}.quarto-dashboard .sidebar form div[class*=oi-][class$=-input]{flex-direction:column}.quarto-dashboard .sidebar form[class*=oi-][class$=-toggle]{flex-direction:row-reverse;align-items:center;justify-content:start}.quarto-dashboard .sidebar form input[type=range]{margin-top:.5em;margin-right:.8em;margin-left:1em}.quarto-dashboard .sidebar label{width:fit-content}.quarto-dashboard .sidebar .card-body{margin-bottom:2em}.quarto-dashboard .sidebar .shiny-input-container{margin-bottom:1em}.quarto-dashboard .sidebar .shiny-options-group{margin-top:0}.quarto-dashboard .sidebar .control-label{margin-bottom:.3em}.quarto-dashboard .card .card-body .quarto-layout-row{align-items:stretch}.quarto-dashboard .toolbar{font-size:.9em;display:flex;flex-direction:row;border-top:solid 1px silver;padding:1em;flex-wrap:wrap;background-color:rgba(52,58,64,.25)}.quarto-dashboard .toolbar .cell-output-display{display:flex}.quarto-dashboard .toolbar .shiny-input-container{padding-bottom:.5em;margin-bottom:.5em;width:inherit}.quarto-dashboard .toolbar .shiny-input-container>.checkbox:first-child{margin-top:6px}.quarto-dashboard .toolbar>*:last-child{margin-right:0}.quarto-dashboard .toolbar>*>*{margin-right:1em;align-items:baseline}.quarto-dashboard .toolbar>*>*>a{text-decoration:none;margin-top:auto;margin-bottom:auto}.quarto-dashboard .toolbar .shiny-input-container{padding-bottom:0;margin-bottom:0}.quarto-dashboard .toolbar .shiny-input-container>*{flex-shrink:0;flex-grow:0}.quarto-dashboard .toolbar .form-group.shiny-input-container:not([role=group])>label{margin-bottom:0}.quarto-dashboard .toolbar .shiny-input-container.no-baseline{align-items:start;padding-top:6px}.quarto-dashboard .toolbar .shiny-input-container{display:flex;align-items:baseline}.quarto-dashboard .toolbar .shiny-input-container label{padding-right:.4em}.quarto-dashboard .toolbar .shiny-input-container .bslib-input-switch{margin-top:6px}.quarto-dashboard .toolbar input[type=text]{line-height:1;width:inherit}.quarto-dashboard .toolbar .input-daterange{width:inherit}.quarto-dashboard .toolbar .input-daterange input[type=text]{height:2.4em;width:10em}.quarto-dashboard .toolbar .input-daterange .input-group-addon{height:auto;padding:0;margin-left:-5px !important;margin-right:-5px}.quarto-dashboard .toolbar .input-daterange .input-group-addon .input-group-text{padding-top:0;padding-bottom:0;height:100%}.quarto-dashboard .toolbar span.irs.irs--shiny{width:10em}.quarto-dashboard .toolbar span.irs.irs--shiny .irs-line{top:9px}.quarto-dashboard .toolbar span.irs.irs--shiny .irs-min,.quarto-dashboard .toolbar span.irs.irs--shiny .irs-max,.quarto-dashboard .toolbar span.irs.irs--shiny .irs-from,.quarto-dashboard .toolbar span.irs.irs--shiny .irs-to,.quarto-dashboard .toolbar span.irs.irs--shiny .irs-single{top:20px}.quarto-dashboard .toolbar span.irs.irs--shiny .irs-bar{top:8px}.quarto-dashboard .toolbar span.irs.irs--shiny .irs-handle{top:0px}.quarto-dashboard .toolbar .shiny-input-checkboxgroup>label{margin-top:6px}.quarto-dashboard .toolbar .shiny-input-checkboxgroup>.shiny-options-group{margin-top:0;align-items:baseline}.quarto-dashboard .toolbar .shiny-input-radiogroup>label{margin-top:6px}.quarto-dashboard .toolbar .shiny-input-radiogroup>.shiny-options-group{align-items:baseline;margin-top:0}.quarto-dashboard .toolbar .shiny-input-radiogroup>.shiny-options-group>.radio{margin-right:.3em}.quarto-dashboard .toolbar .form-select{padding-top:.2em;padding-bottom:.2em}.quarto-dashboard .toolbar .shiny-input-select{min-width:6em}.quarto-dashboard .toolbar div.checkbox{margin-bottom:0px}.quarto-dashboard .toolbar>.checkbox:first-child{margin-top:6px}.quarto-dashboard .toolbar form{width:fit-content}.quarto-dashboard .toolbar form label{padding-top:.2em;padding-bottom:.2em;width:fit-content}.quarto-dashboard .toolbar form input[type=date]{width:fit-content}.quarto-dashboard .toolbar form input[type=color]{width:3em}.quarto-dashboard .toolbar form button{padding:.4em}.quarto-dashboard .toolbar form select{width:fit-content}.quarto-dashboard .toolbar>*{font-size:.9em;flex-grow:0}.quarto-dashboard .toolbar .shiny-input-container label{margin-bottom:1px}.quarto-dashboard .toolbar-bottom{margin-top:1em;margin-bottom:0 !important;order:2}.quarto-dashboard .quarto-dashboard-content>.dashboard-toolbar-container>.toolbar-content>.tab-content>.tab-pane>*:not(.bslib-sidebar-layout){padding:1em}.quarto-dashboard .quarto-dashboard-content>.dashboard-toolbar-container>.toolbar-content>*:not(.tab-content){padding:1em}.quarto-dashboard .quarto-dashboard-content>.tab-content>.dashboard-page>.dashboard-toolbar-container>.toolbar-content,.quarto-dashboard .quarto-dashboard-content>.tab-content>.dashboard-page:not(.dashboard-sidebar-container)>*:not(.dashboard-toolbar-container){padding:1em}.quarto-dashboard .toolbar-content{padding:0}.quarto-dashboard .quarto-dashboard-content.quarto-dashboard-pages .tab-pane>.dashboard-toolbar-container .toolbar{border-radius:0;margin-bottom:0}.quarto-dashboard .dashboard-toolbar-container.toolbar-toplevel .toolbar{border-bottom:1px solid rgba(0,0,0,.175)}.quarto-dashboard .dashboard-toolbar-container.toolbar-toplevel .toolbar-bottom{margin-top:0}.quarto-dashboard .dashboard-toolbar-container:not(.toolbar-toplevel) .toolbar{margin-bottom:1em;border-top:none;border-radius:.25rem;border:1px solid rgba(0,0,0,.175)}.quarto-dashboard .vega-embed.has-actions details{width:1.7em;height:2em;position:absolute !important;top:0;right:0}.quarto-dashboard .dashboard-toolbar-container{padding:0}.quarto-dashboard .card .card-header p:last-child,.quarto-dashboard .card .card-footer p:last-child{margin-bottom:0}.quarto-dashboard .card .card-body>.h4:first-child{margin-top:0}.quarto-dashboard .card .card-body{z-index:4}@media(max-width: 767.98px){.quarto-dashboard .card .card-body .itables div.dataTables_wrapper div.dataTables_length,.quarto-dashboard .card .card-body .itables div.dataTables_wrapper div.dataTables_info,.quarto-dashboard .card .card-body .itables div.dataTables_wrapper div.dataTables_paginate{text-align:initial}.quarto-dashboard .card .card-body .itables div.dataTables_wrapper div.dataTables_filter{text-align:right}.quarto-dashboard .card .card-body .itables div.dataTables_wrapper div.dataTables_paginate ul.pagination{justify-content:initial}}.quarto-dashboard .card .card-body .itables .dataTables_wrapper{display:flex;flex-wrap:wrap;justify-content:space-between;align-items:center;padding-top:0}.quarto-dashboard .card .card-body .itables .dataTables_wrapper table{flex-shrink:0}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dt-buttons{margin-bottom:.5em;margin-left:auto;width:fit-content;float:right}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dt-buttons.btn-group{background:#222;border:none}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dt-buttons .btn-secondary{background-color:#222;background-image:none;border:solid #dee2e6 1px;padding:.2em .7em}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dt-buttons .btn span{font-size:.8em;color:#fff}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_info{margin-left:.5em;margin-bottom:.5em;padding-top:0}@media(min-width: 768px){.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_info{font-size:.875em}}@media(max-width: 767.98px){.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_info{font-size:.8em}}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_filter{margin-bottom:.5em;font-size:.875em}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_filter input[type=search]{padding:1px 5px 1px 5px;font-size:.875em}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_length{flex-basis:1 1 50%;margin-bottom:.5em;font-size:.875em}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_length select{padding:.4em 3em .4em .5em;font-size:.875em;margin-left:.2em;margin-right:.2em}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_paginate{flex-shrink:0}@media(min-width: 768px){.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_paginate{margin-left:auto}}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_paginate ul.pagination .paginate_button .page-link{font-size:.8em}.quarto-dashboard .card .card-footer{font-size:.9em}.quarto-dashboard .card .card-toolbar{display:flex;flex-grow:1;flex-direction:row;width:100%;flex-wrap:wrap}.quarto-dashboard .card .card-toolbar>*{font-size:.8em;flex-grow:0}.quarto-dashboard .card .card-toolbar>.card-title{font-size:1em;flex-grow:1;align-self:flex-start;margin-top:.1em}.quarto-dashboard .card .card-toolbar .cell-output-display{display:flex}.quarto-dashboard .card .card-toolbar .shiny-input-container{padding-bottom:.5em;margin-bottom:.5em;width:inherit}.quarto-dashboard .card .card-toolbar .shiny-input-container>.checkbox:first-child{margin-top:6px}.quarto-dashboard .card .card-toolbar>*:last-child{margin-right:0}.quarto-dashboard .card .card-toolbar>*>*{margin-right:1em;align-items:baseline}.quarto-dashboard .card .card-toolbar>*>*>a{text-decoration:none;margin-top:auto;margin-bottom:auto}.quarto-dashboard .card .card-toolbar form{width:fit-content}.quarto-dashboard .card .card-toolbar form label{padding-top:.2em;padding-bottom:.2em;width:fit-content}.quarto-dashboard .card .card-toolbar form input[type=date]{width:fit-content}.quarto-dashboard .card .card-toolbar form input[type=color]{width:3em}.quarto-dashboard .card .card-toolbar form button{padding:.4em}.quarto-dashboard .card .card-toolbar form select{width:fit-content}.quarto-dashboard .card .card-toolbar .cell-output-display{display:flex}.quarto-dashboard .card .card-toolbar .shiny-input-container{padding-bottom:.5em;margin-bottom:.5em;width:inherit}.quarto-dashboard .card .card-toolbar .shiny-input-container>.checkbox:first-child{margin-top:6px}.quarto-dashboard .card .card-toolbar>*:last-child{margin-right:0}.quarto-dashboard .card .card-toolbar>*>*{margin-right:1em;align-items:baseline}.quarto-dashboard .card .card-toolbar>*>*>a{text-decoration:none;margin-top:auto;margin-bottom:auto}.quarto-dashboard .card .card-toolbar .shiny-input-container{padding-bottom:0;margin-bottom:0}.quarto-dashboard .card .card-toolbar .shiny-input-container>*{flex-shrink:0;flex-grow:0}.quarto-dashboard .card .card-toolbar .form-group.shiny-input-container:not([role=group])>label{margin-bottom:0}.quarto-dashboard .card .card-toolbar .shiny-input-container.no-baseline{align-items:start;padding-top:6px}.quarto-dashboard .card .card-toolbar .shiny-input-container{display:flex;align-items:baseline}.quarto-dashboard .card .card-toolbar .shiny-input-container label{padding-right:.4em}.quarto-dashboard .card .card-toolbar .shiny-input-container .bslib-input-switch{margin-top:6px}.quarto-dashboard .card .card-toolbar input[type=text]{line-height:1;width:inherit}.quarto-dashboard .card .card-toolbar .input-daterange{width:inherit}.quarto-dashboard .card .card-toolbar .input-daterange input[type=text]{height:2.4em;width:10em}.quarto-dashboard .card .card-toolbar .input-daterange .input-group-addon{height:auto;padding:0;margin-left:-5px !important;margin-right:-5px}.quarto-dashboard .card .card-toolbar .input-daterange .input-group-addon .input-group-text{padding-top:0;padding-bottom:0;height:100%}.quarto-dashboard .card .card-toolbar span.irs.irs--shiny{width:10em}.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-line{top:9px}.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-min,.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-max,.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-from,.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-to,.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-single{top:20px}.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-bar{top:8px}.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-handle{top:0px}.quarto-dashboard .card .card-toolbar .shiny-input-checkboxgroup>label{margin-top:6px}.quarto-dashboard .card .card-toolbar .shiny-input-checkboxgroup>.shiny-options-group{margin-top:0;align-items:baseline}.quarto-dashboard .card .card-toolbar .shiny-input-radiogroup>label{margin-top:6px}.quarto-dashboard .card .card-toolbar .shiny-input-radiogroup>.shiny-options-group{align-items:baseline;margin-top:0}.quarto-dashboard .card .card-toolbar .shiny-input-radiogroup>.shiny-options-group>.radio{margin-right:.3em}.quarto-dashboard .card .card-toolbar .form-select{padding-top:.2em;padding-bottom:.2em}.quarto-dashboard .card .card-toolbar .shiny-input-select{min-width:6em}.quarto-dashboard .card .card-toolbar div.checkbox{margin-bottom:0px}.quarto-dashboard .card .card-toolbar>.checkbox:first-child{margin-top:6px}.quarto-dashboard .card-body>table>thead{border-top:none}.quarto-dashboard .card-body>.table>:not(caption)>*>*{background-color:#2d2d2d}.tableFloatingHeaderOriginal{background-color:#2d2d2d;position:sticky !important;top:0 !important}.dashboard-data-table{margin-top:-1px}.quarto-listing{padding-bottom:1em}.listing-pagination{padding-top:.5em}ul.pagination{float:right;padding-left:8px;padding-top:.5em}ul.pagination li{padding-right:.75em}ul.pagination li.disabled a,ul.pagination li.active a{color:#fff;text-decoration:none}ul.pagination li:last-of-type{padding-right:0}.listing-actions-group{display:flex}.listing-actions-group .form-select,.listing-actions-group .form-control{background-color:#222;color:#fff}.quarto-listing-filter{margin-bottom:1em;width:200px;margin-left:auto}.quarto-listing-sort{margin-bottom:1em;margin-right:auto;width:auto}.quarto-listing-sort .input-group-text{font-size:.8em}.input-group-text{border-right:none}.quarto-listing-sort select.form-select{font-size:.8em}.listing-no-matching{text-align:center;padding-top:2em;padding-bottom:3em;font-size:1em}#quarto-margin-sidebar .quarto-listing-category{padding-top:0;font-size:1rem}#quarto-margin-sidebar .quarto-listing-category-title{cursor:pointer;font-weight:600;font-size:1rem}.quarto-listing-category .category{cursor:pointer}.quarto-listing-category .category.active{font-weight:600}.quarto-listing-category.category-cloud{display:flex;flex-wrap:wrap;align-items:baseline}.quarto-listing-category.category-cloud .category{padding-right:5px}.quarto-listing-category.category-cloud .category-cloud-1{font-size:.75em}.quarto-listing-category.category-cloud .category-cloud-2{font-size:.95em}.quarto-listing-category.category-cloud .category-cloud-3{font-size:1.15em}.quarto-listing-category.category-cloud .category-cloud-4{font-size:1.35em}.quarto-listing-category.category-cloud .category-cloud-5{font-size:1.55em}.quarto-listing-category.category-cloud .category-cloud-6{font-size:1.75em}.quarto-listing-category.category-cloud .category-cloud-7{font-size:1.95em}.quarto-listing-category.category-cloud .category-cloud-8{font-size:2.15em}.quarto-listing-category.category-cloud .category-cloud-9{font-size:2.35em}.quarto-listing-category.category-cloud .category-cloud-10{font-size:2.55em}.quarto-listing-cols-1{grid-template-columns:repeat(1, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-1{grid-template-columns:repeat(1, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-1{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-2{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-2{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-2{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-3{grid-template-columns:repeat(3, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-3{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-3{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-4{grid-template-columns:repeat(4, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-4{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-4{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-5{grid-template-columns:repeat(5, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-5{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-5{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-6{grid-template-columns:repeat(6, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-6{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-6{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-7{grid-template-columns:repeat(7, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-7{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-7{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-8{grid-template-columns:repeat(8, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-8{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-8{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-9{grid-template-columns:repeat(9, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-9{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-9{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-10{grid-template-columns:repeat(10, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-10{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-10{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-11{grid-template-columns:repeat(11, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-11{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-11{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-12{grid-template-columns:repeat(12, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-12{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-12{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-grid{gap:1.5em}.quarto-grid-item.borderless{border:none}.quarto-grid-item.borderless .listing-categories .listing-category:last-of-type,.quarto-grid-item.borderless .listing-categories .listing-category:first-of-type{padding-left:0}.quarto-grid-item.borderless .listing-categories .listing-category{border:0}.quarto-grid-link{text-decoration:none;color:inherit}.quarto-grid-link:hover{text-decoration:none;color:inherit}.quarto-grid-item h5.title,.quarto-grid-item .title.h5{margin-top:0;margin-bottom:0}.quarto-grid-item .card-footer{display:flex;justify-content:space-between;font-size:.8em}.quarto-grid-item .card-footer p{margin-bottom:0}.quarto-grid-item p.card-img-top{margin-bottom:0}.quarto-grid-item p.card-img-top>img{object-fit:cover}.quarto-grid-item .card-other-values{margin-top:.5em;font-size:.8em}.quarto-grid-item .card-other-values tr{margin-bottom:.5em}.quarto-grid-item .card-other-values tr>td:first-of-type{font-weight:600;padding-right:1em;padding-left:1em;vertical-align:top}.quarto-grid-item div.post-contents{display:flex;flex-direction:column;text-decoration:none;height:100%}.quarto-grid-item .listing-item-img-placeholder{background-color:rgba(52,58,64,.25);flex-shrink:0}.quarto-grid-item .card-attribution{padding-top:1em;display:flex;gap:1em;text-transform:uppercase;color:#6c757d;font-weight:500;flex-grow:10;align-items:flex-end}.quarto-grid-item .description{padding-bottom:1em}.quarto-grid-item .card-attribution .date{align-self:flex-end}.quarto-grid-item .card-attribution.justify{justify-content:space-between}.quarto-grid-item .card-attribution.start{justify-content:flex-start}.quarto-grid-item .card-attribution.end{justify-content:flex-end}.quarto-grid-item .card-title{margin-bottom:.1em}.quarto-grid-item .card-subtitle{padding-top:.25em}.quarto-grid-item .card-text{font-size:.9em}.quarto-grid-item .listing-reading-time{padding-bottom:.25em}.quarto-grid-item .card-text-small{font-size:.8em}.quarto-grid-item .card-subtitle.subtitle{font-size:.9em;font-weight:600;padding-bottom:.5em}.quarto-grid-item .listing-categories{display:flex;flex-wrap:wrap;padding-bottom:5px}.quarto-grid-item .listing-categories .listing-category{color:#6c757d;border:solid #6c757d 1px;border-radius:.25rem;text-transform:uppercase;font-size:.65em;padding-left:.5em;padding-right:.5em;padding-top:.15em;padding-bottom:.15em;cursor:pointer;margin-right:4px;margin-bottom:4px}.quarto-grid-item.card-right{text-align:right}.quarto-grid-item.card-right .listing-categories{justify-content:flex-end}.quarto-grid-item.card-left{text-align:left}.quarto-grid-item.card-center{text-align:center}.quarto-grid-item.card-center .listing-description{text-align:justify}.quarto-grid-item.card-center .listing-categories{justify-content:center}table.quarto-listing-table td.image{padding:0px}table.quarto-listing-table td.image img{width:100%;max-width:50px;object-fit:contain}table.quarto-listing-table a{text-decoration:none;word-break:keep-all}table.quarto-listing-table th a{color:inherit}table.quarto-listing-table th a.asc:after{margin-bottom:-2px;margin-left:5px;display:inline-block;height:1rem;width:1rem;background-repeat:no-repeat;background-size:1rem 1rem;background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-sort-up" viewBox="0 0 16 16"><path d="M3.5 12.5a.5.5 0 0 1-1 0V3.707L1.354 4.854a.5.5 0 1 1-.708-.708l2-1.999.007-.007a.498.498 0 0 1 .7.006l2 2a.5.5 0 1 1-.707.708L3.5 3.707V12.5zm3.5-9a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5zM7.5 6a.5.5 0 0 0 0 1h5a.5.5 0 0 0 0-1h-5zm0 3a.5.5 0 0 0 0 1h3a.5.5 0 0 0 0-1h-3zm0 3a.5.5 0 0 0 0 1h1a.5.5 0 0 0 0-1h-1z"/></svg>');content:""}table.quarto-listing-table th a.desc:after{margin-bottom:-2px;margin-left:5px;display:inline-block;height:1rem;width:1rem;background-repeat:no-repeat;background-size:1rem 1rem;background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-sort-down" viewBox="0 0 16 16"><path d="M3.5 2.5a.5.5 0 0 0-1 0v8.793l-1.146-1.147a.5.5 0 0 0-.708.708l2 1.999.007.007a.497.497 0 0 0 .7-.006l2-2a.5.5 0 0 0-.707-.708L3.5 11.293V2.5zm3.5 1a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5zM7.5 6a.5.5 0 0 0 0 1h5a.5.5 0 0 0 0-1h-5zm0 3a.5.5 0 0 0 0 1h3a.5.5 0 0 0 0-1h-3zm0 3a.5.5 0 0 0 0 1h1a.5.5 0 0 0 0-1h-1z"/></svg>');content:""}table.quarto-listing-table.table-hover td{cursor:pointer}.quarto-post.image-left{flex-direction:row}.quarto-post.image-right{flex-direction:row-reverse}@media(max-width: 767.98px){.quarto-post.image-right,.quarto-post.image-left{gap:0em;flex-direction:column}.quarto-post .metadata{padding-bottom:1em;order:2}.quarto-post .body{order:1}.quarto-post .thumbnail{order:3}}.list.quarto-listing-default div:last-of-type{border-bottom:none}@media(min-width: 992px){.quarto-listing-container-default{margin-right:2em}}div.quarto-post{display:flex;gap:2em;margin-bottom:1.5em;border-bottom:1px solid #dee2e6}@media(max-width: 767.98px){div.quarto-post{padding-bottom:1em}}div.quarto-post .metadata{flex-basis:20%;flex-grow:0;margin-top:.2em;flex-shrink:10}div.quarto-post .thumbnail{flex-basis:30%;flex-grow:0;flex-shrink:0}div.quarto-post .thumbnail img{margin-top:.4em;width:100%;object-fit:cover}div.quarto-post .body{flex-basis:45%;flex-grow:1;flex-shrink:0}div.quarto-post .body h3.listing-title,div.quarto-post .body .listing-title.h3{margin-top:0px;margin-bottom:0px;border-bottom:none}div.quarto-post .body .listing-subtitle{font-size:.875em;margin-bottom:.5em;margin-top:.2em}div.quarto-post .body .description{font-size:.9em}div.quarto-post .body pre code{white-space:pre-wrap}div.quarto-post a{color:#fff;text-decoration:none}div.quarto-post .metadata{display:flex;flex-direction:column;font-size:.8em;font-family:Lato,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol";flex-basis:33%}div.quarto-post .listing-categories{display:flex;flex-wrap:wrap;padding-bottom:5px}div.quarto-post .listing-categories .listing-category{color:#6c757d;border:solid #6c757d 1px;border-radius:.25rem;text-transform:uppercase;font-size:.65em;padding-left:.5em;padding-right:.5em;padding-top:.15em;padding-bottom:.15em;cursor:pointer;margin-right:4px;margin-bottom:4px}div.quarto-post .listing-description{margin-bottom:.5em}div.quarto-about-jolla{display:flex !important;flex-direction:column;align-items:center;margin-top:10%;padding-bottom:1em}div.quarto-about-jolla .about-image{object-fit:cover;margin-left:auto;margin-right:auto;margin-bottom:1.5em}div.quarto-about-jolla img.round{border-radius:50%}div.quarto-about-jolla img.rounded{border-radius:10px}div.quarto-about-jolla .quarto-title h1.title,div.quarto-about-jolla .quarto-title .title.h1{text-align:center}div.quarto-about-jolla .quarto-title .description{text-align:center}div.quarto-about-jolla h2,div.quarto-about-jolla .h2{border-bottom:none}div.quarto-about-jolla .about-sep{width:60%}div.quarto-about-jolla main{text-align:center}div.quarto-about-jolla .about-links{display:flex}@media(min-width: 992px){div.quarto-about-jolla .about-links{flex-direction:row;column-gap:.8em;row-gap:15px;flex-wrap:wrap}}@media(max-width: 991.98px){div.quarto-about-jolla .about-links{flex-direction:column;row-gap:1em;width:100%;padding-bottom:1.5em}}div.quarto-about-jolla .about-link{color:#fff;text-decoration:none;border:solid 1px}@media(min-width: 992px){div.quarto-about-jolla .about-link{font-size:.8em;padding:.25em .5em;border-radius:4px}}@media(max-width: 991.98px){div.quarto-about-jolla .about-link{font-size:1.1em;padding:.5em .5em;text-align:center;border-radius:6px}}div.quarto-about-jolla .about-link:hover{color:#00bc8c}div.quarto-about-jolla .about-link i.bi{margin-right:.15em}div.quarto-about-solana{display:flex !important;flex-direction:column;padding-top:3em !important;padding-bottom:1em}div.quarto-about-solana .about-entity{display:flex !important;align-items:start;justify-content:space-between}@media(min-width: 992px){div.quarto-about-solana .about-entity{flex-direction:row}}@media(max-width: 991.98px){div.quarto-about-solana .about-entity{flex-direction:column-reverse;align-items:center;text-align:center}}div.quarto-about-solana .about-entity .entity-contents{display:flex;flex-direction:column}@media(max-width: 767.98px){div.quarto-about-solana .about-entity .entity-contents{width:100%}}div.quarto-about-solana .about-entity .about-image{object-fit:cover}@media(max-width: 991.98px){div.quarto-about-solana .about-entity .about-image{margin-bottom:1.5em}}div.quarto-about-solana .about-entity img.round{border-radius:50%}div.quarto-about-solana .about-entity img.rounded{border-radius:10px}div.quarto-about-solana .about-entity .about-links{display:flex;justify-content:left;padding-bottom:1.2em}@media(min-width: 992px){div.quarto-about-solana .about-entity .about-links{flex-direction:row;column-gap:.8em;row-gap:15px;flex-wrap:wrap}}@media(max-width: 991.98px){div.quarto-about-solana .about-entity .about-links{flex-direction:column;row-gap:1em;width:100%;padding-bottom:1.5em}}div.quarto-about-solana .about-entity .about-link{color:#fff;text-decoration:none;border:solid 1px}@media(min-width: 992px){div.quarto-about-solana .about-entity .about-link{font-size:.8em;padding:.25em .5em;border-radius:4px}}@media(max-width: 991.98px){div.quarto-about-solana .about-entity .about-link{font-size:1.1em;padding:.5em .5em;text-align:center;border-radius:6px}}div.quarto-about-solana .about-entity .about-link:hover{color:#00bc8c}div.quarto-about-solana .about-entity .about-link i.bi{margin-right:.15em}div.quarto-about-solana .about-contents{padding-right:1.5em;flex-basis:0;flex-grow:1}div.quarto-about-solana .about-contents main.content{margin-top:0}div.quarto-about-solana .about-contents h2,div.quarto-about-solana .about-contents .h2{border-bottom:none}div.quarto-about-trestles{display:flex !important;flex-direction:row;padding-top:3em !important;padding-bottom:1em}@media(max-width: 991.98px){div.quarto-about-trestles{flex-direction:column;padding-top:0em !important}}div.quarto-about-trestles .about-entity{display:flex !important;flex-direction:column;align-items:center;text-align:center;padding-right:1em}@media(min-width: 992px){div.quarto-about-trestles .about-entity{flex:0 0 42%}}div.quarto-about-trestles .about-entity .about-image{object-fit:cover;margin-bottom:1.5em}div.quarto-about-trestles .about-entity img.round{border-radius:50%}div.quarto-about-trestles .about-entity img.rounded{border-radius:10px}div.quarto-about-trestles .about-entity .about-links{display:flex;justify-content:center}@media(min-width: 992px){div.quarto-about-trestles .about-entity .about-links{flex-direction:row;column-gap:.8em;row-gap:15px;flex-wrap:wrap}}@media(max-width: 991.98px){div.quarto-about-trestles .about-entity .about-links{flex-direction:column;row-gap:1em;width:100%;padding-bottom:1.5em}}div.quarto-about-trestles .about-entity .about-link{color:#fff;text-decoration:none;border:solid 1px}@media(min-width: 992px){div.quarto-about-trestles .about-entity .about-link{font-size:.8em;padding:.25em .5em;border-radius:4px}}@media(max-width: 991.98px){div.quarto-about-trestles .about-entity .about-link{font-size:1.1em;padding:.5em .5em;text-align:center;border-radius:6px}}div.quarto-about-trestles .about-entity .about-link:hover{color:#00bc8c}div.quarto-about-trestles .about-entity .about-link i.bi{margin-right:.15em}div.quarto-about-trestles .about-contents{flex-basis:0;flex-grow:1}div.quarto-about-trestles .about-contents h2,div.quarto-about-trestles .about-contents .h2{border-bottom:none}@media(min-width: 992px){div.quarto-about-trestles .about-contents{border-left:solid 1px #dee2e6;padding-left:1.5em}}div.quarto-about-trestles .about-contents main.content{margin-top:0}div.quarto-about-marquee{padding-bottom:1em}div.quarto-about-marquee .about-contents{display:flex;flex-direction:column}div.quarto-about-marquee .about-image{max-height:550px;margin-bottom:1.5em;object-fit:cover}div.quarto-about-marquee img.round{border-radius:50%}div.quarto-about-marquee img.rounded{border-radius:10px}div.quarto-about-marquee h2,div.quarto-about-marquee .h2{border-bottom:none}div.quarto-about-marquee .about-links{display:flex;justify-content:center;padding-top:1.5em}@media(min-width: 992px){div.quarto-about-marquee .about-links{flex-direction:row;column-gap:.8em;row-gap:15px;flex-wrap:wrap}}@media(max-width: 991.98px){div.quarto-about-marquee .about-links{flex-direction:column;row-gap:1em;width:100%;padding-bottom:1.5em}}div.quarto-about-marquee .about-link{color:#fff;text-decoration:none;border:solid 1px}@media(min-width: 992px){div.quarto-about-marquee .about-link{font-size:.8em;padding:.25em .5em;border-radius:4px}}@media(max-width: 991.98px){div.quarto-about-marquee .about-link{font-size:1.1em;padding:.5em .5em;text-align:center;border-radius:6px}}div.quarto-about-marquee .about-link:hover{color:#00bc8c}div.quarto-about-marquee .about-link i.bi{margin-right:.15em}@media(min-width: 992px){div.quarto-about-marquee .about-link{border:none}}div.quarto-about-broadside{display:flex;flex-direction:column;padding-bottom:1em}div.quarto-about-broadside .about-main{display:flex !important;padding-top:0 !important}@media(min-width: 992px){div.quarto-about-broadside .about-main{flex-direction:row;align-items:flex-start}}@media(max-width: 991.98px){div.quarto-about-broadside .about-main{flex-direction:column}}@media(max-width: 991.98px){div.quarto-about-broadside .about-main .about-entity{flex-shrink:0;width:100%;height:450px;margin-bottom:1.5em;background-size:cover;background-repeat:no-repeat}}@media(min-width: 992px){div.quarto-about-broadside .about-main .about-entity{flex:0 10 50%;margin-right:1.5em;width:100%;height:100%;background-size:100%;background-repeat:no-repeat}}div.quarto-about-broadside .about-main .about-contents{padding-top:14px;flex:0 0 50%}div.quarto-about-broadside h2,div.quarto-about-broadside .h2{border-bottom:none}div.quarto-about-broadside .about-sep{margin-top:1.5em;width:60%;align-self:center}div.quarto-about-broadside .about-links{display:flex;justify-content:center;column-gap:20px;padding-top:1.5em}@media(min-width: 992px){div.quarto-about-broadside .about-links{flex-direction:row;column-gap:.8em;row-gap:15px;flex-wrap:wrap}}@media(max-width: 991.98px){div.quarto-about-broadside .about-links{flex-direction:column;row-gap:1em;width:100%;padding-bottom:1.5em}}div.quarto-about-broadside .about-link{color:#fff;text-decoration:none;border:solid 1px}@media(min-width: 992px){div.quarto-about-broadside .about-link{font-size:.8em;padding:.25em .5em;border-radius:4px}}@media(max-width: 991.98px){div.quarto-about-broadside .about-link{font-size:1.1em;padding:.5em .5em;text-align:center;border-radius:6px}}div.quarto-about-broadside .about-link:hover{color:#00bc8c}div.quarto-about-broadside .about-link i.bi{margin-right:.15em}@media(min-width: 992px){div.quarto-about-broadside .about-link{border:none}}.tippy-box[data-theme~=quarto]{background-color:#222;border:solid 1px #dee2e6;border-radius:.25rem;color:#fff;font-size:.875rem}.tippy-box[data-theme~=quarto]>.tippy-backdrop{background-color:#222}.tippy-box[data-theme~=quarto]>.tippy-arrow:after,.tippy-box[data-theme~=quarto]>.tippy-svg-arrow:after{content:"";position:absolute;z-index:-1}.tippy-box[data-theme~=quarto]>.tippy-arrow:after{border-color:rgba(0,0,0,0);border-style:solid}.tippy-box[data-placement^=top]>.tippy-arrow:before{bottom:-6px}.tippy-box[data-placement^=bottom]>.tippy-arrow:before{top:-6px}.tippy-box[data-placement^=right]>.tippy-arrow:before{left:-6px}.tippy-box[data-placement^=left]>.tippy-arrow:before{right:-6px}.tippy-box[data-theme~=quarto][data-placement^=top]>.tippy-arrow:before{border-top-color:#222}.tippy-box[data-theme~=quarto][data-placement^=top]>.tippy-arrow:after{border-top-color:#dee2e6;border-width:7px 7px 0;top:17px;left:1px}.tippy-box[data-theme~=quarto][data-placement^=top]>.tippy-svg-arrow>svg{top:16px}.tippy-box[data-theme~=quarto][data-placement^=top]>.tippy-svg-arrow:after{top:17px}.tippy-box[data-theme~=quarto][data-placement^=bottom]>.tippy-arrow:before{border-bottom-color:#222;bottom:16px}.tippy-box[data-theme~=quarto][data-placement^=bottom]>.tippy-arrow:after{border-bottom-color:#dee2e6;border-width:0 7px 7px;bottom:17px;left:1px}.tippy-box[data-theme~=quarto][data-placement^=bottom]>.tippy-svg-arrow>svg{bottom:15px}.tippy-box[data-theme~=quarto][data-placement^=bottom]>.tippy-svg-arrow:after{bottom:17px}.tippy-box[data-theme~=quarto][data-placement^=left]>.tippy-arrow:before{border-left-color:#222}.tippy-box[data-theme~=quarto][data-placement^=left]>.tippy-arrow:after{border-left-color:#dee2e6;border-width:7px 0 7px 7px;left:17px;top:1px}.tippy-box[data-theme~=quarto][data-placement^=left]>.tippy-svg-arrow>svg{left:11px}.tippy-box[data-theme~=quarto][data-placement^=left]>.tippy-svg-arrow:after{left:12px}.tippy-box[data-theme~=quarto][data-placement^=right]>.tippy-arrow:before{border-right-color:#222;right:16px}.tippy-box[data-theme~=quarto][data-placement^=right]>.tippy-arrow:after{border-width:7px 7px 7px 0;right:17px;top:1px;border-right-color:#dee2e6}.tippy-box[data-theme~=quarto][data-placement^=right]>.tippy-svg-arrow>svg{right:11px}.tippy-box[data-theme~=quarto][data-placement^=right]>.tippy-svg-arrow:after{right:12px}.tippy-box[data-theme~=quarto]>.tippy-svg-arrow{fill:#fff}.tippy-box[data-theme~=quarto]>.tippy-svg-arrow:after{background-image:url(data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iNiIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBkPSJNMCA2czEuNzk2LS4wMTMgNC42Ny0zLjYxNUM1Ljg1MS45IDYuOTMuMDA2IDggMGMxLjA3LS4wMDYgMi4xNDguODg3IDMuMzQzIDIuMzg1QzE0LjIzMyA2LjAwNSAxNiA2IDE2IDZIMHoiIGZpbGw9InJnYmEoMCwgOCwgMTYsIDAuMikiLz48L3N2Zz4=);background-size:16px 6px;width:16px;height:6px}.top-right{position:absolute;top:1em;right:1em}.visually-hidden{border:0;clip:rect(0 0 0 0);height:auto;margin:0;overflow:hidden;padding:0;position:absolute;width:1px;white-space:nowrap}.hidden{display:none !important}.zindex-bottom{z-index:-1 !important}figure.figure{display:block}.quarto-layout-panel{margin-bottom:1em}.quarto-layout-panel>figure{width:100%}.quarto-layout-panel>figure>figcaption,.quarto-layout-panel>.panel-caption{margin-top:10pt}.quarto-layout-panel>.table-caption{margin-top:0px}.table-caption p{margin-bottom:.5em}.quarto-layout-row{display:flex;flex-direction:row;align-items:flex-start}.quarto-layout-valign-top{align-items:flex-start}.quarto-layout-valign-bottom{align-items:flex-end}.quarto-layout-valign-center{align-items:center}.quarto-layout-cell{position:relative;margin-right:20px}.quarto-layout-cell:last-child{margin-right:0}.quarto-layout-cell figure,.quarto-layout-cell>p{margin:.2em}.quarto-layout-cell img{max-width:100%}.quarto-layout-cell .html-widget{width:100% !important}.quarto-layout-cell div figure p{margin:0}.quarto-layout-cell figure{display:block;margin-inline-start:0;margin-inline-end:0}.quarto-layout-cell table{display:inline-table}.quarto-layout-cell-subref figcaption,figure .quarto-layout-row figure figcaption{text-align:center;font-style:italic}.quarto-figure{position:relative;margin-bottom:1em}.quarto-figure>figure{width:100%;margin-bottom:0}.quarto-figure-left>figure>p,.quarto-figure-left>figure>div{text-align:left}.quarto-figure-center>figure>p,.quarto-figure-center>figure>div{text-align:center}.quarto-figure-right>figure>p,.quarto-figure-right>figure>div{text-align:right}.quarto-figure>figure>div.cell-annotation,.quarto-figure>figure>div code{text-align:left}figure>p:empty{display:none}figure>p:first-child{margin-top:0;margin-bottom:0}figure>figcaption.quarto-float-caption-bottom{margin-bottom:.5em}figure>figcaption.quarto-float-caption-top{margin-top:.5em}div[id^=tbl-]{position:relative}.quarto-figure>.anchorjs-link{position:absolute;top:.6em;right:.5em}div[id^=tbl-]>.anchorjs-link{position:absolute;top:.7em;right:.3em}.quarto-figure:hover>.anchorjs-link,div[id^=tbl-]:hover>.anchorjs-link,h2:hover>.anchorjs-link,.h2:hover>.anchorjs-link,h3:hover>.anchorjs-link,.h3:hover>.anchorjs-link,h4:hover>.anchorjs-link,.h4:hover>.anchorjs-link,h5:hover>.anchorjs-link,.h5:hover>.anchorjs-link,h6:hover>.anchorjs-link,.h6:hover>.anchorjs-link,.reveal-anchorjs-link>.anchorjs-link{opacity:1}#title-block-header{margin-block-end:1rem;position:relative;margin-top:-1px}#title-block-header .abstract{margin-block-start:1rem}#title-block-header .abstract .abstract-title{font-weight:600}#title-block-header a{text-decoration:none}#title-block-header .author,#title-block-header .date,#title-block-header .doi{margin-block-end:.2rem}#title-block-header .quarto-title-block>div{display:flex}#title-block-header .quarto-title-block>div>h1,#title-block-header .quarto-title-block>div>.h1{flex-grow:1}#title-block-header .quarto-title-block>div>button{flex-shrink:0;height:2.25rem;margin-top:0}@media(min-width: 992px){#title-block-header .quarto-title-block>div>button{margin-top:5px}}tr.header>th>p:last-of-type{margin-bottom:0px}table,table.table{margin-top:.5rem;margin-bottom:.5rem}caption,.table-caption{padding-top:.5rem;padding-bottom:.5rem;text-align:center}figure.quarto-float-tbl figcaption.quarto-float-caption-top{margin-top:.5rem;margin-bottom:.25rem;text-align:center}figure.quarto-float-tbl figcaption.quarto-float-caption-bottom{padding-top:.25rem;margin-bottom:.5rem;text-align:center}.utterances{max-width:none;margin-left:-8px}iframe{margin-bottom:1em}details{margin-bottom:1em}details[show]{margin-bottom:0}details>summary{color:#6c757d}details>summary>p:only-child{display:inline}pre.sourceCode,code.sourceCode{position:relative}p code:not(.sourceCode){white-space:pre-wrap}code{white-space:pre}@media print{code{white-space:pre-wrap}}pre>code{display:block}pre>code.sourceCode{white-space:pre}pre>code.sourceCode>span>a:first-child::before{text-decoration:none}pre.code-overflow-wrap>code.sourceCode{white-space:pre-wrap}pre.code-overflow-scroll>code.sourceCode{white-space:pre}code a:any-link{color:inherit;text-decoration:none}code a:hover{color:inherit;text-decoration:underline}ul.task-list{padding-left:1em}[data-tippy-root]{display:inline-block}.tippy-content .footnote-back{display:none}.footnote-back{margin-left:.2em}.tippy-content{overflow-x:auto}.quarto-embedded-source-code{display:none}.quarto-unresolved-ref{font-weight:600}.quarto-cover-image{max-width:35%;float:right;margin-left:30px}.cell-output-display .widget-subarea{margin-bottom:1em}.cell-output-display:not(.no-overflow-x),.knitsql-table:not(.no-overflow-x){overflow-x:auto}.panel-input{margin-bottom:1em}.panel-input>div,.panel-input>div>div{display:inline-block;vertical-align:top;padding-right:12px}.panel-input>p:last-child{margin-bottom:0}.layout-sidebar{margin-bottom:1em}.layout-sidebar .tab-content{border:none}.tab-content>.page-columns.active{display:grid}div.sourceCode>iframe{width:100%;height:300px;margin-bottom:-0.5em}a{text-underline-offset:3px}div.ansi-escaped-output{font-family:monospace;display:block}/*!
 *
 * ansi colors from IPython notebook's
 *
 * we also add `bright-[color]-` synonyms for the `-[color]-intense` classes since
 * that seems to be what ansi_up emits
 *
-*/.ansi-black-fg{color:#3e424d}.ansi-black-bg{background-color:#3e424d}.ansi-black-intense-black,.ansi-bright-black-fg{color:#282c36}.ansi-black-intense-black,.ansi-bright-black-bg{background-color:#282c36}.ansi-red-fg{color:#e75c58}.ansi-red-bg{background-color:#e75c58}.ansi-red-intense-red,.ansi-bright-red-fg{color:#b22b31}.ansi-red-intense-red,.ansi-bright-red-bg{background-color:#b22b31}.ansi-green-fg{color:#00a250}.ansi-green-bg{background-color:#00a250}.ansi-green-intense-green,.ansi-bright-green-fg{color:#007427}.ansi-green-intense-green,.ansi-bright-green-bg{background-color:#007427}.ansi-yellow-fg{color:#ddb62b}.ansi-yellow-bg{background-color:#ddb62b}.ansi-yellow-intense-yellow,.ansi-bright-yellow-fg{color:#b27d12}.ansi-yellow-intense-yellow,.ansi-bright-yellow-bg{background-color:#b27d12}.ansi-blue-fg{color:#208ffb}.ansi-blue-bg{background-color:#208ffb}.ansi-blue-intense-blue,.ansi-bright-blue-fg{color:#0065ca}.ansi-blue-intense-blue,.ansi-bright-blue-bg{background-color:#0065ca}.ansi-magenta-fg{color:#d160c4}.ansi-magenta-bg{background-color:#d160c4}.ansi-magenta-intense-magenta,.ansi-bright-magenta-fg{color:#a03196}.ansi-magenta-intense-magenta,.ansi-bright-magenta-bg{background-color:#a03196}.ansi-cyan-fg{color:#60c6c8}.ansi-cyan-bg{background-color:#60c6c8}.ansi-cyan-intense-cyan,.ansi-bright-cyan-fg{color:#258f8f}.ansi-cyan-intense-cyan,.ansi-bright-cyan-bg{background-color:#258f8f}.ansi-white-fg{color:#c5c1b4}.ansi-white-bg{background-color:#c5c1b4}.ansi-white-intense-white,.ansi-bright-white-fg{color:#a1a6b2}.ansi-white-intense-white,.ansi-bright-white-bg{background-color:#a1a6b2}.ansi-default-inverse-fg{color:#fff}.ansi-default-inverse-bg{background-color:#000}.ansi-bold{font-weight:bold}.ansi-underline{text-decoration:underline}:root{--quarto-body-bg: #222;--quarto-body-color: #fff;--quarto-text-muted: #6c757d;--quarto-border-color: #434343;--quarto-border-width: 1px;--quarto-border-radius: 0.25rem}table.gt_table{color:var(--quarto-body-color);font-size:1em;width:100%;background-color:rgba(0,0,0,0);border-top-width:inherit;border-bottom-width:inherit;border-color:var(--quarto-border-color)}table.gt_table th.gt_column_spanner_outer{color:var(--quarto-body-color);background-color:rgba(0,0,0,0);border-top-width:inherit;border-bottom-width:inherit;border-color:var(--quarto-border-color)}table.gt_table th.gt_col_heading{color:var(--quarto-body-color);font-weight:bold;background-color:rgba(0,0,0,0)}table.gt_table thead.gt_col_headings{border-bottom:1px solid currentColor;border-top-width:inherit;border-top-color:var(--quarto-border-color)}table.gt_table thead.gt_col_headings:not(:first-child){border-top-width:1px;border-top-color:var(--quarto-border-color)}table.gt_table td.gt_row{border-bottom-width:1px;border-bottom-color:var(--quarto-border-color);border-top-width:0px}table.gt_table tbody.gt_table_body{border-top-width:1px;border-bottom-width:1px;border-bottom-color:var(--quarto-border-color);border-top-color:currentColor}div.columns{display:initial;gap:initial}div.column{display:inline-block;overflow-x:initial;vertical-align:top;width:50%}.code-annotation-tip-content{word-wrap:break-word}.code-annotation-container-hidden{display:none !important}dl.code-annotation-container-grid{display:grid;grid-template-columns:min-content auto}dl.code-annotation-container-grid dt{grid-column:1}dl.code-annotation-container-grid dd{grid-column:2}pre.sourceCode.code-annotation-code{padding-right:0}code.sourceCode .code-annotation-anchor{z-index:100;position:relative;float:right;background-color:rgba(0,0,0,0)}input[type=checkbox]{margin-right:.5ch}:root{--mermaid-bg-color: #222;--mermaid-edge-color: #434343;--mermaid-node-fg-color: #fff;--mermaid-fg-color: #fff;--mermaid-fg-color--lighter: white;--mermaid-fg-color--lightest: white;--mermaid-font-family: Lato, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica Neue, Arial, sans-serif, Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol;--mermaid-label-bg-color: #222;--mermaid-label-fg-color: #375a7f;--mermaid-node-bg-color: rgba(55, 90, 127, 0.1);--mermaid-node-fg-color: #fff}@media print{:root{font-size:11pt}#quarto-sidebar,#TOC,.nav-page{display:none}.page-columns .content{grid-column-start:page-start}.fixed-top{position:relative}.panel-caption,.figure-caption,figcaption{color:#666}}.code-copy-button{position:absolute;top:0;right:0;border:0;margin-top:5px;margin-right:5px;background-color:rgba(0,0,0,0);z-index:3}.code-copy-button:focus{outline:none}.code-copy-button-tooltip{font-size:.75em}pre.sourceCode:hover>.code-copy-button>.bi::before{display:inline-block;height:1rem;width:1rem;content:"";vertical-align:-0.125em;background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(106, 115, 125)" viewBox="0 0 16 16"><path d="M4 1.5H3a2 2 0 0 0-2 2V14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V3.5a2 2 0 0 0-2-2h-1v1h1a1 1 0 0 1 1 1V14a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V3.5a1 1 0 0 1 1-1h1v-1z"/><path d="M9.5 1a.5.5 0 0 1 .5.5v1a.5.5 0 0 1-.5.5h-3a.5.5 0 0 1-.5-.5v-1a.5.5 0 0 1 .5-.5h3zm-3-1A1.5 1.5 0 0 0 5 1.5v1A1.5 1.5 0 0 0 6.5 4h3A1.5 1.5 0 0 0 11 2.5v-1A1.5 1.5 0 0 0 9.5 0h-3z"/></svg>');background-repeat:no-repeat;background-size:1rem 1rem}pre.sourceCode:hover>.code-copy-button-checked>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(106, 115, 125)" viewBox="0 0 16 16"><path d="M13.854 3.646a.5.5 0 0 1 0 .708l-7 7a.5.5 0 0 1-.708 0l-3.5-3.5a.5.5 0 1 1 .708-.708L6.5 10.293l6.646-6.647a.5.5 0 0 1 .708 0z"/></svg>')}pre.sourceCode:hover>.code-copy-button:hover>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(179, 146, 240)" viewBox="0 0 16 16"><path d="M4 1.5H3a2 2 0 0 0-2 2V14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V3.5a2 2 0 0 0-2-2h-1v1h1a1 1 0 0 1 1 1V14a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V3.5a1 1 0 0 1 1-1h1v-1z"/><path d="M9.5 1a.5.5 0 0 1 .5.5v1a.5.5 0 0 1-.5.5h-3a.5.5 0 0 1-.5-.5v-1a.5.5 0 0 1 .5-.5h3zm-3-1A1.5 1.5 0 0 0 5 1.5v1A1.5 1.5 0 0 0 6.5 4h3A1.5 1.5 0 0 0 11 2.5v-1A1.5 1.5 0 0 0 9.5 0h-3z"/></svg>')}pre.sourceCode:hover>.code-copy-button-checked:hover>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(179, 146, 240)"  viewBox="0 0 16 16"><path d="M13.854 3.646a.5.5 0 0 1 0 .708l-7 7a.5.5 0 0 1-.708 0l-3.5-3.5a.5.5 0 1 1 .708-.708L6.5 10.293l6.646-6.647a.5.5 0 0 1 .708 0z"/></svg>')}main ol ol,main ul ul,main ol ul,main ul ol{margin-bottom:1em}ul>li:not(:has(>p))>ul,ol>li:not(:has(>p))>ul,ul>li:not(:has(>p))>ol,ol>li:not(:has(>p))>ol{margin-bottom:0}ul>li:not(:has(>p))>ul>li:has(>p),ol>li:not(:has(>p))>ul>li:has(>p),ul>li:not(:has(>p))>ol>li:has(>p),ol>li:not(:has(>p))>ol>li:has(>p){margin-top:1rem}body{margin:0}main.page-columns>header>h1.title,main.page-columns>header>.title.h1{margin-bottom:0}@media(min-width: 992px){body .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start page-start-inset] 35px [body-start-outset] 35px [body-start] 1.5em [body-content-start] minmax(500px, calc(850px - 3em)) [body-content-end] 1.5em [body-end] 35px [body-end-outset] minmax(75px, 145px) [page-end-inset] 35px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.fullcontent:not(.floating):not(.docked) .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start page-start-inset] 35px [body-start-outset] 35px [body-start] 1.5em [body-content-start] minmax(500px, calc(850px - 3em)) [body-content-end] 1.5em [body-end] 35px [body-end-outset] 35px [page-end-inset page-end] 5fr [screen-end-inset] 1.5em}body.slimcontent:not(.floating):not(.docked) .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start page-start-inset] 35px [body-start-outset] 35px [body-start] 1.5em [body-content-start] minmax(500px, calc(850px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(0px, 200px) [page-end-inset] 35px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.listing:not(.floating):not(.docked) .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start] minmax(50px, 100px) [page-start-inset] 50px [body-start-outset] 50px [body-start] 1.5em [body-content-start] minmax(500px, calc(850px - 3em)) [body-content-end] 3em [body-end] 50px [body-end-outset] minmax(0px, 250px) [page-end-inset] minmax(50px, 100px) [page-end] 1fr [screen-end-inset] 1.5em [screen-end]}body:not(.floating):not(.docked) .page-columns.toc-left{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] 35px [page-start-inset] minmax(0px, 175px) [body-start-outset] 35px [body-start] 1.5em [body-content-start] minmax(450px, calc(800px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(0px, 200px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body:not(.floating):not(.docked) .page-columns.toc-left .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] 35px [page-start-inset] minmax(0px, 175px) [body-start-outset] 35px [body-start] 1.5em [body-content-start] minmax(450px, calc(800px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(0px, 200px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.floating .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] minmax(25px, 50px) [page-start-inset] minmax(50px, 150px) [body-start-outset] minmax(25px, 50px) [body-start] 1.5em [body-content-start] minmax(500px, calc(800px - 3em)) [body-content-end] 1.5em [body-end] minmax(25px, 50px) [body-end-outset] minmax(50px, 150px) [page-end-inset] minmax(25px, 50px) [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.docked .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start] minmax(50px, 100px) [page-start-inset] 50px [body-start-outset] 50px [body-start] 1.5em [body-content-start] minmax(500px, calc(1000px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(50px, 100px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.docked.fullcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start] minmax(50px, 100px) [page-start-inset] 50px [body-start-outset] 50px [body-start] 1.5em [body-content-start] minmax(500px, calc(1000px - 3em)) [body-content-end] 1.5em [body-end body-end-outset page-end-inset page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.floating.fullcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] 50px [page-start-inset] minmax(50px, 150px) [body-start-outset] 50px [body-start] 1.5em [body-content-start] minmax(500px, calc(800px - 3em)) [body-content-end] 1.5em [body-end body-end-outset page-end-inset page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.docked.slimcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start] minmax(50px, 100px) [page-start-inset] 50px [body-start-outset] 50px [body-start] 1.5em [body-content-start] minmax(450px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(0px, 200px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.docked.listing .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start] minmax(50px, 100px) [page-start-inset] 50px [body-start-outset] 50px [body-start] 1.5em [body-content-start] minmax(500px, calc(1000px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(0px, 200px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.floating.slimcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] 50px [page-start-inset] minmax(50px, 150px) [body-start-outset] 50px [body-start] 1.5em [body-content-start] minmax(450px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(50px, 150px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.floating.listing .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] minmax(25px, 50px) [page-start-inset] minmax(50px, 150px) [body-start-outset] minmax(25px, 50px) [body-start] 1.5em [body-content-start] minmax(500px, calc(800px - 3em)) [body-content-end] 1.5em [body-end] minmax(25px, 50px) [body-end-outset] minmax(50px, 150px) [page-end-inset] minmax(25px, 50px) [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}}@media(max-width: 991.98px){body .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset] 5fr [body-start] 1.5em [body-content-start] minmax(500px, calc(800px - 3em)) [body-content-end] 1.5em [body-end] 35px [body-end-outset] minmax(75px, 145px) [page-end-inset] 35px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.fullcontent:not(.floating):not(.docked) .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset] 5fr [body-start] 1.5em [body-content-start] minmax(500px, calc(800px - 3em)) [body-content-end] 1.5em [body-end body-end-outset page-end-inset page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.slimcontent:not(.floating):not(.docked) .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset] 5fr [body-start] 1.5em [body-content-start] minmax(500px, calc(800px - 3em)) [body-content-end] 1.5em [body-end] 35px [body-end-outset] minmax(75px, 145px) [page-end-inset] 35px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.listing:not(.floating):not(.docked) .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset] 5fr [body-start] 1.5em [body-content-start] minmax(500px, calc(1250px - 3em)) [body-content-end body-end body-end-outset page-end-inset page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body:not(.floating):not(.docked) .page-columns.toc-left{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] 35px [page-start-inset] minmax(0px, 145px) [body-start-outset] 35px [body-start] 1.5em [body-content-start] minmax(450px, calc(800px - 3em)) [body-content-end] 1.5em [body-end body-end-outset page-end-inset page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body:not(.floating):not(.docked) .page-columns.toc-left .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] 35px [page-start-inset] minmax(0px, 145px) [body-start-outset] 35px [body-start] 1.5em [body-content-start] minmax(450px, calc(800px - 3em)) [body-content-end] 1.5em [body-end body-end-outset page-end-inset page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.floating .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start page-start-inset body-start-outset body-start] 1.5em [body-content-start] minmax(500px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(75px, 150px) [page-end-inset] 25px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.docked .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset body-start body-content-start] minmax(500px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(25px, 50px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.docked.fullcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset body-start body-content-start] minmax(500px, calc(1000px - 3em)) [body-content-end] 1.5em [body-end body-end-outset page-end-inset page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.floating.fullcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start page-start-inset body-start-outset body-start] 1em [body-content-start] minmax(500px, calc(800px - 3em)) [body-content-end] 1.5em [body-end body-end-outset page-end-inset page-end] 4fr [screen-end-inset] 1.5em [screen-end]}body.docked.slimcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset body-start body-content-start] minmax(500px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(25px, 50px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.docked.listing .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset body-start body-content-start] minmax(500px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(25px, 50px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.floating.slimcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start page-start-inset body-start-outset body-start] 1em [body-content-start] minmax(500px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 35px [body-end-outset] minmax(75px, 145px) [page-end-inset] 35px [page-end] 4fr [screen-end-inset] 1.5em [screen-end]}body.floating.listing .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start page-start-inset body-start-outset body-start] 1em [body-content-start] minmax(500px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(75px, 150px) [page-end-inset] 25px [page-end] 4fr [screen-end-inset] 1.5em [screen-end]}}@media(max-width: 767.98px){body .page-columns,body.fullcontent:not(.floating):not(.docked) .page-columns,body.slimcontent:not(.floating):not(.docked) .page-columns,body.docked .page-columns,body.docked.slimcontent .page-columns,body.docked.fullcontent .page-columns,body.floating .page-columns,body.floating.slimcontent .page-columns,body.floating.fullcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset body-start body-content-start] minmax(0px, 1fr) [body-content-end body-end body-end-outset page-end-inset page-end screen-end-inset] 1.5em [screen-end]}body:not(.floating):not(.docked) .page-columns.toc-left{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset body-start body-content-start] minmax(0px, 1fr) [body-content-end body-end body-end-outset page-end-inset page-end screen-end-inset] 1.5em [screen-end]}body:not(.floating):not(.docked) .page-columns.toc-left .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset body-start body-content-start] minmax(0px, 1fr) [body-content-end body-end body-end-outset page-end-inset page-end screen-end-inset] 1.5em [screen-end]}nav[role=doc-toc]{display:none}}body,.page-row-navigation{grid-template-rows:[page-top] max-content [contents-top] max-content [contents-bottom] max-content [page-bottom]}.page-rows-contents{grid-template-rows:[content-top] minmax(max-content, 1fr) [content-bottom] minmax(60px, max-content) [page-bottom]}.page-full{grid-column:screen-start/screen-end !important}.page-columns>*{grid-column:body-content-start/body-content-end}.page-columns.column-page>*{grid-column:page-start/page-end}.page-columns.column-page-left .page-columns.page-full>*,.page-columns.column-page-left>*{grid-column:page-start/body-content-end}.page-columns.column-page-right .page-columns.page-full>*,.page-columns.column-page-right>*{grid-column:body-content-start/page-end}.page-rows{grid-auto-rows:auto}.header{grid-column:screen-start/screen-end;grid-row:page-top/contents-top}#quarto-content{padding:0;grid-column:screen-start/screen-end;grid-row:contents-top/contents-bottom}body.floating .sidebar.sidebar-navigation{grid-column:page-start/body-start;grid-row:content-top/page-bottom}body.docked .sidebar.sidebar-navigation{grid-column:screen-start/body-start;grid-row:content-top/page-bottom}.sidebar.toc-left{grid-column:page-start/body-start;grid-row:content-top/page-bottom}.sidebar.margin-sidebar{grid-column:body-end/page-end;grid-row:content-top/page-bottom}.page-columns .content{grid-column:body-content-start/body-content-end;grid-row:content-top/content-bottom;align-content:flex-start}.page-columns .page-navigation{grid-column:body-content-start/body-content-end;grid-row:content-bottom/page-bottom}.page-columns .footer{grid-column:screen-start/screen-end;grid-row:contents-bottom/page-bottom}.page-columns .column-body{grid-column:body-content-start/body-content-end}.page-columns .column-body-fullbleed{grid-column:body-start/body-end}.page-columns .column-body-outset{grid-column:body-start-outset/body-end-outset;z-index:998;opacity:.999}.page-columns .column-body-outset table{background:#222}.page-columns .column-body-outset-left{grid-column:body-start-outset/body-content-end;z-index:998;opacity:.999}.page-columns .column-body-outset-left table{background:#222}.page-columns .column-body-outset-right{grid-column:body-content-start/body-end-outset;z-index:998;opacity:.999}.page-columns .column-body-outset-right table{background:#222}.page-columns .column-page{grid-column:page-start/page-end;z-index:998;opacity:.999}.page-columns .column-page table{background:#222}.page-columns .column-page-inset{grid-column:page-start-inset/page-end-inset;z-index:998;opacity:.999}.page-columns .column-page-inset table{background:#222}.page-columns .column-page-inset-left{grid-column:page-start-inset/body-content-end;z-index:998;opacity:.999}.page-columns .column-page-inset-left table{background:#222}.page-columns .column-page-inset-right{grid-column:body-content-start/page-end-inset;z-index:998;opacity:.999}.page-columns .column-page-inset-right figcaption table{background:#222}.page-columns .column-page-left{grid-column:page-start/body-content-end;z-index:998;opacity:.999}.page-columns .column-page-left table{background:#222}.page-columns .column-page-right{grid-column:body-content-start/page-end;z-index:998;opacity:.999}.page-columns .column-page-right figcaption table{background:#222}#quarto-content.page-columns #quarto-margin-sidebar,#quarto-content.page-columns #quarto-sidebar{z-index:1}@media(max-width: 991.98px){#quarto-content.page-columns #quarto-margin-sidebar.collapse,#quarto-content.page-columns #quarto-sidebar.collapse,#quarto-content.page-columns #quarto-margin-sidebar.collapsing,#quarto-content.page-columns #quarto-sidebar.collapsing{z-index:1055}}#quarto-content.page-columns main.column-page,#quarto-content.page-columns main.column-page-right,#quarto-content.page-columns main.column-page-left{z-index:0}.page-columns .column-screen-inset{grid-column:screen-start-inset/screen-end-inset;z-index:998;opacity:.999}.page-columns .column-screen-inset table{background:#222}.page-columns .column-screen-inset-left{grid-column:screen-start-inset/body-content-end;z-index:998;opacity:.999}.page-columns .column-screen-inset-left table{background:#222}.page-columns .column-screen-inset-right{grid-column:body-content-start/screen-end-inset;z-index:998;opacity:.999}.page-columns .column-screen-inset-right table{background:#222}.page-columns .column-screen{grid-column:screen-start/screen-end;z-index:998;opacity:.999}.page-columns .column-screen table{background:#222}.page-columns .column-screen-left{grid-column:screen-start/body-content-end;z-index:998;opacity:.999}.page-columns .column-screen-left table{background:#222}.page-columns .column-screen-right{grid-column:body-content-start/screen-end;z-index:998;opacity:.999}.page-columns .column-screen-right table{background:#222}.page-columns .column-screen-inset-shaded{grid-column:screen-start/screen-end;padding:1em;background:#6f6f6f;z-index:998;opacity:.999;margin-bottom:1em}.zindex-content{z-index:998;opacity:.999}.zindex-modal{z-index:1055;opacity:.999}.zindex-over-content{z-index:999;opacity:.999}img.img-fluid.column-screen,img.img-fluid.column-screen-inset-shaded,img.img-fluid.column-screen-inset,img.img-fluid.column-screen-inset-left,img.img-fluid.column-screen-inset-right,img.img-fluid.column-screen-left,img.img-fluid.column-screen-right{width:100%}@media(min-width: 992px){.margin-caption,div.aside,aside:not(.footnotes):not(.sidebar),.column-margin{grid-column:body-end/page-end !important;z-index:998}.column-sidebar{grid-column:page-start/body-start !important;z-index:998}.column-leftmargin{grid-column:screen-start-inset/body-start !important;z-index:998}.no-row-height{height:1em;overflow:visible}}@media(max-width: 991.98px){.margin-caption,div.aside,aside:not(.footnotes):not(.sidebar),.column-margin{grid-column:body-end/page-end !important;z-index:998}.no-row-height{height:1em;overflow:visible}.page-columns.page-full{overflow:visible}.page-columns.toc-left .margin-caption,.page-columns.toc-left div.aside,.page-columns.toc-left aside:not(.footnotes):not(.sidebar),.page-columns.toc-left .column-margin{grid-column:body-content-start/body-content-end !important;z-index:998;opacity:.999}.page-columns.toc-left .no-row-height{height:initial;overflow:initial}}@media(max-width: 767.98px){.margin-caption,div.aside,aside:not(.footnotes):not(.sidebar),.column-margin{grid-column:body-content-start/body-content-end !important;z-index:998;opacity:.999}.no-row-height{height:initial;overflow:initial}#quarto-margin-sidebar{display:none}#quarto-sidebar-toc-left{display:none}.hidden-sm{display:none}}.panel-grid{display:grid;grid-template-rows:repeat(1, 1fr);grid-template-columns:repeat(24, 1fr);gap:1em}.panel-grid .g-col-1{grid-column:auto/span 1}.panel-grid .g-col-2{grid-column:auto/span 2}.panel-grid .g-col-3{grid-column:auto/span 3}.panel-grid .g-col-4{grid-column:auto/span 4}.panel-grid .g-col-5{grid-column:auto/span 5}.panel-grid .g-col-6{grid-column:auto/span 6}.panel-grid .g-col-7{grid-column:auto/span 7}.panel-grid .g-col-8{grid-column:auto/span 8}.panel-grid .g-col-9{grid-column:auto/span 9}.panel-grid .g-col-10{grid-column:auto/span 10}.panel-grid .g-col-11{grid-column:auto/span 11}.panel-grid .g-col-12{grid-column:auto/span 12}.panel-grid .g-col-13{grid-column:auto/span 13}.panel-grid .g-col-14{grid-column:auto/span 14}.panel-grid .g-col-15{grid-column:auto/span 15}.panel-grid .g-col-16{grid-column:auto/span 16}.panel-grid .g-col-17{grid-column:auto/span 17}.panel-grid .g-col-18{grid-column:auto/span 18}.panel-grid .g-col-19{grid-column:auto/span 19}.panel-grid .g-col-20{grid-column:auto/span 20}.panel-grid .g-col-21{grid-column:auto/span 21}.panel-grid .g-col-22{grid-column:auto/span 22}.panel-grid .g-col-23{grid-column:auto/span 23}.panel-grid .g-col-24{grid-column:auto/span 24}.panel-grid .g-start-1{grid-column-start:1}.panel-grid .g-start-2{grid-column-start:2}.panel-grid .g-start-3{grid-column-start:3}.panel-grid .g-start-4{grid-column-start:4}.panel-grid .g-start-5{grid-column-start:5}.panel-grid .g-start-6{grid-column-start:6}.panel-grid .g-start-7{grid-column-start:7}.panel-grid .g-start-8{grid-column-start:8}.panel-grid .g-start-9{grid-column-start:9}.panel-grid .g-start-10{grid-column-start:10}.panel-grid .g-start-11{grid-column-start:11}.panel-grid .g-start-12{grid-column-start:12}.panel-grid .g-start-13{grid-column-start:13}.panel-grid .g-start-14{grid-column-start:14}.panel-grid .g-start-15{grid-column-start:15}.panel-grid .g-start-16{grid-column-start:16}.panel-grid .g-start-17{grid-column-start:17}.panel-grid .g-start-18{grid-column-start:18}.panel-grid .g-start-19{grid-column-start:19}.panel-grid .g-start-20{grid-column-start:20}.panel-grid .g-start-21{grid-column-start:21}.panel-grid .g-start-22{grid-column-start:22}.panel-grid .g-start-23{grid-column-start:23}@media(min-width: 576px){.panel-grid .g-col-sm-1{grid-column:auto/span 1}.panel-grid .g-col-sm-2{grid-column:auto/span 2}.panel-grid .g-col-sm-3{grid-column:auto/span 3}.panel-grid .g-col-sm-4{grid-column:auto/span 4}.panel-grid .g-col-sm-5{grid-column:auto/span 5}.panel-grid .g-col-sm-6{grid-column:auto/span 6}.panel-grid .g-col-sm-7{grid-column:auto/span 7}.panel-grid .g-col-sm-8{grid-column:auto/span 8}.panel-grid .g-col-sm-9{grid-column:auto/span 9}.panel-grid .g-col-sm-10{grid-column:auto/span 10}.panel-grid .g-col-sm-11{grid-column:auto/span 11}.panel-grid .g-col-sm-12{grid-column:auto/span 12}.panel-grid .g-col-sm-13{grid-column:auto/span 13}.panel-grid .g-col-sm-14{grid-column:auto/span 14}.panel-grid .g-col-sm-15{grid-column:auto/span 15}.panel-grid .g-col-sm-16{grid-column:auto/span 16}.panel-grid .g-col-sm-17{grid-column:auto/span 17}.panel-grid .g-col-sm-18{grid-column:auto/span 18}.panel-grid .g-col-sm-19{grid-column:auto/span 19}.panel-grid .g-col-sm-20{grid-column:auto/span 20}.panel-grid .g-col-sm-21{grid-column:auto/span 21}.panel-grid .g-col-sm-22{grid-column:auto/span 22}.panel-grid .g-col-sm-23{grid-column:auto/span 23}.panel-grid .g-col-sm-24{grid-column:auto/span 24}.panel-grid .g-start-sm-1{grid-column-start:1}.panel-grid .g-start-sm-2{grid-column-start:2}.panel-grid .g-start-sm-3{grid-column-start:3}.panel-grid .g-start-sm-4{grid-column-start:4}.panel-grid .g-start-sm-5{grid-column-start:5}.panel-grid .g-start-sm-6{grid-column-start:6}.panel-grid .g-start-sm-7{grid-column-start:7}.panel-grid .g-start-sm-8{grid-column-start:8}.panel-grid .g-start-sm-9{grid-column-start:9}.panel-grid .g-start-sm-10{grid-column-start:10}.panel-grid .g-start-sm-11{grid-column-start:11}.panel-grid .g-start-sm-12{grid-column-start:12}.panel-grid .g-start-sm-13{grid-column-start:13}.panel-grid .g-start-sm-14{grid-column-start:14}.panel-grid .g-start-sm-15{grid-column-start:15}.panel-grid .g-start-sm-16{grid-column-start:16}.panel-grid .g-start-sm-17{grid-column-start:17}.panel-grid .g-start-sm-18{grid-column-start:18}.panel-grid .g-start-sm-19{grid-column-start:19}.panel-grid .g-start-sm-20{grid-column-start:20}.panel-grid .g-start-sm-21{grid-column-start:21}.panel-grid .g-start-sm-22{grid-column-start:22}.panel-grid .g-start-sm-23{grid-column-start:23}}@media(min-width: 768px){.panel-grid .g-col-md-1{grid-column:auto/span 1}.panel-grid .g-col-md-2{grid-column:auto/span 2}.panel-grid .g-col-md-3{grid-column:auto/span 3}.panel-grid .g-col-md-4{grid-column:auto/span 4}.panel-grid .g-col-md-5{grid-column:auto/span 5}.panel-grid .g-col-md-6{grid-column:auto/span 6}.panel-grid .g-col-md-7{grid-column:auto/span 7}.panel-grid .g-col-md-8{grid-column:auto/span 8}.panel-grid .g-col-md-9{grid-column:auto/span 9}.panel-grid .g-col-md-10{grid-column:auto/span 10}.panel-grid .g-col-md-11{grid-column:auto/span 11}.panel-grid .g-col-md-12{grid-column:auto/span 12}.panel-grid .g-col-md-13{grid-column:auto/span 13}.panel-grid .g-col-md-14{grid-column:auto/span 14}.panel-grid .g-col-md-15{grid-column:auto/span 15}.panel-grid .g-col-md-16{grid-column:auto/span 16}.panel-grid .g-col-md-17{grid-column:auto/span 17}.panel-grid .g-col-md-18{grid-column:auto/span 18}.panel-grid .g-col-md-19{grid-column:auto/span 19}.panel-grid .g-col-md-20{grid-column:auto/span 20}.panel-grid .g-col-md-21{grid-column:auto/span 21}.panel-grid .g-col-md-22{grid-column:auto/span 22}.panel-grid .g-col-md-23{grid-column:auto/span 23}.panel-grid .g-col-md-24{grid-column:auto/span 24}.panel-grid .g-start-md-1{grid-column-start:1}.panel-grid .g-start-md-2{grid-column-start:2}.panel-grid .g-start-md-3{grid-column-start:3}.panel-grid .g-start-md-4{grid-column-start:4}.panel-grid .g-start-md-5{grid-column-start:5}.panel-grid .g-start-md-6{grid-column-start:6}.panel-grid .g-start-md-7{grid-column-start:7}.panel-grid .g-start-md-8{grid-column-start:8}.panel-grid .g-start-md-9{grid-column-start:9}.panel-grid .g-start-md-10{grid-column-start:10}.panel-grid .g-start-md-11{grid-column-start:11}.panel-grid .g-start-md-12{grid-column-start:12}.panel-grid .g-start-md-13{grid-column-start:13}.panel-grid .g-start-md-14{grid-column-start:14}.panel-grid .g-start-md-15{grid-column-start:15}.panel-grid .g-start-md-16{grid-column-start:16}.panel-grid .g-start-md-17{grid-column-start:17}.panel-grid .g-start-md-18{grid-column-start:18}.panel-grid .g-start-md-19{grid-column-start:19}.panel-grid .g-start-md-20{grid-column-start:20}.panel-grid .g-start-md-21{grid-column-start:21}.panel-grid .g-start-md-22{grid-column-start:22}.panel-grid .g-start-md-23{grid-column-start:23}}@media(min-width: 992px){.panel-grid .g-col-lg-1{grid-column:auto/span 1}.panel-grid .g-col-lg-2{grid-column:auto/span 2}.panel-grid .g-col-lg-3{grid-column:auto/span 3}.panel-grid .g-col-lg-4{grid-column:auto/span 4}.panel-grid .g-col-lg-5{grid-column:auto/span 5}.panel-grid .g-col-lg-6{grid-column:auto/span 6}.panel-grid .g-col-lg-7{grid-column:auto/span 7}.panel-grid .g-col-lg-8{grid-column:auto/span 8}.panel-grid .g-col-lg-9{grid-column:auto/span 9}.panel-grid .g-col-lg-10{grid-column:auto/span 10}.panel-grid .g-col-lg-11{grid-column:auto/span 11}.panel-grid .g-col-lg-12{grid-column:auto/span 12}.panel-grid .g-col-lg-13{grid-column:auto/span 13}.panel-grid .g-col-lg-14{grid-column:auto/span 14}.panel-grid .g-col-lg-15{grid-column:auto/span 15}.panel-grid .g-col-lg-16{grid-column:auto/span 16}.panel-grid .g-col-lg-17{grid-column:auto/span 17}.panel-grid .g-col-lg-18{grid-column:auto/span 18}.panel-grid .g-col-lg-19{grid-column:auto/span 19}.panel-grid .g-col-lg-20{grid-column:auto/span 20}.panel-grid .g-col-lg-21{grid-column:auto/span 21}.panel-grid .g-col-lg-22{grid-column:auto/span 22}.panel-grid .g-col-lg-23{grid-column:auto/span 23}.panel-grid .g-col-lg-24{grid-column:auto/span 24}.panel-grid .g-start-lg-1{grid-column-start:1}.panel-grid .g-start-lg-2{grid-column-start:2}.panel-grid .g-start-lg-3{grid-column-start:3}.panel-grid .g-start-lg-4{grid-column-start:4}.panel-grid .g-start-lg-5{grid-column-start:5}.panel-grid .g-start-lg-6{grid-column-start:6}.panel-grid .g-start-lg-7{grid-column-start:7}.panel-grid .g-start-lg-8{grid-column-start:8}.panel-grid .g-start-lg-9{grid-column-start:9}.panel-grid .g-start-lg-10{grid-column-start:10}.panel-grid .g-start-lg-11{grid-column-start:11}.panel-grid .g-start-lg-12{grid-column-start:12}.panel-grid .g-start-lg-13{grid-column-start:13}.panel-grid .g-start-lg-14{grid-column-start:14}.panel-grid .g-start-lg-15{grid-column-start:15}.panel-grid .g-start-lg-16{grid-column-start:16}.panel-grid .g-start-lg-17{grid-column-start:17}.panel-grid .g-start-lg-18{grid-column-start:18}.panel-grid .g-start-lg-19{grid-column-start:19}.panel-grid .g-start-lg-20{grid-column-start:20}.panel-grid .g-start-lg-21{grid-column-start:21}.panel-grid .g-start-lg-22{grid-column-start:22}.panel-grid .g-start-lg-23{grid-column-start:23}}@media(min-width: 1200px){.panel-grid .g-col-xl-1{grid-column:auto/span 1}.panel-grid .g-col-xl-2{grid-column:auto/span 2}.panel-grid .g-col-xl-3{grid-column:auto/span 3}.panel-grid .g-col-xl-4{grid-column:auto/span 4}.panel-grid .g-col-xl-5{grid-column:auto/span 5}.panel-grid .g-col-xl-6{grid-column:auto/span 6}.panel-grid .g-col-xl-7{grid-column:auto/span 7}.panel-grid .g-col-xl-8{grid-column:auto/span 8}.panel-grid .g-col-xl-9{grid-column:auto/span 9}.panel-grid .g-col-xl-10{grid-column:auto/span 10}.panel-grid .g-col-xl-11{grid-column:auto/span 11}.panel-grid .g-col-xl-12{grid-column:auto/span 12}.panel-grid .g-col-xl-13{grid-column:auto/span 13}.panel-grid .g-col-xl-14{grid-column:auto/span 14}.panel-grid .g-col-xl-15{grid-column:auto/span 15}.panel-grid .g-col-xl-16{grid-column:auto/span 16}.panel-grid .g-col-xl-17{grid-column:auto/span 17}.panel-grid .g-col-xl-18{grid-column:auto/span 18}.panel-grid .g-col-xl-19{grid-column:auto/span 19}.panel-grid .g-col-xl-20{grid-column:auto/span 20}.panel-grid .g-col-xl-21{grid-column:auto/span 21}.panel-grid .g-col-xl-22{grid-column:auto/span 22}.panel-grid .g-col-xl-23{grid-column:auto/span 23}.panel-grid .g-col-xl-24{grid-column:auto/span 24}.panel-grid .g-start-xl-1{grid-column-start:1}.panel-grid .g-start-xl-2{grid-column-start:2}.panel-grid .g-start-xl-3{grid-column-start:3}.panel-grid .g-start-xl-4{grid-column-start:4}.panel-grid .g-start-xl-5{grid-column-start:5}.panel-grid .g-start-xl-6{grid-column-start:6}.panel-grid .g-start-xl-7{grid-column-start:7}.panel-grid .g-start-xl-8{grid-column-start:8}.panel-grid .g-start-xl-9{grid-column-start:9}.panel-grid .g-start-xl-10{grid-column-start:10}.panel-grid .g-start-xl-11{grid-column-start:11}.panel-grid .g-start-xl-12{grid-column-start:12}.panel-grid .g-start-xl-13{grid-column-start:13}.panel-grid .g-start-xl-14{grid-column-start:14}.panel-grid .g-start-xl-15{grid-column-start:15}.panel-grid .g-start-xl-16{grid-column-start:16}.panel-grid .g-start-xl-17{grid-column-start:17}.panel-grid .g-start-xl-18{grid-column-start:18}.panel-grid .g-start-xl-19{grid-column-start:19}.panel-grid .g-start-xl-20{grid-column-start:20}.panel-grid .g-start-xl-21{grid-column-start:21}.panel-grid .g-start-xl-22{grid-column-start:22}.panel-grid .g-start-xl-23{grid-column-start:23}}@media(min-width: 1400px){.panel-grid .g-col-xxl-1{grid-column:auto/span 1}.panel-grid .g-col-xxl-2{grid-column:auto/span 2}.panel-grid .g-col-xxl-3{grid-column:auto/span 3}.panel-grid .g-col-xxl-4{grid-column:auto/span 4}.panel-grid .g-col-xxl-5{grid-column:auto/span 5}.panel-grid .g-col-xxl-6{grid-column:auto/span 6}.panel-grid .g-col-xxl-7{grid-column:auto/span 7}.panel-grid .g-col-xxl-8{grid-column:auto/span 8}.panel-grid .g-col-xxl-9{grid-column:auto/span 9}.panel-grid .g-col-xxl-10{grid-column:auto/span 10}.panel-grid .g-col-xxl-11{grid-column:auto/span 11}.panel-grid .g-col-xxl-12{grid-column:auto/span 12}.panel-grid .g-col-xxl-13{grid-column:auto/span 13}.panel-grid .g-col-xxl-14{grid-column:auto/span 14}.panel-grid .g-col-xxl-15{grid-column:auto/span 15}.panel-grid .g-col-xxl-16{grid-column:auto/span 16}.panel-grid .g-col-xxl-17{grid-column:auto/span 17}.panel-grid .g-col-xxl-18{grid-column:auto/span 18}.panel-grid .g-col-xxl-19{grid-column:auto/span 19}.panel-grid .g-col-xxl-20{grid-column:auto/span 20}.panel-grid .g-col-xxl-21{grid-column:auto/span 21}.panel-grid .g-col-xxl-22{grid-column:auto/span 22}.panel-grid .g-col-xxl-23{grid-column:auto/span 23}.panel-grid .g-col-xxl-24{grid-column:auto/span 24}.panel-grid .g-start-xxl-1{grid-column-start:1}.panel-grid .g-start-xxl-2{grid-column-start:2}.panel-grid .g-start-xxl-3{grid-column-start:3}.panel-grid .g-start-xxl-4{grid-column-start:4}.panel-grid .g-start-xxl-5{grid-column-start:5}.panel-grid .g-start-xxl-6{grid-column-start:6}.panel-grid .g-start-xxl-7{grid-column-start:7}.panel-grid .g-start-xxl-8{grid-column-start:8}.panel-grid .g-start-xxl-9{grid-column-start:9}.panel-grid .g-start-xxl-10{grid-column-start:10}.panel-grid .g-start-xxl-11{grid-column-start:11}.panel-grid .g-start-xxl-12{grid-column-start:12}.panel-grid .g-start-xxl-13{grid-column-start:13}.panel-grid .g-start-xxl-14{grid-column-start:14}.panel-grid .g-start-xxl-15{grid-column-start:15}.panel-grid .g-start-xxl-16{grid-column-start:16}.panel-grid .g-start-xxl-17{grid-column-start:17}.panel-grid .g-start-xxl-18{grid-column-start:18}.panel-grid .g-start-xxl-19{grid-column-start:19}.panel-grid .g-start-xxl-20{grid-column-start:20}.panel-grid .g-start-xxl-21{grid-column-start:21}.panel-grid .g-start-xxl-22{grid-column-start:22}.panel-grid .g-start-xxl-23{grid-column-start:23}}main{margin-top:1em;margin-bottom:1em}h1,.h1,h2,.h2{color:inherit;margin-top:2rem;margin-bottom:1rem;font-weight:600}h1.title,.title.h1{margin-top:0}main.content>section:first-of-type>h2:first-child,main.content>section:first-of-type>.h2:first-child{margin-top:0}h2,.h2{border-bottom:1px solid #434343;padding-bottom:.5rem}h3,.h3{font-weight:600}h3,.h3,h4,.h4{opacity:.9;margin-top:1.5rem}h5,.h5,h6,.h6{opacity:.9}.header-section-number{color:#bfbfbf}.nav-link.active .header-section-number{color:inherit}mark,.mark{padding:0em}.panel-caption,.figure-caption,.subfigure-caption,.table-caption,figcaption,caption{font-size:.9rem;color:#bfbfbf}.quarto-layout-cell[data-ref-parent] caption{color:#bfbfbf}.column-margin figcaption,.margin-caption,div.aside,aside,.column-margin{color:#bfbfbf;font-size:.825rem}.panel-caption.margin-caption{text-align:inherit}.column-margin.column-container p{margin-bottom:0}.column-margin.column-container>*:not(.collapse):first-child{padding-bottom:.5em;display:block}.column-margin.column-container>*:not(.collapse):not(:first-child){padding-top:.5em;padding-bottom:.5em;display:block}.column-margin.column-container>*.collapse:not(.show){display:none}@media(min-width: 768px){.column-margin.column-container .callout-margin-content:first-child{margin-top:4.5em}.column-margin.column-container .callout-margin-content-simple:first-child{margin-top:3.5em}}.margin-caption>*{padding-top:.5em;padding-bottom:.5em}@media(max-width: 767.98px){.quarto-layout-row{flex-direction:column}}.nav-tabs .nav-item{margin-top:1px;cursor:pointer}.tab-content{margin-top:0px;border-left:#434343 1px solid;border-right:#434343 1px solid;border-bottom:#434343 1px solid;margin-left:0;padding:1em;margin-bottom:1em}@media(max-width: 767.98px){.layout-sidebar{margin-left:0;margin-right:0}}.panel-sidebar,.panel-sidebar .form-control,.panel-input,.panel-input .form-control,.selectize-dropdown{font-size:.9rem}.panel-sidebar .form-control,.panel-input .form-control{padding-top:.1rem}.tab-pane div.sourceCode{margin-top:0px}.tab-pane>p{padding-top:0}.tab-pane>p:nth-child(1){padding-top:0}.tab-pane>p:last-child{margin-bottom:0}.tab-pane>pre:last-child{margin-bottom:0}.tab-content>.tab-pane:not(.active){display:none !important}div.sourceCode{background-color:rgba(67,67,67,.65);border:1px solid rgba(67,67,67,.65);border-radius:.25rem}pre.sourceCode{background-color:rgba(0,0,0,0)}pre.sourceCode{border:none;font-size:.875em;overflow:visible !important;padding:.4em}.callout pre.sourceCode{padding-left:0}div.sourceCode{overflow-y:hidden}.callout div.sourceCode{margin-left:initial}.blockquote{font-size:inherit;padding-left:1rem;padding-right:1.5rem;color:#bfbfbf}.blockquote h1:first-child,.blockquote .h1:first-child,.blockquote h2:first-child,.blockquote .h2:first-child,.blockquote h3:first-child,.blockquote .h3:first-child,.blockquote h4:first-child,.blockquote .h4:first-child,.blockquote h5:first-child,.blockquote .h5:first-child{margin-top:0}pre{background-color:initial;padding:initial;border:initial}p pre code:not(.sourceCode),li pre code:not(.sourceCode),pre code:not(.sourceCode){background-color:initial}p code:not(.sourceCode),li code:not(.sourceCode),td code:not(.sourceCode){background-color:#f8f9fa;padding:.2em}nav p code:not(.sourceCode),nav li code:not(.sourceCode),nav td code:not(.sourceCode){background-color:rgba(0,0,0,0);padding:0}td code:not(.sourceCode){white-space:pre-wrap}#quarto-embedded-source-code-modal>.modal-dialog{max-width:1000px;padding-left:1.75rem;padding-right:1.75rem}#quarto-embedded-source-code-modal>.modal-dialog>.modal-content>.modal-body{padding:0}#quarto-embedded-source-code-modal>.modal-dialog>.modal-content>.modal-body div.sourceCode{margin:0;padding:.2rem .2rem;border-radius:0px;border:none}#quarto-embedded-source-code-modal>.modal-dialog>.modal-content>.modal-header{padding:.7rem}.code-tools-button{font-size:1rem;padding:.15rem .15rem;margin-left:5px;color:#6c757d;background-color:rgba(0,0,0,0);transition:initial;cursor:pointer}.code-tools-button>.bi::before{display:inline-block;height:1rem;width:1rem;content:"";vertical-align:-0.125em;background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(108, 117, 125)" viewBox="0 0 16 16"><path d="M10.478 1.647a.5.5 0 1 0-.956-.294l-4 13a.5.5 0 0 0 .956.294l4-13zM4.854 4.146a.5.5 0 0 1 0 .708L1.707 8l3.147 3.146a.5.5 0 0 1-.708.708l-3.5-3.5a.5.5 0 0 1 0-.708l3.5-3.5a.5.5 0 0 1 .708 0zm6.292 0a.5.5 0 0 0 0 .708L14.293 8l-3.147 3.146a.5.5 0 0 0 .708.708l3.5-3.5a.5.5 0 0 0 0-.708l-3.5-3.5a.5.5 0 0 0-.708 0z"/></svg>');background-repeat:no-repeat;background-size:1rem 1rem}.code-tools-button:hover>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(255, 255, 255)" viewBox="0 0 16 16"><path d="M10.478 1.647a.5.5 0 1 0-.956-.294l-4 13a.5.5 0 0 0 .956.294l4-13zM4.854 4.146a.5.5 0 0 1 0 .708L1.707 8l3.147 3.146a.5.5 0 0 1-.708.708l-3.5-3.5a.5.5 0 0 1 0-.708l3.5-3.5a.5.5 0 0 1 .708 0zm6.292 0a.5.5 0 0 0 0 .708L14.293 8l-3.147 3.146a.5.5 0 0 0 .708.708l3.5-3.5a.5.5 0 0 0 0-.708l-3.5-3.5a.5.5 0 0 0-.708 0z"/></svg>')}#quarto-embedded-source-code-modal .code-copy-button>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(108, 117, 125)" viewBox="0 0 16 16"><path d="M4 1.5H3a2 2 0 0 0-2 2V14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V3.5a2 2 0 0 0-2-2h-1v1h1a1 1 0 0 1 1 1V14a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V3.5a1 1 0 0 1 1-1h1v-1z"/><path d="M9.5 1a.5.5 0 0 1 .5.5v1a.5.5 0 0 1-.5.5h-3a.5.5 0 0 1-.5-.5v-1a.5.5 0 0 1 .5-.5h3zm-3-1A1.5 1.5 0 0 0 5 1.5v1A1.5 1.5 0 0 0 6.5 4h3A1.5 1.5 0 0 0 11 2.5v-1A1.5 1.5 0 0 0 9.5 0h-3z"/></svg>')}#quarto-embedded-source-code-modal .code-copy-button-checked>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(108, 117, 125)" viewBox="0 0 16 16"><path d="M13.854 3.646a.5.5 0 0 1 0 .708l-7 7a.5.5 0 0 1-.708 0l-3.5-3.5a.5.5 0 1 1 .708-.708L6.5 10.293l6.646-6.647a.5.5 0 0 1 .708 0z"/></svg>')}.sidebar{will-change:top;transition:top 200ms linear;position:sticky;overflow-y:auto;padding-top:1.2em;max-height:100vh}.sidebar.toc-left,.sidebar.margin-sidebar{top:0px;padding-top:1em}.sidebar.quarto-banner-title-block-sidebar>*{padding-top:1.65em}figure .quarto-notebook-link{margin-top:.5em}.quarto-notebook-link{font-size:.75em;color:#6c757d;margin-bottom:1em;text-decoration:none;display:block}.quarto-notebook-link:hover{text-decoration:underline;color:#00bc8c}.quarto-notebook-link::before{display:inline-block;height:.75rem;width:.75rem;margin-bottom:0em;margin-right:.25em;content:"";vertical-align:-0.125em;background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(108, 117, 125)" class="bi bi-journal-code" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8.646 5.646a.5.5 0 0 1 .708 0l2 2a.5.5 0 0 1 0 .708l-2 2a.5.5 0 0 1-.708-.708L10.293 8 8.646 6.354a.5.5 0 0 1 0-.708zm-1.292 0a.5.5 0 0 0-.708 0l-2 2a.5.5 0 0 0 0 .708l2 2a.5.5 0 0 0 .708-.708L5.707 8l1.647-1.646a.5.5 0 0 0 0-.708z"/><path d="M3 0h10a2 2 0 0 1 2 2v12a2 2 0 0 1-2 2H3a2 2 0 0 1-2-2v-1h1v1a1 1 0 0 0 1 1h10a1 1 0 0 0 1-1V2a1 1 0 0 0-1-1H3a1 1 0 0 0-1 1v1H1V2a2 2 0 0 1 2-2z"/><path d="M1 5v-.5a.5.5 0 0 1 1 0V5h.5a.5.5 0 0 1 0 1h-2a.5.5 0 0 1 0-1H1zm0 3v-.5a.5.5 0 0 1 1 0V8h.5a.5.5 0 0 1 0 1h-2a.5.5 0 0 1 0-1H1zm0 3v-.5a.5.5 0 0 1 1 0v.5h.5a.5.5 0 0 1 0 1h-2a.5.5 0 0 1 0-1H1z"/></svg>');background-repeat:no-repeat;background-size:.75rem .75rem}.toc-actions i.bi,.quarto-code-links i.bi,.quarto-other-links i.bi,.quarto-alternate-notebooks i.bi,.quarto-alternate-formats i.bi{margin-right:.4em;font-size:.8rem}.quarto-other-links-text-target .quarto-code-links i.bi,.quarto-other-links-text-target .quarto-other-links i.bi{margin-right:.2em}.quarto-other-formats-text-target .quarto-alternate-formats i.bi{margin-right:.1em}.toc-actions i.bi.empty,.quarto-code-links i.bi.empty,.quarto-other-links i.bi.empty,.quarto-alternate-notebooks i.bi.empty,.quarto-alternate-formats i.bi.empty{padding-left:1em}.quarto-notebook h2,.quarto-notebook .h2{border-bottom:none}.quarto-notebook .cell-container{display:flex}.quarto-notebook .cell-container .cell{flex-grow:4}.quarto-notebook .cell-container .cell-decorator{padding-top:1.5em;padding-right:1em;text-align:right}.quarto-notebook .cell-container.code-fold .cell-decorator{padding-top:3em}.quarto-notebook .cell-code code{white-space:pre-wrap}.quarto-notebook .cell .cell-output-stderr pre code,.quarto-notebook .cell .cell-output-stdout pre code{white-space:pre-wrap;overflow-wrap:anywhere}.toc-actions,.quarto-alternate-formats,.quarto-other-links,.quarto-code-links,.quarto-alternate-notebooks{padding-left:0em}.sidebar .toc-actions a,.sidebar .quarto-alternate-formats a,.sidebar .quarto-other-links a,.sidebar .quarto-code-links a,.sidebar .quarto-alternate-notebooks a,.sidebar nav[role=doc-toc] a{text-decoration:none}.sidebar .toc-actions a:hover,.sidebar .quarto-other-links a:hover,.sidebar .quarto-code-links a:hover,.sidebar .quarto-alternate-formats a:hover,.sidebar .quarto-alternate-notebooks a:hover{color:#00bc8c}.sidebar .toc-actions h2,.sidebar .toc-actions .h2,.sidebar .quarto-code-links h2,.sidebar .quarto-code-links .h2,.sidebar .quarto-other-links h2,.sidebar .quarto-other-links .h2,.sidebar .quarto-alternate-notebooks h2,.sidebar .quarto-alternate-notebooks .h2,.sidebar .quarto-alternate-formats h2,.sidebar .quarto-alternate-formats .h2,.sidebar nav[role=doc-toc]>h2,.sidebar nav[role=doc-toc]>.h2{font-weight:500;margin-bottom:.2rem;margin-top:.3rem;font-family:inherit;border-bottom:0;padding-bottom:0;padding-top:0px}.sidebar .toc-actions>h2,.sidebar .toc-actions>.h2,.sidebar .quarto-code-links>h2,.sidebar .quarto-code-links>.h2,.sidebar .quarto-other-links>h2,.sidebar .quarto-other-links>.h2,.sidebar .quarto-alternate-notebooks>h2,.sidebar .quarto-alternate-notebooks>.h2,.sidebar .quarto-alternate-formats>h2,.sidebar .quarto-alternate-formats>.h2{font-size:.8rem}.sidebar nav[role=doc-toc]>h2,.sidebar nav[role=doc-toc]>.h2{font-size:.875rem}.sidebar nav[role=doc-toc]>ul a{border-left:1px solid #ebebeb;padding-left:.6rem}.sidebar .toc-actions h2>ul a,.sidebar .toc-actions .h2>ul a,.sidebar .quarto-code-links h2>ul a,.sidebar .quarto-code-links .h2>ul a,.sidebar .quarto-other-links h2>ul a,.sidebar .quarto-other-links .h2>ul a,.sidebar .quarto-alternate-notebooks h2>ul a,.sidebar .quarto-alternate-notebooks .h2>ul a,.sidebar .quarto-alternate-formats h2>ul a,.sidebar .quarto-alternate-formats .h2>ul a{border-left:none;padding-left:.6rem}.sidebar .toc-actions ul a:empty,.sidebar .quarto-code-links ul a:empty,.sidebar .quarto-other-links ul a:empty,.sidebar .quarto-alternate-notebooks ul a:empty,.sidebar .quarto-alternate-formats ul a:empty,.sidebar nav[role=doc-toc]>ul a:empty{display:none}.sidebar .toc-actions ul,.sidebar .quarto-code-links ul,.sidebar .quarto-other-links ul,.sidebar .quarto-alternate-notebooks ul,.sidebar .quarto-alternate-formats ul{padding-left:0;list-style:none}.sidebar nav[role=doc-toc] ul{list-style:none;padding-left:0;list-style:none}.sidebar nav[role=doc-toc]>ul{margin-left:.45em}.quarto-margin-sidebar nav[role=doc-toc]{padding-left:.5em}.sidebar .toc-actions>ul,.sidebar .quarto-code-links>ul,.sidebar .quarto-other-links>ul,.sidebar .quarto-alternate-notebooks>ul,.sidebar .quarto-alternate-formats>ul{font-size:.8rem}.sidebar nav[role=doc-toc]>ul{font-size:.875rem}.sidebar .toc-actions ul li a,.sidebar .quarto-code-links ul li a,.sidebar .quarto-other-links ul li a,.sidebar .quarto-alternate-notebooks ul li a,.sidebar .quarto-alternate-formats ul li a,.sidebar nav[role=doc-toc]>ul li a{line-height:1.1rem;padding-bottom:.2rem;padding-top:.2rem;color:inherit}.sidebar nav[role=doc-toc] ul>li>ul>li>a{padding-left:1.2em}.sidebar nav[role=doc-toc] ul>li>ul>li>ul>li>a{padding-left:2.4em}.sidebar nav[role=doc-toc] ul>li>ul>li>ul>li>ul>li>a{padding-left:3.6em}.sidebar nav[role=doc-toc] ul>li>ul>li>ul>li>ul>li>ul>li>a{padding-left:4.8em}.sidebar nav[role=doc-toc] ul>li>ul>li>ul>li>ul>li>ul>li>ul>li>a{padding-left:6em}.sidebar nav[role=doc-toc] ul>li>a.active,.sidebar nav[role=doc-toc] ul>li>ul>li>a.active{border-left:1px solid #00bc8c;color:#00bc8c !important}.sidebar nav[role=doc-toc] ul>li>a:hover,.sidebar nav[role=doc-toc] ul>li>ul>li>a:hover{color:#00bc8c !important}kbd,.kbd{color:#fff;background-color:#f8f9fa;border:1px solid;border-radius:5px;border-color:#434343}.quarto-appendix-contents div.hanging-indent{margin-left:0em}.quarto-appendix-contents div.hanging-indent div.csl-entry{margin-left:1em;text-indent:-1em}.citation a,.footnote-ref{text-decoration:none}.footnotes ol{padding-left:1em}.tippy-content>*{margin-bottom:.7em}.tippy-content>*:last-child{margin-bottom:0}.callout{margin-top:1.25rem;margin-bottom:1.25rem;border-radius:.25rem;overflow-wrap:break-word}.callout .callout-title-container{overflow-wrap:anywhere}.callout.callout-style-simple{padding:.4em .7em;border-left:5px solid;border-right:1px solid #434343;border-top:1px solid #434343;border-bottom:1px solid #434343}.callout.callout-style-default{border-left:5px solid;border-right:1px solid #434343;border-top:1px solid #434343;border-bottom:1px solid #434343}.callout .callout-body-container{flex-grow:1}.callout.callout-style-simple .callout-body{font-size:.9rem;font-weight:400}.callout.callout-style-default .callout-body{font-size:.9rem;font-weight:400}.callout:not(.no-icon).callout-titled.callout-style-simple .callout-body{padding-left:1.6em}.callout.callout-titled>.callout-header{padding-top:.2em;margin-bottom:-0.2em}.callout.callout-style-simple>div.callout-header{border-bottom:none;font-size:.9rem;font-weight:600;opacity:75%}.callout.callout-style-default>div.callout-header{border-bottom:none;font-weight:600;opacity:85%;font-size:.9rem;padding-left:.5em;padding-right:.5em}.callout.callout-style-default .callout-body{padding-left:.5em;padding-right:.5em}.callout.callout-style-default .callout-body>:first-child{padding-top:.5rem;margin-top:0}.callout>div.callout-header[data-bs-toggle=collapse]{cursor:pointer}.callout.callout-style-default .callout-header[aria-expanded=false],.callout.callout-style-default .callout-header[aria-expanded=true]{padding-top:0px;margin-bottom:0px;align-items:center}.callout.callout-titled .callout-body>:last-child:not(.sourceCode),.callout.callout-titled .callout-body>div>:last-child:not(.sourceCode){padding-bottom:.5rem;margin-bottom:0}.callout:not(.callout-titled) .callout-body>:first-child,.callout:not(.callout-titled) .callout-body>div>:first-child{margin-top:.25rem}.callout:not(.callout-titled) .callout-body>:last-child,.callout:not(.callout-titled) .callout-body>div>:last-child{margin-bottom:.2rem}.callout.callout-style-simple .callout-icon::before,.callout.callout-style-simple .callout-toggle::before{height:1rem;width:1rem;display:inline-block;content:"";background-repeat:no-repeat;background-size:1rem 1rem}.callout.callout-style-default .callout-icon::before,.callout.callout-style-default .callout-toggle::before{height:.9rem;width:.9rem;display:inline-block;content:"";background-repeat:no-repeat;background-size:.9rem .9rem}.callout.callout-style-default .callout-toggle::before{margin-top:5px}.callout .callout-btn-toggle .callout-toggle::before{transition:transform .2s linear}.callout .callout-header[aria-expanded=false] .callout-toggle::before{transform:rotate(-90deg)}.callout .callout-header[aria-expanded=true] .callout-toggle::before{transform:none}.callout.callout-style-simple:not(.no-icon) div.callout-icon-container{padding-top:.2em;padding-right:.55em}.callout.callout-style-default:not(.no-icon) div.callout-icon-container{padding-top:.1em;padding-right:.35em}.callout.callout-style-default:not(.no-icon) div.callout-title-container{margin-top:-1px}.callout.callout-style-default.callout-caution:not(.no-icon) div.callout-icon-container{padding-top:.3em;padding-right:.35em}.callout>.callout-body>.callout-icon-container>.no-icon,.callout>.callout-header>.callout-icon-container>.no-icon{display:none}div.callout.callout{border-left-color:#6c757d}div.callout.callout-style-default>.callout-header{background-color:#6c757d}div.callout-note.callout{border-left-color:#375a7f}div.callout-note.callout-style-default>.callout-header{background-color:#111b26}div.callout-note:not(.callout-titled) .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %23325172" class="bi bi-info-circle" viewBox="0 0 16 16"><path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z"/><path d="m8.93 6.588-2.29.287-.082.38.45.083c.294.07.352.176.288.469l-.738 3.468c-.194.897.105 1.319.808 1.319.545 0 1.178-.252 1.465-.598l.088-.416c-.2.176-.492.246-.686.246-.275 0-.375-.193-.304-.533L8.93 6.588zM9 4.5a1 1 0 1 1-2 0 1 1 0 0 1 2 0z"/></svg>');}div.callout-note.callout-titled .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %23325172" class="bi bi-info-circle" viewBox="0 0 16 16"><path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z"/><path d="m8.93 6.588-2.29.287-.082.38.45.083c.294.07.352.176.288.469l-.738 3.468c-.194.897.105 1.319.808 1.319.545 0 1.178-.252 1.465-.598l.088-.416c-.2.176-.492.246-.686.246-.275 0-.375-.193-.304-.533L8.93 6.588zM9 4.5a1 1 0 1 1-2 0 1 1 0 0 1 2 0z"/></svg>');}div.callout-note .callout-toggle::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(255, 255, 255)" class="bi bi-chevron-down" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z"/></svg>')}div.callout-tip.callout{border-left-color:#00bc8c}div.callout-tip.callout-style-default>.callout-header{background-color:#00382a}div.callout-tip:not(.callout-titled) .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %2300a97e" class="bi bi-lightbulb" viewBox="0 0 16 16"><path d="M2 6a6 6 0 1 1 10.174 4.31c-.203.196-.359.4-.453.619l-.762 1.769A.5.5 0 0 1 10.5 13a.5.5 0 0 1 0 1 .5.5 0 0 1 0 1l-.224.447a1 1 0 0 1-.894.553H6.618a1 1 0 0 1-.894-.553L5.5 15a.5.5 0 0 1 0-1 .5.5 0 0 1 0-1 .5.5 0 0 1-.46-.302l-.761-1.77a1.964 1.964 0 0 0-.453-.618A5.984 5.984 0 0 1 2 6zm6-5a5 5 0 0 0-3.479 8.592c.263.254.514.564.676.941L5.83 12h4.342l.632-1.467c.162-.377.413-.687.676-.941A5 5 0 0 0 8 1z"/></svg>');}div.callout-tip.callout-titled .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %2300a97e" class="bi bi-lightbulb" viewBox="0 0 16 16"><path d="M2 6a6 6 0 1 1 10.174 4.31c-.203.196-.359.4-.453.619l-.762 1.769A.5.5 0 0 1 10.5 13a.5.5 0 0 1 0 1 .5.5 0 0 1 0 1l-.224.447a1 1 0 0 1-.894.553H6.618a1 1 0 0 1-.894-.553L5.5 15a.5.5 0 0 1 0-1 .5.5 0 0 1 0-1 .5.5 0 0 1-.46-.302l-.761-1.77a1.964 1.964 0 0 0-.453-.618A5.984 5.984 0 0 1 2 6zm6-5a5 5 0 0 0-3.479 8.592c.263.254.514.564.676.941L5.83 12h4.342l.632-1.467c.162-.377.413-.687.676-.941A5 5 0 0 0 8 1z"/></svg>');}div.callout-tip .callout-toggle::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(255, 255, 255)" class="bi bi-chevron-down" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z"/></svg>')}div.callout-warning.callout{border-left-color:#f39c12}div.callout-warning.callout-style-default>.callout-header{background-color:#492f05}div.callout-warning:not(.callout-titled) .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %23db8c10" class="bi bi-exclamation-triangle" viewBox="0 0 16 16"><path d="M7.938 2.016A.13.13 0 0 1 8.002 2a.13.13 0 0 1 .063.016.146.146 0 0 1 .054.057l6.857 11.667c.036.06.035.124.002.183a.163.163 0 0 1-.054.06.116.116 0 0 1-.066.017H1.146a.115.115 0 0 1-.066-.017.163.163 0 0 1-.054-.06.176.176 0 0 1 .002-.183L7.884 2.073a.147.147 0 0 1 .054-.057zm1.044-.45a1.13 1.13 0 0 0-1.96 0L.165 13.233c-.457.778.091 1.767.98 1.767h13.713c.889 0 1.438-.99.98-1.767L8.982 1.566z"/><path d="M7.002 12a1 1 0 1 1 2 0 1 1 0 0 1-2 0zM7.1 5.995a.905.905 0 1 1 1.8 0l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 5.995z"/></svg>');}div.callout-warning.callout-titled .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %23db8c10" class="bi bi-exclamation-triangle" viewBox="0 0 16 16"><path d="M7.938 2.016A.13.13 0 0 1 8.002 2a.13.13 0 0 1 .063.016.146.146 0 0 1 .054.057l6.857 11.667c.036.06.035.124.002.183a.163.163 0 0 1-.054.06.116.116 0 0 1-.066.017H1.146a.115.115 0 0 1-.066-.017.163.163 0 0 1-.054-.06.176.176 0 0 1 .002-.183L7.884 2.073a.147.147 0 0 1 .054-.057zm1.044-.45a1.13 1.13 0 0 0-1.96 0L.165 13.233c-.457.778.091 1.767.98 1.767h13.713c.889 0 1.438-.99.98-1.767L8.982 1.566z"/><path d="M7.002 12a1 1 0 1 1 2 0 1 1 0 0 1-2 0zM7.1 5.995a.905.905 0 1 1 1.8 0l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 5.995z"/></svg>');}div.callout-warning .callout-toggle::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(255, 255, 255)" class="bi bi-chevron-down" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z"/></svg>')}div.callout-caution.callout{border-left-color:#fd7e14}div.callout-caution.callout-style-default>.callout-header{background-color:#4c2606}div.callout-caution:not(.callout-titled) .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %23e47112" class="bi bi-cone-striped" viewBox="0 0 16 16"><path d="M9.97 4.88l.953 3.811C10.158 8.878 9.14 9 8 9c-1.14 0-2.159-.122-2.923-.309L6.03 4.88C6.635 4.957 7.3 5 8 5s1.365-.043 1.97-.12zm-.245-.978L8.97.88C8.718-.13 7.282-.13 7.03.88L6.274 3.9C6.8 3.965 7.382 4 8 4c.618 0 1.2-.036 1.725-.098zm4.396 8.613a.5.5 0 0 1 .037.96l-6 2a.5.5 0 0 1-.316 0l-6-2a.5.5 0 0 1 .037-.96l2.391-.598.565-2.257c.862.212 1.964.339 3.165.339s2.303-.127 3.165-.339l.565 2.257 2.391.598z"/></svg>');}div.callout-caution.callout-titled .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %23e47112" class="bi bi-cone-striped" viewBox="0 0 16 16"><path d="M9.97 4.88l.953 3.811C10.158 8.878 9.14 9 8 9c-1.14 0-2.159-.122-2.923-.309L6.03 4.88C6.635 4.957 7.3 5 8 5s1.365-.043 1.97-.12zm-.245-.978L8.97.88C8.718-.13 7.282-.13 7.03.88L6.274 3.9C6.8 3.965 7.382 4 8 4c.618 0 1.2-.036 1.725-.098zm4.396 8.613a.5.5 0 0 1 .037.96l-6 2a.5.5 0 0 1-.316 0l-6-2a.5.5 0 0 1 .037-.96l2.391-.598.565-2.257c.862.212 1.964.339 3.165.339s2.303-.127 3.165-.339l.565 2.257 2.391.598z"/></svg>');}div.callout-caution .callout-toggle::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(255, 255, 255)" class="bi bi-chevron-down" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z"/></svg>')}div.callout-important.callout{border-left-color:#e74c3c}div.callout-important.callout-style-default>.callout-header{background-color:#451712}div.callout-important:not(.callout-titled) .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %23d04436" class="bi bi-exclamation-circle" viewBox="0 0 16 16"><path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z"/><path d="M7.002 11a1 1 0 1 1 2 0 1 1 0 0 1-2 0zM7.1 4.995a.905.905 0 1 1 1.8 0l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 4.995z"/></svg>');}div.callout-important.callout-titled .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %23d04436" class="bi bi-exclamation-circle" viewBox="0 0 16 16"><path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z"/><path d="M7.002 11a1 1 0 1 1 2 0 1 1 0 0 1-2 0zM7.1 4.995a.905.905 0 1 1 1.8 0l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 4.995z"/></svg>');}div.callout-important .callout-toggle::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(255, 255, 255)" class="bi bi-chevron-down" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z"/></svg>')}.quarto-toggle-container{display:flex;align-items:center}.quarto-reader-toggle .bi::before,.quarto-color-scheme-toggle .bi::before{display:inline-block;height:1rem;width:1rem;content:"";background-repeat:no-repeat;background-size:1rem 1rem}.sidebar-navigation{padding-left:20px}.navbar{background-color:#375a7f;color:#dee2e6}.navbar .quarto-color-scheme-toggle:not(.alternate) .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(222, 226, 230, 1)" class="bi bi-toggle-off" viewBox="0 0 16 16"><path d="M11 4a4 4 0 0 1 0 8H8a4.992 4.992 0 0 0 2-4 4.992 4.992 0 0 0-2-4h3zm-6 8a4 4 0 1 1 0-8 4 4 0 0 1 0 8zM0 8a5 5 0 0 0 5 5h6a5 5 0 0 0 0-10H5a5 5 0 0 0-5 5z"/></svg>')}.navbar .quarto-color-scheme-toggle.alternate .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(222, 226, 230, 1)" class="bi bi-toggle-on" viewBox="0 0 16 16"><path d="M5 3a5 5 0 0 0 0 10h6a5 5 0 0 0 0-10H5zm6 9a4 4 0 1 1 0-8 4 4 0 0 1 0 8z"/></svg>')}.sidebar-navigation .quarto-color-scheme-toggle:not(.alternate) .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(230, 230, 230, 1)" class="bi bi-toggle-off" viewBox="0 0 16 16"><path d="M11 4a4 4 0 0 1 0 8H8a4.992 4.992 0 0 0 2-4 4.992 4.992 0 0 0-2-4h3zm-6 8a4 4 0 1 1 0-8 4 4 0 0 1 0 8zM0 8a5 5 0 0 0 5 5h6a5 5 0 0 0 0-10H5a5 5 0 0 0-5 5z"/></svg>')}.sidebar-navigation .quarto-color-scheme-toggle.alternate .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(230, 230, 230, 1)" class="bi bi-toggle-on" viewBox="0 0 16 16"><path d="M5 3a5 5 0 0 0 0 10h6a5 5 0 0 0 0-10H5zm6 9a4 4 0 1 1 0-8 4 4 0 0 1 0 8z"/></svg>')}.quarto-sidebar-toggle{border-color:#dee2e6;border-bottom-left-radius:.25rem;border-bottom-right-radius:.25rem;border-style:solid;border-width:1px;overflow:hidden;border-top-width:0px;padding-top:0px !important}.quarto-sidebar-toggle-title{cursor:pointer;padding-bottom:2px;margin-left:.25em;text-align:center;font-weight:400;font-size:.775em}#quarto-content .quarto-sidebar-toggle{background:#272727}#quarto-content .quarto-sidebar-toggle-title{color:#fff}.quarto-sidebar-toggle-icon{color:#dee2e6;margin-right:.5em;float:right;transition:transform .2s ease}.quarto-sidebar-toggle-icon::before{padding-top:5px}.quarto-sidebar-toggle.expanded .quarto-sidebar-toggle-icon{transform:rotate(-180deg)}.quarto-sidebar-toggle.expanded .quarto-sidebar-toggle-title{border-bottom:solid #dee2e6 1px}.quarto-sidebar-toggle-contents{background-color:#222;padding-right:10px;padding-left:10px;margin-top:0px !important;transition:max-height .5s ease}.quarto-sidebar-toggle.expanded .quarto-sidebar-toggle-contents{padding-top:1em;padding-bottom:10px}@media(max-width: 767.98px){.sidebar-menu-container{padding-bottom:5em}}.quarto-sidebar-toggle:not(.expanded) .quarto-sidebar-toggle-contents{padding-top:0px !important;padding-bottom:0px}nav[role=doc-toc]{z-index:1020}#quarto-sidebar>*,nav[role=doc-toc]>*{transition:opacity .1s ease,border .1s ease}#quarto-sidebar.slow>*,nav[role=doc-toc].slow>*{transition:opacity .4s ease,border .4s ease}.quarto-color-scheme-toggle:not(.alternate).top-right .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(166, 166, 166, 1)" class="bi bi-toggle-off" viewBox="0 0 16 16"><path d="M11 4a4 4 0 0 1 0 8H8a4.992 4.992 0 0 0 2-4 4.992 4.992 0 0 0-2-4h3zm-6 8a4 4 0 1 1 0-8 4 4 0 0 1 0 8zM0 8a5 5 0 0 0 5 5h6a5 5 0 0 0 0-10H5a5 5 0 0 0-5 5z"/></svg>')}.quarto-color-scheme-toggle.alternate.top-right .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(204, 204, 204, 1)" class="bi bi-toggle-on" viewBox="0 0 16 16"><path d="M5 3a5 5 0 0 0 0 10h6a5 5 0 0 0 0-10H5zm6 9a4 4 0 1 1 0-8 4 4 0 0 1 0 8z"/></svg>')}#quarto-appendix.default{border-top:1px solid #dee2e6}#quarto-appendix.default{background-color:#222;padding-top:1.5em;margin-top:2em;z-index:998}#quarto-appendix.default .quarto-appendix-heading{margin-top:0;line-height:1.4em;font-weight:600;opacity:.9;border-bottom:none;margin-bottom:0}#quarto-appendix.default .footnotes ol,#quarto-appendix.default .footnotes ol li>p:last-of-type,#quarto-appendix.default .quarto-appendix-contents>p:last-of-type{margin-bottom:0}#quarto-appendix.default .footnotes ol{margin-left:.5em}#quarto-appendix.default .quarto-appendix-secondary-label{margin-bottom:.4em}#quarto-appendix.default .quarto-appendix-bibtex{font-size:.7em;padding:1em;border:solid 1px #dee2e6;margin-bottom:1em}#quarto-appendix.default .quarto-appendix-bibtex code.sourceCode{white-space:pre-wrap}#quarto-appendix.default .quarto-appendix-citeas{font-size:.9em;padding:1em;border:solid 1px #dee2e6;margin-bottom:1em}#quarto-appendix.default .quarto-appendix-heading{font-size:1em !important}#quarto-appendix.default *[role=doc-endnotes]>ol,#quarto-appendix.default .quarto-appendix-contents>*:not(h2):not(.h2){font-size:.9em}#quarto-appendix.default section{padding-bottom:1.5em}#quarto-appendix.default section *[role=doc-endnotes],#quarto-appendix.default section>*:not(a){opacity:.9;word-wrap:break-word}.btn.btn-quarto,div.cell-output-display .btn-quarto{--bs-btn-color: #d9d9d9;--bs-btn-bg: #434343;--bs-btn-border-color: #434343;--bs-btn-hover-color: #d9d9d9;--bs-btn-hover-bg: #5f5f5f;--bs-btn-hover-border-color: #565656;--bs-btn-focus-shadow-rgb: 90, 90, 90;--bs-btn-active-color: #fff;--bs-btn-active-bg: dimgray;--bs-btn-active-border-color: #565656;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #434343;--bs-btn-disabled-border-color: #434343}nav.quarto-secondary-nav.color-navbar{background-color:#375a7f;color:#dee2e6}nav.quarto-secondary-nav.color-navbar h1,nav.quarto-secondary-nav.color-navbar .h1,nav.quarto-secondary-nav.color-navbar .quarto-btn-toggle{color:#dee2e6}@media(max-width: 991.98px){body.nav-sidebar .quarto-title-banner{margin-bottom:0;padding-bottom:1em}body.nav-sidebar #title-block-header{margin-block-end:0}}p.subtitle{margin-top:.25em;margin-bottom:.5em}code a:any-link{color:inherit;text-decoration-color:#6c757d}/*! dark */div.observablehq table thead tr th{background-color:var(--bs-body-bg)}input,button,select,optgroup,textarea{background-color:var(--bs-body-bg)}.code-annotated .code-copy-button{margin-right:1.25em;margin-top:0;padding-bottom:0;padding-top:3px}.code-annotation-gutter-bg{background-color:#222}.code-annotation-gutter{background-color:rgba(67,67,67,.65)}.code-annotation-gutter,.code-annotation-gutter-bg{height:100%;width:calc(20px + .5em);position:absolute;top:0;right:0}dl.code-annotation-container-grid dt{margin-right:1em;margin-top:.25rem}dl.code-annotation-container-grid dt{font-family:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace;color:#e6e6e6;border:solid #e6e6e6 1px;border-radius:50%;height:22px;width:22px;line-height:22px;font-size:11px;text-align:center;vertical-align:middle;text-decoration:none}dl.code-annotation-container-grid dt[data-target-cell]{cursor:pointer}dl.code-annotation-container-grid dt[data-target-cell].code-annotation-active{color:#222;border:solid #aaa 1px;background-color:#aaa}pre.code-annotation-code{padding-top:0;padding-bottom:0}pre.code-annotation-code code{z-index:3}#code-annotation-line-highlight-gutter{width:100%;border-top:solid rgba(170,170,170,.2666666667) 1px;border-bottom:solid rgba(170,170,170,.2666666667) 1px;z-index:2;background-color:rgba(170,170,170,.1333333333)}#code-annotation-line-highlight{margin-left:-4em;width:calc(100% + 4em);border-top:solid rgba(170,170,170,.2666666667) 1px;border-bottom:solid rgba(170,170,170,.2666666667) 1px;z-index:2;background-color:rgba(170,170,170,.1333333333)}code.sourceCode .code-annotation-anchor.code-annotation-active{background-color:var(--quarto-hl-normal-color, #aaaaaa);border:solid var(--quarto-hl-normal-color, #aaaaaa) 1px;color:#434343;font-weight:bolder}code.sourceCode .code-annotation-anchor{font-family:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace;color:var(--quarto-hl-co-color);border:solid var(--quarto-hl-co-color) 1px;border-radius:50%;height:18px;width:18px;font-size:9px;margin-top:2px}code.sourceCode button.code-annotation-anchor{padding:2px;user-select:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;-o-user-select:none}code.sourceCode a.code-annotation-anchor{line-height:18px;text-align:center;vertical-align:middle;cursor:default;text-decoration:none}@media print{.page-columns .column-screen-inset{grid-column:page-start-inset/page-end-inset;z-index:998;opacity:.999}.page-columns .column-screen-inset table{background:#222}.page-columns .column-screen-inset-left{grid-column:page-start-inset/body-content-end;z-index:998;opacity:.999}.page-columns .column-screen-inset-left table{background:#222}.page-columns .column-screen-inset-right{grid-column:body-content-start/page-end-inset;z-index:998;opacity:.999}.page-columns .column-screen-inset-right table{background:#222}.page-columns .column-screen{grid-column:page-start/page-end;z-index:998;opacity:.999}.page-columns .column-screen table{background:#222}.page-columns .column-screen-left{grid-column:page-start/body-content-end;z-index:998;opacity:.999}.page-columns .column-screen-left table{background:#222}.page-columns .column-screen-right{grid-column:body-content-start/page-end;z-index:998;opacity:.999}.page-columns .column-screen-right table{background:#222}.page-columns .column-screen-inset-shaded{grid-column:page-start-inset/page-end-inset;padding:1em;background:#6f6f6f;z-index:998;opacity:.999;margin-bottom:1em}}.quarto-video{margin-bottom:1em}.table{border-top:1px solid #fff;border-bottom:1px solid #fff}.table>thead{border-top-width:0;border-bottom:1px solid #fff}.table a{word-break:break-word}.table>:not(caption)>*>*{background-color:unset;color:unset}#quarto-document-content .crosstalk-input .checkbox input[type=checkbox],#quarto-document-content .crosstalk-input .checkbox-inline input[type=checkbox]{position:unset;margin-top:unset;margin-left:unset}#quarto-document-content .row{margin-left:unset;margin-right:unset}.quarto-xref{white-space:nowrap}#quarto-draft-alert{margin-top:0px;margin-bottom:0px;padding:.3em;text-align:center;font-size:.9em}#quarto-draft-alert i{margin-right:.3em}a.external:after{content:"";background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(0, 188, 140)" class="bi bi-box-arrow-up-right" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8.636 3.5a.5.5 0 0 0-.5-.5H1.5A1.5 1.5 0 0 0 0 4.5v10A1.5 1.5 0 0 0 1.5 16h10a1.5 1.5 0 0 0 1.5-1.5V7.864a.5.5 0 0 0-1 0V14.5a.5.5 0 0 1-.5.5h-10a.5.5 0 0 1-.5-.5v-10a.5.5 0 0 1 .5-.5h6.636a.5.5 0 0 0 .5-.5z"/><path fill-rule="evenodd" d="M16 .5a.5.5 0 0 0-.5-.5h-5a.5.5 0 0 0 0 1h3.793L6.146 9.146a.5.5 0 1 0 .708.708L15 1.707V5.5a.5.5 0 0 0 1 0v-5z"/></svg>');background-size:contain;background-repeat:no-repeat;background-position:center center;margin-left:.2em;padding-right:.75em}div.sourceCode code a.external:after{content:none}a.external:after:hover{cursor:pointer}.quarto-ext-icon{display:inline-block;font-size:.75em;padding-left:.3em}.code-with-filename .code-with-filename-file{margin-bottom:0;padding-bottom:2px;padding-top:2px;padding-left:.7em;border:var(--quarto-border-width) solid var(--quarto-border-color);border-radius:var(--quarto-border-radius);border-bottom:0;border-bottom-left-radius:0%;border-bottom-right-radius:0%}.code-with-filename div.sourceCode,.reveal .code-with-filename div.sourceCode{margin-top:0;border-top-left-radius:0%;border-top-right-radius:0%}.code-with-filename .code-with-filename-file pre{margin-bottom:0}.code-with-filename .code-with-filename-file{background-color:rgba(219,219,219,.8)}.quarto-dark .code-with-filename .code-with-filename-file{background-color:#555}.code-with-filename .code-with-filename-file strong{font-weight:400}.blockquote-footer{color:#595959}.form-floating>label,.form-floating>.form-control:focus~label,.form-floating>.form-control:not(:placeholder-shown)~label{color:#595959}.nav-tabs .nav-link,.nav-tabs .nav-link.active,.nav-tabs .nav-link.active:focus,.nav-tabs .nav-link.active:hover,.nav-tabs .nav-item.open .nav-link,.nav-tabs .nav-item.open .nav-link:focus,.nav-tabs .nav-item.open .nav-link:hover,.nav-pills .nav-link,.nav-pills .nav-link.active,.nav-pills .nav-link.active:focus,.nav-pills .nav-link.active:hover,.nav-pills .nav-item.open .nav-link,.nav-pills .nav-item.open .nav-link:focus,.nav-pills .nav-item.open .nav-link:hover{color:#fff}.breadcrumb a{color:#fff}.pagination a:hover{text-decoration:none}.alert{color:#fff;border:none}.alert a,.alert .alert-link{color:#fff;text-decoration:underline}.alert-default{background-color:#434343}.alert-primary{background-color:#375a7f}.alert-secondary{background-color:#434343}.alert-success{background-color:#00bc8c}.alert-info{background-color:#3498db}.alert-warning{background-color:#f39c12}.alert-danger{background-color:#e74c3c}.alert-light{background-color:#6f6f6f}.alert-dark{background-color:#2d2d2d}.tooltip{--bs-tooltip-bg: var(--bs-tertiary-bg);--bs-tooltip-color: var(--bs-emphasis-color)}.quarto-title-banner{margin-bottom:1em;color:#dee2e6;background:#375a7f}.quarto-title-banner a{color:#dee2e6}.quarto-title-banner h1,.quarto-title-banner .h1,.quarto-title-banner h2,.quarto-title-banner .h2{color:#dee2e6}.quarto-title-banner .code-tools-button{color:#a4afba}.quarto-title-banner .code-tools-button:hover{color:#dee2e6}.quarto-title-banner .code-tools-button>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(164, 175, 186)" viewBox="0 0 16 16"><path d="M10.478 1.647a.5.5 0 1 0-.956-.294l-4 13a.5.5 0 0 0 .956.294l4-13zM4.854 4.146a.5.5 0 0 1 0 .708L1.707 8l3.147 3.146a.5.5 0 0 1-.708.708l-3.5-3.5a.5.5 0 0 1 0-.708l3.5-3.5a.5.5 0 0 1 .708 0zm6.292 0a.5.5 0 0 0 0 .708L14.293 8l-3.147 3.146a.5.5 0 0 0 .708.708l3.5-3.5a.5.5 0 0 0 0-.708l-3.5-3.5a.5.5 0 0 0-.708 0z"/></svg>')}.quarto-title-banner .code-tools-button:hover>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(222, 226, 230)" viewBox="0 0 16 16"><path d="M10.478 1.647a.5.5 0 1 0-.956-.294l-4 13a.5.5 0 0 0 .956.294l4-13zM4.854 4.146a.5.5 0 0 1 0 .708L1.707 8l3.147 3.146a.5.5 0 0 1-.708.708l-3.5-3.5a.5.5 0 0 1 0-.708l3.5-3.5a.5.5 0 0 1 .708 0zm6.292 0a.5.5 0 0 0 0 .708L14.293 8l-3.147 3.146a.5.5 0 0 0 .708.708l3.5-3.5a.5.5 0 0 0 0-.708l-3.5-3.5a.5.5 0 0 0-.708 0z"/></svg>')}.quarto-title-banner .quarto-title .title{font-weight:600}.quarto-title-banner .quarto-categories{margin-top:.75em}@media(min-width: 992px){.quarto-title-banner{padding-top:2.5em;padding-bottom:2.5em}}@media(max-width: 991.98px){.quarto-title-banner{padding-top:1em;padding-bottom:1em}}@media(max-width: 767.98px){body.hypothesis-enabled #title-block-header>*{padding-right:20px}}main.quarto-banner-title-block>section:first-child>h2,main.quarto-banner-title-block>section:first-child>.h2,main.quarto-banner-title-block>section:first-child>h3,main.quarto-banner-title-block>section:first-child>.h3,main.quarto-banner-title-block>section:first-child>h4,main.quarto-banner-title-block>section:first-child>.h4{margin-top:0}.quarto-title .quarto-categories{display:flex;flex-wrap:wrap;row-gap:.5em;column-gap:.4em;padding-bottom:.5em;margin-top:.75em}.quarto-title .quarto-categories .quarto-category{padding:.25em .75em;font-size:.65em;text-transform:uppercase;border:solid 1px;border-radius:.25rem;opacity:.6}.quarto-title .quarto-categories .quarto-category a{color:inherit}.quarto-title-meta-container{display:grid;grid-template-columns:1fr auto}.quarto-title-meta-column-end{display:flex;flex-direction:column;padding-left:1em}.quarto-title-meta-column-end a .bi{margin-right:.3em}#title-block-header.quarto-title-block.default .quarto-title-meta{display:grid;grid-template-columns:repeat(2, 1fr);grid-column-gap:1em}#title-block-header.quarto-title-block.default .quarto-title .title{margin-bottom:0}#title-block-header.quarto-title-block.default .quarto-title-author-orcid img{margin-top:-0.2em;height:.8em;width:.8em}#title-block-header.quarto-title-block.default .quarto-title-author-email{opacity:.7}#title-block-header.quarto-title-block.default .quarto-description p:last-of-type{margin-bottom:0}#title-block-header.quarto-title-block.default .quarto-title-meta-contents p,#title-block-header.quarto-title-block.default .quarto-title-authors p,#title-block-header.quarto-title-block.default .quarto-title-affiliations p{margin-bottom:.1em}#title-block-header.quarto-title-block.default .quarto-title-meta-heading{text-transform:uppercase;margin-top:1em;font-size:.8em;opacity:.8;font-weight:400}#title-block-header.quarto-title-block.default .quarto-title-meta-contents{font-size:.9em}#title-block-header.quarto-title-block.default .quarto-title-meta-contents p.affiliation:last-of-type{margin-bottom:.1em}#title-block-header.quarto-title-block.default p.affiliation{margin-bottom:.1em}#title-block-header.quarto-title-block.default .keywords,#title-block-header.quarto-title-block.default .description,#title-block-header.quarto-title-block.default .abstract{margin-top:0}#title-block-header.quarto-title-block.default .keywords>p,#title-block-header.quarto-title-block.default .description>p,#title-block-header.quarto-title-block.default .abstract>p{font-size:.9em}#title-block-header.quarto-title-block.default .keywords>p:last-of-type,#title-block-header.quarto-title-block.default .description>p:last-of-type,#title-block-header.quarto-title-block.default .abstract>p:last-of-type{margin-bottom:0}#title-block-header.quarto-title-block.default .keywords .block-title,#title-block-header.quarto-title-block.default .description .block-title,#title-block-header.quarto-title-block.default .abstract .block-title{margin-top:1em;text-transform:uppercase;font-size:.8em;opacity:.8;font-weight:400}#title-block-header.quarto-title-block.default .quarto-title-meta-author{display:grid;grid-template-columns:minmax(max-content, 1fr) 1fr;grid-column-gap:1em}.quarto-title-tools-only{display:flex;justify-content:right}
+*/.ansi-black-fg{color:#3e424d}.ansi-black-bg{background-color:#3e424d}.ansi-black-intense-black,.ansi-bright-black-fg{color:#282c36}.ansi-black-intense-black,.ansi-bright-black-bg{background-color:#282c36}.ansi-red-fg{color:#e75c58}.ansi-red-bg{background-color:#e75c58}.ansi-red-intense-red,.ansi-bright-red-fg{color:#b22b31}.ansi-red-intense-red,.ansi-bright-red-bg{background-color:#b22b31}.ansi-green-fg{color:#00a250}.ansi-green-bg{background-color:#00a250}.ansi-green-intense-green,.ansi-bright-green-fg{color:#007427}.ansi-green-intense-green,.ansi-bright-green-bg{background-color:#007427}.ansi-yellow-fg{color:#ddb62b}.ansi-yellow-bg{background-color:#ddb62b}.ansi-yellow-intense-yellow,.ansi-bright-yellow-fg{color:#b27d12}.ansi-yellow-intense-yellow,.ansi-bright-yellow-bg{background-color:#b27d12}.ansi-blue-fg{color:#208ffb}.ansi-blue-bg{background-color:#208ffb}.ansi-blue-intense-blue,.ansi-bright-blue-fg{color:#0065ca}.ansi-blue-intense-blue,.ansi-bright-blue-bg{background-color:#0065ca}.ansi-magenta-fg{color:#d160c4}.ansi-magenta-bg{background-color:#d160c4}.ansi-magenta-intense-magenta,.ansi-bright-magenta-fg{color:#a03196}.ansi-magenta-intense-magenta,.ansi-bright-magenta-bg{background-color:#a03196}.ansi-cyan-fg{color:#60c6c8}.ansi-cyan-bg{background-color:#60c6c8}.ansi-cyan-intense-cyan,.ansi-bright-cyan-fg{color:#258f8f}.ansi-cyan-intense-cyan,.ansi-bright-cyan-bg{background-color:#258f8f}.ansi-white-fg{color:#c5c1b4}.ansi-white-bg{background-color:#c5c1b4}.ansi-white-intense-white,.ansi-bright-white-fg{color:#a1a6b2}.ansi-white-intense-white,.ansi-bright-white-bg{background-color:#a1a6b2}.ansi-default-inverse-fg{color:#fff}.ansi-default-inverse-bg{background-color:#000}.ansi-bold{font-weight:bold}.ansi-underline{text-decoration:underline}:root{--quarto-body-bg: #222;--quarto-body-color: #fff;--quarto-text-muted: #6c757d;--quarto-border-color: #434343;--quarto-border-width: 1px;--quarto-border-radius: 0.25rem}table.gt_table{color:var(--quarto-body-color);font-size:1em;width:100%;background-color:rgba(0,0,0,0);border-top-width:inherit;border-bottom-width:inherit;border-color:var(--quarto-border-color)}table.gt_table th.gt_column_spanner_outer{color:var(--quarto-body-color);background-color:rgba(0,0,0,0);border-top-width:inherit;border-bottom-width:inherit;border-color:var(--quarto-border-color)}table.gt_table th.gt_col_heading{color:var(--quarto-body-color);font-weight:bold;background-color:rgba(0,0,0,0)}table.gt_table thead.gt_col_headings{border-bottom:1px solid currentColor;border-top-width:inherit;border-top-color:var(--quarto-border-color)}table.gt_table thead.gt_col_headings:not(:first-child){border-top-width:1px;border-top-color:var(--quarto-border-color)}table.gt_table td.gt_row{border-bottom-width:1px;border-bottom-color:var(--quarto-border-color);border-top-width:0px}table.gt_table tbody.gt_table_body{border-top-width:1px;border-bottom-width:1px;border-bottom-color:var(--quarto-border-color);border-top-color:currentColor}div.columns{display:initial;gap:initial}div.column{display:inline-block;overflow-x:initial;vertical-align:top;width:50%}.code-annotation-tip-content{word-wrap:break-word}.code-annotation-container-hidden{display:none !important}dl.code-annotation-container-grid{display:grid;grid-template-columns:min-content auto}dl.code-annotation-container-grid dt{grid-column:1}dl.code-annotation-container-grid dd{grid-column:2}pre.sourceCode.code-annotation-code{padding-right:0}code.sourceCode .code-annotation-anchor{z-index:100;position:relative;float:right;background-color:rgba(0,0,0,0)}input[type=checkbox]{margin-right:.5ch}:root{--mermaid-bg-color: #222;--mermaid-edge-color: #434343;--mermaid-node-fg-color: #fff;--mermaid-fg-color: #fff;--mermaid-fg-color--lighter: white;--mermaid-fg-color--lightest: white;--mermaid-font-family: Lato, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica Neue, Arial, sans-serif, Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol;--mermaid-label-bg-color: #222;--mermaid-label-fg-color: #375a7f;--mermaid-node-bg-color: rgba(55, 90, 127, 0.1);--mermaid-node-fg-color: #fff}@media print{:root{font-size:11pt}#quarto-sidebar,#TOC,.nav-page{display:none}.page-columns .content{grid-column-start:page-start}.fixed-top{position:relative}.panel-caption,.figure-caption,figcaption{color:#666}}.code-copy-button{position:absolute;top:0;right:0;border:0;margin-top:5px;margin-right:5px;background-color:rgba(0,0,0,0);z-index:3}.code-copy-button:focus{outline:none}.code-copy-button-tooltip{font-size:.75em}pre.sourceCode:hover>.code-copy-button>.bi::before{display:inline-block;height:1rem;width:1rem;content:"";vertical-align:-0.125em;background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(106, 115, 125)" viewBox="0 0 16 16"><path d="M4 1.5H3a2 2 0 0 0-2 2V14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V3.5a2 2 0 0 0-2-2h-1v1h1a1 1 0 0 1 1 1V14a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V3.5a1 1 0 0 1 1-1h1v-1z"/><path d="M9.5 1a.5.5 0 0 1 .5.5v1a.5.5 0 0 1-.5.5h-3a.5.5 0 0 1-.5-.5v-1a.5.5 0 0 1 .5-.5h3zm-3-1A1.5 1.5 0 0 0 5 1.5v1A1.5 1.5 0 0 0 6.5 4h3A1.5 1.5 0 0 0 11 2.5v-1A1.5 1.5 0 0 0 9.5 0h-3z"/></svg>');background-repeat:no-repeat;background-size:1rem 1rem}pre.sourceCode:hover>.code-copy-button-checked>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(106, 115, 125)" viewBox="0 0 16 16"><path d="M13.854 3.646a.5.5 0 0 1 0 .708l-7 7a.5.5 0 0 1-.708 0l-3.5-3.5a.5.5 0 1 1 .708-.708L6.5 10.293l6.646-6.647a.5.5 0 0 1 .708 0z"/></svg>')}pre.sourceCode:hover>.code-copy-button:hover>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(179, 146, 240)" viewBox="0 0 16 16"><path d="M4 1.5H3a2 2 0 0 0-2 2V14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V3.5a2 2 0 0 0-2-2h-1v1h1a1 1 0 0 1 1 1V14a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V3.5a1 1 0 0 1 1-1h1v-1z"/><path d="M9.5 1a.5.5 0 0 1 .5.5v1a.5.5 0 0 1-.5.5h-3a.5.5 0 0 1-.5-.5v-1a.5.5 0 0 1 .5-.5h3zm-3-1A1.5 1.5 0 0 0 5 1.5v1A1.5 1.5 0 0 0 6.5 4h3A1.5 1.5 0 0 0 11 2.5v-1A1.5 1.5 0 0 0 9.5 0h-3z"/></svg>')}pre.sourceCode:hover>.code-copy-button-checked:hover>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(179, 146, 240)"  viewBox="0 0 16 16"><path d="M13.854 3.646a.5.5 0 0 1 0 .708l-7 7a.5.5 0 0 1-.708 0l-3.5-3.5a.5.5 0 1 1 .708-.708L6.5 10.293l6.646-6.647a.5.5 0 0 1 .708 0z"/></svg>')}main ol ol,main ul ul,main ol ul,main ul ol{margin-bottom:1em}ul>li:not(:has(>p))>ul,ol>li:not(:has(>p))>ul,ul>li:not(:has(>p))>ol,ol>li:not(:has(>p))>ol{margin-bottom:0}ul>li:not(:has(>p))>ul>li:has(>p),ol>li:not(:has(>p))>ul>li:has(>p),ul>li:not(:has(>p))>ol>li:has(>p),ol>li:not(:has(>p))>ol>li:has(>p){margin-top:1rem}body{margin:0}main.page-columns>header>h1.title,main.page-columns>header>.title.h1{margin-bottom:0}@media(min-width: 992px){body .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start page-start-inset] 35px [body-start-outset] 35px [body-start] 1.5em [body-content-start] minmax(500px, calc(850px - 3em)) [body-content-end] 1.5em [body-end] 35px [body-end-outset] minmax(75px, 145px) [page-end-inset] 35px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.fullcontent:not(.floating):not(.docked) .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start page-start-inset] 35px [body-start-outset] 35px [body-start] 1.5em [body-content-start] minmax(500px, calc(850px - 3em)) [body-content-end] 1.5em [body-end] 35px [body-end-outset] 35px [page-end-inset page-end] 5fr [screen-end-inset] 1.5em}body.slimcontent:not(.floating):not(.docked) .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start page-start-inset] 35px [body-start-outset] 35px [body-start] 1.5em [body-content-start] minmax(500px, calc(850px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(0px, 200px) [page-end-inset] 35px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.listing:not(.floating):not(.docked) .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start] minmax(50px, 100px) [page-start-inset] 50px [body-start-outset] 50px [body-start] 1.5em [body-content-start] minmax(500px, calc(850px - 3em)) [body-content-end] 3em [body-end] 50px [body-end-outset] minmax(0px, 250px) [page-end-inset] minmax(50px, 100px) [page-end] 1fr [screen-end-inset] 1.5em [screen-end]}body:not(.floating):not(.docked) .page-columns.toc-left{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] 35px [page-start-inset] minmax(0px, 175px) [body-start-outset] 35px [body-start] 1.5em [body-content-start] minmax(450px, calc(800px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(0px, 200px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body:not(.floating):not(.docked) .page-columns.toc-left .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] 35px [page-start-inset] minmax(0px, 175px) [body-start-outset] 35px [body-start] 1.5em [body-content-start] minmax(450px, calc(800px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(0px, 200px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.floating .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] minmax(25px, 50px) [page-start-inset] minmax(50px, 150px) [body-start-outset] minmax(25px, 50px) [body-start] 1.5em [body-content-start] minmax(500px, calc(800px - 3em)) [body-content-end] 1.5em [body-end] minmax(25px, 50px) [body-end-outset] minmax(50px, 150px) [page-end-inset] minmax(25px, 50px) [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.docked .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start] minmax(50px, 100px) [page-start-inset] 50px [body-start-outset] 50px [body-start] 1.5em [body-content-start] minmax(500px, calc(1000px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(50px, 100px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.docked.fullcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start] minmax(50px, 100px) [page-start-inset] 50px [body-start-outset] 50px [body-start] 1.5em [body-content-start] minmax(500px, calc(1000px - 3em)) [body-content-end] 1.5em [body-end body-end-outset page-end-inset page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.floating.fullcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] 50px [page-start-inset] minmax(50px, 150px) [body-start-outset] 50px [body-start] 1.5em [body-content-start] minmax(500px, calc(800px - 3em)) [body-content-end] 1.5em [body-end body-end-outset page-end-inset page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.docked.slimcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start] minmax(50px, 100px) [page-start-inset] 50px [body-start-outset] 50px [body-start] 1.5em [body-content-start] minmax(450px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(0px, 200px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.docked.listing .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start] minmax(50px, 100px) [page-start-inset] 50px [body-start-outset] 50px [body-start] 1.5em [body-content-start] minmax(500px, calc(1000px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(0px, 200px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.floating.slimcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] 50px [page-start-inset] minmax(50px, 150px) [body-start-outset] 50px [body-start] 1.5em [body-content-start] minmax(450px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(50px, 150px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.floating.listing .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] minmax(25px, 50px) [page-start-inset] minmax(50px, 150px) [body-start-outset] minmax(25px, 50px) [body-start] 1.5em [body-content-start] minmax(500px, calc(800px - 3em)) [body-content-end] 1.5em [body-end] minmax(25px, 50px) [body-end-outset] minmax(50px, 150px) [page-end-inset] minmax(25px, 50px) [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}}@media(max-width: 991.98px){body .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset] 5fr [body-start] 1.5em [body-content-start] minmax(500px, calc(800px - 3em)) [body-content-end] 1.5em [body-end] 35px [body-end-outset] minmax(75px, 145px) [page-end-inset] 35px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.fullcontent:not(.floating):not(.docked) .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset] 5fr [body-start] 1.5em [body-content-start] minmax(500px, calc(800px - 3em)) [body-content-end] 1.5em [body-end body-end-outset page-end-inset page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.slimcontent:not(.floating):not(.docked) .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset] 5fr [body-start] 1.5em [body-content-start] minmax(500px, calc(800px - 3em)) [body-content-end] 1.5em [body-end] 35px [body-end-outset] minmax(75px, 145px) [page-end-inset] 35px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.listing:not(.floating):not(.docked) .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset] 5fr [body-start] 1.5em [body-content-start] minmax(500px, calc(1250px - 3em)) [body-content-end body-end body-end-outset page-end-inset page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body:not(.floating):not(.docked) .page-columns.toc-left{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] 35px [page-start-inset] minmax(0px, 145px) [body-start-outset] 35px [body-start] 1.5em [body-content-start] minmax(450px, calc(800px - 3em)) [body-content-end] 1.5em [body-end body-end-outset page-end-inset page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body:not(.floating):not(.docked) .page-columns.toc-left .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] 35px [page-start-inset] minmax(0px, 145px) [body-start-outset] 35px [body-start] 1.5em [body-content-start] minmax(450px, calc(800px - 3em)) [body-content-end] 1.5em [body-end body-end-outset page-end-inset page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.floating .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start page-start-inset body-start-outset body-start] 1.5em [body-content-start] minmax(500px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(75px, 150px) [page-end-inset] 25px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.docked .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset body-start body-content-start] minmax(500px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(25px, 50px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.docked.fullcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset body-start body-content-start] minmax(500px, calc(1000px - 3em)) [body-content-end] 1.5em [body-end body-end-outset page-end-inset page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.floating.fullcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start page-start-inset body-start-outset body-start] 1em [body-content-start] minmax(500px, calc(800px - 3em)) [body-content-end] 1.5em [body-end body-end-outset page-end-inset page-end] 4fr [screen-end-inset] 1.5em [screen-end]}body.docked.slimcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset body-start body-content-start] minmax(500px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(25px, 50px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.docked.listing .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset body-start body-content-start] minmax(500px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(25px, 50px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.floating.slimcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start page-start-inset body-start-outset body-start] 1em [body-content-start] minmax(500px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 35px [body-end-outset] minmax(75px, 145px) [page-end-inset] 35px [page-end] 4fr [screen-end-inset] 1.5em [screen-end]}body.floating.listing .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start page-start-inset body-start-outset body-start] 1em [body-content-start] minmax(500px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(75px, 150px) [page-end-inset] 25px [page-end] 4fr [screen-end-inset] 1.5em [screen-end]}}@media(max-width: 767.98px){body .page-columns,body.fullcontent:not(.floating):not(.docked) .page-columns,body.slimcontent:not(.floating):not(.docked) .page-columns,body.docked .page-columns,body.docked.slimcontent .page-columns,body.docked.fullcontent .page-columns,body.floating .page-columns,body.floating.slimcontent .page-columns,body.floating.fullcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset body-start body-content-start] minmax(0px, 1fr) [body-content-end body-end body-end-outset page-end-inset page-end screen-end-inset] 1.5em [screen-end]}body:not(.floating):not(.docked) .page-columns.toc-left{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset body-start body-content-start] minmax(0px, 1fr) [body-content-end body-end body-end-outset page-end-inset page-end screen-end-inset] 1.5em [screen-end]}body:not(.floating):not(.docked) .page-columns.toc-left .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset body-start body-content-start] minmax(0px, 1fr) [body-content-end body-end body-end-outset page-end-inset page-end screen-end-inset] 1.5em [screen-end]}nav[role=doc-toc]{display:none}}body,.page-row-navigation{grid-template-rows:[page-top] max-content [contents-top] max-content [contents-bottom] max-content [page-bottom]}.page-rows-contents{grid-template-rows:[content-top] minmax(max-content, 1fr) [content-bottom] minmax(60px, max-content) [page-bottom]}.page-full{grid-column:screen-start/screen-end !important}.page-columns>*{grid-column:body-content-start/body-content-end}.page-columns.column-page>*{grid-column:page-start/page-end}.page-columns.column-page-left .page-columns.page-full>*,.page-columns.column-page-left>*{grid-column:page-start/body-content-end}.page-columns.column-page-right .page-columns.page-full>*,.page-columns.column-page-right>*{grid-column:body-content-start/page-end}.page-rows{grid-auto-rows:auto}.header{grid-column:screen-start/screen-end;grid-row:page-top/contents-top}#quarto-content{padding:0;grid-column:screen-start/screen-end;grid-row:contents-top/contents-bottom}body.floating .sidebar.sidebar-navigation{grid-column:page-start/body-start;grid-row:content-top/page-bottom}body.docked .sidebar.sidebar-navigation{grid-column:screen-start/body-start;grid-row:content-top/page-bottom}.sidebar.toc-left{grid-column:page-start/body-start;grid-row:content-top/page-bottom}.sidebar.margin-sidebar{grid-column:body-end/page-end;grid-row:content-top/page-bottom}.page-columns .content{grid-column:body-content-start/body-content-end;grid-row:content-top/content-bottom;align-content:flex-start}.page-columns .page-navigation{grid-column:body-content-start/body-content-end;grid-row:content-bottom/page-bottom}.page-columns .footer{grid-column:screen-start/screen-end;grid-row:contents-bottom/page-bottom}.page-columns .column-body{grid-column:body-content-start/body-content-end}.page-columns .column-body-fullbleed{grid-column:body-start/body-end}.page-columns .column-body-outset{grid-column:body-start-outset/body-end-outset;z-index:998;opacity:.999}.page-columns .column-body-outset table{background:#222}.page-columns .column-body-outset-left{grid-column:body-start-outset/body-content-end;z-index:998;opacity:.999}.page-columns .column-body-outset-left table{background:#222}.page-columns .column-body-outset-right{grid-column:body-content-start/body-end-outset;z-index:998;opacity:.999}.page-columns .column-body-outset-right table{background:#222}.page-columns .column-page{grid-column:page-start/page-end;z-index:998;opacity:.999}.page-columns .column-page table{background:#222}.page-columns .column-page-inset{grid-column:page-start-inset/page-end-inset;z-index:998;opacity:.999}.page-columns .column-page-inset table{background:#222}.page-columns .column-page-inset-left{grid-column:page-start-inset/body-content-end;z-index:998;opacity:.999}.page-columns .column-page-inset-left table{background:#222}.page-columns .column-page-inset-right{grid-column:body-content-start/page-end-inset;z-index:998;opacity:.999}.page-columns .column-page-inset-right figcaption table{background:#222}.page-columns .column-page-left{grid-column:page-start/body-content-end;z-index:998;opacity:.999}.page-columns .column-page-left table{background:#222}.page-columns .column-page-right{grid-column:body-content-start/page-end;z-index:998;opacity:.999}.page-columns .column-page-right figcaption table{background:#222}#quarto-content.page-columns #quarto-margin-sidebar,#quarto-content.page-columns #quarto-sidebar{z-index:1}@media(max-width: 991.98px){#quarto-content.page-columns #quarto-margin-sidebar.collapse,#quarto-content.page-columns #quarto-sidebar.collapse,#quarto-content.page-columns #quarto-margin-sidebar.collapsing,#quarto-content.page-columns #quarto-sidebar.collapsing{z-index:1055}}#quarto-content.page-columns main.column-page,#quarto-content.page-columns main.column-page-right,#quarto-content.page-columns main.column-page-left{z-index:0}.page-columns .column-screen-inset{grid-column:screen-start-inset/screen-end-inset;z-index:998;opacity:.999}.page-columns .column-screen-inset table{background:#222}.page-columns .column-screen-inset-left{grid-column:screen-start-inset/body-content-end;z-index:998;opacity:.999}.page-columns .column-screen-inset-left table{background:#222}.page-columns .column-screen-inset-right{grid-column:body-content-start/screen-end-inset;z-index:998;opacity:.999}.page-columns .column-screen-inset-right table{background:#222}.page-columns .column-screen{grid-column:screen-start/screen-end;z-index:998;opacity:.999}.page-columns .column-screen table{background:#222}.page-columns .column-screen-left{grid-column:screen-start/body-content-end;z-index:998;opacity:.999}.page-columns .column-screen-left table{background:#222}.page-columns .column-screen-right{grid-column:body-content-start/screen-end;z-index:998;opacity:.999}.page-columns .column-screen-right table{background:#222}.page-columns .column-screen-inset-shaded{grid-column:screen-start/screen-end;padding:1em;background:#6f6f6f;z-index:998;opacity:.999;margin-bottom:1em}.zindex-content{z-index:998;opacity:.999}.zindex-modal{z-index:1055;opacity:.999}.zindex-over-content{z-index:999;opacity:.999}img.img-fluid.column-screen,img.img-fluid.column-screen-inset-shaded,img.img-fluid.column-screen-inset,img.img-fluid.column-screen-inset-left,img.img-fluid.column-screen-inset-right,img.img-fluid.column-screen-left,img.img-fluid.column-screen-right{width:100%}@media(min-width: 992px){.margin-caption,div.aside,aside:not(.footnotes):not(.sidebar),.column-margin{grid-column:body-end/page-end !important;z-index:998}.column-sidebar{grid-column:page-start/body-start !important;z-index:998}.column-leftmargin{grid-column:screen-start-inset/body-start !important;z-index:998}.no-row-height{height:1em;overflow:visible}}@media(max-width: 991.98px){.margin-caption,div.aside,aside:not(.footnotes):not(.sidebar),.column-margin{grid-column:body-end/page-end !important;z-index:998}.no-row-height{height:1em;overflow:visible}.page-columns.page-full{overflow:visible}.page-columns.toc-left .margin-caption,.page-columns.toc-left div.aside,.page-columns.toc-left aside:not(.footnotes):not(.sidebar),.page-columns.toc-left .column-margin{grid-column:body-content-start/body-content-end !important;z-index:998;opacity:.999}.page-columns.toc-left .no-row-height{height:initial;overflow:initial}}@media(max-width: 767.98px){.margin-caption,div.aside,aside:not(.footnotes):not(.sidebar),.column-margin{grid-column:body-content-start/body-content-end !important;z-index:998;opacity:.999}.no-row-height{height:initial;overflow:initial}#quarto-margin-sidebar{display:none}#quarto-sidebar-toc-left{display:none}.hidden-sm{display:none}}.panel-grid{display:grid;grid-template-rows:repeat(1, 1fr);grid-template-columns:repeat(24, 1fr);gap:1em}.panel-grid .g-col-1{grid-column:auto/span 1}.panel-grid .g-col-2{grid-column:auto/span 2}.panel-grid .g-col-3{grid-column:auto/span 3}.panel-grid .g-col-4{grid-column:auto/span 4}.panel-grid .g-col-5{grid-column:auto/span 5}.panel-grid .g-col-6{grid-column:auto/span 6}.panel-grid .g-col-7{grid-column:auto/span 7}.panel-grid .g-col-8{grid-column:auto/span 8}.panel-grid .g-col-9{grid-column:auto/span 9}.panel-grid .g-col-10{grid-column:auto/span 10}.panel-grid .g-col-11{grid-column:auto/span 11}.panel-grid .g-col-12{grid-column:auto/span 12}.panel-grid .g-col-13{grid-column:auto/span 13}.panel-grid .g-col-14{grid-column:auto/span 14}.panel-grid .g-col-15{grid-column:auto/span 15}.panel-grid .g-col-16{grid-column:auto/span 16}.panel-grid .g-col-17{grid-column:auto/span 17}.panel-grid .g-col-18{grid-column:auto/span 18}.panel-grid .g-col-19{grid-column:auto/span 19}.panel-grid .g-col-20{grid-column:auto/span 20}.panel-grid .g-col-21{grid-column:auto/span 21}.panel-grid .g-col-22{grid-column:auto/span 22}.panel-grid .g-col-23{grid-column:auto/span 23}.panel-grid .g-col-24{grid-column:auto/span 24}.panel-grid .g-start-1{grid-column-start:1}.panel-grid .g-start-2{grid-column-start:2}.panel-grid .g-start-3{grid-column-start:3}.panel-grid .g-start-4{grid-column-start:4}.panel-grid .g-start-5{grid-column-start:5}.panel-grid .g-start-6{grid-column-start:6}.panel-grid .g-start-7{grid-column-start:7}.panel-grid .g-start-8{grid-column-start:8}.panel-grid .g-start-9{grid-column-start:9}.panel-grid .g-start-10{grid-column-start:10}.panel-grid .g-start-11{grid-column-start:11}.panel-grid .g-start-12{grid-column-start:12}.panel-grid .g-start-13{grid-column-start:13}.panel-grid .g-start-14{grid-column-start:14}.panel-grid .g-start-15{grid-column-start:15}.panel-grid .g-start-16{grid-column-start:16}.panel-grid .g-start-17{grid-column-start:17}.panel-grid .g-start-18{grid-column-start:18}.panel-grid .g-start-19{grid-column-start:19}.panel-grid .g-start-20{grid-column-start:20}.panel-grid .g-start-21{grid-column-start:21}.panel-grid .g-start-22{grid-column-start:22}.panel-grid .g-start-23{grid-column-start:23}@media(min-width: 576px){.panel-grid .g-col-sm-1{grid-column:auto/span 1}.panel-grid .g-col-sm-2{grid-column:auto/span 2}.panel-grid .g-col-sm-3{grid-column:auto/span 3}.panel-grid .g-col-sm-4{grid-column:auto/span 4}.panel-grid .g-col-sm-5{grid-column:auto/span 5}.panel-grid .g-col-sm-6{grid-column:auto/span 6}.panel-grid .g-col-sm-7{grid-column:auto/span 7}.panel-grid .g-col-sm-8{grid-column:auto/span 8}.panel-grid .g-col-sm-9{grid-column:auto/span 9}.panel-grid .g-col-sm-10{grid-column:auto/span 10}.panel-grid .g-col-sm-11{grid-column:auto/span 11}.panel-grid .g-col-sm-12{grid-column:auto/span 12}.panel-grid .g-col-sm-13{grid-column:auto/span 13}.panel-grid .g-col-sm-14{grid-column:auto/span 14}.panel-grid .g-col-sm-15{grid-column:auto/span 15}.panel-grid .g-col-sm-16{grid-column:auto/span 16}.panel-grid .g-col-sm-17{grid-column:auto/span 17}.panel-grid .g-col-sm-18{grid-column:auto/span 18}.panel-grid .g-col-sm-19{grid-column:auto/span 19}.panel-grid .g-col-sm-20{grid-column:auto/span 20}.panel-grid .g-col-sm-21{grid-column:auto/span 21}.panel-grid .g-col-sm-22{grid-column:auto/span 22}.panel-grid .g-col-sm-23{grid-column:auto/span 23}.panel-grid .g-col-sm-24{grid-column:auto/span 24}.panel-grid .g-start-sm-1{grid-column-start:1}.panel-grid .g-start-sm-2{grid-column-start:2}.panel-grid .g-start-sm-3{grid-column-start:3}.panel-grid .g-start-sm-4{grid-column-start:4}.panel-grid .g-start-sm-5{grid-column-start:5}.panel-grid .g-start-sm-6{grid-column-start:6}.panel-grid .g-start-sm-7{grid-column-start:7}.panel-grid .g-start-sm-8{grid-column-start:8}.panel-grid .g-start-sm-9{grid-column-start:9}.panel-grid .g-start-sm-10{grid-column-start:10}.panel-grid .g-start-sm-11{grid-column-start:11}.panel-grid .g-start-sm-12{grid-column-start:12}.panel-grid .g-start-sm-13{grid-column-start:13}.panel-grid .g-start-sm-14{grid-column-start:14}.panel-grid .g-start-sm-15{grid-column-start:15}.panel-grid .g-start-sm-16{grid-column-start:16}.panel-grid .g-start-sm-17{grid-column-start:17}.panel-grid .g-start-sm-18{grid-column-start:18}.panel-grid .g-start-sm-19{grid-column-start:19}.panel-grid .g-start-sm-20{grid-column-start:20}.panel-grid .g-start-sm-21{grid-column-start:21}.panel-grid .g-start-sm-22{grid-column-start:22}.panel-grid .g-start-sm-23{grid-column-start:23}}@media(min-width: 768px){.panel-grid .g-col-md-1{grid-column:auto/span 1}.panel-grid .g-col-md-2{grid-column:auto/span 2}.panel-grid .g-col-md-3{grid-column:auto/span 3}.panel-grid .g-col-md-4{grid-column:auto/span 4}.panel-grid .g-col-md-5{grid-column:auto/span 5}.panel-grid .g-col-md-6{grid-column:auto/span 6}.panel-grid .g-col-md-7{grid-column:auto/span 7}.panel-grid .g-col-md-8{grid-column:auto/span 8}.panel-grid .g-col-md-9{grid-column:auto/span 9}.panel-grid .g-col-md-10{grid-column:auto/span 10}.panel-grid .g-col-md-11{grid-column:auto/span 11}.panel-grid .g-col-md-12{grid-column:auto/span 12}.panel-grid .g-col-md-13{grid-column:auto/span 13}.panel-grid .g-col-md-14{grid-column:auto/span 14}.panel-grid .g-col-md-15{grid-column:auto/span 15}.panel-grid .g-col-md-16{grid-column:auto/span 16}.panel-grid .g-col-md-17{grid-column:auto/span 17}.panel-grid .g-col-md-18{grid-column:auto/span 18}.panel-grid .g-col-md-19{grid-column:auto/span 19}.panel-grid .g-col-md-20{grid-column:auto/span 20}.panel-grid .g-col-md-21{grid-column:auto/span 21}.panel-grid .g-col-md-22{grid-column:auto/span 22}.panel-grid .g-col-md-23{grid-column:auto/span 23}.panel-grid .g-col-md-24{grid-column:auto/span 24}.panel-grid .g-start-md-1{grid-column-start:1}.panel-grid .g-start-md-2{grid-column-start:2}.panel-grid .g-start-md-3{grid-column-start:3}.panel-grid .g-start-md-4{grid-column-start:4}.panel-grid .g-start-md-5{grid-column-start:5}.panel-grid .g-start-md-6{grid-column-start:6}.panel-grid .g-start-md-7{grid-column-start:7}.panel-grid .g-start-md-8{grid-column-start:8}.panel-grid .g-start-md-9{grid-column-start:9}.panel-grid .g-start-md-10{grid-column-start:10}.panel-grid .g-start-md-11{grid-column-start:11}.panel-grid .g-start-md-12{grid-column-start:12}.panel-grid .g-start-md-13{grid-column-start:13}.panel-grid .g-start-md-14{grid-column-start:14}.panel-grid .g-start-md-15{grid-column-start:15}.panel-grid .g-start-md-16{grid-column-start:16}.panel-grid .g-start-md-17{grid-column-start:17}.panel-grid .g-start-md-18{grid-column-start:18}.panel-grid .g-start-md-19{grid-column-start:19}.panel-grid .g-start-md-20{grid-column-start:20}.panel-grid .g-start-md-21{grid-column-start:21}.panel-grid .g-start-md-22{grid-column-start:22}.panel-grid .g-start-md-23{grid-column-start:23}}@media(min-width: 992px){.panel-grid .g-col-lg-1{grid-column:auto/span 1}.panel-grid .g-col-lg-2{grid-column:auto/span 2}.panel-grid .g-col-lg-3{grid-column:auto/span 3}.panel-grid .g-col-lg-4{grid-column:auto/span 4}.panel-grid .g-col-lg-5{grid-column:auto/span 5}.panel-grid .g-col-lg-6{grid-column:auto/span 6}.panel-grid .g-col-lg-7{grid-column:auto/span 7}.panel-grid .g-col-lg-8{grid-column:auto/span 8}.panel-grid .g-col-lg-9{grid-column:auto/span 9}.panel-grid .g-col-lg-10{grid-column:auto/span 10}.panel-grid .g-col-lg-11{grid-column:auto/span 11}.panel-grid .g-col-lg-12{grid-column:auto/span 12}.panel-grid .g-col-lg-13{grid-column:auto/span 13}.panel-grid .g-col-lg-14{grid-column:auto/span 14}.panel-grid .g-col-lg-15{grid-column:auto/span 15}.panel-grid .g-col-lg-16{grid-column:auto/span 16}.panel-grid .g-col-lg-17{grid-column:auto/span 17}.panel-grid .g-col-lg-18{grid-column:auto/span 18}.panel-grid .g-col-lg-19{grid-column:auto/span 19}.panel-grid .g-col-lg-20{grid-column:auto/span 20}.panel-grid .g-col-lg-21{grid-column:auto/span 21}.panel-grid .g-col-lg-22{grid-column:auto/span 22}.panel-grid .g-col-lg-23{grid-column:auto/span 23}.panel-grid .g-col-lg-24{grid-column:auto/span 24}.panel-grid .g-start-lg-1{grid-column-start:1}.panel-grid .g-start-lg-2{grid-column-start:2}.panel-grid .g-start-lg-3{grid-column-start:3}.panel-grid .g-start-lg-4{grid-column-start:4}.panel-grid .g-start-lg-5{grid-column-start:5}.panel-grid .g-start-lg-6{grid-column-start:6}.panel-grid .g-start-lg-7{grid-column-start:7}.panel-grid .g-start-lg-8{grid-column-start:8}.panel-grid .g-start-lg-9{grid-column-start:9}.panel-grid .g-start-lg-10{grid-column-start:10}.panel-grid .g-start-lg-11{grid-column-start:11}.panel-grid .g-start-lg-12{grid-column-start:12}.panel-grid .g-start-lg-13{grid-column-start:13}.panel-grid .g-start-lg-14{grid-column-start:14}.panel-grid .g-start-lg-15{grid-column-start:15}.panel-grid .g-start-lg-16{grid-column-start:16}.panel-grid .g-start-lg-17{grid-column-start:17}.panel-grid .g-start-lg-18{grid-column-start:18}.panel-grid .g-start-lg-19{grid-column-start:19}.panel-grid .g-start-lg-20{grid-column-start:20}.panel-grid .g-start-lg-21{grid-column-start:21}.panel-grid .g-start-lg-22{grid-column-start:22}.panel-grid .g-start-lg-23{grid-column-start:23}}@media(min-width: 1200px){.panel-grid .g-col-xl-1{grid-column:auto/span 1}.panel-grid .g-col-xl-2{grid-column:auto/span 2}.panel-grid .g-col-xl-3{grid-column:auto/span 3}.panel-grid .g-col-xl-4{grid-column:auto/span 4}.panel-grid .g-col-xl-5{grid-column:auto/span 5}.panel-grid .g-col-xl-6{grid-column:auto/span 6}.panel-grid .g-col-xl-7{grid-column:auto/span 7}.panel-grid .g-col-xl-8{grid-column:auto/span 8}.panel-grid .g-col-xl-9{grid-column:auto/span 9}.panel-grid .g-col-xl-10{grid-column:auto/span 10}.panel-grid .g-col-xl-11{grid-column:auto/span 11}.panel-grid .g-col-xl-12{grid-column:auto/span 12}.panel-grid .g-col-xl-13{grid-column:auto/span 13}.panel-grid .g-col-xl-14{grid-column:auto/span 14}.panel-grid .g-col-xl-15{grid-column:auto/span 15}.panel-grid .g-col-xl-16{grid-column:auto/span 16}.panel-grid .g-col-xl-17{grid-column:auto/span 17}.panel-grid .g-col-xl-18{grid-column:auto/span 18}.panel-grid .g-col-xl-19{grid-column:auto/span 19}.panel-grid .g-col-xl-20{grid-column:auto/span 20}.panel-grid .g-col-xl-21{grid-column:auto/span 21}.panel-grid .g-col-xl-22{grid-column:auto/span 22}.panel-grid .g-col-xl-23{grid-column:auto/span 23}.panel-grid .g-col-xl-24{grid-column:auto/span 24}.panel-grid .g-start-xl-1{grid-column-start:1}.panel-grid .g-start-xl-2{grid-column-start:2}.panel-grid .g-start-xl-3{grid-column-start:3}.panel-grid .g-start-xl-4{grid-column-start:4}.panel-grid .g-start-xl-5{grid-column-start:5}.panel-grid .g-start-xl-6{grid-column-start:6}.panel-grid .g-start-xl-7{grid-column-start:7}.panel-grid .g-start-xl-8{grid-column-start:8}.panel-grid .g-start-xl-9{grid-column-start:9}.panel-grid .g-start-xl-10{grid-column-start:10}.panel-grid .g-start-xl-11{grid-column-start:11}.panel-grid .g-start-xl-12{grid-column-start:12}.panel-grid .g-start-xl-13{grid-column-start:13}.panel-grid .g-start-xl-14{grid-column-start:14}.panel-grid .g-start-xl-15{grid-column-start:15}.panel-grid .g-start-xl-16{grid-column-start:16}.panel-grid .g-start-xl-17{grid-column-start:17}.panel-grid .g-start-xl-18{grid-column-start:18}.panel-grid .g-start-xl-19{grid-column-start:19}.panel-grid .g-start-xl-20{grid-column-start:20}.panel-grid .g-start-xl-21{grid-column-start:21}.panel-grid .g-start-xl-22{grid-column-start:22}.panel-grid .g-start-xl-23{grid-column-start:23}}@media(min-width: 1400px){.panel-grid .g-col-xxl-1{grid-column:auto/span 1}.panel-grid .g-col-xxl-2{grid-column:auto/span 2}.panel-grid .g-col-xxl-3{grid-column:auto/span 3}.panel-grid .g-col-xxl-4{grid-column:auto/span 4}.panel-grid .g-col-xxl-5{grid-column:auto/span 5}.panel-grid .g-col-xxl-6{grid-column:auto/span 6}.panel-grid .g-col-xxl-7{grid-column:auto/span 7}.panel-grid .g-col-xxl-8{grid-column:auto/span 8}.panel-grid .g-col-xxl-9{grid-column:auto/span 9}.panel-grid .g-col-xxl-10{grid-column:auto/span 10}.panel-grid .g-col-xxl-11{grid-column:auto/span 11}.panel-grid .g-col-xxl-12{grid-column:auto/span 12}.panel-grid .g-col-xxl-13{grid-column:auto/span 13}.panel-grid .g-col-xxl-14{grid-column:auto/span 14}.panel-grid .g-col-xxl-15{grid-column:auto/span 15}.panel-grid .g-col-xxl-16{grid-column:auto/span 16}.panel-grid .g-col-xxl-17{grid-column:auto/span 17}.panel-grid .g-col-xxl-18{grid-column:auto/span 18}.panel-grid .g-col-xxl-19{grid-column:auto/span 19}.panel-grid .g-col-xxl-20{grid-column:auto/span 20}.panel-grid .g-col-xxl-21{grid-column:auto/span 21}.panel-grid .g-col-xxl-22{grid-column:auto/span 22}.panel-grid .g-col-xxl-23{grid-column:auto/span 23}.panel-grid .g-col-xxl-24{grid-column:auto/span 24}.panel-grid .g-start-xxl-1{grid-column-start:1}.panel-grid .g-start-xxl-2{grid-column-start:2}.panel-grid .g-start-xxl-3{grid-column-start:3}.panel-grid .g-start-xxl-4{grid-column-start:4}.panel-grid .g-start-xxl-5{grid-column-start:5}.panel-grid .g-start-xxl-6{grid-column-start:6}.panel-grid .g-start-xxl-7{grid-column-start:7}.panel-grid .g-start-xxl-8{grid-column-start:8}.panel-grid .g-start-xxl-9{grid-column-start:9}.panel-grid .g-start-xxl-10{grid-column-start:10}.panel-grid .g-start-xxl-11{grid-column-start:11}.panel-grid .g-start-xxl-12{grid-column-start:12}.panel-grid .g-start-xxl-13{grid-column-start:13}.panel-grid .g-start-xxl-14{grid-column-start:14}.panel-grid .g-start-xxl-15{grid-column-start:15}.panel-grid .g-start-xxl-16{grid-column-start:16}.panel-grid .g-start-xxl-17{grid-column-start:17}.panel-grid .g-start-xxl-18{grid-column-start:18}.panel-grid .g-start-xxl-19{grid-column-start:19}.panel-grid .g-start-xxl-20{grid-column-start:20}.panel-grid .g-start-xxl-21{grid-column-start:21}.panel-grid .g-start-xxl-22{grid-column-start:22}.panel-grid .g-start-xxl-23{grid-column-start:23}}main{margin-top:1em;margin-bottom:1em}h1,.h1,h2,.h2{color:inherit;margin-top:2rem;margin-bottom:1rem;font-weight:600}h1.title,.title.h1{margin-top:0}main.content>section:first-of-type>h2:first-child,main.content>section:first-of-type>.h2:first-child{margin-top:0}h2,.h2{border-bottom:1px solid #434343;padding-bottom:.5rem}h3,.h3{font-weight:600}h3,.h3,h4,.h4{opacity:.9;margin-top:1.5rem}h5,.h5,h6,.h6{opacity:.9}.header-section-number{color:#bfbfbf}.nav-link.active .header-section-number{color:inherit}mark,.mark{padding:0em}.panel-caption,.figure-caption,.subfigure-caption,.table-caption,figcaption,caption{font-size:.9rem;color:#bfbfbf}.quarto-layout-cell[data-ref-parent] caption{color:#bfbfbf}.column-margin figcaption,.margin-caption,div.aside,aside,.column-margin{color:#bfbfbf;font-size:.825rem}.panel-caption.margin-caption{text-align:inherit}.column-margin.column-container p{margin-bottom:0}.column-margin.column-container>*:not(.collapse):first-child{padding-bottom:.5em;display:block}.column-margin.column-container>*:not(.collapse):not(:first-child){padding-top:.5em;padding-bottom:.5em;display:block}.column-margin.column-container>*.collapse:not(.show){display:none}@media(min-width: 768px){.column-margin.column-container .callout-margin-content:first-child{margin-top:4.5em}.column-margin.column-container .callout-margin-content-simple:first-child{margin-top:3.5em}}.margin-caption>*{padding-top:.5em;padding-bottom:.5em}@media(max-width: 767.98px){.quarto-layout-row{flex-direction:column}}.nav-tabs .nav-item{margin-top:1px;cursor:pointer}.tab-content{margin-top:0px;border-left:#434343 1px solid;border-right:#434343 1px solid;border-bottom:#434343 1px solid;margin-left:0;padding:1em;margin-bottom:1em}@media(max-width: 767.98px){.layout-sidebar{margin-left:0;margin-right:0}}.panel-sidebar,.panel-sidebar .form-control,.panel-input,.panel-input .form-control,.selectize-dropdown{font-size:.9rem}.panel-sidebar .form-control,.panel-input .form-control{padding-top:.1rem}.tab-pane div.sourceCode{margin-top:0px}.tab-pane>p{padding-top:0}.tab-pane>p:nth-child(1){padding-top:0}.tab-pane>p:last-child{margin-bottom:0}.tab-pane>pre:last-child{margin-bottom:0}.tab-content>.tab-pane:not(.active){display:none !important}div.sourceCode{background-color:rgba(67,67,67,.65);border:1px solid rgba(67,67,67,.65);border-radius:.25rem}pre.sourceCode{background-color:rgba(0,0,0,0)}pre.sourceCode{border:none;font-size:.875em;overflow:visible !important;padding:.4em}.callout pre.sourceCode{padding-left:0}div.sourceCode{overflow-y:hidden}.callout div.sourceCode{margin-left:initial}.blockquote{font-size:inherit;padding-left:1rem;padding-right:1.5rem;color:#bfbfbf}.blockquote h1:first-child,.blockquote .h1:first-child,.blockquote h2:first-child,.blockquote .h2:first-child,.blockquote h3:first-child,.blockquote .h3:first-child,.blockquote h4:first-child,.blockquote .h4:first-child,.blockquote h5:first-child,.blockquote .h5:first-child{margin-top:0}pre{background-color:initial;padding:initial;border:initial}p pre code:not(.sourceCode),li pre code:not(.sourceCode),pre code:not(.sourceCode){background-color:initial}p code:not(.sourceCode),li code:not(.sourceCode),td code:not(.sourceCode){background-color:#f8f9fa;padding:.2em}nav p code:not(.sourceCode),nav li code:not(.sourceCode),nav td code:not(.sourceCode){background-color:rgba(0,0,0,0);padding:0}td code:not(.sourceCode){white-space:pre-wrap}#quarto-embedded-source-code-modal>.modal-dialog{max-width:1000px;padding-left:1.75rem;padding-right:1.75rem}#quarto-embedded-source-code-modal>.modal-dialog>.modal-content>.modal-body{padding:0}#quarto-embedded-source-code-modal>.modal-dialog>.modal-content>.modal-body div.sourceCode{margin:0;padding:.2rem .2rem;border-radius:0px;border:none}#quarto-embedded-source-code-modal>.modal-dialog>.modal-content>.modal-header{padding:.7rem}.code-tools-button{font-size:1rem;padding:.15rem .15rem;margin-left:5px;color:#6c757d;background-color:rgba(0,0,0,0);transition:initial;cursor:pointer}.code-tools-button>.bi::before{display:inline-block;height:1rem;width:1rem;content:"";vertical-align:-0.125em;background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(108, 117, 125)" viewBox="0 0 16 16"><path d="M10.478 1.647a.5.5 0 1 0-.956-.294l-4 13a.5.5 0 0 0 .956.294l4-13zM4.854 4.146a.5.5 0 0 1 0 .708L1.707 8l3.147 3.146a.5.5 0 0 1-.708.708l-3.5-3.5a.5.5 0 0 1 0-.708l3.5-3.5a.5.5 0 0 1 .708 0zm6.292 0a.5.5 0 0 0 0 .708L14.293 8l-3.147 3.146a.5.5 0 0 0 .708.708l3.5-3.5a.5.5 0 0 0 0-.708l-3.5-3.5a.5.5 0 0 0-.708 0z"/></svg>');background-repeat:no-repeat;background-size:1rem 1rem}.code-tools-button:hover>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(255, 255, 255)" viewBox="0 0 16 16"><path d="M10.478 1.647a.5.5 0 1 0-.956-.294l-4 13a.5.5 0 0 0 .956.294l4-13zM4.854 4.146a.5.5 0 0 1 0 .708L1.707 8l3.147 3.146a.5.5 0 0 1-.708.708l-3.5-3.5a.5.5 0 0 1 0-.708l3.5-3.5a.5.5 0 0 1 .708 0zm6.292 0a.5.5 0 0 0 0 .708L14.293 8l-3.147 3.146a.5.5 0 0 0 .708.708l3.5-3.5a.5.5 0 0 0 0-.708l-3.5-3.5a.5.5 0 0 0-.708 0z"/></svg>')}#quarto-embedded-source-code-modal .code-copy-button>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(108, 117, 125)" viewBox="0 0 16 16"><path d="M4 1.5H3a2 2 0 0 0-2 2V14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V3.5a2 2 0 0 0-2-2h-1v1h1a1 1 0 0 1 1 1V14a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V3.5a1 1 0 0 1 1-1h1v-1z"/><path d="M9.5 1a.5.5 0 0 1 .5.5v1a.5.5 0 0 1-.5.5h-3a.5.5 0 0 1-.5-.5v-1a.5.5 0 0 1 .5-.5h3zm-3-1A1.5 1.5 0 0 0 5 1.5v1A1.5 1.5 0 0 0 6.5 4h3A1.5 1.5 0 0 0 11 2.5v-1A1.5 1.5 0 0 0 9.5 0h-3z"/></svg>')}#quarto-embedded-source-code-modal .code-copy-button-checked>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(108, 117, 125)" viewBox="0 0 16 16"><path d="M13.854 3.646a.5.5 0 0 1 0 .708l-7 7a.5.5 0 0 1-.708 0l-3.5-3.5a.5.5 0 1 1 .708-.708L6.5 10.293l6.646-6.647a.5.5 0 0 1 .708 0z"/></svg>')}.sidebar{will-change:top;transition:top 200ms linear;position:sticky;overflow-y:auto;padding-top:1.2em;max-height:100vh}.sidebar.toc-left,.sidebar.margin-sidebar{top:0px;padding-top:1em}.sidebar.quarto-banner-title-block-sidebar>*{padding-top:1.65em}figure .quarto-notebook-link{margin-top:.5em}.quarto-notebook-link{font-size:.75em;color:#6c757d;margin-bottom:1em;text-decoration:none;display:block}.quarto-notebook-link:hover{text-decoration:underline;color:#00bc8c}.quarto-notebook-link::before{display:inline-block;height:.75rem;width:.75rem;margin-bottom:0em;margin-right:.25em;content:"";vertical-align:-0.125em;background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(108, 117, 125)" class="bi bi-journal-code" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8.646 5.646a.5.5 0 0 1 .708 0l2 2a.5.5 0 0 1 0 .708l-2 2a.5.5 0 0 1-.708-.708L10.293 8 8.646 6.354a.5.5 0 0 1 0-.708zm-1.292 0a.5.5 0 0 0-.708 0l-2 2a.5.5 0 0 0 0 .708l2 2a.5.5 0 0 0 .708-.708L5.707 8l1.647-1.646a.5.5 0 0 0 0-.708z"/><path d="M3 0h10a2 2 0 0 1 2 2v12a2 2 0 0 1-2 2H3a2 2 0 0 1-2-2v-1h1v1a1 1 0 0 0 1 1h10a1 1 0 0 0 1-1V2a1 1 0 0 0-1-1H3a1 1 0 0 0-1 1v1H1V2a2 2 0 0 1 2-2z"/><path d="M1 5v-.5a.5.5 0 0 1 1 0V5h.5a.5.5 0 0 1 0 1h-2a.5.5 0 0 1 0-1H1zm0 3v-.5a.5.5 0 0 1 1 0V8h.5a.5.5 0 0 1 0 1h-2a.5.5 0 0 1 0-1H1zm0 3v-.5a.5.5 0 0 1 1 0v.5h.5a.5.5 0 0 1 0 1h-2a.5.5 0 0 1 0-1H1z"/></svg>');background-repeat:no-repeat;background-size:.75rem .75rem}.toc-actions i.bi,.quarto-code-links i.bi,.quarto-other-links i.bi,.quarto-alternate-notebooks i.bi,.quarto-alternate-formats i.bi{margin-right:.4em;font-size:.8rem}.quarto-other-links-text-target .quarto-code-links i.bi,.quarto-other-links-text-target .quarto-other-links i.bi{margin-right:.2em}.quarto-other-formats-text-target .quarto-alternate-formats i.bi{margin-right:.1em}.toc-actions i.bi.empty,.quarto-code-links i.bi.empty,.quarto-other-links i.bi.empty,.quarto-alternate-notebooks i.bi.empty,.quarto-alternate-formats i.bi.empty{padding-left:1em}.quarto-notebook h2,.quarto-notebook .h2{border-bottom:none}.quarto-notebook .cell-container{display:flex}.quarto-notebook .cell-container .cell{flex-grow:4}.quarto-notebook .cell-container .cell-decorator{padding-top:1.5em;padding-right:1em;text-align:right}.quarto-notebook .cell-container.code-fold .cell-decorator{padding-top:3em}.quarto-notebook .cell-code code{white-space:pre-wrap}.quarto-notebook .cell .cell-output-stderr pre code,.quarto-notebook .cell .cell-output-stdout pre code{white-space:pre-wrap;overflow-wrap:anywhere}.toc-actions,.quarto-alternate-formats,.quarto-other-links,.quarto-code-links,.quarto-alternate-notebooks{padding-left:0em}.sidebar .toc-actions a,.sidebar .quarto-alternate-formats a,.sidebar .quarto-other-links a,.sidebar .quarto-code-links a,.sidebar .quarto-alternate-notebooks a,.sidebar nav[role=doc-toc] a{text-decoration:none}.sidebar .toc-actions a:hover,.sidebar .quarto-other-links a:hover,.sidebar .quarto-code-links a:hover,.sidebar .quarto-alternate-formats a:hover,.sidebar .quarto-alternate-notebooks a:hover{color:#00bc8c}.sidebar .toc-actions h2,.sidebar .toc-actions .h2,.sidebar .quarto-code-links h2,.sidebar .quarto-code-links .h2,.sidebar .quarto-other-links h2,.sidebar .quarto-other-links .h2,.sidebar .quarto-alternate-notebooks h2,.sidebar .quarto-alternate-notebooks .h2,.sidebar .quarto-alternate-formats h2,.sidebar .quarto-alternate-formats .h2,.sidebar nav[role=doc-toc]>h2,.sidebar nav[role=doc-toc]>.h2{font-weight:500;margin-bottom:.2rem;margin-top:.3rem;font-family:inherit;border-bottom:0;padding-bottom:0;padding-top:0px}.sidebar .toc-actions>h2,.sidebar .toc-actions>.h2,.sidebar .quarto-code-links>h2,.sidebar .quarto-code-links>.h2,.sidebar .quarto-other-links>h2,.sidebar .quarto-other-links>.h2,.sidebar .quarto-alternate-notebooks>h2,.sidebar .quarto-alternate-notebooks>.h2,.sidebar .quarto-alternate-formats>h2,.sidebar .quarto-alternate-formats>.h2{font-size:.8rem}.sidebar nav[role=doc-toc]>h2,.sidebar nav[role=doc-toc]>.h2{font-size:.875rem}.sidebar nav[role=doc-toc]>ul a{border-left:1px solid #ebebeb;padding-left:.6rem}.sidebar .toc-actions h2>ul a,.sidebar .toc-actions .h2>ul a,.sidebar .quarto-code-links h2>ul a,.sidebar .quarto-code-links .h2>ul a,.sidebar .quarto-other-links h2>ul a,.sidebar .quarto-other-links .h2>ul a,.sidebar .quarto-alternate-notebooks h2>ul a,.sidebar .quarto-alternate-notebooks .h2>ul a,.sidebar .quarto-alternate-formats h2>ul a,.sidebar .quarto-alternate-formats .h2>ul a{border-left:none;padding-left:.6rem}.sidebar .toc-actions ul a:empty,.sidebar .quarto-code-links ul a:empty,.sidebar .quarto-other-links ul a:empty,.sidebar .quarto-alternate-notebooks ul a:empty,.sidebar .quarto-alternate-formats ul a:empty,.sidebar nav[role=doc-toc]>ul a:empty{display:none}.sidebar .toc-actions ul,.sidebar .quarto-code-links ul,.sidebar .quarto-other-links ul,.sidebar .quarto-alternate-notebooks ul,.sidebar .quarto-alternate-formats ul{padding-left:0;list-style:none}.sidebar nav[role=doc-toc] ul{list-style:none;padding-left:0;list-style:none}.sidebar nav[role=doc-toc]>ul{margin-left:.45em}.quarto-margin-sidebar nav[role=doc-toc]{padding-left:.5em}.sidebar .toc-actions>ul,.sidebar .quarto-code-links>ul,.sidebar .quarto-other-links>ul,.sidebar .quarto-alternate-notebooks>ul,.sidebar .quarto-alternate-formats>ul{font-size:.8rem}.sidebar nav[role=doc-toc]>ul{font-size:.875rem}.sidebar .toc-actions ul li a,.sidebar .quarto-code-links ul li a,.sidebar .quarto-other-links ul li a,.sidebar .quarto-alternate-notebooks ul li a,.sidebar .quarto-alternate-formats ul li a,.sidebar nav[role=doc-toc]>ul li a{line-height:1.1rem;padding-bottom:.2rem;padding-top:.2rem;color:inherit}.sidebar nav[role=doc-toc] ul>li>ul>li>a{padding-left:1.2em}.sidebar nav[role=doc-toc] ul>li>ul>li>ul>li>a{padding-left:2.4em}.sidebar nav[role=doc-toc] ul>li>ul>li>ul>li>ul>li>a{padding-left:3.6em}.sidebar nav[role=doc-toc] ul>li>ul>li>ul>li>ul>li>ul>li>a{padding-left:4.8em}.sidebar nav[role=doc-toc] ul>li>ul>li>ul>li>ul>li>ul>li>ul>li>a{padding-left:6em}.sidebar nav[role=doc-toc] ul>li>a.active,.sidebar nav[role=doc-toc] ul>li>ul>li>a.active{border-left:1px solid #00bc8c;color:#00bc8c !important}.sidebar nav[role=doc-toc] ul>li>a:hover,.sidebar nav[role=doc-toc] ul>li>ul>li>a:hover{color:#00bc8c !important}kbd,.kbd{color:#fff;background-color:#f8f9fa;border:1px solid;border-radius:5px;border-color:#434343}.quarto-appendix-contents div.hanging-indent{margin-left:0em}.quarto-appendix-contents div.hanging-indent div.csl-entry{margin-left:1em;text-indent:-1em}.citation a,.footnote-ref{text-decoration:none}.footnotes ol{padding-left:1em}.tippy-content>*{margin-bottom:.7em}.tippy-content>*:last-child{margin-bottom:0}.callout{margin-top:1.25rem;margin-bottom:1.25rem;border-radius:.25rem;overflow-wrap:break-word}.callout .callout-title-container{overflow-wrap:anywhere}.callout.callout-style-simple{padding:.4em .7em;border-left:5px solid;border-right:1px solid #434343;border-top:1px solid #434343;border-bottom:1px solid #434343}.callout.callout-style-default{border-left:5px solid;border-right:1px solid #434343;border-top:1px solid #434343;border-bottom:1px solid #434343}.callout .callout-body-container{flex-grow:1}.callout.callout-style-simple .callout-body{font-size:.9rem;font-weight:400}.callout.callout-style-default .callout-body{font-size:.9rem;font-weight:400}.callout:not(.no-icon).callout-titled.callout-style-simple .callout-body{padding-left:1.6em}.callout.callout-titled>.callout-header{padding-top:.2em;margin-bottom:-0.2em}.callout.callout-style-simple>div.callout-header{border-bottom:none;font-size:.9rem;font-weight:600;opacity:75%}.callout.callout-style-default>div.callout-header{border-bottom:none;font-weight:600;opacity:85%;font-size:.9rem;padding-left:.5em;padding-right:.5em}.callout.callout-style-default .callout-body{padding-left:.5em;padding-right:.5em}.callout.callout-style-default .callout-body>:first-child{padding-top:.5rem;margin-top:0}.callout>div.callout-header[data-bs-toggle=collapse]{cursor:pointer}.callout.callout-style-default .callout-header[aria-expanded=false],.callout.callout-style-default .callout-header[aria-expanded=true]{padding-top:0px;margin-bottom:0px;align-items:center}.callout.callout-titled .callout-body>:last-child:not(.sourceCode),.callout.callout-titled .callout-body>div>:last-child:not(.sourceCode){padding-bottom:.5rem;margin-bottom:0}.callout:not(.callout-titled) .callout-body>:first-child,.callout:not(.callout-titled) .callout-body>div>:first-child{margin-top:.25rem}.callout:not(.callout-titled) .callout-body>:last-child,.callout:not(.callout-titled) .callout-body>div>:last-child{margin-bottom:.2rem}.callout.callout-style-simple .callout-icon::before,.callout.callout-style-simple .callout-toggle::before{height:1rem;width:1rem;display:inline-block;content:"";background-repeat:no-repeat;background-size:1rem 1rem}.callout.callout-style-default .callout-icon::before,.callout.callout-style-default .callout-toggle::before{height:.9rem;width:.9rem;display:inline-block;content:"";background-repeat:no-repeat;background-size:.9rem .9rem}.callout.callout-style-default .callout-toggle::before{margin-top:5px}.callout .callout-btn-toggle .callout-toggle::before{transition:transform .2s linear}.callout .callout-header[aria-expanded=false] .callout-toggle::before{transform:rotate(-90deg)}.callout .callout-header[aria-expanded=true] .callout-toggle::before{transform:none}.callout.callout-style-simple:not(.no-icon) div.callout-icon-container{padding-top:.2em;padding-right:.55em}.callout.callout-style-default:not(.no-icon) div.callout-icon-container{padding-top:.1em;padding-right:.35em}.callout.callout-style-default:not(.no-icon) div.callout-title-container{margin-top:-1px}.callout.callout-style-default.callout-caution:not(.no-icon) div.callout-icon-container{padding-top:.3em;padding-right:.35em}.callout>.callout-body>.callout-icon-container>.no-icon,.callout>.callout-header>.callout-icon-container>.no-icon{display:none}div.callout.callout{border-left-color:#6c757d}div.callout.callout-style-default>.callout-header{background-color:#6c757d}div.callout-note.callout{border-left-color:#375a7f}div.callout-note.callout-style-default>.callout-header{background-color:#111b26}div.callout-note:not(.callout-titled) .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %23325172" class="bi bi-info-circle" viewBox="0 0 16 16"><path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z"/><path d="m8.93 6.588-2.29.287-.082.38.45.083c.294.07.352.176.288.469l-.738 3.468c-.194.897.105 1.319.808 1.319.545 0 1.178-.252 1.465-.598l.088-.416c-.2.176-.492.246-.686.246-.275 0-.375-.193-.304-.533L8.93 6.588zM9 4.5a1 1 0 1 1-2 0 1 1 0 0 1 2 0z"/></svg>');}div.callout-note.callout-titled .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %23325172" class="bi bi-info-circle" viewBox="0 0 16 16"><path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z"/><path d="m8.93 6.588-2.29.287-.082.38.45.083c.294.07.352.176.288.469l-.738 3.468c-.194.897.105 1.319.808 1.319.545 0 1.178-.252 1.465-.598l.088-.416c-.2.176-.492.246-.686.246-.275 0-.375-.193-.304-.533L8.93 6.588zM9 4.5a1 1 0 1 1-2 0 1 1 0 0 1 2 0z"/></svg>');}div.callout-note .callout-toggle::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(255, 255, 255)" class="bi bi-chevron-down" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z"/></svg>')}div.callout-tip.callout{border-left-color:#00bc8c}div.callout-tip.callout-style-default>.callout-header{background-color:#00382a}div.callout-tip:not(.callout-titled) .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %2300a97e" class="bi bi-lightbulb" viewBox="0 0 16 16"><path d="M2 6a6 6 0 1 1 10.174 4.31c-.203.196-.359.4-.453.619l-.762 1.769A.5.5 0 0 1 10.5 13a.5.5 0 0 1 0 1 .5.5 0 0 1 0 1l-.224.447a1 1 0 0 1-.894.553H6.618a1 1 0 0 1-.894-.553L5.5 15a.5.5 0 0 1 0-1 .5.5 0 0 1 0-1 .5.5 0 0 1-.46-.302l-.761-1.77a1.964 1.964 0 0 0-.453-.618A5.984 5.984 0 0 1 2 6zm6-5a5 5 0 0 0-3.479 8.592c.263.254.514.564.676.941L5.83 12h4.342l.632-1.467c.162-.377.413-.687.676-.941A5 5 0 0 0 8 1z"/></svg>');}div.callout-tip.callout-titled .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %2300a97e" class="bi bi-lightbulb" viewBox="0 0 16 16"><path d="M2 6a6 6 0 1 1 10.174 4.31c-.203.196-.359.4-.453.619l-.762 1.769A.5.5 0 0 1 10.5 13a.5.5 0 0 1 0 1 .5.5 0 0 1 0 1l-.224.447a1 1 0 0 1-.894.553H6.618a1 1 0 0 1-.894-.553L5.5 15a.5.5 0 0 1 0-1 .5.5 0 0 1 0-1 .5.5 0 0 1-.46-.302l-.761-1.77a1.964 1.964 0 0 0-.453-.618A5.984 5.984 0 0 1 2 6zm6-5a5 5 0 0 0-3.479 8.592c.263.254.514.564.676.941L5.83 12h4.342l.632-1.467c.162-.377.413-.687.676-.941A5 5 0 0 0 8 1z"/></svg>');}div.callout-tip .callout-toggle::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(255, 255, 255)" class="bi bi-chevron-down" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z"/></svg>')}div.callout-warning.callout{border-left-color:#f39c12}div.callout-warning.callout-style-default>.callout-header{background-color:#492f05}div.callout-warning:not(.callout-titled) .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %23db8c10" class="bi bi-exclamation-triangle" viewBox="0 0 16 16"><path d="M7.938 2.016A.13.13 0 0 1 8.002 2a.13.13 0 0 1 .063.016.146.146 0 0 1 .054.057l6.857 11.667c.036.06.035.124.002.183a.163.163 0 0 1-.054.06.116.116 0 0 1-.066.017H1.146a.115.115 0 0 1-.066-.017.163.163 0 0 1-.054-.06.176.176 0 0 1 .002-.183L7.884 2.073a.147.147 0 0 1 .054-.057zm1.044-.45a1.13 1.13 0 0 0-1.96 0L.165 13.233c-.457.778.091 1.767.98 1.767h13.713c.889 0 1.438-.99.98-1.767L8.982 1.566z"/><path d="M7.002 12a1 1 0 1 1 2 0 1 1 0 0 1-2 0zM7.1 5.995a.905.905 0 1 1 1.8 0l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 5.995z"/></svg>');}div.callout-warning.callout-titled .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %23db8c10" class="bi bi-exclamation-triangle" viewBox="0 0 16 16"><path d="M7.938 2.016A.13.13 0 0 1 8.002 2a.13.13 0 0 1 .063.016.146.146 0 0 1 .054.057l6.857 11.667c.036.06.035.124.002.183a.163.163 0 0 1-.054.06.116.116 0 0 1-.066.017H1.146a.115.115 0 0 1-.066-.017.163.163 0 0 1-.054-.06.176.176 0 0 1 .002-.183L7.884 2.073a.147.147 0 0 1 .054-.057zm1.044-.45a1.13 1.13 0 0 0-1.96 0L.165 13.233c-.457.778.091 1.767.98 1.767h13.713c.889 0 1.438-.99.98-1.767L8.982 1.566z"/><path d="M7.002 12a1 1 0 1 1 2 0 1 1 0 0 1-2 0zM7.1 5.995a.905.905 0 1 1 1.8 0l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 5.995z"/></svg>');}div.callout-warning .callout-toggle::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(255, 255, 255)" class="bi bi-chevron-down" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z"/></svg>')}div.callout-caution.callout{border-left-color:#fd7e14}div.callout-caution.callout-style-default>.callout-header{background-color:#4c2606}div.callout-caution:not(.callout-titled) .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %23e47112" class="bi bi-cone-striped" viewBox="0 0 16 16"><path d="M9.97 4.88l.953 3.811C10.158 8.878 9.14 9 8 9c-1.14 0-2.159-.122-2.923-.309L6.03 4.88C6.635 4.957 7.3 5 8 5s1.365-.043 1.97-.12zm-.245-.978L8.97.88C8.718-.13 7.282-.13 7.03.88L6.274 3.9C6.8 3.965 7.382 4 8 4c.618 0 1.2-.036 1.725-.098zm4.396 8.613a.5.5 0 0 1 .037.96l-6 2a.5.5 0 0 1-.316 0l-6-2a.5.5 0 0 1 .037-.96l2.391-.598.565-2.257c.862.212 1.964.339 3.165.339s2.303-.127 3.165-.339l.565 2.257 2.391.598z"/></svg>');}div.callout-caution.callout-titled .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %23e47112" class="bi bi-cone-striped" viewBox="0 0 16 16"><path d="M9.97 4.88l.953 3.811C10.158 8.878 9.14 9 8 9c-1.14 0-2.159-.122-2.923-.309L6.03 4.88C6.635 4.957 7.3 5 8 5s1.365-.043 1.97-.12zm-.245-.978L8.97.88C8.718-.13 7.282-.13 7.03.88L6.274 3.9C6.8 3.965 7.382 4 8 4c.618 0 1.2-.036 1.725-.098zm4.396 8.613a.5.5 0 0 1 .037.96l-6 2a.5.5 0 0 1-.316 0l-6-2a.5.5 0 0 1 .037-.96l2.391-.598.565-2.257c.862.212 1.964.339 3.165.339s2.303-.127 3.165-.339l.565 2.257 2.391.598z"/></svg>');}div.callout-caution .callout-toggle::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(255, 255, 255)" class="bi bi-chevron-down" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z"/></svg>')}div.callout-important.callout{border-left-color:#e74c3c}div.callout-important.callout-style-default>.callout-header{background-color:#451712}div.callout-important:not(.callout-titled) .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %23d04436" class="bi bi-exclamation-circle" viewBox="0 0 16 16"><path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z"/><path d="M7.002 11a1 1 0 1 1 2 0 1 1 0 0 1-2 0zM7.1 4.995a.905.905 0 1 1 1.8 0l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 4.995z"/></svg>');}div.callout-important.callout-titled .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %23d04436" class="bi bi-exclamation-circle" viewBox="0 0 16 16"><path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z"/><path d="M7.002 11a1 1 0 1 1 2 0 1 1 0 0 1-2 0zM7.1 4.995a.905.905 0 1 1 1.8 0l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 4.995z"/></svg>');}div.callout-important .callout-toggle::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(255, 255, 255)" class="bi bi-chevron-down" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z"/></svg>')}.quarto-toggle-container{display:flex;align-items:center}.quarto-reader-toggle .bi::before,.quarto-color-scheme-toggle .bi::before{display:inline-block;height:1rem;width:1rem;content:"";background-repeat:no-repeat;background-size:1rem 1rem}.sidebar-navigation{padding-left:20px}.navbar{background-color:#375a7f;color:#dee2e6}.navbar .quarto-color-scheme-toggle:not(.alternate) .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(222, 226, 230, 1)" class="bi bi-toggle-off" viewBox="0 0 16 16"><path d="M11 4a4 4 0 0 1 0 8H8a4.992 4.992 0 0 0 2-4 4.992 4.992 0 0 0-2-4h3zm-6 8a4 4 0 1 1 0-8 4 4 0 0 1 0 8zM0 8a5 5 0 0 0 5 5h6a5 5 0 0 0 0-10H5a5 5 0 0 0-5 5z"/></svg>')}.navbar .quarto-color-scheme-toggle.alternate .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(222, 226, 230, 1)" class="bi bi-toggle-on" viewBox="0 0 16 16"><path d="M5 3a5 5 0 0 0 0 10h6a5 5 0 0 0 0-10H5zm6 9a4 4 0 1 1 0-8 4 4 0 0 1 0 8z"/></svg>')}.sidebar-navigation .quarto-color-scheme-toggle:not(.alternate) .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(230, 230, 230, 1)" class="bi bi-toggle-off" viewBox="0 0 16 16"><path d="M11 4a4 4 0 0 1 0 8H8a4.992 4.992 0 0 0 2-4 4.992 4.992 0 0 0-2-4h3zm-6 8a4 4 0 1 1 0-8 4 4 0 0 1 0 8zM0 8a5 5 0 0 0 5 5h6a5 5 0 0 0 0-10H5a5 5 0 0 0-5 5z"/></svg>')}.sidebar-navigation .quarto-color-scheme-toggle.alternate .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(230, 230, 230, 1)" class="bi bi-toggle-on" viewBox="0 0 16 16"><path d="M5 3a5 5 0 0 0 0 10h6a5 5 0 0 0 0-10H5zm6 9a4 4 0 1 1 0-8 4 4 0 0 1 0 8z"/></svg>')}.quarto-sidebar-toggle{border-color:#dee2e6;border-bottom-left-radius:.25rem;border-bottom-right-radius:.25rem;border-style:solid;border-width:1px;overflow:hidden;border-top-width:0px;padding-top:0px !important}.quarto-sidebar-toggle-title{cursor:pointer;padding-bottom:2px;margin-left:.25em;text-align:center;font-weight:400;font-size:.775em}#quarto-content .quarto-sidebar-toggle{background:#272727}#quarto-content .quarto-sidebar-toggle-title{color:#fff}.quarto-sidebar-toggle-icon{color:#dee2e6;margin-right:.5em;float:right;transition:transform .2s ease}.quarto-sidebar-toggle-icon::before{padding-top:5px}.quarto-sidebar-toggle.expanded .quarto-sidebar-toggle-icon{transform:rotate(-180deg)}.quarto-sidebar-toggle.expanded .quarto-sidebar-toggle-title{border-bottom:solid #dee2e6 1px}.quarto-sidebar-toggle-contents{background-color:#222;padding-right:10px;padding-left:10px;margin-top:0px !important;transition:max-height .5s ease}.quarto-sidebar-toggle.expanded .quarto-sidebar-toggle-contents{padding-top:1em;padding-bottom:10px}@media(max-width: 767.98px){.sidebar-menu-container{padding-bottom:5em}}.quarto-sidebar-toggle:not(.expanded) .quarto-sidebar-toggle-contents{padding-top:0px !important;padding-bottom:0px}nav[role=doc-toc]{z-index:1020}#quarto-sidebar>*,nav[role=doc-toc]>*{transition:opacity .1s ease,border .1s ease}#quarto-sidebar.slow>*,nav[role=doc-toc].slow>*{transition:opacity .4s ease,border .4s ease}.quarto-color-scheme-toggle:not(.alternate).top-right .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(166, 166, 166, 1)" class="bi bi-toggle-off" viewBox="0 0 16 16"><path d="M11 4a4 4 0 0 1 0 8H8a4.992 4.992 0 0 0 2-4 4.992 4.992 0 0 0-2-4h3zm-6 8a4 4 0 1 1 0-8 4 4 0 0 1 0 8zM0 8a5 5 0 0 0 5 5h6a5 5 0 0 0 0-10H5a5 5 0 0 0-5 5z"/></svg>')}.quarto-color-scheme-toggle.alternate.top-right .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(204, 204, 204, 1)" class="bi bi-toggle-on" viewBox="0 0 16 16"><path d="M5 3a5 5 0 0 0 0 10h6a5 5 0 0 0 0-10H5zm6 9a4 4 0 1 1 0-8 4 4 0 0 1 0 8z"/></svg>')}#quarto-appendix.default{border-top:1px solid #dee2e6}#quarto-appendix.default{background-color:#222;padding-top:1.5em;margin-top:2em;z-index:998}#quarto-appendix.default .quarto-appendix-heading{margin-top:0;line-height:1.4em;font-weight:600;opacity:.9;border-bottom:none;margin-bottom:0}#quarto-appendix.default .footnotes ol,#quarto-appendix.default .footnotes ol li>p:last-of-type,#quarto-appendix.default .quarto-appendix-contents>p:last-of-type{margin-bottom:0}#quarto-appendix.default .footnotes ol{margin-left:.5em}#quarto-appendix.default .quarto-appendix-secondary-label{margin-bottom:.4em}#quarto-appendix.default .quarto-appendix-bibtex{font-size:.7em;padding:1em;border:solid 1px #dee2e6;margin-bottom:1em}#quarto-appendix.default .quarto-appendix-bibtex code.sourceCode{white-space:pre-wrap}#quarto-appendix.default .quarto-appendix-citeas{font-size:.9em;padding:1em;border:solid 1px #dee2e6;margin-bottom:1em}#quarto-appendix.default .quarto-appendix-heading{font-size:1em !important}#quarto-appendix.default *[role=doc-endnotes]>ol,#quarto-appendix.default .quarto-appendix-contents>*:not(h2):not(.h2){font-size:.9em}#quarto-appendix.default section{padding-bottom:1.5em}#quarto-appendix.default section *[role=doc-endnotes],#quarto-appendix.default section>*:not(a){opacity:.9;word-wrap:break-word}.btn.btn-quarto,div.cell-output-display .btn-quarto{--bs-btn-color: #d9d9d9;--bs-btn-bg: #434343;--bs-btn-border-color: #434343;--bs-btn-hover-color: #d9d9d9;--bs-btn-hover-bg: #5f5f5f;--bs-btn-hover-border-color: #565656;--bs-btn-focus-shadow-rgb: 90, 90, 90;--bs-btn-active-color: #fff;--bs-btn-active-bg: dimgray;--bs-btn-active-border-color: #565656;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #434343;--bs-btn-disabled-border-color: #434343}nav.quarto-secondary-nav.color-navbar{background-color:#375a7f;color:#dee2e6}nav.quarto-secondary-nav.color-navbar h1,nav.quarto-secondary-nav.color-navbar .h1,nav.quarto-secondary-nav.color-navbar .quarto-btn-toggle{color:#dee2e6}@media(max-width: 991.98px){body.nav-sidebar .quarto-title-banner{margin-bottom:0;padding-bottom:1em}body.nav-sidebar #title-block-header{margin-block-end:0}}p.subtitle{margin-top:.25em;margin-bottom:.5em}code a:any-link{color:inherit;text-decoration-color:#6c757d}/*! dark */div.observablehq table thead tr th{background-color:var(--bs-body-bg)}input,button,select,optgroup,textarea{background-color:var(--bs-body-bg)}.code-annotated .code-copy-button{margin-right:1.25em;margin-top:0;padding-bottom:0;padding-top:3px}.code-annotation-gutter-bg{background-color:#222}.code-annotation-gutter{background-color:rgba(67,67,67,.65)}.code-annotation-gutter,.code-annotation-gutter-bg{height:100%;width:calc(20px + .5em);position:absolute;top:0;right:0}dl.code-annotation-container-grid dt{margin-right:1em;margin-top:.25rem}dl.code-annotation-container-grid dt{font-family:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace;color:#e6e6e6;border:solid #e6e6e6 1px;border-radius:50%;height:22px;width:22px;line-height:22px;font-size:11px;text-align:center;vertical-align:middle;text-decoration:none}dl.code-annotation-container-grid dt[data-target-cell]{cursor:pointer}dl.code-annotation-container-grid dt[data-target-cell].code-annotation-active{color:#222;border:solid #aaa 1px;background-color:#aaa}pre.code-annotation-code{padding-top:0;padding-bottom:0}pre.code-annotation-code code{z-index:3}#code-annotation-line-highlight-gutter{width:100%;border-top:solid rgba(170,170,170,.2666666667) 1px;border-bottom:solid rgba(170,170,170,.2666666667) 1px;z-index:2;background-color:rgba(170,170,170,.1333333333)}#code-annotation-line-highlight{margin-left:-4em;width:calc(100% + 4em);border-top:solid rgba(170,170,170,.2666666667) 1px;border-bottom:solid rgba(170,170,170,.2666666667) 1px;z-index:2;background-color:rgba(170,170,170,.1333333333)}code.sourceCode .code-annotation-anchor.code-annotation-active{background-color:var(--quarto-hl-normal-color, #aaaaaa);border:solid var(--quarto-hl-normal-color, #aaaaaa) 1px;color:#434343;font-weight:bolder}code.sourceCode .code-annotation-anchor{font-family:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace;color:var(--quarto-hl-co-color);border:solid var(--quarto-hl-co-color) 1px;border-radius:50%;height:18px;width:18px;font-size:9px;margin-top:2px}code.sourceCode button.code-annotation-anchor{padding:2px;user-select:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;-o-user-select:none}code.sourceCode a.code-annotation-anchor{line-height:18px;text-align:center;vertical-align:middle;cursor:default;text-decoration:none}@media print{.page-columns .column-screen-inset{grid-column:page-start-inset/page-end-inset;z-index:998;opacity:.999}.page-columns .column-screen-inset table{background:#222}.page-columns .column-screen-inset-left{grid-column:page-start-inset/body-content-end;z-index:998;opacity:.999}.page-columns .column-screen-inset-left table{background:#222}.page-columns .column-screen-inset-right{grid-column:body-content-start/page-end-inset;z-index:998;opacity:.999}.page-columns .column-screen-inset-right table{background:#222}.page-columns .column-screen{grid-column:page-start/page-end;z-index:998;opacity:.999}.page-columns .column-screen table{background:#222}.page-columns .column-screen-left{grid-column:page-start/body-content-end;z-index:998;opacity:.999}.page-columns .column-screen-left table{background:#222}.page-columns .column-screen-right{grid-column:body-content-start/page-end;z-index:998;opacity:.999}.page-columns .column-screen-right table{background:#222}.page-columns .column-screen-inset-shaded{grid-column:page-start-inset/page-end-inset;padding:1em;background:#6f6f6f;z-index:998;opacity:.999;margin-bottom:1em}}.quarto-video{margin-bottom:1em}.table{border-top:1px solid #fff;border-bottom:1px solid #fff}.table>thead{border-top-width:0;border-bottom:1px solid #fff}.table a{word-break:break-word}.table>:not(caption)>*>*{background-color:unset;color:unset}#quarto-document-content .crosstalk-input .checkbox input[type=checkbox],#quarto-document-content .crosstalk-input .checkbox-inline input[type=checkbox]{position:unset;margin-top:unset;margin-left:unset}#quarto-document-content .row{margin-left:unset;margin-right:unset}.quarto-xref{white-space:nowrap}a.external:after{content:"";background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(0, 188, 140)" class="bi bi-box-arrow-up-right" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8.636 3.5a.5.5 0 0 0-.5-.5H1.5A1.5 1.5 0 0 0 0 4.5v10A1.5 1.5 0 0 0 1.5 16h10a1.5 1.5 0 0 0 1.5-1.5V7.864a.5.5 0 0 0-1 0V14.5a.5.5 0 0 1-.5.5h-10a.5.5 0 0 1-.5-.5v-10a.5.5 0 0 1 .5-.5h6.636a.5.5 0 0 0 .5-.5z"/><path fill-rule="evenodd" d="M16 .5a.5.5 0 0 0-.5-.5h-5a.5.5 0 0 0 0 1h3.793L6.146 9.146a.5.5 0 1 0 .708.708L15 1.707V5.5a.5.5 0 0 0 1 0v-5z"/></svg>');background-size:contain;background-repeat:no-repeat;background-position:center center;margin-left:.2em;padding-right:.75em}div.sourceCode code a.external:after{content:none}a.external:after:hover{cursor:pointer}.quarto-ext-icon{display:inline-block;font-size:.75em;padding-left:.3em}.code-with-filename .code-with-filename-file{margin-bottom:0;padding-bottom:2px;padding-top:2px;padding-left:.7em;border:var(--quarto-border-width) solid var(--quarto-border-color);border-radius:var(--quarto-border-radius);border-bottom:0;border-bottom-left-radius:0%;border-bottom-right-radius:0%}.code-with-filename div.sourceCode,.reveal .code-with-filename div.sourceCode{margin-top:0;border-top-left-radius:0%;border-top-right-radius:0%}.code-with-filename .code-with-filename-file pre{margin-bottom:0}.code-with-filename .code-with-filename-file{background-color:rgba(219,219,219,.8)}.quarto-dark .code-with-filename .code-with-filename-file{background-color:#555}.code-with-filename .code-with-filename-file strong{font-weight:400}.blockquote-footer{color:#595959}.form-floating>label,.form-floating>.form-control:focus~label,.form-floating>.form-control:not(:placeholder-shown)~label{color:#595959}.nav-tabs .nav-link,.nav-tabs .nav-link.active,.nav-tabs .nav-link.active:focus,.nav-tabs .nav-link.active:hover,.nav-tabs .nav-item.open .nav-link,.nav-tabs .nav-item.open .nav-link:focus,.nav-tabs .nav-item.open .nav-link:hover,.nav-pills .nav-link,.nav-pills .nav-link.active,.nav-pills .nav-link.active:focus,.nav-pills .nav-link.active:hover,.nav-pills .nav-item.open .nav-link,.nav-pills .nav-item.open .nav-link:focus,.nav-pills .nav-item.open .nav-link:hover{color:#fff}.breadcrumb a{color:#fff}.pagination a:hover{text-decoration:none}.alert{color:#fff;border:none}.alert a,.alert .alert-link{color:#fff;text-decoration:underline}.alert-default{background-color:#434343}.alert-primary{background-color:#375a7f}.alert-secondary{background-color:#434343}.alert-success{background-color:#00bc8c}.alert-info{background-color:#3498db}.alert-warning{background-color:#f39c12}.alert-danger{background-color:#e74c3c}.alert-light{background-color:#6f6f6f}.alert-dark{background-color:#2d2d2d}.tooltip{--bs-tooltip-bg: var(--bs-tertiary-bg);--bs-tooltip-color: var(--bs-emphasis-color)}.quarto-title-banner{margin-bottom:1em;color:#dee2e6;background:#375a7f}.quarto-title-banner a{color:#dee2e6}.quarto-title-banner h1,.quarto-title-banner .h1,.quarto-title-banner h2,.quarto-title-banner .h2{color:#dee2e6}.quarto-title-banner .code-tools-button{color:#a4afba}.quarto-title-banner .code-tools-button:hover{color:#dee2e6}.quarto-title-banner .code-tools-button>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(164, 175, 186)" viewBox="0 0 16 16"><path d="M10.478 1.647a.5.5 0 1 0-.956-.294l-4 13a.5.5 0 0 0 .956.294l4-13zM4.854 4.146a.5.5 0 0 1 0 .708L1.707 8l3.147 3.146a.5.5 0 0 1-.708.708l-3.5-3.5a.5.5 0 0 1 0-.708l3.5-3.5a.5.5 0 0 1 .708 0zm6.292 0a.5.5 0 0 0 0 .708L14.293 8l-3.147 3.146a.5.5 0 0 0 .708.708l3.5-3.5a.5.5 0 0 0 0-.708l-3.5-3.5a.5.5 0 0 0-.708 0z"/></svg>')}.quarto-title-banner .code-tools-button:hover>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(222, 226, 230)" viewBox="0 0 16 16"><path d="M10.478 1.647a.5.5 0 1 0-.956-.294l-4 13a.5.5 0 0 0 .956.294l4-13zM4.854 4.146a.5.5 0 0 1 0 .708L1.707 8l3.147 3.146a.5.5 0 0 1-.708.708l-3.5-3.5a.5.5 0 0 1 0-.708l3.5-3.5a.5.5 0 0 1 .708 0zm6.292 0a.5.5 0 0 0 0 .708L14.293 8l-3.147 3.146a.5.5 0 0 0 .708.708l3.5-3.5a.5.5 0 0 0 0-.708l-3.5-3.5a.5.5 0 0 0-.708 0z"/></svg>')}.quarto-title-banner .quarto-title .title{font-weight:600}.quarto-title-banner .quarto-categories{margin-top:.75em}@media(min-width: 992px){.quarto-title-banner{padding-top:2.5em;padding-bottom:2.5em}}@media(max-width: 991.98px){.quarto-title-banner{padding-top:1em;padding-bottom:1em}}@media(max-width: 767.98px){body.hypothesis-enabled #title-block-header>*{padding-right:20px}}main.quarto-banner-title-block>section:first-child>h2,main.quarto-banner-title-block>section:first-child>.h2,main.quarto-banner-title-block>section:first-child>h3,main.quarto-banner-title-block>section:first-child>.h3,main.quarto-banner-title-block>section:first-child>h4,main.quarto-banner-title-block>section:first-child>.h4{margin-top:0}.quarto-title .quarto-categories{display:flex;flex-wrap:wrap;row-gap:.5em;column-gap:.4em;padding-bottom:.5em;margin-top:.75em}.quarto-title .quarto-categories .quarto-category{padding:.25em .75em;font-size:.65em;text-transform:uppercase;border:solid 1px;border-radius:.25rem;opacity:.6}.quarto-title .quarto-categories .quarto-category a{color:inherit}.quarto-title-meta-container{display:grid;grid-template-columns:1fr auto}.quarto-title-meta-column-end{display:flex;flex-direction:column;padding-left:1em}.quarto-title-meta-column-end a .bi{margin-right:.3em}#title-block-header.quarto-title-block.default .quarto-title-meta{display:grid;grid-template-columns:minmax(max-content, 1fr) 1fr;grid-column-gap:1em}#title-block-header.quarto-title-block.default .quarto-title .title{margin-bottom:0}#title-block-header.quarto-title-block.default .quarto-title-author-orcid img{margin-top:-0.2em;height:.8em;width:.8em}#title-block-header.quarto-title-block.default .quarto-title-author-email{opacity:.7}#title-block-header.quarto-title-block.default .quarto-description p:last-of-type{margin-bottom:0}#title-block-header.quarto-title-block.default .quarto-title-meta-contents p,#title-block-header.quarto-title-block.default .quarto-title-authors p,#title-block-header.quarto-title-block.default .quarto-title-affiliations p{margin-bottom:.1em}#title-block-header.quarto-title-block.default .quarto-title-meta-heading{text-transform:uppercase;margin-top:1em;font-size:.8em;opacity:.8;font-weight:400}#title-block-header.quarto-title-block.default .quarto-title-meta-contents{font-size:.9em}#title-block-header.quarto-title-block.default .quarto-title-meta-contents p.affiliation:last-of-type{margin-bottom:.1em}#title-block-header.quarto-title-block.default p.affiliation{margin-bottom:.1em}#title-block-header.quarto-title-block.default .keywords,#title-block-header.quarto-title-block.default .description,#title-block-header.quarto-title-block.default .abstract{margin-top:0}#title-block-header.quarto-title-block.default .keywords>p,#title-block-header.quarto-title-block.default .description>p,#title-block-header.quarto-title-block.default .abstract>p{font-size:.9em}#title-block-header.quarto-title-block.default .keywords>p:last-of-type,#title-block-header.quarto-title-block.default .description>p:last-of-type,#title-block-header.quarto-title-block.default .abstract>p:last-of-type{margin-bottom:0}#title-block-header.quarto-title-block.default .keywords .block-title,#title-block-header.quarto-title-block.default .description .block-title,#title-block-header.quarto-title-block.default .abstract .block-title{margin-top:1em;text-transform:uppercase;font-size:.8em;opacity:.8;font-weight:400}#title-block-header.quarto-title-block.default .quarto-title-meta-author{display:grid;grid-template-columns:minmax(max-content, 1fr) 1fr;grid-column-gap:1em}.quarto-title-tools-only{display:flex;justify-content:right}
diff --git a/docs/site_libs/bootstrap/bootstrap.min.css b/docs/site_libs/bootstrap/bootstrap.min.css
index 3093af1c..64c2771d 100644
--- a/docs/site_libs/bootstrap/bootstrap.min.css
+++ b/docs/site_libs/bootstrap/bootstrap.min.css
@@ -2,11 +2,11 @@
  * Bootstrap  v5.3.1 (https://getbootstrap.com/)
  * Copyright 2011-2023 The Bootstrap Authors
  * Licensed under MIT (https://github.com/twbs/bootstrap/blob/main/LICENSE)
- */@import"https://fonts.googleapis.com/css2?family=Source+Sans+Pro:wght@300;400;700&display=swap";:root,[data-bs-theme=light]{--bs-blue: #2780e3;--bs-indigo: #6610f2;--bs-purple: #613d7c;--bs-pink: #e83e8c;--bs-red: #ff0039;--bs-orange: #f0ad4e;--bs-yellow: #ff7518;--bs-green: #3fb618;--bs-teal: #20c997;--bs-cyan: #9954bb;--bs-black: #000;--bs-white: #fff;--bs-gray: #6c757d;--bs-gray-dark: #343a40;--bs-gray-100: #f8f9fa;--bs-gray-200: #e9ecef;--bs-gray-300: #dee2e6;--bs-gray-400: #ced4da;--bs-gray-500: #adb5bd;--bs-gray-600: #6c757d;--bs-gray-700: #495057;--bs-gray-800: #343a40;--bs-gray-900: #212529;--bs-default: #343a40;--bs-primary: #2780e3;--bs-secondary: #343a40;--bs-success: #3fb618;--bs-info: #9954bb;--bs-warning: #ff7518;--bs-danger: #ff0039;--bs-light: #f8f9fa;--bs-dark: #343a40;--bs-default-rgb: 52, 58, 64;--bs-primary-rgb: 39, 128, 227;--bs-secondary-rgb: 52, 58, 64;--bs-success-rgb: 63, 182, 24;--bs-info-rgb: 153, 84, 187;--bs-warning-rgb: 255, 117, 24;--bs-danger-rgb: 255, 0, 57;--bs-light-rgb: 248, 249, 250;--bs-dark-rgb: 52, 58, 64;--bs-primary-text-emphasis: #10335b;--bs-secondary-text-emphasis: #15171a;--bs-success-text-emphasis: #19490a;--bs-info-text-emphasis: #3d224b;--bs-warning-text-emphasis: #662f0a;--bs-danger-text-emphasis: #660017;--bs-light-text-emphasis: #495057;--bs-dark-text-emphasis: #495057;--bs-primary-bg-subtle: #d4e6f9;--bs-secondary-bg-subtle: #d6d8d9;--bs-success-bg-subtle: #d9f0d1;--bs-info-bg-subtle: #ebddf1;--bs-warning-bg-subtle: #ffe3d1;--bs-danger-bg-subtle: #ffccd7;--bs-light-bg-subtle: #fcfcfd;--bs-dark-bg-subtle: #ced4da;--bs-primary-border-subtle: #a9ccf4;--bs-secondary-border-subtle: #aeb0b3;--bs-success-border-subtle: #b2e2a3;--bs-info-border-subtle: #d6bbe4;--bs-warning-border-subtle: #ffc8a3;--bs-danger-border-subtle: #ff99b0;--bs-light-border-subtle: #e9ecef;--bs-dark-border-subtle: #adb5bd;--bs-white-rgb: 255, 255, 255;--bs-black-rgb: 0, 0, 0;--bs-font-sans-serif: "Source Sans Pro", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";--bs-font-monospace: SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;--bs-gradient: linear-gradient(180deg, rgba(255, 255, 255, 0.15), rgba(255, 255, 255, 0));--bs-root-font-size: 17px;--bs-body-font-family: "Source Sans Pro", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";--bs-body-font-size:1rem;--bs-body-font-weight: 400;--bs-body-line-height: 1.5;--bs-body-color: #343a40;--bs-body-color-rgb: 52, 58, 64;--bs-body-bg: #fff;--bs-body-bg-rgb: 255, 255, 255;--bs-emphasis-color: #000;--bs-emphasis-color-rgb: 0, 0, 0;--bs-secondary-color: rgba(52, 58, 64, 0.75);--bs-secondary-color-rgb: 52, 58, 64;--bs-secondary-bg: #e9ecef;--bs-secondary-bg-rgb: 233, 236, 239;--bs-tertiary-color: rgba(52, 58, 64, 0.5);--bs-tertiary-color-rgb: 52, 58, 64;--bs-tertiary-bg: #f8f9fa;--bs-tertiary-bg-rgb: 248, 249, 250;--bs-heading-color: inherit;--bs-link-color: #2761e3;--bs-link-color-rgb: 39, 97, 227;--bs-link-decoration: underline;--bs-link-hover-color: #1f4eb6;--bs-link-hover-color-rgb: 31, 78, 182;--bs-code-color: #7d12ba;--bs-highlight-bg: #ffe3d1;--bs-border-width: 1px;--bs-border-style: solid;--bs-border-color: #dee2e6;--bs-border-color-translucent: rgba(0, 0, 0, 0.175);--bs-border-radius: 0.25rem;--bs-border-radius-sm: 0.2em;--bs-border-radius-lg: 0.5rem;--bs-border-radius-xl: 1rem;--bs-border-radius-xxl: 2rem;--bs-border-radius-2xl: var(--bs-border-radius-xxl);--bs-border-radius-pill: 50rem;--bs-box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);--bs-box-shadow-sm: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.075);--bs-box-shadow-lg: 0 1rem 3rem rgba(0, 0, 0, 0.175);--bs-box-shadow-inset: inset 0 1px 2px rgba(0, 0, 0, 0.075);--bs-focus-ring-width: 0.25rem;--bs-focus-ring-opacity: 0.25;--bs-focus-ring-color: rgba(39, 128, 227, 0.25);--bs-form-valid-color: #3fb618;--bs-form-valid-border-color: #3fb618;--bs-form-invalid-color: #ff0039;--bs-form-invalid-border-color: #ff0039}[data-bs-theme=dark]{color-scheme:dark;--bs-body-color: #dee2e6;--bs-body-color-rgb: 222, 226, 230;--bs-body-bg: #212529;--bs-body-bg-rgb: 33, 37, 41;--bs-emphasis-color: #fff;--bs-emphasis-color-rgb: 255, 255, 255;--bs-secondary-color: rgba(222, 226, 230, 0.75);--bs-secondary-color-rgb: 222, 226, 230;--bs-secondary-bg: #343a40;--bs-secondary-bg-rgb: 52, 58, 64;--bs-tertiary-color: rgba(222, 226, 230, 0.5);--bs-tertiary-color-rgb: 222, 226, 230;--bs-tertiary-bg: #2b3035;--bs-tertiary-bg-rgb: 43, 48, 53;--bs-primary-text-emphasis: #7db3ee;--bs-secondary-text-emphasis: #85898c;--bs-success-text-emphasis: #8cd374;--bs-info-text-emphasis: #c298d6;--bs-warning-text-emphasis: #ffac74;--bs-danger-text-emphasis: #ff6688;--bs-light-text-emphasis: #f8f9fa;--bs-dark-text-emphasis: #dee2e6;--bs-primary-bg-subtle: #081a2d;--bs-secondary-bg-subtle: #0a0c0d;--bs-success-bg-subtle: #0d2405;--bs-info-bg-subtle: #1f1125;--bs-warning-bg-subtle: #331705;--bs-danger-bg-subtle: #33000b;--bs-light-bg-subtle: #343a40;--bs-dark-bg-subtle: #1a1d20;--bs-primary-border-subtle: #174d88;--bs-secondary-border-subtle: #1f2326;--bs-success-border-subtle: #266d0e;--bs-info-border-subtle: #5c3270;--bs-warning-border-subtle: #99460e;--bs-danger-border-subtle: #990022;--bs-light-border-subtle: #495057;--bs-dark-border-subtle: #343a40;--bs-heading-color: inherit;--bs-link-color: #7db3ee;--bs-link-hover-color: #97c2f1;--bs-link-color-rgb: 125, 179, 238;--bs-link-hover-color-rgb: 151, 194, 241;--bs-code-color: white;--bs-border-color: #495057;--bs-border-color-translucent: rgba(255, 255, 255, 0.15);--bs-form-valid-color: #8cd374;--bs-form-valid-border-color: #8cd374;--bs-form-invalid-color: #ff6688;--bs-form-invalid-border-color: #ff6688}*,*::before,*::after{box-sizing:border-box}:root{font-size:var(--bs-root-font-size)}body{margin:0;font-family:var(--bs-body-font-family);font-size:var(--bs-body-font-size);font-weight:var(--bs-body-font-weight);line-height:var(--bs-body-line-height);color:var(--bs-body-color);text-align:var(--bs-body-text-align);background-color:var(--bs-body-bg);-webkit-text-size-adjust:100%;-webkit-tap-highlight-color:rgba(0,0,0,0)}hr{margin:1rem 0;color:inherit;border:0;border-top:1px solid;opacity:.25}h6,.h6,h5,.h5,h4,.h4,h3,.h3,h2,.h2,h1,.h1{margin-top:0;margin-bottom:.5rem;font-weight:400;line-height:1.2;color:var(--bs-heading-color)}h1,.h1{font-size:calc(1.325rem + 0.9vw)}@media(min-width: 1200px){h1,.h1{font-size:2rem}}h2,.h2{font-size:calc(1.29rem + 0.48vw)}@media(min-width: 1200px){h2,.h2{font-size:1.65rem}}h3,.h3{font-size:calc(1.27rem + 0.24vw)}@media(min-width: 1200px){h3,.h3{font-size:1.45rem}}h4,.h4{font-size:1.25rem}h5,.h5{font-size:1.1rem}h6,.h6{font-size:1rem}p{margin-top:0;margin-bottom:1rem}abbr[title]{text-decoration:underline dotted;-webkit-text-decoration:underline dotted;-moz-text-decoration:underline dotted;-ms-text-decoration:underline dotted;-o-text-decoration:underline dotted;cursor:help;text-decoration-skip-ink:none}address{margin-bottom:1rem;font-style:normal;line-height:inherit}ol,ul{padding-left:2rem}ol,ul,dl{margin-top:0;margin-bottom:1rem}ol ol,ul ul,ol ul,ul ol{margin-bottom:0}dt{font-weight:700}dd{margin-bottom:.5rem;margin-left:0}blockquote{margin:0 0 1rem;padding:.625rem 1.25rem;border-left:.25rem solid #e9ecef}blockquote p:last-child,blockquote ul:last-child,blockquote ol:last-child{margin-bottom:0}b,strong{font-weight:bolder}small,.small{font-size:0.875em}mark,.mark{padding:.1875em;background-color:var(--bs-highlight-bg)}sub,sup{position:relative;font-size:0.75em;line-height:0;vertical-align:baseline}sub{bottom:-0.25em}sup{top:-0.5em}a{color:rgba(var(--bs-link-color-rgb), var(--bs-link-opacity, 1));text-decoration:underline;-webkit-text-decoration:underline;-moz-text-decoration:underline;-ms-text-decoration:underline;-o-text-decoration:underline}a:hover{--bs-link-color-rgb: var(--bs-link-hover-color-rgb)}a:not([href]):not([class]),a:not([href]):not([class]):hover{color:inherit;text-decoration:none}pre,code,kbd,samp{font-family:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace;font-size:1em}pre{display:block;margin-top:0;margin-bottom:1rem;overflow:auto;font-size:0.875em;color:#000;background-color:#f8f9fa;padding:.5rem;border:1px solid var(--bs-border-color, #dee2e6)}pre code{background-color:rgba(0,0,0,0);font-size:inherit;color:inherit;word-break:normal}code{font-size:0.875em;color:var(--bs-code-color);background-color:#f8f9fa;padding:.125rem .25rem;word-wrap:break-word}a>code{color:inherit}kbd{padding:.4rem .4rem;font-size:0.875em;color:#fff;background-color:#343a40}kbd kbd{padding:0;font-size:1em}figure{margin:0 0 1rem}img,svg{vertical-align:middle}table{caption-side:bottom;border-collapse:collapse}caption{padding-top:.5rem;padding-bottom:.5rem;color:rgba(52,58,64,.75);text-align:left}th{text-align:inherit;text-align:-webkit-match-parent}thead,tbody,tfoot,tr,td,th{border-color:inherit;border-style:solid;border-width:0}label{display:inline-block}button{border-radius:0}button:focus:not(:focus-visible){outline:0}input,button,select,optgroup,textarea{margin:0;font-family:inherit;font-size:inherit;line-height:inherit}button,select{text-transform:none}[role=button]{cursor:pointer}select{word-wrap:normal}select:disabled{opacity:1}[list]:not([type=date]):not([type=datetime-local]):not([type=month]):not([type=week]):not([type=time])::-webkit-calendar-picker-indicator{display:none !important}button,[type=button],[type=reset],[type=submit]{-webkit-appearance:button}button:not(:disabled),[type=button]:not(:disabled),[type=reset]:not(:disabled),[type=submit]:not(:disabled){cursor:pointer}::-moz-focus-inner{padding:0;border-style:none}textarea{resize:vertical}fieldset{min-width:0;padding:0;margin:0;border:0}legend{float:left;width:100%;padding:0;margin-bottom:.5rem;font-size:calc(1.275rem + 0.3vw);line-height:inherit}@media(min-width: 1200px){legend{font-size:1.5rem}}legend+*{clear:left}::-webkit-datetime-edit-fields-wrapper,::-webkit-datetime-edit-text,::-webkit-datetime-edit-minute,::-webkit-datetime-edit-hour-field,::-webkit-datetime-edit-day-field,::-webkit-datetime-edit-month-field,::-webkit-datetime-edit-year-field{padding:0}::-webkit-inner-spin-button{height:auto}[type=search]{-webkit-appearance:textfield;outline-offset:-2px}::-webkit-search-decoration{-webkit-appearance:none}::-webkit-color-swatch-wrapper{padding:0}::file-selector-button{font:inherit;-webkit-appearance:button}output{display:inline-block}iframe{border:0}summary{display:list-item;cursor:pointer}progress{vertical-align:baseline}[hidden]{display:none !important}.lead{font-size:1.25rem;font-weight:300}.display-1{font-size:calc(1.625rem + 4.5vw);font-weight:300;line-height:1.2}@media(min-width: 1200px){.display-1{font-size:5rem}}.display-2{font-size:calc(1.575rem + 3.9vw);font-weight:300;line-height:1.2}@media(min-width: 1200px){.display-2{font-size:4.5rem}}.display-3{font-size:calc(1.525rem + 3.3vw);font-weight:300;line-height:1.2}@media(min-width: 1200px){.display-3{font-size:4rem}}.display-4{font-size:calc(1.475rem + 2.7vw);font-weight:300;line-height:1.2}@media(min-width: 1200px){.display-4{font-size:3.5rem}}.display-5{font-size:calc(1.425rem + 2.1vw);font-weight:300;line-height:1.2}@media(min-width: 1200px){.display-5{font-size:3rem}}.display-6{font-size:calc(1.375rem + 1.5vw);font-weight:300;line-height:1.2}@media(min-width: 1200px){.display-6{font-size:2.5rem}}.list-unstyled{padding-left:0;list-style:none}.list-inline{padding-left:0;list-style:none}.list-inline-item{display:inline-block}.list-inline-item:not(:last-child){margin-right:.5rem}.initialism{font-size:0.875em;text-transform:uppercase}.blockquote{margin-bottom:1rem;font-size:1.25rem}.blockquote>:last-child{margin-bottom:0}.blockquote-footer{margin-top:-1rem;margin-bottom:1rem;font-size:0.875em;color:#6c757d}.blockquote-footer::before{content:"— "}.img-fluid{max-width:100%;height:auto}.img-thumbnail{padding:.25rem;background-color:#fff;border:1px solid #dee2e6;max-width:100%;height:auto}.figure{display:inline-block}.figure-img{margin-bottom:.5rem;line-height:1}.figure-caption{font-size:0.875em;color:rgba(52,58,64,.75)}.container,.container-fluid,.container-xxl,.container-xl,.container-lg,.container-md,.container-sm{--bs-gutter-x: 1.5rem;--bs-gutter-y: 0;width:100%;padding-right:calc(var(--bs-gutter-x)*.5);padding-left:calc(var(--bs-gutter-x)*.5);margin-right:auto;margin-left:auto}@media(min-width: 576px){.container-sm,.container{max-width:540px}}@media(min-width: 768px){.container-md,.container-sm,.container{max-width:720px}}@media(min-width: 992px){.container-lg,.container-md,.container-sm,.container{max-width:960px}}@media(min-width: 1200px){.container-xl,.container-lg,.container-md,.container-sm,.container{max-width:1140px}}@media(min-width: 1400px){.container-xxl,.container-xl,.container-lg,.container-md,.container-sm,.container{max-width:1320px}}:root{--bs-breakpoint-xs: 0;--bs-breakpoint-sm: 576px;--bs-breakpoint-md: 768px;--bs-breakpoint-lg: 992px;--bs-breakpoint-xl: 1200px;--bs-breakpoint-xxl: 1400px}.grid{display:grid;grid-template-rows:repeat(var(--bs-rows, 1), 1fr);grid-template-columns:repeat(var(--bs-columns, 12), 1fr);gap:var(--bs-gap, 1.5rem)}.grid .g-col-1{grid-column:auto/span 1}.grid .g-col-2{grid-column:auto/span 2}.grid .g-col-3{grid-column:auto/span 3}.grid .g-col-4{grid-column:auto/span 4}.grid .g-col-5{grid-column:auto/span 5}.grid .g-col-6{grid-column:auto/span 6}.grid .g-col-7{grid-column:auto/span 7}.grid .g-col-8{grid-column:auto/span 8}.grid .g-col-9{grid-column:auto/span 9}.grid .g-col-10{grid-column:auto/span 10}.grid .g-col-11{grid-column:auto/span 11}.grid .g-col-12{grid-column:auto/span 12}.grid .g-start-1{grid-column-start:1}.grid .g-start-2{grid-column-start:2}.grid .g-start-3{grid-column-start:3}.grid .g-start-4{grid-column-start:4}.grid .g-start-5{grid-column-start:5}.grid .g-start-6{grid-column-start:6}.grid .g-start-7{grid-column-start:7}.grid .g-start-8{grid-column-start:8}.grid .g-start-9{grid-column-start:9}.grid .g-start-10{grid-column-start:10}.grid .g-start-11{grid-column-start:11}@media(min-width: 576px){.grid .g-col-sm-1{grid-column:auto/span 1}.grid .g-col-sm-2{grid-column:auto/span 2}.grid .g-col-sm-3{grid-column:auto/span 3}.grid .g-col-sm-4{grid-column:auto/span 4}.grid .g-col-sm-5{grid-column:auto/span 5}.grid .g-col-sm-6{grid-column:auto/span 6}.grid .g-col-sm-7{grid-column:auto/span 7}.grid .g-col-sm-8{grid-column:auto/span 8}.grid .g-col-sm-9{grid-column:auto/span 9}.grid .g-col-sm-10{grid-column:auto/span 10}.grid .g-col-sm-11{grid-column:auto/span 11}.grid .g-col-sm-12{grid-column:auto/span 12}.grid .g-start-sm-1{grid-column-start:1}.grid .g-start-sm-2{grid-column-start:2}.grid .g-start-sm-3{grid-column-start:3}.grid .g-start-sm-4{grid-column-start:4}.grid .g-start-sm-5{grid-column-start:5}.grid .g-start-sm-6{grid-column-start:6}.grid .g-start-sm-7{grid-column-start:7}.grid .g-start-sm-8{grid-column-start:8}.grid .g-start-sm-9{grid-column-start:9}.grid .g-start-sm-10{grid-column-start:10}.grid .g-start-sm-11{grid-column-start:11}}@media(min-width: 768px){.grid .g-col-md-1{grid-column:auto/span 1}.grid .g-col-md-2{grid-column:auto/span 2}.grid .g-col-md-3{grid-column:auto/span 3}.grid .g-col-md-4{grid-column:auto/span 4}.grid .g-col-md-5{grid-column:auto/span 5}.grid .g-col-md-6{grid-column:auto/span 6}.grid .g-col-md-7{grid-column:auto/span 7}.grid .g-col-md-8{grid-column:auto/span 8}.grid .g-col-md-9{grid-column:auto/span 9}.grid .g-col-md-10{grid-column:auto/span 10}.grid .g-col-md-11{grid-column:auto/span 11}.grid .g-col-md-12{grid-column:auto/span 12}.grid .g-start-md-1{grid-column-start:1}.grid .g-start-md-2{grid-column-start:2}.grid .g-start-md-3{grid-column-start:3}.grid .g-start-md-4{grid-column-start:4}.grid .g-start-md-5{grid-column-start:5}.grid .g-start-md-6{grid-column-start:6}.grid .g-start-md-7{grid-column-start:7}.grid .g-start-md-8{grid-column-start:8}.grid .g-start-md-9{grid-column-start:9}.grid .g-start-md-10{grid-column-start:10}.grid .g-start-md-11{grid-column-start:11}}@media(min-width: 992px){.grid .g-col-lg-1{grid-column:auto/span 1}.grid .g-col-lg-2{grid-column:auto/span 2}.grid .g-col-lg-3{grid-column:auto/span 3}.grid .g-col-lg-4{grid-column:auto/span 4}.grid .g-col-lg-5{grid-column:auto/span 5}.grid .g-col-lg-6{grid-column:auto/span 6}.grid .g-col-lg-7{grid-column:auto/span 7}.grid .g-col-lg-8{grid-column:auto/span 8}.grid .g-col-lg-9{grid-column:auto/span 9}.grid .g-col-lg-10{grid-column:auto/span 10}.grid .g-col-lg-11{grid-column:auto/span 11}.grid .g-col-lg-12{grid-column:auto/span 12}.grid .g-start-lg-1{grid-column-start:1}.grid .g-start-lg-2{grid-column-start:2}.grid .g-start-lg-3{grid-column-start:3}.grid .g-start-lg-4{grid-column-start:4}.grid .g-start-lg-5{grid-column-start:5}.grid .g-start-lg-6{grid-column-start:6}.grid .g-start-lg-7{grid-column-start:7}.grid .g-start-lg-8{grid-column-start:8}.grid .g-start-lg-9{grid-column-start:9}.grid .g-start-lg-10{grid-column-start:10}.grid .g-start-lg-11{grid-column-start:11}}@media(min-width: 1200px){.grid .g-col-xl-1{grid-column:auto/span 1}.grid .g-col-xl-2{grid-column:auto/span 2}.grid .g-col-xl-3{grid-column:auto/span 3}.grid .g-col-xl-4{grid-column:auto/span 4}.grid .g-col-xl-5{grid-column:auto/span 5}.grid .g-col-xl-6{grid-column:auto/span 6}.grid .g-col-xl-7{grid-column:auto/span 7}.grid .g-col-xl-8{grid-column:auto/span 8}.grid .g-col-xl-9{grid-column:auto/span 9}.grid .g-col-xl-10{grid-column:auto/span 10}.grid .g-col-xl-11{grid-column:auto/span 11}.grid .g-col-xl-12{grid-column:auto/span 12}.grid .g-start-xl-1{grid-column-start:1}.grid .g-start-xl-2{grid-column-start:2}.grid .g-start-xl-3{grid-column-start:3}.grid .g-start-xl-4{grid-column-start:4}.grid .g-start-xl-5{grid-column-start:5}.grid .g-start-xl-6{grid-column-start:6}.grid .g-start-xl-7{grid-column-start:7}.grid .g-start-xl-8{grid-column-start:8}.grid .g-start-xl-9{grid-column-start:9}.grid .g-start-xl-10{grid-column-start:10}.grid .g-start-xl-11{grid-column-start:11}}@media(min-width: 1400px){.grid .g-col-xxl-1{grid-column:auto/span 1}.grid .g-col-xxl-2{grid-column:auto/span 2}.grid .g-col-xxl-3{grid-column:auto/span 3}.grid .g-col-xxl-4{grid-column:auto/span 4}.grid .g-col-xxl-5{grid-column:auto/span 5}.grid .g-col-xxl-6{grid-column:auto/span 6}.grid .g-col-xxl-7{grid-column:auto/span 7}.grid .g-col-xxl-8{grid-column:auto/span 8}.grid .g-col-xxl-9{grid-column:auto/span 9}.grid .g-col-xxl-10{grid-column:auto/span 10}.grid .g-col-xxl-11{grid-column:auto/span 11}.grid .g-col-xxl-12{grid-column:auto/span 12}.grid .g-start-xxl-1{grid-column-start:1}.grid .g-start-xxl-2{grid-column-start:2}.grid .g-start-xxl-3{grid-column-start:3}.grid .g-start-xxl-4{grid-column-start:4}.grid .g-start-xxl-5{grid-column-start:5}.grid .g-start-xxl-6{grid-column-start:6}.grid .g-start-xxl-7{grid-column-start:7}.grid .g-start-xxl-8{grid-column-start:8}.grid .g-start-xxl-9{grid-column-start:9}.grid .g-start-xxl-10{grid-column-start:10}.grid .g-start-xxl-11{grid-column-start:11}}.table{--bs-table-color-type: initial;--bs-table-bg-type: initial;--bs-table-color-state: initial;--bs-table-bg-state: initial;--bs-table-color: #343a40;--bs-table-bg: #fff;--bs-table-border-color: #dee2e6;--bs-table-accent-bg: transparent;--bs-table-striped-color: #343a40;--bs-table-striped-bg: rgba(0, 0, 0, 0.05);--bs-table-active-color: #343a40;--bs-table-active-bg: rgba(0, 0, 0, 0.1);--bs-table-hover-color: #343a40;--bs-table-hover-bg: rgba(0, 0, 0, 0.075);width:100%;margin-bottom:1rem;vertical-align:top;border-color:var(--bs-table-border-color)}.table>:not(caption)>*>*{padding:.5rem .5rem;color:var(--bs-table-color-state, var(--bs-table-color-type, var(--bs-table-color)));background-color:var(--bs-table-bg);border-bottom-width:1px;box-shadow:inset 0 0 0 9999px var(--bs-table-bg-state, var(--bs-table-bg-type, var(--bs-table-accent-bg)))}.table>tbody{vertical-align:inherit}.table>thead{vertical-align:bottom}.table-group-divider{border-top:calc(1px*2) solid #b2bac1}.caption-top{caption-side:top}.table-sm>:not(caption)>*>*{padding:.25rem .25rem}.table-bordered>:not(caption)>*{border-width:1px 0}.table-bordered>:not(caption)>*>*{border-width:0 1px}.table-borderless>:not(caption)>*>*{border-bottom-width:0}.table-borderless>:not(:first-child){border-top-width:0}.table-striped>tbody>tr:nth-of-type(odd)>*{--bs-table-color-type: var(--bs-table-striped-color);--bs-table-bg-type: var(--bs-table-striped-bg)}.table-striped-columns>:not(caption)>tr>:nth-child(even){--bs-table-color-type: var(--bs-table-striped-color);--bs-table-bg-type: var(--bs-table-striped-bg)}.table-active{--bs-table-color-state: var(--bs-table-active-color);--bs-table-bg-state: var(--bs-table-active-bg)}.table-hover>tbody>tr:hover>*{--bs-table-color-state: var(--bs-table-hover-color);--bs-table-bg-state: var(--bs-table-hover-bg)}.table-primary{--bs-table-color: #000;--bs-table-bg: #d4e6f9;--bs-table-border-color: #bfcfe0;--bs-table-striped-bg: #c9dbed;--bs-table-striped-color: #000;--bs-table-active-bg: #bfcfe0;--bs-table-active-color: #000;--bs-table-hover-bg: #c4d5e6;--bs-table-hover-color: #000;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-secondary{--bs-table-color: #000;--bs-table-bg: #d6d8d9;--bs-table-border-color: #c1c2c3;--bs-table-striped-bg: #cbcdce;--bs-table-striped-color: #000;--bs-table-active-bg: #c1c2c3;--bs-table-active-color: #000;--bs-table-hover-bg: #c6c8c9;--bs-table-hover-color: #000;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-success{--bs-table-color: #000;--bs-table-bg: #d9f0d1;--bs-table-border-color: #c3d8bc;--bs-table-striped-bg: #cee4c7;--bs-table-striped-color: #000;--bs-table-active-bg: #c3d8bc;--bs-table-active-color: #000;--bs-table-hover-bg: #c9dec1;--bs-table-hover-color: #000;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-info{--bs-table-color: #000;--bs-table-bg: #ebddf1;--bs-table-border-color: #d4c7d9;--bs-table-striped-bg: #dfd2e5;--bs-table-striped-color: #000;--bs-table-active-bg: #d4c7d9;--bs-table-active-color: #000;--bs-table-hover-bg: #d9ccdf;--bs-table-hover-color: #000;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-warning{--bs-table-color: #000;--bs-table-bg: #ffe3d1;--bs-table-border-color: #e6ccbc;--bs-table-striped-bg: #f2d8c7;--bs-table-striped-color: #000;--bs-table-active-bg: #e6ccbc;--bs-table-active-color: #000;--bs-table-hover-bg: #ecd2c1;--bs-table-hover-color: #000;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-danger{--bs-table-color: #000;--bs-table-bg: #ffccd7;--bs-table-border-color: #e6b8c2;--bs-table-striped-bg: #f2c2cc;--bs-table-striped-color: #000;--bs-table-active-bg: #e6b8c2;--bs-table-active-color: #000;--bs-table-hover-bg: #ecbdc7;--bs-table-hover-color: #000;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-light{--bs-table-color: #000;--bs-table-bg: #f8f9fa;--bs-table-border-color: #dfe0e1;--bs-table-striped-bg: #ecedee;--bs-table-striped-color: #000;--bs-table-active-bg: #dfe0e1;--bs-table-active-color: #000;--bs-table-hover-bg: #e5e6e7;--bs-table-hover-color: #000;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-dark{--bs-table-color: #fff;--bs-table-bg: #343a40;--bs-table-border-color: #484e53;--bs-table-striped-bg: #3e444a;--bs-table-striped-color: #fff;--bs-table-active-bg: #484e53;--bs-table-active-color: #fff;--bs-table-hover-bg: #43494e;--bs-table-hover-color: #fff;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-responsive{overflow-x:auto;-webkit-overflow-scrolling:touch}@media(max-width: 575.98px){.table-responsive-sm{overflow-x:auto;-webkit-overflow-scrolling:touch}}@media(max-width: 767.98px){.table-responsive-md{overflow-x:auto;-webkit-overflow-scrolling:touch}}@media(max-width: 991.98px){.table-responsive-lg{overflow-x:auto;-webkit-overflow-scrolling:touch}}@media(max-width: 1199.98px){.table-responsive-xl{overflow-x:auto;-webkit-overflow-scrolling:touch}}@media(max-width: 1399.98px){.table-responsive-xxl{overflow-x:auto;-webkit-overflow-scrolling:touch}}.form-label,.shiny-input-container .control-label{margin-bottom:.5rem}.col-form-label{padding-top:calc(0.375rem + 1px);padding-bottom:calc(0.375rem + 1px);margin-bottom:0;font-size:inherit;line-height:1.5}.col-form-label-lg{padding-top:calc(0.5rem + 1px);padding-bottom:calc(0.5rem + 1px);font-size:1.25rem}.col-form-label-sm{padding-top:calc(0.25rem + 1px);padding-bottom:calc(0.25rem + 1px);font-size:0.875rem}.form-text{margin-top:.25rem;font-size:0.875em;color:rgba(52,58,64,.75)}.form-control{display:block;width:100%;padding:.375rem .75rem;font-size:1rem;font-weight:400;line-height:1.5;color:#343a40;appearance:none;-webkit-appearance:none;-moz-appearance:none;-ms-appearance:none;-o-appearance:none;background-color:#fff;background-clip:padding-box;border:1px solid #dee2e6;border-radius:0;transition:border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media(prefers-reduced-motion: reduce){.form-control{transition:none}}.form-control[type=file]{overflow:hidden}.form-control[type=file]:not(:disabled):not([readonly]){cursor:pointer}.form-control:focus{color:#343a40;background-color:#fff;border-color:#93c0f1;outline:0;box-shadow:0 0 0 .25rem rgba(39,128,227,.25)}.form-control::-webkit-date-and-time-value{min-width:85px;height:1.5em;margin:0}.form-control::-webkit-datetime-edit{display:block;padding:0}.form-control::placeholder{color:rgba(52,58,64,.75);opacity:1}.form-control:disabled{background-color:#e9ecef;opacity:1}.form-control::file-selector-button{padding:.375rem .75rem;margin:-0.375rem -0.75rem;margin-inline-end:.75rem;color:#343a40;background-color:#f8f9fa;pointer-events:none;border-color:inherit;border-style:solid;border-width:0;border-inline-end-width:1px;border-radius:0;transition:color .15s ease-in-out,background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media(prefers-reduced-motion: reduce){.form-control::file-selector-button{transition:none}}.form-control:hover:not(:disabled):not([readonly])::file-selector-button{background-color:#e9ecef}.form-control-plaintext{display:block;width:100%;padding:.375rem 0;margin-bottom:0;line-height:1.5;color:#343a40;background-color:rgba(0,0,0,0);border:solid rgba(0,0,0,0);border-width:1px 0}.form-control-plaintext:focus{outline:0}.form-control-plaintext.form-control-sm,.form-control-plaintext.form-control-lg{padding-right:0;padding-left:0}.form-control-sm{min-height:calc(1.5em + 0.5rem + calc(1px * 2));padding:.25rem .5rem;font-size:0.875rem}.form-control-sm::file-selector-button{padding:.25rem .5rem;margin:-0.25rem -0.5rem;margin-inline-end:.5rem}.form-control-lg{min-height:calc(1.5em + 1rem + calc(1px * 2));padding:.5rem 1rem;font-size:1.25rem}.form-control-lg::file-selector-button{padding:.5rem 1rem;margin:-0.5rem -1rem;margin-inline-end:1rem}textarea.form-control{min-height:calc(1.5em + 0.75rem + calc(1px * 2))}textarea.form-control-sm{min-height:calc(1.5em + 0.5rem + calc(1px * 2))}textarea.form-control-lg{min-height:calc(1.5em + 1rem + calc(1px * 2))}.form-control-color{width:3rem;height:calc(1.5em + 0.75rem + calc(1px * 2));padding:.375rem}.form-control-color:not(:disabled):not([readonly]){cursor:pointer}.form-control-color::-moz-color-swatch{border:0 !important}.form-control-color::-webkit-color-swatch{border:0 !important}.form-control-color.form-control-sm{height:calc(1.5em + 0.5rem + calc(1px * 2))}.form-control-color.form-control-lg{height:calc(1.5em + 1rem + calc(1px * 2))}.form-select{--bs-form-select-bg-img: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3e%3cpath fill='none' stroke='%23343a40' stroke-linecap='round' stroke-linejoin='round' stroke-width='2' d='m2 5 6 6 6-6'/%3e%3c/svg%3e");display:block;width:100%;padding:.375rem 2.25rem .375rem .75rem;font-size:1rem;font-weight:400;line-height:1.5;color:#343a40;appearance:none;-webkit-appearance:none;-moz-appearance:none;-ms-appearance:none;-o-appearance:none;background-color:#fff;background-image:var(--bs-form-select-bg-img),var(--bs-form-select-bg-icon, none);background-repeat:no-repeat;background-position:right .75rem center;background-size:16px 12px;border:1px solid #dee2e6;border-radius:0;transition:border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media(prefers-reduced-motion: reduce){.form-select{transition:none}}.form-select:focus{border-color:#93c0f1;outline:0;box-shadow:0 0 0 .25rem rgba(39,128,227,.25)}.form-select[multiple],.form-select[size]:not([size="1"]){padding-right:.75rem;background-image:none}.form-select:disabled{background-color:#e9ecef}.form-select:-moz-focusring{color:rgba(0,0,0,0);text-shadow:0 0 0 #343a40}.form-select-sm{padding-top:.25rem;padding-bottom:.25rem;padding-left:.5rem;font-size:0.875rem}.form-select-lg{padding-top:.5rem;padding-bottom:.5rem;padding-left:1rem;font-size:1.25rem}[data-bs-theme=dark] .form-select{--bs-form-select-bg-img: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3e%3cpath fill='none' stroke='%23dee2e6' stroke-linecap='round' stroke-linejoin='round' stroke-width='2' d='m2 5 6 6 6-6'/%3e%3c/svg%3e")}.form-check,.shiny-input-container .checkbox,.shiny-input-container .radio{display:block;min-height:1.5rem;padding-left:0;margin-bottom:.125rem}.form-check .form-check-input,.form-check .shiny-input-container .checkbox input,.form-check .shiny-input-container .radio input,.shiny-input-container .checkbox .form-check-input,.shiny-input-container .checkbox .shiny-input-container .checkbox input,.shiny-input-container .checkbox .shiny-input-container .radio input,.shiny-input-container .radio .form-check-input,.shiny-input-container .radio .shiny-input-container .checkbox input,.shiny-input-container .radio .shiny-input-container .radio input{float:left;margin-left:0}.form-check-reverse{padding-right:0;padding-left:0;text-align:right}.form-check-reverse .form-check-input{float:right;margin-right:0;margin-left:0}.form-check-input,.shiny-input-container .checkbox input,.shiny-input-container .checkbox-inline input,.shiny-input-container .radio input,.shiny-input-container .radio-inline input{--bs-form-check-bg: #fff;width:1em;height:1em;margin-top:.25em;vertical-align:top;appearance:none;-webkit-appearance:none;-moz-appearance:none;-ms-appearance:none;-o-appearance:none;background-color:var(--bs-form-check-bg);background-image:var(--bs-form-check-bg-image);background-repeat:no-repeat;background-position:center;background-size:contain;border:1px solid #dee2e6;print-color-adjust:exact}.form-check-input[type=radio],.shiny-input-container .checkbox input[type=radio],.shiny-input-container .checkbox-inline input[type=radio],.shiny-input-container .radio input[type=radio],.shiny-input-container .radio-inline input[type=radio]{border-radius:50%}.form-check-input:active,.shiny-input-container .checkbox input:active,.shiny-input-container .checkbox-inline input:active,.shiny-input-container .radio input:active,.shiny-input-container .radio-inline input:active{filter:brightness(90%)}.form-check-input:focus,.shiny-input-container .checkbox input:focus,.shiny-input-container .checkbox-inline input:focus,.shiny-input-container .radio input:focus,.shiny-input-container .radio-inline input:focus{border-color:#93c0f1;outline:0;box-shadow:0 0 0 .25rem rgba(39,128,227,.25)}.form-check-input:checked,.shiny-input-container .checkbox input:checked,.shiny-input-container .checkbox-inline input:checked,.shiny-input-container .radio input:checked,.shiny-input-container .radio-inline input:checked{background-color:#2780e3;border-color:#2780e3}.form-check-input:checked[type=checkbox],.shiny-input-container .checkbox input:checked[type=checkbox],.shiny-input-container .checkbox-inline input:checked[type=checkbox],.shiny-input-container .radio input:checked[type=checkbox],.shiny-input-container .radio-inline input:checked[type=checkbox]{--bs-form-check-bg-image: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20'%3e%3cpath fill='none' stroke='%23fff' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='m6 10 3 3 6-6'/%3e%3c/svg%3e")}.form-check-input:checked[type=radio],.shiny-input-container .checkbox input:checked[type=radio],.shiny-input-container .checkbox-inline input:checked[type=radio],.shiny-input-container .radio input:checked[type=radio],.shiny-input-container .radio-inline input:checked[type=radio]{--bs-form-check-bg-image: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='-4 -4 8 8'%3e%3ccircle r='2' fill='%23fff'/%3e%3c/svg%3e")}.form-check-input[type=checkbox]:indeterminate,.shiny-input-container .checkbox input[type=checkbox]:indeterminate,.shiny-input-container .checkbox-inline input[type=checkbox]:indeterminate,.shiny-input-container .radio input[type=checkbox]:indeterminate,.shiny-input-container .radio-inline input[type=checkbox]:indeterminate{background-color:#2780e3;border-color:#2780e3;--bs-form-check-bg-image: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20'%3e%3cpath fill='none' stroke='%23fff' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='M6 10h8'/%3e%3c/svg%3e")}.form-check-input:disabled,.shiny-input-container .checkbox input:disabled,.shiny-input-container .checkbox-inline input:disabled,.shiny-input-container .radio input:disabled,.shiny-input-container .radio-inline input:disabled{pointer-events:none;filter:none;opacity:.5}.form-check-input[disabled]~.form-check-label,.form-check-input[disabled]~span,.form-check-input:disabled~.form-check-label,.form-check-input:disabled~span,.shiny-input-container .checkbox input[disabled]~.form-check-label,.shiny-input-container .checkbox input[disabled]~span,.shiny-input-container .checkbox input:disabled~.form-check-label,.shiny-input-container .checkbox input:disabled~span,.shiny-input-container .checkbox-inline input[disabled]~.form-check-label,.shiny-input-container .checkbox-inline input[disabled]~span,.shiny-input-container .checkbox-inline input:disabled~.form-check-label,.shiny-input-container .checkbox-inline input:disabled~span,.shiny-input-container .radio input[disabled]~.form-check-label,.shiny-input-container .radio input[disabled]~span,.shiny-input-container .radio input:disabled~.form-check-label,.shiny-input-container .radio input:disabled~span,.shiny-input-container .radio-inline input[disabled]~.form-check-label,.shiny-input-container .radio-inline input[disabled]~span,.shiny-input-container .radio-inline input:disabled~.form-check-label,.shiny-input-container .radio-inline input:disabled~span{cursor:default;opacity:.5}.form-check-label,.shiny-input-container .checkbox label,.shiny-input-container .checkbox-inline label,.shiny-input-container .radio label,.shiny-input-container .radio-inline label{cursor:pointer}.form-switch{padding-left:2.5em}.form-switch .form-check-input{--bs-form-switch-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='-4 -4 8 8'%3e%3ccircle r='3' fill='rgba%280, 0, 0, 0.25%29'/%3e%3c/svg%3e");width:2em;margin-left:-2.5em;background-image:var(--bs-form-switch-bg);background-position:left center;transition:background-position .15s ease-in-out}@media(prefers-reduced-motion: reduce){.form-switch .form-check-input{transition:none}}.form-switch .form-check-input:focus{--bs-form-switch-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='-4 -4 8 8'%3e%3ccircle r='3' fill='%2393c0f1'/%3e%3c/svg%3e")}.form-switch .form-check-input:checked{background-position:right center;--bs-form-switch-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='-4 -4 8 8'%3e%3ccircle r='3' fill='%23fff'/%3e%3c/svg%3e")}.form-switch.form-check-reverse{padding-right:2.5em;padding-left:0}.form-switch.form-check-reverse .form-check-input{margin-right:-2.5em;margin-left:0}.form-check-inline{display:inline-block;margin-right:1rem}.btn-check{position:absolute;clip:rect(0, 0, 0, 0);pointer-events:none}.btn-check[disabled]+.btn,.btn-check:disabled+.btn{pointer-events:none;filter:none;opacity:.65}[data-bs-theme=dark] .form-switch .form-check-input:not(:checked):not(:focus){--bs-form-switch-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='-4 -4 8 8'%3e%3ccircle r='3' fill='rgba%28255, 255, 255, 0.25%29'/%3e%3c/svg%3e")}.form-range{width:100%;height:1.5rem;padding:0;appearance:none;-webkit-appearance:none;-moz-appearance:none;-ms-appearance:none;-o-appearance:none;background-color:rgba(0,0,0,0)}.form-range:focus{outline:0}.form-range:focus::-webkit-slider-thumb{box-shadow:0 0 0 1px #fff,0 0 0 .25rem rgba(39,128,227,.25)}.form-range:focus::-moz-range-thumb{box-shadow:0 0 0 1px #fff,0 0 0 .25rem rgba(39,128,227,.25)}.form-range::-moz-focus-outer{border:0}.form-range::-webkit-slider-thumb{width:1rem;height:1rem;margin-top:-0.25rem;appearance:none;-webkit-appearance:none;-moz-appearance:none;-ms-appearance:none;-o-appearance:none;background-color:#2780e3;border:0;transition:background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media(prefers-reduced-motion: reduce){.form-range::-webkit-slider-thumb{transition:none}}.form-range::-webkit-slider-thumb:active{background-color:#bed9f7}.form-range::-webkit-slider-runnable-track{width:100%;height:.5rem;color:rgba(0,0,0,0);cursor:pointer;background-color:#f8f9fa;border-color:rgba(0,0,0,0)}.form-range::-moz-range-thumb{width:1rem;height:1rem;appearance:none;-webkit-appearance:none;-moz-appearance:none;-ms-appearance:none;-o-appearance:none;background-color:#2780e3;border:0;transition:background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media(prefers-reduced-motion: reduce){.form-range::-moz-range-thumb{transition:none}}.form-range::-moz-range-thumb:active{background-color:#bed9f7}.form-range::-moz-range-track{width:100%;height:.5rem;color:rgba(0,0,0,0);cursor:pointer;background-color:#f8f9fa;border-color:rgba(0,0,0,0)}.form-range:disabled{pointer-events:none}.form-range:disabled::-webkit-slider-thumb{background-color:rgba(52,58,64,.75)}.form-range:disabled::-moz-range-thumb{background-color:rgba(52,58,64,.75)}.form-floating{position:relative}.form-floating>.form-control,.form-floating>.form-control-plaintext,.form-floating>.form-select{height:calc(3.5rem + calc(1px * 2));min-height:calc(3.5rem + calc(1px * 2));line-height:1.25}.form-floating>label{position:absolute;top:0;left:0;z-index:2;height:100%;padding:1rem .75rem;overflow:hidden;text-align:start;text-overflow:ellipsis;white-space:nowrap;pointer-events:none;border:1px solid rgba(0,0,0,0);transform-origin:0 0;transition:opacity .1s ease-in-out,transform .1s ease-in-out}@media(prefers-reduced-motion: reduce){.form-floating>label{transition:none}}.form-floating>.form-control,.form-floating>.form-control-plaintext{padding:1rem .75rem}.form-floating>.form-control::placeholder,.form-floating>.form-control-plaintext::placeholder{color:rgba(0,0,0,0)}.form-floating>.form-control:focus,.form-floating>.form-control:not(:placeholder-shown),.form-floating>.form-control-plaintext:focus,.form-floating>.form-control-plaintext:not(:placeholder-shown){padding-top:1.625rem;padding-bottom:.625rem}.form-floating>.form-control:-webkit-autofill,.form-floating>.form-control-plaintext:-webkit-autofill{padding-top:1.625rem;padding-bottom:.625rem}.form-floating>.form-select{padding-top:1.625rem;padding-bottom:.625rem}.form-floating>.form-control:focus~label,.form-floating>.form-control:not(:placeholder-shown)~label,.form-floating>.form-control-plaintext~label,.form-floating>.form-select~label{color:rgba(var(--bs-body-color-rgb), 0.65);transform:scale(0.85) translateY(-0.5rem) translateX(0.15rem)}.form-floating>.form-control:focus~label::after,.form-floating>.form-control:not(:placeholder-shown)~label::after,.form-floating>.form-control-plaintext~label::after,.form-floating>.form-select~label::after{position:absolute;inset:1rem .375rem;z-index:-1;height:1.5em;content:"";background-color:#fff}.form-floating>.form-control:-webkit-autofill~label{color:rgba(var(--bs-body-color-rgb), 0.65);transform:scale(0.85) translateY(-0.5rem) translateX(0.15rem)}.form-floating>.form-control-plaintext~label{border-width:1px 0}.form-floating>:disabled~label,.form-floating>.form-control:disabled~label{color:#6c757d}.form-floating>:disabled~label::after,.form-floating>.form-control:disabled~label::after{background-color:#e9ecef}.input-group{position:relative;display:flex;display:-webkit-flex;flex-wrap:wrap;-webkit-flex-wrap:wrap;align-items:stretch;-webkit-align-items:stretch;width:100%}.input-group>.form-control,.input-group>.form-select,.input-group>.form-floating{position:relative;flex:1 1 auto;-webkit-flex:1 1 auto;width:1%;min-width:0}.input-group>.form-control:focus,.input-group>.form-select:focus,.input-group>.form-floating:focus-within{z-index:5}.input-group .btn{position:relative;z-index:2}.input-group .btn:focus{z-index:5}.input-group-text{display:flex;display:-webkit-flex;align-items:center;-webkit-align-items:center;padding:.375rem .75rem;font-size:1rem;font-weight:400;line-height:1.5;color:#343a40;text-align:center;white-space:nowrap;background-color:#f8f9fa;border:1px solid #dee2e6}.input-group-lg>.form-control,.input-group-lg>.form-select,.input-group-lg>.input-group-text,.input-group-lg>.btn{padding:.5rem 1rem;font-size:1.25rem}.input-group-sm>.form-control,.input-group-sm>.form-select,.input-group-sm>.input-group-text,.input-group-sm>.btn{padding:.25rem .5rem;font-size:0.875rem}.input-group-lg>.form-select,.input-group-sm>.form-select{padding-right:3rem}.input-group>:not(:first-child):not(.dropdown-menu):not(.valid-tooltip):not(.valid-feedback):not(.invalid-tooltip):not(.invalid-feedback){margin-left:calc(1px*-1)}.valid-feedback{display:none;width:100%;margin-top:.25rem;font-size:0.875em;color:#3fb618}.valid-tooltip{position:absolute;top:100%;z-index:5;display:none;max-width:100%;padding:.25rem .5rem;margin-top:.1rem;font-size:0.875rem;color:#fff;background-color:#3fb618}.was-validated :valid~.valid-feedback,.was-validated :valid~.valid-tooltip,.is-valid~.valid-feedback,.is-valid~.valid-tooltip{display:block}.was-validated .form-control:valid,.form-control.is-valid{border-color:#3fb618;padding-right:calc(1.5em + 0.75rem);background-image:url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 8 8'%3e%3cpath fill='%233fb618' d='M2.3 6.73.6 4.53c-.4-1.04.46-1.4 1.1-.8l1.1 1.4 3.4-3.8c.6-.63 1.6-.27 1.2.7l-4 4.6c-.43.5-.8.4-1.1.1z'/%3e%3c/svg%3e");background-repeat:no-repeat;background-position:right calc(0.375em + 0.1875rem) center;background-size:calc(0.75em + 0.375rem) calc(0.75em + 0.375rem)}.was-validated .form-control:valid:focus,.form-control.is-valid:focus{border-color:#3fb618;box-shadow:0 0 0 .25rem rgba(63,182,24,.25)}.was-validated textarea.form-control:valid,textarea.form-control.is-valid{padding-right:calc(1.5em + 0.75rem);background-position:top calc(0.375em + 0.1875rem) right calc(0.375em + 0.1875rem)}.was-validated .form-select:valid,.form-select.is-valid{border-color:#3fb618}.was-validated .form-select:valid:not([multiple]):not([size]),.was-validated .form-select:valid:not([multiple])[size="1"],.form-select.is-valid:not([multiple]):not([size]),.form-select.is-valid:not([multiple])[size="1"]{--bs-form-select-bg-icon: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 8 8'%3e%3cpath fill='%233fb618' d='M2.3 6.73.6 4.53c-.4-1.04.46-1.4 1.1-.8l1.1 1.4 3.4-3.8c.6-.63 1.6-.27 1.2.7l-4 4.6c-.43.5-.8.4-1.1.1z'/%3e%3c/svg%3e");padding-right:4.125rem;background-position:right .75rem center,center right 2.25rem;background-size:16px 12px,calc(0.75em + 0.375rem) calc(0.75em + 0.375rem)}.was-validated .form-select:valid:focus,.form-select.is-valid:focus{border-color:#3fb618;box-shadow:0 0 0 .25rem rgba(63,182,24,.25)}.was-validated .form-control-color:valid,.form-control-color.is-valid{width:calc(3rem + calc(1.5em + 0.75rem))}.was-validated .form-check-input:valid,.form-check-input.is-valid{border-color:#3fb618}.was-validated .form-check-input:valid:checked,.form-check-input.is-valid:checked{background-color:#3fb618}.was-validated .form-check-input:valid:focus,.form-check-input.is-valid:focus{box-shadow:0 0 0 .25rem rgba(63,182,24,.25)}.was-validated .form-check-input:valid~.form-check-label,.form-check-input.is-valid~.form-check-label{color:#3fb618}.form-check-inline .form-check-input~.valid-feedback{margin-left:.5em}.was-validated .input-group>.form-control:not(:focus):valid,.input-group>.form-control:not(:focus).is-valid,.was-validated .input-group>.form-select:not(:focus):valid,.input-group>.form-select:not(:focus).is-valid,.was-validated .input-group>.form-floating:not(:focus-within):valid,.input-group>.form-floating:not(:focus-within).is-valid{z-index:3}.invalid-feedback{display:none;width:100%;margin-top:.25rem;font-size:0.875em;color:#ff0039}.invalid-tooltip{position:absolute;top:100%;z-index:5;display:none;max-width:100%;padding:.25rem .5rem;margin-top:.1rem;font-size:0.875rem;color:#fff;background-color:#ff0039}.was-validated :invalid~.invalid-feedback,.was-validated :invalid~.invalid-tooltip,.is-invalid~.invalid-feedback,.is-invalid~.invalid-tooltip{display:block}.was-validated .form-control:invalid,.form-control.is-invalid{border-color:#ff0039;padding-right:calc(1.5em + 0.75rem);background-image:url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12' width='12' height='12' fill='none' stroke='%23ff0039'%3e%3ccircle cx='6' cy='6' r='4.5'/%3e%3cpath stroke-linejoin='round' d='M5.8 3.6h.4L6 6.5z'/%3e%3ccircle cx='6' cy='8.2' r='.6' fill='%23ff0039' stroke='none'/%3e%3c/svg%3e");background-repeat:no-repeat;background-position:right calc(0.375em + 0.1875rem) center;background-size:calc(0.75em + 0.375rem) calc(0.75em + 0.375rem)}.was-validated .form-control:invalid:focus,.form-control.is-invalid:focus{border-color:#ff0039;box-shadow:0 0 0 .25rem rgba(255,0,57,.25)}.was-validated textarea.form-control:invalid,textarea.form-control.is-invalid{padding-right:calc(1.5em + 0.75rem);background-position:top calc(0.375em + 0.1875rem) right calc(0.375em + 0.1875rem)}.was-validated .form-select:invalid,.form-select.is-invalid{border-color:#ff0039}.was-validated .form-select:invalid:not([multiple]):not([size]),.was-validated .form-select:invalid:not([multiple])[size="1"],.form-select.is-invalid:not([multiple]):not([size]),.form-select.is-invalid:not([multiple])[size="1"]{--bs-form-select-bg-icon: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12' width='12' height='12' fill='none' stroke='%23ff0039'%3e%3ccircle cx='6' cy='6' r='4.5'/%3e%3cpath stroke-linejoin='round' d='M5.8 3.6h.4L6 6.5z'/%3e%3ccircle cx='6' cy='8.2' r='.6' fill='%23ff0039' stroke='none'/%3e%3c/svg%3e");padding-right:4.125rem;background-position:right .75rem center,center right 2.25rem;background-size:16px 12px,calc(0.75em + 0.375rem) calc(0.75em + 0.375rem)}.was-validated .form-select:invalid:focus,.form-select.is-invalid:focus{border-color:#ff0039;box-shadow:0 0 0 .25rem rgba(255,0,57,.25)}.was-validated .form-control-color:invalid,.form-control-color.is-invalid{width:calc(3rem + calc(1.5em + 0.75rem))}.was-validated .form-check-input:invalid,.form-check-input.is-invalid{border-color:#ff0039}.was-validated .form-check-input:invalid:checked,.form-check-input.is-invalid:checked{background-color:#ff0039}.was-validated .form-check-input:invalid:focus,.form-check-input.is-invalid:focus{box-shadow:0 0 0 .25rem rgba(255,0,57,.25)}.was-validated .form-check-input:invalid~.form-check-label,.form-check-input.is-invalid~.form-check-label{color:#ff0039}.form-check-inline .form-check-input~.invalid-feedback{margin-left:.5em}.was-validated .input-group>.form-control:not(:focus):invalid,.input-group>.form-control:not(:focus).is-invalid,.was-validated .input-group>.form-select:not(:focus):invalid,.input-group>.form-select:not(:focus).is-invalid,.was-validated .input-group>.form-floating:not(:focus-within):invalid,.input-group>.form-floating:not(:focus-within).is-invalid{z-index:4}.btn{--bs-btn-padding-x: 0.75rem;--bs-btn-padding-y: 0.375rem;--bs-btn-font-family: ;--bs-btn-font-size:1rem;--bs-btn-font-weight: 400;--bs-btn-line-height: 1.5;--bs-btn-color: #343a40;--bs-btn-bg: transparent;--bs-btn-border-width: 1px;--bs-btn-border-color: transparent;--bs-btn-border-radius: 0.25rem;--bs-btn-hover-border-color: transparent;--bs-btn-box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.15), 0 1px 1px rgba(0, 0, 0, 0.075);--bs-btn-disabled-opacity: 0.65;--bs-btn-focus-box-shadow: 0 0 0 0.25rem rgba(var(--bs-btn-focus-shadow-rgb), .5);display:inline-block;padding:var(--bs-btn-padding-y) var(--bs-btn-padding-x);font-family:var(--bs-btn-font-family);font-size:var(--bs-btn-font-size);font-weight:var(--bs-btn-font-weight);line-height:var(--bs-btn-line-height);color:var(--bs-btn-color);text-align:center;text-decoration:none;-webkit-text-decoration:none;-moz-text-decoration:none;-ms-text-decoration:none;-o-text-decoration:none;vertical-align:middle;cursor:pointer;user-select:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;-o-user-select:none;border:var(--bs-btn-border-width) solid var(--bs-btn-border-color);background-color:var(--bs-btn-bg);transition:color .15s ease-in-out,background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media(prefers-reduced-motion: reduce){.btn{transition:none}}.btn:hover{color:var(--bs-btn-hover-color);background-color:var(--bs-btn-hover-bg);border-color:var(--bs-btn-hover-border-color)}.btn-check+.btn:hover{color:var(--bs-btn-color);background-color:var(--bs-btn-bg);border-color:var(--bs-btn-border-color)}.btn:focus-visible{color:var(--bs-btn-hover-color);background-color:var(--bs-btn-hover-bg);border-color:var(--bs-btn-hover-border-color);outline:0;box-shadow:var(--bs-btn-focus-box-shadow)}.btn-check:focus-visible+.btn{border-color:var(--bs-btn-hover-border-color);outline:0;box-shadow:var(--bs-btn-focus-box-shadow)}.btn-check:checked+.btn,:not(.btn-check)+.btn:active,.btn:first-child:active,.btn.active,.btn.show{color:var(--bs-btn-active-color);background-color:var(--bs-btn-active-bg);border-color:var(--bs-btn-active-border-color)}.btn-check:checked+.btn:focus-visible,:not(.btn-check)+.btn:active:focus-visible,.btn:first-child:active:focus-visible,.btn.active:focus-visible,.btn.show:focus-visible{box-shadow:var(--bs-btn-focus-box-shadow)}.btn:disabled,.btn.disabled,fieldset:disabled .btn{color:var(--bs-btn-disabled-color);pointer-events:none;background-color:var(--bs-btn-disabled-bg);border-color:var(--bs-btn-disabled-border-color);opacity:var(--bs-btn-disabled-opacity)}.btn-default{--bs-btn-color: #fff;--bs-btn-bg: #343a40;--bs-btn-border-color: #343a40;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #2c3136;--bs-btn-hover-border-color: #2a2e33;--bs-btn-focus-shadow-rgb: 82, 88, 93;--bs-btn-active-color: #fff;--bs-btn-active-bg: #2a2e33;--bs-btn-active-border-color: #272c30;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #343a40;--bs-btn-disabled-border-color: #343a40}.btn-primary{--bs-btn-color: #fff;--bs-btn-bg: #2780e3;--bs-btn-border-color: #2780e3;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #216dc1;--bs-btn-hover-border-color: #1f66b6;--bs-btn-focus-shadow-rgb: 71, 147, 231;--bs-btn-active-color: #fff;--bs-btn-active-bg: #1f66b6;--bs-btn-active-border-color: #1d60aa;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #2780e3;--bs-btn-disabled-border-color: #2780e3}.btn-secondary{--bs-btn-color: #fff;--bs-btn-bg: #343a40;--bs-btn-border-color: #343a40;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #2c3136;--bs-btn-hover-border-color: #2a2e33;--bs-btn-focus-shadow-rgb: 82, 88, 93;--bs-btn-active-color: #fff;--bs-btn-active-bg: #2a2e33;--bs-btn-active-border-color: #272c30;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #343a40;--bs-btn-disabled-border-color: #343a40}.btn-success{--bs-btn-color: #fff;--bs-btn-bg: #3fb618;--bs-btn-border-color: #3fb618;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #369b14;--bs-btn-hover-border-color: #329213;--bs-btn-focus-shadow-rgb: 92, 193, 59;--bs-btn-active-color: #fff;--bs-btn-active-bg: #329213;--bs-btn-active-border-color: #2f8912;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #3fb618;--bs-btn-disabled-border-color: #3fb618}.btn-info{--bs-btn-color: #fff;--bs-btn-bg: #9954bb;--bs-btn-border-color: #9954bb;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #82479f;--bs-btn-hover-border-color: #7a4396;--bs-btn-focus-shadow-rgb: 168, 110, 197;--bs-btn-active-color: #fff;--bs-btn-active-bg: #7a4396;--bs-btn-active-border-color: #733f8c;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #9954bb;--bs-btn-disabled-border-color: #9954bb}.btn-warning{--bs-btn-color: #fff;--bs-btn-bg: #ff7518;--bs-btn-border-color: #ff7518;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #d96314;--bs-btn-hover-border-color: #cc5e13;--bs-btn-focus-shadow-rgb: 255, 138, 59;--bs-btn-active-color: #fff;--bs-btn-active-bg: #cc5e13;--bs-btn-active-border-color: #bf5812;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #ff7518;--bs-btn-disabled-border-color: #ff7518}.btn-danger{--bs-btn-color: #fff;--bs-btn-bg: #ff0039;--bs-btn-border-color: #ff0039;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #d90030;--bs-btn-hover-border-color: #cc002e;--bs-btn-focus-shadow-rgb: 255, 38, 87;--bs-btn-active-color: #fff;--bs-btn-active-bg: #cc002e;--bs-btn-active-border-color: #bf002b;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #ff0039;--bs-btn-disabled-border-color: #ff0039}.btn-light{--bs-btn-color: #000;--bs-btn-bg: #f8f9fa;--bs-btn-border-color: #f8f9fa;--bs-btn-hover-color: #000;--bs-btn-hover-bg: #d3d4d5;--bs-btn-hover-border-color: #c6c7c8;--bs-btn-focus-shadow-rgb: 211, 212, 213;--bs-btn-active-color: #000;--bs-btn-active-bg: #c6c7c8;--bs-btn-active-border-color: #babbbc;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #000;--bs-btn-disabled-bg: #f8f9fa;--bs-btn-disabled-border-color: #f8f9fa}.btn-dark{--bs-btn-color: #fff;--bs-btn-bg: #343a40;--bs-btn-border-color: #343a40;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #52585d;--bs-btn-hover-border-color: #484e53;--bs-btn-focus-shadow-rgb: 82, 88, 93;--bs-btn-active-color: #fff;--bs-btn-active-bg: #5d6166;--bs-btn-active-border-color: #484e53;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #343a40;--bs-btn-disabled-border-color: #343a40}.btn-outline-default{--bs-btn-color: #343a40;--bs-btn-border-color: #343a40;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #343a40;--bs-btn-hover-border-color: #343a40;--bs-btn-focus-shadow-rgb: 52, 58, 64;--bs-btn-active-color: #fff;--bs-btn-active-bg: #343a40;--bs-btn-active-border-color: #343a40;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #343a40;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #343a40;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-primary{--bs-btn-color: #2780e3;--bs-btn-border-color: #2780e3;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #2780e3;--bs-btn-hover-border-color: #2780e3;--bs-btn-focus-shadow-rgb: 39, 128, 227;--bs-btn-active-color: #fff;--bs-btn-active-bg: #2780e3;--bs-btn-active-border-color: #2780e3;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #2780e3;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #2780e3;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-secondary{--bs-btn-color: #343a40;--bs-btn-border-color: #343a40;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #343a40;--bs-btn-hover-border-color: #343a40;--bs-btn-focus-shadow-rgb: 52, 58, 64;--bs-btn-active-color: #fff;--bs-btn-active-bg: #343a40;--bs-btn-active-border-color: #343a40;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #343a40;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #343a40;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-success{--bs-btn-color: #3fb618;--bs-btn-border-color: #3fb618;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #3fb618;--bs-btn-hover-border-color: #3fb618;--bs-btn-focus-shadow-rgb: 63, 182, 24;--bs-btn-active-color: #fff;--bs-btn-active-bg: #3fb618;--bs-btn-active-border-color: #3fb618;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #3fb618;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #3fb618;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-info{--bs-btn-color: #9954bb;--bs-btn-border-color: #9954bb;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #9954bb;--bs-btn-hover-border-color: #9954bb;--bs-btn-focus-shadow-rgb: 153, 84, 187;--bs-btn-active-color: #fff;--bs-btn-active-bg: #9954bb;--bs-btn-active-border-color: #9954bb;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #9954bb;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #9954bb;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-warning{--bs-btn-color: #ff7518;--bs-btn-border-color: #ff7518;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #ff7518;--bs-btn-hover-border-color: #ff7518;--bs-btn-focus-shadow-rgb: 255, 117, 24;--bs-btn-active-color: #fff;--bs-btn-active-bg: #ff7518;--bs-btn-active-border-color: #ff7518;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #ff7518;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #ff7518;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-danger{--bs-btn-color: #ff0039;--bs-btn-border-color: #ff0039;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #ff0039;--bs-btn-hover-border-color: #ff0039;--bs-btn-focus-shadow-rgb: 255, 0, 57;--bs-btn-active-color: #fff;--bs-btn-active-bg: #ff0039;--bs-btn-active-border-color: #ff0039;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #ff0039;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #ff0039;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-light{--bs-btn-color: #f8f9fa;--bs-btn-border-color: #f8f9fa;--bs-btn-hover-color: #000;--bs-btn-hover-bg: #f8f9fa;--bs-btn-hover-border-color: #f8f9fa;--bs-btn-focus-shadow-rgb: 248, 249, 250;--bs-btn-active-color: #000;--bs-btn-active-bg: #f8f9fa;--bs-btn-active-border-color: #f8f9fa;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #f8f9fa;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #f8f9fa;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-dark{--bs-btn-color: #343a40;--bs-btn-border-color: #343a40;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #343a40;--bs-btn-hover-border-color: #343a40;--bs-btn-focus-shadow-rgb: 52, 58, 64;--bs-btn-active-color: #fff;--bs-btn-active-bg: #343a40;--bs-btn-active-border-color: #343a40;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #343a40;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #343a40;--bs-btn-bg: transparent;--bs-gradient: none}.btn-link{--bs-btn-font-weight: 400;--bs-btn-color: #2761e3;--bs-btn-bg: transparent;--bs-btn-border-color: transparent;--bs-btn-hover-color: #1f4eb6;--bs-btn-hover-border-color: transparent;--bs-btn-active-color: #1f4eb6;--bs-btn-active-border-color: transparent;--bs-btn-disabled-color: #6c757d;--bs-btn-disabled-border-color: transparent;--bs-btn-box-shadow: 0 0 0 #000;--bs-btn-focus-shadow-rgb: 71, 121, 231;text-decoration:underline;-webkit-text-decoration:underline;-moz-text-decoration:underline;-ms-text-decoration:underline;-o-text-decoration:underline}.btn-link:focus-visible{color:var(--bs-btn-color)}.btn-link:hover{color:var(--bs-btn-hover-color)}.btn-lg,.btn-group-lg>.btn{--bs-btn-padding-y: 0.5rem;--bs-btn-padding-x: 1rem;--bs-btn-font-size:1.25rem;--bs-btn-border-radius: 0.5rem}.btn-sm,.btn-group-sm>.btn{--bs-btn-padding-y: 0.25rem;--bs-btn-padding-x: 0.5rem;--bs-btn-font-size:0.875rem;--bs-btn-border-radius: 0.2em}.fade{transition:opacity .15s linear}@media(prefers-reduced-motion: reduce){.fade{transition:none}}.fade:not(.show){opacity:0}.collapse:not(.show){display:none}.collapsing{height:0;overflow:hidden;transition:height .2s ease}@media(prefers-reduced-motion: reduce){.collapsing{transition:none}}.collapsing.collapse-horizontal{width:0;height:auto;transition:width .35s ease}@media(prefers-reduced-motion: reduce){.collapsing.collapse-horizontal{transition:none}}.dropup,.dropend,.dropdown,.dropstart,.dropup-center,.dropdown-center{position:relative}.dropdown-toggle{white-space:nowrap}.dropdown-toggle::after{display:inline-block;margin-left:.255em;vertical-align:.255em;content:"";border-top:.3em solid;border-right:.3em solid rgba(0,0,0,0);border-bottom:0;border-left:.3em solid rgba(0,0,0,0)}.dropdown-toggle:empty::after{margin-left:0}.dropdown-menu{--bs-dropdown-zindex: 1000;--bs-dropdown-min-width: 10rem;--bs-dropdown-padding-x: 0;--bs-dropdown-padding-y: 0.5rem;--bs-dropdown-spacer: 0.125rem;--bs-dropdown-font-size:1rem;--bs-dropdown-color: #343a40;--bs-dropdown-bg: #fff;--bs-dropdown-border-color: rgba(0, 0, 0, 0.175);--bs-dropdown-border-radius: 0.25rem;--bs-dropdown-border-width: 1px;--bs-dropdown-inner-border-radius: calc(0.25rem - 1px);--bs-dropdown-divider-bg: rgba(0, 0, 0, 0.175);--bs-dropdown-divider-margin-y: 0.5rem;--bs-dropdown-box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);--bs-dropdown-link-color: #343a40;--bs-dropdown-link-hover-color: #343a40;--bs-dropdown-link-hover-bg: #f8f9fa;--bs-dropdown-link-active-color: #fff;--bs-dropdown-link-active-bg: #2780e3;--bs-dropdown-link-disabled-color: rgba(52, 58, 64, 0.5);--bs-dropdown-item-padding-x: 1rem;--bs-dropdown-item-padding-y: 0.25rem;--bs-dropdown-header-color: #6c757d;--bs-dropdown-header-padding-x: 1rem;--bs-dropdown-header-padding-y: 0.5rem;position:absolute;z-index:var(--bs-dropdown-zindex);display:none;min-width:var(--bs-dropdown-min-width);padding:var(--bs-dropdown-padding-y) var(--bs-dropdown-padding-x);margin:0;font-size:var(--bs-dropdown-font-size);color:var(--bs-dropdown-color);text-align:left;list-style:none;background-color:var(--bs-dropdown-bg);background-clip:padding-box;border:var(--bs-dropdown-border-width) solid var(--bs-dropdown-border-color)}.dropdown-menu[data-bs-popper]{top:100%;left:0;margin-top:var(--bs-dropdown-spacer)}.dropdown-menu-start{--bs-position: start}.dropdown-menu-start[data-bs-popper]{right:auto;left:0}.dropdown-menu-end{--bs-position: end}.dropdown-menu-end[data-bs-popper]{right:0;left:auto}@media(min-width: 576px){.dropdown-menu-sm-start{--bs-position: start}.dropdown-menu-sm-start[data-bs-popper]{right:auto;left:0}.dropdown-menu-sm-end{--bs-position: end}.dropdown-menu-sm-end[data-bs-popper]{right:0;left:auto}}@media(min-width: 768px){.dropdown-menu-md-start{--bs-position: start}.dropdown-menu-md-start[data-bs-popper]{right:auto;left:0}.dropdown-menu-md-end{--bs-position: end}.dropdown-menu-md-end[data-bs-popper]{right:0;left:auto}}@media(min-width: 992px){.dropdown-menu-lg-start{--bs-position: start}.dropdown-menu-lg-start[data-bs-popper]{right:auto;left:0}.dropdown-menu-lg-end{--bs-position: end}.dropdown-menu-lg-end[data-bs-popper]{right:0;left:auto}}@media(min-width: 1200px){.dropdown-menu-xl-start{--bs-position: start}.dropdown-menu-xl-start[data-bs-popper]{right:auto;left:0}.dropdown-menu-xl-end{--bs-position: end}.dropdown-menu-xl-end[data-bs-popper]{right:0;left:auto}}@media(min-width: 1400px){.dropdown-menu-xxl-start{--bs-position: start}.dropdown-menu-xxl-start[data-bs-popper]{right:auto;left:0}.dropdown-menu-xxl-end{--bs-position: end}.dropdown-menu-xxl-end[data-bs-popper]{right:0;left:auto}}.dropup .dropdown-menu[data-bs-popper]{top:auto;bottom:100%;margin-top:0;margin-bottom:var(--bs-dropdown-spacer)}.dropup .dropdown-toggle::after{display:inline-block;margin-left:.255em;vertical-align:.255em;content:"";border-top:0;border-right:.3em solid rgba(0,0,0,0);border-bottom:.3em solid;border-left:.3em solid rgba(0,0,0,0)}.dropup .dropdown-toggle:empty::after{margin-left:0}.dropend .dropdown-menu[data-bs-popper]{top:0;right:auto;left:100%;margin-top:0;margin-left:var(--bs-dropdown-spacer)}.dropend .dropdown-toggle::after{display:inline-block;margin-left:.255em;vertical-align:.255em;content:"";border-top:.3em solid rgba(0,0,0,0);border-right:0;border-bottom:.3em solid rgba(0,0,0,0);border-left:.3em solid}.dropend .dropdown-toggle:empty::after{margin-left:0}.dropend .dropdown-toggle::after{vertical-align:0}.dropstart .dropdown-menu[data-bs-popper]{top:0;right:100%;left:auto;margin-top:0;margin-right:var(--bs-dropdown-spacer)}.dropstart .dropdown-toggle::after{display:inline-block;margin-left:.255em;vertical-align:.255em;content:""}.dropstart .dropdown-toggle::after{display:none}.dropstart .dropdown-toggle::before{display:inline-block;margin-right:.255em;vertical-align:.255em;content:"";border-top:.3em solid rgba(0,0,0,0);border-right:.3em solid;border-bottom:.3em solid rgba(0,0,0,0)}.dropstart .dropdown-toggle:empty::after{margin-left:0}.dropstart .dropdown-toggle::before{vertical-align:0}.dropdown-divider{height:0;margin:var(--bs-dropdown-divider-margin-y) 0;overflow:hidden;border-top:1px solid var(--bs-dropdown-divider-bg);opacity:1}.dropdown-item{display:block;width:100%;padding:var(--bs-dropdown-item-padding-y) var(--bs-dropdown-item-padding-x);clear:both;font-weight:400;color:var(--bs-dropdown-link-color);text-align:inherit;text-decoration:none;-webkit-text-decoration:none;-moz-text-decoration:none;-ms-text-decoration:none;-o-text-decoration:none;white-space:nowrap;background-color:rgba(0,0,0,0);border:0}.dropdown-item:hover,.dropdown-item:focus{color:var(--bs-dropdown-link-hover-color);background-color:var(--bs-dropdown-link-hover-bg)}.dropdown-item.active,.dropdown-item:active{color:var(--bs-dropdown-link-active-color);text-decoration:none;background-color:var(--bs-dropdown-link-active-bg)}.dropdown-item.disabled,.dropdown-item:disabled{color:var(--bs-dropdown-link-disabled-color);pointer-events:none;background-color:rgba(0,0,0,0)}.dropdown-menu.show{display:block}.dropdown-header{display:block;padding:var(--bs-dropdown-header-padding-y) var(--bs-dropdown-header-padding-x);margin-bottom:0;font-size:0.875rem;color:var(--bs-dropdown-header-color);white-space:nowrap}.dropdown-item-text{display:block;padding:var(--bs-dropdown-item-padding-y) var(--bs-dropdown-item-padding-x);color:var(--bs-dropdown-link-color)}.dropdown-menu-dark{--bs-dropdown-color: #dee2e6;--bs-dropdown-bg: #343a40;--bs-dropdown-border-color: rgba(0, 0, 0, 0.175);--bs-dropdown-box-shadow: ;--bs-dropdown-link-color: #dee2e6;--bs-dropdown-link-hover-color: #fff;--bs-dropdown-divider-bg: rgba(0, 0, 0, 0.175);--bs-dropdown-link-hover-bg: rgba(255, 255, 255, 0.15);--bs-dropdown-link-active-color: #fff;--bs-dropdown-link-active-bg: #2780e3;--bs-dropdown-link-disabled-color: #adb5bd;--bs-dropdown-header-color: #adb5bd}.btn-group,.btn-group-vertical{position:relative;display:inline-flex;vertical-align:middle}.btn-group>.btn,.btn-group-vertical>.btn{position:relative;flex:1 1 auto;-webkit-flex:1 1 auto}.btn-group>.btn-check:checked+.btn,.btn-group>.btn-check:focus+.btn,.btn-group>.btn:hover,.btn-group>.btn:focus,.btn-group>.btn:active,.btn-group>.btn.active,.btn-group-vertical>.btn-check:checked+.btn,.btn-group-vertical>.btn-check:focus+.btn,.btn-group-vertical>.btn:hover,.btn-group-vertical>.btn:focus,.btn-group-vertical>.btn:active,.btn-group-vertical>.btn.active{z-index:1}.btn-toolbar{display:flex;display:-webkit-flex;flex-wrap:wrap;-webkit-flex-wrap:wrap;justify-content:flex-start;-webkit-justify-content:flex-start}.btn-toolbar .input-group{width:auto}.btn-group>:not(.btn-check:first-child)+.btn,.btn-group>.btn-group:not(:first-child){margin-left:calc(1px*-1)}.dropdown-toggle-split{padding-right:.5625rem;padding-left:.5625rem}.dropdown-toggle-split::after,.dropup .dropdown-toggle-split::after,.dropend .dropdown-toggle-split::after{margin-left:0}.dropstart .dropdown-toggle-split::before{margin-right:0}.btn-sm+.dropdown-toggle-split,.btn-group-sm>.btn+.dropdown-toggle-split{padding-right:.375rem;padding-left:.375rem}.btn-lg+.dropdown-toggle-split,.btn-group-lg>.btn+.dropdown-toggle-split{padding-right:.75rem;padding-left:.75rem}.btn-group-vertical{flex-direction:column;-webkit-flex-direction:column;align-items:flex-start;-webkit-align-items:flex-start;justify-content:center;-webkit-justify-content:center}.btn-group-vertical>.btn,.btn-group-vertical>.btn-group{width:100%}.btn-group-vertical>.btn:not(:first-child),.btn-group-vertical>.btn-group:not(:first-child){margin-top:calc(1px*-1)}.nav{--bs-nav-link-padding-x: 1rem;--bs-nav-link-padding-y: 0.5rem;--bs-nav-link-font-weight: ;--bs-nav-link-color: #2761e3;--bs-nav-link-hover-color: #1f4eb6;--bs-nav-link-disabled-color: rgba(52, 58, 64, 0.75);display:flex;display:-webkit-flex;flex-wrap:wrap;-webkit-flex-wrap:wrap;padding-left:0;margin-bottom:0;list-style:none}.nav-link{display:block;padding:var(--bs-nav-link-padding-y) var(--bs-nav-link-padding-x);font-size:var(--bs-nav-link-font-size);font-weight:var(--bs-nav-link-font-weight);color:var(--bs-nav-link-color);text-decoration:none;-webkit-text-decoration:none;-moz-text-decoration:none;-ms-text-decoration:none;-o-text-decoration:none;background:none;border:0;transition:color .15s ease-in-out,background-color .15s ease-in-out,border-color .15s ease-in-out}@media(prefers-reduced-motion: reduce){.nav-link{transition:none}}.nav-link:hover,.nav-link:focus{color:var(--bs-nav-link-hover-color)}.nav-link:focus-visible{outline:0;box-shadow:0 0 0 .25rem rgba(39,128,227,.25)}.nav-link.disabled,.nav-link:disabled{color:var(--bs-nav-link-disabled-color);pointer-events:none;cursor:default}.nav-tabs{--bs-nav-tabs-border-width: 1px;--bs-nav-tabs-border-color: #dee2e6;--bs-nav-tabs-border-radius: 0.25rem;--bs-nav-tabs-link-hover-border-color: #e9ecef #e9ecef #dee2e6;--bs-nav-tabs-link-active-color: #000;--bs-nav-tabs-link-active-bg: #fff;--bs-nav-tabs-link-active-border-color: #dee2e6 #dee2e6 #fff;border-bottom:var(--bs-nav-tabs-border-width) solid var(--bs-nav-tabs-border-color)}.nav-tabs .nav-link{margin-bottom:calc(-1*var(--bs-nav-tabs-border-width));border:var(--bs-nav-tabs-border-width) solid rgba(0,0,0,0)}.nav-tabs .nav-link:hover,.nav-tabs .nav-link:focus{isolation:isolate;border-color:var(--bs-nav-tabs-link-hover-border-color)}.nav-tabs .nav-link.active,.nav-tabs .nav-item.show .nav-link{color:var(--bs-nav-tabs-link-active-color);background-color:var(--bs-nav-tabs-link-active-bg);border-color:var(--bs-nav-tabs-link-active-border-color)}.nav-tabs .dropdown-menu{margin-top:calc(-1*var(--bs-nav-tabs-border-width))}.nav-pills{--bs-nav-pills-border-radius: 0.25rem;--bs-nav-pills-link-active-color: #fff;--bs-nav-pills-link-active-bg: #2780e3}.nav-pills .nav-link.active,.nav-pills .show>.nav-link{color:var(--bs-nav-pills-link-active-color);background-color:var(--bs-nav-pills-link-active-bg)}.nav-underline{--bs-nav-underline-gap: 1rem;--bs-nav-underline-border-width: 0.125rem;--bs-nav-underline-link-active-color: #000;gap:var(--bs-nav-underline-gap)}.nav-underline .nav-link{padding-right:0;padding-left:0;border-bottom:var(--bs-nav-underline-border-width) solid rgba(0,0,0,0)}.nav-underline .nav-link:hover,.nav-underline .nav-link:focus{border-bottom-color:currentcolor}.nav-underline .nav-link.active,.nav-underline .show>.nav-link{font-weight:700;color:var(--bs-nav-underline-link-active-color);border-bottom-color:currentcolor}.nav-fill>.nav-link,.nav-fill .nav-item{flex:1 1 auto;-webkit-flex:1 1 auto;text-align:center}.nav-justified>.nav-link,.nav-justified .nav-item{flex-basis:0;-webkit-flex-basis:0;flex-grow:1;-webkit-flex-grow:1;text-align:center}.nav-fill .nav-item .nav-link,.nav-justified .nav-item .nav-link{width:100%}.tab-content>.tab-pane{display:none}.tab-content>.active{display:block}.navbar{--bs-navbar-padding-x: 0;--bs-navbar-padding-y: 0.5rem;--bs-navbar-color: #545555;--bs-navbar-hover-color: rgba(31, 78, 182, 0.8);--bs-navbar-disabled-color: rgba(84, 85, 85, 0.75);--bs-navbar-active-color: #1f4eb6;--bs-navbar-brand-padding-y: 0.3125rem;--bs-navbar-brand-margin-end: 1rem;--bs-navbar-brand-font-size: 1.25rem;--bs-navbar-brand-color: #545555;--bs-navbar-brand-hover-color: #1f4eb6;--bs-navbar-nav-link-padding-x: 0.5rem;--bs-navbar-toggler-padding-y: 0.25;--bs-navbar-toggler-padding-x: 0;--bs-navbar-toggler-font-size: 1.25rem;--bs-navbar-toggler-icon-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 30 30'%3e%3cpath stroke='%23545555' stroke-linecap='round' stroke-miterlimit='10' stroke-width='2' d='M4 7h22M4 15h22M4 23h22'/%3e%3c/svg%3e");--bs-navbar-toggler-border-color: rgba(84, 85, 85, 0);--bs-navbar-toggler-border-radius: 0.25rem;--bs-navbar-toggler-focus-width: 0.25rem;--bs-navbar-toggler-transition: box-shadow 0.15s ease-in-out;position:relative;display:flex;display:-webkit-flex;flex-wrap:wrap;-webkit-flex-wrap:wrap;align-items:center;-webkit-align-items:center;justify-content:space-between;-webkit-justify-content:space-between;padding:var(--bs-navbar-padding-y) var(--bs-navbar-padding-x)}.navbar>.container,.navbar>.container-fluid,.navbar>.container-sm,.navbar>.container-md,.navbar>.container-lg,.navbar>.container-xl,.navbar>.container-xxl{display:flex;display:-webkit-flex;flex-wrap:inherit;-webkit-flex-wrap:inherit;align-items:center;-webkit-align-items:center;justify-content:space-between;-webkit-justify-content:space-between}.navbar-brand{padding-top:var(--bs-navbar-brand-padding-y);padding-bottom:var(--bs-navbar-brand-padding-y);margin-right:var(--bs-navbar-brand-margin-end);font-size:var(--bs-navbar-brand-font-size);color:var(--bs-navbar-brand-color);text-decoration:none;-webkit-text-decoration:none;-moz-text-decoration:none;-ms-text-decoration:none;-o-text-decoration:none;white-space:nowrap}.navbar-brand:hover,.navbar-brand:focus{color:var(--bs-navbar-brand-hover-color)}.navbar-nav{--bs-nav-link-padding-x: 0;--bs-nav-link-padding-y: 0.5rem;--bs-nav-link-font-weight: ;--bs-nav-link-color: var(--bs-navbar-color);--bs-nav-link-hover-color: var(--bs-navbar-hover-color);--bs-nav-link-disabled-color: var(--bs-navbar-disabled-color);display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;padding-left:0;margin-bottom:0;list-style:none}.navbar-nav .nav-link.active,.navbar-nav .nav-link.show{color:var(--bs-navbar-active-color)}.navbar-nav .dropdown-menu{position:static}.navbar-text{padding-top:.5rem;padding-bottom:.5rem;color:var(--bs-navbar-color)}.navbar-text a,.navbar-text a:hover,.navbar-text a:focus{color:var(--bs-navbar-active-color)}.navbar-collapse{flex-basis:100%;-webkit-flex-basis:100%;flex-grow:1;-webkit-flex-grow:1;align-items:center;-webkit-align-items:center}.navbar-toggler{padding:var(--bs-navbar-toggler-padding-y) var(--bs-navbar-toggler-padding-x);font-size:var(--bs-navbar-toggler-font-size);line-height:1;color:var(--bs-navbar-color);background-color:rgba(0,0,0,0);border:var(--bs-border-width) solid var(--bs-navbar-toggler-border-color);transition:var(--bs-navbar-toggler-transition)}@media(prefers-reduced-motion: reduce){.navbar-toggler{transition:none}}.navbar-toggler:hover{text-decoration:none}.navbar-toggler:focus{text-decoration:none;outline:0;box-shadow:0 0 0 var(--bs-navbar-toggler-focus-width)}.navbar-toggler-icon{display:inline-block;width:1.5em;height:1.5em;vertical-align:middle;background-image:var(--bs-navbar-toggler-icon-bg);background-repeat:no-repeat;background-position:center;background-size:100%}.navbar-nav-scroll{max-height:var(--bs-scroll-height, 75vh);overflow-y:auto}@media(min-width: 576px){.navbar-expand-sm{flex-wrap:nowrap;-webkit-flex-wrap:nowrap;justify-content:flex-start;-webkit-justify-content:flex-start}.navbar-expand-sm .navbar-nav{flex-direction:row;-webkit-flex-direction:row}.navbar-expand-sm .navbar-nav .dropdown-menu{position:absolute}.navbar-expand-sm .navbar-nav .nav-link{padding-right:var(--bs-navbar-nav-link-padding-x);padding-left:var(--bs-navbar-nav-link-padding-x)}.navbar-expand-sm .navbar-nav-scroll{overflow:visible}.navbar-expand-sm .navbar-collapse{display:flex !important;display:-webkit-flex !important;flex-basis:auto;-webkit-flex-basis:auto}.navbar-expand-sm .navbar-toggler{display:none}.navbar-expand-sm .offcanvas{position:static;z-index:auto;flex-grow:1;-webkit-flex-grow:1;width:auto !important;height:auto !important;visibility:visible !important;background-color:rgba(0,0,0,0) !important;border:0 !important;transform:none !important;transition:none}.navbar-expand-sm .offcanvas .offcanvas-header{display:none}.navbar-expand-sm .offcanvas .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible}}@media(min-width: 768px){.navbar-expand-md{flex-wrap:nowrap;-webkit-flex-wrap:nowrap;justify-content:flex-start;-webkit-justify-content:flex-start}.navbar-expand-md .navbar-nav{flex-direction:row;-webkit-flex-direction:row}.navbar-expand-md .navbar-nav .dropdown-menu{position:absolute}.navbar-expand-md .navbar-nav .nav-link{padding-right:var(--bs-navbar-nav-link-padding-x);padding-left:var(--bs-navbar-nav-link-padding-x)}.navbar-expand-md .navbar-nav-scroll{overflow:visible}.navbar-expand-md .navbar-collapse{display:flex !important;display:-webkit-flex !important;flex-basis:auto;-webkit-flex-basis:auto}.navbar-expand-md .navbar-toggler{display:none}.navbar-expand-md .offcanvas{position:static;z-index:auto;flex-grow:1;-webkit-flex-grow:1;width:auto !important;height:auto !important;visibility:visible !important;background-color:rgba(0,0,0,0) !important;border:0 !important;transform:none !important;transition:none}.navbar-expand-md .offcanvas .offcanvas-header{display:none}.navbar-expand-md .offcanvas .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible}}@media(min-width: 992px){.navbar-expand-lg{flex-wrap:nowrap;-webkit-flex-wrap:nowrap;justify-content:flex-start;-webkit-justify-content:flex-start}.navbar-expand-lg .navbar-nav{flex-direction:row;-webkit-flex-direction:row}.navbar-expand-lg .navbar-nav .dropdown-menu{position:absolute}.navbar-expand-lg .navbar-nav .nav-link{padding-right:var(--bs-navbar-nav-link-padding-x);padding-left:var(--bs-navbar-nav-link-padding-x)}.navbar-expand-lg .navbar-nav-scroll{overflow:visible}.navbar-expand-lg .navbar-collapse{display:flex !important;display:-webkit-flex !important;flex-basis:auto;-webkit-flex-basis:auto}.navbar-expand-lg .navbar-toggler{display:none}.navbar-expand-lg .offcanvas{position:static;z-index:auto;flex-grow:1;-webkit-flex-grow:1;width:auto !important;height:auto !important;visibility:visible !important;background-color:rgba(0,0,0,0) !important;border:0 !important;transform:none !important;transition:none}.navbar-expand-lg .offcanvas .offcanvas-header{display:none}.navbar-expand-lg .offcanvas .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible}}@media(min-width: 1200px){.navbar-expand-xl{flex-wrap:nowrap;-webkit-flex-wrap:nowrap;justify-content:flex-start;-webkit-justify-content:flex-start}.navbar-expand-xl .navbar-nav{flex-direction:row;-webkit-flex-direction:row}.navbar-expand-xl .navbar-nav .dropdown-menu{position:absolute}.navbar-expand-xl .navbar-nav .nav-link{padding-right:var(--bs-navbar-nav-link-padding-x);padding-left:var(--bs-navbar-nav-link-padding-x)}.navbar-expand-xl .navbar-nav-scroll{overflow:visible}.navbar-expand-xl .navbar-collapse{display:flex !important;display:-webkit-flex !important;flex-basis:auto;-webkit-flex-basis:auto}.navbar-expand-xl .navbar-toggler{display:none}.navbar-expand-xl .offcanvas{position:static;z-index:auto;flex-grow:1;-webkit-flex-grow:1;width:auto !important;height:auto !important;visibility:visible !important;background-color:rgba(0,0,0,0) !important;border:0 !important;transform:none !important;transition:none}.navbar-expand-xl .offcanvas .offcanvas-header{display:none}.navbar-expand-xl .offcanvas .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible}}@media(min-width: 1400px){.navbar-expand-xxl{flex-wrap:nowrap;-webkit-flex-wrap:nowrap;justify-content:flex-start;-webkit-justify-content:flex-start}.navbar-expand-xxl .navbar-nav{flex-direction:row;-webkit-flex-direction:row}.navbar-expand-xxl .navbar-nav .dropdown-menu{position:absolute}.navbar-expand-xxl .navbar-nav .nav-link{padding-right:var(--bs-navbar-nav-link-padding-x);padding-left:var(--bs-navbar-nav-link-padding-x)}.navbar-expand-xxl .navbar-nav-scroll{overflow:visible}.navbar-expand-xxl .navbar-collapse{display:flex !important;display:-webkit-flex !important;flex-basis:auto;-webkit-flex-basis:auto}.navbar-expand-xxl .navbar-toggler{display:none}.navbar-expand-xxl .offcanvas{position:static;z-index:auto;flex-grow:1;-webkit-flex-grow:1;width:auto !important;height:auto !important;visibility:visible !important;background-color:rgba(0,0,0,0) !important;border:0 !important;transform:none !important;transition:none}.navbar-expand-xxl .offcanvas .offcanvas-header{display:none}.navbar-expand-xxl .offcanvas .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible}}.navbar-expand{flex-wrap:nowrap;-webkit-flex-wrap:nowrap;justify-content:flex-start;-webkit-justify-content:flex-start}.navbar-expand .navbar-nav{flex-direction:row;-webkit-flex-direction:row}.navbar-expand .navbar-nav .dropdown-menu{position:absolute}.navbar-expand .navbar-nav .nav-link{padding-right:var(--bs-navbar-nav-link-padding-x);padding-left:var(--bs-navbar-nav-link-padding-x)}.navbar-expand .navbar-nav-scroll{overflow:visible}.navbar-expand .navbar-collapse{display:flex !important;display:-webkit-flex !important;flex-basis:auto;-webkit-flex-basis:auto}.navbar-expand .navbar-toggler{display:none}.navbar-expand .offcanvas{position:static;z-index:auto;flex-grow:1;-webkit-flex-grow:1;width:auto !important;height:auto !important;visibility:visible !important;background-color:rgba(0,0,0,0) !important;border:0 !important;transform:none !important;transition:none}.navbar-expand .offcanvas .offcanvas-header{display:none}.navbar-expand .offcanvas .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible}.navbar-dark,.navbar[data-bs-theme=dark]{--bs-navbar-color: #545555;--bs-navbar-hover-color: rgba(31, 78, 182, 0.8);--bs-navbar-disabled-color: rgba(84, 85, 85, 0.75);--bs-navbar-active-color: #1f4eb6;--bs-navbar-brand-color: #545555;--bs-navbar-brand-hover-color: #1f4eb6;--bs-navbar-toggler-border-color: rgba(84, 85, 85, 0);--bs-navbar-toggler-icon-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 30 30'%3e%3cpath stroke='%23545555' stroke-linecap='round' stroke-miterlimit='10' stroke-width='2' d='M4 7h22M4 15h22M4 23h22'/%3e%3c/svg%3e")}[data-bs-theme=dark] .navbar-toggler-icon{--bs-navbar-toggler-icon-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 30 30'%3e%3cpath stroke='%23545555' stroke-linecap='round' stroke-miterlimit='10' stroke-width='2' d='M4 7h22M4 15h22M4 23h22'/%3e%3c/svg%3e")}.card{--bs-card-spacer-y: 1rem;--bs-card-spacer-x: 1rem;--bs-card-title-spacer-y: 0.5rem;--bs-card-title-color: ;--bs-card-subtitle-color: ;--bs-card-border-width: 1px;--bs-card-border-color: rgba(0, 0, 0, 0.175);--bs-card-border-radius: 0.25rem;--bs-card-box-shadow: ;--bs-card-inner-border-radius: calc(0.25rem - 1px);--bs-card-cap-padding-y: 0.5rem;--bs-card-cap-padding-x: 1rem;--bs-card-cap-bg: rgba(52, 58, 64, 0.25);--bs-card-cap-color: ;--bs-card-height: ;--bs-card-color: ;--bs-card-bg: #fff;--bs-card-img-overlay-padding: 1rem;--bs-card-group-margin: 0.75rem;position:relative;display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;min-width:0;height:var(--bs-card-height);color:var(--bs-body-color);word-wrap:break-word;background-color:var(--bs-card-bg);background-clip:border-box;border:var(--bs-card-border-width) solid var(--bs-card-border-color)}.card>hr{margin-right:0;margin-left:0}.card>.list-group{border-top:inherit;border-bottom:inherit}.card>.list-group:first-child{border-top-width:0}.card>.list-group:last-child{border-bottom-width:0}.card>.card-header+.list-group,.card>.list-group+.card-footer{border-top:0}.card-body{flex:1 1 auto;-webkit-flex:1 1 auto;padding:var(--bs-card-spacer-y) var(--bs-card-spacer-x);color:var(--bs-card-color)}.card-title{margin-bottom:var(--bs-card-title-spacer-y);color:var(--bs-card-title-color)}.card-subtitle{margin-top:calc(-0.5*var(--bs-card-title-spacer-y));margin-bottom:0;color:var(--bs-card-subtitle-color)}.card-text:last-child{margin-bottom:0}.card-link+.card-link{margin-left:var(--bs-card-spacer-x)}.card-header{padding:var(--bs-card-cap-padding-y) var(--bs-card-cap-padding-x);margin-bottom:0;color:var(--bs-card-cap-color);background-color:var(--bs-card-cap-bg);border-bottom:var(--bs-card-border-width) solid var(--bs-card-border-color)}.card-footer{padding:var(--bs-card-cap-padding-y) var(--bs-card-cap-padding-x);color:var(--bs-card-cap-color);background-color:var(--bs-card-cap-bg);border-top:var(--bs-card-border-width) solid var(--bs-card-border-color)}.card-header-tabs{margin-right:calc(-0.5*var(--bs-card-cap-padding-x));margin-bottom:calc(-1*var(--bs-card-cap-padding-y));margin-left:calc(-0.5*var(--bs-card-cap-padding-x));border-bottom:0}.card-header-tabs .nav-link.active{background-color:var(--bs-card-bg);border-bottom-color:var(--bs-card-bg)}.card-header-pills{margin-right:calc(-0.5*var(--bs-card-cap-padding-x));margin-left:calc(-0.5*var(--bs-card-cap-padding-x))}.card-img-overlay{position:absolute;top:0;right:0;bottom:0;left:0;padding:var(--bs-card-img-overlay-padding)}.card-img,.card-img-top,.card-img-bottom{width:100%}.card-group>.card{margin-bottom:var(--bs-card-group-margin)}@media(min-width: 576px){.card-group{display:flex;display:-webkit-flex;flex-flow:row wrap;-webkit-flex-flow:row wrap}.card-group>.card{flex:1 0 0%;-webkit-flex:1 0 0%;margin-bottom:0}.card-group>.card+.card{margin-left:0;border-left:0}}.accordion{--bs-accordion-color: #343a40;--bs-accordion-bg: #fff;--bs-accordion-transition: color 0.15s ease-in-out, background-color 0.15s ease-in-out, border-color 0.15s ease-in-out, box-shadow 0.15s ease-in-out, border-radius 0.15s ease;--bs-accordion-border-color: #dee2e6;--bs-accordion-border-width: 1px;--bs-accordion-border-radius: 0.25rem;--bs-accordion-inner-border-radius: calc(0.25rem - 1px);--bs-accordion-btn-padding-x: 1.25rem;--bs-accordion-btn-padding-y: 1rem;--bs-accordion-btn-color: #343a40;--bs-accordion-btn-bg: #fff;--bs-accordion-btn-icon: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='%23343a40'%3e%3cpath fill-rule='evenodd' d='M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z'/%3e%3c/svg%3e");--bs-accordion-btn-icon-width: 1.25rem;--bs-accordion-btn-icon-transform: rotate(-180deg);--bs-accordion-btn-icon-transition: transform 0.2s ease-in-out;--bs-accordion-btn-active-icon: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='%2310335b'%3e%3cpath fill-rule='evenodd' d='M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z'/%3e%3c/svg%3e");--bs-accordion-btn-focus-border-color: #93c0f1;--bs-accordion-btn-focus-box-shadow: 0 0 0 0.25rem rgba(39, 128, 227, 0.25);--bs-accordion-body-padding-x: 1.25rem;--bs-accordion-body-padding-y: 1rem;--bs-accordion-active-color: #10335b;--bs-accordion-active-bg: #d4e6f9}.accordion-button{position:relative;display:flex;display:-webkit-flex;align-items:center;-webkit-align-items:center;width:100%;padding:var(--bs-accordion-btn-padding-y) var(--bs-accordion-btn-padding-x);font-size:1rem;color:var(--bs-accordion-btn-color);text-align:left;background-color:var(--bs-accordion-btn-bg);border:0;overflow-anchor:none;transition:var(--bs-accordion-transition)}@media(prefers-reduced-motion: reduce){.accordion-button{transition:none}}.accordion-button:not(.collapsed){color:var(--bs-accordion-active-color);background-color:var(--bs-accordion-active-bg);box-shadow:inset 0 calc(-1*var(--bs-accordion-border-width)) 0 var(--bs-accordion-border-color)}.accordion-button:not(.collapsed)::after{background-image:var(--bs-accordion-btn-active-icon);transform:var(--bs-accordion-btn-icon-transform)}.accordion-button::after{flex-shrink:0;-webkit-flex-shrink:0;width:var(--bs-accordion-btn-icon-width);height:var(--bs-accordion-btn-icon-width);margin-left:auto;content:"";background-image:var(--bs-accordion-btn-icon);background-repeat:no-repeat;background-size:var(--bs-accordion-btn-icon-width);transition:var(--bs-accordion-btn-icon-transition)}@media(prefers-reduced-motion: reduce){.accordion-button::after{transition:none}}.accordion-button:hover{z-index:2}.accordion-button:focus{z-index:3;border-color:var(--bs-accordion-btn-focus-border-color);outline:0;box-shadow:var(--bs-accordion-btn-focus-box-shadow)}.accordion-header{margin-bottom:0}.accordion-item{color:var(--bs-accordion-color);background-color:var(--bs-accordion-bg);border:var(--bs-accordion-border-width) solid var(--bs-accordion-border-color)}.accordion-item:not(:first-of-type){border-top:0}.accordion-body{padding:var(--bs-accordion-body-padding-y) var(--bs-accordion-body-padding-x)}.accordion-flush .accordion-collapse{border-width:0}.accordion-flush .accordion-item{border-right:0;border-left:0}.accordion-flush .accordion-item:first-child{border-top:0}.accordion-flush .accordion-item:last-child{border-bottom:0}[data-bs-theme=dark] .accordion-button::after{--bs-accordion-btn-icon: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='%237db3ee'%3e%3cpath fill-rule='evenodd' d='M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z'/%3e%3c/svg%3e");--bs-accordion-btn-active-icon: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='%237db3ee'%3e%3cpath fill-rule='evenodd' d='M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z'/%3e%3c/svg%3e")}.breadcrumb{--bs-breadcrumb-padding-x: 0;--bs-breadcrumb-padding-y: 0;--bs-breadcrumb-margin-bottom: 1rem;--bs-breadcrumb-bg: ;--bs-breadcrumb-border-radius: ;--bs-breadcrumb-divider-color: rgba(52, 58, 64, 0.75);--bs-breadcrumb-item-padding-x: 0.5rem;--bs-breadcrumb-item-active-color: rgba(52, 58, 64, 0.75);display:flex;display:-webkit-flex;flex-wrap:wrap;-webkit-flex-wrap:wrap;padding:var(--bs-breadcrumb-padding-y) var(--bs-breadcrumb-padding-x);margin-bottom:var(--bs-breadcrumb-margin-bottom);font-size:var(--bs-breadcrumb-font-size);list-style:none;background-color:var(--bs-breadcrumb-bg)}.breadcrumb-item+.breadcrumb-item{padding-left:var(--bs-breadcrumb-item-padding-x)}.breadcrumb-item+.breadcrumb-item::before{float:left;padding-right:var(--bs-breadcrumb-item-padding-x);color:var(--bs-breadcrumb-divider-color);content:var(--bs-breadcrumb-divider, ">") /* rtl: var(--bs-breadcrumb-divider, ">") */}.breadcrumb-item.active{color:var(--bs-breadcrumb-item-active-color)}.pagination{--bs-pagination-padding-x: 0.75rem;--bs-pagination-padding-y: 0.375rem;--bs-pagination-font-size:1rem;--bs-pagination-color: #2761e3;--bs-pagination-bg: #fff;--bs-pagination-border-width: 1px;--bs-pagination-border-color: #dee2e6;--bs-pagination-border-radius: 0.25rem;--bs-pagination-hover-color: #1f4eb6;--bs-pagination-hover-bg: #f8f9fa;--bs-pagination-hover-border-color: #dee2e6;--bs-pagination-focus-color: #1f4eb6;--bs-pagination-focus-bg: #e9ecef;--bs-pagination-focus-box-shadow: 0 0 0 0.25rem rgba(39, 128, 227, 0.25);--bs-pagination-active-color: #fff;--bs-pagination-active-bg: #2780e3;--bs-pagination-active-border-color: #2780e3;--bs-pagination-disabled-color: rgba(52, 58, 64, 0.75);--bs-pagination-disabled-bg: #e9ecef;--bs-pagination-disabled-border-color: #dee2e6;display:flex;display:-webkit-flex;padding-left:0;list-style:none}.page-link{position:relative;display:block;padding:var(--bs-pagination-padding-y) var(--bs-pagination-padding-x);font-size:var(--bs-pagination-font-size);color:var(--bs-pagination-color);text-decoration:none;-webkit-text-decoration:none;-moz-text-decoration:none;-ms-text-decoration:none;-o-text-decoration:none;background-color:var(--bs-pagination-bg);border:var(--bs-pagination-border-width) solid var(--bs-pagination-border-color);transition:color .15s ease-in-out,background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media(prefers-reduced-motion: reduce){.page-link{transition:none}}.page-link:hover{z-index:2;color:var(--bs-pagination-hover-color);background-color:var(--bs-pagination-hover-bg);border-color:var(--bs-pagination-hover-border-color)}.page-link:focus{z-index:3;color:var(--bs-pagination-focus-color);background-color:var(--bs-pagination-focus-bg);outline:0;box-shadow:var(--bs-pagination-focus-box-shadow)}.page-link.active,.active>.page-link{z-index:3;color:var(--bs-pagination-active-color);background-color:var(--bs-pagination-active-bg);border-color:var(--bs-pagination-active-border-color)}.page-link.disabled,.disabled>.page-link{color:var(--bs-pagination-disabled-color);pointer-events:none;background-color:var(--bs-pagination-disabled-bg);border-color:var(--bs-pagination-disabled-border-color)}.page-item:not(:first-child) .page-link{margin-left:calc(1px*-1)}.pagination-lg{--bs-pagination-padding-x: 1.5rem;--bs-pagination-padding-y: 0.75rem;--bs-pagination-font-size:1.25rem;--bs-pagination-border-radius: 0.5rem}.pagination-sm{--bs-pagination-padding-x: 0.5rem;--bs-pagination-padding-y: 0.25rem;--bs-pagination-font-size:0.875rem;--bs-pagination-border-radius: 0.2em}.badge{--bs-badge-padding-x: 0.65em;--bs-badge-padding-y: 0.35em;--bs-badge-font-size:0.75em;--bs-badge-font-weight: 700;--bs-badge-color: #fff;--bs-badge-border-radius: 0.25rem;display:inline-block;padding:var(--bs-badge-padding-y) var(--bs-badge-padding-x);font-size:var(--bs-badge-font-size);font-weight:var(--bs-badge-font-weight);line-height:1;color:var(--bs-badge-color);text-align:center;white-space:nowrap;vertical-align:baseline}.badge:empty{display:none}.btn .badge{position:relative;top:-1px}.alert{--bs-alert-bg: transparent;--bs-alert-padding-x: 1rem;--bs-alert-padding-y: 1rem;--bs-alert-margin-bottom: 1rem;--bs-alert-color: inherit;--bs-alert-border-color: transparent;--bs-alert-border: 0 solid var(--bs-alert-border-color);--bs-alert-border-radius: 0.25rem;--bs-alert-link-color: inherit;position:relative;padding:var(--bs-alert-padding-y) var(--bs-alert-padding-x);margin-bottom:var(--bs-alert-margin-bottom);color:var(--bs-alert-color);background-color:var(--bs-alert-bg);border:var(--bs-alert-border)}.alert-heading{color:inherit}.alert-link{font-weight:700;color:var(--bs-alert-link-color)}.alert-dismissible{padding-right:3rem}.alert-dismissible .btn-close{position:absolute;top:0;right:0;z-index:2;padding:1.25rem 1rem}.alert-default{--bs-alert-color: var(--bs-default-text-emphasis);--bs-alert-bg: var(--bs-default-bg-subtle);--bs-alert-border-color: var(--bs-default-border-subtle);--bs-alert-link-color: var(--bs-default-text-emphasis)}.alert-primary{--bs-alert-color: var(--bs-primary-text-emphasis);--bs-alert-bg: var(--bs-primary-bg-subtle);--bs-alert-border-color: var(--bs-primary-border-subtle);--bs-alert-link-color: var(--bs-primary-text-emphasis)}.alert-secondary{--bs-alert-color: var(--bs-secondary-text-emphasis);--bs-alert-bg: var(--bs-secondary-bg-subtle);--bs-alert-border-color: var(--bs-secondary-border-subtle);--bs-alert-link-color: var(--bs-secondary-text-emphasis)}.alert-success{--bs-alert-color: var(--bs-success-text-emphasis);--bs-alert-bg: var(--bs-success-bg-subtle);--bs-alert-border-color: var(--bs-success-border-subtle);--bs-alert-link-color: var(--bs-success-text-emphasis)}.alert-info{--bs-alert-color: var(--bs-info-text-emphasis);--bs-alert-bg: var(--bs-info-bg-subtle);--bs-alert-border-color: var(--bs-info-border-subtle);--bs-alert-link-color: var(--bs-info-text-emphasis)}.alert-warning{--bs-alert-color: var(--bs-warning-text-emphasis);--bs-alert-bg: var(--bs-warning-bg-subtle);--bs-alert-border-color: var(--bs-warning-border-subtle);--bs-alert-link-color: var(--bs-warning-text-emphasis)}.alert-danger{--bs-alert-color: var(--bs-danger-text-emphasis);--bs-alert-bg: var(--bs-danger-bg-subtle);--bs-alert-border-color: var(--bs-danger-border-subtle);--bs-alert-link-color: var(--bs-danger-text-emphasis)}.alert-light{--bs-alert-color: var(--bs-light-text-emphasis);--bs-alert-bg: var(--bs-light-bg-subtle);--bs-alert-border-color: var(--bs-light-border-subtle);--bs-alert-link-color: var(--bs-light-text-emphasis)}.alert-dark{--bs-alert-color: var(--bs-dark-text-emphasis);--bs-alert-bg: var(--bs-dark-bg-subtle);--bs-alert-border-color: var(--bs-dark-border-subtle);--bs-alert-link-color: var(--bs-dark-text-emphasis)}@keyframes progress-bar-stripes{0%{background-position-x:.5rem}}.progress,.progress-stacked{--bs-progress-height: 0.5rem;--bs-progress-font-size:0.75rem;--bs-progress-bg: #e9ecef;--bs-progress-border-radius: 0.25rem;--bs-progress-box-shadow: inset 0 1px 2px rgba(0, 0, 0, 0.075);--bs-progress-bar-color: #fff;--bs-progress-bar-bg: #2780e3;--bs-progress-bar-transition: width 0.6s ease;display:flex;display:-webkit-flex;height:var(--bs-progress-height);overflow:hidden;font-size:var(--bs-progress-font-size);background-color:var(--bs-progress-bg)}.progress-bar{display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;justify-content:center;-webkit-justify-content:center;overflow:hidden;color:var(--bs-progress-bar-color);text-align:center;white-space:nowrap;background-color:var(--bs-progress-bar-bg);transition:var(--bs-progress-bar-transition)}@media(prefers-reduced-motion: reduce){.progress-bar{transition:none}}.progress-bar-striped{background-image:linear-gradient(45deg, rgba(255, 255, 255, 0.15) 25%, transparent 25%, transparent 50%, rgba(255, 255, 255, 0.15) 50%, rgba(255, 255, 255, 0.15) 75%, transparent 75%, transparent);background-size:var(--bs-progress-height) var(--bs-progress-height)}.progress-stacked>.progress{overflow:visible}.progress-stacked>.progress>.progress-bar{width:100%}.progress-bar-animated{animation:1s linear infinite progress-bar-stripes}@media(prefers-reduced-motion: reduce){.progress-bar-animated{animation:none}}.list-group{--bs-list-group-color: #343a40;--bs-list-group-bg: #fff;--bs-list-group-border-color: #dee2e6;--bs-list-group-border-width: 1px;--bs-list-group-border-radius: 0.25rem;--bs-list-group-item-padding-x: 1rem;--bs-list-group-item-padding-y: 0.5rem;--bs-list-group-action-color: rgba(52, 58, 64, 0.75);--bs-list-group-action-hover-color: #000;--bs-list-group-action-hover-bg: #f8f9fa;--bs-list-group-action-active-color: #343a40;--bs-list-group-action-active-bg: #e9ecef;--bs-list-group-disabled-color: rgba(52, 58, 64, 0.75);--bs-list-group-disabled-bg: #fff;--bs-list-group-active-color: #fff;--bs-list-group-active-bg: #2780e3;--bs-list-group-active-border-color: #2780e3;display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;padding-left:0;margin-bottom:0}.list-group-numbered{list-style-type:none;counter-reset:section}.list-group-numbered>.list-group-item::before{content:counters(section, ".") ". ";counter-increment:section}.list-group-item-action{width:100%;color:var(--bs-list-group-action-color);text-align:inherit}.list-group-item-action:hover,.list-group-item-action:focus{z-index:1;color:var(--bs-list-group-action-hover-color);text-decoration:none;background-color:var(--bs-list-group-action-hover-bg)}.list-group-item-action:active{color:var(--bs-list-group-action-active-color);background-color:var(--bs-list-group-action-active-bg)}.list-group-item{position:relative;display:block;padding:var(--bs-list-group-item-padding-y) var(--bs-list-group-item-padding-x);color:var(--bs-list-group-color);text-decoration:none;-webkit-text-decoration:none;-moz-text-decoration:none;-ms-text-decoration:none;-o-text-decoration:none;background-color:var(--bs-list-group-bg);border:var(--bs-list-group-border-width) solid var(--bs-list-group-border-color)}.list-group-item.disabled,.list-group-item:disabled{color:var(--bs-list-group-disabled-color);pointer-events:none;background-color:var(--bs-list-group-disabled-bg)}.list-group-item.active{z-index:2;color:var(--bs-list-group-active-color);background-color:var(--bs-list-group-active-bg);border-color:var(--bs-list-group-active-border-color)}.list-group-item+.list-group-item{border-top-width:0}.list-group-item+.list-group-item.active{margin-top:calc(-1*var(--bs-list-group-border-width));border-top-width:var(--bs-list-group-border-width)}.list-group-horizontal{flex-direction:row;-webkit-flex-direction:row}.list-group-horizontal>.list-group-item.active{margin-top:0}.list-group-horizontal>.list-group-item+.list-group-item{border-top-width:var(--bs-list-group-border-width);border-left-width:0}.list-group-horizontal>.list-group-item+.list-group-item.active{margin-left:calc(-1*var(--bs-list-group-border-width));border-left-width:var(--bs-list-group-border-width)}@media(min-width: 576px){.list-group-horizontal-sm{flex-direction:row;-webkit-flex-direction:row}.list-group-horizontal-sm>.list-group-item.active{margin-top:0}.list-group-horizontal-sm>.list-group-item+.list-group-item{border-top-width:var(--bs-list-group-border-width);border-left-width:0}.list-group-horizontal-sm>.list-group-item+.list-group-item.active{margin-left:calc(-1*var(--bs-list-group-border-width));border-left-width:var(--bs-list-group-border-width)}}@media(min-width: 768px){.list-group-horizontal-md{flex-direction:row;-webkit-flex-direction:row}.list-group-horizontal-md>.list-group-item.active{margin-top:0}.list-group-horizontal-md>.list-group-item+.list-group-item{border-top-width:var(--bs-list-group-border-width);border-left-width:0}.list-group-horizontal-md>.list-group-item+.list-group-item.active{margin-left:calc(-1*var(--bs-list-group-border-width));border-left-width:var(--bs-list-group-border-width)}}@media(min-width: 992px){.list-group-horizontal-lg{flex-direction:row;-webkit-flex-direction:row}.list-group-horizontal-lg>.list-group-item.active{margin-top:0}.list-group-horizontal-lg>.list-group-item+.list-group-item{border-top-width:var(--bs-list-group-border-width);border-left-width:0}.list-group-horizontal-lg>.list-group-item+.list-group-item.active{margin-left:calc(-1*var(--bs-list-group-border-width));border-left-width:var(--bs-list-group-border-width)}}@media(min-width: 1200px){.list-group-horizontal-xl{flex-direction:row;-webkit-flex-direction:row}.list-group-horizontal-xl>.list-group-item.active{margin-top:0}.list-group-horizontal-xl>.list-group-item+.list-group-item{border-top-width:var(--bs-list-group-border-width);border-left-width:0}.list-group-horizontal-xl>.list-group-item+.list-group-item.active{margin-left:calc(-1*var(--bs-list-group-border-width));border-left-width:var(--bs-list-group-border-width)}}@media(min-width: 1400px){.list-group-horizontal-xxl{flex-direction:row;-webkit-flex-direction:row}.list-group-horizontal-xxl>.list-group-item.active{margin-top:0}.list-group-horizontal-xxl>.list-group-item+.list-group-item{border-top-width:var(--bs-list-group-border-width);border-left-width:0}.list-group-horizontal-xxl>.list-group-item+.list-group-item.active{margin-left:calc(-1*var(--bs-list-group-border-width));border-left-width:var(--bs-list-group-border-width)}}.list-group-flush>.list-group-item{border-width:0 0 var(--bs-list-group-border-width)}.list-group-flush>.list-group-item:last-child{border-bottom-width:0}.list-group-item-default{--bs-list-group-color: var(--bs-default-text-emphasis);--bs-list-group-bg: var(--bs-default-bg-subtle);--bs-list-group-border-color: var(--bs-default-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-default-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-default-border-subtle);--bs-list-group-active-color: var(--bs-default-bg-subtle);--bs-list-group-active-bg: var(--bs-default-text-emphasis);--bs-list-group-active-border-color: var(--bs-default-text-emphasis)}.list-group-item-primary{--bs-list-group-color: var(--bs-primary-text-emphasis);--bs-list-group-bg: var(--bs-primary-bg-subtle);--bs-list-group-border-color: var(--bs-primary-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-primary-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-primary-border-subtle);--bs-list-group-active-color: var(--bs-primary-bg-subtle);--bs-list-group-active-bg: var(--bs-primary-text-emphasis);--bs-list-group-active-border-color: var(--bs-primary-text-emphasis)}.list-group-item-secondary{--bs-list-group-color: var(--bs-secondary-text-emphasis);--bs-list-group-bg: var(--bs-secondary-bg-subtle);--bs-list-group-border-color: var(--bs-secondary-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-secondary-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-secondary-border-subtle);--bs-list-group-active-color: var(--bs-secondary-bg-subtle);--bs-list-group-active-bg: var(--bs-secondary-text-emphasis);--bs-list-group-active-border-color: var(--bs-secondary-text-emphasis)}.list-group-item-success{--bs-list-group-color: var(--bs-success-text-emphasis);--bs-list-group-bg: var(--bs-success-bg-subtle);--bs-list-group-border-color: var(--bs-success-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-success-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-success-border-subtle);--bs-list-group-active-color: var(--bs-success-bg-subtle);--bs-list-group-active-bg: var(--bs-success-text-emphasis);--bs-list-group-active-border-color: var(--bs-success-text-emphasis)}.list-group-item-info{--bs-list-group-color: var(--bs-info-text-emphasis);--bs-list-group-bg: var(--bs-info-bg-subtle);--bs-list-group-border-color: var(--bs-info-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-info-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-info-border-subtle);--bs-list-group-active-color: var(--bs-info-bg-subtle);--bs-list-group-active-bg: var(--bs-info-text-emphasis);--bs-list-group-active-border-color: var(--bs-info-text-emphasis)}.list-group-item-warning{--bs-list-group-color: var(--bs-warning-text-emphasis);--bs-list-group-bg: var(--bs-warning-bg-subtle);--bs-list-group-border-color: var(--bs-warning-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-warning-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-warning-border-subtle);--bs-list-group-active-color: var(--bs-warning-bg-subtle);--bs-list-group-active-bg: var(--bs-warning-text-emphasis);--bs-list-group-active-border-color: var(--bs-warning-text-emphasis)}.list-group-item-danger{--bs-list-group-color: var(--bs-danger-text-emphasis);--bs-list-group-bg: var(--bs-danger-bg-subtle);--bs-list-group-border-color: var(--bs-danger-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-danger-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-danger-border-subtle);--bs-list-group-active-color: var(--bs-danger-bg-subtle);--bs-list-group-active-bg: var(--bs-danger-text-emphasis);--bs-list-group-active-border-color: var(--bs-danger-text-emphasis)}.list-group-item-light{--bs-list-group-color: var(--bs-light-text-emphasis);--bs-list-group-bg: var(--bs-light-bg-subtle);--bs-list-group-border-color: var(--bs-light-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-light-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-light-border-subtle);--bs-list-group-active-color: var(--bs-light-bg-subtle);--bs-list-group-active-bg: var(--bs-light-text-emphasis);--bs-list-group-active-border-color: var(--bs-light-text-emphasis)}.list-group-item-dark{--bs-list-group-color: var(--bs-dark-text-emphasis);--bs-list-group-bg: var(--bs-dark-bg-subtle);--bs-list-group-border-color: var(--bs-dark-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-dark-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-dark-border-subtle);--bs-list-group-active-color: var(--bs-dark-bg-subtle);--bs-list-group-active-bg: var(--bs-dark-text-emphasis);--bs-list-group-active-border-color: var(--bs-dark-text-emphasis)}.btn-close{--bs-btn-close-color: #000;--bs-btn-close-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='%23000'%3e%3cpath d='M.293.293a1 1 0 0 1 1.414 0L8 6.586 14.293.293a1 1 0 1 1 1.414 1.414L9.414 8l6.293 6.293a1 1 0 0 1-1.414 1.414L8 9.414l-6.293 6.293a1 1 0 0 1-1.414-1.414L6.586 8 .293 1.707a1 1 0 0 1 0-1.414z'/%3e%3c/svg%3e");--bs-btn-close-opacity: 0.5;--bs-btn-close-hover-opacity: 0.75;--bs-btn-close-focus-shadow: 0 0 0 0.25rem rgba(39, 128, 227, 0.25);--bs-btn-close-focus-opacity: 1;--bs-btn-close-disabled-opacity: 0.25;--bs-btn-close-white-filter: invert(1) grayscale(100%) brightness(200%);box-sizing:content-box;width:1em;height:1em;padding:.25em .25em;color:var(--bs-btn-close-color);background:rgba(0,0,0,0) var(--bs-btn-close-bg) center/1em auto no-repeat;border:0;opacity:var(--bs-btn-close-opacity)}.btn-close:hover{color:var(--bs-btn-close-color);text-decoration:none;opacity:var(--bs-btn-close-hover-opacity)}.btn-close:focus{outline:0;box-shadow:var(--bs-btn-close-focus-shadow);opacity:var(--bs-btn-close-focus-opacity)}.btn-close:disabled,.btn-close.disabled{pointer-events:none;user-select:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;-o-user-select:none;opacity:var(--bs-btn-close-disabled-opacity)}.btn-close-white{filter:var(--bs-btn-close-white-filter)}[data-bs-theme=dark] .btn-close{filter:var(--bs-btn-close-white-filter)}.toast{--bs-toast-zindex: 1090;--bs-toast-padding-x: 0.75rem;--bs-toast-padding-y: 0.5rem;--bs-toast-spacing: 1.5rem;--bs-toast-max-width: 350px;--bs-toast-font-size:0.875rem;--bs-toast-color: ;--bs-toast-bg: rgba(255, 255, 255, 0.85);--bs-toast-border-width: 1px;--bs-toast-border-color: rgba(0, 0, 0, 0.175);--bs-toast-border-radius: 0.25rem;--bs-toast-box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);--bs-toast-header-color: rgba(52, 58, 64, 0.75);--bs-toast-header-bg: rgba(255, 255, 255, 0.85);--bs-toast-header-border-color: rgba(0, 0, 0, 0.175);width:var(--bs-toast-max-width);max-width:100%;font-size:var(--bs-toast-font-size);color:var(--bs-toast-color);pointer-events:auto;background-color:var(--bs-toast-bg);background-clip:padding-box;border:var(--bs-toast-border-width) solid var(--bs-toast-border-color);box-shadow:var(--bs-toast-box-shadow)}.toast.showing{opacity:0}.toast:not(.show){display:none}.toast-container{--bs-toast-zindex: 1090;position:absolute;z-index:var(--bs-toast-zindex);width:max-content;width:-webkit-max-content;width:-moz-max-content;width:-ms-max-content;width:-o-max-content;max-width:100%;pointer-events:none}.toast-container>:not(:last-child){margin-bottom:var(--bs-toast-spacing)}.toast-header{display:flex;display:-webkit-flex;align-items:center;-webkit-align-items:center;padding:var(--bs-toast-padding-y) var(--bs-toast-padding-x);color:var(--bs-toast-header-color);background-color:var(--bs-toast-header-bg);background-clip:padding-box;border-bottom:var(--bs-toast-border-width) solid var(--bs-toast-header-border-color)}.toast-header .btn-close{margin-right:calc(-0.5*var(--bs-toast-padding-x));margin-left:var(--bs-toast-padding-x)}.toast-body{padding:var(--bs-toast-padding-x);word-wrap:break-word}.modal{--bs-modal-zindex: 1055;--bs-modal-width: 500px;--bs-modal-padding: 1rem;--bs-modal-margin: 0.5rem;--bs-modal-color: ;--bs-modal-bg: #fff;--bs-modal-border-color: rgba(0, 0, 0, 0.175);--bs-modal-border-width: 1px;--bs-modal-border-radius: 0.5rem;--bs-modal-box-shadow: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.075);--bs-modal-inner-border-radius: calc(0.5rem - 1px);--bs-modal-header-padding-x: 1rem;--bs-modal-header-padding-y: 1rem;--bs-modal-header-padding: 1rem 1rem;--bs-modal-header-border-color: #dee2e6;--bs-modal-header-border-width: 1px;--bs-modal-title-line-height: 1.5;--bs-modal-footer-gap: 0.5rem;--bs-modal-footer-bg: ;--bs-modal-footer-border-color: #dee2e6;--bs-modal-footer-border-width: 1px;position:fixed;top:0;left:0;z-index:var(--bs-modal-zindex);display:none;width:100%;height:100%;overflow-x:hidden;overflow-y:auto;outline:0}.modal-dialog{position:relative;width:auto;margin:var(--bs-modal-margin);pointer-events:none}.modal.fade .modal-dialog{transition:transform .3s ease-out;transform:translate(0, -50px)}@media(prefers-reduced-motion: reduce){.modal.fade .modal-dialog{transition:none}}.modal.show .modal-dialog{transform:none}.modal.modal-static .modal-dialog{transform:scale(1.02)}.modal-dialog-scrollable{height:calc(100% - var(--bs-modal-margin)*2)}.modal-dialog-scrollable .modal-content{max-height:100%;overflow:hidden}.modal-dialog-scrollable .modal-body{overflow-y:auto}.modal-dialog-centered{display:flex;display:-webkit-flex;align-items:center;-webkit-align-items:center;min-height:calc(100% - var(--bs-modal-margin)*2)}.modal-content{position:relative;display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;width:100%;color:var(--bs-modal-color);pointer-events:auto;background-color:var(--bs-modal-bg);background-clip:padding-box;border:var(--bs-modal-border-width) solid var(--bs-modal-border-color);outline:0}.modal-backdrop{--bs-backdrop-zindex: 1050;--bs-backdrop-bg: #000;--bs-backdrop-opacity: 0.5;position:fixed;top:0;left:0;z-index:var(--bs-backdrop-zindex);width:100vw;height:100vh;background-color:var(--bs-backdrop-bg)}.modal-backdrop.fade{opacity:0}.modal-backdrop.show{opacity:var(--bs-backdrop-opacity)}.modal-header{display:flex;display:-webkit-flex;flex-shrink:0;-webkit-flex-shrink:0;align-items:center;-webkit-align-items:center;justify-content:space-between;-webkit-justify-content:space-between;padding:var(--bs-modal-header-padding);border-bottom:var(--bs-modal-header-border-width) solid var(--bs-modal-header-border-color)}.modal-header .btn-close{padding:calc(var(--bs-modal-header-padding-y)*.5) calc(var(--bs-modal-header-padding-x)*.5);margin:calc(-0.5*var(--bs-modal-header-padding-y)) calc(-0.5*var(--bs-modal-header-padding-x)) calc(-0.5*var(--bs-modal-header-padding-y)) auto}.modal-title{margin-bottom:0;line-height:var(--bs-modal-title-line-height)}.modal-body{position:relative;flex:1 1 auto;-webkit-flex:1 1 auto;padding:var(--bs-modal-padding)}.modal-footer{display:flex;display:-webkit-flex;flex-shrink:0;-webkit-flex-shrink:0;flex-wrap:wrap;-webkit-flex-wrap:wrap;align-items:center;-webkit-align-items:center;justify-content:flex-end;-webkit-justify-content:flex-end;padding:calc(var(--bs-modal-padding) - var(--bs-modal-footer-gap)*.5);background-color:var(--bs-modal-footer-bg);border-top:var(--bs-modal-footer-border-width) solid var(--bs-modal-footer-border-color)}.modal-footer>*{margin:calc(var(--bs-modal-footer-gap)*.5)}@media(min-width: 576px){.modal{--bs-modal-margin: 1.75rem;--bs-modal-box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15)}.modal-dialog{max-width:var(--bs-modal-width);margin-right:auto;margin-left:auto}.modal-sm{--bs-modal-width: 300px}}@media(min-width: 992px){.modal-lg,.modal-xl{--bs-modal-width: 800px}}@media(min-width: 1200px){.modal-xl{--bs-modal-width: 1140px}}.modal-fullscreen{width:100vw;max-width:none;height:100%;margin:0}.modal-fullscreen .modal-content{height:100%;border:0}.modal-fullscreen .modal-body{overflow-y:auto}@media(max-width: 575.98px){.modal-fullscreen-sm-down{width:100vw;max-width:none;height:100%;margin:0}.modal-fullscreen-sm-down .modal-content{height:100%;border:0}.modal-fullscreen-sm-down .modal-body{overflow-y:auto}}@media(max-width: 767.98px){.modal-fullscreen-md-down{width:100vw;max-width:none;height:100%;margin:0}.modal-fullscreen-md-down .modal-content{height:100%;border:0}.modal-fullscreen-md-down .modal-body{overflow-y:auto}}@media(max-width: 991.98px){.modal-fullscreen-lg-down{width:100vw;max-width:none;height:100%;margin:0}.modal-fullscreen-lg-down .modal-content{height:100%;border:0}.modal-fullscreen-lg-down .modal-body{overflow-y:auto}}@media(max-width: 1199.98px){.modal-fullscreen-xl-down{width:100vw;max-width:none;height:100%;margin:0}.modal-fullscreen-xl-down .modal-content{height:100%;border:0}.modal-fullscreen-xl-down .modal-body{overflow-y:auto}}@media(max-width: 1399.98px){.modal-fullscreen-xxl-down{width:100vw;max-width:none;height:100%;margin:0}.modal-fullscreen-xxl-down .modal-content{height:100%;border:0}.modal-fullscreen-xxl-down .modal-body{overflow-y:auto}}.tooltip{--bs-tooltip-zindex: 1080;--bs-tooltip-max-width: 200px;--bs-tooltip-padding-x: 0.5rem;--bs-tooltip-padding-y: 0.25rem;--bs-tooltip-margin: ;--bs-tooltip-font-size:0.875rem;--bs-tooltip-color: #fff;--bs-tooltip-bg: #000;--bs-tooltip-border-radius: 0.25rem;--bs-tooltip-opacity: 0.9;--bs-tooltip-arrow-width: 0.8rem;--bs-tooltip-arrow-height: 0.4rem;z-index:var(--bs-tooltip-zindex);display:block;margin:var(--bs-tooltip-margin);font-family:"Source Sans Pro",-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol";font-style:normal;font-weight:400;line-height:1.5;text-align:left;text-align:start;text-decoration:none;text-shadow:none;text-transform:none;letter-spacing:normal;word-break:normal;white-space:normal;word-spacing:normal;line-break:auto;font-size:var(--bs-tooltip-font-size);word-wrap:break-word;opacity:0}.tooltip.show{opacity:var(--bs-tooltip-opacity)}.tooltip .tooltip-arrow{display:block;width:var(--bs-tooltip-arrow-width);height:var(--bs-tooltip-arrow-height)}.tooltip .tooltip-arrow::before{position:absolute;content:"";border-color:rgba(0,0,0,0);border-style:solid}.bs-tooltip-top .tooltip-arrow,.bs-tooltip-auto[data-popper-placement^=top] .tooltip-arrow{bottom:calc(-1*var(--bs-tooltip-arrow-height))}.bs-tooltip-top .tooltip-arrow::before,.bs-tooltip-auto[data-popper-placement^=top] .tooltip-arrow::before{top:-1px;border-width:var(--bs-tooltip-arrow-height) calc(var(--bs-tooltip-arrow-width)*.5) 0;border-top-color:var(--bs-tooltip-bg)}.bs-tooltip-end .tooltip-arrow,.bs-tooltip-auto[data-popper-placement^=right] .tooltip-arrow{left:calc(-1*var(--bs-tooltip-arrow-height));width:var(--bs-tooltip-arrow-height);height:var(--bs-tooltip-arrow-width)}.bs-tooltip-end .tooltip-arrow::before,.bs-tooltip-auto[data-popper-placement^=right] .tooltip-arrow::before{right:-1px;border-width:calc(var(--bs-tooltip-arrow-width)*.5) var(--bs-tooltip-arrow-height) calc(var(--bs-tooltip-arrow-width)*.5) 0;border-right-color:var(--bs-tooltip-bg)}.bs-tooltip-bottom .tooltip-arrow,.bs-tooltip-auto[data-popper-placement^=bottom] .tooltip-arrow{top:calc(-1*var(--bs-tooltip-arrow-height))}.bs-tooltip-bottom .tooltip-arrow::before,.bs-tooltip-auto[data-popper-placement^=bottom] .tooltip-arrow::before{bottom:-1px;border-width:0 calc(var(--bs-tooltip-arrow-width)*.5) var(--bs-tooltip-arrow-height);border-bottom-color:var(--bs-tooltip-bg)}.bs-tooltip-start .tooltip-arrow,.bs-tooltip-auto[data-popper-placement^=left] .tooltip-arrow{right:calc(-1*var(--bs-tooltip-arrow-height));width:var(--bs-tooltip-arrow-height);height:var(--bs-tooltip-arrow-width)}.bs-tooltip-start .tooltip-arrow::before,.bs-tooltip-auto[data-popper-placement^=left] .tooltip-arrow::before{left:-1px;border-width:calc(var(--bs-tooltip-arrow-width)*.5) 0 calc(var(--bs-tooltip-arrow-width)*.5) var(--bs-tooltip-arrow-height);border-left-color:var(--bs-tooltip-bg)}.tooltip-inner{max-width:var(--bs-tooltip-max-width);padding:var(--bs-tooltip-padding-y) var(--bs-tooltip-padding-x);color:var(--bs-tooltip-color);text-align:center;background-color:var(--bs-tooltip-bg)}.popover{--bs-popover-zindex: 1070;--bs-popover-max-width: 276px;--bs-popover-font-size:0.875rem;--bs-popover-bg: #fff;--bs-popover-border-width: 1px;--bs-popover-border-color: rgba(0, 0, 0, 0.175);--bs-popover-border-radius: 0.5rem;--bs-popover-inner-border-radius: calc(0.5rem - 1px);--bs-popover-box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);--bs-popover-header-padding-x: 1rem;--bs-popover-header-padding-y: 0.5rem;--bs-popover-header-font-size:1rem;--bs-popover-header-color: inherit;--bs-popover-header-bg: #e9ecef;--bs-popover-body-padding-x: 1rem;--bs-popover-body-padding-y: 1rem;--bs-popover-body-color: #343a40;--bs-popover-arrow-width: 1rem;--bs-popover-arrow-height: 0.5rem;--bs-popover-arrow-border: var(--bs-popover-border-color);z-index:var(--bs-popover-zindex);display:block;max-width:var(--bs-popover-max-width);font-family:"Source Sans Pro",-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol";font-style:normal;font-weight:400;line-height:1.5;text-align:left;text-align:start;text-decoration:none;text-shadow:none;text-transform:none;letter-spacing:normal;word-break:normal;white-space:normal;word-spacing:normal;line-break:auto;font-size:var(--bs-popover-font-size);word-wrap:break-word;background-color:var(--bs-popover-bg);background-clip:padding-box;border:var(--bs-popover-border-width) solid var(--bs-popover-border-color)}.popover .popover-arrow{display:block;width:var(--bs-popover-arrow-width);height:var(--bs-popover-arrow-height)}.popover .popover-arrow::before,.popover .popover-arrow::after{position:absolute;display:block;content:"";border-color:rgba(0,0,0,0);border-style:solid;border-width:0}.bs-popover-top>.popover-arrow,.bs-popover-auto[data-popper-placement^=top]>.popover-arrow{bottom:calc(-1*(var(--bs-popover-arrow-height)) - var(--bs-popover-border-width))}.bs-popover-top>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=top]>.popover-arrow::before,.bs-popover-top>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=top]>.popover-arrow::after{border-width:var(--bs-popover-arrow-height) calc(var(--bs-popover-arrow-width)*.5) 0}.bs-popover-top>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=top]>.popover-arrow::before{bottom:0;border-top-color:var(--bs-popover-arrow-border)}.bs-popover-top>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=top]>.popover-arrow::after{bottom:var(--bs-popover-border-width);border-top-color:var(--bs-popover-bg)}.bs-popover-end>.popover-arrow,.bs-popover-auto[data-popper-placement^=right]>.popover-arrow{left:calc(-1*(var(--bs-popover-arrow-height)) - var(--bs-popover-border-width));width:var(--bs-popover-arrow-height);height:var(--bs-popover-arrow-width)}.bs-popover-end>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=right]>.popover-arrow::before,.bs-popover-end>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=right]>.popover-arrow::after{border-width:calc(var(--bs-popover-arrow-width)*.5) var(--bs-popover-arrow-height) calc(var(--bs-popover-arrow-width)*.5) 0}.bs-popover-end>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=right]>.popover-arrow::before{left:0;border-right-color:var(--bs-popover-arrow-border)}.bs-popover-end>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=right]>.popover-arrow::after{left:var(--bs-popover-border-width);border-right-color:var(--bs-popover-bg)}.bs-popover-bottom>.popover-arrow,.bs-popover-auto[data-popper-placement^=bottom]>.popover-arrow{top:calc(-1*(var(--bs-popover-arrow-height)) - var(--bs-popover-border-width))}.bs-popover-bottom>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=bottom]>.popover-arrow::before,.bs-popover-bottom>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=bottom]>.popover-arrow::after{border-width:0 calc(var(--bs-popover-arrow-width)*.5) var(--bs-popover-arrow-height)}.bs-popover-bottom>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=bottom]>.popover-arrow::before{top:0;border-bottom-color:var(--bs-popover-arrow-border)}.bs-popover-bottom>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=bottom]>.popover-arrow::after{top:var(--bs-popover-border-width);border-bottom-color:var(--bs-popover-bg)}.bs-popover-bottom .popover-header::before,.bs-popover-auto[data-popper-placement^=bottom] .popover-header::before{position:absolute;top:0;left:50%;display:block;width:var(--bs-popover-arrow-width);margin-left:calc(-0.5*var(--bs-popover-arrow-width));content:"";border-bottom:var(--bs-popover-border-width) solid var(--bs-popover-header-bg)}.bs-popover-start>.popover-arrow,.bs-popover-auto[data-popper-placement^=left]>.popover-arrow{right:calc(-1*(var(--bs-popover-arrow-height)) - var(--bs-popover-border-width));width:var(--bs-popover-arrow-height);height:var(--bs-popover-arrow-width)}.bs-popover-start>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=left]>.popover-arrow::before,.bs-popover-start>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=left]>.popover-arrow::after{border-width:calc(var(--bs-popover-arrow-width)*.5) 0 calc(var(--bs-popover-arrow-width)*.5) var(--bs-popover-arrow-height)}.bs-popover-start>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=left]>.popover-arrow::before{right:0;border-left-color:var(--bs-popover-arrow-border)}.bs-popover-start>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=left]>.popover-arrow::after{right:var(--bs-popover-border-width);border-left-color:var(--bs-popover-bg)}.popover-header{padding:var(--bs-popover-header-padding-y) var(--bs-popover-header-padding-x);margin-bottom:0;font-size:var(--bs-popover-header-font-size);color:var(--bs-popover-header-color);background-color:var(--bs-popover-header-bg);border-bottom:var(--bs-popover-border-width) solid var(--bs-popover-border-color)}.popover-header:empty{display:none}.popover-body{padding:var(--bs-popover-body-padding-y) var(--bs-popover-body-padding-x);color:var(--bs-popover-body-color)}.carousel{position:relative}.carousel.pointer-event{touch-action:pan-y;-webkit-touch-action:pan-y;-moz-touch-action:pan-y;-ms-touch-action:pan-y;-o-touch-action:pan-y}.carousel-inner{position:relative;width:100%;overflow:hidden}.carousel-inner::after{display:block;clear:both;content:""}.carousel-item{position:relative;display:none;float:left;width:100%;margin-right:-100%;backface-visibility:hidden;-webkit-backface-visibility:hidden;-moz-backface-visibility:hidden;-ms-backface-visibility:hidden;-o-backface-visibility:hidden;transition:transform .6s ease-in-out}@media(prefers-reduced-motion: reduce){.carousel-item{transition:none}}.carousel-item.active,.carousel-item-next,.carousel-item-prev{display:block}.carousel-item-next:not(.carousel-item-start),.active.carousel-item-end{transform:translateX(100%)}.carousel-item-prev:not(.carousel-item-end),.active.carousel-item-start{transform:translateX(-100%)}.carousel-fade .carousel-item{opacity:0;transition-property:opacity;transform:none}.carousel-fade .carousel-item.active,.carousel-fade .carousel-item-next.carousel-item-start,.carousel-fade .carousel-item-prev.carousel-item-end{z-index:1;opacity:1}.carousel-fade .active.carousel-item-start,.carousel-fade .active.carousel-item-end{z-index:0;opacity:0;transition:opacity 0s .6s}@media(prefers-reduced-motion: reduce){.carousel-fade .active.carousel-item-start,.carousel-fade .active.carousel-item-end{transition:none}}.carousel-control-prev,.carousel-control-next{position:absolute;top:0;bottom:0;z-index:1;display:flex;display:-webkit-flex;align-items:center;-webkit-align-items:center;justify-content:center;-webkit-justify-content:center;width:15%;padding:0;color:#fff;text-align:center;background:none;border:0;opacity:.5;transition:opacity .15s ease}@media(prefers-reduced-motion: reduce){.carousel-control-prev,.carousel-control-next{transition:none}}.carousel-control-prev:hover,.carousel-control-prev:focus,.carousel-control-next:hover,.carousel-control-next:focus{color:#fff;text-decoration:none;outline:0;opacity:.9}.carousel-control-prev{left:0}.carousel-control-next{right:0}.carousel-control-prev-icon,.carousel-control-next-icon{display:inline-block;width:2rem;height:2rem;background-repeat:no-repeat;background-position:50%;background-size:100% 100%}.carousel-control-prev-icon{background-image:url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='%23fff'%3e%3cpath d='M11.354 1.646a.5.5 0 0 1 0 .708L5.707 8l5.647 5.646a.5.5 0 0 1-.708.708l-6-6a.5.5 0 0 1 0-.708l6-6a.5.5 0 0 1 .708 0z'/%3e%3c/svg%3e")}.carousel-control-next-icon{background-image:url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='%23fff'%3e%3cpath d='M4.646 1.646a.5.5 0 0 1 .708 0l6 6a.5.5 0 0 1 0 .708l-6 6a.5.5 0 0 1-.708-.708L10.293 8 4.646 2.354a.5.5 0 0 1 0-.708z'/%3e%3c/svg%3e")}.carousel-indicators{position:absolute;right:0;bottom:0;left:0;z-index:2;display:flex;display:-webkit-flex;justify-content:center;-webkit-justify-content:center;padding:0;margin-right:15%;margin-bottom:1rem;margin-left:15%}.carousel-indicators [data-bs-target]{box-sizing:content-box;flex:0 1 auto;-webkit-flex:0 1 auto;width:30px;height:3px;padding:0;margin-right:3px;margin-left:3px;text-indent:-999px;cursor:pointer;background-color:#fff;background-clip:padding-box;border:0;border-top:10px solid rgba(0,0,0,0);border-bottom:10px solid rgba(0,0,0,0);opacity:.5;transition:opacity .6s ease}@media(prefers-reduced-motion: reduce){.carousel-indicators [data-bs-target]{transition:none}}.carousel-indicators .active{opacity:1}.carousel-caption{position:absolute;right:15%;bottom:1.25rem;left:15%;padding-top:1.25rem;padding-bottom:1.25rem;color:#fff;text-align:center}.carousel-dark .carousel-control-prev-icon,.carousel-dark .carousel-control-next-icon{filter:invert(1) grayscale(100)}.carousel-dark .carousel-indicators [data-bs-target]{background-color:#000}.carousel-dark .carousel-caption{color:#000}[data-bs-theme=dark] .carousel .carousel-control-prev-icon,[data-bs-theme=dark] .carousel .carousel-control-next-icon,[data-bs-theme=dark].carousel .carousel-control-prev-icon,[data-bs-theme=dark].carousel .carousel-control-next-icon{filter:invert(1) grayscale(100)}[data-bs-theme=dark] .carousel .carousel-indicators [data-bs-target],[data-bs-theme=dark].carousel .carousel-indicators [data-bs-target]{background-color:#000}[data-bs-theme=dark] .carousel .carousel-caption,[data-bs-theme=dark].carousel .carousel-caption{color:#000}.spinner-grow,.spinner-border{display:inline-block;width:var(--bs-spinner-width);height:var(--bs-spinner-height);vertical-align:var(--bs-spinner-vertical-align);border-radius:50%;animation:var(--bs-spinner-animation-speed) linear infinite var(--bs-spinner-animation-name)}@keyframes spinner-border{to{transform:rotate(360deg) /* rtl:ignore */}}.spinner-border{--bs-spinner-width: 2rem;--bs-spinner-height: 2rem;--bs-spinner-vertical-align: -0.125em;--bs-spinner-border-width: 0.25em;--bs-spinner-animation-speed: 0.75s;--bs-spinner-animation-name: spinner-border;border:var(--bs-spinner-border-width) solid currentcolor;border-right-color:rgba(0,0,0,0)}.spinner-border-sm{--bs-spinner-width: 1rem;--bs-spinner-height: 1rem;--bs-spinner-border-width: 0.2em}@keyframes spinner-grow{0%{transform:scale(0)}50%{opacity:1;transform:none}}.spinner-grow{--bs-spinner-width: 2rem;--bs-spinner-height: 2rem;--bs-spinner-vertical-align: -0.125em;--bs-spinner-animation-speed: 0.75s;--bs-spinner-animation-name: spinner-grow;background-color:currentcolor;opacity:0}.spinner-grow-sm{--bs-spinner-width: 1rem;--bs-spinner-height: 1rem}@media(prefers-reduced-motion: reduce){.spinner-border,.spinner-grow{--bs-spinner-animation-speed: 1.5s}}.offcanvas,.offcanvas-xxl,.offcanvas-xl,.offcanvas-lg,.offcanvas-md,.offcanvas-sm{--bs-offcanvas-zindex: 1045;--bs-offcanvas-width: 400px;--bs-offcanvas-height: 30vh;--bs-offcanvas-padding-x: 1rem;--bs-offcanvas-padding-y: 1rem;--bs-offcanvas-color: #343a40;--bs-offcanvas-bg: #fff;--bs-offcanvas-border-width: 1px;--bs-offcanvas-border-color: rgba(0, 0, 0, 0.175);--bs-offcanvas-box-shadow: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.075);--bs-offcanvas-transition: transform 0.3s ease-in-out;--bs-offcanvas-title-line-height: 1.5}@media(max-width: 575.98px){.offcanvas-sm{position:fixed;bottom:0;z-index:var(--bs-offcanvas-zindex);display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;max-width:100%;color:var(--bs-offcanvas-color);visibility:hidden;background-color:var(--bs-offcanvas-bg);background-clip:padding-box;outline:0;transition:var(--bs-offcanvas-transition)}}@media(max-width: 575.98px)and (prefers-reduced-motion: reduce){.offcanvas-sm{transition:none}}@media(max-width: 575.98px){.offcanvas-sm.offcanvas-start{top:0;left:0;width:var(--bs-offcanvas-width);border-right:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(-100%)}.offcanvas-sm.offcanvas-end{top:0;right:0;width:var(--bs-offcanvas-width);border-left:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(100%)}.offcanvas-sm.offcanvas-top{top:0;right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-bottom:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(-100%)}.offcanvas-sm.offcanvas-bottom{right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-top:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(100%)}.offcanvas-sm.showing,.offcanvas-sm.show:not(.hiding){transform:none}.offcanvas-sm.showing,.offcanvas-sm.hiding,.offcanvas-sm.show{visibility:visible}}@media(min-width: 576px){.offcanvas-sm{--bs-offcanvas-height: auto;--bs-offcanvas-border-width: 0;background-color:rgba(0,0,0,0) !important}.offcanvas-sm .offcanvas-header{display:none}.offcanvas-sm .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible;background-color:rgba(0,0,0,0) !important}}@media(max-width: 767.98px){.offcanvas-md{position:fixed;bottom:0;z-index:var(--bs-offcanvas-zindex);display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;max-width:100%;color:var(--bs-offcanvas-color);visibility:hidden;background-color:var(--bs-offcanvas-bg);background-clip:padding-box;outline:0;transition:var(--bs-offcanvas-transition)}}@media(max-width: 767.98px)and (prefers-reduced-motion: reduce){.offcanvas-md{transition:none}}@media(max-width: 767.98px){.offcanvas-md.offcanvas-start{top:0;left:0;width:var(--bs-offcanvas-width);border-right:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(-100%)}.offcanvas-md.offcanvas-end{top:0;right:0;width:var(--bs-offcanvas-width);border-left:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(100%)}.offcanvas-md.offcanvas-top{top:0;right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-bottom:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(-100%)}.offcanvas-md.offcanvas-bottom{right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-top:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(100%)}.offcanvas-md.showing,.offcanvas-md.show:not(.hiding){transform:none}.offcanvas-md.showing,.offcanvas-md.hiding,.offcanvas-md.show{visibility:visible}}@media(min-width: 768px){.offcanvas-md{--bs-offcanvas-height: auto;--bs-offcanvas-border-width: 0;background-color:rgba(0,0,0,0) !important}.offcanvas-md .offcanvas-header{display:none}.offcanvas-md .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible;background-color:rgba(0,0,0,0) !important}}@media(max-width: 991.98px){.offcanvas-lg{position:fixed;bottom:0;z-index:var(--bs-offcanvas-zindex);display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;max-width:100%;color:var(--bs-offcanvas-color);visibility:hidden;background-color:var(--bs-offcanvas-bg);background-clip:padding-box;outline:0;transition:var(--bs-offcanvas-transition)}}@media(max-width: 991.98px)and (prefers-reduced-motion: reduce){.offcanvas-lg{transition:none}}@media(max-width: 991.98px){.offcanvas-lg.offcanvas-start{top:0;left:0;width:var(--bs-offcanvas-width);border-right:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(-100%)}.offcanvas-lg.offcanvas-end{top:0;right:0;width:var(--bs-offcanvas-width);border-left:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(100%)}.offcanvas-lg.offcanvas-top{top:0;right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-bottom:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(-100%)}.offcanvas-lg.offcanvas-bottom{right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-top:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(100%)}.offcanvas-lg.showing,.offcanvas-lg.show:not(.hiding){transform:none}.offcanvas-lg.showing,.offcanvas-lg.hiding,.offcanvas-lg.show{visibility:visible}}@media(min-width: 992px){.offcanvas-lg{--bs-offcanvas-height: auto;--bs-offcanvas-border-width: 0;background-color:rgba(0,0,0,0) !important}.offcanvas-lg .offcanvas-header{display:none}.offcanvas-lg .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible;background-color:rgba(0,0,0,0) !important}}@media(max-width: 1199.98px){.offcanvas-xl{position:fixed;bottom:0;z-index:var(--bs-offcanvas-zindex);display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;max-width:100%;color:var(--bs-offcanvas-color);visibility:hidden;background-color:var(--bs-offcanvas-bg);background-clip:padding-box;outline:0;transition:var(--bs-offcanvas-transition)}}@media(max-width: 1199.98px)and (prefers-reduced-motion: reduce){.offcanvas-xl{transition:none}}@media(max-width: 1199.98px){.offcanvas-xl.offcanvas-start{top:0;left:0;width:var(--bs-offcanvas-width);border-right:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(-100%)}.offcanvas-xl.offcanvas-end{top:0;right:0;width:var(--bs-offcanvas-width);border-left:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(100%)}.offcanvas-xl.offcanvas-top{top:0;right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-bottom:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(-100%)}.offcanvas-xl.offcanvas-bottom{right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-top:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(100%)}.offcanvas-xl.showing,.offcanvas-xl.show:not(.hiding){transform:none}.offcanvas-xl.showing,.offcanvas-xl.hiding,.offcanvas-xl.show{visibility:visible}}@media(min-width: 1200px){.offcanvas-xl{--bs-offcanvas-height: auto;--bs-offcanvas-border-width: 0;background-color:rgba(0,0,0,0) !important}.offcanvas-xl .offcanvas-header{display:none}.offcanvas-xl .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible;background-color:rgba(0,0,0,0) !important}}@media(max-width: 1399.98px){.offcanvas-xxl{position:fixed;bottom:0;z-index:var(--bs-offcanvas-zindex);display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;max-width:100%;color:var(--bs-offcanvas-color);visibility:hidden;background-color:var(--bs-offcanvas-bg);background-clip:padding-box;outline:0;transition:var(--bs-offcanvas-transition)}}@media(max-width: 1399.98px)and (prefers-reduced-motion: reduce){.offcanvas-xxl{transition:none}}@media(max-width: 1399.98px){.offcanvas-xxl.offcanvas-start{top:0;left:0;width:var(--bs-offcanvas-width);border-right:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(-100%)}.offcanvas-xxl.offcanvas-end{top:0;right:0;width:var(--bs-offcanvas-width);border-left:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(100%)}.offcanvas-xxl.offcanvas-top{top:0;right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-bottom:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(-100%)}.offcanvas-xxl.offcanvas-bottom{right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-top:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(100%)}.offcanvas-xxl.showing,.offcanvas-xxl.show:not(.hiding){transform:none}.offcanvas-xxl.showing,.offcanvas-xxl.hiding,.offcanvas-xxl.show{visibility:visible}}@media(min-width: 1400px){.offcanvas-xxl{--bs-offcanvas-height: auto;--bs-offcanvas-border-width: 0;background-color:rgba(0,0,0,0) !important}.offcanvas-xxl .offcanvas-header{display:none}.offcanvas-xxl .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible;background-color:rgba(0,0,0,0) !important}}.offcanvas{position:fixed;bottom:0;z-index:var(--bs-offcanvas-zindex);display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;max-width:100%;color:var(--bs-offcanvas-color);visibility:hidden;background-color:var(--bs-offcanvas-bg);background-clip:padding-box;outline:0;transition:var(--bs-offcanvas-transition)}@media(prefers-reduced-motion: reduce){.offcanvas{transition:none}}.offcanvas.offcanvas-start{top:0;left:0;width:var(--bs-offcanvas-width);border-right:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(-100%)}.offcanvas.offcanvas-end{top:0;right:0;width:var(--bs-offcanvas-width);border-left:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(100%)}.offcanvas.offcanvas-top{top:0;right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-bottom:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(-100%)}.offcanvas.offcanvas-bottom{right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-top:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(100%)}.offcanvas.showing,.offcanvas.show:not(.hiding){transform:none}.offcanvas.showing,.offcanvas.hiding,.offcanvas.show{visibility:visible}.offcanvas-backdrop{position:fixed;top:0;left:0;z-index:1040;width:100vw;height:100vh;background-color:#000}.offcanvas-backdrop.fade{opacity:0}.offcanvas-backdrop.show{opacity:.5}.offcanvas-header{display:flex;display:-webkit-flex;align-items:center;-webkit-align-items:center;justify-content:space-between;-webkit-justify-content:space-between;padding:var(--bs-offcanvas-padding-y) var(--bs-offcanvas-padding-x)}.offcanvas-header .btn-close{padding:calc(var(--bs-offcanvas-padding-y)*.5) calc(var(--bs-offcanvas-padding-x)*.5);margin-top:calc(-0.5*var(--bs-offcanvas-padding-y));margin-right:calc(-0.5*var(--bs-offcanvas-padding-x));margin-bottom:calc(-0.5*var(--bs-offcanvas-padding-y))}.offcanvas-title{margin-bottom:0;line-height:var(--bs-offcanvas-title-line-height)}.offcanvas-body{flex-grow:1;-webkit-flex-grow:1;padding:var(--bs-offcanvas-padding-y) var(--bs-offcanvas-padding-x);overflow-y:auto}.placeholder{display:inline-block;min-height:1em;vertical-align:middle;cursor:wait;background-color:currentcolor;opacity:.5}.placeholder.btn::before{display:inline-block;content:""}.placeholder-xs{min-height:.6em}.placeholder-sm{min-height:.8em}.placeholder-lg{min-height:1.2em}.placeholder-glow .placeholder{animation:placeholder-glow 2s ease-in-out infinite}@keyframes placeholder-glow{50%{opacity:.2}}.placeholder-wave{mask-image:linear-gradient(130deg, #000 55%, rgba(0, 0, 0, 0.8) 75%, #000 95%);-webkit-mask-image:linear-gradient(130deg, #000 55%, rgba(0, 0, 0, 0.8) 75%, #000 95%);mask-size:200% 100%;-webkit-mask-size:200% 100%;animation:placeholder-wave 2s linear infinite}@keyframes placeholder-wave{100%{mask-position:-200% 0%;-webkit-mask-position:-200% 0%}}.clearfix::after{display:block;clear:both;content:""}.text-bg-default{color:#fff !important;background-color:RGBA(var(--bs-default-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-primary{color:#fff !important;background-color:RGBA(var(--bs-primary-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-secondary{color:#fff !important;background-color:RGBA(var(--bs-secondary-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-success{color:#fff !important;background-color:RGBA(var(--bs-success-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-info{color:#fff !important;background-color:RGBA(var(--bs-info-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-warning{color:#fff !important;background-color:RGBA(var(--bs-warning-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-danger{color:#fff !important;background-color:RGBA(var(--bs-danger-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-light{color:#000 !important;background-color:RGBA(var(--bs-light-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-dark{color:#fff !important;background-color:RGBA(var(--bs-dark-rgb), var(--bs-bg-opacity, 1)) !important}.link-default{color:RGBA(var(--bs-default-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-default-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-default:hover,.link-default:focus{color:RGBA(42, 46, 51, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(42, 46, 51, var(--bs-link-underline-opacity, 1)) !important}.link-primary{color:RGBA(var(--bs-primary-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-primary-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-primary:hover,.link-primary:focus{color:RGBA(31, 102, 182, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(31, 102, 182, var(--bs-link-underline-opacity, 1)) !important}.link-secondary{color:RGBA(var(--bs-secondary-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-secondary-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-secondary:hover,.link-secondary:focus{color:RGBA(42, 46, 51, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(42, 46, 51, var(--bs-link-underline-opacity, 1)) !important}.link-success{color:RGBA(var(--bs-success-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-success-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-success:hover,.link-success:focus{color:RGBA(50, 146, 19, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(50, 146, 19, var(--bs-link-underline-opacity, 1)) !important}.link-info{color:RGBA(var(--bs-info-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-info-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-info:hover,.link-info:focus{color:RGBA(122, 67, 150, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(122, 67, 150, var(--bs-link-underline-opacity, 1)) !important}.link-warning{color:RGBA(var(--bs-warning-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-warning-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-warning:hover,.link-warning:focus{color:RGBA(204, 94, 19, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(204, 94, 19, var(--bs-link-underline-opacity, 1)) !important}.link-danger{color:RGBA(var(--bs-danger-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-danger-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-danger:hover,.link-danger:focus{color:RGBA(204, 0, 46, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(204, 0, 46, var(--bs-link-underline-opacity, 1)) !important}.link-light{color:RGBA(var(--bs-light-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-light-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-light:hover,.link-light:focus{color:RGBA(249, 250, 251, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(249, 250, 251, var(--bs-link-underline-opacity, 1)) !important}.link-dark{color:RGBA(var(--bs-dark-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-dark-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-dark:hover,.link-dark:focus{color:RGBA(42, 46, 51, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(42, 46, 51, var(--bs-link-underline-opacity, 1)) !important}.link-body-emphasis{color:RGBA(var(--bs-emphasis-color-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-emphasis-color-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-body-emphasis:hover,.link-body-emphasis:focus{color:RGBA(var(--bs-emphasis-color-rgb), var(--bs-link-opacity, 0.75)) !important;text-decoration-color:RGBA(var(--bs-emphasis-color-rgb), var(--bs-link-underline-opacity, 0.75)) !important}.focus-ring:focus{outline:0;box-shadow:var(--bs-focus-ring-x, 0) var(--bs-focus-ring-y, 0) var(--bs-focus-ring-blur, 0) var(--bs-focus-ring-width) var(--bs-focus-ring-color)}.icon-link{display:inline-flex;gap:.375rem;align-items:center;-webkit-align-items:center;text-decoration-color:rgba(var(--bs-link-color-rgb), var(--bs-link-opacity, 0.5));text-underline-offset:.25em;backface-visibility:hidden;-webkit-backface-visibility:hidden;-moz-backface-visibility:hidden;-ms-backface-visibility:hidden;-o-backface-visibility:hidden}.icon-link>.bi{flex-shrink:0;-webkit-flex-shrink:0;width:1em;height:1em;fill:currentcolor;transition:.2s ease-in-out transform}@media(prefers-reduced-motion: reduce){.icon-link>.bi{transition:none}}.icon-link-hover:hover>.bi,.icon-link-hover:focus-visible>.bi{transform:var(--bs-icon-link-transform, translate3d(0.25em, 0, 0))}.ratio{position:relative;width:100%}.ratio::before{display:block;padding-top:var(--bs-aspect-ratio);content:""}.ratio>*{position:absolute;top:0;left:0;width:100%;height:100%}.ratio-1x1{--bs-aspect-ratio: 100%}.ratio-4x3{--bs-aspect-ratio: 75%}.ratio-16x9{--bs-aspect-ratio: 56.25%}.ratio-21x9{--bs-aspect-ratio: 42.8571428571%}.fixed-top{position:fixed;top:0;right:0;left:0;z-index:1030}.fixed-bottom{position:fixed;right:0;bottom:0;left:0;z-index:1030}.sticky-top{position:sticky;top:0;z-index:1020}.sticky-bottom{position:sticky;bottom:0;z-index:1020}@media(min-width: 576px){.sticky-sm-top{position:sticky;top:0;z-index:1020}.sticky-sm-bottom{position:sticky;bottom:0;z-index:1020}}@media(min-width: 768px){.sticky-md-top{position:sticky;top:0;z-index:1020}.sticky-md-bottom{position:sticky;bottom:0;z-index:1020}}@media(min-width: 992px){.sticky-lg-top{position:sticky;top:0;z-index:1020}.sticky-lg-bottom{position:sticky;bottom:0;z-index:1020}}@media(min-width: 1200px){.sticky-xl-top{position:sticky;top:0;z-index:1020}.sticky-xl-bottom{position:sticky;bottom:0;z-index:1020}}@media(min-width: 1400px){.sticky-xxl-top{position:sticky;top:0;z-index:1020}.sticky-xxl-bottom{position:sticky;bottom:0;z-index:1020}}.hstack{display:flex;display:-webkit-flex;flex-direction:row;-webkit-flex-direction:row;align-items:center;-webkit-align-items:center;align-self:stretch;-webkit-align-self:stretch}.vstack{display:flex;display:-webkit-flex;flex:1 1 auto;-webkit-flex:1 1 auto;flex-direction:column;-webkit-flex-direction:column;align-self:stretch;-webkit-align-self:stretch}.visually-hidden,.visually-hidden-focusable:not(:focus):not(:focus-within){width:1px !important;height:1px !important;padding:0 !important;margin:-1px !important;overflow:hidden !important;clip:rect(0, 0, 0, 0) !important;white-space:nowrap !important;border:0 !important}.visually-hidden:not(caption),.visually-hidden-focusable:not(:focus):not(:focus-within):not(caption){position:absolute !important}.stretched-link::after{position:absolute;top:0;right:0;bottom:0;left:0;z-index:1;content:""}.text-truncate{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.vr{display:inline-block;align-self:stretch;-webkit-align-self:stretch;width:1px;min-height:1em;background-color:currentcolor;opacity:.25}.align-baseline{vertical-align:baseline !important}.align-top{vertical-align:top !important}.align-middle{vertical-align:middle !important}.align-bottom{vertical-align:bottom !important}.align-text-bottom{vertical-align:text-bottom !important}.align-text-top{vertical-align:text-top !important}.float-start{float:left !important}.float-end{float:right !important}.float-none{float:none !important}.object-fit-contain{object-fit:contain !important}.object-fit-cover{object-fit:cover !important}.object-fit-fill{object-fit:fill !important}.object-fit-scale{object-fit:scale-down !important}.object-fit-none{object-fit:none !important}.opacity-0{opacity:0 !important}.opacity-25{opacity:.25 !important}.opacity-50{opacity:.5 !important}.opacity-75{opacity:.75 !important}.opacity-100{opacity:1 !important}.overflow-auto{overflow:auto !important}.overflow-hidden{overflow:hidden !important}.overflow-visible{overflow:visible !important}.overflow-scroll{overflow:scroll !important}.overflow-x-auto{overflow-x:auto !important}.overflow-x-hidden{overflow-x:hidden !important}.overflow-x-visible{overflow-x:visible !important}.overflow-x-scroll{overflow-x:scroll !important}.overflow-y-auto{overflow-y:auto !important}.overflow-y-hidden{overflow-y:hidden !important}.overflow-y-visible{overflow-y:visible !important}.overflow-y-scroll{overflow-y:scroll !important}.d-inline{display:inline !important}.d-inline-block{display:inline-block !important}.d-block{display:block !important}.d-grid{display:grid !important}.d-inline-grid{display:inline-grid !important}.d-table{display:table !important}.d-table-row{display:table-row !important}.d-table-cell{display:table-cell !important}.d-flex{display:flex !important}.d-inline-flex{display:inline-flex !important}.d-none{display:none !important}.shadow{box-shadow:0 .5rem 1rem rgba(0,0,0,.15) !important}.shadow-sm{box-shadow:0 .125rem .25rem rgba(0,0,0,.075) !important}.shadow-lg{box-shadow:0 1rem 3rem rgba(0,0,0,.175) !important}.shadow-none{box-shadow:none !important}.focus-ring-default{--bs-focus-ring-color: rgba(var(--bs-default-rgb), var(--bs-focus-ring-opacity))}.focus-ring-primary{--bs-focus-ring-color: rgba(var(--bs-primary-rgb), var(--bs-focus-ring-opacity))}.focus-ring-secondary{--bs-focus-ring-color: rgba(var(--bs-secondary-rgb), var(--bs-focus-ring-opacity))}.focus-ring-success{--bs-focus-ring-color: rgba(var(--bs-success-rgb), var(--bs-focus-ring-opacity))}.focus-ring-info{--bs-focus-ring-color: rgba(var(--bs-info-rgb), var(--bs-focus-ring-opacity))}.focus-ring-warning{--bs-focus-ring-color: rgba(var(--bs-warning-rgb), var(--bs-focus-ring-opacity))}.focus-ring-danger{--bs-focus-ring-color: rgba(var(--bs-danger-rgb), var(--bs-focus-ring-opacity))}.focus-ring-light{--bs-focus-ring-color: rgba(var(--bs-light-rgb), var(--bs-focus-ring-opacity))}.focus-ring-dark{--bs-focus-ring-color: rgba(var(--bs-dark-rgb), var(--bs-focus-ring-opacity))}.position-static{position:static !important}.position-relative{position:relative !important}.position-absolute{position:absolute !important}.position-fixed{position:fixed !important}.position-sticky{position:sticky !important}.top-0{top:0 !important}.top-50{top:50% !important}.top-100{top:100% !important}.bottom-0{bottom:0 !important}.bottom-50{bottom:50% !important}.bottom-100{bottom:100% !important}.start-0{left:0 !important}.start-50{left:50% !important}.start-100{left:100% !important}.end-0{right:0 !important}.end-50{right:50% !important}.end-100{right:100% !important}.translate-middle{transform:translate(-50%, -50%) !important}.translate-middle-x{transform:translateX(-50%) !important}.translate-middle-y{transform:translateY(-50%) !important}.border{border:var(--bs-border-width) var(--bs-border-style) var(--bs-border-color) !important}.border-0{border:0 !important}.border-top{border-top:var(--bs-border-width) var(--bs-border-style) var(--bs-border-color) !important}.border-top-0{border-top:0 !important}.border-end{border-right:var(--bs-border-width) var(--bs-border-style) var(--bs-border-color) !important}.border-end-0{border-right:0 !important}.border-bottom{border-bottom:var(--bs-border-width) var(--bs-border-style) var(--bs-border-color) !important}.border-bottom-0{border-bottom:0 !important}.border-start{border-left:var(--bs-border-width) var(--bs-border-style) var(--bs-border-color) !important}.border-start-0{border-left:0 !important}.border-default{--bs-border-opacity: 1;border-color:rgba(var(--bs-default-rgb), var(--bs-border-opacity)) !important}.border-primary{--bs-border-opacity: 1;border-color:rgba(var(--bs-primary-rgb), var(--bs-border-opacity)) !important}.border-secondary{--bs-border-opacity: 1;border-color:rgba(var(--bs-secondary-rgb), var(--bs-border-opacity)) !important}.border-success{--bs-border-opacity: 1;border-color:rgba(var(--bs-success-rgb), var(--bs-border-opacity)) !important}.border-info{--bs-border-opacity: 1;border-color:rgba(var(--bs-info-rgb), var(--bs-border-opacity)) !important}.border-warning{--bs-border-opacity: 1;border-color:rgba(var(--bs-warning-rgb), var(--bs-border-opacity)) !important}.border-danger{--bs-border-opacity: 1;border-color:rgba(var(--bs-danger-rgb), var(--bs-border-opacity)) !important}.border-light{--bs-border-opacity: 1;border-color:rgba(var(--bs-light-rgb), var(--bs-border-opacity)) !important}.border-dark{--bs-border-opacity: 1;border-color:rgba(var(--bs-dark-rgb), var(--bs-border-opacity)) !important}.border-black{--bs-border-opacity: 1;border-color:rgba(var(--bs-black-rgb), var(--bs-border-opacity)) !important}.border-white{--bs-border-opacity: 1;border-color:rgba(var(--bs-white-rgb), var(--bs-border-opacity)) !important}.border-primary-subtle{border-color:var(--bs-primary-border-subtle) !important}.border-secondary-subtle{border-color:var(--bs-secondary-border-subtle) !important}.border-success-subtle{border-color:var(--bs-success-border-subtle) !important}.border-info-subtle{border-color:var(--bs-info-border-subtle) !important}.border-warning-subtle{border-color:var(--bs-warning-border-subtle) !important}.border-danger-subtle{border-color:var(--bs-danger-border-subtle) !important}.border-light-subtle{border-color:var(--bs-light-border-subtle) !important}.border-dark-subtle{border-color:var(--bs-dark-border-subtle) !important}.border-1{border-width:1px !important}.border-2{border-width:2px !important}.border-3{border-width:3px !important}.border-4{border-width:4px !important}.border-5{border-width:5px !important}.border-opacity-10{--bs-border-opacity: 0.1}.border-opacity-25{--bs-border-opacity: 0.25}.border-opacity-50{--bs-border-opacity: 0.5}.border-opacity-75{--bs-border-opacity: 0.75}.border-opacity-100{--bs-border-opacity: 1}.w-25{width:25% !important}.w-50{width:50% !important}.w-75{width:75% !important}.w-100{width:100% !important}.w-auto{width:auto !important}.mw-100{max-width:100% !important}.vw-100{width:100vw !important}.min-vw-100{min-width:100vw !important}.h-25{height:25% !important}.h-50{height:50% !important}.h-75{height:75% !important}.h-100{height:100% !important}.h-auto{height:auto !important}.mh-100{max-height:100% !important}.vh-100{height:100vh !important}.min-vh-100{min-height:100vh !important}.flex-fill{flex:1 1 auto !important}.flex-row{flex-direction:row !important}.flex-column{flex-direction:column !important}.flex-row-reverse{flex-direction:row-reverse !important}.flex-column-reverse{flex-direction:column-reverse !important}.flex-grow-0{flex-grow:0 !important}.flex-grow-1{flex-grow:1 !important}.flex-shrink-0{flex-shrink:0 !important}.flex-shrink-1{flex-shrink:1 !important}.flex-wrap{flex-wrap:wrap !important}.flex-nowrap{flex-wrap:nowrap !important}.flex-wrap-reverse{flex-wrap:wrap-reverse !important}.justify-content-start{justify-content:flex-start !important}.justify-content-end{justify-content:flex-end !important}.justify-content-center{justify-content:center !important}.justify-content-between{justify-content:space-between !important}.justify-content-around{justify-content:space-around !important}.justify-content-evenly{justify-content:space-evenly !important}.align-items-start{align-items:flex-start !important}.align-items-end{align-items:flex-end !important}.align-items-center{align-items:center !important}.align-items-baseline{align-items:baseline !important}.align-items-stretch{align-items:stretch !important}.align-content-start{align-content:flex-start !important}.align-content-end{align-content:flex-end !important}.align-content-center{align-content:center !important}.align-content-between{align-content:space-between !important}.align-content-around{align-content:space-around !important}.align-content-stretch{align-content:stretch !important}.align-self-auto{align-self:auto !important}.align-self-start{align-self:flex-start !important}.align-self-end{align-self:flex-end !important}.align-self-center{align-self:center !important}.align-self-baseline{align-self:baseline !important}.align-self-stretch{align-self:stretch !important}.order-first{order:-1 !important}.order-0{order:0 !important}.order-1{order:1 !important}.order-2{order:2 !important}.order-3{order:3 !important}.order-4{order:4 !important}.order-5{order:5 !important}.order-last{order:6 !important}.m-0{margin:0 !important}.m-1{margin:.25rem !important}.m-2{margin:.5rem !important}.m-3{margin:1rem !important}.m-4{margin:1.5rem !important}.m-5{margin:3rem !important}.m-auto{margin:auto !important}.mx-0{margin-right:0 !important;margin-left:0 !important}.mx-1{margin-right:.25rem !important;margin-left:.25rem !important}.mx-2{margin-right:.5rem !important;margin-left:.5rem !important}.mx-3{margin-right:1rem !important;margin-left:1rem !important}.mx-4{margin-right:1.5rem !important;margin-left:1.5rem !important}.mx-5{margin-right:3rem !important;margin-left:3rem !important}.mx-auto{margin-right:auto !important;margin-left:auto !important}.my-0{margin-top:0 !important;margin-bottom:0 !important}.my-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.my-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.my-3{margin-top:1rem !important;margin-bottom:1rem !important}.my-4{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.my-5{margin-top:3rem !important;margin-bottom:3rem !important}.my-auto{margin-top:auto !important;margin-bottom:auto !important}.mt-0{margin-top:0 !important}.mt-1{margin-top:.25rem !important}.mt-2{margin-top:.5rem !important}.mt-3{margin-top:1rem !important}.mt-4{margin-top:1.5rem !important}.mt-5{margin-top:3rem !important}.mt-auto{margin-top:auto !important}.me-0{margin-right:0 !important}.me-1{margin-right:.25rem !important}.me-2{margin-right:.5rem !important}.me-3{margin-right:1rem !important}.me-4{margin-right:1.5rem !important}.me-5{margin-right:3rem !important}.me-auto{margin-right:auto !important}.mb-0{margin-bottom:0 !important}.mb-1{margin-bottom:.25rem !important}.mb-2{margin-bottom:.5rem !important}.mb-3{margin-bottom:1rem !important}.mb-4{margin-bottom:1.5rem !important}.mb-5{margin-bottom:3rem !important}.mb-auto{margin-bottom:auto !important}.ms-0{margin-left:0 !important}.ms-1{margin-left:.25rem !important}.ms-2{margin-left:.5rem !important}.ms-3{margin-left:1rem !important}.ms-4{margin-left:1.5rem !important}.ms-5{margin-left:3rem !important}.ms-auto{margin-left:auto !important}.p-0{padding:0 !important}.p-1{padding:.25rem !important}.p-2{padding:.5rem !important}.p-3{padding:1rem !important}.p-4{padding:1.5rem !important}.p-5{padding:3rem !important}.px-0{padding-right:0 !important;padding-left:0 !important}.px-1{padding-right:.25rem !important;padding-left:.25rem !important}.px-2{padding-right:.5rem !important;padding-left:.5rem !important}.px-3{padding-right:1rem !important;padding-left:1rem !important}.px-4{padding-right:1.5rem !important;padding-left:1.5rem !important}.px-5{padding-right:3rem !important;padding-left:3rem !important}.py-0{padding-top:0 !important;padding-bottom:0 !important}.py-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.py-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.py-3{padding-top:1rem !important;padding-bottom:1rem !important}.py-4{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.py-5{padding-top:3rem !important;padding-bottom:3rem !important}.pt-0{padding-top:0 !important}.pt-1{padding-top:.25rem !important}.pt-2{padding-top:.5rem !important}.pt-3{padding-top:1rem !important}.pt-4{padding-top:1.5rem !important}.pt-5{padding-top:3rem !important}.pe-0{padding-right:0 !important}.pe-1{padding-right:.25rem !important}.pe-2{padding-right:.5rem !important}.pe-3{padding-right:1rem !important}.pe-4{padding-right:1.5rem !important}.pe-5{padding-right:3rem !important}.pb-0{padding-bottom:0 !important}.pb-1{padding-bottom:.25rem !important}.pb-2{padding-bottom:.5rem !important}.pb-3{padding-bottom:1rem !important}.pb-4{padding-bottom:1.5rem !important}.pb-5{padding-bottom:3rem !important}.ps-0{padding-left:0 !important}.ps-1{padding-left:.25rem !important}.ps-2{padding-left:.5rem !important}.ps-3{padding-left:1rem !important}.ps-4{padding-left:1.5rem !important}.ps-5{padding-left:3rem !important}.gap-0{gap:0 !important}.gap-1{gap:.25rem !important}.gap-2{gap:.5rem !important}.gap-3{gap:1rem !important}.gap-4{gap:1.5rem !important}.gap-5{gap:3rem !important}.row-gap-0{row-gap:0 !important}.row-gap-1{row-gap:.25rem !important}.row-gap-2{row-gap:.5rem !important}.row-gap-3{row-gap:1rem !important}.row-gap-4{row-gap:1.5rem !important}.row-gap-5{row-gap:3rem !important}.column-gap-0{column-gap:0 !important}.column-gap-1{column-gap:.25rem !important}.column-gap-2{column-gap:.5rem !important}.column-gap-3{column-gap:1rem !important}.column-gap-4{column-gap:1.5rem !important}.column-gap-5{column-gap:3rem !important}.font-monospace{font-family:var(--bs-font-monospace) !important}.fs-1{font-size:calc(1.325rem + 0.9vw) !important}.fs-2{font-size:calc(1.29rem + 0.48vw) !important}.fs-3{font-size:calc(1.27rem + 0.24vw) !important}.fs-4{font-size:1.25rem !important}.fs-5{font-size:1.1rem !important}.fs-6{font-size:1rem !important}.fst-italic{font-style:italic !important}.fst-normal{font-style:normal !important}.fw-lighter{font-weight:lighter !important}.fw-light{font-weight:300 !important}.fw-normal{font-weight:400 !important}.fw-medium{font-weight:500 !important}.fw-semibold{font-weight:600 !important}.fw-bold{font-weight:700 !important}.fw-bolder{font-weight:bolder !important}.lh-1{line-height:1 !important}.lh-sm{line-height:1.25 !important}.lh-base{line-height:1.5 !important}.lh-lg{line-height:2 !important}.text-start{text-align:left !important}.text-end{text-align:right !important}.text-center{text-align:center !important}.text-decoration-none{text-decoration:none !important}.text-decoration-underline{text-decoration:underline !important}.text-decoration-line-through{text-decoration:line-through !important}.text-lowercase{text-transform:lowercase !important}.text-uppercase{text-transform:uppercase !important}.text-capitalize{text-transform:capitalize !important}.text-wrap{white-space:normal !important}.text-nowrap{white-space:nowrap !important}.text-break{word-wrap:break-word !important;word-break:break-word !important}.text-default{--bs-text-opacity: 1;color:rgba(var(--bs-default-rgb), var(--bs-text-opacity)) !important}.text-primary{--bs-text-opacity: 1;color:rgba(var(--bs-primary-rgb), var(--bs-text-opacity)) !important}.text-secondary{--bs-text-opacity: 1;color:rgba(var(--bs-secondary-rgb), var(--bs-text-opacity)) !important}.text-success{--bs-text-opacity: 1;color:rgba(var(--bs-success-rgb), var(--bs-text-opacity)) !important}.text-info{--bs-text-opacity: 1;color:rgba(var(--bs-info-rgb), var(--bs-text-opacity)) !important}.text-warning{--bs-text-opacity: 1;color:rgba(var(--bs-warning-rgb), var(--bs-text-opacity)) !important}.text-danger{--bs-text-opacity: 1;color:rgba(var(--bs-danger-rgb), var(--bs-text-opacity)) !important}.text-light{--bs-text-opacity: 1;color:rgba(var(--bs-light-rgb), var(--bs-text-opacity)) !important}.text-dark{--bs-text-opacity: 1;color:rgba(var(--bs-dark-rgb), var(--bs-text-opacity)) !important}.text-black{--bs-text-opacity: 1;color:rgba(var(--bs-black-rgb), var(--bs-text-opacity)) !important}.text-white{--bs-text-opacity: 1;color:rgba(var(--bs-white-rgb), var(--bs-text-opacity)) !important}.text-body{--bs-text-opacity: 1;color:rgba(var(--bs-body-color-rgb), var(--bs-text-opacity)) !important}.text-muted{--bs-text-opacity: 1;color:var(--bs-secondary-color) !important}.text-black-50{--bs-text-opacity: 1;color:rgba(0,0,0,.5) !important}.text-white-50{--bs-text-opacity: 1;color:rgba(255,255,255,.5) !important}.text-body-secondary{--bs-text-opacity: 1;color:var(--bs-secondary-color) !important}.text-body-tertiary{--bs-text-opacity: 1;color:var(--bs-tertiary-color) !important}.text-body-emphasis{--bs-text-opacity: 1;color:var(--bs-emphasis-color) !important}.text-reset{--bs-text-opacity: 1;color:inherit !important}.text-opacity-25{--bs-text-opacity: 0.25}.text-opacity-50{--bs-text-opacity: 0.5}.text-opacity-75{--bs-text-opacity: 0.75}.text-opacity-100{--bs-text-opacity: 1}.text-primary-emphasis{color:var(--bs-primary-text-emphasis) !important}.text-secondary-emphasis{color:var(--bs-secondary-text-emphasis) !important}.text-success-emphasis{color:var(--bs-success-text-emphasis) !important}.text-info-emphasis{color:var(--bs-info-text-emphasis) !important}.text-warning-emphasis{color:var(--bs-warning-text-emphasis) !important}.text-danger-emphasis{color:var(--bs-danger-text-emphasis) !important}.text-light-emphasis{color:var(--bs-light-text-emphasis) !important}.text-dark-emphasis{color:var(--bs-dark-text-emphasis) !important}.link-opacity-10{--bs-link-opacity: 0.1}.link-opacity-10-hover:hover{--bs-link-opacity: 0.1}.link-opacity-25{--bs-link-opacity: 0.25}.link-opacity-25-hover:hover{--bs-link-opacity: 0.25}.link-opacity-50{--bs-link-opacity: 0.5}.link-opacity-50-hover:hover{--bs-link-opacity: 0.5}.link-opacity-75{--bs-link-opacity: 0.75}.link-opacity-75-hover:hover{--bs-link-opacity: 0.75}.link-opacity-100{--bs-link-opacity: 1}.link-opacity-100-hover:hover{--bs-link-opacity: 1}.link-offset-1{text-underline-offset:.125em !important}.link-offset-1-hover:hover{text-underline-offset:.125em !important}.link-offset-2{text-underline-offset:.25em !important}.link-offset-2-hover:hover{text-underline-offset:.25em !important}.link-offset-3{text-underline-offset:.375em !important}.link-offset-3-hover:hover{text-underline-offset:.375em !important}.link-underline-default{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-default-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-primary{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-primary-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-secondary{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-secondary-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-success{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-success-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-info{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-info-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-warning{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-warning-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-danger{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-danger-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-light{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-light-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-dark{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-dark-rgb), var(--bs-link-underline-opacity)) !important}.link-underline{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-link-color-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-underline-opacity-0{--bs-link-underline-opacity: 0}.link-underline-opacity-0-hover:hover{--bs-link-underline-opacity: 0}.link-underline-opacity-10{--bs-link-underline-opacity: 0.1}.link-underline-opacity-10-hover:hover{--bs-link-underline-opacity: 0.1}.link-underline-opacity-25{--bs-link-underline-opacity: 0.25}.link-underline-opacity-25-hover:hover{--bs-link-underline-opacity: 0.25}.link-underline-opacity-50{--bs-link-underline-opacity: 0.5}.link-underline-opacity-50-hover:hover{--bs-link-underline-opacity: 0.5}.link-underline-opacity-75{--bs-link-underline-opacity: 0.75}.link-underline-opacity-75-hover:hover{--bs-link-underline-opacity: 0.75}.link-underline-opacity-100{--bs-link-underline-opacity: 1}.link-underline-opacity-100-hover:hover{--bs-link-underline-opacity: 1}.bg-default{--bs-bg-opacity: 1;background-color:rgba(var(--bs-default-rgb), var(--bs-bg-opacity)) !important}.bg-primary{--bs-bg-opacity: 1;background-color:rgba(var(--bs-primary-rgb), var(--bs-bg-opacity)) !important}.bg-secondary{--bs-bg-opacity: 1;background-color:rgba(var(--bs-secondary-rgb), var(--bs-bg-opacity)) !important}.bg-success{--bs-bg-opacity: 1;background-color:rgba(var(--bs-success-rgb), var(--bs-bg-opacity)) !important}.bg-info{--bs-bg-opacity: 1;background-color:rgba(var(--bs-info-rgb), var(--bs-bg-opacity)) !important}.bg-warning{--bs-bg-opacity: 1;background-color:rgba(var(--bs-warning-rgb), var(--bs-bg-opacity)) !important}.bg-danger{--bs-bg-opacity: 1;background-color:rgba(var(--bs-danger-rgb), var(--bs-bg-opacity)) !important}.bg-light{--bs-bg-opacity: 1;background-color:rgba(var(--bs-light-rgb), var(--bs-bg-opacity)) !important}.bg-dark{--bs-bg-opacity: 1;background-color:rgba(var(--bs-dark-rgb), var(--bs-bg-opacity)) !important}.bg-black{--bs-bg-opacity: 1;background-color:rgba(var(--bs-black-rgb), var(--bs-bg-opacity)) !important}.bg-white{--bs-bg-opacity: 1;background-color:rgba(var(--bs-white-rgb), var(--bs-bg-opacity)) !important}.bg-body{--bs-bg-opacity: 1;background-color:rgba(var(--bs-body-bg-rgb), var(--bs-bg-opacity)) !important}.bg-transparent{--bs-bg-opacity: 1;background-color:rgba(0,0,0,0) !important}.bg-body-secondary{--bs-bg-opacity: 1;background-color:rgba(var(--bs-secondary-bg-rgb), var(--bs-bg-opacity)) !important}.bg-body-tertiary{--bs-bg-opacity: 1;background-color:rgba(var(--bs-tertiary-bg-rgb), var(--bs-bg-opacity)) !important}.bg-opacity-10{--bs-bg-opacity: 0.1}.bg-opacity-25{--bs-bg-opacity: 0.25}.bg-opacity-50{--bs-bg-opacity: 0.5}.bg-opacity-75{--bs-bg-opacity: 0.75}.bg-opacity-100{--bs-bg-opacity: 1}.bg-primary-subtle{background-color:var(--bs-primary-bg-subtle) !important}.bg-secondary-subtle{background-color:var(--bs-secondary-bg-subtle) !important}.bg-success-subtle{background-color:var(--bs-success-bg-subtle) !important}.bg-info-subtle{background-color:var(--bs-info-bg-subtle) !important}.bg-warning-subtle{background-color:var(--bs-warning-bg-subtle) !important}.bg-danger-subtle{background-color:var(--bs-danger-bg-subtle) !important}.bg-light-subtle{background-color:var(--bs-light-bg-subtle) !important}.bg-dark-subtle{background-color:var(--bs-dark-bg-subtle) !important}.bg-gradient{background-image:var(--bs-gradient) !important}.user-select-all{user-select:all !important}.user-select-auto{user-select:auto !important}.user-select-none{user-select:none !important}.pe-none{pointer-events:none !important}.pe-auto{pointer-events:auto !important}.rounded{border-radius:var(--bs-border-radius) !important}.rounded-0{border-radius:0 !important}.rounded-1{border-radius:var(--bs-border-radius-sm) !important}.rounded-2{border-radius:var(--bs-border-radius) !important}.rounded-3{border-radius:var(--bs-border-radius-lg) !important}.rounded-4{border-radius:var(--bs-border-radius-xl) !important}.rounded-5{border-radius:var(--bs-border-radius-xxl) !important}.rounded-circle{border-radius:50% !important}.rounded-pill{border-radius:var(--bs-border-radius-pill) !important}.rounded-top{border-top-left-radius:var(--bs-border-radius) !important;border-top-right-radius:var(--bs-border-radius) !important}.rounded-top-0{border-top-left-radius:0 !important;border-top-right-radius:0 !important}.rounded-top-1{border-top-left-radius:var(--bs-border-radius-sm) !important;border-top-right-radius:var(--bs-border-radius-sm) !important}.rounded-top-2{border-top-left-radius:var(--bs-border-radius) !important;border-top-right-radius:var(--bs-border-radius) !important}.rounded-top-3{border-top-left-radius:var(--bs-border-radius-lg) !important;border-top-right-radius:var(--bs-border-radius-lg) !important}.rounded-top-4{border-top-left-radius:var(--bs-border-radius-xl) !important;border-top-right-radius:var(--bs-border-radius-xl) !important}.rounded-top-5{border-top-left-radius:var(--bs-border-radius-xxl) !important;border-top-right-radius:var(--bs-border-radius-xxl) !important}.rounded-top-circle{border-top-left-radius:50% !important;border-top-right-radius:50% !important}.rounded-top-pill{border-top-left-radius:var(--bs-border-radius-pill) !important;border-top-right-radius:var(--bs-border-radius-pill) !important}.rounded-end{border-top-right-radius:var(--bs-border-radius) !important;border-bottom-right-radius:var(--bs-border-radius) !important}.rounded-end-0{border-top-right-radius:0 !important;border-bottom-right-radius:0 !important}.rounded-end-1{border-top-right-radius:var(--bs-border-radius-sm) !important;border-bottom-right-radius:var(--bs-border-radius-sm) !important}.rounded-end-2{border-top-right-radius:var(--bs-border-radius) !important;border-bottom-right-radius:var(--bs-border-radius) !important}.rounded-end-3{border-top-right-radius:var(--bs-border-radius-lg) !important;border-bottom-right-radius:var(--bs-border-radius-lg) !important}.rounded-end-4{border-top-right-radius:var(--bs-border-radius-xl) !important;border-bottom-right-radius:var(--bs-border-radius-xl) !important}.rounded-end-5{border-top-right-radius:var(--bs-border-radius-xxl) !important;border-bottom-right-radius:var(--bs-border-radius-xxl) !important}.rounded-end-circle{border-top-right-radius:50% !important;border-bottom-right-radius:50% !important}.rounded-end-pill{border-top-right-radius:var(--bs-border-radius-pill) !important;border-bottom-right-radius:var(--bs-border-radius-pill) !important}.rounded-bottom{border-bottom-right-radius:var(--bs-border-radius) !important;border-bottom-left-radius:var(--bs-border-radius) !important}.rounded-bottom-0{border-bottom-right-radius:0 !important;border-bottom-left-radius:0 !important}.rounded-bottom-1{border-bottom-right-radius:var(--bs-border-radius-sm) !important;border-bottom-left-radius:var(--bs-border-radius-sm) !important}.rounded-bottom-2{border-bottom-right-radius:var(--bs-border-radius) !important;border-bottom-left-radius:var(--bs-border-radius) !important}.rounded-bottom-3{border-bottom-right-radius:var(--bs-border-radius-lg) !important;border-bottom-left-radius:var(--bs-border-radius-lg) !important}.rounded-bottom-4{border-bottom-right-radius:var(--bs-border-radius-xl) !important;border-bottom-left-radius:var(--bs-border-radius-xl) !important}.rounded-bottom-5{border-bottom-right-radius:var(--bs-border-radius-xxl) !important;border-bottom-left-radius:var(--bs-border-radius-xxl) !important}.rounded-bottom-circle{border-bottom-right-radius:50% !important;border-bottom-left-radius:50% !important}.rounded-bottom-pill{border-bottom-right-radius:var(--bs-border-radius-pill) !important;border-bottom-left-radius:var(--bs-border-radius-pill) !important}.rounded-start{border-bottom-left-radius:var(--bs-border-radius) !important;border-top-left-radius:var(--bs-border-radius) !important}.rounded-start-0{border-bottom-left-radius:0 !important;border-top-left-radius:0 !important}.rounded-start-1{border-bottom-left-radius:var(--bs-border-radius-sm) !important;border-top-left-radius:var(--bs-border-radius-sm) !important}.rounded-start-2{border-bottom-left-radius:var(--bs-border-radius) !important;border-top-left-radius:var(--bs-border-radius) !important}.rounded-start-3{border-bottom-left-radius:var(--bs-border-radius-lg) !important;border-top-left-radius:var(--bs-border-radius-lg) !important}.rounded-start-4{border-bottom-left-radius:var(--bs-border-radius-xl) !important;border-top-left-radius:var(--bs-border-radius-xl) !important}.rounded-start-5{border-bottom-left-radius:var(--bs-border-radius-xxl) !important;border-top-left-radius:var(--bs-border-radius-xxl) !important}.rounded-start-circle{border-bottom-left-radius:50% !important;border-top-left-radius:50% !important}.rounded-start-pill{border-bottom-left-radius:var(--bs-border-radius-pill) !important;border-top-left-radius:var(--bs-border-radius-pill) !important}.visible{visibility:visible !important}.invisible{visibility:hidden !important}.z-n1{z-index:-1 !important}.z-0{z-index:0 !important}.z-1{z-index:1 !important}.z-2{z-index:2 !important}.z-3{z-index:3 !important}@media(min-width: 576px){.float-sm-start{float:left !important}.float-sm-end{float:right !important}.float-sm-none{float:none !important}.object-fit-sm-contain{object-fit:contain !important}.object-fit-sm-cover{object-fit:cover !important}.object-fit-sm-fill{object-fit:fill !important}.object-fit-sm-scale{object-fit:scale-down !important}.object-fit-sm-none{object-fit:none !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-block{display:block !important}.d-sm-grid{display:grid !important}.d-sm-inline-grid{display:inline-grid !important}.d-sm-table{display:table !important}.d-sm-table-row{display:table-row !important}.d-sm-table-cell{display:table-cell !important}.d-sm-flex{display:flex !important}.d-sm-inline-flex{display:inline-flex !important}.d-sm-none{display:none !important}.flex-sm-fill{flex:1 1 auto !important}.flex-sm-row{flex-direction:row !important}.flex-sm-column{flex-direction:column !important}.flex-sm-row-reverse{flex-direction:row-reverse !important}.flex-sm-column-reverse{flex-direction:column-reverse !important}.flex-sm-grow-0{flex-grow:0 !important}.flex-sm-grow-1{flex-grow:1 !important}.flex-sm-shrink-0{flex-shrink:0 !important}.flex-sm-shrink-1{flex-shrink:1 !important}.flex-sm-wrap{flex-wrap:wrap !important}.flex-sm-nowrap{flex-wrap:nowrap !important}.flex-sm-wrap-reverse{flex-wrap:wrap-reverse !important}.justify-content-sm-start{justify-content:flex-start !important}.justify-content-sm-end{justify-content:flex-end !important}.justify-content-sm-center{justify-content:center !important}.justify-content-sm-between{justify-content:space-between !important}.justify-content-sm-around{justify-content:space-around !important}.justify-content-sm-evenly{justify-content:space-evenly !important}.align-items-sm-start{align-items:flex-start !important}.align-items-sm-end{align-items:flex-end !important}.align-items-sm-center{align-items:center !important}.align-items-sm-baseline{align-items:baseline !important}.align-items-sm-stretch{align-items:stretch !important}.align-content-sm-start{align-content:flex-start !important}.align-content-sm-end{align-content:flex-end !important}.align-content-sm-center{align-content:center !important}.align-content-sm-between{align-content:space-between !important}.align-content-sm-around{align-content:space-around !important}.align-content-sm-stretch{align-content:stretch !important}.align-self-sm-auto{align-self:auto !important}.align-self-sm-start{align-self:flex-start !important}.align-self-sm-end{align-self:flex-end !important}.align-self-sm-center{align-self:center !important}.align-self-sm-baseline{align-self:baseline !important}.align-self-sm-stretch{align-self:stretch !important}.order-sm-first{order:-1 !important}.order-sm-0{order:0 !important}.order-sm-1{order:1 !important}.order-sm-2{order:2 !important}.order-sm-3{order:3 !important}.order-sm-4{order:4 !important}.order-sm-5{order:5 !important}.order-sm-last{order:6 !important}.m-sm-0{margin:0 !important}.m-sm-1{margin:.25rem !important}.m-sm-2{margin:.5rem !important}.m-sm-3{margin:1rem !important}.m-sm-4{margin:1.5rem !important}.m-sm-5{margin:3rem !important}.m-sm-auto{margin:auto !important}.mx-sm-0{margin-right:0 !important;margin-left:0 !important}.mx-sm-1{margin-right:.25rem !important;margin-left:.25rem !important}.mx-sm-2{margin-right:.5rem !important;margin-left:.5rem !important}.mx-sm-3{margin-right:1rem !important;margin-left:1rem !important}.mx-sm-4{margin-right:1.5rem !important;margin-left:1.5rem !important}.mx-sm-5{margin-right:3rem !important;margin-left:3rem !important}.mx-sm-auto{margin-right:auto !important;margin-left:auto !important}.my-sm-0{margin-top:0 !important;margin-bottom:0 !important}.my-sm-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.my-sm-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.my-sm-3{margin-top:1rem !important;margin-bottom:1rem !important}.my-sm-4{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.my-sm-5{margin-top:3rem !important;margin-bottom:3rem !important}.my-sm-auto{margin-top:auto !important;margin-bottom:auto !important}.mt-sm-0{margin-top:0 !important}.mt-sm-1{margin-top:.25rem !important}.mt-sm-2{margin-top:.5rem !important}.mt-sm-3{margin-top:1rem !important}.mt-sm-4{margin-top:1.5rem !important}.mt-sm-5{margin-top:3rem !important}.mt-sm-auto{margin-top:auto !important}.me-sm-0{margin-right:0 !important}.me-sm-1{margin-right:.25rem !important}.me-sm-2{margin-right:.5rem !important}.me-sm-3{margin-right:1rem !important}.me-sm-4{margin-right:1.5rem !important}.me-sm-5{margin-right:3rem !important}.me-sm-auto{margin-right:auto !important}.mb-sm-0{margin-bottom:0 !important}.mb-sm-1{margin-bottom:.25rem !important}.mb-sm-2{margin-bottom:.5rem !important}.mb-sm-3{margin-bottom:1rem !important}.mb-sm-4{margin-bottom:1.5rem !important}.mb-sm-5{margin-bottom:3rem !important}.mb-sm-auto{margin-bottom:auto !important}.ms-sm-0{margin-left:0 !important}.ms-sm-1{margin-left:.25rem !important}.ms-sm-2{margin-left:.5rem !important}.ms-sm-3{margin-left:1rem !important}.ms-sm-4{margin-left:1.5rem !important}.ms-sm-5{margin-left:3rem !important}.ms-sm-auto{margin-left:auto !important}.p-sm-0{padding:0 !important}.p-sm-1{padding:.25rem !important}.p-sm-2{padding:.5rem !important}.p-sm-3{padding:1rem !important}.p-sm-4{padding:1.5rem !important}.p-sm-5{padding:3rem !important}.px-sm-0{padding-right:0 !important;padding-left:0 !important}.px-sm-1{padding-right:.25rem !important;padding-left:.25rem !important}.px-sm-2{padding-right:.5rem !important;padding-left:.5rem !important}.px-sm-3{padding-right:1rem !important;padding-left:1rem !important}.px-sm-4{padding-right:1.5rem !important;padding-left:1.5rem !important}.px-sm-5{padding-right:3rem !important;padding-left:3rem !important}.py-sm-0{padding-top:0 !important;padding-bottom:0 !important}.py-sm-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.py-sm-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.py-sm-3{padding-top:1rem !important;padding-bottom:1rem !important}.py-sm-4{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.py-sm-5{padding-top:3rem !important;padding-bottom:3rem !important}.pt-sm-0{padding-top:0 !important}.pt-sm-1{padding-top:.25rem !important}.pt-sm-2{padding-top:.5rem !important}.pt-sm-3{padding-top:1rem !important}.pt-sm-4{padding-top:1.5rem !important}.pt-sm-5{padding-top:3rem !important}.pe-sm-0{padding-right:0 !important}.pe-sm-1{padding-right:.25rem !important}.pe-sm-2{padding-right:.5rem !important}.pe-sm-3{padding-right:1rem !important}.pe-sm-4{padding-right:1.5rem !important}.pe-sm-5{padding-right:3rem !important}.pb-sm-0{padding-bottom:0 !important}.pb-sm-1{padding-bottom:.25rem !important}.pb-sm-2{padding-bottom:.5rem !important}.pb-sm-3{padding-bottom:1rem !important}.pb-sm-4{padding-bottom:1.5rem !important}.pb-sm-5{padding-bottom:3rem !important}.ps-sm-0{padding-left:0 !important}.ps-sm-1{padding-left:.25rem !important}.ps-sm-2{padding-left:.5rem !important}.ps-sm-3{padding-left:1rem !important}.ps-sm-4{padding-left:1.5rem !important}.ps-sm-5{padding-left:3rem !important}.gap-sm-0{gap:0 !important}.gap-sm-1{gap:.25rem !important}.gap-sm-2{gap:.5rem !important}.gap-sm-3{gap:1rem !important}.gap-sm-4{gap:1.5rem !important}.gap-sm-5{gap:3rem !important}.row-gap-sm-0{row-gap:0 !important}.row-gap-sm-1{row-gap:.25rem !important}.row-gap-sm-2{row-gap:.5rem !important}.row-gap-sm-3{row-gap:1rem !important}.row-gap-sm-4{row-gap:1.5rem !important}.row-gap-sm-5{row-gap:3rem !important}.column-gap-sm-0{column-gap:0 !important}.column-gap-sm-1{column-gap:.25rem !important}.column-gap-sm-2{column-gap:.5rem !important}.column-gap-sm-3{column-gap:1rem !important}.column-gap-sm-4{column-gap:1.5rem !important}.column-gap-sm-5{column-gap:3rem !important}.text-sm-start{text-align:left !important}.text-sm-end{text-align:right !important}.text-sm-center{text-align:center !important}}@media(min-width: 768px){.float-md-start{float:left !important}.float-md-end{float:right !important}.float-md-none{float:none !important}.object-fit-md-contain{object-fit:contain !important}.object-fit-md-cover{object-fit:cover !important}.object-fit-md-fill{object-fit:fill !important}.object-fit-md-scale{object-fit:scale-down !important}.object-fit-md-none{object-fit:none !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-block{display:block !important}.d-md-grid{display:grid !important}.d-md-inline-grid{display:inline-grid !important}.d-md-table{display:table !important}.d-md-table-row{display:table-row !important}.d-md-table-cell{display:table-cell !important}.d-md-flex{display:flex !important}.d-md-inline-flex{display:inline-flex !important}.d-md-none{display:none !important}.flex-md-fill{flex:1 1 auto !important}.flex-md-row{flex-direction:row !important}.flex-md-column{flex-direction:column !important}.flex-md-row-reverse{flex-direction:row-reverse !important}.flex-md-column-reverse{flex-direction:column-reverse !important}.flex-md-grow-0{flex-grow:0 !important}.flex-md-grow-1{flex-grow:1 !important}.flex-md-shrink-0{flex-shrink:0 !important}.flex-md-shrink-1{flex-shrink:1 !important}.flex-md-wrap{flex-wrap:wrap !important}.flex-md-nowrap{flex-wrap:nowrap !important}.flex-md-wrap-reverse{flex-wrap:wrap-reverse !important}.justify-content-md-start{justify-content:flex-start !important}.justify-content-md-end{justify-content:flex-end !important}.justify-content-md-center{justify-content:center !important}.justify-content-md-between{justify-content:space-between !important}.justify-content-md-around{justify-content:space-around !important}.justify-content-md-evenly{justify-content:space-evenly !important}.align-items-md-start{align-items:flex-start !important}.align-items-md-end{align-items:flex-end !important}.align-items-md-center{align-items:center !important}.align-items-md-baseline{align-items:baseline !important}.align-items-md-stretch{align-items:stretch !important}.align-content-md-start{align-content:flex-start !important}.align-content-md-end{align-content:flex-end !important}.align-content-md-center{align-content:center !important}.align-content-md-between{align-content:space-between !important}.align-content-md-around{align-content:space-around !important}.align-content-md-stretch{align-content:stretch !important}.align-self-md-auto{align-self:auto !important}.align-self-md-start{align-self:flex-start !important}.align-self-md-end{align-self:flex-end !important}.align-self-md-center{align-self:center !important}.align-self-md-baseline{align-self:baseline !important}.align-self-md-stretch{align-self:stretch !important}.order-md-first{order:-1 !important}.order-md-0{order:0 !important}.order-md-1{order:1 !important}.order-md-2{order:2 !important}.order-md-3{order:3 !important}.order-md-4{order:4 !important}.order-md-5{order:5 !important}.order-md-last{order:6 !important}.m-md-0{margin:0 !important}.m-md-1{margin:.25rem !important}.m-md-2{margin:.5rem !important}.m-md-3{margin:1rem !important}.m-md-4{margin:1.5rem !important}.m-md-5{margin:3rem !important}.m-md-auto{margin:auto !important}.mx-md-0{margin-right:0 !important;margin-left:0 !important}.mx-md-1{margin-right:.25rem !important;margin-left:.25rem !important}.mx-md-2{margin-right:.5rem !important;margin-left:.5rem !important}.mx-md-3{margin-right:1rem !important;margin-left:1rem !important}.mx-md-4{margin-right:1.5rem !important;margin-left:1.5rem !important}.mx-md-5{margin-right:3rem !important;margin-left:3rem !important}.mx-md-auto{margin-right:auto !important;margin-left:auto !important}.my-md-0{margin-top:0 !important;margin-bottom:0 !important}.my-md-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.my-md-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.my-md-3{margin-top:1rem !important;margin-bottom:1rem !important}.my-md-4{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.my-md-5{margin-top:3rem !important;margin-bottom:3rem !important}.my-md-auto{margin-top:auto !important;margin-bottom:auto !important}.mt-md-0{margin-top:0 !important}.mt-md-1{margin-top:.25rem !important}.mt-md-2{margin-top:.5rem !important}.mt-md-3{margin-top:1rem !important}.mt-md-4{margin-top:1.5rem !important}.mt-md-5{margin-top:3rem !important}.mt-md-auto{margin-top:auto !important}.me-md-0{margin-right:0 !important}.me-md-1{margin-right:.25rem !important}.me-md-2{margin-right:.5rem !important}.me-md-3{margin-right:1rem !important}.me-md-4{margin-right:1.5rem !important}.me-md-5{margin-right:3rem !important}.me-md-auto{margin-right:auto !important}.mb-md-0{margin-bottom:0 !important}.mb-md-1{margin-bottom:.25rem !important}.mb-md-2{margin-bottom:.5rem !important}.mb-md-3{margin-bottom:1rem !important}.mb-md-4{margin-bottom:1.5rem !important}.mb-md-5{margin-bottom:3rem !important}.mb-md-auto{margin-bottom:auto !important}.ms-md-0{margin-left:0 !important}.ms-md-1{margin-left:.25rem !important}.ms-md-2{margin-left:.5rem !important}.ms-md-3{margin-left:1rem !important}.ms-md-4{margin-left:1.5rem !important}.ms-md-5{margin-left:3rem !important}.ms-md-auto{margin-left:auto !important}.p-md-0{padding:0 !important}.p-md-1{padding:.25rem !important}.p-md-2{padding:.5rem !important}.p-md-3{padding:1rem !important}.p-md-4{padding:1.5rem !important}.p-md-5{padding:3rem !important}.px-md-0{padding-right:0 !important;padding-left:0 !important}.px-md-1{padding-right:.25rem !important;padding-left:.25rem !important}.px-md-2{padding-right:.5rem !important;padding-left:.5rem !important}.px-md-3{padding-right:1rem !important;padding-left:1rem !important}.px-md-4{padding-right:1.5rem !important;padding-left:1.5rem !important}.px-md-5{padding-right:3rem !important;padding-left:3rem !important}.py-md-0{padding-top:0 !important;padding-bottom:0 !important}.py-md-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.py-md-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.py-md-3{padding-top:1rem !important;padding-bottom:1rem !important}.py-md-4{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.py-md-5{padding-top:3rem !important;padding-bottom:3rem !important}.pt-md-0{padding-top:0 !important}.pt-md-1{padding-top:.25rem !important}.pt-md-2{padding-top:.5rem !important}.pt-md-3{padding-top:1rem !important}.pt-md-4{padding-top:1.5rem !important}.pt-md-5{padding-top:3rem !important}.pe-md-0{padding-right:0 !important}.pe-md-1{padding-right:.25rem !important}.pe-md-2{padding-right:.5rem !important}.pe-md-3{padding-right:1rem !important}.pe-md-4{padding-right:1.5rem !important}.pe-md-5{padding-right:3rem !important}.pb-md-0{padding-bottom:0 !important}.pb-md-1{padding-bottom:.25rem !important}.pb-md-2{padding-bottom:.5rem !important}.pb-md-3{padding-bottom:1rem !important}.pb-md-4{padding-bottom:1.5rem !important}.pb-md-5{padding-bottom:3rem !important}.ps-md-0{padding-left:0 !important}.ps-md-1{padding-left:.25rem !important}.ps-md-2{padding-left:.5rem !important}.ps-md-3{padding-left:1rem !important}.ps-md-4{padding-left:1.5rem !important}.ps-md-5{padding-left:3rem !important}.gap-md-0{gap:0 !important}.gap-md-1{gap:.25rem !important}.gap-md-2{gap:.5rem !important}.gap-md-3{gap:1rem !important}.gap-md-4{gap:1.5rem !important}.gap-md-5{gap:3rem !important}.row-gap-md-0{row-gap:0 !important}.row-gap-md-1{row-gap:.25rem !important}.row-gap-md-2{row-gap:.5rem !important}.row-gap-md-3{row-gap:1rem !important}.row-gap-md-4{row-gap:1.5rem !important}.row-gap-md-5{row-gap:3rem !important}.column-gap-md-0{column-gap:0 !important}.column-gap-md-1{column-gap:.25rem !important}.column-gap-md-2{column-gap:.5rem !important}.column-gap-md-3{column-gap:1rem !important}.column-gap-md-4{column-gap:1.5rem !important}.column-gap-md-5{column-gap:3rem !important}.text-md-start{text-align:left !important}.text-md-end{text-align:right !important}.text-md-center{text-align:center !important}}@media(min-width: 992px){.float-lg-start{float:left !important}.float-lg-end{float:right !important}.float-lg-none{float:none !important}.object-fit-lg-contain{object-fit:contain !important}.object-fit-lg-cover{object-fit:cover !important}.object-fit-lg-fill{object-fit:fill !important}.object-fit-lg-scale{object-fit:scale-down !important}.object-fit-lg-none{object-fit:none !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-block{display:block !important}.d-lg-grid{display:grid !important}.d-lg-inline-grid{display:inline-grid !important}.d-lg-table{display:table !important}.d-lg-table-row{display:table-row !important}.d-lg-table-cell{display:table-cell !important}.d-lg-flex{display:flex !important}.d-lg-inline-flex{display:inline-flex !important}.d-lg-none{display:none !important}.flex-lg-fill{flex:1 1 auto !important}.flex-lg-row{flex-direction:row !important}.flex-lg-column{flex-direction:column !important}.flex-lg-row-reverse{flex-direction:row-reverse !important}.flex-lg-column-reverse{flex-direction:column-reverse !important}.flex-lg-grow-0{flex-grow:0 !important}.flex-lg-grow-1{flex-grow:1 !important}.flex-lg-shrink-0{flex-shrink:0 !important}.flex-lg-shrink-1{flex-shrink:1 !important}.flex-lg-wrap{flex-wrap:wrap !important}.flex-lg-nowrap{flex-wrap:nowrap !important}.flex-lg-wrap-reverse{flex-wrap:wrap-reverse !important}.justify-content-lg-start{justify-content:flex-start !important}.justify-content-lg-end{justify-content:flex-end !important}.justify-content-lg-center{justify-content:center !important}.justify-content-lg-between{justify-content:space-between !important}.justify-content-lg-around{justify-content:space-around !important}.justify-content-lg-evenly{justify-content:space-evenly !important}.align-items-lg-start{align-items:flex-start !important}.align-items-lg-end{align-items:flex-end !important}.align-items-lg-center{align-items:center !important}.align-items-lg-baseline{align-items:baseline !important}.align-items-lg-stretch{align-items:stretch !important}.align-content-lg-start{align-content:flex-start !important}.align-content-lg-end{align-content:flex-end !important}.align-content-lg-center{align-content:center !important}.align-content-lg-between{align-content:space-between !important}.align-content-lg-around{align-content:space-around !important}.align-content-lg-stretch{align-content:stretch !important}.align-self-lg-auto{align-self:auto !important}.align-self-lg-start{align-self:flex-start !important}.align-self-lg-end{align-self:flex-end !important}.align-self-lg-center{align-self:center !important}.align-self-lg-baseline{align-self:baseline !important}.align-self-lg-stretch{align-self:stretch !important}.order-lg-first{order:-1 !important}.order-lg-0{order:0 !important}.order-lg-1{order:1 !important}.order-lg-2{order:2 !important}.order-lg-3{order:3 !important}.order-lg-4{order:4 !important}.order-lg-5{order:5 !important}.order-lg-last{order:6 !important}.m-lg-0{margin:0 !important}.m-lg-1{margin:.25rem !important}.m-lg-2{margin:.5rem !important}.m-lg-3{margin:1rem !important}.m-lg-4{margin:1.5rem !important}.m-lg-5{margin:3rem !important}.m-lg-auto{margin:auto !important}.mx-lg-0{margin-right:0 !important;margin-left:0 !important}.mx-lg-1{margin-right:.25rem !important;margin-left:.25rem !important}.mx-lg-2{margin-right:.5rem !important;margin-left:.5rem !important}.mx-lg-3{margin-right:1rem !important;margin-left:1rem !important}.mx-lg-4{margin-right:1.5rem !important;margin-left:1.5rem !important}.mx-lg-5{margin-right:3rem !important;margin-left:3rem !important}.mx-lg-auto{margin-right:auto !important;margin-left:auto !important}.my-lg-0{margin-top:0 !important;margin-bottom:0 !important}.my-lg-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.my-lg-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.my-lg-3{margin-top:1rem !important;margin-bottom:1rem !important}.my-lg-4{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.my-lg-5{margin-top:3rem !important;margin-bottom:3rem !important}.my-lg-auto{margin-top:auto !important;margin-bottom:auto !important}.mt-lg-0{margin-top:0 !important}.mt-lg-1{margin-top:.25rem !important}.mt-lg-2{margin-top:.5rem !important}.mt-lg-3{margin-top:1rem !important}.mt-lg-4{margin-top:1.5rem !important}.mt-lg-5{margin-top:3rem !important}.mt-lg-auto{margin-top:auto !important}.me-lg-0{margin-right:0 !important}.me-lg-1{margin-right:.25rem !important}.me-lg-2{margin-right:.5rem !important}.me-lg-3{margin-right:1rem !important}.me-lg-4{margin-right:1.5rem !important}.me-lg-5{margin-right:3rem !important}.me-lg-auto{margin-right:auto !important}.mb-lg-0{margin-bottom:0 !important}.mb-lg-1{margin-bottom:.25rem !important}.mb-lg-2{margin-bottom:.5rem !important}.mb-lg-3{margin-bottom:1rem !important}.mb-lg-4{margin-bottom:1.5rem !important}.mb-lg-5{margin-bottom:3rem !important}.mb-lg-auto{margin-bottom:auto !important}.ms-lg-0{margin-left:0 !important}.ms-lg-1{margin-left:.25rem !important}.ms-lg-2{margin-left:.5rem !important}.ms-lg-3{margin-left:1rem !important}.ms-lg-4{margin-left:1.5rem !important}.ms-lg-5{margin-left:3rem !important}.ms-lg-auto{margin-left:auto !important}.p-lg-0{padding:0 !important}.p-lg-1{padding:.25rem !important}.p-lg-2{padding:.5rem !important}.p-lg-3{padding:1rem !important}.p-lg-4{padding:1.5rem !important}.p-lg-5{padding:3rem !important}.px-lg-0{padding-right:0 !important;padding-left:0 !important}.px-lg-1{padding-right:.25rem !important;padding-left:.25rem !important}.px-lg-2{padding-right:.5rem !important;padding-left:.5rem !important}.px-lg-3{padding-right:1rem !important;padding-left:1rem !important}.px-lg-4{padding-right:1.5rem !important;padding-left:1.5rem !important}.px-lg-5{padding-right:3rem !important;padding-left:3rem !important}.py-lg-0{padding-top:0 !important;padding-bottom:0 !important}.py-lg-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.py-lg-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.py-lg-3{padding-top:1rem !important;padding-bottom:1rem !important}.py-lg-4{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.py-lg-5{padding-top:3rem !important;padding-bottom:3rem !important}.pt-lg-0{padding-top:0 !important}.pt-lg-1{padding-top:.25rem !important}.pt-lg-2{padding-top:.5rem !important}.pt-lg-3{padding-top:1rem !important}.pt-lg-4{padding-top:1.5rem !important}.pt-lg-5{padding-top:3rem !important}.pe-lg-0{padding-right:0 !important}.pe-lg-1{padding-right:.25rem !important}.pe-lg-2{padding-right:.5rem !important}.pe-lg-3{padding-right:1rem !important}.pe-lg-4{padding-right:1.5rem !important}.pe-lg-5{padding-right:3rem !important}.pb-lg-0{padding-bottom:0 !important}.pb-lg-1{padding-bottom:.25rem !important}.pb-lg-2{padding-bottom:.5rem !important}.pb-lg-3{padding-bottom:1rem !important}.pb-lg-4{padding-bottom:1.5rem !important}.pb-lg-5{padding-bottom:3rem !important}.ps-lg-0{padding-left:0 !important}.ps-lg-1{padding-left:.25rem !important}.ps-lg-2{padding-left:.5rem !important}.ps-lg-3{padding-left:1rem !important}.ps-lg-4{padding-left:1.5rem !important}.ps-lg-5{padding-left:3rem !important}.gap-lg-0{gap:0 !important}.gap-lg-1{gap:.25rem !important}.gap-lg-2{gap:.5rem !important}.gap-lg-3{gap:1rem !important}.gap-lg-4{gap:1.5rem !important}.gap-lg-5{gap:3rem !important}.row-gap-lg-0{row-gap:0 !important}.row-gap-lg-1{row-gap:.25rem !important}.row-gap-lg-2{row-gap:.5rem !important}.row-gap-lg-3{row-gap:1rem !important}.row-gap-lg-4{row-gap:1.5rem !important}.row-gap-lg-5{row-gap:3rem !important}.column-gap-lg-0{column-gap:0 !important}.column-gap-lg-1{column-gap:.25rem !important}.column-gap-lg-2{column-gap:.5rem !important}.column-gap-lg-3{column-gap:1rem !important}.column-gap-lg-4{column-gap:1.5rem !important}.column-gap-lg-5{column-gap:3rem !important}.text-lg-start{text-align:left !important}.text-lg-end{text-align:right !important}.text-lg-center{text-align:center !important}}@media(min-width: 1200px){.float-xl-start{float:left !important}.float-xl-end{float:right !important}.float-xl-none{float:none !important}.object-fit-xl-contain{object-fit:contain !important}.object-fit-xl-cover{object-fit:cover !important}.object-fit-xl-fill{object-fit:fill !important}.object-fit-xl-scale{object-fit:scale-down !important}.object-fit-xl-none{object-fit:none !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-block{display:block !important}.d-xl-grid{display:grid !important}.d-xl-inline-grid{display:inline-grid !important}.d-xl-table{display:table !important}.d-xl-table-row{display:table-row !important}.d-xl-table-cell{display:table-cell !important}.d-xl-flex{display:flex !important}.d-xl-inline-flex{display:inline-flex !important}.d-xl-none{display:none !important}.flex-xl-fill{flex:1 1 auto !important}.flex-xl-row{flex-direction:row !important}.flex-xl-column{flex-direction:column !important}.flex-xl-row-reverse{flex-direction:row-reverse !important}.flex-xl-column-reverse{flex-direction:column-reverse !important}.flex-xl-grow-0{flex-grow:0 !important}.flex-xl-grow-1{flex-grow:1 !important}.flex-xl-shrink-0{flex-shrink:0 !important}.flex-xl-shrink-1{flex-shrink:1 !important}.flex-xl-wrap{flex-wrap:wrap !important}.flex-xl-nowrap{flex-wrap:nowrap !important}.flex-xl-wrap-reverse{flex-wrap:wrap-reverse !important}.justify-content-xl-start{justify-content:flex-start !important}.justify-content-xl-end{justify-content:flex-end !important}.justify-content-xl-center{justify-content:center !important}.justify-content-xl-between{justify-content:space-between !important}.justify-content-xl-around{justify-content:space-around !important}.justify-content-xl-evenly{justify-content:space-evenly !important}.align-items-xl-start{align-items:flex-start !important}.align-items-xl-end{align-items:flex-end !important}.align-items-xl-center{align-items:center !important}.align-items-xl-baseline{align-items:baseline !important}.align-items-xl-stretch{align-items:stretch !important}.align-content-xl-start{align-content:flex-start !important}.align-content-xl-end{align-content:flex-end !important}.align-content-xl-center{align-content:center !important}.align-content-xl-between{align-content:space-between !important}.align-content-xl-around{align-content:space-around !important}.align-content-xl-stretch{align-content:stretch !important}.align-self-xl-auto{align-self:auto !important}.align-self-xl-start{align-self:flex-start !important}.align-self-xl-end{align-self:flex-end !important}.align-self-xl-center{align-self:center !important}.align-self-xl-baseline{align-self:baseline !important}.align-self-xl-stretch{align-self:stretch !important}.order-xl-first{order:-1 !important}.order-xl-0{order:0 !important}.order-xl-1{order:1 !important}.order-xl-2{order:2 !important}.order-xl-3{order:3 !important}.order-xl-4{order:4 !important}.order-xl-5{order:5 !important}.order-xl-last{order:6 !important}.m-xl-0{margin:0 !important}.m-xl-1{margin:.25rem !important}.m-xl-2{margin:.5rem !important}.m-xl-3{margin:1rem !important}.m-xl-4{margin:1.5rem !important}.m-xl-5{margin:3rem !important}.m-xl-auto{margin:auto !important}.mx-xl-0{margin-right:0 !important;margin-left:0 !important}.mx-xl-1{margin-right:.25rem !important;margin-left:.25rem !important}.mx-xl-2{margin-right:.5rem !important;margin-left:.5rem !important}.mx-xl-3{margin-right:1rem !important;margin-left:1rem !important}.mx-xl-4{margin-right:1.5rem !important;margin-left:1.5rem !important}.mx-xl-5{margin-right:3rem !important;margin-left:3rem !important}.mx-xl-auto{margin-right:auto !important;margin-left:auto !important}.my-xl-0{margin-top:0 !important;margin-bottom:0 !important}.my-xl-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.my-xl-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.my-xl-3{margin-top:1rem !important;margin-bottom:1rem !important}.my-xl-4{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.my-xl-5{margin-top:3rem !important;margin-bottom:3rem !important}.my-xl-auto{margin-top:auto !important;margin-bottom:auto !important}.mt-xl-0{margin-top:0 !important}.mt-xl-1{margin-top:.25rem !important}.mt-xl-2{margin-top:.5rem !important}.mt-xl-3{margin-top:1rem !important}.mt-xl-4{margin-top:1.5rem !important}.mt-xl-5{margin-top:3rem !important}.mt-xl-auto{margin-top:auto !important}.me-xl-0{margin-right:0 !important}.me-xl-1{margin-right:.25rem !important}.me-xl-2{margin-right:.5rem !important}.me-xl-3{margin-right:1rem !important}.me-xl-4{margin-right:1.5rem !important}.me-xl-5{margin-right:3rem !important}.me-xl-auto{margin-right:auto !important}.mb-xl-0{margin-bottom:0 !important}.mb-xl-1{margin-bottom:.25rem !important}.mb-xl-2{margin-bottom:.5rem !important}.mb-xl-3{margin-bottom:1rem !important}.mb-xl-4{margin-bottom:1.5rem !important}.mb-xl-5{margin-bottom:3rem !important}.mb-xl-auto{margin-bottom:auto !important}.ms-xl-0{margin-left:0 !important}.ms-xl-1{margin-left:.25rem !important}.ms-xl-2{margin-left:.5rem !important}.ms-xl-3{margin-left:1rem !important}.ms-xl-4{margin-left:1.5rem !important}.ms-xl-5{margin-left:3rem !important}.ms-xl-auto{margin-left:auto !important}.p-xl-0{padding:0 !important}.p-xl-1{padding:.25rem !important}.p-xl-2{padding:.5rem !important}.p-xl-3{padding:1rem !important}.p-xl-4{padding:1.5rem !important}.p-xl-5{padding:3rem !important}.px-xl-0{padding-right:0 !important;padding-left:0 !important}.px-xl-1{padding-right:.25rem !important;padding-left:.25rem !important}.px-xl-2{padding-right:.5rem !important;padding-left:.5rem !important}.px-xl-3{padding-right:1rem !important;padding-left:1rem !important}.px-xl-4{padding-right:1.5rem !important;padding-left:1.5rem !important}.px-xl-5{padding-right:3rem !important;padding-left:3rem !important}.py-xl-0{padding-top:0 !important;padding-bottom:0 !important}.py-xl-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.py-xl-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.py-xl-3{padding-top:1rem !important;padding-bottom:1rem !important}.py-xl-4{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.py-xl-5{padding-top:3rem !important;padding-bottom:3rem !important}.pt-xl-0{padding-top:0 !important}.pt-xl-1{padding-top:.25rem !important}.pt-xl-2{padding-top:.5rem !important}.pt-xl-3{padding-top:1rem !important}.pt-xl-4{padding-top:1.5rem !important}.pt-xl-5{padding-top:3rem !important}.pe-xl-0{padding-right:0 !important}.pe-xl-1{padding-right:.25rem !important}.pe-xl-2{padding-right:.5rem !important}.pe-xl-3{padding-right:1rem !important}.pe-xl-4{padding-right:1.5rem !important}.pe-xl-5{padding-right:3rem !important}.pb-xl-0{padding-bottom:0 !important}.pb-xl-1{padding-bottom:.25rem !important}.pb-xl-2{padding-bottom:.5rem !important}.pb-xl-3{padding-bottom:1rem !important}.pb-xl-4{padding-bottom:1.5rem !important}.pb-xl-5{padding-bottom:3rem !important}.ps-xl-0{padding-left:0 !important}.ps-xl-1{padding-left:.25rem !important}.ps-xl-2{padding-left:.5rem !important}.ps-xl-3{padding-left:1rem !important}.ps-xl-4{padding-left:1.5rem !important}.ps-xl-5{padding-left:3rem !important}.gap-xl-0{gap:0 !important}.gap-xl-1{gap:.25rem !important}.gap-xl-2{gap:.5rem !important}.gap-xl-3{gap:1rem !important}.gap-xl-4{gap:1.5rem !important}.gap-xl-5{gap:3rem !important}.row-gap-xl-0{row-gap:0 !important}.row-gap-xl-1{row-gap:.25rem !important}.row-gap-xl-2{row-gap:.5rem !important}.row-gap-xl-3{row-gap:1rem !important}.row-gap-xl-4{row-gap:1.5rem !important}.row-gap-xl-5{row-gap:3rem !important}.column-gap-xl-0{column-gap:0 !important}.column-gap-xl-1{column-gap:.25rem !important}.column-gap-xl-2{column-gap:.5rem !important}.column-gap-xl-3{column-gap:1rem !important}.column-gap-xl-4{column-gap:1.5rem !important}.column-gap-xl-5{column-gap:3rem !important}.text-xl-start{text-align:left !important}.text-xl-end{text-align:right !important}.text-xl-center{text-align:center !important}}@media(min-width: 1400px){.float-xxl-start{float:left !important}.float-xxl-end{float:right !important}.float-xxl-none{float:none !important}.object-fit-xxl-contain{object-fit:contain !important}.object-fit-xxl-cover{object-fit:cover !important}.object-fit-xxl-fill{object-fit:fill !important}.object-fit-xxl-scale{object-fit:scale-down !important}.object-fit-xxl-none{object-fit:none !important}.d-xxl-inline{display:inline !important}.d-xxl-inline-block{display:inline-block !important}.d-xxl-block{display:block !important}.d-xxl-grid{display:grid !important}.d-xxl-inline-grid{display:inline-grid !important}.d-xxl-table{display:table !important}.d-xxl-table-row{display:table-row !important}.d-xxl-table-cell{display:table-cell !important}.d-xxl-flex{display:flex !important}.d-xxl-inline-flex{display:inline-flex !important}.d-xxl-none{display:none !important}.flex-xxl-fill{flex:1 1 auto !important}.flex-xxl-row{flex-direction:row !important}.flex-xxl-column{flex-direction:column !important}.flex-xxl-row-reverse{flex-direction:row-reverse !important}.flex-xxl-column-reverse{flex-direction:column-reverse !important}.flex-xxl-grow-0{flex-grow:0 !important}.flex-xxl-grow-1{flex-grow:1 !important}.flex-xxl-shrink-0{flex-shrink:0 !important}.flex-xxl-shrink-1{flex-shrink:1 !important}.flex-xxl-wrap{flex-wrap:wrap !important}.flex-xxl-nowrap{flex-wrap:nowrap !important}.flex-xxl-wrap-reverse{flex-wrap:wrap-reverse !important}.justify-content-xxl-start{justify-content:flex-start !important}.justify-content-xxl-end{justify-content:flex-end !important}.justify-content-xxl-center{justify-content:center !important}.justify-content-xxl-between{justify-content:space-between !important}.justify-content-xxl-around{justify-content:space-around !important}.justify-content-xxl-evenly{justify-content:space-evenly !important}.align-items-xxl-start{align-items:flex-start !important}.align-items-xxl-end{align-items:flex-end !important}.align-items-xxl-center{align-items:center !important}.align-items-xxl-baseline{align-items:baseline !important}.align-items-xxl-stretch{align-items:stretch !important}.align-content-xxl-start{align-content:flex-start !important}.align-content-xxl-end{align-content:flex-end !important}.align-content-xxl-center{align-content:center !important}.align-content-xxl-between{align-content:space-between !important}.align-content-xxl-around{align-content:space-around !important}.align-content-xxl-stretch{align-content:stretch !important}.align-self-xxl-auto{align-self:auto !important}.align-self-xxl-start{align-self:flex-start !important}.align-self-xxl-end{align-self:flex-end !important}.align-self-xxl-center{align-self:center !important}.align-self-xxl-baseline{align-self:baseline !important}.align-self-xxl-stretch{align-self:stretch !important}.order-xxl-first{order:-1 !important}.order-xxl-0{order:0 !important}.order-xxl-1{order:1 !important}.order-xxl-2{order:2 !important}.order-xxl-3{order:3 !important}.order-xxl-4{order:4 !important}.order-xxl-5{order:5 !important}.order-xxl-last{order:6 !important}.m-xxl-0{margin:0 !important}.m-xxl-1{margin:.25rem !important}.m-xxl-2{margin:.5rem !important}.m-xxl-3{margin:1rem !important}.m-xxl-4{margin:1.5rem !important}.m-xxl-5{margin:3rem !important}.m-xxl-auto{margin:auto !important}.mx-xxl-0{margin-right:0 !important;margin-left:0 !important}.mx-xxl-1{margin-right:.25rem !important;margin-left:.25rem !important}.mx-xxl-2{margin-right:.5rem !important;margin-left:.5rem !important}.mx-xxl-3{margin-right:1rem !important;margin-left:1rem !important}.mx-xxl-4{margin-right:1.5rem !important;margin-left:1.5rem !important}.mx-xxl-5{margin-right:3rem !important;margin-left:3rem !important}.mx-xxl-auto{margin-right:auto !important;margin-left:auto !important}.my-xxl-0{margin-top:0 !important;margin-bottom:0 !important}.my-xxl-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.my-xxl-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.my-xxl-3{margin-top:1rem !important;margin-bottom:1rem !important}.my-xxl-4{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.my-xxl-5{margin-top:3rem !important;margin-bottom:3rem !important}.my-xxl-auto{margin-top:auto !important;margin-bottom:auto !important}.mt-xxl-0{margin-top:0 !important}.mt-xxl-1{margin-top:.25rem !important}.mt-xxl-2{margin-top:.5rem !important}.mt-xxl-3{margin-top:1rem !important}.mt-xxl-4{margin-top:1.5rem !important}.mt-xxl-5{margin-top:3rem !important}.mt-xxl-auto{margin-top:auto !important}.me-xxl-0{margin-right:0 !important}.me-xxl-1{margin-right:.25rem !important}.me-xxl-2{margin-right:.5rem !important}.me-xxl-3{margin-right:1rem !important}.me-xxl-4{margin-right:1.5rem !important}.me-xxl-5{margin-right:3rem !important}.me-xxl-auto{margin-right:auto !important}.mb-xxl-0{margin-bottom:0 !important}.mb-xxl-1{margin-bottom:.25rem !important}.mb-xxl-2{margin-bottom:.5rem !important}.mb-xxl-3{margin-bottom:1rem !important}.mb-xxl-4{margin-bottom:1.5rem !important}.mb-xxl-5{margin-bottom:3rem !important}.mb-xxl-auto{margin-bottom:auto !important}.ms-xxl-0{margin-left:0 !important}.ms-xxl-1{margin-left:.25rem !important}.ms-xxl-2{margin-left:.5rem !important}.ms-xxl-3{margin-left:1rem !important}.ms-xxl-4{margin-left:1.5rem !important}.ms-xxl-5{margin-left:3rem !important}.ms-xxl-auto{margin-left:auto !important}.p-xxl-0{padding:0 !important}.p-xxl-1{padding:.25rem !important}.p-xxl-2{padding:.5rem !important}.p-xxl-3{padding:1rem !important}.p-xxl-4{padding:1.5rem !important}.p-xxl-5{padding:3rem !important}.px-xxl-0{padding-right:0 !important;padding-left:0 !important}.px-xxl-1{padding-right:.25rem !important;padding-left:.25rem !important}.px-xxl-2{padding-right:.5rem !important;padding-left:.5rem !important}.px-xxl-3{padding-right:1rem !important;padding-left:1rem !important}.px-xxl-4{padding-right:1.5rem !important;padding-left:1.5rem !important}.px-xxl-5{padding-right:3rem !important;padding-left:3rem !important}.py-xxl-0{padding-top:0 !important;padding-bottom:0 !important}.py-xxl-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.py-xxl-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.py-xxl-3{padding-top:1rem !important;padding-bottom:1rem !important}.py-xxl-4{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.py-xxl-5{padding-top:3rem !important;padding-bottom:3rem !important}.pt-xxl-0{padding-top:0 !important}.pt-xxl-1{padding-top:.25rem !important}.pt-xxl-2{padding-top:.5rem !important}.pt-xxl-3{padding-top:1rem !important}.pt-xxl-4{padding-top:1.5rem !important}.pt-xxl-5{padding-top:3rem !important}.pe-xxl-0{padding-right:0 !important}.pe-xxl-1{padding-right:.25rem !important}.pe-xxl-2{padding-right:.5rem !important}.pe-xxl-3{padding-right:1rem !important}.pe-xxl-4{padding-right:1.5rem !important}.pe-xxl-5{padding-right:3rem !important}.pb-xxl-0{padding-bottom:0 !important}.pb-xxl-1{padding-bottom:.25rem !important}.pb-xxl-2{padding-bottom:.5rem !important}.pb-xxl-3{padding-bottom:1rem !important}.pb-xxl-4{padding-bottom:1.5rem !important}.pb-xxl-5{padding-bottom:3rem !important}.ps-xxl-0{padding-left:0 !important}.ps-xxl-1{padding-left:.25rem !important}.ps-xxl-2{padding-left:.5rem !important}.ps-xxl-3{padding-left:1rem !important}.ps-xxl-4{padding-left:1.5rem !important}.ps-xxl-5{padding-left:3rem !important}.gap-xxl-0{gap:0 !important}.gap-xxl-1{gap:.25rem !important}.gap-xxl-2{gap:.5rem !important}.gap-xxl-3{gap:1rem !important}.gap-xxl-4{gap:1.5rem !important}.gap-xxl-5{gap:3rem !important}.row-gap-xxl-0{row-gap:0 !important}.row-gap-xxl-1{row-gap:.25rem !important}.row-gap-xxl-2{row-gap:.5rem !important}.row-gap-xxl-3{row-gap:1rem !important}.row-gap-xxl-4{row-gap:1.5rem !important}.row-gap-xxl-5{row-gap:3rem !important}.column-gap-xxl-0{column-gap:0 !important}.column-gap-xxl-1{column-gap:.25rem !important}.column-gap-xxl-2{column-gap:.5rem !important}.column-gap-xxl-3{column-gap:1rem !important}.column-gap-xxl-4{column-gap:1.5rem !important}.column-gap-xxl-5{column-gap:3rem !important}.text-xxl-start{text-align:left !important}.text-xxl-end{text-align:right !important}.text-xxl-center{text-align:center !important}}.bg-default{color:#fff}.bg-primary{color:#fff}.bg-secondary{color:#fff}.bg-success{color:#fff}.bg-info{color:#fff}.bg-warning{color:#fff}.bg-danger{color:#fff}.bg-light{color:#000}.bg-dark{color:#fff}@media(min-width: 1200px){.fs-1{font-size:2rem !important}.fs-2{font-size:1.65rem !important}.fs-3{font-size:1.45rem !important}}@media print{.d-print-inline{display:inline !important}.d-print-inline-block{display:inline-block !important}.d-print-block{display:block !important}.d-print-grid{display:grid !important}.d-print-inline-grid{display:inline-grid !important}.d-print-table{display:table !important}.d-print-table-row{display:table-row !important}.d-print-table-cell{display:table-cell !important}.d-print-flex{display:flex !important}.d-print-inline-flex{display:inline-flex !important}.d-print-none{display:none !important}}.bg-blue{--bslib-color-bg: #2780e3;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-blue{--bslib-color-fg: #2780e3;color:var(--bslib-color-fg)}.bg-indigo{--bslib-color-bg: #6610f2;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-indigo{--bslib-color-fg: #6610f2;color:var(--bslib-color-fg)}.bg-purple{--bslib-color-bg: #613d7c;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-purple{--bslib-color-fg: #613d7c;color:var(--bslib-color-fg)}.bg-pink{--bslib-color-bg: #e83e8c;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-pink{--bslib-color-fg: #e83e8c;color:var(--bslib-color-fg)}.bg-red{--bslib-color-bg: #ff0039;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-red{--bslib-color-fg: #ff0039;color:var(--bslib-color-fg)}.bg-orange{--bslib-color-bg: #f0ad4e;--bslib-color-fg: #000;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-orange{--bslib-color-fg: #f0ad4e;color:var(--bslib-color-fg)}.bg-yellow{--bslib-color-bg: #ff7518;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-yellow{--bslib-color-fg: #ff7518;color:var(--bslib-color-fg)}.bg-green{--bslib-color-bg: #3fb618;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-green{--bslib-color-fg: #3fb618;color:var(--bslib-color-fg)}.bg-teal{--bslib-color-bg: #20c997;--bslib-color-fg: #000;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-teal{--bslib-color-fg: #20c997;color:var(--bslib-color-fg)}.bg-cyan{--bslib-color-bg: #9954bb;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-cyan{--bslib-color-fg: #9954bb;color:var(--bslib-color-fg)}.text-default{--bslib-color-fg: #343a40}.bg-default{--bslib-color-bg: #343a40;--bslib-color-fg: #fff}.text-primary{--bslib-color-fg: #2780e3}.bg-primary{--bslib-color-bg: #2780e3;--bslib-color-fg: #fff}.text-secondary{--bslib-color-fg: #343a40}.bg-secondary{--bslib-color-bg: #343a40;--bslib-color-fg: #fff}.text-success{--bslib-color-fg: #3fb618}.bg-success{--bslib-color-bg: #3fb618;--bslib-color-fg: #fff}.text-info{--bslib-color-fg: #9954bb}.bg-info{--bslib-color-bg: #9954bb;--bslib-color-fg: #fff}.text-warning{--bslib-color-fg: #ff7518}.bg-warning{--bslib-color-bg: #ff7518;--bslib-color-fg: #fff}.text-danger{--bslib-color-fg: #ff0039}.bg-danger{--bslib-color-bg: #ff0039;--bslib-color-fg: #fff}.text-light{--bslib-color-fg: #f8f9fa}.bg-light{--bslib-color-bg: #f8f9fa;--bslib-color-fg: #000}.text-dark{--bslib-color-fg: #343a40}.bg-dark{--bslib-color-bg: #343a40;--bslib-color-fg: #fff}.bg-gradient-blue-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #4053e9;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #4053e9;color:#fff}.bg-gradient-blue-purple{--bslib-color-fg: #fff;--bslib-color-bg: #3e65ba;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #3e65ba;color:#fff}.bg-gradient-blue-pink{--bslib-color-fg: #fff;--bslib-color-bg: #7466c0;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #7466c0;color:#fff}.bg-gradient-blue-red{--bslib-color-fg: #fff;--bslib-color-bg: #7d4d9f;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #7d4d9f;color:#fff}.bg-gradient-blue-orange{--bslib-color-fg: #fff;--bslib-color-bg: #7792a7;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #7792a7;color:#fff}.bg-gradient-blue-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #7d7c92;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #7d7c92;color:#fff}.bg-gradient-blue-green{--bslib-color-fg: #fff;--bslib-color-bg: #319692;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #319692;color:#fff}.bg-gradient-blue-teal{--bslib-color-fg: #fff;--bslib-color-bg: #249dc5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #249dc5;color:#fff}.bg-gradient-blue-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #556ed3;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #556ed3;color:#fff}.bg-gradient-indigo-blue{--bslib-color-fg: #fff;--bslib-color-bg: #4d3dec;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #4d3dec;color:#fff}.bg-gradient-indigo-purple{--bslib-color-fg: #fff;--bslib-color-bg: #6422c3;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #6422c3;color:#fff}.bg-gradient-indigo-pink{--bslib-color-fg: #fff;--bslib-color-bg: #9a22c9;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #9a22c9;color:#fff}.bg-gradient-indigo-red{--bslib-color-fg: #fff;--bslib-color-bg: #a30aa8;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #a30aa8;color:#fff}.bg-gradient-indigo-orange{--bslib-color-fg: #fff;--bslib-color-bg: #9d4fb0;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #9d4fb0;color:#fff}.bg-gradient-indigo-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #a3389b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #a3389b;color:#fff}.bg-gradient-indigo-green{--bslib-color-fg: #fff;--bslib-color-bg: #56529b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #56529b;color:#fff}.bg-gradient-indigo-teal{--bslib-color-fg: #fff;--bslib-color-bg: #4a5ace;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #4a5ace;color:#fff}.bg-gradient-indigo-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #7a2bdc;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #7a2bdc;color:#fff}.bg-gradient-purple-blue{--bslib-color-fg: #fff;--bslib-color-bg: #4a58a5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #4a58a5;color:#fff}.bg-gradient-purple-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #632bab;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #632bab;color:#fff}.bg-gradient-purple-pink{--bslib-color-fg: #fff;--bslib-color-bg: #973d82;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #973d82;color:#fff}.bg-gradient-purple-red{--bslib-color-fg: #fff;--bslib-color-bg: #a02561;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #a02561;color:#fff}.bg-gradient-purple-orange{--bslib-color-fg: #fff;--bslib-color-bg: #9a6a6a;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #9a6a6a;color:#fff}.bg-gradient-purple-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #a05354;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #a05354;color:#fff}.bg-gradient-purple-green{--bslib-color-fg: #fff;--bslib-color-bg: #536d54;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #536d54;color:#fff}.bg-gradient-purple-teal{--bslib-color-fg: #fff;--bslib-color-bg: #477587;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #477587;color:#fff}.bg-gradient-purple-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #774695;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #774695;color:#fff}.bg-gradient-pink-blue{--bslib-color-fg: #fff;--bslib-color-bg: #9b58af;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #9b58af;color:#fff}.bg-gradient-pink-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #b42cb5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #b42cb5;color:#fff}.bg-gradient-pink-purple{--bslib-color-fg: #fff;--bslib-color-bg: #b23e86;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #b23e86;color:#fff}.bg-gradient-pink-red{--bslib-color-fg: #fff;--bslib-color-bg: #f1256b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #f1256b;color:#fff}.bg-gradient-pink-orange{--bslib-color-fg: #fff;--bslib-color-bg: #eb6a73;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #eb6a73;color:#fff}.bg-gradient-pink-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #f1545e;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #f1545e;color:#fff}.bg-gradient-pink-green{--bslib-color-fg: #fff;--bslib-color-bg: #a46e5e;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #a46e5e;color:#fff}.bg-gradient-pink-teal{--bslib-color-fg: #fff;--bslib-color-bg: #987690;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #987690;color:#fff}.bg-gradient-pink-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #c8479f;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #c8479f;color:#fff}.bg-gradient-red-blue{--bslib-color-fg: #fff;--bslib-color-bg: #a9337d;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #a9337d;color:#fff}.bg-gradient-red-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #c20683;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #c20683;color:#fff}.bg-gradient-red-purple{--bslib-color-fg: #fff;--bslib-color-bg: #c01854;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #c01854;color:#fff}.bg-gradient-red-pink{--bslib-color-fg: #fff;--bslib-color-bg: #f6195a;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #f6195a;color:#fff}.bg-gradient-red-orange{--bslib-color-fg: #fff;--bslib-color-bg: #f94541;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #f94541;color:#fff}.bg-gradient-red-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #ff2f2c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #ff2f2c;color:#fff}.bg-gradient-red-green{--bslib-color-fg: #fff;--bslib-color-bg: #b2492c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #b2492c;color:#fff}.bg-gradient-red-teal{--bslib-color-fg: #fff;--bslib-color-bg: #a6505f;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #a6505f;color:#fff}.bg-gradient-red-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #d6226d;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #d6226d;color:#fff}.bg-gradient-orange-blue{--bslib-color-fg: #fff;--bslib-color-bg: #a09b8a;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #a09b8a;color:#fff}.bg-gradient-orange-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #b96e90;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #b96e90;color:#fff}.bg-gradient-orange-purple{--bslib-color-fg: #fff;--bslib-color-bg: #b78060;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #b78060;color:#fff}.bg-gradient-orange-pink{--bslib-color-fg: #fff;--bslib-color-bg: #ed8167;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #ed8167;color:#fff}.bg-gradient-orange-red{--bslib-color-fg: #fff;--bslib-color-bg: #f66846;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #f66846;color:#fff}.bg-gradient-orange-yellow{--bslib-color-fg: #000;--bslib-color-bg: #f69738;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #f69738;color:#000}.bg-gradient-orange-green{--bslib-color-fg: #000;--bslib-color-bg: #a9b138;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #a9b138;color:#000}.bg-gradient-orange-teal{--bslib-color-fg: #000;--bslib-color-bg: #9db86b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #9db86b;color:#000}.bg-gradient-orange-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #cd897a;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #cd897a;color:#fff}.bg-gradient-yellow-blue{--bslib-color-fg: #fff;--bslib-color-bg: #a97969;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #a97969;color:#fff}.bg-gradient-yellow-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #c24d6f;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #c24d6f;color:#fff}.bg-gradient-yellow-purple{--bslib-color-fg: #fff;--bslib-color-bg: #c05f40;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #c05f40;color:#fff}.bg-gradient-yellow-pink{--bslib-color-fg: #fff;--bslib-color-bg: #f65f46;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #f65f46;color:#fff}.bg-gradient-yellow-red{--bslib-color-fg: #fff;--bslib-color-bg: #ff4625;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #ff4625;color:#fff}.bg-gradient-yellow-orange{--bslib-color-fg: #000;--bslib-color-bg: #f98b2e;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #f98b2e;color:#000}.bg-gradient-yellow-green{--bslib-color-fg: #fff;--bslib-color-bg: #b28f18;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #b28f18;color:#fff}.bg-gradient-yellow-teal{--bslib-color-fg: #fff;--bslib-color-bg: #a6974b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #a6974b;color:#fff}.bg-gradient-yellow-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #d66859;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #d66859;color:#fff}.bg-gradient-green-blue{--bslib-color-fg: #fff;--bslib-color-bg: #35a069;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #35a069;color:#fff}.bg-gradient-green-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #4f746f;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #4f746f;color:#fff}.bg-gradient-green-purple{--bslib-color-fg: #fff;--bslib-color-bg: #4d8640;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #4d8640;color:#fff}.bg-gradient-green-pink{--bslib-color-fg: #fff;--bslib-color-bg: #838646;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #838646;color:#fff}.bg-gradient-green-red{--bslib-color-fg: #fff;--bslib-color-bg: #8c6d25;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #8c6d25;color:#fff}.bg-gradient-green-orange{--bslib-color-fg: #000;--bslib-color-bg: #86b22e;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #86b22e;color:#000}.bg-gradient-green-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #8c9c18;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #8c9c18;color:#fff}.bg-gradient-green-teal{--bslib-color-fg: #000;--bslib-color-bg: #33be4b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #33be4b;color:#000}.bg-gradient-green-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #638f59;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #638f59;color:#fff}.bg-gradient-teal-blue{--bslib-color-fg: #fff;--bslib-color-bg: #23acb5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #23acb5;color:#fff}.bg-gradient-teal-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #3c7fbb;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #3c7fbb;color:#fff}.bg-gradient-teal-purple{--bslib-color-fg: #fff;--bslib-color-bg: #3a918c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #3a918c;color:#fff}.bg-gradient-teal-pink{--bslib-color-fg: #fff;--bslib-color-bg: #709193;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #709193;color:#fff}.bg-gradient-teal-red{--bslib-color-fg: #fff;--bslib-color-bg: #797971;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #797971;color:#fff}.bg-gradient-teal-orange{--bslib-color-fg: #000;--bslib-color-bg: #73be7a;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #73be7a;color:#000}.bg-gradient-teal-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #79a764;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #79a764;color:#fff}.bg-gradient-teal-green{--bslib-color-fg: #000;--bslib-color-bg: #2cc164;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #2cc164;color:#000}.bg-gradient-teal-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #509aa5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #509aa5;color:#fff}.bg-gradient-cyan-blue{--bslib-color-fg: #fff;--bslib-color-bg: #6b66cb;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #6b66cb;color:#fff}.bg-gradient-cyan-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #8539d1;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #8539d1;color:#fff}.bg-gradient-cyan-purple{--bslib-color-fg: #fff;--bslib-color-bg: #834ba2;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #834ba2;color:#fff}.bg-gradient-cyan-pink{--bslib-color-fg: #fff;--bslib-color-bg: #b94ba8;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #b94ba8;color:#fff}.bg-gradient-cyan-red{--bslib-color-fg: #fff;--bslib-color-bg: #c23287;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #c23287;color:#fff}.bg-gradient-cyan-orange{--bslib-color-fg: #fff;--bslib-color-bg: #bc788f;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #bc788f;color:#fff}.bg-gradient-cyan-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #c2617a;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #c2617a;color:#fff}.bg-gradient-cyan-green{--bslib-color-fg: #fff;--bslib-color-bg: #757b7a;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #757b7a;color:#fff}.bg-gradient-cyan-teal{--bslib-color-fg: #fff;--bslib-color-bg: #6983ad;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #6983ad;color:#fff}:root{--bslib-spacer: 1rem;--bslib-mb-spacer: var(--bslib-spacer, 1rem)}.bslib-mb-spacing{margin-bottom:var(--bslib-mb-spacer)}.bslib-gap-spacing{gap:var(--bslib-mb-spacer)}.bslib-gap-spacing>.bslib-mb-spacing,.bslib-gap-spacing>.form-group,.bslib-gap-spacing>p,.bslib-gap-spacing>pre{margin-bottom:0}.html-fill-container>.html-fill-item.bslib-mb-spacing{margin-bottom:0}.tab-content>.tab-pane.html-fill-container{display:none}.tab-content>.active.html-fill-container{display:flex}.tab-content.html-fill-container{padding:0}:root{--bslib-spacer: 1rem;--bslib-mb-spacer: var(--bslib-spacer, 1rem)}.bslib-mb-spacing{margin-bottom:var(--bslib-mb-spacer)}.bslib-gap-spacing{gap:var(--bslib-mb-spacer)}.bslib-gap-spacing>.bslib-mb-spacing,.bslib-gap-spacing>.form-group,.bslib-gap-spacing>p,.bslib-gap-spacing>pre{margin-bottom:0}.html-fill-container>.html-fill-item.bslib-mb-spacing{margin-bottom:0}.tab-content>.tab-pane.html-fill-container{display:none}.tab-content>.active.html-fill-container{display:flex}.tab-content.html-fill-container{padding:0}.bg-blue{--bslib-color-bg: #2780e3;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-blue{--bslib-color-fg: #2780e3;color:var(--bslib-color-fg)}.bg-indigo{--bslib-color-bg: #6610f2;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-indigo{--bslib-color-fg: #6610f2;color:var(--bslib-color-fg)}.bg-purple{--bslib-color-bg: #613d7c;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-purple{--bslib-color-fg: #613d7c;color:var(--bslib-color-fg)}.bg-pink{--bslib-color-bg: #e83e8c;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-pink{--bslib-color-fg: #e83e8c;color:var(--bslib-color-fg)}.bg-red{--bslib-color-bg: #ff0039;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-red{--bslib-color-fg: #ff0039;color:var(--bslib-color-fg)}.bg-orange{--bslib-color-bg: #f0ad4e;--bslib-color-fg: #000;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-orange{--bslib-color-fg: #f0ad4e;color:var(--bslib-color-fg)}.bg-yellow{--bslib-color-bg: #ff7518;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-yellow{--bslib-color-fg: #ff7518;color:var(--bslib-color-fg)}.bg-green{--bslib-color-bg: #3fb618;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-green{--bslib-color-fg: #3fb618;color:var(--bslib-color-fg)}.bg-teal{--bslib-color-bg: #20c997;--bslib-color-fg: #000;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-teal{--bslib-color-fg: #20c997;color:var(--bslib-color-fg)}.bg-cyan{--bslib-color-bg: #9954bb;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-cyan{--bslib-color-fg: #9954bb;color:var(--bslib-color-fg)}.text-default{--bslib-color-fg: #343a40}.bg-default{--bslib-color-bg: #343a40;--bslib-color-fg: #fff}.text-primary{--bslib-color-fg: #2780e3}.bg-primary{--bslib-color-bg: #2780e3;--bslib-color-fg: #fff}.text-secondary{--bslib-color-fg: #343a40}.bg-secondary{--bslib-color-bg: #343a40;--bslib-color-fg: #fff}.text-success{--bslib-color-fg: #3fb618}.bg-success{--bslib-color-bg: #3fb618;--bslib-color-fg: #fff}.text-info{--bslib-color-fg: #9954bb}.bg-info{--bslib-color-bg: #9954bb;--bslib-color-fg: #fff}.text-warning{--bslib-color-fg: #ff7518}.bg-warning{--bslib-color-bg: #ff7518;--bslib-color-fg: #fff}.text-danger{--bslib-color-fg: #ff0039}.bg-danger{--bslib-color-bg: #ff0039;--bslib-color-fg: #fff}.text-light{--bslib-color-fg: #f8f9fa}.bg-light{--bslib-color-bg: #f8f9fa;--bslib-color-fg: #000}.text-dark{--bslib-color-fg: #343a40}.bg-dark{--bslib-color-bg: #343a40;--bslib-color-fg: #fff}.bg-gradient-blue-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #4053e9;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #4053e9;color:#fff}.bg-gradient-blue-purple{--bslib-color-fg: #fff;--bslib-color-bg: #3e65ba;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #3e65ba;color:#fff}.bg-gradient-blue-pink{--bslib-color-fg: #fff;--bslib-color-bg: #7466c0;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #7466c0;color:#fff}.bg-gradient-blue-red{--bslib-color-fg: #fff;--bslib-color-bg: #7d4d9f;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #7d4d9f;color:#fff}.bg-gradient-blue-orange{--bslib-color-fg: #fff;--bslib-color-bg: #7792a7;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #7792a7;color:#fff}.bg-gradient-blue-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #7d7c92;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #7d7c92;color:#fff}.bg-gradient-blue-green{--bslib-color-fg: #fff;--bslib-color-bg: #319692;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #319692;color:#fff}.bg-gradient-blue-teal{--bslib-color-fg: #fff;--bslib-color-bg: #249dc5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #249dc5;color:#fff}.bg-gradient-blue-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #556ed3;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #556ed3;color:#fff}.bg-gradient-indigo-blue{--bslib-color-fg: #fff;--bslib-color-bg: #4d3dec;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #4d3dec;color:#fff}.bg-gradient-indigo-purple{--bslib-color-fg: #fff;--bslib-color-bg: #6422c3;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #6422c3;color:#fff}.bg-gradient-indigo-pink{--bslib-color-fg: #fff;--bslib-color-bg: #9a22c9;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #9a22c9;color:#fff}.bg-gradient-indigo-red{--bslib-color-fg: #fff;--bslib-color-bg: #a30aa8;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #a30aa8;color:#fff}.bg-gradient-indigo-orange{--bslib-color-fg: #fff;--bslib-color-bg: #9d4fb0;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #9d4fb0;color:#fff}.bg-gradient-indigo-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #a3389b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #a3389b;color:#fff}.bg-gradient-indigo-green{--bslib-color-fg: #fff;--bslib-color-bg: #56529b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #56529b;color:#fff}.bg-gradient-indigo-teal{--bslib-color-fg: #fff;--bslib-color-bg: #4a5ace;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #4a5ace;color:#fff}.bg-gradient-indigo-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #7a2bdc;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #7a2bdc;color:#fff}.bg-gradient-purple-blue{--bslib-color-fg: #fff;--bslib-color-bg: #4a58a5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #4a58a5;color:#fff}.bg-gradient-purple-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #632bab;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #632bab;color:#fff}.bg-gradient-purple-pink{--bslib-color-fg: #fff;--bslib-color-bg: #973d82;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #973d82;color:#fff}.bg-gradient-purple-red{--bslib-color-fg: #fff;--bslib-color-bg: #a02561;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #a02561;color:#fff}.bg-gradient-purple-orange{--bslib-color-fg: #fff;--bslib-color-bg: #9a6a6a;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #9a6a6a;color:#fff}.bg-gradient-purple-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #a05354;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #a05354;color:#fff}.bg-gradient-purple-green{--bslib-color-fg: #fff;--bslib-color-bg: #536d54;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #536d54;color:#fff}.bg-gradient-purple-teal{--bslib-color-fg: #fff;--bslib-color-bg: #477587;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #477587;color:#fff}.bg-gradient-purple-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #774695;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #774695;color:#fff}.bg-gradient-pink-blue{--bslib-color-fg: #fff;--bslib-color-bg: #9b58af;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #9b58af;color:#fff}.bg-gradient-pink-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #b42cb5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #b42cb5;color:#fff}.bg-gradient-pink-purple{--bslib-color-fg: #fff;--bslib-color-bg: #b23e86;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #b23e86;color:#fff}.bg-gradient-pink-red{--bslib-color-fg: #fff;--bslib-color-bg: #f1256b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #f1256b;color:#fff}.bg-gradient-pink-orange{--bslib-color-fg: #fff;--bslib-color-bg: #eb6a73;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #eb6a73;color:#fff}.bg-gradient-pink-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #f1545e;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #f1545e;color:#fff}.bg-gradient-pink-green{--bslib-color-fg: #fff;--bslib-color-bg: #a46e5e;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #a46e5e;color:#fff}.bg-gradient-pink-teal{--bslib-color-fg: #fff;--bslib-color-bg: #987690;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #987690;color:#fff}.bg-gradient-pink-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #c8479f;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #c8479f;color:#fff}.bg-gradient-red-blue{--bslib-color-fg: #fff;--bslib-color-bg: #a9337d;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #a9337d;color:#fff}.bg-gradient-red-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #c20683;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #c20683;color:#fff}.bg-gradient-red-purple{--bslib-color-fg: #fff;--bslib-color-bg: #c01854;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #c01854;color:#fff}.bg-gradient-red-pink{--bslib-color-fg: #fff;--bslib-color-bg: #f6195a;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #f6195a;color:#fff}.bg-gradient-red-orange{--bslib-color-fg: #fff;--bslib-color-bg: #f94541;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #f94541;color:#fff}.bg-gradient-red-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #ff2f2c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #ff2f2c;color:#fff}.bg-gradient-red-green{--bslib-color-fg: #fff;--bslib-color-bg: #b2492c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #b2492c;color:#fff}.bg-gradient-red-teal{--bslib-color-fg: #fff;--bslib-color-bg: #a6505f;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #a6505f;color:#fff}.bg-gradient-red-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #d6226d;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #d6226d;color:#fff}.bg-gradient-orange-blue{--bslib-color-fg: #fff;--bslib-color-bg: #a09b8a;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #a09b8a;color:#fff}.bg-gradient-orange-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #b96e90;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #b96e90;color:#fff}.bg-gradient-orange-purple{--bslib-color-fg: #fff;--bslib-color-bg: #b78060;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #b78060;color:#fff}.bg-gradient-orange-pink{--bslib-color-fg: #fff;--bslib-color-bg: #ed8167;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #ed8167;color:#fff}.bg-gradient-orange-red{--bslib-color-fg: #fff;--bslib-color-bg: #f66846;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #f66846;color:#fff}.bg-gradient-orange-yellow{--bslib-color-fg: #000;--bslib-color-bg: #f69738;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #f69738;color:#000}.bg-gradient-orange-green{--bslib-color-fg: #000;--bslib-color-bg: #a9b138;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #a9b138;color:#000}.bg-gradient-orange-teal{--bslib-color-fg: #000;--bslib-color-bg: #9db86b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #9db86b;color:#000}.bg-gradient-orange-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #cd897a;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #cd897a;color:#fff}.bg-gradient-yellow-blue{--bslib-color-fg: #fff;--bslib-color-bg: #a97969;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #a97969;color:#fff}.bg-gradient-yellow-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #c24d6f;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #c24d6f;color:#fff}.bg-gradient-yellow-purple{--bslib-color-fg: #fff;--bslib-color-bg: #c05f40;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #c05f40;color:#fff}.bg-gradient-yellow-pink{--bslib-color-fg: #fff;--bslib-color-bg: #f65f46;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #f65f46;color:#fff}.bg-gradient-yellow-red{--bslib-color-fg: #fff;--bslib-color-bg: #ff4625;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #ff4625;color:#fff}.bg-gradient-yellow-orange{--bslib-color-fg: #000;--bslib-color-bg: #f98b2e;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #f98b2e;color:#000}.bg-gradient-yellow-green{--bslib-color-fg: #fff;--bslib-color-bg: #b28f18;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #b28f18;color:#fff}.bg-gradient-yellow-teal{--bslib-color-fg: #fff;--bslib-color-bg: #a6974b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #a6974b;color:#fff}.bg-gradient-yellow-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #d66859;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #d66859;color:#fff}.bg-gradient-green-blue{--bslib-color-fg: #fff;--bslib-color-bg: #35a069;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #35a069;color:#fff}.bg-gradient-green-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #4f746f;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #4f746f;color:#fff}.bg-gradient-green-purple{--bslib-color-fg: #fff;--bslib-color-bg: #4d8640;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #4d8640;color:#fff}.bg-gradient-green-pink{--bslib-color-fg: #fff;--bslib-color-bg: #838646;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #838646;color:#fff}.bg-gradient-green-red{--bslib-color-fg: #fff;--bslib-color-bg: #8c6d25;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #8c6d25;color:#fff}.bg-gradient-green-orange{--bslib-color-fg: #000;--bslib-color-bg: #86b22e;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #86b22e;color:#000}.bg-gradient-green-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #8c9c18;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #8c9c18;color:#fff}.bg-gradient-green-teal{--bslib-color-fg: #000;--bslib-color-bg: #33be4b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #33be4b;color:#000}.bg-gradient-green-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #638f59;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #638f59;color:#fff}.bg-gradient-teal-blue{--bslib-color-fg: #fff;--bslib-color-bg: #23acb5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #23acb5;color:#fff}.bg-gradient-teal-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #3c7fbb;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #3c7fbb;color:#fff}.bg-gradient-teal-purple{--bslib-color-fg: #fff;--bslib-color-bg: #3a918c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #3a918c;color:#fff}.bg-gradient-teal-pink{--bslib-color-fg: #fff;--bslib-color-bg: #709193;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #709193;color:#fff}.bg-gradient-teal-red{--bslib-color-fg: #fff;--bslib-color-bg: #797971;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #797971;color:#fff}.bg-gradient-teal-orange{--bslib-color-fg: #000;--bslib-color-bg: #73be7a;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #73be7a;color:#000}.bg-gradient-teal-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #79a764;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #79a764;color:#fff}.bg-gradient-teal-green{--bslib-color-fg: #000;--bslib-color-bg: #2cc164;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #2cc164;color:#000}.bg-gradient-teal-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #509aa5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #509aa5;color:#fff}.bg-gradient-cyan-blue{--bslib-color-fg: #fff;--bslib-color-bg: #6b66cb;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #6b66cb;color:#fff}.bg-gradient-cyan-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #8539d1;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #8539d1;color:#fff}.bg-gradient-cyan-purple{--bslib-color-fg: #fff;--bslib-color-bg: #834ba2;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #834ba2;color:#fff}.bg-gradient-cyan-pink{--bslib-color-fg: #fff;--bslib-color-bg: #b94ba8;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #b94ba8;color:#fff}.bg-gradient-cyan-red{--bslib-color-fg: #fff;--bslib-color-bg: #c23287;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #c23287;color:#fff}.bg-gradient-cyan-orange{--bslib-color-fg: #fff;--bslib-color-bg: #bc788f;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #bc788f;color:#fff}.bg-gradient-cyan-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #c2617a;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #c2617a;color:#fff}.bg-gradient-cyan-green{--bslib-color-fg: #fff;--bslib-color-bg: #757b7a;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #757b7a;color:#fff}.bg-gradient-cyan-teal{--bslib-color-fg: #fff;--bslib-color-bg: #6983ad;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #6983ad;color:#fff}:root{--bslib-value-box-shadow: none;--bslib-value-box-border-width-auto-yes: var(--bslib-value-box-border-width-baseline);--bslib-value-box-border-width-auto-no: 0;--bslib-value-box-border-width-baseline: 1px}.bslib-value-box{border-width:var(--bslib-value-box-border-width-auto-no, var(--bslib-value-box-border-width-baseline));container-name:bslib-value-box;container-type:inline-size}.bslib-value-box.card{box-shadow:var(--bslib-value-box-shadow)}.bslib-value-box.border-auto{border-width:var(--bslib-value-box-border-width-auto-yes, var(--bslib-value-box-border-width-baseline))}.bslib-value-box.default{--bslib-value-box-bg-default: var(--bs-card-bg, #fff);--bslib-value-box-border-color-default: var(--bs-card-border-color, rgba(0, 0, 0, 0.175));color:var(--bslib-value-box-color);background-color:var(--bslib-value-box-bg, var(--bslib-value-box-bg-default));border-color:var(--bslib-value-box-border-color, var(--bslib-value-box-border-color-default))}.bslib-value-box .value-box-grid{display:grid;grid-template-areas:"left right";align-items:center;overflow:hidden}.bslib-value-box .value-box-showcase{height:100%;max-height:var(---bslib-value-box-showcase-max-h, 100%)}.bslib-value-box .value-box-showcase,.bslib-value-box .value-box-showcase>.html-fill-item{width:100%}.bslib-value-box[data-full-screen=true] .value-box-showcase{max-height:var(---bslib-value-box-showcase-max-h-fs, 100%)}@media screen and (min-width: 575.98px){@container bslib-value-box (max-width: 300px){.bslib-value-box:not(.showcase-bottom) .value-box-grid{grid-template-columns:1fr !important;grid-template-rows:auto auto;grid-template-areas:"top" "bottom"}.bslib-value-box:not(.showcase-bottom) .value-box-grid .value-box-showcase{grid-area:top !important}.bslib-value-box:not(.showcase-bottom) .value-box-grid .value-box-area{grid-area:bottom !important;justify-content:end}}}.bslib-value-box .value-box-area{justify-content:center;padding:1.5rem 1rem;font-size:.9rem;font-weight:500}.bslib-value-box .value-box-area *{margin-bottom:0;margin-top:0}.bslib-value-box .value-box-title{font-size:1rem;margin-top:0;margin-bottom:.5rem;font-weight:400;line-height:1.2}.bslib-value-box .value-box-title:empty::after{content:" "}.bslib-value-box .value-box-value{font-size:calc(1.29rem + 0.48vw);margin-top:0;margin-bottom:.5rem;font-weight:400;line-height:1.2}@media(min-width: 1200px){.bslib-value-box .value-box-value{font-size:1.65rem}}.bslib-value-box .value-box-value:empty::after{content:" "}.bslib-value-box .value-box-showcase{align-items:center;justify-content:center;margin-top:auto;margin-bottom:auto;padding:1rem}.bslib-value-box .value-box-showcase .bi,.bslib-value-box .value-box-showcase .fa,.bslib-value-box .value-box-showcase .fab,.bslib-value-box .value-box-showcase .fas,.bslib-value-box .value-box-showcase .far{opacity:.85;min-width:50px;max-width:125%}.bslib-value-box .value-box-showcase .bi,.bslib-value-box .value-box-showcase .fa,.bslib-value-box .value-box-showcase .fab,.bslib-value-box .value-box-showcase .fas,.bslib-value-box .value-box-showcase .far{font-size:4rem}.bslib-value-box.showcase-top-right .value-box-grid{grid-template-columns:1fr var(---bslib-value-box-showcase-w, 50%)}.bslib-value-box.showcase-top-right .value-box-grid .value-box-showcase{grid-area:right;margin-left:auto;align-self:start;align-items:end;padding-left:0;padding-bottom:0}.bslib-value-box.showcase-top-right .value-box-grid .value-box-area{grid-area:left;align-self:end}.bslib-value-box.showcase-top-right[data-full-screen=true] .value-box-grid{grid-template-columns:auto var(---bslib-value-box-showcase-w-fs, 1fr)}.bslib-value-box.showcase-top-right[data-full-screen=true] .value-box-grid>div{align-self:center}.bslib-value-box.showcase-top-right:not([data-full-screen=true]) .value-box-showcase{margin-top:0}@container bslib-value-box (max-width: 300px){.bslib-value-box.showcase-top-right:not([data-full-screen=true]) .value-box-grid .value-box-showcase{padding-left:1rem}}.bslib-value-box.showcase-left-center .value-box-grid{grid-template-columns:var(---bslib-value-box-showcase-w, 30%) auto}.bslib-value-box.showcase-left-center[data-full-screen=true] .value-box-grid{grid-template-columns:var(---bslib-value-box-showcase-w-fs, 1fr) auto}.bslib-value-box.showcase-left-center:not([data-fill-screen=true]) .value-box-grid .value-box-showcase{grid-area:left}.bslib-value-box.showcase-left-center:not([data-fill-screen=true]) .value-box-grid .value-box-area{grid-area:right}.bslib-value-box.showcase-bottom .value-box-grid{grid-template-columns:1fr;grid-template-rows:1fr var(---bslib-value-box-showcase-h, auto);grid-template-areas:"top" "bottom";overflow:hidden}.bslib-value-box.showcase-bottom .value-box-grid .value-box-showcase{grid-area:bottom;padding:0;margin:0}.bslib-value-box.showcase-bottom .value-box-grid .value-box-area{grid-area:top}.bslib-value-box.showcase-bottom[data-full-screen=true] .value-box-grid{grid-template-rows:1fr var(---bslib-value-box-showcase-h-fs, 2fr)}.bslib-value-box.showcase-bottom[data-full-screen=true] .value-box-grid .value-box-showcase{padding:1rem}[data-bs-theme=dark] .bslib-value-box{--bslib-value-box-shadow: 0 0.5rem 1rem rgb(0 0 0 / 50%)}.accordion .accordion-header{font-size:calc(1.29rem + 0.48vw);margin-top:0;margin-bottom:.5rem;font-weight:400;line-height:1.2;color:var(--bs-heading-color);margin-bottom:0}@media(min-width: 1200px){.accordion .accordion-header{font-size:1.65rem}}.accordion .accordion-icon:not(:empty){margin-right:.75rem;display:flex}.accordion .accordion-button:not(.collapsed){box-shadow:none}.accordion .accordion-button:not(.collapsed):focus{box-shadow:var(--bs-accordion-btn-focus-box-shadow)}.bslib-grid{display:grid !important;gap:var(--bslib-spacer, 1rem);height:var(--bslib-grid-height)}.bslib-grid.grid{grid-template-columns:repeat(var(--bs-columns, 12), minmax(0, 1fr));grid-template-rows:unset;grid-auto-rows:var(--bslib-grid--row-heights);--bslib-grid--row-heights--xs: unset;--bslib-grid--row-heights--sm: unset;--bslib-grid--row-heights--md: unset;--bslib-grid--row-heights--lg: unset;--bslib-grid--row-heights--xl: unset;--bslib-grid--row-heights--xxl: unset}.bslib-grid.grid.bslib-grid--row-heights--xs{--bslib-grid--row-heights: var(--bslib-grid--row-heights--xs)}@media(min-width: 576px){.bslib-grid.grid.bslib-grid--row-heights--sm{--bslib-grid--row-heights: var(--bslib-grid--row-heights--sm)}}@media(min-width: 768px){.bslib-grid.grid.bslib-grid--row-heights--md{--bslib-grid--row-heights: var(--bslib-grid--row-heights--md)}}@media(min-width: 992px){.bslib-grid.grid.bslib-grid--row-heights--lg{--bslib-grid--row-heights: var(--bslib-grid--row-heights--lg)}}@media(min-width: 1200px){.bslib-grid.grid.bslib-grid--row-heights--xl{--bslib-grid--row-heights: var(--bslib-grid--row-heights--xl)}}@media(min-width: 1400px){.bslib-grid.grid.bslib-grid--row-heights--xxl{--bslib-grid--row-heights: var(--bslib-grid--row-heights--xxl)}}.bslib-grid>*>.shiny-input-container{width:100%}.bslib-grid-item{grid-column:auto/span 1}@media(max-width: 767.98px){.bslib-grid-item{grid-column:1/-1}}@media(max-width: 575.98px){.bslib-grid{grid-template-columns:1fr !important;height:var(--bslib-grid-height-mobile)}.bslib-grid.grid{height:unset !important;grid-auto-rows:var(--bslib-grid--row-heights--xs, auto)}}.navbar+.container-fluid:has(>.tab-content>.tab-pane.active.html-fill-container),.navbar+.container-sm:has(>.tab-content>.tab-pane.active.html-fill-container),.navbar+.container-md:has(>.tab-content>.tab-pane.active.html-fill-container),.navbar+.container-lg:has(>.tab-content>.tab-pane.active.html-fill-container),.navbar+.container-xl:has(>.tab-content>.tab-pane.active.html-fill-container),.navbar+.container-xxl:has(>.tab-content>.tab-pane.active.html-fill-container){padding-left:0;padding-right:0}.navbar+.container-fluid>.tab-content>.tab-pane.active.html-fill-container,.navbar+.container-sm>.tab-content>.tab-pane.active.html-fill-container,.navbar+.container-md>.tab-content>.tab-pane.active.html-fill-container,.navbar+.container-lg>.tab-content>.tab-pane.active.html-fill-container,.navbar+.container-xl>.tab-content>.tab-pane.active.html-fill-container,.navbar+.container-xxl>.tab-content>.tab-pane.active.html-fill-container{padding:var(--bslib-spacer, 1rem);gap:var(--bslib-spacer, 1rem)}.navbar+.container-fluid>.tab-content>.tab-pane.active.html-fill-container:has(>.bslib-sidebar-layout:only-child),.navbar+.container-sm>.tab-content>.tab-pane.active.html-fill-container:has(>.bslib-sidebar-layout:only-child),.navbar+.container-md>.tab-content>.tab-pane.active.html-fill-container:has(>.bslib-sidebar-layout:only-child),.navbar+.container-lg>.tab-content>.tab-pane.active.html-fill-container:has(>.bslib-sidebar-layout:only-child),.navbar+.container-xl>.tab-content>.tab-pane.active.html-fill-container:has(>.bslib-sidebar-layout:only-child),.navbar+.container-xxl>.tab-content>.tab-pane.active.html-fill-container:has(>.bslib-sidebar-layout:only-child){padding:0}.navbar+.container-fluid>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border=true]),.navbar+.container-sm>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border=true]),.navbar+.container-md>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border=true]),.navbar+.container-lg>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border=true]),.navbar+.container-xl>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border=true]),.navbar+.container-xxl>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border=true]){border-left:none;border-right:none;border-bottom:none}.navbar+.container-fluid>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border-radius=true]),.navbar+.container-sm>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border-radius=true]),.navbar+.container-md>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border-radius=true]),.navbar+.container-lg>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border-radius=true]),.navbar+.container-xl>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border-radius=true]),.navbar+.container-xxl>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border-radius=true]){border-radius:0}.navbar+div>.bslib-sidebar-layout{border-top:var(--bslib-sidebar-border)}:root{--bslib-page-sidebar-title-bg: #f8f9fa;--bslib-page-sidebar-title-color: #000}.bslib-page-title{background-color:var(--bslib-page-sidebar-title-bg);color:var(--bslib-page-sidebar-title-color);font-size:1.25rem;font-weight:300;padding:var(--bslib-spacer, 1rem);padding-left:1.5rem;margin-bottom:0;border-bottom:1px solid #dee2e6}@media(min-width: 576px){.nav:not(.nav-hidden){display:flex !important;display:-webkit-flex !important}.nav:not(.nav-hidden):not(.nav-stacked):not(.flex-column){float:none !important}.nav:not(.nav-hidden):not(.nav-stacked):not(.flex-column)>.bslib-nav-spacer{margin-left:auto !important}.nav:not(.nav-hidden):not(.nav-stacked):not(.flex-column)>.form-inline{margin-top:auto;margin-bottom:auto}.nav:not(.nav-hidden).nav-stacked{flex-direction:column;-webkit-flex-direction:column;height:100%}.nav:not(.nav-hidden).nav-stacked>.bslib-nav-spacer{margin-top:auto !important}}.bslib-sidebar-layout{--bslib-sidebar-transition-duration: 500ms;--bslib-sidebar-transition-easing-x: cubic-bezier(0.8, 0.78, 0.22, 1.07);--bslib-sidebar-border: var(--bs-card-border-width, 1px) solid var(--bs-card-border-color, rgba(0, 0, 0, 0.175));--bslib-sidebar-border-radius: var(--bs-border-radius);--bslib-sidebar-vert-border: var(--bs-card-border-width, 1px) solid var(--bs-card-border-color, rgba(0, 0, 0, 0.175));--bslib-sidebar-bg: rgba(var(--bs-emphasis-color-rgb, 0, 0, 0), 0.05);--bslib-sidebar-fg: var(--bs-emphasis-color, black);--bslib-sidebar-main-fg: var(--bs-card-color, var(--bs-body-color));--bslib-sidebar-main-bg: var(--bs-card-bg, var(--bs-body-bg));--bslib-sidebar-toggle-bg: rgba(var(--bs-emphasis-color-rgb, 0, 0, 0), 0.1);--bslib-sidebar-padding: calc(var(--bslib-spacer) * 1.5);--bslib-sidebar-icon-size: var(--bslib-spacer, 1rem);--bslib-sidebar-icon-button-size: calc(var(--bslib-sidebar-icon-size, 1rem) * 2);--bslib-sidebar-padding-icon: calc(var(--bslib-sidebar-icon-button-size, 2rem) * 1.5);--bslib-collapse-toggle-border-radius: var(--bs-border-radius, 0.25rem);--bslib-collapse-toggle-transform: 0deg;--bslib-sidebar-toggle-transition-easing: cubic-bezier(1, 0, 0, 1);--bslib-collapse-toggle-right-transform: 180deg;--bslib-sidebar-column-main: minmax(0, 1fr);display:grid !important;grid-template-columns:min(100% - var(--bslib-sidebar-icon-size),var(--bslib-sidebar-width, 250px)) var(--bslib-sidebar-column-main);position:relative;transition:grid-template-columns ease-in-out var(--bslib-sidebar-transition-duration);border:var(--bslib-sidebar-border);border-radius:var(--bslib-sidebar-border-radius)}@media(prefers-reduced-motion: reduce){.bslib-sidebar-layout{transition:none}}.bslib-sidebar-layout[data-bslib-sidebar-border=false]{border:none}.bslib-sidebar-layout[data-bslib-sidebar-border-radius=false]{border-radius:initial}.bslib-sidebar-layout>.main,.bslib-sidebar-layout>.sidebar{grid-row:1/2;border-radius:inherit;overflow:auto}.bslib-sidebar-layout>.main{grid-column:2/3;border-top-left-radius:0;border-bottom-left-radius:0;padding:var(--bslib-sidebar-padding);transition:padding var(--bslib-sidebar-transition-easing-x) var(--bslib-sidebar-transition-duration);color:var(--bslib-sidebar-main-fg);background-color:var(--bslib-sidebar-main-bg)}.bslib-sidebar-layout>.sidebar{grid-column:1/2;width:100%;height:100%;border-right:var(--bslib-sidebar-vert-border);border-top-right-radius:0;border-bottom-right-radius:0;color:var(--bslib-sidebar-fg);background-color:var(--bslib-sidebar-bg);backdrop-filter:blur(5px)}.bslib-sidebar-layout>.sidebar>.sidebar-content{display:flex;flex-direction:column;gap:var(--bslib-spacer, 1rem);padding:var(--bslib-sidebar-padding);padding-top:var(--bslib-sidebar-padding-icon)}.bslib-sidebar-layout>.sidebar>.sidebar-content>:last-child:not(.sidebar-title){margin-bottom:0}.bslib-sidebar-layout>.sidebar>.sidebar-content>.accordion{margin-left:calc(-1*var(--bslib-sidebar-padding));margin-right:calc(-1*var(--bslib-sidebar-padding))}.bslib-sidebar-layout>.sidebar>.sidebar-content>.accordion:last-child{margin-bottom:calc(-1*var(--bslib-sidebar-padding))}.bslib-sidebar-layout>.sidebar>.sidebar-content>.accordion:not(:last-child){margin-bottom:1rem}.bslib-sidebar-layout>.sidebar>.sidebar-content>.accordion .accordion-body{display:flex;flex-direction:column}.bslib-sidebar-layout>.sidebar>.sidebar-content>.accordion:not(:first-child) .accordion-item:first-child{border-top:var(--bs-accordion-border-width) solid var(--bs-accordion-border-color)}.bslib-sidebar-layout>.sidebar>.sidebar-content>.accordion:not(:last-child) .accordion-item:last-child{border-bottom:var(--bs-accordion-border-width) solid var(--bs-accordion-border-color)}.bslib-sidebar-layout>.sidebar>.sidebar-content.has-accordion>.sidebar-title{border-bottom:none;padding-bottom:0}.bslib-sidebar-layout>.sidebar .shiny-input-container{width:100%}.bslib-sidebar-layout[data-bslib-sidebar-open=always]>.sidebar>.sidebar-content{padding-top:var(--bslib-sidebar-padding)}.bslib-sidebar-layout>.collapse-toggle{grid-row:1/2;grid-column:1/2;display:inline-flex;align-items:center;position:absolute;right:calc(var(--bslib-sidebar-icon-size));top:calc(var(--bslib-sidebar-icon-size, 1rem)/2);border:none;border-radius:var(--bslib-collapse-toggle-border-radius);height:var(--bslib-sidebar-icon-button-size, 2rem);width:var(--bslib-sidebar-icon-button-size, 2rem);display:flex;align-items:center;justify-content:center;padding:0;color:var(--bslib-sidebar-fg);background-color:unset;transition:color var(--bslib-sidebar-transition-easing-x) var(--bslib-sidebar-transition-duration),top var(--bslib-sidebar-transition-easing-x) var(--bslib-sidebar-transition-duration),right var(--bslib-sidebar-transition-easing-x) var(--bslib-sidebar-transition-duration),left var(--bslib-sidebar-transition-easing-x) var(--bslib-sidebar-transition-duration)}.bslib-sidebar-layout>.collapse-toggle:hover{background-color:var(--bslib-sidebar-toggle-bg)}.bslib-sidebar-layout>.collapse-toggle>.collapse-icon{opacity:.8;width:var(--bslib-sidebar-icon-size);height:var(--bslib-sidebar-icon-size);transform:rotateY(var(--bslib-collapse-toggle-transform));transition:transform var(--bslib-sidebar-toggle-transition-easing) var(--bslib-sidebar-transition-duration)}.bslib-sidebar-layout>.collapse-toggle:hover>.collapse-icon{opacity:1}.bslib-sidebar-layout .sidebar-title{font-size:1.25rem;line-height:1.25;margin-top:0;margin-bottom:1rem;padding-bottom:1rem;border-bottom:var(--bslib-sidebar-border)}.bslib-sidebar-layout.sidebar-right{grid-template-columns:var(--bslib-sidebar-column-main) min(100% - var(--bslib-sidebar-icon-size),var(--bslib-sidebar-width, 250px))}.bslib-sidebar-layout.sidebar-right>.main{grid-column:1/2;border-top-right-radius:0;border-bottom-right-radius:0;border-top-left-radius:inherit;border-bottom-left-radius:inherit}.bslib-sidebar-layout.sidebar-right>.sidebar{grid-column:2/3;border-right:none;border-left:var(--bslib-sidebar-vert-border);border-top-left-radius:0;border-bottom-left-radius:0}.bslib-sidebar-layout.sidebar-right>.collapse-toggle{grid-column:2/3;left:var(--bslib-sidebar-icon-size);right:unset;border:var(--bslib-collapse-toggle-border)}.bslib-sidebar-layout.sidebar-right>.collapse-toggle>.collapse-icon{transform:rotateY(var(--bslib-collapse-toggle-right-transform))}.bslib-sidebar-layout.sidebar-collapsed{--bslib-collapse-toggle-transform: 180deg;--bslib-collapse-toggle-right-transform: 0deg;--bslib-sidebar-vert-border: none;grid-template-columns:0 minmax(0, 1fr)}.bslib-sidebar-layout.sidebar-collapsed.sidebar-right{grid-template-columns:minmax(0, 1fr) 0}.bslib-sidebar-layout.sidebar-collapsed:not(.transitioning)>.sidebar>*{display:none}.bslib-sidebar-layout.sidebar-collapsed>.main{border-radius:inherit}.bslib-sidebar-layout.sidebar-collapsed:not(.sidebar-right)>.main{padding-left:var(--bslib-sidebar-padding-icon)}.bslib-sidebar-layout.sidebar-collapsed.sidebar-right>.main{padding-right:var(--bslib-sidebar-padding-icon)}.bslib-sidebar-layout.sidebar-collapsed>.collapse-toggle{color:var(--bslib-sidebar-main-fg);top:calc(var(--bslib-sidebar-overlap-counter, 0)*(var(--bslib-sidebar-icon-size) + var(--bslib-sidebar-padding)) + var(--bslib-sidebar-icon-size, 1rem)/2);right:calc(-2.5*var(--bslib-sidebar-icon-size) - var(--bs-card-border-width, 1px))}.bslib-sidebar-layout.sidebar-collapsed.sidebar-right>.collapse-toggle{left:calc(-2.5*var(--bslib-sidebar-icon-size) - var(--bs-card-border-width, 1px));right:unset}@media(min-width: 576px){.bslib-sidebar-layout.transitioning>.sidebar>.sidebar-content{display:none}}@media(max-width: 575.98px){.bslib-sidebar-layout[data-bslib-sidebar-open=desktop]{--bslib-sidebar-js-init-collapsed: true}.bslib-sidebar-layout>.sidebar,.bslib-sidebar-layout.sidebar-right>.sidebar{border:none}.bslib-sidebar-layout>.main,.bslib-sidebar-layout.sidebar-right>.main{grid-column:1/3}.bslib-sidebar-layout[data-bslib-sidebar-open=always]{display:block !important}.bslib-sidebar-layout[data-bslib-sidebar-open=always]>.sidebar{max-height:var(--bslib-sidebar-max-height-mobile);overflow-y:auto;border-top:var(--bslib-sidebar-vert-border)}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]){grid-template-columns:100% 0}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]):not(.sidebar-collapsed)>.sidebar{z-index:1}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]):not(.sidebar-collapsed)>.collapse-toggle{z-index:1}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]).sidebar-right{grid-template-columns:0 100%}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]).sidebar-collapsed{grid-template-columns:0 100%}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]).sidebar-collapsed.sidebar-right{grid-template-columns:100% 0}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]):not(.sidebar-right)>.main{padding-left:var(--bslib-sidebar-padding-icon)}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]).sidebar-right>.main{padding-right:var(--bslib-sidebar-padding-icon)}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always])>.main{opacity:0;transition:opacity var(--bslib-sidebar-transition-easing-x) var(--bslib-sidebar-transition-duration)}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]).sidebar-collapsed>.main{opacity:1}}.bslib-card{overflow:auto}.bslib-card .card-body+.card-body{padding-top:0}.bslib-card .card-body{overflow:auto}.bslib-card .card-body p{margin-top:0}.bslib-card .card-body p:last-child{margin-bottom:0}.bslib-card .card-body{max-height:var(--bslib-card-body-max-height, none)}.bslib-card[data-full-screen=true]>.card-body{max-height:var(--bslib-card-body-max-height-full-screen, none)}.bslib-card .card-header .form-group{margin-bottom:0}.bslib-card .card-header .selectize-control{margin-bottom:0}.bslib-card .card-header .selectize-control .item{margin-right:1.15rem}.bslib-card .card-footer{margin-top:auto}.bslib-card .bslib-navs-card-title{display:flex;flex-wrap:wrap;justify-content:space-between;align-items:center}.bslib-card .bslib-navs-card-title .nav{margin-left:auto}.bslib-card .bslib-sidebar-layout:not([data-bslib-sidebar-border=true]){border:none}.bslib-card .bslib-sidebar-layout:not([data-bslib-sidebar-border-radius=true]){border-top-left-radius:0;border-top-right-radius:0}[data-full-screen=true]{position:fixed;inset:3.5rem 1rem 1rem;height:auto !important;max-height:none !important;width:auto !important;z-index:1070}.bslib-full-screen-enter{display:none;position:absolute;bottom:var(--bslib-full-screen-enter-bottom, 0.2rem);right:var(--bslib-full-screen-enter-right, 0);top:var(--bslib-full-screen-enter-top);left:var(--bslib-full-screen-enter-left);color:var(--bslib-color-fg, var(--bs-card-color));background-color:var(--bslib-color-bg, var(--bs-card-bg, var(--bs-body-bg)));border:var(--bs-card-border-width) solid var(--bslib-color-fg, var(--bs-card-border-color));box-shadow:0 2px 4px rgba(0,0,0,.15);margin:.2rem .4rem;padding:.55rem !important;font-size:.8rem;cursor:pointer;opacity:.7;z-index:1070}.bslib-full-screen-enter:hover{opacity:1}.card[data-full-screen=false]:hover>*>.bslib-full-screen-enter{display:block}.bslib-has-full-screen .card:hover>*>.bslib-full-screen-enter{display:none}@media(max-width: 575.98px){.bslib-full-screen-enter{display:none !important}}.bslib-full-screen-exit{position:relative;top:1.35rem;font-size:.9rem;cursor:pointer;text-decoration:none;display:flex;float:right;margin-right:2.15rem;align-items:center;color:rgba(var(--bs-body-bg-rgb), 0.8)}.bslib-full-screen-exit:hover{color:rgba(var(--bs-body-bg-rgb), 1)}.bslib-full-screen-exit svg{margin-left:.5rem;font-size:1.5rem}#bslib-full-screen-overlay{position:fixed;inset:0;background-color:rgba(var(--bs-body-color-rgb), 0.6);backdrop-filter:blur(2px);-webkit-backdrop-filter:blur(2px);z-index:1069;animation:bslib-full-screen-overlay-enter 400ms cubic-bezier(0.6, 0.02, 0.65, 1) forwards}@keyframes bslib-full-screen-overlay-enter{0%{opacity:0}100%{opacity:1}}html{height:100%}.bslib-page-fill{width:100%;height:100%;margin:0;padding:var(--bslib-spacer, 1rem);gap:var(--bslib-spacer, 1rem)}@media(max-width: 575.98px){.bslib-page-fill{height:var(--bslib-page-fill-mobile-height, auto)}}.html-fill-container{display:flex;flex-direction:column;min-height:0;min-width:0}.html-fill-container>.html-fill-item{flex:1 1 auto;min-height:0;min-width:0}.html-fill-container>:not(.html-fill-item){flex:0 0 auto}.sidebar-item .chapter-number{color:#343a40}.quarto-container{min-height:calc(100vh - 132px)}body.hypothesis-enabled #quarto-header{margin-right:16px}footer.footer .nav-footer,#quarto-header>nav{padding-left:1em;padding-right:1em}footer.footer div.nav-footer p:first-child{margin-top:0}footer.footer div.nav-footer p:last-child{margin-bottom:0}#quarto-content>*{padding-top:14px}#quarto-content>#quarto-sidebar-glass{padding-top:0px}@media(max-width: 991.98px){#quarto-content>*{padding-top:0}#quarto-content .subtitle{padding-top:14px}#quarto-content section:first-of-type h2:first-of-type,#quarto-content section:first-of-type .h2:first-of-type{margin-top:1rem}}.headroom-target,header.headroom{will-change:transform;transition:position 200ms linear;transition:all 200ms linear}header.headroom--pinned{transform:translateY(0%)}header.headroom--unpinned{transform:translateY(-100%)}.navbar-container{width:100%}.navbar-brand{overflow:hidden;text-overflow:ellipsis}.navbar-brand-container{max-width:calc(100% - 115px);min-width:0;display:flex;align-items:center}@media(min-width: 992px){.navbar-brand-container{margin-right:1em}}.navbar-brand.navbar-brand-logo{margin-right:4px;display:inline-flex}.navbar-toggler{flex-basis:content;flex-shrink:0}.navbar .navbar-brand-container{order:2}.navbar .navbar-toggler{order:1}.navbar .navbar-container>.navbar-nav{order:20}.navbar .navbar-container>.navbar-brand-container{margin-left:0 !important;margin-right:0 !important}.navbar .navbar-collapse{order:20}.navbar #quarto-search{order:4;margin-left:auto}.navbar .navbar-toggler{margin-right:.5em}.navbar-collapse .quarto-navbar-tools{margin-left:.5em}.navbar-logo{max-height:24px;width:auto;padding-right:4px}nav .nav-item:not(.compact){padding-top:1px}nav .nav-link i,nav .dropdown-item i{padding-right:1px}.navbar-expand-lg .navbar-nav .nav-link{padding-left:.6rem;padding-right:.6rem}nav .nav-item.compact .nav-link{padding-left:.5rem;padding-right:.5rem;font-size:1.1rem}.navbar .quarto-navbar-tools{order:3}.navbar .quarto-navbar-tools div.dropdown{display:inline-block}.navbar .quarto-navbar-tools .quarto-navigation-tool{color:#545555}.navbar .quarto-navbar-tools .quarto-navigation-tool:hover{color:#1f4eb6}.navbar-nav .dropdown-menu{min-width:220px;font-size:.9rem}.navbar .navbar-nav .nav-link.dropdown-toggle::after{opacity:.75;vertical-align:.175em}.navbar ul.dropdown-menu{padding-top:0;padding-bottom:0}.navbar .dropdown-header{text-transform:uppercase;font-size:.8rem;padding:0 .5rem}.navbar .dropdown-item{padding:.4rem .5rem}.navbar .dropdown-item>i.bi{margin-left:.1rem;margin-right:.25em}.sidebar #quarto-search{margin-top:-1px}.sidebar #quarto-search svg.aa-SubmitIcon{width:16px;height:16px}.sidebar-navigation a{color:inherit}.sidebar-title{margin-top:.25rem;padding-bottom:.5rem;font-size:1.3rem;line-height:1.6rem;visibility:visible}.sidebar-title>a{font-size:inherit;text-decoration:none}.sidebar-title .sidebar-tools-main{margin-top:-6px}@media(max-width: 991.98px){#quarto-sidebar div.sidebar-header{padding-top:.2em}}.sidebar-header-stacked .sidebar-title{margin-top:.6rem}.sidebar-logo{max-width:90%;padding-bottom:.5rem}.sidebar-logo-link{text-decoration:none}.sidebar-navigation li a{text-decoration:none}.sidebar-navigation .quarto-navigation-tool{opacity:.7;font-size:.875rem}#quarto-sidebar>nav>.sidebar-tools-main{margin-left:14px}.sidebar-tools-main{display:inline-flex;margin-left:0px;order:2}.sidebar-tools-main:not(.tools-wide){vertical-align:middle}.sidebar-navigation .quarto-navigation-tool.dropdown-toggle::after{display:none}.sidebar.sidebar-navigation>*{padding-top:1em}.sidebar-item{margin-bottom:.2em;line-height:1rem;margin-top:.4rem}.sidebar-section{padding-left:.5em;padding-bottom:.2em}.sidebar-item .sidebar-item-container{display:flex;justify-content:space-between;cursor:pointer}.sidebar-item-toggle:hover{cursor:pointer}.sidebar-item .sidebar-item-toggle .bi{font-size:.7rem;text-align:center}.sidebar-item .sidebar-item-toggle .bi-chevron-right::before{transition:transform 200ms ease}.sidebar-item .sidebar-item-toggle[aria-expanded=false] .bi-chevron-right::before{transform:none}.sidebar-item .sidebar-item-toggle[aria-expanded=true] .bi-chevron-right::before{transform:rotate(90deg)}.sidebar-item-text{width:100%}.sidebar-navigation .sidebar-divider{margin-left:0;margin-right:0;margin-top:.5rem;margin-bottom:.5rem}@media(max-width: 991.98px){.quarto-secondary-nav{display:block}.quarto-secondary-nav button.quarto-search-button{padding-right:0em;padding-left:2em}.quarto-secondary-nav button.quarto-btn-toggle{margin-left:-0.75rem;margin-right:.15rem}.quarto-secondary-nav nav.quarto-title-breadcrumbs{display:none}.quarto-secondary-nav nav.quarto-page-breadcrumbs{display:flex;align-items:center;padding-right:1em;margin-left:-0.25em}.quarto-secondary-nav nav.quarto-page-breadcrumbs a{text-decoration:none}.quarto-secondary-nav nav.quarto-page-breadcrumbs ol.breadcrumb{margin-bottom:0}}@media(min-width: 992px){.quarto-secondary-nav{display:none}}.quarto-title-breadcrumbs .breadcrumb{margin-bottom:.5em;font-size:.9rem}.quarto-title-breadcrumbs .breadcrumb li:last-of-type a{color:#6c757d}.quarto-secondary-nav .quarto-btn-toggle{color:#595959}.quarto-secondary-nav[aria-expanded=false] .quarto-btn-toggle .bi-chevron-right::before{transform:none}.quarto-secondary-nav[aria-expanded=true] .quarto-btn-toggle .bi-chevron-right::before{transform:rotate(90deg)}.quarto-secondary-nav .quarto-btn-toggle .bi-chevron-right::before{transition:transform 200ms ease}.quarto-secondary-nav{cursor:pointer}.no-decor{text-decoration:none}.quarto-secondary-nav-title{margin-top:.3em;color:#595959;padding-top:4px}.quarto-secondary-nav nav.quarto-page-breadcrumbs{color:#595959}.quarto-secondary-nav nav.quarto-page-breadcrumbs a{color:#595959}.quarto-secondary-nav nav.quarto-page-breadcrumbs a:hover{color:rgba(33,81,191,.8)}.quarto-secondary-nav nav.quarto-page-breadcrumbs .breadcrumb-item::before{color:#8c8c8c}.breadcrumb-item{line-height:1.2rem}div.sidebar-item-container{color:#595959}div.sidebar-item-container:hover,div.sidebar-item-container:focus{color:rgba(33,81,191,.8)}div.sidebar-item-container.disabled{color:rgba(89,89,89,.75)}div.sidebar-item-container .active,div.sidebar-item-container .show>.nav-link,div.sidebar-item-container .sidebar-link>code{color:#2151bf}div.sidebar.sidebar-navigation.rollup.quarto-sidebar-toggle-contents,nav.sidebar.sidebar-navigation:not(.rollup){background-color:#fff}@media(max-width: 991.98px){.sidebar-navigation .sidebar-item a,.nav-page .nav-page-text,.sidebar-navigation{font-size:1rem}.sidebar-navigation ul.sidebar-section.depth1 .sidebar-section-item{font-size:1.1rem}.sidebar-logo{display:none}.sidebar.sidebar-navigation{position:static;border-bottom:1px solid #dee2e6}.sidebar.sidebar-navigation.collapsing{position:fixed;z-index:1000}.sidebar.sidebar-navigation.show{position:fixed;z-index:1000}.sidebar.sidebar-navigation{min-height:100%}nav.quarto-secondary-nav{background-color:#fff;border-bottom:1px solid #dee2e6}.quarto-banner nav.quarto-secondary-nav{background-color:#f8f9fa;color:#545555;border-top:1px solid #dee2e6}.sidebar .sidebar-footer{visibility:visible;padding-top:1rem;position:inherit}.sidebar-tools-collapse{display:block}}#quarto-sidebar{transition:width .15s ease-in}#quarto-sidebar>*{padding-right:1em}@media(max-width: 991.98px){#quarto-sidebar .sidebar-menu-container{white-space:nowrap;min-width:225px}#quarto-sidebar.show{transition:width .15s ease-out}}@media(min-width: 992px){#quarto-sidebar{display:flex;flex-direction:column}.nav-page .nav-page-text,.sidebar-navigation .sidebar-section .sidebar-item{font-size:.875rem}.sidebar-navigation .sidebar-item{font-size:.925rem}.sidebar.sidebar-navigation{display:block;position:sticky}.sidebar-search{width:100%}.sidebar .sidebar-footer{visibility:visible}}@media(min-width: 992px){#quarto-sidebar-glass{display:none}}@media(max-width: 991.98px){#quarto-sidebar-glass{position:fixed;top:0;bottom:0;left:0;right:0;background-color:rgba(255,255,255,0);transition:background-color .15s ease-in;z-index:-1}#quarto-sidebar-glass.collapsing{z-index:1000}#quarto-sidebar-glass.show{transition:background-color .15s ease-out;background-color:rgba(102,102,102,.4);z-index:1000}}.sidebar .sidebar-footer{padding:.5rem 1rem;align-self:flex-end;color:#6c757d;width:100%}.quarto-page-breadcrumbs .breadcrumb-item+.breadcrumb-item,.quarto-page-breadcrumbs .breadcrumb-item{padding-right:.33em;padding-left:0}.quarto-page-breadcrumbs .breadcrumb-item::before{padding-right:.33em}.quarto-sidebar-footer{font-size:.875em}.sidebar-section .bi-chevron-right{vertical-align:middle}.sidebar-section .bi-chevron-right::before{font-size:.9em}.notransition{-webkit-transition:none !important;-moz-transition:none !important;-o-transition:none !important;transition:none !important}.btn:focus:not(:focus-visible){box-shadow:none}.page-navigation{display:flex;justify-content:space-between}.nav-page{padding-bottom:.75em}.nav-page .bi{font-size:1.8rem;vertical-align:middle}.nav-page .nav-page-text{padding-left:.25em;padding-right:.25em}.nav-page a{color:#6c757d;text-decoration:none;display:flex;align-items:center}.nav-page a:hover{color:#1f4eb6}.nav-footer .toc-actions{padding-bottom:.5em;padding-top:.5em}.nav-footer .toc-actions a,.nav-footer .toc-actions a:hover{text-decoration:none}.nav-footer .toc-actions ul{display:flex;list-style:none}.nav-footer .toc-actions ul :first-child{margin-left:auto}.nav-footer .toc-actions ul :last-child{margin-right:auto}.nav-footer .toc-actions ul li{padding-right:1.5em}.nav-footer .toc-actions ul li i.bi{padding-right:.4em}.nav-footer .toc-actions ul li:last-of-type{padding-right:0}.nav-footer{display:flex;flex-direction:row;flex-wrap:wrap;justify-content:space-between;align-items:baseline;text-align:center;padding-top:.5rem;padding-bottom:.5rem;background-color:#fff}body.nav-fixed{padding-top:64px}.nav-footer-contents{color:#6c757d;margin-top:.25rem}.nav-footer{min-height:3.5em;color:#757575}.nav-footer a{color:#757575}.nav-footer .nav-footer-left{font-size:.825em}.nav-footer .nav-footer-center{font-size:.825em}.nav-footer .nav-footer-right{font-size:.825em}.nav-footer-left .footer-items,.nav-footer-center .footer-items,.nav-footer-right .footer-items{display:inline-flex;padding-top:.3em;padding-bottom:.3em;margin-bottom:0em}.nav-footer-left .footer-items .nav-link,.nav-footer-center .footer-items .nav-link,.nav-footer-right .footer-items .nav-link{padding-left:.6em;padding-right:.6em}@media(min-width: 768px){.nav-footer-left{flex:1 1 0px;text-align:left}}@media(max-width: 575.98px){.nav-footer-left{margin-bottom:1em;flex:100%}}@media(min-width: 768px){.nav-footer-right{flex:1 1 0px;text-align:right}}@media(max-width: 575.98px){.nav-footer-right{margin-bottom:1em;flex:100%}}.nav-footer-center{text-align:center;min-height:3em}@media(min-width: 768px){.nav-footer-center{flex:1 1 0px}}.nav-footer-center .footer-items{justify-content:center}@media(max-width: 767.98px){.nav-footer-center{margin-bottom:1em;flex:100%}}@media(max-width: 767.98px){.nav-footer-center{margin-top:3em;order:10}}.navbar .quarto-reader-toggle.reader .quarto-reader-toggle-btn{background-color:#545555;border-radius:3px}@media(max-width: 991.98px){.quarto-reader-toggle{display:none}}.quarto-reader-toggle.reader.quarto-navigation-tool .quarto-reader-toggle-btn{background-color:#595959;border-radius:3px}.quarto-reader-toggle .quarto-reader-toggle-btn{display:inline-flex;padding-left:.2em;padding-right:.2em;margin-left:-0.2em;margin-right:-0.2em;text-align:center}.navbar .quarto-reader-toggle:not(.reader) .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(84, 85, 85, 1)" class="bi bi-body-text" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M0 .5A.5.5 0 0 1 .5 0h4a.5.5 0 0 1 0 1h-4A.5.5 0 0 1 0 .5Zm0 2A.5.5 0 0 1 .5 2h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm9 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-9 2A.5.5 0 0 1 .5 4h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm5 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm-12 2A.5.5 0 0 1 .5 6h6a.5.5 0 0 1 0 1h-6a.5.5 0 0 1-.5-.5Zm8 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-8 2A.5.5 0 0 1 .5 8h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm-7 2a.5.5 0 0 1 .5-.5h8a.5.5 0 0 1 0 1h-8a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h4a.5.5 0 0 1 0 1h-4a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h2a.5.5 0 0 1 0 1h-2a.5.5 0 0 1-.5-.5Z"/></svg>')}.navbar .quarto-reader-toggle.reader .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(248, 249, 250, 1)" class="bi bi-body-text" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M0 .5A.5.5 0 0 1 .5 0h4a.5.5 0 0 1 0 1h-4A.5.5 0 0 1 0 .5Zm0 2A.5.5 0 0 1 .5 2h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm9 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-9 2A.5.5 0 0 1 .5 4h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm5 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm-12 2A.5.5 0 0 1 .5 6h6a.5.5 0 0 1 0 1h-6a.5.5 0 0 1-.5-.5Zm8 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-8 2A.5.5 0 0 1 .5 8h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm-7 2a.5.5 0 0 1 .5-.5h8a.5.5 0 0 1 0 1h-8a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h4a.5.5 0 0 1 0 1h-4a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h2a.5.5 0 0 1 0 1h-2a.5.5 0 0 1-.5-.5Z"/></svg>')}.sidebar-navigation .quarto-reader-toggle:not(.reader) .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(89, 89, 89, 1)" class="bi bi-body-text" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M0 .5A.5.5 0 0 1 .5 0h4a.5.5 0 0 1 0 1h-4A.5.5 0 0 1 0 .5Zm0 2A.5.5 0 0 1 .5 2h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm9 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-9 2A.5.5 0 0 1 .5 4h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm5 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm-12 2A.5.5 0 0 1 .5 6h6a.5.5 0 0 1 0 1h-6a.5.5 0 0 1-.5-.5Zm8 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-8 2A.5.5 0 0 1 .5 8h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm-7 2a.5.5 0 0 1 .5-.5h8a.5.5 0 0 1 0 1h-8a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h4a.5.5 0 0 1 0 1h-4a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h2a.5.5 0 0 1 0 1h-2a.5.5 0 0 1-.5-.5Z"/></svg>')}.sidebar-navigation .quarto-reader-toggle.reader .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(255, 255, 255, 1)" class="bi bi-body-text" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M0 .5A.5.5 0 0 1 .5 0h4a.5.5 0 0 1 0 1h-4A.5.5 0 0 1 0 .5Zm0 2A.5.5 0 0 1 .5 2h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm9 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-9 2A.5.5 0 0 1 .5 4h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm5 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm-12 2A.5.5 0 0 1 .5 6h6a.5.5 0 0 1 0 1h-6a.5.5 0 0 1-.5-.5Zm8 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-8 2A.5.5 0 0 1 .5 8h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm-7 2a.5.5 0 0 1 .5-.5h8a.5.5 0 0 1 0 1h-8a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h4a.5.5 0 0 1 0 1h-4a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h2a.5.5 0 0 1 0 1h-2a.5.5 0 0 1-.5-.5Z"/></svg>')}#quarto-back-to-top{display:none;position:fixed;bottom:50px;background-color:#fff;border-radius:.25rem;box-shadow:0 .2rem .5rem #6c757d,0 0 .05rem #6c757d;color:#6c757d;text-decoration:none;font-size:.9em;text-align:center;left:50%;padding:.4rem .8rem;transform:translate(-50%, 0)}#quarto-announcement{padding:.5em;display:flex;justify-content:space-between;margin-bottom:0;font-size:.9em}#quarto-announcement .quarto-announcement-content{margin-right:auto}#quarto-announcement .quarto-announcement-content p{margin-bottom:0}#quarto-announcement .quarto-announcement-icon{margin-right:.5em;font-size:1.2em;margin-top:-0.15em}#quarto-announcement .quarto-announcement-action{cursor:pointer}.aa-DetachedSearchButtonQuery{display:none}.aa-DetachedOverlay ul.aa-List,#quarto-search-results ul.aa-List{list-style:none;padding-left:0}.aa-DetachedOverlay .aa-Panel,#quarto-search-results .aa-Panel{background-color:#fff;position:absolute;z-index:2000}#quarto-search-results .aa-Panel{max-width:400px}#quarto-search input{font-size:.925rem}@media(min-width: 992px){.navbar #quarto-search{margin-left:.25rem;order:999}}.navbar.navbar-expand-sm #quarto-search,.navbar.navbar-expand-md #quarto-search{order:999}@media(min-width: 992px){.navbar .quarto-navbar-tools{order:900}}@media(min-width: 992px){.navbar .quarto-navbar-tools.tools-end{margin-left:auto !important}}@media(max-width: 991.98px){#quarto-sidebar .sidebar-search{display:none}}#quarto-sidebar .sidebar-search .aa-Autocomplete{width:100%}.navbar .aa-Autocomplete .aa-Form{width:180px}.navbar #quarto-search.type-overlay .aa-Autocomplete{width:40px}.navbar #quarto-search.type-overlay .aa-Autocomplete .aa-Form{background-color:inherit;border:none}.navbar #quarto-search.type-overlay .aa-Autocomplete .aa-Form:focus-within{box-shadow:none;outline:none}.navbar #quarto-search.type-overlay .aa-Autocomplete .aa-Form .aa-InputWrapper{display:none}.navbar #quarto-search.type-overlay .aa-Autocomplete .aa-Form .aa-InputWrapper:focus-within{display:inherit}.navbar #quarto-search.type-overlay .aa-Autocomplete .aa-Form .aa-Label svg,.navbar #quarto-search.type-overlay .aa-Autocomplete .aa-Form .aa-LoadingIndicator svg{width:26px;height:26px;color:#545555;opacity:1}.navbar #quarto-search.type-overlay .aa-Autocomplete svg.aa-SubmitIcon{width:26px;height:26px;color:#545555;opacity:1}.aa-Autocomplete .aa-Form,.aa-DetachedFormContainer .aa-Form{align-items:center;background-color:#fff;border:1px solid #dee2e6;border-radius:.25rem;color:#343a40;display:flex;line-height:1em;margin:0;position:relative;width:100%}.aa-Autocomplete .aa-Form:focus-within,.aa-DetachedFormContainer .aa-Form:focus-within{box-shadow:rgba(39,128,227,.6) 0 0 0 1px;outline:currentColor none medium}.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix{align-items:center;display:flex;flex-shrink:0;order:1}.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix .aa-Label,.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix .aa-Label,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator{cursor:initial;flex-shrink:0;padding:0;text-align:left}.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix .aa-Label svg,.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator svg,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix .aa-Label svg,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator svg{color:#343a40;opacity:.5}.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix .aa-SubmitButton,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix .aa-SubmitButton{appearance:none;background:none;border:0;margin:0}.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator{align-items:center;display:flex;justify-content:center}.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator[hidden],.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator[hidden]{display:none}.aa-Autocomplete .aa-Form .aa-InputWrapper,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper{order:3;position:relative;width:100%}.aa-Autocomplete .aa-Form .aa-InputWrapper .aa-Input,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input{appearance:none;background:none;border:0;color:#343a40;font:inherit;height:calc(1.5em + .1rem + 2px);padding:0;width:100%}.aa-Autocomplete .aa-Form .aa-InputWrapper .aa-Input::placeholder,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input::placeholder{color:#343a40;opacity:.8}.aa-Autocomplete .aa-Form .aa-InputWrapper .aa-Input:focus,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input:focus{border-color:none;box-shadow:none;outline:none}.aa-Autocomplete .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-decoration,.aa-Autocomplete .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-cancel-button,.aa-Autocomplete .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-results-button,.aa-Autocomplete .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-results-decoration,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-decoration,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-cancel-button,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-results-button,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-results-decoration{display:none}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix{align-items:center;display:flex;order:4}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-ClearButton,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-ClearButton{align-items:center;background:none;border:0;color:#343a40;opacity:.8;cursor:pointer;display:flex;margin:0;width:calc(1.5em + .1rem + 2px)}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-ClearButton:hover,.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-ClearButton:focus,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-ClearButton:hover,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-ClearButton:focus{color:#343a40;opacity:.8}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-ClearButton[hidden],.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-ClearButton[hidden]{display:none}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-ClearButton svg,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-ClearButton svg{width:calc(1.5em + 0.75rem + calc(1px * 2))}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-CopyButton,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-CopyButton{border:none;align-items:center;background:none;color:#343a40;opacity:.4;font-size:.7rem;cursor:pointer;display:none;margin:0;width:calc(1em + .1rem + 2px)}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-CopyButton:hover,.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-CopyButton:focus,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-CopyButton:hover,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-CopyButton:focus{color:#343a40;opacity:.8}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-CopyButton[hidden],.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-CopyButton[hidden]{display:none}.aa-PanelLayout:empty{display:none}.quarto-search-no-results.no-query{display:none}.aa-Source:has(.no-query){display:none}#quarto-search-results .aa-Panel{border:solid #dee2e6 1px}#quarto-search-results .aa-SourceNoResults{width:398px}.aa-DetachedOverlay .aa-Panel,#quarto-search-results .aa-Panel{max-height:65vh;overflow-y:auto;font-size:.925rem}.aa-DetachedOverlay .aa-SourceNoResults,#quarto-search-results .aa-SourceNoResults{height:60px;display:flex;justify-content:center;align-items:center}.aa-DetachedOverlay .search-error,#quarto-search-results .search-error{padding-top:10px;padding-left:20px;padding-right:20px;cursor:default}.aa-DetachedOverlay .search-error .search-error-title,#quarto-search-results .search-error .search-error-title{font-size:1.1rem;margin-bottom:.5rem}.aa-DetachedOverlay .search-error .search-error-title .search-error-icon,#quarto-search-results .search-error .search-error-title .search-error-icon{margin-right:8px}.aa-DetachedOverlay .search-error .search-error-text,#quarto-search-results .search-error .search-error-text{font-weight:300}.aa-DetachedOverlay .search-result-text,#quarto-search-results .search-result-text{font-weight:300;overflow:hidden;text-overflow:ellipsis;display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;line-height:1.2rem;max-height:2.4rem}.aa-DetachedOverlay .aa-SourceHeader .search-result-header,#quarto-search-results .aa-SourceHeader .search-result-header{font-size:.875rem;background-color:#f2f2f2;padding-left:14px;padding-bottom:4px;padding-top:4px}.aa-DetachedOverlay .aa-SourceHeader .search-result-header-no-results,#quarto-search-results .aa-SourceHeader .search-result-header-no-results{display:none}.aa-DetachedOverlay .aa-SourceFooter .algolia-search-logo,#quarto-search-results .aa-SourceFooter .algolia-search-logo{width:110px;opacity:.85;margin:8px;float:right}.aa-DetachedOverlay .search-result-section,#quarto-search-results .search-result-section{font-size:.925em}.aa-DetachedOverlay a.search-result-link,#quarto-search-results a.search-result-link{color:inherit;text-decoration:none}.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item,#quarto-search-results li.aa-Item[aria-selected=true] .search-item{background-color:#2780e3}.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item.search-result-more,.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item .search-result-section,.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item .search-result-text,.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item .search-result-title-container,.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item .search-result-text-container,#quarto-search-results li.aa-Item[aria-selected=true] .search-item.search-result-more,#quarto-search-results li.aa-Item[aria-selected=true] .search-item .search-result-section,#quarto-search-results li.aa-Item[aria-selected=true] .search-item .search-result-text,#quarto-search-results li.aa-Item[aria-selected=true] .search-item .search-result-title-container,#quarto-search-results li.aa-Item[aria-selected=true] .search-item .search-result-text-container{color:#fff;background-color:#2780e3}.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item mark.search-match,.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item .search-match.mark,#quarto-search-results li.aa-Item[aria-selected=true] .search-item mark.search-match,#quarto-search-results li.aa-Item[aria-selected=true] .search-item .search-match.mark{color:#fff;background-color:#4b95e8}.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item,#quarto-search-results li.aa-Item[aria-selected=false] .search-item{background-color:#fff}.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item.search-result-more,.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item .search-result-section,.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item .search-result-text,.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item .search-result-title-container,.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item .search-result-text-container,#quarto-search-results li.aa-Item[aria-selected=false] .search-item.search-result-more,#quarto-search-results li.aa-Item[aria-selected=false] .search-item .search-result-section,#quarto-search-results li.aa-Item[aria-selected=false] .search-item .search-result-text,#quarto-search-results li.aa-Item[aria-selected=false] .search-item .search-result-title-container,#quarto-search-results li.aa-Item[aria-selected=false] .search-item .search-result-text-container{color:#343a40}.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item mark.search-match,.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item .search-match.mark,#quarto-search-results li.aa-Item[aria-selected=false] .search-item mark.search-match,#quarto-search-results li.aa-Item[aria-selected=false] .search-item .search-match.mark{color:inherit;background-color:#e5effc}.aa-DetachedOverlay .aa-Item .search-result-doc:not(.document-selectable) .search-result-title-container,#quarto-search-results .aa-Item .search-result-doc:not(.document-selectable) .search-result-title-container{background-color:#fff;color:#343a40}.aa-DetachedOverlay .aa-Item .search-result-doc:not(.document-selectable) .search-result-text-container,#quarto-search-results .aa-Item .search-result-doc:not(.document-selectable) .search-result-text-container{padding-top:0px}.aa-DetachedOverlay li.aa-Item .search-result-doc.document-selectable .search-result-text-container,#quarto-search-results li.aa-Item .search-result-doc.document-selectable .search-result-text-container{margin-top:-4px}.aa-DetachedOverlay .aa-Item,#quarto-search-results .aa-Item{cursor:pointer}.aa-DetachedOverlay .aa-Item .search-item,#quarto-search-results .aa-Item .search-item{border-left:none;border-right:none;border-top:none;background-color:#fff;border-color:#dee2e6;color:#343a40}.aa-DetachedOverlay .aa-Item .search-item p,#quarto-search-results .aa-Item .search-item p{margin-top:0;margin-bottom:0}.aa-DetachedOverlay .aa-Item .search-item i.bi,#quarto-search-results .aa-Item .search-item i.bi{padding-left:8px;padding-right:8px;font-size:1.3em}.aa-DetachedOverlay .aa-Item .search-item .search-result-title,#quarto-search-results .aa-Item .search-item .search-result-title{margin-top:.3em;margin-bottom:0em}.aa-DetachedOverlay .aa-Item .search-item .search-result-crumbs,#quarto-search-results .aa-Item .search-item .search-result-crumbs{white-space:nowrap;text-overflow:ellipsis;font-size:.8em;font-weight:300;margin-right:1em}.aa-DetachedOverlay .aa-Item .search-item .search-result-crumbs:not(.search-result-crumbs-wrap),#quarto-search-results .aa-Item .search-item .search-result-crumbs:not(.search-result-crumbs-wrap){max-width:30%;margin-left:auto;margin-top:.5em;margin-bottom:.1rem}.aa-DetachedOverlay .aa-Item .search-item .search-result-crumbs.search-result-crumbs-wrap,#quarto-search-results .aa-Item .search-item .search-result-crumbs.search-result-crumbs-wrap{flex-basis:100%;margin-top:0em;margin-bottom:.2em;margin-left:37px}.aa-DetachedOverlay .aa-Item .search-result-title-container,#quarto-search-results .aa-Item .search-result-title-container{font-size:1em;display:flex;flex-wrap:wrap;padding:6px 4px 6px 4px}.aa-DetachedOverlay .aa-Item .search-result-text-container,#quarto-search-results .aa-Item .search-result-text-container{padding-bottom:8px;padding-right:8px;margin-left:42px}.aa-DetachedOverlay .aa-Item .search-result-doc-section,.aa-DetachedOverlay .aa-Item .search-result-more,#quarto-search-results .aa-Item .search-result-doc-section,#quarto-search-results .aa-Item .search-result-more{padding-top:8px;padding-bottom:8px;padding-left:44px}.aa-DetachedOverlay .aa-Item .search-result-more,#quarto-search-results .aa-Item .search-result-more{font-size:.8em;font-weight:400}.aa-DetachedOverlay .aa-Item .search-result-doc,#quarto-search-results .aa-Item .search-result-doc{border-top:1px solid #dee2e6}.aa-DetachedSearchButton{background:none;border:none}.aa-DetachedSearchButton .aa-DetachedSearchButtonPlaceholder{display:none}.navbar .aa-DetachedSearchButton .aa-DetachedSearchButtonIcon{color:#545555}.sidebar-tools-collapse #quarto-search,.sidebar-tools-main #quarto-search{display:inline}.sidebar-tools-collapse #quarto-search .aa-Autocomplete,.sidebar-tools-main #quarto-search .aa-Autocomplete{display:inline}.sidebar-tools-collapse #quarto-search .aa-DetachedSearchButton,.sidebar-tools-main #quarto-search .aa-DetachedSearchButton{padding-left:4px;padding-right:4px}.sidebar-tools-collapse #quarto-search .aa-DetachedSearchButton .aa-DetachedSearchButtonIcon,.sidebar-tools-main #quarto-search .aa-DetachedSearchButton .aa-DetachedSearchButtonIcon{color:#595959}.sidebar-tools-collapse #quarto-search .aa-DetachedSearchButton .aa-DetachedSearchButtonIcon .aa-SubmitIcon,.sidebar-tools-main #quarto-search .aa-DetachedSearchButton .aa-DetachedSearchButtonIcon .aa-SubmitIcon{margin-top:-3px}.aa-DetachedContainer{background:rgba(255,255,255,.65);width:90%;bottom:0;box-shadow:rgba(222,226,230,.6) 0 0 0 1px;outline:currentColor none medium;display:flex;flex-direction:column;left:0;margin:0;overflow:hidden;padding:0;position:fixed;right:0;top:0;z-index:1101}.aa-DetachedContainer::after{height:32px}.aa-DetachedContainer .aa-SourceHeader{margin:var(--aa-spacing-half) 0 var(--aa-spacing-half) 2px}.aa-DetachedContainer .aa-Panel{background-color:#fff;border-radius:0;box-shadow:none;flex-grow:1;margin:0;padding:0;position:relative}.aa-DetachedContainer .aa-PanelLayout{bottom:0;box-shadow:none;left:0;margin:0;max-height:none;overflow-y:auto;position:absolute;right:0;top:0;width:100%}.aa-DetachedFormContainer{background-color:#fff;border-bottom:1px solid #dee2e6;display:flex;flex-direction:row;justify-content:space-between;margin:0;padding:.5em}.aa-DetachedCancelButton{background:none;font-size:.8em;border:0;border-radius:3px;color:#343a40;cursor:pointer;margin:0 0 0 .5em;padding:0 .5em}.aa-DetachedCancelButton:hover,.aa-DetachedCancelButton:focus{box-shadow:rgba(39,128,227,.6) 0 0 0 1px;outline:currentColor none medium}.aa-DetachedContainer--modal{bottom:inherit;height:auto;margin:0 auto;position:absolute;top:100px;border-radius:6px;max-width:850px}@media(max-width: 575.98px){.aa-DetachedContainer--modal{width:100%;top:0px;border-radius:0px;border:none}}.aa-DetachedContainer--modal .aa-PanelLayout{max-height:var(--aa-detached-modal-max-height);padding-bottom:var(--aa-spacing-half);position:static}.aa-Detached{height:100vh;overflow:hidden}.aa-DetachedOverlay{background-color:rgba(52,58,64,.4);position:fixed;left:0;right:0;top:0;margin:0;padding:0;height:100vh;z-index:1100}.quarto-dashboard.nav-fixed.dashboard-sidebar #quarto-content.quarto-dashboard-content{padding:0em}.quarto-dashboard #quarto-content.quarto-dashboard-content{padding:1em}.quarto-dashboard #quarto-content.quarto-dashboard-content>*{padding-top:0}@media(min-width: 576px){.quarto-dashboard{height:100%}}.quarto-dashboard .card.valuebox.bslib-card.bg-primary{background-color:#5397e9 !important}.quarto-dashboard .card.valuebox.bslib-card.bg-secondary{background-color:#343a40 !important}.quarto-dashboard .card.valuebox.bslib-card.bg-success{background-color:#3aa716 !important}.quarto-dashboard .card.valuebox.bslib-card.bg-info{background-color:rgba(153,84,187,.7019607843) !important}.quarto-dashboard .card.valuebox.bslib-card.bg-warning{background-color:#fa6400 !important}.quarto-dashboard .card.valuebox.bslib-card.bg-danger{background-color:rgba(255,0,57,.7019607843) !important}.quarto-dashboard .card.valuebox.bslib-card.bg-light{background-color:#f8f9fa !important}.quarto-dashboard .card.valuebox.bslib-card.bg-dark{background-color:#343a40 !important}.quarto-dashboard.dashboard-fill{display:flex;flex-direction:column}.quarto-dashboard #quarto-appendix{display:none}.quarto-dashboard #quarto-header #quarto-dashboard-header{border-top:solid 1px #dae0e5;border-bottom:solid 1px #dae0e5}.quarto-dashboard #quarto-header #quarto-dashboard-header>nav{padding-left:1em;padding-right:1em}.quarto-dashboard #quarto-header #quarto-dashboard-header>nav .navbar-brand-container{padding-left:0}.quarto-dashboard #quarto-header #quarto-dashboard-header .navbar-toggler{margin-right:0}.quarto-dashboard #quarto-header #quarto-dashboard-header .navbar-toggler-icon{height:1em;width:1em;background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(84, 85, 85)" class="bi bi-menu-button-wide" viewBox="0 0 16 16"><path d="M0 1.5A1.5 1.5 0 0 1 1.5 0h13A1.5 1.5 0 0 1 16 1.5v2A1.5 1.5 0 0 1 14.5 5h-13A1.5 1.5 0 0 1 0 3.5v-2zM1.5 1a.5.5 0 0 0-.5.5v2a.5.5 0 0 0 .5.5h13a.5.5 0 0 0 .5-.5v-2a.5.5 0 0 0-.5-.5h-13z"/><path d="M2 2.5a.5.5 0 0 1 .5-.5h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5zm10.823.323-.396-.396A.25.25 0 0 1 12.604 2h.792a.25.25 0 0 1 .177.427l-.396.396a.25.25 0 0 1-.354 0zM0 8a2 2 0 0 1 2-2h12a2 2 0 0 1 2 2v5a2 2 0 0 1-2 2H2a2 2 0 0 1-2-2V8zm1 3v2a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-2H1zm14-1V8a1 1 0 0 0-1-1H2a1 1 0 0 0-1 1v2h14zM2 8.5a.5.5 0 0 1 .5-.5h9a.5.5 0 0 1 0 1h-9a.5.5 0 0 1-.5-.5zm0 4a.5.5 0 0 1 .5-.5h6a.5.5 0 0 1 0 1h-6a.5.5 0 0 1-.5-.5z"/></svg>')}.quarto-dashboard #quarto-header #quarto-dashboard-header .navbar-brand-container{padding-right:1em}.quarto-dashboard #quarto-header #quarto-dashboard-header .navbar-title{font-size:1.1em}.quarto-dashboard #quarto-header #quarto-dashboard-header .navbar-nav{font-size:.9em}.quarto-dashboard #quarto-dashboard-header .navbar{padding:0}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-container{padding-left:1em}.quarto-dashboard #quarto-dashboard-header .navbar.slim .navbar-brand-container .nav-link,.quarto-dashboard #quarto-dashboard-header .navbar.slim .navbar-nav .nav-link{padding:.7em}.quarto-dashboard #quarto-dashboard-header .navbar .quarto-color-scheme-toggle{order:9}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-toggler{margin-left:.5em;order:10}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-nav .nav-link{padding:.5em;height:100%;display:flex;align-items:center}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-nav .active{background-color:#e0e5e9}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-brand-container{padding:.5em .5em .5em 0;display:flex;flex-direction:row;margin-right:2em;align-items:center}@media(max-width: 767.98px){.quarto-dashboard #quarto-dashboard-header .navbar .navbar-brand-container{margin-right:auto}}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-collapse{align-self:stretch}@media(min-width: 768px){.quarto-dashboard #quarto-dashboard-header .navbar .navbar-collapse{order:8}}@media(max-width: 767.98px){.quarto-dashboard #quarto-dashboard-header .navbar .navbar-collapse{order:1000;padding-bottom:.5em}}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-collapse .navbar-nav{align-self:stretch}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-title{font-size:1.25em;line-height:1.1em;display:flex;flex-direction:row;flex-wrap:wrap;align-items:baseline}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-title .navbar-title-text{margin-right:.4em}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-title a{text-decoration:none;color:inherit}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-subtitle,.quarto-dashboard #quarto-dashboard-header .navbar .navbar-author{font-size:.9rem;margin-right:.5em}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-author{margin-left:auto}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-logo{max-height:48px;min-height:30px;object-fit:cover;margin-right:1em}.quarto-dashboard #quarto-dashboard-header .navbar .quarto-dashboard-links{order:9;padding-right:1em}.quarto-dashboard #quarto-dashboard-header .navbar .quarto-dashboard-link-text{margin-left:.25em}.quarto-dashboard #quarto-dashboard-header .navbar .quarto-dashboard-link{padding-right:0em;padding-left:.7em;text-decoration:none;color:#545555}.quarto-dashboard .page-layout-custom .tab-content{padding:0;border:none}.quarto-dashboard-img-contain{height:100%;width:100%;object-fit:contain}@media(max-width: 575.98px){.quarto-dashboard .bslib-grid{grid-template-rows:minmax(1em, max-content) !important}.quarto-dashboard .sidebar-content{height:inherit}.quarto-dashboard .page-layout-custom{min-height:100vh}}.quarto-dashboard.dashboard-toolbar>.page-layout-custom,.quarto-dashboard.dashboard-sidebar>.page-layout-custom{padding:0}.quarto-dashboard .quarto-dashboard-content.quarto-dashboard-pages{padding:0}.quarto-dashboard .callout{margin-bottom:0;margin-top:0}.quarto-dashboard .html-fill-container figure{overflow:hidden}.quarto-dashboard bslib-tooltip .rounded-pill{border:solid #6c757d 1px}.quarto-dashboard bslib-tooltip .rounded-pill .svg{fill:#343a40}.quarto-dashboard .tabset .dashboard-card-no-title .nav-tabs{margin-left:0;margin-right:auto}.quarto-dashboard .tabset .tab-content{border:none}.quarto-dashboard .tabset .card-header .nav-link[role=tab]{margin-top:-6px;padding-top:6px;padding-bottom:6px}.quarto-dashboard .card.valuebox,.quarto-dashboard .card.bslib-value-box{min-height:3rem}.quarto-dashboard .card.valuebox .card-body,.quarto-dashboard .card.bslib-value-box .card-body{padding:0}.quarto-dashboard .bslib-value-box .value-box-value{font-size:clamp(.1em,15cqw,5em)}.quarto-dashboard .bslib-value-box .value-box-showcase .bi{font-size:clamp(.1em,max(18cqw,5.2cqh),5em);text-align:center;height:1em}.quarto-dashboard .bslib-value-box .value-box-showcase .bi::before{vertical-align:1em}.quarto-dashboard .bslib-value-box .value-box-area{margin-top:auto;margin-bottom:auto}.quarto-dashboard .card figure.quarto-float{display:flex;flex-direction:column;align-items:center}.quarto-dashboard .dashboard-scrolling{padding:1em}.quarto-dashboard .full-height{height:100%}.quarto-dashboard .showcase-bottom .value-box-grid{display:grid;grid-template-columns:1fr;grid-template-rows:1fr auto;grid-template-areas:"top" "bottom"}.quarto-dashboard .showcase-bottom .value-box-grid .value-box-showcase{grid-area:bottom;padding:0;margin:0}.quarto-dashboard .showcase-bottom .value-box-grid .value-box-showcase i.bi{font-size:4rem}.quarto-dashboard .showcase-bottom .value-box-grid .value-box-area{grid-area:top}.quarto-dashboard .tab-content{margin-bottom:0}.quarto-dashboard .bslib-card .bslib-navs-card-title{justify-content:stretch;align-items:end}.quarto-dashboard .card-header{display:flex;flex-wrap:wrap;justify-content:space-between}.quarto-dashboard .card-header .card-title{display:flex;flex-direction:column;justify-content:center;margin-bottom:0}.quarto-dashboard .tabset .card-toolbar{margin-bottom:1em}.quarto-dashboard .bslib-grid>.bslib-sidebar-layout{border:none;gap:var(--bslib-spacer, 1rem)}.quarto-dashboard .bslib-grid>.bslib-sidebar-layout>.main{padding:0}.quarto-dashboard .bslib-grid>.bslib-sidebar-layout>.sidebar{border-radius:.25rem;border:1px solid rgba(0,0,0,.175)}.quarto-dashboard .bslib-grid>.bslib-sidebar-layout>.collapse-toggle{display:none}@media(max-width: 767.98px){.quarto-dashboard .bslib-grid>.bslib-sidebar-layout{grid-template-columns:1fr;grid-template-rows:max-content 1fr}.quarto-dashboard .bslib-grid>.bslib-sidebar-layout>.main{grid-column:1;grid-row:2}.quarto-dashboard .bslib-grid>.bslib-sidebar-layout .sidebar{grid-column:1;grid-row:1}}.quarto-dashboard .sidebar-right .sidebar{padding-left:2.5em}.quarto-dashboard .sidebar-right .collapse-toggle{left:2px}.quarto-dashboard .quarto-dashboard .sidebar-right button.collapse-toggle:not(.transitioning){left:unset}.quarto-dashboard aside.sidebar{padding-left:1em;padding-right:1em;background-color:rgba(52,58,64,.25);color:#343a40}.quarto-dashboard .bslib-sidebar-layout>div.main{padding:.7em}.quarto-dashboard .bslib-sidebar-layout button.collapse-toggle{margin-top:.3em}.quarto-dashboard .bslib-sidebar-layout .collapse-toggle{top:0}.quarto-dashboard .bslib-sidebar-layout.sidebar-collapsed:not(.transitioning):not(.sidebar-right) .collapse-toggle{left:2px}.quarto-dashboard .sidebar>section>.h3:first-of-type{margin-top:0em}.quarto-dashboard .sidebar .h3,.quarto-dashboard .sidebar .h4,.quarto-dashboard .sidebar .h5,.quarto-dashboard .sidebar .h6{margin-top:.5em}.quarto-dashboard .sidebar form{flex-direction:column;align-items:start;margin-bottom:1em}.quarto-dashboard .sidebar form div[class*=oi-][class$=-input]{flex-direction:column}.quarto-dashboard .sidebar form[class*=oi-][class$=-toggle]{flex-direction:row-reverse;align-items:center;justify-content:start}.quarto-dashboard .sidebar form input[type=range]{margin-top:.5em;margin-right:.8em;margin-left:1em}.quarto-dashboard .sidebar label{width:fit-content}.quarto-dashboard .sidebar .card-body{margin-bottom:2em}.quarto-dashboard .sidebar .shiny-input-container{margin-bottom:1em}.quarto-dashboard .sidebar .shiny-options-group{margin-top:0}.quarto-dashboard .sidebar .control-label{margin-bottom:.3em}.quarto-dashboard .card .card-body .quarto-layout-row{align-items:stretch}.quarto-dashboard .toolbar{font-size:.9em;display:flex;flex-direction:row;border-top:solid 1px #bcbfc0;padding:1em;flex-wrap:wrap;background-color:rgba(52,58,64,.25)}.quarto-dashboard .toolbar .cell-output-display{display:flex}.quarto-dashboard .toolbar .shiny-input-container{padding-bottom:.5em;margin-bottom:.5em;width:inherit}.quarto-dashboard .toolbar .shiny-input-container>.checkbox:first-child{margin-top:6px}.quarto-dashboard .toolbar>*:last-child{margin-right:0}.quarto-dashboard .toolbar>*>*{margin-right:1em;align-items:baseline}.quarto-dashboard .toolbar>*>*>a{text-decoration:none;margin-top:auto;margin-bottom:auto}.quarto-dashboard .toolbar .shiny-input-container{padding-bottom:0;margin-bottom:0}.quarto-dashboard .toolbar .shiny-input-container>*{flex-shrink:0;flex-grow:0}.quarto-dashboard .toolbar .form-group.shiny-input-container:not([role=group])>label{margin-bottom:0}.quarto-dashboard .toolbar .shiny-input-container.no-baseline{align-items:start;padding-top:6px}.quarto-dashboard .toolbar .shiny-input-container{display:flex;align-items:baseline}.quarto-dashboard .toolbar .shiny-input-container label{padding-right:.4em}.quarto-dashboard .toolbar .shiny-input-container .bslib-input-switch{margin-top:6px}.quarto-dashboard .toolbar input[type=text]{line-height:1;width:inherit}.quarto-dashboard .toolbar .input-daterange{width:inherit}.quarto-dashboard .toolbar .input-daterange input[type=text]{height:2.4em;width:10em}.quarto-dashboard .toolbar .input-daterange .input-group-addon{height:auto;padding:0;margin-left:-5px !important;margin-right:-5px}.quarto-dashboard .toolbar .input-daterange .input-group-addon .input-group-text{padding-top:0;padding-bottom:0;height:100%}.quarto-dashboard .toolbar span.irs.irs--shiny{width:10em}.quarto-dashboard .toolbar span.irs.irs--shiny .irs-line{top:9px}.quarto-dashboard .toolbar span.irs.irs--shiny .irs-min,.quarto-dashboard .toolbar span.irs.irs--shiny .irs-max,.quarto-dashboard .toolbar span.irs.irs--shiny .irs-from,.quarto-dashboard .toolbar span.irs.irs--shiny .irs-to,.quarto-dashboard .toolbar span.irs.irs--shiny .irs-single{top:20px}.quarto-dashboard .toolbar span.irs.irs--shiny .irs-bar{top:8px}.quarto-dashboard .toolbar span.irs.irs--shiny .irs-handle{top:0px}.quarto-dashboard .toolbar .shiny-input-checkboxgroup>label{margin-top:6px}.quarto-dashboard .toolbar .shiny-input-checkboxgroup>.shiny-options-group{margin-top:0;align-items:baseline}.quarto-dashboard .toolbar .shiny-input-radiogroup>label{margin-top:6px}.quarto-dashboard .toolbar .shiny-input-radiogroup>.shiny-options-group{align-items:baseline;margin-top:0}.quarto-dashboard .toolbar .shiny-input-radiogroup>.shiny-options-group>.radio{margin-right:.3em}.quarto-dashboard .toolbar .form-select{padding-top:.2em;padding-bottom:.2em}.quarto-dashboard .toolbar .shiny-input-select{min-width:6em}.quarto-dashboard .toolbar div.checkbox{margin-bottom:0px}.quarto-dashboard .toolbar>.checkbox:first-child{margin-top:6px}.quarto-dashboard .toolbar form{width:fit-content}.quarto-dashboard .toolbar form label{padding-top:.2em;padding-bottom:.2em;width:fit-content}.quarto-dashboard .toolbar form input[type=date]{width:fit-content}.quarto-dashboard .toolbar form input[type=color]{width:3em}.quarto-dashboard .toolbar form button{padding:.4em}.quarto-dashboard .toolbar form select{width:fit-content}.quarto-dashboard .toolbar>*{font-size:.9em;flex-grow:0}.quarto-dashboard .toolbar .shiny-input-container label{margin-bottom:1px}.quarto-dashboard .toolbar-bottom{margin-top:1em;margin-bottom:0 !important;order:2}.quarto-dashboard .quarto-dashboard-content>.dashboard-toolbar-container>.toolbar-content>.tab-content>.tab-pane>*:not(.bslib-sidebar-layout){padding:1em}.quarto-dashboard .quarto-dashboard-content>.dashboard-toolbar-container>.toolbar-content>*:not(.tab-content){padding:1em}.quarto-dashboard .quarto-dashboard-content>.tab-content>.dashboard-page>.dashboard-toolbar-container>.toolbar-content,.quarto-dashboard .quarto-dashboard-content>.tab-content>.dashboard-page:not(.dashboard-sidebar-container)>*:not(.dashboard-toolbar-container){padding:1em}.quarto-dashboard .toolbar-content{padding:0}.quarto-dashboard .quarto-dashboard-content.quarto-dashboard-pages .tab-pane>.dashboard-toolbar-container .toolbar{border-radius:0;margin-bottom:0}.quarto-dashboard .dashboard-toolbar-container.toolbar-toplevel .toolbar{border-bottom:1px solid rgba(0,0,0,.175)}.quarto-dashboard .dashboard-toolbar-container.toolbar-toplevel .toolbar-bottom{margin-top:0}.quarto-dashboard .dashboard-toolbar-container:not(.toolbar-toplevel) .toolbar{margin-bottom:1em;border-top:none;border-radius:.25rem;border:1px solid rgba(0,0,0,.175)}.quarto-dashboard .vega-embed.has-actions details{width:1.7em;height:2em;position:absolute !important;top:0;right:0}.quarto-dashboard .dashboard-toolbar-container{padding:0}.quarto-dashboard .card .card-header p:last-child,.quarto-dashboard .card .card-footer p:last-child{margin-bottom:0}.quarto-dashboard .card .card-body>.h4:first-child{margin-top:0}.quarto-dashboard .card .card-body{z-index:4}@media(max-width: 767.98px){.quarto-dashboard .card .card-body .itables div.dataTables_wrapper div.dataTables_length,.quarto-dashboard .card .card-body .itables div.dataTables_wrapper div.dataTables_info,.quarto-dashboard .card .card-body .itables div.dataTables_wrapper div.dataTables_paginate{text-align:initial}.quarto-dashboard .card .card-body .itables div.dataTables_wrapper div.dataTables_filter{text-align:right}.quarto-dashboard .card .card-body .itables div.dataTables_wrapper div.dataTables_paginate ul.pagination{justify-content:initial}}.quarto-dashboard .card .card-body .itables .dataTables_wrapper{display:flex;flex-wrap:wrap;justify-content:space-between;align-items:center;padding-top:0}.quarto-dashboard .card .card-body .itables .dataTables_wrapper table{flex-shrink:0}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dt-buttons{margin-bottom:.5em;margin-left:auto;width:fit-content;float:right}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dt-buttons.btn-group{background:#fff;border:none}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dt-buttons .btn-secondary{background-color:#fff;background-image:none;border:solid #dee2e6 1px;padding:.2em .7em}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dt-buttons .btn span{font-size:.8em;color:#343a40}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_info{margin-left:.5em;margin-bottom:.5em;padding-top:0}@media(min-width: 768px){.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_info{font-size:.875em}}@media(max-width: 767.98px){.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_info{font-size:.8em}}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_filter{margin-bottom:.5em;font-size:.875em}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_filter input[type=search]{padding:1px 5px 1px 5px;font-size:.875em}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_length{flex-basis:1 1 50%;margin-bottom:.5em;font-size:.875em}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_length select{padding:.4em 3em .4em .5em;font-size:.875em;margin-left:.2em;margin-right:.2em}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_paginate{flex-shrink:0}@media(min-width: 768px){.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_paginate{margin-left:auto}}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_paginate ul.pagination .paginate_button .page-link{font-size:.8em}.quarto-dashboard .card .card-footer{font-size:.9em}.quarto-dashboard .card .card-toolbar{display:flex;flex-grow:1;flex-direction:row;width:100%;flex-wrap:wrap}.quarto-dashboard .card .card-toolbar>*{font-size:.8em;flex-grow:0}.quarto-dashboard .card .card-toolbar>.card-title{font-size:1em;flex-grow:1;align-self:flex-start;margin-top:.1em}.quarto-dashboard .card .card-toolbar .cell-output-display{display:flex}.quarto-dashboard .card .card-toolbar .shiny-input-container{padding-bottom:.5em;margin-bottom:.5em;width:inherit}.quarto-dashboard .card .card-toolbar .shiny-input-container>.checkbox:first-child{margin-top:6px}.quarto-dashboard .card .card-toolbar>*:last-child{margin-right:0}.quarto-dashboard .card .card-toolbar>*>*{margin-right:1em;align-items:baseline}.quarto-dashboard .card .card-toolbar>*>*>a{text-decoration:none;margin-top:auto;margin-bottom:auto}.quarto-dashboard .card .card-toolbar form{width:fit-content}.quarto-dashboard .card .card-toolbar form label{padding-top:.2em;padding-bottom:.2em;width:fit-content}.quarto-dashboard .card .card-toolbar form input[type=date]{width:fit-content}.quarto-dashboard .card .card-toolbar form input[type=color]{width:3em}.quarto-dashboard .card .card-toolbar form button{padding:.4em}.quarto-dashboard .card .card-toolbar form select{width:fit-content}.quarto-dashboard .card .card-toolbar .cell-output-display{display:flex}.quarto-dashboard .card .card-toolbar .shiny-input-container{padding-bottom:.5em;margin-bottom:.5em;width:inherit}.quarto-dashboard .card .card-toolbar .shiny-input-container>.checkbox:first-child{margin-top:6px}.quarto-dashboard .card .card-toolbar>*:last-child{margin-right:0}.quarto-dashboard .card .card-toolbar>*>*{margin-right:1em;align-items:baseline}.quarto-dashboard .card .card-toolbar>*>*>a{text-decoration:none;margin-top:auto;margin-bottom:auto}.quarto-dashboard .card .card-toolbar .shiny-input-container{padding-bottom:0;margin-bottom:0}.quarto-dashboard .card .card-toolbar .shiny-input-container>*{flex-shrink:0;flex-grow:0}.quarto-dashboard .card .card-toolbar .form-group.shiny-input-container:not([role=group])>label{margin-bottom:0}.quarto-dashboard .card .card-toolbar .shiny-input-container.no-baseline{align-items:start;padding-top:6px}.quarto-dashboard .card .card-toolbar .shiny-input-container{display:flex;align-items:baseline}.quarto-dashboard .card .card-toolbar .shiny-input-container label{padding-right:.4em}.quarto-dashboard .card .card-toolbar .shiny-input-container .bslib-input-switch{margin-top:6px}.quarto-dashboard .card .card-toolbar input[type=text]{line-height:1;width:inherit}.quarto-dashboard .card .card-toolbar .input-daterange{width:inherit}.quarto-dashboard .card .card-toolbar .input-daterange input[type=text]{height:2.4em;width:10em}.quarto-dashboard .card .card-toolbar .input-daterange .input-group-addon{height:auto;padding:0;margin-left:-5px !important;margin-right:-5px}.quarto-dashboard .card .card-toolbar .input-daterange .input-group-addon .input-group-text{padding-top:0;padding-bottom:0;height:100%}.quarto-dashboard .card .card-toolbar span.irs.irs--shiny{width:10em}.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-line{top:9px}.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-min,.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-max,.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-from,.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-to,.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-single{top:20px}.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-bar{top:8px}.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-handle{top:0px}.quarto-dashboard .card .card-toolbar .shiny-input-checkboxgroup>label{margin-top:6px}.quarto-dashboard .card .card-toolbar .shiny-input-checkboxgroup>.shiny-options-group{margin-top:0;align-items:baseline}.quarto-dashboard .card .card-toolbar .shiny-input-radiogroup>label{margin-top:6px}.quarto-dashboard .card .card-toolbar .shiny-input-radiogroup>.shiny-options-group{align-items:baseline;margin-top:0}.quarto-dashboard .card .card-toolbar .shiny-input-radiogroup>.shiny-options-group>.radio{margin-right:.3em}.quarto-dashboard .card .card-toolbar .form-select{padding-top:.2em;padding-bottom:.2em}.quarto-dashboard .card .card-toolbar .shiny-input-select{min-width:6em}.quarto-dashboard .card .card-toolbar div.checkbox{margin-bottom:0px}.quarto-dashboard .card .card-toolbar>.checkbox:first-child{margin-top:6px}.quarto-dashboard .card-body>table>thead{border-top:none}.quarto-dashboard .card-body>.table>:not(caption)>*>*{background-color:#fff}.tableFloatingHeaderOriginal{background-color:#fff;position:sticky !important;top:0 !important}.dashboard-data-table{margin-top:-1px}div.value-box-area span.observablehq--number{font-size:calc(clamp(.1em,15cqw,5em)*1.25);line-height:1.2;color:inherit;font-family:var(--bs-body-font-family)}.quarto-listing{padding-bottom:1em}.listing-pagination{padding-top:.5em}ul.pagination{float:right;padding-left:8px;padding-top:.5em}ul.pagination li{padding-right:.75em}ul.pagination li.disabled a,ul.pagination li.active a{color:#fff;text-decoration:none}ul.pagination li:last-of-type{padding-right:0}.listing-actions-group{display:flex}.quarto-listing-filter{margin-bottom:1em;width:200px;margin-left:auto}.quarto-listing-sort{margin-bottom:1em;margin-right:auto;width:auto}.quarto-listing-sort .input-group-text{font-size:.8em}.input-group-text{border-right:none}.quarto-listing-sort select.form-select{font-size:.8em}.listing-no-matching{text-align:center;padding-top:2em;padding-bottom:3em;font-size:1em}#quarto-margin-sidebar .quarto-listing-category{padding-top:0;font-size:1rem}#quarto-margin-sidebar .quarto-listing-category-title{cursor:pointer;font-weight:600;font-size:1rem}.quarto-listing-category .category{cursor:pointer}.quarto-listing-category .category.active{font-weight:600}.quarto-listing-category.category-cloud{display:flex;flex-wrap:wrap;align-items:baseline}.quarto-listing-category.category-cloud .category{padding-right:5px}.quarto-listing-category.category-cloud .category-cloud-1{font-size:.75em}.quarto-listing-category.category-cloud .category-cloud-2{font-size:.95em}.quarto-listing-category.category-cloud .category-cloud-3{font-size:1.15em}.quarto-listing-category.category-cloud .category-cloud-4{font-size:1.35em}.quarto-listing-category.category-cloud .category-cloud-5{font-size:1.55em}.quarto-listing-category.category-cloud .category-cloud-6{font-size:1.75em}.quarto-listing-category.category-cloud .category-cloud-7{font-size:1.95em}.quarto-listing-category.category-cloud .category-cloud-8{font-size:2.15em}.quarto-listing-category.category-cloud .category-cloud-9{font-size:2.35em}.quarto-listing-category.category-cloud .category-cloud-10{font-size:2.55em}.quarto-listing-cols-1{grid-template-columns:repeat(1, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-1{grid-template-columns:repeat(1, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-1{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-2{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-2{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-2{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-3{grid-template-columns:repeat(3, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-3{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-3{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-4{grid-template-columns:repeat(4, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-4{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-4{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-5{grid-template-columns:repeat(5, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-5{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-5{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-6{grid-template-columns:repeat(6, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-6{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-6{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-7{grid-template-columns:repeat(7, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-7{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-7{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-8{grid-template-columns:repeat(8, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-8{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-8{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-9{grid-template-columns:repeat(9, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-9{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-9{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-10{grid-template-columns:repeat(10, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-10{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-10{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-11{grid-template-columns:repeat(11, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-11{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-11{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-12{grid-template-columns:repeat(12, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-12{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-12{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-grid{gap:1.5em}.quarto-grid-item.borderless{border:none}.quarto-grid-item.borderless .listing-categories .listing-category:last-of-type,.quarto-grid-item.borderless .listing-categories .listing-category:first-of-type{padding-left:0}.quarto-grid-item.borderless .listing-categories .listing-category{border:0}.quarto-grid-link{text-decoration:none;color:inherit}.quarto-grid-link:hover{text-decoration:none;color:inherit}.quarto-grid-item h5.title,.quarto-grid-item .title.h5{margin-top:0;margin-bottom:0}.quarto-grid-item .card-footer{display:flex;justify-content:space-between;font-size:.8em}.quarto-grid-item .card-footer p{margin-bottom:0}.quarto-grid-item p.card-img-top{margin-bottom:0}.quarto-grid-item p.card-img-top>img{object-fit:cover}.quarto-grid-item .card-other-values{margin-top:.5em;font-size:.8em}.quarto-grid-item .card-other-values tr{margin-bottom:.5em}.quarto-grid-item .card-other-values tr>td:first-of-type{font-weight:600;padding-right:1em;padding-left:1em;vertical-align:top}.quarto-grid-item div.post-contents{display:flex;flex-direction:column;text-decoration:none;height:100%}.quarto-grid-item .listing-item-img-placeholder{background-color:rgba(52,58,64,.25);flex-shrink:0}.quarto-grid-item .card-attribution{padding-top:1em;display:flex;gap:1em;text-transform:uppercase;color:#6c757d;font-weight:500;flex-grow:10;align-items:flex-end}.quarto-grid-item .description{padding-bottom:1em}.quarto-grid-item .card-attribution .date{align-self:flex-end}.quarto-grid-item .card-attribution.justify{justify-content:space-between}.quarto-grid-item .card-attribution.start{justify-content:flex-start}.quarto-grid-item .card-attribution.end{justify-content:flex-end}.quarto-grid-item .card-title{margin-bottom:.1em}.quarto-grid-item .card-subtitle{padding-top:.25em}.quarto-grid-item .card-text{font-size:.9em}.quarto-grid-item .listing-reading-time{padding-bottom:.25em}.quarto-grid-item .card-text-small{font-size:.8em}.quarto-grid-item .card-subtitle.subtitle{font-size:.9em;font-weight:600;padding-bottom:.5em}.quarto-grid-item .listing-categories{display:flex;flex-wrap:wrap;padding-bottom:5px}.quarto-grid-item .listing-categories .listing-category{color:#6c757d;border:solid 1px #dee2e6;border-radius:.25rem;text-transform:uppercase;font-size:.65em;padding-left:.5em;padding-right:.5em;padding-top:.15em;padding-bottom:.15em;cursor:pointer;margin-right:4px;margin-bottom:4px}.quarto-grid-item.card-right{text-align:right}.quarto-grid-item.card-right .listing-categories{justify-content:flex-end}.quarto-grid-item.card-left{text-align:left}.quarto-grid-item.card-center{text-align:center}.quarto-grid-item.card-center .listing-description{text-align:justify}.quarto-grid-item.card-center .listing-categories{justify-content:center}table.quarto-listing-table td.image{padding:0px}table.quarto-listing-table td.image img{width:100%;max-width:50px;object-fit:contain}table.quarto-listing-table a{text-decoration:none;word-break:keep-all}table.quarto-listing-table th a{color:inherit}table.quarto-listing-table th a.asc:after{margin-bottom:-2px;margin-left:5px;display:inline-block;height:1rem;width:1rem;background-repeat:no-repeat;background-size:1rem 1rem;background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-sort-up" viewBox="0 0 16 16"><path d="M3.5 12.5a.5.5 0 0 1-1 0V3.707L1.354 4.854a.5.5 0 1 1-.708-.708l2-1.999.007-.007a.498.498 0 0 1 .7.006l2 2a.5.5 0 1 1-.707.708L3.5 3.707V12.5zm3.5-9a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5zM7.5 6a.5.5 0 0 0 0 1h5a.5.5 0 0 0 0-1h-5zm0 3a.5.5 0 0 0 0 1h3a.5.5 0 0 0 0-1h-3zm0 3a.5.5 0 0 0 0 1h1a.5.5 0 0 0 0-1h-1z"/></svg>');content:""}table.quarto-listing-table th a.desc:after{margin-bottom:-2px;margin-left:5px;display:inline-block;height:1rem;width:1rem;background-repeat:no-repeat;background-size:1rem 1rem;background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-sort-down" viewBox="0 0 16 16"><path d="M3.5 2.5a.5.5 0 0 0-1 0v8.793l-1.146-1.147a.5.5 0 0 0-.708.708l2 1.999.007.007a.497.497 0 0 0 .7-.006l2-2a.5.5 0 0 0-.707-.708L3.5 11.293V2.5zm3.5 1a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5zM7.5 6a.5.5 0 0 0 0 1h5a.5.5 0 0 0 0-1h-5zm0 3a.5.5 0 0 0 0 1h3a.5.5 0 0 0 0-1h-3zm0 3a.5.5 0 0 0 0 1h1a.5.5 0 0 0 0-1h-1z"/></svg>');content:""}table.quarto-listing-table.table-hover td{cursor:pointer}.quarto-post.image-left{flex-direction:row}.quarto-post.image-right{flex-direction:row-reverse}@media(max-width: 767.98px){.quarto-post.image-right,.quarto-post.image-left{gap:0em;flex-direction:column}.quarto-post .metadata{padding-bottom:1em;order:2}.quarto-post .body{order:1}.quarto-post .thumbnail{order:3}}.list.quarto-listing-default div:last-of-type{border-bottom:none}@media(min-width: 992px){.quarto-listing-container-default{margin-right:2em}}div.quarto-post{display:flex;gap:2em;margin-bottom:1.5em;border-bottom:1px solid #dee2e6}@media(max-width: 767.98px){div.quarto-post{padding-bottom:1em}}div.quarto-post .metadata{flex-basis:20%;flex-grow:0;margin-top:.2em;flex-shrink:10}div.quarto-post .thumbnail{flex-basis:30%;flex-grow:0;flex-shrink:0}div.quarto-post .thumbnail img{margin-top:.4em;width:100%;object-fit:cover}div.quarto-post .body{flex-basis:45%;flex-grow:1;flex-shrink:0}div.quarto-post .body h3.listing-title,div.quarto-post .body .listing-title.h3{margin-top:0px;margin-bottom:0px;border-bottom:none}div.quarto-post .body .listing-subtitle{font-size:.875em;margin-bottom:.5em;margin-top:.2em}div.quarto-post .body .description{font-size:.9em}div.quarto-post .body pre code{white-space:pre-wrap}div.quarto-post a{color:#343a40;text-decoration:none}div.quarto-post .metadata{display:flex;flex-direction:column;font-size:.8em;font-family:"Source Sans Pro",-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol";flex-basis:33%}div.quarto-post .listing-categories{display:flex;flex-wrap:wrap;padding-bottom:5px}div.quarto-post .listing-categories .listing-category{color:#6c757d;border:solid 1px #dee2e6;border-radius:.25rem;text-transform:uppercase;font-size:.65em;padding-left:.5em;padding-right:.5em;padding-top:.15em;padding-bottom:.15em;cursor:pointer;margin-right:4px;margin-bottom:4px}div.quarto-post .listing-description{margin-bottom:.5em}div.quarto-about-jolla{display:flex !important;flex-direction:column;align-items:center;margin-top:10%;padding-bottom:1em}div.quarto-about-jolla .about-image{object-fit:cover;margin-left:auto;margin-right:auto;margin-bottom:1.5em}div.quarto-about-jolla img.round{border-radius:50%}div.quarto-about-jolla img.rounded{border-radius:10px}div.quarto-about-jolla .quarto-title h1.title,div.quarto-about-jolla .quarto-title .title.h1{text-align:center}div.quarto-about-jolla .quarto-title .description{text-align:center}div.quarto-about-jolla h2,div.quarto-about-jolla .h2{border-bottom:none}div.quarto-about-jolla .about-sep{width:60%}div.quarto-about-jolla main{text-align:center}div.quarto-about-jolla .about-links{display:flex}@media(min-width: 992px){div.quarto-about-jolla .about-links{flex-direction:row;column-gap:.8em;row-gap:15px;flex-wrap:wrap}}@media(max-width: 991.98px){div.quarto-about-jolla .about-links{flex-direction:column;row-gap:1em;width:100%;padding-bottom:1.5em}}div.quarto-about-jolla .about-link{color:#626d78;text-decoration:none;border:solid 1px}@media(min-width: 992px){div.quarto-about-jolla .about-link{font-size:.8em;padding:.25em .5em;border-radius:4px}}@media(max-width: 991.98px){div.quarto-about-jolla .about-link{font-size:1.1em;padding:.5em .5em;text-align:center;border-radius:6px}}div.quarto-about-jolla .about-link:hover{color:#2761e3}div.quarto-about-jolla .about-link i.bi{margin-right:.15em}div.quarto-about-solana{display:flex !important;flex-direction:column;padding-top:3em !important;padding-bottom:1em}div.quarto-about-solana .about-entity{display:flex !important;align-items:start;justify-content:space-between}@media(min-width: 992px){div.quarto-about-solana .about-entity{flex-direction:row}}@media(max-width: 991.98px){div.quarto-about-solana .about-entity{flex-direction:column-reverse;align-items:center;text-align:center}}div.quarto-about-solana .about-entity .entity-contents{display:flex;flex-direction:column}@media(max-width: 767.98px){div.quarto-about-solana .about-entity .entity-contents{width:100%}}div.quarto-about-solana .about-entity .about-image{object-fit:cover}@media(max-width: 991.98px){div.quarto-about-solana .about-entity .about-image{margin-bottom:1.5em}}div.quarto-about-solana .about-entity img.round{border-radius:50%}div.quarto-about-solana .about-entity img.rounded{border-radius:10px}div.quarto-about-solana .about-entity .about-links{display:flex;justify-content:left;padding-bottom:1.2em}@media(min-width: 992px){div.quarto-about-solana .about-entity .about-links{flex-direction:row;column-gap:.8em;row-gap:15px;flex-wrap:wrap}}@media(max-width: 991.98px){div.quarto-about-solana .about-entity .about-links{flex-direction:column;row-gap:1em;width:100%;padding-bottom:1.5em}}div.quarto-about-solana .about-entity .about-link{color:#626d78;text-decoration:none;border:solid 1px}@media(min-width: 992px){div.quarto-about-solana .about-entity .about-link{font-size:.8em;padding:.25em .5em;border-radius:4px}}@media(max-width: 991.98px){div.quarto-about-solana .about-entity .about-link{font-size:1.1em;padding:.5em .5em;text-align:center;border-radius:6px}}div.quarto-about-solana .about-entity .about-link:hover{color:#2761e3}div.quarto-about-solana .about-entity .about-link i.bi{margin-right:.15em}div.quarto-about-solana .about-contents{padding-right:1.5em;flex-basis:0;flex-grow:1}div.quarto-about-solana .about-contents main.content{margin-top:0}div.quarto-about-solana .about-contents h2,div.quarto-about-solana .about-contents .h2{border-bottom:none}div.quarto-about-trestles{display:flex !important;flex-direction:row;padding-top:3em !important;padding-bottom:1em}@media(max-width: 991.98px){div.quarto-about-trestles{flex-direction:column;padding-top:0em !important}}div.quarto-about-trestles .about-entity{display:flex !important;flex-direction:column;align-items:center;text-align:center;padding-right:1em}@media(min-width: 992px){div.quarto-about-trestles .about-entity{flex:0 0 42%}}div.quarto-about-trestles .about-entity .about-image{object-fit:cover;margin-bottom:1.5em}div.quarto-about-trestles .about-entity img.round{border-radius:50%}div.quarto-about-trestles .about-entity img.rounded{border-radius:10px}div.quarto-about-trestles .about-entity .about-links{display:flex;justify-content:center}@media(min-width: 992px){div.quarto-about-trestles .about-entity .about-links{flex-direction:row;column-gap:.8em;row-gap:15px;flex-wrap:wrap}}@media(max-width: 991.98px){div.quarto-about-trestles .about-entity .about-links{flex-direction:column;row-gap:1em;width:100%;padding-bottom:1.5em}}div.quarto-about-trestles .about-entity .about-link{color:#626d78;text-decoration:none;border:solid 1px}@media(min-width: 992px){div.quarto-about-trestles .about-entity .about-link{font-size:.8em;padding:.25em .5em;border-radius:4px}}@media(max-width: 991.98px){div.quarto-about-trestles .about-entity .about-link{font-size:1.1em;padding:.5em .5em;text-align:center;border-radius:6px}}div.quarto-about-trestles .about-entity .about-link:hover{color:#2761e3}div.quarto-about-trestles .about-entity .about-link i.bi{margin-right:.15em}div.quarto-about-trestles .about-contents{flex-basis:0;flex-grow:1}div.quarto-about-trestles .about-contents h2,div.quarto-about-trestles .about-contents .h2{border-bottom:none}@media(min-width: 992px){div.quarto-about-trestles .about-contents{border-left:solid 1px #dee2e6;padding-left:1.5em}}div.quarto-about-trestles .about-contents main.content{margin-top:0}div.quarto-about-marquee{padding-bottom:1em}div.quarto-about-marquee .about-contents{display:flex;flex-direction:column}div.quarto-about-marquee .about-image{max-height:550px;margin-bottom:1.5em;object-fit:cover}div.quarto-about-marquee img.round{border-radius:50%}div.quarto-about-marquee img.rounded{border-radius:10px}div.quarto-about-marquee h2,div.quarto-about-marquee .h2{border-bottom:none}div.quarto-about-marquee .about-links{display:flex;justify-content:center;padding-top:1.5em}@media(min-width: 992px){div.quarto-about-marquee .about-links{flex-direction:row;column-gap:.8em;row-gap:15px;flex-wrap:wrap}}@media(max-width: 991.98px){div.quarto-about-marquee .about-links{flex-direction:column;row-gap:1em;width:100%;padding-bottom:1.5em}}div.quarto-about-marquee .about-link{color:#626d78;text-decoration:none;border:solid 1px}@media(min-width: 992px){div.quarto-about-marquee .about-link{font-size:.8em;padding:.25em .5em;border-radius:4px}}@media(max-width: 991.98px){div.quarto-about-marquee .about-link{font-size:1.1em;padding:.5em .5em;text-align:center;border-radius:6px}}div.quarto-about-marquee .about-link:hover{color:#2761e3}div.quarto-about-marquee .about-link i.bi{margin-right:.15em}@media(min-width: 992px){div.quarto-about-marquee .about-link{border:none}}div.quarto-about-broadside{display:flex;flex-direction:column;padding-bottom:1em}div.quarto-about-broadside .about-main{display:flex !important;padding-top:0 !important}@media(min-width: 992px){div.quarto-about-broadside .about-main{flex-direction:row;align-items:flex-start}}@media(max-width: 991.98px){div.quarto-about-broadside .about-main{flex-direction:column}}@media(max-width: 991.98px){div.quarto-about-broadside .about-main .about-entity{flex-shrink:0;width:100%;height:450px;margin-bottom:1.5em;background-size:cover;background-repeat:no-repeat}}@media(min-width: 992px){div.quarto-about-broadside .about-main .about-entity{flex:0 10 50%;margin-right:1.5em;width:100%;height:100%;background-size:100%;background-repeat:no-repeat}}div.quarto-about-broadside .about-main .about-contents{padding-top:14px;flex:0 0 50%}div.quarto-about-broadside h2,div.quarto-about-broadside .h2{border-bottom:none}div.quarto-about-broadside .about-sep{margin-top:1.5em;width:60%;align-self:center}div.quarto-about-broadside .about-links{display:flex;justify-content:center;column-gap:20px;padding-top:1.5em}@media(min-width: 992px){div.quarto-about-broadside .about-links{flex-direction:row;column-gap:.8em;row-gap:15px;flex-wrap:wrap}}@media(max-width: 991.98px){div.quarto-about-broadside .about-links{flex-direction:column;row-gap:1em;width:100%;padding-bottom:1.5em}}div.quarto-about-broadside .about-link{color:#626d78;text-decoration:none;border:solid 1px}@media(min-width: 992px){div.quarto-about-broadside .about-link{font-size:.8em;padding:.25em .5em;border-radius:4px}}@media(max-width: 991.98px){div.quarto-about-broadside .about-link{font-size:1.1em;padding:.5em .5em;text-align:center;border-radius:6px}}div.quarto-about-broadside .about-link:hover{color:#2761e3}div.quarto-about-broadside .about-link i.bi{margin-right:.15em}@media(min-width: 992px){div.quarto-about-broadside .about-link{border:none}}.tippy-box[data-theme~=quarto]{background-color:#fff;border:solid 1px #dee2e6;border-radius:.25rem;color:#343a40;font-size:.875rem}.tippy-box[data-theme~=quarto]>.tippy-backdrop{background-color:#fff}.tippy-box[data-theme~=quarto]>.tippy-arrow:after,.tippy-box[data-theme~=quarto]>.tippy-svg-arrow:after{content:"";position:absolute;z-index:-1}.tippy-box[data-theme~=quarto]>.tippy-arrow:after{border-color:rgba(0,0,0,0);border-style:solid}.tippy-box[data-placement^=top]>.tippy-arrow:before{bottom:-6px}.tippy-box[data-placement^=bottom]>.tippy-arrow:before{top:-6px}.tippy-box[data-placement^=right]>.tippy-arrow:before{left:-6px}.tippy-box[data-placement^=left]>.tippy-arrow:before{right:-6px}.tippy-box[data-theme~=quarto][data-placement^=top]>.tippy-arrow:before{border-top-color:#fff}.tippy-box[data-theme~=quarto][data-placement^=top]>.tippy-arrow:after{border-top-color:#dee2e6;border-width:7px 7px 0;top:17px;left:1px}.tippy-box[data-theme~=quarto][data-placement^=top]>.tippy-svg-arrow>svg{top:16px}.tippy-box[data-theme~=quarto][data-placement^=top]>.tippy-svg-arrow:after{top:17px}.tippy-box[data-theme~=quarto][data-placement^=bottom]>.tippy-arrow:before{border-bottom-color:#fff;bottom:16px}.tippy-box[data-theme~=quarto][data-placement^=bottom]>.tippy-arrow:after{border-bottom-color:#dee2e6;border-width:0 7px 7px;bottom:17px;left:1px}.tippy-box[data-theme~=quarto][data-placement^=bottom]>.tippy-svg-arrow>svg{bottom:15px}.tippy-box[data-theme~=quarto][data-placement^=bottom]>.tippy-svg-arrow:after{bottom:17px}.tippy-box[data-theme~=quarto][data-placement^=left]>.tippy-arrow:before{border-left-color:#fff}.tippy-box[data-theme~=quarto][data-placement^=left]>.tippy-arrow:after{border-left-color:#dee2e6;border-width:7px 0 7px 7px;left:17px;top:1px}.tippy-box[data-theme~=quarto][data-placement^=left]>.tippy-svg-arrow>svg{left:11px}.tippy-box[data-theme~=quarto][data-placement^=left]>.tippy-svg-arrow:after{left:12px}.tippy-box[data-theme~=quarto][data-placement^=right]>.tippy-arrow:before{border-right-color:#fff;right:16px}.tippy-box[data-theme~=quarto][data-placement^=right]>.tippy-arrow:after{border-width:7px 7px 7px 0;right:17px;top:1px;border-right-color:#dee2e6}.tippy-box[data-theme~=quarto][data-placement^=right]>.tippy-svg-arrow>svg{right:11px}.tippy-box[data-theme~=quarto][data-placement^=right]>.tippy-svg-arrow:after{right:12px}.tippy-box[data-theme~=quarto]>.tippy-svg-arrow{fill:#343a40}.tippy-box[data-theme~=quarto]>.tippy-svg-arrow:after{background-image:url(data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iNiIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBkPSJNMCA2czEuNzk2LS4wMTMgNC42Ny0zLjYxNUM1Ljg1MS45IDYuOTMuMDA2IDggMGMxLjA3LS4wMDYgMi4xNDguODg3IDMuMzQzIDIuMzg1QzE0LjIzMyA2LjAwNSAxNiA2IDE2IDZIMHoiIGZpbGw9InJnYmEoMCwgOCwgMTYsIDAuMikiLz48L3N2Zz4=);background-size:16px 6px;width:16px;height:6px}.top-right{position:absolute;top:1em;right:1em}.visually-hidden{border:0;clip:rect(0 0 0 0);height:auto;margin:0;overflow:hidden;padding:0;position:absolute;width:1px;white-space:nowrap}.hidden{display:none !important}.zindex-bottom{z-index:-1 !important}figure.figure{display:block}.quarto-layout-panel{margin-bottom:1em}.quarto-layout-panel>figure{width:100%}.quarto-layout-panel>figure>figcaption,.quarto-layout-panel>.panel-caption{margin-top:10pt}.quarto-layout-panel>.table-caption{margin-top:0px}.table-caption p{margin-bottom:.5em}.quarto-layout-row{display:flex;flex-direction:row;align-items:flex-start}.quarto-layout-valign-top{align-items:flex-start}.quarto-layout-valign-bottom{align-items:flex-end}.quarto-layout-valign-center{align-items:center}.quarto-layout-cell{position:relative;margin-right:20px}.quarto-layout-cell:last-child{margin-right:0}.quarto-layout-cell figure,.quarto-layout-cell>p{margin:.2em}.quarto-layout-cell img{max-width:100%}.quarto-layout-cell .html-widget{width:100% !important}.quarto-layout-cell div figure p{margin:0}.quarto-layout-cell figure{display:block;margin-inline-start:0;margin-inline-end:0}.quarto-layout-cell table{display:inline-table}.quarto-layout-cell-subref figcaption,figure .quarto-layout-row figure figcaption{text-align:center;font-style:italic}.quarto-figure{position:relative;margin-bottom:1em}.quarto-figure>figure{width:100%;margin-bottom:0}.quarto-figure-left>figure>p,.quarto-figure-left>figure>div{text-align:left}.quarto-figure-center>figure>p,.quarto-figure-center>figure>div{text-align:center}.quarto-figure-right>figure>p,.quarto-figure-right>figure>div{text-align:right}.quarto-figure>figure>div.cell-annotation,.quarto-figure>figure>div code{text-align:left}figure>p:empty{display:none}figure>p:first-child{margin-top:0;margin-bottom:0}figure>figcaption.quarto-float-caption-bottom{margin-bottom:.5em}figure>figcaption.quarto-float-caption-top{margin-top:.5em}div[id^=tbl-]{position:relative}.quarto-figure>.anchorjs-link{position:absolute;top:.6em;right:.5em}div[id^=tbl-]>.anchorjs-link{position:absolute;top:.7em;right:.3em}.quarto-figure:hover>.anchorjs-link,div[id^=tbl-]:hover>.anchorjs-link,h2:hover>.anchorjs-link,.h2:hover>.anchorjs-link,h3:hover>.anchorjs-link,.h3:hover>.anchorjs-link,h4:hover>.anchorjs-link,.h4:hover>.anchorjs-link,h5:hover>.anchorjs-link,.h5:hover>.anchorjs-link,h6:hover>.anchorjs-link,.h6:hover>.anchorjs-link,.reveal-anchorjs-link>.anchorjs-link{opacity:1}#title-block-header{margin-block-end:1rem;position:relative;margin-top:-1px}#title-block-header .abstract{margin-block-start:1rem}#title-block-header .abstract .abstract-title{font-weight:600}#title-block-header a{text-decoration:none}#title-block-header .author,#title-block-header .date,#title-block-header .doi{margin-block-end:.2rem}#title-block-header .quarto-title-block>div{display:flex}#title-block-header .quarto-title-block>div>h1,#title-block-header .quarto-title-block>div>.h1{flex-grow:1}#title-block-header .quarto-title-block>div>button{flex-shrink:0;height:2.25rem;margin-top:0}@media(min-width: 992px){#title-block-header .quarto-title-block>div>button{margin-top:5px}}tr.header>th>p:last-of-type{margin-bottom:0px}table,table.table{margin-top:.5rem;margin-bottom:.5rem}caption,.table-caption{padding-top:.5rem;padding-bottom:.5rem;text-align:center}figure.quarto-float-tbl figcaption.quarto-float-caption-top{margin-top:.5rem;margin-bottom:.25rem;text-align:center}figure.quarto-float-tbl figcaption.quarto-float-caption-bottom{padding-top:.25rem;margin-bottom:.5rem;text-align:center}.utterances{max-width:none;margin-left:-8px}iframe{margin-bottom:1em}details{margin-bottom:1em}details[show]{margin-bottom:0}details>summary{color:#6c757d}details>summary>p:only-child{display:inline}pre.sourceCode,code.sourceCode{position:relative}dd code:not(.sourceCode),p code:not(.sourceCode){white-space:pre-wrap}code{white-space:pre}@media print{code{white-space:pre-wrap}}pre>code{display:block}pre>code.sourceCode{white-space:pre}pre>code.sourceCode>span>a:first-child::before{text-decoration:none}pre.code-overflow-wrap>code.sourceCode{white-space:pre-wrap}pre.code-overflow-scroll>code.sourceCode{white-space:pre}code a:any-link{color:inherit;text-decoration:none}code a:hover{color:inherit;text-decoration:underline}ul.task-list{padding-left:1em}[data-tippy-root]{display:inline-block}.tippy-content .footnote-back{display:none}.footnote-back{margin-left:.2em}.tippy-content{overflow-x:auto}.quarto-embedded-source-code{display:none}.quarto-unresolved-ref{font-weight:600}.quarto-cover-image{max-width:35%;float:right;margin-left:30px}.cell-output-display .widget-subarea{margin-bottom:1em}.cell-output-display:not(.no-overflow-x),.knitsql-table:not(.no-overflow-x){overflow-x:auto}.panel-input{margin-bottom:1em}.panel-input>div,.panel-input>div>div{display:inline-block;vertical-align:top;padding-right:12px}.panel-input>p:last-child{margin-bottom:0}.layout-sidebar{margin-bottom:1em}.layout-sidebar .tab-content{border:none}.tab-content>.page-columns.active{display:grid}div.sourceCode>iframe{width:100%;height:300px;margin-bottom:-0.5em}a{text-underline-offset:3px}div.ansi-escaped-output{font-family:monospace;display:block}/*!
+ */@import"https://fonts.googleapis.com/css2?family=Source+Sans+Pro:wght@300;400;700&display=swap";:root,[data-bs-theme=light]{--bs-blue: #2780e3;--bs-indigo: #6610f2;--bs-purple: #613d7c;--bs-pink: #e83e8c;--bs-red: #ff0039;--bs-orange: #f0ad4e;--bs-yellow: #ff7518;--bs-green: #3fb618;--bs-teal: #20c997;--bs-cyan: #9954bb;--bs-black: #000;--bs-white: #fff;--bs-gray: #6c757d;--bs-gray-dark: #343a40;--bs-gray-100: #f8f9fa;--bs-gray-200: #e9ecef;--bs-gray-300: #dee2e6;--bs-gray-400: #ced4da;--bs-gray-500: #adb5bd;--bs-gray-600: #6c757d;--bs-gray-700: #495057;--bs-gray-800: #343a40;--bs-gray-900: #212529;--bs-default: #343a40;--bs-primary: #2780e3;--bs-secondary: #343a40;--bs-success: #3fb618;--bs-info: #9954bb;--bs-warning: #ff7518;--bs-danger: #ff0039;--bs-light: #f8f9fa;--bs-dark: #343a40;--bs-default-rgb: 52, 58, 64;--bs-primary-rgb: 39, 128, 227;--bs-secondary-rgb: 52, 58, 64;--bs-success-rgb: 63, 182, 24;--bs-info-rgb: 153, 84, 187;--bs-warning-rgb: 255, 117, 24;--bs-danger-rgb: 255, 0, 57;--bs-light-rgb: 248, 249, 250;--bs-dark-rgb: 52, 58, 64;--bs-primary-text-emphasis: #10335b;--bs-secondary-text-emphasis: #15171a;--bs-success-text-emphasis: #19490a;--bs-info-text-emphasis: #3d224b;--bs-warning-text-emphasis: #662f0a;--bs-danger-text-emphasis: #660017;--bs-light-text-emphasis: #495057;--bs-dark-text-emphasis: #495057;--bs-primary-bg-subtle: #d4e6f9;--bs-secondary-bg-subtle: #d6d8d9;--bs-success-bg-subtle: #d9f0d1;--bs-info-bg-subtle: #ebddf1;--bs-warning-bg-subtle: #ffe3d1;--bs-danger-bg-subtle: #ffccd7;--bs-light-bg-subtle: #fcfcfd;--bs-dark-bg-subtle: #ced4da;--bs-primary-border-subtle: #a9ccf4;--bs-secondary-border-subtle: #aeb0b3;--bs-success-border-subtle: #b2e2a3;--bs-info-border-subtle: #d6bbe4;--bs-warning-border-subtle: #ffc8a3;--bs-danger-border-subtle: #ff99b0;--bs-light-border-subtle: #e9ecef;--bs-dark-border-subtle: #adb5bd;--bs-white-rgb: 255, 255, 255;--bs-black-rgb: 0, 0, 0;--bs-font-sans-serif: "Source Sans Pro", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";--bs-font-monospace: SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;--bs-gradient: linear-gradient(180deg, rgba(255, 255, 255, 0.15), rgba(255, 255, 255, 0));--bs-root-font-size: 17px;--bs-body-font-family: "Source Sans Pro", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";--bs-body-font-size:1rem;--bs-body-font-weight: 400;--bs-body-line-height: 1.5;--bs-body-color: #343a40;--bs-body-color-rgb: 52, 58, 64;--bs-body-bg: #fff;--bs-body-bg-rgb: 255, 255, 255;--bs-emphasis-color: #000;--bs-emphasis-color-rgb: 0, 0, 0;--bs-secondary-color: rgba(52, 58, 64, 0.75);--bs-secondary-color-rgb: 52, 58, 64;--bs-secondary-bg: #e9ecef;--bs-secondary-bg-rgb: 233, 236, 239;--bs-tertiary-color: rgba(52, 58, 64, 0.5);--bs-tertiary-color-rgb: 52, 58, 64;--bs-tertiary-bg: #f8f9fa;--bs-tertiary-bg-rgb: 248, 249, 250;--bs-heading-color: inherit;--bs-link-color: #2761e3;--bs-link-color-rgb: 39, 97, 227;--bs-link-decoration: underline;--bs-link-hover-color: #1f4eb6;--bs-link-hover-color-rgb: 31, 78, 182;--bs-code-color: #7d12ba;--bs-highlight-bg: #ffe3d1;--bs-border-width: 1px;--bs-border-style: solid;--bs-border-color: #dee2e6;--bs-border-color-translucent: rgba(0, 0, 0, 0.175);--bs-border-radius: 0.25rem;--bs-border-radius-sm: 0.2em;--bs-border-radius-lg: 0.5rem;--bs-border-radius-xl: 1rem;--bs-border-radius-xxl: 2rem;--bs-border-radius-2xl: var(--bs-border-radius-xxl);--bs-border-radius-pill: 50rem;--bs-box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);--bs-box-shadow-sm: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.075);--bs-box-shadow-lg: 0 1rem 3rem rgba(0, 0, 0, 0.175);--bs-box-shadow-inset: inset 0 1px 2px rgba(0, 0, 0, 0.075);--bs-focus-ring-width: 0.25rem;--bs-focus-ring-opacity: 0.25;--bs-focus-ring-color: rgba(39, 128, 227, 0.25);--bs-form-valid-color: #3fb618;--bs-form-valid-border-color: #3fb618;--bs-form-invalid-color: #ff0039;--bs-form-invalid-border-color: #ff0039}[data-bs-theme=dark]{color-scheme:dark;--bs-body-color: #dee2e6;--bs-body-color-rgb: 222, 226, 230;--bs-body-bg: #212529;--bs-body-bg-rgb: 33, 37, 41;--bs-emphasis-color: #fff;--bs-emphasis-color-rgb: 255, 255, 255;--bs-secondary-color: rgba(222, 226, 230, 0.75);--bs-secondary-color-rgb: 222, 226, 230;--bs-secondary-bg: #343a40;--bs-secondary-bg-rgb: 52, 58, 64;--bs-tertiary-color: rgba(222, 226, 230, 0.5);--bs-tertiary-color-rgb: 222, 226, 230;--bs-tertiary-bg: #2b3035;--bs-tertiary-bg-rgb: 43, 48, 53;--bs-primary-text-emphasis: #7db3ee;--bs-secondary-text-emphasis: #85898c;--bs-success-text-emphasis: #8cd374;--bs-info-text-emphasis: #c298d6;--bs-warning-text-emphasis: #ffac74;--bs-danger-text-emphasis: #ff6688;--bs-light-text-emphasis: #f8f9fa;--bs-dark-text-emphasis: #dee2e6;--bs-primary-bg-subtle: #081a2d;--bs-secondary-bg-subtle: #0a0c0d;--bs-success-bg-subtle: #0d2405;--bs-info-bg-subtle: #1f1125;--bs-warning-bg-subtle: #331705;--bs-danger-bg-subtle: #33000b;--bs-light-bg-subtle: #343a40;--bs-dark-bg-subtle: #1a1d20;--bs-primary-border-subtle: #174d88;--bs-secondary-border-subtle: #1f2326;--bs-success-border-subtle: #266d0e;--bs-info-border-subtle: #5c3270;--bs-warning-border-subtle: #99460e;--bs-danger-border-subtle: #990022;--bs-light-border-subtle: #495057;--bs-dark-border-subtle: #343a40;--bs-heading-color: inherit;--bs-link-color: #7db3ee;--bs-link-hover-color: #97c2f1;--bs-link-color-rgb: 125, 179, 238;--bs-link-hover-color-rgb: 151, 194, 241;--bs-code-color: white;--bs-border-color: #495057;--bs-border-color-translucent: rgba(255, 255, 255, 0.15);--bs-form-valid-color: #8cd374;--bs-form-valid-border-color: #8cd374;--bs-form-invalid-color: #ff6688;--bs-form-invalid-border-color: #ff6688}*,*::before,*::after{box-sizing:border-box}:root{font-size:var(--bs-root-font-size)}body{margin:0;font-family:var(--bs-body-font-family);font-size:var(--bs-body-font-size);font-weight:var(--bs-body-font-weight);line-height:var(--bs-body-line-height);color:var(--bs-body-color);text-align:var(--bs-body-text-align);background-color:var(--bs-body-bg);-webkit-text-size-adjust:100%;-webkit-tap-highlight-color:rgba(0,0,0,0)}hr{margin:1rem 0;color:inherit;border:0;border-top:1px solid;opacity:.25}h6,.h6,h5,.h5,h4,.h4,h3,.h3,h2,.h2,h1,.h1{margin-top:0;margin-bottom:.5rem;font-weight:400;line-height:1.2;color:var(--bs-heading-color)}h1,.h1{font-size:calc(1.325rem + 0.9vw)}@media(min-width: 1200px){h1,.h1{font-size:2rem}}h2,.h2{font-size:calc(1.29rem + 0.48vw)}@media(min-width: 1200px){h2,.h2{font-size:1.65rem}}h3,.h3{font-size:calc(1.27rem + 0.24vw)}@media(min-width: 1200px){h3,.h3{font-size:1.45rem}}h4,.h4{font-size:1.25rem}h5,.h5{font-size:1.1rem}h6,.h6{font-size:1rem}p{margin-top:0;margin-bottom:1rem}abbr[title]{text-decoration:underline dotted;-webkit-text-decoration:underline dotted;-moz-text-decoration:underline dotted;-ms-text-decoration:underline dotted;-o-text-decoration:underline dotted;cursor:help;text-decoration-skip-ink:none}address{margin-bottom:1rem;font-style:normal;line-height:inherit}ol,ul{padding-left:2rem}ol,ul,dl{margin-top:0;margin-bottom:1rem}ol ol,ul ul,ol ul,ul ol{margin-bottom:0}dt{font-weight:700}dd{margin-bottom:.5rem;margin-left:0}blockquote{margin:0 0 1rem;padding:.625rem 1.25rem;border-left:.25rem solid #e9ecef}blockquote p:last-child,blockquote ul:last-child,blockquote ol:last-child{margin-bottom:0}b,strong{font-weight:bolder}small,.small{font-size:0.875em}mark,.mark{padding:.1875em;background-color:var(--bs-highlight-bg)}sub,sup{position:relative;font-size:0.75em;line-height:0;vertical-align:baseline}sub{bottom:-0.25em}sup{top:-0.5em}a{color:rgba(var(--bs-link-color-rgb), var(--bs-link-opacity, 1));text-decoration:underline;-webkit-text-decoration:underline;-moz-text-decoration:underline;-ms-text-decoration:underline;-o-text-decoration:underline}a:hover{--bs-link-color-rgb: var(--bs-link-hover-color-rgb)}a:not([href]):not([class]),a:not([href]):not([class]):hover{color:inherit;text-decoration:none}pre,code,kbd,samp{font-family:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace;font-size:1em}pre{display:block;margin-top:0;margin-bottom:1rem;overflow:auto;font-size:0.875em;color:#000;background-color:#f8f9fa;padding:.5rem;border:1px solid var(--bs-border-color, #dee2e6)}pre code{background-color:rgba(0,0,0,0);font-size:inherit;color:inherit;word-break:normal}code{font-size:0.875em;color:var(--bs-code-color);background-color:#f8f9fa;padding:.125rem .25rem;word-wrap:break-word}a>code{color:inherit}kbd{padding:.4rem .4rem;font-size:0.875em;color:#fff;background-color:#343a40}kbd kbd{padding:0;font-size:1em}figure{margin:0 0 1rem}img,svg{vertical-align:middle}table{caption-side:bottom;border-collapse:collapse}caption{padding-top:.5rem;padding-bottom:.5rem;color:rgba(52,58,64,.75);text-align:left}th{text-align:inherit;text-align:-webkit-match-parent}thead,tbody,tfoot,tr,td,th{border-color:inherit;border-style:solid;border-width:0}label{display:inline-block}button{border-radius:0}button:focus:not(:focus-visible){outline:0}input,button,select,optgroup,textarea{margin:0;font-family:inherit;font-size:inherit;line-height:inherit}button,select{text-transform:none}[role=button]{cursor:pointer}select{word-wrap:normal}select:disabled{opacity:1}[list]:not([type=date]):not([type=datetime-local]):not([type=month]):not([type=week]):not([type=time])::-webkit-calendar-picker-indicator{display:none !important}button,[type=button],[type=reset],[type=submit]{-webkit-appearance:button}button:not(:disabled),[type=button]:not(:disabled),[type=reset]:not(:disabled),[type=submit]:not(:disabled){cursor:pointer}::-moz-focus-inner{padding:0;border-style:none}textarea{resize:vertical}fieldset{min-width:0;padding:0;margin:0;border:0}legend{float:left;width:100%;padding:0;margin-bottom:.5rem;font-size:calc(1.275rem + 0.3vw);line-height:inherit}@media(min-width: 1200px){legend{font-size:1.5rem}}legend+*{clear:left}::-webkit-datetime-edit-fields-wrapper,::-webkit-datetime-edit-text,::-webkit-datetime-edit-minute,::-webkit-datetime-edit-hour-field,::-webkit-datetime-edit-day-field,::-webkit-datetime-edit-month-field,::-webkit-datetime-edit-year-field{padding:0}::-webkit-inner-spin-button{height:auto}[type=search]{-webkit-appearance:textfield;outline-offset:-2px}::-webkit-search-decoration{-webkit-appearance:none}::-webkit-color-swatch-wrapper{padding:0}::file-selector-button{font:inherit;-webkit-appearance:button}output{display:inline-block}iframe{border:0}summary{display:list-item;cursor:pointer}progress{vertical-align:baseline}[hidden]{display:none !important}.lead{font-size:1.25rem;font-weight:300}.display-1{font-size:calc(1.625rem + 4.5vw);font-weight:300;line-height:1.2}@media(min-width: 1200px){.display-1{font-size:5rem}}.display-2{font-size:calc(1.575rem + 3.9vw);font-weight:300;line-height:1.2}@media(min-width: 1200px){.display-2{font-size:4.5rem}}.display-3{font-size:calc(1.525rem + 3.3vw);font-weight:300;line-height:1.2}@media(min-width: 1200px){.display-3{font-size:4rem}}.display-4{font-size:calc(1.475rem + 2.7vw);font-weight:300;line-height:1.2}@media(min-width: 1200px){.display-4{font-size:3.5rem}}.display-5{font-size:calc(1.425rem + 2.1vw);font-weight:300;line-height:1.2}@media(min-width: 1200px){.display-5{font-size:3rem}}.display-6{font-size:calc(1.375rem + 1.5vw);font-weight:300;line-height:1.2}@media(min-width: 1200px){.display-6{font-size:2.5rem}}.list-unstyled{padding-left:0;list-style:none}.list-inline{padding-left:0;list-style:none}.list-inline-item{display:inline-block}.list-inline-item:not(:last-child){margin-right:.5rem}.initialism{font-size:0.875em;text-transform:uppercase}.blockquote{margin-bottom:1rem;font-size:1.25rem}.blockquote>:last-child{margin-bottom:0}.blockquote-footer{margin-top:-1rem;margin-bottom:1rem;font-size:0.875em;color:#6c757d}.blockquote-footer::before{content:"— "}.img-fluid{max-width:100%;height:auto}.img-thumbnail{padding:.25rem;background-color:#fff;border:1px solid #dee2e6;max-width:100%;height:auto}.figure{display:inline-block}.figure-img{margin-bottom:.5rem;line-height:1}.figure-caption{font-size:0.875em;color:rgba(52,58,64,.75)}.container,.container-fluid,.container-xxl,.container-xl,.container-lg,.container-md,.container-sm{--bs-gutter-x: 1.5rem;--bs-gutter-y: 0;width:100%;padding-right:calc(var(--bs-gutter-x)*.5);padding-left:calc(var(--bs-gutter-x)*.5);margin-right:auto;margin-left:auto}@media(min-width: 576px){.container-sm,.container{max-width:540px}}@media(min-width: 768px){.container-md,.container-sm,.container{max-width:720px}}@media(min-width: 992px){.container-lg,.container-md,.container-sm,.container{max-width:960px}}@media(min-width: 1200px){.container-xl,.container-lg,.container-md,.container-sm,.container{max-width:1140px}}@media(min-width: 1400px){.container-xxl,.container-xl,.container-lg,.container-md,.container-sm,.container{max-width:1320px}}:root{--bs-breakpoint-xs: 0;--bs-breakpoint-sm: 576px;--bs-breakpoint-md: 768px;--bs-breakpoint-lg: 992px;--bs-breakpoint-xl: 1200px;--bs-breakpoint-xxl: 1400px}.grid{display:grid;grid-template-rows:repeat(var(--bs-rows, 1), 1fr);grid-template-columns:repeat(var(--bs-columns, 12), 1fr);gap:var(--bs-gap, 1.5rem)}.grid .g-col-1{grid-column:auto/span 1}.grid .g-col-2{grid-column:auto/span 2}.grid .g-col-3{grid-column:auto/span 3}.grid .g-col-4{grid-column:auto/span 4}.grid .g-col-5{grid-column:auto/span 5}.grid .g-col-6{grid-column:auto/span 6}.grid .g-col-7{grid-column:auto/span 7}.grid .g-col-8{grid-column:auto/span 8}.grid .g-col-9{grid-column:auto/span 9}.grid .g-col-10{grid-column:auto/span 10}.grid .g-col-11{grid-column:auto/span 11}.grid .g-col-12{grid-column:auto/span 12}.grid .g-start-1{grid-column-start:1}.grid .g-start-2{grid-column-start:2}.grid .g-start-3{grid-column-start:3}.grid .g-start-4{grid-column-start:4}.grid .g-start-5{grid-column-start:5}.grid .g-start-6{grid-column-start:6}.grid .g-start-7{grid-column-start:7}.grid .g-start-8{grid-column-start:8}.grid .g-start-9{grid-column-start:9}.grid .g-start-10{grid-column-start:10}.grid .g-start-11{grid-column-start:11}@media(min-width: 576px){.grid .g-col-sm-1{grid-column:auto/span 1}.grid .g-col-sm-2{grid-column:auto/span 2}.grid .g-col-sm-3{grid-column:auto/span 3}.grid .g-col-sm-4{grid-column:auto/span 4}.grid .g-col-sm-5{grid-column:auto/span 5}.grid .g-col-sm-6{grid-column:auto/span 6}.grid .g-col-sm-7{grid-column:auto/span 7}.grid .g-col-sm-8{grid-column:auto/span 8}.grid .g-col-sm-9{grid-column:auto/span 9}.grid .g-col-sm-10{grid-column:auto/span 10}.grid .g-col-sm-11{grid-column:auto/span 11}.grid .g-col-sm-12{grid-column:auto/span 12}.grid .g-start-sm-1{grid-column-start:1}.grid .g-start-sm-2{grid-column-start:2}.grid .g-start-sm-3{grid-column-start:3}.grid .g-start-sm-4{grid-column-start:4}.grid .g-start-sm-5{grid-column-start:5}.grid .g-start-sm-6{grid-column-start:6}.grid .g-start-sm-7{grid-column-start:7}.grid .g-start-sm-8{grid-column-start:8}.grid .g-start-sm-9{grid-column-start:9}.grid .g-start-sm-10{grid-column-start:10}.grid .g-start-sm-11{grid-column-start:11}}@media(min-width: 768px){.grid .g-col-md-1{grid-column:auto/span 1}.grid .g-col-md-2{grid-column:auto/span 2}.grid .g-col-md-3{grid-column:auto/span 3}.grid .g-col-md-4{grid-column:auto/span 4}.grid .g-col-md-5{grid-column:auto/span 5}.grid .g-col-md-6{grid-column:auto/span 6}.grid .g-col-md-7{grid-column:auto/span 7}.grid .g-col-md-8{grid-column:auto/span 8}.grid .g-col-md-9{grid-column:auto/span 9}.grid .g-col-md-10{grid-column:auto/span 10}.grid .g-col-md-11{grid-column:auto/span 11}.grid .g-col-md-12{grid-column:auto/span 12}.grid .g-start-md-1{grid-column-start:1}.grid .g-start-md-2{grid-column-start:2}.grid .g-start-md-3{grid-column-start:3}.grid .g-start-md-4{grid-column-start:4}.grid .g-start-md-5{grid-column-start:5}.grid .g-start-md-6{grid-column-start:6}.grid .g-start-md-7{grid-column-start:7}.grid .g-start-md-8{grid-column-start:8}.grid .g-start-md-9{grid-column-start:9}.grid .g-start-md-10{grid-column-start:10}.grid .g-start-md-11{grid-column-start:11}}@media(min-width: 992px){.grid .g-col-lg-1{grid-column:auto/span 1}.grid .g-col-lg-2{grid-column:auto/span 2}.grid .g-col-lg-3{grid-column:auto/span 3}.grid .g-col-lg-4{grid-column:auto/span 4}.grid .g-col-lg-5{grid-column:auto/span 5}.grid .g-col-lg-6{grid-column:auto/span 6}.grid .g-col-lg-7{grid-column:auto/span 7}.grid .g-col-lg-8{grid-column:auto/span 8}.grid .g-col-lg-9{grid-column:auto/span 9}.grid .g-col-lg-10{grid-column:auto/span 10}.grid .g-col-lg-11{grid-column:auto/span 11}.grid .g-col-lg-12{grid-column:auto/span 12}.grid .g-start-lg-1{grid-column-start:1}.grid .g-start-lg-2{grid-column-start:2}.grid .g-start-lg-3{grid-column-start:3}.grid .g-start-lg-4{grid-column-start:4}.grid .g-start-lg-5{grid-column-start:5}.grid .g-start-lg-6{grid-column-start:6}.grid .g-start-lg-7{grid-column-start:7}.grid .g-start-lg-8{grid-column-start:8}.grid .g-start-lg-9{grid-column-start:9}.grid .g-start-lg-10{grid-column-start:10}.grid .g-start-lg-11{grid-column-start:11}}@media(min-width: 1200px){.grid .g-col-xl-1{grid-column:auto/span 1}.grid .g-col-xl-2{grid-column:auto/span 2}.grid .g-col-xl-3{grid-column:auto/span 3}.grid .g-col-xl-4{grid-column:auto/span 4}.grid .g-col-xl-5{grid-column:auto/span 5}.grid .g-col-xl-6{grid-column:auto/span 6}.grid .g-col-xl-7{grid-column:auto/span 7}.grid .g-col-xl-8{grid-column:auto/span 8}.grid .g-col-xl-9{grid-column:auto/span 9}.grid .g-col-xl-10{grid-column:auto/span 10}.grid .g-col-xl-11{grid-column:auto/span 11}.grid .g-col-xl-12{grid-column:auto/span 12}.grid .g-start-xl-1{grid-column-start:1}.grid .g-start-xl-2{grid-column-start:2}.grid .g-start-xl-3{grid-column-start:3}.grid .g-start-xl-4{grid-column-start:4}.grid .g-start-xl-5{grid-column-start:5}.grid .g-start-xl-6{grid-column-start:6}.grid .g-start-xl-7{grid-column-start:7}.grid .g-start-xl-8{grid-column-start:8}.grid .g-start-xl-9{grid-column-start:9}.grid .g-start-xl-10{grid-column-start:10}.grid .g-start-xl-11{grid-column-start:11}}@media(min-width: 1400px){.grid .g-col-xxl-1{grid-column:auto/span 1}.grid .g-col-xxl-2{grid-column:auto/span 2}.grid .g-col-xxl-3{grid-column:auto/span 3}.grid .g-col-xxl-4{grid-column:auto/span 4}.grid .g-col-xxl-5{grid-column:auto/span 5}.grid .g-col-xxl-6{grid-column:auto/span 6}.grid .g-col-xxl-7{grid-column:auto/span 7}.grid .g-col-xxl-8{grid-column:auto/span 8}.grid .g-col-xxl-9{grid-column:auto/span 9}.grid .g-col-xxl-10{grid-column:auto/span 10}.grid .g-col-xxl-11{grid-column:auto/span 11}.grid .g-col-xxl-12{grid-column:auto/span 12}.grid .g-start-xxl-1{grid-column-start:1}.grid .g-start-xxl-2{grid-column-start:2}.grid .g-start-xxl-3{grid-column-start:3}.grid .g-start-xxl-4{grid-column-start:4}.grid .g-start-xxl-5{grid-column-start:5}.grid .g-start-xxl-6{grid-column-start:6}.grid .g-start-xxl-7{grid-column-start:7}.grid .g-start-xxl-8{grid-column-start:8}.grid .g-start-xxl-9{grid-column-start:9}.grid .g-start-xxl-10{grid-column-start:10}.grid .g-start-xxl-11{grid-column-start:11}}.table{--bs-table-color-type: initial;--bs-table-bg-type: initial;--bs-table-color-state: initial;--bs-table-bg-state: initial;--bs-table-color: #343a40;--bs-table-bg: #fff;--bs-table-border-color: #dee2e6;--bs-table-accent-bg: transparent;--bs-table-striped-color: #343a40;--bs-table-striped-bg: rgba(0, 0, 0, 0.05);--bs-table-active-color: #343a40;--bs-table-active-bg: rgba(0, 0, 0, 0.1);--bs-table-hover-color: #343a40;--bs-table-hover-bg: rgba(0, 0, 0, 0.075);width:100%;margin-bottom:1rem;vertical-align:top;border-color:var(--bs-table-border-color)}.table>:not(caption)>*>*{padding:.5rem .5rem;color:var(--bs-table-color-state, var(--bs-table-color-type, var(--bs-table-color)));background-color:var(--bs-table-bg);border-bottom-width:1px;box-shadow:inset 0 0 0 9999px var(--bs-table-bg-state, var(--bs-table-bg-type, var(--bs-table-accent-bg)))}.table>tbody{vertical-align:inherit}.table>thead{vertical-align:bottom}.table-group-divider{border-top:calc(1px*2) solid #b2bac1}.caption-top{caption-side:top}.table-sm>:not(caption)>*>*{padding:.25rem .25rem}.table-bordered>:not(caption)>*{border-width:1px 0}.table-bordered>:not(caption)>*>*{border-width:0 1px}.table-borderless>:not(caption)>*>*{border-bottom-width:0}.table-borderless>:not(:first-child){border-top-width:0}.table-striped>tbody>tr:nth-of-type(odd)>*{--bs-table-color-type: var(--bs-table-striped-color);--bs-table-bg-type: var(--bs-table-striped-bg)}.table-striped-columns>:not(caption)>tr>:nth-child(even){--bs-table-color-type: var(--bs-table-striped-color);--bs-table-bg-type: var(--bs-table-striped-bg)}.table-active{--bs-table-color-state: var(--bs-table-active-color);--bs-table-bg-state: var(--bs-table-active-bg)}.table-hover>tbody>tr:hover>*{--bs-table-color-state: var(--bs-table-hover-color);--bs-table-bg-state: var(--bs-table-hover-bg)}.table-primary{--bs-table-color: #000;--bs-table-bg: #d4e6f9;--bs-table-border-color: #bfcfe0;--bs-table-striped-bg: #c9dbed;--bs-table-striped-color: #000;--bs-table-active-bg: #bfcfe0;--bs-table-active-color: #000;--bs-table-hover-bg: #c4d5e6;--bs-table-hover-color: #000;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-secondary{--bs-table-color: #000;--bs-table-bg: #d6d8d9;--bs-table-border-color: #c1c2c3;--bs-table-striped-bg: #cbcdce;--bs-table-striped-color: #000;--bs-table-active-bg: #c1c2c3;--bs-table-active-color: #000;--bs-table-hover-bg: #c6c8c9;--bs-table-hover-color: #000;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-success{--bs-table-color: #000;--bs-table-bg: #d9f0d1;--bs-table-border-color: #c3d8bc;--bs-table-striped-bg: #cee4c7;--bs-table-striped-color: #000;--bs-table-active-bg: #c3d8bc;--bs-table-active-color: #000;--bs-table-hover-bg: #c9dec1;--bs-table-hover-color: #000;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-info{--bs-table-color: #000;--bs-table-bg: #ebddf1;--bs-table-border-color: #d4c7d9;--bs-table-striped-bg: #dfd2e5;--bs-table-striped-color: #000;--bs-table-active-bg: #d4c7d9;--bs-table-active-color: #000;--bs-table-hover-bg: #d9ccdf;--bs-table-hover-color: #000;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-warning{--bs-table-color: #000;--bs-table-bg: #ffe3d1;--bs-table-border-color: #e6ccbc;--bs-table-striped-bg: #f2d8c7;--bs-table-striped-color: #000;--bs-table-active-bg: #e6ccbc;--bs-table-active-color: #000;--bs-table-hover-bg: #ecd2c1;--bs-table-hover-color: #000;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-danger{--bs-table-color: #000;--bs-table-bg: #ffccd7;--bs-table-border-color: #e6b8c2;--bs-table-striped-bg: #f2c2cc;--bs-table-striped-color: #000;--bs-table-active-bg: #e6b8c2;--bs-table-active-color: #000;--bs-table-hover-bg: #ecbdc7;--bs-table-hover-color: #000;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-light{--bs-table-color: #000;--bs-table-bg: #f8f9fa;--bs-table-border-color: #dfe0e1;--bs-table-striped-bg: #ecedee;--bs-table-striped-color: #000;--bs-table-active-bg: #dfe0e1;--bs-table-active-color: #000;--bs-table-hover-bg: #e5e6e7;--bs-table-hover-color: #000;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-dark{--bs-table-color: #fff;--bs-table-bg: #343a40;--bs-table-border-color: #484e53;--bs-table-striped-bg: #3e444a;--bs-table-striped-color: #fff;--bs-table-active-bg: #484e53;--bs-table-active-color: #fff;--bs-table-hover-bg: #43494e;--bs-table-hover-color: #fff;color:var(--bs-table-color);border-color:var(--bs-table-border-color)}.table-responsive{overflow-x:auto;-webkit-overflow-scrolling:touch}@media(max-width: 575.98px){.table-responsive-sm{overflow-x:auto;-webkit-overflow-scrolling:touch}}@media(max-width: 767.98px){.table-responsive-md{overflow-x:auto;-webkit-overflow-scrolling:touch}}@media(max-width: 991.98px){.table-responsive-lg{overflow-x:auto;-webkit-overflow-scrolling:touch}}@media(max-width: 1199.98px){.table-responsive-xl{overflow-x:auto;-webkit-overflow-scrolling:touch}}@media(max-width: 1399.98px){.table-responsive-xxl{overflow-x:auto;-webkit-overflow-scrolling:touch}}.form-label,.shiny-input-container .control-label{margin-bottom:.5rem}.col-form-label{padding-top:calc(0.375rem + 1px);padding-bottom:calc(0.375rem + 1px);margin-bottom:0;font-size:inherit;line-height:1.5}.col-form-label-lg{padding-top:calc(0.5rem + 1px);padding-bottom:calc(0.5rem + 1px);font-size:1.25rem}.col-form-label-sm{padding-top:calc(0.25rem + 1px);padding-bottom:calc(0.25rem + 1px);font-size:0.875rem}.form-text{margin-top:.25rem;font-size:0.875em;color:rgba(52,58,64,.75)}.form-control{display:block;width:100%;padding:.375rem .75rem;font-size:1rem;font-weight:400;line-height:1.5;color:#343a40;appearance:none;-webkit-appearance:none;-moz-appearance:none;-ms-appearance:none;-o-appearance:none;background-color:#fff;background-clip:padding-box;border:1px solid #dee2e6;border-radius:0;transition:border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media(prefers-reduced-motion: reduce){.form-control{transition:none}}.form-control[type=file]{overflow:hidden}.form-control[type=file]:not(:disabled):not([readonly]){cursor:pointer}.form-control:focus{color:#343a40;background-color:#fff;border-color:#93c0f1;outline:0;box-shadow:0 0 0 .25rem rgba(39,128,227,.25)}.form-control::-webkit-date-and-time-value{min-width:85px;height:1.5em;margin:0}.form-control::-webkit-datetime-edit{display:block;padding:0}.form-control::placeholder{color:rgba(52,58,64,.75);opacity:1}.form-control:disabled{background-color:#e9ecef;opacity:1}.form-control::file-selector-button{padding:.375rem .75rem;margin:-0.375rem -0.75rem;margin-inline-end:.75rem;color:#343a40;background-color:#f8f9fa;pointer-events:none;border-color:inherit;border-style:solid;border-width:0;border-inline-end-width:1px;border-radius:0;transition:color .15s ease-in-out,background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media(prefers-reduced-motion: reduce){.form-control::file-selector-button{transition:none}}.form-control:hover:not(:disabled):not([readonly])::file-selector-button{background-color:#e9ecef}.form-control-plaintext{display:block;width:100%;padding:.375rem 0;margin-bottom:0;line-height:1.5;color:#343a40;background-color:rgba(0,0,0,0);border:solid rgba(0,0,0,0);border-width:1px 0}.form-control-plaintext:focus{outline:0}.form-control-plaintext.form-control-sm,.form-control-plaintext.form-control-lg{padding-right:0;padding-left:0}.form-control-sm{min-height:calc(1.5em + 0.5rem + calc(1px * 2));padding:.25rem .5rem;font-size:0.875rem}.form-control-sm::file-selector-button{padding:.25rem .5rem;margin:-0.25rem -0.5rem;margin-inline-end:.5rem}.form-control-lg{min-height:calc(1.5em + 1rem + calc(1px * 2));padding:.5rem 1rem;font-size:1.25rem}.form-control-lg::file-selector-button{padding:.5rem 1rem;margin:-0.5rem -1rem;margin-inline-end:1rem}textarea.form-control{min-height:calc(1.5em + 0.75rem + calc(1px * 2))}textarea.form-control-sm{min-height:calc(1.5em + 0.5rem + calc(1px * 2))}textarea.form-control-lg{min-height:calc(1.5em + 1rem + calc(1px * 2))}.form-control-color{width:3rem;height:calc(1.5em + 0.75rem + calc(1px * 2));padding:.375rem}.form-control-color:not(:disabled):not([readonly]){cursor:pointer}.form-control-color::-moz-color-swatch{border:0 !important}.form-control-color::-webkit-color-swatch{border:0 !important}.form-control-color.form-control-sm{height:calc(1.5em + 0.5rem + calc(1px * 2))}.form-control-color.form-control-lg{height:calc(1.5em + 1rem + calc(1px * 2))}.form-select{--bs-form-select-bg-img: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3e%3cpath fill='none' stroke='%23343a40' stroke-linecap='round' stroke-linejoin='round' stroke-width='2' d='m2 5 6 6 6-6'/%3e%3c/svg%3e");display:block;width:100%;padding:.375rem 2.25rem .375rem .75rem;font-size:1rem;font-weight:400;line-height:1.5;color:#343a40;appearance:none;-webkit-appearance:none;-moz-appearance:none;-ms-appearance:none;-o-appearance:none;background-color:#fff;background-image:var(--bs-form-select-bg-img),var(--bs-form-select-bg-icon, none);background-repeat:no-repeat;background-position:right .75rem center;background-size:16px 12px;border:1px solid #dee2e6;border-radius:0;transition:border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media(prefers-reduced-motion: reduce){.form-select{transition:none}}.form-select:focus{border-color:#93c0f1;outline:0;box-shadow:0 0 0 .25rem rgba(39,128,227,.25)}.form-select[multiple],.form-select[size]:not([size="1"]){padding-right:.75rem;background-image:none}.form-select:disabled{background-color:#e9ecef}.form-select:-moz-focusring{color:rgba(0,0,0,0);text-shadow:0 0 0 #343a40}.form-select-sm{padding-top:.25rem;padding-bottom:.25rem;padding-left:.5rem;font-size:0.875rem}.form-select-lg{padding-top:.5rem;padding-bottom:.5rem;padding-left:1rem;font-size:1.25rem}[data-bs-theme=dark] .form-select{--bs-form-select-bg-img: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3e%3cpath fill='none' stroke='%23dee2e6' stroke-linecap='round' stroke-linejoin='round' stroke-width='2' d='m2 5 6 6 6-6'/%3e%3c/svg%3e")}.form-check,.shiny-input-container .checkbox,.shiny-input-container .radio{display:block;min-height:1.5rem;padding-left:0;margin-bottom:.125rem}.form-check .form-check-input,.form-check .shiny-input-container .checkbox input,.form-check .shiny-input-container .radio input,.shiny-input-container .checkbox .form-check-input,.shiny-input-container .checkbox .shiny-input-container .checkbox input,.shiny-input-container .checkbox .shiny-input-container .radio input,.shiny-input-container .radio .form-check-input,.shiny-input-container .radio .shiny-input-container .checkbox input,.shiny-input-container .radio .shiny-input-container .radio input{float:left;margin-left:0}.form-check-reverse{padding-right:0;padding-left:0;text-align:right}.form-check-reverse .form-check-input{float:right;margin-right:0;margin-left:0}.form-check-input,.shiny-input-container .checkbox input,.shiny-input-container .checkbox-inline input,.shiny-input-container .radio input,.shiny-input-container .radio-inline input{--bs-form-check-bg: #fff;width:1em;height:1em;margin-top:.25em;vertical-align:top;appearance:none;-webkit-appearance:none;-moz-appearance:none;-ms-appearance:none;-o-appearance:none;background-color:var(--bs-form-check-bg);background-image:var(--bs-form-check-bg-image);background-repeat:no-repeat;background-position:center;background-size:contain;border:1px solid #dee2e6;print-color-adjust:exact}.form-check-input[type=radio],.shiny-input-container .checkbox input[type=radio],.shiny-input-container .checkbox-inline input[type=radio],.shiny-input-container .radio input[type=radio],.shiny-input-container .radio-inline input[type=radio]{border-radius:50%}.form-check-input:active,.shiny-input-container .checkbox input:active,.shiny-input-container .checkbox-inline input:active,.shiny-input-container .radio input:active,.shiny-input-container .radio-inline input:active{filter:brightness(90%)}.form-check-input:focus,.shiny-input-container .checkbox input:focus,.shiny-input-container .checkbox-inline input:focus,.shiny-input-container .radio input:focus,.shiny-input-container .radio-inline input:focus{border-color:#93c0f1;outline:0;box-shadow:0 0 0 .25rem rgba(39,128,227,.25)}.form-check-input:checked,.shiny-input-container .checkbox input:checked,.shiny-input-container .checkbox-inline input:checked,.shiny-input-container .radio input:checked,.shiny-input-container .radio-inline input:checked{background-color:#2780e3;border-color:#2780e3}.form-check-input:checked[type=checkbox],.shiny-input-container .checkbox input:checked[type=checkbox],.shiny-input-container .checkbox-inline input:checked[type=checkbox],.shiny-input-container .radio input:checked[type=checkbox],.shiny-input-container .radio-inline input:checked[type=checkbox]{--bs-form-check-bg-image: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20'%3e%3cpath fill='none' stroke='%23fff' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='m6 10 3 3 6-6'/%3e%3c/svg%3e")}.form-check-input:checked[type=radio],.shiny-input-container .checkbox input:checked[type=radio],.shiny-input-container .checkbox-inline input:checked[type=radio],.shiny-input-container .radio input:checked[type=radio],.shiny-input-container .radio-inline input:checked[type=radio]{--bs-form-check-bg-image: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='-4 -4 8 8'%3e%3ccircle r='2' fill='%23fff'/%3e%3c/svg%3e")}.form-check-input[type=checkbox]:indeterminate,.shiny-input-container .checkbox input[type=checkbox]:indeterminate,.shiny-input-container .checkbox-inline input[type=checkbox]:indeterminate,.shiny-input-container .radio input[type=checkbox]:indeterminate,.shiny-input-container .radio-inline input[type=checkbox]:indeterminate{background-color:#2780e3;border-color:#2780e3;--bs-form-check-bg-image: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20'%3e%3cpath fill='none' stroke='%23fff' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='M6 10h8'/%3e%3c/svg%3e")}.form-check-input:disabled,.shiny-input-container .checkbox input:disabled,.shiny-input-container .checkbox-inline input:disabled,.shiny-input-container .radio input:disabled,.shiny-input-container .radio-inline input:disabled{pointer-events:none;filter:none;opacity:.5}.form-check-input[disabled]~.form-check-label,.form-check-input[disabled]~span,.form-check-input:disabled~.form-check-label,.form-check-input:disabled~span,.shiny-input-container .checkbox input[disabled]~.form-check-label,.shiny-input-container .checkbox input[disabled]~span,.shiny-input-container .checkbox input:disabled~.form-check-label,.shiny-input-container .checkbox input:disabled~span,.shiny-input-container .checkbox-inline input[disabled]~.form-check-label,.shiny-input-container .checkbox-inline input[disabled]~span,.shiny-input-container .checkbox-inline input:disabled~.form-check-label,.shiny-input-container .checkbox-inline input:disabled~span,.shiny-input-container .radio input[disabled]~.form-check-label,.shiny-input-container .radio input[disabled]~span,.shiny-input-container .radio input:disabled~.form-check-label,.shiny-input-container .radio input:disabled~span,.shiny-input-container .radio-inline input[disabled]~.form-check-label,.shiny-input-container .radio-inline input[disabled]~span,.shiny-input-container .radio-inline input:disabled~.form-check-label,.shiny-input-container .radio-inline input:disabled~span{cursor:default;opacity:.5}.form-check-label,.shiny-input-container .checkbox label,.shiny-input-container .checkbox-inline label,.shiny-input-container .radio label,.shiny-input-container .radio-inline label{cursor:pointer}.form-switch{padding-left:2.5em}.form-switch .form-check-input{--bs-form-switch-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='-4 -4 8 8'%3e%3ccircle r='3' fill='rgba%280, 0, 0, 0.25%29'/%3e%3c/svg%3e");width:2em;margin-left:-2.5em;background-image:var(--bs-form-switch-bg);background-position:left center;transition:background-position .15s ease-in-out}@media(prefers-reduced-motion: reduce){.form-switch .form-check-input{transition:none}}.form-switch .form-check-input:focus{--bs-form-switch-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='-4 -4 8 8'%3e%3ccircle r='3' fill='%2393c0f1'/%3e%3c/svg%3e")}.form-switch .form-check-input:checked{background-position:right center;--bs-form-switch-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='-4 -4 8 8'%3e%3ccircle r='3' fill='%23fff'/%3e%3c/svg%3e")}.form-switch.form-check-reverse{padding-right:2.5em;padding-left:0}.form-switch.form-check-reverse .form-check-input{margin-right:-2.5em;margin-left:0}.form-check-inline{display:inline-block;margin-right:1rem}.btn-check{position:absolute;clip:rect(0, 0, 0, 0);pointer-events:none}.btn-check[disabled]+.btn,.btn-check:disabled+.btn{pointer-events:none;filter:none;opacity:.65}[data-bs-theme=dark] .form-switch .form-check-input:not(:checked):not(:focus){--bs-form-switch-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='-4 -4 8 8'%3e%3ccircle r='3' fill='rgba%28255, 255, 255, 0.25%29'/%3e%3c/svg%3e")}.form-range{width:100%;height:1.5rem;padding:0;appearance:none;-webkit-appearance:none;-moz-appearance:none;-ms-appearance:none;-o-appearance:none;background-color:rgba(0,0,0,0)}.form-range:focus{outline:0}.form-range:focus::-webkit-slider-thumb{box-shadow:0 0 0 1px #fff,0 0 0 .25rem rgba(39,128,227,.25)}.form-range:focus::-moz-range-thumb{box-shadow:0 0 0 1px #fff,0 0 0 .25rem rgba(39,128,227,.25)}.form-range::-moz-focus-outer{border:0}.form-range::-webkit-slider-thumb{width:1rem;height:1rem;margin-top:-0.25rem;appearance:none;-webkit-appearance:none;-moz-appearance:none;-ms-appearance:none;-o-appearance:none;background-color:#2780e3;border:0;transition:background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media(prefers-reduced-motion: reduce){.form-range::-webkit-slider-thumb{transition:none}}.form-range::-webkit-slider-thumb:active{background-color:#bed9f7}.form-range::-webkit-slider-runnable-track{width:100%;height:.5rem;color:rgba(0,0,0,0);cursor:pointer;background-color:#f8f9fa;border-color:rgba(0,0,0,0)}.form-range::-moz-range-thumb{width:1rem;height:1rem;appearance:none;-webkit-appearance:none;-moz-appearance:none;-ms-appearance:none;-o-appearance:none;background-color:#2780e3;border:0;transition:background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media(prefers-reduced-motion: reduce){.form-range::-moz-range-thumb{transition:none}}.form-range::-moz-range-thumb:active{background-color:#bed9f7}.form-range::-moz-range-track{width:100%;height:.5rem;color:rgba(0,0,0,0);cursor:pointer;background-color:#f8f9fa;border-color:rgba(0,0,0,0)}.form-range:disabled{pointer-events:none}.form-range:disabled::-webkit-slider-thumb{background-color:rgba(52,58,64,.75)}.form-range:disabled::-moz-range-thumb{background-color:rgba(52,58,64,.75)}.form-floating{position:relative}.form-floating>.form-control,.form-floating>.form-control-plaintext,.form-floating>.form-select{height:calc(3.5rem + calc(1px * 2));min-height:calc(3.5rem + calc(1px * 2));line-height:1.25}.form-floating>label{position:absolute;top:0;left:0;z-index:2;height:100%;padding:1rem .75rem;overflow:hidden;text-align:start;text-overflow:ellipsis;white-space:nowrap;pointer-events:none;border:1px solid rgba(0,0,0,0);transform-origin:0 0;transition:opacity .1s ease-in-out,transform .1s ease-in-out}@media(prefers-reduced-motion: reduce){.form-floating>label{transition:none}}.form-floating>.form-control,.form-floating>.form-control-plaintext{padding:1rem .75rem}.form-floating>.form-control::placeholder,.form-floating>.form-control-plaintext::placeholder{color:rgba(0,0,0,0)}.form-floating>.form-control:focus,.form-floating>.form-control:not(:placeholder-shown),.form-floating>.form-control-plaintext:focus,.form-floating>.form-control-plaintext:not(:placeholder-shown){padding-top:1.625rem;padding-bottom:.625rem}.form-floating>.form-control:-webkit-autofill,.form-floating>.form-control-plaintext:-webkit-autofill{padding-top:1.625rem;padding-bottom:.625rem}.form-floating>.form-select{padding-top:1.625rem;padding-bottom:.625rem}.form-floating>.form-control:focus~label,.form-floating>.form-control:not(:placeholder-shown)~label,.form-floating>.form-control-plaintext~label,.form-floating>.form-select~label{color:rgba(var(--bs-body-color-rgb), 0.65);transform:scale(0.85) translateY(-0.5rem) translateX(0.15rem)}.form-floating>.form-control:focus~label::after,.form-floating>.form-control:not(:placeholder-shown)~label::after,.form-floating>.form-control-plaintext~label::after,.form-floating>.form-select~label::after{position:absolute;inset:1rem .375rem;z-index:-1;height:1.5em;content:"";background-color:#fff}.form-floating>.form-control:-webkit-autofill~label{color:rgba(var(--bs-body-color-rgb), 0.65);transform:scale(0.85) translateY(-0.5rem) translateX(0.15rem)}.form-floating>.form-control-plaintext~label{border-width:1px 0}.form-floating>:disabled~label,.form-floating>.form-control:disabled~label{color:#6c757d}.form-floating>:disabled~label::after,.form-floating>.form-control:disabled~label::after{background-color:#e9ecef}.input-group{position:relative;display:flex;display:-webkit-flex;flex-wrap:wrap;-webkit-flex-wrap:wrap;align-items:stretch;-webkit-align-items:stretch;width:100%}.input-group>.form-control,.input-group>.form-select,.input-group>.form-floating{position:relative;flex:1 1 auto;-webkit-flex:1 1 auto;width:1%;min-width:0}.input-group>.form-control:focus,.input-group>.form-select:focus,.input-group>.form-floating:focus-within{z-index:5}.input-group .btn{position:relative;z-index:2}.input-group .btn:focus{z-index:5}.input-group-text{display:flex;display:-webkit-flex;align-items:center;-webkit-align-items:center;padding:.375rem .75rem;font-size:1rem;font-weight:400;line-height:1.5;color:#343a40;text-align:center;white-space:nowrap;background-color:#f8f9fa;border:1px solid #dee2e6}.input-group-lg>.form-control,.input-group-lg>.form-select,.input-group-lg>.input-group-text,.input-group-lg>.btn{padding:.5rem 1rem;font-size:1.25rem}.input-group-sm>.form-control,.input-group-sm>.form-select,.input-group-sm>.input-group-text,.input-group-sm>.btn{padding:.25rem .5rem;font-size:0.875rem}.input-group-lg>.form-select,.input-group-sm>.form-select{padding-right:3rem}.input-group>:not(:first-child):not(.dropdown-menu):not(.valid-tooltip):not(.valid-feedback):not(.invalid-tooltip):not(.invalid-feedback){margin-left:calc(1px*-1)}.valid-feedback{display:none;width:100%;margin-top:.25rem;font-size:0.875em;color:#3fb618}.valid-tooltip{position:absolute;top:100%;z-index:5;display:none;max-width:100%;padding:.25rem .5rem;margin-top:.1rem;font-size:0.875rem;color:#fff;background-color:#3fb618}.was-validated :valid~.valid-feedback,.was-validated :valid~.valid-tooltip,.is-valid~.valid-feedback,.is-valid~.valid-tooltip{display:block}.was-validated .form-control:valid,.form-control.is-valid{border-color:#3fb618;padding-right:calc(1.5em + 0.75rem);background-image:url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 8 8'%3e%3cpath fill='%233fb618' d='M2.3 6.73.6 4.53c-.4-1.04.46-1.4 1.1-.8l1.1 1.4 3.4-3.8c.6-.63 1.6-.27 1.2.7l-4 4.6c-.43.5-.8.4-1.1.1z'/%3e%3c/svg%3e");background-repeat:no-repeat;background-position:right calc(0.375em + 0.1875rem) center;background-size:calc(0.75em + 0.375rem) calc(0.75em + 0.375rem)}.was-validated .form-control:valid:focus,.form-control.is-valid:focus{border-color:#3fb618;box-shadow:0 0 0 .25rem rgba(63,182,24,.25)}.was-validated textarea.form-control:valid,textarea.form-control.is-valid{padding-right:calc(1.5em + 0.75rem);background-position:top calc(0.375em + 0.1875rem) right calc(0.375em + 0.1875rem)}.was-validated .form-select:valid,.form-select.is-valid{border-color:#3fb618}.was-validated .form-select:valid:not([multiple]):not([size]),.was-validated .form-select:valid:not([multiple])[size="1"],.form-select.is-valid:not([multiple]):not([size]),.form-select.is-valid:not([multiple])[size="1"]{--bs-form-select-bg-icon: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 8 8'%3e%3cpath fill='%233fb618' d='M2.3 6.73.6 4.53c-.4-1.04.46-1.4 1.1-.8l1.1 1.4 3.4-3.8c.6-.63 1.6-.27 1.2.7l-4 4.6c-.43.5-.8.4-1.1.1z'/%3e%3c/svg%3e");padding-right:4.125rem;background-position:right .75rem center,center right 2.25rem;background-size:16px 12px,calc(0.75em + 0.375rem) calc(0.75em + 0.375rem)}.was-validated .form-select:valid:focus,.form-select.is-valid:focus{border-color:#3fb618;box-shadow:0 0 0 .25rem rgba(63,182,24,.25)}.was-validated .form-control-color:valid,.form-control-color.is-valid{width:calc(3rem + calc(1.5em + 0.75rem))}.was-validated .form-check-input:valid,.form-check-input.is-valid{border-color:#3fb618}.was-validated .form-check-input:valid:checked,.form-check-input.is-valid:checked{background-color:#3fb618}.was-validated .form-check-input:valid:focus,.form-check-input.is-valid:focus{box-shadow:0 0 0 .25rem rgba(63,182,24,.25)}.was-validated .form-check-input:valid~.form-check-label,.form-check-input.is-valid~.form-check-label{color:#3fb618}.form-check-inline .form-check-input~.valid-feedback{margin-left:.5em}.was-validated .input-group>.form-control:not(:focus):valid,.input-group>.form-control:not(:focus).is-valid,.was-validated .input-group>.form-select:not(:focus):valid,.input-group>.form-select:not(:focus).is-valid,.was-validated .input-group>.form-floating:not(:focus-within):valid,.input-group>.form-floating:not(:focus-within).is-valid{z-index:3}.invalid-feedback{display:none;width:100%;margin-top:.25rem;font-size:0.875em;color:#ff0039}.invalid-tooltip{position:absolute;top:100%;z-index:5;display:none;max-width:100%;padding:.25rem .5rem;margin-top:.1rem;font-size:0.875rem;color:#fff;background-color:#ff0039}.was-validated :invalid~.invalid-feedback,.was-validated :invalid~.invalid-tooltip,.is-invalid~.invalid-feedback,.is-invalid~.invalid-tooltip{display:block}.was-validated .form-control:invalid,.form-control.is-invalid{border-color:#ff0039;padding-right:calc(1.5em + 0.75rem);background-image:url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12' width='12' height='12' fill='none' stroke='%23ff0039'%3e%3ccircle cx='6' cy='6' r='4.5'/%3e%3cpath stroke-linejoin='round' d='M5.8 3.6h.4L6 6.5z'/%3e%3ccircle cx='6' cy='8.2' r='.6' fill='%23ff0039' stroke='none'/%3e%3c/svg%3e");background-repeat:no-repeat;background-position:right calc(0.375em + 0.1875rem) center;background-size:calc(0.75em + 0.375rem) calc(0.75em + 0.375rem)}.was-validated .form-control:invalid:focus,.form-control.is-invalid:focus{border-color:#ff0039;box-shadow:0 0 0 .25rem rgba(255,0,57,.25)}.was-validated textarea.form-control:invalid,textarea.form-control.is-invalid{padding-right:calc(1.5em + 0.75rem);background-position:top calc(0.375em + 0.1875rem) right calc(0.375em + 0.1875rem)}.was-validated .form-select:invalid,.form-select.is-invalid{border-color:#ff0039}.was-validated .form-select:invalid:not([multiple]):not([size]),.was-validated .form-select:invalid:not([multiple])[size="1"],.form-select.is-invalid:not([multiple]):not([size]),.form-select.is-invalid:not([multiple])[size="1"]{--bs-form-select-bg-icon: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12' width='12' height='12' fill='none' stroke='%23ff0039'%3e%3ccircle cx='6' cy='6' r='4.5'/%3e%3cpath stroke-linejoin='round' d='M5.8 3.6h.4L6 6.5z'/%3e%3ccircle cx='6' cy='8.2' r='.6' fill='%23ff0039' stroke='none'/%3e%3c/svg%3e");padding-right:4.125rem;background-position:right .75rem center,center right 2.25rem;background-size:16px 12px,calc(0.75em + 0.375rem) calc(0.75em + 0.375rem)}.was-validated .form-select:invalid:focus,.form-select.is-invalid:focus{border-color:#ff0039;box-shadow:0 0 0 .25rem rgba(255,0,57,.25)}.was-validated .form-control-color:invalid,.form-control-color.is-invalid{width:calc(3rem + calc(1.5em + 0.75rem))}.was-validated .form-check-input:invalid,.form-check-input.is-invalid{border-color:#ff0039}.was-validated .form-check-input:invalid:checked,.form-check-input.is-invalid:checked{background-color:#ff0039}.was-validated .form-check-input:invalid:focus,.form-check-input.is-invalid:focus{box-shadow:0 0 0 .25rem rgba(255,0,57,.25)}.was-validated .form-check-input:invalid~.form-check-label,.form-check-input.is-invalid~.form-check-label{color:#ff0039}.form-check-inline .form-check-input~.invalid-feedback{margin-left:.5em}.was-validated .input-group>.form-control:not(:focus):invalid,.input-group>.form-control:not(:focus).is-invalid,.was-validated .input-group>.form-select:not(:focus):invalid,.input-group>.form-select:not(:focus).is-invalid,.was-validated .input-group>.form-floating:not(:focus-within):invalid,.input-group>.form-floating:not(:focus-within).is-invalid{z-index:4}.btn{--bs-btn-padding-x: 0.75rem;--bs-btn-padding-y: 0.375rem;--bs-btn-font-family: ;--bs-btn-font-size:1rem;--bs-btn-font-weight: 400;--bs-btn-line-height: 1.5;--bs-btn-color: #343a40;--bs-btn-bg: transparent;--bs-btn-border-width: 1px;--bs-btn-border-color: transparent;--bs-btn-border-radius: 0.25rem;--bs-btn-hover-border-color: transparent;--bs-btn-box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.15), 0 1px 1px rgba(0, 0, 0, 0.075);--bs-btn-disabled-opacity: 0.65;--bs-btn-focus-box-shadow: 0 0 0 0.25rem rgba(var(--bs-btn-focus-shadow-rgb), .5);display:inline-block;padding:var(--bs-btn-padding-y) var(--bs-btn-padding-x);font-family:var(--bs-btn-font-family);font-size:var(--bs-btn-font-size);font-weight:var(--bs-btn-font-weight);line-height:var(--bs-btn-line-height);color:var(--bs-btn-color);text-align:center;text-decoration:none;-webkit-text-decoration:none;-moz-text-decoration:none;-ms-text-decoration:none;-o-text-decoration:none;vertical-align:middle;cursor:pointer;user-select:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;-o-user-select:none;border:var(--bs-btn-border-width) solid var(--bs-btn-border-color);background-color:var(--bs-btn-bg);transition:color .15s ease-in-out,background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media(prefers-reduced-motion: reduce){.btn{transition:none}}.btn:hover{color:var(--bs-btn-hover-color);background-color:var(--bs-btn-hover-bg);border-color:var(--bs-btn-hover-border-color)}.btn-check+.btn:hover{color:var(--bs-btn-color);background-color:var(--bs-btn-bg);border-color:var(--bs-btn-border-color)}.btn:focus-visible{color:var(--bs-btn-hover-color);background-color:var(--bs-btn-hover-bg);border-color:var(--bs-btn-hover-border-color);outline:0;box-shadow:var(--bs-btn-focus-box-shadow)}.btn-check:focus-visible+.btn{border-color:var(--bs-btn-hover-border-color);outline:0;box-shadow:var(--bs-btn-focus-box-shadow)}.btn-check:checked+.btn,:not(.btn-check)+.btn:active,.btn:first-child:active,.btn.active,.btn.show{color:var(--bs-btn-active-color);background-color:var(--bs-btn-active-bg);border-color:var(--bs-btn-active-border-color)}.btn-check:checked+.btn:focus-visible,:not(.btn-check)+.btn:active:focus-visible,.btn:first-child:active:focus-visible,.btn.active:focus-visible,.btn.show:focus-visible{box-shadow:var(--bs-btn-focus-box-shadow)}.btn:disabled,.btn.disabled,fieldset:disabled .btn{color:var(--bs-btn-disabled-color);pointer-events:none;background-color:var(--bs-btn-disabled-bg);border-color:var(--bs-btn-disabled-border-color);opacity:var(--bs-btn-disabled-opacity)}.btn-default{--bs-btn-color: #fff;--bs-btn-bg: #343a40;--bs-btn-border-color: #343a40;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #2c3136;--bs-btn-hover-border-color: #2a2e33;--bs-btn-focus-shadow-rgb: 82, 88, 93;--bs-btn-active-color: #fff;--bs-btn-active-bg: #2a2e33;--bs-btn-active-border-color: #272c30;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #343a40;--bs-btn-disabled-border-color: #343a40}.btn-primary{--bs-btn-color: #fff;--bs-btn-bg: #2780e3;--bs-btn-border-color: #2780e3;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #216dc1;--bs-btn-hover-border-color: #1f66b6;--bs-btn-focus-shadow-rgb: 71, 147, 231;--bs-btn-active-color: #fff;--bs-btn-active-bg: #1f66b6;--bs-btn-active-border-color: #1d60aa;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #2780e3;--bs-btn-disabled-border-color: #2780e3}.btn-secondary{--bs-btn-color: #fff;--bs-btn-bg: #343a40;--bs-btn-border-color: #343a40;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #2c3136;--bs-btn-hover-border-color: #2a2e33;--bs-btn-focus-shadow-rgb: 82, 88, 93;--bs-btn-active-color: #fff;--bs-btn-active-bg: #2a2e33;--bs-btn-active-border-color: #272c30;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #343a40;--bs-btn-disabled-border-color: #343a40}.btn-success{--bs-btn-color: #fff;--bs-btn-bg: #3fb618;--bs-btn-border-color: #3fb618;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #369b14;--bs-btn-hover-border-color: #329213;--bs-btn-focus-shadow-rgb: 92, 193, 59;--bs-btn-active-color: #fff;--bs-btn-active-bg: #329213;--bs-btn-active-border-color: #2f8912;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #3fb618;--bs-btn-disabled-border-color: #3fb618}.btn-info{--bs-btn-color: #fff;--bs-btn-bg: #9954bb;--bs-btn-border-color: #9954bb;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #82479f;--bs-btn-hover-border-color: #7a4396;--bs-btn-focus-shadow-rgb: 168, 110, 197;--bs-btn-active-color: #fff;--bs-btn-active-bg: #7a4396;--bs-btn-active-border-color: #733f8c;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #9954bb;--bs-btn-disabled-border-color: #9954bb}.btn-warning{--bs-btn-color: #fff;--bs-btn-bg: #ff7518;--bs-btn-border-color: #ff7518;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #d96314;--bs-btn-hover-border-color: #cc5e13;--bs-btn-focus-shadow-rgb: 255, 138, 59;--bs-btn-active-color: #fff;--bs-btn-active-bg: #cc5e13;--bs-btn-active-border-color: #bf5812;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #ff7518;--bs-btn-disabled-border-color: #ff7518}.btn-danger{--bs-btn-color: #fff;--bs-btn-bg: #ff0039;--bs-btn-border-color: #ff0039;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #d90030;--bs-btn-hover-border-color: #cc002e;--bs-btn-focus-shadow-rgb: 255, 38, 87;--bs-btn-active-color: #fff;--bs-btn-active-bg: #cc002e;--bs-btn-active-border-color: #bf002b;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #ff0039;--bs-btn-disabled-border-color: #ff0039}.btn-light{--bs-btn-color: #000;--bs-btn-bg: #f8f9fa;--bs-btn-border-color: #f8f9fa;--bs-btn-hover-color: #000;--bs-btn-hover-bg: #d3d4d5;--bs-btn-hover-border-color: #c6c7c8;--bs-btn-focus-shadow-rgb: 211, 212, 213;--bs-btn-active-color: #000;--bs-btn-active-bg: #c6c7c8;--bs-btn-active-border-color: #babbbc;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #000;--bs-btn-disabled-bg: #f8f9fa;--bs-btn-disabled-border-color: #f8f9fa}.btn-dark{--bs-btn-color: #fff;--bs-btn-bg: #343a40;--bs-btn-border-color: #343a40;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #52585d;--bs-btn-hover-border-color: #484e53;--bs-btn-focus-shadow-rgb: 82, 88, 93;--bs-btn-active-color: #fff;--bs-btn-active-bg: #5d6166;--bs-btn-active-border-color: #484e53;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #343a40;--bs-btn-disabled-border-color: #343a40}.btn-outline-default{--bs-btn-color: #343a40;--bs-btn-border-color: #343a40;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #343a40;--bs-btn-hover-border-color: #343a40;--bs-btn-focus-shadow-rgb: 52, 58, 64;--bs-btn-active-color: #fff;--bs-btn-active-bg: #343a40;--bs-btn-active-border-color: #343a40;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #343a40;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #343a40;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-primary{--bs-btn-color: #2780e3;--bs-btn-border-color: #2780e3;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #2780e3;--bs-btn-hover-border-color: #2780e3;--bs-btn-focus-shadow-rgb: 39, 128, 227;--bs-btn-active-color: #fff;--bs-btn-active-bg: #2780e3;--bs-btn-active-border-color: #2780e3;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #2780e3;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #2780e3;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-secondary{--bs-btn-color: #343a40;--bs-btn-border-color: #343a40;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #343a40;--bs-btn-hover-border-color: #343a40;--bs-btn-focus-shadow-rgb: 52, 58, 64;--bs-btn-active-color: #fff;--bs-btn-active-bg: #343a40;--bs-btn-active-border-color: #343a40;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #343a40;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #343a40;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-success{--bs-btn-color: #3fb618;--bs-btn-border-color: #3fb618;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #3fb618;--bs-btn-hover-border-color: #3fb618;--bs-btn-focus-shadow-rgb: 63, 182, 24;--bs-btn-active-color: #fff;--bs-btn-active-bg: #3fb618;--bs-btn-active-border-color: #3fb618;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #3fb618;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #3fb618;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-info{--bs-btn-color: #9954bb;--bs-btn-border-color: #9954bb;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #9954bb;--bs-btn-hover-border-color: #9954bb;--bs-btn-focus-shadow-rgb: 153, 84, 187;--bs-btn-active-color: #fff;--bs-btn-active-bg: #9954bb;--bs-btn-active-border-color: #9954bb;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #9954bb;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #9954bb;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-warning{--bs-btn-color: #ff7518;--bs-btn-border-color: #ff7518;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #ff7518;--bs-btn-hover-border-color: #ff7518;--bs-btn-focus-shadow-rgb: 255, 117, 24;--bs-btn-active-color: #fff;--bs-btn-active-bg: #ff7518;--bs-btn-active-border-color: #ff7518;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #ff7518;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #ff7518;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-danger{--bs-btn-color: #ff0039;--bs-btn-border-color: #ff0039;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #ff0039;--bs-btn-hover-border-color: #ff0039;--bs-btn-focus-shadow-rgb: 255, 0, 57;--bs-btn-active-color: #fff;--bs-btn-active-bg: #ff0039;--bs-btn-active-border-color: #ff0039;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #ff0039;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #ff0039;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-light{--bs-btn-color: #f8f9fa;--bs-btn-border-color: #f8f9fa;--bs-btn-hover-color: #000;--bs-btn-hover-bg: #f8f9fa;--bs-btn-hover-border-color: #f8f9fa;--bs-btn-focus-shadow-rgb: 248, 249, 250;--bs-btn-active-color: #000;--bs-btn-active-bg: #f8f9fa;--bs-btn-active-border-color: #f8f9fa;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #f8f9fa;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #f8f9fa;--bs-btn-bg: transparent;--bs-gradient: none}.btn-outline-dark{--bs-btn-color: #343a40;--bs-btn-border-color: #343a40;--bs-btn-hover-color: #fff;--bs-btn-hover-bg: #343a40;--bs-btn-hover-border-color: #343a40;--bs-btn-focus-shadow-rgb: 52, 58, 64;--bs-btn-active-color: #fff;--bs-btn-active-bg: #343a40;--bs-btn-active-border-color: #343a40;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #343a40;--bs-btn-disabled-bg: transparent;--bs-btn-disabled-border-color: #343a40;--bs-btn-bg: transparent;--bs-gradient: none}.btn-link{--bs-btn-font-weight: 400;--bs-btn-color: #2761e3;--bs-btn-bg: transparent;--bs-btn-border-color: transparent;--bs-btn-hover-color: #1f4eb6;--bs-btn-hover-border-color: transparent;--bs-btn-active-color: #1f4eb6;--bs-btn-active-border-color: transparent;--bs-btn-disabled-color: #6c757d;--bs-btn-disabled-border-color: transparent;--bs-btn-box-shadow: 0 0 0 #000;--bs-btn-focus-shadow-rgb: 71, 121, 231;text-decoration:underline;-webkit-text-decoration:underline;-moz-text-decoration:underline;-ms-text-decoration:underline;-o-text-decoration:underline}.btn-link:focus-visible{color:var(--bs-btn-color)}.btn-link:hover{color:var(--bs-btn-hover-color)}.btn-lg,.btn-group-lg>.btn{--bs-btn-padding-y: 0.5rem;--bs-btn-padding-x: 1rem;--bs-btn-font-size:1.25rem;--bs-btn-border-radius: 0.5rem}.btn-sm,.btn-group-sm>.btn{--bs-btn-padding-y: 0.25rem;--bs-btn-padding-x: 0.5rem;--bs-btn-font-size:0.875rem;--bs-btn-border-radius: 0.2em}.fade{transition:opacity .15s linear}@media(prefers-reduced-motion: reduce){.fade{transition:none}}.fade:not(.show){opacity:0}.collapse:not(.show){display:none}.collapsing{height:0;overflow:hidden;transition:height .2s ease}@media(prefers-reduced-motion: reduce){.collapsing{transition:none}}.collapsing.collapse-horizontal{width:0;height:auto;transition:width .35s ease}@media(prefers-reduced-motion: reduce){.collapsing.collapse-horizontal{transition:none}}.dropup,.dropend,.dropdown,.dropstart,.dropup-center,.dropdown-center{position:relative}.dropdown-toggle{white-space:nowrap}.dropdown-toggle::after{display:inline-block;margin-left:.255em;vertical-align:.255em;content:"";border-top:.3em solid;border-right:.3em solid rgba(0,0,0,0);border-bottom:0;border-left:.3em solid rgba(0,0,0,0)}.dropdown-toggle:empty::after{margin-left:0}.dropdown-menu{--bs-dropdown-zindex: 1000;--bs-dropdown-min-width: 10rem;--bs-dropdown-padding-x: 0;--bs-dropdown-padding-y: 0.5rem;--bs-dropdown-spacer: 0.125rem;--bs-dropdown-font-size:1rem;--bs-dropdown-color: #343a40;--bs-dropdown-bg: #fff;--bs-dropdown-border-color: rgba(0, 0, 0, 0.175);--bs-dropdown-border-radius: 0.25rem;--bs-dropdown-border-width: 1px;--bs-dropdown-inner-border-radius: calc(0.25rem - 1px);--bs-dropdown-divider-bg: rgba(0, 0, 0, 0.175);--bs-dropdown-divider-margin-y: 0.5rem;--bs-dropdown-box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);--bs-dropdown-link-color: #343a40;--bs-dropdown-link-hover-color: #343a40;--bs-dropdown-link-hover-bg: #f8f9fa;--bs-dropdown-link-active-color: #fff;--bs-dropdown-link-active-bg: #2780e3;--bs-dropdown-link-disabled-color: rgba(52, 58, 64, 0.5);--bs-dropdown-item-padding-x: 1rem;--bs-dropdown-item-padding-y: 0.25rem;--bs-dropdown-header-color: #6c757d;--bs-dropdown-header-padding-x: 1rem;--bs-dropdown-header-padding-y: 0.5rem;position:absolute;z-index:var(--bs-dropdown-zindex);display:none;min-width:var(--bs-dropdown-min-width);padding:var(--bs-dropdown-padding-y) var(--bs-dropdown-padding-x);margin:0;font-size:var(--bs-dropdown-font-size);color:var(--bs-dropdown-color);text-align:left;list-style:none;background-color:var(--bs-dropdown-bg);background-clip:padding-box;border:var(--bs-dropdown-border-width) solid var(--bs-dropdown-border-color)}.dropdown-menu[data-bs-popper]{top:100%;left:0;margin-top:var(--bs-dropdown-spacer)}.dropdown-menu-start{--bs-position: start}.dropdown-menu-start[data-bs-popper]{right:auto;left:0}.dropdown-menu-end{--bs-position: end}.dropdown-menu-end[data-bs-popper]{right:0;left:auto}@media(min-width: 576px){.dropdown-menu-sm-start{--bs-position: start}.dropdown-menu-sm-start[data-bs-popper]{right:auto;left:0}.dropdown-menu-sm-end{--bs-position: end}.dropdown-menu-sm-end[data-bs-popper]{right:0;left:auto}}@media(min-width: 768px){.dropdown-menu-md-start{--bs-position: start}.dropdown-menu-md-start[data-bs-popper]{right:auto;left:0}.dropdown-menu-md-end{--bs-position: end}.dropdown-menu-md-end[data-bs-popper]{right:0;left:auto}}@media(min-width: 992px){.dropdown-menu-lg-start{--bs-position: start}.dropdown-menu-lg-start[data-bs-popper]{right:auto;left:0}.dropdown-menu-lg-end{--bs-position: end}.dropdown-menu-lg-end[data-bs-popper]{right:0;left:auto}}@media(min-width: 1200px){.dropdown-menu-xl-start{--bs-position: start}.dropdown-menu-xl-start[data-bs-popper]{right:auto;left:0}.dropdown-menu-xl-end{--bs-position: end}.dropdown-menu-xl-end[data-bs-popper]{right:0;left:auto}}@media(min-width: 1400px){.dropdown-menu-xxl-start{--bs-position: start}.dropdown-menu-xxl-start[data-bs-popper]{right:auto;left:0}.dropdown-menu-xxl-end{--bs-position: end}.dropdown-menu-xxl-end[data-bs-popper]{right:0;left:auto}}.dropup .dropdown-menu[data-bs-popper]{top:auto;bottom:100%;margin-top:0;margin-bottom:var(--bs-dropdown-spacer)}.dropup .dropdown-toggle::after{display:inline-block;margin-left:.255em;vertical-align:.255em;content:"";border-top:0;border-right:.3em solid rgba(0,0,0,0);border-bottom:.3em solid;border-left:.3em solid rgba(0,0,0,0)}.dropup .dropdown-toggle:empty::after{margin-left:0}.dropend .dropdown-menu[data-bs-popper]{top:0;right:auto;left:100%;margin-top:0;margin-left:var(--bs-dropdown-spacer)}.dropend .dropdown-toggle::after{display:inline-block;margin-left:.255em;vertical-align:.255em;content:"";border-top:.3em solid rgba(0,0,0,0);border-right:0;border-bottom:.3em solid rgba(0,0,0,0);border-left:.3em solid}.dropend .dropdown-toggle:empty::after{margin-left:0}.dropend .dropdown-toggle::after{vertical-align:0}.dropstart .dropdown-menu[data-bs-popper]{top:0;right:100%;left:auto;margin-top:0;margin-right:var(--bs-dropdown-spacer)}.dropstart .dropdown-toggle::after{display:inline-block;margin-left:.255em;vertical-align:.255em;content:""}.dropstart .dropdown-toggle::after{display:none}.dropstart .dropdown-toggle::before{display:inline-block;margin-right:.255em;vertical-align:.255em;content:"";border-top:.3em solid rgba(0,0,0,0);border-right:.3em solid;border-bottom:.3em solid rgba(0,0,0,0)}.dropstart .dropdown-toggle:empty::after{margin-left:0}.dropstart .dropdown-toggle::before{vertical-align:0}.dropdown-divider{height:0;margin:var(--bs-dropdown-divider-margin-y) 0;overflow:hidden;border-top:1px solid var(--bs-dropdown-divider-bg);opacity:1}.dropdown-item{display:block;width:100%;padding:var(--bs-dropdown-item-padding-y) var(--bs-dropdown-item-padding-x);clear:both;font-weight:400;color:var(--bs-dropdown-link-color);text-align:inherit;text-decoration:none;-webkit-text-decoration:none;-moz-text-decoration:none;-ms-text-decoration:none;-o-text-decoration:none;white-space:nowrap;background-color:rgba(0,0,0,0);border:0}.dropdown-item:hover,.dropdown-item:focus{color:var(--bs-dropdown-link-hover-color);background-color:var(--bs-dropdown-link-hover-bg)}.dropdown-item.active,.dropdown-item:active{color:var(--bs-dropdown-link-active-color);text-decoration:none;background-color:var(--bs-dropdown-link-active-bg)}.dropdown-item.disabled,.dropdown-item:disabled{color:var(--bs-dropdown-link-disabled-color);pointer-events:none;background-color:rgba(0,0,0,0)}.dropdown-menu.show{display:block}.dropdown-header{display:block;padding:var(--bs-dropdown-header-padding-y) var(--bs-dropdown-header-padding-x);margin-bottom:0;font-size:0.875rem;color:var(--bs-dropdown-header-color);white-space:nowrap}.dropdown-item-text{display:block;padding:var(--bs-dropdown-item-padding-y) var(--bs-dropdown-item-padding-x);color:var(--bs-dropdown-link-color)}.dropdown-menu-dark{--bs-dropdown-color: #dee2e6;--bs-dropdown-bg: #343a40;--bs-dropdown-border-color: rgba(0, 0, 0, 0.175);--bs-dropdown-box-shadow: ;--bs-dropdown-link-color: #dee2e6;--bs-dropdown-link-hover-color: #fff;--bs-dropdown-divider-bg: rgba(0, 0, 0, 0.175);--bs-dropdown-link-hover-bg: rgba(255, 255, 255, 0.15);--bs-dropdown-link-active-color: #fff;--bs-dropdown-link-active-bg: #2780e3;--bs-dropdown-link-disabled-color: #adb5bd;--bs-dropdown-header-color: #adb5bd}.btn-group,.btn-group-vertical{position:relative;display:inline-flex;vertical-align:middle}.btn-group>.btn,.btn-group-vertical>.btn{position:relative;flex:1 1 auto;-webkit-flex:1 1 auto}.btn-group>.btn-check:checked+.btn,.btn-group>.btn-check:focus+.btn,.btn-group>.btn:hover,.btn-group>.btn:focus,.btn-group>.btn:active,.btn-group>.btn.active,.btn-group-vertical>.btn-check:checked+.btn,.btn-group-vertical>.btn-check:focus+.btn,.btn-group-vertical>.btn:hover,.btn-group-vertical>.btn:focus,.btn-group-vertical>.btn:active,.btn-group-vertical>.btn.active{z-index:1}.btn-toolbar{display:flex;display:-webkit-flex;flex-wrap:wrap;-webkit-flex-wrap:wrap;justify-content:flex-start;-webkit-justify-content:flex-start}.btn-toolbar .input-group{width:auto}.btn-group>:not(.btn-check:first-child)+.btn,.btn-group>.btn-group:not(:first-child){margin-left:calc(1px*-1)}.dropdown-toggle-split{padding-right:.5625rem;padding-left:.5625rem}.dropdown-toggle-split::after,.dropup .dropdown-toggle-split::after,.dropend .dropdown-toggle-split::after{margin-left:0}.dropstart .dropdown-toggle-split::before{margin-right:0}.btn-sm+.dropdown-toggle-split,.btn-group-sm>.btn+.dropdown-toggle-split{padding-right:.375rem;padding-left:.375rem}.btn-lg+.dropdown-toggle-split,.btn-group-lg>.btn+.dropdown-toggle-split{padding-right:.75rem;padding-left:.75rem}.btn-group-vertical{flex-direction:column;-webkit-flex-direction:column;align-items:flex-start;-webkit-align-items:flex-start;justify-content:center;-webkit-justify-content:center}.btn-group-vertical>.btn,.btn-group-vertical>.btn-group{width:100%}.btn-group-vertical>.btn:not(:first-child),.btn-group-vertical>.btn-group:not(:first-child){margin-top:calc(1px*-1)}.nav{--bs-nav-link-padding-x: 1rem;--bs-nav-link-padding-y: 0.5rem;--bs-nav-link-font-weight: ;--bs-nav-link-color: #2761e3;--bs-nav-link-hover-color: #1f4eb6;--bs-nav-link-disabled-color: rgba(52, 58, 64, 0.75);display:flex;display:-webkit-flex;flex-wrap:wrap;-webkit-flex-wrap:wrap;padding-left:0;margin-bottom:0;list-style:none}.nav-link{display:block;padding:var(--bs-nav-link-padding-y) var(--bs-nav-link-padding-x);font-size:var(--bs-nav-link-font-size);font-weight:var(--bs-nav-link-font-weight);color:var(--bs-nav-link-color);text-decoration:none;-webkit-text-decoration:none;-moz-text-decoration:none;-ms-text-decoration:none;-o-text-decoration:none;background:none;border:0;transition:color .15s ease-in-out,background-color .15s ease-in-out,border-color .15s ease-in-out}@media(prefers-reduced-motion: reduce){.nav-link{transition:none}}.nav-link:hover,.nav-link:focus{color:var(--bs-nav-link-hover-color)}.nav-link:focus-visible{outline:0;box-shadow:0 0 0 .25rem rgba(39,128,227,.25)}.nav-link.disabled,.nav-link:disabled{color:var(--bs-nav-link-disabled-color);pointer-events:none;cursor:default}.nav-tabs{--bs-nav-tabs-border-width: 1px;--bs-nav-tabs-border-color: #dee2e6;--bs-nav-tabs-border-radius: 0.25rem;--bs-nav-tabs-link-hover-border-color: #e9ecef #e9ecef #dee2e6;--bs-nav-tabs-link-active-color: #000;--bs-nav-tabs-link-active-bg: #fff;--bs-nav-tabs-link-active-border-color: #dee2e6 #dee2e6 #fff;border-bottom:var(--bs-nav-tabs-border-width) solid var(--bs-nav-tabs-border-color)}.nav-tabs .nav-link{margin-bottom:calc(-1*var(--bs-nav-tabs-border-width));border:var(--bs-nav-tabs-border-width) solid rgba(0,0,0,0)}.nav-tabs .nav-link:hover,.nav-tabs .nav-link:focus{isolation:isolate;border-color:var(--bs-nav-tabs-link-hover-border-color)}.nav-tabs .nav-link.active,.nav-tabs .nav-item.show .nav-link{color:var(--bs-nav-tabs-link-active-color);background-color:var(--bs-nav-tabs-link-active-bg);border-color:var(--bs-nav-tabs-link-active-border-color)}.nav-tabs .dropdown-menu{margin-top:calc(-1*var(--bs-nav-tabs-border-width))}.nav-pills{--bs-nav-pills-border-radius: 0.25rem;--bs-nav-pills-link-active-color: #fff;--bs-nav-pills-link-active-bg: #2780e3}.nav-pills .nav-link.active,.nav-pills .show>.nav-link{color:var(--bs-nav-pills-link-active-color);background-color:var(--bs-nav-pills-link-active-bg)}.nav-underline{--bs-nav-underline-gap: 1rem;--bs-nav-underline-border-width: 0.125rem;--bs-nav-underline-link-active-color: #000;gap:var(--bs-nav-underline-gap)}.nav-underline .nav-link{padding-right:0;padding-left:0;border-bottom:var(--bs-nav-underline-border-width) solid rgba(0,0,0,0)}.nav-underline .nav-link:hover,.nav-underline .nav-link:focus{border-bottom-color:currentcolor}.nav-underline .nav-link.active,.nav-underline .show>.nav-link{font-weight:700;color:var(--bs-nav-underline-link-active-color);border-bottom-color:currentcolor}.nav-fill>.nav-link,.nav-fill .nav-item{flex:1 1 auto;-webkit-flex:1 1 auto;text-align:center}.nav-justified>.nav-link,.nav-justified .nav-item{flex-basis:0;-webkit-flex-basis:0;flex-grow:1;-webkit-flex-grow:1;text-align:center}.nav-fill .nav-item .nav-link,.nav-justified .nav-item .nav-link{width:100%}.tab-content>.tab-pane{display:none}.tab-content>.active{display:block}.navbar{--bs-navbar-padding-x: 0;--bs-navbar-padding-y: 0.5rem;--bs-navbar-color: #545555;--bs-navbar-hover-color: rgba(31, 78, 182, 0.8);--bs-navbar-disabled-color: rgba(84, 85, 85, 0.75);--bs-navbar-active-color: #1f4eb6;--bs-navbar-brand-padding-y: 0.3125rem;--bs-navbar-brand-margin-end: 1rem;--bs-navbar-brand-font-size: 1.25rem;--bs-navbar-brand-color: #545555;--bs-navbar-brand-hover-color: #1f4eb6;--bs-navbar-nav-link-padding-x: 0.5rem;--bs-navbar-toggler-padding-y: 0.25;--bs-navbar-toggler-padding-x: 0;--bs-navbar-toggler-font-size: 1.25rem;--bs-navbar-toggler-icon-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 30 30'%3e%3cpath stroke='%23545555' stroke-linecap='round' stroke-miterlimit='10' stroke-width='2' d='M4 7h22M4 15h22M4 23h22'/%3e%3c/svg%3e");--bs-navbar-toggler-border-color: rgba(84, 85, 85, 0);--bs-navbar-toggler-border-radius: 0.25rem;--bs-navbar-toggler-focus-width: 0.25rem;--bs-navbar-toggler-transition: box-shadow 0.15s ease-in-out;position:relative;display:flex;display:-webkit-flex;flex-wrap:wrap;-webkit-flex-wrap:wrap;align-items:center;-webkit-align-items:center;justify-content:space-between;-webkit-justify-content:space-between;padding:var(--bs-navbar-padding-y) var(--bs-navbar-padding-x)}.navbar>.container,.navbar>.container-fluid,.navbar>.container-sm,.navbar>.container-md,.navbar>.container-lg,.navbar>.container-xl,.navbar>.container-xxl{display:flex;display:-webkit-flex;flex-wrap:inherit;-webkit-flex-wrap:inherit;align-items:center;-webkit-align-items:center;justify-content:space-between;-webkit-justify-content:space-between}.navbar-brand{padding-top:var(--bs-navbar-brand-padding-y);padding-bottom:var(--bs-navbar-brand-padding-y);margin-right:var(--bs-navbar-brand-margin-end);font-size:var(--bs-navbar-brand-font-size);color:var(--bs-navbar-brand-color);text-decoration:none;-webkit-text-decoration:none;-moz-text-decoration:none;-ms-text-decoration:none;-o-text-decoration:none;white-space:nowrap}.navbar-brand:hover,.navbar-brand:focus{color:var(--bs-navbar-brand-hover-color)}.navbar-nav{--bs-nav-link-padding-x: 0;--bs-nav-link-padding-y: 0.5rem;--bs-nav-link-font-weight: ;--bs-nav-link-color: var(--bs-navbar-color);--bs-nav-link-hover-color: var(--bs-navbar-hover-color);--bs-nav-link-disabled-color: var(--bs-navbar-disabled-color);display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;padding-left:0;margin-bottom:0;list-style:none}.navbar-nav .nav-link.active,.navbar-nav .nav-link.show{color:var(--bs-navbar-active-color)}.navbar-nav .dropdown-menu{position:static}.navbar-text{padding-top:.5rem;padding-bottom:.5rem;color:var(--bs-navbar-color)}.navbar-text a,.navbar-text a:hover,.navbar-text a:focus{color:var(--bs-navbar-active-color)}.navbar-collapse{flex-basis:100%;-webkit-flex-basis:100%;flex-grow:1;-webkit-flex-grow:1;align-items:center;-webkit-align-items:center}.navbar-toggler{padding:var(--bs-navbar-toggler-padding-y) var(--bs-navbar-toggler-padding-x);font-size:var(--bs-navbar-toggler-font-size);line-height:1;color:var(--bs-navbar-color);background-color:rgba(0,0,0,0);border:var(--bs-border-width) solid var(--bs-navbar-toggler-border-color);transition:var(--bs-navbar-toggler-transition)}@media(prefers-reduced-motion: reduce){.navbar-toggler{transition:none}}.navbar-toggler:hover{text-decoration:none}.navbar-toggler:focus{text-decoration:none;outline:0;box-shadow:0 0 0 var(--bs-navbar-toggler-focus-width)}.navbar-toggler-icon{display:inline-block;width:1.5em;height:1.5em;vertical-align:middle;background-image:var(--bs-navbar-toggler-icon-bg);background-repeat:no-repeat;background-position:center;background-size:100%}.navbar-nav-scroll{max-height:var(--bs-scroll-height, 75vh);overflow-y:auto}@media(min-width: 576px){.navbar-expand-sm{flex-wrap:nowrap;-webkit-flex-wrap:nowrap;justify-content:flex-start;-webkit-justify-content:flex-start}.navbar-expand-sm .navbar-nav{flex-direction:row;-webkit-flex-direction:row}.navbar-expand-sm .navbar-nav .dropdown-menu{position:absolute}.navbar-expand-sm .navbar-nav .nav-link{padding-right:var(--bs-navbar-nav-link-padding-x);padding-left:var(--bs-navbar-nav-link-padding-x)}.navbar-expand-sm .navbar-nav-scroll{overflow:visible}.navbar-expand-sm .navbar-collapse{display:flex !important;display:-webkit-flex !important;flex-basis:auto;-webkit-flex-basis:auto}.navbar-expand-sm .navbar-toggler{display:none}.navbar-expand-sm .offcanvas{position:static;z-index:auto;flex-grow:1;-webkit-flex-grow:1;width:auto !important;height:auto !important;visibility:visible !important;background-color:rgba(0,0,0,0) !important;border:0 !important;transform:none !important;transition:none}.navbar-expand-sm .offcanvas .offcanvas-header{display:none}.navbar-expand-sm .offcanvas .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible}}@media(min-width: 768px){.navbar-expand-md{flex-wrap:nowrap;-webkit-flex-wrap:nowrap;justify-content:flex-start;-webkit-justify-content:flex-start}.navbar-expand-md .navbar-nav{flex-direction:row;-webkit-flex-direction:row}.navbar-expand-md .navbar-nav .dropdown-menu{position:absolute}.navbar-expand-md .navbar-nav .nav-link{padding-right:var(--bs-navbar-nav-link-padding-x);padding-left:var(--bs-navbar-nav-link-padding-x)}.navbar-expand-md .navbar-nav-scroll{overflow:visible}.navbar-expand-md .navbar-collapse{display:flex !important;display:-webkit-flex !important;flex-basis:auto;-webkit-flex-basis:auto}.navbar-expand-md .navbar-toggler{display:none}.navbar-expand-md .offcanvas{position:static;z-index:auto;flex-grow:1;-webkit-flex-grow:1;width:auto !important;height:auto !important;visibility:visible !important;background-color:rgba(0,0,0,0) !important;border:0 !important;transform:none !important;transition:none}.navbar-expand-md .offcanvas .offcanvas-header{display:none}.navbar-expand-md .offcanvas .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible}}@media(min-width: 992px){.navbar-expand-lg{flex-wrap:nowrap;-webkit-flex-wrap:nowrap;justify-content:flex-start;-webkit-justify-content:flex-start}.navbar-expand-lg .navbar-nav{flex-direction:row;-webkit-flex-direction:row}.navbar-expand-lg .navbar-nav .dropdown-menu{position:absolute}.navbar-expand-lg .navbar-nav .nav-link{padding-right:var(--bs-navbar-nav-link-padding-x);padding-left:var(--bs-navbar-nav-link-padding-x)}.navbar-expand-lg .navbar-nav-scroll{overflow:visible}.navbar-expand-lg .navbar-collapse{display:flex !important;display:-webkit-flex !important;flex-basis:auto;-webkit-flex-basis:auto}.navbar-expand-lg .navbar-toggler{display:none}.navbar-expand-lg .offcanvas{position:static;z-index:auto;flex-grow:1;-webkit-flex-grow:1;width:auto !important;height:auto !important;visibility:visible !important;background-color:rgba(0,0,0,0) !important;border:0 !important;transform:none !important;transition:none}.navbar-expand-lg .offcanvas .offcanvas-header{display:none}.navbar-expand-lg .offcanvas .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible}}@media(min-width: 1200px){.navbar-expand-xl{flex-wrap:nowrap;-webkit-flex-wrap:nowrap;justify-content:flex-start;-webkit-justify-content:flex-start}.navbar-expand-xl .navbar-nav{flex-direction:row;-webkit-flex-direction:row}.navbar-expand-xl .navbar-nav .dropdown-menu{position:absolute}.navbar-expand-xl .navbar-nav .nav-link{padding-right:var(--bs-navbar-nav-link-padding-x);padding-left:var(--bs-navbar-nav-link-padding-x)}.navbar-expand-xl .navbar-nav-scroll{overflow:visible}.navbar-expand-xl .navbar-collapse{display:flex !important;display:-webkit-flex !important;flex-basis:auto;-webkit-flex-basis:auto}.navbar-expand-xl .navbar-toggler{display:none}.navbar-expand-xl .offcanvas{position:static;z-index:auto;flex-grow:1;-webkit-flex-grow:1;width:auto !important;height:auto !important;visibility:visible !important;background-color:rgba(0,0,0,0) !important;border:0 !important;transform:none !important;transition:none}.navbar-expand-xl .offcanvas .offcanvas-header{display:none}.navbar-expand-xl .offcanvas .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible}}@media(min-width: 1400px){.navbar-expand-xxl{flex-wrap:nowrap;-webkit-flex-wrap:nowrap;justify-content:flex-start;-webkit-justify-content:flex-start}.navbar-expand-xxl .navbar-nav{flex-direction:row;-webkit-flex-direction:row}.navbar-expand-xxl .navbar-nav .dropdown-menu{position:absolute}.navbar-expand-xxl .navbar-nav .nav-link{padding-right:var(--bs-navbar-nav-link-padding-x);padding-left:var(--bs-navbar-nav-link-padding-x)}.navbar-expand-xxl .navbar-nav-scroll{overflow:visible}.navbar-expand-xxl .navbar-collapse{display:flex !important;display:-webkit-flex !important;flex-basis:auto;-webkit-flex-basis:auto}.navbar-expand-xxl .navbar-toggler{display:none}.navbar-expand-xxl .offcanvas{position:static;z-index:auto;flex-grow:1;-webkit-flex-grow:1;width:auto !important;height:auto !important;visibility:visible !important;background-color:rgba(0,0,0,0) !important;border:0 !important;transform:none !important;transition:none}.navbar-expand-xxl .offcanvas .offcanvas-header{display:none}.navbar-expand-xxl .offcanvas .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible}}.navbar-expand{flex-wrap:nowrap;-webkit-flex-wrap:nowrap;justify-content:flex-start;-webkit-justify-content:flex-start}.navbar-expand .navbar-nav{flex-direction:row;-webkit-flex-direction:row}.navbar-expand .navbar-nav .dropdown-menu{position:absolute}.navbar-expand .navbar-nav .nav-link{padding-right:var(--bs-navbar-nav-link-padding-x);padding-left:var(--bs-navbar-nav-link-padding-x)}.navbar-expand .navbar-nav-scroll{overflow:visible}.navbar-expand .navbar-collapse{display:flex !important;display:-webkit-flex !important;flex-basis:auto;-webkit-flex-basis:auto}.navbar-expand .navbar-toggler{display:none}.navbar-expand .offcanvas{position:static;z-index:auto;flex-grow:1;-webkit-flex-grow:1;width:auto !important;height:auto !important;visibility:visible !important;background-color:rgba(0,0,0,0) !important;border:0 !important;transform:none !important;transition:none}.navbar-expand .offcanvas .offcanvas-header{display:none}.navbar-expand .offcanvas .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible}.navbar-dark,.navbar[data-bs-theme=dark]{--bs-navbar-color: #545555;--bs-navbar-hover-color: rgba(31, 78, 182, 0.8);--bs-navbar-disabled-color: rgba(84, 85, 85, 0.75);--bs-navbar-active-color: #1f4eb6;--bs-navbar-brand-color: #545555;--bs-navbar-brand-hover-color: #1f4eb6;--bs-navbar-toggler-border-color: rgba(84, 85, 85, 0);--bs-navbar-toggler-icon-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 30 30'%3e%3cpath stroke='%23545555' stroke-linecap='round' stroke-miterlimit='10' stroke-width='2' d='M4 7h22M4 15h22M4 23h22'/%3e%3c/svg%3e")}[data-bs-theme=dark] .navbar-toggler-icon{--bs-navbar-toggler-icon-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 30 30'%3e%3cpath stroke='%23545555' stroke-linecap='round' stroke-miterlimit='10' stroke-width='2' d='M4 7h22M4 15h22M4 23h22'/%3e%3c/svg%3e")}.card{--bs-card-spacer-y: 1rem;--bs-card-spacer-x: 1rem;--bs-card-title-spacer-y: 0.5rem;--bs-card-title-color: ;--bs-card-subtitle-color: ;--bs-card-border-width: 1px;--bs-card-border-color: rgba(0, 0, 0, 0.175);--bs-card-border-radius: 0.25rem;--bs-card-box-shadow: ;--bs-card-inner-border-radius: calc(0.25rem - 1px);--bs-card-cap-padding-y: 0.5rem;--bs-card-cap-padding-x: 1rem;--bs-card-cap-bg: rgba(52, 58, 64, 0.25);--bs-card-cap-color: ;--bs-card-height: ;--bs-card-color: ;--bs-card-bg: #fff;--bs-card-img-overlay-padding: 1rem;--bs-card-group-margin: 0.75rem;position:relative;display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;min-width:0;height:var(--bs-card-height);color:var(--bs-body-color);word-wrap:break-word;background-color:var(--bs-card-bg);background-clip:border-box;border:var(--bs-card-border-width) solid var(--bs-card-border-color)}.card>hr{margin-right:0;margin-left:0}.card>.list-group{border-top:inherit;border-bottom:inherit}.card>.list-group:first-child{border-top-width:0}.card>.list-group:last-child{border-bottom-width:0}.card>.card-header+.list-group,.card>.list-group+.card-footer{border-top:0}.card-body{flex:1 1 auto;-webkit-flex:1 1 auto;padding:var(--bs-card-spacer-y) var(--bs-card-spacer-x);color:var(--bs-card-color)}.card-title{margin-bottom:var(--bs-card-title-spacer-y);color:var(--bs-card-title-color)}.card-subtitle{margin-top:calc(-0.5*var(--bs-card-title-spacer-y));margin-bottom:0;color:var(--bs-card-subtitle-color)}.card-text:last-child{margin-bottom:0}.card-link+.card-link{margin-left:var(--bs-card-spacer-x)}.card-header{padding:var(--bs-card-cap-padding-y) var(--bs-card-cap-padding-x);margin-bottom:0;color:var(--bs-card-cap-color);background-color:var(--bs-card-cap-bg);border-bottom:var(--bs-card-border-width) solid var(--bs-card-border-color)}.card-footer{padding:var(--bs-card-cap-padding-y) var(--bs-card-cap-padding-x);color:var(--bs-card-cap-color);background-color:var(--bs-card-cap-bg);border-top:var(--bs-card-border-width) solid var(--bs-card-border-color)}.card-header-tabs{margin-right:calc(-0.5*var(--bs-card-cap-padding-x));margin-bottom:calc(-1*var(--bs-card-cap-padding-y));margin-left:calc(-0.5*var(--bs-card-cap-padding-x));border-bottom:0}.card-header-tabs .nav-link.active{background-color:var(--bs-card-bg);border-bottom-color:var(--bs-card-bg)}.card-header-pills{margin-right:calc(-0.5*var(--bs-card-cap-padding-x));margin-left:calc(-0.5*var(--bs-card-cap-padding-x))}.card-img-overlay{position:absolute;top:0;right:0;bottom:0;left:0;padding:var(--bs-card-img-overlay-padding)}.card-img,.card-img-top,.card-img-bottom{width:100%}.card-group>.card{margin-bottom:var(--bs-card-group-margin)}@media(min-width: 576px){.card-group{display:flex;display:-webkit-flex;flex-flow:row wrap;-webkit-flex-flow:row wrap}.card-group>.card{flex:1 0 0%;-webkit-flex:1 0 0%;margin-bottom:0}.card-group>.card+.card{margin-left:0;border-left:0}}.accordion{--bs-accordion-color: #343a40;--bs-accordion-bg: #fff;--bs-accordion-transition: color 0.15s ease-in-out, background-color 0.15s ease-in-out, border-color 0.15s ease-in-out, box-shadow 0.15s ease-in-out, border-radius 0.15s ease;--bs-accordion-border-color: #dee2e6;--bs-accordion-border-width: 1px;--bs-accordion-border-radius: 0.25rem;--bs-accordion-inner-border-radius: calc(0.25rem - 1px);--bs-accordion-btn-padding-x: 1.25rem;--bs-accordion-btn-padding-y: 1rem;--bs-accordion-btn-color: #343a40;--bs-accordion-btn-bg: #fff;--bs-accordion-btn-icon: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='%23343a40'%3e%3cpath fill-rule='evenodd' d='M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z'/%3e%3c/svg%3e");--bs-accordion-btn-icon-width: 1.25rem;--bs-accordion-btn-icon-transform: rotate(-180deg);--bs-accordion-btn-icon-transition: transform 0.2s ease-in-out;--bs-accordion-btn-active-icon: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='%2310335b'%3e%3cpath fill-rule='evenodd' d='M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z'/%3e%3c/svg%3e");--bs-accordion-btn-focus-border-color: #93c0f1;--bs-accordion-btn-focus-box-shadow: 0 0 0 0.25rem rgba(39, 128, 227, 0.25);--bs-accordion-body-padding-x: 1.25rem;--bs-accordion-body-padding-y: 1rem;--bs-accordion-active-color: #10335b;--bs-accordion-active-bg: #d4e6f9}.accordion-button{position:relative;display:flex;display:-webkit-flex;align-items:center;-webkit-align-items:center;width:100%;padding:var(--bs-accordion-btn-padding-y) var(--bs-accordion-btn-padding-x);font-size:1rem;color:var(--bs-accordion-btn-color);text-align:left;background-color:var(--bs-accordion-btn-bg);border:0;overflow-anchor:none;transition:var(--bs-accordion-transition)}@media(prefers-reduced-motion: reduce){.accordion-button{transition:none}}.accordion-button:not(.collapsed){color:var(--bs-accordion-active-color);background-color:var(--bs-accordion-active-bg);box-shadow:inset 0 calc(-1*var(--bs-accordion-border-width)) 0 var(--bs-accordion-border-color)}.accordion-button:not(.collapsed)::after{background-image:var(--bs-accordion-btn-active-icon);transform:var(--bs-accordion-btn-icon-transform)}.accordion-button::after{flex-shrink:0;-webkit-flex-shrink:0;width:var(--bs-accordion-btn-icon-width);height:var(--bs-accordion-btn-icon-width);margin-left:auto;content:"";background-image:var(--bs-accordion-btn-icon);background-repeat:no-repeat;background-size:var(--bs-accordion-btn-icon-width);transition:var(--bs-accordion-btn-icon-transition)}@media(prefers-reduced-motion: reduce){.accordion-button::after{transition:none}}.accordion-button:hover{z-index:2}.accordion-button:focus{z-index:3;border-color:var(--bs-accordion-btn-focus-border-color);outline:0;box-shadow:var(--bs-accordion-btn-focus-box-shadow)}.accordion-header{margin-bottom:0}.accordion-item{color:var(--bs-accordion-color);background-color:var(--bs-accordion-bg);border:var(--bs-accordion-border-width) solid var(--bs-accordion-border-color)}.accordion-item:not(:first-of-type){border-top:0}.accordion-body{padding:var(--bs-accordion-body-padding-y) var(--bs-accordion-body-padding-x)}.accordion-flush .accordion-collapse{border-width:0}.accordion-flush .accordion-item{border-right:0;border-left:0}.accordion-flush .accordion-item:first-child{border-top:0}.accordion-flush .accordion-item:last-child{border-bottom:0}[data-bs-theme=dark] .accordion-button::after{--bs-accordion-btn-icon: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='%237db3ee'%3e%3cpath fill-rule='evenodd' d='M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z'/%3e%3c/svg%3e");--bs-accordion-btn-active-icon: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='%237db3ee'%3e%3cpath fill-rule='evenodd' d='M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z'/%3e%3c/svg%3e")}.breadcrumb{--bs-breadcrumb-padding-x: 0;--bs-breadcrumb-padding-y: 0;--bs-breadcrumb-margin-bottom: 1rem;--bs-breadcrumb-bg: ;--bs-breadcrumb-border-radius: ;--bs-breadcrumb-divider-color: rgba(52, 58, 64, 0.75);--bs-breadcrumb-item-padding-x: 0.5rem;--bs-breadcrumb-item-active-color: rgba(52, 58, 64, 0.75);display:flex;display:-webkit-flex;flex-wrap:wrap;-webkit-flex-wrap:wrap;padding:var(--bs-breadcrumb-padding-y) var(--bs-breadcrumb-padding-x);margin-bottom:var(--bs-breadcrumb-margin-bottom);font-size:var(--bs-breadcrumb-font-size);list-style:none;background-color:var(--bs-breadcrumb-bg)}.breadcrumb-item+.breadcrumb-item{padding-left:var(--bs-breadcrumb-item-padding-x)}.breadcrumb-item+.breadcrumb-item::before{float:left;padding-right:var(--bs-breadcrumb-item-padding-x);color:var(--bs-breadcrumb-divider-color);content:var(--bs-breadcrumb-divider, ">") /* rtl: var(--bs-breadcrumb-divider, ">") */}.breadcrumb-item.active{color:var(--bs-breadcrumb-item-active-color)}.pagination{--bs-pagination-padding-x: 0.75rem;--bs-pagination-padding-y: 0.375rem;--bs-pagination-font-size:1rem;--bs-pagination-color: #2761e3;--bs-pagination-bg: #fff;--bs-pagination-border-width: 1px;--bs-pagination-border-color: #dee2e6;--bs-pagination-border-radius: 0.25rem;--bs-pagination-hover-color: #1f4eb6;--bs-pagination-hover-bg: #f8f9fa;--bs-pagination-hover-border-color: #dee2e6;--bs-pagination-focus-color: #1f4eb6;--bs-pagination-focus-bg: #e9ecef;--bs-pagination-focus-box-shadow: 0 0 0 0.25rem rgba(39, 128, 227, 0.25);--bs-pagination-active-color: #fff;--bs-pagination-active-bg: #2780e3;--bs-pagination-active-border-color: #2780e3;--bs-pagination-disabled-color: rgba(52, 58, 64, 0.75);--bs-pagination-disabled-bg: #e9ecef;--bs-pagination-disabled-border-color: #dee2e6;display:flex;display:-webkit-flex;padding-left:0;list-style:none}.page-link{position:relative;display:block;padding:var(--bs-pagination-padding-y) var(--bs-pagination-padding-x);font-size:var(--bs-pagination-font-size);color:var(--bs-pagination-color);text-decoration:none;-webkit-text-decoration:none;-moz-text-decoration:none;-ms-text-decoration:none;-o-text-decoration:none;background-color:var(--bs-pagination-bg);border:var(--bs-pagination-border-width) solid var(--bs-pagination-border-color);transition:color .15s ease-in-out,background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out}@media(prefers-reduced-motion: reduce){.page-link{transition:none}}.page-link:hover{z-index:2;color:var(--bs-pagination-hover-color);background-color:var(--bs-pagination-hover-bg);border-color:var(--bs-pagination-hover-border-color)}.page-link:focus{z-index:3;color:var(--bs-pagination-focus-color);background-color:var(--bs-pagination-focus-bg);outline:0;box-shadow:var(--bs-pagination-focus-box-shadow)}.page-link.active,.active>.page-link{z-index:3;color:var(--bs-pagination-active-color);background-color:var(--bs-pagination-active-bg);border-color:var(--bs-pagination-active-border-color)}.page-link.disabled,.disabled>.page-link{color:var(--bs-pagination-disabled-color);pointer-events:none;background-color:var(--bs-pagination-disabled-bg);border-color:var(--bs-pagination-disabled-border-color)}.page-item:not(:first-child) .page-link{margin-left:calc(1px*-1)}.pagination-lg{--bs-pagination-padding-x: 1.5rem;--bs-pagination-padding-y: 0.75rem;--bs-pagination-font-size:1.25rem;--bs-pagination-border-radius: 0.5rem}.pagination-sm{--bs-pagination-padding-x: 0.5rem;--bs-pagination-padding-y: 0.25rem;--bs-pagination-font-size:0.875rem;--bs-pagination-border-radius: 0.2em}.badge{--bs-badge-padding-x: 0.65em;--bs-badge-padding-y: 0.35em;--bs-badge-font-size:0.75em;--bs-badge-font-weight: 700;--bs-badge-color: #fff;--bs-badge-border-radius: 0.25rem;display:inline-block;padding:var(--bs-badge-padding-y) var(--bs-badge-padding-x);font-size:var(--bs-badge-font-size);font-weight:var(--bs-badge-font-weight);line-height:1;color:var(--bs-badge-color);text-align:center;white-space:nowrap;vertical-align:baseline}.badge:empty{display:none}.btn .badge{position:relative;top:-1px}.alert{--bs-alert-bg: transparent;--bs-alert-padding-x: 1rem;--bs-alert-padding-y: 1rem;--bs-alert-margin-bottom: 1rem;--bs-alert-color: inherit;--bs-alert-border-color: transparent;--bs-alert-border: 0 solid var(--bs-alert-border-color);--bs-alert-border-radius: 0.25rem;--bs-alert-link-color: inherit;position:relative;padding:var(--bs-alert-padding-y) var(--bs-alert-padding-x);margin-bottom:var(--bs-alert-margin-bottom);color:var(--bs-alert-color);background-color:var(--bs-alert-bg);border:var(--bs-alert-border)}.alert-heading{color:inherit}.alert-link{font-weight:700;color:var(--bs-alert-link-color)}.alert-dismissible{padding-right:3rem}.alert-dismissible .btn-close{position:absolute;top:0;right:0;z-index:2;padding:1.25rem 1rem}.alert-default{--bs-alert-color: var(--bs-default-text-emphasis);--bs-alert-bg: var(--bs-default-bg-subtle);--bs-alert-border-color: var(--bs-default-border-subtle);--bs-alert-link-color: var(--bs-default-text-emphasis)}.alert-primary{--bs-alert-color: var(--bs-primary-text-emphasis);--bs-alert-bg: var(--bs-primary-bg-subtle);--bs-alert-border-color: var(--bs-primary-border-subtle);--bs-alert-link-color: var(--bs-primary-text-emphasis)}.alert-secondary{--bs-alert-color: var(--bs-secondary-text-emphasis);--bs-alert-bg: var(--bs-secondary-bg-subtle);--bs-alert-border-color: var(--bs-secondary-border-subtle);--bs-alert-link-color: var(--bs-secondary-text-emphasis)}.alert-success{--bs-alert-color: var(--bs-success-text-emphasis);--bs-alert-bg: var(--bs-success-bg-subtle);--bs-alert-border-color: var(--bs-success-border-subtle);--bs-alert-link-color: var(--bs-success-text-emphasis)}.alert-info{--bs-alert-color: var(--bs-info-text-emphasis);--bs-alert-bg: var(--bs-info-bg-subtle);--bs-alert-border-color: var(--bs-info-border-subtle);--bs-alert-link-color: var(--bs-info-text-emphasis)}.alert-warning{--bs-alert-color: var(--bs-warning-text-emphasis);--bs-alert-bg: var(--bs-warning-bg-subtle);--bs-alert-border-color: var(--bs-warning-border-subtle);--bs-alert-link-color: var(--bs-warning-text-emphasis)}.alert-danger{--bs-alert-color: var(--bs-danger-text-emphasis);--bs-alert-bg: var(--bs-danger-bg-subtle);--bs-alert-border-color: var(--bs-danger-border-subtle);--bs-alert-link-color: var(--bs-danger-text-emphasis)}.alert-light{--bs-alert-color: var(--bs-light-text-emphasis);--bs-alert-bg: var(--bs-light-bg-subtle);--bs-alert-border-color: var(--bs-light-border-subtle);--bs-alert-link-color: var(--bs-light-text-emphasis)}.alert-dark{--bs-alert-color: var(--bs-dark-text-emphasis);--bs-alert-bg: var(--bs-dark-bg-subtle);--bs-alert-border-color: var(--bs-dark-border-subtle);--bs-alert-link-color: var(--bs-dark-text-emphasis)}@keyframes progress-bar-stripes{0%{background-position-x:.5rem}}.progress,.progress-stacked{--bs-progress-height: 0.5rem;--bs-progress-font-size:0.75rem;--bs-progress-bg: #e9ecef;--bs-progress-border-radius: 0.25rem;--bs-progress-box-shadow: inset 0 1px 2px rgba(0, 0, 0, 0.075);--bs-progress-bar-color: #fff;--bs-progress-bar-bg: #2780e3;--bs-progress-bar-transition: width 0.6s ease;display:flex;display:-webkit-flex;height:var(--bs-progress-height);overflow:hidden;font-size:var(--bs-progress-font-size);background-color:var(--bs-progress-bg)}.progress-bar{display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;justify-content:center;-webkit-justify-content:center;overflow:hidden;color:var(--bs-progress-bar-color);text-align:center;white-space:nowrap;background-color:var(--bs-progress-bar-bg);transition:var(--bs-progress-bar-transition)}@media(prefers-reduced-motion: reduce){.progress-bar{transition:none}}.progress-bar-striped{background-image:linear-gradient(45deg, rgba(255, 255, 255, 0.15) 25%, transparent 25%, transparent 50%, rgba(255, 255, 255, 0.15) 50%, rgba(255, 255, 255, 0.15) 75%, transparent 75%, transparent);background-size:var(--bs-progress-height) var(--bs-progress-height)}.progress-stacked>.progress{overflow:visible}.progress-stacked>.progress>.progress-bar{width:100%}.progress-bar-animated{animation:1s linear infinite progress-bar-stripes}@media(prefers-reduced-motion: reduce){.progress-bar-animated{animation:none}}.list-group{--bs-list-group-color: #343a40;--bs-list-group-bg: #fff;--bs-list-group-border-color: #dee2e6;--bs-list-group-border-width: 1px;--bs-list-group-border-radius: 0.25rem;--bs-list-group-item-padding-x: 1rem;--bs-list-group-item-padding-y: 0.5rem;--bs-list-group-action-color: rgba(52, 58, 64, 0.75);--bs-list-group-action-hover-color: #000;--bs-list-group-action-hover-bg: #f8f9fa;--bs-list-group-action-active-color: #343a40;--bs-list-group-action-active-bg: #e9ecef;--bs-list-group-disabled-color: rgba(52, 58, 64, 0.75);--bs-list-group-disabled-bg: #fff;--bs-list-group-active-color: #fff;--bs-list-group-active-bg: #2780e3;--bs-list-group-active-border-color: #2780e3;display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;padding-left:0;margin-bottom:0}.list-group-numbered{list-style-type:none;counter-reset:section}.list-group-numbered>.list-group-item::before{content:counters(section, ".") ". ";counter-increment:section}.list-group-item-action{width:100%;color:var(--bs-list-group-action-color);text-align:inherit}.list-group-item-action:hover,.list-group-item-action:focus{z-index:1;color:var(--bs-list-group-action-hover-color);text-decoration:none;background-color:var(--bs-list-group-action-hover-bg)}.list-group-item-action:active{color:var(--bs-list-group-action-active-color);background-color:var(--bs-list-group-action-active-bg)}.list-group-item{position:relative;display:block;padding:var(--bs-list-group-item-padding-y) var(--bs-list-group-item-padding-x);color:var(--bs-list-group-color);text-decoration:none;-webkit-text-decoration:none;-moz-text-decoration:none;-ms-text-decoration:none;-o-text-decoration:none;background-color:var(--bs-list-group-bg);border:var(--bs-list-group-border-width) solid var(--bs-list-group-border-color)}.list-group-item.disabled,.list-group-item:disabled{color:var(--bs-list-group-disabled-color);pointer-events:none;background-color:var(--bs-list-group-disabled-bg)}.list-group-item.active{z-index:2;color:var(--bs-list-group-active-color);background-color:var(--bs-list-group-active-bg);border-color:var(--bs-list-group-active-border-color)}.list-group-item+.list-group-item{border-top-width:0}.list-group-item+.list-group-item.active{margin-top:calc(-1*var(--bs-list-group-border-width));border-top-width:var(--bs-list-group-border-width)}.list-group-horizontal{flex-direction:row;-webkit-flex-direction:row}.list-group-horizontal>.list-group-item.active{margin-top:0}.list-group-horizontal>.list-group-item+.list-group-item{border-top-width:var(--bs-list-group-border-width);border-left-width:0}.list-group-horizontal>.list-group-item+.list-group-item.active{margin-left:calc(-1*var(--bs-list-group-border-width));border-left-width:var(--bs-list-group-border-width)}@media(min-width: 576px){.list-group-horizontal-sm{flex-direction:row;-webkit-flex-direction:row}.list-group-horizontal-sm>.list-group-item.active{margin-top:0}.list-group-horizontal-sm>.list-group-item+.list-group-item{border-top-width:var(--bs-list-group-border-width);border-left-width:0}.list-group-horizontal-sm>.list-group-item+.list-group-item.active{margin-left:calc(-1*var(--bs-list-group-border-width));border-left-width:var(--bs-list-group-border-width)}}@media(min-width: 768px){.list-group-horizontal-md{flex-direction:row;-webkit-flex-direction:row}.list-group-horizontal-md>.list-group-item.active{margin-top:0}.list-group-horizontal-md>.list-group-item+.list-group-item{border-top-width:var(--bs-list-group-border-width);border-left-width:0}.list-group-horizontal-md>.list-group-item+.list-group-item.active{margin-left:calc(-1*var(--bs-list-group-border-width));border-left-width:var(--bs-list-group-border-width)}}@media(min-width: 992px){.list-group-horizontal-lg{flex-direction:row;-webkit-flex-direction:row}.list-group-horizontal-lg>.list-group-item.active{margin-top:0}.list-group-horizontal-lg>.list-group-item+.list-group-item{border-top-width:var(--bs-list-group-border-width);border-left-width:0}.list-group-horizontal-lg>.list-group-item+.list-group-item.active{margin-left:calc(-1*var(--bs-list-group-border-width));border-left-width:var(--bs-list-group-border-width)}}@media(min-width: 1200px){.list-group-horizontal-xl{flex-direction:row;-webkit-flex-direction:row}.list-group-horizontal-xl>.list-group-item.active{margin-top:0}.list-group-horizontal-xl>.list-group-item+.list-group-item{border-top-width:var(--bs-list-group-border-width);border-left-width:0}.list-group-horizontal-xl>.list-group-item+.list-group-item.active{margin-left:calc(-1*var(--bs-list-group-border-width));border-left-width:var(--bs-list-group-border-width)}}@media(min-width: 1400px){.list-group-horizontal-xxl{flex-direction:row;-webkit-flex-direction:row}.list-group-horizontal-xxl>.list-group-item.active{margin-top:0}.list-group-horizontal-xxl>.list-group-item+.list-group-item{border-top-width:var(--bs-list-group-border-width);border-left-width:0}.list-group-horizontal-xxl>.list-group-item+.list-group-item.active{margin-left:calc(-1*var(--bs-list-group-border-width));border-left-width:var(--bs-list-group-border-width)}}.list-group-flush>.list-group-item{border-width:0 0 var(--bs-list-group-border-width)}.list-group-flush>.list-group-item:last-child{border-bottom-width:0}.list-group-item-default{--bs-list-group-color: var(--bs-default-text-emphasis);--bs-list-group-bg: var(--bs-default-bg-subtle);--bs-list-group-border-color: var(--bs-default-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-default-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-default-border-subtle);--bs-list-group-active-color: var(--bs-default-bg-subtle);--bs-list-group-active-bg: var(--bs-default-text-emphasis);--bs-list-group-active-border-color: var(--bs-default-text-emphasis)}.list-group-item-primary{--bs-list-group-color: var(--bs-primary-text-emphasis);--bs-list-group-bg: var(--bs-primary-bg-subtle);--bs-list-group-border-color: var(--bs-primary-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-primary-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-primary-border-subtle);--bs-list-group-active-color: var(--bs-primary-bg-subtle);--bs-list-group-active-bg: var(--bs-primary-text-emphasis);--bs-list-group-active-border-color: var(--bs-primary-text-emphasis)}.list-group-item-secondary{--bs-list-group-color: var(--bs-secondary-text-emphasis);--bs-list-group-bg: var(--bs-secondary-bg-subtle);--bs-list-group-border-color: var(--bs-secondary-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-secondary-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-secondary-border-subtle);--bs-list-group-active-color: var(--bs-secondary-bg-subtle);--bs-list-group-active-bg: var(--bs-secondary-text-emphasis);--bs-list-group-active-border-color: var(--bs-secondary-text-emphasis)}.list-group-item-success{--bs-list-group-color: var(--bs-success-text-emphasis);--bs-list-group-bg: var(--bs-success-bg-subtle);--bs-list-group-border-color: var(--bs-success-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-success-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-success-border-subtle);--bs-list-group-active-color: var(--bs-success-bg-subtle);--bs-list-group-active-bg: var(--bs-success-text-emphasis);--bs-list-group-active-border-color: var(--bs-success-text-emphasis)}.list-group-item-info{--bs-list-group-color: var(--bs-info-text-emphasis);--bs-list-group-bg: var(--bs-info-bg-subtle);--bs-list-group-border-color: var(--bs-info-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-info-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-info-border-subtle);--bs-list-group-active-color: var(--bs-info-bg-subtle);--bs-list-group-active-bg: var(--bs-info-text-emphasis);--bs-list-group-active-border-color: var(--bs-info-text-emphasis)}.list-group-item-warning{--bs-list-group-color: var(--bs-warning-text-emphasis);--bs-list-group-bg: var(--bs-warning-bg-subtle);--bs-list-group-border-color: var(--bs-warning-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-warning-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-warning-border-subtle);--bs-list-group-active-color: var(--bs-warning-bg-subtle);--bs-list-group-active-bg: var(--bs-warning-text-emphasis);--bs-list-group-active-border-color: var(--bs-warning-text-emphasis)}.list-group-item-danger{--bs-list-group-color: var(--bs-danger-text-emphasis);--bs-list-group-bg: var(--bs-danger-bg-subtle);--bs-list-group-border-color: var(--bs-danger-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-danger-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-danger-border-subtle);--bs-list-group-active-color: var(--bs-danger-bg-subtle);--bs-list-group-active-bg: var(--bs-danger-text-emphasis);--bs-list-group-active-border-color: var(--bs-danger-text-emphasis)}.list-group-item-light{--bs-list-group-color: var(--bs-light-text-emphasis);--bs-list-group-bg: var(--bs-light-bg-subtle);--bs-list-group-border-color: var(--bs-light-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-light-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-light-border-subtle);--bs-list-group-active-color: var(--bs-light-bg-subtle);--bs-list-group-active-bg: var(--bs-light-text-emphasis);--bs-list-group-active-border-color: var(--bs-light-text-emphasis)}.list-group-item-dark{--bs-list-group-color: var(--bs-dark-text-emphasis);--bs-list-group-bg: var(--bs-dark-bg-subtle);--bs-list-group-border-color: var(--bs-dark-border-subtle);--bs-list-group-action-hover-color: var(--bs-emphasis-color);--bs-list-group-action-hover-bg: var(--bs-dark-border-subtle);--bs-list-group-action-active-color: var(--bs-emphasis-color);--bs-list-group-action-active-bg: var(--bs-dark-border-subtle);--bs-list-group-active-color: var(--bs-dark-bg-subtle);--bs-list-group-active-bg: var(--bs-dark-text-emphasis);--bs-list-group-active-border-color: var(--bs-dark-text-emphasis)}.btn-close{--bs-btn-close-color: #000;--bs-btn-close-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='%23000'%3e%3cpath d='M.293.293a1 1 0 0 1 1.414 0L8 6.586 14.293.293a1 1 0 1 1 1.414 1.414L9.414 8l6.293 6.293a1 1 0 0 1-1.414 1.414L8 9.414l-6.293 6.293a1 1 0 0 1-1.414-1.414L6.586 8 .293 1.707a1 1 0 0 1 0-1.414z'/%3e%3c/svg%3e");--bs-btn-close-opacity: 0.5;--bs-btn-close-hover-opacity: 0.75;--bs-btn-close-focus-shadow: 0 0 0 0.25rem rgba(39, 128, 227, 0.25);--bs-btn-close-focus-opacity: 1;--bs-btn-close-disabled-opacity: 0.25;--bs-btn-close-white-filter: invert(1) grayscale(100%) brightness(200%);box-sizing:content-box;width:1em;height:1em;padding:.25em .25em;color:var(--bs-btn-close-color);background:rgba(0,0,0,0) var(--bs-btn-close-bg) center/1em auto no-repeat;border:0;opacity:var(--bs-btn-close-opacity)}.btn-close:hover{color:var(--bs-btn-close-color);text-decoration:none;opacity:var(--bs-btn-close-hover-opacity)}.btn-close:focus{outline:0;box-shadow:var(--bs-btn-close-focus-shadow);opacity:var(--bs-btn-close-focus-opacity)}.btn-close:disabled,.btn-close.disabled{pointer-events:none;user-select:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;-o-user-select:none;opacity:var(--bs-btn-close-disabled-opacity)}.btn-close-white{filter:var(--bs-btn-close-white-filter)}[data-bs-theme=dark] .btn-close{filter:var(--bs-btn-close-white-filter)}.toast{--bs-toast-zindex: 1090;--bs-toast-padding-x: 0.75rem;--bs-toast-padding-y: 0.5rem;--bs-toast-spacing: 1.5rem;--bs-toast-max-width: 350px;--bs-toast-font-size:0.875rem;--bs-toast-color: ;--bs-toast-bg: rgba(255, 255, 255, 0.85);--bs-toast-border-width: 1px;--bs-toast-border-color: rgba(0, 0, 0, 0.175);--bs-toast-border-radius: 0.25rem;--bs-toast-box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);--bs-toast-header-color: rgba(52, 58, 64, 0.75);--bs-toast-header-bg: rgba(255, 255, 255, 0.85);--bs-toast-header-border-color: rgba(0, 0, 0, 0.175);width:var(--bs-toast-max-width);max-width:100%;font-size:var(--bs-toast-font-size);color:var(--bs-toast-color);pointer-events:auto;background-color:var(--bs-toast-bg);background-clip:padding-box;border:var(--bs-toast-border-width) solid var(--bs-toast-border-color);box-shadow:var(--bs-toast-box-shadow)}.toast.showing{opacity:0}.toast:not(.show){display:none}.toast-container{--bs-toast-zindex: 1090;position:absolute;z-index:var(--bs-toast-zindex);width:max-content;width:-webkit-max-content;width:-moz-max-content;width:-ms-max-content;width:-o-max-content;max-width:100%;pointer-events:none}.toast-container>:not(:last-child){margin-bottom:var(--bs-toast-spacing)}.toast-header{display:flex;display:-webkit-flex;align-items:center;-webkit-align-items:center;padding:var(--bs-toast-padding-y) var(--bs-toast-padding-x);color:var(--bs-toast-header-color);background-color:var(--bs-toast-header-bg);background-clip:padding-box;border-bottom:var(--bs-toast-border-width) solid var(--bs-toast-header-border-color)}.toast-header .btn-close{margin-right:calc(-0.5*var(--bs-toast-padding-x));margin-left:var(--bs-toast-padding-x)}.toast-body{padding:var(--bs-toast-padding-x);word-wrap:break-word}.modal{--bs-modal-zindex: 1055;--bs-modal-width: 500px;--bs-modal-padding: 1rem;--bs-modal-margin: 0.5rem;--bs-modal-color: ;--bs-modal-bg: #fff;--bs-modal-border-color: rgba(0, 0, 0, 0.175);--bs-modal-border-width: 1px;--bs-modal-border-radius: 0.5rem;--bs-modal-box-shadow: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.075);--bs-modal-inner-border-radius: calc(0.5rem - 1px);--bs-modal-header-padding-x: 1rem;--bs-modal-header-padding-y: 1rem;--bs-modal-header-padding: 1rem 1rem;--bs-modal-header-border-color: #dee2e6;--bs-modal-header-border-width: 1px;--bs-modal-title-line-height: 1.5;--bs-modal-footer-gap: 0.5rem;--bs-modal-footer-bg: ;--bs-modal-footer-border-color: #dee2e6;--bs-modal-footer-border-width: 1px;position:fixed;top:0;left:0;z-index:var(--bs-modal-zindex);display:none;width:100%;height:100%;overflow-x:hidden;overflow-y:auto;outline:0}.modal-dialog{position:relative;width:auto;margin:var(--bs-modal-margin);pointer-events:none}.modal.fade .modal-dialog{transition:transform .3s ease-out;transform:translate(0, -50px)}@media(prefers-reduced-motion: reduce){.modal.fade .modal-dialog{transition:none}}.modal.show .modal-dialog{transform:none}.modal.modal-static .modal-dialog{transform:scale(1.02)}.modal-dialog-scrollable{height:calc(100% - var(--bs-modal-margin)*2)}.modal-dialog-scrollable .modal-content{max-height:100%;overflow:hidden}.modal-dialog-scrollable .modal-body{overflow-y:auto}.modal-dialog-centered{display:flex;display:-webkit-flex;align-items:center;-webkit-align-items:center;min-height:calc(100% - var(--bs-modal-margin)*2)}.modal-content{position:relative;display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;width:100%;color:var(--bs-modal-color);pointer-events:auto;background-color:var(--bs-modal-bg);background-clip:padding-box;border:var(--bs-modal-border-width) solid var(--bs-modal-border-color);outline:0}.modal-backdrop{--bs-backdrop-zindex: 1050;--bs-backdrop-bg: #000;--bs-backdrop-opacity: 0.5;position:fixed;top:0;left:0;z-index:var(--bs-backdrop-zindex);width:100vw;height:100vh;background-color:var(--bs-backdrop-bg)}.modal-backdrop.fade{opacity:0}.modal-backdrop.show{opacity:var(--bs-backdrop-opacity)}.modal-header{display:flex;display:-webkit-flex;flex-shrink:0;-webkit-flex-shrink:0;align-items:center;-webkit-align-items:center;justify-content:space-between;-webkit-justify-content:space-between;padding:var(--bs-modal-header-padding);border-bottom:var(--bs-modal-header-border-width) solid var(--bs-modal-header-border-color)}.modal-header .btn-close{padding:calc(var(--bs-modal-header-padding-y)*.5) calc(var(--bs-modal-header-padding-x)*.5);margin:calc(-0.5*var(--bs-modal-header-padding-y)) calc(-0.5*var(--bs-modal-header-padding-x)) calc(-0.5*var(--bs-modal-header-padding-y)) auto}.modal-title{margin-bottom:0;line-height:var(--bs-modal-title-line-height)}.modal-body{position:relative;flex:1 1 auto;-webkit-flex:1 1 auto;padding:var(--bs-modal-padding)}.modal-footer{display:flex;display:-webkit-flex;flex-shrink:0;-webkit-flex-shrink:0;flex-wrap:wrap;-webkit-flex-wrap:wrap;align-items:center;-webkit-align-items:center;justify-content:flex-end;-webkit-justify-content:flex-end;padding:calc(var(--bs-modal-padding) - var(--bs-modal-footer-gap)*.5);background-color:var(--bs-modal-footer-bg);border-top:var(--bs-modal-footer-border-width) solid var(--bs-modal-footer-border-color)}.modal-footer>*{margin:calc(var(--bs-modal-footer-gap)*.5)}@media(min-width: 576px){.modal{--bs-modal-margin: 1.75rem;--bs-modal-box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15)}.modal-dialog{max-width:var(--bs-modal-width);margin-right:auto;margin-left:auto}.modal-sm{--bs-modal-width: 300px}}@media(min-width: 992px){.modal-lg,.modal-xl{--bs-modal-width: 800px}}@media(min-width: 1200px){.modal-xl{--bs-modal-width: 1140px}}.modal-fullscreen{width:100vw;max-width:none;height:100%;margin:0}.modal-fullscreen .modal-content{height:100%;border:0}.modal-fullscreen .modal-body{overflow-y:auto}@media(max-width: 575.98px){.modal-fullscreen-sm-down{width:100vw;max-width:none;height:100%;margin:0}.modal-fullscreen-sm-down .modal-content{height:100%;border:0}.modal-fullscreen-sm-down .modal-body{overflow-y:auto}}@media(max-width: 767.98px){.modal-fullscreen-md-down{width:100vw;max-width:none;height:100%;margin:0}.modal-fullscreen-md-down .modal-content{height:100%;border:0}.modal-fullscreen-md-down .modal-body{overflow-y:auto}}@media(max-width: 991.98px){.modal-fullscreen-lg-down{width:100vw;max-width:none;height:100%;margin:0}.modal-fullscreen-lg-down .modal-content{height:100%;border:0}.modal-fullscreen-lg-down .modal-body{overflow-y:auto}}@media(max-width: 1199.98px){.modal-fullscreen-xl-down{width:100vw;max-width:none;height:100%;margin:0}.modal-fullscreen-xl-down .modal-content{height:100%;border:0}.modal-fullscreen-xl-down .modal-body{overflow-y:auto}}@media(max-width: 1399.98px){.modal-fullscreen-xxl-down{width:100vw;max-width:none;height:100%;margin:0}.modal-fullscreen-xxl-down .modal-content{height:100%;border:0}.modal-fullscreen-xxl-down .modal-body{overflow-y:auto}}.tooltip{--bs-tooltip-zindex: 1080;--bs-tooltip-max-width: 200px;--bs-tooltip-padding-x: 0.5rem;--bs-tooltip-padding-y: 0.25rem;--bs-tooltip-margin: ;--bs-tooltip-font-size:0.875rem;--bs-tooltip-color: #fff;--bs-tooltip-bg: #000;--bs-tooltip-border-radius: 0.25rem;--bs-tooltip-opacity: 0.9;--bs-tooltip-arrow-width: 0.8rem;--bs-tooltip-arrow-height: 0.4rem;z-index:var(--bs-tooltip-zindex);display:block;margin:var(--bs-tooltip-margin);font-family:"Source Sans Pro",-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol";font-style:normal;font-weight:400;line-height:1.5;text-align:left;text-align:start;text-decoration:none;text-shadow:none;text-transform:none;letter-spacing:normal;word-break:normal;white-space:normal;word-spacing:normal;line-break:auto;font-size:var(--bs-tooltip-font-size);word-wrap:break-word;opacity:0}.tooltip.show{opacity:var(--bs-tooltip-opacity)}.tooltip .tooltip-arrow{display:block;width:var(--bs-tooltip-arrow-width);height:var(--bs-tooltip-arrow-height)}.tooltip .tooltip-arrow::before{position:absolute;content:"";border-color:rgba(0,0,0,0);border-style:solid}.bs-tooltip-top .tooltip-arrow,.bs-tooltip-auto[data-popper-placement^=top] .tooltip-arrow{bottom:calc(-1*var(--bs-tooltip-arrow-height))}.bs-tooltip-top .tooltip-arrow::before,.bs-tooltip-auto[data-popper-placement^=top] .tooltip-arrow::before{top:-1px;border-width:var(--bs-tooltip-arrow-height) calc(var(--bs-tooltip-arrow-width)*.5) 0;border-top-color:var(--bs-tooltip-bg)}.bs-tooltip-end .tooltip-arrow,.bs-tooltip-auto[data-popper-placement^=right] .tooltip-arrow{left:calc(-1*var(--bs-tooltip-arrow-height));width:var(--bs-tooltip-arrow-height);height:var(--bs-tooltip-arrow-width)}.bs-tooltip-end .tooltip-arrow::before,.bs-tooltip-auto[data-popper-placement^=right] .tooltip-arrow::before{right:-1px;border-width:calc(var(--bs-tooltip-arrow-width)*.5) var(--bs-tooltip-arrow-height) calc(var(--bs-tooltip-arrow-width)*.5) 0;border-right-color:var(--bs-tooltip-bg)}.bs-tooltip-bottom .tooltip-arrow,.bs-tooltip-auto[data-popper-placement^=bottom] .tooltip-arrow{top:calc(-1*var(--bs-tooltip-arrow-height))}.bs-tooltip-bottom .tooltip-arrow::before,.bs-tooltip-auto[data-popper-placement^=bottom] .tooltip-arrow::before{bottom:-1px;border-width:0 calc(var(--bs-tooltip-arrow-width)*.5) var(--bs-tooltip-arrow-height);border-bottom-color:var(--bs-tooltip-bg)}.bs-tooltip-start .tooltip-arrow,.bs-tooltip-auto[data-popper-placement^=left] .tooltip-arrow{right:calc(-1*var(--bs-tooltip-arrow-height));width:var(--bs-tooltip-arrow-height);height:var(--bs-tooltip-arrow-width)}.bs-tooltip-start .tooltip-arrow::before,.bs-tooltip-auto[data-popper-placement^=left] .tooltip-arrow::before{left:-1px;border-width:calc(var(--bs-tooltip-arrow-width)*.5) 0 calc(var(--bs-tooltip-arrow-width)*.5) var(--bs-tooltip-arrow-height);border-left-color:var(--bs-tooltip-bg)}.tooltip-inner{max-width:var(--bs-tooltip-max-width);padding:var(--bs-tooltip-padding-y) var(--bs-tooltip-padding-x);color:var(--bs-tooltip-color);text-align:center;background-color:var(--bs-tooltip-bg)}.popover{--bs-popover-zindex: 1070;--bs-popover-max-width: 276px;--bs-popover-font-size:0.875rem;--bs-popover-bg: #fff;--bs-popover-border-width: 1px;--bs-popover-border-color: rgba(0, 0, 0, 0.175);--bs-popover-border-radius: 0.5rem;--bs-popover-inner-border-radius: calc(0.5rem - 1px);--bs-popover-box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);--bs-popover-header-padding-x: 1rem;--bs-popover-header-padding-y: 0.5rem;--bs-popover-header-font-size:1rem;--bs-popover-header-color: inherit;--bs-popover-header-bg: #e9ecef;--bs-popover-body-padding-x: 1rem;--bs-popover-body-padding-y: 1rem;--bs-popover-body-color: #343a40;--bs-popover-arrow-width: 1rem;--bs-popover-arrow-height: 0.5rem;--bs-popover-arrow-border: var(--bs-popover-border-color);z-index:var(--bs-popover-zindex);display:block;max-width:var(--bs-popover-max-width);font-family:"Source Sans Pro",-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol";font-style:normal;font-weight:400;line-height:1.5;text-align:left;text-align:start;text-decoration:none;text-shadow:none;text-transform:none;letter-spacing:normal;word-break:normal;white-space:normal;word-spacing:normal;line-break:auto;font-size:var(--bs-popover-font-size);word-wrap:break-word;background-color:var(--bs-popover-bg);background-clip:padding-box;border:var(--bs-popover-border-width) solid var(--bs-popover-border-color)}.popover .popover-arrow{display:block;width:var(--bs-popover-arrow-width);height:var(--bs-popover-arrow-height)}.popover .popover-arrow::before,.popover .popover-arrow::after{position:absolute;display:block;content:"";border-color:rgba(0,0,0,0);border-style:solid;border-width:0}.bs-popover-top>.popover-arrow,.bs-popover-auto[data-popper-placement^=top]>.popover-arrow{bottom:calc(-1*(var(--bs-popover-arrow-height)) - var(--bs-popover-border-width))}.bs-popover-top>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=top]>.popover-arrow::before,.bs-popover-top>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=top]>.popover-arrow::after{border-width:var(--bs-popover-arrow-height) calc(var(--bs-popover-arrow-width)*.5) 0}.bs-popover-top>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=top]>.popover-arrow::before{bottom:0;border-top-color:var(--bs-popover-arrow-border)}.bs-popover-top>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=top]>.popover-arrow::after{bottom:var(--bs-popover-border-width);border-top-color:var(--bs-popover-bg)}.bs-popover-end>.popover-arrow,.bs-popover-auto[data-popper-placement^=right]>.popover-arrow{left:calc(-1*(var(--bs-popover-arrow-height)) - var(--bs-popover-border-width));width:var(--bs-popover-arrow-height);height:var(--bs-popover-arrow-width)}.bs-popover-end>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=right]>.popover-arrow::before,.bs-popover-end>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=right]>.popover-arrow::after{border-width:calc(var(--bs-popover-arrow-width)*.5) var(--bs-popover-arrow-height) calc(var(--bs-popover-arrow-width)*.5) 0}.bs-popover-end>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=right]>.popover-arrow::before{left:0;border-right-color:var(--bs-popover-arrow-border)}.bs-popover-end>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=right]>.popover-arrow::after{left:var(--bs-popover-border-width);border-right-color:var(--bs-popover-bg)}.bs-popover-bottom>.popover-arrow,.bs-popover-auto[data-popper-placement^=bottom]>.popover-arrow{top:calc(-1*(var(--bs-popover-arrow-height)) - var(--bs-popover-border-width))}.bs-popover-bottom>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=bottom]>.popover-arrow::before,.bs-popover-bottom>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=bottom]>.popover-arrow::after{border-width:0 calc(var(--bs-popover-arrow-width)*.5) var(--bs-popover-arrow-height)}.bs-popover-bottom>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=bottom]>.popover-arrow::before{top:0;border-bottom-color:var(--bs-popover-arrow-border)}.bs-popover-bottom>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=bottom]>.popover-arrow::after{top:var(--bs-popover-border-width);border-bottom-color:var(--bs-popover-bg)}.bs-popover-bottom .popover-header::before,.bs-popover-auto[data-popper-placement^=bottom] .popover-header::before{position:absolute;top:0;left:50%;display:block;width:var(--bs-popover-arrow-width);margin-left:calc(-0.5*var(--bs-popover-arrow-width));content:"";border-bottom:var(--bs-popover-border-width) solid var(--bs-popover-header-bg)}.bs-popover-start>.popover-arrow,.bs-popover-auto[data-popper-placement^=left]>.popover-arrow{right:calc(-1*(var(--bs-popover-arrow-height)) - var(--bs-popover-border-width));width:var(--bs-popover-arrow-height);height:var(--bs-popover-arrow-width)}.bs-popover-start>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=left]>.popover-arrow::before,.bs-popover-start>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=left]>.popover-arrow::after{border-width:calc(var(--bs-popover-arrow-width)*.5) 0 calc(var(--bs-popover-arrow-width)*.5) var(--bs-popover-arrow-height)}.bs-popover-start>.popover-arrow::before,.bs-popover-auto[data-popper-placement^=left]>.popover-arrow::before{right:0;border-left-color:var(--bs-popover-arrow-border)}.bs-popover-start>.popover-arrow::after,.bs-popover-auto[data-popper-placement^=left]>.popover-arrow::after{right:var(--bs-popover-border-width);border-left-color:var(--bs-popover-bg)}.popover-header{padding:var(--bs-popover-header-padding-y) var(--bs-popover-header-padding-x);margin-bottom:0;font-size:var(--bs-popover-header-font-size);color:var(--bs-popover-header-color);background-color:var(--bs-popover-header-bg);border-bottom:var(--bs-popover-border-width) solid var(--bs-popover-border-color)}.popover-header:empty{display:none}.popover-body{padding:var(--bs-popover-body-padding-y) var(--bs-popover-body-padding-x);color:var(--bs-popover-body-color)}.carousel{position:relative}.carousel.pointer-event{touch-action:pan-y;-webkit-touch-action:pan-y;-moz-touch-action:pan-y;-ms-touch-action:pan-y;-o-touch-action:pan-y}.carousel-inner{position:relative;width:100%;overflow:hidden}.carousel-inner::after{display:block;clear:both;content:""}.carousel-item{position:relative;display:none;float:left;width:100%;margin-right:-100%;backface-visibility:hidden;-webkit-backface-visibility:hidden;-moz-backface-visibility:hidden;-ms-backface-visibility:hidden;-o-backface-visibility:hidden;transition:transform .6s ease-in-out}@media(prefers-reduced-motion: reduce){.carousel-item{transition:none}}.carousel-item.active,.carousel-item-next,.carousel-item-prev{display:block}.carousel-item-next:not(.carousel-item-start),.active.carousel-item-end{transform:translateX(100%)}.carousel-item-prev:not(.carousel-item-end),.active.carousel-item-start{transform:translateX(-100%)}.carousel-fade .carousel-item{opacity:0;transition-property:opacity;transform:none}.carousel-fade .carousel-item.active,.carousel-fade .carousel-item-next.carousel-item-start,.carousel-fade .carousel-item-prev.carousel-item-end{z-index:1;opacity:1}.carousel-fade .active.carousel-item-start,.carousel-fade .active.carousel-item-end{z-index:0;opacity:0;transition:opacity 0s .6s}@media(prefers-reduced-motion: reduce){.carousel-fade .active.carousel-item-start,.carousel-fade .active.carousel-item-end{transition:none}}.carousel-control-prev,.carousel-control-next{position:absolute;top:0;bottom:0;z-index:1;display:flex;display:-webkit-flex;align-items:center;-webkit-align-items:center;justify-content:center;-webkit-justify-content:center;width:15%;padding:0;color:#fff;text-align:center;background:none;border:0;opacity:.5;transition:opacity .15s ease}@media(prefers-reduced-motion: reduce){.carousel-control-prev,.carousel-control-next{transition:none}}.carousel-control-prev:hover,.carousel-control-prev:focus,.carousel-control-next:hover,.carousel-control-next:focus{color:#fff;text-decoration:none;outline:0;opacity:.9}.carousel-control-prev{left:0}.carousel-control-next{right:0}.carousel-control-prev-icon,.carousel-control-next-icon{display:inline-block;width:2rem;height:2rem;background-repeat:no-repeat;background-position:50%;background-size:100% 100%}.carousel-control-prev-icon{background-image:url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='%23fff'%3e%3cpath d='M11.354 1.646a.5.5 0 0 1 0 .708L5.707 8l5.647 5.646a.5.5 0 0 1-.708.708l-6-6a.5.5 0 0 1 0-.708l6-6a.5.5 0 0 1 .708 0z'/%3e%3c/svg%3e")}.carousel-control-next-icon{background-image:url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='%23fff'%3e%3cpath d='M4.646 1.646a.5.5 0 0 1 .708 0l6 6a.5.5 0 0 1 0 .708l-6 6a.5.5 0 0 1-.708-.708L10.293 8 4.646 2.354a.5.5 0 0 1 0-.708z'/%3e%3c/svg%3e")}.carousel-indicators{position:absolute;right:0;bottom:0;left:0;z-index:2;display:flex;display:-webkit-flex;justify-content:center;-webkit-justify-content:center;padding:0;margin-right:15%;margin-bottom:1rem;margin-left:15%}.carousel-indicators [data-bs-target]{box-sizing:content-box;flex:0 1 auto;-webkit-flex:0 1 auto;width:30px;height:3px;padding:0;margin-right:3px;margin-left:3px;text-indent:-999px;cursor:pointer;background-color:#fff;background-clip:padding-box;border:0;border-top:10px solid rgba(0,0,0,0);border-bottom:10px solid rgba(0,0,0,0);opacity:.5;transition:opacity .6s ease}@media(prefers-reduced-motion: reduce){.carousel-indicators [data-bs-target]{transition:none}}.carousel-indicators .active{opacity:1}.carousel-caption{position:absolute;right:15%;bottom:1.25rem;left:15%;padding-top:1.25rem;padding-bottom:1.25rem;color:#fff;text-align:center}.carousel-dark .carousel-control-prev-icon,.carousel-dark .carousel-control-next-icon{filter:invert(1) grayscale(100)}.carousel-dark .carousel-indicators [data-bs-target]{background-color:#000}.carousel-dark .carousel-caption{color:#000}[data-bs-theme=dark] .carousel .carousel-control-prev-icon,[data-bs-theme=dark] .carousel .carousel-control-next-icon,[data-bs-theme=dark].carousel .carousel-control-prev-icon,[data-bs-theme=dark].carousel .carousel-control-next-icon{filter:invert(1) grayscale(100)}[data-bs-theme=dark] .carousel .carousel-indicators [data-bs-target],[data-bs-theme=dark].carousel .carousel-indicators [data-bs-target]{background-color:#000}[data-bs-theme=dark] .carousel .carousel-caption,[data-bs-theme=dark].carousel .carousel-caption{color:#000}.spinner-grow,.spinner-border{display:inline-block;width:var(--bs-spinner-width);height:var(--bs-spinner-height);vertical-align:var(--bs-spinner-vertical-align);border-radius:50%;animation:var(--bs-spinner-animation-speed) linear infinite var(--bs-spinner-animation-name)}@keyframes spinner-border{to{transform:rotate(360deg) /* rtl:ignore */}}.spinner-border{--bs-spinner-width: 2rem;--bs-spinner-height: 2rem;--bs-spinner-vertical-align: -0.125em;--bs-spinner-border-width: 0.25em;--bs-spinner-animation-speed: 0.75s;--bs-spinner-animation-name: spinner-border;border:var(--bs-spinner-border-width) solid currentcolor;border-right-color:rgba(0,0,0,0)}.spinner-border-sm{--bs-spinner-width: 1rem;--bs-spinner-height: 1rem;--bs-spinner-border-width: 0.2em}@keyframes spinner-grow{0%{transform:scale(0)}50%{opacity:1;transform:none}}.spinner-grow{--bs-spinner-width: 2rem;--bs-spinner-height: 2rem;--bs-spinner-vertical-align: -0.125em;--bs-spinner-animation-speed: 0.75s;--bs-spinner-animation-name: spinner-grow;background-color:currentcolor;opacity:0}.spinner-grow-sm{--bs-spinner-width: 1rem;--bs-spinner-height: 1rem}@media(prefers-reduced-motion: reduce){.spinner-border,.spinner-grow{--bs-spinner-animation-speed: 1.5s}}.offcanvas,.offcanvas-xxl,.offcanvas-xl,.offcanvas-lg,.offcanvas-md,.offcanvas-sm{--bs-offcanvas-zindex: 1045;--bs-offcanvas-width: 400px;--bs-offcanvas-height: 30vh;--bs-offcanvas-padding-x: 1rem;--bs-offcanvas-padding-y: 1rem;--bs-offcanvas-color: #343a40;--bs-offcanvas-bg: #fff;--bs-offcanvas-border-width: 1px;--bs-offcanvas-border-color: rgba(0, 0, 0, 0.175);--bs-offcanvas-box-shadow: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.075);--bs-offcanvas-transition: transform 0.3s ease-in-out;--bs-offcanvas-title-line-height: 1.5}@media(max-width: 575.98px){.offcanvas-sm{position:fixed;bottom:0;z-index:var(--bs-offcanvas-zindex);display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;max-width:100%;color:var(--bs-offcanvas-color);visibility:hidden;background-color:var(--bs-offcanvas-bg);background-clip:padding-box;outline:0;transition:var(--bs-offcanvas-transition)}}@media(max-width: 575.98px)and (prefers-reduced-motion: reduce){.offcanvas-sm{transition:none}}@media(max-width: 575.98px){.offcanvas-sm.offcanvas-start{top:0;left:0;width:var(--bs-offcanvas-width);border-right:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(-100%)}.offcanvas-sm.offcanvas-end{top:0;right:0;width:var(--bs-offcanvas-width);border-left:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(100%)}.offcanvas-sm.offcanvas-top{top:0;right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-bottom:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(-100%)}.offcanvas-sm.offcanvas-bottom{right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-top:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(100%)}.offcanvas-sm.showing,.offcanvas-sm.show:not(.hiding){transform:none}.offcanvas-sm.showing,.offcanvas-sm.hiding,.offcanvas-sm.show{visibility:visible}}@media(min-width: 576px){.offcanvas-sm{--bs-offcanvas-height: auto;--bs-offcanvas-border-width: 0;background-color:rgba(0,0,0,0) !important}.offcanvas-sm .offcanvas-header{display:none}.offcanvas-sm .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible;background-color:rgba(0,0,0,0) !important}}@media(max-width: 767.98px){.offcanvas-md{position:fixed;bottom:0;z-index:var(--bs-offcanvas-zindex);display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;max-width:100%;color:var(--bs-offcanvas-color);visibility:hidden;background-color:var(--bs-offcanvas-bg);background-clip:padding-box;outline:0;transition:var(--bs-offcanvas-transition)}}@media(max-width: 767.98px)and (prefers-reduced-motion: reduce){.offcanvas-md{transition:none}}@media(max-width: 767.98px){.offcanvas-md.offcanvas-start{top:0;left:0;width:var(--bs-offcanvas-width);border-right:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(-100%)}.offcanvas-md.offcanvas-end{top:0;right:0;width:var(--bs-offcanvas-width);border-left:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(100%)}.offcanvas-md.offcanvas-top{top:0;right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-bottom:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(-100%)}.offcanvas-md.offcanvas-bottom{right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-top:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(100%)}.offcanvas-md.showing,.offcanvas-md.show:not(.hiding){transform:none}.offcanvas-md.showing,.offcanvas-md.hiding,.offcanvas-md.show{visibility:visible}}@media(min-width: 768px){.offcanvas-md{--bs-offcanvas-height: auto;--bs-offcanvas-border-width: 0;background-color:rgba(0,0,0,0) !important}.offcanvas-md .offcanvas-header{display:none}.offcanvas-md .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible;background-color:rgba(0,0,0,0) !important}}@media(max-width: 991.98px){.offcanvas-lg{position:fixed;bottom:0;z-index:var(--bs-offcanvas-zindex);display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;max-width:100%;color:var(--bs-offcanvas-color);visibility:hidden;background-color:var(--bs-offcanvas-bg);background-clip:padding-box;outline:0;transition:var(--bs-offcanvas-transition)}}@media(max-width: 991.98px)and (prefers-reduced-motion: reduce){.offcanvas-lg{transition:none}}@media(max-width: 991.98px){.offcanvas-lg.offcanvas-start{top:0;left:0;width:var(--bs-offcanvas-width);border-right:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(-100%)}.offcanvas-lg.offcanvas-end{top:0;right:0;width:var(--bs-offcanvas-width);border-left:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(100%)}.offcanvas-lg.offcanvas-top{top:0;right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-bottom:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(-100%)}.offcanvas-lg.offcanvas-bottom{right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-top:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(100%)}.offcanvas-lg.showing,.offcanvas-lg.show:not(.hiding){transform:none}.offcanvas-lg.showing,.offcanvas-lg.hiding,.offcanvas-lg.show{visibility:visible}}@media(min-width: 992px){.offcanvas-lg{--bs-offcanvas-height: auto;--bs-offcanvas-border-width: 0;background-color:rgba(0,0,0,0) !important}.offcanvas-lg .offcanvas-header{display:none}.offcanvas-lg .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible;background-color:rgba(0,0,0,0) !important}}@media(max-width: 1199.98px){.offcanvas-xl{position:fixed;bottom:0;z-index:var(--bs-offcanvas-zindex);display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;max-width:100%;color:var(--bs-offcanvas-color);visibility:hidden;background-color:var(--bs-offcanvas-bg);background-clip:padding-box;outline:0;transition:var(--bs-offcanvas-transition)}}@media(max-width: 1199.98px)and (prefers-reduced-motion: reduce){.offcanvas-xl{transition:none}}@media(max-width: 1199.98px){.offcanvas-xl.offcanvas-start{top:0;left:0;width:var(--bs-offcanvas-width);border-right:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(-100%)}.offcanvas-xl.offcanvas-end{top:0;right:0;width:var(--bs-offcanvas-width);border-left:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(100%)}.offcanvas-xl.offcanvas-top{top:0;right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-bottom:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(-100%)}.offcanvas-xl.offcanvas-bottom{right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-top:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(100%)}.offcanvas-xl.showing,.offcanvas-xl.show:not(.hiding){transform:none}.offcanvas-xl.showing,.offcanvas-xl.hiding,.offcanvas-xl.show{visibility:visible}}@media(min-width: 1200px){.offcanvas-xl{--bs-offcanvas-height: auto;--bs-offcanvas-border-width: 0;background-color:rgba(0,0,0,0) !important}.offcanvas-xl .offcanvas-header{display:none}.offcanvas-xl .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible;background-color:rgba(0,0,0,0) !important}}@media(max-width: 1399.98px){.offcanvas-xxl{position:fixed;bottom:0;z-index:var(--bs-offcanvas-zindex);display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;max-width:100%;color:var(--bs-offcanvas-color);visibility:hidden;background-color:var(--bs-offcanvas-bg);background-clip:padding-box;outline:0;transition:var(--bs-offcanvas-transition)}}@media(max-width: 1399.98px)and (prefers-reduced-motion: reduce){.offcanvas-xxl{transition:none}}@media(max-width: 1399.98px){.offcanvas-xxl.offcanvas-start{top:0;left:0;width:var(--bs-offcanvas-width);border-right:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(-100%)}.offcanvas-xxl.offcanvas-end{top:0;right:0;width:var(--bs-offcanvas-width);border-left:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(100%)}.offcanvas-xxl.offcanvas-top{top:0;right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-bottom:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(-100%)}.offcanvas-xxl.offcanvas-bottom{right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-top:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(100%)}.offcanvas-xxl.showing,.offcanvas-xxl.show:not(.hiding){transform:none}.offcanvas-xxl.showing,.offcanvas-xxl.hiding,.offcanvas-xxl.show{visibility:visible}}@media(min-width: 1400px){.offcanvas-xxl{--bs-offcanvas-height: auto;--bs-offcanvas-border-width: 0;background-color:rgba(0,0,0,0) !important}.offcanvas-xxl .offcanvas-header{display:none}.offcanvas-xxl .offcanvas-body{display:flex;display:-webkit-flex;flex-grow:0;-webkit-flex-grow:0;padding:0;overflow-y:visible;background-color:rgba(0,0,0,0) !important}}.offcanvas{position:fixed;bottom:0;z-index:var(--bs-offcanvas-zindex);display:flex;display:-webkit-flex;flex-direction:column;-webkit-flex-direction:column;max-width:100%;color:var(--bs-offcanvas-color);visibility:hidden;background-color:var(--bs-offcanvas-bg);background-clip:padding-box;outline:0;transition:var(--bs-offcanvas-transition)}@media(prefers-reduced-motion: reduce){.offcanvas{transition:none}}.offcanvas.offcanvas-start{top:0;left:0;width:var(--bs-offcanvas-width);border-right:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(-100%)}.offcanvas.offcanvas-end{top:0;right:0;width:var(--bs-offcanvas-width);border-left:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateX(100%)}.offcanvas.offcanvas-top{top:0;right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-bottom:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(-100%)}.offcanvas.offcanvas-bottom{right:0;left:0;height:var(--bs-offcanvas-height);max-height:100%;border-top:var(--bs-offcanvas-border-width) solid var(--bs-offcanvas-border-color);transform:translateY(100%)}.offcanvas.showing,.offcanvas.show:not(.hiding){transform:none}.offcanvas.showing,.offcanvas.hiding,.offcanvas.show{visibility:visible}.offcanvas-backdrop{position:fixed;top:0;left:0;z-index:1040;width:100vw;height:100vh;background-color:#000}.offcanvas-backdrop.fade{opacity:0}.offcanvas-backdrop.show{opacity:.5}.offcanvas-header{display:flex;display:-webkit-flex;align-items:center;-webkit-align-items:center;justify-content:space-between;-webkit-justify-content:space-between;padding:var(--bs-offcanvas-padding-y) var(--bs-offcanvas-padding-x)}.offcanvas-header .btn-close{padding:calc(var(--bs-offcanvas-padding-y)*.5) calc(var(--bs-offcanvas-padding-x)*.5);margin-top:calc(-0.5*var(--bs-offcanvas-padding-y));margin-right:calc(-0.5*var(--bs-offcanvas-padding-x));margin-bottom:calc(-0.5*var(--bs-offcanvas-padding-y))}.offcanvas-title{margin-bottom:0;line-height:var(--bs-offcanvas-title-line-height)}.offcanvas-body{flex-grow:1;-webkit-flex-grow:1;padding:var(--bs-offcanvas-padding-y) var(--bs-offcanvas-padding-x);overflow-y:auto}.placeholder{display:inline-block;min-height:1em;vertical-align:middle;cursor:wait;background-color:currentcolor;opacity:.5}.placeholder.btn::before{display:inline-block;content:""}.placeholder-xs{min-height:.6em}.placeholder-sm{min-height:.8em}.placeholder-lg{min-height:1.2em}.placeholder-glow .placeholder{animation:placeholder-glow 2s ease-in-out infinite}@keyframes placeholder-glow{50%{opacity:.2}}.placeholder-wave{mask-image:linear-gradient(130deg, #000 55%, rgba(0, 0, 0, 0.8) 75%, #000 95%);-webkit-mask-image:linear-gradient(130deg, #000 55%, rgba(0, 0, 0, 0.8) 75%, #000 95%);mask-size:200% 100%;-webkit-mask-size:200% 100%;animation:placeholder-wave 2s linear infinite}@keyframes placeholder-wave{100%{mask-position:-200% 0%;-webkit-mask-position:-200% 0%}}.clearfix::after{display:block;clear:both;content:""}.text-bg-default{color:#fff !important;background-color:RGBA(var(--bs-default-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-primary{color:#fff !important;background-color:RGBA(var(--bs-primary-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-secondary{color:#fff !important;background-color:RGBA(var(--bs-secondary-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-success{color:#fff !important;background-color:RGBA(var(--bs-success-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-info{color:#fff !important;background-color:RGBA(var(--bs-info-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-warning{color:#fff !important;background-color:RGBA(var(--bs-warning-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-danger{color:#fff !important;background-color:RGBA(var(--bs-danger-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-light{color:#000 !important;background-color:RGBA(var(--bs-light-rgb), var(--bs-bg-opacity, 1)) !important}.text-bg-dark{color:#fff !important;background-color:RGBA(var(--bs-dark-rgb), var(--bs-bg-opacity, 1)) !important}.link-default{color:RGBA(var(--bs-default-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-default-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-default:hover,.link-default:focus{color:RGBA(42, 46, 51, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(42, 46, 51, var(--bs-link-underline-opacity, 1)) !important}.link-primary{color:RGBA(var(--bs-primary-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-primary-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-primary:hover,.link-primary:focus{color:RGBA(31, 102, 182, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(31, 102, 182, var(--bs-link-underline-opacity, 1)) !important}.link-secondary{color:RGBA(var(--bs-secondary-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-secondary-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-secondary:hover,.link-secondary:focus{color:RGBA(42, 46, 51, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(42, 46, 51, var(--bs-link-underline-opacity, 1)) !important}.link-success{color:RGBA(var(--bs-success-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-success-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-success:hover,.link-success:focus{color:RGBA(50, 146, 19, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(50, 146, 19, var(--bs-link-underline-opacity, 1)) !important}.link-info{color:RGBA(var(--bs-info-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-info-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-info:hover,.link-info:focus{color:RGBA(122, 67, 150, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(122, 67, 150, var(--bs-link-underline-opacity, 1)) !important}.link-warning{color:RGBA(var(--bs-warning-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-warning-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-warning:hover,.link-warning:focus{color:RGBA(204, 94, 19, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(204, 94, 19, var(--bs-link-underline-opacity, 1)) !important}.link-danger{color:RGBA(var(--bs-danger-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-danger-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-danger:hover,.link-danger:focus{color:RGBA(204, 0, 46, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(204, 0, 46, var(--bs-link-underline-opacity, 1)) !important}.link-light{color:RGBA(var(--bs-light-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-light-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-light:hover,.link-light:focus{color:RGBA(249, 250, 251, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(249, 250, 251, var(--bs-link-underline-opacity, 1)) !important}.link-dark{color:RGBA(var(--bs-dark-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-dark-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-dark:hover,.link-dark:focus{color:RGBA(42, 46, 51, var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(42, 46, 51, var(--bs-link-underline-opacity, 1)) !important}.link-body-emphasis{color:RGBA(var(--bs-emphasis-color-rgb), var(--bs-link-opacity, 1)) !important;text-decoration-color:RGBA(var(--bs-emphasis-color-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-body-emphasis:hover,.link-body-emphasis:focus{color:RGBA(var(--bs-emphasis-color-rgb), var(--bs-link-opacity, 0.75)) !important;text-decoration-color:RGBA(var(--bs-emphasis-color-rgb), var(--bs-link-underline-opacity, 0.75)) !important}.focus-ring:focus{outline:0;box-shadow:var(--bs-focus-ring-x, 0) var(--bs-focus-ring-y, 0) var(--bs-focus-ring-blur, 0) var(--bs-focus-ring-width) var(--bs-focus-ring-color)}.icon-link{display:inline-flex;gap:.375rem;align-items:center;-webkit-align-items:center;text-decoration-color:rgba(var(--bs-link-color-rgb), var(--bs-link-opacity, 0.5));text-underline-offset:.25em;backface-visibility:hidden;-webkit-backface-visibility:hidden;-moz-backface-visibility:hidden;-ms-backface-visibility:hidden;-o-backface-visibility:hidden}.icon-link>.bi{flex-shrink:0;-webkit-flex-shrink:0;width:1em;height:1em;fill:currentcolor;transition:.2s ease-in-out transform}@media(prefers-reduced-motion: reduce){.icon-link>.bi{transition:none}}.icon-link-hover:hover>.bi,.icon-link-hover:focus-visible>.bi{transform:var(--bs-icon-link-transform, translate3d(0.25em, 0, 0))}.ratio{position:relative;width:100%}.ratio::before{display:block;padding-top:var(--bs-aspect-ratio);content:""}.ratio>*{position:absolute;top:0;left:0;width:100%;height:100%}.ratio-1x1{--bs-aspect-ratio: 100%}.ratio-4x3{--bs-aspect-ratio: 75%}.ratio-16x9{--bs-aspect-ratio: 56.25%}.ratio-21x9{--bs-aspect-ratio: 42.8571428571%}.fixed-top{position:fixed;top:0;right:0;left:0;z-index:1030}.fixed-bottom{position:fixed;right:0;bottom:0;left:0;z-index:1030}.sticky-top{position:sticky;top:0;z-index:1020}.sticky-bottom{position:sticky;bottom:0;z-index:1020}@media(min-width: 576px){.sticky-sm-top{position:sticky;top:0;z-index:1020}.sticky-sm-bottom{position:sticky;bottom:0;z-index:1020}}@media(min-width: 768px){.sticky-md-top{position:sticky;top:0;z-index:1020}.sticky-md-bottom{position:sticky;bottom:0;z-index:1020}}@media(min-width: 992px){.sticky-lg-top{position:sticky;top:0;z-index:1020}.sticky-lg-bottom{position:sticky;bottom:0;z-index:1020}}@media(min-width: 1200px){.sticky-xl-top{position:sticky;top:0;z-index:1020}.sticky-xl-bottom{position:sticky;bottom:0;z-index:1020}}@media(min-width: 1400px){.sticky-xxl-top{position:sticky;top:0;z-index:1020}.sticky-xxl-bottom{position:sticky;bottom:0;z-index:1020}}.hstack{display:flex;display:-webkit-flex;flex-direction:row;-webkit-flex-direction:row;align-items:center;-webkit-align-items:center;align-self:stretch;-webkit-align-self:stretch}.vstack{display:flex;display:-webkit-flex;flex:1 1 auto;-webkit-flex:1 1 auto;flex-direction:column;-webkit-flex-direction:column;align-self:stretch;-webkit-align-self:stretch}.visually-hidden,.visually-hidden-focusable:not(:focus):not(:focus-within){width:1px !important;height:1px !important;padding:0 !important;margin:-1px !important;overflow:hidden !important;clip:rect(0, 0, 0, 0) !important;white-space:nowrap !important;border:0 !important}.visually-hidden:not(caption),.visually-hidden-focusable:not(:focus):not(:focus-within):not(caption){position:absolute !important}.stretched-link::after{position:absolute;top:0;right:0;bottom:0;left:0;z-index:1;content:""}.text-truncate{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.vr{display:inline-block;align-self:stretch;-webkit-align-self:stretch;width:1px;min-height:1em;background-color:currentcolor;opacity:.25}.align-baseline{vertical-align:baseline !important}.align-top{vertical-align:top !important}.align-middle{vertical-align:middle !important}.align-bottom{vertical-align:bottom !important}.align-text-bottom{vertical-align:text-bottom !important}.align-text-top{vertical-align:text-top !important}.float-start{float:left !important}.float-end{float:right !important}.float-none{float:none !important}.object-fit-contain{object-fit:contain !important}.object-fit-cover{object-fit:cover !important}.object-fit-fill{object-fit:fill !important}.object-fit-scale{object-fit:scale-down !important}.object-fit-none{object-fit:none !important}.opacity-0{opacity:0 !important}.opacity-25{opacity:.25 !important}.opacity-50{opacity:.5 !important}.opacity-75{opacity:.75 !important}.opacity-100{opacity:1 !important}.overflow-auto{overflow:auto !important}.overflow-hidden{overflow:hidden !important}.overflow-visible{overflow:visible !important}.overflow-scroll{overflow:scroll !important}.overflow-x-auto{overflow-x:auto !important}.overflow-x-hidden{overflow-x:hidden !important}.overflow-x-visible{overflow-x:visible !important}.overflow-x-scroll{overflow-x:scroll !important}.overflow-y-auto{overflow-y:auto !important}.overflow-y-hidden{overflow-y:hidden !important}.overflow-y-visible{overflow-y:visible !important}.overflow-y-scroll{overflow-y:scroll !important}.d-inline{display:inline !important}.d-inline-block{display:inline-block !important}.d-block{display:block !important}.d-grid{display:grid !important}.d-inline-grid{display:inline-grid !important}.d-table{display:table !important}.d-table-row{display:table-row !important}.d-table-cell{display:table-cell !important}.d-flex{display:flex !important}.d-inline-flex{display:inline-flex !important}.d-none{display:none !important}.shadow{box-shadow:0 .5rem 1rem rgba(0,0,0,.15) !important}.shadow-sm{box-shadow:0 .125rem .25rem rgba(0,0,0,.075) !important}.shadow-lg{box-shadow:0 1rem 3rem rgba(0,0,0,.175) !important}.shadow-none{box-shadow:none !important}.focus-ring-default{--bs-focus-ring-color: rgba(var(--bs-default-rgb), var(--bs-focus-ring-opacity))}.focus-ring-primary{--bs-focus-ring-color: rgba(var(--bs-primary-rgb), var(--bs-focus-ring-opacity))}.focus-ring-secondary{--bs-focus-ring-color: rgba(var(--bs-secondary-rgb), var(--bs-focus-ring-opacity))}.focus-ring-success{--bs-focus-ring-color: rgba(var(--bs-success-rgb), var(--bs-focus-ring-opacity))}.focus-ring-info{--bs-focus-ring-color: rgba(var(--bs-info-rgb), var(--bs-focus-ring-opacity))}.focus-ring-warning{--bs-focus-ring-color: rgba(var(--bs-warning-rgb), var(--bs-focus-ring-opacity))}.focus-ring-danger{--bs-focus-ring-color: rgba(var(--bs-danger-rgb), var(--bs-focus-ring-opacity))}.focus-ring-light{--bs-focus-ring-color: rgba(var(--bs-light-rgb), var(--bs-focus-ring-opacity))}.focus-ring-dark{--bs-focus-ring-color: rgba(var(--bs-dark-rgb), var(--bs-focus-ring-opacity))}.position-static{position:static !important}.position-relative{position:relative !important}.position-absolute{position:absolute !important}.position-fixed{position:fixed !important}.position-sticky{position:sticky !important}.top-0{top:0 !important}.top-50{top:50% !important}.top-100{top:100% !important}.bottom-0{bottom:0 !important}.bottom-50{bottom:50% !important}.bottom-100{bottom:100% !important}.start-0{left:0 !important}.start-50{left:50% !important}.start-100{left:100% !important}.end-0{right:0 !important}.end-50{right:50% !important}.end-100{right:100% !important}.translate-middle{transform:translate(-50%, -50%) !important}.translate-middle-x{transform:translateX(-50%) !important}.translate-middle-y{transform:translateY(-50%) !important}.border{border:var(--bs-border-width) var(--bs-border-style) var(--bs-border-color) !important}.border-0{border:0 !important}.border-top{border-top:var(--bs-border-width) var(--bs-border-style) var(--bs-border-color) !important}.border-top-0{border-top:0 !important}.border-end{border-right:var(--bs-border-width) var(--bs-border-style) var(--bs-border-color) !important}.border-end-0{border-right:0 !important}.border-bottom{border-bottom:var(--bs-border-width) var(--bs-border-style) var(--bs-border-color) !important}.border-bottom-0{border-bottom:0 !important}.border-start{border-left:var(--bs-border-width) var(--bs-border-style) var(--bs-border-color) !important}.border-start-0{border-left:0 !important}.border-default{--bs-border-opacity: 1;border-color:rgba(var(--bs-default-rgb), var(--bs-border-opacity)) !important}.border-primary{--bs-border-opacity: 1;border-color:rgba(var(--bs-primary-rgb), var(--bs-border-opacity)) !important}.border-secondary{--bs-border-opacity: 1;border-color:rgba(var(--bs-secondary-rgb), var(--bs-border-opacity)) !important}.border-success{--bs-border-opacity: 1;border-color:rgba(var(--bs-success-rgb), var(--bs-border-opacity)) !important}.border-info{--bs-border-opacity: 1;border-color:rgba(var(--bs-info-rgb), var(--bs-border-opacity)) !important}.border-warning{--bs-border-opacity: 1;border-color:rgba(var(--bs-warning-rgb), var(--bs-border-opacity)) !important}.border-danger{--bs-border-opacity: 1;border-color:rgba(var(--bs-danger-rgb), var(--bs-border-opacity)) !important}.border-light{--bs-border-opacity: 1;border-color:rgba(var(--bs-light-rgb), var(--bs-border-opacity)) !important}.border-dark{--bs-border-opacity: 1;border-color:rgba(var(--bs-dark-rgb), var(--bs-border-opacity)) !important}.border-black{--bs-border-opacity: 1;border-color:rgba(var(--bs-black-rgb), var(--bs-border-opacity)) !important}.border-white{--bs-border-opacity: 1;border-color:rgba(var(--bs-white-rgb), var(--bs-border-opacity)) !important}.border-primary-subtle{border-color:var(--bs-primary-border-subtle) !important}.border-secondary-subtle{border-color:var(--bs-secondary-border-subtle) !important}.border-success-subtle{border-color:var(--bs-success-border-subtle) !important}.border-info-subtle{border-color:var(--bs-info-border-subtle) !important}.border-warning-subtle{border-color:var(--bs-warning-border-subtle) !important}.border-danger-subtle{border-color:var(--bs-danger-border-subtle) !important}.border-light-subtle{border-color:var(--bs-light-border-subtle) !important}.border-dark-subtle{border-color:var(--bs-dark-border-subtle) !important}.border-1{border-width:1px !important}.border-2{border-width:2px !important}.border-3{border-width:3px !important}.border-4{border-width:4px !important}.border-5{border-width:5px !important}.border-opacity-10{--bs-border-opacity: 0.1}.border-opacity-25{--bs-border-opacity: 0.25}.border-opacity-50{--bs-border-opacity: 0.5}.border-opacity-75{--bs-border-opacity: 0.75}.border-opacity-100{--bs-border-opacity: 1}.w-25{width:25% !important}.w-50{width:50% !important}.w-75{width:75% !important}.w-100{width:100% !important}.w-auto{width:auto !important}.mw-100{max-width:100% !important}.vw-100{width:100vw !important}.min-vw-100{min-width:100vw !important}.h-25{height:25% !important}.h-50{height:50% !important}.h-75{height:75% !important}.h-100{height:100% !important}.h-auto{height:auto !important}.mh-100{max-height:100% !important}.vh-100{height:100vh !important}.min-vh-100{min-height:100vh !important}.flex-fill{flex:1 1 auto !important}.flex-row{flex-direction:row !important}.flex-column{flex-direction:column !important}.flex-row-reverse{flex-direction:row-reverse !important}.flex-column-reverse{flex-direction:column-reverse !important}.flex-grow-0{flex-grow:0 !important}.flex-grow-1{flex-grow:1 !important}.flex-shrink-0{flex-shrink:0 !important}.flex-shrink-1{flex-shrink:1 !important}.flex-wrap{flex-wrap:wrap !important}.flex-nowrap{flex-wrap:nowrap !important}.flex-wrap-reverse{flex-wrap:wrap-reverse !important}.justify-content-start{justify-content:flex-start !important}.justify-content-end{justify-content:flex-end !important}.justify-content-center{justify-content:center !important}.justify-content-between{justify-content:space-between !important}.justify-content-around{justify-content:space-around !important}.justify-content-evenly{justify-content:space-evenly !important}.align-items-start{align-items:flex-start !important}.align-items-end{align-items:flex-end !important}.align-items-center{align-items:center !important}.align-items-baseline{align-items:baseline !important}.align-items-stretch{align-items:stretch !important}.align-content-start{align-content:flex-start !important}.align-content-end{align-content:flex-end !important}.align-content-center{align-content:center !important}.align-content-between{align-content:space-between !important}.align-content-around{align-content:space-around !important}.align-content-stretch{align-content:stretch !important}.align-self-auto{align-self:auto !important}.align-self-start{align-self:flex-start !important}.align-self-end{align-self:flex-end !important}.align-self-center{align-self:center !important}.align-self-baseline{align-self:baseline !important}.align-self-stretch{align-self:stretch !important}.order-first{order:-1 !important}.order-0{order:0 !important}.order-1{order:1 !important}.order-2{order:2 !important}.order-3{order:3 !important}.order-4{order:4 !important}.order-5{order:5 !important}.order-last{order:6 !important}.m-0{margin:0 !important}.m-1{margin:.25rem !important}.m-2{margin:.5rem !important}.m-3{margin:1rem !important}.m-4{margin:1.5rem !important}.m-5{margin:3rem !important}.m-auto{margin:auto !important}.mx-0{margin-right:0 !important;margin-left:0 !important}.mx-1{margin-right:.25rem !important;margin-left:.25rem !important}.mx-2{margin-right:.5rem !important;margin-left:.5rem !important}.mx-3{margin-right:1rem !important;margin-left:1rem !important}.mx-4{margin-right:1.5rem !important;margin-left:1.5rem !important}.mx-5{margin-right:3rem !important;margin-left:3rem !important}.mx-auto{margin-right:auto !important;margin-left:auto !important}.my-0{margin-top:0 !important;margin-bottom:0 !important}.my-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.my-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.my-3{margin-top:1rem !important;margin-bottom:1rem !important}.my-4{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.my-5{margin-top:3rem !important;margin-bottom:3rem !important}.my-auto{margin-top:auto !important;margin-bottom:auto !important}.mt-0{margin-top:0 !important}.mt-1{margin-top:.25rem !important}.mt-2{margin-top:.5rem !important}.mt-3{margin-top:1rem !important}.mt-4{margin-top:1.5rem !important}.mt-5{margin-top:3rem !important}.mt-auto{margin-top:auto !important}.me-0{margin-right:0 !important}.me-1{margin-right:.25rem !important}.me-2{margin-right:.5rem !important}.me-3{margin-right:1rem !important}.me-4{margin-right:1.5rem !important}.me-5{margin-right:3rem !important}.me-auto{margin-right:auto !important}.mb-0{margin-bottom:0 !important}.mb-1{margin-bottom:.25rem !important}.mb-2{margin-bottom:.5rem !important}.mb-3{margin-bottom:1rem !important}.mb-4{margin-bottom:1.5rem !important}.mb-5{margin-bottom:3rem !important}.mb-auto{margin-bottom:auto !important}.ms-0{margin-left:0 !important}.ms-1{margin-left:.25rem !important}.ms-2{margin-left:.5rem !important}.ms-3{margin-left:1rem !important}.ms-4{margin-left:1.5rem !important}.ms-5{margin-left:3rem !important}.ms-auto{margin-left:auto !important}.p-0{padding:0 !important}.p-1{padding:.25rem !important}.p-2{padding:.5rem !important}.p-3{padding:1rem !important}.p-4{padding:1.5rem !important}.p-5{padding:3rem !important}.px-0{padding-right:0 !important;padding-left:0 !important}.px-1{padding-right:.25rem !important;padding-left:.25rem !important}.px-2{padding-right:.5rem !important;padding-left:.5rem !important}.px-3{padding-right:1rem !important;padding-left:1rem !important}.px-4{padding-right:1.5rem !important;padding-left:1.5rem !important}.px-5{padding-right:3rem !important;padding-left:3rem !important}.py-0{padding-top:0 !important;padding-bottom:0 !important}.py-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.py-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.py-3{padding-top:1rem !important;padding-bottom:1rem !important}.py-4{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.py-5{padding-top:3rem !important;padding-bottom:3rem !important}.pt-0{padding-top:0 !important}.pt-1{padding-top:.25rem !important}.pt-2{padding-top:.5rem !important}.pt-3{padding-top:1rem !important}.pt-4{padding-top:1.5rem !important}.pt-5{padding-top:3rem !important}.pe-0{padding-right:0 !important}.pe-1{padding-right:.25rem !important}.pe-2{padding-right:.5rem !important}.pe-3{padding-right:1rem !important}.pe-4{padding-right:1.5rem !important}.pe-5{padding-right:3rem !important}.pb-0{padding-bottom:0 !important}.pb-1{padding-bottom:.25rem !important}.pb-2{padding-bottom:.5rem !important}.pb-3{padding-bottom:1rem !important}.pb-4{padding-bottom:1.5rem !important}.pb-5{padding-bottom:3rem !important}.ps-0{padding-left:0 !important}.ps-1{padding-left:.25rem !important}.ps-2{padding-left:.5rem !important}.ps-3{padding-left:1rem !important}.ps-4{padding-left:1.5rem !important}.ps-5{padding-left:3rem !important}.gap-0{gap:0 !important}.gap-1{gap:.25rem !important}.gap-2{gap:.5rem !important}.gap-3{gap:1rem !important}.gap-4{gap:1.5rem !important}.gap-5{gap:3rem !important}.row-gap-0{row-gap:0 !important}.row-gap-1{row-gap:.25rem !important}.row-gap-2{row-gap:.5rem !important}.row-gap-3{row-gap:1rem !important}.row-gap-4{row-gap:1.5rem !important}.row-gap-5{row-gap:3rem !important}.column-gap-0{column-gap:0 !important}.column-gap-1{column-gap:.25rem !important}.column-gap-2{column-gap:.5rem !important}.column-gap-3{column-gap:1rem !important}.column-gap-4{column-gap:1.5rem !important}.column-gap-5{column-gap:3rem !important}.font-monospace{font-family:var(--bs-font-monospace) !important}.fs-1{font-size:calc(1.325rem + 0.9vw) !important}.fs-2{font-size:calc(1.29rem + 0.48vw) !important}.fs-3{font-size:calc(1.27rem + 0.24vw) !important}.fs-4{font-size:1.25rem !important}.fs-5{font-size:1.1rem !important}.fs-6{font-size:1rem !important}.fst-italic{font-style:italic !important}.fst-normal{font-style:normal !important}.fw-lighter{font-weight:lighter !important}.fw-light{font-weight:300 !important}.fw-normal{font-weight:400 !important}.fw-medium{font-weight:500 !important}.fw-semibold{font-weight:600 !important}.fw-bold{font-weight:700 !important}.fw-bolder{font-weight:bolder !important}.lh-1{line-height:1 !important}.lh-sm{line-height:1.25 !important}.lh-base{line-height:1.5 !important}.lh-lg{line-height:2 !important}.text-start{text-align:left !important}.text-end{text-align:right !important}.text-center{text-align:center !important}.text-decoration-none{text-decoration:none !important}.text-decoration-underline{text-decoration:underline !important}.text-decoration-line-through{text-decoration:line-through !important}.text-lowercase{text-transform:lowercase !important}.text-uppercase{text-transform:uppercase !important}.text-capitalize{text-transform:capitalize !important}.text-wrap{white-space:normal !important}.text-nowrap{white-space:nowrap !important}.text-break{word-wrap:break-word !important;word-break:break-word !important}.text-default{--bs-text-opacity: 1;color:rgba(var(--bs-default-rgb), var(--bs-text-opacity)) !important}.text-primary{--bs-text-opacity: 1;color:rgba(var(--bs-primary-rgb), var(--bs-text-opacity)) !important}.text-secondary{--bs-text-opacity: 1;color:rgba(var(--bs-secondary-rgb), var(--bs-text-opacity)) !important}.text-success{--bs-text-opacity: 1;color:rgba(var(--bs-success-rgb), var(--bs-text-opacity)) !important}.text-info{--bs-text-opacity: 1;color:rgba(var(--bs-info-rgb), var(--bs-text-opacity)) !important}.text-warning{--bs-text-opacity: 1;color:rgba(var(--bs-warning-rgb), var(--bs-text-opacity)) !important}.text-danger{--bs-text-opacity: 1;color:rgba(var(--bs-danger-rgb), var(--bs-text-opacity)) !important}.text-light{--bs-text-opacity: 1;color:rgba(var(--bs-light-rgb), var(--bs-text-opacity)) !important}.text-dark{--bs-text-opacity: 1;color:rgba(var(--bs-dark-rgb), var(--bs-text-opacity)) !important}.text-black{--bs-text-opacity: 1;color:rgba(var(--bs-black-rgb), var(--bs-text-opacity)) !important}.text-white{--bs-text-opacity: 1;color:rgba(var(--bs-white-rgb), var(--bs-text-opacity)) !important}.text-body{--bs-text-opacity: 1;color:rgba(var(--bs-body-color-rgb), var(--bs-text-opacity)) !important}.text-muted{--bs-text-opacity: 1;color:var(--bs-secondary-color) !important}.text-black-50{--bs-text-opacity: 1;color:rgba(0,0,0,.5) !important}.text-white-50{--bs-text-opacity: 1;color:rgba(255,255,255,.5) !important}.text-body-secondary{--bs-text-opacity: 1;color:var(--bs-secondary-color) !important}.text-body-tertiary{--bs-text-opacity: 1;color:var(--bs-tertiary-color) !important}.text-body-emphasis{--bs-text-opacity: 1;color:var(--bs-emphasis-color) !important}.text-reset{--bs-text-opacity: 1;color:inherit !important}.text-opacity-25{--bs-text-opacity: 0.25}.text-opacity-50{--bs-text-opacity: 0.5}.text-opacity-75{--bs-text-opacity: 0.75}.text-opacity-100{--bs-text-opacity: 1}.text-primary-emphasis{color:var(--bs-primary-text-emphasis) !important}.text-secondary-emphasis{color:var(--bs-secondary-text-emphasis) !important}.text-success-emphasis{color:var(--bs-success-text-emphasis) !important}.text-info-emphasis{color:var(--bs-info-text-emphasis) !important}.text-warning-emphasis{color:var(--bs-warning-text-emphasis) !important}.text-danger-emphasis{color:var(--bs-danger-text-emphasis) !important}.text-light-emphasis{color:var(--bs-light-text-emphasis) !important}.text-dark-emphasis{color:var(--bs-dark-text-emphasis) !important}.link-opacity-10{--bs-link-opacity: 0.1}.link-opacity-10-hover:hover{--bs-link-opacity: 0.1}.link-opacity-25{--bs-link-opacity: 0.25}.link-opacity-25-hover:hover{--bs-link-opacity: 0.25}.link-opacity-50{--bs-link-opacity: 0.5}.link-opacity-50-hover:hover{--bs-link-opacity: 0.5}.link-opacity-75{--bs-link-opacity: 0.75}.link-opacity-75-hover:hover{--bs-link-opacity: 0.75}.link-opacity-100{--bs-link-opacity: 1}.link-opacity-100-hover:hover{--bs-link-opacity: 1}.link-offset-1{text-underline-offset:.125em !important}.link-offset-1-hover:hover{text-underline-offset:.125em !important}.link-offset-2{text-underline-offset:.25em !important}.link-offset-2-hover:hover{text-underline-offset:.25em !important}.link-offset-3{text-underline-offset:.375em !important}.link-offset-3-hover:hover{text-underline-offset:.375em !important}.link-underline-default{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-default-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-primary{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-primary-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-secondary{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-secondary-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-success{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-success-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-info{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-info-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-warning{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-warning-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-danger{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-danger-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-light{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-light-rgb), var(--bs-link-underline-opacity)) !important}.link-underline-dark{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-dark-rgb), var(--bs-link-underline-opacity)) !important}.link-underline{--bs-link-underline-opacity: 1;text-decoration-color:rgba(var(--bs-link-color-rgb), var(--bs-link-underline-opacity, 1)) !important}.link-underline-opacity-0{--bs-link-underline-opacity: 0}.link-underline-opacity-0-hover:hover{--bs-link-underline-opacity: 0}.link-underline-opacity-10{--bs-link-underline-opacity: 0.1}.link-underline-opacity-10-hover:hover{--bs-link-underline-opacity: 0.1}.link-underline-opacity-25{--bs-link-underline-opacity: 0.25}.link-underline-opacity-25-hover:hover{--bs-link-underline-opacity: 0.25}.link-underline-opacity-50{--bs-link-underline-opacity: 0.5}.link-underline-opacity-50-hover:hover{--bs-link-underline-opacity: 0.5}.link-underline-opacity-75{--bs-link-underline-opacity: 0.75}.link-underline-opacity-75-hover:hover{--bs-link-underline-opacity: 0.75}.link-underline-opacity-100{--bs-link-underline-opacity: 1}.link-underline-opacity-100-hover:hover{--bs-link-underline-opacity: 1}.bg-default{--bs-bg-opacity: 1;background-color:rgba(var(--bs-default-rgb), var(--bs-bg-opacity)) !important}.bg-primary{--bs-bg-opacity: 1;background-color:rgba(var(--bs-primary-rgb), var(--bs-bg-opacity)) !important}.bg-secondary{--bs-bg-opacity: 1;background-color:rgba(var(--bs-secondary-rgb), var(--bs-bg-opacity)) !important}.bg-success{--bs-bg-opacity: 1;background-color:rgba(var(--bs-success-rgb), var(--bs-bg-opacity)) !important}.bg-info{--bs-bg-opacity: 1;background-color:rgba(var(--bs-info-rgb), var(--bs-bg-opacity)) !important}.bg-warning{--bs-bg-opacity: 1;background-color:rgba(var(--bs-warning-rgb), var(--bs-bg-opacity)) !important}.bg-danger{--bs-bg-opacity: 1;background-color:rgba(var(--bs-danger-rgb), var(--bs-bg-opacity)) !important}.bg-light{--bs-bg-opacity: 1;background-color:rgba(var(--bs-light-rgb), var(--bs-bg-opacity)) !important}.bg-dark{--bs-bg-opacity: 1;background-color:rgba(var(--bs-dark-rgb), var(--bs-bg-opacity)) !important}.bg-black{--bs-bg-opacity: 1;background-color:rgba(var(--bs-black-rgb), var(--bs-bg-opacity)) !important}.bg-white{--bs-bg-opacity: 1;background-color:rgba(var(--bs-white-rgb), var(--bs-bg-opacity)) !important}.bg-body{--bs-bg-opacity: 1;background-color:rgba(var(--bs-body-bg-rgb), var(--bs-bg-opacity)) !important}.bg-transparent{--bs-bg-opacity: 1;background-color:rgba(0,0,0,0) !important}.bg-body-secondary{--bs-bg-opacity: 1;background-color:rgba(var(--bs-secondary-bg-rgb), var(--bs-bg-opacity)) !important}.bg-body-tertiary{--bs-bg-opacity: 1;background-color:rgba(var(--bs-tertiary-bg-rgb), var(--bs-bg-opacity)) !important}.bg-opacity-10{--bs-bg-opacity: 0.1}.bg-opacity-25{--bs-bg-opacity: 0.25}.bg-opacity-50{--bs-bg-opacity: 0.5}.bg-opacity-75{--bs-bg-opacity: 0.75}.bg-opacity-100{--bs-bg-opacity: 1}.bg-primary-subtle{background-color:var(--bs-primary-bg-subtle) !important}.bg-secondary-subtle{background-color:var(--bs-secondary-bg-subtle) !important}.bg-success-subtle{background-color:var(--bs-success-bg-subtle) !important}.bg-info-subtle{background-color:var(--bs-info-bg-subtle) !important}.bg-warning-subtle{background-color:var(--bs-warning-bg-subtle) !important}.bg-danger-subtle{background-color:var(--bs-danger-bg-subtle) !important}.bg-light-subtle{background-color:var(--bs-light-bg-subtle) !important}.bg-dark-subtle{background-color:var(--bs-dark-bg-subtle) !important}.bg-gradient{background-image:var(--bs-gradient) !important}.user-select-all{user-select:all !important}.user-select-auto{user-select:auto !important}.user-select-none{user-select:none !important}.pe-none{pointer-events:none !important}.pe-auto{pointer-events:auto !important}.rounded{border-radius:var(--bs-border-radius) !important}.rounded-0{border-radius:0 !important}.rounded-1{border-radius:var(--bs-border-radius-sm) !important}.rounded-2{border-radius:var(--bs-border-radius) !important}.rounded-3{border-radius:var(--bs-border-radius-lg) !important}.rounded-4{border-radius:var(--bs-border-radius-xl) !important}.rounded-5{border-radius:var(--bs-border-radius-xxl) !important}.rounded-circle{border-radius:50% !important}.rounded-pill{border-radius:var(--bs-border-radius-pill) !important}.rounded-top{border-top-left-radius:var(--bs-border-radius) !important;border-top-right-radius:var(--bs-border-radius) !important}.rounded-top-0{border-top-left-radius:0 !important;border-top-right-radius:0 !important}.rounded-top-1{border-top-left-radius:var(--bs-border-radius-sm) !important;border-top-right-radius:var(--bs-border-radius-sm) !important}.rounded-top-2{border-top-left-radius:var(--bs-border-radius) !important;border-top-right-radius:var(--bs-border-radius) !important}.rounded-top-3{border-top-left-radius:var(--bs-border-radius-lg) !important;border-top-right-radius:var(--bs-border-radius-lg) !important}.rounded-top-4{border-top-left-radius:var(--bs-border-radius-xl) !important;border-top-right-radius:var(--bs-border-radius-xl) !important}.rounded-top-5{border-top-left-radius:var(--bs-border-radius-xxl) !important;border-top-right-radius:var(--bs-border-radius-xxl) !important}.rounded-top-circle{border-top-left-radius:50% !important;border-top-right-radius:50% !important}.rounded-top-pill{border-top-left-radius:var(--bs-border-radius-pill) !important;border-top-right-radius:var(--bs-border-radius-pill) !important}.rounded-end{border-top-right-radius:var(--bs-border-radius) !important;border-bottom-right-radius:var(--bs-border-radius) !important}.rounded-end-0{border-top-right-radius:0 !important;border-bottom-right-radius:0 !important}.rounded-end-1{border-top-right-radius:var(--bs-border-radius-sm) !important;border-bottom-right-radius:var(--bs-border-radius-sm) !important}.rounded-end-2{border-top-right-radius:var(--bs-border-radius) !important;border-bottom-right-radius:var(--bs-border-radius) !important}.rounded-end-3{border-top-right-radius:var(--bs-border-radius-lg) !important;border-bottom-right-radius:var(--bs-border-radius-lg) !important}.rounded-end-4{border-top-right-radius:var(--bs-border-radius-xl) !important;border-bottom-right-radius:var(--bs-border-radius-xl) !important}.rounded-end-5{border-top-right-radius:var(--bs-border-radius-xxl) !important;border-bottom-right-radius:var(--bs-border-radius-xxl) !important}.rounded-end-circle{border-top-right-radius:50% !important;border-bottom-right-radius:50% !important}.rounded-end-pill{border-top-right-radius:var(--bs-border-radius-pill) !important;border-bottom-right-radius:var(--bs-border-radius-pill) !important}.rounded-bottom{border-bottom-right-radius:var(--bs-border-radius) !important;border-bottom-left-radius:var(--bs-border-radius) !important}.rounded-bottom-0{border-bottom-right-radius:0 !important;border-bottom-left-radius:0 !important}.rounded-bottom-1{border-bottom-right-radius:var(--bs-border-radius-sm) !important;border-bottom-left-radius:var(--bs-border-radius-sm) !important}.rounded-bottom-2{border-bottom-right-radius:var(--bs-border-radius) !important;border-bottom-left-radius:var(--bs-border-radius) !important}.rounded-bottom-3{border-bottom-right-radius:var(--bs-border-radius-lg) !important;border-bottom-left-radius:var(--bs-border-radius-lg) !important}.rounded-bottom-4{border-bottom-right-radius:var(--bs-border-radius-xl) !important;border-bottom-left-radius:var(--bs-border-radius-xl) !important}.rounded-bottom-5{border-bottom-right-radius:var(--bs-border-radius-xxl) !important;border-bottom-left-radius:var(--bs-border-radius-xxl) !important}.rounded-bottom-circle{border-bottom-right-radius:50% !important;border-bottom-left-radius:50% !important}.rounded-bottom-pill{border-bottom-right-radius:var(--bs-border-radius-pill) !important;border-bottom-left-radius:var(--bs-border-radius-pill) !important}.rounded-start{border-bottom-left-radius:var(--bs-border-radius) !important;border-top-left-radius:var(--bs-border-radius) !important}.rounded-start-0{border-bottom-left-radius:0 !important;border-top-left-radius:0 !important}.rounded-start-1{border-bottom-left-radius:var(--bs-border-radius-sm) !important;border-top-left-radius:var(--bs-border-radius-sm) !important}.rounded-start-2{border-bottom-left-radius:var(--bs-border-radius) !important;border-top-left-radius:var(--bs-border-radius) !important}.rounded-start-3{border-bottom-left-radius:var(--bs-border-radius-lg) !important;border-top-left-radius:var(--bs-border-radius-lg) !important}.rounded-start-4{border-bottom-left-radius:var(--bs-border-radius-xl) !important;border-top-left-radius:var(--bs-border-radius-xl) !important}.rounded-start-5{border-bottom-left-radius:var(--bs-border-radius-xxl) !important;border-top-left-radius:var(--bs-border-radius-xxl) !important}.rounded-start-circle{border-bottom-left-radius:50% !important;border-top-left-radius:50% !important}.rounded-start-pill{border-bottom-left-radius:var(--bs-border-radius-pill) !important;border-top-left-radius:var(--bs-border-radius-pill) !important}.visible{visibility:visible !important}.invisible{visibility:hidden !important}.z-n1{z-index:-1 !important}.z-0{z-index:0 !important}.z-1{z-index:1 !important}.z-2{z-index:2 !important}.z-3{z-index:3 !important}@media(min-width: 576px){.float-sm-start{float:left !important}.float-sm-end{float:right !important}.float-sm-none{float:none !important}.object-fit-sm-contain{object-fit:contain !important}.object-fit-sm-cover{object-fit:cover !important}.object-fit-sm-fill{object-fit:fill !important}.object-fit-sm-scale{object-fit:scale-down !important}.object-fit-sm-none{object-fit:none !important}.d-sm-inline{display:inline !important}.d-sm-inline-block{display:inline-block !important}.d-sm-block{display:block !important}.d-sm-grid{display:grid !important}.d-sm-inline-grid{display:inline-grid !important}.d-sm-table{display:table !important}.d-sm-table-row{display:table-row !important}.d-sm-table-cell{display:table-cell !important}.d-sm-flex{display:flex !important}.d-sm-inline-flex{display:inline-flex !important}.d-sm-none{display:none !important}.flex-sm-fill{flex:1 1 auto !important}.flex-sm-row{flex-direction:row !important}.flex-sm-column{flex-direction:column !important}.flex-sm-row-reverse{flex-direction:row-reverse !important}.flex-sm-column-reverse{flex-direction:column-reverse !important}.flex-sm-grow-0{flex-grow:0 !important}.flex-sm-grow-1{flex-grow:1 !important}.flex-sm-shrink-0{flex-shrink:0 !important}.flex-sm-shrink-1{flex-shrink:1 !important}.flex-sm-wrap{flex-wrap:wrap !important}.flex-sm-nowrap{flex-wrap:nowrap !important}.flex-sm-wrap-reverse{flex-wrap:wrap-reverse !important}.justify-content-sm-start{justify-content:flex-start !important}.justify-content-sm-end{justify-content:flex-end !important}.justify-content-sm-center{justify-content:center !important}.justify-content-sm-between{justify-content:space-between !important}.justify-content-sm-around{justify-content:space-around !important}.justify-content-sm-evenly{justify-content:space-evenly !important}.align-items-sm-start{align-items:flex-start !important}.align-items-sm-end{align-items:flex-end !important}.align-items-sm-center{align-items:center !important}.align-items-sm-baseline{align-items:baseline !important}.align-items-sm-stretch{align-items:stretch !important}.align-content-sm-start{align-content:flex-start !important}.align-content-sm-end{align-content:flex-end !important}.align-content-sm-center{align-content:center !important}.align-content-sm-between{align-content:space-between !important}.align-content-sm-around{align-content:space-around !important}.align-content-sm-stretch{align-content:stretch !important}.align-self-sm-auto{align-self:auto !important}.align-self-sm-start{align-self:flex-start !important}.align-self-sm-end{align-self:flex-end !important}.align-self-sm-center{align-self:center !important}.align-self-sm-baseline{align-self:baseline !important}.align-self-sm-stretch{align-self:stretch !important}.order-sm-first{order:-1 !important}.order-sm-0{order:0 !important}.order-sm-1{order:1 !important}.order-sm-2{order:2 !important}.order-sm-3{order:3 !important}.order-sm-4{order:4 !important}.order-sm-5{order:5 !important}.order-sm-last{order:6 !important}.m-sm-0{margin:0 !important}.m-sm-1{margin:.25rem !important}.m-sm-2{margin:.5rem !important}.m-sm-3{margin:1rem !important}.m-sm-4{margin:1.5rem !important}.m-sm-5{margin:3rem !important}.m-sm-auto{margin:auto !important}.mx-sm-0{margin-right:0 !important;margin-left:0 !important}.mx-sm-1{margin-right:.25rem !important;margin-left:.25rem !important}.mx-sm-2{margin-right:.5rem !important;margin-left:.5rem !important}.mx-sm-3{margin-right:1rem !important;margin-left:1rem !important}.mx-sm-4{margin-right:1.5rem !important;margin-left:1.5rem !important}.mx-sm-5{margin-right:3rem !important;margin-left:3rem !important}.mx-sm-auto{margin-right:auto !important;margin-left:auto !important}.my-sm-0{margin-top:0 !important;margin-bottom:0 !important}.my-sm-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.my-sm-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.my-sm-3{margin-top:1rem !important;margin-bottom:1rem !important}.my-sm-4{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.my-sm-5{margin-top:3rem !important;margin-bottom:3rem !important}.my-sm-auto{margin-top:auto !important;margin-bottom:auto !important}.mt-sm-0{margin-top:0 !important}.mt-sm-1{margin-top:.25rem !important}.mt-sm-2{margin-top:.5rem !important}.mt-sm-3{margin-top:1rem !important}.mt-sm-4{margin-top:1.5rem !important}.mt-sm-5{margin-top:3rem !important}.mt-sm-auto{margin-top:auto !important}.me-sm-0{margin-right:0 !important}.me-sm-1{margin-right:.25rem !important}.me-sm-2{margin-right:.5rem !important}.me-sm-3{margin-right:1rem !important}.me-sm-4{margin-right:1.5rem !important}.me-sm-5{margin-right:3rem !important}.me-sm-auto{margin-right:auto !important}.mb-sm-0{margin-bottom:0 !important}.mb-sm-1{margin-bottom:.25rem !important}.mb-sm-2{margin-bottom:.5rem !important}.mb-sm-3{margin-bottom:1rem !important}.mb-sm-4{margin-bottom:1.5rem !important}.mb-sm-5{margin-bottom:3rem !important}.mb-sm-auto{margin-bottom:auto !important}.ms-sm-0{margin-left:0 !important}.ms-sm-1{margin-left:.25rem !important}.ms-sm-2{margin-left:.5rem !important}.ms-sm-3{margin-left:1rem !important}.ms-sm-4{margin-left:1.5rem !important}.ms-sm-5{margin-left:3rem !important}.ms-sm-auto{margin-left:auto !important}.p-sm-0{padding:0 !important}.p-sm-1{padding:.25rem !important}.p-sm-2{padding:.5rem !important}.p-sm-3{padding:1rem !important}.p-sm-4{padding:1.5rem !important}.p-sm-5{padding:3rem !important}.px-sm-0{padding-right:0 !important;padding-left:0 !important}.px-sm-1{padding-right:.25rem !important;padding-left:.25rem !important}.px-sm-2{padding-right:.5rem !important;padding-left:.5rem !important}.px-sm-3{padding-right:1rem !important;padding-left:1rem !important}.px-sm-4{padding-right:1.5rem !important;padding-left:1.5rem !important}.px-sm-5{padding-right:3rem !important;padding-left:3rem !important}.py-sm-0{padding-top:0 !important;padding-bottom:0 !important}.py-sm-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.py-sm-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.py-sm-3{padding-top:1rem !important;padding-bottom:1rem !important}.py-sm-4{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.py-sm-5{padding-top:3rem !important;padding-bottom:3rem !important}.pt-sm-0{padding-top:0 !important}.pt-sm-1{padding-top:.25rem !important}.pt-sm-2{padding-top:.5rem !important}.pt-sm-3{padding-top:1rem !important}.pt-sm-4{padding-top:1.5rem !important}.pt-sm-5{padding-top:3rem !important}.pe-sm-0{padding-right:0 !important}.pe-sm-1{padding-right:.25rem !important}.pe-sm-2{padding-right:.5rem !important}.pe-sm-3{padding-right:1rem !important}.pe-sm-4{padding-right:1.5rem !important}.pe-sm-5{padding-right:3rem !important}.pb-sm-0{padding-bottom:0 !important}.pb-sm-1{padding-bottom:.25rem !important}.pb-sm-2{padding-bottom:.5rem !important}.pb-sm-3{padding-bottom:1rem !important}.pb-sm-4{padding-bottom:1.5rem !important}.pb-sm-5{padding-bottom:3rem !important}.ps-sm-0{padding-left:0 !important}.ps-sm-1{padding-left:.25rem !important}.ps-sm-2{padding-left:.5rem !important}.ps-sm-3{padding-left:1rem !important}.ps-sm-4{padding-left:1.5rem !important}.ps-sm-5{padding-left:3rem !important}.gap-sm-0{gap:0 !important}.gap-sm-1{gap:.25rem !important}.gap-sm-2{gap:.5rem !important}.gap-sm-3{gap:1rem !important}.gap-sm-4{gap:1.5rem !important}.gap-sm-5{gap:3rem !important}.row-gap-sm-0{row-gap:0 !important}.row-gap-sm-1{row-gap:.25rem !important}.row-gap-sm-2{row-gap:.5rem !important}.row-gap-sm-3{row-gap:1rem !important}.row-gap-sm-4{row-gap:1.5rem !important}.row-gap-sm-5{row-gap:3rem !important}.column-gap-sm-0{column-gap:0 !important}.column-gap-sm-1{column-gap:.25rem !important}.column-gap-sm-2{column-gap:.5rem !important}.column-gap-sm-3{column-gap:1rem !important}.column-gap-sm-4{column-gap:1.5rem !important}.column-gap-sm-5{column-gap:3rem !important}.text-sm-start{text-align:left !important}.text-sm-end{text-align:right !important}.text-sm-center{text-align:center !important}}@media(min-width: 768px){.float-md-start{float:left !important}.float-md-end{float:right !important}.float-md-none{float:none !important}.object-fit-md-contain{object-fit:contain !important}.object-fit-md-cover{object-fit:cover !important}.object-fit-md-fill{object-fit:fill !important}.object-fit-md-scale{object-fit:scale-down !important}.object-fit-md-none{object-fit:none !important}.d-md-inline{display:inline !important}.d-md-inline-block{display:inline-block !important}.d-md-block{display:block !important}.d-md-grid{display:grid !important}.d-md-inline-grid{display:inline-grid !important}.d-md-table{display:table !important}.d-md-table-row{display:table-row !important}.d-md-table-cell{display:table-cell !important}.d-md-flex{display:flex !important}.d-md-inline-flex{display:inline-flex !important}.d-md-none{display:none !important}.flex-md-fill{flex:1 1 auto !important}.flex-md-row{flex-direction:row !important}.flex-md-column{flex-direction:column !important}.flex-md-row-reverse{flex-direction:row-reverse !important}.flex-md-column-reverse{flex-direction:column-reverse !important}.flex-md-grow-0{flex-grow:0 !important}.flex-md-grow-1{flex-grow:1 !important}.flex-md-shrink-0{flex-shrink:0 !important}.flex-md-shrink-1{flex-shrink:1 !important}.flex-md-wrap{flex-wrap:wrap !important}.flex-md-nowrap{flex-wrap:nowrap !important}.flex-md-wrap-reverse{flex-wrap:wrap-reverse !important}.justify-content-md-start{justify-content:flex-start !important}.justify-content-md-end{justify-content:flex-end !important}.justify-content-md-center{justify-content:center !important}.justify-content-md-between{justify-content:space-between !important}.justify-content-md-around{justify-content:space-around !important}.justify-content-md-evenly{justify-content:space-evenly !important}.align-items-md-start{align-items:flex-start !important}.align-items-md-end{align-items:flex-end !important}.align-items-md-center{align-items:center !important}.align-items-md-baseline{align-items:baseline !important}.align-items-md-stretch{align-items:stretch !important}.align-content-md-start{align-content:flex-start !important}.align-content-md-end{align-content:flex-end !important}.align-content-md-center{align-content:center !important}.align-content-md-between{align-content:space-between !important}.align-content-md-around{align-content:space-around !important}.align-content-md-stretch{align-content:stretch !important}.align-self-md-auto{align-self:auto !important}.align-self-md-start{align-self:flex-start !important}.align-self-md-end{align-self:flex-end !important}.align-self-md-center{align-self:center !important}.align-self-md-baseline{align-self:baseline !important}.align-self-md-stretch{align-self:stretch !important}.order-md-first{order:-1 !important}.order-md-0{order:0 !important}.order-md-1{order:1 !important}.order-md-2{order:2 !important}.order-md-3{order:3 !important}.order-md-4{order:4 !important}.order-md-5{order:5 !important}.order-md-last{order:6 !important}.m-md-0{margin:0 !important}.m-md-1{margin:.25rem !important}.m-md-2{margin:.5rem !important}.m-md-3{margin:1rem !important}.m-md-4{margin:1.5rem !important}.m-md-5{margin:3rem !important}.m-md-auto{margin:auto !important}.mx-md-0{margin-right:0 !important;margin-left:0 !important}.mx-md-1{margin-right:.25rem !important;margin-left:.25rem !important}.mx-md-2{margin-right:.5rem !important;margin-left:.5rem !important}.mx-md-3{margin-right:1rem !important;margin-left:1rem !important}.mx-md-4{margin-right:1.5rem !important;margin-left:1.5rem !important}.mx-md-5{margin-right:3rem !important;margin-left:3rem !important}.mx-md-auto{margin-right:auto !important;margin-left:auto !important}.my-md-0{margin-top:0 !important;margin-bottom:0 !important}.my-md-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.my-md-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.my-md-3{margin-top:1rem !important;margin-bottom:1rem !important}.my-md-4{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.my-md-5{margin-top:3rem !important;margin-bottom:3rem !important}.my-md-auto{margin-top:auto !important;margin-bottom:auto !important}.mt-md-0{margin-top:0 !important}.mt-md-1{margin-top:.25rem !important}.mt-md-2{margin-top:.5rem !important}.mt-md-3{margin-top:1rem !important}.mt-md-4{margin-top:1.5rem !important}.mt-md-5{margin-top:3rem !important}.mt-md-auto{margin-top:auto !important}.me-md-0{margin-right:0 !important}.me-md-1{margin-right:.25rem !important}.me-md-2{margin-right:.5rem !important}.me-md-3{margin-right:1rem !important}.me-md-4{margin-right:1.5rem !important}.me-md-5{margin-right:3rem !important}.me-md-auto{margin-right:auto !important}.mb-md-0{margin-bottom:0 !important}.mb-md-1{margin-bottom:.25rem !important}.mb-md-2{margin-bottom:.5rem !important}.mb-md-3{margin-bottom:1rem !important}.mb-md-4{margin-bottom:1.5rem !important}.mb-md-5{margin-bottom:3rem !important}.mb-md-auto{margin-bottom:auto !important}.ms-md-0{margin-left:0 !important}.ms-md-1{margin-left:.25rem !important}.ms-md-2{margin-left:.5rem !important}.ms-md-3{margin-left:1rem !important}.ms-md-4{margin-left:1.5rem !important}.ms-md-5{margin-left:3rem !important}.ms-md-auto{margin-left:auto !important}.p-md-0{padding:0 !important}.p-md-1{padding:.25rem !important}.p-md-2{padding:.5rem !important}.p-md-3{padding:1rem !important}.p-md-4{padding:1.5rem !important}.p-md-5{padding:3rem !important}.px-md-0{padding-right:0 !important;padding-left:0 !important}.px-md-1{padding-right:.25rem !important;padding-left:.25rem !important}.px-md-2{padding-right:.5rem !important;padding-left:.5rem !important}.px-md-3{padding-right:1rem !important;padding-left:1rem !important}.px-md-4{padding-right:1.5rem !important;padding-left:1.5rem !important}.px-md-5{padding-right:3rem !important;padding-left:3rem !important}.py-md-0{padding-top:0 !important;padding-bottom:0 !important}.py-md-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.py-md-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.py-md-3{padding-top:1rem !important;padding-bottom:1rem !important}.py-md-4{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.py-md-5{padding-top:3rem !important;padding-bottom:3rem !important}.pt-md-0{padding-top:0 !important}.pt-md-1{padding-top:.25rem !important}.pt-md-2{padding-top:.5rem !important}.pt-md-3{padding-top:1rem !important}.pt-md-4{padding-top:1.5rem !important}.pt-md-5{padding-top:3rem !important}.pe-md-0{padding-right:0 !important}.pe-md-1{padding-right:.25rem !important}.pe-md-2{padding-right:.5rem !important}.pe-md-3{padding-right:1rem !important}.pe-md-4{padding-right:1.5rem !important}.pe-md-5{padding-right:3rem !important}.pb-md-0{padding-bottom:0 !important}.pb-md-1{padding-bottom:.25rem !important}.pb-md-2{padding-bottom:.5rem !important}.pb-md-3{padding-bottom:1rem !important}.pb-md-4{padding-bottom:1.5rem !important}.pb-md-5{padding-bottom:3rem !important}.ps-md-0{padding-left:0 !important}.ps-md-1{padding-left:.25rem !important}.ps-md-2{padding-left:.5rem !important}.ps-md-3{padding-left:1rem !important}.ps-md-4{padding-left:1.5rem !important}.ps-md-5{padding-left:3rem !important}.gap-md-0{gap:0 !important}.gap-md-1{gap:.25rem !important}.gap-md-2{gap:.5rem !important}.gap-md-3{gap:1rem !important}.gap-md-4{gap:1.5rem !important}.gap-md-5{gap:3rem !important}.row-gap-md-0{row-gap:0 !important}.row-gap-md-1{row-gap:.25rem !important}.row-gap-md-2{row-gap:.5rem !important}.row-gap-md-3{row-gap:1rem !important}.row-gap-md-4{row-gap:1.5rem !important}.row-gap-md-5{row-gap:3rem !important}.column-gap-md-0{column-gap:0 !important}.column-gap-md-1{column-gap:.25rem !important}.column-gap-md-2{column-gap:.5rem !important}.column-gap-md-3{column-gap:1rem !important}.column-gap-md-4{column-gap:1.5rem !important}.column-gap-md-5{column-gap:3rem !important}.text-md-start{text-align:left !important}.text-md-end{text-align:right !important}.text-md-center{text-align:center !important}}@media(min-width: 992px){.float-lg-start{float:left !important}.float-lg-end{float:right !important}.float-lg-none{float:none !important}.object-fit-lg-contain{object-fit:contain !important}.object-fit-lg-cover{object-fit:cover !important}.object-fit-lg-fill{object-fit:fill !important}.object-fit-lg-scale{object-fit:scale-down !important}.object-fit-lg-none{object-fit:none !important}.d-lg-inline{display:inline !important}.d-lg-inline-block{display:inline-block !important}.d-lg-block{display:block !important}.d-lg-grid{display:grid !important}.d-lg-inline-grid{display:inline-grid !important}.d-lg-table{display:table !important}.d-lg-table-row{display:table-row !important}.d-lg-table-cell{display:table-cell !important}.d-lg-flex{display:flex !important}.d-lg-inline-flex{display:inline-flex !important}.d-lg-none{display:none !important}.flex-lg-fill{flex:1 1 auto !important}.flex-lg-row{flex-direction:row !important}.flex-lg-column{flex-direction:column !important}.flex-lg-row-reverse{flex-direction:row-reverse !important}.flex-lg-column-reverse{flex-direction:column-reverse !important}.flex-lg-grow-0{flex-grow:0 !important}.flex-lg-grow-1{flex-grow:1 !important}.flex-lg-shrink-0{flex-shrink:0 !important}.flex-lg-shrink-1{flex-shrink:1 !important}.flex-lg-wrap{flex-wrap:wrap !important}.flex-lg-nowrap{flex-wrap:nowrap !important}.flex-lg-wrap-reverse{flex-wrap:wrap-reverse !important}.justify-content-lg-start{justify-content:flex-start !important}.justify-content-lg-end{justify-content:flex-end !important}.justify-content-lg-center{justify-content:center !important}.justify-content-lg-between{justify-content:space-between !important}.justify-content-lg-around{justify-content:space-around !important}.justify-content-lg-evenly{justify-content:space-evenly !important}.align-items-lg-start{align-items:flex-start !important}.align-items-lg-end{align-items:flex-end !important}.align-items-lg-center{align-items:center !important}.align-items-lg-baseline{align-items:baseline !important}.align-items-lg-stretch{align-items:stretch !important}.align-content-lg-start{align-content:flex-start !important}.align-content-lg-end{align-content:flex-end !important}.align-content-lg-center{align-content:center !important}.align-content-lg-between{align-content:space-between !important}.align-content-lg-around{align-content:space-around !important}.align-content-lg-stretch{align-content:stretch !important}.align-self-lg-auto{align-self:auto !important}.align-self-lg-start{align-self:flex-start !important}.align-self-lg-end{align-self:flex-end !important}.align-self-lg-center{align-self:center !important}.align-self-lg-baseline{align-self:baseline !important}.align-self-lg-stretch{align-self:stretch !important}.order-lg-first{order:-1 !important}.order-lg-0{order:0 !important}.order-lg-1{order:1 !important}.order-lg-2{order:2 !important}.order-lg-3{order:3 !important}.order-lg-4{order:4 !important}.order-lg-5{order:5 !important}.order-lg-last{order:6 !important}.m-lg-0{margin:0 !important}.m-lg-1{margin:.25rem !important}.m-lg-2{margin:.5rem !important}.m-lg-3{margin:1rem !important}.m-lg-4{margin:1.5rem !important}.m-lg-5{margin:3rem !important}.m-lg-auto{margin:auto !important}.mx-lg-0{margin-right:0 !important;margin-left:0 !important}.mx-lg-1{margin-right:.25rem !important;margin-left:.25rem !important}.mx-lg-2{margin-right:.5rem !important;margin-left:.5rem !important}.mx-lg-3{margin-right:1rem !important;margin-left:1rem !important}.mx-lg-4{margin-right:1.5rem !important;margin-left:1.5rem !important}.mx-lg-5{margin-right:3rem !important;margin-left:3rem !important}.mx-lg-auto{margin-right:auto !important;margin-left:auto !important}.my-lg-0{margin-top:0 !important;margin-bottom:0 !important}.my-lg-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.my-lg-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.my-lg-3{margin-top:1rem !important;margin-bottom:1rem !important}.my-lg-4{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.my-lg-5{margin-top:3rem !important;margin-bottom:3rem !important}.my-lg-auto{margin-top:auto !important;margin-bottom:auto !important}.mt-lg-0{margin-top:0 !important}.mt-lg-1{margin-top:.25rem !important}.mt-lg-2{margin-top:.5rem !important}.mt-lg-3{margin-top:1rem !important}.mt-lg-4{margin-top:1.5rem !important}.mt-lg-5{margin-top:3rem !important}.mt-lg-auto{margin-top:auto !important}.me-lg-0{margin-right:0 !important}.me-lg-1{margin-right:.25rem !important}.me-lg-2{margin-right:.5rem !important}.me-lg-3{margin-right:1rem !important}.me-lg-4{margin-right:1.5rem !important}.me-lg-5{margin-right:3rem !important}.me-lg-auto{margin-right:auto !important}.mb-lg-0{margin-bottom:0 !important}.mb-lg-1{margin-bottom:.25rem !important}.mb-lg-2{margin-bottom:.5rem !important}.mb-lg-3{margin-bottom:1rem !important}.mb-lg-4{margin-bottom:1.5rem !important}.mb-lg-5{margin-bottom:3rem !important}.mb-lg-auto{margin-bottom:auto !important}.ms-lg-0{margin-left:0 !important}.ms-lg-1{margin-left:.25rem !important}.ms-lg-2{margin-left:.5rem !important}.ms-lg-3{margin-left:1rem !important}.ms-lg-4{margin-left:1.5rem !important}.ms-lg-5{margin-left:3rem !important}.ms-lg-auto{margin-left:auto !important}.p-lg-0{padding:0 !important}.p-lg-1{padding:.25rem !important}.p-lg-2{padding:.5rem !important}.p-lg-3{padding:1rem !important}.p-lg-4{padding:1.5rem !important}.p-lg-5{padding:3rem !important}.px-lg-0{padding-right:0 !important;padding-left:0 !important}.px-lg-1{padding-right:.25rem !important;padding-left:.25rem !important}.px-lg-2{padding-right:.5rem !important;padding-left:.5rem !important}.px-lg-3{padding-right:1rem !important;padding-left:1rem !important}.px-lg-4{padding-right:1.5rem !important;padding-left:1.5rem !important}.px-lg-5{padding-right:3rem !important;padding-left:3rem !important}.py-lg-0{padding-top:0 !important;padding-bottom:0 !important}.py-lg-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.py-lg-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.py-lg-3{padding-top:1rem !important;padding-bottom:1rem !important}.py-lg-4{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.py-lg-5{padding-top:3rem !important;padding-bottom:3rem !important}.pt-lg-0{padding-top:0 !important}.pt-lg-1{padding-top:.25rem !important}.pt-lg-2{padding-top:.5rem !important}.pt-lg-3{padding-top:1rem !important}.pt-lg-4{padding-top:1.5rem !important}.pt-lg-5{padding-top:3rem !important}.pe-lg-0{padding-right:0 !important}.pe-lg-1{padding-right:.25rem !important}.pe-lg-2{padding-right:.5rem !important}.pe-lg-3{padding-right:1rem !important}.pe-lg-4{padding-right:1.5rem !important}.pe-lg-5{padding-right:3rem !important}.pb-lg-0{padding-bottom:0 !important}.pb-lg-1{padding-bottom:.25rem !important}.pb-lg-2{padding-bottom:.5rem !important}.pb-lg-3{padding-bottom:1rem !important}.pb-lg-4{padding-bottom:1.5rem !important}.pb-lg-5{padding-bottom:3rem !important}.ps-lg-0{padding-left:0 !important}.ps-lg-1{padding-left:.25rem !important}.ps-lg-2{padding-left:.5rem !important}.ps-lg-3{padding-left:1rem !important}.ps-lg-4{padding-left:1.5rem !important}.ps-lg-5{padding-left:3rem !important}.gap-lg-0{gap:0 !important}.gap-lg-1{gap:.25rem !important}.gap-lg-2{gap:.5rem !important}.gap-lg-3{gap:1rem !important}.gap-lg-4{gap:1.5rem !important}.gap-lg-5{gap:3rem !important}.row-gap-lg-0{row-gap:0 !important}.row-gap-lg-1{row-gap:.25rem !important}.row-gap-lg-2{row-gap:.5rem !important}.row-gap-lg-3{row-gap:1rem !important}.row-gap-lg-4{row-gap:1.5rem !important}.row-gap-lg-5{row-gap:3rem !important}.column-gap-lg-0{column-gap:0 !important}.column-gap-lg-1{column-gap:.25rem !important}.column-gap-lg-2{column-gap:.5rem !important}.column-gap-lg-3{column-gap:1rem !important}.column-gap-lg-4{column-gap:1.5rem !important}.column-gap-lg-5{column-gap:3rem !important}.text-lg-start{text-align:left !important}.text-lg-end{text-align:right !important}.text-lg-center{text-align:center !important}}@media(min-width: 1200px){.float-xl-start{float:left !important}.float-xl-end{float:right !important}.float-xl-none{float:none !important}.object-fit-xl-contain{object-fit:contain !important}.object-fit-xl-cover{object-fit:cover !important}.object-fit-xl-fill{object-fit:fill !important}.object-fit-xl-scale{object-fit:scale-down !important}.object-fit-xl-none{object-fit:none !important}.d-xl-inline{display:inline !important}.d-xl-inline-block{display:inline-block !important}.d-xl-block{display:block !important}.d-xl-grid{display:grid !important}.d-xl-inline-grid{display:inline-grid !important}.d-xl-table{display:table !important}.d-xl-table-row{display:table-row !important}.d-xl-table-cell{display:table-cell !important}.d-xl-flex{display:flex !important}.d-xl-inline-flex{display:inline-flex !important}.d-xl-none{display:none !important}.flex-xl-fill{flex:1 1 auto !important}.flex-xl-row{flex-direction:row !important}.flex-xl-column{flex-direction:column !important}.flex-xl-row-reverse{flex-direction:row-reverse !important}.flex-xl-column-reverse{flex-direction:column-reverse !important}.flex-xl-grow-0{flex-grow:0 !important}.flex-xl-grow-1{flex-grow:1 !important}.flex-xl-shrink-0{flex-shrink:0 !important}.flex-xl-shrink-1{flex-shrink:1 !important}.flex-xl-wrap{flex-wrap:wrap !important}.flex-xl-nowrap{flex-wrap:nowrap !important}.flex-xl-wrap-reverse{flex-wrap:wrap-reverse !important}.justify-content-xl-start{justify-content:flex-start !important}.justify-content-xl-end{justify-content:flex-end !important}.justify-content-xl-center{justify-content:center !important}.justify-content-xl-between{justify-content:space-between !important}.justify-content-xl-around{justify-content:space-around !important}.justify-content-xl-evenly{justify-content:space-evenly !important}.align-items-xl-start{align-items:flex-start !important}.align-items-xl-end{align-items:flex-end !important}.align-items-xl-center{align-items:center !important}.align-items-xl-baseline{align-items:baseline !important}.align-items-xl-stretch{align-items:stretch !important}.align-content-xl-start{align-content:flex-start !important}.align-content-xl-end{align-content:flex-end !important}.align-content-xl-center{align-content:center !important}.align-content-xl-between{align-content:space-between !important}.align-content-xl-around{align-content:space-around !important}.align-content-xl-stretch{align-content:stretch !important}.align-self-xl-auto{align-self:auto !important}.align-self-xl-start{align-self:flex-start !important}.align-self-xl-end{align-self:flex-end !important}.align-self-xl-center{align-self:center !important}.align-self-xl-baseline{align-self:baseline !important}.align-self-xl-stretch{align-self:stretch !important}.order-xl-first{order:-1 !important}.order-xl-0{order:0 !important}.order-xl-1{order:1 !important}.order-xl-2{order:2 !important}.order-xl-3{order:3 !important}.order-xl-4{order:4 !important}.order-xl-5{order:5 !important}.order-xl-last{order:6 !important}.m-xl-0{margin:0 !important}.m-xl-1{margin:.25rem !important}.m-xl-2{margin:.5rem !important}.m-xl-3{margin:1rem !important}.m-xl-4{margin:1.5rem !important}.m-xl-5{margin:3rem !important}.m-xl-auto{margin:auto !important}.mx-xl-0{margin-right:0 !important;margin-left:0 !important}.mx-xl-1{margin-right:.25rem !important;margin-left:.25rem !important}.mx-xl-2{margin-right:.5rem !important;margin-left:.5rem !important}.mx-xl-3{margin-right:1rem !important;margin-left:1rem !important}.mx-xl-4{margin-right:1.5rem !important;margin-left:1.5rem !important}.mx-xl-5{margin-right:3rem !important;margin-left:3rem !important}.mx-xl-auto{margin-right:auto !important;margin-left:auto !important}.my-xl-0{margin-top:0 !important;margin-bottom:0 !important}.my-xl-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.my-xl-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.my-xl-3{margin-top:1rem !important;margin-bottom:1rem !important}.my-xl-4{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.my-xl-5{margin-top:3rem !important;margin-bottom:3rem !important}.my-xl-auto{margin-top:auto !important;margin-bottom:auto !important}.mt-xl-0{margin-top:0 !important}.mt-xl-1{margin-top:.25rem !important}.mt-xl-2{margin-top:.5rem !important}.mt-xl-3{margin-top:1rem !important}.mt-xl-4{margin-top:1.5rem !important}.mt-xl-5{margin-top:3rem !important}.mt-xl-auto{margin-top:auto !important}.me-xl-0{margin-right:0 !important}.me-xl-1{margin-right:.25rem !important}.me-xl-2{margin-right:.5rem !important}.me-xl-3{margin-right:1rem !important}.me-xl-4{margin-right:1.5rem !important}.me-xl-5{margin-right:3rem !important}.me-xl-auto{margin-right:auto !important}.mb-xl-0{margin-bottom:0 !important}.mb-xl-1{margin-bottom:.25rem !important}.mb-xl-2{margin-bottom:.5rem !important}.mb-xl-3{margin-bottom:1rem !important}.mb-xl-4{margin-bottom:1.5rem !important}.mb-xl-5{margin-bottom:3rem !important}.mb-xl-auto{margin-bottom:auto !important}.ms-xl-0{margin-left:0 !important}.ms-xl-1{margin-left:.25rem !important}.ms-xl-2{margin-left:.5rem !important}.ms-xl-3{margin-left:1rem !important}.ms-xl-4{margin-left:1.5rem !important}.ms-xl-5{margin-left:3rem !important}.ms-xl-auto{margin-left:auto !important}.p-xl-0{padding:0 !important}.p-xl-1{padding:.25rem !important}.p-xl-2{padding:.5rem !important}.p-xl-3{padding:1rem !important}.p-xl-4{padding:1.5rem !important}.p-xl-5{padding:3rem !important}.px-xl-0{padding-right:0 !important;padding-left:0 !important}.px-xl-1{padding-right:.25rem !important;padding-left:.25rem !important}.px-xl-2{padding-right:.5rem !important;padding-left:.5rem !important}.px-xl-3{padding-right:1rem !important;padding-left:1rem !important}.px-xl-4{padding-right:1.5rem !important;padding-left:1.5rem !important}.px-xl-5{padding-right:3rem !important;padding-left:3rem !important}.py-xl-0{padding-top:0 !important;padding-bottom:0 !important}.py-xl-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.py-xl-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.py-xl-3{padding-top:1rem !important;padding-bottom:1rem !important}.py-xl-4{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.py-xl-5{padding-top:3rem !important;padding-bottom:3rem !important}.pt-xl-0{padding-top:0 !important}.pt-xl-1{padding-top:.25rem !important}.pt-xl-2{padding-top:.5rem !important}.pt-xl-3{padding-top:1rem !important}.pt-xl-4{padding-top:1.5rem !important}.pt-xl-5{padding-top:3rem !important}.pe-xl-0{padding-right:0 !important}.pe-xl-1{padding-right:.25rem !important}.pe-xl-2{padding-right:.5rem !important}.pe-xl-3{padding-right:1rem !important}.pe-xl-4{padding-right:1.5rem !important}.pe-xl-5{padding-right:3rem !important}.pb-xl-0{padding-bottom:0 !important}.pb-xl-1{padding-bottom:.25rem !important}.pb-xl-2{padding-bottom:.5rem !important}.pb-xl-3{padding-bottom:1rem !important}.pb-xl-4{padding-bottom:1.5rem !important}.pb-xl-5{padding-bottom:3rem !important}.ps-xl-0{padding-left:0 !important}.ps-xl-1{padding-left:.25rem !important}.ps-xl-2{padding-left:.5rem !important}.ps-xl-3{padding-left:1rem !important}.ps-xl-4{padding-left:1.5rem !important}.ps-xl-5{padding-left:3rem !important}.gap-xl-0{gap:0 !important}.gap-xl-1{gap:.25rem !important}.gap-xl-2{gap:.5rem !important}.gap-xl-3{gap:1rem !important}.gap-xl-4{gap:1.5rem !important}.gap-xl-5{gap:3rem !important}.row-gap-xl-0{row-gap:0 !important}.row-gap-xl-1{row-gap:.25rem !important}.row-gap-xl-2{row-gap:.5rem !important}.row-gap-xl-3{row-gap:1rem !important}.row-gap-xl-4{row-gap:1.5rem !important}.row-gap-xl-5{row-gap:3rem !important}.column-gap-xl-0{column-gap:0 !important}.column-gap-xl-1{column-gap:.25rem !important}.column-gap-xl-2{column-gap:.5rem !important}.column-gap-xl-3{column-gap:1rem !important}.column-gap-xl-4{column-gap:1.5rem !important}.column-gap-xl-5{column-gap:3rem !important}.text-xl-start{text-align:left !important}.text-xl-end{text-align:right !important}.text-xl-center{text-align:center !important}}@media(min-width: 1400px){.float-xxl-start{float:left !important}.float-xxl-end{float:right !important}.float-xxl-none{float:none !important}.object-fit-xxl-contain{object-fit:contain !important}.object-fit-xxl-cover{object-fit:cover !important}.object-fit-xxl-fill{object-fit:fill !important}.object-fit-xxl-scale{object-fit:scale-down !important}.object-fit-xxl-none{object-fit:none !important}.d-xxl-inline{display:inline !important}.d-xxl-inline-block{display:inline-block !important}.d-xxl-block{display:block !important}.d-xxl-grid{display:grid !important}.d-xxl-inline-grid{display:inline-grid !important}.d-xxl-table{display:table !important}.d-xxl-table-row{display:table-row !important}.d-xxl-table-cell{display:table-cell !important}.d-xxl-flex{display:flex !important}.d-xxl-inline-flex{display:inline-flex !important}.d-xxl-none{display:none !important}.flex-xxl-fill{flex:1 1 auto !important}.flex-xxl-row{flex-direction:row !important}.flex-xxl-column{flex-direction:column !important}.flex-xxl-row-reverse{flex-direction:row-reverse !important}.flex-xxl-column-reverse{flex-direction:column-reverse !important}.flex-xxl-grow-0{flex-grow:0 !important}.flex-xxl-grow-1{flex-grow:1 !important}.flex-xxl-shrink-0{flex-shrink:0 !important}.flex-xxl-shrink-1{flex-shrink:1 !important}.flex-xxl-wrap{flex-wrap:wrap !important}.flex-xxl-nowrap{flex-wrap:nowrap !important}.flex-xxl-wrap-reverse{flex-wrap:wrap-reverse !important}.justify-content-xxl-start{justify-content:flex-start !important}.justify-content-xxl-end{justify-content:flex-end !important}.justify-content-xxl-center{justify-content:center !important}.justify-content-xxl-between{justify-content:space-between !important}.justify-content-xxl-around{justify-content:space-around !important}.justify-content-xxl-evenly{justify-content:space-evenly !important}.align-items-xxl-start{align-items:flex-start !important}.align-items-xxl-end{align-items:flex-end !important}.align-items-xxl-center{align-items:center !important}.align-items-xxl-baseline{align-items:baseline !important}.align-items-xxl-stretch{align-items:stretch !important}.align-content-xxl-start{align-content:flex-start !important}.align-content-xxl-end{align-content:flex-end !important}.align-content-xxl-center{align-content:center !important}.align-content-xxl-between{align-content:space-between !important}.align-content-xxl-around{align-content:space-around !important}.align-content-xxl-stretch{align-content:stretch !important}.align-self-xxl-auto{align-self:auto !important}.align-self-xxl-start{align-self:flex-start !important}.align-self-xxl-end{align-self:flex-end !important}.align-self-xxl-center{align-self:center !important}.align-self-xxl-baseline{align-self:baseline !important}.align-self-xxl-stretch{align-self:stretch !important}.order-xxl-first{order:-1 !important}.order-xxl-0{order:0 !important}.order-xxl-1{order:1 !important}.order-xxl-2{order:2 !important}.order-xxl-3{order:3 !important}.order-xxl-4{order:4 !important}.order-xxl-5{order:5 !important}.order-xxl-last{order:6 !important}.m-xxl-0{margin:0 !important}.m-xxl-1{margin:.25rem !important}.m-xxl-2{margin:.5rem !important}.m-xxl-3{margin:1rem !important}.m-xxl-4{margin:1.5rem !important}.m-xxl-5{margin:3rem !important}.m-xxl-auto{margin:auto !important}.mx-xxl-0{margin-right:0 !important;margin-left:0 !important}.mx-xxl-1{margin-right:.25rem !important;margin-left:.25rem !important}.mx-xxl-2{margin-right:.5rem !important;margin-left:.5rem !important}.mx-xxl-3{margin-right:1rem !important;margin-left:1rem !important}.mx-xxl-4{margin-right:1.5rem !important;margin-left:1.5rem !important}.mx-xxl-5{margin-right:3rem !important;margin-left:3rem !important}.mx-xxl-auto{margin-right:auto !important;margin-left:auto !important}.my-xxl-0{margin-top:0 !important;margin-bottom:0 !important}.my-xxl-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.my-xxl-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.my-xxl-3{margin-top:1rem !important;margin-bottom:1rem !important}.my-xxl-4{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.my-xxl-5{margin-top:3rem !important;margin-bottom:3rem !important}.my-xxl-auto{margin-top:auto !important;margin-bottom:auto !important}.mt-xxl-0{margin-top:0 !important}.mt-xxl-1{margin-top:.25rem !important}.mt-xxl-2{margin-top:.5rem !important}.mt-xxl-3{margin-top:1rem !important}.mt-xxl-4{margin-top:1.5rem !important}.mt-xxl-5{margin-top:3rem !important}.mt-xxl-auto{margin-top:auto !important}.me-xxl-0{margin-right:0 !important}.me-xxl-1{margin-right:.25rem !important}.me-xxl-2{margin-right:.5rem !important}.me-xxl-3{margin-right:1rem !important}.me-xxl-4{margin-right:1.5rem !important}.me-xxl-5{margin-right:3rem !important}.me-xxl-auto{margin-right:auto !important}.mb-xxl-0{margin-bottom:0 !important}.mb-xxl-1{margin-bottom:.25rem !important}.mb-xxl-2{margin-bottom:.5rem !important}.mb-xxl-3{margin-bottom:1rem !important}.mb-xxl-4{margin-bottom:1.5rem !important}.mb-xxl-5{margin-bottom:3rem !important}.mb-xxl-auto{margin-bottom:auto !important}.ms-xxl-0{margin-left:0 !important}.ms-xxl-1{margin-left:.25rem !important}.ms-xxl-2{margin-left:.5rem !important}.ms-xxl-3{margin-left:1rem !important}.ms-xxl-4{margin-left:1.5rem !important}.ms-xxl-5{margin-left:3rem !important}.ms-xxl-auto{margin-left:auto !important}.p-xxl-0{padding:0 !important}.p-xxl-1{padding:.25rem !important}.p-xxl-2{padding:.5rem !important}.p-xxl-3{padding:1rem !important}.p-xxl-4{padding:1.5rem !important}.p-xxl-5{padding:3rem !important}.px-xxl-0{padding-right:0 !important;padding-left:0 !important}.px-xxl-1{padding-right:.25rem !important;padding-left:.25rem !important}.px-xxl-2{padding-right:.5rem !important;padding-left:.5rem !important}.px-xxl-3{padding-right:1rem !important;padding-left:1rem !important}.px-xxl-4{padding-right:1.5rem !important;padding-left:1.5rem !important}.px-xxl-5{padding-right:3rem !important;padding-left:3rem !important}.py-xxl-0{padding-top:0 !important;padding-bottom:0 !important}.py-xxl-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.py-xxl-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.py-xxl-3{padding-top:1rem !important;padding-bottom:1rem !important}.py-xxl-4{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.py-xxl-5{padding-top:3rem !important;padding-bottom:3rem !important}.pt-xxl-0{padding-top:0 !important}.pt-xxl-1{padding-top:.25rem !important}.pt-xxl-2{padding-top:.5rem !important}.pt-xxl-3{padding-top:1rem !important}.pt-xxl-4{padding-top:1.5rem !important}.pt-xxl-5{padding-top:3rem !important}.pe-xxl-0{padding-right:0 !important}.pe-xxl-1{padding-right:.25rem !important}.pe-xxl-2{padding-right:.5rem !important}.pe-xxl-3{padding-right:1rem !important}.pe-xxl-4{padding-right:1.5rem !important}.pe-xxl-5{padding-right:3rem !important}.pb-xxl-0{padding-bottom:0 !important}.pb-xxl-1{padding-bottom:.25rem !important}.pb-xxl-2{padding-bottom:.5rem !important}.pb-xxl-3{padding-bottom:1rem !important}.pb-xxl-4{padding-bottom:1.5rem !important}.pb-xxl-5{padding-bottom:3rem !important}.ps-xxl-0{padding-left:0 !important}.ps-xxl-1{padding-left:.25rem !important}.ps-xxl-2{padding-left:.5rem !important}.ps-xxl-3{padding-left:1rem !important}.ps-xxl-4{padding-left:1.5rem !important}.ps-xxl-5{padding-left:3rem !important}.gap-xxl-0{gap:0 !important}.gap-xxl-1{gap:.25rem !important}.gap-xxl-2{gap:.5rem !important}.gap-xxl-3{gap:1rem !important}.gap-xxl-4{gap:1.5rem !important}.gap-xxl-5{gap:3rem !important}.row-gap-xxl-0{row-gap:0 !important}.row-gap-xxl-1{row-gap:.25rem !important}.row-gap-xxl-2{row-gap:.5rem !important}.row-gap-xxl-3{row-gap:1rem !important}.row-gap-xxl-4{row-gap:1.5rem !important}.row-gap-xxl-5{row-gap:3rem !important}.column-gap-xxl-0{column-gap:0 !important}.column-gap-xxl-1{column-gap:.25rem !important}.column-gap-xxl-2{column-gap:.5rem !important}.column-gap-xxl-3{column-gap:1rem !important}.column-gap-xxl-4{column-gap:1.5rem !important}.column-gap-xxl-5{column-gap:3rem !important}.text-xxl-start{text-align:left !important}.text-xxl-end{text-align:right !important}.text-xxl-center{text-align:center !important}}.bg-default{color:#fff}.bg-primary{color:#fff}.bg-secondary{color:#fff}.bg-success{color:#fff}.bg-info{color:#fff}.bg-warning{color:#fff}.bg-danger{color:#fff}.bg-light{color:#000}.bg-dark{color:#fff}@media(min-width: 1200px){.fs-1{font-size:2rem !important}.fs-2{font-size:1.65rem !important}.fs-3{font-size:1.45rem !important}}@media print{.d-print-inline{display:inline !important}.d-print-inline-block{display:inline-block !important}.d-print-block{display:block !important}.d-print-grid{display:grid !important}.d-print-inline-grid{display:inline-grid !important}.d-print-table{display:table !important}.d-print-table-row{display:table-row !important}.d-print-table-cell{display:table-cell !important}.d-print-flex{display:flex !important}.d-print-inline-flex{display:inline-flex !important}.d-print-none{display:none !important}}:root{--bslib-spacer: 1rem;--bslib-mb-spacer: var(--bslib-spacer, 1rem)}.bslib-mb-spacing{margin-bottom:var(--bslib-mb-spacer)}.bslib-gap-spacing{gap:var(--bslib-mb-spacer)}.bslib-gap-spacing>.bslib-mb-spacing,.bslib-gap-spacing>.form-group,.bslib-gap-spacing>p,.bslib-gap-spacing>pre{margin-bottom:0}.html-fill-container>.html-fill-item.bslib-mb-spacing{margin-bottom:0}.tab-content>.tab-pane.html-fill-container{display:none}.tab-content>.active.html-fill-container{display:flex}.tab-content.html-fill-container{padding:0}.bg-blue{--bslib-color-bg: #2780e3;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-blue{--bslib-color-fg: #2780e3;color:var(--bslib-color-fg)}.bg-indigo{--bslib-color-bg: #6610f2;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-indigo{--bslib-color-fg: #6610f2;color:var(--bslib-color-fg)}.bg-purple{--bslib-color-bg: #613d7c;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-purple{--bslib-color-fg: #613d7c;color:var(--bslib-color-fg)}.bg-pink{--bslib-color-bg: #e83e8c;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-pink{--bslib-color-fg: #e83e8c;color:var(--bslib-color-fg)}.bg-red{--bslib-color-bg: #ff0039;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-red{--bslib-color-fg: #ff0039;color:var(--bslib-color-fg)}.bg-orange{--bslib-color-bg: #f0ad4e;--bslib-color-fg: #000;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-orange{--bslib-color-fg: #f0ad4e;color:var(--bslib-color-fg)}.bg-yellow{--bslib-color-bg: #ff7518;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-yellow{--bslib-color-fg: #ff7518;color:var(--bslib-color-fg)}.bg-green{--bslib-color-bg: #3fb618;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-green{--bslib-color-fg: #3fb618;color:var(--bslib-color-fg)}.bg-teal{--bslib-color-bg: #20c997;--bslib-color-fg: #000;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-teal{--bslib-color-fg: #20c997;color:var(--bslib-color-fg)}.bg-cyan{--bslib-color-bg: #9954bb;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-cyan{--bslib-color-fg: #9954bb;color:var(--bslib-color-fg)}.text-default{--bslib-color-fg: #343a40}.bg-default{--bslib-color-bg: #343a40;--bslib-color-fg: #fff}.text-primary{--bslib-color-fg: #2780e3}.bg-primary{--bslib-color-bg: #2780e3;--bslib-color-fg: #fff}.text-secondary{--bslib-color-fg: #343a40}.bg-secondary{--bslib-color-bg: #343a40;--bslib-color-fg: #fff}.text-success{--bslib-color-fg: #3fb618}.bg-success{--bslib-color-bg: #3fb618;--bslib-color-fg: #fff}.text-info{--bslib-color-fg: #9954bb}.bg-info{--bslib-color-bg: #9954bb;--bslib-color-fg: #fff}.text-warning{--bslib-color-fg: #ff7518}.bg-warning{--bslib-color-bg: #ff7518;--bslib-color-fg: #fff}.text-danger{--bslib-color-fg: #ff0039}.bg-danger{--bslib-color-bg: #ff0039;--bslib-color-fg: #fff}.text-light{--bslib-color-fg: #f8f9fa}.bg-light{--bslib-color-bg: #f8f9fa;--bslib-color-fg: #000}.text-dark{--bslib-color-fg: #343a40}.bg-dark{--bslib-color-bg: #343a40;--bslib-color-fg: #fff}.bg-gradient-blue-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #4053e9;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #4053e9;color:#fff}.bg-gradient-blue-purple{--bslib-color-fg: #fff;--bslib-color-bg: #3e65ba;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #3e65ba;color:#fff}.bg-gradient-blue-pink{--bslib-color-fg: #fff;--bslib-color-bg: #7466c0;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #7466c0;color:#fff}.bg-gradient-blue-red{--bslib-color-fg: #fff;--bslib-color-bg: #7d4d9f;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #7d4d9f;color:#fff}.bg-gradient-blue-orange{--bslib-color-fg: #fff;--bslib-color-bg: #7792a7;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #7792a7;color:#fff}.bg-gradient-blue-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #7d7c92;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #7d7c92;color:#fff}.bg-gradient-blue-green{--bslib-color-fg: #fff;--bslib-color-bg: #319692;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #319692;color:#fff}.bg-gradient-blue-teal{--bslib-color-fg: #fff;--bslib-color-bg: #249dc5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #249dc5;color:#fff}.bg-gradient-blue-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #556ed3;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #556ed3;color:#fff}.bg-gradient-indigo-blue{--bslib-color-fg: #fff;--bslib-color-bg: #4d3dec;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #4d3dec;color:#fff}.bg-gradient-indigo-purple{--bslib-color-fg: #fff;--bslib-color-bg: #6422c3;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #6422c3;color:#fff}.bg-gradient-indigo-pink{--bslib-color-fg: #fff;--bslib-color-bg: #9a22c9;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #9a22c9;color:#fff}.bg-gradient-indigo-red{--bslib-color-fg: #fff;--bslib-color-bg: #a30aa8;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #a30aa8;color:#fff}.bg-gradient-indigo-orange{--bslib-color-fg: #fff;--bslib-color-bg: #9d4fb0;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #9d4fb0;color:#fff}.bg-gradient-indigo-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #a3389b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #a3389b;color:#fff}.bg-gradient-indigo-green{--bslib-color-fg: #fff;--bslib-color-bg: #56529b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #56529b;color:#fff}.bg-gradient-indigo-teal{--bslib-color-fg: #fff;--bslib-color-bg: #4a5ace;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #4a5ace;color:#fff}.bg-gradient-indigo-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #7a2bdc;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #7a2bdc;color:#fff}.bg-gradient-purple-blue{--bslib-color-fg: #fff;--bslib-color-bg: #4a58a5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #4a58a5;color:#fff}.bg-gradient-purple-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #632bab;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #632bab;color:#fff}.bg-gradient-purple-pink{--bslib-color-fg: #fff;--bslib-color-bg: #973d82;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #973d82;color:#fff}.bg-gradient-purple-red{--bslib-color-fg: #fff;--bslib-color-bg: #a02561;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #a02561;color:#fff}.bg-gradient-purple-orange{--bslib-color-fg: #fff;--bslib-color-bg: #9a6a6a;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #9a6a6a;color:#fff}.bg-gradient-purple-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #a05354;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #a05354;color:#fff}.bg-gradient-purple-green{--bslib-color-fg: #fff;--bslib-color-bg: #536d54;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #536d54;color:#fff}.bg-gradient-purple-teal{--bslib-color-fg: #fff;--bslib-color-bg: #477587;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #477587;color:#fff}.bg-gradient-purple-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #774695;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #774695;color:#fff}.bg-gradient-pink-blue{--bslib-color-fg: #fff;--bslib-color-bg: #9b58af;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #9b58af;color:#fff}.bg-gradient-pink-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #b42cb5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #b42cb5;color:#fff}.bg-gradient-pink-purple{--bslib-color-fg: #fff;--bslib-color-bg: #b23e86;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #b23e86;color:#fff}.bg-gradient-pink-red{--bslib-color-fg: #fff;--bslib-color-bg: #f1256b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #f1256b;color:#fff}.bg-gradient-pink-orange{--bslib-color-fg: #fff;--bslib-color-bg: #eb6a73;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #eb6a73;color:#fff}.bg-gradient-pink-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #f1545e;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #f1545e;color:#fff}.bg-gradient-pink-green{--bslib-color-fg: #fff;--bslib-color-bg: #a46e5e;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #a46e5e;color:#fff}.bg-gradient-pink-teal{--bslib-color-fg: #fff;--bslib-color-bg: #987690;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #987690;color:#fff}.bg-gradient-pink-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #c8479f;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #c8479f;color:#fff}.bg-gradient-red-blue{--bslib-color-fg: #fff;--bslib-color-bg: #a9337d;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #a9337d;color:#fff}.bg-gradient-red-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #c20683;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #c20683;color:#fff}.bg-gradient-red-purple{--bslib-color-fg: #fff;--bslib-color-bg: #c01854;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #c01854;color:#fff}.bg-gradient-red-pink{--bslib-color-fg: #fff;--bslib-color-bg: #f6195a;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #f6195a;color:#fff}.bg-gradient-red-orange{--bslib-color-fg: #fff;--bslib-color-bg: #f94541;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #f94541;color:#fff}.bg-gradient-red-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #ff2f2c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #ff2f2c;color:#fff}.bg-gradient-red-green{--bslib-color-fg: #fff;--bslib-color-bg: #b2492c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #b2492c;color:#fff}.bg-gradient-red-teal{--bslib-color-fg: #fff;--bslib-color-bg: #a6505f;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #a6505f;color:#fff}.bg-gradient-red-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #d6226d;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #d6226d;color:#fff}.bg-gradient-orange-blue{--bslib-color-fg: #fff;--bslib-color-bg: #a09b8a;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #a09b8a;color:#fff}.bg-gradient-orange-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #b96e90;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #b96e90;color:#fff}.bg-gradient-orange-purple{--bslib-color-fg: #fff;--bslib-color-bg: #b78060;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #b78060;color:#fff}.bg-gradient-orange-pink{--bslib-color-fg: #fff;--bslib-color-bg: #ed8167;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #ed8167;color:#fff}.bg-gradient-orange-red{--bslib-color-fg: #fff;--bslib-color-bg: #f66846;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #f66846;color:#fff}.bg-gradient-orange-yellow{--bslib-color-fg: #000;--bslib-color-bg: #f69738;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #f69738;color:#000}.bg-gradient-orange-green{--bslib-color-fg: #000;--bslib-color-bg: #a9b138;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #a9b138;color:#000}.bg-gradient-orange-teal{--bslib-color-fg: #000;--bslib-color-bg: #9db86b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #9db86b;color:#000}.bg-gradient-orange-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #cd897a;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #cd897a;color:#fff}.bg-gradient-yellow-blue{--bslib-color-fg: #fff;--bslib-color-bg: #a97969;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #a97969;color:#fff}.bg-gradient-yellow-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #c24d6f;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #c24d6f;color:#fff}.bg-gradient-yellow-purple{--bslib-color-fg: #fff;--bslib-color-bg: #c05f40;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #c05f40;color:#fff}.bg-gradient-yellow-pink{--bslib-color-fg: #fff;--bslib-color-bg: #f65f46;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #f65f46;color:#fff}.bg-gradient-yellow-red{--bslib-color-fg: #fff;--bslib-color-bg: #ff4625;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #ff4625;color:#fff}.bg-gradient-yellow-orange{--bslib-color-fg: #000;--bslib-color-bg: #f98b2e;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #f98b2e;color:#000}.bg-gradient-yellow-green{--bslib-color-fg: #fff;--bslib-color-bg: #b28f18;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #b28f18;color:#fff}.bg-gradient-yellow-teal{--bslib-color-fg: #fff;--bslib-color-bg: #a6974b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #a6974b;color:#fff}.bg-gradient-yellow-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #d66859;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #d66859;color:#fff}.bg-gradient-green-blue{--bslib-color-fg: #fff;--bslib-color-bg: #35a069;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #35a069;color:#fff}.bg-gradient-green-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #4f746f;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #4f746f;color:#fff}.bg-gradient-green-purple{--bslib-color-fg: #fff;--bslib-color-bg: #4d8640;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #4d8640;color:#fff}.bg-gradient-green-pink{--bslib-color-fg: #fff;--bslib-color-bg: #838646;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #838646;color:#fff}.bg-gradient-green-red{--bslib-color-fg: #fff;--bslib-color-bg: #8c6d25;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #8c6d25;color:#fff}.bg-gradient-green-orange{--bslib-color-fg: #000;--bslib-color-bg: #86b22e;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #86b22e;color:#000}.bg-gradient-green-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #8c9c18;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #8c9c18;color:#fff}.bg-gradient-green-teal{--bslib-color-fg: #000;--bslib-color-bg: #33be4b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #33be4b;color:#000}.bg-gradient-green-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #638f59;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #638f59;color:#fff}.bg-gradient-teal-blue{--bslib-color-fg: #fff;--bslib-color-bg: #23acb5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #23acb5;color:#fff}.bg-gradient-teal-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #3c7fbb;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #3c7fbb;color:#fff}.bg-gradient-teal-purple{--bslib-color-fg: #fff;--bslib-color-bg: #3a918c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #3a918c;color:#fff}.bg-gradient-teal-pink{--bslib-color-fg: #fff;--bslib-color-bg: #709193;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #709193;color:#fff}.bg-gradient-teal-red{--bslib-color-fg: #fff;--bslib-color-bg: #797971;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #797971;color:#fff}.bg-gradient-teal-orange{--bslib-color-fg: #000;--bslib-color-bg: #73be7a;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #73be7a;color:#000}.bg-gradient-teal-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #79a764;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #79a764;color:#fff}.bg-gradient-teal-green{--bslib-color-fg: #000;--bslib-color-bg: #2cc164;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #2cc164;color:#000}.bg-gradient-teal-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #509aa5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #509aa5;color:#fff}.bg-gradient-cyan-blue{--bslib-color-fg: #fff;--bslib-color-bg: #6b66cb;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #6b66cb;color:#fff}.bg-gradient-cyan-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #8539d1;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #8539d1;color:#fff}.bg-gradient-cyan-purple{--bslib-color-fg: #fff;--bslib-color-bg: #834ba2;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #834ba2;color:#fff}.bg-gradient-cyan-pink{--bslib-color-fg: #fff;--bslib-color-bg: #b94ba8;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #b94ba8;color:#fff}.bg-gradient-cyan-red{--bslib-color-fg: #fff;--bslib-color-bg: #c23287;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #c23287;color:#fff}.bg-gradient-cyan-orange{--bslib-color-fg: #fff;--bslib-color-bg: #bc788f;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #bc788f;color:#fff}.bg-gradient-cyan-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #c2617a;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #c2617a;color:#fff}.bg-gradient-cyan-green{--bslib-color-fg: #fff;--bslib-color-bg: #757b7a;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #757b7a;color:#fff}.bg-gradient-cyan-teal{--bslib-color-fg: #fff;--bslib-color-bg: #6983ad;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #6983ad;color:#fff}.bg-blue{--bslib-color-bg: #2780e3;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-blue{--bslib-color-fg: #2780e3;color:var(--bslib-color-fg)}.bg-indigo{--bslib-color-bg: #6610f2;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-indigo{--bslib-color-fg: #6610f2;color:var(--bslib-color-fg)}.bg-purple{--bslib-color-bg: #613d7c;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-purple{--bslib-color-fg: #613d7c;color:var(--bslib-color-fg)}.bg-pink{--bslib-color-bg: #e83e8c;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-pink{--bslib-color-fg: #e83e8c;color:var(--bslib-color-fg)}.bg-red{--bslib-color-bg: #ff0039;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-red{--bslib-color-fg: #ff0039;color:var(--bslib-color-fg)}.bg-orange{--bslib-color-bg: #f0ad4e;--bslib-color-fg: #000;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-orange{--bslib-color-fg: #f0ad4e;color:var(--bslib-color-fg)}.bg-yellow{--bslib-color-bg: #ff7518;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-yellow{--bslib-color-fg: #ff7518;color:var(--bslib-color-fg)}.bg-green{--bslib-color-bg: #3fb618;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-green{--bslib-color-fg: #3fb618;color:var(--bslib-color-fg)}.bg-teal{--bslib-color-bg: #20c997;--bslib-color-fg: #000;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-teal{--bslib-color-fg: #20c997;color:var(--bslib-color-fg)}.bg-cyan{--bslib-color-bg: #9954bb;--bslib-color-fg: #fff;background-color:var(--bslib-color-bg);color:var(--bslib-color-fg)}.text-cyan{--bslib-color-fg: #9954bb;color:var(--bslib-color-fg)}.text-default{--bslib-color-fg: #343a40}.bg-default{--bslib-color-bg: #343a40;--bslib-color-fg: #fff}.text-primary{--bslib-color-fg: #2780e3}.bg-primary{--bslib-color-bg: #2780e3;--bslib-color-fg: #fff}.text-secondary{--bslib-color-fg: #343a40}.bg-secondary{--bslib-color-bg: #343a40;--bslib-color-fg: #fff}.text-success{--bslib-color-fg: #3fb618}.bg-success{--bslib-color-bg: #3fb618;--bslib-color-fg: #fff}.text-info{--bslib-color-fg: #9954bb}.bg-info{--bslib-color-bg: #9954bb;--bslib-color-fg: #fff}.text-warning{--bslib-color-fg: #ff7518}.bg-warning{--bslib-color-bg: #ff7518;--bslib-color-fg: #fff}.text-danger{--bslib-color-fg: #ff0039}.bg-danger{--bslib-color-bg: #ff0039;--bslib-color-fg: #fff}.text-light{--bslib-color-fg: #f8f9fa}.bg-light{--bslib-color-bg: #f8f9fa;--bslib-color-fg: #000}.text-dark{--bslib-color-fg: #343a40}.bg-dark{--bslib-color-bg: #343a40;--bslib-color-fg: #fff}.bg-gradient-blue-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #4053e9;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #4053e9;color:#fff}.bg-gradient-blue-purple{--bslib-color-fg: #fff;--bslib-color-bg: #3e65ba;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #3e65ba;color:#fff}.bg-gradient-blue-pink{--bslib-color-fg: #fff;--bslib-color-bg: #7466c0;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #7466c0;color:#fff}.bg-gradient-blue-red{--bslib-color-fg: #fff;--bslib-color-bg: #7d4d9f;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #7d4d9f;color:#fff}.bg-gradient-blue-orange{--bslib-color-fg: #fff;--bslib-color-bg: #7792a7;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #7792a7;color:#fff}.bg-gradient-blue-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #7d7c92;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #7d7c92;color:#fff}.bg-gradient-blue-green{--bslib-color-fg: #fff;--bslib-color-bg: #319692;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #319692;color:#fff}.bg-gradient-blue-teal{--bslib-color-fg: #fff;--bslib-color-bg: #249dc5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #249dc5;color:#fff}.bg-gradient-blue-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #556ed3;background:linear-gradient(var(--bg-gradient-deg, 140deg), #2780e3 var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #556ed3;color:#fff}.bg-gradient-indigo-blue{--bslib-color-fg: #fff;--bslib-color-bg: #4d3dec;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #4d3dec;color:#fff}.bg-gradient-indigo-purple{--bslib-color-fg: #fff;--bslib-color-bg: #6422c3;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #6422c3;color:#fff}.bg-gradient-indigo-pink{--bslib-color-fg: #fff;--bslib-color-bg: #9a22c9;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #9a22c9;color:#fff}.bg-gradient-indigo-red{--bslib-color-fg: #fff;--bslib-color-bg: #a30aa8;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #a30aa8;color:#fff}.bg-gradient-indigo-orange{--bslib-color-fg: #fff;--bslib-color-bg: #9d4fb0;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #9d4fb0;color:#fff}.bg-gradient-indigo-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #a3389b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #a3389b;color:#fff}.bg-gradient-indigo-green{--bslib-color-fg: #fff;--bslib-color-bg: #56529b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #56529b;color:#fff}.bg-gradient-indigo-teal{--bslib-color-fg: #fff;--bslib-color-bg: #4a5ace;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #4a5ace;color:#fff}.bg-gradient-indigo-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #7a2bdc;background:linear-gradient(var(--bg-gradient-deg, 140deg), #6610f2 var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #7a2bdc;color:#fff}.bg-gradient-purple-blue{--bslib-color-fg: #fff;--bslib-color-bg: #4a58a5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #4a58a5;color:#fff}.bg-gradient-purple-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #632bab;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #632bab;color:#fff}.bg-gradient-purple-pink{--bslib-color-fg: #fff;--bslib-color-bg: #973d82;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #973d82;color:#fff}.bg-gradient-purple-red{--bslib-color-fg: #fff;--bslib-color-bg: #a02561;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #a02561;color:#fff}.bg-gradient-purple-orange{--bslib-color-fg: #fff;--bslib-color-bg: #9a6a6a;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #9a6a6a;color:#fff}.bg-gradient-purple-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #a05354;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #a05354;color:#fff}.bg-gradient-purple-green{--bslib-color-fg: #fff;--bslib-color-bg: #536d54;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #536d54;color:#fff}.bg-gradient-purple-teal{--bslib-color-fg: #fff;--bslib-color-bg: #477587;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #477587;color:#fff}.bg-gradient-purple-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #774695;background:linear-gradient(var(--bg-gradient-deg, 140deg), #613d7c var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #774695;color:#fff}.bg-gradient-pink-blue{--bslib-color-fg: #fff;--bslib-color-bg: #9b58af;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #9b58af;color:#fff}.bg-gradient-pink-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #b42cb5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #b42cb5;color:#fff}.bg-gradient-pink-purple{--bslib-color-fg: #fff;--bslib-color-bg: #b23e86;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #b23e86;color:#fff}.bg-gradient-pink-red{--bslib-color-fg: #fff;--bslib-color-bg: #f1256b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #f1256b;color:#fff}.bg-gradient-pink-orange{--bslib-color-fg: #fff;--bslib-color-bg: #eb6a73;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #eb6a73;color:#fff}.bg-gradient-pink-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #f1545e;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #f1545e;color:#fff}.bg-gradient-pink-green{--bslib-color-fg: #fff;--bslib-color-bg: #a46e5e;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #a46e5e;color:#fff}.bg-gradient-pink-teal{--bslib-color-fg: #fff;--bslib-color-bg: #987690;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #987690;color:#fff}.bg-gradient-pink-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #c8479f;background:linear-gradient(var(--bg-gradient-deg, 140deg), #e83e8c var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #c8479f;color:#fff}.bg-gradient-red-blue{--bslib-color-fg: #fff;--bslib-color-bg: #a9337d;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #a9337d;color:#fff}.bg-gradient-red-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #c20683;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #c20683;color:#fff}.bg-gradient-red-purple{--bslib-color-fg: #fff;--bslib-color-bg: #c01854;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #c01854;color:#fff}.bg-gradient-red-pink{--bslib-color-fg: #fff;--bslib-color-bg: #f6195a;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #f6195a;color:#fff}.bg-gradient-red-orange{--bslib-color-fg: #fff;--bslib-color-bg: #f94541;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #f94541;color:#fff}.bg-gradient-red-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #ff2f2c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #ff2f2c;color:#fff}.bg-gradient-red-green{--bslib-color-fg: #fff;--bslib-color-bg: #b2492c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #b2492c;color:#fff}.bg-gradient-red-teal{--bslib-color-fg: #fff;--bslib-color-bg: #a6505f;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #a6505f;color:#fff}.bg-gradient-red-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #d6226d;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff0039 var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #d6226d;color:#fff}.bg-gradient-orange-blue{--bslib-color-fg: #fff;--bslib-color-bg: #a09b8a;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #a09b8a;color:#fff}.bg-gradient-orange-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #b96e90;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #b96e90;color:#fff}.bg-gradient-orange-purple{--bslib-color-fg: #fff;--bslib-color-bg: #b78060;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #b78060;color:#fff}.bg-gradient-orange-pink{--bslib-color-fg: #fff;--bslib-color-bg: #ed8167;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #ed8167;color:#fff}.bg-gradient-orange-red{--bslib-color-fg: #fff;--bslib-color-bg: #f66846;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #f66846;color:#fff}.bg-gradient-orange-yellow{--bslib-color-fg: #000;--bslib-color-bg: #f69738;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #f69738;color:#000}.bg-gradient-orange-green{--bslib-color-fg: #000;--bslib-color-bg: #a9b138;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #a9b138;color:#000}.bg-gradient-orange-teal{--bslib-color-fg: #000;--bslib-color-bg: #9db86b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #9db86b;color:#000}.bg-gradient-orange-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #cd897a;background:linear-gradient(var(--bg-gradient-deg, 140deg), #f0ad4e var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #cd897a;color:#fff}.bg-gradient-yellow-blue{--bslib-color-fg: #fff;--bslib-color-bg: #a97969;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #a97969;color:#fff}.bg-gradient-yellow-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #c24d6f;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #c24d6f;color:#fff}.bg-gradient-yellow-purple{--bslib-color-fg: #fff;--bslib-color-bg: #c05f40;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #c05f40;color:#fff}.bg-gradient-yellow-pink{--bslib-color-fg: #fff;--bslib-color-bg: #f65f46;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #f65f46;color:#fff}.bg-gradient-yellow-red{--bslib-color-fg: #fff;--bslib-color-bg: #ff4625;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #ff4625;color:#fff}.bg-gradient-yellow-orange{--bslib-color-fg: #000;--bslib-color-bg: #f98b2e;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #f98b2e;color:#000}.bg-gradient-yellow-green{--bslib-color-fg: #fff;--bslib-color-bg: #b28f18;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #b28f18;color:#fff}.bg-gradient-yellow-teal{--bslib-color-fg: #fff;--bslib-color-bg: #a6974b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #a6974b;color:#fff}.bg-gradient-yellow-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #d66859;background:linear-gradient(var(--bg-gradient-deg, 140deg), #ff7518 var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #d66859;color:#fff}.bg-gradient-green-blue{--bslib-color-fg: #fff;--bslib-color-bg: #35a069;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #35a069;color:#fff}.bg-gradient-green-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #4f746f;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #4f746f;color:#fff}.bg-gradient-green-purple{--bslib-color-fg: #fff;--bslib-color-bg: #4d8640;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #4d8640;color:#fff}.bg-gradient-green-pink{--bslib-color-fg: #fff;--bslib-color-bg: #838646;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #838646;color:#fff}.bg-gradient-green-red{--bslib-color-fg: #fff;--bslib-color-bg: #8c6d25;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #8c6d25;color:#fff}.bg-gradient-green-orange{--bslib-color-fg: #000;--bslib-color-bg: #86b22e;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #86b22e;color:#000}.bg-gradient-green-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #8c9c18;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #8c9c18;color:#fff}.bg-gradient-green-teal{--bslib-color-fg: #000;--bslib-color-bg: #33be4b;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #33be4b;color:#000}.bg-gradient-green-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #638f59;background:linear-gradient(var(--bg-gradient-deg, 140deg), #3fb618 var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #638f59;color:#fff}.bg-gradient-teal-blue{--bslib-color-fg: #fff;--bslib-color-bg: #23acb5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #23acb5;color:#fff}.bg-gradient-teal-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #3c7fbb;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #3c7fbb;color:#fff}.bg-gradient-teal-purple{--bslib-color-fg: #fff;--bslib-color-bg: #3a918c;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #3a918c;color:#fff}.bg-gradient-teal-pink{--bslib-color-fg: #fff;--bslib-color-bg: #709193;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #709193;color:#fff}.bg-gradient-teal-red{--bslib-color-fg: #fff;--bslib-color-bg: #797971;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #797971;color:#fff}.bg-gradient-teal-orange{--bslib-color-fg: #000;--bslib-color-bg: #73be7a;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #73be7a;color:#000}.bg-gradient-teal-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #79a764;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #79a764;color:#fff}.bg-gradient-teal-green{--bslib-color-fg: #000;--bslib-color-bg: #2cc164;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #2cc164;color:#000}.bg-gradient-teal-cyan{--bslib-color-fg: #fff;--bslib-color-bg: #509aa5;background:linear-gradient(var(--bg-gradient-deg, 140deg), #20c997 var(--bg-gradient-start, 36%), #9954bb var(--bg-gradient-end, 180%)) #509aa5;color:#fff}.bg-gradient-cyan-blue{--bslib-color-fg: #fff;--bslib-color-bg: #6b66cb;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #2780e3 var(--bg-gradient-end, 180%)) #6b66cb;color:#fff}.bg-gradient-cyan-indigo{--bslib-color-fg: #fff;--bslib-color-bg: #8539d1;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #6610f2 var(--bg-gradient-end, 180%)) #8539d1;color:#fff}.bg-gradient-cyan-purple{--bslib-color-fg: #fff;--bslib-color-bg: #834ba2;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #613d7c var(--bg-gradient-end, 180%)) #834ba2;color:#fff}.bg-gradient-cyan-pink{--bslib-color-fg: #fff;--bslib-color-bg: #b94ba8;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #e83e8c var(--bg-gradient-end, 180%)) #b94ba8;color:#fff}.bg-gradient-cyan-red{--bslib-color-fg: #fff;--bslib-color-bg: #c23287;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #ff0039 var(--bg-gradient-end, 180%)) #c23287;color:#fff}.bg-gradient-cyan-orange{--bslib-color-fg: #fff;--bslib-color-bg: #bc788f;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #f0ad4e var(--bg-gradient-end, 180%)) #bc788f;color:#fff}.bg-gradient-cyan-yellow{--bslib-color-fg: #fff;--bslib-color-bg: #c2617a;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #ff7518 var(--bg-gradient-end, 180%)) #c2617a;color:#fff}.bg-gradient-cyan-green{--bslib-color-fg: #fff;--bslib-color-bg: #757b7a;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #3fb618 var(--bg-gradient-end, 180%)) #757b7a;color:#fff}.bg-gradient-cyan-teal{--bslib-color-fg: #fff;--bslib-color-bg: #6983ad;background:linear-gradient(var(--bg-gradient-deg, 140deg), #9954bb var(--bg-gradient-start, 36%), #20c997 var(--bg-gradient-end, 180%)) #6983ad;color:#fff}:root{--bslib-spacer: 1rem;--bslib-mb-spacer: var(--bslib-spacer, 1rem)}.bslib-mb-spacing{margin-bottom:var(--bslib-mb-spacer)}.bslib-gap-spacing{gap:var(--bslib-mb-spacer)}.bslib-gap-spacing>.bslib-mb-spacing,.bslib-gap-spacing>.form-group,.bslib-gap-spacing>p,.bslib-gap-spacing>pre{margin-bottom:0}.html-fill-container>.html-fill-item.bslib-mb-spacing{margin-bottom:0}.tab-content>.tab-pane.html-fill-container{display:none}.tab-content>.active.html-fill-container{display:flex}.tab-content.html-fill-container{padding:0}.accordion .accordion-header{font-size:calc(1.29rem + 0.48vw);margin-top:0;margin-bottom:.5rem;font-weight:400;line-height:1.2;color:var(--bs-heading-color);margin-bottom:0}@media(min-width: 1200px){.accordion .accordion-header{font-size:1.65rem}}.accordion .accordion-icon:not(:empty){margin-right:.75rem;display:flex}.accordion .accordion-button:not(.collapsed){box-shadow:none}.accordion .accordion-button:not(.collapsed):focus{box-shadow:var(--bs-accordion-btn-focus-box-shadow)}.bslib-card{overflow:auto}.bslib-card .card-body+.card-body{padding-top:0}.bslib-card .card-body{overflow:auto}.bslib-card .card-body p{margin-top:0}.bslib-card .card-body p:last-child{margin-bottom:0}.bslib-card .card-body{max-height:var(--bslib-card-body-max-height, none)}.bslib-card[data-full-screen=true]>.card-body{max-height:var(--bslib-card-body-max-height-full-screen, none)}.bslib-card .card-header .form-group{margin-bottom:0}.bslib-card .card-header .selectize-control{margin-bottom:0}.bslib-card .card-header .selectize-control .item{margin-right:1.15rem}.bslib-card .card-footer{margin-top:auto}.bslib-card .bslib-navs-card-title{display:flex;flex-wrap:wrap;justify-content:space-between;align-items:center}.bslib-card .bslib-navs-card-title .nav{margin-left:auto}.bslib-card .bslib-sidebar-layout:not([data-bslib-sidebar-border=true]){border:none}.bslib-card .bslib-sidebar-layout:not([data-bslib-sidebar-border-radius=true]){border-top-left-radius:0;border-top-right-radius:0}[data-full-screen=true]{position:fixed;inset:3.5rem 1rem 1rem;height:auto !important;max-height:none !important;width:auto !important;z-index:1070}.bslib-full-screen-enter{display:none;position:absolute;bottom:var(--bslib-full-screen-enter-bottom, 0.2rem);right:var(--bslib-full-screen-enter-right, 0);top:var(--bslib-full-screen-enter-top);left:var(--bslib-full-screen-enter-left);color:var(--bslib-color-fg, var(--bs-card-color));background-color:var(--bslib-color-bg, var(--bs-card-bg, var(--bs-body-bg)));border:var(--bs-card-border-width) solid var(--bslib-color-fg, var(--bs-card-border-color));box-shadow:0 2px 4px rgba(0,0,0,.15);margin:.2rem .4rem;padding:.55rem !important;font-size:.8rem;cursor:pointer;opacity:.7;z-index:1070}.bslib-full-screen-enter:hover{opacity:1}.card[data-full-screen=false]:hover>*>.bslib-full-screen-enter{display:block}.bslib-has-full-screen .card:hover>*>.bslib-full-screen-enter{display:none}@media(max-width: 575.98px){.bslib-full-screen-enter{display:none !important}}.bslib-full-screen-exit{position:relative;top:1.35rem;font-size:.9rem;cursor:pointer;text-decoration:none;display:flex;float:right;margin-right:2.15rem;align-items:center;color:rgba(var(--bs-body-bg-rgb), 0.8)}.bslib-full-screen-exit:hover{color:rgba(var(--bs-body-bg-rgb), 1)}.bslib-full-screen-exit svg{margin-left:.5rem;font-size:1.5rem}#bslib-full-screen-overlay{position:fixed;inset:0;background-color:rgba(var(--bs-body-color-rgb), 0.6);backdrop-filter:blur(2px);-webkit-backdrop-filter:blur(2px);z-index:1069;animation:bslib-full-screen-overlay-enter 400ms cubic-bezier(0.6, 0.02, 0.65, 1) forwards}@keyframes bslib-full-screen-overlay-enter{0%{opacity:0}100%{opacity:1}}.bslib-grid{display:grid !important;gap:var(--bslib-spacer, 1rem);height:var(--bslib-grid-height)}.bslib-grid.grid{grid-template-columns:repeat(var(--bs-columns, 12), minmax(0, 1fr));grid-template-rows:unset;grid-auto-rows:var(--bslib-grid--row-heights);--bslib-grid--row-heights--xs: unset;--bslib-grid--row-heights--sm: unset;--bslib-grid--row-heights--md: unset;--bslib-grid--row-heights--lg: unset;--bslib-grid--row-heights--xl: unset;--bslib-grid--row-heights--xxl: unset}.bslib-grid.grid.bslib-grid--row-heights--xs{--bslib-grid--row-heights: var(--bslib-grid--row-heights--xs)}@media(min-width: 576px){.bslib-grid.grid.bslib-grid--row-heights--sm{--bslib-grid--row-heights: var(--bslib-grid--row-heights--sm)}}@media(min-width: 768px){.bslib-grid.grid.bslib-grid--row-heights--md{--bslib-grid--row-heights: var(--bslib-grid--row-heights--md)}}@media(min-width: 992px){.bslib-grid.grid.bslib-grid--row-heights--lg{--bslib-grid--row-heights: var(--bslib-grid--row-heights--lg)}}@media(min-width: 1200px){.bslib-grid.grid.bslib-grid--row-heights--xl{--bslib-grid--row-heights: var(--bslib-grid--row-heights--xl)}}@media(min-width: 1400px){.bslib-grid.grid.bslib-grid--row-heights--xxl{--bslib-grid--row-heights: var(--bslib-grid--row-heights--xxl)}}.bslib-grid>*>.shiny-input-container{width:100%}.bslib-grid-item{grid-column:auto/span 1}@media(max-width: 767.98px){.bslib-grid-item{grid-column:1/-1}}@media(max-width: 575.98px){.bslib-grid{grid-template-columns:1fr !important;height:var(--bslib-grid-height-mobile)}.bslib-grid.grid{height:unset !important;grid-auto-rows:var(--bslib-grid--row-heights--xs, auto)}}@media(min-width: 576px){.nav:not(.nav-hidden){display:flex !important;display:-webkit-flex !important}.nav:not(.nav-hidden):not(.nav-stacked):not(.flex-column){float:none !important}.nav:not(.nav-hidden):not(.nav-stacked):not(.flex-column)>.bslib-nav-spacer{margin-left:auto !important}.nav:not(.nav-hidden):not(.nav-stacked):not(.flex-column)>.form-inline{margin-top:auto;margin-bottom:auto}.nav:not(.nav-hidden).nav-stacked{flex-direction:column;-webkit-flex-direction:column;height:100%}.nav:not(.nav-hidden).nav-stacked>.bslib-nav-spacer{margin-top:auto !important}}html{height:100%}.bslib-page-fill{width:100%;height:100%;margin:0;padding:var(--bslib-spacer, 1rem);gap:var(--bslib-spacer, 1rem)}@media(max-width: 575.98px){.bslib-page-fill{height:var(--bslib-page-fill-mobile-height, auto)}}.navbar+.container-fluid:has(>.tab-content>.tab-pane.active.html-fill-container),.navbar+.container-sm:has(>.tab-content>.tab-pane.active.html-fill-container),.navbar+.container-md:has(>.tab-content>.tab-pane.active.html-fill-container),.navbar+.container-lg:has(>.tab-content>.tab-pane.active.html-fill-container),.navbar+.container-xl:has(>.tab-content>.tab-pane.active.html-fill-container),.navbar+.container-xxl:has(>.tab-content>.tab-pane.active.html-fill-container){padding-left:0;padding-right:0}.navbar+.container-fluid>.tab-content>.tab-pane.active.html-fill-container,.navbar+.container-sm>.tab-content>.tab-pane.active.html-fill-container,.navbar+.container-md>.tab-content>.tab-pane.active.html-fill-container,.navbar+.container-lg>.tab-content>.tab-pane.active.html-fill-container,.navbar+.container-xl>.tab-content>.tab-pane.active.html-fill-container,.navbar+.container-xxl>.tab-content>.tab-pane.active.html-fill-container{padding:var(--bslib-spacer, 1rem);gap:var(--bslib-spacer, 1rem)}.navbar+.container-fluid>.tab-content>.tab-pane.active.html-fill-container:has(>.bslib-sidebar-layout:only-child),.navbar+.container-sm>.tab-content>.tab-pane.active.html-fill-container:has(>.bslib-sidebar-layout:only-child),.navbar+.container-md>.tab-content>.tab-pane.active.html-fill-container:has(>.bslib-sidebar-layout:only-child),.navbar+.container-lg>.tab-content>.tab-pane.active.html-fill-container:has(>.bslib-sidebar-layout:only-child),.navbar+.container-xl>.tab-content>.tab-pane.active.html-fill-container:has(>.bslib-sidebar-layout:only-child),.navbar+.container-xxl>.tab-content>.tab-pane.active.html-fill-container:has(>.bslib-sidebar-layout:only-child){padding:0}.navbar+.container-fluid>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border=true]),.navbar+.container-sm>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border=true]),.navbar+.container-md>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border=true]),.navbar+.container-lg>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border=true]),.navbar+.container-xl>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border=true]),.navbar+.container-xxl>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border=true]){border-left:none;border-right:none;border-bottom:none}.navbar+.container-fluid>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border-radius=true]),.navbar+.container-sm>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border-radius=true]),.navbar+.container-md>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border-radius=true]),.navbar+.container-lg>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border-radius=true]),.navbar+.container-xl>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border-radius=true]),.navbar+.container-xxl>.tab-content>.tab-pane.active.html-fill-container>.bslib-sidebar-layout:only-child:not([data-bslib-sidebar-border-radius=true]){border-radius:0}.navbar+div>.bslib-sidebar-layout{border-top:var(--bslib-sidebar-border)}:root{--bslib-page-sidebar-title-bg: #f8f9fa;--bslib-page-sidebar-title-color: #000}.bslib-page-title{background-color:var(--bslib-page-sidebar-title-bg);color:var(--bslib-page-sidebar-title-color);font-size:1.25rem;font-weight:300;padding:var(--bslib-spacer, 1rem);padding-left:1.5rem;margin-bottom:0;border-bottom:1px solid #dee2e6}.bslib-sidebar-layout{--bslib-sidebar-transition-duration: 500ms;--bslib-sidebar-transition-easing-x: cubic-bezier(0.8, 0.78, 0.22, 1.07);--bslib-sidebar-border: var(--bs-card-border-width, 1px) solid var(--bs-card-border-color, rgba(0, 0, 0, 0.175));--bslib-sidebar-border-radius: var(--bs-border-radius);--bslib-sidebar-vert-border: var(--bs-card-border-width, 1px) solid var(--bs-card-border-color, rgba(0, 0, 0, 0.175));--bslib-sidebar-bg: rgba(var(--bs-emphasis-color-rgb, 0, 0, 0), 0.05);--bslib-sidebar-fg: var(--bs-emphasis-color, black);--bslib-sidebar-main-fg: var(--bs-card-color, var(--bs-body-color));--bslib-sidebar-main-bg: var(--bs-card-bg, var(--bs-body-bg));--bslib-sidebar-toggle-bg: rgba(var(--bs-emphasis-color-rgb, 0, 0, 0), 0.1);--bslib-sidebar-padding: calc(var(--bslib-spacer) * 1.5);--bslib-sidebar-icon-size: var(--bslib-spacer, 1rem);--bslib-sidebar-icon-button-size: calc(var(--bslib-sidebar-icon-size, 1rem) * 2);--bslib-sidebar-padding-icon: calc(var(--bslib-sidebar-icon-button-size, 2rem) * 1.5);--bslib-collapse-toggle-border-radius: var(--bs-border-radius, 0.25rem);--bslib-collapse-toggle-transform: 0deg;--bslib-sidebar-toggle-transition-easing: cubic-bezier(1, 0, 0, 1);--bslib-collapse-toggle-right-transform: 180deg;--bslib-sidebar-column-main: minmax(0, 1fr);display:grid !important;grid-template-columns:min(100% - var(--bslib-sidebar-icon-size),var(--bslib-sidebar-width, 250px)) var(--bslib-sidebar-column-main);position:relative;transition:grid-template-columns ease-in-out var(--bslib-sidebar-transition-duration);border:var(--bslib-sidebar-border);border-radius:var(--bslib-sidebar-border-radius)}@media(prefers-reduced-motion: reduce){.bslib-sidebar-layout{transition:none}}.bslib-sidebar-layout[data-bslib-sidebar-border=false]{border:none}.bslib-sidebar-layout[data-bslib-sidebar-border-radius=false]{border-radius:initial}.bslib-sidebar-layout>.main,.bslib-sidebar-layout>.sidebar{grid-row:1/2;border-radius:inherit;overflow:auto}.bslib-sidebar-layout>.main{grid-column:2/3;border-top-left-radius:0;border-bottom-left-radius:0;padding:var(--bslib-sidebar-padding);transition:padding var(--bslib-sidebar-transition-easing-x) var(--bslib-sidebar-transition-duration);color:var(--bslib-sidebar-main-fg);background-color:var(--bslib-sidebar-main-bg)}.bslib-sidebar-layout>.sidebar{grid-column:1/2;width:100%;height:100%;border-right:var(--bslib-sidebar-vert-border);border-top-right-radius:0;border-bottom-right-radius:0;color:var(--bslib-sidebar-fg);background-color:var(--bslib-sidebar-bg);backdrop-filter:blur(5px)}.bslib-sidebar-layout>.sidebar>.sidebar-content{display:flex;flex-direction:column;gap:var(--bslib-spacer, 1rem);padding:var(--bslib-sidebar-padding);padding-top:var(--bslib-sidebar-padding-icon)}.bslib-sidebar-layout>.sidebar>.sidebar-content>:last-child:not(.sidebar-title){margin-bottom:0}.bslib-sidebar-layout>.sidebar>.sidebar-content>.accordion{margin-left:calc(-1*var(--bslib-sidebar-padding));margin-right:calc(-1*var(--bslib-sidebar-padding))}.bslib-sidebar-layout>.sidebar>.sidebar-content>.accordion:last-child{margin-bottom:calc(-1*var(--bslib-sidebar-padding))}.bslib-sidebar-layout>.sidebar>.sidebar-content>.accordion:not(:last-child){margin-bottom:1rem}.bslib-sidebar-layout>.sidebar>.sidebar-content>.accordion .accordion-body{display:flex;flex-direction:column}.bslib-sidebar-layout>.sidebar>.sidebar-content>.accordion:not(:first-child) .accordion-item:first-child{border-top:var(--bs-accordion-border-width) solid var(--bs-accordion-border-color)}.bslib-sidebar-layout>.sidebar>.sidebar-content>.accordion:not(:last-child) .accordion-item:last-child{border-bottom:var(--bs-accordion-border-width) solid var(--bs-accordion-border-color)}.bslib-sidebar-layout>.sidebar>.sidebar-content.has-accordion>.sidebar-title{border-bottom:none;padding-bottom:0}.bslib-sidebar-layout>.sidebar .shiny-input-container{width:100%}.bslib-sidebar-layout[data-bslib-sidebar-open=always]>.sidebar>.sidebar-content{padding-top:var(--bslib-sidebar-padding)}.bslib-sidebar-layout>.collapse-toggle{grid-row:1/2;grid-column:1/2;display:inline-flex;align-items:center;position:absolute;right:calc(var(--bslib-sidebar-icon-size));top:calc(var(--bslib-sidebar-icon-size, 1rem)/2);border:none;border-radius:var(--bslib-collapse-toggle-border-radius);height:var(--bslib-sidebar-icon-button-size, 2rem);width:var(--bslib-sidebar-icon-button-size, 2rem);display:flex;align-items:center;justify-content:center;padding:0;color:var(--bslib-sidebar-fg);background-color:unset;transition:color var(--bslib-sidebar-transition-easing-x) var(--bslib-sidebar-transition-duration),top var(--bslib-sidebar-transition-easing-x) var(--bslib-sidebar-transition-duration),right var(--bslib-sidebar-transition-easing-x) var(--bslib-sidebar-transition-duration),left var(--bslib-sidebar-transition-easing-x) var(--bslib-sidebar-transition-duration)}.bslib-sidebar-layout>.collapse-toggle:hover{background-color:var(--bslib-sidebar-toggle-bg)}.bslib-sidebar-layout>.collapse-toggle>.collapse-icon{opacity:.8;width:var(--bslib-sidebar-icon-size);height:var(--bslib-sidebar-icon-size);transform:rotateY(var(--bslib-collapse-toggle-transform));transition:transform var(--bslib-sidebar-toggle-transition-easing) var(--bslib-sidebar-transition-duration)}.bslib-sidebar-layout>.collapse-toggle:hover>.collapse-icon{opacity:1}.bslib-sidebar-layout .sidebar-title{font-size:1.25rem;line-height:1.25;margin-top:0;margin-bottom:1rem;padding-bottom:1rem;border-bottom:var(--bslib-sidebar-border)}.bslib-sidebar-layout.sidebar-right{grid-template-columns:var(--bslib-sidebar-column-main) min(100% - var(--bslib-sidebar-icon-size),var(--bslib-sidebar-width, 250px))}.bslib-sidebar-layout.sidebar-right>.main{grid-column:1/2;border-top-right-radius:0;border-bottom-right-radius:0;border-top-left-radius:inherit;border-bottom-left-radius:inherit}.bslib-sidebar-layout.sidebar-right>.sidebar{grid-column:2/3;border-right:none;border-left:var(--bslib-sidebar-vert-border);border-top-left-radius:0;border-bottom-left-radius:0}.bslib-sidebar-layout.sidebar-right>.collapse-toggle{grid-column:2/3;left:var(--bslib-sidebar-icon-size);right:unset;border:var(--bslib-collapse-toggle-border)}.bslib-sidebar-layout.sidebar-right>.collapse-toggle>.collapse-icon{transform:rotateY(var(--bslib-collapse-toggle-right-transform))}.bslib-sidebar-layout.sidebar-collapsed{--bslib-collapse-toggle-transform: 180deg;--bslib-collapse-toggle-right-transform: 0deg;--bslib-sidebar-vert-border: none;grid-template-columns:0 minmax(0, 1fr)}.bslib-sidebar-layout.sidebar-collapsed.sidebar-right{grid-template-columns:minmax(0, 1fr) 0}.bslib-sidebar-layout.sidebar-collapsed:not(.transitioning)>.sidebar>*{display:none}.bslib-sidebar-layout.sidebar-collapsed>.main{border-radius:inherit}.bslib-sidebar-layout.sidebar-collapsed:not(.sidebar-right)>.main{padding-left:var(--bslib-sidebar-padding-icon)}.bslib-sidebar-layout.sidebar-collapsed.sidebar-right>.main{padding-right:var(--bslib-sidebar-padding-icon)}.bslib-sidebar-layout.sidebar-collapsed>.collapse-toggle{color:var(--bslib-sidebar-main-fg);top:calc(var(--bslib-sidebar-overlap-counter, 0)*(var(--bslib-sidebar-icon-size) + var(--bslib-sidebar-padding)) + var(--bslib-sidebar-icon-size, 1rem)/2);right:calc(-2.5*var(--bslib-sidebar-icon-size) - var(--bs-card-border-width, 1px))}.bslib-sidebar-layout.sidebar-collapsed.sidebar-right>.collapse-toggle{left:calc(-2.5*var(--bslib-sidebar-icon-size) - var(--bs-card-border-width, 1px));right:unset}@media(min-width: 576px){.bslib-sidebar-layout.transitioning>.sidebar>.sidebar-content{display:none}}@media(max-width: 575.98px){.bslib-sidebar-layout[data-bslib-sidebar-open=desktop]{--bslib-sidebar-js-init-collapsed: true}.bslib-sidebar-layout>.sidebar,.bslib-sidebar-layout.sidebar-right>.sidebar{border:none}.bslib-sidebar-layout>.main,.bslib-sidebar-layout.sidebar-right>.main{grid-column:1/3}.bslib-sidebar-layout[data-bslib-sidebar-open=always]{display:block !important}.bslib-sidebar-layout[data-bslib-sidebar-open=always]>.sidebar{max-height:var(--bslib-sidebar-max-height-mobile);overflow-y:auto;border-top:var(--bslib-sidebar-vert-border)}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]){grid-template-columns:100% 0}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]):not(.sidebar-collapsed)>.sidebar{z-index:1}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]):not(.sidebar-collapsed)>.collapse-toggle{z-index:1}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]).sidebar-right{grid-template-columns:0 100%}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]).sidebar-collapsed{grid-template-columns:0 100%}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]).sidebar-collapsed.sidebar-right{grid-template-columns:100% 0}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]):not(.sidebar-right)>.main{padding-left:var(--bslib-sidebar-padding-icon)}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]).sidebar-right>.main{padding-right:var(--bslib-sidebar-padding-icon)}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always])>.main{opacity:0;transition:opacity var(--bslib-sidebar-transition-easing-x) var(--bslib-sidebar-transition-duration)}.bslib-sidebar-layout:not([data-bslib-sidebar-open=always]).sidebar-collapsed>.main{opacity:1}}:root{--bslib-value-box-shadow: none;--bslib-value-box-border-width-auto-yes: var(--bslib-value-box-border-width-baseline);--bslib-value-box-border-width-auto-no: 0;--bslib-value-box-border-width-baseline: 1px}.bslib-value-box{border-width:var(--bslib-value-box-border-width-auto-no, var(--bslib-value-box-border-width-baseline));container-name:bslib-value-box;container-type:inline-size}.bslib-value-box.card{box-shadow:var(--bslib-value-box-shadow)}.bslib-value-box.border-auto{border-width:var(--bslib-value-box-border-width-auto-yes, var(--bslib-value-box-border-width-baseline))}.bslib-value-box.default{--bslib-value-box-bg-default: var(--bs-card-bg, #fff);--bslib-value-box-border-color-default: var(--bs-card-border-color, rgba(0, 0, 0, 0.175));color:var(--bslib-value-box-color);background-color:var(--bslib-value-box-bg, var(--bslib-value-box-bg-default));border-color:var(--bslib-value-box-border-color, var(--bslib-value-box-border-color-default))}.bslib-value-box .value-box-grid{display:grid;grid-template-areas:"left right";align-items:center;overflow:hidden}.bslib-value-box .value-box-showcase{height:100%;max-height:var(---bslib-value-box-showcase-max-h, 100%)}.bslib-value-box .value-box-showcase,.bslib-value-box .value-box-showcase>.html-fill-item{width:100%}.bslib-value-box[data-full-screen=true] .value-box-showcase{max-height:var(---bslib-value-box-showcase-max-h-fs, 100%)}@media screen and (min-width: 575.98px){@container bslib-value-box (max-width: 300px){.bslib-value-box:not(.showcase-bottom) .value-box-grid{grid-template-columns:1fr !important;grid-template-rows:auto auto;grid-template-areas:"top" "bottom"}.bslib-value-box:not(.showcase-bottom) .value-box-grid .value-box-showcase{grid-area:top !important}.bslib-value-box:not(.showcase-bottom) .value-box-grid .value-box-area{grid-area:bottom !important;justify-content:end}}}.bslib-value-box .value-box-area{justify-content:center;padding:1.5rem 1rem;font-size:.9rem;font-weight:500}.bslib-value-box .value-box-area *{margin-bottom:0;margin-top:0}.bslib-value-box .value-box-title{font-size:1rem;margin-top:0;margin-bottom:.5rem;font-weight:400;line-height:1.2}.bslib-value-box .value-box-title:empty::after{content:" "}.bslib-value-box .value-box-value{font-size:calc(1.29rem + 0.48vw);margin-top:0;margin-bottom:.5rem;font-weight:400;line-height:1.2}@media(min-width: 1200px){.bslib-value-box .value-box-value{font-size:1.65rem}}.bslib-value-box .value-box-value:empty::after{content:" "}.bslib-value-box .value-box-showcase{align-items:center;justify-content:center;margin-top:auto;margin-bottom:auto;padding:1rem}.bslib-value-box .value-box-showcase .bi,.bslib-value-box .value-box-showcase .fa,.bslib-value-box .value-box-showcase .fab,.bslib-value-box .value-box-showcase .fas,.bslib-value-box .value-box-showcase .far{opacity:.85;min-width:50px;max-width:125%}.bslib-value-box .value-box-showcase .bi,.bslib-value-box .value-box-showcase .fa,.bslib-value-box .value-box-showcase .fab,.bslib-value-box .value-box-showcase .fas,.bslib-value-box .value-box-showcase .far{font-size:4rem}.bslib-value-box.showcase-top-right .value-box-grid{grid-template-columns:1fr var(---bslib-value-box-showcase-w, 50%)}.bslib-value-box.showcase-top-right .value-box-grid .value-box-showcase{grid-area:right;margin-left:auto;align-self:start;align-items:end;padding-left:0;padding-bottom:0}.bslib-value-box.showcase-top-right .value-box-grid .value-box-area{grid-area:left;align-self:end}.bslib-value-box.showcase-top-right[data-full-screen=true] .value-box-grid{grid-template-columns:auto var(---bslib-value-box-showcase-w-fs, 1fr)}.bslib-value-box.showcase-top-right[data-full-screen=true] .value-box-grid>div{align-self:center}.bslib-value-box.showcase-top-right:not([data-full-screen=true]) .value-box-showcase{margin-top:0}@container bslib-value-box (max-width: 300px){.bslib-value-box.showcase-top-right:not([data-full-screen=true]) .value-box-grid .value-box-showcase{padding-left:1rem}}.bslib-value-box.showcase-left-center .value-box-grid{grid-template-columns:var(---bslib-value-box-showcase-w, 30%) auto}.bslib-value-box.showcase-left-center[data-full-screen=true] .value-box-grid{grid-template-columns:var(---bslib-value-box-showcase-w-fs, 1fr) auto}.bslib-value-box.showcase-left-center:not([data-fill-screen=true]) .value-box-grid .value-box-showcase{grid-area:left}.bslib-value-box.showcase-left-center:not([data-fill-screen=true]) .value-box-grid .value-box-area{grid-area:right}.bslib-value-box.showcase-bottom .value-box-grid{grid-template-columns:1fr;grid-template-rows:1fr var(---bslib-value-box-showcase-h, auto);grid-template-areas:"top" "bottom";overflow:hidden}.bslib-value-box.showcase-bottom .value-box-grid .value-box-showcase{grid-area:bottom;padding:0;margin:0}.bslib-value-box.showcase-bottom .value-box-grid .value-box-area{grid-area:top}.bslib-value-box.showcase-bottom[data-full-screen=true] .value-box-grid{grid-template-rows:1fr var(---bslib-value-box-showcase-h-fs, 2fr)}.bslib-value-box.showcase-bottom[data-full-screen=true] .value-box-grid .value-box-showcase{padding:1rem}[data-bs-theme=dark] .bslib-value-box{--bslib-value-box-shadow: 0 0.5rem 1rem rgb(0 0 0 / 50%)}.html-fill-container{display:flex;flex-direction:column;min-height:0;min-width:0}.html-fill-container>.html-fill-item{flex:1 1 auto;min-height:0;min-width:0}.html-fill-container>:not(.html-fill-item){flex:0 0 auto}.sidebar-item .chapter-number{color:#343a40}.quarto-container{min-height:calc(100vh - 132px)}body.hypothesis-enabled #quarto-header{margin-right:16px}footer.footer .nav-footer,#quarto-header>nav{padding-left:1em;padding-right:1em}footer.footer div.nav-footer p:first-child{margin-top:0}footer.footer div.nav-footer p:last-child{margin-bottom:0}#quarto-content>*{padding-top:14px}#quarto-content>#quarto-sidebar-glass{padding-top:0px}@media(max-width: 991.98px){#quarto-content>*{padding-top:0}#quarto-content .subtitle{padding-top:14px}#quarto-content section:first-of-type h2:first-of-type,#quarto-content section:first-of-type .h2:first-of-type{margin-top:1rem}}.headroom-target,header.headroom{will-change:transform;transition:position 200ms linear;transition:all 200ms linear}header.headroom--pinned{transform:translateY(0%)}header.headroom--unpinned{transform:translateY(-100%)}.navbar-container{width:100%}.navbar-brand{overflow:hidden;text-overflow:ellipsis}.navbar-brand-container{max-width:calc(100% - 115px);min-width:0;display:flex;align-items:center}@media(min-width: 992px){.navbar-brand-container{margin-right:1em}}.navbar-brand.navbar-brand-logo{margin-right:4px;display:inline-flex}.navbar-toggler{flex-basis:content;flex-shrink:0}.navbar .navbar-brand-container{order:2}.navbar .navbar-toggler{order:1}.navbar .navbar-container>.navbar-nav{order:20}.navbar .navbar-container>.navbar-brand-container{margin-left:0 !important;margin-right:0 !important}.navbar .navbar-collapse{order:20}.navbar #quarto-search{order:4;margin-left:auto}.navbar .navbar-toggler{margin-right:.5em}.navbar-logo{max-height:24px;width:auto;padding-right:4px}nav .nav-item:not(.compact){padding-top:1px}nav .nav-link i,nav .dropdown-item i{padding-right:1px}.navbar-expand-lg .navbar-nav .nav-link{padding-left:.6rem;padding-right:.6rem}nav .nav-item.compact .nav-link{padding-left:.5rem;padding-right:.5rem;font-size:1.1rem}.navbar .quarto-navbar-tools{order:3}.navbar .quarto-navbar-tools div.dropdown{display:inline-block}.navbar .quarto-navbar-tools .quarto-navigation-tool{color:#545555}.navbar .quarto-navbar-tools .quarto-navigation-tool:hover{color:#1f4eb6}.navbar-nav .dropdown-menu{min-width:220px;font-size:.9rem}.navbar .navbar-nav .nav-link.dropdown-toggle::after{opacity:.75;vertical-align:.175em}.navbar ul.dropdown-menu{padding-top:0;padding-bottom:0}.navbar .dropdown-header{text-transform:uppercase;font-size:.8rem;padding:0 .5rem}.navbar .dropdown-item{padding:.4rem .5rem}.navbar .dropdown-item>i.bi{margin-left:.1rem;margin-right:.25em}.sidebar #quarto-search{margin-top:-1px}.sidebar #quarto-search svg.aa-SubmitIcon{width:16px;height:16px}.sidebar-navigation a{color:inherit}.sidebar-title{margin-top:.25rem;padding-bottom:.5rem;font-size:1.3rem;line-height:1.6rem;visibility:visible}.sidebar-title>a{font-size:inherit;text-decoration:none}.sidebar-title .sidebar-tools-main{margin-top:-6px}@media(max-width: 991.98px){#quarto-sidebar div.sidebar-header{padding-top:.2em}}.sidebar-header-stacked .sidebar-title{margin-top:.6rem}.sidebar-logo{max-width:90%;padding-bottom:.5rem}.sidebar-logo-link{text-decoration:none}.sidebar-navigation li a{text-decoration:none}.sidebar-navigation .quarto-navigation-tool{opacity:.7;font-size:.875rem}#quarto-sidebar>nav>.sidebar-tools-main{margin-left:14px}.sidebar-tools-main{display:inline-flex;margin-left:0px;order:2}.sidebar-tools-main:not(.tools-wide){vertical-align:middle}.sidebar-navigation .quarto-navigation-tool.dropdown-toggle::after{display:none}.sidebar.sidebar-navigation>*{padding-top:1em}.sidebar-item{margin-bottom:.2em;line-height:1rem;margin-top:.4rem}.sidebar-section{padding-left:.5em;padding-bottom:.2em}.sidebar-item .sidebar-item-container{display:flex;justify-content:space-between;cursor:pointer}.sidebar-item-toggle:hover{cursor:pointer}.sidebar-item .sidebar-item-toggle .bi{font-size:.7rem;text-align:center}.sidebar-item .sidebar-item-toggle .bi-chevron-right::before{transition:transform 200ms ease}.sidebar-item .sidebar-item-toggle[aria-expanded=false] .bi-chevron-right::before{transform:none}.sidebar-item .sidebar-item-toggle[aria-expanded=true] .bi-chevron-right::before{transform:rotate(90deg)}.sidebar-item-text{width:100%}.sidebar-navigation .sidebar-divider{margin-left:0;margin-right:0;margin-top:.5rem;margin-bottom:.5rem}@media(max-width: 991.98px){.quarto-secondary-nav{display:block}.quarto-secondary-nav button.quarto-search-button{padding-right:0em;padding-left:2em}.quarto-secondary-nav button.quarto-btn-toggle{margin-left:-0.75rem;margin-right:.15rem}.quarto-secondary-nav nav.quarto-title-breadcrumbs{display:none}.quarto-secondary-nav nav.quarto-page-breadcrumbs{display:flex;align-items:center;padding-right:1em;margin-left:-0.25em}.quarto-secondary-nav nav.quarto-page-breadcrumbs a{text-decoration:none}.quarto-secondary-nav nav.quarto-page-breadcrumbs ol.breadcrumb{margin-bottom:0}}@media(min-width: 992px){.quarto-secondary-nav{display:none}}.quarto-title-breadcrumbs .breadcrumb{margin-bottom:.5em;font-size:.9rem}.quarto-title-breadcrumbs .breadcrumb li:last-of-type a{color:#6c757d}.quarto-secondary-nav .quarto-btn-toggle{color:#595959}.quarto-secondary-nav[aria-expanded=false] .quarto-btn-toggle .bi-chevron-right::before{transform:none}.quarto-secondary-nav[aria-expanded=true] .quarto-btn-toggle .bi-chevron-right::before{transform:rotate(90deg)}.quarto-secondary-nav .quarto-btn-toggle .bi-chevron-right::before{transition:transform 200ms ease}.quarto-secondary-nav{cursor:pointer}.no-decor{text-decoration:none}.quarto-secondary-nav-title{margin-top:.3em;color:#595959;padding-top:4px}.quarto-secondary-nav nav.quarto-page-breadcrumbs{color:#595959}.quarto-secondary-nav nav.quarto-page-breadcrumbs a{color:#595959}.quarto-secondary-nav nav.quarto-page-breadcrumbs a:hover{color:rgba(33,81,191,.8)}.quarto-secondary-nav nav.quarto-page-breadcrumbs .breadcrumb-item::before{color:#8c8c8c}.breadcrumb-item{line-height:1.2rem}div.sidebar-item-container{color:#595959}div.sidebar-item-container:hover,div.sidebar-item-container:focus{color:rgba(33,81,191,.8)}div.sidebar-item-container.disabled{color:rgba(89,89,89,.75)}div.sidebar-item-container .active,div.sidebar-item-container .show>.nav-link,div.sidebar-item-container .sidebar-link>code{color:#2151bf}div.sidebar.sidebar-navigation.rollup.quarto-sidebar-toggle-contents,nav.sidebar.sidebar-navigation:not(.rollup){background-color:#fff}@media(max-width: 991.98px){.sidebar-navigation .sidebar-item a,.nav-page .nav-page-text,.sidebar-navigation{font-size:1rem}.sidebar-navigation ul.sidebar-section.depth1 .sidebar-section-item{font-size:1.1rem}.sidebar-logo{display:none}.sidebar.sidebar-navigation{position:static;border-bottom:1px solid #dee2e6}.sidebar.sidebar-navigation.collapsing{position:fixed;z-index:1000}.sidebar.sidebar-navigation.show{position:fixed;z-index:1000}.sidebar.sidebar-navigation{min-height:100%}nav.quarto-secondary-nav{background-color:#fff;border-bottom:1px solid #dee2e6}.quarto-banner nav.quarto-secondary-nav{background-color:#f8f9fa;color:#545555;border-top:1px solid #dee2e6}.sidebar .sidebar-footer{visibility:visible;padding-top:1rem;position:inherit}.sidebar-tools-collapse{display:block}}#quarto-sidebar{transition:width .15s ease-in}#quarto-sidebar>*{padding-right:1em}@media(max-width: 991.98px){#quarto-sidebar .sidebar-menu-container{white-space:nowrap;min-width:225px}#quarto-sidebar.show{transition:width .15s ease-out}}@media(min-width: 992px){#quarto-sidebar{display:flex;flex-direction:column}.nav-page .nav-page-text,.sidebar-navigation .sidebar-section .sidebar-item{font-size:.875rem}.sidebar-navigation .sidebar-item{font-size:.925rem}.sidebar.sidebar-navigation{display:block;position:sticky}.sidebar-search{width:100%}.sidebar .sidebar-footer{visibility:visible}}@media(max-width: 991.98px){#quarto-sidebar-glass{position:fixed;top:0;bottom:0;left:0;right:0;background-color:rgba(255,255,255,0);transition:background-color .15s ease-in;z-index:-1}#quarto-sidebar-glass.collapsing{z-index:1000}#quarto-sidebar-glass.show{transition:background-color .15s ease-out;background-color:rgba(102,102,102,.4);z-index:1000}}.sidebar .sidebar-footer{padding:.5rem 1rem;align-self:flex-end;color:#6c757d;width:100%}.quarto-page-breadcrumbs .breadcrumb-item+.breadcrumb-item,.quarto-page-breadcrumbs .breadcrumb-item{padding-right:.33em;padding-left:0}.quarto-page-breadcrumbs .breadcrumb-item::before{padding-right:.33em}.quarto-sidebar-footer{font-size:.875em}.sidebar-section .bi-chevron-right{vertical-align:middle}.sidebar-section .bi-chevron-right::before{font-size:.9em}.notransition{-webkit-transition:none !important;-moz-transition:none !important;-o-transition:none !important;transition:none !important}.btn:focus:not(:focus-visible){box-shadow:none}.page-navigation{display:flex;justify-content:space-between}.nav-page{padding-bottom:.75em}.nav-page .bi{font-size:1.8rem;vertical-align:middle}.nav-page .nav-page-text{padding-left:.25em;padding-right:.25em}.nav-page a{color:#6c757d;text-decoration:none;display:flex;align-items:center}.nav-page a:hover{color:#1f4eb6}.nav-footer .toc-actions{padding-bottom:.5em;padding-top:.5em}.nav-footer .toc-actions a,.nav-footer .toc-actions a:hover{text-decoration:none}.nav-footer .toc-actions ul{display:flex;list-style:none}.nav-footer .toc-actions ul :first-child{margin-left:auto}.nav-footer .toc-actions ul :last-child{margin-right:auto}.nav-footer .toc-actions ul li{padding-right:1.5em}.nav-footer .toc-actions ul li i.bi{padding-right:.4em}.nav-footer .toc-actions ul li:last-of-type{padding-right:0}.nav-footer{display:flex;flex-direction:row;flex-wrap:wrap;justify-content:space-between;align-items:baseline;text-align:center;padding-top:.5rem;padding-bottom:.5rem;background-color:#fff}body.nav-fixed{padding-top:64px}.nav-footer-contents{color:#6c757d;margin-top:.25rem}.nav-footer{min-height:3.5em;color:#757575}.nav-footer a{color:#757575}.nav-footer .nav-footer-left{font-size:.825em}.nav-footer .nav-footer-center{font-size:.825em}.nav-footer .nav-footer-right{font-size:.825em}.nav-footer-left .footer-items,.nav-footer-center .footer-items,.nav-footer-right .footer-items{display:inline-flex;padding-top:.3em;padding-bottom:.3em;margin-bottom:0em}.nav-footer-left .footer-items .nav-link,.nav-footer-center .footer-items .nav-link,.nav-footer-right .footer-items .nav-link{padding-left:.6em;padding-right:.6em}.nav-footer-left{flex:1 1 0px;text-align:left}.nav-footer-right{flex:1 1 0px;text-align:right}.nav-footer-center{flex:1 1 0px;min-height:3em;text-align:center}.nav-footer-center .footer-items{justify-content:center}@media(max-width: 767.98px){.nav-footer-center{margin-top:3em}}.navbar .quarto-reader-toggle.reader .quarto-reader-toggle-btn{background-color:#545555;border-radius:3px}@media(max-width: 991.98px){.quarto-reader-toggle{display:none}}.quarto-reader-toggle.reader.quarto-navigation-tool .quarto-reader-toggle-btn{background-color:#595959;border-radius:3px}.quarto-reader-toggle .quarto-reader-toggle-btn{display:inline-flex;padding-left:.2em;padding-right:.2em;margin-left:-0.2em;margin-right:-0.2em;text-align:center}.navbar .quarto-reader-toggle:not(.reader) .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(84, 85, 85, 1)" class="bi bi-body-text" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M0 .5A.5.5 0 0 1 .5 0h4a.5.5 0 0 1 0 1h-4A.5.5 0 0 1 0 .5Zm0 2A.5.5 0 0 1 .5 2h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm9 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-9 2A.5.5 0 0 1 .5 4h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm5 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm-12 2A.5.5 0 0 1 .5 6h6a.5.5 0 0 1 0 1h-6a.5.5 0 0 1-.5-.5Zm8 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-8 2A.5.5 0 0 1 .5 8h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm-7 2a.5.5 0 0 1 .5-.5h8a.5.5 0 0 1 0 1h-8a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h4a.5.5 0 0 1 0 1h-4a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h2a.5.5 0 0 1 0 1h-2a.5.5 0 0 1-.5-.5Z"/></svg>')}.navbar .quarto-reader-toggle.reader .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(248, 249, 250, 1)" class="bi bi-body-text" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M0 .5A.5.5 0 0 1 .5 0h4a.5.5 0 0 1 0 1h-4A.5.5 0 0 1 0 .5Zm0 2A.5.5 0 0 1 .5 2h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm9 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-9 2A.5.5 0 0 1 .5 4h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm5 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm-12 2A.5.5 0 0 1 .5 6h6a.5.5 0 0 1 0 1h-6a.5.5 0 0 1-.5-.5Zm8 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-8 2A.5.5 0 0 1 .5 8h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm-7 2a.5.5 0 0 1 .5-.5h8a.5.5 0 0 1 0 1h-8a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h4a.5.5 0 0 1 0 1h-4a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h2a.5.5 0 0 1 0 1h-2a.5.5 0 0 1-.5-.5Z"/></svg>')}.sidebar-navigation .quarto-reader-toggle:not(.reader) .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(89, 89, 89, 1)" class="bi bi-body-text" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M0 .5A.5.5 0 0 1 .5 0h4a.5.5 0 0 1 0 1h-4A.5.5 0 0 1 0 .5Zm0 2A.5.5 0 0 1 .5 2h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm9 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-9 2A.5.5 0 0 1 .5 4h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm5 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm-12 2A.5.5 0 0 1 .5 6h6a.5.5 0 0 1 0 1h-6a.5.5 0 0 1-.5-.5Zm8 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-8 2A.5.5 0 0 1 .5 8h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm-7 2a.5.5 0 0 1 .5-.5h8a.5.5 0 0 1 0 1h-8a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h4a.5.5 0 0 1 0 1h-4a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h2a.5.5 0 0 1 0 1h-2a.5.5 0 0 1-.5-.5Z"/></svg>')}.sidebar-navigation .quarto-reader-toggle.reader .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(255, 255, 255, 1)" class="bi bi-body-text" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M0 .5A.5.5 0 0 1 .5 0h4a.5.5 0 0 1 0 1h-4A.5.5 0 0 1 0 .5Zm0 2A.5.5 0 0 1 .5 2h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm9 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-9 2A.5.5 0 0 1 .5 4h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm5 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5Zm-12 2A.5.5 0 0 1 .5 6h6a.5.5 0 0 1 0 1h-6a.5.5 0 0 1-.5-.5Zm8 0a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm-8 2A.5.5 0 0 1 .5 8h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5Zm7 0a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5Zm-7 2a.5.5 0 0 1 .5-.5h8a.5.5 0 0 1 0 1h-8a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h4a.5.5 0 0 1 0 1h-4a.5.5 0 0 1-.5-.5Zm0 2a.5.5 0 0 1 .5-.5h2a.5.5 0 0 1 0 1h-2a.5.5 0 0 1-.5-.5Z"/></svg>')}#quarto-back-to-top{display:none;position:fixed;bottom:50px;background-color:#fff;border-radius:.25rem;box-shadow:0 .2rem .5rem #6c757d,0 0 .05rem #6c757d;color:#6c757d;text-decoration:none;font-size:.9em;text-align:center;left:50%;padding:.4rem .8rem;transform:translate(-50%, 0)}.aa-DetachedSearchButtonQuery{display:none}.aa-DetachedOverlay ul.aa-List,#quarto-search-results ul.aa-List{list-style:none;padding-left:0}.aa-DetachedOverlay .aa-Panel,#quarto-search-results .aa-Panel{background-color:#fff;position:absolute;z-index:2000}#quarto-search-results .aa-Panel{max-width:400px}#quarto-search input{font-size:.925rem}@media(min-width: 992px){.navbar #quarto-search{margin-left:.25rem;order:999}}.navbar.navbar-expand-sm #quarto-search,.navbar.navbar-expand-md #quarto-search{order:999}@media(min-width: 992px){.navbar .quarto-navbar-tools{order:900}}@media(min-width: 992px){.navbar .quarto-navbar-tools.tools-end{margin-left:auto !important}}@media(max-width: 991.98px){#quarto-sidebar .sidebar-search{display:none}}#quarto-sidebar .sidebar-search .aa-Autocomplete{width:100%}.navbar .aa-Autocomplete .aa-Form{width:180px}.navbar #quarto-search.type-overlay .aa-Autocomplete{width:40px}.navbar #quarto-search.type-overlay .aa-Autocomplete .aa-Form{background-color:inherit;border:none}.navbar #quarto-search.type-overlay .aa-Autocomplete .aa-Form:focus-within{box-shadow:none;outline:none}.navbar #quarto-search.type-overlay .aa-Autocomplete .aa-Form .aa-InputWrapper{display:none}.navbar #quarto-search.type-overlay .aa-Autocomplete .aa-Form .aa-InputWrapper:focus-within{display:inherit}.navbar #quarto-search.type-overlay .aa-Autocomplete .aa-Form .aa-Label svg,.navbar #quarto-search.type-overlay .aa-Autocomplete .aa-Form .aa-LoadingIndicator svg{width:26px;height:26px;color:#545555;opacity:1}.navbar #quarto-search.type-overlay .aa-Autocomplete svg.aa-SubmitIcon{width:26px;height:26px;color:#545555;opacity:1}.aa-Autocomplete .aa-Form,.aa-DetachedFormContainer .aa-Form{align-items:center;background-color:#fff;border:1px solid #dee2e6;border-radius:.25rem;color:#343a40;display:flex;line-height:1em;margin:0;position:relative;width:100%}.aa-Autocomplete .aa-Form:focus-within,.aa-DetachedFormContainer .aa-Form:focus-within{box-shadow:rgba(39,128,227,.6) 0 0 0 1px;outline:currentColor none medium}.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix{align-items:center;display:flex;flex-shrink:0;order:1}.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix .aa-Label,.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix .aa-Label,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator{cursor:initial;flex-shrink:0;padding:0;text-align:left}.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix .aa-Label svg,.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator svg,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix .aa-Label svg,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator svg{color:#343a40;opacity:.5}.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix .aa-SubmitButton,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix .aa-SubmitButton{appearance:none;background:none;border:0;margin:0}.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator{align-items:center;display:flex;justify-content:center}.aa-Autocomplete .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator[hidden],.aa-DetachedFormContainer .aa-Form .aa-InputWrapperPrefix .aa-LoadingIndicator[hidden]{display:none}.aa-Autocomplete .aa-Form .aa-InputWrapper,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper{order:3;position:relative;width:100%}.aa-Autocomplete .aa-Form .aa-InputWrapper .aa-Input,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input{appearance:none;background:none;border:0;color:#343a40;font:inherit;height:calc(1.5em + .1rem + 2px);padding:0;width:100%}.aa-Autocomplete .aa-Form .aa-InputWrapper .aa-Input::placeholder,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input::placeholder{color:#343a40;opacity:.8}.aa-Autocomplete .aa-Form .aa-InputWrapper .aa-Input:focus,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input:focus{border-color:none;box-shadow:none;outline:none}.aa-Autocomplete .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-decoration,.aa-Autocomplete .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-cancel-button,.aa-Autocomplete .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-results-button,.aa-Autocomplete .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-results-decoration,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-decoration,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-cancel-button,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-results-button,.aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input::-webkit-search-results-decoration{display:none}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix{align-items:center;display:flex;order:4}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-ClearButton,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-ClearButton{align-items:center;background:none;border:0;color:#343a40;opacity:.8;cursor:pointer;display:flex;margin:0;width:calc(1.5em + .1rem + 2px)}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-ClearButton:hover,.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-ClearButton:focus,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-ClearButton:hover,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-ClearButton:focus{color:#343a40;opacity:.8}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-ClearButton[hidden],.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-ClearButton[hidden]{display:none}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-ClearButton svg,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-ClearButton svg{width:calc(1.5em + 0.75rem + calc(1px * 2))}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-CopyButton,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-CopyButton{border:none;align-items:center;background:none;color:#343a40;opacity:.4;font-size:.7rem;cursor:pointer;display:none;margin:0;width:calc(1em + .1rem + 2px)}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-CopyButton:hover,.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-CopyButton:focus,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-CopyButton:hover,.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-CopyButton:focus{color:#343a40;opacity:.8}.aa-Autocomplete .aa-Form .aa-InputWrapperSuffix .aa-CopyButton[hidden],.aa-DetachedFormContainer .aa-Form .aa-InputWrapperSuffix .aa-CopyButton[hidden]{display:none}.aa-PanelLayout:empty{display:none}.quarto-search-no-results.no-query{display:none}.aa-Source:has(.no-query){display:none}#quarto-search-results .aa-Panel{border:solid #dee2e6 1px}#quarto-search-results .aa-SourceNoResults{width:398px}.aa-DetachedOverlay .aa-Panel,#quarto-search-results .aa-Panel{max-height:65vh;overflow-y:auto;font-size:.925rem}.aa-DetachedOverlay .aa-SourceNoResults,#quarto-search-results .aa-SourceNoResults{height:60px;display:flex;justify-content:center;align-items:center}.aa-DetachedOverlay .search-error,#quarto-search-results .search-error{padding-top:10px;padding-left:20px;padding-right:20px;cursor:default}.aa-DetachedOverlay .search-error .search-error-title,#quarto-search-results .search-error .search-error-title{font-size:1.1rem;margin-bottom:.5rem}.aa-DetachedOverlay .search-error .search-error-title .search-error-icon,#quarto-search-results .search-error .search-error-title .search-error-icon{margin-right:8px}.aa-DetachedOverlay .search-error .search-error-text,#quarto-search-results .search-error .search-error-text{font-weight:300}.aa-DetachedOverlay .search-result-text,#quarto-search-results .search-result-text{font-weight:300;overflow:hidden;text-overflow:ellipsis;display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;line-height:1.2rem;max-height:2.4rem}.aa-DetachedOverlay .aa-SourceHeader .search-result-header,#quarto-search-results .aa-SourceHeader .search-result-header{font-size:.875rem;background-color:#f2f2f2;padding-left:14px;padding-bottom:4px;padding-top:4px}.aa-DetachedOverlay .aa-SourceHeader .search-result-header-no-results,#quarto-search-results .aa-SourceHeader .search-result-header-no-results{display:none}.aa-DetachedOverlay .aa-SourceFooter .algolia-search-logo,#quarto-search-results .aa-SourceFooter .algolia-search-logo{width:110px;opacity:.85;margin:8px;float:right}.aa-DetachedOverlay .search-result-section,#quarto-search-results .search-result-section{font-size:.925em}.aa-DetachedOverlay a.search-result-link,#quarto-search-results a.search-result-link{color:inherit;text-decoration:none}.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item,#quarto-search-results li.aa-Item[aria-selected=true] .search-item{background-color:#2780e3}.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item.search-result-more,.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item .search-result-section,.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item .search-result-text,.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item .search-result-title-container,.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item .search-result-text-container,#quarto-search-results li.aa-Item[aria-selected=true] .search-item.search-result-more,#quarto-search-results li.aa-Item[aria-selected=true] .search-item .search-result-section,#quarto-search-results li.aa-Item[aria-selected=true] .search-item .search-result-text,#quarto-search-results li.aa-Item[aria-selected=true] .search-item .search-result-title-container,#quarto-search-results li.aa-Item[aria-selected=true] .search-item .search-result-text-container{color:#fff;background-color:#2780e3}.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item mark.search-match,.aa-DetachedOverlay li.aa-Item[aria-selected=true] .search-item .search-match.mark,#quarto-search-results li.aa-Item[aria-selected=true] .search-item mark.search-match,#quarto-search-results li.aa-Item[aria-selected=true] .search-item .search-match.mark{color:#fff;background-color:#4b95e8}.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item,#quarto-search-results li.aa-Item[aria-selected=false] .search-item{background-color:#fff}.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item.search-result-more,.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item .search-result-section,.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item .search-result-text,.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item .search-result-title-container,.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item .search-result-text-container,#quarto-search-results li.aa-Item[aria-selected=false] .search-item.search-result-more,#quarto-search-results li.aa-Item[aria-selected=false] .search-item .search-result-section,#quarto-search-results li.aa-Item[aria-selected=false] .search-item .search-result-text,#quarto-search-results li.aa-Item[aria-selected=false] .search-item .search-result-title-container,#quarto-search-results li.aa-Item[aria-selected=false] .search-item .search-result-text-container{color:#343a40}.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item mark.search-match,.aa-DetachedOverlay li.aa-Item[aria-selected=false] .search-item .search-match.mark,#quarto-search-results li.aa-Item[aria-selected=false] .search-item mark.search-match,#quarto-search-results li.aa-Item[aria-selected=false] .search-item .search-match.mark{color:inherit;background-color:#e5effc}.aa-DetachedOverlay .aa-Item .search-result-doc:not(.document-selectable) .search-result-title-container,#quarto-search-results .aa-Item .search-result-doc:not(.document-selectable) .search-result-title-container{background-color:#fff;color:#343a40}.aa-DetachedOverlay .aa-Item .search-result-doc:not(.document-selectable) .search-result-text-container,#quarto-search-results .aa-Item .search-result-doc:not(.document-selectable) .search-result-text-container{padding-top:0px}.aa-DetachedOverlay li.aa-Item .search-result-doc.document-selectable .search-result-text-container,#quarto-search-results li.aa-Item .search-result-doc.document-selectable .search-result-text-container{margin-top:-4px}.aa-DetachedOverlay .aa-Item,#quarto-search-results .aa-Item{cursor:pointer}.aa-DetachedOverlay .aa-Item .search-item,#quarto-search-results .aa-Item .search-item{border-left:none;border-right:none;border-top:none;background-color:#fff;border-color:#dee2e6;color:#343a40}.aa-DetachedOverlay .aa-Item .search-item p,#quarto-search-results .aa-Item .search-item p{margin-top:0;margin-bottom:0}.aa-DetachedOverlay .aa-Item .search-item i.bi,#quarto-search-results .aa-Item .search-item i.bi{padding-left:8px;padding-right:8px;font-size:1.3em}.aa-DetachedOverlay .aa-Item .search-item .search-result-title,#quarto-search-results .aa-Item .search-item .search-result-title{margin-top:.3em;margin-bottom:0em}.aa-DetachedOverlay .aa-Item .search-item .search-result-crumbs,#quarto-search-results .aa-Item .search-item .search-result-crumbs{white-space:nowrap;text-overflow:ellipsis;font-size:.8em;font-weight:300;margin-right:1em}.aa-DetachedOverlay .aa-Item .search-item .search-result-crumbs:not(.search-result-crumbs-wrap),#quarto-search-results .aa-Item .search-item .search-result-crumbs:not(.search-result-crumbs-wrap){max-width:30%;margin-left:auto;margin-top:.5em;margin-bottom:.1rem}.aa-DetachedOverlay .aa-Item .search-item .search-result-crumbs.search-result-crumbs-wrap,#quarto-search-results .aa-Item .search-item .search-result-crumbs.search-result-crumbs-wrap{flex-basis:100%;margin-top:0em;margin-bottom:.2em;margin-left:37px}.aa-DetachedOverlay .aa-Item .search-result-title-container,#quarto-search-results .aa-Item .search-result-title-container{font-size:1em;display:flex;flex-wrap:wrap;padding:6px 4px 6px 4px}.aa-DetachedOverlay .aa-Item .search-result-text-container,#quarto-search-results .aa-Item .search-result-text-container{padding-bottom:8px;padding-right:8px;margin-left:42px}.aa-DetachedOverlay .aa-Item .search-result-doc-section,.aa-DetachedOverlay .aa-Item .search-result-more,#quarto-search-results .aa-Item .search-result-doc-section,#quarto-search-results .aa-Item .search-result-more{padding-top:8px;padding-bottom:8px;padding-left:44px}.aa-DetachedOverlay .aa-Item .search-result-more,#quarto-search-results .aa-Item .search-result-more{font-size:.8em;font-weight:400}.aa-DetachedOverlay .aa-Item .search-result-doc,#quarto-search-results .aa-Item .search-result-doc{border-top:1px solid #dee2e6}.aa-DetachedSearchButton{background:none;border:none}.aa-DetachedSearchButton .aa-DetachedSearchButtonPlaceholder{display:none}.navbar .aa-DetachedSearchButton .aa-DetachedSearchButtonIcon{color:#545555}.sidebar-tools-collapse #quarto-search,.sidebar-tools-main #quarto-search{display:inline}.sidebar-tools-collapse #quarto-search .aa-Autocomplete,.sidebar-tools-main #quarto-search .aa-Autocomplete{display:inline}.sidebar-tools-collapse #quarto-search .aa-DetachedSearchButton,.sidebar-tools-main #quarto-search .aa-DetachedSearchButton{padding-left:4px;padding-right:4px}.sidebar-tools-collapse #quarto-search .aa-DetachedSearchButton .aa-DetachedSearchButtonIcon,.sidebar-tools-main #quarto-search .aa-DetachedSearchButton .aa-DetachedSearchButtonIcon{color:#595959}.sidebar-tools-collapse #quarto-search .aa-DetachedSearchButton .aa-DetachedSearchButtonIcon .aa-SubmitIcon,.sidebar-tools-main #quarto-search .aa-DetachedSearchButton .aa-DetachedSearchButtonIcon .aa-SubmitIcon{margin-top:-3px}.aa-DetachedContainer{background:rgba(255,255,255,.65);width:90%;bottom:0;box-shadow:rgba(222,226,230,.6) 0 0 0 1px;outline:currentColor none medium;display:flex;flex-direction:column;left:0;margin:0;overflow:hidden;padding:0;position:fixed;right:0;top:0;z-index:1101}.aa-DetachedContainer::after{height:32px}.aa-DetachedContainer .aa-SourceHeader{margin:var(--aa-spacing-half) 0 var(--aa-spacing-half) 2px}.aa-DetachedContainer .aa-Panel{background-color:#fff;border-radius:0;box-shadow:none;flex-grow:1;margin:0;padding:0;position:relative}.aa-DetachedContainer .aa-PanelLayout{bottom:0;box-shadow:none;left:0;margin:0;max-height:none;overflow-y:auto;position:absolute;right:0;top:0;width:100%}.aa-DetachedFormContainer{background-color:#fff;border-bottom:1px solid #dee2e6;display:flex;flex-direction:row;justify-content:space-between;margin:0;padding:.5em}.aa-DetachedCancelButton{background:none;font-size:.8em;border:0;border-radius:3px;color:#343a40;cursor:pointer;margin:0 0 0 .5em;padding:0 .5em}.aa-DetachedCancelButton:hover,.aa-DetachedCancelButton:focus{box-shadow:rgba(39,128,227,.6) 0 0 0 1px;outline:currentColor none medium}.aa-DetachedContainer--modal{bottom:inherit;height:auto;margin:0 auto;position:absolute;top:100px;border-radius:6px;max-width:850px}@media(max-width: 575.98px){.aa-DetachedContainer--modal{width:100%;top:0px;border-radius:0px;border:none}}.aa-DetachedContainer--modal .aa-PanelLayout{max-height:var(--aa-detached-modal-max-height);padding-bottom:var(--aa-spacing-half);position:static}.aa-Detached{height:100vh;overflow:hidden}.aa-DetachedOverlay{background-color:rgba(52,58,64,.4);position:fixed;left:0;right:0;top:0;margin:0;padding:0;height:100vh;z-index:1100}.quarto-dashboard.nav-fixed.dashboard-sidebar #quarto-content.quarto-dashboard-content{padding:0em}.quarto-dashboard #quarto-content.quarto-dashboard-content{padding:1em}.quarto-dashboard #quarto-content.quarto-dashboard-content>*{padding-top:0}@media(min-width: 576px){.quarto-dashboard{height:100%}}.quarto-dashboard .card.valuebox.bslib-card.bg-primary{background-color:#5397e9 !important}.quarto-dashboard .card.valuebox.bslib-card.bg-secondary{background-color:#343a40 !important}.quarto-dashboard .card.valuebox.bslib-card.bg-success{background-color:#3aa716 !important}.quarto-dashboard .card.valuebox.bslib-card.bg-info{background-color:rgba(153,84,187,.7019607843) !important}.quarto-dashboard .card.valuebox.bslib-card.bg-warning{background-color:#fa6400 !important}.quarto-dashboard .card.valuebox.bslib-card.bg-danger{background-color:rgba(255,0,57,.7019607843) !important}.quarto-dashboard .card.valuebox.bslib-card.bg-light{background-color:#f8f9fa !important}.quarto-dashboard .card.valuebox.bslib-card.bg-dark{background-color:#343a40 !important}.quarto-dashboard.dashboard-fill{display:flex;flex-direction:column}.quarto-dashboard #quarto-appendix{display:none}.quarto-dashboard #quarto-header #quarto-dashboard-header{border-top:solid 1px #dae0e5;border-bottom:solid 1px #dae0e5}.quarto-dashboard #quarto-header #quarto-dashboard-header>nav{padding-left:1em;padding-right:1em}.quarto-dashboard #quarto-header #quarto-dashboard-header>nav .navbar-brand-container{padding-left:0}.quarto-dashboard #quarto-header #quarto-dashboard-header .navbar-toggler{margin-right:0}.quarto-dashboard #quarto-header #quarto-dashboard-header .navbar-toggler-icon{height:1em;width:1em;background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(84, 85, 85)" class="bi bi-menu-button-wide" viewBox="0 0 16 16"><path d="M0 1.5A1.5 1.5 0 0 1 1.5 0h13A1.5 1.5 0 0 1 16 1.5v2A1.5 1.5 0 0 1 14.5 5h-13A1.5 1.5 0 0 1 0 3.5v-2zM1.5 1a.5.5 0 0 0-.5.5v2a.5.5 0 0 0 .5.5h13a.5.5 0 0 0 .5-.5v-2a.5.5 0 0 0-.5-.5h-13z"/><path d="M2 2.5a.5.5 0 0 1 .5-.5h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5zm10.823.323-.396-.396A.25.25 0 0 1 12.604 2h.792a.25.25 0 0 1 .177.427l-.396.396a.25.25 0 0 1-.354 0zM0 8a2 2 0 0 1 2-2h12a2 2 0 0 1 2 2v5a2 2 0 0 1-2 2H2a2 2 0 0 1-2-2V8zm1 3v2a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-2H1zm14-1V8a1 1 0 0 0-1-1H2a1 1 0 0 0-1 1v2h14zM2 8.5a.5.5 0 0 1 .5-.5h9a.5.5 0 0 1 0 1h-9a.5.5 0 0 1-.5-.5zm0 4a.5.5 0 0 1 .5-.5h6a.5.5 0 0 1 0 1h-6a.5.5 0 0 1-.5-.5z"/></svg>')}.quarto-dashboard #quarto-header #quarto-dashboard-header .navbar-brand-container{padding-right:1em}.quarto-dashboard #quarto-header #quarto-dashboard-header .navbar-title{font-size:1.1em}.quarto-dashboard #quarto-header #quarto-dashboard-header .navbar-nav{font-size:.9em}.quarto-dashboard #quarto-dashboard-header .navbar{padding:0}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-container{padding-left:1em}.quarto-dashboard #quarto-dashboard-header .navbar.slim .navbar-brand-container .nav-link,.quarto-dashboard #quarto-dashboard-header .navbar.slim .navbar-nav .nav-link{padding:.7em}.quarto-dashboard #quarto-dashboard-header .navbar .quarto-color-scheme-toggle{order:9}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-toggler{margin-left:.5em;order:10}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-nav .nav-link{padding:.5em;height:100%;display:flex;align-items:center}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-nav .active{background-color:#e0e5e9}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-brand-container{padding:.5em .5em .5em 0;display:flex;flex-direction:row;margin-right:2em;align-items:center}@media(max-width: 767.98px){.quarto-dashboard #quarto-dashboard-header .navbar .navbar-brand-container{margin-right:auto}}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-collapse{align-self:stretch}@media(min-width: 768px){.quarto-dashboard #quarto-dashboard-header .navbar .navbar-collapse{order:8}}@media(max-width: 767.98px){.quarto-dashboard #quarto-dashboard-header .navbar .navbar-collapse{order:1000;padding-bottom:.5em}}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-collapse .navbar-nav{align-self:stretch}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-title{font-size:1.25em;line-height:1.1em;display:flex;flex-direction:row;flex-wrap:wrap;align-items:baseline}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-title .navbar-title-text{margin-right:.4em}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-title a{text-decoration:none;color:inherit}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-subtitle,.quarto-dashboard #quarto-dashboard-header .navbar .navbar-author{font-size:.9rem;margin-right:.5em}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-author{margin-left:auto}.quarto-dashboard #quarto-dashboard-header .navbar .navbar-logo{max-height:48px;min-height:30px;object-fit:cover;margin-right:1em}.quarto-dashboard #quarto-dashboard-header .navbar .quarto-dashboard-links{order:9;padding-right:1em}.quarto-dashboard #quarto-dashboard-header .navbar .quarto-dashboard-link-text{margin-left:.25em}.quarto-dashboard #quarto-dashboard-header .navbar .quarto-dashboard-link{padding-right:0em;padding-left:.7em;text-decoration:none;color:#545555}.quarto-dashboard .page-layout-custom .tab-content{padding:0;border:none}.quarto-dashboard-img-contain{height:100%;width:100%;object-fit:contain}@media(max-width: 575.98px){.quarto-dashboard .bslib-grid{grid-template-rows:minmax(1em, max-content) !important}.quarto-dashboard .sidebar-content{height:inherit}.quarto-dashboard .page-layout-custom{min-height:100vh}}.quarto-dashboard.dashboard-toolbar>.page-layout-custom,.quarto-dashboard.dashboard-sidebar>.page-layout-custom{padding:0}.quarto-dashboard .quarto-dashboard-content.quarto-dashboard-pages{padding:0}.quarto-dashboard .callout{margin-bottom:0;margin-top:0}.quarto-dashboard .html-fill-container figure{overflow:hidden}.quarto-dashboard bslib-tooltip .rounded-pill{border:solid #6c757d 1px}.quarto-dashboard bslib-tooltip .rounded-pill .svg{fill:#343a40}.quarto-dashboard .tabset .dashboard-card-no-title .nav-tabs{margin-left:0;margin-right:auto}.quarto-dashboard .tabset .tab-content{border:none}.quarto-dashboard .tabset .card-header .nav-link[role=tab]{margin-top:-6px;padding-top:6px;padding-bottom:6px}.quarto-dashboard .card.valuebox,.quarto-dashboard .card.bslib-value-box{min-height:3rem}.quarto-dashboard .card.valuebox .card-body,.quarto-dashboard .card.bslib-value-box .card-body{padding:0}.quarto-dashboard .bslib-value-box .value-box-value{font-size:clamp(.1em,15cqw,5em)}.quarto-dashboard .bslib-value-box .value-box-showcase .bi{font-size:clamp(.1em,max(18cqw,5.2cqh),5em);text-align:center;height:1em}.quarto-dashboard .bslib-value-box .value-box-showcase .bi::before{vertical-align:1em}.quarto-dashboard .bslib-value-box .value-box-area{margin-top:auto;margin-bottom:auto}.quarto-dashboard .card figure.quarto-float{display:flex;flex-direction:column;align-items:center}.quarto-dashboard .dashboard-scrolling{padding:1em}.quarto-dashboard .full-height{height:100%}.quarto-dashboard .showcase-bottom .value-box-grid{display:grid;grid-template-columns:1fr;grid-template-rows:1fr auto;grid-template-areas:"top" "bottom"}.quarto-dashboard .showcase-bottom .value-box-grid .value-box-showcase{grid-area:bottom;padding:0;margin:0}.quarto-dashboard .showcase-bottom .value-box-grid .value-box-showcase i.bi{font-size:4rem}.quarto-dashboard .showcase-bottom .value-box-grid .value-box-area{grid-area:top}.quarto-dashboard .tab-content{margin-bottom:0}.quarto-dashboard .bslib-card .bslib-navs-card-title{justify-content:stretch;align-items:end}.quarto-dashboard .card-header{display:flex;flex-wrap:wrap;justify-content:space-between}.quarto-dashboard .card-header .card-title{display:flex;flex-direction:column;justify-content:center;margin-bottom:0}.quarto-dashboard .tabset .card-toolbar{margin-bottom:1em}.quarto-dashboard .bslib-grid>.bslib-sidebar-layout{border:none;gap:var(--bslib-spacer, 1rem)}.quarto-dashboard .bslib-grid>.bslib-sidebar-layout>.main{padding:0}.quarto-dashboard .bslib-grid>.bslib-sidebar-layout>.sidebar{border-radius:.25rem;border:1px solid rgba(0,0,0,.175)}.quarto-dashboard .bslib-grid>.bslib-sidebar-layout>.collapse-toggle{display:none}@media(max-width: 767.98px){.quarto-dashboard .bslib-grid>.bslib-sidebar-layout{grid-template-columns:1fr;grid-template-rows:max-content 1fr}.quarto-dashboard .bslib-grid>.bslib-sidebar-layout>.main{grid-column:1;grid-row:2}.quarto-dashboard .bslib-grid>.bslib-sidebar-layout .sidebar{grid-column:1;grid-row:1}}.quarto-dashboard .sidebar-right .sidebar{padding-left:2.5em}.quarto-dashboard .sidebar-right .collapse-toggle{left:2px}.quarto-dashboard .quarto-dashboard .sidebar-right button.collapse-toggle:not(.transitioning){left:unset}.quarto-dashboard aside.sidebar{padding-left:1em;padding-right:1em;background-color:rgba(52,58,64,.25);color:#343a40}.quarto-dashboard .bslib-sidebar-layout>div.main{padding:.7em}.quarto-dashboard .bslib-sidebar-layout button.collapse-toggle{margin-top:.3em}.quarto-dashboard .bslib-sidebar-layout .collapse-toggle{top:0}.quarto-dashboard .bslib-sidebar-layout.sidebar-collapsed:not(.transitioning):not(.sidebar-right) .collapse-toggle{left:2px}.quarto-dashboard .sidebar>section>.h3:first-of-type{margin-top:0em}.quarto-dashboard .sidebar .h3,.quarto-dashboard .sidebar .h4,.quarto-dashboard .sidebar .h5,.quarto-dashboard .sidebar .h6{margin-top:.5em}.quarto-dashboard .sidebar form{flex-direction:column;align-items:start;margin-bottom:1em}.quarto-dashboard .sidebar form div[class*=oi-][class$=-input]{flex-direction:column}.quarto-dashboard .sidebar form[class*=oi-][class$=-toggle]{flex-direction:row-reverse;align-items:center;justify-content:start}.quarto-dashboard .sidebar form input[type=range]{margin-top:.5em;margin-right:.8em;margin-left:1em}.quarto-dashboard .sidebar label{width:fit-content}.quarto-dashboard .sidebar .card-body{margin-bottom:2em}.quarto-dashboard .sidebar .shiny-input-container{margin-bottom:1em}.quarto-dashboard .sidebar .shiny-options-group{margin-top:0}.quarto-dashboard .sidebar .control-label{margin-bottom:.3em}.quarto-dashboard .card .card-body .quarto-layout-row{align-items:stretch}.quarto-dashboard .toolbar{font-size:.9em;display:flex;flex-direction:row;border-top:solid 1px #bcbfc0;padding:1em;flex-wrap:wrap;background-color:rgba(52,58,64,.25)}.quarto-dashboard .toolbar .cell-output-display{display:flex}.quarto-dashboard .toolbar .shiny-input-container{padding-bottom:.5em;margin-bottom:.5em;width:inherit}.quarto-dashboard .toolbar .shiny-input-container>.checkbox:first-child{margin-top:6px}.quarto-dashboard .toolbar>*:last-child{margin-right:0}.quarto-dashboard .toolbar>*>*{margin-right:1em;align-items:baseline}.quarto-dashboard .toolbar>*>*>a{text-decoration:none;margin-top:auto;margin-bottom:auto}.quarto-dashboard .toolbar .shiny-input-container{padding-bottom:0;margin-bottom:0}.quarto-dashboard .toolbar .shiny-input-container>*{flex-shrink:0;flex-grow:0}.quarto-dashboard .toolbar .form-group.shiny-input-container:not([role=group])>label{margin-bottom:0}.quarto-dashboard .toolbar .shiny-input-container.no-baseline{align-items:start;padding-top:6px}.quarto-dashboard .toolbar .shiny-input-container{display:flex;align-items:baseline}.quarto-dashboard .toolbar .shiny-input-container label{padding-right:.4em}.quarto-dashboard .toolbar .shiny-input-container .bslib-input-switch{margin-top:6px}.quarto-dashboard .toolbar input[type=text]{line-height:1;width:inherit}.quarto-dashboard .toolbar .input-daterange{width:inherit}.quarto-dashboard .toolbar .input-daterange input[type=text]{height:2.4em;width:10em}.quarto-dashboard .toolbar .input-daterange .input-group-addon{height:auto;padding:0;margin-left:-5px !important;margin-right:-5px}.quarto-dashboard .toolbar .input-daterange .input-group-addon .input-group-text{padding-top:0;padding-bottom:0;height:100%}.quarto-dashboard .toolbar span.irs.irs--shiny{width:10em}.quarto-dashboard .toolbar span.irs.irs--shiny .irs-line{top:9px}.quarto-dashboard .toolbar span.irs.irs--shiny .irs-min,.quarto-dashboard .toolbar span.irs.irs--shiny .irs-max,.quarto-dashboard .toolbar span.irs.irs--shiny .irs-from,.quarto-dashboard .toolbar span.irs.irs--shiny .irs-to,.quarto-dashboard .toolbar span.irs.irs--shiny .irs-single{top:20px}.quarto-dashboard .toolbar span.irs.irs--shiny .irs-bar{top:8px}.quarto-dashboard .toolbar span.irs.irs--shiny .irs-handle{top:0px}.quarto-dashboard .toolbar .shiny-input-checkboxgroup>label{margin-top:6px}.quarto-dashboard .toolbar .shiny-input-checkboxgroup>.shiny-options-group{margin-top:0;align-items:baseline}.quarto-dashboard .toolbar .shiny-input-radiogroup>label{margin-top:6px}.quarto-dashboard .toolbar .shiny-input-radiogroup>.shiny-options-group{align-items:baseline;margin-top:0}.quarto-dashboard .toolbar .shiny-input-radiogroup>.shiny-options-group>.radio{margin-right:.3em}.quarto-dashboard .toolbar .form-select{padding-top:.2em;padding-bottom:.2em}.quarto-dashboard .toolbar .shiny-input-select{min-width:6em}.quarto-dashboard .toolbar div.checkbox{margin-bottom:0px}.quarto-dashboard .toolbar>.checkbox:first-child{margin-top:6px}.quarto-dashboard .toolbar form{width:fit-content}.quarto-dashboard .toolbar form label{padding-top:.2em;padding-bottom:.2em;width:fit-content}.quarto-dashboard .toolbar form input[type=date]{width:fit-content}.quarto-dashboard .toolbar form input[type=color]{width:3em}.quarto-dashboard .toolbar form button{padding:.4em}.quarto-dashboard .toolbar form select{width:fit-content}.quarto-dashboard .toolbar>*{font-size:.9em;flex-grow:0}.quarto-dashboard .toolbar .shiny-input-container label{margin-bottom:1px}.quarto-dashboard .toolbar-bottom{margin-top:1em;margin-bottom:0 !important;order:2}.quarto-dashboard .quarto-dashboard-content>.dashboard-toolbar-container>.toolbar-content>.tab-content>.tab-pane>*:not(.bslib-sidebar-layout){padding:1em}.quarto-dashboard .quarto-dashboard-content>.dashboard-toolbar-container>.toolbar-content>*:not(.tab-content){padding:1em}.quarto-dashboard .quarto-dashboard-content>.tab-content>.dashboard-page>.dashboard-toolbar-container>.toolbar-content,.quarto-dashboard .quarto-dashboard-content>.tab-content>.dashboard-page:not(.dashboard-sidebar-container)>*:not(.dashboard-toolbar-container){padding:1em}.quarto-dashboard .toolbar-content{padding:0}.quarto-dashboard .quarto-dashboard-content.quarto-dashboard-pages .tab-pane>.dashboard-toolbar-container .toolbar{border-radius:0;margin-bottom:0}.quarto-dashboard .dashboard-toolbar-container.toolbar-toplevel .toolbar{border-bottom:1px solid rgba(0,0,0,.175)}.quarto-dashboard .dashboard-toolbar-container.toolbar-toplevel .toolbar-bottom{margin-top:0}.quarto-dashboard .dashboard-toolbar-container:not(.toolbar-toplevel) .toolbar{margin-bottom:1em;border-top:none;border-radius:.25rem;border:1px solid rgba(0,0,0,.175)}.quarto-dashboard .vega-embed.has-actions details{width:1.7em;height:2em;position:absolute !important;top:0;right:0}.quarto-dashboard .dashboard-toolbar-container{padding:0}.quarto-dashboard .card .card-header p:last-child,.quarto-dashboard .card .card-footer p:last-child{margin-bottom:0}.quarto-dashboard .card .card-body>.h4:first-child{margin-top:0}.quarto-dashboard .card .card-body{z-index:4}@media(max-width: 767.98px){.quarto-dashboard .card .card-body .itables div.dataTables_wrapper div.dataTables_length,.quarto-dashboard .card .card-body .itables div.dataTables_wrapper div.dataTables_info,.quarto-dashboard .card .card-body .itables div.dataTables_wrapper div.dataTables_paginate{text-align:initial}.quarto-dashboard .card .card-body .itables div.dataTables_wrapper div.dataTables_filter{text-align:right}.quarto-dashboard .card .card-body .itables div.dataTables_wrapper div.dataTables_paginate ul.pagination{justify-content:initial}}.quarto-dashboard .card .card-body .itables .dataTables_wrapper{display:flex;flex-wrap:wrap;justify-content:space-between;align-items:center;padding-top:0}.quarto-dashboard .card .card-body .itables .dataTables_wrapper table{flex-shrink:0}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dt-buttons{margin-bottom:.5em;margin-left:auto;width:fit-content;float:right}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dt-buttons.btn-group{background:#fff;border:none}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dt-buttons .btn-secondary{background-color:#fff;background-image:none;border:solid #dee2e6 1px;padding:.2em .7em}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dt-buttons .btn span{font-size:.8em;color:#343a40}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_info{margin-left:.5em;margin-bottom:.5em;padding-top:0}@media(min-width: 768px){.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_info{font-size:.875em}}@media(max-width: 767.98px){.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_info{font-size:.8em}}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_filter{margin-bottom:.5em;font-size:.875em}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_filter input[type=search]{padding:1px 5px 1px 5px;font-size:.875em}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_length{flex-basis:1 1 50%;margin-bottom:.5em;font-size:.875em}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_length select{padding:.4em 3em .4em .5em;font-size:.875em;margin-left:.2em;margin-right:.2em}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_paginate{flex-shrink:0}@media(min-width: 768px){.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_paginate{margin-left:auto}}.quarto-dashboard .card .card-body .itables .dataTables_wrapper .dataTables_paginate ul.pagination .paginate_button .page-link{font-size:.8em}.quarto-dashboard .card .card-footer{font-size:.9em}.quarto-dashboard .card .card-toolbar{display:flex;flex-grow:1;flex-direction:row;width:100%;flex-wrap:wrap}.quarto-dashboard .card .card-toolbar>*{font-size:.8em;flex-grow:0}.quarto-dashboard .card .card-toolbar>.card-title{font-size:1em;flex-grow:1;align-self:flex-start;margin-top:.1em}.quarto-dashboard .card .card-toolbar .cell-output-display{display:flex}.quarto-dashboard .card .card-toolbar .shiny-input-container{padding-bottom:.5em;margin-bottom:.5em;width:inherit}.quarto-dashboard .card .card-toolbar .shiny-input-container>.checkbox:first-child{margin-top:6px}.quarto-dashboard .card .card-toolbar>*:last-child{margin-right:0}.quarto-dashboard .card .card-toolbar>*>*{margin-right:1em;align-items:baseline}.quarto-dashboard .card .card-toolbar>*>*>a{text-decoration:none;margin-top:auto;margin-bottom:auto}.quarto-dashboard .card .card-toolbar form{width:fit-content}.quarto-dashboard .card .card-toolbar form label{padding-top:.2em;padding-bottom:.2em;width:fit-content}.quarto-dashboard .card .card-toolbar form input[type=date]{width:fit-content}.quarto-dashboard .card .card-toolbar form input[type=color]{width:3em}.quarto-dashboard .card .card-toolbar form button{padding:.4em}.quarto-dashboard .card .card-toolbar form select{width:fit-content}.quarto-dashboard .card .card-toolbar .cell-output-display{display:flex}.quarto-dashboard .card .card-toolbar .shiny-input-container{padding-bottom:.5em;margin-bottom:.5em;width:inherit}.quarto-dashboard .card .card-toolbar .shiny-input-container>.checkbox:first-child{margin-top:6px}.quarto-dashboard .card .card-toolbar>*:last-child{margin-right:0}.quarto-dashboard .card .card-toolbar>*>*{margin-right:1em;align-items:baseline}.quarto-dashboard .card .card-toolbar>*>*>a{text-decoration:none;margin-top:auto;margin-bottom:auto}.quarto-dashboard .card .card-toolbar .shiny-input-container{padding-bottom:0;margin-bottom:0}.quarto-dashboard .card .card-toolbar .shiny-input-container>*{flex-shrink:0;flex-grow:0}.quarto-dashboard .card .card-toolbar .form-group.shiny-input-container:not([role=group])>label{margin-bottom:0}.quarto-dashboard .card .card-toolbar .shiny-input-container.no-baseline{align-items:start;padding-top:6px}.quarto-dashboard .card .card-toolbar .shiny-input-container{display:flex;align-items:baseline}.quarto-dashboard .card .card-toolbar .shiny-input-container label{padding-right:.4em}.quarto-dashboard .card .card-toolbar .shiny-input-container .bslib-input-switch{margin-top:6px}.quarto-dashboard .card .card-toolbar input[type=text]{line-height:1;width:inherit}.quarto-dashboard .card .card-toolbar .input-daterange{width:inherit}.quarto-dashboard .card .card-toolbar .input-daterange input[type=text]{height:2.4em;width:10em}.quarto-dashboard .card .card-toolbar .input-daterange .input-group-addon{height:auto;padding:0;margin-left:-5px !important;margin-right:-5px}.quarto-dashboard .card .card-toolbar .input-daterange .input-group-addon .input-group-text{padding-top:0;padding-bottom:0;height:100%}.quarto-dashboard .card .card-toolbar span.irs.irs--shiny{width:10em}.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-line{top:9px}.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-min,.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-max,.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-from,.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-to,.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-single{top:20px}.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-bar{top:8px}.quarto-dashboard .card .card-toolbar span.irs.irs--shiny .irs-handle{top:0px}.quarto-dashboard .card .card-toolbar .shiny-input-checkboxgroup>label{margin-top:6px}.quarto-dashboard .card .card-toolbar .shiny-input-checkboxgroup>.shiny-options-group{margin-top:0;align-items:baseline}.quarto-dashboard .card .card-toolbar .shiny-input-radiogroup>label{margin-top:6px}.quarto-dashboard .card .card-toolbar .shiny-input-radiogroup>.shiny-options-group{align-items:baseline;margin-top:0}.quarto-dashboard .card .card-toolbar .shiny-input-radiogroup>.shiny-options-group>.radio{margin-right:.3em}.quarto-dashboard .card .card-toolbar .form-select{padding-top:.2em;padding-bottom:.2em}.quarto-dashboard .card .card-toolbar .shiny-input-select{min-width:6em}.quarto-dashboard .card .card-toolbar div.checkbox{margin-bottom:0px}.quarto-dashboard .card .card-toolbar>.checkbox:first-child{margin-top:6px}.quarto-dashboard .card-body>table>thead{border-top:none}.quarto-dashboard .card-body>.table>:not(caption)>*>*{background-color:#fff}.tableFloatingHeaderOriginal{background-color:#fff;position:sticky !important;top:0 !important}.dashboard-data-table{margin-top:-1px}.quarto-listing{padding-bottom:1em}.listing-pagination{padding-top:.5em}ul.pagination{float:right;padding-left:8px;padding-top:.5em}ul.pagination li{padding-right:.75em}ul.pagination li.disabled a,ul.pagination li.active a{color:#fff;text-decoration:none}ul.pagination li:last-of-type{padding-right:0}.listing-actions-group{display:flex}.quarto-listing-filter{margin-bottom:1em;width:200px;margin-left:auto}.quarto-listing-sort{margin-bottom:1em;margin-right:auto;width:auto}.quarto-listing-sort .input-group-text{font-size:.8em}.input-group-text{border-right:none}.quarto-listing-sort select.form-select{font-size:.8em}.listing-no-matching{text-align:center;padding-top:2em;padding-bottom:3em;font-size:1em}#quarto-margin-sidebar .quarto-listing-category{padding-top:0;font-size:1rem}#quarto-margin-sidebar .quarto-listing-category-title{cursor:pointer;font-weight:600;font-size:1rem}.quarto-listing-category .category{cursor:pointer}.quarto-listing-category .category.active{font-weight:600}.quarto-listing-category.category-cloud{display:flex;flex-wrap:wrap;align-items:baseline}.quarto-listing-category.category-cloud .category{padding-right:5px}.quarto-listing-category.category-cloud .category-cloud-1{font-size:.75em}.quarto-listing-category.category-cloud .category-cloud-2{font-size:.95em}.quarto-listing-category.category-cloud .category-cloud-3{font-size:1.15em}.quarto-listing-category.category-cloud .category-cloud-4{font-size:1.35em}.quarto-listing-category.category-cloud .category-cloud-5{font-size:1.55em}.quarto-listing-category.category-cloud .category-cloud-6{font-size:1.75em}.quarto-listing-category.category-cloud .category-cloud-7{font-size:1.95em}.quarto-listing-category.category-cloud .category-cloud-8{font-size:2.15em}.quarto-listing-category.category-cloud .category-cloud-9{font-size:2.35em}.quarto-listing-category.category-cloud .category-cloud-10{font-size:2.55em}.quarto-listing-cols-1{grid-template-columns:repeat(1, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-1{grid-template-columns:repeat(1, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-1{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-2{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-2{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-2{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-3{grid-template-columns:repeat(3, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-3{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-3{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-4{grid-template-columns:repeat(4, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-4{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-4{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-5{grid-template-columns:repeat(5, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-5{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-5{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-6{grid-template-columns:repeat(6, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-6{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-6{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-7{grid-template-columns:repeat(7, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-7{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-7{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-8{grid-template-columns:repeat(8, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-8{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-8{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-9{grid-template-columns:repeat(9, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-9{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-9{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-10{grid-template-columns:repeat(10, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-10{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-10{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-11{grid-template-columns:repeat(11, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-11{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-11{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-cols-12{grid-template-columns:repeat(12, minmax(0, 1fr));gap:1.5em}@media(max-width: 767.98px){.quarto-listing-cols-12{grid-template-columns:repeat(2, minmax(0, 1fr));gap:1.5em}}@media(max-width: 575.98px){.quarto-listing-cols-12{grid-template-columns:minmax(0, 1fr);gap:1.5em}}.quarto-listing-grid{gap:1.5em}.quarto-grid-item.borderless{border:none}.quarto-grid-item.borderless .listing-categories .listing-category:last-of-type,.quarto-grid-item.borderless .listing-categories .listing-category:first-of-type{padding-left:0}.quarto-grid-item.borderless .listing-categories .listing-category{border:0}.quarto-grid-link{text-decoration:none;color:inherit}.quarto-grid-link:hover{text-decoration:none;color:inherit}.quarto-grid-item h5.title,.quarto-grid-item .title.h5{margin-top:0;margin-bottom:0}.quarto-grid-item .card-footer{display:flex;justify-content:space-between;font-size:.8em}.quarto-grid-item .card-footer p{margin-bottom:0}.quarto-grid-item p.card-img-top{margin-bottom:0}.quarto-grid-item p.card-img-top>img{object-fit:cover}.quarto-grid-item .card-other-values{margin-top:.5em;font-size:.8em}.quarto-grid-item .card-other-values tr{margin-bottom:.5em}.quarto-grid-item .card-other-values tr>td:first-of-type{font-weight:600;padding-right:1em;padding-left:1em;vertical-align:top}.quarto-grid-item div.post-contents{display:flex;flex-direction:column;text-decoration:none;height:100%}.quarto-grid-item .listing-item-img-placeholder{background-color:rgba(52,58,64,.25);flex-shrink:0}.quarto-grid-item .card-attribution{padding-top:1em;display:flex;gap:1em;text-transform:uppercase;color:#6c757d;font-weight:500;flex-grow:10;align-items:flex-end}.quarto-grid-item .description{padding-bottom:1em}.quarto-grid-item .card-attribution .date{align-self:flex-end}.quarto-grid-item .card-attribution.justify{justify-content:space-between}.quarto-grid-item .card-attribution.start{justify-content:flex-start}.quarto-grid-item .card-attribution.end{justify-content:flex-end}.quarto-grid-item .card-title{margin-bottom:.1em}.quarto-grid-item .card-subtitle{padding-top:.25em}.quarto-grid-item .card-text{font-size:.9em}.quarto-grid-item .listing-reading-time{padding-bottom:.25em}.quarto-grid-item .card-text-small{font-size:.8em}.quarto-grid-item .card-subtitle.subtitle{font-size:.9em;font-weight:600;padding-bottom:.5em}.quarto-grid-item .listing-categories{display:flex;flex-wrap:wrap;padding-bottom:5px}.quarto-grid-item .listing-categories .listing-category{color:#6c757d;border:solid 1px #dee2e6;border-radius:.25rem;text-transform:uppercase;font-size:.65em;padding-left:.5em;padding-right:.5em;padding-top:.15em;padding-bottom:.15em;cursor:pointer;margin-right:4px;margin-bottom:4px}.quarto-grid-item.card-right{text-align:right}.quarto-grid-item.card-right .listing-categories{justify-content:flex-end}.quarto-grid-item.card-left{text-align:left}.quarto-grid-item.card-center{text-align:center}.quarto-grid-item.card-center .listing-description{text-align:justify}.quarto-grid-item.card-center .listing-categories{justify-content:center}table.quarto-listing-table td.image{padding:0px}table.quarto-listing-table td.image img{width:100%;max-width:50px;object-fit:contain}table.quarto-listing-table a{text-decoration:none;word-break:keep-all}table.quarto-listing-table th a{color:inherit}table.quarto-listing-table th a.asc:after{margin-bottom:-2px;margin-left:5px;display:inline-block;height:1rem;width:1rem;background-repeat:no-repeat;background-size:1rem 1rem;background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-sort-up" viewBox="0 0 16 16"><path d="M3.5 12.5a.5.5 0 0 1-1 0V3.707L1.354 4.854a.5.5 0 1 1-.708-.708l2-1.999.007-.007a.498.498 0 0 1 .7.006l2 2a.5.5 0 1 1-.707.708L3.5 3.707V12.5zm3.5-9a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5zM7.5 6a.5.5 0 0 0 0 1h5a.5.5 0 0 0 0-1h-5zm0 3a.5.5 0 0 0 0 1h3a.5.5 0 0 0 0-1h-3zm0 3a.5.5 0 0 0 0 1h1a.5.5 0 0 0 0-1h-1z"/></svg>');content:""}table.quarto-listing-table th a.desc:after{margin-bottom:-2px;margin-left:5px;display:inline-block;height:1rem;width:1rem;background-repeat:no-repeat;background-size:1rem 1rem;background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-sort-down" viewBox="0 0 16 16"><path d="M3.5 2.5a.5.5 0 0 0-1 0v8.793l-1.146-1.147a.5.5 0 0 0-.708.708l2 1.999.007.007a.497.497 0 0 0 .7-.006l2-2a.5.5 0 0 0-.707-.708L3.5 11.293V2.5zm3.5 1a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5zM7.5 6a.5.5 0 0 0 0 1h5a.5.5 0 0 0 0-1h-5zm0 3a.5.5 0 0 0 0 1h3a.5.5 0 0 0 0-1h-3zm0 3a.5.5 0 0 0 0 1h1a.5.5 0 0 0 0-1h-1z"/></svg>');content:""}table.quarto-listing-table.table-hover td{cursor:pointer}.quarto-post.image-left{flex-direction:row}.quarto-post.image-right{flex-direction:row-reverse}@media(max-width: 767.98px){.quarto-post.image-right,.quarto-post.image-left{gap:0em;flex-direction:column}.quarto-post .metadata{padding-bottom:1em;order:2}.quarto-post .body{order:1}.quarto-post .thumbnail{order:3}}.list.quarto-listing-default div:last-of-type{border-bottom:none}@media(min-width: 992px){.quarto-listing-container-default{margin-right:2em}}div.quarto-post{display:flex;gap:2em;margin-bottom:1.5em;border-bottom:1px solid #dee2e6}@media(max-width: 767.98px){div.quarto-post{padding-bottom:1em}}div.quarto-post .metadata{flex-basis:20%;flex-grow:0;margin-top:.2em;flex-shrink:10}div.quarto-post .thumbnail{flex-basis:30%;flex-grow:0;flex-shrink:0}div.quarto-post .thumbnail img{margin-top:.4em;width:100%;object-fit:cover}div.quarto-post .body{flex-basis:45%;flex-grow:1;flex-shrink:0}div.quarto-post .body h3.listing-title,div.quarto-post .body .listing-title.h3{margin-top:0px;margin-bottom:0px;border-bottom:none}div.quarto-post .body .listing-subtitle{font-size:.875em;margin-bottom:.5em;margin-top:.2em}div.quarto-post .body .description{font-size:.9em}div.quarto-post .body pre code{white-space:pre-wrap}div.quarto-post a{color:#343a40;text-decoration:none}div.quarto-post .metadata{display:flex;flex-direction:column;font-size:.8em;font-family:"Source Sans Pro",-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol";flex-basis:33%}div.quarto-post .listing-categories{display:flex;flex-wrap:wrap;padding-bottom:5px}div.quarto-post .listing-categories .listing-category{color:#6c757d;border:solid 1px #dee2e6;border-radius:.25rem;text-transform:uppercase;font-size:.65em;padding-left:.5em;padding-right:.5em;padding-top:.15em;padding-bottom:.15em;cursor:pointer;margin-right:4px;margin-bottom:4px}div.quarto-post .listing-description{margin-bottom:.5em}div.quarto-about-jolla{display:flex !important;flex-direction:column;align-items:center;margin-top:10%;padding-bottom:1em}div.quarto-about-jolla .about-image{object-fit:cover;margin-left:auto;margin-right:auto;margin-bottom:1.5em}div.quarto-about-jolla img.round{border-radius:50%}div.quarto-about-jolla img.rounded{border-radius:10px}div.quarto-about-jolla .quarto-title h1.title,div.quarto-about-jolla .quarto-title .title.h1{text-align:center}div.quarto-about-jolla .quarto-title .description{text-align:center}div.quarto-about-jolla h2,div.quarto-about-jolla .h2{border-bottom:none}div.quarto-about-jolla .about-sep{width:60%}div.quarto-about-jolla main{text-align:center}div.quarto-about-jolla .about-links{display:flex}@media(min-width: 992px){div.quarto-about-jolla .about-links{flex-direction:row;column-gap:.8em;row-gap:15px;flex-wrap:wrap}}@media(max-width: 991.98px){div.quarto-about-jolla .about-links{flex-direction:column;row-gap:1em;width:100%;padding-bottom:1.5em}}div.quarto-about-jolla .about-link{color:#626d78;text-decoration:none;border:solid 1px}@media(min-width: 992px){div.quarto-about-jolla .about-link{font-size:.8em;padding:.25em .5em;border-radius:4px}}@media(max-width: 991.98px){div.quarto-about-jolla .about-link{font-size:1.1em;padding:.5em .5em;text-align:center;border-radius:6px}}div.quarto-about-jolla .about-link:hover{color:#2761e3}div.quarto-about-jolla .about-link i.bi{margin-right:.15em}div.quarto-about-solana{display:flex !important;flex-direction:column;padding-top:3em !important;padding-bottom:1em}div.quarto-about-solana .about-entity{display:flex !important;align-items:start;justify-content:space-between}@media(min-width: 992px){div.quarto-about-solana .about-entity{flex-direction:row}}@media(max-width: 991.98px){div.quarto-about-solana .about-entity{flex-direction:column-reverse;align-items:center;text-align:center}}div.quarto-about-solana .about-entity .entity-contents{display:flex;flex-direction:column}@media(max-width: 767.98px){div.quarto-about-solana .about-entity .entity-contents{width:100%}}div.quarto-about-solana .about-entity .about-image{object-fit:cover}@media(max-width: 991.98px){div.quarto-about-solana .about-entity .about-image{margin-bottom:1.5em}}div.quarto-about-solana .about-entity img.round{border-radius:50%}div.quarto-about-solana .about-entity img.rounded{border-radius:10px}div.quarto-about-solana .about-entity .about-links{display:flex;justify-content:left;padding-bottom:1.2em}@media(min-width: 992px){div.quarto-about-solana .about-entity .about-links{flex-direction:row;column-gap:.8em;row-gap:15px;flex-wrap:wrap}}@media(max-width: 991.98px){div.quarto-about-solana .about-entity .about-links{flex-direction:column;row-gap:1em;width:100%;padding-bottom:1.5em}}div.quarto-about-solana .about-entity .about-link{color:#626d78;text-decoration:none;border:solid 1px}@media(min-width: 992px){div.quarto-about-solana .about-entity .about-link{font-size:.8em;padding:.25em .5em;border-radius:4px}}@media(max-width: 991.98px){div.quarto-about-solana .about-entity .about-link{font-size:1.1em;padding:.5em .5em;text-align:center;border-radius:6px}}div.quarto-about-solana .about-entity .about-link:hover{color:#2761e3}div.quarto-about-solana .about-entity .about-link i.bi{margin-right:.15em}div.quarto-about-solana .about-contents{padding-right:1.5em;flex-basis:0;flex-grow:1}div.quarto-about-solana .about-contents main.content{margin-top:0}div.quarto-about-solana .about-contents h2,div.quarto-about-solana .about-contents .h2{border-bottom:none}div.quarto-about-trestles{display:flex !important;flex-direction:row;padding-top:3em !important;padding-bottom:1em}@media(max-width: 991.98px){div.quarto-about-trestles{flex-direction:column;padding-top:0em !important}}div.quarto-about-trestles .about-entity{display:flex !important;flex-direction:column;align-items:center;text-align:center;padding-right:1em}@media(min-width: 992px){div.quarto-about-trestles .about-entity{flex:0 0 42%}}div.quarto-about-trestles .about-entity .about-image{object-fit:cover;margin-bottom:1.5em}div.quarto-about-trestles .about-entity img.round{border-radius:50%}div.quarto-about-trestles .about-entity img.rounded{border-radius:10px}div.quarto-about-trestles .about-entity .about-links{display:flex;justify-content:center}@media(min-width: 992px){div.quarto-about-trestles .about-entity .about-links{flex-direction:row;column-gap:.8em;row-gap:15px;flex-wrap:wrap}}@media(max-width: 991.98px){div.quarto-about-trestles .about-entity .about-links{flex-direction:column;row-gap:1em;width:100%;padding-bottom:1.5em}}div.quarto-about-trestles .about-entity .about-link{color:#626d78;text-decoration:none;border:solid 1px}@media(min-width: 992px){div.quarto-about-trestles .about-entity .about-link{font-size:.8em;padding:.25em .5em;border-radius:4px}}@media(max-width: 991.98px){div.quarto-about-trestles .about-entity .about-link{font-size:1.1em;padding:.5em .5em;text-align:center;border-radius:6px}}div.quarto-about-trestles .about-entity .about-link:hover{color:#2761e3}div.quarto-about-trestles .about-entity .about-link i.bi{margin-right:.15em}div.quarto-about-trestles .about-contents{flex-basis:0;flex-grow:1}div.quarto-about-trestles .about-contents h2,div.quarto-about-trestles .about-contents .h2{border-bottom:none}@media(min-width: 992px){div.quarto-about-trestles .about-contents{border-left:solid 1px #dee2e6;padding-left:1.5em}}div.quarto-about-trestles .about-contents main.content{margin-top:0}div.quarto-about-marquee{padding-bottom:1em}div.quarto-about-marquee .about-contents{display:flex;flex-direction:column}div.quarto-about-marquee .about-image{max-height:550px;margin-bottom:1.5em;object-fit:cover}div.quarto-about-marquee img.round{border-radius:50%}div.quarto-about-marquee img.rounded{border-radius:10px}div.quarto-about-marquee h2,div.quarto-about-marquee .h2{border-bottom:none}div.quarto-about-marquee .about-links{display:flex;justify-content:center;padding-top:1.5em}@media(min-width: 992px){div.quarto-about-marquee .about-links{flex-direction:row;column-gap:.8em;row-gap:15px;flex-wrap:wrap}}@media(max-width: 991.98px){div.quarto-about-marquee .about-links{flex-direction:column;row-gap:1em;width:100%;padding-bottom:1.5em}}div.quarto-about-marquee .about-link{color:#626d78;text-decoration:none;border:solid 1px}@media(min-width: 992px){div.quarto-about-marquee .about-link{font-size:.8em;padding:.25em .5em;border-radius:4px}}@media(max-width: 991.98px){div.quarto-about-marquee .about-link{font-size:1.1em;padding:.5em .5em;text-align:center;border-radius:6px}}div.quarto-about-marquee .about-link:hover{color:#2761e3}div.quarto-about-marquee .about-link i.bi{margin-right:.15em}@media(min-width: 992px){div.quarto-about-marquee .about-link{border:none}}div.quarto-about-broadside{display:flex;flex-direction:column;padding-bottom:1em}div.quarto-about-broadside .about-main{display:flex !important;padding-top:0 !important}@media(min-width: 992px){div.quarto-about-broadside .about-main{flex-direction:row;align-items:flex-start}}@media(max-width: 991.98px){div.quarto-about-broadside .about-main{flex-direction:column}}@media(max-width: 991.98px){div.quarto-about-broadside .about-main .about-entity{flex-shrink:0;width:100%;height:450px;margin-bottom:1.5em;background-size:cover;background-repeat:no-repeat}}@media(min-width: 992px){div.quarto-about-broadside .about-main .about-entity{flex:0 10 50%;margin-right:1.5em;width:100%;height:100%;background-size:100%;background-repeat:no-repeat}}div.quarto-about-broadside .about-main .about-contents{padding-top:14px;flex:0 0 50%}div.quarto-about-broadside h2,div.quarto-about-broadside .h2{border-bottom:none}div.quarto-about-broadside .about-sep{margin-top:1.5em;width:60%;align-self:center}div.quarto-about-broadside .about-links{display:flex;justify-content:center;column-gap:20px;padding-top:1.5em}@media(min-width: 992px){div.quarto-about-broadside .about-links{flex-direction:row;column-gap:.8em;row-gap:15px;flex-wrap:wrap}}@media(max-width: 991.98px){div.quarto-about-broadside .about-links{flex-direction:column;row-gap:1em;width:100%;padding-bottom:1.5em}}div.quarto-about-broadside .about-link{color:#626d78;text-decoration:none;border:solid 1px}@media(min-width: 992px){div.quarto-about-broadside .about-link{font-size:.8em;padding:.25em .5em;border-radius:4px}}@media(max-width: 991.98px){div.quarto-about-broadside .about-link{font-size:1.1em;padding:.5em .5em;text-align:center;border-radius:6px}}div.quarto-about-broadside .about-link:hover{color:#2761e3}div.quarto-about-broadside .about-link i.bi{margin-right:.15em}@media(min-width: 992px){div.quarto-about-broadside .about-link{border:none}}.tippy-box[data-theme~=quarto]{background-color:#fff;border:solid 1px #dee2e6;border-radius:.25rem;color:#343a40;font-size:.875rem}.tippy-box[data-theme~=quarto]>.tippy-backdrop{background-color:#fff}.tippy-box[data-theme~=quarto]>.tippy-arrow:after,.tippy-box[data-theme~=quarto]>.tippy-svg-arrow:after{content:"";position:absolute;z-index:-1}.tippy-box[data-theme~=quarto]>.tippy-arrow:after{border-color:rgba(0,0,0,0);border-style:solid}.tippy-box[data-placement^=top]>.tippy-arrow:before{bottom:-6px}.tippy-box[data-placement^=bottom]>.tippy-arrow:before{top:-6px}.tippy-box[data-placement^=right]>.tippy-arrow:before{left:-6px}.tippy-box[data-placement^=left]>.tippy-arrow:before{right:-6px}.tippy-box[data-theme~=quarto][data-placement^=top]>.tippy-arrow:before{border-top-color:#fff}.tippy-box[data-theme~=quarto][data-placement^=top]>.tippy-arrow:after{border-top-color:#dee2e6;border-width:7px 7px 0;top:17px;left:1px}.tippy-box[data-theme~=quarto][data-placement^=top]>.tippy-svg-arrow>svg{top:16px}.tippy-box[data-theme~=quarto][data-placement^=top]>.tippy-svg-arrow:after{top:17px}.tippy-box[data-theme~=quarto][data-placement^=bottom]>.tippy-arrow:before{border-bottom-color:#fff;bottom:16px}.tippy-box[data-theme~=quarto][data-placement^=bottom]>.tippy-arrow:after{border-bottom-color:#dee2e6;border-width:0 7px 7px;bottom:17px;left:1px}.tippy-box[data-theme~=quarto][data-placement^=bottom]>.tippy-svg-arrow>svg{bottom:15px}.tippy-box[data-theme~=quarto][data-placement^=bottom]>.tippy-svg-arrow:after{bottom:17px}.tippy-box[data-theme~=quarto][data-placement^=left]>.tippy-arrow:before{border-left-color:#fff}.tippy-box[data-theme~=quarto][data-placement^=left]>.tippy-arrow:after{border-left-color:#dee2e6;border-width:7px 0 7px 7px;left:17px;top:1px}.tippy-box[data-theme~=quarto][data-placement^=left]>.tippy-svg-arrow>svg{left:11px}.tippy-box[data-theme~=quarto][data-placement^=left]>.tippy-svg-arrow:after{left:12px}.tippy-box[data-theme~=quarto][data-placement^=right]>.tippy-arrow:before{border-right-color:#fff;right:16px}.tippy-box[data-theme~=quarto][data-placement^=right]>.tippy-arrow:after{border-width:7px 7px 7px 0;right:17px;top:1px;border-right-color:#dee2e6}.tippy-box[data-theme~=quarto][data-placement^=right]>.tippy-svg-arrow>svg{right:11px}.tippy-box[data-theme~=quarto][data-placement^=right]>.tippy-svg-arrow:after{right:12px}.tippy-box[data-theme~=quarto]>.tippy-svg-arrow{fill:#343a40}.tippy-box[data-theme~=quarto]>.tippy-svg-arrow:after{background-image:url(data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iNiIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBkPSJNMCA2czEuNzk2LS4wMTMgNC42Ny0zLjYxNUM1Ljg1MS45IDYuOTMuMDA2IDggMGMxLjA3LS4wMDYgMi4xNDguODg3IDMuMzQzIDIuMzg1QzE0LjIzMyA2LjAwNSAxNiA2IDE2IDZIMHoiIGZpbGw9InJnYmEoMCwgOCwgMTYsIDAuMikiLz48L3N2Zz4=);background-size:16px 6px;width:16px;height:6px}.top-right{position:absolute;top:1em;right:1em}.visually-hidden{border:0;clip:rect(0 0 0 0);height:auto;margin:0;overflow:hidden;padding:0;position:absolute;width:1px;white-space:nowrap}.hidden{display:none !important}.zindex-bottom{z-index:-1 !important}figure.figure{display:block}.quarto-layout-panel{margin-bottom:1em}.quarto-layout-panel>figure{width:100%}.quarto-layout-panel>figure>figcaption,.quarto-layout-panel>.panel-caption{margin-top:10pt}.quarto-layout-panel>.table-caption{margin-top:0px}.table-caption p{margin-bottom:.5em}.quarto-layout-row{display:flex;flex-direction:row;align-items:flex-start}.quarto-layout-valign-top{align-items:flex-start}.quarto-layout-valign-bottom{align-items:flex-end}.quarto-layout-valign-center{align-items:center}.quarto-layout-cell{position:relative;margin-right:20px}.quarto-layout-cell:last-child{margin-right:0}.quarto-layout-cell figure,.quarto-layout-cell>p{margin:.2em}.quarto-layout-cell img{max-width:100%}.quarto-layout-cell .html-widget{width:100% !important}.quarto-layout-cell div figure p{margin:0}.quarto-layout-cell figure{display:block;margin-inline-start:0;margin-inline-end:0}.quarto-layout-cell table{display:inline-table}.quarto-layout-cell-subref figcaption,figure .quarto-layout-row figure figcaption{text-align:center;font-style:italic}.quarto-figure{position:relative;margin-bottom:1em}.quarto-figure>figure{width:100%;margin-bottom:0}.quarto-figure-left>figure>p,.quarto-figure-left>figure>div{text-align:left}.quarto-figure-center>figure>p,.quarto-figure-center>figure>div{text-align:center}.quarto-figure-right>figure>p,.quarto-figure-right>figure>div{text-align:right}.quarto-figure>figure>div.cell-annotation,.quarto-figure>figure>div code{text-align:left}figure>p:empty{display:none}figure>p:first-child{margin-top:0;margin-bottom:0}figure>figcaption.quarto-float-caption-bottom{margin-bottom:.5em}figure>figcaption.quarto-float-caption-top{margin-top:.5em}div[id^=tbl-]{position:relative}.quarto-figure>.anchorjs-link{position:absolute;top:.6em;right:.5em}div[id^=tbl-]>.anchorjs-link{position:absolute;top:.7em;right:.3em}.quarto-figure:hover>.anchorjs-link,div[id^=tbl-]:hover>.anchorjs-link,h2:hover>.anchorjs-link,.h2:hover>.anchorjs-link,h3:hover>.anchorjs-link,.h3:hover>.anchorjs-link,h4:hover>.anchorjs-link,.h4:hover>.anchorjs-link,h5:hover>.anchorjs-link,.h5:hover>.anchorjs-link,h6:hover>.anchorjs-link,.h6:hover>.anchorjs-link,.reveal-anchorjs-link>.anchorjs-link{opacity:1}#title-block-header{margin-block-end:1rem;position:relative;margin-top:-1px}#title-block-header .abstract{margin-block-start:1rem}#title-block-header .abstract .abstract-title{font-weight:600}#title-block-header a{text-decoration:none}#title-block-header .author,#title-block-header .date,#title-block-header .doi{margin-block-end:.2rem}#title-block-header .quarto-title-block>div{display:flex}#title-block-header .quarto-title-block>div>h1,#title-block-header .quarto-title-block>div>.h1{flex-grow:1}#title-block-header .quarto-title-block>div>button{flex-shrink:0;height:2.25rem;margin-top:0}@media(min-width: 992px){#title-block-header .quarto-title-block>div>button{margin-top:5px}}tr.header>th>p:last-of-type{margin-bottom:0px}table,table.table{margin-top:.5rem;margin-bottom:.5rem}caption,.table-caption{padding-top:.5rem;padding-bottom:.5rem;text-align:center}figure.quarto-float-tbl figcaption.quarto-float-caption-top{margin-top:.5rem;margin-bottom:.25rem;text-align:center}figure.quarto-float-tbl figcaption.quarto-float-caption-bottom{padding-top:.25rem;margin-bottom:.5rem;text-align:center}.utterances{max-width:none;margin-left:-8px}iframe{margin-bottom:1em}details{margin-bottom:1em}details[show]{margin-bottom:0}details>summary{color:#6c757d}details>summary>p:only-child{display:inline}pre.sourceCode,code.sourceCode{position:relative}p code:not(.sourceCode){white-space:pre-wrap}code{white-space:pre}@media print{code{white-space:pre-wrap}}pre>code{display:block}pre>code.sourceCode{white-space:pre}pre>code.sourceCode>span>a:first-child::before{text-decoration:none}pre.code-overflow-wrap>code.sourceCode{white-space:pre-wrap}pre.code-overflow-scroll>code.sourceCode{white-space:pre}code a:any-link{color:inherit;text-decoration:none}code a:hover{color:inherit;text-decoration:underline}ul.task-list{padding-left:1em}[data-tippy-root]{display:inline-block}.tippy-content .footnote-back{display:none}.footnote-back{margin-left:.2em}.tippy-content{overflow-x:auto}.quarto-embedded-source-code{display:none}.quarto-unresolved-ref{font-weight:600}.quarto-cover-image{max-width:35%;float:right;margin-left:30px}.cell-output-display .widget-subarea{margin-bottom:1em}.cell-output-display:not(.no-overflow-x),.knitsql-table:not(.no-overflow-x){overflow-x:auto}.panel-input{margin-bottom:1em}.panel-input>div,.panel-input>div>div{display:inline-block;vertical-align:top;padding-right:12px}.panel-input>p:last-child{margin-bottom:0}.layout-sidebar{margin-bottom:1em}.layout-sidebar .tab-content{border:none}.tab-content>.page-columns.active{display:grid}div.sourceCode>iframe{width:100%;height:300px;margin-bottom:-0.5em}a{text-underline-offset:3px}div.ansi-escaped-output{font-family:monospace;display:block}/*!
 *
 * ansi colors from IPython notebook's
 *
 * we also add `bright-[color]-` synonyms for the `-[color]-intense` classes since
 * that seems to be what ansi_up emits
 *
-*/.ansi-black-fg{color:#3e424d}.ansi-black-bg{background-color:#3e424d}.ansi-black-intense-black,.ansi-bright-black-fg{color:#282c36}.ansi-black-intense-black,.ansi-bright-black-bg{background-color:#282c36}.ansi-red-fg{color:#e75c58}.ansi-red-bg{background-color:#e75c58}.ansi-red-intense-red,.ansi-bright-red-fg{color:#b22b31}.ansi-red-intense-red,.ansi-bright-red-bg{background-color:#b22b31}.ansi-green-fg{color:#00a250}.ansi-green-bg{background-color:#00a250}.ansi-green-intense-green,.ansi-bright-green-fg{color:#007427}.ansi-green-intense-green,.ansi-bright-green-bg{background-color:#007427}.ansi-yellow-fg{color:#ddb62b}.ansi-yellow-bg{background-color:#ddb62b}.ansi-yellow-intense-yellow,.ansi-bright-yellow-fg{color:#b27d12}.ansi-yellow-intense-yellow,.ansi-bright-yellow-bg{background-color:#b27d12}.ansi-blue-fg{color:#208ffb}.ansi-blue-bg{background-color:#208ffb}.ansi-blue-intense-blue,.ansi-bright-blue-fg{color:#0065ca}.ansi-blue-intense-blue,.ansi-bright-blue-bg{background-color:#0065ca}.ansi-magenta-fg{color:#d160c4}.ansi-magenta-bg{background-color:#d160c4}.ansi-magenta-intense-magenta,.ansi-bright-magenta-fg{color:#a03196}.ansi-magenta-intense-magenta,.ansi-bright-magenta-bg{background-color:#a03196}.ansi-cyan-fg{color:#60c6c8}.ansi-cyan-bg{background-color:#60c6c8}.ansi-cyan-intense-cyan,.ansi-bright-cyan-fg{color:#258f8f}.ansi-cyan-intense-cyan,.ansi-bright-cyan-bg{background-color:#258f8f}.ansi-white-fg{color:#c5c1b4}.ansi-white-bg{background-color:#c5c1b4}.ansi-white-intense-white,.ansi-bright-white-fg{color:#a1a6b2}.ansi-white-intense-white,.ansi-bright-white-bg{background-color:#a1a6b2}.ansi-default-inverse-fg{color:#fff}.ansi-default-inverse-bg{background-color:#000}.ansi-bold{font-weight:bold}.ansi-underline{text-decoration:underline}:root{--quarto-body-bg: #fff;--quarto-body-color: #343a40;--quarto-text-muted: #6c757d;--quarto-border-color: #dee2e6;--quarto-border-width: 1px;--quarto-border-radius: 0.25rem}table.gt_table{color:var(--quarto-body-color);font-size:1em;width:100%;background-color:rgba(0,0,0,0);border-top-width:inherit;border-bottom-width:inherit;border-color:var(--quarto-border-color)}table.gt_table th.gt_column_spanner_outer{color:var(--quarto-body-color);background-color:rgba(0,0,0,0);border-top-width:inherit;border-bottom-width:inherit;border-color:var(--quarto-border-color)}table.gt_table th.gt_col_heading{color:var(--quarto-body-color);font-weight:bold;background-color:rgba(0,0,0,0)}table.gt_table thead.gt_col_headings{border-bottom:1px solid currentColor;border-top-width:inherit;border-top-color:var(--quarto-border-color)}table.gt_table thead.gt_col_headings:not(:first-child){border-top-width:1px;border-top-color:var(--quarto-border-color)}table.gt_table td.gt_row{border-bottom-width:1px;border-bottom-color:var(--quarto-border-color);border-top-width:0px}table.gt_table tbody.gt_table_body{border-top-width:1px;border-bottom-width:1px;border-bottom-color:var(--quarto-border-color);border-top-color:currentColor}div.columns{display:initial;gap:initial}div.column{display:inline-block;overflow-x:initial;vertical-align:top;width:50%}.code-annotation-tip-content{word-wrap:break-word}.code-annotation-container-hidden{display:none !important}dl.code-annotation-container-grid{display:grid;grid-template-columns:min-content auto}dl.code-annotation-container-grid dt{grid-column:1}dl.code-annotation-container-grid dd{grid-column:2}pre.sourceCode.code-annotation-code{padding-right:0}code.sourceCode .code-annotation-anchor{z-index:100;position:relative;float:right;background-color:rgba(0,0,0,0)}input[type=checkbox]{margin-right:.5ch}:root{--mermaid-bg-color: #fff;--mermaid-edge-color: #343a40;--mermaid-node-fg-color: #343a40;--mermaid-fg-color: #343a40;--mermaid-fg-color--lighter: #4b545c;--mermaid-fg-color--lightest: #626d78;--mermaid-font-family: Source Sans Pro, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica Neue, Arial, sans-serif, Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol;--mermaid-label-bg-color: #fff;--mermaid-label-fg-color: #2780e3;--mermaid-node-bg-color: rgba(39, 128, 227, 0.1);--mermaid-node-fg-color: #343a40}@media print{:root{font-size:11pt}#quarto-sidebar,#TOC,.nav-page{display:none}.page-columns .content{grid-column-start:page-start}.fixed-top{position:relative}.panel-caption,.figure-caption,figcaption{color:#666}}.code-copy-button{position:absolute;top:0;right:0;border:0;margin-top:5px;margin-right:5px;background-color:rgba(0,0,0,0);z-index:3}.code-copy-button:focus{outline:none}.code-copy-button-tooltip{font-size:.75em}pre.sourceCode:hover>.code-copy-button>.bi::before{display:inline-block;height:1rem;width:1rem;content:"";vertical-align:-0.125em;background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(106, 115, 125)" viewBox="0 0 16 16"><path d="M4 1.5H3a2 2 0 0 0-2 2V14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V3.5a2 2 0 0 0-2-2h-1v1h1a1 1 0 0 1 1 1V14a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V3.5a1 1 0 0 1 1-1h1v-1z"/><path d="M9.5 1a.5.5 0 0 1 .5.5v1a.5.5 0 0 1-.5.5h-3a.5.5 0 0 1-.5-.5v-1a.5.5 0 0 1 .5-.5h3zm-3-1A1.5 1.5 0 0 0 5 1.5v1A1.5 1.5 0 0 0 6.5 4h3A1.5 1.5 0 0 0 11 2.5v-1A1.5 1.5 0 0 0 9.5 0h-3z"/></svg>');background-repeat:no-repeat;background-size:1rem 1rem}pre.sourceCode:hover>.code-copy-button-checked>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(106, 115, 125)" viewBox="0 0 16 16"><path d="M13.854 3.646a.5.5 0 0 1 0 .708l-7 7a.5.5 0 0 1-.708 0l-3.5-3.5a.5.5 0 1 1 .708-.708L6.5 10.293l6.646-6.647a.5.5 0 0 1 .708 0z"/></svg>')}pre.sourceCode:hover>.code-copy-button:hover>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(111, 66, 193)" viewBox="0 0 16 16"><path d="M4 1.5H3a2 2 0 0 0-2 2V14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V3.5a2 2 0 0 0-2-2h-1v1h1a1 1 0 0 1 1 1V14a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V3.5a1 1 0 0 1 1-1h1v-1z"/><path d="M9.5 1a.5.5 0 0 1 .5.5v1a.5.5 0 0 1-.5.5h-3a.5.5 0 0 1-.5-.5v-1a.5.5 0 0 1 .5-.5h3zm-3-1A1.5 1.5 0 0 0 5 1.5v1A1.5 1.5 0 0 0 6.5 4h3A1.5 1.5 0 0 0 11 2.5v-1A1.5 1.5 0 0 0 9.5 0h-3z"/></svg>')}pre.sourceCode:hover>.code-copy-button-checked:hover>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(111, 66, 193)"  viewBox="0 0 16 16"><path d="M13.854 3.646a.5.5 0 0 1 0 .708l-7 7a.5.5 0 0 1-.708 0l-3.5-3.5a.5.5 0 1 1 .708-.708L6.5 10.293l6.646-6.647a.5.5 0 0 1 .708 0z"/></svg>')}main ol ol,main ul ul,main ol ul,main ul ol{margin-bottom:1em}ul>li:not(:has(>p))>ul,ol>li:not(:has(>p))>ul,ul>li:not(:has(>p))>ol,ol>li:not(:has(>p))>ol{margin-bottom:0}ul>li:not(:has(>p))>ul>li:has(>p),ol>li:not(:has(>p))>ul>li:has(>p),ul>li:not(:has(>p))>ol>li:has(>p),ol>li:not(:has(>p))>ol>li:has(>p){margin-top:1rem}body{margin:0}main.page-columns>header>h1.title,main.page-columns>header>.title.h1{margin-bottom:0}@media(min-width: 992px){body .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start page-start-inset] 35px [body-start-outset] 35px [body-start] 1.5em [body-content-start] minmax(500px, calc(850px - 3em)) [body-content-end] 1.5em [body-end] 35px [body-end-outset] minmax(75px, 145px) [page-end-inset] 35px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.fullcontent:not(.floating):not(.docked) .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start page-start-inset] 35px [body-start-outset] 35px [body-start] 1.5em [body-content-start] minmax(500px, calc(850px - 3em)) [body-content-end] 1.5em [body-end] 35px [body-end-outset] 35px [page-end-inset page-end] 5fr [screen-end-inset] 1.5em}body.slimcontent:not(.floating):not(.docked) .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start page-start-inset] 35px [body-start-outset] 35px [body-start] 1.5em [body-content-start] minmax(500px, calc(850px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(0px, 200px) [page-end-inset] 35px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.listing:not(.floating):not(.docked) .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start] minmax(50px, 100px) [page-start-inset] 50px [body-start-outset] 50px [body-start] 1.5em [body-content-start] minmax(500px, calc(850px - 3em)) [body-content-end] 3em [body-end] 50px [body-end-outset] minmax(0px, 250px) [page-end-inset] minmax(50px, 100px) [page-end] 1fr [screen-end-inset] 1.5em [screen-end]}body:not(.floating):not(.docked) .page-columns.toc-left{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] 35px [page-start-inset] minmax(0px, 175px) [body-start-outset] 35px [body-start] 1.5em [body-content-start] minmax(450px, calc(800px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(0px, 200px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body:not(.floating):not(.docked) .page-columns.toc-left .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] 35px [page-start-inset] minmax(0px, 175px) [body-start-outset] 35px [body-start] 1.5em [body-content-start] minmax(450px, calc(800px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(0px, 200px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.floating .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] minmax(25px, 50px) [page-start-inset] minmax(50px, 150px) [body-start-outset] minmax(25px, 50px) [body-start] 1.5em [body-content-start] minmax(500px, calc(800px - 3em)) [body-content-end] 1.5em [body-end] minmax(25px, 50px) [body-end-outset] minmax(50px, 150px) [page-end-inset] minmax(25px, 50px) [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.docked .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start] minmax(50px, 100px) [page-start-inset] 50px [body-start-outset] 50px [body-start] 1.5em [body-content-start] minmax(500px, calc(1000px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(50px, 100px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.docked.fullcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start] minmax(50px, 100px) [page-start-inset] 50px [body-start-outset] 50px [body-start] 1.5em [body-content-start] minmax(500px, calc(1000px - 3em)) [body-content-end] 1.5em [body-end body-end-outset page-end-inset page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.floating.fullcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] 50px [page-start-inset] minmax(50px, 150px) [body-start-outset] 50px [body-start] 1.5em [body-content-start] minmax(500px, calc(800px - 3em)) [body-content-end] 1.5em [body-end body-end-outset page-end-inset page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.docked.slimcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start] minmax(50px, 100px) [page-start-inset] 50px [body-start-outset] 50px [body-start] 1.5em [body-content-start] minmax(450px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(0px, 200px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.docked.listing .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start] minmax(50px, 100px) [page-start-inset] 50px [body-start-outset] 50px [body-start] 1.5em [body-content-start] minmax(500px, calc(1000px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(0px, 200px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.floating.slimcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] 50px [page-start-inset] minmax(50px, 150px) [body-start-outset] 50px [body-start] 1.5em [body-content-start] minmax(450px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(50px, 150px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.floating.listing .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] minmax(25px, 50px) [page-start-inset] minmax(50px, 150px) [body-start-outset] minmax(25px, 50px) [body-start] 1.5em [body-content-start] minmax(500px, calc(800px - 3em)) [body-content-end] 1.5em [body-end] minmax(25px, 50px) [body-end-outset] minmax(50px, 150px) [page-end-inset] minmax(25px, 50px) [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}}@media(max-width: 991.98px){body .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset] 5fr [body-start] 1.5em [body-content-start] minmax(500px, calc(800px - 3em)) [body-content-end] 1.5em [body-end] 35px [body-end-outset] minmax(75px, 145px) [page-end-inset] 35px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.fullcontent:not(.floating):not(.docked) .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset] 5fr [body-start] 1.5em [body-content-start] minmax(500px, calc(800px - 3em)) [body-content-end] 1.5em [body-end body-end-outset page-end-inset page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.slimcontent:not(.floating):not(.docked) .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset] 5fr [body-start] 1.5em [body-content-start] minmax(500px, calc(800px - 3em)) [body-content-end] 1.5em [body-end] 35px [body-end-outset] minmax(75px, 145px) [page-end-inset] 35px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.listing:not(.floating):not(.docked) .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset] 5fr [body-start] 1.5em [body-content-start] minmax(500px, calc(1250px - 3em)) [body-content-end body-end body-end-outset page-end-inset page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body:not(.floating):not(.docked) .page-columns.toc-left{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] 35px [page-start-inset] minmax(0px, 145px) [body-start-outset] 35px [body-start] 1.5em [body-content-start] minmax(450px, calc(800px - 3em)) [body-content-end] 1.5em [body-end body-end-outset page-end-inset page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body:not(.floating):not(.docked) .page-columns.toc-left .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] 35px [page-start-inset] minmax(0px, 145px) [body-start-outset] 35px [body-start] 1.5em [body-content-start] minmax(450px, calc(800px - 3em)) [body-content-end] 1.5em [body-end body-end-outset page-end-inset page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.floating .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start page-start-inset body-start-outset body-start] 1.5em [body-content-start] minmax(500px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(75px, 150px) [page-end-inset] 25px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.docked .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset body-start body-content-start] minmax(500px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(25px, 50px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.docked.fullcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset body-start body-content-start] minmax(500px, calc(1000px - 3em)) [body-content-end] 1.5em [body-end body-end-outset page-end-inset page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.floating.fullcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start page-start-inset body-start-outset body-start] 1em [body-content-start] minmax(500px, calc(800px - 3em)) [body-content-end] 1.5em [body-end body-end-outset page-end-inset page-end] 4fr [screen-end-inset] 1.5em [screen-end]}body.docked.slimcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset body-start body-content-start] minmax(500px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(25px, 50px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.docked.listing .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset body-start body-content-start] minmax(500px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(25px, 50px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.floating.slimcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start page-start-inset body-start-outset body-start] 1em [body-content-start] minmax(500px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 35px [body-end-outset] minmax(75px, 145px) [page-end-inset] 35px [page-end] 4fr [screen-end-inset] 1.5em [screen-end]}body.floating.listing .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start page-start-inset body-start-outset body-start] 1em [body-content-start] minmax(500px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(75px, 150px) [page-end-inset] 25px [page-end] 4fr [screen-end-inset] 1.5em [screen-end]}}@media(max-width: 767.98px){body .page-columns,body.fullcontent:not(.floating):not(.docked) .page-columns,body.slimcontent:not(.floating):not(.docked) .page-columns,body.docked .page-columns,body.docked.slimcontent .page-columns,body.docked.fullcontent .page-columns,body.floating .page-columns,body.floating.slimcontent .page-columns,body.floating.fullcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset body-start body-content-start] minmax(0px, 1fr) [body-content-end body-end body-end-outset page-end-inset page-end screen-end-inset] 1.5em [screen-end]}body:not(.floating):not(.docked) .page-columns.toc-left{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset body-start body-content-start] minmax(0px, 1fr) [body-content-end body-end body-end-outset page-end-inset page-end screen-end-inset] 1.5em [screen-end]}body:not(.floating):not(.docked) .page-columns.toc-left .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset body-start body-content-start] minmax(0px, 1fr) [body-content-end body-end body-end-outset page-end-inset page-end screen-end-inset] 1.5em [screen-end]}nav[role=doc-toc]{display:none}}body,.page-row-navigation{grid-template-rows:[page-top] max-content [contents-top] max-content [contents-bottom] max-content [page-bottom]}.page-rows-contents{grid-template-rows:[content-top] minmax(max-content, 1fr) [content-bottom] minmax(60px, max-content) [page-bottom]}.page-full{grid-column:screen-start/screen-end !important}.page-columns>*{grid-column:body-content-start/body-content-end}.page-columns.column-page>*{grid-column:page-start/page-end}.page-columns.column-page-left .page-columns.page-full>*,.page-columns.column-page-left>*{grid-column:page-start/body-content-end}.page-columns.column-page-right .page-columns.page-full>*,.page-columns.column-page-right>*{grid-column:body-content-start/page-end}.page-rows{grid-auto-rows:auto}.header{grid-column:screen-start/screen-end;grid-row:page-top/contents-top}#quarto-content{padding:0;grid-column:screen-start/screen-end;grid-row:contents-top/contents-bottom}body.floating .sidebar.sidebar-navigation{grid-column:page-start/body-start;grid-row:content-top/page-bottom}body.docked .sidebar.sidebar-navigation{grid-column:screen-start/body-start;grid-row:content-top/page-bottom}.sidebar.toc-left{grid-column:page-start/body-start;grid-row:content-top/page-bottom}.sidebar.margin-sidebar{grid-column:body-end/page-end;grid-row:content-top/page-bottom}.page-columns .content{grid-column:body-content-start/body-content-end;grid-row:content-top/content-bottom;align-content:flex-start}.page-columns .page-navigation{grid-column:body-content-start/body-content-end;grid-row:content-bottom/page-bottom}.page-columns .footer{grid-column:screen-start/screen-end;grid-row:contents-bottom/page-bottom}.page-columns .column-body{grid-column:body-content-start/body-content-end}.page-columns .column-body-fullbleed{grid-column:body-start/body-end}.page-columns .column-body-outset{grid-column:body-start-outset/body-end-outset;z-index:998;opacity:.999}.page-columns .column-body-outset table{background:#fff}.page-columns .column-body-outset-left{grid-column:body-start-outset/body-content-end;z-index:998;opacity:.999}.page-columns .column-body-outset-left table{background:#fff}.page-columns .column-body-outset-right{grid-column:body-content-start/body-end-outset;z-index:998;opacity:.999}.page-columns .column-body-outset-right table{background:#fff}.page-columns .column-page{grid-column:page-start/page-end;z-index:998;opacity:.999}.page-columns .column-page table{background:#fff}.page-columns .column-page-inset{grid-column:page-start-inset/page-end-inset;z-index:998;opacity:.999}.page-columns .column-page-inset table{background:#fff}.page-columns .column-page-inset-left{grid-column:page-start-inset/body-content-end;z-index:998;opacity:.999}.page-columns .column-page-inset-left table{background:#fff}.page-columns .column-page-inset-right{grid-column:body-content-start/page-end-inset;z-index:998;opacity:.999}.page-columns .column-page-inset-right figcaption table{background:#fff}.page-columns .column-page-left{grid-column:page-start/body-content-end;z-index:998;opacity:.999}.page-columns .column-page-left table{background:#fff}.page-columns .column-page-right{grid-column:body-content-start/page-end;z-index:998;opacity:.999}.page-columns .column-page-right figcaption table{background:#fff}#quarto-content.page-columns #quarto-margin-sidebar,#quarto-content.page-columns #quarto-sidebar{z-index:1}@media(max-width: 991.98px){#quarto-content.page-columns #quarto-margin-sidebar.collapse,#quarto-content.page-columns #quarto-sidebar.collapse,#quarto-content.page-columns #quarto-margin-sidebar.collapsing,#quarto-content.page-columns #quarto-sidebar.collapsing{z-index:1055}}#quarto-content.page-columns main.column-page,#quarto-content.page-columns main.column-page-right,#quarto-content.page-columns main.column-page-left{z-index:0}.page-columns .column-screen-inset{grid-column:screen-start-inset/screen-end-inset;z-index:998;opacity:.999}.page-columns .column-screen-inset table{background:#fff}.page-columns .column-screen-inset-left{grid-column:screen-start-inset/body-content-end;z-index:998;opacity:.999}.page-columns .column-screen-inset-left table{background:#fff}.page-columns .column-screen-inset-right{grid-column:body-content-start/screen-end-inset;z-index:998;opacity:.999}.page-columns .column-screen-inset-right table{background:#fff}.page-columns .column-screen{grid-column:screen-start/screen-end;z-index:998;opacity:.999}.page-columns .column-screen table{background:#fff}.page-columns .column-screen-left{grid-column:screen-start/body-content-end;z-index:998;opacity:.999}.page-columns .column-screen-left table{background:#fff}.page-columns .column-screen-right{grid-column:body-content-start/screen-end;z-index:998;opacity:.999}.page-columns .column-screen-right table{background:#fff}.page-columns .column-screen-inset-shaded{grid-column:screen-start/screen-end;padding:1em;background:#f8f9fa;z-index:998;opacity:.999;margin-bottom:1em}.zindex-content{z-index:998;opacity:.999}.zindex-modal{z-index:1055;opacity:.999}.zindex-over-content{z-index:999;opacity:.999}img.img-fluid.column-screen,img.img-fluid.column-screen-inset-shaded,img.img-fluid.column-screen-inset,img.img-fluid.column-screen-inset-left,img.img-fluid.column-screen-inset-right,img.img-fluid.column-screen-left,img.img-fluid.column-screen-right{width:100%}@media(min-width: 992px){.margin-caption,div.aside,aside:not(.footnotes):not(.sidebar),.column-margin{grid-column:body-end/page-end !important;z-index:998}.column-sidebar{grid-column:page-start/body-start !important;z-index:998}.column-leftmargin{grid-column:screen-start-inset/body-start !important;z-index:998}.no-row-height{height:1em;overflow:visible}}@media(max-width: 991.98px){.margin-caption,div.aside,aside:not(.footnotes):not(.sidebar),.column-margin{grid-column:body-end/page-end !important;z-index:998}.no-row-height{height:1em;overflow:visible}.page-columns.page-full{overflow:visible}.page-columns.toc-left .margin-caption,.page-columns.toc-left div.aside,.page-columns.toc-left aside:not(.footnotes):not(.sidebar),.page-columns.toc-left .column-margin{grid-column:body-content-start/body-content-end !important;z-index:998;opacity:.999}.page-columns.toc-left .no-row-height{height:initial;overflow:initial}}@media(max-width: 767.98px){.margin-caption,div.aside,aside:not(.footnotes):not(.sidebar),.column-margin{grid-column:body-content-start/body-content-end !important;z-index:998;opacity:.999}.no-row-height{height:initial;overflow:initial}#quarto-margin-sidebar{display:none}#quarto-sidebar-toc-left{display:none}.hidden-sm{display:none}}.panel-grid{display:grid;grid-template-rows:repeat(1, 1fr);grid-template-columns:repeat(24, 1fr);gap:1em}.panel-grid .g-col-1{grid-column:auto/span 1}.panel-grid .g-col-2{grid-column:auto/span 2}.panel-grid .g-col-3{grid-column:auto/span 3}.panel-grid .g-col-4{grid-column:auto/span 4}.panel-grid .g-col-5{grid-column:auto/span 5}.panel-grid .g-col-6{grid-column:auto/span 6}.panel-grid .g-col-7{grid-column:auto/span 7}.panel-grid .g-col-8{grid-column:auto/span 8}.panel-grid .g-col-9{grid-column:auto/span 9}.panel-grid .g-col-10{grid-column:auto/span 10}.panel-grid .g-col-11{grid-column:auto/span 11}.panel-grid .g-col-12{grid-column:auto/span 12}.panel-grid .g-col-13{grid-column:auto/span 13}.panel-grid .g-col-14{grid-column:auto/span 14}.panel-grid .g-col-15{grid-column:auto/span 15}.panel-grid .g-col-16{grid-column:auto/span 16}.panel-grid .g-col-17{grid-column:auto/span 17}.panel-grid .g-col-18{grid-column:auto/span 18}.panel-grid .g-col-19{grid-column:auto/span 19}.panel-grid .g-col-20{grid-column:auto/span 20}.panel-grid .g-col-21{grid-column:auto/span 21}.panel-grid .g-col-22{grid-column:auto/span 22}.panel-grid .g-col-23{grid-column:auto/span 23}.panel-grid .g-col-24{grid-column:auto/span 24}.panel-grid .g-start-1{grid-column-start:1}.panel-grid .g-start-2{grid-column-start:2}.panel-grid .g-start-3{grid-column-start:3}.panel-grid .g-start-4{grid-column-start:4}.panel-grid .g-start-5{grid-column-start:5}.panel-grid .g-start-6{grid-column-start:6}.panel-grid .g-start-7{grid-column-start:7}.panel-grid .g-start-8{grid-column-start:8}.panel-grid .g-start-9{grid-column-start:9}.panel-grid .g-start-10{grid-column-start:10}.panel-grid .g-start-11{grid-column-start:11}.panel-grid .g-start-12{grid-column-start:12}.panel-grid .g-start-13{grid-column-start:13}.panel-grid .g-start-14{grid-column-start:14}.panel-grid .g-start-15{grid-column-start:15}.panel-grid .g-start-16{grid-column-start:16}.panel-grid .g-start-17{grid-column-start:17}.panel-grid .g-start-18{grid-column-start:18}.panel-grid .g-start-19{grid-column-start:19}.panel-grid .g-start-20{grid-column-start:20}.panel-grid .g-start-21{grid-column-start:21}.panel-grid .g-start-22{grid-column-start:22}.panel-grid .g-start-23{grid-column-start:23}@media(min-width: 576px){.panel-grid .g-col-sm-1{grid-column:auto/span 1}.panel-grid .g-col-sm-2{grid-column:auto/span 2}.panel-grid .g-col-sm-3{grid-column:auto/span 3}.panel-grid .g-col-sm-4{grid-column:auto/span 4}.panel-grid .g-col-sm-5{grid-column:auto/span 5}.panel-grid .g-col-sm-6{grid-column:auto/span 6}.panel-grid .g-col-sm-7{grid-column:auto/span 7}.panel-grid .g-col-sm-8{grid-column:auto/span 8}.panel-grid .g-col-sm-9{grid-column:auto/span 9}.panel-grid .g-col-sm-10{grid-column:auto/span 10}.panel-grid .g-col-sm-11{grid-column:auto/span 11}.panel-grid .g-col-sm-12{grid-column:auto/span 12}.panel-grid .g-col-sm-13{grid-column:auto/span 13}.panel-grid .g-col-sm-14{grid-column:auto/span 14}.panel-grid .g-col-sm-15{grid-column:auto/span 15}.panel-grid .g-col-sm-16{grid-column:auto/span 16}.panel-grid .g-col-sm-17{grid-column:auto/span 17}.panel-grid .g-col-sm-18{grid-column:auto/span 18}.panel-grid .g-col-sm-19{grid-column:auto/span 19}.panel-grid .g-col-sm-20{grid-column:auto/span 20}.panel-grid .g-col-sm-21{grid-column:auto/span 21}.panel-grid .g-col-sm-22{grid-column:auto/span 22}.panel-grid .g-col-sm-23{grid-column:auto/span 23}.panel-grid .g-col-sm-24{grid-column:auto/span 24}.panel-grid .g-start-sm-1{grid-column-start:1}.panel-grid .g-start-sm-2{grid-column-start:2}.panel-grid .g-start-sm-3{grid-column-start:3}.panel-grid .g-start-sm-4{grid-column-start:4}.panel-grid .g-start-sm-5{grid-column-start:5}.panel-grid .g-start-sm-6{grid-column-start:6}.panel-grid .g-start-sm-7{grid-column-start:7}.panel-grid .g-start-sm-8{grid-column-start:8}.panel-grid .g-start-sm-9{grid-column-start:9}.panel-grid .g-start-sm-10{grid-column-start:10}.panel-grid .g-start-sm-11{grid-column-start:11}.panel-grid .g-start-sm-12{grid-column-start:12}.panel-grid .g-start-sm-13{grid-column-start:13}.panel-grid .g-start-sm-14{grid-column-start:14}.panel-grid .g-start-sm-15{grid-column-start:15}.panel-grid .g-start-sm-16{grid-column-start:16}.panel-grid .g-start-sm-17{grid-column-start:17}.panel-grid .g-start-sm-18{grid-column-start:18}.panel-grid .g-start-sm-19{grid-column-start:19}.panel-grid .g-start-sm-20{grid-column-start:20}.panel-grid .g-start-sm-21{grid-column-start:21}.panel-grid .g-start-sm-22{grid-column-start:22}.panel-grid .g-start-sm-23{grid-column-start:23}}@media(min-width: 768px){.panel-grid .g-col-md-1{grid-column:auto/span 1}.panel-grid .g-col-md-2{grid-column:auto/span 2}.panel-grid .g-col-md-3{grid-column:auto/span 3}.panel-grid .g-col-md-4{grid-column:auto/span 4}.panel-grid .g-col-md-5{grid-column:auto/span 5}.panel-grid .g-col-md-6{grid-column:auto/span 6}.panel-grid .g-col-md-7{grid-column:auto/span 7}.panel-grid .g-col-md-8{grid-column:auto/span 8}.panel-grid .g-col-md-9{grid-column:auto/span 9}.panel-grid .g-col-md-10{grid-column:auto/span 10}.panel-grid .g-col-md-11{grid-column:auto/span 11}.panel-grid .g-col-md-12{grid-column:auto/span 12}.panel-grid .g-col-md-13{grid-column:auto/span 13}.panel-grid .g-col-md-14{grid-column:auto/span 14}.panel-grid .g-col-md-15{grid-column:auto/span 15}.panel-grid .g-col-md-16{grid-column:auto/span 16}.panel-grid .g-col-md-17{grid-column:auto/span 17}.panel-grid .g-col-md-18{grid-column:auto/span 18}.panel-grid .g-col-md-19{grid-column:auto/span 19}.panel-grid .g-col-md-20{grid-column:auto/span 20}.panel-grid .g-col-md-21{grid-column:auto/span 21}.panel-grid .g-col-md-22{grid-column:auto/span 22}.panel-grid .g-col-md-23{grid-column:auto/span 23}.panel-grid .g-col-md-24{grid-column:auto/span 24}.panel-grid .g-start-md-1{grid-column-start:1}.panel-grid .g-start-md-2{grid-column-start:2}.panel-grid .g-start-md-3{grid-column-start:3}.panel-grid .g-start-md-4{grid-column-start:4}.panel-grid .g-start-md-5{grid-column-start:5}.panel-grid .g-start-md-6{grid-column-start:6}.panel-grid .g-start-md-7{grid-column-start:7}.panel-grid .g-start-md-8{grid-column-start:8}.panel-grid .g-start-md-9{grid-column-start:9}.panel-grid .g-start-md-10{grid-column-start:10}.panel-grid .g-start-md-11{grid-column-start:11}.panel-grid .g-start-md-12{grid-column-start:12}.panel-grid .g-start-md-13{grid-column-start:13}.panel-grid .g-start-md-14{grid-column-start:14}.panel-grid .g-start-md-15{grid-column-start:15}.panel-grid .g-start-md-16{grid-column-start:16}.panel-grid .g-start-md-17{grid-column-start:17}.panel-grid .g-start-md-18{grid-column-start:18}.panel-grid .g-start-md-19{grid-column-start:19}.panel-grid .g-start-md-20{grid-column-start:20}.panel-grid .g-start-md-21{grid-column-start:21}.panel-grid .g-start-md-22{grid-column-start:22}.panel-grid .g-start-md-23{grid-column-start:23}}@media(min-width: 992px){.panel-grid .g-col-lg-1{grid-column:auto/span 1}.panel-grid .g-col-lg-2{grid-column:auto/span 2}.panel-grid .g-col-lg-3{grid-column:auto/span 3}.panel-grid .g-col-lg-4{grid-column:auto/span 4}.panel-grid .g-col-lg-5{grid-column:auto/span 5}.panel-grid .g-col-lg-6{grid-column:auto/span 6}.panel-grid .g-col-lg-7{grid-column:auto/span 7}.panel-grid .g-col-lg-8{grid-column:auto/span 8}.panel-grid .g-col-lg-9{grid-column:auto/span 9}.panel-grid .g-col-lg-10{grid-column:auto/span 10}.panel-grid .g-col-lg-11{grid-column:auto/span 11}.panel-grid .g-col-lg-12{grid-column:auto/span 12}.panel-grid .g-col-lg-13{grid-column:auto/span 13}.panel-grid .g-col-lg-14{grid-column:auto/span 14}.panel-grid .g-col-lg-15{grid-column:auto/span 15}.panel-grid .g-col-lg-16{grid-column:auto/span 16}.panel-grid .g-col-lg-17{grid-column:auto/span 17}.panel-grid .g-col-lg-18{grid-column:auto/span 18}.panel-grid .g-col-lg-19{grid-column:auto/span 19}.panel-grid .g-col-lg-20{grid-column:auto/span 20}.panel-grid .g-col-lg-21{grid-column:auto/span 21}.panel-grid .g-col-lg-22{grid-column:auto/span 22}.panel-grid .g-col-lg-23{grid-column:auto/span 23}.panel-grid .g-col-lg-24{grid-column:auto/span 24}.panel-grid .g-start-lg-1{grid-column-start:1}.panel-grid .g-start-lg-2{grid-column-start:2}.panel-grid .g-start-lg-3{grid-column-start:3}.panel-grid .g-start-lg-4{grid-column-start:4}.panel-grid .g-start-lg-5{grid-column-start:5}.panel-grid .g-start-lg-6{grid-column-start:6}.panel-grid .g-start-lg-7{grid-column-start:7}.panel-grid .g-start-lg-8{grid-column-start:8}.panel-grid .g-start-lg-9{grid-column-start:9}.panel-grid .g-start-lg-10{grid-column-start:10}.panel-grid .g-start-lg-11{grid-column-start:11}.panel-grid .g-start-lg-12{grid-column-start:12}.panel-grid .g-start-lg-13{grid-column-start:13}.panel-grid .g-start-lg-14{grid-column-start:14}.panel-grid .g-start-lg-15{grid-column-start:15}.panel-grid .g-start-lg-16{grid-column-start:16}.panel-grid .g-start-lg-17{grid-column-start:17}.panel-grid .g-start-lg-18{grid-column-start:18}.panel-grid .g-start-lg-19{grid-column-start:19}.panel-grid .g-start-lg-20{grid-column-start:20}.panel-grid .g-start-lg-21{grid-column-start:21}.panel-grid .g-start-lg-22{grid-column-start:22}.panel-grid .g-start-lg-23{grid-column-start:23}}@media(min-width: 1200px){.panel-grid .g-col-xl-1{grid-column:auto/span 1}.panel-grid .g-col-xl-2{grid-column:auto/span 2}.panel-grid .g-col-xl-3{grid-column:auto/span 3}.panel-grid .g-col-xl-4{grid-column:auto/span 4}.panel-grid .g-col-xl-5{grid-column:auto/span 5}.panel-grid .g-col-xl-6{grid-column:auto/span 6}.panel-grid .g-col-xl-7{grid-column:auto/span 7}.panel-grid .g-col-xl-8{grid-column:auto/span 8}.panel-grid .g-col-xl-9{grid-column:auto/span 9}.panel-grid .g-col-xl-10{grid-column:auto/span 10}.panel-grid .g-col-xl-11{grid-column:auto/span 11}.panel-grid .g-col-xl-12{grid-column:auto/span 12}.panel-grid .g-col-xl-13{grid-column:auto/span 13}.panel-grid .g-col-xl-14{grid-column:auto/span 14}.panel-grid .g-col-xl-15{grid-column:auto/span 15}.panel-grid .g-col-xl-16{grid-column:auto/span 16}.panel-grid .g-col-xl-17{grid-column:auto/span 17}.panel-grid .g-col-xl-18{grid-column:auto/span 18}.panel-grid .g-col-xl-19{grid-column:auto/span 19}.panel-grid .g-col-xl-20{grid-column:auto/span 20}.panel-grid .g-col-xl-21{grid-column:auto/span 21}.panel-grid .g-col-xl-22{grid-column:auto/span 22}.panel-grid .g-col-xl-23{grid-column:auto/span 23}.panel-grid .g-col-xl-24{grid-column:auto/span 24}.panel-grid .g-start-xl-1{grid-column-start:1}.panel-grid .g-start-xl-2{grid-column-start:2}.panel-grid .g-start-xl-3{grid-column-start:3}.panel-grid .g-start-xl-4{grid-column-start:4}.panel-grid .g-start-xl-5{grid-column-start:5}.panel-grid .g-start-xl-6{grid-column-start:6}.panel-grid .g-start-xl-7{grid-column-start:7}.panel-grid .g-start-xl-8{grid-column-start:8}.panel-grid .g-start-xl-9{grid-column-start:9}.panel-grid .g-start-xl-10{grid-column-start:10}.panel-grid .g-start-xl-11{grid-column-start:11}.panel-grid .g-start-xl-12{grid-column-start:12}.panel-grid .g-start-xl-13{grid-column-start:13}.panel-grid .g-start-xl-14{grid-column-start:14}.panel-grid .g-start-xl-15{grid-column-start:15}.panel-grid .g-start-xl-16{grid-column-start:16}.panel-grid .g-start-xl-17{grid-column-start:17}.panel-grid .g-start-xl-18{grid-column-start:18}.panel-grid .g-start-xl-19{grid-column-start:19}.panel-grid .g-start-xl-20{grid-column-start:20}.panel-grid .g-start-xl-21{grid-column-start:21}.panel-grid .g-start-xl-22{grid-column-start:22}.panel-grid .g-start-xl-23{grid-column-start:23}}@media(min-width: 1400px){.panel-grid .g-col-xxl-1{grid-column:auto/span 1}.panel-grid .g-col-xxl-2{grid-column:auto/span 2}.panel-grid .g-col-xxl-3{grid-column:auto/span 3}.panel-grid .g-col-xxl-4{grid-column:auto/span 4}.panel-grid .g-col-xxl-5{grid-column:auto/span 5}.panel-grid .g-col-xxl-6{grid-column:auto/span 6}.panel-grid .g-col-xxl-7{grid-column:auto/span 7}.panel-grid .g-col-xxl-8{grid-column:auto/span 8}.panel-grid .g-col-xxl-9{grid-column:auto/span 9}.panel-grid .g-col-xxl-10{grid-column:auto/span 10}.panel-grid .g-col-xxl-11{grid-column:auto/span 11}.panel-grid .g-col-xxl-12{grid-column:auto/span 12}.panel-grid .g-col-xxl-13{grid-column:auto/span 13}.panel-grid .g-col-xxl-14{grid-column:auto/span 14}.panel-grid .g-col-xxl-15{grid-column:auto/span 15}.panel-grid .g-col-xxl-16{grid-column:auto/span 16}.panel-grid .g-col-xxl-17{grid-column:auto/span 17}.panel-grid .g-col-xxl-18{grid-column:auto/span 18}.panel-grid .g-col-xxl-19{grid-column:auto/span 19}.panel-grid .g-col-xxl-20{grid-column:auto/span 20}.panel-grid .g-col-xxl-21{grid-column:auto/span 21}.panel-grid .g-col-xxl-22{grid-column:auto/span 22}.panel-grid .g-col-xxl-23{grid-column:auto/span 23}.panel-grid .g-col-xxl-24{grid-column:auto/span 24}.panel-grid .g-start-xxl-1{grid-column-start:1}.panel-grid .g-start-xxl-2{grid-column-start:2}.panel-grid .g-start-xxl-3{grid-column-start:3}.panel-grid .g-start-xxl-4{grid-column-start:4}.panel-grid .g-start-xxl-5{grid-column-start:5}.panel-grid .g-start-xxl-6{grid-column-start:6}.panel-grid .g-start-xxl-7{grid-column-start:7}.panel-grid .g-start-xxl-8{grid-column-start:8}.panel-grid .g-start-xxl-9{grid-column-start:9}.panel-grid .g-start-xxl-10{grid-column-start:10}.panel-grid .g-start-xxl-11{grid-column-start:11}.panel-grid .g-start-xxl-12{grid-column-start:12}.panel-grid .g-start-xxl-13{grid-column-start:13}.panel-grid .g-start-xxl-14{grid-column-start:14}.panel-grid .g-start-xxl-15{grid-column-start:15}.panel-grid .g-start-xxl-16{grid-column-start:16}.panel-grid .g-start-xxl-17{grid-column-start:17}.panel-grid .g-start-xxl-18{grid-column-start:18}.panel-grid .g-start-xxl-19{grid-column-start:19}.panel-grid .g-start-xxl-20{grid-column-start:20}.panel-grid .g-start-xxl-21{grid-column-start:21}.panel-grid .g-start-xxl-22{grid-column-start:22}.panel-grid .g-start-xxl-23{grid-column-start:23}}main{margin-top:1em;margin-bottom:1em}h1,.h1,h2,.h2{color:inherit;margin-top:2rem;margin-bottom:1rem;font-weight:600}h1.title,.title.h1{margin-top:0}main.content>section:first-of-type>h2:first-child,main.content>section:first-of-type>.h2:first-child{margin-top:0}h2,.h2{border-bottom:1px solid #dee2e6;padding-bottom:.5rem}h3,.h3{font-weight:600}h3,.h3,h4,.h4{opacity:.9;margin-top:1.5rem}h5,.h5,h6,.h6{opacity:.9}.header-section-number{color:#6d7a86}.nav-link.active .header-section-number{color:inherit}mark,.mark{padding:0em}.panel-caption,.figure-caption,.subfigure-caption,.table-caption,figcaption,caption{font-size:.9rem;color:#6d7a86}.quarto-layout-cell[data-ref-parent] caption{color:#6d7a86}.column-margin figcaption,.margin-caption,div.aside,aside,.column-margin{color:#6d7a86;font-size:.825rem}.panel-caption.margin-caption{text-align:inherit}.column-margin.column-container p{margin-bottom:0}.column-margin.column-container>*:not(.collapse):first-child{padding-bottom:.5em;display:block}.column-margin.column-container>*:not(.collapse):not(:first-child){padding-top:.5em;padding-bottom:.5em;display:block}.column-margin.column-container>*.collapse:not(.show){display:none}@media(min-width: 768px){.column-margin.column-container .callout-margin-content:first-child{margin-top:4.5em}.column-margin.column-container .callout-margin-content-simple:first-child{margin-top:3.5em}}.margin-caption>*{padding-top:.5em;padding-bottom:.5em}@media(max-width: 767.98px){.quarto-layout-row{flex-direction:column}}.nav-tabs .nav-item{margin-top:1px;cursor:pointer}.tab-content{margin-top:0px;border-left:#dee2e6 1px solid;border-right:#dee2e6 1px solid;border-bottom:#dee2e6 1px solid;margin-left:0;padding:1em;margin-bottom:1em}@media(max-width: 767.98px){.layout-sidebar{margin-left:0;margin-right:0}}.panel-sidebar,.panel-sidebar .form-control,.panel-input,.panel-input .form-control,.selectize-dropdown{font-size:.9rem}.panel-sidebar .form-control,.panel-input .form-control{padding-top:.1rem}.tab-pane div.sourceCode{margin-top:0px}.tab-pane>p{padding-top:0}.tab-pane>p:nth-child(1){padding-top:0}.tab-pane>p:last-child{margin-bottom:0}.tab-pane>pre:last-child{margin-bottom:0}.tab-content>.tab-pane:not(.active){display:none !important}div.sourceCode{background-color:rgba(233,236,239,.65);border:1px solid rgba(233,236,239,.65);border-radius:.25rem}pre.sourceCode{background-color:rgba(0,0,0,0)}pre.sourceCode{border:none;font-size:.875em;overflow:visible !important;padding:.4em}.callout pre.sourceCode{padding-left:0}div.sourceCode{overflow-y:hidden}.callout div.sourceCode{margin-left:initial}.blockquote{font-size:inherit;padding-left:1rem;padding-right:1.5rem;color:#6d7a86}.blockquote h1:first-child,.blockquote .h1:first-child,.blockquote h2:first-child,.blockquote .h2:first-child,.blockquote h3:first-child,.blockquote .h3:first-child,.blockquote h4:first-child,.blockquote .h4:first-child,.blockquote h5:first-child,.blockquote .h5:first-child{margin-top:0}pre{background-color:initial;padding:initial;border:initial}p pre code:not(.sourceCode),li pre code:not(.sourceCode),pre code:not(.sourceCode){background-color:initial}p code:not(.sourceCode),li code:not(.sourceCode),td code:not(.sourceCode){background-color:#f8f9fa;padding:.2em}nav p code:not(.sourceCode),nav li code:not(.sourceCode),nav td code:not(.sourceCode){background-color:rgba(0,0,0,0);padding:0}td code:not(.sourceCode){white-space:pre-wrap}#quarto-embedded-source-code-modal>.modal-dialog{max-width:1000px;padding-left:1.75rem;padding-right:1.75rem}#quarto-embedded-source-code-modal>.modal-dialog>.modal-content>.modal-body{padding:0}#quarto-embedded-source-code-modal>.modal-dialog>.modal-content>.modal-body div.sourceCode{margin:0;padding:.2rem .2rem;border-radius:0px;border:none}#quarto-embedded-source-code-modal>.modal-dialog>.modal-content>.modal-header{padding:.7rem}.code-tools-button{font-size:1rem;padding:.15rem .15rem;margin-left:5px;color:#6c757d;background-color:rgba(0,0,0,0);transition:initial;cursor:pointer}.code-tools-button>.bi::before{display:inline-block;height:1rem;width:1rem;content:"";vertical-align:-0.125em;background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(108, 117, 125)" viewBox="0 0 16 16"><path d="M10.478 1.647a.5.5 0 1 0-.956-.294l-4 13a.5.5 0 0 0 .956.294l4-13zM4.854 4.146a.5.5 0 0 1 0 .708L1.707 8l3.147 3.146a.5.5 0 0 1-.708.708l-3.5-3.5a.5.5 0 0 1 0-.708l3.5-3.5a.5.5 0 0 1 .708 0zm6.292 0a.5.5 0 0 0 0 .708L14.293 8l-3.147 3.146a.5.5 0 0 0 .708.708l3.5-3.5a.5.5 0 0 0 0-.708l-3.5-3.5a.5.5 0 0 0-.708 0z"/></svg>');background-repeat:no-repeat;background-size:1rem 1rem}.code-tools-button:hover>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(52, 58, 64)" viewBox="0 0 16 16"><path d="M10.478 1.647a.5.5 0 1 0-.956-.294l-4 13a.5.5 0 0 0 .956.294l4-13zM4.854 4.146a.5.5 0 0 1 0 .708L1.707 8l3.147 3.146a.5.5 0 0 1-.708.708l-3.5-3.5a.5.5 0 0 1 0-.708l3.5-3.5a.5.5 0 0 1 .708 0zm6.292 0a.5.5 0 0 0 0 .708L14.293 8l-3.147 3.146a.5.5 0 0 0 .708.708l3.5-3.5a.5.5 0 0 0 0-.708l-3.5-3.5a.5.5 0 0 0-.708 0z"/></svg>')}#quarto-embedded-source-code-modal .code-copy-button>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(108, 117, 125)" viewBox="0 0 16 16"><path d="M4 1.5H3a2 2 0 0 0-2 2V14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V3.5a2 2 0 0 0-2-2h-1v1h1a1 1 0 0 1 1 1V14a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V3.5a1 1 0 0 1 1-1h1v-1z"/><path d="M9.5 1a.5.5 0 0 1 .5.5v1a.5.5 0 0 1-.5.5h-3a.5.5 0 0 1-.5-.5v-1a.5.5 0 0 1 .5-.5h3zm-3-1A1.5 1.5 0 0 0 5 1.5v1A1.5 1.5 0 0 0 6.5 4h3A1.5 1.5 0 0 0 11 2.5v-1A1.5 1.5 0 0 0 9.5 0h-3z"/></svg>')}#quarto-embedded-source-code-modal .code-copy-button-checked>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(108, 117, 125)" viewBox="0 0 16 16"><path d="M13.854 3.646a.5.5 0 0 1 0 .708l-7 7a.5.5 0 0 1-.708 0l-3.5-3.5a.5.5 0 1 1 .708-.708L6.5 10.293l6.646-6.647a.5.5 0 0 1 .708 0z"/></svg>')}.sidebar{will-change:top;transition:top 200ms linear;position:sticky;overflow-y:auto;padding-top:1.2em;max-height:100vh}.sidebar.toc-left,.sidebar.margin-sidebar{top:0px;padding-top:1em}.sidebar.quarto-banner-title-block-sidebar>*{padding-top:1.65em}figure .quarto-notebook-link{margin-top:.5em}.quarto-notebook-link{font-size:.75em;color:#6c757d;margin-bottom:1em;text-decoration:none;display:block}.quarto-notebook-link:hover{text-decoration:underline;color:#2761e3}.quarto-notebook-link::before{display:inline-block;height:.75rem;width:.75rem;margin-bottom:0em;margin-right:.25em;content:"";vertical-align:-0.125em;background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(108, 117, 125)" class="bi bi-journal-code" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8.646 5.646a.5.5 0 0 1 .708 0l2 2a.5.5 0 0 1 0 .708l-2 2a.5.5 0 0 1-.708-.708L10.293 8 8.646 6.354a.5.5 0 0 1 0-.708zm-1.292 0a.5.5 0 0 0-.708 0l-2 2a.5.5 0 0 0 0 .708l2 2a.5.5 0 0 0 .708-.708L5.707 8l1.647-1.646a.5.5 0 0 0 0-.708z"/><path d="M3 0h10a2 2 0 0 1 2 2v12a2 2 0 0 1-2 2H3a2 2 0 0 1-2-2v-1h1v1a1 1 0 0 0 1 1h10a1 1 0 0 0 1-1V2a1 1 0 0 0-1-1H3a1 1 0 0 0-1 1v1H1V2a2 2 0 0 1 2-2z"/><path d="M1 5v-.5a.5.5 0 0 1 1 0V5h.5a.5.5 0 0 1 0 1h-2a.5.5 0 0 1 0-1H1zm0 3v-.5a.5.5 0 0 1 1 0V8h.5a.5.5 0 0 1 0 1h-2a.5.5 0 0 1 0-1H1zm0 3v-.5a.5.5 0 0 1 1 0v.5h.5a.5.5 0 0 1 0 1h-2a.5.5 0 0 1 0-1H1z"/></svg>');background-repeat:no-repeat;background-size:.75rem .75rem}.toc-actions i.bi,.quarto-code-links i.bi,.quarto-other-links i.bi,.quarto-alternate-notebooks i.bi,.quarto-alternate-formats i.bi{margin-right:.4em;font-size:.8rem}.quarto-other-links-text-target .quarto-code-links i.bi,.quarto-other-links-text-target .quarto-other-links i.bi{margin-right:.2em}.quarto-other-formats-text-target .quarto-alternate-formats i.bi{margin-right:.1em}.toc-actions i.bi.empty,.quarto-code-links i.bi.empty,.quarto-other-links i.bi.empty,.quarto-alternate-notebooks i.bi.empty,.quarto-alternate-formats i.bi.empty{padding-left:1em}.quarto-notebook h2,.quarto-notebook .h2{border-bottom:none}.quarto-notebook .cell-container{display:flex}.quarto-notebook .cell-container .cell{flex-grow:4}.quarto-notebook .cell-container .cell-decorator{padding-top:1.5em;padding-right:1em;text-align:right}.quarto-notebook .cell-container.code-fold .cell-decorator{padding-top:3em}.quarto-notebook .cell-code code{white-space:pre-wrap}.quarto-notebook .cell .cell-output-stderr pre code,.quarto-notebook .cell .cell-output-stdout pre code{white-space:pre-wrap;overflow-wrap:anywhere}.toc-actions,.quarto-alternate-formats,.quarto-other-links,.quarto-code-links,.quarto-alternate-notebooks{padding-left:0em}.sidebar .toc-actions a,.sidebar .quarto-alternate-formats a,.sidebar .quarto-other-links a,.sidebar .quarto-code-links a,.sidebar .quarto-alternate-notebooks a,.sidebar nav[role=doc-toc] a{text-decoration:none}.sidebar .toc-actions a:hover,.sidebar .quarto-other-links a:hover,.sidebar .quarto-code-links a:hover,.sidebar .quarto-alternate-formats a:hover,.sidebar .quarto-alternate-notebooks a:hover{color:#2761e3}.sidebar .toc-actions h2,.sidebar .toc-actions .h2,.sidebar .quarto-code-links h2,.sidebar .quarto-code-links .h2,.sidebar .quarto-other-links h2,.sidebar .quarto-other-links .h2,.sidebar .quarto-alternate-notebooks h2,.sidebar .quarto-alternate-notebooks .h2,.sidebar .quarto-alternate-formats h2,.sidebar .quarto-alternate-formats .h2,.sidebar nav[role=doc-toc]>h2,.sidebar nav[role=doc-toc]>.h2{font-weight:500;margin-bottom:.2rem;margin-top:.3rem;font-family:inherit;border-bottom:0;padding-bottom:0;padding-top:0px}.sidebar .toc-actions>h2,.sidebar .toc-actions>.h2,.sidebar .quarto-code-links>h2,.sidebar .quarto-code-links>.h2,.sidebar .quarto-other-links>h2,.sidebar .quarto-other-links>.h2,.sidebar .quarto-alternate-notebooks>h2,.sidebar .quarto-alternate-notebooks>.h2,.sidebar .quarto-alternate-formats>h2,.sidebar .quarto-alternate-formats>.h2{font-size:.8rem}.sidebar nav[role=doc-toc]>h2,.sidebar nav[role=doc-toc]>.h2{font-size:.875rem}.sidebar nav[role=doc-toc]>ul a{border-left:1px solid #e9ecef;padding-left:.6rem}.sidebar .toc-actions h2>ul a,.sidebar .toc-actions .h2>ul a,.sidebar .quarto-code-links h2>ul a,.sidebar .quarto-code-links .h2>ul a,.sidebar .quarto-other-links h2>ul a,.sidebar .quarto-other-links .h2>ul a,.sidebar .quarto-alternate-notebooks h2>ul a,.sidebar .quarto-alternate-notebooks .h2>ul a,.sidebar .quarto-alternate-formats h2>ul a,.sidebar .quarto-alternate-formats .h2>ul a{border-left:none;padding-left:.6rem}.sidebar .toc-actions ul a:empty,.sidebar .quarto-code-links ul a:empty,.sidebar .quarto-other-links ul a:empty,.sidebar .quarto-alternate-notebooks ul a:empty,.sidebar .quarto-alternate-formats ul a:empty,.sidebar nav[role=doc-toc]>ul a:empty{display:none}.sidebar .toc-actions ul,.sidebar .quarto-code-links ul,.sidebar .quarto-other-links ul,.sidebar .quarto-alternate-notebooks ul,.sidebar .quarto-alternate-formats ul{padding-left:0;list-style:none}.sidebar nav[role=doc-toc] ul{list-style:none;padding-left:0;list-style:none}.sidebar nav[role=doc-toc]>ul{margin-left:.45em}.quarto-margin-sidebar nav[role=doc-toc]{padding-left:.5em}.sidebar .toc-actions>ul,.sidebar .quarto-code-links>ul,.sidebar .quarto-other-links>ul,.sidebar .quarto-alternate-notebooks>ul,.sidebar .quarto-alternate-formats>ul{font-size:.8rem}.sidebar nav[role=doc-toc]>ul{font-size:.875rem}.sidebar .toc-actions ul li a,.sidebar .quarto-code-links ul li a,.sidebar .quarto-other-links ul li a,.sidebar .quarto-alternate-notebooks ul li a,.sidebar .quarto-alternate-formats ul li a,.sidebar nav[role=doc-toc]>ul li a{line-height:1.1rem;padding-bottom:.2rem;padding-top:.2rem;color:inherit}.sidebar nav[role=doc-toc] ul>li>ul>li>a{padding-left:1.2em}.sidebar nav[role=doc-toc] ul>li>ul>li>ul>li>a{padding-left:2.4em}.sidebar nav[role=doc-toc] ul>li>ul>li>ul>li>ul>li>a{padding-left:3.6em}.sidebar nav[role=doc-toc] ul>li>ul>li>ul>li>ul>li>ul>li>a{padding-left:4.8em}.sidebar nav[role=doc-toc] ul>li>ul>li>ul>li>ul>li>ul>li>ul>li>a{padding-left:6em}.sidebar nav[role=doc-toc] ul>li>a.active,.sidebar nav[role=doc-toc] ul>li>ul>li>a.active{border-left:1px solid #2761e3;color:#2761e3 !important}.sidebar nav[role=doc-toc] ul>li>a:hover,.sidebar nav[role=doc-toc] ul>li>ul>li>a:hover{color:#2761e3 !important}kbd,.kbd{color:#343a40;background-color:#f8f9fa;border:1px solid;border-radius:5px;border-color:#dee2e6}.quarto-appendix-contents div.hanging-indent{margin-left:0em}.quarto-appendix-contents div.hanging-indent div.csl-entry{margin-left:1em;text-indent:-1em}.citation a,.footnote-ref{text-decoration:none}.footnotes ol{padding-left:1em}.tippy-content>*{margin-bottom:.7em}.tippy-content>*:last-child{margin-bottom:0}.callout{margin-top:1.25rem;margin-bottom:1.25rem;border-radius:.25rem;overflow-wrap:break-word}.callout .callout-title-container{overflow-wrap:anywhere}.callout.callout-style-simple{padding:.4em .7em;border-left:5px solid;border-right:1px solid #dee2e6;border-top:1px solid #dee2e6;border-bottom:1px solid #dee2e6}.callout.callout-style-default{border-left:5px solid;border-right:1px solid #dee2e6;border-top:1px solid #dee2e6;border-bottom:1px solid #dee2e6}.callout .callout-body-container{flex-grow:1}.callout.callout-style-simple .callout-body{font-size:.9rem;font-weight:400}.callout.callout-style-default .callout-body{font-size:.9rem;font-weight:400}.callout:not(.no-icon).callout-titled.callout-style-simple .callout-body{padding-left:1.6em}.callout.callout-titled>.callout-header{padding-top:.2em;margin-bottom:-0.2em}.callout.callout-style-simple>div.callout-header{border-bottom:none;font-size:.9rem;font-weight:600;opacity:75%}.callout.callout-style-default>div.callout-header{border-bottom:none;font-weight:600;opacity:85%;font-size:.9rem;padding-left:.5em;padding-right:.5em}.callout.callout-style-default .callout-body{padding-left:.5em;padding-right:.5em}.callout.callout-style-default .callout-body>:first-child{padding-top:.5rem;margin-top:0}.callout>div.callout-header[data-bs-toggle=collapse]{cursor:pointer}.callout.callout-style-default .callout-header[aria-expanded=false],.callout.callout-style-default .callout-header[aria-expanded=true]{padding-top:0px;margin-bottom:0px;align-items:center}.callout.callout-titled .callout-body>:last-child:not(.sourceCode),.callout.callout-titled .callout-body>div>:last-child:not(.sourceCode){padding-bottom:.5rem;margin-bottom:0}.callout:not(.callout-titled) .callout-body>:first-child,.callout:not(.callout-titled) .callout-body>div>:first-child{margin-top:.25rem}.callout:not(.callout-titled) .callout-body>:last-child,.callout:not(.callout-titled) .callout-body>div>:last-child{margin-bottom:.2rem}.callout.callout-style-simple .callout-icon::before,.callout.callout-style-simple .callout-toggle::before{height:1rem;width:1rem;display:inline-block;content:"";background-repeat:no-repeat;background-size:1rem 1rem}.callout.callout-style-default .callout-icon::before,.callout.callout-style-default .callout-toggle::before{height:.9rem;width:.9rem;display:inline-block;content:"";background-repeat:no-repeat;background-size:.9rem .9rem}.callout.callout-style-default .callout-toggle::before{margin-top:5px}.callout .callout-btn-toggle .callout-toggle::before{transition:transform .2s linear}.callout .callout-header[aria-expanded=false] .callout-toggle::before{transform:rotate(-90deg)}.callout .callout-header[aria-expanded=true] .callout-toggle::before{transform:none}.callout.callout-style-simple:not(.no-icon) div.callout-icon-container{padding-top:.2em;padding-right:.55em}.callout.callout-style-default:not(.no-icon) div.callout-icon-container{padding-top:.1em;padding-right:.35em}.callout.callout-style-default:not(.no-icon) div.callout-title-container{margin-top:-1px}.callout.callout-style-default.callout-caution:not(.no-icon) div.callout-icon-container{padding-top:.3em;padding-right:.35em}.callout>.callout-body>.callout-icon-container>.no-icon,.callout>.callout-header>.callout-icon-container>.no-icon{display:none}div.callout.callout{border-left-color:#6c757d}div.callout.callout-style-default>.callout-header{background-color:#6c757d}div.callout-note.callout{border-left-color:#2780e3}div.callout-note.callout-style-default>.callout-header{background-color:#e9f2fc}div.callout-note:not(.callout-titled) .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %232373cc" class="bi bi-info-circle" viewBox="0 0 16 16"><path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z"/><path d="m8.93 6.588-2.29.287-.082.38.45.083c.294.07.352.176.288.469l-.738 3.468c-.194.897.105 1.319.808 1.319.545 0 1.178-.252 1.465-.598l.088-.416c-.2.176-.492.246-.686.246-.275 0-.375-.193-.304-.533L8.93 6.588zM9 4.5a1 1 0 1 1-2 0 1 1 0 0 1 2 0z"/></svg>');}div.callout-note.callout-titled .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %232373cc" class="bi bi-info-circle" viewBox="0 0 16 16"><path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z"/><path d="m8.93 6.588-2.29.287-.082.38.45.083c.294.07.352.176.288.469l-.738 3.468c-.194.897.105 1.319.808 1.319.545 0 1.178-.252 1.465-.598l.088-.416c-.2.176-.492.246-.686.246-.275 0-.375-.193-.304-.533L8.93 6.588zM9 4.5a1 1 0 1 1-2 0 1 1 0 0 1 2 0z"/></svg>');}div.callout-note .callout-toggle::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(52, 58, 64)" class="bi bi-chevron-down" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z"/></svg>')}div.callout-tip.callout{border-left-color:#3fb618}div.callout-tip.callout-style-default>.callout-header{background-color:#ecf8e8}div.callout-tip:not(.callout-titled) .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %2339a416" class="bi bi-lightbulb" viewBox="0 0 16 16"><path d="M2 6a6 6 0 1 1 10.174 4.31c-.203.196-.359.4-.453.619l-.762 1.769A.5.5 0 0 1 10.5 13a.5.5 0 0 1 0 1 .5.5 0 0 1 0 1l-.224.447a1 1 0 0 1-.894.553H6.618a1 1 0 0 1-.894-.553L5.5 15a.5.5 0 0 1 0-1 .5.5 0 0 1 0-1 .5.5 0 0 1-.46-.302l-.761-1.77a1.964 1.964 0 0 0-.453-.618A5.984 5.984 0 0 1 2 6zm6-5a5 5 0 0 0-3.479 8.592c.263.254.514.564.676.941L5.83 12h4.342l.632-1.467c.162-.377.413-.687.676-.941A5 5 0 0 0 8 1z"/></svg>');}div.callout-tip.callout-titled .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %2339a416" class="bi bi-lightbulb" viewBox="0 0 16 16"><path d="M2 6a6 6 0 1 1 10.174 4.31c-.203.196-.359.4-.453.619l-.762 1.769A.5.5 0 0 1 10.5 13a.5.5 0 0 1 0 1 .5.5 0 0 1 0 1l-.224.447a1 1 0 0 1-.894.553H6.618a1 1 0 0 1-.894-.553L5.5 15a.5.5 0 0 1 0-1 .5.5 0 0 1 0-1 .5.5 0 0 1-.46-.302l-.761-1.77a1.964 1.964 0 0 0-.453-.618A5.984 5.984 0 0 1 2 6zm6-5a5 5 0 0 0-3.479 8.592c.263.254.514.564.676.941L5.83 12h4.342l.632-1.467c.162-.377.413-.687.676-.941A5 5 0 0 0 8 1z"/></svg>');}div.callout-tip .callout-toggle::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(52, 58, 64)" class="bi bi-chevron-down" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z"/></svg>')}div.callout-warning.callout{border-left-color:#ff7518}div.callout-warning.callout-style-default>.callout-header{background-color:#fff1e8}div.callout-warning:not(.callout-titled) .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %23e66916" class="bi bi-exclamation-triangle" viewBox="0 0 16 16"><path d="M7.938 2.016A.13.13 0 0 1 8.002 2a.13.13 0 0 1 .063.016.146.146 0 0 1 .054.057l6.857 11.667c.036.06.035.124.002.183a.163.163 0 0 1-.054.06.116.116 0 0 1-.066.017H1.146a.115.115 0 0 1-.066-.017.163.163 0 0 1-.054-.06.176.176 0 0 1 .002-.183L7.884 2.073a.147.147 0 0 1 .054-.057zm1.044-.45a1.13 1.13 0 0 0-1.96 0L.165 13.233c-.457.778.091 1.767.98 1.767h13.713c.889 0 1.438-.99.98-1.767L8.982 1.566z"/><path d="M7.002 12a1 1 0 1 1 2 0 1 1 0 0 1-2 0zM7.1 5.995a.905.905 0 1 1 1.8 0l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 5.995z"/></svg>');}div.callout-warning.callout-titled .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %23e66916" class="bi bi-exclamation-triangle" viewBox="0 0 16 16"><path d="M7.938 2.016A.13.13 0 0 1 8.002 2a.13.13 0 0 1 .063.016.146.146 0 0 1 .054.057l6.857 11.667c.036.06.035.124.002.183a.163.163 0 0 1-.054.06.116.116 0 0 1-.066.017H1.146a.115.115 0 0 1-.066-.017.163.163 0 0 1-.054-.06.176.176 0 0 1 .002-.183L7.884 2.073a.147.147 0 0 1 .054-.057zm1.044-.45a1.13 1.13 0 0 0-1.96 0L.165 13.233c-.457.778.091 1.767.98 1.767h13.713c.889 0 1.438-.99.98-1.767L8.982 1.566z"/><path d="M7.002 12a1 1 0 1 1 2 0 1 1 0 0 1-2 0zM7.1 5.995a.905.905 0 1 1 1.8 0l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 5.995z"/></svg>');}div.callout-warning .callout-toggle::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(52, 58, 64)" class="bi bi-chevron-down" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z"/></svg>')}div.callout-caution.callout{border-left-color:#f0ad4e}div.callout-caution.callout-style-default>.callout-header{background-color:#fef7ed}div.callout-caution:not(.callout-titled) .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %23d89c46" class="bi bi-cone-striped" viewBox="0 0 16 16"><path d="M9.97 4.88l.953 3.811C10.158 8.878 9.14 9 8 9c-1.14 0-2.159-.122-2.923-.309L6.03 4.88C6.635 4.957 7.3 5 8 5s1.365-.043 1.97-.12zm-.245-.978L8.97.88C8.718-.13 7.282-.13 7.03.88L6.274 3.9C6.8 3.965 7.382 4 8 4c.618 0 1.2-.036 1.725-.098zm4.396 8.613a.5.5 0 0 1 .037.96l-6 2a.5.5 0 0 1-.316 0l-6-2a.5.5 0 0 1 .037-.96l2.391-.598.565-2.257c.862.212 1.964.339 3.165.339s2.303-.127 3.165-.339l.565 2.257 2.391.598z"/></svg>');}div.callout-caution.callout-titled .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %23d89c46" class="bi bi-cone-striped" viewBox="0 0 16 16"><path d="M9.97 4.88l.953 3.811C10.158 8.878 9.14 9 8 9c-1.14 0-2.159-.122-2.923-.309L6.03 4.88C6.635 4.957 7.3 5 8 5s1.365-.043 1.97-.12zm-.245-.978L8.97.88C8.718-.13 7.282-.13 7.03.88L6.274 3.9C6.8 3.965 7.382 4 8 4c.618 0 1.2-.036 1.725-.098zm4.396 8.613a.5.5 0 0 1 .037.96l-6 2a.5.5 0 0 1-.316 0l-6-2a.5.5 0 0 1 .037-.96l2.391-.598.565-2.257c.862.212 1.964.339 3.165.339s2.303-.127 3.165-.339l.565 2.257 2.391.598z"/></svg>');}div.callout-caution .callout-toggle::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(52, 58, 64)" class="bi bi-chevron-down" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z"/></svg>')}div.callout-important.callout{border-left-color:#ff0039}div.callout-important.callout-style-default>.callout-header{background-color:#ffe6eb}div.callout-important:not(.callout-titled) .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %23e60033" class="bi bi-exclamation-circle" viewBox="0 0 16 16"><path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z"/><path d="M7.002 11a1 1 0 1 1 2 0 1 1 0 0 1-2 0zM7.1 4.995a.905.905 0 1 1 1.8 0l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 4.995z"/></svg>');}div.callout-important.callout-titled .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %23e60033" class="bi bi-exclamation-circle" viewBox="0 0 16 16"><path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z"/><path d="M7.002 11a1 1 0 1 1 2 0 1 1 0 0 1-2 0zM7.1 4.995a.905.905 0 1 1 1.8 0l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 4.995z"/></svg>');}div.callout-important .callout-toggle::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(52, 58, 64)" class="bi bi-chevron-down" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z"/></svg>')}.quarto-toggle-container{display:flex;align-items:center}.quarto-reader-toggle .bi::before,.quarto-color-scheme-toggle .bi::before{display:inline-block;height:1rem;width:1rem;content:"";background-repeat:no-repeat;background-size:1rem 1rem}.sidebar-navigation{padding-left:20px}.navbar{background-color:#f8f9fa;color:#545555}.navbar .quarto-color-scheme-toggle:not(.alternate) .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(84, 85, 85, 1)" class="bi bi-toggle-off" viewBox="0 0 16 16"><path d="M11 4a4 4 0 0 1 0 8H8a4.992 4.992 0 0 0 2-4 4.992 4.992 0 0 0-2-4h3zm-6 8a4 4 0 1 1 0-8 4 4 0 0 1 0 8zM0 8a5 5 0 0 0 5 5h6a5 5 0 0 0 0-10H5a5 5 0 0 0-5 5z"/></svg>')}.navbar .quarto-color-scheme-toggle.alternate .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(84, 85, 85, 1)" class="bi bi-toggle-on" viewBox="0 0 16 16"><path d="M5 3a5 5 0 0 0 0 10h6a5 5 0 0 0 0-10H5zm6 9a4 4 0 1 1 0-8 4 4 0 0 1 0 8z"/></svg>')}.sidebar-navigation .quarto-color-scheme-toggle:not(.alternate) .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(75, 84, 92, 1)" class="bi bi-toggle-off" viewBox="0 0 16 16"><path d="M11 4a4 4 0 0 1 0 8H8a4.992 4.992 0 0 0 2-4 4.992 4.992 0 0 0-2-4h3zm-6 8a4 4 0 1 1 0-8 4 4 0 0 1 0 8zM0 8a5 5 0 0 0 5 5h6a5 5 0 0 0 0-10H5a5 5 0 0 0-5 5z"/></svg>')}.sidebar-navigation .quarto-color-scheme-toggle.alternate .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(75, 84, 92, 1)" class="bi bi-toggle-on" viewBox="0 0 16 16"><path d="M5 3a5 5 0 0 0 0 10h6a5 5 0 0 0 0-10H5zm6 9a4 4 0 1 1 0-8 4 4 0 0 1 0 8z"/></svg>')}.quarto-sidebar-toggle{border-color:#dee2e6;border-bottom-left-radius:.25rem;border-bottom-right-radius:.25rem;border-style:solid;border-width:1px;overflow:hidden;border-top-width:0px;padding-top:0px !important}.quarto-sidebar-toggle-title{cursor:pointer;padding-bottom:2px;margin-left:.25em;text-align:center;font-weight:400;font-size:.775em}#quarto-content .quarto-sidebar-toggle{background:#fafafa}#quarto-content .quarto-sidebar-toggle-title{color:#343a40}.quarto-sidebar-toggle-icon{color:#dee2e6;margin-right:.5em;float:right;transition:transform .2s ease}.quarto-sidebar-toggle-icon::before{padding-top:5px}.quarto-sidebar-toggle.expanded .quarto-sidebar-toggle-icon{transform:rotate(-180deg)}.quarto-sidebar-toggle.expanded .quarto-sidebar-toggle-title{border-bottom:solid #dee2e6 1px}.quarto-sidebar-toggle-contents{background-color:#fff;padding-right:10px;padding-left:10px;margin-top:0px !important;transition:max-height .5s ease}.quarto-sidebar-toggle.expanded .quarto-sidebar-toggle-contents{padding-top:1em;padding-bottom:10px}@media(max-width: 767.98px){.sidebar-menu-container{padding-bottom:5em}}.quarto-sidebar-toggle:not(.expanded) .quarto-sidebar-toggle-contents{padding-top:0px !important;padding-bottom:0px}nav[role=doc-toc]{z-index:1020}#quarto-sidebar>*,nav[role=doc-toc]>*{transition:opacity .1s ease,border .1s ease}#quarto-sidebar.slow>*,nav[role=doc-toc].slow>*{transition:opacity .4s ease,border .4s ease}.quarto-color-scheme-toggle:not(.alternate).top-right .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(136, 147, 158, 1)" class="bi bi-toggle-off" viewBox="0 0 16 16"><path d="M11 4a4 4 0 0 1 0 8H8a4.992 4.992 0 0 0 2-4 4.992 4.992 0 0 0-2-4h3zm-6 8a4 4 0 1 1 0-8 4 4 0 0 1 0 8zM0 8a5 5 0 0 0 5 5h6a5 5 0 0 0 0-10H5a5 5 0 0 0-5 5z"/></svg>')}.quarto-color-scheme-toggle.alternate.top-right .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(98, 109, 120, 1)" class="bi bi-toggle-on" viewBox="0 0 16 16"><path d="M5 3a5 5 0 0 0 0 10h6a5 5 0 0 0 0-10H5zm6 9a4 4 0 1 1 0-8 4 4 0 0 1 0 8z"/></svg>')}#quarto-appendix.default{border-top:1px solid #dee2e6}#quarto-appendix.default{background-color:#fff;padding-top:1.5em;margin-top:2em;z-index:998}#quarto-appendix.default .quarto-appendix-heading{margin-top:0;line-height:1.4em;font-weight:600;opacity:.9;border-bottom:none;margin-bottom:0}#quarto-appendix.default .footnotes ol,#quarto-appendix.default .footnotes ol li>p:last-of-type,#quarto-appendix.default .quarto-appendix-contents>p:last-of-type{margin-bottom:0}#quarto-appendix.default .footnotes ol{margin-left:.5em}#quarto-appendix.default .quarto-appendix-secondary-label{margin-bottom:.4em}#quarto-appendix.default .quarto-appendix-bibtex{font-size:.7em;padding:1em;border:solid 1px #dee2e6;margin-bottom:1em}#quarto-appendix.default .quarto-appendix-bibtex code.sourceCode{white-space:pre-wrap}#quarto-appendix.default .quarto-appendix-citeas{font-size:.9em;padding:1em;border:solid 1px #dee2e6;margin-bottom:1em}#quarto-appendix.default .quarto-appendix-heading{font-size:1em !important}#quarto-appendix.default *[role=doc-endnotes]>ol,#quarto-appendix.default .quarto-appendix-contents>*:not(h2):not(.h2){font-size:.9em}#quarto-appendix.default section{padding-bottom:1.5em}#quarto-appendix.default section *[role=doc-endnotes],#quarto-appendix.default section>*:not(a){opacity:.9;word-wrap:break-word}.btn.btn-quarto,div.cell-output-display .btn-quarto{--bs-btn-color: #cacccd;--bs-btn-bg: #343a40;--bs-btn-border-color: #343a40;--bs-btn-hover-color: #cacccd;--bs-btn-hover-bg: #52585d;--bs-btn-hover-border-color: #484e53;--bs-btn-focus-shadow-rgb: 75, 80, 85;--bs-btn-active-color: #fff;--bs-btn-active-bg: #5d6166;--bs-btn-active-border-color: #484e53;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #343a40;--bs-btn-disabled-border-color: #343a40}nav.quarto-secondary-nav.color-navbar{background-color:#f8f9fa;color:#545555}nav.quarto-secondary-nav.color-navbar h1,nav.quarto-secondary-nav.color-navbar .h1,nav.quarto-secondary-nav.color-navbar .quarto-btn-toggle{color:#545555}@media(max-width: 991.98px){body.nav-sidebar .quarto-title-banner{margin-bottom:0;padding-bottom:1em}body.nav-sidebar #title-block-header{margin-block-end:0}}p.subtitle{margin-top:.25em;margin-bottom:.5em}code a:any-link{color:inherit;text-decoration-color:#6c757d}/*! light */div.observablehq table thead tr th{background-color:var(--bs-body-bg)}input,button,select,optgroup,textarea{background-color:var(--bs-body-bg)}.code-annotated .code-copy-button{margin-right:1.25em;margin-top:0;padding-bottom:0;padding-top:3px}.code-annotation-gutter-bg{background-color:#fff}.code-annotation-gutter{background-color:rgba(233,236,239,.65)}.code-annotation-gutter,.code-annotation-gutter-bg{height:100%;width:calc(20px + .5em);position:absolute;top:0;right:0}dl.code-annotation-container-grid dt{margin-right:1em;margin-top:.25rem}dl.code-annotation-container-grid dt{font-family:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace;color:#4b545c;border:solid #4b545c 1px;border-radius:50%;height:22px;width:22px;line-height:22px;font-size:11px;text-align:center;vertical-align:middle;text-decoration:none}dl.code-annotation-container-grid dt[data-target-cell]{cursor:pointer}dl.code-annotation-container-grid dt[data-target-cell].code-annotation-active{color:#fff;border:solid #aaa 1px;background-color:#aaa}pre.code-annotation-code{padding-top:0;padding-bottom:0}pre.code-annotation-code code{z-index:3}#code-annotation-line-highlight-gutter{width:100%;border-top:solid rgba(170,170,170,.2666666667) 1px;border-bottom:solid rgba(170,170,170,.2666666667) 1px;z-index:2;background-color:rgba(170,170,170,.1333333333)}#code-annotation-line-highlight{margin-left:-4em;width:calc(100% + 4em);border-top:solid rgba(170,170,170,.2666666667) 1px;border-bottom:solid rgba(170,170,170,.2666666667) 1px;z-index:2;background-color:rgba(170,170,170,.1333333333)}code.sourceCode .code-annotation-anchor.code-annotation-active{background-color:var(--quarto-hl-normal-color, #aaaaaa);border:solid var(--quarto-hl-normal-color, #aaaaaa) 1px;color:#e9ecef;font-weight:bolder}code.sourceCode .code-annotation-anchor{font-family:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace;color:var(--quarto-hl-co-color);border:solid var(--quarto-hl-co-color) 1px;border-radius:50%;height:18px;width:18px;font-size:9px;margin-top:2px}code.sourceCode button.code-annotation-anchor{padding:2px;user-select:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;-o-user-select:none}code.sourceCode a.code-annotation-anchor{line-height:18px;text-align:center;vertical-align:middle;cursor:default;text-decoration:none}@media print{.page-columns .column-screen-inset{grid-column:page-start-inset/page-end-inset;z-index:998;opacity:.999}.page-columns .column-screen-inset table{background:#fff}.page-columns .column-screen-inset-left{grid-column:page-start-inset/body-content-end;z-index:998;opacity:.999}.page-columns .column-screen-inset-left table{background:#fff}.page-columns .column-screen-inset-right{grid-column:body-content-start/page-end-inset;z-index:998;opacity:.999}.page-columns .column-screen-inset-right table{background:#fff}.page-columns .column-screen{grid-column:page-start/page-end;z-index:998;opacity:.999}.page-columns .column-screen table{background:#fff}.page-columns .column-screen-left{grid-column:page-start/body-content-end;z-index:998;opacity:.999}.page-columns .column-screen-left table{background:#fff}.page-columns .column-screen-right{grid-column:body-content-start/page-end;z-index:998;opacity:.999}.page-columns .column-screen-right table{background:#fff}.page-columns .column-screen-inset-shaded{grid-column:page-start-inset/page-end-inset;padding:1em;background:#f8f9fa;z-index:998;opacity:.999;margin-bottom:1em}}.quarto-video{margin-bottom:1em}.table{border-top:1px solid #ebedee;border-bottom:1px solid #ebedee}.table>thead{border-top-width:0;border-bottom:1px solid #b2bac1}.table a{word-break:break-word}.table>:not(caption)>*>*{background-color:unset;color:unset}#quarto-document-content .crosstalk-input .checkbox input[type=checkbox],#quarto-document-content .crosstalk-input .checkbox-inline input[type=checkbox]{position:unset;margin-top:unset;margin-left:unset}#quarto-document-content .row{margin-left:unset;margin-right:unset}.quarto-xref{white-space:nowrap}#quarto-draft-alert{margin-top:0px;margin-bottom:0px;padding:.3em;text-align:center;font-size:.9em}#quarto-draft-alert i{margin-right:.3em}a.external:after{content:"";background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(39, 97, 227)" class="bi bi-box-arrow-up-right" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8.636 3.5a.5.5 0 0 0-.5-.5H1.5A1.5 1.5 0 0 0 0 4.5v10A1.5 1.5 0 0 0 1.5 16h10a1.5 1.5 0 0 0 1.5-1.5V7.864a.5.5 0 0 0-1 0V14.5a.5.5 0 0 1-.5.5h-10a.5.5 0 0 1-.5-.5v-10a.5.5 0 0 1 .5-.5h6.636a.5.5 0 0 0 .5-.5z"/><path fill-rule="evenodd" d="M16 .5a.5.5 0 0 0-.5-.5h-5a.5.5 0 0 0 0 1h3.793L6.146 9.146a.5.5 0 1 0 .708.708L15 1.707V5.5a.5.5 0 0 0 1 0v-5z"/></svg>');background-size:contain;background-repeat:no-repeat;background-position:center center;margin-left:.2em;padding-right:.75em}div.sourceCode code a.external:after{content:none}a.external:after:hover{cursor:pointer}.quarto-ext-icon{display:inline-block;font-size:.75em;padding-left:.3em}.code-with-filename .code-with-filename-file{margin-bottom:0;padding-bottom:2px;padding-top:2px;padding-left:.7em;border:var(--quarto-border-width) solid var(--quarto-border-color);border-radius:var(--quarto-border-radius);border-bottom:0;border-bottom-left-radius:0%;border-bottom-right-radius:0%}.code-with-filename div.sourceCode,.reveal .code-with-filename div.sourceCode{margin-top:0;border-top-left-radius:0%;border-top-right-radius:0%}.code-with-filename .code-with-filename-file pre{margin-bottom:0}.code-with-filename .code-with-filename-file{background-color:rgba(219,219,219,.8)}.quarto-dark .code-with-filename .code-with-filename-file{background-color:#555}.code-with-filename .code-with-filename-file strong{font-weight:400}.quarto-title-banner{margin-bottom:1em;color:#545555;background:#f8f9fa}.quarto-title-banner a{color:#545555}.quarto-title-banner h1,.quarto-title-banner .h1,.quarto-title-banner h2,.quarto-title-banner .h2{color:#545555}.quarto-title-banner .code-tools-button{color:#878888}.quarto-title-banner .code-tools-button:hover{color:#545555}.quarto-title-banner .code-tools-button>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(135, 136, 136)" viewBox="0 0 16 16"><path d="M10.478 1.647a.5.5 0 1 0-.956-.294l-4 13a.5.5 0 0 0 .956.294l4-13zM4.854 4.146a.5.5 0 0 1 0 .708L1.707 8l3.147 3.146a.5.5 0 0 1-.708.708l-3.5-3.5a.5.5 0 0 1 0-.708l3.5-3.5a.5.5 0 0 1 .708 0zm6.292 0a.5.5 0 0 0 0 .708L14.293 8l-3.147 3.146a.5.5 0 0 0 .708.708l3.5-3.5a.5.5 0 0 0 0-.708l-3.5-3.5a.5.5 0 0 0-.708 0z"/></svg>')}.quarto-title-banner .code-tools-button:hover>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(84, 85, 85)" viewBox="0 0 16 16"><path d="M10.478 1.647a.5.5 0 1 0-.956-.294l-4 13a.5.5 0 0 0 .956.294l4-13zM4.854 4.146a.5.5 0 0 1 0 .708L1.707 8l3.147 3.146a.5.5 0 0 1-.708.708l-3.5-3.5a.5.5 0 0 1 0-.708l3.5-3.5a.5.5 0 0 1 .708 0zm6.292 0a.5.5 0 0 0 0 .708L14.293 8l-3.147 3.146a.5.5 0 0 0 .708.708l3.5-3.5a.5.5 0 0 0 0-.708l-3.5-3.5a.5.5 0 0 0-.708 0z"/></svg>')}.quarto-title-banner .quarto-title .title{font-weight:600}.quarto-title-banner .quarto-categories{margin-top:.75em}@media(min-width: 992px){.quarto-title-banner{padding-top:2.5em;padding-bottom:2.5em}}@media(max-width: 991.98px){.quarto-title-banner{padding-top:1em;padding-bottom:1em}}@media(max-width: 767.98px){body.hypothesis-enabled #title-block-header>*{padding-right:20px}}main.quarto-banner-title-block>section:first-child>h2,main.quarto-banner-title-block>section:first-child>.h2,main.quarto-banner-title-block>section:first-child>h3,main.quarto-banner-title-block>section:first-child>.h3,main.quarto-banner-title-block>section:first-child>h4,main.quarto-banner-title-block>section:first-child>.h4{margin-top:0}.quarto-title .quarto-categories{display:flex;flex-wrap:wrap;row-gap:.5em;column-gap:.4em;padding-bottom:.5em;margin-top:.75em}.quarto-title .quarto-categories .quarto-category{padding:.25em .75em;font-size:.65em;text-transform:uppercase;border:solid 1px;border-radius:.25rem;opacity:.6}.quarto-title .quarto-categories .quarto-category a{color:inherit}.quarto-title-meta-container{display:grid;grid-template-columns:1fr auto}.quarto-title-meta-column-end{display:flex;flex-direction:column;padding-left:1em}.quarto-title-meta-column-end a .bi{margin-right:.3em}#title-block-header.quarto-title-block.default .quarto-title-meta{display:grid;grid-template-columns:repeat(2, 1fr);grid-column-gap:1em}#title-block-header.quarto-title-block.default .quarto-title .title{margin-bottom:0}#title-block-header.quarto-title-block.default .quarto-title-author-orcid img{margin-top:-0.2em;height:.8em;width:.8em}#title-block-header.quarto-title-block.default .quarto-title-author-email{opacity:.7}#title-block-header.quarto-title-block.default .quarto-description p:last-of-type{margin-bottom:0}#title-block-header.quarto-title-block.default .quarto-title-meta-contents p,#title-block-header.quarto-title-block.default .quarto-title-authors p,#title-block-header.quarto-title-block.default .quarto-title-affiliations p{margin-bottom:.1em}#title-block-header.quarto-title-block.default .quarto-title-meta-heading{text-transform:uppercase;margin-top:1em;font-size:.8em;opacity:.8;font-weight:400}#title-block-header.quarto-title-block.default .quarto-title-meta-contents{font-size:.9em}#title-block-header.quarto-title-block.default .quarto-title-meta-contents p.affiliation:last-of-type{margin-bottom:.1em}#title-block-header.quarto-title-block.default p.affiliation{margin-bottom:.1em}#title-block-header.quarto-title-block.default .keywords,#title-block-header.quarto-title-block.default .description,#title-block-header.quarto-title-block.default .abstract{margin-top:0}#title-block-header.quarto-title-block.default .keywords>p,#title-block-header.quarto-title-block.default .description>p,#title-block-header.quarto-title-block.default .abstract>p{font-size:.9em}#title-block-header.quarto-title-block.default .keywords>p:last-of-type,#title-block-header.quarto-title-block.default .description>p:last-of-type,#title-block-header.quarto-title-block.default .abstract>p:last-of-type{margin-bottom:0}#title-block-header.quarto-title-block.default .keywords .block-title,#title-block-header.quarto-title-block.default .description .block-title,#title-block-header.quarto-title-block.default .abstract .block-title{margin-top:1em;text-transform:uppercase;font-size:.8em;opacity:.8;font-weight:400}#title-block-header.quarto-title-block.default .quarto-title-meta-author{display:grid;grid-template-columns:minmax(max-content, 1fr) 1fr;grid-column-gap:1em}.quarto-title-tools-only{display:flex;justify-content:right}body{-webkit-font-smoothing:antialiased}.badge.bg-light{color:#343a40}.progress .progress-bar{font-size:8px;line-height:8px}
+*/.ansi-black-fg{color:#3e424d}.ansi-black-bg{background-color:#3e424d}.ansi-black-intense-black,.ansi-bright-black-fg{color:#282c36}.ansi-black-intense-black,.ansi-bright-black-bg{background-color:#282c36}.ansi-red-fg{color:#e75c58}.ansi-red-bg{background-color:#e75c58}.ansi-red-intense-red,.ansi-bright-red-fg{color:#b22b31}.ansi-red-intense-red,.ansi-bright-red-bg{background-color:#b22b31}.ansi-green-fg{color:#00a250}.ansi-green-bg{background-color:#00a250}.ansi-green-intense-green,.ansi-bright-green-fg{color:#007427}.ansi-green-intense-green,.ansi-bright-green-bg{background-color:#007427}.ansi-yellow-fg{color:#ddb62b}.ansi-yellow-bg{background-color:#ddb62b}.ansi-yellow-intense-yellow,.ansi-bright-yellow-fg{color:#b27d12}.ansi-yellow-intense-yellow,.ansi-bright-yellow-bg{background-color:#b27d12}.ansi-blue-fg{color:#208ffb}.ansi-blue-bg{background-color:#208ffb}.ansi-blue-intense-blue,.ansi-bright-blue-fg{color:#0065ca}.ansi-blue-intense-blue,.ansi-bright-blue-bg{background-color:#0065ca}.ansi-magenta-fg{color:#d160c4}.ansi-magenta-bg{background-color:#d160c4}.ansi-magenta-intense-magenta,.ansi-bright-magenta-fg{color:#a03196}.ansi-magenta-intense-magenta,.ansi-bright-magenta-bg{background-color:#a03196}.ansi-cyan-fg{color:#60c6c8}.ansi-cyan-bg{background-color:#60c6c8}.ansi-cyan-intense-cyan,.ansi-bright-cyan-fg{color:#258f8f}.ansi-cyan-intense-cyan,.ansi-bright-cyan-bg{background-color:#258f8f}.ansi-white-fg{color:#c5c1b4}.ansi-white-bg{background-color:#c5c1b4}.ansi-white-intense-white,.ansi-bright-white-fg{color:#a1a6b2}.ansi-white-intense-white,.ansi-bright-white-bg{background-color:#a1a6b2}.ansi-default-inverse-fg{color:#fff}.ansi-default-inverse-bg{background-color:#000}.ansi-bold{font-weight:bold}.ansi-underline{text-decoration:underline}:root{--quarto-body-bg: #fff;--quarto-body-color: #343a40;--quarto-text-muted: #6c757d;--quarto-border-color: #dee2e6;--quarto-border-width: 1px;--quarto-border-radius: 0.25rem}table.gt_table{color:var(--quarto-body-color);font-size:1em;width:100%;background-color:rgba(0,0,0,0);border-top-width:inherit;border-bottom-width:inherit;border-color:var(--quarto-border-color)}table.gt_table th.gt_column_spanner_outer{color:var(--quarto-body-color);background-color:rgba(0,0,0,0);border-top-width:inherit;border-bottom-width:inherit;border-color:var(--quarto-border-color)}table.gt_table th.gt_col_heading{color:var(--quarto-body-color);font-weight:bold;background-color:rgba(0,0,0,0)}table.gt_table thead.gt_col_headings{border-bottom:1px solid currentColor;border-top-width:inherit;border-top-color:var(--quarto-border-color)}table.gt_table thead.gt_col_headings:not(:first-child){border-top-width:1px;border-top-color:var(--quarto-border-color)}table.gt_table td.gt_row{border-bottom-width:1px;border-bottom-color:var(--quarto-border-color);border-top-width:0px}table.gt_table tbody.gt_table_body{border-top-width:1px;border-bottom-width:1px;border-bottom-color:var(--quarto-border-color);border-top-color:currentColor}div.columns{display:initial;gap:initial}div.column{display:inline-block;overflow-x:initial;vertical-align:top;width:50%}.code-annotation-tip-content{word-wrap:break-word}.code-annotation-container-hidden{display:none !important}dl.code-annotation-container-grid{display:grid;grid-template-columns:min-content auto}dl.code-annotation-container-grid dt{grid-column:1}dl.code-annotation-container-grid dd{grid-column:2}pre.sourceCode.code-annotation-code{padding-right:0}code.sourceCode .code-annotation-anchor{z-index:100;position:relative;float:right;background-color:rgba(0,0,0,0)}input[type=checkbox]{margin-right:.5ch}:root{--mermaid-bg-color: #fff;--mermaid-edge-color: #343a40;--mermaid-node-fg-color: #343a40;--mermaid-fg-color: #343a40;--mermaid-fg-color--lighter: #4b545c;--mermaid-fg-color--lightest: #626d78;--mermaid-font-family: Source Sans Pro, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica Neue, Arial, sans-serif, Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol;--mermaid-label-bg-color: #fff;--mermaid-label-fg-color: #2780e3;--mermaid-node-bg-color: rgba(39, 128, 227, 0.1);--mermaid-node-fg-color: #343a40}@media print{:root{font-size:11pt}#quarto-sidebar,#TOC,.nav-page{display:none}.page-columns .content{grid-column-start:page-start}.fixed-top{position:relative}.panel-caption,.figure-caption,figcaption{color:#666}}.code-copy-button{position:absolute;top:0;right:0;border:0;margin-top:5px;margin-right:5px;background-color:rgba(0,0,0,0);z-index:3}.code-copy-button:focus{outline:none}.code-copy-button-tooltip{font-size:.75em}pre.sourceCode:hover>.code-copy-button>.bi::before{display:inline-block;height:1rem;width:1rem;content:"";vertical-align:-0.125em;background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(106, 115, 125)" viewBox="0 0 16 16"><path d="M4 1.5H3a2 2 0 0 0-2 2V14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V3.5a2 2 0 0 0-2-2h-1v1h1a1 1 0 0 1 1 1V14a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V3.5a1 1 0 0 1 1-1h1v-1z"/><path d="M9.5 1a.5.5 0 0 1 .5.5v1a.5.5 0 0 1-.5.5h-3a.5.5 0 0 1-.5-.5v-1a.5.5 0 0 1 .5-.5h3zm-3-1A1.5 1.5 0 0 0 5 1.5v1A1.5 1.5 0 0 0 6.5 4h3A1.5 1.5 0 0 0 11 2.5v-1A1.5 1.5 0 0 0 9.5 0h-3z"/></svg>');background-repeat:no-repeat;background-size:1rem 1rem}pre.sourceCode:hover>.code-copy-button-checked>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(106, 115, 125)" viewBox="0 0 16 16"><path d="M13.854 3.646a.5.5 0 0 1 0 .708l-7 7a.5.5 0 0 1-.708 0l-3.5-3.5a.5.5 0 1 1 .708-.708L6.5 10.293l6.646-6.647a.5.5 0 0 1 .708 0z"/></svg>')}pre.sourceCode:hover>.code-copy-button:hover>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(111, 66, 193)" viewBox="0 0 16 16"><path d="M4 1.5H3a2 2 0 0 0-2 2V14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V3.5a2 2 0 0 0-2-2h-1v1h1a1 1 0 0 1 1 1V14a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V3.5a1 1 0 0 1 1-1h1v-1z"/><path d="M9.5 1a.5.5 0 0 1 .5.5v1a.5.5 0 0 1-.5.5h-3a.5.5 0 0 1-.5-.5v-1a.5.5 0 0 1 .5-.5h3zm-3-1A1.5 1.5 0 0 0 5 1.5v1A1.5 1.5 0 0 0 6.5 4h3A1.5 1.5 0 0 0 11 2.5v-1A1.5 1.5 0 0 0 9.5 0h-3z"/></svg>')}pre.sourceCode:hover>.code-copy-button-checked:hover>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(111, 66, 193)"  viewBox="0 0 16 16"><path d="M13.854 3.646a.5.5 0 0 1 0 .708l-7 7a.5.5 0 0 1-.708 0l-3.5-3.5a.5.5 0 1 1 .708-.708L6.5 10.293l6.646-6.647a.5.5 0 0 1 .708 0z"/></svg>')}main ol ol,main ul ul,main ol ul,main ul ol{margin-bottom:1em}ul>li:not(:has(>p))>ul,ol>li:not(:has(>p))>ul,ul>li:not(:has(>p))>ol,ol>li:not(:has(>p))>ol{margin-bottom:0}ul>li:not(:has(>p))>ul>li:has(>p),ol>li:not(:has(>p))>ul>li:has(>p),ul>li:not(:has(>p))>ol>li:has(>p),ol>li:not(:has(>p))>ol>li:has(>p){margin-top:1rem}body{margin:0}main.page-columns>header>h1.title,main.page-columns>header>.title.h1{margin-bottom:0}@media(min-width: 992px){body .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start page-start-inset] 35px [body-start-outset] 35px [body-start] 1.5em [body-content-start] minmax(500px, calc(850px - 3em)) [body-content-end] 1.5em [body-end] 35px [body-end-outset] minmax(75px, 145px) [page-end-inset] 35px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.fullcontent:not(.floating):not(.docked) .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start page-start-inset] 35px [body-start-outset] 35px [body-start] 1.5em [body-content-start] minmax(500px, calc(850px - 3em)) [body-content-end] 1.5em [body-end] 35px [body-end-outset] 35px [page-end-inset page-end] 5fr [screen-end-inset] 1.5em}body.slimcontent:not(.floating):not(.docked) .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start page-start-inset] 35px [body-start-outset] 35px [body-start] 1.5em [body-content-start] minmax(500px, calc(850px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(0px, 200px) [page-end-inset] 35px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.listing:not(.floating):not(.docked) .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start] minmax(50px, 100px) [page-start-inset] 50px [body-start-outset] 50px [body-start] 1.5em [body-content-start] minmax(500px, calc(850px - 3em)) [body-content-end] 3em [body-end] 50px [body-end-outset] minmax(0px, 250px) [page-end-inset] minmax(50px, 100px) [page-end] 1fr [screen-end-inset] 1.5em [screen-end]}body:not(.floating):not(.docked) .page-columns.toc-left{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] 35px [page-start-inset] minmax(0px, 175px) [body-start-outset] 35px [body-start] 1.5em [body-content-start] minmax(450px, calc(800px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(0px, 200px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body:not(.floating):not(.docked) .page-columns.toc-left .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] 35px [page-start-inset] minmax(0px, 175px) [body-start-outset] 35px [body-start] 1.5em [body-content-start] minmax(450px, calc(800px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(0px, 200px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.floating .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] minmax(25px, 50px) [page-start-inset] minmax(50px, 150px) [body-start-outset] minmax(25px, 50px) [body-start] 1.5em [body-content-start] minmax(500px, calc(800px - 3em)) [body-content-end] 1.5em [body-end] minmax(25px, 50px) [body-end-outset] minmax(50px, 150px) [page-end-inset] minmax(25px, 50px) [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.docked .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start] minmax(50px, 100px) [page-start-inset] 50px [body-start-outset] 50px [body-start] 1.5em [body-content-start] minmax(500px, calc(1000px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(50px, 100px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.docked.fullcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start] minmax(50px, 100px) [page-start-inset] 50px [body-start-outset] 50px [body-start] 1.5em [body-content-start] minmax(500px, calc(1000px - 3em)) [body-content-end] 1.5em [body-end body-end-outset page-end-inset page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.floating.fullcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] 50px [page-start-inset] minmax(50px, 150px) [body-start-outset] 50px [body-start] 1.5em [body-content-start] minmax(500px, calc(800px - 3em)) [body-content-end] 1.5em [body-end body-end-outset page-end-inset page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.docked.slimcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start] minmax(50px, 100px) [page-start-inset] 50px [body-start-outset] 50px [body-start] 1.5em [body-content-start] minmax(450px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(0px, 200px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.docked.listing .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start] minmax(50px, 100px) [page-start-inset] 50px [body-start-outset] 50px [body-start] 1.5em [body-content-start] minmax(500px, calc(1000px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(0px, 200px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.floating.slimcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] 50px [page-start-inset] minmax(50px, 150px) [body-start-outset] 50px [body-start] 1.5em [body-content-start] minmax(450px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(50px, 150px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.floating.listing .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] minmax(25px, 50px) [page-start-inset] minmax(50px, 150px) [body-start-outset] minmax(25px, 50px) [body-start] 1.5em [body-content-start] minmax(500px, calc(800px - 3em)) [body-content-end] 1.5em [body-end] minmax(25px, 50px) [body-end-outset] minmax(50px, 150px) [page-end-inset] minmax(25px, 50px) [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}}@media(max-width: 991.98px){body .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset] 5fr [body-start] 1.5em [body-content-start] minmax(500px, calc(800px - 3em)) [body-content-end] 1.5em [body-end] 35px [body-end-outset] minmax(75px, 145px) [page-end-inset] 35px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.fullcontent:not(.floating):not(.docked) .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset] 5fr [body-start] 1.5em [body-content-start] minmax(500px, calc(800px - 3em)) [body-content-end] 1.5em [body-end body-end-outset page-end-inset page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.slimcontent:not(.floating):not(.docked) .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset] 5fr [body-start] 1.5em [body-content-start] minmax(500px, calc(800px - 3em)) [body-content-end] 1.5em [body-end] 35px [body-end-outset] minmax(75px, 145px) [page-end-inset] 35px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.listing:not(.floating):not(.docked) .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset] 5fr [body-start] 1.5em [body-content-start] minmax(500px, calc(1250px - 3em)) [body-content-end body-end body-end-outset page-end-inset page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body:not(.floating):not(.docked) .page-columns.toc-left{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] 35px [page-start-inset] minmax(0px, 145px) [body-start-outset] 35px [body-start] 1.5em [body-content-start] minmax(450px, calc(800px - 3em)) [body-content-end] 1.5em [body-end body-end-outset page-end-inset page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body:not(.floating):not(.docked) .page-columns.toc-left .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start] 35px [page-start-inset] minmax(0px, 145px) [body-start-outset] 35px [body-start] 1.5em [body-content-start] minmax(450px, calc(800px - 3em)) [body-content-end] 1.5em [body-end body-end-outset page-end-inset page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.floating .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start page-start-inset body-start-outset body-start] 1.5em [body-content-start] minmax(500px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(75px, 150px) [page-end-inset] 25px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.docked .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset body-start body-content-start] minmax(500px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(25px, 50px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.docked.fullcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset body-start body-content-start] minmax(500px, calc(1000px - 3em)) [body-content-end] 1.5em [body-end body-end-outset page-end-inset page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.floating.fullcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start page-start-inset body-start-outset body-start] 1em [body-content-start] minmax(500px, calc(800px - 3em)) [body-content-end] 1.5em [body-end body-end-outset page-end-inset page-end] 4fr [screen-end-inset] 1.5em [screen-end]}body.docked.slimcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset body-start body-content-start] minmax(500px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(25px, 50px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.docked.listing .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset body-start body-content-start] minmax(500px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(25px, 50px) [page-end-inset] 50px [page-end] 5fr [screen-end-inset] 1.5em [screen-end]}body.floating.slimcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start page-start-inset body-start-outset body-start] 1em [body-content-start] minmax(500px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 35px [body-end-outset] minmax(75px, 145px) [page-end-inset] 35px [page-end] 4fr [screen-end-inset] 1.5em [screen-end]}body.floating.listing .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset] 5fr [page-start page-start-inset body-start-outset body-start] 1em [body-content-start] minmax(500px, calc(750px - 3em)) [body-content-end] 1.5em [body-end] 50px [body-end-outset] minmax(75px, 150px) [page-end-inset] 25px [page-end] 4fr [screen-end-inset] 1.5em [screen-end]}}@media(max-width: 767.98px){body .page-columns,body.fullcontent:not(.floating):not(.docked) .page-columns,body.slimcontent:not(.floating):not(.docked) .page-columns,body.docked .page-columns,body.docked.slimcontent .page-columns,body.docked.fullcontent .page-columns,body.floating .page-columns,body.floating.slimcontent .page-columns,body.floating.fullcontent .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset body-start body-content-start] minmax(0px, 1fr) [body-content-end body-end body-end-outset page-end-inset page-end screen-end-inset] 1.5em [screen-end]}body:not(.floating):not(.docked) .page-columns.toc-left{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset body-start body-content-start] minmax(0px, 1fr) [body-content-end body-end body-end-outset page-end-inset page-end screen-end-inset] 1.5em [screen-end]}body:not(.floating):not(.docked) .page-columns.toc-left .page-columns{display:grid;gap:0;grid-template-columns:[screen-start] 1.5em [screen-start-inset page-start page-start-inset body-start-outset body-start body-content-start] minmax(0px, 1fr) [body-content-end body-end body-end-outset page-end-inset page-end screen-end-inset] 1.5em [screen-end]}nav[role=doc-toc]{display:none}}body,.page-row-navigation{grid-template-rows:[page-top] max-content [contents-top] max-content [contents-bottom] max-content [page-bottom]}.page-rows-contents{grid-template-rows:[content-top] minmax(max-content, 1fr) [content-bottom] minmax(60px, max-content) [page-bottom]}.page-full{grid-column:screen-start/screen-end !important}.page-columns>*{grid-column:body-content-start/body-content-end}.page-columns.column-page>*{grid-column:page-start/page-end}.page-columns.column-page-left .page-columns.page-full>*,.page-columns.column-page-left>*{grid-column:page-start/body-content-end}.page-columns.column-page-right .page-columns.page-full>*,.page-columns.column-page-right>*{grid-column:body-content-start/page-end}.page-rows{grid-auto-rows:auto}.header{grid-column:screen-start/screen-end;grid-row:page-top/contents-top}#quarto-content{padding:0;grid-column:screen-start/screen-end;grid-row:contents-top/contents-bottom}body.floating .sidebar.sidebar-navigation{grid-column:page-start/body-start;grid-row:content-top/page-bottom}body.docked .sidebar.sidebar-navigation{grid-column:screen-start/body-start;grid-row:content-top/page-bottom}.sidebar.toc-left{grid-column:page-start/body-start;grid-row:content-top/page-bottom}.sidebar.margin-sidebar{grid-column:body-end/page-end;grid-row:content-top/page-bottom}.page-columns .content{grid-column:body-content-start/body-content-end;grid-row:content-top/content-bottom;align-content:flex-start}.page-columns .page-navigation{grid-column:body-content-start/body-content-end;grid-row:content-bottom/page-bottom}.page-columns .footer{grid-column:screen-start/screen-end;grid-row:contents-bottom/page-bottom}.page-columns .column-body{grid-column:body-content-start/body-content-end}.page-columns .column-body-fullbleed{grid-column:body-start/body-end}.page-columns .column-body-outset{grid-column:body-start-outset/body-end-outset;z-index:998;opacity:.999}.page-columns .column-body-outset table{background:#fff}.page-columns .column-body-outset-left{grid-column:body-start-outset/body-content-end;z-index:998;opacity:.999}.page-columns .column-body-outset-left table{background:#fff}.page-columns .column-body-outset-right{grid-column:body-content-start/body-end-outset;z-index:998;opacity:.999}.page-columns .column-body-outset-right table{background:#fff}.page-columns .column-page{grid-column:page-start/page-end;z-index:998;opacity:.999}.page-columns .column-page table{background:#fff}.page-columns .column-page-inset{grid-column:page-start-inset/page-end-inset;z-index:998;opacity:.999}.page-columns .column-page-inset table{background:#fff}.page-columns .column-page-inset-left{grid-column:page-start-inset/body-content-end;z-index:998;opacity:.999}.page-columns .column-page-inset-left table{background:#fff}.page-columns .column-page-inset-right{grid-column:body-content-start/page-end-inset;z-index:998;opacity:.999}.page-columns .column-page-inset-right figcaption table{background:#fff}.page-columns .column-page-left{grid-column:page-start/body-content-end;z-index:998;opacity:.999}.page-columns .column-page-left table{background:#fff}.page-columns .column-page-right{grid-column:body-content-start/page-end;z-index:998;opacity:.999}.page-columns .column-page-right figcaption table{background:#fff}#quarto-content.page-columns #quarto-margin-sidebar,#quarto-content.page-columns #quarto-sidebar{z-index:1}@media(max-width: 991.98px){#quarto-content.page-columns #quarto-margin-sidebar.collapse,#quarto-content.page-columns #quarto-sidebar.collapse,#quarto-content.page-columns #quarto-margin-sidebar.collapsing,#quarto-content.page-columns #quarto-sidebar.collapsing{z-index:1055}}#quarto-content.page-columns main.column-page,#quarto-content.page-columns main.column-page-right,#quarto-content.page-columns main.column-page-left{z-index:0}.page-columns .column-screen-inset{grid-column:screen-start-inset/screen-end-inset;z-index:998;opacity:.999}.page-columns .column-screen-inset table{background:#fff}.page-columns .column-screen-inset-left{grid-column:screen-start-inset/body-content-end;z-index:998;opacity:.999}.page-columns .column-screen-inset-left table{background:#fff}.page-columns .column-screen-inset-right{grid-column:body-content-start/screen-end-inset;z-index:998;opacity:.999}.page-columns .column-screen-inset-right table{background:#fff}.page-columns .column-screen{grid-column:screen-start/screen-end;z-index:998;opacity:.999}.page-columns .column-screen table{background:#fff}.page-columns .column-screen-left{grid-column:screen-start/body-content-end;z-index:998;opacity:.999}.page-columns .column-screen-left table{background:#fff}.page-columns .column-screen-right{grid-column:body-content-start/screen-end;z-index:998;opacity:.999}.page-columns .column-screen-right table{background:#fff}.page-columns .column-screen-inset-shaded{grid-column:screen-start/screen-end;padding:1em;background:#f8f9fa;z-index:998;opacity:.999;margin-bottom:1em}.zindex-content{z-index:998;opacity:.999}.zindex-modal{z-index:1055;opacity:.999}.zindex-over-content{z-index:999;opacity:.999}img.img-fluid.column-screen,img.img-fluid.column-screen-inset-shaded,img.img-fluid.column-screen-inset,img.img-fluid.column-screen-inset-left,img.img-fluid.column-screen-inset-right,img.img-fluid.column-screen-left,img.img-fluid.column-screen-right{width:100%}@media(min-width: 992px){.margin-caption,div.aside,aside:not(.footnotes):not(.sidebar),.column-margin{grid-column:body-end/page-end !important;z-index:998}.column-sidebar{grid-column:page-start/body-start !important;z-index:998}.column-leftmargin{grid-column:screen-start-inset/body-start !important;z-index:998}.no-row-height{height:1em;overflow:visible}}@media(max-width: 991.98px){.margin-caption,div.aside,aside:not(.footnotes):not(.sidebar),.column-margin{grid-column:body-end/page-end !important;z-index:998}.no-row-height{height:1em;overflow:visible}.page-columns.page-full{overflow:visible}.page-columns.toc-left .margin-caption,.page-columns.toc-left div.aside,.page-columns.toc-left aside:not(.footnotes):not(.sidebar),.page-columns.toc-left .column-margin{grid-column:body-content-start/body-content-end !important;z-index:998;opacity:.999}.page-columns.toc-left .no-row-height{height:initial;overflow:initial}}@media(max-width: 767.98px){.margin-caption,div.aside,aside:not(.footnotes):not(.sidebar),.column-margin{grid-column:body-content-start/body-content-end !important;z-index:998;opacity:.999}.no-row-height{height:initial;overflow:initial}#quarto-margin-sidebar{display:none}#quarto-sidebar-toc-left{display:none}.hidden-sm{display:none}}.panel-grid{display:grid;grid-template-rows:repeat(1, 1fr);grid-template-columns:repeat(24, 1fr);gap:1em}.panel-grid .g-col-1{grid-column:auto/span 1}.panel-grid .g-col-2{grid-column:auto/span 2}.panel-grid .g-col-3{grid-column:auto/span 3}.panel-grid .g-col-4{grid-column:auto/span 4}.panel-grid .g-col-5{grid-column:auto/span 5}.panel-grid .g-col-6{grid-column:auto/span 6}.panel-grid .g-col-7{grid-column:auto/span 7}.panel-grid .g-col-8{grid-column:auto/span 8}.panel-grid .g-col-9{grid-column:auto/span 9}.panel-grid .g-col-10{grid-column:auto/span 10}.panel-grid .g-col-11{grid-column:auto/span 11}.panel-grid .g-col-12{grid-column:auto/span 12}.panel-grid .g-col-13{grid-column:auto/span 13}.panel-grid .g-col-14{grid-column:auto/span 14}.panel-grid .g-col-15{grid-column:auto/span 15}.panel-grid .g-col-16{grid-column:auto/span 16}.panel-grid .g-col-17{grid-column:auto/span 17}.panel-grid .g-col-18{grid-column:auto/span 18}.panel-grid .g-col-19{grid-column:auto/span 19}.panel-grid .g-col-20{grid-column:auto/span 20}.panel-grid .g-col-21{grid-column:auto/span 21}.panel-grid .g-col-22{grid-column:auto/span 22}.panel-grid .g-col-23{grid-column:auto/span 23}.panel-grid .g-col-24{grid-column:auto/span 24}.panel-grid .g-start-1{grid-column-start:1}.panel-grid .g-start-2{grid-column-start:2}.panel-grid .g-start-3{grid-column-start:3}.panel-grid .g-start-4{grid-column-start:4}.panel-grid .g-start-5{grid-column-start:5}.panel-grid .g-start-6{grid-column-start:6}.panel-grid .g-start-7{grid-column-start:7}.panel-grid .g-start-8{grid-column-start:8}.panel-grid .g-start-9{grid-column-start:9}.panel-grid .g-start-10{grid-column-start:10}.panel-grid .g-start-11{grid-column-start:11}.panel-grid .g-start-12{grid-column-start:12}.panel-grid .g-start-13{grid-column-start:13}.panel-grid .g-start-14{grid-column-start:14}.panel-grid .g-start-15{grid-column-start:15}.panel-grid .g-start-16{grid-column-start:16}.panel-grid .g-start-17{grid-column-start:17}.panel-grid .g-start-18{grid-column-start:18}.panel-grid .g-start-19{grid-column-start:19}.panel-grid .g-start-20{grid-column-start:20}.panel-grid .g-start-21{grid-column-start:21}.panel-grid .g-start-22{grid-column-start:22}.panel-grid .g-start-23{grid-column-start:23}@media(min-width: 576px){.panel-grid .g-col-sm-1{grid-column:auto/span 1}.panel-grid .g-col-sm-2{grid-column:auto/span 2}.panel-grid .g-col-sm-3{grid-column:auto/span 3}.panel-grid .g-col-sm-4{grid-column:auto/span 4}.panel-grid .g-col-sm-5{grid-column:auto/span 5}.panel-grid .g-col-sm-6{grid-column:auto/span 6}.panel-grid .g-col-sm-7{grid-column:auto/span 7}.panel-grid .g-col-sm-8{grid-column:auto/span 8}.panel-grid .g-col-sm-9{grid-column:auto/span 9}.panel-grid .g-col-sm-10{grid-column:auto/span 10}.panel-grid .g-col-sm-11{grid-column:auto/span 11}.panel-grid .g-col-sm-12{grid-column:auto/span 12}.panel-grid .g-col-sm-13{grid-column:auto/span 13}.panel-grid .g-col-sm-14{grid-column:auto/span 14}.panel-grid .g-col-sm-15{grid-column:auto/span 15}.panel-grid .g-col-sm-16{grid-column:auto/span 16}.panel-grid .g-col-sm-17{grid-column:auto/span 17}.panel-grid .g-col-sm-18{grid-column:auto/span 18}.panel-grid .g-col-sm-19{grid-column:auto/span 19}.panel-grid .g-col-sm-20{grid-column:auto/span 20}.panel-grid .g-col-sm-21{grid-column:auto/span 21}.panel-grid .g-col-sm-22{grid-column:auto/span 22}.panel-grid .g-col-sm-23{grid-column:auto/span 23}.panel-grid .g-col-sm-24{grid-column:auto/span 24}.panel-grid .g-start-sm-1{grid-column-start:1}.panel-grid .g-start-sm-2{grid-column-start:2}.panel-grid .g-start-sm-3{grid-column-start:3}.panel-grid .g-start-sm-4{grid-column-start:4}.panel-grid .g-start-sm-5{grid-column-start:5}.panel-grid .g-start-sm-6{grid-column-start:6}.panel-grid .g-start-sm-7{grid-column-start:7}.panel-grid .g-start-sm-8{grid-column-start:8}.panel-grid .g-start-sm-9{grid-column-start:9}.panel-grid .g-start-sm-10{grid-column-start:10}.panel-grid .g-start-sm-11{grid-column-start:11}.panel-grid .g-start-sm-12{grid-column-start:12}.panel-grid .g-start-sm-13{grid-column-start:13}.panel-grid .g-start-sm-14{grid-column-start:14}.panel-grid .g-start-sm-15{grid-column-start:15}.panel-grid .g-start-sm-16{grid-column-start:16}.panel-grid .g-start-sm-17{grid-column-start:17}.panel-grid .g-start-sm-18{grid-column-start:18}.panel-grid .g-start-sm-19{grid-column-start:19}.panel-grid .g-start-sm-20{grid-column-start:20}.panel-grid .g-start-sm-21{grid-column-start:21}.panel-grid .g-start-sm-22{grid-column-start:22}.panel-grid .g-start-sm-23{grid-column-start:23}}@media(min-width: 768px){.panel-grid .g-col-md-1{grid-column:auto/span 1}.panel-grid .g-col-md-2{grid-column:auto/span 2}.panel-grid .g-col-md-3{grid-column:auto/span 3}.panel-grid .g-col-md-4{grid-column:auto/span 4}.panel-grid .g-col-md-5{grid-column:auto/span 5}.panel-grid .g-col-md-6{grid-column:auto/span 6}.panel-grid .g-col-md-7{grid-column:auto/span 7}.panel-grid .g-col-md-8{grid-column:auto/span 8}.panel-grid .g-col-md-9{grid-column:auto/span 9}.panel-grid .g-col-md-10{grid-column:auto/span 10}.panel-grid .g-col-md-11{grid-column:auto/span 11}.panel-grid .g-col-md-12{grid-column:auto/span 12}.panel-grid .g-col-md-13{grid-column:auto/span 13}.panel-grid .g-col-md-14{grid-column:auto/span 14}.panel-grid .g-col-md-15{grid-column:auto/span 15}.panel-grid .g-col-md-16{grid-column:auto/span 16}.panel-grid .g-col-md-17{grid-column:auto/span 17}.panel-grid .g-col-md-18{grid-column:auto/span 18}.panel-grid .g-col-md-19{grid-column:auto/span 19}.panel-grid .g-col-md-20{grid-column:auto/span 20}.panel-grid .g-col-md-21{grid-column:auto/span 21}.panel-grid .g-col-md-22{grid-column:auto/span 22}.panel-grid .g-col-md-23{grid-column:auto/span 23}.panel-grid .g-col-md-24{grid-column:auto/span 24}.panel-grid .g-start-md-1{grid-column-start:1}.panel-grid .g-start-md-2{grid-column-start:2}.panel-grid .g-start-md-3{grid-column-start:3}.panel-grid .g-start-md-4{grid-column-start:4}.panel-grid .g-start-md-5{grid-column-start:5}.panel-grid .g-start-md-6{grid-column-start:6}.panel-grid .g-start-md-7{grid-column-start:7}.panel-grid .g-start-md-8{grid-column-start:8}.panel-grid .g-start-md-9{grid-column-start:9}.panel-grid .g-start-md-10{grid-column-start:10}.panel-grid .g-start-md-11{grid-column-start:11}.panel-grid .g-start-md-12{grid-column-start:12}.panel-grid .g-start-md-13{grid-column-start:13}.panel-grid .g-start-md-14{grid-column-start:14}.panel-grid .g-start-md-15{grid-column-start:15}.panel-grid .g-start-md-16{grid-column-start:16}.panel-grid .g-start-md-17{grid-column-start:17}.panel-grid .g-start-md-18{grid-column-start:18}.panel-grid .g-start-md-19{grid-column-start:19}.panel-grid .g-start-md-20{grid-column-start:20}.panel-grid .g-start-md-21{grid-column-start:21}.panel-grid .g-start-md-22{grid-column-start:22}.panel-grid .g-start-md-23{grid-column-start:23}}@media(min-width: 992px){.panel-grid .g-col-lg-1{grid-column:auto/span 1}.panel-grid .g-col-lg-2{grid-column:auto/span 2}.panel-grid .g-col-lg-3{grid-column:auto/span 3}.panel-grid .g-col-lg-4{grid-column:auto/span 4}.panel-grid .g-col-lg-5{grid-column:auto/span 5}.panel-grid .g-col-lg-6{grid-column:auto/span 6}.panel-grid .g-col-lg-7{grid-column:auto/span 7}.panel-grid .g-col-lg-8{grid-column:auto/span 8}.panel-grid .g-col-lg-9{grid-column:auto/span 9}.panel-grid .g-col-lg-10{grid-column:auto/span 10}.panel-grid .g-col-lg-11{grid-column:auto/span 11}.panel-grid .g-col-lg-12{grid-column:auto/span 12}.panel-grid .g-col-lg-13{grid-column:auto/span 13}.panel-grid .g-col-lg-14{grid-column:auto/span 14}.panel-grid .g-col-lg-15{grid-column:auto/span 15}.panel-grid .g-col-lg-16{grid-column:auto/span 16}.panel-grid .g-col-lg-17{grid-column:auto/span 17}.panel-grid .g-col-lg-18{grid-column:auto/span 18}.panel-grid .g-col-lg-19{grid-column:auto/span 19}.panel-grid .g-col-lg-20{grid-column:auto/span 20}.panel-grid .g-col-lg-21{grid-column:auto/span 21}.panel-grid .g-col-lg-22{grid-column:auto/span 22}.panel-grid .g-col-lg-23{grid-column:auto/span 23}.panel-grid .g-col-lg-24{grid-column:auto/span 24}.panel-grid .g-start-lg-1{grid-column-start:1}.panel-grid .g-start-lg-2{grid-column-start:2}.panel-grid .g-start-lg-3{grid-column-start:3}.panel-grid .g-start-lg-4{grid-column-start:4}.panel-grid .g-start-lg-5{grid-column-start:5}.panel-grid .g-start-lg-6{grid-column-start:6}.panel-grid .g-start-lg-7{grid-column-start:7}.panel-grid .g-start-lg-8{grid-column-start:8}.panel-grid .g-start-lg-9{grid-column-start:9}.panel-grid .g-start-lg-10{grid-column-start:10}.panel-grid .g-start-lg-11{grid-column-start:11}.panel-grid .g-start-lg-12{grid-column-start:12}.panel-grid .g-start-lg-13{grid-column-start:13}.panel-grid .g-start-lg-14{grid-column-start:14}.panel-grid .g-start-lg-15{grid-column-start:15}.panel-grid .g-start-lg-16{grid-column-start:16}.panel-grid .g-start-lg-17{grid-column-start:17}.panel-grid .g-start-lg-18{grid-column-start:18}.panel-grid .g-start-lg-19{grid-column-start:19}.panel-grid .g-start-lg-20{grid-column-start:20}.panel-grid .g-start-lg-21{grid-column-start:21}.panel-grid .g-start-lg-22{grid-column-start:22}.panel-grid .g-start-lg-23{grid-column-start:23}}@media(min-width: 1200px){.panel-grid .g-col-xl-1{grid-column:auto/span 1}.panel-grid .g-col-xl-2{grid-column:auto/span 2}.panel-grid .g-col-xl-3{grid-column:auto/span 3}.panel-grid .g-col-xl-4{grid-column:auto/span 4}.panel-grid .g-col-xl-5{grid-column:auto/span 5}.panel-grid .g-col-xl-6{grid-column:auto/span 6}.panel-grid .g-col-xl-7{grid-column:auto/span 7}.panel-grid .g-col-xl-8{grid-column:auto/span 8}.panel-grid .g-col-xl-9{grid-column:auto/span 9}.panel-grid .g-col-xl-10{grid-column:auto/span 10}.panel-grid .g-col-xl-11{grid-column:auto/span 11}.panel-grid .g-col-xl-12{grid-column:auto/span 12}.panel-grid .g-col-xl-13{grid-column:auto/span 13}.panel-grid .g-col-xl-14{grid-column:auto/span 14}.panel-grid .g-col-xl-15{grid-column:auto/span 15}.panel-grid .g-col-xl-16{grid-column:auto/span 16}.panel-grid .g-col-xl-17{grid-column:auto/span 17}.panel-grid .g-col-xl-18{grid-column:auto/span 18}.panel-grid .g-col-xl-19{grid-column:auto/span 19}.panel-grid .g-col-xl-20{grid-column:auto/span 20}.panel-grid .g-col-xl-21{grid-column:auto/span 21}.panel-grid .g-col-xl-22{grid-column:auto/span 22}.panel-grid .g-col-xl-23{grid-column:auto/span 23}.panel-grid .g-col-xl-24{grid-column:auto/span 24}.panel-grid .g-start-xl-1{grid-column-start:1}.panel-grid .g-start-xl-2{grid-column-start:2}.panel-grid .g-start-xl-3{grid-column-start:3}.panel-grid .g-start-xl-4{grid-column-start:4}.panel-grid .g-start-xl-5{grid-column-start:5}.panel-grid .g-start-xl-6{grid-column-start:6}.panel-grid .g-start-xl-7{grid-column-start:7}.panel-grid .g-start-xl-8{grid-column-start:8}.panel-grid .g-start-xl-9{grid-column-start:9}.panel-grid .g-start-xl-10{grid-column-start:10}.panel-grid .g-start-xl-11{grid-column-start:11}.panel-grid .g-start-xl-12{grid-column-start:12}.panel-grid .g-start-xl-13{grid-column-start:13}.panel-grid .g-start-xl-14{grid-column-start:14}.panel-grid .g-start-xl-15{grid-column-start:15}.panel-grid .g-start-xl-16{grid-column-start:16}.panel-grid .g-start-xl-17{grid-column-start:17}.panel-grid .g-start-xl-18{grid-column-start:18}.panel-grid .g-start-xl-19{grid-column-start:19}.panel-grid .g-start-xl-20{grid-column-start:20}.panel-grid .g-start-xl-21{grid-column-start:21}.panel-grid .g-start-xl-22{grid-column-start:22}.panel-grid .g-start-xl-23{grid-column-start:23}}@media(min-width: 1400px){.panel-grid .g-col-xxl-1{grid-column:auto/span 1}.panel-grid .g-col-xxl-2{grid-column:auto/span 2}.panel-grid .g-col-xxl-3{grid-column:auto/span 3}.panel-grid .g-col-xxl-4{grid-column:auto/span 4}.panel-grid .g-col-xxl-5{grid-column:auto/span 5}.panel-grid .g-col-xxl-6{grid-column:auto/span 6}.panel-grid .g-col-xxl-7{grid-column:auto/span 7}.panel-grid .g-col-xxl-8{grid-column:auto/span 8}.panel-grid .g-col-xxl-9{grid-column:auto/span 9}.panel-grid .g-col-xxl-10{grid-column:auto/span 10}.panel-grid .g-col-xxl-11{grid-column:auto/span 11}.panel-grid .g-col-xxl-12{grid-column:auto/span 12}.panel-grid .g-col-xxl-13{grid-column:auto/span 13}.panel-grid .g-col-xxl-14{grid-column:auto/span 14}.panel-grid .g-col-xxl-15{grid-column:auto/span 15}.panel-grid .g-col-xxl-16{grid-column:auto/span 16}.panel-grid .g-col-xxl-17{grid-column:auto/span 17}.panel-grid .g-col-xxl-18{grid-column:auto/span 18}.panel-grid .g-col-xxl-19{grid-column:auto/span 19}.panel-grid .g-col-xxl-20{grid-column:auto/span 20}.panel-grid .g-col-xxl-21{grid-column:auto/span 21}.panel-grid .g-col-xxl-22{grid-column:auto/span 22}.panel-grid .g-col-xxl-23{grid-column:auto/span 23}.panel-grid .g-col-xxl-24{grid-column:auto/span 24}.panel-grid .g-start-xxl-1{grid-column-start:1}.panel-grid .g-start-xxl-2{grid-column-start:2}.panel-grid .g-start-xxl-3{grid-column-start:3}.panel-grid .g-start-xxl-4{grid-column-start:4}.panel-grid .g-start-xxl-5{grid-column-start:5}.panel-grid .g-start-xxl-6{grid-column-start:6}.panel-grid .g-start-xxl-7{grid-column-start:7}.panel-grid .g-start-xxl-8{grid-column-start:8}.panel-grid .g-start-xxl-9{grid-column-start:9}.panel-grid .g-start-xxl-10{grid-column-start:10}.panel-grid .g-start-xxl-11{grid-column-start:11}.panel-grid .g-start-xxl-12{grid-column-start:12}.panel-grid .g-start-xxl-13{grid-column-start:13}.panel-grid .g-start-xxl-14{grid-column-start:14}.panel-grid .g-start-xxl-15{grid-column-start:15}.panel-grid .g-start-xxl-16{grid-column-start:16}.panel-grid .g-start-xxl-17{grid-column-start:17}.panel-grid .g-start-xxl-18{grid-column-start:18}.panel-grid .g-start-xxl-19{grid-column-start:19}.panel-grid .g-start-xxl-20{grid-column-start:20}.panel-grid .g-start-xxl-21{grid-column-start:21}.panel-grid .g-start-xxl-22{grid-column-start:22}.panel-grid .g-start-xxl-23{grid-column-start:23}}main{margin-top:1em;margin-bottom:1em}h1,.h1,h2,.h2{color:inherit;margin-top:2rem;margin-bottom:1rem;font-weight:600}h1.title,.title.h1{margin-top:0}main.content>section:first-of-type>h2:first-child,main.content>section:first-of-type>.h2:first-child{margin-top:0}h2,.h2{border-bottom:1px solid #dee2e6;padding-bottom:.5rem}h3,.h3{font-weight:600}h3,.h3,h4,.h4{opacity:.9;margin-top:1.5rem}h5,.h5,h6,.h6{opacity:.9}.header-section-number{color:#6d7a86}.nav-link.active .header-section-number{color:inherit}mark,.mark{padding:0em}.panel-caption,.figure-caption,.subfigure-caption,.table-caption,figcaption,caption{font-size:.9rem;color:#6d7a86}.quarto-layout-cell[data-ref-parent] caption{color:#6d7a86}.column-margin figcaption,.margin-caption,div.aside,aside,.column-margin{color:#6d7a86;font-size:.825rem}.panel-caption.margin-caption{text-align:inherit}.column-margin.column-container p{margin-bottom:0}.column-margin.column-container>*:not(.collapse):first-child{padding-bottom:.5em;display:block}.column-margin.column-container>*:not(.collapse):not(:first-child){padding-top:.5em;padding-bottom:.5em;display:block}.column-margin.column-container>*.collapse:not(.show){display:none}@media(min-width: 768px){.column-margin.column-container .callout-margin-content:first-child{margin-top:4.5em}.column-margin.column-container .callout-margin-content-simple:first-child{margin-top:3.5em}}.margin-caption>*{padding-top:.5em;padding-bottom:.5em}@media(max-width: 767.98px){.quarto-layout-row{flex-direction:column}}.nav-tabs .nav-item{margin-top:1px;cursor:pointer}.tab-content{margin-top:0px;border-left:#dee2e6 1px solid;border-right:#dee2e6 1px solid;border-bottom:#dee2e6 1px solid;margin-left:0;padding:1em;margin-bottom:1em}@media(max-width: 767.98px){.layout-sidebar{margin-left:0;margin-right:0}}.panel-sidebar,.panel-sidebar .form-control,.panel-input,.panel-input .form-control,.selectize-dropdown{font-size:.9rem}.panel-sidebar .form-control,.panel-input .form-control{padding-top:.1rem}.tab-pane div.sourceCode{margin-top:0px}.tab-pane>p{padding-top:0}.tab-pane>p:nth-child(1){padding-top:0}.tab-pane>p:last-child{margin-bottom:0}.tab-pane>pre:last-child{margin-bottom:0}.tab-content>.tab-pane:not(.active){display:none !important}div.sourceCode{background-color:rgba(233,236,239,.65);border:1px solid rgba(233,236,239,.65);border-radius:.25rem}pre.sourceCode{background-color:rgba(0,0,0,0)}pre.sourceCode{border:none;font-size:.875em;overflow:visible !important;padding:.4em}.callout pre.sourceCode{padding-left:0}div.sourceCode{overflow-y:hidden}.callout div.sourceCode{margin-left:initial}.blockquote{font-size:inherit;padding-left:1rem;padding-right:1.5rem;color:#6d7a86}.blockquote h1:first-child,.blockquote .h1:first-child,.blockquote h2:first-child,.blockquote .h2:first-child,.blockquote h3:first-child,.blockquote .h3:first-child,.blockquote h4:first-child,.blockquote .h4:first-child,.blockquote h5:first-child,.blockquote .h5:first-child{margin-top:0}pre{background-color:initial;padding:initial;border:initial}p pre code:not(.sourceCode),li pre code:not(.sourceCode),pre code:not(.sourceCode){background-color:initial}p code:not(.sourceCode),li code:not(.sourceCode),td code:not(.sourceCode){background-color:#f8f9fa;padding:.2em}nav p code:not(.sourceCode),nav li code:not(.sourceCode),nav td code:not(.sourceCode){background-color:rgba(0,0,0,0);padding:0}td code:not(.sourceCode){white-space:pre-wrap}#quarto-embedded-source-code-modal>.modal-dialog{max-width:1000px;padding-left:1.75rem;padding-right:1.75rem}#quarto-embedded-source-code-modal>.modal-dialog>.modal-content>.modal-body{padding:0}#quarto-embedded-source-code-modal>.modal-dialog>.modal-content>.modal-body div.sourceCode{margin:0;padding:.2rem .2rem;border-radius:0px;border:none}#quarto-embedded-source-code-modal>.modal-dialog>.modal-content>.modal-header{padding:.7rem}.code-tools-button{font-size:1rem;padding:.15rem .15rem;margin-left:5px;color:#6c757d;background-color:rgba(0,0,0,0);transition:initial;cursor:pointer}.code-tools-button>.bi::before{display:inline-block;height:1rem;width:1rem;content:"";vertical-align:-0.125em;background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(108, 117, 125)" viewBox="0 0 16 16"><path d="M10.478 1.647a.5.5 0 1 0-.956-.294l-4 13a.5.5 0 0 0 .956.294l4-13zM4.854 4.146a.5.5 0 0 1 0 .708L1.707 8l3.147 3.146a.5.5 0 0 1-.708.708l-3.5-3.5a.5.5 0 0 1 0-.708l3.5-3.5a.5.5 0 0 1 .708 0zm6.292 0a.5.5 0 0 0 0 .708L14.293 8l-3.147 3.146a.5.5 0 0 0 .708.708l3.5-3.5a.5.5 0 0 0 0-.708l-3.5-3.5a.5.5 0 0 0-.708 0z"/></svg>');background-repeat:no-repeat;background-size:1rem 1rem}.code-tools-button:hover>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(52, 58, 64)" viewBox="0 0 16 16"><path d="M10.478 1.647a.5.5 0 1 0-.956-.294l-4 13a.5.5 0 0 0 .956.294l4-13zM4.854 4.146a.5.5 0 0 1 0 .708L1.707 8l3.147 3.146a.5.5 0 0 1-.708.708l-3.5-3.5a.5.5 0 0 1 0-.708l3.5-3.5a.5.5 0 0 1 .708 0zm6.292 0a.5.5 0 0 0 0 .708L14.293 8l-3.147 3.146a.5.5 0 0 0 .708.708l3.5-3.5a.5.5 0 0 0 0-.708l-3.5-3.5a.5.5 0 0 0-.708 0z"/></svg>')}#quarto-embedded-source-code-modal .code-copy-button>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(108, 117, 125)" viewBox="0 0 16 16"><path d="M4 1.5H3a2 2 0 0 0-2 2V14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V3.5a2 2 0 0 0-2-2h-1v1h1a1 1 0 0 1 1 1V14a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V3.5a1 1 0 0 1 1-1h1v-1z"/><path d="M9.5 1a.5.5 0 0 1 .5.5v1a.5.5 0 0 1-.5.5h-3a.5.5 0 0 1-.5-.5v-1a.5.5 0 0 1 .5-.5h3zm-3-1A1.5 1.5 0 0 0 5 1.5v1A1.5 1.5 0 0 0 6.5 4h3A1.5 1.5 0 0 0 11 2.5v-1A1.5 1.5 0 0 0 9.5 0h-3z"/></svg>')}#quarto-embedded-source-code-modal .code-copy-button-checked>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(108, 117, 125)" viewBox="0 0 16 16"><path d="M13.854 3.646a.5.5 0 0 1 0 .708l-7 7a.5.5 0 0 1-.708 0l-3.5-3.5a.5.5 0 1 1 .708-.708L6.5 10.293l6.646-6.647a.5.5 0 0 1 .708 0z"/></svg>')}.sidebar{will-change:top;transition:top 200ms linear;position:sticky;overflow-y:auto;padding-top:1.2em;max-height:100vh}.sidebar.toc-left,.sidebar.margin-sidebar{top:0px;padding-top:1em}.sidebar.quarto-banner-title-block-sidebar>*{padding-top:1.65em}figure .quarto-notebook-link{margin-top:.5em}.quarto-notebook-link{font-size:.75em;color:#6c757d;margin-bottom:1em;text-decoration:none;display:block}.quarto-notebook-link:hover{text-decoration:underline;color:#2761e3}.quarto-notebook-link::before{display:inline-block;height:.75rem;width:.75rem;margin-bottom:0em;margin-right:.25em;content:"";vertical-align:-0.125em;background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(108, 117, 125)" class="bi bi-journal-code" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8.646 5.646a.5.5 0 0 1 .708 0l2 2a.5.5 0 0 1 0 .708l-2 2a.5.5 0 0 1-.708-.708L10.293 8 8.646 6.354a.5.5 0 0 1 0-.708zm-1.292 0a.5.5 0 0 0-.708 0l-2 2a.5.5 0 0 0 0 .708l2 2a.5.5 0 0 0 .708-.708L5.707 8l1.647-1.646a.5.5 0 0 0 0-.708z"/><path d="M3 0h10a2 2 0 0 1 2 2v12a2 2 0 0 1-2 2H3a2 2 0 0 1-2-2v-1h1v1a1 1 0 0 0 1 1h10a1 1 0 0 0 1-1V2a1 1 0 0 0-1-1H3a1 1 0 0 0-1 1v1H1V2a2 2 0 0 1 2-2z"/><path d="M1 5v-.5a.5.5 0 0 1 1 0V5h.5a.5.5 0 0 1 0 1h-2a.5.5 0 0 1 0-1H1zm0 3v-.5a.5.5 0 0 1 1 0V8h.5a.5.5 0 0 1 0 1h-2a.5.5 0 0 1 0-1H1zm0 3v-.5a.5.5 0 0 1 1 0v.5h.5a.5.5 0 0 1 0 1h-2a.5.5 0 0 1 0-1H1z"/></svg>');background-repeat:no-repeat;background-size:.75rem .75rem}.toc-actions i.bi,.quarto-code-links i.bi,.quarto-other-links i.bi,.quarto-alternate-notebooks i.bi,.quarto-alternate-formats i.bi{margin-right:.4em;font-size:.8rem}.quarto-other-links-text-target .quarto-code-links i.bi,.quarto-other-links-text-target .quarto-other-links i.bi{margin-right:.2em}.quarto-other-formats-text-target .quarto-alternate-formats i.bi{margin-right:.1em}.toc-actions i.bi.empty,.quarto-code-links i.bi.empty,.quarto-other-links i.bi.empty,.quarto-alternate-notebooks i.bi.empty,.quarto-alternate-formats i.bi.empty{padding-left:1em}.quarto-notebook h2,.quarto-notebook .h2{border-bottom:none}.quarto-notebook .cell-container{display:flex}.quarto-notebook .cell-container .cell{flex-grow:4}.quarto-notebook .cell-container .cell-decorator{padding-top:1.5em;padding-right:1em;text-align:right}.quarto-notebook .cell-container.code-fold .cell-decorator{padding-top:3em}.quarto-notebook .cell-code code{white-space:pre-wrap}.quarto-notebook .cell .cell-output-stderr pre code,.quarto-notebook .cell .cell-output-stdout pre code{white-space:pre-wrap;overflow-wrap:anywhere}.toc-actions,.quarto-alternate-formats,.quarto-other-links,.quarto-code-links,.quarto-alternate-notebooks{padding-left:0em}.sidebar .toc-actions a,.sidebar .quarto-alternate-formats a,.sidebar .quarto-other-links a,.sidebar .quarto-code-links a,.sidebar .quarto-alternate-notebooks a,.sidebar nav[role=doc-toc] a{text-decoration:none}.sidebar .toc-actions a:hover,.sidebar .quarto-other-links a:hover,.sidebar .quarto-code-links a:hover,.sidebar .quarto-alternate-formats a:hover,.sidebar .quarto-alternate-notebooks a:hover{color:#2761e3}.sidebar .toc-actions h2,.sidebar .toc-actions .h2,.sidebar .quarto-code-links h2,.sidebar .quarto-code-links .h2,.sidebar .quarto-other-links h2,.sidebar .quarto-other-links .h2,.sidebar .quarto-alternate-notebooks h2,.sidebar .quarto-alternate-notebooks .h2,.sidebar .quarto-alternate-formats h2,.sidebar .quarto-alternate-formats .h2,.sidebar nav[role=doc-toc]>h2,.sidebar nav[role=doc-toc]>.h2{font-weight:500;margin-bottom:.2rem;margin-top:.3rem;font-family:inherit;border-bottom:0;padding-bottom:0;padding-top:0px}.sidebar .toc-actions>h2,.sidebar .toc-actions>.h2,.sidebar .quarto-code-links>h2,.sidebar .quarto-code-links>.h2,.sidebar .quarto-other-links>h2,.sidebar .quarto-other-links>.h2,.sidebar .quarto-alternate-notebooks>h2,.sidebar .quarto-alternate-notebooks>.h2,.sidebar .quarto-alternate-formats>h2,.sidebar .quarto-alternate-formats>.h2{font-size:.8rem}.sidebar nav[role=doc-toc]>h2,.sidebar nav[role=doc-toc]>.h2{font-size:.875rem}.sidebar nav[role=doc-toc]>ul a{border-left:1px solid #e9ecef;padding-left:.6rem}.sidebar .toc-actions h2>ul a,.sidebar .toc-actions .h2>ul a,.sidebar .quarto-code-links h2>ul a,.sidebar .quarto-code-links .h2>ul a,.sidebar .quarto-other-links h2>ul a,.sidebar .quarto-other-links .h2>ul a,.sidebar .quarto-alternate-notebooks h2>ul a,.sidebar .quarto-alternate-notebooks .h2>ul a,.sidebar .quarto-alternate-formats h2>ul a,.sidebar .quarto-alternate-formats .h2>ul a{border-left:none;padding-left:.6rem}.sidebar .toc-actions ul a:empty,.sidebar .quarto-code-links ul a:empty,.sidebar .quarto-other-links ul a:empty,.sidebar .quarto-alternate-notebooks ul a:empty,.sidebar .quarto-alternate-formats ul a:empty,.sidebar nav[role=doc-toc]>ul a:empty{display:none}.sidebar .toc-actions ul,.sidebar .quarto-code-links ul,.sidebar .quarto-other-links ul,.sidebar .quarto-alternate-notebooks ul,.sidebar .quarto-alternate-formats ul{padding-left:0;list-style:none}.sidebar nav[role=doc-toc] ul{list-style:none;padding-left:0;list-style:none}.sidebar nav[role=doc-toc]>ul{margin-left:.45em}.quarto-margin-sidebar nav[role=doc-toc]{padding-left:.5em}.sidebar .toc-actions>ul,.sidebar .quarto-code-links>ul,.sidebar .quarto-other-links>ul,.sidebar .quarto-alternate-notebooks>ul,.sidebar .quarto-alternate-formats>ul{font-size:.8rem}.sidebar nav[role=doc-toc]>ul{font-size:.875rem}.sidebar .toc-actions ul li a,.sidebar .quarto-code-links ul li a,.sidebar .quarto-other-links ul li a,.sidebar .quarto-alternate-notebooks ul li a,.sidebar .quarto-alternate-formats ul li a,.sidebar nav[role=doc-toc]>ul li a{line-height:1.1rem;padding-bottom:.2rem;padding-top:.2rem;color:inherit}.sidebar nav[role=doc-toc] ul>li>ul>li>a{padding-left:1.2em}.sidebar nav[role=doc-toc] ul>li>ul>li>ul>li>a{padding-left:2.4em}.sidebar nav[role=doc-toc] ul>li>ul>li>ul>li>ul>li>a{padding-left:3.6em}.sidebar nav[role=doc-toc] ul>li>ul>li>ul>li>ul>li>ul>li>a{padding-left:4.8em}.sidebar nav[role=doc-toc] ul>li>ul>li>ul>li>ul>li>ul>li>ul>li>a{padding-left:6em}.sidebar nav[role=doc-toc] ul>li>a.active,.sidebar nav[role=doc-toc] ul>li>ul>li>a.active{border-left:1px solid #2761e3;color:#2761e3 !important}.sidebar nav[role=doc-toc] ul>li>a:hover,.sidebar nav[role=doc-toc] ul>li>ul>li>a:hover{color:#2761e3 !important}kbd,.kbd{color:#343a40;background-color:#f8f9fa;border:1px solid;border-radius:5px;border-color:#dee2e6}.quarto-appendix-contents div.hanging-indent{margin-left:0em}.quarto-appendix-contents div.hanging-indent div.csl-entry{margin-left:1em;text-indent:-1em}.citation a,.footnote-ref{text-decoration:none}.footnotes ol{padding-left:1em}.tippy-content>*{margin-bottom:.7em}.tippy-content>*:last-child{margin-bottom:0}.callout{margin-top:1.25rem;margin-bottom:1.25rem;border-radius:.25rem;overflow-wrap:break-word}.callout .callout-title-container{overflow-wrap:anywhere}.callout.callout-style-simple{padding:.4em .7em;border-left:5px solid;border-right:1px solid #dee2e6;border-top:1px solid #dee2e6;border-bottom:1px solid #dee2e6}.callout.callout-style-default{border-left:5px solid;border-right:1px solid #dee2e6;border-top:1px solid #dee2e6;border-bottom:1px solid #dee2e6}.callout .callout-body-container{flex-grow:1}.callout.callout-style-simple .callout-body{font-size:.9rem;font-weight:400}.callout.callout-style-default .callout-body{font-size:.9rem;font-weight:400}.callout:not(.no-icon).callout-titled.callout-style-simple .callout-body{padding-left:1.6em}.callout.callout-titled>.callout-header{padding-top:.2em;margin-bottom:-0.2em}.callout.callout-style-simple>div.callout-header{border-bottom:none;font-size:.9rem;font-weight:600;opacity:75%}.callout.callout-style-default>div.callout-header{border-bottom:none;font-weight:600;opacity:85%;font-size:.9rem;padding-left:.5em;padding-right:.5em}.callout.callout-style-default .callout-body{padding-left:.5em;padding-right:.5em}.callout.callout-style-default .callout-body>:first-child{padding-top:.5rem;margin-top:0}.callout>div.callout-header[data-bs-toggle=collapse]{cursor:pointer}.callout.callout-style-default .callout-header[aria-expanded=false],.callout.callout-style-default .callout-header[aria-expanded=true]{padding-top:0px;margin-bottom:0px;align-items:center}.callout.callout-titled .callout-body>:last-child:not(.sourceCode),.callout.callout-titled .callout-body>div>:last-child:not(.sourceCode){padding-bottom:.5rem;margin-bottom:0}.callout:not(.callout-titled) .callout-body>:first-child,.callout:not(.callout-titled) .callout-body>div>:first-child{margin-top:.25rem}.callout:not(.callout-titled) .callout-body>:last-child,.callout:not(.callout-titled) .callout-body>div>:last-child{margin-bottom:.2rem}.callout.callout-style-simple .callout-icon::before,.callout.callout-style-simple .callout-toggle::before{height:1rem;width:1rem;display:inline-block;content:"";background-repeat:no-repeat;background-size:1rem 1rem}.callout.callout-style-default .callout-icon::before,.callout.callout-style-default .callout-toggle::before{height:.9rem;width:.9rem;display:inline-block;content:"";background-repeat:no-repeat;background-size:.9rem .9rem}.callout.callout-style-default .callout-toggle::before{margin-top:5px}.callout .callout-btn-toggle .callout-toggle::before{transition:transform .2s linear}.callout .callout-header[aria-expanded=false] .callout-toggle::before{transform:rotate(-90deg)}.callout .callout-header[aria-expanded=true] .callout-toggle::before{transform:none}.callout.callout-style-simple:not(.no-icon) div.callout-icon-container{padding-top:.2em;padding-right:.55em}.callout.callout-style-default:not(.no-icon) div.callout-icon-container{padding-top:.1em;padding-right:.35em}.callout.callout-style-default:not(.no-icon) div.callout-title-container{margin-top:-1px}.callout.callout-style-default.callout-caution:not(.no-icon) div.callout-icon-container{padding-top:.3em;padding-right:.35em}.callout>.callout-body>.callout-icon-container>.no-icon,.callout>.callout-header>.callout-icon-container>.no-icon{display:none}div.callout.callout{border-left-color:#6c757d}div.callout.callout-style-default>.callout-header{background-color:#6c757d}div.callout-note.callout{border-left-color:#2780e3}div.callout-note.callout-style-default>.callout-header{background-color:#e9f2fc}div.callout-note:not(.callout-titled) .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %232373cc" class="bi bi-info-circle" viewBox="0 0 16 16"><path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z"/><path d="m8.93 6.588-2.29.287-.082.38.45.083c.294.07.352.176.288.469l-.738 3.468c-.194.897.105 1.319.808 1.319.545 0 1.178-.252 1.465-.598l.088-.416c-.2.176-.492.246-.686.246-.275 0-.375-.193-.304-.533L8.93 6.588zM9 4.5a1 1 0 1 1-2 0 1 1 0 0 1 2 0z"/></svg>');}div.callout-note.callout-titled .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %232373cc" class="bi bi-info-circle" viewBox="0 0 16 16"><path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z"/><path d="m8.93 6.588-2.29.287-.082.38.45.083c.294.07.352.176.288.469l-.738 3.468c-.194.897.105 1.319.808 1.319.545 0 1.178-.252 1.465-.598l.088-.416c-.2.176-.492.246-.686.246-.275 0-.375-.193-.304-.533L8.93 6.588zM9 4.5a1 1 0 1 1-2 0 1 1 0 0 1 2 0z"/></svg>');}div.callout-note .callout-toggle::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(52, 58, 64)" class="bi bi-chevron-down" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z"/></svg>')}div.callout-tip.callout{border-left-color:#3fb618}div.callout-tip.callout-style-default>.callout-header{background-color:#ecf8e8}div.callout-tip:not(.callout-titled) .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %2339a416" class="bi bi-lightbulb" viewBox="0 0 16 16"><path d="M2 6a6 6 0 1 1 10.174 4.31c-.203.196-.359.4-.453.619l-.762 1.769A.5.5 0 0 1 10.5 13a.5.5 0 0 1 0 1 .5.5 0 0 1 0 1l-.224.447a1 1 0 0 1-.894.553H6.618a1 1 0 0 1-.894-.553L5.5 15a.5.5 0 0 1 0-1 .5.5 0 0 1 0-1 .5.5 0 0 1-.46-.302l-.761-1.77a1.964 1.964 0 0 0-.453-.618A5.984 5.984 0 0 1 2 6zm6-5a5 5 0 0 0-3.479 8.592c.263.254.514.564.676.941L5.83 12h4.342l.632-1.467c.162-.377.413-.687.676-.941A5 5 0 0 0 8 1z"/></svg>');}div.callout-tip.callout-titled .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %2339a416" class="bi bi-lightbulb" viewBox="0 0 16 16"><path d="M2 6a6 6 0 1 1 10.174 4.31c-.203.196-.359.4-.453.619l-.762 1.769A.5.5 0 0 1 10.5 13a.5.5 0 0 1 0 1 .5.5 0 0 1 0 1l-.224.447a1 1 0 0 1-.894.553H6.618a1 1 0 0 1-.894-.553L5.5 15a.5.5 0 0 1 0-1 .5.5 0 0 1 0-1 .5.5 0 0 1-.46-.302l-.761-1.77a1.964 1.964 0 0 0-.453-.618A5.984 5.984 0 0 1 2 6zm6-5a5 5 0 0 0-3.479 8.592c.263.254.514.564.676.941L5.83 12h4.342l.632-1.467c.162-.377.413-.687.676-.941A5 5 0 0 0 8 1z"/></svg>');}div.callout-tip .callout-toggle::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(52, 58, 64)" class="bi bi-chevron-down" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z"/></svg>')}div.callout-warning.callout{border-left-color:#ff7518}div.callout-warning.callout-style-default>.callout-header{background-color:#fff1e8}div.callout-warning:not(.callout-titled) .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %23e66916" class="bi bi-exclamation-triangle" viewBox="0 0 16 16"><path d="M7.938 2.016A.13.13 0 0 1 8.002 2a.13.13 0 0 1 .063.016.146.146 0 0 1 .054.057l6.857 11.667c.036.06.035.124.002.183a.163.163 0 0 1-.054.06.116.116 0 0 1-.066.017H1.146a.115.115 0 0 1-.066-.017.163.163 0 0 1-.054-.06.176.176 0 0 1 .002-.183L7.884 2.073a.147.147 0 0 1 .054-.057zm1.044-.45a1.13 1.13 0 0 0-1.96 0L.165 13.233c-.457.778.091 1.767.98 1.767h13.713c.889 0 1.438-.99.98-1.767L8.982 1.566z"/><path d="M7.002 12a1 1 0 1 1 2 0 1 1 0 0 1-2 0zM7.1 5.995a.905.905 0 1 1 1.8 0l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 5.995z"/></svg>');}div.callout-warning.callout-titled .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %23e66916" class="bi bi-exclamation-triangle" viewBox="0 0 16 16"><path d="M7.938 2.016A.13.13 0 0 1 8.002 2a.13.13 0 0 1 .063.016.146.146 0 0 1 .054.057l6.857 11.667c.036.06.035.124.002.183a.163.163 0 0 1-.054.06.116.116 0 0 1-.066.017H1.146a.115.115 0 0 1-.066-.017.163.163 0 0 1-.054-.06.176.176 0 0 1 .002-.183L7.884 2.073a.147.147 0 0 1 .054-.057zm1.044-.45a1.13 1.13 0 0 0-1.96 0L.165 13.233c-.457.778.091 1.767.98 1.767h13.713c.889 0 1.438-.99.98-1.767L8.982 1.566z"/><path d="M7.002 12a1 1 0 1 1 2 0 1 1 0 0 1-2 0zM7.1 5.995a.905.905 0 1 1 1.8 0l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 5.995z"/></svg>');}div.callout-warning .callout-toggle::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(52, 58, 64)" class="bi bi-chevron-down" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z"/></svg>')}div.callout-caution.callout{border-left-color:#f0ad4e}div.callout-caution.callout-style-default>.callout-header{background-color:#fef7ed}div.callout-caution:not(.callout-titled) .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %23d89c46" class="bi bi-cone-striped" viewBox="0 0 16 16"><path d="M9.97 4.88l.953 3.811C10.158 8.878 9.14 9 8 9c-1.14 0-2.159-.122-2.923-.309L6.03 4.88C6.635 4.957 7.3 5 8 5s1.365-.043 1.97-.12zm-.245-.978L8.97.88C8.718-.13 7.282-.13 7.03.88L6.274 3.9C6.8 3.965 7.382 4 8 4c.618 0 1.2-.036 1.725-.098zm4.396 8.613a.5.5 0 0 1 .037.96l-6 2a.5.5 0 0 1-.316 0l-6-2a.5.5 0 0 1 .037-.96l2.391-.598.565-2.257c.862.212 1.964.339 3.165.339s2.303-.127 3.165-.339l.565 2.257 2.391.598z"/></svg>');}div.callout-caution.callout-titled .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %23d89c46" class="bi bi-cone-striped" viewBox="0 0 16 16"><path d="M9.97 4.88l.953 3.811C10.158 8.878 9.14 9 8 9c-1.14 0-2.159-.122-2.923-.309L6.03 4.88C6.635 4.957 7.3 5 8 5s1.365-.043 1.97-.12zm-.245-.978L8.97.88C8.718-.13 7.282-.13 7.03.88L6.274 3.9C6.8 3.965 7.382 4 8 4c.618 0 1.2-.036 1.725-.098zm4.396 8.613a.5.5 0 0 1 .037.96l-6 2a.5.5 0 0 1-.316 0l-6-2a.5.5 0 0 1 .037-.96l2.391-.598.565-2.257c.862.212 1.964.339 3.165.339s2.303-.127 3.165-.339l.565 2.257 2.391.598z"/></svg>');}div.callout-caution .callout-toggle::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(52, 58, 64)" class="bi bi-chevron-down" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z"/></svg>')}div.callout-important.callout{border-left-color:#ff0039}div.callout-important.callout-style-default>.callout-header{background-color:#ffe6eb}div.callout-important:not(.callout-titled) .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %23e60033" class="bi bi-exclamation-circle" viewBox="0 0 16 16"><path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z"/><path d="M7.002 11a1 1 0 1 1 2 0 1 1 0 0 1-2 0zM7.1 4.995a.905.905 0 1 1 1.8 0l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 4.995z"/></svg>');}div.callout-important.callout-titled .callout-icon::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" style="fill: %23e60033" class="bi bi-exclamation-circle" viewBox="0 0 16 16"><path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z"/><path d="M7.002 11a1 1 0 1 1 2 0 1 1 0 0 1-2 0zM7.1 4.995a.905.905 0 1 1 1.8 0l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 4.995z"/></svg>');}div.callout-important .callout-toggle::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(52, 58, 64)" class="bi bi-chevron-down" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z"/></svg>')}.quarto-toggle-container{display:flex;align-items:center}.quarto-reader-toggle .bi::before,.quarto-color-scheme-toggle .bi::before{display:inline-block;height:1rem;width:1rem;content:"";background-repeat:no-repeat;background-size:1rem 1rem}.sidebar-navigation{padding-left:20px}.navbar{background-color:#f8f9fa;color:#545555}.navbar .quarto-color-scheme-toggle:not(.alternate) .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(84, 85, 85, 1)" class="bi bi-toggle-off" viewBox="0 0 16 16"><path d="M11 4a4 4 0 0 1 0 8H8a4.992 4.992 0 0 0 2-4 4.992 4.992 0 0 0-2-4h3zm-6 8a4 4 0 1 1 0-8 4 4 0 0 1 0 8zM0 8a5 5 0 0 0 5 5h6a5 5 0 0 0 0-10H5a5 5 0 0 0-5 5z"/></svg>')}.navbar .quarto-color-scheme-toggle.alternate .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(84, 85, 85, 1)" class="bi bi-toggle-on" viewBox="0 0 16 16"><path d="M5 3a5 5 0 0 0 0 10h6a5 5 0 0 0 0-10H5zm6 9a4 4 0 1 1 0-8 4 4 0 0 1 0 8z"/></svg>')}.sidebar-navigation .quarto-color-scheme-toggle:not(.alternate) .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(75, 84, 92, 1)" class="bi bi-toggle-off" viewBox="0 0 16 16"><path d="M11 4a4 4 0 0 1 0 8H8a4.992 4.992 0 0 0 2-4 4.992 4.992 0 0 0-2-4h3zm-6 8a4 4 0 1 1 0-8 4 4 0 0 1 0 8zM0 8a5 5 0 0 0 5 5h6a5 5 0 0 0 0-10H5a5 5 0 0 0-5 5z"/></svg>')}.sidebar-navigation .quarto-color-scheme-toggle.alternate .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(75, 84, 92, 1)" class="bi bi-toggle-on" viewBox="0 0 16 16"><path d="M5 3a5 5 0 0 0 0 10h6a5 5 0 0 0 0-10H5zm6 9a4 4 0 1 1 0-8 4 4 0 0 1 0 8z"/></svg>')}.quarto-sidebar-toggle{border-color:#dee2e6;border-bottom-left-radius:.25rem;border-bottom-right-radius:.25rem;border-style:solid;border-width:1px;overflow:hidden;border-top-width:0px;padding-top:0px !important}.quarto-sidebar-toggle-title{cursor:pointer;padding-bottom:2px;margin-left:.25em;text-align:center;font-weight:400;font-size:.775em}#quarto-content .quarto-sidebar-toggle{background:#fafafa}#quarto-content .quarto-sidebar-toggle-title{color:#343a40}.quarto-sidebar-toggle-icon{color:#dee2e6;margin-right:.5em;float:right;transition:transform .2s ease}.quarto-sidebar-toggle-icon::before{padding-top:5px}.quarto-sidebar-toggle.expanded .quarto-sidebar-toggle-icon{transform:rotate(-180deg)}.quarto-sidebar-toggle.expanded .quarto-sidebar-toggle-title{border-bottom:solid #dee2e6 1px}.quarto-sidebar-toggle-contents{background-color:#fff;padding-right:10px;padding-left:10px;margin-top:0px !important;transition:max-height .5s ease}.quarto-sidebar-toggle.expanded .quarto-sidebar-toggle-contents{padding-top:1em;padding-bottom:10px}@media(max-width: 767.98px){.sidebar-menu-container{padding-bottom:5em}}.quarto-sidebar-toggle:not(.expanded) .quarto-sidebar-toggle-contents{padding-top:0px !important;padding-bottom:0px}nav[role=doc-toc]{z-index:1020}#quarto-sidebar>*,nav[role=doc-toc]>*{transition:opacity .1s ease,border .1s ease}#quarto-sidebar.slow>*,nav[role=doc-toc].slow>*{transition:opacity .4s ease,border .4s ease}.quarto-color-scheme-toggle:not(.alternate).top-right .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(136, 147, 158, 1)" class="bi bi-toggle-off" viewBox="0 0 16 16"><path d="M11 4a4 4 0 0 1 0 8H8a4.992 4.992 0 0 0 2-4 4.992 4.992 0 0 0-2-4h3zm-6 8a4 4 0 1 1 0-8 4 4 0 0 1 0 8zM0 8a5 5 0 0 0 5 5h6a5 5 0 0 0 0-10H5a5 5 0 0 0-5 5z"/></svg>')}.quarto-color-scheme-toggle.alternate.top-right .bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgba(98, 109, 120, 1)" class="bi bi-toggle-on" viewBox="0 0 16 16"><path d="M5 3a5 5 0 0 0 0 10h6a5 5 0 0 0 0-10H5zm6 9a4 4 0 1 1 0-8 4 4 0 0 1 0 8z"/></svg>')}#quarto-appendix.default{border-top:1px solid #dee2e6}#quarto-appendix.default{background-color:#fff;padding-top:1.5em;margin-top:2em;z-index:998}#quarto-appendix.default .quarto-appendix-heading{margin-top:0;line-height:1.4em;font-weight:600;opacity:.9;border-bottom:none;margin-bottom:0}#quarto-appendix.default .footnotes ol,#quarto-appendix.default .footnotes ol li>p:last-of-type,#quarto-appendix.default .quarto-appendix-contents>p:last-of-type{margin-bottom:0}#quarto-appendix.default .footnotes ol{margin-left:.5em}#quarto-appendix.default .quarto-appendix-secondary-label{margin-bottom:.4em}#quarto-appendix.default .quarto-appendix-bibtex{font-size:.7em;padding:1em;border:solid 1px #dee2e6;margin-bottom:1em}#quarto-appendix.default .quarto-appendix-bibtex code.sourceCode{white-space:pre-wrap}#quarto-appendix.default .quarto-appendix-citeas{font-size:.9em;padding:1em;border:solid 1px #dee2e6;margin-bottom:1em}#quarto-appendix.default .quarto-appendix-heading{font-size:1em !important}#quarto-appendix.default *[role=doc-endnotes]>ol,#quarto-appendix.default .quarto-appendix-contents>*:not(h2):not(.h2){font-size:.9em}#quarto-appendix.default section{padding-bottom:1.5em}#quarto-appendix.default section *[role=doc-endnotes],#quarto-appendix.default section>*:not(a){opacity:.9;word-wrap:break-word}.btn.btn-quarto,div.cell-output-display .btn-quarto{--bs-btn-color: #cacccd;--bs-btn-bg: #343a40;--bs-btn-border-color: #343a40;--bs-btn-hover-color: #cacccd;--bs-btn-hover-bg: #52585d;--bs-btn-hover-border-color: #484e53;--bs-btn-focus-shadow-rgb: 75, 80, 85;--bs-btn-active-color: #fff;--bs-btn-active-bg: #5d6166;--bs-btn-active-border-color: #484e53;--bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);--bs-btn-disabled-color: #fff;--bs-btn-disabled-bg: #343a40;--bs-btn-disabled-border-color: #343a40}nav.quarto-secondary-nav.color-navbar{background-color:#f8f9fa;color:#545555}nav.quarto-secondary-nav.color-navbar h1,nav.quarto-secondary-nav.color-navbar .h1,nav.quarto-secondary-nav.color-navbar .quarto-btn-toggle{color:#545555}@media(max-width: 991.98px){body.nav-sidebar .quarto-title-banner{margin-bottom:0;padding-bottom:1em}body.nav-sidebar #title-block-header{margin-block-end:0}}p.subtitle{margin-top:.25em;margin-bottom:.5em}code a:any-link{color:inherit;text-decoration-color:#6c757d}/*! light */div.observablehq table thead tr th{background-color:var(--bs-body-bg)}input,button,select,optgroup,textarea{background-color:var(--bs-body-bg)}.code-annotated .code-copy-button{margin-right:1.25em;margin-top:0;padding-bottom:0;padding-top:3px}.code-annotation-gutter-bg{background-color:#fff}.code-annotation-gutter{background-color:rgba(233,236,239,.65)}.code-annotation-gutter,.code-annotation-gutter-bg{height:100%;width:calc(20px + .5em);position:absolute;top:0;right:0}dl.code-annotation-container-grid dt{margin-right:1em;margin-top:.25rem}dl.code-annotation-container-grid dt{font-family:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace;color:#4b545c;border:solid #4b545c 1px;border-radius:50%;height:22px;width:22px;line-height:22px;font-size:11px;text-align:center;vertical-align:middle;text-decoration:none}dl.code-annotation-container-grid dt[data-target-cell]{cursor:pointer}dl.code-annotation-container-grid dt[data-target-cell].code-annotation-active{color:#fff;border:solid #aaa 1px;background-color:#aaa}pre.code-annotation-code{padding-top:0;padding-bottom:0}pre.code-annotation-code code{z-index:3}#code-annotation-line-highlight-gutter{width:100%;border-top:solid rgba(170,170,170,.2666666667) 1px;border-bottom:solid rgba(170,170,170,.2666666667) 1px;z-index:2;background-color:rgba(170,170,170,.1333333333)}#code-annotation-line-highlight{margin-left:-4em;width:calc(100% + 4em);border-top:solid rgba(170,170,170,.2666666667) 1px;border-bottom:solid rgba(170,170,170,.2666666667) 1px;z-index:2;background-color:rgba(170,170,170,.1333333333)}code.sourceCode .code-annotation-anchor.code-annotation-active{background-color:var(--quarto-hl-normal-color, #aaaaaa);border:solid var(--quarto-hl-normal-color, #aaaaaa) 1px;color:#e9ecef;font-weight:bolder}code.sourceCode .code-annotation-anchor{font-family:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace;color:var(--quarto-hl-co-color);border:solid var(--quarto-hl-co-color) 1px;border-radius:50%;height:18px;width:18px;font-size:9px;margin-top:2px}code.sourceCode button.code-annotation-anchor{padding:2px;user-select:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;-o-user-select:none}code.sourceCode a.code-annotation-anchor{line-height:18px;text-align:center;vertical-align:middle;cursor:default;text-decoration:none}@media print{.page-columns .column-screen-inset{grid-column:page-start-inset/page-end-inset;z-index:998;opacity:.999}.page-columns .column-screen-inset table{background:#fff}.page-columns .column-screen-inset-left{grid-column:page-start-inset/body-content-end;z-index:998;opacity:.999}.page-columns .column-screen-inset-left table{background:#fff}.page-columns .column-screen-inset-right{grid-column:body-content-start/page-end-inset;z-index:998;opacity:.999}.page-columns .column-screen-inset-right table{background:#fff}.page-columns .column-screen{grid-column:page-start/page-end;z-index:998;opacity:.999}.page-columns .column-screen table{background:#fff}.page-columns .column-screen-left{grid-column:page-start/body-content-end;z-index:998;opacity:.999}.page-columns .column-screen-left table{background:#fff}.page-columns .column-screen-right{grid-column:body-content-start/page-end;z-index:998;opacity:.999}.page-columns .column-screen-right table{background:#fff}.page-columns .column-screen-inset-shaded{grid-column:page-start-inset/page-end-inset;padding:1em;background:#f8f9fa;z-index:998;opacity:.999;margin-bottom:1em}}.quarto-video{margin-bottom:1em}.table{border-top:1px solid #ebedee;border-bottom:1px solid #ebedee}.table>thead{border-top-width:0;border-bottom:1px solid #b2bac1}.table a{word-break:break-word}.table>:not(caption)>*>*{background-color:unset;color:unset}#quarto-document-content .crosstalk-input .checkbox input[type=checkbox],#quarto-document-content .crosstalk-input .checkbox-inline input[type=checkbox]{position:unset;margin-top:unset;margin-left:unset}#quarto-document-content .row{margin-left:unset;margin-right:unset}.quarto-xref{white-space:nowrap}a.external:after{content:"";background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(39, 97, 227)" class="bi bi-box-arrow-up-right" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8.636 3.5a.5.5 0 0 0-.5-.5H1.5A1.5 1.5 0 0 0 0 4.5v10A1.5 1.5 0 0 0 1.5 16h10a1.5 1.5 0 0 0 1.5-1.5V7.864a.5.5 0 0 0-1 0V14.5a.5.5 0 0 1-.5.5h-10a.5.5 0 0 1-.5-.5v-10a.5.5 0 0 1 .5-.5h6.636a.5.5 0 0 0 .5-.5z"/><path fill-rule="evenodd" d="M16 .5a.5.5 0 0 0-.5-.5h-5a.5.5 0 0 0 0 1h3.793L6.146 9.146a.5.5 0 1 0 .708.708L15 1.707V5.5a.5.5 0 0 0 1 0v-5z"/></svg>');background-size:contain;background-repeat:no-repeat;background-position:center center;margin-left:.2em;padding-right:.75em}div.sourceCode code a.external:after{content:none}a.external:after:hover{cursor:pointer}.quarto-ext-icon{display:inline-block;font-size:.75em;padding-left:.3em}.code-with-filename .code-with-filename-file{margin-bottom:0;padding-bottom:2px;padding-top:2px;padding-left:.7em;border:var(--quarto-border-width) solid var(--quarto-border-color);border-radius:var(--quarto-border-radius);border-bottom:0;border-bottom-left-radius:0%;border-bottom-right-radius:0%}.code-with-filename div.sourceCode,.reveal .code-with-filename div.sourceCode{margin-top:0;border-top-left-radius:0%;border-top-right-radius:0%}.code-with-filename .code-with-filename-file pre{margin-bottom:0}.code-with-filename .code-with-filename-file{background-color:rgba(219,219,219,.8)}.quarto-dark .code-with-filename .code-with-filename-file{background-color:#555}.code-with-filename .code-with-filename-file strong{font-weight:400}.quarto-title-banner{margin-bottom:1em;color:#545555;background:#f8f9fa}.quarto-title-banner a{color:#545555}.quarto-title-banner h1,.quarto-title-banner .h1,.quarto-title-banner h2,.quarto-title-banner .h2{color:#545555}.quarto-title-banner .code-tools-button{color:#878888}.quarto-title-banner .code-tools-button:hover{color:#545555}.quarto-title-banner .code-tools-button>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(135, 136, 136)" viewBox="0 0 16 16"><path d="M10.478 1.647a.5.5 0 1 0-.956-.294l-4 13a.5.5 0 0 0 .956.294l4-13zM4.854 4.146a.5.5 0 0 1 0 .708L1.707 8l3.147 3.146a.5.5 0 0 1-.708.708l-3.5-3.5a.5.5 0 0 1 0-.708l3.5-3.5a.5.5 0 0 1 .708 0zm6.292 0a.5.5 0 0 0 0 .708L14.293 8l-3.147 3.146a.5.5 0 0 0 .708.708l3.5-3.5a.5.5 0 0 0 0-.708l-3.5-3.5a.5.5 0 0 0-.708 0z"/></svg>')}.quarto-title-banner .code-tools-button:hover>.bi::before{background-image:url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="rgb(84, 85, 85)" viewBox="0 0 16 16"><path d="M10.478 1.647a.5.5 0 1 0-.956-.294l-4 13a.5.5 0 0 0 .956.294l4-13zM4.854 4.146a.5.5 0 0 1 0 .708L1.707 8l3.147 3.146a.5.5 0 0 1-.708.708l-3.5-3.5a.5.5 0 0 1 0-.708l3.5-3.5a.5.5 0 0 1 .708 0zm6.292 0a.5.5 0 0 0 0 .708L14.293 8l-3.147 3.146a.5.5 0 0 0 .708.708l3.5-3.5a.5.5 0 0 0 0-.708l-3.5-3.5a.5.5 0 0 0-.708 0z"/></svg>')}.quarto-title-banner .quarto-title .title{font-weight:600}.quarto-title-banner .quarto-categories{margin-top:.75em}@media(min-width: 992px){.quarto-title-banner{padding-top:2.5em;padding-bottom:2.5em}}@media(max-width: 991.98px){.quarto-title-banner{padding-top:1em;padding-bottom:1em}}@media(max-width: 767.98px){body.hypothesis-enabled #title-block-header>*{padding-right:20px}}main.quarto-banner-title-block>section:first-child>h2,main.quarto-banner-title-block>section:first-child>.h2,main.quarto-banner-title-block>section:first-child>h3,main.quarto-banner-title-block>section:first-child>.h3,main.quarto-banner-title-block>section:first-child>h4,main.quarto-banner-title-block>section:first-child>.h4{margin-top:0}.quarto-title .quarto-categories{display:flex;flex-wrap:wrap;row-gap:.5em;column-gap:.4em;padding-bottom:.5em;margin-top:.75em}.quarto-title .quarto-categories .quarto-category{padding:.25em .75em;font-size:.65em;text-transform:uppercase;border:solid 1px;border-radius:.25rem;opacity:.6}.quarto-title .quarto-categories .quarto-category a{color:inherit}.quarto-title-meta-container{display:grid;grid-template-columns:1fr auto}.quarto-title-meta-column-end{display:flex;flex-direction:column;padding-left:1em}.quarto-title-meta-column-end a .bi{margin-right:.3em}#title-block-header.quarto-title-block.default .quarto-title-meta{display:grid;grid-template-columns:minmax(max-content, 1fr) 1fr;grid-column-gap:1em}#title-block-header.quarto-title-block.default .quarto-title .title{margin-bottom:0}#title-block-header.quarto-title-block.default .quarto-title-author-orcid img{margin-top:-0.2em;height:.8em;width:.8em}#title-block-header.quarto-title-block.default .quarto-title-author-email{opacity:.7}#title-block-header.quarto-title-block.default .quarto-description p:last-of-type{margin-bottom:0}#title-block-header.quarto-title-block.default .quarto-title-meta-contents p,#title-block-header.quarto-title-block.default .quarto-title-authors p,#title-block-header.quarto-title-block.default .quarto-title-affiliations p{margin-bottom:.1em}#title-block-header.quarto-title-block.default .quarto-title-meta-heading{text-transform:uppercase;margin-top:1em;font-size:.8em;opacity:.8;font-weight:400}#title-block-header.quarto-title-block.default .quarto-title-meta-contents{font-size:.9em}#title-block-header.quarto-title-block.default .quarto-title-meta-contents p.affiliation:last-of-type{margin-bottom:.1em}#title-block-header.quarto-title-block.default p.affiliation{margin-bottom:.1em}#title-block-header.quarto-title-block.default .keywords,#title-block-header.quarto-title-block.default .description,#title-block-header.quarto-title-block.default .abstract{margin-top:0}#title-block-header.quarto-title-block.default .keywords>p,#title-block-header.quarto-title-block.default .description>p,#title-block-header.quarto-title-block.default .abstract>p{font-size:.9em}#title-block-header.quarto-title-block.default .keywords>p:last-of-type,#title-block-header.quarto-title-block.default .description>p:last-of-type,#title-block-header.quarto-title-block.default .abstract>p:last-of-type{margin-bottom:0}#title-block-header.quarto-title-block.default .keywords .block-title,#title-block-header.quarto-title-block.default .description .block-title,#title-block-header.quarto-title-block.default .abstract .block-title{margin-top:1em;text-transform:uppercase;font-size:.8em;opacity:.8;font-weight:400}#title-block-header.quarto-title-block.default .quarto-title-meta-author{display:grid;grid-template-columns:minmax(max-content, 1fr) 1fr;grid-column-gap:1em}.quarto-title-tools-only{display:flex;justify-content:right}body{-webkit-font-smoothing:antialiased}.badge.bg-light{color:#343a40}.progress .progress-bar{font-size:8px;line-height:8px}
diff --git a/docs/site_libs/quarto-html/quarto.js b/docs/site_libs/quarto-html/quarto.js
index 39e68699..3ebd49cb 100644
--- a/docs/site_libs/quarto-html/quarto.js
+++ b/docs/site_libs/quarto-html/quarto.js
@@ -94,7 +94,7 @@ window.document.addEventListener("DOMContentLoaded", function (_event) {
       if (link.href.indexOf("#") !== -1) {
         const anchor = link.href.split("#")[1];
         const heading = window.document.querySelector(
-          `[data-anchor-id="${anchor}"]`
+          `[data-anchor-id=${anchor}]`
         );
         if (heading) {
           // Add the class
@@ -134,10 +134,8 @@ window.document.addEventListener("DOMContentLoaded", function (_event) {
       window.innerHeight + window.pageYOffset >=
       window.document.body.offsetHeight
     ) {
-      // This is the no-scroll case where last section should be the active one
       sectionIndex = 0;
     } else {
-      // This finds the last section visible on screen that should be made active
       sectionIndex = [...sections].reverse().findIndex((section) => {
         if (section) {
           return window.pageYOffset >= section.offsetTop - sectionMargin;
@@ -319,7 +317,6 @@ window.document.addEventListener("DOMContentLoaded", function (_event) {
           for (const child of el.children) {
             child.style.opacity = 0;
             child.style.overflow = "hidden";
-            child.style.pointerEvents = "none";
           }
 
           nexttick(() => {
@@ -361,7 +358,6 @@ window.document.addEventListener("DOMContentLoaded", function (_event) {
 
               const clone = child.cloneNode(true);
               clone.style.opacity = 1;
-              clone.style.pointerEvents = null;
               clone.style.display = null;
               toggleContents.append(clone);
             }
@@ -436,7 +432,6 @@ window.document.addEventListener("DOMContentLoaded", function (_event) {
           for (const child of el.children) {
             child.style.opacity = 1;
             child.style.overflow = null;
-            child.style.pointerEvents = null;
           }
 
           const placeholderEl = window.document.getElementById(
@@ -744,7 +739,6 @@ window.document.addEventListener("DOMContentLoaded", function (_event) {
     // Process the collapse state if this is an UL
     if (el.tagName === "UL") {
       if (tocOpenDepth === -1 && depth > 1) {
-        // toc-expand: false
         el.classList.add("collapse");
       } else if (
         depth <= tocOpenDepth ||
@@ -763,9 +757,10 @@ window.document.addEventListener("DOMContentLoaded", function (_event) {
   };
 
   // walk the TOC and expand / collapse any items that should be shown
+
   if (tocEl) {
-    updateActiveLink();
     walk(tocEl, 0);
+    updateActiveLink();
   }
 
   // Throttle the scroll event and walk peridiocally
@@ -784,10 +779,6 @@ window.document.addEventListener("DOMContentLoaded", function (_event) {
   window.addEventListener(
     "resize",
     throttle(() => {
-      if (tocEl) {
-        updateActiveLink();
-        walk(tocEl, 0);
-      }
       if (!isReaderMode()) {
         hideOverlappedSidebars();
       }
diff --git a/docs/site_libs/quarto-nav/quarto-nav.js b/docs/site_libs/quarto-nav/quarto-nav.js
index 38cc4305..f6a53b10 100644
--- a/docs/site_libs/quarto-nav/quarto-nav.js
+++ b/docs/site_libs/quarto-nav/quarto-nav.js
@@ -5,45 +5,9 @@ const headroomChanged = new CustomEvent("quarto-hrChanged", {
   composed: false,
 });
 
-const announceDismiss = () => {
-  const annEl = window.document.getElementById("quarto-announcement");
-  if (annEl) {
-    annEl.remove();
-
-    const annId = annEl.getAttribute("data-announcement-id");
-    window.localStorage.setItem(`quarto-announce-${annId}`, "true");
-  }
-};
-
-const announceRegister = () => {
-  const annEl = window.document.getElementById("quarto-announcement");
-  if (annEl) {
-    const annId = annEl.getAttribute("data-announcement-id");
-    const isDismissed =
-      window.localStorage.getItem(`quarto-announce-${annId}`) || false;
-    if (isDismissed) {
-      announceDismiss();
-      return;
-    } else {
-      annEl.classList.remove("hidden");
-    }
-
-    const actionEl = annEl.querySelector(".quarto-announcement-action");
-    if (actionEl) {
-      actionEl.addEventListener("click", function (e) {
-        e.preventDefault();
-        // Hide the bar immediately
-        announceDismiss();
-      });
-    }
-  }
-};
-
 window.document.addEventListener("DOMContentLoaded", function () {
   let init = false;
 
-  announceRegister();
-
   // Manage the back to top button, if one is present.
   let lastScrollTop = window.pageYOffset || document.documentElement.scrollTop;
   const scrollDownBuffer = 5;
diff --git a/docs/site_libs/quarto-search/quarto-search.js b/docs/site_libs/quarto-search/quarto-search.js
index d788a958..5f723d72 100644
--- a/docs/site_libs/quarto-search/quarto-search.js
+++ b/docs/site_libs/quarto-search/quarto-search.js
@@ -1275,11 +1275,7 @@ async function fuseSearch(query, fuse, fuseOptions) {
 
   // If we don't have a subfuse and the query is long enough, go ahead
   // and create a subfuse to use for subsequent queries
-  if (
-    now - then > kFuseMaxWait &&
-    subSearchFuse === undefined &&
-    resultsRaw.length < fuseOptions.limit
-  ) {
+  if (now - then > kFuseMaxWait && subSearchFuse === undefined) {
     subSearchTerm = query;
     subSearchFuse = new window.Fuse([], kFuseIndexOptions);
     resultsRaw.forEach((rr) => {
diff --git a/flake.lock b/flake.lock
new file mode 100644
index 00000000..2468070f
--- /dev/null
+++ b/flake.lock
@@ -0,0 +1,61 @@
+{
+  "nodes": {
+    "flake-utils": {
+      "inputs": {
+        "systems": "systems"
+      },
+      "locked": {
+        "lastModified": 1731533236,
+        "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1735563628,
+        "narHash": "sha256-OnSAY7XDSx7CtDoqNh8jwVwh4xNL/2HaJxGjryLWzX8=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "b134951a4c9f3c995fd7be05f3243f8ecd65d798",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-24.05",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "flake-utils": "flake-utils",
+        "nixpkgs": "nixpkgs"
+      }
+    },
+    "systems": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

From d849ed0ca71c6f77b77128df2d2a2194a6b6ce40 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sun, 25 May 2025 20:16:12 -0300
Subject: [PATCH 135/151] Add pandoc desc

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 8d934611..249cc212 100644
--- a/README.md
+++ b/README.md
@@ -103,7 +103,7 @@ First of all, you need to care about the dependencies of the project. This book
 
 1. The [Zig compiler](https://ziglang.org/download/), which is responsible for compiling most of the code examples exposed in the book.
 2. The [R programming language](https://cran.r-project.org/), which provides some useful tools, specially `knitr` and `rmarkdown`, which are responsible for collecting the code examples exposed across the book, and sending them to the zig compiler to be compiled and executed, and also, collecting the results back to include them in the book.
-3. The [Quarto publishing system](https://quarto.org/docs/get-started/), which is responsible for compiling the book, creating internal links, references, a chapters structure, the HTML content of the book, etc.
+3. The [Quarto publishing system](https://quarto.org/docs/get-started/), which is responsible for compiling the book, creating internal links, references, a chapters structure, the HTML content of the book. It does all of that by using the amazing [Pandoc](https://pandoc.org/) with some extra features implemented by Quarto.
 
 So, installing these three pieces of software (Zig, R, Quarto) in your current machine is the first step to build the book.
 There are two strategies that you can take here:

From 764ad33a97d31e734fae86c2b99d8ecea400e679 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Sun, 25 May 2025 21:00:14 -0300
Subject: [PATCH 136/151] Fix zig package in Nix Flake and also add @bengtfrost
 to contributors

---
 _freeze/index/execute-results/html.json |  2 +-
 contributors.txt                        |  1 +
 docs/index.html                         |  8 +--
 docs/search.json                        |  4 +-
 flake.lock                              | 88 ++++++++++++++++++++++++-
 flake.nix                               | 12 ++--
 6 files changed, 103 insertions(+), 12 deletions(-)

diff --git a/_freeze/index/execute-results/html.json b/_freeze/index/execute-results/html.json
index 9e805cf2..f43fa582 100644
--- a/_freeze/index/execute-results/html.json
+++ b/_freeze/index/execute-results/html.json
@@ -2,7 +2,7 @@
   "hash": "0b80ffe49bae68e2641a31569b9e19df",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy a PDF, eBook or a physical copy\nof the book, either at Amazon, or at Leanpub:\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://leanpub.com/introductiontozigaproject-basedbook\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Leanpub!\n    </button>\n</a>\n\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e., open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.\nCurrently, he is a Senior Data Engineer at [DSM-Firmenich](https://www.dsm-firmenich.com)[^dsm], and\na Databricks Certified Associate Developer for Apache Spark 3.0.\n\n[^dsm]: <https://www.dsm-firmenich.com>\n\n\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nBrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer who loves to learn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2025 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n\n- System version: Linux, 6.11.0-21-generic, 24.04.1-Ubuntu, x86_64.\n- Zig version: 0.14.0-dev.3046+08d661fcf.\n- Quarto version: 1.5.57.\n\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang), Tommaso Ricci (\\@Zorgatone), Primo Sabatini (\\@primos63), Santiago Fernandez (\\@santif), Hamza Wahed (\\@HamzaWahed), mwilbur (\\@mwilbur), Dima Budaragin (\\@dbud), Jorge Jímenez (\\@jorge-j1m), Alexander (\\@alexwheezy), Maarten Coopens (\\@maarteNNNN), Niklas Johansson (\\@Raphexion), glystik (\\@glystik), Michael Lynch (\\@mtlynch), Yashank (\\@stickyburn)\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy a PDF, eBook or a physical copy\nof the book, either at Amazon, or at Leanpub:\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://leanpub.com/introductiontozigaproject-basedbook\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Leanpub!\n    </button>\n</a>\n\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e., open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.\nCurrently, he is a Senior Data Engineer at [DSM-Firmenich](https://www.dsm-firmenich.com)[^dsm], and\na Databricks Certified Associate Developer for Apache Spark 3.0.\n\n[^dsm]: <https://www.dsm-firmenich.com>\n\n\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nBrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer who loves to learn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2025 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n- System version: Linux, 6.12.21-4-MANJARO, NA, x86_64.\n- Zig version: 0.15.0-dev.635+7dbd21bd5.\n- Quarto version: 1.4.554.\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang), Tommaso Ricci (\\@Zorgatone), Primo Sabatini (\\@primos63), Santiago Fernandez (\\@santif), Hamza Wahed (\\@HamzaWahed), mwilbur (\\@mwilbur), Dima Budaragin (\\@dbud), Jorge Jímenez (\\@jorge-j1m), Alexander (\\@alexwheezy), Maarten Coopens (\\@maarteNNNN), Niklas Johansson (\\@Raphexion), glystik (\\@glystik), Michael Lynch (\\@mtlynch), Yashank (\\@stickyburn), _blf_ (\\@bengtfrost)\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
diff --git a/contributors.txt b/contributors.txt
index 73ae3ac2..e6f0f030 100644
--- a/contributors.txt
+++ b/contributors.txt
@@ -25,3 +25,4 @@ Niklas Johansson,@Raphexion
 glystik,@glystik
 Michael Lynch,@mtlynch
 Yashank,@stickyburn
+_blf_,@bengtfrost
diff --git a/docs/index.html b/docs/index.html
index 224b605c..be6ab3c0 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -426,9 +426,9 @@ <h2 class="unnumbered anchored" data-anchor-id="license">License</h2>
 <h2 class="unnumbered anchored" data-anchor-id="book-compilation-metadata">Book compilation metadata</h2>
 <p>This book was compiled using the following versions of <a href="https://ziglang.org">Zig</a> and <a href="https://quarto.org">Quarto</a>:</p>
 <ul>
-<li>System version: Linux, 6.11.0-21-generic, 24.04.1-Ubuntu, x86_64.</li>
-<li>Zig version: 0.14.0-dev.3046+08d661fcf.</li>
-<li>Quarto version: 1.5.57.</li>
+<li>System version: Linux, 6.12.21-4-MANJARO, NA, x86_64.</li>
+<li>Zig version: 0.15.0-dev.635+7dbd21bd5.</li>
+<li>Quarto version: 1.4.554.</li>
 </ul>
 </section>
 <section id="book-citation" class="level2 unnumbered">
@@ -454,7 +454,7 @@ <h2 class="unnumbered anchored" data-anchor-id="corresponding-author-and-maintai
 <section id="acknowledgments" class="level2 unnumbered">
 <h2 class="unnumbered anchored" data-anchor-id="acknowledgments">Acknowledgments</h2>
 <p>This book is also a product of many conversations and exchanges that we had with different people from the Zig community. I (Pedro Duarte Faria) am incredibly grateful for these conversations, and also, for some direct contributions that we had. Below we have a list of the people involved (name of the person with their usename in GitHub):</p>
-<p>Calin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang), Tommaso Ricci (@Zorgatone), Primo Sabatini (@primos63), Santiago Fernandez (@santif), Hamza Wahed (@HamzaWahed), mwilbur (@mwilbur), Dima Budaragin (@dbud), Jorge Jímenez (@jorge-j1m), Alexander (@alexwheezy), Maarten Coopens (@maarteNNNN), Niklas Johansson (@Raphexion), glystik (@glystik), Michael Lynch (@mtlynch), Yashank (@stickyburn)</p>
+<p>Calin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang), Tommaso Ricci (@Zorgatone), Primo Sabatini (@primos63), Santiago Fernandez (@santif), Hamza Wahed (@HamzaWahed), mwilbur (@mwilbur), Dima Budaragin (@dbud), Jorge Jímenez (@jorge-j1m), Alexander (@alexwheezy), Maarten Coopens (@maarteNNNN), Niklas Johansson (@Raphexion), glystik (@glystik), Michael Lynch (@mtlynch), Yashank (@stickyburn), <em>blf</em> (@bengtfrost)</p>
 
 
 </section>
diff --git a/docs/search.json b/docs/search.json
index fbcaa66e..9fb32b5e 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -54,7 +54,7 @@
     "href": "index.html#book-compilation-metadata",
     "title": "Introduction to Zig",
     "section": "Book compilation metadata",
-    "text": "Book compilation metadata\nThis book was compiled using the following versions of Zig and Quarto:\n\nSystem version: Linux, 6.11.0-21-generic, 24.04.1-Ubuntu, x86_64.\nZig version: 0.14.0-dev.3046+08d661fcf.\nQuarto version: 1.5.57.",
+    "text": "Book compilation metadata\nThis book was compiled using the following versions of Zig and Quarto:\n\nSystem version: Linux, 6.12.21-4-MANJARO, NA, x86_64.\nZig version: 0.15.0-dev.635+7dbd21bd5.\nQuarto version: 1.4.554.",
     "crumbs": [
       "Welcome"
     ]
@@ -84,7 +84,7 @@
     "href": "index.html#acknowledgments",
     "title": "Introduction to Zig",
     "section": "Acknowledgments",
-    "text": "Acknowledgments\nThis book is also a product of many conversations and exchanges that we had with different people from the Zig community. I (Pedro Duarte Faria) am incredibly grateful for these conversations, and also, for some direct contributions that we had. Below we have a list of the people involved (name of the person with their usename in GitHub):\nCalin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang), Tommaso Ricci (@Zorgatone), Primo Sabatini (@primos63), Santiago Fernandez (@santif), Hamza Wahed (@HamzaWahed), mwilbur (@mwilbur), Dima Budaragin (@dbud), Jorge Jímenez (@jorge-j1m), Alexander (@alexwheezy), Maarten Coopens (@maarteNNNN), Niklas Johansson (@Raphexion), glystik (@glystik), Michael Lynch (@mtlynch), Yashank (@stickyburn)",
+    "text": "Acknowledgments\nThis book is also a product of many conversations and exchanges that we had with different people from the Zig community. I (Pedro Duarte Faria) am incredibly grateful for these conversations, and also, for some direct contributions that we had. Below we have a list of the people involved (name of the person with their usename in GitHub):\nCalin Martinconi (@martinconic), Steffen Roller (@sroller), Chris Boesch (@chrboesch), Lv Sihan (@Pokryton), saurabh sharma. (@esskayesss), slackline (@slackline), Markus Kurz (@kurz-m), Rubin Simons (@rubin55), Chris Boesch (@chrboesch), Bruno (@PoorlyDefinedBehaviour), Ilia Choly (@icholy), Korri Katti (@KorryKatti), Vedang Manerikar (@vedang), Tommaso Ricci (@Zorgatone), Primo Sabatini (@primos63), Santiago Fernandez (@santif), Hamza Wahed (@HamzaWahed), mwilbur (@mwilbur), Dima Budaragin (@dbud), Jorge Jímenez (@jorge-j1m), Alexander (@alexwheezy), Maarten Coopens (@maarteNNNN), Niklas Johansson (@Raphexion), glystik (@glystik), Michael Lynch (@mtlynch), Yashank (@stickyburn), blf (@bengtfrost)",
     "crumbs": [
       "Welcome"
     ]
diff --git a/flake.lock b/flake.lock
index 2468070f..b12776a6 100644
--- a/flake.lock
+++ b/flake.lock
@@ -1,5 +1,21 @@
 {
   "nodes": {
+    "flake-compat": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1696426674,
+        "narHash": "sha256-kvjfFW7WAETZlt09AgDn1MrtKzP7t90Vf7vypd3OL1U=",
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "rev": "0f9255e01c2351cc7d116c072cb317785dd33b33",
+        "type": "github"
+      },
+      "original": {
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "type": "github"
+      }
+    },
     "flake-utils": {
       "inputs": {
         "systems": "systems"
@@ -18,6 +34,24 @@
         "type": "github"
       }
     },
+    "flake-utils_2": {
+      "inputs": {
+        "systems": "systems_2"
+      },
+      "locked": {
+        "lastModified": 1705309234,
+        "narHash": "sha256-uNRRNRKmJyCRC/8y1RqBkqWBLM034y4qN7EprSdmgyA=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "1ef2e671c3b0c19053962c07dbda38332dcebf26",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
     "nixpkgs": {
       "locked": {
         "lastModified": 1735563628,
@@ -34,10 +68,27 @@
         "type": "github"
       }
     },
+    "nixpkgs_2": {
+      "locked": {
+        "lastModified": 1708161998,
+        "narHash": "sha256-6KnemmUorCvlcAvGziFosAVkrlWZGIc6UNT9GUYr0jQ=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "84d981bae8b5e783b3b548de505b22880559515f",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-23.11",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
     "root": {
       "inputs": {
         "flake-utils": "flake-utils",
-        "nixpkgs": "nixpkgs"
+        "nixpkgs": "nixpkgs",
+        "zig": "zig"
       }
     },
     "systems": {
@@ -54,6 +105,41 @@
         "repo": "default",
         "type": "github"
       }
+    },
+    "systems_2": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    },
+    "zig": {
+      "inputs": {
+        "flake-compat": "flake-compat",
+        "flake-utils": "flake-utils_2",
+        "nixpkgs": "nixpkgs_2"
+      },
+      "locked": {
+        "lastModified": 1748175105,
+        "narHash": "sha256-IcT4UOp+K7lDjYuSzKGMzrv1dp1znK3YS7UPKkLDvQ0=",
+        "owner": "mitchellh",
+        "repo": "zig-overlay",
+        "rev": "d665bd0897e491db11e24a12213c7f2a3ded5c08",
+        "type": "github"
+      },
+      "original": {
+        "owner": "mitchellh",
+        "repo": "zig-overlay",
+        "type": "github"
+      }
     }
   },
   "root": "root",
diff --git a/flake.nix b/flake.nix
index 1d6ede3f..eff8a318 100644
--- a/flake.nix
+++ b/flake.nix
@@ -4,9 +4,10 @@
   inputs = {
     nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.05";
     flake-utils.url = "github:numtide/flake-utils";
+    zig.url = "github:mitchellh/zig-overlay";
   };
 
-  outputs = { self, nixpkgs, flake-utils, ... }:
+  outputs = { self, nixpkgs, flake-utils, zig, ... } @ inputs:
     flake-utils.lib.eachDefaultSystem (system:
       let
         pkgs = nixpkgs.legacyPackages.${system};
@@ -52,13 +53,14 @@
           buildInputs = [
             R_env       # Provides R and Rscript
             pkgs.quarto # The Quarto CLI
+            zig.packages.${system}.master
             # REMOVED: localeDefinitions
           ] ++ nativeDeps;
 
           shellHook = ''
             # QUARTO_R: Point Quarto to the Rscript from our Nix-provided R environment
             unset QUARTO_R # Clear any pre-existing value
-            export QUARTO_R="${R_env}/bin/Rscript"
+            export QUARTO_R=$(which Rscript)
 
             # --- GENERAL LOCALE SETUP ---
             # Set a universally available, UTF-8 compatible locale.
@@ -66,14 +68,16 @@
             # without imposing a specific language or requiring extra locale packages.
             export LANG="C.UTF-8"
             export LC_ALL="C.UTF-8"
-            # C.UTF-8 does not need LOCALE_ARCHIVE to be explicitly set from glibcLocalesUtf8.
+
 
             echo "--- Nix Shell Environment (HTML Only) ---"
             echo "Locale set to C.UTF-8 for broad compatibility." # Added this line for clarity
-            echo "Zig is assumed to be available via \$PATH: $(which zig || echo 'Not found in PATH')"
+            echo "Zig is assumed to be available via \$PATH: $(which zig || echo 'Not found zig in PATH')"
             echo "R environment configured."
             echo "  To check R's library paths: R -e '.libPaths()'"
             echo "  To list R packages: R -e 'installed.packages()[,1]'"
+            echo "R environment is set to: $R_env"
+            echo "Rscript is at: $(which Rscript || echo 'Not found Rscript')"
             echo "QUARTO_R set to: $QUARTO_R"
             # REMOVED: echo "LOCALE_ARCHIVE set to: $LOCALE_ARCHIVE"
             echo ""

From 33b6810dcd630fcec9d39a2db96a179caf884023 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Mon, 26 May 2025 19:23:07 -0300
Subject: [PATCH 137/151] Fix singly linked list examples

---
 Chapters/09-data-structures.qmd | 167 ++++++++++++++++++++------------
 1 file changed, 103 insertions(+), 64 deletions(-)

diff --git a/Chapters/09-data-structures.qmd b/Chapters/09-data-structures.qmd
index add3878e..044958c3 100644
--- a/Chapters/09-data-structures.qmd
+++ b/Chapters/09-data-structures.qmd
@@ -706,8 +706,11 @@ var ages = std.StringArrayHashMap(u8).init(allocator);
 ## Linked lists
 
 The Zig Standard Library provides an implementation for both singly and doubly linked lists.
-A linked list is a linear data structure that looks like a chain, or, a rope.
-The main advantage of this data structure is that you normally have very fast
+More specifically, through the structs `SinglyLinkedList` and `DoublyLinkedList`, for "singly linked lists" and "doubly linked lists",
+respectively.
+
+In case you are not familiar with these data structures, a linked list is a linear data structure that looks
+like a chain, or, a rope. The main advantage of this data structure is that you normally have very fast
 insertion and deletion operations. But, as a disadvantage, iterating through
 this data structure is usually not so fast as iterating through an array.
 
@@ -740,88 +743,124 @@ normally have only the `next` pointer in them.
 ![A diagram of a doubly linked list.](./../Figures/doubly-linked-list.png){#fig-linked-list2}
 
 
-Linked lists are available in Zig through the functions `SinglyLinkedList()` and
-`DoublyLinkedList()`, for "singly linked lists" and "doubly linked lists", respectively. These functions are
-actually generic functions, which we are going to talk more about in @sec-generic-fun.
 
-For now, just understand that, in order to create a linked list object,
-we begin by providing a data type to these functions. This data type defines
-the type of data that each node in this linked list will store. In the example below,
-we are creating a singly linked list of `u32` values.
-So each node in this linked list will store a `u32` value.
+### Recent change in the API
 
-Both the `SinglyLinkedList()` and `DoublyLinkedList()` functions returns a type,
-i.e., a struct definition, as output. Therefore, the object `Lu32` is actually
-a struct definition. It defines the type "singly linked list of `u32` values".
+On previous versions of Zig, the `SinglyLinkedList` and `DoublyLinkedList` structures were initially implemented as "generics data structures".
+Meaning that, you would use a generic function to create a singly (or doubly) linked list that could store
+the specific data type that you wanted to use. In other words, you just tell Zig which data type that you are
+going to store inside the nodes of the linked list, and Zig creates the structure with the appropriate attributes
+for you. We will learn more about generics at @sec-generics, and also, how we can create a "generic data structure"
+at @sec-generics-struct.
 
-Now that we have the definition of the struct, we need to instantiate a `Lu32` object.
-We normally instantiate struct objects in Zig by using an `init()` method.
-But in this case, we are instantiating the struct directly, by using an empty
-`struct` literal, in the expression `Lu32{}`.
+However, on most recent versions of Zig, the structs `SinglyLinkedList` and `DoublyLinkedList` were altered to use a
+"less generic API". This specific change was introduced on April 3, 2025. Therefore, check if your Zig version is one released after this
+date. Just have in mind that if you don't have a very recent version of the Zig compiler,
+you might have problems while trying to compile the next examples.
 
-In this example, we first create multiple node objects, and after we create them,
-we start to insert and connect these nodes to build the linked list, using the
-`prepend()` and `insertAfter()` methods. Notice that the `prepend()` method
-is a method from the linked list object, while the `insertAfter()` is a method
-present in the node objects.
 
-In essence, the `prepend()` method inserts a node at the beginning of the linked
-list. In other words, the node that you provide to this method, becomes the new
-"head node" of the linked list. It becomes the first node in the list (see @fig-linked-list).
 
-On the other side, the `insertAfter()` method is used to basically connect two nodes together.
-When you provide a node to this method, it creates a pointer to this input node,
-and stores this pointer in the `next` attribute of the current node, from which the method was called from.
+### How to use a singly linked list
 
-Because doubly linked lists have both a `next` and a `prev` attributes in each node
-(as described in @fig-linked-list2), a node object created from
-a `DoublyLinkedList` object have both an `insertBefore()` (for `prev`)
-and an `insertAfter()` (for `next`) methods available.
+For example, consider that you are creating a singly linked list that is going to store `u32` values.
+Given this scenario, the first thing that we need to do, is to create a "node type" that is capable
+of storing a `u32` value. The `NodeU32` type exposed below demonstrates such "node type".
 
-Thus, if we have used a doubly linked list, we can use the `insertBefore()` method
-to store the pointer to the input node in the `prev` attribute. This would put the input
-node as the "previous node", or, the node before the current node. In contrast, the `insertAfter()` method
-puts the pointer created to the input node in the `next` attribute of the current node,
-and as result, the input node becomes the "next node" of the current node.
+Notice that the data type associated with the member named `data` is the most important part of this
+custom "node type". It determines the data type that is going to be stored in each node.
 
-Since we are using a singly linked list in this example, we have only the `insertAfter()` method
-available in the node objects that we create from our `Lu32` type.
+```{zig}
+#| eval: false
+const std = @import("std");
+const SinglyLinkedList = ;
 
+const NodeU32 = struct {
+    data: u32,
+    node: std.SinglyLinkedList.Node = .{},
+};
+```
+
+After we created our custom "node type" that can store the specific data type that we
+want, we can just create a new and empty singly linked list, which will store our nodes.
+To do that, we just create a new object with the type `SinglyLinkedList`, like this:
 
 ```{zig}
-#| auto_main: false
-const std = @import("std");
-const SinglyLinkedList = std.SinglyLinkedList;
-const Lu32 = SinglyLinkedList(u32);
+#| eval: false
+var list: std.SinglyLinkedList = .{};
+```
 
-pub fn main() !void {
-    var list = Lu32{};
-    var one = Lu32.Node{ .data = 1 };
-    var two = Lu32.Node{ .data = 2 };
-    var three = Lu32.Node{ .data = 3 };
-    var four = Lu32.Node{ .data = 4 };
-    var five = Lu32.Node{ .data = 5 };
-
-    list.prepend(&two); // {2}
-    two.insertAfter(&five); // {2, 5}
-    list.prepend(&one); // {1, 2, 5}
-    two.insertAfter(&three); // {1, 2, 3, 5}
-    three.insertAfter(&four); // {1, 2, 3, 4, 5}
-}
+Now, we have our linked list... But how can we insert nodes in it? Well, first of all,
+we need to create our nodes. So let's focus on that first. The snippet exposed below demonstrates
+how we could use our `NodeU32` struct to create such nodes.
+
+Notice in this snippet that we are just setting the `data` member of the struct for now.
+We don't need to connect these nodes together in this first instance. This is why we ignore
+the `node` member at first. But we are going to connect these nodes in a future point of the code, which is
+why these objects are marked as "variable objects", so that we can alter them in the future.
+
+```{zig}
+#| eval: false
+var one: NodeU32 = .{ .data = 1 };
+var two: NodeU32 = .{ .data = 2 };
+var three: NodeU32 = .{ .data = 3 };
+var five: NodeU32 = .{ .data = 5 };
 ```
 
+Now that we have both the linked list and also the nodes created, we can start to connect them together.
+You can use the `prepend()` method from the linked list object to insert the first node in the list, which
+is the "head" of the linked list. As the name suggests, this specific method prepends the input node to the linked list,
+or, in other words, it transforms the input node into the first node of the list.
+
+After we added the "head node" of the list, we can start to add the "next nodes" in the list by using the `insertAfter()` method
+from the `SinglyLinkedList.Node` type, which, in our case here, is accessible through the `node` member of our
+`NodeU32` type. Thus, we can start to create the connections between the nodes by calling this method from the node objects
+that are present in the list. Like in this example below:
 
-There are other methods available from the linked list object, depending if this object is
-a singly linked list or a doubly linked list, that might be very useful for you. You can find a
+```{zig}
+#| eval: false
+list.prepend(&two.node); // {2}
+two.node.insertAfter(&five.node); // {2, 5}
+two.node.insertAfter(&three.node); // {2, 3, 5}
+```
+
+You can also call the `prepend()` method again to add new nodes to the beginning of the linked list, which
+means, effectively, changing the "head node" of the list, like this:
+
+```{zig}
+#| eval: false
+list.prepend(&one.node); // {1, 2, 3, 5}
+```
+
+
+There are other methods available from the singly linked list object that you might be interested. You can find a
 summary of them in the bullet points below:
 
 - `remove()` to remove a specific node from the linked list.
-- if singly linked list, `len()` to count how many nodes there is in the linked list.
-- if doubly linked list, checkout the `len` attribute to see how many nodes there is in the linked list.
-- if singly linked list, `popFirst()` to remove the first node (i.e., the "head") from the linked list.
-- if doubly linked list, `pop()` and `popFirst()` to remove the last and first nodes from the linked list, respectively.
-- if doubly linked list, `append()` to add a new node to end of the linked list (i.e., inverse of `prepend()`).
+- `len()` to count how many nodes there is in the linked list.
+- `popFirst()` to remove the first node (i.e., the "head") from the linked list.
+
+So, that is how singly linked lists work in Zig in a nutshell. To sum up what we have exposed here,
+this is all the source code that was exposed in this section inside the single cell:
+
+```{zig}
+#| build_type: "run"
+#| auto_main: true
+const NodeU32 = struct {
+    data: u32,
+    node: std.SinglyLinkedList.Node = .{},
+};
 
+var list: std.SinglyLinkedList = .{};
+var one: NodeU32 = .{ .data = 1 };
+var two: NodeU32 = .{ .data = 2 };
+var three: NodeU32 = .{ .data = 3 };
+var five: NodeU32 = .{ .data = 5 };
+
+list.prepend(&two.node); // {2}
+two.node.insertAfter(&five.node); // {2, 5}
+two.node.insertAfter(&three.node); // {2, 3, 5}
+list.prepend(&one.node); // {1, 2, 3, 5}
+```
 
 
 ## Multi array structure

From 3257bf035856aa6241ef805ae888a240ee3acc71 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Mon, 26 May 2025 19:31:33 -0300
Subject: [PATCH 138/151] Fix example

---
 Chapters/09-data-structures.qmd               |  20 +-
 .../execute-results/html.json                 |   8 +-
 docs/Chapters/09-data-structures.html         | 178 +++++++++++-------
 docs/index.html                               |   4 +-
 docs/search.json                              |   2 +-
 5 files changed, 122 insertions(+), 90 deletions(-)

diff --git a/Chapters/09-data-structures.qmd b/Chapters/09-data-structures.qmd
index 044958c3..338b867e 100644
--- a/Chapters/09-data-structures.qmd
+++ b/Chapters/09-data-structures.qmd
@@ -706,8 +706,7 @@ var ages = std.StringArrayHashMap(u8).init(allocator);
 ## Linked lists
 
 The Zig Standard Library provides an implementation for both singly and doubly linked lists.
-More specifically, through the structs `SinglyLinkedList` and `DoublyLinkedList`, for "singly linked lists" and "doubly linked lists",
-respectively.
+More specifically, through the structs `SinglyLinkedList` and `DoublyLinkedList`.
 
 In case you are not familiar with these data structures, a linked list is a linear data structure that looks
 like a chain, or, a rope. The main advantage of this data structure is that you normally have very fast
@@ -746,17 +745,15 @@ normally have only the `next` pointer in them.
 
 ### Recent change in the API
 
-On previous versions of Zig, the `SinglyLinkedList` and `DoublyLinkedList` structures were initially implemented as "generics data structures".
+On previous versions of Zig, the `SinglyLinkedList` and `DoublyLinkedList` structs were initially implemented as "generics data structures".
 Meaning that, you would use a generic function to create a singly (or doubly) linked list that could store
-the specific data type that you wanted to use. In other words, you just tell Zig which data type that you are
-going to store inside the nodes of the linked list, and Zig creates the structure with the appropriate attributes
-for you. We will learn more about generics at @sec-generics, and also, how we can create a "generic data structure"
-at @sec-generics-struct.
+the specific data type that you wanted to use. We will learn more about generics at @sec-generics, and also,
+how we can create a "generic data structure" at @sec-generic-struct.
 
-However, on most recent versions of Zig, the structs `SinglyLinkedList` and `DoublyLinkedList` were altered to use a
+However, on the latest versions of Zig, the structs `SinglyLinkedList` and `DoublyLinkedList` were altered to use a
 "less generic API". This specific change was introduced on April 3, 2025. Therefore, check if your Zig version is one released after this
 date. Just have in mind that if you don't have a very recent version of the Zig compiler,
-you might have problems while trying to compile the next examples.
+you might have problems while trying to compile the next examples exposed here.
 
 
 
@@ -772,7 +769,6 @@ custom "node type". It determines the data type that is going to be stored in ea
 ```{zig}
 #| eval: false
 const std = @import("std");
-const SinglyLinkedList = ;
 
 const NodeU32 = struct {
     data: u32,
@@ -839,7 +835,7 @@ summary of them in the bullet points below:
 - `len()` to count how many nodes there is in the linked list.
 - `popFirst()` to remove the first node (i.e., the "head") from the linked list.
 
-So, that is how singly linked lists work in Zig in a nutshell. To sum up what we have exposed here,
+So, that is how singly linked lists work in Zig in a nutshell. To sum up,
 this is all the source code that was exposed in this section inside the single cell:
 
 ```{zig}
@@ -860,6 +856,8 @@ list.prepend(&two.node); // {2}
 two.node.insertAfter(&five.node); // {2, 5}
 two.node.insertAfter(&three.node); // {2, 3, 5}
 list.prepend(&one.node); // {1, 2, 3, 5}
+
+try stdout.print("Number of nodes: {}", .{list.len()});
 ```
 
 
diff --git a/_freeze/Chapters/09-data-structures/execute-results/html.json b/_freeze/Chapters/09-data-structures/execute-results/html.json
index 3bbf890a..d48aede7 100644
--- a/_freeze/Chapters/09-data-structures/execute-results/html.json
+++ b/_freeze/Chapters/09-data-structures/execute-results/html.json
@@ -1,11 +1,9 @@
 {
-  "hash": "ec46a394836e999ef1cdcb2a2a2407a2",
+  "hash": "b402250b83835ffcd41be6613f43fc78",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Data Structures\n\nIn this chapter, I want to present the most common Data Structures that are available from\nthe Zig Standard Library, especially `ArrayList` and also `HashMap`. These are generic Data Structures\nthat you can use to store and control any type of data that is produced by your application.\n\n## Dynamic Arrays {#sec-dynamic-array}\n\nIn high level languages, arrays are usually dynamic. They can easily grow\nin size when they have to, and you don't need to worry about it.\nIn contrast, arrays in low level languages are usually static by default.\nThis is the reality of C, C++, Rust and also Zig. Static arrays were presented at\n@sec-arrays, but in this section, we are going to talk about dynamic arrays in Zig.\n\nDynamic arrays are simply arrays that can grow in size during the runtime\nof your program. Most low level languages have some implementation of\na dynamic array in their standard library. C++ have `std::vector`, Rust have `Vec`,\nand Zig have `std.ArrayList`.\n\nThe `std.ArrayList` struct provides a contiguous and growable array for you.\nIt works like any other dynamic array, it allocates a contiguous block of memory, and when this block have no space left,\n`ArrayList` allocates another contiguous and bigger block of memory, copies the\nelements to this new location, and erases (or frees) the previous block of memory.\n\n\n### Capacity vs Length\n\nWhen we talk about dynamic arrays, we usually have two similar concepts that\nare very essential to how a dynamic array works behind the hood.\nThese concepts are *capacity* and *length*. In some contexts, especially\nin C++, *length* is also called of *size*.\n\nAlthough they look similar, these concepts represent different things\nin the context of a dynamic array. *Capacity* is the number of items (or elements)\nthat your dynamic array can currently hold without the need to allocate more memory.\n\nIn contrast, the *length* refers to how many elements in the array\nare currently being used, or, in other words, how many elements in this array\nthat you have assigned a value to. Every dynamic array works around\na block of allocated memory, which represents an array with total capacity for $n$ elements.\nHowever, only a portion of these $n$ elements are being used most of the time. This portion\nof $n$ is the *length* of the array. So every time you append a new value\nto the array, you are incrementing its *length* by one.\n\nThis means that a dynamic array usually works with an extra margin, or an extra space\nthat is currently empty, but waiting and ready to be used. This \"extra space\"\nis essentially the difference between *capacity* and *length*. *Capacity* represents\nthe total number of elements that the array can hold without the need to re-allocate\nor re-expand the array, while the *length* represents how much of this capacity\nis currently being used to hold/store values.\n\n@fig-capacity-length presents this idea visually. Notice that, at first,\nthe capacity of the array is greater than the length of the array.\nSo, the dynamic array have extra space that is currently empty, but it\nis ready to receive a value to be stored.\n\n![Difference between capacity and length in a dynamic array](./../Figures/dynamic-array.png){#fig-capacity-length}\n\nWe can also see in @fig-capacity-length that, when *length* and *capacity* are equal, it means that the array have no space left.\nWe have reached the ceiling of our capacity, and because of that, if we want to store more values\nin this array, we need to expand it. We need to get a bigger space that can hold more values\nthan what we currently have.\n\nA dynamic array works by expanding the underlying array, whenever the *length* becomes equal\nto the *capacity* of the array. It basically allocates a new contiguous block of memory that is bigger\nthan the previous one, then, it copies all values that are currently being stored to this new\nlocation (i.e., this new block of memory), then, it frees the previous block of\nmemory. At the end of this process, the new underlying array have a bigger *capacity*, and, therefore,\nthe *length* becomes, once again, smaller than the *capacity* of the array.\n\nThis is the cycle of a dynamic array. Notice that, throughout this cycle, the *capacity* is always\neither equal to or higher than the *length* of the array. If you have an `ArrayList` object (let's suppose\nyou named it `buffer`), you can check the current capacity of your array by accessing the `capacity`\nattribute of your `ArrayList` object, while the current *length* of it is available at the `items.len`\nattribute.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// Check capacity\nbuffer.capacity;\n// Check length\nbuffer.items.len;\n```\n:::\n\n\n\n\n\n### Creating an `ArrayList` object\n\nIn order to use `ArrayList`, you must provide an allocator object to it.\nRemember, Zig does not have a default memory allocator. And as I described in @sec-allocators, all memory\nallocations must be done by an allocator object that you define, that\nyou have control over. In our example here, I'm going to use\na general purpose allocator, but you can use any other allocator\nof your preference.\n\nWhen you initialize an `ArrayList` object, you must provide the data type of the elements of\nthe array. In other words, this defines the type of data that this array (or container) will\nstore. Therefore, if I provide the `u8` type to it, then, I will create a dynamic\narray of `u8` values. However, if I provide a struct that I have defined instead, like the struct `User`\nfrom @sec-structs-and-oop, then, a dynamic array of `User` values\nwill be created. In the example below, with the expression `ArrayList(u8)` we\nare creating a dynamic array of `u8` values.\n\nAfter you provide the data type of the elements of the array, you can initialize\nan `ArrayList` object by either using the `init()` or the `initCapacity()` methods.\nThe former method receives only the allocator object\nas input, while the latter method receives both the allocator object and a capacity number as inputs.\nWith the latter method, you not only initialize the struct, but you\nalso set the starting capacity of the allocated array.\n\nUsing the `initCapacity()` method is the preferred way to initialize your dynamic array.\nBecause reallocations, or, in other words, the process of expanding the capacity of the array,\nis always a high cost operation. You should take any possible opportunity to avoid reallocations in\nyour array. If you know how much space your array needs to occupy at the beginning,\nyou should always use `initCapacity()` to create your dynamic array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n```\n:::\n\n\n\n\n\nIn the example above, the `buffer` object starts as an array of 100 elements. If this\n`buffer` object needs to create more space to accomodate more elements during the runtime of your program, the `ArrayList`\ninternals will perform the necessary actions for you automatically.\nAlso notice the `deinit()` method being used to destroy the `buffer` object at the\nend of the current scope, by freeing all the memory that was allocated for the dynamic\narray stored in this `buffer` object.\n\n\n### Adding new elements to the array\n\nNow that we have created our dynamic array, we can start to use it. You can append (a.k.a \"add\")\nnew values to this array by using the `append()` method. This method works the same way\nas the `append()` method from a Python list, or, the `emplace_back()` method from `std::vector` of C++.\nYou provide a single value to this method, and the method appends this value to the array.\n\nYou can also use the `appendSlice()` method to append multiple values at once. You provide\na slice (slices were described in @sec-arrays) to this method, and the method adds all values present\nin this slice to your dynamic array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry buffer.append('H');\ntry buffer.append('e');\ntry buffer.append('l');\ntry buffer.append('l');\ntry buffer.append('o');\ntry buffer.appendSlice(\" World!\");\n```\n:::\n\n\n\n\n### Removing elements from the array {#sec-dynamic-array-remove}\n\nYou can use the `pop()` method to \"pop\" or remove\nthe last element in the array. It's worth noting that this method\ndo not change the capacity of the array. It just deletes or erases\nthe last value stored in the array.\n\nAlso, this method returns as result the value that got deleted. That is, you can\nuse this method to both get the last value in the array, and also, remove\nit from the array. It's a \"get and remove value\" type of method.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exclamation_mark = buffer.pop();\n```\n:::\n\n\n\n\nNow, if you want to remove specific elements from specific positions\nof your array, you can use the `orderedRemove()` method from your\n`ArrayList` object. With this method, you can provide an index as input,\nthen, the method will delete the value that is at this index in the array.\nYou are effectively reducing the *length* of the array everytime you execute\nan `orderedRemove()` operation.\n\nIn the example below, we first create an `ArrayList` object, and we fill it\nwith numbers. Then, we use `orderedRemove()` to remove the value at\nindex 3 in the array, two consecutive times.\n\nAlso, notice that we are assigning the result of `orderedRemove()` to the\nunderscore character. So we are discarding the result value of this method.\nThe `orderedRemove()` method returns the value that got deleted, in a similar\nstyle to the `pop()` method.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n\nfor (0..10) |i| {\n    const index: u8 = @intCast(i);\n    try buffer.append(index);\n}\n\nstd.debug.print(\n    \"{any}\\n\", .{buffer.items}\n);\n_ = buffer.orderedRemove(3);\n_ = buffer.orderedRemove(3);\n\nstd.debug.print(\"{any}\\n\", .{buffer.items});\nstd.debug.print(\"{any}\\n\", .{buffer.items.len});\n```\n:::\n\n\n\n\n```\n{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }\n{ 0, 1, 2, 5, 6, 7, 8, 9 }\n8\n```\n\nOne key characteristic about `orderedRemove()` is that it preserves the order\nof the values in the array. So, it deletes the value that you asked it to\nremove, but it also makes sure that the order of the values that remain in the array\nstay the same as before.\n\nNow, if you don't care about the order of the values, for example, maybe you want to treat\nyour dynamic array as a set of values, like the `std::unordered_set`\nstructure from C++, you can use the `swapRemove()` method instead. This method\nworks similarly to the `orderedRemove()` method. You give an index to this\nmethod, then, it deletes the value that is at this index in the array.\nBut this method does not preserve the original order of the values that remain\nin the array. As a result, `swapRemove()` is, in general, faster than `orderedRemove()`.\n\n\n### Inserting elements at specific indexes\n\nWhen you need to insert values in the middle of your array,\ninstead of just appending them to the end of the array, you need to use\nthe `insert()` and `insertSlice()` methods, instead of\nthe `append()` and `appendSlice()` methods.\n\nThese two methods work very similarly to `insert()` and `insert_range()`\nfrom the C++ `std::vector` class. You provide an index to these methods,\nand they insert the values that you provide at that index in the array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 10);\ndefer buffer.deinit();\n\ntry buffer.appendSlice(\"My Pedro\");\ntry buffer.insert(4, '3');\ntry buffer.insertSlice(2, \" name\");\nfor (buffer.items) |char| {\n    try stdout.print(\"{c}\", .{char});\n}\n```\n:::\n\n\n\n\n```\nMy name P3edro\n```\n\n\n### Conclusion\n\nIf you feel the lack of some other method, I recommend\nyou to read the [official documentation for the `ArrayListAligned`](https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned)[^zig-array2]\nstruct, which describes most of the methods available\nthrough the `ArrayList` object.\n\nYou will notice that there is a lot of other methods in this page that\nI did not described here, and I recommend you to explore these methods,\nand understand how they work.\n\n[^zig-array2]: <https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned>\n\n\n\n## Maps or HashTables {#sec-maps-hashtables}\n\nSome professionals know this type of data structure by different terms, like \"map\",\n\"hashmap\" or \"associative arrays\". But the most common term used is *hashtable*.\nEvery programming language normally have some implementation of a hashtable in their\nstandard libraries. Python have `dict()`, C++ have `std::map` and `std::unordered_map`, Rust\nhave `HashMap`, Javascript have `Object()` and `Map()`, etc.\n\n\n\n### What is a hashtable?\n\nA hashtable is a data structure based on key-value pairs.\nYou provide a key and a value to this structure, then, the hashtable will store\nthe input value at a location that can be identified by the input\nkey that you provided.\nIt does that by using an underlying array and a hash function.\nThese two components are essential to how a hashtable works.\n\nUnder the hood, the hashtable contains an array. This array is where the values\nare stored, and the elements of this array are usually called of *buckets*.\nSo the values that you provide to the hashtable are stored inside buckets,\nand you access each bucket by using an index.\n\nWhen you provide a key to a hashtable, it passes this key to the\nhash function. This hash function uses some sort of hashing algorithm to transform\nthis key into an index. This index is actually an array index. It's a position\nin the underlying array of the hashtable.\nThis is how a key identifies a specific position (or location) inside the hashtable\nstructure.\n\nTherefore, you provide a key to the hashtable, and this key identifies a specific location\ninside the hashtable, then, the hashtable takes the input value that you provided,\nand stores this value in the location identified by this input key.\nYou could say that the key maps to the value stored in the hashtable. You find\nthe value, by using the key that identifies the location where the value is stored.\nThe @fig-hashtable presents this process visually.\n\n\n![A diagram of a Hashtable. Source: Wikipedia, the free encyclopedia.](./../Figures/hashtable.svg){#fig-hashtable}\n\n\nThe operation described in the previous paragraph is normally called an *insertion* operation.\nBecause you are inserting new values into the hashtable.\nBut there are other types of operations in hashtables such as *delete* and *lookup*.\nDelete is self describing, it's when you delete (or remove) a value from the hashtable.\nWhile lookup corresponds to when you look at a value that is stored in\nthe hashtable, by using the key that identifies the location where this value is stored.\n\nSometimes, instead of storing the values directly, the underlying array of the hashtable might be an array of pointers,\ni.e., the buckets of the array stores pointers that points to the value,\nor also, may be an array of linked lists.\nThese cases are common on hashtables that allows duplicate keys, or, in other words,\non hashtables that effectively handle \"collisions\" that may arise from the hash function.\n\nDuplicate keys, or this \"collision\" thing that I'm talking about, is when you have two different keys\nthat points to the same location (i.e., to the same index)\nin the underlying array of the hashtable. This might happen depending on the characteristics of the hash function\nthat is being used in the hashtable. Some implementations of the hashtable will actively deal with collisions,\nmeaning that, they will handle this case in some way. For example, the hashtable\nmight transform all buckets into linked lists. Because with a linked list you can store\nmultiple values into a single bucket.\n\nThere are different techniques to handle collisions in hashtables, which I will not describe\nin this book, because it's not our main scope here. But you can find a good description of\nsome of the most common techniques at the Wikipedia page of hashtables [@wikipedia_hashtables].\n\n\n### Hashtables in Zig {#sec-hashmap}\n\nThe Zig Standard Library provides different implementations of a hashtable.\nEach implementation have its own cons and pros, which we will\ndiscuss later on, and all of them are available through the `std.hash_map` module.\n\nThe `HashMap` struct is a general-purpose hashtable,\nwhich have very fast operations (lookup, insertion, delete), and also,\nquite high load factors for low memory usage. You can create and provide a context object\nto the `HashMap` constructor. This context object allows you to tailor\nthe behaviour of the hashtable itself, because you can\nprovide a hash function implementation to be used by the hashtable\nthrough this context object.\n\nBut let's not worry about this context object now, because it's meant to be used\nby \"experts in the field of hashtables\". Since we are most likely not\nexperts in this field, we are going to take the easy way to create\na hashtable. Which is by using the `AutoHashMap()` function.\n\n\nThis `AutoHashMap()` function is essentially a \"create a hashtable object that uses the default settings\"\ntype of function. It automatically chooses a context object, and, therefore, a hash function implementation,\nfor you. This function receives two data types as input, the first input is the data type of the keys\nthat will be used in this hashtable, while the second input is the data type of the data that will be\nstored inside the hashtable, that is, the data type of the values to be stored.\n\nIn the example below, we are providing the data type `u32` in the first argument, and `u16` in the second argument of this\nfunction. This means that we are going to use `u32` values as keys in this hashtable, while `u16` values are the actual values\nthat are going to be stored into this hashtable.\nAt the end of this process, the `hash_table` object contains a `HashMap` object\nthat uses the default settings and context.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n    std.debug.print(\n        \"Value at key 50050: {d}\\n\",\n        .{hash_table.get(50050).?}\n    );\n\n    if (hash_table.remove(57709)) {\n        std.debug.print(\n            \"Value at key 57709 successfully removed!\\n\",\n            .{}\n        );\n    }\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n}\n```\n:::\n\n\n\n\n```\nN of values stored: 3\nValue at key 50050: 55\nValue at key 57709 successfully removed!\nN of values stored: 2\n```\n\nYou can add/put new values into the hashtable by using the `put()` method. The first argument\nis the key to be used, and the second argument is the actual value that you want to store inside\nthe hashtable. In the example below, we first add the value 89 using the key 54321, next, we add\nthe value 55 using the key 50050, etc.\n\nNotice that we have used the method `count()` to see how many values are currently stored in the\nhashtable. After that, we also use the `get()` method to access (or look) at the value stored in\nthe position identified by the key 500050. The output of this `get()` method is an optional value.\nThis is why we use the `?` method at the end to get the actual value.\n\nAlso notice that we can remove (or delete) values from the hashtable by using the `remove()` method.\nYou provide the key that identifies the value that you want to delete, then, the method will\ndelete this value and return a `true` value as output. This `true` value essentially tells us\nthat the method successfully deleted the value.\n\nBut this delete operation might not be always successful. For example, you might provide the wrong\nkey to this method. I mean, maybe you provide\n(either intentionally or unintentionally) a key that points to an empty bucket,\ni.e., a bucket that still doesn't have a value in it.\nIn this case, the `remove()` method would return a `false` value.\n\n\n\n### Iterating through the hashtable\n\nIterating through the keys and values that are currently being stored in\nthe hashtable is a very common necessity.\nYou can do that in Zig by using an iterator object that can iterate\nthrough the elements of your hashtable object.\n\nThis iterator object works like any other iterator object that you would\nfind in languages such as C++ and Rust. It's basically a pointer object\nthat points to some value in the container, and has a `next()` method\nthat you can use to navigate (or iterate) through the values in the\ncontainer.\n\nYou can create such iterator object by using the `iterator()` method of the hashtable object.\nThis method returns an iterator object, from which you can use the `next()` method in conjunction\nwith a while loop to iterate through the elements of your hashtable. The `next()` method returns an optional\n`Entry` value, and therefore, you must unwrap this optional value to get the actual `Entry` value\nfrom which you can access the key and also the value identified by this key.\n\nWith this `Entry` value at hand, you can access the key of this current entry by using the `key_ptr`\nattribute and dereferencing the pointer that lives inside of it, while the value identified by this\nkey is accessed through the `value_ptr` attribute instead, which is also a pointer to be dereferenced.\nThe code example below demonstrates the use of these elements:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n\n    var it = hash_table.iterator();\n    while (it.next()) |kv| {\n        // Access the current key\n        std.debug.print(\"Key: {d} | \", .{kv.key_ptr.*});\n        // Access the current value\n        std.debug.print(\"Value: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n:::\n\n\n\n\n```\nKey: 54321 | Value: 89\nKey: 50050 | Value: 55\nKey: 57709 | Value: 41\n```\n\n\nIf you want to iterate specifically through the values or the keys of your hashtable,\nyou can create a key iterator or a value iterator object. These are also iterator\nobjects, which have the same `next()` method that you can use to iterate through the\nhashtable.\n\nKey iterators are created from the `keyIterator()` method of your\nhashtable object, while value iterators are created from the `valueIterator()` method.\nAll you have to do is to unwrap the value from the `next()` method and deference it\ndirectly to access the key or the value that you are iterating over.\nThe code example below demonstrates the use of a key iterator,\nbut you can replicate the same logic to a value iterator.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar kit = hash_table.keyIterator();\nwhile (kit.next()) |key| {\n    std.debug.print(\"Key: {d}\\n\", .{key.*});\n}\n```\n:::\n\n\n\n\n```\nKey: 54321\nKey: 50050\nKey: 57709\n```\n\n\n### The `ArrayHashMap` hashtable {#sec-array-map}\n\nIf you need to iterate through the elements of your hashtable constantly,\nyou might want to use the `ArrayHashMap` struct for your specific case,\ninstead of going with the usual and general-purpose `HashMap` struct.\n\nThe `ArrayHashMap` struct creates a hashtable that is faster to iterate over.\nThat is why this specific type of hashtable might be valuable to you.\nSome other properties of a `ArrayHashMap` hashtable are:\n\n- the order of insertion is preserved, i.e., the order of the values that you find while iterating through this hashtable is actually the order in which these values were inserted in the hashtable.\n- the key-value pairs are stored sequentially, one after another.\n\n\nYou can create an `ArrayHashMap` object by using, once again, a helper function that\nchooses automatically for you a hash function implementation. This is the\n`AutoArrayHashMap()` function, which works very similarly to the `AutoHashMap()`\nfunction that we presented in @sec-hashmap.\n\nYou provide two data types to this function. The data type of the keys that will be\nused in this hashtable, and the data type of the values that will be stored in\nthis hashtable.\n\nAn `ArrayHashMap` object have essentially the exact same methods from the `HashMap` struct.\nSo you can insert new values into the hashtable by using the `put()` method, and you can look (or get)\na value from the hashtable by using the `get()` method. But the `remove()` method is not available\nin this specific type of hashtable.\n\nIn order to delete values from the hashtable, you would use the same methods that you find in\nan `ArrayList` object, i.e., a dynamic array. I presented these methods in @sec-dynamic-array-remove,\nwhich are the `swapRemove()` and `orderedRemove()` methods. These methods have the same meaning here, or,\nthe same effect that they have in an `ArrayList` object.\n\nThis means that, with `swapRemove()` you remove the value from the hashtable, but you do not preserve\nthe order in which the values were inserted into the structure. While `orderedRemove()` is able\nto retain the order in which these values were inserted.\n\nBut instead of providing an index as input to `swapRemove()` or `orderedRemove()`, like I described\nin @sec-dynamic-array-remove, these methods here in an `ArrayHashMap` take a key as input, like\nthe `remove()` method from a `HashMap` object. If you want to provide an index as input, instead\nof a key, you should use the `swapRemoveAt()` and `orderedRemoveAt()` methods.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar hash_table = AutoArrayHashMap(u32, u16)\n    .init(allocator);\ndefer hash_table.deinit();\n```\n:::\n\n\n\n\n\n\n### The `StringHashMap` hashtable {#sec-string-hash-map}\n\nOne thing that you will notice in the other two types of hashtables that I have\npresented over the last sections, is that neither of them accepts a slice data type\nin their keys.\nWhat this means is that you cannot use a slice value to represent a key in\nthese types of hashtable.\n\nThe most obvious consequence of this, is that you cannot use strings as keys\nin these hashtables. But it's extremely common to use strings as keys\nin hashtables.\n\nTake this very simple Javascript code snippet as an example. We are creating\na simple hashtable object named `people`. Then, we add a new entry to this\nhashtable, which is identified by the string `'Pedro'`. This string is the\nkey in this case, while the object containing different personal information such as\nage, height and city, is the value to be stored in the hashtable.\n\n```js\nvar people = new Object();\npeople['Pedro'] = {\n    'age': 25,\n    'height': 1.67,\n    'city': 'Belo Horizonte'\n};\n```\n\nThis pattern of using strings as keys is very common in\nall sorts of situations. That is why the Zig Standard Library offers a\nspecific type of hashtable for this purpose, which is created through the `StringHashMap()` function.\nThis function creates a hashtable that uses strings as keys. The only input of this\nfunction is the data type of the values that will be stored into this hashtable.\n\nIn the example below, I'm creating a hashtable to store the ages of different people.\nEach key in this hashtable is represented by the name of each person, while the value stored in the\nhashtable is the age of this person identified by the key.\n\nThat is why I provide the `u8` data type (which is the data type used by the age values) as input to this `StringHashMap()` function.\nAs the result, it creates a hashtable that uses string values as keys, and, that stores\n`u8` values in it. Notice that an allocator object is provided at the `init()` method of the\nresulting object from the `StringHashMap()` function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var ages = std.StringHashMap(u8).init(allocator);\n    defer ages.deinit();\n\n    try ages.put(\"Pedro\", 25);\n    try ages.put(\"Matheus\", 21);\n    try ages.put(\"Abgail\", 42);\n\n    var it = ages.iterator();\n    while (it.next()) |kv| {\n        std.debug.print(\"Key: {s} | \", .{kv.key_ptr.*});\n        std.debug.print(\"Age: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n:::\n\n\n\n\n```\nKey: Pedro | Age: 25\nKey: Abgail | Age: 42\nKey: Matheus | Age: 21\n```\n\n\n### The `StringArrayHashMap` hashtable\n\nThe Zig Standard Library also provides a type of hashtable that mix the cons and pros of the\n`StringHashMap` and `ArrayHashMap` together. That is, a hashtable\nthat uses strings as keys, but also have the advantages from `ArrayHashMap`.\nIn other words, you can have a hashtable that is fast to iterate over,\nthat preserves insertion order, and also, that uses strings as keys.\n\nYou can create such type of hashtable by using the `StringArrayHashMap()` function.\nThis function accepts a data type as input, which is the data type of the values that are\ngoing to be stored inside this hashtable, in the same style as the function presented\nin @sec-string-hash-map.\n\nYou can insert new values into this hashtable by using the same `put()` method that\nwe have discussed in @sec-string-hash-map. And you can also get values from the hashtable\nby using the same `get()` method.\nLike its `ArrayHashMap` brother, to delete values from this specific type of hashtable,\nwe also use the `orderedRemove()` and `swapRemove()` methods, with the same effects that\nI have described in @sec-array-map.\n\nIf we take the code example that was exposed in @sec-string-hash-map, we can\nachieve the exact same result with `StringArrayHashMap()`:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar ages = std.StringArrayHashMap(u8).init(allocator);\n```\n:::\n\n\n\n\n\n\n\n## Linked lists\n\nThe Zig Standard Library provides an implementation for both singly and doubly linked lists.\nA linked list is a linear data structure that looks like a chain, or, a rope.\nThe main advantage of this data structure is that you normally have very fast\ninsertion and deletion operations. But, as a disadvantage, iterating through\nthis data structure is usually not so fast as iterating through an array.\n\nThe idea behind a linked list is to build a structure that consists of a sequence of nodes\nconnected to each other by pointers. This means that linked lists are usually not contiguous\nin memory, because each node might be anywhere in memory. They do not need to be close to\none another.\n\nIn @fig-linked-list we can see a diagram of a singly linked list. We begin at the first node\n(which is usually called \"the head of the linked list\"). Then, from this\nfirst node we uncover the remaining nodes in the structure, by following the locations pointed\nby the pointers found in each node.\n\nEach node has two things in it. It has the value that is stored in the current node\n, and also, a pointer. This pointer points to the next node in the list. If this pointer\nis null, then, it means that we have reached the end of our linked list.\n\n![A diagram of a singly linked list.](./../Figures/linked-list.png){#fig-linked-list}\n\n\nIn @fig-linked-list2 we can see a diagram of a doubly linked list. The only thing that really\nchanges now is that every node in the linked list has both a pointer to the previous node,\nand, a pointer to the next node. So every node in a doubly linked list has two pointers in it. These are\nusually called the `prev` (for \"previous\") and the `next` (for \"next\") pointers of the node.\n\nIn the singly linked list example, we had only one single pointer in each node, and this singular\npointer was always pointing to the next node in the sequence. This means that singly linked lists\nnormally have only the `next` pointer in them.\n\n![A diagram of a doubly linked list.](./../Figures/doubly-linked-list.png){#fig-linked-list2}\n\n\nLinked lists are available in Zig through the functions `SinglyLinkedList()` and\n`DoublyLinkedList()`, for \"singly linked lists\" and \"doubly linked lists\", respectively. These functions are\nactually generic functions, which we are going to talk more about in @sec-generic-fun.\n\nFor now, just understand that, in order to create a linked list object,\nwe begin by providing a data type to these functions. This data type defines\nthe type of data that each node in this linked list will store. In the example below,\nwe are creating a singly linked list of `u32` values.\nSo each node in this linked list will store a `u32` value.\n\nBoth the `SinglyLinkedList()` and `DoublyLinkedList()` functions returns a type,\ni.e., a struct definition, as output. Therefore, the object `Lu32` is actually\na struct definition. It defines the type \"singly linked list of `u32` values\".\n\nNow that we have the definition of the struct, we need to instantiate a `Lu32` object.\nWe normally instantiate struct objects in Zig by using an `init()` method.\nBut in this case, we are instantiating the struct directly, by using an empty\n`struct` literal, in the expression `Lu32{}`.\n\nIn this example, we first create multiple node objects, and after we create them,\nwe start to insert and connect these nodes to build the linked list, using the\n`prepend()` and `insertAfter()` methods. Notice that the `prepend()` method\nis a method from the linked list object, while the `insertAfter()` is a method\npresent in the node objects.\n\nIn essence, the `prepend()` method inserts a node at the beginning of the linked\nlist. In other words, the node that you provide to this method, becomes the new\n\"head node\" of the linked list. It becomes the first node in the list (see @fig-linked-list).\n\nOn the other side, the `insertAfter()` method is used to basically connect two nodes together.\nWhen you provide a node to this method, it creates a pointer to this input node,\nand stores this pointer in the `next` attribute of the current node, from which the method was called from.\n\nBecause doubly linked lists have both a `next` and a `prev` attributes in each node\n(as described in @fig-linked-list2), a node object created from\na `DoublyLinkedList` object have both an `insertBefore()` (for `prev`)\nand an `insertAfter()` (for `next`) methods available.\n\nThus, if we have used a doubly linked list, we can use the `insertBefore()` method\nto store the pointer to the input node in the `prev` attribute. This would put the input\nnode as the \"previous node\", or, the node before the current node. In contrast, the `insertAfter()` method\nputs the pointer created to the input node in the `next` attribute of the current node,\nand as result, the input node becomes the \"next node\" of the current node.\n\nSince we are using a singly linked list in this example, we have only the `insertAfter()` method\navailable in the node objects that we create from our `Lu32` type.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SinglyLinkedList = std.SinglyLinkedList;\nconst Lu32 = SinglyLinkedList(u32);\n\npub fn main() !void {\n    var list = Lu32{};\n    var one = Lu32.Node{ .data = 1 };\n    var two = Lu32.Node{ .data = 2 };\n    var three = Lu32.Node{ .data = 3 };\n    var four = Lu32.Node{ .data = 4 };\n    var five = Lu32.Node{ .data = 5 };\n\n    list.prepend(&two); // {2}\n    two.insertAfter(&five); // {2, 5}\n    list.prepend(&one); // {1, 2, 5}\n    two.insertAfter(&three); // {1, 2, 3, 5}\n    three.insertAfter(&four); // {1, 2, 3, 4, 5}\n}\n```\n:::\n\n\n\n\n\nThere are other methods available from the linked list object, depending if this object is\na singly linked list or a doubly linked list, that might be very useful for you. You can find a\nsummary of them in the bullet points below:\n\n- `remove()` to remove a specific node from the linked list.\n- if singly linked list, `len()` to count how many nodes there is in the linked list.\n- if doubly linked list, checkout the `len` attribute to see how many nodes there is in the linked list.\n- if singly linked list, `popFirst()` to remove the first node (i.e., the \"head\") from the linked list.\n- if doubly linked list, `pop()` and `popFirst()` to remove the last and first nodes from the linked list, respectively.\n- if doubly linked list, `append()` to add a new node to end of the linked list (i.e., inverse of `prepend()`).\n\n\n\n## Multi array structure\n\nZig introduces a new data structure called `MultiArrayList()`. It's a different version of the dynamic array\nthat we have introduced in @sec-dynamic-array. The difference between this structure and the `ArrayList()`\nthat we know from @sec-dynamic-array, is that `MultiArrayList()` creates a separate dynamic array\nfor each field of the struct that you provide as input.\n\nConsider the following code example. We create a new custom struct called `Person`. This\nstruct contains three different data members, or, three different fields. As consequence,\nwhen we provide this `Person` data type as input to `MultiArrayList()`, this\ncreates a \"struct of three different arrays\" called `PersonArray`. In other words,\nthis `PersonArray` is a struct that contains three internal dynamic arrays in it.\nOne array for each field found in the `Person` struct definition.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Person = struct {\n    name: []const u8,\n    age: u8,\n    height: f32,\n};\nconst PersonArray = std.MultiArrayList(Person);\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var people = PersonArray{};\n    defer people.deinit(allocator);\n\n    try people.append(allocator, .{\n        .name = \"Auguste\", .age = 15, .height = 1.54\n    });\n    try people.append(allocator, .{\n        .name = \"Elena\", .age = 26, .height = 1.65\n    });\n    try people.append(allocator, .{\n        .name = \"Michael\", .age = 64, .height = 1.87\n    });\n}\n```\n:::\n\n\n\n\nIn other words, instead of creating an array of \"persons\", the `MultiArrayList()` function\ncreates a \"struct of arrays\". Each data member of this struct is a different array that stores\nthe values of a specific field from the `Person` values that were added (or, appended) to this \"struct of arrays\".\nOne important detail is that each of these separate internal arrays stored inside `PersonArray`\nare dynamic arrays. This means that these arrays can grow in capacity automatically as needed, to accomodate\nmore values.\n\nThe @fig-multi-array exposed below presents a diagram that describes the `PersonArray` struct\nthat we have created in the previous code example. Notice that the values of the data members\npresent in each of the three `Person` values that we have appended into the `PersonArray` object\n, are scattered across three different internal arrays of the `PersonArray` object.\n\n![A diagram of the `PersonArray` struct.](./../Figures/multi-array.png){#fig-multi-array}\n\nYou can easily access each of these arrays separately, and iterate over the values of each array.\nFor that, you will need to call the `items()` method from the `PersonArray` object, and provide as input\nto this method, the name of the field that you want to iterate over.\nIf you want to iterate through the `.age` array for example, then, you need to call `items(.age)` from\nthe `PersonArray` object, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (people.items(.age)) |*age| {\n    try stdout.print(\"Age: {d}\\n\", .{age.*});\n}\n```\n:::\n\n\n\n\n```\nAge: 15\nAge: 26\nAge: 64\n```\n\n\nIn the above example, we are iterating over the values of the `.age` array, or,\nthe internal array of the `PersonArray` object that contains the values of the `age`\ndata member from the `Person` values that were added to the multi array struct.\n\nIn this example we are calling the `items()` method directly from the `PersonArray`\nobject. However, in most situations it's recommened to call this `items()` method\nfrom a \"slice object\", which you can create from the `slice()` method.\nThe reason for this is that calling `items()` multiple times have better performance\nif you use a slice object.\n\nTherefore, if you are planning to access only one of the\ninternal arrays from your \"multi array struct\", it's fine to call `items()` directly\nfrom the multi array object. But if you need to access many of the internal arrays\nfrom your \"multi array struct\", then, you will likely need to call `items()` more\nthan once, and, in such circumstance, is better to call `items()` through a slice object.\nThe example below demonstrates the use of such object:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar slice = people.slice();\nfor (slice.items(.age)) |*age| {\n    age.* += 10;\n}\nfor (slice.items(.name), slice.items(.age)) |*n,*a| {\n    try stdout.print(\n        \"Name: {s}, Age: {d}\\n\", .{n.*, a.*}\n    );\n}\n```\n:::\n\n\n\n\n```\nName: Auguste, Age: 25\nName: Elena, Age: 36\nName: Michael, Age: 74\n```\n\n\n## Conclusion\n\nThere are many other data structures that I haven't presented here.\nBut you can check them out at the official Zig Standard Library documentation page.\nActually, when you get into the [homepage of the documentation](https://ziglang.org/documentation/master/std/#)[^home], the first thing\nthat appears to you in this page, is a list of types and data structures that\nare available in the Zig Standard Library.\nThere are some very specific data structures in this list, like a\n[`BoundedArray` struct](https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray)[^bounded]\n, but there is also some more general structures, such as a\n[`PriorityQueue` struct](https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue)[^priority].\n\n\n[^home]: <https://ziglang.org/documentation/master/std/#>\n[^priority]: <https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue>.\n[^bounded]: <https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray>\n",
-    "supporting": [
-      "09-data-structures_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Data Structures\n\nIn this chapter, I want to present the most common Data Structures that are available from\nthe Zig Standard Library, especially `ArrayList` and also `HashMap`. These are generic Data Structures\nthat you can use to store and control any type of data that is produced by your application.\n\n## Dynamic Arrays {#sec-dynamic-array}\n\nIn high level languages, arrays are usually dynamic. They can easily grow\nin size when they have to, and you don't need to worry about it.\nIn contrast, arrays in low level languages are usually static by default.\nThis is the reality of C, C++, Rust and also Zig. Static arrays were presented at\n@sec-arrays, but in this section, we are going to talk about dynamic arrays in Zig.\n\nDynamic arrays are simply arrays that can grow in size during the runtime\nof your program. Most low level languages have some implementation of\na dynamic array in their standard library. C++ have `std::vector`, Rust have `Vec`,\nand Zig have `std.ArrayList`.\n\nThe `std.ArrayList` struct provides a contiguous and growable array for you.\nIt works like any other dynamic array, it allocates a contiguous block of memory, and when this block have no space left,\n`ArrayList` allocates another contiguous and bigger block of memory, copies the\nelements to this new location, and erases (or frees) the previous block of memory.\n\n\n### Capacity vs Length\n\nWhen we talk about dynamic arrays, we usually have two similar concepts that\nare very essential to how a dynamic array works behind the hood.\nThese concepts are *capacity* and *length*. In some contexts, especially\nin C++, *length* is also called of *size*.\n\nAlthough they look similar, these concepts represent different things\nin the context of a dynamic array. *Capacity* is the number of items (or elements)\nthat your dynamic array can currently hold without the need to allocate more memory.\n\nIn contrast, the *length* refers to how many elements in the array\nare currently being used, or, in other words, how many elements in this array\nthat you have assigned a value to. Every dynamic array works around\na block of allocated memory, which represents an array with total capacity for $n$ elements.\nHowever, only a portion of these $n$ elements are being used most of the time. This portion\nof $n$ is the *length* of the array. So every time you append a new value\nto the array, you are incrementing its *length* by one.\n\nThis means that a dynamic array usually works with an extra margin, or an extra space\nthat is currently empty, but waiting and ready to be used. This \"extra space\"\nis essentially the difference between *capacity* and *length*. *Capacity* represents\nthe total number of elements that the array can hold without the need to re-allocate\nor re-expand the array, while the *length* represents how much of this capacity\nis currently being used to hold/store values.\n\n@fig-capacity-length presents this idea visually. Notice that, at first,\nthe capacity of the array is greater than the length of the array.\nSo, the dynamic array have extra space that is currently empty, but it\nis ready to receive a value to be stored.\n\n![Difference between capacity and length in a dynamic array](./../Figures/dynamic-array.png){#fig-capacity-length}\n\nWe can also see in @fig-capacity-length that, when *length* and *capacity* are equal, it means that the array have no space left.\nWe have reached the ceiling of our capacity, and because of that, if we want to store more values\nin this array, we need to expand it. We need to get a bigger space that can hold more values\nthan what we currently have.\n\nA dynamic array works by expanding the underlying array, whenever the *length* becomes equal\nto the *capacity* of the array. It basically allocates a new contiguous block of memory that is bigger\nthan the previous one, then, it copies all values that are currently being stored to this new\nlocation (i.e., this new block of memory), then, it frees the previous block of\nmemory. At the end of this process, the new underlying array have a bigger *capacity*, and, therefore,\nthe *length* becomes, once again, smaller than the *capacity* of the array.\n\nThis is the cycle of a dynamic array. Notice that, throughout this cycle, the *capacity* is always\neither equal to or higher than the *length* of the array. If you have an `ArrayList` object (let's suppose\nyou named it `buffer`), you can check the current capacity of your array by accessing the `capacity`\nattribute of your `ArrayList` object, while the current *length* of it is available at the `items.len`\nattribute.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// Check capacity\nbuffer.capacity;\n// Check length\nbuffer.items.len;\n```\n:::\n\n\n\n### Creating an `ArrayList` object\n\nIn order to use `ArrayList`, you must provide an allocator object to it.\nRemember, Zig does not have a default memory allocator. And as I described in @sec-allocators, all memory\nallocations must be done by an allocator object that you define, that\nyou have control over. In our example here, I'm going to use\na general purpose allocator, but you can use any other allocator\nof your preference.\n\nWhen you initialize an `ArrayList` object, you must provide the data type of the elements of\nthe array. In other words, this defines the type of data that this array (or container) will\nstore. Therefore, if I provide the `u8` type to it, then, I will create a dynamic\narray of `u8` values. However, if I provide a struct that I have defined instead, like the struct `User`\nfrom @sec-structs-and-oop, then, a dynamic array of `User` values\nwill be created. In the example below, with the expression `ArrayList(u8)` we\nare creating a dynamic array of `u8` values.\n\nAfter you provide the data type of the elements of the array, you can initialize\nan `ArrayList` object by either using the `init()` or the `initCapacity()` methods.\nThe former method receives only the allocator object\nas input, while the latter method receives both the allocator object and a capacity number as inputs.\nWith the latter method, you not only initialize the struct, but you\nalso set the starting capacity of the allocated array.\n\nUsing the `initCapacity()` method is the preferred way to initialize your dynamic array.\nBecause reallocations, or, in other words, the process of expanding the capacity of the array,\nis always a high cost operation. You should take any possible opportunity to avoid reallocations in\nyour array. If you know how much space your array needs to occupy at the beginning,\nyou should always use `initCapacity()` to create your dynamic array.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n```\n:::\n\n\n\nIn the example above, the `buffer` object starts as an array of 100 elements. If this\n`buffer` object needs to create more space to accomodate more elements during the runtime of your program, the `ArrayList`\ninternals will perform the necessary actions for you automatically.\nAlso notice the `deinit()` method being used to destroy the `buffer` object at the\nend of the current scope, by freeing all the memory that was allocated for the dynamic\narray stored in this `buffer` object.\n\n\n### Adding new elements to the array\n\nNow that we have created our dynamic array, we can start to use it. You can append (a.k.a \"add\")\nnew values to this array by using the `append()` method. This method works the same way\nas the `append()` method from a Python list, or, the `emplace_back()` method from `std::vector` of C++.\nYou provide a single value to this method, and the method appends this value to the array.\n\nYou can also use the `appendSlice()` method to append multiple values at once. You provide\na slice (slices were described in @sec-arrays) to this method, and the method adds all values present\nin this slice to your dynamic array.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry buffer.append('H');\ntry buffer.append('e');\ntry buffer.append('l');\ntry buffer.append('l');\ntry buffer.append('o');\ntry buffer.appendSlice(\" World!\");\n```\n:::\n\n\n### Removing elements from the array {#sec-dynamic-array-remove}\n\nYou can use the `pop()` method to \"pop\" or remove\nthe last element in the array. It's worth noting that this method\ndo not change the capacity of the array. It just deletes or erases\nthe last value stored in the array.\n\nAlso, this method returns as result the value that got deleted. That is, you can\nuse this method to both get the last value in the array, and also, remove\nit from the array. It's a \"get and remove value\" type of method.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exclamation_mark = buffer.pop();\n```\n:::\n\n\nNow, if you want to remove specific elements from specific positions\nof your array, you can use the `orderedRemove()` method from your\n`ArrayList` object. With this method, you can provide an index as input,\nthen, the method will delete the value that is at this index in the array.\nYou are effectively reducing the *length* of the array everytime you execute\nan `orderedRemove()` operation.\n\nIn the example below, we first create an `ArrayList` object, and we fill it\nwith numbers. Then, we use `orderedRemove()` to remove the value at\nindex 3 in the array, two consecutive times.\n\nAlso, notice that we are assigning the result of `orderedRemove()` to the\nunderscore character. So we are discarding the result value of this method.\nThe `orderedRemove()` method returns the value that got deleted, in a similar\nstyle to the `pop()` method.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n\nfor (0..10) |i| {\n    const index: u8 = @intCast(i);\n    try buffer.append(index);\n}\n\nstd.debug.print(\n    \"{any}\\n\", .{buffer.items}\n);\n_ = buffer.orderedRemove(3);\n_ = buffer.orderedRemove(3);\n\nstd.debug.print(\"{any}\\n\", .{buffer.items});\nstd.debug.print(\"{any}\\n\", .{buffer.items.len});\n```\n:::\n\n\n```\n{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }\n{ 0, 1, 2, 5, 6, 7, 8, 9 }\n8\n```\n\nOne key characteristic about `orderedRemove()` is that it preserves the order\nof the values in the array. So, it deletes the value that you asked it to\nremove, but it also makes sure that the order of the values that remain in the array\nstay the same as before.\n\nNow, if you don't care about the order of the values, for example, maybe you want to treat\nyour dynamic array as a set of values, like the `std::unordered_set`\nstructure from C++, you can use the `swapRemove()` method instead. This method\nworks similarly to the `orderedRemove()` method. You give an index to this\nmethod, then, it deletes the value that is at this index in the array.\nBut this method does not preserve the original order of the values that remain\nin the array. As a result, `swapRemove()` is, in general, faster than `orderedRemove()`.\n\n\n### Inserting elements at specific indexes\n\nWhen you need to insert values in the middle of your array,\ninstead of just appending them to the end of the array, you need to use\nthe `insert()` and `insertSlice()` methods, instead of\nthe `append()` and `appendSlice()` methods.\n\nThese two methods work very similarly to `insert()` and `insert_range()`\nfrom the C++ `std::vector` class. You provide an index to these methods,\nand they insert the values that you provide at that index in the array.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 10);\ndefer buffer.deinit();\n\ntry buffer.appendSlice(\"My Pedro\");\ntry buffer.insert(4, '3');\ntry buffer.insertSlice(2, \" name\");\nfor (buffer.items) |char| {\n    try stdout.print(\"{c}\", .{char});\n}\n```\n:::\n\n\n```\nMy name P3edro\n```\n\n\n### Conclusion\n\nIf you feel the lack of some other method, I recommend\nyou to read the [official documentation for the `ArrayListAligned`](https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned)[^zig-array2]\nstruct, which describes most of the methods available\nthrough the `ArrayList` object.\n\nYou will notice that there is a lot of other methods in this page that\nI did not described here, and I recommend you to explore these methods,\nand understand how they work.\n\n[^zig-array2]: <https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned>\n\n\n\n## Maps or HashTables {#sec-maps-hashtables}\n\nSome professionals know this type of data structure by different terms, like \"map\",\n\"hashmap\" or \"associative arrays\". But the most common term used is *hashtable*.\nEvery programming language normally have some implementation of a hashtable in their\nstandard libraries. Python have `dict()`, C++ have `std::map` and `std::unordered_map`, Rust\nhave `HashMap`, Javascript have `Object()` and `Map()`, etc.\n\n\n\n### What is a hashtable?\n\nA hashtable is a data structure based on key-value pairs.\nYou provide a key and a value to this structure, then, the hashtable will store\nthe input value at a location that can be identified by the input\nkey that you provided.\nIt does that by using an underlying array and a hash function.\nThese two components are essential to how a hashtable works.\n\nUnder the hood, the hashtable contains an array. This array is where the values\nare stored, and the elements of this array are usually called of *buckets*.\nSo the values that you provide to the hashtable are stored inside buckets,\nand you access each bucket by using an index.\n\nWhen you provide a key to a hashtable, it passes this key to the\nhash function. This hash function uses some sort of hashing algorithm to transform\nthis key into an index. This index is actually an array index. It's a position\nin the underlying array of the hashtable.\nThis is how a key identifies a specific position (or location) inside the hashtable\nstructure.\n\nTherefore, you provide a key to the hashtable, and this key identifies a specific location\ninside the hashtable, then, the hashtable takes the input value that you provided,\nand stores this value in the location identified by this input key.\nYou could say that the key maps to the value stored in the hashtable. You find\nthe value, by using the key that identifies the location where the value is stored.\nThe @fig-hashtable presents this process visually.\n\n\n![A diagram of a Hashtable. Source: Wikipedia, the free encyclopedia.](./../Figures/hashtable.svg){#fig-hashtable}\n\n\nThe operation described in the previous paragraph is normally called an *insertion* operation.\nBecause you are inserting new values into the hashtable.\nBut there are other types of operations in hashtables such as *delete* and *lookup*.\nDelete is self describing, it's when you delete (or remove) a value from the hashtable.\nWhile lookup corresponds to when you look at a value that is stored in\nthe hashtable, by using the key that identifies the location where this value is stored.\n\nSometimes, instead of storing the values directly, the underlying array of the hashtable might be an array of pointers,\ni.e., the buckets of the array stores pointers that points to the value,\nor also, may be an array of linked lists.\nThese cases are common on hashtables that allows duplicate keys, or, in other words,\non hashtables that effectively handle \"collisions\" that may arise from the hash function.\n\nDuplicate keys, or this \"collision\" thing that I'm talking about, is when you have two different keys\nthat points to the same location (i.e., to the same index)\nin the underlying array of the hashtable. This might happen depending on the characteristics of the hash function\nthat is being used in the hashtable. Some implementations of the hashtable will actively deal with collisions,\nmeaning that, they will handle this case in some way. For example, the hashtable\nmight transform all buckets into linked lists. Because with a linked list you can store\nmultiple values into a single bucket.\n\nThere are different techniques to handle collisions in hashtables, which I will not describe\nin this book, because it's not our main scope here. But you can find a good description of\nsome of the most common techniques at the Wikipedia page of hashtables [@wikipedia_hashtables].\n\n\n### Hashtables in Zig {#sec-hashmap}\n\nThe Zig Standard Library provides different implementations of a hashtable.\nEach implementation have its own cons and pros, which we will\ndiscuss later on, and all of them are available through the `std.hash_map` module.\n\nThe `HashMap` struct is a general-purpose hashtable,\nwhich have very fast operations (lookup, insertion, delete), and also,\nquite high load factors for low memory usage. You can create and provide a context object\nto the `HashMap` constructor. This context object allows you to tailor\nthe behaviour of the hashtable itself, because you can\nprovide a hash function implementation to be used by the hashtable\nthrough this context object.\n\nBut let's not worry about this context object now, because it's meant to be used\nby \"experts in the field of hashtables\". Since we are most likely not\nexperts in this field, we are going to take the easy way to create\na hashtable. Which is by using the `AutoHashMap()` function.\n\n\nThis `AutoHashMap()` function is essentially a \"create a hashtable object that uses the default settings\"\ntype of function. It automatically chooses a context object, and, therefore, a hash function implementation,\nfor you. This function receives two data types as input, the first input is the data type of the keys\nthat will be used in this hashtable, while the second input is the data type of the data that will be\nstored inside the hashtable, that is, the data type of the values to be stored.\n\nIn the example below, we are providing the data type `u32` in the first argument, and `u16` in the second argument of this\nfunction. This means that we are going to use `u32` values as keys in this hashtable, while `u16` values are the actual values\nthat are going to be stored into this hashtable.\nAt the end of this process, the `hash_table` object contains a `HashMap` object\nthat uses the default settings and context.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n    std.debug.print(\n        \"Value at key 50050: {d}\\n\",\n        .{hash_table.get(50050).?}\n    );\n\n    if (hash_table.remove(57709)) {\n        std.debug.print(\n            \"Value at key 57709 successfully removed!\\n\",\n            .{}\n        );\n    }\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n}\n```\n:::\n\n\n```\nN of values stored: 3\nValue at key 50050: 55\nValue at key 57709 successfully removed!\nN of values stored: 2\n```\n\nYou can add/put new values into the hashtable by using the `put()` method. The first argument\nis the key to be used, and the second argument is the actual value that you want to store inside\nthe hashtable. In the example below, we first add the value 89 using the key 54321, next, we add\nthe value 55 using the key 50050, etc.\n\nNotice that we have used the method `count()` to see how many values are currently stored in the\nhashtable. After that, we also use the `get()` method to access (or look) at the value stored in\nthe position identified by the key 500050. The output of this `get()` method is an optional value.\nThis is why we use the `?` method at the end to get the actual value.\n\nAlso notice that we can remove (or delete) values from the hashtable by using the `remove()` method.\nYou provide the key that identifies the value that you want to delete, then, the method will\ndelete this value and return a `true` value as output. This `true` value essentially tells us\nthat the method successfully deleted the value.\n\nBut this delete operation might not be always successful. For example, you might provide the wrong\nkey to this method. I mean, maybe you provide\n(either intentionally or unintentionally) a key that points to an empty bucket,\ni.e., a bucket that still doesn't have a value in it.\nIn this case, the `remove()` method would return a `false` value.\n\n\n\n### Iterating through the hashtable\n\nIterating through the keys and values that are currently being stored in\nthe hashtable is a very common necessity.\nYou can do that in Zig by using an iterator object that can iterate\nthrough the elements of your hashtable object.\n\nThis iterator object works like any other iterator object that you would\nfind in languages such as C++ and Rust. It's basically a pointer object\nthat points to some value in the container, and has a `next()` method\nthat you can use to navigate (or iterate) through the values in the\ncontainer.\n\nYou can create such iterator object by using the `iterator()` method of the hashtable object.\nThis method returns an iterator object, from which you can use the `next()` method in conjunction\nwith a while loop to iterate through the elements of your hashtable. The `next()` method returns an optional\n`Entry` value, and therefore, you must unwrap this optional value to get the actual `Entry` value\nfrom which you can access the key and also the value identified by this key.\n\nWith this `Entry` value at hand, you can access the key of this current entry by using the `key_ptr`\nattribute and dereferencing the pointer that lives inside of it, while the value identified by this\nkey is accessed through the `value_ptr` attribute instead, which is also a pointer to be dereferenced.\nThe code example below demonstrates the use of these elements:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n\n    var it = hash_table.iterator();\n    while (it.next()) |kv| {\n        // Access the current key\n        std.debug.print(\"Key: {d} | \", .{kv.key_ptr.*});\n        // Access the current value\n        std.debug.print(\"Value: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n:::\n\n\n```\nKey: 54321 | Value: 89\nKey: 50050 | Value: 55\nKey: 57709 | Value: 41\n```\n\n\nIf you want to iterate specifically through the values or the keys of your hashtable,\nyou can create a key iterator or a value iterator object. These are also iterator\nobjects, which have the same `next()` method that you can use to iterate through the\nhashtable.\n\nKey iterators are created from the `keyIterator()` method of your\nhashtable object, while value iterators are created from the `valueIterator()` method.\nAll you have to do is to unwrap the value from the `next()` method and deference it\ndirectly to access the key or the value that you are iterating over.\nThe code example below demonstrates the use of a key iterator,\nbut you can replicate the same logic to a value iterator.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar kit = hash_table.keyIterator();\nwhile (kit.next()) |key| {\n    std.debug.print(\"Key: {d}\\n\", .{key.*});\n}\n```\n:::\n\n\n```\nKey: 54321\nKey: 50050\nKey: 57709\n```\n\n\n### The `ArrayHashMap` hashtable {#sec-array-map}\n\nIf you need to iterate through the elements of your hashtable constantly,\nyou might want to use the `ArrayHashMap` struct for your specific case,\ninstead of going with the usual and general-purpose `HashMap` struct.\n\nThe `ArrayHashMap` struct creates a hashtable that is faster to iterate over.\nThat is why this specific type of hashtable might be valuable to you.\nSome other properties of a `ArrayHashMap` hashtable are:\n\n- the order of insertion is preserved, i.e., the order of the values that you find while iterating through this hashtable is actually the order in which these values were inserted in the hashtable.\n- the key-value pairs are stored sequentially, one after another.\n\n\nYou can create an `ArrayHashMap` object by using, once again, a helper function that\nchooses automatically for you a hash function implementation. This is the\n`AutoArrayHashMap()` function, which works very similarly to the `AutoHashMap()`\nfunction that we presented in @sec-hashmap.\n\nYou provide two data types to this function. The data type of the keys that will be\nused in this hashtable, and the data type of the values that will be stored in\nthis hashtable.\n\nAn `ArrayHashMap` object have essentially the exact same methods from the `HashMap` struct.\nSo you can insert new values into the hashtable by using the `put()` method, and you can look (or get)\na value from the hashtable by using the `get()` method. But the `remove()` method is not available\nin this specific type of hashtable.\n\nIn order to delete values from the hashtable, you would use the same methods that you find in\nan `ArrayList` object, i.e., a dynamic array. I presented these methods in @sec-dynamic-array-remove,\nwhich are the `swapRemove()` and `orderedRemove()` methods. These methods have the same meaning here, or,\nthe same effect that they have in an `ArrayList` object.\n\nThis means that, with `swapRemove()` you remove the value from the hashtable, but you do not preserve\nthe order in which the values were inserted into the structure. While `orderedRemove()` is able\nto retain the order in which these values were inserted.\n\nBut instead of providing an index as input to `swapRemove()` or `orderedRemove()`, like I described\nin @sec-dynamic-array-remove, these methods here in an `ArrayHashMap` take a key as input, like\nthe `remove()` method from a `HashMap` object. If you want to provide an index as input, instead\nof a key, you should use the `swapRemoveAt()` and `orderedRemoveAt()` methods.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar hash_table = AutoArrayHashMap(u32, u16)\n    .init(allocator);\ndefer hash_table.deinit();\n```\n:::\n\n\n\n\n### The `StringHashMap` hashtable {#sec-string-hash-map}\n\nOne thing that you will notice in the other two types of hashtables that I have\npresented over the last sections, is that neither of them accepts a slice data type\nin their keys.\nWhat this means is that you cannot use a slice value to represent a key in\nthese types of hashtable.\n\nThe most obvious consequence of this, is that you cannot use strings as keys\nin these hashtables. But it's extremely common to use strings as keys\nin hashtables.\n\nTake this very simple Javascript code snippet as an example. We are creating\na simple hashtable object named `people`. Then, we add a new entry to this\nhashtable, which is identified by the string `'Pedro'`. This string is the\nkey in this case, while the object containing different personal information such as\nage, height and city, is the value to be stored in the hashtable.\n\n```js\nvar people = new Object();\npeople['Pedro'] = {\n    'age': 25,\n    'height': 1.67,\n    'city': 'Belo Horizonte'\n};\n```\n\nThis pattern of using strings as keys is very common in\nall sorts of situations. That is why the Zig Standard Library offers a\nspecific type of hashtable for this purpose, which is created through the `StringHashMap()` function.\nThis function creates a hashtable that uses strings as keys. The only input of this\nfunction is the data type of the values that will be stored into this hashtable.\n\nIn the example below, I'm creating a hashtable to store the ages of different people.\nEach key in this hashtable is represented by the name of each person, while the value stored in the\nhashtable is the age of this person identified by the key.\n\nThat is why I provide the `u8` data type (which is the data type used by the age values) as input to this `StringHashMap()` function.\nAs the result, it creates a hashtable that uses string values as keys, and, that stores\n`u8` values in it. Notice that an allocator object is provided at the `init()` method of the\nresulting object from the `StringHashMap()` function.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var ages = std.StringHashMap(u8).init(allocator);\n    defer ages.deinit();\n\n    try ages.put(\"Pedro\", 25);\n    try ages.put(\"Matheus\", 21);\n    try ages.put(\"Abgail\", 42);\n\n    var it = ages.iterator();\n    while (it.next()) |kv| {\n        std.debug.print(\"Key: {s} | \", .{kv.key_ptr.*});\n        std.debug.print(\"Age: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n:::\n\n\n```\nKey: Pedro | Age: 25\nKey: Abgail | Age: 42\nKey: Matheus | Age: 21\n```\n\n\n### The `StringArrayHashMap` hashtable\n\nThe Zig Standard Library also provides a type of hashtable that mix the cons and pros of the\n`StringHashMap` and `ArrayHashMap` together. That is, a hashtable\nthat uses strings as keys, but also have the advantages from `ArrayHashMap`.\nIn other words, you can have a hashtable that is fast to iterate over,\nthat preserves insertion order, and also, that uses strings as keys.\n\nYou can create such type of hashtable by using the `StringArrayHashMap()` function.\nThis function accepts a data type as input, which is the data type of the values that are\ngoing to be stored inside this hashtable, in the same style as the function presented\nin @sec-string-hash-map.\n\nYou can insert new values into this hashtable by using the same `put()` method that\nwe have discussed in @sec-string-hash-map. And you can also get values from the hashtable\nby using the same `get()` method.\nLike its `ArrayHashMap` brother, to delete values from this specific type of hashtable,\nwe also use the `orderedRemove()` and `swapRemove()` methods, with the same effects that\nI have described in @sec-array-map.\n\nIf we take the code example that was exposed in @sec-string-hash-map, we can\nachieve the exact same result with `StringArrayHashMap()`:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar ages = std.StringArrayHashMap(u8).init(allocator);\n```\n:::\n\n\n\n\n\n## Linked lists\n\nThe Zig Standard Library provides an implementation for both singly and doubly linked lists.\nMore specifically, through the structs `SinglyLinkedList` and `DoublyLinkedList`.\n\nIn case you are not familiar with these data structures, a linked list is a linear data structure that looks\nlike a chain, or, a rope. The main advantage of this data structure is that you normally have very fast\ninsertion and deletion operations. But, as a disadvantage, iterating through\nthis data structure is usually not so fast as iterating through an array.\n\nThe idea behind a linked list is to build a structure that consists of a sequence of nodes\nconnected to each other by pointers. This means that linked lists are usually not contiguous\nin memory, because each node might be anywhere in memory. They do not need to be close to\none another.\n\nIn @fig-linked-list we can see a diagram of a singly linked list. We begin at the first node\n(which is usually called \"the head of the linked list\"). Then, from this\nfirst node we uncover the remaining nodes in the structure, by following the locations pointed\nby the pointers found in each node.\n\nEach node has two things in it. It has the value that is stored in the current node\n, and also, a pointer. This pointer points to the next node in the list. If this pointer\nis null, then, it means that we have reached the end of our linked list.\n\n![A diagram of a singly linked list.](./../Figures/linked-list.png){#fig-linked-list}\n\n\nIn @fig-linked-list2 we can see a diagram of a doubly linked list. The only thing that really\nchanges now is that every node in the linked list has both a pointer to the previous node,\nand, a pointer to the next node. So every node in a doubly linked list has two pointers in it. These are\nusually called the `prev` (for \"previous\") and the `next` (for \"next\") pointers of the node.\n\nIn the singly linked list example, we had only one single pointer in each node, and this singular\npointer was always pointing to the next node in the sequence. This means that singly linked lists\nnormally have only the `next` pointer in them.\n\n![A diagram of a doubly linked list.](./../Figures/doubly-linked-list.png){#fig-linked-list2}\n\n\n\n### Recent change in the API\n\nOn previous versions of Zig, the `SinglyLinkedList` and `DoublyLinkedList` structs were initially implemented as \"generics data structures\".\nMeaning that, you would use a generic function to create a singly (or doubly) linked list that could store\nthe specific data type that you wanted to use. We will learn more about generics at @sec-generics, and also,\nhow we can create a \"generic data structure\" at @sec-generic-struct.\n\nHowever, on the latest versions of Zig, the structs `SinglyLinkedList` and `DoublyLinkedList` were altered to use a\n\"less generic API\". This specific change was introduced on April 3, 2025. Therefore, check if your Zig version is one released after this\ndate. Just have in mind that if you don't have a very recent version of the Zig compiler,\nyou might have problems while trying to compile the next examples exposed here.\n\n\n\n### How to use a singly linked list\n\nFor example, consider that you are creating a singly linked list that is going to store `u32` values.\nGiven this scenario, the first thing that we need to do, is to create a \"node type\" that is capable\nof storing a `u32` value. The `NodeU32` type exposed below demonstrates such \"node type\".\n\nNotice that the data type associated with the member named `data` is the most important part of this\ncustom \"node type\". It determines the data type that is going to be stored in each node.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\nconst NodeU32 = struct {\n    data: u32,\n    node: std.SinglyLinkedList.Node = .{},\n};\n```\n:::\n\n\nAfter we created our custom \"node type\" that can store the specific data type that we\nwant, we can just create a new and empty singly linked list, which will store our nodes.\nTo do that, we just create a new object with the type `SinglyLinkedList`, like this:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar list: std.SinglyLinkedList = .{};\n```\n:::\n\n\nNow, we have our linked list... But how can we insert nodes in it? Well, first of all,\nwe need to create our nodes. So let's focus on that first. The snippet exposed below demonstrates\nhow we could use our `NodeU32` struct to create such nodes.\n\nNotice in this snippet that we are just setting the `data` member of the struct for now.\nWe don't need to connect these nodes together in this first instance. This is why we ignore\nthe `node` member at first. But we are going to connect these nodes in a future point of the code, which is\nwhy these objects are marked as \"variable objects\", so that we can alter them in the future.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n```\n:::\n\n\nNow that we have both the linked list and also the nodes created, we can start to connect them together.\nYou can use the `prepend()` method from the linked list object to insert the first node in the list, which\nis the \"head\" of the linked list. As the name suggests, this specific method prepends the input node to the linked list,\nor, in other words, it transforms the input node into the first node of the list.\n\nAfter we added the \"head node\" of the list, we can start to add the \"next nodes\" in the list by using the `insertAfter()` method\nfrom the `SinglyLinkedList.Node` type, which, in our case here, is accessible through the `node` member of our\n`NodeU32` type. Thus, we can start to create the connections between the nodes by calling this method from the node objects\nthat are present in the list. Like in this example below:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nlist.prepend(&two.node); // {2}\ntwo.node.insertAfter(&five.node); // {2, 5}\ntwo.node.insertAfter(&three.node); // {2, 3, 5}\n```\n:::\n\n\nYou can also call the `prepend()` method again to add new nodes to the beginning of the linked list, which\nmeans, effectively, changing the \"head node\" of the list, like this:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nlist.prepend(&one.node); // {1, 2, 3, 5}\n```\n:::\n\n\n\nThere are other methods available from the singly linked list object that you might be interested. You can find a\nsummary of them in the bullet points below:\n\n- `remove()` to remove a specific node from the linked list.\n- `len()` to count how many nodes there is in the linked list.\n- `popFirst()` to remove the first node (i.e., the \"head\") from the linked list.\n\nSo, that is how singly linked lists work in Zig in a nutshell. To sum up what we have exposed here,\nthis is all the source code that was exposed in this section inside the single cell:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst NodeU32 = struct {\n    data: u32,\n    node: std.SinglyLinkedList.Node = .{},\n};\n\nvar list: std.SinglyLinkedList = .{};\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nlist.prepend(&two.node); // {2}\ntwo.node.insertAfter(&five.node); // {2, 5}\ntwo.node.insertAfter(&three.node); // {2, 3, 5}\nlist.prepend(&one.node); // {1, 2, 3, 5}\n\ntry stdout.print(\"Number of nodes: {}\", .{list.len()});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nNumber of nodes: 4\n```\n\n\n:::\n:::\n\n\n\n## Multi array structure\n\nZig introduces a new data structure called `MultiArrayList()`. It's a different version of the dynamic array\nthat we have introduced in @sec-dynamic-array. The difference between this structure and the `ArrayList()`\nthat we know from @sec-dynamic-array, is that `MultiArrayList()` creates a separate dynamic array\nfor each field of the struct that you provide as input.\n\nConsider the following code example. We create a new custom struct called `Person`. This\nstruct contains three different data members, or, three different fields. As consequence,\nwhen we provide this `Person` data type as input to `MultiArrayList()`, this\ncreates a \"struct of three different arrays\" called `PersonArray`. In other words,\nthis `PersonArray` is a struct that contains three internal dynamic arrays in it.\nOne array for each field found in the `Person` struct definition.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Person = struct {\n    name: []const u8,\n    age: u8,\n    height: f32,\n};\nconst PersonArray = std.MultiArrayList(Person);\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var people = PersonArray{};\n    defer people.deinit(allocator);\n\n    try people.append(allocator, .{\n        .name = \"Auguste\", .age = 15, .height = 1.54\n    });\n    try people.append(allocator, .{\n        .name = \"Elena\", .age = 26, .height = 1.65\n    });\n    try people.append(allocator, .{\n        .name = \"Michael\", .age = 64, .height = 1.87\n    });\n}\n```\n:::\n\n\nIn other words, instead of creating an array of \"persons\", the `MultiArrayList()` function\ncreates a \"struct of arrays\". Each data member of this struct is a different array that stores\nthe values of a specific field from the `Person` values that were added (or, appended) to this \"struct of arrays\".\nOne important detail is that each of these separate internal arrays stored inside `PersonArray`\nare dynamic arrays. This means that these arrays can grow in capacity automatically as needed, to accomodate\nmore values.\n\nThe @fig-multi-array exposed below presents a diagram that describes the `PersonArray` struct\nthat we have created in the previous code example. Notice that the values of the data members\npresent in each of the three `Person` values that we have appended into the `PersonArray` object\n, are scattered across three different internal arrays of the `PersonArray` object.\n\n![A diagram of the `PersonArray` struct.](./../Figures/multi-array.png){#fig-multi-array}\n\nYou can easily access each of these arrays separately, and iterate over the values of each array.\nFor that, you will need to call the `items()` method from the `PersonArray` object, and provide as input\nto this method, the name of the field that you want to iterate over.\nIf you want to iterate through the `.age` array for example, then, you need to call `items(.age)` from\nthe `PersonArray` object, like in the example below:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (people.items(.age)) |*age| {\n    try stdout.print(\"Age: {d}\\n\", .{age.*});\n}\n```\n:::\n\n\n```\nAge: 15\nAge: 26\nAge: 64\n```\n\n\nIn the above example, we are iterating over the values of the `.age` array, or,\nthe internal array of the `PersonArray` object that contains the values of the `age`\ndata member from the `Person` values that were added to the multi array struct.\n\nIn this example we are calling the `items()` method directly from the `PersonArray`\nobject. However, in most situations it's recommened to call this `items()` method\nfrom a \"slice object\", which you can create from the `slice()` method.\nThe reason for this is that calling `items()` multiple times have better performance\nif you use a slice object.\n\nTherefore, if you are planning to access only one of the\ninternal arrays from your \"multi array struct\", it's fine to call `items()` directly\nfrom the multi array object. But if you need to access many of the internal arrays\nfrom your \"multi array struct\", then, you will likely need to call `items()` more\nthan once, and, in such circumstance, is better to call `items()` through a slice object.\nThe example below demonstrates the use of such object:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar slice = people.slice();\nfor (slice.items(.age)) |*age| {\n    age.* += 10;\n}\nfor (slice.items(.name), slice.items(.age)) |*n,*a| {\n    try stdout.print(\n        \"Name: {s}, Age: {d}\\n\", .{n.*, a.*}\n    );\n}\n```\n:::\n\n\n```\nName: Auguste, Age: 25\nName: Elena, Age: 36\nName: Michael, Age: 74\n```\n\n\n## Conclusion\n\nThere are many other data structures that I haven't presented here.\nBut you can check them out at the official Zig Standard Library documentation page.\nActually, when you get into the [homepage of the documentation](https://ziglang.org/documentation/master/std/#)[^home], the first thing\nthat appears to you in this page, is a list of types and data structures that\nare available in the Zig Standard Library.\nThere are some very specific data structures in this list, like a\n[`BoundedArray` struct](https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray)[^bounded]\n, but there is also some more general structures, such as a\n[`PriorityQueue` struct](https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue)[^priority].\n\n\n[^home]: <https://ziglang.org/documentation/master/std/#>\n[^priority]: <https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue>.\n[^bounded]: <https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray>\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/docs/Chapters/09-data-structures.html b/docs/Chapters/09-data-structures.html
index 5f70ae35..4cf9c0a3 100644
--- a/docs/Chapters/09-data-structures.html
+++ b/docs/Chapters/09-data-structures.html
@@ -345,7 +345,11 @@ <h2 id="toc-title">Table of contents</h2>
   <li><a href="#sec-string-hash-map" id="toc-sec-string-hash-map" class="nav-link" data-scroll-target="#sec-string-hash-map"><span class="header-section-number">11.2.5</span> The <code>StringHashMap</code> hashtable</a></li>
   <li><a href="#the-stringarrayhashmap-hashtable" id="toc-the-stringarrayhashmap-hashtable" class="nav-link" data-scroll-target="#the-stringarrayhashmap-hashtable"><span class="header-section-number">11.2.6</span> The <code>StringArrayHashMap</code> hashtable</a></li>
   </ul></li>
-  <li><a href="#linked-lists" id="toc-linked-lists" class="nav-link" data-scroll-target="#linked-lists"><span class="header-section-number">11.3</span> Linked lists</a></li>
+  <li><a href="#linked-lists" id="toc-linked-lists" class="nav-link" data-scroll-target="#linked-lists"><span class="header-section-number">11.3</span> Linked lists</a>
+  <ul class="collapse">
+  <li><a href="#recent-change-in-the-api" id="toc-recent-change-in-the-api" class="nav-link" data-scroll-target="#recent-change-in-the-api"><span class="header-section-number">11.3.1</span> Recent change in the API</a></li>
+  <li><a href="#how-to-use-a-singly-linked-list" id="toc-how-to-use-a-singly-linked-list" class="nav-link" data-scroll-target="#how-to-use-a-singly-linked-list"><span class="header-section-number">11.3.2</span> How to use a singly linked list</a></li>
+  </ul></li>
   <li><a href="#multi-array-structure" id="toc-multi-array-structure" class="nav-link" data-scroll-target="#multi-array-structure"><span class="header-section-number">11.4</span> Multi array structure</a></li>
   <li><a href="#conclusion-1" id="toc-conclusion-1" class="nav-link" data-scroll-target="#conclusion-1"><span class="header-section-number">11.5</span> Conclusion</a></li>
   </ul>
@@ -685,7 +689,8 @@ <h3 data-number="11.2.6" class="anchored" data-anchor-id="the-stringarrayhashmap
 </section>
 <section id="linked-lists" class="level2" data-number="11.3">
 <h2 data-number="11.3" class="anchored" data-anchor-id="linked-lists"><span class="header-section-number">11.3</span> Linked lists</h2>
-<p>The Zig Standard Library provides an implementation for both singly and doubly linked lists. A linked list is a linear data structure that looks like a chain, or, a rope. The main advantage of this data structure is that you normally have very fast insertion and deletion operations. But, as a disadvantage, iterating through this data structure is usually not so fast as iterating through an array.</p>
+<p>The Zig Standard Library provides an implementation for both singly and doubly linked lists. More specifically, through the structs <code>SinglyLinkedList</code> and <code>DoublyLinkedList</code>.</p>
+<p>In case you are not familiar with these data structures, a linked list is a linear data structure that looks like a chain, or, a rope. The main advantage of this data structure is that you normally have very fast insertion and deletion operations. But, as a disadvantage, iterating through this data structure is usually not so fast as iterating through an array.</p>
 <p>The idea behind a linked list is to build a structure that consists of a sequence of nodes connected to each other by pointers. This means that linked lists are usually not contiguous in memory, because each node might be anywhere in memory. They do not need to be close to one another.</p>
 <p>In <a href="#fig-linked-list" class="quarto-xref">Figure&nbsp;<span>11.3</span></a> we can see a diagram of a singly linked list. We begin at the first node (which is usually called “the head of the linked list”). Then, from this first node we uncover the remaining nodes in the structure, by following the locations pointed by the pointers found in each node.</p>
 <p>Each node has two things in it. It has the value that is stored in the current node , and also, a pointer. This pointer points to the next node in the list. If this pointer is null, then, it means that we have reached the end of our linked list.</p>
@@ -711,75 +716,106 @@ <h2 data-number="11.3" class="anchored" data-anchor-id="linked-lists"><span clas
 </figcaption>
 </figure>
 </div>
-<p>Linked lists are available in Zig through the functions <code>SinglyLinkedList()</code> and <code>DoublyLinkedList()</code>, for “singly linked lists” and “doubly linked lists”, respectively. These functions are actually generic functions, which we are going to talk more about in <a href="10-stack-project.html#sec-generic-fun" class="quarto-xref"><span>Section 12.2.1</span></a>.</p>
-<p>For now, just understand that, in order to create a linked list object, we begin by providing a data type to these functions. This data type defines the type of data that each node in this linked list will store. In the example below, we are creating a singly linked list of <code>u32</code> values. So each node in this linked list will store a <code>u32</code> value.</p>
-<p>Both the <code>SinglyLinkedList()</code> and <code>DoublyLinkedList()</code> functions returns a type, i.e., a struct definition, as output. Therefore, the object <code>Lu32</code> is actually a struct definition. It defines the type “singly linked list of <code>u32</code> values”.</p>
-<p>Now that we have the definition of the struct, we need to instantiate a <code>Lu32</code> object. We normally instantiate struct objects in Zig by using an <code>init()</code> method. But in this case, we are instantiating the struct directly, by using an empty <code>struct</code> literal, in the expression <code>Lu32{}</code>.</p>
-<p>In this example, we first create multiple node objects, and after we create them, we start to insert and connect these nodes to build the linked list, using the <code>prepend()</code> and <code>insertAfter()</code> methods. Notice that the <code>prepend()</code> method is a method from the linked list object, while the <code>insertAfter()</code> is a method present in the node objects.</p>
-<p>In essence, the <code>prepend()</code> method inserts a node at the beginning of the linked list. In other words, the node that you provide to this method, becomes the new “head node” of the linked list. It becomes the first node in the list (see <a href="#fig-linked-list" class="quarto-xref">Figure&nbsp;<span>11.3</span></a>).</p>
-<p>On the other side, the <code>insertAfter()</code> method is used to basically connect two nodes together. When you provide a node to this method, it creates a pointer to this input node, and stores this pointer in the <code>next</code> attribute of the current node, from which the method was called from.</p>
-<p>Because doubly linked lists have both a <code>next</code> and a <code>prev</code> attributes in each node (as described in <a href="#fig-linked-list2" class="quarto-xref">Figure&nbsp;<span>11.4</span></a>), a node object created from a <code>DoublyLinkedList</code> object have both an <code>insertBefore()</code> (for <code>prev</code>) and an <code>insertAfter()</code> (for <code>next</code>) methods available.</p>
-<p>Thus, if we have used a doubly linked list, we can use the <code>insertBefore()</code> method to store the pointer to the input node in the <code>prev</code> attribute. This would put the input node as the “previous node”, or, the node before the current node. In contrast, the <code>insertAfter()</code> method puts the pointer created to the input node in the <code>next</code> attribute of the current node, and as result, the input node becomes the “next node” of the current node.</p>
-<p>Since we are using a singly linked list in this example, we have only the <code>insertAfter()</code> method available in the node objects that we create from our <code>Lu32</code> type.</p>
+<section id="recent-change-in-the-api" class="level3" data-number="11.3.1">
+<h3 data-number="11.3.1" class="anchored" data-anchor-id="recent-change-in-the-api"><span class="header-section-number">11.3.1</span> Recent change in the API</h3>
+<p>On previous versions of Zig, the <code>SinglyLinkedList</code> and <code>DoublyLinkedList</code> structs were initially implemented as “generics data structures”. Meaning that, you would use a generic function to create a singly (or doubly) linked list that could store the specific data type that you wanted to use. We will learn more about generics at <a href="10-stack-project.html#sec-generics" class="quarto-xref"><span>Section 12.2</span></a>, and also, how we can create a “generic data structure” at <a href="10-stack-project.html#sec-generic-struct" class="quarto-xref"><span>Section 12.2.2</span></a>.</p>
+<p>However, on the latest versions of Zig, the structs <code>SinglyLinkedList</code> and <code>DoublyLinkedList</code> were altered to use a “less generic API”. This specific change was introduced on April 3, 2025. Therefore, check if your Zig version is one released after this date. Just have in mind that if you don’t have a very recent version of the Zig compiler, you might have problems while trying to compile the next examples exposed here.</p>
+</section>
+<section id="how-to-use-a-singly-linked-list" class="level3" data-number="11.3.2">
+<h3 data-number="11.3.2" class="anchored" data-anchor-id="how-to-use-a-singly-linked-list"><span class="header-section-number">11.3.2</span> How to use a singly linked list</h3>
+<p>For example, consider that you are creating a singly linked list that is going to store <code>u32</code> values. Given this scenario, the first thing that we need to do, is to create a “node type” that is capable of storing a <code>u32</code> value. The <code>NodeU32</code> type exposed below demonstrates such “node type”.</p>
+<p>Notice that the data type associated with the member named <code>data</code> is the most important part of this custom “node type”. It determines the data type that is going to be stored in each node.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb20"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb20-1"><a href="#cb20-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb20-2"><a href="#cb20-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> SinglyLinkedList = std.SinglyLinkedList;</span>
-<span id="cb20-3"><a href="#cb20-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Lu32 = SinglyLinkedList(<span class="dt">u32</span>);</span>
-<span id="cb20-4"><a href="#cb20-4" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb20-5"><a href="#cb20-5" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb20-6"><a href="#cb20-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> list = Lu32<span class="op">{}</span>;</span>
-<span id="cb20-7"><a href="#cb20-7" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> one = Lu32.Node<span class="op">{</span> .data = <span class="dv">1</span> <span class="op">}</span>;</span>
-<span id="cb20-8"><a href="#cb20-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> two = Lu32.Node<span class="op">{</span> .data = <span class="dv">2</span> <span class="op">}</span>;</span>
-<span id="cb20-9"><a href="#cb20-9" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> three = Lu32.Node<span class="op">{</span> .data = <span class="dv">3</span> <span class="op">}</span>;</span>
-<span id="cb20-10"><a href="#cb20-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> four = Lu32.Node<span class="op">{</span> .data = <span class="dv">4</span> <span class="op">}</span>;</span>
-<span id="cb20-11"><a href="#cb20-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> five = Lu32.Node<span class="op">{</span> .data = <span class="dv">5</span> <span class="op">}</span>;</span>
-<span id="cb20-12"><a href="#cb20-12" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb20-13"><a href="#cb20-13" aria-hidden="true" tabindex="-1"></a>    list.prepend(&amp;two); <span class="co">// {2}</span></span>
-<span id="cb20-14"><a href="#cb20-14" aria-hidden="true" tabindex="-1"></a>    two.insertAfter(&amp;five); <span class="co">// {2, 5}</span></span>
-<span id="cb20-15"><a href="#cb20-15" aria-hidden="true" tabindex="-1"></a>    list.prepend(&amp;one); <span class="co">// {1, 2, 5}</span></span>
-<span id="cb20-16"><a href="#cb20-16" aria-hidden="true" tabindex="-1"></a>    two.insertAfter(&amp;three); <span class="co">// {1, 2, 3, 5}</span></span>
-<span id="cb20-17"><a href="#cb20-17" aria-hidden="true" tabindex="-1"></a>    three.insertAfter(&amp;four); <span class="co">// {1, 2, 3, 4, 5}</span></span>
-<span id="cb20-18"><a href="#cb20-18" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<span id="cb20-2"><a href="#cb20-2" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb20-3"><a href="#cb20-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> NodeU32 = <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb20-4"><a href="#cb20-4" aria-hidden="true" tabindex="-1"></a>    data: <span class="dt">u32</span>,</span>
+<span id="cb20-5"><a href="#cb20-5" aria-hidden="true" tabindex="-1"></a>    node: std.SinglyLinkedList.Node = .<span class="op">{}</span>,</span>
+<span id="cb20-6"><a href="#cb20-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+</div>
+<p>After we created our custom “node type” that can store the specific data type that we want, we can just create a new and empty singly linked list, which will store our nodes. To do that, we just create a new object with the type <code>SinglyLinkedList</code>, like this:</p>
+<div class="cell">
+<div class="sourceCode cell-code" id="cb21"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb21-1"><a href="#cb21-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> list: std.SinglyLinkedList = .<span class="op">{}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+</div>
+<p>Now, we have our linked list… But how can we insert nodes in it? Well, first of all, we need to create our nodes. So let’s focus on that first. The snippet exposed below demonstrates how we could use our <code>NodeU32</code> struct to create such nodes.</p>
+<p>Notice in this snippet that we are just setting the <code>data</code> member of the struct for now. We don’t need to connect these nodes together in this first instance. This is why we ignore the <code>node</code> member at first. But we are going to connect these nodes in a future point of the code, which is why these objects are marked as “variable objects”, so that we can alter them in the future.</p>
+<div class="cell">
+<div class="sourceCode cell-code" id="cb22"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb22-1"><a href="#cb22-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> one: NodeU32 = .<span class="op">{</span> .data = <span class="dv">1</span> <span class="op">}</span>;</span>
+<span id="cb22-2"><a href="#cb22-2" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> two: NodeU32 = .<span class="op">{</span> .data = <span class="dv">2</span> <span class="op">}</span>;</span>
+<span id="cb22-3"><a href="#cb22-3" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> three: NodeU32 = .<span class="op">{</span> .data = <span class="dv">3</span> <span class="op">}</span>;</span>
+<span id="cb22-4"><a href="#cb22-4" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> five: NodeU32 = .<span class="op">{</span> .data = <span class="dv">5</span> <span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
-<p>There are other methods available from the linked list object, depending if this object is a singly linked list or a doubly linked list, that might be very useful for you. You can find a summary of them in the bullet points below:</p>
+<p>Now that we have both the linked list and also the nodes created, we can start to connect them together. You can use the <code>prepend()</code> method from the linked list object to insert the first node in the list, which is the “head” of the linked list. As the name suggests, this specific method prepends the input node to the linked list, or, in other words, it transforms the input node into the first node of the list.</p>
+<p>After we added the “head node” of the list, we can start to add the “next nodes” in the list by using the <code>insertAfter()</code> method from the <code>SinglyLinkedList.Node</code> type, which, in our case here, is accessible through the <code>node</code> member of our <code>NodeU32</code> type. Thus, we can start to create the connections between the nodes by calling this method from the node objects that are present in the list. Like in this example below:</p>
+<div class="cell">
+<div class="sourceCode cell-code" id="cb23"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb23-1"><a href="#cb23-1" aria-hidden="true" tabindex="-1"></a>list.prepend(&amp;two.node); <span class="co">// {2}</span></span>
+<span id="cb23-2"><a href="#cb23-2" aria-hidden="true" tabindex="-1"></a>two.node.insertAfter(&amp;five.node); <span class="co">// {2, 5}</span></span>
+<span id="cb23-3"><a href="#cb23-3" aria-hidden="true" tabindex="-1"></a>two.node.insertAfter(&amp;three.node); <span class="co">// {2, 3, 5}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+</div>
+<p>You can also call the <code>prepend()</code> method again to add new nodes to the beginning of the linked list, which means, effectively, changing the “head node” of the list, like this:</p>
+<div class="cell">
+<div class="sourceCode cell-code" id="cb24"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb24-1"><a href="#cb24-1" aria-hidden="true" tabindex="-1"></a>list.prepend(&amp;one.node); <span class="co">// {1, 2, 3, 5}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+</div>
+<p>There are other methods available from the singly linked list object that you might be interested. You can find a summary of them in the bullet points below:</p>
 <ul>
 <li><code>remove()</code> to remove a specific node from the linked list.</li>
-<li>if singly linked list, <code>len()</code> to count how many nodes there is in the linked list.</li>
-<li>if doubly linked list, checkout the <code>len</code> attribute to see how many nodes there is in the linked list.</li>
-<li>if singly linked list, <code>popFirst()</code> to remove the first node (i.e., the “head”) from the linked list.</li>
-<li>if doubly linked list, <code>pop()</code> and <code>popFirst()</code> to remove the last and first nodes from the linked list, respectively.</li>
-<li>if doubly linked list, <code>append()</code> to add a new node to end of the linked list (i.e., inverse of <code>prepend()</code>).</li>
+<li><code>len()</code> to count how many nodes there is in the linked list.</li>
+<li><code>popFirst()</code> to remove the first node (i.e., the “head”) from the linked list.</li>
 </ul>
+<p>So, that is how singly linked lists work in Zig in a nutshell. To sum up what we have exposed here, this is all the source code that was exposed in this section inside the single cell:</p>
+<div class="cell">
+<div class="sourceCode cell-code" id="cb25"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb25-1"><a href="#cb25-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> NodeU32 = <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb25-2"><a href="#cb25-2" aria-hidden="true" tabindex="-1"></a>    data: <span class="dt">u32</span>,</span>
+<span id="cb25-3"><a href="#cb25-3" aria-hidden="true" tabindex="-1"></a>    node: std.SinglyLinkedList.Node = .<span class="op">{}</span>,</span>
+<span id="cb25-4"><a href="#cb25-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
+<span id="cb25-5"><a href="#cb25-5" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb25-6"><a href="#cb25-6" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> list: std.SinglyLinkedList = .<span class="op">{}</span>;</span>
+<span id="cb25-7"><a href="#cb25-7" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> one: NodeU32 = .<span class="op">{</span> .data = <span class="dv">1</span> <span class="op">}</span>;</span>
+<span id="cb25-8"><a href="#cb25-8" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> two: NodeU32 = .<span class="op">{</span> .data = <span class="dv">2</span> <span class="op">}</span>;</span>
+<span id="cb25-9"><a href="#cb25-9" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> three: NodeU32 = .<span class="op">{</span> .data = <span class="dv">3</span> <span class="op">}</span>;</span>
+<span id="cb25-10"><a href="#cb25-10" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> five: NodeU32 = .<span class="op">{</span> .data = <span class="dv">5</span> <span class="op">}</span>;</span>
+<span id="cb25-11"><a href="#cb25-11" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb25-12"><a href="#cb25-12" aria-hidden="true" tabindex="-1"></a>list.prepend(&amp;two.node); <span class="co">// {2}</span></span>
+<span id="cb25-13"><a href="#cb25-13" aria-hidden="true" tabindex="-1"></a>two.node.insertAfter(&amp;five.node); <span class="co">// {2, 5}</span></span>
+<span id="cb25-14"><a href="#cb25-14" aria-hidden="true" tabindex="-1"></a>two.node.insertAfter(&amp;three.node); <span class="co">// {2, 3, 5}</span></span>
+<span id="cb25-15"><a href="#cb25-15" aria-hidden="true" tabindex="-1"></a>list.prepend(&amp;one.node); <span class="co">// {1, 2, 3, 5}</span></span>
+<span id="cb25-16"><a href="#cb25-16" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb25-17"><a href="#cb25-17" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"Number of nodes: {}"</span>, .<span class="op">{</span>list.len()<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="cell-output cell-output-stdout">
+<pre><code>Number of nodes: 4</code></pre>
+</div>
+</div>
+</section>
 </section>
 <section id="multi-array-structure" class="level2" data-number="11.4">
 <h2 data-number="11.4" class="anchored" data-anchor-id="multi-array-structure"><span class="header-section-number">11.4</span> Multi array structure</h2>
 <p>Zig introduces a new data structure called <code>MultiArrayList()</code>. It’s a different version of the dynamic array that we have introduced in <a href="#sec-dynamic-array" class="quarto-xref"><span>Section 11.1</span></a>. The difference between this structure and the <code>ArrayList()</code> that we know from <a href="#sec-dynamic-array" class="quarto-xref"><span>Section 11.1</span></a>, is that <code>MultiArrayList()</code> creates a separate dynamic array for each field of the struct that you provide as input.</p>
 <p>Consider the following code example. We create a new custom struct called <code>Person</code>. This struct contains three different data members, or, three different fields. As consequence, when we provide this <code>Person</code> data type as input to <code>MultiArrayList()</code>, this creates a “struct of three different arrays” called <code>PersonArray</code>. In other words, this <code>PersonArray</code> is a struct that contains three internal dynamic arrays in it. One array for each field found in the <code>Person</code> struct definition.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb21"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb21-1"><a href="#cb21-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb21-2"><a href="#cb21-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Person = <span class="kw">struct</span> <span class="op">{</span></span>
-<span id="cb21-3"><a href="#cb21-3" aria-hidden="true" tabindex="-1"></a>    name: []<span class="kw">const</span> <span class="dt">u8</span>,</span>
-<span id="cb21-4"><a href="#cb21-4" aria-hidden="true" tabindex="-1"></a>    age: <span class="dt">u8</span>,</span>
-<span id="cb21-5"><a href="#cb21-5" aria-hidden="true" tabindex="-1"></a>    height: <span class="dt">f32</span>,</span>
-<span id="cb21-6"><a href="#cb21-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
-<span id="cb21-7"><a href="#cb21-7" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> PersonArray = std.MultiArrayList(Person);</span>
-<span id="cb21-8"><a href="#cb21-8" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb21-9"><a href="#cb21-9" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb21-10"><a href="#cb21-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> gpa = std.heap.GeneralPurposeAllocator(.<span class="op">{}</span>)<span class="op">{}</span>;</span>
-<span id="cb21-11"><a href="#cb21-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> allocator = gpa.allocator();</span>
-<span id="cb21-12"><a href="#cb21-12" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> people = PersonArray<span class="op">{}</span>;</span>
-<span id="cb21-13"><a href="#cb21-13" aria-hidden="true" tabindex="-1"></a>    <span class="kw">defer</span> people.deinit(allocator);</span>
-<span id="cb21-14"><a href="#cb21-14" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb21-15"><a href="#cb21-15" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
-<span id="cb21-16"><a href="#cb21-16" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Auguste"</span>, .age = <span class="dv">15</span>, .height = <span class="fl">1.54</span></span>
-<span id="cb21-17"><a href="#cb21-17" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
-<span id="cb21-18"><a href="#cb21-18" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
-<span id="cb21-19"><a href="#cb21-19" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Elena"</span>, .age = <span class="dv">26</span>, .height = <span class="fl">1.65</span></span>
-<span id="cb21-20"><a href="#cb21-20" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
-<span id="cb21-21"><a href="#cb21-21" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
-<span id="cb21-22"><a href="#cb21-22" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Michael"</span>, .age = <span class="dv">64</span>, .height = <span class="fl">1.87</span></span>
-<span id="cb21-23"><a href="#cb21-23" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
-<span id="cb21-24"><a href="#cb21-24" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb27"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb27-1"><a href="#cb27-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb27-2"><a href="#cb27-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Person = <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb27-3"><a href="#cb27-3" aria-hidden="true" tabindex="-1"></a>    name: []<span class="kw">const</span> <span class="dt">u8</span>,</span>
+<span id="cb27-4"><a href="#cb27-4" aria-hidden="true" tabindex="-1"></a>    age: <span class="dt">u8</span>,</span>
+<span id="cb27-5"><a href="#cb27-5" aria-hidden="true" tabindex="-1"></a>    height: <span class="dt">f32</span>,</span>
+<span id="cb27-6"><a href="#cb27-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
+<span id="cb27-7"><a href="#cb27-7" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> PersonArray = std.MultiArrayList(Person);</span>
+<span id="cb27-8"><a href="#cb27-8" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb27-9"><a href="#cb27-9" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb27-10"><a href="#cb27-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> gpa = std.heap.GeneralPurposeAllocator(.<span class="op">{}</span>)<span class="op">{}</span>;</span>
+<span id="cb27-11"><a href="#cb27-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> allocator = gpa.allocator();</span>
+<span id="cb27-12"><a href="#cb27-12" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> people = PersonArray<span class="op">{}</span>;</span>
+<span id="cb27-13"><a href="#cb27-13" aria-hidden="true" tabindex="-1"></a>    <span class="kw">defer</span> people.deinit(allocator);</span>
+<span id="cb27-14"><a href="#cb27-14" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb27-15"><a href="#cb27-15" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
+<span id="cb27-16"><a href="#cb27-16" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Auguste"</span>, .age = <span class="dv">15</span>, .height = <span class="fl">1.54</span></span>
+<span id="cb27-17"><a href="#cb27-17" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
+<span id="cb27-18"><a href="#cb27-18" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
+<span id="cb27-19"><a href="#cb27-19" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Elena"</span>, .age = <span class="dv">26</span>, .height = <span class="fl">1.65</span></span>
+<span id="cb27-20"><a href="#cb27-20" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
+<span id="cb27-21"><a href="#cb27-21" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
+<span id="cb27-22"><a href="#cb27-22" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Michael"</span>, .age = <span class="dv">64</span>, .height = <span class="fl">1.87</span></span>
+<span id="cb27-23"><a href="#cb27-23" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
+<span id="cb27-24"><a href="#cb27-24" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>In other words, instead of creating an array of “persons”, the <code>MultiArrayList()</code> function creates a “struct of arrays”. Each data member of this struct is a different array that stores the values of a specific field from the <code>Person</code> values that were added (or, appended) to this “struct of arrays”. One important detail is that each of these separate internal arrays stored inside <code>PersonArray</code> are dynamic arrays. This means that these arrays can grow in capacity automatically as needed, to accomodate more values.</p>
 <p>The <a href="#fig-multi-array" class="quarto-xref">Figure&nbsp;<span>11.5</span></a> exposed below presents a diagram that describes the <code>PersonArray</code> struct that we have created in the previous code example. Notice that the values of the data members present in each of the three <code>Person</code> values that we have appended into the <code>PersonArray</code> object , are scattered across three different internal arrays of the <code>PersonArray</code> object.</p>
@@ -795,9 +831,9 @@ <h2 data-number="11.4" class="anchored" data-anchor-id="multi-array-structure"><
 </div>
 <p>You can easily access each of these arrays separately, and iterate over the values of each array. For that, you will need to call the <code>items()</code> method from the <code>PersonArray</code> object, and provide as input to this method, the name of the field that you want to iterate over. If you want to iterate through the <code>.age</code> array for example, then, you need to call <code>items(.age)</code> from the <code>PersonArray</code> object, like in the example below:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb22"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb22-1"><a href="#cb22-1" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (people.items(.age)) |*age| <span class="op">{</span></span>
-<span id="cb22-2"><a href="#cb22-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"Age: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>age.*<span class="op">}</span>);</span>
-<span id="cb22-3"><a href="#cb22-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb28"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb28-1"><a href="#cb28-1" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (people.items(.age)) |*age| <span class="op">{</span></span>
+<span id="cb28-2"><a href="#cb28-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"Age: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>age.*<span class="op">}</span>);</span>
+<span id="cb28-3"><a href="#cb28-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Age: 15
 Age: 26
@@ -806,15 +842,15 @@ <h2 data-number="11.4" class="anchored" data-anchor-id="multi-array-structure"><
 <p>In this example we are calling the <code>items()</code> method directly from the <code>PersonArray</code> object. However, in most situations it’s recommened to call this <code>items()</code> method from a “slice object”, which you can create from the <code>slice()</code> method. The reason for this is that calling <code>items()</code> multiple times have better performance if you use a slice object.</p>
 <p>Therefore, if you are planning to access only one of the internal arrays from your “multi array struct”, it’s fine to call <code>items()</code> directly from the multi array object. But if you need to access many of the internal arrays from your “multi array struct”, then, you will likely need to call <code>items()</code> more than once, and, in such circumstance, is better to call <code>items()</code> through a slice object. The example below demonstrates the use of such object:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb24"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb24-1"><a href="#cb24-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> slice = people.slice();</span>
-<span id="cb24-2"><a href="#cb24-2" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (slice.items(.age)) |*age| <span class="op">{</span></span>
-<span id="cb24-3"><a href="#cb24-3" aria-hidden="true" tabindex="-1"></a>    age.* += <span class="dv">10</span>;</span>
-<span id="cb24-4"><a href="#cb24-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
-<span id="cb24-5"><a href="#cb24-5" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (slice.items(.name), slice.items(.age)) |*n,*a| <span class="op">{</span></span>
-<span id="cb24-6"><a href="#cb24-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(</span>
-<span id="cb24-7"><a href="#cb24-7" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Name: {s}, Age: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>n.*, a.*<span class="op">}</span></span>
-<span id="cb24-8"><a href="#cb24-8" aria-hidden="true" tabindex="-1"></a>    );</span>
-<span id="cb24-9"><a href="#cb24-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb30"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb30-1"><a href="#cb30-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> slice = people.slice();</span>
+<span id="cb30-2"><a href="#cb30-2" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (slice.items(.age)) |*age| <span class="op">{</span></span>
+<span id="cb30-3"><a href="#cb30-3" aria-hidden="true" tabindex="-1"></a>    age.* += <span class="dv">10</span>;</span>
+<span id="cb30-4"><a href="#cb30-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
+<span id="cb30-5"><a href="#cb30-5" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (slice.items(.name), slice.items(.age)) |*n,*a| <span class="op">{</span></span>
+<span id="cb30-6"><a href="#cb30-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(</span>
+<span id="cb30-7"><a href="#cb30-7" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Name: {s}, Age: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>n.*, a.*<span class="op">}</span></span>
+<span id="cb30-8"><a href="#cb30-8" aria-hidden="true" tabindex="-1"></a>    );</span>
+<span id="cb30-9"><a href="#cb30-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Name: Auguste, Age: 25
 Name: Elena, Age: 36
diff --git a/docs/index.html b/docs/index.html
index be6ab3c0..6a8a4913 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -7,7 +7,7 @@
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 <meta name="author" content="Pedro Duarte Faria">
-<meta name="dcterms.date" content="2025-05-25">
+<meta name="dcterms.date" content="2025-05-26">
 
 <title>Introduction to Zig</title>
 <style>
@@ -287,7 +287,7 @@ <h1 class="title">Introduction to Zig</h1>
     <div>
     <div class="quarto-title-meta-heading">Published</div>
     <div class="quarto-title-meta-contents">
-      <p class="date">May 25, 2025</p>
+      <p class="date">May 26, 2025</p>
     </div>
   </div>
   
diff --git a/docs/search.json b/docs/search.json
index 9fb32b5e..81682d32 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -904,7 +904,7 @@
     "href": "Chapters/09-data-structures.html#linked-lists",
     "title": "11  Data Structures",
     "section": "11.3 Linked lists",
-    "text": "11.3 Linked lists\nThe Zig Standard Library provides an implementation for both singly and doubly linked lists. A linked list is a linear data structure that looks like a chain, or, a rope. The main advantage of this data structure is that you normally have very fast insertion and deletion operations. But, as a disadvantage, iterating through this data structure is usually not so fast as iterating through an array.\nThe idea behind a linked list is to build a structure that consists of a sequence of nodes connected to each other by pointers. This means that linked lists are usually not contiguous in memory, because each node might be anywhere in memory. They do not need to be close to one another.\nIn Figure 11.3 we can see a diagram of a singly linked list. We begin at the first node (which is usually called “the head of the linked list”). Then, from this first node we uncover the remaining nodes in the structure, by following the locations pointed by the pointers found in each node.\nEach node has two things in it. It has the value that is stored in the current node , and also, a pointer. This pointer points to the next node in the list. If this pointer is null, then, it means that we have reached the end of our linked list.\n\n\n\n\n\n\nFigure 11.3: A diagram of a singly linked list.\n\n\n\nIn Figure 11.4 we can see a diagram of a doubly linked list. The only thing that really changes now is that every node in the linked list has both a pointer to the previous node, and, a pointer to the next node. So every node in a doubly linked list has two pointers in it. These are usually called the prev (for “previous”) and the next (for “next”) pointers of the node.\nIn the singly linked list example, we had only one single pointer in each node, and this singular pointer was always pointing to the next node in the sequence. This means that singly linked lists normally have only the next pointer in them.\n\n\n\n\n\n\nFigure 11.4: A diagram of a doubly linked list.\n\n\n\nLinked lists are available in Zig through the functions SinglyLinkedList() and DoublyLinkedList(), for “singly linked lists” and “doubly linked lists”, respectively. These functions are actually generic functions, which we are going to talk more about in Section 12.2.1.\nFor now, just understand that, in order to create a linked list object, we begin by providing a data type to these functions. This data type defines the type of data that each node in this linked list will store. In the example below, we are creating a singly linked list of u32 values. So each node in this linked list will store a u32 value.\nBoth the SinglyLinkedList() and DoublyLinkedList() functions returns a type, i.e., a struct definition, as output. Therefore, the object Lu32 is actually a struct definition. It defines the type “singly linked list of u32 values”.\nNow that we have the definition of the struct, we need to instantiate a Lu32 object. We normally instantiate struct objects in Zig by using an init() method. But in this case, we are instantiating the struct directly, by using an empty struct literal, in the expression Lu32{}.\nIn this example, we first create multiple node objects, and after we create them, we start to insert and connect these nodes to build the linked list, using the prepend() and insertAfter() methods. Notice that the prepend() method is a method from the linked list object, while the insertAfter() is a method present in the node objects.\nIn essence, the prepend() method inserts a node at the beginning of the linked list. In other words, the node that you provide to this method, becomes the new “head node” of the linked list. It becomes the first node in the list (see Figure 11.3).\nOn the other side, the insertAfter() method is used to basically connect two nodes together. When you provide a node to this method, it creates a pointer to this input node, and stores this pointer in the next attribute of the current node, from which the method was called from.\nBecause doubly linked lists have both a next and a prev attributes in each node (as described in Figure 11.4), a node object created from a DoublyLinkedList object have both an insertBefore() (for prev) and an insertAfter() (for next) methods available.\nThus, if we have used a doubly linked list, we can use the insertBefore() method to store the pointer to the input node in the prev attribute. This would put the input node as the “previous node”, or, the node before the current node. In contrast, the insertAfter() method puts the pointer created to the input node in the next attribute of the current node, and as result, the input node becomes the “next node” of the current node.\nSince we are using a singly linked list in this example, we have only the insertAfter() method available in the node objects that we create from our Lu32 type.\n\nconst std = @import(\"std\");\nconst SinglyLinkedList = std.SinglyLinkedList;\nconst Lu32 = SinglyLinkedList(u32);\n\npub fn main() !void {\n    var list = Lu32{};\n    var one = Lu32.Node{ .data = 1 };\n    var two = Lu32.Node{ .data = 2 };\n    var three = Lu32.Node{ .data = 3 };\n    var four = Lu32.Node{ .data = 4 };\n    var five = Lu32.Node{ .data = 5 };\n\n    list.prepend(&two); // {2}\n    two.insertAfter(&five); // {2, 5}\n    list.prepend(&one); // {1, 2, 5}\n    two.insertAfter(&three); // {1, 2, 3, 5}\n    three.insertAfter(&four); // {1, 2, 3, 4, 5}\n}\n\nThere are other methods available from the linked list object, depending if this object is a singly linked list or a doubly linked list, that might be very useful for you. You can find a summary of them in the bullet points below:\n\nremove() to remove a specific node from the linked list.\nif singly linked list, len() to count how many nodes there is in the linked list.\nif doubly linked list, checkout the len attribute to see how many nodes there is in the linked list.\nif singly linked list, popFirst() to remove the first node (i.e., the “head”) from the linked list.\nif doubly linked list, pop() and popFirst() to remove the last and first nodes from the linked list, respectively.\nif doubly linked list, append() to add a new node to end of the linked list (i.e., inverse of prepend()).",
+    "text": "11.3 Linked lists\nThe Zig Standard Library provides an implementation for both singly and doubly linked lists. More specifically, through the structs SinglyLinkedList and DoublyLinkedList.\nIn case you are not familiar with these data structures, a linked list is a linear data structure that looks like a chain, or, a rope. The main advantage of this data structure is that you normally have very fast insertion and deletion operations. But, as a disadvantage, iterating through this data structure is usually not so fast as iterating through an array.\nThe idea behind a linked list is to build a structure that consists of a sequence of nodes connected to each other by pointers. This means that linked lists are usually not contiguous in memory, because each node might be anywhere in memory. They do not need to be close to one another.\nIn Figure 11.3 we can see a diagram of a singly linked list. We begin at the first node (which is usually called “the head of the linked list”). Then, from this first node we uncover the remaining nodes in the structure, by following the locations pointed by the pointers found in each node.\nEach node has two things in it. It has the value that is stored in the current node , and also, a pointer. This pointer points to the next node in the list. If this pointer is null, then, it means that we have reached the end of our linked list.\n\n\n\n\n\n\nFigure 11.3: A diagram of a singly linked list.\n\n\n\nIn Figure 11.4 we can see a diagram of a doubly linked list. The only thing that really changes now is that every node in the linked list has both a pointer to the previous node, and, a pointer to the next node. So every node in a doubly linked list has two pointers in it. These are usually called the prev (for “previous”) and the next (for “next”) pointers of the node.\nIn the singly linked list example, we had only one single pointer in each node, and this singular pointer was always pointing to the next node in the sequence. This means that singly linked lists normally have only the next pointer in them.\n\n\n\n\n\n\nFigure 11.4: A diagram of a doubly linked list.\n\n\n\n\n11.3.1 Recent change in the API\nOn previous versions of Zig, the SinglyLinkedList and DoublyLinkedList structs were initially implemented as “generics data structures”. Meaning that, you would use a generic function to create a singly (or doubly) linked list that could store the specific data type that you wanted to use. We will learn more about generics at Section 12.2, and also, how we can create a “generic data structure” at Section 12.2.2.\nHowever, on the latest versions of Zig, the structs SinglyLinkedList and DoublyLinkedList were altered to use a “less generic API”. This specific change was introduced on April 3, 2025. Therefore, check if your Zig version is one released after this date. Just have in mind that if you don’t have a very recent version of the Zig compiler, you might have problems while trying to compile the next examples exposed here.\n\n\n11.3.2 How to use a singly linked list\nFor example, consider that you are creating a singly linked list that is going to store u32 values. Given this scenario, the first thing that we need to do, is to create a “node type” that is capable of storing a u32 value. The NodeU32 type exposed below demonstrates such “node type”.\nNotice that the data type associated with the member named data is the most important part of this custom “node type”. It determines the data type that is going to be stored in each node.\n\nconst std = @import(\"std\");\n\nconst NodeU32 = struct {\n    data: u32,\n    node: std.SinglyLinkedList.Node = .{},\n};\n\nAfter we created our custom “node type” that can store the specific data type that we want, we can just create a new and empty singly linked list, which will store our nodes. To do that, we just create a new object with the type SinglyLinkedList, like this:\n\nvar list: std.SinglyLinkedList = .{};\n\nNow, we have our linked list… But how can we insert nodes in it? Well, first of all, we need to create our nodes. So let’s focus on that first. The snippet exposed below demonstrates how we could use our NodeU32 struct to create such nodes.\nNotice in this snippet that we are just setting the data member of the struct for now. We don’t need to connect these nodes together in this first instance. This is why we ignore the node member at first. But we are going to connect these nodes in a future point of the code, which is why these objects are marked as “variable objects”, so that we can alter them in the future.\n\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nNow that we have both the linked list and also the nodes created, we can start to connect them together. You can use the prepend() method from the linked list object to insert the first node in the list, which is the “head” of the linked list. As the name suggests, this specific method prepends the input node to the linked list, or, in other words, it transforms the input node into the first node of the list.\nAfter we added the “head node” of the list, we can start to add the “next nodes” in the list by using the insertAfter() method from the SinglyLinkedList.Node type, which, in our case here, is accessible through the node member of our NodeU32 type. Thus, we can start to create the connections between the nodes by calling this method from the node objects that are present in the list. Like in this example below:\n\nlist.prepend(&two.node); // {2}\ntwo.node.insertAfter(&five.node); // {2, 5}\ntwo.node.insertAfter(&three.node); // {2, 3, 5}\n\nYou can also call the prepend() method again to add new nodes to the beginning of the linked list, which means, effectively, changing the “head node” of the list, like this:\n\nlist.prepend(&one.node); // {1, 2, 3, 5}\n\nThere are other methods available from the singly linked list object that you might be interested. You can find a summary of them in the bullet points below:\n\nremove() to remove a specific node from the linked list.\nlen() to count how many nodes there is in the linked list.\npopFirst() to remove the first node (i.e., the “head”) from the linked list.\n\nSo, that is how singly linked lists work in Zig in a nutshell. To sum up what we have exposed here, this is all the source code that was exposed in this section inside the single cell:\n\nconst NodeU32 = struct {\n    data: u32,\n    node: std.SinglyLinkedList.Node = .{},\n};\n\nvar list: std.SinglyLinkedList = .{};\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nlist.prepend(&two.node); // {2}\ntwo.node.insertAfter(&five.node); // {2, 5}\ntwo.node.insertAfter(&three.node); // {2, 3, 5}\nlist.prepend(&one.node); // {1, 2, 3, 5}\n\ntry stdout.print(\"Number of nodes: {}\", .{list.len()});\n\nNumber of nodes: 4",
     "crumbs": [
       "<span class='chapter-number'>11</span>  <span class='chapter-title'>Data Structures</span>"
     ]

From 97cdb8b256c5e076a8e1b7a4ac8d69e5437938f8 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Mon, 26 May 2025 20:30:50 -0300
Subject: [PATCH 139/151] Add doubly list section

---
 Chapters/09-data-structures.qmd               |  64 ++++++++-
 .../execute-results/html.json                 |   4 +-
 docs/Chapters/09-data-structures.html         | 131 ++++++++++++------
 docs/search.json                              |   2 +-
 4 files changed, 155 insertions(+), 46 deletions(-)

diff --git a/Chapters/09-data-structures.qmd b/Chapters/09-data-structures.qmd
index 338b867e..36929a45 100644
--- a/Chapters/09-data-structures.qmd
+++ b/Chapters/09-data-structures.qmd
@@ -769,7 +769,6 @@ custom "node type". It determines the data type that is going to be stored in ea
 ```{zig}
 #| eval: false
 const std = @import("std");
-
 const NodeU32 = struct {
     data: u32,
     node: std.SinglyLinkedList.Node = .{},
@@ -861,6 +860,69 @@ try stdout.print("Number of nodes: {}", .{list.len()});
 ```
 
 
+### How to use a doubly linked list
+
+If you want to use a doubly linked list instead, you will face a similar workflow compared to the
+singly linked list:
+
+1. You first create a "custom node type" that can store the specific data type that you want.
+2. Create an empty doubly linked list object.
+3. Create the nodes of linked list.
+4. Start to insert the nodes inside the list.
+
+In your "custom node type", you should use the `DoublyLinkedList.Node` type to denote
+the `node` member of the struct. The snippet below demonstrates that. Here we are creating,
+once again, a node type that can store `u32` values. But this time, this struct is tailored
+to be used inside a `DoublyLinkedList` struct.
+
+After this step, the way that you create the new empty linked list, and the nodes that you want insert,
+is practically identical to the singly linked list case. But, this time,
+we normally use the `append()` method from the linked list object to add new nodes to the list.
+
+This `append()` method from the linked list object will always append the input node to the end of the
+linked list. However, in case you want to add the new node into a different position of the list, then,
+you should take a look at the `insertAfter()` and `insertBefore()` methods of the linked list object.
+These methods allow you to insert the new node either after or before an existing node in the list.
+
+
+```{zig}
+#| build_type: "run"
+#| auto_main: true
+const NodeU32 = struct {
+    data: u32,
+    node: std.DoublyLinkedList.Node = .{},
+};
+
+var list: std.DoublyLinkedList = .{};
+var one: NodeU32 = .{ .data = 1 };
+var two: NodeU32 = .{ .data = 2 };
+var three: NodeU32 = .{ .data = 3 };
+var five: NodeU32 = .{ .data = 5 };
+
+list.append(&one.node); // {1}
+list.append(&three.node); // {1, 3}
+list.insertAfter(
+    &one.node,
+    &five.node
+); // {1, 5, 3}
+list.append(&two.node); // {1, 5, 3, 2}
+
+try stdout.print("Number of nodes: {}", .{list.len()});
+```
+
+These are other methods from the `DoublyLinkedList` object that might interest you:
+
+- `remove()`: to remove a specific node from the list.
+- `len()`: to count the number of nodes in the list.
+- `prepend()`: to add a node to the beginning of the list (i.e. set the head node of the list).
+- `pop()`: to remove the last node of the list.
+- `popFirst()`: to remove the first node of the list.
+- `concatByMoving()`: to concat two doubly linked lists together.
+
+
+
+
+
 ## Multi array structure
 
 Zig introduces a new data structure called `MultiArrayList()`. It's a different version of the dynamic array
diff --git a/_freeze/Chapters/09-data-structures/execute-results/html.json b/_freeze/Chapters/09-data-structures/execute-results/html.json
index d48aede7..b52aa8ad 100644
--- a/_freeze/Chapters/09-data-structures/execute-results/html.json
+++ b/_freeze/Chapters/09-data-structures/execute-results/html.json
@@ -1,8 +1,8 @@
 {
-  "hash": "b402250b83835ffcd41be6613f43fc78",
+  "hash": "2ac41eed214fdc9ab33751c389155448",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Data Structures\n\nIn this chapter, I want to present the most common Data Structures that are available from\nthe Zig Standard Library, especially `ArrayList` and also `HashMap`. These are generic Data Structures\nthat you can use to store and control any type of data that is produced by your application.\n\n## Dynamic Arrays {#sec-dynamic-array}\n\nIn high level languages, arrays are usually dynamic. They can easily grow\nin size when they have to, and you don't need to worry about it.\nIn contrast, arrays in low level languages are usually static by default.\nThis is the reality of C, C++, Rust and also Zig. Static arrays were presented at\n@sec-arrays, but in this section, we are going to talk about dynamic arrays in Zig.\n\nDynamic arrays are simply arrays that can grow in size during the runtime\nof your program. Most low level languages have some implementation of\na dynamic array in their standard library. C++ have `std::vector`, Rust have `Vec`,\nand Zig have `std.ArrayList`.\n\nThe `std.ArrayList` struct provides a contiguous and growable array for you.\nIt works like any other dynamic array, it allocates a contiguous block of memory, and when this block have no space left,\n`ArrayList` allocates another contiguous and bigger block of memory, copies the\nelements to this new location, and erases (or frees) the previous block of memory.\n\n\n### Capacity vs Length\n\nWhen we talk about dynamic arrays, we usually have two similar concepts that\nare very essential to how a dynamic array works behind the hood.\nThese concepts are *capacity* and *length*. In some contexts, especially\nin C++, *length* is also called of *size*.\n\nAlthough they look similar, these concepts represent different things\nin the context of a dynamic array. *Capacity* is the number of items (or elements)\nthat your dynamic array can currently hold without the need to allocate more memory.\n\nIn contrast, the *length* refers to how many elements in the array\nare currently being used, or, in other words, how many elements in this array\nthat you have assigned a value to. Every dynamic array works around\na block of allocated memory, which represents an array with total capacity for $n$ elements.\nHowever, only a portion of these $n$ elements are being used most of the time. This portion\nof $n$ is the *length* of the array. So every time you append a new value\nto the array, you are incrementing its *length* by one.\n\nThis means that a dynamic array usually works with an extra margin, or an extra space\nthat is currently empty, but waiting and ready to be used. This \"extra space\"\nis essentially the difference between *capacity* and *length*. *Capacity* represents\nthe total number of elements that the array can hold without the need to re-allocate\nor re-expand the array, while the *length* represents how much of this capacity\nis currently being used to hold/store values.\n\n@fig-capacity-length presents this idea visually. Notice that, at first,\nthe capacity of the array is greater than the length of the array.\nSo, the dynamic array have extra space that is currently empty, but it\nis ready to receive a value to be stored.\n\n![Difference between capacity and length in a dynamic array](./../Figures/dynamic-array.png){#fig-capacity-length}\n\nWe can also see in @fig-capacity-length that, when *length* and *capacity* are equal, it means that the array have no space left.\nWe have reached the ceiling of our capacity, and because of that, if we want to store more values\nin this array, we need to expand it. We need to get a bigger space that can hold more values\nthan what we currently have.\n\nA dynamic array works by expanding the underlying array, whenever the *length* becomes equal\nto the *capacity* of the array. It basically allocates a new contiguous block of memory that is bigger\nthan the previous one, then, it copies all values that are currently being stored to this new\nlocation (i.e., this new block of memory), then, it frees the previous block of\nmemory. At the end of this process, the new underlying array have a bigger *capacity*, and, therefore,\nthe *length* becomes, once again, smaller than the *capacity* of the array.\n\nThis is the cycle of a dynamic array. Notice that, throughout this cycle, the *capacity* is always\neither equal to or higher than the *length* of the array. If you have an `ArrayList` object (let's suppose\nyou named it `buffer`), you can check the current capacity of your array by accessing the `capacity`\nattribute of your `ArrayList` object, while the current *length* of it is available at the `items.len`\nattribute.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// Check capacity\nbuffer.capacity;\n// Check length\nbuffer.items.len;\n```\n:::\n\n\n\n### Creating an `ArrayList` object\n\nIn order to use `ArrayList`, you must provide an allocator object to it.\nRemember, Zig does not have a default memory allocator. And as I described in @sec-allocators, all memory\nallocations must be done by an allocator object that you define, that\nyou have control over. In our example here, I'm going to use\na general purpose allocator, but you can use any other allocator\nof your preference.\n\nWhen you initialize an `ArrayList` object, you must provide the data type of the elements of\nthe array. In other words, this defines the type of data that this array (or container) will\nstore. Therefore, if I provide the `u8` type to it, then, I will create a dynamic\narray of `u8` values. However, if I provide a struct that I have defined instead, like the struct `User`\nfrom @sec-structs-and-oop, then, a dynamic array of `User` values\nwill be created. In the example below, with the expression `ArrayList(u8)` we\nare creating a dynamic array of `u8` values.\n\nAfter you provide the data type of the elements of the array, you can initialize\nan `ArrayList` object by either using the `init()` or the `initCapacity()` methods.\nThe former method receives only the allocator object\nas input, while the latter method receives both the allocator object and a capacity number as inputs.\nWith the latter method, you not only initialize the struct, but you\nalso set the starting capacity of the allocated array.\n\nUsing the `initCapacity()` method is the preferred way to initialize your dynamic array.\nBecause reallocations, or, in other words, the process of expanding the capacity of the array,\nis always a high cost operation. You should take any possible opportunity to avoid reallocations in\nyour array. If you know how much space your array needs to occupy at the beginning,\nyou should always use `initCapacity()` to create your dynamic array.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n```\n:::\n\n\n\nIn the example above, the `buffer` object starts as an array of 100 elements. If this\n`buffer` object needs to create more space to accomodate more elements during the runtime of your program, the `ArrayList`\ninternals will perform the necessary actions for you automatically.\nAlso notice the `deinit()` method being used to destroy the `buffer` object at the\nend of the current scope, by freeing all the memory that was allocated for the dynamic\narray stored in this `buffer` object.\n\n\n### Adding new elements to the array\n\nNow that we have created our dynamic array, we can start to use it. You can append (a.k.a \"add\")\nnew values to this array by using the `append()` method. This method works the same way\nas the `append()` method from a Python list, or, the `emplace_back()` method from `std::vector` of C++.\nYou provide a single value to this method, and the method appends this value to the array.\n\nYou can also use the `appendSlice()` method to append multiple values at once. You provide\na slice (slices were described in @sec-arrays) to this method, and the method adds all values present\nin this slice to your dynamic array.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry buffer.append('H');\ntry buffer.append('e');\ntry buffer.append('l');\ntry buffer.append('l');\ntry buffer.append('o');\ntry buffer.appendSlice(\" World!\");\n```\n:::\n\n\n### Removing elements from the array {#sec-dynamic-array-remove}\n\nYou can use the `pop()` method to \"pop\" or remove\nthe last element in the array. It's worth noting that this method\ndo not change the capacity of the array. It just deletes or erases\nthe last value stored in the array.\n\nAlso, this method returns as result the value that got deleted. That is, you can\nuse this method to both get the last value in the array, and also, remove\nit from the array. It's a \"get and remove value\" type of method.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exclamation_mark = buffer.pop();\n```\n:::\n\n\nNow, if you want to remove specific elements from specific positions\nof your array, you can use the `orderedRemove()` method from your\n`ArrayList` object. With this method, you can provide an index as input,\nthen, the method will delete the value that is at this index in the array.\nYou are effectively reducing the *length* of the array everytime you execute\nan `orderedRemove()` operation.\n\nIn the example below, we first create an `ArrayList` object, and we fill it\nwith numbers. Then, we use `orderedRemove()` to remove the value at\nindex 3 in the array, two consecutive times.\n\nAlso, notice that we are assigning the result of `orderedRemove()` to the\nunderscore character. So we are discarding the result value of this method.\nThe `orderedRemove()` method returns the value that got deleted, in a similar\nstyle to the `pop()` method.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n\nfor (0..10) |i| {\n    const index: u8 = @intCast(i);\n    try buffer.append(index);\n}\n\nstd.debug.print(\n    \"{any}\\n\", .{buffer.items}\n);\n_ = buffer.orderedRemove(3);\n_ = buffer.orderedRemove(3);\n\nstd.debug.print(\"{any}\\n\", .{buffer.items});\nstd.debug.print(\"{any}\\n\", .{buffer.items.len});\n```\n:::\n\n\n```\n{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }\n{ 0, 1, 2, 5, 6, 7, 8, 9 }\n8\n```\n\nOne key characteristic about `orderedRemove()` is that it preserves the order\nof the values in the array. So, it deletes the value that you asked it to\nremove, but it also makes sure that the order of the values that remain in the array\nstay the same as before.\n\nNow, if you don't care about the order of the values, for example, maybe you want to treat\nyour dynamic array as a set of values, like the `std::unordered_set`\nstructure from C++, you can use the `swapRemove()` method instead. This method\nworks similarly to the `orderedRemove()` method. You give an index to this\nmethod, then, it deletes the value that is at this index in the array.\nBut this method does not preserve the original order of the values that remain\nin the array. As a result, `swapRemove()` is, in general, faster than `orderedRemove()`.\n\n\n### Inserting elements at specific indexes\n\nWhen you need to insert values in the middle of your array,\ninstead of just appending them to the end of the array, you need to use\nthe `insert()` and `insertSlice()` methods, instead of\nthe `append()` and `appendSlice()` methods.\n\nThese two methods work very similarly to `insert()` and `insert_range()`\nfrom the C++ `std::vector` class. You provide an index to these methods,\nand they insert the values that you provide at that index in the array.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 10);\ndefer buffer.deinit();\n\ntry buffer.appendSlice(\"My Pedro\");\ntry buffer.insert(4, '3');\ntry buffer.insertSlice(2, \" name\");\nfor (buffer.items) |char| {\n    try stdout.print(\"{c}\", .{char});\n}\n```\n:::\n\n\n```\nMy name P3edro\n```\n\n\n### Conclusion\n\nIf you feel the lack of some other method, I recommend\nyou to read the [official documentation for the `ArrayListAligned`](https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned)[^zig-array2]\nstruct, which describes most of the methods available\nthrough the `ArrayList` object.\n\nYou will notice that there is a lot of other methods in this page that\nI did not described here, and I recommend you to explore these methods,\nand understand how they work.\n\n[^zig-array2]: <https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned>\n\n\n\n## Maps or HashTables {#sec-maps-hashtables}\n\nSome professionals know this type of data structure by different terms, like \"map\",\n\"hashmap\" or \"associative arrays\". But the most common term used is *hashtable*.\nEvery programming language normally have some implementation of a hashtable in their\nstandard libraries. Python have `dict()`, C++ have `std::map` and `std::unordered_map`, Rust\nhave `HashMap`, Javascript have `Object()` and `Map()`, etc.\n\n\n\n### What is a hashtable?\n\nA hashtable is a data structure based on key-value pairs.\nYou provide a key and a value to this structure, then, the hashtable will store\nthe input value at a location that can be identified by the input\nkey that you provided.\nIt does that by using an underlying array and a hash function.\nThese two components are essential to how a hashtable works.\n\nUnder the hood, the hashtable contains an array. This array is where the values\nare stored, and the elements of this array are usually called of *buckets*.\nSo the values that you provide to the hashtable are stored inside buckets,\nand you access each bucket by using an index.\n\nWhen you provide a key to a hashtable, it passes this key to the\nhash function. This hash function uses some sort of hashing algorithm to transform\nthis key into an index. This index is actually an array index. It's a position\nin the underlying array of the hashtable.\nThis is how a key identifies a specific position (or location) inside the hashtable\nstructure.\n\nTherefore, you provide a key to the hashtable, and this key identifies a specific location\ninside the hashtable, then, the hashtable takes the input value that you provided,\nand stores this value in the location identified by this input key.\nYou could say that the key maps to the value stored in the hashtable. You find\nthe value, by using the key that identifies the location where the value is stored.\nThe @fig-hashtable presents this process visually.\n\n\n![A diagram of a Hashtable. Source: Wikipedia, the free encyclopedia.](./../Figures/hashtable.svg){#fig-hashtable}\n\n\nThe operation described in the previous paragraph is normally called an *insertion* operation.\nBecause you are inserting new values into the hashtable.\nBut there are other types of operations in hashtables such as *delete* and *lookup*.\nDelete is self describing, it's when you delete (or remove) a value from the hashtable.\nWhile lookup corresponds to when you look at a value that is stored in\nthe hashtable, by using the key that identifies the location where this value is stored.\n\nSometimes, instead of storing the values directly, the underlying array of the hashtable might be an array of pointers,\ni.e., the buckets of the array stores pointers that points to the value,\nor also, may be an array of linked lists.\nThese cases are common on hashtables that allows duplicate keys, or, in other words,\non hashtables that effectively handle \"collisions\" that may arise from the hash function.\n\nDuplicate keys, or this \"collision\" thing that I'm talking about, is when you have two different keys\nthat points to the same location (i.e., to the same index)\nin the underlying array of the hashtable. This might happen depending on the characteristics of the hash function\nthat is being used in the hashtable. Some implementations of the hashtable will actively deal with collisions,\nmeaning that, they will handle this case in some way. For example, the hashtable\nmight transform all buckets into linked lists. Because with a linked list you can store\nmultiple values into a single bucket.\n\nThere are different techniques to handle collisions in hashtables, which I will not describe\nin this book, because it's not our main scope here. But you can find a good description of\nsome of the most common techniques at the Wikipedia page of hashtables [@wikipedia_hashtables].\n\n\n### Hashtables in Zig {#sec-hashmap}\n\nThe Zig Standard Library provides different implementations of a hashtable.\nEach implementation have its own cons and pros, which we will\ndiscuss later on, and all of them are available through the `std.hash_map` module.\n\nThe `HashMap` struct is a general-purpose hashtable,\nwhich have very fast operations (lookup, insertion, delete), and also,\nquite high load factors for low memory usage. You can create and provide a context object\nto the `HashMap` constructor. This context object allows you to tailor\nthe behaviour of the hashtable itself, because you can\nprovide a hash function implementation to be used by the hashtable\nthrough this context object.\n\nBut let's not worry about this context object now, because it's meant to be used\nby \"experts in the field of hashtables\". Since we are most likely not\nexperts in this field, we are going to take the easy way to create\na hashtable. Which is by using the `AutoHashMap()` function.\n\n\nThis `AutoHashMap()` function is essentially a \"create a hashtable object that uses the default settings\"\ntype of function. It automatically chooses a context object, and, therefore, a hash function implementation,\nfor you. This function receives two data types as input, the first input is the data type of the keys\nthat will be used in this hashtable, while the second input is the data type of the data that will be\nstored inside the hashtable, that is, the data type of the values to be stored.\n\nIn the example below, we are providing the data type `u32` in the first argument, and `u16` in the second argument of this\nfunction. This means that we are going to use `u32` values as keys in this hashtable, while `u16` values are the actual values\nthat are going to be stored into this hashtable.\nAt the end of this process, the `hash_table` object contains a `HashMap` object\nthat uses the default settings and context.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n    std.debug.print(\n        \"Value at key 50050: {d}\\n\",\n        .{hash_table.get(50050).?}\n    );\n\n    if (hash_table.remove(57709)) {\n        std.debug.print(\n            \"Value at key 57709 successfully removed!\\n\",\n            .{}\n        );\n    }\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n}\n```\n:::\n\n\n```\nN of values stored: 3\nValue at key 50050: 55\nValue at key 57709 successfully removed!\nN of values stored: 2\n```\n\nYou can add/put new values into the hashtable by using the `put()` method. The first argument\nis the key to be used, and the second argument is the actual value that you want to store inside\nthe hashtable. In the example below, we first add the value 89 using the key 54321, next, we add\nthe value 55 using the key 50050, etc.\n\nNotice that we have used the method `count()` to see how many values are currently stored in the\nhashtable. After that, we also use the `get()` method to access (or look) at the value stored in\nthe position identified by the key 500050. The output of this `get()` method is an optional value.\nThis is why we use the `?` method at the end to get the actual value.\n\nAlso notice that we can remove (or delete) values from the hashtable by using the `remove()` method.\nYou provide the key that identifies the value that you want to delete, then, the method will\ndelete this value and return a `true` value as output. This `true` value essentially tells us\nthat the method successfully deleted the value.\n\nBut this delete operation might not be always successful. For example, you might provide the wrong\nkey to this method. I mean, maybe you provide\n(either intentionally or unintentionally) a key that points to an empty bucket,\ni.e., a bucket that still doesn't have a value in it.\nIn this case, the `remove()` method would return a `false` value.\n\n\n\n### Iterating through the hashtable\n\nIterating through the keys and values that are currently being stored in\nthe hashtable is a very common necessity.\nYou can do that in Zig by using an iterator object that can iterate\nthrough the elements of your hashtable object.\n\nThis iterator object works like any other iterator object that you would\nfind in languages such as C++ and Rust. It's basically a pointer object\nthat points to some value in the container, and has a `next()` method\nthat you can use to navigate (or iterate) through the values in the\ncontainer.\n\nYou can create such iterator object by using the `iterator()` method of the hashtable object.\nThis method returns an iterator object, from which you can use the `next()` method in conjunction\nwith a while loop to iterate through the elements of your hashtable. The `next()` method returns an optional\n`Entry` value, and therefore, you must unwrap this optional value to get the actual `Entry` value\nfrom which you can access the key and also the value identified by this key.\n\nWith this `Entry` value at hand, you can access the key of this current entry by using the `key_ptr`\nattribute and dereferencing the pointer that lives inside of it, while the value identified by this\nkey is accessed through the `value_ptr` attribute instead, which is also a pointer to be dereferenced.\nThe code example below demonstrates the use of these elements:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n\n    var it = hash_table.iterator();\n    while (it.next()) |kv| {\n        // Access the current key\n        std.debug.print(\"Key: {d} | \", .{kv.key_ptr.*});\n        // Access the current value\n        std.debug.print(\"Value: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n:::\n\n\n```\nKey: 54321 | Value: 89\nKey: 50050 | Value: 55\nKey: 57709 | Value: 41\n```\n\n\nIf you want to iterate specifically through the values or the keys of your hashtable,\nyou can create a key iterator or a value iterator object. These are also iterator\nobjects, which have the same `next()` method that you can use to iterate through the\nhashtable.\n\nKey iterators are created from the `keyIterator()` method of your\nhashtable object, while value iterators are created from the `valueIterator()` method.\nAll you have to do is to unwrap the value from the `next()` method and deference it\ndirectly to access the key or the value that you are iterating over.\nThe code example below demonstrates the use of a key iterator,\nbut you can replicate the same logic to a value iterator.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar kit = hash_table.keyIterator();\nwhile (kit.next()) |key| {\n    std.debug.print(\"Key: {d}\\n\", .{key.*});\n}\n```\n:::\n\n\n```\nKey: 54321\nKey: 50050\nKey: 57709\n```\n\n\n### The `ArrayHashMap` hashtable {#sec-array-map}\n\nIf you need to iterate through the elements of your hashtable constantly,\nyou might want to use the `ArrayHashMap` struct for your specific case,\ninstead of going with the usual and general-purpose `HashMap` struct.\n\nThe `ArrayHashMap` struct creates a hashtable that is faster to iterate over.\nThat is why this specific type of hashtable might be valuable to you.\nSome other properties of a `ArrayHashMap` hashtable are:\n\n- the order of insertion is preserved, i.e., the order of the values that you find while iterating through this hashtable is actually the order in which these values were inserted in the hashtable.\n- the key-value pairs are stored sequentially, one after another.\n\n\nYou can create an `ArrayHashMap` object by using, once again, a helper function that\nchooses automatically for you a hash function implementation. This is the\n`AutoArrayHashMap()` function, which works very similarly to the `AutoHashMap()`\nfunction that we presented in @sec-hashmap.\n\nYou provide two data types to this function. The data type of the keys that will be\nused in this hashtable, and the data type of the values that will be stored in\nthis hashtable.\n\nAn `ArrayHashMap` object have essentially the exact same methods from the `HashMap` struct.\nSo you can insert new values into the hashtable by using the `put()` method, and you can look (or get)\na value from the hashtable by using the `get()` method. But the `remove()` method is not available\nin this specific type of hashtable.\n\nIn order to delete values from the hashtable, you would use the same methods that you find in\nan `ArrayList` object, i.e., a dynamic array. I presented these methods in @sec-dynamic-array-remove,\nwhich are the `swapRemove()` and `orderedRemove()` methods. These methods have the same meaning here, or,\nthe same effect that they have in an `ArrayList` object.\n\nThis means that, with `swapRemove()` you remove the value from the hashtable, but you do not preserve\nthe order in which the values were inserted into the structure. While `orderedRemove()` is able\nto retain the order in which these values were inserted.\n\nBut instead of providing an index as input to `swapRemove()` or `orderedRemove()`, like I described\nin @sec-dynamic-array-remove, these methods here in an `ArrayHashMap` take a key as input, like\nthe `remove()` method from a `HashMap` object. If you want to provide an index as input, instead\nof a key, you should use the `swapRemoveAt()` and `orderedRemoveAt()` methods.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar hash_table = AutoArrayHashMap(u32, u16)\n    .init(allocator);\ndefer hash_table.deinit();\n```\n:::\n\n\n\n\n### The `StringHashMap` hashtable {#sec-string-hash-map}\n\nOne thing that you will notice in the other two types of hashtables that I have\npresented over the last sections, is that neither of them accepts a slice data type\nin their keys.\nWhat this means is that you cannot use a slice value to represent a key in\nthese types of hashtable.\n\nThe most obvious consequence of this, is that you cannot use strings as keys\nin these hashtables. But it's extremely common to use strings as keys\nin hashtables.\n\nTake this very simple Javascript code snippet as an example. We are creating\na simple hashtable object named `people`. Then, we add a new entry to this\nhashtable, which is identified by the string `'Pedro'`. This string is the\nkey in this case, while the object containing different personal information such as\nage, height and city, is the value to be stored in the hashtable.\n\n```js\nvar people = new Object();\npeople['Pedro'] = {\n    'age': 25,\n    'height': 1.67,\n    'city': 'Belo Horizonte'\n};\n```\n\nThis pattern of using strings as keys is very common in\nall sorts of situations. That is why the Zig Standard Library offers a\nspecific type of hashtable for this purpose, which is created through the `StringHashMap()` function.\nThis function creates a hashtable that uses strings as keys. The only input of this\nfunction is the data type of the values that will be stored into this hashtable.\n\nIn the example below, I'm creating a hashtable to store the ages of different people.\nEach key in this hashtable is represented by the name of each person, while the value stored in the\nhashtable is the age of this person identified by the key.\n\nThat is why I provide the `u8` data type (which is the data type used by the age values) as input to this `StringHashMap()` function.\nAs the result, it creates a hashtable that uses string values as keys, and, that stores\n`u8` values in it. Notice that an allocator object is provided at the `init()` method of the\nresulting object from the `StringHashMap()` function.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var ages = std.StringHashMap(u8).init(allocator);\n    defer ages.deinit();\n\n    try ages.put(\"Pedro\", 25);\n    try ages.put(\"Matheus\", 21);\n    try ages.put(\"Abgail\", 42);\n\n    var it = ages.iterator();\n    while (it.next()) |kv| {\n        std.debug.print(\"Key: {s} | \", .{kv.key_ptr.*});\n        std.debug.print(\"Age: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n:::\n\n\n```\nKey: Pedro | Age: 25\nKey: Abgail | Age: 42\nKey: Matheus | Age: 21\n```\n\n\n### The `StringArrayHashMap` hashtable\n\nThe Zig Standard Library also provides a type of hashtable that mix the cons and pros of the\n`StringHashMap` and `ArrayHashMap` together. That is, a hashtable\nthat uses strings as keys, but also have the advantages from `ArrayHashMap`.\nIn other words, you can have a hashtable that is fast to iterate over,\nthat preserves insertion order, and also, that uses strings as keys.\n\nYou can create such type of hashtable by using the `StringArrayHashMap()` function.\nThis function accepts a data type as input, which is the data type of the values that are\ngoing to be stored inside this hashtable, in the same style as the function presented\nin @sec-string-hash-map.\n\nYou can insert new values into this hashtable by using the same `put()` method that\nwe have discussed in @sec-string-hash-map. And you can also get values from the hashtable\nby using the same `get()` method.\nLike its `ArrayHashMap` brother, to delete values from this specific type of hashtable,\nwe also use the `orderedRemove()` and `swapRemove()` methods, with the same effects that\nI have described in @sec-array-map.\n\nIf we take the code example that was exposed in @sec-string-hash-map, we can\nachieve the exact same result with `StringArrayHashMap()`:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar ages = std.StringArrayHashMap(u8).init(allocator);\n```\n:::\n\n\n\n\n\n## Linked lists\n\nThe Zig Standard Library provides an implementation for both singly and doubly linked lists.\nMore specifically, through the structs `SinglyLinkedList` and `DoublyLinkedList`.\n\nIn case you are not familiar with these data structures, a linked list is a linear data structure that looks\nlike a chain, or, a rope. The main advantage of this data structure is that you normally have very fast\ninsertion and deletion operations. But, as a disadvantage, iterating through\nthis data structure is usually not so fast as iterating through an array.\n\nThe idea behind a linked list is to build a structure that consists of a sequence of nodes\nconnected to each other by pointers. This means that linked lists are usually not contiguous\nin memory, because each node might be anywhere in memory. They do not need to be close to\none another.\n\nIn @fig-linked-list we can see a diagram of a singly linked list. We begin at the first node\n(which is usually called \"the head of the linked list\"). Then, from this\nfirst node we uncover the remaining nodes in the structure, by following the locations pointed\nby the pointers found in each node.\n\nEach node has two things in it. It has the value that is stored in the current node\n, and also, a pointer. This pointer points to the next node in the list. If this pointer\nis null, then, it means that we have reached the end of our linked list.\n\n![A diagram of a singly linked list.](./../Figures/linked-list.png){#fig-linked-list}\n\n\nIn @fig-linked-list2 we can see a diagram of a doubly linked list. The only thing that really\nchanges now is that every node in the linked list has both a pointer to the previous node,\nand, a pointer to the next node. So every node in a doubly linked list has two pointers in it. These are\nusually called the `prev` (for \"previous\") and the `next` (for \"next\") pointers of the node.\n\nIn the singly linked list example, we had only one single pointer in each node, and this singular\npointer was always pointing to the next node in the sequence. This means that singly linked lists\nnormally have only the `next` pointer in them.\n\n![A diagram of a doubly linked list.](./../Figures/doubly-linked-list.png){#fig-linked-list2}\n\n\n\n### Recent change in the API\n\nOn previous versions of Zig, the `SinglyLinkedList` and `DoublyLinkedList` structs were initially implemented as \"generics data structures\".\nMeaning that, you would use a generic function to create a singly (or doubly) linked list that could store\nthe specific data type that you wanted to use. We will learn more about generics at @sec-generics, and also,\nhow we can create a \"generic data structure\" at @sec-generic-struct.\n\nHowever, on the latest versions of Zig, the structs `SinglyLinkedList` and `DoublyLinkedList` were altered to use a\n\"less generic API\". This specific change was introduced on April 3, 2025. Therefore, check if your Zig version is one released after this\ndate. Just have in mind that if you don't have a very recent version of the Zig compiler,\nyou might have problems while trying to compile the next examples exposed here.\n\n\n\n### How to use a singly linked list\n\nFor example, consider that you are creating a singly linked list that is going to store `u32` values.\nGiven this scenario, the first thing that we need to do, is to create a \"node type\" that is capable\nof storing a `u32` value. The `NodeU32` type exposed below demonstrates such \"node type\".\n\nNotice that the data type associated with the member named `data` is the most important part of this\ncustom \"node type\". It determines the data type that is going to be stored in each node.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\nconst NodeU32 = struct {\n    data: u32,\n    node: std.SinglyLinkedList.Node = .{},\n};\n```\n:::\n\n\nAfter we created our custom \"node type\" that can store the specific data type that we\nwant, we can just create a new and empty singly linked list, which will store our nodes.\nTo do that, we just create a new object with the type `SinglyLinkedList`, like this:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar list: std.SinglyLinkedList = .{};\n```\n:::\n\n\nNow, we have our linked list... But how can we insert nodes in it? Well, first of all,\nwe need to create our nodes. So let's focus on that first. The snippet exposed below demonstrates\nhow we could use our `NodeU32` struct to create such nodes.\n\nNotice in this snippet that we are just setting the `data` member of the struct for now.\nWe don't need to connect these nodes together in this first instance. This is why we ignore\nthe `node` member at first. But we are going to connect these nodes in a future point of the code, which is\nwhy these objects are marked as \"variable objects\", so that we can alter them in the future.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n```\n:::\n\n\nNow that we have both the linked list and also the nodes created, we can start to connect them together.\nYou can use the `prepend()` method from the linked list object to insert the first node in the list, which\nis the \"head\" of the linked list. As the name suggests, this specific method prepends the input node to the linked list,\nor, in other words, it transforms the input node into the first node of the list.\n\nAfter we added the \"head node\" of the list, we can start to add the \"next nodes\" in the list by using the `insertAfter()` method\nfrom the `SinglyLinkedList.Node` type, which, in our case here, is accessible through the `node` member of our\n`NodeU32` type. Thus, we can start to create the connections between the nodes by calling this method from the node objects\nthat are present in the list. Like in this example below:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nlist.prepend(&two.node); // {2}\ntwo.node.insertAfter(&five.node); // {2, 5}\ntwo.node.insertAfter(&three.node); // {2, 3, 5}\n```\n:::\n\n\nYou can also call the `prepend()` method again to add new nodes to the beginning of the linked list, which\nmeans, effectively, changing the \"head node\" of the list, like this:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nlist.prepend(&one.node); // {1, 2, 3, 5}\n```\n:::\n\n\n\nThere are other methods available from the singly linked list object that you might be interested. You can find a\nsummary of them in the bullet points below:\n\n- `remove()` to remove a specific node from the linked list.\n- `len()` to count how many nodes there is in the linked list.\n- `popFirst()` to remove the first node (i.e., the \"head\") from the linked list.\n\nSo, that is how singly linked lists work in Zig in a nutshell. To sum up what we have exposed here,\nthis is all the source code that was exposed in this section inside the single cell:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst NodeU32 = struct {\n    data: u32,\n    node: std.SinglyLinkedList.Node = .{},\n};\n\nvar list: std.SinglyLinkedList = .{};\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nlist.prepend(&two.node); // {2}\ntwo.node.insertAfter(&five.node); // {2, 5}\ntwo.node.insertAfter(&three.node); // {2, 3, 5}\nlist.prepend(&one.node); // {1, 2, 3, 5}\n\ntry stdout.print(\"Number of nodes: {}\", .{list.len()});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nNumber of nodes: 4\n```\n\n\n:::\n:::\n\n\n\n## Multi array structure\n\nZig introduces a new data structure called `MultiArrayList()`. It's a different version of the dynamic array\nthat we have introduced in @sec-dynamic-array. The difference between this structure and the `ArrayList()`\nthat we know from @sec-dynamic-array, is that `MultiArrayList()` creates a separate dynamic array\nfor each field of the struct that you provide as input.\n\nConsider the following code example. We create a new custom struct called `Person`. This\nstruct contains three different data members, or, three different fields. As consequence,\nwhen we provide this `Person` data type as input to `MultiArrayList()`, this\ncreates a \"struct of three different arrays\" called `PersonArray`. In other words,\nthis `PersonArray` is a struct that contains three internal dynamic arrays in it.\nOne array for each field found in the `Person` struct definition.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Person = struct {\n    name: []const u8,\n    age: u8,\n    height: f32,\n};\nconst PersonArray = std.MultiArrayList(Person);\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var people = PersonArray{};\n    defer people.deinit(allocator);\n\n    try people.append(allocator, .{\n        .name = \"Auguste\", .age = 15, .height = 1.54\n    });\n    try people.append(allocator, .{\n        .name = \"Elena\", .age = 26, .height = 1.65\n    });\n    try people.append(allocator, .{\n        .name = \"Michael\", .age = 64, .height = 1.87\n    });\n}\n```\n:::\n\n\nIn other words, instead of creating an array of \"persons\", the `MultiArrayList()` function\ncreates a \"struct of arrays\". Each data member of this struct is a different array that stores\nthe values of a specific field from the `Person` values that were added (or, appended) to this \"struct of arrays\".\nOne important detail is that each of these separate internal arrays stored inside `PersonArray`\nare dynamic arrays. This means that these arrays can grow in capacity automatically as needed, to accomodate\nmore values.\n\nThe @fig-multi-array exposed below presents a diagram that describes the `PersonArray` struct\nthat we have created in the previous code example. Notice that the values of the data members\npresent in each of the three `Person` values that we have appended into the `PersonArray` object\n, are scattered across three different internal arrays of the `PersonArray` object.\n\n![A diagram of the `PersonArray` struct.](./../Figures/multi-array.png){#fig-multi-array}\n\nYou can easily access each of these arrays separately, and iterate over the values of each array.\nFor that, you will need to call the `items()` method from the `PersonArray` object, and provide as input\nto this method, the name of the field that you want to iterate over.\nIf you want to iterate through the `.age` array for example, then, you need to call `items(.age)` from\nthe `PersonArray` object, like in the example below:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (people.items(.age)) |*age| {\n    try stdout.print(\"Age: {d}\\n\", .{age.*});\n}\n```\n:::\n\n\n```\nAge: 15\nAge: 26\nAge: 64\n```\n\n\nIn the above example, we are iterating over the values of the `.age` array, or,\nthe internal array of the `PersonArray` object that contains the values of the `age`\ndata member from the `Person` values that were added to the multi array struct.\n\nIn this example we are calling the `items()` method directly from the `PersonArray`\nobject. However, in most situations it's recommened to call this `items()` method\nfrom a \"slice object\", which you can create from the `slice()` method.\nThe reason for this is that calling `items()` multiple times have better performance\nif you use a slice object.\n\nTherefore, if you are planning to access only one of the\ninternal arrays from your \"multi array struct\", it's fine to call `items()` directly\nfrom the multi array object. But if you need to access many of the internal arrays\nfrom your \"multi array struct\", then, you will likely need to call `items()` more\nthan once, and, in such circumstance, is better to call `items()` through a slice object.\nThe example below demonstrates the use of such object:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar slice = people.slice();\nfor (slice.items(.age)) |*age| {\n    age.* += 10;\n}\nfor (slice.items(.name), slice.items(.age)) |*n,*a| {\n    try stdout.print(\n        \"Name: {s}, Age: {d}\\n\", .{n.*, a.*}\n    );\n}\n```\n:::\n\n\n```\nName: Auguste, Age: 25\nName: Elena, Age: 36\nName: Michael, Age: 74\n```\n\n\n## Conclusion\n\nThere are many other data structures that I haven't presented here.\nBut you can check them out at the official Zig Standard Library documentation page.\nActually, when you get into the [homepage of the documentation](https://ziglang.org/documentation/master/std/#)[^home], the first thing\nthat appears to you in this page, is a list of types and data structures that\nare available in the Zig Standard Library.\nThere are some very specific data structures in this list, like a\n[`BoundedArray` struct](https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray)[^bounded]\n, but there is also some more general structures, such as a\n[`PriorityQueue` struct](https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue)[^priority].\n\n\n[^home]: <https://ziglang.org/documentation/master/std/#>\n[^priority]: <https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue>.\n[^bounded]: <https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray>\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Data Structures\n\nIn this chapter, I want to present the most common Data Structures that are available from\nthe Zig Standard Library, especially `ArrayList` and also `HashMap`. These are generic Data Structures\nthat you can use to store and control any type of data that is produced by your application.\n\n## Dynamic Arrays {#sec-dynamic-array}\n\nIn high level languages, arrays are usually dynamic. They can easily grow\nin size when they have to, and you don't need to worry about it.\nIn contrast, arrays in low level languages are usually static by default.\nThis is the reality of C, C++, Rust and also Zig. Static arrays were presented at\n@sec-arrays, but in this section, we are going to talk about dynamic arrays in Zig.\n\nDynamic arrays are simply arrays that can grow in size during the runtime\nof your program. Most low level languages have some implementation of\na dynamic array in their standard library. C++ have `std::vector`, Rust have `Vec`,\nand Zig have `std.ArrayList`.\n\nThe `std.ArrayList` struct provides a contiguous and growable array for you.\nIt works like any other dynamic array, it allocates a contiguous block of memory, and when this block have no space left,\n`ArrayList` allocates another contiguous and bigger block of memory, copies the\nelements to this new location, and erases (or frees) the previous block of memory.\n\n\n### Capacity vs Length\n\nWhen we talk about dynamic arrays, we usually have two similar concepts that\nare very essential to how a dynamic array works behind the hood.\nThese concepts are *capacity* and *length*. In some contexts, especially\nin C++, *length* is also called of *size*.\n\nAlthough they look similar, these concepts represent different things\nin the context of a dynamic array. *Capacity* is the number of items (or elements)\nthat your dynamic array can currently hold without the need to allocate more memory.\n\nIn contrast, the *length* refers to how many elements in the array\nare currently being used, or, in other words, how many elements in this array\nthat you have assigned a value to. Every dynamic array works around\na block of allocated memory, which represents an array with total capacity for $n$ elements.\nHowever, only a portion of these $n$ elements are being used most of the time. This portion\nof $n$ is the *length* of the array. So every time you append a new value\nto the array, you are incrementing its *length* by one.\n\nThis means that a dynamic array usually works with an extra margin, or an extra space\nthat is currently empty, but waiting and ready to be used. This \"extra space\"\nis essentially the difference between *capacity* and *length*. *Capacity* represents\nthe total number of elements that the array can hold without the need to re-allocate\nor re-expand the array, while the *length* represents how much of this capacity\nis currently being used to hold/store values.\n\n@fig-capacity-length presents this idea visually. Notice that, at first,\nthe capacity of the array is greater than the length of the array.\nSo, the dynamic array have extra space that is currently empty, but it\nis ready to receive a value to be stored.\n\n![Difference between capacity and length in a dynamic array](./../Figures/dynamic-array.png){#fig-capacity-length}\n\nWe can also see in @fig-capacity-length that, when *length* and *capacity* are equal, it means that the array have no space left.\nWe have reached the ceiling of our capacity, and because of that, if we want to store more values\nin this array, we need to expand it. We need to get a bigger space that can hold more values\nthan what we currently have.\n\nA dynamic array works by expanding the underlying array, whenever the *length* becomes equal\nto the *capacity* of the array. It basically allocates a new contiguous block of memory that is bigger\nthan the previous one, then, it copies all values that are currently being stored to this new\nlocation (i.e., this new block of memory), then, it frees the previous block of\nmemory. At the end of this process, the new underlying array have a bigger *capacity*, and, therefore,\nthe *length* becomes, once again, smaller than the *capacity* of the array.\n\nThis is the cycle of a dynamic array. Notice that, throughout this cycle, the *capacity* is always\neither equal to or higher than the *length* of the array. If you have an `ArrayList` object (let's suppose\nyou named it `buffer`), you can check the current capacity of your array by accessing the `capacity`\nattribute of your `ArrayList` object, while the current *length* of it is available at the `items.len`\nattribute.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// Check capacity\nbuffer.capacity;\n// Check length\nbuffer.items.len;\n```\n:::\n\n\n\n### Creating an `ArrayList` object\n\nIn order to use `ArrayList`, you must provide an allocator object to it.\nRemember, Zig does not have a default memory allocator. And as I described in @sec-allocators, all memory\nallocations must be done by an allocator object that you define, that\nyou have control over. In our example here, I'm going to use\na general purpose allocator, but you can use any other allocator\nof your preference.\n\nWhen you initialize an `ArrayList` object, you must provide the data type of the elements of\nthe array. In other words, this defines the type of data that this array (or container) will\nstore. Therefore, if I provide the `u8` type to it, then, I will create a dynamic\narray of `u8` values. However, if I provide a struct that I have defined instead, like the struct `User`\nfrom @sec-structs-and-oop, then, a dynamic array of `User` values\nwill be created. In the example below, with the expression `ArrayList(u8)` we\nare creating a dynamic array of `u8` values.\n\nAfter you provide the data type of the elements of the array, you can initialize\nan `ArrayList` object by either using the `init()` or the `initCapacity()` methods.\nThe former method receives only the allocator object\nas input, while the latter method receives both the allocator object and a capacity number as inputs.\nWith the latter method, you not only initialize the struct, but you\nalso set the starting capacity of the allocated array.\n\nUsing the `initCapacity()` method is the preferred way to initialize your dynamic array.\nBecause reallocations, or, in other words, the process of expanding the capacity of the array,\nis always a high cost operation. You should take any possible opportunity to avoid reallocations in\nyour array. If you know how much space your array needs to occupy at the beginning,\nyou should always use `initCapacity()` to create your dynamic array.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n```\n:::\n\n\n\nIn the example above, the `buffer` object starts as an array of 100 elements. If this\n`buffer` object needs to create more space to accomodate more elements during the runtime of your program, the `ArrayList`\ninternals will perform the necessary actions for you automatically.\nAlso notice the `deinit()` method being used to destroy the `buffer` object at the\nend of the current scope, by freeing all the memory that was allocated for the dynamic\narray stored in this `buffer` object.\n\n\n### Adding new elements to the array\n\nNow that we have created our dynamic array, we can start to use it. You can append (a.k.a \"add\")\nnew values to this array by using the `append()` method. This method works the same way\nas the `append()` method from a Python list, or, the `emplace_back()` method from `std::vector` of C++.\nYou provide a single value to this method, and the method appends this value to the array.\n\nYou can also use the `appendSlice()` method to append multiple values at once. You provide\na slice (slices were described in @sec-arrays) to this method, and the method adds all values present\nin this slice to your dynamic array.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry buffer.append('H');\ntry buffer.append('e');\ntry buffer.append('l');\ntry buffer.append('l');\ntry buffer.append('o');\ntry buffer.appendSlice(\" World!\");\n```\n:::\n\n\n### Removing elements from the array {#sec-dynamic-array-remove}\n\nYou can use the `pop()` method to \"pop\" or remove\nthe last element in the array. It's worth noting that this method\ndo not change the capacity of the array. It just deletes or erases\nthe last value stored in the array.\n\nAlso, this method returns as result the value that got deleted. That is, you can\nuse this method to both get the last value in the array, and also, remove\nit from the array. It's a \"get and remove value\" type of method.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exclamation_mark = buffer.pop();\n```\n:::\n\n\nNow, if you want to remove specific elements from specific positions\nof your array, you can use the `orderedRemove()` method from your\n`ArrayList` object. With this method, you can provide an index as input,\nthen, the method will delete the value that is at this index in the array.\nYou are effectively reducing the *length* of the array everytime you execute\nan `orderedRemove()` operation.\n\nIn the example below, we first create an `ArrayList` object, and we fill it\nwith numbers. Then, we use `orderedRemove()` to remove the value at\nindex 3 in the array, two consecutive times.\n\nAlso, notice that we are assigning the result of `orderedRemove()` to the\nunderscore character. So we are discarding the result value of this method.\nThe `orderedRemove()` method returns the value that got deleted, in a similar\nstyle to the `pop()` method.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n\nfor (0..10) |i| {\n    const index: u8 = @intCast(i);\n    try buffer.append(index);\n}\n\nstd.debug.print(\n    \"{any}\\n\", .{buffer.items}\n);\n_ = buffer.orderedRemove(3);\n_ = buffer.orderedRemove(3);\n\nstd.debug.print(\"{any}\\n\", .{buffer.items});\nstd.debug.print(\"{any}\\n\", .{buffer.items.len});\n```\n:::\n\n\n```\n{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }\n{ 0, 1, 2, 5, 6, 7, 8, 9 }\n8\n```\n\nOne key characteristic about `orderedRemove()` is that it preserves the order\nof the values in the array. So, it deletes the value that you asked it to\nremove, but it also makes sure that the order of the values that remain in the array\nstay the same as before.\n\nNow, if you don't care about the order of the values, for example, maybe you want to treat\nyour dynamic array as a set of values, like the `std::unordered_set`\nstructure from C++, you can use the `swapRemove()` method instead. This method\nworks similarly to the `orderedRemove()` method. You give an index to this\nmethod, then, it deletes the value that is at this index in the array.\nBut this method does not preserve the original order of the values that remain\nin the array. As a result, `swapRemove()` is, in general, faster than `orderedRemove()`.\n\n\n### Inserting elements at specific indexes\n\nWhen you need to insert values in the middle of your array,\ninstead of just appending them to the end of the array, you need to use\nthe `insert()` and `insertSlice()` methods, instead of\nthe `append()` and `appendSlice()` methods.\n\nThese two methods work very similarly to `insert()` and `insert_range()`\nfrom the C++ `std::vector` class. You provide an index to these methods,\nand they insert the values that you provide at that index in the array.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 10);\ndefer buffer.deinit();\n\ntry buffer.appendSlice(\"My Pedro\");\ntry buffer.insert(4, '3');\ntry buffer.insertSlice(2, \" name\");\nfor (buffer.items) |char| {\n    try stdout.print(\"{c}\", .{char});\n}\n```\n:::\n\n\n```\nMy name P3edro\n```\n\n\n### Conclusion\n\nIf you feel the lack of some other method, I recommend\nyou to read the [official documentation for the `ArrayListAligned`](https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned)[^zig-array2]\nstruct, which describes most of the methods available\nthrough the `ArrayList` object.\n\nYou will notice that there is a lot of other methods in this page that\nI did not described here, and I recommend you to explore these methods,\nand understand how they work.\n\n[^zig-array2]: <https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned>\n\n\n\n## Maps or HashTables {#sec-maps-hashtables}\n\nSome professionals know this type of data structure by different terms, like \"map\",\n\"hashmap\" or \"associative arrays\". But the most common term used is *hashtable*.\nEvery programming language normally have some implementation of a hashtable in their\nstandard libraries. Python have `dict()`, C++ have `std::map` and `std::unordered_map`, Rust\nhave `HashMap`, Javascript have `Object()` and `Map()`, etc.\n\n\n\n### What is a hashtable?\n\nA hashtable is a data structure based on key-value pairs.\nYou provide a key and a value to this structure, then, the hashtable will store\nthe input value at a location that can be identified by the input\nkey that you provided.\nIt does that by using an underlying array and a hash function.\nThese two components are essential to how a hashtable works.\n\nUnder the hood, the hashtable contains an array. This array is where the values\nare stored, and the elements of this array are usually called of *buckets*.\nSo the values that you provide to the hashtable are stored inside buckets,\nand you access each bucket by using an index.\n\nWhen you provide a key to a hashtable, it passes this key to the\nhash function. This hash function uses some sort of hashing algorithm to transform\nthis key into an index. This index is actually an array index. It's a position\nin the underlying array of the hashtable.\nThis is how a key identifies a specific position (or location) inside the hashtable\nstructure.\n\nTherefore, you provide a key to the hashtable, and this key identifies a specific location\ninside the hashtable, then, the hashtable takes the input value that you provided,\nand stores this value in the location identified by this input key.\nYou could say that the key maps to the value stored in the hashtable. You find\nthe value, by using the key that identifies the location where the value is stored.\nThe @fig-hashtable presents this process visually.\n\n\n![A diagram of a Hashtable. Source: Wikipedia, the free encyclopedia.](./../Figures/hashtable.svg){#fig-hashtable}\n\n\nThe operation described in the previous paragraph is normally called an *insertion* operation.\nBecause you are inserting new values into the hashtable.\nBut there are other types of operations in hashtables such as *delete* and *lookup*.\nDelete is self describing, it's when you delete (or remove) a value from the hashtable.\nWhile lookup corresponds to when you look at a value that is stored in\nthe hashtable, by using the key that identifies the location where this value is stored.\n\nSometimes, instead of storing the values directly, the underlying array of the hashtable might be an array of pointers,\ni.e., the buckets of the array stores pointers that points to the value,\nor also, may be an array of linked lists.\nThese cases are common on hashtables that allows duplicate keys, or, in other words,\non hashtables that effectively handle \"collisions\" that may arise from the hash function.\n\nDuplicate keys, or this \"collision\" thing that I'm talking about, is when you have two different keys\nthat points to the same location (i.e., to the same index)\nin the underlying array of the hashtable. This might happen depending on the characteristics of the hash function\nthat is being used in the hashtable. Some implementations of the hashtable will actively deal with collisions,\nmeaning that, they will handle this case in some way. For example, the hashtable\nmight transform all buckets into linked lists. Because with a linked list you can store\nmultiple values into a single bucket.\n\nThere are different techniques to handle collisions in hashtables, which I will not describe\nin this book, because it's not our main scope here. But you can find a good description of\nsome of the most common techniques at the Wikipedia page of hashtables [@wikipedia_hashtables].\n\n\n### Hashtables in Zig {#sec-hashmap}\n\nThe Zig Standard Library provides different implementations of a hashtable.\nEach implementation have its own cons and pros, which we will\ndiscuss later on, and all of them are available through the `std.hash_map` module.\n\nThe `HashMap` struct is a general-purpose hashtable,\nwhich have very fast operations (lookup, insertion, delete), and also,\nquite high load factors for low memory usage. You can create and provide a context object\nto the `HashMap` constructor. This context object allows you to tailor\nthe behaviour of the hashtable itself, because you can\nprovide a hash function implementation to be used by the hashtable\nthrough this context object.\n\nBut let's not worry about this context object now, because it's meant to be used\nby \"experts in the field of hashtables\". Since we are most likely not\nexperts in this field, we are going to take the easy way to create\na hashtable. Which is by using the `AutoHashMap()` function.\n\n\nThis `AutoHashMap()` function is essentially a \"create a hashtable object that uses the default settings\"\ntype of function. It automatically chooses a context object, and, therefore, a hash function implementation,\nfor you. This function receives two data types as input, the first input is the data type of the keys\nthat will be used in this hashtable, while the second input is the data type of the data that will be\nstored inside the hashtable, that is, the data type of the values to be stored.\n\nIn the example below, we are providing the data type `u32` in the first argument, and `u16` in the second argument of this\nfunction. This means that we are going to use `u32` values as keys in this hashtable, while `u16` values are the actual values\nthat are going to be stored into this hashtable.\nAt the end of this process, the `hash_table` object contains a `HashMap` object\nthat uses the default settings and context.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n    std.debug.print(\n        \"Value at key 50050: {d}\\n\",\n        .{hash_table.get(50050).?}\n    );\n\n    if (hash_table.remove(57709)) {\n        std.debug.print(\n            \"Value at key 57709 successfully removed!\\n\",\n            .{}\n        );\n    }\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n}\n```\n:::\n\n\n```\nN of values stored: 3\nValue at key 50050: 55\nValue at key 57709 successfully removed!\nN of values stored: 2\n```\n\nYou can add/put new values into the hashtable by using the `put()` method. The first argument\nis the key to be used, and the second argument is the actual value that you want to store inside\nthe hashtable. In the example below, we first add the value 89 using the key 54321, next, we add\nthe value 55 using the key 50050, etc.\n\nNotice that we have used the method `count()` to see how many values are currently stored in the\nhashtable. After that, we also use the `get()` method to access (or look) at the value stored in\nthe position identified by the key 500050. The output of this `get()` method is an optional value.\nThis is why we use the `?` method at the end to get the actual value.\n\nAlso notice that we can remove (or delete) values from the hashtable by using the `remove()` method.\nYou provide the key that identifies the value that you want to delete, then, the method will\ndelete this value and return a `true` value as output. This `true` value essentially tells us\nthat the method successfully deleted the value.\n\nBut this delete operation might not be always successful. For example, you might provide the wrong\nkey to this method. I mean, maybe you provide\n(either intentionally or unintentionally) a key that points to an empty bucket,\ni.e., a bucket that still doesn't have a value in it.\nIn this case, the `remove()` method would return a `false` value.\n\n\n\n### Iterating through the hashtable\n\nIterating through the keys and values that are currently being stored in\nthe hashtable is a very common necessity.\nYou can do that in Zig by using an iterator object that can iterate\nthrough the elements of your hashtable object.\n\nThis iterator object works like any other iterator object that you would\nfind in languages such as C++ and Rust. It's basically a pointer object\nthat points to some value in the container, and has a `next()` method\nthat you can use to navigate (or iterate) through the values in the\ncontainer.\n\nYou can create such iterator object by using the `iterator()` method of the hashtable object.\nThis method returns an iterator object, from which you can use the `next()` method in conjunction\nwith a while loop to iterate through the elements of your hashtable. The `next()` method returns an optional\n`Entry` value, and therefore, you must unwrap this optional value to get the actual `Entry` value\nfrom which you can access the key and also the value identified by this key.\n\nWith this `Entry` value at hand, you can access the key of this current entry by using the `key_ptr`\nattribute and dereferencing the pointer that lives inside of it, while the value identified by this\nkey is accessed through the `value_ptr` attribute instead, which is also a pointer to be dereferenced.\nThe code example below demonstrates the use of these elements:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n\n    var it = hash_table.iterator();\n    while (it.next()) |kv| {\n        // Access the current key\n        std.debug.print(\"Key: {d} | \", .{kv.key_ptr.*});\n        // Access the current value\n        std.debug.print(\"Value: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n:::\n\n\n```\nKey: 54321 | Value: 89\nKey: 50050 | Value: 55\nKey: 57709 | Value: 41\n```\n\n\nIf you want to iterate specifically through the values or the keys of your hashtable,\nyou can create a key iterator or a value iterator object. These are also iterator\nobjects, which have the same `next()` method that you can use to iterate through the\nhashtable.\n\nKey iterators are created from the `keyIterator()` method of your\nhashtable object, while value iterators are created from the `valueIterator()` method.\nAll you have to do is to unwrap the value from the `next()` method and deference it\ndirectly to access the key or the value that you are iterating over.\nThe code example below demonstrates the use of a key iterator,\nbut you can replicate the same logic to a value iterator.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar kit = hash_table.keyIterator();\nwhile (kit.next()) |key| {\n    std.debug.print(\"Key: {d}\\n\", .{key.*});\n}\n```\n:::\n\n\n```\nKey: 54321\nKey: 50050\nKey: 57709\n```\n\n\n### The `ArrayHashMap` hashtable {#sec-array-map}\n\nIf you need to iterate through the elements of your hashtable constantly,\nyou might want to use the `ArrayHashMap` struct for your specific case,\ninstead of going with the usual and general-purpose `HashMap` struct.\n\nThe `ArrayHashMap` struct creates a hashtable that is faster to iterate over.\nThat is why this specific type of hashtable might be valuable to you.\nSome other properties of a `ArrayHashMap` hashtable are:\n\n- the order of insertion is preserved, i.e., the order of the values that you find while iterating through this hashtable is actually the order in which these values were inserted in the hashtable.\n- the key-value pairs are stored sequentially, one after another.\n\n\nYou can create an `ArrayHashMap` object by using, once again, a helper function that\nchooses automatically for you a hash function implementation. This is the\n`AutoArrayHashMap()` function, which works very similarly to the `AutoHashMap()`\nfunction that we presented in @sec-hashmap.\n\nYou provide two data types to this function. The data type of the keys that will be\nused in this hashtable, and the data type of the values that will be stored in\nthis hashtable.\n\nAn `ArrayHashMap` object have essentially the exact same methods from the `HashMap` struct.\nSo you can insert new values into the hashtable by using the `put()` method, and you can look (or get)\na value from the hashtable by using the `get()` method. But the `remove()` method is not available\nin this specific type of hashtable.\n\nIn order to delete values from the hashtable, you would use the same methods that you find in\nan `ArrayList` object, i.e., a dynamic array. I presented these methods in @sec-dynamic-array-remove,\nwhich are the `swapRemove()` and `orderedRemove()` methods. These methods have the same meaning here, or,\nthe same effect that they have in an `ArrayList` object.\n\nThis means that, with `swapRemove()` you remove the value from the hashtable, but you do not preserve\nthe order in which the values were inserted into the structure. While `orderedRemove()` is able\nto retain the order in which these values were inserted.\n\nBut instead of providing an index as input to `swapRemove()` or `orderedRemove()`, like I described\nin @sec-dynamic-array-remove, these methods here in an `ArrayHashMap` take a key as input, like\nthe `remove()` method from a `HashMap` object. If you want to provide an index as input, instead\nof a key, you should use the `swapRemoveAt()` and `orderedRemoveAt()` methods.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar hash_table = AutoArrayHashMap(u32, u16)\n    .init(allocator);\ndefer hash_table.deinit();\n```\n:::\n\n\n\n\n### The `StringHashMap` hashtable {#sec-string-hash-map}\n\nOne thing that you will notice in the other two types of hashtables that I have\npresented over the last sections, is that neither of them accepts a slice data type\nin their keys.\nWhat this means is that you cannot use a slice value to represent a key in\nthese types of hashtable.\n\nThe most obvious consequence of this, is that you cannot use strings as keys\nin these hashtables. But it's extremely common to use strings as keys\nin hashtables.\n\nTake this very simple Javascript code snippet as an example. We are creating\na simple hashtable object named `people`. Then, we add a new entry to this\nhashtable, which is identified by the string `'Pedro'`. This string is the\nkey in this case, while the object containing different personal information such as\nage, height and city, is the value to be stored in the hashtable.\n\n```js\nvar people = new Object();\npeople['Pedro'] = {\n    'age': 25,\n    'height': 1.67,\n    'city': 'Belo Horizonte'\n};\n```\n\nThis pattern of using strings as keys is very common in\nall sorts of situations. That is why the Zig Standard Library offers a\nspecific type of hashtable for this purpose, which is created through the `StringHashMap()` function.\nThis function creates a hashtable that uses strings as keys. The only input of this\nfunction is the data type of the values that will be stored into this hashtable.\n\nIn the example below, I'm creating a hashtable to store the ages of different people.\nEach key in this hashtable is represented by the name of each person, while the value stored in the\nhashtable is the age of this person identified by the key.\n\nThat is why I provide the `u8` data type (which is the data type used by the age values) as input to this `StringHashMap()` function.\nAs the result, it creates a hashtable that uses string values as keys, and, that stores\n`u8` values in it. Notice that an allocator object is provided at the `init()` method of the\nresulting object from the `StringHashMap()` function.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var ages = std.StringHashMap(u8).init(allocator);\n    defer ages.deinit();\n\n    try ages.put(\"Pedro\", 25);\n    try ages.put(\"Matheus\", 21);\n    try ages.put(\"Abgail\", 42);\n\n    var it = ages.iterator();\n    while (it.next()) |kv| {\n        std.debug.print(\"Key: {s} | \", .{kv.key_ptr.*});\n        std.debug.print(\"Age: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n:::\n\n\n```\nKey: Pedro | Age: 25\nKey: Abgail | Age: 42\nKey: Matheus | Age: 21\n```\n\n\n### The `StringArrayHashMap` hashtable\n\nThe Zig Standard Library also provides a type of hashtable that mix the cons and pros of the\n`StringHashMap` and `ArrayHashMap` together. That is, a hashtable\nthat uses strings as keys, but also have the advantages from `ArrayHashMap`.\nIn other words, you can have a hashtable that is fast to iterate over,\nthat preserves insertion order, and also, that uses strings as keys.\n\nYou can create such type of hashtable by using the `StringArrayHashMap()` function.\nThis function accepts a data type as input, which is the data type of the values that are\ngoing to be stored inside this hashtable, in the same style as the function presented\nin @sec-string-hash-map.\n\nYou can insert new values into this hashtable by using the same `put()` method that\nwe have discussed in @sec-string-hash-map. And you can also get values from the hashtable\nby using the same `get()` method.\nLike its `ArrayHashMap` brother, to delete values from this specific type of hashtable,\nwe also use the `orderedRemove()` and `swapRemove()` methods, with the same effects that\nI have described in @sec-array-map.\n\nIf we take the code example that was exposed in @sec-string-hash-map, we can\nachieve the exact same result with `StringArrayHashMap()`:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar ages = std.StringArrayHashMap(u8).init(allocator);\n```\n:::\n\n\n\n\n\n## Linked lists\n\nThe Zig Standard Library provides an implementation for both singly and doubly linked lists.\nMore specifically, through the structs `SinglyLinkedList` and `DoublyLinkedList`.\n\nIn case you are not familiar with these data structures, a linked list is a linear data structure that looks\nlike a chain, or, a rope. The main advantage of this data structure is that you normally have very fast\ninsertion and deletion operations. But, as a disadvantage, iterating through\nthis data structure is usually not so fast as iterating through an array.\n\nThe idea behind a linked list is to build a structure that consists of a sequence of nodes\nconnected to each other by pointers. This means that linked lists are usually not contiguous\nin memory, because each node might be anywhere in memory. They do not need to be close to\none another.\n\nIn @fig-linked-list we can see a diagram of a singly linked list. We begin at the first node\n(which is usually called \"the head of the linked list\"). Then, from this\nfirst node we uncover the remaining nodes in the structure, by following the locations pointed\nby the pointers found in each node.\n\nEach node has two things in it. It has the value that is stored in the current node\n, and also, a pointer. This pointer points to the next node in the list. If this pointer\nis null, then, it means that we have reached the end of our linked list.\n\n![A diagram of a singly linked list.](./../Figures/linked-list.png){#fig-linked-list}\n\n\nIn @fig-linked-list2 we can see a diagram of a doubly linked list. The only thing that really\nchanges now is that every node in the linked list has both a pointer to the previous node,\nand, a pointer to the next node. So every node in a doubly linked list has two pointers in it. These are\nusually called the `prev` (for \"previous\") and the `next` (for \"next\") pointers of the node.\n\nIn the singly linked list example, we had only one single pointer in each node, and this singular\npointer was always pointing to the next node in the sequence. This means that singly linked lists\nnormally have only the `next` pointer in them.\n\n![A diagram of a doubly linked list.](./../Figures/doubly-linked-list.png){#fig-linked-list2}\n\n\n\n### Recent change in the API\n\nOn previous versions of Zig, the `SinglyLinkedList` and `DoublyLinkedList` structs were initially implemented as \"generics data structures\".\nMeaning that, you would use a generic function to create a singly (or doubly) linked list that could store\nthe specific data type that you wanted to use. We will learn more about generics at @sec-generics, and also,\nhow we can create a \"generic data structure\" at @sec-generic-struct.\n\nHowever, on the latest versions of Zig, the structs `SinglyLinkedList` and `DoublyLinkedList` were altered to use a\n\"less generic API\". This specific change was introduced on April 3, 2025. Therefore, check if your Zig version is one released after this\ndate. Just have in mind that if you don't have a very recent version of the Zig compiler,\nyou might have problems while trying to compile the next examples exposed here.\n\n\n\n### How to use a singly linked list\n\nFor example, consider that you are creating a singly linked list that is going to store `u32` values.\nGiven this scenario, the first thing that we need to do, is to create a \"node type\" that is capable\nof storing a `u32` value. The `NodeU32` type exposed below demonstrates such \"node type\".\n\nNotice that the data type associated with the member named `data` is the most important part of this\ncustom \"node type\". It determines the data type that is going to be stored in each node.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst NodeU32 = struct {\n    data: u32,\n    node: std.SinglyLinkedList.Node = .{},\n};\n```\n:::\n\n\nAfter we created our custom \"node type\" that can store the specific data type that we\nwant, we can just create a new and empty singly linked list, which will store our nodes.\nTo do that, we just create a new object with the type `SinglyLinkedList`, like this:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar list: std.SinglyLinkedList = .{};\n```\n:::\n\n\nNow, we have our linked list... But how can we insert nodes in it? Well, first of all,\nwe need to create our nodes. So let's focus on that first. The snippet exposed below demonstrates\nhow we could use our `NodeU32` struct to create such nodes.\n\nNotice in this snippet that we are just setting the `data` member of the struct for now.\nWe don't need to connect these nodes together in this first instance. This is why we ignore\nthe `node` member at first. But we are going to connect these nodes in a future point of the code, which is\nwhy these objects are marked as \"variable objects\", so that we can alter them in the future.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n```\n:::\n\n\nNow that we have both the linked list and also the nodes created, we can start to connect them together.\nYou can use the `prepend()` method from the linked list object to insert the first node in the list, which\nis the \"head\" of the linked list. As the name suggests, this specific method prepends the input node to the linked list,\nor, in other words, it transforms the input node into the first node of the list.\n\nAfter we added the \"head node\" of the list, we can start to add the \"next nodes\" in the list by using the `insertAfter()` method\nfrom the `SinglyLinkedList.Node` type, which, in our case here, is accessible through the `node` member of our\n`NodeU32` type. Thus, we can start to create the connections between the nodes by calling this method from the node objects\nthat are present in the list. Like in this example below:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nlist.prepend(&two.node); // {2}\ntwo.node.insertAfter(&five.node); // {2, 5}\ntwo.node.insertAfter(&three.node); // {2, 3, 5}\n```\n:::\n\n\nYou can also call the `prepend()` method again to add new nodes to the beginning of the linked list, which\nmeans, effectively, changing the \"head node\" of the list, like this:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nlist.prepend(&one.node); // {1, 2, 3, 5}\n```\n:::\n\n\n\nThere are other methods available from the singly linked list object that you might be interested. You can find a\nsummary of them in the bullet points below:\n\n- `remove()` to remove a specific node from the linked list.\n- `len()` to count how many nodes there is in the linked list.\n- `popFirst()` to remove the first node (i.e., the \"head\") from the linked list.\n\nSo, that is how singly linked lists work in Zig in a nutshell. To sum up,\nthis is all the source code that was exposed in this section inside the single cell:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst NodeU32 = struct {\n    data: u32,\n    node: std.SinglyLinkedList.Node = .{},\n};\n\nvar list: std.SinglyLinkedList = .{};\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nlist.prepend(&two.node); // {2}\ntwo.node.insertAfter(&five.node); // {2, 5}\ntwo.node.insertAfter(&three.node); // {2, 3, 5}\nlist.prepend(&one.node); // {1, 2, 3, 5}\n\ntry stdout.print(\"Number of nodes: {}\", .{list.len()});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nNumber of nodes: 4\n```\n\n\n:::\n:::\n\n\n\n### How to use a doubly linked list\n\nIf you want to use a doubly linked list instead, you will face a similar workflow compared to the\nsingly linked list:\n\n1. You first create a \"custom node type\" that can store the specific data type that you want.\n2. Create an empty doubly linked list object.\n3. Create the nodes of linked list.\n4. Start to insert the nodes inside the list.\n\nIn your \"custom node type\", you should use the `DoublyLinkedList.Node` type to denote\nthe `node` member of the struct. The snippet below demonstrates that. Here we are creating,\nonce again, a node type that can store `u32` values. But this time, this struct is tailored\nto be used inside a `DoublyLinkedList` struct.\n\nAfter this step, the way that you create the new empty linked list, and the nodes that you want insert,\nis practically identical to the singly linked list case. But, things are different when you start to add nodes\nto the list. Instead of using the `prepend()` method of the list object, you should use the `append()` method\nto add the nodes to the linked list.\n\nThis `append()` method from the linked list object will always append the input node to the end of the\nlinked list. However, in case you want to add the new node into a different position of the list, then,\nyou should take a look at the `insertAfter()` and `insertBefore()` methods of the linked list object.\nThese methods allow you to insert the new node either after or before an existing node in the list.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst NodeU32 = struct {\n    data: u32,\n    node: std.DoublyLinkedList.Node = .{},\n};\n\nvar list: std.DoublyLinkedList = .{};\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nlist.append(&one.node); // {1}\nlist.append(&three.node); // {1, 3}\nlist.insertAfter(\n    &one.node,\n    &five.node\n); // {1, 5, 3}\nlist.append(&two.node); // {1, 5, 3, 2}\n\ntry stdout.print(\"Number of nodes: {}\", .{list.len()});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nNumber of nodes: 4\n```\n\n\n:::\n:::\n\n\nThese are other methods from the `DoublyLinkedList` object that might interest you:\n\n- `remove()`: to remove a specific node from the list.\n- `len()`: to count the number of nodes in the list.\n- `prepend()`: to add a node to the beginning of the list (i.e. set the head node of the list).\n- `pop()`: to remove the last node of the list.\n- `popFirst()`: to remove the first node of the list.\n- `concatByMoving()`: to concat two doubly linked lists together.\n\n\n\n\n\n## Multi array structure\n\nZig introduces a new data structure called `MultiArrayList()`. It's a different version of the dynamic array\nthat we have introduced in @sec-dynamic-array. The difference between this structure and the `ArrayList()`\nthat we know from @sec-dynamic-array, is that `MultiArrayList()` creates a separate dynamic array\nfor each field of the struct that you provide as input.\n\nConsider the following code example. We create a new custom struct called `Person`. This\nstruct contains three different data members, or, three different fields. As consequence,\nwhen we provide this `Person` data type as input to `MultiArrayList()`, this\ncreates a \"struct of three different arrays\" called `PersonArray`. In other words,\nthis `PersonArray` is a struct that contains three internal dynamic arrays in it.\nOne array for each field found in the `Person` struct definition.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Person = struct {\n    name: []const u8,\n    age: u8,\n    height: f32,\n};\nconst PersonArray = std.MultiArrayList(Person);\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var people = PersonArray{};\n    defer people.deinit(allocator);\n\n    try people.append(allocator, .{\n        .name = \"Auguste\", .age = 15, .height = 1.54\n    });\n    try people.append(allocator, .{\n        .name = \"Elena\", .age = 26, .height = 1.65\n    });\n    try people.append(allocator, .{\n        .name = \"Michael\", .age = 64, .height = 1.87\n    });\n}\n```\n:::\n\n\nIn other words, instead of creating an array of \"persons\", the `MultiArrayList()` function\ncreates a \"struct of arrays\". Each data member of this struct is a different array that stores\nthe values of a specific field from the `Person` values that were added (or, appended) to this \"struct of arrays\".\nOne important detail is that each of these separate internal arrays stored inside `PersonArray`\nare dynamic arrays. This means that these arrays can grow in capacity automatically as needed, to accomodate\nmore values.\n\nThe @fig-multi-array exposed below presents a diagram that describes the `PersonArray` struct\nthat we have created in the previous code example. Notice that the values of the data members\npresent in each of the three `Person` values that we have appended into the `PersonArray` object\n, are scattered across three different internal arrays of the `PersonArray` object.\n\n![A diagram of the `PersonArray` struct.](./../Figures/multi-array.png){#fig-multi-array}\n\nYou can easily access each of these arrays separately, and iterate over the values of each array.\nFor that, you will need to call the `items()` method from the `PersonArray` object, and provide as input\nto this method, the name of the field that you want to iterate over.\nIf you want to iterate through the `.age` array for example, then, you need to call `items(.age)` from\nthe `PersonArray` object, like in the example below:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (people.items(.age)) |*age| {\n    try stdout.print(\"Age: {d}\\n\", .{age.*});\n}\n```\n:::\n\n\n```\nAge: 15\nAge: 26\nAge: 64\n```\n\n\nIn the above example, we are iterating over the values of the `.age` array, or,\nthe internal array of the `PersonArray` object that contains the values of the `age`\ndata member from the `Person` values that were added to the multi array struct.\n\nIn this example we are calling the `items()` method directly from the `PersonArray`\nobject. However, in most situations it's recommened to call this `items()` method\nfrom a \"slice object\", which you can create from the `slice()` method.\nThe reason for this is that calling `items()` multiple times have better performance\nif you use a slice object.\n\nTherefore, if you are planning to access only one of the\ninternal arrays from your \"multi array struct\", it's fine to call `items()` directly\nfrom the multi array object. But if you need to access many of the internal arrays\nfrom your \"multi array struct\", then, you will likely need to call `items()` more\nthan once, and, in such circumstance, is better to call `items()` through a slice object.\nThe example below demonstrates the use of such object:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar slice = people.slice();\nfor (slice.items(.age)) |*age| {\n    age.* += 10;\n}\nfor (slice.items(.name), slice.items(.age)) |*n,*a| {\n    try stdout.print(\n        \"Name: {s}, Age: {d}\\n\", .{n.*, a.*}\n    );\n}\n```\n:::\n\n\n```\nName: Auguste, Age: 25\nName: Elena, Age: 36\nName: Michael, Age: 74\n```\n\n\n## Conclusion\n\nThere are many other data structures that I haven't presented here.\nBut you can check them out at the official Zig Standard Library documentation page.\nActually, when you get into the [homepage of the documentation](https://ziglang.org/documentation/master/std/#)[^home], the first thing\nthat appears to you in this page, is a list of types and data structures that\nare available in the Zig Standard Library.\nThere are some very specific data structures in this list, like a\n[`BoundedArray` struct](https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray)[^bounded]\n, but there is also some more general structures, such as a\n[`PriorityQueue` struct](https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue)[^priority].\n\n\n[^home]: <https://ziglang.org/documentation/master/std/#>\n[^priority]: <https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue>.\n[^bounded]: <https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray>\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
diff --git a/docs/Chapters/09-data-structures.html b/docs/Chapters/09-data-structures.html
index 4cf9c0a3..1e43b46a 100644
--- a/docs/Chapters/09-data-structures.html
+++ b/docs/Chapters/09-data-structures.html
@@ -349,6 +349,7 @@ <h2 id="toc-title">Table of contents</h2>
   <ul class="collapse">
   <li><a href="#recent-change-in-the-api" id="toc-recent-change-in-the-api" class="nav-link" data-scroll-target="#recent-change-in-the-api"><span class="header-section-number">11.3.1</span> Recent change in the API</a></li>
   <li><a href="#how-to-use-a-singly-linked-list" id="toc-how-to-use-a-singly-linked-list" class="nav-link" data-scroll-target="#how-to-use-a-singly-linked-list"><span class="header-section-number">11.3.2</span> How to use a singly linked list</a></li>
+  <li><a href="#how-to-use-a-doubly-linked-list" id="toc-how-to-use-a-doubly-linked-list" class="nav-link" data-scroll-target="#how-to-use-a-doubly-linked-list"><span class="header-section-number">11.3.3</span> How to use a doubly linked list</a></li>
   </ul></li>
   <li><a href="#multi-array-structure" id="toc-multi-array-structure" class="nav-link" data-scroll-target="#multi-array-structure"><span class="header-section-number">11.4</span> Multi array structure</a></li>
   <li><a href="#conclusion-1" id="toc-conclusion-1" class="nav-link" data-scroll-target="#conclusion-1"><span class="header-section-number">11.5</span> Conclusion</a></li>
@@ -727,11 +728,10 @@ <h3 data-number="11.3.2" class="anchored" data-anchor-id="how-to-use-a-singly-li
 <p>Notice that the data type associated with the member named <code>data</code> is the most important part of this custom “node type”. It determines the data type that is going to be stored in each node.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb20"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb20-1"><a href="#cb20-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb20-2"><a href="#cb20-2" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb20-3"><a href="#cb20-3" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> NodeU32 = <span class="kw">struct</span> <span class="op">{</span></span>
-<span id="cb20-4"><a href="#cb20-4" aria-hidden="true" tabindex="-1"></a>    data: <span class="dt">u32</span>,</span>
-<span id="cb20-5"><a href="#cb20-5" aria-hidden="true" tabindex="-1"></a>    node: std.SinglyLinkedList.Node = .<span class="op">{}</span>,</span>
-<span id="cb20-6"><a href="#cb20-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<span id="cb20-2"><a href="#cb20-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> NodeU32 = <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb20-3"><a href="#cb20-3" aria-hidden="true" tabindex="-1"></a>    data: <span class="dt">u32</span>,</span>
+<span id="cb20-4"><a href="#cb20-4" aria-hidden="true" tabindex="-1"></a>    node: std.SinglyLinkedList.Node = .<span class="op">{}</span>,</span>
+<span id="cb20-5"><a href="#cb20-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>After we created our custom “node type” that can store the specific data type that we want, we can just create a new and empty singly linked list, which will store our nodes. To do that, we just create a new object with the type <code>SinglyLinkedList</code>, like this:</p>
 <div class="cell">
@@ -762,7 +762,7 @@ <h3 data-number="11.3.2" class="anchored" data-anchor-id="how-to-use-a-singly-li
 <li><code>len()</code> to count how many nodes there is in the linked list.</li>
 <li><code>popFirst()</code> to remove the first node (i.e., the “head”) from the linked list.</li>
 </ul>
-<p>So, that is how singly linked lists work in Zig in a nutshell. To sum up what we have exposed here, this is all the source code that was exposed in this section inside the single cell:</p>
+<p>So, that is how singly linked lists work in Zig in a nutshell. To sum up, this is all the source code that was exposed in this section inside the single cell:</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb25"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb25-1"><a href="#cb25-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> NodeU32 = <span class="kw">struct</span> <span class="op">{</span></span>
 <span id="cb25-2"><a href="#cb25-2" aria-hidden="true" tabindex="-1"></a>    data: <span class="dt">u32</span>,</span>
@@ -786,36 +786,83 @@ <h3 data-number="11.3.2" class="anchored" data-anchor-id="how-to-use-a-singly-li
 </div>
 </div>
 </section>
+<section id="how-to-use-a-doubly-linked-list" class="level3" data-number="11.3.3">
+<h3 data-number="11.3.3" class="anchored" data-anchor-id="how-to-use-a-doubly-linked-list"><span class="header-section-number">11.3.3</span> How to use a doubly linked list</h3>
+<p>If you want to use a doubly linked list instead, you will face a similar workflow compared to the singly linked list:</p>
+<ol type="1">
+<li>You first create a “custom node type” that can store the specific data type that you want.</li>
+<li>Create an empty doubly linked list object.</li>
+<li>Create the nodes of linked list.</li>
+<li>Start to insert the nodes inside the list.</li>
+</ol>
+<p>In your “custom node type”, you should use the <code>DoublyLinkedList.Node</code> type to denote the <code>node</code> member of the struct. The snippet below demonstrates that. Here we are creating, once again, a node type that can store <code>u32</code> values. But this time, this struct is tailored to be used inside a <code>DoublyLinkedList</code> struct.</p>
+<p>After this step, the way that you create the new empty linked list, and the nodes that you want insert, is practically identical to the singly linked list case. But, things are different when you start to add nodes to the list. Instead of using the <code>prepend()</code> method of the list object, you should use the <code>append()</code> method to add the nodes to the linked list.</p>
+<p>This <code>append()</code> method from the linked list object will always append the input node to the end of the linked list. However, in case you want to add the new node into a different position of the list, then, you should take a look at the <code>insertAfter()</code> and <code>insertBefore()</code> methods of the linked list object. These methods allow you to insert the new node either after or before an existing node in the list.</p>
+<div class="cell">
+<div class="sourceCode cell-code" id="cb27"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb27-1"><a href="#cb27-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> NodeU32 = <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb27-2"><a href="#cb27-2" aria-hidden="true" tabindex="-1"></a>    data: <span class="dt">u32</span>,</span>
+<span id="cb27-3"><a href="#cb27-3" aria-hidden="true" tabindex="-1"></a>    node: std.DoublyLinkedList.Node = .<span class="op">{}</span>,</span>
+<span id="cb27-4"><a href="#cb27-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
+<span id="cb27-5"><a href="#cb27-5" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb27-6"><a href="#cb27-6" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> list: std.DoublyLinkedList = .<span class="op">{}</span>;</span>
+<span id="cb27-7"><a href="#cb27-7" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> one: NodeU32 = .<span class="op">{</span> .data = <span class="dv">1</span> <span class="op">}</span>;</span>
+<span id="cb27-8"><a href="#cb27-8" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> two: NodeU32 = .<span class="op">{</span> .data = <span class="dv">2</span> <span class="op">}</span>;</span>
+<span id="cb27-9"><a href="#cb27-9" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> three: NodeU32 = .<span class="op">{</span> .data = <span class="dv">3</span> <span class="op">}</span>;</span>
+<span id="cb27-10"><a href="#cb27-10" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> five: NodeU32 = .<span class="op">{</span> .data = <span class="dv">5</span> <span class="op">}</span>;</span>
+<span id="cb27-11"><a href="#cb27-11" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb27-12"><a href="#cb27-12" aria-hidden="true" tabindex="-1"></a>list.append(&amp;one.node); <span class="co">// {1}</span></span>
+<span id="cb27-13"><a href="#cb27-13" aria-hidden="true" tabindex="-1"></a>list.append(&amp;three.node); <span class="co">// {1, 3}</span></span>
+<span id="cb27-14"><a href="#cb27-14" aria-hidden="true" tabindex="-1"></a>list.insertAfter(</span>
+<span id="cb27-15"><a href="#cb27-15" aria-hidden="true" tabindex="-1"></a>    &amp;one.node,</span>
+<span id="cb27-16"><a href="#cb27-16" aria-hidden="true" tabindex="-1"></a>    &amp;five.node</span>
+<span id="cb27-17"><a href="#cb27-17" aria-hidden="true" tabindex="-1"></a>); <span class="co">// {1, 5, 3}</span></span>
+<span id="cb27-18"><a href="#cb27-18" aria-hidden="true" tabindex="-1"></a>list.append(&amp;two.node); <span class="co">// {1, 5, 3, 2}</span></span>
+<span id="cb27-19"><a href="#cb27-19" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb27-20"><a href="#cb27-20" aria-hidden="true" tabindex="-1"></a><span class="kw">try</span> stdout.print(<span class="st">"Number of nodes: {}"</span>, .<span class="op">{</span>list.len()<span class="op">}</span>);</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="cell-output cell-output-stdout">
+<pre><code>Number of nodes: 4</code></pre>
+</div>
+</div>
+<p>These are other methods from the <code>DoublyLinkedList</code> object that might interest you:</p>
+<ul>
+<li><code>remove()</code>: to remove a specific node from the list.</li>
+<li><code>len()</code>: to count the number of nodes in the list.</li>
+<li><code>prepend()</code>: to add a node to the beginning of the list (i.e.&nbsp;set the head node of the list).</li>
+<li><code>pop()</code>: to remove the last node of the list.</li>
+<li><code>popFirst()</code>: to remove the first node of the list.</li>
+<li><code>concatByMoving()</code>: to concat two doubly linked lists together.</li>
+</ul>
+</section>
 </section>
 <section id="multi-array-structure" class="level2" data-number="11.4">
 <h2 data-number="11.4" class="anchored" data-anchor-id="multi-array-structure"><span class="header-section-number">11.4</span> Multi array structure</h2>
 <p>Zig introduces a new data structure called <code>MultiArrayList()</code>. It’s a different version of the dynamic array that we have introduced in <a href="#sec-dynamic-array" class="quarto-xref"><span>Section 11.1</span></a>. The difference between this structure and the <code>ArrayList()</code> that we know from <a href="#sec-dynamic-array" class="quarto-xref"><span>Section 11.1</span></a>, is that <code>MultiArrayList()</code> creates a separate dynamic array for each field of the struct that you provide as input.</p>
 <p>Consider the following code example. We create a new custom struct called <code>Person</code>. This struct contains three different data members, or, three different fields. As consequence, when we provide this <code>Person</code> data type as input to <code>MultiArrayList()</code>, this creates a “struct of three different arrays” called <code>PersonArray</code>. In other words, this <code>PersonArray</code> is a struct that contains three internal dynamic arrays in it. One array for each field found in the <code>Person</code> struct definition.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb27"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb27-1"><a href="#cb27-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb27-2"><a href="#cb27-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Person = <span class="kw">struct</span> <span class="op">{</span></span>
-<span id="cb27-3"><a href="#cb27-3" aria-hidden="true" tabindex="-1"></a>    name: []<span class="kw">const</span> <span class="dt">u8</span>,</span>
-<span id="cb27-4"><a href="#cb27-4" aria-hidden="true" tabindex="-1"></a>    age: <span class="dt">u8</span>,</span>
-<span id="cb27-5"><a href="#cb27-5" aria-hidden="true" tabindex="-1"></a>    height: <span class="dt">f32</span>,</span>
-<span id="cb27-6"><a href="#cb27-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
-<span id="cb27-7"><a href="#cb27-7" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> PersonArray = std.MultiArrayList(Person);</span>
-<span id="cb27-8"><a href="#cb27-8" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb27-9"><a href="#cb27-9" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb27-10"><a href="#cb27-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> gpa = std.heap.GeneralPurposeAllocator(.<span class="op">{}</span>)<span class="op">{}</span>;</span>
-<span id="cb27-11"><a href="#cb27-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> allocator = gpa.allocator();</span>
-<span id="cb27-12"><a href="#cb27-12" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> people = PersonArray<span class="op">{}</span>;</span>
-<span id="cb27-13"><a href="#cb27-13" aria-hidden="true" tabindex="-1"></a>    <span class="kw">defer</span> people.deinit(allocator);</span>
-<span id="cb27-14"><a href="#cb27-14" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb27-15"><a href="#cb27-15" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
-<span id="cb27-16"><a href="#cb27-16" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Auguste"</span>, .age = <span class="dv">15</span>, .height = <span class="fl">1.54</span></span>
-<span id="cb27-17"><a href="#cb27-17" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
-<span id="cb27-18"><a href="#cb27-18" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
-<span id="cb27-19"><a href="#cb27-19" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Elena"</span>, .age = <span class="dv">26</span>, .height = <span class="fl">1.65</span></span>
-<span id="cb27-20"><a href="#cb27-20" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
-<span id="cb27-21"><a href="#cb27-21" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
-<span id="cb27-22"><a href="#cb27-22" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Michael"</span>, .age = <span class="dv">64</span>, .height = <span class="fl">1.87</span></span>
-<span id="cb27-23"><a href="#cb27-23" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
-<span id="cb27-24"><a href="#cb27-24" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb29"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb29-1"><a href="#cb29-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb29-2"><a href="#cb29-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Person = <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb29-3"><a href="#cb29-3" aria-hidden="true" tabindex="-1"></a>    name: []<span class="kw">const</span> <span class="dt">u8</span>,</span>
+<span id="cb29-4"><a href="#cb29-4" aria-hidden="true" tabindex="-1"></a>    age: <span class="dt">u8</span>,</span>
+<span id="cb29-5"><a href="#cb29-5" aria-hidden="true" tabindex="-1"></a>    height: <span class="dt">f32</span>,</span>
+<span id="cb29-6"><a href="#cb29-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
+<span id="cb29-7"><a href="#cb29-7" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> PersonArray = std.MultiArrayList(Person);</span>
+<span id="cb29-8"><a href="#cb29-8" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb29-9"><a href="#cb29-9" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb29-10"><a href="#cb29-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> gpa = std.heap.GeneralPurposeAllocator(.<span class="op">{}</span>)<span class="op">{}</span>;</span>
+<span id="cb29-11"><a href="#cb29-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> allocator = gpa.allocator();</span>
+<span id="cb29-12"><a href="#cb29-12" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> people = PersonArray<span class="op">{}</span>;</span>
+<span id="cb29-13"><a href="#cb29-13" aria-hidden="true" tabindex="-1"></a>    <span class="kw">defer</span> people.deinit(allocator);</span>
+<span id="cb29-14"><a href="#cb29-14" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb29-15"><a href="#cb29-15" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
+<span id="cb29-16"><a href="#cb29-16" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Auguste"</span>, .age = <span class="dv">15</span>, .height = <span class="fl">1.54</span></span>
+<span id="cb29-17"><a href="#cb29-17" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
+<span id="cb29-18"><a href="#cb29-18" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
+<span id="cb29-19"><a href="#cb29-19" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Elena"</span>, .age = <span class="dv">26</span>, .height = <span class="fl">1.65</span></span>
+<span id="cb29-20"><a href="#cb29-20" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
+<span id="cb29-21"><a href="#cb29-21" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
+<span id="cb29-22"><a href="#cb29-22" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Michael"</span>, .age = <span class="dv">64</span>, .height = <span class="fl">1.87</span></span>
+<span id="cb29-23"><a href="#cb29-23" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
+<span id="cb29-24"><a href="#cb29-24" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>In other words, instead of creating an array of “persons”, the <code>MultiArrayList()</code> function creates a “struct of arrays”. Each data member of this struct is a different array that stores the values of a specific field from the <code>Person</code> values that were added (or, appended) to this “struct of arrays”. One important detail is that each of these separate internal arrays stored inside <code>PersonArray</code> are dynamic arrays. This means that these arrays can grow in capacity automatically as needed, to accomodate more values.</p>
 <p>The <a href="#fig-multi-array" class="quarto-xref">Figure&nbsp;<span>11.5</span></a> exposed below presents a diagram that describes the <code>PersonArray</code> struct that we have created in the previous code example. Notice that the values of the data members present in each of the three <code>Person</code> values that we have appended into the <code>PersonArray</code> object , are scattered across three different internal arrays of the <code>PersonArray</code> object.</p>
@@ -831,9 +878,9 @@ <h2 data-number="11.4" class="anchored" data-anchor-id="multi-array-structure"><
 </div>
 <p>You can easily access each of these arrays separately, and iterate over the values of each array. For that, you will need to call the <code>items()</code> method from the <code>PersonArray</code> object, and provide as input to this method, the name of the field that you want to iterate over. If you want to iterate through the <code>.age</code> array for example, then, you need to call <code>items(.age)</code> from the <code>PersonArray</code> object, like in the example below:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb28"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb28-1"><a href="#cb28-1" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (people.items(.age)) |*age| <span class="op">{</span></span>
-<span id="cb28-2"><a href="#cb28-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"Age: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>age.*<span class="op">}</span>);</span>
-<span id="cb28-3"><a href="#cb28-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb30"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb30-1"><a href="#cb30-1" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (people.items(.age)) |*age| <span class="op">{</span></span>
+<span id="cb30-2"><a href="#cb30-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"Age: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>age.*<span class="op">}</span>);</span>
+<span id="cb30-3"><a href="#cb30-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Age: 15
 Age: 26
@@ -842,15 +889,15 @@ <h2 data-number="11.4" class="anchored" data-anchor-id="multi-array-structure"><
 <p>In this example we are calling the <code>items()</code> method directly from the <code>PersonArray</code> object. However, in most situations it’s recommened to call this <code>items()</code> method from a “slice object”, which you can create from the <code>slice()</code> method. The reason for this is that calling <code>items()</code> multiple times have better performance if you use a slice object.</p>
 <p>Therefore, if you are planning to access only one of the internal arrays from your “multi array struct”, it’s fine to call <code>items()</code> directly from the multi array object. But if you need to access many of the internal arrays from your “multi array struct”, then, you will likely need to call <code>items()</code> more than once, and, in such circumstance, is better to call <code>items()</code> through a slice object. The example below demonstrates the use of such object:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb30"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb30-1"><a href="#cb30-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> slice = people.slice();</span>
-<span id="cb30-2"><a href="#cb30-2" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (slice.items(.age)) |*age| <span class="op">{</span></span>
-<span id="cb30-3"><a href="#cb30-3" aria-hidden="true" tabindex="-1"></a>    age.* += <span class="dv">10</span>;</span>
-<span id="cb30-4"><a href="#cb30-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
-<span id="cb30-5"><a href="#cb30-5" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (slice.items(.name), slice.items(.age)) |*n,*a| <span class="op">{</span></span>
-<span id="cb30-6"><a href="#cb30-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(</span>
-<span id="cb30-7"><a href="#cb30-7" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Name: {s}, Age: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>n.*, a.*<span class="op">}</span></span>
-<span id="cb30-8"><a href="#cb30-8" aria-hidden="true" tabindex="-1"></a>    );</span>
-<span id="cb30-9"><a href="#cb30-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb32"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb32-1"><a href="#cb32-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> slice = people.slice();</span>
+<span id="cb32-2"><a href="#cb32-2" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (slice.items(.age)) |*age| <span class="op">{</span></span>
+<span id="cb32-3"><a href="#cb32-3" aria-hidden="true" tabindex="-1"></a>    age.* += <span class="dv">10</span>;</span>
+<span id="cb32-4"><a href="#cb32-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
+<span id="cb32-5"><a href="#cb32-5" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (slice.items(.name), slice.items(.age)) |*n,*a| <span class="op">{</span></span>
+<span id="cb32-6"><a href="#cb32-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(</span>
+<span id="cb32-7"><a href="#cb32-7" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Name: {s}, Age: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>n.*, a.*<span class="op">}</span></span>
+<span id="cb32-8"><a href="#cb32-8" aria-hidden="true" tabindex="-1"></a>    );</span>
+<span id="cb32-9"><a href="#cb32-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Name: Auguste, Age: 25
 Name: Elena, Age: 36
diff --git a/docs/search.json b/docs/search.json
index 81682d32..a11536a5 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -904,7 +904,7 @@
     "href": "Chapters/09-data-structures.html#linked-lists",
     "title": "11  Data Structures",
     "section": "11.3 Linked lists",
-    "text": "11.3 Linked lists\nThe Zig Standard Library provides an implementation for both singly and doubly linked lists. More specifically, through the structs SinglyLinkedList and DoublyLinkedList.\nIn case you are not familiar with these data structures, a linked list is a linear data structure that looks like a chain, or, a rope. The main advantage of this data structure is that you normally have very fast insertion and deletion operations. But, as a disadvantage, iterating through this data structure is usually not so fast as iterating through an array.\nThe idea behind a linked list is to build a structure that consists of a sequence of nodes connected to each other by pointers. This means that linked lists are usually not contiguous in memory, because each node might be anywhere in memory. They do not need to be close to one another.\nIn Figure 11.3 we can see a diagram of a singly linked list. We begin at the first node (which is usually called “the head of the linked list”). Then, from this first node we uncover the remaining nodes in the structure, by following the locations pointed by the pointers found in each node.\nEach node has two things in it. It has the value that is stored in the current node , and also, a pointer. This pointer points to the next node in the list. If this pointer is null, then, it means that we have reached the end of our linked list.\n\n\n\n\n\n\nFigure 11.3: A diagram of a singly linked list.\n\n\n\nIn Figure 11.4 we can see a diagram of a doubly linked list. The only thing that really changes now is that every node in the linked list has both a pointer to the previous node, and, a pointer to the next node. So every node in a doubly linked list has two pointers in it. These are usually called the prev (for “previous”) and the next (for “next”) pointers of the node.\nIn the singly linked list example, we had only one single pointer in each node, and this singular pointer was always pointing to the next node in the sequence. This means that singly linked lists normally have only the next pointer in them.\n\n\n\n\n\n\nFigure 11.4: A diagram of a doubly linked list.\n\n\n\n\n11.3.1 Recent change in the API\nOn previous versions of Zig, the SinglyLinkedList and DoublyLinkedList structs were initially implemented as “generics data structures”. Meaning that, you would use a generic function to create a singly (or doubly) linked list that could store the specific data type that you wanted to use. We will learn more about generics at Section 12.2, and also, how we can create a “generic data structure” at Section 12.2.2.\nHowever, on the latest versions of Zig, the structs SinglyLinkedList and DoublyLinkedList were altered to use a “less generic API”. This specific change was introduced on April 3, 2025. Therefore, check if your Zig version is one released after this date. Just have in mind that if you don’t have a very recent version of the Zig compiler, you might have problems while trying to compile the next examples exposed here.\n\n\n11.3.2 How to use a singly linked list\nFor example, consider that you are creating a singly linked list that is going to store u32 values. Given this scenario, the first thing that we need to do, is to create a “node type” that is capable of storing a u32 value. The NodeU32 type exposed below demonstrates such “node type”.\nNotice that the data type associated with the member named data is the most important part of this custom “node type”. It determines the data type that is going to be stored in each node.\n\nconst std = @import(\"std\");\n\nconst NodeU32 = struct {\n    data: u32,\n    node: std.SinglyLinkedList.Node = .{},\n};\n\nAfter we created our custom “node type” that can store the specific data type that we want, we can just create a new and empty singly linked list, which will store our nodes. To do that, we just create a new object with the type SinglyLinkedList, like this:\n\nvar list: std.SinglyLinkedList = .{};\n\nNow, we have our linked list… But how can we insert nodes in it? Well, first of all, we need to create our nodes. So let’s focus on that first. The snippet exposed below demonstrates how we could use our NodeU32 struct to create such nodes.\nNotice in this snippet that we are just setting the data member of the struct for now. We don’t need to connect these nodes together in this first instance. This is why we ignore the node member at first. But we are going to connect these nodes in a future point of the code, which is why these objects are marked as “variable objects”, so that we can alter them in the future.\n\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nNow that we have both the linked list and also the nodes created, we can start to connect them together. You can use the prepend() method from the linked list object to insert the first node in the list, which is the “head” of the linked list. As the name suggests, this specific method prepends the input node to the linked list, or, in other words, it transforms the input node into the first node of the list.\nAfter we added the “head node” of the list, we can start to add the “next nodes” in the list by using the insertAfter() method from the SinglyLinkedList.Node type, which, in our case here, is accessible through the node member of our NodeU32 type. Thus, we can start to create the connections between the nodes by calling this method from the node objects that are present in the list. Like in this example below:\n\nlist.prepend(&two.node); // {2}\ntwo.node.insertAfter(&five.node); // {2, 5}\ntwo.node.insertAfter(&three.node); // {2, 3, 5}\n\nYou can also call the prepend() method again to add new nodes to the beginning of the linked list, which means, effectively, changing the “head node” of the list, like this:\n\nlist.prepend(&one.node); // {1, 2, 3, 5}\n\nThere are other methods available from the singly linked list object that you might be interested. You can find a summary of them in the bullet points below:\n\nremove() to remove a specific node from the linked list.\nlen() to count how many nodes there is in the linked list.\npopFirst() to remove the first node (i.e., the “head”) from the linked list.\n\nSo, that is how singly linked lists work in Zig in a nutshell. To sum up what we have exposed here, this is all the source code that was exposed in this section inside the single cell:\n\nconst NodeU32 = struct {\n    data: u32,\n    node: std.SinglyLinkedList.Node = .{},\n};\n\nvar list: std.SinglyLinkedList = .{};\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nlist.prepend(&two.node); // {2}\ntwo.node.insertAfter(&five.node); // {2, 5}\ntwo.node.insertAfter(&three.node); // {2, 3, 5}\nlist.prepend(&one.node); // {1, 2, 3, 5}\n\ntry stdout.print(\"Number of nodes: {}\", .{list.len()});\n\nNumber of nodes: 4",
+    "text": "11.3 Linked lists\nThe Zig Standard Library provides an implementation for both singly and doubly linked lists. More specifically, through the structs SinglyLinkedList and DoublyLinkedList.\nIn case you are not familiar with these data structures, a linked list is a linear data structure that looks like a chain, or, a rope. The main advantage of this data structure is that you normally have very fast insertion and deletion operations. But, as a disadvantage, iterating through this data structure is usually not so fast as iterating through an array.\nThe idea behind a linked list is to build a structure that consists of a sequence of nodes connected to each other by pointers. This means that linked lists are usually not contiguous in memory, because each node might be anywhere in memory. They do not need to be close to one another.\nIn Figure 11.3 we can see a diagram of a singly linked list. We begin at the first node (which is usually called “the head of the linked list”). Then, from this first node we uncover the remaining nodes in the structure, by following the locations pointed by the pointers found in each node.\nEach node has two things in it. It has the value that is stored in the current node , and also, a pointer. This pointer points to the next node in the list. If this pointer is null, then, it means that we have reached the end of our linked list.\n\n\n\n\n\n\nFigure 11.3: A diagram of a singly linked list.\n\n\n\nIn Figure 11.4 we can see a diagram of a doubly linked list. The only thing that really changes now is that every node in the linked list has both a pointer to the previous node, and, a pointer to the next node. So every node in a doubly linked list has two pointers in it. These are usually called the prev (for “previous”) and the next (for “next”) pointers of the node.\nIn the singly linked list example, we had only one single pointer in each node, and this singular pointer was always pointing to the next node in the sequence. This means that singly linked lists normally have only the next pointer in them.\n\n\n\n\n\n\nFigure 11.4: A diagram of a doubly linked list.\n\n\n\n\n11.3.1 Recent change in the API\nOn previous versions of Zig, the SinglyLinkedList and DoublyLinkedList structs were initially implemented as “generics data structures”. Meaning that, you would use a generic function to create a singly (or doubly) linked list that could store the specific data type that you wanted to use. We will learn more about generics at Section 12.2, and also, how we can create a “generic data structure” at Section 12.2.2.\nHowever, on the latest versions of Zig, the structs SinglyLinkedList and DoublyLinkedList were altered to use a “less generic API”. This specific change was introduced on April 3, 2025. Therefore, check if your Zig version is one released after this date. Just have in mind that if you don’t have a very recent version of the Zig compiler, you might have problems while trying to compile the next examples exposed here.\n\n\n11.3.2 How to use a singly linked list\nFor example, consider that you are creating a singly linked list that is going to store u32 values. Given this scenario, the first thing that we need to do, is to create a “node type” that is capable of storing a u32 value. The NodeU32 type exposed below demonstrates such “node type”.\nNotice that the data type associated with the member named data is the most important part of this custom “node type”. It determines the data type that is going to be stored in each node.\n\nconst std = @import(\"std\");\nconst NodeU32 = struct {\n    data: u32,\n    node: std.SinglyLinkedList.Node = .{},\n};\n\nAfter we created our custom “node type” that can store the specific data type that we want, we can just create a new and empty singly linked list, which will store our nodes. To do that, we just create a new object with the type SinglyLinkedList, like this:\n\nvar list: std.SinglyLinkedList = .{};\n\nNow, we have our linked list… But how can we insert nodes in it? Well, first of all, we need to create our nodes. So let’s focus on that first. The snippet exposed below demonstrates how we could use our NodeU32 struct to create such nodes.\nNotice in this snippet that we are just setting the data member of the struct for now. We don’t need to connect these nodes together in this first instance. This is why we ignore the node member at first. But we are going to connect these nodes in a future point of the code, which is why these objects are marked as “variable objects”, so that we can alter them in the future.\n\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nNow that we have both the linked list and also the nodes created, we can start to connect them together. You can use the prepend() method from the linked list object to insert the first node in the list, which is the “head” of the linked list. As the name suggests, this specific method prepends the input node to the linked list, or, in other words, it transforms the input node into the first node of the list.\nAfter we added the “head node” of the list, we can start to add the “next nodes” in the list by using the insertAfter() method from the SinglyLinkedList.Node type, which, in our case here, is accessible through the node member of our NodeU32 type. Thus, we can start to create the connections between the nodes by calling this method from the node objects that are present in the list. Like in this example below:\n\nlist.prepend(&two.node); // {2}\ntwo.node.insertAfter(&five.node); // {2, 5}\ntwo.node.insertAfter(&three.node); // {2, 3, 5}\n\nYou can also call the prepend() method again to add new nodes to the beginning of the linked list, which means, effectively, changing the “head node” of the list, like this:\n\nlist.prepend(&one.node); // {1, 2, 3, 5}\n\nThere are other methods available from the singly linked list object that you might be interested. You can find a summary of them in the bullet points below:\n\nremove() to remove a specific node from the linked list.\nlen() to count how many nodes there is in the linked list.\npopFirst() to remove the first node (i.e., the “head”) from the linked list.\n\nSo, that is how singly linked lists work in Zig in a nutshell. To sum up, this is all the source code that was exposed in this section inside the single cell:\n\nconst NodeU32 = struct {\n    data: u32,\n    node: std.SinglyLinkedList.Node = .{},\n};\n\nvar list: std.SinglyLinkedList = .{};\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nlist.prepend(&two.node); // {2}\ntwo.node.insertAfter(&five.node); // {2, 5}\ntwo.node.insertAfter(&three.node); // {2, 3, 5}\nlist.prepend(&one.node); // {1, 2, 3, 5}\n\ntry stdout.print(\"Number of nodes: {}\", .{list.len()});\n\nNumber of nodes: 4\n\n\n\n\n11.3.3 How to use a doubly linked list\nIf you want to use a doubly linked list instead, you will face a similar workflow compared to the singly linked list:\n\nYou first create a “custom node type” that can store the specific data type that you want.\nCreate an empty doubly linked list object.\nCreate the nodes of linked list.\nStart to insert the nodes inside the list.\n\nIn your “custom node type”, you should use the DoublyLinkedList.Node type to denote the node member of the struct. The snippet below demonstrates that. Here we are creating, once again, a node type that can store u32 values. But this time, this struct is tailored to be used inside a DoublyLinkedList struct.\nAfter this step, the way that you create the new empty linked list, and the nodes that you want insert, is practically identical to the singly linked list case. But, things are different when you start to add nodes to the list. Instead of using the prepend() method of the list object, you should use the append() method to add the nodes to the linked list.\nThis append() method from the linked list object will always append the input node to the end of the linked list. However, in case you want to add the new node into a different position of the list, then, you should take a look at the insertAfter() and insertBefore() methods of the linked list object. These methods allow you to insert the new node either after or before an existing node in the list.\n\nconst NodeU32 = struct {\n    data: u32,\n    node: std.DoublyLinkedList.Node = .{},\n};\n\nvar list: std.DoublyLinkedList = .{};\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nlist.append(&one.node); // {1}\nlist.append(&three.node); // {1, 3}\nlist.insertAfter(\n    &one.node,\n    &five.node\n); // {1, 5, 3}\nlist.append(&two.node); // {1, 5, 3, 2}\n\ntry stdout.print(\"Number of nodes: {}\", .{list.len()});\n\nNumber of nodes: 4\n\n\nThese are other methods from the DoublyLinkedList object that might interest you:\n\nremove(): to remove a specific node from the list.\nlen(): to count the number of nodes in the list.\nprepend(): to add a node to the beginning of the list (i.e. set the head node of the list).\npop(): to remove the last node of the list.\npopFirst(): to remove the first node of the list.\nconcatByMoving(): to concat two doubly linked lists together.",
     "crumbs": [
       "<span class='chapter-number'>11</span>  <span class='chapter-title'>Data Structures</span>"
     ]

From 3a45cdb8b2f7fbf5d5b477395cbce60e2c6f4388 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Mon, 26 May 2025 20:49:27 -0300
Subject: [PATCH 140/151] Add section to iterate through list

---
 Chapters/09-data-structures.qmd               |  54 +++++++++
 .../execute-results/html.json                 |   4 +-
 docs/Chapters/09-data-structures.html         | 112 ++++++++++++------
 docs/search.json                              |   2 +-
 4 files changed, 132 insertions(+), 40 deletions(-)

diff --git a/Chapters/09-data-structures.qmd b/Chapters/09-data-structures.qmd
index 36929a45..a8a1d112 100644
--- a/Chapters/09-data-structures.qmd
+++ b/Chapters/09-data-structures.qmd
@@ -920,6 +920,60 @@ These are other methods from the `DoublyLinkedList` object that might interest y
 - `concatByMoving()`: to concat two doubly linked lists together.
 
 
+### Iterating through the linked list
+
+If you want to iterate over the elements of the linked list, all you need to do is to follow
+the trail created by the "pointer to next node". We usually do that inside a while loop, that simply goes to the
+next node over and over, until it finds a null pointer, which means that we hit the end of the list.
+
+This next example demonstrates how such while loop would work. Notice that we are using the `@fieldParentPtr()`
+built-in function to get access to a pointer that points to the parent instance of the `node` object. In other words,
+we get access to a pointer to the `NodeU32` instance that contains the current node. This way, we can use this pointer
+to access the data that is currently stored in this node.
+
+Also notice that in each iteration of the while loop, we are changing the value of the `it` variable to the next node
+in the list. The while loop is interrupted in the moment that this `it` variable becomes null, which will happen
+when the there is not "next node" in the list, which means that we have reached the end of the list.
+
+
+```{zig}
+#| build_type: "run"
+#| auto_main: true
+#| results: "hide"
+const NodeU32 = struct {
+    data: u32,
+    node: std.SinglyLinkedList.Node = .{},
+};
+
+var list: std.SinglyLinkedList = .{};
+var one: NodeU32 = .{ .data = 1 };
+var two: NodeU32 = .{ .data = 2 };
+var three: NodeU32 = .{ .data = 3 };
+var five: NodeU32 = .{ .data = 5 };
+
+list.prepend(&two.node); // {2}
+list.prepend(&five.node); // {5, 2}
+list.prepend(&three.node); // {3, 5, 2}
+list.prepend(&one.node); // {1, 3, 5, 2}
+
+var it = list.first;
+while (it) |node| : (it = node.next) {
+    const l: *NodeU32 = @fieldParentPtr(
+        "node", node
+    );
+    try stdout.print(
+        "Current value: {}", .{l.data}
+    );
+}
+```
+
+```
+Current value: 1
+Current value: 3
+Current value: 5
+Current value: 2
+```
+
 
 
 
diff --git a/_freeze/Chapters/09-data-structures/execute-results/html.json b/_freeze/Chapters/09-data-structures/execute-results/html.json
index b52aa8ad..1193b1cb 100644
--- a/_freeze/Chapters/09-data-structures/execute-results/html.json
+++ b/_freeze/Chapters/09-data-structures/execute-results/html.json
@@ -1,8 +1,8 @@
 {
-  "hash": "2ac41eed214fdc9ab33751c389155448",
+  "hash": "0d90c199a3a2c5a7a25c66baac2ca8aa",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Data Structures\n\nIn this chapter, I want to present the most common Data Structures that are available from\nthe Zig Standard Library, especially `ArrayList` and also `HashMap`. These are generic Data Structures\nthat you can use to store and control any type of data that is produced by your application.\n\n## Dynamic Arrays {#sec-dynamic-array}\n\nIn high level languages, arrays are usually dynamic. They can easily grow\nin size when they have to, and you don't need to worry about it.\nIn contrast, arrays in low level languages are usually static by default.\nThis is the reality of C, C++, Rust and also Zig. Static arrays were presented at\n@sec-arrays, but in this section, we are going to talk about dynamic arrays in Zig.\n\nDynamic arrays are simply arrays that can grow in size during the runtime\nof your program. Most low level languages have some implementation of\na dynamic array in their standard library. C++ have `std::vector`, Rust have `Vec`,\nand Zig have `std.ArrayList`.\n\nThe `std.ArrayList` struct provides a contiguous and growable array for you.\nIt works like any other dynamic array, it allocates a contiguous block of memory, and when this block have no space left,\n`ArrayList` allocates another contiguous and bigger block of memory, copies the\nelements to this new location, and erases (or frees) the previous block of memory.\n\n\n### Capacity vs Length\n\nWhen we talk about dynamic arrays, we usually have two similar concepts that\nare very essential to how a dynamic array works behind the hood.\nThese concepts are *capacity* and *length*. In some contexts, especially\nin C++, *length* is also called of *size*.\n\nAlthough they look similar, these concepts represent different things\nin the context of a dynamic array. *Capacity* is the number of items (or elements)\nthat your dynamic array can currently hold without the need to allocate more memory.\n\nIn contrast, the *length* refers to how many elements in the array\nare currently being used, or, in other words, how many elements in this array\nthat you have assigned a value to. Every dynamic array works around\na block of allocated memory, which represents an array with total capacity for $n$ elements.\nHowever, only a portion of these $n$ elements are being used most of the time. This portion\nof $n$ is the *length* of the array. So every time you append a new value\nto the array, you are incrementing its *length* by one.\n\nThis means that a dynamic array usually works with an extra margin, or an extra space\nthat is currently empty, but waiting and ready to be used. This \"extra space\"\nis essentially the difference between *capacity* and *length*. *Capacity* represents\nthe total number of elements that the array can hold without the need to re-allocate\nor re-expand the array, while the *length* represents how much of this capacity\nis currently being used to hold/store values.\n\n@fig-capacity-length presents this idea visually. Notice that, at first,\nthe capacity of the array is greater than the length of the array.\nSo, the dynamic array have extra space that is currently empty, but it\nis ready to receive a value to be stored.\n\n![Difference between capacity and length in a dynamic array](./../Figures/dynamic-array.png){#fig-capacity-length}\n\nWe can also see in @fig-capacity-length that, when *length* and *capacity* are equal, it means that the array have no space left.\nWe have reached the ceiling of our capacity, and because of that, if we want to store more values\nin this array, we need to expand it. We need to get a bigger space that can hold more values\nthan what we currently have.\n\nA dynamic array works by expanding the underlying array, whenever the *length* becomes equal\nto the *capacity* of the array. It basically allocates a new contiguous block of memory that is bigger\nthan the previous one, then, it copies all values that are currently being stored to this new\nlocation (i.e., this new block of memory), then, it frees the previous block of\nmemory. At the end of this process, the new underlying array have a bigger *capacity*, and, therefore,\nthe *length* becomes, once again, smaller than the *capacity* of the array.\n\nThis is the cycle of a dynamic array. Notice that, throughout this cycle, the *capacity* is always\neither equal to or higher than the *length* of the array. If you have an `ArrayList` object (let's suppose\nyou named it `buffer`), you can check the current capacity of your array by accessing the `capacity`\nattribute of your `ArrayList` object, while the current *length* of it is available at the `items.len`\nattribute.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// Check capacity\nbuffer.capacity;\n// Check length\nbuffer.items.len;\n```\n:::\n\n\n\n### Creating an `ArrayList` object\n\nIn order to use `ArrayList`, you must provide an allocator object to it.\nRemember, Zig does not have a default memory allocator. And as I described in @sec-allocators, all memory\nallocations must be done by an allocator object that you define, that\nyou have control over. In our example here, I'm going to use\na general purpose allocator, but you can use any other allocator\nof your preference.\n\nWhen you initialize an `ArrayList` object, you must provide the data type of the elements of\nthe array. In other words, this defines the type of data that this array (or container) will\nstore. Therefore, if I provide the `u8` type to it, then, I will create a dynamic\narray of `u8` values. However, if I provide a struct that I have defined instead, like the struct `User`\nfrom @sec-structs-and-oop, then, a dynamic array of `User` values\nwill be created. In the example below, with the expression `ArrayList(u8)` we\nare creating a dynamic array of `u8` values.\n\nAfter you provide the data type of the elements of the array, you can initialize\nan `ArrayList` object by either using the `init()` or the `initCapacity()` methods.\nThe former method receives only the allocator object\nas input, while the latter method receives both the allocator object and a capacity number as inputs.\nWith the latter method, you not only initialize the struct, but you\nalso set the starting capacity of the allocated array.\n\nUsing the `initCapacity()` method is the preferred way to initialize your dynamic array.\nBecause reallocations, or, in other words, the process of expanding the capacity of the array,\nis always a high cost operation. You should take any possible opportunity to avoid reallocations in\nyour array. If you know how much space your array needs to occupy at the beginning,\nyou should always use `initCapacity()` to create your dynamic array.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n```\n:::\n\n\n\nIn the example above, the `buffer` object starts as an array of 100 elements. If this\n`buffer` object needs to create more space to accomodate more elements during the runtime of your program, the `ArrayList`\ninternals will perform the necessary actions for you automatically.\nAlso notice the `deinit()` method being used to destroy the `buffer` object at the\nend of the current scope, by freeing all the memory that was allocated for the dynamic\narray stored in this `buffer` object.\n\n\n### Adding new elements to the array\n\nNow that we have created our dynamic array, we can start to use it. You can append (a.k.a \"add\")\nnew values to this array by using the `append()` method. This method works the same way\nas the `append()` method from a Python list, or, the `emplace_back()` method from `std::vector` of C++.\nYou provide a single value to this method, and the method appends this value to the array.\n\nYou can also use the `appendSlice()` method to append multiple values at once. You provide\na slice (slices were described in @sec-arrays) to this method, and the method adds all values present\nin this slice to your dynamic array.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry buffer.append('H');\ntry buffer.append('e');\ntry buffer.append('l');\ntry buffer.append('l');\ntry buffer.append('o');\ntry buffer.appendSlice(\" World!\");\n```\n:::\n\n\n### Removing elements from the array {#sec-dynamic-array-remove}\n\nYou can use the `pop()` method to \"pop\" or remove\nthe last element in the array. It's worth noting that this method\ndo not change the capacity of the array. It just deletes or erases\nthe last value stored in the array.\n\nAlso, this method returns as result the value that got deleted. That is, you can\nuse this method to both get the last value in the array, and also, remove\nit from the array. It's a \"get and remove value\" type of method.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exclamation_mark = buffer.pop();\n```\n:::\n\n\nNow, if you want to remove specific elements from specific positions\nof your array, you can use the `orderedRemove()` method from your\n`ArrayList` object. With this method, you can provide an index as input,\nthen, the method will delete the value that is at this index in the array.\nYou are effectively reducing the *length* of the array everytime you execute\nan `orderedRemove()` operation.\n\nIn the example below, we first create an `ArrayList` object, and we fill it\nwith numbers. Then, we use `orderedRemove()` to remove the value at\nindex 3 in the array, two consecutive times.\n\nAlso, notice that we are assigning the result of `orderedRemove()` to the\nunderscore character. So we are discarding the result value of this method.\nThe `orderedRemove()` method returns the value that got deleted, in a similar\nstyle to the `pop()` method.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n\nfor (0..10) |i| {\n    const index: u8 = @intCast(i);\n    try buffer.append(index);\n}\n\nstd.debug.print(\n    \"{any}\\n\", .{buffer.items}\n);\n_ = buffer.orderedRemove(3);\n_ = buffer.orderedRemove(3);\n\nstd.debug.print(\"{any}\\n\", .{buffer.items});\nstd.debug.print(\"{any}\\n\", .{buffer.items.len});\n```\n:::\n\n\n```\n{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }\n{ 0, 1, 2, 5, 6, 7, 8, 9 }\n8\n```\n\nOne key characteristic about `orderedRemove()` is that it preserves the order\nof the values in the array. So, it deletes the value that you asked it to\nremove, but it also makes sure that the order of the values that remain in the array\nstay the same as before.\n\nNow, if you don't care about the order of the values, for example, maybe you want to treat\nyour dynamic array as a set of values, like the `std::unordered_set`\nstructure from C++, you can use the `swapRemove()` method instead. This method\nworks similarly to the `orderedRemove()` method. You give an index to this\nmethod, then, it deletes the value that is at this index in the array.\nBut this method does not preserve the original order of the values that remain\nin the array. As a result, `swapRemove()` is, in general, faster than `orderedRemove()`.\n\n\n### Inserting elements at specific indexes\n\nWhen you need to insert values in the middle of your array,\ninstead of just appending them to the end of the array, you need to use\nthe `insert()` and `insertSlice()` methods, instead of\nthe `append()` and `appendSlice()` methods.\n\nThese two methods work very similarly to `insert()` and `insert_range()`\nfrom the C++ `std::vector` class. You provide an index to these methods,\nand they insert the values that you provide at that index in the array.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 10);\ndefer buffer.deinit();\n\ntry buffer.appendSlice(\"My Pedro\");\ntry buffer.insert(4, '3');\ntry buffer.insertSlice(2, \" name\");\nfor (buffer.items) |char| {\n    try stdout.print(\"{c}\", .{char});\n}\n```\n:::\n\n\n```\nMy name P3edro\n```\n\n\n### Conclusion\n\nIf you feel the lack of some other method, I recommend\nyou to read the [official documentation for the `ArrayListAligned`](https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned)[^zig-array2]\nstruct, which describes most of the methods available\nthrough the `ArrayList` object.\n\nYou will notice that there is a lot of other methods in this page that\nI did not described here, and I recommend you to explore these methods,\nand understand how they work.\n\n[^zig-array2]: <https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned>\n\n\n\n## Maps or HashTables {#sec-maps-hashtables}\n\nSome professionals know this type of data structure by different terms, like \"map\",\n\"hashmap\" or \"associative arrays\". But the most common term used is *hashtable*.\nEvery programming language normally have some implementation of a hashtable in their\nstandard libraries. Python have `dict()`, C++ have `std::map` and `std::unordered_map`, Rust\nhave `HashMap`, Javascript have `Object()` and `Map()`, etc.\n\n\n\n### What is a hashtable?\n\nA hashtable is a data structure based on key-value pairs.\nYou provide a key and a value to this structure, then, the hashtable will store\nthe input value at a location that can be identified by the input\nkey that you provided.\nIt does that by using an underlying array and a hash function.\nThese two components are essential to how a hashtable works.\n\nUnder the hood, the hashtable contains an array. This array is where the values\nare stored, and the elements of this array are usually called of *buckets*.\nSo the values that you provide to the hashtable are stored inside buckets,\nand you access each bucket by using an index.\n\nWhen you provide a key to a hashtable, it passes this key to the\nhash function. This hash function uses some sort of hashing algorithm to transform\nthis key into an index. This index is actually an array index. It's a position\nin the underlying array of the hashtable.\nThis is how a key identifies a specific position (or location) inside the hashtable\nstructure.\n\nTherefore, you provide a key to the hashtable, and this key identifies a specific location\ninside the hashtable, then, the hashtable takes the input value that you provided,\nand stores this value in the location identified by this input key.\nYou could say that the key maps to the value stored in the hashtable. You find\nthe value, by using the key that identifies the location where the value is stored.\nThe @fig-hashtable presents this process visually.\n\n\n![A diagram of a Hashtable. Source: Wikipedia, the free encyclopedia.](./../Figures/hashtable.svg){#fig-hashtable}\n\n\nThe operation described in the previous paragraph is normally called an *insertion* operation.\nBecause you are inserting new values into the hashtable.\nBut there are other types of operations in hashtables such as *delete* and *lookup*.\nDelete is self describing, it's when you delete (or remove) a value from the hashtable.\nWhile lookup corresponds to when you look at a value that is stored in\nthe hashtable, by using the key that identifies the location where this value is stored.\n\nSometimes, instead of storing the values directly, the underlying array of the hashtable might be an array of pointers,\ni.e., the buckets of the array stores pointers that points to the value,\nor also, may be an array of linked lists.\nThese cases are common on hashtables that allows duplicate keys, or, in other words,\non hashtables that effectively handle \"collisions\" that may arise from the hash function.\n\nDuplicate keys, or this \"collision\" thing that I'm talking about, is when you have two different keys\nthat points to the same location (i.e., to the same index)\nin the underlying array of the hashtable. This might happen depending on the characteristics of the hash function\nthat is being used in the hashtable. Some implementations of the hashtable will actively deal with collisions,\nmeaning that, they will handle this case in some way. For example, the hashtable\nmight transform all buckets into linked lists. Because with a linked list you can store\nmultiple values into a single bucket.\n\nThere are different techniques to handle collisions in hashtables, which I will not describe\nin this book, because it's not our main scope here. But you can find a good description of\nsome of the most common techniques at the Wikipedia page of hashtables [@wikipedia_hashtables].\n\n\n### Hashtables in Zig {#sec-hashmap}\n\nThe Zig Standard Library provides different implementations of a hashtable.\nEach implementation have its own cons and pros, which we will\ndiscuss later on, and all of them are available through the `std.hash_map` module.\n\nThe `HashMap` struct is a general-purpose hashtable,\nwhich have very fast operations (lookup, insertion, delete), and also,\nquite high load factors for low memory usage. You can create and provide a context object\nto the `HashMap` constructor. This context object allows you to tailor\nthe behaviour of the hashtable itself, because you can\nprovide a hash function implementation to be used by the hashtable\nthrough this context object.\n\nBut let's not worry about this context object now, because it's meant to be used\nby \"experts in the field of hashtables\". Since we are most likely not\nexperts in this field, we are going to take the easy way to create\na hashtable. Which is by using the `AutoHashMap()` function.\n\n\nThis `AutoHashMap()` function is essentially a \"create a hashtable object that uses the default settings\"\ntype of function. It automatically chooses a context object, and, therefore, a hash function implementation,\nfor you. This function receives two data types as input, the first input is the data type of the keys\nthat will be used in this hashtable, while the second input is the data type of the data that will be\nstored inside the hashtable, that is, the data type of the values to be stored.\n\nIn the example below, we are providing the data type `u32` in the first argument, and `u16` in the second argument of this\nfunction. This means that we are going to use `u32` values as keys in this hashtable, while `u16` values are the actual values\nthat are going to be stored into this hashtable.\nAt the end of this process, the `hash_table` object contains a `HashMap` object\nthat uses the default settings and context.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n    std.debug.print(\n        \"Value at key 50050: {d}\\n\",\n        .{hash_table.get(50050).?}\n    );\n\n    if (hash_table.remove(57709)) {\n        std.debug.print(\n            \"Value at key 57709 successfully removed!\\n\",\n            .{}\n        );\n    }\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n}\n```\n:::\n\n\n```\nN of values stored: 3\nValue at key 50050: 55\nValue at key 57709 successfully removed!\nN of values stored: 2\n```\n\nYou can add/put new values into the hashtable by using the `put()` method. The first argument\nis the key to be used, and the second argument is the actual value that you want to store inside\nthe hashtable. In the example below, we first add the value 89 using the key 54321, next, we add\nthe value 55 using the key 50050, etc.\n\nNotice that we have used the method `count()` to see how many values are currently stored in the\nhashtable. After that, we also use the `get()` method to access (or look) at the value stored in\nthe position identified by the key 500050. The output of this `get()` method is an optional value.\nThis is why we use the `?` method at the end to get the actual value.\n\nAlso notice that we can remove (or delete) values from the hashtable by using the `remove()` method.\nYou provide the key that identifies the value that you want to delete, then, the method will\ndelete this value and return a `true` value as output. This `true` value essentially tells us\nthat the method successfully deleted the value.\n\nBut this delete operation might not be always successful. For example, you might provide the wrong\nkey to this method. I mean, maybe you provide\n(either intentionally or unintentionally) a key that points to an empty bucket,\ni.e., a bucket that still doesn't have a value in it.\nIn this case, the `remove()` method would return a `false` value.\n\n\n\n### Iterating through the hashtable\n\nIterating through the keys and values that are currently being stored in\nthe hashtable is a very common necessity.\nYou can do that in Zig by using an iterator object that can iterate\nthrough the elements of your hashtable object.\n\nThis iterator object works like any other iterator object that you would\nfind in languages such as C++ and Rust. It's basically a pointer object\nthat points to some value in the container, and has a `next()` method\nthat you can use to navigate (or iterate) through the values in the\ncontainer.\n\nYou can create such iterator object by using the `iterator()` method of the hashtable object.\nThis method returns an iterator object, from which you can use the `next()` method in conjunction\nwith a while loop to iterate through the elements of your hashtable. The `next()` method returns an optional\n`Entry` value, and therefore, you must unwrap this optional value to get the actual `Entry` value\nfrom which you can access the key and also the value identified by this key.\n\nWith this `Entry` value at hand, you can access the key of this current entry by using the `key_ptr`\nattribute and dereferencing the pointer that lives inside of it, while the value identified by this\nkey is accessed through the `value_ptr` attribute instead, which is also a pointer to be dereferenced.\nThe code example below demonstrates the use of these elements:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n\n    var it = hash_table.iterator();\n    while (it.next()) |kv| {\n        // Access the current key\n        std.debug.print(\"Key: {d} | \", .{kv.key_ptr.*});\n        // Access the current value\n        std.debug.print(\"Value: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n:::\n\n\n```\nKey: 54321 | Value: 89\nKey: 50050 | Value: 55\nKey: 57709 | Value: 41\n```\n\n\nIf you want to iterate specifically through the values or the keys of your hashtable,\nyou can create a key iterator or a value iterator object. These are also iterator\nobjects, which have the same `next()` method that you can use to iterate through the\nhashtable.\n\nKey iterators are created from the `keyIterator()` method of your\nhashtable object, while value iterators are created from the `valueIterator()` method.\nAll you have to do is to unwrap the value from the `next()` method and deference it\ndirectly to access the key or the value that you are iterating over.\nThe code example below demonstrates the use of a key iterator,\nbut you can replicate the same logic to a value iterator.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar kit = hash_table.keyIterator();\nwhile (kit.next()) |key| {\n    std.debug.print(\"Key: {d}\\n\", .{key.*});\n}\n```\n:::\n\n\n```\nKey: 54321\nKey: 50050\nKey: 57709\n```\n\n\n### The `ArrayHashMap` hashtable {#sec-array-map}\n\nIf you need to iterate through the elements of your hashtable constantly,\nyou might want to use the `ArrayHashMap` struct for your specific case,\ninstead of going with the usual and general-purpose `HashMap` struct.\n\nThe `ArrayHashMap` struct creates a hashtable that is faster to iterate over.\nThat is why this specific type of hashtable might be valuable to you.\nSome other properties of a `ArrayHashMap` hashtable are:\n\n- the order of insertion is preserved, i.e., the order of the values that you find while iterating through this hashtable is actually the order in which these values were inserted in the hashtable.\n- the key-value pairs are stored sequentially, one after another.\n\n\nYou can create an `ArrayHashMap` object by using, once again, a helper function that\nchooses automatically for you a hash function implementation. This is the\n`AutoArrayHashMap()` function, which works very similarly to the `AutoHashMap()`\nfunction that we presented in @sec-hashmap.\n\nYou provide two data types to this function. The data type of the keys that will be\nused in this hashtable, and the data type of the values that will be stored in\nthis hashtable.\n\nAn `ArrayHashMap` object have essentially the exact same methods from the `HashMap` struct.\nSo you can insert new values into the hashtable by using the `put()` method, and you can look (or get)\na value from the hashtable by using the `get()` method. But the `remove()` method is not available\nin this specific type of hashtable.\n\nIn order to delete values from the hashtable, you would use the same methods that you find in\nan `ArrayList` object, i.e., a dynamic array. I presented these methods in @sec-dynamic-array-remove,\nwhich are the `swapRemove()` and `orderedRemove()` methods. These methods have the same meaning here, or,\nthe same effect that they have in an `ArrayList` object.\n\nThis means that, with `swapRemove()` you remove the value from the hashtable, but you do not preserve\nthe order in which the values were inserted into the structure. While `orderedRemove()` is able\nto retain the order in which these values were inserted.\n\nBut instead of providing an index as input to `swapRemove()` or `orderedRemove()`, like I described\nin @sec-dynamic-array-remove, these methods here in an `ArrayHashMap` take a key as input, like\nthe `remove()` method from a `HashMap` object. If you want to provide an index as input, instead\nof a key, you should use the `swapRemoveAt()` and `orderedRemoveAt()` methods.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar hash_table = AutoArrayHashMap(u32, u16)\n    .init(allocator);\ndefer hash_table.deinit();\n```\n:::\n\n\n\n\n### The `StringHashMap` hashtable {#sec-string-hash-map}\n\nOne thing that you will notice in the other two types of hashtables that I have\npresented over the last sections, is that neither of them accepts a slice data type\nin their keys.\nWhat this means is that you cannot use a slice value to represent a key in\nthese types of hashtable.\n\nThe most obvious consequence of this, is that you cannot use strings as keys\nin these hashtables. But it's extremely common to use strings as keys\nin hashtables.\n\nTake this very simple Javascript code snippet as an example. We are creating\na simple hashtable object named `people`. Then, we add a new entry to this\nhashtable, which is identified by the string `'Pedro'`. This string is the\nkey in this case, while the object containing different personal information such as\nage, height and city, is the value to be stored in the hashtable.\n\n```js\nvar people = new Object();\npeople['Pedro'] = {\n    'age': 25,\n    'height': 1.67,\n    'city': 'Belo Horizonte'\n};\n```\n\nThis pattern of using strings as keys is very common in\nall sorts of situations. That is why the Zig Standard Library offers a\nspecific type of hashtable for this purpose, which is created through the `StringHashMap()` function.\nThis function creates a hashtable that uses strings as keys. The only input of this\nfunction is the data type of the values that will be stored into this hashtable.\n\nIn the example below, I'm creating a hashtable to store the ages of different people.\nEach key in this hashtable is represented by the name of each person, while the value stored in the\nhashtable is the age of this person identified by the key.\n\nThat is why I provide the `u8` data type (which is the data type used by the age values) as input to this `StringHashMap()` function.\nAs the result, it creates a hashtable that uses string values as keys, and, that stores\n`u8` values in it. Notice that an allocator object is provided at the `init()` method of the\nresulting object from the `StringHashMap()` function.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var ages = std.StringHashMap(u8).init(allocator);\n    defer ages.deinit();\n\n    try ages.put(\"Pedro\", 25);\n    try ages.put(\"Matheus\", 21);\n    try ages.put(\"Abgail\", 42);\n\n    var it = ages.iterator();\n    while (it.next()) |kv| {\n        std.debug.print(\"Key: {s} | \", .{kv.key_ptr.*});\n        std.debug.print(\"Age: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n:::\n\n\n```\nKey: Pedro | Age: 25\nKey: Abgail | Age: 42\nKey: Matheus | Age: 21\n```\n\n\n### The `StringArrayHashMap` hashtable\n\nThe Zig Standard Library also provides a type of hashtable that mix the cons and pros of the\n`StringHashMap` and `ArrayHashMap` together. That is, a hashtable\nthat uses strings as keys, but also have the advantages from `ArrayHashMap`.\nIn other words, you can have a hashtable that is fast to iterate over,\nthat preserves insertion order, and also, that uses strings as keys.\n\nYou can create such type of hashtable by using the `StringArrayHashMap()` function.\nThis function accepts a data type as input, which is the data type of the values that are\ngoing to be stored inside this hashtable, in the same style as the function presented\nin @sec-string-hash-map.\n\nYou can insert new values into this hashtable by using the same `put()` method that\nwe have discussed in @sec-string-hash-map. And you can also get values from the hashtable\nby using the same `get()` method.\nLike its `ArrayHashMap` brother, to delete values from this specific type of hashtable,\nwe also use the `orderedRemove()` and `swapRemove()` methods, with the same effects that\nI have described in @sec-array-map.\n\nIf we take the code example that was exposed in @sec-string-hash-map, we can\nachieve the exact same result with `StringArrayHashMap()`:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar ages = std.StringArrayHashMap(u8).init(allocator);\n```\n:::\n\n\n\n\n\n## Linked lists\n\nThe Zig Standard Library provides an implementation for both singly and doubly linked lists.\nMore specifically, through the structs `SinglyLinkedList` and `DoublyLinkedList`.\n\nIn case you are not familiar with these data structures, a linked list is a linear data structure that looks\nlike a chain, or, a rope. The main advantage of this data structure is that you normally have very fast\ninsertion and deletion operations. But, as a disadvantage, iterating through\nthis data structure is usually not so fast as iterating through an array.\n\nThe idea behind a linked list is to build a structure that consists of a sequence of nodes\nconnected to each other by pointers. This means that linked lists are usually not contiguous\nin memory, because each node might be anywhere in memory. They do not need to be close to\none another.\n\nIn @fig-linked-list we can see a diagram of a singly linked list. We begin at the first node\n(which is usually called \"the head of the linked list\"). Then, from this\nfirst node we uncover the remaining nodes in the structure, by following the locations pointed\nby the pointers found in each node.\n\nEach node has two things in it. It has the value that is stored in the current node\n, and also, a pointer. This pointer points to the next node in the list. If this pointer\nis null, then, it means that we have reached the end of our linked list.\n\n![A diagram of a singly linked list.](./../Figures/linked-list.png){#fig-linked-list}\n\n\nIn @fig-linked-list2 we can see a diagram of a doubly linked list. The only thing that really\nchanges now is that every node in the linked list has both a pointer to the previous node,\nand, a pointer to the next node. So every node in a doubly linked list has two pointers in it. These are\nusually called the `prev` (for \"previous\") and the `next` (for \"next\") pointers of the node.\n\nIn the singly linked list example, we had only one single pointer in each node, and this singular\npointer was always pointing to the next node in the sequence. This means that singly linked lists\nnormally have only the `next` pointer in them.\n\n![A diagram of a doubly linked list.](./../Figures/doubly-linked-list.png){#fig-linked-list2}\n\n\n\n### Recent change in the API\n\nOn previous versions of Zig, the `SinglyLinkedList` and `DoublyLinkedList` structs were initially implemented as \"generics data structures\".\nMeaning that, you would use a generic function to create a singly (or doubly) linked list that could store\nthe specific data type that you wanted to use. We will learn more about generics at @sec-generics, and also,\nhow we can create a \"generic data structure\" at @sec-generic-struct.\n\nHowever, on the latest versions of Zig, the structs `SinglyLinkedList` and `DoublyLinkedList` were altered to use a\n\"less generic API\". This specific change was introduced on April 3, 2025. Therefore, check if your Zig version is one released after this\ndate. Just have in mind that if you don't have a very recent version of the Zig compiler,\nyou might have problems while trying to compile the next examples exposed here.\n\n\n\n### How to use a singly linked list\n\nFor example, consider that you are creating a singly linked list that is going to store `u32` values.\nGiven this scenario, the first thing that we need to do, is to create a \"node type\" that is capable\nof storing a `u32` value. The `NodeU32` type exposed below demonstrates such \"node type\".\n\nNotice that the data type associated with the member named `data` is the most important part of this\ncustom \"node type\". It determines the data type that is going to be stored in each node.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst NodeU32 = struct {\n    data: u32,\n    node: std.SinglyLinkedList.Node = .{},\n};\n```\n:::\n\n\nAfter we created our custom \"node type\" that can store the specific data type that we\nwant, we can just create a new and empty singly linked list, which will store our nodes.\nTo do that, we just create a new object with the type `SinglyLinkedList`, like this:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar list: std.SinglyLinkedList = .{};\n```\n:::\n\n\nNow, we have our linked list... But how can we insert nodes in it? Well, first of all,\nwe need to create our nodes. So let's focus on that first. The snippet exposed below demonstrates\nhow we could use our `NodeU32` struct to create such nodes.\n\nNotice in this snippet that we are just setting the `data` member of the struct for now.\nWe don't need to connect these nodes together in this first instance. This is why we ignore\nthe `node` member at first. But we are going to connect these nodes in a future point of the code, which is\nwhy these objects are marked as \"variable objects\", so that we can alter them in the future.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n```\n:::\n\n\nNow that we have both the linked list and also the nodes created, we can start to connect them together.\nYou can use the `prepend()` method from the linked list object to insert the first node in the list, which\nis the \"head\" of the linked list. As the name suggests, this specific method prepends the input node to the linked list,\nor, in other words, it transforms the input node into the first node of the list.\n\nAfter we added the \"head node\" of the list, we can start to add the \"next nodes\" in the list by using the `insertAfter()` method\nfrom the `SinglyLinkedList.Node` type, which, in our case here, is accessible through the `node` member of our\n`NodeU32` type. Thus, we can start to create the connections between the nodes by calling this method from the node objects\nthat are present in the list. Like in this example below:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nlist.prepend(&two.node); // {2}\ntwo.node.insertAfter(&five.node); // {2, 5}\ntwo.node.insertAfter(&three.node); // {2, 3, 5}\n```\n:::\n\n\nYou can also call the `prepend()` method again to add new nodes to the beginning of the linked list, which\nmeans, effectively, changing the \"head node\" of the list, like this:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nlist.prepend(&one.node); // {1, 2, 3, 5}\n```\n:::\n\n\n\nThere are other methods available from the singly linked list object that you might be interested. You can find a\nsummary of them in the bullet points below:\n\n- `remove()` to remove a specific node from the linked list.\n- `len()` to count how many nodes there is in the linked list.\n- `popFirst()` to remove the first node (i.e., the \"head\") from the linked list.\n\nSo, that is how singly linked lists work in Zig in a nutshell. To sum up,\nthis is all the source code that was exposed in this section inside the single cell:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst NodeU32 = struct {\n    data: u32,\n    node: std.SinglyLinkedList.Node = .{},\n};\n\nvar list: std.SinglyLinkedList = .{};\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nlist.prepend(&two.node); // {2}\ntwo.node.insertAfter(&five.node); // {2, 5}\ntwo.node.insertAfter(&three.node); // {2, 3, 5}\nlist.prepend(&one.node); // {1, 2, 3, 5}\n\ntry stdout.print(\"Number of nodes: {}\", .{list.len()});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nNumber of nodes: 4\n```\n\n\n:::\n:::\n\n\n\n### How to use a doubly linked list\n\nIf you want to use a doubly linked list instead, you will face a similar workflow compared to the\nsingly linked list:\n\n1. You first create a \"custom node type\" that can store the specific data type that you want.\n2. Create an empty doubly linked list object.\n3. Create the nodes of linked list.\n4. Start to insert the nodes inside the list.\n\nIn your \"custom node type\", you should use the `DoublyLinkedList.Node` type to denote\nthe `node` member of the struct. The snippet below demonstrates that. Here we are creating,\nonce again, a node type that can store `u32` values. But this time, this struct is tailored\nto be used inside a `DoublyLinkedList` struct.\n\nAfter this step, the way that you create the new empty linked list, and the nodes that you want insert,\nis practically identical to the singly linked list case. But, things are different when you start to add nodes\nto the list. Instead of using the `prepend()` method of the list object, you should use the `append()` method\nto add the nodes to the linked list.\n\nThis `append()` method from the linked list object will always append the input node to the end of the\nlinked list. However, in case you want to add the new node into a different position of the list, then,\nyou should take a look at the `insertAfter()` and `insertBefore()` methods of the linked list object.\nThese methods allow you to insert the new node either after or before an existing node in the list.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst NodeU32 = struct {\n    data: u32,\n    node: std.DoublyLinkedList.Node = .{},\n};\n\nvar list: std.DoublyLinkedList = .{};\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nlist.append(&one.node); // {1}\nlist.append(&three.node); // {1, 3}\nlist.insertAfter(\n    &one.node,\n    &five.node\n); // {1, 5, 3}\nlist.append(&two.node); // {1, 5, 3, 2}\n\ntry stdout.print(\"Number of nodes: {}\", .{list.len()});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nNumber of nodes: 4\n```\n\n\n:::\n:::\n\n\nThese are other methods from the `DoublyLinkedList` object that might interest you:\n\n- `remove()`: to remove a specific node from the list.\n- `len()`: to count the number of nodes in the list.\n- `prepend()`: to add a node to the beginning of the list (i.e. set the head node of the list).\n- `pop()`: to remove the last node of the list.\n- `popFirst()`: to remove the first node of the list.\n- `concatByMoving()`: to concat two doubly linked lists together.\n\n\n\n\n\n## Multi array structure\n\nZig introduces a new data structure called `MultiArrayList()`. It's a different version of the dynamic array\nthat we have introduced in @sec-dynamic-array. The difference between this structure and the `ArrayList()`\nthat we know from @sec-dynamic-array, is that `MultiArrayList()` creates a separate dynamic array\nfor each field of the struct that you provide as input.\n\nConsider the following code example. We create a new custom struct called `Person`. This\nstruct contains three different data members, or, three different fields. As consequence,\nwhen we provide this `Person` data type as input to `MultiArrayList()`, this\ncreates a \"struct of three different arrays\" called `PersonArray`. In other words,\nthis `PersonArray` is a struct that contains three internal dynamic arrays in it.\nOne array for each field found in the `Person` struct definition.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Person = struct {\n    name: []const u8,\n    age: u8,\n    height: f32,\n};\nconst PersonArray = std.MultiArrayList(Person);\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var people = PersonArray{};\n    defer people.deinit(allocator);\n\n    try people.append(allocator, .{\n        .name = \"Auguste\", .age = 15, .height = 1.54\n    });\n    try people.append(allocator, .{\n        .name = \"Elena\", .age = 26, .height = 1.65\n    });\n    try people.append(allocator, .{\n        .name = \"Michael\", .age = 64, .height = 1.87\n    });\n}\n```\n:::\n\n\nIn other words, instead of creating an array of \"persons\", the `MultiArrayList()` function\ncreates a \"struct of arrays\". Each data member of this struct is a different array that stores\nthe values of a specific field from the `Person` values that were added (or, appended) to this \"struct of arrays\".\nOne important detail is that each of these separate internal arrays stored inside `PersonArray`\nare dynamic arrays. This means that these arrays can grow in capacity automatically as needed, to accomodate\nmore values.\n\nThe @fig-multi-array exposed below presents a diagram that describes the `PersonArray` struct\nthat we have created in the previous code example. Notice that the values of the data members\npresent in each of the three `Person` values that we have appended into the `PersonArray` object\n, are scattered across three different internal arrays of the `PersonArray` object.\n\n![A diagram of the `PersonArray` struct.](./../Figures/multi-array.png){#fig-multi-array}\n\nYou can easily access each of these arrays separately, and iterate over the values of each array.\nFor that, you will need to call the `items()` method from the `PersonArray` object, and provide as input\nto this method, the name of the field that you want to iterate over.\nIf you want to iterate through the `.age` array for example, then, you need to call `items(.age)` from\nthe `PersonArray` object, like in the example below:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (people.items(.age)) |*age| {\n    try stdout.print(\"Age: {d}\\n\", .{age.*});\n}\n```\n:::\n\n\n```\nAge: 15\nAge: 26\nAge: 64\n```\n\n\nIn the above example, we are iterating over the values of the `.age` array, or,\nthe internal array of the `PersonArray` object that contains the values of the `age`\ndata member from the `Person` values that were added to the multi array struct.\n\nIn this example we are calling the `items()` method directly from the `PersonArray`\nobject. However, in most situations it's recommened to call this `items()` method\nfrom a \"slice object\", which you can create from the `slice()` method.\nThe reason for this is that calling `items()` multiple times have better performance\nif you use a slice object.\n\nTherefore, if you are planning to access only one of the\ninternal arrays from your \"multi array struct\", it's fine to call `items()` directly\nfrom the multi array object. But if you need to access many of the internal arrays\nfrom your \"multi array struct\", then, you will likely need to call `items()` more\nthan once, and, in such circumstance, is better to call `items()` through a slice object.\nThe example below demonstrates the use of such object:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar slice = people.slice();\nfor (slice.items(.age)) |*age| {\n    age.* += 10;\n}\nfor (slice.items(.name), slice.items(.age)) |*n,*a| {\n    try stdout.print(\n        \"Name: {s}, Age: {d}\\n\", .{n.*, a.*}\n    );\n}\n```\n:::\n\n\n```\nName: Auguste, Age: 25\nName: Elena, Age: 36\nName: Michael, Age: 74\n```\n\n\n## Conclusion\n\nThere are many other data structures that I haven't presented here.\nBut you can check them out at the official Zig Standard Library documentation page.\nActually, when you get into the [homepage of the documentation](https://ziglang.org/documentation/master/std/#)[^home], the first thing\nthat appears to you in this page, is a list of types and data structures that\nare available in the Zig Standard Library.\nThere are some very specific data structures in this list, like a\n[`BoundedArray` struct](https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray)[^bounded]\n, but there is also some more general structures, such as a\n[`PriorityQueue` struct](https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue)[^priority].\n\n\n[^home]: <https://ziglang.org/documentation/master/std/#>\n[^priority]: <https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue>.\n[^bounded]: <https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray>\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Data Structures\n\nIn this chapter, I want to present the most common Data Structures that are available from\nthe Zig Standard Library, especially `ArrayList` and also `HashMap`. These are generic Data Structures\nthat you can use to store and control any type of data that is produced by your application.\n\n## Dynamic Arrays {#sec-dynamic-array}\n\nIn high level languages, arrays are usually dynamic. They can easily grow\nin size when they have to, and you don't need to worry about it.\nIn contrast, arrays in low level languages are usually static by default.\nThis is the reality of C, C++, Rust and also Zig. Static arrays were presented at\n@sec-arrays, but in this section, we are going to talk about dynamic arrays in Zig.\n\nDynamic arrays are simply arrays that can grow in size during the runtime\nof your program. Most low level languages have some implementation of\na dynamic array in their standard library. C++ have `std::vector`, Rust have `Vec`,\nand Zig have `std.ArrayList`.\n\nThe `std.ArrayList` struct provides a contiguous and growable array for you.\nIt works like any other dynamic array, it allocates a contiguous block of memory, and when this block have no space left,\n`ArrayList` allocates another contiguous and bigger block of memory, copies the\nelements to this new location, and erases (or frees) the previous block of memory.\n\n\n### Capacity vs Length\n\nWhen we talk about dynamic arrays, we usually have two similar concepts that\nare very essential to how a dynamic array works behind the hood.\nThese concepts are *capacity* and *length*. In some contexts, especially\nin C++, *length* is also called of *size*.\n\nAlthough they look similar, these concepts represent different things\nin the context of a dynamic array. *Capacity* is the number of items (or elements)\nthat your dynamic array can currently hold without the need to allocate more memory.\n\nIn contrast, the *length* refers to how many elements in the array\nare currently being used, or, in other words, how many elements in this array\nthat you have assigned a value to. Every dynamic array works around\na block of allocated memory, which represents an array with total capacity for $n$ elements.\nHowever, only a portion of these $n$ elements are being used most of the time. This portion\nof $n$ is the *length* of the array. So every time you append a new value\nto the array, you are incrementing its *length* by one.\n\nThis means that a dynamic array usually works with an extra margin, or an extra space\nthat is currently empty, but waiting and ready to be used. This \"extra space\"\nis essentially the difference between *capacity* and *length*. *Capacity* represents\nthe total number of elements that the array can hold without the need to re-allocate\nor re-expand the array, while the *length* represents how much of this capacity\nis currently being used to hold/store values.\n\n@fig-capacity-length presents this idea visually. Notice that, at first,\nthe capacity of the array is greater than the length of the array.\nSo, the dynamic array have extra space that is currently empty, but it\nis ready to receive a value to be stored.\n\n![Difference between capacity and length in a dynamic array](./../Figures/dynamic-array.png){#fig-capacity-length}\n\nWe can also see in @fig-capacity-length that, when *length* and *capacity* are equal, it means that the array have no space left.\nWe have reached the ceiling of our capacity, and because of that, if we want to store more values\nin this array, we need to expand it. We need to get a bigger space that can hold more values\nthan what we currently have.\n\nA dynamic array works by expanding the underlying array, whenever the *length* becomes equal\nto the *capacity* of the array. It basically allocates a new contiguous block of memory that is bigger\nthan the previous one, then, it copies all values that are currently being stored to this new\nlocation (i.e., this new block of memory), then, it frees the previous block of\nmemory. At the end of this process, the new underlying array have a bigger *capacity*, and, therefore,\nthe *length* becomes, once again, smaller than the *capacity* of the array.\n\nThis is the cycle of a dynamic array. Notice that, throughout this cycle, the *capacity* is always\neither equal to or higher than the *length* of the array. If you have an `ArrayList` object (let's suppose\nyou named it `buffer`), you can check the current capacity of your array by accessing the `capacity`\nattribute of your `ArrayList` object, while the current *length* of it is available at the `items.len`\nattribute.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// Check capacity\nbuffer.capacity;\n// Check length\nbuffer.items.len;\n```\n:::\n\n\n\n### Creating an `ArrayList` object\n\nIn order to use `ArrayList`, you must provide an allocator object to it.\nRemember, Zig does not have a default memory allocator. And as I described in @sec-allocators, all memory\nallocations must be done by an allocator object that you define, that\nyou have control over. In our example here, I'm going to use\na general purpose allocator, but you can use any other allocator\nof your preference.\n\nWhen you initialize an `ArrayList` object, you must provide the data type of the elements of\nthe array. In other words, this defines the type of data that this array (or container) will\nstore. Therefore, if I provide the `u8` type to it, then, I will create a dynamic\narray of `u8` values. However, if I provide a struct that I have defined instead, like the struct `User`\nfrom @sec-structs-and-oop, then, a dynamic array of `User` values\nwill be created. In the example below, with the expression `ArrayList(u8)` we\nare creating a dynamic array of `u8` values.\n\nAfter you provide the data type of the elements of the array, you can initialize\nan `ArrayList` object by either using the `init()` or the `initCapacity()` methods.\nThe former method receives only the allocator object\nas input, while the latter method receives both the allocator object and a capacity number as inputs.\nWith the latter method, you not only initialize the struct, but you\nalso set the starting capacity of the allocated array.\n\nUsing the `initCapacity()` method is the preferred way to initialize your dynamic array.\nBecause reallocations, or, in other words, the process of expanding the capacity of the array,\nis always a high cost operation. You should take any possible opportunity to avoid reallocations in\nyour array. If you know how much space your array needs to occupy at the beginning,\nyou should always use `initCapacity()` to create your dynamic array.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n```\n:::\n\n\n\nIn the example above, the `buffer` object starts as an array of 100 elements. If this\n`buffer` object needs to create more space to accomodate more elements during the runtime of your program, the `ArrayList`\ninternals will perform the necessary actions for you automatically.\nAlso notice the `deinit()` method being used to destroy the `buffer` object at the\nend of the current scope, by freeing all the memory that was allocated for the dynamic\narray stored in this `buffer` object.\n\n\n### Adding new elements to the array\n\nNow that we have created our dynamic array, we can start to use it. You can append (a.k.a \"add\")\nnew values to this array by using the `append()` method. This method works the same way\nas the `append()` method from a Python list, or, the `emplace_back()` method from `std::vector` of C++.\nYou provide a single value to this method, and the method appends this value to the array.\n\nYou can also use the `appendSlice()` method to append multiple values at once. You provide\na slice (slices were described in @sec-arrays) to this method, and the method adds all values present\nin this slice to your dynamic array.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry buffer.append('H');\ntry buffer.append('e');\ntry buffer.append('l');\ntry buffer.append('l');\ntry buffer.append('o');\ntry buffer.appendSlice(\" World!\");\n```\n:::\n\n\n### Removing elements from the array {#sec-dynamic-array-remove}\n\nYou can use the `pop()` method to \"pop\" or remove\nthe last element in the array. It's worth noting that this method\ndo not change the capacity of the array. It just deletes or erases\nthe last value stored in the array.\n\nAlso, this method returns as result the value that got deleted. That is, you can\nuse this method to both get the last value in the array, and also, remove\nit from the array. It's a \"get and remove value\" type of method.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exclamation_mark = buffer.pop();\n```\n:::\n\n\nNow, if you want to remove specific elements from specific positions\nof your array, you can use the `orderedRemove()` method from your\n`ArrayList` object. With this method, you can provide an index as input,\nthen, the method will delete the value that is at this index in the array.\nYou are effectively reducing the *length* of the array everytime you execute\nan `orderedRemove()` operation.\n\nIn the example below, we first create an `ArrayList` object, and we fill it\nwith numbers. Then, we use `orderedRemove()` to remove the value at\nindex 3 in the array, two consecutive times.\n\nAlso, notice that we are assigning the result of `orderedRemove()` to the\nunderscore character. So we are discarding the result value of this method.\nThe `orderedRemove()` method returns the value that got deleted, in a similar\nstyle to the `pop()` method.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n\nfor (0..10) |i| {\n    const index: u8 = @intCast(i);\n    try buffer.append(index);\n}\n\nstd.debug.print(\n    \"{any}\\n\", .{buffer.items}\n);\n_ = buffer.orderedRemove(3);\n_ = buffer.orderedRemove(3);\n\nstd.debug.print(\"{any}\\n\", .{buffer.items});\nstd.debug.print(\"{any}\\n\", .{buffer.items.len});\n```\n:::\n\n\n```\n{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }\n{ 0, 1, 2, 5, 6, 7, 8, 9 }\n8\n```\n\nOne key characteristic about `orderedRemove()` is that it preserves the order\nof the values in the array. So, it deletes the value that you asked it to\nremove, but it also makes sure that the order of the values that remain in the array\nstay the same as before.\n\nNow, if you don't care about the order of the values, for example, maybe you want to treat\nyour dynamic array as a set of values, like the `std::unordered_set`\nstructure from C++, you can use the `swapRemove()` method instead. This method\nworks similarly to the `orderedRemove()` method. You give an index to this\nmethod, then, it deletes the value that is at this index in the array.\nBut this method does not preserve the original order of the values that remain\nin the array. As a result, `swapRemove()` is, in general, faster than `orderedRemove()`.\n\n\n### Inserting elements at specific indexes\n\nWhen you need to insert values in the middle of your array,\ninstead of just appending them to the end of the array, you need to use\nthe `insert()` and `insertSlice()` methods, instead of\nthe `append()` and `appendSlice()` methods.\n\nThese two methods work very similarly to `insert()` and `insert_range()`\nfrom the C++ `std::vector` class. You provide an index to these methods,\nand they insert the values that you provide at that index in the array.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 10);\ndefer buffer.deinit();\n\ntry buffer.appendSlice(\"My Pedro\");\ntry buffer.insert(4, '3');\ntry buffer.insertSlice(2, \" name\");\nfor (buffer.items) |char| {\n    try stdout.print(\"{c}\", .{char});\n}\n```\n:::\n\n\n```\nMy name P3edro\n```\n\n\n### Conclusion\n\nIf you feel the lack of some other method, I recommend\nyou to read the [official documentation for the `ArrayListAligned`](https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned)[^zig-array2]\nstruct, which describes most of the methods available\nthrough the `ArrayList` object.\n\nYou will notice that there is a lot of other methods in this page that\nI did not described here, and I recommend you to explore these methods,\nand understand how they work.\n\n[^zig-array2]: <https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned>\n\n\n\n## Maps or HashTables {#sec-maps-hashtables}\n\nSome professionals know this type of data structure by different terms, like \"map\",\n\"hashmap\" or \"associative arrays\". But the most common term used is *hashtable*.\nEvery programming language normally have some implementation of a hashtable in their\nstandard libraries. Python have `dict()`, C++ have `std::map` and `std::unordered_map`, Rust\nhave `HashMap`, Javascript have `Object()` and `Map()`, etc.\n\n\n\n### What is a hashtable?\n\nA hashtable is a data structure based on key-value pairs.\nYou provide a key and a value to this structure, then, the hashtable will store\nthe input value at a location that can be identified by the input\nkey that you provided.\nIt does that by using an underlying array and a hash function.\nThese two components are essential to how a hashtable works.\n\nUnder the hood, the hashtable contains an array. This array is where the values\nare stored, and the elements of this array are usually called of *buckets*.\nSo the values that you provide to the hashtable are stored inside buckets,\nand you access each bucket by using an index.\n\nWhen you provide a key to a hashtable, it passes this key to the\nhash function. This hash function uses some sort of hashing algorithm to transform\nthis key into an index. This index is actually an array index. It's a position\nin the underlying array of the hashtable.\nThis is how a key identifies a specific position (or location) inside the hashtable\nstructure.\n\nTherefore, you provide a key to the hashtable, and this key identifies a specific location\ninside the hashtable, then, the hashtable takes the input value that you provided,\nand stores this value in the location identified by this input key.\nYou could say that the key maps to the value stored in the hashtable. You find\nthe value, by using the key that identifies the location where the value is stored.\nThe @fig-hashtable presents this process visually.\n\n\n![A diagram of a Hashtable. Source: Wikipedia, the free encyclopedia.](./../Figures/hashtable.svg){#fig-hashtable}\n\n\nThe operation described in the previous paragraph is normally called an *insertion* operation.\nBecause you are inserting new values into the hashtable.\nBut there are other types of operations in hashtables such as *delete* and *lookup*.\nDelete is self describing, it's when you delete (or remove) a value from the hashtable.\nWhile lookup corresponds to when you look at a value that is stored in\nthe hashtable, by using the key that identifies the location where this value is stored.\n\nSometimes, instead of storing the values directly, the underlying array of the hashtable might be an array of pointers,\ni.e., the buckets of the array stores pointers that points to the value,\nor also, may be an array of linked lists.\nThese cases are common on hashtables that allows duplicate keys, or, in other words,\non hashtables that effectively handle \"collisions\" that may arise from the hash function.\n\nDuplicate keys, or this \"collision\" thing that I'm talking about, is when you have two different keys\nthat points to the same location (i.e., to the same index)\nin the underlying array of the hashtable. This might happen depending on the characteristics of the hash function\nthat is being used in the hashtable. Some implementations of the hashtable will actively deal with collisions,\nmeaning that, they will handle this case in some way. For example, the hashtable\nmight transform all buckets into linked lists. Because with a linked list you can store\nmultiple values into a single bucket.\n\nThere are different techniques to handle collisions in hashtables, which I will not describe\nin this book, because it's not our main scope here. But you can find a good description of\nsome of the most common techniques at the Wikipedia page of hashtables [@wikipedia_hashtables].\n\n\n### Hashtables in Zig {#sec-hashmap}\n\nThe Zig Standard Library provides different implementations of a hashtable.\nEach implementation have its own cons and pros, which we will\ndiscuss later on, and all of them are available through the `std.hash_map` module.\n\nThe `HashMap` struct is a general-purpose hashtable,\nwhich have very fast operations (lookup, insertion, delete), and also,\nquite high load factors for low memory usage. You can create and provide a context object\nto the `HashMap` constructor. This context object allows you to tailor\nthe behaviour of the hashtable itself, because you can\nprovide a hash function implementation to be used by the hashtable\nthrough this context object.\n\nBut let's not worry about this context object now, because it's meant to be used\nby \"experts in the field of hashtables\". Since we are most likely not\nexperts in this field, we are going to take the easy way to create\na hashtable. Which is by using the `AutoHashMap()` function.\n\n\nThis `AutoHashMap()` function is essentially a \"create a hashtable object that uses the default settings\"\ntype of function. It automatically chooses a context object, and, therefore, a hash function implementation,\nfor you. This function receives two data types as input, the first input is the data type of the keys\nthat will be used in this hashtable, while the second input is the data type of the data that will be\nstored inside the hashtable, that is, the data type of the values to be stored.\n\nIn the example below, we are providing the data type `u32` in the first argument, and `u16` in the second argument of this\nfunction. This means that we are going to use `u32` values as keys in this hashtable, while `u16` values are the actual values\nthat are going to be stored into this hashtable.\nAt the end of this process, the `hash_table` object contains a `HashMap` object\nthat uses the default settings and context.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n    std.debug.print(\n        \"Value at key 50050: {d}\\n\",\n        .{hash_table.get(50050).?}\n    );\n\n    if (hash_table.remove(57709)) {\n        std.debug.print(\n            \"Value at key 57709 successfully removed!\\n\",\n            .{}\n        );\n    }\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n}\n```\n:::\n\n\n```\nN of values stored: 3\nValue at key 50050: 55\nValue at key 57709 successfully removed!\nN of values stored: 2\n```\n\nYou can add/put new values into the hashtable by using the `put()` method. The first argument\nis the key to be used, and the second argument is the actual value that you want to store inside\nthe hashtable. In the example below, we first add the value 89 using the key 54321, next, we add\nthe value 55 using the key 50050, etc.\n\nNotice that we have used the method `count()` to see how many values are currently stored in the\nhashtable. After that, we also use the `get()` method to access (or look) at the value stored in\nthe position identified by the key 500050. The output of this `get()` method is an optional value.\nThis is why we use the `?` method at the end to get the actual value.\n\nAlso notice that we can remove (or delete) values from the hashtable by using the `remove()` method.\nYou provide the key that identifies the value that you want to delete, then, the method will\ndelete this value and return a `true` value as output. This `true` value essentially tells us\nthat the method successfully deleted the value.\n\nBut this delete operation might not be always successful. For example, you might provide the wrong\nkey to this method. I mean, maybe you provide\n(either intentionally or unintentionally) a key that points to an empty bucket,\ni.e., a bucket that still doesn't have a value in it.\nIn this case, the `remove()` method would return a `false` value.\n\n\n\n### Iterating through the hashtable\n\nIterating through the keys and values that are currently being stored in\nthe hashtable is a very common necessity.\nYou can do that in Zig by using an iterator object that can iterate\nthrough the elements of your hashtable object.\n\nThis iterator object works like any other iterator object that you would\nfind in languages such as C++ and Rust. It's basically a pointer object\nthat points to some value in the container, and has a `next()` method\nthat you can use to navigate (or iterate) through the values in the\ncontainer.\n\nYou can create such iterator object by using the `iterator()` method of the hashtable object.\nThis method returns an iterator object, from which you can use the `next()` method in conjunction\nwith a while loop to iterate through the elements of your hashtable. The `next()` method returns an optional\n`Entry` value, and therefore, you must unwrap this optional value to get the actual `Entry` value\nfrom which you can access the key and also the value identified by this key.\n\nWith this `Entry` value at hand, you can access the key of this current entry by using the `key_ptr`\nattribute and dereferencing the pointer that lives inside of it, while the value identified by this\nkey is accessed through the `value_ptr` attribute instead, which is also a pointer to be dereferenced.\nThe code example below demonstrates the use of these elements:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n\n    var it = hash_table.iterator();\n    while (it.next()) |kv| {\n        // Access the current key\n        std.debug.print(\"Key: {d} | \", .{kv.key_ptr.*});\n        // Access the current value\n        std.debug.print(\"Value: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n:::\n\n\n```\nKey: 54321 | Value: 89\nKey: 50050 | Value: 55\nKey: 57709 | Value: 41\n```\n\n\nIf you want to iterate specifically through the values or the keys of your hashtable,\nyou can create a key iterator or a value iterator object. These are also iterator\nobjects, which have the same `next()` method that you can use to iterate through the\nhashtable.\n\nKey iterators are created from the `keyIterator()` method of your\nhashtable object, while value iterators are created from the `valueIterator()` method.\nAll you have to do is to unwrap the value from the `next()` method and deference it\ndirectly to access the key or the value that you are iterating over.\nThe code example below demonstrates the use of a key iterator,\nbut you can replicate the same logic to a value iterator.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar kit = hash_table.keyIterator();\nwhile (kit.next()) |key| {\n    std.debug.print(\"Key: {d}\\n\", .{key.*});\n}\n```\n:::\n\n\n```\nKey: 54321\nKey: 50050\nKey: 57709\n```\n\n\n### The `ArrayHashMap` hashtable {#sec-array-map}\n\nIf you need to iterate through the elements of your hashtable constantly,\nyou might want to use the `ArrayHashMap` struct for your specific case,\ninstead of going with the usual and general-purpose `HashMap` struct.\n\nThe `ArrayHashMap` struct creates a hashtable that is faster to iterate over.\nThat is why this specific type of hashtable might be valuable to you.\nSome other properties of a `ArrayHashMap` hashtable are:\n\n- the order of insertion is preserved, i.e., the order of the values that you find while iterating through this hashtable is actually the order in which these values were inserted in the hashtable.\n- the key-value pairs are stored sequentially, one after another.\n\n\nYou can create an `ArrayHashMap` object by using, once again, a helper function that\nchooses automatically for you a hash function implementation. This is the\n`AutoArrayHashMap()` function, which works very similarly to the `AutoHashMap()`\nfunction that we presented in @sec-hashmap.\n\nYou provide two data types to this function. The data type of the keys that will be\nused in this hashtable, and the data type of the values that will be stored in\nthis hashtable.\n\nAn `ArrayHashMap` object have essentially the exact same methods from the `HashMap` struct.\nSo you can insert new values into the hashtable by using the `put()` method, and you can look (or get)\na value from the hashtable by using the `get()` method. But the `remove()` method is not available\nin this specific type of hashtable.\n\nIn order to delete values from the hashtable, you would use the same methods that you find in\nan `ArrayList` object, i.e., a dynamic array. I presented these methods in @sec-dynamic-array-remove,\nwhich are the `swapRemove()` and `orderedRemove()` methods. These methods have the same meaning here, or,\nthe same effect that they have in an `ArrayList` object.\n\nThis means that, with `swapRemove()` you remove the value from the hashtable, but you do not preserve\nthe order in which the values were inserted into the structure. While `orderedRemove()` is able\nto retain the order in which these values were inserted.\n\nBut instead of providing an index as input to `swapRemove()` or `orderedRemove()`, like I described\nin @sec-dynamic-array-remove, these methods here in an `ArrayHashMap` take a key as input, like\nthe `remove()` method from a `HashMap` object. If you want to provide an index as input, instead\nof a key, you should use the `swapRemoveAt()` and `orderedRemoveAt()` methods.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar hash_table = AutoArrayHashMap(u32, u16)\n    .init(allocator);\ndefer hash_table.deinit();\n```\n:::\n\n\n\n\n### The `StringHashMap` hashtable {#sec-string-hash-map}\n\nOne thing that you will notice in the other two types of hashtables that I have\npresented over the last sections, is that neither of them accepts a slice data type\nin their keys.\nWhat this means is that you cannot use a slice value to represent a key in\nthese types of hashtable.\n\nThe most obvious consequence of this, is that you cannot use strings as keys\nin these hashtables. But it's extremely common to use strings as keys\nin hashtables.\n\nTake this very simple Javascript code snippet as an example. We are creating\na simple hashtable object named `people`. Then, we add a new entry to this\nhashtable, which is identified by the string `'Pedro'`. This string is the\nkey in this case, while the object containing different personal information such as\nage, height and city, is the value to be stored in the hashtable.\n\n```js\nvar people = new Object();\npeople['Pedro'] = {\n    'age': 25,\n    'height': 1.67,\n    'city': 'Belo Horizonte'\n};\n```\n\nThis pattern of using strings as keys is very common in\nall sorts of situations. That is why the Zig Standard Library offers a\nspecific type of hashtable for this purpose, which is created through the `StringHashMap()` function.\nThis function creates a hashtable that uses strings as keys. The only input of this\nfunction is the data type of the values that will be stored into this hashtable.\n\nIn the example below, I'm creating a hashtable to store the ages of different people.\nEach key in this hashtable is represented by the name of each person, while the value stored in the\nhashtable is the age of this person identified by the key.\n\nThat is why I provide the `u8` data type (which is the data type used by the age values) as input to this `StringHashMap()` function.\nAs the result, it creates a hashtable that uses string values as keys, and, that stores\n`u8` values in it. Notice that an allocator object is provided at the `init()` method of the\nresulting object from the `StringHashMap()` function.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var ages = std.StringHashMap(u8).init(allocator);\n    defer ages.deinit();\n\n    try ages.put(\"Pedro\", 25);\n    try ages.put(\"Matheus\", 21);\n    try ages.put(\"Abgail\", 42);\n\n    var it = ages.iterator();\n    while (it.next()) |kv| {\n        std.debug.print(\"Key: {s} | \", .{kv.key_ptr.*});\n        std.debug.print(\"Age: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n:::\n\n\n```\nKey: Pedro | Age: 25\nKey: Abgail | Age: 42\nKey: Matheus | Age: 21\n```\n\n\n### The `StringArrayHashMap` hashtable\n\nThe Zig Standard Library also provides a type of hashtable that mix the cons and pros of the\n`StringHashMap` and `ArrayHashMap` together. That is, a hashtable\nthat uses strings as keys, but also have the advantages from `ArrayHashMap`.\nIn other words, you can have a hashtable that is fast to iterate over,\nthat preserves insertion order, and also, that uses strings as keys.\n\nYou can create such type of hashtable by using the `StringArrayHashMap()` function.\nThis function accepts a data type as input, which is the data type of the values that are\ngoing to be stored inside this hashtable, in the same style as the function presented\nin @sec-string-hash-map.\n\nYou can insert new values into this hashtable by using the same `put()` method that\nwe have discussed in @sec-string-hash-map. And you can also get values from the hashtable\nby using the same `get()` method.\nLike its `ArrayHashMap` brother, to delete values from this specific type of hashtable,\nwe also use the `orderedRemove()` and `swapRemove()` methods, with the same effects that\nI have described in @sec-array-map.\n\nIf we take the code example that was exposed in @sec-string-hash-map, we can\nachieve the exact same result with `StringArrayHashMap()`:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar ages = std.StringArrayHashMap(u8).init(allocator);\n```\n:::\n\n\n\n\n\n## Linked lists\n\nThe Zig Standard Library provides an implementation for both singly and doubly linked lists.\nMore specifically, through the structs `SinglyLinkedList` and `DoublyLinkedList`.\n\nIn case you are not familiar with these data structures, a linked list is a linear data structure that looks\nlike a chain, or, a rope. The main advantage of this data structure is that you normally have very fast\ninsertion and deletion operations. But, as a disadvantage, iterating through\nthis data structure is usually not so fast as iterating through an array.\n\nThe idea behind a linked list is to build a structure that consists of a sequence of nodes\nconnected to each other by pointers. This means that linked lists are usually not contiguous\nin memory, because each node might be anywhere in memory. They do not need to be close to\none another.\n\nIn @fig-linked-list we can see a diagram of a singly linked list. We begin at the first node\n(which is usually called \"the head of the linked list\"). Then, from this\nfirst node we uncover the remaining nodes in the structure, by following the locations pointed\nby the pointers found in each node.\n\nEach node has two things in it. It has the value that is stored in the current node\n, and also, a pointer. This pointer points to the next node in the list. If this pointer\nis null, then, it means that we have reached the end of our linked list.\n\n![A diagram of a singly linked list.](./../Figures/linked-list.png){#fig-linked-list}\n\n\nIn @fig-linked-list2 we can see a diagram of a doubly linked list. The only thing that really\nchanges now is that every node in the linked list has both a pointer to the previous node,\nand, a pointer to the next node. So every node in a doubly linked list has two pointers in it. These are\nusually called the `prev` (for \"previous\") and the `next` (for \"next\") pointers of the node.\n\nIn the singly linked list example, we had only one single pointer in each node, and this singular\npointer was always pointing to the next node in the sequence. This means that singly linked lists\nnormally have only the `next` pointer in them.\n\n![A diagram of a doubly linked list.](./../Figures/doubly-linked-list.png){#fig-linked-list2}\n\n\n\n### Recent change in the API\n\nOn previous versions of Zig, the `SinglyLinkedList` and `DoublyLinkedList` structs were initially implemented as \"generics data structures\".\nMeaning that, you would use a generic function to create a singly (or doubly) linked list that could store\nthe specific data type that you wanted to use. We will learn more about generics at @sec-generics, and also,\nhow we can create a \"generic data structure\" at @sec-generic-struct.\n\nHowever, on the latest versions of Zig, the structs `SinglyLinkedList` and `DoublyLinkedList` were altered to use a\n\"less generic API\". This specific change was introduced on April 3, 2025. Therefore, check if your Zig version is one released after this\ndate. Just have in mind that if you don't have a very recent version of the Zig compiler,\nyou might have problems while trying to compile the next examples exposed here.\n\n\n\n### How to use a singly linked list\n\nFor example, consider that you are creating a singly linked list that is going to store `u32` values.\nGiven this scenario, the first thing that we need to do, is to create a \"node type\" that is capable\nof storing a `u32` value. The `NodeU32` type exposed below demonstrates such \"node type\".\n\nNotice that the data type associated with the member named `data` is the most important part of this\ncustom \"node type\". It determines the data type that is going to be stored in each node.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst NodeU32 = struct {\n    data: u32,\n    node: std.SinglyLinkedList.Node = .{},\n};\n```\n:::\n\n\nAfter we created our custom \"node type\" that can store the specific data type that we\nwant, we can just create a new and empty singly linked list, which will store our nodes.\nTo do that, we just create a new object with the type `SinglyLinkedList`, like this:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar list: std.SinglyLinkedList = .{};\n```\n:::\n\n\nNow, we have our linked list... But how can we insert nodes in it? Well, first of all,\nwe need to create our nodes. So let's focus on that first. The snippet exposed below demonstrates\nhow we could use our `NodeU32` struct to create such nodes.\n\nNotice in this snippet that we are just setting the `data` member of the struct for now.\nWe don't need to connect these nodes together in this first instance. This is why we ignore\nthe `node` member at first. But we are going to connect these nodes in a future point of the code, which is\nwhy these objects are marked as \"variable objects\", so that we can alter them in the future.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n```\n:::\n\n\nNow that we have both the linked list and also the nodes created, we can start to connect them together.\nYou can use the `prepend()` method from the linked list object to insert the first node in the list, which\nis the \"head\" of the linked list. As the name suggests, this specific method prepends the input node to the linked list,\nor, in other words, it transforms the input node into the first node of the list.\n\nAfter we added the \"head node\" of the list, we can start to add the \"next nodes\" in the list by using the `insertAfter()` method\nfrom the `SinglyLinkedList.Node` type, which, in our case here, is accessible through the `node` member of our\n`NodeU32` type. Thus, we can start to create the connections between the nodes by calling this method from the node objects\nthat are present in the list. Like in this example below:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nlist.prepend(&two.node); // {2}\ntwo.node.insertAfter(&five.node); // {2, 5}\ntwo.node.insertAfter(&three.node); // {2, 3, 5}\n```\n:::\n\n\nYou can also call the `prepend()` method again to add new nodes to the beginning of the linked list, which\nmeans, effectively, changing the \"head node\" of the list, like this:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nlist.prepend(&one.node); // {1, 2, 3, 5}\n```\n:::\n\n\n\nThere are other methods available from the singly linked list object that you might be interested. You can find a\nsummary of them in the bullet points below:\n\n- `remove()` to remove a specific node from the linked list.\n- `len()` to count how many nodes there is in the linked list.\n- `popFirst()` to remove the first node (i.e., the \"head\") from the linked list.\n\nSo, that is how singly linked lists work in Zig in a nutshell. To sum up,\nthis is all the source code that was exposed in this section inside the single cell:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst NodeU32 = struct {\n    data: u32,\n    node: std.SinglyLinkedList.Node = .{},\n};\n\nvar list: std.SinglyLinkedList = .{};\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nlist.prepend(&two.node); // {2}\ntwo.node.insertAfter(&five.node); // {2, 5}\ntwo.node.insertAfter(&three.node); // {2, 3, 5}\nlist.prepend(&one.node); // {1, 2, 3, 5}\n\ntry stdout.print(\"Number of nodes: {}\", .{list.len()});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nNumber of nodes: 4\n```\n\n\n:::\n:::\n\n\n\n### How to use a doubly linked list\n\nIf you want to use a doubly linked list instead, you will face a similar workflow compared to the\nsingly linked list:\n\n1. You first create a \"custom node type\" that can store the specific data type that you want.\n2. Create an empty doubly linked list object.\n3. Create the nodes of linked list.\n4. Start to insert the nodes inside the list.\n\nIn your \"custom node type\", you should use the `DoublyLinkedList.Node` type to denote\nthe `node` member of the struct. The snippet below demonstrates that. Here we are creating,\nonce again, a node type that can store `u32` values. But this time, this struct is tailored\nto be used inside a `DoublyLinkedList` struct.\n\nAfter this step, the way that you create the new empty linked list, and the nodes that you want insert,\nis practically identical to the singly linked list case. But, this time,\nwe normally use the `append()` method from the linked list object to add new nodes to the list.\n\nThis `append()` method from the linked list object will always append the input node to the end of the\nlinked list. However, in case you want to add the new node into a different position of the list, then,\nyou should take a look at the `insertAfter()` and `insertBefore()` methods of the linked list object.\nThese methods allow you to insert the new node either after or before an existing node in the list.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst NodeU32 = struct {\n    data: u32,\n    node: std.DoublyLinkedList.Node = .{},\n};\n\nvar list: std.DoublyLinkedList = .{};\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nlist.append(&one.node); // {1}\nlist.append(&three.node); // {1, 3}\nlist.insertAfter(\n    &one.node,\n    &five.node\n); // {1, 5, 3}\nlist.append(&two.node); // {1, 5, 3, 2}\n\ntry stdout.print(\"Number of nodes: {}\", .{list.len()});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nNumber of nodes: 4\n```\n\n\n:::\n:::\n\n\nThese are other methods from the `DoublyLinkedList` object that might interest you:\n\n- `remove()`: to remove a specific node from the list.\n- `len()`: to count the number of nodes in the list.\n- `prepend()`: to add a node to the beginning of the list (i.e. set the head node of the list).\n- `pop()`: to remove the last node of the list.\n- `popFirst()`: to remove the first node of the list.\n- `concatByMoving()`: to concat two doubly linked lists together.\n\n\n### Iterating through the linked list\n\nIf you want to iterate over the elements of the linked list, all you need to do is to follow\nthe trail created by the \"pointer to next node\". We usually do that inside a while loop, that simply goes to the\nnext node over and over, until it finds a null pointer, which means that we hit the end of the list.\n\nThis next example demonstrates how such while loop would work. Notice that we are using the `@fieldParentPtr()`\nbuilt-in function to get access to a pointer that points to the parent instance of the `node` object. In other words,\nwe get access to a pointer to the `NodeU32` instance that contains the current node. This way, we can use this pointer\nto access the data that is currently stored in this node.\n\nAlso notice that in each iteration of the while loop, we are changing the value of the `it` variable to the next node\nin the list. The while loop is interrupted in the moment that this `it` variable becomes null, which will happen\nwhen the there is not \"next node\" in the list, which means that we have reached the end of the list.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst NodeU32 = struct {\n    data: u32,\n    node: std.SinglyLinkedList.Node = .{},\n};\n\nvar list: std.SinglyLinkedList = .{};\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nlist.prepend(&two.node); // {2}\nlist.prepend(&five.node); // {5, 2}\nlist.prepend(&three.node); // {3, 5, 2}\nlist.prepend(&one.node); // {1, 3, 5, 2}\n\nvar it = list.first;\nwhile (it) |node| : (it = node.next) {\n    const l: *NodeU32 = @fieldParentPtr(\n        \"node\", node\n    );\n    try stdout.print(\n        \"Current value: {}\", .{l.data}\n    );\n}\n```\n:::\n\n\n```\nCurrent value: 1\nCurrent value: 3\nCurrent value: 5\nCurrent value: 2\n```\n\n\n\n\n## Multi array structure\n\nZig introduces a new data structure called `MultiArrayList()`. It's a different version of the dynamic array\nthat we have introduced in @sec-dynamic-array. The difference between this structure and the `ArrayList()`\nthat we know from @sec-dynamic-array, is that `MultiArrayList()` creates a separate dynamic array\nfor each field of the struct that you provide as input.\n\nConsider the following code example. We create a new custom struct called `Person`. This\nstruct contains three different data members, or, three different fields. As consequence,\nwhen we provide this `Person` data type as input to `MultiArrayList()`, this\ncreates a \"struct of three different arrays\" called `PersonArray`. In other words,\nthis `PersonArray` is a struct that contains three internal dynamic arrays in it.\nOne array for each field found in the `Person` struct definition.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Person = struct {\n    name: []const u8,\n    age: u8,\n    height: f32,\n};\nconst PersonArray = std.MultiArrayList(Person);\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var people = PersonArray{};\n    defer people.deinit(allocator);\n\n    try people.append(allocator, .{\n        .name = \"Auguste\", .age = 15, .height = 1.54\n    });\n    try people.append(allocator, .{\n        .name = \"Elena\", .age = 26, .height = 1.65\n    });\n    try people.append(allocator, .{\n        .name = \"Michael\", .age = 64, .height = 1.87\n    });\n}\n```\n:::\n\n\nIn other words, instead of creating an array of \"persons\", the `MultiArrayList()` function\ncreates a \"struct of arrays\". Each data member of this struct is a different array that stores\nthe values of a specific field from the `Person` values that were added (or, appended) to this \"struct of arrays\".\nOne important detail is that each of these separate internal arrays stored inside `PersonArray`\nare dynamic arrays. This means that these arrays can grow in capacity automatically as needed, to accomodate\nmore values.\n\nThe @fig-multi-array exposed below presents a diagram that describes the `PersonArray` struct\nthat we have created in the previous code example. Notice that the values of the data members\npresent in each of the three `Person` values that we have appended into the `PersonArray` object\n, are scattered across three different internal arrays of the `PersonArray` object.\n\n![A diagram of the `PersonArray` struct.](./../Figures/multi-array.png){#fig-multi-array}\n\nYou can easily access each of these arrays separately, and iterate over the values of each array.\nFor that, you will need to call the `items()` method from the `PersonArray` object, and provide as input\nto this method, the name of the field that you want to iterate over.\nIf you want to iterate through the `.age` array for example, then, you need to call `items(.age)` from\nthe `PersonArray` object, like in the example below:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (people.items(.age)) |*age| {\n    try stdout.print(\"Age: {d}\\n\", .{age.*});\n}\n```\n:::\n\n\n```\nAge: 15\nAge: 26\nAge: 64\n```\n\n\nIn the above example, we are iterating over the values of the `.age` array, or,\nthe internal array of the `PersonArray` object that contains the values of the `age`\ndata member from the `Person` values that were added to the multi array struct.\n\nIn this example we are calling the `items()` method directly from the `PersonArray`\nobject. However, in most situations it's recommened to call this `items()` method\nfrom a \"slice object\", which you can create from the `slice()` method.\nThe reason for this is that calling `items()` multiple times have better performance\nif you use a slice object.\n\nTherefore, if you are planning to access only one of the\ninternal arrays from your \"multi array struct\", it's fine to call `items()` directly\nfrom the multi array object. But if you need to access many of the internal arrays\nfrom your \"multi array struct\", then, you will likely need to call `items()` more\nthan once, and, in such circumstance, is better to call `items()` through a slice object.\nThe example below demonstrates the use of such object:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar slice = people.slice();\nfor (slice.items(.age)) |*age| {\n    age.* += 10;\n}\nfor (slice.items(.name), slice.items(.age)) |*n,*a| {\n    try stdout.print(\n        \"Name: {s}, Age: {d}\\n\", .{n.*, a.*}\n    );\n}\n```\n:::\n\n\n```\nName: Auguste, Age: 25\nName: Elena, Age: 36\nName: Michael, Age: 74\n```\n\n\n## Conclusion\n\nThere are many other data structures that I haven't presented here.\nBut you can check them out at the official Zig Standard Library documentation page.\nActually, when you get into the [homepage of the documentation](https://ziglang.org/documentation/master/std/#)[^home], the first thing\nthat appears to you in this page, is a list of types and data structures that\nare available in the Zig Standard Library.\nThere are some very specific data structures in this list, like a\n[`BoundedArray` struct](https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray)[^bounded]\n, but there is also some more general structures, such as a\n[`PriorityQueue` struct](https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue)[^priority].\n\n\n[^home]: <https://ziglang.org/documentation/master/std/#>\n[^priority]: <https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue>.\n[^bounded]: <https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray>\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
diff --git a/docs/Chapters/09-data-structures.html b/docs/Chapters/09-data-structures.html
index 1e43b46a..d3a850aa 100644
--- a/docs/Chapters/09-data-structures.html
+++ b/docs/Chapters/09-data-structures.html
@@ -350,6 +350,7 @@ <h2 id="toc-title">Table of contents</h2>
   <li><a href="#recent-change-in-the-api" id="toc-recent-change-in-the-api" class="nav-link" data-scroll-target="#recent-change-in-the-api"><span class="header-section-number">11.3.1</span> Recent change in the API</a></li>
   <li><a href="#how-to-use-a-singly-linked-list" id="toc-how-to-use-a-singly-linked-list" class="nav-link" data-scroll-target="#how-to-use-a-singly-linked-list"><span class="header-section-number">11.3.2</span> How to use a singly linked list</a></li>
   <li><a href="#how-to-use-a-doubly-linked-list" id="toc-how-to-use-a-doubly-linked-list" class="nav-link" data-scroll-target="#how-to-use-a-doubly-linked-list"><span class="header-section-number">11.3.3</span> How to use a doubly linked list</a></li>
+  <li><a href="#iterating-through-the-linked-list" id="toc-iterating-through-the-linked-list" class="nav-link" data-scroll-target="#iterating-through-the-linked-list"><span class="header-section-number">11.3.4</span> Iterating through the linked list</a></li>
   </ul></li>
   <li><a href="#multi-array-structure" id="toc-multi-array-structure" class="nav-link" data-scroll-target="#multi-array-structure"><span class="header-section-number">11.4</span> Multi array structure</a></li>
   <li><a href="#conclusion-1" id="toc-conclusion-1" class="nav-link" data-scroll-target="#conclusion-1"><span class="header-section-number">11.5</span> Conclusion</a></li>
@@ -796,7 +797,7 @@ <h3 data-number="11.3.3" class="anchored" data-anchor-id="how-to-use-a-doubly-li
 <li>Start to insert the nodes inside the list.</li>
 </ol>
 <p>In your “custom node type”, you should use the <code>DoublyLinkedList.Node</code> type to denote the <code>node</code> member of the struct. The snippet below demonstrates that. Here we are creating, once again, a node type that can store <code>u32</code> values. But this time, this struct is tailored to be used inside a <code>DoublyLinkedList</code> struct.</p>
-<p>After this step, the way that you create the new empty linked list, and the nodes that you want insert, is practically identical to the singly linked list case. But, things are different when you start to add nodes to the list. Instead of using the <code>prepend()</code> method of the list object, you should use the <code>append()</code> method to add the nodes to the linked list.</p>
+<p>After this step, the way that you create the new empty linked list, and the nodes that you want insert, is practically identical to the singly linked list case. But, this time, we normally use the <code>append()</code> method from the linked list object to add new nodes to the list.</p>
 <p>This <code>append()</code> method from the linked list object will always append the input node to the end of the linked list. However, in case you want to add the new node into a different position of the list, then, you should take a look at the <code>insertAfter()</code> and <code>insertBefore()</code> methods of the linked list object. These methods allow you to insert the new node either after or before an existing node in the list.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb27"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb27-1"><a href="#cb27-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> NodeU32 = <span class="kw">struct</span> <span class="op">{</span></span>
@@ -833,36 +834,73 @@ <h3 data-number="11.3.3" class="anchored" data-anchor-id="how-to-use-a-doubly-li
 <li><code>concatByMoving()</code>: to concat two doubly linked lists together.</li>
 </ul>
 </section>
+<section id="iterating-through-the-linked-list" class="level3" data-number="11.3.4">
+<h3 data-number="11.3.4" class="anchored" data-anchor-id="iterating-through-the-linked-list"><span class="header-section-number">11.3.4</span> Iterating through the linked list</h3>
+<p>If you want to iterate over the elements of the linked list, all you need to do is to follow the trail created by the “pointer to next node”. We usually do that inside a while loop, that simply goes to the next node over and over, until it finds a null pointer, which means that we hit the end of the list.</p>
+<p>This next example demonstrates how such while loop would work. Notice that we are using the <code>@fieldParentPtr()</code> built-in function to get access to a pointer that points to the parent instance of the <code>node</code> object. In other words, we get access to a pointer to the <code>NodeU32</code> instance that contains the current node. This way, we can use this pointer to access the data that is currently stored in this node.</p>
+<p>Also notice that in each iteration of the while loop, we are changing the value of the <code>it</code> variable to the next node in the list. The while loop is interrupted in the moment that this <code>it</code> variable becomes null, which will happen when the there is not “next node” in the list, which means that we have reached the end of the list.</p>
+<div class="cell">
+<div class="sourceCode cell-code" id="cb29"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb29-1"><a href="#cb29-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> NodeU32 = <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb29-2"><a href="#cb29-2" aria-hidden="true" tabindex="-1"></a>    data: <span class="dt">u32</span>,</span>
+<span id="cb29-3"><a href="#cb29-3" aria-hidden="true" tabindex="-1"></a>    node: std.SinglyLinkedList.Node = .<span class="op">{}</span>,</span>
+<span id="cb29-4"><a href="#cb29-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
+<span id="cb29-5"><a href="#cb29-5" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb29-6"><a href="#cb29-6" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> list: std.SinglyLinkedList = .<span class="op">{}</span>;</span>
+<span id="cb29-7"><a href="#cb29-7" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> one: NodeU32 = .<span class="op">{</span> .data = <span class="dv">1</span> <span class="op">}</span>;</span>
+<span id="cb29-8"><a href="#cb29-8" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> two: NodeU32 = .<span class="op">{</span> .data = <span class="dv">2</span> <span class="op">}</span>;</span>
+<span id="cb29-9"><a href="#cb29-9" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> three: NodeU32 = .<span class="op">{</span> .data = <span class="dv">3</span> <span class="op">}</span>;</span>
+<span id="cb29-10"><a href="#cb29-10" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> five: NodeU32 = .<span class="op">{</span> .data = <span class="dv">5</span> <span class="op">}</span>;</span>
+<span id="cb29-11"><a href="#cb29-11" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb29-12"><a href="#cb29-12" aria-hidden="true" tabindex="-1"></a>list.prepend(&amp;two.node); <span class="co">// {2}</span></span>
+<span id="cb29-13"><a href="#cb29-13" aria-hidden="true" tabindex="-1"></a>list.prepend(&amp;five.node); <span class="co">// {5, 2}</span></span>
+<span id="cb29-14"><a href="#cb29-14" aria-hidden="true" tabindex="-1"></a>list.prepend(&amp;three.node); <span class="co">// {3, 5, 2}</span></span>
+<span id="cb29-15"><a href="#cb29-15" aria-hidden="true" tabindex="-1"></a>list.prepend(&amp;one.node); <span class="co">// {1, 3, 5, 2}</span></span>
+<span id="cb29-16"><a href="#cb29-16" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb29-17"><a href="#cb29-17" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> it = list.first;</span>
+<span id="cb29-18"><a href="#cb29-18" aria-hidden="true" tabindex="-1"></a><span class="kw">while</span> (it) |node| : (it = node.next) <span class="op">{</span></span>
+<span id="cb29-19"><a href="#cb29-19" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> l: *NodeU32 = <span class="bu">@fieldParentPtr</span>(</span>
+<span id="cb29-20"><a href="#cb29-20" aria-hidden="true" tabindex="-1"></a>        <span class="st">"node"</span>, node</span>
+<span id="cb29-21"><a href="#cb29-21" aria-hidden="true" tabindex="-1"></a>    );</span>
+<span id="cb29-22"><a href="#cb29-22" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(</span>
+<span id="cb29-23"><a href="#cb29-23" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Current value: {}"</span>, .<span class="op">{</span>l.data<span class="op">}</span></span>
+<span id="cb29-24"><a href="#cb29-24" aria-hidden="true" tabindex="-1"></a>    );</span>
+<span id="cb29-25"><a href="#cb29-25" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+</div>
+<pre><code>Current value: 1
+Current value: 3
+Current value: 5
+Current value: 2</code></pre>
+</section>
 </section>
 <section id="multi-array-structure" class="level2" data-number="11.4">
 <h2 data-number="11.4" class="anchored" data-anchor-id="multi-array-structure"><span class="header-section-number">11.4</span> Multi array structure</h2>
 <p>Zig introduces a new data structure called <code>MultiArrayList()</code>. It’s a different version of the dynamic array that we have introduced in <a href="#sec-dynamic-array" class="quarto-xref"><span>Section 11.1</span></a>. The difference between this structure and the <code>ArrayList()</code> that we know from <a href="#sec-dynamic-array" class="quarto-xref"><span>Section 11.1</span></a>, is that <code>MultiArrayList()</code> creates a separate dynamic array for each field of the struct that you provide as input.</p>
 <p>Consider the following code example. We create a new custom struct called <code>Person</code>. This struct contains three different data members, or, three different fields. As consequence, when we provide this <code>Person</code> data type as input to <code>MultiArrayList()</code>, this creates a “struct of three different arrays” called <code>PersonArray</code>. In other words, this <code>PersonArray</code> is a struct that contains three internal dynamic arrays in it. One array for each field found in the <code>Person</code> struct definition.</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb29"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb29-1"><a href="#cb29-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
-<span id="cb29-2"><a href="#cb29-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Person = <span class="kw">struct</span> <span class="op">{</span></span>
-<span id="cb29-3"><a href="#cb29-3" aria-hidden="true" tabindex="-1"></a>    name: []<span class="kw">const</span> <span class="dt">u8</span>,</span>
-<span id="cb29-4"><a href="#cb29-4" aria-hidden="true" tabindex="-1"></a>    age: <span class="dt">u8</span>,</span>
-<span id="cb29-5"><a href="#cb29-5" aria-hidden="true" tabindex="-1"></a>    height: <span class="dt">f32</span>,</span>
-<span id="cb29-6"><a href="#cb29-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
-<span id="cb29-7"><a href="#cb29-7" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> PersonArray = std.MultiArrayList(Person);</span>
-<span id="cb29-8"><a href="#cb29-8" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb29-9"><a href="#cb29-9" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
-<span id="cb29-10"><a href="#cb29-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> gpa = std.heap.GeneralPurposeAllocator(.<span class="op">{}</span>)<span class="op">{}</span>;</span>
-<span id="cb29-11"><a href="#cb29-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> allocator = gpa.allocator();</span>
-<span id="cb29-12"><a href="#cb29-12" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> people = PersonArray<span class="op">{}</span>;</span>
-<span id="cb29-13"><a href="#cb29-13" aria-hidden="true" tabindex="-1"></a>    <span class="kw">defer</span> people.deinit(allocator);</span>
-<span id="cb29-14"><a href="#cb29-14" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb29-15"><a href="#cb29-15" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
-<span id="cb29-16"><a href="#cb29-16" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Auguste"</span>, .age = <span class="dv">15</span>, .height = <span class="fl">1.54</span></span>
-<span id="cb29-17"><a href="#cb29-17" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
-<span id="cb29-18"><a href="#cb29-18" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
-<span id="cb29-19"><a href="#cb29-19" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Elena"</span>, .age = <span class="dv">26</span>, .height = <span class="fl">1.65</span></span>
-<span id="cb29-20"><a href="#cb29-20" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
-<span id="cb29-21"><a href="#cb29-21" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
-<span id="cb29-22"><a href="#cb29-22" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Michael"</span>, .age = <span class="dv">64</span>, .height = <span class="fl">1.87</span></span>
-<span id="cb29-23"><a href="#cb29-23" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
-<span id="cb29-24"><a href="#cb29-24" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb31"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb31-1"><a href="#cb31-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
+<span id="cb31-2"><a href="#cb31-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Person = <span class="kw">struct</span> <span class="op">{</span></span>
+<span id="cb31-3"><a href="#cb31-3" aria-hidden="true" tabindex="-1"></a>    name: []<span class="kw">const</span> <span class="dt">u8</span>,</span>
+<span id="cb31-4"><a href="#cb31-4" aria-hidden="true" tabindex="-1"></a>    age: <span class="dt">u8</span>,</span>
+<span id="cb31-5"><a href="#cb31-5" aria-hidden="true" tabindex="-1"></a>    height: <span class="dt">f32</span>,</span>
+<span id="cb31-6"><a href="#cb31-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>;</span>
+<span id="cb31-7"><a href="#cb31-7" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> PersonArray = std.MultiArrayList(Person);</span>
+<span id="cb31-8"><a href="#cb31-8" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb31-9"><a href="#cb31-9" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> main() !<span class="dt">void</span> <span class="op">{</span></span>
+<span id="cb31-10"><a href="#cb31-10" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> gpa = std.heap.GeneralPurposeAllocator(.<span class="op">{}</span>)<span class="op">{}</span>;</span>
+<span id="cb31-11"><a href="#cb31-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">const</span> allocator = gpa.allocator();</span>
+<span id="cb31-12"><a href="#cb31-12" aria-hidden="true" tabindex="-1"></a>    <span class="kw">var</span> people = PersonArray<span class="op">{}</span>;</span>
+<span id="cb31-13"><a href="#cb31-13" aria-hidden="true" tabindex="-1"></a>    <span class="kw">defer</span> people.deinit(allocator);</span>
+<span id="cb31-14"><a href="#cb31-14" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb31-15"><a href="#cb31-15" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
+<span id="cb31-16"><a href="#cb31-16" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Auguste"</span>, .age = <span class="dv">15</span>, .height = <span class="fl">1.54</span></span>
+<span id="cb31-17"><a href="#cb31-17" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
+<span id="cb31-18"><a href="#cb31-18" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
+<span id="cb31-19"><a href="#cb31-19" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Elena"</span>, .age = <span class="dv">26</span>, .height = <span class="fl">1.65</span></span>
+<span id="cb31-20"><a href="#cb31-20" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
+<span id="cb31-21"><a href="#cb31-21" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> people.append(allocator, .<span class="op">{</span></span>
+<span id="cb31-22"><a href="#cb31-22" aria-hidden="true" tabindex="-1"></a>        .name = <span class="st">"Michael"</span>, .age = <span class="dv">64</span>, .height = <span class="fl">1.87</span></span>
+<span id="cb31-23"><a href="#cb31-23" aria-hidden="true" tabindex="-1"></a>    <span class="op">}</span>);</span>
+<span id="cb31-24"><a href="#cb31-24" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <p>In other words, instead of creating an array of “persons”, the <code>MultiArrayList()</code> function creates a “struct of arrays”. Each data member of this struct is a different array that stores the values of a specific field from the <code>Person</code> values that were added (or, appended) to this “struct of arrays”. One important detail is that each of these separate internal arrays stored inside <code>PersonArray</code> are dynamic arrays. This means that these arrays can grow in capacity automatically as needed, to accomodate more values.</p>
 <p>The <a href="#fig-multi-array" class="quarto-xref">Figure&nbsp;<span>11.5</span></a> exposed below presents a diagram that describes the <code>PersonArray</code> struct that we have created in the previous code example. Notice that the values of the data members present in each of the three <code>Person</code> values that we have appended into the <code>PersonArray</code> object , are scattered across three different internal arrays of the <code>PersonArray</code> object.</p>
@@ -878,9 +916,9 @@ <h2 data-number="11.4" class="anchored" data-anchor-id="multi-array-structure"><
 </div>
 <p>You can easily access each of these arrays separately, and iterate over the values of each array. For that, you will need to call the <code>items()</code> method from the <code>PersonArray</code> object, and provide as input to this method, the name of the field that you want to iterate over. If you want to iterate through the <code>.age</code> array for example, then, you need to call <code>items(.age)</code> from the <code>PersonArray</code> object, like in the example below:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb30"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb30-1"><a href="#cb30-1" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (people.items(.age)) |*age| <span class="op">{</span></span>
-<span id="cb30-2"><a href="#cb30-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"Age: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>age.*<span class="op">}</span>);</span>
-<span id="cb30-3"><a href="#cb30-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb32"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb32-1"><a href="#cb32-1" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (people.items(.age)) |*age| <span class="op">{</span></span>
+<span id="cb32-2"><a href="#cb32-2" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(<span class="st">"Age: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>age.*<span class="op">}</span>);</span>
+<span id="cb32-3"><a href="#cb32-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Age: 15
 Age: 26
@@ -889,15 +927,15 @@ <h2 data-number="11.4" class="anchored" data-anchor-id="multi-array-structure"><
 <p>In this example we are calling the <code>items()</code> method directly from the <code>PersonArray</code> object. However, in most situations it’s recommened to call this <code>items()</code> method from a “slice object”, which you can create from the <code>slice()</code> method. The reason for this is that calling <code>items()</code> multiple times have better performance if you use a slice object.</p>
 <p>Therefore, if you are planning to access only one of the internal arrays from your “multi array struct”, it’s fine to call <code>items()</code> directly from the multi array object. But if you need to access many of the internal arrays from your “multi array struct”, then, you will likely need to call <code>items()</code> more than once, and, in such circumstance, is better to call <code>items()</code> through a slice object. The example below demonstrates the use of such object:</p>
 <div class="cell">
-<div class="sourceCode cell-code" id="cb32"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb32-1"><a href="#cb32-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> slice = people.slice();</span>
-<span id="cb32-2"><a href="#cb32-2" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (slice.items(.age)) |*age| <span class="op">{</span></span>
-<span id="cb32-3"><a href="#cb32-3" aria-hidden="true" tabindex="-1"></a>    age.* += <span class="dv">10</span>;</span>
-<span id="cb32-4"><a href="#cb32-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
-<span id="cb32-5"><a href="#cb32-5" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (slice.items(.name), slice.items(.age)) |*n,*a| <span class="op">{</span></span>
-<span id="cb32-6"><a href="#cb32-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(</span>
-<span id="cb32-7"><a href="#cb32-7" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Name: {s}, Age: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>n.*, a.*<span class="op">}</span></span>
-<span id="cb32-8"><a href="#cb32-8" aria-hidden="true" tabindex="-1"></a>    );</span>
-<span id="cb32-9"><a href="#cb32-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="sourceCode cell-code" id="cb34"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb34-1"><a href="#cb34-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> slice = people.slice();</span>
+<span id="cb34-2"><a href="#cb34-2" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (slice.items(.age)) |*age| <span class="op">{</span></span>
+<span id="cb34-3"><a href="#cb34-3" aria-hidden="true" tabindex="-1"></a>    age.* += <span class="dv">10</span>;</span>
+<span id="cb34-4"><a href="#cb34-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span>
+<span id="cb34-5"><a href="#cb34-5" aria-hidden="true" tabindex="-1"></a><span class="kw">for</span> (slice.items(.name), slice.items(.age)) |*n,*a| <span class="op">{</span></span>
+<span id="cb34-6"><a href="#cb34-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> stdout.print(</span>
+<span id="cb34-7"><a href="#cb34-7" aria-hidden="true" tabindex="-1"></a>        <span class="st">"Name: {s}, Age: {d}</span><span class="sc">\n</span><span class="st">"</span>, .<span class="op">{</span>n.*, a.*<span class="op">}</span></span>
+<span id="cb34-8"><a href="#cb34-8" aria-hidden="true" tabindex="-1"></a>    );</span>
+<span id="cb34-9"><a href="#cb34-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 </div>
 <pre><code>Name: Auguste, Age: 25
 Name: Elena, Age: 36
diff --git a/docs/search.json b/docs/search.json
index a11536a5..d218958c 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -904,7 +904,7 @@
     "href": "Chapters/09-data-structures.html#linked-lists",
     "title": "11  Data Structures",
     "section": "11.3 Linked lists",
-    "text": "11.3 Linked lists\nThe Zig Standard Library provides an implementation for both singly and doubly linked lists. More specifically, through the structs SinglyLinkedList and DoublyLinkedList.\nIn case you are not familiar with these data structures, a linked list is a linear data structure that looks like a chain, or, a rope. The main advantage of this data structure is that you normally have very fast insertion and deletion operations. But, as a disadvantage, iterating through this data structure is usually not so fast as iterating through an array.\nThe idea behind a linked list is to build a structure that consists of a sequence of nodes connected to each other by pointers. This means that linked lists are usually not contiguous in memory, because each node might be anywhere in memory. They do not need to be close to one another.\nIn Figure 11.3 we can see a diagram of a singly linked list. We begin at the first node (which is usually called “the head of the linked list”). Then, from this first node we uncover the remaining nodes in the structure, by following the locations pointed by the pointers found in each node.\nEach node has two things in it. It has the value that is stored in the current node , and also, a pointer. This pointer points to the next node in the list. If this pointer is null, then, it means that we have reached the end of our linked list.\n\n\n\n\n\n\nFigure 11.3: A diagram of a singly linked list.\n\n\n\nIn Figure 11.4 we can see a diagram of a doubly linked list. The only thing that really changes now is that every node in the linked list has both a pointer to the previous node, and, a pointer to the next node. So every node in a doubly linked list has two pointers in it. These are usually called the prev (for “previous”) and the next (for “next”) pointers of the node.\nIn the singly linked list example, we had only one single pointer in each node, and this singular pointer was always pointing to the next node in the sequence. This means that singly linked lists normally have only the next pointer in them.\n\n\n\n\n\n\nFigure 11.4: A diagram of a doubly linked list.\n\n\n\n\n11.3.1 Recent change in the API\nOn previous versions of Zig, the SinglyLinkedList and DoublyLinkedList structs were initially implemented as “generics data structures”. Meaning that, you would use a generic function to create a singly (or doubly) linked list that could store the specific data type that you wanted to use. We will learn more about generics at Section 12.2, and also, how we can create a “generic data structure” at Section 12.2.2.\nHowever, on the latest versions of Zig, the structs SinglyLinkedList and DoublyLinkedList were altered to use a “less generic API”. This specific change was introduced on April 3, 2025. Therefore, check if your Zig version is one released after this date. Just have in mind that if you don’t have a very recent version of the Zig compiler, you might have problems while trying to compile the next examples exposed here.\n\n\n11.3.2 How to use a singly linked list\nFor example, consider that you are creating a singly linked list that is going to store u32 values. Given this scenario, the first thing that we need to do, is to create a “node type” that is capable of storing a u32 value. The NodeU32 type exposed below demonstrates such “node type”.\nNotice that the data type associated with the member named data is the most important part of this custom “node type”. It determines the data type that is going to be stored in each node.\n\nconst std = @import(\"std\");\nconst NodeU32 = struct {\n    data: u32,\n    node: std.SinglyLinkedList.Node = .{},\n};\n\nAfter we created our custom “node type” that can store the specific data type that we want, we can just create a new and empty singly linked list, which will store our nodes. To do that, we just create a new object with the type SinglyLinkedList, like this:\n\nvar list: std.SinglyLinkedList = .{};\n\nNow, we have our linked list… But how can we insert nodes in it? Well, first of all, we need to create our nodes. So let’s focus on that first. The snippet exposed below demonstrates how we could use our NodeU32 struct to create such nodes.\nNotice in this snippet that we are just setting the data member of the struct for now. We don’t need to connect these nodes together in this first instance. This is why we ignore the node member at first. But we are going to connect these nodes in a future point of the code, which is why these objects are marked as “variable objects”, so that we can alter them in the future.\n\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nNow that we have both the linked list and also the nodes created, we can start to connect them together. You can use the prepend() method from the linked list object to insert the first node in the list, which is the “head” of the linked list. As the name suggests, this specific method prepends the input node to the linked list, or, in other words, it transforms the input node into the first node of the list.\nAfter we added the “head node” of the list, we can start to add the “next nodes” in the list by using the insertAfter() method from the SinglyLinkedList.Node type, which, in our case here, is accessible through the node member of our NodeU32 type. Thus, we can start to create the connections between the nodes by calling this method from the node objects that are present in the list. Like in this example below:\n\nlist.prepend(&two.node); // {2}\ntwo.node.insertAfter(&five.node); // {2, 5}\ntwo.node.insertAfter(&three.node); // {2, 3, 5}\n\nYou can also call the prepend() method again to add new nodes to the beginning of the linked list, which means, effectively, changing the “head node” of the list, like this:\n\nlist.prepend(&one.node); // {1, 2, 3, 5}\n\nThere are other methods available from the singly linked list object that you might be interested. You can find a summary of them in the bullet points below:\n\nremove() to remove a specific node from the linked list.\nlen() to count how many nodes there is in the linked list.\npopFirst() to remove the first node (i.e., the “head”) from the linked list.\n\nSo, that is how singly linked lists work in Zig in a nutshell. To sum up, this is all the source code that was exposed in this section inside the single cell:\n\nconst NodeU32 = struct {\n    data: u32,\n    node: std.SinglyLinkedList.Node = .{},\n};\n\nvar list: std.SinglyLinkedList = .{};\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nlist.prepend(&two.node); // {2}\ntwo.node.insertAfter(&five.node); // {2, 5}\ntwo.node.insertAfter(&three.node); // {2, 3, 5}\nlist.prepend(&one.node); // {1, 2, 3, 5}\n\ntry stdout.print(\"Number of nodes: {}\", .{list.len()});\n\nNumber of nodes: 4\n\n\n\n\n11.3.3 How to use a doubly linked list\nIf you want to use a doubly linked list instead, you will face a similar workflow compared to the singly linked list:\n\nYou first create a “custom node type” that can store the specific data type that you want.\nCreate an empty doubly linked list object.\nCreate the nodes of linked list.\nStart to insert the nodes inside the list.\n\nIn your “custom node type”, you should use the DoublyLinkedList.Node type to denote the node member of the struct. The snippet below demonstrates that. Here we are creating, once again, a node type that can store u32 values. But this time, this struct is tailored to be used inside a DoublyLinkedList struct.\nAfter this step, the way that you create the new empty linked list, and the nodes that you want insert, is practically identical to the singly linked list case. But, things are different when you start to add nodes to the list. Instead of using the prepend() method of the list object, you should use the append() method to add the nodes to the linked list.\nThis append() method from the linked list object will always append the input node to the end of the linked list. However, in case you want to add the new node into a different position of the list, then, you should take a look at the insertAfter() and insertBefore() methods of the linked list object. These methods allow you to insert the new node either after or before an existing node in the list.\n\nconst NodeU32 = struct {\n    data: u32,\n    node: std.DoublyLinkedList.Node = .{},\n};\n\nvar list: std.DoublyLinkedList = .{};\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nlist.append(&one.node); // {1}\nlist.append(&three.node); // {1, 3}\nlist.insertAfter(\n    &one.node,\n    &five.node\n); // {1, 5, 3}\nlist.append(&two.node); // {1, 5, 3, 2}\n\ntry stdout.print(\"Number of nodes: {}\", .{list.len()});\n\nNumber of nodes: 4\n\n\nThese are other methods from the DoublyLinkedList object that might interest you:\n\nremove(): to remove a specific node from the list.\nlen(): to count the number of nodes in the list.\nprepend(): to add a node to the beginning of the list (i.e. set the head node of the list).\npop(): to remove the last node of the list.\npopFirst(): to remove the first node of the list.\nconcatByMoving(): to concat two doubly linked lists together.",
+    "text": "11.3 Linked lists\nThe Zig Standard Library provides an implementation for both singly and doubly linked lists. More specifically, through the structs SinglyLinkedList and DoublyLinkedList.\nIn case you are not familiar with these data structures, a linked list is a linear data structure that looks like a chain, or, a rope. The main advantage of this data structure is that you normally have very fast insertion and deletion operations. But, as a disadvantage, iterating through this data structure is usually not so fast as iterating through an array.\nThe idea behind a linked list is to build a structure that consists of a sequence of nodes connected to each other by pointers. This means that linked lists are usually not contiguous in memory, because each node might be anywhere in memory. They do not need to be close to one another.\nIn Figure 11.3 we can see a diagram of a singly linked list. We begin at the first node (which is usually called “the head of the linked list”). Then, from this first node we uncover the remaining nodes in the structure, by following the locations pointed by the pointers found in each node.\nEach node has two things in it. It has the value that is stored in the current node , and also, a pointer. This pointer points to the next node in the list. If this pointer is null, then, it means that we have reached the end of our linked list.\n\n\n\n\n\n\nFigure 11.3: A diagram of a singly linked list.\n\n\n\nIn Figure 11.4 we can see a diagram of a doubly linked list. The only thing that really changes now is that every node in the linked list has both a pointer to the previous node, and, a pointer to the next node. So every node in a doubly linked list has two pointers in it. These are usually called the prev (for “previous”) and the next (for “next”) pointers of the node.\nIn the singly linked list example, we had only one single pointer in each node, and this singular pointer was always pointing to the next node in the sequence. This means that singly linked lists normally have only the next pointer in them.\n\n\n\n\n\n\nFigure 11.4: A diagram of a doubly linked list.\n\n\n\n\n11.3.1 Recent change in the API\nOn previous versions of Zig, the SinglyLinkedList and DoublyLinkedList structs were initially implemented as “generics data structures”. Meaning that, you would use a generic function to create a singly (or doubly) linked list that could store the specific data type that you wanted to use. We will learn more about generics at Section 12.2, and also, how we can create a “generic data structure” at Section 12.2.2.\nHowever, on the latest versions of Zig, the structs SinglyLinkedList and DoublyLinkedList were altered to use a “less generic API”. This specific change was introduced on April 3, 2025. Therefore, check if your Zig version is one released after this date. Just have in mind that if you don’t have a very recent version of the Zig compiler, you might have problems while trying to compile the next examples exposed here.\n\n\n11.3.2 How to use a singly linked list\nFor example, consider that you are creating a singly linked list that is going to store u32 values. Given this scenario, the first thing that we need to do, is to create a “node type” that is capable of storing a u32 value. The NodeU32 type exposed below demonstrates such “node type”.\nNotice that the data type associated with the member named data is the most important part of this custom “node type”. It determines the data type that is going to be stored in each node.\n\nconst std = @import(\"std\");\nconst NodeU32 = struct {\n    data: u32,\n    node: std.SinglyLinkedList.Node = .{},\n};\n\nAfter we created our custom “node type” that can store the specific data type that we want, we can just create a new and empty singly linked list, which will store our nodes. To do that, we just create a new object with the type SinglyLinkedList, like this:\n\nvar list: std.SinglyLinkedList = .{};\n\nNow, we have our linked list… But how can we insert nodes in it? Well, first of all, we need to create our nodes. So let’s focus on that first. The snippet exposed below demonstrates how we could use our NodeU32 struct to create such nodes.\nNotice in this snippet that we are just setting the data member of the struct for now. We don’t need to connect these nodes together in this first instance. This is why we ignore the node member at first. But we are going to connect these nodes in a future point of the code, which is why these objects are marked as “variable objects”, so that we can alter them in the future.\n\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nNow that we have both the linked list and also the nodes created, we can start to connect them together. You can use the prepend() method from the linked list object to insert the first node in the list, which is the “head” of the linked list. As the name suggests, this specific method prepends the input node to the linked list, or, in other words, it transforms the input node into the first node of the list.\nAfter we added the “head node” of the list, we can start to add the “next nodes” in the list by using the insertAfter() method from the SinglyLinkedList.Node type, which, in our case here, is accessible through the node member of our NodeU32 type. Thus, we can start to create the connections between the nodes by calling this method from the node objects that are present in the list. Like in this example below:\n\nlist.prepend(&two.node); // {2}\ntwo.node.insertAfter(&five.node); // {2, 5}\ntwo.node.insertAfter(&three.node); // {2, 3, 5}\n\nYou can also call the prepend() method again to add new nodes to the beginning of the linked list, which means, effectively, changing the “head node” of the list, like this:\n\nlist.prepend(&one.node); // {1, 2, 3, 5}\n\nThere are other methods available from the singly linked list object that you might be interested. You can find a summary of them in the bullet points below:\n\nremove() to remove a specific node from the linked list.\nlen() to count how many nodes there is in the linked list.\npopFirst() to remove the first node (i.e., the “head”) from the linked list.\n\nSo, that is how singly linked lists work in Zig in a nutshell. To sum up, this is all the source code that was exposed in this section inside the single cell:\n\nconst NodeU32 = struct {\n    data: u32,\n    node: std.SinglyLinkedList.Node = .{},\n};\n\nvar list: std.SinglyLinkedList = .{};\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nlist.prepend(&two.node); // {2}\ntwo.node.insertAfter(&five.node); // {2, 5}\ntwo.node.insertAfter(&three.node); // {2, 3, 5}\nlist.prepend(&one.node); // {1, 2, 3, 5}\n\ntry stdout.print(\"Number of nodes: {}\", .{list.len()});\n\nNumber of nodes: 4\n\n\n\n\n11.3.3 How to use a doubly linked list\nIf you want to use a doubly linked list instead, you will face a similar workflow compared to the singly linked list:\n\nYou first create a “custom node type” that can store the specific data type that you want.\nCreate an empty doubly linked list object.\nCreate the nodes of linked list.\nStart to insert the nodes inside the list.\n\nIn your “custom node type”, you should use the DoublyLinkedList.Node type to denote the node member of the struct. The snippet below demonstrates that. Here we are creating, once again, a node type that can store u32 values. But this time, this struct is tailored to be used inside a DoublyLinkedList struct.\nAfter this step, the way that you create the new empty linked list, and the nodes that you want insert, is practically identical to the singly linked list case. But, this time, we normally use the append() method from the linked list object to add new nodes to the list.\nThis append() method from the linked list object will always append the input node to the end of the linked list. However, in case you want to add the new node into a different position of the list, then, you should take a look at the insertAfter() and insertBefore() methods of the linked list object. These methods allow you to insert the new node either after or before an existing node in the list.\n\nconst NodeU32 = struct {\n    data: u32,\n    node: std.DoublyLinkedList.Node = .{},\n};\n\nvar list: std.DoublyLinkedList = .{};\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nlist.append(&one.node); // {1}\nlist.append(&three.node); // {1, 3}\nlist.insertAfter(\n    &one.node,\n    &five.node\n); // {1, 5, 3}\nlist.append(&two.node); // {1, 5, 3, 2}\n\ntry stdout.print(\"Number of nodes: {}\", .{list.len()});\n\nNumber of nodes: 4\n\n\nThese are other methods from the DoublyLinkedList object that might interest you:\n\nremove(): to remove a specific node from the list.\nlen(): to count the number of nodes in the list.\nprepend(): to add a node to the beginning of the list (i.e. set the head node of the list).\npop(): to remove the last node of the list.\npopFirst(): to remove the first node of the list.\nconcatByMoving(): to concat two doubly linked lists together.\n\n\n\n11.3.4 Iterating through the linked list\nIf you want to iterate over the elements of the linked list, all you need to do is to follow the trail created by the “pointer to next node”. We usually do that inside a while loop, that simply goes to the next node over and over, until it finds a null pointer, which means that we hit the end of the list.\nThis next example demonstrates how such while loop would work. Notice that we are using the @fieldParentPtr() built-in function to get access to a pointer that points to the parent instance of the node object. In other words, we get access to a pointer to the NodeU32 instance that contains the current node. This way, we can use this pointer to access the data that is currently stored in this node.\nAlso notice that in each iteration of the while loop, we are changing the value of the it variable to the next node in the list. The while loop is interrupted in the moment that this it variable becomes null, which will happen when the there is not “next node” in the list, which means that we have reached the end of the list.\n\nconst NodeU32 = struct {\n    data: u32,\n    node: std.SinglyLinkedList.Node = .{},\n};\n\nvar list: std.SinglyLinkedList = .{};\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nlist.prepend(&two.node); // {2}\nlist.prepend(&five.node); // {5, 2}\nlist.prepend(&three.node); // {3, 5, 2}\nlist.prepend(&one.node); // {1, 3, 5, 2}\n\nvar it = list.first;\nwhile (it) |node| : (it = node.next) {\n    const l: *NodeU32 = @fieldParentPtr(\n        \"node\", node\n    );\n    try stdout.print(\n        \"Current value: {}\", .{l.data}\n    );\n}\n\nCurrent value: 1\nCurrent value: 3\nCurrent value: 5\nCurrent value: 2",
     "crumbs": [
       "<span class='chapter-number'>11</span>  <span class='chapter-title'>Data Structures</span>"
     ]

From 1709663ec2607637bfd5b63d030a9cb39369d58a Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Mon, 26 May 2025 23:16:13 -0300
Subject: [PATCH 141/151] Commit to switch

---
 .../01-base64/execute-results/epub.json       | 21 +++++++++++++++++++
 .../01-memory/execute-results/epub.json       | 21 +++++++++++++++++++
 .../01-zig-weird/execute-results/epub.json    | 21 +++++++++++++++++++
 .../02-debugging/execute-results/epub.json    | 21 +++++++++++++++++++
 .../03-structs/execute-results/epub.json      | 21 +++++++++++++++++++
 .../03-unittests/execute-results/epub.json    | 21 +++++++++++++++++++
 .../04-http-server/execute-results/epub.json  | 21 +++++++++++++++++++
 .../05-pointers/execute-results/epub.json     | 21 +++++++++++++++++++
 .../07-build-system/execute-results/epub.json | 21 +++++++++++++++++++
 .../execute-results/epub.json                 | 21 +++++++++++++++++++
 .../execute-results/epub.json                 | 21 +++++++++++++++++++
 .../execute-results/epub.json                 | 21 +++++++++++++++++++
 .../12-file-op/execute-results/epub.json      | 21 +++++++++++++++++++
 .../13-image-filter/execute-results/epub.json | 21 +++++++++++++++++++
 .../14-threads/execute-results/epub.json      | 21 +++++++++++++++++++
 .../execute-results/epub.json                 | 21 +++++++++++++++++++
 .../15-vectors/execute-results/epub.json      | 21 +++++++++++++++++++
 _freeze/index/execute-results/epub.json       | 21 +++++++++++++++++++
 _freeze/references/execute-results/epub.json  | 21 +++++++++++++++++++
 19 files changed, 399 insertions(+)
 create mode 100644 _freeze/Chapters/01-base64/execute-results/epub.json
 create mode 100644 _freeze/Chapters/01-memory/execute-results/epub.json
 create mode 100644 _freeze/Chapters/01-zig-weird/execute-results/epub.json
 create mode 100644 _freeze/Chapters/02-debugging/execute-results/epub.json
 create mode 100644 _freeze/Chapters/03-structs/execute-results/epub.json
 create mode 100644 _freeze/Chapters/03-unittests/execute-results/epub.json
 create mode 100644 _freeze/Chapters/04-http-server/execute-results/epub.json
 create mode 100644 _freeze/Chapters/05-pointers/execute-results/epub.json
 create mode 100644 _freeze/Chapters/07-build-system/execute-results/epub.json
 create mode 100644 _freeze/Chapters/09-data-structures/execute-results/epub.json
 create mode 100644 _freeze/Chapters/09-error-handling/execute-results/epub.json
 create mode 100644 _freeze/Chapters/10-stack-project/execute-results/epub.json
 create mode 100644 _freeze/Chapters/12-file-op/execute-results/epub.json
 create mode 100644 _freeze/Chapters/13-image-filter/execute-results/epub.json
 create mode 100644 _freeze/Chapters/14-threads/execute-results/epub.json
 create mode 100644 _freeze/Chapters/14-zig-c-interop/execute-results/epub.json
 create mode 100644 _freeze/Chapters/15-vectors/execute-results/epub.json
 create mode 100644 _freeze/index/execute-results/epub.json
 create mode 100644 _freeze/references/execute-results/epub.json

diff --git a/_freeze/Chapters/01-base64/execute-results/epub.json b/_freeze/Chapters/01-base64/execute-results/epub.json
new file mode 100644
index 00000000..7dbf61d0
--- /dev/null
+++ b/_freeze/Chapters/01-base64/execute-results/epub.json
@@ -0,0 +1,21 @@
+{
+  "hash": "378ceb7f207e1c24d8ca75cf94cd22bf",
+  "result": {
+    "engine": "knitr",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Project 1 - Building a base64 encoder/decoder {#sec-base64}\n\nAs our first small project, I want to implement a base64 encoder/decoder with you.\nBase64 is an encoding system which translates binary data to text.\nA big chunk of the web uses base64 to deliver binary data to systems\nthat can only read text data.\n\nThe most common example of a modern use case for base64 is essentially any email system,\nlike GMail, Outlook, etc. Because email systems normally use\nthe Simple Mail Transfer Protocol (SMTP), which is a web protocol\nthat supports only text data. So, if you need, for any reason, to\nsend a binary file (like for example, a PDF, or an Excel file) as\nan attachment in your email, these binary files are normally\nconverted to base64, before they are included in the SMTP message.\nSo, the base64 encoding is largely used in these email systems to include\nbinary data into the SMTP message.\n\n\n\n\n\n\n## How the base64 algorithm work?\n\nBut how exactly does the algorithm behind the base64 encoding work? Let's discuss that. First, I will\nexplain the base64 scale, which is the 64-character scale that is the basis for\nthe base64 encoding system.\n\nAfter that, I explain the algorithm behind a base64 encoder, which is the part of the algorithm that is responsible for encoding messages\ninto the base64 encoding system. Then, after that, I explain the algorithm behind a base64 decoder, which is\nthe part of the algorithm that is responsible for translating base64 messages back into their original meaning.\n\nIf you are unsure about the differences between an \"encoder\" and a \"decoder\",\ntake a look at @sec-encode-vs-decode.\n\n\n### The base64 scale {#sec-base64-scale}\n\nThe base64 encoding system is based on a scale that goes from 0 to 63 (hence the name).\nEach index in this scale is represented by a character (it's a scale of 64 characters).\nSo, in order to convert some binary data, to the base64 encoding, we need to convert each binary number to the corresponding\ncharacter in this \"scale of 64 characters\".\n\nThe base64 scale starts with all ASCII uppercase letters (A to Z) which represents\nthe first 25 indexes in this scale (0 to 25). After that, we have all ASCII lowercase letters\n(a to z), which represents the range 26 to 51 in the scale. After that, we\nhave the one digit numbers (0 to 9), which represents the indexes from 52 to 61 in the scale.\nFinally, the last two indexes in the scale (62 and 63) are represented by the characters `+` and `/`,\nrespectively.\n\nThese are the 64 characters that compose the base64 scale. The equal sign character (`=`) is not part of the scale itself,\nbut it is a special character in the base64 encoding system. This character is used solely as a suffix, to mark the end of the character sequence,\nor, to mark the end of meaningful characters in the sequence.\n\nThe bullet points below summarises the base64 scale:\n\n- range 0 to 25 is represented by: ASCII uppercase letters `-> [A-Z]`;\n- range 26 to 51 is represented by: ASCII lowercase letters `-> [a-z]`;\n- range 52 to 61 is represented by: one digit numbers `-> [0-9]`;\n- index 62 and 63 are represented by the characters `+` and `/`, respectively;\n- the character `=` represents the end of meaningful characters in the sequence;\n\n\n\n\n### Creating the scale as a lookup table {#sec-base64-table}\n\nThe best way to represent this scale in code, is to represent it as a *lookup table*.\nLookup tables are a classic strategy in computer science to speed up calculations. The basic idea\nis to replace a runtime calculation (which can take a long time to be done) with a basic array indexing\noperation.\n\nInstead of calculating the results everytime you need them, you calculate all possible results at once, and then, you store them in an array\n(which behaves lake a \"table\"). Then, every time you need to use one of the characters in the base64 scale, instead of\nusing many resources to calculate the exact character to be used, you simply retrieve this character\nfrom the array where you stored all the possible characters in the base64 scale.\nWe retrieve the character that we need directly from memory.\n\nWe can start building a Zig struct to store our base64 decoder/encoder logic.\nWe start with the `Base64` struct below. For now, we only have one single data member in this\nstruct, i.e., the member `_table`, which represents our lookup table. We also have an `init()` method,\nto create a new instance of a `Base64` object, and, a `_char_at()` method, which is a\n\"get character at index $x$\" type of function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Base64 = struct {\n    _table: *const [64]u8,\n\n    pub fn init() Base64 {\n        const upper = \"ABCDEFGHIJKLMNOPQRSTUVWXYZ\";\n        const lower = \"abcdefghijklmnopqrstuvwxyz\";\n        const numbers_symb = \"0123456789+/\";\n        return Base64{\n            ._table = upper ++ lower ++ numbers_symb,\n        };\n    }\n\n    pub fn _char_at(self: Base64, index: usize) u8 {\n        return self._table[index];\n    }\n};\n```\n:::\n\n\n\n\nIn other words, the `_char_at()` method is responsible for getting the character in the lookup\ntable (i.e., the `_table` struct data member) that corresponds to a particular index in the\n\"base64 scale\". So, in the example below, we know that the character that corresponds to the\nindex 28 in the \"base64 scale\" is the character \"c\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst base64 = Base64.init();\ntry stdout.print(\n    \"Character at index 28: {c}\\n\",\n    .{base64._char_at(28)}\n);\n```\n:::\n\n\n\n```\nCharacter at index 28: c\n```\n\n\n\n### A base64 encoder {#sec-base64-encoder-algo}\n\nThe algorithm behind a base64 encoder usually works on a window of 3 bytes. Because each byte has\n8 bits, so, 3 bytes forms a set of $8 \\times 3 = 24$ bits. This is desirable for the base64 algorithm, because\n24 bits is divisible by 6, which forms $24 / 6 = 4$ groups of 6 bits each.\n\nTherefore, the base64 algorithm works by converting 3 bytes at a time\ninto 4 characters from the base64 scale. It keeps iterating through the input string,\n3 bytes at a time, and converting them into the base64 scale, producing 4 characters\nper iteration. It keeps iterating, and producing these \"new characters\"\nuntil it hits the end of the input string.\n\nNow you may think, what if you have a particular string that has a number of bytes\nthat is not divisible by 3 - what happens? For example, if you have a string\nthat contains only two characters/bytes, such as \"Hi\". How would the algorithm\nbehave in such situation? You find the answer in @fig-base64-algo1.\nYou can see in @fig-base64-algo1 that the string \"Hi\", when converted to base64,\nbecomes the string \"SGk=\":\n\n![The logic behind a base64 encoder](./../Figures/base64-encoder-flow.png){#fig-base64-algo1}\n\nTaking the string \"Hi\" as an example, we have 2 bytes, or, 16 bits in total. So, we lack a full byte (8 bits)\nto complete the window of 24 bits that the base64 algorithm likes to work on. The first thing that\nthe algorithm does, is to check how to divide the input bytes into groups of 6 bits.\n\nIf the algorithm notices that there is a group of 6 bits that it's not complete, meaning that, this group contains $nbits$, where $0 < nbits < 6$,\n\nthe algorithm simply adds extra zeros in this group to fill the space that it needs.\nThat is why in @fig-base64-algo1, in the third group after the 6-bit transformation,\n2 extra zeros were added to fill the gap.\n\nWhen we have a 6-bit group that is not completely full, like the third group, extra zeros\nare added to fill the gap. But what about when an entire 6-bit group is empty, or, it\nsimply doesn't exist? This is the case of the fourth 6-bit group exposed at\n@fig-base64-algo1.\n\nThis fourth group is necessary, because the algorithm works on 4 groups of 6 bits.\nBut the input string does not have enough bytes to create a fourth 6-bit group.\nEvery time this happens, where an entire group of 6 bits is empty,\nthis group becomes a \"padding group\". Every \"padding group\" is mapped to\nthe character `=` (equal sign), which represents \"null\", or, the end\nof meaningful characters in the sequence. Hence, everytime that the algorithm produces a\n\"padding group\", this group is automatically mapped to `=`.\n\nAs another example, if you give the string \"0\" as input to a base64 encoder, this string is\ntranslated into the base64 sequence \"MA==\".\nThe character \"0\" is, in binary, the sequence `00110000`[^zero-note]. So, with the 6-bit transformation\nexposed in @fig-base64-algo1, this single character would produce these two 6-bit groups: `001100`, `000000`.\nThe remaining two 6-bit groups become \"padding groups\". That is why the last\ntwo characters in the output sequence (MA==) are `==`.\n\n\n[^zero-note]: Notice that, the character \"0\" is different than the actual number 0, which is simply zero in binary.\n\n### A base64 decoder {#sec-base64-decoder-algo}\n\nThe algorithm behind a base64 decoder is essentially the inverse process of a base64 encoder.\nA base64 decoder needs to translate base64 messages back into their original meaning,\ni.e., into the original sequence of binary data.\n\nA base64 decoder usually works on a window of 4 bytes. Because it wants to convert these 4 bytes\nback into the original sequence of 3 bytes, that was converted into 4 groups of 6 bits by the\nbase64 encoder. Remember, in a base64 decoder we are essentially reverting the process made\nby the base64 encoder.\n\nEach byte in the input string (the base64 encoded string) normally contributes to re-create\ntwo different bytes in the output (the original binary data).\nIn other words, each byte that comes out of a base64 decoder is created by transforming merging two different\nbytes in the input together. You can visualize this relationship in @fig-base64-algo2:\n\n![The logic behind a base64 decoder](./../Figures/base64-decoder-flow.png){#fig-base64-algo2}\n\nThe exact transformations, or, the exact steps applied to each byte from the input to transform them\ninto the bytes of the output, are a bit tricky to visualize in a figure like this. Because of that, I have\nsummarized these transformations as \"Some bit shifting and additions ...\" in the figure. These transformations\nwill be described in depth later.\n\nBesides that, if you look again in @fig-base64-algo2, you will notice that the character `=` was completely\nignored by the algorithm. Remember, this is just a special character that marks the end of meaningful characters\nin the base64 sequence. So, every `=` character in a base64 encoded sequence should be ignored by a base64 decoder.\n\n\n## Difference between encode and decode {#sec-encode-vs-decode}\n\nIf you don't have any previous experience with base64, you might not understand the differences\nbetween \"encode\" and \"decode\". Essentially, the terms \"encode\" and \"decode\" here\nhave the exact same meaning as they have in the field of encryption (i.e., they mean the same thing as \"encode\" and \"decode\" in hashing\nalgorithms, like the MD5 algorithm).\n\nThus, \"encode\" means that we want to encode, or, in other words, we want to translate some message into\nthe base64 encoding system. We want to produce the sequence of base64 characters that represent this\noriginal message in the base64 encoding system.\n\nIn contrast, \"decode\" represents the inverse process.\nWe want to decode, or, in other words, translate a base64 message back to its original content.\nSo, in this process we get a sequence of base64 characters as input, and produce as output,\nthe binary data that is represented by this sequence of base64 characters.\n\nAny base64 library is normally composed of these two parts: 1) the encoder, which is a function that encodes\n(i.e., it converts) any sequence of binary data into a sequence of base64 characters; 2) the decoder, which is a function\nthat converts a sequence of base64 characters back into the original sequence of binary data.\n\n\n\n## Calculating the size of the output {#sec-base64-length-out}\n\nOne task that we need to do is to calculate how much space we need to reserve for the\noutput, both of the encoder and decoder. This is simple math, and can be done easily in Zig\nbecause every array has its length (its number of elements) easily accesible by consulting\nthe `.len` property of the array.\n\nFor the encoder, the logic is the following: for each 3 bytes that we find in the input,\n4 new bytes are created in the output. So, we take the number of bytes in the input, divide it\nby 3, use a ceiling function, then, we multiply the result by 4. That way, we get the total\nnumber of bytes that will be produced by the encoder in its output.\n\nThe `_calc_encode_length()` function below encapsulates this logic.\nInside this function, we take the length of the input array,\nwe divide it by 3, and apply a ceil operation over the result by using the\n`divCeil()` function from the Zig Standard Library. Lastly, we multiply\nthe end result by 4 to get the answer we need.\n\nAlso, you might have notice that, if the input length is less than 3 bytes, then, the output length of the encoder is\nalways 4 bytes. This is the case for every input with less than 3 bytes, because, as I described in @sec-base64-encoder-algo,\nthe algorithm always produces enough \"padding-groups\" in the end result, to complete the 4 bytes window.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_encode_length(input: []const u8) !usize {\n    if (input.len < 3) {\n        return 4;\n    }\n    const n_groups: usize = try std.math.divCeil(\n        usize, input.len, 3\n    );\n    return n_groups * 4;\n}\n```\n:::\n\n\n\n\nNow, the logic to calculate the length of the output from the decoder is a little bit more complicated. But, it is basically\njust the inverse logic that we've used for the encoder: for each 4 bytes in the input, 3 bytes\nwill be produced in the output of the decoder. However, this time we need to\ntake the `=` character into account, which is always ignored by the decoder, as we described in @sec-base64-decoder-algo, and,\nin @fig-base64-algo2.\n\nIn essence, we take the length of the input and divide it by 4, then we apply a floor function on the result, then\nwe multiply the result by 3, and then, we subtract from the result how much times the character `=` is found\nin the input.\n\nThe function `_calc_decode_length()` exposed below summarizes this logic that we described. It's similar\nto the function `_calc_encode_length()`. Notice that the division part is twisted. Also notice that this time, we apply\na floor operation over the output of the division, by using the `divFloor()`\nfunction (instead of a ceiling operation with `divCeil()`).\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_decode_length(input: []const u8) !usize {\n    if (input.len < 4) {\n        return 3;\n    }\n\n    const n_groups: usize = try std.math.divFloor(\n        usize, input.len, 4\n    );\n    var multiple_groups: usize = n_groups * 3;\n    var i: usize = input.len - 1;\n    while (i > 0) : (i -= 1) {\n        if (input[i] == '=') {\n            multiple_groups -= 1;\n        } else {\n            break;\n        }\n    }\n\n    return multiple_groups;\n}\n```\n:::\n\n\n\n\n## Building the encoder logic {#sec-encoder-logic}\n\nIn this section, we can start building the logic behind the `encode()` function, which\nwill be responsible for encoding messages into the base64 encoding system.\nIf you are an anxious person, and you want to see now the full source code of the implementation\nfor this base64 encoder/decoder, you can find it at the `ZigExamples` folder in the official repository of\nthis book[^zig-base64-algo].\n\n[^zig-base64-algo]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/base64/base64_basic.zig>.\n\n\n\n### The 6-bit transformation {#sec-6bit-transf}\n\nThe 6-bit transformation presented in @fig-base64-algo1 is the core part of the base64 encoder algorithm.\nBy understanding how this transformation is made in code, the rest of the algorithm becomes much simpler\nto comprehend.\n\nIn essence, this 6-bit transformation is made with the help of bitwise operators.\nBitwise operators are essential to any type of low-level operation that is done at the bit-level. For the specific case of the base64 algorithm,\nthe operators *bif shift to the left* (`<<`), *bit shift to the right* (`>>`), and the *bitwise and* (`&`) are used. They\nare the core solution for the 6-bit transformation.\n\nThere are 3 different scenarios that we need to take into account in this transformation. First, is the perfect scenario,\nwhere we have the perfect window of 3 bytes to work on. Second, we have the scenario where we have a window of only\ntwo bytes to work with. And last, we have the scenario where we have a window of one single byte.\n\nIn each of these 3 scenarios, the 6-bit transformation works a bit differently. To make the explanation\neasier, I will use the variable `output` to refer to the bytes in the output of the base64 encoder,\nand the variable `input` to refer to the bytes in the input of the encoder.\n\n\nSo, if you have the perfect window of 3 bytes, these are steps for the 6-bit transformation:\n\n1. `output[0]` is produced by moving the bits from `input[0]` two positions to the right.\n1. `output[1]` is produced by summing two components. First, take the last two bits from `input[0]`, then, move them four positions to the left. Second, move the bits from `input[1]` four positions to the right. Sum these two components.\n1. `output[2]` is produced by summing two components. First, take the last four bits from `input[1]`, then, move them two positions to the left. Second, move the bits from `input[2]` six positions to the right. Sum these two components.\n1. `output[3]` is produced by taking the last six bits from `input[2]`.\n\n\nThis is the perfect scenario, where we have a full window of 3 bytes to work on.\nJust to make things as clear as possible, the @fig-encoder-bitshift demonstrates visually how\nthe step 2 mentioned above works. So the 2nd byte in the `output` of the encoder, is made by taking the 1st byte (dark purple)\nand the 2nd byte (orange) from the input. You can see that, at the end of the process, we get a new\nbyte that contains the last 2 bits from the 1st byte in the `input`, and the first 4 bits\nfrom the 2nd byte in the `input`.\n\n![How the 2nd byte in the output of the encoder is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input.](../Figures/base64-encoder-bit-shift.png){#fig-encoder-bitshift}\n\nOn the other hand, we must be prepared for the instances where we do not have the perfect window of 3 bytes.\nIf you have a window of 2 bytes, then, the steps 3 and 4, which produces the bytes `output[2]` and `output[3]`, change a little bit,\nand they become:\n\n- `output[2]` is produced by taking the last 4 bits from `input[1]`, then, move them two positions to the left.\n- `output[3]` is the character `'='`.\n\n\nFinally, if you have a window of a single byte, then, the steps 2 to 4, which produces the bytes `output[1]`, `output[2]` and `output[3]` change,\nbecoming:\n\n- `output[1]` is produced by taking the last two bits from `input[0]`, then, move them four positions to the left.\n- `output[2]` and `output[3]` are the character `=`.\n\n\nIf these bullet points were a bit confusing for you, you may find the @tbl-transf-6bit more intuitive.\nThis table unifies all this logic into a simple table. Notice that\nthis table also provides the exact expression in Zig that creates the corresponding\nbyte in the output.\n\n\n::: {#tbl-transf-6bit}\n\n| Number of bytes in the window | Byte index in the output | In code                                    |\n|-------------------------------|--------------------------|--------------------------------------------|\n| 3                             | 0                        | input[0] >> 2                              |\n| 3                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 3                             | 2                        | ((input[1] & 0x0f) << 2) + (input[2] >> 6) |\n| 3                             | 3                        | input[2] & 0x3f                            |\n| 2                             | 0                        | input[0] >> 2                              |\n| 2                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 2                             | 2                        | ((input[1] & 0x0f) << 2)                   |\n| 2                             | 3                        | '='                                        |\n| 1                             | 0                        | input[0] >> 2                              |\n| 1                             | 1                        | ((input[0] & 0x03) << 4)                   |\n| 1                             | 2                        | '='                                        |\n| 1                             | 3                        | '='                                        |\n\n: How the 6-bit transformation translates into code in different window settings.\n\n:::\n\n\n\n\n\n\n### Bit-shifting in Zig\n\nBit-shifting in Zig works similarly to bit-shifting in C.\nAll bitwise operators that exist in C are available in Zig.\nHere, in the base64 encoder algorithm, they are essential\nto produce the result we want.\n\nFor those who are not familiar with these operators, they are\noperators that operates at the bit-level of your values.\nThis means that these operators takes the bits that form the value\nyou have, and change them in some way. This ultimately also changes\nthe value itself, because the binary representation of this value\nchanges.\n\nWe have already seen in @fig-encoder-bitshift the effect produced by a bit-shift.\nBut let's use the first byte in the output of the base64 encoder as another example of what\nbit-shifting means. This is the easiest byte of the 4 bytes in the output\nto build. Because we only need to move the bits from the first byte in the input two positions to the right,\nwith the *bit shift to the right* (`>>`) operator.\n\nIf we take the string \"Hi\" that we used in @fig-base64-algo1 as an example, the first byte in\nthis string is \"H\", which is the sequence `01001000` in binary.\nIf we move the bits of this byte, two places to the right, we get the sequence `00010010` as result.\nThis binary sequence is the value `18` in decimal, and also, the value `0x12` in hexadecimal.\nNotice that the first 6 bits of \"H\" were moved to the end of the byte.\nWith this operation, we get the first byte of the output.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const input = \"Hi\";\n    try stdout.print(\"{d}\\n\", .{input[0] >> 2});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n18\n```\n\n\n:::\n:::\n\n\n\nIf you recall @fig-base64-algo1, the first byte present in the output should\nbe equivalent to the 6-bit group `010010`. Although being visually different, the\nsequences `010010` and `00010010` are semantically equal. They mean the same thing.\nThey both represent the number 18 in decimal, and the value `0x12` in hexadecimal.\n\nSo, don't take the \"6-bit group\" factor so seriously. We do not need necessarily to\nget a 6-bit sequence as result. As long as the meaning of the 8-bit sequence we get is the same\nof the 6-bit sequence, we are in the clear.\n\n\n\n### Selecting specific bits with the `&` operator\n\nIf you comeback to @sec-6bit-transf, you will see that, in order to produce\nthe second and third bytes in the output, we need to select specific\nbits from the first and second bytes in the input string. But how\ncan we do that? The answer relies on the *bitwise and* (`&`) operator.\n\nThe @fig-encoder-bitshift already showed you what effect this `&` operator\nproduces in the bits of its operands. But let's make a clear description of it.\n\nIn summary, the `&` operator performs a logical conjunction operation\nbetween the bits of its operands. In more details, the operator `&`\ncompares each bit of the first operand to the corresponding bit of the second operand.\nIf both bits are 1, the corresponding result bit is set to 1.\nOtherwise, the corresponding result bit is set to 0 [@microsoftbitwiseand].\n\nSo, if we apply this operator to the binary sequences `1000100` and `00001101`\nthe result of this operation is the binary sequence `00000100`. Because only\nat the sixth position in both binary sequences we had a 1 value. So any\nposition where we do not have both binary sequences setted to 1, we get\na 0 bit in the resulting binary sequence.\n\nWe lose information about the original bit values\nfrom both sequences in this case. Because we no longer know\nif this 0 bit in the resulting binary sequence was produced by\ncombining 0 with 0, or 1 with 0, or 0 with 1.\n\nAs an example, suppose you have the binary sequence `10010111`, which is the number 151 in decimal. How\ncan we get a new binary sequence which contains only the third and\nfourth bits of this sequence?\n\nWe just need to combine this sequence with `00110000` (is `0x30` in hexadecimal) using the `&` operator.\nNotice that only the third and fourth positions in this binary sequence is setted to 1. As a consequence, only the\nthird and fourth values of both binary sequences are potentially preserved in the output. All the remaining positions\nare setted to zero in the output sequence, which is `00010000` (is the number 16 in decimal).\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const bits = 0b10010111;\n    try stdout.print(\"{d}\\n\", .{bits & 0b00110000});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n16\n```\n\n\n:::\n:::\n\n\n\n\n\n### Allocating space for the output\n\nAs I described in @sec-stack, to store an object in the stack,\nthis object needs to have a known and fixed length at compile-time. This is an important\nlimitation for our base64 encoder/decoder case. Because the size of\nthe output (from both the encoder and decoder) depends\ndirectly on the size of the input.\n\nHaving this in mind, we cannot know at compile time which is\nthe size of the output for both the encoder and decoder.\nSo, if we can't know the size of the output at compile time,\nthis means that we cannot store the output for both the encoder\nand decoder in the stack.\n\nConsequently, we need to store this output on the heap,\nand, as I commented in @sec-heap, we can only\nstore objects in the heap by using allocator objects.\nSo, one the arguments to both the `encode()` and `decode()`\nfunctions, needs to be an allocator object, because\nwe know for sure that, at some point inside the body of these\nfunctions, we need to allocate space on the heap to\nstore the output of these functions.\n\nThat is why, both the `encode()` and `decode()` functions that I\npresent in this book, have an argument called `allocator`,\nwhich receives a allocator object as input, identified by\nthe type `std.mem.Allocator` from the Zig Standard Library.\n\n\n\n### Writing the `encode()` function\n\nNow that we have a basic understanding on how the bitwise operators work, and how\nexactly they help us to achieve the result we want to achieve. We can now encapsulate\nall the logic that we have described in @fig-base64-algo1 and @tbl-transf-6bit into a nice\nfunction that we can add to our `Base64` struct definition, that we started in @sec-base64-table.\n\nYou can find the `encode()` function below. Notice that the first argument of this function,\nis the `Base64` struct itself. Therefore, this argument clearly signals\nthat this function is a method from the `Base64` struct.\n\nBecause the `encode()` function itself is fairly long,\nI intentionally omitted the `Base64` struct definition in this source code,\njust for brevity reasons. So, just remember that this function is a public function (or a public method) from the\n`Base64` struct.\n\nFurthermore, this `encode()` function has two other arguments:\n\n1. `input` is the input sequence of characters that you want to encode in base64;\n1. `allocator` is an allocator object to use in the necessary memory allocations.\n\nI described everything you need to know about allocator objects in @sec-allocators.\nSo, if you are not familiar with them, I highly recommend you to comeback to\nthat section, and read it.\nBy looking at the `encode()` function, you will see that we use this\nallocator object to allocate enough memory to store the output of\nthe encoding process.\n\nThe main for loop in the function is responsible for iterating through the entire input string.\nIn every iteration, we use a `count` variable to count how many iterations we had at the\nmoment. When `count` reaches 3, then, we try to encode the 3 characters (or bytes) that we have accumulated\nin the temporary buffer object (`buf`).\n\nAfter encoding these 3 characters and storing the result in the `output` variable, we reset\nthe `count` variable to zero, and start to count again on the next iteration of the loop.\nIf the loop hits the end of the string, and, the `count` variable is less than 3, then, it means that\nthe temporary buffer contains the last 1 or 2 bytes from the input.\nThat is why we have two `if` statements after the for loop. To deal which each possible case.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn encode(self: Base64,\n              allocator: std.mem.Allocator,\n              input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n\n    const n_out = try _calc_encode_length(input);\n    var out = try allocator.alloc(u8, n_out);\n    var buf = [3]u8{ 0, 0, 0 };\n    var count: u8 = 0;\n    var iout: u64 = 0;\n\n    for (input, 0..) |_, i| {\n        buf[count] = input[i];\n        count += 1;\n        if (count == 3) {\n            out[iout] = self._char_at(buf[0] >> 2);\n            out[iout + 1] = self._char_at(\n                ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n            );\n            out[iout + 2] = self._char_at(\n                ((buf[1] & 0x0f) << 2) + (buf[2] >> 6)\n            );\n            out[iout + 3] = self._char_at(buf[2] & 0x3f);\n            iout += 4;\n            count = 0;\n        }\n    }\n\n    if (count == 1) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            (buf[0] & 0x03) << 4\n        );\n        out[iout + 2] = '=';\n        out[iout + 3] = '=';\n    }\n\n    if (count == 2) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n        );\n        out[iout + 2] = self._char_at(\n            (buf[1] & 0x0f) << 2\n        );\n        out[iout + 3] = '=';\n        iout += 4;\n    }\n\n    return out;\n}\n```\n:::\n\n\n\n\n\n## Building the decoder logic {#sec-decoder-logic}\n\nNow, we can focus on writing the base64 decoder logic. Remember from @fig-base64-algo2 that,\na base64 decoder does the inverse process of an encoder. So, all we need to do, is to\nwrite a `decode()` function that performs the inverse process that I exposed in @sec-encoder-logic.\n\n\n### Mapping base64 characters to their indexes {#sec-map-base64-index}\n\nOne thing that we need to do, in order to decode a base64-encoded message, is to calculate\nthe index in the base64 scale of every base64 character that we encounter in the decoder input.\n\nIn other words, the decoder receives as input, a sequence of base64 characters. We need\nto translate this sequence of characters into a sequence of indexes. These indexes\nare the index of each character in the base64 scale. This way, we get the value/byte\nthat was calculated in the 6-bit transformation step of the encoder process.\n\nThere are probably better/faster ways to calculate this, especially using a \"divide and conquer\"\ntype of strategy. But for now, I am satisfied with a simple and \"brute force\" type of strategy.\nThe `_char_index()` function below contains this strategy.\n\nWe are essentially looping through the *lookup table* with the base64 scale,\nand comparing the character we got with each character in the base64 scale.\nIf these characters match, then, we return the index of this character in the\nbase64 scale as the result.\n\nNotice that, if the input character is `'='`, the function returns the index 64, which is\n\"out of range\" in the scale. But, as I described in @sec-base64-scale,\nthe character `'='` does not belong to the base64 scale itself.\nIt's a special and meaningless character in base64.\n\nAlso notice that this `_char_index()` function is a method from our `Base64` struct,\nbecause of the `self` argument. Again, I have omitted the `Base64` struct definition in this example\nfor brevity reasons.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn _char_index(self: Base64, char: u8) u8 {\n    if (char == '=')\n        return 64;\n    var index: u8 = 0;\n    for (0..63) |i| {\n        if (self._char_at(i) == char)\n            break;\n        index += 1;\n    }\n\n    return index;\n}\n```\n:::\n\n\n\n\n\n### The 6-bit transformation\n\nOnce again, the core part of the algorithm is the 6-bit transformation.\nIf we understand the necessary steps to perform this transformation, the rest\nof the algorithm becomes much easier.\n\nFirst of all, before we actually go to the 6-bit transformation,\nwe need to make sure that we use `_char_index()` to convert the sequence of base64 characters\ninto a sequence of indexes. So the snippet below is important for the job that will be done.\nThe result of `_char_index()` is stored in a temporary buffer, and this temporary buffer\nis what we are going to use in the 6-bit transformation, instead of the actual `input` object.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (0..input.len) |i| {\n    buf[i] = self._char_index(input[i]);\n}\n```\n:::\n\n\n\nNow, instead of producing 4 bytes (or 4 characters) as output per each window of 3 characters in the input,\na base64 decoder produces 3 bytes (or 3 characters) as output per each window of 4 characters in the input.\nOnce again, is the inverse process.\n\nSo, the steps to produce the 3 bytes in the output are:\n\n1. `output[0]` is produced by summing two components. First, move the bits from `buf[0]` two positions to the left. Second, move the bits from `buf[1]` 4 positions to the right. Then, sum these two components.\n1. `output[1]` is produced by summing two components. First, move the bits from `buf[1]` four positions to the left. Second, move the bits from `buf[2]` 2 positions to the right. Then, sum these two components.\n1. `output[2]` is produced by summing two components. First, move the bits from `buf[2]` six positions to the left. Then, you sum the result with `buf[3]`.\n\n\nBefore we continue, let's try to visualize how these transformations make the original bytes that we had\nbefore the encoding process. First, think back to the 6-bit transformation performed by the encoder exposed in @sec-encoder-logic.\nThe first byte in the output of the encoder is produced by moving the bits in the first byte of the input two positions to the right.\n\nIf for example the first byte in the input of the encoder was the sequence `ABCDEFGH`, then, the first byte in the output of the encoder would be\n`00ABCDEF` (this sequence would be the first byte in the input of the decoder). Now, if the second byte in the input of the encoder was the sequence\n`IJKLMNOP`, then, the second byte in the encoder output would be `00GHIJKL` (as we demonstrated in @fig-encoder-bitshift).\n\nHence, if the sequences `00ABCDEF` and `00GHIJKL` are the first and second bytes, respectively, in the input of the decoder, the\n@fig-decoder-bitshift demonstrates visually how these two bytes are transformed into the first byte of the output of the decoder.\nNotice that the output byte is the sequence `ABCDEFGH`, which is the original byte from the input of the encoder.\n\n![How the 1st byte in the decoder output is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input](../Figures/base64-decoder-bit-shift.png){#fig-decoder-bitshift}\n\nThe @tbl-6bit-decode presents how the three steps described earlier translate into Zig code:\n\n\n\n::: {#tbl-6bit-decode}\n\n| Byte index in the output | In code                       |\n|--------------------------|-------------------------------|\n| 0                        | (buf[0] << 2) + (buf[1] >> 4) |\n| 1                        | (buf[1] << 4) + (buf[2] >> 2) |\n| 2                        | (buf[2] << 6) + buf[3]        |\n\n: The necessary steps for the 6-transformation in the decode process.\n\n\n:::\n\n\n\n\n\n\n\n### Writing the `decode()` function\n\nThe `decode()` function below contains the entire decoding process.\nWe first calculate the size of the output, with\n`_calc_decode_length()`, then, we allocate enough memory for this output with\nthe allocator object.\n\nThree temporary variables are created: 1) `count`, to hold the window count\nin each iteration of the for loop; 2) `iout`, to hold the current index in the output;\n3) `buf`, which is the temporary buffer that holds the base64 indexes to be\nconverted through the 6-bit transformation.\n\nThen, in each iteration of the for loop we fill the temporary buffer with the current\nwindow of bytes. When `count` hits the number 4, then, we have a full window of\nindexes in `buf` to be converted, and then, we apply the 6-bit transformation\nover the temporary buffer.\n\nNotice that we check if the indexes 2 and 3 in the temporary buffer are the number 64, which, if you recall\nfrom @sec-map-base64-index, is when the `_calc_index()` function receives a `'='` character\nas input. So, if these indexes are equal to the number 64, the `decode()` function knows\nthat it can simply ignore these indexes. They are not converted because, as I described before,\nthe character `'='` has no meaning, despite being the end of meaningful characters in the sequence.\nSo we can safely ignore them when they appear in the sequence.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn decode(self: Base64,\n          allocator: std.mem.Allocator,\n          input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n    const n_output = try _calc_decode_length(input);\n    var output = try allocator.alloc(u8, n_output);\n    var count: u8 = 0;\n    var iout: u64 = 0;\n    var buf = [4]u8{ 0, 0, 0, 0 };\n\n    for (0..input.len) |i| {\n        buf[count] = self._char_index(input[i]);\n        count += 1;\n        if (count == 4) {\n            output[iout] = (buf[0] << 2) + (buf[1] >> 4);\n            if (buf[2] != 64) {\n                output[iout + 1] = (buf[1] << 4) + (buf[2] >> 2);\n            }\n            if (buf[3] != 64) {\n                output[iout + 2] = (buf[2] << 6) + buf[3];\n            }\n            iout += 3;\n            count = 0;\n        }\n    }\n\n    return output;\n}\n```\n:::\n\n\n\n\n## The end result\n\nNow that we have both `decode()` and `encode()` implemented. We have a fully functioning\nbase64 encoder/decoder implemented in Zig. Here is an usage example of our\n`Base64` struct with the `encode()` and `decode()` methods that we have implemented.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar memory_buffer: [1000]u8 = undefined;\nvar fba = std.heap.FixedBufferAllocator.init(\n    &memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst text = \"Testing some more stuff\";\nconst etext = \"VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=\";\nconst base64 = Base64.init();\nconst encoded_text = try base64.encode(\n    allocator, text\n);\nconst decoded_text = try base64.decode(\n    allocator, etext\n);\ntry stdout.print(\n    \"Encoded text: {s}\\n\", .{encoded_text}\n);\ntry stdout.print(\n    \"Decoded text: {s}\\n\", .{decoded_text}\n);\n```\n:::\n\n\n\n```\nEncoded text: VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=\nDecoded text: Testing some more stuff\n```\n\nYou can also see the full source code at once, by visiting the official repository of this book[^repo].\nMore precisely inside the `ZigExamples` folder[^zig-base64-algo].\n\n[^repo]: <https://github.com/pedropark99/zig-book>\n",
+    "supporting": [
+      "01-base64_files"
+    ],
+    "filters": [
+      "rmarkdown/pagebreak.lua"
+    ],
+    "includes": {},
+    "engineDependencies": {
+      "knitr": [
+        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
+      ]
+    },
+    "preserve": null,
+    "postProcess": false
+  }
+}
\ No newline at end of file
diff --git a/_freeze/Chapters/01-memory/execute-results/epub.json b/_freeze/Chapters/01-memory/execute-results/epub.json
new file mode 100644
index 00000000..eda130d2
--- /dev/null
+++ b/_freeze/Chapters/01-memory/execute-results/epub.json
@@ -0,0 +1,21 @@
+{
+  "hash": "55899a376e1db53689b78790e55a518d",
+  "result": {
+    "engine": "knitr",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Memory and Allocators\n\n\nIn this chapter, we will talk about memory. How does Zig control memory? What\ncommon tools are used? Are there any important aspects that make memory\ndifferent/special in Zig? You will find the answers here.\n\nComputers fundamentally rely on memory to function. This memory acts as a temporary storage\nspace for the data and values generated during computations. Without memory, the core\nconcepts of \"variables\" and \"objects\" in programming languages would be impossible.\n\n\n\n\n## Memory spaces\n\nEvery object that you create in your Zig source code needs to be stored somewhere,\nin your computer's memory. Depending on where and how you define your object, Zig\nwill use a different \"memory space\", or a different\ntype of memory to store this object.\n\nEach type of memory normally serves for different purposes.\nIn Zig, there are 3 types of memory (or 3 different memory spaces) that we care about. They are:\n\n- Global data register (or the \"global data section\");\n- Stack;\n- Heap;\n\n\n### Compile-time known versus runtime known {#sec-compile-time}\n\nOne strategy that Zig uses to decide where it will store each object that you declare, is by looking\nat the value of this particular object. More specifically, by investigating if this value is\nknown at \"compile-time\" or at \"runtime\".\n\nWhen you write a program in Zig, the values of some of the objects that you write in your program are *known\nat compile time*. Meaning that, when you compile your Zig source code, during the compilation process,\nthe `zig` compiler can figure out the exact value of a particular object\nthat exists in your source code.\nKnowing the length (or the size) of each object is also important. So the length (or the size) of each object that you write in your program is,\nin some cases, *known at compile time*.\n\nThe `zig` compiler cares more about knowing the length (or the size) of a particular object\n, than to know its actual value. But, if the `zig` compiler knows the value of the object, then, it\nautomatically knows the size of this object. Because it can simply calculate the\nsize of the object by looking at the size of the value.\n\nTherefore, the priority for the `zig` compiler is to discover the size of each object in your source code.\nIf the value of the object in question is known at compile-time, then, the `zig` compiler\nautomatically knows the size/length of this object. But if the value of this object is not\nknown at compile-time, then, the size of this object is only known at compile-time if,\nand only if, the type of this object has a known fixed size.\n\nIn order for a type to have a known fixed size, this type must have data members whose size is fixed.\nIf this type includes, for example, a variable sized array in it, then, this type does not have a known\nfixed size. Because this array can have any size at runtime\n(i.e., it can be an array of 2 elements, or 50 elements, or 1 thousand elements, etc.).\n\nFor example, a string object, which internally is an array of constant u8 values (`[]const u8`)\nhas a variable size. It can be a string object with 100 or 500 characters in it. If we do not\nknow at compile-time, which exact string will be stored inside this string object, then, we cannot calculate\nthe size of this string object at compile-time. So, any type, or any struct declaration that you make, that\nincludes a string data member that does not have an explicit fixed size, makes this type, or this\nnew struct that you are declaring, a type that does not have a known fixed size at compile-time.\n\nIn contrast, if the type of this struct that you are declaring, includes a data member that is an array,\nbut this array has a known fixed size, like `[60]u8` (which declares an array of 60 `u8` values), then,\nthis type, or, this struct that you are declaring, becomes a type with a known fixed size at compile-time.\nAnd because of that, in this case, the `zig` compiler does not need to know at compile-time the exact value of\nany object of this type. Since the compiler can find the necessary size to store this object by\nlooking at the size of its type.\n\n\nLet's look at an example. In the source code below, we have two constant objects (`name` and `array`) declared.\nBecause the values of these particular objects are written down, in the source code itself (`\"Pedro\"`\nand the number sequence from 1 to 4), the `zig` compiler can easily discover the values of these constant\nobjects (`name` and `array`) during the compilation process.\nThis is what \"known at compile time\" means. It refers to any object that you have in your Zig source code\nwhose value can be identified at compile time.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn input_length(input: []const u8) usize {\n    const n = input.len;\n    return n;\n}\n\npub fn main() !void {\n    const name = \"Pedro\";\n    const array = [_]u8{1, 2, 3, 4};\n    _ = name; _ = array;\n}\n```\n:::\n\n\n\nThe other side of the spectrum are objects whose values are not known at compile time.\nFunction arguments are a classic example of this. Because the value of each function\nargument depends on the value that you assign to this particular argument,\nwhen you call the function.\n\nFor example, the function `input_length()` contains an argument named `input`, which is an array of constant `u8` integers (`[]const u8`).\nIt's impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length\nof this particular argument. Because it's an array that does not have a fixed size specified explicitly in the argument type annotation.\n\nSo, we know that this `input` argument will be an array of `u8` integers. But we do not know at compile-time, its value, and neither its size.\nThis information is known only at runtime, which is the period of time when you program is executed.\nAs a consequence, the value of the expression `input.len` is also known only at runtime.\nThis is an intrinsic characteristic of any function. Just remember that the value of function arguments is usually not \"compile-time known\".\n\nHowever, as I mentioned earlier, what really matters to the compiler is to know the size of the object\nat compile-time, and not necessarily its value. So, although we don't know the value of the object `n`, which is the result of the expression\n`input.len`, at compile-time, we do know its size. Because the expression `input.len` always returns a value of type `usize`,\nand the type `usize` has a known fixed size.\n\n\n\n### Global data register\n\nThe global data register is a specific section of the executable of your Zig program, that is responsible\nfor storing any value that is known at compile time.\n\nEvery constant object whose value is known at compile time that you declare in your source code,\nis stored in the global data register. Also, every literal value that you write in your source code,\nsuch as the string `\"this is a string\"`, or the integer `10`, or a boolean value such as `true`,\nis also stored in the global data register.\n\nHonestly, you don't need to care much about this memory space. Because you can't control it,\nyou can't deliberately access it or use it for your own purposes.\nAlso, this memory space does not affect the logic of your program.\nIt simply exists in your program.\n\n\n### Stack vs Heap\n\nIf you are familiar with systems programming, or just low-level programming in general, you\nprobably have heard of the \"duel\" between Stack vs Heap. These are two different types of memory,\nor different memory spaces, which are both available in Zig.\n\nThese two types of memory don't actually duel with\neach other. This is a common mistake that beginners have, when seeing \"x vs y\" styles of\ntabloid headlines. These two types of memory are actually complementary to each other.\nSo, in almost every Zig program that you ever write, you will likely use a combination of both.\nI will describe each memory space in detail over the next sections. But for now, I just want to\nstablish the main difference between these two types of memory.\n\nIn essence, the stack memory is normally used to store values whose length is fixed and known\nat compile time. In contrast, the heap memory is a *dynamic* type of memory space, meaning that, it's\nused to store values whose length might grow during the execution (runtime) of your program [@jenny2022].\n\nLengths that grow during runtime are intrinsically associated with \"runtime known\" type of values.\nIn other words, if you have an object whose length might grow during runtime, then, the length\nof this object becomes not known at compile time. If the length is not known at compile-time,\nthe value of this object also becomes not known at compile-time.\nThese types of objects should be stored in the heap memory space, which is\na dynamic memory space, which can grow or shrink to fit the size of your objects.\n\n\n\n### Stack {#sec-stack}\n\nThe stack is a type of memory that uses the power of the *stack data structure*, hence the name.\nA \"stack\" is a type of *data structure* that uses a \"last in, first out\" (LIFO) mechanism to store the values\nyou give it to. I imagine you are familiar with this data structure.\nBut, if you are not, the [Wikipedia page](https://en.wikipedia.org/wiki/Stack_(abstract_data_type))[^wiki-stack]\n, or, the [Geeks For Geeks page](https://www.geeksforgeeks.org/stack-data-structure/)[^geek-stack] are both\nexcellent and easy resources to fully understand how this data structure works.\n\n[^wiki-stack]: <https://en.wikipedia.org/wiki/Stack_(abstract_data_type)>\n[^geek-stack]: <https://www.geeksforgeeks.org/stack-data-structure/>\n\nSo, the stack memory space is a type of memory that stores values using a stack data structure.\nIt adds and removes values from the memory by following a \"last in, first out\" (LIFO) principle.\n\nEvery time you make a function call in Zig, an amount of space in the stack is\nreserved for this particular function call [@jenny2022; @zigdocs].\nThe value of each function argument given to the function in this function call is stored in this\nstack space. Also, every local object that you declare inside the function scope is\nusually stored in this same stack space.\n\n\nLooking at the example below, the object `result` is a local object declared inside the scope of the `add()`\nfunction. Because of that, this object is stored inside the stack space reserved for the `add()` function.\nThe `r` object (which is declared outside of the `add()` function scope) is also stored in the stack.\nBut since it's declared in the \"outer\" scope, this object is stored in the\nstack space that belongs to this outer scope.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn add(x: u8, y: u8) u8 {\n    const result = x + y;\n    return result;\n}\n\npub fn main() !void {\n    const r = add(5, 27);\n    _ = r;\n}\n```\n:::\n\n\n\n\nSo, any object that you declare inside the scope of a function is always stored inside\nthe space that was reserved for that particular function in the stack memory. This\nalso counts for any object declared inside the scope of your `main()` function for example.\nAs you would expect, in this case, they\nare stored inside the stack space reserved for the `main()` function.\n\nOne very important detail about the stack memory is that **it frees itself automatically**.\nThis is very important, remember that. When objects are stored in the stack memory,\nyou don't have the work (or the responsibility) of freeing/destroying these objects.\nBecause they will be automatically destroyed once the stack space is freed at the end of the function scope.\n\nSo, once the function call returns (or ends, if you prefer to call it this way)\nthe space that was reserved in the stack is destroyed, and all of the objects that were in that space goes away with it.\nThis mechanism exists because this space, and the objects within it, are not necessary anymore,\nsince the function \"finished its business\".\nUsing the `add()` function that we exposed above as an example, it means that the object `result` is automatically\ndestroyed once the function returns.\n\n::: {.callout-important}\nLocal objects that are stored in the stack space of a function are automatically\nfreed/destroyed at the end of the function scope.\n:::\n\n\nThis same logic applies to any other special structure in Zig that has its own scope by surrounding\nit with curly braces (`{}`).\nFor loops, while loops, if else statements, etc. For example, if you declare any local\nobject in the scope of a for loop, this local object is accessible only within the scope\nof this particular for loop. Because once the scope of this for loop ends, the space in the stack\nreserved for this for loop is freed.\nThe example below demonstrates this idea.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This does not compile successfully!\nconst a = [_]u8{0, 1, 2, 3, 4};\nfor (0..a.len) |i| {\n    const index = i;\n    _ = index;\n}\n// Trying to use an object that was\n// declared in the for loop scope,\n// and that does not exist anymore.\nstd.debug.print(\"{d}\\n\", .{index});\n```\n:::\n\n\n\n\n\nOne important consequence of this mechanism is that, once the function returns, you can no longer access any memory\naddress that was inside the space in the stack reserved for this particular function. Because this space was\ndestroyed. This means that, if this local object is stored in the stack,\nyou cannot make a function that **returns a pointer to this object**.\n\nThink about that for a second. If all local objects in the stack are destroyed at the end of the function scope, why\nwould you even consider returning a pointer to one of these objects? This pointer is at best,\ninvalid, or, more likely, \"undefined\".\n\nIn conclusion, it's totally fine to write a function that returns the local object\nitself as result, because then, you return the value of that object as the result.\nBut, if this local object is stored in the stack, you should never write a function\nthat returns a pointer to this local object. Because the memory address pointed by the pointer\nno longer exists.\n\n\nSo, using again the `add()` function as an example, if you rewrite this function so that it\nreturns a pointer to the local object `result`, the `zig` compiler will actually compile\nyour program, with no warnings or errors. At first glance, it looks like this is good code\nthat works as expected. But this is a lie!\n\nIf you try to take a look at the value inside of the `r` object,\nor, if you try to use this `r` object in another expression\nor function call, then, you would have undefined behaviour, and major\nbugs in your program [@zigdocs, see \"Lifetime and Ownership\"[^life] and \"Undefined Behaviour\"[^undef] sections].\n\n[^life]: <https://ziglang.org/documentation/master/#Lifetime-and-Ownership>\n[^undef]: <https://ziglang.org/documentation/master/#Undefined-Behavior>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn add(x: u8, y: u8) *const u8 {\n    const result = x + y;\n    return &result;\n}\n\npub fn main() !void {\n    // This code compiles successfully. But it has\n    // undefined behaviour. Never do this!!!\n    // The `r` object is undefined!\n    const r = add(5, 27); _ = r;\n}\n```\n:::\n\n\n\nThis \"invalid pointer to stack variable\" problem is well known across many programming language communities.\nIf you try to do the same thing, for example, in a C or C++ program (i.e., returning an address to\na local object stored in the stack), you would also get undefined behaviour\nin the program.\n\n::: {.callout-important}\nIf a local object in your function is stored in the stack, you should never\nreturn a pointer to this local object from the function. Because\nthis pointer will always become undefined after the function returns, since the stack space of the function\nis destroyed at the end of its scope.\n:::\n\nBut what if you really need to use this local object in some way after your function returns?\nHow can you do this? The answer is: \"in the same way you would do if this were a C or C++ program. By returning\nan address to an object stored in the heap\". The heap memory has a much more flexible lifecycle,\nand allows you to get a valid pointer to a local object of a function that already returned\nfrom its scope.\n\n\n### Heap {#sec-heap}\n\nOne important limitation of the stack, is that, only objects whose length/size is known at compile-time can be\nstored in it. In contrast, the heap is a much more dynamic\n(and flexible) type of memory. It's the perfect type of memory to use\nfor objects whose size/length might grow during the execution of your program.\n\nVirtually any application that behaves as a server is a classic use case of the heap.\nA HTTP server, a SSH server, a DNS server, a LSP server, ... any type of server.\nIn summary, a server is a type of application that runs for long periods of time,\nand that serves (or \"deals with\") any incoming request that reaches this particular server.\n\nThe heap is a good choice for this type of system, mainly because the server does not know upfront\nhow many requests it will receive from users, while it is active. It could be a single request,\n5 thousand requests, or even zero requests.\nThe server needs to have the ability to allocate and manage its memory according to how many requests it receives.\n\nAnother key difference between the stack and the heap, is that the heap is a type\nof memory that you, the programmer, have complete control over. This makes the heap a\nmore flexible type of memory, but it also makes it harder to work with. Because you,\nthe programmer, is responsible for managing everything related to it. Including where the memory is allocated,\nhow much memory is allocated, and where this memory is freed.\n\n> Unlike stack memory, heap memory is allocated explicitly by programmers and it won’t be deallocated until it is explicitly freed [@jenny2022].\n\nTo store an object in the heap, you, the programmer, needs to explicitly tells Zig to do so,\nby using an allocator to allocate some space in the heap. In @sec-allocators, I will present how you can use allocators to allocate memory\nin Zig.\n\n::: {.callout-important}\nEvery memory you allocate in the heap needs to be explicitly freed by you, the programmer.\n:::\n\nThe majority of allocators in Zig do allocate memory on the heap. But some exceptions to this rule are\n`ArenaAllocator()` and `FixedBufferAllocator()`. The `ArenaAllocator()` is a special\ntype of allocator that works in conjunction with a second type of allocator.\nOn the other side, the `FixedBufferAllocator()` is an allocator that works based on\nbuffer objects created on the stack. This means that the `FixedBufferAllocator()` makes\nallocations only on the stack.\n\n\n\n\n### Summary\n\nAfter discussing all of these boring details, we can quickly recap what we learned.\nIn summary, the Zig compiler will use the following rules to decide where each\nobject you declare is stored:\n\n1. every literal value (such as `\"this is string\"`, `10`, or `true`) is stored in the global data section.\n1. every constant object (`const`) whose value **is known at compile-time** is also stored in the global data section.\n1. every object (constant or not) whose length/size **is known at compile time** is stored in the stack space for the current scope.\n1. if an object is created with the method `alloc()` or `create()` of an allocator object, this object is stored in the memory space used by this particular allocator object. Most of allocators available in Zig use the heap memory, so, this object is likely stored in the heap (`FixedBufferAllocator()` is an exception to that).\n1. the heap can only be accessed through allocators. If your object was not created through the `alloc()` or `create()` methods of an allocator object, then, it is most certainly not an object stored in the heap.\n\n\n## Stack overflows {#sec-stack-overflow}\n\nAllocating memory on the stack is generally faster than allocating it on the heap.\nBut this better performance comes with many restrictions. We have already discussed\nmany of these restrictions of the stack in @sec-stack. But there is one more important\nlimitation that I want to talk about, which is the size of the stack itself.\n\nThe stack is limited in size. This size varies from computer to computer, and it depends on\na lot of things (the computer architecture, the operating system, etc.). Nevertheless, this size is usually\nnot that big. This is why we normally use the stack to store only temporary and small objects in memory.\n\nIn essence, if you try to make an allocation on the stack, that is so big that exceeds the stack size limit,\na *stack overflow* happens, and your program just crashes as a result of that. In other words, a stack overflow happens when\nyou attempt to use more space than is available on the stack.\n\nThis type of problem is very similar to a *buffer overflow*, i.e., you are trying to use more space\nthan is available in the \"buffer object\". However, a stack overflow always causes your program to crash,\nwhile a buffer overflow does not always cause your program to crash (although it often does).\n\nYou can see an example of a stack overflow in the example below. We are trying to allocate a very big array of `u64` values\non the stack. You can see below that this program does not run successfully, because it crashed\nwith a \"segmentation fault\" error message.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar very_big_alloc: [1000 * 1000 * 24]u64 = undefined;\n@memset(very_big_alloc[0..], 0);\n```\n:::\n\n\n\n```\nSegmentation fault (core dumped)\n```\n\nThis segmentation fault error is a result of the stack overflow that was caused by the big\nmemory allocation made on the stack, to store the `very_big_alloc` object.\nThis is why very big objects are usually stored on the heap, instead of the stack.\n\n\n\n## Allocators {#sec-allocators}\n\nOne key aspect about Zig, is that there are \"no hidden-memory allocations\" in Zig.\nWhat that really means, is that \"no allocations happen behind your back in the standard library\" [@zigguide].\n\nThis is a known problem, especially in C++. Because in C++, there are some operators that do allocate\nmemory behind the scene, and there is no way for you to know that, until you actually read the\nsource code of these operators, and find the memory allocation calls.\nMany programmers find this behaviour annoying and hard to keep track of.\n\nBut, in Zig, if a function, an operator, or anything from the standard library\nneeds to allocate some memory during its execution, then, this function/operator needs to receive (as input) an allocator\nprovided by the user, to actually be able to allocate the memory it needs.\n\nThis creates a clear distinction between functions that \"do not\" from those that \"actually do\"\nallocate memory. Just look at the arguments of this function.\nIf a function, or operator, has an allocator object as one of its inputs/arguments, then, you know for\nsure that this function/operator will allocate some memory during its execution.\n\nAn example is the `allocPrint()` function from the Zig Standard Library. With this function, you can\nwrite a new string using format specifiers. So, this function is, for example, very similar to the function `sprintf()` in C.\nIn order to write such a new string, the `allocPrint()` function needs to allocate some memory to store the\noutput string.\n\nThat is why, the first argument of this function is an allocator object that you, the user/programmer, gives\nas input to the function. In the example below, I am using the `GeneralPurposeAllocator()` as my allocator\nobject. But I could easily use any other type of allocator object from the Zig Standard Library.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst name = \"Pedro\";\nconst output = try std.fmt.allocPrint(\n    allocator,\n    \"Hello {s}!!!\",\n    .{name}\n);\ntry stdout.print(\"{s}\\n\", .{output});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello Pedro!!!\n```\n\n\n:::\n:::\n\n\n\n\nYou get a lot of control over where and how much memory this function can allocate.\nBecause it is you, the user/programmer, that provides the allocator for the function to use.\nThis makes \"total control\" over memory management easier to achieve in Zig.\n\n### What are allocators?\n\nAllocators in Zig are objects that you can use to allocate memory for your program.\nThey are similar to the memory allocating functions in C, like `malloc()` and `calloc()`.\nSo, if you need to use more memory than you initially have, during the execution of your program, you can simply ask\nfor more memory by using an allocator object.\n\nZig offers different types of allocators, and they are usually available through the `std.heap` module of\nthe standard library. Thus, just import the Zig Standard Library into your Zig module (with `@import(\"std\")`), and you can start\nusing these allocators in your code.\n\nFurthermore, every allocator object is built on top of the `Allocator` interface in Zig.\nThis means that, every allocator object you find in Zig must have the methods `alloc()`,\n`create()`, `free()` and `destroy()`. So, you can change the type of allocator you are using,\nbut you don't need to change the function calls to the methods that do the memory allocation\n(and the free memory operations) for your program.\n\n### Why you need an allocator?\n\nAs we described in @sec-stack, everytime you make a function call in Zig,\na space in the stack is reserved for this function call. But the stack\nhas a key limitation which is: every object stored in the stack has a\nknown fixed length.\n\nBut in reality, there are two very common instances where this \"fixed length limitation\" of the stack is a deal braker:\n\n1. the objects that you create inside your function might grow in size during the execution of the function.\n1. sometimes, it's impossible to know upfront how many inputs you will receive, or how big this input will be.\n\nAlso, there is another instance where you might want to use an allocator, which is when you want to write a function that returns a pointer\nto a local object. As I described in @sec-stack, you cannot do that if this local object is stored in the\nstack. However, if this object is stored in the heap, then, you can return a pointer to this object at the\nend of the function. Because you (the programmer) control the lifetime of any heap memory that you allocate. You decide\nwhen this memory gets destroyed/freed.\n\nThese are common situations for which the stack is not good.\nThat is why you need a different memory management strategy to\nstore these objects inside your function. You need to use\na memory type that can grow together with your objects, or that you\ncan control the lifetime of this memory.\nThe heap fits this description.\n\nAllocating memory on the heap is commonly known as dynamic memory management. As the objects you create grow in size\nduring the execution of your program, you grow the amount of memory\nyou have by allocating more memory in the heap to store these objects.\nAnd you do that in Zig, by using an allocator object.\n\n\n### The different types of allocators\n\n\nAt the moment of the writing of this book, in Zig, we have 6 different\nallocators available in the standard library:\n\n- `GeneralPurposeAllocator()`.\n- `page_allocator()`.\n- `FixedBufferAllocator()` and `ThreadSafeFixedBufferAllocator()`.\n- `ArenaAllocator()`.\n- `c_allocator()` (requires you to link to libc).\n\n\nEach allocator has its own perks and limitations. All allocators, except `FixedBufferAllocator()` and `ArenaAllocator()`,\nare allocators that use the heap memory. So any memory that you allocate with\nthese allocators, will be placed in the heap.\n\n### General-purpose allocators\n\nThe `GeneralPurposeAllocator()`, as the name suggests, is a \"general purpose\" allocator. You can use it for every type\nof task. In the example below, I'm allocating enough space to store a single integer in the object `some_number`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const some_number = try allocator.create(u32);\n    defer allocator.destroy(some_number);\n\n    some_number.* = @as(u32, 45);\n}\n```\n:::\n\n\n\n\nWhile useful, you might want to use the `c_allocator()`, which is a alias to the C standard allocator `malloc()`. So, yes, you can use\n`malloc()` in Zig if you want to. Just use the `c_allocator()` from the Zig standard library. However,\nif you do use `c_allocator()`, you must link to Libc when compiling your source code with the\n`zig` compiler, by including the flag `-lc` in your compilation process.\nIf you do not link your source code to Libc, Zig will not be able to find the\n`malloc()` implementation in your system.\n\n### Page allocator\n\nThe `page_allocator()` is an allocator that allocates full pages of memory in the heap. In other words,\nevery time you allocate memory with `page_allocator()`, a full page of memory in the heap is allocated,\ninstead of just a small piece of it.\n\nThe size of this page depends on the system you are using.\nMost systems use a page size of 4KB in the heap, so, that is the amount of memory that is normally\nallocated in each call by `page_allocator()`. That is why, `page_allocator()` is considered a\nfast, but also \"wasteful\" allocator in Zig. Because it allocates a big amount of memory\nin each call, and you most likely will not need that much memory in your program.\n\n### Buffer allocators\n\nThe `FixedBufferAllocator()` and `ThreadSafeFixedBufferAllocator()` are allocator objects that\nwork with a fixed sized buffer object at the back. In other words, they use a fixed sized buffer\nobject as the basis for the memory. When you ask these allocator objects to allocate some memory for you,\nthey are essentially reserving some amount of space inside this fixed sized buffer object for you to use.\n\nThis means that, in order to use these allocators, you must first create a buffer object in your code,\nand then, give this buffer object as an input to these allocators.\n\nThis also means that, these allocator objects can allocate memory both in the stack or in the heap.\nEverything depends on where the buffer object that you provide lives. If this buffer object lives\nin the stack, then, the memory allocated is \"stack-based\". But if it lives on the heap, then,\nthe memory allocated is \"heap-based\".\n\n\nIn the example below, I'm creating a `buffer` object on the stack that is 10 elements long.\nNotice that I give this `buffer` object to the `FixedBufferAllocator()` constructor.\nNow, because this `buffer` object is 10 elements long, this means that I am limited to this space.\nI cannot allocate more than 10 elements with this allocator object. If I try to\nallocate more than that, the `alloc()` method will return an `OutOfMemory` error value.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar buffer: [10]u8 = undefined;\nfor (0..buffer.len) |i| {\n    buffer[i] = 0; // Initialize to zero\n}\n\nvar fba = std.heap.FixedBufferAllocator.init(&buffer);\nconst allocator = fba.allocator();\nconst input = try allocator.alloc(u8, 5);\ndefer allocator.free(input);\n```\n:::\n\n\n\nRemember, the memory allocated by these allocator objects can be either from\nthe stack, or, from the heap. It all depends on where the buffer object that you provide lives.\nIn the above example, the `buffer` object lives in the stack, and, therefore, the memory allocated\nis based in the stack. But what if it was based on the heap?\n\nAs we described in @sec-stack-overflow, one of the main reasons why you would use the heap,\ninstead of the stack, is to allocate huge amounts of space to store very big objects.\nThus, let's suppose you wanted to use a very big buffer object as the basis for your\nallocator objects. You would have to allocate this very big buffer object on the heap.\nThe example below demonstrates this case.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst heap = std.heap.page_allocator;\nconst memory_buffer = try heap.alloc(\n    u8, 100 * 1024 * 1024 // 100 MB memory\n);\ndefer heap.free(memory_buffer);\nvar fba = std.heap.FixedBufferAllocator.init(\n    memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst input = try allocator.alloc(u8, 1000);\ndefer allocator.free(input);\n```\n:::\n\n\n\n\n\n### Arena allocator {#sec-arena-allocator}\n\nThe `ArenaAllocator()` is an allocator object that takes a child allocator as input. The idea behind the `ArenaAllocator()` in Zig\nis similar to the concept of \"arenas\" in the programming language Go[^go-arena]. It's an allocator object that allows you\nto allocate memory as many times you want, but free all memory only once.\nIn other words, if you have, for example, called 5 times the method `alloc()` of an `ArenaAllocator()` object, you can\nfree all the memory you allocated over these 5 calls at once, by simply calling the `deinit()` method of the same `ArenaAllocator()` object.\n\n[^go-arena]: <https://go.dev/src/arena/arena.go>\n\nIf you give, for example, a `GeneralPurposeAllocator()` object as input to the `ArenaAllocator()` constructor, like in the example below, then, the allocations\nyou perform with `alloc()` will actually be made with the underlying object `GeneralPurposeAllocator()` that was passed.\nSo, with an arena allocator, any new memory you ask for is allocated by the child allocator. The only thing that an arena allocator\nreally does is help you to free all the memory you allocated multiple times with just a single command. In the example\nbelow, I called `alloc()` 3 times. So, if I did not use an arena allocator, then, I would need to call\n`free()` 3 times to free all the allocated memory.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nvar aa = std.heap.ArenaAllocator.init(gpa.allocator());\ndefer aa.deinit();\nconst allocator = aa.allocator();\n\nconst in1 = try allocator.alloc(u8, 5);\nconst in2 = try allocator.alloc(u8, 10);\nconst in3 = try allocator.alloc(u8, 15);\n_ = in1; _ = in2; _ = in3;\n```\n:::\n\n\n\n\n\n### The `alloc()` and `free()` methods\n\nIn the code example below, we are accessing the `stdin`, which is\nthe standard input channel, to receive an input from the\nuser. We read the input given by the user with the `readUntilDelimiterOrEof()`\nmethod.\n\nNow, after reading the input of the user, we need to store this input somewhere in\nour program. That is why I use an allocator in this example. I use it to allocate some\namount of memory to store this input given by the user. More specifically, the method `alloc()`\nof the allocator object is used to allocate an array capable of storing 50 `u8` values.\n\nNotice that this `alloc()` method receives two inputs. The first one, is a type.\nThis defines what type of values the allocated array will store. In the example\nbelow, we are allocating an array of unsigned 8-bit integers (`u8`). But\nyou can create an array to store any type of value you want. Next, in the second argument, we\ndefine the size of the allocated array, by specifying how many elements\nthis array will contain. In the case below, we are allocating an array of 50 elements.\n\nIn @sec-zig-strings we described that strings in Zig are simply arrays of characters.\nEach character is represented by a `u8` value. So, this means that the array that\nwas allocated in the object `input` is capable of storing a string that is\n50-characters long.\n\nSo, in essence, the expression `var input: [50]u8 = undefined` would create\nan array for 50 `u8` values in the stack of the current scope. But, you\ncan allocate the same array in the heap by using the expression `var input = try allocator.alloc(u8, 50)`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdin = std.io.getStdIn();\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var input = try allocator.alloc(u8, 50);\n    defer allocator.free(input);\n    for (0..input.len) |i| {\n        input[i] = 0; // initialize all fields to zero.\n    }\n    // read user input\n    const input_reader = stdin.reader();\n    _ = try input_reader.readUntilDelimiterOrEof(\n        input,\n        '\\n'\n    );\n    std.debug.print(\"{s}\\n\", .{input});\n}\n```\n:::\n\n\n\nAlso, notice that in this example, we use the `defer` keyword (which I described in @sec-defer) to run a small\npiece of code at the end of the current scope, which is the expression `allocator.free(input)`.\nWhen you execute this expression, the allocator will free the memory that it allocated\nfor the `input` object.\n\nWe have talked about this in @sec-heap. You **should always** explicitly free any memory that you allocate\nusing an allocator! You do that by using the `free()` method of the same allocator object you\nused to allocate this memory. The `defer` keyword is used in this example only to help us execute\nthis free operation at the end of the current scope.\n\n\n### The `create()` and `destroy()` methods\n\nWith the `alloc()` and `free()` methods, you can allocate memory to store multiple elements\nat once. In other words, with these methods, we always allocate an array to store multiple elements at once.\nBut what if you need enough space to store just a single item? Should you\nallocate an array of a single element through `alloc()`?\n\nThe answer is no! In this case,\nyou should use the `create()` method of the allocator object.\nEvery allocator object offers the `create()` and `destroy()` methods,\nwhich are used to allocate and free memory for a single item, respectively.\n\nSo, in essence, if you want to allocate memory to store an array of elements, you\nshould use `alloc()` and `free()`. But if you need to store just a single item,\nthen, the `create()` and `destroy()` methods are ideal for you.\n\nIn the example below, I'm defining a struct to represent an user of some sort.\nIt could be a user for a game, or software to manage resources, it doesn't mater.\nNotice that I use the `create()` method this time, to store a single `User` object\nin the program. Also notice that I use the `destroy()` method to free the memory\nused by this object at the end of the scope.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst User = struct {\n    id: usize,\n    name: []const u8,\n\n    pub fn init(id: usize, name: []const u8) User {\n        return .{ .id = id, .name = name };\n    }\n};\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const user = try allocator.create(User);\n    defer allocator.destroy(user);\n\n    user.* = User.init(0, \"Pedro\");\n}\n```\n:::\n",
+    "supporting": [
+      "01-memory_files"
+    ],
+    "filters": [
+      "rmarkdown/pagebreak.lua"
+    ],
+    "includes": {},
+    "engineDependencies": {
+      "knitr": [
+        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
+      ]
+    },
+    "preserve": null,
+    "postProcess": false
+  }
+}
\ No newline at end of file
diff --git a/_freeze/Chapters/01-zig-weird/execute-results/epub.json b/_freeze/Chapters/01-zig-weird/execute-results/epub.json
new file mode 100644
index 00000000..6385ce4f
--- /dev/null
+++ b/_freeze/Chapters/01-zig-weird/execute-results/epub.json
@@ -0,0 +1,21 @@
+{
+  "hash": "4d435d48922c81726d4668b9e1fc1e4f",
+  "result": {
+    "engine": "knitr",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\nlanguage, it's still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. Sometimes, they really make it hard to debug\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscure the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that gets compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e., where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contains Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nWe can use this build system to write small scripts in Zig,\nwhich describe the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e., creating new objects)\nare made in Zig. You can create a new object in Zig by using the syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). In @sec-assignments we talk more about objects in general.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that in @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIt's worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt's like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portable C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nIn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e., the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. If you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith an \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, on Windows, operations like accessing the `stdout` (or opening a file) depend on\nresources that are available only at *runtime* (you will learn more about compile-time versus runtime\nin @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerges from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword in @sec-comptime.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation in a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues\n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described in @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig later in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig?\nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar to our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentation.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It's a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (on YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e., identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nSo, if you want to change the value of your object, you need to transform your immutable (or \"constant\")\nobject into a mutable (or \"variable\") object. You can do that by using the `var` keyword.\nThis keyword stands for \"variable\", and when you apply this keyword to some object, you are\ntelling the Zig compiler that the value associated with this object might change at some point.\n\nThus, if we come back to the previous example, and change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it's a \"variable object\".\n\nHowever, if you take a look at the example below, you will notice that we have not only declared the\n`age` object with the `var` keyword, but we also have explicitly annotated the data type\nof the `age` object with the `u8` type this time. The basic idea is, when we use a variable/mutable object,\nthe Zig compiler ask for us to be more explicit with what we want, to be more clear\nabout what our code does. This translates into being more explicit about the data types that we want\nto use in our objects.\n\nTherefore, if you transform your object into a variable/mutable object, just remember to always\nannotate the type of the object explicitly in your code. Otherwise, the Zig compiler might raise\na compilation error, asking you to transform your object back into a `const` object, or,\nto give your object an \"explicit type\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIt's important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code uses this object while it's uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object.\n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e., if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to a special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It's discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also gets discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig has many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e., the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\nIt's worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it has the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it's a slice that\naccesses all elements in the array.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhas 2 elements in it.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" in @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth in @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially in @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned in @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e., both the start and the end of this range)\nis known at compile-time, the slice object that gets created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nin @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that gets created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e., a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can\ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice has a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n_ = slice;\n```\n:::\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat gets created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, we are reading a file, and then, we try to create a slice object\nthat covers the entire buffer that contains the contents of this file. This is obviously\nan example of a runtime known range, because the end index of the range\nis not known at compile time.\n\nIn other words, the end index of the range is the size of\nthe array `file_contents`. However, the size of `file_contents` is not known at compile time.\nBecause we don't know how many bytes are stored inside this `shop-list.txt` file.\nAnd because this is a file, someone might edit this file tomorrow and add more lines\nor remove lines from it. Therefore, the size of this file might vary drastically from one execution to another.\n\nNow, if the file size can vary from one run to another, then, we can conclude that the value of the expression\n`file_contents.len` exposed in the example below can also vary from one run to another. As consequence,\nthe value of the expression `file_contents.len` is runtime-known only, and, as a consequence of that,\nthe range `0..file_contents.len` is also runtime-known only.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\nfn read_file(allocator: std.mem.Allocator, path: []const u8) ![]u8 {\n    const file = try std.fs.cwd().openFile(path, .{});\n    defer file.close();\n    return try file.reader().readAllAlloc(\n        allocator, std.math.maxInt(usize)\n    );\n}\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const path = \"../ZigExamples/file-io/shop-list.txt\";\n    const file_contents = try read_file(allocator, path);\n    const slice = file_contents[0..file_contents.len];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code has its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e., a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nStrings in Zig work very similarly to strings in C, but they come with some extra caveats which adds more safety\nand efficiency to them. You could also say that Zig simply uses a more modern and safe approach to manage\nand use strings.\n\nA string in Zig is essentially an array of arbitrary bytes, or, more specifically, an array of `u8` values.\nThis very similar to a string in C, which is also interpreted as an array of arbitrary bytes, or, in the case\nof C, an array of `char` (which usually represents an unsigned 8-bit integer value in most systems) values.\n\nNow, because a string in Zig is an array, you automatically\nget the length of the string (i.e. the length of the array) embedded in the value itself. This makes\nall the difference! Because now, the Zig compiler can use the length value that is embedded in the string to\ncheck for \"buffer overflow\" or \"wrong memory access\" problems in your code.\n\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need to do something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible in the string value itself. You can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\nAnother point is that Zig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e., a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\n### Using a slice versus a sentinel-terminated array\n\nIn memory, all string values in Zig are always stored in the same way.\nThey are simply stored as sequences/arrays of arbitrary bytes. But you can use and access\nthis sequence of bytes in two different ways. You can access this sequence of bytes as:\n\n- a sentinel-terminated array of `u8` values.\n- or as a slice of `u8` values.\n\n\n#### Sentinel-terminated arrays\n\nSentinel-terminated arrays in Zig are described in the Language Reference of Zig[^sentinel].\nIn summary a sentinel-terminated array is just a normal array, but, the difference is that they\ncontain a \"sentinel value\" at the last index/element of the array. With a sentinel-terminated array\nyou embed both the length of the array, and also, the sentinel value in the type itself of your object.\n\n[^sentinel]: <https://ziglang.org/documentation/master/#Sentinel-Terminated-Arrays>.\n\nFor example, if you write a string literal value in your code, and ask Zig to print the data type of this value,\nyou usually get a data type in the format `*const [n:0]u8`. The `n` in the data type indicates the size of\nthe string (that is the length of the array). The zero after the `n:` part of the data type is the sentinel\nvalue itself.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n_ = \"A literal value\";\ntry stdout.print(\"{any}\\n\", .{@TypeOf(\"A literal value\")});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n*const [15:0]u8\n```\n\n\n:::\n:::\n\n\n\n\nSo, with this data type `*const [n:0]u8` you are essentially saying that you have an array of `u8` values\nof length `n`, where, the element at the index corresponding to the length `n` in the array is the\nnumber zero. If you really think about this description, you will notice that this is just a fancy way to\ndescribe a string in C, which is a null-terminated array of bytes. The `NULL` value in C is the number\nzero. So, an array that ends in a null/zero value in C is essentially a sentinel-terminated array in Zig,\nwhere the sentinel value of the array is the number zero.\n\nTherefore, a string literal value in Zig is just a pointer to a null-terminated array of bytes (i.e., similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string, and also, the fact that they are \"NULL terminated\",\ninto the data type of the value itself.\n\n\n\n#### Slice\n\nYou can also access and use the arbitrary sequence of bytes that represent your string as a slice of `u8` values.\nThe majority of functions from the Zig standard library usually receive strings as inputs as slices of\n`u8` values (slices were presented in @sec-arrays).\n\nThus, you will see a lot of string values with a data type of `[]u8` or `[]const u8`, depending if the object\nwhere this string is stored is marked as constant with `const`, or as variable with `var`. Now, because\nthe string in this case is being interpreted as a slice, this slice is not necessarilly null-terminated,\nbecause now, the sentinel value is not mandatory. You can include the null/zero value in the slice if you\nwant to, but there is no need to do it.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string value being\n// interpreted as a slice.\nconst str: []const u8 = \"A string value\";\ntry stdout.print(\"{any}\\n\", .{@TypeOf(str)});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n[]const u8\n```\n\n\n:::\n:::\n\n\n\n\n\n### Iterating through the string\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below,\nand also, you can see that this is a null-terminated array, because of the zero value after the `:` character in the data type.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it's a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n:::\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIt's important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop through the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig in @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers in @sec-root-file and especially in @sec-assignments.\n- How strings work in Zig in @sec-zig-strings.\n- How to use arrays and slices in @sec-arrays.\n- How to import functionality from other Zig modules in @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* in @sec-structs-and-oop.\n- Basic control flow syntax in @sec-zig-control-flow.\n- Enums in @sec-enum;\n- Pointers and Optionals in @sec-pointer;\n- Error handling with `try` and `catch` in @sec-error-handling;\n- Unit tests in @sec-unittests;\n- Vectors in @sec-vectors-simd;\n- Build System in @sec-build-system;\n",
+    "supporting": [
+      "01-zig-weird_files"
+    ],
+    "filters": [
+      "rmarkdown/pagebreak.lua"
+    ],
+    "includes": {},
+    "engineDependencies": {
+      "knitr": [
+        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
+      ]
+    },
+    "preserve": null,
+    "postProcess": false
+  }
+}
\ No newline at end of file
diff --git a/_freeze/Chapters/02-debugging/execute-results/epub.json b/_freeze/Chapters/02-debugging/execute-results/epub.json
new file mode 100644
index 00000000..933510c4
--- /dev/null
+++ b/_freeze/Chapters/02-debugging/execute-results/epub.json
@@ -0,0 +1,21 @@
+{
+  "hash": "f6eea7230762e3b8cde487458c00b745",
+  "result": {
+    "engine": "knitr",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Debugging Zig applications\n\nBeing able to debug your applications is essential for any programmer who wants to\ndo serious programming in any language. That is why, in this chapter, we are going to talk about the\navailable strategies and tools to debug applications written in Zig.\n\n\n## Print debugging\n\nWe begin with the classic and battle-tested *print debugging* strategy.\nThe key advantage that debugging offers you is *visibility*.\nWith *print statements* you can easily see what results and objects\nare being produced by your application.\n\nThis is the essence of *print debugging* - using\nprint expressions to see the values that are being generated by your program,\nand, as a result, get a much better understanding of how your program\nis behaving.\n\nMany programmers often resort to the print functions in Zig, such as the `stdout.print()`,\nor, the `std.debug.print()`, to get a better understanding of their programs.\nThis is a known and old strategy that is very simple and effective, and it's better known within\nthe programming community as *print debugging*.\nIn Zig, you can print information to the `stdout` or `stderr` streams of your system.\n\nLet's begin with `stdout`. First, you\nneed to get access to the `stdout`, by calling the `getStdOut()` method, from\nthe Zig Standard Library. This method returns a *file descriptor* object,\nand, through this object you can read/write to the `stdout`.\nI recommend you to check out all methods available in this object, by [checking the page in\nthe Zig Standard Library Official Reference for the type `File`](https://ziglang.org/documentation/master/std/#std.fs.File)[^zig-fiile-reference].\n\n[^zig-fiile-reference]: <https://ziglang.org/documentation/master/std/#std.fs.File>.\n\nFor our purpose here, which is to write something to the `stdout`, especially to debug our\nprogram, I recommend you to use the `writer()` method, which gives you a *writer* object.\nThis *writer* object offers some helper methods to write stuff into the file descriptor object\nthat represents the `stdout` stream. In special, the `print()` method.\n\n\nThe `print()` method from this *writer* object is a \"print formatter\" type of a function.\nIn other words, this method works exactly like the `printf()` function from C,\nor, like `println!()` from Rust.\nIn the first argument of the function, you specify a template string, and,\nin the second argument, you provide a list of values (or objects) that you want to insert\ninto your template message.\n\nIdeally, the template string in the first argument should contain some format specifier.\nEach format specifier is matched to a value (or object) that you have listed in the second argument.\nSo, if you provided 5 different objects in the second argument, then, the template string\nshould contain 5 format specifiers, one for each object provided.\n\nEach format specifier is represented by a single letter, and\nyou provide this format specifier inside a pair of curly braces. So, if you want to format\nyour object using the string specifier (`s`), then, you can insert the text `{s}` in your template string.\nHere is a quick list of the most used format specifiers:\n\n- `d`: for printing integers and floating-point numbers.\n- `c`: for printing characters.\n- `s`: for printing strings.\n- `p`: for printing memory addresses.\n- `x`: for printing hexadecimal values.\n- `any`: use any compatible format specifier (i.e., it automatically selects a format specifier for you).\n\nThe code example below gives you an example of use of this `print()` method\nwith the `d` format specifier.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    try stdout.print(\"Result: {d}\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\n\nIt's important to emphasize that, the `stdout.print()` method, as you would expect,\nprints your template string into the `stdout` stream of your system.\nHowever, you can also print your template string into the `stderr` stream\nif your prefer. All you need to do, is to replace the `stdout.print()`\ncall with the function `std.debug.print()`. Like this:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    std.debug.print(\"Result: {d}\\n\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\n\n\nYou could also achieve the exact same result by getting a file descriptor object to `stderr`,\nthen, creating a *writer* object to `stderr`, then, using the `print()` method of this\n*writer* object, like in the example below:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stderr = std.io.getStdErr().writer();\n// some more lines ...\ntry stderr.print(\"Result: {d}\", .{result});\n```\n:::\n\n\n\n\n\n## Debugging through debuggers\n\nAlthough *print debugging* is a valid and very useful strategy,\nmost programmers prefer to use a debugger to debug their programs.\nSince Zig is a low-level language, you can use either GDB (GNU Debugger),\nor LLDB (LLVM Project Debugger) as your debugger.\n\nBoth debuggers can work with Zig code, and it's a matter of taste here.\nYou choose the debugger of your preference, and you work with it.\nIn this book, I will use LLDB as my debugger in the examples.\n\n\n### Compile your source code in debug mode {#sec-compile-debug-mode}\n\nIn order to debug your program through a debugger, you must compile\nyour source code in `Debug` mode. Because when you compile your\nsource code in other modes (such as `Release`), the compiler usually\nstrips out some essential information that is used by the debugger\nto read and track your program, like PDB (*Program Database*) files.\n\nBy compiling your source code in `Debug` mode, you ensure that the debugger\nwill find the necessary information in your program to debug it.\nBy default, the compiler uses the `Debug` mode when compiling your code.\nHaving this in mind, when you compile your program with the `build-exe`\ncommand (which was described in @sec-compile-code), if you don't specify\nan explicit mode through the `-O` command-line [^oargument]\nargument, then, the compiler will compile your code in `Debug` mode.\n\n[^oargument]: See <https://ziglang.org/documentation/master/#Debug>.\n\n\n### Let's debug a program\n\nAs an example, let's use LLDB to navigate and investigate the following\npiece of Zig code:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\nfn add_and_increment(a: u8, b: u8) u8 {\n    const sum = a + b;\n    const incremented = sum + 1;\n    return incremented;\n}\n\npub fn main() !void {\n    var n = add_and_increment(2, 3);\n    n = add_and_increment(n, n);\n    try stdout.print(\"Result: {d}!\\n\", .{n});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 13!\n```\n\n\n:::\n:::\n\n\n\nThere is nothing wrong with this program. But it's\na good start for us. First, we need to compile\nthis program with the `zig build-exe` command.\nFor this example, suppose that I have compiled the above\nZig code into a binary executable called `add_program`.\n\n```bash\nzig build-exe add_program.zig\n```\n\nNow, we can start LLDB with `add_program`, like this:\n\n```bash\nlldb add_program\n```\n\nFrom now on, LLDB is started, and you can know that I'm\nexecuting LLDB commands by looking at the prefix `(lldb)`.\nIf something is prefixed with `(lldb)`, then you know\nthat it's a LLDB command.\n\nThe first thing I will do, is to set a breakpoint at\nthe `main()` function, by executing `b main`.\nAfter that, I just start the execution of the program\nwith `run`.\nYou can see in the output below, that the execution\nstopped at the first line in the function `main()`, as we expected.\n\n```bash\n(lldb) b main\nBreakpoint 1: where = debugging`debug1.main + 22\n    at debug1.zig:11:30, address = 0x00000000010341a6\n(lldb) run\nProcess 8654 launched: 'add_program' (x86_64)\nProcess 8654 stopped\n* thread #1, name = 'add_program',\n    stop reason = breakpoint 1.1 frame #0: 0x10341a6\n    add_program`debug1.main at add_program.zig:11:30\n   8   \t}\n   9\n   10  \tpub fn main() !void {\n-> 11  \t    var n = add_and_increment(2, 3);\n   12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n```\n\nI can start navigating through the code, and checking the objects\nthat are being generated. If you are not familiar with the commands\navailable in LLDB, I recommend you to read the official documentation\nof the project[^lldb].\nYou can also look for cheat sheets, which quickly describes all commands\navailable for you[^lldb-quick-list].\n\n[^lldb]: <https://lldb.llvm.org/>\n[^lldb-quick-list]: <https://gist.github.com/ryanchang/a2f738f0c3cc6fbd71fa>.\n\nCurrently, we are in the first line at the `main()` function. In this line, we create\nthe `n` object, by executing the `add_and_increment()` function.\nTo execute the current line of code, and go to the next line, we can\nrun the `n` LLDB command. Let's execute this command.\n\nAfter we executed this line, we can also look at the value stored inside this `n` object\nby using the `p` LLDB command. The syntax for this command is `p <name-of-object>`.\n\nIf we take a look at the value stored in the `n` object (`p n`),\nnotice that it stores the hexadecimal value `0x06`, which\nis the number 6 in decimal. We can also see that this value has a type of `unsigned char`,\nwhich is an unsigned 8-bit integer.\nWe have talked already about this in @sec-zig-strings, that `u8` integers in Zig are equivalent\nto the C data type `unsigned char`.\n\n\n\n```bash\n(lldb) n\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step over frame #0: 0x10341ae\n    debugging`debug1.main at debug1.zig:12:26\n   9\n   10  \tpub fn main() !void {\n   11  \t    var n = add_and_increment(2, 3);\n-> 12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n(lldb) p n\n(unsigned char) $1 = '\\x06'\n```\n\nNow, on the next line of code, we are executing the `add_and_increment()` function once again.\nWhy not step inside this function? Shall we? We can do that, by executing the `s` LLDB command.\nNotice in the example below that, after executing this command, we have entered into the context of the\n`add_and_increment()` function.\n\nAlso notice in the example below that, I have walked two more lines in the function's body, then,\nI execute the `frame variable` LLDB command, to see at once, the value stored in each of the variables\nthat were created inside the current scope.\n\nYou can see in the output below that, the object `sum` stores the value `\\f`,\nwhich represents the *form feed* character. This character in the ASCII table,\ncorresponds to the hexadecimal value `0x0C`, or, in decimal, the number 12.\nSo, this means that the result of the expression `a + b` executed at line\n5, resulted in the number 12.\n\n```bash\n(lldb) s\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step in frame #0: 0x10342de\n    debugging`debug1.add_and_increment(a='\\x02', b='\\x03')\n    at debug1.zig:4:39\n-> 4   \tfn add_and_increment(a: u8, b: u8) u8 {\n   5   \t    const sum = a + b;\n   6   \t    const incremented = sum + 1;\n   7   \t    return incremented;\n(lldb) n\n(lldb) n\n(lldb) frame variable\n(unsigned char) a = '\\x06'\n(unsigned char) b = '\\x06'\n(unsigned char) sum = '\\f'\n(unsigned char) incremented = '\\x06'\n```\n\n\n\n## How to investigate the data type of your objects\n\nSince Zig is a strongly-typed language, the data types associated with your objects\nare very important for your program. So, debugging the data types associated\nwith your objects might be important to understand bugs and errors in your program.\n\nWhen you walk through your program with a debugger, you can inspect the types of\nyour objects by simply printing them to the console, with the LLDB `p` command.\nBut you also have alternatives embedded in the language itself to access the data\ntypes of your objects.\n\nIn Zig, you can retrieve the data type of an object, by using the built-in function\n`@TypeOf()`. Just apply this function over the object, and you get access to\nthe data type of the object.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst expect = std.testing.expect;\n\npub fn main() !void {\n    const number: i32 = 5;\n    try expect(@TypeOf(number) == i32);\n    try stdout.print(\"{any}\\n\", .{@TypeOf(number)});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ni32\n```\n\n\n:::\n:::\n\n\n\nThis function is similar to the `type()` built-in function from Python,\nor, the `typeof` operator in Javascript.\n",
+    "supporting": [
+      "02-debugging_files"
+    ],
+    "filters": [
+      "rmarkdown/pagebreak.lua"
+    ],
+    "includes": {},
+    "engineDependencies": {
+      "knitr": [
+        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
+      ]
+    },
+    "preserve": null,
+    "postProcess": false
+  }
+}
\ No newline at end of file
diff --git a/_freeze/Chapters/03-structs/execute-results/epub.json b/_freeze/Chapters/03-structs/execute-results/epub.json
new file mode 100644
index 00000000..7b1a937c
--- /dev/null
+++ b/_freeze/Chapters/03-structs/execute-results/epub.json
@@ -0,0 +1,21 @@
+{
+  "hash": "eb1d22d8dc0121e7c7768b70c606a801",
+  "result": {
+    "engine": "knitr",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Control flow, structs, modules and types\n\nWe have discussed a lot of Zig's syntax in the last chapter,\nespecially in @sec-root-file and @sec-main-file.\nBut we still need to discuss some other very important\nelements of the language. Elements that you will use constantly on your day-to-day\nroutine.\n\nWe begin this chapter by discussing the different keywords and structures\nin Zig related to control flow (e.g. loops and if statements).\nThen, we talk about structs and how they can be used to do some\nbasic Object-Oriented (OOP) patterns in Zig. We also talk about\ntype inference and type casting.\nFinally, we end this chapter by discussing modules, and how they relate\nto structs.\n\n\n\n## Control flow {#sec-zig-control-flow}\n\nSometimes, you need to make decisions in your program. Maybe you need to decide\nwhether or not to execute a specific piece of code. Or maybe,\nyou need to apply the same operation over a sequence of values. These kinds of tasks,\ninvolve using structures that are capable of changing the \"control flow\" of our program.\n\nIn computer science, the term \"control flow\" usually refers to the order in which expressions (or commands)\nare evaluated in a given language or program. But this term is also used to refer\nto structures that are capable of changing this \"evaluation order\" of the commands\nexecuted by a given language/program.\n\nThese structures are better known\nby a set of terms, such as: loops, if/else statements, switch statements, among others. So,\nloops and if/else statements are examples of structures that can change the \"control\nflow\" of our program. The keywords `continue` and `break` are also examples of symbols\nthat can change the order of evaluation, since they can move our program to the next iteration\nof a loop, or make the loop stop completely.\n\n\n### If/else statements\n\nAn if/else statement performs a \"conditional flow operation\".\nA conditional flow control (or choice control) allows you to execute\nor ignore a certain block of commands based on a logical condition.\nMany programmers and computer science professionals also use\nthe term \"branching\" in this case.\nIn essence, an if/else statement allow us to use the result of a logical test\nto decide whether or not to execute a given block of commands.\n\nIn Zig, we write if/else statements by using the keywords `if` and `else`.\nWe start with the `if` keyword followed by a logical test inside a pair\nof parentheses, followed by a pair of curly braces which contains the lines\nof code to be executed in case the logical test returns the value `true`.\n\nAfter that, you can optionally add an `else` statement. To do that, just add the `else`\nkeyword followed by a pair of curly braces, with the lines of code\nto executed in case the logical test defined at `if` returns `false`.\n\nIn the example below, we are testing if the object `x` contains a number\nthat is greater than 10. Judging by the output printed to the console,\nwe know that this logical test returned `false`. Because the output\nin the console is compatible with the line of code present in the\n`else` branch of the if/else statement.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x = 5;\nif (x > 10) {\n    try stdout.print(\n        \"x > 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x <= 10!\\n\", .{}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nx <= 10!\n```\n\n\n:::\n:::\n\n\n\n\n\n### Switch statements {#sec-switch}\n\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust.\nAs you would expect, to write a switch statement in Zig we use the `switch` keyword.\nWe provide the value that we want to \"switch over\" inside a\npair of parentheses. Then, we list the possible combinations (or \"branches\")\ninside a pair of curly braces.\n\nLet's take a look at the code example below. You can see that\nI'm creating an enum type called `Role`. We talk more about enums in @sec-enum.\nBut in summary, this `Role` type is listing different types of roles in a fictitious\ncompany, like `SE` for Software Engineer, `DE` for Data Engineer, `PM` for Product Manager,\netc.\n\nNotice that we are using the value from the `role` object in the\nswitch statement, to discover which exact area we need to store in the `area` variable object.\nAlso notice that we are using type inference inside the switch statement, with the dot character,\nas we are going to describe in @sec-type-inference.\nThis makes the `zig` compiler infer the correct data type of the values (`PM`, `SE`, etc.) for us.\n\nAlso notice that, we are grouping multiple values in the same branch of the switch statement.\nWe just separate each possible value with a comma. For example, if `role` contains either `DE` or `DA`,\nthe `area` variable would contain the value `\"Data & Analytics\"`, instead of `\"Platform\"` or `\"Sales\"`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO => {\n            area = \"Platform\";\n        },\n        .DE, .DA => {\n            area = \"Data & Analytics\";\n        },\n        .KS => {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nPlatform\n```\n\n\n:::\n:::\n\n\n\n\n#### Switch statements must exhaust all possibilities\n\nOne very important aspect about switch statements in Zig\nis that they must exhaust all existing possibilities.\nIn other words, all possible values that could be found inside the `role`\nobject must be explicitly handled in this switch statement.\n\nSince the `role` object has type `Role`, the only possible values to\nbe found inside this object are `PM`, `SE`, `DPE`, `PO`, `DE`, `DA` and `KS`.\nThere are no other possible values to be stored in this `role` object.\nThus, the switch statements must have a combination (branch) for each one of these values.\nThis is what \"exhaust all existing possibilities\" means. The switch statement covers\nevery possible case.\n\nTherefore, you cannot write a switch statement in Zig, and leave an edge case\nwith no explicit action to be taken.\nThis is a similar behaviour to switch statements in Rust, which also have to\nhandle all possible cases.\n\n\n\n#### The else branch\n\nTake a look at the `dump_hex_fallible()` function below as an example. This function\ncomes from the Zig Standard Library. More precisely, from the\n[`debug.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/debug.zig)[^debug-mod].\nThere are multiple lines in this function, but I omitted them to focus solely on the\nswitch statement found in this function. Notice that this switch statement has four\npossible cases (i.e., four explicit branches). Also, notice that we used an `else` branch\nin this case.\n\nAn `else` branch in a switch statement works as the \"default branch\".\nWhenever you have multiple cases in your switch statement where\nyou want to apply the exact same action, you can use an `else` branch to do that.\n\n[^debug-mod]: <https://github.com/ziglang/zig/blob/master/lib/std/debug.zig>\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' => try writer.writeAll(\"␊\"),\n        '\\r' => try writer.writeAll(\"␍\"),\n        '\\t' => try writer.writeAll(\"␉\"),\n        else => try writer.writeByte('.'),\n    }\n}\n```\n:::\n\n\n\nMany programmers would also use an `else` branch to handle a \"not supported\" case.\nThat is, a case that cannot be properly handled by your code, or, just a case that\nshould not be \"fixed\". Therefore, you can use an `else` branch to panic (or raise an error)\nin your program to stop the current execution.\n\nTake the code example below. We can see that, we are handling the cases\nfor the `level` object being either 1, 2, or 3. All other possible cases are not supported by default,\nand, as consequence, we raise a runtime error in such cases through the `@panic()` built-in function.\n\nAlso notice that, we are assigning the result of the switch statement to a new object called `category`.\nThis is another thing that you can do with switch statements in Zig. If a branch\noutputs a value as result, you can store the result value of the switch statement into\na new object.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 => \"beginner\",\n    3 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n:::\n\n\n\n```\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n```\n\n\n\n#### Using ranges in switch\n\nFurthermore, you can also use ranges of values in switch statements.\nThat is, you can create a branch in your switch statement that is used\nwhenever the input value is within the specified range. These \"range expressions\"\nare created with the operator `...`. It's important\nto emphasize that the ranges created by this operator are\ninclusive on both ends.\n\nFor example, I could easily change the previous code example to support all\nlevels between 0 and 100. Like this:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 => \"beginner\",\n    26...75 => \"intermediary\",\n    76...100 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nbeginner\n```\n\n\n:::\n:::\n\n\n\nThis is neat, and it works with character ranges too. That is, I could\nsimply write `'a'...'z'`, to match any character value that is a\nlowercase letter, and it would work fine.\n\n\n#### Labeled switch statements\n\nIn @sec-blocks we have talked about labeling blocks, and also, about using these labels\nto return a value from the block. Well, from version 0.14.0 and onwards of the `zig` compiler,\nyou can also apply labels over switch statements, which makes it possible to almost implement a\n\"C `goto`\" like pattern.\n\nFor example, if you give the label `xsw` to a switch statement, you can use this\nlabel in conjunction with the `continue` keyword to go back to the beginning of the switch\nstatement. In the example below, the execution goes back to the beginning of the\nswitch statement two times, before ending at the `3` branch.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nxsw: switch (@as(u8, 1)) {\n    1 => {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 => continue :xsw 3,\n    3 => return,\n    4 => {},\n    else => {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n```\n:::\n\n\n\n\n### The `defer` keyword {#sec-defer}\n\nWith the `defer` keyword you can register an expression to be executed when you exit the current scope.\nTherefore, this keyword has a similar functionality as the `on.exit()` function from R.\nTake the `foo()` function below as an example. When we execute this `foo()` function, the expression\nthat prints the message \"Exiting function ...\" is getting executed only when the function exits\nits scope.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n```\n:::\n\n\n\n```\nAdding some numbers ...\nMultiplying ...\nExiting function ...\n```\n\nTherefore, we can use `defer` to declare an expression that is going to be executed\nwhen your code exits the current scope. Some programmers like to interpret the phrase \"exit of the current scope\"\nas \"the end of the current scope\". But this interpretation might not be entirely correct, depending\non what you consider as \"the end of the current scope\".\n\nI mean, what do you consider as **the end** of the current scope? Is it the closing curly bracket (`}`) of the scope?\nIs it when the last expression in the function gets executed? Is it when the function returns to the previous scope?\nEtc. For example, it would not be correct to interpret the \"exit of the current scope\" as the closing\ncurly bracket of the scope. Because the function might exit from an earlier position than this\nclosing curly bracket (e.g. an error value was generated at a previous line inside the function;\nthe function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\n\nNow, if you remember of what we have discussed in @sec-blocks, there are multiple structures in the language\nthat create their own separate scopes. For/while loops, if/else statements,\nfunctions, normal blocks, etc. This also affects the interpretation of `defer`.\nFor example, if you use `defer` inside a for loop, then, the given expression\nwill be executed everytime this specific for loop exits its own scope.\n\nBefore we continue, it's worth emphasizing that the `defer` keyword is an \"unconditional defer\".\nWhich means that the given expression will be executed no matter how the code exits\nthe current scope. For example, your code might exit the current scope because of an error value\nbeing generated, or, because of a return statement, or, a break statement, etc.\n\n\n\n### The `errdefer` keyword {#sec-errdefer1}\n\nOn the previous section, we have discussed the `defer` keyword, which you can use to\nregister an expression to be executed at the exit of the current scope.\nBut this keyword has a brother, which is the `errdefer` keyword. While `defer`\nis an \"unconditional defer\", the `errdefer` keyword is a \"conditional defer\".\nWhich means that the given expression is executed only when you exit the current\nscope on a very specific circumstance.\n\nIn more details, the expression given to `errdefer` is executed only when an error occurs in the current scope.\nTherefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope\nin a normal situation, without errors, the expression given to `errdefer` is not executed.\n\nThis makes the `errdefer` keyword one of the many tools available in Zig for error handling.\nIn this section, we are more concerned with the control flow aspects around `errdefer`.\nBut we are going to discuss `errdefer` later as a error handling tool in @sec-errdefer2.\n\nThe code example below demonstrates three things:\n\n- that `defer` is an \"unconditional defer\", because the given expression gets executed regardless of how the function `foo()` exits its own scope.\n- that `errdefer` is executed because the function `foo()` returned an error value.\n- that `defer` and `errdefer` expressions are executed in a LIFO (*last in, first out*) order.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n```\n:::\n\n\n\n```\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\nWhen I say that \"defer expressions\" are executed in a LIFO order, what I want to say is that\nthe last `defer` or `errdefer` expressions in the code are the first ones to be executed.\nYou could also interpret this as: \"defer expressions\" are executed from bottom to top, or,\nfrom last to first.\n\nTherefore, if I change the order of the `defer` and `errdefer` expressions, you will notice that\nthe value of `i` that gets printed to the console changes to 1. This doesn't mean that the\n`defer` expression was not executed in this case. This actually means that the `defer` expression\nwas executed only after the `errdefer` expression. The code example below demonstrates this:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n```\n:::\n\n\n\n```\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\n\n\n### For loops\n\nA loop allows you to execute the same lines of code multiple times,\nthus, creating a \"repetition space\" in the execution flow of your program.\nLoops are particularly useful when we want to replicate the same function\n(or the same set of commands) over different inputs.\n\nThere are different types of loops available in Zig. But the most\nessential of them all is probably the *for loop*. A for loop is\nused to apply the same piece of code over the elements of a slice, or, an array.\n\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from\nother languages. You start with the `for` keyword, then, you\nlist the items that you want to iterate\nover inside a pair of parentheses. Then, inside of a pair of pipes (`|`)\nyou should declare an identifier that will serve as your iterator, or,\nthe \"repetition index of the loop\".\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (items) |value| {\n    // code to execute\n}\n```\n:::\n\n\n\nTherefore, instead of using a `(value in items)` syntax,\nin Zig, for loops use the syntax `(items) |value|`. In the example\nbelow, you can see that we are looping through the items\nof the array stored at the object `name`, and printing to the\nconsole the decimal representation of each character in this array.\n\nIf we wanted, we could also iterate through a slice (or a portion) of\nthe array, instead of iterating through the entire array stored in the `name` object.\nJust use a range selector to select the section you want. For example,\nI could provide the expression `name[0..3]` to the for loop, to iterate\njust through the first 3 elements in the array.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n80 | 101 | 100 | 114 | 111 | \n```\n\n\n:::\n:::\n\n\n\nIn the above example we are using the value itself of each\nelement in the array as our iterator. But there are many situations where\nwe need to use an index instead of the actual values of the items.\n\nYou can do that by providing a second set of items to iterate over.\nMore precisely, you provide the range selector `0..` to the for loop. So,\nyes, you can use two different iterators at the same time in a for\nloop in Zig.\n\nBut remember from @sec-assignments that, every object\nyou create in Zig must be used in some way. So if you declare two iterators\nin your for loop, you must use both iterators inside the for loop body.\nBut if you want to use just the index iterator, and not use the \"value iterator\",\nthen, you can discard the value iterator by maching the\nvalue items to the underscore character, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n:::\n\n\n\n```\n0 | 1 | 2 | 3 | 4 |\n```\n\n\n### While loops\n\nA while loop is created from the `while` keyword. A `for` loop\niterates through the items of an array, but a `while` loop\nwill loop continuously, and infinitely, until a logical test\n(specified by you) becomes false.\n\nYou start with the `while` keyword, then, you define a logical\nexpression inside a pair of parentheses, and the body of the\nloop is provided inside a pair of curly braces, like in the example below:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\nYou can also specify the increment expression to be used at the beginning of a while loop.\nTo do that, we write the increment expression inside a pair of parentheses after a colon character (`:`).\nThe code example below demonstrates this other pattern.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n### Using `break` and `continue`\n\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using\nthe keywords `break` and `continue`, respectively. The `while` loop presented in the next code example is,\nat first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to `true`.\nBut what makes this `while` loop stop when the `i` object reaches the count\n10? It's the `break` keyword!\n\nInside the while loop, we have an if statement that is constantly checking if the `i` variable\nis equal to 10. Since we are incrementing the value of `i` at each iteration of the\nwhile loop, this `i` object will eventually be equal to 10, and when it is, the if statement\nwill execute the `break` expression, and, as a result, the execution of the while loop is stopped.\n\nNotice the use of the `expect()` function from the Zig Standard Library after the while loop.\nThis `expect()` function is an \"assert\" type of function.\nThis function checks if the logical test provided is equal to true. If so, the function do nothing.\nOtherwise (i.e., the logical test is equal to false), the function raises an assertion error.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nEverything worked!\n```\n\n\n:::\n:::\n\n\n\nSince this code example was executed successfully by the `zig` compiler,\nwithout raising any errors, we known that, after the execution of the while loop,\nthe `i` object is equal to 10. Because if it wasn't equal to 10, an error would have\nbeen raised by `expect()`.\n\nNow, in the next example, we have a use case for\nthe `continue` keyword. The if statement is constantly\nchecking if the current index is a multiple of 2. If\nit is, we jump to the next iteration of the loop.\nOtherwise, the loop just prints the current index to the console.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 3 | 5 | \n```\n\n\n:::\n:::\n\n\n\n\n\n## Function parameters are immutable {#sec-fun-pars}\n\nWe have already discussed a lot of the syntax behind function declarations in @sec-root-file and @sec-main-file.\nBut I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig.\nIn summary, function parameters are immutable in Zig.\n\nTake the code example below, where we declare a simple function that just tries to add\nsome amount to the input integer, and returns the result back. If you look closely\nat the body of this `add2()` function, you will notice that we try\nto save the result back into the `x` function argument.\n\nIn other words, this function not only uses the value that it received through the function argument\n`x`, but it also tries to change the value of this function argument, by assigning the addition result\ninto `x`. However, function arguments in Zig are immutable. You cannot change their values, or, you\ncannot assign values to them inside the body's function.\n\nThis is the reason why, the code example below does not compile successfully. If you try to compile\nthis code example, you will get a compile error message about \"trying to change the value of a\nimmutable (i.e., constant) object\".\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n\n```\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n```\n\n\n### A free optimization\n\nIf a function argument receives as input an object whose data type is\nany of the primitive types that we have listed in @sec-primitive-data-types,\nthis object is always passed by value to the function. In other words, this object\nis copied into the function stack frame.\n\nHowever, if the input object have a more complex data type, for example, it might\nbe a struct instance, or an array, or an union value, etc., in cases like that, the `zig` compiler\nwill take the liberty of deciding for you which strategy is best. Thus, the `zig` compiler will\npass your object to the function either by value, or by reference. The compiler will always\nchoose the strategy that is faster for you.\nThis optimization that you get for free is possible only because function arguments are\nimmutable in Zig.\n\n\n### How to overcome this barrier\n\nThere are some situations where you might need to change the value of your function argument\ndirectly inside the function's body. This happens more often when we are passing\nC structs as inputs to Zig functions.\n\nIn a situation like this, you can overcome this barrier by using a pointer. In other words,\ninstead of passing a value as input to the argument, you can pass a \"pointer to value\" instead.\nYou can change the value that the pointer points to, by dereferencing it.\n\nTherefore, if we take our previous `add2()` example, we can change the value of the\nfunction argument `x` inside the function's body by marking the `x` argument as a\n\"pointer to a `u32` value\" (i.e., `*u32` data type), instead of a `u32` value.\nBy making it a pointer, we can finally alter the value of this function argument directly inside\nthe body of the `add2()` function. You can see that the code example below compiles successfully.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n```\n:::\n\n\n\n```\nResult: 6\n```\n\n\nEven in this code example above, the `x` argument is still immutable. Which means that the pointer itself is immutable.\nTherefore, you cannot change the memory address that it points to. However, you can dereference the pointer\nto access the value that it points to, and also, to change this value, if you need to.\n\n\n\n\n\n## Structs and OOP {#sec-structs-and-oop}\n\nZig is a language more closely related to C (which is a procedural language),\nthan it is to C++ or Java (which are object-oriented languages). Because of that, you do not\nhave advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or\nclass inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\n\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C.\nYou give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can\nalso register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object\nthat you create with this new type, will always have these methods available and associated with them.\n\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which\nis used to construct (or, to instantiate) every object of this particular class, and we also have\na destructor method (or a destructor function), which is the function responsible for destroying\nevery object of this class.\n\nIn Zig, we normally declare the constructor and the destructor methods\nof our structs, by declaring an `init()` and a `deinit()` methods inside the struct.\nThis is just a naming convention that you will find across the entire Zig Standard Library.\nSo, in Zig, the `init()` method of a struct is normally the constructor method of the class represented by this struct.\nWhile the `deinit()` method is the method used for destroying an existing instance of that struct.\n\nThe `init()` and `deinit()` methods are both used extensively in Zig code, and you will see both of\nthem being used when we talk about allocators in @sec-allocators.\nBut, as another example, let's build a simple `User` struct to represent a user of some sort of system.\n\nIf you look at the `User` struct below, you can see the `struct` keyword.\nNotice the data members of this struct: `id`, `name` and `email`. Every data member has its\ntype explicitly annotated, with the colon character (`:`) syntax that we described earlier in @sec-root-file.\nBut also notice that every line in the struct body that describes a data member, ends with a comma character (`,`).\nSo every time you declare a data member in your Zig code, always end the line with a comma character, instead\nof ending it with the traditional semicolon character (`;`).\n\nNext, we have registered an `init()` function as a method\nof this `User` struct. This `init()` method is the constructor method that we will use to instantiate\nevery new `User` object. That is why this `init()` function returns a new `User` object as result.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    fn init(id: u64,\n            name: []const u8,\n            email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\npedro\n```\n\n\n:::\n:::\n\n\n\n\n\n### The `pub` keyword\n\nThe `pub` keyword plays an important role in struct declarations, and OOP in Zig.\nIn essence, this keyword is short for \"public\", and it makes an item/component available outside of the\nmodule where this item/component is declared. In other words, if I don't apply the `pub` keyword on\nsomething, it means that this \"something\" is available to be called/used only from within the module\nwhere this \"something\" is declared.\n\nTo demonstrate the effect of this keyword let's focus again on the `User` struct that we have\ndeclared on the previous section. For our example here, let's suppose that this `User` struct is declared inside\na Zig module named `user.zig`. If I don't use the `pub` keyword on the `User` struct, it means that I can create\nan `User` object, and call it's methods (`print_name()` and `init()`) only from within the module where the `User`\nstruct is declared, which in this case is the `user.zig` module.\n\nThis is why the previous code example works fine. Because we declare and also use the `User` struct\ninside the same module. But problems start to arise when we try to import and call/use this struct\nfrom another module. For example, if I create a new module called `register.zig`, and import the `user.zig`\nmodule into it, and try to annotate any variable with the `User` type, I get an error from the compiler.\n\n```zig\n// register.zig\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = undefined;\n    _ = u;\n}\n```\n\n```\nregister.zig:3:18: error: 'User' is not marked 'pub'\n    const u: user.User = undefined;\n             ~~~~^~~~~\nuser.zig:3:1: note: declared here\nconst User = struct {\n^~~~~\n```\n\nTherefore, if you want to use something outside of the module where this \"something\" is declared,\nyou have to mark it with the `pub` keyword. This \"something\" can be a module,\na struct, a function, an object, etc.\n\nFor our example here, if we go back to the `user.zig` module, and add the `pub` keyword\nto the `User` struct declaration, then, I can successfully compile the `register.zig` module.\n\n```zig\n// user.zig\n// Added the `pub` keyword to `User`\npub const User = struct {\n// ...\n```\n\n```zig\n// register.zig\n// This works fine now!\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = undefined;\n    _ = u;\n}\n```\n\n\nNow, what do you think it will happen if I try to actually call from `register.zig` any of the methods\nof the `User` struct? For example, if I try to call the `init()` method? The answer is: I get a similar error message,\nwarning me that the `init()` method is not marked as `pub`, as you can see below:\n\n```zig\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = user.User.init(\n        1, \"pedro\", \"email@gmail.com\"\n    );\n    _ = u;\n}\n```\n\n```\nregister.zig:3:35: error: 'init' is not marked 'pub'\n    const u: user.User = user.User.init(\n                         ~~~~~~~~~^~~~~\nuser.zig:8:5: note: declared here\n    fn init(id: u64,\n    ^~~~~~~\n```\n\nThus, just because we have applied the `pub` keyword on the struct declaration,\nthis does not make the methods of that struct public as well. If we want to use\nany method from a struct (such as the `init()` method) outside of the module\nwhere this struct is declared, we have to mark this method with the `pub` keyword\nas well.\n\nGoing back to the `user.zig` module, and marking both the `init()` and `print_name()`\nmethods with the `pub` keyword, makes them both available to the outside world, and,\nas consequence, makes the previous code example work.\n\n\n```zig\n// user.zig\n// Added the `pub` keyword to `User.init`\n    pub fn init(\n// ...\n// Added the `pub` keyword to `User.print_name`\n    pub fn print_name(self: User) !void {\n// ...\n```\n\n```zig\n// register.zig\n// This works fine now!\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = user.User.init(\n        1, \"pedro\", \"email@gmail.com\"\n    );\n    _ = u;\n}\n```\n\n\n### Anonymous struct literals {#sec-anonymous-struct-literals}\n\nYou can declare a struct object as a literal value. When we do that, we normally specify the\ndata type of this struct literal by writing its data type just before the opening curly brace.\nFor example, I could write a struct literal value of the type `User` that we have defined\nin the previous section like this:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n```\n:::\n\n\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a\nstruct literal, but not specify explicitly the type of this particular struct.\nAn anonymous struct is written by using the syntax `.{}`. So, we essentially\nreplaced the explicit type of the struct literal with a dot character (`.`).\n\nAs we described in @sec-type-inference, when you put a dot before a struct literal,\nthe type of this struct literal is automatically inferred by the `zig` compiler.\nIn essence, the `zig` compiler will look for some hint of what is the type of that struct.\nThis hint can be the type annotation of a function argument,\nor the return type annotation of the function that you are using, or the type annotation\nof an existing object.\nIf the compiler does find such type annotation, it will use this\ntype in your literal struct.\n\nAnonymous structs are very commonly used as inputs to function arguments in Zig.\nOne example that you have seen already constantly, is the `print()`\nfunction from the `stdout` object.\nThis function takes two arguments.\nThe first argument, is a template string, which should\ncontain string format specifiers in it, which tells how the values provided\nin the second argument should be printed into the message.\n\nWhile the second argument is a struct literal that lists the values\nto be printed into the template message specified in the first argument.\nYou normally want to use an anonymous struct literal here, so that the\n`zig` compiler do the job of specifying the type of this particular\nanonymous struct for you.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello, world!\n```\n\n\n:::\n:::\n\n\n\n\n\n### Struct declarations must be constant\n\nTypes in Zig must be `const` or `comptime` (we are going to talk more about comptime in @sec-comptime).\nWhat this means is that you cannot create a new data type, and mark it as variable with the `var` keyword.\nSo struct declarations are always constant. You cannot declare a new struct type using the `var` keyword.\nIt must be `const`.\n\nIn the `Vec3` example below, this declaration is allowed because I'm using the `const` keyword\nto declare this new data type.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n```\n:::\n\n\n\n\n### The `self` method argument {#sec-self-arg}\n\nIn every language that have OOP, when we declare a method of some class or struct, we\nusually declare this method as a function that has a `self` argument.\nThis `self` argument is the reference to the object itself from which the method\nis being called from.\n\nIt's not mandatory to use this `self` argument. But why would you not use this `self` argument?\nThere is no reason to not use it. Because the only way to get access to the data stored in the\ndata members of your struct is to access them through this `self` argument.\nIf you don't need to use the data in the data members of your struct inside your method, you very likely don't need\na method. You can just declare this logic as a simple function, outside of your\nstruct declaration.\n\n\nTake the `Vec3` struct below. Inside this `Vec3` struct we declared a method named `distance()`.\nThis method calculates the distance between two `Vec3` objects, by following the distance\nformula in euclidean space. Notice that this `distance()` method takes two `Vec3` objects\nas input, `self` and `other`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n```\n:::\n\n\n\n\nThe `self` argument corresponds to the `Vec3` object from which this `distance()` method\nis being called from. While the `other` is a separate `Vec3` object that is given as input\nto this method. In the example below, the `self` argument corresponds to the object\n`v1`, because the `distance()` method is being called from the `v1` object,\nwhile the `other` argument corresponds to the object `v2`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n```\n:::\n\n\n\n```\nDistance: 3.3970575502926055\n```\n\n\n\n### About the struct state\n\nSometimes you don't need to care about the state of your struct object. Sometimes, you just need\nto instantiate and use the objects, without altering their state. You can notice that when you have methods\ninside your struct declaration that might use the values that are present in the data members, but they\ndo not alter the values in these data members of the struct in anyway.\n\nThe `Vec3` struct that was presented in @sec-self-arg is an example of that.\nThis struct have a single method named `distance()`, and this method does use the values\npresent in all three data members of the struct (`x`, `y` and `z`). But at the same time,\nthis method does not change the values of these data members at any point.\n\nAs a result of that, when we create `Vec3` objects we usually create them as\nconstant objects, like the `v1` and `v2` objects presented in @sec-self-arg.\nWe can create them as variable objects with the `var` keyword,\nif we want to. But because the methods of this `Vec3` struct do not change\nthe state of the objects in any point, it's unnecessary to mark them\nas variable objects.\n\nBut why? Why am I talking about this here? It's because the `self` argument\nin the methods are affected depending on whether the\nmethods present in a struct change or don't change the state of the object itself.\nMore specifically, when you have a method in a struct that changes the state\nof the object (i.e., changes the value of a data member), the `self` argument\nin this method must be annotated in a different manner.\n\nAs I described in @sec-self-arg, the `self` argument in methods of\na struct is the argument that receives as input the object from which the method\nwas called from. We usually annotate this argument in the methods by writing `self`,\nfollowed by the colon character (`:`), and the data type of the struct to which\nthe method belongs to (e.g. `User`, `Vec3`, etc.).\n\nIf we take the `Vec3` struct that we defined in the previous section as an example,\nwe can see in the `distance()` method that this `self` argument is annotated as\n`self: Vec3`. Because the state of the `Vec3` object is never altered by this\nmethod.\n\nBut what if we do have a method that alters the state of the object, by altering the\nvalues of its data members, how should we annotate `self` in this instance? The answer is:\n\"we should annotate `self` as a pointer of `x`, instead of just `x`\".\nIn other words, you should annotate `self` as `self: *x`, instead of annotating it\nas `self: x`.\n\nIf we create a new method inside the `Vec3` object that, for example, expands the\nvector by multiplying its coordinates by a factor of two, then, we need to follow\nthis rule specified in the previous paragraph. The code example below demonstrates\nthis idea:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n```\n:::\n\n\n\nNotice in the code example above that we have added a new method\nto our `Vec3` struct named `twice()`. This method doubles the\ncoordinate values of our vector object. In the\ncase of the `twice()` method, we annotated the `self` argument as `*Vec3`,\nindicating that this argument receives a pointer (or a reference, if you prefer to call it this way)\nto a `Vec3` object as input.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n```\n:::\n\n\n\n```\nDoubled: 8.4\n```\n\n\n\nNow, if you change the `self` argument in this `twice()` method to `self: Vec3`, like in the\n`distance()` method, you will get the compiler error exposed below as result. Notice that this\nerror message is showing a line from the `twice()` method body,\nindicating that you cannot alter the value of the `x` data member.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n```\n:::\n\n\n\n```\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\n```\n\nThis error message indicates that the `x` data member belongs to a constant object,\nand, because of that, it cannot be changed. Ultimately, this error message\nis telling us that the `self` argument is constant.\n\nIf you take some time, and think hard about this error message, you will understand it.\nYou already have the tools to understand why we are getting this error message.\nWe have talked about it already in @sec-fun-pars.\nSo remember, every function argument is immutable in Zig, and `self`\nis no exception to this rule.\n\nIn this example, we marked the `v3` object as a variable object.\nBut this does not matter. Because it's not about the input object, it's about\nthe function argument.\n\nThe problem begins when we try to alter the value of `self` directly, which is a function argument,\nand, every function argument is immutable by default. You may ask yourself how can we overcome\nthis barrier, and once again, the solution was also discussed in @sec-fun-pars.\nWe overcome this barrier, by explicitly marking the `self` argument as a pointer.\n\n\n::: {.callout-note}\nIf a method of your `x` struct alters the state of the object, by\nchanging the value of any data member, then, remember to use `self: *x`,\ninstead of `self: x` in the function signature of this method.\n:::\n\n\nYou could also interpret the content discussed in this section as:\n\"if you need to alter the state of your `x` struct object in one of its methods,\nyou must explicitly pass the `x` struct object by reference to the `self` argument of this method\".\n\n\n\n## Type inference {#sec-type-inference}\n\nZig is a strongly typed language. But, there are some situations\nwhere you don't have to explicitly write the type of every single object in your source code,\nas you would expect from a traditional strongly typed language, such as C and C++.\n\nIn some situations, the `zig` compiler can use type inference to solve the data types for you, easing some of\nthe burden that you carry as a developer.\nThe most common way this happens is through function arguments that receive struct objects\nas input.\n\nIn general, type inference in Zig is done by using the dot character (`.`).\nEverytime you see a dot character written before a struct literal, or before an enum value, or something like that,\nyou know that this dot character is playing a special part in this place. More specifically, it's\ntelling the `zig` compiler something along the lines of: \"Hey! Can you infer the type of this\nvalue for me? Please!\". In other words, this dot character is playing a similar role as the `auto` keyword in C++.\n\nI gave you some examples of this in @sec-anonymous-struct-literals, where we used anonymous struct literals.\nAnonymous struct literals are, struct literals that use type inference to\ninfer the exact type of this particular struct literal.\nThis type inference is done by looking for some minimal hint of the correct data type to be used.\nYou could say that the `zig` compiler looks for any neighbouring type annotation that might tell it\nwhat the correct type would be.\n\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in @sec-switch).\nI also gave some other examples of type inference in @sec-switch, where we were inferring the data types of enum values listed inside\nof switch statements (e.g. `.DE`).\nBut as another example, take a look at this `fence()` function reproduced below,\nwhich comes from the [`atomic.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig)[^fence-fn]\nof the Zig Standard Library.\n\n[^fence-fn]: <https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig>.\n\nThere are a lot of things in this function that we haven't talked about yet, such as:\nwhat `comptime` means? `inline`? `extern`?\nLet's just ignore all of these things, and focus solely on the switch statement\nthat is inside this function.\n\nWe can see that this switch statement uses the `order` object as input. This `order`\nobject is one of the inputs of this `fence()` function, and we can see in the type annotation,\nthat this object is of type `AtomicOrder`. We can also see a bunch of values inside the\nswitch statements that begin with a dot character, such as `.release` and `.acquire`.\n\nBecause these weird values contain a dot character before them, we are asking the `zig`\ncompiler to infer the types of these values inside the switch statement. Then, the `zig`\ncompiler is looking into the current context where these values are being used, and trying\nto infer the types of these values.\n\nSince they are being used inside a switch statement, the `zig` compiler looks into the type\nof the input object given to the switch statement, which is the `order` object in this case.\nBecause this object have type `AtomicOrder`, the `zig` compiler infers that these values\nare data members from this type `AtomicOrder`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic => @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire => tsan.__tsan_acquire(addr),\n            .release => tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst => {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n```\n:::\n\n\n\nThis is how basic type inference is done in Zig. If we didn't use the dot character before\nthe values inside this switch statement, then, we would be forced to explicitly write\nthe data types of these values. For example, instead of writing `.release` we would have to\nwrite `AtomicOrder.release`. We would have to do this for every single value\nin this switch statement, and this is a lot of work. That is why type inference\nis commonly used on switch statements in Zig.\n\n\n\n## Type casting {#sec-type-cast}\n\nIn this section, I want to discuss type casting (or, type conversion) with you.\nWe use type casting when we have an object of type \"x\", and we want to convert\nit into an object of type \"y\", i.e., we want to change the data type of the object.\n\nMost languages have a formal way to perform type casting. In Rust for example, we normally\nuse the keyword `as`, and in C, we normally use the type casting syntax, e.g. `(int) x`.\nIn Zig, we use the `@as()` built-in function to cast an object of type \"x\", into\nan object of type \"y\".\n\nThis `@as()` function is the preferred way to perform type conversion (or type casting)\nin Zig. Because it's explicit, and, it also performs the casting only if it\nis unambiguous and safe. To use this function, you just provide the target data type\nin the first argument, and, the object that you want cast as the second argument.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file3731626c8b4e.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\nThis is the general way to perform type casting in Zig. But remember, `@as()` works only when casting\nis unambiguous and safe. There are many situations where these assumptions do not hold. For example,\n\nwhen casting an integer value into a float value, or vice-versa, it's not clear to the compiler\nhow to perform this conversion safely.\n\nTherefore, we need to use specialized \"casting functions\" in such situations.\nFor example, if you want to cast an integer value into a float value, then, you\nshould use the `@floatFromInt()` function. In the inverse scenario, you should use\nthe `@intFromFloat()` function.\n\nIn these functions, you just provide the object that you want to\ncast as input. Then, the target data type of the \"type casting operation\" is determined by\nthe type annotation of the object where you are saving the results.\nIn the example below, we are casting the object `x` into a value of type `f32`,\nbecause the object `y`, which is where we are saving the results, is annotated\nas an object of type `f32`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file373174d96589.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\nAnother built-in function that is very useful when performing type casting operations is `@ptrCast()`.\nIn essence, we use the `@as()` built-in function when we want to explicit convert (or cast) a Zig value/object\nfrom a type \"x\" to a type \"y\", etc. However, pointers (we are going to discuss pointers\nin more depth in @sec-pointer) are a special type of object in Zig,\ni.e., they are treated differently from \"normal objects\".\n\nEverytime a pointer is involved in some \"type casting operation\" in Zig, the `@ptrCast()` function is used.\nThis function works similarly to `@floatFromInt()`.\nYou just provide the pointer object that you want to cast as input to this function, and the\ntarget data type is, once again, determined by the type annotation of the object where the results are being\nstored.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file373135327b62.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n## Modules\n\nWe already talked about what modules are, and also, how to import other modules into\nyour current module via *import statements*. Every Zig module (i.e., a `.zig` file) that you write in your project\nis internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the\nZig Standard Library into our current module.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n```\n:::\n\n\n\nWhen we want to access the functions and objects from the standard library, we\nare basically accessing the data members of the struct stored in the `std`\nobject. That is why we use the same syntax that we use in normal structs, with the dot operator (`.`)\nto access the data members and methods of the struct.\n\nWhen this \"import statement\" gets executed, the result of this expression is a struct\nobject that contains the Zig Standard Library modules, global variables, functions, etc.\nAnd this struct object gets saved (or stored) inside the constant object named `std`.\n\n\nTake the [`thread_pool.zig` module from the project `zap`](https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig)[^thread]\nas an example. This module is written as if it was\na big struct. That is why we have a top-level and public `init()` method\nwritten in this module. The idea is that all top-level functions written in this\nmodule are methods from the struct, and all top-level objects and struct declarations\nare data members of this struct. The module is the struct itself.\n\n[^thread]: <https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig>\n\n\nSo you would import and use this module by doing something like this:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst ThreadPool = @import(\"thread_pool.zig\");\nconst num_cpus = std.Thread.getCpuCount()\n    catch @panic(\"failed to get cpu core count\");\nconst num_threads = std.math.cast(u16, num_cpus)\n    catch std.math.maxInt(u16);\nconst pool = ThreadPool.init(\n    .{ .max_threads = num_threads }\n);\n```\n:::\n",
+    "supporting": [
+      "03-structs_files"
+    ],
+    "filters": [
+      "rmarkdown/pagebreak.lua"
+    ],
+    "includes": {},
+    "engineDependencies": {
+      "knitr": [
+        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
+      ]
+    },
+    "preserve": null,
+    "postProcess": false
+  }
+}
\ No newline at end of file
diff --git a/_freeze/Chapters/03-unittests/execute-results/epub.json b/_freeze/Chapters/03-unittests/execute-results/epub.json
new file mode 100644
index 00000000..8a67fd57
--- /dev/null
+++ b/_freeze/Chapters/03-unittests/execute-results/epub.json
@@ -0,0 +1,21 @@
+{
+  "hash": "555cc5c67a26414e89a3511dba578c1d",
+  "result": {
+    "engine": "knitr",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Unit tests {#sec-unittests}\n\nIn this chapter, I want to dive in on how unit tests are done in\nZig. We are going to talk about what is the testing workflow in Zig, and\nalso, about the `test` command from the `zig` compiler.\n\n\n## Introducing the `test` block\n\nIn Zig, unit tests are written inside a `test` declaration, or, how I prefer to call it, inside a `test` block.\nEvery `test` block is written by using the keyword `test`.\nYou can optionally use a string literal to write a label, which is responsible for identifying\nthe specific group of unit tests that you are writing inside this specific `test` block.\n\nIn the example below, we are testing if the sum of two objects (`a` and `b`)\nis equal to 4. The `expect()` function from the Zig Standard Library\nis a function that receives a logical test as input. If this logical test\nresults in `true`, then, the test passes. But if it results\nin `false`, then, the test fails.\n\nYou can write any Zig code you want inside a `test` block.\nPart of this code might be some necessary commands to setup your testing\nenvironment, or just initializing some objects that you need to use\nin your unit tests.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest \"testing simple sum\" {\n    const a: u8 = 2;\n    const b: u8 = 2;\n    try expect((a + b) == 4);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file3d7d5828b2d3.test.testing simple sum...OKA\n  All 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\nYou can have multiple `test` blocks written on the same Zig module.\nAlso, you can mix `test` blocks with your source code, with no problems\nor consequences. If you mix `test` blocks with your normal source code,\nwhen you execute the `build`, `build-exe`, `build-obj` or `build-lib` commands from the\n`zig` compiler that we exposed in @sec-compile-code, these `test` blocks are automatically\nignored by the compiler.\n\nIn other words, the `zig` compiler builds and execute your unit tests only\nwhen you ask it to. By default, the compiler always ignore `test`\nblocks written in your Zig modules. The compiler normally checks only if\nthere are any syntax errors in these `test` blocks.\n\nIf you take a look at the source code for most of the files present in the\nZig Standard Library[^zig-std-lib], you can see that the `test` blocks\nare written together with the normal source code of the library.\nYou can see this for example, at the [`array_list` module](https://github.com/ziglang/zig/blob/master/lib/std/array_list.zig)[^zig-array].\nSo, the standard that the Zig developers decided to adopt\nis to keep their unit tests together with the source code\nof the functionality that they are testing.\n\nEach programmer might have a different opinion on this.\nSome of them might prefer to keep unit tests separate from the actual\nsource code of their application. If that is your case, you can\nsimply create a separate `tests` folder in your project, and\nstart writing Zig modules that contains only unit tests (as you would normally do\non a Python project with `pytest`, for example), and everything will work fine.\nIt boils down to which is your preference here.\n\n[^zig-std-lib]: <https://github.com/ziglang/zig/tree/master/lib/std>\n[^zig-array]: <https://github.com/ziglang/zig/blob/master/lib/std/array_list.zig>\n\n\n## How to run your tests\n\nIf the `zig` compiler ignores any `test` block by default, how can\nyou compile and run your unit tests? The answer is the `test` command from\nthe `zig` compiler. By running the `zig test` command, the compiler will\nfind every instance of a `test` block in your Zig modules, and, it will\ncompile and run the unit tests that you wrote.\n\n\n```bash\nzig test simple_sum.zig\n```\n\n```\n1/1 simple_sum.test.testing simple sum... OK\nAll 1 tests passed.\n```\n\n\n## Testing memory allocations\n\nOne of the advantages of Zig is that it offers great tools\nthat help us, programmers, to avoid (but also detect) memory problems, such as\nmemory leaks and double-frees. The `defer` keyword\nis especially helpful in this regard.\n\nWhen developing your source code, you, the programmer, are responsible for making\nsure that your code does not produce such problems. However,\nyou can also use a special type of an allocator object in Zig\nthat is capable of automatically detecting such problems for you.\nThis is the `std.testing.allocator` object.\nThis allocator object offers some basic memory safety detection\nfeatures, which are capable of detecting memory leaks.\n\nAs we described in @sec-heap, to allocate memory on the heap, you need\nto use an allocator object, and your functions that use these objects to allocate memory\non the heap, should receive an allocator object as one of its inputs.\nEvery memory on the heap that you allocate using these allocator objects,\nmust also be freed using this same allocator object.\n\nSo, if you want to test the memory allocations performed by your functions,\nand make sure that you don't have problems in these allocations, you can simply\nwrite unit tests for these functions, where you provide the\n`std.testing.allocator` object as input to these functions.\n\nLook at the example below, where I'm defining a function that clearly causes\na memory leak. Because we allocate memory, but, at the same time,\nwe do not free this allocated memory at any point. So, when the function\nreturns, we lose the reference to the `buffer` object, which contains\nthe allocated memory, and, as a result, we can no longer free this memory.\n\nNotice that, inside a `test` block I execute this function with\nthe `std.testing.allocator`. The allocator object was capable\nof looking deeper in our program, and detecting the memory leak. As a result,\nthis allocator object returns an error message of \"memory leaked\", and also,\na stack trace showing the exact point where the memory was leaked.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nfn some_memory_leak(allocator: Allocator) !void {\n    const buffer = try allocator.alloc(u32, 10);\n    _ = buffer;\n    // Return without freeing the\n    // allocated memory\n}\n\ntest \"memory leak\" {\n    const allocator = std.testing.allocator;\n    try some_memory_leak(allocator);\n}\n```\n:::\n\n\n\n```\nTest [1/1] leak_memory.test.memory leak...\n    [gpa] (err): memory address 0x7c1fddf39000 leaked:\n./ZigExamples/debugging/leak_memory.zig:4:39: 0x10395f2\n    const buffer = try allocator.alloc(u32, 10);\n                                      ^\n./ZigExamples/debugging/leak_memory.zig:12:25: 0x10398ea\n    try some_memory_leak(allocator);\n\n... more stack trace\n```\n\n\n## Testing errors\n\nOne common style of unit tests are those that look for\nspecific errors in your functions. In other words, you write\na unit test that tries to assert if a specific function call\nreturns any error, or a specific type of error.\n\nIn C++ you would normally write this style of unit tests using, for example,\nthe functions `REQUIRE_THROWS()` or `CHECK_THROWS()` from the [`Catch2` test framework](https://github.com/catchorg/Catch2/tree/devel)[^catch2].\nIn the case of a Python project, you would probably use the\n[`raises()` function from `pytest`](https://docs.pytest.org/en/7.1.x/reference/reference.html#pytest-raises)[^pytest].\nWhile in Rust, you would probably use `assert_eq!()` in conjunction with `Err()`.\n\n[^pytest]: <https://docs.pytest.org/en/7.1.x/reference/reference.html#pytest-raises>\n[^catch2]: <https://github.com/catchorg/Catch2/tree/devel>\n\n\nBut in Zig, we use the `expectError()` function, from the `std.testing` module.\nWith this function, you can test if a specific function call returns the exact\ntype of error that you expect it to return. To use this function, you first write\n`try expectError()`. Then, on the first argument, you provide the type of error that you\nare expecting from the function call. Then, on the second argument, you write\nthe function call that you expect to fail.\n\nThe code example below demonstrates such type of unit test in Zig.\nNotice that, inside the function `alloc_error()` we are allocating\n100 bytes of memory, or, an array of 100 elements, for the object `ibuffer`. However,\nin the `test` block, we are using the `FixedBufferAllocator()`\nallocator object, which is limited to 10 bytes of space, because\nthe object `buffer`, which we provided to the allocator object,\nhave only 10 bytes of space.\n\nThat is why, the `alloc_error()` function raises an `OutOfMemory` error\non this case.\nBecause this function is trying to allocate more space than the allocator\nobject allows.\nSo, in essence, we are testing for a specific type of error,\nwhich is `OutOfMemory`. If the `alloc_error()` function returns any other type of error,\nthen, the `expectError()` function would make the entire test fail.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst expectError = std.testing.expectError;\nfn alloc_error(allocator: Allocator) !void {\n    var ibuffer = try allocator.alloc(u8, 100);\n    defer allocator.free(ibuffer);\n    ibuffer[0] = 2;\n}\n\ntest \"testing error\" {\n    var buffer: [10]u8 = undefined;\n    var fba = std.heap.FixedBufferAllocator.init(&buffer);\n    const allocator = fba.allocator();\n    try expectError(error.OutOfMemory, alloc_error(allocator));\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file3d7d15bc8ea0.test.testing error...OKAll 1 \n   tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n## Testing simple equalities\n\nIn Zig, there are some different ways you can test for an equality.\nYou already saw that we can use `expect()` with the logical operator `==`\nto essentially reproduce an equality test. But we also have\nsome other helper functions that you should know about, especially\n`expectEqual()`, `expectEqualSlices()` and `expectEqualStrings()`.\n\n\nThe `expectEqual()` function, as the name suggests, is a classic\ntest equality function. It receives two objects as input. The first\nobject is the value that you expect to be in the second object.\nWhile second object is the object you have, or, the object that your application\nproduced as result. So, with `expectEqual()` you are essentially\ntesting if the values stored inside these two objects\nare equal or not.\n\nYou can see in the example below that, the test performed by\n`expectEqual()` failed. Because the objects `v1` and `v2` contain\ndifferent values in them.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"values are equal?\" {\n    const v1 = 15;\n    const v2 = 18;\n    try std.testing.expectEqual(v1, v2);\n}\n```\n:::\n\n\n\n```\n1/1 ve.test.values are equal?...\n    expected 15, found 18\n    FAIL (TestExpectedEqual)\nve.zig:5:5: test.values are equal? (test)\n    try std.testing.expectEqual(v1, v2);\n    ^\n0 passed; 0 skipped; 1 failed.\n```\n\n\nAlthough useful, the `expectEqual()` function does not work with arrays.\nFor testing if two arrays are equal, you should use the `expectEqualSlices()`\nfunction instead. This function have three arguments. First, you provide\nthe data type contained in both arrays that you are trying to compare.\nWhile the second and third arguments corresponds to the array objects that you want to compare.\n\nIn the example below, we are using this function to test if two array\nobjects (`array1` and `array2`) are equal or not. Since they\nare in fact equal, the unit test passed with no errors.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"arrays are equal?\" {\n    const array1 = [3]u32{1, 2, 3};\n    const array2 = [3]u32{1, 2, 3};\n    try std.testing.expectEqualSlices(\n        u32, &array1, &array2\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file3d7d7d8ccdbb.test.arrays are equal?...OKAl\n  ll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\nAt last, you might also want to use the `expectEqualStrings()` function.\nAs the name suggests, you can use this function to test if two strings\nare equal or not. Just provide the two string objects that you want to compare,\nas inputs to the function.\n\nIf the function finds any existing differences between the two strings,\nthen, the function will raise an error, and also, print an error message\nthat shows the exact difference between the two string objects provided,\nas the example below demonstrates:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"strings are equal?\" {\n    const str1 = \"hello, world!\";\n    const str2 = \"Hello, world!\";\n    try std.testing.expectEqualStrings(\n        str1, str2\n    );\n}\n```\n:::\n\n\n\n```\n1/1 t.test.strings are equal?...\n====== expected this output: =========\nhello, world!␃\n======== instead found this: =========\nHello, world!␃\n======================================\nFirst difference occurs on line 1:\nexpected:\nhello, world!\n^ ('\\x68')\nfound:\nHello, world!\n^ ('\\x48')\n```\n",
+    "supporting": [
+      "03-unittests_files"
+    ],
+    "filters": [
+      "rmarkdown/pagebreak.lua"
+    ],
+    "includes": {},
+    "engineDependencies": {
+      "knitr": [
+        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
+      ]
+    },
+    "preserve": null,
+    "postProcess": false
+  }
+}
\ No newline at end of file
diff --git a/_freeze/Chapters/04-http-server/execute-results/epub.json b/_freeze/Chapters/04-http-server/execute-results/epub.json
new file mode 100644
index 00000000..ddf9953a
--- /dev/null
+++ b/_freeze/Chapters/04-http-server/execute-results/epub.json
@@ -0,0 +1,21 @@
+{
+  "hash": "f64c88659b4b19943ce530d1245b8add",
+  "result": {
+    "engine": "knitr",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Project 2 - Building a HTTP Server from scratch\n\nIn this chapter, I want to implement a new\nsmall project with you. This time, we are going\nto implement a basic HTTP Server from scratch.\n\nThe Zig Standard Library already have a HTTP Server\nimplemented, which is available at `std.http.Server`.\nBut again, our objective here in this chapter, is to implement\nit **from scratch**. So we can't use this server object available\nfrom the Zig Standard Library.\n\n## What is a HTTP Server?\n\nFirst of all, what is a HTTP Server?\nA HTTP server, as any other type of server, is essentially\na program that runs indefinitely, on an infinite loop, waiting for incoming connections\nfrom clients. Once the server receives an incoming connection, it will\naccept this connection, and it will send messages back-and-forth to the client\nthrough this connection.\n\nBut the messages that are transmitted inside this connection are in a\nspecific format. They are HTTP messages\n(i.e., messages that use the HTTP Protocol specification).\nThe HTTP Protocol is the backbone of the modern web.\nThe world wide web as we know it today, would not exist without the\nHTTP Protocol.\n\nSo, Web servers (which is just a fancy name to\nHTTP Servers) are servers that exchange HTTP messages with clients.\nAnd these HTTP servers and the HTTP Protocol specification\nare essential to the operation of the world wide web today.\n\nThat is the whole picture of the process.\nAgain, we have two subjects involved here, a server (which is\na program that is running indefinitely, waiting to receive incoming connections),\nand a client (which is someone that wants to connect to the server,\nand exchange HTTP messages with it).\n\nYou may find the material about the [HTTP Protocol available at the Mozilla MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview)[^mdn-http]\n, a great resource for you to also look at. It gives you a great overview on how\nHTTP works, and what role the server plays in this matter.\n\n[^mdn-http]: <https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview>.\n\n\n## How a HTTP Server works? {#sec-how-http-works}\n\nImagine a HTTP Server as if it were the receptionist of a large hotel. In a hotel,\nyou have a reception, and inside that reception there is a receptionist\nwaiting for customers to arrive. A HTTP Server is essentially a receptionist\nthat is indefinitely waiting for new customers (or, in the context of HTTP, new clients)\nto arrive in the hotel.\n\nWhen a customer arrives at the hotel, that customer starts a conversation with the\nreceptionist. He tells the receptionist how many days he wants to stay at the hotel.\nThen, the receptionist search for an available apartment. If there is an available apartment\nat the moment, the customer pays the hotel fees, then, he gets the keys to the apartment,\nand then, he goes to the apartment to rest.\n\nAfter this entire process of dealing with the customer (searching for available apartments,\nreceiving payment, handing over the keys), the receptionist goes back to what he was\ndoing earlier, which is to wait. Wait for new customers to arrive.\n\nThat is, in a nutshell, what a HTTP Server do. It waits for clients to connect to the\nserver. When a client attempts to connect to the server, the server accepts this connection,\nand it starts to exchange messages with the client through this connection.\nThe first message that happens inside this connection is always a message from the client\nto the server. This message is called the *HTTP Request*.\n\nThis HTTP Request is a HTTP message that contains what\nthe client wants from the server. It is literally a request. The client\nthat connected to the server is asking this server to do something for him.\n\nThere are different \"types of request\" that a client can send to a HTTP Server.\nBut the most basic type of request, is when a client ask to the\nHTTP Server to serve (i.e., to send) some specific web page (which is a HTML file) to him.\nWhen you type `google.com` in your web browser, you are essentially sending a HTTP Request to Google's\nHTTP servers. This request is asking these servers to send the Google webpage to you.\n\nNonetheless, when the server receives this first message, the *HTTP Request*, it\nanalyzes this request, to understand: who the client is? What he wants the server to do?\nThis client has provided all the necessary information to perform the action that he\nasked? Etc.\n\nOnce the server understands what the client wants, he simply perform the action\nthat was requested, and, to finish the whole process, the server sends back\na HTTP message to the client, informing if the action performed was successful or not,\nand, at last, the server ends (or closes) the connection with the client.\n\nThis last HTTP message sent from the server to the client, is called the *HTTP Response*.\nBecause the server is responding to the action that was requested by the client.\nThe main objective of this response message is let the client know if the\naction requested was successful or not, before the server closes the connection.\n\n\n## How a HTTP server is normally implemented? {#sec-http-how-impl}\n\nLet's use the C language as an example. There are many materials\nteaching how to write a simple HTTP server in C code, like @jeffrey_http,\nor @nipun_http, or @eric_http.\nHaving this in mind, I will not show C code examples here, because you\ncan find them on the internet.\nBut I will describe the theory behind the necessary steps to create\nsuch HTTP server in C.\n\n\nIn essence, we normally implement a HTTP server in C by using a TCP socket,\nwhich involves the following steps:\n\n1. Create a TCP socket object.\n1. Bind a name (or more specifically, an address) to this socket object.\n1. Make this socket object to start listening and waiting for incoming connections.\n1. When a connection arrive, we accept this connection, and we exchange the HTTP messages (HTTP Request and HTTP Response).\n1. Then, we simply close this connection.\n\n\nA socket object is essentially a channel of communication.\nYou are creating a channel where people can send messages through.\nWhen you create a socket object, this object is not binded to any particular\naddress. This means that with this object you have a representation of a channel of communication\nin your hands. But this channel is not currently available, or, it is not currently accessible,\nbecause it does not have a known address where you can find it.\n\nThat is what the \"bind\" operation do. It binds a name (or more specifically, an address) to\nthis socket object, or, this channel of communication, so that it becomes available,\nor, accessible through this address. While the \"listen\" operation makes the socket object to\nlisten for incoming connections in this address. In other words, the \"listen\" operation\nmakes the socket wait for incoming connections.\n\nNow, when a client actually attempts to connect to the server through the socket address\nthat we have specified, in order to establish this connection with the client,\nthe socket object needs to accept this incoming connection. Thus, when we\naccept an incoming connection, the client and the server become\nconnected to each other, and they can start reading or writing messages into this\nestablished connection.\n\nAfter we receive the HTTP Request from the client, analyze it, and send the HTTP Response\nto the client, we can then close the connection, and end this communication.\n\n\n## Implementing the server - Part 1\n\n### Creating the socket object {#sec-create-socket}\n\nLet's begin with creating the socket object for our server.\nJust to make things shorter, I will create this socket object in\na separate Zig module. I will name it `config.zig`.\n\nIn Zig, we can create a TCP socket using\nthe `std.posix.socket()` function, from the Zig Standard Library.\nAs I mentioned earlier in @sec-http-how-impl, every socket object that we create\nrepresents a communication channel, and we need to bind this channel to a specific address.\nAn \"address\" is defined as an IP address, or, more specifically, an IPv4 address^[It can be also an IPv6 address. But normally, we use a IPv4 address for that.].\nEvery IPv4 address is composed by two components. The first component is the host,\nwhich is a sequence of 4 numbers separated by dot characters (`.`) that identifies the machine used.\nWhile the second component is a port number, which identifies the specific\ndoor, or, the specific port to use in the host machine.\n\nThe sequence of 4 numbers (i.e., the host) identifies the machine (i.e., the computer itself) where\nthis socket will live in. Every computer normally have multiple \"doors\" available inside of him, because\nthis allows the computer to receive and work with multiple connections at the same time.\nHe simply use a single door for each connection. So the port number, is\nessentially a number that identifies the specific door in the computer that will be responsible\nfor receiving the connection. That is, it identifies the \"door\" in the computer that the socket will use\nto receive incoming connections.\n\nTo make things simpler, I will use an IP address that identifies our current machine in this example.\nThis means that, our socket object will reside on the same computer that we are currently using\n(this is also known as the \"localhost\") to write this Zig source code.\n\nBy convention, the IP address that identifies the \"localhost\", which is the current machine we\nare using, is the IP `127.0.0.1`. So, that is the IP\naddress we are going to use in our server. I can declare it in Zig\nby using an array of 4 integers, like this:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst localhost = [4]u8{ 127, 0, 0, 1 };\n_ = localhost;\n```\n:::\n\n\n\nNow, we need to decide which port number to use. By convention, there are some\nport numbers that are reserved, meaning that, we cannot use them for our own\npurposes, like the port 22 (which is normally used for SSH connections).\nFor TCP connections, which is our case here,\na port number is a 16-bit unsigned integer (type `u16` in Zig),\nthus ranging from 0 to 65535 [@wikipedia_port].\nSo, we can choose\na number from 0 to 65535 for our port number. In the\nexample of this book, I will use the port number 3490\n(just a random number).\n\n\nNow that we have these two informations at hand, I can\nfinally create our socket object, using the `std.posix.socket()` function.\nFirst, we use the host and the port number to create an `Address` object,\nwith the `std.net.Address.initIp4()` function, like in the example below.\nAfter that, I use this address object inside the `socket()` function\nto create our socket object.\n\nThe `Socket` struct defined below summarizes all the logic behind\nthis process. In this struct, we have two data members, which are:\n1)  the address object; 2) and a stream object, which is\nthe object we will use to read and write the messages into any connection we establish.\n\nNotice that, inside the constructor method of this struct,\nwhen we create the socket object, we are using the `IPROTO.TCP` property as an input to\ntell the function to create a socket for TCP connections.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\nconst net = @import(\"std\").net;\n\npub const Socket = struct {\n    _address: std.net.Address,\n    _stream: std.net.Stream,\n\n    pub fn init() !Socket {\n        const host = [4]u8{ 127, 0, 0, 1 };\n        const port = 3490;\n        const addr = net.Address.initIp4(host, port);\n        const socket = try std.posix.socket(\n            addr.any.family,\n            std.posix.SOCK.STREAM,\n            std.posix.IPPROTO.TCP\n        );\n        const stream = net.Stream{ .handle = socket };\n        return Socket{ ._address = addr, ._stream = stream };\n    }\n};\n```\n:::\n\n\n\n\n### Listening and receiving connections\n\nRemember that we stored the `Socket` struct\ndeclaration that we built in @sec-create-socket inside a Zig module named `config.zig`.\nThis is why I imported this module into our main module (`main.zig`) in the example below, as the `SocketConf` object,\nto access the `Socket` struct.\n\nOnce we created our socket object, we can focus now on making this socket object\nlisten and receive new incoming connections. We do that, by calling the `listen()`\nmethod from the `Address` object that is contained inside the socket object, and then,\nwe call the `accept()` method over the result.\n\nThe `listen()` method from the `Address` object produces a server object,\nwhich is an object that will stay open and running indefinitely, waiting\nto receive an incoming connection. Therefore, if you try to run the code\nexample below, by calling the `run` command from the `zig` compiler,\nyou will notice that the programs keeps running indefinitely,\nwithout a clear end.\n\nThis happens, because the program is waiting for something to happen.\nIt's waiting for someone to try to connect to the address (`http://127.0.0.1:3490`) where\nthe server is running and listening for incoming connections. This is what\nthe `listen()` method do, it makes the socket to be active waiting for someone\nto connect.\n\nOn the other side, the `accept()` method is the function that establishes the connection\nwhen someone tries to connect to the socket. This means that, the `accept()` method\nreturns a new connection object as a result. And you can use this connection object\nto read or write messages from or to the client.\nFor now, we are not doing anything with this connection object.\nBut we are going to use it in the next section.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n    _ = connection;\n}\n```\n:::\n\n\n\nThis code example allows one single connection. In other words, the\nserver will wait for one incoming connection, and as soon as the\nserver is done with this first connection that it establishes, the\nprogram ends, and the server stops.\n\nThis is not the norm in the real world. Most people that write\na HTTP server like this, usually put the `accept()` method\ninside a `while` (infinite) loop, where if a connection\nis created with `accept()`, a new thread of execution is created to deal with\nthis new connection and the client. That is, real-world examples of HTTP Servers\nnormally rely on parallel computing to work.\n\nWith this design, the server simply accepts the connection,\nand the whole process of dealing with the client, and receiving\nthe HTTP Request, and sending the HTTP Response, all of this\nis done in the background, on a separate execution thread.\n\nSo, as soon as the server accepts the connection, and creates\nthe separate thread, the server goes back to what he was doing earlier,\nwhich is to wait indefinitely for a new connection to accept.\nHaving this in mind, the code example exposed above, is a\nserver that serves only a single client. Because the program\nterminates as soon as the connection is accepted.\n\n\n\n### Reading the message from the client {#sec-read-http-message}\n\nNow that we have a connection established, i.e., the connection\nobject that we created through the `accept()` function, we can now\nuse this connection object to read any messages that the client\nsend to our server. But we can also use it to send messages back\nto the client.\n\nThe basic idea is, if we **write** any data into this connection object,\nthen, we are sending data to the client, and if we **read** the data present in\nthis connection object, then, we are reading any data that the\nclient sent to us, through this connection object. So, just\nhave this logic in mind. \"Read\" is for reading messages from the client,\nand \"write\" is to send a message to the client.\n\nRemember from @sec-how-http-works that, the first thing that we need to do is to read the HTTP Request\nsent by the client to our server. Because it is the first message that happens\ninside the established connection, and, as a consequence, it is the first\nthing that we need to deal with.\n\nThat is why, I'm going to create a new Zig module in this small project, named `request.zig`\nto keep all functions related to the HTTP Request\ntogether. Then, I will create a new function named `read_request()` that will\nuse our connection object to read the message sent by the client,\nwhich is the HTTP Request.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Connection = std.net.Server.Connection;\npub fn read_request(conn: Connection,\n                    buffer: []u8) !void {\n    const reader = conn.stream.reader();\n    _ = try reader.read(buffer);\n}\n```\n:::\n\n\n\n\nThis function accepts a slice object which behaves as a buffer.\nThe `read_request()` function reads the message sent into\nthe connection object, and saves this message into this buffer object that\nwe have provided as input.\n\nNotice that I'm using the connection object that we created to read\nthe message from the client. I first access the `reader` object that lives inside the\nconnection object. Then, I call the `read()` method of this `reader` object\nto effectively read and save the data sent by the client into the buffer object\nthat we created earlier. I'm discarding the return value\nof the `read()` method, by assigning it to the underscore character (`_`),\nbecause this return value is not useful for us right now.\n\n\n\n## Looking at the current state of the program\n\n\nI think now is a good time to see how our program is currently working. Shall we?\nSo, the first thing I will do is to update the `main.zig` module in our small Zig project,\nso that the `main()` function call this new `read_request()` function that we have just created.\nI will also add a print statement at the end of the `main()` function,\njust so that you can see what the HTTP Request that we have just loaded into the buffer object\nlooks like.\n\nAlso, I'm creating the buffer object in the `main()` function, which will be\nresponsible for storing the message sent by the client, and, I'm also\nusing a `for` loop to initialize all fields of this buffer object to the number zero.\nThis is important to make sure that we don't have uninitialized memory in\nthis object. Because uninitialized memory may cause undefined behaviour in our program.\n\nSince the `read_request()` function should receive as input the buffer object as a slice object (`[]u8`),\nI am using the syntax `array[0..array.len]` to get access to a slice of this `buffer` object.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    _ = try Request.read_request(\n        connection, buffer[0..buffer.len]\n    );\n    try stdout.print(\"{s}\\n\", .{buffer});\n}\n```\n:::\n\n\n\nNow, I'm going to execute this program, with the `run` command from the\n`zig` compiler. But remember, as we sad earlier, as soon as I execute this program, it will\nhang indefinitely, because the program is waiting for a client trying to\nconnect to the server.\n\nMore specifically, the program will pause at the line\nwith the `accept()` call. As soon as a client try to connect to the\nserver, then, the execution will \"unpause\", and the `accept()` function\nwill finally be executed to create the\nconnection object that we need, and the remaining of the program\nwill run.\n\nYou can see that in @fig-print-zigrun1. The message `Server Addr: 127.0.0.1:3490`\nis printed to the console, and the program is now waiting for an incoming connection.\n\n![A screenshot of running the program](./../Figures/print-zigrun1.png){#fig-print-zigrun1}\n\n\nWe can finally try to connect to this server, and there are several ways we can do this.\nFor example, we could use the following Python script:\n\n```python\nimport requests\nrequests.get(\"http://127.0.0.1:3490\")\n```\n\nOr, we could also open any web browser of our preference, and type\nthe URL `localhost:3490`. OBS: `localhost` is the same thing as the\nIP `127.0.0.1`. When you press enter, and your web browser go\nto this address, first, the browser will probably print a message\nsaying that \"this page isn't working\", and, then, it will\nprobably change to a new message saying that \"the site can't be\nreached\".\n\nYou get these \"error messages\" in the web browser, because\nit got no response back from the server. In other words, when the web\nbrowser connected to our server, it did send the HTTP Request through the established connection.\nThen, the web browser was expecting to receive a HTTP Response back, but\nit got no response from the server (we didn't implemented the HTTP Response logic yet).\n\nBut that is okay. We have achieved the result that we wanted for now,\nwhich is to connect to the server, and see the HTTP Request\nthat was sent by the web browser (or by the Python script)\nto the server.\n\nIf you comeback to the console that you left open\nwhen you have executed the program, you will see that the\nprogram finished its execution, and, a new message is\nprinted in the console, which is the actual HTTP Request\nmessage that was sent by the web browser to the server.\nYou can see this message in @fig-print-zigrun2.\n\n![A screenshot of the HTTP Request sent by the web browser](./../Figures/print-zigrun2.png){#fig-print-zigrun2}\n\n\n\n\n## Learning about Enums in Zig {#sec-enum}\n\nEnums structures are available in Zig through the `enum` keyword.\nAn enum (short for \"enumeration\") is a special structure that represents a group of constant values.\nSo, if you have a variable which can assume a short and known\nset of values, you might want to associate this variable to an enum structure,\nto make sure that this variable only assumes a value from this set.\n\nA classic example for enums are primary colors. If for some reason, your program\nneeds to represent one of the primary colors, you can create an enum\nthat represents one of these colors.\nIn the example below, we are creating the enum `PrimaryColorRGB`, which\nrepresents a primary color from the RGB color system. By using this enum,\nI am guaranteed that the `acolor` object for example, will contain\none of these three values: `RED`, `GREEN` or `BLUE`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst PrimaryColorRGB = enum {\n    RED, GREEN, BLUE\n};\nconst acolor = PrimaryColorRGB.RED;\n_ = acolor;\n```\n:::\n\n\n\nIf for some reason, my code tries to save in `acolor`,\na value that is not in this set, I will get an error message\nwarning me that a value such as \"MAGENTA\" do not exist\ninside the `PrimaryColorRGB` enum.\nThen I can easily fix my mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst acolor = PrimaryColorRGB.MAGENTA;\n```\n:::\n\n\n\n```\ne1.zig:5:36: error: enum 'PrimaryColorRGB' has\n        no member named 'MAGENTA':\n    const acolor = PrimaryColorRGB.MAGENTA;\n                                   ^~~~~~~\n```\n\nBehind the hood, enums in Zig work the same way that enums\nwork in C. Each enum value is essentially represented as an integer.\nThe first value in the set is represented as zero,\nthen, the second value is one, ... etc.\n\nOne thing that we are going to learn in the next section is that\nenums can have methods in them. Wait... What? This is amazing!\nYes, enums in Zig are similar to structs, and they can have\nprivate and public methods inside them.\n\n\n\n\n\n\n\n## Implementing the server - Part 2\n\nNow, on this section, I want to focus on parsing\nthe HTTP Request that we received from the client.\nHowever, to effectively parse a HTTP Request message, we first need to understand its\nstructure.\nIn summary, a HTTP Request is a text message that is divided into 3 different\nsections (or parts):\n\n- The top-level header indicating the method of the HTTP Request, the URI, and the HTTP version used in the message.\n- A list of HTTP Headers.\n- The body of the HTTP Request.\n\n### The top-level header\n\nThe first line of text in a HTTP Request always come with the three most essential\ninformation about the request. These three key attributes of the HTTP Request\nare separated by a simple space in this first line of the request.\nThe first information is the HTTP method that is being\nused in the request, second, we have the URI to which this HTTP Request is being sent to,\nand third, we have the version of the HTTP protocol that is being used in this HTTP Request.\n\nIn the snippet below, you can find an example of this first line in a HTTP Request.\nFirst, we have the HTTP method of this request (`GET`). Many programmers\nrefer to the URI component (`/users/list`) as the \"API endpoint\" to which the HTTP Request\nis being sent to. In the context of this specific request, since it's a GET request,\nyou could also say that the URI component is the path to the resource we want to access,\nor, the path to the document (or the file) that we want to retrieve from the server.\n\n```\nGET /users/list HTTP/1.1\n```\n\nAlso, notice that this HTTP Request is using the version 1.1 of the HTTP protocol,\nwhich is the most popular version of the protocol used in the web.\n\n\n\n### The list of HTTP headers\n\nMost HTTP Requests also include a section of HTTP Headers,\nwhich is just a list of attributes or key-value pairs associated with this\nparticular request. This section always comes right after the \"top-level header\" of the request.\n\nFor our purpose in this chapter, which is to build a simple HTTP Server,\nwe are going to ignore this section of the HTTP Request, for simplicity.\nBut most HTTP servers that exist in the wild parses and use these\nHTTP headers to change the way that the server responds to the request\nsent by the client.\n\nFor example, many requests we encounter in the real-world comes with\na HTTP header called `Accept`. In this header, we find a list of [MIME types](https://en.wikipedia.org/wiki/Media_type)[^mime].\nThis list indicates the file formats that the client can read, or parse, or interpret.\nIn other words, you also interpret this header as the client saying the following phrase\nto the server: \"Hey! Look, I can read only HTML documents, so please, send me back\na document that is in a HTML format.\".\n\n[^mime]: <https://en.wikipedia.org/wiki/Media_type>.\n\nIf the HTTP server can read and use this `Accept` header, then, the server can identify\nwhich is the best file format for the document to be sent to the client. Maybe the HTTP server have\nthe same document in multiple formats, for example, in JSON, in XML, in HTML and in PDF,\nbut the client can only understand documents in the HTML format. That is the purpose\nof this `Accept` header.\n\n\n### The body\n\nThe body comes after the list of HTTP headers, and it's an optional section of the HTTP Request, meaning that, not\nall HTTP Requests will come with a body in them. For example, every HTTP Request that uses the\nGET method usually does not come with a body.\n\nBecause a GET request is used to request data, instead of sending it to the server.\nSo, the body section is more related to the POST method, which is a method that involves\nsending data to the server, to be processed and stored.\n\nSince we are going to support only the GET method in this project, it means that\nwe also do not need to care about the body of the request.\n\n\n\n### Creating the HTTP Method enum\n\nEvery HTTP Request comes with a explicit method. The method used in a HTTP Request\nis identified by one these words:\n\n- GET;\n- POST;\n- OPTIONS;\n- PATCH;\n- DELETE;\n- and some other methods.\n\nEach HTTP method is used for a specific type of task. The POST method for example is normally\nused to post some data into the destination. In other words, it's used\nto send some data to the HTTP server, so that it can be processed and stored by the server.\n\nAs another example, the GET method is normally used to get content from the server.\nIn other words, we use this method whenever we want the server to send some\ncontent back to us. It can be any type of content. It can be a web page,\na document file, or some data in a JSON format.\n\nWhen a client sends a POST HTTP Request, the HTTP Response sent by the server normally have the sole purpose of\nletting the client know if the server processed and stored the data successfully.\nIn contrast, when the server receives a GET HTTP Request, then, the server sends the content\nthat the client asked for in the HTTP Response itself. This demonstrates that the method associated\nwith the HTTP Request changes a lot on the dynamics and the roles that each party\nplays in the whole process.\n\nSince the HTTP method of the HTTP Request is identified by this very small and specific\nset of words, it would be interesting to create an enum structure to represent a HTTP method.\nThis way, we can easily check if the HTTP Request we receive from the client is a\nHTTP method that we currently support in our small HTTP server project.\n\nThe `Method` structure below represents this enumeration.\nNotice that, for now, only the GET HTTP method is included in this\nenumeration. Because, for the purpose of this chapter, I want to\nimplement only the GET HTTP method. That is why I am not\nincluding the other HTTP methods in this enumeration.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const Method = enum {\n    GET\n};\n```\n:::\n\n\n\n\nNow, I think we should add two methods to this enum structure. One method is `is_supported()`,\nwhich will be a function that returns a boolean value, indicating if the input HTTP method is supported\nor not by our HTTP Server. The other is `init()`, which is a constructor function that takes a string as input,\nand tries to convert it into a `Method` value.\n\n\nBut in order to build these functions, I will use a functionality from the Zig Standard Library, called\n`StaticStringMap()`. This function allows us to create a simple map from strings to enum values.\nIn other words, we can use this map structure to map a string to the respective enum value.\nTo some extent, this specific structure from the standard library works almost like a \"hashtable\" structure,\nand it's optimized for small sets of words, or, small sets of keys, which is our case here.\nWe are going to talk more about hashtables in Zig in @sec-maps-hashtables.\n\nTo use this \"static string map\" structure, you have to import it from the `std.static_string_map` module\nof the Zig Standard Library. Just to make things shorter and easier to type, I am going to import this\nfunction through a different and shorter name (`Map`).\n\nWith `Map()` imported, we can just apply this function over the enum structure\nthat we are going to use in the resulting map. In our case here, it's the `Method` enum structure\nthat we declared at the last code example. Then, I call the `initComptime()` method with the\nmap, i.e., the list of key-value pairs that we are going to use.\n\nYou can see in the example below that I wrote this map using multiple anonymous struct literals.\nInside the first (or \"top-level\") struct literal, we have a list (or a sequence) of struct literals.\nEach struct literal in this list represents a separate key-value pair. The first element (or the key)\nin each key-value pair should always be a string value. While the second element should\nbe a value from the enum structure that you have used inside the `Map()` function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Map = std.static_string_map.StaticStringMap;\nconst MethodMap = Map(Method).initComptime(.{\n    .{ \"GET\", Method.GET },\n});\n```\n:::\n\n\n\nTherefore, the `MethodMap` object is basically a `std::map` object from C++, or,\na `dict` object from Python. You can retrieve (or get) the enum value that\ncorresponds to a particular key, by using the `get()` method from the map\nobject. This method returns an optional value, so, the `get()` method might\nresult in a null value.\n\nWe can use this in our advantage to detect if a particular HTTP method is\nsupported or not in our HTTP server. Because, if the `get()` method returns null,\nit means that it did not found the method that we provided inside the `MethodMap` object, and,\nas a consequence, this method is not supported by our HTTP server.\n\nThe `init()` method below, takes a string value as input, and then, it simply passes this string value\nto the `get()` method of our `MethodMap` object. As consequence, we should get the enum value that corresponds\nto this input string.\n\nNotice in the example below that, the `init()` method returns either an error\n(which might happen if the `?` method returns `unreacheable`, checkout @sec-null-handling for more details)\nor a `Method` object as result. Since `GET` is currently the only value in our `Method` enum\nstructure, it means that, the `init()` method will most likely return the value `Method.GET` as result.\n\nAlso notice that, in the `is_supported()` method, we are using the optional value returned\nby the `get()` method from our `MethodMap` object. The if statement unwraps the optional value\nreturned by this method, and returns `true` in case this optional value is a not-null value.\nOtherwise, it simply returns `false`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const Method = enum {\n    GET,\n    pub fn init(text: []const u8) !Method {\n        return MethodMap.get(text).?;\n    }\n    pub fn is_supported(m: []const u8) bool {\n        const method = MethodMap.get(m);\n        if (method) |_| {\n            return true;\n        }\n        return false;\n    }\n};\n```\n:::\n\n\n\n\n\n\n\n\n\n### Writing the parse request function\n\nNow that we created the enum that represents our HTTP method,\nwe should start to write the function responsible for\nactually parsing the HTTP Request.\n\nThe first thing we can do, is to write a struct to represent the HTTP Request.\nTake the `Request` struct below as an example. It contains the three\nessential information from the \"top-level\" header (i.e., the first line)\nin the HTTP Request.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Request = struct {\n    method: Method,\n    version: []const u8,\n    uri: []const u8,\n    pub fn init(method: Method,\n                uri: []const u8,\n                version: []const u8) Request {\n        return Request{\n            .method = method,\n            .uri = uri,\n            .version = version,\n        };\n    }\n};\n```\n:::\n\n\n\n\nThe `parse_request()` function should receive a string as input. This input string\ncontains the entire HTTP Request message, and the parsing function should\nread and understand the individual parts of this message.\n\nNow, remember that for the purpose of this chapter, we care only about the first\nline in this message, which contains the \"top-level header\", or, the three essential attributes about the HTTP Request,\nwhich are the HTTP method used, the URI and the HTTP version.\n\nNotice that I use the function `indexOfScalar()` in `parse_request()`. This function from the\nZig Standard Library returns the first index where the scalar value that we provide\nhappens in a string. In this case, I'm looking at the first occurrence of the new line character (`\\n`).\nBecause once again, we care only about the first line in the HTTP Request message.\nThis is the line where we have the three information that we want to parse\n(version of HTTP, the HTTP method and the URI).\n\nTherefore, we are using this `indexOfScalar()` function\nto limit our parsing process to the first line in the message.\nIt's also worth mentioning that, the `indexOfScalar()` function returns an optional value.\nThat is why I use the `orelse` keyword to provide an alternative value, in case\nthe value returned by the function is a null value.\n\nSince each of these three attributes are separated by a simple space, we\ncould use the function `splitScalar()` from the Zig Standard Library to split\nthe input string into sections by looking for every position that appears\na simple space. In other words, this `splitScalar()` function is equivalent\nto the `split()` method in Python, or, the `std::getline()` function from C++,\nor the `strtok()` function in C.\n\nWhen you use this `splitScalar()` function, you get an iterator as the result.\nThis iterator have a `next()` method that you can use to advance the iterator\nto the next position, or, to the next section of the splitted string.\nNote that, when you use `next()`, the method not only advances the iterator,\nbut it also returns a slice to the current section of the splitted\nstring as result.\n\nNow, if you want to get a slice to the current section of the splitted\nstring, but not advance the iterator to the next position, you can use\nthe `peek()` method. Both `next()` and `peek()` methods return an optional value, that is\nwhy I use the `?` method to unwrap these optional values.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn parse_request(text: []u8) Request {\n    const line_index = std.mem.indexOfScalar(\n        u8, text, '\\n'\n    ) orelse text.len;\n    var iterator = std.mem.splitScalar(\n        u8, text[0..line_index], ' '\n    );\n    const method = try Method.init(iterator.next().?);\n    const uri = iterator.next().?;\n    const version = iterator.next().?;\n    const request = Request.init(method, uri, version);\n    return request;\n}\n```\n:::\n\n\n\n\nAs I described in @sec-zig-strings, strings in Zig are simply arrays of bytes in the language.\nSo, you will find lots of excellent utility functions to work directly with strings\ninside this `mem` module from the Zig Standard Library.\nWe have described some of these useful utility functions already\nin @sec-strings-useful-funs.\n\n\n\n### Using the parse request function\n\nNow that we wrote the function responsible for parsing the HTTP Request,\nwe can add the function call to `parse_request()` in\nthe `main()` function of our program.\n\nAfter that, is a good idea to test once again the state of our program.\nI execute this program again with the `run` command from the `zig` compiler,\nthen, I use my web browser to connect once again to the server through the URL `localhost:3490`, and finally,\nthe end result of our `Request` object is printed to the console.\n\nA quick observation, since I have used the `any` format specifier in the\nprint statement, the data members `version` and `uri` of the `Request`\nstruct were printed as raw integer values. String data being printed\nas integer values is common in Zig, and remember, these integer values are just the decimal representation of\nthe bytes that form the string in question.\n\nIn the result below, the sequence of decimal values 72, 84, 84, 80, 47, 49, 46, 49, and 13,\nare the bytes that form the text \"HTTP/1.1\". And the integer 47, is the decimal value of\nthe character `/`, which represents our URI in this request.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    try Request.read_request(\n        connection, buffer[0..buffer.len]\n    );\n    const request = Request.parse_request(\n        buffer[0..buffer.len]\n    );\n    try stdout.print(\"{any}\\n\", .{request});\n}\n```\n:::\n\n\n\n```\nrequest.Request{\n    .method = request.Method.GET,\n    .version = {72, 84, 84, 80, 47, 49, 46, 49, 13},\n    .uri = {47}\n}\n```\n\n\n\n### Sending the HTTP Response to the client\n\nIn this last part, we are going to write the logic responsible for\nsending the HTTP Response from the server to the client. To make things\nsimple, the server in this project will send just a simple web page\ncontaining the text \"Hello world\".\n\nFirst, I create a new Zig module in the project, named `response.zig`.\nIn this module, I will declare just two functions. Each function\ncorresponds to a specific status code in the HTTP Response.\nThe `send_200()` function will send a HTTP Response with status code 200\n(which means \"Success\") to the client. While the `send_404()` function sends a response\nwith status code 404 (which means \"Not found\").\n\nThis is definitely not the most ergonomic and adequate way of handling the\nHTTP Response, but it works for our case here. We are just building toy projects\nin this book after all, therefore, the source code that we write do not need to be perfect.\nIt just needs to work!\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Connection = std.net.Server.Connection;\npub fn send_200(conn: Connection) !void {\n    const message = (\n        \"HTTP/1.1 200 OK\\nContent-Length: 48\"\n        ++ \"\\nContent-Type: text/html\\n\"\n        ++ \"Connection: Closed\\n\\n<html><body>\"\n        ++ \"<h1>Hello, World!</h1></body></html>\"\n    );\n    _ = try conn.stream.write(message);\n}\n\npub fn send_404(conn: Connection) !void {\n    const message = (\n        \"HTTP/1.1 404 Not Found\\nContent-Length: 50\"\n        ++ \"\\nContent-Type: text/html\\n\"\n        ++ \"Connection: Closed\\n\\n<html><body>\"\n        ++ \"<h1>File not found!</h1></body></html>\"\n    );\n    _ = try conn.stream.write(message);\n}\n```\n:::\n\n\n\nNotice that both functions receives the connection object as input, and\nuse the `write()` method to write the HTTP Response message directly\ninto this communication channel. As result, the party in the other\nside of the connection (i.e., the client), will receive such message.\n\nMost real-world HTTP Servers will have a single function (or a single struct) to effectively handle\nthe response. It gets the HTTP Request already parsed as input, and then, it tries to build\nthe HTTP Response bit by bit, before the function sends it over the connection.\n\nWe would also have a specialized struct to represent a HTTP Response, and\na lot of methods that would be used to build each part or component of the response object.\nTake the `Response` struct created by the Javascript runtime Bun as an example.\nYou can find this struct in the [`response.zig` module](https://github.com/oven-sh/bun/blob/main/src/bun.js/webcore/response.zig)[^bun-resp]\nin their GitHub project.\n\n[^bun-resp]: <https://github.com/oven-sh/bun/blob/main/src/bun.js/webcore/response.zig>.\n\n\n## The end result\n\nWe can now, update once again our `main()` function to incorporate our new\nfunctions from the `response.zig` module. First, I need to import this module\ninto our `main.zig` module, then, I add the function calls to `send_200()`\nand `send_404()`.\n\nNotice that I'm using if statements to decide which \"response function\" to call,\nbased especially on the URI present in the HTTP Request. If the user asked for\na content (or a document) that is not present in our server, we should respond\nwith a 404 status code. But since we have just a simple HTTP server, with no\nreal documents to send, we can just check if the URI is the root path (`/`)\nor not to decide which function to call.\n\nAlso, notice that I'm using the function `std.mem.eql()` from the Zig Standard Library\nto check if the string from `uri` is equal or not the string `\"/\"`. We have\ndescribed this function already in @sec-strings-useful-funs, so, comeback to\nthat section if you are not familiar yet with this function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst Response = @import(\"response.zig\");\nconst Method = Request.Method;\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    try Request.read_request(connection, buffer[0..buffer.len]);\n    const request = Request.parse_request(\n        buffer[0..buffer.len]\n    );\n    if (request.method == Method.GET) {\n        if (std.mem.eql(u8, request.uri, \"/\")) {\n            try Response.send_200(connection);\n        } else {\n            try Response.send_404(connection);\n        }\n    }\n}\n```\n:::\n\n\n\n\nNow that we adjusted our `main()` function, I can now execute our program, and\nsee the effects of these last changes. First, I execute the program once again, with the\n`run` command of the `zig` compiler. The program will hang, waiting for a client to connect.\n\nThen, I open my web browser, and try to connect to the server again, using the URL `localhost:3490`.\nThis time, instead of getting some sort of an error message from the browser, you will get the message\n\"Hello World\" printed into your web browser. Because this time, the server sended the HTTP Response\nsuccessfully to the web browser, as demonstrated by @fig-print-zigrun3.\n\n\n![The Hello World message sent in the HTTP Response](./../Figures/print-zigrun3.png){#fig-print-zigrun3}\n",
+    "supporting": [
+      "04-http-server_files"
+    ],
+    "filters": [
+      "rmarkdown/pagebreak.lua"
+    ],
+    "includes": {},
+    "engineDependencies": {
+      "knitr": [
+        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
+      ]
+    },
+    "preserve": null,
+    "postProcess": false
+  }
+}
\ No newline at end of file
diff --git a/_freeze/Chapters/05-pointers/execute-results/epub.json b/_freeze/Chapters/05-pointers/execute-results/epub.json
new file mode 100644
index 00000000..8ff2a6f8
--- /dev/null
+++ b/_freeze/Chapters/05-pointers/execute-results/epub.json
@@ -0,0 +1,21 @@
+{
+  "hash": "8201d761dfd46af14c754587b77047a2",
+  "result": {
+    "engine": "knitr",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Pointers and Optionals {#sec-pointer}\n\nOn our next project we are going to build a HTTP server from scratch.\nBut in order to do that, we need to learn more about pointers and how they work in Zig.\nPointers in Zig are similar to pointers in C. But they come with some extra advantages in Zig.\n\nA pointer is an object that contains a memory address. This memory address is the address where\na particular value is stored in memory. It can be any value. Most of the times,\nit's a value that comes from another object (or variable) present in our code.\n\nIn the example below, I'm creating two objects (`number` and `pointer`).\nThe `pointer` object contains the memory address where the value of the `number` object\n(the number 5) is stored. So, that is a pointer in a nutshell. It's a memory\naddress that points to a particular existing value in the memory. You could\nalso say, that, the `pointer` object points to the memory address where the `number` object is\nstored.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number: u8 = 5;\nconst pointer = &number;\n_ = pointer;\n```\n:::\n\n\n\nWe create a pointer object in Zig by using the `&` operator. When you put this operator\nbefore the name of an existing object, you get the memory address of this object as result.\nWhen you store this memory address inside a new object, this new object becomes a pointer object.\nBecause it stores a memory address.\n\nPeople mostly use pointers as an alternative way to access a particular value.\nFor example, I can use the `pointer` object to access the value stored by\nthe `number` object. This operation of accessing the value that the\npointer \"points to\" is normally called of *dereferencing the pointer*.\nWe can dereference a pointer in Zig by using the `*` method of the pointer object. Like in the example\nbelow, where we take the number 5 pointed by the `pointer` object,\nand double it.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number: u8 = 5;\nconst pointer = &number;\nconst doubled = 2 * pointer.*;\nstd.debug.print(\"{d}\\n\", .{doubled});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n10\n```\n\n\n:::\n:::\n\n\n\n\nThis syntax to dereference the pointer is nice. Because we can easily chain it with\nmethods of the value pointed by the pointer. We can use the `User` struct that we have\ncreated in @sec-structs-and-oop as an example. If you comeback to that section,\nyou will see that this struct have a method named `print_name()`.\n\nSo, for example, if we have an user object, and a pointer that points to this user object,\nwe can use the pointer to access this user object, and, at the same time, call the method `print_name()`\non it, by chaining the dereference method (`*`) with the `print_name()` method. Like in the\nexample below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst u = User.init(1, \"pedro\", \"email@gmail.com\");\nconst pointer = &u;\ntry pointer.*.print_name();\n```\n:::\n\n\n\n```\npedro\n```\n\nWe can also use pointers to effectively alter the value of an object.\nFor example, I could use the `pointer` object to set\nthe value of the object `number` to 6, like in the example below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n6\n```\n\n\n:::\n:::\n\n\n\n\nTherefore, as I mentioned earlier, people use pointers as an alternative way to access a particular value.\nAnd they use it especially when they do not want to \"move\" these values around. There are situations where,\nyou want to access a particular value in a different scope (i.e., a different location) of your code,\nbut you do not want to \"move\" this value to this new scope (or location) that you are in.\n\nThis matters especially if this value is big in size. Because if it is, then,\nmoving this value becomes an expensive operation to do.\nThe computer will have to spend a considerable amount of time\ncopying this value to this new location.\n\nTherefore, many programmers prefer to avoid this heavy operation of copying the value\nto the new location, by accessing this value through pointers.\nWe are going to talk more about this \"moving operation\" over the next sections.\nFor now, just keep in mind that avoiding this \"move operation\" is\none of main reasons why pointers are used in programming languages.\n\n\n\n\n\n## Constant objects vs variable objects {#sec-pointer-var}\n\nYou can have a pointer that points to a constant object, or, a pointer that points to a variable object.\nBut regardless of who this pointer is, a pointer **must always respect the characteristics of the object that it points to**.\nAs a consequence, if the pointer points to a constant object, then, you cannot use this pointer\nto change the value that it points to. Because it points to a value that is constant. As we discussed in @sec-assignments, you cannot\nchange a value that is constant.\n\nFor example, if I have a `number` object, which is constant, I cannot execute\nthe expression below where I'm trying to change the value of `number` to 6 through\nthe `pointer` object. As demonstrated below, when you try to do something\nlike that, you get a compile time error:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number = 5;\nconst pointer = &number;\npointer.* = 6;\n```\n:::\n\n\n\n```\np.zig:6:12: error: cannot assign to constant\n    pointer.* = 6;\n```\n\nIf I change the `number` object to be a variable object, by introducing the `var` keyword,\nthen, I can successfully change the value of this object through a pointer, as demonstrated below:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n6\n```\n\n\n:::\n:::\n\n\n\nYou can see this relationship between \"constant versus variable\" on the data type of\nyour pointer object. In other words, the data type of a pointer object already gives you\nsome clues about whether the value that it points to is constant or not.\n\nWhen a pointer object points to a constant value, then, this pointer have a data type `*const T`,\nwhich means \"a pointer to a constant value of type `T`\".\nIn contrast, if the pointer points to a variable value, then, the type of the pointer is usually `*T`, which is\nsimply \"a pointer to a value of type `T`\".\nHence, whenever you see a pointer object whose data type is in the format `*const T`, then,\nyou know that you cannot use this pointer to change the value that it points to.\nBecause this pointer points to a constant value of type `T`.\n\n\nWe have talked about the value pointed by the pointer being constant or not,\nand the consequences that arises from it. But, what about the pointer object itself? I mean, what happens\nif the pointer object itself is constant or not? Think about it.\nWe can have a constant pointer that points to a constant value.\nBut we can also have a variable pointer that points to a constant value. And vice-versa.\n\nUntil this point, the `pointer` object was always constant,\nbut what does this mean for us? What is the consequence of the\n`pointer` object being constant? The consequence is that\nwe cannot change the pointer object, because it is constant. We can use the\npointer object in multiple ways, but we cannot change the\nmemory address that is inside this pointer object.\n\nHowever, if we mark the `pointer` object as a variable object,\nthen, we can change the memory address pointed by this `pointer` object.\nThe example below demonstrates that. Notice that the object pointed\nby the `pointer` object changes from `c1` to `c2`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c1: u8 = 5;\nconst c2: u8 = 6;\nvar pointer = &c1;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\npointer = &c2;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\n```\n:::\n\n\n\n```\n5\n6\n```\n\nThus, by setting the `pointer` object to a `var` or `const` object,\nyou specify if the memory address contained in this pointer object can change or not\nin your program. On the other side, you can change the value pointed by the pointer,\nif, and only if this value is stored in a variable object. If this value\nis in a constant object, then, you cannot change this value through a pointer.\n\n\n## Types of pointer\n\nIn Zig, there are two types of pointers [@zigdocs], which are:\n\n- single-item pointer (`*`);\n- many-item pointer (`[*]`);\n\n\nSingle-item pointer objects are objects whose data types are in the format `*T`.\nSo, for example, if an object have a data type `*u32`, it means that, this\nobject contains a single-item pointer that points to an unsigned 32-bit integer value.\nAs another example, if an object have type `*User`, then, it contains\na single-item pointer to an `User` value.\n\nIn contrast, many-item pointers are objects whose data types are in the format `[*]T`.\nNotice that the star symbol (`*`) is now inside a pair of brackets (`[]`). If the star\nsymbol is inside a pair of brackets, you know that this object is a many-item pointer.\n\nWhen you apply the `&` operator over an object, you will always get a single-item pointer.\nMany-item pointers are more of a \"internal type\" of the language, more closely\nrelated to slices. So, when you deliberately create a pointer with the `&` operator,\nyou always get a single-item pointer as result.\n\n\n\n## Pointer arithmetic\n\nPointer arithmetic is available in Zig, and they work the same way they work in C.\nWhen you have a pointer that points to an array, the pointer usually points to\nthe first element in the array, and you can use pointer arithmetic to\nadvance this pointer and access the other elements in the array.\n\n\nNotice in the example below, that initially, the `ptr` object was pointing\nto the first element in the array `ar`. But then, I started to walk through the array, by advancing\nthe pointer with simple pointer arithmetic.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [_]i32{ 1, 2, 3, 4 };\nvar ptr: [*]const i32 = &ar;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\n```\n:::\n\n\n\n```\n1\n2\n3\n```\n\nAlthough you can create a pointer to an array like that, and\nstart to walk through this array by using pointer arithmetic,\nin Zig, we prefer to use slices, which were presented in @sec-arrays.\n\nBehind the hood, slices already are pointers,\nand they also come with the `len` property, which indicates\nhow many elements are in the slice. This is good because the `zig` compiler\ncan use it to check for potential buffer overflows, and other problems like that.\n\nAlso, you don't need to use pointer arithmetic to walk through the elements\nof a slice. You can simply use the `slice[index]` syntax to directly access\nany element you want in the slice.\nAs I mentioned in @sec-arrays, you can get a slice from an array by using\na range selector inside brackets. In the example below, I'm creating\na slice (`sl`) that covers the entire `ar` array. I can access any\nelement of `ar` from this slice, and, the slice itself already is a pointer\nbehind the hood.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [_]i32{1,2,3,4};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\n## Optionals and Optional Pointers\n\nLet's talk about optionals and how they relate to pointers in Zig.\nBy default, objects in Zig are **non-nullable**. This means that, in Zig,\nyou can safely assume that any object in your source code is not null.\n\nThis is a powerful feature of Zig when you compare it to the developer experience in C.\nBecause in C, any object can be null at any point, and, as consequence, a pointer in C\nmight point to a null value. This is a common source of undefined behaviour in C.\nWhen programmers work with pointers in C, they have to constantly check if\ntheir pointers are pointing to null values or not.\n\nIf for some reason, your Zig code produces a null value somewhere, and, this null\nvalue ends up in an object that is non-nullable, a runtime error is always\nraised by your Zig program. Take the program below as an example.\nThe `zig` compiler can see the `null` value at compile time, and, as result,\nit raises a compile time error. But, if a `null` value is raised during\nruntime, a runtime error is also raised by the Zig program, with a\n\"attempt to use null value\" message.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nnumber = null;\n```\n:::\n\n\n```\np5.zig:5:14: error: expected type 'u8',\n        found '@TypeOf(null)'\n    number = null;\n             ^~~~\n```\n\n\nYou don't get this type of safety in C.\nIn C, you don't get warnings or errors about null values being produced in your program.\nIf for some reason, your code produces a null value in C, most of the times, you end up getting a segmentation fault error\nas result, which can mean many things.\nThat is why programmers have to constantly check for null values in C.\n\nPointers in Zig are also, by default, **non-nullable**. This is another amazing\nfeature in Zig. So, you can safely assume that any pointer that you create in\nyour Zig code is pointing to a non-null value.\nTherefore, you don't have this heavy work of checking if the pointers you create\nin Zig are pointing to a null value.\n\n\n### What are optionals?\n\nOk, we know now that all objects are non-nullable by default in Zig.\nBut what if we actually need to use an object that might receive a null value?\nHere is where optionals come in.\n\nAn optional object in Zig is an object that can be null.\nTo mark an object as optional, we use the `?` operator. When you put\nthis `?` operator right before the data type of an object, you transform\nthis data type into an optional data type, and the object becomes an optional object.\n\nTake the snippet below as an example. We are creating a new variable object\ncalled `num`. This object have the data type `?i32`, which means that,\nthis object contains either a signed 32-bit integer (`i32`), or, a null value.\nBoth alternatives are valid values to the `num` object.\nThat is why, I can actually change the value of this object to null, and,\nno errors are raised by the `zig` compiler, as demonstrated below:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: ?i32 = 5;\nnum = null;\n```\n:::\n\n\n\n### Optional pointers\n\nYou can also mark a pointer object as an optional pointer, meaning that,\nthis object contains either a null value, or, a pointer that points to a value.\nWhen you mark a pointer as optional, the data type of this pointer object\nbecomes `?*const T` or `?*T`, depending if the value pointed by the pointer\nis a constant value or not. The `?` identifies the object as optional, while\nthe `*` identifies it as a pointer object.\n\nIn the example below, we are creating a variable object named `num`, and an\noptional pointer object named `ptr`. Notice that the data type of the object\n`ptr` indicates that it's either a null value, or a pointer to an `i32` value.\nAlso, notice that the pointer object (`ptr`) can be marked as optional, even if\nthe object `num` is not optional.\n\nWhat this code tells us is that, the `num` variable will never contain a null value.\nThis variable will always contain a valid `i32` value. But in contrast, the `ptr` object might contain either a null\nvalue, or, a pointer to an `i32` value.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: i32 = 5;\nvar ptr: ?*i32 = &num;\nptr = null;\nnum = 6;\n```\n:::\n\n\n\nBut what happens if we turn the table, and mark the `num` object as optional,\ninstead of the pointer object. If we do that, then, the pointer object is\nnot optional anymore. It would be a similar (although different) result. Because then, we would have\na pointer to an optional value. In other words, a pointer to a value that is either a\nnull value, or, a not-null value.\n\nIn the example below, we are recreating this idea. Now, the `ptr` object\nhave a data type of `*?i32`, instead of `?*i32`. Notice that the `*` symbol comes before of `?`\nthis time. So now, we have a pointer that points to a value that is either null\n, or, a signed 32-bit integer.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: ?i32 = 5;\n// ptr have type `*?i32`, instead of `?*i32`.\nconst ptr = &num;\n_ = ptr;\n```\n:::\n\n\n\n\n### Null handling in optionals {#sec-null-handling}\n\nWhen you have an optional object in your Zig code, you have to explicitly handle\nthe possibility of this object being null. It's like error-handling with `try` and `catch`.\nIn Zig you also have to handle null values like if they were a type of error.\n\nWe can do that, by using either:\n\n- an if statement, like you would do in C.\n- the `orelse` keyword.\n- unwrap the optional value with the `?` method.\n\nWhen you use an if statement, you use a pair of pipes\nto unwrap the optional value, and use this \"unwrapped object\"\ninside the if block.\nUsing the example below as a reference, if the object `num` is null,\nthen, the code inside the if statement is not executed. Otherwise,\nthe if statement will unwrap the object `num` into the `not_null_num`\nobject. This `not_null_num` object is guaranteed to be not null inside\nthe scope of the if statement.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst num: ?i32 = 5;\nif (num) |not_null_num| {\n    try stdout.print(\"{d}\\n\", .{not_null_num});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n5\n```\n\n\n:::\n:::\n\n\n\nNow, the `orelse` keyword behaves like a binary operator. You connect two expressions with this keyword.\nOn the left side of `orelse`, you provide the expression that might result\nin a null value, and on the right side of `orelse`, you provide another expression\nthat will not result in a null value.\n\nThe idea behind the `orelse` keyword is: if the expression on the left side\nresult in a not-null value, then, this not-null value is used. However,\nif this expression on the left side result in a null value, then, the value\nof the expression on the right side is used instead.\n\nLooking at the example below, since the `x` object is currently null, the\n`orelse` decided to use the alternative value, which is the number 15.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x: ?i32 = null;\nconst dbl = (x orelse 15) * 2;\ntry stdout.print(\"{d}\\n\", .{dbl});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n30\n```\n\n\n:::\n:::\n\n\n\nYou can use the if statement or the `orelse` keyword, when you want to\nsolve (or deal with) this null value. However, if there is no clear solution\nto this null value, and the most logic and sane path is to simply panic\nand raise a loud error in your program when this null value is encountered,\nyou can use the `?` method of your optional object.\n\nIn essence, when you use this `?` method, the optional object is unwrapped.\nIf a not-null value is found in the optional object, then, this not-null value is used.\nOtherwise, the `unreachable` keyword is used. You can read more about this\n[`unreacheable` keyword at the official documentation](https://ziglang.org/documentation/master/#unreachable)[^un-docs].\nBut in essence, when you build your Zig source code using the build modes `ReleaseSafe` or `Debug`, this\n`unreacheable` keyword causes the program to panic and raise an error during runtime,\nlike in the example below:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn return_null(n: i32) ?i32 {\n    if (n == 5) return null;\n    return n;\n}\n\npub fn main() !void {\n    const x: i32 = 5;\n    const y: ?i32 = return_null(x);\n    try stdout.print(\"{d}\\n\", .{y.?});\n}\n```\n:::\n\n\n\n```\nthread 12767 panic: attempt to use null value\np7.zig:12:34: 0x103419d in main (p7):\n    try stdout.print(\"{d}\\n\", .{y.?});\n                                 ^\n```\n\n\n[^un-docs]: <https://ziglang.org/documentation/master/#unreachable>.\n",
+    "supporting": [
+      "05-pointers_files"
+    ],
+    "filters": [
+      "rmarkdown/pagebreak.lua"
+    ],
+    "includes": {},
+    "engineDependencies": {
+      "knitr": [
+        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
+      ]
+    },
+    "preserve": null,
+    "postProcess": false
+  }
+}
\ No newline at end of file
diff --git a/_freeze/Chapters/07-build-system/execute-results/epub.json b/_freeze/Chapters/07-build-system/execute-results/epub.json
new file mode 100644
index 00000000..57752a70
--- /dev/null
+++ b/_freeze/Chapters/07-build-system/execute-results/epub.json
@@ -0,0 +1,21 @@
+{
+  "hash": "0286d5b6db10173d3df147400fd019aa",
+  "result": {
+    "engine": "knitr",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Build System {#sec-build-system}\n\n\nIn this chapter, we are going to talk about the build system, and how an entire project\nis built in Zig.\nOne key advantage of Zig is that it includes a build system embedded in the language itself.\nThis is great, because then you do not have to depend on an external system, separated\nfrom the compiler, to build your code.\n\n\nYou can find a good description of Zig's build system\nin the [article entitled \"Build System\"](https://ziglang.org/learn/build-system/#user-provided-options)[^zig-art1]\nfrom the official Zig's website.\nWe also have the excellent [series of posts written by Felix](https://zig.news/xq/zig-build-explained-part-1-59lf)[^felix].\nHence, this chapter represents an extra resource for you to consult and rely on.\n\n[^felix]: <https://zig.news/xq/zig-build-explained-part-1-59lf>\n[^zig-art1]: <https://ziglang.org/learn/build-system/#user-provided-options>\n\nBuilding code is one of the things that Zig is best at. One thing that is particularly\ndifficult in C/C++ and even in Rust, is to cross-compile source code to multiple targets\n(e.g. multiple computer architectures and operating systems),\nand the `zig` compiler is known for being one of the best existing pieces of software\nfor this particular task.\n\n\n\n\n## How source code is built?\n\nWe already have talked about the challenges of building source code in low-level languages\nin @sec-project-files. As we described at that section, programmers invented Build Systems\nto surpass these challenges on the process of building source code in low-level languages.\n\nLow-level languages uses a compiler to compile (or to build) your source code into binary instructions.\nIn C and C++, we normally use compilers like `gcc`, `g++` or `clang` to compile\nour C and C++ source code into these instructions.\nEvery language have its own compiler, and this is no different in Zig.\n\nIn Zig, we have the `zig` compiler to compile our Zig source code into\nbinary instructions that can be executed by our computer.\nIn Zig, the compilation (or the build) process involves\nthe following components:\n\n- The Zig modules that contains your source code;\n- Library files (either a dynamic library or a static library);\n- Compiler flags that tailors the build process to your needs.\n\nThese are the things that you need to connect together in order to build your\nsource code in Zig. In C and C++, you would have an extra component, which are the header files of\nthe libraries that you are using. But header files do not exist in Zig, so, you only need\nto care about them if you are linking your Zig source code with a C library.\nIf that is not your case, you can forget about it.\n\nYour build process is usually organized in a build script. In Zig, we normally\nwrite this build script into a Zig module in the root directory of our project,\nnamed as `build.zig`. You write this build script, then, when you run it, your project\ngets built into binary files that you can use and distribute to your users.\n\nThis build script is normally organized around *target objects*. A target is simply\nsomething to be built, or, in other words, it's something that you want the `zig` compiler\nto build for you. This concept of \"targets\" is present in most Build Systems,\nespecially in CMake[^cmake].\n\n[^cmake]: <https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html>\n\nThere are four types of target objects that you can build in Zig, which are:\n\n- An executable (e.g. a `.exe` file on Windows).\n- A shared library (e.g. a `.so` file in Linux or a `.dll` file on Windows).\n- A static library (e.g. a `.a` file in Linux or a `.lib` file on Windows).\n- An executable file that executes only unit tests (or, a \"unit tests executable\").\n\nWe are going to talk more about these target objects in @sec-targets.\n\n\n\n## The `build()` function {#sec-build-fun}\n\nA build script in Zig always contains a public (and top-level) `build()` function declared.\nIt's like the `main()` function in the main Zig module of your project, that we discussed in @sec-main-file.\nBut instead of creating the entrypoint to your code, this `build()` function is the entrypoint to the build process.\n\nThis `build()` function should accept a pointer to a `Build` object as input, and it should use this \"build object\" to perform\nthe necessary steps to build your project. The return type of this function is always `void`,\nand this `Build` struct comes directly from the Zig Standard Library (`std.Build`). So, you can\naccess this struct by just importing the Zig Standard Library into your `build.zig` module.\n\nJust as a very simple example, here you can see the source code necessary to build\nan executable file from the `hello.zig` Zig module.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"hello.zig\"),\n        .target = b.host,\n    });\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\nYou can define and use other functions and objects in this build script. You can also import\nother Zig modules as you would normally do in any other module of your project.\nThe only real requirement for this build script, is to have a public and top-level\n`build()` function defined, that accepts a pointer to a `Build` struct as input.\n\n\n## Target objects {#sec-targets}\n\nAs we described over the previous sections, a build script is composed around target objects.\nEach target object is normally a binary file (or an output) that you want to get from the build process. You can list\nmultiple target objects in your build script, so that the build process generates multiple\nbinary files for you at once.\n\nFor example, maybe you are a developer working in a cross-platform application,\nand, because this application is cross-platform, you probably need to release\nbinary files of your software for each OS supported by your application to your end users.\nThus, you can define a different target object in your build script\nfor each OS (Windows, Linux, etc.) where you want to publish your software.\nThis will make the `zig` compiler to build your project to multiple target OS's at once.\nThe Zig Build System official documentation have a [great code example that demonstrates this strategy](https://ziglang.org/learn/build-system/#handy-examples)[^zig-ex].\n\n[^zig-ex]: <https://ziglang.org/learn/build-system/#handy-examples>\n\n\nA target object is created by the following methods of the `Build` struct that we introduced\nin @sec-build-fun:\n\n- `addExecutable()` creates an executable file;\n- `addSharedLibrary()` creates a shared library file;\n- `addStaticLibrary()` creates a static library file;\n- `addTest()` creates an executable file that executes unit tests.\n\n\nThese functions are methods from the `Build` struct that you receive\nas input of the `build()` function. All of them, create as output\na `Compile` object, which represents a target object to be compiled\nby the `zig` compiler. All of these functions accept a similar struct literal as input.\nThis struct literal defines three essential specs about this target object that you are building:\n`name`, `target` and `root_source_file`.\n\nWe have already seen these three options being used on the previous example,\nwhere we used the `addExecutable()` method to create an executable target object.\nThis example is reproduced below. Notice the use of the `path()` method\nfrom the `Build` struct, to define a path in the `root_source_file` option.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n```\n:::\n\n\n\nThe `name` option specify the name that you want to give to the binary file defined\nby this target object. So, in this example, we are building an executable file named `hello`.\nIt's common to set this `name` option to the name of your project.\n\n\nFurthermore, the `target` option specify the target computer architecture (or the target operating system) of this\nbinary file. For example, if you want this target object to run on a Windows machine\nthat uses a `x86_64` architecture, you can set this `target` option to `x86_64-windows-gnu` for example.\nThis will make the `zig` compiler to compile the project to run on a `x86_64` Windows machine.\nYou can see the full list of architectures and OS's that the `zig` compiler supports by running\nthe `zig targets` command in the terminal.\n\nNow, if you are building the project to run on the current machine\nthat you are using to run this build script, you can set this `target`\noption to the `host` method of the `Build` object, like we did in the example above.\nThis `host` method identifies the current machine where you are\ncurrently running the `zig` compiler.\n\n\nAt last, the `root_source_file` option specifies the root Zig module of your project.\nThat is the Zig module that contains the entrypoint to your application (i.e., the `main()` function), or, the main API of your library.\nThis also means that, all the Zig modules that compose your project are automatically discovered\nfrom the import statements you have inside this \"root source file\".\nThe `zig` compiler can detect when a Zig module depends on the other through the import statements,\nand, as a result, it can discover the entire map of Zig modules used in your project.\n\nThis is handy, and it's different from what happens in other build systems.\nIn CMake for example, you have to explicitly list the paths to all source files that you want to\ninclude in your build process. This is probably a symptom of the \"lack of conditional\ncompilation\" in the C and C++ compilers. Since they lack this feature, you have\nto explicitly choose which source files should be sent to the C/C++ compiler, because not\nevery C/C++ code is portable or supported in every operating system, and, therefore,\nwould cause a compilation error in the C/C++ compiler.\n\n\nNow, one important detail about the build process is that, you have to **explicitly\ninstall the target objects that you create in your build script**, by using the\n`installArtifact()` method of the `Build` struct.\n\nEverytime you invoke the build process of your project, by calling the `build` command\nof the `zig` compiler, a new directory named `zig-out` is created in the root\ndirectory of your project. This new directory contains the outputs of the build process,\nthat is, the binary files built from your source code.\n\nWhat the `installArtifact()` method do is to install (or copy) the built target objects\nthat you defined to this `zig-out` directory.\nThis means that, if you do not\ninstall the target objects you define in your build script, these target objects are\nessentially discarded at the end of the build process.\n\nFor example, you might be building a project that uses a third party library that is built\ntogether with the project. So, when you build your project, you would need first, to\nbuild the third party library, and then, you link it with the source code of your project.\nSo, in this case, we have two binary files that are generated in the build process (the executable file of your project, and the third party library).\nBut only one is of interest, which is the executable file of our project.\nWe can discard the binary file of the third party library, by simply not installing it\ninto this `zig-out` directory.\n\nThis `installArtifact()` method is pretty straightforward. Just remember to apply it to every\ntarget object that you want to save into the `zig-out` directory, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n## Setting the build mode\n\nWe have talked about the three essential options that are set when you create a new target object.\nBut there is also a fourth option that you can use to set the build mode of this target object,\nwhich is the `optimize` option.\nThis option is called this way, because the build modes in Zig are treated more of\nan \"optimization vs safety\" problem. So optimization plays an important role here.\nDon't worry, I'm going back to this question very soon.\n\nIn Zig, we have four build modes (which are listed below). Each one of these build modes offer\ndifferent advantages and characteristics. As we described in @sec-compile-debug-mode, the `zig` compiler\nuses the `Debug` build mode by default, when you don't explicitly choose a build mode.\n\n- `Debug`, mode that produces and includes debugging information in the output of the build process (i.e., the binary file defined by the target object);\n- `ReleaseSmall`, mode that tries to produce a binary file that is small in size;\n- `ReleaseFast`, mode that tries to optimize your code, in order to produce a binary file that is as fast as possible;\n- `ReleaseSafe`, mode that tries to make your code as safe as possible, by including safeguards when possible.\n\nSo, when you build your project, you can set the build mode of your target object to `ReleaseFast` for example, which will tell\nthe `zig` compiler to apply important optimizations in your code. This creates a binary file\nthat simply runs faster on most contexts, because it contains a more optimized version of your code.\nHowever, as a result, we often lose some safety features in our code.\nBecause some safety checks are removed from the final binary file,\nwhich makes your code run faster, but in a less safe manner.\n\nThis choice depends on your current priorities. If you are building a cryptography or banking system, you might\nprefer to prioritize safety in your code, so, you would choose the `ReleaseSafe` build mode, which is a little\nslower to run, but much more secure, because it includes all possible runtime safety checks in the binary file\nbuilt in the build process. In the other hand, if you are writing a game for example, you might prefer to prioritize performance\nover safety, by using the `ReleaseFast` build mode, so that your users can experience faster frame rates in your game.\n\nIn the example below, we are creating the same target object that we have used on previous examples.\nBut this time, we are specifying the build mode of this target object to the `ReleaseSafe` mode.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .optimize = .ReleaseSafe\n});\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n## Setting the version of your build\n\nEverytime you build a target object in your build script, you can assign a version\nnumber to this specific build, following a semantic versioning framework.\nYou can find more about semantic versioning by visiting the [Semantic Versioning website](https://semver.org/)[^semver].\nAnyway, in Zig, you can specify the version of your build, by providing a `SemanticVersion` struct to\nthe `version` option, like in the example below:\n\n\n[^semver]: <https://semver.org/>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .version = .{\n        .major = 2, .minor = 9, .patch = 7\n    }\n});\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n## Detecting the OS in your build script {#sec-detect-os}\n\nIt's very common in Build Systems to use different options, or, to include different modules, or,\nto link against different libraries depending on the Operational System (OS)\nthat you are targeting in the build process.\n\nIn Zig, you can detect the target OS of the build process, by looking\nat the `os.tag` inside the `builtin` module from the Zig library.\nIn the example below, we are using an if statement to run some\narbitrary code when the target of the build process is a\nWindows system.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nif (builtin.target.os.tag == .windows) {\n    // Code that runs only when the target of\n    // the compilation process is Windows.\n}\n```\n:::\n\n\n\n\n## Adding a run step to your build process\n\nOne thing that is neat in Rust is that you can compile and run your\nsource code with one single command (`cargo run`) from the Rust compiler.\nWe saw in @sec-compile-run-code how can we perform a similar job in Zig, by\nbuilding and running our Zig source code through the `run` command from the `zig` compiler.\n\nBut how can we, at the same time, build and run the binary file specified by a target object in our\nbuild script?\nThe answer is by including a \"run artifact\" in our build script.\nA run artifact is created through the `addRunArtifact()` method from the `Build` struct.\nWe simply provide as input to this function the target object that describes the binary file that we\nwant to execute. As a result, this function creates a run artifact that is capable of executing\nthis binary file.\n\nIn the example below, we are defining an executable binary file named `hello`,\nand we use this `addRunArtifact()` method to create a run artifact that will execute\nthis `hello` executable file.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"src/hello.zig\"),\n    .target = b.host\n});\nb.installArtifact(exe);\nconst run_arti = b.addRunArtifact(exe);\n```\n:::\n\n\n\nNow that we have created this run artifact, we need to include it in\nthe build process. We do that by declaring a new step in our build\nscript to call this artifact, through the `step()` method of the `Build`\nstruct.\n\nWe can give any name we want to this step, but, for our\ncontext here, I'm going to name this step as \"run\".\nAlso, I give it a brief description to this step (\"Run the project\").\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst run_step = b.step(\n    \"run\", \"Run the project\"\n);\n```\n:::\n\n\n\n\nNow that we have declared this \"run step\" we need to tell Zig that\nthis \"run step\" depends on the run artifact.\nIn other words, a run artifact always depends on a \"step\" to effectively be executed.\nBy creating this dependency\nwe finally stablish the necessary commands to build and run the executable file\nfrom the build script.\n\nWe can establish a dependency between the run step and the run artifact\nby using the `dependsOn()` method from the run step. So, we first\ncreate the run step, and then, we link it with the run artifact, by\nusing this `dependsOn()` method from the run step.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nrun_step.dependOn(&run_arti.step);\n```\n:::\n\n\n\nThe entire source code of this specific build script that\nwe wrote, piece by piece, in this section, is\navailable in the `build_and_run.zig` module. You can\nsee this module by\n[visiting the official repository of this book](https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig)\n[^module-src].\n\n\n[^module-src]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig>\n\nWhen you declare a new step in your build script, this step\nbecomes available through the `build` command in the `zig` compiler.\nYou can actually see this step by running `zig build --help` in the terminal, like\nin the example below, where we can see that this new \"run\"\nstep that we declared in the build script appeared in the output.\n\n```bash\nzig build --help\n```\n\n```\nSteps:\n  ...\n  run   Run the project\n  ...\n```\n\nNow, everything that we need to is to\ncall this \"run\" step that we created in our build script. We\ncall it by using the name that we gave to this step\nafter the `build` command from the `zig` compiler.\nThis will cause the compiler to build our executable file\nand execute it at the same time.\n\n```bash\nzig build run\n```\n\n## Build unit tests in your project\n\nWe have talked at length about writing unit tests in Zig in @sec-unittests,\nand we also have talked about how to execute these unit tests through\nthe `test` command of the `zig` compiler. However,\nas we did with the `run` command on the previous section, we also might want to\ninclude some commands in our build script to also build and execute the unit tests in our project.\n\nSo, once again, we are going to discuss how a specific built-in command from the `zig` compiler,\n(in this case, the `test` command) can be used in a build script in Zig.\nHere is where a \"test target object\" comes into play.\nAs was described in @sec-targets, we can create a test target object by using the `addTest()` method of\nthe `Build` struct. The first thing that we need to do is to\ndeclare a test target object in our build script.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst test_exe = b.addTest(.{\n    .name = \"unit_tests\",\n    .root_source_file = b.path(\"src/main.zig\"),\n    .target = b.host,\n});\nb.installArtifact(test_exe);\n```\n:::\n\n\n\n\nA test target object essentially selects all `test` blocks in all Zig modules\nacross your project, and builds only the source code present inside\nthese `test` blocks in your project. As a result, this target object\ncreates an executable file that contains only the source code present\nin all of these `test` blocks (i.e., the unit tests) in your project.\n\nPerfect! Now that we have declared this test target object, an executable file\nnamed `unit_tests` is built by the `zig` compiler when we trigger the build\nscript with the `build` command. After the build\nprocess is finished, we can simply execute this `unit_tests` executable\nin the terminal.\n\nHowever, if you remember the previous section, we already learned\nhow can we create a run step in our build script, to execute an executable file\nbuilt by the build script.\n\nSo, we could simply add a run step in our build script to run these unit tests\nfrom a single command in the `zig` compiler, to make our lifes easier.\nIn the example below, we demonstrate the commands to\nregister a new build step called \"tests\" in our build script\nto run these unit tests.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst run_arti = b.addRunArtifact(test_exe);\nconst run_step = b.step(\"tests\", \"Run unit tests\");\nrun_step.dependOn(&run_arti.step);\n```\n:::\n\n\n\nNow that we registered this new build step, we can trigger it by calling the command below\nin the terminal. You can also checkout the complete source\ncode for this specific build script at the `build_tests.zig` module at the\n[official repository of this book](https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig)\n[^module-src2].\n\n\n[^module-src2]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig>\n\n\n```bash\nzig build tests\n```\n\n\n## Tailoring your build process with user-provided options\n\nSometimes, you want to make a build script that is customizable by the user\nof your project. You can do that by creating user-provided options in\nyour build script. We create an user-provided option by using the\n`option()` method from the `Build` struct.\n\nWith this method, we create a \"build option\" which can be passed\nto the `build.zig` script at the command line. The user have the power of setting\nthis option at the `build` command from the\n`zig` compiler. In other words, each build option that we create\nbecomes a new command line argument that is accessible through the `build` command\nof the compiler.\n\nThese \"user-provided options\" are set by using the prefix `-D` in the command line.\nFor example, if we declare an option named `use_zlib`, that receives a boolean value which\nindicates if we should link our source code to `zlib` or not, we can set the value\nof this option in the command line with `-Duse_zlib`. The code example below\ndemonstrates this idea:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const use_zlib = b.option(\n        bool,\n        \"use_zlib\",\n        \"Should link to zlib?\"\n    ) orelse false;\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"example.zig\"),\n        .target = b.host,\n    });\n    if (use_zlib) {\n        exe.linkSystemLibrary(\"zlib\");\n    }\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n```bash\nzig build -Duse_zlib=false\n```\n\n\n## Linking to external libraries\n\n\nOne essential part of every build process is the linking stage.\nThis stage is responsible for combining the multiple object files\nthat represent your code, into a single executable file. It also links\nthis executable file to external libraries, if you use any in your code.\n\nIn Zig, we have two notions of a \"library\", which are: 1) a system's library;\n2) a local library. A system's library is just a library that is already installed\nin your system. While a local library is a library that belongs to the current\nproject; a library that is present in your project directory, and\nthat you are building together with your project source code.\n\nThe basic difference between the two, is that a system's library is already\nbuilt and installed in your system, supposedly, and all you need to do\nis to link your source code to this library to start using it.\nWe do that by using the `linkSystemLibrary()` method from a\n`Compile` object. This method accepts the name of the library\nin a string as input. Remember from @sec-targets that a `Compile` object\nis a target object that you declare in your build script.\n\nWhen you link a particular target object with a system's library,\nthe `zig` compiler will use `pkg-config` to find where\nare the binary files and also the header files of this library\nin your system.\nWhen it finds these files, the linker present in the `zig` compiler\nwill link your object files with the files of this library to\nproduce a single binary file for you.\n\nIn the example below, we are creating an executable file named `image_filter`,\nand, we are linking this executable file to the C Standard Library with the\nmethod `linkLibC()`, but we also are linking this executable file to the\nC library `libpng` that is currently installed in my system.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"image_filter\",\n        .root_source_file = b.path(\"src/main.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n    exe.linkLibC();\n    exe.linkSystemLibrary(\"png\");\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\nIf you are linking with a C library in your project, is generally a good idea\nto also link your code with the C Standard Library. Because is very likely\nthat this C library uses some functionality of the C Standard Library at some point.\nThe same goes to C++ libraries. So, if you are linking with\nC++ libraries, is a good idea to link your project with the C++\nStandard Library by using the `linkLibCpp()` method.\n\nOn the order side, when you want to link with a local library,\nyou should use the `linkLibrary()` method of a `Compile` object.\nThis method expects to receive another `Compile` object as input.\nThat is, another target object defined in your build script,\nusing either the `addStaticLibrary()` or `addSharedLibrary()` methods\nwhich defines a library to be built.\n\nAs we discussed earlier, a local library is a library\nthat is local to your project, and that is being built together\nwith your project. So, you need to create a target object in your build script\nto build this local library. Then, you link the target objects of interest in your project,\nwith this target object that identifies this local library.\n\nTake a look at this example extracted from the build script of the [`libxev` library](https://github.com/mitchellh/libxev/tree/main)[^libxev2].\nYou can see in this snippet that\nwe are declaring a shared library file, from the `c_api.zig`\nmodule. Then, later in the build script, we declare an\nexecutable file named `\"dynamic-binding-test\"`, which\nlinks to this shared library that we defined earlier\nin the script.\n\n[^libxev2]: <https://github.com/mitchellh/libxev/tree/main>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst optimize = b.standardOptimizeOption(.{});\nconst target = b.standardTargetOptions(.{});\n\nconst dynamic_lib = b.addSharedLibrary(.{\n    .name = dynamic_lib_name,\n    .root_source_file = b.path(\"src/c_api.zig\"),\n    .target = target,\n    .optimize = optimize,\n});\nb.installArtifact(dynamic_lib);\n// ... more lines in the script\nconst dynamic_binding_test = b.addExecutable(.{\n    .name = \"dynamic-binding-test\",\n    .target = target,\n    .optimize = optimize,\n});\ndynamic_binding_test.linkLibrary(dynamic_lib);\n```\n:::\n\n\n\n\n\n## Building C code {#sec-building-c-code}\n\nThe `zig` compiler comes with a C compiler embedded in it. In other words,\nyou can use the `zig` compiler to build C projects. This C compiler is available\nthrough the `cc` command of the `zig` compiler.\n\nAs an example, let's use the famous [FreeType library](https://freetype.org/)[^freetype].\nFreeType is one of the most widely used pieces of software in the world.\nIt's a C library designed to produce high-quality fonts. But it's also\nheavily used in the industry to natively render text and fonts\nin the screen of your computer.\n\nIn this section, we are going to write a build script, piece by piece, that is capable\nof building the FreeType project from source.\nYou can find the source code of this build script on the\n[`freetype-zig` repository](https://github.com/pedropark99/freetype-zig/tree/main)[^freetype-zig]\navailable at GitHub.\n\n[^freetype]: <https://freetype.org/>\n[^freetype-zig]: <https://github.com/pedropark99/freetype-zig/tree/main>\n\nAfter you download the source code of FreeType from the official website[^freetype],\nyou can start writing the `build.zig` module. We begin by defining the target object\nthat defines the binary file that we want to compile.\n\nAs an example, I will build the project as a static library file using the `addStaticLibrary()` method\nto create the target object.\nAlso, since FreeType is a C library, I will also link the library\nagainst `libc` through the `linkLibC()` method, to guarantee that any use\nof the C Standard Library is covered in the compilation process.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst target = b.standardTargetOptions(.{});\nconst opti = b.standardOptimizeOption(.{});\nconst lib = b.addStaticLibrary(.{\n    .name = \"freetype\",\n    .optimize = opti,\n    .target = target,\n});\nlib.linkLibC();\n```\n:::\n\n\n\n### Creating C compiler flags\n\nCompiler flags are also known as \"compiler options\" by many programmers,\nor also, as \"command options\" in the GCC official documentation.\nIt's fair to also call them as the \"command-line arguments\" of the C compiler.\nIn general, we use compiler flags to turn on (or turn off) some features from the compiler,\nor to tweak the compilation process to fit the needs of our project.\n\nIn build scripts written in Zig, we normally list the C compiler flags to be used in the compilation process\nin a simple array, like in the example below.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c_flags = [_][]const u8{\n    \"-Wall\",\n    \"-Wextra\",\n    \"-Werror\",\n};\n```\n:::\n\n\n\nIn theory, there is nothing stopping you from using this array to add \"include paths\" (with the `-I` flag)\nor \"library paths\" (with the `-L` flag) to the compilation process. But there are formal ways in Zig to\nadd these types of paths in the compilation process. Both are discussed in @sec-include-paths\nand @sec-library-paths.\n\nAnyway, in Zig, we add C flags to the build process together with the C files that we want to compile, by using the\n`addCSourceFile()` and `addCSourceFiles()` methods. In the example above, we have just declared\nthe C flags that we want to use. But we haven't added them to the build process yet.\nTo do that, we also need to list the C files to be compiled.\n\n### Listing your C files\n\nThe C files that contains \"cross-platform\" source code are listed in the `c_source_files`\nobject below. These are the C files that are included by default in every platform\nsupported by the FreeType library. Now, since the amount of C files in the FreeType library is big,\nI have omitted the rest of the files in the code example below, for brevity purposes.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c_source_files = [_][]const u8{\n    \"src/autofit/autofit.c\",\n    \"src/base/ftbase.c\",\n    // ... and many other C files.\n};\n```\n:::\n\n\n\nNow, in addition to \"cross-platform\" source code, we also have some C files in the FreeType project\nthat are platform-specific, meaning that, they contain source code that can only be compiled in specific platforms,\nand, as a result, they are only included in the build process on these specific target platforms.\nThe objects that list these C files are exposed in the code example below.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst windows_c_source_files = [_][]const u8{\n    \"builds/windows/ftdebug.c\",\n    \"builds/windows/ftsystem.c\"\n};\nconst linux_c_source_files = [_][]const u8{\n    \"src/base/ftsystem.c\",\n    \"src/base/ftdebug.c\"\n};\n```\n:::\n\n\n\nNow that we declared both the files that we want to include and the C compiler flags to be used,\nwe can add them to the target object that describes the FreeType library, by using the\n`addCSourceFile()` and `addCSourceFiles()` methods.\n\nBoth of these functions are methods from a `Compile` object (i.e., a target object).\nThe `addCSourceFile()` method is capable of adding a single C file to the target object,\nwhile the `addCSourceFiles()` method is used to add multiple C files in a single command.\nYou might prefer to use `addCSourceFile()` when you need to use different compiler flags\non specific C files in your project. But, if you can use the same compiler flags\nacross all C files, then, you will probably find `addCSourceFiles()` a better choice.\n\nNotice that we are using the `addCSourceFiles()` method in the example below,\nto add both the C files and the C compiler flags. Also notice that we\nare using the `os.tag` that we learned about in @sec-detect-os, to add the platform-specific\nC files.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nlib.addCSourceFiles(\n    &c_source_files, &c_flags\n);\n\nswitch (builtin.target.os.tag) {\n    .windows => {\n        lib.addCSourceFiles(\n            &windows_c_source_files,\n            &c_flags\n        );\n    },\n    .linux => {\n        lib.addCSourceFiles(\n            &linux_c_source_files,\n            &c_flags\n        );\n    },\n    else => {},\n}\n```\n:::\n\n\n\n\n### Defining C Macros\n\nC Macros are an essential part of the C programming language,\nand they are commonly defined through the `-D` flag from a C compiler.\nIn Zig, you can define a C Macro to be used in your build process\nby using the `defineCMacro()` method from the target object that\ndefines the binary file that you are building.\n\nIn the example below, we are using the `lib` object that we have defined\nin the previous sections to define some C Macros used by the FreeType project\nin the compilation process. These C Macros specify if FreeType\nshould (or should not) include functionalities from different\nexternal libraries.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nlib.defineCMacro(\"FT_DISABLE_ZLIB\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_PNG\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_HARFBUZZ\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BZIP2\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BROTLI\", \"TRUE\");\nlib.defineCMacro(\"FT2_BUILD_LIBRARY\", \"TRUE\");\n```\n:::\n\n\n\n\n### Adding library paths {#sec-library-paths}\n\nLibrary paths are paths in your computer where the C compiler will look (or search) for\nlibrary files to link against your source code. In other words, when you use a library in your\nC source code, and you ask the C compiler to link your source code against this library,\nthe C compiler will search for the binary files of this library across the paths listed\nin this \"library paths\" set.\n\nThese paths are platform specific, and, by default, the C compiler starts by looking at a\npre-defined set of places in your computer. But you can add more paths (or more places)\nto this list. For example, you may have a library installed in a non-conventional place of your\ncomputer, and you can make the C compiler \"see\" this \"non-conventional place\" by adding this path\nto this list of pre-defined paths.\n\nIn Zig, you can add more paths to this set by using the `addLibraryPath()` method from your target object.\nFirst, you defined a `LazyPath` object, containing the path you want to add, then,\nyou provide this object as input to the `addLibraryPath()` method, like in the example below:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst lib_path: std.Build.LazyPath = .{\n    .cwd_relative = \"/usr/local/lib/\"\n};\nlib.addLibraryPath(lib_path);\n```\n:::\n\n\n\n\n\n\n### Adding include paths {#sec-include-paths}\n\nThe preprocessor search path is a popular concept from the\nC community, but it's also known by many C programmers as \"include paths\", because\nthe paths in this \"search path\" relate to the `#include` statements found in the C files.\n\nInclude paths are similar to library paths. They are a set of pre-defined places in your computer where\nthe C compiler will look for files during the compilation process. But instead of looking for\nlibrary files, the include paths are places where the compiler looks for header files included\nin your C source code.\nThis is why many C programmers prefer to call these paths as the \"preprocessor search path\".\nBecause header files are processed during the preprocessor stage of the compilation\nprocess.\n\nSo, every header file that you include in your C source code, through a `#include` statements needs to\nbe found somewhere, and the C compiler will search for this header file across the paths listed in this \"include paths\" set.\nInclude paths are added to the compilation process through the `-I` flag.\n\nIn Zig, you can add new paths to this pre-defined set of paths, by using the `addIncludePath()` method\nfrom your target object. This method also accepts a `LazyPath` object as input.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst inc_path: std.Build.LazyPath = .{\n    .path = \"./include\"\n};\nlib.addIncludePath(inc_path);\n```\n:::\n",
+    "supporting": [
+      "07-build-system_files"
+    ],
+    "filters": [
+      "rmarkdown/pagebreak.lua"
+    ],
+    "includes": {},
+    "engineDependencies": {
+      "knitr": [
+        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
+      ]
+    },
+    "preserve": null,
+    "postProcess": false
+  }
+}
\ No newline at end of file
diff --git a/_freeze/Chapters/09-data-structures/execute-results/epub.json b/_freeze/Chapters/09-data-structures/execute-results/epub.json
new file mode 100644
index 00000000..9a281348
--- /dev/null
+++ b/_freeze/Chapters/09-data-structures/execute-results/epub.json
@@ -0,0 +1,21 @@
+{
+  "hash": "0d90c199a3a2c5a7a25c66baac2ca8aa",
+  "result": {
+    "engine": "knitr",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Data Structures\n\nIn this chapter, I want to present the most common Data Structures that are available from\nthe Zig Standard Library, especially `ArrayList` and also `HashMap`. These are generic Data Structures\nthat you can use to store and control any type of data that is produced by your application.\n\n## Dynamic Arrays {#sec-dynamic-array}\n\nIn high level languages, arrays are usually dynamic. They can easily grow\nin size when they have to, and you don't need to worry about it.\nIn contrast, arrays in low level languages are usually static by default.\nThis is the reality of C, C++, Rust and also Zig. Static arrays were presented at\n@sec-arrays, but in this section, we are going to talk about dynamic arrays in Zig.\n\nDynamic arrays are simply arrays that can grow in size during the runtime\nof your program. Most low level languages have some implementation of\na dynamic array in their standard library. C++ have `std::vector`, Rust have `Vec`,\nand Zig have `std.ArrayList`.\n\nThe `std.ArrayList` struct provides a contiguous and growable array for you.\nIt works like any other dynamic array, it allocates a contiguous block of memory, and when this block have no space left,\n`ArrayList` allocates another contiguous and bigger block of memory, copies the\nelements to this new location, and erases (or frees) the previous block of memory.\n\n\n### Capacity vs Length\n\nWhen we talk about dynamic arrays, we usually have two similar concepts that\nare very essential to how a dynamic array works behind the hood.\nThese concepts are *capacity* and *length*. In some contexts, especially\nin C++, *length* is also called of *size*.\n\nAlthough they look similar, these concepts represent different things\nin the context of a dynamic array. *Capacity* is the number of items (or elements)\nthat your dynamic array can currently hold without the need to allocate more memory.\n\nIn contrast, the *length* refers to how many elements in the array\nare currently being used, or, in other words, how many elements in this array\nthat you have assigned a value to. Every dynamic array works around\na block of allocated memory, which represents an array with total capacity for $n$ elements.\nHowever, only a portion of these $n$ elements are being used most of the time. This portion\nof $n$ is the *length* of the array. So every time you append a new value\nto the array, you are incrementing its *length* by one.\n\nThis means that a dynamic array usually works with an extra margin, or an extra space\nthat is currently empty, but waiting and ready to be used. This \"extra space\"\nis essentially the difference between *capacity* and *length*. *Capacity* represents\nthe total number of elements that the array can hold without the need to re-allocate\nor re-expand the array, while the *length* represents how much of this capacity\nis currently being used to hold/store values.\n\n@fig-capacity-length presents this idea visually. Notice that, at first,\nthe capacity of the array is greater than the length of the array.\nSo, the dynamic array have extra space that is currently empty, but it\nis ready to receive a value to be stored.\n\n![Difference between capacity and length in a dynamic array](./../Figures/dynamic-array.png){#fig-capacity-length}\n\nWe can also see in @fig-capacity-length that, when *length* and *capacity* are equal, it means that the array have no space left.\nWe have reached the ceiling of our capacity, and because of that, if we want to store more values\nin this array, we need to expand it. We need to get a bigger space that can hold more values\nthan what we currently have.\n\nA dynamic array works by expanding the underlying array, whenever the *length* becomes equal\nto the *capacity* of the array. It basically allocates a new contiguous block of memory that is bigger\nthan the previous one, then, it copies all values that are currently being stored to this new\nlocation (i.e., this new block of memory), then, it frees the previous block of\nmemory. At the end of this process, the new underlying array have a bigger *capacity*, and, therefore,\nthe *length* becomes, once again, smaller than the *capacity* of the array.\n\nThis is the cycle of a dynamic array. Notice that, throughout this cycle, the *capacity* is always\neither equal to or higher than the *length* of the array. If you have an `ArrayList` object (let's suppose\nyou named it `buffer`), you can check the current capacity of your array by accessing the `capacity`\nattribute of your `ArrayList` object, while the current *length* of it is available at the `items.len`\nattribute.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// Check capacity\nbuffer.capacity;\n// Check length\nbuffer.items.len;\n```\n:::\n\n\n\n\n### Creating an `ArrayList` object\n\nIn order to use `ArrayList`, you must provide an allocator object to it.\nRemember, Zig does not have a default memory allocator. And as I described in @sec-allocators, all memory\nallocations must be done by an allocator object that you define, that\nyou have control over. In our example here, I'm going to use\na general purpose allocator, but you can use any other allocator\nof your preference.\n\nWhen you initialize an `ArrayList` object, you must provide the data type of the elements of\nthe array. In other words, this defines the type of data that this array (or container) will\nstore. Therefore, if I provide the `u8` type to it, then, I will create a dynamic\narray of `u8` values. However, if I provide a struct that I have defined instead, like the struct `User`\nfrom @sec-structs-and-oop, then, a dynamic array of `User` values\nwill be created. In the example below, with the expression `ArrayList(u8)` we\nare creating a dynamic array of `u8` values.\n\nAfter you provide the data type of the elements of the array, you can initialize\nan `ArrayList` object by either using the `init()` or the `initCapacity()` methods.\nThe former method receives only the allocator object\nas input, while the latter method receives both the allocator object and a capacity number as inputs.\nWith the latter method, you not only initialize the struct, but you\nalso set the starting capacity of the allocated array.\n\nUsing the `initCapacity()` method is the preferred way to initialize your dynamic array.\nBecause reallocations, or, in other words, the process of expanding the capacity of the array,\nis always a high cost operation. You should take any possible opportunity to avoid reallocations in\nyour array. If you know how much space your array needs to occupy at the beginning,\nyou should always use `initCapacity()` to create your dynamic array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n```\n:::\n\n\n\n\nIn the example above, the `buffer` object starts as an array of 100 elements. If this\n`buffer` object needs to create more space to accomodate more elements during the runtime of your program, the `ArrayList`\ninternals will perform the necessary actions for you automatically.\nAlso notice the `deinit()` method being used to destroy the `buffer` object at the\nend of the current scope, by freeing all the memory that was allocated for the dynamic\narray stored in this `buffer` object.\n\n\n### Adding new elements to the array\n\nNow that we have created our dynamic array, we can start to use it. You can append (a.k.a \"add\")\nnew values to this array by using the `append()` method. This method works the same way\nas the `append()` method from a Python list, or, the `emplace_back()` method from `std::vector` of C++.\nYou provide a single value to this method, and the method appends this value to the array.\n\nYou can also use the `appendSlice()` method to append multiple values at once. You provide\na slice (slices were described in @sec-arrays) to this method, and the method adds all values present\nin this slice to your dynamic array.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry buffer.append('H');\ntry buffer.append('e');\ntry buffer.append('l');\ntry buffer.append('l');\ntry buffer.append('o');\ntry buffer.appendSlice(\" World!\");\n```\n:::\n\n\n\n### Removing elements from the array {#sec-dynamic-array-remove}\n\nYou can use the `pop()` method to \"pop\" or remove\nthe last element in the array. It's worth noting that this method\ndo not change the capacity of the array. It just deletes or erases\nthe last value stored in the array.\n\nAlso, this method returns as result the value that got deleted. That is, you can\nuse this method to both get the last value in the array, and also, remove\nit from the array. It's a \"get and remove value\" type of method.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exclamation_mark = buffer.pop();\n```\n:::\n\n\n\nNow, if you want to remove specific elements from specific positions\nof your array, you can use the `orderedRemove()` method from your\n`ArrayList` object. With this method, you can provide an index as input,\nthen, the method will delete the value that is at this index in the array.\nYou are effectively reducing the *length* of the array everytime you execute\nan `orderedRemove()` operation.\n\nIn the example below, we first create an `ArrayList` object, and we fill it\nwith numbers. Then, we use `orderedRemove()` to remove the value at\nindex 3 in the array, two consecutive times.\n\nAlso, notice that we are assigning the result of `orderedRemove()` to the\nunderscore character. So we are discarding the result value of this method.\nThe `orderedRemove()` method returns the value that got deleted, in a similar\nstyle to the `pop()` method.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n\nfor (0..10) |i| {\n    const index: u8 = @intCast(i);\n    try buffer.append(index);\n}\n\nstd.debug.print(\n    \"{any}\\n\", .{buffer.items}\n);\n_ = buffer.orderedRemove(3);\n_ = buffer.orderedRemove(3);\n\nstd.debug.print(\"{any}\\n\", .{buffer.items});\nstd.debug.print(\"{any}\\n\", .{buffer.items.len});\n```\n:::\n\n\n\n```\n{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }\n{ 0, 1, 2, 5, 6, 7, 8, 9 }\n8\n```\n\nOne key characteristic about `orderedRemove()` is that it preserves the order\nof the values in the array. So, it deletes the value that you asked it to\nremove, but it also makes sure that the order of the values that remain in the array\nstay the same as before.\n\nNow, if you don't care about the order of the values, for example, maybe you want to treat\nyour dynamic array as a set of values, like the `std::unordered_set`\nstructure from C++, you can use the `swapRemove()` method instead. This method\nworks similarly to the `orderedRemove()` method. You give an index to this\nmethod, then, it deletes the value that is at this index in the array.\nBut this method does not preserve the original order of the values that remain\nin the array. As a result, `swapRemove()` is, in general, faster than `orderedRemove()`.\n\n\n### Inserting elements at specific indexes\n\nWhen you need to insert values in the middle of your array,\ninstead of just appending them to the end of the array, you need to use\nthe `insert()` and `insertSlice()` methods, instead of\nthe `append()` and `appendSlice()` methods.\n\nThese two methods work very similarly to `insert()` and `insert_range()`\nfrom the C++ `std::vector` class. You provide an index to these methods,\nand they insert the values that you provide at that index in the array.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 10);\ndefer buffer.deinit();\n\ntry buffer.appendSlice(\"My Pedro\");\ntry buffer.insert(4, '3');\ntry buffer.insertSlice(2, \" name\");\nfor (buffer.items) |char| {\n    try stdout.print(\"{c}\", .{char});\n}\n```\n:::\n\n\n\n```\nMy name P3edro\n```\n\n\n### Conclusion\n\nIf you feel the lack of some other method, I recommend\nyou to read the [official documentation for the `ArrayListAligned`](https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned)[^zig-array2]\nstruct, which describes most of the methods available\nthrough the `ArrayList` object.\n\nYou will notice that there is a lot of other methods in this page that\nI did not described here, and I recommend you to explore these methods,\nand understand how they work.\n\n[^zig-array2]: <https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned>\n\n\n\n## Maps or HashTables {#sec-maps-hashtables}\n\nSome professionals know this type of data structure by different terms, like \"map\",\n\"hashmap\" or \"associative arrays\". But the most common term used is *hashtable*.\nEvery programming language normally have some implementation of a hashtable in their\nstandard libraries. Python have `dict()`, C++ have `std::map` and `std::unordered_map`, Rust\nhave `HashMap`, Javascript have `Object()` and `Map()`, etc.\n\n\n\n### What is a hashtable?\n\nA hashtable is a data structure based on key-value pairs.\nYou provide a key and a value to this structure, then, the hashtable will store\nthe input value at a location that can be identified by the input\nkey that you provided.\nIt does that by using an underlying array and a hash function.\nThese two components are essential to how a hashtable works.\n\nUnder the hood, the hashtable contains an array. This array is where the values\nare stored, and the elements of this array are usually called of *buckets*.\nSo the values that you provide to the hashtable are stored inside buckets,\nand you access each bucket by using an index.\n\nWhen you provide a key to a hashtable, it passes this key to the\nhash function. This hash function uses some sort of hashing algorithm to transform\nthis key into an index. This index is actually an array index. It's a position\nin the underlying array of the hashtable.\nThis is how a key identifies a specific position (or location) inside the hashtable\nstructure.\n\nTherefore, you provide a key to the hashtable, and this key identifies a specific location\ninside the hashtable, then, the hashtable takes the input value that you provided,\nand stores this value in the location identified by this input key.\nYou could say that the key maps to the value stored in the hashtable. You find\nthe value, by using the key that identifies the location where the value is stored.\nThe @fig-hashtable presents this process visually.\n\n\n![A diagram of a Hashtable. Source: Wikipedia, the free encyclopedia.](./../Figures/hashtable.svg){#fig-hashtable}\n\n\nThe operation described in the previous paragraph is normally called an *insertion* operation.\nBecause you are inserting new values into the hashtable.\nBut there are other types of operations in hashtables such as *delete* and *lookup*.\nDelete is self describing, it's when you delete (or remove) a value from the hashtable.\nWhile lookup corresponds to when you look at a value that is stored in\nthe hashtable, by using the key that identifies the location where this value is stored.\n\nSometimes, instead of storing the values directly, the underlying array of the hashtable might be an array of pointers,\ni.e., the buckets of the array stores pointers that points to the value,\nor also, may be an array of linked lists.\nThese cases are common on hashtables that allows duplicate keys, or, in other words,\non hashtables that effectively handle \"collisions\" that may arise from the hash function.\n\nDuplicate keys, or this \"collision\" thing that I'm talking about, is when you have two different keys\nthat points to the same location (i.e., to the same index)\nin the underlying array of the hashtable. This might happen depending on the characteristics of the hash function\nthat is being used in the hashtable. Some implementations of the hashtable will actively deal with collisions,\nmeaning that, they will handle this case in some way. For example, the hashtable\nmight transform all buckets into linked lists. Because with a linked list you can store\nmultiple values into a single bucket.\n\nThere are different techniques to handle collisions in hashtables, which I will not describe\nin this book, because it's not our main scope here. But you can find a good description of\nsome of the most common techniques at the Wikipedia page of hashtables [@wikipedia_hashtables].\n\n\n### Hashtables in Zig {#sec-hashmap}\n\nThe Zig Standard Library provides different implementations of a hashtable.\nEach implementation have its own cons and pros, which we will\ndiscuss later on, and all of them are available through the `std.hash_map` module.\n\nThe `HashMap` struct is a general-purpose hashtable,\nwhich have very fast operations (lookup, insertion, delete), and also,\nquite high load factors for low memory usage. You can create and provide a context object\nto the `HashMap` constructor. This context object allows you to tailor\nthe behaviour of the hashtable itself, because you can\nprovide a hash function implementation to be used by the hashtable\nthrough this context object.\n\nBut let's not worry about this context object now, because it's meant to be used\nby \"experts in the field of hashtables\". Since we are most likely not\nexperts in this field, we are going to take the easy way to create\na hashtable. Which is by using the `AutoHashMap()` function.\n\n\nThis `AutoHashMap()` function is essentially a \"create a hashtable object that uses the default settings\"\ntype of function. It automatically chooses a context object, and, therefore, a hash function implementation,\nfor you. This function receives two data types as input, the first input is the data type of the keys\nthat will be used in this hashtable, while the second input is the data type of the data that will be\nstored inside the hashtable, that is, the data type of the values to be stored.\n\nIn the example below, we are providing the data type `u32` in the first argument, and `u16` in the second argument of this\nfunction. This means that we are going to use `u32` values as keys in this hashtable, while `u16` values are the actual values\nthat are going to be stored into this hashtable.\nAt the end of this process, the `hash_table` object contains a `HashMap` object\nthat uses the default settings and context.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n    std.debug.print(\n        \"Value at key 50050: {d}\\n\",\n        .{hash_table.get(50050).?}\n    );\n\n    if (hash_table.remove(57709)) {\n        std.debug.print(\n            \"Value at key 57709 successfully removed!\\n\",\n            .{}\n        );\n    }\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n}\n```\n:::\n\n\n\n```\nN of values stored: 3\nValue at key 50050: 55\nValue at key 57709 successfully removed!\nN of values stored: 2\n```\n\nYou can add/put new values into the hashtable by using the `put()` method. The first argument\nis the key to be used, and the second argument is the actual value that you want to store inside\nthe hashtable. In the example below, we first add the value 89 using the key 54321, next, we add\nthe value 55 using the key 50050, etc.\n\nNotice that we have used the method `count()` to see how many values are currently stored in the\nhashtable. After that, we also use the `get()` method to access (or look) at the value stored in\nthe position identified by the key 500050. The output of this `get()` method is an optional value.\nThis is why we use the `?` method at the end to get the actual value.\n\nAlso notice that we can remove (or delete) values from the hashtable by using the `remove()` method.\nYou provide the key that identifies the value that you want to delete, then, the method will\ndelete this value and return a `true` value as output. This `true` value essentially tells us\nthat the method successfully deleted the value.\n\nBut this delete operation might not be always successful. For example, you might provide the wrong\nkey to this method. I mean, maybe you provide\n(either intentionally or unintentionally) a key that points to an empty bucket,\ni.e., a bucket that still doesn't have a value in it.\nIn this case, the `remove()` method would return a `false` value.\n\n\n\n### Iterating through the hashtable\n\nIterating through the keys and values that are currently being stored in\nthe hashtable is a very common necessity.\nYou can do that in Zig by using an iterator object that can iterate\nthrough the elements of your hashtable object.\n\nThis iterator object works like any other iterator object that you would\nfind in languages such as C++ and Rust. It's basically a pointer object\nthat points to some value in the container, and has a `next()` method\nthat you can use to navigate (or iterate) through the values in the\ncontainer.\n\nYou can create such iterator object by using the `iterator()` method of the hashtable object.\nThis method returns an iterator object, from which you can use the `next()` method in conjunction\nwith a while loop to iterate through the elements of your hashtable. The `next()` method returns an optional\n`Entry` value, and therefore, you must unwrap this optional value to get the actual `Entry` value\nfrom which you can access the key and also the value identified by this key.\n\nWith this `Entry` value at hand, you can access the key of this current entry by using the `key_ptr`\nattribute and dereferencing the pointer that lives inside of it, while the value identified by this\nkey is accessed through the `value_ptr` attribute instead, which is also a pointer to be dereferenced.\nThe code example below demonstrates the use of these elements:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n\n    var it = hash_table.iterator();\n    while (it.next()) |kv| {\n        // Access the current key\n        std.debug.print(\"Key: {d} | \", .{kv.key_ptr.*});\n        // Access the current value\n        std.debug.print(\"Value: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n:::\n\n\n\n```\nKey: 54321 | Value: 89\nKey: 50050 | Value: 55\nKey: 57709 | Value: 41\n```\n\n\nIf you want to iterate specifically through the values or the keys of your hashtable,\nyou can create a key iterator or a value iterator object. These are also iterator\nobjects, which have the same `next()` method that you can use to iterate through the\nhashtable.\n\nKey iterators are created from the `keyIterator()` method of your\nhashtable object, while value iterators are created from the `valueIterator()` method.\nAll you have to do is to unwrap the value from the `next()` method and deference it\ndirectly to access the key or the value that you are iterating over.\nThe code example below demonstrates the use of a key iterator,\nbut you can replicate the same logic to a value iterator.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar kit = hash_table.keyIterator();\nwhile (kit.next()) |key| {\n    std.debug.print(\"Key: {d}\\n\", .{key.*});\n}\n```\n:::\n\n\n\n```\nKey: 54321\nKey: 50050\nKey: 57709\n```\n\n\n### The `ArrayHashMap` hashtable {#sec-array-map}\n\nIf you need to iterate through the elements of your hashtable constantly,\nyou might want to use the `ArrayHashMap` struct for your specific case,\ninstead of going with the usual and general-purpose `HashMap` struct.\n\nThe `ArrayHashMap` struct creates a hashtable that is faster to iterate over.\nThat is why this specific type of hashtable might be valuable to you.\nSome other properties of a `ArrayHashMap` hashtable are:\n\n- the order of insertion is preserved, i.e., the order of the values that you find while iterating through this hashtable is actually the order in which these values were inserted in the hashtable.\n- the key-value pairs are stored sequentially, one after another.\n\n\nYou can create an `ArrayHashMap` object by using, once again, a helper function that\nchooses automatically for you a hash function implementation. This is the\n`AutoArrayHashMap()` function, which works very similarly to the `AutoHashMap()`\nfunction that we presented in @sec-hashmap.\n\nYou provide two data types to this function. The data type of the keys that will be\nused in this hashtable, and the data type of the values that will be stored in\nthis hashtable.\n\nAn `ArrayHashMap` object have essentially the exact same methods from the `HashMap` struct.\nSo you can insert new values into the hashtable by using the `put()` method, and you can look (or get)\na value from the hashtable by using the `get()` method. But the `remove()` method is not available\nin this specific type of hashtable.\n\nIn order to delete values from the hashtable, you would use the same methods that you find in\nan `ArrayList` object, i.e., a dynamic array. I presented these methods in @sec-dynamic-array-remove,\nwhich are the `swapRemove()` and `orderedRemove()` methods. These methods have the same meaning here, or,\nthe same effect that they have in an `ArrayList` object.\n\nThis means that, with `swapRemove()` you remove the value from the hashtable, but you do not preserve\nthe order in which the values were inserted into the structure. While `orderedRemove()` is able\nto retain the order in which these values were inserted.\n\nBut instead of providing an index as input to `swapRemove()` or `orderedRemove()`, like I described\nin @sec-dynamic-array-remove, these methods here in an `ArrayHashMap` take a key as input, like\nthe `remove()` method from a `HashMap` object. If you want to provide an index as input, instead\nof a key, you should use the `swapRemoveAt()` and `orderedRemoveAt()` methods.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar hash_table = AutoArrayHashMap(u32, u16)\n    .init(allocator);\ndefer hash_table.deinit();\n```\n:::\n\n\n\n\n\n### The `StringHashMap` hashtable {#sec-string-hash-map}\n\nOne thing that you will notice in the other two types of hashtables that I have\npresented over the last sections, is that neither of them accepts a slice data type\nin their keys.\nWhat this means is that you cannot use a slice value to represent a key in\nthese types of hashtable.\n\nThe most obvious consequence of this, is that you cannot use strings as keys\nin these hashtables. But it's extremely common to use strings as keys\nin hashtables.\n\nTake this very simple Javascript code snippet as an example. We are creating\na simple hashtable object named `people`. Then, we add a new entry to this\nhashtable, which is identified by the string `'Pedro'`. This string is the\nkey in this case, while the object containing different personal information such as\nage, height and city, is the value to be stored in the hashtable.\n\n```js\nvar people = new Object();\npeople['Pedro'] = {\n    'age': 25,\n    'height': 1.67,\n    'city': 'Belo Horizonte'\n};\n```\n\nThis pattern of using strings as keys is very common in\nall sorts of situations. That is why the Zig Standard Library offers a\nspecific type of hashtable for this purpose, which is created through the `StringHashMap()` function.\nThis function creates a hashtable that uses strings as keys. The only input of this\nfunction is the data type of the values that will be stored into this hashtable.\n\nIn the example below, I'm creating a hashtable to store the ages of different people.\nEach key in this hashtable is represented by the name of each person, while the value stored in the\nhashtable is the age of this person identified by the key.\n\nThat is why I provide the `u8` data type (which is the data type used by the age values) as input to this `StringHashMap()` function.\nAs the result, it creates a hashtable that uses string values as keys, and, that stores\n`u8` values in it. Notice that an allocator object is provided at the `init()` method of the\nresulting object from the `StringHashMap()` function.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var ages = std.StringHashMap(u8).init(allocator);\n    defer ages.deinit();\n\n    try ages.put(\"Pedro\", 25);\n    try ages.put(\"Matheus\", 21);\n    try ages.put(\"Abgail\", 42);\n\n    var it = ages.iterator();\n    while (it.next()) |kv| {\n        std.debug.print(\"Key: {s} | \", .{kv.key_ptr.*});\n        std.debug.print(\"Age: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n:::\n\n\n\n```\nKey: Pedro | Age: 25\nKey: Abgail | Age: 42\nKey: Matheus | Age: 21\n```\n\n\n### The `StringArrayHashMap` hashtable\n\nThe Zig Standard Library also provides a type of hashtable that mix the cons and pros of the\n`StringHashMap` and `ArrayHashMap` together. That is, a hashtable\nthat uses strings as keys, but also have the advantages from `ArrayHashMap`.\nIn other words, you can have a hashtable that is fast to iterate over,\nthat preserves insertion order, and also, that uses strings as keys.\n\nYou can create such type of hashtable by using the `StringArrayHashMap()` function.\nThis function accepts a data type as input, which is the data type of the values that are\ngoing to be stored inside this hashtable, in the same style as the function presented\nin @sec-string-hash-map.\n\nYou can insert new values into this hashtable by using the same `put()` method that\nwe have discussed in @sec-string-hash-map. And you can also get values from the hashtable\nby using the same `get()` method.\nLike its `ArrayHashMap` brother, to delete values from this specific type of hashtable,\nwe also use the `orderedRemove()` and `swapRemove()` methods, with the same effects that\nI have described in @sec-array-map.\n\nIf we take the code example that was exposed in @sec-string-hash-map, we can\nachieve the exact same result with `StringArrayHashMap()`:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar ages = std.StringArrayHashMap(u8).init(allocator);\n```\n:::\n\n\n\n\n\n\n## Linked lists\n\nThe Zig Standard Library provides an implementation for both singly and doubly linked lists.\nMore specifically, through the structs `SinglyLinkedList` and `DoublyLinkedList`.\n\nIn case you are not familiar with these data structures, a linked list is a linear data structure that looks\nlike a chain, or, a rope. The main advantage of this data structure is that you normally have very fast\ninsertion and deletion operations. But, as a disadvantage, iterating through\nthis data structure is usually not so fast as iterating through an array.\n\nThe idea behind a linked list is to build a structure that consists of a sequence of nodes\nconnected to each other by pointers. This means that linked lists are usually not contiguous\nin memory, because each node might be anywhere in memory. They do not need to be close to\none another.\n\nIn @fig-linked-list we can see a diagram of a singly linked list. We begin at the first node\n(which is usually called \"the head of the linked list\"). Then, from this\nfirst node we uncover the remaining nodes in the structure, by following the locations pointed\nby the pointers found in each node.\n\nEach node has two things in it. It has the value that is stored in the current node\n, and also, a pointer. This pointer points to the next node in the list. If this pointer\nis null, then, it means that we have reached the end of our linked list.\n\n![A diagram of a singly linked list.](./../Figures/linked-list.png){#fig-linked-list}\n\n\nIn @fig-linked-list2 we can see a diagram of a doubly linked list. The only thing that really\nchanges now is that every node in the linked list has both a pointer to the previous node,\nand, a pointer to the next node. So every node in a doubly linked list has two pointers in it. These are\nusually called the `prev` (for \"previous\") and the `next` (for \"next\") pointers of the node.\n\nIn the singly linked list example, we had only one single pointer in each node, and this singular\npointer was always pointing to the next node in the sequence. This means that singly linked lists\nnormally have only the `next` pointer in them.\n\n![A diagram of a doubly linked list.](./../Figures/doubly-linked-list.png){#fig-linked-list2}\n\n\n\n### Recent change in the API\n\nOn previous versions of Zig, the `SinglyLinkedList` and `DoublyLinkedList` structs were initially implemented as \"generics data structures\".\nMeaning that, you would use a generic function to create a singly (or doubly) linked list that could store\nthe specific data type that you wanted to use. We will learn more about generics at @sec-generics, and also,\nhow we can create a \"generic data structure\" at @sec-generic-struct.\n\nHowever, on the latest versions of Zig, the structs `SinglyLinkedList` and `DoublyLinkedList` were altered to use a\n\"less generic API\". This specific change was introduced on April 3, 2025. Therefore, check if your Zig version is one released after this\ndate. Just have in mind that if you don't have a very recent version of the Zig compiler,\nyou might have problems while trying to compile the next examples exposed here.\n\n\n\n### How to use a singly linked list\n\nFor example, consider that you are creating a singly linked list that is going to store `u32` values.\nGiven this scenario, the first thing that we need to do, is to create a \"node type\" that is capable\nof storing a `u32` value. The `NodeU32` type exposed below demonstrates such \"node type\".\n\nNotice that the data type associated with the member named `data` is the most important part of this\ncustom \"node type\". It determines the data type that is going to be stored in each node.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst NodeU32 = struct {\n    data: u32,\n    node: std.SinglyLinkedList.Node = .{},\n};\n```\n:::\n\n\n\nAfter we created our custom \"node type\" that can store the specific data type that we\nwant, we can just create a new and empty singly linked list, which will store our nodes.\nTo do that, we just create a new object with the type `SinglyLinkedList`, like this:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar list: std.SinglyLinkedList = .{};\n```\n:::\n\n\n\nNow, we have our linked list... But how can we insert nodes in it? Well, first of all,\nwe need to create our nodes. So let's focus on that first. The snippet exposed below demonstrates\nhow we could use our `NodeU32` struct to create such nodes.\n\nNotice in this snippet that we are just setting the `data` member of the struct for now.\nWe don't need to connect these nodes together in this first instance. This is why we ignore\nthe `node` member at first. But we are going to connect these nodes in a future point of the code, which is\nwhy these objects are marked as \"variable objects\", so that we can alter them in the future.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n```\n:::\n\n\n\nNow that we have both the linked list and also the nodes created, we can start to connect them together.\nYou can use the `prepend()` method from the linked list object to insert the first node in the list, which\nis the \"head\" of the linked list. As the name suggests, this specific method prepends the input node to the linked list,\nor, in other words, it transforms the input node into the first node of the list.\n\nAfter we added the \"head node\" of the list, we can start to add the \"next nodes\" in the list by using the `insertAfter()` method\nfrom the `SinglyLinkedList.Node` type, which, in our case here, is accessible through the `node` member of our\n`NodeU32` type. Thus, we can start to create the connections between the nodes by calling this method from the node objects\nthat are present in the list. Like in this example below:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nlist.prepend(&two.node); // {2}\ntwo.node.insertAfter(&five.node); // {2, 5}\ntwo.node.insertAfter(&three.node); // {2, 3, 5}\n```\n:::\n\n\n\nYou can also call the `prepend()` method again to add new nodes to the beginning of the linked list, which\nmeans, effectively, changing the \"head node\" of the list, like this:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nlist.prepend(&one.node); // {1, 2, 3, 5}\n```\n:::\n\n\n\n\nThere are other methods available from the singly linked list object that you might be interested. You can find a\nsummary of them in the bullet points below:\n\n- `remove()` to remove a specific node from the linked list.\n- `len()` to count how many nodes there is in the linked list.\n- `popFirst()` to remove the first node (i.e., the \"head\") from the linked list.\n\nSo, that is how singly linked lists work in Zig in a nutshell. To sum up,\nthis is all the source code that was exposed in this section inside the single cell:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst NodeU32 = struct {\n    data: u32,\n    node: std.SinglyLinkedList.Node = .{},\n};\n\nvar list: std.SinglyLinkedList = .{};\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nlist.prepend(&two.node); // {2}\ntwo.node.insertAfter(&five.node); // {2, 5}\ntwo.node.insertAfter(&three.node); // {2, 3, 5}\nlist.prepend(&one.node); // {1, 2, 3, 5}\n\ntry stdout.print(\"Number of nodes: {}\", .{list.len()});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nNumber of nodes: 4\n```\n\n\n:::\n:::\n\n\n\n\n### How to use a doubly linked list\n\nIf you want to use a doubly linked list instead, you will face a similar workflow compared to the\nsingly linked list:\n\n1. You first create a \"custom node type\" that can store the specific data type that you want.\n2. Create an empty doubly linked list object.\n3. Create the nodes of linked list.\n4. Start to insert the nodes inside the list.\n\nIn your \"custom node type\", you should use the `DoublyLinkedList.Node` type to denote\nthe `node` member of the struct. The snippet below demonstrates that. Here we are creating,\nonce again, a node type that can store `u32` values. But this time, this struct is tailored\nto be used inside a `DoublyLinkedList` struct.\n\nAfter this step, the way that you create the new empty linked list, and the nodes that you want insert,\nis practically identical to the singly linked list case. But, this time,\nwe normally use the `append()` method from the linked list object to add new nodes to the list.\n\nThis `append()` method from the linked list object will always append the input node to the end of the\nlinked list. However, in case you want to add the new node into a different position of the list, then,\nyou should take a look at the `insertAfter()` and `insertBefore()` methods of the linked list object.\nThese methods allow you to insert the new node either after or before an existing node in the list.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst NodeU32 = struct {\n    data: u32,\n    node: std.DoublyLinkedList.Node = .{},\n};\n\nvar list: std.DoublyLinkedList = .{};\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nlist.append(&one.node); // {1}\nlist.append(&three.node); // {1, 3}\nlist.insertAfter(\n    &one.node,\n    &five.node\n); // {1, 5, 3}\nlist.append(&two.node); // {1, 5, 3, 2}\n\ntry stdout.print(\"Number of nodes: {}\", .{list.len()});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nNumber of nodes: 4\n```\n\n\n:::\n:::\n\n\n\nThese are other methods from the `DoublyLinkedList` object that might interest you:\n\n- `remove()`: to remove a specific node from the list.\n- `len()`: to count the number of nodes in the list.\n- `prepend()`: to add a node to the beginning of the list (i.e. set the head node of the list).\n- `pop()`: to remove the last node of the list.\n- `popFirst()`: to remove the first node of the list.\n- `concatByMoving()`: to concat two doubly linked lists together.\n\n\n### Iterating through the linked list\n\nIf you want to iterate over the elements of the linked list, all you need to do is to follow\nthe trail created by the \"pointer to next node\". We usually do that inside a while loop, that simply goes to the\nnext node over and over, until it finds a null pointer, which means that we hit the end of the list.\n\nThis next example demonstrates how such while loop would work. Notice that we are using the `@fieldParentPtr()`\nbuilt-in function to get access to a pointer that points to the parent instance of the `node` object. In other words,\nwe get access to a pointer to the `NodeU32` instance that contains the current node. This way, we can use this pointer\nto access the data that is currently stored in this node.\n\nAlso notice that in each iteration of the while loop, we are changing the value of the `it` variable to the next node\nin the list. The while loop is interrupted in the moment that this `it` variable becomes null, which will happen\nwhen the there is not \"next node\" in the list, which means that we have reached the end of the list.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst NodeU32 = struct {\n    data: u32,\n    node: std.SinglyLinkedList.Node = .{},\n};\n\nvar list: std.SinglyLinkedList = .{};\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nlist.prepend(&two.node); // {2}\nlist.prepend(&five.node); // {5, 2}\nlist.prepend(&three.node); // {3, 5, 2}\nlist.prepend(&one.node); // {1, 3, 5, 2}\n\nvar it = list.first;\nwhile (it) |node| : (it = node.next) {\n    const l: *NodeU32 = @fieldParentPtr(\n        \"node\", node\n    );\n    try stdout.print(\n        \"Current value: {}\", .{l.data}\n    );\n}\n```\n:::\n\n\n\n```\nCurrent value: 1\nCurrent value: 3\nCurrent value: 5\nCurrent value: 2\n```\n\n\n\n\n## Multi array structure\n\nZig introduces a new data structure called `MultiArrayList()`. It's a different version of the dynamic array\nthat we have introduced in @sec-dynamic-array. The difference between this structure and the `ArrayList()`\nthat we know from @sec-dynamic-array, is that `MultiArrayList()` creates a separate dynamic array\nfor each field of the struct that you provide as input.\n\nConsider the following code example. We create a new custom struct called `Person`. This\nstruct contains three different data members, or, three different fields. As consequence,\nwhen we provide this `Person` data type as input to `MultiArrayList()`, this\ncreates a \"struct of three different arrays\" called `PersonArray`. In other words,\nthis `PersonArray` is a struct that contains three internal dynamic arrays in it.\nOne array for each field found in the `Person` struct definition.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Person = struct {\n    name: []const u8,\n    age: u8,\n    height: f32,\n};\nconst PersonArray = std.MultiArrayList(Person);\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var people = PersonArray{};\n    defer people.deinit(allocator);\n\n    try people.append(allocator, .{\n        .name = \"Auguste\", .age = 15, .height = 1.54\n    });\n    try people.append(allocator, .{\n        .name = \"Elena\", .age = 26, .height = 1.65\n    });\n    try people.append(allocator, .{\n        .name = \"Michael\", .age = 64, .height = 1.87\n    });\n}\n```\n:::\n\n\n\nIn other words, instead of creating an array of \"persons\", the `MultiArrayList()` function\ncreates a \"struct of arrays\". Each data member of this struct is a different array that stores\nthe values of a specific field from the `Person` values that were added (or, appended) to this \"struct of arrays\".\nOne important detail is that each of these separate internal arrays stored inside `PersonArray`\nare dynamic arrays. This means that these arrays can grow in capacity automatically as needed, to accomodate\nmore values.\n\nThe @fig-multi-array exposed below presents a diagram that describes the `PersonArray` struct\nthat we have created in the previous code example. Notice that the values of the data members\npresent in each of the three `Person` values that we have appended into the `PersonArray` object\n, are scattered across three different internal arrays of the `PersonArray` object.\n\n![A diagram of the `PersonArray` struct.](./../Figures/multi-array.png){#fig-multi-array}\n\nYou can easily access each of these arrays separately, and iterate over the values of each array.\nFor that, you will need to call the `items()` method from the `PersonArray` object, and provide as input\nto this method, the name of the field that you want to iterate over.\nIf you want to iterate through the `.age` array for example, then, you need to call `items(.age)` from\nthe `PersonArray` object, like in the example below:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (people.items(.age)) |*age| {\n    try stdout.print(\"Age: {d}\\n\", .{age.*});\n}\n```\n:::\n\n\n\n```\nAge: 15\nAge: 26\nAge: 64\n```\n\n\nIn the above example, we are iterating over the values of the `.age` array, or,\nthe internal array of the `PersonArray` object that contains the values of the `age`\ndata member from the `Person` values that were added to the multi array struct.\n\nIn this example we are calling the `items()` method directly from the `PersonArray`\nobject. However, in most situations it's recommened to call this `items()` method\nfrom a \"slice object\", which you can create from the `slice()` method.\nThe reason for this is that calling `items()` multiple times have better performance\nif you use a slice object.\n\nTherefore, if you are planning to access only one of the\ninternal arrays from your \"multi array struct\", it's fine to call `items()` directly\nfrom the multi array object. But if you need to access many of the internal arrays\nfrom your \"multi array struct\", then, you will likely need to call `items()` more\nthan once, and, in such circumstance, is better to call `items()` through a slice object.\nThe example below demonstrates the use of such object:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar slice = people.slice();\nfor (slice.items(.age)) |*age| {\n    age.* += 10;\n}\nfor (slice.items(.name), slice.items(.age)) |*n,*a| {\n    try stdout.print(\n        \"Name: {s}, Age: {d}\\n\", .{n.*, a.*}\n    );\n}\n```\n:::\n\n\n\n```\nName: Auguste, Age: 25\nName: Elena, Age: 36\nName: Michael, Age: 74\n```\n\n\n## Conclusion\n\nThere are many other data structures that I haven't presented here.\nBut you can check them out at the official Zig Standard Library documentation page.\nActually, when you get into the [homepage of the documentation](https://ziglang.org/documentation/master/std/#)[^home], the first thing\nthat appears to you in this page, is a list of types and data structures that\nare available in the Zig Standard Library.\nThere are some very specific data structures in this list, like a\n[`BoundedArray` struct](https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray)[^bounded]\n, but there is also some more general structures, such as a\n[`PriorityQueue` struct](https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue)[^priority].\n\n\n[^home]: <https://ziglang.org/documentation/master/std/#>\n[^priority]: <https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue>.\n[^bounded]: <https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray>\n",
+    "supporting": [
+      "09-data-structures_files"
+    ],
+    "filters": [
+      "rmarkdown/pagebreak.lua"
+    ],
+    "includes": {},
+    "engineDependencies": {
+      "knitr": [
+        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
+      ]
+    },
+    "preserve": null,
+    "postProcess": false
+  }
+}
\ No newline at end of file
diff --git a/_freeze/Chapters/09-error-handling/execute-results/epub.json b/_freeze/Chapters/09-error-handling/execute-results/epub.json
new file mode 100644
index 00000000..bd4ccc0b
--- /dev/null
+++ b/_freeze/Chapters/09-error-handling/execute-results/epub.json
@@ -0,0 +1,21 @@
+{
+  "hash": "1ef4c69c6b1bfd8553723d38f6a46fb8",
+  "result": {
+    "engine": "knitr",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Error handling and unions {#sec-error-handling}\n\nIn this chapter, I want to discuss how error handling is done in Zig.\nWe already briefly learned about one of the available strategies to handle errors in Zig,\nwhich is the `try` keyword presented in @sec-main-file. But we still haven't learned about\nthe other methods, such as the `catch` keyword.\nI also want to discuss in this chapter how union types are created in Zig.\n\n## Learning more about errors in Zig\n\nBefore we get into how error handling is done, we need to learn more about what errors are in Zig.\nAn error is actually a value in Zig [@zigoverview]. In other words, when an error occurs inside your Zig program,\nit means that somewhere in your Zig codebase, an error value is being generated.\nAn error value is similar to any integer value that you create in your Zig code.\nYou can take an error value and pass it as input to a function,\nand you can also cast (or coerce) it into a different type of an error value.\n\nThis have some similarities with exceptions in C++ and Python.\nBecause in C++ and Python, when an exception happens inside a `try` block,\nyou can use a `catch` block (in C++) or an `except` block (in Python)\nto capture the exception produced in the `try` block,\nand pass it to functions as an input.\n\nHowever, error values in Zig are treated very differently than exceptions.\nFirst, you cannot ignore error values in your Zig code. Meaning that, if an error\nvalue appears somewhere in your source code, this error value must be explicitly handled in some way.\nThis also means that you cannot discard error values by assigning them to an underscore,\nas you could do with normal values and objects.\n\nTake the source code below as an example. Here we are trying to open a file that does not exist\nin my computer, and as a result, an obvious error value of `FileNotFound` is returned from the `openFile()`\nfunction. But because I'm assigning the result of this function to an underscore, I end up\ntrying to discard an error value.\n\nThe `zig` compiler detects this mistake, and raises a compile\nerror telling me that I'm trying to discard an error value.\nIt also adds a note message that suggests the use of `try`,\n`catch` or an if statement to explicitly handle this error value\nThis note is reinforcing that every possible error value must be explicitly handled in Zig.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst dir = std.fs.cwd();\n_ = dir.openFile(\"doesnt_exist.txt\", .{});\n```\n:::\n\n\n\n```\nt.zig:8:17: error: error set is discarded\nt.zig:8:17: note: consider using 'try', 'catch', or 'if'\n```\n\n\n### Returning errors from functions\n\nAs we described in @sec-main-file, when we have a function that might return an error\nvalue, this function normally includes an exclamation mark (`!`) in its return type\nannotation. The presence of this exclamation mark indicates that this function might\nreturn an error value as result, and, the `zig` compiler forces you to always handle explicitly\nthe case of this function returning an error value.\n\nTake a look at the `print_name()` function below. This function might return an error in the `stdout.print()` function call,\nand, as a consequence, its return type (`!void`) includes an exclamation mark in it.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_name() !void {\n    const stdout = std.getStdOut().writer();\n    try stdout.print(\"My name is Pedro!\", .{});\n}\n```\n:::\n\n\n\nIn the example above, we are using the exclamation mark to tell the `zig` compiler\nthat this function might return some error. But which error exactly is returned from\nthis function? For now, we are not specifying a specific error value. For now,\nwe only know that some error value (whatever it is) might be returned.\n\nBut in fact, you can (if you want to) specify clearly which exact error values\nmight be returned from this function. There are lot of examples of\nthis in the Zig Standard Library. Take this `fill()` function from\nthe `http.Client` module as an example. This function returns\neither a error value of type `ReadError`, or `void`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn fill(conn: *Connection) ReadError!void {\n    // The body of this function ...\n}\n```\n:::\n\n\n\nThis idea of specifying the exact error values that you expect to be returned\nfrom the function is interesting. Because they automatically become some sort of documentation\nof your function, and also, this allows the `zig` compiler to perform some extra checks over\nyour code. Because the compiler can check if there is any other type of error value\nthat is being generated inside your function, and, that it's not being accounted\nfor in this return type annotation.\n\nAnyway, you can list the types of errors that can be returned from the function\nby listing them on the left side of the exclamation mark. While the valid values\nstay on the right side of the exclamation mark. So the syntax format become:\n\n```\n<error-value>!<valid-value>\n```\n\n\n### Error sets\n\nBut what about when we have a single function that might return different types of errors?\nWhen you have such a function, you can list\nall of these different types of errors that can be returned from this function,\nthrough a structure in Zig that we call of an *error set*.\n\nAn error set is a special case of a union type. It's a union that contains error values in it.\nNot all programming languages have a notion of a \"union object\".\nBut in summary, a union is just a set of data types.\nUnions are used to allow an object to have multiple data types.\nFor example, a union of `x`, `y` and `z`, means that\nan object can be either of type `x`, or type `y` or type `z`.\n\nWe are going to talk in more depth about unions in @sec-unions.\nBut you can write an error set by writing the keyword `error` before\na pair of curly braces, then you list the error values that can be\nreturned from the function inside this pair of curly braces.\n\nTake the `resolvePath()` function below as an example, which comes from the\n`introspect.zig` module of the Zig Standard Library. We can see in its return type annotation, that this\nfunction return either: 1) a valid slice of `u8` values (`[]u8`); or, 2) one of the three different\ntypes of error values listed inside the error set (`OutOfMemory`, `Unexpected`, etc.).\nThis is an usage example of an error set.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn resolvePath(\n    ally: mem.Allocator,\n    p: []const u8,\n) error{\n    OutOfMemory,\n    CurrentWorkingDirectoryUnlinked,\n    Unexpected,\n}![]u8 {\n    // The body of the function ...\n}\n```\n:::\n\n\n\n\nThis is a valid way of annotating the return value of a Zig function. But, if you navigate through\nthe modules that composes the Zig Standard Library, you will notice that, for the majority of cases,\nthe programmers prefer to give a descriptive name to this error set, and then, use this name (or this \"label\")\nof the error set in the return type annotation, instead of using the error set directly.\n\nWe can see that in the `ReadError` error set that we showed earlier in the `fill()` function,\nwhich is defined in the `http.Client` module.\nSo yes, I presented the `ReadError` as if it was just a standard and single error value, but in fact,\nit's an error set defined in the `http.Client` module, and therefore, it actually represents\na set of different error values that might happen inside the `fill()` function.\n\n\nTake a look at the `ReadError` definition reproduced below. Notice that we are grouping all of these\ndifferent error values into a single object, and then, we use this object into the return type annotation of the function.\nLike the `fill()` function that we showed earlier, or, the `readvDirect()` function from the same module,\nwhich is reproduced below.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const ReadError = error{\n    TlsFailure,\n    TlsAlert,\n    ConnectionTimedOut,\n    ConnectionResetByPeer,\n    UnexpectedReadFailure,\n    EndOfStream,\n};\n// Some lines of code\npub fn readvDirect(\n        conn: *Connection,\n        buffers: []std.posix.iovec\n    ) ReadError!usize {\n    // The body of the function ...\n}\n```\n:::\n\n\n\nSo, an error set is just a convenient way of grouping a set of\npossible error values into a single object, or a single type of an error value.\n\n\n### Casting error values\n\nLet's suppose you have two different error sets, named `A` and `B`.\nIf error set `A` is a superset of error set `B`, then, you can cast (or coerce)\nerror values from `B` into error values of `A`.\n\nError sets are just a set of error values. So, if the error set `A`\ncontains all error values from the error set `B`, then `A`\nbecomes a superset of `B`. You could also say\nthat the error set `B` is a subset of error set `A`.\n\nThe example below demonstrates this idea. Because `A` contains all\nvalues from `B`, `A` is a superset of `B`.\nIn math notation, we would say that $A \\supset B$.\nAs a consequence, we can give an error value from `B` as input to the `cast()`\nfunction, and, implicitly cast this input into the same error value, but from the `A` set.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst A = error{\n    ConnectionTimeoutError,\n    DatabaseNotFound,\n    OutOfMemory,\n    InvalidToken,\n};\nconst B = error {\n    OutOfMemory,\n};\n\nfn cast(err: B) A {\n    return err;\n}\n\ntest \"coerce error value\" {\n    const error_value = cast(B.OutOfMemory);\n    try std.testing.expect(\n        error_value == A.OutOfMemory\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file3e2d5fb03d41.test.coerce error value...OKA\n  All 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n## How to handle errors\n\nNow that we learned more about what errors are in Zig,\nlet's discuss the available strategies to handle these errors,\nwhich are:\n\n- `try` keyword;\n- `catch` keyword;\n- an if statement;\n- `errdefer` keyword;\n\n\n\n### What `try` means?\n\nAs I described over the previous sections, when we say that an expression might\nreturn an error, we are basically referring to an expression that have\na return type in the format `!T`.\nThe `!` indicates that this expression returns either an error value, or a value of type `T`.\n\nIn @sec-main-file, I presented the `try` keyword and where to use it.\nBut I did not talked about what exactly this keyword does to your code,\nor, in other words, I have not explained yet what `try` means in your code.\n\nIn essence, when you use the `try` keyword in an expression, you are telling\nthe `zig` compiler the following: \"Hey! Execute this expression for me,\nand, if this expression return an error, please, return this error for me\nand stop the execution of my program. But if this expression return a valid\nvalue, then, return this value, and move on\".\n\nIn other words, the `try` keyword is essentially, a strategy to enter in panic mode, and stop\nthe execution of your program in case an error occurs.\nWith the `try` keyword, you are telling the `zig` compiler, that stopping the execution\nof your program is the most reasonable strategy to take if an error occurs\nin that particular expression.\n\n### The `catch` keyword\n\nOk, now that we understand properly what `try` means, let's discuss `catch` now.\nOne important detail here, is that you can use `try` or `catch` to handle your errors,\nbut you **cannot use `try` and `catch` together**. In other words, `try` and `catch`\nare different and completely separate strategies in the Zig language.\n\nThis is uncommon, and different than what happens in other languages. Most\nprogramming languages that adopts the *try catch* pattern (such as C++, R, Python, Javascript, etc.), normally use\nthese two keywords together to form the complete logic to\nproperly handle the errors.\nAnyway, Zig tries a different approach in the *try catch* pattern.\n\nSo, we learned already about what `try` means, and we also known that both\n`try` and `catch` should be used alone, separate from each other. But\nwhat exactly `catch` do in Zig? With `catch`, we can construct a block of\nlogic to handle the error value, in case it happens in the current expression.\n\nLook at the code example below. Once again, we go back to the previous\nexample where we were trying to open a file that doesn't exist in my computer,\nbut this time, I use `catch` to actually implement a logic to handle the error, instead of\njust stopping the execution right away.\n\nMore specifically, in this example, I'm using a logger object to record some logs into\nthe system, before I return the error, and stop the execution of the program. For example,\nthis could be some part of the codebase of a complex system that I do not have full control over,\nand I want to record these logs before the program crashes, so that I can debug it later\n(e.g. maybe I cannot compile the full program, and properly debug it with a debugger. So, these logs might\nbe a valid strategy to surpass this barrier).\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst dir = std.fs.cwd();\nconst file = dir.openFile(\n    \"doesnt_exist.txt\", .{}\n) catch |err| {\n    logger.record_context();\n    logger.log_error(err);\n    return err;\n};\n```\n:::\n\n\n\n\nTherefore, we use `catch` to create a block of expressions that will handle the error.\nI can return the error value from this block of expressions, like I did in the above example,\nwhich, will make the program enter in panic mode, and, stop the execution.\nBut I could also, return a valid value from this block of code, which would\nbe stored in the `file` object.\n\nNotice that, instead of writing the keyword before the expression that might return the error,\nlike we do with `try`, we write `catch` after the expression. We can open the pair of pipes (`|`),\nwhich captures the error value returned by the expression, and makes\nthis error value available in the scope of the `catch` block as the object named `err`.\nIn other words, because I wrote `|err|` in the code, I can access the error value\nreturned by the expression, by using the `err` object.\n\nAlthough this being the most common use of `catch`, you can also use this keyword\nto handle the error in a \"default value\" style. That is, if the expression returns\nan error, we use the default value instead. Otherwise, we use the valid value returned\nby the expression.\n\nThe Zig official language reference, provides a great example of this \"default value\"\nstrategy with `catch`. This example is reproduced below. Notice that we are trying to parse\nsome unsigned integer from a string object named `str`. In other words, this function\nis trying to transform an object of type `[]const u8` (i.e., an array of characters, a string, etc.)\ninto an object of type `u64`.\n\nBut this parsing process done by the function `parseU64()` may fail, resulting in a runtime error.\nThe `catch` keyword used in this example provides an alternative value (13) to be used in case\nthis `parseU64()` function raises an error. So, the expression below essentially means:\n\"Hey! Please, parse this string into a `u64` for me, and store the results into the\nobject `number`. But, if an error occurs, then, use the value `13` instead\".\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number = parseU64(str, 10) catch 13;\n```\n:::\n\n\n\nSo, at the end of this process, the object `number` will contain either a `u64` integer\nthat was parsed successfully from the input string `str`, or, if an error occurs in the\nparsing process, it will contain the `u64` value `13` that was provided by the `catch`\nkeyword as the \"default\", or, the \"alternative\" value.\n\n\n\n### Using if statements\n\nNow, you can also use if statements to handle errors in your Zig code.\nIn the example below, I'm reproducing the previous example, where\nwe try to parse an integer value from an input string with a function\nnamed `parseU64()`.\n\nWe execute the expression inside the \"if\". If this expression returns an\nerror value, the \"if branch\" (or, the \"true branch\") of the if statement is not executed.\nBut if this expression returns a valid value instead, then, this value is unwrapped\ninto the `number` object.\n\nThis means that, if the `parseU64()` expression returns a valid value, this value becomes available\ninside the scope of this \"if branch\" (i.e., the \"true branch\") through the object that we listed inside the pair\nof pipe character (`|`), which is the object `number`.\n\nIf an error occurs, we can use an \"else branch\" (or the \"false branch\") of the if statement\nto handle the error. In the example below, we are using the `else` in the if statement\nto unwrap the error value (that was returned by `parseU64()`) into the `err` object,\nand handle the error.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (parseU64(str, 10)) |number| {\n    // do something with `number` here\n} else |err| {\n    // handle the error value.\n}\n```\n:::\n\n\n\nNow, if the expression that you are executing returns different types of error values,\nand you want to take a different action in each of these types of error values, the\n`try` and `catch` keywords, and the if statement strategy, becomes limited.\n\nFor this type of situation, the official documentation of the language suggests\nthe use of a switch statement together with an if statement [@zigdocs].\nThe basic idea is, to use the if statement to execute the expression, and\nuse the \"else branch\" to pass the error value to a switch statement, where\nyou define a different action for each type of error value that might be\nreturned by the expression executed in the if statement.\n\nThe example below demonstrates this idea. We first try to add (or register) a set of\ntasks to a queue. If this \"registration process\" occurs well, we then try\nto distribute these tasks across the workers of our system. But\nif this \"registration process\" returns an error value, we then use a switch\nstatement in the \"else branch\" to handle each possible error value.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (add_tasks_to_queue(&queue, tasks)) |_| {\n    distribute_tasks(&queue);\n} else |err| switch (err) {\n    error.InvalidTaskName => {\n        // do something\n    },\n    error.TimeoutTooBig => {\n        // do something\n    },\n    error.QueueNotFound => {\n        // do something\n    },\n    // and all the other error options ...\n}\n```\n:::\n\n\n\n\n### The `errdefer` keyword {#sec-errdefer2}\n\nA common pattern in C programs in general, is to clean resources when an error occurs during\nthe execution of the program. In other words, one common way to handle errors, is to perform\n\"cleanup actions\" before we exit our program. This guarantees that a runtime error does not make\nour program to leak resources of the system.\n\n\nThe `errdefer` keyword is a tool to perform such \"cleanup actions\" in hostile situations.\nThis keyword is commonly used to clean (or to free) allocated resources, before the execution of our program\ngets stopped because of an error value being generated.\n\nThe basic idea is to provide an expression to the `errdefer` keyword. Then,\n`errdefer` executes this expression if, and only if, an error occurs\nduring the execution of the current scope.\nIn the example below, we are using an allocator object (that we have presented in @sec-allocators)\nto create a new `User` object. If we are successful in creating and registering this new user,\nthis `create_user()` function will return this new `User` object as its return value.\n\nHowever, if for some reason, an error value is generated by some expression\nthat is after the `errdefer` line, for example, in the `db.add(user)` expression,\nthe expression registered by `errdefer` gets executed before the error value is returned\nfrom the function, and before the program enters in panic mode and stops the\ncurrent execution.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn create_user(db: Database, allocator: Allocator) !User {\n    const user = try allocator.create(User);\n    errdefer allocator.destroy(user);\n\n    // Register new user in the Database.\n    _ = try db.register_user(user);\n    return user;\n}\n```\n:::\n\n\n\nBy using `errdefer` to destroy the `user` object that we have just created,\nwe guarantee that the memory allocated for this `user` object\ngets freed, before the execution of the program stops.\nBecause if the expression `try db.add(user)` returns an error value,\nthe execution of our program stops, and we lose all references and control over the memory\nthat we have allocated for the `user` object.\nAs a result, if we do not free the memory associated with the `user` object before the program stops,\nwe cannot free this memory anymore. We simply lose our chance to do the right thing.\nThat is why `errdefer` is essential in this situation.\n\nJust to state clearly the differences between `defer` and `errdefer`\n(which I described in @sec-defer and @sec-errdefer1), it might be worth\nto discuss the subject a bit further. You might still have the question\n\"why use `errdefer` if we can use `defer` instead?\" in your mind.\n\nAlthough being similar, the key difference between `errdefer` and `defer` keyword\nis when the provided expression gets executed.\nThe `defer` keyword always execute the provided expression at the end of the\ncurrent scope, no matter how your code exits this scope.\nIn contrast, `errdefer` executes the provided expression only when an error occurs in the\ncurrent scope.\n\nThis becomes important if a resource that you allocate in the\ncurrent scope gets freed later in your code, in a different scope.\nThe `create_user()` functions is an example of this. If you think\nclosely about this function, you will notice that this function returns\nthe `user` object as the result.\n\nIn other words, the allocated memory for the `user` object does not get\nfreed inside the `create_user()` function, if it returns successfully.\nSo, if an error does not occur inside this function, the `user` object\nis returned from the function, and probably, the code that runs after\nthis `create_user()` function will be responsible for freeing\nthe memory of the `user` object.\n\nBut what if an error occurs inside the `create_user()` function? What happens then?\nThis would mean that the execution of your code would stop in this `create_user()`\nfunction, and, as a consequence, the code that runs after this `create_user()`\nfunction would simply not run, and, as a result, the memory of the `user` object\nwould not be freed before your program stops.\n\nThis is the perfect scenario for `errdefer`. We use this keyword to guarantee\nthat our program will free the allocated memory for the `user` object,\neven if an error occurs inside the `create_user()` function.\n\nIf you allocate and free some memory for an object inside the same scope, then,\njust use `defer` and be happy, i.e., `errdefer` have no use for you in such situation.\nBut if you allocate some memory in a scope A, but you only free this memory\nlater, in a scope B for example, then, `errdefer` becomes useful to avoid leaking memory\nin sketchy situations.\n\n\n\n## Union type in Zig {#sec-unions}\n\nA union type defines a set of types that an object can be. It's like a list of\noptions. Each option is a type that an object can assume. Therefore, unions in Zig\nhave the same meaning, or, the same role as unions in C. They are used for the same purpose.\nYou could also say that unions in Zig produces a similar effect to\n[using `typing.Union` in Python](https://docs.python.org/3/library/typing.html#typing.Union)[^pyunion].\n\n[^pyunion]: <https://docs.python.org/3/library/typing.html#typing.Union>\n\nFor example, you might be creating an API that sends data to a data lake, hosted\nin some private cloud infrastructure. Suppose you have created different structs in your codebase,\nto store the necessary information that you need, in order to connect to the services of\neach mainstream data lake service (Amazon S3, Azure Blob, etc.).\n\nNow, suppose you also have a function named `send_event()` that receives an event as input,\nand, a target data lake, and it sends the input event to the data lake specified in the\ntarget data lake argument. But this target data lake could be any of the three mainstream data lakes\nservices (Amazon S3, Azure Blob, etc.). Here is where an union can help you.\n\nThe union `LakeTarget` defined below allows the `lake_target` argument of `send_event()`\nto be either an object of type `AzureBlob`, or type `AmazonS3`, or type `GoogleGCP`.\nThis union allows the `send_event()` function to receive an object of any of these three types\nas input in the `lake_target` argument.\n\nRemember that each of these three types (`AmazonS3`, `GoogleGCP` and `AzureBlob`)\nare separate structs that we have defined in our source code. So, at first glance,\nthey are separate data types in our source code. But is the `union` keyword that\nunifies them into a single data type called `LakeTarget`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst LakeTarget = union {\n    azure: AzureBlob,\n    amazon: AmazonS3,\n    google: GoogleGCP,\n};\n\nfn send_event(\n    event: Event,\n    lake_target: LakeTarget\n) bool {\n    // body of the function ...\n}\n```\n:::\n\n\n\nAn union definition is composed by a list of data members. Each data member is of a specific data type.\nIn the example above, the `LakeTarget` union have three data members (`azure`, `amazon`, `google`).\nWhen you instantiate an object that uses an union type, you can only use one of its data members\nin this instantiation.\n\nYou could also interpret this as: only one data member of an union type can be activated at a time, the other data\nmembers remain deactivated and unaccessible. For example, if you create a `LakeTarget` object that uses\nthe `azure` data member, you can no longer use or access the data members `google` or `amazon`.\nIt's like if these other data members didn't exist at all in the `LakeTarget` type.\n\nYou can see this logic in the example below. Notice that, we first instantiate the union\nobject using the `azure` data member. As a result, this `target` object contains only\nthe `azure` data member inside of it. Only this data member is active in this object.\nThat is why the last line in this code example is invalid. Because we are trying to instantiate the data member\n`google`, which is currently inactive for this `target` object, and as a result, the program\nenters in panic mode warning us about this mistake through a loud error message.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar target = LakeTarget {\n    .azure = AzureBlob.init()\n};\n// Only the `azure` data member exist inside\n// the `target` object, and, as a result, this\n// line below is invalid:\ntarget.google = GoogleGCP.init();\n```\n:::\n\n\n\n```\nthread 2177312 panic: access of union field 'google' while\n    field 'azure' is active:\n    target.google = GoogleGCP.init();\n          ^\n```\n\nSo, when you instantiate an union object, you must choose one of the data types (or, one of the data members)\nlisted in the union type. In the example above, I choose to use the `azure` data member, and, as a result,\nall other data members were automatically deactivated,\nand you can no longer use them after you instantiate the object.\n\nYou can activate another data member by completely redefining the entire enum object.\nIn the example below, I initially use the `azure` data member. But then, I redefine the\n`target` object to use a new `LakeTarget` object, which uses the `google` data member.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar target = LakeTarget {\n    .azure = AzureBlob.init()\n};\ntarget = LakeTarget {\n    .google = GoogleGCP.init()\n};\n```\n:::\n\n\n\nA curious fact about union types, is that, at first, you cannot use them in switch statements (which were presented in @sec-switch).\nIn other words, if you have an object of type `LakeTarget` for example, you cannot give this object\nas input to a switch statement.\n\nBut what if you really need to do so? What if you actually need to\nprovide an \"union object\" to a switch statement? The answer to this question relies on another special type in Zig,\nwhich are the *tagged unions*. To create a tagged union, all you have to do is to add\nan enum type into your union declaration.\n\nAs an example of a tagged union in Zig, take the `Registry` type exposed\nbelow. This type comes from the\n[`grammar.zig` module](https://github.com/ziglang/zig/blob/30b4a87db711c368853b3eff8e214ab681810ef9/tools/spirv/grammar.zig)[^grammar]\nfrom the Zig repository. This union type lists different types of registries.\nBut notice this time, the use of `(enum)` after the `union` keyword. This is what makes\nthis union type a tagged union. By being a tagged union, an object of this `Registry` type\ncan be used as input in a switch statement. This is all you have to do. Just add `(enum)`\nto your `union` declaration, and you can use it in switch statements.\n\n[^grammar]: <https://github.com/ziglang/zig/blob/30b4a87db711c368853b3eff8e214ab681810ef9/tools/spirv/grammar.zig>.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const Registry = union(enum) {\n    core: CoreRegistry,\n    extension: ExtensionRegistry,\n};\n```\n:::\n",
+    "supporting": [
+      "09-error-handling_files"
+    ],
+    "filters": [
+      "rmarkdown/pagebreak.lua"
+    ],
+    "includes": {},
+    "engineDependencies": {
+      "knitr": [
+        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
+      ]
+    },
+    "preserve": null,
+    "postProcess": false
+  }
+}
\ No newline at end of file
diff --git a/_freeze/Chapters/10-stack-project/execute-results/epub.json b/_freeze/Chapters/10-stack-project/execute-results/epub.json
new file mode 100644
index 00000000..8c071b38
--- /dev/null
+++ b/_freeze/Chapters/10-stack-project/execute-results/epub.json
@@ -0,0 +1,21 @@
+{
+  "hash": "801c378f39cbcf646c40a137880aa3b8",
+  "result": {
+    "engine": "knitr",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Project 3 - Building a stack data structure\n\nIn this chapter we are going to implement a stack data structure as our next small project\nin this book. Implementing basic data structures in any language is kind of a\n\"kindergarten task\" (if this term even exist) in computer science (CS), because\nwe normally learn and implement them in the first semesters of CS.\n\nBut this is actually good! Since this should be a very easy task, we don't need much to explain\nwhat a stack is, then, we can concentrate on what is really important here, which is learning\nhow the concept of \"generics\" is implemented in the Zig language, and how one of the key\nfeatures of Zig, which is comptime, works, and use the stack data structure to demonstrate\nthese concepts on the fly.\n\nBut before we get into building the stack data structure, we first need to understand\nwhat the `comptime` keyword does to your code, and after that, we also need to learn about\nhow generics work in Zig.\n\n\n## Understanding `comptime` in Zig {#sec-comptime}\n\nOne of the key features of Zig is `comptime`. This keyword introduces a whole\nnew concept and paradigm, that is tightly connected with the compilation process.\nIn @sec-compile-time we have described the importance and the role that \"compile-time versus runtime\"\nplays into Zig. In that section, we learned that the rules applied to a value/object change\na lot depending on whether this value is known at compile-time, or just at runtime.\n\nThe `comptime` keyword is strongly related to these two spaces in time (compile-time and runtime).\nLet's quickly recap the differences. Compile-time is the period of time when your\nZig source code is being compiled by the `zig` compiler, while the runtime is\nthe period of time when your Zig program is being executed, i.e., when we execute\nthe binary files that were generated by the `zig` compiler.\n\nThere are three ways in which you can apply the `comptime` keyword, which are:\n\n- apply `comptime` on a function argument.\n- apply `comptime` on an object.\n- apply `comptime` on a block of expressions.\n\n\n\n### Applying over a function argument\n\nWhen you apply the `comptime` keyword on a function argument, you are saying to the `zig` compiler\nthat the value assigned to that particular function argument must be known at compile-time.\nWe explained in detail in @sec-compile-time what exactly \"value known at compile-time\" means. So\nif you have any doubts about this idea, refer back to that section.\n\nNow let's think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement\nto that particular function argument. If the programmer accidentally tries to give a value to this\nfunction argument that is not known at compile time, the `zig` compiler will notice this problem, and\nas a consequence, it will raise a compilation error saying that it cannot compile your program. Because\nyou are providing a value that is \"runtime known\" to a function argument that must be \"compile-time known\".\n\nTake a look at this very simple example below, where we define a `twice()` function, that simply\ndoubles the input value named `num`. Notice that we use the `comptime` keyword before the name\nof the function argument. This keyword is marking the function argument `num` as a \"comptime argument\".\n\nThat is a function argument whose value must be compile-time known. This is why the expression\n`twice(5678)` is valid, and no compilation errors are raised. Because the value `5678`\nis compile-time known, so this is the expected behaviour for this function.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file3f5922d93418.test.test comptime...OKAll 1 \n   tests passed.\n```\n\n\n:::\n:::\n\n\n\nBut what if we provide a number that is not compile-time known to this function?\nFor example, your program might receive some input from the user through the `stdin`\nchannel of your system. This input from the user might be many different things,\nand cannot be predicted at compile-time. These circumstances make this \"input\nfrom the user\" a value that is runtime-known only.\n\nIn the example below, this \"input from the user\" is initially received as a string,\nwhich is then parsed and transformed into a integer value, and the result of this operation\nis stored inside the `n` object.\n\nBecause the \"input of the user\" is known only at runtime, the value of the object `n` is determined only at runtime.\nAs consequence, we cannot provide this object as input to the `twice()` function.\nThe `zig` compiler will not allow it, because we marked\nthe `num` argument as a \"comptime argument\". That is why the `zig` compiler raises\nthe compile-time error exposed below:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\n\npub fn main() !void {\n    var buffer: [5]u8 = .{ 0, 0, 0, 0, 0 };\n    const stdout = std.io.getStdOut().writer();\n    const stdin = std.io.getStdIn().reader();\n    _ = try stdout.write(\"Please write a 4-digit integer number\\n\");\n    _ = try stdin.readUntilDelimiter(&buffer, '\\n');\n\n    try stdout.print(\"Input: {s}\", .{buffer});\n    const n: u32 = try std.fmt.parseInt(\n        u32, buffer[0 .. buffer.len - 1], 10\n    );\n    const twice_result = twice(n);\n    try stdout.print(\"Result: {d}\\n\", .{twice_result});\n}\n```\n:::\n\n\n\n```\nt.zig:12:16: error: unable to resolve comptime value\n    const twice_result = twice(n);\n                               ^\n```\n\nComptime arguments are frequently used on functions that return some sort\nof generic structure. In fact, `comptime` is the essence (or the basis) to make generics in Zig.\nWe are going to talk more about generics in @sec-generics.\n\nFor now, let's take a look at this code example from @karlseguin_generics. You\ncan see that this `IntArray()` function has one argument named `length`.\nThis argument is marked as comptime, and receives a value of type `usize` as input. So the value given to this argument\nmust be compile-time known.\nWe can also see that this function returns an array of `i64` values as output.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n```\n:::\n\n\n\nNow, the key component of this function is the `length` argument. This argument\nis used to determine the size of the array that is produced by the function. Let's\nthink about the consequences of that. If the size of the array is dependent on\nthe value assigned to the `length` argument, this means that the data type of the\noutput of the function depends on the value of this `length` argument.\n\nLet this statement sink for a bit in your mind. As I described in @sec-root-file,\nZig is a strongly-typed language, especially on function declarations.\nSo every time we write a function in Zig, we have to annotate the data type of\nthe value returned by the function. But how can we do that, if this data type\ndepends on the value given to the argument of the function?\n\nThink about this for a second. If `length` is equal to 3 for example, then, the\nreturn type of the function is `[3]i64`. But if `length` is equal to 40, then,\nthe return type becomes `[40]i64`. At this point the `zig` compiler would be confused,\nand raise a compilation error, saying something like this:\n\n> Hey! You have annotated that this function should return a `[3]i64` value, but I got a `[40]i64` value instead! This doesn't look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when\nthe `type` keyword comes in. This `type` keyword is basically saying to the\n`zig` compiler that this function will return some data type as output, but it doesn't know yet\nwhat exactly data type that is. We will talk more about this in @sec-generics.\n\n\n\n### Applying over an expression\n\nWhen you apply the `comptime` keyword over an expression, then, it is guaranteed that the `zig` compiler will\nexecute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time\n(e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the `zig` compiler\nwill raise a compilation error.\n\nTake this example from the official documentation of Zig [@zigdocs]. We\nare executing the same `fibonacci()` function both at runtime, and, at compile-time.\nThe function is executed by default at runtime, but because we use the `comptime`\nkeyword in the second \"try expression\", this expression is executed at compile-time.\n\nThis might be a bit confusing for some people. Yes! When I say that this expression\nis executed at compile-time, I mean that this expression is compiled and executed\nwhile the `zig` compiler is compiling your Zig source code.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file3f596129a9ee.test.fibonacci...OKAll 1 test\n  ts passed.\n```\n\n\n:::\n:::\n\n\n\nA lot of your Zig source code might be potentially executed at compile-time,\nbecause the `zig` compiler can figure out the output of some expressions.\nEspecially if these expressions depend only on compile-time known values.\nWe have talked about this in @sec-compile-time.\n\nBut when you use the `comptime` keyword on an expression, there is no \"it might be executed\nat compile-time\" anymore. With the `comptime` keyword you are ordering the `zig` compiler\nto execute this expression at compile-time. You are imposing this rule, it is guaranteed\nthat the compiler will always execute it at compile-time. Or, at least, the compiler\nwill try to execute it. If the compiler cannot execute the expression for whatever reason,\nthe compiler will raise a compilation error.\n\n\n### Applying over a block\n\nBlocks were described in @sec-blocks. When you apply the `comptime` keyword to a\nblock of expressions, you get essentially the same effect as when you apply this keyword to\na single expression. That is, the entire block of expressions is executed at\ncompile-time by the `zig` compiler.\n\nIn the example below, we mark the block labeled of `blk` as a comptime block,\nand, therefore, the expressions inside this block are executed at compile-time.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file3f5947d42e1f.test.fibonacci in a block...O\n  OKAll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n## Introducing Generics {#sec-generics}\n\nFirst of all, what is a generic? Generic is the idea to allow a type\n(`f64`, `u8`, `u32`, `bool`, and also, user-defined types, like the `User` struct\nthat we defined in @sec-structs-and-oop) to be a parameter to methods, classes and\ninterfaces [@geeks_generics]. In other words, a \"generic\" is a class (or a method) that can work\nwith multiple data types.\n\nFor example, in Java, generics are created through the operator `<>`. With this operator,\na Java class is capable of receiving a data type as input, and therefore, the class can fit\nits features according to this input data type.\nAs another example, generics in C++ are supported through the concept of templates.\nClass templates in C++ are generics.\n\nIn Zig, generics are implemented through `comptime`. The `comptime` keyword\nallows us to collect a data type at compile time, and pass this data type as\ninput to a piece of code.\n\n\n### A generic function {#sec-generic-fun}\n\nTake the `max()` function exposed below as a first example.\nThis function is essentially a \"generic function\".\nIn this function, we have a comptime function argument named `T`.\nNotice that this `T` argument has a data type of `type`. Weird right? This `type` keyword is the\n\"father of all types\", or, \"the type of types\" in Zig.\n\nBecause we have used this `type` keyword in the `T` argument, we are telling\nthe `zig` compiler that this `T` argument will receive some data type as input.\nAlso notice the use of the `comptime` keyword in this argument.\nAs I described in @sec-comptime, every time you use this keyword in a function argument,\nthis means that the value of this argument must be known at compile-time.\nThis makes sense, right? Because there is no data type that is not known at compile-time.\n\nThink about this. Every data type that you will ever write is always\nknown at compile-time. Especially because data types are an essential\ninformation for the compiler to actually compile your source code.\nHaving this in mind, makes sense to mark this argument as a comptime argument.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\n```\n:::\n\n\n\nAlso notice that the value of the `T` argument is actually used\nto define the data type of the other arguments in the function, `a` and `b`, and also at the\nreturn type annotation of the function.\nThat is, the data type of these arguments (`a` and `b`), and, the return data type of the function itself,\nare determined by the input value given to the `T` argument.\n\nAs a result, we have a generic function that works with different data types.\nFor example, I can provide `u8` values to this `max()` function, and it will work as expected.\nBut if I provide `f64` values instead, it will also work as expected.\nWithout a generic function, I would have to write a different `max()` function\nfor each data type I wanted to use.\nThis generic function provides a very useful shortcut for us.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\ntest \"test max\" {\n    const n1 = max(u8, 4, 10);\n    std.debug.print(\"Max n1: {d}\\n\", .{n1});\n    const n2 = max(f64, 89.24, 64.001);\n    std.debug.print(\"Max n2: {d}\\n\", .{n2});\n}\n```\n:::\n\n\n\n```\nMax n1: 10\nMax n2: 89.24\n```\n\n\n### A generic data structure {#sec-generic-struct}\n\nEvery data structure that you find in the Zig Standard Library (e.g. `ArrayList`, `HashMap`, etc.)\nis essentially a generic data structure.\nThese data structures are generic in the sense that they work with any data type you want.\nYou just say which is the data type of the values that are going to be stored in this data\nstructure, and they just work as expected.\n\nA generic data structure in Zig is how you replicate a generic class from Java,\nor, a class template from C++. But you may ask yourself: how do we build a\ngeneric data structure in Zig?\n\nThe basic idea is to write a generic function that creates the data structure definition\nfor the specific type we want. In other words, this generic function behaves as a \"factory of data structures\".\nThe generic function outputs the `struct` definition that defines this data structure for a\nspecific data type.\n\nTo create such function, we need to add a comptime argument to this function that receives a data type\nas input. We already learned how to do this in the previous section (@sec-generic-fun).\nI think the best way to demonstrate how to create a generic data structure is to actually write one.\nThis where we go into our next small project in this book. This one is a very small project,\nwhich is to write a generic stack data structure.\n\n\n\n\n## What is a stack? {#sec-what-stack}\n\nA stack data structure is a structure that follows a LIFO (*last in, first out*) principle.\nOnly two operations are normally supported in a stack data structure, which are `push` and `pop`.\nThe `push` operation is used to add new values to the stack, while `pop` is used to remove\nvalues from the stack.\n\nWhen people try to explain how the stack data structure works, the most common analogy\nthat they use is a stack of plates. Imagine that you have a stack of plates,\nfor example, a stack of 10 plates in your table. Each plate represents a value that\nis currently stored in this stack.\n\nWe begin with a stack of 10 different values, or 10 different plates. Now, imagine that you want to\nadd a new plate (or a new value) to this stack, which translates to the `push` operation.\nYou would add this plate (or this value) by just putting the new plate\non the top of the stack. Then, you would increase the stack to 11 plates.\n\nBut how would you remove plates (or remove values) from this stack (a.k.a. the `pop` operation) ?\nTo do that, we would have to remove the plate on the top of the stack, and, as a result, we would\nhave, once again, 10 plates in the stack.\n\nThis demonstrates the LIFO concept, because the first plate in the stack, which is the plate\nin the bottom of the stack, is always the last plate to get out of the stack. Think about it. In order\nto remove this specific plate from the stack, we have to remove all plates in the\nstack. So every operation in the stack, either insertion or deletion, is always made at the top of the stack.\nThe @fig-stack below exposes this logic visually:\n\n![A diagram of a stack structure. Source: Wikipedia, the free encyclopedia.](./../Figures/lifo-stack.svg){#fig-stack}\n\n\n\n## Writing the stack data structure\n\nWe are going to write the stack data structure in two steps. First, we are going\nto implement a stack that can only store `u32` values. Then, after that, we are going\nto extend our implementation to make it generic, so that it works with any data type\nwe want.\n\nFirst, we need to decide how the values will be stored inside the stack. There are multiple\nways to implement the storage behind a stack structure. Some people prefer to use a doubly linked list,\nothers prefer to use a dynamic array, etc. In this example we are going to use an array behind the hood,\nto store the values in the stack, which is the `items` data member of our `Stack` struct definition.\n\nAlso notice in our `Stack` struct that we have three other data members: `capacity`, `length` and `allocator`.\nThe `capacity` member contains the capacity of the underlying array that stores the values in the stack.\nThe `length` contains the number of values that are currently being stored in the stack.\nAnd the `allocator` contains the allocator object that will be used by the stack structure whenever it\nneeds to allocate more space for the values that are being stored.\n\nWe begin by defining an `init()` method of this struct, which is going to be\nresponsible for instantiating a `Stack` object. Notice that, inside this\n`init()` method, we start by allocating an array with the capacity specified\nin the `capacity` argument.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst Stack = struct {\n    items: []u32,\n    capacity: usize,\n    length: usize,\n    allocator: Allocator,\n\n    pub fn init(allocator: Allocator, capacity: usize) !Stack {\n        var buf = try allocator.alloc(u32, capacity);\n        return .{\n            .items = buf[0..],\n            .capacity = capacity,\n            .length = 0,\n            .allocator = allocator,\n        };\n    }\n};\n```\n:::\n\n\n\n\n### Implementing the `push` operation\n\nNow that we have written the basic logic to create a new `Stack` object,\nwe can start writing the logic responsible for performing a push operation.\nRemember, a push operation in a stack data structure is the operation\nresponsible for adding a new value to the stack.\n\nSo how can we add a new value to the `Stack` object that we have?\nThe `push()` function exposed below is a possible answer to this question.\nRemember from what we discussed in @sec-what-stack that values are always added to the top of the stack.\nThis means that this `push()` function must always find the element in the underlying array\nthat currently represents the top position of the stack, and then, add the input value there.\n\nFirst, we have an if statement in this function. This if statement is\nchecking whether we need to expand the underlying array to store\nthis new value that we are adding to the stack. In other words, maybe\nthe underlying array does not have enough capacity to store this new\nvalue, and, in this case, we need to expand our array to get the capacity that we need.\n\nSo, if the logical test in this if statement returns true, it means that the array\ndoes not have enough capacity, and we need to expand it before we store this new value.\nSo inside this if statement we are executing the necessary expressions to expand the underlying array.\nNotice that we use the allocator object to allocate a new array that is twice as bigger\nthan the current array (`self.capacity * 2`).\n\nAfter that, we use a different built-in function named `@memcpy()`. This built-in function\nis equivalent to the `memcpy()` function from the C Standard Library[^cmemcpy]. It's used to\ncopy the values from one block of memory to another block of memory. In other words,\nyou can use this function to copy the values from one array into another array.\n\n[^cmemcpy]: <https://www.tutorialspoint.com/c_standard_library/c_function_memcpy.htm>\n\nWe are using this `@memcpy()` built-in function to copy the values that are currently stored\nin the underlying array of the stack object (`self.items`) into our new and bigger array that\nwe have allocated (`new_buf`). After we execute this function, the `new_buf` contains a copy\nof the values that are present at `self.items`.\n\nNow that we have secured a copy of our current values in the `new_buf` object, we\ncan now free the memory currently allocated at `self.items`. After that, we just need\nto assign our new and bigger array to `self.items`. This is the sequence\nof steps necessary to expand our array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn push(self: *Stack, val: u32) !void {\n    if ((self.length + 1) > self.capacity) {\n        var new_buf = try self.allocator.alloc(\n            u32, self.capacity * 2\n        );\n        @memcpy(\n            new_buf[0..self.capacity], self.items\n        );\n        self.allocator.free(self.items);\n        self.items = new_buf;\n        self.capacity = self.capacity * 2;\n    }\n\n    self.items[self.length] = val;\n    self.length += 1;\n}\n```\n:::\n\n\n\nAfter we make sure that we have enough room to store this new value\nthat we are adding to the stack, all we have to do is to assign\nthis value to the top element in this stack, and, increase the\nvalue of the `length` attribute by one. We find the top element\nin the stack by using the `length` attribute.\n\n\n\n### Implementing the `pop` operation\n\nNow we can implement the pop operation of our stack object.\nThis is a much easier operation to implement, and the `pop()` method below summarises\nall the logic that is needed.\n\nWe just have to find the element in the underlying array that currently represents the top\nof the stack, and set this element to \"undefined\", to indicate that\nthis element is \"empty\". After that, we also need to decrease\nthe `length` attribute of the stack by one.\n\nIf the current length of the stack is zero, it means that there is\nno values being stored in the stack currently. So, in this case,\nwe could just return from the function and do nothing really.\nThis is what the if statement inside this function is checking for.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn pop(self: *Stack) void {\n    if (self.length == 0) return;\n\n    self.items[self.length - 1] = undefined;\n    self.length -= 1;\n}\n```\n:::\n\n\n\n\n\n### Implementing the `deinit` method\n\nWe have implemented the methods responsible for the two main operations\nassociated with the stack data structure, which is `pop()` and `push()`,\nand we also have implemented the method responsible for instantiating\na new `Stack` object, which is the `init()` method.\n\nBut now, we need to implement also the method responsible for destroying\na `Stack` object. In Zig, this task is commonly associated with the method\nnamed `deinit()`. Most struct objects in Zig have such method, and it\nis commonly nicknamed \"the destructor method\".\n\nIn theory, all we have to do to destroy the `Stack` object is to make\nsure that we free the allocated memory for the underlying array, using\nthe allocator object that is stored inside the `Stack` object.\nThis is what the `deinit()` method below is doing.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn deinit(self: *Stack) void {\n    self.allocator.free(self.items);\n}\n```\n:::\n\n\n\n\n\n\n## Making it generic\n\nNow that we have implemented the basic skeleton of our stack data structure,\nwe can now focus on discussing how we can make it generic. How can we make\nthis basic skeleton to work not only with `u32` values, but also with any other\ndata type we want?\nFor example, we might need to create a stack object to store `User` values\nin it. How can we make this possible? The answer lies in the use of generics\nand `comptime`.\n\nAs I described in @sec-generic-struct, the basic idea is to write a generic\nfunction that returns a struct definition as output.\nIn theory, we do not need much to transform our `Stack` struct into a generic\ndata structure. All that we need to do is to transform the underlying array\nof the stack into a generic array.\n\nIn other words, this underlying array needs to be a \"chameleon\". It needs to adapt,\nand transform it into an array of any data type that we want. For example, if we need to create\na stack that will store `u8` values, then this underlying array needs to be\na `u8` array (i.e., `[]u8`). But if we need to store `User` values instead, then,\nthis array needs to be a `User` array (i.e., `[]User`). Etc.\n\nWe do that by using a generic function. Because a generic function can receive a data type\nas input, and we can pass this data type to the struct definition of our `Stack` object.\nTherefore, we can use the generic function to create a `Stack` object that can store\nthe data type we want. If we want to create a stack structure that stores `User` values,\nwe pass the `User` data type to this generic function, and it will create for us\nthe struct definition that describes a `Stack` object that can store `User` values in it.\n\nLook at the code example below. I have omitted some parts of the `Stack` struct definition\nfor brevity. However, if a specific part of our `Stack` struct is not exposed here\nin this example, then it's because this part did not change from the previous example.\nIt remains the same.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn Stack(comptime T: type) type {\n    return struct {\n        items: []T,\n        capacity: usize,\n        length: usize,\n        allocator: Allocator,\n        const Self = @This();\n\n        pub fn init(allocator: Allocator,\n                    capacity: usize) !Stack(T) {\n            var buf = try allocator.alloc(T, capacity);\n            return .{\n                .items = buf[0..],\n                .capacity = capacity,\n                .length = 0,\n                .allocator = allocator,\n            };\n        }\n\n        pub fn push(self: *Self, val: T) !void {\n        // Truncate the rest of the struct\n    };\n}\n```\n:::\n\n\n\nNotice that we have created a function in this example named `Stack()`. This function\ntakes a type as input, and passes this type to the struct definition of our\n`Stack` object. The data member `items` is now, an array of type `T`, which is the\ndata type that we have provided as input to the function. The function argument\n`val` in the `push()` function is now a value of type `T` too.\n\nWe can just provide a data type to this function, and it will create a definition of a\n`Stack` object that can store values of the data type that we have provided. In the example below, we are creating\nthe definition of a\n`Stack` object that can store `u8` values in it. This definition is stored at the `Stacku8` object.\nThis `Stacku8` object becomes our new struct, that we are going to use\nto create our `Stack` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst Stacku8 = Stack(u8);\nvar stack = try Stacku8.init(allocator, 10);\ndefer stack.deinit();\ntry stack.push(1);\ntry stack.push(2);\ntry stack.push(3);\ntry stack.push(4);\ntry stack.push(5);\ntry stack.push(6);\n\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\"Stack capacity: {d}\\n\", .{stack.capacity});\n\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\n    \"Stack state: {any}\\n\",\n    .{stack.items[0..stack.length]}\n);\n```\n:::\n\n\n\n```\nStack len: 6\nStack capacity: 10\nStack len: 5\nStack len: 4\nStack state: { 1, 2, 3, 4, 0, 0, 0, 0, 0, 0 }\n```\n\nEvery generic data structure in the Zig Standard Library (`ArrayList`, `HashMap`, `SinlyLinkedList`, etc.)\nis implemented through this logic. They use a generic function to create the struct definition that can work\nwith the data type that you provided as input.\n\n\n\n\n## Conclusion\n\nThe full source code of the stack structure discussed in this chapter is freely available in the official\nrepository of this book. Just checkout the [`stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig)[^zig-stack]\nfor the `u32` version of our stack,\nand the [`generic_stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig)[^zig-stack2]\nfor the generic version, available inside the `ZigExamples` folder of the repository.\n\n\n[^zig-stack]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig>\n[^zig-stack2]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig>\n",
+    "supporting": [
+      "10-stack-project_files"
+    ],
+    "filters": [
+      "rmarkdown/pagebreak.lua"
+    ],
+    "includes": {},
+    "engineDependencies": {
+      "knitr": [
+        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
+      ]
+    },
+    "preserve": null,
+    "postProcess": false
+  }
+}
\ No newline at end of file
diff --git a/_freeze/Chapters/12-file-op/execute-results/epub.json b/_freeze/Chapters/12-file-op/execute-results/epub.json
new file mode 100644
index 00000000..acf050fc
--- /dev/null
+++ b/_freeze/Chapters/12-file-op/execute-results/epub.json
@@ -0,0 +1,21 @@
+{
+  "hash": "1e79228e1613c85b9e688833811e2fda",
+  "result": {
+    "engine": "knitr",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Filesystem and Input/Output (IO) {#sec-filesystem}\n\nIn this chapter we are going to discuss how to use the cross-platform structs and functions\nfrom the Zig Standard Library that can execute filesystem operations. Most of these functions and structs\ncomes from the `std.fs` module.\n\nWe are also going to talk about Input/Output (also known as IO) operations in Zig. Most of\nthese operations are made by using the structs and functions from `std.io` module, which defines\nfile descriptors for the *standard channels* of your system (`stdout` and `stdin`), and also,\nfunctions to create and use I/O streams.\n\n\n## Input/Output basics {#sec-io-basics}\n\nIf you have some experience in a high-level language, you have certainly used\nthese input and output functionalities before in this language. In other words, you certainly have\nbeen in a situation where you needed to sent some output to the user, or, to receive an input\nfrom the user.\n\nFor example, in Python we can receive some input from the user by using the `input()` built-in\nfunction. But we can also print (or \"show\") some output to the user by using the `print()`\nbuilt-in function. So yes, if you have programmed before in Python, you certainly have\nused these functions once before.\n\nBut do you know how these functions relate back to your operating system (OS)? How exactly\nthey are interacting with the resources of your OS to receive or sent some input/output.\nIn essence, these input/output functions from high-level languages are just abstractions\nover the *standard output* and *standard input* channels of your operating system.\n\nThis means that we receive an input, or send some output, through the operating system.\nIt's the OS that makes the bridge between the user and your program. Your program\ndoes not have a direct access to the user. It's the OS that intermediates every\nmessage exchanged between your program and the user.\n\nThe *standard output* and *standard input* channels of your OS are commonly known as the\n`stdout` and `stdin` channels of your OS, respectively. In some contexts, they are also\ncalled the *standard output device* and the *standard input device*. As the name suggests,\nthe *standard output* is the channel through which output flows, while the *standard input*\nis the channel in which input flows.\n\nFurthermore, OS's also normally create a dedicated channel for exchanging error messages, which is known as the\n*standard error* channel, or, the `stderr` channel. This is the channel to which error and warning messages\nare usually sent to. These are the messages that are normally displayed in red-like or orange-like colors\ninto your terminal.\n\nNormally, every OS (e.g. Windows, macOS, Linux, etc.) creates a dedicated and separate set of\n*standard output*, *standard error* and *standard input* channels for every single program (or process) that runs in your computer.\nThis means that every program you write have a dedicated `stdin`, `stderr` and `stdout` that are separate\nfrom the `stdin`, `stderr` and `stdout` of other programs and processes that are currently running.\n\nThis is a behaviour from your OS. This does not come from the programming language that you are using.\nBecause as I sad earlier, input and output in programming languages, especially\nin high-level ones, are just a simple abstraction over the `stdin`, `stderr` and `stdout` from your current OS.\nThat is, your OS is the intermediary between every input/output operation made in your program,\nregardless of the programming language that you are using.\n\n\n### The writer and reader pattern {#sec-writer-reader}\n\nIn Zig, there is a pattern around input/output (IO). I (the author of this book) don't know if there\nis an official name for this pattern. But here, in this book, I will call it the \"writer and reader pattern\".\nIn essence, every IO operation in Zig is made through either a `GenericReader` or a `GenericWriter` object[^gen-zig].\n\nThese two data types come from the `std.io` module of the Zig Standard Library. As their names suggests, a\n`GenericReader` is an object that offers tools to read data from \"something\" (or \"somewhere\"), while a `GenericWriter`\noffers tools to write data into this \"something\". This \"something\" might be different things: like a\nfile that exists in your filesystem; or, it might be a network socket in your system[^sock]; or,\na continuous stream of data, like a standard input device from your system, that might be constantly\nreceiving new data from users, or, as another example, a live chat in a game that is constantly\nreceiving and displaying new messages from the players of the game.\n\n[^gen-zig]: Previously, these objects were known as the `Reader` and `Writer` objects.\n[^sock]: The socket objects that we have created in @sec-create-socket, are examples of network sockets.\n\nSo, if you want to **read** data from something, or somewhere, it means that you need to use a `GenericReader` object.\nBut if you need instead, to **write** data into this \"something\", then, you need to use a `GenericWriter` object instead.\nBoth of these objects are normally created from a file descriptor object. More specifically, through the `writer()` and `reader()`\nmethods of this file descriptor object. If you are not familiar with this type of object, go to the next section.\n\nEvery `GenericWriter` object have methods like `print()`, which allows you to write/send a formatted string\n(i.e., this formatted string is like a `f` string in Python, or, similar to the `printf()` C function)\ninto the \"something\" (file, socket, stream, etc.) that you are using. It also have a `writeAll()` method, which allows you to\nwrite a string, or, an array of bytes into the \"something\".\n\nLikewise, every `GenericReader` object have methods like `readAll()`, which allows you to read the\ndata from the \"something\" (file, socket, stream, etc.) until it fills a particular array (i.e., a \"buffer\") object.\nIn other words, if you provide an array object of 300 `u8` values to `readAll()`, then, this method attempts to read 300 bytes\nof data from the \"something\", and it stores them into the array object that you have provided.\n\nWe also have other methods, like the `readAtLeast()` method, which allows you to specify how\nmany bytes exactly you want to read from the \"something\". In more details, if you give the\nnumber $n$ as input to this method, then, it will attempt to read at least $n$ bytes of data\nfrom the \"something\". The \"something\" might have less than $n$ bytes of data available for you\nto read, so, it's not guaranteed that you will get precisely $n$ bytes as result.\n\nAnother useful method is `readUntilDelimiterOrEof()`. In this method, you specify a \"delimiter character\".\nThe idea is that this function will attempt to read as many bytes of data as possible from the \"something\",\nuntil it encounters the end of the stream, or, it encounters the \"delimiter character\" that you have specified.\n\nIf you don't know exactly how many bytes will come from the \"something\", you may find the `readAllAlloc()` method\nuseful. In essence, you provide an allocator object to this method, so that it can allocate more space if needed.\nAs consequence, this method will try to read all bytes of the \"something\", and, if it runs out of space at some point\nduring the \"reading process\", it uses the allocator object to allocate more space to continue reading the bytes.\nAs result, this method returns a slice to the array object containing all the bytes read.\n\nThis is just a quick description of the methods present in these types of objects. But I recommend you\nto read the official docs, both for\n[`GenericWriter`](https://ziglang.org/documentation/master/std/#std.io.GenericWriter)[^gen-write] and\n[`GenericReader`](https://ziglang.org/documentation/master/std/#std.io.GenericReader)[^gen-read].\nI also think it's a good idea to read the source code of the modules in the Zig Standard Library\nthat defines the methods present in these objects, which are the\n[`Reader.zig`](https://github.com/ziglang/zig/blob/master/lib/std/io/Reader.zig)[^mod-read]\nand [`Writer.zig`]()[^mod-write].\n\n[^gen-read]: <https://ziglang.org/documentation/master/std/#std.io.GenericReader>.\n[^gen-write]: <https://ziglang.org/documentation/master/std/#std.io.GenericWriter>.\n[^mod-read]: <https://github.com/ziglang/zig/blob/master/lib/std/io/Reader.zig>.\n[^mod-write]: <https://github.com/ziglang/zig/blob/master/lib/std/io/Writer.zig>.\n\n\n\n### Introducing file descriptors {#sec-file-descriptor}\n\nA \"file descriptor\" object is a core component behind every IO operation that is made in any operating system (OS).\nSuch object is an identifier for a particular input/output (IO) resource from your OS [@wiki_file_descriptor].\nIt describes and identifies this particular resource. An IO resource might be:\n\n- an existing file in your filesystem.\n- an existing network socket.\n- other types of stream channels.\n- a pipeline (or just \"pipe\") in your terminal[^pipes].\n\n[^pipes]: A pipeline is a mechanism for inter-process communication, or, inter-process IO. You could also interpret a pipeline as a \"set of processes that are chained together, through the standard input/output devices of the system\". At Linux for example, a pipeline is created inside a terminal, by connecting two or more terminal commands with the \"pipe\" character (`|`).\n\nFrom the bullet points listed above, we know that although the term \"file\" is present,\na \"file descriptor\" might describe something more than just a file.\nThis concept of a \"file descriptor\" comes from the Portable Operating System Interface (POSIX) API,\nwhich is a set of standards that guide how operating systems across the world should be implemented,\nto maintain compatibility between them.\n\nA file descriptor not only identifies the input/output resource that you are using to receive or send some data,\nbut it also describes where this resource is, and also, which IO mode this resource is currently using.\nFor example, this IO resource might be using only the \"read\" IO mode, which means that this resource\nis open to \"read operations\", while \"write operations\" are not authorized.\nThese IO modes are essentially the modes that you provide to the argument `mode`\nfrom the `fopen()` C function, and also, from the `open()` Python built-in function.\n\nIn C, a \"file descriptor\" is a `FILE` pointer, but, in Zig, a file descriptor is a `File` object.\nThis data type (`File`) is described in the `std.fs` module of the Zig Standard Library.\nWe normally don't create a `File` object directly in our Zig code. Instead, we normally get such object as result when we\nopen an IO resource. In other words, we normally ask our OS to open a particular IO resource for us,\nand, if the OS do open successfully this IO resource, the OS normally handles back to us\na file descriptor to this particular IO resource.\n\nSo you usually get a `File` object by using functions and methods from the Zig Standard Library\nthat asks the OS to open some IO resource, like the `openFile()` method that opens a file in the\nfilesystem. The `net.Stream` object that we have created in @sec-create-socket is also a type of\nfile descriptor object.\n\n\n### The *standard output*\n\nYou already saw across this book, how can we access and use specifically the `stdout` in Zig\nto send some output to the user.\nFor that, we use the `getStdOut()` function from the `std.io` module. This function returns\na file descriptor that describes the `stdout` channel of your current OS. Through this file\ndescriptor object, we can read from or write stuff to the `stdout` of our program.\n\nAlthough we can read stuff recorded into the `stdout` channel, we normally only\nwrite to (or \"print\") stuff into this channel. The reason is very similar to what we discussed at\n@sec-read-http-message, when we were discussing what \"reading from\" versus \"writing to\" the connection\nobject from our small HTTP Server project would mean.\n\nWhen we write stuff into a channel, we are essentially sending data to the other end of this channel.\nIn contrast, when we read stuff from this channel, we are essentially reading the data that was sent\nthrough this channel. Since the `stdout` is a channel to send output to the user, the key verb here\nis **send**. We want to send something to someone, and, as consequence, we want to **write** something\ninto some channel.\n\nThat is why, when we use `getStdOut()`, most of the times, we also use the `writer()` method from the `stdout` file descriptor,\nto get access to a writer object that we can use to write stuff into this `stdout` channel.\nMore specifically, this `writer()` method returns a `GenericWriter` object. One of the\nmain methods of this `GenericWriter` object is the `print()` method that we have used\nbefore to write (or \"print\") a formatted string into the `stdout` channel.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    try stdout.writeAll(\n        \"This message was written into stdout.\\n\"\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nThis message was written into stdout.\n```\n\n\n:::\n:::\n\n\n\n\n\nThis `GenericWriter` object is like any other generic writer object that you would normally get from a file descriptor object.\nSo, the same methods from a generic writer object that you would use while writing files to the filesystem for example, you could also\nuse them here, from the file descriptor object of `stdout`, and vice-versa.\n\n\n### The *standard input*\n\nYou can access the *standard input* (i.e., `stdin`) in Zig by using the `getStdIn()` function from the `std.io` module.\nLike its brother (`getStdOut()`), this function also returns a file descriptor object that describes the `stdin` channel\nof your OS.\n\nBecause we want to receive some input from the user, the key verb here becomes **receive**, and, as consequence,\nwe usually want to **read** data from the `stdin` channel, instead of writing data into it. So, we normally use\nthe `reader()` method of the file descriptor object returned by `getStdIn()`, to get access to a `GenericReader`\nobject that we can use to read data from `stdin`.\n\nIn the example below, we are creating a small buffer capable of holding 20 characters. Then, we try to read\nthe data from the `stdin` with the `readUntilDelimiterOrEof()` method, and save this data into the `buffer` object.\nAlso notice that we are reading the data from the `stdin` until we hit a new line character (`'\\n'`).\n\nIf you execute this program, you will notice that it stops the execution, ands start to wait indefinitely\nfor some input from the user. In other words, you need to type your name into the terminal, and then, you press Enter to\nsend your name to `stdin`. After you send your name to `stdin`, the program reads this input, and continues with the execution,\nby printing the given name to `stdout`. In the example below, I typed my name (Pedro) into the terminal, and then, pressed Enter.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst stdin = std.io.getStdIn().reader();\npub fn main() !void {\n    try stdout.writeAll(\"Type your name\\n\");\n    var buffer: [20]u8 = undefined;\n    @memset(buffer[0..], 0);\n    _ = try stdin.readUntilDelimiterOrEof(buffer[0..], '\\n');\n    try stdout.print(\"Your name is: {s}\\n\", .{buffer});\n}\n```\n:::\n\n\n\n```\nType your name\nYour name is: Pedro\n\n```\n\n\n### The *standard error*\n\nThe *standard error* (a.k.a. the `stderr`) works exactly the same as `stdout` and `stdin`.\nYou just call the `getStdErr()` function from the `std.io` module, and you get the file descriptor to `stderr`.\nIdeally, you should write only error or warning messages to `stderr`, because this is\nthe purpose of this channel.\n\n\n\n\n\n## Buffered IO\n\nAs we described in @sec-io-basics, input/output (IO) operations are made directly by the operating system.\nIt's the OS that manages the IO resource that you want to use for your IO operations.\nThe consequence of this fact is that IO operations are heavily based on system calls (i.e., calling the operating system directly).\n\nJust to be clear, there is nothing particularly wrong with system calls. We use them all the time on\nany serious codebase written in any low-level programming language. However, system calls are\nalways orders of magnitude slower than many different types of operations.\n\nSo is perfectly fine to use a system call once in a while. But when these system calls are used often,\nyou can clearly notice most of the time the loss of performance in your application. So, the good rule of thumb\nis to use a system call only when it's needed, and also, only in infrequent situations, to reduce\nthe number of system calls performed to a minimum.\n\n\n### Understanding how buffered IO works\n\nBuffered IO is a strategy to achieve better performance. It's used to reduce the number of system calls made by IO operations, and, as\nconsequence, achieve a much higher performance. In @fig-unbuffered-io and @fig-buffered-io you can find two different diagrams\nwhich presents the difference between read operations performed in an unbuffered IO environment versus a buffered IO environment.\n\nTo give a better context to these diagrams, let's suppose that we have a text file that contains the famous Lorem ipsum text[^lorem]\nin our filesystem. Let's also suppose that these diagrams in @fig-unbuffered-io and @fig-buffered-io\nare showing the read operations that we are performing to read the Lorem ipsum text from this text file.\nThe first thing you will notice when looking at these diagrams, is that in an unbuffered environment\nthe read operations leads to many system calls.\nMore precisely, in the diagram exposed in @fig-unbuffered-io we get one system call per each byte that we read from the text file.\nOn the other hand, in @fig-buffered-io we have only one system call at the very beginning.\n\nWhen we use a buffered IO system, at the first read operation we perform, instead of sending one single byte directly\nto our program, the OS first sends a chunk of bytes from the file to a buffer object (i.e., an array).\nThis chunk of bytes are cached/stored inside this buffer object.\n\nTherefore, from now on, for every new read operation that you perform, instead of making a new system call to ask\nfor the next byte in the file to the OS, this read operation is redirected to the buffer object, that have\nthis next byte already cached and ready to go.\n\n\n[^lorem]: <https://www.lipsum.com/>.\n\n\n![Unbuffered IO](./../Figures/unbuffered-io.png){#fig-unbuffered-io width=60%}\n\n![Buffered IO](./../Figures/buffered-io.png){#fig-buffered-io}\n\n\n\nThis is the basic logic behind buffered IO systems. The size of the buffer object depends on multiple factors. But it's usually\nequal to the size of a full page of memory (4096 bytes). If we follow this logic, then, the OS reads the first 4096 bytes\nof the file and caches it into the buffer object. As long as your program does not consume all of these 4096 bytes from the buffer,\nyou will not create new system calls.\n\nHowever, as soon as you consume all of these 4096 bytes from the buffer, it means that there is no bytes left in the buffer.\nIn this situation, a new system call is made to ask the OS to send the next 4096 bytes in the file, and once again,\nthese bytes are cached into the buffer object, and the cycle starts once again.\n\n\n### Buffered IO across different languages\n\nIO operations made through a `FILE` pointer in C are buffered\nby default, so, at least in C, you don't need to worry about this subject. But in contrast, IO operations in both Rust and Zig are not\nbuffered depending on which functions from the standard libraries that you are using.\n\nFor example, in Rust, buffered IO is implemented through the `BufReader` and `BufWriter` structs, while in Zig, it's implemented\nthrough the `BufferedReader` and `BufferedWriter` structs.\nSo any IO operation that you perform through the `GenericWriter` and `GenericReader` objects\nthat I presented in @sec-writer-reader are not buffered, which means that these objects\nmight create a lot of system calls depending on the situation.\n\n\n### Using buffered IO in Zig\n\nUsing buffered IO in Zig is actually very easy. All you have to do is to just\ngive the `GenericWriter` object to the `bufferedWriter()` function, or, to give the `GenericReader`\nobject to the `bufferedReader()` function. These functions come from the `std.io` module,\nand they will construct the `BufferedWriter` or `BufferedReader` object for you.\n\nAfter you create this new `BufferedWriter` or `BufferedReader` object, you can call the `writer()`\nor `reader()` method of this new object, to get access to a new (and buffered) generic reader or\ngeneric writer.\n\nLet's describe the process once again. Every time that you have a file descriptor object, you first get the generic writer or generic reader\nobject from it, by calling the `writer()` or `reader()` methods of this file descriptor object.\nThen, you provide this generic writer or generic reader to the `bufferedWriter()` or `bufferedReader()`\nfunction, which creates a new `BufferedWriter` or `BufferedReader` object. Then, you call\nthe `writer()` or `reader()` methods of this buffered writer or buffered reader object,\nwhich gives you access to a generic writer or a generic reader object that is buffered.\n\nTake this program as an example. This program is demonstrating the process exposed in @fig-buffered-io.\nWe are simply opening a text file that contains the Lorem ipsum text, and then, we create a buffered IO reader object\nat `bufreader`, and we use this `bufreader` object to read the contents of this file into a buffer object, then,\nwe end the program by printing this buffer to `stdout`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar file = try std.fs.cwd().openFile(\n    \"ZigExamples/file-io/lorem.txt\", .{}\n);\ndefer file.close();\nvar buffered = std.io.bufferedReader(file.reader());\nvar bufreader = buffered.reader();\n\nvar buffer: [1000]u8 = undefined;\n@memset(buffer[0..], 0);\n\n_ = try bufreader.readUntilDelimiterOrEof(\n    buffer[0..], '\\n'\n);\ntry stdout.print(\"{s}\\n\", .{buffer});\n```\n:::\n\n\n\n```\nLorem ipsum dolor sit amet, consectetur\nadipiscing elit. Sed tincidunt erat sed nulla ornare, nec\naliquet ex laoreet. Ut nec rhoncus nunc. Integer magna metus,\nultrices eleifend porttitor ut, finibus ut tortor. Maecenas\nsapien justo, finibus tincidunt dictum ac, semper et lectus.\nVivamus molestie egestas orci ac viverra. Pellentesque nec\narcu facilisis, euismod eros eu, sodales nisl. Ut egestas\nsagittis arcu, in accumsan sapien rhoncus sit amet. Aenean\nneque lectus, imperdiet ac lobortis a, ullamcorper sed massa.\nNullam porttitor porttitor erat nec dapibus. Ut vel dui nec\nnulla vulputate molestie eget non nunc. Ut commodo luctus ipsum,\nin finibus libero feugiat eget. Etiam vel ante at urna tincidunt\nposuere sit amet ut felis. Maecenas finibus suscipit tristique.\nDonec viverra non sapien id suscipit.\n```\n\nDespite being a buffered IO reader, this `bufreader` object is similar to any other `GenericReader` object,\nand have the exact same methods. So, although these two types of objects perform very different IO operations,\nthey have the same interface, so you, the programmer, can interchangeably use them\nwithout the need to change anything in your source code.\nSo a buffered IO reader or a buffered IO writer objects have the same methods than its generic and unbuffered brothers,\ni.e., the generic reader and generic writer objects that I presented in @sec-writer-reader.\n\n::: {.callout-tip}\nIn general, you should always use a buffered IO reader or a buffered IO writer object to perform\nIO operations in Zig. Because they deliver better performance to your IO operations.\n:::\n\n\n## Filesystem basics\n\nNow that we have discussed the basics around Input/Output operations in Zig, we need to\ntalk about the basics around filesystems, which is another core part of any operating system.\nAlso, filesystems are related to input/output, because the files that we store and create in our\ncomputer are considered an IO resource, as we described in @sec-file-descriptor.\n\n\n### The concept of current working directory (CWD)\n\nThe working directory is the folder on your computer where you are currently rooted at.\nIn other words, it's the folder that your program is currently looking at.\nTherefore, whenever you are executing a program, this program is always working with\na specific folder on your computer. It's always in this folder that the program will initially\nlook for the files you require, and it's also in this folder that the program\nwill initially save all the files you ask it to save.\n\nThe working directory is determined by the folder from which you invoke your program\nin the terminal. In other words, if you are in the terminal of your OS, and you\nexecute a binary file (i.e., a program) from this terminal, the folder to which your terminal\nis pointing at is the current working directory of your program that is being executed.\n\nIn @fig-cwd we have an example of me executing a program from the terminal. We are executing\nthe program outputted by the `zig` compiler by compiling the Zig module named `hello.zig`.\nThe CWD in this case is the `zig-book` folder. In other words, while the `hello.zig` program\nis executing, it will be looking at the `zig-book` folder, and any file operation that we perform\ninside this program, will be using this `zig-book` folder as the \"starting point\", or, as the \"central focus\".\n\n![Executing a program from the terminal](./../Figures/cwd.png){#fig-cwd}\n\nJust because we are rooted inside a particular folder (in the case of @fig-cwd, the `zig-book` folder) of our computer,\nit doesn't mean that we cannot access or write resources in other locations of our computer.\nThe current working directory (CWD) mechanism just defines where your program will look first\nfor the files you ask for. This does not prevent you from accessing files that are located\nelsewhere on your computer. However, to access any file that is in a folder other than your\ncurrent working directory, you must provide a path to that file or folder.\n\n\n### The concept of paths\n\nA path is essentially a location. It points to a location in your filesystem. We use\npaths to describe the location of files and folders in our computer.\nOne important aspect about paths is that they are always written inside strings,\ni.e., they are always provided as text values.\n\nThere are two types of paths that you can provide to any program in any OS: a relative path, or an absolute path.\nAbsolute paths are paths that start at the root of your filesystem, and go all the way to the file name or the specific folder\nthat you are referring to. This type of path is called absolute, because it points to an unique and absolute location on your computer.\nThat is, there is no other existing location on your computer that corresponds to this path. It's an unique identifier.\n\nIn Windows, an absolute path is a path that starts with a hard disk identifier (e.g. `C:/Users/pedro`).\nOn the other hand, absolute paths in Linux and macOS, are paths that start with a forward slash character (e.g. `/usr/local/bin`).\nNotice that a path is composed by \"segments\". Each segment is connected to each other by a slash character (`\\` or `/`).\nOn Windows, the backward slash (`\\`) is normally used to connect the path segments. While on Linux and macOS, the forward\nslash (`/`) is the character used to connect path segments.\n\nA relative path is a path that start at the CWD. In other words, a relative path is\n\"relative to the CWD\". The path used to access the `hello.zig` file in @fig-cwd is an example of a relative path. This path\nis reproduced below. This path begins at the CWD, which in the context of @fig-cwd, is the `zig-book` folder,\nthen, it goes to the `ZigExamples` folder, then, into `zig-basics`, then, to the `hello.zig` file.\n\n```\nZigExamples/zig-basics/hello_world.zig\n```\n\n\n### Path wildcards\n\nWhen providing paths, especially relative paths, you have the option of using a *wildcard*.\nThere are two commonly used *wildcards* in paths, which are \"one period\" (.) and \"two periods\" (..).\nIn other words, these two specific characters have special meanings when used in paths,\nand can be used on any operating system (Mac, Windows, Linux, etc.). That is, they\nare \"cross platform\".\n\nThe \"one period\" represents an alias for the current directory.\nThis means that the relative paths `\"./Course/Data/covid.csv\"` and `\"Course/Data/covid.csv\"` are equivalent.\nOn the other hand, the \"two periods\" refers to the previous directory.\nFor example, the path `\"Course/..\"` is equivalent to the path `\".\"`, that is, the current working directory.\n\nTherefore, the path `\"Course/..\"` refers to the folder before the `Course` folder.\nAs another example, the path `\"src/writexml/../xml.cpp\"` refers to the file `xml.cpp`\nthat is inside the folder before the `writexml` folder, which in this example is the `src` folder.\nTherefore, this path is equivalent to `\"src/xml.cpp\"`.\n\n\n\n\n## The CWD handler\n\nIn Zig, filesystem operations are usually made through a directory handler object.\nA directory handler in Zig is an object of type `Dir`, which is an object that describes\na particular folder in the filesystem of our computer.\nYou normally create a `Dir` object, by calling the `std.fs.cwd()` function.\nThis function returns a `Dir` object that points to (or, that describes) the\ncurrent working directory (CWD).\n\nThrough this `Dir` object, you can create new files, or modify, or read existing ones that are\ninside your CWD. In other words, a `Dir` object is the main entrypoint in Zig to perform\nmultiple types of filesystem operations.\nIn the example below, we are creating this `Dir` object, and storing it\ninside the `cwd` object. Although we are not using this object at this code example,\nwe are going to use it a lot over the next examples.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\n_ = cwd;\n```\n:::\n\n\n\n\n\n\n\n\n\n\n## File operations\n\n### Creating files {#sec-creating-files}\n\nWe create new files by using the `createFile()` method from the `Dir` object.\nJust provide the name of the file that you want to create, and this function will\ndo the necessary steps to create such file. You can also provide a relative path to this function,\nand it will create the file by following this path, which is relative to the CWD.\n\nThis function might return an error, so, you should use `try`, `catch`, or any of the other methods presented\nin @sec-error-handling to handle the possible error. But if everything goes well,\nthis `createFile()` method returns a file descriptor object (i.e., a `File` object) as result,\nthrough which you can add content to the file with the IO operations that I presented before.\n\nTake this code example below. In this example, we are creating a new text file\nnamed `foo.txt`. If the function `createFile()` succeeds, the object named `file` will contain a file descriptor\nobject, which we can use to write (or add) new content to the file, like we do in this example, by using\na buffered writer object to write a new line of text to the file.\n\nNow, a quick note, when we create a file descriptor object in C, by using a C function like `fopen()`, we must always close the file\nat the end of our program, or, as soon as we complete all operations that we wanted to perform\non the file. In Zig, this is no different. So everytime we create a new file, this file remains\n\"open\", waiting for some operation to be performed. As soon as we are done with it, we always have\nto close this file, to free the resources associated with it.\nIn Zig, we do this by calling the method `close()` from the file descriptor object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.createFile(\"foo.txt\", .{});\n// Don't forget to close the file at the end.\ndefer file.close();\n// Do things with the file ...\nvar fw = file.writer();\n_ = try fw.writeAll(\n    \"Writing this line to the file\\n\"\n);\n```\n:::\n\n\n\n\nSo, in this example we not only have created a file into the filesystem,\nbut we also wrote some data into this file, using the file descriptor object\nreturned by `createFile()`. If the file that you are trying to create\nalready exists in your filesystem, this `createFile()` call will\noverwrite the contents of the file, or, in other words, it will\nin erase all the contents of the existing file.\n\nIf you don't want this to happen, meaning, that you don't want to overwrite\nthe contents of the existing file, but you want to write data to this file anyway\n(i.e., you want to append data to the file), you should use the `openFile()`\nmethod from the `Dir` object.\n\nAnother important aspect about `createFile()` is that this method creates a file\nthat is not open to read operations by default. It means that you cannot read this file.\nYou are not allowed to.\nSo for example, you might want to write some stuff into this file at the beginning of the execution\nof your program. Then, at a future point in your program you might need to read what you\nwrote in this file. If you try to read data from this file, you will likely\nget a `NotOpenForReading` error as result.\n\n\nBut how can you overcome this barrier? How can you create a file that is open\nto read operations? All you have to do, is to set the `read` flag to true\nin the second argument of `createFile()`. When you set this flag to true,\nthen the file gets create with \"read permissions\", and, as consequence,\na program like this one below becomes valid:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.createFile(\n    \"foo.txt\",\n    .{ .read = true }\n);\ndefer file.close();\n\nvar fw = file.writer();\n_ = try fw.writeAll(\"We are going to read this line\\n\");\n\nvar buffer: [300]u8 = undefined;\n@memset(buffer[0..], 0);\ntry file.seekTo(0);\nvar fr = file.reader();\n_ = try fr.readAll(buffer[0..]);\ntry stdout.print(\"{s}\\n\", .{buffer});\n```\n:::\n\n\n\n\n```\nWe are going to read this line\n```\n\n\nIf you are not familiar with position indicators, you might not recognize the method\n`seekTo()`. If that is your case, do not worry,\nwe are going to talk more about this method in @sec-indicators. But essentially\nthis method is moving the position indicator back to the beginning of the file,\nso that we can read the contents of the file from the beginning.\n\n\n### Opening files and appending data to it\n\nOpening files is easy. Just use the `openFile()` method instead of `createFile()`.\nIn the first argument of `openFile()` you provide the path to the file that\nyou want to open. Then, on the second argument you provide the flags (or, the options)\nthat dictates how the file is opened.\n\nYou can see the full list of options for `openFile()` by visiting the documentation for\n[`OpenFlags`](https://ziglang.org/documentation/master/std/#std.fs.File.OpenFlags)[^oflags].\nBut the main flag that you will most certainly use is the `mode` flag.\nThis flag specifies the IO mode that the file will be using when it gets opened.\nThere are three IO modes, or, three values that you can provide to this flag, which are:\n\n- `read_only`, allows only read operations on the file. All write operations are blocked.\n- `write_only`, allows only write operations on the file. All read operations are blocked.\n- `read_write`, allows both write and read operations on the file.\n\n[^oflags]: <https://ziglang.org/documentation/master/std/#std.fs.File.OpenFlags>\n\nThese modes are similar to the modes that you provide to the `mode` argument of the\n`open()` Python built-in function[^py-open], or, the `mode` argument of the\n`fopen()` C function[^c-open].\nIn the code example below, we are opening the `foo.txt` text file with a `write_only` mode,\nand appending a new line of text to the end of the file. We use `seekFromEnd()` this time\nto guarantee that we are going to append the text to the end of the file. Once again, methods\nsuch as `seekFromEnd()` are described in more depth in @sec-indicators.\n\n[^py-open]: <https://docs.python.org/3/tutorial/inputoutput.html#reading-and-writing-files>\n[^c-open]: <https://www.tutorialspoint.com/c_standard_library/c_function_fopen.htm>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.openFile(\n    \"foo.txt\", .{ .mode = .write_only }\n);\ndefer file.close();\ntry file.seekFromEnd(0);\nvar fw = file.writer();\n_ = try fw.writeAll(\"Some random text to write\\n\");\n```\n:::\n\n\n\n\n### Deleting files\n\nSometimes, we just need to delete/remove the files that we have.\nTo do that, we use the `deleteFile()` method. You just provide the path of the\nfile that you want to delete, and this method will try to delete the file located\nat this path.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.deleteFile(\"foo.txt\");\n```\n:::\n\n\n\n### Copying files\n\nTo copy existing files, we use the `copyFile()` method. The first argument in this method\nis the path to the file that you want to copy. The second argument is a `Dir` object, i.e., a directory handler,\nmore specifically, a `Dir` object that points to the folder in your computer where you want to\ncopy the file to. The third argument is the new path of the file, or, in other words, the new location\nof the file. The fourth argument is the options (or flags) to be used in the copy operation.\n\nThe `Dir` object that you provide as input to this method will be used to copy the file to\nthe new location. You may create this `Dir` object before calling the `copyFile()` method.\nMaybe you are planning to copy the file to a completely different location in your computer,\nso it might be worth to create a directory handler to that location. But if you are copying the\nfile to a subfolder of your CWD, then, you can just simply pass the CWD handler to this argument.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.copyFile(\n    \"foo.txt\",\n    cwd,\n    \"ZigExamples/file-io/foo.txt\",\n    .{}\n);\n```\n:::\n\n\n\n\n### Read the docs!\n\nThere are some other useful methods for file operations available at `Dir` objects,\nsuch as the `writeFile()` method, but I recommend you to read the docs for the\n[`Dir` type](https://ziglang.org/documentation/master/std/#std.fs.Dir)[^zig-dir]\nto explore the other available methods, since I already talked too much about them.\n\n\n[^zig-dir]: <https://ziglang.org/documentation/master/std/#std.fs.Dir>\n\n\n\n\n## Position indicators {#sec-indicators}\n\nA position indicator is like a type of cursor, or, an index. This \"index\" identifies the current\nlocation in the file (or, in the data stream) that the file descriptor object that you have\nis currently looking at.\nWhen you create a file descriptor, the position indicator starts at the beginning of the file,\nor, at the beginning of the stream. When you read from or write into the file (or socket, or data stream, etc.)\ndescribed by this file descriptor object, you end up moving the position indicator.\n\nIn other words, any IO operation have a common side effect, which is to move the position indicator.\nFor example, suppose that we have a file of 300 bytes total in size. If you\nread 100 bytes from the file, then, the position indicator moves 100 bytes forward. If you try\nto write 50 bytes into this same file, these 50 bytes will be written from the current\nposition indicated by the position indicator. Since the indicator is at a 100 bytes forward from\nthe beginning of the file, these 50 bytes would be written in the middle of the file.\n\nThis is why we have used the `seekTo()` method at the last code example presented in @sec-creating-files.\nWe have used this method to move the position indicator back to the beginning of the file, which\nwould make sure that we would write the text that we wanted to write from the beginning of the file,\ninstead of writing it from the middle of the file. Because before the write operation, we had\nperformed a read operation, which means that the position indicator was moved in this read operation.\n\nThe position indicators of a file descriptor object can be changed (or altered) by using the\n\"seek\" methods from this file descriptor, which are: `seekTo()`, `seekFromEnd()` and `seekBy()`.\nThese methods have the same effect, or, the same responsibility that the\n[`fseek()`](https://en.cppreference.com/w/c/io/fseek)[^c-fseek] C function.\n\n[^c-fseek]: <https://en.cppreference.com/w/c/io/fseek>\n\n\nConsidering that `offset` refers to the index that you provide as input to these \"seek\" methods,\nthe bullet points below summarises what is the effect of each of these methods.\nAs a quick note, in the case of `seekFromEnd()` and `seekBy()`, the `offset` provided can be either a\npositive or a negative index.\n\n- `seekTo()` will move the position indicator to the location that is `offset` bytes from the beginning of the file.\n- `seekFromEnd()` will move the position indicator to the location that is `offset` bytes from the end of the file.\n- `seekBy()` will move the position indicator to the location that is `offset` bytes from the current position in the file.\n\n\n\n\n\n\n\n## Directory operations\n\n### Iterating through the files in a directory\n\nOne of the most classic tasks related to filesystem is to be able\nto iterate through the existing files in a directory. To iterate over the\nfiles in a directory, we need to create an iterator object.\n\nYou can produce such iterator object by using either the `iterate()` or `walk()` methods\nof a `Dir` object. Both methods return an iterator object as output, which you can advance by using the\n`next()` method. The difference between these methods, is that `iterate()` returns a non-recursive iterator,\nwhile `walk()` does. It means that the iterator returned by `walk()` will not only iterate through\nthe files available in the current directory, but also, through the files from any subdirectory found\ninside the current directory.\n\nIn the example below, we are displaying the names of the files stored inside the\ndirectory `ZigExamples/file-io`. Notice that we had to open this directory through\nthe `openDir()` function. Also notice that we provided the flag `iterate` in the\nsecond argument of `openDir()`. This flag is important, because without this flag,\nwe would not be allowed to iterate through the files in this directory.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst dir = try cwd.openDir(\n    \"ZigExamples/file-io/\",\n    .{ .iterate = true }\n);\nvar it = dir.iterate();\nwhile (try it.next()) |entry| {\n    try stdout.print(\n        \"File name: {s}\\n\",\n        .{entry.name}\n    );\n}\n```\n:::\n\n\n\n```\nFile name: create_file_and_write_toit.zig\nFile name: create_file.zig\nFile name: lorem.txt\nFile name: iterate.zig\nFile name: delete_file.zig\nFile name: append_to_file.zig\nFile name: user_input.zig\nFile name: foo.txt\nFile name: create_file_and_read.zig\nFile name: buff_io.zig\nFile name: copy_file.zig\n```\n\n\n### Creating new directories\n\nThere are two methods that are important when it comes to\ncreating directories, which are `makeDir()` and `makePath()`.\nThe difference between these two methods is that `makeDir()` can\nonly create one single directory in the current directory in each call,\nwhile `makePath()` is capable of recursively create subdirectories in the same call.\n\n\nThis is why the name of this method is \"make path\". It will create as many\nsubdirectories as necessary to create the path that you provided as input.\nSo, if you provide the path `\"sub1/sub2/sub3\"` as input to this method,\nit will create three different subdirectories, `sub1`, `sub2` and `sub3`,\nwithin the same function call. In contrast, if you provided such path\nas input to `makeDir()`, you would likely get an error as result, since\nthis method can only create a single subdirectory.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.makeDir(\"src\");\ntry cwd.makePath(\"src/decoders/jpg/\");\n```\n:::\n\n\n\n### Deleting directories\n\nTo delete a directory, just provide the path to the directory that you want to delete\nas input to the `deleteDir()` method from a `Dir` object. In the example below,\nwe are deleting the `src` directory that we have just created in the previous example.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.deleteDir(\"src\");\n```\n:::\n\n\n\n\n## Conclusion\n\nIn this chapter, I have described how to perform in Zig the most common filesystem and IO operations.\nBut you might feel the lack of some other, less common, operation in this chapter, such as: how to rename files,\nor how to open a directory, or how to create symbolic links, or how to use `access()` to test if a particular\npath exists in your computer. But for all of these less common tasks, I recommend you to read\nthe documentation of the [`Dir` type](https://ziglang.org/documentation/master/std/#std.fs.Dir)[^zig-dir]\n, since you can find a good description of these cases there.\n",
+    "supporting": [
+      "12-file-op_files"
+    ],
+    "filters": [
+      "rmarkdown/pagebreak.lua"
+    ],
+    "includes": {},
+    "engineDependencies": {
+      "knitr": [
+        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
+      ]
+    },
+    "preserve": null,
+    "postProcess": false
+  }
+}
\ No newline at end of file
diff --git a/_freeze/Chapters/13-image-filter/execute-results/epub.json b/_freeze/Chapters/13-image-filter/execute-results/epub.json
new file mode 100644
index 00000000..31e3f7fe
--- /dev/null
+++ b/_freeze/Chapters/13-image-filter/execute-results/epub.json
@@ -0,0 +1,21 @@
+{
+  "hash": "99b3cf5d4ae363f25838f780686e3234",
+  "result": {
+    "engine": "knitr",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Project 4 - Developing an image filter\n\nIn this chapter we are going to build a new project. The objective of\nthis project is to write a program that applies a filter over an image.\nMore specifically, a \"grayscale filter\", which transforms\nany color image into a grayscale image.\n\nWe are going to use the image displayed in @fig-pascal in this project.\nIn other words, we want to transform this colored image into a grayscale image,\nby using our \"image filter program\" written in Zig.\n\n![A photo of the chilean-american actor Pedro Pascal. Source: Google Images.](../ZigExamples/image_filter/pedro_pascal.png){#fig-pascal}\n\nWe don't need to write a lot of code to build such \"image filter program\". However, we first need\nto understand how digital images work. That is why we begin this chapter\nby explaining the theory behind digital images and how colors are represented in modern computers.\nWe also give a brief explanation about the PNG (Portable Network Graphics) file format, which is the format used\nin the example images.\n\nAt the end of this chapter, we should have a full example of a program that takes the PNG image displayed in @fig-pascal\nas input, and writes a new image to the current working directory that is the grayscale version of this input image.\nThis grayscale version of @fig-pascal is exposed in @fig-pascal-gray.\nYou can find the full source code of this small project at the `ZigExamples/image_filter`\n[folder at the official repository of this book](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter)[^img-filter-folder].\n\n\n![The grayscale version of the photo.](../ZigExamples/image_filter/pedro_pascal_filter.png){#fig-pascal-gray}\n\n\n## How we see things? {#sec-eyes}\n\nIn this section, I want to briefly describe to you how we (humans) actually see things with our own eyes.\nI mean, how our eyes work? If you do have a very basic understanding of how our eyes work, you will understand\nmore easily how digital images are made. Because the techniques behind digital images\nwere developed by taking a lot of inspiration from how our human eyes work.\n\nYou can interpret a human eye as a light sensor, or, a light receptor. The eye receives some amount of light as input,\nand it interprets the colors that are present in this \"amount of light\".\nIf no amount of light hits the eye, then, the eye cannot extract color from it, and as result,\nwe end up seeing nothing, or, more precisely, we see complete blackness.\n\nTherefore, everything depends on light. What we actually see are the colors (blue, red, orange, green, purple, yellow, etc.) that\nare being reflected from the light that is hitting our eyes. **Light is the source of all colors!**\nThis is what Isaac Newton discovered on his famous prism experiment[^newton] in the 1660s.\n\n[^newton]: <https://library.si.edu/exhibition/color-in-a-new-light/science>\n\nInside our eyes, we have a specific type of cell called the \"cone cell\".\nOur eye have three different types, or, three different versions of these \"cone cells\".\nEach type of cone cell is very sensitive to a specific spectrum of the light. More specifically,\nto the spectrums that define the colors red, green and blue.\nSo, in summary, our eyes have specific types of cells that\nare highly sensitive to these three colors (red, green and blue).\n\nThese are the cells responsible for perceiving the color present in the light that hits our eyes.\nAs a result, our eyes perceives color as a mixture of these three colors (red, green and blue). By having an amount\nof each one of these three colors, and mixing them together, we can get any other visible color\nthat we want. So every color that we see is perceived as a specific mixture of blues, greens and reds,\nlike 30% of red, plus 20% of green, plus 50% of blue.\n\nWhen these cone cells perceive (or, detect) the colors that are found in the\nlight that is hitting our eyes, these cells produce electrical signals, which are sent to the brain.\nOur brain interprets these electrical signals, and use them to form the image that we are seeing\ninside our head.\n\nBased on what we have discussed here, the bullet points exposed below describes the sequence of events that\ncomposes this very simplified version of how our human eyes work:\n\n1. Light hits our eyes.\n1. The cone cells perceive the colors that are present in this light.\n1. Cone cells produce electrical signals that describes the colors that were perceived in the light.\n1. The electrical signals are sent to the brain.\n1. Brain interprets these signals, and form the image based on the colors identified by these electrical signals.\n\n\n## How digital images work? {#sec-digital-img}\n\nA digital image is a \"digital representation\" of an image that we see with our eyes.\nIn other words, a digital image is a \"digital representation\" of the colors that we see\nand perceive through the light.\nIn the digital world, we have two types of images, which are: vector images and raster images.\nVector images are not described here. So just remember that the content discussed here\n**is related solely to raster images**, and not vector images.\n\nA raster image is a type of digital image that is represented as a 2D (two dimensional) matrix\nof pixels. In other words, every raster image is basically a rectangle of pixels, and each pixel have a particular color.\nSo, a raster image is just a rectangle of pixels, and each of these pixels are displayed in the screen of your computer (or the screen\nof any other device, e.g. laptop, tablet, smartphone, etc.) as a color.\n\n@fig-raster demonstrates this idea. If you take any raster image, and you zoom into it very hard,\nyou will see the actual pixels of the image. JPEG, TIFF and PNG are file formats that are commonly\nused to store raster images.\n\n![Zooming over a raster image to see the pixels. Source: Google Images.](../Figures/imagem-raster.png){#fig-raster}\n\nThe more pixels the image has, the more information and detail we can include in the image.\nThe more accurate, sharp and pretty the image will look. This is why photographic cameras\nusually produce big raster images, with several megapixels of resolution, to include as much detail as possible into the final image.\nAs an example, a digital image with dimensions of 1920 pixels wide and 1080 pixels high, would be a image that\ncontains $1920 \\times 1080 = 2073600$ pixels in total. You could also say that the \"total area\" of the image is\nof 2073600 pixels, although the concept of \"area\" is not really used here in computer graphics.\n\nMost digital images we see in our modern world uses the RGB color model. RGB stands for (red, green and blue).\nSo the color of each pixel in these raster images are usually represented as a mixture of red, green and blue,\njust like in our eyes. That is, the color of each pixel is identified by a set of\nthree different integer values. Each integer value identifies the \"amount\" of each color (red, green and blue).\nFor example, the set `(199, 78, 70)` identifies a color that is more close to red. We have 199 of red, 78 of green,\nand 70 of blue. In contrast, the set `(129, 77, 250)` describes a color that is more close to purple. Et cetera.\n\n\n\n### Images are displayed from top to bottom\n\nThis is not a rule written in stone, but the big majority of digital images are displayed from top\nto bottom and left to right. Most computers screens also follow this pattern. So, the first pixels\nin the image are the ones that are at the top and left corner of the image. You can find a visual representation\nof this logic in @fig-img-display.\n\nAlso notice in @fig-img-display that, because a raster image is essentially a 2D matrix of pixels,\nthe image is organized into rows and columns of pixels. The columns are defined by the horizontal x axis,\nwhile the rows are defined by the vertical y axis.\n\nEach pixel (i.e., the gray rectangles) exposed in @fig-img-display contains a number inside of it.\nThese numbers are the indexes of the pixels. You can notice that the first pixels are in the top and left\ncorner, and also, that the indexes of these pixels \"grow to the sides\", or, in other words, they grow in the direction of the horizontal x axis.\nMost raster images are organized as rows of pixels. Thus, when these digital images are\ndisplayed, the screen display the first row of pixels, then, the second row, then, the third row, etc.\n\n![How the pixels of raster images are displayed.](./../Figures/image-display.png){#fig-img-display}\n\n\n\n\n\n\n### Representing the matrix of pixels in code {#sec-pixel-repr}\n\nOk, we know already that raster images are represented as 2D matrices of pixels.\nBut we do not have a notion of a 2D matrix in Zig. Actually, most low-level languages in general\n(Zig, C, Rust, etc.) do not have such notion.\nSo how can we represent such matrix of pixels in Zig, or any other low-level language?\nThe strategy that most programmers choose in this situation is to just use a normal 1D array to store the values of\nthis 2D matrix. In other words, you just create an normal 1D array, and store all values from both dimensions into this 1D array.\n\nAs an example, suppose we have a very small image of dimensions 4x3.\nSince a raster image is represented as a 2D matrix of pixels, and each pixel\nis represented by 3 \"unsigned 8-bit\" integer values, we have 12 pixels in\ntotal in this image, which are represented by $3 \\times 12 = 36$ integer values.\nTherefore, we need to create an array of 36 `u8` values to store this small image.\n\nThe reason why unsigned 8-bit integer (`u8`) values are used to represent the amounts of each color,\ninstead of any other integer type, is because they take the minimum amount of space as possible, or,\nthe minimum amount of bits as possible. Which helps to reduces the binary size of the image, i.e., the 2D matrix.\nAlso, they convey a good amount of precision and detail about the colors, even though they can represent\na relatively small range (from 0 to 255) of \"color amounts\".\n\nComing back to our initial example of a 4x3 image,\nthe `matrix` object exposed below could be an example of an 1D array that stores\nthe data that represents this 4x3 image.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst matrix = [_]u8{\n    201, 10, 25, 185, 65, 70,\n    65, 120, 110, 65, 120, 117,\n    98, 95, 12, 213, 26, 88,\n    143, 112, 65, 97, 99, 205,\n    234, 105, 56, 43, 44, 216,\n    45, 59, 243, 211, 209, 54,\n};\n```\n:::\n\n\n\nThe first three integer values in this array are the color amounts of the first pixel in the image.\nThe next three integers are the colors amounts for the second pixel.\nAnd the sequence goes on in this pattern. Having that in mind, the size of the array that stores\na raster image is usually a multiple of 3. In this case, the array have a size of 36.\n\nI mean, the size of the array is **usually** a multiple of 3, because in specific circumstances,\nit can also be a multiple of 4. This happens when a transparency amount is\nalso included into the raster image. In other words, there are some types of raster images\nthat uses a different color model, which is the RGBA (red, green, blue and alpha)\ncolor model. The \"alpha\" corresponds to an amount of transparency in the pixel.\nSo every pixel in a RGBA image is represented by a red, green, blue and alpha values.\n\nMost raster images uses the standard RGB model, so, for the most part, you will\nsee arrays sizes that are multiples of 3. But some images, especially the ones\nthat are stored in PNG files, might be using the RGBA model, and, therefore, are\nrepresented by an array whose size is a multiple of 4.\n\nIn our case here, the example image of our project (@fig-pascal) is a raster image\nstored in a PNG file, and this specific image is using the RGBA color model. Therefore,\neach pixel in the image is represented by 4 different integer values, and, as consequence,\nto store this image in our Zig code, we need to create an array whose size is a multiple of 4.\n\n\n## The PNG library that we are going to use\n\nLet's begin our project by focusing on writing the necessary Zig code to\nread the data from the PNG file. In other words, we want to read the PNG file exposed\nin @fig-pascal, and parse its data to extract the 2D matrix of pixels that represents the image.\n\nAs we have discussed in @sec-pixel-repr, the image that we are using as example here\nis a PNG file that uses the RGBA color model, and, therefore, each pixel of the image\nis represented by 4 integer values. You can download this image by visiting the `ZigExamples/image_filter`\n[folder at the official repository of this book](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter)[^img-filter-folder].\nYou can also find in this folder the complete source code of this small project that we\nare developing here.\n\n[^img-filter-folder]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter>\n\nThere are some C libraries available that we can use to read and parse PNG files.\nThe most famous and used of all is `libpng`, which is the \"official library\" for reading and writing\nPNG files. Although this library is available on most operating system, it's well known\nfor being complex and hard to use.\n\nThat is why, I'm going to use a more modern alternative here in this project, which is the `libspng` library.\nI choose to use this C library here, because it's much, much simpler to use than `libpng`,\nand it also offers very good performance for all operations. You can checkout the\n[official website of the library](https://libspng.org/)[^libspng]\nto know more about it. You will also find there some documentation that might help you to understand and\nfollow the code examples exposed here.\n\n[^libspng]: <https://libspng.org/>\n\n\nFirst of all, remember to build and install this `libspng` into your system. Because\nif you don't do this step, the `zig` compiler will not be able to find the files and resources of\nthis library in your computer, and link them with the Zig source code that we are writing together here.\nThere is good information about how to build and install the library at the\n[build section of the library documentation](https://libspng.org/docs/build/)[^lib-build].\n\n[^lib-build]: <https://libspng.org/docs/build/>\n\n\n\n\n## Reading the PNG file\n\nIn order to extract the pixel data from the PNG file, we need to read and decode the file.\nA PNG file is just a binary file written in the \"PNG format\". Luckily, the `libspng` library offers\na function called `spng_decode_image()` that does all this heavy work for us.\n\nNow, since `libspng` is a C library, most of the file and I/O operations in this library are made by using\na `FILE` C pointer. Because of that, is probably a better idea to use the `fopen()` C function\nto open our PNG file, instead of using the `openFile()` method that I introduced in @sec-filesystem.\nThat is why I'm importing the `stdio.h` C header in this project, and using the `fopen()` C function to open the file.\n\nIf you look at the snippet below, you can see that we are:\n\n1. opening the PNG file with `fopen()`.\n1. creating the `libspng` context with `spng_ctx_new()`.\n1. using `spng_set_png_file()` to specify the `FILE` object that reads the PNG file that we are going to use.\n\nEvery operation in `libspng` is made through a \"context object\". In our snippet below, this object is `ctx`.\nAlso, to perform an operation over a PNG file, we need to specify which exact PNG file we are referring to.\nThis is the job of `spng_set_png_file()`. We are using this function to specify the file descriptor\nobject that reads the PNG file that we want to use.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n    @cInclude(\"spng.h\");\n});\n\nconst path = \"pedro_pascal.png\";\nconst file_descriptor = c.fopen(path, \"rb\");\nif (file_descriptor == null) {\n    @panic(\"Could not open file!\");\n}\nconst ctx = c.spng_ctx_new(0) orelse unreachable;\n_ = c.spng_set_png_file(\n    ctx, @ptrCast(file_descriptor)\n);\n```\n:::\n\n\n\nBefore we continue, is important to emphasize the following: since we have opened the file with `fopen()`,\nwe have to remember to close the file at the end of the program, with `fclose()`.\nIn other words, after we have done everything that we wanted to do with the PNG file\n`pedro_pascal.png`, we need to close this file, by applying `fclose()` over the file descriptor object.\nWe could use also the `defer` keyword to help us in this task, if we want to.\nThis code snippet below demonstrates this step:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (c.fclose(file_descriptor) != 0) {\n    return error.CouldNotCloseFileDescriptor;\n}\n```\n:::\n\n\n\n\n\n\n### Reading the image header section\n\nNow, the context object `ctx` is aware of our PNG file `pedro_pascal.png`, because it has access to\na file descriptor object to this file. The first thing that we are going to do is to read the\n\"image header section\" of the PNG file. This \"image header section\" is the section\nof the file that contains some basic information about the PNG file, like, the bit depth of the pixel data\nof the image, the color model used in the file, the dimensions of the image (height and width in number of pixels),\netc.\n\nTo make things easier, I will encapsulate this \"read image header\" operation into a\nnice and small function called `get_image_header()`. All that this function needs to do\nis to call the `spng_get_ihdr()` function. This function from `libspng` is responsible\nfor reading the image header data, and storing it into a C struct named `spng_ihdr`.\nThus, an object of type `spng_ihdr` is a C struct that contains the data from the\nimage header section of the PNG file.\n\nSince this Zig function is receiving a C object (the `libspng` context object) as input, I marked\nthe function argument `ctx` as \"a pointer to the context object\" (`*c.spng_ctx`), following the recommendations\nthat we have discussed in @sec-pass-c-structs.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn get_image_header(ctx: *c.spng_ctx) !c.spng_ihdr {\n    var image_header: c.spng_ihdr = undefined;\n    if (c.spng_get_ihdr(ctx, &image_header) != 0) {\n        return error.CouldNotGetImageHeader;\n    }\n\n    return image_header;\n}\n\nvar image_header = try get_image_header(ctx);\n```\n:::\n\n\n\nAlso notice in this function, that I'm checking if the `spng_get_ihdr()` function call have\nreturned or not an integer value that is different than zero. Most functions from the\n`libspng` library return a code status as result, and the code status \"zero\" means\n\"success\". So any code status that is different than zero means that an error\noccurred while running `spng_get_ihdr()`. This is why I'm returning an error value from\nthe function in case the code status returned by the function is different than zero.\n\n\n### Allocating space for the pixel data\n\nBefore we read the pixel data from the PNG file, we need to allocate enough space to hold this data.\nBut in order to allocate such space, we first need to know how much space we need to allocate.\nThe dimensions of the image are obviously needed to calculate the size of this space. But there are\nother elements that also affect this number, such as the color model used in the image, the bit depth, and others.\n\nAnyway, all of this means that calculating the size of the space that we need, is not a simple task.\nThat is why the `libspng` library offers an utility function named\n`spng_decoded_image_size()` to calculate this size for us. Once again, I'm going\nto encapsulate the logic around this C function into a nice and small Zig function\nnamed `calc_output_size()`. You can see below that this function returns a nice\ninteger value as result, informing the size of the space that we need to allocate.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn calc_output_size(ctx: *c.spng_ctx) !u64 {\n    var output_size: u64 = 0;\n    const status = c.spng_decoded_image_size(\n        ctx, c.SPNG_FMT_RGBA8, &output_size\n    );\n    if (status != 0) {\n        return error.CouldNotCalcOutputSize;\n    }\n    return output_size;\n}\n```\n:::\n\n\n\n\n\nYou might quest yourself what the value `SPNG_FMT_RGBA8` means. This value is actually an enum\nvalue defined in the `spng.h` C header file. This enum is used to identify a \"PNG format\".\nMore precisely, it identifies a PNG file that uses the RGBA color model and 8 bit depth.\nSo, by providing this enum value as input to the `spng_decoded_image_size()` function,\nwe are saying to this function to calculate the size of the decoded pixel data, by considering\na PNG file that follows this \"RGBA color model with 8 bit depth\" format.\n\nHaving this function, we can use it in conjunction with an allocator object, to allocate an\narray of bytes (`u8` values) that is big enough to store the decoded pixel data of the image.\nNotice that I'm using `@memset()` to initialize the entire array to zero.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst output_size = try calc_output_size(ctx);\nvar buffer = try allocator.alloc(u8, output_size);\n@memset(buffer[0..], 0);\n```\n:::\n\n\n\n\n### Decoding the image data\n\nNow that we have the necessary space to store the decoded pixel data of the image,\nwe can start to actually decode and extract this pixel data from the image,\nby using the `spng_decode_image()` C function.\n\nThe `read_data_to_buffer()` Zig function exposed below summarises the necessary\nsteps to read this decoded pixel data, and store it into an input buffer.\nNotice that this function is encapsulating the logic around the `spng_decode_image()` function.\nAlso, we are using the `SPNG_FMT_RGBA8` enum value once again to inform the corresponding function,\nthat the PNG image being decoded, uses the RGBA color model and 8 bit depth.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn read_data_to_buffer(ctx: *c.spng_ctx, buffer: []u8) !void {\n    const status = c.spng_decode_image(\n        ctx,\n        buffer.ptr,\n        buffer.len,\n        c.SPNG_FMT_RGBA8,\n        0\n    );\n\n    if (status != 0) {\n        return error.CouldNotDecodeImage;\n    }\n}\n```\n:::\n\n\n\nHaving this function at hand, we can apply it over our context object, and also, over\nthe buffer object that we have allocated in the previous section to hold the decoded pixel data\nof the image:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry read_data_to_buffer(ctx, buffer[0..]);\n```\n:::\n\n\n\n\n### Looking at the pixel data\n\nNow that we have the pixel data stored in our \"buffer object\", we can take\na quick look at the bytes. In the example below, we are looking at the first\n12 bytes in the decoded pixel data.\n\nIf you take a close look at these values, you might notice that every 4 bytes\nin the sequence is 255. Which, coincidentally is the maximum possible integer value\nto be represented by a `u8` value. So, if the range from 0 to 255, which is the range\nof integer values that can be represented by an `u8` value, can be represented as a scale from 0% to 100%,\nthese 255 values are essentially 100% in that scale.\n\nIf you recall from @sec-pixel-repr, I have\ndescribed in that section that our `pedro_pascal.png` PNG file uses the RGBA color model,\nwhich adds an alpha (or transparency) byte to each pixel in the image.\nAs consequence, each pixel in the image is represented by 4 bytes. Since we are looking\nhere are the first 12 bytes in the image, it means that we are looking at the data from\nthe first $12 / 4 = 3$ pixels in the image.\n\nSo, based on how these first 12 bytes (or these 3 pixels) look, with these 255 values at every 4 bytes, we can say that is likely\nthat every pixel in the image have alpha (or transparency) setted to 100%. This might not be true,\nbut, is the most likely possibility. Also, if we look at the image itself, which if your recall is\nexposed in @fig-pascal, we can see that the transparency does not change across the image,\nwhich enforces this theory.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry stdout.print(\"{any}\\n\", .{buffer[0..12]});\n```\n:::\n\n\n\n```\n{\n    200, 194, 216, 255, 203, 197,\n    219, 255, 206, 200, 223, 255\n}\n```\n\n\nWe can see in the above result that the first pixel in this image have 200 of red, 194 of green, and 216 of blue.\nHow do I know the order in which the colors appears in the sequence? If you have not guessed that yet,\nis because of the acronym RGB. First RED, then GREEN, then BLUE. If we scale these integer values\naccording to our scale of 0% to 100% (0 to 255), we get 78% of red, 76% of green and 85% of blue.\n\n\n\n## Applying the image filter\n\nNow that we have the data of each pixel in the image, we can focus on applying our image\nfilter over these pixels. Remember, our objective here is to apply a grayscale filter over\nthe image. A grayscale filter is a filter that transforms a colored image into a grayscale image.\n\nThere are different formulas and strategies to transform a colored image into a grayscale image.\nBut all of these different strategies normally involve applying some math over the colors of each pixel.\nIn this project, we are going to use the most general formula, which is exposed below.\nThis formula considers $r$ as the red of the pixel, $g$ as the green, $b$ as the blue, and $p'$ as the\nlinear luminance of the pixel.\n\n$$\n    p' = (0.2126 \\times r) + (0.7152 \\times g) + (0.0722 \\times b)\n$${#eq-grayscale}\n\nThis @eq-grayscale is the formula to calculate the linear luminance of a pixel. It's worth noting that this formula\nworks only for images whose pixels are using the sRGB color space, which is the standard color space\nfor the web. Thus, ideally, all images on the web should use this color space. Luckily,\nthis is our case here, i.e., the `pedro_pascal.png` image is using this sRGB color space, and, as consequence,\nwe can use the @eq-grayscale. You can read more about this formula at the Wikipedia page for grayscale [@wiki_grayscale].\n\nThe `apply_image_filter()` function exposed below summarises the necessary steps to\napply @eq-grayscale over the pixels in the image. We just apply this function\nover our buffer object that contains our pixel data, and, as result, the pixel\ndata stored in this buffer object should now represent the grayscale version of our image.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn apply_image_filter(buffer:[]u8) !void {\n    const len = buffer.len;\n    const red_factor: f16 = 0.2126;\n    const green_factor: f16 = 0.7152;\n    const blue_factor: f16 = 0.0722;\n    var index: u64 = 0;\n    while (index < len) : (index += 4) {\n        const rf: f16 = @floatFromInt(buffer[index]);\n        const gf: f16 = @floatFromInt(buffer[index + 1]);\n        const bf: f16 = @floatFromInt(buffer[index + 2]);\n        const y_linear: f16 = (\n            (rf * red_factor) + (gf * green_factor)\n            + (bf * blue_factor)\n        );\n        buffer[index] = @intFromFloat(y_linear);\n        buffer[index + 1] = @intFromFloat(y_linear);\n        buffer[index + 2] = @intFromFloat(y_linear);\n    }\n}\n\ntry apply_image_filter(buffer[0..]);\n```\n:::\n\n\n\n\n\n## Saving the grayscale version of the image\n\nSince we have now the grayscale version of our image stored in our buffer object,\nwe need to encode this buffer object back into the \"PNG format\", and save the encoded data into\na new PNG file in our filesystem, so that we can access and see the grayscale version of our image\nthat was produced by our small program.\n\nTo do that, the `libspng` library help us once again by offering an \"encode data to PNG\" type of function,\nwhich is the `spng_encode_image()` function. But in order to \"encode data to PNG\" with `libspng`, we need\nto create a new context object. This new context object must use an \"encoder context\", which\nis identified by the enum value `SPNG_CTX_ENCODER`.\n\nThe `save_png()` function exposed below, summarises all the necessary steps to save the\ngrayscale version of our image into a new PNG file in the filesystem. By default, this\nfunction will save the grayscale image into a file named `pedro_pascal_filter.png` in the CWD.\n\nNotice in this code example that we are using the same image header object (`image_header`) that we have\ncollected previously with the `get_image_header()` function. Remember, this image header object\nis a C struct (`spng_ihdr`) that contains basic information about our PNG file, such as\nthe dimensions of the image, the color model used, etc.\n\nIf we wanted to save a very different image in this new PNG file, e.g. an image\nwith different dimensions, or, an image that uses a different color model, a different bit depth, etc.\nwe would have to create a new image header (`spng_ihdr`) object that describes the properties\nof this new image.\n\nBut we are essentially saving the same image that we have begin with here (the dimensions of\nthe image, the color model, etc. are all still the same). The only difference\nbetween the two images are the colors of the pixels, which are now \"shades of gray\".\nAs consequence, we can safely use the exact same image header data in this new PNG file.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn save_png(image_header: *c.spng_ihdr, buffer: []u8) !void {\n    const path = \"pedro_pascal_filter.png\";\n    const file_descriptor = c.fopen(path.ptr, \"wb\");\n    if (file_descriptor == null) {\n        return error.CouldNotOpenFile;\n    }\n    const ctx = (\n        c.spng_ctx_new(c.SPNG_CTX_ENCODER)\n        orelse unreachable\n    );\n    defer c.spng_ctx_free(ctx);\n    _ = c.spng_set_png_file(ctx, @ptrCast(file_descriptor));\n    _ = c.spng_set_ihdr(ctx, image_header);\n\n    const encode_status = c.spng_encode_image(\n        ctx,\n        buffer.ptr,\n        buffer.len,\n        c.SPNG_FMT_PNG,\n        c.SPNG_ENCODE_FINALIZE\n    );\n    if (encode_status != 0) {\n        return error.CouldNotEncodeImage;\n    }\n    if (c.fclose(file_descriptor) != 0) {\n        return error.CouldNotCloseFileDescriptor;\n    }\n}\n\ntry save_png(&image_header, buffer[0..]);\n```\n:::\n\n\n\nAfter we execute this `save_png()` function, we should have a new PNG file\ninside our CWD, named `pedro_pascal_filter.png`. If we open this PNG file,\nwe will see the same image exposed in @fig-pascal-gray.\n\n\n## Building our project\n\nNow that we have written the code, let's discuss how can we build/compile this project.\nTo do that, I'm going to create a `build.zig` file in the root directory of our project,\nand start writing the necessary code to compile the project, using the knowledge\nthat we have acquired from @sec-build-system.\n\n\nWe first create the build target for our executable file, that executes our\nZig code. Let's suppose that all of our Zig code was written into a Zig module\nnamed `image_filter.zig`. The `exe` object exposed in the build script below\ndescribes the build target for our executable file.\n\nSince we have used some C code from the `libspng` library in our Zig code,\nwe need to link our Zig code (which is in the `exe` build target) to both\nthe C Standard Library, and, to the `libspng` library. We do that, by calling\nthe `linkLibC()` and `linkSystemLibrary()` methods from our `exe` build target.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const target = b.standardTargetOptions(.{});\n    const optimize = b.standardOptimizeOption(.{});\n    const exe = b.addExecutable(.{\n        .name = \"image_filter\",\n        .root_source_file = b.path(\"src/image_filter.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n    exe.linkLibC();\n    // Link to libspng library:\n    exe.linkSystemLibrary(\"spng\");\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\nSince we are using the `linkSystemLibrary()` method, it means that the library\nfiles for `libspng` are searched in your system to be linked with the `exe` build target.\nIf you have not yet built and installed the `libspng` library into your system, this\nlinkage step will likely not work. Because it will not find the library files in your system.\n\nSo, just remember to install `libspng` in your system, if you want to build this project.\nHaving this build script above written, we can finally build our project by\nrunning the `zig build` command in the terminal.\n\n```bash\nzig build\n```\n",
+    "supporting": [
+      "13-image-filter_files"
+    ],
+    "filters": [
+      "rmarkdown/pagebreak.lua"
+    ],
+    "includes": {},
+    "engineDependencies": {
+      "knitr": [
+        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
+      ]
+    },
+    "preserve": null,
+    "postProcess": false
+  }
+}
\ No newline at end of file
diff --git a/_freeze/Chapters/14-threads/execute-results/epub.json b/_freeze/Chapters/14-threads/execute-results/epub.json
new file mode 100644
index 00000000..430a96bc
--- /dev/null
+++ b/_freeze/Chapters/14-threads/execute-results/epub.json
@@ -0,0 +1,21 @@
+{
+  "hash": "5330e6bae2255d3ad46893b0641f0683",
+  "result": {
+    "engine": "knitr",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Introducing threads and parallelism in Zig {#sec-thread}\n\nThreads are available in Zig through the `Thread` struct from the Zig Standard Library.\nThis struct represents a kernel thread, and it follows a POSIX Thread pattern,\nmeaning that, it works similarly to a thread from the `pthread` C library, which is usually available on any distribution\nof the GNU C Compiler (`gcc`). If you are not familiar with threads, I will give you some theory behind it first, shall we?\n\n\n## What are threads? {#sec-what-thread}\n\nA thread is basically a separate context of execution.\nWe use threads to introduce parallelism into our program,\nwhich in most cases, makes the program run faster, because we have multiple tasks\nbeing performed at the same time, parallel to each other.\n\nPrograms are normally single-threaded by default. Which means that each program\nusually runs on a single thread, or, a single context of execution. When we have only one thread running, we have no\nparallelism. And when we don't have parallelism, the commands are executed sequentially, that is,\nonly one command is executed at a time, one after another. By creating multiple threads inside our program,\nwe start to execute multiple commands at the same time.\n\nPrograms that create multiple threads are very common in the wild. Because many different types\nof applications are well suited for parallelism. Good examples are video and photo-editing applications\n(e.g. Adobe Photoshop or DaVinci Resolve), games (e.g. The Witcher 3), and also web browsers\n(e.g. Google Chrome, Firefox, Microsoft Edge, etc).\nFor example, in web browsers, threads are normally used to implement tabs.\nThe tabs in a web browsers usually run as separate threads in the main process of\nthe web browser. That is, each new tab that you open in your web browser\nusually runs on a separate thread of execution.\n\nBy running each tab in a separate thread, we allow all open tabs in the browser to run at the same time,\nand independently from each other. For example, you might have YouTube or Spotify currently open in\na tab, and you are listening to some podcast in that tab while at the same time\nworking in another tab, writing an essay on Google Docs. Even if you are not looking\ninto the YouTube tab, you can still hear the podcast only because this YouTube tab is running in parallel\nwith the other tab where Google Docs is running.\n\nWithout threads, the other alternative would be to run each tab as a completely separate\nprocess in your computer. But that would be a bad choice because just a few tabs would already consume\ntoo much power and resources from your computer. In other words, it's very expensive to create a completely new process,\ncompared to creating a new thread of execution. Also, the chances of you experiencing lag and overhead\nwhile using the browser would be significant. Threads are faster to create, and they also consume\nmuch, much less resources from the computer, especially because they share some resources\nwith the main process.\n\nTherefore, it's the use of threads in modern web browsers that allow you to hear the podcast\nat the same time while you are writing something on Google Docs.\nWithout threads, a web browser would probably be limited to just one single tab.\n\nThreads are also well-suited for anything that involves serving requests or orders.\nBecause serving a request takes time, and usually involves a lot of \"waiting time\".\nIn other words, we spend a lot of time in idle, waiting for something to complete.\nFor example, consider a restaurant. Serving orders in a restaurant usually involves\nthe following steps:\n\n1. receive order from the client.\n1. pass the order to the kitchen, and wait for the food to be cooked.\n1. start cooking the food in the kitchen.\n1. when the food is fully cooked deliver this food to the client.\n\nIf you think about the bullet points above, you will notice that one big moment of waiting time\nis present in this whole process, which is while the food is being cooked\ninside the kitchen. While the food is being prepped, both the waiter and the client\nthemselves are waiting for the food to be ready and delivered.\n\nIf we write a program to represent this restaurant, more specifically, a single-threaded program, then\nthis program would be very inefficient. Because the program would stay in idle, waiting for a considerable amount\nof time on the \"check if food is ready\" step. Consider the code snippet exposed below that could\npotentially represent such program.\n\nThe problem with this program is the while loop. This program will spend a lot of time\nwaiting on the while loop, doing nothing more than just checking if the food is ready.\nThis is a waste of time. Instead of waiting for something to happen, the waiter\ncould just send the order to the kitchen, and just move on, and continue with receiving\nmore orders from other clients, and sending more orders to the kitchen, instead\nof doing nothing and waiting for the food to be ready.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst order = Order.init(\"Pizza Margherita\", n = 1);\nconst waiter = Waiter.init();\nwaiter.receive_order(order);\nwaiter.ask_kitchen_to_cook();\nvar food_not_ready = true;\nwhile (food_not_ready) {\n    food_not_ready = waiter.is_food_ready();\n}\nconst food = waiter.get_food_from_kitchen();\nwaiter.send_food_to_client(food);\n```\n:::\n\n\n\nThis is why threads would be a great fit for this program. We could use threads\nto free the waiters from their \"waiting duties\", so they can go on with their\nother tasks, and receive more orders. Take a look at the next example, where I have re-written the above\nprogram into a different program that uses threads to cook and deliver the orders.\n\nYou can see in this program that when a waiter receives a new order\nfrom a client, this waiter executes the `send_order()` function.\nThe only thing that this function does is to create a new thread\nand detaches it. Since creating a thread is a very fast operation,\nthis `send_order()` function returns almost immediately,\nso the waiter spends almost no time worrying about the order, and just\nmove on and tries to get the next order from the clients.\n\nInside the new thread created, the order gets cooked by a chef, and when the\nfood is ready, it's delivered to the client's table.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn cook_and_deliver_order(order: *Order) void {\n    const chef = Chef.init();\n    const food = chef.cook(order.*);\n    chef.deliver_food(food);\n}\nfn send_order(order: Order) void {\n    const cook_thread = Thread.spawn(\n        .{}, cook_and_deliver_order, .{&order}\n    );\n    cook_thread.detach();\n}\n\nconst waiter = Waiter.init();\nwhile (true) {\n    const order = waiter.get_new_order();\n    if (order) {\n        send_order(order);\n    }\n}\n```\n:::\n\n\n\n\n\n## Threads versus processes\n\nWhen we run a program, this program is executed as a *process* in the operating system.\nThis is a one to one relationship, each program or application that you execute\nis a separate process in the operating system. But each program, or each process,\ncan create and contain multiple threads inside of it. Therefore,\nprocesses and threads have a one to many relationship.\n\nThis also means that every thread that we create is always associated with a particular process in our computer.\nIn other words, a thread is always a subset (or a children) of an existing process.\nAll threads share some of the resources associated with the process from which they were created.\nAnd because threads share resources with the process, they are very good for making communication\nbetween tasks easier.\n\nFor example, suppose that you were developing a big and complex application\nthat would be much simpler if you could split it in two, and make these two separate pieces talk\nwith each other. Some programmers opt to effectively write these two pieces of the codebase as two\ncompletely separate programs, and then, they use IPC (*inter-process communication*) to make these\ntwo separate programs/processes talk to each other, and make them work together.\n\nHowever, some programmers find IPC hard to deal with, and, as consequence,\nthey prefer to write one piece of the codebase as the \"main part of the program\",\nor, as the part of the code that runs as the process in the operating system,\nwhile the other piece of the codebase is written as a task to be executed in\na new thread. A process and a thread can easily comunicate with each other\nthrough both control flow, and also, through data, because they share and have\naccess to the same standard file descriptors (`stdout`, `stdin`, `stderr`), and also to the\nsame memory space on the heap and global data section.\n\n\nIn more details, each thread that you create have a separate stack frame reserved just for that thread,\nwhich essentially means that each local object that you create inside this thread, is local to that\nthread, i.e., the other threads cannot see this local object. Unless this object that you have created\nis an object that lives on the heap. In other words, if the memory associated with this object\nis on the heap, then, the other threads can potentially access this object.\n\nTherefore, objects that are stored in the stack are local to the thread where they were created.\nBut objects that are stored on the heap are potentially accessible to other threads. All of this means that,\neach thread has its own separate stack frame, but, at the same time, all threads share\nthe same heap, the same standard file descriptors (which means that they share the same `stdout`, `stdin`, `stderr`),\nand the same global data section in the program.\n\n\n\n## Creating a thread\n\nWe create new threads in Zig by first importing the `Thread` struct into\nour current Zig module and then calling the `spawn()` method of this struct,\nwhich creates (or \"spawns\") a new thread of execution from our current process.\nThis method has three arguments, which are, respectively:\n\n1. a `SpawnConfig` object, which contains configurations for the spawn process.\n1. the name of the function that is going to be executed (or that is going to be \"called\") inside this new thread.\n1. a list of arguments (or inputs) to be passed to the function provided in the second argument.\n\nWith these three arguments, you can control how the thread gets created, and also, specify which\nwork (or \"tasks\") will be performed inside this new thread. A thread is just a separate context of execution,\nand we usually create new threads in our code because we want to perform some work inside this\nnew context of execution. And we specify which exact work, or which exact steps that are going to be\nperformed inside this context by providing the name of a function as the second argument of the `spawn()` method.\n\nThus, when this new thread gets created, this function that you provided as input to the `spawn()`\nmethod gets called, or gets executed inside this new thread. You can control the\narguments, or the inputs that are passed to this function when it gets called by providing\na list of arguments (or a list of inputs) in the third argument of the `spawn()` method.\nThese arguments are passed to the function in the same order that they are\nprovided to `spawn()`.\n\nFurthermore, the `SpawnConfig` is a struct object with only two possible fields, or, two possible members, that you\ncan set to tailor the spawn behaviour. These fields are:\n\n- `stack_size`: you can provide a `usize` value to specify the size (in bytes) of the thread's stack frame. By default, this value is: $16 \\times 1024 \\times 1024$.\n- `allocator`: you can provide an allocator object to be used when allocating memory for the thread.\n\nTo use one of these two fields (or \"configs\"), you just have to create a new object of type `SpawnConfig`,\nand provide this object as input to the `spawn()` method. But, if you are not interested in using\none of these configs, and you are ok with using just the defaults, you can just provide an anonymous\nstruct literal (`.{}`) in place of this `SpawnConfig` argument.\n\nAs our first, and very simple example, consider the code exposed below.\nInside the same program, you can create multiple threads of execution if you want to.\nBut, in this first example, we are creating just a single thread of execution, because\nwe call `spawn()` only once.\n\nAlso, notice in this example that we are executing the function `do_some_work()`\ninside the new thread. Since this function receives no inputs, because it has\nno arguments, we have passed an empty list in this instance, or more precisely,\nan empty, anonymous struct (`.{}`) in the third argument of `spawn()`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Thread = std.Thread;\nfn do_some_work() !void {\n    _ = try stdout.write(\"Starting the work.\\n\");\n    std.time.sleep(100 * std.time.ns_per_ms);\n    _ = try stdout.write(\"Finishing the work.\\n\");\n}\n\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, do_some_work, .{});\n    thread.join();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nStarting the work.Finishing the work.\n```\n\n\n:::\n:::\n\n\n\nNotice the use of `try` when calling the `spawn()` method. This means\nthat this method can return an error in some circumstances. One circumstance\nin particular is when you attempt to create a new thread, when you have already\ncreated too much (i.e., you have exceeded the quota of concurrent threads in your system).\n\nBut, if the new thread is successfully created, the `spawn()` method returns a handler\nobject (which is just an object of type `Thread`) to this new thread. You can use\nthis handler object to effectively control all aspects of the thread.\n\nWhen the thread gets created, the function that you provided as input to `spawn()`\ngets invoked (i.e., gets called) to start the execution on this new thread.\nIn other words, every time you call `spawn()`, not only is a new thread created,\nbut the \"start work button\" of this thread is also automatically pressed.\nSo the work being performed in this thread starts as soon as the thread is created.\nThis is similar to how `pthread_create()` from the `pthreads` library in C works,\nwhich also starts the execution as soon as the thread is created.\n\n\n## Returning from a thread\n\nWe have learned in the previous section that the execution of the thread starts as soon as\nthe thread is created. Now, we will learn how to \"join\" or \"detach\" a thread in Zig.\n\"Join\" and \"detach\" are operations that control how the thread returns to\nthe main thread, or to the main process in our program.\n\nWe perform these operations by using the methods `join()` and `detach()` from the thread handler object.\nEvery thread that you create can be marked as either *joinable* or *detached* [@linux_pthread_create].\nYou can turn a thread into a *detached* thread by calling the `detach()` method\nfrom the thread handler object. But if you call the `join()` method instead, then this thread\nbecomes a *joinable* thread.\n\nA thread cannot be both *joinable* and *detached*. Which in general means\nthat you cannot call both `join()` and `detach()` on the same thread.\nBut a thread must be one of the two, meaning that, you should always call\neither `join()` or `detach()` over a thread. If you don't call\none of these two methods over your thread, you introduce undefined behaviour into your program,\nwhich is described in @sec-not-call-join-detach.\n\nNow, let's describe what each of these two methods do to your thread.\n\n\n### Joining a thread\n\nWhen you join a thread, you are essentially saying: \"Hey! Could you please wait for the thread to finish,\nbefore you continue with your execution?\". For example, if we come back to our first and simplest example\nof a thread in Zig, we created a single thread inside the `main()` function of our program\nand just called `join()` on this thread at the end. This section of the code example is reproduced below.\n\nBecause we are joining this new thread inside the `main()`'s scope, it means that the\nexecution of the `main()` function is temporarily stopped, to wait for the execution of the thread\nto finish. That is, the execution of `main()` stops temporarily at the line where `join()` gets called,\nand it will continue only after the thread has finished its tasks.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, do_some_work, .{});\n    thread.join();\n}\n```\n:::\n\n\n\nBecause we have joined this new thread inside the `main()` scope, we have a\nguarantee that this new thread will finish before the end of the execution of `main()`.\nBecause it's guaranteed that `main()` will wait for the thread to finish its tasks.\n\nIn the example above, there are no more expressions after the `join()` call. We just have the end\nof the `main()`'s scope, and, therefore, the execution of our program just ends after the thread finishes its tasks,\nsince there is nothing more to do. But what if we had more stuff to do after the join call?\n\nTo demonstrate this other possibility, consider the next example exposed\nbelow. Here, we create a `print_id()` function, that just receives an id\nas input, and prints it to `stdout`. In this example, we are creating two\nnew threads, one after another. Then, we join the first thread, then,\nwe wait for two whole seconds, then, at last, we join the second thread.\n\nThe idea behind this example is that the last `join()` call is executed\nonly after the first thread finishes its task (i.e., the first `join()` call),\nand the two-second delay. If you compile and run this\nexample, you will notice that most messages are quickly printed to `stdout`,\ni.e., they appear almost instantly on your screen.\nHowever, the last message (\"Joining thread 2\") takes around 2 seconds to appear\non the screen.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_id(id: *const u8) !void {\n    try stdout.print(\"Thread ID: {d}\\n\", .{id.*});\n}\n\npub fn main() !void {\n    const id1: u8 = 1;\n    const id2: u8 = 2;\n    const thread1 = try Thread.spawn(.{}, print_id, .{&id1});\n    const thread2 = try Thread.spawn(.{}, print_id, .{&id2});\n\n    _ = try stdout.write(\"Joining thread 1\\n\");\n    thread1.join();\n    std.time.sleep(2 * std.time.ns_per_s);\n    _ = try stdout.write(\"Joining thread 2\\n\");\n    thread2.join();\n}\n```\n:::\n\n\n\n```\nThread ID: Joining thread 1\n1\nThread ID: 2\nJoining thread 2\n```\n\nThis demonstrates that both threads finish their work (i.e., printing the IDs)\nvery fast, before the two seconds of delay end. Because of that, the last `join()` call\nreturns pretty much instantly. Because when this last `join()` call happens, the second\nthread has already finished its task.\n\nNow, if you compile and run this example, you will also notice that, in some cases,\nthe messages intertwine with each other. In other words, you might see\nthe message \"Joining thread 1\" inserted in the middle of the message \"Thread 1\",\nor vice-versa. This happens because:\n\n- the threads are executing basically at the same time as the main process of the program (i.e., the `main()` function).\n- the threads share the same `stdout` from the main process of the program, which means that the messages that the threads produce are sent to exact same place as the messages produced by the main process.\n\nBoth of these points were described previously in @sec-what-thread.\nSo the messages might get intertwined because they are being produced and\nsent to the same `stdout` roughly at the same time.\nAnyway, when you call `join()` over a thread, the current process will wait\nfor the thread to finish before it continues, and, when the thread finishes its\ntask, the resources associated with this thread are automatically freed, and\nthe current process continues with its execution.\n\n\n### Detaching a thread\n\nWhen you detach a thread, the resources associated with this thread are automatically\nreleased back to the system, without the need for another thread to join with this terminated thread.\n\nIn other words, when you call `detach()` on a thread it's like when your children become adults,\ni.e., they become independent from you. A detached thread frees itself, and when this thread finishes its\ntasks, it does not report the results back to you. Thus, you normally mark a thread as *detached*\nwhen you don't need to use the return value of the thread, or when you don't care about\nwhen exactly the thread finishes its job, i.e., the thread solves everything by itself.\n\nTake the code example below. We create a new thread, detach it, and then, we just\nprint a final message before we end our program. We use the same `print_id()`\nfunction that we have used over the previous examples.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_id(id: *const u8) !void {\n    try stdout.print(\"Thread ID: {d}\\n\", .{id.*});\n}\n\npub fn main() !void {\n    const id1: u8 = 1;\n    const thread1 = try Thread.spawn(.{}, print_id, .{&id1});\n    thread1.detach();\n    _ = try stdout.write(\"Finish main\\n\");\n}\n```\n:::\n\n\n\n```\nFinish main\n```\n\nNow, if you look closely at the output of this code example, you will notice\nthat only the final message in main was printed to the console. The message\nthat was supposed to be printed by `print_id()` did not appear in the console.\nWhy? It's because the main process of our program has finished first,\nbefore the thread was able to say anything.\n\nAnd that is perfectly ok behaviour, because the thread was detached, so it was\nable to free itself, without the need to wait for the main process.\nIf you ask main to sleep (or \"wait\") for some extra nanoseconds, before it ends, you will likely\nsee the message printed by `print_id()`, because you give enough time for the thread to\nfinish before the main process ends.\n\n\n## Thread pools\n\nThread pools is a very popular programming pattern, which is used especially on servers and daemons processes.\nA thread pool is just a set of threads, or a \"pool\" of threads. Many programmers like to use this pattern because it makes\nit easier to manage and use multiple threads in your program, instead of manually creating the threads when you need them.\n\nAlso, using thread pools might increase performance as well in your program,\nespecially if your program is constantly creating threads to perform short-lived tasks.\nIn such instance, a thread pool might cause an increase in performance because you do not have be constantly\ncreating and destroying threads all the time, so you don't face a lot of the overhead involved\nin this constant process of creating and destroying threads.\n\nThe main idea behind a thread pool is to have a set of threads already created and ready to perform\ntasks at all times. You create a set of threads at the moment that your program starts, and keep\nthese threads alive while your program runs. Each of these threads will be either performing a task, or\nwaiting for a task to be assigned.\nEvery time a new task emerges in your program, this task is added to a \"queue of tasks\",\nand the moment that a thread becomes available and ready to perform a new task,\nthis thread takes the next task from the \"queue of tasks\", and it simply performs the task.\n\nThe Zig Standard Library offers a thread pool implementation on the `std.Thread.Pool` struct.\nYou create a new instance of a `Pool` object by providing a `Pool.Options` object\nas input to the `init()` method of this struct. A `Pool.Options` object, is a struct object that contains\nconfigurations for the pool of threads. The most important settings in this struct object are\nthe members `n_jobs` and `allocator`. As the name suggests, the member `allocator` should receive an allocator object,\nwhile the member `n_jobs` specifies the number of threads to be created and maintained in this pool.\n\nConsider the example exposed below, that demonstrates how can we create a new thread pool object.\nHere, we create a `Pool.Options` object that contains\na general purpose allocator object, and also, the `n_jobs` member was set to 4, which\nmeans that the thread pool will create and use 4 threads.\n\nAlso notice that the `pool` object was initially set to `undefined`. This allow us\nto initially declare the thread pool object, but not properly instantiate the\nunderlying memory of the object. You have to initially declare your thread pool object\nby using `undefined` like this, because the `init()` method of `Pool` needs\nto have an initial pointer to properly instantiate the object.\n\nSo, just remember to create your thread pool object by using `undefined`, and then,\nafter that, you call the `init()` method over the object.\nYou should also not forget to call the `deinit()` method over the thread pool\nobject, once you are done with it, to release the resources allocated for the thread pool. Otherwise, you will\nhave a memory leak in your program.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Pool = std.Thread.Pool;\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const opt = Pool.Options{\n        .n_jobs = 4,\n        .allocator = allocator,\n    };\n    var pool: Pool = undefined;\n    try pool.init(opt);\n    defer pool.deinit();\n}\n```\n:::\n\n\n\nNow that we know how to create `Pool` objects, we have\nto understand how to assign tasks to be executed by the threads in this pool object.\nTo assign a task to be performed by a thread, we need to call the `spawn()` method\nfrom the thread pool object.\n\nThis `spawn()` method works identical to the `spawn()` method from the\n`Thread` object. The method has almost the same arguments as the previous one,\nmore precisely, we don't have to provide a `SpawnConfig` object in this case.\nBut instead of creating a new thread, this `spawn()` method from\nthe thread pool object just registers a new task in the internal \"queue of tasks\" to be performed,\nand any available thread in the pool will get this task, and it will simply perform the task.\n\nIn the example below, we are using our previous `print_id()` function once again.\nBut you may notice that the `print_id()` function is a little different this time,\nbecause now we are using `catch` instead of `try` in the `print()` call.\nCurrently, the `Pool` struct only supports functions that don't return errors\nas tasks. Thus, when assigning tasks to threads in a thread pool, it is essential to use functions\nthat don't return errors. That is why we are using `catch` here, so that the\n`print_id()` function don't return an error.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_id(id: *const u8) void {\n    _ = stdout.print(\"Thread ID: {d}\\n\", .{id.*})\n        catch void;\n}\nconst id1: u8 = 1;\nconst id2: u8 = 2;\ntry pool.spawn(print_id, .{&id1});\ntry pool.spawn(print_id, .{&id2});\n```\n:::\n\n\n\nThis limitation should probably not exist, and, in fact, it's already on the radar of the\nZig team to fix this issue, and it's being tracked in an [open issue](https://github.com/ziglang/zig/issues/18810)[^issue].\nSo, if you do need to provide a function that might return an error as the task\nto be performed by the threads in the thread pool, then, you are either limited to:\n\n- implementing your own thread pool that does not have this limitation.\n- wait for the Zig team to actually fix this issue.\n\n[^issue]: <https://github.com/ziglang/zig/issues/18810>\n\n\n\n\n## Mutexes\n\nMutexes are a classic component of every thread library. In essence, a mutex is a *Mutually Exclusive Flag*, and this flag\nacts like a type of \"lock\", or as a gate keeper to a particular section of your code. Mutexes are related to thread synchronization,\nmore specifically, they prevent you from having some classic race conditions in your program,\nand, therefore, major bugs and undefined behaviour that are usually difficult to track and understand.\n\nThe main idea behind a mutex is to help us to control the execution of a particular section of the code, and to\nprevent two or more threads from executing this particular section of the code at the same time.\nMany programmers like to compare a mutex to a bathroom door (which typically has a lock).\nWhen a thread locks its own mutex object, it's like if the bathroom door was locked.\nTherefore, other people (in this case, other threads) who want to use the same bathroom at the same time\nmust be patient and simply wait for the current occupant (or thread) to unlock the door and get out of the bathroom.\n\nSome other programmers also like to explain mutexes by using the analogy of \"each person will have their turn to speak\".\nThis is the analogy used in the [*Multithreading Code* video from the Computerphile project](https://www.youtube.com/watch?v=7ENFeb-J75k&ab_channel=Computerphile)[^computerphile].\nImagine if you are in a conversation circle. There is a moderator in this circle, which is the person that decides who\nhas the right to speak at that particular moment. The moderator gives a green card (or some sort of an authorization card) to the person that\nis going to speak, and, as a result, everyone else must be silent and hear this person that has the green card.\nWhen the person finishes talking, they give the green card back to the moderator, and the moderator decides\nwho is going to talk next, and delivers the green card to that person. And the cycle goes on like this.\n\n[^computerphile]: <https://www.youtube.com/watch?v=7ENFeb-J75k&ab_channel=Computerphile>\n\n\nA mutex acts like the moderator in this conversation circle. The mutex authorizes one single thread to execute a specific section of the code,\nand it also blocks the other threads from executing this same section of the code. If these other threads want to execute this same\npiece of the code, they are forced to wait for the the authorized thread to finish first.\nWhen the authorized thread finishes executing this code, the mutex authorizes the next thread to execute this code,\nwhile the remaining threads remain blocked. Therefore, a mutex is like a moderator that does a \"each\nthread will have their turn to execute this section of the code\" type of control.\n\n\nMutexes are especially used to prevent data race problems from happening. A data race problem happens when two or more threads\nare trying to read from or write to the same shared object at the same time.\nSo, when you have an object that is shared will all threads, and, you want to avoid two or more threads from\naccessing this same object at the same time, you can use a mutex to lock the part of the code that access this specific object.\nWhen a thread tries to run this code that is locked by a mutex, this thread stops its execution,\nand patiently waits for this section of the codebase to be unlocked to continue.\n\nNotice that mutexes are normally used to lock areas of the codebase that access/modify data that is **shared** with all threads,\ni.e., objects that are either stored in the global data section, or in the heap space of your program.\nSo mutexes are not normally used on areas of the codebase that access/modify objects that are local to the thread.\n\n\n\n### Critical section {#sec-critical-section}\n\nCritical section is a concept commonly associated with mutexes and thread synchronization.\nIn essence, a critical section is the section of the program that a thread access/modify a shared resource\n(i.e., an object, a file descriptor, something that all threads have access to). In other words,\na critical section is the section of the program where race conditions might happen, and, therefore,\nwhere undefined behaviour can be introduced into the program.\n\nWhen we use mutexes in our program, the critical section defines the area of the codebase that we want to lock.\nSo we normally lock the mutex object at the beginning of the critical section,\nand then, we unlock it at the end of the critical section.\nThe two bullet points exposed below comes from the \"Critical Section\" article from GeekFromGeeks,\nand they summarise well the role that a critical section plays in the thread synchronization problem [@geeks_critical_section].\n\n\n1. The critical section must be executed as an atomic operation, which means that once one thread or process has entered the critical section, all other threads or processes must wait until the executing thread or process exits the critical section. The purpose of synchronization mechanisms is to ensure that only one thread or process can execute the critical section at a time.\n1. The concept of a critical section is central to synchronization in computer systems, as it is necessary to ensure that multiple threads or processes can execute concurrently without interfering with each other. Various synchronization mechanisms such as semaphores, mutexes, monitors, and condition variables are used to implement critical sections and ensure that shared resources are accessed in a mutually exclusive manner.\n\n\n### Atomic operations {#sec-atomic-operation}\n\nYou will also see the term \"atomic operation\" a lot when reading about threads, race conditions and mutexes.\nIn summary, an operation is categorized as \"atomic\" when a context switch cannot occur in\nthe middle of the operation. In other words, this operation is always done from beginning to end, without interruptions\nof another process or operation in the middle of its execution phase.\n\nNot many operations today are atomic. But why do atomic operations matter here? It's because data races\n(which is a type of a race condition) cannot happen on operations that are atomic.\nSo if a particular line in your code performs an atomic operation, then this line will never\nsuffer from a data race problem. Therefore, programmers sometimes use an atomic operation\nto protect themselves from data race problems in their code.\n\nWhen you have an operation that is compiled into just one single assembly instruction, this operation might be atomic,\nbecause it's just one assembly instruction. But this is not guaranteed. This is usually true for old CPU architectures\n(such as `x86`). But nowadays, most assembly instructions in modern CPU architectures are broken down into multiple micro-tasks,\nwhich inherently makes the operation non-atomic, even if it consists of a single assembly instruction.\n\nThe Zig Standard Library offers some atomic functionality in the `std.atomic` module.\nIn this module, you will find a public and generic function called `Value()`. With this function we create an \"atomic object\", which is\na value that contains some native atomic operations, most notably, a `load()` and a `fetchAdd()` operation.\nIf you have experience with multithreading in C++, you probably have recognized this pattern. So yes, this generic\n\"atomic object\" in Zig is essentially identical to the template struct `std::atomic` from the C++ Standard Library.\nIt's important to emphasize that only primitive data types (i.e., the types presented in @sec-primitive-data-types)\nare supported by these atomic operations in Zig.\n\n\n\n\n\n### Data races and race conditions\n\nTo understand why mutexes are used, we need to understand better the problem that they seek\nto solve, which can be summarized into data race problems. A data race problem is a type of a race condition,\nwhich happens when one thread is accessing a particular memory location (i.e., a particular shared object) at the same\ntime that another thread is trying to write/save new data into this same memory location (i.e., the same shared object).\n\nWe can simply define a race condition as any type of bug in your program that is based\non a \"who gets there first\" problem. A data race problem is a type of a race condition, because it occurs when two or more parties\nare trying to read and write into the same memory location at the same time, and, therefore, the end result of this operation\ndepends completely on who gets to this memory location first.\nAs a consequence, a program that has a data race problem will likely produce a different result each time that we execute it.\n\nThus, race conditions produce undefined behaviour and unpredictability because the program produces\na different answer each time a different person gets to the target location before the others.\nAnd, we have no easy way to either predict or control who is getting to this target location first.\nIn other words, each time your program runs, you may get a different answer because a different person,\nfunction, or part of the code finishes its tasks before the others.\n\nAs an example, consider the code snippet exposed below. In this example, we create a global counter\nvariable, and we also create an `increment()` function, whose job is to just increment this global counter\nvariable in a for loop.\n\nSince the for loop iterates 1 hundred thousand times, and, we create two separate threads\nin this code example, what number do you expect to see in the final message printed to `stdout`?\nThe answer should be 2 hundred thousand. Right? Well, in theory, this program was supposed\nto print 2 hundred thousand at the end, but in practice, every time that I execute this program\nI get a different answer.\n\nIn the example exposed below, you can see that this time the end\nresult was 117254, instead of the expected 200000. The second time I executed this program,\nI got the number 108592 as the result. So the end result of this program is varying, but it never gets\nto the expected 200000 that we want.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// Global counter variable\nvar counter: usize = 0;\n// Function to increment the counter\nfn increment() void {\n    for (0..100000) |_| {\n        counter += 1;\n    }\n}\n\npub fn main() !void {\n    const thr1 = try Thread.spawn(.{}, increment, .{});\n    const thr2 = try Thread.spawn(.{}, increment, .{});\n    thr1.join();\n    thr2.join();\n    try stdout.print(\"Couter value: {d}\\n\", .{counter});\n}\n```\n:::\n\n\n\n```\nCouter value: 117254\n```\n\n\nWhy this is happening? The answer is: because this program contains a data race problem.\nThis program would print the correct number 200000 if and only if the first thread finishes\nits tasks before the second thread starts to execute. But that is very unlikely to happen.\nBecause the process of creating the thread is too fast, and therefore, both threads start to execute roughly\nat the same time. If you change this code to add some nanoseconds of sleep between the first and the second calls to `spawn()`,\nyou will increase the chances of the program producing the \"correct result\".\n\nSo the data race problem happens because both threads are reading and writing to the same\nmemory location at roughly the same time. In this example, each thread is essentially performing\nthree basic operations at each iteration of the for loop, which are:\n\n1. reading the current value of `count`.\n1. incrementing this value by 1.\n1. writing the result back into `count`.\n\nIdeally, a thread B should read the value of `count`, only after the other thread A has finished\nwriting the incremented value back into the `count` object. Therefore, in the ideal scenario, which is demonstrated\nin @tbl-data-race-ideal, the threads should work in sync with each other. But the reality is that these\nthreads are out of sync, and because of that, they suffer from a data race problem, which is demonstrated\nin @tbl-data-race-not.\n\nNotice that, in the data race scenario (@tbl-data-race-not), the read performed by a thread B happens\nbefore the write operation of thread A, and that ultimately leads to wrong results at the end of the program.\nBecause when thread B reads the value of the `count` variable, thread A is still processing\nthe initial value from `count`, and has not yet written the new, incremented value back to `count`. As a result,\nthread B ends up reading the same initial (or \"old\") value from `count` instead of\nthe updated, incremented value that thread A would have written.\n\n\n::: {#tbl-data-race-ideal}\n\n| Thread 1    | Thread 2    | Integer value |\n|-------------|-------------|---------------|\n| read value  |             | 0             |\n| increment   |             | 1             |\n| write value |             | 1             |\n|             | read value  | 1             |\n|             | increment   | 2             |\n|             | write value | 2             |\n\n: An ideal scenario for two threads incrementing the same integer value\n:::\n\n::: {#tbl-data-race-not}\n\n| Thread 1    | Thread 2    | Integer value |\n|-------------|-------------|---------------|\n| read value  |             | 0             |\n|             | read value  | 0             |\n| increment   |             | 1             |\n|             | increment   | 1             |\n| write value |             | 1             |\n|             | write value | 1             |\n\n: A data race scenario when two threads are incrementing the same integer value\n:::\n\n\nIf you think about these diagrams exposed in form of tables, you will notice that they relate back to our discussion of atomic operations\nin @sec-atomic-operation. Remember, atomic operations are operations that the CPU executes\nfrom beginning to end, without interruptions from other threads or processes. So,\nthe scenario exposed in @tbl-data-race-ideal does not suffer from a data race, because\nthe operations performed by thread A are not interrupted in the middle by the operations\nfrom thread B.\n\nIf we also think about the discussion of critical section from @sec-critical-section, we can identify\nthe section that representes the critical section of the program, which is the section that is vulnerable\nto data race conditions. In this example, the critical section of the program is the line where we increment\nthe `counter` variable (`counter += 1`). So, ideally, we want to use a mutex, and lock right before this line, and then\nunlock right after this line.\n\n\n\n\n### Using mutexes in Zig\n\nNow that we know the problem that mutexes seek to solve, we can learn how to use them in Zig.\nMutexes in Zig are available through the `std.Thread.Mutex` struct from the Zig Standard Library.\nIf we take the same code from the previous example, and improve it with mutexes, to solve\nour data race problem, we get the code example below.\n\nNotice that this time, we had to alter the `increment()` function to receive a pointer to\nthe `Mutex` object as input. All that we need to do, to make this program safe against\ndata race problems, is to call the `lock()` method at the beginning of\nthe critical section, and then, call `unlock()` at the end of the critical section.\nNotice that the output of this program is now the correct number of 200000.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Thread = std.Thread;\nconst Mutex = std.Thread.Mutex;\nvar counter: usize = 0;\nfn increment(mutex: *Mutex) void {\n    for (0..100000) |_| {\n        mutex.lock();\n        counter += 1;\n        mutex.unlock();\n    }\n}\n\npub fn main() !void {\n    var mutex: Mutex = .{};\n    const thr1 = try Thread.spawn(.{}, increment, .{&mutex});\n    const thr2 = try Thread.spawn(.{}, increment, .{&mutex});\n    thr1.join();\n    thr2.join();\n    try stdout.print(\"Couter value: {d}\\n\", .{counter});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nCouter value: 200000\n```\n\n\n:::\n:::\n\n\n\n\n\n\n## Read/Write locks\n\nMutexes are normally used when it's not always safe for two or more threads running the same\npiece of code at the same time. In contrast, read/write locks are normally used in situations\nwhere you have a mixture of scenarios, i.e., there are some pieces of the codebase that are safe\nto run in parallel, and other pieces that are not safe.\n\nFor example, suppose that you have multiple threads that uses the same shared file in the filesystem to store some configurations, or\nstatistics. If two or more threads try to read the data from this same file at the same time, nothing bad happens.\nSo this part of the codebase is perfectly safe to be executed in parallel, with multiple threads reading the same file at the same time.\n\nHowever, if two or more threads try to write data into this same file at the same time, then we cause some race condition\nproblems. So this other part of the codebase is not safe to be executed in parallel.\nMore specifically, a thread might end up writing data in the middle of the data written by the other thread.\nThis process of two or more threads writing to the same location might lead to data corruption.\nThis specific situation is usually called a *torn write*.\n\nThus, what we can extract from this example is that there are certain types of operations that cause\na race condition, but there are also other types of operations that do not cause a race condition problem.\nYou could also say that there are types of operations that are susceptible to race condition problems,\nand there are other types of operations that are not.\n\nA read/write lock is a type of lock that acknowledges the existence of this specific scenario, and you can\nuse this type of lock to control which parts of the codebase are safe to run in parallel and which parts are not.\n\n\n\n### Exclusive lock vs shared lock\n\nTherefore, a read/write lock is a little different from a mutex. Because a mutex is always an *exclusive lock*, meaning that, only\none thread is allowed to execute at all times. With an exclusive lock, the other threads are always \"excluded\",\ni.e., they are always blocked from executing. But in a read/write lock, the other threads might be authorized\nto run at the same time, depending on the type of lock that they acquire.\n\nWe have two types of locks in a read/write lock, which are: an exclusive lock and a shared lock. An exclusive lock works exactly the same\nas a mutex, while a shared lock is a lock that does not block the other threads from running at the same time.\nIn the `pthreads` C library, read/write locks are available through the `pthread_rwlock_t` C struct. With\nthis C struct, you can create:\n\n- a \"write lock\", which corresponds to an exclusive lock.\n- a \"read lock\", which corresponds to a shared lock.\n\nThe terminology might be a little different compared to Zig. But the meaning is still the same.\nTherefore, just remember this relationship, write locks are exclusive locks, while read locks are shared locks.\n\nWhen a thread tries to acquire a read lock (i.e., a shared lock), this thread gets the shared lock\nif and only if another thread does not currently hold a write lock (i.e., an exclusive lock), and also\nif there are no other threads already in the queue,\nwaiting for their turn to acquire a write lock. In other words, the thread in the queue has attempted\nto get a write lock earlier, but this thread was blocked\nbecause there was another thread running that already had a write lock. As a consequence, this thread is in the queue to get a write lock,\nand it's currently waiting for the other thread with a write lock to finish its execution.\n\nWhen a thread tries to acquire a read lock, but it fails in acquiring this read lock, either because there is\na thread with a write lock already running, or because there is a thread in the queue to get a write lock,\nthe execution of this thread is instantly blocked, i.e., paused. This thread will indefinitely attempt to get the\nread lock, and its execution will be unblocked (or unpaused) only after this thread successfully acquires the read lock.\n\nIf you think deeply about this dynamic between read locks versus write locks, you might notice that a read lock is basically a safety mechanism.\nMore specifically, it's a way for us to\nallow a particular thread to run together with the other threads only when it's safe to. In other words, if there is currently\na thread with a write lock running, then it's very likely not safe for the thread that is trying to acquire the read lock to run now.\nAs a consequence, the read lock protects this thread from running into dangerous waters, and patiently waits for the\n\"write lock\" thread to finishes its tasks before it continues.\n\nOn the other hand, if there are only \"read lock\" (i.e., \"shared lock\") threads currently running\n(i.e., not a single \"write lock\" thread currently exists), then it\nis perfectly safe for this thread that is acquiring the read lock to run in parallel with the other\nthreads. As a result, the read lock just\nallows for this thread to run together with the other threads.\n\nThus, by using read locks (shared locks) in conjunction with write locks (exclusive locks), we can control which regions or sections\nof our multithreaded code is safe to have parallelism, and which sections are not safe to have parallelism.\n\n\n\n\n\n### Using read/write locks in Zig\n\nThe Zig Standard Library supports read/write locks through the `std.Thread.RwLock` module.\nIf you want a particular thread to acquire a shared lock (i.e., a read lock), you should\ncall the `lockShared()` method from the `RwLock` object. But, if you want this thread\nto acquire an exclusive lock (i.e., a write lock) instead, then you should call the\n`lock()` method from the `RwLock` object.\n\nAs with mutexes, we also have to unlock the shared or exclusive locks that we acquire through a read/write lock object,\nonce we are at the end of our \"critical section\". If you have acquired an exclusive lock, then, you unlock\nthis exclusive lock by calling the `unlock()` method from the read/write lock object. In contrast,\nif you have acquired a shared lock instead, then, call `unlockShared()` to unlock this shared lock.\n\nAs a simple example, the snippet below creates three separate threads responsible for reading the\ncurrent value in a `counter` object, and it also creates another thread responsible for writing\nnew data into the `counter` object (incrementing it, more specifically).\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar counter: u32 = 0;\nfn reader(lock: *RwLock) !void {\n    while (true) {\n        lock.lockShared();\n        const v: u32 = counter;\n        try stdout.print(\"{d}\", .{v});\n        lock.unlockShared();\n        std.time.sleep(2 * std.time.ns_per_s);\n    }\n}\nfn writer(lock: *RwLock) void {\n    while (true) {\n        lock.lock();\n        counter += 1;\n        lock.unlock();\n        std.time.sleep(2 * std.time.ns_per_s);\n    }\n}\n\npub fn main() !void {\n    var lock: RwLock = .{};\n    const thr1 = try Thread.spawn(.{}, reader, .{&lock});\n    const thr2 = try Thread.spawn(.{}, reader, .{&lock});\n    const thr3 = try Thread.spawn(.{}, reader, .{&lock});\n    const wthread = try Thread.spawn(.{}, writer, .{&lock});\n\n    thr1.join();\n    thr2.join();\n    thr3.join();\n    wthread.join();\n}\n```\n:::\n\n\n\n\n## Yielding a thread\n\nThe `Thread` struct supports yielding through the `yield()` method.\nYielding a thread means that the execution of the thread is temporarily stopped,\nand it moves to the end of the priority queue managed by the scheduler of\nyour operating system.\n\nThat is, when you yield a thread, you are essentially saying the following to your OS:\n\"Hey! Could you please stop executing this thread for now, and comeback to continue it later?\".\nYou could also interpret this yield operation as: \"Could you please deprioritize this thread,\nto focus on doing other things instead?\".\nSo this yield operation is also a way for you\nto stop a particular thread, so that you can work and prioritize other threads instead.\n\nIt's important to say that, yielding a thread is a \"not so common\" thread operation these days.\nIn other words, not many programmers use yielding in production, simply because it's hard to use\nthis operation and make it work properly, and also, there\nare better alternatives. Most programmers prefer to use `join()` instead.\nIn fact, most of the time, when you see someone using this \"yield\" operation in some code example,\nthey are usually doing so to help debug race conditions in their applications.\nThat is, this \"yield\" operation is mostly used as a debug tool nowadays.\n\nAnyway, if you want to yield a thread, just call the `yield()` method from it, like this:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nthread.yield();\n```\n:::\n\n\n\n\n\n\n\n\n## Common problems in threads\n\n\n\n### Deadlocks\n\nA deadlock occurs when two or more threads are blocked forever,\nwaiting for each other to release a resource. This usually happens when multiple locks are involved,\nand the order of acquiring them is not well managed.\n\nThe code example below demonstrates a deadlock situation. We have two different threads that execute\ntwo different functions (`work1()` and `work2()`) in this example. And we also have two separate\nmutexes. If you compile and run this code example, you will notice that the program just runs indefinitely,\nwithout ending.\n\nWhen we look into the first thread, which executes the `work1()` function, we can\nnotice that this function acquires the `mut1` lock first. Because this is the first operation\nthat is executed inside this thread, which is the first thread created in the program.\nAfter that, the function sleeps for 1 second, to\nsimulate some type of work, and then, the function tries to acquire the `mut2` lock.\n\nOn the other hand, when we look into the second thread, which executes the `work2()` function,\nwe can see that this function acquires the `mut2` lock first. Because when this thread gets created and it tries\nto acquire this `mut2` lock, the first thread is still sleeping on that \"sleep 1 second\" line.\nAfter acquiring `mut2`, the `work2()` function also sleeps for 1 second, to\nsimulate some type of work, and then the function tries to acquire the `mut1` lock.\n\nThis creates a deadlock situation, because after the \"sleep for 1 second\" line in both threads,\nthread 1 is trying to acquire the `mut2` lock, but this lock is currently being used by thread 2.\nHowever, at this moment, thread 2 is also trying to acquire the `mut1` lock, which is currently\nbeing used by thread 1. Therefore, both threads end up waiting for ever. Waiting for their peer to\nfree the lock that they want to acquire.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar mut1: Mutex = .{}; var mut2: Mutex = .{};\nfn work1() !void {\n    mut1.lock();\n    std.time.sleep(1 * std.time.ns_per_s);\n    mut2.lock();\n    _ = try stdout.write(\"Doing some work 1\\n\");\n    mut2.unlock(); mut1.unlock();\n}\n\nfn work2() !void {\n    mut2.lock();\n    std.time.sleep(1 * std.time.ns_per_s);\n    mut1.lock();\n    _ = try stdout.write(\"Doing some work 1\\n\");\n    mut1.unlock(); mut2.unlock();\n}\n\npub fn main() !void {\n    const thr1 = try Thread.spawn(.{}, work1, .{});\n    const thr2 = try Thread.spawn(.{}, work2, .{});\n    thr1.join();\n    thr2.join();\n}\n```\n:::\n\n\n\n\n### Not calling `join()` or `detach()` {#sec-not-call-join-detach}\n\nWhen you do not call either `join()` or `detach()` over a thread, then this thread becomes a \"zombie thread\",\nbecause it does not have a clear \"return point\".\nYou could also interpret this as: \"nobody is properly responsible for managing the thread\".\nWhen we don't establish if a thread is either *joinable* or *detached*,\nnobody becomes responsible for dealing with the return value of this thread, and also,\nnobody becomes responsible for clearing (or freeing) the resources associated with this thread.\n\nYou don't want to be in this situation, so remember to always use `join()` or `detach()`\non the threads that you create. When you don't use one of these methods, we lose\ncontrol over the thread, and its resources are never freed\n(i.e., you have leaked resources in the system).\n\n\n### Cancelling or killing a particular thread\n\nWhen we think about the `pthreads` C library, there is a possible way to asynchronously kill or cancel\na thread, which is by sending a `SIGTERM` signal to the thread through the `pthread_kill()` function.\nBut canceling a thread like this is bad. It's dangerously bad. As a consequence, the Zig implementation\nof threads does not have a similar function, or, a similar way to asynchronously cancel or kill\na thread.\n\nTherefore, if you want to cancel a thread in the middle of its execution in Zig,\nthen one good strategy that you can take is to use control flow in conjunction with `join()`.\nMore specifically, you can design your thread around a while loop that is constantly\nchecking if the thread should continue running.\nIf it's time to cancel the thread, we could make the while loop break, and join the thread with the main thread\nby calling `join()`.\n\nThe code example below demonstrates to some extent this strategy.\nHere, we are using control flow to break the while loop, and exit the thread earlier than\nwhat we have initially planned to. This example also demonstrates how can we use\natomic objects in Zig with the `Value()` generic function that we have mentioned in @sec-atomic-operation.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Thread = std.Thread;\nconst stdout = std.io.getStdOut().writer();\nvar running = std.atomic.Value(bool).init(true);\nvar counter: u64 = 0;\nfn do_more_work() void {\n    std.time.sleep(2 * std.time.ns_per_s);\n}\nfn work() !void {\n    while (running.load(.monotonic)) {\n        for (0..10000) |_| { counter += 1; }\n        if (counter < 15000) {\n            _ = try stdout.write(\n                \"Time to cancel the thread.\\n\"\n            );\n            running.store(false, .monotonic);\n        } else {\n            _ = try stdout.write(\"Time to do more work.\\n\");\n            do_more_work();\n            running.store(false, .monotonic);\n        }\n    }\n}\n\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, work, .{});\n    thread.join();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nTime to cancel the thread.\n```\n\n\n:::\n:::\n",
+    "supporting": [
+      "14-threads_files"
+    ],
+    "filters": [
+      "rmarkdown/pagebreak.lua"
+    ],
+    "includes": {},
+    "engineDependencies": {
+      "knitr": [
+        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
+      ]
+    },
+    "preserve": null,
+    "postProcess": false
+  }
+}
\ No newline at end of file
diff --git a/_freeze/Chapters/14-zig-c-interop/execute-results/epub.json b/_freeze/Chapters/14-zig-c-interop/execute-results/epub.json
new file mode 100644
index 00000000..d2ed7502
--- /dev/null
+++ b/_freeze/Chapters/14-zig-c-interop/execute-results/epub.json
@@ -0,0 +1,21 @@
+{
+  "hash": "7f0fb45d8337d93333a20759133b82dc",
+  "result": {
+    "engine": "knitr",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Zig interoperability with C\n\nIn this chapter, we are going to discuss the interoperability of Zig with C.\nWe have discussed in @sec-building-c-code how you can use the `zig` compiler to build C code.\nBut we haven't discussed yet how to actually use C code in Zig. In other words,\nwe haven't discussed yet how to call and use C code from Zig.\n\nThis is the main subject of this chapter.\nAlso, in our next small project in this book, we are going to use a C library in it.\nAs consequence, we will put in practice a lot of the knowledge discussed here on\nthis next project.\n\n\n## How to call C code from Zig\n\nInteroperability with C is not something new. Most high-level programming languages have FFI (foreign function interfaces),\nwhich can be used to call C code. For example, Python have Cython, R have `.Call()`, Javascript have `ccall()`, etc.\nBut Zig integrates with C in a deeper level, which affects not only the way that C code gets called, but also,\nhow this C code is compiled and incorporated into your Zig project.\n\nIn summary, Zig have great interoperability with C. If you want to call any C code from Zig,\nyou have to perform the following steps:\n\n- import a C header file into your Zig code.\n- link your Zig code with the C library.\n\n\n### Strategies to import C header files {#sec-strategy-c}\n\nUsing C code in Zig always involves performing the two steps cited above. However, when\nwe talk specifically about the first step listed above, there are currently two\ndifferent ways to perform this first step, which are:\n\n- translating the C header file into Zig code, through the `zig translate-c` command, and then, import and use the translated Zig code.\n- importing the C header file directly into your Zig module through the `@cImport()` built-in function.\n\nIf you are not familiar with `translate-c`, this is a subcommand inside the `zig` compiler that takes C files\nas input, and outputs the Zig representation of the C code present in these C files.\nIn other words, this subcommand works like a transpiler. It takes C code, and translates it into\nthe equivalent Zig code.\n\nI think it would be ok to interpret `translate-c` as a tool to generate Zig bindings\nto C code, similarly to the `rust-bindgen`[^bindgen] tool, which generates Rust FFI bindings to C code.\nBut that would not be a precise interpretation of `translate-c`. The idea behind this tool is\nto really translate the C code into Zig code.\n\n[^bindgen]: <https://github.com/rust-lang/rust-bindgen>\n\nNow, on a surface level, `@cImport()` versus `translate-c` might seem like\ntwo completely different strategies. But in fact, they are effectively the exact same strategy.\nBecause, under the hood, the `@cImport()` built-in function is just a shortcut to `translate-c`.\nBoth tools use the same \"C to Zig\" translation functionality. So when you use `@cImport()`,\nyou are essentially asking the `zig` compiler to translate the C header file into Zig code, then,\nto import this Zig code into your current Zig module.\n\nAt the present moment, there is an accepted proposal at the Zig project, to move `@cImport()`\nto the Zig build system[^cimport-issue]. If this proposal is completed, then, the \"use `@cImport()`\"\nstrategy would be transformed into \"call a translate C function in your Zig build script\".\nSo, the step of translating the C code into Zig code would be moved to\nthe build script of your Zig project, and you would only need to import the translated Zig code into\nyour Zig module to start calling C code from Zig.\n\n[^cimport-issue]: <https://github.com/ziglang/zig/issues/20630>\n\nIf you think about this proposal for a minute, you will understand that this is actually\na small change. I mean, the logic is the same, and the steps are still essentially the same.\nThe only difference is that one of the steps will be moved to the build script of your Zig project.\n\n\n\n### Linking Zig code with a C library {#sec-linking-c}\n\nRegardless of which of the two strategies from the previous section you choose,\nif you want to call C code from Zig, you must link your Zig code\nwith the C library that contains the C code that you want to call.\n\nIn other words, everytime you use some C code in your Zig code, **you introduce a dependency in your build process**.\nThis should come as no surprise to anyone that have any experience with C and C++.\nBecause this is no different in C. Everytime you use a C library in your C code, you also\nhave to build and link your C code with this C library that you are using.\n\nWhen we use a C library in our Zig code, the `zig` compiler needs to access the definition of the C functions that\nare being called in your Zig code. The C header file of this library provides the\ndeclarations of these C functions, but not their definitions. So, in order to access these definitions,\nthe `zig` compiler needs to build your Zig code and link it with the C library during the build process.\n\nAs we discussed across the @sec-build-system, there are different strategies to link something with a library.\nThis might involve building the C library first, and then, linking it with the Zig code. Or,\nit could also involve just the linking step, if this C library is already built and\ninstalled in your system. Anyway, if you have doubts about this, comeback to @sec-build-system.\n\n\n\n## Importing C header files {#sec-import-c-header}\n\nIn @sec-strategy-c, we have described that, currently, there are two different paths that\nyou can take to import a C header file into your Zig modules, `translate-c` or `@cImport()`.\nThis section describes each strategy separately in more details.\n\n### Strategy 1: using `translate-c`\n\nWhen we choose this strategy, we first need to use the `translate-c` tool to translate\nthe C header files that we want to use into Zig code. For example, suppose we wanted to\nuse the `fopen()` C function from the `stdio.h` C header file. We can translate the\n`stdio.h` C header file through the bash command below:\n\n```bash\nzig translate-c /usr/include/stdio.h \\\n    -lc -I/usr/include \\\n    -D_NO_CRT_STDIO_INLINE=1 > c.zig \\\n```\n\nNotice that, in this bash command, we are passing the necessary compiler flags (`-D` to define macros,\n`-l` to link libraries, `-I` to add an \"include path\") to compile and use the `stdio.h` header file.\nAlso notice that we are saving the results of the translation process inside a Zig module called `c.zig`.\n\nTherefore, after running this command, all we have to do is to import this `c.zig` module, and start\ncalling the C functions that you want to call from it. The example below demonstrates that.\nIt's important to remember what we've discussed in @sec-linking-c. In order to compile this\nexample you have to link this code with `libc`, by passing the flag `-lc` to the `zig` compiler.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @import(\"c.zig\");\npub fn main() !void {\n    const x: f32 = 1772.94122;\n    _ = c.printf(\"%.3f\\n\", x);\n}\n```\n:::\n\n\n\n```\n1772.941\n```\n\n\n### Strategy 2: using `@cImport()`\n\nTo import a C header file into our Zig code, we can use the built-in functions `@cInclude()` and `@cImport()`.\nInside the `@cImport()` function, we open a block (with a pair of curly braces). Inside this block\nwe can (if we need to) include multiple `@cDefine()` calls to define C macros when including this specific C header file.\nBut for the most part, you will probably need to use just a single call inside this block,\nwhich is a call to `@cInclude()`.\n\nThis `@cInclude()` function is equivalent to the `#include` statement in C.\nYou provide the name of the C header that you want to include as input to this `@cInclude()` function,\nthen, in conjunction with `@cImport()`, it will perform the necessary steps\nto include this C header file into your Zig code.\n\nYou should bind the result of `@cImport()` to a constant object, pretty much like you would do with\n`@import()`. You just assign the result to a constant object in your\nZig code, and, as consequence, all C functions, C structs, C macros, etc. that are defined inside the\nC header files will be available through this constant object.\n\nLook at the code example below, where we are importing the Standard I/O C Library (`stdio.h`),\nand calling the `printf()`[^printf] C function. Notice that we have also used in this example the C function `powf()`[^powf],\nwhich comes from the C Math Library (`math.h`).\nIn order to compile this example, you have to link this Zig code with both\nthe C Standard Library and the C Math Library, by passing the flags `-lc` and `-lm`\nto the `zig` compiler.\n\n[^printf]: <https://cplusplus.com/reference/cstdio/printf/>\n[^powf]: <https://en.cppreference.com/w/c/numeric/math/pow>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n    @cInclude(\"math.h\");\n});\n\npub fn main() !void {\n    const x: f32 = 15.2;\n    const y = c.powf(x, @as(f32, 2.6));\n    _ = c.printf(\"%.3f\\n\", y);\n}\n```\n:::\n\n\n\n```\n1182.478\n```\n\n\n## About passing Zig values to C functions {#sec-zig-obj-to-c}\n\nZig objects have some intrinsic differences between their C equivalents.\nProbably the most noticeable one is the difference between C strings and Zig strings,\nwhich I described in @sec-zig-strings.\nZig strings are objects that contains both an array of arbitrary bytes and a length value.\nOn the other hand, a C string is usually just a pointer to a null-terminated array of arbitrary bytes.\n\nBecause of these intrinsic differences, in some specific cases, you cannot pass Zig objects directly\nas inputs to C functions before you convert them into C compatible values. However, in some other cases,\nyou are allowed to pass Zig objects and Zig literal values directly as inputs to C functions,\nand everything will work just fine, because the `zig` compiler will handle everything for you.\n\nSo we have two different scenarios being described here. Let's call them \"auto-conversion\" and \"need-conversion\".\nThe \"auto-conversion\" scenario is when the `zig` compiler handles everything for you, and automatically convert your\nZig objects/values into C compatible values. In contrast,\nthe \"need-conversion\" scenario is when you, the programmer, have the responsibility of converting\nthat Zig object into a C compatible value, before passing it to C code.\n\nThere is also a third scenario that is not being described here, which is when you create a C object, or, a C struct, or\na C compatible value in your Zig code, and you pass this C object/value as input to a C function in your Zig code.\nThis scenario will be described later in @sec-c-inputs. In this section, we are focused on the scenarios where\nwe are passing Zig objects/values to C code, instead of C objects/values being passed to C code.\n\n\n### The \"auto-conversion\" scenario\n\nAn \"auto-conversion\" scenario is when the `zig` compiler automatically converts our Zig objects into\nC compatible values for us. This specific scenario happens mostly in two instances:\n\n- with string literal values;\n- with any of the primitive data types that were introduced in @sec-primitive-data-types.\n\nWhen we think about the second instance described above, the `zig` compiler does automatically\nconvert any of the primitive data types into their C equivalents, because the compiler knows how\nto properly convert a `i16` into a `signed short`, or, a `u8` into a `unsigned char`, etc.\nNow, when we think about string literal values, they can be automatically\nconverted into C strings as well, especially because the `zig` compiler does not forces\na specific Zig data type into a string literal at first glance, unless you store this\nstring literal into a Zig object, and explicitly annotate the data type of this object.\n\nThus, with string literal values, the `zig` compiler has more freedom to infer which is the appropriate data type\nto be used in each situation. You could say that the string literal value \"inherits its data type\" depending on the context that\nit's used in. Most of the times, this data type is going to be the type that we commonly associate with Zig strings (`[]const u8`).\nBut it might be a different type depending on the situation. When the `zig` compiler detects that you are providing\na string literal value as input to some C function, the compiler automatically interprets this string\nliteral as a C string value.\n\nAs an example, look at the code exposed below. Here we are using\nthe `fopen()` C function to simply open and close a file. If you do not know how this `fopen()`\nfunction works in C, it takes two C strings as input. But in this code example below, we are passing some\nstring literals written in our Zig code directly as inputs to this `fopen()` C function.\n\nIn other words, we are not doing any conversion from a Zig string to a C string.\nWe are just passing the Zig string literals directly as inputs to the C function. And it works just fine!\nBecause the compiler interprets the string `\"foo.txt\"` as a C string given the current context.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n});\n\npub fn main() !void {\n    const file = c.fopen(\"foo.txt\", \"rb\");\n    if (file == null) {\n        @panic(\"Could not open file!\");\n    }\n    if (c.fclose(file) != 0) {\n        return error.CouldNotCloseFileDescriptor;\n    }\n}\n```\n:::\n\n\n\nLet's make some experiments, by writing the same code in different manners, and we\nsee how this affects the program. As a starting point, let's store the `\"foo.txt\"` string inside\na Zig object, like the `path` object below, and then, we pass this Zig object as input to the `fopen()` C function.\n\nIf we do this, the program still compiles and runs successfully. Notice that I have omitted most of the code in this example below.\nThis is just for brevity reasons, because the remainder of the program is still the same.\nThe only difference between this example and the previous one is just these two lines exposed below.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\nNow, what happens if you give an explicit data type to the `path` object? Well, if I force\nthe `zig` compiler to interpret this `path` object as a Zig string object,\nby annotating the `path` object with the data type `[]const u8`, then, I actually get a compile error\nas demonstrated below. We get this compile error because now I'm forcing the `zig` compiler\nto interpret `path` as a Zig string object.\n\nAccording to the error message, the `fopen()` C function was expecting to receive an\ninput value of type `[*c]const u8` (C string) instead of a value of type `[]const u8` (Zig string).\nIn more details, the type `[*c]const u8` is actually the Zig type representation of a C string.\nThe `[*c]` portion of this type identifies a C pointer. So, this Zig type essentially means: a C pointer to an array (`[*c]`) of\nconstant bytes (`const u8`).\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\n```\nt.zig:2:7 error: expected type '[*c]const u8', found '[]const u8':\n    const file = c.fopen(path, \"rb\");\n                         ^~~~\n```\n\nTherefore, when we talk exclusively about string literal values, as long as you don't give an\nexplicit data type to these string literal values, the `zig` compiler should be capable of automatically\nconverting them into C strings as needed.\n\nBut what about using one of the primitive data types that were introduced in @sec-primitive-data-types?\nLet's take code exposed below as an example of that. Here, we are giving some float literal values as input\nto the C function `powf()`. Notice that this code example compiles and runs successfully.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst cmath = @cImport({\n    @cInclude(\"math.h\");\n});\n\npub fn main() !void {\n    const y = cmath.powf(15.68, 2.32);\n    try stdout.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n\n```\n593.2023\n```\n\nOnce again, because the `zig` compiler does not associate a specific data type with the literal values\n`15.68` and `2.32` at first glance, the compiler can automatically convert these values\ninto their C `float` (or `double`) equivalents, before it passes to the `powf()` C function.\nNow, even if I give an explicit Zig data type to these literal values, by storing them into a Zig object,\nand explicit annotating the type of these objects, the code still compiles and runs successfully.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const x: f32 = 15.68;\n    const y = cmath.powf(x, 2.32);\n    // The remainder of the program\n```\n:::\n\n\n\n```\n593.2023\n```\n\n\n\n### The \"need-conversion\" scenario\n\nA \"need-conversion\" scenario is when we need to manually convert our Zig objects into C compatible values\nbefore passing them as input to C functions. You will fall in this scenario, when passing Zig string objects\nto C functions.\n\nWe have already seen this specific circumstance in the last `fopen()` example,\nwhich is reproduced below. You can see in this example, that we have given an explicit Zig data type\n(`[]const u8`) to our `path` object, and, as a consequence of that, we have forced the `zig` compiler\nto see this `path` object, as a Zig string object. Therefore, we need now to manually convert\nthis `path` object into a C string before we pass it to `fopen()`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\n```\nt.zig:10:26: error: expected type '[*c]const u8', found '[]const u8'\n    const file = c.fopen(path, \"rb\");\n                         ^~~~\n```\n\n\nThere are different ways to convert a Zig string object into a C string.\nOne way to solve this problem is to provide the pointer to the underlying array\nof bytes, instead of providing the Zig object directly as input.\nYou can access this pointer by using the `ptr` property of the Zig string object.\n\nThe code example below demonstrates this strategy. Notice that, by giving the\npointer to the underlying array in `path` through the `ptr` property, we get no compile errors as result\nwhile using the `fopen()` C function.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path.ptr, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\nThis strategy works because this pointer to the underlying array found in the `ptr` property,\nis semantically identical to a C pointer to an array of bytes, i.e., a C object of type `*unsigned char`.\nThis is why this option also solves the problem of converting the Zig string into a C string.\n\nAnother option is to explicitly convert the Zig string object into a C pointer by using the\nbuilt-in function `@ptrCast()`. With this function we can convert\nan object of type `[]const u8` into an object of type `[*c]const u8`.\nAs I described at the previous section, the `[*c]` portion of the type\nmeans that it's a C pointer. This strategy is not-recommended. But it's\nuseful to demonstrate the use of `@ptrCast()`.\n\nYou may recall of `@as()` and `@ptrCast()` from @sec-type-cast. Just as a recap,\nthe `@as()` built-in function is used to explicitly convert (or cast) a Zig value\nfrom a type \"x\" into a value of type \"y\". But in our case here, we are converting\na pointer object. Everytime a pointer is involved in some \"type casting operation\" in Zig,\nthe `@ptrCast()` function is involved.\n\nIn the example below, we are using this function to cast our `path` object\ninto a C pointer to an array of bytes. Then, we pass this C pointer as input\nto the `fopen()` function. Notice that this code example compiles successfully\nwith no errors.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path: []const u8 = \"foo.txt\";\n    const c_path: [*c]const u8 = @ptrCast(path);\n    const file = c.fopen(c_path, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\n\n\n## Creating C objects in Zig {#sec-c-inputs}\n\nCreating C objects, or, in other words, creating instances of C structs in your Zig code\nis actually something quite easy to do. You first need to import the C header file (like I described in @sec-import-c-header) that defines\nthe C struct that you are trying to instantiate in your Zig code. After that, you can just\ncreate a new object in your Zig code, and annotate it with the data type of the C struct.\n\nFor example, suppose we have a C header file called `user.h`, and that this header file is declaring a new struct named `User`.\nThis C header file is exposed below:\n\n```c\n#include <stdint.h>\n\ntypedef struct {\n    uint64_t id;\n    char* name;\n} User;\n```\n\nThis `User` C struct have two distinct fields, or two struct members, named `id` and `name`.\nThe field `id` is an unsigned 64-bit integer value, while the field `name` is just a standard C string.\nNow, suppose that I want to create an instance of this `User` struct in my Zig code.\nI can do that by importing this `user.h` header file into my Zig code, and creating\na new object with type `User`. These steps are reproduced in the code example below.\n\nNotice that I have used the keyword `undefined` in this example. This allows me to\ncreate the `new_user` object without the need to provide an initial value to the object.\nAs consequence, the underlying memory associated with this `new_user` object is uninitialized,\ni.e., the memory is currently populated with \"garbage\" values.\nThus, this expression have the exact same effect of the expression `User new_user;` in C,\nwhich means \"declare a new object named `new_user` of type `User`\".\n\nIt's our responsibility to properly initialize this memory associated with this `new_user` object,\nby assigning valid values to the members (or the fields) of the C struct. In the example below,\nI'm assigning the integer 1 to the member `id`. I am also saving the string `\"pedropark99\"` into the member `name`.\nNotice in this example that I manually add the null character (zero byte) to the end of the allocated array\nfor this string. This null character marks the end of the array in C.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst c = @cImport({\n    @cInclude(\"user.h\");\n});\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n\n    var new_user: c.User = undefined;\n    new_user.id = 1;\n    var user_name = try allocator.alloc(u8, 12);\n    defer allocator.free(user_name);\n    @memcpy(user_name[0..(user_name.len - 1)], \"pedropark99\");\n    user_name[user_name.len - 1] = 0;\n    new_user.name = user_name.ptr;\n}\n```\n:::\n\n\n\nSo, in this example above, we are manually initializing each field of the C struct.\nWe could say that, in this instance, we are \"manually instantiating\nthe C struct object\". However, when we use C libraries in our Zig code, we rarely need\nto manually instantiate the C structs like that. Only because C libraries\nusually provide a \"constructor function\" in their public APIs. As consequence, we normally rely on\nthese constructor functions to properly initialize the C structs, and\nthe struct fields for us.\n\nFor example, consider the Harfbuzz C library. This a text shaping C library,\nand it works around a \"buffer object\", or, more specifically, an instance of\nthe C struct `hb_buffer_t`. Therefore, we need to create an instance of\nthis C struct if we want to use this C library. Luckily, this library offers\nthe function `hb_buffer_create()`, which we can use to create such object.\nSo the Zig code necessary to create such object would probably look something like this:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cInclude(\"hb.h\");\n});\nvar buf: c.hb_buffer_t = c.hb_buffer_create();\n// Do stuff with the \"buffer object\"\n```\n:::\n\n\n\nTherefore, we do not need to manually create an instance of the C struct\n`hb_buffer_t` here, and manually assign valid values to each field in this C struct.\nBecause the constructor function `hb_buffer_create()` is doing this heavy job for us.\n\nSince this `buf` object, and also, the `new_user` object from previous examples, are instances of C structs, these\nobjects are by themselves C compatible values. They are C objects defined in our Zig code. As consequence,\nyou can freely pass these objects as input to any C function that expects to receive this type\nof C struct as input. You do not need to use any special syntax, or, to convert them in\nany special manner to use them in C code. This is how we create and use C objects in our Zig code.\n\n\n\n## Passing C structs across Zig functions {#sec-pass-c-structs}\n\nNow that we have learned how to create/declare C objects in our Zig code, we\nneed to learn how to pass these C objects as inputs to Zig functions.\nAs I described in @sec-c-inputs, we can freely pass these C objects as inputs to C code\nthat we call from our Zig code. But what about passing these C objects to Zig functions?\n\nIn essence, this specific case requires one small adjustment in the Zig function declaration.\nAll you need to do, is to make sure that you pass your C object *by reference* to the function,\ninstead of passing it *by value*. To do that, you have to annotate the data type of the function argument\nthat is receiving this C object as \"a pointer to the C struct\", instead of annotating it as \"an instance of the C struct\".\n\nLet's consider the C struct `User` from the `user.h` C header file that we have used in @sec-c-inputs.\nNow, consider that we want to create a Zig function that sets the value of the `id` field\nin this C struct, like the `set_user_id()` function declared below.\nNotice that the `user` argument in this function is annotated as a pointer (`*`) to a `c.User` object.\n\nTherefore, all you have to do when passing C objects to Zig functions, is to add `*` to the\ndata type of the function argument that is receiving the C object. This will make sure that\nthe C object is passed *by reference* to the function.\n\nBecause we have transformed the function argument into a pointer,\neverytime that you have to access the value pointed by this input pointer inside the function body, for whatever reason (e.g. you want\nto read, update, or delete this value), you have to dereference the pointer with the `.*` syntax that we\nlearned from @sec-pointer. Notice that the `set_user_id()` function is using this syntax to alter\nthe value in the `id` field of the `User` struct pointed by the input pointer.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst c = @cImport({\n    @cInclude(\"user.h\");\n});\nfn set_user_id(id: u64, user: *c.User) void {\n    user.*.id = id;\n}\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n\n    var new_user: c.User = undefined;\n    new_user.id = 1;\n    var user_name = try allocator.alloc(u8, 12);\n    defer allocator.free(user_name);\n    @memcpy(user_name[0..(user_name.len - 1)], \"pedropark99\");\n    user_name[user_name.len - 1] = 0;\n    new_user.name = user_name.ptr;\n\n    set_user_id(25, &new_user);\n    try stdout.print(\"New ID: {any}\\n\", .{new_user.id});\n}\n```\n:::\n\n\n\n```\nNew ID: 25\n```\n",
+    "supporting": [
+      "14-zig-c-interop_files"
+    ],
+    "filters": [
+      "rmarkdown/pagebreak.lua"
+    ],
+    "includes": {},
+    "engineDependencies": {
+      "knitr": [
+        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
+      ]
+    },
+    "preserve": null,
+    "postProcess": false
+  }
+}
\ No newline at end of file
diff --git a/_freeze/Chapters/15-vectors/execute-results/epub.json b/_freeze/Chapters/15-vectors/execute-results/epub.json
new file mode 100644
index 00000000..4b0fe519
--- /dev/null
+++ b/_freeze/Chapters/15-vectors/execute-results/epub.json
@@ -0,0 +1,21 @@
+{
+  "hash": "3da767c3f773d387d2d0a42df4405278",
+  "result": {
+    "engine": "knitr",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Introducing Vectors and SIMD {#sec-vectors-simd}\n\nIn this chapter, I want to discuss vectors in Zig, which are\nrelated to SIMD operations (i.e., they have no relationship with the `std::vector` class\nfrom C++).\n\n## What is SIMD?\n\nSIMD (*Single Instruction/Multiple Data*) is a group of operations that are widely used\non video/audio editing programs, and also in graphics applications. SIMD is not a new technology,\nbut the massive use of SIMD on normal desktop computers is somewhat recent. In the old days, SIMD\nwas only used on \"supercomputer models\".\n\nMost modern CPU models (from AMD, Intel, etc.) these days (either in a desktop or in a\nnotebook model) have support for SIMD operations. So, if you have a very old CPU model installed in your\ncomputer, then, it's possible that you have no support for SIMD operations in your computer.\n\nWhy have people started using SIMD in their software? The answer is performance.\nBut what does SIMD precisely do to achieve better performance? Well, in essence, SIMD operations are a different\nstrategy to get parallel computing in your program, and therefore, make faster calculations.\n\nThe basic idea behind SIMD is to have a single instruction that operates over multiple data\nat the same time. When you perform a normal scalar operation, like for example, four add instructions,\neach addition is performed separately, one after another. But with SIMD, these four add instructions\nare translated into a single instruction, and, as consequence, the four additions are performed\nin parallel, at the same time.\n\nCurrently, the `zig` compiler allows you to apply the following group of operators on vector objects.\nWhen you apply one of these operators on vector objects, SIMD is used to make the calculations, and,\ntherefore, these operators are applied element-wise and in parallel by default.\n\n- Arithmetic (`+`, `-`, `/`, `*`, `@divFloor()`, `@sqrt()`,  `@ceil()`, `@log()`, etc.).\n- Bitwise operators (`>>`, `<<`, `&`, `|`, `~`, etc.).\n- Comparison operators (`<`, `>`, `==`, etc.).\n\n\n## Vectors {#sec-what-vectors}\n\nA SIMD operation is usually performed through a *SIMD intrinsic*, which is just a fancy\nname for a function that performs a SIMD operation. These SIMD intrinsics (or \"SIMD functions\")\nalways operate over a special type of object, which are called \"vectors\". So,\nin order to use SIMD, you have to create a \"vector object\".\n\nA vector object is usually a fixed-sized block of 128 bits (16 bytes).\nAs a consequence, most vectors that you find in the wild are essentially arrays that contains 2 values of 8 bytes each,\nor, 4 values of 4 bytes each, or, 8 values of 2 bytes each, etc.\nHowever, different CPU models may have different extensions (or, \"implementations\") of SIMD,\nwhich may offer more types of vector objects that are bigger in size (256 bits or 512 bits)\nto accomodate more data into a single vector object.\n\nYou can create a new vector object in Zig by using the `@Vector()` built-in function. Inside this function,\nyou specify the vector length (number of elements in the vector), and the data type of the elements\nof the vector. Only primitive data types are supported in these vector objects.\nIn the example below, I'm creating two vector objects (`v1` and `v2`) of 4 elements of type `u32` each.\n\nAlso notice in the example below, that a third vector object (`v3`) is created from the\nsum of the previous two vector objects (`v1` plus `v2`). Therefore,\nmath operations over vector objects take place element-wise by default, because\nthe same operation (in this case, addition) is transformed into a single instruction\nthat is replicated in parallel, across all elements of the vectors.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1 = @Vector(4, u32){4, 12, 37, 9};\nconst v2 = @Vector(4, u32){10, 22, 5, 12};\nconst v3 = v1 + v2;\ntry stdout.print(\"{any}\\n\", .{v3});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 14, 34, 42, 21 }\n```\n\n\n:::\n:::\n\n\n\nThis is how SIMD introduces more performance in your program. Instead of using a for loop\nto iterate through the elements of `v1` and `v2`, and adding them together, one element at a time,\nwe enjoy the benefits of SIMD, which performs all 4 additions in parallel, at the same time.\n\nTherefore, the `@Vector` structure is essentially the Zig representation of SIMD vector objects.\nThe elements in these vector objects will be operated in parallel, if, and only if your current CPU model\nsupports SIMD operations. If your CPU model does not have support for SIMD, then, the `@Vector` structure will\nlikely produce a similar performance from a \"for loop solution\".\n\n\n### Transforming arrays into vectors\n\nThere are different ways to transform a normal array into a vector object.\nYou can either use implicit conversion (which is when you assign the array to\na vector object directly), or, use slices to create a vector object from a normal array.\n\nIn the example below, we are implicitly converting the array `a1` into a vector object (`v1`)\nof length 4. We first explicitly annotate the data type of the vector object,\nand then, we assign the array object to this vector object.\n\nAlso notice in the example below, that a second vector object (`v2`) is also created\nby taking a slice of the array object (`a1`), and then, storing the pointer to this\nslice (`.*`) into this vector object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a1 = [4]u32{4, 12, 37, 9};\nconst v1: @Vector(4, u32) = a1;\nconst v2: @Vector(2, u32) = a1[1..3].*;\n_ = v1; _ = v2;\n```\n:::\n\n\n\n\nIt's worth emphasizing that only arrays and slices whose sizes\nare compile-time known can be transformed into vectors. Vectors in general\nare structures that work only with compile-time known sizes. Therefore, if\nyou have an array whose size is runtime known, then, you first need to\ncopy it into an array with a compile-time known size, before transforming it into a vector.\n\n\n\n### The `@splat()` function\n\nYou can use the `@splat()` built-in function to create a vector object that is filled\nwith the same value across all of its elements. This function was created to offer a quick\nand easy way to directly convert a scalar value (a.k.a. a single value, like a single character, or a single integer, etc.)\ninto a vector object.\n\nThus, we can use `@splat()` to convert a single value, like the integer `16` into a vector object\nof length 1. But we can also use this function to convert the same integer `16` into a\nvector object of length 10, that is filled with 10 `16` values. The example below demonstrates\nthis idea.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1: @Vector(10, u32) = @splat(16);\ntry stdout.print(\"{any}\\n\", .{v1});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 16, 16, 16, 16, 16, 16, 16, 16, 16, 16 }\n```\n\n\n:::\n:::\n\n\n\n\n\n### Careful with vectors that are too big\n\nAs I described in @sec-what-vectors, each vector object is usually a small block of 128, 256 or 512 bits.\nThis means that a vector object is usually small in size, and when you try to go in the opposite direction,\nby creating a vector object that is very big in size (i.e., sizes that are close to $2^{20}$),\nyou usually end up with crashes and loud errors from the compiler.\n\nFor example, if you try to compile the program below, you will likely face segmentation faults, or LLVM errors during\nthe build process. Just be careful to not create vector objects that are too big in size.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1: @Vector(1000000, u32) = @splat(16);\n_ = v1;\n```\n:::\n\n\n\n```\nSegmentation fault (core dumped)\n```\n",
+    "supporting": [
+      "15-vectors_files"
+    ],
+    "filters": [
+      "rmarkdown/pagebreak.lua"
+    ],
+    "includes": {},
+    "engineDependencies": {
+      "knitr": [
+        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
+      ]
+    },
+    "preserve": null,
+    "postProcess": false
+  }
+}
\ No newline at end of file
diff --git a/_freeze/index/execute-results/epub.json b/_freeze/index/execute-results/epub.json
new file mode 100644
index 00000000..4df3471d
--- /dev/null
+++ b/_freeze/index/execute-results/epub.json
@@ -0,0 +1,21 @@
+{
+  "hash": "0b80ffe49bae68e2641a31569b9e19df",
+  "result": {
+    "engine": "knitr",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy a PDF, eBook or a physical copy\nof the book, either at Amazon, or at Leanpub:\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://leanpub.com/introductiontozigaproject-basedbook\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Leanpub!\n    </button>\n</a>\n\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e., open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.\nCurrently, he is a Senior Data Engineer at [DSM-Firmenich](https://www.dsm-firmenich.com)[^dsm], and\na Databricks Certified Associate Developer for Apache Spark 3.0.\n\n[^dsm]: <https://www.dsm-firmenich.com>\n\n\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nBrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer who loves to learn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2025 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n- System version: Linux, 6.12.21-4-MANJARO, NA, x86_64.\n- Zig version: 0.15.0-dev.635+7dbd21bd5.\n- Quarto version: 1.4.554.\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang), Tommaso Ricci (\\@Zorgatone), Primo Sabatini (\\@primos63), Santiago Fernandez (\\@santif), Hamza Wahed (\\@HamzaWahed), mwilbur (\\@mwilbur), Dima Budaragin (\\@dbud), Jorge Jímenez (\\@jorge-j1m), Alexander (\\@alexwheezy), Maarten Coopens (\\@maarteNNNN), Niklas Johansson (\\@Raphexion), glystik (\\@glystik), Michael Lynch (\\@mtlynch), Yashank (\\@stickyburn), _blf_ (\\@bengtfrost)\n",
+    "supporting": [
+      "index_files"
+    ],
+    "filters": [
+      "rmarkdown/pagebreak.lua"
+    ],
+    "includes": {},
+    "engineDependencies": {
+      "knitr": [
+        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
+      ]
+    },
+    "preserve": null,
+    "postProcess": false
+  }
+}
\ No newline at end of file
diff --git a/_freeze/references/execute-results/epub.json b/_freeze/references/execute-results/epub.json
new file mode 100644
index 00000000..eb15b841
--- /dev/null
+++ b/_freeze/references/execute-results/epub.json
@@ -0,0 +1,21 @@
+{
+  "hash": "b3fb07f33430db017c1afb683e34205a",
+  "result": {
+    "engine": "knitr",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n::::: {.content-visible when-format=\"html\"}\n\n# References {.unnumbered}\n\n::: {#refs}\n:::\n\n:::::\n",
+    "supporting": [
+      "references_files"
+    ],
+    "filters": [
+      "rmarkdown/pagebreak.lua"
+    ],
+    "includes": {},
+    "engineDependencies": {
+      "knitr": [
+        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
+      ]
+    },
+    "preserve": null,
+    "postProcess": false
+  }
+}
\ No newline at end of file

From 8a4289d99b1aee75b559328af54ab4c9bd6a7d40 Mon Sep 17 00:00:00 2001
From: Pedro Faria <69123925+pedropark99@users.noreply.github.com>
Date: Tue, 27 May 2025 18:24:36 -0300
Subject: [PATCH 142/151] Update README.md

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 249cc212..ab93cf22 100644
--- a/README.md
+++ b/README.md
@@ -150,7 +150,7 @@ to open a terminal, and run the `nix develop` command on the root of the project
 nix develop
 ```
 
-With this command, Onix will download the necessary packages and libraries, and then create a new bash session that points
+With this command, Nix will download the necessary packages and libraries, and then create a new bash session that points
 to a new environment that contains these packages and libraries in it. Then, inside this new bash session that is created
 by Nix, all you need to do is to run the `quarto render` command, which will kickstart Quarto, and make it build the book
 for you:

From 332e3b0138cf66612123425d1b51a69d33dd8d95 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Wed, 28 May 2025 17:22:14 -0300
Subject: [PATCH 143/151] Compare zig defer with go defer

---
 Chapters/03-structs.qmd                       | 19 ++++++++++++++---
 Chapters/05-pointers.qmd                      |  7 ++++---
 .../01-base64/execute-results/epub.json       | 21 -------------------
 .../01-base64/execute-results/html.json       |  6 ++----
 .../01-memory/execute-results/epub.json       | 21 -------------------
 .../01-memory/execute-results/html.json       |  6 ++----
 .../01-zig-weird/execute-results/epub.json    | 21 -------------------
 .../01-zig-weird/execute-results/html.json    |  2 +-
 .../02-debugging/execute-results/epub.json    | 21 -------------------
 .../02-debugging/execute-results/html.json    |  6 ++----
 .../03-structs/execute-results/epub.json      | 21 -------------------
 .../03-structs/execute-results/html.json      |  4 ++--
 .../03-unittests/execute-results/epub.json    | 21 -------------------
 .../03-unittests/execute-results/html.json    |  6 ++----
 .../04-http-server/execute-results/epub.json  | 21 -------------------
 .../04-http-server/execute-results/html.json  |  6 ++----
 .../05-pointers/execute-results/html.json     |  4 ++--
 .../07-build-system/execute-results/epub.json | 21 -------------------
 .../07-build-system/execute-results/html.json |  6 ++----
 .../execute-results/epub.json                 | 21 -------------------
 .../execute-results/epub.json                 | 21 -------------------
 .../execute-results/html.json                 |  6 ++----
 .../execute-results/epub.json                 | 21 -------------------
 .../execute-results/html.json                 |  2 +-
 .../12-file-op/execute-results/epub.json      | 21 -------------------
 .../12-file-op/execute-results/html.json      |  6 ++----
 .../13-image-filter/execute-results/epub.json | 21 -------------------
 .../13-image-filter/execute-results/html.json |  6 ++----
 .../14-threads/execute-results/epub.json      | 21 -------------------
 .../14-threads/execute-results/html.json      |  6 ++----
 .../execute-results/epub.json                 | 21 -------------------
 .../execute-results/html.json                 |  6 ++----
 .../15-vectors/execute-results/epub.json      | 21 -------------------
 .../15-vectors/execute-results/html.json      |  6 ++----
 _freeze/index/execute-results/epub.json       | 21 -------------------
 _freeze/index/execute-results/html.json       |  4 ++--
 _freeze/references/execute-results/epub.json  | 21 -------------------
 _freeze/references/execute-results/html.json  |  2 +-
 _quarto.yml                                   |  5 ++++-
 docs/Chapters/03-structs.html                 | 11 ++++++----
 docs/Chapters/03-unittests.html               |  8 +++----
 docs/Chapters/05-pointers.html                |  4 ++--
 docs/Chapters/09-error-handling.html          |  2 +-
 docs/Chapters/10-stack-project.html           |  6 +++---
 docs/index.html                               |  4 ++--
 docs/search.json                              | 16 +++++++-------
 index.qmd                                     |  4 +++-
 47 files changed, 87 insertions(+), 467 deletions(-)
 delete mode 100644 _freeze/Chapters/01-base64/execute-results/epub.json
 delete mode 100644 _freeze/Chapters/01-memory/execute-results/epub.json
 delete mode 100644 _freeze/Chapters/01-zig-weird/execute-results/epub.json
 delete mode 100644 _freeze/Chapters/02-debugging/execute-results/epub.json
 delete mode 100644 _freeze/Chapters/03-structs/execute-results/epub.json
 delete mode 100644 _freeze/Chapters/03-unittests/execute-results/epub.json
 delete mode 100644 _freeze/Chapters/04-http-server/execute-results/epub.json
 delete mode 100644 _freeze/Chapters/07-build-system/execute-results/epub.json
 delete mode 100644 _freeze/Chapters/09-data-structures/execute-results/epub.json
 delete mode 100644 _freeze/Chapters/09-error-handling/execute-results/epub.json
 delete mode 100644 _freeze/Chapters/10-stack-project/execute-results/epub.json
 delete mode 100644 _freeze/Chapters/12-file-op/execute-results/epub.json
 delete mode 100644 _freeze/Chapters/13-image-filter/execute-results/epub.json
 delete mode 100644 _freeze/Chapters/14-threads/execute-results/epub.json
 delete mode 100644 _freeze/Chapters/14-zig-c-interop/execute-results/epub.json
 delete mode 100644 _freeze/Chapters/15-vectors/execute-results/epub.json
 delete mode 100644 _freeze/index/execute-results/epub.json
 delete mode 100644 _freeze/references/execute-results/epub.json

diff --git a/Chapters/03-structs.qmd b/Chapters/03-structs.qmd
index 56c67e00..3c1676e4 100644
--- a/Chapters/03-structs.qmd
+++ b/Chapters/03-structs.qmd
@@ -301,9 +301,22 @@ xsw: switch (@as(u8, 1)) {
 
 ### The `defer` keyword {#sec-defer}
 
-With the `defer` keyword you can register an expression to be executed when you exit the current scope.
-Therefore, this keyword has a similar functionality as the `on.exit()` function from R.
-Take the `foo()` function below as an example. When we execute this `foo()` function, the expression
+Zig has a `defer` keyword, which plays a very important role in control flow, and also, in releasing resources.
+In summary, the `defer` keyword allows you to register an expression to be executed when you exit the current scope.
+
+At this point, you might attempt to compare the Zig `defer` keyword to it's sibling in the Go language
+(i.e. [Go also has a `defer` keyword](https://go.dev/tour/flowcontrol/12)).
+However, the Go `defer` keyword behaves slightly different
+than it's sibling in Zig. More specifically, the `defer` keyword in Go always move an expression to be
+executed at the **exit of the current function**.
+
+If you think deeply about this statement, you will notice that the "exit of the current function" is something
+slightly different than the "exit of the current scope". So, just be careful when comparing the two
+keywords together. A single function in Zig might contain many different scopes inside of it, and, therefore,
+the `defer` input expression might be executed at different places of the function, depending on which scope you
+are currently in.
+
+As a first example, consider the `foo()` function exposed below. When we execute this `foo()` function, the expression
 that prints the message "Exiting function ..." is getting executed only when the function exits
 its scope.
 
diff --git a/Chapters/05-pointers.qmd b/Chapters/05-pointers.qmd
index f75cbe85..f82966d0 100644
--- a/Chapters/05-pointers.qmd
+++ b/Chapters/05-pointers.qmd
@@ -307,7 +307,7 @@ might point to a null value. This is a common source of undefined behaviour in C
 When programmers work with pointers in C, they have to constantly check if
 their pointers are pointing to null values or not.
 
-If for some reason, your Zig code produces a null value somewhere, and, this null
+In contrast, when working in Zig, if for some reason, your Zig code produces a null value somewhere, and, this null
 value ends up in an object that is non-nullable, a runtime error is always
 raised by your Zig program. Take the program below as an example.
 The `zig` compiler can see the `null` value at compile time, and, as result,
@@ -347,8 +347,9 @@ Ok, we know now that all objects are non-nullable by default in Zig.
 But what if we actually need to use an object that might receive a null value?
 Here is where optionals come in.
 
-An optional object in Zig is an object that can be null.
-To mark an object as optional, we use the `?` operator. When you put
+An optional object in Zig is rather similar to a [`std::optional` object in C++](https://en.cppreference.com/w/cpp/utility/optional.html).
+It is an object that can either contain a value, or nothing at all (a.k.a. the object can be null).
+To mark an object in our Zig code as "optional", we use the `?` operator. When you put
 this `?` operator right before the data type of an object, you transform
 this data type into an optional data type, and the object becomes an optional object.
 
diff --git a/_freeze/Chapters/01-base64/execute-results/epub.json b/_freeze/Chapters/01-base64/execute-results/epub.json
deleted file mode 100644
index 7dbf61d0..00000000
--- a/_freeze/Chapters/01-base64/execute-results/epub.json
+++ /dev/null
@@ -1,21 +0,0 @@
-{
-  "hash": "378ceb7f207e1c24d8ca75cf94cd22bf",
-  "result": {
-    "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Project 1 - Building a base64 encoder/decoder {#sec-base64}\n\nAs our first small project, I want to implement a base64 encoder/decoder with you.\nBase64 is an encoding system which translates binary data to text.\nA big chunk of the web uses base64 to deliver binary data to systems\nthat can only read text data.\n\nThe most common example of a modern use case for base64 is essentially any email system,\nlike GMail, Outlook, etc. Because email systems normally use\nthe Simple Mail Transfer Protocol (SMTP), which is a web protocol\nthat supports only text data. So, if you need, for any reason, to\nsend a binary file (like for example, a PDF, or an Excel file) as\nan attachment in your email, these binary files are normally\nconverted to base64, before they are included in the SMTP message.\nSo, the base64 encoding is largely used in these email systems to include\nbinary data into the SMTP message.\n\n\n\n\n\n\n## How the base64 algorithm work?\n\nBut how exactly does the algorithm behind the base64 encoding work? Let's discuss that. First, I will\nexplain the base64 scale, which is the 64-character scale that is the basis for\nthe base64 encoding system.\n\nAfter that, I explain the algorithm behind a base64 encoder, which is the part of the algorithm that is responsible for encoding messages\ninto the base64 encoding system. Then, after that, I explain the algorithm behind a base64 decoder, which is\nthe part of the algorithm that is responsible for translating base64 messages back into their original meaning.\n\nIf you are unsure about the differences between an \"encoder\" and a \"decoder\",\ntake a look at @sec-encode-vs-decode.\n\n\n### The base64 scale {#sec-base64-scale}\n\nThe base64 encoding system is based on a scale that goes from 0 to 63 (hence the name).\nEach index in this scale is represented by a character (it's a scale of 64 characters).\nSo, in order to convert some binary data, to the base64 encoding, we need to convert each binary number to the corresponding\ncharacter in this \"scale of 64 characters\".\n\nThe base64 scale starts with all ASCII uppercase letters (A to Z) which represents\nthe first 25 indexes in this scale (0 to 25). After that, we have all ASCII lowercase letters\n(a to z), which represents the range 26 to 51 in the scale. After that, we\nhave the one digit numbers (0 to 9), which represents the indexes from 52 to 61 in the scale.\nFinally, the last two indexes in the scale (62 and 63) are represented by the characters `+` and `/`,\nrespectively.\n\nThese are the 64 characters that compose the base64 scale. The equal sign character (`=`) is not part of the scale itself,\nbut it is a special character in the base64 encoding system. This character is used solely as a suffix, to mark the end of the character sequence,\nor, to mark the end of meaningful characters in the sequence.\n\nThe bullet points below summarises the base64 scale:\n\n- range 0 to 25 is represented by: ASCII uppercase letters `-> [A-Z]`;\n- range 26 to 51 is represented by: ASCII lowercase letters `-> [a-z]`;\n- range 52 to 61 is represented by: one digit numbers `-> [0-9]`;\n- index 62 and 63 are represented by the characters `+` and `/`, respectively;\n- the character `=` represents the end of meaningful characters in the sequence;\n\n\n\n\n### Creating the scale as a lookup table {#sec-base64-table}\n\nThe best way to represent this scale in code, is to represent it as a *lookup table*.\nLookup tables are a classic strategy in computer science to speed up calculations. The basic idea\nis to replace a runtime calculation (which can take a long time to be done) with a basic array indexing\noperation.\n\nInstead of calculating the results everytime you need them, you calculate all possible results at once, and then, you store them in an array\n(which behaves lake a \"table\"). Then, every time you need to use one of the characters in the base64 scale, instead of\nusing many resources to calculate the exact character to be used, you simply retrieve this character\nfrom the array where you stored all the possible characters in the base64 scale.\nWe retrieve the character that we need directly from memory.\n\nWe can start building a Zig struct to store our base64 decoder/encoder logic.\nWe start with the `Base64` struct below. For now, we only have one single data member in this\nstruct, i.e., the member `_table`, which represents our lookup table. We also have an `init()` method,\nto create a new instance of a `Base64` object, and, a `_char_at()` method, which is a\n\"get character at index $x$\" type of function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Base64 = struct {\n    _table: *const [64]u8,\n\n    pub fn init() Base64 {\n        const upper = \"ABCDEFGHIJKLMNOPQRSTUVWXYZ\";\n        const lower = \"abcdefghijklmnopqrstuvwxyz\";\n        const numbers_symb = \"0123456789+/\";\n        return Base64{\n            ._table = upper ++ lower ++ numbers_symb,\n        };\n    }\n\n    pub fn _char_at(self: Base64, index: usize) u8 {\n        return self._table[index];\n    }\n};\n```\n:::\n\n\n\n\nIn other words, the `_char_at()` method is responsible for getting the character in the lookup\ntable (i.e., the `_table` struct data member) that corresponds to a particular index in the\n\"base64 scale\". So, in the example below, we know that the character that corresponds to the\nindex 28 in the \"base64 scale\" is the character \"c\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst base64 = Base64.init();\ntry stdout.print(\n    \"Character at index 28: {c}\\n\",\n    .{base64._char_at(28)}\n);\n```\n:::\n\n\n\n```\nCharacter at index 28: c\n```\n\n\n\n### A base64 encoder {#sec-base64-encoder-algo}\n\nThe algorithm behind a base64 encoder usually works on a window of 3 bytes. Because each byte has\n8 bits, so, 3 bytes forms a set of $8 \\times 3 = 24$ bits. This is desirable for the base64 algorithm, because\n24 bits is divisible by 6, which forms $24 / 6 = 4$ groups of 6 bits each.\n\nTherefore, the base64 algorithm works by converting 3 bytes at a time\ninto 4 characters from the base64 scale. It keeps iterating through the input string,\n3 bytes at a time, and converting them into the base64 scale, producing 4 characters\nper iteration. It keeps iterating, and producing these \"new characters\"\nuntil it hits the end of the input string.\n\nNow you may think, what if you have a particular string that has a number of bytes\nthat is not divisible by 3 - what happens? For example, if you have a string\nthat contains only two characters/bytes, such as \"Hi\". How would the algorithm\nbehave in such situation? You find the answer in @fig-base64-algo1.\nYou can see in @fig-base64-algo1 that the string \"Hi\", when converted to base64,\nbecomes the string \"SGk=\":\n\n![The logic behind a base64 encoder](./../Figures/base64-encoder-flow.png){#fig-base64-algo1}\n\nTaking the string \"Hi\" as an example, we have 2 bytes, or, 16 bits in total. So, we lack a full byte (8 bits)\nto complete the window of 24 bits that the base64 algorithm likes to work on. The first thing that\nthe algorithm does, is to check how to divide the input bytes into groups of 6 bits.\n\nIf the algorithm notices that there is a group of 6 bits that it's not complete, meaning that, this group contains $nbits$, where $0 < nbits < 6$,\n\nthe algorithm simply adds extra zeros in this group to fill the space that it needs.\nThat is why in @fig-base64-algo1, in the third group after the 6-bit transformation,\n2 extra zeros were added to fill the gap.\n\nWhen we have a 6-bit group that is not completely full, like the third group, extra zeros\nare added to fill the gap. But what about when an entire 6-bit group is empty, or, it\nsimply doesn't exist? This is the case of the fourth 6-bit group exposed at\n@fig-base64-algo1.\n\nThis fourth group is necessary, because the algorithm works on 4 groups of 6 bits.\nBut the input string does not have enough bytes to create a fourth 6-bit group.\nEvery time this happens, where an entire group of 6 bits is empty,\nthis group becomes a \"padding group\". Every \"padding group\" is mapped to\nthe character `=` (equal sign), which represents \"null\", or, the end\nof meaningful characters in the sequence. Hence, everytime that the algorithm produces a\n\"padding group\", this group is automatically mapped to `=`.\n\nAs another example, if you give the string \"0\" as input to a base64 encoder, this string is\ntranslated into the base64 sequence \"MA==\".\nThe character \"0\" is, in binary, the sequence `00110000`[^zero-note]. So, with the 6-bit transformation\nexposed in @fig-base64-algo1, this single character would produce these two 6-bit groups: `001100`, `000000`.\nThe remaining two 6-bit groups become \"padding groups\". That is why the last\ntwo characters in the output sequence (MA==) are `==`.\n\n\n[^zero-note]: Notice that, the character \"0\" is different than the actual number 0, which is simply zero in binary.\n\n### A base64 decoder {#sec-base64-decoder-algo}\n\nThe algorithm behind a base64 decoder is essentially the inverse process of a base64 encoder.\nA base64 decoder needs to translate base64 messages back into their original meaning,\ni.e., into the original sequence of binary data.\n\nA base64 decoder usually works on a window of 4 bytes. Because it wants to convert these 4 bytes\nback into the original sequence of 3 bytes, that was converted into 4 groups of 6 bits by the\nbase64 encoder. Remember, in a base64 decoder we are essentially reverting the process made\nby the base64 encoder.\n\nEach byte in the input string (the base64 encoded string) normally contributes to re-create\ntwo different bytes in the output (the original binary data).\nIn other words, each byte that comes out of a base64 decoder is created by transforming merging two different\nbytes in the input together. You can visualize this relationship in @fig-base64-algo2:\n\n![The logic behind a base64 decoder](./../Figures/base64-decoder-flow.png){#fig-base64-algo2}\n\nThe exact transformations, or, the exact steps applied to each byte from the input to transform them\ninto the bytes of the output, are a bit tricky to visualize in a figure like this. Because of that, I have\nsummarized these transformations as \"Some bit shifting and additions ...\" in the figure. These transformations\nwill be described in depth later.\n\nBesides that, if you look again in @fig-base64-algo2, you will notice that the character `=` was completely\nignored by the algorithm. Remember, this is just a special character that marks the end of meaningful characters\nin the base64 sequence. So, every `=` character in a base64 encoded sequence should be ignored by a base64 decoder.\n\n\n## Difference between encode and decode {#sec-encode-vs-decode}\n\nIf you don't have any previous experience with base64, you might not understand the differences\nbetween \"encode\" and \"decode\". Essentially, the terms \"encode\" and \"decode\" here\nhave the exact same meaning as they have in the field of encryption (i.e., they mean the same thing as \"encode\" and \"decode\" in hashing\nalgorithms, like the MD5 algorithm).\n\nThus, \"encode\" means that we want to encode, or, in other words, we want to translate some message into\nthe base64 encoding system. We want to produce the sequence of base64 characters that represent this\noriginal message in the base64 encoding system.\n\nIn contrast, \"decode\" represents the inverse process.\nWe want to decode, or, in other words, translate a base64 message back to its original content.\nSo, in this process we get a sequence of base64 characters as input, and produce as output,\nthe binary data that is represented by this sequence of base64 characters.\n\nAny base64 library is normally composed of these two parts: 1) the encoder, which is a function that encodes\n(i.e., it converts) any sequence of binary data into a sequence of base64 characters; 2) the decoder, which is a function\nthat converts a sequence of base64 characters back into the original sequence of binary data.\n\n\n\n## Calculating the size of the output {#sec-base64-length-out}\n\nOne task that we need to do is to calculate how much space we need to reserve for the\noutput, both of the encoder and decoder. This is simple math, and can be done easily in Zig\nbecause every array has its length (its number of elements) easily accesible by consulting\nthe `.len` property of the array.\n\nFor the encoder, the logic is the following: for each 3 bytes that we find in the input,\n4 new bytes are created in the output. So, we take the number of bytes in the input, divide it\nby 3, use a ceiling function, then, we multiply the result by 4. That way, we get the total\nnumber of bytes that will be produced by the encoder in its output.\n\nThe `_calc_encode_length()` function below encapsulates this logic.\nInside this function, we take the length of the input array,\nwe divide it by 3, and apply a ceil operation over the result by using the\n`divCeil()` function from the Zig Standard Library. Lastly, we multiply\nthe end result by 4 to get the answer we need.\n\nAlso, you might have notice that, if the input length is less than 3 bytes, then, the output length of the encoder is\nalways 4 bytes. This is the case for every input with less than 3 bytes, because, as I described in @sec-base64-encoder-algo,\nthe algorithm always produces enough \"padding-groups\" in the end result, to complete the 4 bytes window.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_encode_length(input: []const u8) !usize {\n    if (input.len < 3) {\n        return 4;\n    }\n    const n_groups: usize = try std.math.divCeil(\n        usize, input.len, 3\n    );\n    return n_groups * 4;\n}\n```\n:::\n\n\n\n\nNow, the logic to calculate the length of the output from the decoder is a little bit more complicated. But, it is basically\njust the inverse logic that we've used for the encoder: for each 4 bytes in the input, 3 bytes\nwill be produced in the output of the decoder. However, this time we need to\ntake the `=` character into account, which is always ignored by the decoder, as we described in @sec-base64-decoder-algo, and,\nin @fig-base64-algo2.\n\nIn essence, we take the length of the input and divide it by 4, then we apply a floor function on the result, then\nwe multiply the result by 3, and then, we subtract from the result how much times the character `=` is found\nin the input.\n\nThe function `_calc_decode_length()` exposed below summarizes this logic that we described. It's similar\nto the function `_calc_encode_length()`. Notice that the division part is twisted. Also notice that this time, we apply\na floor operation over the output of the division, by using the `divFloor()`\nfunction (instead of a ceiling operation with `divCeil()`).\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_decode_length(input: []const u8) !usize {\n    if (input.len < 4) {\n        return 3;\n    }\n\n    const n_groups: usize = try std.math.divFloor(\n        usize, input.len, 4\n    );\n    var multiple_groups: usize = n_groups * 3;\n    var i: usize = input.len - 1;\n    while (i > 0) : (i -= 1) {\n        if (input[i] == '=') {\n            multiple_groups -= 1;\n        } else {\n            break;\n        }\n    }\n\n    return multiple_groups;\n}\n```\n:::\n\n\n\n\n## Building the encoder logic {#sec-encoder-logic}\n\nIn this section, we can start building the logic behind the `encode()` function, which\nwill be responsible for encoding messages into the base64 encoding system.\nIf you are an anxious person, and you want to see now the full source code of the implementation\nfor this base64 encoder/decoder, you can find it at the `ZigExamples` folder in the official repository of\nthis book[^zig-base64-algo].\n\n[^zig-base64-algo]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/base64/base64_basic.zig>.\n\n\n\n### The 6-bit transformation {#sec-6bit-transf}\n\nThe 6-bit transformation presented in @fig-base64-algo1 is the core part of the base64 encoder algorithm.\nBy understanding how this transformation is made in code, the rest of the algorithm becomes much simpler\nto comprehend.\n\nIn essence, this 6-bit transformation is made with the help of bitwise operators.\nBitwise operators are essential to any type of low-level operation that is done at the bit-level. For the specific case of the base64 algorithm,\nthe operators *bif shift to the left* (`<<`), *bit shift to the right* (`>>`), and the *bitwise and* (`&`) are used. They\nare the core solution for the 6-bit transformation.\n\nThere are 3 different scenarios that we need to take into account in this transformation. First, is the perfect scenario,\nwhere we have the perfect window of 3 bytes to work on. Second, we have the scenario where we have a window of only\ntwo bytes to work with. And last, we have the scenario where we have a window of one single byte.\n\nIn each of these 3 scenarios, the 6-bit transformation works a bit differently. To make the explanation\neasier, I will use the variable `output` to refer to the bytes in the output of the base64 encoder,\nand the variable `input` to refer to the bytes in the input of the encoder.\n\n\nSo, if you have the perfect window of 3 bytes, these are steps for the 6-bit transformation:\n\n1. `output[0]` is produced by moving the bits from `input[0]` two positions to the right.\n1. `output[1]` is produced by summing two components. First, take the last two bits from `input[0]`, then, move them four positions to the left. Second, move the bits from `input[1]` four positions to the right. Sum these two components.\n1. `output[2]` is produced by summing two components. First, take the last four bits from `input[1]`, then, move them two positions to the left. Second, move the bits from `input[2]` six positions to the right. Sum these two components.\n1. `output[3]` is produced by taking the last six bits from `input[2]`.\n\n\nThis is the perfect scenario, where we have a full window of 3 bytes to work on.\nJust to make things as clear as possible, the @fig-encoder-bitshift demonstrates visually how\nthe step 2 mentioned above works. So the 2nd byte in the `output` of the encoder, is made by taking the 1st byte (dark purple)\nand the 2nd byte (orange) from the input. You can see that, at the end of the process, we get a new\nbyte that contains the last 2 bits from the 1st byte in the `input`, and the first 4 bits\nfrom the 2nd byte in the `input`.\n\n![How the 2nd byte in the output of the encoder is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input.](../Figures/base64-encoder-bit-shift.png){#fig-encoder-bitshift}\n\nOn the other hand, we must be prepared for the instances where we do not have the perfect window of 3 bytes.\nIf you have a window of 2 bytes, then, the steps 3 and 4, which produces the bytes `output[2]` and `output[3]`, change a little bit,\nand they become:\n\n- `output[2]` is produced by taking the last 4 bits from `input[1]`, then, move them two positions to the left.\n- `output[3]` is the character `'='`.\n\n\nFinally, if you have a window of a single byte, then, the steps 2 to 4, which produces the bytes `output[1]`, `output[2]` and `output[3]` change,\nbecoming:\n\n- `output[1]` is produced by taking the last two bits from `input[0]`, then, move them four positions to the left.\n- `output[2]` and `output[3]` are the character `=`.\n\n\nIf these bullet points were a bit confusing for you, you may find the @tbl-transf-6bit more intuitive.\nThis table unifies all this logic into a simple table. Notice that\nthis table also provides the exact expression in Zig that creates the corresponding\nbyte in the output.\n\n\n::: {#tbl-transf-6bit}\n\n| Number of bytes in the window | Byte index in the output | In code                                    |\n|-------------------------------|--------------------------|--------------------------------------------|\n| 3                             | 0                        | input[0] >> 2                              |\n| 3                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 3                             | 2                        | ((input[1] & 0x0f) << 2) + (input[2] >> 6) |\n| 3                             | 3                        | input[2] & 0x3f                            |\n| 2                             | 0                        | input[0] >> 2                              |\n| 2                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 2                             | 2                        | ((input[1] & 0x0f) << 2)                   |\n| 2                             | 3                        | '='                                        |\n| 1                             | 0                        | input[0] >> 2                              |\n| 1                             | 1                        | ((input[0] & 0x03) << 4)                   |\n| 1                             | 2                        | '='                                        |\n| 1                             | 3                        | '='                                        |\n\n: How the 6-bit transformation translates into code in different window settings.\n\n:::\n\n\n\n\n\n\n### Bit-shifting in Zig\n\nBit-shifting in Zig works similarly to bit-shifting in C.\nAll bitwise operators that exist in C are available in Zig.\nHere, in the base64 encoder algorithm, they are essential\nto produce the result we want.\n\nFor those who are not familiar with these operators, they are\noperators that operates at the bit-level of your values.\nThis means that these operators takes the bits that form the value\nyou have, and change them in some way. This ultimately also changes\nthe value itself, because the binary representation of this value\nchanges.\n\nWe have already seen in @fig-encoder-bitshift the effect produced by a bit-shift.\nBut let's use the first byte in the output of the base64 encoder as another example of what\nbit-shifting means. This is the easiest byte of the 4 bytes in the output\nto build. Because we only need to move the bits from the first byte in the input two positions to the right,\nwith the *bit shift to the right* (`>>`) operator.\n\nIf we take the string \"Hi\" that we used in @fig-base64-algo1 as an example, the first byte in\nthis string is \"H\", which is the sequence `01001000` in binary.\nIf we move the bits of this byte, two places to the right, we get the sequence `00010010` as result.\nThis binary sequence is the value `18` in decimal, and also, the value `0x12` in hexadecimal.\nNotice that the first 6 bits of \"H\" were moved to the end of the byte.\nWith this operation, we get the first byte of the output.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const input = \"Hi\";\n    try stdout.print(\"{d}\\n\", .{input[0] >> 2});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n18\n```\n\n\n:::\n:::\n\n\n\nIf you recall @fig-base64-algo1, the first byte present in the output should\nbe equivalent to the 6-bit group `010010`. Although being visually different, the\nsequences `010010` and `00010010` are semantically equal. They mean the same thing.\nThey both represent the number 18 in decimal, and the value `0x12` in hexadecimal.\n\nSo, don't take the \"6-bit group\" factor so seriously. We do not need necessarily to\nget a 6-bit sequence as result. As long as the meaning of the 8-bit sequence we get is the same\nof the 6-bit sequence, we are in the clear.\n\n\n\n### Selecting specific bits with the `&` operator\n\nIf you comeback to @sec-6bit-transf, you will see that, in order to produce\nthe second and third bytes in the output, we need to select specific\nbits from the first and second bytes in the input string. But how\ncan we do that? The answer relies on the *bitwise and* (`&`) operator.\n\nThe @fig-encoder-bitshift already showed you what effect this `&` operator\nproduces in the bits of its operands. But let's make a clear description of it.\n\nIn summary, the `&` operator performs a logical conjunction operation\nbetween the bits of its operands. In more details, the operator `&`\ncompares each bit of the first operand to the corresponding bit of the second operand.\nIf both bits are 1, the corresponding result bit is set to 1.\nOtherwise, the corresponding result bit is set to 0 [@microsoftbitwiseand].\n\nSo, if we apply this operator to the binary sequences `1000100` and `00001101`\nthe result of this operation is the binary sequence `00000100`. Because only\nat the sixth position in both binary sequences we had a 1 value. So any\nposition where we do not have both binary sequences setted to 1, we get\na 0 bit in the resulting binary sequence.\n\nWe lose information about the original bit values\nfrom both sequences in this case. Because we no longer know\nif this 0 bit in the resulting binary sequence was produced by\ncombining 0 with 0, or 1 with 0, or 0 with 1.\n\nAs an example, suppose you have the binary sequence `10010111`, which is the number 151 in decimal. How\ncan we get a new binary sequence which contains only the third and\nfourth bits of this sequence?\n\nWe just need to combine this sequence with `00110000` (is `0x30` in hexadecimal) using the `&` operator.\nNotice that only the third and fourth positions in this binary sequence is setted to 1. As a consequence, only the\nthird and fourth values of both binary sequences are potentially preserved in the output. All the remaining positions\nare setted to zero in the output sequence, which is `00010000` (is the number 16 in decimal).\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const bits = 0b10010111;\n    try stdout.print(\"{d}\\n\", .{bits & 0b00110000});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n16\n```\n\n\n:::\n:::\n\n\n\n\n\n### Allocating space for the output\n\nAs I described in @sec-stack, to store an object in the stack,\nthis object needs to have a known and fixed length at compile-time. This is an important\nlimitation for our base64 encoder/decoder case. Because the size of\nthe output (from both the encoder and decoder) depends\ndirectly on the size of the input.\n\nHaving this in mind, we cannot know at compile time which is\nthe size of the output for both the encoder and decoder.\nSo, if we can't know the size of the output at compile time,\nthis means that we cannot store the output for both the encoder\nand decoder in the stack.\n\nConsequently, we need to store this output on the heap,\nand, as I commented in @sec-heap, we can only\nstore objects in the heap by using allocator objects.\nSo, one the arguments to both the `encode()` and `decode()`\nfunctions, needs to be an allocator object, because\nwe know for sure that, at some point inside the body of these\nfunctions, we need to allocate space on the heap to\nstore the output of these functions.\n\nThat is why, both the `encode()` and `decode()` functions that I\npresent in this book, have an argument called `allocator`,\nwhich receives a allocator object as input, identified by\nthe type `std.mem.Allocator` from the Zig Standard Library.\n\n\n\n### Writing the `encode()` function\n\nNow that we have a basic understanding on how the bitwise operators work, and how\nexactly they help us to achieve the result we want to achieve. We can now encapsulate\nall the logic that we have described in @fig-base64-algo1 and @tbl-transf-6bit into a nice\nfunction that we can add to our `Base64` struct definition, that we started in @sec-base64-table.\n\nYou can find the `encode()` function below. Notice that the first argument of this function,\nis the `Base64` struct itself. Therefore, this argument clearly signals\nthat this function is a method from the `Base64` struct.\n\nBecause the `encode()` function itself is fairly long,\nI intentionally omitted the `Base64` struct definition in this source code,\njust for brevity reasons. So, just remember that this function is a public function (or a public method) from the\n`Base64` struct.\n\nFurthermore, this `encode()` function has two other arguments:\n\n1. `input` is the input sequence of characters that you want to encode in base64;\n1. `allocator` is an allocator object to use in the necessary memory allocations.\n\nI described everything you need to know about allocator objects in @sec-allocators.\nSo, if you are not familiar with them, I highly recommend you to comeback to\nthat section, and read it.\nBy looking at the `encode()` function, you will see that we use this\nallocator object to allocate enough memory to store the output of\nthe encoding process.\n\nThe main for loop in the function is responsible for iterating through the entire input string.\nIn every iteration, we use a `count` variable to count how many iterations we had at the\nmoment. When `count` reaches 3, then, we try to encode the 3 characters (or bytes) that we have accumulated\nin the temporary buffer object (`buf`).\n\nAfter encoding these 3 characters and storing the result in the `output` variable, we reset\nthe `count` variable to zero, and start to count again on the next iteration of the loop.\nIf the loop hits the end of the string, and, the `count` variable is less than 3, then, it means that\nthe temporary buffer contains the last 1 or 2 bytes from the input.\nThat is why we have two `if` statements after the for loop. To deal which each possible case.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn encode(self: Base64,\n              allocator: std.mem.Allocator,\n              input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n\n    const n_out = try _calc_encode_length(input);\n    var out = try allocator.alloc(u8, n_out);\n    var buf = [3]u8{ 0, 0, 0 };\n    var count: u8 = 0;\n    var iout: u64 = 0;\n\n    for (input, 0..) |_, i| {\n        buf[count] = input[i];\n        count += 1;\n        if (count == 3) {\n            out[iout] = self._char_at(buf[0] >> 2);\n            out[iout + 1] = self._char_at(\n                ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n            );\n            out[iout + 2] = self._char_at(\n                ((buf[1] & 0x0f) << 2) + (buf[2] >> 6)\n            );\n            out[iout + 3] = self._char_at(buf[2] & 0x3f);\n            iout += 4;\n            count = 0;\n        }\n    }\n\n    if (count == 1) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            (buf[0] & 0x03) << 4\n        );\n        out[iout + 2] = '=';\n        out[iout + 3] = '=';\n    }\n\n    if (count == 2) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n        );\n        out[iout + 2] = self._char_at(\n            (buf[1] & 0x0f) << 2\n        );\n        out[iout + 3] = '=';\n        iout += 4;\n    }\n\n    return out;\n}\n```\n:::\n\n\n\n\n\n## Building the decoder logic {#sec-decoder-logic}\n\nNow, we can focus on writing the base64 decoder logic. Remember from @fig-base64-algo2 that,\na base64 decoder does the inverse process of an encoder. So, all we need to do, is to\nwrite a `decode()` function that performs the inverse process that I exposed in @sec-encoder-logic.\n\n\n### Mapping base64 characters to their indexes {#sec-map-base64-index}\n\nOne thing that we need to do, in order to decode a base64-encoded message, is to calculate\nthe index in the base64 scale of every base64 character that we encounter in the decoder input.\n\nIn other words, the decoder receives as input, a sequence of base64 characters. We need\nto translate this sequence of characters into a sequence of indexes. These indexes\nare the index of each character in the base64 scale. This way, we get the value/byte\nthat was calculated in the 6-bit transformation step of the encoder process.\n\nThere are probably better/faster ways to calculate this, especially using a \"divide and conquer\"\ntype of strategy. But for now, I am satisfied with a simple and \"brute force\" type of strategy.\nThe `_char_index()` function below contains this strategy.\n\nWe are essentially looping through the *lookup table* with the base64 scale,\nand comparing the character we got with each character in the base64 scale.\nIf these characters match, then, we return the index of this character in the\nbase64 scale as the result.\n\nNotice that, if the input character is `'='`, the function returns the index 64, which is\n\"out of range\" in the scale. But, as I described in @sec-base64-scale,\nthe character `'='` does not belong to the base64 scale itself.\nIt's a special and meaningless character in base64.\n\nAlso notice that this `_char_index()` function is a method from our `Base64` struct,\nbecause of the `self` argument. Again, I have omitted the `Base64` struct definition in this example\nfor brevity reasons.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn _char_index(self: Base64, char: u8) u8 {\n    if (char == '=')\n        return 64;\n    var index: u8 = 0;\n    for (0..63) |i| {\n        if (self._char_at(i) == char)\n            break;\n        index += 1;\n    }\n\n    return index;\n}\n```\n:::\n\n\n\n\n\n### The 6-bit transformation\n\nOnce again, the core part of the algorithm is the 6-bit transformation.\nIf we understand the necessary steps to perform this transformation, the rest\nof the algorithm becomes much easier.\n\nFirst of all, before we actually go to the 6-bit transformation,\nwe need to make sure that we use `_char_index()` to convert the sequence of base64 characters\ninto a sequence of indexes. So the snippet below is important for the job that will be done.\nThe result of `_char_index()` is stored in a temporary buffer, and this temporary buffer\nis what we are going to use in the 6-bit transformation, instead of the actual `input` object.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (0..input.len) |i| {\n    buf[i] = self._char_index(input[i]);\n}\n```\n:::\n\n\n\nNow, instead of producing 4 bytes (or 4 characters) as output per each window of 3 characters in the input,\na base64 decoder produces 3 bytes (or 3 characters) as output per each window of 4 characters in the input.\nOnce again, is the inverse process.\n\nSo, the steps to produce the 3 bytes in the output are:\n\n1. `output[0]` is produced by summing two components. First, move the bits from `buf[0]` two positions to the left. Second, move the bits from `buf[1]` 4 positions to the right. Then, sum these two components.\n1. `output[1]` is produced by summing two components. First, move the bits from `buf[1]` four positions to the left. Second, move the bits from `buf[2]` 2 positions to the right. Then, sum these two components.\n1. `output[2]` is produced by summing two components. First, move the bits from `buf[2]` six positions to the left. Then, you sum the result with `buf[3]`.\n\n\nBefore we continue, let's try to visualize how these transformations make the original bytes that we had\nbefore the encoding process. First, think back to the 6-bit transformation performed by the encoder exposed in @sec-encoder-logic.\nThe first byte in the output of the encoder is produced by moving the bits in the first byte of the input two positions to the right.\n\nIf for example the first byte in the input of the encoder was the sequence `ABCDEFGH`, then, the first byte in the output of the encoder would be\n`00ABCDEF` (this sequence would be the first byte in the input of the decoder). Now, if the second byte in the input of the encoder was the sequence\n`IJKLMNOP`, then, the second byte in the encoder output would be `00GHIJKL` (as we demonstrated in @fig-encoder-bitshift).\n\nHence, if the sequences `00ABCDEF` and `00GHIJKL` are the first and second bytes, respectively, in the input of the decoder, the\n@fig-decoder-bitshift demonstrates visually how these two bytes are transformed into the first byte of the output of the decoder.\nNotice that the output byte is the sequence `ABCDEFGH`, which is the original byte from the input of the encoder.\n\n![How the 1st byte in the decoder output is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input](../Figures/base64-decoder-bit-shift.png){#fig-decoder-bitshift}\n\nThe @tbl-6bit-decode presents how the three steps described earlier translate into Zig code:\n\n\n\n::: {#tbl-6bit-decode}\n\n| Byte index in the output | In code                       |\n|--------------------------|-------------------------------|\n| 0                        | (buf[0] << 2) + (buf[1] >> 4) |\n| 1                        | (buf[1] << 4) + (buf[2] >> 2) |\n| 2                        | (buf[2] << 6) + buf[3]        |\n\n: The necessary steps for the 6-transformation in the decode process.\n\n\n:::\n\n\n\n\n\n\n\n### Writing the `decode()` function\n\nThe `decode()` function below contains the entire decoding process.\nWe first calculate the size of the output, with\n`_calc_decode_length()`, then, we allocate enough memory for this output with\nthe allocator object.\n\nThree temporary variables are created: 1) `count`, to hold the window count\nin each iteration of the for loop; 2) `iout`, to hold the current index in the output;\n3) `buf`, which is the temporary buffer that holds the base64 indexes to be\nconverted through the 6-bit transformation.\n\nThen, in each iteration of the for loop we fill the temporary buffer with the current\nwindow of bytes. When `count` hits the number 4, then, we have a full window of\nindexes in `buf` to be converted, and then, we apply the 6-bit transformation\nover the temporary buffer.\n\nNotice that we check if the indexes 2 and 3 in the temporary buffer are the number 64, which, if you recall\nfrom @sec-map-base64-index, is when the `_calc_index()` function receives a `'='` character\nas input. So, if these indexes are equal to the number 64, the `decode()` function knows\nthat it can simply ignore these indexes. They are not converted because, as I described before,\nthe character `'='` has no meaning, despite being the end of meaningful characters in the sequence.\nSo we can safely ignore them when they appear in the sequence.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn decode(self: Base64,\n          allocator: std.mem.Allocator,\n          input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n    const n_output = try _calc_decode_length(input);\n    var output = try allocator.alloc(u8, n_output);\n    var count: u8 = 0;\n    var iout: u64 = 0;\n    var buf = [4]u8{ 0, 0, 0, 0 };\n\n    for (0..input.len) |i| {\n        buf[count] = self._char_index(input[i]);\n        count += 1;\n        if (count == 4) {\n            output[iout] = (buf[0] << 2) + (buf[1] >> 4);\n            if (buf[2] != 64) {\n                output[iout + 1] = (buf[1] << 4) + (buf[2] >> 2);\n            }\n            if (buf[3] != 64) {\n                output[iout + 2] = (buf[2] << 6) + buf[3];\n            }\n            iout += 3;\n            count = 0;\n        }\n    }\n\n    return output;\n}\n```\n:::\n\n\n\n\n## The end result\n\nNow that we have both `decode()` and `encode()` implemented. We have a fully functioning\nbase64 encoder/decoder implemented in Zig. Here is an usage example of our\n`Base64` struct with the `encode()` and `decode()` methods that we have implemented.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar memory_buffer: [1000]u8 = undefined;\nvar fba = std.heap.FixedBufferAllocator.init(\n    &memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst text = \"Testing some more stuff\";\nconst etext = \"VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=\";\nconst base64 = Base64.init();\nconst encoded_text = try base64.encode(\n    allocator, text\n);\nconst decoded_text = try base64.decode(\n    allocator, etext\n);\ntry stdout.print(\n    \"Encoded text: {s}\\n\", .{encoded_text}\n);\ntry stdout.print(\n    \"Decoded text: {s}\\n\", .{decoded_text}\n);\n```\n:::\n\n\n\n```\nEncoded text: VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=\nDecoded text: Testing some more stuff\n```\n\nYou can also see the full source code at once, by visiting the official repository of this book[^repo].\nMore precisely inside the `ZigExamples` folder[^zig-base64-algo].\n\n[^repo]: <https://github.com/pedropark99/zig-book>\n",
-    "supporting": [
-      "01-base64_files"
-    ],
-    "filters": [
-      "rmarkdown/pagebreak.lua"
-    ],
-    "includes": {},
-    "engineDependencies": {
-      "knitr": [
-        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
-      ]
-    },
-    "preserve": null,
-    "postProcess": false
-  }
-}
\ No newline at end of file
diff --git a/_freeze/Chapters/01-base64/execute-results/html.json b/_freeze/Chapters/01-base64/execute-results/html.json
index 7f1a2b90..875237c5 100644
--- a/_freeze/Chapters/01-base64/execute-results/html.json
+++ b/_freeze/Chapters/01-base64/execute-results/html.json
@@ -2,10 +2,8 @@
   "hash": "378ceb7f207e1c24d8ca75cf94cd22bf",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 1 - Building a base64 encoder/decoder {#sec-base64}\n\nAs our first small project, I want to implement a base64 encoder/decoder with you.\nBase64 is an encoding system which translates binary data to text.\nA big chunk of the web uses base64 to deliver binary data to systems\nthat can only read text data.\n\nThe most common example of a modern use case for base64 is essentially any email system,\nlike GMail, Outlook, etc. Because email systems normally use\nthe Simple Mail Transfer Protocol (SMTP), which is a web protocol\nthat supports only text data. So, if you need, for any reason, to\nsend a binary file (like for example, a PDF, or an Excel file) as\nan attachment in your email, these binary files are normally\nconverted to base64, before they are included in the SMTP message.\nSo, the base64 encoding is largely used in these email systems to include\nbinary data into the SMTP message.\n\n\n\n\n\n\n## How the base64 algorithm work?\n\nBut how exactly does the algorithm behind the base64 encoding work? Let's discuss that. First, I will\nexplain the base64 scale, which is the 64-character scale that is the basis for\nthe base64 encoding system.\n\nAfter that, I explain the algorithm behind a base64 encoder, which is the part of the algorithm that is responsible for encoding messages\ninto the base64 encoding system. Then, after that, I explain the algorithm behind a base64 decoder, which is\nthe part of the algorithm that is responsible for translating base64 messages back into their original meaning.\n\nIf you are unsure about the differences between an \"encoder\" and a \"decoder\",\ntake a look at @sec-encode-vs-decode.\n\n\n### The base64 scale {#sec-base64-scale}\n\nThe base64 encoding system is based on a scale that goes from 0 to 63 (hence the name).\nEach index in this scale is represented by a character (it's a scale of 64 characters).\nSo, in order to convert some binary data, to the base64 encoding, we need to convert each binary number to the corresponding\ncharacter in this \"scale of 64 characters\".\n\nThe base64 scale starts with all ASCII uppercase letters (A to Z) which represents\nthe first 25 indexes in this scale (0 to 25). After that, we have all ASCII lowercase letters\n(a to z), which represents the range 26 to 51 in the scale. After that, we\nhave the one digit numbers (0 to 9), which represents the indexes from 52 to 61 in the scale.\nFinally, the last two indexes in the scale (62 and 63) are represented by the characters `+` and `/`,\nrespectively.\n\nThese are the 64 characters that compose the base64 scale. The equal sign character (`=`) is not part of the scale itself,\nbut it is a special character in the base64 encoding system. This character is used solely as a suffix, to mark the end of the character sequence,\nor, to mark the end of meaningful characters in the sequence.\n\nThe bullet points below summarises the base64 scale:\n\n- range 0 to 25 is represented by: ASCII uppercase letters `-> [A-Z]`;\n- range 26 to 51 is represented by: ASCII lowercase letters `-> [a-z]`;\n- range 52 to 61 is represented by: one digit numbers `-> [0-9]`;\n- index 62 and 63 are represented by the characters `+` and `/`, respectively;\n- the character `=` represents the end of meaningful characters in the sequence;\n\n\n\n\n### Creating the scale as a lookup table {#sec-base64-table}\n\nThe best way to represent this scale in code, is to represent it as a *lookup table*.\nLookup tables are a classic strategy in computer science to speed up calculations. The basic idea\nis to replace a runtime calculation (which can take a long time to be done) with a basic array indexing\noperation.\n\nInstead of calculating the results everytime you need them, you calculate all possible results at once, and then, you store them in an array\n(which behaves lake a \"table\"). Then, every time you need to use one of the characters in the base64 scale, instead of\nusing many resources to calculate the exact character to be used, you simply retrieve this character\nfrom the array where you stored all the possible characters in the base64 scale.\nWe retrieve the character that we need directly from memory.\n\nWe can start building a Zig struct to store our base64 decoder/encoder logic.\nWe start with the `Base64` struct below. For now, we only have one single data member in this\nstruct, i.e., the member `_table`, which represents our lookup table. We also have an `init()` method,\nto create a new instance of a `Base64` object, and, a `_char_at()` method, which is a\n\"get character at index $x$\" type of function.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Base64 = struct {\n    _table: *const [64]u8,\n\n    pub fn init() Base64 {\n        const upper = \"ABCDEFGHIJKLMNOPQRSTUVWXYZ\";\n        const lower = \"abcdefghijklmnopqrstuvwxyz\";\n        const numbers_symb = \"0123456789+/\";\n        return Base64{\n            ._table = upper ++ lower ++ numbers_symb,\n        };\n    }\n\n    pub fn _char_at(self: Base64, index: usize) u8 {\n        return self._table[index];\n    }\n};\n```\n:::\n\n\n\n\n\nIn other words, the `_char_at()` method is responsible for getting the character in the lookup\ntable (i.e., the `_table` struct data member) that corresponds to a particular index in the\n\"base64 scale\". So, in the example below, we know that the character that corresponds to the\nindex 28 in the \"base64 scale\" is the character \"c\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst base64 = Base64.init();\ntry stdout.print(\n    \"Character at index 28: {c}\\n\",\n    .{base64._char_at(28)}\n);\n```\n:::\n\n\n\n\n```\nCharacter at index 28: c\n```\n\n\n\n### A base64 encoder {#sec-base64-encoder-algo}\n\nThe algorithm behind a base64 encoder usually works on a window of 3 bytes. Because each byte has\n8 bits, so, 3 bytes forms a set of $8 \\times 3 = 24$ bits. This is desirable for the base64 algorithm, because\n24 bits is divisible by 6, which forms $24 / 6 = 4$ groups of 6 bits each.\n\nTherefore, the base64 algorithm works by converting 3 bytes at a time\ninto 4 characters from the base64 scale. It keeps iterating through the input string,\n3 bytes at a time, and converting them into the base64 scale, producing 4 characters\nper iteration. It keeps iterating, and producing these \"new characters\"\nuntil it hits the end of the input string.\n\nNow you may think, what if you have a particular string that has a number of bytes\nthat is not divisible by 3 - what happens? For example, if you have a string\nthat contains only two characters/bytes, such as \"Hi\". How would the algorithm\nbehave in such situation? You find the answer in @fig-base64-algo1.\nYou can see in @fig-base64-algo1 that the string \"Hi\", when converted to base64,\nbecomes the string \"SGk=\":\n\n![The logic behind a base64 encoder](./../Figures/base64-encoder-flow.png){#fig-base64-algo1}\n\nTaking the string \"Hi\" as an example, we have 2 bytes, or, 16 bits in total. So, we lack a full byte (8 bits)\nto complete the window of 24 bits that the base64 algorithm likes to work on. The first thing that\nthe algorithm does, is to check how to divide the input bytes into groups of 6 bits.\n\nIf the algorithm notices that there is a group of 6 bits that it's not complete, meaning that, this group contains $nbits$, where $0 < nbits < 6$,\n\nthe algorithm simply adds extra zeros in this group to fill the space that it needs.\nThat is why in @fig-base64-algo1, in the third group after the 6-bit transformation,\n2 extra zeros were added to fill the gap.\n\nWhen we have a 6-bit group that is not completely full, like the third group, extra zeros\nare added to fill the gap. But what about when an entire 6-bit group is empty, or, it\nsimply doesn't exist? This is the case of the fourth 6-bit group exposed at\n@fig-base64-algo1.\n\nThis fourth group is necessary, because the algorithm works on 4 groups of 6 bits.\nBut the input string does not have enough bytes to create a fourth 6-bit group.\nEvery time this happens, where an entire group of 6 bits is empty,\nthis group becomes a \"padding group\". Every \"padding group\" is mapped to\nthe character `=` (equal sign), which represents \"null\", or, the end\nof meaningful characters in the sequence. Hence, everytime that the algorithm produces a\n\"padding group\", this group is automatically mapped to `=`.\n\nAs another example, if you give the string \"0\" as input to a base64 encoder, this string is\ntranslated into the base64 sequence \"MA==\".\nThe character \"0\" is, in binary, the sequence `00110000`[^zero-note]. So, with the 6-bit transformation\nexposed in @fig-base64-algo1, this single character would produce these two 6-bit groups: `001100`, `000000`.\nThe remaining two 6-bit groups become \"padding groups\". That is why the last\ntwo characters in the output sequence (MA==) are `==`.\n\n\n[^zero-note]: Notice that, the character \"0\" is different than the actual number 0, which is simply zero in binary.\n\n### A base64 decoder {#sec-base64-decoder-algo}\n\nThe algorithm behind a base64 decoder is essentially the inverse process of a base64 encoder.\nA base64 decoder needs to translate base64 messages back into their original meaning,\ni.e., into the original sequence of binary data.\n\nA base64 decoder usually works on a window of 4 bytes. Because it wants to convert these 4 bytes\nback into the original sequence of 3 bytes, that was converted into 4 groups of 6 bits by the\nbase64 encoder. Remember, in a base64 decoder we are essentially reverting the process made\nby the base64 encoder.\n\nEach byte in the input string (the base64 encoded string) normally contributes to re-create\ntwo different bytes in the output (the original binary data).\nIn other words, each byte that comes out of a base64 decoder is created by transforming merging two different\nbytes in the input together. You can visualize this relationship in @fig-base64-algo2:\n\n![The logic behind a base64 decoder](./../Figures/base64-decoder-flow.png){#fig-base64-algo2}\n\nThe exact transformations, or, the exact steps applied to each byte from the input to transform them\ninto the bytes of the output, are a bit tricky to visualize in a figure like this. Because of that, I have\nsummarized these transformations as \"Some bit shifting and additions ...\" in the figure. These transformations\nwill be described in depth later.\n\nBesides that, if you look again in @fig-base64-algo2, you will notice that the character `=` was completely\nignored by the algorithm. Remember, this is just a special character that marks the end of meaningful characters\nin the base64 sequence. So, every `=` character in a base64 encoded sequence should be ignored by a base64 decoder.\n\n\n## Difference between encode and decode {#sec-encode-vs-decode}\n\nIf you don't have any previous experience with base64, you might not understand the differences\nbetween \"encode\" and \"decode\". Essentially, the terms \"encode\" and \"decode\" here\nhave the exact same meaning as they have in the field of encryption (i.e., they mean the same thing as \"encode\" and \"decode\" in hashing\nalgorithms, like the MD5 algorithm).\n\nThus, \"encode\" means that we want to encode, or, in other words, we want to translate some message into\nthe base64 encoding system. We want to produce the sequence of base64 characters that represent this\noriginal message in the base64 encoding system.\n\nIn contrast, \"decode\" represents the inverse process.\nWe want to decode, or, in other words, translate a base64 message back to its original content.\nSo, in this process we get a sequence of base64 characters as input, and produce as output,\nthe binary data that is represented by this sequence of base64 characters.\n\nAny base64 library is normally composed of these two parts: 1) the encoder, which is a function that encodes\n(i.e., it converts) any sequence of binary data into a sequence of base64 characters; 2) the decoder, which is a function\nthat converts a sequence of base64 characters back into the original sequence of binary data.\n\n\n\n## Calculating the size of the output {#sec-base64-length-out}\n\nOne task that we need to do is to calculate how much space we need to reserve for the\noutput, both of the encoder and decoder. This is simple math, and can be done easily in Zig\nbecause every array has its length (its number of elements) easily accesible by consulting\nthe `.len` property of the array.\n\nFor the encoder, the logic is the following: for each 3 bytes that we find in the input,\n4 new bytes are created in the output. So, we take the number of bytes in the input, divide it\nby 3, use a ceiling function, then, we multiply the result by 4. That way, we get the total\nnumber of bytes that will be produced by the encoder in its output.\n\nThe `_calc_encode_length()` function below encapsulates this logic.\nInside this function, we take the length of the input array,\nwe divide it by 3, and apply a ceil operation over the result by using the\n`divCeil()` function from the Zig Standard Library. Lastly, we multiply\nthe end result by 4 to get the answer we need.\n\nAlso, you might have notice that, if the input length is less than 3 bytes, then, the output length of the encoder is\nalways 4 bytes. This is the case for every input with less than 3 bytes, because, as I described in @sec-base64-encoder-algo,\nthe algorithm always produces enough \"padding-groups\" in the end result, to complete the 4 bytes window.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_encode_length(input: []const u8) !usize {\n    if (input.len < 3) {\n        return 4;\n    }\n    const n_groups: usize = try std.math.divCeil(\n        usize, input.len, 3\n    );\n    return n_groups * 4;\n}\n```\n:::\n\n\n\n\n\nNow, the logic to calculate the length of the output from the decoder is a little bit more complicated. But, it is basically\njust the inverse logic that we've used for the encoder: for each 4 bytes in the input, 3 bytes\nwill be produced in the output of the decoder. However, this time we need to\ntake the `=` character into account, which is always ignored by the decoder, as we described in @sec-base64-decoder-algo, and,\nin @fig-base64-algo2.\n\nIn essence, we take the length of the input and divide it by 4, then we apply a floor function on the result, then\nwe multiply the result by 3, and then, we subtract from the result how much times the character `=` is found\nin the input.\n\nThe function `_calc_decode_length()` exposed below summarizes this logic that we described. It's similar\nto the function `_calc_encode_length()`. Notice that the division part is twisted. Also notice that this time, we apply\na floor operation over the output of the division, by using the `divFloor()`\nfunction (instead of a ceiling operation with `divCeil()`).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_decode_length(input: []const u8) !usize {\n    if (input.len < 4) {\n        return 3;\n    }\n\n    const n_groups: usize = try std.math.divFloor(\n        usize, input.len, 4\n    );\n    var multiple_groups: usize = n_groups * 3;\n    var i: usize = input.len - 1;\n    while (i > 0) : (i -= 1) {\n        if (input[i] == '=') {\n            multiple_groups -= 1;\n        } else {\n            break;\n        }\n    }\n\n    return multiple_groups;\n}\n```\n:::\n\n\n\n\n\n## Building the encoder logic {#sec-encoder-logic}\n\nIn this section, we can start building the logic behind the `encode()` function, which\nwill be responsible for encoding messages into the base64 encoding system.\nIf you are an anxious person, and you want to see now the full source code of the implementation\nfor this base64 encoder/decoder, you can find it at the `ZigExamples` folder in the official repository of\nthis book[^zig-base64-algo].\n\n[^zig-base64-algo]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/base64/base64_basic.zig>.\n\n\n\n### The 6-bit transformation {#sec-6bit-transf}\n\nThe 6-bit transformation presented in @fig-base64-algo1 is the core part of the base64 encoder algorithm.\nBy understanding how this transformation is made in code, the rest of the algorithm becomes much simpler\nto comprehend.\n\nIn essence, this 6-bit transformation is made with the help of bitwise operators.\nBitwise operators are essential to any type of low-level operation that is done at the bit-level. For the specific case of the base64 algorithm,\nthe operators *bif shift to the left* (`<<`), *bit shift to the right* (`>>`), and the *bitwise and* (`&`) are used. They\nare the core solution for the 6-bit transformation.\n\nThere are 3 different scenarios that we need to take into account in this transformation. First, is the perfect scenario,\nwhere we have the perfect window of 3 bytes to work on. Second, we have the scenario where we have a window of only\ntwo bytes to work with. And last, we have the scenario where we have a window of one single byte.\n\nIn each of these 3 scenarios, the 6-bit transformation works a bit differently. To make the explanation\neasier, I will use the variable `output` to refer to the bytes in the output of the base64 encoder,\nand the variable `input` to refer to the bytes in the input of the encoder.\n\n\nSo, if you have the perfect window of 3 bytes, these are steps for the 6-bit transformation:\n\n1. `output[0]` is produced by moving the bits from `input[0]` two positions to the right.\n1. `output[1]` is produced by summing two components. First, take the last two bits from `input[0]`, then, move them four positions to the left. Second, move the bits from `input[1]` four positions to the right. Sum these two components.\n1. `output[2]` is produced by summing two components. First, take the last four bits from `input[1]`, then, move them two positions to the left. Second, move the bits from `input[2]` six positions to the right. Sum these two components.\n1. `output[3]` is produced by taking the last six bits from `input[2]`.\n\n\nThis is the perfect scenario, where we have a full window of 3 bytes to work on.\nJust to make things as clear as possible, the @fig-encoder-bitshift demonstrates visually how\nthe step 2 mentioned above works. So the 2nd byte in the `output` of the encoder, is made by taking the 1st byte (dark purple)\nand the 2nd byte (orange) from the input. You can see that, at the end of the process, we get a new\nbyte that contains the last 2 bits from the 1st byte in the `input`, and the first 4 bits\nfrom the 2nd byte in the `input`.\n\n![How the 2nd byte in the output of the encoder is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input.](../Figures/base64-encoder-bit-shift.png){#fig-encoder-bitshift}\n\nOn the other hand, we must be prepared for the instances where we do not have the perfect window of 3 bytes.\nIf you have a window of 2 bytes, then, the steps 3 and 4, which produces the bytes `output[2]` and `output[3]`, change a little bit,\nand they become:\n\n- `output[2]` is produced by taking the last 4 bits from `input[1]`, then, move them two positions to the left.\n- `output[3]` is the character `'='`.\n\n\nFinally, if you have a window of a single byte, then, the steps 2 to 4, which produces the bytes `output[1]`, `output[2]` and `output[3]` change,\nbecoming:\n\n- `output[1]` is produced by taking the last two bits from `input[0]`, then, move them four positions to the left.\n- `output[2]` and `output[3]` are the character `=`.\n\n\nIf these bullet points were a bit confusing for you, you may find the @tbl-transf-6bit more intuitive.\nThis table unifies all this logic into a simple table. Notice that\nthis table also provides the exact expression in Zig that creates the corresponding\nbyte in the output.\n\n\n::: {#tbl-transf-6bit}\n\n| Number of bytes in the window | Byte index in the output | In code                                    |\n|-------------------------------|--------------------------|--------------------------------------------|\n| 3                             | 0                        | input[0] >> 2                              |\n| 3                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 3                             | 2                        | ((input[1] & 0x0f) << 2) + (input[2] >> 6) |\n| 3                             | 3                        | input[2] & 0x3f                            |\n| 2                             | 0                        | input[0] >> 2                              |\n| 2                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 2                             | 2                        | ((input[1] & 0x0f) << 2)                   |\n| 2                             | 3                        | '='                                        |\n| 1                             | 0                        | input[0] >> 2                              |\n| 1                             | 1                        | ((input[0] & 0x03) << 4)                   |\n| 1                             | 2                        | '='                                        |\n| 1                             | 3                        | '='                                        |\n\n: How the 6-bit transformation translates into code in different window settings.\n\n:::\n\n\n\n\n\n\n### Bit-shifting in Zig\n\nBit-shifting in Zig works similarly to bit-shifting in C.\nAll bitwise operators that exist in C are available in Zig.\nHere, in the base64 encoder algorithm, they are essential\nto produce the result we want.\n\nFor those who are not familiar with these operators, they are\noperators that operates at the bit-level of your values.\nThis means that these operators takes the bits that form the value\nyou have, and change them in some way. This ultimately also changes\nthe value itself, because the binary representation of this value\nchanges.\n\nWe have already seen in @fig-encoder-bitshift the effect produced by a bit-shift.\nBut let's use the first byte in the output of the base64 encoder as another example of what\nbit-shifting means. This is the easiest byte of the 4 bytes in the output\nto build. Because we only need to move the bits from the first byte in the input two positions to the right,\nwith the *bit shift to the right* (`>>`) operator.\n\nIf we take the string \"Hi\" that we used in @fig-base64-algo1 as an example, the first byte in\nthis string is \"H\", which is the sequence `01001000` in binary.\nIf we move the bits of this byte, two places to the right, we get the sequence `00010010` as result.\nThis binary sequence is the value `18` in decimal, and also, the value `0x12` in hexadecimal.\nNotice that the first 6 bits of \"H\" were moved to the end of the byte.\nWith this operation, we get the first byte of the output.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const input = \"Hi\";\n    try stdout.print(\"{d}\\n\", .{input[0] >> 2});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n18\n```\n\n\n:::\n:::\n\n\n\n\nIf you recall @fig-base64-algo1, the first byte present in the output should\nbe equivalent to the 6-bit group `010010`. Although being visually different, the\nsequences `010010` and `00010010` are semantically equal. They mean the same thing.\nThey both represent the number 18 in decimal, and the value `0x12` in hexadecimal.\n\nSo, don't take the \"6-bit group\" factor so seriously. We do not need necessarily to\nget a 6-bit sequence as result. As long as the meaning of the 8-bit sequence we get is the same\nof the 6-bit sequence, we are in the clear.\n\n\n\n### Selecting specific bits with the `&` operator\n\nIf you comeback to @sec-6bit-transf, you will see that, in order to produce\nthe second and third bytes in the output, we need to select specific\nbits from the first and second bytes in the input string. But how\ncan we do that? The answer relies on the *bitwise and* (`&`) operator.\n\nThe @fig-encoder-bitshift already showed you what effect this `&` operator\nproduces in the bits of its operands. But let's make a clear description of it.\n\nIn summary, the `&` operator performs a logical conjunction operation\nbetween the bits of its operands. In more details, the operator `&`\ncompares each bit of the first operand to the corresponding bit of the second operand.\nIf both bits are 1, the corresponding result bit is set to 1.\nOtherwise, the corresponding result bit is set to 0 [@microsoftbitwiseand].\n\nSo, if we apply this operator to the binary sequences `1000100` and `00001101`\nthe result of this operation is the binary sequence `00000100`. Because only\nat the sixth position in both binary sequences we had a 1 value. So any\nposition where we do not have both binary sequences setted to 1, we get\na 0 bit in the resulting binary sequence.\n\nWe lose information about the original bit values\nfrom both sequences in this case. Because we no longer know\nif this 0 bit in the resulting binary sequence was produced by\ncombining 0 with 0, or 1 with 0, or 0 with 1.\n\nAs an example, suppose you have the binary sequence `10010111`, which is the number 151 in decimal. How\ncan we get a new binary sequence which contains only the third and\nfourth bits of this sequence?\n\nWe just need to combine this sequence with `00110000` (is `0x30` in hexadecimal) using the `&` operator.\nNotice that only the third and fourth positions in this binary sequence is setted to 1. As a consequence, only the\nthird and fourth values of both binary sequences are potentially preserved in the output. All the remaining positions\nare setted to zero in the output sequence, which is `00010000` (is the number 16 in decimal).\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const bits = 0b10010111;\n    try stdout.print(\"{d}\\n\", .{bits & 0b00110000});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n16\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Allocating space for the output\n\nAs I described in @sec-stack, to store an object in the stack,\nthis object needs to have a known and fixed length at compile-time. This is an important\nlimitation for our base64 encoder/decoder case. Because the size of\nthe output (from both the encoder and decoder) depends\ndirectly on the size of the input.\n\nHaving this in mind, we cannot know at compile time which is\nthe size of the output for both the encoder and decoder.\nSo, if we can't know the size of the output at compile time,\nthis means that we cannot store the output for both the encoder\nand decoder in the stack.\n\nConsequently, we need to store this output on the heap,\nand, as I commented in @sec-heap, we can only\nstore objects in the heap by using allocator objects.\nSo, one the arguments to both the `encode()` and `decode()`\nfunctions, needs to be an allocator object, because\nwe know for sure that, at some point inside the body of these\nfunctions, we need to allocate space on the heap to\nstore the output of these functions.\n\nThat is why, both the `encode()` and `decode()` functions that I\npresent in this book, have an argument called `allocator`,\nwhich receives a allocator object as input, identified by\nthe type `std.mem.Allocator` from the Zig Standard Library.\n\n\n\n### Writing the `encode()` function\n\nNow that we have a basic understanding on how the bitwise operators work, and how\nexactly they help us to achieve the result we want to achieve. We can now encapsulate\nall the logic that we have described in @fig-base64-algo1 and @tbl-transf-6bit into a nice\nfunction that we can add to our `Base64` struct definition, that we started in @sec-base64-table.\n\nYou can find the `encode()` function below. Notice that the first argument of this function,\nis the `Base64` struct itself. Therefore, this argument clearly signals\nthat this function is a method from the `Base64` struct.\n\nBecause the `encode()` function itself is fairly long,\nI intentionally omitted the `Base64` struct definition in this source code,\njust for brevity reasons. So, just remember that this function is a public function (or a public method) from the\n`Base64` struct.\n\nFurthermore, this `encode()` function has two other arguments:\n\n1. `input` is the input sequence of characters that you want to encode in base64;\n1. `allocator` is an allocator object to use in the necessary memory allocations.\n\nI described everything you need to know about allocator objects in @sec-allocators.\nSo, if you are not familiar with them, I highly recommend you to comeback to\nthat section, and read it.\nBy looking at the `encode()` function, you will see that we use this\nallocator object to allocate enough memory to store the output of\nthe encoding process.\n\nThe main for loop in the function is responsible for iterating through the entire input string.\nIn every iteration, we use a `count` variable to count how many iterations we had at the\nmoment. When `count` reaches 3, then, we try to encode the 3 characters (or bytes) that we have accumulated\nin the temporary buffer object (`buf`).\n\nAfter encoding these 3 characters and storing the result in the `output` variable, we reset\nthe `count` variable to zero, and start to count again on the next iteration of the loop.\nIf the loop hits the end of the string, and, the `count` variable is less than 3, then, it means that\nthe temporary buffer contains the last 1 or 2 bytes from the input.\nThat is why we have two `if` statements after the for loop. To deal which each possible case.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn encode(self: Base64,\n              allocator: std.mem.Allocator,\n              input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n\n    const n_out = try _calc_encode_length(input);\n    var out = try allocator.alloc(u8, n_out);\n    var buf = [3]u8{ 0, 0, 0 };\n    var count: u8 = 0;\n    var iout: u64 = 0;\n\n    for (input, 0..) |_, i| {\n        buf[count] = input[i];\n        count += 1;\n        if (count == 3) {\n            out[iout] = self._char_at(buf[0] >> 2);\n            out[iout + 1] = self._char_at(\n                ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n            );\n            out[iout + 2] = self._char_at(\n                ((buf[1] & 0x0f) << 2) + (buf[2] >> 6)\n            );\n            out[iout + 3] = self._char_at(buf[2] & 0x3f);\n            iout += 4;\n            count = 0;\n        }\n    }\n\n    if (count == 1) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            (buf[0] & 0x03) << 4\n        );\n        out[iout + 2] = '=';\n        out[iout + 3] = '=';\n    }\n\n    if (count == 2) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n        );\n        out[iout + 2] = self._char_at(\n            (buf[1] & 0x0f) << 2\n        );\n        out[iout + 3] = '=';\n        iout += 4;\n    }\n\n    return out;\n}\n```\n:::\n\n\n\n\n\n\n## Building the decoder logic {#sec-decoder-logic}\n\nNow, we can focus on writing the base64 decoder logic. Remember from @fig-base64-algo2 that,\na base64 decoder does the inverse process of an encoder. So, all we need to do, is to\nwrite a `decode()` function that performs the inverse process that I exposed in @sec-encoder-logic.\n\n\n### Mapping base64 characters to their indexes {#sec-map-base64-index}\n\nOne thing that we need to do, in order to decode a base64-encoded message, is to calculate\nthe index in the base64 scale of every base64 character that we encounter in the decoder input.\n\nIn other words, the decoder receives as input, a sequence of base64 characters. We need\nto translate this sequence of characters into a sequence of indexes. These indexes\nare the index of each character in the base64 scale. This way, we get the value/byte\nthat was calculated in the 6-bit transformation step of the encoder process.\n\nThere are probably better/faster ways to calculate this, especially using a \"divide and conquer\"\ntype of strategy. But for now, I am satisfied with a simple and \"brute force\" type of strategy.\nThe `_char_index()` function below contains this strategy.\n\nWe are essentially looping through the *lookup table* with the base64 scale,\nand comparing the character we got with each character in the base64 scale.\nIf these characters match, then, we return the index of this character in the\nbase64 scale as the result.\n\nNotice that, if the input character is `'='`, the function returns the index 64, which is\n\"out of range\" in the scale. But, as I described in @sec-base64-scale,\nthe character `'='` does not belong to the base64 scale itself.\nIt's a special and meaningless character in base64.\n\nAlso notice that this `_char_index()` function is a method from our `Base64` struct,\nbecause of the `self` argument. Again, I have omitted the `Base64` struct definition in this example\nfor brevity reasons.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn _char_index(self: Base64, char: u8) u8 {\n    if (char == '=')\n        return 64;\n    var index: u8 = 0;\n    for (0..63) |i| {\n        if (self._char_at(i) == char)\n            break;\n        index += 1;\n    }\n\n    return index;\n}\n```\n:::\n\n\n\n\n\n\n### The 6-bit transformation\n\nOnce again, the core part of the algorithm is the 6-bit transformation.\nIf we understand the necessary steps to perform this transformation, the rest\nof the algorithm becomes much easier.\n\nFirst of all, before we actually go to the 6-bit transformation,\nwe need to make sure that we use `_char_index()` to convert the sequence of base64 characters\ninto a sequence of indexes. So the snippet below is important for the job that will be done.\nThe result of `_char_index()` is stored in a temporary buffer, and this temporary buffer\nis what we are going to use in the 6-bit transformation, instead of the actual `input` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (0..input.len) |i| {\n    buf[i] = self._char_index(input[i]);\n}\n```\n:::\n\n\n\n\nNow, instead of producing 4 bytes (or 4 characters) as output per each window of 3 characters in the input,\na base64 decoder produces 3 bytes (or 3 characters) as output per each window of 4 characters in the input.\nOnce again, is the inverse process.\n\nSo, the steps to produce the 3 bytes in the output are:\n\n1. `output[0]` is produced by summing two components. First, move the bits from `buf[0]` two positions to the left. Second, move the bits from `buf[1]` 4 positions to the right. Then, sum these two components.\n1. `output[1]` is produced by summing two components. First, move the bits from `buf[1]` four positions to the left. Second, move the bits from `buf[2]` 2 positions to the right. Then, sum these two components.\n1. `output[2]` is produced by summing two components. First, move the bits from `buf[2]` six positions to the left. Then, you sum the result with `buf[3]`.\n\n\nBefore we continue, let's try to visualize how these transformations make the original bytes that we had\nbefore the encoding process. First, think back to the 6-bit transformation performed by the encoder exposed in @sec-encoder-logic.\nThe first byte in the output of the encoder is produced by moving the bits in the first byte of the input two positions to the right.\n\nIf for example the first byte in the input of the encoder was the sequence `ABCDEFGH`, then, the first byte in the output of the encoder would be\n`00ABCDEF` (this sequence would be the first byte in the input of the decoder). Now, if the second byte in the input of the encoder was the sequence\n`IJKLMNOP`, then, the second byte in the encoder output would be `00GHIJKL` (as we demonstrated in @fig-encoder-bitshift).\n\nHence, if the sequences `00ABCDEF` and `00GHIJKL` are the first and second bytes, respectively, in the input of the decoder, the\n@fig-decoder-bitshift demonstrates visually how these two bytes are transformed into the first byte of the output of the decoder.\nNotice that the output byte is the sequence `ABCDEFGH`, which is the original byte from the input of the encoder.\n\n![How the 1st byte in the decoder output is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input](../Figures/base64-decoder-bit-shift.png){#fig-decoder-bitshift}\n\nThe @tbl-6bit-decode presents how the three steps described earlier translate into Zig code:\n\n\n\n::: {#tbl-6bit-decode}\n\n| Byte index in the output | In code                       |\n|--------------------------|-------------------------------|\n| 0                        | (buf[0] << 2) + (buf[1] >> 4) |\n| 1                        | (buf[1] << 4) + (buf[2] >> 2) |\n| 2                        | (buf[2] << 6) + buf[3]        |\n\n: The necessary steps for the 6-transformation in the decode process.\n\n\n:::\n\n\n\n\n\n\n\n### Writing the `decode()` function\n\nThe `decode()` function below contains the entire decoding process.\nWe first calculate the size of the output, with\n`_calc_decode_length()`, then, we allocate enough memory for this output with\nthe allocator object.\n\nThree temporary variables are created: 1) `count`, to hold the window count\nin each iteration of the for loop; 2) `iout`, to hold the current index in the output;\n3) `buf`, which is the temporary buffer that holds the base64 indexes to be\nconverted through the 6-bit transformation.\n\nThen, in each iteration of the for loop we fill the temporary buffer with the current\nwindow of bytes. When `count` hits the number 4, then, we have a full window of\nindexes in `buf` to be converted, and then, we apply the 6-bit transformation\nover the temporary buffer.\n\nNotice that we check if the indexes 2 and 3 in the temporary buffer are the number 64, which, if you recall\nfrom @sec-map-base64-index, is when the `_calc_index()` function receives a `'='` character\nas input. So, if these indexes are equal to the number 64, the `decode()` function knows\nthat it can simply ignore these indexes. They are not converted because, as I described before,\nthe character `'='` has no meaning, despite being the end of meaningful characters in the sequence.\nSo we can safely ignore them when they appear in the sequence.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn decode(self: Base64,\n          allocator: std.mem.Allocator,\n          input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n    const n_output = try _calc_decode_length(input);\n    var output = try allocator.alloc(u8, n_output);\n    var count: u8 = 0;\n    var iout: u64 = 0;\n    var buf = [4]u8{ 0, 0, 0, 0 };\n\n    for (0..input.len) |i| {\n        buf[count] = self._char_index(input[i]);\n        count += 1;\n        if (count == 4) {\n            output[iout] = (buf[0] << 2) + (buf[1] >> 4);\n            if (buf[2] != 64) {\n                output[iout + 1] = (buf[1] << 4) + (buf[2] >> 2);\n            }\n            if (buf[3] != 64) {\n                output[iout + 2] = (buf[2] << 6) + buf[3];\n            }\n            iout += 3;\n            count = 0;\n        }\n    }\n\n    return output;\n}\n```\n:::\n\n\n\n\n\n## The end result\n\nNow that we have both `decode()` and `encode()` implemented. We have a fully functioning\nbase64 encoder/decoder implemented in Zig. Here is an usage example of our\n`Base64` struct with the `encode()` and `decode()` methods that we have implemented.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar memory_buffer: [1000]u8 = undefined;\nvar fba = std.heap.FixedBufferAllocator.init(\n    &memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst text = \"Testing some more stuff\";\nconst etext = \"VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=\";\nconst base64 = Base64.init();\nconst encoded_text = try base64.encode(\n    allocator, text\n);\nconst decoded_text = try base64.decode(\n    allocator, etext\n);\ntry stdout.print(\n    \"Encoded text: {s}\\n\", .{encoded_text}\n);\ntry stdout.print(\n    \"Decoded text: {s}\\n\", .{decoded_text}\n);\n```\n:::\n\n\n\n\n```\nEncoded text: VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=\nDecoded text: Testing some more stuff\n```\n\nYou can also see the full source code at once, by visiting the official repository of this book[^repo].\nMore precisely inside the `ZigExamples` folder[^zig-base64-algo].\n\n[^repo]: <https://github.com/pedropark99/zig-book>\n",
-    "supporting": [
-      "01-base64_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n# Project 1 - Building a base64 encoder/decoder {#sec-base64}\n\nAs our first small project, I want to implement a base64 encoder/decoder with you.\nBase64 is an encoding system which translates binary data to text.\nA big chunk of the web uses base64 to deliver binary data to systems\nthat can only read text data.\n\nThe most common example of a modern use case for base64 is essentially any email system,\nlike GMail, Outlook, etc. Because email systems normally use\nthe Simple Mail Transfer Protocol (SMTP), which is a web protocol\nthat supports only text data. So, if you need, for any reason, to\nsend a binary file (like for example, a PDF, or an Excel file) as\nan attachment in your email, these binary files are normally\nconverted to base64, before they are included in the SMTP message.\nSo, the base64 encoding is largely used in these email systems to include\nbinary data into the SMTP message.\n\n\n\n\n\n\n## How the base64 algorithm work?\n\nBut how exactly does the algorithm behind the base64 encoding work? Let's discuss that. First, I will\nexplain the base64 scale, which is the 64-character scale that is the basis for\nthe base64 encoding system.\n\nAfter that, I explain the algorithm behind a base64 encoder, which is the part of the algorithm that is responsible for encoding messages\ninto the base64 encoding system. Then, after that, I explain the algorithm behind a base64 decoder, which is\nthe part of the algorithm that is responsible for translating base64 messages back into their original meaning.\n\nIf you are unsure about the differences between an \"encoder\" and a \"decoder\",\ntake a look at @sec-encode-vs-decode.\n\n\n### The base64 scale {#sec-base64-scale}\n\nThe base64 encoding system is based on a scale that goes from 0 to 63 (hence the name).\nEach index in this scale is represented by a character (it's a scale of 64 characters).\nSo, in order to convert some binary data, to the base64 encoding, we need to convert each binary number to the corresponding\ncharacter in this \"scale of 64 characters\".\n\nThe base64 scale starts with all ASCII uppercase letters (A to Z) which represents\nthe first 25 indexes in this scale (0 to 25). After that, we have all ASCII lowercase letters\n(a to z), which represents the range 26 to 51 in the scale. After that, we\nhave the one digit numbers (0 to 9), which represents the indexes from 52 to 61 in the scale.\nFinally, the last two indexes in the scale (62 and 63) are represented by the characters `+` and `/`,\nrespectively.\n\nThese are the 64 characters that compose the base64 scale. The equal sign character (`=`) is not part of the scale itself,\nbut it is a special character in the base64 encoding system. This character is used solely as a suffix, to mark the end of the character sequence,\nor, to mark the end of meaningful characters in the sequence.\n\nThe bullet points below summarises the base64 scale:\n\n- range 0 to 25 is represented by: ASCII uppercase letters `-> [A-Z]`;\n- range 26 to 51 is represented by: ASCII lowercase letters `-> [a-z]`;\n- range 52 to 61 is represented by: one digit numbers `-> [0-9]`;\n- index 62 and 63 are represented by the characters `+` and `/`, respectively;\n- the character `=` represents the end of meaningful characters in the sequence;\n\n\n\n\n### Creating the scale as a lookup table {#sec-base64-table}\n\nThe best way to represent this scale in code, is to represent it as a *lookup table*.\nLookup tables are a classic strategy in computer science to speed up calculations. The basic idea\nis to replace a runtime calculation (which can take a long time to be done) with a basic array indexing\noperation.\n\nInstead of calculating the results everytime you need them, you calculate all possible results at once, and then, you store them in an array\n(which behaves lake a \"table\"). Then, every time you need to use one of the characters in the base64 scale, instead of\nusing many resources to calculate the exact character to be used, you simply retrieve this character\nfrom the array where you stored all the possible characters in the base64 scale.\nWe retrieve the character that we need directly from memory.\n\nWe can start building a Zig struct to store our base64 decoder/encoder logic.\nWe start with the `Base64` struct below. For now, we only have one single data member in this\nstruct, i.e., the member `_table`, which represents our lookup table. We also have an `init()` method,\nto create a new instance of a `Base64` object, and, a `_char_at()` method, which is a\n\"get character at index $x$\" type of function.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Base64 = struct {\n    _table: *const [64]u8,\n\n    pub fn init() Base64 {\n        const upper = \"ABCDEFGHIJKLMNOPQRSTUVWXYZ\";\n        const lower = \"abcdefghijklmnopqrstuvwxyz\";\n        const numbers_symb = \"0123456789+/\";\n        return Base64{\n            ._table = upper ++ lower ++ numbers_symb,\n        };\n    }\n\n    pub fn _char_at(self: Base64, index: usize) u8 {\n        return self._table[index];\n    }\n};\n```\n:::\n\n\n\nIn other words, the `_char_at()` method is responsible for getting the character in the lookup\ntable (i.e., the `_table` struct data member) that corresponds to a particular index in the\n\"base64 scale\". So, in the example below, we know that the character that corresponds to the\nindex 28 in the \"base64 scale\" is the character \"c\".\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst base64 = Base64.init();\ntry stdout.print(\n    \"Character at index 28: {c}\\n\",\n    .{base64._char_at(28)}\n);\n```\n:::\n\n\n```\nCharacter at index 28: c\n```\n\n\n\n### A base64 encoder {#sec-base64-encoder-algo}\n\nThe algorithm behind a base64 encoder usually works on a window of 3 bytes. Because each byte has\n8 bits, so, 3 bytes forms a set of $8 \\times 3 = 24$ bits. This is desirable for the base64 algorithm, because\n24 bits is divisible by 6, which forms $24 / 6 = 4$ groups of 6 bits each.\n\nTherefore, the base64 algorithm works by converting 3 bytes at a time\ninto 4 characters from the base64 scale. It keeps iterating through the input string,\n3 bytes at a time, and converting them into the base64 scale, producing 4 characters\nper iteration. It keeps iterating, and producing these \"new characters\"\nuntil it hits the end of the input string.\n\nNow you may think, what if you have a particular string that has a number of bytes\nthat is not divisible by 3 - what happens? For example, if you have a string\nthat contains only two characters/bytes, such as \"Hi\". How would the algorithm\nbehave in such situation? You find the answer in @fig-base64-algo1.\nYou can see in @fig-base64-algo1 that the string \"Hi\", when converted to base64,\nbecomes the string \"SGk=\":\n\n![The logic behind a base64 encoder](./../Figures/base64-encoder-flow.png){#fig-base64-algo1}\n\nTaking the string \"Hi\" as an example, we have 2 bytes, or, 16 bits in total. So, we lack a full byte (8 bits)\nto complete the window of 24 bits that the base64 algorithm likes to work on. The first thing that\nthe algorithm does, is to check how to divide the input bytes into groups of 6 bits.\n\nIf the algorithm notices that there is a group of 6 bits that it's not complete, meaning that, this group contains $nbits$, where $0 < nbits < 6$,\n\nthe algorithm simply adds extra zeros in this group to fill the space that it needs.\nThat is why in @fig-base64-algo1, in the third group after the 6-bit transformation,\n2 extra zeros were added to fill the gap.\n\nWhen we have a 6-bit group that is not completely full, like the third group, extra zeros\nare added to fill the gap. But what about when an entire 6-bit group is empty, or, it\nsimply doesn't exist? This is the case of the fourth 6-bit group exposed at\n@fig-base64-algo1.\n\nThis fourth group is necessary, because the algorithm works on 4 groups of 6 bits.\nBut the input string does not have enough bytes to create a fourth 6-bit group.\nEvery time this happens, where an entire group of 6 bits is empty,\nthis group becomes a \"padding group\". Every \"padding group\" is mapped to\nthe character `=` (equal sign), which represents \"null\", or, the end\nof meaningful characters in the sequence. Hence, everytime that the algorithm produces a\n\"padding group\", this group is automatically mapped to `=`.\n\nAs another example, if you give the string \"0\" as input to a base64 encoder, this string is\ntranslated into the base64 sequence \"MA==\".\nThe character \"0\" is, in binary, the sequence `00110000`[^zero-note]. So, with the 6-bit transformation\nexposed in @fig-base64-algo1, this single character would produce these two 6-bit groups: `001100`, `000000`.\nThe remaining two 6-bit groups become \"padding groups\". That is why the last\ntwo characters in the output sequence (MA==) are `==`.\n\n\n[^zero-note]: Notice that, the character \"0\" is different than the actual number 0, which is simply zero in binary.\n\n### A base64 decoder {#sec-base64-decoder-algo}\n\nThe algorithm behind a base64 decoder is essentially the inverse process of a base64 encoder.\nA base64 decoder needs to translate base64 messages back into their original meaning,\ni.e., into the original sequence of binary data.\n\nA base64 decoder usually works on a window of 4 bytes. Because it wants to convert these 4 bytes\nback into the original sequence of 3 bytes, that was converted into 4 groups of 6 bits by the\nbase64 encoder. Remember, in a base64 decoder we are essentially reverting the process made\nby the base64 encoder.\n\nEach byte in the input string (the base64 encoded string) normally contributes to re-create\ntwo different bytes in the output (the original binary data).\nIn other words, each byte that comes out of a base64 decoder is created by transforming merging two different\nbytes in the input together. You can visualize this relationship in @fig-base64-algo2:\n\n![The logic behind a base64 decoder](./../Figures/base64-decoder-flow.png){#fig-base64-algo2}\n\nThe exact transformations, or, the exact steps applied to each byte from the input to transform them\ninto the bytes of the output, are a bit tricky to visualize in a figure like this. Because of that, I have\nsummarized these transformations as \"Some bit shifting and additions ...\" in the figure. These transformations\nwill be described in depth later.\n\nBesides that, if you look again in @fig-base64-algo2, you will notice that the character `=` was completely\nignored by the algorithm. Remember, this is just a special character that marks the end of meaningful characters\nin the base64 sequence. So, every `=` character in a base64 encoded sequence should be ignored by a base64 decoder.\n\n\n## Difference between encode and decode {#sec-encode-vs-decode}\n\nIf you don't have any previous experience with base64, you might not understand the differences\nbetween \"encode\" and \"decode\". Essentially, the terms \"encode\" and \"decode\" here\nhave the exact same meaning as they have in the field of encryption (i.e., they mean the same thing as \"encode\" and \"decode\" in hashing\nalgorithms, like the MD5 algorithm).\n\nThus, \"encode\" means that we want to encode, or, in other words, we want to translate some message into\nthe base64 encoding system. We want to produce the sequence of base64 characters that represent this\noriginal message in the base64 encoding system.\n\nIn contrast, \"decode\" represents the inverse process.\nWe want to decode, or, in other words, translate a base64 message back to its original content.\nSo, in this process we get a sequence of base64 characters as input, and produce as output,\nthe binary data that is represented by this sequence of base64 characters.\n\nAny base64 library is normally composed of these two parts: 1) the encoder, which is a function that encodes\n(i.e., it converts) any sequence of binary data into a sequence of base64 characters; 2) the decoder, which is a function\nthat converts a sequence of base64 characters back into the original sequence of binary data.\n\n\n\n## Calculating the size of the output {#sec-base64-length-out}\n\nOne task that we need to do is to calculate how much space we need to reserve for the\noutput, both of the encoder and decoder. This is simple math, and can be done easily in Zig\nbecause every array has its length (its number of elements) easily accesible by consulting\nthe `.len` property of the array.\n\nFor the encoder, the logic is the following: for each 3 bytes that we find in the input,\n4 new bytes are created in the output. So, we take the number of bytes in the input, divide it\nby 3, use a ceiling function, then, we multiply the result by 4. That way, we get the total\nnumber of bytes that will be produced by the encoder in its output.\n\nThe `_calc_encode_length()` function below encapsulates this logic.\nInside this function, we take the length of the input array,\nwe divide it by 3, and apply a ceil operation over the result by using the\n`divCeil()` function from the Zig Standard Library. Lastly, we multiply\nthe end result by 4 to get the answer we need.\n\nAlso, you might have notice that, if the input length is less than 3 bytes, then, the output length of the encoder is\nalways 4 bytes. This is the case for every input with less than 3 bytes, because, as I described in @sec-base64-encoder-algo,\nthe algorithm always produces enough \"padding-groups\" in the end result, to complete the 4 bytes window.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_encode_length(input: []const u8) !usize {\n    if (input.len < 3) {\n        return 4;\n    }\n    const n_groups: usize = try std.math.divCeil(\n        usize, input.len, 3\n    );\n    return n_groups * 4;\n}\n```\n:::\n\n\n\nNow, the logic to calculate the length of the output from the decoder is a little bit more complicated. But, it is basically\njust the inverse logic that we've used for the encoder: for each 4 bytes in the input, 3 bytes\nwill be produced in the output of the decoder. However, this time we need to\ntake the `=` character into account, which is always ignored by the decoder, as we described in @sec-base64-decoder-algo, and,\nin @fig-base64-algo2.\n\nIn essence, we take the length of the input and divide it by 4, then we apply a floor function on the result, then\nwe multiply the result by 3, and then, we subtract from the result how much times the character `=` is found\nin the input.\n\nThe function `_calc_decode_length()` exposed below summarizes this logic that we described. It's similar\nto the function `_calc_encode_length()`. Notice that the division part is twisted. Also notice that this time, we apply\na floor operation over the output of the division, by using the `divFloor()`\nfunction (instead of a ceiling operation with `divCeil()`).\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_decode_length(input: []const u8) !usize {\n    if (input.len < 4) {\n        return 3;\n    }\n\n    const n_groups: usize = try std.math.divFloor(\n        usize, input.len, 4\n    );\n    var multiple_groups: usize = n_groups * 3;\n    var i: usize = input.len - 1;\n    while (i > 0) : (i -= 1) {\n        if (input[i] == '=') {\n            multiple_groups -= 1;\n        } else {\n            break;\n        }\n    }\n\n    return multiple_groups;\n}\n```\n:::\n\n\n\n## Building the encoder logic {#sec-encoder-logic}\n\nIn this section, we can start building the logic behind the `encode()` function, which\nwill be responsible for encoding messages into the base64 encoding system.\nIf you are an anxious person, and you want to see now the full source code of the implementation\nfor this base64 encoder/decoder, you can find it at the `ZigExamples` folder in the official repository of\nthis book[^zig-base64-algo].\n\n[^zig-base64-algo]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/base64/base64_basic.zig>.\n\n\n\n### The 6-bit transformation {#sec-6bit-transf}\n\nThe 6-bit transformation presented in @fig-base64-algo1 is the core part of the base64 encoder algorithm.\nBy understanding how this transformation is made in code, the rest of the algorithm becomes much simpler\nto comprehend.\n\nIn essence, this 6-bit transformation is made with the help of bitwise operators.\nBitwise operators are essential to any type of low-level operation that is done at the bit-level. For the specific case of the base64 algorithm,\nthe operators *bif shift to the left* (`<<`), *bit shift to the right* (`>>`), and the *bitwise and* (`&`) are used. They\nare the core solution for the 6-bit transformation.\n\nThere are 3 different scenarios that we need to take into account in this transformation. First, is the perfect scenario,\nwhere we have the perfect window of 3 bytes to work on. Second, we have the scenario where we have a window of only\ntwo bytes to work with. And last, we have the scenario where we have a window of one single byte.\n\nIn each of these 3 scenarios, the 6-bit transformation works a bit differently. To make the explanation\neasier, I will use the variable `output` to refer to the bytes in the output of the base64 encoder,\nand the variable `input` to refer to the bytes in the input of the encoder.\n\n\nSo, if you have the perfect window of 3 bytes, these are steps for the 6-bit transformation:\n\n1. `output[0]` is produced by moving the bits from `input[0]` two positions to the right.\n1. `output[1]` is produced by summing two components. First, take the last two bits from `input[0]`, then, move them four positions to the left. Second, move the bits from `input[1]` four positions to the right. Sum these two components.\n1. `output[2]` is produced by summing two components. First, take the last four bits from `input[1]`, then, move them two positions to the left. Second, move the bits from `input[2]` six positions to the right. Sum these two components.\n1. `output[3]` is produced by taking the last six bits from `input[2]`.\n\n\nThis is the perfect scenario, where we have a full window of 3 bytes to work on.\nJust to make things as clear as possible, the @fig-encoder-bitshift demonstrates visually how\nthe step 2 mentioned above works. So the 2nd byte in the `output` of the encoder, is made by taking the 1st byte (dark purple)\nand the 2nd byte (orange) from the input. You can see that, at the end of the process, we get a new\nbyte that contains the last 2 bits from the 1st byte in the `input`, and the first 4 bits\nfrom the 2nd byte in the `input`.\n\n![How the 2nd byte in the output of the encoder is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input.](../Figures/base64-encoder-bit-shift.png){#fig-encoder-bitshift}\n\nOn the other hand, we must be prepared for the instances where we do not have the perfect window of 3 bytes.\nIf you have a window of 2 bytes, then, the steps 3 and 4, which produces the bytes `output[2]` and `output[3]`, change a little bit,\nand they become:\n\n- `output[2]` is produced by taking the last 4 bits from `input[1]`, then, move them two positions to the left.\n- `output[3]` is the character `'='`.\n\n\nFinally, if you have a window of a single byte, then, the steps 2 to 4, which produces the bytes `output[1]`, `output[2]` and `output[3]` change,\nbecoming:\n\n- `output[1]` is produced by taking the last two bits from `input[0]`, then, move them four positions to the left.\n- `output[2]` and `output[3]` are the character `=`.\n\n\nIf these bullet points were a bit confusing for you, you may find the @tbl-transf-6bit more intuitive.\nThis table unifies all this logic into a simple table. Notice that\nthis table also provides the exact expression in Zig that creates the corresponding\nbyte in the output.\n\n\n::: {#tbl-transf-6bit}\n\n| Number of bytes in the window | Byte index in the output | In code                                    |\n|-------------------------------|--------------------------|--------------------------------------------|\n| 3                             | 0                        | input[0] >> 2                              |\n| 3                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 3                             | 2                        | ((input[1] & 0x0f) << 2) + (input[2] >> 6) |\n| 3                             | 3                        | input[2] & 0x3f                            |\n| 2                             | 0                        | input[0] >> 2                              |\n| 2                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 2                             | 2                        | ((input[1] & 0x0f) << 2)                   |\n| 2                             | 3                        | '='                                        |\n| 1                             | 0                        | input[0] >> 2                              |\n| 1                             | 1                        | ((input[0] & 0x03) << 4)                   |\n| 1                             | 2                        | '='                                        |\n| 1                             | 3                        | '='                                        |\n\n: How the 6-bit transformation translates into code in different window settings.\n\n:::\n\n\n\n\n\n\n### Bit-shifting in Zig\n\nBit-shifting in Zig works similarly to bit-shifting in C.\nAll bitwise operators that exist in C are available in Zig.\nHere, in the base64 encoder algorithm, they are essential\nto produce the result we want.\n\nFor those who are not familiar with these operators, they are\noperators that operates at the bit-level of your values.\nThis means that these operators takes the bits that form the value\nyou have, and change them in some way. This ultimately also changes\nthe value itself, because the binary representation of this value\nchanges.\n\nWe have already seen in @fig-encoder-bitshift the effect produced by a bit-shift.\nBut let's use the first byte in the output of the base64 encoder as another example of what\nbit-shifting means. This is the easiest byte of the 4 bytes in the output\nto build. Because we only need to move the bits from the first byte in the input two positions to the right,\nwith the *bit shift to the right* (`>>`) operator.\n\nIf we take the string \"Hi\" that we used in @fig-base64-algo1 as an example, the first byte in\nthis string is \"H\", which is the sequence `01001000` in binary.\nIf we move the bits of this byte, two places to the right, we get the sequence `00010010` as result.\nThis binary sequence is the value `18` in decimal, and also, the value `0x12` in hexadecimal.\nNotice that the first 6 bits of \"H\" were moved to the end of the byte.\nWith this operation, we get the first byte of the output.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const input = \"Hi\";\n    try stdout.print(\"{d}\\n\", .{input[0] >> 2});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n18\n```\n\n\n:::\n:::\n\n\nIf you recall @fig-base64-algo1, the first byte present in the output should\nbe equivalent to the 6-bit group `010010`. Although being visually different, the\nsequences `010010` and `00010010` are semantically equal. They mean the same thing.\nThey both represent the number 18 in decimal, and the value `0x12` in hexadecimal.\n\nSo, don't take the \"6-bit group\" factor so seriously. We do not need necessarily to\nget a 6-bit sequence as result. As long as the meaning of the 8-bit sequence we get is the same\nof the 6-bit sequence, we are in the clear.\n\n\n\n### Selecting specific bits with the `&` operator\n\nIf you comeback to @sec-6bit-transf, you will see that, in order to produce\nthe second and third bytes in the output, we need to select specific\nbits from the first and second bytes in the input string. But how\ncan we do that? The answer relies on the *bitwise and* (`&`) operator.\n\nThe @fig-encoder-bitshift already showed you what effect this `&` operator\nproduces in the bits of its operands. But let's make a clear description of it.\n\nIn summary, the `&` operator performs a logical conjunction operation\nbetween the bits of its operands. In more details, the operator `&`\ncompares each bit of the first operand to the corresponding bit of the second operand.\nIf both bits are 1, the corresponding result bit is set to 1.\nOtherwise, the corresponding result bit is set to 0 [@microsoftbitwiseand].\n\nSo, if we apply this operator to the binary sequences `1000100` and `00001101`\nthe result of this operation is the binary sequence `00000100`. Because only\nat the sixth position in both binary sequences we had a 1 value. So any\nposition where we do not have both binary sequences setted to 1, we get\na 0 bit in the resulting binary sequence.\n\nWe lose information about the original bit values\nfrom both sequences in this case. Because we no longer know\nif this 0 bit in the resulting binary sequence was produced by\ncombining 0 with 0, or 1 with 0, or 0 with 1.\n\nAs an example, suppose you have the binary sequence `10010111`, which is the number 151 in decimal. How\ncan we get a new binary sequence which contains only the third and\nfourth bits of this sequence?\n\nWe just need to combine this sequence with `00110000` (is `0x30` in hexadecimal) using the `&` operator.\nNotice that only the third and fourth positions in this binary sequence is setted to 1. As a consequence, only the\nthird and fourth values of both binary sequences are potentially preserved in the output. All the remaining positions\nare setted to zero in the output sequence, which is `00010000` (is the number 16 in decimal).\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const bits = 0b10010111;\n    try stdout.print(\"{d}\\n\", .{bits & 0b00110000});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n16\n```\n\n\n:::\n:::\n\n\n\n\n### Allocating space for the output\n\nAs I described in @sec-stack, to store an object in the stack,\nthis object needs to have a known and fixed length at compile-time. This is an important\nlimitation for our base64 encoder/decoder case. Because the size of\nthe output (from both the encoder and decoder) depends\ndirectly on the size of the input.\n\nHaving this in mind, we cannot know at compile time which is\nthe size of the output for both the encoder and decoder.\nSo, if we can't know the size of the output at compile time,\nthis means that we cannot store the output for both the encoder\nand decoder in the stack.\n\nConsequently, we need to store this output on the heap,\nand, as I commented in @sec-heap, we can only\nstore objects in the heap by using allocator objects.\nSo, one the arguments to both the `encode()` and `decode()`\nfunctions, needs to be an allocator object, because\nwe know for sure that, at some point inside the body of these\nfunctions, we need to allocate space on the heap to\nstore the output of these functions.\n\nThat is why, both the `encode()` and `decode()` functions that I\npresent in this book, have an argument called `allocator`,\nwhich receives a allocator object as input, identified by\nthe type `std.mem.Allocator` from the Zig Standard Library.\n\n\n\n### Writing the `encode()` function\n\nNow that we have a basic understanding on how the bitwise operators work, and how\nexactly they help us to achieve the result we want to achieve. We can now encapsulate\nall the logic that we have described in @fig-base64-algo1 and @tbl-transf-6bit into a nice\nfunction that we can add to our `Base64` struct definition, that we started in @sec-base64-table.\n\nYou can find the `encode()` function below. Notice that the first argument of this function,\nis the `Base64` struct itself. Therefore, this argument clearly signals\nthat this function is a method from the `Base64` struct.\n\nBecause the `encode()` function itself is fairly long,\nI intentionally omitted the `Base64` struct definition in this source code,\njust for brevity reasons. So, just remember that this function is a public function (or a public method) from the\n`Base64` struct.\n\nFurthermore, this `encode()` function has two other arguments:\n\n1. `input` is the input sequence of characters that you want to encode in base64;\n1. `allocator` is an allocator object to use in the necessary memory allocations.\n\nI described everything you need to know about allocator objects in @sec-allocators.\nSo, if you are not familiar with them, I highly recommend you to comeback to\nthat section, and read it.\nBy looking at the `encode()` function, you will see that we use this\nallocator object to allocate enough memory to store the output of\nthe encoding process.\n\nThe main for loop in the function is responsible for iterating through the entire input string.\nIn every iteration, we use a `count` variable to count how many iterations we had at the\nmoment. When `count` reaches 3, then, we try to encode the 3 characters (or bytes) that we have accumulated\nin the temporary buffer object (`buf`).\n\nAfter encoding these 3 characters and storing the result in the `output` variable, we reset\nthe `count` variable to zero, and start to count again on the next iteration of the loop.\nIf the loop hits the end of the string, and, the `count` variable is less than 3, then, it means that\nthe temporary buffer contains the last 1 or 2 bytes from the input.\nThat is why we have two `if` statements after the for loop. To deal which each possible case.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn encode(self: Base64,\n              allocator: std.mem.Allocator,\n              input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n\n    const n_out = try _calc_encode_length(input);\n    var out = try allocator.alloc(u8, n_out);\n    var buf = [3]u8{ 0, 0, 0 };\n    var count: u8 = 0;\n    var iout: u64 = 0;\n\n    for (input, 0..) |_, i| {\n        buf[count] = input[i];\n        count += 1;\n        if (count == 3) {\n            out[iout] = self._char_at(buf[0] >> 2);\n            out[iout + 1] = self._char_at(\n                ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n            );\n            out[iout + 2] = self._char_at(\n                ((buf[1] & 0x0f) << 2) + (buf[2] >> 6)\n            );\n            out[iout + 3] = self._char_at(buf[2] & 0x3f);\n            iout += 4;\n            count = 0;\n        }\n    }\n\n    if (count == 1) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            (buf[0] & 0x03) << 4\n        );\n        out[iout + 2] = '=';\n        out[iout + 3] = '=';\n    }\n\n    if (count == 2) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n        );\n        out[iout + 2] = self._char_at(\n            (buf[1] & 0x0f) << 2\n        );\n        out[iout + 3] = '=';\n        iout += 4;\n    }\n\n    return out;\n}\n```\n:::\n\n\n\n\n## Building the decoder logic {#sec-decoder-logic}\n\nNow, we can focus on writing the base64 decoder logic. Remember from @fig-base64-algo2 that,\na base64 decoder does the inverse process of an encoder. So, all we need to do, is to\nwrite a `decode()` function that performs the inverse process that I exposed in @sec-encoder-logic.\n\n\n### Mapping base64 characters to their indexes {#sec-map-base64-index}\n\nOne thing that we need to do, in order to decode a base64-encoded message, is to calculate\nthe index in the base64 scale of every base64 character that we encounter in the decoder input.\n\nIn other words, the decoder receives as input, a sequence of base64 characters. We need\nto translate this sequence of characters into a sequence of indexes. These indexes\nare the index of each character in the base64 scale. This way, we get the value/byte\nthat was calculated in the 6-bit transformation step of the encoder process.\n\nThere are probably better/faster ways to calculate this, especially using a \"divide and conquer\"\ntype of strategy. But for now, I am satisfied with a simple and \"brute force\" type of strategy.\nThe `_char_index()` function below contains this strategy.\n\nWe are essentially looping through the *lookup table* with the base64 scale,\nand comparing the character we got with each character in the base64 scale.\nIf these characters match, then, we return the index of this character in the\nbase64 scale as the result.\n\nNotice that, if the input character is `'='`, the function returns the index 64, which is\n\"out of range\" in the scale. But, as I described in @sec-base64-scale,\nthe character `'='` does not belong to the base64 scale itself.\nIt's a special and meaningless character in base64.\n\nAlso notice that this `_char_index()` function is a method from our `Base64` struct,\nbecause of the `self` argument. Again, I have omitted the `Base64` struct definition in this example\nfor brevity reasons.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn _char_index(self: Base64, char: u8) u8 {\n    if (char == '=')\n        return 64;\n    var index: u8 = 0;\n    for (0..63) |i| {\n        if (self._char_at(i) == char)\n            break;\n        index += 1;\n    }\n\n    return index;\n}\n```\n:::\n\n\n\n\n### The 6-bit transformation\n\nOnce again, the core part of the algorithm is the 6-bit transformation.\nIf we understand the necessary steps to perform this transformation, the rest\nof the algorithm becomes much easier.\n\nFirst of all, before we actually go to the 6-bit transformation,\nwe need to make sure that we use `_char_index()` to convert the sequence of base64 characters\ninto a sequence of indexes. So the snippet below is important for the job that will be done.\nThe result of `_char_index()` is stored in a temporary buffer, and this temporary buffer\nis what we are going to use in the 6-bit transformation, instead of the actual `input` object.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (0..input.len) |i| {\n    buf[i] = self._char_index(input[i]);\n}\n```\n:::\n\n\nNow, instead of producing 4 bytes (or 4 characters) as output per each window of 3 characters in the input,\na base64 decoder produces 3 bytes (or 3 characters) as output per each window of 4 characters in the input.\nOnce again, is the inverse process.\n\nSo, the steps to produce the 3 bytes in the output are:\n\n1. `output[0]` is produced by summing two components. First, move the bits from `buf[0]` two positions to the left. Second, move the bits from `buf[1]` 4 positions to the right. Then, sum these two components.\n1. `output[1]` is produced by summing two components. First, move the bits from `buf[1]` four positions to the left. Second, move the bits from `buf[2]` 2 positions to the right. Then, sum these two components.\n1. `output[2]` is produced by summing two components. First, move the bits from `buf[2]` six positions to the left. Then, you sum the result with `buf[3]`.\n\n\nBefore we continue, let's try to visualize how these transformations make the original bytes that we had\nbefore the encoding process. First, think back to the 6-bit transformation performed by the encoder exposed in @sec-encoder-logic.\nThe first byte in the output of the encoder is produced by moving the bits in the first byte of the input two positions to the right.\n\nIf for example the first byte in the input of the encoder was the sequence `ABCDEFGH`, then, the first byte in the output of the encoder would be\n`00ABCDEF` (this sequence would be the first byte in the input of the decoder). Now, if the second byte in the input of the encoder was the sequence\n`IJKLMNOP`, then, the second byte in the encoder output would be `00GHIJKL` (as we demonstrated in @fig-encoder-bitshift).\n\nHence, if the sequences `00ABCDEF` and `00GHIJKL` are the first and second bytes, respectively, in the input of the decoder, the\n@fig-decoder-bitshift demonstrates visually how these two bytes are transformed into the first byte of the output of the decoder.\nNotice that the output byte is the sequence `ABCDEFGH`, which is the original byte from the input of the encoder.\n\n![How the 1st byte in the decoder output is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input](../Figures/base64-decoder-bit-shift.png){#fig-decoder-bitshift}\n\nThe @tbl-6bit-decode presents how the three steps described earlier translate into Zig code:\n\n\n\n::: {#tbl-6bit-decode}\n\n| Byte index in the output | In code                       |\n|--------------------------|-------------------------------|\n| 0                        | (buf[0] << 2) + (buf[1] >> 4) |\n| 1                        | (buf[1] << 4) + (buf[2] >> 2) |\n| 2                        | (buf[2] << 6) + buf[3]        |\n\n: The necessary steps for the 6-transformation in the decode process.\n\n\n:::\n\n\n\n\n\n\n\n### Writing the `decode()` function\n\nThe `decode()` function below contains the entire decoding process.\nWe first calculate the size of the output, with\n`_calc_decode_length()`, then, we allocate enough memory for this output with\nthe allocator object.\n\nThree temporary variables are created: 1) `count`, to hold the window count\nin each iteration of the for loop; 2) `iout`, to hold the current index in the output;\n3) `buf`, which is the temporary buffer that holds the base64 indexes to be\nconverted through the 6-bit transformation.\n\nThen, in each iteration of the for loop we fill the temporary buffer with the current\nwindow of bytes. When `count` hits the number 4, then, we have a full window of\nindexes in `buf` to be converted, and then, we apply the 6-bit transformation\nover the temporary buffer.\n\nNotice that we check if the indexes 2 and 3 in the temporary buffer are the number 64, which, if you recall\nfrom @sec-map-base64-index, is when the `_calc_index()` function receives a `'='` character\nas input. So, if these indexes are equal to the number 64, the `decode()` function knows\nthat it can simply ignore these indexes. They are not converted because, as I described before,\nthe character `'='` has no meaning, despite being the end of meaningful characters in the sequence.\nSo we can safely ignore them when they appear in the sequence.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn decode(self: Base64,\n          allocator: std.mem.Allocator,\n          input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n    const n_output = try _calc_decode_length(input);\n    var output = try allocator.alloc(u8, n_output);\n    var count: u8 = 0;\n    var iout: u64 = 0;\n    var buf = [4]u8{ 0, 0, 0, 0 };\n\n    for (0..input.len) |i| {\n        buf[count] = self._char_index(input[i]);\n        count += 1;\n        if (count == 4) {\n            output[iout] = (buf[0] << 2) + (buf[1] >> 4);\n            if (buf[2] != 64) {\n                output[iout + 1] = (buf[1] << 4) + (buf[2] >> 2);\n            }\n            if (buf[3] != 64) {\n                output[iout + 2] = (buf[2] << 6) + buf[3];\n            }\n            iout += 3;\n            count = 0;\n        }\n    }\n\n    return output;\n}\n```\n:::\n\n\n\n## The end result\n\nNow that we have both `decode()` and `encode()` implemented. We have a fully functioning\nbase64 encoder/decoder implemented in Zig. Here is an usage example of our\n`Base64` struct with the `encode()` and `decode()` methods that we have implemented.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar memory_buffer: [1000]u8 = undefined;\nvar fba = std.heap.FixedBufferAllocator.init(\n    &memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst text = \"Testing some more stuff\";\nconst etext = \"VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=\";\nconst base64 = Base64.init();\nconst encoded_text = try base64.encode(\n    allocator, text\n);\nconst decoded_text = try base64.decode(\n    allocator, etext\n);\ntry stdout.print(\n    \"Encoded text: {s}\\n\", .{encoded_text}\n);\ntry stdout.print(\n    \"Decoded text: {s}\\n\", .{decoded_text}\n);\n```\n:::\n\n\n```\nEncoded text: VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=\nDecoded text: Testing some more stuff\n```\n\nYou can also see the full source code at once, by visiting the official repository of this book[^repo].\nMore precisely inside the `ZigExamples` folder[^zig-base64-algo].\n\n[^repo]: <https://github.com/pedropark99/zig-book>\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/01-memory/execute-results/epub.json b/_freeze/Chapters/01-memory/execute-results/epub.json
deleted file mode 100644
index eda130d2..00000000
--- a/_freeze/Chapters/01-memory/execute-results/epub.json
+++ /dev/null
@@ -1,21 +0,0 @@
-{
-  "hash": "55899a376e1db53689b78790e55a518d",
-  "result": {
-    "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Memory and Allocators\n\n\nIn this chapter, we will talk about memory. How does Zig control memory? What\ncommon tools are used? Are there any important aspects that make memory\ndifferent/special in Zig? You will find the answers here.\n\nComputers fundamentally rely on memory to function. This memory acts as a temporary storage\nspace for the data and values generated during computations. Without memory, the core\nconcepts of \"variables\" and \"objects\" in programming languages would be impossible.\n\n\n\n\n## Memory spaces\n\nEvery object that you create in your Zig source code needs to be stored somewhere,\nin your computer's memory. Depending on where and how you define your object, Zig\nwill use a different \"memory space\", or a different\ntype of memory to store this object.\n\nEach type of memory normally serves for different purposes.\nIn Zig, there are 3 types of memory (or 3 different memory spaces) that we care about. They are:\n\n- Global data register (or the \"global data section\");\n- Stack;\n- Heap;\n\n\n### Compile-time known versus runtime known {#sec-compile-time}\n\nOne strategy that Zig uses to decide where it will store each object that you declare, is by looking\nat the value of this particular object. More specifically, by investigating if this value is\nknown at \"compile-time\" or at \"runtime\".\n\nWhen you write a program in Zig, the values of some of the objects that you write in your program are *known\nat compile time*. Meaning that, when you compile your Zig source code, during the compilation process,\nthe `zig` compiler can figure out the exact value of a particular object\nthat exists in your source code.\nKnowing the length (or the size) of each object is also important. So the length (or the size) of each object that you write in your program is,\nin some cases, *known at compile time*.\n\nThe `zig` compiler cares more about knowing the length (or the size) of a particular object\n, than to know its actual value. But, if the `zig` compiler knows the value of the object, then, it\nautomatically knows the size of this object. Because it can simply calculate the\nsize of the object by looking at the size of the value.\n\nTherefore, the priority for the `zig` compiler is to discover the size of each object in your source code.\nIf the value of the object in question is known at compile-time, then, the `zig` compiler\nautomatically knows the size/length of this object. But if the value of this object is not\nknown at compile-time, then, the size of this object is only known at compile-time if,\nand only if, the type of this object has a known fixed size.\n\nIn order for a type to have a known fixed size, this type must have data members whose size is fixed.\nIf this type includes, for example, a variable sized array in it, then, this type does not have a known\nfixed size. Because this array can have any size at runtime\n(i.e., it can be an array of 2 elements, or 50 elements, or 1 thousand elements, etc.).\n\nFor example, a string object, which internally is an array of constant u8 values (`[]const u8`)\nhas a variable size. It can be a string object with 100 or 500 characters in it. If we do not\nknow at compile-time, which exact string will be stored inside this string object, then, we cannot calculate\nthe size of this string object at compile-time. So, any type, or any struct declaration that you make, that\nincludes a string data member that does not have an explicit fixed size, makes this type, or this\nnew struct that you are declaring, a type that does not have a known fixed size at compile-time.\n\nIn contrast, if the type of this struct that you are declaring, includes a data member that is an array,\nbut this array has a known fixed size, like `[60]u8` (which declares an array of 60 `u8` values), then,\nthis type, or, this struct that you are declaring, becomes a type with a known fixed size at compile-time.\nAnd because of that, in this case, the `zig` compiler does not need to know at compile-time the exact value of\nany object of this type. Since the compiler can find the necessary size to store this object by\nlooking at the size of its type.\n\n\nLet's look at an example. In the source code below, we have two constant objects (`name` and `array`) declared.\nBecause the values of these particular objects are written down, in the source code itself (`\"Pedro\"`\nand the number sequence from 1 to 4), the `zig` compiler can easily discover the values of these constant\nobjects (`name` and `array`) during the compilation process.\nThis is what \"known at compile time\" means. It refers to any object that you have in your Zig source code\nwhose value can be identified at compile time.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn input_length(input: []const u8) usize {\n    const n = input.len;\n    return n;\n}\n\npub fn main() !void {\n    const name = \"Pedro\";\n    const array = [_]u8{1, 2, 3, 4};\n    _ = name; _ = array;\n}\n```\n:::\n\n\n\nThe other side of the spectrum are objects whose values are not known at compile time.\nFunction arguments are a classic example of this. Because the value of each function\nargument depends on the value that you assign to this particular argument,\nwhen you call the function.\n\nFor example, the function `input_length()` contains an argument named `input`, which is an array of constant `u8` integers (`[]const u8`).\nIt's impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length\nof this particular argument. Because it's an array that does not have a fixed size specified explicitly in the argument type annotation.\n\nSo, we know that this `input` argument will be an array of `u8` integers. But we do not know at compile-time, its value, and neither its size.\nThis information is known only at runtime, which is the period of time when you program is executed.\nAs a consequence, the value of the expression `input.len` is also known only at runtime.\nThis is an intrinsic characteristic of any function. Just remember that the value of function arguments is usually not \"compile-time known\".\n\nHowever, as I mentioned earlier, what really matters to the compiler is to know the size of the object\nat compile-time, and not necessarily its value. So, although we don't know the value of the object `n`, which is the result of the expression\n`input.len`, at compile-time, we do know its size. Because the expression `input.len` always returns a value of type `usize`,\nand the type `usize` has a known fixed size.\n\n\n\n### Global data register\n\nThe global data register is a specific section of the executable of your Zig program, that is responsible\nfor storing any value that is known at compile time.\n\nEvery constant object whose value is known at compile time that you declare in your source code,\nis stored in the global data register. Also, every literal value that you write in your source code,\nsuch as the string `\"this is a string\"`, or the integer `10`, or a boolean value such as `true`,\nis also stored in the global data register.\n\nHonestly, you don't need to care much about this memory space. Because you can't control it,\nyou can't deliberately access it or use it for your own purposes.\nAlso, this memory space does not affect the logic of your program.\nIt simply exists in your program.\n\n\n### Stack vs Heap\n\nIf you are familiar with systems programming, or just low-level programming in general, you\nprobably have heard of the \"duel\" between Stack vs Heap. These are two different types of memory,\nor different memory spaces, which are both available in Zig.\n\nThese two types of memory don't actually duel with\neach other. This is a common mistake that beginners have, when seeing \"x vs y\" styles of\ntabloid headlines. These two types of memory are actually complementary to each other.\nSo, in almost every Zig program that you ever write, you will likely use a combination of both.\nI will describe each memory space in detail over the next sections. But for now, I just want to\nstablish the main difference between these two types of memory.\n\nIn essence, the stack memory is normally used to store values whose length is fixed and known\nat compile time. In contrast, the heap memory is a *dynamic* type of memory space, meaning that, it's\nused to store values whose length might grow during the execution (runtime) of your program [@jenny2022].\n\nLengths that grow during runtime are intrinsically associated with \"runtime known\" type of values.\nIn other words, if you have an object whose length might grow during runtime, then, the length\nof this object becomes not known at compile time. If the length is not known at compile-time,\nthe value of this object also becomes not known at compile-time.\nThese types of objects should be stored in the heap memory space, which is\na dynamic memory space, which can grow or shrink to fit the size of your objects.\n\n\n\n### Stack {#sec-stack}\n\nThe stack is a type of memory that uses the power of the *stack data structure*, hence the name.\nA \"stack\" is a type of *data structure* that uses a \"last in, first out\" (LIFO) mechanism to store the values\nyou give it to. I imagine you are familiar with this data structure.\nBut, if you are not, the [Wikipedia page](https://en.wikipedia.org/wiki/Stack_(abstract_data_type))[^wiki-stack]\n, or, the [Geeks For Geeks page](https://www.geeksforgeeks.org/stack-data-structure/)[^geek-stack] are both\nexcellent and easy resources to fully understand how this data structure works.\n\n[^wiki-stack]: <https://en.wikipedia.org/wiki/Stack_(abstract_data_type)>\n[^geek-stack]: <https://www.geeksforgeeks.org/stack-data-structure/>\n\nSo, the stack memory space is a type of memory that stores values using a stack data structure.\nIt adds and removes values from the memory by following a \"last in, first out\" (LIFO) principle.\n\nEvery time you make a function call in Zig, an amount of space in the stack is\nreserved for this particular function call [@jenny2022; @zigdocs].\nThe value of each function argument given to the function in this function call is stored in this\nstack space. Also, every local object that you declare inside the function scope is\nusually stored in this same stack space.\n\n\nLooking at the example below, the object `result` is a local object declared inside the scope of the `add()`\nfunction. Because of that, this object is stored inside the stack space reserved for the `add()` function.\nThe `r` object (which is declared outside of the `add()` function scope) is also stored in the stack.\nBut since it's declared in the \"outer\" scope, this object is stored in the\nstack space that belongs to this outer scope.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn add(x: u8, y: u8) u8 {\n    const result = x + y;\n    return result;\n}\n\npub fn main() !void {\n    const r = add(5, 27);\n    _ = r;\n}\n```\n:::\n\n\n\n\nSo, any object that you declare inside the scope of a function is always stored inside\nthe space that was reserved for that particular function in the stack memory. This\nalso counts for any object declared inside the scope of your `main()` function for example.\nAs you would expect, in this case, they\nare stored inside the stack space reserved for the `main()` function.\n\nOne very important detail about the stack memory is that **it frees itself automatically**.\nThis is very important, remember that. When objects are stored in the stack memory,\nyou don't have the work (or the responsibility) of freeing/destroying these objects.\nBecause they will be automatically destroyed once the stack space is freed at the end of the function scope.\n\nSo, once the function call returns (or ends, if you prefer to call it this way)\nthe space that was reserved in the stack is destroyed, and all of the objects that were in that space goes away with it.\nThis mechanism exists because this space, and the objects within it, are not necessary anymore,\nsince the function \"finished its business\".\nUsing the `add()` function that we exposed above as an example, it means that the object `result` is automatically\ndestroyed once the function returns.\n\n::: {.callout-important}\nLocal objects that are stored in the stack space of a function are automatically\nfreed/destroyed at the end of the function scope.\n:::\n\n\nThis same logic applies to any other special structure in Zig that has its own scope by surrounding\nit with curly braces (`{}`).\nFor loops, while loops, if else statements, etc. For example, if you declare any local\nobject in the scope of a for loop, this local object is accessible only within the scope\nof this particular for loop. Because once the scope of this for loop ends, the space in the stack\nreserved for this for loop is freed.\nThe example below demonstrates this idea.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This does not compile successfully!\nconst a = [_]u8{0, 1, 2, 3, 4};\nfor (0..a.len) |i| {\n    const index = i;\n    _ = index;\n}\n// Trying to use an object that was\n// declared in the for loop scope,\n// and that does not exist anymore.\nstd.debug.print(\"{d}\\n\", .{index});\n```\n:::\n\n\n\n\n\nOne important consequence of this mechanism is that, once the function returns, you can no longer access any memory\naddress that was inside the space in the stack reserved for this particular function. Because this space was\ndestroyed. This means that, if this local object is stored in the stack,\nyou cannot make a function that **returns a pointer to this object**.\n\nThink about that for a second. If all local objects in the stack are destroyed at the end of the function scope, why\nwould you even consider returning a pointer to one of these objects? This pointer is at best,\ninvalid, or, more likely, \"undefined\".\n\nIn conclusion, it's totally fine to write a function that returns the local object\nitself as result, because then, you return the value of that object as the result.\nBut, if this local object is stored in the stack, you should never write a function\nthat returns a pointer to this local object. Because the memory address pointed by the pointer\nno longer exists.\n\n\nSo, using again the `add()` function as an example, if you rewrite this function so that it\nreturns a pointer to the local object `result`, the `zig` compiler will actually compile\nyour program, with no warnings or errors. At first glance, it looks like this is good code\nthat works as expected. But this is a lie!\n\nIf you try to take a look at the value inside of the `r` object,\nor, if you try to use this `r` object in another expression\nor function call, then, you would have undefined behaviour, and major\nbugs in your program [@zigdocs, see \"Lifetime and Ownership\"[^life] and \"Undefined Behaviour\"[^undef] sections].\n\n[^life]: <https://ziglang.org/documentation/master/#Lifetime-and-Ownership>\n[^undef]: <https://ziglang.org/documentation/master/#Undefined-Behavior>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn add(x: u8, y: u8) *const u8 {\n    const result = x + y;\n    return &result;\n}\n\npub fn main() !void {\n    // This code compiles successfully. But it has\n    // undefined behaviour. Never do this!!!\n    // The `r` object is undefined!\n    const r = add(5, 27); _ = r;\n}\n```\n:::\n\n\n\nThis \"invalid pointer to stack variable\" problem is well known across many programming language communities.\nIf you try to do the same thing, for example, in a C or C++ program (i.e., returning an address to\na local object stored in the stack), you would also get undefined behaviour\nin the program.\n\n::: {.callout-important}\nIf a local object in your function is stored in the stack, you should never\nreturn a pointer to this local object from the function. Because\nthis pointer will always become undefined after the function returns, since the stack space of the function\nis destroyed at the end of its scope.\n:::\n\nBut what if you really need to use this local object in some way after your function returns?\nHow can you do this? The answer is: \"in the same way you would do if this were a C or C++ program. By returning\nan address to an object stored in the heap\". The heap memory has a much more flexible lifecycle,\nand allows you to get a valid pointer to a local object of a function that already returned\nfrom its scope.\n\n\n### Heap {#sec-heap}\n\nOne important limitation of the stack, is that, only objects whose length/size is known at compile-time can be\nstored in it. In contrast, the heap is a much more dynamic\n(and flexible) type of memory. It's the perfect type of memory to use\nfor objects whose size/length might grow during the execution of your program.\n\nVirtually any application that behaves as a server is a classic use case of the heap.\nA HTTP server, a SSH server, a DNS server, a LSP server, ... any type of server.\nIn summary, a server is a type of application that runs for long periods of time,\nand that serves (or \"deals with\") any incoming request that reaches this particular server.\n\nThe heap is a good choice for this type of system, mainly because the server does not know upfront\nhow many requests it will receive from users, while it is active. It could be a single request,\n5 thousand requests, or even zero requests.\nThe server needs to have the ability to allocate and manage its memory according to how many requests it receives.\n\nAnother key difference between the stack and the heap, is that the heap is a type\nof memory that you, the programmer, have complete control over. This makes the heap a\nmore flexible type of memory, but it also makes it harder to work with. Because you,\nthe programmer, is responsible for managing everything related to it. Including where the memory is allocated,\nhow much memory is allocated, and where this memory is freed.\n\n> Unlike stack memory, heap memory is allocated explicitly by programmers and it won’t be deallocated until it is explicitly freed [@jenny2022].\n\nTo store an object in the heap, you, the programmer, needs to explicitly tells Zig to do so,\nby using an allocator to allocate some space in the heap. In @sec-allocators, I will present how you can use allocators to allocate memory\nin Zig.\n\n::: {.callout-important}\nEvery memory you allocate in the heap needs to be explicitly freed by you, the programmer.\n:::\n\nThe majority of allocators in Zig do allocate memory on the heap. But some exceptions to this rule are\n`ArenaAllocator()` and `FixedBufferAllocator()`. The `ArenaAllocator()` is a special\ntype of allocator that works in conjunction with a second type of allocator.\nOn the other side, the `FixedBufferAllocator()` is an allocator that works based on\nbuffer objects created on the stack. This means that the `FixedBufferAllocator()` makes\nallocations only on the stack.\n\n\n\n\n### Summary\n\nAfter discussing all of these boring details, we can quickly recap what we learned.\nIn summary, the Zig compiler will use the following rules to decide where each\nobject you declare is stored:\n\n1. every literal value (such as `\"this is string\"`, `10`, or `true`) is stored in the global data section.\n1. every constant object (`const`) whose value **is known at compile-time** is also stored in the global data section.\n1. every object (constant or not) whose length/size **is known at compile time** is stored in the stack space for the current scope.\n1. if an object is created with the method `alloc()` or `create()` of an allocator object, this object is stored in the memory space used by this particular allocator object. Most of allocators available in Zig use the heap memory, so, this object is likely stored in the heap (`FixedBufferAllocator()` is an exception to that).\n1. the heap can only be accessed through allocators. If your object was not created through the `alloc()` or `create()` methods of an allocator object, then, it is most certainly not an object stored in the heap.\n\n\n## Stack overflows {#sec-stack-overflow}\n\nAllocating memory on the stack is generally faster than allocating it on the heap.\nBut this better performance comes with many restrictions. We have already discussed\nmany of these restrictions of the stack in @sec-stack. But there is one more important\nlimitation that I want to talk about, which is the size of the stack itself.\n\nThe stack is limited in size. This size varies from computer to computer, and it depends on\na lot of things (the computer architecture, the operating system, etc.). Nevertheless, this size is usually\nnot that big. This is why we normally use the stack to store only temporary and small objects in memory.\n\nIn essence, if you try to make an allocation on the stack, that is so big that exceeds the stack size limit,\na *stack overflow* happens, and your program just crashes as a result of that. In other words, a stack overflow happens when\nyou attempt to use more space than is available on the stack.\n\nThis type of problem is very similar to a *buffer overflow*, i.e., you are trying to use more space\nthan is available in the \"buffer object\". However, a stack overflow always causes your program to crash,\nwhile a buffer overflow does not always cause your program to crash (although it often does).\n\nYou can see an example of a stack overflow in the example below. We are trying to allocate a very big array of `u64` values\non the stack. You can see below that this program does not run successfully, because it crashed\nwith a \"segmentation fault\" error message.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar very_big_alloc: [1000 * 1000 * 24]u64 = undefined;\n@memset(very_big_alloc[0..], 0);\n```\n:::\n\n\n\n```\nSegmentation fault (core dumped)\n```\n\nThis segmentation fault error is a result of the stack overflow that was caused by the big\nmemory allocation made on the stack, to store the `very_big_alloc` object.\nThis is why very big objects are usually stored on the heap, instead of the stack.\n\n\n\n## Allocators {#sec-allocators}\n\nOne key aspect about Zig, is that there are \"no hidden-memory allocations\" in Zig.\nWhat that really means, is that \"no allocations happen behind your back in the standard library\" [@zigguide].\n\nThis is a known problem, especially in C++. Because in C++, there are some operators that do allocate\nmemory behind the scene, and there is no way for you to know that, until you actually read the\nsource code of these operators, and find the memory allocation calls.\nMany programmers find this behaviour annoying and hard to keep track of.\n\nBut, in Zig, if a function, an operator, or anything from the standard library\nneeds to allocate some memory during its execution, then, this function/operator needs to receive (as input) an allocator\nprovided by the user, to actually be able to allocate the memory it needs.\n\nThis creates a clear distinction between functions that \"do not\" from those that \"actually do\"\nallocate memory. Just look at the arguments of this function.\nIf a function, or operator, has an allocator object as one of its inputs/arguments, then, you know for\nsure that this function/operator will allocate some memory during its execution.\n\nAn example is the `allocPrint()` function from the Zig Standard Library. With this function, you can\nwrite a new string using format specifiers. So, this function is, for example, very similar to the function `sprintf()` in C.\nIn order to write such a new string, the `allocPrint()` function needs to allocate some memory to store the\noutput string.\n\nThat is why, the first argument of this function is an allocator object that you, the user/programmer, gives\nas input to the function. In the example below, I am using the `GeneralPurposeAllocator()` as my allocator\nobject. But I could easily use any other type of allocator object from the Zig Standard Library.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst name = \"Pedro\";\nconst output = try std.fmt.allocPrint(\n    allocator,\n    \"Hello {s}!!!\",\n    .{name}\n);\ntry stdout.print(\"{s}\\n\", .{output});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello Pedro!!!\n```\n\n\n:::\n:::\n\n\n\n\nYou get a lot of control over where and how much memory this function can allocate.\nBecause it is you, the user/programmer, that provides the allocator for the function to use.\nThis makes \"total control\" over memory management easier to achieve in Zig.\n\n### What are allocators?\n\nAllocators in Zig are objects that you can use to allocate memory for your program.\nThey are similar to the memory allocating functions in C, like `malloc()` and `calloc()`.\nSo, if you need to use more memory than you initially have, during the execution of your program, you can simply ask\nfor more memory by using an allocator object.\n\nZig offers different types of allocators, and they are usually available through the `std.heap` module of\nthe standard library. Thus, just import the Zig Standard Library into your Zig module (with `@import(\"std\")`), and you can start\nusing these allocators in your code.\n\nFurthermore, every allocator object is built on top of the `Allocator` interface in Zig.\nThis means that, every allocator object you find in Zig must have the methods `alloc()`,\n`create()`, `free()` and `destroy()`. So, you can change the type of allocator you are using,\nbut you don't need to change the function calls to the methods that do the memory allocation\n(and the free memory operations) for your program.\n\n### Why you need an allocator?\n\nAs we described in @sec-stack, everytime you make a function call in Zig,\na space in the stack is reserved for this function call. But the stack\nhas a key limitation which is: every object stored in the stack has a\nknown fixed length.\n\nBut in reality, there are two very common instances where this \"fixed length limitation\" of the stack is a deal braker:\n\n1. the objects that you create inside your function might grow in size during the execution of the function.\n1. sometimes, it's impossible to know upfront how many inputs you will receive, or how big this input will be.\n\nAlso, there is another instance where you might want to use an allocator, which is when you want to write a function that returns a pointer\nto a local object. As I described in @sec-stack, you cannot do that if this local object is stored in the\nstack. However, if this object is stored in the heap, then, you can return a pointer to this object at the\nend of the function. Because you (the programmer) control the lifetime of any heap memory that you allocate. You decide\nwhen this memory gets destroyed/freed.\n\nThese are common situations for which the stack is not good.\nThat is why you need a different memory management strategy to\nstore these objects inside your function. You need to use\na memory type that can grow together with your objects, or that you\ncan control the lifetime of this memory.\nThe heap fits this description.\n\nAllocating memory on the heap is commonly known as dynamic memory management. As the objects you create grow in size\nduring the execution of your program, you grow the amount of memory\nyou have by allocating more memory in the heap to store these objects.\nAnd you do that in Zig, by using an allocator object.\n\n\n### The different types of allocators\n\n\nAt the moment of the writing of this book, in Zig, we have 6 different\nallocators available in the standard library:\n\n- `GeneralPurposeAllocator()`.\n- `page_allocator()`.\n- `FixedBufferAllocator()` and `ThreadSafeFixedBufferAllocator()`.\n- `ArenaAllocator()`.\n- `c_allocator()` (requires you to link to libc).\n\n\nEach allocator has its own perks and limitations. All allocators, except `FixedBufferAllocator()` and `ArenaAllocator()`,\nare allocators that use the heap memory. So any memory that you allocate with\nthese allocators, will be placed in the heap.\n\n### General-purpose allocators\n\nThe `GeneralPurposeAllocator()`, as the name suggests, is a \"general purpose\" allocator. You can use it for every type\nof task. In the example below, I'm allocating enough space to store a single integer in the object `some_number`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const some_number = try allocator.create(u32);\n    defer allocator.destroy(some_number);\n\n    some_number.* = @as(u32, 45);\n}\n```\n:::\n\n\n\n\nWhile useful, you might want to use the `c_allocator()`, which is a alias to the C standard allocator `malloc()`. So, yes, you can use\n`malloc()` in Zig if you want to. Just use the `c_allocator()` from the Zig standard library. However,\nif you do use `c_allocator()`, you must link to Libc when compiling your source code with the\n`zig` compiler, by including the flag `-lc` in your compilation process.\nIf you do not link your source code to Libc, Zig will not be able to find the\n`malloc()` implementation in your system.\n\n### Page allocator\n\nThe `page_allocator()` is an allocator that allocates full pages of memory in the heap. In other words,\nevery time you allocate memory with `page_allocator()`, a full page of memory in the heap is allocated,\ninstead of just a small piece of it.\n\nThe size of this page depends on the system you are using.\nMost systems use a page size of 4KB in the heap, so, that is the amount of memory that is normally\nallocated in each call by `page_allocator()`. That is why, `page_allocator()` is considered a\nfast, but also \"wasteful\" allocator in Zig. Because it allocates a big amount of memory\nin each call, and you most likely will not need that much memory in your program.\n\n### Buffer allocators\n\nThe `FixedBufferAllocator()` and `ThreadSafeFixedBufferAllocator()` are allocator objects that\nwork with a fixed sized buffer object at the back. In other words, they use a fixed sized buffer\nobject as the basis for the memory. When you ask these allocator objects to allocate some memory for you,\nthey are essentially reserving some amount of space inside this fixed sized buffer object for you to use.\n\nThis means that, in order to use these allocators, you must first create a buffer object in your code,\nand then, give this buffer object as an input to these allocators.\n\nThis also means that, these allocator objects can allocate memory both in the stack or in the heap.\nEverything depends on where the buffer object that you provide lives. If this buffer object lives\nin the stack, then, the memory allocated is \"stack-based\". But if it lives on the heap, then,\nthe memory allocated is \"heap-based\".\n\n\nIn the example below, I'm creating a `buffer` object on the stack that is 10 elements long.\nNotice that I give this `buffer` object to the `FixedBufferAllocator()` constructor.\nNow, because this `buffer` object is 10 elements long, this means that I am limited to this space.\nI cannot allocate more than 10 elements with this allocator object. If I try to\nallocate more than that, the `alloc()` method will return an `OutOfMemory` error value.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar buffer: [10]u8 = undefined;\nfor (0..buffer.len) |i| {\n    buffer[i] = 0; // Initialize to zero\n}\n\nvar fba = std.heap.FixedBufferAllocator.init(&buffer);\nconst allocator = fba.allocator();\nconst input = try allocator.alloc(u8, 5);\ndefer allocator.free(input);\n```\n:::\n\n\n\nRemember, the memory allocated by these allocator objects can be either from\nthe stack, or, from the heap. It all depends on where the buffer object that you provide lives.\nIn the above example, the `buffer` object lives in the stack, and, therefore, the memory allocated\nis based in the stack. But what if it was based on the heap?\n\nAs we described in @sec-stack-overflow, one of the main reasons why you would use the heap,\ninstead of the stack, is to allocate huge amounts of space to store very big objects.\nThus, let's suppose you wanted to use a very big buffer object as the basis for your\nallocator objects. You would have to allocate this very big buffer object on the heap.\nThe example below demonstrates this case.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst heap = std.heap.page_allocator;\nconst memory_buffer = try heap.alloc(\n    u8, 100 * 1024 * 1024 // 100 MB memory\n);\ndefer heap.free(memory_buffer);\nvar fba = std.heap.FixedBufferAllocator.init(\n    memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst input = try allocator.alloc(u8, 1000);\ndefer allocator.free(input);\n```\n:::\n\n\n\n\n\n### Arena allocator {#sec-arena-allocator}\n\nThe `ArenaAllocator()` is an allocator object that takes a child allocator as input. The idea behind the `ArenaAllocator()` in Zig\nis similar to the concept of \"arenas\" in the programming language Go[^go-arena]. It's an allocator object that allows you\nto allocate memory as many times you want, but free all memory only once.\nIn other words, if you have, for example, called 5 times the method `alloc()` of an `ArenaAllocator()` object, you can\nfree all the memory you allocated over these 5 calls at once, by simply calling the `deinit()` method of the same `ArenaAllocator()` object.\n\n[^go-arena]: <https://go.dev/src/arena/arena.go>\n\nIf you give, for example, a `GeneralPurposeAllocator()` object as input to the `ArenaAllocator()` constructor, like in the example below, then, the allocations\nyou perform with `alloc()` will actually be made with the underlying object `GeneralPurposeAllocator()` that was passed.\nSo, with an arena allocator, any new memory you ask for is allocated by the child allocator. The only thing that an arena allocator\nreally does is help you to free all the memory you allocated multiple times with just a single command. In the example\nbelow, I called `alloc()` 3 times. So, if I did not use an arena allocator, then, I would need to call\n`free()` 3 times to free all the allocated memory.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nvar aa = std.heap.ArenaAllocator.init(gpa.allocator());\ndefer aa.deinit();\nconst allocator = aa.allocator();\n\nconst in1 = try allocator.alloc(u8, 5);\nconst in2 = try allocator.alloc(u8, 10);\nconst in3 = try allocator.alloc(u8, 15);\n_ = in1; _ = in2; _ = in3;\n```\n:::\n\n\n\n\n\n### The `alloc()` and `free()` methods\n\nIn the code example below, we are accessing the `stdin`, which is\nthe standard input channel, to receive an input from the\nuser. We read the input given by the user with the `readUntilDelimiterOrEof()`\nmethod.\n\nNow, after reading the input of the user, we need to store this input somewhere in\nour program. That is why I use an allocator in this example. I use it to allocate some\namount of memory to store this input given by the user. More specifically, the method `alloc()`\nof the allocator object is used to allocate an array capable of storing 50 `u8` values.\n\nNotice that this `alloc()` method receives two inputs. The first one, is a type.\nThis defines what type of values the allocated array will store. In the example\nbelow, we are allocating an array of unsigned 8-bit integers (`u8`). But\nyou can create an array to store any type of value you want. Next, in the second argument, we\ndefine the size of the allocated array, by specifying how many elements\nthis array will contain. In the case below, we are allocating an array of 50 elements.\n\nIn @sec-zig-strings we described that strings in Zig are simply arrays of characters.\nEach character is represented by a `u8` value. So, this means that the array that\nwas allocated in the object `input` is capable of storing a string that is\n50-characters long.\n\nSo, in essence, the expression `var input: [50]u8 = undefined` would create\nan array for 50 `u8` values in the stack of the current scope. But, you\ncan allocate the same array in the heap by using the expression `var input = try allocator.alloc(u8, 50)`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdin = std.io.getStdIn();\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var input = try allocator.alloc(u8, 50);\n    defer allocator.free(input);\n    for (0..input.len) |i| {\n        input[i] = 0; // initialize all fields to zero.\n    }\n    // read user input\n    const input_reader = stdin.reader();\n    _ = try input_reader.readUntilDelimiterOrEof(\n        input,\n        '\\n'\n    );\n    std.debug.print(\"{s}\\n\", .{input});\n}\n```\n:::\n\n\n\nAlso, notice that in this example, we use the `defer` keyword (which I described in @sec-defer) to run a small\npiece of code at the end of the current scope, which is the expression `allocator.free(input)`.\nWhen you execute this expression, the allocator will free the memory that it allocated\nfor the `input` object.\n\nWe have talked about this in @sec-heap. You **should always** explicitly free any memory that you allocate\nusing an allocator! You do that by using the `free()` method of the same allocator object you\nused to allocate this memory. The `defer` keyword is used in this example only to help us execute\nthis free operation at the end of the current scope.\n\n\n### The `create()` and `destroy()` methods\n\nWith the `alloc()` and `free()` methods, you can allocate memory to store multiple elements\nat once. In other words, with these methods, we always allocate an array to store multiple elements at once.\nBut what if you need enough space to store just a single item? Should you\nallocate an array of a single element through `alloc()`?\n\nThe answer is no! In this case,\nyou should use the `create()` method of the allocator object.\nEvery allocator object offers the `create()` and `destroy()` methods,\nwhich are used to allocate and free memory for a single item, respectively.\n\nSo, in essence, if you want to allocate memory to store an array of elements, you\nshould use `alloc()` and `free()`. But if you need to store just a single item,\nthen, the `create()` and `destroy()` methods are ideal for you.\n\nIn the example below, I'm defining a struct to represent an user of some sort.\nIt could be a user for a game, or software to manage resources, it doesn't mater.\nNotice that I use the `create()` method this time, to store a single `User` object\nin the program. Also notice that I use the `destroy()` method to free the memory\nused by this object at the end of the scope.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst User = struct {\n    id: usize,\n    name: []const u8,\n\n    pub fn init(id: usize, name: []const u8) User {\n        return .{ .id = id, .name = name };\n    }\n};\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const user = try allocator.create(User);\n    defer allocator.destroy(user);\n\n    user.* = User.init(0, \"Pedro\");\n}\n```\n:::\n",
-    "supporting": [
-      "01-memory_files"
-    ],
-    "filters": [
-      "rmarkdown/pagebreak.lua"
-    ],
-    "includes": {},
-    "engineDependencies": {
-      "knitr": [
-        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
-      ]
-    },
-    "preserve": null,
-    "postProcess": false
-  }
-}
\ No newline at end of file
diff --git a/_freeze/Chapters/01-memory/execute-results/html.json b/_freeze/Chapters/01-memory/execute-results/html.json
index 269c7d87..9f9e16f9 100644
--- a/_freeze/Chapters/01-memory/execute-results/html.json
+++ b/_freeze/Chapters/01-memory/execute-results/html.json
@@ -2,10 +2,8 @@
   "hash": "55899a376e1db53689b78790e55a518d",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Memory and Allocators\n\n\nIn this chapter, we will talk about memory. How does Zig control memory? What\ncommon tools are used? Are there any important aspects that make memory\ndifferent/special in Zig? You will find the answers here.\n\nComputers fundamentally rely on memory to function. This memory acts as a temporary storage\nspace for the data and values generated during computations. Without memory, the core\nconcepts of \"variables\" and \"objects\" in programming languages would be impossible.\n\n\n\n\n## Memory spaces\n\nEvery object that you create in your Zig source code needs to be stored somewhere,\nin your computer's memory. Depending on where and how you define your object, Zig\nwill use a different \"memory space\", or a different\ntype of memory to store this object.\n\nEach type of memory normally serves for different purposes.\nIn Zig, there are 3 types of memory (or 3 different memory spaces) that we care about. They are:\n\n- Global data register (or the \"global data section\");\n- Stack;\n- Heap;\n\n\n### Compile-time known versus runtime known {#sec-compile-time}\n\nOne strategy that Zig uses to decide where it will store each object that you declare, is by looking\nat the value of this particular object. More specifically, by investigating if this value is\nknown at \"compile-time\" or at \"runtime\".\n\nWhen you write a program in Zig, the values of some of the objects that you write in your program are *known\nat compile time*. Meaning that, when you compile your Zig source code, during the compilation process,\nthe `zig` compiler can figure out the exact value of a particular object\nthat exists in your source code.\nKnowing the length (or the size) of each object is also important. So the length (or the size) of each object that you write in your program is,\nin some cases, *known at compile time*.\n\nThe `zig` compiler cares more about knowing the length (or the size) of a particular object\n, than to know its actual value. But, if the `zig` compiler knows the value of the object, then, it\nautomatically knows the size of this object. Because it can simply calculate the\nsize of the object by looking at the size of the value.\n\nTherefore, the priority for the `zig` compiler is to discover the size of each object in your source code.\nIf the value of the object in question is known at compile-time, then, the `zig` compiler\nautomatically knows the size/length of this object. But if the value of this object is not\nknown at compile-time, then, the size of this object is only known at compile-time if,\nand only if, the type of this object has a known fixed size.\n\nIn order for a type to have a known fixed size, this type must have data members whose size is fixed.\nIf this type includes, for example, a variable sized array in it, then, this type does not have a known\nfixed size. Because this array can have any size at runtime\n(i.e., it can be an array of 2 elements, or 50 elements, or 1 thousand elements, etc.).\n\nFor example, a string object, which internally is an array of constant u8 values (`[]const u8`)\nhas a variable size. It can be a string object with 100 or 500 characters in it. If we do not\nknow at compile-time, which exact string will be stored inside this string object, then, we cannot calculate\nthe size of this string object at compile-time. So, any type, or any struct declaration that you make, that\nincludes a string data member that does not have an explicit fixed size, makes this type, or this\nnew struct that you are declaring, a type that does not have a known fixed size at compile-time.\n\nIn contrast, if the type of this struct that you are declaring, includes a data member that is an array,\nbut this array has a known fixed size, like `[60]u8` (which declares an array of 60 `u8` values), then,\nthis type, or, this struct that you are declaring, becomes a type with a known fixed size at compile-time.\nAnd because of that, in this case, the `zig` compiler does not need to know at compile-time the exact value of\nany object of this type. Since the compiler can find the necessary size to store this object by\nlooking at the size of its type.\n\n\nLet's look at an example. In the source code below, we have two constant objects (`name` and `array`) declared.\nBecause the values of these particular objects are written down, in the source code itself (`\"Pedro\"`\nand the number sequence from 1 to 4), the `zig` compiler can easily discover the values of these constant\nobjects (`name` and `array`) during the compilation process.\nThis is what \"known at compile time\" means. It refers to any object that you have in your Zig source code\nwhose value can be identified at compile time.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn input_length(input: []const u8) usize {\n    const n = input.len;\n    return n;\n}\n\npub fn main() !void {\n    const name = \"Pedro\";\n    const array = [_]u8{1, 2, 3, 4};\n    _ = name; _ = array;\n}\n```\n:::\n\n\n\n\nThe other side of the spectrum are objects whose values are not known at compile time.\nFunction arguments are a classic example of this. Because the value of each function\nargument depends on the value that you assign to this particular argument,\nwhen you call the function.\n\nFor example, the function `input_length()` contains an argument named `input`, which is an array of constant `u8` integers (`[]const u8`).\nIt's impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length\nof this particular argument. Because it's an array that does not have a fixed size specified explicitly in the argument type annotation.\n\nSo, we know that this `input` argument will be an array of `u8` integers. But we do not know at compile-time, its value, and neither its size.\nThis information is known only at runtime, which is the period of time when you program is executed.\nAs a consequence, the value of the expression `input.len` is also known only at runtime.\nThis is an intrinsic characteristic of any function. Just remember that the value of function arguments is usually not \"compile-time known\".\n\nHowever, as I mentioned earlier, what really matters to the compiler is to know the size of the object\nat compile-time, and not necessarily its value. So, although we don't know the value of the object `n`, which is the result of the expression\n`input.len`, at compile-time, we do know its size. Because the expression `input.len` always returns a value of type `usize`,\nand the type `usize` has a known fixed size.\n\n\n\n### Global data register\n\nThe global data register is a specific section of the executable of your Zig program, that is responsible\nfor storing any value that is known at compile time.\n\nEvery constant object whose value is known at compile time that you declare in your source code,\nis stored in the global data register. Also, every literal value that you write in your source code,\nsuch as the string `\"this is a string\"`, or the integer `10`, or a boolean value such as `true`,\nis also stored in the global data register.\n\nHonestly, you don't need to care much about this memory space. Because you can't control it,\nyou can't deliberately access it or use it for your own purposes.\nAlso, this memory space does not affect the logic of your program.\nIt simply exists in your program.\n\n\n### Stack vs Heap\n\nIf you are familiar with systems programming, or just low-level programming in general, you\nprobably have heard of the \"duel\" between Stack vs Heap. These are two different types of memory,\nor different memory spaces, which are both available in Zig.\n\nThese two types of memory don't actually duel with\neach other. This is a common mistake that beginners have, when seeing \"x vs y\" styles of\ntabloid headlines. These two types of memory are actually complementary to each other.\nSo, in almost every Zig program that you ever write, you will likely use a combination of both.\nI will describe each memory space in detail over the next sections. But for now, I just want to\nstablish the main difference between these two types of memory.\n\nIn essence, the stack memory is normally used to store values whose length is fixed and known\nat compile time. In contrast, the heap memory is a *dynamic* type of memory space, meaning that, it's\nused to store values whose length might grow during the execution (runtime) of your program [@jenny2022].\n\nLengths that grow during runtime are intrinsically associated with \"runtime known\" type of values.\nIn other words, if you have an object whose length might grow during runtime, then, the length\nof this object becomes not known at compile time. If the length is not known at compile-time,\nthe value of this object also becomes not known at compile-time.\nThese types of objects should be stored in the heap memory space, which is\na dynamic memory space, which can grow or shrink to fit the size of your objects.\n\n\n\n### Stack {#sec-stack}\n\nThe stack is a type of memory that uses the power of the *stack data structure*, hence the name.\nA \"stack\" is a type of *data structure* that uses a \"last in, first out\" (LIFO) mechanism to store the values\nyou give it to. I imagine you are familiar with this data structure.\nBut, if you are not, the [Wikipedia page](https://en.wikipedia.org/wiki/Stack_(abstract_data_type))[^wiki-stack]\n, or, the [Geeks For Geeks page](https://www.geeksforgeeks.org/stack-data-structure/)[^geek-stack] are both\nexcellent and easy resources to fully understand how this data structure works.\n\n[^wiki-stack]: <https://en.wikipedia.org/wiki/Stack_(abstract_data_type)>\n[^geek-stack]: <https://www.geeksforgeeks.org/stack-data-structure/>\n\nSo, the stack memory space is a type of memory that stores values using a stack data structure.\nIt adds and removes values from the memory by following a \"last in, first out\" (LIFO) principle.\n\nEvery time you make a function call in Zig, an amount of space in the stack is\nreserved for this particular function call [@jenny2022; @zigdocs].\nThe value of each function argument given to the function in this function call is stored in this\nstack space. Also, every local object that you declare inside the function scope is\nusually stored in this same stack space.\n\n\nLooking at the example below, the object `result` is a local object declared inside the scope of the `add()`\nfunction. Because of that, this object is stored inside the stack space reserved for the `add()` function.\nThe `r` object (which is declared outside of the `add()` function scope) is also stored in the stack.\nBut since it's declared in the \"outer\" scope, this object is stored in the\nstack space that belongs to this outer scope.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn add(x: u8, y: u8) u8 {\n    const result = x + y;\n    return result;\n}\n\npub fn main() !void {\n    const r = add(5, 27);\n    _ = r;\n}\n```\n:::\n\n\n\n\n\nSo, any object that you declare inside the scope of a function is always stored inside\nthe space that was reserved for that particular function in the stack memory. This\nalso counts for any object declared inside the scope of your `main()` function for example.\nAs you would expect, in this case, they\nare stored inside the stack space reserved for the `main()` function.\n\nOne very important detail about the stack memory is that **it frees itself automatically**.\nThis is very important, remember that. When objects are stored in the stack memory,\nyou don't have the work (or the responsibility) of freeing/destroying these objects.\nBecause they will be automatically destroyed once the stack space is freed at the end of the function scope.\n\nSo, once the function call returns (or ends, if you prefer to call it this way)\nthe space that was reserved in the stack is destroyed, and all of the objects that were in that space goes away with it.\nThis mechanism exists because this space, and the objects within it, are not necessary anymore,\nsince the function \"finished its business\".\nUsing the `add()` function that we exposed above as an example, it means that the object `result` is automatically\ndestroyed once the function returns.\n\n::: {.callout-important}\nLocal objects that are stored in the stack space of a function are automatically\nfreed/destroyed at the end of the function scope.\n:::\n\n\nThis same logic applies to any other special structure in Zig that has its own scope by surrounding\nit with curly braces (`{}`).\nFor loops, while loops, if else statements, etc. For example, if you declare any local\nobject in the scope of a for loop, this local object is accessible only within the scope\nof this particular for loop. Because once the scope of this for loop ends, the space in the stack\nreserved for this for loop is freed.\nThe example below demonstrates this idea.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This does not compile successfully!\nconst a = [_]u8{0, 1, 2, 3, 4};\nfor (0..a.len) |i| {\n    const index = i;\n    _ = index;\n}\n// Trying to use an object that was\n// declared in the for loop scope,\n// and that does not exist anymore.\nstd.debug.print(\"{d}\\n\", .{index});\n```\n:::\n\n\n\n\n\n\nOne important consequence of this mechanism is that, once the function returns, you can no longer access any memory\naddress that was inside the space in the stack reserved for this particular function. Because this space was\ndestroyed. This means that, if this local object is stored in the stack,\nyou cannot make a function that **returns a pointer to this object**.\n\nThink about that for a second. If all local objects in the stack are destroyed at the end of the function scope, why\nwould you even consider returning a pointer to one of these objects? This pointer is at best,\ninvalid, or, more likely, \"undefined\".\n\nIn conclusion, it's totally fine to write a function that returns the local object\nitself as result, because then, you return the value of that object as the result.\nBut, if this local object is stored in the stack, you should never write a function\nthat returns a pointer to this local object. Because the memory address pointed by the pointer\nno longer exists.\n\n\nSo, using again the `add()` function as an example, if you rewrite this function so that it\nreturns a pointer to the local object `result`, the `zig` compiler will actually compile\nyour program, with no warnings or errors. At first glance, it looks like this is good code\nthat works as expected. But this is a lie!\n\nIf you try to take a look at the value inside of the `r` object,\nor, if you try to use this `r` object in another expression\nor function call, then, you would have undefined behaviour, and major\nbugs in your program [@zigdocs, see \"Lifetime and Ownership\"[^life] and \"Undefined Behaviour\"[^undef] sections].\n\n[^life]: <https://ziglang.org/documentation/master/#Lifetime-and-Ownership>\n[^undef]: <https://ziglang.org/documentation/master/#Undefined-Behavior>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn add(x: u8, y: u8) *const u8 {\n    const result = x + y;\n    return &result;\n}\n\npub fn main() !void {\n    // This code compiles successfully. But it has\n    // undefined behaviour. Never do this!!!\n    // The `r` object is undefined!\n    const r = add(5, 27); _ = r;\n}\n```\n:::\n\n\n\n\nThis \"invalid pointer to stack variable\" problem is well known across many programming language communities.\nIf you try to do the same thing, for example, in a C or C++ program (i.e., returning an address to\na local object stored in the stack), you would also get undefined behaviour\nin the program.\n\n::: {.callout-important}\nIf a local object in your function is stored in the stack, you should never\nreturn a pointer to this local object from the function. Because\nthis pointer will always become undefined after the function returns, since the stack space of the function\nis destroyed at the end of its scope.\n:::\n\nBut what if you really need to use this local object in some way after your function returns?\nHow can you do this? The answer is: \"in the same way you would do if this were a C or C++ program. By returning\nan address to an object stored in the heap\". The heap memory has a much more flexible lifecycle,\nand allows you to get a valid pointer to a local object of a function that already returned\nfrom its scope.\n\n\n### Heap {#sec-heap}\n\nOne important limitation of the stack, is that, only objects whose length/size is known at compile-time can be\nstored in it. In contrast, the heap is a much more dynamic\n(and flexible) type of memory. It's the perfect type of memory to use\nfor objects whose size/length might grow during the execution of your program.\n\nVirtually any application that behaves as a server is a classic use case of the heap.\nA HTTP server, a SSH server, a DNS server, a LSP server, ... any type of server.\nIn summary, a server is a type of application that runs for long periods of time,\nand that serves (or \"deals with\") any incoming request that reaches this particular server.\n\nThe heap is a good choice for this type of system, mainly because the server does not know upfront\nhow many requests it will receive from users, while it is active. It could be a single request,\n5 thousand requests, or even zero requests.\nThe server needs to have the ability to allocate and manage its memory according to how many requests it receives.\n\nAnother key difference between the stack and the heap, is that the heap is a type\nof memory that you, the programmer, have complete control over. This makes the heap a\nmore flexible type of memory, but it also makes it harder to work with. Because you,\nthe programmer, is responsible for managing everything related to it. Including where the memory is allocated,\nhow much memory is allocated, and where this memory is freed.\n\n> Unlike stack memory, heap memory is allocated explicitly by programmers and it won’t be deallocated until it is explicitly freed [@jenny2022].\n\nTo store an object in the heap, you, the programmer, needs to explicitly tells Zig to do so,\nby using an allocator to allocate some space in the heap. In @sec-allocators, I will present how you can use allocators to allocate memory\nin Zig.\n\n::: {.callout-important}\nEvery memory you allocate in the heap needs to be explicitly freed by you, the programmer.\n:::\n\nThe majority of allocators in Zig do allocate memory on the heap. But some exceptions to this rule are\n`ArenaAllocator()` and `FixedBufferAllocator()`. The `ArenaAllocator()` is a special\ntype of allocator that works in conjunction with a second type of allocator.\nOn the other side, the `FixedBufferAllocator()` is an allocator that works based on\nbuffer objects created on the stack. This means that the `FixedBufferAllocator()` makes\nallocations only on the stack.\n\n\n\n\n### Summary\n\nAfter discussing all of these boring details, we can quickly recap what we learned.\nIn summary, the Zig compiler will use the following rules to decide where each\nobject you declare is stored:\n\n1. every literal value (such as `\"this is string\"`, `10`, or `true`) is stored in the global data section.\n1. every constant object (`const`) whose value **is known at compile-time** is also stored in the global data section.\n1. every object (constant or not) whose length/size **is known at compile time** is stored in the stack space for the current scope.\n1. if an object is created with the method `alloc()` or `create()` of an allocator object, this object is stored in the memory space used by this particular allocator object. Most of allocators available in Zig use the heap memory, so, this object is likely stored in the heap (`FixedBufferAllocator()` is an exception to that).\n1. the heap can only be accessed through allocators. If your object was not created through the `alloc()` or `create()` methods of an allocator object, then, it is most certainly not an object stored in the heap.\n\n\n## Stack overflows {#sec-stack-overflow}\n\nAllocating memory on the stack is generally faster than allocating it on the heap.\nBut this better performance comes with many restrictions. We have already discussed\nmany of these restrictions of the stack in @sec-stack. But there is one more important\nlimitation that I want to talk about, which is the size of the stack itself.\n\nThe stack is limited in size. This size varies from computer to computer, and it depends on\na lot of things (the computer architecture, the operating system, etc.). Nevertheless, this size is usually\nnot that big. This is why we normally use the stack to store only temporary and small objects in memory.\n\nIn essence, if you try to make an allocation on the stack, that is so big that exceeds the stack size limit,\na *stack overflow* happens, and your program just crashes as a result of that. In other words, a stack overflow happens when\nyou attempt to use more space than is available on the stack.\n\nThis type of problem is very similar to a *buffer overflow*, i.e., you are trying to use more space\nthan is available in the \"buffer object\". However, a stack overflow always causes your program to crash,\nwhile a buffer overflow does not always cause your program to crash (although it often does).\n\nYou can see an example of a stack overflow in the example below. We are trying to allocate a very big array of `u64` values\non the stack. You can see below that this program does not run successfully, because it crashed\nwith a \"segmentation fault\" error message.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar very_big_alloc: [1000 * 1000 * 24]u64 = undefined;\n@memset(very_big_alloc[0..], 0);\n```\n:::\n\n\n\n\n```\nSegmentation fault (core dumped)\n```\n\nThis segmentation fault error is a result of the stack overflow that was caused by the big\nmemory allocation made on the stack, to store the `very_big_alloc` object.\nThis is why very big objects are usually stored on the heap, instead of the stack.\n\n\n\n## Allocators {#sec-allocators}\n\nOne key aspect about Zig, is that there are \"no hidden-memory allocations\" in Zig.\nWhat that really means, is that \"no allocations happen behind your back in the standard library\" [@zigguide].\n\nThis is a known problem, especially in C++. Because in C++, there are some operators that do allocate\nmemory behind the scene, and there is no way for you to know that, until you actually read the\nsource code of these operators, and find the memory allocation calls.\nMany programmers find this behaviour annoying and hard to keep track of.\n\nBut, in Zig, if a function, an operator, or anything from the standard library\nneeds to allocate some memory during its execution, then, this function/operator needs to receive (as input) an allocator\nprovided by the user, to actually be able to allocate the memory it needs.\n\nThis creates a clear distinction between functions that \"do not\" from those that \"actually do\"\nallocate memory. Just look at the arguments of this function.\nIf a function, or operator, has an allocator object as one of its inputs/arguments, then, you know for\nsure that this function/operator will allocate some memory during its execution.\n\nAn example is the `allocPrint()` function from the Zig Standard Library. With this function, you can\nwrite a new string using format specifiers. So, this function is, for example, very similar to the function `sprintf()` in C.\nIn order to write such a new string, the `allocPrint()` function needs to allocate some memory to store the\noutput string.\n\nThat is why, the first argument of this function is an allocator object that you, the user/programmer, gives\nas input to the function. In the example below, I am using the `GeneralPurposeAllocator()` as my allocator\nobject. But I could easily use any other type of allocator object from the Zig Standard Library.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst name = \"Pedro\";\nconst output = try std.fmt.allocPrint(\n    allocator,\n    \"Hello {s}!!!\",\n    .{name}\n);\ntry stdout.print(\"{s}\\n\", .{output});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello Pedro!!!\n```\n\n\n:::\n:::\n\n\n\n\n\nYou get a lot of control over where and how much memory this function can allocate.\nBecause it is you, the user/programmer, that provides the allocator for the function to use.\nThis makes \"total control\" over memory management easier to achieve in Zig.\n\n### What are allocators?\n\nAllocators in Zig are objects that you can use to allocate memory for your program.\nThey are similar to the memory allocating functions in C, like `malloc()` and `calloc()`.\nSo, if you need to use more memory than you initially have, during the execution of your program, you can simply ask\nfor more memory by using an allocator object.\n\nZig offers different types of allocators, and they are usually available through the `std.heap` module of\nthe standard library. Thus, just import the Zig Standard Library into your Zig module (with `@import(\"std\")`), and you can start\nusing these allocators in your code.\n\nFurthermore, every allocator object is built on top of the `Allocator` interface in Zig.\nThis means that, every allocator object you find in Zig must have the methods `alloc()`,\n`create()`, `free()` and `destroy()`. So, you can change the type of allocator you are using,\nbut you don't need to change the function calls to the methods that do the memory allocation\n(and the free memory operations) for your program.\n\n### Why you need an allocator?\n\nAs we described in @sec-stack, everytime you make a function call in Zig,\na space in the stack is reserved for this function call. But the stack\nhas a key limitation which is: every object stored in the stack has a\nknown fixed length.\n\nBut in reality, there are two very common instances where this \"fixed length limitation\" of the stack is a deal braker:\n\n1. the objects that you create inside your function might grow in size during the execution of the function.\n1. sometimes, it's impossible to know upfront how many inputs you will receive, or how big this input will be.\n\nAlso, there is another instance where you might want to use an allocator, which is when you want to write a function that returns a pointer\nto a local object. As I described in @sec-stack, you cannot do that if this local object is stored in the\nstack. However, if this object is stored in the heap, then, you can return a pointer to this object at the\nend of the function. Because you (the programmer) control the lifetime of any heap memory that you allocate. You decide\nwhen this memory gets destroyed/freed.\n\nThese are common situations for which the stack is not good.\nThat is why you need a different memory management strategy to\nstore these objects inside your function. You need to use\na memory type that can grow together with your objects, or that you\ncan control the lifetime of this memory.\nThe heap fits this description.\n\nAllocating memory on the heap is commonly known as dynamic memory management. As the objects you create grow in size\nduring the execution of your program, you grow the amount of memory\nyou have by allocating more memory in the heap to store these objects.\nAnd you do that in Zig, by using an allocator object.\n\n\n### The different types of allocators\n\n\nAt the moment of the writing of this book, in Zig, we have 6 different\nallocators available in the standard library:\n\n- `GeneralPurposeAllocator()`.\n- `page_allocator()`.\n- `FixedBufferAllocator()` and `ThreadSafeFixedBufferAllocator()`.\n- `ArenaAllocator()`.\n- `c_allocator()` (requires you to link to libc).\n\n\nEach allocator has its own perks and limitations. All allocators, except `FixedBufferAllocator()` and `ArenaAllocator()`,\nare allocators that use the heap memory. So any memory that you allocate with\nthese allocators, will be placed in the heap.\n\n### General-purpose allocators\n\nThe `GeneralPurposeAllocator()`, as the name suggests, is a \"general purpose\" allocator. You can use it for every type\nof task. In the example below, I'm allocating enough space to store a single integer in the object `some_number`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const some_number = try allocator.create(u32);\n    defer allocator.destroy(some_number);\n\n    some_number.* = @as(u32, 45);\n}\n```\n:::\n\n\n\n\n\nWhile useful, you might want to use the `c_allocator()`, which is a alias to the C standard allocator `malloc()`. So, yes, you can use\n`malloc()` in Zig if you want to. Just use the `c_allocator()` from the Zig standard library. However,\nif you do use `c_allocator()`, you must link to Libc when compiling your source code with the\n`zig` compiler, by including the flag `-lc` in your compilation process.\nIf you do not link your source code to Libc, Zig will not be able to find the\n`malloc()` implementation in your system.\n\n### Page allocator\n\nThe `page_allocator()` is an allocator that allocates full pages of memory in the heap. In other words,\nevery time you allocate memory with `page_allocator()`, a full page of memory in the heap is allocated,\ninstead of just a small piece of it.\n\nThe size of this page depends on the system you are using.\nMost systems use a page size of 4KB in the heap, so, that is the amount of memory that is normally\nallocated in each call by `page_allocator()`. That is why, `page_allocator()` is considered a\nfast, but also \"wasteful\" allocator in Zig. Because it allocates a big amount of memory\nin each call, and you most likely will not need that much memory in your program.\n\n### Buffer allocators\n\nThe `FixedBufferAllocator()` and `ThreadSafeFixedBufferAllocator()` are allocator objects that\nwork with a fixed sized buffer object at the back. In other words, they use a fixed sized buffer\nobject as the basis for the memory. When you ask these allocator objects to allocate some memory for you,\nthey are essentially reserving some amount of space inside this fixed sized buffer object for you to use.\n\nThis means that, in order to use these allocators, you must first create a buffer object in your code,\nand then, give this buffer object as an input to these allocators.\n\nThis also means that, these allocator objects can allocate memory both in the stack or in the heap.\nEverything depends on where the buffer object that you provide lives. If this buffer object lives\nin the stack, then, the memory allocated is \"stack-based\". But if it lives on the heap, then,\nthe memory allocated is \"heap-based\".\n\n\nIn the example below, I'm creating a `buffer` object on the stack that is 10 elements long.\nNotice that I give this `buffer` object to the `FixedBufferAllocator()` constructor.\nNow, because this `buffer` object is 10 elements long, this means that I am limited to this space.\nI cannot allocate more than 10 elements with this allocator object. If I try to\nallocate more than that, the `alloc()` method will return an `OutOfMemory` error value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar buffer: [10]u8 = undefined;\nfor (0..buffer.len) |i| {\n    buffer[i] = 0; // Initialize to zero\n}\n\nvar fba = std.heap.FixedBufferAllocator.init(&buffer);\nconst allocator = fba.allocator();\nconst input = try allocator.alloc(u8, 5);\ndefer allocator.free(input);\n```\n:::\n\n\n\n\nRemember, the memory allocated by these allocator objects can be either from\nthe stack, or, from the heap. It all depends on where the buffer object that you provide lives.\nIn the above example, the `buffer` object lives in the stack, and, therefore, the memory allocated\nis based in the stack. But what if it was based on the heap?\n\nAs we described in @sec-stack-overflow, one of the main reasons why you would use the heap,\ninstead of the stack, is to allocate huge amounts of space to store very big objects.\nThus, let's suppose you wanted to use a very big buffer object as the basis for your\nallocator objects. You would have to allocate this very big buffer object on the heap.\nThe example below demonstrates this case.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst heap = std.heap.page_allocator;\nconst memory_buffer = try heap.alloc(\n    u8, 100 * 1024 * 1024 // 100 MB memory\n);\ndefer heap.free(memory_buffer);\nvar fba = std.heap.FixedBufferAllocator.init(\n    memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst input = try allocator.alloc(u8, 1000);\ndefer allocator.free(input);\n```\n:::\n\n\n\n\n\n\n### Arena allocator {#sec-arena-allocator}\n\nThe `ArenaAllocator()` is an allocator object that takes a child allocator as input. The idea behind the `ArenaAllocator()` in Zig\nis similar to the concept of \"arenas\" in the programming language Go[^go-arena]. It's an allocator object that allows you\nto allocate memory as many times you want, but free all memory only once.\nIn other words, if you have, for example, called 5 times the method `alloc()` of an `ArenaAllocator()` object, you can\nfree all the memory you allocated over these 5 calls at once, by simply calling the `deinit()` method of the same `ArenaAllocator()` object.\n\n[^go-arena]: <https://go.dev/src/arena/arena.go>\n\nIf you give, for example, a `GeneralPurposeAllocator()` object as input to the `ArenaAllocator()` constructor, like in the example below, then, the allocations\nyou perform with `alloc()` will actually be made with the underlying object `GeneralPurposeAllocator()` that was passed.\nSo, with an arena allocator, any new memory you ask for is allocated by the child allocator. The only thing that an arena allocator\nreally does is help you to free all the memory you allocated multiple times with just a single command. In the example\nbelow, I called `alloc()` 3 times. So, if I did not use an arena allocator, then, I would need to call\n`free()` 3 times to free all the allocated memory.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nvar aa = std.heap.ArenaAllocator.init(gpa.allocator());\ndefer aa.deinit();\nconst allocator = aa.allocator();\n\nconst in1 = try allocator.alloc(u8, 5);\nconst in2 = try allocator.alloc(u8, 10);\nconst in3 = try allocator.alloc(u8, 15);\n_ = in1; _ = in2; _ = in3;\n```\n:::\n\n\n\n\n\n\n### The `alloc()` and `free()` methods\n\nIn the code example below, we are accessing the `stdin`, which is\nthe standard input channel, to receive an input from the\nuser. We read the input given by the user with the `readUntilDelimiterOrEof()`\nmethod.\n\nNow, after reading the input of the user, we need to store this input somewhere in\nour program. That is why I use an allocator in this example. I use it to allocate some\namount of memory to store this input given by the user. More specifically, the method `alloc()`\nof the allocator object is used to allocate an array capable of storing 50 `u8` values.\n\nNotice that this `alloc()` method receives two inputs. The first one, is a type.\nThis defines what type of values the allocated array will store. In the example\nbelow, we are allocating an array of unsigned 8-bit integers (`u8`). But\nyou can create an array to store any type of value you want. Next, in the second argument, we\ndefine the size of the allocated array, by specifying how many elements\nthis array will contain. In the case below, we are allocating an array of 50 elements.\n\nIn @sec-zig-strings we described that strings in Zig are simply arrays of characters.\nEach character is represented by a `u8` value. So, this means that the array that\nwas allocated in the object `input` is capable of storing a string that is\n50-characters long.\n\nSo, in essence, the expression `var input: [50]u8 = undefined` would create\nan array for 50 `u8` values in the stack of the current scope. But, you\ncan allocate the same array in the heap by using the expression `var input = try allocator.alloc(u8, 50)`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdin = std.io.getStdIn();\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var input = try allocator.alloc(u8, 50);\n    defer allocator.free(input);\n    for (0..input.len) |i| {\n        input[i] = 0; // initialize all fields to zero.\n    }\n    // read user input\n    const input_reader = stdin.reader();\n    _ = try input_reader.readUntilDelimiterOrEof(\n        input,\n        '\\n'\n    );\n    std.debug.print(\"{s}\\n\", .{input});\n}\n```\n:::\n\n\n\n\nAlso, notice that in this example, we use the `defer` keyword (which I described in @sec-defer) to run a small\npiece of code at the end of the current scope, which is the expression `allocator.free(input)`.\nWhen you execute this expression, the allocator will free the memory that it allocated\nfor the `input` object.\n\nWe have talked about this in @sec-heap. You **should always** explicitly free any memory that you allocate\nusing an allocator! You do that by using the `free()` method of the same allocator object you\nused to allocate this memory. The `defer` keyword is used in this example only to help us execute\nthis free operation at the end of the current scope.\n\n\n### The `create()` and `destroy()` methods\n\nWith the `alloc()` and `free()` methods, you can allocate memory to store multiple elements\nat once. In other words, with these methods, we always allocate an array to store multiple elements at once.\nBut what if you need enough space to store just a single item? Should you\nallocate an array of a single element through `alloc()`?\n\nThe answer is no! In this case,\nyou should use the `create()` method of the allocator object.\nEvery allocator object offers the `create()` and `destroy()` methods,\nwhich are used to allocate and free memory for a single item, respectively.\n\nSo, in essence, if you want to allocate memory to store an array of elements, you\nshould use `alloc()` and `free()`. But if you need to store just a single item,\nthen, the `create()` and `destroy()` methods are ideal for you.\n\nIn the example below, I'm defining a struct to represent an user of some sort.\nIt could be a user for a game, or software to manage resources, it doesn't mater.\nNotice that I use the `create()` method this time, to store a single `User` object\nin the program. Also notice that I use the `destroy()` method to free the memory\nused by this object at the end of the scope.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst User = struct {\n    id: usize,\n    name: []const u8,\n\n    pub fn init(id: usize, name: []const u8) User {\n        return .{ .id = id, .name = name };\n    }\n};\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const user = try allocator.create(User);\n    defer allocator.destroy(user);\n\n    user.* = User.init(0, \"Pedro\");\n}\n```\n:::\n",
-    "supporting": [
-      "01-memory_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n# Memory and Allocators\n\n\nIn this chapter, we will talk about memory. How does Zig control memory? What\ncommon tools are used? Are there any important aspects that make memory\ndifferent/special in Zig? You will find the answers here.\n\nComputers fundamentally rely on memory to function. This memory acts as a temporary storage\nspace for the data and values generated during computations. Without memory, the core\nconcepts of \"variables\" and \"objects\" in programming languages would be impossible.\n\n\n\n\n## Memory spaces\n\nEvery object that you create in your Zig source code needs to be stored somewhere,\nin your computer's memory. Depending on where and how you define your object, Zig\nwill use a different \"memory space\", or a different\ntype of memory to store this object.\n\nEach type of memory normally serves for different purposes.\nIn Zig, there are 3 types of memory (or 3 different memory spaces) that we care about. They are:\n\n- Global data register (or the \"global data section\");\n- Stack;\n- Heap;\n\n\n### Compile-time known versus runtime known {#sec-compile-time}\n\nOne strategy that Zig uses to decide where it will store each object that you declare, is by looking\nat the value of this particular object. More specifically, by investigating if this value is\nknown at \"compile-time\" or at \"runtime\".\n\nWhen you write a program in Zig, the values of some of the objects that you write in your program are *known\nat compile time*. Meaning that, when you compile your Zig source code, during the compilation process,\nthe `zig` compiler can figure out the exact value of a particular object\nthat exists in your source code.\nKnowing the length (or the size) of each object is also important. So the length (or the size) of each object that you write in your program is,\nin some cases, *known at compile time*.\n\nThe `zig` compiler cares more about knowing the length (or the size) of a particular object\n, than to know its actual value. But, if the `zig` compiler knows the value of the object, then, it\nautomatically knows the size of this object. Because it can simply calculate the\nsize of the object by looking at the size of the value.\n\nTherefore, the priority for the `zig` compiler is to discover the size of each object in your source code.\nIf the value of the object in question is known at compile-time, then, the `zig` compiler\nautomatically knows the size/length of this object. But if the value of this object is not\nknown at compile-time, then, the size of this object is only known at compile-time if,\nand only if, the type of this object has a known fixed size.\n\nIn order for a type to have a known fixed size, this type must have data members whose size is fixed.\nIf this type includes, for example, a variable sized array in it, then, this type does not have a known\nfixed size. Because this array can have any size at runtime\n(i.e., it can be an array of 2 elements, or 50 elements, or 1 thousand elements, etc.).\n\nFor example, a string object, which internally is an array of constant u8 values (`[]const u8`)\nhas a variable size. It can be a string object with 100 or 500 characters in it. If we do not\nknow at compile-time, which exact string will be stored inside this string object, then, we cannot calculate\nthe size of this string object at compile-time. So, any type, or any struct declaration that you make, that\nincludes a string data member that does not have an explicit fixed size, makes this type, or this\nnew struct that you are declaring, a type that does not have a known fixed size at compile-time.\n\nIn contrast, if the type of this struct that you are declaring, includes a data member that is an array,\nbut this array has a known fixed size, like `[60]u8` (which declares an array of 60 `u8` values), then,\nthis type, or, this struct that you are declaring, becomes a type with a known fixed size at compile-time.\nAnd because of that, in this case, the `zig` compiler does not need to know at compile-time the exact value of\nany object of this type. Since the compiler can find the necessary size to store this object by\nlooking at the size of its type.\n\n\nLet's look at an example. In the source code below, we have two constant objects (`name` and `array`) declared.\nBecause the values of these particular objects are written down, in the source code itself (`\"Pedro\"`\nand the number sequence from 1 to 4), the `zig` compiler can easily discover the values of these constant\nobjects (`name` and `array`) during the compilation process.\nThis is what \"known at compile time\" means. It refers to any object that you have in your Zig source code\nwhose value can be identified at compile time.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn input_length(input: []const u8) usize {\n    const n = input.len;\n    return n;\n}\n\npub fn main() !void {\n    const name = \"Pedro\";\n    const array = [_]u8{1, 2, 3, 4};\n    _ = name; _ = array;\n}\n```\n:::\n\n\nThe other side of the spectrum are objects whose values are not known at compile time.\nFunction arguments are a classic example of this. Because the value of each function\nargument depends on the value that you assign to this particular argument,\nwhen you call the function.\n\nFor example, the function `input_length()` contains an argument named `input`, which is an array of constant `u8` integers (`[]const u8`).\nIt's impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length\nof this particular argument. Because it's an array that does not have a fixed size specified explicitly in the argument type annotation.\n\nSo, we know that this `input` argument will be an array of `u8` integers. But we do not know at compile-time, its value, and neither its size.\nThis information is known only at runtime, which is the period of time when you program is executed.\nAs a consequence, the value of the expression `input.len` is also known only at runtime.\nThis is an intrinsic characteristic of any function. Just remember that the value of function arguments is usually not \"compile-time known\".\n\nHowever, as I mentioned earlier, what really matters to the compiler is to know the size of the object\nat compile-time, and not necessarily its value. So, although we don't know the value of the object `n`, which is the result of the expression\n`input.len`, at compile-time, we do know its size. Because the expression `input.len` always returns a value of type `usize`,\nand the type `usize` has a known fixed size.\n\n\n\n### Global data register\n\nThe global data register is a specific section of the executable of your Zig program, that is responsible\nfor storing any value that is known at compile time.\n\nEvery constant object whose value is known at compile time that you declare in your source code,\nis stored in the global data register. Also, every literal value that you write in your source code,\nsuch as the string `\"this is a string\"`, or the integer `10`, or a boolean value such as `true`,\nis also stored in the global data register.\n\nHonestly, you don't need to care much about this memory space. Because you can't control it,\nyou can't deliberately access it or use it for your own purposes.\nAlso, this memory space does not affect the logic of your program.\nIt simply exists in your program.\n\n\n### Stack vs Heap\n\nIf you are familiar with systems programming, or just low-level programming in general, you\nprobably have heard of the \"duel\" between Stack vs Heap. These are two different types of memory,\nor different memory spaces, which are both available in Zig.\n\nThese two types of memory don't actually duel with\neach other. This is a common mistake that beginners have, when seeing \"x vs y\" styles of\ntabloid headlines. These two types of memory are actually complementary to each other.\nSo, in almost every Zig program that you ever write, you will likely use a combination of both.\nI will describe each memory space in detail over the next sections. But for now, I just want to\nstablish the main difference between these two types of memory.\n\nIn essence, the stack memory is normally used to store values whose length is fixed and known\nat compile time. In contrast, the heap memory is a *dynamic* type of memory space, meaning that, it's\nused to store values whose length might grow during the execution (runtime) of your program [@jenny2022].\n\nLengths that grow during runtime are intrinsically associated with \"runtime known\" type of values.\nIn other words, if you have an object whose length might grow during runtime, then, the length\nof this object becomes not known at compile time. If the length is not known at compile-time,\nthe value of this object also becomes not known at compile-time.\nThese types of objects should be stored in the heap memory space, which is\na dynamic memory space, which can grow or shrink to fit the size of your objects.\n\n\n\n### Stack {#sec-stack}\n\nThe stack is a type of memory that uses the power of the *stack data structure*, hence the name.\nA \"stack\" is a type of *data structure* that uses a \"last in, first out\" (LIFO) mechanism to store the values\nyou give it to. I imagine you are familiar with this data structure.\nBut, if you are not, the [Wikipedia page](https://en.wikipedia.org/wiki/Stack_(abstract_data_type))[^wiki-stack]\n, or, the [Geeks For Geeks page](https://www.geeksforgeeks.org/stack-data-structure/)[^geek-stack] are both\nexcellent and easy resources to fully understand how this data structure works.\n\n[^wiki-stack]: <https://en.wikipedia.org/wiki/Stack_(abstract_data_type)>\n[^geek-stack]: <https://www.geeksforgeeks.org/stack-data-structure/>\n\nSo, the stack memory space is a type of memory that stores values using a stack data structure.\nIt adds and removes values from the memory by following a \"last in, first out\" (LIFO) principle.\n\nEvery time you make a function call in Zig, an amount of space in the stack is\nreserved for this particular function call [@jenny2022; @zigdocs].\nThe value of each function argument given to the function in this function call is stored in this\nstack space. Also, every local object that you declare inside the function scope is\nusually stored in this same stack space.\n\n\nLooking at the example below, the object `result` is a local object declared inside the scope of the `add()`\nfunction. Because of that, this object is stored inside the stack space reserved for the `add()` function.\nThe `r` object (which is declared outside of the `add()` function scope) is also stored in the stack.\nBut since it's declared in the \"outer\" scope, this object is stored in the\nstack space that belongs to this outer scope.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn add(x: u8, y: u8) u8 {\n    const result = x + y;\n    return result;\n}\n\npub fn main() !void {\n    const r = add(5, 27);\n    _ = r;\n}\n```\n:::\n\n\n\nSo, any object that you declare inside the scope of a function is always stored inside\nthe space that was reserved for that particular function in the stack memory. This\nalso counts for any object declared inside the scope of your `main()` function for example.\nAs you would expect, in this case, they\nare stored inside the stack space reserved for the `main()` function.\n\nOne very important detail about the stack memory is that **it frees itself automatically**.\nThis is very important, remember that. When objects are stored in the stack memory,\nyou don't have the work (or the responsibility) of freeing/destroying these objects.\nBecause they will be automatically destroyed once the stack space is freed at the end of the function scope.\n\nSo, once the function call returns (or ends, if you prefer to call it this way)\nthe space that was reserved in the stack is destroyed, and all of the objects that were in that space goes away with it.\nThis mechanism exists because this space, and the objects within it, are not necessary anymore,\nsince the function \"finished its business\".\nUsing the `add()` function that we exposed above as an example, it means that the object `result` is automatically\ndestroyed once the function returns.\n\n::: {.callout-important}\nLocal objects that are stored in the stack space of a function are automatically\nfreed/destroyed at the end of the function scope.\n:::\n\n\nThis same logic applies to any other special structure in Zig that has its own scope by surrounding\nit with curly braces (`{}`).\nFor loops, while loops, if else statements, etc. For example, if you declare any local\nobject in the scope of a for loop, this local object is accessible only within the scope\nof this particular for loop. Because once the scope of this for loop ends, the space in the stack\nreserved for this for loop is freed.\nThe example below demonstrates this idea.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This does not compile successfully!\nconst a = [_]u8{0, 1, 2, 3, 4};\nfor (0..a.len) |i| {\n    const index = i;\n    _ = index;\n}\n// Trying to use an object that was\n// declared in the for loop scope,\n// and that does not exist anymore.\nstd.debug.print(\"{d}\\n\", .{index});\n```\n:::\n\n\n\n\nOne important consequence of this mechanism is that, once the function returns, you can no longer access any memory\naddress that was inside the space in the stack reserved for this particular function. Because this space was\ndestroyed. This means that, if this local object is stored in the stack,\nyou cannot make a function that **returns a pointer to this object**.\n\nThink about that for a second. If all local objects in the stack are destroyed at the end of the function scope, why\nwould you even consider returning a pointer to one of these objects? This pointer is at best,\ninvalid, or, more likely, \"undefined\".\n\nIn conclusion, it's totally fine to write a function that returns the local object\nitself as result, because then, you return the value of that object as the result.\nBut, if this local object is stored in the stack, you should never write a function\nthat returns a pointer to this local object. Because the memory address pointed by the pointer\nno longer exists.\n\n\nSo, using again the `add()` function as an example, if you rewrite this function so that it\nreturns a pointer to the local object `result`, the `zig` compiler will actually compile\nyour program, with no warnings or errors. At first glance, it looks like this is good code\nthat works as expected. But this is a lie!\n\nIf you try to take a look at the value inside of the `r` object,\nor, if you try to use this `r` object in another expression\nor function call, then, you would have undefined behaviour, and major\nbugs in your program [@zigdocs, see \"Lifetime and Ownership\"[^life] and \"Undefined Behaviour\"[^undef] sections].\n\n[^life]: <https://ziglang.org/documentation/master/#Lifetime-and-Ownership>\n[^undef]: <https://ziglang.org/documentation/master/#Undefined-Behavior>\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn add(x: u8, y: u8) *const u8 {\n    const result = x + y;\n    return &result;\n}\n\npub fn main() !void {\n    // This code compiles successfully. But it has\n    // undefined behaviour. Never do this!!!\n    // The `r` object is undefined!\n    const r = add(5, 27); _ = r;\n}\n```\n:::\n\n\nThis \"invalid pointer to stack variable\" problem is well known across many programming language communities.\nIf you try to do the same thing, for example, in a C or C++ program (i.e., returning an address to\na local object stored in the stack), you would also get undefined behaviour\nin the program.\n\n::: {.callout-important}\nIf a local object in your function is stored in the stack, you should never\nreturn a pointer to this local object from the function. Because\nthis pointer will always become undefined after the function returns, since the stack space of the function\nis destroyed at the end of its scope.\n:::\n\nBut what if you really need to use this local object in some way after your function returns?\nHow can you do this? The answer is: \"in the same way you would do if this were a C or C++ program. By returning\nan address to an object stored in the heap\". The heap memory has a much more flexible lifecycle,\nand allows you to get a valid pointer to a local object of a function that already returned\nfrom its scope.\n\n\n### Heap {#sec-heap}\n\nOne important limitation of the stack, is that, only objects whose length/size is known at compile-time can be\nstored in it. In contrast, the heap is a much more dynamic\n(and flexible) type of memory. It's the perfect type of memory to use\nfor objects whose size/length might grow during the execution of your program.\n\nVirtually any application that behaves as a server is a classic use case of the heap.\nA HTTP server, a SSH server, a DNS server, a LSP server, ... any type of server.\nIn summary, a server is a type of application that runs for long periods of time,\nand that serves (or \"deals with\") any incoming request that reaches this particular server.\n\nThe heap is a good choice for this type of system, mainly because the server does not know upfront\nhow many requests it will receive from users, while it is active. It could be a single request,\n5 thousand requests, or even zero requests.\nThe server needs to have the ability to allocate and manage its memory according to how many requests it receives.\n\nAnother key difference between the stack and the heap, is that the heap is a type\nof memory that you, the programmer, have complete control over. This makes the heap a\nmore flexible type of memory, but it also makes it harder to work with. Because you,\nthe programmer, is responsible for managing everything related to it. Including where the memory is allocated,\nhow much memory is allocated, and where this memory is freed.\n\n> Unlike stack memory, heap memory is allocated explicitly by programmers and it won’t be deallocated until it is explicitly freed [@jenny2022].\n\nTo store an object in the heap, you, the programmer, needs to explicitly tells Zig to do so,\nby using an allocator to allocate some space in the heap. In @sec-allocators, I will present how you can use allocators to allocate memory\nin Zig.\n\n::: {.callout-important}\nEvery memory you allocate in the heap needs to be explicitly freed by you, the programmer.\n:::\n\nThe majority of allocators in Zig do allocate memory on the heap. But some exceptions to this rule are\n`ArenaAllocator()` and `FixedBufferAllocator()`. The `ArenaAllocator()` is a special\ntype of allocator that works in conjunction with a second type of allocator.\nOn the other side, the `FixedBufferAllocator()` is an allocator that works based on\nbuffer objects created on the stack. This means that the `FixedBufferAllocator()` makes\nallocations only on the stack.\n\n\n\n\n### Summary\n\nAfter discussing all of these boring details, we can quickly recap what we learned.\nIn summary, the Zig compiler will use the following rules to decide where each\nobject you declare is stored:\n\n1. every literal value (such as `\"this is string\"`, `10`, or `true`) is stored in the global data section.\n1. every constant object (`const`) whose value **is known at compile-time** is also stored in the global data section.\n1. every object (constant or not) whose length/size **is known at compile time** is stored in the stack space for the current scope.\n1. if an object is created with the method `alloc()` or `create()` of an allocator object, this object is stored in the memory space used by this particular allocator object. Most of allocators available in Zig use the heap memory, so, this object is likely stored in the heap (`FixedBufferAllocator()` is an exception to that).\n1. the heap can only be accessed through allocators. If your object was not created through the `alloc()` or `create()` methods of an allocator object, then, it is most certainly not an object stored in the heap.\n\n\n## Stack overflows {#sec-stack-overflow}\n\nAllocating memory on the stack is generally faster than allocating it on the heap.\nBut this better performance comes with many restrictions. We have already discussed\nmany of these restrictions of the stack in @sec-stack. But there is one more important\nlimitation that I want to talk about, which is the size of the stack itself.\n\nThe stack is limited in size. This size varies from computer to computer, and it depends on\na lot of things (the computer architecture, the operating system, etc.). Nevertheless, this size is usually\nnot that big. This is why we normally use the stack to store only temporary and small objects in memory.\n\nIn essence, if you try to make an allocation on the stack, that is so big that exceeds the stack size limit,\na *stack overflow* happens, and your program just crashes as a result of that. In other words, a stack overflow happens when\nyou attempt to use more space than is available on the stack.\n\nThis type of problem is very similar to a *buffer overflow*, i.e., you are trying to use more space\nthan is available in the \"buffer object\". However, a stack overflow always causes your program to crash,\nwhile a buffer overflow does not always cause your program to crash (although it often does).\n\nYou can see an example of a stack overflow in the example below. We are trying to allocate a very big array of `u64` values\non the stack. You can see below that this program does not run successfully, because it crashed\nwith a \"segmentation fault\" error message.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar very_big_alloc: [1000 * 1000 * 24]u64 = undefined;\n@memset(very_big_alloc[0..], 0);\n```\n:::\n\n\n```\nSegmentation fault (core dumped)\n```\n\nThis segmentation fault error is a result of the stack overflow that was caused by the big\nmemory allocation made on the stack, to store the `very_big_alloc` object.\nThis is why very big objects are usually stored on the heap, instead of the stack.\n\n\n\n## Allocators {#sec-allocators}\n\nOne key aspect about Zig, is that there are \"no hidden-memory allocations\" in Zig.\nWhat that really means, is that \"no allocations happen behind your back in the standard library\" [@zigguide].\n\nThis is a known problem, especially in C++. Because in C++, there are some operators that do allocate\nmemory behind the scene, and there is no way for you to know that, until you actually read the\nsource code of these operators, and find the memory allocation calls.\nMany programmers find this behaviour annoying and hard to keep track of.\n\nBut, in Zig, if a function, an operator, or anything from the standard library\nneeds to allocate some memory during its execution, then, this function/operator needs to receive (as input) an allocator\nprovided by the user, to actually be able to allocate the memory it needs.\n\nThis creates a clear distinction between functions that \"do not\" from those that \"actually do\"\nallocate memory. Just look at the arguments of this function.\nIf a function, or operator, has an allocator object as one of its inputs/arguments, then, you know for\nsure that this function/operator will allocate some memory during its execution.\n\nAn example is the `allocPrint()` function from the Zig Standard Library. With this function, you can\nwrite a new string using format specifiers. So, this function is, for example, very similar to the function `sprintf()` in C.\nIn order to write such a new string, the `allocPrint()` function needs to allocate some memory to store the\noutput string.\n\nThat is why, the first argument of this function is an allocator object that you, the user/programmer, gives\nas input to the function. In the example below, I am using the `GeneralPurposeAllocator()` as my allocator\nobject. But I could easily use any other type of allocator object from the Zig Standard Library.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst name = \"Pedro\";\nconst output = try std.fmt.allocPrint(\n    allocator,\n    \"Hello {s}!!!\",\n    .{name}\n);\ntry stdout.print(\"{s}\\n\", .{output});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello Pedro!!!\n```\n\n\n:::\n:::\n\n\n\nYou get a lot of control over where and how much memory this function can allocate.\nBecause it is you, the user/programmer, that provides the allocator for the function to use.\nThis makes \"total control\" over memory management easier to achieve in Zig.\n\n### What are allocators?\n\nAllocators in Zig are objects that you can use to allocate memory for your program.\nThey are similar to the memory allocating functions in C, like `malloc()` and `calloc()`.\nSo, if you need to use more memory than you initially have, during the execution of your program, you can simply ask\nfor more memory by using an allocator object.\n\nZig offers different types of allocators, and they are usually available through the `std.heap` module of\nthe standard library. Thus, just import the Zig Standard Library into your Zig module (with `@import(\"std\")`), and you can start\nusing these allocators in your code.\n\nFurthermore, every allocator object is built on top of the `Allocator` interface in Zig.\nThis means that, every allocator object you find in Zig must have the methods `alloc()`,\n`create()`, `free()` and `destroy()`. So, you can change the type of allocator you are using,\nbut you don't need to change the function calls to the methods that do the memory allocation\n(and the free memory operations) for your program.\n\n### Why you need an allocator?\n\nAs we described in @sec-stack, everytime you make a function call in Zig,\na space in the stack is reserved for this function call. But the stack\nhas a key limitation which is: every object stored in the stack has a\nknown fixed length.\n\nBut in reality, there are two very common instances where this \"fixed length limitation\" of the stack is a deal braker:\n\n1. the objects that you create inside your function might grow in size during the execution of the function.\n1. sometimes, it's impossible to know upfront how many inputs you will receive, or how big this input will be.\n\nAlso, there is another instance where you might want to use an allocator, which is when you want to write a function that returns a pointer\nto a local object. As I described in @sec-stack, you cannot do that if this local object is stored in the\nstack. However, if this object is stored in the heap, then, you can return a pointer to this object at the\nend of the function. Because you (the programmer) control the lifetime of any heap memory that you allocate. You decide\nwhen this memory gets destroyed/freed.\n\nThese are common situations for which the stack is not good.\nThat is why you need a different memory management strategy to\nstore these objects inside your function. You need to use\na memory type that can grow together with your objects, or that you\ncan control the lifetime of this memory.\nThe heap fits this description.\n\nAllocating memory on the heap is commonly known as dynamic memory management. As the objects you create grow in size\nduring the execution of your program, you grow the amount of memory\nyou have by allocating more memory in the heap to store these objects.\nAnd you do that in Zig, by using an allocator object.\n\n\n### The different types of allocators\n\n\nAt the moment of the writing of this book, in Zig, we have 6 different\nallocators available in the standard library:\n\n- `GeneralPurposeAllocator()`.\n- `page_allocator()`.\n- `FixedBufferAllocator()` and `ThreadSafeFixedBufferAllocator()`.\n- `ArenaAllocator()`.\n- `c_allocator()` (requires you to link to libc).\n\n\nEach allocator has its own perks and limitations. All allocators, except `FixedBufferAllocator()` and `ArenaAllocator()`,\nare allocators that use the heap memory. So any memory that you allocate with\nthese allocators, will be placed in the heap.\n\n### General-purpose allocators\n\nThe `GeneralPurposeAllocator()`, as the name suggests, is a \"general purpose\" allocator. You can use it for every type\nof task. In the example below, I'm allocating enough space to store a single integer in the object `some_number`.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const some_number = try allocator.create(u32);\n    defer allocator.destroy(some_number);\n\n    some_number.* = @as(u32, 45);\n}\n```\n:::\n\n\n\nWhile useful, you might want to use the `c_allocator()`, which is a alias to the C standard allocator `malloc()`. So, yes, you can use\n`malloc()` in Zig if you want to. Just use the `c_allocator()` from the Zig standard library. However,\nif you do use `c_allocator()`, you must link to Libc when compiling your source code with the\n`zig` compiler, by including the flag `-lc` in your compilation process.\nIf you do not link your source code to Libc, Zig will not be able to find the\n`malloc()` implementation in your system.\n\n### Page allocator\n\nThe `page_allocator()` is an allocator that allocates full pages of memory in the heap. In other words,\nevery time you allocate memory with `page_allocator()`, a full page of memory in the heap is allocated,\ninstead of just a small piece of it.\n\nThe size of this page depends on the system you are using.\nMost systems use a page size of 4KB in the heap, so, that is the amount of memory that is normally\nallocated in each call by `page_allocator()`. That is why, `page_allocator()` is considered a\nfast, but also \"wasteful\" allocator in Zig. Because it allocates a big amount of memory\nin each call, and you most likely will not need that much memory in your program.\n\n### Buffer allocators\n\nThe `FixedBufferAllocator()` and `ThreadSafeFixedBufferAllocator()` are allocator objects that\nwork with a fixed sized buffer object at the back. In other words, they use a fixed sized buffer\nobject as the basis for the memory. When you ask these allocator objects to allocate some memory for you,\nthey are essentially reserving some amount of space inside this fixed sized buffer object for you to use.\n\nThis means that, in order to use these allocators, you must first create a buffer object in your code,\nand then, give this buffer object as an input to these allocators.\n\nThis also means that, these allocator objects can allocate memory both in the stack or in the heap.\nEverything depends on where the buffer object that you provide lives. If this buffer object lives\nin the stack, then, the memory allocated is \"stack-based\". But if it lives on the heap, then,\nthe memory allocated is \"heap-based\".\n\n\nIn the example below, I'm creating a `buffer` object on the stack that is 10 elements long.\nNotice that I give this `buffer` object to the `FixedBufferAllocator()` constructor.\nNow, because this `buffer` object is 10 elements long, this means that I am limited to this space.\nI cannot allocate more than 10 elements with this allocator object. If I try to\nallocate more than that, the `alloc()` method will return an `OutOfMemory` error value.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar buffer: [10]u8 = undefined;\nfor (0..buffer.len) |i| {\n    buffer[i] = 0; // Initialize to zero\n}\n\nvar fba = std.heap.FixedBufferAllocator.init(&buffer);\nconst allocator = fba.allocator();\nconst input = try allocator.alloc(u8, 5);\ndefer allocator.free(input);\n```\n:::\n\n\nRemember, the memory allocated by these allocator objects can be either from\nthe stack, or, from the heap. It all depends on where the buffer object that you provide lives.\nIn the above example, the `buffer` object lives in the stack, and, therefore, the memory allocated\nis based in the stack. But what if it was based on the heap?\n\nAs we described in @sec-stack-overflow, one of the main reasons why you would use the heap,\ninstead of the stack, is to allocate huge amounts of space to store very big objects.\nThus, let's suppose you wanted to use a very big buffer object as the basis for your\nallocator objects. You would have to allocate this very big buffer object on the heap.\nThe example below demonstrates this case.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst heap = std.heap.page_allocator;\nconst memory_buffer = try heap.alloc(\n    u8, 100 * 1024 * 1024 // 100 MB memory\n);\ndefer heap.free(memory_buffer);\nvar fba = std.heap.FixedBufferAllocator.init(\n    memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst input = try allocator.alloc(u8, 1000);\ndefer allocator.free(input);\n```\n:::\n\n\n\n\n### Arena allocator {#sec-arena-allocator}\n\nThe `ArenaAllocator()` is an allocator object that takes a child allocator as input. The idea behind the `ArenaAllocator()` in Zig\nis similar to the concept of \"arenas\" in the programming language Go[^go-arena]. It's an allocator object that allows you\nto allocate memory as many times you want, but free all memory only once.\nIn other words, if you have, for example, called 5 times the method `alloc()` of an `ArenaAllocator()` object, you can\nfree all the memory you allocated over these 5 calls at once, by simply calling the `deinit()` method of the same `ArenaAllocator()` object.\n\n[^go-arena]: <https://go.dev/src/arena/arena.go>\n\nIf you give, for example, a `GeneralPurposeAllocator()` object as input to the `ArenaAllocator()` constructor, like in the example below, then, the allocations\nyou perform with `alloc()` will actually be made with the underlying object `GeneralPurposeAllocator()` that was passed.\nSo, with an arena allocator, any new memory you ask for is allocated by the child allocator. The only thing that an arena allocator\nreally does is help you to free all the memory you allocated multiple times with just a single command. In the example\nbelow, I called `alloc()` 3 times. So, if I did not use an arena allocator, then, I would need to call\n`free()` 3 times to free all the allocated memory.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nvar aa = std.heap.ArenaAllocator.init(gpa.allocator());\ndefer aa.deinit();\nconst allocator = aa.allocator();\n\nconst in1 = try allocator.alloc(u8, 5);\nconst in2 = try allocator.alloc(u8, 10);\nconst in3 = try allocator.alloc(u8, 15);\n_ = in1; _ = in2; _ = in3;\n```\n:::\n\n\n\n\n### The `alloc()` and `free()` methods\n\nIn the code example below, we are accessing the `stdin`, which is\nthe standard input channel, to receive an input from the\nuser. We read the input given by the user with the `readUntilDelimiterOrEof()`\nmethod.\n\nNow, after reading the input of the user, we need to store this input somewhere in\nour program. That is why I use an allocator in this example. I use it to allocate some\namount of memory to store this input given by the user. More specifically, the method `alloc()`\nof the allocator object is used to allocate an array capable of storing 50 `u8` values.\n\nNotice that this `alloc()` method receives two inputs. The first one, is a type.\nThis defines what type of values the allocated array will store. In the example\nbelow, we are allocating an array of unsigned 8-bit integers (`u8`). But\nyou can create an array to store any type of value you want. Next, in the second argument, we\ndefine the size of the allocated array, by specifying how many elements\nthis array will contain. In the case below, we are allocating an array of 50 elements.\n\nIn @sec-zig-strings we described that strings in Zig are simply arrays of characters.\nEach character is represented by a `u8` value. So, this means that the array that\nwas allocated in the object `input` is capable of storing a string that is\n50-characters long.\n\nSo, in essence, the expression `var input: [50]u8 = undefined` would create\nan array for 50 `u8` values in the stack of the current scope. But, you\ncan allocate the same array in the heap by using the expression `var input = try allocator.alloc(u8, 50)`.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdin = std.io.getStdIn();\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var input = try allocator.alloc(u8, 50);\n    defer allocator.free(input);\n    for (0..input.len) |i| {\n        input[i] = 0; // initialize all fields to zero.\n    }\n    // read user input\n    const input_reader = stdin.reader();\n    _ = try input_reader.readUntilDelimiterOrEof(\n        input,\n        '\\n'\n    );\n    std.debug.print(\"{s}\\n\", .{input});\n}\n```\n:::\n\n\nAlso, notice that in this example, we use the `defer` keyword (which I described in @sec-defer) to run a small\npiece of code at the end of the current scope, which is the expression `allocator.free(input)`.\nWhen you execute this expression, the allocator will free the memory that it allocated\nfor the `input` object.\n\nWe have talked about this in @sec-heap. You **should always** explicitly free any memory that you allocate\nusing an allocator! You do that by using the `free()` method of the same allocator object you\nused to allocate this memory. The `defer` keyword is used in this example only to help us execute\nthis free operation at the end of the current scope.\n\n\n### The `create()` and `destroy()` methods\n\nWith the `alloc()` and `free()` methods, you can allocate memory to store multiple elements\nat once. In other words, with these methods, we always allocate an array to store multiple elements at once.\nBut what if you need enough space to store just a single item? Should you\nallocate an array of a single element through `alloc()`?\n\nThe answer is no! In this case,\nyou should use the `create()` method of the allocator object.\nEvery allocator object offers the `create()` and `destroy()` methods,\nwhich are used to allocate and free memory for a single item, respectively.\n\nSo, in essence, if you want to allocate memory to store an array of elements, you\nshould use `alloc()` and `free()`. But if you need to store just a single item,\nthen, the `create()` and `destroy()` methods are ideal for you.\n\nIn the example below, I'm defining a struct to represent an user of some sort.\nIt could be a user for a game, or software to manage resources, it doesn't mater.\nNotice that I use the `create()` method this time, to store a single `User` object\nin the program. Also notice that I use the `destroy()` method to free the memory\nused by this object at the end of the scope.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst User = struct {\n    id: usize,\n    name: []const u8,\n\n    pub fn init(id: usize, name: []const u8) User {\n        return .{ .id = id, .name = name };\n    }\n};\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const user = try allocator.create(User);\n    defer allocator.destroy(user);\n\n    user.* = User.init(0, \"Pedro\");\n}\n```\n:::\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/01-zig-weird/execute-results/epub.json b/_freeze/Chapters/01-zig-weird/execute-results/epub.json
deleted file mode 100644
index 6385ce4f..00000000
--- a/_freeze/Chapters/01-zig-weird/execute-results/epub.json
+++ /dev/null
@@ -1,21 +0,0 @@
-{
-  "hash": "4d435d48922c81726d4668b9e1fc1e4f",
-  "result": {
-    "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\nlanguage, it's still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. Sometimes, they really make it hard to debug\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscure the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that gets compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e., where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contains Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nWe can use this build system to write small scripts in Zig,\nwhich describe the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e., creating new objects)\nare made in Zig. You can create a new object in Zig by using the syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). In @sec-assignments we talk more about objects in general.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that in @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIt's worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt's like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portable C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nIn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e., the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. If you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith an \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, on Windows, operations like accessing the `stdout` (or opening a file) depend on\nresources that are available only at *runtime* (you will learn more about compile-time versus runtime\nin @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerges from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword in @sec-comptime.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation in a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues\n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described in @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig later in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig?\nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar to our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentation.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It's a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (on YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e., identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nSo, if you want to change the value of your object, you need to transform your immutable (or \"constant\")\nobject into a mutable (or \"variable\") object. You can do that by using the `var` keyword.\nThis keyword stands for \"variable\", and when you apply this keyword to some object, you are\ntelling the Zig compiler that the value associated with this object might change at some point.\n\nThus, if we come back to the previous example, and change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it's a \"variable object\".\n\nHowever, if you take a look at the example below, you will notice that we have not only declared the\n`age` object with the `var` keyword, but we also have explicitly annotated the data type\nof the `age` object with the `u8` type this time. The basic idea is, when we use a variable/mutable object,\nthe Zig compiler ask for us to be more explicit with what we want, to be more clear\nabout what our code does. This translates into being more explicit about the data types that we want\nto use in our objects.\n\nTherefore, if you transform your object into a variable/mutable object, just remember to always\nannotate the type of the object explicitly in your code. Otherwise, the Zig compiler might raise\na compilation error, asking you to transform your object back into a `const` object, or,\nto give your object an \"explicit type\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIt's important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code uses this object while it's uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object.\n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e., if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to a special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It's discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also gets discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig has many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e., the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\nIt's worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it has the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it's a slice that\naccesses all elements in the array.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhas 2 elements in it.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" in @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth in @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially in @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned in @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e., both the start and the end of this range)\nis known at compile-time, the slice object that gets created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nin @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that gets created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e., a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can\ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice has a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n_ = slice;\n```\n:::\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat gets created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, we are reading a file, and then, we try to create a slice object\nthat covers the entire buffer that contains the contents of this file. This is obviously\nan example of a runtime known range, because the end index of the range\nis not known at compile time.\n\nIn other words, the end index of the range is the size of\nthe array `file_contents`. However, the size of `file_contents` is not known at compile time.\nBecause we don't know how many bytes are stored inside this `shop-list.txt` file.\nAnd because this is a file, someone might edit this file tomorrow and add more lines\nor remove lines from it. Therefore, the size of this file might vary drastically from one execution to another.\n\nNow, if the file size can vary from one run to another, then, we can conclude that the value of the expression\n`file_contents.len` exposed in the example below can also vary from one run to another. As consequence,\nthe value of the expression `file_contents.len` is runtime-known only, and, as a consequence of that,\nthe range `0..file_contents.len` is also runtime-known only.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\nfn read_file(allocator: std.mem.Allocator, path: []const u8) ![]u8 {\n    const file = try std.fs.cwd().openFile(path, .{});\n    defer file.close();\n    return try file.reader().readAllAlloc(\n        allocator, std.math.maxInt(usize)\n    );\n}\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const path = \"../ZigExamples/file-io/shop-list.txt\";\n    const file_contents = try read_file(allocator, path);\n    const slice = file_contents[0..file_contents.len];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code has its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e., a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nStrings in Zig work very similarly to strings in C, but they come with some extra caveats which adds more safety\nand efficiency to them. You could also say that Zig simply uses a more modern and safe approach to manage\nand use strings.\n\nA string in Zig is essentially an array of arbitrary bytes, or, more specifically, an array of `u8` values.\nThis very similar to a string in C, which is also interpreted as an array of arbitrary bytes, or, in the case\nof C, an array of `char` (which usually represents an unsigned 8-bit integer value in most systems) values.\n\nNow, because a string in Zig is an array, you automatically\nget the length of the string (i.e. the length of the array) embedded in the value itself. This makes\nall the difference! Because now, the Zig compiler can use the length value that is embedded in the string to\ncheck for \"buffer overflow\" or \"wrong memory access\" problems in your code.\n\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need to do something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible in the string value itself. You can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\nAnother point is that Zig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e., a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\n### Using a slice versus a sentinel-terminated array\n\nIn memory, all string values in Zig are always stored in the same way.\nThey are simply stored as sequences/arrays of arbitrary bytes. But you can use and access\nthis sequence of bytes in two different ways. You can access this sequence of bytes as:\n\n- a sentinel-terminated array of `u8` values.\n- or as a slice of `u8` values.\n\n\n#### Sentinel-terminated arrays\n\nSentinel-terminated arrays in Zig are described in the Language Reference of Zig[^sentinel].\nIn summary a sentinel-terminated array is just a normal array, but, the difference is that they\ncontain a \"sentinel value\" at the last index/element of the array. With a sentinel-terminated array\nyou embed both the length of the array, and also, the sentinel value in the type itself of your object.\n\n[^sentinel]: <https://ziglang.org/documentation/master/#Sentinel-Terminated-Arrays>.\n\nFor example, if you write a string literal value in your code, and ask Zig to print the data type of this value,\nyou usually get a data type in the format `*const [n:0]u8`. The `n` in the data type indicates the size of\nthe string (that is the length of the array). The zero after the `n:` part of the data type is the sentinel\nvalue itself.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n_ = \"A literal value\";\ntry stdout.print(\"{any}\\n\", .{@TypeOf(\"A literal value\")});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n*const [15:0]u8\n```\n\n\n:::\n:::\n\n\n\n\nSo, with this data type `*const [n:0]u8` you are essentially saying that you have an array of `u8` values\nof length `n`, where, the element at the index corresponding to the length `n` in the array is the\nnumber zero. If you really think about this description, you will notice that this is just a fancy way to\ndescribe a string in C, which is a null-terminated array of bytes. The `NULL` value in C is the number\nzero. So, an array that ends in a null/zero value in C is essentially a sentinel-terminated array in Zig,\nwhere the sentinel value of the array is the number zero.\n\nTherefore, a string literal value in Zig is just a pointer to a null-terminated array of bytes (i.e., similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string, and also, the fact that they are \"NULL terminated\",\ninto the data type of the value itself.\n\n\n\n#### Slice\n\nYou can also access and use the arbitrary sequence of bytes that represent your string as a slice of `u8` values.\nThe majority of functions from the Zig standard library usually receive strings as inputs as slices of\n`u8` values (slices were presented in @sec-arrays).\n\nThus, you will see a lot of string values with a data type of `[]u8` or `[]const u8`, depending if the object\nwhere this string is stored is marked as constant with `const`, or as variable with `var`. Now, because\nthe string in this case is being interpreted as a slice, this slice is not necessarilly null-terminated,\nbecause now, the sentinel value is not mandatory. You can include the null/zero value in the slice if you\nwant to, but there is no need to do it.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string value being\n// interpreted as a slice.\nconst str: []const u8 = \"A string value\";\ntry stdout.print(\"{any}\\n\", .{@TypeOf(str)});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n[]const u8\n```\n\n\n:::\n:::\n\n\n\n\n\n### Iterating through the string\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below,\nand also, you can see that this is a null-terminated array, because of the zero value after the `:` character in the data type.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it's a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n:::\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIt's important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop through the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig in @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers in @sec-root-file and especially in @sec-assignments.\n- How strings work in Zig in @sec-zig-strings.\n- How to use arrays and slices in @sec-arrays.\n- How to import functionality from other Zig modules in @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* in @sec-structs-and-oop.\n- Basic control flow syntax in @sec-zig-control-flow.\n- Enums in @sec-enum;\n- Pointers and Optionals in @sec-pointer;\n- Error handling with `try` and `catch` in @sec-error-handling;\n- Unit tests in @sec-unittests;\n- Vectors in @sec-vectors-simd;\n- Build System in @sec-build-system;\n",
-    "supporting": [
-      "01-zig-weird_files"
-    ],
-    "filters": [
-      "rmarkdown/pagebreak.lua"
-    ],
-    "includes": {},
-    "engineDependencies": {
-      "knitr": [
-        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
-      ]
-    },
-    "preserve": null,
-    "postProcess": false
-  }
-}
\ No newline at end of file
diff --git a/_freeze/Chapters/01-zig-weird/execute-results/html.json b/_freeze/Chapters/01-zig-weird/execute-results/html.json
index 4920b2b5..6ef9bbe0 100644
--- a/_freeze/Chapters/01-zig-weird/execute-results/html.json
+++ b/_freeze/Chapters/01-zig-weird/execute-results/html.json
@@ -2,7 +2,7 @@
   "hash": "4d435d48922c81726d4668b9e1fc1e4f",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\nlanguage, it's still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. Sometimes, they really make it hard to debug\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscure the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that gets compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e., where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contains Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nWe can use this build system to write small scripts in Zig,\nwhich describe the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e., creating new objects)\nare made in Zig. You can create a new object in Zig by using the syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). In @sec-assignments we talk more about objects in general.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\n\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that in @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIt's worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt's like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\n\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portable C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nIn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e., the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. If you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith an \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, on Windows, operations like accessing the `stdout` (or opening a file) depend on\nresources that are available only at *runtime* (you will learn more about compile-time versus runtime\nin @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerges from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword in @sec-comptime.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation in a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues\n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described in @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig later in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig?\nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar to our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentation.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It's a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (on YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e., identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nSo, if you want to change the value of your object, you need to transform your immutable (or \"constant\")\nobject into a mutable (or \"variable\") object. You can do that by using the `var` keyword.\nThis keyword stands for \"variable\", and when you apply this keyword to some object, you are\ntelling the Zig compiler that the value associated with this object might change at some point.\n\nThus, if we come back to the previous example, and change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it's a \"variable object\".\n\nHowever, if you take a look at the example below, you will notice that we have not only declared the\n`age` object with the `var` keyword, but we also have explicitly annotated the data type\nof the `age` object with the `u8` type this time. The basic idea is, when we use a variable/mutable object,\nthe Zig compiler ask for us to be more explicit with what we want, to be more clear\nabout what our code does. This translates into being more explicit about the data types that we want\nto use in our objects.\n\nTherefore, if you transform your object into a variable/mutable object, just remember to always\nannotate the type of the object explicitly in your code. Otherwise, the Zig compiler might raise\na compilation error, asking you to transform your object back into a `const` object, or,\nto give your object an \"explicit type\".\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIt's important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code uses this object while it's uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\n\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object.\n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e., if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to a special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\n\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It's discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also gets discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig has many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e., the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\n\n\n\nIt's worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\n\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it has the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\n\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it's a slice that\naccesses all elements in the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhas 2 elements in it.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" in @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\n\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth in @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially in @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned in @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e., both the start and the end of this range)\nis known at compile-time, the slice object that gets created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nin @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that gets created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e., a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can\ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice has a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n_ = slice;\n```\n:::\n\n\n\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat gets created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, we are reading a file, and then, we try to create a slice object\nthat covers the entire buffer that contains the contents of this file. This is obviously\nan example of a runtime known range, because the end index of the range\nis not known at compile time.\n\nIn other words, the end index of the range is the size of\nthe array `file_contents`. However, the size of `file_contents` is not known at compile time.\nBecause we don't know how many bytes are stored inside this `shop-list.txt` file.\nAnd because this is a file, someone might edit this file tomorrow and add more lines\nor remove lines from it. Therefore, the size of this file might vary drastically from one execution to another.\n\nNow, if the file size can vary from one run to another, then, we can conclude that the value of the expression\n`file_contents.len` exposed in the example below can also vary from one run to another. As consequence,\nthe value of the expression `file_contents.len` is runtime-known only, and, as a consequence of that,\nthe range `0..file_contents.len` is also runtime-known only.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\nfn read_file(allocator: std.mem.Allocator, path: []const u8) ![]u8 {\n    const file = try std.fs.cwd().openFile(path, .{});\n    defer file.close();\n    return try file.reader().readAllAlloc(\n        allocator, std.math.maxInt(usize)\n    );\n}\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const path = \"../ZigExamples/file-io/shop-list.txt\";\n    const file_contents = try read_file(allocator, path);\n    const slice = file_contents[0..file_contents.len];\n    _ = slice;\n}\n```\n:::\n\n\n\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code has its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e., a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nStrings in Zig work very similarly to strings in C, but they come with some extra caveats which adds more safety\nand efficiency to them. You could also say that Zig simply uses a more modern and safe approach to manage\nand use strings.\n\nA string in Zig is essentially an array of arbitrary bytes, or, more specifically, an array of `u8` values.\nThis very similar to a string in C, which is also interpreted as an array of arbitrary bytes, or, in the case\nof C, an array of `char` (which usually represents an unsigned 8-bit integer value in most systems) values.\n\nNow, because a string in Zig is an array, you automatically\nget the length of the string (i.e. the length of the array) embedded in the value itself. This makes\nall the difference! Because now, the Zig compiler can use the length value that is embedded in the string to\ncheck for \"buffer overflow\" or \"wrong memory access\" problems in your code.\n\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need to do something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible in the string value itself. You can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\n\n\n\nAnother point is that Zig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e., a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n### Using a slice versus a sentinel-terminated array\n\nIn memory, all string values in Zig are always stored in the same way.\nThey are simply stored as sequences/arrays of arbitrary bytes. But you can use and access\nthis sequence of bytes in two different ways. You can access this sequence of bytes as:\n\n- a sentinel-terminated array of `u8` values.\n- or as a slice of `u8` values.\n\n\n#### Sentinel-terminated arrays\n\nSentinel-terminated arrays in Zig are described in the Language Reference of Zig[^sentinel].\nIn summary a sentinel-terminated array is just a normal array, but, the difference is that they\ncontain a \"sentinel value\" at the last index/element of the array. With a sentinel-terminated array\nyou embed both the length of the array, and also, the sentinel value in the type itself of your object.\n\n[^sentinel]: <https://ziglang.org/documentation/master/#Sentinel-Terminated-Arrays>.\n\nFor example, if you write a string literal value in your code, and ask Zig to print the data type of this value,\nyou usually get a data type in the format `*const [n:0]u8`. The `n` in the data type indicates the size of\nthe string (that is the length of the array). The zero after the `n:` part of the data type is the sentinel\nvalue itself.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n_ = \"A literal value\";\ntry stdout.print(\"{any}\\n\", .{@TypeOf(\"A literal value\")});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n*const [15:0]u8\n```\n\n\n:::\n:::\n\n\n\n\n\n\nSo, with this data type `*const [n:0]u8` you are essentially saying that you have an array of `u8` values\nof length `n`, where, the element at the index corresponding to the length `n` in the array is the\nnumber zero. If you really think about this description, you will notice that this is just a fancy way to\ndescribe a string in C, which is a null-terminated array of bytes. The `NULL` value in C is the number\nzero. So, an array that ends in a null/zero value in C is essentially a sentinel-terminated array in Zig,\nwhere the sentinel value of the array is the number zero.\n\nTherefore, a string literal value in Zig is just a pointer to a null-terminated array of bytes (i.e., similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string, and also, the fact that they are \"NULL terminated\",\ninto the data type of the value itself.\n\n\n\n#### Slice\n\nYou can also access and use the arbitrary sequence of bytes that represent your string as a slice of `u8` values.\nThe majority of functions from the Zig standard library usually receive strings as inputs as slices of\n`u8` values (slices were presented in @sec-arrays).\n\nThus, you will see a lot of string values with a data type of `[]u8` or `[]const u8`, depending if the object\nwhere this string is stored is marked as constant with `const`, or as variable with `var`. Now, because\nthe string in this case is being interpreted as a slice, this slice is not necessarilly null-terminated,\nbecause now, the sentinel value is not mandatory. You can include the null/zero value in the slice if you\nwant to, but there is no need to do it.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string value being\n// interpreted as a slice.\nconst str: []const u8 = \"A string value\";\ntry stdout.print(\"{any}\\n\", .{@TypeOf(str)});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n[]const u8\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n### Iterating through the string\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below,\nand also, you can see that this is a null-terminated array, because of the zero value after the `:` character in the data type.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it's a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n:::\n\n\n\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIt's important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop through the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\n\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig in @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers in @sec-root-file and especially in @sec-assignments.\n- How strings work in Zig in @sec-zig-strings.\n- How to use arrays and slices in @sec-arrays.\n- How to import functionality from other Zig modules in @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* in @sec-structs-and-oop.\n- Basic control flow syntax in @sec-zig-control-flow.\n- Enums in @sec-enum;\n- Pointers and Optionals in @sec-pointer;\n- Error handling with `try` and `catch` in @sec-error-handling;\n- Unit tests in @sec-unittests;\n- Vectors in @sec-vectors-simd;\n- Build System in @sec-build-system;\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Introducing Zig\n\nIn this chapter, I want to introduce you to the world of Zig.\nZig is a very young language that is being actively developed.\nAs a consequence, its world is still very wild and to be explored.\nThis book is my attempt to help you on your personal journey for\nunderstanding and exploring the exciting world of Zig.\n\nI assume you have previous experience with some programming\nlanguage in this book, not necessarily with a low-level one.\nSo, if you have experience with Python, or Javascript, for example, it will be fine.\nBut, if you do have experience with low-level languages, such as C, C++, or\nRust, you will probably learn faster throughout this book.\n\n## What is Zig?\n\nZig is a modern, low-level, and general-purpose programming language. Some programmers think of\nZig as a modern and better version of C.\n\nIn the author's personal interpretation, Zig is tightly connected with \"less is more\".\nInstead of trying to become a modern language by adding more and more features,\nmany of the core improvements that Zig brings to the\ntable are actually about removing annoying behaviours/features from C and C++.\nIn other words, Zig tries to be better by simplifying the language, and by having more consistent and robust behaviour.\nAs a result, analyzing, writing and debugging applications become much easier and simpler in Zig, than it is in C or C++.\n\nThis philosophy becomes clear with the following phrase from the official website of Zig:\n\n> \"Focus on debugging your application rather than debugging your programming language knowledge\".\n\nThis phrase is specially true for C++ programmers. Because C++ is a gigantic language,\nwith tons of features, and also, there are lots of different \"flavors of C++\". These elements\nare what makes C++ so complex and hard to learn. Zig tries to go in the opposite direction.\nZig is a very simple language, more closely related to other simple languages such as C and Go.\n\nThe phrase above is still important for C programmers too. Because, even C being a simple\nlanguage, it's still hard sometimes to read and understand C code. For example, pre-processor macros in\nC are a frequent source of confusion. Sometimes, they really make it hard to debug\nC programs. Because macros are essentially a second language embedded in C that obscures\nyour C code. With macros, you are no longer 100% sure about which pieces\nof the code are being sent to the compiler, i.e.\nthey obscure the actual source code that you wrote.\n\nYou don't have macros in Zig. In Zig, the code you write, is the actual code that gets compiled by the compiler.\nYou also don't have a hidden control flow happening behind the scenes. And, you also\ndon't have functions or operators from the standard library that make\nhidden memory allocations behind your back.\n\nBy being a simpler language, Zig becomes much more clear and easier to read/write,\nbut at the same time, it also achieves a much more robust state, with more consistent\nbehaviour in edge situations. Once again, less is more.\n\n\n## Hello world in Zig\n\nWe begin our journey in Zig by creating a small \"Hello World\" program.\nTo start a new Zig project in your computer, you simply call the `init` command\nfrom the `zig` compiler.\nJust create a new directory in your computer, then, init a new Zig project\ninside this directory, like this:\n\n```bash\nmkdir hello_world\ncd hello_world\nzig init\n```\n\n```\ninfo: created build.zig\ninfo: created build.zig.zon\ninfo: created src/main.zig\ninfo: created src/root.zig\ninfo: see `zig build --help` for a menu of options\n```\n\n### Understanding the project files {#sec-project-files}\n\nAfter you run the `init` command from the `zig` compiler, some new files\nare created inside of your current directory. First, a \"source\" (`src`) directory\nis created, containing two files, `main.zig` and `root.zig`. Each `.zig` file\nis a separate Zig module, which is simply a text file that contains some Zig code.\n\nBy convention, the `main.zig` module is where your main function lives. Thus,\nif you are building an executable program in Zig, you need to declare a `main()` function,\nwhich represents the entrypoint of your program, i.e., where the execution of your program begins.\n\nHowever, if you are building a library (instead of an executable program), then,\nthe normal procedure is to delete this `main.zig` file and start with the `root.zig` module.\nBy convention, the `root.zig` module is the root source file of your library.\n\n```bash\ntree .\n```\n\n```\n.\n├── build.zig\n├── build.zig.zon\n└── src\n    ├── main.zig\n    └── root.zig\n\n1 directory, 4 files\n```\n\nThe `init` command also creates two additional files in our working directory:\n`build.zig` and `build.zig.zon`. The first file (`build.zig`) represents a build script written in Zig.\nThis script is executed when you call the `build` command from the `zig` compiler.\nIn other words, this file contains Zig code that executes the necessary steps to build the entire project.\n\n\nLow-level languages normally use a compiler to build your\nsource code into binary executables or binary libraries.\nNevertheless, this process of compiling your source code and building\nbinary executables or binary libraries from it, became a real challenge\nin the programming world, once the projects became bigger and bigger.\nAs a result, programmers created \"build systems\", which are a second set of tools designed to make this process\nof compiling and building complex projects, easier.\n\nExamples of build systems are CMake, GNU Make, GNU Autoconf and Ninja,\nwhich are used to build complex C and C++ projects.\nWith these systems, you can write scripts, which are called \"build scripts\".\nThey simply are scripts that describes the necessary steps to compile/build\nyour project.\n\nHowever, these are separate tools, that do not\nbelong to C/C++ compilers, like `gcc` or `clang`.\nAs a result, in C/C++ projects, you have not only to install and\nmanage your C/C++ compilers, but you also have to install and manage\nthese build systems separately.\n\nIn Zig, we don't need to use a separate set of tools to build our projects,\nbecause a build system is embedded inside the language itself.\nWe can use this build system to write small scripts in Zig,\nwhich describe the necessary steps to build/compile our Zig project[^zig-build-system].\nSo, everything you need to build a complex Zig project is the\n`zig` compiler, and nothing more.\n\n[^zig-build-system]: <https://ziglang.org/learn/overview/#zig-build-system>.\n\n\nThe second generated file (`build.zig.zon`) is a JSON-like file, in which you can describe\nyour project, and also, declare a set of dependencies of your project that you want to fetch from the internet.\nIn other words, you can use this `build.zig.zon` file to include a list of external libraries in your project.\n\nOne possible way to include an external Zig library in your project, is to manually build\nand install the library in your system, and just link your source code\nwith the library at the build step of your project.\n\nHowever, if this external Zig library is available on GitHub for example,\nand it has a valid `build.zig.zon` file in root folder of the project,\nwhich describes the project, you can easily include this library in\nyour project by simply listing this external library in your `build.zig.zon` file.\n\nIn other words, this `build.zig.zon` file works similarly to the `package.json`\nfile in Javascript projects, or the `Pipfile` file in Python projects,\nor the `Cargo.toml` file in Rust projects. You can read more about this\nspecific file in a couple of articles on the internet[^zig-zon][^zig-zon2], and\nyou can also see the expected schema for this `build.zig.zon` file\nin a documentation file inside the official repository of Zig[^zig-zon-schema].\n\n[^zig-zon]: <https://zig.news/edyu/zig-package-manager-wtf-is-zon-558e>\n[^zig-zon2]: <https://medium.com/@edlyuu/zig-package-manager-2-wtf-is-build-zig-zon-and-build-zig-0-11-0-update-5bc46e830fc1>\n[^zig-zon-schema]: <https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md>\n\n### The file `root.zig` {#sec-root-file}\n\nLet's take a look into the `root.zig` file.\nYou might have noticed that every line of code with an expression ends with a semicolon (`;`).\nThis follows the syntax of a C-family programming language[^c-family].\n\n[^c-family]: <https://en.wikipedia.org/wiki/List_of_C-family_programming_languages>\n\nAlso, notice the `@import()` call at the first line. We use this built-in function\nto import functionality from other Zig modules into our current module.\nThis `@import()` function works similarly to the `#include` pre-processor\nin C or C++, or, to the `import` statement in Python or Javascript code.\nIn this example, we are importing the `std` module,\nwhich gives you access to the Zig Standard Library.\n\nIn this `root.zig` file, we can also see how assignments (i.e., creating new objects)\nare made in Zig. You can create a new object in Zig by using the syntax\n`(const|var) name = value;`. In the example below, we are creating two constant\nobjects (`std` and `testing`). In @sec-assignments we talk more about objects in general.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst testing = std.testing;\n\nexport fn add(a: i32, b: i32) i32 {\n    return a + b;\n}\n```\n:::\n\n\nFunctions in Zig are declared using the `fn` keyword.\nIn this `root.zig` module, we are declaring a function called `add()`, which has two arguments named `a` and `b`.\nThe function returns an integer of the type `i32` as result.\n\n\nZig is a strongly-typed language. There are some specific situations where you can (if you want to) omit\nthe type of an object in your code, if this type can be inferred by the `zig` compiler (we talk more\nabout that in @sec-type-inference). But there are other situations where you do need to be explicit.\nFor example, you do have to explicitly specify the type of each function argument, and also,\nthe return type of every function that you create in Zig.\n\nWe specify the type of an object or a function argument in Zig by\nusing a colon character (`:`) followed by the type after the name of this object/function argument.\nWith the expressions `a: i32` and `b: i32`, we know that both `a` and `b` arguments have type `i32`,\nwhich is a signed 32 bit integer. In this part,\nthe syntax in Zig is identical to the syntax in Rust, which also specifies types by\nusing the colon character.\n\nLastly, we have the return type of the function at the end of the line, before we open\nthe curly braces to start writing the function's body. In the example above, this type is also\na signed 32 bit integer (`i32`) value.\n\nNotice that we also have an `export` keyword before the function declaration. This keyword\nis similar to the `extern` keyword in C. It exposes the function\nto make it available in the library API. Therefore, if you are writing\na library for other people to use, you have to expose the functions\nyou write in the public API of this library by using this `export` keyword.\nIf we removed the `export` keyword from the `add()` function declaration,\nthen, this function would be no longer exposed in the library object built\nby the `zig` compiler.\n\n\n### The `main.zig` file {#sec-main-file}\n\nNow that we have learned a lot about Zig's syntax from the `root.zig` file,\nlet's take a look at the `main.zig` file.\nA lot of the elements we saw in `root.zig` are also present in `main.zig`.\nBut there are some other elements that we haven't seen yet, so let's dive in.\n\nFirst, look at the return type of the `main()` function in this file.\nWe can see a small change. The return type of the function (`void`) is accompanied by an exclamation mark (`!`).\nThis exclamation mark tells us that this `main()` function might return an error.\n\nIt's worth noting that, a `main()` function in Zig is allowed to return nothing (`void`),\nor an unsigned 8-bit integer (`u8`) value[^u8-example], or an error. In other words, you can write your `main()` function in Zig\nto return essentially nothing (`void`), or, if you prefer, you can also write a more C-like `main()` function,\nwhich returns an integer value that usually serves as a \"status code\" for the process.\n\n[^u8-example]: You can see an example of a `main()` function that returns an `u8` value in the `return-integer.zig` file, <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/zig-basics/return-integer.zig>\n\nIn this example, the return type annotation of `main()` indicates that this function can either\nreturn nothing (`void`), or return an error. This exclamation mark in the return type annotation\nis an interesting and powerful feature of Zig. In summary, if you write a function and something inside\nthe body of this function might return an error, then, you are forced to:\n\n- either add the exclamation mark to the return type of the function and make it clear that\nthis function might return an error.\n- explicitly handle this error inside the function.\n\nIn most programming languages, we normally handle (or deal with) an error through\na *try catch* pattern. Zig does have both `try` and `catch` keywords. But they work\na little differently than what you're probably used to in other languages.\n\nIf we look at the `main()` function below, you can see that we do have a `try` keyword\non the 5th line. But we do not have a `catch` keyword in this code.\nIn Zig, we use the `try` keyword to execute an expression that might return an error,\nwhich, in this example, is the `stdout.print()` expression.\n\nIn essence, the `try` keyword executes the expression `stdout.print()`. If this expression\nreturns a valid value, then, the `try` keyword does absolutely nothing. It only passes the value forward.\nIt's like if this `try` keyword was never there. However, if the expression does return an error, then,\nthe `try` keyword will unwrap the error value, then, it returns this error from the function\nand also prints the current stack trace to `stderr`.\n\nThis might sound weird to you if you come from a high-level language. Because in\nhigh-level languages, such as Python, if an error occurs somewhere, this error is automatically\nreturned and the execution of your program will automatically stop even if you don't want\nto stop the execution. You are obligated to face the error.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n:::\n\n\nAnother thing that you might have noticed in this code example, is that\nthe `main()` function is marked with the `pub` keyword. It marks the `main()`\nfunction as a *public function* from this module. Every function in your Zig\nmodule is by default private to this Zig module and can only be called from within the module.\nUnless, you explicitly mark this function as a public function with the `pub` keyword.\n\nIf you think about it, this `pub` keyword in Zig does essentially the opposite of what the `static` keyword\ndo in C/C++. By making a function \"public\" you allow other Zig modules to access and call this function.\nA calling Zig module imports another module by using the `@import()` built-in function, which makes\nall public functions from the imported module visible to the calling Zig module.\n\n\n### Compiling your source code {#sec-compile-code}\n\nYou can compile your Zig modules into a binary executable by running the `build-exe` command\nfrom the `zig` compiler. You simply list all the Zig modules that you want to build after\nthe `build-exe` command, separated by spaces. In the example below, we are compiling the module `main.zig`.\n\n```bash\nzig build-exe src/main.zig\n```\n\nSince we are building an executable, the `zig` compiler will look for a `main()` function\ndeclared in any of the files that you list after the `build-exe` command. If\nthe compiler does not find a `main()` function declared somewhere, a\ncompilation error will be raised, warning about this mistake.\n\nThe `zig` compiler also offers a `build-lib` and `build-obj` commands, which work\nthe exact same way as the `build-exe` command. The only difference is that, they compile your\nZig modules into a portable C ABI library, or, into object files, respectively.\n\nIn the case of the `build-exe` command, a binary executable file is created by the `zig`\ncompiler in the root directory of your project.\nIf we take a look now at the contents of our current directory, with a simple `ls` command, we can\nsee the binary file called `main` that was created by the compiler.\n\n```bash\nls\n```\n\n```\nbuild.zig  build.zig.zon  main  src\n```\n\nIf I execute this binary executable, I get the \"Hello World\" message in the terminal\n, as we expected.\n\n```bash\n./main\n```\n\n```\nHello, world!\n```\n\n\n### Compile and execute at the same time {#sec-compile-run-code}\n\nIn the previous section, I presented the `zig build-exe` command, which\ncompiles Zig modules into an executable file. However, this means that,\nin order to execute the executable file, we have to run two different commands.\nFirst, the `zig build-exe` command, and then, we call the executable file\ncreated by the compiler.\n\nBut what if we wanted to perform these two steps,\nall at once, in a single command? We can do that by using the `zig run`\ncommand.\n\n```bash\nzig run src/main.zig\n```\n\n```\nHello, world!\n```\n\n\n### Important note for Windows users\n\nFirst of all, this is a Windows-specific thing, and, therefore, does not apply to other\noperating systems, such as Linux and macOS. In summary, if you have a piece of Zig code that\nincludes some global variables whose initialization rely on runtime resources, then,\nyou might have some troubles while trying to compile this Zig code on Windows.\n\nAn example of that is accessing the `stdout` (i.e., the *standard output* of your system), which is usually\ndone in Zig by using the expression `std.io.getStdOut()`. If you use this expression to instantiate\na global variable in a Zig module, then, the compilation of your Zig code will very likely fail on Windows,\nwith an \"unable to evaluate comptime expression\" error message.\n\nThis failure in the compilation process happens because all global variables in Zig are initialized\nat *compile-time*. However, on Windows, operations like accessing the `stdout` (or opening a file) depend on\nresources that are available only at *runtime* (you will learn more about compile-time versus runtime\nin @sec-compile-time).\n\nFor example, if you try to compile this code example on Windows, you will likely get the error message\nexposed below:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n// ERROR! Compile-time error that emerges from\n// this next line, on the `stdout` object\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n```\nt.zig:2107:28: error: unable to evaluate comptime expression\n    break :blk asm {\n               ^~~\n```\n\n\n\nTo avoid this problem on Windows, we need to force the `zig` compiler to instantiate this\n`stdout` object only at runtime, instead of instantiating it at compile-time. We can achieve\nthat by simply moving the expression to a function body.\n\nThis solves the problem because all expressions that are inside a function body in Zig\nare evaluated only at runtime, unless you use the `comptime` keyword explicitly to change this behaviour.\nYou will learn more about this `comptime` keyword in @sec-comptime.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    // SUCCESS: Stdout initialized at runtime.\n    const stdout = std.io.getStdOut().writer();\n    _ = try stdout.write(\"Hello\\n\");\n}\n```\n:::\n\n\n```\nHello\n```\n\nYou can read more details about this Windows-specific limitation in a couple of\nGitHub issues opened at the official Zig repository. More specifically, the issues\n17186 [^cissue1] and 19864 [^cissue2].\n\n[^cissue1]: <https://github.com/ziglang/zig/issues/17186>\n[^cissue2]: <https://github.com/ziglang/zig/issues/19864>\n\n\n### Compiling the entire project {#sec-compile-project}\n\nJust as I described in @sec-project-files, as our project grows in size and\ncomplexity, we usually prefer to organize the compilation and build process\nof the project into a build script, using some sort of \"build system\".\n\nIn other words, as our project grows in size and complexity,\nthe `build-exe`, `build-lib` and `build-obj` commands become\nharder to use directly. Because then, we start to list\nmultiple and multiple modules at the same time. We also\nstart to add built-in compilation flags to customize the\nbuild process for our needs, etc. It becomes a lot of work\nto write the necessary commands by hand.\n\nIn C/C++ projects, programmers normally opt to use CMake, Ninja, `Makefile` or `configure` scripts\nto organize this process. However, in Zig, we have a native build system in the language itself.\nSo, we can write build scripts in Zig to compile and build Zig projects. Then, all we\nneed to do, is to call the `zig build` command to build our project.\n\nSo, when you execute the `zig build` command, the `zig` compiler will search\nfor a Zig module named `build.zig` inside your current directory, which\nshould be your build script, containing the necessary code to compile and\nbuild your project. If the compiler does find this `build.zig` file in your directory,\nthen, the compiler will essentially execute a `zig run` command\nover this `build.zig` file, to compile and execute this build\nscript, which in turn, will compile and build your entire project.\n\n\n```bash\nzig build\n```\n\n\nAfter you execute this \"build project\" command, a `zig-out` directory\nis created in the root of your project directory, where you can find\nthe binary executables and libraries created from your Zig modules\naccordingly to the build commands that you specified at `build.zig`.\nWe will talk more about the build system in Zig later in this book.\n\nIn the example below, I'm executing the binary executable\nnamed `hello_world` that was generated by the compiler after the\n`zig build` command.\n\n```bash\n./zig-out/bin/hello_world\n```\n\n```\nHello, world!\n```\n\n\n\n## How to learn Zig?\n\nWhat are the best strategies to learn Zig?\nFirst of all, of course this book will help you a lot on your journey through Zig.\nBut you will also need some extra resources if you want to be really good at Zig.\n\nAs a first tip, you can join a community with Zig programmers to get some help\n, when you need it:\n\n- Reddit forum: <https://www.reddit.com/r/Zig/>;\n- Ziggit community: <https://ziggit.dev/>;\n- Discord, Slack, Telegram, and others: <https://github.com/ziglang/zig/wiki/Community>;\n\nNow, one of the best ways to learn Zig is to simply read Zig code. Try\nto read Zig code often, and things will become more clear.\nA C/C++ programmer would also probably give you this same tip.\nBecause this strategy really works!\n\nNow, where can you find Zig code to read?\nI personally think that, the best way of reading Zig code is to read the source code of the\nZig Standard Library. The Zig Standard Library is available at the [`lib/std` folder](https://github.com/ziglang/zig/tree/master/lib/std)[^zig-lib-std] on\nthe official GitHub repository of Zig. Access this folder, and start exploring the Zig modules.\n\nAlso, a great alternative is to read code from other large Zig\ncodebases, such as:\n\n1. the [Javascript runtime Bun](https://github.com/oven-sh/bun)[^bunjs].\n1. the [game engine Mach](https://github.com/hexops/mach)[^mach].\n1. a [LLama 2 LLM model implementation in Zig](https://github.com/cgbur/llama2.zig/tree/main)[^ll2].\n1. the [financial transactions database `tigerbeetle`](https://github.com/tigerbeetle/tigerbeetle)[^tiger].\n1. the [command-line arguments parser `zig-clap`](https://github.com/Hejsil/zig-clap)[^clap].\n1. the [UI framework `capy`](https://github.com/capy-ui/capy)[^capy].\n1. the [Language Protocol implementation for Zig, `zls`](https://github.com/zigtools/zls)[^zls].\n1. the [event-loop library `libxev`](https://github.com/mitchellh/libxev)[^xev].\n\n[^xev]: <https://github.com/mitchellh/libxev>\n[^zls]: <https://github.com/zigtools/zls>\n[^capy]: <https://github.com/capy-ui/capy>\n[^clap]: <https://github.com/Hejsil/zig-clap>\n[^tiger]: <https://github.com/tigerbeetle/tigerbeetle>\n[^ll2]: <https://github.com/cgbur/llama2.zig/tree/main>\n[^mach]: <https://github.com/hexops/mach>\n[^bunjs]: <https://github.com/oven-sh/bun>.\n\nAll these assets are available on GitHub,\nand this is great, because we can use the GitHub search bar to our advantage,\nto find Zig code that fits our description.\nFor example, you can always include `lang:Zig` in the GitHub search bar when you\nare searching for a particular pattern. This will limit the search to only Zig modules.\n\n[^zig-lib-std]: <https://github.com/ziglang/zig/tree/master/lib/std>\n\nAlso, a great alternative is to consult online resources and documentation.\nHere is a quick list of resources that I personally use from time to time to learn\nmore about the language each day:\n\n- Zig Language Reference: <https://ziglang.org/documentation/master/>;\n- Zig Standard Library Reference: <https://ziglang.org/documentation/master/std/>;\n- Zig Guide: <https://zig.guide/>;\n- Karl Seguin Blog: <https://www.openmymind.net/>;\n- Zig News: <https://zig.news/>;\n- Read the code written by one of the Zig core team members: <https://github.com/kubkon>;\n- Some livecoding sessions are transmitted in the Zig Showtime Youtube Channel: <https://www.youtube.com/@ZigSHOWTIME/videos>;\n\n\nAnother great strategy to learn Zig, or honestly, to learn any language you want,\nis to practice it by solving exercises. For example, there is a famous repository\nin the Zig community called [Ziglings](https://ziglings.org)[^ziglings]\n, which contains more than 100 small exercises that you can solve. It's a repository of\ntiny programs written in Zig that are currently broken, and your responsibility is to\nfix these programs, and make them work again.\n\n[^ziglings]: <https://ziglings.org>.\n\nA famous tech YouTuber known as *The Primeagen* also posted some videos (on YouTube)\nwhere he solves these exercises from Ziglings. The first video is named\n[\"Trying Zig Part 1\"](https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen)[^prime1].\n\n[^prime1]: <https://www.youtube.com/watch?v=OPuztQfM3Fg&t=2524s&ab_channel=TheVimeagen>.\n\nAnother great alternative, is to solve the [Advent of Code exercises](https://adventofcode.com/)[^advent-code].\nThere are people that already took the time to learn and solve the exercises, and they posted\ntheir solutions on GitHub as well, so, in case you need some resource to compare while solving\nthe exercises, you can look at these two repositories:\n\n- <https://github.com/SpexGuy/Zig-AoC-Template>;\n- <https://github.com/fjebaker/advent-of-code-2022>;\n\n[^advent-code]: <https://adventofcode.com/>\n\n\n\n\n\n\n## Creating new objects in Zig (i.e., identifiers) {#sec-assignments}\n\nLet's talk more about objects in Zig. Readers that have past experience\nwith other programming languages might know this concept through\na different name, such as: \"variable\" or \"identifier\". In this book, I choose\nto use the term \"object\" to refer to this concept.\n\nTo create a new object (or a new \"identifier\") in Zig, we use\nthe keywords `const` or `var`. These keywords specify if the object\nthat you are creating is mutable or not.\nIf you use `const`, then the object you are\ncreating is a constant (or immutable) object, which means that once you declare this object, you\ncan no longer change the value stored inside this object.\n\nOn the other side, if you use `var`, then, you are creating a variable (or mutable) object.\nYou can change the value of this object as many times you want. Using the\nkeyword `var` in Zig is similar to using the keywords `let mut` in Rust.\n\n### Constant objects vs variable objects\n\nIn the code example below, we are creating a new constant object called `age`.\nThis object stores a number representing the age of someone. However, this code example\ndoes not compile successfully. Because on the next line of code, we are trying to change the value\nof the object `age` to 25.\n\nThe `zig` compiler detects that we are trying to change\nthe value of an object/identifier that is constant, and because of that,\nthe compiler will raise a compilation error, warning us about the mistake.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 24;\n// The line below is not valid!\nage = 25;\n```\n:::\n\n\n```\nt.zig:10:5: error: cannot assign to constant\n    age = 25;\n      ~~^~~\n```\n\nSo, if you want to change the value of your object, you need to transform your immutable (or \"constant\")\nobject into a mutable (or \"variable\") object. You can do that by using the `var` keyword.\nThis keyword stands for \"variable\", and when you apply this keyword to some object, you are\ntelling the Zig compiler that the value associated with this object might change at some point.\n\nThus, if we come back to the previous example, and change the declaration of the\n`age` object to use the `var` keyword, then, the program gets compiled successfully.\nBecause now, the `zig` compiler detects that we are changing the value of an\nobject that allows this behaviour, because it's a \"variable object\".\n\nHowever, if you take a look at the example below, you will notice that we have not only declared the\n`age` object with the `var` keyword, but we also have explicitly annotated the data type\nof the `age` object with the `u8` type this time. The basic idea is, when we use a variable/mutable object,\nthe Zig compiler ask for us to be more explicit with what we want, to be more clear\nabout what our code does. This translates into being more explicit about the data types that we want\nto use in our objects.\n\nTherefore, if you transform your object into a variable/mutable object, just remember to always\nannotate the type of the object explicitly in your code. Otherwise, the Zig compiler might raise\na compilation error, asking you to transform your object back into a `const` object, or,\nto give your object an \"explicit type\".\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = 24;\nage = 25;\n```\n:::\n\n\n\n### Declaring without an initial value\n\nBy default, when you declare a new object in Zig, you must give it\nan initial value. In other words, this means\nthat we have to declare, and, at the same time, initialize every object we\ncreate in our source code.\n\nOn the other hand, you can, in fact, declare a new object in your source code,\nand not give it an explicit value. But we need to use a special keyword for that,\nwhich is the `undefined` keyword.\n\nIt's important to emphasize that, you should avoid using `undefined` as much as possible.\nBecause when you use this keyword, you leave your object uninitialized, and, as a consequence,\nif for some reason, your code uses this object while it's uninitialized, then, you will definitely\nhave undefined behaviour and major bugs in your program.\n\nIn the example below, I'm declaring the `age` object again. But this time,\nI do not give it an initial value. The variable is only initialized at\nthe second line of code, where I store the number 25 in this object.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar age: u8 = undefined;\nage = 25;\n```\n:::\n\n\nHaving these points in mind, just remember that you should avoid as much as possible to use `undefined` in your code.\nAlways declare and initialize your objects. Because this gives you much more safety in your program.\nBut in case you really need to declare an object without initializing it... the\n`undefined` keyword is the way to do it in Zig.\n\n\n### There is no such thing as unused objects\n\nEvery object (being constant or variable) that you declare in Zig **must be used in some way**. You can give this object\nto a function call, as a function argument, or, you can use it in another expression\nto calculate the value of another object, or, you can call a method that belongs to this\nparticular object.\n\nIt doesn't matter in which way you use it. As long as you use it.\nIf you try to break this rule, i.e., if your try to declare a object, but not use it,\nthe `zig` compiler will not compile your Zig source code, and it will issue a error\nmessage warning that you have unused objects in your code.\n\nLet's demonstrate this with an example. In the source code below, we declare a constant object\ncalled `age`. If you try to compile a simple Zig program with this line of code below,\nthe compiler will return an error as demonstrated below:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst age = 15;\n```\n:::\n\n\n```\nt.zig:4:11: error: unused local constant\n    const age = 15;\n          ^~~\n```\n\nEverytime you declare a new object in Zig, you have two choices:\n\n1. you either use the value of this object;\n1. or you explicitly discard the value of the object;\n\nTo explicitly discard the value of any object (constant or variable), all you need to do is to assign\nthis object to a special character in Zig, which is the underscore (`_`).\nWhen you assign an object to a underscore, like in the example below, the `zig` compiler will automatically\ndiscard the value of this particular object.\n\nYou can see in the example below that, this time, the compiler did not\ncomplain about any \"unused constant\", and successfully compiled our source code.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It compiles!\nconst age = 15;\n_ = age;\n```\n:::\n\n\nNow, remember, everytime you assign a particular object to the underscore, this object\nis essentially destroyed. It's discarded by the compiler. This means that you can no longer\nuse this object further in your code. It doesn't exist anymore.\n\nSo if you try to use the constant `age` in the example below, after we discarded it, you\nwill get a loud error message from the compiler (talking about a \"pointless discard\")\nwarning you about this mistake.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// It does not compile.\nconst age = 15;\n_ = age;\n// Using a discarded value!\nstd.debug.print(\"{d}\\n\", .{age + 2});\n```\n:::\n\n\n```\nt.zig:7:5: error: pointless discard\n    of local constant\n```\n\n\nThis same rule applies to variable objects. Every variable object must also be used in\nsome way. And if you assign a variable object to the underscore,\nthis object also gets discarded, and you can no longer use this object.\n\n\n\n### You must mutate every variable objects\n\nEvery variable object that you create in your source code must be mutated at some point.\nIn other words, if you declare an object as a variable\nobject, with the keyword `var`, and you do not change the value of this object\nat some point in the future, the `zig` compiler will detect this,\nand it will raise an error warning you about this mistake.\n\nThe concept behind this is that every object you create in Zig should be preferably a\nconstant object, unless you really need an object whose value will\nchange during the execution of your program.\n\nSo, if I try to declare a variable object such as `where_i_live` below,\nand I do not change the value of this object in some way,\nthe `zig` compiler raises an error message with the phrase \"variable is never mutated\".\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar where_i_live = \"Belo Horizonte\";\n_ = where_i_live;\n```\n:::\n\n\n```\nt.zig:7:5: error: local variable is never mutated\nt.zig:7:5: note: consider using 'const'\n```\n\n## Primitive Data Types {#sec-primitive-data-types}\n\nZig has many different primitive data types available for you to use.\nYou can see the full list of available data types at the official\n[Language Reference page](https://ziglang.org/documentation/master/#Primitive-Types)[^lang-data-types].\n\n[^lang-data-types]: <https://ziglang.org/documentation/master/#Primitive-Types>.\n\nBut here is a quick list:\n\n- Unsigned integers: `u8`, 8-bit integer; `u16`, 16-bit integer; `u32`, 32-bit integer; `u64`, 64-bit integer; `u128`, 128-bit integer.\n- Signed integers: `i8`, 8-bit integer; `i16`, 16-bit integer; `i32`, 32-bit integer; `i64`, 64-bit integer; `i128`, 128-bit integer.\n- Float number: `f16`, 16-bit floating point; `f32`, 32-bit floating point; `f64`, 64-bit floating point; `f128`, 128-bit floating point;\n- Boolean: `bool`, represents true or false values.\n- C ABI compatible types: `c_long`, `c_char`, `c_short`, `c_ushort`, `c_int`, `c_uint`, and many others.\n- Pointer sized integers: `isize` and `usize`.\n\n\n\n\n\n\n\n## Arrays {#sec-arrays}\n\nYou create arrays in Zig by using a syntax that resembles the C syntax.\nFirst, you specify the size of the array (i.e., the number of elements that will be stored in the array)\nyou want to create inside a pair of brackets.\n\nThen, you specify the data type of the elements that will be stored inside this array.\nAll elements present in an array in Zig must have the same data type. For example, you cannot mix elements\nof type `f32` with elements of type `i32` in the same array.\n\nAfter that, you simply list the values that you want to store in this array inside\na pair of curly braces.\nIn the example below, I am creating two constant objects that contain different arrays.\nThe first object contains an array of 4 integer values, while the second object,\nan array of 3 floating point values.\n\nNow, you should notice that in the object `ls`, I am\nnot explicitly specifying the size of the array inside of the brackets. Instead\nof using a literal value (like the value 4 that I used in the `ns` object), I am\nusing the special character underscore (`_`). This syntax tells the `zig` compiler\nto fill this field with the number of elements listed inside of the curly braces.\nSo, this syntax `[_]` is for lazy (or smart) programmers who leave the job of\ncounting how many elements there are in the curly braces for the compiler.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst ls = [_]f64{432.1, 87.2, 900.05};\n_ = ns; _ = ls;\n```\n:::\n\n\nIt's worth noting that these are static arrays, meaning that\nthey cannot grow in size.\nOnce you declare your array, you cannot change the size of it.\nThis is very common in low level languages.\nBecause low level languages normally wants to give you (the programmer) full control over memory,\nand the way in which arrays are expanded is tightly related to\nmemory management.\n\n\n### Selecting elements of the array {#sec-select-array-elem}\n\nOne very common activity is to select specific portions of an array\nyou have in your source code.\nIn Zig, you can select a specific element from your\narray, by simply providing the index of this particular\nelement inside brackets after the object name.\nIn the example below, I am selecting the third element from the\n`ns` array. Notice that Zig is a \"zero-index\" based language,\nlike C, C++, Rust, Python, and many other languages.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\ntry stdout.print(\"{d}\\n\", .{ ns[2] });\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n12\n```\n\n\n:::\n:::\n\n\nIn contrast, you can also select specific slices (or sections) of your array, by using a\nrange selector. Some programmers also call these selectors of \"slice selectors\",\nand they also exist in Rust, and have the exact same syntax as in Zig.\nAnyway, a range selector is a special expression in Zig that defines\na range of indexes, and it has the syntax `start..end`.\n\nIn the example below, at the second line of code,\nthe `sl` object stores a slice (or a portion) of the\n`ns` array. More precisely, the elements at index 1 and 2\nin the `ns` array.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\n_ = sl;\n```\n:::\n\n\nWhen you use the `start..end` syntax,\nthe \"end tail\" of the range selector is non-inclusive,\nmeaning that, the index at the end is not included in the range that is\nselected from the array.\nTherefore, the syntax `start..end` actually means `start..end - 1` in practice.\n\nYou can for example, create a slice that goes from the first to the\nlast elements of the array, by using `ar[0..ar.len]` syntax\nIn other words, it's a slice that\naccesses all elements in the array.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [4]u8{48, 24, 12, 6};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\nYou can also use the syntax `start..` in your range selector.\nWhich tells the `zig` compiler to select the portion of the array\nthat begins at the `start` index until the last element of the array.\nIn the example below, we are selecting the range from index 1\nuntil the end of the array.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..];\n_ = sl;\n```\n:::\n\n\n\n### More on slices\n\nAs we discussed before, in Zig, you can select specific portions of an existing\narray. This is called *slicing* in Zig [@zigguide], because when you select a portion\nof an array, you are creating a slice object from that array.\n\nA slice object is essentially a pointer object accompanied by a length number.\nThe pointer object points to the first element in the slice, and the\nlength number tells the `zig` compiler how many elements there are in this slice.\n\n> Slices can be thought of as a pair of `[*]T` (the pointer to the data) and a `usize` (the element count) [@zigguide].\n\nThrough the pointer contained inside the slice you can access the elements (or values)\nthat are inside this range (or portion) that you selected from the original array.\nBut the length number (which you can access through the `len` property of your slice object)\nis the really big improvement (over C arrays for example) that Zig brings to the table here.\n\nBecause with this length number\nthe `zig` compiler can easily check if you are trying to access an index that is out of the bounds of this particular slice,\nor, if you are causing any buffer overflow problems. In the example below,\nwe access the `len` property of the slice `sl`, which tells us that this slice\nhas 2 elements in it.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [4]u8{48, 24, 12, 6};\nconst sl = ns[1..3];\ntry stdout.print(\"{d}\\n\", .{sl.len});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n2\n```\n\n\n:::\n:::\n\n\n\n### Array operators\n\nThere are two array operators available in Zig that are very useful.\nThe array concatenation operator (`++`), and the array multiplication operator (`**`). As the name suggests,\nthese are array operators.\n\nOne important detail about these two operators is that they work\nonly when both operands have a size (or \"length\") that is compile-time known.\nWe are going to talk more about\nthe differences between \"compile-time known\" and \"runtime known\" in @sec-compile-time.\nBut for now, keep this information in mind, that you cannot use these operators in every situation.\n\nIn summary, the `++` operator creates a new array that is the concatenation,\nof both arrays provided as operands. So, the expression `a ++ b` produces\na new array which contains all the elements from arrays `a` and `b`.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst b = [_]u8{4,5};\nconst c = a ++ b;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 4, 5 }\n```\n\n\n:::\n:::\n\n\nThis `++` operator is particularly useful to concatenate strings together.\nStrings in Zig are described in depth in @sec-zig-strings. In summary, a string object in Zig\nis essentially an arrays of bytes. So, you can use this array concatenation operator\nto effectively concatenate strings together.\n\nIn contrast, the `**` operator is used to replicate an array multiple\ntimes. In other words, the expression `a ** 3` creates a new array\nwhich contains the elements of the array `a` repeated 3 times.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a = [_]u8{1,2,3};\nconst c = a ** 2;\ntry stdout.print(\"{any}\\n\", .{c});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 1, 2, 3, 1, 2, 3 }\n```\n\n\n:::\n:::\n\n\n\n### Runtime versus compile-time known length in slices\n\nWe are going to talk a lot about the differences between compile-time known\nand runtime known across this book, especially in @sec-compile-time.\nBut the basic idea is that a thing is compile-time known, when we know\neverything (the value, the attributes and the characteristics) about this thing at compile-time.\nIn contrast, a runtime known thing is when the exact value of a thing is calculated only at runtime.\nTherefore, we don't know the value of this thing at compile-time, only at runtime.\n\nWe have learned in @sec-select-array-elem that slices are created by using a *range selector*,\nwhich represents a range of indexes. When this \"range of indexes\" (i.e., both the start and the end of this range)\nis known at compile-time, the slice object that gets created is actually, under the hood, just\na single-item pointer to an array.\n\nYou don't need to precisely understand what that means now. We are going to talk a lot about pointers\nin @sec-pointer. For now, just understand that, when the range of indexes is known at compile-time,\nthe slice that gets created is just a pointer to an array, accompanied by a length value that\ntells the size of the slice.\n\nIf you have a slice object like this, i.e., a slice that has a compile-time known range,\nyou can use common pointer operations over this slice object. For example, you can\ndereference the pointer of this slice, by using the `.*` method, like you would\ndo on a normal pointer object.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst arr1 = [10]u64 {\n    1, 2, 3, 4, 5,\n    6, 7, 8, 9, 10\n};\n// This slice has a compile-time known range.\n// Because we know both the start and end of the range.\nconst slice = arr1[1..4];\n_ = slice;\n```\n:::\n\n\n\nOn the other hand, if the range of indexes is not known at compile time, then, the slice object\nthat gets created is not a pointer anymore, and, thus, it does not support pointer operations.\nFor example, maybe the start index is known at compile time, but the end index is not. In such\ncase, the range of the slice becomes runtime known only.\n\nIn the example below, we are reading a file, and then, we try to create a slice object\nthat covers the entire buffer that contains the contents of this file. This is obviously\nan example of a runtime known range, because the end index of the range\nis not known at compile time.\n\nIn other words, the end index of the range is the size of\nthe array `file_contents`. However, the size of `file_contents` is not known at compile time.\nBecause we don't know how many bytes are stored inside this `shop-list.txt` file.\nAnd because this is a file, someone might edit this file tomorrow and add more lines\nor remove lines from it. Therefore, the size of this file might vary drastically from one execution to another.\n\nNow, if the file size can vary from one run to another, then, we can conclude that the value of the expression\n`file_contents.len` exposed in the example below can also vary from one run to another. As consequence,\nthe value of the expression `file_contents.len` is runtime-known only, and, as a consequence of that,\nthe range `0..file_contents.len` is also runtime-known only.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\n\nfn read_file(allocator: std.mem.Allocator, path: []const u8) ![]u8 {\n    const file = try std.fs.cwd().openFile(path, .{});\n    defer file.close();\n    return try file.reader().readAllAlloc(\n        allocator, std.math.maxInt(usize)\n    );\n}\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const path = \"../ZigExamples/file-io/shop-list.txt\";\n    const file_contents = try read_file(allocator, path);\n    const slice = file_contents[0..file_contents.len];\n    _ = slice;\n}\n```\n:::\n\n\n\n## Blocks and scopes {#sec-blocks}\n\nBlocks are created in Zig by a pair of curly braces. A block is just a group of\nexpressions (or statements) contained inside of a pair of curly braces. All of these expressions that\nare contained inside of this pair of curly braces belongs to the same scope.\n\nIn other words, a block just delimits a scope in your code.\nThe objects that you define inside the same block belongs to the same\nscope, and, therefore, are accessible from within this scope.\nAt the same time, these objects are not accessible outside of this scope.\nSo, you could also say that blocks are used to limit the scope of the objects that you create in\nyour source code. In less technical terms, blocks are used to specify where in your source code\nyou can access whatever object you have in your source code.\n\nSo, a block is just a group of expressions contained inside a pair of curly braces.\nAnd every block have its own scope separated from the others.\nThe body of a function is a classic example of a block. If statements, for and while loops\n(and any other structure in the language that uses the pair of curly braces)\nare also examples of blocks.\n\nThis means that, every if statement, or for loop,\netc., that you create in your source code has its own separate scope.\nThat is why you can't access the objects that you defined inside\nof your for loop (or if statement) in an outer scope, i.e., a scope outside of the for loop.\nBecause you are trying to access an object that belongs to a scope that is different\nthan your current scope.\n\n\nYou can create blocks within blocks, with multiple levels of nesting.\nYou can also (if you want to) give a label to a particular block, with the colon character (`:`).\nJust write `label:` before you open the pair of curly braces that delimits your block. When you label a block\nin Zig, you can use the `break` keyword to return a value from this block, like as if it\nwas a function's body. You just write the `break` keyword, followed by the block label in the format `:label`,\nand the expression that defines the value that you want to return.\n\nLike in the example below, where we are returning the value from the `y` object\nfrom the block `add_one`, and saving the result inside the `x` object.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar y: i32 = 123;\nconst x = add_one: {\n    y += 1;\n    break :add_one y;\n};\nif (x == 124 and y == 124) {\n    try stdout.print(\"Hey!\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHey!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n## How strings work in Zig? {#sec-zig-strings}\n\nThe first project that we are going to build and discuss in this book is a base64 encoder/decoder (@sec-base64).\nBut in order for us to build such a thing, we need to get a better understanding on how strings work in Zig.\nSo let's discuss this specific aspect of Zig.\n\nStrings in Zig work very similarly to strings in C, but they come with some extra caveats which adds more safety\nand efficiency to them. You could also say that Zig simply uses a more modern and safe approach to manage\nand use strings.\n\nA string in Zig is essentially an array of arbitrary bytes, or, more specifically, an array of `u8` values.\nThis very similar to a string in C, which is also interpreted as an array of arbitrary bytes, or, in the case\nof C, an array of `char` (which usually represents an unsigned 8-bit integer value in most systems) values.\n\nNow, because a string in Zig is an array, you automatically\nget the length of the string (i.e. the length of the array) embedded in the value itself. This makes\nall the difference! Because now, the Zig compiler can use the length value that is embedded in the string to\ncheck for \"buffer overflow\" or \"wrong memory access\" problems in your code.\n\n\nTo achieve this same kind of safety in C, you have to do a lot of work that kind of seems pointless.\nSo getting this kind of safety is not automatic and much harder to do in C. For example, if you want\nto track the length of your string throughout your program in C, then, you first need to loop through\nthe array of bytes that represents this string, and find the null element (`'\\0'`) position to discover\nwhere exactly the array ends, or, in other words, to find how much elements the array of bytes contain.\n\nTo do that, you would need to do something like this in C. In this example, the C string stored in\nthe object `array` is 25 bytes long:\n\n\n::: {.cell}\n\n```{.c .cell-code}\n#include <stdio.h>\nint main() {\n    char* array = \"An example of string in C\";\n    int index = 0;\n    while (1) {\n        if (array[index] == '\\0') {\n            break;\n        }\n        index++;\n    }\n    printf(\"Number of elements in the array: %d\\n\", index);\n}\n```\n:::\n\n\n```\nNumber of elements in the array: 25\n```\n\n\nYou don't have this kind of work in Zig. Because the length of the string is always\npresent and accessible in the string value itself. You can easily access the length of the string\nthrough the `len` attribute. As an example, the `string_object` object below is 43 bytes long:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example of string literal in Zig\";\n    try stdout.print(\"{d}\\n\", .{string_object.len});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n43\n```\n\n\n:::\n:::\n\n\n\nAnother point is that Zig always assumes that the sequence of bytes in your string is UTF-8 encoded. This might not be true for every\nsequence of bytes you're working with, but is not really Zig's job to fix the encoding of your strings\n(you can use [`iconv`](https://www.gnu.org/software/libiconv/)[^libiconv] for that).\nToday, most of the text in our modern world, especially on the web, should be UTF-8 encoded.\nSo if your string literal is not UTF-8 encoded, then, you will likely have problems in Zig.\n\n[^libiconv]: <https://www.gnu.org/software/libiconv/>\n\nLet's take for example the word \"Hello\". In UTF-8, this sequence of characters (H, e, l, l, o)\nis represented by the sequence of decimal numbers 72, 101, 108, 108, 111. In hexadecimal, this\nsequence is `0x48`, `0x65`, `0x6C`, `0x6C`, `0x6F`. So if I take this sequence of hexadecimal values,\nand ask Zig to print this sequence of bytes as a sequence of characters (i.e., a string), then,\nthe text \"Hello\" will be printed into the terminal:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const bytes = [_]u8{0x48, 0x65, 0x6C, 0x6C, 0x6F};\n    try stdout.print(\"{s}\\n\", .{bytes});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello\n```\n\n\n:::\n:::\n\n\n\n\n### Using a slice versus a sentinel-terminated array\n\nIn memory, all string values in Zig are always stored in the same way.\nThey are simply stored as sequences/arrays of arbitrary bytes. But you can use and access\nthis sequence of bytes in two different ways. You can access this sequence of bytes as:\n\n- a sentinel-terminated array of `u8` values.\n- or as a slice of `u8` values.\n\n\n#### Sentinel-terminated arrays\n\nSentinel-terminated arrays in Zig are described in the Language Reference of Zig[^sentinel].\nIn summary a sentinel-terminated array is just a normal array, but, the difference is that they\ncontain a \"sentinel value\" at the last index/element of the array. With a sentinel-terminated array\nyou embed both the length of the array, and also, the sentinel value in the type itself of your object.\n\n[^sentinel]: <https://ziglang.org/documentation/master/#Sentinel-Terminated-Arrays>.\n\nFor example, if you write a string literal value in your code, and ask Zig to print the data type of this value,\nyou usually get a data type in the format `*const [n:0]u8`. The `n` in the data type indicates the size of\nthe string (that is the length of the array). The zero after the `n:` part of the data type is the sentinel\nvalue itself.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string literal value:\n_ = \"A literal value\";\ntry stdout.print(\"{any}\\n\", .{@TypeOf(\"A literal value\")});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n*const [15:0]u8\n```\n\n\n:::\n:::\n\n\n\nSo, with this data type `*const [n:0]u8` you are essentially saying that you have an array of `u8` values\nof length `n`, where, the element at the index corresponding to the length `n` in the array is the\nnumber zero. If you really think about this description, you will notice that this is just a fancy way to\ndescribe a string in C, which is a null-terminated array of bytes. The `NULL` value in C is the number\nzero. So, an array that ends in a null/zero value in C is essentially a sentinel-terminated array in Zig,\nwhere the sentinel value of the array is the number zero.\n\nTherefore, a string literal value in Zig is just a pointer to a null-terminated array of bytes (i.e., similar to a C string).\nBut in Zig, a string literal value also embeds the length of the string, and also, the fact that they are \"NULL terminated\",\ninto the data type of the value itself.\n\n\n\n#### Slice\n\nYou can also access and use the arbitrary sequence of bytes that represent your string as a slice of `u8` values.\nThe majority of functions from the Zig standard library usually receive strings as inputs as slices of\n`u8` values (slices were presented in @sec-arrays).\n\nThus, you will see a lot of string values with a data type of `[]u8` or `[]const u8`, depending if the object\nwhere this string is stored is marked as constant with `const`, or as variable with `var`. Now, because\nthe string in this case is being interpreted as a slice, this slice is not necessarilly null-terminated,\nbecause now, the sentinel value is not mandatory. You can include the null/zero value in the slice if you\nwant to, but there is no need to do it.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// This is a string value being\n// interpreted as a slice.\nconst str: []const u8 = \"A string value\";\ntry stdout.print(\"{any}\\n\", .{@TypeOf(str)});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n[]const u8\n```\n\n\n:::\n:::\n\n\n\n\n### Iterating through the string\n\nIf you want to see the actual bytes that represents a string in Zig, you can use\na `for` loop to iterate through each byte in the string, and ask Zig to print each byte as an hexadecimal\nvalue to the terminal. You do that by using a `print()` statement with the `X` formatting specifier,\nlike you would normally do with the [`printf()` function](https://cplusplus.com/reference/cstdio/printf/)[^printfs] in C.\n\n[^printfs]: <https://cplusplus.com/reference/cstdio/printf/>\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"This is an example\";\n    try stdout.print(\"Bytes that represents the string object: \", .{});\n    for (string_object) |byte| {\n        try stdout.print(\"{X} \", .{byte});\n    }\n    try stdout.print(\"\\n\", .{});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: 54 68 69 \n   73 20 69 73 20 61 6E 20 65 78 61 6D 70 6C 65 \n```\n\n\n:::\n:::\n\n\n\n\n### A better look at the object type\n\nNow, we can inspect better the type of objects that Zig create. To check the type of any object in Zig, you can use the\n`@TypeOf()` function. If we look at the type of the `simple_array` object below, you will find that this object\nis an array of 4 elements. Each element is a signed integer of 32 bits which corresponds to the data type `i32` in Zig.\nThat is what an object of type `[4]i32` is.\n\nBut if we look closely at the type of the string literal value exposed below, you will find that this object is a\nconstant pointer (hence the `*const` annotation) to an array of 16 elements (or 16 bytes). Each element is a\nsingle byte (more precisely, an unsigned 8 bit integer - `u8`), that is why we have the `[16:0]u8` portion of the type below,\nand also, you can see that this is a null-terminated array, because of the zero value after the `:` character in the data type.\nIn other words, the string literal value exposed below is 16 bytes long.\n\nNow, if we create an pointer to the `simple_array` object, then, we get a constant pointer to an array of 4 elements (`*const [4]i32`),\nwhich is very similar to the type of the string literal value. This demonstrates that a string literal value\nin Zig is already a pointer to a null-terminated array of bytes.\n\nFurthermore, if we take a look at the type of the `string_obj` object, you will see that it's a\nslice object (hence the `[]` portion of the type) to a sequence of constant `u8` values (hence\nthe `const u8` portion of the type).\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const simple_array = [_]i32{1, 2, 3, 4};\n    const string_obj: []const u8 = \"A string object\";\n    std.debug.print(\n        \"Type 1: {}\\n\", .{@TypeOf(simple_array)}\n    );\n    std.debug.print(\n        \"Type 2: {}\\n\", .{@TypeOf(\"A string literal\")}\n    );\n    std.debug.print(\n        \"Type 3: {}\\n\", .{@TypeOf(&simple_array)}\n    );\n    std.debug.print(\n        \"Type 4: {}\\n\", .{@TypeOf(string_obj)}\n    );\n}\n```\n:::\n\n\n```\nType 1: [4]i32\nType 2: *const [16:0]u8\nType 3: *const [4]i32\nType 4: []const u8\n```\n\n\n\n### Byte vs unicode points\n\nIt's important to point out that each byte in the array is not necessarily a single character.\nThis fact arises from the difference between a single byte and a single unicode point.\n\nThe encoding UTF-8 works by assigning a number (which is called a unicode point) to each character in\nthe string. For example, the character \"H\" is stored in UTF-8 as the decimal number 72. This means that\nthe number 72 is the unicode point for the character \"H\". Each possible character that can appear in a\nUTF-8 encoded string have its own unicode point.\n\nFor example, the Latin Capital Letter A With Stroke (Ⱥ) is represented by the number (or the unicode point)\n570. However, this decimal number (570) is higher than the maximum number stored inside a single byte, which\nis 255. In other words, the maximum decimal number that can be represented with a single byte is 255. That is why,\nthe unicode point 570 is actually stored inside the computer’s memory as the bytes `C8 BA`.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const string_object = \"Ⱥ\";\n    _ = try stdout.write(\n        \"Bytes that represents the string object: \"\n    );\n    for (string_object) |char| {\n        try stdout.print(\"{X} \", .{char});\n    }\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nBytes that represents the string object: C8 BA \n```\n\n\n:::\n:::\n\n\n\nThis means that to store the character Ⱥ in an UTF-8 encoded string, we need to use two bytes together\nto represent the number 570. That is why the relationship between bytes and unicode points is not always\n1 to 1. Each unicode point is a single character in the string, but not always a single byte corresponds\nto a single unicode point.\n\nAll of this means that if you loop through the elements of a string in Zig, you will be looping through the\nbytes that represents that string, and not through the characters of that string. In the Ⱥ example above,\nthe for loop needed two iterations (instead of a single iteration) to print the two bytes that represents this Ⱥ letter.\n\nNow, all english letters (or ASCII letters if you prefer) can be represented by a single byte in UTF-8. As a\nconsequence, if your UTF-8 string contains only english letters (or ASCII letters), then, you are lucky. Because\nthe number of bytes will be equal to the number of characters in that string. In other words, in this specific\nsituation, the relationship between bytes and unicode points is 1 to 1.\n\nBut on the other side, if your string contains other types of letters… for example, you might be working with\ntext data that contains, chinese, japanese or latin letters, then, the number of bytes necessary to represent\nyour UTF-8 string will likely be much higher than the number of characters in that string.\n\nIf you need to iterate through the characters of a string, instead of its bytes, then, you can use the\n`std.unicode.Utf8View` struct to create an iterator that iterates through the unicode points of your string.\n\nIn the example below, we loop through the japanese characters “アメリカ”. Each of the four characters in\nthis string is represented by three bytes. But the for loop iterates four times, one iteration for each\ncharacter/unicode point in this string:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    var utf8 = try std.unicode.Utf8View.init(\"アメリカ\");\n    var iterator = utf8.iterator();\n    while (iterator.nextCodepointSlice()) |codepoint| {\n        try stdout.print(\n            \"got codepoint {}\\n\",\n            .{std.fmt.fmtSliceHexUpper(codepoint)},\n        );\n    }\n}\n\n```\n:::\n\n\n```\ngot codepoint E382A2\ngot codepoint E383A1\ngot codepoint E383AA\ngot codepoint E382AB\n```\n\n\n### Some useful functions for strings {#sec-strings-useful-funs}\n\nIn this section, I just want to quickly describe some functions from the Zig Standard Library\nthat are very useful to use when working with strings. Most notably:\n\n- `std.mem.eql()`: to compare if two strings are equal.\n- `std.mem.splitScalar()`: to split a string into an array of substrings given a delimiter value.\n- `std.mem.splitSequence()`: to split a string into an array of substrings given a substring delimiter.\n- `std.mem.startsWith()`: to check if string starts with substring.\n- `std.mem.endsWith()`: to check if string ends with substring.\n- `std.mem.trim()`: to remove specific values from both start and end of the string.\n- `std.mem.concat()`: to concatenate strings together.\n- `std.mem.count()`: to count the occurrences of substring in the string.\n- `std.mem.replace()`: to replace the occurrences of substring in the string.\n\nNotice that all of these functions come from the `mem` module of\nthe Zig Standard Library. This module contains multiple functions and methods\nthat are useful to work with memory and sequences of bytes in general.\n\nThe `eql()` function is used to check if two arrays of data are equal or not.\nSince strings are just arbitrary arrays of bytes, we can use this function to compare two strings together.\nThis function returns a boolean value indicating if the two strings are equal\nor not. The first argument of this function is the data type of the elements of the arrays\nthat are being compared.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.eql(u8, name, \"Pedro\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\nThe `splitScalar()` and `splitSequence()` functions are useful to split\na string into multiple fragments, like the `split()` method from Python strings. The difference between these two\nmethods is that the `splitScalar()` uses a single character as the separator to\nsplit the string, while `splitSequence()` uses a sequence of characters (a.k.a. a substring)\nas the separator. There is a practical example of these functions later in the book.\n\nThe `startsWith()` and `endsWith()` functions are pretty straightforward. They\nreturn a boolean value indicating if the string (or, more precisely, if the array of data)\nbegins (`startsWith`) or ends (`endsWith`) with the sequence provided.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name: []const u8 = \"Pedro\";\ntry stdout.print(\n    \"{any}\\n\", .{std.mem.startsWith(u8, name, \"Pe\")}\n);\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ntrue\n```\n\n\n:::\n:::\n\n\nThe `concat()` function, as the name suggests, concatenate two or more strings together.\nBecause the process of concatenating the strings involves allocating enough space to\naccomodate all the strings together, this `concat()` function receives an allocator\nobject as input.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nconst str2 = \" you!\";\nconst str3 = try std.mem.concat(\n    allocator, u8, &[_][]const u8{ str1, str2 }\n);\ntry stdout.print(\"{s}\\n\", .{str3});\n```\n:::\n\n\n\nAs you can imagine, the `replace()` function is used to replace substrings in a string by another substring.\nThis function works very similarly to the `replace()` method from Python strings. Therefore, you\nprovide a substring to search, and every time that the `replace()` function finds\nthis substring within the input string, it replaces this substring with the \"replacement substring\"\nthat you provided as input.\n\nIn the example below, we are taking the input string \"Hello\", and replacing all occurrences\nof the substring \"el\" inside this input string with \"34\", and saving the results inside the\n`buffer` object. As result, the `replace()` function returns an `usize` value that\nindicates how many replacements were performed.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst str1 = \"Hello\";\nvar buffer: [5]u8 = undefined;\nconst nrep = std.mem.replace(\n    u8, str1, \"el\", \"34\", buffer[0..]\n);\ntry stdout.print(\"New string: {s}\\n\", .{buffer});\ntry stdout.print(\"N of replacements: {d}\\n\", .{nrep});\n```\n:::\n\n\n```\nNew string: H34lo\nN of replacements: 1\n```\n\n\n\n\n\n\n## Safety in Zig\n\nA general trend in modern low-level programming languages is safety. As our modern world\nbecomes more interconnected with technology and computers,\nthe data produced by all of this technology becomes one of the most important\n(and also, one of the most dangerous) assets that we have.\n\nThis is probably the main reason why modern low-level programming languages\nhave been giving great attention to safety, especially memory safety, because\nmemory corruption is still the main target for hackers to exploit.\nThe reality is that we don't have an easy solution for this problem.\nFor now, we only have techniques and strategies that mitigates these\nproblems.\n\nAs Richard Feldman explains on his [most recent GOTO conference talk](https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences)[^gotop]\n, we haven't figured it out yet a way to achieve **true safety in technology**.\nIn other words, we haven't found a way to build software that won't be exploited\nwith 100% certainty. We can greatly reduce the risks of our software being\nexploited, by ensuring memory safety for example. But this is not enough\nto achieve \"true safety\" territory.\n\nBecause even if you write your program in a \"safe language\", hackers can still\nexploit failures in the operating system where your program is running (e.g. maybe the\nsystem where your code is running has a \"backdoor exploit\" that can still\naffect your code in unexpected ways), or also, they can exploit the features\nfrom the architecture of your computer. A recently found exploit\nthat involves memory invalidation through a feature of \"memory tags\"\npresent in ARM chips is an example of that [@exploit1].\n\n[^gotop]: <https://www.youtube.com/watch?v=jIZpKpLCOiU&ab_channel=GOTOConferences>\n\nThe question is: what have Zig and other languages been doing to mitigate this problem?\nIf we take Rust as an example, Rust is, for the most part[^rust-safe], a memory safe\nlanguage by enforcing specific rules to the developer. In other words, the key feature\nof Rust, the *borrow checker*, forces you to follow a specific logic when you are writing\nyour Rust code, and the Rust compiler will always complain everytime you try to go out of this\npattern.\n\n[^rust-safe]: Actually, a lot of existing Rust code is still memory unsafe, because they communicate with external libraries through FFI (*foreign function interface*), which disables the borrow-checker features through the `unsafe` keyword.\n\n\nIn contrast, the Zig language is not a memory safe language by default.\nThere are some memory safety features that you get for free in Zig,\nespecially in arrays and pointer objects. But there are other tools\noffered by the language, that are not used by default.\nIn other words, the `zig` compiler does not obligate you to use such tools.\n\nThe tools listed below are related to memory safety. That is, they help you to achieve\nmemory safety in your Zig code:\n\n- `defer` allows you to keep free operations physically close to allocations. This helps you to avoid memory leaks, \"use after free\", and also \"double-free\" problems. Furthermore, it also keeps free operations logically tied to the end of the current scope, which greatly reduces the mental overhead about object lifetime.\n- `errdefer` helps you to guarantee that your program frees the allocated memory, even if a runtime error occurs.\n- pointers and objects are non-nullable by default. This helps you to avoid memory problems that might arise from de-referencing null pointers.\n- Zig offers some native types of allocators (called \"testing allocators\") that can detect memory leaks and double-frees. These types of allocators are widely used on unit tests, so they transform your unit tests into a weapon that you can use to detect memory problems in your code.\n- arrays and slices in Zig have their lengths embedded in the object itself, which makes the `zig` compiler very effective on detecting \"index out-of-range\" type of errors, and avoiding buffer overflows.\n\n\nDespite these features that Zig offers that are related to memory safety issues, the language\nalso has some rules that help you to achieve another type of safety, which is more related to\nprogram logic safety. These rules are:\n\n- pointers and objects are non-nullable by default. Which eliminates an edge case that might break the logic of your program.\n- switch statements must exaust all possible options.\n- the `zig` compiler forces you to handle every possible error in your program.\n\n\n## Other parts of Zig\n\nWe already learned a lot about Zig's syntax, and also, some pretty technical\ndetails about it. Just as a quick recap:\n\n- We talked about how functions are written in Zig in @sec-root-file and @sec-main-file.\n- How to create new objects/identifiers in @sec-root-file and especially in @sec-assignments.\n- How strings work in Zig in @sec-zig-strings.\n- How to use arrays and slices in @sec-arrays.\n- How to import functionality from other Zig modules in @sec-root-file.\n\n\nBut, for now, this amount of knowledge is enough for us to continue with this book.\nLater, over the next chapters we will still talk more about other parts of\nZig's syntax that are also equally important. Such as:\n\n\n- How Object-Oriented programming can be done in Zig through *struct declarations* in @sec-structs-and-oop.\n- Basic control flow syntax in @sec-zig-control-flow.\n- Enums in @sec-enum;\n- Pointers and Optionals in @sec-pointer;\n- Error handling with `try` and `catch` in @sec-error-handling;\n- Unit tests in @sec-unittests;\n- Vectors in @sec-vectors-simd;\n- Build System in @sec-build-system;\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
diff --git a/_freeze/Chapters/02-debugging/execute-results/epub.json b/_freeze/Chapters/02-debugging/execute-results/epub.json
deleted file mode 100644
index 933510c4..00000000
--- a/_freeze/Chapters/02-debugging/execute-results/epub.json
+++ /dev/null
@@ -1,21 +0,0 @@
-{
-  "hash": "f6eea7230762e3b8cde487458c00b745",
-  "result": {
-    "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Debugging Zig applications\n\nBeing able to debug your applications is essential for any programmer who wants to\ndo serious programming in any language. That is why, in this chapter, we are going to talk about the\navailable strategies and tools to debug applications written in Zig.\n\n\n## Print debugging\n\nWe begin with the classic and battle-tested *print debugging* strategy.\nThe key advantage that debugging offers you is *visibility*.\nWith *print statements* you can easily see what results and objects\nare being produced by your application.\n\nThis is the essence of *print debugging* - using\nprint expressions to see the values that are being generated by your program,\nand, as a result, get a much better understanding of how your program\nis behaving.\n\nMany programmers often resort to the print functions in Zig, such as the `stdout.print()`,\nor, the `std.debug.print()`, to get a better understanding of their programs.\nThis is a known and old strategy that is very simple and effective, and it's better known within\nthe programming community as *print debugging*.\nIn Zig, you can print information to the `stdout` or `stderr` streams of your system.\n\nLet's begin with `stdout`. First, you\nneed to get access to the `stdout`, by calling the `getStdOut()` method, from\nthe Zig Standard Library. This method returns a *file descriptor* object,\nand, through this object you can read/write to the `stdout`.\nI recommend you to check out all methods available in this object, by [checking the page in\nthe Zig Standard Library Official Reference for the type `File`](https://ziglang.org/documentation/master/std/#std.fs.File)[^zig-fiile-reference].\n\n[^zig-fiile-reference]: <https://ziglang.org/documentation/master/std/#std.fs.File>.\n\nFor our purpose here, which is to write something to the `stdout`, especially to debug our\nprogram, I recommend you to use the `writer()` method, which gives you a *writer* object.\nThis *writer* object offers some helper methods to write stuff into the file descriptor object\nthat represents the `stdout` stream. In special, the `print()` method.\n\n\nThe `print()` method from this *writer* object is a \"print formatter\" type of a function.\nIn other words, this method works exactly like the `printf()` function from C,\nor, like `println!()` from Rust.\nIn the first argument of the function, you specify a template string, and,\nin the second argument, you provide a list of values (or objects) that you want to insert\ninto your template message.\n\nIdeally, the template string in the first argument should contain some format specifier.\nEach format specifier is matched to a value (or object) that you have listed in the second argument.\nSo, if you provided 5 different objects in the second argument, then, the template string\nshould contain 5 format specifiers, one for each object provided.\n\nEach format specifier is represented by a single letter, and\nyou provide this format specifier inside a pair of curly braces. So, if you want to format\nyour object using the string specifier (`s`), then, you can insert the text `{s}` in your template string.\nHere is a quick list of the most used format specifiers:\n\n- `d`: for printing integers and floating-point numbers.\n- `c`: for printing characters.\n- `s`: for printing strings.\n- `p`: for printing memory addresses.\n- `x`: for printing hexadecimal values.\n- `any`: use any compatible format specifier (i.e., it automatically selects a format specifier for you).\n\nThe code example below gives you an example of use of this `print()` method\nwith the `d` format specifier.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    try stdout.print(\"Result: {d}\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\n\nIt's important to emphasize that, the `stdout.print()` method, as you would expect,\nprints your template string into the `stdout` stream of your system.\nHowever, you can also print your template string into the `stderr` stream\nif your prefer. All you need to do, is to replace the `stdout.print()`\ncall with the function `std.debug.print()`. Like this:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    std.debug.print(\"Result: {d}\\n\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\n\n\nYou could also achieve the exact same result by getting a file descriptor object to `stderr`,\nthen, creating a *writer* object to `stderr`, then, using the `print()` method of this\n*writer* object, like in the example below:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stderr = std.io.getStdErr().writer();\n// some more lines ...\ntry stderr.print(\"Result: {d}\", .{result});\n```\n:::\n\n\n\n\n\n## Debugging through debuggers\n\nAlthough *print debugging* is a valid and very useful strategy,\nmost programmers prefer to use a debugger to debug their programs.\nSince Zig is a low-level language, you can use either GDB (GNU Debugger),\nor LLDB (LLVM Project Debugger) as your debugger.\n\nBoth debuggers can work with Zig code, and it's a matter of taste here.\nYou choose the debugger of your preference, and you work with it.\nIn this book, I will use LLDB as my debugger in the examples.\n\n\n### Compile your source code in debug mode {#sec-compile-debug-mode}\n\nIn order to debug your program through a debugger, you must compile\nyour source code in `Debug` mode. Because when you compile your\nsource code in other modes (such as `Release`), the compiler usually\nstrips out some essential information that is used by the debugger\nto read and track your program, like PDB (*Program Database*) files.\n\nBy compiling your source code in `Debug` mode, you ensure that the debugger\nwill find the necessary information in your program to debug it.\nBy default, the compiler uses the `Debug` mode when compiling your code.\nHaving this in mind, when you compile your program with the `build-exe`\ncommand (which was described in @sec-compile-code), if you don't specify\nan explicit mode through the `-O` command-line [^oargument]\nargument, then, the compiler will compile your code in `Debug` mode.\n\n[^oargument]: See <https://ziglang.org/documentation/master/#Debug>.\n\n\n### Let's debug a program\n\nAs an example, let's use LLDB to navigate and investigate the following\npiece of Zig code:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\nfn add_and_increment(a: u8, b: u8) u8 {\n    const sum = a + b;\n    const incremented = sum + 1;\n    return incremented;\n}\n\npub fn main() !void {\n    var n = add_and_increment(2, 3);\n    n = add_and_increment(n, n);\n    try stdout.print(\"Result: {d}!\\n\", .{n});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 13!\n```\n\n\n:::\n:::\n\n\n\nThere is nothing wrong with this program. But it's\na good start for us. First, we need to compile\nthis program with the `zig build-exe` command.\nFor this example, suppose that I have compiled the above\nZig code into a binary executable called `add_program`.\n\n```bash\nzig build-exe add_program.zig\n```\n\nNow, we can start LLDB with `add_program`, like this:\n\n```bash\nlldb add_program\n```\n\nFrom now on, LLDB is started, and you can know that I'm\nexecuting LLDB commands by looking at the prefix `(lldb)`.\nIf something is prefixed with `(lldb)`, then you know\nthat it's a LLDB command.\n\nThe first thing I will do, is to set a breakpoint at\nthe `main()` function, by executing `b main`.\nAfter that, I just start the execution of the program\nwith `run`.\nYou can see in the output below, that the execution\nstopped at the first line in the function `main()`, as we expected.\n\n```bash\n(lldb) b main\nBreakpoint 1: where = debugging`debug1.main + 22\n    at debug1.zig:11:30, address = 0x00000000010341a6\n(lldb) run\nProcess 8654 launched: 'add_program' (x86_64)\nProcess 8654 stopped\n* thread #1, name = 'add_program',\n    stop reason = breakpoint 1.1 frame #0: 0x10341a6\n    add_program`debug1.main at add_program.zig:11:30\n   8   \t}\n   9\n   10  \tpub fn main() !void {\n-> 11  \t    var n = add_and_increment(2, 3);\n   12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n```\n\nI can start navigating through the code, and checking the objects\nthat are being generated. If you are not familiar with the commands\navailable in LLDB, I recommend you to read the official documentation\nof the project[^lldb].\nYou can also look for cheat sheets, which quickly describes all commands\navailable for you[^lldb-quick-list].\n\n[^lldb]: <https://lldb.llvm.org/>\n[^lldb-quick-list]: <https://gist.github.com/ryanchang/a2f738f0c3cc6fbd71fa>.\n\nCurrently, we are in the first line at the `main()` function. In this line, we create\nthe `n` object, by executing the `add_and_increment()` function.\nTo execute the current line of code, and go to the next line, we can\nrun the `n` LLDB command. Let's execute this command.\n\nAfter we executed this line, we can also look at the value stored inside this `n` object\nby using the `p` LLDB command. The syntax for this command is `p <name-of-object>`.\n\nIf we take a look at the value stored in the `n` object (`p n`),\nnotice that it stores the hexadecimal value `0x06`, which\nis the number 6 in decimal. We can also see that this value has a type of `unsigned char`,\nwhich is an unsigned 8-bit integer.\nWe have talked already about this in @sec-zig-strings, that `u8` integers in Zig are equivalent\nto the C data type `unsigned char`.\n\n\n\n```bash\n(lldb) n\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step over frame #0: 0x10341ae\n    debugging`debug1.main at debug1.zig:12:26\n   9\n   10  \tpub fn main() !void {\n   11  \t    var n = add_and_increment(2, 3);\n-> 12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n(lldb) p n\n(unsigned char) $1 = '\\x06'\n```\n\nNow, on the next line of code, we are executing the `add_and_increment()` function once again.\nWhy not step inside this function? Shall we? We can do that, by executing the `s` LLDB command.\nNotice in the example below that, after executing this command, we have entered into the context of the\n`add_and_increment()` function.\n\nAlso notice in the example below that, I have walked two more lines in the function's body, then,\nI execute the `frame variable` LLDB command, to see at once, the value stored in each of the variables\nthat were created inside the current scope.\n\nYou can see in the output below that, the object `sum` stores the value `\\f`,\nwhich represents the *form feed* character. This character in the ASCII table,\ncorresponds to the hexadecimal value `0x0C`, or, in decimal, the number 12.\nSo, this means that the result of the expression `a + b` executed at line\n5, resulted in the number 12.\n\n```bash\n(lldb) s\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step in frame #0: 0x10342de\n    debugging`debug1.add_and_increment(a='\\x02', b='\\x03')\n    at debug1.zig:4:39\n-> 4   \tfn add_and_increment(a: u8, b: u8) u8 {\n   5   \t    const sum = a + b;\n   6   \t    const incremented = sum + 1;\n   7   \t    return incremented;\n(lldb) n\n(lldb) n\n(lldb) frame variable\n(unsigned char) a = '\\x06'\n(unsigned char) b = '\\x06'\n(unsigned char) sum = '\\f'\n(unsigned char) incremented = '\\x06'\n```\n\n\n\n## How to investigate the data type of your objects\n\nSince Zig is a strongly-typed language, the data types associated with your objects\nare very important for your program. So, debugging the data types associated\nwith your objects might be important to understand bugs and errors in your program.\n\nWhen you walk through your program with a debugger, you can inspect the types of\nyour objects by simply printing them to the console, with the LLDB `p` command.\nBut you also have alternatives embedded in the language itself to access the data\ntypes of your objects.\n\nIn Zig, you can retrieve the data type of an object, by using the built-in function\n`@TypeOf()`. Just apply this function over the object, and you get access to\nthe data type of the object.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst expect = std.testing.expect;\n\npub fn main() !void {\n    const number: i32 = 5;\n    try expect(@TypeOf(number) == i32);\n    try stdout.print(\"{any}\\n\", .{@TypeOf(number)});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ni32\n```\n\n\n:::\n:::\n\n\n\nThis function is similar to the `type()` built-in function from Python,\nor, the `typeof` operator in Javascript.\n",
-    "supporting": [
-      "02-debugging_files"
-    ],
-    "filters": [
-      "rmarkdown/pagebreak.lua"
-    ],
-    "includes": {},
-    "engineDependencies": {
-      "knitr": [
-        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
-      ]
-    },
-    "preserve": null,
-    "postProcess": false
-  }
-}
\ No newline at end of file
diff --git a/_freeze/Chapters/02-debugging/execute-results/html.json b/_freeze/Chapters/02-debugging/execute-results/html.json
index 2068b83e..739f1f0c 100644
--- a/_freeze/Chapters/02-debugging/execute-results/html.json
+++ b/_freeze/Chapters/02-debugging/execute-results/html.json
@@ -2,10 +2,8 @@
   "hash": "f6eea7230762e3b8cde487458c00b745",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Debugging Zig applications\n\nBeing able to debug your applications is essential for any programmer who wants to\ndo serious programming in any language. That is why, in this chapter, we are going to talk about the\navailable strategies and tools to debug applications written in Zig.\n\n\n## Print debugging\n\nWe begin with the classic and battle-tested *print debugging* strategy.\nThe key advantage that debugging offers you is *visibility*.\nWith *print statements* you can easily see what results and objects\nare being produced by your application.\n\nThis is the essence of *print debugging* - using\nprint expressions to see the values that are being generated by your program,\nand, as a result, get a much better understanding of how your program\nis behaving.\n\nMany programmers often resort to the print functions in Zig, such as the `stdout.print()`,\nor, the `std.debug.print()`, to get a better understanding of their programs.\nThis is a known and old strategy that is very simple and effective, and it's better known within\nthe programming community as *print debugging*.\nIn Zig, you can print information to the `stdout` or `stderr` streams of your system.\n\nLet's begin with `stdout`. First, you\nneed to get access to the `stdout`, by calling the `getStdOut()` method, from\nthe Zig Standard Library. This method returns a *file descriptor* object,\nand, through this object you can read/write to the `stdout`.\nI recommend you to check out all methods available in this object, by [checking the page in\nthe Zig Standard Library Official Reference for the type `File`](https://ziglang.org/documentation/master/std/#std.fs.File)[^zig-fiile-reference].\n\n[^zig-fiile-reference]: <https://ziglang.org/documentation/master/std/#std.fs.File>.\n\nFor our purpose here, which is to write something to the `stdout`, especially to debug our\nprogram, I recommend you to use the `writer()` method, which gives you a *writer* object.\nThis *writer* object offers some helper methods to write stuff into the file descriptor object\nthat represents the `stdout` stream. In special, the `print()` method.\n\n\nThe `print()` method from this *writer* object is a \"print formatter\" type of a function.\nIn other words, this method works exactly like the `printf()` function from C,\nor, like `println!()` from Rust.\nIn the first argument of the function, you specify a template string, and,\nin the second argument, you provide a list of values (or objects) that you want to insert\ninto your template message.\n\nIdeally, the template string in the first argument should contain some format specifier.\nEach format specifier is matched to a value (or object) that you have listed in the second argument.\nSo, if you provided 5 different objects in the second argument, then, the template string\nshould contain 5 format specifiers, one for each object provided.\n\nEach format specifier is represented by a single letter, and\nyou provide this format specifier inside a pair of curly braces. So, if you want to format\nyour object using the string specifier (`s`), then, you can insert the text `{s}` in your template string.\nHere is a quick list of the most used format specifiers:\n\n- `d`: for printing integers and floating-point numbers.\n- `c`: for printing characters.\n- `s`: for printing strings.\n- `p`: for printing memory addresses.\n- `x`: for printing hexadecimal values.\n- `any`: use any compatible format specifier (i.e., it automatically selects a format specifier for you).\n\nThe code example below gives you an example of use of this `print()` method\nwith the `d` format specifier.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    try stdout.print(\"Result: {d}\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\n\n\nIt's important to emphasize that, the `stdout.print()` method, as you would expect,\nprints your template string into the `stdout` stream of your system.\nHowever, you can also print your template string into the `stderr` stream\nif your prefer. All you need to do, is to replace the `stdout.print()`\ncall with the function `std.debug.print()`. Like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    std.debug.print(\"Result: {d}\\n\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\n\n\n\nYou could also achieve the exact same result by getting a file descriptor object to `stderr`,\nthen, creating a *writer* object to `stderr`, then, using the `print()` method of this\n*writer* object, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stderr = std.io.getStdErr().writer();\n// some more lines ...\ntry stderr.print(\"Result: {d}\", .{result});\n```\n:::\n\n\n\n\n\n\n## Debugging through debuggers\n\nAlthough *print debugging* is a valid and very useful strategy,\nmost programmers prefer to use a debugger to debug their programs.\nSince Zig is a low-level language, you can use either GDB (GNU Debugger),\nor LLDB (LLVM Project Debugger) as your debugger.\n\nBoth debuggers can work with Zig code, and it's a matter of taste here.\nYou choose the debugger of your preference, and you work with it.\nIn this book, I will use LLDB as my debugger in the examples.\n\n\n### Compile your source code in debug mode {#sec-compile-debug-mode}\n\nIn order to debug your program through a debugger, you must compile\nyour source code in `Debug` mode. Because when you compile your\nsource code in other modes (such as `Release`), the compiler usually\nstrips out some essential information that is used by the debugger\nto read and track your program, like PDB (*Program Database*) files.\n\nBy compiling your source code in `Debug` mode, you ensure that the debugger\nwill find the necessary information in your program to debug it.\nBy default, the compiler uses the `Debug` mode when compiling your code.\nHaving this in mind, when you compile your program with the `build-exe`\ncommand (which was described in @sec-compile-code), if you don't specify\nan explicit mode through the `-O` command-line [^oargument]\nargument, then, the compiler will compile your code in `Debug` mode.\n\n[^oargument]: See <https://ziglang.org/documentation/master/#Debug>.\n\n\n### Let's debug a program\n\nAs an example, let's use LLDB to navigate and investigate the following\npiece of Zig code:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\nfn add_and_increment(a: u8, b: u8) u8 {\n    const sum = a + b;\n    const incremented = sum + 1;\n    return incremented;\n}\n\npub fn main() !void {\n    var n = add_and_increment(2, 3);\n    n = add_and_increment(n, n);\n    try stdout.print(\"Result: {d}!\\n\", .{n});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 13!\n```\n\n\n:::\n:::\n\n\n\n\nThere is nothing wrong with this program. But it's\na good start for us. First, we need to compile\nthis program with the `zig build-exe` command.\nFor this example, suppose that I have compiled the above\nZig code into a binary executable called `add_program`.\n\n```bash\nzig build-exe add_program.zig\n```\n\nNow, we can start LLDB with `add_program`, like this:\n\n```bash\nlldb add_program\n```\n\nFrom now on, LLDB is started, and you can know that I'm\nexecuting LLDB commands by looking at the prefix `(lldb)`.\nIf something is prefixed with `(lldb)`, then you know\nthat it's a LLDB command.\n\nThe first thing I will do, is to set a breakpoint at\nthe `main()` function, by executing `b main`.\nAfter that, I just start the execution of the program\nwith `run`.\nYou can see in the output below, that the execution\nstopped at the first line in the function `main()`, as we expected.\n\n```bash\n(lldb) b main\nBreakpoint 1: where = debugging`debug1.main + 22\n    at debug1.zig:11:30, address = 0x00000000010341a6\n(lldb) run\nProcess 8654 launched: 'add_program' (x86_64)\nProcess 8654 stopped\n* thread #1, name = 'add_program',\n    stop reason = breakpoint 1.1 frame #0: 0x10341a6\n    add_program`debug1.main at add_program.zig:11:30\n   8   \t}\n   9\n   10  \tpub fn main() !void {\n-> 11  \t    var n = add_and_increment(2, 3);\n   12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n```\n\nI can start navigating through the code, and checking the objects\nthat are being generated. If you are not familiar with the commands\navailable in LLDB, I recommend you to read the official documentation\nof the project[^lldb].\nYou can also look for cheat sheets, which quickly describes all commands\navailable for you[^lldb-quick-list].\n\n[^lldb]: <https://lldb.llvm.org/>\n[^lldb-quick-list]: <https://gist.github.com/ryanchang/a2f738f0c3cc6fbd71fa>.\n\nCurrently, we are in the first line at the `main()` function. In this line, we create\nthe `n` object, by executing the `add_and_increment()` function.\nTo execute the current line of code, and go to the next line, we can\nrun the `n` LLDB command. Let's execute this command.\n\nAfter we executed this line, we can also look at the value stored inside this `n` object\nby using the `p` LLDB command. The syntax for this command is `p <name-of-object>`.\n\nIf we take a look at the value stored in the `n` object (`p n`),\nnotice that it stores the hexadecimal value `0x06`, which\nis the number 6 in decimal. We can also see that this value has a type of `unsigned char`,\nwhich is an unsigned 8-bit integer.\nWe have talked already about this in @sec-zig-strings, that `u8` integers in Zig are equivalent\nto the C data type `unsigned char`.\n\n\n\n```bash\n(lldb) n\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step over frame #0: 0x10341ae\n    debugging`debug1.main at debug1.zig:12:26\n   9\n   10  \tpub fn main() !void {\n   11  \t    var n = add_and_increment(2, 3);\n-> 12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n(lldb) p n\n(unsigned char) $1 = '\\x06'\n```\n\nNow, on the next line of code, we are executing the `add_and_increment()` function once again.\nWhy not step inside this function? Shall we? We can do that, by executing the `s` LLDB command.\nNotice in the example below that, after executing this command, we have entered into the context of the\n`add_and_increment()` function.\n\nAlso notice in the example below that, I have walked two more lines in the function's body, then,\nI execute the `frame variable` LLDB command, to see at once, the value stored in each of the variables\nthat were created inside the current scope.\n\nYou can see in the output below that, the object `sum` stores the value `\\f`,\nwhich represents the *form feed* character. This character in the ASCII table,\ncorresponds to the hexadecimal value `0x0C`, or, in decimal, the number 12.\nSo, this means that the result of the expression `a + b` executed at line\n5, resulted in the number 12.\n\n```bash\n(lldb) s\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step in frame #0: 0x10342de\n    debugging`debug1.add_and_increment(a='\\x02', b='\\x03')\n    at debug1.zig:4:39\n-> 4   \tfn add_and_increment(a: u8, b: u8) u8 {\n   5   \t    const sum = a + b;\n   6   \t    const incremented = sum + 1;\n   7   \t    return incremented;\n(lldb) n\n(lldb) n\n(lldb) frame variable\n(unsigned char) a = '\\x06'\n(unsigned char) b = '\\x06'\n(unsigned char) sum = '\\f'\n(unsigned char) incremented = '\\x06'\n```\n\n\n\n## How to investigate the data type of your objects\n\nSince Zig is a strongly-typed language, the data types associated with your objects\nare very important for your program. So, debugging the data types associated\nwith your objects might be important to understand bugs and errors in your program.\n\nWhen you walk through your program with a debugger, you can inspect the types of\nyour objects by simply printing them to the console, with the LLDB `p` command.\nBut you also have alternatives embedded in the language itself to access the data\ntypes of your objects.\n\nIn Zig, you can retrieve the data type of an object, by using the built-in function\n`@TypeOf()`. Just apply this function over the object, and you get access to\nthe data type of the object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst expect = std.testing.expect;\n\npub fn main() !void {\n    const number: i32 = 5;\n    try expect(@TypeOf(number) == i32);\n    try stdout.print(\"{any}\\n\", .{@TypeOf(number)});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ni32\n```\n\n\n:::\n:::\n\n\n\n\nThis function is similar to the `type()` built-in function from Python,\nor, the `typeof` operator in Javascript.\n",
-    "supporting": [
-      "02-debugging_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Debugging Zig applications\n\nBeing able to debug your applications is essential for any programmer who wants to\ndo serious programming in any language. That is why, in this chapter, we are going to talk about the\navailable strategies and tools to debug applications written in Zig.\n\n\n## Print debugging\n\nWe begin with the classic and battle-tested *print debugging* strategy.\nThe key advantage that debugging offers you is *visibility*.\nWith *print statements* you can easily see what results and objects\nare being produced by your application.\n\nThis is the essence of *print debugging* - using\nprint expressions to see the values that are being generated by your program,\nand, as a result, get a much better understanding of how your program\nis behaving.\n\nMany programmers often resort to the print functions in Zig, such as the `stdout.print()`,\nor, the `std.debug.print()`, to get a better understanding of their programs.\nThis is a known and old strategy that is very simple and effective, and it's better known within\nthe programming community as *print debugging*.\nIn Zig, you can print information to the `stdout` or `stderr` streams of your system.\n\nLet's begin with `stdout`. First, you\nneed to get access to the `stdout`, by calling the `getStdOut()` method, from\nthe Zig Standard Library. This method returns a *file descriptor* object,\nand, through this object you can read/write to the `stdout`.\nI recommend you to check out all methods available in this object, by [checking the page in\nthe Zig Standard Library Official Reference for the type `File`](https://ziglang.org/documentation/master/std/#std.fs.File)[^zig-fiile-reference].\n\n[^zig-fiile-reference]: <https://ziglang.org/documentation/master/std/#std.fs.File>.\n\nFor our purpose here, which is to write something to the `stdout`, especially to debug our\nprogram, I recommend you to use the `writer()` method, which gives you a *writer* object.\nThis *writer* object offers some helper methods to write stuff into the file descriptor object\nthat represents the `stdout` stream. In special, the `print()` method.\n\n\nThe `print()` method from this *writer* object is a \"print formatter\" type of a function.\nIn other words, this method works exactly like the `printf()` function from C,\nor, like `println!()` from Rust.\nIn the first argument of the function, you specify a template string, and,\nin the second argument, you provide a list of values (or objects) that you want to insert\ninto your template message.\n\nIdeally, the template string in the first argument should contain some format specifier.\nEach format specifier is matched to a value (or object) that you have listed in the second argument.\nSo, if you provided 5 different objects in the second argument, then, the template string\nshould contain 5 format specifiers, one for each object provided.\n\nEach format specifier is represented by a single letter, and\nyou provide this format specifier inside a pair of curly braces. So, if you want to format\nyour object using the string specifier (`s`), then, you can insert the text `{s}` in your template string.\nHere is a quick list of the most used format specifiers:\n\n- `d`: for printing integers and floating-point numbers.\n- `c`: for printing characters.\n- `s`: for printing strings.\n- `p`: for printing memory addresses.\n- `x`: for printing hexadecimal values.\n- `any`: use any compatible format specifier (i.e., it automatically selects a format specifier for you).\n\nThe code example below gives you an example of use of this `print()` method\nwith the `d` format specifier.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    try stdout.print(\"Result: {d}\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\nIt's important to emphasize that, the `stdout.print()` method, as you would expect,\nprints your template string into the `stdout` stream of your system.\nHowever, you can also print your template string into the `stderr` stream\nif your prefer. All you need to do, is to replace the `stdout.print()`\ncall with the function `std.debug.print()`. Like this:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add(x: u8, y: u8) u8 {\n    return x + y;\n}\n\npub fn main() !void {\n    const result = add(34, 16);\n    std.debug.print(\"Result: {d}\\n\", .{result});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 50\n```\n\n\n:::\n:::\n\n\n\nYou could also achieve the exact same result by getting a file descriptor object to `stderr`,\nthen, creating a *writer* object to `stderr`, then, using the `print()` method of this\n*writer* object, like in the example below:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stderr = std.io.getStdErr().writer();\n// some more lines ...\ntry stderr.print(\"Result: {d}\", .{result});\n```\n:::\n\n\n\n\n## Debugging through debuggers\n\nAlthough *print debugging* is a valid and very useful strategy,\nmost programmers prefer to use a debugger to debug their programs.\nSince Zig is a low-level language, you can use either GDB (GNU Debugger),\nor LLDB (LLVM Project Debugger) as your debugger.\n\nBoth debuggers can work with Zig code, and it's a matter of taste here.\nYou choose the debugger of your preference, and you work with it.\nIn this book, I will use LLDB as my debugger in the examples.\n\n\n### Compile your source code in debug mode {#sec-compile-debug-mode}\n\nIn order to debug your program through a debugger, you must compile\nyour source code in `Debug` mode. Because when you compile your\nsource code in other modes (such as `Release`), the compiler usually\nstrips out some essential information that is used by the debugger\nto read and track your program, like PDB (*Program Database*) files.\n\nBy compiling your source code in `Debug` mode, you ensure that the debugger\nwill find the necessary information in your program to debug it.\nBy default, the compiler uses the `Debug` mode when compiling your code.\nHaving this in mind, when you compile your program with the `build-exe`\ncommand (which was described in @sec-compile-code), if you don't specify\nan explicit mode through the `-O` command-line [^oargument]\nargument, then, the compiler will compile your code in `Debug` mode.\n\n[^oargument]: See <https://ziglang.org/documentation/master/#Debug>.\n\n\n### Let's debug a program\n\nAs an example, let's use LLDB to navigate and investigate the following\npiece of Zig code:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\n\nfn add_and_increment(a: u8, b: u8) u8 {\n    const sum = a + b;\n    const incremented = sum + 1;\n    return incremented;\n}\n\npub fn main() !void {\n    var n = add_and_increment(2, 3);\n    n = add_and_increment(n, n);\n    try stdout.print(\"Result: {d}!\\n\", .{n});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nResult: 13!\n```\n\n\n:::\n:::\n\n\nThere is nothing wrong with this program. But it's\na good start for us. First, we need to compile\nthis program with the `zig build-exe` command.\nFor this example, suppose that I have compiled the above\nZig code into a binary executable called `add_program`.\n\n```bash\nzig build-exe add_program.zig\n```\n\nNow, we can start LLDB with `add_program`, like this:\n\n```bash\nlldb add_program\n```\n\nFrom now on, LLDB is started, and you can know that I'm\nexecuting LLDB commands by looking at the prefix `(lldb)`.\nIf something is prefixed with `(lldb)`, then you know\nthat it's a LLDB command.\n\nThe first thing I will do, is to set a breakpoint at\nthe `main()` function, by executing `b main`.\nAfter that, I just start the execution of the program\nwith `run`.\nYou can see in the output below, that the execution\nstopped at the first line in the function `main()`, as we expected.\n\n```bash\n(lldb) b main\nBreakpoint 1: where = debugging`debug1.main + 22\n    at debug1.zig:11:30, address = 0x00000000010341a6\n(lldb) run\nProcess 8654 launched: 'add_program' (x86_64)\nProcess 8654 stopped\n* thread #1, name = 'add_program',\n    stop reason = breakpoint 1.1 frame #0: 0x10341a6\n    add_program`debug1.main at add_program.zig:11:30\n   8   \t}\n   9\n   10  \tpub fn main() !void {\n-> 11  \t    var n = add_and_increment(2, 3);\n   12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n```\n\nI can start navigating through the code, and checking the objects\nthat are being generated. If you are not familiar with the commands\navailable in LLDB, I recommend you to read the official documentation\nof the project[^lldb].\nYou can also look for cheat sheets, which quickly describes all commands\navailable for you[^lldb-quick-list].\n\n[^lldb]: <https://lldb.llvm.org/>\n[^lldb-quick-list]: <https://gist.github.com/ryanchang/a2f738f0c3cc6fbd71fa>.\n\nCurrently, we are in the first line at the `main()` function. In this line, we create\nthe `n` object, by executing the `add_and_increment()` function.\nTo execute the current line of code, and go to the next line, we can\nrun the `n` LLDB command. Let's execute this command.\n\nAfter we executed this line, we can also look at the value stored inside this `n` object\nby using the `p` LLDB command. The syntax for this command is `p <name-of-object>`.\n\nIf we take a look at the value stored in the `n` object (`p n`),\nnotice that it stores the hexadecimal value `0x06`, which\nis the number 6 in decimal. We can also see that this value has a type of `unsigned char`,\nwhich is an unsigned 8-bit integer.\nWe have talked already about this in @sec-zig-strings, that `u8` integers in Zig are equivalent\nto the C data type `unsigned char`.\n\n\n\n```bash\n(lldb) n\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step over frame #0: 0x10341ae\n    debugging`debug1.main at debug1.zig:12:26\n   9\n   10  \tpub fn main() !void {\n   11  \t    var n = add_and_increment(2, 3);\n-> 12  \t    n = add_and_increment(n, n);\n   13  \t    try stdout.print(\"Result: {d}!\\n\", .{n});\n   14  \t}\n(lldb) p n\n(unsigned char) $1 = '\\x06'\n```\n\nNow, on the next line of code, we are executing the `add_and_increment()` function once again.\nWhy not step inside this function? Shall we? We can do that, by executing the `s` LLDB command.\nNotice in the example below that, after executing this command, we have entered into the context of the\n`add_and_increment()` function.\n\nAlso notice in the example below that, I have walked two more lines in the function's body, then,\nI execute the `frame variable` LLDB command, to see at once, the value stored in each of the variables\nthat were created inside the current scope.\n\nYou can see in the output below that, the object `sum` stores the value `\\f`,\nwhich represents the *form feed* character. This character in the ASCII table,\ncorresponds to the hexadecimal value `0x0C`, or, in decimal, the number 12.\nSo, this means that the result of the expression `a + b` executed at line\n5, resulted in the number 12.\n\n```bash\n(lldb) s\nProcess 4798 stopped\n* thread #1, name = 'debugging',\n    stop reason = step in frame #0: 0x10342de\n    debugging`debug1.add_and_increment(a='\\x02', b='\\x03')\n    at debug1.zig:4:39\n-> 4   \tfn add_and_increment(a: u8, b: u8) u8 {\n   5   \t    const sum = a + b;\n   6   \t    const incremented = sum + 1;\n   7   \t    return incremented;\n(lldb) n\n(lldb) n\n(lldb) frame variable\n(unsigned char) a = '\\x06'\n(unsigned char) b = '\\x06'\n(unsigned char) sum = '\\f'\n(unsigned char) incremented = '\\x06'\n```\n\n\n\n## How to investigate the data type of your objects\n\nSince Zig is a strongly-typed language, the data types associated with your objects\nare very important for your program. So, debugging the data types associated\nwith your objects might be important to understand bugs and errors in your program.\n\nWhen you walk through your program with a debugger, you can inspect the types of\nyour objects by simply printing them to the console, with the LLDB `p` command.\nBut you also have alternatives embedded in the language itself to access the data\ntypes of your objects.\n\nIn Zig, you can retrieve the data type of an object, by using the built-in function\n`@TypeOf()`. Just apply this function over the object, and you get access to\nthe data type of the object.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst expect = std.testing.expect;\n\npub fn main() !void {\n    const number: i32 = 5;\n    try expect(@TypeOf(number) == i32);\n    try stdout.print(\"{any}\\n\", .{@TypeOf(number)});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\ni32\n```\n\n\n:::\n:::\n\n\nThis function is similar to the `type()` built-in function from Python,\nor, the `typeof` operator in Javascript.\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/03-structs/execute-results/epub.json b/_freeze/Chapters/03-structs/execute-results/epub.json
deleted file mode 100644
index 7b1a937c..00000000
--- a/_freeze/Chapters/03-structs/execute-results/epub.json
+++ /dev/null
@@ -1,21 +0,0 @@
-{
-  "hash": "eb1d22d8dc0121e7c7768b70c606a801",
-  "result": {
-    "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Control flow, structs, modules and types\n\nWe have discussed a lot of Zig's syntax in the last chapter,\nespecially in @sec-root-file and @sec-main-file.\nBut we still need to discuss some other very important\nelements of the language. Elements that you will use constantly on your day-to-day\nroutine.\n\nWe begin this chapter by discussing the different keywords and structures\nin Zig related to control flow (e.g. loops and if statements).\nThen, we talk about structs and how they can be used to do some\nbasic Object-Oriented (OOP) patterns in Zig. We also talk about\ntype inference and type casting.\nFinally, we end this chapter by discussing modules, and how they relate\nto structs.\n\n\n\n## Control flow {#sec-zig-control-flow}\n\nSometimes, you need to make decisions in your program. Maybe you need to decide\nwhether or not to execute a specific piece of code. Or maybe,\nyou need to apply the same operation over a sequence of values. These kinds of tasks,\ninvolve using structures that are capable of changing the \"control flow\" of our program.\n\nIn computer science, the term \"control flow\" usually refers to the order in which expressions (or commands)\nare evaluated in a given language or program. But this term is also used to refer\nto structures that are capable of changing this \"evaluation order\" of the commands\nexecuted by a given language/program.\n\nThese structures are better known\nby a set of terms, such as: loops, if/else statements, switch statements, among others. So,\nloops and if/else statements are examples of structures that can change the \"control\nflow\" of our program. The keywords `continue` and `break` are also examples of symbols\nthat can change the order of evaluation, since they can move our program to the next iteration\nof a loop, or make the loop stop completely.\n\n\n### If/else statements\n\nAn if/else statement performs a \"conditional flow operation\".\nA conditional flow control (or choice control) allows you to execute\nor ignore a certain block of commands based on a logical condition.\nMany programmers and computer science professionals also use\nthe term \"branching\" in this case.\nIn essence, an if/else statement allow us to use the result of a logical test\nto decide whether or not to execute a given block of commands.\n\nIn Zig, we write if/else statements by using the keywords `if` and `else`.\nWe start with the `if` keyword followed by a logical test inside a pair\nof parentheses, followed by a pair of curly braces which contains the lines\nof code to be executed in case the logical test returns the value `true`.\n\nAfter that, you can optionally add an `else` statement. To do that, just add the `else`\nkeyword followed by a pair of curly braces, with the lines of code\nto executed in case the logical test defined at `if` returns `false`.\n\nIn the example below, we are testing if the object `x` contains a number\nthat is greater than 10. Judging by the output printed to the console,\nwe know that this logical test returned `false`. Because the output\nin the console is compatible with the line of code present in the\n`else` branch of the if/else statement.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x = 5;\nif (x > 10) {\n    try stdout.print(\n        \"x > 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x <= 10!\\n\", .{}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nx <= 10!\n```\n\n\n:::\n:::\n\n\n\n\n\n### Switch statements {#sec-switch}\n\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust.\nAs you would expect, to write a switch statement in Zig we use the `switch` keyword.\nWe provide the value that we want to \"switch over\" inside a\npair of parentheses. Then, we list the possible combinations (or \"branches\")\ninside a pair of curly braces.\n\nLet's take a look at the code example below. You can see that\nI'm creating an enum type called `Role`. We talk more about enums in @sec-enum.\nBut in summary, this `Role` type is listing different types of roles in a fictitious\ncompany, like `SE` for Software Engineer, `DE` for Data Engineer, `PM` for Product Manager,\netc.\n\nNotice that we are using the value from the `role` object in the\nswitch statement, to discover which exact area we need to store in the `area` variable object.\nAlso notice that we are using type inference inside the switch statement, with the dot character,\nas we are going to describe in @sec-type-inference.\nThis makes the `zig` compiler infer the correct data type of the values (`PM`, `SE`, etc.) for us.\n\nAlso notice that, we are grouping multiple values in the same branch of the switch statement.\nWe just separate each possible value with a comma. For example, if `role` contains either `DE` or `DA`,\nthe `area` variable would contain the value `\"Data & Analytics\"`, instead of `\"Platform\"` or `\"Sales\"`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO => {\n            area = \"Platform\";\n        },\n        .DE, .DA => {\n            area = \"Data & Analytics\";\n        },\n        .KS => {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nPlatform\n```\n\n\n:::\n:::\n\n\n\n\n#### Switch statements must exhaust all possibilities\n\nOne very important aspect about switch statements in Zig\nis that they must exhaust all existing possibilities.\nIn other words, all possible values that could be found inside the `role`\nobject must be explicitly handled in this switch statement.\n\nSince the `role` object has type `Role`, the only possible values to\nbe found inside this object are `PM`, `SE`, `DPE`, `PO`, `DE`, `DA` and `KS`.\nThere are no other possible values to be stored in this `role` object.\nThus, the switch statements must have a combination (branch) for each one of these values.\nThis is what \"exhaust all existing possibilities\" means. The switch statement covers\nevery possible case.\n\nTherefore, you cannot write a switch statement in Zig, and leave an edge case\nwith no explicit action to be taken.\nThis is a similar behaviour to switch statements in Rust, which also have to\nhandle all possible cases.\n\n\n\n#### The else branch\n\nTake a look at the `dump_hex_fallible()` function below as an example. This function\ncomes from the Zig Standard Library. More precisely, from the\n[`debug.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/debug.zig)[^debug-mod].\nThere are multiple lines in this function, but I omitted them to focus solely on the\nswitch statement found in this function. Notice that this switch statement has four\npossible cases (i.e., four explicit branches). Also, notice that we used an `else` branch\nin this case.\n\nAn `else` branch in a switch statement works as the \"default branch\".\nWhenever you have multiple cases in your switch statement where\nyou want to apply the exact same action, you can use an `else` branch to do that.\n\n[^debug-mod]: <https://github.com/ziglang/zig/blob/master/lib/std/debug.zig>\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' => try writer.writeAll(\"␊\"),\n        '\\r' => try writer.writeAll(\"␍\"),\n        '\\t' => try writer.writeAll(\"␉\"),\n        else => try writer.writeByte('.'),\n    }\n}\n```\n:::\n\n\n\nMany programmers would also use an `else` branch to handle a \"not supported\" case.\nThat is, a case that cannot be properly handled by your code, or, just a case that\nshould not be \"fixed\". Therefore, you can use an `else` branch to panic (or raise an error)\nin your program to stop the current execution.\n\nTake the code example below. We can see that, we are handling the cases\nfor the `level` object being either 1, 2, or 3. All other possible cases are not supported by default,\nand, as consequence, we raise a runtime error in such cases through the `@panic()` built-in function.\n\nAlso notice that, we are assigning the result of the switch statement to a new object called `category`.\nThis is another thing that you can do with switch statements in Zig. If a branch\noutputs a value as result, you can store the result value of the switch statement into\na new object.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 => \"beginner\",\n    3 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n:::\n\n\n\n```\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n```\n\n\n\n#### Using ranges in switch\n\nFurthermore, you can also use ranges of values in switch statements.\nThat is, you can create a branch in your switch statement that is used\nwhenever the input value is within the specified range. These \"range expressions\"\nare created with the operator `...`. It's important\nto emphasize that the ranges created by this operator are\ninclusive on both ends.\n\nFor example, I could easily change the previous code example to support all\nlevels between 0 and 100. Like this:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 => \"beginner\",\n    26...75 => \"intermediary\",\n    76...100 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nbeginner\n```\n\n\n:::\n:::\n\n\n\nThis is neat, and it works with character ranges too. That is, I could\nsimply write `'a'...'z'`, to match any character value that is a\nlowercase letter, and it would work fine.\n\n\n#### Labeled switch statements\n\nIn @sec-blocks we have talked about labeling blocks, and also, about using these labels\nto return a value from the block. Well, from version 0.14.0 and onwards of the `zig` compiler,\nyou can also apply labels over switch statements, which makes it possible to almost implement a\n\"C `goto`\" like pattern.\n\nFor example, if you give the label `xsw` to a switch statement, you can use this\nlabel in conjunction with the `continue` keyword to go back to the beginning of the switch\nstatement. In the example below, the execution goes back to the beginning of the\nswitch statement two times, before ending at the `3` branch.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nxsw: switch (@as(u8, 1)) {\n    1 => {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 => continue :xsw 3,\n    3 => return,\n    4 => {},\n    else => {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n```\n:::\n\n\n\n\n### The `defer` keyword {#sec-defer}\n\nWith the `defer` keyword you can register an expression to be executed when you exit the current scope.\nTherefore, this keyword has a similar functionality as the `on.exit()` function from R.\nTake the `foo()` function below as an example. When we execute this `foo()` function, the expression\nthat prints the message \"Exiting function ...\" is getting executed only when the function exits\nits scope.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n```\n:::\n\n\n\n```\nAdding some numbers ...\nMultiplying ...\nExiting function ...\n```\n\nTherefore, we can use `defer` to declare an expression that is going to be executed\nwhen your code exits the current scope. Some programmers like to interpret the phrase \"exit of the current scope\"\nas \"the end of the current scope\". But this interpretation might not be entirely correct, depending\non what you consider as \"the end of the current scope\".\n\nI mean, what do you consider as **the end** of the current scope? Is it the closing curly bracket (`}`) of the scope?\nIs it when the last expression in the function gets executed? Is it when the function returns to the previous scope?\nEtc. For example, it would not be correct to interpret the \"exit of the current scope\" as the closing\ncurly bracket of the scope. Because the function might exit from an earlier position than this\nclosing curly bracket (e.g. an error value was generated at a previous line inside the function;\nthe function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\n\nNow, if you remember of what we have discussed in @sec-blocks, there are multiple structures in the language\nthat create their own separate scopes. For/while loops, if/else statements,\nfunctions, normal blocks, etc. This also affects the interpretation of `defer`.\nFor example, if you use `defer` inside a for loop, then, the given expression\nwill be executed everytime this specific for loop exits its own scope.\n\nBefore we continue, it's worth emphasizing that the `defer` keyword is an \"unconditional defer\".\nWhich means that the given expression will be executed no matter how the code exits\nthe current scope. For example, your code might exit the current scope because of an error value\nbeing generated, or, because of a return statement, or, a break statement, etc.\n\n\n\n### The `errdefer` keyword {#sec-errdefer1}\n\nOn the previous section, we have discussed the `defer` keyword, which you can use to\nregister an expression to be executed at the exit of the current scope.\nBut this keyword has a brother, which is the `errdefer` keyword. While `defer`\nis an \"unconditional defer\", the `errdefer` keyword is a \"conditional defer\".\nWhich means that the given expression is executed only when you exit the current\nscope on a very specific circumstance.\n\nIn more details, the expression given to `errdefer` is executed only when an error occurs in the current scope.\nTherefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope\nin a normal situation, without errors, the expression given to `errdefer` is not executed.\n\nThis makes the `errdefer` keyword one of the many tools available in Zig for error handling.\nIn this section, we are more concerned with the control flow aspects around `errdefer`.\nBut we are going to discuss `errdefer` later as a error handling tool in @sec-errdefer2.\n\nThe code example below demonstrates three things:\n\n- that `defer` is an \"unconditional defer\", because the given expression gets executed regardless of how the function `foo()` exits its own scope.\n- that `errdefer` is executed because the function `foo()` returned an error value.\n- that `defer` and `errdefer` expressions are executed in a LIFO (*last in, first out*) order.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n```\n:::\n\n\n\n```\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\nWhen I say that \"defer expressions\" are executed in a LIFO order, what I want to say is that\nthe last `defer` or `errdefer` expressions in the code are the first ones to be executed.\nYou could also interpret this as: \"defer expressions\" are executed from bottom to top, or,\nfrom last to first.\n\nTherefore, if I change the order of the `defer` and `errdefer` expressions, you will notice that\nthe value of `i` that gets printed to the console changes to 1. This doesn't mean that the\n`defer` expression was not executed in this case. This actually means that the `defer` expression\nwas executed only after the `errdefer` expression. The code example below demonstrates this:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n```\n:::\n\n\n\n```\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\n\n\n### For loops\n\nA loop allows you to execute the same lines of code multiple times,\nthus, creating a \"repetition space\" in the execution flow of your program.\nLoops are particularly useful when we want to replicate the same function\n(or the same set of commands) over different inputs.\n\nThere are different types of loops available in Zig. But the most\nessential of them all is probably the *for loop*. A for loop is\nused to apply the same piece of code over the elements of a slice, or, an array.\n\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from\nother languages. You start with the `for` keyword, then, you\nlist the items that you want to iterate\nover inside a pair of parentheses. Then, inside of a pair of pipes (`|`)\nyou should declare an identifier that will serve as your iterator, or,\nthe \"repetition index of the loop\".\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (items) |value| {\n    // code to execute\n}\n```\n:::\n\n\n\nTherefore, instead of using a `(value in items)` syntax,\nin Zig, for loops use the syntax `(items) |value|`. In the example\nbelow, you can see that we are looping through the items\nof the array stored at the object `name`, and printing to the\nconsole the decimal representation of each character in this array.\n\nIf we wanted, we could also iterate through a slice (or a portion) of\nthe array, instead of iterating through the entire array stored in the `name` object.\nJust use a range selector to select the section you want. For example,\nI could provide the expression `name[0..3]` to the for loop, to iterate\njust through the first 3 elements in the array.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n80 | 101 | 100 | 114 | 111 | \n```\n\n\n:::\n:::\n\n\n\nIn the above example we are using the value itself of each\nelement in the array as our iterator. But there are many situations where\nwe need to use an index instead of the actual values of the items.\n\nYou can do that by providing a second set of items to iterate over.\nMore precisely, you provide the range selector `0..` to the for loop. So,\nyes, you can use two different iterators at the same time in a for\nloop in Zig.\n\nBut remember from @sec-assignments that, every object\nyou create in Zig must be used in some way. So if you declare two iterators\nin your for loop, you must use both iterators inside the for loop body.\nBut if you want to use just the index iterator, and not use the \"value iterator\",\nthen, you can discard the value iterator by maching the\nvalue items to the underscore character, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n:::\n\n\n\n```\n0 | 1 | 2 | 3 | 4 |\n```\n\n\n### While loops\n\nA while loop is created from the `while` keyword. A `for` loop\niterates through the items of an array, but a `while` loop\nwill loop continuously, and infinitely, until a logical test\n(specified by you) becomes false.\n\nYou start with the `while` keyword, then, you define a logical\nexpression inside a pair of parentheses, and the body of the\nloop is provided inside a pair of curly braces, like in the example below:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\nYou can also specify the increment expression to be used at the beginning of a while loop.\nTo do that, we write the increment expression inside a pair of parentheses after a colon character (`:`).\nThe code example below demonstrates this other pattern.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n### Using `break` and `continue`\n\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using\nthe keywords `break` and `continue`, respectively. The `while` loop presented in the next code example is,\nat first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to `true`.\nBut what makes this `while` loop stop when the `i` object reaches the count\n10? It's the `break` keyword!\n\nInside the while loop, we have an if statement that is constantly checking if the `i` variable\nis equal to 10. Since we are incrementing the value of `i` at each iteration of the\nwhile loop, this `i` object will eventually be equal to 10, and when it is, the if statement\nwill execute the `break` expression, and, as a result, the execution of the while loop is stopped.\n\nNotice the use of the `expect()` function from the Zig Standard Library after the while loop.\nThis `expect()` function is an \"assert\" type of function.\nThis function checks if the logical test provided is equal to true. If so, the function do nothing.\nOtherwise (i.e., the logical test is equal to false), the function raises an assertion error.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nEverything worked!\n```\n\n\n:::\n:::\n\n\n\nSince this code example was executed successfully by the `zig` compiler,\nwithout raising any errors, we known that, after the execution of the while loop,\nthe `i` object is equal to 10. Because if it wasn't equal to 10, an error would have\nbeen raised by `expect()`.\n\nNow, in the next example, we have a use case for\nthe `continue` keyword. The if statement is constantly\nchecking if the current index is a multiple of 2. If\nit is, we jump to the next iteration of the loop.\nOtherwise, the loop just prints the current index to the console.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 3 | 5 | \n```\n\n\n:::\n:::\n\n\n\n\n\n## Function parameters are immutable {#sec-fun-pars}\n\nWe have already discussed a lot of the syntax behind function declarations in @sec-root-file and @sec-main-file.\nBut I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig.\nIn summary, function parameters are immutable in Zig.\n\nTake the code example below, where we declare a simple function that just tries to add\nsome amount to the input integer, and returns the result back. If you look closely\nat the body of this `add2()` function, you will notice that we try\nto save the result back into the `x` function argument.\n\nIn other words, this function not only uses the value that it received through the function argument\n`x`, but it also tries to change the value of this function argument, by assigning the addition result\ninto `x`. However, function arguments in Zig are immutable. You cannot change their values, or, you\ncannot assign values to them inside the body's function.\n\nThis is the reason why, the code example below does not compile successfully. If you try to compile\nthis code example, you will get a compile error message about \"trying to change the value of a\nimmutable (i.e., constant) object\".\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n\n```\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n```\n\n\n### A free optimization\n\nIf a function argument receives as input an object whose data type is\nany of the primitive types that we have listed in @sec-primitive-data-types,\nthis object is always passed by value to the function. In other words, this object\nis copied into the function stack frame.\n\nHowever, if the input object have a more complex data type, for example, it might\nbe a struct instance, or an array, or an union value, etc., in cases like that, the `zig` compiler\nwill take the liberty of deciding for you which strategy is best. Thus, the `zig` compiler will\npass your object to the function either by value, or by reference. The compiler will always\nchoose the strategy that is faster for you.\nThis optimization that you get for free is possible only because function arguments are\nimmutable in Zig.\n\n\n### How to overcome this barrier\n\nThere are some situations where you might need to change the value of your function argument\ndirectly inside the function's body. This happens more often when we are passing\nC structs as inputs to Zig functions.\n\nIn a situation like this, you can overcome this barrier by using a pointer. In other words,\ninstead of passing a value as input to the argument, you can pass a \"pointer to value\" instead.\nYou can change the value that the pointer points to, by dereferencing it.\n\nTherefore, if we take our previous `add2()` example, we can change the value of the\nfunction argument `x` inside the function's body by marking the `x` argument as a\n\"pointer to a `u32` value\" (i.e., `*u32` data type), instead of a `u32` value.\nBy making it a pointer, we can finally alter the value of this function argument directly inside\nthe body of the `add2()` function. You can see that the code example below compiles successfully.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n```\n:::\n\n\n\n```\nResult: 6\n```\n\n\nEven in this code example above, the `x` argument is still immutable. Which means that the pointer itself is immutable.\nTherefore, you cannot change the memory address that it points to. However, you can dereference the pointer\nto access the value that it points to, and also, to change this value, if you need to.\n\n\n\n\n\n## Structs and OOP {#sec-structs-and-oop}\n\nZig is a language more closely related to C (which is a procedural language),\nthan it is to C++ or Java (which are object-oriented languages). Because of that, you do not\nhave advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or\nclass inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\n\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C.\nYou give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can\nalso register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object\nthat you create with this new type, will always have these methods available and associated with them.\n\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which\nis used to construct (or, to instantiate) every object of this particular class, and we also have\na destructor method (or a destructor function), which is the function responsible for destroying\nevery object of this class.\n\nIn Zig, we normally declare the constructor and the destructor methods\nof our structs, by declaring an `init()` and a `deinit()` methods inside the struct.\nThis is just a naming convention that you will find across the entire Zig Standard Library.\nSo, in Zig, the `init()` method of a struct is normally the constructor method of the class represented by this struct.\nWhile the `deinit()` method is the method used for destroying an existing instance of that struct.\n\nThe `init()` and `deinit()` methods are both used extensively in Zig code, and you will see both of\nthem being used when we talk about allocators in @sec-allocators.\nBut, as another example, let's build a simple `User` struct to represent a user of some sort of system.\n\nIf you look at the `User` struct below, you can see the `struct` keyword.\nNotice the data members of this struct: `id`, `name` and `email`. Every data member has its\ntype explicitly annotated, with the colon character (`:`) syntax that we described earlier in @sec-root-file.\nBut also notice that every line in the struct body that describes a data member, ends with a comma character (`,`).\nSo every time you declare a data member in your Zig code, always end the line with a comma character, instead\nof ending it with the traditional semicolon character (`;`).\n\nNext, we have registered an `init()` function as a method\nof this `User` struct. This `init()` method is the constructor method that we will use to instantiate\nevery new `User` object. That is why this `init()` function returns a new `User` object as result.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    fn init(id: u64,\n            name: []const u8,\n            email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\npedro\n```\n\n\n:::\n:::\n\n\n\n\n\n### The `pub` keyword\n\nThe `pub` keyword plays an important role in struct declarations, and OOP in Zig.\nIn essence, this keyword is short for \"public\", and it makes an item/component available outside of the\nmodule where this item/component is declared. In other words, if I don't apply the `pub` keyword on\nsomething, it means that this \"something\" is available to be called/used only from within the module\nwhere this \"something\" is declared.\n\nTo demonstrate the effect of this keyword let's focus again on the `User` struct that we have\ndeclared on the previous section. For our example here, let's suppose that this `User` struct is declared inside\na Zig module named `user.zig`. If I don't use the `pub` keyword on the `User` struct, it means that I can create\nan `User` object, and call it's methods (`print_name()` and `init()`) only from within the module where the `User`\nstruct is declared, which in this case is the `user.zig` module.\n\nThis is why the previous code example works fine. Because we declare and also use the `User` struct\ninside the same module. But problems start to arise when we try to import and call/use this struct\nfrom another module. For example, if I create a new module called `register.zig`, and import the `user.zig`\nmodule into it, and try to annotate any variable with the `User` type, I get an error from the compiler.\n\n```zig\n// register.zig\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = undefined;\n    _ = u;\n}\n```\n\n```\nregister.zig:3:18: error: 'User' is not marked 'pub'\n    const u: user.User = undefined;\n             ~~~~^~~~~\nuser.zig:3:1: note: declared here\nconst User = struct {\n^~~~~\n```\n\nTherefore, if you want to use something outside of the module where this \"something\" is declared,\nyou have to mark it with the `pub` keyword. This \"something\" can be a module,\na struct, a function, an object, etc.\n\nFor our example here, if we go back to the `user.zig` module, and add the `pub` keyword\nto the `User` struct declaration, then, I can successfully compile the `register.zig` module.\n\n```zig\n// user.zig\n// Added the `pub` keyword to `User`\npub const User = struct {\n// ...\n```\n\n```zig\n// register.zig\n// This works fine now!\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = undefined;\n    _ = u;\n}\n```\n\n\nNow, what do you think it will happen if I try to actually call from `register.zig` any of the methods\nof the `User` struct? For example, if I try to call the `init()` method? The answer is: I get a similar error message,\nwarning me that the `init()` method is not marked as `pub`, as you can see below:\n\n```zig\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = user.User.init(\n        1, \"pedro\", \"email@gmail.com\"\n    );\n    _ = u;\n}\n```\n\n```\nregister.zig:3:35: error: 'init' is not marked 'pub'\n    const u: user.User = user.User.init(\n                         ~~~~~~~~~^~~~~\nuser.zig:8:5: note: declared here\n    fn init(id: u64,\n    ^~~~~~~\n```\n\nThus, just because we have applied the `pub` keyword on the struct declaration,\nthis does not make the methods of that struct public as well. If we want to use\nany method from a struct (such as the `init()` method) outside of the module\nwhere this struct is declared, we have to mark this method with the `pub` keyword\nas well.\n\nGoing back to the `user.zig` module, and marking both the `init()` and `print_name()`\nmethods with the `pub` keyword, makes them both available to the outside world, and,\nas consequence, makes the previous code example work.\n\n\n```zig\n// user.zig\n// Added the `pub` keyword to `User.init`\n    pub fn init(\n// ...\n// Added the `pub` keyword to `User.print_name`\n    pub fn print_name(self: User) !void {\n// ...\n```\n\n```zig\n// register.zig\n// This works fine now!\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = user.User.init(\n        1, \"pedro\", \"email@gmail.com\"\n    );\n    _ = u;\n}\n```\n\n\n### Anonymous struct literals {#sec-anonymous-struct-literals}\n\nYou can declare a struct object as a literal value. When we do that, we normally specify the\ndata type of this struct literal by writing its data type just before the opening curly brace.\nFor example, I could write a struct literal value of the type `User` that we have defined\nin the previous section like this:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n```\n:::\n\n\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a\nstruct literal, but not specify explicitly the type of this particular struct.\nAn anonymous struct is written by using the syntax `.{}`. So, we essentially\nreplaced the explicit type of the struct literal with a dot character (`.`).\n\nAs we described in @sec-type-inference, when you put a dot before a struct literal,\nthe type of this struct literal is automatically inferred by the `zig` compiler.\nIn essence, the `zig` compiler will look for some hint of what is the type of that struct.\nThis hint can be the type annotation of a function argument,\nor the return type annotation of the function that you are using, or the type annotation\nof an existing object.\nIf the compiler does find such type annotation, it will use this\ntype in your literal struct.\n\nAnonymous structs are very commonly used as inputs to function arguments in Zig.\nOne example that you have seen already constantly, is the `print()`\nfunction from the `stdout` object.\nThis function takes two arguments.\nThe first argument, is a template string, which should\ncontain string format specifiers in it, which tells how the values provided\nin the second argument should be printed into the message.\n\nWhile the second argument is a struct literal that lists the values\nto be printed into the template message specified in the first argument.\nYou normally want to use an anonymous struct literal here, so that the\n`zig` compiler do the job of specifying the type of this particular\nanonymous struct for you.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello, world!\n```\n\n\n:::\n:::\n\n\n\n\n\n### Struct declarations must be constant\n\nTypes in Zig must be `const` or `comptime` (we are going to talk more about comptime in @sec-comptime).\nWhat this means is that you cannot create a new data type, and mark it as variable with the `var` keyword.\nSo struct declarations are always constant. You cannot declare a new struct type using the `var` keyword.\nIt must be `const`.\n\nIn the `Vec3` example below, this declaration is allowed because I'm using the `const` keyword\nto declare this new data type.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n```\n:::\n\n\n\n\n### The `self` method argument {#sec-self-arg}\n\nIn every language that have OOP, when we declare a method of some class or struct, we\nusually declare this method as a function that has a `self` argument.\nThis `self` argument is the reference to the object itself from which the method\nis being called from.\n\nIt's not mandatory to use this `self` argument. But why would you not use this `self` argument?\nThere is no reason to not use it. Because the only way to get access to the data stored in the\ndata members of your struct is to access them through this `self` argument.\nIf you don't need to use the data in the data members of your struct inside your method, you very likely don't need\na method. You can just declare this logic as a simple function, outside of your\nstruct declaration.\n\n\nTake the `Vec3` struct below. Inside this `Vec3` struct we declared a method named `distance()`.\nThis method calculates the distance between two `Vec3` objects, by following the distance\nformula in euclidean space. Notice that this `distance()` method takes two `Vec3` objects\nas input, `self` and `other`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n```\n:::\n\n\n\n\nThe `self` argument corresponds to the `Vec3` object from which this `distance()` method\nis being called from. While the `other` is a separate `Vec3` object that is given as input\nto this method. In the example below, the `self` argument corresponds to the object\n`v1`, because the `distance()` method is being called from the `v1` object,\nwhile the `other` argument corresponds to the object `v2`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n```\n:::\n\n\n\n```\nDistance: 3.3970575502926055\n```\n\n\n\n### About the struct state\n\nSometimes you don't need to care about the state of your struct object. Sometimes, you just need\nto instantiate and use the objects, without altering their state. You can notice that when you have methods\ninside your struct declaration that might use the values that are present in the data members, but they\ndo not alter the values in these data members of the struct in anyway.\n\nThe `Vec3` struct that was presented in @sec-self-arg is an example of that.\nThis struct have a single method named `distance()`, and this method does use the values\npresent in all three data members of the struct (`x`, `y` and `z`). But at the same time,\nthis method does not change the values of these data members at any point.\n\nAs a result of that, when we create `Vec3` objects we usually create them as\nconstant objects, like the `v1` and `v2` objects presented in @sec-self-arg.\nWe can create them as variable objects with the `var` keyword,\nif we want to. But because the methods of this `Vec3` struct do not change\nthe state of the objects in any point, it's unnecessary to mark them\nas variable objects.\n\nBut why? Why am I talking about this here? It's because the `self` argument\nin the methods are affected depending on whether the\nmethods present in a struct change or don't change the state of the object itself.\nMore specifically, when you have a method in a struct that changes the state\nof the object (i.e., changes the value of a data member), the `self` argument\nin this method must be annotated in a different manner.\n\nAs I described in @sec-self-arg, the `self` argument in methods of\na struct is the argument that receives as input the object from which the method\nwas called from. We usually annotate this argument in the methods by writing `self`,\nfollowed by the colon character (`:`), and the data type of the struct to which\nthe method belongs to (e.g. `User`, `Vec3`, etc.).\n\nIf we take the `Vec3` struct that we defined in the previous section as an example,\nwe can see in the `distance()` method that this `self` argument is annotated as\n`self: Vec3`. Because the state of the `Vec3` object is never altered by this\nmethod.\n\nBut what if we do have a method that alters the state of the object, by altering the\nvalues of its data members, how should we annotate `self` in this instance? The answer is:\n\"we should annotate `self` as a pointer of `x`, instead of just `x`\".\nIn other words, you should annotate `self` as `self: *x`, instead of annotating it\nas `self: x`.\n\nIf we create a new method inside the `Vec3` object that, for example, expands the\nvector by multiplying its coordinates by a factor of two, then, we need to follow\nthis rule specified in the previous paragraph. The code example below demonstrates\nthis idea:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n```\n:::\n\n\n\nNotice in the code example above that we have added a new method\nto our `Vec3` struct named `twice()`. This method doubles the\ncoordinate values of our vector object. In the\ncase of the `twice()` method, we annotated the `self` argument as `*Vec3`,\nindicating that this argument receives a pointer (or a reference, if you prefer to call it this way)\nto a `Vec3` object as input.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n```\n:::\n\n\n\n```\nDoubled: 8.4\n```\n\n\n\nNow, if you change the `self` argument in this `twice()` method to `self: Vec3`, like in the\n`distance()` method, you will get the compiler error exposed below as result. Notice that this\nerror message is showing a line from the `twice()` method body,\nindicating that you cannot alter the value of the `x` data member.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n```\n:::\n\n\n\n```\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\n```\n\nThis error message indicates that the `x` data member belongs to a constant object,\nand, because of that, it cannot be changed. Ultimately, this error message\nis telling us that the `self` argument is constant.\n\nIf you take some time, and think hard about this error message, you will understand it.\nYou already have the tools to understand why we are getting this error message.\nWe have talked about it already in @sec-fun-pars.\nSo remember, every function argument is immutable in Zig, and `self`\nis no exception to this rule.\n\nIn this example, we marked the `v3` object as a variable object.\nBut this does not matter. Because it's not about the input object, it's about\nthe function argument.\n\nThe problem begins when we try to alter the value of `self` directly, which is a function argument,\nand, every function argument is immutable by default. You may ask yourself how can we overcome\nthis barrier, and once again, the solution was also discussed in @sec-fun-pars.\nWe overcome this barrier, by explicitly marking the `self` argument as a pointer.\n\n\n::: {.callout-note}\nIf a method of your `x` struct alters the state of the object, by\nchanging the value of any data member, then, remember to use `self: *x`,\ninstead of `self: x` in the function signature of this method.\n:::\n\n\nYou could also interpret the content discussed in this section as:\n\"if you need to alter the state of your `x` struct object in one of its methods,\nyou must explicitly pass the `x` struct object by reference to the `self` argument of this method\".\n\n\n\n## Type inference {#sec-type-inference}\n\nZig is a strongly typed language. But, there are some situations\nwhere you don't have to explicitly write the type of every single object in your source code,\nas you would expect from a traditional strongly typed language, such as C and C++.\n\nIn some situations, the `zig` compiler can use type inference to solve the data types for you, easing some of\nthe burden that you carry as a developer.\nThe most common way this happens is through function arguments that receive struct objects\nas input.\n\nIn general, type inference in Zig is done by using the dot character (`.`).\nEverytime you see a dot character written before a struct literal, or before an enum value, or something like that,\nyou know that this dot character is playing a special part in this place. More specifically, it's\ntelling the `zig` compiler something along the lines of: \"Hey! Can you infer the type of this\nvalue for me? Please!\". In other words, this dot character is playing a similar role as the `auto` keyword in C++.\n\nI gave you some examples of this in @sec-anonymous-struct-literals, where we used anonymous struct literals.\nAnonymous struct literals are, struct literals that use type inference to\ninfer the exact type of this particular struct literal.\nThis type inference is done by looking for some minimal hint of the correct data type to be used.\nYou could say that the `zig` compiler looks for any neighbouring type annotation that might tell it\nwhat the correct type would be.\n\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in @sec-switch).\nI also gave some other examples of type inference in @sec-switch, where we were inferring the data types of enum values listed inside\nof switch statements (e.g. `.DE`).\nBut as another example, take a look at this `fence()` function reproduced below,\nwhich comes from the [`atomic.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig)[^fence-fn]\nof the Zig Standard Library.\n\n[^fence-fn]: <https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig>.\n\nThere are a lot of things in this function that we haven't talked about yet, such as:\nwhat `comptime` means? `inline`? `extern`?\nLet's just ignore all of these things, and focus solely on the switch statement\nthat is inside this function.\n\nWe can see that this switch statement uses the `order` object as input. This `order`\nobject is one of the inputs of this `fence()` function, and we can see in the type annotation,\nthat this object is of type `AtomicOrder`. We can also see a bunch of values inside the\nswitch statements that begin with a dot character, such as `.release` and `.acquire`.\n\nBecause these weird values contain a dot character before them, we are asking the `zig`\ncompiler to infer the types of these values inside the switch statement. Then, the `zig`\ncompiler is looking into the current context where these values are being used, and trying\nto infer the types of these values.\n\nSince they are being used inside a switch statement, the `zig` compiler looks into the type\nof the input object given to the switch statement, which is the `order` object in this case.\nBecause this object have type `AtomicOrder`, the `zig` compiler infers that these values\nare data members from this type `AtomicOrder`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic => @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire => tsan.__tsan_acquire(addr),\n            .release => tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst => {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n```\n:::\n\n\n\nThis is how basic type inference is done in Zig. If we didn't use the dot character before\nthe values inside this switch statement, then, we would be forced to explicitly write\nthe data types of these values. For example, instead of writing `.release` we would have to\nwrite `AtomicOrder.release`. We would have to do this for every single value\nin this switch statement, and this is a lot of work. That is why type inference\nis commonly used on switch statements in Zig.\n\n\n\n## Type casting {#sec-type-cast}\n\nIn this section, I want to discuss type casting (or, type conversion) with you.\nWe use type casting when we have an object of type \"x\", and we want to convert\nit into an object of type \"y\", i.e., we want to change the data type of the object.\n\nMost languages have a formal way to perform type casting. In Rust for example, we normally\nuse the keyword `as`, and in C, we normally use the type casting syntax, e.g. `(int) x`.\nIn Zig, we use the `@as()` built-in function to cast an object of type \"x\", into\nan object of type \"y\".\n\nThis `@as()` function is the preferred way to perform type conversion (or type casting)\nin Zig. Because it's explicit, and, it also performs the casting only if it\nis unambiguous and safe. To use this function, you just provide the target data type\nin the first argument, and, the object that you want cast as the second argument.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file3731626c8b4e.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\nThis is the general way to perform type casting in Zig. But remember, `@as()` works only when casting\nis unambiguous and safe. There are many situations where these assumptions do not hold. For example,\n\nwhen casting an integer value into a float value, or vice-versa, it's not clear to the compiler\nhow to perform this conversion safely.\n\nTherefore, we need to use specialized \"casting functions\" in such situations.\nFor example, if you want to cast an integer value into a float value, then, you\nshould use the `@floatFromInt()` function. In the inverse scenario, you should use\nthe `@intFromFloat()` function.\n\nIn these functions, you just provide the object that you want to\ncast as input. Then, the target data type of the \"type casting operation\" is determined by\nthe type annotation of the object where you are saving the results.\nIn the example below, we are casting the object `x` into a value of type `f32`,\nbecause the object `y`, which is where we are saving the results, is annotated\nas an object of type `f32`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file373174d96589.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\nAnother built-in function that is very useful when performing type casting operations is `@ptrCast()`.\nIn essence, we use the `@as()` built-in function when we want to explicit convert (or cast) a Zig value/object\nfrom a type \"x\" to a type \"y\", etc. However, pointers (we are going to discuss pointers\nin more depth in @sec-pointer) are a special type of object in Zig,\ni.e., they are treated differently from \"normal objects\".\n\nEverytime a pointer is involved in some \"type casting operation\" in Zig, the `@ptrCast()` function is used.\nThis function works similarly to `@floatFromInt()`.\nYou just provide the pointer object that you want to cast as input to this function, and the\ntarget data type is, once again, determined by the type annotation of the object where the results are being\nstored.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file373135327b62.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n## Modules\n\nWe already talked about what modules are, and also, how to import other modules into\nyour current module via *import statements*. Every Zig module (i.e., a `.zig` file) that you write in your project\nis internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the\nZig Standard Library into our current module.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n```\n:::\n\n\n\nWhen we want to access the functions and objects from the standard library, we\nare basically accessing the data members of the struct stored in the `std`\nobject. That is why we use the same syntax that we use in normal structs, with the dot operator (`.`)\nto access the data members and methods of the struct.\n\nWhen this \"import statement\" gets executed, the result of this expression is a struct\nobject that contains the Zig Standard Library modules, global variables, functions, etc.\nAnd this struct object gets saved (or stored) inside the constant object named `std`.\n\n\nTake the [`thread_pool.zig` module from the project `zap`](https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig)[^thread]\nas an example. This module is written as if it was\na big struct. That is why we have a top-level and public `init()` method\nwritten in this module. The idea is that all top-level functions written in this\nmodule are methods from the struct, and all top-level objects and struct declarations\nare data members of this struct. The module is the struct itself.\n\n[^thread]: <https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig>\n\n\nSo you would import and use this module by doing something like this:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst ThreadPool = @import(\"thread_pool.zig\");\nconst num_cpus = std.Thread.getCpuCount()\n    catch @panic(\"failed to get cpu core count\");\nconst num_threads = std.math.cast(u16, num_cpus)\n    catch std.math.maxInt(u16);\nconst pool = ThreadPool.init(\n    .{ .max_threads = num_threads }\n);\n```\n:::\n",
-    "supporting": [
-      "03-structs_files"
-    ],
-    "filters": [
-      "rmarkdown/pagebreak.lua"
-    ],
-    "includes": {},
-    "engineDependencies": {
-      "knitr": [
-        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
-      ]
-    },
-    "preserve": null,
-    "postProcess": false
-  }
-}
\ No newline at end of file
diff --git a/_freeze/Chapters/03-structs/execute-results/html.json b/_freeze/Chapters/03-structs/execute-results/html.json
index a05f2337..a74310d7 100644
--- a/_freeze/Chapters/03-structs/execute-results/html.json
+++ b/_freeze/Chapters/03-structs/execute-results/html.json
@@ -1,8 +1,8 @@
 {
-  "hash": "eb1d22d8dc0121e7c7768b70c606a801",
+  "hash": "5eabe664631237b4e295d88eb82533f3",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Control flow, structs, modules and types\n\nWe have discussed a lot of Zig's syntax in the last chapter,\nespecially in @sec-root-file and @sec-main-file.\nBut we still need to discuss some other very important\nelements of the language. Elements that you will use constantly on your day-to-day\nroutine.\n\nWe begin this chapter by discussing the different keywords and structures\nin Zig related to control flow (e.g. loops and if statements).\nThen, we talk about structs and how they can be used to do some\nbasic Object-Oriented (OOP) patterns in Zig. We also talk about\ntype inference and type casting.\nFinally, we end this chapter by discussing modules, and how they relate\nto structs.\n\n\n\n## Control flow {#sec-zig-control-flow}\n\nSometimes, you need to make decisions in your program. Maybe you need to decide\nwhether or not to execute a specific piece of code. Or maybe,\nyou need to apply the same operation over a sequence of values. These kinds of tasks,\ninvolve using structures that are capable of changing the \"control flow\" of our program.\n\nIn computer science, the term \"control flow\" usually refers to the order in which expressions (or commands)\nare evaluated in a given language or program. But this term is also used to refer\nto structures that are capable of changing this \"evaluation order\" of the commands\nexecuted by a given language/program.\n\nThese structures are better known\nby a set of terms, such as: loops, if/else statements, switch statements, among others. So,\nloops and if/else statements are examples of structures that can change the \"control\nflow\" of our program. The keywords `continue` and `break` are also examples of symbols\nthat can change the order of evaluation, since they can move our program to the next iteration\nof a loop, or make the loop stop completely.\n\n\n### If/else statements\n\nAn if/else statement performs a \"conditional flow operation\".\nA conditional flow control (or choice control) allows you to execute\nor ignore a certain block of commands based on a logical condition.\nMany programmers and computer science professionals also use\nthe term \"branching\" in this case.\nIn essence, an if/else statement allow us to use the result of a logical test\nto decide whether or not to execute a given block of commands.\n\nIn Zig, we write if/else statements by using the keywords `if` and `else`.\nWe start with the `if` keyword followed by a logical test inside a pair\nof parentheses, followed by a pair of curly braces which contains the lines\nof code to be executed in case the logical test returns the value `true`.\n\nAfter that, you can optionally add an `else` statement. To do that, just add the `else`\nkeyword followed by a pair of curly braces, with the lines of code\nto executed in case the logical test defined at `if` returns `false`.\n\nIn the example below, we are testing if the object `x` contains a number\nthat is greater than 10. Judging by the output printed to the console,\nwe know that this logical test returned `false`. Because the output\nin the console is compatible with the line of code present in the\n`else` branch of the if/else statement.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x = 5;\nif (x > 10) {\n    try stdout.print(\n        \"x > 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x <= 10!\\n\", .{}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nx <= 10!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n### Switch statements {#sec-switch}\n\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust.\nAs you would expect, to write a switch statement in Zig we use the `switch` keyword.\nWe provide the value that we want to \"switch over\" inside a\npair of parentheses. Then, we list the possible combinations (or \"branches\")\ninside a pair of curly braces.\n\nLet's take a look at the code example below. You can see that\nI'm creating an enum type called `Role`. We talk more about enums in @sec-enum.\nBut in summary, this `Role` type is listing different types of roles in a fictitious\ncompany, like `SE` for Software Engineer, `DE` for Data Engineer, `PM` for Product Manager,\netc.\n\nNotice that we are using the value from the `role` object in the\nswitch statement, to discover which exact area we need to store in the `area` variable object.\nAlso notice that we are using type inference inside the switch statement, with the dot character,\nas we are going to describe in @sec-type-inference.\nThis makes the `zig` compiler infer the correct data type of the values (`PM`, `SE`, etc.) for us.\n\nAlso notice that, we are grouping multiple values in the same branch of the switch statement.\nWe just separate each possible value with a comma. For example, if `role` contains either `DE` or `DA`,\nthe `area` variable would contain the value `\"Data & Analytics\"`, instead of `\"Platform\"` or `\"Sales\"`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO => {\n            area = \"Platform\";\n        },\n        .DE, .DA => {\n            area = \"Data & Analytics\";\n        },\n        .KS => {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nPlatform\n```\n\n\n:::\n:::\n\n\n\n\n\n\n#### Switch statements must exhaust all possibilities\n\nOne very important aspect about switch statements in Zig\nis that they must exhaust all existing possibilities.\nIn other words, all possible values that could be found inside the `role`\nobject must be explicitly handled in this switch statement.\n\nSince the `role` object has type `Role`, the only possible values to\nbe found inside this object are `PM`, `SE`, `DPE`, `PO`, `DE`, `DA` and `KS`.\nThere are no other possible values to be stored in this `role` object.\nThus, the switch statements must have a combination (branch) for each one of these values.\nThis is what \"exhaust all existing possibilities\" means. The switch statement covers\nevery possible case.\n\nTherefore, you cannot write a switch statement in Zig, and leave an edge case\nwith no explicit action to be taken.\nThis is a similar behaviour to switch statements in Rust, which also have to\nhandle all possible cases.\n\n\n\n#### The else branch\n\nTake a look at the `dump_hex_fallible()` function below as an example. This function\ncomes from the Zig Standard Library. More precisely, from the\n[`debug.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/debug.zig)[^debug-mod].\nThere are multiple lines in this function, but I omitted them to focus solely on the\nswitch statement found in this function. Notice that this switch statement has four\npossible cases (i.e., four explicit branches). Also, notice that we used an `else` branch\nin this case.\n\nAn `else` branch in a switch statement works as the \"default branch\".\nWhenever you have multiple cases in your switch statement where\nyou want to apply the exact same action, you can use an `else` branch to do that.\n\n[^debug-mod]: <https://github.com/ziglang/zig/blob/master/lib/std/debug.zig>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' => try writer.writeAll(\"␊\"),\n        '\\r' => try writer.writeAll(\"␍\"),\n        '\\t' => try writer.writeAll(\"␉\"),\n        else => try writer.writeByte('.'),\n    }\n}\n```\n:::\n\n\n\n\n\nMany programmers would also use an `else` branch to handle a \"not supported\" case.\nThat is, a case that cannot be properly handled by your code, or, just a case that\nshould not be \"fixed\". Therefore, you can use an `else` branch to panic (or raise an error)\nin your program to stop the current execution.\n\nTake the code example below. We can see that, we are handling the cases\nfor the `level` object being either 1, 2, or 3. All other possible cases are not supported by default,\nand, as consequence, we raise a runtime error in such cases through the `@panic()` built-in function.\n\nAlso notice that, we are assigning the result of the switch statement to a new object called `category`.\nThis is another thing that you can do with switch statements in Zig. If a branch\noutputs a value as result, you can store the result value of the switch statement into\na new object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 => \"beginner\",\n    3 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n:::\n\n\n\n\n\n```\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n```\n\n\n\n#### Using ranges in switch\n\nFurthermore, you can also use ranges of values in switch statements.\nThat is, you can create a branch in your switch statement that is used\nwhenever the input value is within the specified range. These \"range expressions\"\nare created with the operator `...`. It's important\nto emphasize that the ranges created by this operator are\ninclusive on both ends.\n\nFor example, I could easily change the previous code example to support all\nlevels between 0 and 100. Like this:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 => \"beginner\",\n    26...75 => \"intermediary\",\n    76...100 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nbeginner\n```\n\n\n:::\n:::\n\n\n\n\n\nThis is neat, and it works with character ranges too. That is, I could\nsimply write `'a'...'z'`, to match any character value that is a\nlowercase letter, and it would work fine.\n\n\n#### Labeled switch statements\n\nIn @sec-blocks we have talked about labeling blocks, and also, about using these labels\nto return a value from the block. Well, from version 0.14.0 and onwards of the `zig` compiler,\nyou can also apply labels over switch statements, which makes it possible to almost implement a\n\"C `goto`\" like pattern.\n\nFor example, if you give the label `xsw` to a switch statement, you can use this\nlabel in conjunction with the `continue` keyword to go back to the beginning of the switch\nstatement. In the example below, the execution goes back to the beginning of the\nswitch statement two times, before ending at the `3` branch.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nxsw: switch (@as(u8, 1)) {\n    1 => {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 => continue :xsw 3,\n    3 => return,\n    4 => {},\n    else => {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n```\n:::\n\n\n\n\n\n\n### The `defer` keyword {#sec-defer}\n\nWith the `defer` keyword you can register an expression to be executed when you exit the current scope.\nTherefore, this keyword has a similar functionality as the `on.exit()` function from R.\nTake the `foo()` function below as an example. When we execute this `foo()` function, the expression\nthat prints the message \"Exiting function ...\" is getting executed only when the function exits\nits scope.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n```\n:::\n\n\n\n\n\n```\nAdding some numbers ...\nMultiplying ...\nExiting function ...\n```\n\nTherefore, we can use `defer` to declare an expression that is going to be executed\nwhen your code exits the current scope. Some programmers like to interpret the phrase \"exit of the current scope\"\nas \"the end of the current scope\". But this interpretation might not be entirely correct, depending\non what you consider as \"the end of the current scope\".\n\nI mean, what do you consider as **the end** of the current scope? Is it the closing curly bracket (`}`) of the scope?\nIs it when the last expression in the function gets executed? Is it when the function returns to the previous scope?\nEtc. For example, it would not be correct to interpret the \"exit of the current scope\" as the closing\ncurly bracket of the scope. Because the function might exit from an earlier position than this\nclosing curly bracket (e.g. an error value was generated at a previous line inside the function;\nthe function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\n\nNow, if you remember of what we have discussed in @sec-blocks, there are multiple structures in the language\nthat create their own separate scopes. For/while loops, if/else statements,\nfunctions, normal blocks, etc. This also affects the interpretation of `defer`.\nFor example, if you use `defer` inside a for loop, then, the given expression\nwill be executed everytime this specific for loop exits its own scope.\n\nBefore we continue, it's worth emphasizing that the `defer` keyword is an \"unconditional defer\".\nWhich means that the given expression will be executed no matter how the code exits\nthe current scope. For example, your code might exit the current scope because of an error value\nbeing generated, or, because of a return statement, or, a break statement, etc.\n\n\n\n### The `errdefer` keyword {#sec-errdefer1}\n\nOn the previous section, we have discussed the `defer` keyword, which you can use to\nregister an expression to be executed at the exit of the current scope.\nBut this keyword has a brother, which is the `errdefer` keyword. While `defer`\nis an \"unconditional defer\", the `errdefer` keyword is a \"conditional defer\".\nWhich means that the given expression is executed only when you exit the current\nscope on a very specific circumstance.\n\nIn more details, the expression given to `errdefer` is executed only when an error occurs in the current scope.\nTherefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope\nin a normal situation, without errors, the expression given to `errdefer` is not executed.\n\nThis makes the `errdefer` keyword one of the many tools available in Zig for error handling.\nIn this section, we are more concerned with the control flow aspects around `errdefer`.\nBut we are going to discuss `errdefer` later as a error handling tool in @sec-errdefer2.\n\nThe code example below demonstrates three things:\n\n- that `defer` is an \"unconditional defer\", because the given expression gets executed regardless of how the function `foo()` exits its own scope.\n- that `errdefer` is executed because the function `foo()` returned an error value.\n- that `defer` and `errdefer` expressions are executed in a LIFO (*last in, first out*) order.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n```\n:::\n\n\n\n\n\n```\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\nWhen I say that \"defer expressions\" are executed in a LIFO order, what I want to say is that\nthe last `defer` or `errdefer` expressions in the code are the first ones to be executed.\nYou could also interpret this as: \"defer expressions\" are executed from bottom to top, or,\nfrom last to first.\n\nTherefore, if I change the order of the `defer` and `errdefer` expressions, you will notice that\nthe value of `i` that gets printed to the console changes to 1. This doesn't mean that the\n`defer` expression was not executed in this case. This actually means that the `defer` expression\nwas executed only after the `errdefer` expression. The code example below demonstrates this:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n```\n:::\n\n\n\n\n\n```\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\n\n\n### For loops\n\nA loop allows you to execute the same lines of code multiple times,\nthus, creating a \"repetition space\" in the execution flow of your program.\nLoops are particularly useful when we want to replicate the same function\n(or the same set of commands) over different inputs.\n\nThere are different types of loops available in Zig. But the most\nessential of them all is probably the *for loop*. A for loop is\nused to apply the same piece of code over the elements of a slice, or, an array.\n\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from\nother languages. You start with the `for` keyword, then, you\nlist the items that you want to iterate\nover inside a pair of parentheses. Then, inside of a pair of pipes (`|`)\nyou should declare an identifier that will serve as your iterator, or,\nthe \"repetition index of the loop\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (items) |value| {\n    // code to execute\n}\n```\n:::\n\n\n\n\n\nTherefore, instead of using a `(value in items)` syntax,\nin Zig, for loops use the syntax `(items) |value|`. In the example\nbelow, you can see that we are looping through the items\nof the array stored at the object `name`, and printing to the\nconsole the decimal representation of each character in this array.\n\nIf we wanted, we could also iterate through a slice (or a portion) of\nthe array, instead of iterating through the entire array stored in the `name` object.\nJust use a range selector to select the section you want. For example,\nI could provide the expression `name[0..3]` to the for loop, to iterate\njust through the first 3 elements in the array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n80 | 101 | 100 | 114 | 111 | \n```\n\n\n:::\n:::\n\n\n\n\n\nIn the above example we are using the value itself of each\nelement in the array as our iterator. But there are many situations where\nwe need to use an index instead of the actual values of the items.\n\nYou can do that by providing a second set of items to iterate over.\nMore precisely, you provide the range selector `0..` to the for loop. So,\nyes, you can use two different iterators at the same time in a for\nloop in Zig.\n\nBut remember from @sec-assignments that, every object\nyou create in Zig must be used in some way. So if you declare two iterators\nin your for loop, you must use both iterators inside the for loop body.\nBut if you want to use just the index iterator, and not use the \"value iterator\",\nthen, you can discard the value iterator by maching the\nvalue items to the underscore character, like in the example below:\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n:::\n\n\n\n\n\n```\n0 | 1 | 2 | 3 | 4 |\n```\n\n\n### While loops\n\nA while loop is created from the `while` keyword. A `for` loop\niterates through the items of an array, but a `while` loop\nwill loop continuously, and infinitely, until a logical test\n(specified by you) becomes false.\n\nYou start with the `while` keyword, then, you define a logical\nexpression inside a pair of parentheses, and the body of the\nloop is provided inside a pair of curly braces, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\n\nYou can also specify the increment expression to be used at the beginning of a while loop.\nTo do that, we write the increment expression inside a pair of parentheses after a colon character (`:`).\nThe code example below demonstrates this other pattern.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n\n\n\n### Using `break` and `continue`\n\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using\nthe keywords `break` and `continue`, respectively. The `while` loop presented in the next code example is,\nat first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to `true`.\nBut what makes this `while` loop stop when the `i` object reaches the count\n10? It's the `break` keyword!\n\nInside the while loop, we have an if statement that is constantly checking if the `i` variable\nis equal to 10. Since we are incrementing the value of `i` at each iteration of the\nwhile loop, this `i` object will eventually be equal to 10, and when it is, the if statement\nwill execute the `break` expression, and, as a result, the execution of the while loop is stopped.\n\nNotice the use of the `expect()` function from the Zig Standard Library after the while loop.\nThis `expect()` function is an \"assert\" type of function.\nThis function checks if the logical test provided is equal to true. If so, the function do nothing.\nOtherwise (i.e., the logical test is equal to false), the function raises an assertion error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nEverything worked!\n```\n\n\n:::\n:::\n\n\n\n\n\nSince this code example was executed successfully by the `zig` compiler,\nwithout raising any errors, we known that, after the execution of the while loop,\nthe `i` object is equal to 10. Because if it wasn't equal to 10, an error would have\nbeen raised by `expect()`.\n\nNow, in the next example, we have a use case for\nthe `continue` keyword. The if statement is constantly\nchecking if the current index is a multiple of 2. If\nit is, we jump to the next iteration of the loop.\nOtherwise, the loop just prints the current index to the console.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 3 | 5 | \n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n## Function parameters are immutable {#sec-fun-pars}\n\nWe have already discussed a lot of the syntax behind function declarations in @sec-root-file and @sec-main-file.\nBut I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig.\nIn summary, function parameters are immutable in Zig.\n\nTake the code example below, where we declare a simple function that just tries to add\nsome amount to the input integer, and returns the result back. If you look closely\nat the body of this `add2()` function, you will notice that we try\nto save the result back into the `x` function argument.\n\nIn other words, this function not only uses the value that it received through the function argument\n`x`, but it also tries to change the value of this function argument, by assigning the addition result\ninto `x`. However, function arguments in Zig are immutable. You cannot change their values, or, you\ncannot assign values to them inside the body's function.\n\nThis is the reason why, the code example below does not compile successfully. If you try to compile\nthis code example, you will get a compile error message about \"trying to change the value of a\nimmutable (i.e., constant) object\".\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n\n\n\n```\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n```\n\n\n### A free optimization\n\nIf a function argument receives as input an object whose data type is\nany of the primitive types that we have listed in @sec-primitive-data-types,\nthis object is always passed by value to the function. In other words, this object\nis copied into the function stack frame.\n\nHowever, if the input object have a more complex data type, for example, it might\nbe a struct instance, or an array, or an union value, etc., in cases like that, the `zig` compiler\nwill take the liberty of deciding for you which strategy is best. Thus, the `zig` compiler will\npass your object to the function either by value, or by reference. The compiler will always\nchoose the strategy that is faster for you.\nThis optimization that you get for free is possible only because function arguments are\nimmutable in Zig.\n\n\n### How to overcome this barrier\n\nThere are some situations where you might need to change the value of your function argument\ndirectly inside the function's body. This happens more often when we are passing\nC structs as inputs to Zig functions.\n\nIn a situation like this, you can overcome this barrier by using a pointer. In other words,\ninstead of passing a value as input to the argument, you can pass a \"pointer to value\" instead.\nYou can change the value that the pointer points to, by dereferencing it.\n\nTherefore, if we take our previous `add2()` example, we can change the value of the\nfunction argument `x` inside the function's body by marking the `x` argument as a\n\"pointer to a `u32` value\" (i.e., `*u32` data type), instead of a `u32` value.\nBy making it a pointer, we can finally alter the value of this function argument directly inside\nthe body of the `add2()` function. You can see that the code example below compiles successfully.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n```\n:::\n\n\n\n\n\n```\nResult: 6\n```\n\n\nEven in this code example above, the `x` argument is still immutable. Which means that the pointer itself is immutable.\nTherefore, you cannot change the memory address that it points to. However, you can dereference the pointer\nto access the value that it points to, and also, to change this value, if you need to.\n\n\n\n\n\n## Structs and OOP {#sec-structs-and-oop}\n\nZig is a language more closely related to C (which is a procedural language),\nthan it is to C++ or Java (which are object-oriented languages). Because of that, you do not\nhave advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or\nclass inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\n\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C.\nYou give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can\nalso register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object\nthat you create with this new type, will always have these methods available and associated with them.\n\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which\nis used to construct (or, to instantiate) every object of this particular class, and we also have\na destructor method (or a destructor function), which is the function responsible for destroying\nevery object of this class.\n\nIn Zig, we normally declare the constructor and the destructor methods\nof our structs, by declaring an `init()` and a `deinit()` methods inside the struct.\nThis is just a naming convention that you will find across the entire Zig Standard Library.\nSo, in Zig, the `init()` method of a struct is normally the constructor method of the class represented by this struct.\nWhile the `deinit()` method is the method used for destroying an existing instance of that struct.\n\nThe `init()` and `deinit()` methods are both used extensively in Zig code, and you will see both of\nthem being used when we talk about allocators in @sec-allocators.\nBut, as another example, let's build a simple `User` struct to represent a user of some sort of system.\n\nIf you look at the `User` struct below, you can see the `struct` keyword.\nNotice the data members of this struct: `id`, `name` and `email`. Every data member has its\ntype explicitly annotated, with the colon character (`:`) syntax that we described earlier in @sec-root-file.\nBut also notice that every line in the struct body that describes a data member, ends with a comma character (`,`).\nSo every time you declare a data member in your Zig code, always end the line with a comma character, instead\nof ending it with the traditional semicolon character (`;`).\n\nNext, we have registered an `init()` function as a method\nof this `User` struct. This `init()` method is the constructor method that we will use to instantiate\nevery new `User` object. That is why this `init()` function returns a new `User` object as result.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    fn init(id: u64,\n            name: []const u8,\n            email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\npedro\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n### The `pub` keyword\n\nThe `pub` keyword plays an important role in struct declarations, and OOP in Zig.\nIn essence, this keyword is short for \"public\", and it makes an item/component available outside of the\nmodule where this item/component is declared. In other words, if I don't apply the `pub` keyword on\nsomething, it means that this \"something\" is available to be called/used only from within the module\nwhere this \"something\" is declared.\n\nTo demonstrate the effect of this keyword let's focus again on the `User` struct that we have\ndeclared on the previous section. For our example here, let's suppose that this `User` struct is declared inside\na Zig module named `user.zig`. If I don't use the `pub` keyword on the `User` struct, it means that I can create\nan `User` object, and call it's methods (`print_name()` and `init()`) only from within the module where the `User`\nstruct is declared, which in this case is the `user.zig` module.\n\nThis is why the previous code example works fine. Because we declare and also use the `User` struct\ninside the same module. But problems start to arise when we try to import and call/use this struct\nfrom another module. For example, if I create a new module called `register.zig`, and import the `user.zig`\nmodule into it, and try to annotate any variable with the `User` type, I get an error from the compiler.\n\n```zig\n// register.zig\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = undefined;\n    _ = u;\n}\n```\n\n```\nregister.zig:3:18: error: 'User' is not marked 'pub'\n    const u: user.User = undefined;\n             ~~~~^~~~~\nuser.zig:3:1: note: declared here\nconst User = struct {\n^~~~~\n```\n\nTherefore, if you want to use something outside of the module where this \"something\" is declared,\nyou have to mark it with the `pub` keyword. This \"something\" can be a module,\na struct, a function, an object, etc.\n\nFor our example here, if we go back to the `user.zig` module, and add the `pub` keyword\nto the `User` struct declaration, then, I can successfully compile the `register.zig` module.\n\n```zig\n// user.zig\n// Added the `pub` keyword to `User`\npub const User = struct {\n// ...\n```\n\n```zig\n// register.zig\n// This works fine now!\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = undefined;\n    _ = u;\n}\n```\n\n\nNow, what do you think it will happen if I try to actually call from `register.zig` any of the methods\nof the `User` struct? For example, if I try to call the `init()` method? The answer is: I get a similar error message,\nwarning me that the `init()` method is not marked as `pub`, as you can see below:\n\n```zig\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = user.User.init(\n        1, \"pedro\", \"email@gmail.com\"\n    );\n    _ = u;\n}\n```\n\n```\nregister.zig:3:35: error: 'init' is not marked 'pub'\n    const u: user.User = user.User.init(\n                         ~~~~~~~~~^~~~~\nuser.zig:8:5: note: declared here\n    fn init(id: u64,\n    ^~~~~~~\n```\n\nThus, just because we have applied the `pub` keyword on the struct declaration,\nthis does not make the methods of that struct public as well. If we want to use\nany method from a struct (such as the `init()` method) outside of the module\nwhere this struct is declared, we have to mark this method with the `pub` keyword\nas well.\n\nGoing back to the `user.zig` module, and marking both the `init()` and `print_name()`\nmethods with the `pub` keyword, makes them both available to the outside world, and,\nas consequence, makes the previous code example work.\n\n\n```zig\n// user.zig\n// Added the `pub` keyword to `User.init`\n    pub fn init(\n// ...\n// Added the `pub` keyword to `User.print_name`\n    pub fn print_name(self: User) !void {\n// ...\n```\n\n```zig\n// register.zig\n// This works fine now!\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = user.User.init(\n        1, \"pedro\", \"email@gmail.com\"\n    );\n    _ = u;\n}\n```\n\n\n### Anonymous struct literals {#sec-anonymous-struct-literals}\n\nYou can declare a struct object as a literal value. When we do that, we normally specify the\ndata type of this struct literal by writing its data type just before the opening curly brace.\nFor example, I could write a struct literal value of the type `User` that we have defined\nin the previous section like this:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n```\n:::\n\n\n\n\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a\nstruct literal, but not specify explicitly the type of this particular struct.\nAn anonymous struct is written by using the syntax `.{}`. So, we essentially\nreplaced the explicit type of the struct literal with a dot character (`.`).\n\nAs we described in @sec-type-inference, when you put a dot before a struct literal,\nthe type of this struct literal is automatically inferred by the `zig` compiler.\nIn essence, the `zig` compiler will look for some hint of what is the type of that struct.\nThis hint can be the type annotation of a function argument,\nor the return type annotation of the function that you are using, or the type annotation\nof an existing object.\nIf the compiler does find such type annotation, it will use this\ntype in your literal struct.\n\nAnonymous structs are very commonly used as inputs to function arguments in Zig.\nOne example that you have seen already constantly, is the `print()`\nfunction from the `stdout` object.\nThis function takes two arguments.\nThe first argument, is a template string, which should\ncontain string format specifiers in it, which tells how the values provided\nin the second argument should be printed into the message.\n\nWhile the second argument is a struct literal that lists the values\nto be printed into the template message specified in the first argument.\nYou normally want to use an anonymous struct literal here, so that the\n`zig` compiler do the job of specifying the type of this particular\nanonymous struct for you.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello, world!\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n### Struct declarations must be constant\n\nTypes in Zig must be `const` or `comptime` (we are going to talk more about comptime in @sec-comptime).\nWhat this means is that you cannot create a new data type, and mark it as variable with the `var` keyword.\nSo struct declarations are always constant. You cannot declare a new struct type using the `var` keyword.\nIt must be `const`.\n\nIn the `Vec3` example below, this declaration is allowed because I'm using the `const` keyword\nto declare this new data type.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n```\n:::\n\n\n\n\n\n\n### The `self` method argument {#sec-self-arg}\n\nIn every language that have OOP, when we declare a method of some class or struct, we\nusually declare this method as a function that has a `self` argument.\nThis `self` argument is the reference to the object itself from which the method\nis being called from.\n\nIt's not mandatory to use this `self` argument. But why would you not use this `self` argument?\nThere is no reason to not use it. Because the only way to get access to the data stored in the\ndata members of your struct is to access them through this `self` argument.\nIf you don't need to use the data in the data members of your struct inside your method, you very likely don't need\na method. You can just declare this logic as a simple function, outside of your\nstruct declaration.\n\n\nTake the `Vec3` struct below. Inside this `Vec3` struct we declared a method named `distance()`.\nThis method calculates the distance between two `Vec3` objects, by following the distance\nformula in euclidean space. Notice that this `distance()` method takes two `Vec3` objects\nas input, `self` and `other`.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n```\n:::\n\n\n\n\n\n\nThe `self` argument corresponds to the `Vec3` object from which this `distance()` method\nis being called from. While the `other` is a separate `Vec3` object that is given as input\nto this method. In the example below, the `self` argument corresponds to the object\n`v1`, because the `distance()` method is being called from the `v1` object,\nwhile the `other` argument corresponds to the object `v2`.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n```\n:::\n\n\n\n\n\n```\nDistance: 3.3970575502926055\n```\n\n\n\n### About the struct state\n\nSometimes you don't need to care about the state of your struct object. Sometimes, you just need\nto instantiate and use the objects, without altering their state. You can notice that when you have methods\ninside your struct declaration that might use the values that are present in the data members, but they\ndo not alter the values in these data members of the struct in anyway.\n\nThe `Vec3` struct that was presented in @sec-self-arg is an example of that.\nThis struct have a single method named `distance()`, and this method does use the values\npresent in all three data members of the struct (`x`, `y` and `z`). But at the same time,\nthis method does not change the values of these data members at any point.\n\nAs a result of that, when we create `Vec3` objects we usually create them as\nconstant objects, like the `v1` and `v2` objects presented in @sec-self-arg.\nWe can create them as variable objects with the `var` keyword,\nif we want to. But because the methods of this `Vec3` struct do not change\nthe state of the objects in any point, it's unnecessary to mark them\nas variable objects.\n\nBut why? Why am I talking about this here? It's because the `self` argument\nin the methods are affected depending on whether the\nmethods present in a struct change or don't change the state of the object itself.\nMore specifically, when you have a method in a struct that changes the state\nof the object (i.e., changes the value of a data member), the `self` argument\nin this method must be annotated in a different manner.\n\nAs I described in @sec-self-arg, the `self` argument in methods of\na struct is the argument that receives as input the object from which the method\nwas called from. We usually annotate this argument in the methods by writing `self`,\nfollowed by the colon character (`:`), and the data type of the struct to which\nthe method belongs to (e.g. `User`, `Vec3`, etc.).\n\nIf we take the `Vec3` struct that we defined in the previous section as an example,\nwe can see in the `distance()` method that this `self` argument is annotated as\n`self: Vec3`. Because the state of the `Vec3` object is never altered by this\nmethod.\n\nBut what if we do have a method that alters the state of the object, by altering the\nvalues of its data members, how should we annotate `self` in this instance? The answer is:\n\"we should annotate `self` as a pointer of `x`, instead of just `x`\".\nIn other words, you should annotate `self` as `self: *x`, instead of annotating it\nas `self: x`.\n\nIf we create a new method inside the `Vec3` object that, for example, expands the\nvector by multiplying its coordinates by a factor of two, then, we need to follow\nthis rule specified in the previous paragraph. The code example below demonstrates\nthis idea:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n```\n:::\n\n\n\n\n\nNotice in the code example above that we have added a new method\nto our `Vec3` struct named `twice()`. This method doubles the\ncoordinate values of our vector object. In the\ncase of the `twice()` method, we annotated the `self` argument as `*Vec3`,\nindicating that this argument receives a pointer (or a reference, if you prefer to call it this way)\nto a `Vec3` object as input.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n```\n:::\n\n\n\n\n\n```\nDoubled: 8.4\n```\n\n\n\nNow, if you change the `self` argument in this `twice()` method to `self: Vec3`, like in the\n`distance()` method, you will get the compiler error exposed below as result. Notice that this\nerror message is showing a line from the `twice()` method body,\nindicating that you cannot alter the value of the `x` data member.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n```\n:::\n\n\n\n\n\n```\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\n```\n\nThis error message indicates that the `x` data member belongs to a constant object,\nand, because of that, it cannot be changed. Ultimately, this error message\nis telling us that the `self` argument is constant.\n\nIf you take some time, and think hard about this error message, you will understand it.\nYou already have the tools to understand why we are getting this error message.\nWe have talked about it already in @sec-fun-pars.\nSo remember, every function argument is immutable in Zig, and `self`\nis no exception to this rule.\n\nIn this example, we marked the `v3` object as a variable object.\nBut this does not matter. Because it's not about the input object, it's about\nthe function argument.\n\nThe problem begins when we try to alter the value of `self` directly, which is a function argument,\nand, every function argument is immutable by default. You may ask yourself how can we overcome\nthis barrier, and once again, the solution was also discussed in @sec-fun-pars.\nWe overcome this barrier, by explicitly marking the `self` argument as a pointer.\n\n\n::: {.callout-note}\nIf a method of your `x` struct alters the state of the object, by\nchanging the value of any data member, then, remember to use `self: *x`,\ninstead of `self: x` in the function signature of this method.\n:::\n\n\nYou could also interpret the content discussed in this section as:\n\"if you need to alter the state of your `x` struct object in one of its methods,\nyou must explicitly pass the `x` struct object by reference to the `self` argument of this method\".\n\n\n\n## Type inference {#sec-type-inference}\n\nZig is a strongly typed language. But, there are some situations\nwhere you don't have to explicitly write the type of every single object in your source code,\nas you would expect from a traditional strongly typed language, such as C and C++.\n\nIn some situations, the `zig` compiler can use type inference to solve the data types for you, easing some of\nthe burden that you carry as a developer.\nThe most common way this happens is through function arguments that receive struct objects\nas input.\n\nIn general, type inference in Zig is done by using the dot character (`.`).\nEverytime you see a dot character written before a struct literal, or before an enum value, or something like that,\nyou know that this dot character is playing a special part in this place. More specifically, it's\ntelling the `zig` compiler something along the lines of: \"Hey! Can you infer the type of this\nvalue for me? Please!\". In other words, this dot character is playing a similar role as the `auto` keyword in C++.\n\nI gave you some examples of this in @sec-anonymous-struct-literals, where we used anonymous struct literals.\nAnonymous struct literals are, struct literals that use type inference to\ninfer the exact type of this particular struct literal.\nThis type inference is done by looking for some minimal hint of the correct data type to be used.\nYou could say that the `zig` compiler looks for any neighbouring type annotation that might tell it\nwhat the correct type would be.\n\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in @sec-switch).\nI also gave some other examples of type inference in @sec-switch, where we were inferring the data types of enum values listed inside\nof switch statements (e.g. `.DE`).\nBut as another example, take a look at this `fence()` function reproduced below,\nwhich comes from the [`atomic.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig)[^fence-fn]\nof the Zig Standard Library.\n\n[^fence-fn]: <https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig>.\n\nThere are a lot of things in this function that we haven't talked about yet, such as:\nwhat `comptime` means? `inline`? `extern`?\nLet's just ignore all of these things, and focus solely on the switch statement\nthat is inside this function.\n\nWe can see that this switch statement uses the `order` object as input. This `order`\nobject is one of the inputs of this `fence()` function, and we can see in the type annotation,\nthat this object is of type `AtomicOrder`. We can also see a bunch of values inside the\nswitch statements that begin with a dot character, such as `.release` and `.acquire`.\n\nBecause these weird values contain a dot character before them, we are asking the `zig`\ncompiler to infer the types of these values inside the switch statement. Then, the `zig`\ncompiler is looking into the current context where these values are being used, and trying\nto infer the types of these values.\n\nSince they are being used inside a switch statement, the `zig` compiler looks into the type\nof the input object given to the switch statement, which is the `order` object in this case.\nBecause this object have type `AtomicOrder`, the `zig` compiler infers that these values\nare data members from this type `AtomicOrder`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic => @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire => tsan.__tsan_acquire(addr),\n            .release => tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst => {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n```\n:::\n\n\n\n\n\nThis is how basic type inference is done in Zig. If we didn't use the dot character before\nthe values inside this switch statement, then, we would be forced to explicitly write\nthe data types of these values. For example, instead of writing `.release` we would have to\nwrite `AtomicOrder.release`. We would have to do this for every single value\nin this switch statement, and this is a lot of work. That is why type inference\nis commonly used on switch statements in Zig.\n\n\n\n## Type casting {#sec-type-cast}\n\nIn this section, I want to discuss type casting (or, type conversion) with you.\nWe use type casting when we have an object of type \"x\", and we want to convert\nit into an object of type \"y\", i.e., we want to change the data type of the object.\n\nMost languages have a formal way to perform type casting. In Rust for example, we normally\nuse the keyword `as`, and in C, we normally use the type casting syntax, e.g. `(int) x`.\nIn Zig, we use the `@as()` built-in function to cast an object of type \"x\", into\nan object of type \"y\".\n\nThis `@as()` function is the preferred way to perform type conversion (or type casting)\nin Zig. Because it's explicit, and, it also performs the casting only if it\nis unambiguous and safe. To use this function, you just provide the target data type\nin the first argument, and, the object that you want cast as the second argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file3fc93b4ea641.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\n\nThis is the general way to perform type casting in Zig. But remember, `@as()` works only when casting\nis unambiguous and safe. There are many situations where these assumptions do not hold. For example,\n\nwhen casting an integer value into a float value, or vice-versa, it's not clear to the compiler\nhow to perform this conversion safely.\n\nTherefore, we need to use specialized \"casting functions\" in such situations.\nFor example, if you want to cast an integer value into a float value, then, you\nshould use the `@floatFromInt()` function. In the inverse scenario, you should use\nthe `@intFromFloat()` function.\n\nIn these functions, you just provide the object that you want to\ncast as input. Then, the target data type of the \"type casting operation\" is determined by\nthe type annotation of the object where you are saving the results.\nIn the example below, we are casting the object `x` into a value of type `f32`,\nbecause the object `y`, which is where we are saving the results, is annotated\nas an object of type `f32`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file3fc91795a712.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\n\nAnother built-in function that is very useful when performing type casting operations is `@ptrCast()`.\nIn essence, we use the `@as()` built-in function when we want to explicit convert (or cast) a Zig value/object\nfrom a type \"x\" to a type \"y\", etc. However, pointers (we are going to discuss pointers\nin more depth in @sec-pointer) are a special type of object in Zig,\ni.e., they are treated differently from \"normal objects\".\n\nEverytime a pointer is involved in some \"type casting operation\" in Zig, the `@ptrCast()` function is used.\nThis function works similarly to `@floatFromInt()`.\nYou just provide the pointer object that you want to cast as input to this function, and the\ntarget data type is, once again, determined by the type annotation of the object where the results are being\nstored.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file3fc945f8b4b0.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n\n## Modules\n\nWe already talked about what modules are, and also, how to import other modules into\nyour current module via *import statements*. Every Zig module (i.e., a `.zig` file) that you write in your project\nis internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the\nZig Standard Library into our current module.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n```\n:::\n\n\n\n\n\nWhen we want to access the functions and objects from the standard library, we\nare basically accessing the data members of the struct stored in the `std`\nobject. That is why we use the same syntax that we use in normal structs, with the dot operator (`.`)\nto access the data members and methods of the struct.\n\nWhen this \"import statement\" gets executed, the result of this expression is a struct\nobject that contains the Zig Standard Library modules, global variables, functions, etc.\nAnd this struct object gets saved (or stored) inside the constant object named `std`.\n\n\nTake the [`thread_pool.zig` module from the project `zap`](https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig)[^thread]\nas an example. This module is written as if it was\na big struct. That is why we have a top-level and public `init()` method\nwritten in this module. The idea is that all top-level functions written in this\nmodule are methods from the struct, and all top-level objects and struct declarations\nare data members of this struct. The module is the struct itself.\n\n[^thread]: <https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig>\n\n\nSo you would import and use this module by doing something like this:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst ThreadPool = @import(\"thread_pool.zig\");\nconst num_cpus = std.Thread.getCpuCount()\n    catch @panic(\"failed to get cpu core count\");\nconst num_threads = std.math.cast(u16, num_cpus)\n    catch std.math.maxInt(u16);\nconst pool = ThreadPool.init(\n    .{ .max_threads = num_threads }\n);\n```\n:::\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n# Control flow, structs, modules and types\n\nWe have discussed a lot of Zig's syntax in the last chapter,\nespecially in @sec-root-file and @sec-main-file.\nBut we still need to discuss some other very important\nelements of the language. Elements that you will use constantly on your day-to-day\nroutine.\n\nWe begin this chapter by discussing the different keywords and structures\nin Zig related to control flow (e.g. loops and if statements).\nThen, we talk about structs and how they can be used to do some\nbasic Object-Oriented (OOP) patterns in Zig. We also talk about\ntype inference and type casting.\nFinally, we end this chapter by discussing modules, and how they relate\nto structs.\n\n\n\n## Control flow {#sec-zig-control-flow}\n\nSometimes, you need to make decisions in your program. Maybe you need to decide\nwhether or not to execute a specific piece of code. Or maybe,\nyou need to apply the same operation over a sequence of values. These kinds of tasks,\ninvolve using structures that are capable of changing the \"control flow\" of our program.\n\nIn computer science, the term \"control flow\" usually refers to the order in which expressions (or commands)\nare evaluated in a given language or program. But this term is also used to refer\nto structures that are capable of changing this \"evaluation order\" of the commands\nexecuted by a given language/program.\n\nThese structures are better known\nby a set of terms, such as: loops, if/else statements, switch statements, among others. So,\nloops and if/else statements are examples of structures that can change the \"control\nflow\" of our program. The keywords `continue` and `break` are also examples of symbols\nthat can change the order of evaluation, since they can move our program to the next iteration\nof a loop, or make the loop stop completely.\n\n\n### If/else statements\n\nAn if/else statement performs a \"conditional flow operation\".\nA conditional flow control (or choice control) allows you to execute\nor ignore a certain block of commands based on a logical condition.\nMany programmers and computer science professionals also use\nthe term \"branching\" in this case.\nIn essence, an if/else statement allow us to use the result of a logical test\nto decide whether or not to execute a given block of commands.\n\nIn Zig, we write if/else statements by using the keywords `if` and `else`.\nWe start with the `if` keyword followed by a logical test inside a pair\nof parentheses, followed by a pair of curly braces which contains the lines\nof code to be executed in case the logical test returns the value `true`.\n\nAfter that, you can optionally add an `else` statement. To do that, just add the `else`\nkeyword followed by a pair of curly braces, with the lines of code\nto executed in case the logical test defined at `if` returns `false`.\n\nIn the example below, we are testing if the object `x` contains a number\nthat is greater than 10. Judging by the output printed to the console,\nwe know that this logical test returned `false`. Because the output\nin the console is compatible with the line of code present in the\n`else` branch of the if/else statement.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x = 5;\nif (x > 10) {\n    try stdout.print(\n        \"x > 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x <= 10!\\n\", .{}\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nx <= 10!\n```\n\n\n:::\n:::\n\n\n\n\n### Switch statements {#sec-switch}\n\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust.\nAs you would expect, to write a switch statement in Zig we use the `switch` keyword.\nWe provide the value that we want to \"switch over\" inside a\npair of parentheses. Then, we list the possible combinations (or \"branches\")\ninside a pair of curly braces.\n\nLet's take a look at the code example below. You can see that\nI'm creating an enum type called `Role`. We talk more about enums in @sec-enum.\nBut in summary, this `Role` type is listing different types of roles in a fictitious\ncompany, like `SE` for Software Engineer, `DE` for Data Engineer, `PM` for Product Manager,\netc.\n\nNotice that we are using the value from the `role` object in the\nswitch statement, to discover which exact area we need to store in the `area` variable object.\nAlso notice that we are using type inference inside the switch statement, with the dot character,\nas we are going to describe in @sec-type-inference.\nThis makes the `zig` compiler infer the correct data type of the values (`PM`, `SE`, etc.) for us.\n\nAlso notice that, we are grouping multiple values in the same branch of the switch statement.\nWe just separate each possible value with a comma. For example, if `role` contains either `DE` or `DA`,\nthe `area` variable would contain the value `\"Data & Analytics\"`, instead of `\"Platform\"` or `\"Sales\"`.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO => {\n            area = \"Platform\";\n        },\n        .DE, .DA => {\n            area = \"Data & Analytics\";\n        },\n        .KS => {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nPlatform\n```\n\n\n:::\n:::\n\n\n\n#### Switch statements must exhaust all possibilities\n\nOne very important aspect about switch statements in Zig\nis that they must exhaust all existing possibilities.\nIn other words, all possible values that could be found inside the `role`\nobject must be explicitly handled in this switch statement.\n\nSince the `role` object has type `Role`, the only possible values to\nbe found inside this object are `PM`, `SE`, `DPE`, `PO`, `DE`, `DA` and `KS`.\nThere are no other possible values to be stored in this `role` object.\nThus, the switch statements must have a combination (branch) for each one of these values.\nThis is what \"exhaust all existing possibilities\" means. The switch statement covers\nevery possible case.\n\nTherefore, you cannot write a switch statement in Zig, and leave an edge case\nwith no explicit action to be taken.\nThis is a similar behaviour to switch statements in Rust, which also have to\nhandle all possible cases.\n\n\n\n#### The else branch\n\nTake a look at the `dump_hex_fallible()` function below as an example. This function\ncomes from the Zig Standard Library. More precisely, from the\n[`debug.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/debug.zig)[^debug-mod].\nThere are multiple lines in this function, but I omitted them to focus solely on the\nswitch statement found in this function. Notice that this switch statement has four\npossible cases (i.e., four explicit branches). Also, notice that we used an `else` branch\nin this case.\n\nAn `else` branch in a switch statement works as the \"default branch\".\nWhenever you have multiple cases in your switch statement where\nyou want to apply the exact same action, you can use an `else` branch to do that.\n\n[^debug-mod]: <https://github.com/ziglang/zig/blob/master/lib/std/debug.zig>\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' => try writer.writeAll(\"␊\"),\n        '\\r' => try writer.writeAll(\"␍\"),\n        '\\t' => try writer.writeAll(\"␉\"),\n        else => try writer.writeByte('.'),\n    }\n}\n```\n:::\n\n\nMany programmers would also use an `else` branch to handle a \"not supported\" case.\nThat is, a case that cannot be properly handled by your code, or, just a case that\nshould not be \"fixed\". Therefore, you can use an `else` branch to panic (or raise an error)\nin your program to stop the current execution.\n\nTake the code example below. We can see that, we are handling the cases\nfor the `level` object being either 1, 2, or 3. All other possible cases are not supported by default,\nand, as consequence, we raise a runtime error in such cases through the `@panic()` built-in function.\n\nAlso notice that, we are assigning the result of the switch statement to a new object called `category`.\nThis is another thing that you can do with switch statements in Zig. If a branch\noutputs a value as result, you can store the result value of the switch statement into\na new object.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 => \"beginner\",\n    3 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n:::\n\n\n```\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n```\n\n\n\n#### Using ranges in switch\n\nFurthermore, you can also use ranges of values in switch statements.\nThat is, you can create a branch in your switch statement that is used\nwhenever the input value is within the specified range. These \"range expressions\"\nare created with the operator `...`. It's important\nto emphasize that the ranges created by this operator are\ninclusive on both ends.\n\nFor example, I could easily change the previous code example to support all\nlevels between 0 and 100. Like this:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 => \"beginner\",\n    26...75 => \"intermediary\",\n    76...100 => \"professional\",\n    else => {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nbeginner\n```\n\n\n:::\n:::\n\n\nThis is neat, and it works with character ranges too. That is, I could\nsimply write `'a'...'z'`, to match any character value that is a\nlowercase letter, and it would work fine.\n\n\n#### Labeled switch statements\n\nIn @sec-blocks we have talked about labeling blocks, and also, about using these labels\nto return a value from the block. Well, from version 0.14.0 and onwards of the `zig` compiler,\nyou can also apply labels over switch statements, which makes it possible to almost implement a\n\"C `goto`\" like pattern.\n\nFor example, if you give the label `xsw` to a switch statement, you can use this\nlabel in conjunction with the `continue` keyword to go back to the beginning of the switch\nstatement. In the example below, the execution goes back to the beginning of the\nswitch statement two times, before ending at the `3` branch.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nxsw: switch (@as(u8, 1)) {\n    1 => {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 => continue :xsw 3,\n    3 => return,\n    4 => {},\n    else => {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n```\n:::\n\n\n\n### The `defer` keyword {#sec-defer}\n\nZig has a `defer` keyword, which plays a very important role in control flow, and also, in releasing resources.\nIn summary, the `defer` keyword allows you to register an expression to be executed when you exit the current scope.\n\nAt this point, you might attempt to compare the Zig `defer` keyword to it's sibling in the Go language\n(i.e. [Go also has a `defer` keyword](https://go.dev/tour/flowcontrol/12)).\nHowever, the Go `defer` keyword behaves slightly different\nthan it's sibling in Zig. More specifically, the `defer` keyword in Go always move an expression to be\nexecuted at the **exit of the current function**.\n\nIf you think deeply about this statement, you will notice that the \"exit of the current function\" is something\nslightly different than the \"exit of the current scope\". So, just be careful when comparing the two\nkeywords together. A single function in Zig might contain many different scopes inside of it, and, therefore,\nthe `defer` input expression might be executed at different places of the function, depending on which scope you\nare currently in.\n\nAs a first example, consider the `foo()` function exposed below. When we execute this `foo()` function, the expression\nthat prints the message \"Exiting function ...\" is getting executed only when the function exits\nits scope.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n```\n:::\n\n\n```\nAdding some numbers ...\nMultiplying ...\nExiting function ...\n```\n\nTherefore, we can use `defer` to declare an expression that is going to be executed\nwhen your code exits the current scope. Some programmers like to interpret the phrase \"exit of the current scope\"\nas \"the end of the current scope\". But this interpretation might not be entirely correct, depending\non what you consider as \"the end of the current scope\".\n\nI mean, what do you consider as **the end** of the current scope? Is it the closing curly bracket (`}`) of the scope?\nIs it when the last expression in the function gets executed? Is it when the function returns to the previous scope?\nEtc. For example, it would not be correct to interpret the \"exit of the current scope\" as the closing\ncurly bracket of the scope. Because the function might exit from an earlier position than this\nclosing curly bracket (e.g. an error value was generated at a previous line inside the function;\nthe function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\n\nNow, if you remember of what we have discussed in @sec-blocks, there are multiple structures in the language\nthat create their own separate scopes. For/while loops, if/else statements,\nfunctions, normal blocks, etc. This also affects the interpretation of `defer`.\nFor example, if you use `defer` inside a for loop, then, the given expression\nwill be executed everytime this specific for loop exits its own scope.\n\nBefore we continue, it's worth emphasizing that the `defer` keyword is an \"unconditional defer\".\nWhich means that the given expression will be executed no matter how the code exits\nthe current scope. For example, your code might exit the current scope because of an error value\nbeing generated, or, because of a return statement, or, a break statement, etc.\n\n\n\n### The `errdefer` keyword {#sec-errdefer1}\n\nOn the previous section, we have discussed the `defer` keyword, which you can use to\nregister an expression to be executed at the exit of the current scope.\nBut this keyword has a brother, which is the `errdefer` keyword. While `defer`\nis an \"unconditional defer\", the `errdefer` keyword is a \"conditional defer\".\nWhich means that the given expression is executed only when you exit the current\nscope on a very specific circumstance.\n\nIn more details, the expression given to `errdefer` is executed only when an error occurs in the current scope.\nTherefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope\nin a normal situation, without errors, the expression given to `errdefer` is not executed.\n\nThis makes the `errdefer` keyword one of the many tools available in Zig for error handling.\nIn this section, we are more concerned with the control flow aspects around `errdefer`.\nBut we are going to discuss `errdefer` later as a error handling tool in @sec-errdefer2.\n\nThe code example below demonstrates three things:\n\n- that `defer` is an \"unconditional defer\", because the given expression gets executed regardless of how the function `foo()` exits its own scope.\n- that `errdefer` is executed because the function `foo()` returned an error value.\n- that `defer` and `errdefer` expressions are executed in a LIFO (*last in, first out*) order.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n```\n:::\n\n\n```\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\nWhen I say that \"defer expressions\" are executed in a LIFO order, what I want to say is that\nthe last `defer` or `errdefer` expressions in the code are the first ones to be executed.\nYou could also interpret this as: \"defer expressions\" are executed from bottom to top, or,\nfrom last to first.\n\nTherefore, if I change the order of the `defer` and `errdefer` expressions, you will notice that\nthe value of `i` that gets printed to the console changes to 1. This doesn't mean that the\n`defer` expression was not executed in this case. This actually means that the `defer` expression\nwas executed only after the `errdefer` expression. The code example below demonstrates this:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n```\n:::\n\n\n```\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n```\n\n\n\n\n### For loops\n\nA loop allows you to execute the same lines of code multiple times,\nthus, creating a \"repetition space\" in the execution flow of your program.\nLoops are particularly useful when we want to replicate the same function\n(or the same set of commands) over different inputs.\n\nThere are different types of loops available in Zig. But the most\nessential of them all is probably the *for loop*. A for loop is\nused to apply the same piece of code over the elements of a slice, or, an array.\n\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from\nother languages. You start with the `for` keyword, then, you\nlist the items that you want to iterate\nover inside a pair of parentheses. Then, inside of a pair of pipes (`|`)\nyou should declare an identifier that will serve as your iterator, or,\nthe \"repetition index of the loop\".\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (items) |value| {\n    // code to execute\n}\n```\n:::\n\n\nTherefore, instead of using a `(value in items)` syntax,\nin Zig, for loops use the syntax `(items) |value|`. In the example\nbelow, you can see that we are looping through the items\nof the array stored at the object `name`, and printing to the\nconsole the decimal representation of each character in this array.\n\nIf we wanted, we could also iterate through a slice (or a portion) of\nthe array, instead of iterating through the entire array stored in the `name` object.\nJust use a range selector to select the section you want. For example,\nI could provide the expression `name[0..3]` to the for loop, to iterate\njust through the first 3 elements in the array.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n80 | 101 | 100 | 114 | 111 | \n```\n\n\n:::\n:::\n\n\nIn the above example we are using the value itself of each\nelement in the array as our iterator. But there are many situations where\nwe need to use an index instead of the actual values of the items.\n\nYou can do that by providing a second set of items to iterate over.\nMore precisely, you provide the range selector `0..` to the for loop. So,\nyes, you can use two different iterators at the same time in a for\nloop in Zig.\n\nBut remember from @sec-assignments that, every object\nyou create in Zig must be used in some way. So if you declare two iterators\nin your for loop, you must use both iterators inside the for loop body.\nBut if you want to use just the index iterator, and not use the \"value iterator\",\nthen, you can discard the value iterator by maching the\nvalue items to the underscore character, like in the example below:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n:::\n\n\n```\n0 | 1 | 2 | 3 | 4 |\n```\n\n\n### While loops\n\nA while loop is created from the `while` keyword. A `for` loop\niterates through the items of an array, but a `while` loop\nwill loop continuously, and infinitely, until a logical test\n(specified by you) becomes false.\n\nYou start with the `while` keyword, then, you define a logical\nexpression inside a pair of parentheses, and the body of the\nloop is provided inside a pair of curly braces, like in the example below:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\nYou can also specify the increment expression to be used at the beginning of a while loop.\nTo do that, we write the increment expression inside a pair of parentheses after a colon character (`:`).\nThe code example below demonstrates this other pattern.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: u8 = 1;\nwhile (i < 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 2 | 3 | 4 | \n```\n\n\n:::\n:::\n\n\n### Using `break` and `continue`\n\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using\nthe keywords `break` and `continue`, respectively. The `while` loop presented in the next code example is,\nat first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to `true`.\nBut what makes this `while` loop stop when the `i` object reaches the count\n10? It's the `break` keyword!\n\nInside the while loop, we have an if statement that is constantly checking if the `i` variable\nis equal to 10. Since we are incrementing the value of `i` at each iteration of the\nwhile loop, this `i` object will eventually be equal to 10, and when it is, the if statement\nwill execute the `break` expression, and, as a result, the execution of the while loop is stopped.\n\nNotice the use of the `expect()` function from the Zig Standard Library after the while loop.\nThis `expect()` function is an \"assert\" type of function.\nThis function checks if the logical test provided is equal to true. If so, the function do nothing.\nOtherwise (i.e., the logical test is equal to false), the function raises an assertion error.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nEverything worked!\n```\n\n\n:::\n:::\n\n\nSince this code example was executed successfully by the `zig` compiler,\nwithout raising any errors, we known that, after the execution of the while loop,\nthe `i` object is equal to 10. Because if it wasn't equal to 10, an error would have\nbeen raised by `expect()`.\n\nNow, in the next example, we have a use case for\nthe `continue` keyword. The if statement is constantly\nchecking if the current index is a multiple of 2. If\nit is, we jump to the next iteration of the loop.\nOtherwise, the loop just prints the current index to the console.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1 | 3 | 5 | \n```\n\n\n:::\n:::\n\n\n\n\n## Function parameters are immutable {#sec-fun-pars}\n\nWe have already discussed a lot of the syntax behind function declarations in @sec-root-file and @sec-main-file.\nBut I want to emphasize a curious fact about function parameters (a.k.a. function arguments) in Zig.\nIn summary, function parameters are immutable in Zig.\n\nTake the code example below, where we declare a simple function that just tries to add\nsome amount to the input integer, and returns the result back. If you look closely\nat the body of this `add2()` function, you will notice that we try\nto save the result back into the `x` function argument.\n\nIn other words, this function not only uses the value that it received through the function argument\n`x`, but it also tries to change the value of this function argument, by assigning the addition result\ninto `x`. However, function arguments in Zig are immutable. You cannot change their values, or, you\ncannot assign values to them inside the body's function.\n\nThis is the reason why, the code example below does not compile successfully. If you try to compile\nthis code example, you will get a compile error message about \"trying to change the value of a\nimmutable (i.e., constant) object\".\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: u32) u32 {\n    x = x + 2;\n    return x;\n}\n\npub fn main() !void {\n    const y = add2(4);\n    std.debug.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n```\nt.zig:3:5: error: cannot assign to constant\n    x = x + 2;\n    ^\n```\n\n\n### A free optimization\n\nIf a function argument receives as input an object whose data type is\nany of the primitive types that we have listed in @sec-primitive-data-types,\nthis object is always passed by value to the function. In other words, this object\nis copied into the function stack frame.\n\nHowever, if the input object have a more complex data type, for example, it might\nbe a struct instance, or an array, or an union value, etc., in cases like that, the `zig` compiler\nwill take the liberty of deciding for you which strategy is best. Thus, the `zig` compiler will\npass your object to the function either by value, or by reference. The compiler will always\nchoose the strategy that is faster for you.\nThis optimization that you get for free is possible only because function arguments are\nimmutable in Zig.\n\n\n### How to overcome this barrier\n\nThere are some situations where you might need to change the value of your function argument\ndirectly inside the function's body. This happens more often when we are passing\nC structs as inputs to Zig functions.\n\nIn a situation like this, you can overcome this barrier by using a pointer. In other words,\ninstead of passing a value as input to the argument, you can pass a \"pointer to value\" instead.\nYou can change the value that the pointer points to, by dereferencing it.\n\nTherefore, if we take our previous `add2()` example, we can change the value of the\nfunction argument `x` inside the function's body by marking the `x` argument as a\n\"pointer to a `u32` value\" (i.e., `*u32` data type), instead of a `u32` value.\nBy making it a pointer, we can finally alter the value of this function argument directly inside\nthe body of the `add2()` function. You can see that the code example below compiles successfully.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn add2(x: *u32) void {\n    const d: u32 = 2;\n    x.* = x.* + d;\n}\n\npub fn main() !void {\n    var x: u32 = 4;\n    add2(&x);\n    std.debug.print(\"Result: {d}\\n\", .{x});\n}\n```\n:::\n\n\n```\nResult: 6\n```\n\n\nEven in this code example above, the `x` argument is still immutable. Which means that the pointer itself is immutable.\nTherefore, you cannot change the memory address that it points to. However, you can dereference the pointer\nto access the value that it points to, and also, to change this value, if you need to.\n\n\n\n\n\n## Structs and OOP {#sec-structs-and-oop}\n\nZig is a language more closely related to C (which is a procedural language),\nthan it is to C++ or Java (which are object-oriented languages). Because of that, you do not\nhave advanced OOP (Object-Oriented Programming) patterns available in Zig, such as classes, interfaces or\nclass inheritance. Nonetheless, OOP in Zig is still possible by using struct definitions.\n\nWith struct definitions, you can create (or define) a new data type in Zig. These struct definitions work the same way as they work in C.\nYou give a name to this new struct (or, to this new data type you are creating), then, you list the data members of this new struct. You can\nalso register functions inside this struct, and they become the methods of this particular struct (or data type), so that, every object\nthat you create with this new type, will always have these methods available and associated with them.\n\nIn C++, when we create a new class, we normally have a constructor method (or, a constructor function) which\nis used to construct (or, to instantiate) every object of this particular class, and we also have\na destructor method (or a destructor function), which is the function responsible for destroying\nevery object of this class.\n\nIn Zig, we normally declare the constructor and the destructor methods\nof our structs, by declaring an `init()` and a `deinit()` methods inside the struct.\nThis is just a naming convention that you will find across the entire Zig Standard Library.\nSo, in Zig, the `init()` method of a struct is normally the constructor method of the class represented by this struct.\nWhile the `deinit()` method is the method used for destroying an existing instance of that struct.\n\nThe `init()` and `deinit()` methods are both used extensively in Zig code, and you will see both of\nthem being used when we talk about allocators in @sec-allocators.\nBut, as another example, let's build a simple `User` struct to represent a user of some sort of system.\n\nIf you look at the `User` struct below, you can see the `struct` keyword.\nNotice the data members of this struct: `id`, `name` and `email`. Every data member has its\ntype explicitly annotated, with the colon character (`:`) syntax that we described earlier in @sec-root-file.\nBut also notice that every line in the struct body that describes a data member, ends with a comma character (`,`).\nSo every time you declare a data member in your Zig code, always end the line with a comma character, instead\nof ending it with the traditional semicolon character (`;`).\n\nNext, we have registered an `init()` function as a method\nof this `User` struct. This `init()` method is the constructor method that we will use to instantiate\nevery new `User` object. That is why this `init()` function returns a new `User` object as result.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst User = struct {\n    id: u64,\n    name: []const u8,\n    email: []const u8,\n\n    fn init(id: u64,\n            name: []const u8,\n            email: []const u8) User {\n\n        return User {\n            .id = id,\n            .name = name,\n            .email = email\n        };\n    }\n\n    fn print_name(self: User) !void {\n        try stdout.print(\"{s}\\n\", .{self.name});\n    }\n};\n\npub fn main() !void {\n    const u = User.init(1, \"pedro\", \"email@gmail.com\");\n    try u.print_name();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\npedro\n```\n\n\n:::\n:::\n\n\n\n\n### The `pub` keyword\n\nThe `pub` keyword plays an important role in struct declarations, and OOP in Zig.\nIn essence, this keyword is short for \"public\", and it makes an item/component available outside of the\nmodule where this item/component is declared. In other words, if I don't apply the `pub` keyword on\nsomething, it means that this \"something\" is available to be called/used only from within the module\nwhere this \"something\" is declared.\n\nTo demonstrate the effect of this keyword let's focus again on the `User` struct that we have\ndeclared on the previous section. For our example here, let's suppose that this `User` struct is declared inside\na Zig module named `user.zig`. If I don't use the `pub` keyword on the `User` struct, it means that I can create\nan `User` object, and call it's methods (`print_name()` and `init()`) only from within the module where the `User`\nstruct is declared, which in this case is the `user.zig` module.\n\nThis is why the previous code example works fine. Because we declare and also use the `User` struct\ninside the same module. But problems start to arise when we try to import and call/use this struct\nfrom another module. For example, if I create a new module called `register.zig`, and import the `user.zig`\nmodule into it, and try to annotate any variable with the `User` type, I get an error from the compiler.\n\n```zig\n// register.zig\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = undefined;\n    _ = u;\n}\n```\n\n```\nregister.zig:3:18: error: 'User' is not marked 'pub'\n    const u: user.User = undefined;\n             ~~~~^~~~~\nuser.zig:3:1: note: declared here\nconst User = struct {\n^~~~~\n```\n\nTherefore, if you want to use something outside of the module where this \"something\" is declared,\nyou have to mark it with the `pub` keyword. This \"something\" can be a module,\na struct, a function, an object, etc.\n\nFor our example here, if we go back to the `user.zig` module, and add the `pub` keyword\nto the `User` struct declaration, then, I can successfully compile the `register.zig` module.\n\n```zig\n// user.zig\n// Added the `pub` keyword to `User`\npub const User = struct {\n// ...\n```\n\n```zig\n// register.zig\n// This works fine now!\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = undefined;\n    _ = u;\n}\n```\n\n\nNow, what do you think it will happen if I try to actually call from `register.zig` any of the methods\nof the `User` struct? For example, if I try to call the `init()` method? The answer is: I get a similar error message,\nwarning me that the `init()` method is not marked as `pub`, as you can see below:\n\n```zig\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = user.User.init(\n        1, \"pedro\", \"email@gmail.com\"\n    );\n    _ = u;\n}\n```\n\n```\nregister.zig:3:35: error: 'init' is not marked 'pub'\n    const u: user.User = user.User.init(\n                         ~~~~~~~~~^~~~~\nuser.zig:8:5: note: declared here\n    fn init(id: u64,\n    ^~~~~~~\n```\n\nThus, just because we have applied the `pub` keyword on the struct declaration,\nthis does not make the methods of that struct public as well. If we want to use\nany method from a struct (such as the `init()` method) outside of the module\nwhere this struct is declared, we have to mark this method with the `pub` keyword\nas well.\n\nGoing back to the `user.zig` module, and marking both the `init()` and `print_name()`\nmethods with the `pub` keyword, makes them both available to the outside world, and,\nas consequence, makes the previous code example work.\n\n\n```zig\n// user.zig\n// Added the `pub` keyword to `User.init`\n    pub fn init(\n// ...\n// Added the `pub` keyword to `User.print_name`\n    pub fn print_name(self: User) !void {\n// ...\n```\n\n```zig\n// register.zig\n// This works fine now!\nconst user = @import(\"user.zig\");\npub fn main() !void {\n    const u: user.User = user.User.init(\n        1, \"pedro\", \"email@gmail.com\"\n    );\n    _ = u;\n}\n```\n\n\n### Anonymous struct literals {#sec-anonymous-struct-literals}\n\nYou can declare a struct object as a literal value. When we do that, we normally specify the\ndata type of this struct literal by writing its data type just before the opening curly brace.\nFor example, I could write a struct literal value of the type `User` that we have defined\nin the previous section like this:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst eu = User {\n    .id = 1,\n    .name = \"Pedro\",\n    .email = \"someemail@gmail.com\"\n};\n_ = eu;\n```\n:::\n\n\nHowever, in Zig, we can also write an anonymous struct literal. That is, you can write a\nstruct literal, but not specify explicitly the type of this particular struct.\nAn anonymous struct is written by using the syntax `.{}`. So, we essentially\nreplaced the explicit type of the struct literal with a dot character (`.`).\n\nAs we described in @sec-type-inference, when you put a dot before a struct literal,\nthe type of this struct literal is automatically inferred by the `zig` compiler.\nIn essence, the `zig` compiler will look for some hint of what is the type of that struct.\nThis hint can be the type annotation of a function argument,\nor the return type annotation of the function that you are using, or the type annotation\nof an existing object.\nIf the compiler does find such type annotation, it will use this\ntype in your literal struct.\n\nAnonymous structs are very commonly used as inputs to function arguments in Zig.\nOne example that you have seen already constantly, is the `print()`\nfunction from the `stdout` object.\nThis function takes two arguments.\nThe first argument, is a template string, which should\ncontain string format specifiers in it, which tells how the values provided\nin the second argument should be printed into the message.\n\nWhile the second argument is a struct literal that lists the values\nto be printed into the template message specified in the first argument.\nYou normally want to use an anonymous struct literal here, so that the\n`zig` compiler do the job of specifying the type of this particular\nanonymous struct for you.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    const stdout = std.io.getStdOut().writer();\n    try stdout.print(\"Hello, {s}!\\n\", .{\"world\"});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nHello, world!\n```\n\n\n:::\n:::\n\n\n\n\n### Struct declarations must be constant\n\nTypes in Zig must be `const` or `comptime` (we are going to talk more about comptime in @sec-comptime).\nWhat this means is that you cannot create a new data type, and mark it as variable with the `var` keyword.\nSo struct declarations are always constant. You cannot declare a new struct type using the `var` keyword.\nIt must be `const`.\n\nIn the `Vec3` example below, this declaration is allowed because I'm using the `const` keyword\nto declare this new data type.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n};\n```\n:::\n\n\n\n### The `self` method argument {#sec-self-arg}\n\nIn every language that have OOP, when we declare a method of some class or struct, we\nusually declare this method as a function that has a `self` argument.\nThis `self` argument is the reference to the object itself from which the method\nis being called from.\n\nIt's not mandatory to use this `self` argument. But why would you not use this `self` argument?\nThere is no reason to not use it. Because the only way to get access to the data stored in the\ndata members of your struct is to access them through this `self` argument.\nIf you don't need to use the data in the data members of your struct inside your method, you very likely don't need\na method. You can just declare this logic as a simple function, outside of your\nstruct declaration.\n\n\nTake the `Vec3` struct below. Inside this `Vec3` struct we declared a method named `distance()`.\nThis method calculates the distance between two `Vec3` objects, by following the distance\nformula in euclidean space. Notice that this `distance()` method takes two `Vec3` objects\nas input, `self` and `other`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n};\n```\n:::\n\n\n\nThe `self` argument corresponds to the `Vec3` object from which this `distance()` method\nis being called from. While the `other` is a separate `Vec3` object that is given as input\nto this method. In the example below, the `self` argument corresponds to the object\n`v1`, because the `distance()` method is being called from the `v1` object,\nwhile the `other` argument corresponds to the object `v2`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nconst v2 = Vec3 {\n    .x = 5.1, .y = 5.6, .z = 1.6\n};\n\nstd.debug.print(\n    \"Distance: {d}\\n\",\n    .{v1.distance(v2)}\n);\n```\n:::\n\n\n```\nDistance: 3.3970575502926055\n```\n\n\n\n### About the struct state\n\nSometimes you don't need to care about the state of your struct object. Sometimes, you just need\nto instantiate and use the objects, without altering their state. You can notice that when you have methods\ninside your struct declaration that might use the values that are present in the data members, but they\ndo not alter the values in these data members of the struct in anyway.\n\nThe `Vec3` struct that was presented in @sec-self-arg is an example of that.\nThis struct have a single method named `distance()`, and this method does use the values\npresent in all three data members of the struct (`x`, `y` and `z`). But at the same time,\nthis method does not change the values of these data members at any point.\n\nAs a result of that, when we create `Vec3` objects we usually create them as\nconstant objects, like the `v1` and `v2` objects presented in @sec-self-arg.\nWe can create them as variable objects with the `var` keyword,\nif we want to. But because the methods of this `Vec3` struct do not change\nthe state of the objects in any point, it's unnecessary to mark them\nas variable objects.\n\nBut why? Why am I talking about this here? It's because the `self` argument\nin the methods are affected depending on whether the\nmethods present in a struct change or don't change the state of the object itself.\nMore specifically, when you have a method in a struct that changes the state\nof the object (i.e., changes the value of a data member), the `self` argument\nin this method must be annotated in a different manner.\n\nAs I described in @sec-self-arg, the `self` argument in methods of\na struct is the argument that receives as input the object from which the method\nwas called from. We usually annotate this argument in the methods by writing `self`,\nfollowed by the colon character (`:`), and the data type of the struct to which\nthe method belongs to (e.g. `User`, `Vec3`, etc.).\n\nIf we take the `Vec3` struct that we defined in the previous section as an example,\nwe can see in the `distance()` method that this `self` argument is annotated as\n`self: Vec3`. Because the state of the `Vec3` object is never altered by this\nmethod.\n\nBut what if we do have a method that alters the state of the object, by altering the\nvalues of its data members, how should we annotate `self` in this instance? The answer is:\n\"we should annotate `self` as a pointer of `x`, instead of just `x`\".\nIn other words, you should annotate `self` as `self: *x`, instead of annotating it\nas `self: x`.\n\nIf we create a new method inside the `Vec3` object that, for example, expands the\nvector by multiplying its coordinates by a factor of two, then, we need to follow\nthis rule specified in the previous paragraph. The code example below demonstrates\nthis idea:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst m = std.math;\nconst Vec3 = struct {\n    x: f64,\n    y: f64,\n    z: f64,\n\n    pub fn distance(self: Vec3, other: Vec3) f64 {\n        const xd = m.pow(f64, self.x - other.x, 2.0);\n        const yd = m.pow(f64, self.y - other.y, 2.0);\n        const zd = m.pow(f64, self.z - other.z, 2.0);\n        return m.sqrt(xd + yd + zd);\n    }\n\n    pub fn twice(self: *Vec3) void {\n        self.x = self.x * 2.0;\n        self.y = self.y * 2.0;\n        self.z = self.z * 2.0;\n    }\n};\n```\n:::\n\n\nNotice in the code example above that we have added a new method\nto our `Vec3` struct named `twice()`. This method doubles the\ncoordinate values of our vector object. In the\ncase of the `twice()` method, we annotated the `self` argument as `*Vec3`,\nindicating that this argument receives a pointer (or a reference, if you prefer to call it this way)\nto a `Vec3` object as input.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar v3 = Vec3 {\n    .x = 4.2, .y = 2.4, .z = 0.9\n};\nv3.twice();\nstd.debug.print(\"Doubled: {d}\\n\", .{v3.x});\n```\n:::\n\n\n```\nDoubled: 8.4\n```\n\n\n\nNow, if you change the `self` argument in this `twice()` method to `self: Vec3`, like in the\n`distance()` method, you will get the compiler error exposed below as result. Notice that this\nerror message is showing a line from the `twice()` method body,\nindicating that you cannot alter the value of the `x` data member.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// If we change the function signature of double to:\n    pub fn twice(self: Vec3) void {\n```\n:::\n\n\n```\nt.zig:16:13: error: cannot assign to constant\n        self.x = self.x * 2.0;\n        ~~~~^~\n```\n\nThis error message indicates that the `x` data member belongs to a constant object,\nand, because of that, it cannot be changed. Ultimately, this error message\nis telling us that the `self` argument is constant.\n\nIf you take some time, and think hard about this error message, you will understand it.\nYou already have the tools to understand why we are getting this error message.\nWe have talked about it already in @sec-fun-pars.\nSo remember, every function argument is immutable in Zig, and `self`\nis no exception to this rule.\n\nIn this example, we marked the `v3` object as a variable object.\nBut this does not matter. Because it's not about the input object, it's about\nthe function argument.\n\nThe problem begins when we try to alter the value of `self` directly, which is a function argument,\nand, every function argument is immutable by default. You may ask yourself how can we overcome\nthis barrier, and once again, the solution was also discussed in @sec-fun-pars.\nWe overcome this barrier, by explicitly marking the `self` argument as a pointer.\n\n\n::: {.callout-note}\nIf a method of your `x` struct alters the state of the object, by\nchanging the value of any data member, then, remember to use `self: *x`,\ninstead of `self: x` in the function signature of this method.\n:::\n\n\nYou could also interpret the content discussed in this section as:\n\"if you need to alter the state of your `x` struct object in one of its methods,\nyou must explicitly pass the `x` struct object by reference to the `self` argument of this method\".\n\n\n\n## Type inference {#sec-type-inference}\n\nZig is a strongly typed language. But, there are some situations\nwhere you don't have to explicitly write the type of every single object in your source code,\nas you would expect from a traditional strongly typed language, such as C and C++.\n\nIn some situations, the `zig` compiler can use type inference to solve the data types for you, easing some of\nthe burden that you carry as a developer.\nThe most common way this happens is through function arguments that receive struct objects\nas input.\n\nIn general, type inference in Zig is done by using the dot character (`.`).\nEverytime you see a dot character written before a struct literal, or before an enum value, or something like that,\nyou know that this dot character is playing a special part in this place. More specifically, it's\ntelling the `zig` compiler something along the lines of: \"Hey! Can you infer the type of this\nvalue for me? Please!\". In other words, this dot character is playing a similar role as the `auto` keyword in C++.\n\nI gave you some examples of this in @sec-anonymous-struct-literals, where we used anonymous struct literals.\nAnonymous struct literals are, struct literals that use type inference to\ninfer the exact type of this particular struct literal.\nThis type inference is done by looking for some minimal hint of the correct data type to be used.\nYou could say that the `zig` compiler looks for any neighbouring type annotation that might tell it\nwhat the correct type would be.\n\nAnother common place where we use type inference in Zig is at switch statements (which we talked about in @sec-switch).\nI also gave some other examples of type inference in @sec-switch, where we were inferring the data types of enum values listed inside\nof switch statements (e.g. `.DE`).\nBut as another example, take a look at this `fence()` function reproduced below,\nwhich comes from the [`atomic.zig` module](https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig)[^fence-fn]\nof the Zig Standard Library.\n\n[^fence-fn]: <https://github.com/ziglang/zig/blob/master/lib/std/atomic.zig>.\n\nThere are a lot of things in this function that we haven't talked about yet, such as:\nwhat `comptime` means? `inline`? `extern`?\nLet's just ignore all of these things, and focus solely on the switch statement\nthat is inside this function.\n\nWe can see that this switch statement uses the `order` object as input. This `order`\nobject is one of the inputs of this `fence()` function, and we can see in the type annotation,\nthat this object is of type `AtomicOrder`. We can also see a bunch of values inside the\nswitch statements that begin with a dot character, such as `.release` and `.acquire`.\n\nBecause these weird values contain a dot character before them, we are asking the `zig`\ncompiler to infer the types of these values inside the switch statement. Then, the `zig`\ncompiler is looking into the current context where these values are being used, and trying\nto infer the types of these values.\n\nSince they are being used inside a switch statement, the `zig` compiler looks into the type\nof the input object given to the switch statement, which is the `order` object in this case.\nBecause this object have type `AtomicOrder`, the `zig` compiler infers that these values\nare data members from this type `AtomicOrder`.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub inline fn fence(self: *Self, comptime order: AtomicOrder) void {\n    // many lines of code ...\n    if (builtin.sanitize_thread) {\n        const tsan = struct {\n            extern \"c\" fn __tsan_acquire(addr: *anyopaque) void;\n            extern \"c\" fn __tsan_release(addr: *anyopaque) void;\n        };\n\n        const addr: *anyopaque = self;\n        return switch (order) {\n            .unordered, .monotonic => @compileError(\n                @tagName(order)\n                ++ \" only applies to atomic loads and stores\"\n            ),\n            .acquire => tsan.__tsan_acquire(addr),\n            .release => tsan.__tsan_release(addr),\n            .acq_rel, .seq_cst => {\n                tsan.__tsan_acquire(addr);\n                tsan.__tsan_release(addr);\n            },\n        };\n    }\n\n    return @fence(order);\n}\n```\n:::\n\n\nThis is how basic type inference is done in Zig. If we didn't use the dot character before\nthe values inside this switch statement, then, we would be forced to explicitly write\nthe data types of these values. For example, instead of writing `.release` we would have to\nwrite `AtomicOrder.release`. We would have to do this for every single value\nin this switch statement, and this is a lot of work. That is why type inference\nis commonly used on switch statements in Zig.\n\n\n\n## Type casting {#sec-type-cast}\n\nIn this section, I want to discuss type casting (or, type conversion) with you.\nWe use type casting when we have an object of type \"x\", and we want to convert\nit into an object of type \"y\", i.e., we want to change the data type of the object.\n\nMost languages have a formal way to perform type casting. In Rust for example, we normally\nuse the keyword `as`, and in C, we normally use the type casting syntax, e.g. `(int) x`.\nIn Zig, we use the `@as()` built-in function to cast an object of type \"x\", into\nan object of type \"y\".\n\nThis `@as()` function is the preferred way to perform type conversion (or type casting)\nin Zig. Because it's explicit, and, it also performs the casting only if it\nis unambiguous and safe. To use this function, you just provide the target data type\nin the first argument, and, the object that you want cast as the second argument.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file26f81ac33a52.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\nThis is the general way to perform type casting in Zig. But remember, `@as()` works only when casting\nis unambiguous and safe. There are many situations where these assumptions do not hold. For example,\n\nwhen casting an integer value into a float value, or vice-versa, it's not clear to the compiler\nhow to perform this conversion safely.\n\nTherefore, we need to use specialized \"casting functions\" in such situations.\nFor example, if you want to cast an integer value into a float value, then, you\nshould use the `@floatFromInt()` function. In the inverse scenario, you should use\nthe `@intFromFloat()` function.\n\nIn these functions, you just provide the object that you want to\ncast as input. Then, the target data type of the \"type casting operation\" is determined by\nthe type annotation of the object where you are saving the results.\nIn the example below, we are casting the object `x` into a value of type `f32`,\nbecause the object `y`, which is where we are saving the results, is annotated\nas an object of type `f32`.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file26f81f277e9b.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\nAnother built-in function that is very useful when performing type casting operations is `@ptrCast()`.\nIn essence, we use the `@as()` built-in function when we want to explicit convert (or cast) a Zig value/object\nfrom a type \"x\" to a type \"y\", etc. However, pointers (we are going to discuss pointers\nin more depth in @sec-pointer) are a special type of object in Zig,\ni.e., they are treated differently from \"normal objects\".\n\nEverytime a pointer is involved in some \"type casting operation\" in Zig, the `@ptrCast()` function is used.\nThis function works similarly to `@floatFromInt()`.\nYou just provide the pointer object that you want to cast as input to this function, and the\ntarget data type is, once again, determined by the type annotation of the object where the results are being\nstored.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file26f843ae7baf.test_0...OKAll 1 tests passed\n  d.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n## Modules\n\nWe already talked about what modules are, and also, how to import other modules into\nyour current module via *import statements*. Every Zig module (i.e., a `.zig` file) that you write in your project\nis internally stored as a struct object. Take the line exposed below as an example. In this line we are importing the\nZig Standard Library into our current module.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\n```\n:::\n\n\nWhen we want to access the functions and objects from the standard library, we\nare basically accessing the data members of the struct stored in the `std`\nobject. That is why we use the same syntax that we use in normal structs, with the dot operator (`.`)\nto access the data members and methods of the struct.\n\nWhen this \"import statement\" gets executed, the result of this expression is a struct\nobject that contains the Zig Standard Library modules, global variables, functions, etc.\nAnd this struct object gets saved (or stored) inside the constant object named `std`.\n\n\nTake the [`thread_pool.zig` module from the project `zap`](https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig)[^thread]\nas an example. This module is written as if it was\na big struct. That is why we have a top-level and public `init()` method\nwritten in this module. The idea is that all top-level functions written in this\nmodule are methods from the struct, and all top-level objects and struct declarations\nare data members of this struct. The module is the struct itself.\n\n[^thread]: <https://github.com/kprotty/zap/blob/blog/src/thread_pool.zig>\n\n\nSo you would import and use this module by doing something like this:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst ThreadPool = @import(\"thread_pool.zig\");\nconst num_cpus = std.Thread.getCpuCount()\n    catch @panic(\"failed to get cpu core count\");\nconst num_threads = std.math.cast(u16, num_cpus)\n    catch std.math.maxInt(u16);\nconst pool = ThreadPool.init(\n    .{ .max_threads = num_threads }\n);\n```\n:::\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
diff --git a/_freeze/Chapters/03-unittests/execute-results/epub.json b/_freeze/Chapters/03-unittests/execute-results/epub.json
deleted file mode 100644
index 8a67fd57..00000000
--- a/_freeze/Chapters/03-unittests/execute-results/epub.json
+++ /dev/null
@@ -1,21 +0,0 @@
-{
-  "hash": "555cc5c67a26414e89a3511dba578c1d",
-  "result": {
-    "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Unit tests {#sec-unittests}\n\nIn this chapter, I want to dive in on how unit tests are done in\nZig. We are going to talk about what is the testing workflow in Zig, and\nalso, about the `test` command from the `zig` compiler.\n\n\n## Introducing the `test` block\n\nIn Zig, unit tests are written inside a `test` declaration, or, how I prefer to call it, inside a `test` block.\nEvery `test` block is written by using the keyword `test`.\nYou can optionally use a string literal to write a label, which is responsible for identifying\nthe specific group of unit tests that you are writing inside this specific `test` block.\n\nIn the example below, we are testing if the sum of two objects (`a` and `b`)\nis equal to 4. The `expect()` function from the Zig Standard Library\nis a function that receives a logical test as input. If this logical test\nresults in `true`, then, the test passes. But if it results\nin `false`, then, the test fails.\n\nYou can write any Zig code you want inside a `test` block.\nPart of this code might be some necessary commands to setup your testing\nenvironment, or just initializing some objects that you need to use\nin your unit tests.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest \"testing simple sum\" {\n    const a: u8 = 2;\n    const b: u8 = 2;\n    try expect((a + b) == 4);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file3d7d5828b2d3.test.testing simple sum...OKA\n  All 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\nYou can have multiple `test` blocks written on the same Zig module.\nAlso, you can mix `test` blocks with your source code, with no problems\nor consequences. If you mix `test` blocks with your normal source code,\nwhen you execute the `build`, `build-exe`, `build-obj` or `build-lib` commands from the\n`zig` compiler that we exposed in @sec-compile-code, these `test` blocks are automatically\nignored by the compiler.\n\nIn other words, the `zig` compiler builds and execute your unit tests only\nwhen you ask it to. By default, the compiler always ignore `test`\nblocks written in your Zig modules. The compiler normally checks only if\nthere are any syntax errors in these `test` blocks.\n\nIf you take a look at the source code for most of the files present in the\nZig Standard Library[^zig-std-lib], you can see that the `test` blocks\nare written together with the normal source code of the library.\nYou can see this for example, at the [`array_list` module](https://github.com/ziglang/zig/blob/master/lib/std/array_list.zig)[^zig-array].\nSo, the standard that the Zig developers decided to adopt\nis to keep their unit tests together with the source code\nof the functionality that they are testing.\n\nEach programmer might have a different opinion on this.\nSome of them might prefer to keep unit tests separate from the actual\nsource code of their application. If that is your case, you can\nsimply create a separate `tests` folder in your project, and\nstart writing Zig modules that contains only unit tests (as you would normally do\non a Python project with `pytest`, for example), and everything will work fine.\nIt boils down to which is your preference here.\n\n[^zig-std-lib]: <https://github.com/ziglang/zig/tree/master/lib/std>\n[^zig-array]: <https://github.com/ziglang/zig/blob/master/lib/std/array_list.zig>\n\n\n## How to run your tests\n\nIf the `zig` compiler ignores any `test` block by default, how can\nyou compile and run your unit tests? The answer is the `test` command from\nthe `zig` compiler. By running the `zig test` command, the compiler will\nfind every instance of a `test` block in your Zig modules, and, it will\ncompile and run the unit tests that you wrote.\n\n\n```bash\nzig test simple_sum.zig\n```\n\n```\n1/1 simple_sum.test.testing simple sum... OK\nAll 1 tests passed.\n```\n\n\n## Testing memory allocations\n\nOne of the advantages of Zig is that it offers great tools\nthat help us, programmers, to avoid (but also detect) memory problems, such as\nmemory leaks and double-frees. The `defer` keyword\nis especially helpful in this regard.\n\nWhen developing your source code, you, the programmer, are responsible for making\nsure that your code does not produce such problems. However,\nyou can also use a special type of an allocator object in Zig\nthat is capable of automatically detecting such problems for you.\nThis is the `std.testing.allocator` object.\nThis allocator object offers some basic memory safety detection\nfeatures, which are capable of detecting memory leaks.\n\nAs we described in @sec-heap, to allocate memory on the heap, you need\nto use an allocator object, and your functions that use these objects to allocate memory\non the heap, should receive an allocator object as one of its inputs.\nEvery memory on the heap that you allocate using these allocator objects,\nmust also be freed using this same allocator object.\n\nSo, if you want to test the memory allocations performed by your functions,\nand make sure that you don't have problems in these allocations, you can simply\nwrite unit tests for these functions, where you provide the\n`std.testing.allocator` object as input to these functions.\n\nLook at the example below, where I'm defining a function that clearly causes\na memory leak. Because we allocate memory, but, at the same time,\nwe do not free this allocated memory at any point. So, when the function\nreturns, we lose the reference to the `buffer` object, which contains\nthe allocated memory, and, as a result, we can no longer free this memory.\n\nNotice that, inside a `test` block I execute this function with\nthe `std.testing.allocator`. The allocator object was capable\nof looking deeper in our program, and detecting the memory leak. As a result,\nthis allocator object returns an error message of \"memory leaked\", and also,\na stack trace showing the exact point where the memory was leaked.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nfn some_memory_leak(allocator: Allocator) !void {\n    const buffer = try allocator.alloc(u32, 10);\n    _ = buffer;\n    // Return without freeing the\n    // allocated memory\n}\n\ntest \"memory leak\" {\n    const allocator = std.testing.allocator;\n    try some_memory_leak(allocator);\n}\n```\n:::\n\n\n\n```\nTest [1/1] leak_memory.test.memory leak...\n    [gpa] (err): memory address 0x7c1fddf39000 leaked:\n./ZigExamples/debugging/leak_memory.zig:4:39: 0x10395f2\n    const buffer = try allocator.alloc(u32, 10);\n                                      ^\n./ZigExamples/debugging/leak_memory.zig:12:25: 0x10398ea\n    try some_memory_leak(allocator);\n\n... more stack trace\n```\n\n\n## Testing errors\n\nOne common style of unit tests are those that look for\nspecific errors in your functions. In other words, you write\na unit test that tries to assert if a specific function call\nreturns any error, or a specific type of error.\n\nIn C++ you would normally write this style of unit tests using, for example,\nthe functions `REQUIRE_THROWS()` or `CHECK_THROWS()` from the [`Catch2` test framework](https://github.com/catchorg/Catch2/tree/devel)[^catch2].\nIn the case of a Python project, you would probably use the\n[`raises()` function from `pytest`](https://docs.pytest.org/en/7.1.x/reference/reference.html#pytest-raises)[^pytest].\nWhile in Rust, you would probably use `assert_eq!()` in conjunction with `Err()`.\n\n[^pytest]: <https://docs.pytest.org/en/7.1.x/reference/reference.html#pytest-raises>\n[^catch2]: <https://github.com/catchorg/Catch2/tree/devel>\n\n\nBut in Zig, we use the `expectError()` function, from the `std.testing` module.\nWith this function, you can test if a specific function call returns the exact\ntype of error that you expect it to return. To use this function, you first write\n`try expectError()`. Then, on the first argument, you provide the type of error that you\nare expecting from the function call. Then, on the second argument, you write\nthe function call that you expect to fail.\n\nThe code example below demonstrates such type of unit test in Zig.\nNotice that, inside the function `alloc_error()` we are allocating\n100 bytes of memory, or, an array of 100 elements, for the object `ibuffer`. However,\nin the `test` block, we are using the `FixedBufferAllocator()`\nallocator object, which is limited to 10 bytes of space, because\nthe object `buffer`, which we provided to the allocator object,\nhave only 10 bytes of space.\n\nThat is why, the `alloc_error()` function raises an `OutOfMemory` error\non this case.\nBecause this function is trying to allocate more space than the allocator\nobject allows.\nSo, in essence, we are testing for a specific type of error,\nwhich is `OutOfMemory`. If the `alloc_error()` function returns any other type of error,\nthen, the `expectError()` function would make the entire test fail.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst expectError = std.testing.expectError;\nfn alloc_error(allocator: Allocator) !void {\n    var ibuffer = try allocator.alloc(u8, 100);\n    defer allocator.free(ibuffer);\n    ibuffer[0] = 2;\n}\n\ntest \"testing error\" {\n    var buffer: [10]u8 = undefined;\n    var fba = std.heap.FixedBufferAllocator.init(&buffer);\n    const allocator = fba.allocator();\n    try expectError(error.OutOfMemory, alloc_error(allocator));\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file3d7d15bc8ea0.test.testing error...OKAll 1 \n   tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n## Testing simple equalities\n\nIn Zig, there are some different ways you can test for an equality.\nYou already saw that we can use `expect()` with the logical operator `==`\nto essentially reproduce an equality test. But we also have\nsome other helper functions that you should know about, especially\n`expectEqual()`, `expectEqualSlices()` and `expectEqualStrings()`.\n\n\nThe `expectEqual()` function, as the name suggests, is a classic\ntest equality function. It receives two objects as input. The first\nobject is the value that you expect to be in the second object.\nWhile second object is the object you have, or, the object that your application\nproduced as result. So, with `expectEqual()` you are essentially\ntesting if the values stored inside these two objects\nare equal or not.\n\nYou can see in the example below that, the test performed by\n`expectEqual()` failed. Because the objects `v1` and `v2` contain\ndifferent values in them.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"values are equal?\" {\n    const v1 = 15;\n    const v2 = 18;\n    try std.testing.expectEqual(v1, v2);\n}\n```\n:::\n\n\n\n```\n1/1 ve.test.values are equal?...\n    expected 15, found 18\n    FAIL (TestExpectedEqual)\nve.zig:5:5: test.values are equal? (test)\n    try std.testing.expectEqual(v1, v2);\n    ^\n0 passed; 0 skipped; 1 failed.\n```\n\n\nAlthough useful, the `expectEqual()` function does not work with arrays.\nFor testing if two arrays are equal, you should use the `expectEqualSlices()`\nfunction instead. This function have three arguments. First, you provide\nthe data type contained in both arrays that you are trying to compare.\nWhile the second and third arguments corresponds to the array objects that you want to compare.\n\nIn the example below, we are using this function to test if two array\nobjects (`array1` and `array2`) are equal or not. Since they\nare in fact equal, the unit test passed with no errors.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"arrays are equal?\" {\n    const array1 = [3]u32{1, 2, 3};\n    const array2 = [3]u32{1, 2, 3};\n    try std.testing.expectEqualSlices(\n        u32, &array1, &array2\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file3d7d7d8ccdbb.test.arrays are equal?...OKAl\n  ll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\nAt last, you might also want to use the `expectEqualStrings()` function.\nAs the name suggests, you can use this function to test if two strings\nare equal or not. Just provide the two string objects that you want to compare,\nas inputs to the function.\n\nIf the function finds any existing differences between the two strings,\nthen, the function will raise an error, and also, print an error message\nthat shows the exact difference between the two string objects provided,\nas the example below demonstrates:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"strings are equal?\" {\n    const str1 = \"hello, world!\";\n    const str2 = \"Hello, world!\";\n    try std.testing.expectEqualStrings(\n        str1, str2\n    );\n}\n```\n:::\n\n\n\n```\n1/1 t.test.strings are equal?...\n====== expected this output: =========\nhello, world!␃\n======== instead found this: =========\nHello, world!␃\n======================================\nFirst difference occurs on line 1:\nexpected:\nhello, world!\n^ ('\\x68')\nfound:\nHello, world!\n^ ('\\x48')\n```\n",
-    "supporting": [
-      "03-unittests_files"
-    ],
-    "filters": [
-      "rmarkdown/pagebreak.lua"
-    ],
-    "includes": {},
-    "engineDependencies": {
-      "knitr": [
-        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
-      ]
-    },
-    "preserve": null,
-    "postProcess": false
-  }
-}
\ No newline at end of file
diff --git a/_freeze/Chapters/03-unittests/execute-results/html.json b/_freeze/Chapters/03-unittests/execute-results/html.json
index 7e5990dc..a6dbf076 100644
--- a/_freeze/Chapters/03-unittests/execute-results/html.json
+++ b/_freeze/Chapters/03-unittests/execute-results/html.json
@@ -2,10 +2,8 @@
   "hash": "555cc5c67a26414e89a3511dba578c1d",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Unit tests {#sec-unittests}\n\nIn this chapter, I want to dive in on how unit tests are done in\nZig. We are going to talk about what is the testing workflow in Zig, and\nalso, about the `test` command from the `zig` compiler.\n\n\n## Introducing the `test` block\n\nIn Zig, unit tests are written inside a `test` declaration, or, how I prefer to call it, inside a `test` block.\nEvery `test` block is written by using the keyword `test`.\nYou can optionally use a string literal to write a label, which is responsible for identifying\nthe specific group of unit tests that you are writing inside this specific `test` block.\n\nIn the example below, we are testing if the sum of two objects (`a` and `b`)\nis equal to 4. The `expect()` function from the Zig Standard Library\nis a function that receives a logical test as input. If this logical test\nresults in `true`, then, the test passes. But if it results\nin `false`, then, the test fails.\n\nYou can write any Zig code you want inside a `test` block.\nPart of this code might be some necessary commands to setup your testing\nenvironment, or just initializing some objects that you need to use\nin your unit tests.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest \"testing simple sum\" {\n    const a: u8 = 2;\n    const b: u8 = 2;\n    try expect((a + b) == 4);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file81c21dbf264e.test.testing simple sum...OKA\n  All 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\nYou can have multiple `test` blocks written on the same Zig module.\nAlso, you can mix `test` blocks with your source code, with no problems\nor consequences. If you mix `test` blocks with your normal source code,\nwhen you execute the `build`, `build-exe`, `build-obj` or `build-lib` commands from the\n`zig` compiler that we exposed in @sec-compile-code, these `test` blocks are automatically\nignored by the compiler.\n\nIn other words, the `zig` compiler builds and execute your unit tests only\nwhen you ask it to. By default, the compiler always ignore `test`\nblocks written in your Zig modules. The compiler normally checks only if\nthere are any syntax errors in these `test` blocks.\n\nIf you take a look at the source code for most of the files present in the\nZig Standard Library[^zig-std-lib], you can see that the `test` blocks\nare written together with the normal source code of the library.\nYou can see this for example, at the [`array_list` module](https://github.com/ziglang/zig/blob/master/lib/std/array_list.zig)[^zig-array].\nSo, the standard that the Zig developers decided to adopt\nis to keep their unit tests together with the source code\nof the functionality that they are testing.\n\nEach programmer might have a different opinion on this.\nSome of them might prefer to keep unit tests separate from the actual\nsource code of their application. If that is your case, you can\nsimply create a separate `tests` folder in your project, and\nstart writing Zig modules that contains only unit tests (as you would normally do\non a Python project with `pytest`, for example), and everything will work fine.\nIt boils down to which is your preference here.\n\n[^zig-std-lib]: <https://github.com/ziglang/zig/tree/master/lib/std>\n[^zig-array]: <https://github.com/ziglang/zig/blob/master/lib/std/array_list.zig>\n\n\n## How to run your tests\n\nIf the `zig` compiler ignores any `test` block by default, how can\nyou compile and run your unit tests? The answer is the `test` command from\nthe `zig` compiler. By running the `zig test` command, the compiler will\nfind every instance of a `test` block in your Zig modules, and, it will\ncompile and run the unit tests that you wrote.\n\n\n```bash\nzig test simple_sum.zig\n```\n\n```\n1/1 simple_sum.test.testing simple sum... OK\nAll 1 tests passed.\n```\n\n\n## Testing memory allocations\n\nOne of the advantages of Zig is that it offers great tools\nthat help us, programmers, to avoid (but also detect) memory problems, such as\nmemory leaks and double-frees. The `defer` keyword\nis especially helpful in this regard.\n\nWhen developing your source code, you, the programmer, are responsible for making\nsure that your code does not produce such problems. However,\nyou can also use a special type of an allocator object in Zig\nthat is capable of automatically detecting such problems for you.\nThis is the `std.testing.allocator` object.\nThis allocator object offers some basic memory safety detection\nfeatures, which are capable of detecting memory leaks.\n\nAs we described in @sec-heap, to allocate memory on the heap, you need\nto use an allocator object, and your functions that use these objects to allocate memory\non the heap, should receive an allocator object as one of its inputs.\nEvery memory on the heap that you allocate using these allocator objects,\nmust also be freed using this same allocator object.\n\nSo, if you want to test the memory allocations performed by your functions,\nand make sure that you don't have problems in these allocations, you can simply\nwrite unit tests for these functions, where you provide the\n`std.testing.allocator` object as input to these functions.\n\nLook at the example below, where I'm defining a function that clearly causes\na memory leak. Because we allocate memory, but, at the same time,\nwe do not free this allocated memory at any point. So, when the function\nreturns, we lose the reference to the `buffer` object, which contains\nthe allocated memory, and, as a result, we can no longer free this memory.\n\nNotice that, inside a `test` block I execute this function with\nthe `std.testing.allocator`. The allocator object was capable\nof looking deeper in our program, and detecting the memory leak. As a result,\nthis allocator object returns an error message of \"memory leaked\", and also,\na stack trace showing the exact point where the memory was leaked.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nfn some_memory_leak(allocator: Allocator) !void {\n    const buffer = try allocator.alloc(u32, 10);\n    _ = buffer;\n    // Return without freeing the\n    // allocated memory\n}\n\ntest \"memory leak\" {\n    const allocator = std.testing.allocator;\n    try some_memory_leak(allocator);\n}\n```\n:::\n\n\n\n\n```\nTest [1/1] leak_memory.test.memory leak...\n    [gpa] (err): memory address 0x7c1fddf39000 leaked:\n./ZigExamples/debugging/leak_memory.zig:4:39: 0x10395f2\n    const buffer = try allocator.alloc(u32, 10);\n                                      ^\n./ZigExamples/debugging/leak_memory.zig:12:25: 0x10398ea\n    try some_memory_leak(allocator);\n\n... more stack trace\n```\n\n\n## Testing errors\n\nOne common style of unit tests are those that look for\nspecific errors in your functions. In other words, you write\na unit test that tries to assert if a specific function call\nreturns any error, or a specific type of error.\n\nIn C++ you would normally write this style of unit tests using, for example,\nthe functions `REQUIRE_THROWS()` or `CHECK_THROWS()` from the [`Catch2` test framework](https://github.com/catchorg/Catch2/tree/devel)[^catch2].\nIn the case of a Python project, you would probably use the\n[`raises()` function from `pytest`](https://docs.pytest.org/en/7.1.x/reference/reference.html#pytest-raises)[^pytest].\nWhile in Rust, you would probably use `assert_eq!()` in conjunction with `Err()`.\n\n[^pytest]: <https://docs.pytest.org/en/7.1.x/reference/reference.html#pytest-raises>\n[^catch2]: <https://github.com/catchorg/Catch2/tree/devel>\n\n\nBut in Zig, we use the `expectError()` function, from the `std.testing` module.\nWith this function, you can test if a specific function call returns the exact\ntype of error that you expect it to return. To use this function, you first write\n`try expectError()`. Then, on the first argument, you provide the type of error that you\nare expecting from the function call. Then, on the second argument, you write\nthe function call that you expect to fail.\n\nThe code example below demonstrates such type of unit test in Zig.\nNotice that, inside the function `alloc_error()` we are allocating\n100 bytes of memory, or, an array of 100 elements, for the object `ibuffer`. However,\nin the `test` block, we are using the `FixedBufferAllocator()`\nallocator object, which is limited to 10 bytes of space, because\nthe object `buffer`, which we provided to the allocator object,\nhave only 10 bytes of space.\n\nThat is why, the `alloc_error()` function raises an `OutOfMemory` error\non this case.\nBecause this function is trying to allocate more space than the allocator\nobject allows.\nSo, in essence, we are testing for a specific type of error,\nwhich is `OutOfMemory`. If the `alloc_error()` function returns any other type of error,\nthen, the `expectError()` function would make the entire test fail.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst expectError = std.testing.expectError;\nfn alloc_error(allocator: Allocator) !void {\n    var ibuffer = try allocator.alloc(u8, 100);\n    defer allocator.free(ibuffer);\n    ibuffer[0] = 2;\n}\n\ntest \"testing error\" {\n    var buffer: [10]u8 = undefined;\n    var fba = std.heap.FixedBufferAllocator.init(&buffer);\n    const allocator = fba.allocator();\n    try expectError(error.OutOfMemory, alloc_error(allocator));\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file81c24fea00d1.test.testing error...OKAll 1 \n   tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n## Testing simple equalities\n\nIn Zig, there are some different ways you can test for an equality.\nYou already saw that we can use `expect()` with the logical operator `==`\nto essentially reproduce an equality test. But we also have\nsome other helper functions that you should know about, especially\n`expectEqual()`, `expectEqualSlices()` and `expectEqualStrings()`.\n\n\nThe `expectEqual()` function, as the name suggests, is a classic\ntest equality function. It receives two objects as input. The first\nobject is the value that you expect to be in the second object.\nWhile second object is the object you have, or, the object that your application\nproduced as result. So, with `expectEqual()` you are essentially\ntesting if the values stored inside these two objects\nare equal or not.\n\nYou can see in the example below that, the test performed by\n`expectEqual()` failed. Because the objects `v1` and `v2` contain\ndifferent values in them.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"values are equal?\" {\n    const v1 = 15;\n    const v2 = 18;\n    try std.testing.expectEqual(v1, v2);\n}\n```\n:::\n\n\n\n\n```\n1/1 ve.test.values are equal?...\n    expected 15, found 18\n    FAIL (TestExpectedEqual)\nve.zig:5:5: test.values are equal? (test)\n    try std.testing.expectEqual(v1, v2);\n    ^\n0 passed; 0 skipped; 1 failed.\n```\n\n\nAlthough useful, the `expectEqual()` function does not work with arrays.\nFor testing if two arrays are equal, you should use the `expectEqualSlices()`\nfunction instead. This function have three arguments. First, you provide\nthe data type contained in both arrays that you are trying to compare.\nWhile the second and third arguments corresponds to the array objects that you want to compare.\n\nIn the example below, we are using this function to test if two array\nobjects (`array1` and `array2`) are equal or not. Since they\nare in fact equal, the unit test passed with no errors.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"arrays are equal?\" {\n    const array1 = [3]u32{1, 2, 3};\n    const array2 = [3]u32{1, 2, 3};\n    try std.testing.expectEqualSlices(\n        u32, &array1, &array2\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file81c25513148.test.arrays are equal?...OKAll\n  l 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\nAt last, you might also want to use the `expectEqualStrings()` function.\nAs the name suggests, you can use this function to test if two strings\nare equal or not. Just provide the two string objects that you want to compare,\nas inputs to the function.\n\nIf the function finds any existing differences between the two strings,\nthen, the function will raise an error, and also, print an error message\nthat shows the exact difference between the two string objects provided,\nas the example below demonstrates:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"strings are equal?\" {\n    const str1 = \"hello, world!\";\n    const str2 = \"Hello, world!\";\n    try std.testing.expectEqualStrings(\n        str1, str2\n    );\n}\n```\n:::\n\n\n\n\n```\n1/1 t.test.strings are equal?...\n====== expected this output: =========\nhello, world!␃\n======== instead found this: =========\nHello, world!␃\n======================================\nFirst difference occurs on line 1:\nexpected:\nhello, world!\n^ ('\\x68')\nfound:\nHello, world!\n^ ('\\x48')\n```\n",
-    "supporting": [
-      "03-unittests_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n# Unit tests {#sec-unittests}\n\nIn this chapter, I want to dive in on how unit tests are done in\nZig. We are going to talk about what is the testing workflow in Zig, and\nalso, about the `test` command from the `zig` compiler.\n\n\n## Introducing the `test` block\n\nIn Zig, unit tests are written inside a `test` declaration, or, how I prefer to call it, inside a `test` block.\nEvery `test` block is written by using the keyword `test`.\nYou can optionally use a string literal to write a label, which is responsible for identifying\nthe specific group of unit tests that you are writing inside this specific `test` block.\n\nIn the example below, we are testing if the sum of two objects (`a` and `b`)\nis equal to 4. The `expect()` function from the Zig Standard Library\nis a function that receives a logical test as input. If this logical test\nresults in `true`, then, the test passes. But if it results\nin `false`, then, the test fails.\n\nYou can write any Zig code you want inside a `test` block.\nPart of this code might be some necessary commands to setup your testing\nenvironment, or just initializing some objects that you need to use\nin your unit tests.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest \"testing simple sum\" {\n    const a: u8 = 2;\n    const b: u8 = 2;\n    try expect((a + b) == 4);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file1ed835512cf8.test.testing simple sum...OKA\n  All 1 tests passed.\n```\n\n\n:::\n:::\n\n\nYou can have multiple `test` blocks written on the same Zig module.\nAlso, you can mix `test` blocks with your source code, with no problems\nor consequences. If you mix `test` blocks with your normal source code,\nwhen you execute the `build`, `build-exe`, `build-obj` or `build-lib` commands from the\n`zig` compiler that we exposed in @sec-compile-code, these `test` blocks are automatically\nignored by the compiler.\n\nIn other words, the `zig` compiler builds and execute your unit tests only\nwhen you ask it to. By default, the compiler always ignore `test`\nblocks written in your Zig modules. The compiler normally checks only if\nthere are any syntax errors in these `test` blocks.\n\nIf you take a look at the source code for most of the files present in the\nZig Standard Library[^zig-std-lib], you can see that the `test` blocks\nare written together with the normal source code of the library.\nYou can see this for example, at the [`array_list` module](https://github.com/ziglang/zig/blob/master/lib/std/array_list.zig)[^zig-array].\nSo, the standard that the Zig developers decided to adopt\nis to keep their unit tests together with the source code\nof the functionality that they are testing.\n\nEach programmer might have a different opinion on this.\nSome of them might prefer to keep unit tests separate from the actual\nsource code of their application. If that is your case, you can\nsimply create a separate `tests` folder in your project, and\nstart writing Zig modules that contains only unit tests (as you would normally do\non a Python project with `pytest`, for example), and everything will work fine.\nIt boils down to which is your preference here.\n\n[^zig-std-lib]: <https://github.com/ziglang/zig/tree/master/lib/std>\n[^zig-array]: <https://github.com/ziglang/zig/blob/master/lib/std/array_list.zig>\n\n\n## How to run your tests\n\nIf the `zig` compiler ignores any `test` block by default, how can\nyou compile and run your unit tests? The answer is the `test` command from\nthe `zig` compiler. By running the `zig test` command, the compiler will\nfind every instance of a `test` block in your Zig modules, and, it will\ncompile and run the unit tests that you wrote.\n\n\n```bash\nzig test simple_sum.zig\n```\n\n```\n1/1 simple_sum.test.testing simple sum... OK\nAll 1 tests passed.\n```\n\n\n## Testing memory allocations\n\nOne of the advantages of Zig is that it offers great tools\nthat help us, programmers, to avoid (but also detect) memory problems, such as\nmemory leaks and double-frees. The `defer` keyword\nis especially helpful in this regard.\n\nWhen developing your source code, you, the programmer, are responsible for making\nsure that your code does not produce such problems. However,\nyou can also use a special type of an allocator object in Zig\nthat is capable of automatically detecting such problems for you.\nThis is the `std.testing.allocator` object.\nThis allocator object offers some basic memory safety detection\nfeatures, which are capable of detecting memory leaks.\n\nAs we described in @sec-heap, to allocate memory on the heap, you need\nto use an allocator object, and your functions that use these objects to allocate memory\non the heap, should receive an allocator object as one of its inputs.\nEvery memory on the heap that you allocate using these allocator objects,\nmust also be freed using this same allocator object.\n\nSo, if you want to test the memory allocations performed by your functions,\nand make sure that you don't have problems in these allocations, you can simply\nwrite unit tests for these functions, where you provide the\n`std.testing.allocator` object as input to these functions.\n\nLook at the example below, where I'm defining a function that clearly causes\na memory leak. Because we allocate memory, but, at the same time,\nwe do not free this allocated memory at any point. So, when the function\nreturns, we lose the reference to the `buffer` object, which contains\nthe allocated memory, and, as a result, we can no longer free this memory.\n\nNotice that, inside a `test` block I execute this function with\nthe `std.testing.allocator`. The allocator object was capable\nof looking deeper in our program, and detecting the memory leak. As a result,\nthis allocator object returns an error message of \"memory leaked\", and also,\na stack trace showing the exact point where the memory was leaked.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nfn some_memory_leak(allocator: Allocator) !void {\n    const buffer = try allocator.alloc(u32, 10);\n    _ = buffer;\n    // Return without freeing the\n    // allocated memory\n}\n\ntest \"memory leak\" {\n    const allocator = std.testing.allocator;\n    try some_memory_leak(allocator);\n}\n```\n:::\n\n\n```\nTest [1/1] leak_memory.test.memory leak...\n    [gpa] (err): memory address 0x7c1fddf39000 leaked:\n./ZigExamples/debugging/leak_memory.zig:4:39: 0x10395f2\n    const buffer = try allocator.alloc(u32, 10);\n                                      ^\n./ZigExamples/debugging/leak_memory.zig:12:25: 0x10398ea\n    try some_memory_leak(allocator);\n\n... more stack trace\n```\n\n\n## Testing errors\n\nOne common style of unit tests are those that look for\nspecific errors in your functions. In other words, you write\na unit test that tries to assert if a specific function call\nreturns any error, or a specific type of error.\n\nIn C++ you would normally write this style of unit tests using, for example,\nthe functions `REQUIRE_THROWS()` or `CHECK_THROWS()` from the [`Catch2` test framework](https://github.com/catchorg/Catch2/tree/devel)[^catch2].\nIn the case of a Python project, you would probably use the\n[`raises()` function from `pytest`](https://docs.pytest.org/en/7.1.x/reference/reference.html#pytest-raises)[^pytest].\nWhile in Rust, you would probably use `assert_eq!()` in conjunction with `Err()`.\n\n[^pytest]: <https://docs.pytest.org/en/7.1.x/reference/reference.html#pytest-raises>\n[^catch2]: <https://github.com/catchorg/Catch2/tree/devel>\n\n\nBut in Zig, we use the `expectError()` function, from the `std.testing` module.\nWith this function, you can test if a specific function call returns the exact\ntype of error that you expect it to return. To use this function, you first write\n`try expectError()`. Then, on the first argument, you provide the type of error that you\nare expecting from the function call. Then, on the second argument, you write\nthe function call that you expect to fail.\n\nThe code example below demonstrates such type of unit test in Zig.\nNotice that, inside the function `alloc_error()` we are allocating\n100 bytes of memory, or, an array of 100 elements, for the object `ibuffer`. However,\nin the `test` block, we are using the `FixedBufferAllocator()`\nallocator object, which is limited to 10 bytes of space, because\nthe object `buffer`, which we provided to the allocator object,\nhave only 10 bytes of space.\n\nThat is why, the `alloc_error()` function raises an `OutOfMemory` error\non this case.\nBecause this function is trying to allocate more space than the allocator\nobject allows.\nSo, in essence, we are testing for a specific type of error,\nwhich is `OutOfMemory`. If the `alloc_error()` function returns any other type of error,\nthen, the `expectError()` function would make the entire test fail.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst expectError = std.testing.expectError;\nfn alloc_error(allocator: Allocator) !void {\n    var ibuffer = try allocator.alloc(u8, 100);\n    defer allocator.free(ibuffer);\n    ibuffer[0] = 2;\n}\n\ntest \"testing error\" {\n    var buffer: [10]u8 = undefined;\n    var fba = std.heap.FixedBufferAllocator.init(&buffer);\n    const allocator = fba.allocator();\n    try expectError(error.OutOfMemory, alloc_error(allocator));\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file1ed878d2d839.test.testing error...OKAll 1 \n   tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n## Testing simple equalities\n\nIn Zig, there are some different ways you can test for an equality.\nYou already saw that we can use `expect()` with the logical operator `==`\nto essentially reproduce an equality test. But we also have\nsome other helper functions that you should know about, especially\n`expectEqual()`, `expectEqualSlices()` and `expectEqualStrings()`.\n\n\nThe `expectEqual()` function, as the name suggests, is a classic\ntest equality function. It receives two objects as input. The first\nobject is the value that you expect to be in the second object.\nWhile second object is the object you have, or, the object that your application\nproduced as result. So, with `expectEqual()` you are essentially\ntesting if the values stored inside these two objects\nare equal or not.\n\nYou can see in the example below that, the test performed by\n`expectEqual()` failed. Because the objects `v1` and `v2` contain\ndifferent values in them.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"values are equal?\" {\n    const v1 = 15;\n    const v2 = 18;\n    try std.testing.expectEqual(v1, v2);\n}\n```\n:::\n\n\n```\n1/1 ve.test.values are equal?...\n    expected 15, found 18\n    FAIL (TestExpectedEqual)\nve.zig:5:5: test.values are equal? (test)\n    try std.testing.expectEqual(v1, v2);\n    ^\n0 passed; 0 skipped; 1 failed.\n```\n\n\nAlthough useful, the `expectEqual()` function does not work with arrays.\nFor testing if two arrays are equal, you should use the `expectEqualSlices()`\nfunction instead. This function have three arguments. First, you provide\nthe data type contained in both arrays that you are trying to compare.\nWhile the second and third arguments corresponds to the array objects that you want to compare.\n\nIn the example below, we are using this function to test if two array\nobjects (`array1` and `array2`) are equal or not. Since they\nare in fact equal, the unit test passed with no errors.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"arrays are equal?\" {\n    const array1 = [3]u32{1, 2, 3};\n    const array2 = [3]u32{1, 2, 3};\n    try std.testing.expectEqualSlices(\n        u32, &array1, &array2\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file1ed83cbad6df.test.arrays are equal?...OKAl\n  ll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\nAt last, you might also want to use the `expectEqualStrings()` function.\nAs the name suggests, you can use this function to test if two strings\nare equal or not. Just provide the two string objects that you want to compare,\nas inputs to the function.\n\nIf the function finds any existing differences between the two strings,\nthen, the function will raise an error, and also, print an error message\nthat shows the exact difference between the two string objects provided,\nas the example below demonstrates:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\ntest \"strings are equal?\" {\n    const str1 = \"hello, world!\";\n    const str2 = \"Hello, world!\";\n    try std.testing.expectEqualStrings(\n        str1, str2\n    );\n}\n```\n:::\n\n\n```\n1/1 t.test.strings are equal?...\n====== expected this output: =========\nhello, world!␃\n======== instead found this: =========\nHello, world!␃\n======================================\nFirst difference occurs on line 1:\nexpected:\nhello, world!\n^ ('\\x68')\nfound:\nHello, world!\n^ ('\\x48')\n```\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/04-http-server/execute-results/epub.json b/_freeze/Chapters/04-http-server/execute-results/epub.json
deleted file mode 100644
index ddf9953a..00000000
--- a/_freeze/Chapters/04-http-server/execute-results/epub.json
+++ /dev/null
@@ -1,21 +0,0 @@
-{
-  "hash": "f64c88659b4b19943ce530d1245b8add",
-  "result": {
-    "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Project 2 - Building a HTTP Server from scratch\n\nIn this chapter, I want to implement a new\nsmall project with you. This time, we are going\nto implement a basic HTTP Server from scratch.\n\nThe Zig Standard Library already have a HTTP Server\nimplemented, which is available at `std.http.Server`.\nBut again, our objective here in this chapter, is to implement\nit **from scratch**. So we can't use this server object available\nfrom the Zig Standard Library.\n\n## What is a HTTP Server?\n\nFirst of all, what is a HTTP Server?\nA HTTP server, as any other type of server, is essentially\na program that runs indefinitely, on an infinite loop, waiting for incoming connections\nfrom clients. Once the server receives an incoming connection, it will\naccept this connection, and it will send messages back-and-forth to the client\nthrough this connection.\n\nBut the messages that are transmitted inside this connection are in a\nspecific format. They are HTTP messages\n(i.e., messages that use the HTTP Protocol specification).\nThe HTTP Protocol is the backbone of the modern web.\nThe world wide web as we know it today, would not exist without the\nHTTP Protocol.\n\nSo, Web servers (which is just a fancy name to\nHTTP Servers) are servers that exchange HTTP messages with clients.\nAnd these HTTP servers and the HTTP Protocol specification\nare essential to the operation of the world wide web today.\n\nThat is the whole picture of the process.\nAgain, we have two subjects involved here, a server (which is\na program that is running indefinitely, waiting to receive incoming connections),\nand a client (which is someone that wants to connect to the server,\nand exchange HTTP messages with it).\n\nYou may find the material about the [HTTP Protocol available at the Mozilla MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview)[^mdn-http]\n, a great resource for you to also look at. It gives you a great overview on how\nHTTP works, and what role the server plays in this matter.\n\n[^mdn-http]: <https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview>.\n\n\n## How a HTTP Server works? {#sec-how-http-works}\n\nImagine a HTTP Server as if it were the receptionist of a large hotel. In a hotel,\nyou have a reception, and inside that reception there is a receptionist\nwaiting for customers to arrive. A HTTP Server is essentially a receptionist\nthat is indefinitely waiting for new customers (or, in the context of HTTP, new clients)\nto arrive in the hotel.\n\nWhen a customer arrives at the hotel, that customer starts a conversation with the\nreceptionist. He tells the receptionist how many days he wants to stay at the hotel.\nThen, the receptionist search for an available apartment. If there is an available apartment\nat the moment, the customer pays the hotel fees, then, he gets the keys to the apartment,\nand then, he goes to the apartment to rest.\n\nAfter this entire process of dealing with the customer (searching for available apartments,\nreceiving payment, handing over the keys), the receptionist goes back to what he was\ndoing earlier, which is to wait. Wait for new customers to arrive.\n\nThat is, in a nutshell, what a HTTP Server do. It waits for clients to connect to the\nserver. When a client attempts to connect to the server, the server accepts this connection,\nand it starts to exchange messages with the client through this connection.\nThe first message that happens inside this connection is always a message from the client\nto the server. This message is called the *HTTP Request*.\n\nThis HTTP Request is a HTTP message that contains what\nthe client wants from the server. It is literally a request. The client\nthat connected to the server is asking this server to do something for him.\n\nThere are different \"types of request\" that a client can send to a HTTP Server.\nBut the most basic type of request, is when a client ask to the\nHTTP Server to serve (i.e., to send) some specific web page (which is a HTML file) to him.\nWhen you type `google.com` in your web browser, you are essentially sending a HTTP Request to Google's\nHTTP servers. This request is asking these servers to send the Google webpage to you.\n\nNonetheless, when the server receives this first message, the *HTTP Request*, it\nanalyzes this request, to understand: who the client is? What he wants the server to do?\nThis client has provided all the necessary information to perform the action that he\nasked? Etc.\n\nOnce the server understands what the client wants, he simply perform the action\nthat was requested, and, to finish the whole process, the server sends back\na HTTP message to the client, informing if the action performed was successful or not,\nand, at last, the server ends (or closes) the connection with the client.\n\nThis last HTTP message sent from the server to the client, is called the *HTTP Response*.\nBecause the server is responding to the action that was requested by the client.\nThe main objective of this response message is let the client know if the\naction requested was successful or not, before the server closes the connection.\n\n\n## How a HTTP server is normally implemented? {#sec-http-how-impl}\n\nLet's use the C language as an example. There are many materials\nteaching how to write a simple HTTP server in C code, like @jeffrey_http,\nor @nipun_http, or @eric_http.\nHaving this in mind, I will not show C code examples here, because you\ncan find them on the internet.\nBut I will describe the theory behind the necessary steps to create\nsuch HTTP server in C.\n\n\nIn essence, we normally implement a HTTP server in C by using a TCP socket,\nwhich involves the following steps:\n\n1. Create a TCP socket object.\n1. Bind a name (or more specifically, an address) to this socket object.\n1. Make this socket object to start listening and waiting for incoming connections.\n1. When a connection arrive, we accept this connection, and we exchange the HTTP messages (HTTP Request and HTTP Response).\n1. Then, we simply close this connection.\n\n\nA socket object is essentially a channel of communication.\nYou are creating a channel where people can send messages through.\nWhen you create a socket object, this object is not binded to any particular\naddress. This means that with this object you have a representation of a channel of communication\nin your hands. But this channel is not currently available, or, it is not currently accessible,\nbecause it does not have a known address where you can find it.\n\nThat is what the \"bind\" operation do. It binds a name (or more specifically, an address) to\nthis socket object, or, this channel of communication, so that it becomes available,\nor, accessible through this address. While the \"listen\" operation makes the socket object to\nlisten for incoming connections in this address. In other words, the \"listen\" operation\nmakes the socket wait for incoming connections.\n\nNow, when a client actually attempts to connect to the server through the socket address\nthat we have specified, in order to establish this connection with the client,\nthe socket object needs to accept this incoming connection. Thus, when we\naccept an incoming connection, the client and the server become\nconnected to each other, and they can start reading or writing messages into this\nestablished connection.\n\nAfter we receive the HTTP Request from the client, analyze it, and send the HTTP Response\nto the client, we can then close the connection, and end this communication.\n\n\n## Implementing the server - Part 1\n\n### Creating the socket object {#sec-create-socket}\n\nLet's begin with creating the socket object for our server.\nJust to make things shorter, I will create this socket object in\na separate Zig module. I will name it `config.zig`.\n\nIn Zig, we can create a TCP socket using\nthe `std.posix.socket()` function, from the Zig Standard Library.\nAs I mentioned earlier in @sec-http-how-impl, every socket object that we create\nrepresents a communication channel, and we need to bind this channel to a specific address.\nAn \"address\" is defined as an IP address, or, more specifically, an IPv4 address^[It can be also an IPv6 address. But normally, we use a IPv4 address for that.].\nEvery IPv4 address is composed by two components. The first component is the host,\nwhich is a sequence of 4 numbers separated by dot characters (`.`) that identifies the machine used.\nWhile the second component is a port number, which identifies the specific\ndoor, or, the specific port to use in the host machine.\n\nThe sequence of 4 numbers (i.e., the host) identifies the machine (i.e., the computer itself) where\nthis socket will live in. Every computer normally have multiple \"doors\" available inside of him, because\nthis allows the computer to receive and work with multiple connections at the same time.\nHe simply use a single door for each connection. So the port number, is\nessentially a number that identifies the specific door in the computer that will be responsible\nfor receiving the connection. That is, it identifies the \"door\" in the computer that the socket will use\nto receive incoming connections.\n\nTo make things simpler, I will use an IP address that identifies our current machine in this example.\nThis means that, our socket object will reside on the same computer that we are currently using\n(this is also known as the \"localhost\") to write this Zig source code.\n\nBy convention, the IP address that identifies the \"localhost\", which is the current machine we\nare using, is the IP `127.0.0.1`. So, that is the IP\naddress we are going to use in our server. I can declare it in Zig\nby using an array of 4 integers, like this:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst localhost = [4]u8{ 127, 0, 0, 1 };\n_ = localhost;\n```\n:::\n\n\n\nNow, we need to decide which port number to use. By convention, there are some\nport numbers that are reserved, meaning that, we cannot use them for our own\npurposes, like the port 22 (which is normally used for SSH connections).\nFor TCP connections, which is our case here,\na port number is a 16-bit unsigned integer (type `u16` in Zig),\nthus ranging from 0 to 65535 [@wikipedia_port].\nSo, we can choose\na number from 0 to 65535 for our port number. In the\nexample of this book, I will use the port number 3490\n(just a random number).\n\n\nNow that we have these two informations at hand, I can\nfinally create our socket object, using the `std.posix.socket()` function.\nFirst, we use the host and the port number to create an `Address` object,\nwith the `std.net.Address.initIp4()` function, like in the example below.\nAfter that, I use this address object inside the `socket()` function\nto create our socket object.\n\nThe `Socket` struct defined below summarizes all the logic behind\nthis process. In this struct, we have two data members, which are:\n1)  the address object; 2) and a stream object, which is\nthe object we will use to read and write the messages into any connection we establish.\n\nNotice that, inside the constructor method of this struct,\nwhen we create the socket object, we are using the `IPROTO.TCP` property as an input to\ntell the function to create a socket for TCP connections.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\nconst net = @import(\"std\").net;\n\npub const Socket = struct {\n    _address: std.net.Address,\n    _stream: std.net.Stream,\n\n    pub fn init() !Socket {\n        const host = [4]u8{ 127, 0, 0, 1 };\n        const port = 3490;\n        const addr = net.Address.initIp4(host, port);\n        const socket = try std.posix.socket(\n            addr.any.family,\n            std.posix.SOCK.STREAM,\n            std.posix.IPPROTO.TCP\n        );\n        const stream = net.Stream{ .handle = socket };\n        return Socket{ ._address = addr, ._stream = stream };\n    }\n};\n```\n:::\n\n\n\n\n### Listening and receiving connections\n\nRemember that we stored the `Socket` struct\ndeclaration that we built in @sec-create-socket inside a Zig module named `config.zig`.\nThis is why I imported this module into our main module (`main.zig`) in the example below, as the `SocketConf` object,\nto access the `Socket` struct.\n\nOnce we created our socket object, we can focus now on making this socket object\nlisten and receive new incoming connections. We do that, by calling the `listen()`\nmethod from the `Address` object that is contained inside the socket object, and then,\nwe call the `accept()` method over the result.\n\nThe `listen()` method from the `Address` object produces a server object,\nwhich is an object that will stay open and running indefinitely, waiting\nto receive an incoming connection. Therefore, if you try to run the code\nexample below, by calling the `run` command from the `zig` compiler,\nyou will notice that the programs keeps running indefinitely,\nwithout a clear end.\n\nThis happens, because the program is waiting for something to happen.\nIt's waiting for someone to try to connect to the address (`http://127.0.0.1:3490`) where\nthe server is running and listening for incoming connections. This is what\nthe `listen()` method do, it makes the socket to be active waiting for someone\nto connect.\n\nOn the other side, the `accept()` method is the function that establishes the connection\nwhen someone tries to connect to the socket. This means that, the `accept()` method\nreturns a new connection object as a result. And you can use this connection object\nto read or write messages from or to the client.\nFor now, we are not doing anything with this connection object.\nBut we are going to use it in the next section.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n    _ = connection;\n}\n```\n:::\n\n\n\nThis code example allows one single connection. In other words, the\nserver will wait for one incoming connection, and as soon as the\nserver is done with this first connection that it establishes, the\nprogram ends, and the server stops.\n\nThis is not the norm in the real world. Most people that write\na HTTP server like this, usually put the `accept()` method\ninside a `while` (infinite) loop, where if a connection\nis created with `accept()`, a new thread of execution is created to deal with\nthis new connection and the client. That is, real-world examples of HTTP Servers\nnormally rely on parallel computing to work.\n\nWith this design, the server simply accepts the connection,\nand the whole process of dealing with the client, and receiving\nthe HTTP Request, and sending the HTTP Response, all of this\nis done in the background, on a separate execution thread.\n\nSo, as soon as the server accepts the connection, and creates\nthe separate thread, the server goes back to what he was doing earlier,\nwhich is to wait indefinitely for a new connection to accept.\nHaving this in mind, the code example exposed above, is a\nserver that serves only a single client. Because the program\nterminates as soon as the connection is accepted.\n\n\n\n### Reading the message from the client {#sec-read-http-message}\n\nNow that we have a connection established, i.e., the connection\nobject that we created through the `accept()` function, we can now\nuse this connection object to read any messages that the client\nsend to our server. But we can also use it to send messages back\nto the client.\n\nThe basic idea is, if we **write** any data into this connection object,\nthen, we are sending data to the client, and if we **read** the data present in\nthis connection object, then, we are reading any data that the\nclient sent to us, through this connection object. So, just\nhave this logic in mind. \"Read\" is for reading messages from the client,\nand \"write\" is to send a message to the client.\n\nRemember from @sec-how-http-works that, the first thing that we need to do is to read the HTTP Request\nsent by the client to our server. Because it is the first message that happens\ninside the established connection, and, as a consequence, it is the first\nthing that we need to deal with.\n\nThat is why, I'm going to create a new Zig module in this small project, named `request.zig`\nto keep all functions related to the HTTP Request\ntogether. Then, I will create a new function named `read_request()` that will\nuse our connection object to read the message sent by the client,\nwhich is the HTTP Request.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Connection = std.net.Server.Connection;\npub fn read_request(conn: Connection,\n                    buffer: []u8) !void {\n    const reader = conn.stream.reader();\n    _ = try reader.read(buffer);\n}\n```\n:::\n\n\n\n\nThis function accepts a slice object which behaves as a buffer.\nThe `read_request()` function reads the message sent into\nthe connection object, and saves this message into this buffer object that\nwe have provided as input.\n\nNotice that I'm using the connection object that we created to read\nthe message from the client. I first access the `reader` object that lives inside the\nconnection object. Then, I call the `read()` method of this `reader` object\nto effectively read and save the data sent by the client into the buffer object\nthat we created earlier. I'm discarding the return value\nof the `read()` method, by assigning it to the underscore character (`_`),\nbecause this return value is not useful for us right now.\n\n\n\n## Looking at the current state of the program\n\n\nI think now is a good time to see how our program is currently working. Shall we?\nSo, the first thing I will do is to update the `main.zig` module in our small Zig project,\nso that the `main()` function call this new `read_request()` function that we have just created.\nI will also add a print statement at the end of the `main()` function,\njust so that you can see what the HTTP Request that we have just loaded into the buffer object\nlooks like.\n\nAlso, I'm creating the buffer object in the `main()` function, which will be\nresponsible for storing the message sent by the client, and, I'm also\nusing a `for` loop to initialize all fields of this buffer object to the number zero.\nThis is important to make sure that we don't have uninitialized memory in\nthis object. Because uninitialized memory may cause undefined behaviour in our program.\n\nSince the `read_request()` function should receive as input the buffer object as a slice object (`[]u8`),\nI am using the syntax `array[0..array.len]` to get access to a slice of this `buffer` object.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    _ = try Request.read_request(\n        connection, buffer[0..buffer.len]\n    );\n    try stdout.print(\"{s}\\n\", .{buffer});\n}\n```\n:::\n\n\n\nNow, I'm going to execute this program, with the `run` command from the\n`zig` compiler. But remember, as we sad earlier, as soon as I execute this program, it will\nhang indefinitely, because the program is waiting for a client trying to\nconnect to the server.\n\nMore specifically, the program will pause at the line\nwith the `accept()` call. As soon as a client try to connect to the\nserver, then, the execution will \"unpause\", and the `accept()` function\nwill finally be executed to create the\nconnection object that we need, and the remaining of the program\nwill run.\n\nYou can see that in @fig-print-zigrun1. The message `Server Addr: 127.0.0.1:3490`\nis printed to the console, and the program is now waiting for an incoming connection.\n\n![A screenshot of running the program](./../Figures/print-zigrun1.png){#fig-print-zigrun1}\n\n\nWe can finally try to connect to this server, and there are several ways we can do this.\nFor example, we could use the following Python script:\n\n```python\nimport requests\nrequests.get(\"http://127.0.0.1:3490\")\n```\n\nOr, we could also open any web browser of our preference, and type\nthe URL `localhost:3490`. OBS: `localhost` is the same thing as the\nIP `127.0.0.1`. When you press enter, and your web browser go\nto this address, first, the browser will probably print a message\nsaying that \"this page isn't working\", and, then, it will\nprobably change to a new message saying that \"the site can't be\nreached\".\n\nYou get these \"error messages\" in the web browser, because\nit got no response back from the server. In other words, when the web\nbrowser connected to our server, it did send the HTTP Request through the established connection.\nThen, the web browser was expecting to receive a HTTP Response back, but\nit got no response from the server (we didn't implemented the HTTP Response logic yet).\n\nBut that is okay. We have achieved the result that we wanted for now,\nwhich is to connect to the server, and see the HTTP Request\nthat was sent by the web browser (or by the Python script)\nto the server.\n\nIf you comeback to the console that you left open\nwhen you have executed the program, you will see that the\nprogram finished its execution, and, a new message is\nprinted in the console, which is the actual HTTP Request\nmessage that was sent by the web browser to the server.\nYou can see this message in @fig-print-zigrun2.\n\n![A screenshot of the HTTP Request sent by the web browser](./../Figures/print-zigrun2.png){#fig-print-zigrun2}\n\n\n\n\n## Learning about Enums in Zig {#sec-enum}\n\nEnums structures are available in Zig through the `enum` keyword.\nAn enum (short for \"enumeration\") is a special structure that represents a group of constant values.\nSo, if you have a variable which can assume a short and known\nset of values, you might want to associate this variable to an enum structure,\nto make sure that this variable only assumes a value from this set.\n\nA classic example for enums are primary colors. If for some reason, your program\nneeds to represent one of the primary colors, you can create an enum\nthat represents one of these colors.\nIn the example below, we are creating the enum `PrimaryColorRGB`, which\nrepresents a primary color from the RGB color system. By using this enum,\nI am guaranteed that the `acolor` object for example, will contain\none of these three values: `RED`, `GREEN` or `BLUE`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst PrimaryColorRGB = enum {\n    RED, GREEN, BLUE\n};\nconst acolor = PrimaryColorRGB.RED;\n_ = acolor;\n```\n:::\n\n\n\nIf for some reason, my code tries to save in `acolor`,\na value that is not in this set, I will get an error message\nwarning me that a value such as \"MAGENTA\" do not exist\ninside the `PrimaryColorRGB` enum.\nThen I can easily fix my mistake.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst acolor = PrimaryColorRGB.MAGENTA;\n```\n:::\n\n\n\n```\ne1.zig:5:36: error: enum 'PrimaryColorRGB' has\n        no member named 'MAGENTA':\n    const acolor = PrimaryColorRGB.MAGENTA;\n                                   ^~~~~~~\n```\n\nBehind the hood, enums in Zig work the same way that enums\nwork in C. Each enum value is essentially represented as an integer.\nThe first value in the set is represented as zero,\nthen, the second value is one, ... etc.\n\nOne thing that we are going to learn in the next section is that\nenums can have methods in them. Wait... What? This is amazing!\nYes, enums in Zig are similar to structs, and they can have\nprivate and public methods inside them.\n\n\n\n\n\n\n\n## Implementing the server - Part 2\n\nNow, on this section, I want to focus on parsing\nthe HTTP Request that we received from the client.\nHowever, to effectively parse a HTTP Request message, we first need to understand its\nstructure.\nIn summary, a HTTP Request is a text message that is divided into 3 different\nsections (or parts):\n\n- The top-level header indicating the method of the HTTP Request, the URI, and the HTTP version used in the message.\n- A list of HTTP Headers.\n- The body of the HTTP Request.\n\n### The top-level header\n\nThe first line of text in a HTTP Request always come with the three most essential\ninformation about the request. These three key attributes of the HTTP Request\nare separated by a simple space in this first line of the request.\nThe first information is the HTTP method that is being\nused in the request, second, we have the URI to which this HTTP Request is being sent to,\nand third, we have the version of the HTTP protocol that is being used in this HTTP Request.\n\nIn the snippet below, you can find an example of this first line in a HTTP Request.\nFirst, we have the HTTP method of this request (`GET`). Many programmers\nrefer to the URI component (`/users/list`) as the \"API endpoint\" to which the HTTP Request\nis being sent to. In the context of this specific request, since it's a GET request,\nyou could also say that the URI component is the path to the resource we want to access,\nor, the path to the document (or the file) that we want to retrieve from the server.\n\n```\nGET /users/list HTTP/1.1\n```\n\nAlso, notice that this HTTP Request is using the version 1.1 of the HTTP protocol,\nwhich is the most popular version of the protocol used in the web.\n\n\n\n### The list of HTTP headers\n\nMost HTTP Requests also include a section of HTTP Headers,\nwhich is just a list of attributes or key-value pairs associated with this\nparticular request. This section always comes right after the \"top-level header\" of the request.\n\nFor our purpose in this chapter, which is to build a simple HTTP Server,\nwe are going to ignore this section of the HTTP Request, for simplicity.\nBut most HTTP servers that exist in the wild parses and use these\nHTTP headers to change the way that the server responds to the request\nsent by the client.\n\nFor example, many requests we encounter in the real-world comes with\na HTTP header called `Accept`. In this header, we find a list of [MIME types](https://en.wikipedia.org/wiki/Media_type)[^mime].\nThis list indicates the file formats that the client can read, or parse, or interpret.\nIn other words, you also interpret this header as the client saying the following phrase\nto the server: \"Hey! Look, I can read only HTML documents, so please, send me back\na document that is in a HTML format.\".\n\n[^mime]: <https://en.wikipedia.org/wiki/Media_type>.\n\nIf the HTTP server can read and use this `Accept` header, then, the server can identify\nwhich is the best file format for the document to be sent to the client. Maybe the HTTP server have\nthe same document in multiple formats, for example, in JSON, in XML, in HTML and in PDF,\nbut the client can only understand documents in the HTML format. That is the purpose\nof this `Accept` header.\n\n\n### The body\n\nThe body comes after the list of HTTP headers, and it's an optional section of the HTTP Request, meaning that, not\nall HTTP Requests will come with a body in them. For example, every HTTP Request that uses the\nGET method usually does not come with a body.\n\nBecause a GET request is used to request data, instead of sending it to the server.\nSo, the body section is more related to the POST method, which is a method that involves\nsending data to the server, to be processed and stored.\n\nSince we are going to support only the GET method in this project, it means that\nwe also do not need to care about the body of the request.\n\n\n\n### Creating the HTTP Method enum\n\nEvery HTTP Request comes with a explicit method. The method used in a HTTP Request\nis identified by one these words:\n\n- GET;\n- POST;\n- OPTIONS;\n- PATCH;\n- DELETE;\n- and some other methods.\n\nEach HTTP method is used for a specific type of task. The POST method for example is normally\nused to post some data into the destination. In other words, it's used\nto send some data to the HTTP server, so that it can be processed and stored by the server.\n\nAs another example, the GET method is normally used to get content from the server.\nIn other words, we use this method whenever we want the server to send some\ncontent back to us. It can be any type of content. It can be a web page,\na document file, or some data in a JSON format.\n\nWhen a client sends a POST HTTP Request, the HTTP Response sent by the server normally have the sole purpose of\nletting the client know if the server processed and stored the data successfully.\nIn contrast, when the server receives a GET HTTP Request, then, the server sends the content\nthat the client asked for in the HTTP Response itself. This demonstrates that the method associated\nwith the HTTP Request changes a lot on the dynamics and the roles that each party\nplays in the whole process.\n\nSince the HTTP method of the HTTP Request is identified by this very small and specific\nset of words, it would be interesting to create an enum structure to represent a HTTP method.\nThis way, we can easily check if the HTTP Request we receive from the client is a\nHTTP method that we currently support in our small HTTP server project.\n\nThe `Method` structure below represents this enumeration.\nNotice that, for now, only the GET HTTP method is included in this\nenumeration. Because, for the purpose of this chapter, I want to\nimplement only the GET HTTP method. That is why I am not\nincluding the other HTTP methods in this enumeration.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const Method = enum {\n    GET\n};\n```\n:::\n\n\n\n\nNow, I think we should add two methods to this enum structure. One method is `is_supported()`,\nwhich will be a function that returns a boolean value, indicating if the input HTTP method is supported\nor not by our HTTP Server. The other is `init()`, which is a constructor function that takes a string as input,\nand tries to convert it into a `Method` value.\n\n\nBut in order to build these functions, I will use a functionality from the Zig Standard Library, called\n`StaticStringMap()`. This function allows us to create a simple map from strings to enum values.\nIn other words, we can use this map structure to map a string to the respective enum value.\nTo some extent, this specific structure from the standard library works almost like a \"hashtable\" structure,\nand it's optimized for small sets of words, or, small sets of keys, which is our case here.\nWe are going to talk more about hashtables in Zig in @sec-maps-hashtables.\n\nTo use this \"static string map\" structure, you have to import it from the `std.static_string_map` module\nof the Zig Standard Library. Just to make things shorter and easier to type, I am going to import this\nfunction through a different and shorter name (`Map`).\n\nWith `Map()` imported, we can just apply this function over the enum structure\nthat we are going to use in the resulting map. In our case here, it's the `Method` enum structure\nthat we declared at the last code example. Then, I call the `initComptime()` method with the\nmap, i.e., the list of key-value pairs that we are going to use.\n\nYou can see in the example below that I wrote this map using multiple anonymous struct literals.\nInside the first (or \"top-level\") struct literal, we have a list (or a sequence) of struct literals.\nEach struct literal in this list represents a separate key-value pair. The first element (or the key)\nin each key-value pair should always be a string value. While the second element should\nbe a value from the enum structure that you have used inside the `Map()` function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Map = std.static_string_map.StaticStringMap;\nconst MethodMap = Map(Method).initComptime(.{\n    .{ \"GET\", Method.GET },\n});\n```\n:::\n\n\n\nTherefore, the `MethodMap` object is basically a `std::map` object from C++, or,\na `dict` object from Python. You can retrieve (or get) the enum value that\ncorresponds to a particular key, by using the `get()` method from the map\nobject. This method returns an optional value, so, the `get()` method might\nresult in a null value.\n\nWe can use this in our advantage to detect if a particular HTTP method is\nsupported or not in our HTTP server. Because, if the `get()` method returns null,\nit means that it did not found the method that we provided inside the `MethodMap` object, and,\nas a consequence, this method is not supported by our HTTP server.\n\nThe `init()` method below, takes a string value as input, and then, it simply passes this string value\nto the `get()` method of our `MethodMap` object. As consequence, we should get the enum value that corresponds\nto this input string.\n\nNotice in the example below that, the `init()` method returns either an error\n(which might happen if the `?` method returns `unreacheable`, checkout @sec-null-handling for more details)\nor a `Method` object as result. Since `GET` is currently the only value in our `Method` enum\nstructure, it means that, the `init()` method will most likely return the value `Method.GET` as result.\n\nAlso notice that, in the `is_supported()` method, we are using the optional value returned\nby the `get()` method from our `MethodMap` object. The if statement unwraps the optional value\nreturned by this method, and returns `true` in case this optional value is a not-null value.\nOtherwise, it simply returns `false`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const Method = enum {\n    GET,\n    pub fn init(text: []const u8) !Method {\n        return MethodMap.get(text).?;\n    }\n    pub fn is_supported(m: []const u8) bool {\n        const method = MethodMap.get(m);\n        if (method) |_| {\n            return true;\n        }\n        return false;\n    }\n};\n```\n:::\n\n\n\n\n\n\n\n\n\n### Writing the parse request function\n\nNow that we created the enum that represents our HTTP method,\nwe should start to write the function responsible for\nactually parsing the HTTP Request.\n\nThe first thing we can do, is to write a struct to represent the HTTP Request.\nTake the `Request` struct below as an example. It contains the three\nessential information from the \"top-level\" header (i.e., the first line)\nin the HTTP Request.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Request = struct {\n    method: Method,\n    version: []const u8,\n    uri: []const u8,\n    pub fn init(method: Method,\n                uri: []const u8,\n                version: []const u8) Request {\n        return Request{\n            .method = method,\n            .uri = uri,\n            .version = version,\n        };\n    }\n};\n```\n:::\n\n\n\n\nThe `parse_request()` function should receive a string as input. This input string\ncontains the entire HTTP Request message, and the parsing function should\nread and understand the individual parts of this message.\n\nNow, remember that for the purpose of this chapter, we care only about the first\nline in this message, which contains the \"top-level header\", or, the three essential attributes about the HTTP Request,\nwhich are the HTTP method used, the URI and the HTTP version.\n\nNotice that I use the function `indexOfScalar()` in `parse_request()`. This function from the\nZig Standard Library returns the first index where the scalar value that we provide\nhappens in a string. In this case, I'm looking at the first occurrence of the new line character (`\\n`).\nBecause once again, we care only about the first line in the HTTP Request message.\nThis is the line where we have the three information that we want to parse\n(version of HTTP, the HTTP method and the URI).\n\nTherefore, we are using this `indexOfScalar()` function\nto limit our parsing process to the first line in the message.\nIt's also worth mentioning that, the `indexOfScalar()` function returns an optional value.\nThat is why I use the `orelse` keyword to provide an alternative value, in case\nthe value returned by the function is a null value.\n\nSince each of these three attributes are separated by a simple space, we\ncould use the function `splitScalar()` from the Zig Standard Library to split\nthe input string into sections by looking for every position that appears\na simple space. In other words, this `splitScalar()` function is equivalent\nto the `split()` method in Python, or, the `std::getline()` function from C++,\nor the `strtok()` function in C.\n\nWhen you use this `splitScalar()` function, you get an iterator as the result.\nThis iterator have a `next()` method that you can use to advance the iterator\nto the next position, or, to the next section of the splitted string.\nNote that, when you use `next()`, the method not only advances the iterator,\nbut it also returns a slice to the current section of the splitted\nstring as result.\n\nNow, if you want to get a slice to the current section of the splitted\nstring, but not advance the iterator to the next position, you can use\nthe `peek()` method. Both `next()` and `peek()` methods return an optional value, that is\nwhy I use the `?` method to unwrap these optional values.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn parse_request(text: []u8) Request {\n    const line_index = std.mem.indexOfScalar(\n        u8, text, '\\n'\n    ) orelse text.len;\n    var iterator = std.mem.splitScalar(\n        u8, text[0..line_index], ' '\n    );\n    const method = try Method.init(iterator.next().?);\n    const uri = iterator.next().?;\n    const version = iterator.next().?;\n    const request = Request.init(method, uri, version);\n    return request;\n}\n```\n:::\n\n\n\n\nAs I described in @sec-zig-strings, strings in Zig are simply arrays of bytes in the language.\nSo, you will find lots of excellent utility functions to work directly with strings\ninside this `mem` module from the Zig Standard Library.\nWe have described some of these useful utility functions already\nin @sec-strings-useful-funs.\n\n\n\n### Using the parse request function\n\nNow that we wrote the function responsible for parsing the HTTP Request,\nwe can add the function call to `parse_request()` in\nthe `main()` function of our program.\n\nAfter that, is a good idea to test once again the state of our program.\nI execute this program again with the `run` command from the `zig` compiler,\nthen, I use my web browser to connect once again to the server through the URL `localhost:3490`, and finally,\nthe end result of our `Request` object is printed to the console.\n\nA quick observation, since I have used the `any` format specifier in the\nprint statement, the data members `version` and `uri` of the `Request`\nstruct were printed as raw integer values. String data being printed\nas integer values is common in Zig, and remember, these integer values are just the decimal representation of\nthe bytes that form the string in question.\n\nIn the result below, the sequence of decimal values 72, 84, 84, 80, 47, 49, 46, 49, and 13,\nare the bytes that form the text \"HTTP/1.1\". And the integer 47, is the decimal value of\nthe character `/`, which represents our URI in this request.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    try Request.read_request(\n        connection, buffer[0..buffer.len]\n    );\n    const request = Request.parse_request(\n        buffer[0..buffer.len]\n    );\n    try stdout.print(\"{any}\\n\", .{request});\n}\n```\n:::\n\n\n\n```\nrequest.Request{\n    .method = request.Method.GET,\n    .version = {72, 84, 84, 80, 47, 49, 46, 49, 13},\n    .uri = {47}\n}\n```\n\n\n\n### Sending the HTTP Response to the client\n\nIn this last part, we are going to write the logic responsible for\nsending the HTTP Response from the server to the client. To make things\nsimple, the server in this project will send just a simple web page\ncontaining the text \"Hello world\".\n\nFirst, I create a new Zig module in the project, named `response.zig`.\nIn this module, I will declare just two functions. Each function\ncorresponds to a specific status code in the HTTP Response.\nThe `send_200()` function will send a HTTP Response with status code 200\n(which means \"Success\") to the client. While the `send_404()` function sends a response\nwith status code 404 (which means \"Not found\").\n\nThis is definitely not the most ergonomic and adequate way of handling the\nHTTP Response, but it works for our case here. We are just building toy projects\nin this book after all, therefore, the source code that we write do not need to be perfect.\nIt just needs to work!\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Connection = std.net.Server.Connection;\npub fn send_200(conn: Connection) !void {\n    const message = (\n        \"HTTP/1.1 200 OK\\nContent-Length: 48\"\n        ++ \"\\nContent-Type: text/html\\n\"\n        ++ \"Connection: Closed\\n\\n<html><body>\"\n        ++ \"<h1>Hello, World!</h1></body></html>\"\n    );\n    _ = try conn.stream.write(message);\n}\n\npub fn send_404(conn: Connection) !void {\n    const message = (\n        \"HTTP/1.1 404 Not Found\\nContent-Length: 50\"\n        ++ \"\\nContent-Type: text/html\\n\"\n        ++ \"Connection: Closed\\n\\n<html><body>\"\n        ++ \"<h1>File not found!</h1></body></html>\"\n    );\n    _ = try conn.stream.write(message);\n}\n```\n:::\n\n\n\nNotice that both functions receives the connection object as input, and\nuse the `write()` method to write the HTTP Response message directly\ninto this communication channel. As result, the party in the other\nside of the connection (i.e., the client), will receive such message.\n\nMost real-world HTTP Servers will have a single function (or a single struct) to effectively handle\nthe response. It gets the HTTP Request already parsed as input, and then, it tries to build\nthe HTTP Response bit by bit, before the function sends it over the connection.\n\nWe would also have a specialized struct to represent a HTTP Response, and\na lot of methods that would be used to build each part or component of the response object.\nTake the `Response` struct created by the Javascript runtime Bun as an example.\nYou can find this struct in the [`response.zig` module](https://github.com/oven-sh/bun/blob/main/src/bun.js/webcore/response.zig)[^bun-resp]\nin their GitHub project.\n\n[^bun-resp]: <https://github.com/oven-sh/bun/blob/main/src/bun.js/webcore/response.zig>.\n\n\n## The end result\n\nWe can now, update once again our `main()` function to incorporate our new\nfunctions from the `response.zig` module. First, I need to import this module\ninto our `main.zig` module, then, I add the function calls to `send_200()`\nand `send_404()`.\n\nNotice that I'm using if statements to decide which \"response function\" to call,\nbased especially on the URI present in the HTTP Request. If the user asked for\na content (or a document) that is not present in our server, we should respond\nwith a 404 status code. But since we have just a simple HTTP server, with no\nreal documents to send, we can just check if the URI is the root path (`/`)\nor not to decide which function to call.\n\nAlso, notice that I'm using the function `std.mem.eql()` from the Zig Standard Library\nto check if the string from `uri` is equal or not the string `\"/\"`. We have\ndescribed this function already in @sec-strings-useful-funs, so, comeback to\nthat section if you are not familiar yet with this function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst Response = @import(\"response.zig\");\nconst Method = Request.Method;\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    try Request.read_request(connection, buffer[0..buffer.len]);\n    const request = Request.parse_request(\n        buffer[0..buffer.len]\n    );\n    if (request.method == Method.GET) {\n        if (std.mem.eql(u8, request.uri, \"/\")) {\n            try Response.send_200(connection);\n        } else {\n            try Response.send_404(connection);\n        }\n    }\n}\n```\n:::\n\n\n\n\nNow that we adjusted our `main()` function, I can now execute our program, and\nsee the effects of these last changes. First, I execute the program once again, with the\n`run` command of the `zig` compiler. The program will hang, waiting for a client to connect.\n\nThen, I open my web browser, and try to connect to the server again, using the URL `localhost:3490`.\nThis time, instead of getting some sort of an error message from the browser, you will get the message\n\"Hello World\" printed into your web browser. Because this time, the server sended the HTTP Response\nsuccessfully to the web browser, as demonstrated by @fig-print-zigrun3.\n\n\n![The Hello World message sent in the HTTP Response](./../Figures/print-zigrun3.png){#fig-print-zigrun3}\n",
-    "supporting": [
-      "04-http-server_files"
-    ],
-    "filters": [
-      "rmarkdown/pagebreak.lua"
-    ],
-    "includes": {},
-    "engineDependencies": {
-      "knitr": [
-        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
-      ]
-    },
-    "preserve": null,
-    "postProcess": false
-  }
-}
\ No newline at end of file
diff --git a/_freeze/Chapters/04-http-server/execute-results/html.json b/_freeze/Chapters/04-http-server/execute-results/html.json
index b09291c7..577dfb71 100644
--- a/_freeze/Chapters/04-http-server/execute-results/html.json
+++ b/_freeze/Chapters/04-http-server/execute-results/html.json
@@ -2,10 +2,8 @@
   "hash": "f64c88659b4b19943ce530d1245b8add",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 2 - Building a HTTP Server from scratch\n\nIn this chapter, I want to implement a new\nsmall project with you. This time, we are going\nto implement a basic HTTP Server from scratch.\n\nThe Zig Standard Library already have a HTTP Server\nimplemented, which is available at `std.http.Server`.\nBut again, our objective here in this chapter, is to implement\nit **from scratch**. So we can't use this server object available\nfrom the Zig Standard Library.\n\n## What is a HTTP Server?\n\nFirst of all, what is a HTTP Server?\nA HTTP server, as any other type of server, is essentially\na program that runs indefinitely, on an infinite loop, waiting for incoming connections\nfrom clients. Once the server receives an incoming connection, it will\naccept this connection, and it will send messages back-and-forth to the client\nthrough this connection.\n\nBut the messages that are transmitted inside this connection are in a\nspecific format. They are HTTP messages\n(i.e., messages that use the HTTP Protocol specification).\nThe HTTP Protocol is the backbone of the modern web.\nThe world wide web as we know it today, would not exist without the\nHTTP Protocol.\n\nSo, Web servers (which is just a fancy name to\nHTTP Servers) are servers that exchange HTTP messages with clients.\nAnd these HTTP servers and the HTTP Protocol specification\nare essential to the operation of the world wide web today.\n\nThat is the whole picture of the process.\nAgain, we have two subjects involved here, a server (which is\na program that is running indefinitely, waiting to receive incoming connections),\nand a client (which is someone that wants to connect to the server,\nand exchange HTTP messages with it).\n\nYou may find the material about the [HTTP Protocol available at the Mozilla MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview)[^mdn-http]\n, a great resource for you to also look at. It gives you a great overview on how\nHTTP works, and what role the server plays in this matter.\n\n[^mdn-http]: <https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview>.\n\n\n## How a HTTP Server works? {#sec-how-http-works}\n\nImagine a HTTP Server as if it were the receptionist of a large hotel. In a hotel,\nyou have a reception, and inside that reception there is a receptionist\nwaiting for customers to arrive. A HTTP Server is essentially a receptionist\nthat is indefinitely waiting for new customers (or, in the context of HTTP, new clients)\nto arrive in the hotel.\n\nWhen a customer arrives at the hotel, that customer starts a conversation with the\nreceptionist. He tells the receptionist how many days he wants to stay at the hotel.\nThen, the receptionist search for an available apartment. If there is an available apartment\nat the moment, the customer pays the hotel fees, then, he gets the keys to the apartment,\nand then, he goes to the apartment to rest.\n\nAfter this entire process of dealing with the customer (searching for available apartments,\nreceiving payment, handing over the keys), the receptionist goes back to what he was\ndoing earlier, which is to wait. Wait for new customers to arrive.\n\nThat is, in a nutshell, what a HTTP Server do. It waits for clients to connect to the\nserver. When a client attempts to connect to the server, the server accepts this connection,\nand it starts to exchange messages with the client through this connection.\nThe first message that happens inside this connection is always a message from the client\nto the server. This message is called the *HTTP Request*.\n\nThis HTTP Request is a HTTP message that contains what\nthe client wants from the server. It is literally a request. The client\nthat connected to the server is asking this server to do something for him.\n\nThere are different \"types of request\" that a client can send to a HTTP Server.\nBut the most basic type of request, is when a client ask to the\nHTTP Server to serve (i.e., to send) some specific web page (which is a HTML file) to him.\nWhen you type `google.com` in your web browser, you are essentially sending a HTTP Request to Google's\nHTTP servers. This request is asking these servers to send the Google webpage to you.\n\nNonetheless, when the server receives this first message, the *HTTP Request*, it\nanalyzes this request, to understand: who the client is? What he wants the server to do?\nThis client has provided all the necessary information to perform the action that he\nasked? Etc.\n\nOnce the server understands what the client wants, he simply perform the action\nthat was requested, and, to finish the whole process, the server sends back\na HTTP message to the client, informing if the action performed was successful or not,\nand, at last, the server ends (or closes) the connection with the client.\n\nThis last HTTP message sent from the server to the client, is called the *HTTP Response*.\nBecause the server is responding to the action that was requested by the client.\nThe main objective of this response message is let the client know if the\naction requested was successful or not, before the server closes the connection.\n\n\n## How a HTTP server is normally implemented? {#sec-http-how-impl}\n\nLet's use the C language as an example. There are many materials\nteaching how to write a simple HTTP server in C code, like @jeffrey_http,\nor @nipun_http, or @eric_http.\nHaving this in mind, I will not show C code examples here, because you\ncan find them on the internet.\nBut I will describe the theory behind the necessary steps to create\nsuch HTTP server in C.\n\n\nIn essence, we normally implement a HTTP server in C by using a TCP socket,\nwhich involves the following steps:\n\n1. Create a TCP socket object.\n1. Bind a name (or more specifically, an address) to this socket object.\n1. Make this socket object to start listening and waiting for incoming connections.\n1. When a connection arrive, we accept this connection, and we exchange the HTTP messages (HTTP Request and HTTP Response).\n1. Then, we simply close this connection.\n\n\nA socket object is essentially a channel of communication.\nYou are creating a channel where people can send messages through.\nWhen you create a socket object, this object is not binded to any particular\naddress. This means that with this object you have a representation of a channel of communication\nin your hands. But this channel is not currently available, or, it is not currently accessible,\nbecause it does not have a known address where you can find it.\n\nThat is what the \"bind\" operation do. It binds a name (or more specifically, an address) to\nthis socket object, or, this channel of communication, so that it becomes available,\nor, accessible through this address. While the \"listen\" operation makes the socket object to\nlisten for incoming connections in this address. In other words, the \"listen\" operation\nmakes the socket wait for incoming connections.\n\nNow, when a client actually attempts to connect to the server through the socket address\nthat we have specified, in order to establish this connection with the client,\nthe socket object needs to accept this incoming connection. Thus, when we\naccept an incoming connection, the client and the server become\nconnected to each other, and they can start reading or writing messages into this\nestablished connection.\n\nAfter we receive the HTTP Request from the client, analyze it, and send the HTTP Response\nto the client, we can then close the connection, and end this communication.\n\n\n## Implementing the server - Part 1\n\n### Creating the socket object {#sec-create-socket}\n\nLet's begin with creating the socket object for our server.\nJust to make things shorter, I will create this socket object in\na separate Zig module. I will name it `config.zig`.\n\nIn Zig, we can create a TCP socket using\nthe `std.posix.socket()` function, from the Zig Standard Library.\nAs I mentioned earlier in @sec-http-how-impl, every socket object that we create\nrepresents a communication channel, and we need to bind this channel to a specific address.\nAn \"address\" is defined as an IP address, or, more specifically, an IPv4 address^[It can be also an IPv6 address. But normally, we use a IPv4 address for that.].\nEvery IPv4 address is composed by two components. The first component is the host,\nwhich is a sequence of 4 numbers separated by dot characters (`.`) that identifies the machine used.\nWhile the second component is a port number, which identifies the specific\ndoor, or, the specific port to use in the host machine.\n\nThe sequence of 4 numbers (i.e., the host) identifies the machine (i.e., the computer itself) where\nthis socket will live in. Every computer normally have multiple \"doors\" available inside of him, because\nthis allows the computer to receive and work with multiple connections at the same time.\nHe simply use a single door for each connection. So the port number, is\nessentially a number that identifies the specific door in the computer that will be responsible\nfor receiving the connection. That is, it identifies the \"door\" in the computer that the socket will use\nto receive incoming connections.\n\nTo make things simpler, I will use an IP address that identifies our current machine in this example.\nThis means that, our socket object will reside on the same computer that we are currently using\n(this is also known as the \"localhost\") to write this Zig source code.\n\nBy convention, the IP address that identifies the \"localhost\", which is the current machine we\nare using, is the IP `127.0.0.1`. So, that is the IP\naddress we are going to use in our server. I can declare it in Zig\nby using an array of 4 integers, like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst localhost = [4]u8{ 127, 0, 0, 1 };\n_ = localhost;\n```\n:::\n\n\n\n\nNow, we need to decide which port number to use. By convention, there are some\nport numbers that are reserved, meaning that, we cannot use them for our own\npurposes, like the port 22 (which is normally used for SSH connections).\nFor TCP connections, which is our case here,\na port number is a 16-bit unsigned integer (type `u16` in Zig),\nthus ranging from 0 to 65535 [@wikipedia_port].\nSo, we can choose\na number from 0 to 65535 for our port number. In the\nexample of this book, I will use the port number 3490\n(just a random number).\n\n\nNow that we have these two informations at hand, I can\nfinally create our socket object, using the `std.posix.socket()` function.\nFirst, we use the host and the port number to create an `Address` object,\nwith the `std.net.Address.initIp4()` function, like in the example below.\nAfter that, I use this address object inside the `socket()` function\nto create our socket object.\n\nThe `Socket` struct defined below summarizes all the logic behind\nthis process. In this struct, we have two data members, which are:\n1)  the address object; 2) and a stream object, which is\nthe object we will use to read and write the messages into any connection we establish.\n\nNotice that, inside the constructor method of this struct,\nwhen we create the socket object, we are using the `IPROTO.TCP` property as an input to\ntell the function to create a socket for TCP connections.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\nconst net = @import(\"std\").net;\n\npub const Socket = struct {\n    _address: std.net.Address,\n    _stream: std.net.Stream,\n\n    pub fn init() !Socket {\n        const host = [4]u8{ 127, 0, 0, 1 };\n        const port = 3490;\n        const addr = net.Address.initIp4(host, port);\n        const socket = try std.posix.socket(\n            addr.any.family,\n            std.posix.SOCK.STREAM,\n            std.posix.IPPROTO.TCP\n        );\n        const stream = net.Stream{ .handle = socket };\n        return Socket{ ._address = addr, ._stream = stream };\n    }\n};\n```\n:::\n\n\n\n\n\n### Listening and receiving connections\n\nRemember that we stored the `Socket` struct\ndeclaration that we built in @sec-create-socket inside a Zig module named `config.zig`.\nThis is why I imported this module into our main module (`main.zig`) in the example below, as the `SocketConf` object,\nto access the `Socket` struct.\n\nOnce we created our socket object, we can focus now on making this socket object\nlisten and receive new incoming connections. We do that, by calling the `listen()`\nmethod from the `Address` object that is contained inside the socket object, and then,\nwe call the `accept()` method over the result.\n\nThe `listen()` method from the `Address` object produces a server object,\nwhich is an object that will stay open and running indefinitely, waiting\nto receive an incoming connection. Therefore, if you try to run the code\nexample below, by calling the `run` command from the `zig` compiler,\nyou will notice that the programs keeps running indefinitely,\nwithout a clear end.\n\nThis happens, because the program is waiting for something to happen.\nIt's waiting for someone to try to connect to the address (`http://127.0.0.1:3490`) where\nthe server is running and listening for incoming connections. This is what\nthe `listen()` method do, it makes the socket to be active waiting for someone\nto connect.\n\nOn the other side, the `accept()` method is the function that establishes the connection\nwhen someone tries to connect to the socket. This means that, the `accept()` method\nreturns a new connection object as a result. And you can use this connection object\nto read or write messages from or to the client.\nFor now, we are not doing anything with this connection object.\nBut we are going to use it in the next section.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n    _ = connection;\n}\n```\n:::\n\n\n\n\nThis code example allows one single connection. In other words, the\nserver will wait for one incoming connection, and as soon as the\nserver is done with this first connection that it establishes, the\nprogram ends, and the server stops.\n\nThis is not the norm in the real world. Most people that write\na HTTP server like this, usually put the `accept()` method\ninside a `while` (infinite) loop, where if a connection\nis created with `accept()`, a new thread of execution is created to deal with\nthis new connection and the client. That is, real-world examples of HTTP Servers\nnormally rely on parallel computing to work.\n\nWith this design, the server simply accepts the connection,\nand the whole process of dealing with the client, and receiving\nthe HTTP Request, and sending the HTTP Response, all of this\nis done in the background, on a separate execution thread.\n\nSo, as soon as the server accepts the connection, and creates\nthe separate thread, the server goes back to what he was doing earlier,\nwhich is to wait indefinitely for a new connection to accept.\nHaving this in mind, the code example exposed above, is a\nserver that serves only a single client. Because the program\nterminates as soon as the connection is accepted.\n\n\n\n### Reading the message from the client {#sec-read-http-message}\n\nNow that we have a connection established, i.e., the connection\nobject that we created through the `accept()` function, we can now\nuse this connection object to read any messages that the client\nsend to our server. But we can also use it to send messages back\nto the client.\n\nThe basic idea is, if we **write** any data into this connection object,\nthen, we are sending data to the client, and if we **read** the data present in\nthis connection object, then, we are reading any data that the\nclient sent to us, through this connection object. So, just\nhave this logic in mind. \"Read\" is for reading messages from the client,\nand \"write\" is to send a message to the client.\n\nRemember from @sec-how-http-works that, the first thing that we need to do is to read the HTTP Request\nsent by the client to our server. Because it is the first message that happens\ninside the established connection, and, as a consequence, it is the first\nthing that we need to deal with.\n\nThat is why, I'm going to create a new Zig module in this small project, named `request.zig`\nto keep all functions related to the HTTP Request\ntogether. Then, I will create a new function named `read_request()` that will\nuse our connection object to read the message sent by the client,\nwhich is the HTTP Request.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Connection = std.net.Server.Connection;\npub fn read_request(conn: Connection,\n                    buffer: []u8) !void {\n    const reader = conn.stream.reader();\n    _ = try reader.read(buffer);\n}\n```\n:::\n\n\n\n\n\nThis function accepts a slice object which behaves as a buffer.\nThe `read_request()` function reads the message sent into\nthe connection object, and saves this message into this buffer object that\nwe have provided as input.\n\nNotice that I'm using the connection object that we created to read\nthe message from the client. I first access the `reader` object that lives inside the\nconnection object. Then, I call the `read()` method of this `reader` object\nto effectively read and save the data sent by the client into the buffer object\nthat we created earlier. I'm discarding the return value\nof the `read()` method, by assigning it to the underscore character (`_`),\nbecause this return value is not useful for us right now.\n\n\n\n## Looking at the current state of the program\n\n\nI think now is a good time to see how our program is currently working. Shall we?\nSo, the first thing I will do is to update the `main.zig` module in our small Zig project,\nso that the `main()` function call this new `read_request()` function that we have just created.\nI will also add a print statement at the end of the `main()` function,\njust so that you can see what the HTTP Request that we have just loaded into the buffer object\nlooks like.\n\nAlso, I'm creating the buffer object in the `main()` function, which will be\nresponsible for storing the message sent by the client, and, I'm also\nusing a `for` loop to initialize all fields of this buffer object to the number zero.\nThis is important to make sure that we don't have uninitialized memory in\nthis object. Because uninitialized memory may cause undefined behaviour in our program.\n\nSince the `read_request()` function should receive as input the buffer object as a slice object (`[]u8`),\nI am using the syntax `array[0..array.len]` to get access to a slice of this `buffer` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    _ = try Request.read_request(\n        connection, buffer[0..buffer.len]\n    );\n    try stdout.print(\"{s}\\n\", .{buffer});\n}\n```\n:::\n\n\n\n\nNow, I'm going to execute this program, with the `run` command from the\n`zig` compiler. But remember, as we sad earlier, as soon as I execute this program, it will\nhang indefinitely, because the program is waiting for a client trying to\nconnect to the server.\n\nMore specifically, the program will pause at the line\nwith the `accept()` call. As soon as a client try to connect to the\nserver, then, the execution will \"unpause\", and the `accept()` function\nwill finally be executed to create the\nconnection object that we need, and the remaining of the program\nwill run.\n\nYou can see that in @fig-print-zigrun1. The message `Server Addr: 127.0.0.1:3490`\nis printed to the console, and the program is now waiting for an incoming connection.\n\n![A screenshot of running the program](./../Figures/print-zigrun1.png){#fig-print-zigrun1}\n\n\nWe can finally try to connect to this server, and there are several ways we can do this.\nFor example, we could use the following Python script:\n\n```python\nimport requests\nrequests.get(\"http://127.0.0.1:3490\")\n```\n\nOr, we could also open any web browser of our preference, and type\nthe URL `localhost:3490`. OBS: `localhost` is the same thing as the\nIP `127.0.0.1`. When you press enter, and your web browser go\nto this address, first, the browser will probably print a message\nsaying that \"this page isn't working\", and, then, it will\nprobably change to a new message saying that \"the site can't be\nreached\".\n\nYou get these \"error messages\" in the web browser, because\nit got no response back from the server. In other words, when the web\nbrowser connected to our server, it did send the HTTP Request through the established connection.\nThen, the web browser was expecting to receive a HTTP Response back, but\nit got no response from the server (we didn't implemented the HTTP Response logic yet).\n\nBut that is okay. We have achieved the result that we wanted for now,\nwhich is to connect to the server, and see the HTTP Request\nthat was sent by the web browser (or by the Python script)\nto the server.\n\nIf you comeback to the console that you left open\nwhen you have executed the program, you will see that the\nprogram finished its execution, and, a new message is\nprinted in the console, which is the actual HTTP Request\nmessage that was sent by the web browser to the server.\nYou can see this message in @fig-print-zigrun2.\n\n![A screenshot of the HTTP Request sent by the web browser](./../Figures/print-zigrun2.png){#fig-print-zigrun2}\n\n\n\n\n## Learning about Enums in Zig {#sec-enum}\n\nEnums structures are available in Zig through the `enum` keyword.\nAn enum (short for \"enumeration\") is a special structure that represents a group of constant values.\nSo, if you have a variable which can assume a short and known\nset of values, you might want to associate this variable to an enum structure,\nto make sure that this variable only assumes a value from this set.\n\nA classic example for enums are primary colors. If for some reason, your program\nneeds to represent one of the primary colors, you can create an enum\nthat represents one of these colors.\nIn the example below, we are creating the enum `PrimaryColorRGB`, which\nrepresents a primary color from the RGB color system. By using this enum,\nI am guaranteed that the `acolor` object for example, will contain\none of these three values: `RED`, `GREEN` or `BLUE`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst PrimaryColorRGB = enum {\n    RED, GREEN, BLUE\n};\nconst acolor = PrimaryColorRGB.RED;\n_ = acolor;\n```\n:::\n\n\n\n\nIf for some reason, my code tries to save in `acolor`,\na value that is not in this set, I will get an error message\nwarning me that a value such as \"MAGENTA\" do not exist\ninside the `PrimaryColorRGB` enum.\nThen I can easily fix my mistake.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst acolor = PrimaryColorRGB.MAGENTA;\n```\n:::\n\n\n\n\n```\ne1.zig:5:36: error: enum 'PrimaryColorRGB' has\n        no member named 'MAGENTA':\n    const acolor = PrimaryColorRGB.MAGENTA;\n                                   ^~~~~~~\n```\n\nBehind the hood, enums in Zig work the same way that enums\nwork in C. Each enum value is essentially represented as an integer.\nThe first value in the set is represented as zero,\nthen, the second value is one, ... etc.\n\nOne thing that we are going to learn in the next section is that\nenums can have methods in them. Wait... What? This is amazing!\nYes, enums in Zig are similar to structs, and they can have\nprivate and public methods inside them.\n\n\n\n\n\n\n\n## Implementing the server - Part 2\n\nNow, on this section, I want to focus on parsing\nthe HTTP Request that we received from the client.\nHowever, to effectively parse a HTTP Request message, we first need to understand its\nstructure.\nIn summary, a HTTP Request is a text message that is divided into 3 different\nsections (or parts):\n\n- The top-level header indicating the method of the HTTP Request, the URI, and the HTTP version used in the message.\n- A list of HTTP Headers.\n- The body of the HTTP Request.\n\n### The top-level header\n\nThe first line of text in a HTTP Request always come with the three most essential\ninformation about the request. These three key attributes of the HTTP Request\nare separated by a simple space in this first line of the request.\nThe first information is the HTTP method that is being\nused in the request, second, we have the URI to which this HTTP Request is being sent to,\nand third, we have the version of the HTTP protocol that is being used in this HTTP Request.\n\nIn the snippet below, you can find an example of this first line in a HTTP Request.\nFirst, we have the HTTP method of this request (`GET`). Many programmers\nrefer to the URI component (`/users/list`) as the \"API endpoint\" to which the HTTP Request\nis being sent to. In the context of this specific request, since it's a GET request,\nyou could also say that the URI component is the path to the resource we want to access,\nor, the path to the document (or the file) that we want to retrieve from the server.\n\n```\nGET /users/list HTTP/1.1\n```\n\nAlso, notice that this HTTP Request is using the version 1.1 of the HTTP protocol,\nwhich is the most popular version of the protocol used in the web.\n\n\n\n### The list of HTTP headers\n\nMost HTTP Requests also include a section of HTTP Headers,\nwhich is just a list of attributes or key-value pairs associated with this\nparticular request. This section always comes right after the \"top-level header\" of the request.\n\nFor our purpose in this chapter, which is to build a simple HTTP Server,\nwe are going to ignore this section of the HTTP Request, for simplicity.\nBut most HTTP servers that exist in the wild parses and use these\nHTTP headers to change the way that the server responds to the request\nsent by the client.\n\nFor example, many requests we encounter in the real-world comes with\na HTTP header called `Accept`. In this header, we find a list of [MIME types](https://en.wikipedia.org/wiki/Media_type)[^mime].\nThis list indicates the file formats that the client can read, or parse, or interpret.\nIn other words, you also interpret this header as the client saying the following phrase\nto the server: \"Hey! Look, I can read only HTML documents, so please, send me back\na document that is in a HTML format.\".\n\n[^mime]: <https://en.wikipedia.org/wiki/Media_type>.\n\nIf the HTTP server can read and use this `Accept` header, then, the server can identify\nwhich is the best file format for the document to be sent to the client. Maybe the HTTP server have\nthe same document in multiple formats, for example, in JSON, in XML, in HTML and in PDF,\nbut the client can only understand documents in the HTML format. That is the purpose\nof this `Accept` header.\n\n\n### The body\n\nThe body comes after the list of HTTP headers, and it's an optional section of the HTTP Request, meaning that, not\nall HTTP Requests will come with a body in them. For example, every HTTP Request that uses the\nGET method usually does not come with a body.\n\nBecause a GET request is used to request data, instead of sending it to the server.\nSo, the body section is more related to the POST method, which is a method that involves\nsending data to the server, to be processed and stored.\n\nSince we are going to support only the GET method in this project, it means that\nwe also do not need to care about the body of the request.\n\n\n\n### Creating the HTTP Method enum\n\nEvery HTTP Request comes with a explicit method. The method used in a HTTP Request\nis identified by one these words:\n\n- GET;\n- POST;\n- OPTIONS;\n- PATCH;\n- DELETE;\n- and some other methods.\n\nEach HTTP method is used for a specific type of task. The POST method for example is normally\nused to post some data into the destination. In other words, it's used\nto send some data to the HTTP server, so that it can be processed and stored by the server.\n\nAs another example, the GET method is normally used to get content from the server.\nIn other words, we use this method whenever we want the server to send some\ncontent back to us. It can be any type of content. It can be a web page,\na document file, or some data in a JSON format.\n\nWhen a client sends a POST HTTP Request, the HTTP Response sent by the server normally have the sole purpose of\nletting the client know if the server processed and stored the data successfully.\nIn contrast, when the server receives a GET HTTP Request, then, the server sends the content\nthat the client asked for in the HTTP Response itself. This demonstrates that the method associated\nwith the HTTP Request changes a lot on the dynamics and the roles that each party\nplays in the whole process.\n\nSince the HTTP method of the HTTP Request is identified by this very small and specific\nset of words, it would be interesting to create an enum structure to represent a HTTP method.\nThis way, we can easily check if the HTTP Request we receive from the client is a\nHTTP method that we currently support in our small HTTP server project.\n\nThe `Method` structure below represents this enumeration.\nNotice that, for now, only the GET HTTP method is included in this\nenumeration. Because, for the purpose of this chapter, I want to\nimplement only the GET HTTP method. That is why I am not\nincluding the other HTTP methods in this enumeration.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const Method = enum {\n    GET\n};\n```\n:::\n\n\n\n\n\nNow, I think we should add two methods to this enum structure. One method is `is_supported()`,\nwhich will be a function that returns a boolean value, indicating if the input HTTP method is supported\nor not by our HTTP Server. The other is `init()`, which is a constructor function that takes a string as input,\nand tries to convert it into a `Method` value.\n\n\nBut in order to build these functions, I will use a functionality from the Zig Standard Library, called\n`StaticStringMap()`. This function allows us to create a simple map from strings to enum values.\nIn other words, we can use this map structure to map a string to the respective enum value.\nTo some extent, this specific structure from the standard library works almost like a \"hashtable\" structure,\nand it's optimized for small sets of words, or, small sets of keys, which is our case here.\nWe are going to talk more about hashtables in Zig in @sec-maps-hashtables.\n\nTo use this \"static string map\" structure, you have to import it from the `std.static_string_map` module\nof the Zig Standard Library. Just to make things shorter and easier to type, I am going to import this\nfunction through a different and shorter name (`Map`).\n\nWith `Map()` imported, we can just apply this function over the enum structure\nthat we are going to use in the resulting map. In our case here, it's the `Method` enum structure\nthat we declared at the last code example. Then, I call the `initComptime()` method with the\nmap, i.e., the list of key-value pairs that we are going to use.\n\nYou can see in the example below that I wrote this map using multiple anonymous struct literals.\nInside the first (or \"top-level\") struct literal, we have a list (or a sequence) of struct literals.\nEach struct literal in this list represents a separate key-value pair. The first element (or the key)\nin each key-value pair should always be a string value. While the second element should\nbe a value from the enum structure that you have used inside the `Map()` function.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Map = std.static_string_map.StaticStringMap;\nconst MethodMap = Map(Method).initComptime(.{\n    .{ \"GET\", Method.GET },\n});\n```\n:::\n\n\n\n\nTherefore, the `MethodMap` object is basically a `std::map` object from C++, or,\na `dict` object from Python. You can retrieve (or get) the enum value that\ncorresponds to a particular key, by using the `get()` method from the map\nobject. This method returns an optional value, so, the `get()` method might\nresult in a null value.\n\nWe can use this in our advantage to detect if a particular HTTP method is\nsupported or not in our HTTP server. Because, if the `get()` method returns null,\nit means that it did not found the method that we provided inside the `MethodMap` object, and,\nas a consequence, this method is not supported by our HTTP server.\n\nThe `init()` method below, takes a string value as input, and then, it simply passes this string value\nto the `get()` method of our `MethodMap` object. As consequence, we should get the enum value that corresponds\nto this input string.\n\nNotice in the example below that, the `init()` method returns either an error\n(which might happen if the `?` method returns `unreacheable`, checkout @sec-null-handling for more details)\nor a `Method` object as result. Since `GET` is currently the only value in our `Method` enum\nstructure, it means that, the `init()` method will most likely return the value `Method.GET` as result.\n\nAlso notice that, in the `is_supported()` method, we are using the optional value returned\nby the `get()` method from our `MethodMap` object. The if statement unwraps the optional value\nreturned by this method, and returns `true` in case this optional value is a not-null value.\nOtherwise, it simply returns `false`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const Method = enum {\n    GET,\n    pub fn init(text: []const u8) !Method {\n        return MethodMap.get(text).?;\n    }\n    pub fn is_supported(m: []const u8) bool {\n        const method = MethodMap.get(m);\n        if (method) |_| {\n            return true;\n        }\n        return false;\n    }\n};\n```\n:::\n\n\n\n\n\n\n\n\n\n\n### Writing the parse request function\n\nNow that we created the enum that represents our HTTP method,\nwe should start to write the function responsible for\nactually parsing the HTTP Request.\n\nThe first thing we can do, is to write a struct to represent the HTTP Request.\nTake the `Request` struct below as an example. It contains the three\nessential information from the \"top-level\" header (i.e., the first line)\nin the HTTP Request.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Request = struct {\n    method: Method,\n    version: []const u8,\n    uri: []const u8,\n    pub fn init(method: Method,\n                uri: []const u8,\n                version: []const u8) Request {\n        return Request{\n            .method = method,\n            .uri = uri,\n            .version = version,\n        };\n    }\n};\n```\n:::\n\n\n\n\n\nThe `parse_request()` function should receive a string as input. This input string\ncontains the entire HTTP Request message, and the parsing function should\nread and understand the individual parts of this message.\n\nNow, remember that for the purpose of this chapter, we care only about the first\nline in this message, which contains the \"top-level header\", or, the three essential attributes about the HTTP Request,\nwhich are the HTTP method used, the URI and the HTTP version.\n\nNotice that I use the function `indexOfScalar()` in `parse_request()`. This function from the\nZig Standard Library returns the first index where the scalar value that we provide\nhappens in a string. In this case, I'm looking at the first occurrence of the new line character (`\\n`).\nBecause once again, we care only about the first line in the HTTP Request message.\nThis is the line where we have the three information that we want to parse\n(version of HTTP, the HTTP method and the URI).\n\nTherefore, we are using this `indexOfScalar()` function\nto limit our parsing process to the first line in the message.\nIt's also worth mentioning that, the `indexOfScalar()` function returns an optional value.\nThat is why I use the `orelse` keyword to provide an alternative value, in case\nthe value returned by the function is a null value.\n\nSince each of these three attributes are separated by a simple space, we\ncould use the function `splitScalar()` from the Zig Standard Library to split\nthe input string into sections by looking for every position that appears\na simple space. In other words, this `splitScalar()` function is equivalent\nto the `split()` method in Python, or, the `std::getline()` function from C++,\nor the `strtok()` function in C.\n\nWhen you use this `splitScalar()` function, you get an iterator as the result.\nThis iterator have a `next()` method that you can use to advance the iterator\nto the next position, or, to the next section of the splitted string.\nNote that, when you use `next()`, the method not only advances the iterator,\nbut it also returns a slice to the current section of the splitted\nstring as result.\n\nNow, if you want to get a slice to the current section of the splitted\nstring, but not advance the iterator to the next position, you can use\nthe `peek()` method. Both `next()` and `peek()` methods return an optional value, that is\nwhy I use the `?` method to unwrap these optional values.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn parse_request(text: []u8) Request {\n    const line_index = std.mem.indexOfScalar(\n        u8, text, '\\n'\n    ) orelse text.len;\n    var iterator = std.mem.splitScalar(\n        u8, text[0..line_index], ' '\n    );\n    const method = try Method.init(iterator.next().?);\n    const uri = iterator.next().?;\n    const version = iterator.next().?;\n    const request = Request.init(method, uri, version);\n    return request;\n}\n```\n:::\n\n\n\n\n\nAs I described in @sec-zig-strings, strings in Zig are simply arrays of bytes in the language.\nSo, you will find lots of excellent utility functions to work directly with strings\ninside this `mem` module from the Zig Standard Library.\nWe have described some of these useful utility functions already\nin @sec-strings-useful-funs.\n\n\n\n### Using the parse request function\n\nNow that we wrote the function responsible for parsing the HTTP Request,\nwe can add the function call to `parse_request()` in\nthe `main()` function of our program.\n\nAfter that, is a good idea to test once again the state of our program.\nI execute this program again with the `run` command from the `zig` compiler,\nthen, I use my web browser to connect once again to the server through the URL `localhost:3490`, and finally,\nthe end result of our `Request` object is printed to the console.\n\nA quick observation, since I have used the `any` format specifier in the\nprint statement, the data members `version` and `uri` of the `Request`\nstruct were printed as raw integer values. String data being printed\nas integer values is common in Zig, and remember, these integer values are just the decimal representation of\nthe bytes that form the string in question.\n\nIn the result below, the sequence of decimal values 72, 84, 84, 80, 47, 49, 46, 49, and 13,\nare the bytes that form the text \"HTTP/1.1\". And the integer 47, is the decimal value of\nthe character `/`, which represents our URI in this request.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    try Request.read_request(\n        connection, buffer[0..buffer.len]\n    );\n    const request = Request.parse_request(\n        buffer[0..buffer.len]\n    );\n    try stdout.print(\"{any}\\n\", .{request});\n}\n```\n:::\n\n\n\n\n```\nrequest.Request{\n    .method = request.Method.GET,\n    .version = {72, 84, 84, 80, 47, 49, 46, 49, 13},\n    .uri = {47}\n}\n```\n\n\n\n### Sending the HTTP Response to the client\n\nIn this last part, we are going to write the logic responsible for\nsending the HTTP Response from the server to the client. To make things\nsimple, the server in this project will send just a simple web page\ncontaining the text \"Hello world\".\n\nFirst, I create a new Zig module in the project, named `response.zig`.\nIn this module, I will declare just two functions. Each function\ncorresponds to a specific status code in the HTTP Response.\nThe `send_200()` function will send a HTTP Response with status code 200\n(which means \"Success\") to the client. While the `send_404()` function sends a response\nwith status code 404 (which means \"Not found\").\n\nThis is definitely not the most ergonomic and adequate way of handling the\nHTTP Response, but it works for our case here. We are just building toy projects\nin this book after all, therefore, the source code that we write do not need to be perfect.\nIt just needs to work!\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Connection = std.net.Server.Connection;\npub fn send_200(conn: Connection) !void {\n    const message = (\n        \"HTTP/1.1 200 OK\\nContent-Length: 48\"\n        ++ \"\\nContent-Type: text/html\\n\"\n        ++ \"Connection: Closed\\n\\n<html><body>\"\n        ++ \"<h1>Hello, World!</h1></body></html>\"\n    );\n    _ = try conn.stream.write(message);\n}\n\npub fn send_404(conn: Connection) !void {\n    const message = (\n        \"HTTP/1.1 404 Not Found\\nContent-Length: 50\"\n        ++ \"\\nContent-Type: text/html\\n\"\n        ++ \"Connection: Closed\\n\\n<html><body>\"\n        ++ \"<h1>File not found!</h1></body></html>\"\n    );\n    _ = try conn.stream.write(message);\n}\n```\n:::\n\n\n\n\nNotice that both functions receives the connection object as input, and\nuse the `write()` method to write the HTTP Response message directly\ninto this communication channel. As result, the party in the other\nside of the connection (i.e., the client), will receive such message.\n\nMost real-world HTTP Servers will have a single function (or a single struct) to effectively handle\nthe response. It gets the HTTP Request already parsed as input, and then, it tries to build\nthe HTTP Response bit by bit, before the function sends it over the connection.\n\nWe would also have a specialized struct to represent a HTTP Response, and\na lot of methods that would be used to build each part or component of the response object.\nTake the `Response` struct created by the Javascript runtime Bun as an example.\nYou can find this struct in the [`response.zig` module](https://github.com/oven-sh/bun/blob/main/src/bun.js/webcore/response.zig)[^bun-resp]\nin their GitHub project.\n\n[^bun-resp]: <https://github.com/oven-sh/bun/blob/main/src/bun.js/webcore/response.zig>.\n\n\n## The end result\n\nWe can now, update once again our `main()` function to incorporate our new\nfunctions from the `response.zig` module. First, I need to import this module\ninto our `main.zig` module, then, I add the function calls to `send_200()`\nand `send_404()`.\n\nNotice that I'm using if statements to decide which \"response function\" to call,\nbased especially on the URI present in the HTTP Request. If the user asked for\na content (or a document) that is not present in our server, we should respond\nwith a 404 status code. But since we have just a simple HTTP server, with no\nreal documents to send, we can just check if the URI is the root path (`/`)\nor not to decide which function to call.\n\nAlso, notice that I'm using the function `std.mem.eql()` from the Zig Standard Library\nto check if the string from `uri` is equal or not the string `\"/\"`. We have\ndescribed this function already in @sec-strings-useful-funs, so, comeback to\nthat section if you are not familiar yet with this function.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst Response = @import(\"response.zig\");\nconst Method = Request.Method;\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    try Request.read_request(connection, buffer[0..buffer.len]);\n    const request = Request.parse_request(\n        buffer[0..buffer.len]\n    );\n    if (request.method == Method.GET) {\n        if (std.mem.eql(u8, request.uri, \"/\")) {\n            try Response.send_200(connection);\n        } else {\n            try Response.send_404(connection);\n        }\n    }\n}\n```\n:::\n\n\n\n\n\nNow that we adjusted our `main()` function, I can now execute our program, and\nsee the effects of these last changes. First, I execute the program once again, with the\n`run` command of the `zig` compiler. The program will hang, waiting for a client to connect.\n\nThen, I open my web browser, and try to connect to the server again, using the URL `localhost:3490`.\nThis time, instead of getting some sort of an error message from the browser, you will get the message\n\"Hello World\" printed into your web browser. Because this time, the server sended the HTTP Response\nsuccessfully to the web browser, as demonstrated by @fig-print-zigrun3.\n\n\n![The Hello World message sent in the HTTP Response](./../Figures/print-zigrun3.png){#fig-print-zigrun3}\n",
-    "supporting": [
-      "04-http-server_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n# Project 2 - Building a HTTP Server from scratch\n\nIn this chapter, I want to implement a new\nsmall project with you. This time, we are going\nto implement a basic HTTP Server from scratch.\n\nThe Zig Standard Library already have a HTTP Server\nimplemented, which is available at `std.http.Server`.\nBut again, our objective here in this chapter, is to implement\nit **from scratch**. So we can't use this server object available\nfrom the Zig Standard Library.\n\n## What is a HTTP Server?\n\nFirst of all, what is a HTTP Server?\nA HTTP server, as any other type of server, is essentially\na program that runs indefinitely, on an infinite loop, waiting for incoming connections\nfrom clients. Once the server receives an incoming connection, it will\naccept this connection, and it will send messages back-and-forth to the client\nthrough this connection.\n\nBut the messages that are transmitted inside this connection are in a\nspecific format. They are HTTP messages\n(i.e., messages that use the HTTP Protocol specification).\nThe HTTP Protocol is the backbone of the modern web.\nThe world wide web as we know it today, would not exist without the\nHTTP Protocol.\n\nSo, Web servers (which is just a fancy name to\nHTTP Servers) are servers that exchange HTTP messages with clients.\nAnd these HTTP servers and the HTTP Protocol specification\nare essential to the operation of the world wide web today.\n\nThat is the whole picture of the process.\nAgain, we have two subjects involved here, a server (which is\na program that is running indefinitely, waiting to receive incoming connections),\nand a client (which is someone that wants to connect to the server,\nand exchange HTTP messages with it).\n\nYou may find the material about the [HTTP Protocol available at the Mozilla MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview)[^mdn-http]\n, a great resource for you to also look at. It gives you a great overview on how\nHTTP works, and what role the server plays in this matter.\n\n[^mdn-http]: <https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview>.\n\n\n## How a HTTP Server works? {#sec-how-http-works}\n\nImagine a HTTP Server as if it were the receptionist of a large hotel. In a hotel,\nyou have a reception, and inside that reception there is a receptionist\nwaiting for customers to arrive. A HTTP Server is essentially a receptionist\nthat is indefinitely waiting for new customers (or, in the context of HTTP, new clients)\nto arrive in the hotel.\n\nWhen a customer arrives at the hotel, that customer starts a conversation with the\nreceptionist. He tells the receptionist how many days he wants to stay at the hotel.\nThen, the receptionist search for an available apartment. If there is an available apartment\nat the moment, the customer pays the hotel fees, then, he gets the keys to the apartment,\nand then, he goes to the apartment to rest.\n\nAfter this entire process of dealing with the customer (searching for available apartments,\nreceiving payment, handing over the keys), the receptionist goes back to what he was\ndoing earlier, which is to wait. Wait for new customers to arrive.\n\nThat is, in a nutshell, what a HTTP Server do. It waits for clients to connect to the\nserver. When a client attempts to connect to the server, the server accepts this connection,\nand it starts to exchange messages with the client through this connection.\nThe first message that happens inside this connection is always a message from the client\nto the server. This message is called the *HTTP Request*.\n\nThis HTTP Request is a HTTP message that contains what\nthe client wants from the server. It is literally a request. The client\nthat connected to the server is asking this server to do something for him.\n\nThere are different \"types of request\" that a client can send to a HTTP Server.\nBut the most basic type of request, is when a client ask to the\nHTTP Server to serve (i.e., to send) some specific web page (which is a HTML file) to him.\nWhen you type `google.com` in your web browser, you are essentially sending a HTTP Request to Google's\nHTTP servers. This request is asking these servers to send the Google webpage to you.\n\nNonetheless, when the server receives this first message, the *HTTP Request*, it\nanalyzes this request, to understand: who the client is? What he wants the server to do?\nThis client has provided all the necessary information to perform the action that he\nasked? Etc.\n\nOnce the server understands what the client wants, he simply perform the action\nthat was requested, and, to finish the whole process, the server sends back\na HTTP message to the client, informing if the action performed was successful or not,\nand, at last, the server ends (or closes) the connection with the client.\n\nThis last HTTP message sent from the server to the client, is called the *HTTP Response*.\nBecause the server is responding to the action that was requested by the client.\nThe main objective of this response message is let the client know if the\naction requested was successful or not, before the server closes the connection.\n\n\n## How a HTTP server is normally implemented? {#sec-http-how-impl}\n\nLet's use the C language as an example. There are many materials\nteaching how to write a simple HTTP server in C code, like @jeffrey_http,\nor @nipun_http, or @eric_http.\nHaving this in mind, I will not show C code examples here, because you\ncan find them on the internet.\nBut I will describe the theory behind the necessary steps to create\nsuch HTTP server in C.\n\n\nIn essence, we normally implement a HTTP server in C by using a TCP socket,\nwhich involves the following steps:\n\n1. Create a TCP socket object.\n1. Bind a name (or more specifically, an address) to this socket object.\n1. Make this socket object to start listening and waiting for incoming connections.\n1. When a connection arrive, we accept this connection, and we exchange the HTTP messages (HTTP Request and HTTP Response).\n1. Then, we simply close this connection.\n\n\nA socket object is essentially a channel of communication.\nYou are creating a channel where people can send messages through.\nWhen you create a socket object, this object is not binded to any particular\naddress. This means that with this object you have a representation of a channel of communication\nin your hands. But this channel is not currently available, or, it is not currently accessible,\nbecause it does not have a known address where you can find it.\n\nThat is what the \"bind\" operation do. It binds a name (or more specifically, an address) to\nthis socket object, or, this channel of communication, so that it becomes available,\nor, accessible through this address. While the \"listen\" operation makes the socket object to\nlisten for incoming connections in this address. In other words, the \"listen\" operation\nmakes the socket wait for incoming connections.\n\nNow, when a client actually attempts to connect to the server through the socket address\nthat we have specified, in order to establish this connection with the client,\nthe socket object needs to accept this incoming connection. Thus, when we\naccept an incoming connection, the client and the server become\nconnected to each other, and they can start reading or writing messages into this\nestablished connection.\n\nAfter we receive the HTTP Request from the client, analyze it, and send the HTTP Response\nto the client, we can then close the connection, and end this communication.\n\n\n## Implementing the server - Part 1\n\n### Creating the socket object {#sec-create-socket}\n\nLet's begin with creating the socket object for our server.\nJust to make things shorter, I will create this socket object in\na separate Zig module. I will name it `config.zig`.\n\nIn Zig, we can create a TCP socket using\nthe `std.posix.socket()` function, from the Zig Standard Library.\nAs I mentioned earlier in @sec-http-how-impl, every socket object that we create\nrepresents a communication channel, and we need to bind this channel to a specific address.\nAn \"address\" is defined as an IP address, or, more specifically, an IPv4 address^[It can be also an IPv6 address. But normally, we use a IPv4 address for that.].\nEvery IPv4 address is composed by two components. The first component is the host,\nwhich is a sequence of 4 numbers separated by dot characters (`.`) that identifies the machine used.\nWhile the second component is a port number, which identifies the specific\ndoor, or, the specific port to use in the host machine.\n\nThe sequence of 4 numbers (i.e., the host) identifies the machine (i.e., the computer itself) where\nthis socket will live in. Every computer normally have multiple \"doors\" available inside of him, because\nthis allows the computer to receive and work with multiple connections at the same time.\nHe simply use a single door for each connection. So the port number, is\nessentially a number that identifies the specific door in the computer that will be responsible\nfor receiving the connection. That is, it identifies the \"door\" in the computer that the socket will use\nto receive incoming connections.\n\nTo make things simpler, I will use an IP address that identifies our current machine in this example.\nThis means that, our socket object will reside on the same computer that we are currently using\n(this is also known as the \"localhost\") to write this Zig source code.\n\nBy convention, the IP address that identifies the \"localhost\", which is the current machine we\nare using, is the IP `127.0.0.1`. So, that is the IP\naddress we are going to use in our server. I can declare it in Zig\nby using an array of 4 integers, like this:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst localhost = [4]u8{ 127, 0, 0, 1 };\n_ = localhost;\n```\n:::\n\n\nNow, we need to decide which port number to use. By convention, there are some\nport numbers that are reserved, meaning that, we cannot use them for our own\npurposes, like the port 22 (which is normally used for SSH connections).\nFor TCP connections, which is our case here,\na port number is a 16-bit unsigned integer (type `u16` in Zig),\nthus ranging from 0 to 65535 [@wikipedia_port].\nSo, we can choose\na number from 0 to 65535 for our port number. In the\nexample of this book, I will use the port number 3490\n(just a random number).\n\n\nNow that we have these two informations at hand, I can\nfinally create our socket object, using the `std.posix.socket()` function.\nFirst, we use the host and the port number to create an `Address` object,\nwith the `std.net.Address.initIp4()` function, like in the example below.\nAfter that, I use this address object inside the `socket()` function\nto create our socket object.\n\nThe `Socket` struct defined below summarizes all the logic behind\nthis process. In this struct, we have two data members, which are:\n1)  the address object; 2) and a stream object, which is\nthe object we will use to read and write the messages into any connection we establish.\n\nNotice that, inside the constructor method of this struct,\nwhen we create the socket object, we are using the `IPROTO.TCP` property as an input to\ntell the function to create a socket for TCP connections.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst builtin = @import(\"builtin\");\nconst net = @import(\"std\").net;\n\npub const Socket = struct {\n    _address: std.net.Address,\n    _stream: std.net.Stream,\n\n    pub fn init() !Socket {\n        const host = [4]u8{ 127, 0, 0, 1 };\n        const port = 3490;\n        const addr = net.Address.initIp4(host, port);\n        const socket = try std.posix.socket(\n            addr.any.family,\n            std.posix.SOCK.STREAM,\n            std.posix.IPPROTO.TCP\n        );\n        const stream = net.Stream{ .handle = socket };\n        return Socket{ ._address = addr, ._stream = stream };\n    }\n};\n```\n:::\n\n\n\n### Listening and receiving connections\n\nRemember that we stored the `Socket` struct\ndeclaration that we built in @sec-create-socket inside a Zig module named `config.zig`.\nThis is why I imported this module into our main module (`main.zig`) in the example below, as the `SocketConf` object,\nto access the `Socket` struct.\n\nOnce we created our socket object, we can focus now on making this socket object\nlisten and receive new incoming connections. We do that, by calling the `listen()`\nmethod from the `Address` object that is contained inside the socket object, and then,\nwe call the `accept()` method over the result.\n\nThe `listen()` method from the `Address` object produces a server object,\nwhich is an object that will stay open and running indefinitely, waiting\nto receive an incoming connection. Therefore, if you try to run the code\nexample below, by calling the `run` command from the `zig` compiler,\nyou will notice that the programs keeps running indefinitely,\nwithout a clear end.\n\nThis happens, because the program is waiting for something to happen.\nIt's waiting for someone to try to connect to the address (`http://127.0.0.1:3490`) where\nthe server is running and listening for incoming connections. This is what\nthe `listen()` method do, it makes the socket to be active waiting for someone\nto connect.\n\nOn the other side, the `accept()` method is the function that establishes the connection\nwhen someone tries to connect to the socket. This means that, the `accept()` method\nreturns a new connection object as a result. And you can use this connection object\nto read or write messages from or to the client.\nFor now, we are not doing anything with this connection object.\nBut we are going to use it in the next section.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n    _ = connection;\n}\n```\n:::\n\n\nThis code example allows one single connection. In other words, the\nserver will wait for one incoming connection, and as soon as the\nserver is done with this first connection that it establishes, the\nprogram ends, and the server stops.\n\nThis is not the norm in the real world. Most people that write\na HTTP server like this, usually put the `accept()` method\ninside a `while` (infinite) loop, where if a connection\nis created with `accept()`, a new thread of execution is created to deal with\nthis new connection and the client. That is, real-world examples of HTTP Servers\nnormally rely on parallel computing to work.\n\nWith this design, the server simply accepts the connection,\nand the whole process of dealing with the client, and receiving\nthe HTTP Request, and sending the HTTP Response, all of this\nis done in the background, on a separate execution thread.\n\nSo, as soon as the server accepts the connection, and creates\nthe separate thread, the server goes back to what he was doing earlier,\nwhich is to wait indefinitely for a new connection to accept.\nHaving this in mind, the code example exposed above, is a\nserver that serves only a single client. Because the program\nterminates as soon as the connection is accepted.\n\n\n\n### Reading the message from the client {#sec-read-http-message}\n\nNow that we have a connection established, i.e., the connection\nobject that we created through the `accept()` function, we can now\nuse this connection object to read any messages that the client\nsend to our server. But we can also use it to send messages back\nto the client.\n\nThe basic idea is, if we **write** any data into this connection object,\nthen, we are sending data to the client, and if we **read** the data present in\nthis connection object, then, we are reading any data that the\nclient sent to us, through this connection object. So, just\nhave this logic in mind. \"Read\" is for reading messages from the client,\nand \"write\" is to send a message to the client.\n\nRemember from @sec-how-http-works that, the first thing that we need to do is to read the HTTP Request\nsent by the client to our server. Because it is the first message that happens\ninside the established connection, and, as a consequence, it is the first\nthing that we need to deal with.\n\nThat is why, I'm going to create a new Zig module in this small project, named `request.zig`\nto keep all functions related to the HTTP Request\ntogether. Then, I will create a new function named `read_request()` that will\nuse our connection object to read the message sent by the client,\nwhich is the HTTP Request.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Connection = std.net.Server.Connection;\npub fn read_request(conn: Connection,\n                    buffer: []u8) !void {\n    const reader = conn.stream.reader();\n    _ = try reader.read(buffer);\n}\n```\n:::\n\n\n\nThis function accepts a slice object which behaves as a buffer.\nThe `read_request()` function reads the message sent into\nthe connection object, and saves this message into this buffer object that\nwe have provided as input.\n\nNotice that I'm using the connection object that we created to read\nthe message from the client. I first access the `reader` object that lives inside the\nconnection object. Then, I call the `read()` method of this `reader` object\nto effectively read and save the data sent by the client into the buffer object\nthat we created earlier. I'm discarding the return value\nof the `read()` method, by assigning it to the underscore character (`_`),\nbecause this return value is not useful for us right now.\n\n\n\n## Looking at the current state of the program\n\n\nI think now is a good time to see how our program is currently working. Shall we?\nSo, the first thing I will do is to update the `main.zig` module in our small Zig project,\nso that the `main()` function call this new `read_request()` function that we have just created.\nI will also add a print statement at the end of the `main()` function,\njust so that you can see what the HTTP Request that we have just loaded into the buffer object\nlooks like.\n\nAlso, I'm creating the buffer object in the `main()` function, which will be\nresponsible for storing the message sent by the client, and, I'm also\nusing a `for` loop to initialize all fields of this buffer object to the number zero.\nThis is important to make sure that we don't have uninitialized memory in\nthis object. Because uninitialized memory may cause undefined behaviour in our program.\n\nSince the `read_request()` function should receive as input the buffer object as a slice object (`[]u8`),\nI am using the syntax `array[0..array.len]` to get access to a slice of this `buffer` object.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    _ = try Request.read_request(\n        connection, buffer[0..buffer.len]\n    );\n    try stdout.print(\"{s}\\n\", .{buffer});\n}\n```\n:::\n\n\nNow, I'm going to execute this program, with the `run` command from the\n`zig` compiler. But remember, as we sad earlier, as soon as I execute this program, it will\nhang indefinitely, because the program is waiting for a client trying to\nconnect to the server.\n\nMore specifically, the program will pause at the line\nwith the `accept()` call. As soon as a client try to connect to the\nserver, then, the execution will \"unpause\", and the `accept()` function\nwill finally be executed to create the\nconnection object that we need, and the remaining of the program\nwill run.\n\nYou can see that in @fig-print-zigrun1. The message `Server Addr: 127.0.0.1:3490`\nis printed to the console, and the program is now waiting for an incoming connection.\n\n![A screenshot of running the program](./../Figures/print-zigrun1.png){#fig-print-zigrun1}\n\n\nWe can finally try to connect to this server, and there are several ways we can do this.\nFor example, we could use the following Python script:\n\n```python\nimport requests\nrequests.get(\"http://127.0.0.1:3490\")\n```\n\nOr, we could also open any web browser of our preference, and type\nthe URL `localhost:3490`. OBS: `localhost` is the same thing as the\nIP `127.0.0.1`. When you press enter, and your web browser go\nto this address, first, the browser will probably print a message\nsaying that \"this page isn't working\", and, then, it will\nprobably change to a new message saying that \"the site can't be\nreached\".\n\nYou get these \"error messages\" in the web browser, because\nit got no response back from the server. In other words, when the web\nbrowser connected to our server, it did send the HTTP Request through the established connection.\nThen, the web browser was expecting to receive a HTTP Response back, but\nit got no response from the server (we didn't implemented the HTTP Response logic yet).\n\nBut that is okay. We have achieved the result that we wanted for now,\nwhich is to connect to the server, and see the HTTP Request\nthat was sent by the web browser (or by the Python script)\nto the server.\n\nIf you comeback to the console that you left open\nwhen you have executed the program, you will see that the\nprogram finished its execution, and, a new message is\nprinted in the console, which is the actual HTTP Request\nmessage that was sent by the web browser to the server.\nYou can see this message in @fig-print-zigrun2.\n\n![A screenshot of the HTTP Request sent by the web browser](./../Figures/print-zigrun2.png){#fig-print-zigrun2}\n\n\n\n\n## Learning about Enums in Zig {#sec-enum}\n\nEnums structures are available in Zig through the `enum` keyword.\nAn enum (short for \"enumeration\") is a special structure that represents a group of constant values.\nSo, if you have a variable which can assume a short and known\nset of values, you might want to associate this variable to an enum structure,\nto make sure that this variable only assumes a value from this set.\n\nA classic example for enums are primary colors. If for some reason, your program\nneeds to represent one of the primary colors, you can create an enum\nthat represents one of these colors.\nIn the example below, we are creating the enum `PrimaryColorRGB`, which\nrepresents a primary color from the RGB color system. By using this enum,\nI am guaranteed that the `acolor` object for example, will contain\none of these three values: `RED`, `GREEN` or `BLUE`.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst PrimaryColorRGB = enum {\n    RED, GREEN, BLUE\n};\nconst acolor = PrimaryColorRGB.RED;\n_ = acolor;\n```\n:::\n\n\nIf for some reason, my code tries to save in `acolor`,\na value that is not in this set, I will get an error message\nwarning me that a value such as \"MAGENTA\" do not exist\ninside the `PrimaryColorRGB` enum.\nThen I can easily fix my mistake.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst acolor = PrimaryColorRGB.MAGENTA;\n```\n:::\n\n\n```\ne1.zig:5:36: error: enum 'PrimaryColorRGB' has\n        no member named 'MAGENTA':\n    const acolor = PrimaryColorRGB.MAGENTA;\n                                   ^~~~~~~\n```\n\nBehind the hood, enums in Zig work the same way that enums\nwork in C. Each enum value is essentially represented as an integer.\nThe first value in the set is represented as zero,\nthen, the second value is one, ... etc.\n\nOne thing that we are going to learn in the next section is that\nenums can have methods in them. Wait... What? This is amazing!\nYes, enums in Zig are similar to structs, and they can have\nprivate and public methods inside them.\n\n\n\n\n\n\n\n## Implementing the server - Part 2\n\nNow, on this section, I want to focus on parsing\nthe HTTP Request that we received from the client.\nHowever, to effectively parse a HTTP Request message, we first need to understand its\nstructure.\nIn summary, a HTTP Request is a text message that is divided into 3 different\nsections (or parts):\n\n- The top-level header indicating the method of the HTTP Request, the URI, and the HTTP version used in the message.\n- A list of HTTP Headers.\n- The body of the HTTP Request.\n\n### The top-level header\n\nThe first line of text in a HTTP Request always come with the three most essential\ninformation about the request. These three key attributes of the HTTP Request\nare separated by a simple space in this first line of the request.\nThe first information is the HTTP method that is being\nused in the request, second, we have the URI to which this HTTP Request is being sent to,\nand third, we have the version of the HTTP protocol that is being used in this HTTP Request.\n\nIn the snippet below, you can find an example of this first line in a HTTP Request.\nFirst, we have the HTTP method of this request (`GET`). Many programmers\nrefer to the URI component (`/users/list`) as the \"API endpoint\" to which the HTTP Request\nis being sent to. In the context of this specific request, since it's a GET request,\nyou could also say that the URI component is the path to the resource we want to access,\nor, the path to the document (or the file) that we want to retrieve from the server.\n\n```\nGET /users/list HTTP/1.1\n```\n\nAlso, notice that this HTTP Request is using the version 1.1 of the HTTP protocol,\nwhich is the most popular version of the protocol used in the web.\n\n\n\n### The list of HTTP headers\n\nMost HTTP Requests also include a section of HTTP Headers,\nwhich is just a list of attributes or key-value pairs associated with this\nparticular request. This section always comes right after the \"top-level header\" of the request.\n\nFor our purpose in this chapter, which is to build a simple HTTP Server,\nwe are going to ignore this section of the HTTP Request, for simplicity.\nBut most HTTP servers that exist in the wild parses and use these\nHTTP headers to change the way that the server responds to the request\nsent by the client.\n\nFor example, many requests we encounter in the real-world comes with\na HTTP header called `Accept`. In this header, we find a list of [MIME types](https://en.wikipedia.org/wiki/Media_type)[^mime].\nThis list indicates the file formats that the client can read, or parse, or interpret.\nIn other words, you also interpret this header as the client saying the following phrase\nto the server: \"Hey! Look, I can read only HTML documents, so please, send me back\na document that is in a HTML format.\".\n\n[^mime]: <https://en.wikipedia.org/wiki/Media_type>.\n\nIf the HTTP server can read and use this `Accept` header, then, the server can identify\nwhich is the best file format for the document to be sent to the client. Maybe the HTTP server have\nthe same document in multiple formats, for example, in JSON, in XML, in HTML and in PDF,\nbut the client can only understand documents in the HTML format. That is the purpose\nof this `Accept` header.\n\n\n### The body\n\nThe body comes after the list of HTTP headers, and it's an optional section of the HTTP Request, meaning that, not\nall HTTP Requests will come with a body in them. For example, every HTTP Request that uses the\nGET method usually does not come with a body.\n\nBecause a GET request is used to request data, instead of sending it to the server.\nSo, the body section is more related to the POST method, which is a method that involves\nsending data to the server, to be processed and stored.\n\nSince we are going to support only the GET method in this project, it means that\nwe also do not need to care about the body of the request.\n\n\n\n### Creating the HTTP Method enum\n\nEvery HTTP Request comes with a explicit method. The method used in a HTTP Request\nis identified by one these words:\n\n- GET;\n- POST;\n- OPTIONS;\n- PATCH;\n- DELETE;\n- and some other methods.\n\nEach HTTP method is used for a specific type of task. The POST method for example is normally\nused to post some data into the destination. In other words, it's used\nto send some data to the HTTP server, so that it can be processed and stored by the server.\n\nAs another example, the GET method is normally used to get content from the server.\nIn other words, we use this method whenever we want the server to send some\ncontent back to us. It can be any type of content. It can be a web page,\na document file, or some data in a JSON format.\n\nWhen a client sends a POST HTTP Request, the HTTP Response sent by the server normally have the sole purpose of\nletting the client know if the server processed and stored the data successfully.\nIn contrast, when the server receives a GET HTTP Request, then, the server sends the content\nthat the client asked for in the HTTP Response itself. This demonstrates that the method associated\nwith the HTTP Request changes a lot on the dynamics and the roles that each party\nplays in the whole process.\n\nSince the HTTP method of the HTTP Request is identified by this very small and specific\nset of words, it would be interesting to create an enum structure to represent a HTTP method.\nThis way, we can easily check if the HTTP Request we receive from the client is a\nHTTP method that we currently support in our small HTTP server project.\n\nThe `Method` structure below represents this enumeration.\nNotice that, for now, only the GET HTTP method is included in this\nenumeration. Because, for the purpose of this chapter, I want to\nimplement only the GET HTTP method. That is why I am not\nincluding the other HTTP methods in this enumeration.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const Method = enum {\n    GET\n};\n```\n:::\n\n\n\nNow, I think we should add two methods to this enum structure. One method is `is_supported()`,\nwhich will be a function that returns a boolean value, indicating if the input HTTP method is supported\nor not by our HTTP Server. The other is `init()`, which is a constructor function that takes a string as input,\nand tries to convert it into a `Method` value.\n\n\nBut in order to build these functions, I will use a functionality from the Zig Standard Library, called\n`StaticStringMap()`. This function allows us to create a simple map from strings to enum values.\nIn other words, we can use this map structure to map a string to the respective enum value.\nTo some extent, this specific structure from the standard library works almost like a \"hashtable\" structure,\nand it's optimized for small sets of words, or, small sets of keys, which is our case here.\nWe are going to talk more about hashtables in Zig in @sec-maps-hashtables.\n\nTo use this \"static string map\" structure, you have to import it from the `std.static_string_map` module\nof the Zig Standard Library. Just to make things shorter and easier to type, I am going to import this\nfunction through a different and shorter name (`Map`).\n\nWith `Map()` imported, we can just apply this function over the enum structure\nthat we are going to use in the resulting map. In our case here, it's the `Method` enum structure\nthat we declared at the last code example. Then, I call the `initComptime()` method with the\nmap, i.e., the list of key-value pairs that we are going to use.\n\nYou can see in the example below that I wrote this map using multiple anonymous struct literals.\nInside the first (or \"top-level\") struct literal, we have a list (or a sequence) of struct literals.\nEach struct literal in this list represents a separate key-value pair. The first element (or the key)\nin each key-value pair should always be a string value. While the second element should\nbe a value from the enum structure that you have used inside the `Map()` function.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Map = std.static_string_map.StaticStringMap;\nconst MethodMap = Map(Method).initComptime(.{\n    .{ \"GET\", Method.GET },\n});\n```\n:::\n\n\nTherefore, the `MethodMap` object is basically a `std::map` object from C++, or,\na `dict` object from Python. You can retrieve (or get) the enum value that\ncorresponds to a particular key, by using the `get()` method from the map\nobject. This method returns an optional value, so, the `get()` method might\nresult in a null value.\n\nWe can use this in our advantage to detect if a particular HTTP method is\nsupported or not in our HTTP server. Because, if the `get()` method returns null,\nit means that it did not found the method that we provided inside the `MethodMap` object, and,\nas a consequence, this method is not supported by our HTTP server.\n\nThe `init()` method below, takes a string value as input, and then, it simply passes this string value\nto the `get()` method of our `MethodMap` object. As consequence, we should get the enum value that corresponds\nto this input string.\n\nNotice in the example below that, the `init()` method returns either an error\n(which might happen if the `?` method returns `unreacheable`, checkout @sec-null-handling for more details)\nor a `Method` object as result. Since `GET` is currently the only value in our `Method` enum\nstructure, it means that, the `init()` method will most likely return the value `Method.GET` as result.\n\nAlso notice that, in the `is_supported()` method, we are using the optional value returned\nby the `get()` method from our `MethodMap` object. The if statement unwraps the optional value\nreturned by this method, and returns `true` in case this optional value is a not-null value.\nOtherwise, it simply returns `false`.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const Method = enum {\n    GET,\n    pub fn init(text: []const u8) !Method {\n        return MethodMap.get(text).?;\n    }\n    pub fn is_supported(m: []const u8) bool {\n        const method = MethodMap.get(m);\n        if (method) |_| {\n            return true;\n        }\n        return false;\n    }\n};\n```\n:::\n\n\n\n\n\n\n\n\n### Writing the parse request function\n\nNow that we created the enum that represents our HTTP method,\nwe should start to write the function responsible for\nactually parsing the HTTP Request.\n\nThe first thing we can do, is to write a struct to represent the HTTP Request.\nTake the `Request` struct below as an example. It contains the three\nessential information from the \"top-level\" header (i.e., the first line)\nin the HTTP Request.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Request = struct {\n    method: Method,\n    version: []const u8,\n    uri: []const u8,\n    pub fn init(method: Method,\n                uri: []const u8,\n                version: []const u8) Request {\n        return Request{\n            .method = method,\n            .uri = uri,\n            .version = version,\n        };\n    }\n};\n```\n:::\n\n\n\nThe `parse_request()` function should receive a string as input. This input string\ncontains the entire HTTP Request message, and the parsing function should\nread and understand the individual parts of this message.\n\nNow, remember that for the purpose of this chapter, we care only about the first\nline in this message, which contains the \"top-level header\", or, the three essential attributes about the HTTP Request,\nwhich are the HTTP method used, the URI and the HTTP version.\n\nNotice that I use the function `indexOfScalar()` in `parse_request()`. This function from the\nZig Standard Library returns the first index where the scalar value that we provide\nhappens in a string. In this case, I'm looking at the first occurrence of the new line character (`\\n`).\nBecause once again, we care only about the first line in the HTTP Request message.\nThis is the line where we have the three information that we want to parse\n(version of HTTP, the HTTP method and the URI).\n\nTherefore, we are using this `indexOfScalar()` function\nto limit our parsing process to the first line in the message.\nIt's also worth mentioning that, the `indexOfScalar()` function returns an optional value.\nThat is why I use the `orelse` keyword to provide an alternative value, in case\nthe value returned by the function is a null value.\n\nSince each of these three attributes are separated by a simple space, we\ncould use the function `splitScalar()` from the Zig Standard Library to split\nthe input string into sections by looking for every position that appears\na simple space. In other words, this `splitScalar()` function is equivalent\nto the `split()` method in Python, or, the `std::getline()` function from C++,\nor the `strtok()` function in C.\n\nWhen you use this `splitScalar()` function, you get an iterator as the result.\nThis iterator have a `next()` method that you can use to advance the iterator\nto the next position, or, to the next section of the splitted string.\nNote that, when you use `next()`, the method not only advances the iterator,\nbut it also returns a slice to the current section of the splitted\nstring as result.\n\nNow, if you want to get a slice to the current section of the splitted\nstring, but not advance the iterator to the next position, you can use\nthe `peek()` method. Both `next()` and `peek()` methods return an optional value, that is\nwhy I use the `?` method to unwrap these optional values.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn parse_request(text: []u8) Request {\n    const line_index = std.mem.indexOfScalar(\n        u8, text, '\\n'\n    ) orelse text.len;\n    var iterator = std.mem.splitScalar(\n        u8, text[0..line_index], ' '\n    );\n    const method = try Method.init(iterator.next().?);\n    const uri = iterator.next().?;\n    const version = iterator.next().?;\n    const request = Request.init(method, uri, version);\n    return request;\n}\n```\n:::\n\n\n\nAs I described in @sec-zig-strings, strings in Zig are simply arrays of bytes in the language.\nSo, you will find lots of excellent utility functions to work directly with strings\ninside this `mem` module from the Zig Standard Library.\nWe have described some of these useful utility functions already\nin @sec-strings-useful-funs.\n\n\n\n### Using the parse request function\n\nNow that we wrote the function responsible for parsing the HTTP Request,\nwe can add the function call to `parse_request()` in\nthe `main()` function of our program.\n\nAfter that, is a good idea to test once again the state of our program.\nI execute this program again with the `run` command from the `zig` compiler,\nthen, I use my web browser to connect once again to the server through the URL `localhost:3490`, and finally,\nthe end result of our `Request` object is printed to the console.\n\nA quick observation, since I have used the `any` format specifier in the\nprint statement, the data members `version` and `uri` of the `Request`\nstruct were printed as raw integer values. String data being printed\nas integer values is common in Zig, and remember, these integer values are just the decimal representation of\nthe bytes that form the string in question.\n\nIn the result below, the sequence of decimal values 72, 84, 84, 80, 47, 49, 46, 49, and 13,\nare the bytes that form the text \"HTTP/1.1\". And the integer 47, is the decimal value of\nthe character `/`, which represents our URI in this request.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    try Request.read_request(\n        connection, buffer[0..buffer.len]\n    );\n    const request = Request.parse_request(\n        buffer[0..buffer.len]\n    );\n    try stdout.print(\"{any}\\n\", .{request});\n}\n```\n:::\n\n\n```\nrequest.Request{\n    .method = request.Method.GET,\n    .version = {72, 84, 84, 80, 47, 49, 46, 49, 13},\n    .uri = {47}\n}\n```\n\n\n\n### Sending the HTTP Response to the client\n\nIn this last part, we are going to write the logic responsible for\nsending the HTTP Response from the server to the client. To make things\nsimple, the server in this project will send just a simple web page\ncontaining the text \"Hello world\".\n\nFirst, I create a new Zig module in the project, named `response.zig`.\nIn this module, I will declare just two functions. Each function\ncorresponds to a specific status code in the HTTP Response.\nThe `send_200()` function will send a HTTP Response with status code 200\n(which means \"Success\") to the client. While the `send_404()` function sends a response\nwith status code 404 (which means \"Not found\").\n\nThis is definitely not the most ergonomic and adequate way of handling the\nHTTP Response, but it works for our case here. We are just building toy projects\nin this book after all, therefore, the source code that we write do not need to be perfect.\nIt just needs to work!\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Connection = std.net.Server.Connection;\npub fn send_200(conn: Connection) !void {\n    const message = (\n        \"HTTP/1.1 200 OK\\nContent-Length: 48\"\n        ++ \"\\nContent-Type: text/html\\n\"\n        ++ \"Connection: Closed\\n\\n<html><body>\"\n        ++ \"<h1>Hello, World!</h1></body></html>\"\n    );\n    _ = try conn.stream.write(message);\n}\n\npub fn send_404(conn: Connection) !void {\n    const message = (\n        \"HTTP/1.1 404 Not Found\\nContent-Length: 50\"\n        ++ \"\\nContent-Type: text/html\\n\"\n        ++ \"Connection: Closed\\n\\n<html><body>\"\n        ++ \"<h1>File not found!</h1></body></html>\"\n    );\n    _ = try conn.stream.write(message);\n}\n```\n:::\n\n\nNotice that both functions receives the connection object as input, and\nuse the `write()` method to write the HTTP Response message directly\ninto this communication channel. As result, the party in the other\nside of the connection (i.e., the client), will receive such message.\n\nMost real-world HTTP Servers will have a single function (or a single struct) to effectively handle\nthe response. It gets the HTTP Request already parsed as input, and then, it tries to build\nthe HTTP Response bit by bit, before the function sends it over the connection.\n\nWe would also have a specialized struct to represent a HTTP Response, and\na lot of methods that would be used to build each part or component of the response object.\nTake the `Response` struct created by the Javascript runtime Bun as an example.\nYou can find this struct in the [`response.zig` module](https://github.com/oven-sh/bun/blob/main/src/bun.js/webcore/response.zig)[^bun-resp]\nin their GitHub project.\n\n[^bun-resp]: <https://github.com/oven-sh/bun/blob/main/src/bun.js/webcore/response.zig>.\n\n\n## The end result\n\nWe can now, update once again our `main()` function to incorporate our new\nfunctions from the `response.zig` module. First, I need to import this module\ninto our `main.zig` module, then, I add the function calls to `send_200()`\nand `send_404()`.\n\nNotice that I'm using if statements to decide which \"response function\" to call,\nbased especially on the URI present in the HTTP Request. If the user asked for\na content (or a document) that is not present in our server, we should respond\nwith a 404 status code. But since we have just a simple HTTP server, with no\nreal documents to send, we can just check if the URI is the root path (`/`)\nor not to decide which function to call.\n\nAlso, notice that I'm using the function `std.mem.eql()` from the Zig Standard Library\nto check if the string from `uri` is equal or not the string `\"/\"`. We have\ndescribed this function already in @sec-strings-useful-funs, so, comeback to\nthat section if you are not familiar yet with this function.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst SocketConf = @import(\"config.zig\");\nconst Request = @import(\"request.zig\");\nconst Response = @import(\"response.zig\");\nconst Method = Request.Method;\nconst stdout = std.io.getStdOut().writer();\n\npub fn main() !void {\n    const socket = try SocketConf.Socket.init();\n    try stdout.print(\"Server Addr: {any}\\n\", .{socket._address});\n    var server = try socket._address.listen(.{});\n    const connection = try server.accept();\n\n    var buffer: [1000]u8 = undefined;\n    for (0..buffer.len) |i| {\n        buffer[i] = 0;\n    }\n    try Request.read_request(connection, buffer[0..buffer.len]);\n    const request = Request.parse_request(\n        buffer[0..buffer.len]\n    );\n    if (request.method == Method.GET) {\n        if (std.mem.eql(u8, request.uri, \"/\")) {\n            try Response.send_200(connection);\n        } else {\n            try Response.send_404(connection);\n        }\n    }\n}\n```\n:::\n\n\n\nNow that we adjusted our `main()` function, I can now execute our program, and\nsee the effects of these last changes. First, I execute the program once again, with the\n`run` command of the `zig` compiler. The program will hang, waiting for a client to connect.\n\nThen, I open my web browser, and try to connect to the server again, using the URL `localhost:3490`.\nThis time, instead of getting some sort of an error message from the browser, you will get the message\n\"Hello World\" printed into your web browser. Because this time, the server sended the HTTP Response\nsuccessfully to the web browser, as demonstrated by @fig-print-zigrun3.\n\n\n![The Hello World message sent in the HTTP Response](./../Figures/print-zigrun3.png){#fig-print-zigrun3}\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/05-pointers/execute-results/html.json b/_freeze/Chapters/05-pointers/execute-results/html.json
index 322b1cc9..8c1fac77 100644
--- a/_freeze/Chapters/05-pointers/execute-results/html.json
+++ b/_freeze/Chapters/05-pointers/execute-results/html.json
@@ -1,8 +1,8 @@
 {
-  "hash": "8201d761dfd46af14c754587b77047a2",
+  "hash": "51c6d3c5265304100391eb65d556de78",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Pointers and Optionals {#sec-pointer}\n\nOn our next project we are going to build a HTTP server from scratch.\nBut in order to do that, we need to learn more about pointers and how they work in Zig.\nPointers in Zig are similar to pointers in C. But they come with some extra advantages in Zig.\n\nA pointer is an object that contains a memory address. This memory address is the address where\na particular value is stored in memory. It can be any value. Most of the times,\nit's a value that comes from another object (or variable) present in our code.\n\nIn the example below, I'm creating two objects (`number` and `pointer`).\nThe `pointer` object contains the memory address where the value of the `number` object\n(the number 5) is stored. So, that is a pointer in a nutshell. It's a memory\naddress that points to a particular existing value in the memory. You could\nalso say, that, the `pointer` object points to the memory address where the `number` object is\nstored.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number: u8 = 5;\nconst pointer = &number;\n_ = pointer;\n```\n:::\n\n\n\n\nWe create a pointer object in Zig by using the `&` operator. When you put this operator\nbefore the name of an existing object, you get the memory address of this object as result.\nWhen you store this memory address inside a new object, this new object becomes a pointer object.\nBecause it stores a memory address.\n\nPeople mostly use pointers as an alternative way to access a particular value.\nFor example, I can use the `pointer` object to access the value stored by\nthe `number` object. This operation of accessing the value that the\npointer \"points to\" is normally called of *dereferencing the pointer*.\nWe can dereference a pointer in Zig by using the `*` method of the pointer object. Like in the example\nbelow, where we take the number 5 pointed by the `pointer` object,\nand double it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number: u8 = 5;\nconst pointer = &number;\nconst doubled = 2 * pointer.*;\nstd.debug.print(\"{d}\\n\", .{doubled});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n10\n```\n\n\n:::\n:::\n\n\n\n\n\nThis syntax to dereference the pointer is nice. Because we can easily chain it with\nmethods of the value pointed by the pointer. We can use the `User` struct that we have\ncreated in @sec-structs-and-oop as an example. If you comeback to that section,\nyou will see that this struct have a method named `print_name()`.\n\nSo, for example, if we have an user object, and a pointer that points to this user object,\nwe can use the pointer to access this user object, and, at the same time, call the method `print_name()`\non it, by chaining the dereference method (`*`) with the `print_name()` method. Like in the\nexample below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst u = User.init(1, \"pedro\", \"email@gmail.com\");\nconst pointer = &u;\ntry pointer.*.print_name();\n```\n:::\n\n\n\n\n```\npedro\n```\n\nWe can also use pointers to effectively alter the value of an object.\nFor example, I could use the `pointer` object to set\nthe value of the object `number` to 6, like in the example below.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n6\n```\n\n\n:::\n:::\n\n\n\n\n\nTherefore, as I mentioned earlier, people use pointers as an alternative way to access a particular value.\nAnd they use it especially when they do not want to \"move\" these values around. There are situations where,\nyou want to access a particular value in a different scope (i.e., a different location) of your code,\nbut you do not want to \"move\" this value to this new scope (or location) that you are in.\n\nThis matters especially if this value is big in size. Because if it is, then,\nmoving this value becomes an expensive operation to do.\nThe computer will have to spend a considerable amount of time\ncopying this value to this new location.\n\nTherefore, many programmers prefer to avoid this heavy operation of copying the value\nto the new location, by accessing this value through pointers.\nWe are going to talk more about this \"moving operation\" over the next sections.\nFor now, just keep in mind that avoiding this \"move operation\" is\none of main reasons why pointers are used in programming languages.\n\n\n\n\n\n## Constant objects vs variable objects {#sec-pointer-var}\n\nYou can have a pointer that points to a constant object, or, a pointer that points to a variable object.\nBut regardless of who this pointer is, a pointer **must always respect the characteristics of the object that it points to**.\nAs a consequence, if the pointer points to a constant object, then, you cannot use this pointer\nto change the value that it points to. Because it points to a value that is constant. As we discussed in @sec-assignments, you cannot\nchange a value that is constant.\n\nFor example, if I have a `number` object, which is constant, I cannot execute\nthe expression below where I'm trying to change the value of `number` to 6 through\nthe `pointer` object. As demonstrated below, when you try to do something\nlike that, you get a compile time error:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number = 5;\nconst pointer = &number;\npointer.* = 6;\n```\n:::\n\n\n\n\n```\np.zig:6:12: error: cannot assign to constant\n    pointer.* = 6;\n```\n\nIf I change the `number` object to be a variable object, by introducing the `var` keyword,\nthen, I can successfully change the value of this object through a pointer, as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n6\n```\n\n\n:::\n:::\n\n\n\n\nYou can see this relationship between \"constant versus variable\" on the data type of\nyour pointer object. In other words, the data type of a pointer object already gives you\nsome clues about whether the value that it points to is constant or not.\n\nWhen a pointer object points to a constant value, then, this pointer have a data type `*const T`,\nwhich means \"a pointer to a constant value of type `T`\".\nIn contrast, if the pointer points to a variable value, then, the type of the pointer is usually `*T`, which is\nsimply \"a pointer to a value of type `T`\".\nHence, whenever you see a pointer object whose data type is in the format `*const T`, then,\nyou know that you cannot use this pointer to change the value that it points to.\nBecause this pointer points to a constant value of type `T`.\n\n\nWe have talked about the value pointed by the pointer being constant or not,\nand the consequences that arises from it. But, what about the pointer object itself? I mean, what happens\nif the pointer object itself is constant or not? Think about it.\nWe can have a constant pointer that points to a constant value.\nBut we can also have a variable pointer that points to a constant value. And vice-versa.\n\nUntil this point, the `pointer` object was always constant,\nbut what does this mean for us? What is the consequence of the\n`pointer` object being constant? The consequence is that\nwe cannot change the pointer object, because it is constant. We can use the\npointer object in multiple ways, but we cannot change the\nmemory address that is inside this pointer object.\n\nHowever, if we mark the `pointer` object as a variable object,\nthen, we can change the memory address pointed by this `pointer` object.\nThe example below demonstrates that. Notice that the object pointed\nby the `pointer` object changes from `c1` to `c2`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c1: u8 = 5;\nconst c2: u8 = 6;\nvar pointer = &c1;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\npointer = &c2;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\n```\n:::\n\n\n\n\n```\n5\n6\n```\n\nThus, by setting the `pointer` object to a `var` or `const` object,\nyou specify if the memory address contained in this pointer object can change or not\nin your program. On the other side, you can change the value pointed by the pointer,\nif, and only if this value is stored in a variable object. If this value\nis in a constant object, then, you cannot change this value through a pointer.\n\n\n## Types of pointer\n\nIn Zig, there are two types of pointers [@zigdocs], which are:\n\n- single-item pointer (`*`);\n- many-item pointer (`[*]`);\n\n\nSingle-item pointer objects are objects whose data types are in the format `*T`.\nSo, for example, if an object have a data type `*u32`, it means that, this\nobject contains a single-item pointer that points to an unsigned 32-bit integer value.\nAs another example, if an object have type `*User`, then, it contains\na single-item pointer to an `User` value.\n\nIn contrast, many-item pointers are objects whose data types are in the format `[*]T`.\nNotice that the star symbol (`*`) is now inside a pair of brackets (`[]`). If the star\nsymbol is inside a pair of brackets, you know that this object is a many-item pointer.\n\nWhen you apply the `&` operator over an object, you will always get a single-item pointer.\nMany-item pointers are more of a \"internal type\" of the language, more closely\nrelated to slices. So, when you deliberately create a pointer with the `&` operator,\nyou always get a single-item pointer as result.\n\n\n\n## Pointer arithmetic\n\nPointer arithmetic is available in Zig, and they work the same way they work in C.\nWhen you have a pointer that points to an array, the pointer usually points to\nthe first element in the array, and you can use pointer arithmetic to\nadvance this pointer and access the other elements in the array.\n\n\nNotice in the example below, that initially, the `ptr` object was pointing\nto the first element in the array `ar`. But then, I started to walk through the array, by advancing\nthe pointer with simple pointer arithmetic.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [_]i32{ 1, 2, 3, 4 };\nvar ptr: [*]const i32 = &ar;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\n```\n:::\n\n\n\n\n```\n1\n2\n3\n```\n\nAlthough you can create a pointer to an array like that, and\nstart to walk through this array by using pointer arithmetic,\nin Zig, we prefer to use slices, which were presented in @sec-arrays.\n\nBehind the hood, slices already are pointers,\nand they also come with the `len` property, which indicates\nhow many elements are in the slice. This is good because the `zig` compiler\ncan use it to check for potential buffer overflows, and other problems like that.\n\nAlso, you don't need to use pointer arithmetic to walk through the elements\nof a slice. You can simply use the `slice[index]` syntax to directly access\nany element you want in the slice.\nAs I mentioned in @sec-arrays, you can get a slice from an array by using\na range selector inside brackets. In the example below, I'm creating\na slice (`sl`) that covers the entire `ar` array. I can access any\nelement of `ar` from this slice, and, the slice itself already is a pointer\nbehind the hood.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [_]i32{1,2,3,4};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\n\n## Optionals and Optional Pointers\n\nLet's talk about optionals and how they relate to pointers in Zig.\nBy default, objects in Zig are **non-nullable**. This means that, in Zig,\nyou can safely assume that any object in your source code is not null.\n\nThis is a powerful feature of Zig when you compare it to the developer experience in C.\nBecause in C, any object can be null at any point, and, as consequence, a pointer in C\nmight point to a null value. This is a common source of undefined behaviour in C.\nWhen programmers work with pointers in C, they have to constantly check if\ntheir pointers are pointing to null values or not.\n\nIf for some reason, your Zig code produces a null value somewhere, and, this null\nvalue ends up in an object that is non-nullable, a runtime error is always\nraised by your Zig program. Take the program below as an example.\nThe `zig` compiler can see the `null` value at compile time, and, as result,\nit raises a compile time error. But, if a `null` value is raised during\nruntime, a runtime error is also raised by the Zig program, with a\n\"attempt to use null value\" message.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nnumber = null;\n```\n:::\n\n\n\n```\np5.zig:5:14: error: expected type 'u8',\n        found '@TypeOf(null)'\n    number = null;\n             ^~~~\n```\n\n\nYou don't get this type of safety in C.\nIn C, you don't get warnings or errors about null values being produced in your program.\nIf for some reason, your code produces a null value in C, most of the times, you end up getting a segmentation fault error\nas result, which can mean many things.\nThat is why programmers have to constantly check for null values in C.\n\nPointers in Zig are also, by default, **non-nullable**. This is another amazing\nfeature in Zig. So, you can safely assume that any pointer that you create in\nyour Zig code is pointing to a non-null value.\nTherefore, you don't have this heavy work of checking if the pointers you create\nin Zig are pointing to a null value.\n\n\n### What are optionals?\n\nOk, we know now that all objects are non-nullable by default in Zig.\nBut what if we actually need to use an object that might receive a null value?\nHere is where optionals come in.\n\nAn optional object in Zig is an object that can be null.\nTo mark an object as optional, we use the `?` operator. When you put\nthis `?` operator right before the data type of an object, you transform\nthis data type into an optional data type, and the object becomes an optional object.\n\nTake the snippet below as an example. We are creating a new variable object\ncalled `num`. This object have the data type `?i32`, which means that,\nthis object contains either a signed 32-bit integer (`i32`), or, a null value.\nBoth alternatives are valid values to the `num` object.\nThat is why, I can actually change the value of this object to null, and,\nno errors are raised by the `zig` compiler, as demonstrated below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: ?i32 = 5;\nnum = null;\n```\n:::\n\n\n\n\n### Optional pointers\n\nYou can also mark a pointer object as an optional pointer, meaning that,\nthis object contains either a null value, or, a pointer that points to a value.\nWhen you mark a pointer as optional, the data type of this pointer object\nbecomes `?*const T` or `?*T`, depending if the value pointed by the pointer\nis a constant value or not. The `?` identifies the object as optional, while\nthe `*` identifies it as a pointer object.\n\nIn the example below, we are creating a variable object named `num`, and an\noptional pointer object named `ptr`. Notice that the data type of the object\n`ptr` indicates that it's either a null value, or a pointer to an `i32` value.\nAlso, notice that the pointer object (`ptr`) can be marked as optional, even if\nthe object `num` is not optional.\n\nWhat this code tells us is that, the `num` variable will never contain a null value.\nThis variable will always contain a valid `i32` value. But in contrast, the `ptr` object might contain either a null\nvalue, or, a pointer to an `i32` value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: i32 = 5;\nvar ptr: ?*i32 = &num;\nptr = null;\nnum = 6;\n```\n:::\n\n\n\n\nBut what happens if we turn the table, and mark the `num` object as optional,\ninstead of the pointer object. If we do that, then, the pointer object is\nnot optional anymore. It would be a similar (although different) result. Because then, we would have\na pointer to an optional value. In other words, a pointer to a value that is either a\nnull value, or, a not-null value.\n\nIn the example below, we are recreating this idea. Now, the `ptr` object\nhave a data type of `*?i32`, instead of `?*i32`. Notice that the `*` symbol comes before of `?`\nthis time. So now, we have a pointer that points to a value that is either null\n, or, a signed 32-bit integer.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: ?i32 = 5;\n// ptr have type `*?i32`, instead of `?*i32`.\nconst ptr = &num;\n_ = ptr;\n```\n:::\n\n\n\n\n\n### Null handling in optionals {#sec-null-handling}\n\nWhen you have an optional object in your Zig code, you have to explicitly handle\nthe possibility of this object being null. It's like error-handling with `try` and `catch`.\nIn Zig you also have to handle null values like if they were a type of error.\n\nWe can do that, by using either:\n\n- an if statement, like you would do in C.\n- the `orelse` keyword.\n- unwrap the optional value with the `?` method.\n\nWhen you use an if statement, you use a pair of pipes\nto unwrap the optional value, and use this \"unwrapped object\"\ninside the if block.\nUsing the example below as a reference, if the object `num` is null,\nthen, the code inside the if statement is not executed. Otherwise,\nthe if statement will unwrap the object `num` into the `not_null_num`\nobject. This `not_null_num` object is guaranteed to be not null inside\nthe scope of the if statement.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst num: ?i32 = 5;\nif (num) |not_null_num| {\n    try stdout.print(\"{d}\\n\", .{not_null_num});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n5\n```\n\n\n:::\n:::\n\n\n\n\nNow, the `orelse` keyword behaves like a binary operator. You connect two expressions with this keyword.\nOn the left side of `orelse`, you provide the expression that might result\nin a null value, and on the right side of `orelse`, you provide another expression\nthat will not result in a null value.\n\nThe idea behind the `orelse` keyword is: if the expression on the left side\nresult in a not-null value, then, this not-null value is used. However,\nif this expression on the left side result in a null value, then, the value\nof the expression on the right side is used instead.\n\nLooking at the example below, since the `x` object is currently null, the\n`orelse` decided to use the alternative value, which is the number 15.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x: ?i32 = null;\nconst dbl = (x orelse 15) * 2;\ntry stdout.print(\"{d}\\n\", .{dbl});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n30\n```\n\n\n:::\n:::\n\n\n\n\nYou can use the if statement or the `orelse` keyword, when you want to\nsolve (or deal with) this null value. However, if there is no clear solution\nto this null value, and the most logic and sane path is to simply panic\nand raise a loud error in your program when this null value is encountered,\nyou can use the `?` method of your optional object.\n\nIn essence, when you use this `?` method, the optional object is unwrapped.\nIf a not-null value is found in the optional object, then, this not-null value is used.\nOtherwise, the `unreachable` keyword is used. You can read more about this\n[`unreacheable` keyword at the official documentation](https://ziglang.org/documentation/master/#unreachable)[^un-docs].\nBut in essence, when you build your Zig source code using the build modes `ReleaseSafe` or `Debug`, this\n`unreacheable` keyword causes the program to panic and raise an error during runtime,\nlike in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn return_null(n: i32) ?i32 {\n    if (n == 5) return null;\n    return n;\n}\n\npub fn main() !void {\n    const x: i32 = 5;\n    const y: ?i32 = return_null(x);\n    try stdout.print(\"{d}\\n\", .{y.?});\n}\n```\n:::\n\n\n\n\n```\nthread 12767 panic: attempt to use null value\np7.zig:12:34: 0x103419d in main (p7):\n    try stdout.print(\"{d}\\n\", .{y.?});\n                                 ^\n```\n\n\n[^un-docs]: <https://ziglang.org/documentation/master/#unreachable>.\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n# Pointers and Optionals {#sec-pointer}\n\nOn our next project we are going to build a HTTP server from scratch.\nBut in order to do that, we need to learn more about pointers and how they work in Zig.\nPointers in Zig are similar to pointers in C. But they come with some extra advantages in Zig.\n\nA pointer is an object that contains a memory address. This memory address is the address where\na particular value is stored in memory. It can be any value. Most of the times,\nit's a value that comes from another object (or variable) present in our code.\n\nIn the example below, I'm creating two objects (`number` and `pointer`).\nThe `pointer` object contains the memory address where the value of the `number` object\n(the number 5) is stored. So, that is a pointer in a nutshell. It's a memory\naddress that points to a particular existing value in the memory. You could\nalso say, that, the `pointer` object points to the memory address where the `number` object is\nstored.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number: u8 = 5;\nconst pointer = &number;\n_ = pointer;\n```\n:::\n\n\nWe create a pointer object in Zig by using the `&` operator. When you put this operator\nbefore the name of an existing object, you get the memory address of this object as result.\nWhen you store this memory address inside a new object, this new object becomes a pointer object.\nBecause it stores a memory address.\n\nPeople mostly use pointers as an alternative way to access a particular value.\nFor example, I can use the `pointer` object to access the value stored by\nthe `number` object. This operation of accessing the value that the\npointer \"points to\" is normally called of *dereferencing the pointer*.\nWe can dereference a pointer in Zig by using the `*` method of the pointer object. Like in the example\nbelow, where we take the number 5 pointed by the `pointer` object,\nand double it.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number: u8 = 5;\nconst pointer = &number;\nconst doubled = 2 * pointer.*;\nstd.debug.print(\"{d}\\n\", .{doubled});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n10\n```\n\n\n:::\n:::\n\n\n\nThis syntax to dereference the pointer is nice. Because we can easily chain it with\nmethods of the value pointed by the pointer. We can use the `User` struct that we have\ncreated in @sec-structs-and-oop as an example. If you comeback to that section,\nyou will see that this struct have a method named `print_name()`.\n\nSo, for example, if we have an user object, and a pointer that points to this user object,\nwe can use the pointer to access this user object, and, at the same time, call the method `print_name()`\non it, by chaining the dereference method (`*`) with the `print_name()` method. Like in the\nexample below:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst u = User.init(1, \"pedro\", \"email@gmail.com\");\nconst pointer = &u;\ntry pointer.*.print_name();\n```\n:::\n\n\n```\npedro\n```\n\nWe can also use pointers to effectively alter the value of an object.\nFor example, I could use the `pointer` object to set\nthe value of the object `number` to 6, like in the example below.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n6\n```\n\n\n:::\n:::\n\n\n\nTherefore, as I mentioned earlier, people use pointers as an alternative way to access a particular value.\nAnd they use it especially when they do not want to \"move\" these values around. There are situations where,\nyou want to access a particular value in a different scope (i.e., a different location) of your code,\nbut you do not want to \"move\" this value to this new scope (or location) that you are in.\n\nThis matters especially if this value is big in size. Because if it is, then,\nmoving this value becomes an expensive operation to do.\nThe computer will have to spend a considerable amount of time\ncopying this value to this new location.\n\nTherefore, many programmers prefer to avoid this heavy operation of copying the value\nto the new location, by accessing this value through pointers.\nWe are going to talk more about this \"moving operation\" over the next sections.\nFor now, just keep in mind that avoiding this \"move operation\" is\none of main reasons why pointers are used in programming languages.\n\n\n\n\n\n## Constant objects vs variable objects {#sec-pointer-var}\n\nYou can have a pointer that points to a constant object, or, a pointer that points to a variable object.\nBut regardless of who this pointer is, a pointer **must always respect the characteristics of the object that it points to**.\nAs a consequence, if the pointer points to a constant object, then, you cannot use this pointer\nto change the value that it points to. Because it points to a value that is constant. As we discussed in @sec-assignments, you cannot\nchange a value that is constant.\n\nFor example, if I have a `number` object, which is constant, I cannot execute\nthe expression below where I'm trying to change the value of `number` to 6 through\nthe `pointer` object. As demonstrated below, when you try to do something\nlike that, you get a compile time error:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number = 5;\nconst pointer = &number;\npointer.* = 6;\n```\n:::\n\n\n```\np.zig:6:12: error: cannot assign to constant\n    pointer.* = 6;\n```\n\nIf I change the `number` object to be a variable object, by introducing the `var` keyword,\nthen, I can successfully change the value of this object through a pointer, as demonstrated below:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n6\n```\n\n\n:::\n:::\n\n\nYou can see this relationship between \"constant versus variable\" on the data type of\nyour pointer object. In other words, the data type of a pointer object already gives you\nsome clues about whether the value that it points to is constant or not.\n\nWhen a pointer object points to a constant value, then, this pointer have a data type `*const T`,\nwhich means \"a pointer to a constant value of type `T`\".\nIn contrast, if the pointer points to a variable value, then, the type of the pointer is usually `*T`, which is\nsimply \"a pointer to a value of type `T`\".\nHence, whenever you see a pointer object whose data type is in the format `*const T`, then,\nyou know that you cannot use this pointer to change the value that it points to.\nBecause this pointer points to a constant value of type `T`.\n\n\nWe have talked about the value pointed by the pointer being constant or not,\nand the consequences that arises from it. But, what about the pointer object itself? I mean, what happens\nif the pointer object itself is constant or not? Think about it.\nWe can have a constant pointer that points to a constant value.\nBut we can also have a variable pointer that points to a constant value. And vice-versa.\n\nUntil this point, the `pointer` object was always constant,\nbut what does this mean for us? What is the consequence of the\n`pointer` object being constant? The consequence is that\nwe cannot change the pointer object, because it is constant. We can use the\npointer object in multiple ways, but we cannot change the\nmemory address that is inside this pointer object.\n\nHowever, if we mark the `pointer` object as a variable object,\nthen, we can change the memory address pointed by this `pointer` object.\nThe example below demonstrates that. Notice that the object pointed\nby the `pointer` object changes from `c1` to `c2`.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c1: u8 = 5;\nconst c2: u8 = 6;\nvar pointer = &c1;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\npointer = &c2;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\n```\n:::\n\n\n```\n5\n6\n```\n\nThus, by setting the `pointer` object to a `var` or `const` object,\nyou specify if the memory address contained in this pointer object can change or not\nin your program. On the other side, you can change the value pointed by the pointer,\nif, and only if this value is stored in a variable object. If this value\nis in a constant object, then, you cannot change this value through a pointer.\n\n\n## Types of pointer\n\nIn Zig, there are two types of pointers [@zigdocs], which are:\n\n- single-item pointer (`*`);\n- many-item pointer (`[*]`);\n\n\nSingle-item pointer objects are objects whose data types are in the format `*T`.\nSo, for example, if an object have a data type `*u32`, it means that, this\nobject contains a single-item pointer that points to an unsigned 32-bit integer value.\nAs another example, if an object have type `*User`, then, it contains\na single-item pointer to an `User` value.\n\nIn contrast, many-item pointers are objects whose data types are in the format `[*]T`.\nNotice that the star symbol (`*`) is now inside a pair of brackets (`[]`). If the star\nsymbol is inside a pair of brackets, you know that this object is a many-item pointer.\n\nWhen you apply the `&` operator over an object, you will always get a single-item pointer.\nMany-item pointers are more of a \"internal type\" of the language, more closely\nrelated to slices. So, when you deliberately create a pointer with the `&` operator,\nyou always get a single-item pointer as result.\n\n\n\n## Pointer arithmetic\n\nPointer arithmetic is available in Zig, and they work the same way they work in C.\nWhen you have a pointer that points to an array, the pointer usually points to\nthe first element in the array, and you can use pointer arithmetic to\nadvance this pointer and access the other elements in the array.\n\n\nNotice in the example below, that initially, the `ptr` object was pointing\nto the first element in the array `ar`. But then, I started to walk through the array, by advancing\nthe pointer with simple pointer arithmetic.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [_]i32{ 1, 2, 3, 4 };\nvar ptr: [*]const i32 = &ar;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\n```\n:::\n\n\n```\n1\n2\n3\n```\n\nAlthough you can create a pointer to an array like that, and\nstart to walk through this array by using pointer arithmetic,\nin Zig, we prefer to use slices, which were presented in @sec-arrays.\n\nBehind the hood, slices already are pointers,\nand they also come with the `len` property, which indicates\nhow many elements are in the slice. This is good because the `zig` compiler\ncan use it to check for potential buffer overflows, and other problems like that.\n\nAlso, you don't need to use pointer arithmetic to walk through the elements\nof a slice. You can simply use the `slice[index]` syntax to directly access\nany element you want in the slice.\nAs I mentioned in @sec-arrays, you can get a slice from an array by using\na range selector inside brackets. In the example below, I'm creating\na slice (`sl`) that covers the entire `ar` array. I can access any\nelement of `ar` from this slice, and, the slice itself already is a pointer\nbehind the hood.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [_]i32{1,2,3,4};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n## Optionals and Optional Pointers\n\nLet's talk about optionals and how they relate to pointers in Zig.\nBy default, objects in Zig are **non-nullable**. This means that, in Zig,\nyou can safely assume that any object in your source code is not null.\n\nThis is a powerful feature of Zig when you compare it to the developer experience in C.\nBecause in C, any object can be null at any point, and, as consequence, a pointer in C\nmight point to a null value. This is a common source of undefined behaviour in C.\nWhen programmers work with pointers in C, they have to constantly check if\ntheir pointers are pointing to null values or not.\n\nIn contrast, when working in Zig, if for some reason, your Zig code produces a null value somewhere, and, this null\nvalue ends up in an object that is non-nullable, a runtime error is always\nraised by your Zig program. Take the program below as an example.\nThe `zig` compiler can see the `null` value at compile time, and, as result,\nit raises a compile time error. But, if a `null` value is raised during\nruntime, a runtime error is also raised by the Zig program, with a\n\"attempt to use null value\" message.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nnumber = null;\n```\n:::\n\n```\np5.zig:5:14: error: expected type 'u8',\n        found '@TypeOf(null)'\n    number = null;\n             ^~~~\n```\n\n\nYou don't get this type of safety in C.\nIn C, you don't get warnings or errors about null values being produced in your program.\nIf for some reason, your code produces a null value in C, most of the times, you end up getting a segmentation fault error\nas result, which can mean many things.\nThat is why programmers have to constantly check for null values in C.\n\nPointers in Zig are also, by default, **non-nullable**. This is another amazing\nfeature in Zig. So, you can safely assume that any pointer that you create in\nyour Zig code is pointing to a non-null value.\nTherefore, you don't have this heavy work of checking if the pointers you create\nin Zig are pointing to a null value.\n\n\n### What are optionals?\n\nOk, we know now that all objects are non-nullable by default in Zig.\nBut what if we actually need to use an object that might receive a null value?\nHere is where optionals come in.\n\nAn optional object in Zig is rather similar to a [`std::optional` object in C++](https://en.cppreference.com/w/cpp/utility/optional.html).\nIt is an object that can either contain a value, or nothing at all (a.k.a. the object can be null).\nTo mark an object in our Zig code as \"optional\", we use the `?` operator. When you put\nthis `?` operator right before the data type of an object, you transform\nthis data type into an optional data type, and the object becomes an optional object.\n\nTake the snippet below as an example. We are creating a new variable object\ncalled `num`. This object have the data type `?i32`, which means that,\nthis object contains either a signed 32-bit integer (`i32`), or, a null value.\nBoth alternatives are valid values to the `num` object.\nThat is why, I can actually change the value of this object to null, and,\nno errors are raised by the `zig` compiler, as demonstrated below:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: ?i32 = 5;\nnum = null;\n```\n:::\n\n\n### Optional pointers\n\nYou can also mark a pointer object as an optional pointer, meaning that,\nthis object contains either a null value, or, a pointer that points to a value.\nWhen you mark a pointer as optional, the data type of this pointer object\nbecomes `?*const T` or `?*T`, depending if the value pointed by the pointer\nis a constant value or not. The `?` identifies the object as optional, while\nthe `*` identifies it as a pointer object.\n\nIn the example below, we are creating a variable object named `num`, and an\noptional pointer object named `ptr`. Notice that the data type of the object\n`ptr` indicates that it's either a null value, or a pointer to an `i32` value.\nAlso, notice that the pointer object (`ptr`) can be marked as optional, even if\nthe object `num` is not optional.\n\nWhat this code tells us is that, the `num` variable will never contain a null value.\nThis variable will always contain a valid `i32` value. But in contrast, the `ptr` object might contain either a null\nvalue, or, a pointer to an `i32` value.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: i32 = 5;\nvar ptr: ?*i32 = &num;\nptr = null;\nnum = 6;\n```\n:::\n\n\nBut what happens if we turn the table, and mark the `num` object as optional,\ninstead of the pointer object. If we do that, then, the pointer object is\nnot optional anymore. It would be a similar (although different) result. Because then, we would have\na pointer to an optional value. In other words, a pointer to a value that is either a\nnull value, or, a not-null value.\n\nIn the example below, we are recreating this idea. Now, the `ptr` object\nhave a data type of `*?i32`, instead of `?*i32`. Notice that the `*` symbol comes before of `?`\nthis time. So now, we have a pointer that points to a value that is either null\n, or, a signed 32-bit integer.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: ?i32 = 5;\n// ptr have type `*?i32`, instead of `?*i32`.\nconst ptr = &num;\n_ = ptr;\n```\n:::\n\n\n\n### Null handling in optionals {#sec-null-handling}\n\nWhen you have an optional object in your Zig code, you have to explicitly handle\nthe possibility of this object being null. It's like error-handling with `try` and `catch`.\nIn Zig you also have to handle null values like if they were a type of error.\n\nWe can do that, by using either:\n\n- an if statement, like you would do in C.\n- the `orelse` keyword.\n- unwrap the optional value with the `?` method.\n\nWhen you use an if statement, you use a pair of pipes\nto unwrap the optional value, and use this \"unwrapped object\"\ninside the if block.\nUsing the example below as a reference, if the object `num` is null,\nthen, the code inside the if statement is not executed. Otherwise,\nthe if statement will unwrap the object `num` into the `not_null_num`\nobject. This `not_null_num` object is guaranteed to be not null inside\nthe scope of the if statement.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst num: ?i32 = 5;\nif (num) |not_null_num| {\n    try stdout.print(\"{d}\\n\", .{not_null_num});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n5\n```\n\n\n:::\n:::\n\n\nNow, the `orelse` keyword behaves like a binary operator. You connect two expressions with this keyword.\nOn the left side of `orelse`, you provide the expression that might result\nin a null value, and on the right side of `orelse`, you provide another expression\nthat will not result in a null value.\n\nThe idea behind the `orelse` keyword is: if the expression on the left side\nresult in a not-null value, then, this not-null value is used. However,\nif this expression on the left side result in a null value, then, the value\nof the expression on the right side is used instead.\n\nLooking at the example below, since the `x` object is currently null, the\n`orelse` decided to use the alternative value, which is the number 15.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x: ?i32 = null;\nconst dbl = (x orelse 15) * 2;\ntry stdout.print(\"{d}\\n\", .{dbl});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n30\n```\n\n\n:::\n:::\n\n\nYou can use the if statement or the `orelse` keyword, when you want to\nsolve (or deal with) this null value. However, if there is no clear solution\nto this null value, and the most logic and sane path is to simply panic\nand raise a loud error in your program when this null value is encountered,\nyou can use the `?` method of your optional object.\n\nIn essence, when you use this `?` method, the optional object is unwrapped.\nIf a not-null value is found in the optional object, then, this not-null value is used.\nOtherwise, the `unreachable` keyword is used. You can read more about this\n[`unreacheable` keyword at the official documentation](https://ziglang.org/documentation/master/#unreachable)[^un-docs].\nBut in essence, when you build your Zig source code using the build modes `ReleaseSafe` or `Debug`, this\n`unreacheable` keyword causes the program to panic and raise an error during runtime,\nlike in the example below:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn return_null(n: i32) ?i32 {\n    if (n == 5) return null;\n    return n;\n}\n\npub fn main() !void {\n    const x: i32 = 5;\n    const y: ?i32 = return_null(x);\n    try stdout.print(\"{d}\\n\", .{y.?});\n}\n```\n:::\n\n\n```\nthread 12767 panic: attempt to use null value\np7.zig:12:34: 0x103419d in main (p7):\n    try stdout.print(\"{d}\\n\", .{y.?});\n                                 ^\n```\n\n\n[^un-docs]: <https://ziglang.org/documentation/master/#unreachable>.\n",
     "supporting": [
       "05-pointers_files"
     ],
diff --git a/_freeze/Chapters/07-build-system/execute-results/epub.json b/_freeze/Chapters/07-build-system/execute-results/epub.json
deleted file mode 100644
index 57752a70..00000000
--- a/_freeze/Chapters/07-build-system/execute-results/epub.json
+++ /dev/null
@@ -1,21 +0,0 @@
-{
-  "hash": "0286d5b6db10173d3df147400fd019aa",
-  "result": {
-    "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Build System {#sec-build-system}\n\n\nIn this chapter, we are going to talk about the build system, and how an entire project\nis built in Zig.\nOne key advantage of Zig is that it includes a build system embedded in the language itself.\nThis is great, because then you do not have to depend on an external system, separated\nfrom the compiler, to build your code.\n\n\nYou can find a good description of Zig's build system\nin the [article entitled \"Build System\"](https://ziglang.org/learn/build-system/#user-provided-options)[^zig-art1]\nfrom the official Zig's website.\nWe also have the excellent [series of posts written by Felix](https://zig.news/xq/zig-build-explained-part-1-59lf)[^felix].\nHence, this chapter represents an extra resource for you to consult and rely on.\n\n[^felix]: <https://zig.news/xq/zig-build-explained-part-1-59lf>\n[^zig-art1]: <https://ziglang.org/learn/build-system/#user-provided-options>\n\nBuilding code is one of the things that Zig is best at. One thing that is particularly\ndifficult in C/C++ and even in Rust, is to cross-compile source code to multiple targets\n(e.g. multiple computer architectures and operating systems),\nand the `zig` compiler is known for being one of the best existing pieces of software\nfor this particular task.\n\n\n\n\n## How source code is built?\n\nWe already have talked about the challenges of building source code in low-level languages\nin @sec-project-files. As we described at that section, programmers invented Build Systems\nto surpass these challenges on the process of building source code in low-level languages.\n\nLow-level languages uses a compiler to compile (or to build) your source code into binary instructions.\nIn C and C++, we normally use compilers like `gcc`, `g++` or `clang` to compile\nour C and C++ source code into these instructions.\nEvery language have its own compiler, and this is no different in Zig.\n\nIn Zig, we have the `zig` compiler to compile our Zig source code into\nbinary instructions that can be executed by our computer.\nIn Zig, the compilation (or the build) process involves\nthe following components:\n\n- The Zig modules that contains your source code;\n- Library files (either a dynamic library or a static library);\n- Compiler flags that tailors the build process to your needs.\n\nThese are the things that you need to connect together in order to build your\nsource code in Zig. In C and C++, you would have an extra component, which are the header files of\nthe libraries that you are using. But header files do not exist in Zig, so, you only need\nto care about them if you are linking your Zig source code with a C library.\nIf that is not your case, you can forget about it.\n\nYour build process is usually organized in a build script. In Zig, we normally\nwrite this build script into a Zig module in the root directory of our project,\nnamed as `build.zig`. You write this build script, then, when you run it, your project\ngets built into binary files that you can use and distribute to your users.\n\nThis build script is normally organized around *target objects*. A target is simply\nsomething to be built, or, in other words, it's something that you want the `zig` compiler\nto build for you. This concept of \"targets\" is present in most Build Systems,\nespecially in CMake[^cmake].\n\n[^cmake]: <https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html>\n\nThere are four types of target objects that you can build in Zig, which are:\n\n- An executable (e.g. a `.exe` file on Windows).\n- A shared library (e.g. a `.so` file in Linux or a `.dll` file on Windows).\n- A static library (e.g. a `.a` file in Linux or a `.lib` file on Windows).\n- An executable file that executes only unit tests (or, a \"unit tests executable\").\n\nWe are going to talk more about these target objects in @sec-targets.\n\n\n\n## The `build()` function {#sec-build-fun}\n\nA build script in Zig always contains a public (and top-level) `build()` function declared.\nIt's like the `main()` function in the main Zig module of your project, that we discussed in @sec-main-file.\nBut instead of creating the entrypoint to your code, this `build()` function is the entrypoint to the build process.\n\nThis `build()` function should accept a pointer to a `Build` object as input, and it should use this \"build object\" to perform\nthe necessary steps to build your project. The return type of this function is always `void`,\nand this `Build` struct comes directly from the Zig Standard Library (`std.Build`). So, you can\naccess this struct by just importing the Zig Standard Library into your `build.zig` module.\n\nJust as a very simple example, here you can see the source code necessary to build\nan executable file from the `hello.zig` Zig module.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"hello.zig\"),\n        .target = b.host,\n    });\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\nYou can define and use other functions and objects in this build script. You can also import\nother Zig modules as you would normally do in any other module of your project.\nThe only real requirement for this build script, is to have a public and top-level\n`build()` function defined, that accepts a pointer to a `Build` struct as input.\n\n\n## Target objects {#sec-targets}\n\nAs we described over the previous sections, a build script is composed around target objects.\nEach target object is normally a binary file (or an output) that you want to get from the build process. You can list\nmultiple target objects in your build script, so that the build process generates multiple\nbinary files for you at once.\n\nFor example, maybe you are a developer working in a cross-platform application,\nand, because this application is cross-platform, you probably need to release\nbinary files of your software for each OS supported by your application to your end users.\nThus, you can define a different target object in your build script\nfor each OS (Windows, Linux, etc.) where you want to publish your software.\nThis will make the `zig` compiler to build your project to multiple target OS's at once.\nThe Zig Build System official documentation have a [great code example that demonstrates this strategy](https://ziglang.org/learn/build-system/#handy-examples)[^zig-ex].\n\n[^zig-ex]: <https://ziglang.org/learn/build-system/#handy-examples>\n\n\nA target object is created by the following methods of the `Build` struct that we introduced\nin @sec-build-fun:\n\n- `addExecutable()` creates an executable file;\n- `addSharedLibrary()` creates a shared library file;\n- `addStaticLibrary()` creates a static library file;\n- `addTest()` creates an executable file that executes unit tests.\n\n\nThese functions are methods from the `Build` struct that you receive\nas input of the `build()` function. All of them, create as output\na `Compile` object, which represents a target object to be compiled\nby the `zig` compiler. All of these functions accept a similar struct literal as input.\nThis struct literal defines three essential specs about this target object that you are building:\n`name`, `target` and `root_source_file`.\n\nWe have already seen these three options being used on the previous example,\nwhere we used the `addExecutable()` method to create an executable target object.\nThis example is reproduced below. Notice the use of the `path()` method\nfrom the `Build` struct, to define a path in the `root_source_file` option.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n```\n:::\n\n\n\nThe `name` option specify the name that you want to give to the binary file defined\nby this target object. So, in this example, we are building an executable file named `hello`.\nIt's common to set this `name` option to the name of your project.\n\n\nFurthermore, the `target` option specify the target computer architecture (or the target operating system) of this\nbinary file. For example, if you want this target object to run on a Windows machine\nthat uses a `x86_64` architecture, you can set this `target` option to `x86_64-windows-gnu` for example.\nThis will make the `zig` compiler to compile the project to run on a `x86_64` Windows machine.\nYou can see the full list of architectures and OS's that the `zig` compiler supports by running\nthe `zig targets` command in the terminal.\n\nNow, if you are building the project to run on the current machine\nthat you are using to run this build script, you can set this `target`\noption to the `host` method of the `Build` object, like we did in the example above.\nThis `host` method identifies the current machine where you are\ncurrently running the `zig` compiler.\n\n\nAt last, the `root_source_file` option specifies the root Zig module of your project.\nThat is the Zig module that contains the entrypoint to your application (i.e., the `main()` function), or, the main API of your library.\nThis also means that, all the Zig modules that compose your project are automatically discovered\nfrom the import statements you have inside this \"root source file\".\nThe `zig` compiler can detect when a Zig module depends on the other through the import statements,\nand, as a result, it can discover the entire map of Zig modules used in your project.\n\nThis is handy, and it's different from what happens in other build systems.\nIn CMake for example, you have to explicitly list the paths to all source files that you want to\ninclude in your build process. This is probably a symptom of the \"lack of conditional\ncompilation\" in the C and C++ compilers. Since they lack this feature, you have\nto explicitly choose which source files should be sent to the C/C++ compiler, because not\nevery C/C++ code is portable or supported in every operating system, and, therefore,\nwould cause a compilation error in the C/C++ compiler.\n\n\nNow, one important detail about the build process is that, you have to **explicitly\ninstall the target objects that you create in your build script**, by using the\n`installArtifact()` method of the `Build` struct.\n\nEverytime you invoke the build process of your project, by calling the `build` command\nof the `zig` compiler, a new directory named `zig-out` is created in the root\ndirectory of your project. This new directory contains the outputs of the build process,\nthat is, the binary files built from your source code.\n\nWhat the `installArtifact()` method do is to install (or copy) the built target objects\nthat you defined to this `zig-out` directory.\nThis means that, if you do not\ninstall the target objects you define in your build script, these target objects are\nessentially discarded at the end of the build process.\n\nFor example, you might be building a project that uses a third party library that is built\ntogether with the project. So, when you build your project, you would need first, to\nbuild the third party library, and then, you link it with the source code of your project.\nSo, in this case, we have two binary files that are generated in the build process (the executable file of your project, and the third party library).\nBut only one is of interest, which is the executable file of our project.\nWe can discard the binary file of the third party library, by simply not installing it\ninto this `zig-out` directory.\n\nThis `installArtifact()` method is pretty straightforward. Just remember to apply it to every\ntarget object that you want to save into the `zig-out` directory, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n## Setting the build mode\n\nWe have talked about the three essential options that are set when you create a new target object.\nBut there is also a fourth option that you can use to set the build mode of this target object,\nwhich is the `optimize` option.\nThis option is called this way, because the build modes in Zig are treated more of\nan \"optimization vs safety\" problem. So optimization plays an important role here.\nDon't worry, I'm going back to this question very soon.\n\nIn Zig, we have four build modes (which are listed below). Each one of these build modes offer\ndifferent advantages and characteristics. As we described in @sec-compile-debug-mode, the `zig` compiler\nuses the `Debug` build mode by default, when you don't explicitly choose a build mode.\n\n- `Debug`, mode that produces and includes debugging information in the output of the build process (i.e., the binary file defined by the target object);\n- `ReleaseSmall`, mode that tries to produce a binary file that is small in size;\n- `ReleaseFast`, mode that tries to optimize your code, in order to produce a binary file that is as fast as possible;\n- `ReleaseSafe`, mode that tries to make your code as safe as possible, by including safeguards when possible.\n\nSo, when you build your project, you can set the build mode of your target object to `ReleaseFast` for example, which will tell\nthe `zig` compiler to apply important optimizations in your code. This creates a binary file\nthat simply runs faster on most contexts, because it contains a more optimized version of your code.\nHowever, as a result, we often lose some safety features in our code.\nBecause some safety checks are removed from the final binary file,\nwhich makes your code run faster, but in a less safe manner.\n\nThis choice depends on your current priorities. If you are building a cryptography or banking system, you might\nprefer to prioritize safety in your code, so, you would choose the `ReleaseSafe` build mode, which is a little\nslower to run, but much more secure, because it includes all possible runtime safety checks in the binary file\nbuilt in the build process. In the other hand, if you are writing a game for example, you might prefer to prioritize performance\nover safety, by using the `ReleaseFast` build mode, so that your users can experience faster frame rates in your game.\n\nIn the example below, we are creating the same target object that we have used on previous examples.\nBut this time, we are specifying the build mode of this target object to the `ReleaseSafe` mode.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .optimize = .ReleaseSafe\n});\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n## Setting the version of your build\n\nEverytime you build a target object in your build script, you can assign a version\nnumber to this specific build, following a semantic versioning framework.\nYou can find more about semantic versioning by visiting the [Semantic Versioning website](https://semver.org/)[^semver].\nAnyway, in Zig, you can specify the version of your build, by providing a `SemanticVersion` struct to\nthe `version` option, like in the example below:\n\n\n[^semver]: <https://semver.org/>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .version = .{\n        .major = 2, .minor = 9, .patch = 7\n    }\n});\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n## Detecting the OS in your build script {#sec-detect-os}\n\nIt's very common in Build Systems to use different options, or, to include different modules, or,\nto link against different libraries depending on the Operational System (OS)\nthat you are targeting in the build process.\n\nIn Zig, you can detect the target OS of the build process, by looking\nat the `os.tag` inside the `builtin` module from the Zig library.\nIn the example below, we are using an if statement to run some\narbitrary code when the target of the build process is a\nWindows system.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nif (builtin.target.os.tag == .windows) {\n    // Code that runs only when the target of\n    // the compilation process is Windows.\n}\n```\n:::\n\n\n\n\n## Adding a run step to your build process\n\nOne thing that is neat in Rust is that you can compile and run your\nsource code with one single command (`cargo run`) from the Rust compiler.\nWe saw in @sec-compile-run-code how can we perform a similar job in Zig, by\nbuilding and running our Zig source code through the `run` command from the `zig` compiler.\n\nBut how can we, at the same time, build and run the binary file specified by a target object in our\nbuild script?\nThe answer is by including a \"run artifact\" in our build script.\nA run artifact is created through the `addRunArtifact()` method from the `Build` struct.\nWe simply provide as input to this function the target object that describes the binary file that we\nwant to execute. As a result, this function creates a run artifact that is capable of executing\nthis binary file.\n\nIn the example below, we are defining an executable binary file named `hello`,\nand we use this `addRunArtifact()` method to create a run artifact that will execute\nthis `hello` executable file.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"src/hello.zig\"),\n    .target = b.host\n});\nb.installArtifact(exe);\nconst run_arti = b.addRunArtifact(exe);\n```\n:::\n\n\n\nNow that we have created this run artifact, we need to include it in\nthe build process. We do that by declaring a new step in our build\nscript to call this artifact, through the `step()` method of the `Build`\nstruct.\n\nWe can give any name we want to this step, but, for our\ncontext here, I'm going to name this step as \"run\".\nAlso, I give it a brief description to this step (\"Run the project\").\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst run_step = b.step(\n    \"run\", \"Run the project\"\n);\n```\n:::\n\n\n\n\nNow that we have declared this \"run step\" we need to tell Zig that\nthis \"run step\" depends on the run artifact.\nIn other words, a run artifact always depends on a \"step\" to effectively be executed.\nBy creating this dependency\nwe finally stablish the necessary commands to build and run the executable file\nfrom the build script.\n\nWe can establish a dependency between the run step and the run artifact\nby using the `dependsOn()` method from the run step. So, we first\ncreate the run step, and then, we link it with the run artifact, by\nusing this `dependsOn()` method from the run step.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nrun_step.dependOn(&run_arti.step);\n```\n:::\n\n\n\nThe entire source code of this specific build script that\nwe wrote, piece by piece, in this section, is\navailable in the `build_and_run.zig` module. You can\nsee this module by\n[visiting the official repository of this book](https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig)\n[^module-src].\n\n\n[^module-src]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig>\n\nWhen you declare a new step in your build script, this step\nbecomes available through the `build` command in the `zig` compiler.\nYou can actually see this step by running `zig build --help` in the terminal, like\nin the example below, where we can see that this new \"run\"\nstep that we declared in the build script appeared in the output.\n\n```bash\nzig build --help\n```\n\n```\nSteps:\n  ...\n  run   Run the project\n  ...\n```\n\nNow, everything that we need to is to\ncall this \"run\" step that we created in our build script. We\ncall it by using the name that we gave to this step\nafter the `build` command from the `zig` compiler.\nThis will cause the compiler to build our executable file\nand execute it at the same time.\n\n```bash\nzig build run\n```\n\n## Build unit tests in your project\n\nWe have talked at length about writing unit tests in Zig in @sec-unittests,\nand we also have talked about how to execute these unit tests through\nthe `test` command of the `zig` compiler. However,\nas we did with the `run` command on the previous section, we also might want to\ninclude some commands in our build script to also build and execute the unit tests in our project.\n\nSo, once again, we are going to discuss how a specific built-in command from the `zig` compiler,\n(in this case, the `test` command) can be used in a build script in Zig.\nHere is where a \"test target object\" comes into play.\nAs was described in @sec-targets, we can create a test target object by using the `addTest()` method of\nthe `Build` struct. The first thing that we need to do is to\ndeclare a test target object in our build script.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst test_exe = b.addTest(.{\n    .name = \"unit_tests\",\n    .root_source_file = b.path(\"src/main.zig\"),\n    .target = b.host,\n});\nb.installArtifact(test_exe);\n```\n:::\n\n\n\n\nA test target object essentially selects all `test` blocks in all Zig modules\nacross your project, and builds only the source code present inside\nthese `test` blocks in your project. As a result, this target object\ncreates an executable file that contains only the source code present\nin all of these `test` blocks (i.e., the unit tests) in your project.\n\nPerfect! Now that we have declared this test target object, an executable file\nnamed `unit_tests` is built by the `zig` compiler when we trigger the build\nscript with the `build` command. After the build\nprocess is finished, we can simply execute this `unit_tests` executable\nin the terminal.\n\nHowever, if you remember the previous section, we already learned\nhow can we create a run step in our build script, to execute an executable file\nbuilt by the build script.\n\nSo, we could simply add a run step in our build script to run these unit tests\nfrom a single command in the `zig` compiler, to make our lifes easier.\nIn the example below, we demonstrate the commands to\nregister a new build step called \"tests\" in our build script\nto run these unit tests.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst run_arti = b.addRunArtifact(test_exe);\nconst run_step = b.step(\"tests\", \"Run unit tests\");\nrun_step.dependOn(&run_arti.step);\n```\n:::\n\n\n\nNow that we registered this new build step, we can trigger it by calling the command below\nin the terminal. You can also checkout the complete source\ncode for this specific build script at the `build_tests.zig` module at the\n[official repository of this book](https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig)\n[^module-src2].\n\n\n[^module-src2]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig>\n\n\n```bash\nzig build tests\n```\n\n\n## Tailoring your build process with user-provided options\n\nSometimes, you want to make a build script that is customizable by the user\nof your project. You can do that by creating user-provided options in\nyour build script. We create an user-provided option by using the\n`option()` method from the `Build` struct.\n\nWith this method, we create a \"build option\" which can be passed\nto the `build.zig` script at the command line. The user have the power of setting\nthis option at the `build` command from the\n`zig` compiler. In other words, each build option that we create\nbecomes a new command line argument that is accessible through the `build` command\nof the compiler.\n\nThese \"user-provided options\" are set by using the prefix `-D` in the command line.\nFor example, if we declare an option named `use_zlib`, that receives a boolean value which\nindicates if we should link our source code to `zlib` or not, we can set the value\nof this option in the command line with `-Duse_zlib`. The code example below\ndemonstrates this idea:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const use_zlib = b.option(\n        bool,\n        \"use_zlib\",\n        \"Should link to zlib?\"\n    ) orelse false;\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"example.zig\"),\n        .target = b.host,\n    });\n    if (use_zlib) {\n        exe.linkSystemLibrary(\"zlib\");\n    }\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n```bash\nzig build -Duse_zlib=false\n```\n\n\n## Linking to external libraries\n\n\nOne essential part of every build process is the linking stage.\nThis stage is responsible for combining the multiple object files\nthat represent your code, into a single executable file. It also links\nthis executable file to external libraries, if you use any in your code.\n\nIn Zig, we have two notions of a \"library\", which are: 1) a system's library;\n2) a local library. A system's library is just a library that is already installed\nin your system. While a local library is a library that belongs to the current\nproject; a library that is present in your project directory, and\nthat you are building together with your project source code.\n\nThe basic difference between the two, is that a system's library is already\nbuilt and installed in your system, supposedly, and all you need to do\nis to link your source code to this library to start using it.\nWe do that by using the `linkSystemLibrary()` method from a\n`Compile` object. This method accepts the name of the library\nin a string as input. Remember from @sec-targets that a `Compile` object\nis a target object that you declare in your build script.\n\nWhen you link a particular target object with a system's library,\nthe `zig` compiler will use `pkg-config` to find where\nare the binary files and also the header files of this library\nin your system.\nWhen it finds these files, the linker present in the `zig` compiler\nwill link your object files with the files of this library to\nproduce a single binary file for you.\n\nIn the example below, we are creating an executable file named `image_filter`,\nand, we are linking this executable file to the C Standard Library with the\nmethod `linkLibC()`, but we also are linking this executable file to the\nC library `libpng` that is currently installed in my system.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"image_filter\",\n        .root_source_file = b.path(\"src/main.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n    exe.linkLibC();\n    exe.linkSystemLibrary(\"png\");\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\nIf you are linking with a C library in your project, is generally a good idea\nto also link your code with the C Standard Library. Because is very likely\nthat this C library uses some functionality of the C Standard Library at some point.\nThe same goes to C++ libraries. So, if you are linking with\nC++ libraries, is a good idea to link your project with the C++\nStandard Library by using the `linkLibCpp()` method.\n\nOn the order side, when you want to link with a local library,\nyou should use the `linkLibrary()` method of a `Compile` object.\nThis method expects to receive another `Compile` object as input.\nThat is, another target object defined in your build script,\nusing either the `addStaticLibrary()` or `addSharedLibrary()` methods\nwhich defines a library to be built.\n\nAs we discussed earlier, a local library is a library\nthat is local to your project, and that is being built together\nwith your project. So, you need to create a target object in your build script\nto build this local library. Then, you link the target objects of interest in your project,\nwith this target object that identifies this local library.\n\nTake a look at this example extracted from the build script of the [`libxev` library](https://github.com/mitchellh/libxev/tree/main)[^libxev2].\nYou can see in this snippet that\nwe are declaring a shared library file, from the `c_api.zig`\nmodule. Then, later in the build script, we declare an\nexecutable file named `\"dynamic-binding-test\"`, which\nlinks to this shared library that we defined earlier\nin the script.\n\n[^libxev2]: <https://github.com/mitchellh/libxev/tree/main>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst optimize = b.standardOptimizeOption(.{});\nconst target = b.standardTargetOptions(.{});\n\nconst dynamic_lib = b.addSharedLibrary(.{\n    .name = dynamic_lib_name,\n    .root_source_file = b.path(\"src/c_api.zig\"),\n    .target = target,\n    .optimize = optimize,\n});\nb.installArtifact(dynamic_lib);\n// ... more lines in the script\nconst dynamic_binding_test = b.addExecutable(.{\n    .name = \"dynamic-binding-test\",\n    .target = target,\n    .optimize = optimize,\n});\ndynamic_binding_test.linkLibrary(dynamic_lib);\n```\n:::\n\n\n\n\n\n## Building C code {#sec-building-c-code}\n\nThe `zig` compiler comes with a C compiler embedded in it. In other words,\nyou can use the `zig` compiler to build C projects. This C compiler is available\nthrough the `cc` command of the `zig` compiler.\n\nAs an example, let's use the famous [FreeType library](https://freetype.org/)[^freetype].\nFreeType is one of the most widely used pieces of software in the world.\nIt's a C library designed to produce high-quality fonts. But it's also\nheavily used in the industry to natively render text and fonts\nin the screen of your computer.\n\nIn this section, we are going to write a build script, piece by piece, that is capable\nof building the FreeType project from source.\nYou can find the source code of this build script on the\n[`freetype-zig` repository](https://github.com/pedropark99/freetype-zig/tree/main)[^freetype-zig]\navailable at GitHub.\n\n[^freetype]: <https://freetype.org/>\n[^freetype-zig]: <https://github.com/pedropark99/freetype-zig/tree/main>\n\nAfter you download the source code of FreeType from the official website[^freetype],\nyou can start writing the `build.zig` module. We begin by defining the target object\nthat defines the binary file that we want to compile.\n\nAs an example, I will build the project as a static library file using the `addStaticLibrary()` method\nto create the target object.\nAlso, since FreeType is a C library, I will also link the library\nagainst `libc` through the `linkLibC()` method, to guarantee that any use\nof the C Standard Library is covered in the compilation process.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst target = b.standardTargetOptions(.{});\nconst opti = b.standardOptimizeOption(.{});\nconst lib = b.addStaticLibrary(.{\n    .name = \"freetype\",\n    .optimize = opti,\n    .target = target,\n});\nlib.linkLibC();\n```\n:::\n\n\n\n### Creating C compiler flags\n\nCompiler flags are also known as \"compiler options\" by many programmers,\nor also, as \"command options\" in the GCC official documentation.\nIt's fair to also call them as the \"command-line arguments\" of the C compiler.\nIn general, we use compiler flags to turn on (or turn off) some features from the compiler,\nor to tweak the compilation process to fit the needs of our project.\n\nIn build scripts written in Zig, we normally list the C compiler flags to be used in the compilation process\nin a simple array, like in the example below.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c_flags = [_][]const u8{\n    \"-Wall\",\n    \"-Wextra\",\n    \"-Werror\",\n};\n```\n:::\n\n\n\nIn theory, there is nothing stopping you from using this array to add \"include paths\" (with the `-I` flag)\nor \"library paths\" (with the `-L` flag) to the compilation process. But there are formal ways in Zig to\nadd these types of paths in the compilation process. Both are discussed in @sec-include-paths\nand @sec-library-paths.\n\nAnyway, in Zig, we add C flags to the build process together with the C files that we want to compile, by using the\n`addCSourceFile()` and `addCSourceFiles()` methods. In the example above, we have just declared\nthe C flags that we want to use. But we haven't added them to the build process yet.\nTo do that, we also need to list the C files to be compiled.\n\n### Listing your C files\n\nThe C files that contains \"cross-platform\" source code are listed in the `c_source_files`\nobject below. These are the C files that are included by default in every platform\nsupported by the FreeType library. Now, since the amount of C files in the FreeType library is big,\nI have omitted the rest of the files in the code example below, for brevity purposes.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c_source_files = [_][]const u8{\n    \"src/autofit/autofit.c\",\n    \"src/base/ftbase.c\",\n    // ... and many other C files.\n};\n```\n:::\n\n\n\nNow, in addition to \"cross-platform\" source code, we also have some C files in the FreeType project\nthat are platform-specific, meaning that, they contain source code that can only be compiled in specific platforms,\nand, as a result, they are only included in the build process on these specific target platforms.\nThe objects that list these C files are exposed in the code example below.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst windows_c_source_files = [_][]const u8{\n    \"builds/windows/ftdebug.c\",\n    \"builds/windows/ftsystem.c\"\n};\nconst linux_c_source_files = [_][]const u8{\n    \"src/base/ftsystem.c\",\n    \"src/base/ftdebug.c\"\n};\n```\n:::\n\n\n\nNow that we declared both the files that we want to include and the C compiler flags to be used,\nwe can add them to the target object that describes the FreeType library, by using the\n`addCSourceFile()` and `addCSourceFiles()` methods.\n\nBoth of these functions are methods from a `Compile` object (i.e., a target object).\nThe `addCSourceFile()` method is capable of adding a single C file to the target object,\nwhile the `addCSourceFiles()` method is used to add multiple C files in a single command.\nYou might prefer to use `addCSourceFile()` when you need to use different compiler flags\non specific C files in your project. But, if you can use the same compiler flags\nacross all C files, then, you will probably find `addCSourceFiles()` a better choice.\n\nNotice that we are using the `addCSourceFiles()` method in the example below,\nto add both the C files and the C compiler flags. Also notice that we\nare using the `os.tag` that we learned about in @sec-detect-os, to add the platform-specific\nC files.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nlib.addCSourceFiles(\n    &c_source_files, &c_flags\n);\n\nswitch (builtin.target.os.tag) {\n    .windows => {\n        lib.addCSourceFiles(\n            &windows_c_source_files,\n            &c_flags\n        );\n    },\n    .linux => {\n        lib.addCSourceFiles(\n            &linux_c_source_files,\n            &c_flags\n        );\n    },\n    else => {},\n}\n```\n:::\n\n\n\n\n### Defining C Macros\n\nC Macros are an essential part of the C programming language,\nand they are commonly defined through the `-D` flag from a C compiler.\nIn Zig, you can define a C Macro to be used in your build process\nby using the `defineCMacro()` method from the target object that\ndefines the binary file that you are building.\n\nIn the example below, we are using the `lib` object that we have defined\nin the previous sections to define some C Macros used by the FreeType project\nin the compilation process. These C Macros specify if FreeType\nshould (or should not) include functionalities from different\nexternal libraries.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nlib.defineCMacro(\"FT_DISABLE_ZLIB\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_PNG\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_HARFBUZZ\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BZIP2\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BROTLI\", \"TRUE\");\nlib.defineCMacro(\"FT2_BUILD_LIBRARY\", \"TRUE\");\n```\n:::\n\n\n\n\n### Adding library paths {#sec-library-paths}\n\nLibrary paths are paths in your computer where the C compiler will look (or search) for\nlibrary files to link against your source code. In other words, when you use a library in your\nC source code, and you ask the C compiler to link your source code against this library,\nthe C compiler will search for the binary files of this library across the paths listed\nin this \"library paths\" set.\n\nThese paths are platform specific, and, by default, the C compiler starts by looking at a\npre-defined set of places in your computer. But you can add more paths (or more places)\nto this list. For example, you may have a library installed in a non-conventional place of your\ncomputer, and you can make the C compiler \"see\" this \"non-conventional place\" by adding this path\nto this list of pre-defined paths.\n\nIn Zig, you can add more paths to this set by using the `addLibraryPath()` method from your target object.\nFirst, you defined a `LazyPath` object, containing the path you want to add, then,\nyou provide this object as input to the `addLibraryPath()` method, like in the example below:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst lib_path: std.Build.LazyPath = .{\n    .cwd_relative = \"/usr/local/lib/\"\n};\nlib.addLibraryPath(lib_path);\n```\n:::\n\n\n\n\n\n\n### Adding include paths {#sec-include-paths}\n\nThe preprocessor search path is a popular concept from the\nC community, but it's also known by many C programmers as \"include paths\", because\nthe paths in this \"search path\" relate to the `#include` statements found in the C files.\n\nInclude paths are similar to library paths. They are a set of pre-defined places in your computer where\nthe C compiler will look for files during the compilation process. But instead of looking for\nlibrary files, the include paths are places where the compiler looks for header files included\nin your C source code.\nThis is why many C programmers prefer to call these paths as the \"preprocessor search path\".\nBecause header files are processed during the preprocessor stage of the compilation\nprocess.\n\nSo, every header file that you include in your C source code, through a `#include` statements needs to\nbe found somewhere, and the C compiler will search for this header file across the paths listed in this \"include paths\" set.\nInclude paths are added to the compilation process through the `-I` flag.\n\nIn Zig, you can add new paths to this pre-defined set of paths, by using the `addIncludePath()` method\nfrom your target object. This method also accepts a `LazyPath` object as input.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst inc_path: std.Build.LazyPath = .{\n    .path = \"./include\"\n};\nlib.addIncludePath(inc_path);\n```\n:::\n",
-    "supporting": [
-      "07-build-system_files"
-    ],
-    "filters": [
-      "rmarkdown/pagebreak.lua"
-    ],
-    "includes": {},
-    "engineDependencies": {
-      "knitr": [
-        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
-      ]
-    },
-    "preserve": null,
-    "postProcess": false
-  }
-}
\ No newline at end of file
diff --git a/_freeze/Chapters/07-build-system/execute-results/html.json b/_freeze/Chapters/07-build-system/execute-results/html.json
index 8d0f268d..b1269ae0 100644
--- a/_freeze/Chapters/07-build-system/execute-results/html.json
+++ b/_freeze/Chapters/07-build-system/execute-results/html.json
@@ -2,10 +2,8 @@
   "hash": "0286d5b6db10173d3df147400fd019aa",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Build System {#sec-build-system}\n\n\nIn this chapter, we are going to talk about the build system, and how an entire project\nis built in Zig.\nOne key advantage of Zig is that it includes a build system embedded in the language itself.\nThis is great, because then you do not have to depend on an external system, separated\nfrom the compiler, to build your code.\n\n\nYou can find a good description of Zig's build system\nin the [article entitled \"Build System\"](https://ziglang.org/learn/build-system/#user-provided-options)[^zig-art1]\nfrom the official Zig's website.\nWe also have the excellent [series of posts written by Felix](https://zig.news/xq/zig-build-explained-part-1-59lf)[^felix].\nHence, this chapter represents an extra resource for you to consult and rely on.\n\n[^felix]: <https://zig.news/xq/zig-build-explained-part-1-59lf>\n[^zig-art1]: <https://ziglang.org/learn/build-system/#user-provided-options>\n\nBuilding code is one of the things that Zig is best at. One thing that is particularly\ndifficult in C/C++ and even in Rust, is to cross-compile source code to multiple targets\n(e.g. multiple computer architectures and operating systems),\nand the `zig` compiler is known for being one of the best existing pieces of software\nfor this particular task.\n\n\n\n\n## How source code is built?\n\nWe already have talked about the challenges of building source code in low-level languages\nin @sec-project-files. As we described at that section, programmers invented Build Systems\nto surpass these challenges on the process of building source code in low-level languages.\n\nLow-level languages uses a compiler to compile (or to build) your source code into binary instructions.\nIn C and C++, we normally use compilers like `gcc`, `g++` or `clang` to compile\nour C and C++ source code into these instructions.\nEvery language have its own compiler, and this is no different in Zig.\n\nIn Zig, we have the `zig` compiler to compile our Zig source code into\nbinary instructions that can be executed by our computer.\nIn Zig, the compilation (or the build) process involves\nthe following components:\n\n- The Zig modules that contains your source code;\n- Library files (either a dynamic library or a static library);\n- Compiler flags that tailors the build process to your needs.\n\nThese are the things that you need to connect together in order to build your\nsource code in Zig. In C and C++, you would have an extra component, which are the header files of\nthe libraries that you are using. But header files do not exist in Zig, so, you only need\nto care about them if you are linking your Zig source code with a C library.\nIf that is not your case, you can forget about it.\n\nYour build process is usually organized in a build script. In Zig, we normally\nwrite this build script into a Zig module in the root directory of our project,\nnamed as `build.zig`. You write this build script, then, when you run it, your project\ngets built into binary files that you can use and distribute to your users.\n\nThis build script is normally organized around *target objects*. A target is simply\nsomething to be built, or, in other words, it's something that you want the `zig` compiler\nto build for you. This concept of \"targets\" is present in most Build Systems,\nespecially in CMake[^cmake].\n\n[^cmake]: <https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html>\n\nThere are four types of target objects that you can build in Zig, which are:\n\n- An executable (e.g. a `.exe` file on Windows).\n- A shared library (e.g. a `.so` file in Linux or a `.dll` file on Windows).\n- A static library (e.g. a `.a` file in Linux or a `.lib` file on Windows).\n- An executable file that executes only unit tests (or, a \"unit tests executable\").\n\nWe are going to talk more about these target objects in @sec-targets.\n\n\n\n## The `build()` function {#sec-build-fun}\n\nA build script in Zig always contains a public (and top-level) `build()` function declared.\nIt's like the `main()` function in the main Zig module of your project, that we discussed in @sec-main-file.\nBut instead of creating the entrypoint to your code, this `build()` function is the entrypoint to the build process.\n\nThis `build()` function should accept a pointer to a `Build` object as input, and it should use this \"build object\" to perform\nthe necessary steps to build your project. The return type of this function is always `void`,\nand this `Build` struct comes directly from the Zig Standard Library (`std.Build`). So, you can\naccess this struct by just importing the Zig Standard Library into your `build.zig` module.\n\nJust as a very simple example, here you can see the source code necessary to build\nan executable file from the `hello.zig` Zig module.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"hello.zig\"),\n        .target = b.host,\n    });\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\nYou can define and use other functions and objects in this build script. You can also import\nother Zig modules as you would normally do in any other module of your project.\nThe only real requirement for this build script, is to have a public and top-level\n`build()` function defined, that accepts a pointer to a `Build` struct as input.\n\n\n## Target objects {#sec-targets}\n\nAs we described over the previous sections, a build script is composed around target objects.\nEach target object is normally a binary file (or an output) that you want to get from the build process. You can list\nmultiple target objects in your build script, so that the build process generates multiple\nbinary files for you at once.\n\nFor example, maybe you are a developer working in a cross-platform application,\nand, because this application is cross-platform, you probably need to release\nbinary files of your software for each OS supported by your application to your end users.\nThus, you can define a different target object in your build script\nfor each OS (Windows, Linux, etc.) where you want to publish your software.\nThis will make the `zig` compiler to build your project to multiple target OS's at once.\nThe Zig Build System official documentation have a [great code example that demonstrates this strategy](https://ziglang.org/learn/build-system/#handy-examples)[^zig-ex].\n\n[^zig-ex]: <https://ziglang.org/learn/build-system/#handy-examples>\n\n\nA target object is created by the following methods of the `Build` struct that we introduced\nin @sec-build-fun:\n\n- `addExecutable()` creates an executable file;\n- `addSharedLibrary()` creates a shared library file;\n- `addStaticLibrary()` creates a static library file;\n- `addTest()` creates an executable file that executes unit tests.\n\n\nThese functions are methods from the `Build` struct that you receive\nas input of the `build()` function. All of them, create as output\na `Compile` object, which represents a target object to be compiled\nby the `zig` compiler. All of these functions accept a similar struct literal as input.\nThis struct literal defines three essential specs about this target object that you are building:\n`name`, `target` and `root_source_file`.\n\nWe have already seen these three options being used on the previous example,\nwhere we used the `addExecutable()` method to create an executable target object.\nThis example is reproduced below. Notice the use of the `path()` method\nfrom the `Build` struct, to define a path in the `root_source_file` option.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n```\n:::\n\n\n\n\nThe `name` option specify the name that you want to give to the binary file defined\nby this target object. So, in this example, we are building an executable file named `hello`.\nIt's common to set this `name` option to the name of your project.\n\n\nFurthermore, the `target` option specify the target computer architecture (or the target operating system) of this\nbinary file. For example, if you want this target object to run on a Windows machine\nthat uses a `x86_64` architecture, you can set this `target` option to `x86_64-windows-gnu` for example.\nThis will make the `zig` compiler to compile the project to run on a `x86_64` Windows machine.\nYou can see the full list of architectures and OS's that the `zig` compiler supports by running\nthe `zig targets` command in the terminal.\n\nNow, if you are building the project to run on the current machine\nthat you are using to run this build script, you can set this `target`\noption to the `host` method of the `Build` object, like we did in the example above.\nThis `host` method identifies the current machine where you are\ncurrently running the `zig` compiler.\n\n\nAt last, the `root_source_file` option specifies the root Zig module of your project.\nThat is the Zig module that contains the entrypoint to your application (i.e., the `main()` function), or, the main API of your library.\nThis also means that, all the Zig modules that compose your project are automatically discovered\nfrom the import statements you have inside this \"root source file\".\nThe `zig` compiler can detect when a Zig module depends on the other through the import statements,\nand, as a result, it can discover the entire map of Zig modules used in your project.\n\nThis is handy, and it's different from what happens in other build systems.\nIn CMake for example, you have to explicitly list the paths to all source files that you want to\ninclude in your build process. This is probably a symptom of the \"lack of conditional\ncompilation\" in the C and C++ compilers. Since they lack this feature, you have\nto explicitly choose which source files should be sent to the C/C++ compiler, because not\nevery C/C++ code is portable or supported in every operating system, and, therefore,\nwould cause a compilation error in the C/C++ compiler.\n\n\nNow, one important detail about the build process is that, you have to **explicitly\ninstall the target objects that you create in your build script**, by using the\n`installArtifact()` method of the `Build` struct.\n\nEverytime you invoke the build process of your project, by calling the `build` command\nof the `zig` compiler, a new directory named `zig-out` is created in the root\ndirectory of your project. This new directory contains the outputs of the build process,\nthat is, the binary files built from your source code.\n\nWhat the `installArtifact()` method do is to install (or copy) the built target objects\nthat you defined to this `zig-out` directory.\nThis means that, if you do not\ninstall the target objects you define in your build script, these target objects are\nessentially discarded at the end of the build process.\n\nFor example, you might be building a project that uses a third party library that is built\ntogether with the project. So, when you build your project, you would need first, to\nbuild the third party library, and then, you link it with the source code of your project.\nSo, in this case, we have two binary files that are generated in the build process (the executable file of your project, and the third party library).\nBut only one is of interest, which is the executable file of our project.\nWe can discard the binary file of the third party library, by simply not installing it\ninto this `zig-out` directory.\n\nThis `installArtifact()` method is pretty straightforward. Just remember to apply it to every\ntarget object that you want to save into the `zig-out` directory, like in the example below:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n## Setting the build mode\n\nWe have talked about the three essential options that are set when you create a new target object.\nBut there is also a fourth option that you can use to set the build mode of this target object,\nwhich is the `optimize` option.\nThis option is called this way, because the build modes in Zig are treated more of\nan \"optimization vs safety\" problem. So optimization plays an important role here.\nDon't worry, I'm going back to this question very soon.\n\nIn Zig, we have four build modes (which are listed below). Each one of these build modes offer\ndifferent advantages and characteristics. As we described in @sec-compile-debug-mode, the `zig` compiler\nuses the `Debug` build mode by default, when you don't explicitly choose a build mode.\n\n- `Debug`, mode that produces and includes debugging information in the output of the build process (i.e., the binary file defined by the target object);\n- `ReleaseSmall`, mode that tries to produce a binary file that is small in size;\n- `ReleaseFast`, mode that tries to optimize your code, in order to produce a binary file that is as fast as possible;\n- `ReleaseSafe`, mode that tries to make your code as safe as possible, by including safeguards when possible.\n\nSo, when you build your project, you can set the build mode of your target object to `ReleaseFast` for example, which will tell\nthe `zig` compiler to apply important optimizations in your code. This creates a binary file\nthat simply runs faster on most contexts, because it contains a more optimized version of your code.\nHowever, as a result, we often lose some safety features in our code.\nBecause some safety checks are removed from the final binary file,\nwhich makes your code run faster, but in a less safe manner.\n\nThis choice depends on your current priorities. If you are building a cryptography or banking system, you might\nprefer to prioritize safety in your code, so, you would choose the `ReleaseSafe` build mode, which is a little\nslower to run, but much more secure, because it includes all possible runtime safety checks in the binary file\nbuilt in the build process. In the other hand, if you are writing a game for example, you might prefer to prioritize performance\nover safety, by using the `ReleaseFast` build mode, so that your users can experience faster frame rates in your game.\n\nIn the example below, we are creating the same target object that we have used on previous examples.\nBut this time, we are specifying the build mode of this target object to the `ReleaseSafe` mode.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .optimize = .ReleaseSafe\n});\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n## Setting the version of your build\n\nEverytime you build a target object in your build script, you can assign a version\nnumber to this specific build, following a semantic versioning framework.\nYou can find more about semantic versioning by visiting the [Semantic Versioning website](https://semver.org/)[^semver].\nAnyway, in Zig, you can specify the version of your build, by providing a `SemanticVersion` struct to\nthe `version` option, like in the example below:\n\n\n[^semver]: <https://semver.org/>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .version = .{\n        .major = 2, .minor = 9, .patch = 7\n    }\n});\nb.installArtifact(exe);\n```\n:::\n\n\n\n\n\n## Detecting the OS in your build script {#sec-detect-os}\n\nIt's very common in Build Systems to use different options, or, to include different modules, or,\nto link against different libraries depending on the Operational System (OS)\nthat you are targeting in the build process.\n\nIn Zig, you can detect the target OS of the build process, by looking\nat the `os.tag` inside the `builtin` module from the Zig library.\nIn the example below, we are using an if statement to run some\narbitrary code when the target of the build process is a\nWindows system.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nif (builtin.target.os.tag == .windows) {\n    // Code that runs only when the target of\n    // the compilation process is Windows.\n}\n```\n:::\n\n\n\n\n\n## Adding a run step to your build process\n\nOne thing that is neat in Rust is that you can compile and run your\nsource code with one single command (`cargo run`) from the Rust compiler.\nWe saw in @sec-compile-run-code how can we perform a similar job in Zig, by\nbuilding and running our Zig source code through the `run` command from the `zig` compiler.\n\nBut how can we, at the same time, build and run the binary file specified by a target object in our\nbuild script?\nThe answer is by including a \"run artifact\" in our build script.\nA run artifact is created through the `addRunArtifact()` method from the `Build` struct.\nWe simply provide as input to this function the target object that describes the binary file that we\nwant to execute. As a result, this function creates a run artifact that is capable of executing\nthis binary file.\n\nIn the example below, we are defining an executable binary file named `hello`,\nand we use this `addRunArtifact()` method to create a run artifact that will execute\nthis `hello` executable file.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"src/hello.zig\"),\n    .target = b.host\n});\nb.installArtifact(exe);\nconst run_arti = b.addRunArtifact(exe);\n```\n:::\n\n\n\n\nNow that we have created this run artifact, we need to include it in\nthe build process. We do that by declaring a new step in our build\nscript to call this artifact, through the `step()` method of the `Build`\nstruct.\n\nWe can give any name we want to this step, but, for our\ncontext here, I'm going to name this step as \"run\".\nAlso, I give it a brief description to this step (\"Run the project\").\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst run_step = b.step(\n    \"run\", \"Run the project\"\n);\n```\n:::\n\n\n\n\n\nNow that we have declared this \"run step\" we need to tell Zig that\nthis \"run step\" depends on the run artifact.\nIn other words, a run artifact always depends on a \"step\" to effectively be executed.\nBy creating this dependency\nwe finally stablish the necessary commands to build and run the executable file\nfrom the build script.\n\nWe can establish a dependency between the run step and the run artifact\nby using the `dependsOn()` method from the run step. So, we first\ncreate the run step, and then, we link it with the run artifact, by\nusing this `dependsOn()` method from the run step.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nrun_step.dependOn(&run_arti.step);\n```\n:::\n\n\n\n\nThe entire source code of this specific build script that\nwe wrote, piece by piece, in this section, is\navailable in the `build_and_run.zig` module. You can\nsee this module by\n[visiting the official repository of this book](https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig)\n[^module-src].\n\n\n[^module-src]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig>\n\nWhen you declare a new step in your build script, this step\nbecomes available through the `build` command in the `zig` compiler.\nYou can actually see this step by running `zig build --help` in the terminal, like\nin the example below, where we can see that this new \"run\"\nstep that we declared in the build script appeared in the output.\n\n```bash\nzig build --help\n```\n\n```\nSteps:\n  ...\n  run   Run the project\n  ...\n```\n\nNow, everything that we need to is to\ncall this \"run\" step that we created in our build script. We\ncall it by using the name that we gave to this step\nafter the `build` command from the `zig` compiler.\nThis will cause the compiler to build our executable file\nand execute it at the same time.\n\n```bash\nzig build run\n```\n\n## Build unit tests in your project\n\nWe have talked at length about writing unit tests in Zig in @sec-unittests,\nand we also have talked about how to execute these unit tests through\nthe `test` command of the `zig` compiler. However,\nas we did with the `run` command on the previous section, we also might want to\ninclude some commands in our build script to also build and execute the unit tests in our project.\n\nSo, once again, we are going to discuss how a specific built-in command from the `zig` compiler,\n(in this case, the `test` command) can be used in a build script in Zig.\nHere is where a \"test target object\" comes into play.\nAs was described in @sec-targets, we can create a test target object by using the `addTest()` method of\nthe `Build` struct. The first thing that we need to do is to\ndeclare a test target object in our build script.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst test_exe = b.addTest(.{\n    .name = \"unit_tests\",\n    .root_source_file = b.path(\"src/main.zig\"),\n    .target = b.host,\n});\nb.installArtifact(test_exe);\n```\n:::\n\n\n\n\n\nA test target object essentially selects all `test` blocks in all Zig modules\nacross your project, and builds only the source code present inside\nthese `test` blocks in your project. As a result, this target object\ncreates an executable file that contains only the source code present\nin all of these `test` blocks (i.e., the unit tests) in your project.\n\nPerfect! Now that we have declared this test target object, an executable file\nnamed `unit_tests` is built by the `zig` compiler when we trigger the build\nscript with the `build` command. After the build\nprocess is finished, we can simply execute this `unit_tests` executable\nin the terminal.\n\nHowever, if you remember the previous section, we already learned\nhow can we create a run step in our build script, to execute an executable file\nbuilt by the build script.\n\nSo, we could simply add a run step in our build script to run these unit tests\nfrom a single command in the `zig` compiler, to make our lifes easier.\nIn the example below, we demonstrate the commands to\nregister a new build step called \"tests\" in our build script\nto run these unit tests.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst run_arti = b.addRunArtifact(test_exe);\nconst run_step = b.step(\"tests\", \"Run unit tests\");\nrun_step.dependOn(&run_arti.step);\n```\n:::\n\n\n\n\nNow that we registered this new build step, we can trigger it by calling the command below\nin the terminal. You can also checkout the complete source\ncode for this specific build script at the `build_tests.zig` module at the\n[official repository of this book](https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig)\n[^module-src2].\n\n\n[^module-src2]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig>\n\n\n```bash\nzig build tests\n```\n\n\n## Tailoring your build process with user-provided options\n\nSometimes, you want to make a build script that is customizable by the user\nof your project. You can do that by creating user-provided options in\nyour build script. We create an user-provided option by using the\n`option()` method from the `Build` struct.\n\nWith this method, we create a \"build option\" which can be passed\nto the `build.zig` script at the command line. The user have the power of setting\nthis option at the `build` command from the\n`zig` compiler. In other words, each build option that we create\nbecomes a new command line argument that is accessible through the `build` command\nof the compiler.\n\nThese \"user-provided options\" are set by using the prefix `-D` in the command line.\nFor example, if we declare an option named `use_zlib`, that receives a boolean value which\nindicates if we should link our source code to `zlib` or not, we can set the value\nof this option in the command line with `-Duse_zlib`. The code example below\ndemonstrates this idea:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const use_zlib = b.option(\n        bool,\n        \"use_zlib\",\n        \"Should link to zlib?\"\n    ) orelse false;\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"example.zig\"),\n        .target = b.host,\n    });\n    if (use_zlib) {\n        exe.linkSystemLibrary(\"zlib\");\n    }\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\n```bash\nzig build -Duse_zlib=false\n```\n\n\n## Linking to external libraries\n\n\nOne essential part of every build process is the linking stage.\nThis stage is responsible for combining the multiple object files\nthat represent your code, into a single executable file. It also links\nthis executable file to external libraries, if you use any in your code.\n\nIn Zig, we have two notions of a \"library\", which are: 1) a system's library;\n2) a local library. A system's library is just a library that is already installed\nin your system. While a local library is a library that belongs to the current\nproject; a library that is present in your project directory, and\nthat you are building together with your project source code.\n\nThe basic difference between the two, is that a system's library is already\nbuilt and installed in your system, supposedly, and all you need to do\nis to link your source code to this library to start using it.\nWe do that by using the `linkSystemLibrary()` method from a\n`Compile` object. This method accepts the name of the library\nin a string as input. Remember from @sec-targets that a `Compile` object\nis a target object that you declare in your build script.\n\nWhen you link a particular target object with a system's library,\nthe `zig` compiler will use `pkg-config` to find where\nare the binary files and also the header files of this library\nin your system.\nWhen it finds these files, the linker present in the `zig` compiler\nwill link your object files with the files of this library to\nproduce a single binary file for you.\n\nIn the example below, we are creating an executable file named `image_filter`,\nand, we are linking this executable file to the C Standard Library with the\nmethod `linkLibC()`, but we also are linking this executable file to the\nC library `libpng` that is currently installed in my system.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"image_filter\",\n        .root_source_file = b.path(\"src/main.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n    exe.linkLibC();\n    exe.linkSystemLibrary(\"png\");\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\nIf you are linking with a C library in your project, is generally a good idea\nto also link your code with the C Standard Library. Because is very likely\nthat this C library uses some functionality of the C Standard Library at some point.\nThe same goes to C++ libraries. So, if you are linking with\nC++ libraries, is a good idea to link your project with the C++\nStandard Library by using the `linkLibCpp()` method.\n\nOn the order side, when you want to link with a local library,\nyou should use the `linkLibrary()` method of a `Compile` object.\nThis method expects to receive another `Compile` object as input.\nThat is, another target object defined in your build script,\nusing either the `addStaticLibrary()` or `addSharedLibrary()` methods\nwhich defines a library to be built.\n\nAs we discussed earlier, a local library is a library\nthat is local to your project, and that is being built together\nwith your project. So, you need to create a target object in your build script\nto build this local library. Then, you link the target objects of interest in your project,\nwith this target object that identifies this local library.\n\nTake a look at this example extracted from the build script of the [`libxev` library](https://github.com/mitchellh/libxev/tree/main)[^libxev2].\nYou can see in this snippet that\nwe are declaring a shared library file, from the `c_api.zig`\nmodule. Then, later in the build script, we declare an\nexecutable file named `\"dynamic-binding-test\"`, which\nlinks to this shared library that we defined earlier\nin the script.\n\n[^libxev2]: <https://github.com/mitchellh/libxev/tree/main>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst optimize = b.standardOptimizeOption(.{});\nconst target = b.standardTargetOptions(.{});\n\nconst dynamic_lib = b.addSharedLibrary(.{\n    .name = dynamic_lib_name,\n    .root_source_file = b.path(\"src/c_api.zig\"),\n    .target = target,\n    .optimize = optimize,\n});\nb.installArtifact(dynamic_lib);\n// ... more lines in the script\nconst dynamic_binding_test = b.addExecutable(.{\n    .name = \"dynamic-binding-test\",\n    .target = target,\n    .optimize = optimize,\n});\ndynamic_binding_test.linkLibrary(dynamic_lib);\n```\n:::\n\n\n\n\n\n\n## Building C code {#sec-building-c-code}\n\nThe `zig` compiler comes with a C compiler embedded in it. In other words,\nyou can use the `zig` compiler to build C projects. This C compiler is available\nthrough the `cc` command of the `zig` compiler.\n\nAs an example, let's use the famous [FreeType library](https://freetype.org/)[^freetype].\nFreeType is one of the most widely used pieces of software in the world.\nIt's a C library designed to produce high-quality fonts. But it's also\nheavily used in the industry to natively render text and fonts\nin the screen of your computer.\n\nIn this section, we are going to write a build script, piece by piece, that is capable\nof building the FreeType project from source.\nYou can find the source code of this build script on the\n[`freetype-zig` repository](https://github.com/pedropark99/freetype-zig/tree/main)[^freetype-zig]\navailable at GitHub.\n\n[^freetype]: <https://freetype.org/>\n[^freetype-zig]: <https://github.com/pedropark99/freetype-zig/tree/main>\n\nAfter you download the source code of FreeType from the official website[^freetype],\nyou can start writing the `build.zig` module. We begin by defining the target object\nthat defines the binary file that we want to compile.\n\nAs an example, I will build the project as a static library file using the `addStaticLibrary()` method\nto create the target object.\nAlso, since FreeType is a C library, I will also link the library\nagainst `libc` through the `linkLibC()` method, to guarantee that any use\nof the C Standard Library is covered in the compilation process.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst target = b.standardTargetOptions(.{});\nconst opti = b.standardOptimizeOption(.{});\nconst lib = b.addStaticLibrary(.{\n    .name = \"freetype\",\n    .optimize = opti,\n    .target = target,\n});\nlib.linkLibC();\n```\n:::\n\n\n\n\n### Creating C compiler flags\n\nCompiler flags are also known as \"compiler options\" by many programmers,\nor also, as \"command options\" in the GCC official documentation.\nIt's fair to also call them as the \"command-line arguments\" of the C compiler.\nIn general, we use compiler flags to turn on (or turn off) some features from the compiler,\nor to tweak the compilation process to fit the needs of our project.\n\nIn build scripts written in Zig, we normally list the C compiler flags to be used in the compilation process\nin a simple array, like in the example below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c_flags = [_][]const u8{\n    \"-Wall\",\n    \"-Wextra\",\n    \"-Werror\",\n};\n```\n:::\n\n\n\n\nIn theory, there is nothing stopping you from using this array to add \"include paths\" (with the `-I` flag)\nor \"library paths\" (with the `-L` flag) to the compilation process. But there are formal ways in Zig to\nadd these types of paths in the compilation process. Both are discussed in @sec-include-paths\nand @sec-library-paths.\n\nAnyway, in Zig, we add C flags to the build process together with the C files that we want to compile, by using the\n`addCSourceFile()` and `addCSourceFiles()` methods. In the example above, we have just declared\nthe C flags that we want to use. But we haven't added them to the build process yet.\nTo do that, we also need to list the C files to be compiled.\n\n### Listing your C files\n\nThe C files that contains \"cross-platform\" source code are listed in the `c_source_files`\nobject below. These are the C files that are included by default in every platform\nsupported by the FreeType library. Now, since the amount of C files in the FreeType library is big,\nI have omitted the rest of the files in the code example below, for brevity purposes.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c_source_files = [_][]const u8{\n    \"src/autofit/autofit.c\",\n    \"src/base/ftbase.c\",\n    // ... and many other C files.\n};\n```\n:::\n\n\n\n\nNow, in addition to \"cross-platform\" source code, we also have some C files in the FreeType project\nthat are platform-specific, meaning that, they contain source code that can only be compiled in specific platforms,\nand, as a result, they are only included in the build process on these specific target platforms.\nThe objects that list these C files are exposed in the code example below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst windows_c_source_files = [_][]const u8{\n    \"builds/windows/ftdebug.c\",\n    \"builds/windows/ftsystem.c\"\n};\nconst linux_c_source_files = [_][]const u8{\n    \"src/base/ftsystem.c\",\n    \"src/base/ftdebug.c\"\n};\n```\n:::\n\n\n\n\nNow that we declared both the files that we want to include and the C compiler flags to be used,\nwe can add them to the target object that describes the FreeType library, by using the\n`addCSourceFile()` and `addCSourceFiles()` methods.\n\nBoth of these functions are methods from a `Compile` object (i.e., a target object).\nThe `addCSourceFile()` method is capable of adding a single C file to the target object,\nwhile the `addCSourceFiles()` method is used to add multiple C files in a single command.\nYou might prefer to use `addCSourceFile()` when you need to use different compiler flags\non specific C files in your project. But, if you can use the same compiler flags\nacross all C files, then, you will probably find `addCSourceFiles()` a better choice.\n\nNotice that we are using the `addCSourceFiles()` method in the example below,\nto add both the C files and the C compiler flags. Also notice that we\nare using the `os.tag` that we learned about in @sec-detect-os, to add the platform-specific\nC files.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nlib.addCSourceFiles(\n    &c_source_files, &c_flags\n);\n\nswitch (builtin.target.os.tag) {\n    .windows => {\n        lib.addCSourceFiles(\n            &windows_c_source_files,\n            &c_flags\n        );\n    },\n    .linux => {\n        lib.addCSourceFiles(\n            &linux_c_source_files,\n            &c_flags\n        );\n    },\n    else => {},\n}\n```\n:::\n\n\n\n\n\n### Defining C Macros\n\nC Macros are an essential part of the C programming language,\nand they are commonly defined through the `-D` flag from a C compiler.\nIn Zig, you can define a C Macro to be used in your build process\nby using the `defineCMacro()` method from the target object that\ndefines the binary file that you are building.\n\nIn the example below, we are using the `lib` object that we have defined\nin the previous sections to define some C Macros used by the FreeType project\nin the compilation process. These C Macros specify if FreeType\nshould (or should not) include functionalities from different\nexternal libraries.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nlib.defineCMacro(\"FT_DISABLE_ZLIB\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_PNG\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_HARFBUZZ\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BZIP2\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BROTLI\", \"TRUE\");\nlib.defineCMacro(\"FT2_BUILD_LIBRARY\", \"TRUE\");\n```\n:::\n\n\n\n\n\n### Adding library paths {#sec-library-paths}\n\nLibrary paths are paths in your computer where the C compiler will look (or search) for\nlibrary files to link against your source code. In other words, when you use a library in your\nC source code, and you ask the C compiler to link your source code against this library,\nthe C compiler will search for the binary files of this library across the paths listed\nin this \"library paths\" set.\n\nThese paths are platform specific, and, by default, the C compiler starts by looking at a\npre-defined set of places in your computer. But you can add more paths (or more places)\nto this list. For example, you may have a library installed in a non-conventional place of your\ncomputer, and you can make the C compiler \"see\" this \"non-conventional place\" by adding this path\nto this list of pre-defined paths.\n\nIn Zig, you can add more paths to this set by using the `addLibraryPath()` method from your target object.\nFirst, you defined a `LazyPath` object, containing the path you want to add, then,\nyou provide this object as input to the `addLibraryPath()` method, like in the example below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst lib_path: std.Build.LazyPath = .{\n    .cwd_relative = \"/usr/local/lib/\"\n};\nlib.addLibraryPath(lib_path);\n```\n:::\n\n\n\n\n\n\n\n### Adding include paths {#sec-include-paths}\n\nThe preprocessor search path is a popular concept from the\nC community, but it's also known by many C programmers as \"include paths\", because\nthe paths in this \"search path\" relate to the `#include` statements found in the C files.\n\nInclude paths are similar to library paths. They are a set of pre-defined places in your computer where\nthe C compiler will look for files during the compilation process. But instead of looking for\nlibrary files, the include paths are places where the compiler looks for header files included\nin your C source code.\nThis is why many C programmers prefer to call these paths as the \"preprocessor search path\".\nBecause header files are processed during the preprocessor stage of the compilation\nprocess.\n\nSo, every header file that you include in your C source code, through a `#include` statements needs to\nbe found somewhere, and the C compiler will search for this header file across the paths listed in this \"include paths\" set.\nInclude paths are added to the compilation process through the `-I` flag.\n\nIn Zig, you can add new paths to this pre-defined set of paths, by using the `addIncludePath()` method\nfrom your target object. This method also accepts a `LazyPath` object as input.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst inc_path: std.Build.LazyPath = .{\n    .path = \"./include\"\n};\nlib.addIncludePath(inc_path);\n```\n:::\n",
-    "supporting": [
-      "07-build-system_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Build System {#sec-build-system}\n\n\nIn this chapter, we are going to talk about the build system, and how an entire project\nis built in Zig.\nOne key advantage of Zig is that it includes a build system embedded in the language itself.\nThis is great, because then you do not have to depend on an external system, separated\nfrom the compiler, to build your code.\n\n\nYou can find a good description of Zig's build system\nin the [article entitled \"Build System\"](https://ziglang.org/learn/build-system/#user-provided-options)[^zig-art1]\nfrom the official Zig's website.\nWe also have the excellent [series of posts written by Felix](https://zig.news/xq/zig-build-explained-part-1-59lf)[^felix].\nHence, this chapter represents an extra resource for you to consult and rely on.\n\n[^felix]: <https://zig.news/xq/zig-build-explained-part-1-59lf>\n[^zig-art1]: <https://ziglang.org/learn/build-system/#user-provided-options>\n\nBuilding code is one of the things that Zig is best at. One thing that is particularly\ndifficult in C/C++ and even in Rust, is to cross-compile source code to multiple targets\n(e.g. multiple computer architectures and operating systems),\nand the `zig` compiler is known for being one of the best existing pieces of software\nfor this particular task.\n\n\n\n\n## How source code is built?\n\nWe already have talked about the challenges of building source code in low-level languages\nin @sec-project-files. As we described at that section, programmers invented Build Systems\nto surpass these challenges on the process of building source code in low-level languages.\n\nLow-level languages uses a compiler to compile (or to build) your source code into binary instructions.\nIn C and C++, we normally use compilers like `gcc`, `g++` or `clang` to compile\nour C and C++ source code into these instructions.\nEvery language have its own compiler, and this is no different in Zig.\n\nIn Zig, we have the `zig` compiler to compile our Zig source code into\nbinary instructions that can be executed by our computer.\nIn Zig, the compilation (or the build) process involves\nthe following components:\n\n- The Zig modules that contains your source code;\n- Library files (either a dynamic library or a static library);\n- Compiler flags that tailors the build process to your needs.\n\nThese are the things that you need to connect together in order to build your\nsource code in Zig. In C and C++, you would have an extra component, which are the header files of\nthe libraries that you are using. But header files do not exist in Zig, so, you only need\nto care about them if you are linking your Zig source code with a C library.\nIf that is not your case, you can forget about it.\n\nYour build process is usually organized in a build script. In Zig, we normally\nwrite this build script into a Zig module in the root directory of our project,\nnamed as `build.zig`. You write this build script, then, when you run it, your project\ngets built into binary files that you can use and distribute to your users.\n\nThis build script is normally organized around *target objects*. A target is simply\nsomething to be built, or, in other words, it's something that you want the `zig` compiler\nto build for you. This concept of \"targets\" is present in most Build Systems,\nespecially in CMake[^cmake].\n\n[^cmake]: <https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html>\n\nThere are four types of target objects that you can build in Zig, which are:\n\n- An executable (e.g. a `.exe` file on Windows).\n- A shared library (e.g. a `.so` file in Linux or a `.dll` file on Windows).\n- A static library (e.g. a `.a` file in Linux or a `.lib` file on Windows).\n- An executable file that executes only unit tests (or, a \"unit tests executable\").\n\nWe are going to talk more about these target objects in @sec-targets.\n\n\n\n## The `build()` function {#sec-build-fun}\n\nA build script in Zig always contains a public (and top-level) `build()` function declared.\nIt's like the `main()` function in the main Zig module of your project, that we discussed in @sec-main-file.\nBut instead of creating the entrypoint to your code, this `build()` function is the entrypoint to the build process.\n\nThis `build()` function should accept a pointer to a `Build` object as input, and it should use this \"build object\" to perform\nthe necessary steps to build your project. The return type of this function is always `void`,\nand this `Build` struct comes directly from the Zig Standard Library (`std.Build`). So, you can\naccess this struct by just importing the Zig Standard Library into your `build.zig` module.\n\nJust as a very simple example, here you can see the source code necessary to build\nan executable file from the `hello.zig` Zig module.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"hello.zig\"),\n        .target = b.host,\n    });\n    b.installArtifact(exe);\n}\n```\n:::\n\n\nYou can define and use other functions and objects in this build script. You can also import\nother Zig modules as you would normally do in any other module of your project.\nThe only real requirement for this build script, is to have a public and top-level\n`build()` function defined, that accepts a pointer to a `Build` struct as input.\n\n\n## Target objects {#sec-targets}\n\nAs we described over the previous sections, a build script is composed around target objects.\nEach target object is normally a binary file (or an output) that you want to get from the build process. You can list\nmultiple target objects in your build script, so that the build process generates multiple\nbinary files for you at once.\n\nFor example, maybe you are a developer working in a cross-platform application,\nand, because this application is cross-platform, you probably need to release\nbinary files of your software for each OS supported by your application to your end users.\nThus, you can define a different target object in your build script\nfor each OS (Windows, Linux, etc.) where you want to publish your software.\nThis will make the `zig` compiler to build your project to multiple target OS's at once.\nThe Zig Build System official documentation have a [great code example that demonstrates this strategy](https://ziglang.org/learn/build-system/#handy-examples)[^zig-ex].\n\n[^zig-ex]: <https://ziglang.org/learn/build-system/#handy-examples>\n\n\nA target object is created by the following methods of the `Build` struct that we introduced\nin @sec-build-fun:\n\n- `addExecutable()` creates an executable file;\n- `addSharedLibrary()` creates a shared library file;\n- `addStaticLibrary()` creates a static library file;\n- `addTest()` creates an executable file that executes unit tests.\n\n\nThese functions are methods from the `Build` struct that you receive\nas input of the `build()` function. All of them, create as output\na `Compile` object, which represents a target object to be compiled\nby the `zig` compiler. All of these functions accept a similar struct literal as input.\nThis struct literal defines three essential specs about this target object that you are building:\n`name`, `target` and `root_source_file`.\n\nWe have already seen these three options being used on the previous example,\nwhere we used the `addExecutable()` method to create an executable target object.\nThis example is reproduced below. Notice the use of the `path()` method\nfrom the `Build` struct, to define a path in the `root_source_file` option.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n```\n:::\n\n\nThe `name` option specify the name that you want to give to the binary file defined\nby this target object. So, in this example, we are building an executable file named `hello`.\nIt's common to set this `name` option to the name of your project.\n\n\nFurthermore, the `target` option specify the target computer architecture (or the target operating system) of this\nbinary file. For example, if you want this target object to run on a Windows machine\nthat uses a `x86_64` architecture, you can set this `target` option to `x86_64-windows-gnu` for example.\nThis will make the `zig` compiler to compile the project to run on a `x86_64` Windows machine.\nYou can see the full list of architectures and OS's that the `zig` compiler supports by running\nthe `zig targets` command in the terminal.\n\nNow, if you are building the project to run on the current machine\nthat you are using to run this build script, you can set this `target`\noption to the `host` method of the `Build` object, like we did in the example above.\nThis `host` method identifies the current machine where you are\ncurrently running the `zig` compiler.\n\n\nAt last, the `root_source_file` option specifies the root Zig module of your project.\nThat is the Zig module that contains the entrypoint to your application (i.e., the `main()` function), or, the main API of your library.\nThis also means that, all the Zig modules that compose your project are automatically discovered\nfrom the import statements you have inside this \"root source file\".\nThe `zig` compiler can detect when a Zig module depends on the other through the import statements,\nand, as a result, it can discover the entire map of Zig modules used in your project.\n\nThis is handy, and it's different from what happens in other build systems.\nIn CMake for example, you have to explicitly list the paths to all source files that you want to\ninclude in your build process. This is probably a symptom of the \"lack of conditional\ncompilation\" in the C and C++ compilers. Since they lack this feature, you have\nto explicitly choose which source files should be sent to the C/C++ compiler, because not\nevery C/C++ code is portable or supported in every operating system, and, therefore,\nwould cause a compilation error in the C/C++ compiler.\n\n\nNow, one important detail about the build process is that, you have to **explicitly\ninstall the target objects that you create in your build script**, by using the\n`installArtifact()` method of the `Build` struct.\n\nEverytime you invoke the build process of your project, by calling the `build` command\nof the `zig` compiler, a new directory named `zig-out` is created in the root\ndirectory of your project. This new directory contains the outputs of the build process,\nthat is, the binary files built from your source code.\n\nWhat the `installArtifact()` method do is to install (or copy) the built target objects\nthat you defined to this `zig-out` directory.\nThis means that, if you do not\ninstall the target objects you define in your build script, these target objects are\nessentially discarded at the end of the build process.\n\nFor example, you might be building a project that uses a third party library that is built\ntogether with the project. So, when you build your project, you would need first, to\nbuild the third party library, and then, you link it with the source code of your project.\nSo, in this case, we have two binary files that are generated in the build process (the executable file of your project, and the third party library).\nBut only one is of interest, which is the executable file of our project.\nWe can discard the binary file of the third party library, by simply not installing it\ninto this `zig-out` directory.\n\nThis `installArtifact()` method is pretty straightforward. Just remember to apply it to every\ntarget object that you want to save into the `zig-out` directory, like in the example below:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n});\n\nb.installArtifact(exe);\n```\n:::\n\n\n\n## Setting the build mode\n\nWe have talked about the three essential options that are set when you create a new target object.\nBut there is also a fourth option that you can use to set the build mode of this target object,\nwhich is the `optimize` option.\nThis option is called this way, because the build modes in Zig are treated more of\nan \"optimization vs safety\" problem. So optimization plays an important role here.\nDon't worry, I'm going back to this question very soon.\n\nIn Zig, we have four build modes (which are listed below). Each one of these build modes offer\ndifferent advantages and characteristics. As we described in @sec-compile-debug-mode, the `zig` compiler\nuses the `Debug` build mode by default, when you don't explicitly choose a build mode.\n\n- `Debug`, mode that produces and includes debugging information in the output of the build process (i.e., the binary file defined by the target object);\n- `ReleaseSmall`, mode that tries to produce a binary file that is small in size;\n- `ReleaseFast`, mode that tries to optimize your code, in order to produce a binary file that is as fast as possible;\n- `ReleaseSafe`, mode that tries to make your code as safe as possible, by including safeguards when possible.\n\nSo, when you build your project, you can set the build mode of your target object to `ReleaseFast` for example, which will tell\nthe `zig` compiler to apply important optimizations in your code. This creates a binary file\nthat simply runs faster on most contexts, because it contains a more optimized version of your code.\nHowever, as a result, we often lose some safety features in our code.\nBecause some safety checks are removed from the final binary file,\nwhich makes your code run faster, but in a less safe manner.\n\nThis choice depends on your current priorities. If you are building a cryptography or banking system, you might\nprefer to prioritize safety in your code, so, you would choose the `ReleaseSafe` build mode, which is a little\nslower to run, but much more secure, because it includes all possible runtime safety checks in the binary file\nbuilt in the build process. In the other hand, if you are writing a game for example, you might prefer to prioritize performance\nover safety, by using the `ReleaseFast` build mode, so that your users can experience faster frame rates in your game.\n\nIn the example below, we are creating the same target object that we have used on previous examples.\nBut this time, we are specifying the build mode of this target object to the `ReleaseSafe` mode.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .optimize = .ReleaseSafe\n});\nb.installArtifact(exe);\n```\n:::\n\n\n\n## Setting the version of your build\n\nEverytime you build a target object in your build script, you can assign a version\nnumber to this specific build, following a semantic versioning framework.\nYou can find more about semantic versioning by visiting the [Semantic Versioning website](https://semver.org/)[^semver].\nAnyway, in Zig, you can specify the version of your build, by providing a `SemanticVersion` struct to\nthe `version` option, like in the example below:\n\n\n[^semver]: <https://semver.org/>\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"hello.zig\"),\n    .target = b.host,\n    .version = .{\n        .major = 2, .minor = 9, .patch = 7\n    }\n});\nb.installArtifact(exe);\n```\n:::\n\n\n\n## Detecting the OS in your build script {#sec-detect-os}\n\nIt's very common in Build Systems to use different options, or, to include different modules, or,\nto link against different libraries depending on the Operational System (OS)\nthat you are targeting in the build process.\n\nIn Zig, you can detect the target OS of the build process, by looking\nat the `os.tag` inside the `builtin` module from the Zig library.\nIn the example below, we are using an if statement to run some\narbitrary code when the target of the build process is a\nWindows system.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nif (builtin.target.os.tag == .windows) {\n    // Code that runs only when the target of\n    // the compilation process is Windows.\n}\n```\n:::\n\n\n\n## Adding a run step to your build process\n\nOne thing that is neat in Rust is that you can compile and run your\nsource code with one single command (`cargo run`) from the Rust compiler.\nWe saw in @sec-compile-run-code how can we perform a similar job in Zig, by\nbuilding and running our Zig source code through the `run` command from the `zig` compiler.\n\nBut how can we, at the same time, build and run the binary file specified by a target object in our\nbuild script?\nThe answer is by including a \"run artifact\" in our build script.\nA run artifact is created through the `addRunArtifact()` method from the `Build` struct.\nWe simply provide as input to this function the target object that describes the binary file that we\nwant to execute. As a result, this function creates a run artifact that is capable of executing\nthis binary file.\n\nIn the example below, we are defining an executable binary file named `hello`,\nand we use this `addRunArtifact()` method to create a run artifact that will execute\nthis `hello` executable file.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exe = b.addExecutable(.{\n    .name = \"hello\",\n    .root_source_file = b.path(\"src/hello.zig\"),\n    .target = b.host\n});\nb.installArtifact(exe);\nconst run_arti = b.addRunArtifact(exe);\n```\n:::\n\n\nNow that we have created this run artifact, we need to include it in\nthe build process. We do that by declaring a new step in our build\nscript to call this artifact, through the `step()` method of the `Build`\nstruct.\n\nWe can give any name we want to this step, but, for our\ncontext here, I'm going to name this step as \"run\".\nAlso, I give it a brief description to this step (\"Run the project\").\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst run_step = b.step(\n    \"run\", \"Run the project\"\n);\n```\n:::\n\n\n\nNow that we have declared this \"run step\" we need to tell Zig that\nthis \"run step\" depends on the run artifact.\nIn other words, a run artifact always depends on a \"step\" to effectively be executed.\nBy creating this dependency\nwe finally stablish the necessary commands to build and run the executable file\nfrom the build script.\n\nWe can establish a dependency between the run step and the run artifact\nby using the `dependsOn()` method from the run step. So, we first\ncreate the run step, and then, we link it with the run artifact, by\nusing this `dependsOn()` method from the run step.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nrun_step.dependOn(&run_arti.step);\n```\n:::\n\n\nThe entire source code of this specific build script that\nwe wrote, piece by piece, in this section, is\navailable in the `build_and_run.zig` module. You can\nsee this module by\n[visiting the official repository of this book](https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig)\n[^module-src].\n\n\n[^module-src]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_and_run.zig>\n\nWhen you declare a new step in your build script, this step\nbecomes available through the `build` command in the `zig` compiler.\nYou can actually see this step by running `zig build --help` in the terminal, like\nin the example below, where we can see that this new \"run\"\nstep that we declared in the build script appeared in the output.\n\n```bash\nzig build --help\n```\n\n```\nSteps:\n  ...\n  run   Run the project\n  ...\n```\n\nNow, everything that we need to is to\ncall this \"run\" step that we created in our build script. We\ncall it by using the name that we gave to this step\nafter the `build` command from the `zig` compiler.\nThis will cause the compiler to build our executable file\nand execute it at the same time.\n\n```bash\nzig build run\n```\n\n## Build unit tests in your project\n\nWe have talked at length about writing unit tests in Zig in @sec-unittests,\nand we also have talked about how to execute these unit tests through\nthe `test` command of the `zig` compiler. However,\nas we did with the `run` command on the previous section, we also might want to\ninclude some commands in our build script to also build and execute the unit tests in our project.\n\nSo, once again, we are going to discuss how a specific built-in command from the `zig` compiler,\n(in this case, the `test` command) can be used in a build script in Zig.\nHere is where a \"test target object\" comes into play.\nAs was described in @sec-targets, we can create a test target object by using the `addTest()` method of\nthe `Build` struct. The first thing that we need to do is to\ndeclare a test target object in our build script.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst test_exe = b.addTest(.{\n    .name = \"unit_tests\",\n    .root_source_file = b.path(\"src/main.zig\"),\n    .target = b.host,\n});\nb.installArtifact(test_exe);\n```\n:::\n\n\n\nA test target object essentially selects all `test` blocks in all Zig modules\nacross your project, and builds only the source code present inside\nthese `test` blocks in your project. As a result, this target object\ncreates an executable file that contains only the source code present\nin all of these `test` blocks (i.e., the unit tests) in your project.\n\nPerfect! Now that we have declared this test target object, an executable file\nnamed `unit_tests` is built by the `zig` compiler when we trigger the build\nscript with the `build` command. After the build\nprocess is finished, we can simply execute this `unit_tests` executable\nin the terminal.\n\nHowever, if you remember the previous section, we already learned\nhow can we create a run step in our build script, to execute an executable file\nbuilt by the build script.\n\nSo, we could simply add a run step in our build script to run these unit tests\nfrom a single command in the `zig` compiler, to make our lifes easier.\nIn the example below, we demonstrate the commands to\nregister a new build step called \"tests\" in our build script\nto run these unit tests.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst run_arti = b.addRunArtifact(test_exe);\nconst run_step = b.step(\"tests\", \"Run unit tests\");\nrun_step.dependOn(&run_arti.step);\n```\n:::\n\n\nNow that we registered this new build step, we can trigger it by calling the command below\nin the terminal. You can also checkout the complete source\ncode for this specific build script at the `build_tests.zig` module at the\n[official repository of this book](https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig)\n[^module-src2].\n\n\n[^module-src2]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/build_system/build_tests.zig>\n\n\n```bash\nzig build tests\n```\n\n\n## Tailoring your build process with user-provided options\n\nSometimes, you want to make a build script that is customizable by the user\nof your project. You can do that by creating user-provided options in\nyour build script. We create an user-provided option by using the\n`option()` method from the `Build` struct.\n\nWith this method, we create a \"build option\" which can be passed\nto the `build.zig` script at the command line. The user have the power of setting\nthis option at the `build` command from the\n`zig` compiler. In other words, each build option that we create\nbecomes a new command line argument that is accessible through the `build` command\nof the compiler.\n\nThese \"user-provided options\" are set by using the prefix `-D` in the command line.\nFor example, if we declare an option named `use_zlib`, that receives a boolean value which\nindicates if we should link our source code to `zlib` or not, we can set the value\nof this option in the command line with `-Duse_zlib`. The code example below\ndemonstrates this idea:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const use_zlib = b.option(\n        bool,\n        \"use_zlib\",\n        \"Should link to zlib?\"\n    ) orelse false;\n    const exe = b.addExecutable(.{\n        .name = \"hello\",\n        .root_source_file = b.path(\"example.zig\"),\n        .target = b.host,\n    });\n    if (use_zlib) {\n        exe.linkSystemLibrary(\"zlib\");\n    }\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n```bash\nzig build -Duse_zlib=false\n```\n\n\n## Linking to external libraries\n\n\nOne essential part of every build process is the linking stage.\nThis stage is responsible for combining the multiple object files\nthat represent your code, into a single executable file. It also links\nthis executable file to external libraries, if you use any in your code.\n\nIn Zig, we have two notions of a \"library\", which are: 1) a system's library;\n2) a local library. A system's library is just a library that is already installed\nin your system. While a local library is a library that belongs to the current\nproject; a library that is present in your project directory, and\nthat you are building together with your project source code.\n\nThe basic difference between the two, is that a system's library is already\nbuilt and installed in your system, supposedly, and all you need to do\nis to link your source code to this library to start using it.\nWe do that by using the `linkSystemLibrary()` method from a\n`Compile` object. This method accepts the name of the library\nin a string as input. Remember from @sec-targets that a `Compile` object\nis a target object that you declare in your build script.\n\nWhen you link a particular target object with a system's library,\nthe `zig` compiler will use `pkg-config` to find where\nare the binary files and also the header files of this library\nin your system.\nWhen it finds these files, the linker present in the `zig` compiler\nwill link your object files with the files of this library to\nproduce a single binary file for you.\n\nIn the example below, we are creating an executable file named `image_filter`,\nand, we are linking this executable file to the C Standard Library with the\nmethod `linkLibC()`, but we also are linking this executable file to the\nC library `libpng` that is currently installed in my system.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const exe = b.addExecutable(.{\n        .name = \"image_filter\",\n        .root_source_file = b.path(\"src/main.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n    exe.linkLibC();\n    exe.linkSystemLibrary(\"png\");\n    b.installArtifact(exe);\n}\n```\n:::\n\n\nIf you are linking with a C library in your project, is generally a good idea\nto also link your code with the C Standard Library. Because is very likely\nthat this C library uses some functionality of the C Standard Library at some point.\nThe same goes to C++ libraries. So, if you are linking with\nC++ libraries, is a good idea to link your project with the C++\nStandard Library by using the `linkLibCpp()` method.\n\nOn the order side, when you want to link with a local library,\nyou should use the `linkLibrary()` method of a `Compile` object.\nThis method expects to receive another `Compile` object as input.\nThat is, another target object defined in your build script,\nusing either the `addStaticLibrary()` or `addSharedLibrary()` methods\nwhich defines a library to be built.\n\nAs we discussed earlier, a local library is a library\nthat is local to your project, and that is being built together\nwith your project. So, you need to create a target object in your build script\nto build this local library. Then, you link the target objects of interest in your project,\nwith this target object that identifies this local library.\n\nTake a look at this example extracted from the build script of the [`libxev` library](https://github.com/mitchellh/libxev/tree/main)[^libxev2].\nYou can see in this snippet that\nwe are declaring a shared library file, from the `c_api.zig`\nmodule. Then, later in the build script, we declare an\nexecutable file named `\"dynamic-binding-test\"`, which\nlinks to this shared library that we defined earlier\nin the script.\n\n[^libxev2]: <https://github.com/mitchellh/libxev/tree/main>\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst optimize = b.standardOptimizeOption(.{});\nconst target = b.standardTargetOptions(.{});\n\nconst dynamic_lib = b.addSharedLibrary(.{\n    .name = dynamic_lib_name,\n    .root_source_file = b.path(\"src/c_api.zig\"),\n    .target = target,\n    .optimize = optimize,\n});\nb.installArtifact(dynamic_lib);\n// ... more lines in the script\nconst dynamic_binding_test = b.addExecutable(.{\n    .name = \"dynamic-binding-test\",\n    .target = target,\n    .optimize = optimize,\n});\ndynamic_binding_test.linkLibrary(dynamic_lib);\n```\n:::\n\n\n\n\n## Building C code {#sec-building-c-code}\n\nThe `zig` compiler comes with a C compiler embedded in it. In other words,\nyou can use the `zig` compiler to build C projects. This C compiler is available\nthrough the `cc` command of the `zig` compiler.\n\nAs an example, let's use the famous [FreeType library](https://freetype.org/)[^freetype].\nFreeType is one of the most widely used pieces of software in the world.\nIt's a C library designed to produce high-quality fonts. But it's also\nheavily used in the industry to natively render text and fonts\nin the screen of your computer.\n\nIn this section, we are going to write a build script, piece by piece, that is capable\nof building the FreeType project from source.\nYou can find the source code of this build script on the\n[`freetype-zig` repository](https://github.com/pedropark99/freetype-zig/tree/main)[^freetype-zig]\navailable at GitHub.\n\n[^freetype]: <https://freetype.org/>\n[^freetype-zig]: <https://github.com/pedropark99/freetype-zig/tree/main>\n\nAfter you download the source code of FreeType from the official website[^freetype],\nyou can start writing the `build.zig` module. We begin by defining the target object\nthat defines the binary file that we want to compile.\n\nAs an example, I will build the project as a static library file using the `addStaticLibrary()` method\nto create the target object.\nAlso, since FreeType is a C library, I will also link the library\nagainst `libc` through the `linkLibC()` method, to guarantee that any use\nof the C Standard Library is covered in the compilation process.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst target = b.standardTargetOptions(.{});\nconst opti = b.standardOptimizeOption(.{});\nconst lib = b.addStaticLibrary(.{\n    .name = \"freetype\",\n    .optimize = opti,\n    .target = target,\n});\nlib.linkLibC();\n```\n:::\n\n\n### Creating C compiler flags\n\nCompiler flags are also known as \"compiler options\" by many programmers,\nor also, as \"command options\" in the GCC official documentation.\nIt's fair to also call them as the \"command-line arguments\" of the C compiler.\nIn general, we use compiler flags to turn on (or turn off) some features from the compiler,\nor to tweak the compilation process to fit the needs of our project.\n\nIn build scripts written in Zig, we normally list the C compiler flags to be used in the compilation process\nin a simple array, like in the example below.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c_flags = [_][]const u8{\n    \"-Wall\",\n    \"-Wextra\",\n    \"-Werror\",\n};\n```\n:::\n\n\nIn theory, there is nothing stopping you from using this array to add \"include paths\" (with the `-I` flag)\nor \"library paths\" (with the `-L` flag) to the compilation process. But there are formal ways in Zig to\nadd these types of paths in the compilation process. Both are discussed in @sec-include-paths\nand @sec-library-paths.\n\nAnyway, in Zig, we add C flags to the build process together with the C files that we want to compile, by using the\n`addCSourceFile()` and `addCSourceFiles()` methods. In the example above, we have just declared\nthe C flags that we want to use. But we haven't added them to the build process yet.\nTo do that, we also need to list the C files to be compiled.\n\n### Listing your C files\n\nThe C files that contains \"cross-platform\" source code are listed in the `c_source_files`\nobject below. These are the C files that are included by default in every platform\nsupported by the FreeType library. Now, since the amount of C files in the FreeType library is big,\nI have omitted the rest of the files in the code example below, for brevity purposes.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c_source_files = [_][]const u8{\n    \"src/autofit/autofit.c\",\n    \"src/base/ftbase.c\",\n    // ... and many other C files.\n};\n```\n:::\n\n\nNow, in addition to \"cross-platform\" source code, we also have some C files in the FreeType project\nthat are platform-specific, meaning that, they contain source code that can only be compiled in specific platforms,\nand, as a result, they are only included in the build process on these specific target platforms.\nThe objects that list these C files are exposed in the code example below.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst windows_c_source_files = [_][]const u8{\n    \"builds/windows/ftdebug.c\",\n    \"builds/windows/ftsystem.c\"\n};\nconst linux_c_source_files = [_][]const u8{\n    \"src/base/ftsystem.c\",\n    \"src/base/ftdebug.c\"\n};\n```\n:::\n\n\nNow that we declared both the files that we want to include and the C compiler flags to be used,\nwe can add them to the target object that describes the FreeType library, by using the\n`addCSourceFile()` and `addCSourceFiles()` methods.\n\nBoth of these functions are methods from a `Compile` object (i.e., a target object).\nThe `addCSourceFile()` method is capable of adding a single C file to the target object,\nwhile the `addCSourceFiles()` method is used to add multiple C files in a single command.\nYou might prefer to use `addCSourceFile()` when you need to use different compiler flags\non specific C files in your project. But, if you can use the same compiler flags\nacross all C files, then, you will probably find `addCSourceFiles()` a better choice.\n\nNotice that we are using the `addCSourceFiles()` method in the example below,\nto add both the C files and the C compiler flags. Also notice that we\nare using the `os.tag` that we learned about in @sec-detect-os, to add the platform-specific\nC files.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst builtin = @import(\"builtin\");\nlib.addCSourceFiles(\n    &c_source_files, &c_flags\n);\n\nswitch (builtin.target.os.tag) {\n    .windows => {\n        lib.addCSourceFiles(\n            &windows_c_source_files,\n            &c_flags\n        );\n    },\n    .linux => {\n        lib.addCSourceFiles(\n            &linux_c_source_files,\n            &c_flags\n        );\n    },\n    else => {},\n}\n```\n:::\n\n\n\n### Defining C Macros\n\nC Macros are an essential part of the C programming language,\nand they are commonly defined through the `-D` flag from a C compiler.\nIn Zig, you can define a C Macro to be used in your build process\nby using the `defineCMacro()` method from the target object that\ndefines the binary file that you are building.\n\nIn the example below, we are using the `lib` object that we have defined\nin the previous sections to define some C Macros used by the FreeType project\nin the compilation process. These C Macros specify if FreeType\nshould (or should not) include functionalities from different\nexternal libraries.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nlib.defineCMacro(\"FT_DISABLE_ZLIB\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_PNG\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_HARFBUZZ\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BZIP2\", \"TRUE\");\nlib.defineCMacro(\"FT_DISABLE_BROTLI\", \"TRUE\");\nlib.defineCMacro(\"FT2_BUILD_LIBRARY\", \"TRUE\");\n```\n:::\n\n\n\n### Adding library paths {#sec-library-paths}\n\nLibrary paths are paths in your computer where the C compiler will look (or search) for\nlibrary files to link against your source code. In other words, when you use a library in your\nC source code, and you ask the C compiler to link your source code against this library,\nthe C compiler will search for the binary files of this library across the paths listed\nin this \"library paths\" set.\n\nThese paths are platform specific, and, by default, the C compiler starts by looking at a\npre-defined set of places in your computer. But you can add more paths (or more places)\nto this list. For example, you may have a library installed in a non-conventional place of your\ncomputer, and you can make the C compiler \"see\" this \"non-conventional place\" by adding this path\nto this list of pre-defined paths.\n\nIn Zig, you can add more paths to this set by using the `addLibraryPath()` method from your target object.\nFirst, you defined a `LazyPath` object, containing the path you want to add, then,\nyou provide this object as input to the `addLibraryPath()` method, like in the example below:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst lib_path: std.Build.LazyPath = .{\n    .cwd_relative = \"/usr/local/lib/\"\n};\nlib.addLibraryPath(lib_path);\n```\n:::\n\n\n\n\n\n### Adding include paths {#sec-include-paths}\n\nThe preprocessor search path is a popular concept from the\nC community, but it's also known by many C programmers as \"include paths\", because\nthe paths in this \"search path\" relate to the `#include` statements found in the C files.\n\nInclude paths are similar to library paths. They are a set of pre-defined places in your computer where\nthe C compiler will look for files during the compilation process. But instead of looking for\nlibrary files, the include paths are places where the compiler looks for header files included\nin your C source code.\nThis is why many C programmers prefer to call these paths as the \"preprocessor search path\".\nBecause header files are processed during the preprocessor stage of the compilation\nprocess.\n\nSo, every header file that you include in your C source code, through a `#include` statements needs to\nbe found somewhere, and the C compiler will search for this header file across the paths listed in this \"include paths\" set.\nInclude paths are added to the compilation process through the `-I` flag.\n\nIn Zig, you can add new paths to this pre-defined set of paths, by using the `addIncludePath()` method\nfrom your target object. This method also accepts a `LazyPath` object as input.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst inc_path: std.Build.LazyPath = .{\n    .path = \"./include\"\n};\nlib.addIncludePath(inc_path);\n```\n:::\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/09-data-structures/execute-results/epub.json b/_freeze/Chapters/09-data-structures/execute-results/epub.json
deleted file mode 100644
index 9a281348..00000000
--- a/_freeze/Chapters/09-data-structures/execute-results/epub.json
+++ /dev/null
@@ -1,21 +0,0 @@
-{
-  "hash": "0d90c199a3a2c5a7a25c66baac2ca8aa",
-  "result": {
-    "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Data Structures\n\nIn this chapter, I want to present the most common Data Structures that are available from\nthe Zig Standard Library, especially `ArrayList` and also `HashMap`. These are generic Data Structures\nthat you can use to store and control any type of data that is produced by your application.\n\n## Dynamic Arrays {#sec-dynamic-array}\n\nIn high level languages, arrays are usually dynamic. They can easily grow\nin size when they have to, and you don't need to worry about it.\nIn contrast, arrays in low level languages are usually static by default.\nThis is the reality of C, C++, Rust and also Zig. Static arrays were presented at\n@sec-arrays, but in this section, we are going to talk about dynamic arrays in Zig.\n\nDynamic arrays are simply arrays that can grow in size during the runtime\nof your program. Most low level languages have some implementation of\na dynamic array in their standard library. C++ have `std::vector`, Rust have `Vec`,\nand Zig have `std.ArrayList`.\n\nThe `std.ArrayList` struct provides a contiguous and growable array for you.\nIt works like any other dynamic array, it allocates a contiguous block of memory, and when this block have no space left,\n`ArrayList` allocates another contiguous and bigger block of memory, copies the\nelements to this new location, and erases (or frees) the previous block of memory.\n\n\n### Capacity vs Length\n\nWhen we talk about dynamic arrays, we usually have two similar concepts that\nare very essential to how a dynamic array works behind the hood.\nThese concepts are *capacity* and *length*. In some contexts, especially\nin C++, *length* is also called of *size*.\n\nAlthough they look similar, these concepts represent different things\nin the context of a dynamic array. *Capacity* is the number of items (or elements)\nthat your dynamic array can currently hold without the need to allocate more memory.\n\nIn contrast, the *length* refers to how many elements in the array\nare currently being used, or, in other words, how many elements in this array\nthat you have assigned a value to. Every dynamic array works around\na block of allocated memory, which represents an array with total capacity for $n$ elements.\nHowever, only a portion of these $n$ elements are being used most of the time. This portion\nof $n$ is the *length* of the array. So every time you append a new value\nto the array, you are incrementing its *length* by one.\n\nThis means that a dynamic array usually works with an extra margin, or an extra space\nthat is currently empty, but waiting and ready to be used. This \"extra space\"\nis essentially the difference between *capacity* and *length*. *Capacity* represents\nthe total number of elements that the array can hold without the need to re-allocate\nor re-expand the array, while the *length* represents how much of this capacity\nis currently being used to hold/store values.\n\n@fig-capacity-length presents this idea visually. Notice that, at first,\nthe capacity of the array is greater than the length of the array.\nSo, the dynamic array have extra space that is currently empty, but it\nis ready to receive a value to be stored.\n\n![Difference between capacity and length in a dynamic array](./../Figures/dynamic-array.png){#fig-capacity-length}\n\nWe can also see in @fig-capacity-length that, when *length* and *capacity* are equal, it means that the array have no space left.\nWe have reached the ceiling of our capacity, and because of that, if we want to store more values\nin this array, we need to expand it. We need to get a bigger space that can hold more values\nthan what we currently have.\n\nA dynamic array works by expanding the underlying array, whenever the *length* becomes equal\nto the *capacity* of the array. It basically allocates a new contiguous block of memory that is bigger\nthan the previous one, then, it copies all values that are currently being stored to this new\nlocation (i.e., this new block of memory), then, it frees the previous block of\nmemory. At the end of this process, the new underlying array have a bigger *capacity*, and, therefore,\nthe *length* becomes, once again, smaller than the *capacity* of the array.\n\nThis is the cycle of a dynamic array. Notice that, throughout this cycle, the *capacity* is always\neither equal to or higher than the *length* of the array. If you have an `ArrayList` object (let's suppose\nyou named it `buffer`), you can check the current capacity of your array by accessing the `capacity`\nattribute of your `ArrayList` object, while the current *length* of it is available at the `items.len`\nattribute.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// Check capacity\nbuffer.capacity;\n// Check length\nbuffer.items.len;\n```\n:::\n\n\n\n\n### Creating an `ArrayList` object\n\nIn order to use `ArrayList`, you must provide an allocator object to it.\nRemember, Zig does not have a default memory allocator. And as I described in @sec-allocators, all memory\nallocations must be done by an allocator object that you define, that\nyou have control over. In our example here, I'm going to use\na general purpose allocator, but you can use any other allocator\nof your preference.\n\nWhen you initialize an `ArrayList` object, you must provide the data type of the elements of\nthe array. In other words, this defines the type of data that this array (or container) will\nstore. Therefore, if I provide the `u8` type to it, then, I will create a dynamic\narray of `u8` values. However, if I provide a struct that I have defined instead, like the struct `User`\nfrom @sec-structs-and-oop, then, a dynamic array of `User` values\nwill be created. In the example below, with the expression `ArrayList(u8)` we\nare creating a dynamic array of `u8` values.\n\nAfter you provide the data type of the elements of the array, you can initialize\nan `ArrayList` object by either using the `init()` or the `initCapacity()` methods.\nThe former method receives only the allocator object\nas input, while the latter method receives both the allocator object and a capacity number as inputs.\nWith the latter method, you not only initialize the struct, but you\nalso set the starting capacity of the allocated array.\n\nUsing the `initCapacity()` method is the preferred way to initialize your dynamic array.\nBecause reallocations, or, in other words, the process of expanding the capacity of the array,\nis always a high cost operation. You should take any possible opportunity to avoid reallocations in\nyour array. If you know how much space your array needs to occupy at the beginning,\nyou should always use `initCapacity()` to create your dynamic array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n```\n:::\n\n\n\n\nIn the example above, the `buffer` object starts as an array of 100 elements. If this\n`buffer` object needs to create more space to accomodate more elements during the runtime of your program, the `ArrayList`\ninternals will perform the necessary actions for you automatically.\nAlso notice the `deinit()` method being used to destroy the `buffer` object at the\nend of the current scope, by freeing all the memory that was allocated for the dynamic\narray stored in this `buffer` object.\n\n\n### Adding new elements to the array\n\nNow that we have created our dynamic array, we can start to use it. You can append (a.k.a \"add\")\nnew values to this array by using the `append()` method. This method works the same way\nas the `append()` method from a Python list, or, the `emplace_back()` method from `std::vector` of C++.\nYou provide a single value to this method, and the method appends this value to the array.\n\nYou can also use the `appendSlice()` method to append multiple values at once. You provide\na slice (slices were described in @sec-arrays) to this method, and the method adds all values present\nin this slice to your dynamic array.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry buffer.append('H');\ntry buffer.append('e');\ntry buffer.append('l');\ntry buffer.append('l');\ntry buffer.append('o');\ntry buffer.appendSlice(\" World!\");\n```\n:::\n\n\n\n### Removing elements from the array {#sec-dynamic-array-remove}\n\nYou can use the `pop()` method to \"pop\" or remove\nthe last element in the array. It's worth noting that this method\ndo not change the capacity of the array. It just deletes or erases\nthe last value stored in the array.\n\nAlso, this method returns as result the value that got deleted. That is, you can\nuse this method to both get the last value in the array, and also, remove\nit from the array. It's a \"get and remove value\" type of method.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst exclamation_mark = buffer.pop();\n```\n:::\n\n\n\nNow, if you want to remove specific elements from specific positions\nof your array, you can use the `orderedRemove()` method from your\n`ArrayList` object. With this method, you can provide an index as input,\nthen, the method will delete the value that is at this index in the array.\nYou are effectively reducing the *length* of the array everytime you execute\nan `orderedRemove()` operation.\n\nIn the example below, we first create an `ArrayList` object, and we fill it\nwith numbers. Then, we use `orderedRemove()` to remove the value at\nindex 3 in the array, two consecutive times.\n\nAlso, notice that we are assigning the result of `orderedRemove()` to the\nunderscore character. So we are discarding the result value of this method.\nThe `orderedRemove()` method returns the value that got deleted, in a similar\nstyle to the `pop()` method.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 100);\ndefer buffer.deinit();\n\nfor (0..10) |i| {\n    const index: u8 = @intCast(i);\n    try buffer.append(index);\n}\n\nstd.debug.print(\n    \"{any}\\n\", .{buffer.items}\n);\n_ = buffer.orderedRemove(3);\n_ = buffer.orderedRemove(3);\n\nstd.debug.print(\"{any}\\n\", .{buffer.items});\nstd.debug.print(\"{any}\\n\", .{buffer.items.len});\n```\n:::\n\n\n\n```\n{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }\n{ 0, 1, 2, 5, 6, 7, 8, 9 }\n8\n```\n\nOne key characteristic about `orderedRemove()` is that it preserves the order\nof the values in the array. So, it deletes the value that you asked it to\nremove, but it also makes sure that the order of the values that remain in the array\nstay the same as before.\n\nNow, if you don't care about the order of the values, for example, maybe you want to treat\nyour dynamic array as a set of values, like the `std::unordered_set`\nstructure from C++, you can use the `swapRemove()` method instead. This method\nworks similarly to the `orderedRemove()` method. You give an index to this\nmethod, then, it deletes the value that is at this index in the array.\nBut this method does not preserve the original order of the values that remain\nin the array. As a result, `swapRemove()` is, in general, faster than `orderedRemove()`.\n\n\n### Inserting elements at specific indexes\n\nWhen you need to insert values in the middle of your array,\ninstead of just appending them to the end of the array, you need to use\nthe `insert()` and `insertSlice()` methods, instead of\nthe `append()` and `appendSlice()` methods.\n\nThese two methods work very similarly to `insert()` and `insert_range()`\nfrom the C++ `std::vector` class. You provide an index to these methods,\nand they insert the values that you provide at that index in the array.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nvar buffer = try std.ArrayList(u8)\n    .initCapacity(allocator, 10);\ndefer buffer.deinit();\n\ntry buffer.appendSlice(\"My Pedro\");\ntry buffer.insert(4, '3');\ntry buffer.insertSlice(2, \" name\");\nfor (buffer.items) |char| {\n    try stdout.print(\"{c}\", .{char});\n}\n```\n:::\n\n\n\n```\nMy name P3edro\n```\n\n\n### Conclusion\n\nIf you feel the lack of some other method, I recommend\nyou to read the [official documentation for the `ArrayListAligned`](https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned)[^zig-array2]\nstruct, which describes most of the methods available\nthrough the `ArrayList` object.\n\nYou will notice that there is a lot of other methods in this page that\nI did not described here, and I recommend you to explore these methods,\nand understand how they work.\n\n[^zig-array2]: <https://ziglang.org/documentation/master/std/#std.array_list.ArrayListAligned>\n\n\n\n## Maps or HashTables {#sec-maps-hashtables}\n\nSome professionals know this type of data structure by different terms, like \"map\",\n\"hashmap\" or \"associative arrays\". But the most common term used is *hashtable*.\nEvery programming language normally have some implementation of a hashtable in their\nstandard libraries. Python have `dict()`, C++ have `std::map` and `std::unordered_map`, Rust\nhave `HashMap`, Javascript have `Object()` and `Map()`, etc.\n\n\n\n### What is a hashtable?\n\nA hashtable is a data structure based on key-value pairs.\nYou provide a key and a value to this structure, then, the hashtable will store\nthe input value at a location that can be identified by the input\nkey that you provided.\nIt does that by using an underlying array and a hash function.\nThese two components are essential to how a hashtable works.\n\nUnder the hood, the hashtable contains an array. This array is where the values\nare stored, and the elements of this array are usually called of *buckets*.\nSo the values that you provide to the hashtable are stored inside buckets,\nand you access each bucket by using an index.\n\nWhen you provide a key to a hashtable, it passes this key to the\nhash function. This hash function uses some sort of hashing algorithm to transform\nthis key into an index. This index is actually an array index. It's a position\nin the underlying array of the hashtable.\nThis is how a key identifies a specific position (or location) inside the hashtable\nstructure.\n\nTherefore, you provide a key to the hashtable, and this key identifies a specific location\ninside the hashtable, then, the hashtable takes the input value that you provided,\nand stores this value in the location identified by this input key.\nYou could say that the key maps to the value stored in the hashtable. You find\nthe value, by using the key that identifies the location where the value is stored.\nThe @fig-hashtable presents this process visually.\n\n\n![A diagram of a Hashtable. Source: Wikipedia, the free encyclopedia.](./../Figures/hashtable.svg){#fig-hashtable}\n\n\nThe operation described in the previous paragraph is normally called an *insertion* operation.\nBecause you are inserting new values into the hashtable.\nBut there are other types of operations in hashtables such as *delete* and *lookup*.\nDelete is self describing, it's when you delete (or remove) a value from the hashtable.\nWhile lookup corresponds to when you look at a value that is stored in\nthe hashtable, by using the key that identifies the location where this value is stored.\n\nSometimes, instead of storing the values directly, the underlying array of the hashtable might be an array of pointers,\ni.e., the buckets of the array stores pointers that points to the value,\nor also, may be an array of linked lists.\nThese cases are common on hashtables that allows duplicate keys, or, in other words,\non hashtables that effectively handle \"collisions\" that may arise from the hash function.\n\nDuplicate keys, or this \"collision\" thing that I'm talking about, is when you have two different keys\nthat points to the same location (i.e., to the same index)\nin the underlying array of the hashtable. This might happen depending on the characteristics of the hash function\nthat is being used in the hashtable. Some implementations of the hashtable will actively deal with collisions,\nmeaning that, they will handle this case in some way. For example, the hashtable\nmight transform all buckets into linked lists. Because with a linked list you can store\nmultiple values into a single bucket.\n\nThere are different techniques to handle collisions in hashtables, which I will not describe\nin this book, because it's not our main scope here. But you can find a good description of\nsome of the most common techniques at the Wikipedia page of hashtables [@wikipedia_hashtables].\n\n\n### Hashtables in Zig {#sec-hashmap}\n\nThe Zig Standard Library provides different implementations of a hashtable.\nEach implementation have its own cons and pros, which we will\ndiscuss later on, and all of them are available through the `std.hash_map` module.\n\nThe `HashMap` struct is a general-purpose hashtable,\nwhich have very fast operations (lookup, insertion, delete), and also,\nquite high load factors for low memory usage. You can create and provide a context object\nto the `HashMap` constructor. This context object allows you to tailor\nthe behaviour of the hashtable itself, because you can\nprovide a hash function implementation to be used by the hashtable\nthrough this context object.\n\nBut let's not worry about this context object now, because it's meant to be used\nby \"experts in the field of hashtables\". Since we are most likely not\nexperts in this field, we are going to take the easy way to create\na hashtable. Which is by using the `AutoHashMap()` function.\n\n\nThis `AutoHashMap()` function is essentially a \"create a hashtable object that uses the default settings\"\ntype of function. It automatically chooses a context object, and, therefore, a hash function implementation,\nfor you. This function receives two data types as input, the first input is the data type of the keys\nthat will be used in this hashtable, while the second input is the data type of the data that will be\nstored inside the hashtable, that is, the data type of the values to be stored.\n\nIn the example below, we are providing the data type `u32` in the first argument, and `u16` in the second argument of this\nfunction. This means that we are going to use `u32` values as keys in this hashtable, while `u16` values are the actual values\nthat are going to be stored into this hashtable.\nAt the end of this process, the `hash_table` object contains a `HashMap` object\nthat uses the default settings and context.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n    std.debug.print(\n        \"Value at key 50050: {d}\\n\",\n        .{hash_table.get(50050).?}\n    );\n\n    if (hash_table.remove(57709)) {\n        std.debug.print(\n            \"Value at key 57709 successfully removed!\\n\",\n            .{}\n        );\n    }\n    std.debug.print(\n        \"N of values stored: {d}\\n\",\n        .{hash_table.count()}\n    );\n}\n```\n:::\n\n\n\n```\nN of values stored: 3\nValue at key 50050: 55\nValue at key 57709 successfully removed!\nN of values stored: 2\n```\n\nYou can add/put new values into the hashtable by using the `put()` method. The first argument\nis the key to be used, and the second argument is the actual value that you want to store inside\nthe hashtable. In the example below, we first add the value 89 using the key 54321, next, we add\nthe value 55 using the key 50050, etc.\n\nNotice that we have used the method `count()` to see how many values are currently stored in the\nhashtable. After that, we also use the `get()` method to access (or look) at the value stored in\nthe position identified by the key 500050. The output of this `get()` method is an optional value.\nThis is why we use the `?` method at the end to get the actual value.\n\nAlso notice that we can remove (or delete) values from the hashtable by using the `remove()` method.\nYou provide the key that identifies the value that you want to delete, then, the method will\ndelete this value and return a `true` value as output. This `true` value essentially tells us\nthat the method successfully deleted the value.\n\nBut this delete operation might not be always successful. For example, you might provide the wrong\nkey to this method. I mean, maybe you provide\n(either intentionally or unintentionally) a key that points to an empty bucket,\ni.e., a bucket that still doesn't have a value in it.\nIn this case, the `remove()` method would return a `false` value.\n\n\n\n### Iterating through the hashtable\n\nIterating through the keys and values that are currently being stored in\nthe hashtable is a very common necessity.\nYou can do that in Zig by using an iterator object that can iterate\nthrough the elements of your hashtable object.\n\nThis iterator object works like any other iterator object that you would\nfind in languages such as C++ and Rust. It's basically a pointer object\nthat points to some value in the container, and has a `next()` method\nthat you can use to navigate (or iterate) through the values in the\ncontainer.\n\nYou can create such iterator object by using the `iterator()` method of the hashtable object.\nThis method returns an iterator object, from which you can use the `next()` method in conjunction\nwith a while loop to iterate through the elements of your hashtable. The `next()` method returns an optional\n`Entry` value, and therefore, you must unwrap this optional value to get the actual `Entry` value\nfrom which you can access the key and also the value identified by this key.\n\nWith this `Entry` value at hand, you can access the key of this current entry by using the `key_ptr`\nattribute and dereferencing the pointer that lives inside of it, while the value identified by this\nkey is accessed through the `value_ptr` attribute instead, which is also a pointer to be dereferenced.\nThe code example below demonstrates the use of these elements:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst AutoHashMap = std.hash_map.AutoHashMap;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var hash_table = AutoHashMap(u32, u16).init(allocator);\n    defer hash_table.deinit();\n\n    try hash_table.put(54321, 89);\n    try hash_table.put(50050, 55);\n    try hash_table.put(57709, 41);\n\n    var it = hash_table.iterator();\n    while (it.next()) |kv| {\n        // Access the current key\n        std.debug.print(\"Key: {d} | \", .{kv.key_ptr.*});\n        // Access the current value\n        std.debug.print(\"Value: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n:::\n\n\n\n```\nKey: 54321 | Value: 89\nKey: 50050 | Value: 55\nKey: 57709 | Value: 41\n```\n\n\nIf you want to iterate specifically through the values or the keys of your hashtable,\nyou can create a key iterator or a value iterator object. These are also iterator\nobjects, which have the same `next()` method that you can use to iterate through the\nhashtable.\n\nKey iterators are created from the `keyIterator()` method of your\nhashtable object, while value iterators are created from the `valueIterator()` method.\nAll you have to do is to unwrap the value from the `next()` method and deference it\ndirectly to access the key or the value that you are iterating over.\nThe code example below demonstrates the use of a key iterator,\nbut you can replicate the same logic to a value iterator.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar kit = hash_table.keyIterator();\nwhile (kit.next()) |key| {\n    std.debug.print(\"Key: {d}\\n\", .{key.*});\n}\n```\n:::\n\n\n\n```\nKey: 54321\nKey: 50050\nKey: 57709\n```\n\n\n### The `ArrayHashMap` hashtable {#sec-array-map}\n\nIf you need to iterate through the elements of your hashtable constantly,\nyou might want to use the `ArrayHashMap` struct for your specific case,\ninstead of going with the usual and general-purpose `HashMap` struct.\n\nThe `ArrayHashMap` struct creates a hashtable that is faster to iterate over.\nThat is why this specific type of hashtable might be valuable to you.\nSome other properties of a `ArrayHashMap` hashtable are:\n\n- the order of insertion is preserved, i.e., the order of the values that you find while iterating through this hashtable is actually the order in which these values were inserted in the hashtable.\n- the key-value pairs are stored sequentially, one after another.\n\n\nYou can create an `ArrayHashMap` object by using, once again, a helper function that\nchooses automatically for you a hash function implementation. This is the\n`AutoArrayHashMap()` function, which works very similarly to the `AutoHashMap()`\nfunction that we presented in @sec-hashmap.\n\nYou provide two data types to this function. The data type of the keys that will be\nused in this hashtable, and the data type of the values that will be stored in\nthis hashtable.\n\nAn `ArrayHashMap` object have essentially the exact same methods from the `HashMap` struct.\nSo you can insert new values into the hashtable by using the `put()` method, and you can look (or get)\na value from the hashtable by using the `get()` method. But the `remove()` method is not available\nin this specific type of hashtable.\n\nIn order to delete values from the hashtable, you would use the same methods that you find in\nan `ArrayList` object, i.e., a dynamic array. I presented these methods in @sec-dynamic-array-remove,\nwhich are the `swapRemove()` and `orderedRemove()` methods. These methods have the same meaning here, or,\nthe same effect that they have in an `ArrayList` object.\n\nThis means that, with `swapRemove()` you remove the value from the hashtable, but you do not preserve\nthe order in which the values were inserted into the structure. While `orderedRemove()` is able\nto retain the order in which these values were inserted.\n\nBut instead of providing an index as input to `swapRemove()` or `orderedRemove()`, like I described\nin @sec-dynamic-array-remove, these methods here in an `ArrayHashMap` take a key as input, like\nthe `remove()` method from a `HashMap` object. If you want to provide an index as input, instead\nof a key, you should use the `swapRemoveAt()` and `orderedRemoveAt()` methods.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar hash_table = AutoArrayHashMap(u32, u16)\n    .init(allocator);\ndefer hash_table.deinit();\n```\n:::\n\n\n\n\n\n### The `StringHashMap` hashtable {#sec-string-hash-map}\n\nOne thing that you will notice in the other two types of hashtables that I have\npresented over the last sections, is that neither of them accepts a slice data type\nin their keys.\nWhat this means is that you cannot use a slice value to represent a key in\nthese types of hashtable.\n\nThe most obvious consequence of this, is that you cannot use strings as keys\nin these hashtables. But it's extremely common to use strings as keys\nin hashtables.\n\nTake this very simple Javascript code snippet as an example. We are creating\na simple hashtable object named `people`. Then, we add a new entry to this\nhashtable, which is identified by the string `'Pedro'`. This string is the\nkey in this case, while the object containing different personal information such as\nage, height and city, is the value to be stored in the hashtable.\n\n```js\nvar people = new Object();\npeople['Pedro'] = {\n    'age': 25,\n    'height': 1.67,\n    'city': 'Belo Horizonte'\n};\n```\n\nThis pattern of using strings as keys is very common in\nall sorts of situations. That is why the Zig Standard Library offers a\nspecific type of hashtable for this purpose, which is created through the `StringHashMap()` function.\nThis function creates a hashtable that uses strings as keys. The only input of this\nfunction is the data type of the values that will be stored into this hashtable.\n\nIn the example below, I'm creating a hashtable to store the ages of different people.\nEach key in this hashtable is represented by the name of each person, while the value stored in the\nhashtable is the age of this person identified by the key.\n\nThat is why I provide the `u8` data type (which is the data type used by the age values) as input to this `StringHashMap()` function.\nAs the result, it creates a hashtable that uses string values as keys, and, that stores\n`u8` values in it. Notice that an allocator object is provided at the `init()` method of the\nresulting object from the `StringHashMap()` function.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var ages = std.StringHashMap(u8).init(allocator);\n    defer ages.deinit();\n\n    try ages.put(\"Pedro\", 25);\n    try ages.put(\"Matheus\", 21);\n    try ages.put(\"Abgail\", 42);\n\n    var it = ages.iterator();\n    while (it.next()) |kv| {\n        std.debug.print(\"Key: {s} | \", .{kv.key_ptr.*});\n        std.debug.print(\"Age: {d}\\n\", .{kv.value_ptr.*});\n    }\n}\n```\n:::\n\n\n\n```\nKey: Pedro | Age: 25\nKey: Abgail | Age: 42\nKey: Matheus | Age: 21\n```\n\n\n### The `StringArrayHashMap` hashtable\n\nThe Zig Standard Library also provides a type of hashtable that mix the cons and pros of the\n`StringHashMap` and `ArrayHashMap` together. That is, a hashtable\nthat uses strings as keys, but also have the advantages from `ArrayHashMap`.\nIn other words, you can have a hashtable that is fast to iterate over,\nthat preserves insertion order, and also, that uses strings as keys.\n\nYou can create such type of hashtable by using the `StringArrayHashMap()` function.\nThis function accepts a data type as input, which is the data type of the values that are\ngoing to be stored inside this hashtable, in the same style as the function presented\nin @sec-string-hash-map.\n\nYou can insert new values into this hashtable by using the same `put()` method that\nwe have discussed in @sec-string-hash-map. And you can also get values from the hashtable\nby using the same `get()` method.\nLike its `ArrayHashMap` brother, to delete values from this specific type of hashtable,\nwe also use the `orderedRemove()` and `swapRemove()` methods, with the same effects that\nI have described in @sec-array-map.\n\nIf we take the code example that was exposed in @sec-string-hash-map, we can\nachieve the exact same result with `StringArrayHashMap()`:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar ages = std.StringArrayHashMap(u8).init(allocator);\n```\n:::\n\n\n\n\n\n\n## Linked lists\n\nThe Zig Standard Library provides an implementation for both singly and doubly linked lists.\nMore specifically, through the structs `SinglyLinkedList` and `DoublyLinkedList`.\n\nIn case you are not familiar with these data structures, a linked list is a linear data structure that looks\nlike a chain, or, a rope. The main advantage of this data structure is that you normally have very fast\ninsertion and deletion operations. But, as a disadvantage, iterating through\nthis data structure is usually not so fast as iterating through an array.\n\nThe idea behind a linked list is to build a structure that consists of a sequence of nodes\nconnected to each other by pointers. This means that linked lists are usually not contiguous\nin memory, because each node might be anywhere in memory. They do not need to be close to\none another.\n\nIn @fig-linked-list we can see a diagram of a singly linked list. We begin at the first node\n(which is usually called \"the head of the linked list\"). Then, from this\nfirst node we uncover the remaining nodes in the structure, by following the locations pointed\nby the pointers found in each node.\n\nEach node has two things in it. It has the value that is stored in the current node\n, and also, a pointer. This pointer points to the next node in the list. If this pointer\nis null, then, it means that we have reached the end of our linked list.\n\n![A diagram of a singly linked list.](./../Figures/linked-list.png){#fig-linked-list}\n\n\nIn @fig-linked-list2 we can see a diagram of a doubly linked list. The only thing that really\nchanges now is that every node in the linked list has both a pointer to the previous node,\nand, a pointer to the next node. So every node in a doubly linked list has two pointers in it. These are\nusually called the `prev` (for \"previous\") and the `next` (for \"next\") pointers of the node.\n\nIn the singly linked list example, we had only one single pointer in each node, and this singular\npointer was always pointing to the next node in the sequence. This means that singly linked lists\nnormally have only the `next` pointer in them.\n\n![A diagram of a doubly linked list.](./../Figures/doubly-linked-list.png){#fig-linked-list2}\n\n\n\n### Recent change in the API\n\nOn previous versions of Zig, the `SinglyLinkedList` and `DoublyLinkedList` structs were initially implemented as \"generics data structures\".\nMeaning that, you would use a generic function to create a singly (or doubly) linked list that could store\nthe specific data type that you wanted to use. We will learn more about generics at @sec-generics, and also,\nhow we can create a \"generic data structure\" at @sec-generic-struct.\n\nHowever, on the latest versions of Zig, the structs `SinglyLinkedList` and `DoublyLinkedList` were altered to use a\n\"less generic API\". This specific change was introduced on April 3, 2025. Therefore, check if your Zig version is one released after this\ndate. Just have in mind that if you don't have a very recent version of the Zig compiler,\nyou might have problems while trying to compile the next examples exposed here.\n\n\n\n### How to use a singly linked list\n\nFor example, consider that you are creating a singly linked list that is going to store `u32` values.\nGiven this scenario, the first thing that we need to do, is to create a \"node type\" that is capable\nof storing a `u32` value. The `NodeU32` type exposed below demonstrates such \"node type\".\n\nNotice that the data type associated with the member named `data` is the most important part of this\ncustom \"node type\". It determines the data type that is going to be stored in each node.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst NodeU32 = struct {\n    data: u32,\n    node: std.SinglyLinkedList.Node = .{},\n};\n```\n:::\n\n\n\nAfter we created our custom \"node type\" that can store the specific data type that we\nwant, we can just create a new and empty singly linked list, which will store our nodes.\nTo do that, we just create a new object with the type `SinglyLinkedList`, like this:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar list: std.SinglyLinkedList = .{};\n```\n:::\n\n\n\nNow, we have our linked list... But how can we insert nodes in it? Well, first of all,\nwe need to create our nodes. So let's focus on that first. The snippet exposed below demonstrates\nhow we could use our `NodeU32` struct to create such nodes.\n\nNotice in this snippet that we are just setting the `data` member of the struct for now.\nWe don't need to connect these nodes together in this first instance. This is why we ignore\nthe `node` member at first. But we are going to connect these nodes in a future point of the code, which is\nwhy these objects are marked as \"variable objects\", so that we can alter them in the future.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n```\n:::\n\n\n\nNow that we have both the linked list and also the nodes created, we can start to connect them together.\nYou can use the `prepend()` method from the linked list object to insert the first node in the list, which\nis the \"head\" of the linked list. As the name suggests, this specific method prepends the input node to the linked list,\nor, in other words, it transforms the input node into the first node of the list.\n\nAfter we added the \"head node\" of the list, we can start to add the \"next nodes\" in the list by using the `insertAfter()` method\nfrom the `SinglyLinkedList.Node` type, which, in our case here, is accessible through the `node` member of our\n`NodeU32` type. Thus, we can start to create the connections between the nodes by calling this method from the node objects\nthat are present in the list. Like in this example below:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nlist.prepend(&two.node); // {2}\ntwo.node.insertAfter(&five.node); // {2, 5}\ntwo.node.insertAfter(&three.node); // {2, 3, 5}\n```\n:::\n\n\n\nYou can also call the `prepend()` method again to add new nodes to the beginning of the linked list, which\nmeans, effectively, changing the \"head node\" of the list, like this:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nlist.prepend(&one.node); // {1, 2, 3, 5}\n```\n:::\n\n\n\n\nThere are other methods available from the singly linked list object that you might be interested. You can find a\nsummary of them in the bullet points below:\n\n- `remove()` to remove a specific node from the linked list.\n- `len()` to count how many nodes there is in the linked list.\n- `popFirst()` to remove the first node (i.e., the \"head\") from the linked list.\n\nSo, that is how singly linked lists work in Zig in a nutshell. To sum up,\nthis is all the source code that was exposed in this section inside the single cell:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst NodeU32 = struct {\n    data: u32,\n    node: std.SinglyLinkedList.Node = .{},\n};\n\nvar list: std.SinglyLinkedList = .{};\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nlist.prepend(&two.node); // {2}\ntwo.node.insertAfter(&five.node); // {2, 5}\ntwo.node.insertAfter(&three.node); // {2, 3, 5}\nlist.prepend(&one.node); // {1, 2, 3, 5}\n\ntry stdout.print(\"Number of nodes: {}\", .{list.len()});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nNumber of nodes: 4\n```\n\n\n:::\n:::\n\n\n\n\n### How to use a doubly linked list\n\nIf you want to use a doubly linked list instead, you will face a similar workflow compared to the\nsingly linked list:\n\n1. You first create a \"custom node type\" that can store the specific data type that you want.\n2. Create an empty doubly linked list object.\n3. Create the nodes of linked list.\n4. Start to insert the nodes inside the list.\n\nIn your \"custom node type\", you should use the `DoublyLinkedList.Node` type to denote\nthe `node` member of the struct. The snippet below demonstrates that. Here we are creating,\nonce again, a node type that can store `u32` values. But this time, this struct is tailored\nto be used inside a `DoublyLinkedList` struct.\n\nAfter this step, the way that you create the new empty linked list, and the nodes that you want insert,\nis practically identical to the singly linked list case. But, this time,\nwe normally use the `append()` method from the linked list object to add new nodes to the list.\n\nThis `append()` method from the linked list object will always append the input node to the end of the\nlinked list. However, in case you want to add the new node into a different position of the list, then,\nyou should take a look at the `insertAfter()` and `insertBefore()` methods of the linked list object.\nThese methods allow you to insert the new node either after or before an existing node in the list.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst NodeU32 = struct {\n    data: u32,\n    node: std.DoublyLinkedList.Node = .{},\n};\n\nvar list: std.DoublyLinkedList = .{};\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nlist.append(&one.node); // {1}\nlist.append(&three.node); // {1, 3}\nlist.insertAfter(\n    &one.node,\n    &five.node\n); // {1, 5, 3}\nlist.append(&two.node); // {1, 5, 3, 2}\n\ntry stdout.print(\"Number of nodes: {}\", .{list.len()});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nNumber of nodes: 4\n```\n\n\n:::\n:::\n\n\n\nThese are other methods from the `DoublyLinkedList` object that might interest you:\n\n- `remove()`: to remove a specific node from the list.\n- `len()`: to count the number of nodes in the list.\n- `prepend()`: to add a node to the beginning of the list (i.e. set the head node of the list).\n- `pop()`: to remove the last node of the list.\n- `popFirst()`: to remove the first node of the list.\n- `concatByMoving()`: to concat two doubly linked lists together.\n\n\n### Iterating through the linked list\n\nIf you want to iterate over the elements of the linked list, all you need to do is to follow\nthe trail created by the \"pointer to next node\". We usually do that inside a while loop, that simply goes to the\nnext node over and over, until it finds a null pointer, which means that we hit the end of the list.\n\nThis next example demonstrates how such while loop would work. Notice that we are using the `@fieldParentPtr()`\nbuilt-in function to get access to a pointer that points to the parent instance of the `node` object. In other words,\nwe get access to a pointer to the `NodeU32` instance that contains the current node. This way, we can use this pointer\nto access the data that is currently stored in this node.\n\nAlso notice that in each iteration of the while loop, we are changing the value of the `it` variable to the next node\nin the list. The while loop is interrupted in the moment that this `it` variable becomes null, which will happen\nwhen the there is not \"next node\" in the list, which means that we have reached the end of the list.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst NodeU32 = struct {\n    data: u32,\n    node: std.SinglyLinkedList.Node = .{},\n};\n\nvar list: std.SinglyLinkedList = .{};\nvar one: NodeU32 = .{ .data = 1 };\nvar two: NodeU32 = .{ .data = 2 };\nvar three: NodeU32 = .{ .data = 3 };\nvar five: NodeU32 = .{ .data = 5 };\n\nlist.prepend(&two.node); // {2}\nlist.prepend(&five.node); // {5, 2}\nlist.prepend(&three.node); // {3, 5, 2}\nlist.prepend(&one.node); // {1, 3, 5, 2}\n\nvar it = list.first;\nwhile (it) |node| : (it = node.next) {\n    const l: *NodeU32 = @fieldParentPtr(\n        \"node\", node\n    );\n    try stdout.print(\n        \"Current value: {}\", .{l.data}\n    );\n}\n```\n:::\n\n\n\n```\nCurrent value: 1\nCurrent value: 3\nCurrent value: 5\nCurrent value: 2\n```\n\n\n\n\n## Multi array structure\n\nZig introduces a new data structure called `MultiArrayList()`. It's a different version of the dynamic array\nthat we have introduced in @sec-dynamic-array. The difference between this structure and the `ArrayList()`\nthat we know from @sec-dynamic-array, is that `MultiArrayList()` creates a separate dynamic array\nfor each field of the struct that you provide as input.\n\nConsider the following code example. We create a new custom struct called `Person`. This\nstruct contains three different data members, or, three different fields. As consequence,\nwhen we provide this `Person` data type as input to `MultiArrayList()`, this\ncreates a \"struct of three different arrays\" called `PersonArray`. In other words,\nthis `PersonArray` is a struct that contains three internal dynamic arrays in it.\nOne array for each field found in the `Person` struct definition.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Person = struct {\n    name: []const u8,\n    age: u8,\n    height: f32,\n};\nconst PersonArray = std.MultiArrayList(Person);\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    var people = PersonArray{};\n    defer people.deinit(allocator);\n\n    try people.append(allocator, .{\n        .name = \"Auguste\", .age = 15, .height = 1.54\n    });\n    try people.append(allocator, .{\n        .name = \"Elena\", .age = 26, .height = 1.65\n    });\n    try people.append(allocator, .{\n        .name = \"Michael\", .age = 64, .height = 1.87\n    });\n}\n```\n:::\n\n\n\nIn other words, instead of creating an array of \"persons\", the `MultiArrayList()` function\ncreates a \"struct of arrays\". Each data member of this struct is a different array that stores\nthe values of a specific field from the `Person` values that were added (or, appended) to this \"struct of arrays\".\nOne important detail is that each of these separate internal arrays stored inside `PersonArray`\nare dynamic arrays. This means that these arrays can grow in capacity automatically as needed, to accomodate\nmore values.\n\nThe @fig-multi-array exposed below presents a diagram that describes the `PersonArray` struct\nthat we have created in the previous code example. Notice that the values of the data members\npresent in each of the three `Person` values that we have appended into the `PersonArray` object\n, are scattered across three different internal arrays of the `PersonArray` object.\n\n![A diagram of the `PersonArray` struct.](./../Figures/multi-array.png){#fig-multi-array}\n\nYou can easily access each of these arrays separately, and iterate over the values of each array.\nFor that, you will need to call the `items()` method from the `PersonArray` object, and provide as input\nto this method, the name of the field that you want to iterate over.\nIf you want to iterate through the `.age` array for example, then, you need to call `items(.age)` from\nthe `PersonArray` object, like in the example below:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (people.items(.age)) |*age| {\n    try stdout.print(\"Age: {d}\\n\", .{age.*});\n}\n```\n:::\n\n\n\n```\nAge: 15\nAge: 26\nAge: 64\n```\n\n\nIn the above example, we are iterating over the values of the `.age` array, or,\nthe internal array of the `PersonArray` object that contains the values of the `age`\ndata member from the `Person` values that were added to the multi array struct.\n\nIn this example we are calling the `items()` method directly from the `PersonArray`\nobject. However, in most situations it's recommened to call this `items()` method\nfrom a \"slice object\", which you can create from the `slice()` method.\nThe reason for this is that calling `items()` multiple times have better performance\nif you use a slice object.\n\nTherefore, if you are planning to access only one of the\ninternal arrays from your \"multi array struct\", it's fine to call `items()` directly\nfrom the multi array object. But if you need to access many of the internal arrays\nfrom your \"multi array struct\", then, you will likely need to call `items()` more\nthan once, and, in such circumstance, is better to call `items()` through a slice object.\nThe example below demonstrates the use of such object:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar slice = people.slice();\nfor (slice.items(.age)) |*age| {\n    age.* += 10;\n}\nfor (slice.items(.name), slice.items(.age)) |*n,*a| {\n    try stdout.print(\n        \"Name: {s}, Age: {d}\\n\", .{n.*, a.*}\n    );\n}\n```\n:::\n\n\n\n```\nName: Auguste, Age: 25\nName: Elena, Age: 36\nName: Michael, Age: 74\n```\n\n\n## Conclusion\n\nThere are many other data structures that I haven't presented here.\nBut you can check them out at the official Zig Standard Library documentation page.\nActually, when you get into the [homepage of the documentation](https://ziglang.org/documentation/master/std/#)[^home], the first thing\nthat appears to you in this page, is a list of types and data structures that\nare available in the Zig Standard Library.\nThere are some very specific data structures in this list, like a\n[`BoundedArray` struct](https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray)[^bounded]\n, but there is also some more general structures, such as a\n[`PriorityQueue` struct](https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue)[^priority].\n\n\n[^home]: <https://ziglang.org/documentation/master/std/#>\n[^priority]: <https://ziglang.org/documentation/master/std/#std.priority_queue.PriorityQueue>.\n[^bounded]: <https://ziglang.org/documentation/master/std/#std.bounded_array.BoundedArray>\n",
-    "supporting": [
-      "09-data-structures_files"
-    ],
-    "filters": [
-      "rmarkdown/pagebreak.lua"
-    ],
-    "includes": {},
-    "engineDependencies": {
-      "knitr": [
-        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
-      ]
-    },
-    "preserve": null,
-    "postProcess": false
-  }
-}
\ No newline at end of file
diff --git a/_freeze/Chapters/09-error-handling/execute-results/epub.json b/_freeze/Chapters/09-error-handling/execute-results/epub.json
deleted file mode 100644
index bd4ccc0b..00000000
--- a/_freeze/Chapters/09-error-handling/execute-results/epub.json
+++ /dev/null
@@ -1,21 +0,0 @@
-{
-  "hash": "1ef4c69c6b1bfd8553723d38f6a46fb8",
-  "result": {
-    "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Error handling and unions {#sec-error-handling}\n\nIn this chapter, I want to discuss how error handling is done in Zig.\nWe already briefly learned about one of the available strategies to handle errors in Zig,\nwhich is the `try` keyword presented in @sec-main-file. But we still haven't learned about\nthe other methods, such as the `catch` keyword.\nI also want to discuss in this chapter how union types are created in Zig.\n\n## Learning more about errors in Zig\n\nBefore we get into how error handling is done, we need to learn more about what errors are in Zig.\nAn error is actually a value in Zig [@zigoverview]. In other words, when an error occurs inside your Zig program,\nit means that somewhere in your Zig codebase, an error value is being generated.\nAn error value is similar to any integer value that you create in your Zig code.\nYou can take an error value and pass it as input to a function,\nand you can also cast (or coerce) it into a different type of an error value.\n\nThis have some similarities with exceptions in C++ and Python.\nBecause in C++ and Python, when an exception happens inside a `try` block,\nyou can use a `catch` block (in C++) or an `except` block (in Python)\nto capture the exception produced in the `try` block,\nand pass it to functions as an input.\n\nHowever, error values in Zig are treated very differently than exceptions.\nFirst, you cannot ignore error values in your Zig code. Meaning that, if an error\nvalue appears somewhere in your source code, this error value must be explicitly handled in some way.\nThis also means that you cannot discard error values by assigning them to an underscore,\nas you could do with normal values and objects.\n\nTake the source code below as an example. Here we are trying to open a file that does not exist\nin my computer, and as a result, an obvious error value of `FileNotFound` is returned from the `openFile()`\nfunction. But because I'm assigning the result of this function to an underscore, I end up\ntrying to discard an error value.\n\nThe `zig` compiler detects this mistake, and raises a compile\nerror telling me that I'm trying to discard an error value.\nIt also adds a note message that suggests the use of `try`,\n`catch` or an if statement to explicitly handle this error value\nThis note is reinforcing that every possible error value must be explicitly handled in Zig.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst dir = std.fs.cwd();\n_ = dir.openFile(\"doesnt_exist.txt\", .{});\n```\n:::\n\n\n\n```\nt.zig:8:17: error: error set is discarded\nt.zig:8:17: note: consider using 'try', 'catch', or 'if'\n```\n\n\n### Returning errors from functions\n\nAs we described in @sec-main-file, when we have a function that might return an error\nvalue, this function normally includes an exclamation mark (`!`) in its return type\nannotation. The presence of this exclamation mark indicates that this function might\nreturn an error value as result, and, the `zig` compiler forces you to always handle explicitly\nthe case of this function returning an error value.\n\nTake a look at the `print_name()` function below. This function might return an error in the `stdout.print()` function call,\nand, as a consequence, its return type (`!void`) includes an exclamation mark in it.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_name() !void {\n    const stdout = std.getStdOut().writer();\n    try stdout.print(\"My name is Pedro!\", .{});\n}\n```\n:::\n\n\n\nIn the example above, we are using the exclamation mark to tell the `zig` compiler\nthat this function might return some error. But which error exactly is returned from\nthis function? For now, we are not specifying a specific error value. For now,\nwe only know that some error value (whatever it is) might be returned.\n\nBut in fact, you can (if you want to) specify clearly which exact error values\nmight be returned from this function. There are lot of examples of\nthis in the Zig Standard Library. Take this `fill()` function from\nthe `http.Client` module as an example. This function returns\neither a error value of type `ReadError`, or `void`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn fill(conn: *Connection) ReadError!void {\n    // The body of this function ...\n}\n```\n:::\n\n\n\nThis idea of specifying the exact error values that you expect to be returned\nfrom the function is interesting. Because they automatically become some sort of documentation\nof your function, and also, this allows the `zig` compiler to perform some extra checks over\nyour code. Because the compiler can check if there is any other type of error value\nthat is being generated inside your function, and, that it's not being accounted\nfor in this return type annotation.\n\nAnyway, you can list the types of errors that can be returned from the function\nby listing them on the left side of the exclamation mark. While the valid values\nstay on the right side of the exclamation mark. So the syntax format become:\n\n```\n<error-value>!<valid-value>\n```\n\n\n### Error sets\n\nBut what about when we have a single function that might return different types of errors?\nWhen you have such a function, you can list\nall of these different types of errors that can be returned from this function,\nthrough a structure in Zig that we call of an *error set*.\n\nAn error set is a special case of a union type. It's a union that contains error values in it.\nNot all programming languages have a notion of a \"union object\".\nBut in summary, a union is just a set of data types.\nUnions are used to allow an object to have multiple data types.\nFor example, a union of `x`, `y` and `z`, means that\nan object can be either of type `x`, or type `y` or type `z`.\n\nWe are going to talk in more depth about unions in @sec-unions.\nBut you can write an error set by writing the keyword `error` before\na pair of curly braces, then you list the error values that can be\nreturned from the function inside this pair of curly braces.\n\nTake the `resolvePath()` function below as an example, which comes from the\n`introspect.zig` module of the Zig Standard Library. We can see in its return type annotation, that this\nfunction return either: 1) a valid slice of `u8` values (`[]u8`); or, 2) one of the three different\ntypes of error values listed inside the error set (`OutOfMemory`, `Unexpected`, etc.).\nThis is an usage example of an error set.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn resolvePath(\n    ally: mem.Allocator,\n    p: []const u8,\n) error{\n    OutOfMemory,\n    CurrentWorkingDirectoryUnlinked,\n    Unexpected,\n}![]u8 {\n    // The body of the function ...\n}\n```\n:::\n\n\n\n\nThis is a valid way of annotating the return value of a Zig function. But, if you navigate through\nthe modules that composes the Zig Standard Library, you will notice that, for the majority of cases,\nthe programmers prefer to give a descriptive name to this error set, and then, use this name (or this \"label\")\nof the error set in the return type annotation, instead of using the error set directly.\n\nWe can see that in the `ReadError` error set that we showed earlier in the `fill()` function,\nwhich is defined in the `http.Client` module.\nSo yes, I presented the `ReadError` as if it was just a standard and single error value, but in fact,\nit's an error set defined in the `http.Client` module, and therefore, it actually represents\na set of different error values that might happen inside the `fill()` function.\n\n\nTake a look at the `ReadError` definition reproduced below. Notice that we are grouping all of these\ndifferent error values into a single object, and then, we use this object into the return type annotation of the function.\nLike the `fill()` function that we showed earlier, or, the `readvDirect()` function from the same module,\nwhich is reproduced below.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const ReadError = error{\n    TlsFailure,\n    TlsAlert,\n    ConnectionTimedOut,\n    ConnectionResetByPeer,\n    UnexpectedReadFailure,\n    EndOfStream,\n};\n// Some lines of code\npub fn readvDirect(\n        conn: *Connection,\n        buffers: []std.posix.iovec\n    ) ReadError!usize {\n    // The body of the function ...\n}\n```\n:::\n\n\n\nSo, an error set is just a convenient way of grouping a set of\npossible error values into a single object, or a single type of an error value.\n\n\n### Casting error values\n\nLet's suppose you have two different error sets, named `A` and `B`.\nIf error set `A` is a superset of error set `B`, then, you can cast (or coerce)\nerror values from `B` into error values of `A`.\n\nError sets are just a set of error values. So, if the error set `A`\ncontains all error values from the error set `B`, then `A`\nbecomes a superset of `B`. You could also say\nthat the error set `B` is a subset of error set `A`.\n\nThe example below demonstrates this idea. Because `A` contains all\nvalues from `B`, `A` is a superset of `B`.\nIn math notation, we would say that $A \\supset B$.\nAs a consequence, we can give an error value from `B` as input to the `cast()`\nfunction, and, implicitly cast this input into the same error value, but from the `A` set.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst A = error{\n    ConnectionTimeoutError,\n    DatabaseNotFound,\n    OutOfMemory,\n    InvalidToken,\n};\nconst B = error {\n    OutOfMemory,\n};\n\nfn cast(err: B) A {\n    return err;\n}\n\ntest \"coerce error value\" {\n    const error_value = cast(B.OutOfMemory);\n    try std.testing.expect(\n        error_value == A.OutOfMemory\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file3e2d5fb03d41.test.coerce error value...OKA\n  All 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n## How to handle errors\n\nNow that we learned more about what errors are in Zig,\nlet's discuss the available strategies to handle these errors,\nwhich are:\n\n- `try` keyword;\n- `catch` keyword;\n- an if statement;\n- `errdefer` keyword;\n\n\n\n### What `try` means?\n\nAs I described over the previous sections, when we say that an expression might\nreturn an error, we are basically referring to an expression that have\na return type in the format `!T`.\nThe `!` indicates that this expression returns either an error value, or a value of type `T`.\n\nIn @sec-main-file, I presented the `try` keyword and where to use it.\nBut I did not talked about what exactly this keyword does to your code,\nor, in other words, I have not explained yet what `try` means in your code.\n\nIn essence, when you use the `try` keyword in an expression, you are telling\nthe `zig` compiler the following: \"Hey! Execute this expression for me,\nand, if this expression return an error, please, return this error for me\nand stop the execution of my program. But if this expression return a valid\nvalue, then, return this value, and move on\".\n\nIn other words, the `try` keyword is essentially, a strategy to enter in panic mode, and stop\nthe execution of your program in case an error occurs.\nWith the `try` keyword, you are telling the `zig` compiler, that stopping the execution\nof your program is the most reasonable strategy to take if an error occurs\nin that particular expression.\n\n### The `catch` keyword\n\nOk, now that we understand properly what `try` means, let's discuss `catch` now.\nOne important detail here, is that you can use `try` or `catch` to handle your errors,\nbut you **cannot use `try` and `catch` together**. In other words, `try` and `catch`\nare different and completely separate strategies in the Zig language.\n\nThis is uncommon, and different than what happens in other languages. Most\nprogramming languages that adopts the *try catch* pattern (such as C++, R, Python, Javascript, etc.), normally use\nthese two keywords together to form the complete logic to\nproperly handle the errors.\nAnyway, Zig tries a different approach in the *try catch* pattern.\n\nSo, we learned already about what `try` means, and we also known that both\n`try` and `catch` should be used alone, separate from each other. But\nwhat exactly `catch` do in Zig? With `catch`, we can construct a block of\nlogic to handle the error value, in case it happens in the current expression.\n\nLook at the code example below. Once again, we go back to the previous\nexample where we were trying to open a file that doesn't exist in my computer,\nbut this time, I use `catch` to actually implement a logic to handle the error, instead of\njust stopping the execution right away.\n\nMore specifically, in this example, I'm using a logger object to record some logs into\nthe system, before I return the error, and stop the execution of the program. For example,\nthis could be some part of the codebase of a complex system that I do not have full control over,\nand I want to record these logs before the program crashes, so that I can debug it later\n(e.g. maybe I cannot compile the full program, and properly debug it with a debugger. So, these logs might\nbe a valid strategy to surpass this barrier).\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst dir = std.fs.cwd();\nconst file = dir.openFile(\n    \"doesnt_exist.txt\", .{}\n) catch |err| {\n    logger.record_context();\n    logger.log_error(err);\n    return err;\n};\n```\n:::\n\n\n\n\nTherefore, we use `catch` to create a block of expressions that will handle the error.\nI can return the error value from this block of expressions, like I did in the above example,\nwhich, will make the program enter in panic mode, and, stop the execution.\nBut I could also, return a valid value from this block of code, which would\nbe stored in the `file` object.\n\nNotice that, instead of writing the keyword before the expression that might return the error,\nlike we do with `try`, we write `catch` after the expression. We can open the pair of pipes (`|`),\nwhich captures the error value returned by the expression, and makes\nthis error value available in the scope of the `catch` block as the object named `err`.\nIn other words, because I wrote `|err|` in the code, I can access the error value\nreturned by the expression, by using the `err` object.\n\nAlthough this being the most common use of `catch`, you can also use this keyword\nto handle the error in a \"default value\" style. That is, if the expression returns\nan error, we use the default value instead. Otherwise, we use the valid value returned\nby the expression.\n\nThe Zig official language reference, provides a great example of this \"default value\"\nstrategy with `catch`. This example is reproduced below. Notice that we are trying to parse\nsome unsigned integer from a string object named `str`. In other words, this function\nis trying to transform an object of type `[]const u8` (i.e., an array of characters, a string, etc.)\ninto an object of type `u64`.\n\nBut this parsing process done by the function `parseU64()` may fail, resulting in a runtime error.\nThe `catch` keyword used in this example provides an alternative value (13) to be used in case\nthis `parseU64()` function raises an error. So, the expression below essentially means:\n\"Hey! Please, parse this string into a `u64` for me, and store the results into the\nobject `number`. But, if an error occurs, then, use the value `13` instead\".\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number = parseU64(str, 10) catch 13;\n```\n:::\n\n\n\nSo, at the end of this process, the object `number` will contain either a `u64` integer\nthat was parsed successfully from the input string `str`, or, if an error occurs in the\nparsing process, it will contain the `u64` value `13` that was provided by the `catch`\nkeyword as the \"default\", or, the \"alternative\" value.\n\n\n\n### Using if statements\n\nNow, you can also use if statements to handle errors in your Zig code.\nIn the example below, I'm reproducing the previous example, where\nwe try to parse an integer value from an input string with a function\nnamed `parseU64()`.\n\nWe execute the expression inside the \"if\". If this expression returns an\nerror value, the \"if branch\" (or, the \"true branch\") of the if statement is not executed.\nBut if this expression returns a valid value instead, then, this value is unwrapped\ninto the `number` object.\n\nThis means that, if the `parseU64()` expression returns a valid value, this value becomes available\ninside the scope of this \"if branch\" (i.e., the \"true branch\") through the object that we listed inside the pair\nof pipe character (`|`), which is the object `number`.\n\nIf an error occurs, we can use an \"else branch\" (or the \"false branch\") of the if statement\nto handle the error. In the example below, we are using the `else` in the if statement\nto unwrap the error value (that was returned by `parseU64()`) into the `err` object,\nand handle the error.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (parseU64(str, 10)) |number| {\n    // do something with `number` here\n} else |err| {\n    // handle the error value.\n}\n```\n:::\n\n\n\nNow, if the expression that you are executing returns different types of error values,\nand you want to take a different action in each of these types of error values, the\n`try` and `catch` keywords, and the if statement strategy, becomes limited.\n\nFor this type of situation, the official documentation of the language suggests\nthe use of a switch statement together with an if statement [@zigdocs].\nThe basic idea is, to use the if statement to execute the expression, and\nuse the \"else branch\" to pass the error value to a switch statement, where\nyou define a different action for each type of error value that might be\nreturned by the expression executed in the if statement.\n\nThe example below demonstrates this idea. We first try to add (or register) a set of\ntasks to a queue. If this \"registration process\" occurs well, we then try\nto distribute these tasks across the workers of our system. But\nif this \"registration process\" returns an error value, we then use a switch\nstatement in the \"else branch\" to handle each possible error value.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (add_tasks_to_queue(&queue, tasks)) |_| {\n    distribute_tasks(&queue);\n} else |err| switch (err) {\n    error.InvalidTaskName => {\n        // do something\n    },\n    error.TimeoutTooBig => {\n        // do something\n    },\n    error.QueueNotFound => {\n        // do something\n    },\n    // and all the other error options ...\n}\n```\n:::\n\n\n\n\n### The `errdefer` keyword {#sec-errdefer2}\n\nA common pattern in C programs in general, is to clean resources when an error occurs during\nthe execution of the program. In other words, one common way to handle errors, is to perform\n\"cleanup actions\" before we exit our program. This guarantees that a runtime error does not make\nour program to leak resources of the system.\n\n\nThe `errdefer` keyword is a tool to perform such \"cleanup actions\" in hostile situations.\nThis keyword is commonly used to clean (or to free) allocated resources, before the execution of our program\ngets stopped because of an error value being generated.\n\nThe basic idea is to provide an expression to the `errdefer` keyword. Then,\n`errdefer` executes this expression if, and only if, an error occurs\nduring the execution of the current scope.\nIn the example below, we are using an allocator object (that we have presented in @sec-allocators)\nto create a new `User` object. If we are successful in creating and registering this new user,\nthis `create_user()` function will return this new `User` object as its return value.\n\nHowever, if for some reason, an error value is generated by some expression\nthat is after the `errdefer` line, for example, in the `db.add(user)` expression,\nthe expression registered by `errdefer` gets executed before the error value is returned\nfrom the function, and before the program enters in panic mode and stops the\ncurrent execution.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn create_user(db: Database, allocator: Allocator) !User {\n    const user = try allocator.create(User);\n    errdefer allocator.destroy(user);\n\n    // Register new user in the Database.\n    _ = try db.register_user(user);\n    return user;\n}\n```\n:::\n\n\n\nBy using `errdefer` to destroy the `user` object that we have just created,\nwe guarantee that the memory allocated for this `user` object\ngets freed, before the execution of the program stops.\nBecause if the expression `try db.add(user)` returns an error value,\nthe execution of our program stops, and we lose all references and control over the memory\nthat we have allocated for the `user` object.\nAs a result, if we do not free the memory associated with the `user` object before the program stops,\nwe cannot free this memory anymore. We simply lose our chance to do the right thing.\nThat is why `errdefer` is essential in this situation.\n\nJust to state clearly the differences between `defer` and `errdefer`\n(which I described in @sec-defer and @sec-errdefer1), it might be worth\nto discuss the subject a bit further. You might still have the question\n\"why use `errdefer` if we can use `defer` instead?\" in your mind.\n\nAlthough being similar, the key difference between `errdefer` and `defer` keyword\nis when the provided expression gets executed.\nThe `defer` keyword always execute the provided expression at the end of the\ncurrent scope, no matter how your code exits this scope.\nIn contrast, `errdefer` executes the provided expression only when an error occurs in the\ncurrent scope.\n\nThis becomes important if a resource that you allocate in the\ncurrent scope gets freed later in your code, in a different scope.\nThe `create_user()` functions is an example of this. If you think\nclosely about this function, you will notice that this function returns\nthe `user` object as the result.\n\nIn other words, the allocated memory for the `user` object does not get\nfreed inside the `create_user()` function, if it returns successfully.\nSo, if an error does not occur inside this function, the `user` object\nis returned from the function, and probably, the code that runs after\nthis `create_user()` function will be responsible for freeing\nthe memory of the `user` object.\n\nBut what if an error occurs inside the `create_user()` function? What happens then?\nThis would mean that the execution of your code would stop in this `create_user()`\nfunction, and, as a consequence, the code that runs after this `create_user()`\nfunction would simply not run, and, as a result, the memory of the `user` object\nwould not be freed before your program stops.\n\nThis is the perfect scenario for `errdefer`. We use this keyword to guarantee\nthat our program will free the allocated memory for the `user` object,\neven if an error occurs inside the `create_user()` function.\n\nIf you allocate and free some memory for an object inside the same scope, then,\njust use `defer` and be happy, i.e., `errdefer` have no use for you in such situation.\nBut if you allocate some memory in a scope A, but you only free this memory\nlater, in a scope B for example, then, `errdefer` becomes useful to avoid leaking memory\nin sketchy situations.\n\n\n\n## Union type in Zig {#sec-unions}\n\nA union type defines a set of types that an object can be. It's like a list of\noptions. Each option is a type that an object can assume. Therefore, unions in Zig\nhave the same meaning, or, the same role as unions in C. They are used for the same purpose.\nYou could also say that unions in Zig produces a similar effect to\n[using `typing.Union` in Python](https://docs.python.org/3/library/typing.html#typing.Union)[^pyunion].\n\n[^pyunion]: <https://docs.python.org/3/library/typing.html#typing.Union>\n\nFor example, you might be creating an API that sends data to a data lake, hosted\nin some private cloud infrastructure. Suppose you have created different structs in your codebase,\nto store the necessary information that you need, in order to connect to the services of\neach mainstream data lake service (Amazon S3, Azure Blob, etc.).\n\nNow, suppose you also have a function named `send_event()` that receives an event as input,\nand, a target data lake, and it sends the input event to the data lake specified in the\ntarget data lake argument. But this target data lake could be any of the three mainstream data lakes\nservices (Amazon S3, Azure Blob, etc.). Here is where an union can help you.\n\nThe union `LakeTarget` defined below allows the `lake_target` argument of `send_event()`\nto be either an object of type `AzureBlob`, or type `AmazonS3`, or type `GoogleGCP`.\nThis union allows the `send_event()` function to receive an object of any of these three types\nas input in the `lake_target` argument.\n\nRemember that each of these three types (`AmazonS3`, `GoogleGCP` and `AzureBlob`)\nare separate structs that we have defined in our source code. So, at first glance,\nthey are separate data types in our source code. But is the `union` keyword that\nunifies them into a single data type called `LakeTarget`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst LakeTarget = union {\n    azure: AzureBlob,\n    amazon: AmazonS3,\n    google: GoogleGCP,\n};\n\nfn send_event(\n    event: Event,\n    lake_target: LakeTarget\n) bool {\n    // body of the function ...\n}\n```\n:::\n\n\n\nAn union definition is composed by a list of data members. Each data member is of a specific data type.\nIn the example above, the `LakeTarget` union have three data members (`azure`, `amazon`, `google`).\nWhen you instantiate an object that uses an union type, you can only use one of its data members\nin this instantiation.\n\nYou could also interpret this as: only one data member of an union type can be activated at a time, the other data\nmembers remain deactivated and unaccessible. For example, if you create a `LakeTarget` object that uses\nthe `azure` data member, you can no longer use or access the data members `google` or `amazon`.\nIt's like if these other data members didn't exist at all in the `LakeTarget` type.\n\nYou can see this logic in the example below. Notice that, we first instantiate the union\nobject using the `azure` data member. As a result, this `target` object contains only\nthe `azure` data member inside of it. Only this data member is active in this object.\nThat is why the last line in this code example is invalid. Because we are trying to instantiate the data member\n`google`, which is currently inactive for this `target` object, and as a result, the program\nenters in panic mode warning us about this mistake through a loud error message.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar target = LakeTarget {\n    .azure = AzureBlob.init()\n};\n// Only the `azure` data member exist inside\n// the `target` object, and, as a result, this\n// line below is invalid:\ntarget.google = GoogleGCP.init();\n```\n:::\n\n\n\n```\nthread 2177312 panic: access of union field 'google' while\n    field 'azure' is active:\n    target.google = GoogleGCP.init();\n          ^\n```\n\nSo, when you instantiate an union object, you must choose one of the data types (or, one of the data members)\nlisted in the union type. In the example above, I choose to use the `azure` data member, and, as a result,\nall other data members were automatically deactivated,\nand you can no longer use them after you instantiate the object.\n\nYou can activate another data member by completely redefining the entire enum object.\nIn the example below, I initially use the `azure` data member. But then, I redefine the\n`target` object to use a new `LakeTarget` object, which uses the `google` data member.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar target = LakeTarget {\n    .azure = AzureBlob.init()\n};\ntarget = LakeTarget {\n    .google = GoogleGCP.init()\n};\n```\n:::\n\n\n\nA curious fact about union types, is that, at first, you cannot use them in switch statements (which were presented in @sec-switch).\nIn other words, if you have an object of type `LakeTarget` for example, you cannot give this object\nas input to a switch statement.\n\nBut what if you really need to do so? What if you actually need to\nprovide an \"union object\" to a switch statement? The answer to this question relies on another special type in Zig,\nwhich are the *tagged unions*. To create a tagged union, all you have to do is to add\nan enum type into your union declaration.\n\nAs an example of a tagged union in Zig, take the `Registry` type exposed\nbelow. This type comes from the\n[`grammar.zig` module](https://github.com/ziglang/zig/blob/30b4a87db711c368853b3eff8e214ab681810ef9/tools/spirv/grammar.zig)[^grammar]\nfrom the Zig repository. This union type lists different types of registries.\nBut notice this time, the use of `(enum)` after the `union` keyword. This is what makes\nthis union type a tagged union. By being a tagged union, an object of this `Registry` type\ncan be used as input in a switch statement. This is all you have to do. Just add `(enum)`\nto your `union` declaration, and you can use it in switch statements.\n\n[^grammar]: <https://github.com/ziglang/zig/blob/30b4a87db711c368853b3eff8e214ab681810ef9/tools/spirv/grammar.zig>.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const Registry = union(enum) {\n    core: CoreRegistry,\n    extension: ExtensionRegistry,\n};\n```\n:::\n",
-    "supporting": [
-      "09-error-handling_files"
-    ],
-    "filters": [
-      "rmarkdown/pagebreak.lua"
-    ],
-    "includes": {},
-    "engineDependencies": {
-      "knitr": [
-        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
-      ]
-    },
-    "preserve": null,
-    "postProcess": false
-  }
-}
\ No newline at end of file
diff --git a/_freeze/Chapters/09-error-handling/execute-results/html.json b/_freeze/Chapters/09-error-handling/execute-results/html.json
index aaffaa3e..9c2d7fed 100644
--- a/_freeze/Chapters/09-error-handling/execute-results/html.json
+++ b/_freeze/Chapters/09-error-handling/execute-results/html.json
@@ -2,10 +2,8 @@
   "hash": "1ef4c69c6b1bfd8553723d38f6a46fb8",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Error handling and unions {#sec-error-handling}\n\nIn this chapter, I want to discuss how error handling is done in Zig.\nWe already briefly learned about one of the available strategies to handle errors in Zig,\nwhich is the `try` keyword presented in @sec-main-file. But we still haven't learned about\nthe other methods, such as the `catch` keyword.\nI also want to discuss in this chapter how union types are created in Zig.\n\n## Learning more about errors in Zig\n\nBefore we get into how error handling is done, we need to learn more about what errors are in Zig.\nAn error is actually a value in Zig [@zigoverview]. In other words, when an error occurs inside your Zig program,\nit means that somewhere in your Zig codebase, an error value is being generated.\nAn error value is similar to any integer value that you create in your Zig code.\nYou can take an error value and pass it as input to a function,\nand you can also cast (or coerce) it into a different type of an error value.\n\nThis have some similarities with exceptions in C++ and Python.\nBecause in C++ and Python, when an exception happens inside a `try` block,\nyou can use a `catch` block (in C++) or an `except` block (in Python)\nto capture the exception produced in the `try` block,\nand pass it to functions as an input.\n\nHowever, error values in Zig are treated very differently than exceptions.\nFirst, you cannot ignore error values in your Zig code. Meaning that, if an error\nvalue appears somewhere in your source code, this error value must be explicitly handled in some way.\nThis also means that you cannot discard error values by assigning them to an underscore,\nas you could do with normal values and objects.\n\nTake the source code below as an example. Here we are trying to open a file that does not exist\nin my computer, and as a result, an obvious error value of `FileNotFound` is returned from the `openFile()`\nfunction. But because I'm assigning the result of this function to an underscore, I end up\ntrying to discard an error value.\n\nThe `zig` compiler detects this mistake, and raises a compile\nerror telling me that I'm trying to discard an error value.\nIt also adds a note message that suggests the use of `try`,\n`catch` or an if statement to explicitly handle this error value\nThis note is reinforcing that every possible error value must be explicitly handled in Zig.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst dir = std.fs.cwd();\n_ = dir.openFile(\"doesnt_exist.txt\", .{});\n```\n:::\n\n\n\n\n```\nt.zig:8:17: error: error set is discarded\nt.zig:8:17: note: consider using 'try', 'catch', or 'if'\n```\n\n\n### Returning errors from functions\n\nAs we described in @sec-main-file, when we have a function that might return an error\nvalue, this function normally includes an exclamation mark (`!`) in its return type\nannotation. The presence of this exclamation mark indicates that this function might\nreturn an error value as result, and, the `zig` compiler forces you to always handle explicitly\nthe case of this function returning an error value.\n\nTake a look at the `print_name()` function below. This function might return an error in the `stdout.print()` function call,\nand, as a consequence, its return type (`!void`) includes an exclamation mark in it.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_name() !void {\n    const stdout = std.getStdOut().writer();\n    try stdout.print(\"My name is Pedro!\", .{});\n}\n```\n:::\n\n\n\n\nIn the example above, we are using the exclamation mark to tell the `zig` compiler\nthat this function might return some error. But which error exactly is returned from\nthis function? For now, we are not specifying a specific error value. For now,\nwe only know that some error value (whatever it is) might be returned.\n\nBut in fact, you can (if you want to) specify clearly which exact error values\nmight be returned from this function. There are lot of examples of\nthis in the Zig Standard Library. Take this `fill()` function from\nthe `http.Client` module as an example. This function returns\neither a error value of type `ReadError`, or `void`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn fill(conn: *Connection) ReadError!void {\n    // The body of this function ...\n}\n```\n:::\n\n\n\n\nThis idea of specifying the exact error values that you expect to be returned\nfrom the function is interesting. Because they automatically become some sort of documentation\nof your function, and also, this allows the `zig` compiler to perform some extra checks over\nyour code. Because the compiler can check if there is any other type of error value\nthat is being generated inside your function, and, that it's not being accounted\nfor in this return type annotation.\n\nAnyway, you can list the types of errors that can be returned from the function\nby listing them on the left side of the exclamation mark. While the valid values\nstay on the right side of the exclamation mark. So the syntax format become:\n\n```\n<error-value>!<valid-value>\n```\n\n\n### Error sets\n\nBut what about when we have a single function that might return different types of errors?\nWhen you have such a function, you can list\nall of these different types of errors that can be returned from this function,\nthrough a structure in Zig that we call of an *error set*.\n\nAn error set is a special case of a union type. It's a union that contains error values in it.\nNot all programming languages have a notion of a \"union object\".\nBut in summary, a union is just a set of data types.\nUnions are used to allow an object to have multiple data types.\nFor example, a union of `x`, `y` and `z`, means that\nan object can be either of type `x`, or type `y` or type `z`.\n\nWe are going to talk in more depth about unions in @sec-unions.\nBut you can write an error set by writing the keyword `error` before\na pair of curly braces, then you list the error values that can be\nreturned from the function inside this pair of curly braces.\n\nTake the `resolvePath()` function below as an example, which comes from the\n`introspect.zig` module of the Zig Standard Library. We can see in its return type annotation, that this\nfunction return either: 1) a valid slice of `u8` values (`[]u8`); or, 2) one of the three different\ntypes of error values listed inside the error set (`OutOfMemory`, `Unexpected`, etc.).\nThis is an usage example of an error set.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn resolvePath(\n    ally: mem.Allocator,\n    p: []const u8,\n) error{\n    OutOfMemory,\n    CurrentWorkingDirectoryUnlinked,\n    Unexpected,\n}![]u8 {\n    // The body of the function ...\n}\n```\n:::\n\n\n\n\n\nThis is a valid way of annotating the return value of a Zig function. But, if you navigate through\nthe modules that composes the Zig Standard Library, you will notice that, for the majority of cases,\nthe programmers prefer to give a descriptive name to this error set, and then, use this name (or this \"label\")\nof the error set in the return type annotation, instead of using the error set directly.\n\nWe can see that in the `ReadError` error set that we showed earlier in the `fill()` function,\nwhich is defined in the `http.Client` module.\nSo yes, I presented the `ReadError` as if it was just a standard and single error value, but in fact,\nit's an error set defined in the `http.Client` module, and therefore, it actually represents\na set of different error values that might happen inside the `fill()` function.\n\n\nTake a look at the `ReadError` definition reproduced below. Notice that we are grouping all of these\ndifferent error values into a single object, and then, we use this object into the return type annotation of the function.\nLike the `fill()` function that we showed earlier, or, the `readvDirect()` function from the same module,\nwhich is reproduced below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const ReadError = error{\n    TlsFailure,\n    TlsAlert,\n    ConnectionTimedOut,\n    ConnectionResetByPeer,\n    UnexpectedReadFailure,\n    EndOfStream,\n};\n// Some lines of code\npub fn readvDirect(\n        conn: *Connection,\n        buffers: []std.posix.iovec\n    ) ReadError!usize {\n    // The body of the function ...\n}\n```\n:::\n\n\n\n\nSo, an error set is just a convenient way of grouping a set of\npossible error values into a single object, or a single type of an error value.\n\n\n### Casting error values\n\nLet's suppose you have two different error sets, named `A` and `B`.\nIf error set `A` is a superset of error set `B`, then, you can cast (or coerce)\nerror values from `B` into error values of `A`.\n\nError sets are just a set of error values. So, if the error set `A`\ncontains all error values from the error set `B`, then `A`\nbecomes a superset of `B`. You could also say\nthat the error set `B` is a subset of error set `A`.\n\nThe example below demonstrates this idea. Because `A` contains all\nvalues from `B`, `A` is a superset of `B`.\nIn math notation, we would say that $A \\supset B$.\nAs a consequence, we can give an error value from `B` as input to the `cast()`\nfunction, and, implicitly cast this input into the same error value, but from the `A` set.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst A = error{\n    ConnectionTimeoutError,\n    DatabaseNotFound,\n    OutOfMemory,\n    InvalidToken,\n};\nconst B = error {\n    OutOfMemory,\n};\n\nfn cast(err: B) A {\n    return err;\n}\n\ntest \"coerce error value\" {\n    const error_value = cast(B.OutOfMemory);\n    try std.testing.expect(\n        error_value == A.OutOfMemory\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file826379a872a1.test.coerce error value...OKA\n  All 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n## How to handle errors\n\nNow that we learned more about what errors are in Zig,\nlet's discuss the available strategies to handle these errors,\nwhich are:\n\n- `try` keyword;\n- `catch` keyword;\n- an if statement;\n- `errdefer` keyword;\n\n\n\n### What `try` means?\n\nAs I described over the previous sections, when we say that an expression might\nreturn an error, we are basically referring to an expression that have\na return type in the format `!T`.\nThe `!` indicates that this expression returns either an error value, or a value of type `T`.\n\nIn @sec-main-file, I presented the `try` keyword and where to use it.\nBut I did not talked about what exactly this keyword does to your code,\nor, in other words, I have not explained yet what `try` means in your code.\n\nIn essence, when you use the `try` keyword in an expression, you are telling\nthe `zig` compiler the following: \"Hey! Execute this expression for me,\nand, if this expression return an error, please, return this error for me\nand stop the execution of my program. But if this expression return a valid\nvalue, then, return this value, and move on\".\n\nIn other words, the `try` keyword is essentially, a strategy to enter in panic mode, and stop\nthe execution of your program in case an error occurs.\nWith the `try` keyword, you are telling the `zig` compiler, that stopping the execution\nof your program is the most reasonable strategy to take if an error occurs\nin that particular expression.\n\n### The `catch` keyword\n\nOk, now that we understand properly what `try` means, let's discuss `catch` now.\nOne important detail here, is that you can use `try` or `catch` to handle your errors,\nbut you **cannot use `try` and `catch` together**. In other words, `try` and `catch`\nare different and completely separate strategies in the Zig language.\n\nThis is uncommon, and different than what happens in other languages. Most\nprogramming languages that adopts the *try catch* pattern (such as C++, R, Python, Javascript, etc.), normally use\nthese two keywords together to form the complete logic to\nproperly handle the errors.\nAnyway, Zig tries a different approach in the *try catch* pattern.\n\nSo, we learned already about what `try` means, and we also known that both\n`try` and `catch` should be used alone, separate from each other. But\nwhat exactly `catch` do in Zig? With `catch`, we can construct a block of\nlogic to handle the error value, in case it happens in the current expression.\n\nLook at the code example below. Once again, we go back to the previous\nexample where we were trying to open a file that doesn't exist in my computer,\nbut this time, I use `catch` to actually implement a logic to handle the error, instead of\njust stopping the execution right away.\n\nMore specifically, in this example, I'm using a logger object to record some logs into\nthe system, before I return the error, and stop the execution of the program. For example,\nthis could be some part of the codebase of a complex system that I do not have full control over,\nand I want to record these logs before the program crashes, so that I can debug it later\n(e.g. maybe I cannot compile the full program, and properly debug it with a debugger. So, these logs might\nbe a valid strategy to surpass this barrier).\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst dir = std.fs.cwd();\nconst file = dir.openFile(\n    \"doesnt_exist.txt\", .{}\n) catch |err| {\n    logger.record_context();\n    logger.log_error(err);\n    return err;\n};\n```\n:::\n\n\n\n\n\nTherefore, we use `catch` to create a block of expressions that will handle the error.\nI can return the error value from this block of expressions, like I did in the above example,\nwhich, will make the program enter in panic mode, and, stop the execution.\nBut I could also, return a valid value from this block of code, which would\nbe stored in the `file` object.\n\nNotice that, instead of writing the keyword before the expression that might return the error,\nlike we do with `try`, we write `catch` after the expression. We can open the pair of pipes (`|`),\nwhich captures the error value returned by the expression, and makes\nthis error value available in the scope of the `catch` block as the object named `err`.\nIn other words, because I wrote `|err|` in the code, I can access the error value\nreturned by the expression, by using the `err` object.\n\nAlthough this being the most common use of `catch`, you can also use this keyword\nto handle the error in a \"default value\" style. That is, if the expression returns\nan error, we use the default value instead. Otherwise, we use the valid value returned\nby the expression.\n\nThe Zig official language reference, provides a great example of this \"default value\"\nstrategy with `catch`. This example is reproduced below. Notice that we are trying to parse\nsome unsigned integer from a string object named `str`. In other words, this function\nis trying to transform an object of type `[]const u8` (i.e., an array of characters, a string, etc.)\ninto an object of type `u64`.\n\nBut this parsing process done by the function `parseU64()` may fail, resulting in a runtime error.\nThe `catch` keyword used in this example provides an alternative value (13) to be used in case\nthis `parseU64()` function raises an error. So, the expression below essentially means:\n\"Hey! Please, parse this string into a `u64` for me, and store the results into the\nobject `number`. But, if an error occurs, then, use the value `13` instead\".\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number = parseU64(str, 10) catch 13;\n```\n:::\n\n\n\n\nSo, at the end of this process, the object `number` will contain either a `u64` integer\nthat was parsed successfully from the input string `str`, or, if an error occurs in the\nparsing process, it will contain the `u64` value `13` that was provided by the `catch`\nkeyword as the \"default\", or, the \"alternative\" value.\n\n\n\n### Using if statements\n\nNow, you can also use if statements to handle errors in your Zig code.\nIn the example below, I'm reproducing the previous example, where\nwe try to parse an integer value from an input string with a function\nnamed `parseU64()`.\n\nWe execute the expression inside the \"if\". If this expression returns an\nerror value, the \"if branch\" (or, the \"true branch\") of the if statement is not executed.\nBut if this expression returns a valid value instead, then, this value is unwrapped\ninto the `number` object.\n\nThis means that, if the `parseU64()` expression returns a valid value, this value becomes available\ninside the scope of this \"if branch\" (i.e., the \"true branch\") through the object that we listed inside the pair\nof pipe character (`|`), which is the object `number`.\n\nIf an error occurs, we can use an \"else branch\" (or the \"false branch\") of the if statement\nto handle the error. In the example below, we are using the `else` in the if statement\nto unwrap the error value (that was returned by `parseU64()`) into the `err` object,\nand handle the error.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (parseU64(str, 10)) |number| {\n    // do something with `number` here\n} else |err| {\n    // handle the error value.\n}\n```\n:::\n\n\n\n\nNow, if the expression that you are executing returns different types of error values,\nand you want to take a different action in each of these types of error values, the\n`try` and `catch` keywords, and the if statement strategy, becomes limited.\n\nFor this type of situation, the official documentation of the language suggests\nthe use of a switch statement together with an if statement [@zigdocs].\nThe basic idea is, to use the if statement to execute the expression, and\nuse the \"else branch\" to pass the error value to a switch statement, where\nyou define a different action for each type of error value that might be\nreturned by the expression executed in the if statement.\n\nThe example below demonstrates this idea. We first try to add (or register) a set of\ntasks to a queue. If this \"registration process\" occurs well, we then try\nto distribute these tasks across the workers of our system. But\nif this \"registration process\" returns an error value, we then use a switch\nstatement in the \"else branch\" to handle each possible error value.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (add_tasks_to_queue(&queue, tasks)) |_| {\n    distribute_tasks(&queue);\n} else |err| switch (err) {\n    error.InvalidTaskName => {\n        // do something\n    },\n    error.TimeoutTooBig => {\n        // do something\n    },\n    error.QueueNotFound => {\n        // do something\n    },\n    // and all the other error options ...\n}\n```\n:::\n\n\n\n\n\n### The `errdefer` keyword {#sec-errdefer2}\n\nA common pattern in C programs in general, is to clean resources when an error occurs during\nthe execution of the program. In other words, one common way to handle errors, is to perform\n\"cleanup actions\" before we exit our program. This guarantees that a runtime error does not make\nour program to leak resources of the system.\n\n\nThe `errdefer` keyword is a tool to perform such \"cleanup actions\" in hostile situations.\nThis keyword is commonly used to clean (or to free) allocated resources, before the execution of our program\ngets stopped because of an error value being generated.\n\nThe basic idea is to provide an expression to the `errdefer` keyword. Then,\n`errdefer` executes this expression if, and only if, an error occurs\nduring the execution of the current scope.\nIn the example below, we are using an allocator object (that we have presented in @sec-allocators)\nto create a new `User` object. If we are successful in creating and registering this new user,\nthis `create_user()` function will return this new `User` object as its return value.\n\nHowever, if for some reason, an error value is generated by some expression\nthat is after the `errdefer` line, for example, in the `db.add(user)` expression,\nthe expression registered by `errdefer` gets executed before the error value is returned\nfrom the function, and before the program enters in panic mode and stops the\ncurrent execution.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn create_user(db: Database, allocator: Allocator) !User {\n    const user = try allocator.create(User);\n    errdefer allocator.destroy(user);\n\n    // Register new user in the Database.\n    _ = try db.register_user(user);\n    return user;\n}\n```\n:::\n\n\n\n\nBy using `errdefer` to destroy the `user` object that we have just created,\nwe guarantee that the memory allocated for this `user` object\ngets freed, before the execution of the program stops.\nBecause if the expression `try db.add(user)` returns an error value,\nthe execution of our program stops, and we lose all references and control over the memory\nthat we have allocated for the `user` object.\nAs a result, if we do not free the memory associated with the `user` object before the program stops,\nwe cannot free this memory anymore. We simply lose our chance to do the right thing.\nThat is why `errdefer` is essential in this situation.\n\nJust to state clearly the differences between `defer` and `errdefer`\n(which I described in @sec-defer and @sec-errdefer1), it might be worth\nto discuss the subject a bit further. You might still have the question\n\"why use `errdefer` if we can use `defer` instead?\" in your mind.\n\nAlthough being similar, the key difference between `errdefer` and `defer` keyword\nis when the provided expression gets executed.\nThe `defer` keyword always execute the provided expression at the end of the\ncurrent scope, no matter how your code exits this scope.\nIn contrast, `errdefer` executes the provided expression only when an error occurs in the\ncurrent scope.\n\nThis becomes important if a resource that you allocate in the\ncurrent scope gets freed later in your code, in a different scope.\nThe `create_user()` functions is an example of this. If you think\nclosely about this function, you will notice that this function returns\nthe `user` object as the result.\n\nIn other words, the allocated memory for the `user` object does not get\nfreed inside the `create_user()` function, if it returns successfully.\nSo, if an error does not occur inside this function, the `user` object\nis returned from the function, and probably, the code that runs after\nthis `create_user()` function will be responsible for freeing\nthe memory of the `user` object.\n\nBut what if an error occurs inside the `create_user()` function? What happens then?\nThis would mean that the execution of your code would stop in this `create_user()`\nfunction, and, as a consequence, the code that runs after this `create_user()`\nfunction would simply not run, and, as a result, the memory of the `user` object\nwould not be freed before your program stops.\n\nThis is the perfect scenario for `errdefer`. We use this keyword to guarantee\nthat our program will free the allocated memory for the `user` object,\neven if an error occurs inside the `create_user()` function.\n\nIf you allocate and free some memory for an object inside the same scope, then,\njust use `defer` and be happy, i.e., `errdefer` have no use for you in such situation.\nBut if you allocate some memory in a scope A, but you only free this memory\nlater, in a scope B for example, then, `errdefer` becomes useful to avoid leaking memory\nin sketchy situations.\n\n\n\n## Union type in Zig {#sec-unions}\n\nA union type defines a set of types that an object can be. It's like a list of\noptions. Each option is a type that an object can assume. Therefore, unions in Zig\nhave the same meaning, or, the same role as unions in C. They are used for the same purpose.\nYou could also say that unions in Zig produces a similar effect to\n[using `typing.Union` in Python](https://docs.python.org/3/library/typing.html#typing.Union)[^pyunion].\n\n[^pyunion]: <https://docs.python.org/3/library/typing.html#typing.Union>\n\nFor example, you might be creating an API that sends data to a data lake, hosted\nin some private cloud infrastructure. Suppose you have created different structs in your codebase,\nto store the necessary information that you need, in order to connect to the services of\neach mainstream data lake service (Amazon S3, Azure Blob, etc.).\n\nNow, suppose you also have a function named `send_event()` that receives an event as input,\nand, a target data lake, and it sends the input event to the data lake specified in the\ntarget data lake argument. But this target data lake could be any of the three mainstream data lakes\nservices (Amazon S3, Azure Blob, etc.). Here is where an union can help you.\n\nThe union `LakeTarget` defined below allows the `lake_target` argument of `send_event()`\nto be either an object of type `AzureBlob`, or type `AmazonS3`, or type `GoogleGCP`.\nThis union allows the `send_event()` function to receive an object of any of these three types\nas input in the `lake_target` argument.\n\nRemember that each of these three types (`AmazonS3`, `GoogleGCP` and `AzureBlob`)\nare separate structs that we have defined in our source code. So, at first glance,\nthey are separate data types in our source code. But is the `union` keyword that\nunifies them into a single data type called `LakeTarget`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst LakeTarget = union {\n    azure: AzureBlob,\n    amazon: AmazonS3,\n    google: GoogleGCP,\n};\n\nfn send_event(\n    event: Event,\n    lake_target: LakeTarget\n) bool {\n    // body of the function ...\n}\n```\n:::\n\n\n\n\nAn union definition is composed by a list of data members. Each data member is of a specific data type.\nIn the example above, the `LakeTarget` union have three data members (`azure`, `amazon`, `google`).\nWhen you instantiate an object that uses an union type, you can only use one of its data members\nin this instantiation.\n\nYou could also interpret this as: only one data member of an union type can be activated at a time, the other data\nmembers remain deactivated and unaccessible. For example, if you create a `LakeTarget` object that uses\nthe `azure` data member, you can no longer use or access the data members `google` or `amazon`.\nIt's like if these other data members didn't exist at all in the `LakeTarget` type.\n\nYou can see this logic in the example below. Notice that, we first instantiate the union\nobject using the `azure` data member. As a result, this `target` object contains only\nthe `azure` data member inside of it. Only this data member is active in this object.\nThat is why the last line in this code example is invalid. Because we are trying to instantiate the data member\n`google`, which is currently inactive for this `target` object, and as a result, the program\nenters in panic mode warning us about this mistake through a loud error message.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar target = LakeTarget {\n    .azure = AzureBlob.init()\n};\n// Only the `azure` data member exist inside\n// the `target` object, and, as a result, this\n// line below is invalid:\ntarget.google = GoogleGCP.init();\n```\n:::\n\n\n\n\n```\nthread 2177312 panic: access of union field 'google' while\n    field 'azure' is active:\n    target.google = GoogleGCP.init();\n          ^\n```\n\nSo, when you instantiate an union object, you must choose one of the data types (or, one of the data members)\nlisted in the union type. In the example above, I choose to use the `azure` data member, and, as a result,\nall other data members were automatically deactivated,\nand you can no longer use them after you instantiate the object.\n\nYou can activate another data member by completely redefining the entire enum object.\nIn the example below, I initially use the `azure` data member. But then, I redefine the\n`target` object to use a new `LakeTarget` object, which uses the `google` data member.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar target = LakeTarget {\n    .azure = AzureBlob.init()\n};\ntarget = LakeTarget {\n    .google = GoogleGCP.init()\n};\n```\n:::\n\n\n\n\nA curious fact about union types, is that, at first, you cannot use them in switch statements (which were presented in @sec-switch).\nIn other words, if you have an object of type `LakeTarget` for example, you cannot give this object\nas input to a switch statement.\n\nBut what if you really need to do so? What if you actually need to\nprovide an \"union object\" to a switch statement? The answer to this question relies on another special type in Zig,\nwhich are the *tagged unions*. To create a tagged union, all you have to do is to add\nan enum type into your union declaration.\n\nAs an example of a tagged union in Zig, take the `Registry` type exposed\nbelow. This type comes from the\n[`grammar.zig` module](https://github.com/ziglang/zig/blob/30b4a87db711c368853b3eff8e214ab681810ef9/tools/spirv/grammar.zig)[^grammar]\nfrom the Zig repository. This union type lists different types of registries.\nBut notice this time, the use of `(enum)` after the `union` keyword. This is what makes\nthis union type a tagged union. By being a tagged union, an object of this `Registry` type\ncan be used as input in a switch statement. This is all you have to do. Just add `(enum)`\nto your `union` declaration, and you can use it in switch statements.\n\n[^grammar]: <https://github.com/ziglang/zig/blob/30b4a87db711c368853b3eff8e214ab681810ef9/tools/spirv/grammar.zig>.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const Registry = union(enum) {\n    core: CoreRegistry,\n    extension: ExtensionRegistry,\n};\n```\n:::\n",
-    "supporting": [
-      "09-error-handling_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Error handling and unions {#sec-error-handling}\n\nIn this chapter, I want to discuss how error handling is done in Zig.\nWe already briefly learned about one of the available strategies to handle errors in Zig,\nwhich is the `try` keyword presented in @sec-main-file. But we still haven't learned about\nthe other methods, such as the `catch` keyword.\nI also want to discuss in this chapter how union types are created in Zig.\n\n## Learning more about errors in Zig\n\nBefore we get into how error handling is done, we need to learn more about what errors are in Zig.\nAn error is actually a value in Zig [@zigoverview]. In other words, when an error occurs inside your Zig program,\nit means that somewhere in your Zig codebase, an error value is being generated.\nAn error value is similar to any integer value that you create in your Zig code.\nYou can take an error value and pass it as input to a function,\nand you can also cast (or coerce) it into a different type of an error value.\n\nThis have some similarities with exceptions in C++ and Python.\nBecause in C++ and Python, when an exception happens inside a `try` block,\nyou can use a `catch` block (in C++) or an `except` block (in Python)\nto capture the exception produced in the `try` block,\nand pass it to functions as an input.\n\nHowever, error values in Zig are treated very differently than exceptions.\nFirst, you cannot ignore error values in your Zig code. Meaning that, if an error\nvalue appears somewhere in your source code, this error value must be explicitly handled in some way.\nThis also means that you cannot discard error values by assigning them to an underscore,\nas you could do with normal values and objects.\n\nTake the source code below as an example. Here we are trying to open a file that does not exist\nin my computer, and as a result, an obvious error value of `FileNotFound` is returned from the `openFile()`\nfunction. But because I'm assigning the result of this function to an underscore, I end up\ntrying to discard an error value.\n\nThe `zig` compiler detects this mistake, and raises a compile\nerror telling me that I'm trying to discard an error value.\nIt also adds a note message that suggests the use of `try`,\n`catch` or an if statement to explicitly handle this error value\nThis note is reinforcing that every possible error value must be explicitly handled in Zig.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst dir = std.fs.cwd();\n_ = dir.openFile(\"doesnt_exist.txt\", .{});\n```\n:::\n\n\n```\nt.zig:8:17: error: error set is discarded\nt.zig:8:17: note: consider using 'try', 'catch', or 'if'\n```\n\n\n### Returning errors from functions\n\nAs we described in @sec-main-file, when we have a function that might return an error\nvalue, this function normally includes an exclamation mark (`!`) in its return type\nannotation. The presence of this exclamation mark indicates that this function might\nreturn an error value as result, and, the `zig` compiler forces you to always handle explicitly\nthe case of this function returning an error value.\n\nTake a look at the `print_name()` function below. This function might return an error in the `stdout.print()` function call,\nand, as a consequence, its return type (`!void`) includes an exclamation mark in it.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_name() !void {\n    const stdout = std.getStdOut().writer();\n    try stdout.print(\"My name is Pedro!\", .{});\n}\n```\n:::\n\n\nIn the example above, we are using the exclamation mark to tell the `zig` compiler\nthat this function might return some error. But which error exactly is returned from\nthis function? For now, we are not specifying a specific error value. For now,\nwe only know that some error value (whatever it is) might be returned.\n\nBut in fact, you can (if you want to) specify clearly which exact error values\nmight be returned from this function. There are lot of examples of\nthis in the Zig Standard Library. Take this `fill()` function from\nthe `http.Client` module as an example. This function returns\neither a error value of type `ReadError`, or `void`.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn fill(conn: *Connection) ReadError!void {\n    // The body of this function ...\n}\n```\n:::\n\n\nThis idea of specifying the exact error values that you expect to be returned\nfrom the function is interesting. Because they automatically become some sort of documentation\nof your function, and also, this allows the `zig` compiler to perform some extra checks over\nyour code. Because the compiler can check if there is any other type of error value\nthat is being generated inside your function, and, that it's not being accounted\nfor in this return type annotation.\n\nAnyway, you can list the types of errors that can be returned from the function\nby listing them on the left side of the exclamation mark. While the valid values\nstay on the right side of the exclamation mark. So the syntax format become:\n\n```\n<error-value>!<valid-value>\n```\n\n\n### Error sets\n\nBut what about when we have a single function that might return different types of errors?\nWhen you have such a function, you can list\nall of these different types of errors that can be returned from this function,\nthrough a structure in Zig that we call of an *error set*.\n\nAn error set is a special case of a union type. It's a union that contains error values in it.\nNot all programming languages have a notion of a \"union object\".\nBut in summary, a union is just a set of data types.\nUnions are used to allow an object to have multiple data types.\nFor example, a union of `x`, `y` and `z`, means that\nan object can be either of type `x`, or type `y` or type `z`.\n\nWe are going to talk in more depth about unions in @sec-unions.\nBut you can write an error set by writing the keyword `error` before\na pair of curly braces, then you list the error values that can be\nreturned from the function inside this pair of curly braces.\n\nTake the `resolvePath()` function below as an example, which comes from the\n`introspect.zig` module of the Zig Standard Library. We can see in its return type annotation, that this\nfunction return either: 1) a valid slice of `u8` values (`[]u8`); or, 2) one of the three different\ntypes of error values listed inside the error set (`OutOfMemory`, `Unexpected`, etc.).\nThis is an usage example of an error set.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn resolvePath(\n    ally: mem.Allocator,\n    p: []const u8,\n) error{\n    OutOfMemory,\n    CurrentWorkingDirectoryUnlinked,\n    Unexpected,\n}![]u8 {\n    // The body of the function ...\n}\n```\n:::\n\n\n\nThis is a valid way of annotating the return value of a Zig function. But, if you navigate through\nthe modules that composes the Zig Standard Library, you will notice that, for the majority of cases,\nthe programmers prefer to give a descriptive name to this error set, and then, use this name (or this \"label\")\nof the error set in the return type annotation, instead of using the error set directly.\n\nWe can see that in the `ReadError` error set that we showed earlier in the `fill()` function,\nwhich is defined in the `http.Client` module.\nSo yes, I presented the `ReadError` as if it was just a standard and single error value, but in fact,\nit's an error set defined in the `http.Client` module, and therefore, it actually represents\na set of different error values that might happen inside the `fill()` function.\n\n\nTake a look at the `ReadError` definition reproduced below. Notice that we are grouping all of these\ndifferent error values into a single object, and then, we use this object into the return type annotation of the function.\nLike the `fill()` function that we showed earlier, or, the `readvDirect()` function from the same module,\nwhich is reproduced below.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const ReadError = error{\n    TlsFailure,\n    TlsAlert,\n    ConnectionTimedOut,\n    ConnectionResetByPeer,\n    UnexpectedReadFailure,\n    EndOfStream,\n};\n// Some lines of code\npub fn readvDirect(\n        conn: *Connection,\n        buffers: []std.posix.iovec\n    ) ReadError!usize {\n    // The body of the function ...\n}\n```\n:::\n\n\nSo, an error set is just a convenient way of grouping a set of\npossible error values into a single object, or a single type of an error value.\n\n\n### Casting error values\n\nLet's suppose you have two different error sets, named `A` and `B`.\nIf error set `A` is a superset of error set `B`, then, you can cast (or coerce)\nerror values from `B` into error values of `A`.\n\nError sets are just a set of error values. So, if the error set `A`\ncontains all error values from the error set `B`, then `A`\nbecomes a superset of `B`. You could also say\nthat the error set `B` is a subset of error set `A`.\n\nThe example below demonstrates this idea. Because `A` contains all\nvalues from `B`, `A` is a superset of `B`.\nIn math notation, we would say that $A \\supset B$.\nAs a consequence, we can give an error value from `B` as input to the `cast()`\nfunction, and, implicitly cast this input into the same error value, but from the `A` set.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst A = error{\n    ConnectionTimeoutError,\n    DatabaseNotFound,\n    OutOfMemory,\n    InvalidToken,\n};\nconst B = error {\n    OutOfMemory,\n};\n\nfn cast(err: B) A {\n    return err;\n}\n\ntest \"coerce error value\" {\n    const error_value = cast(B.OutOfMemory);\n    try std.testing.expect(\n        error_value == A.OutOfMemory\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file1f7f62fdbe33.test.coerce error value...OKA\n  All 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n## How to handle errors\n\nNow that we learned more about what errors are in Zig,\nlet's discuss the available strategies to handle these errors,\nwhich are:\n\n- `try` keyword;\n- `catch` keyword;\n- an if statement;\n- `errdefer` keyword;\n\n\n\n### What `try` means?\n\nAs I described over the previous sections, when we say that an expression might\nreturn an error, we are basically referring to an expression that have\na return type in the format `!T`.\nThe `!` indicates that this expression returns either an error value, or a value of type `T`.\n\nIn @sec-main-file, I presented the `try` keyword and where to use it.\nBut I did not talked about what exactly this keyword does to your code,\nor, in other words, I have not explained yet what `try` means in your code.\n\nIn essence, when you use the `try` keyword in an expression, you are telling\nthe `zig` compiler the following: \"Hey! Execute this expression for me,\nand, if this expression return an error, please, return this error for me\nand stop the execution of my program. But if this expression return a valid\nvalue, then, return this value, and move on\".\n\nIn other words, the `try` keyword is essentially, a strategy to enter in panic mode, and stop\nthe execution of your program in case an error occurs.\nWith the `try` keyword, you are telling the `zig` compiler, that stopping the execution\nof your program is the most reasonable strategy to take if an error occurs\nin that particular expression.\n\n### The `catch` keyword\n\nOk, now that we understand properly what `try` means, let's discuss `catch` now.\nOne important detail here, is that you can use `try` or `catch` to handle your errors,\nbut you **cannot use `try` and `catch` together**. In other words, `try` and `catch`\nare different and completely separate strategies in the Zig language.\n\nThis is uncommon, and different than what happens in other languages. Most\nprogramming languages that adopts the *try catch* pattern (such as C++, R, Python, Javascript, etc.), normally use\nthese two keywords together to form the complete logic to\nproperly handle the errors.\nAnyway, Zig tries a different approach in the *try catch* pattern.\n\nSo, we learned already about what `try` means, and we also known that both\n`try` and `catch` should be used alone, separate from each other. But\nwhat exactly `catch` do in Zig? With `catch`, we can construct a block of\nlogic to handle the error value, in case it happens in the current expression.\n\nLook at the code example below. Once again, we go back to the previous\nexample where we were trying to open a file that doesn't exist in my computer,\nbut this time, I use `catch` to actually implement a logic to handle the error, instead of\njust stopping the execution right away.\n\nMore specifically, in this example, I'm using a logger object to record some logs into\nthe system, before I return the error, and stop the execution of the program. For example,\nthis could be some part of the codebase of a complex system that I do not have full control over,\nand I want to record these logs before the program crashes, so that I can debug it later\n(e.g. maybe I cannot compile the full program, and properly debug it with a debugger. So, these logs might\nbe a valid strategy to surpass this barrier).\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst dir = std.fs.cwd();\nconst file = dir.openFile(\n    \"doesnt_exist.txt\", .{}\n) catch |err| {\n    logger.record_context();\n    logger.log_error(err);\n    return err;\n};\n```\n:::\n\n\n\nTherefore, we use `catch` to create a block of expressions that will handle the error.\nI can return the error value from this block of expressions, like I did in the above example,\nwhich, will make the program enter in panic mode, and, stop the execution.\nBut I could also, return a valid value from this block of code, which would\nbe stored in the `file` object.\n\nNotice that, instead of writing the keyword before the expression that might return the error,\nlike we do with `try`, we write `catch` after the expression. We can open the pair of pipes (`|`),\nwhich captures the error value returned by the expression, and makes\nthis error value available in the scope of the `catch` block as the object named `err`.\nIn other words, because I wrote `|err|` in the code, I can access the error value\nreturned by the expression, by using the `err` object.\n\nAlthough this being the most common use of `catch`, you can also use this keyword\nto handle the error in a \"default value\" style. That is, if the expression returns\nan error, we use the default value instead. Otherwise, we use the valid value returned\nby the expression.\n\nThe Zig official language reference, provides a great example of this \"default value\"\nstrategy with `catch`. This example is reproduced below. Notice that we are trying to parse\nsome unsigned integer from a string object named `str`. In other words, this function\nis trying to transform an object of type `[]const u8` (i.e., an array of characters, a string, etc.)\ninto an object of type `u64`.\n\nBut this parsing process done by the function `parseU64()` may fail, resulting in a runtime error.\nThe `catch` keyword used in this example provides an alternative value (13) to be used in case\nthis `parseU64()` function raises an error. So, the expression below essentially means:\n\"Hey! Please, parse this string into a `u64` for me, and store the results into the\nobject `number`. But, if an error occurs, then, use the value `13` instead\".\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number = parseU64(str, 10) catch 13;\n```\n:::\n\n\nSo, at the end of this process, the object `number` will contain either a `u64` integer\nthat was parsed successfully from the input string `str`, or, if an error occurs in the\nparsing process, it will contain the `u64` value `13` that was provided by the `catch`\nkeyword as the \"default\", or, the \"alternative\" value.\n\n\n\n### Using if statements\n\nNow, you can also use if statements to handle errors in your Zig code.\nIn the example below, I'm reproducing the previous example, where\nwe try to parse an integer value from an input string with a function\nnamed `parseU64()`.\n\nWe execute the expression inside the \"if\". If this expression returns an\nerror value, the \"if branch\" (or, the \"true branch\") of the if statement is not executed.\nBut if this expression returns a valid value instead, then, this value is unwrapped\ninto the `number` object.\n\nThis means that, if the `parseU64()` expression returns a valid value, this value becomes available\ninside the scope of this \"if branch\" (i.e., the \"true branch\") through the object that we listed inside the pair\nof pipe character (`|`), which is the object `number`.\n\nIf an error occurs, we can use an \"else branch\" (or the \"false branch\") of the if statement\nto handle the error. In the example below, we are using the `else` in the if statement\nto unwrap the error value (that was returned by `parseU64()`) into the `err` object,\nand handle the error.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (parseU64(str, 10)) |number| {\n    // do something with `number` here\n} else |err| {\n    // handle the error value.\n}\n```\n:::\n\n\nNow, if the expression that you are executing returns different types of error values,\nand you want to take a different action in each of these types of error values, the\n`try` and `catch` keywords, and the if statement strategy, becomes limited.\n\nFor this type of situation, the official documentation of the language suggests\nthe use of a switch statement together with an if statement [@zigdocs].\nThe basic idea is, to use the if statement to execute the expression, and\nuse the \"else branch\" to pass the error value to a switch statement, where\nyou define a different action for each type of error value that might be\nreturned by the expression executed in the if statement.\n\nThe example below demonstrates this idea. We first try to add (or register) a set of\ntasks to a queue. If this \"registration process\" occurs well, we then try\nto distribute these tasks across the workers of our system. But\nif this \"registration process\" returns an error value, we then use a switch\nstatement in the \"else branch\" to handle each possible error value.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (add_tasks_to_queue(&queue, tasks)) |_| {\n    distribute_tasks(&queue);\n} else |err| switch (err) {\n    error.InvalidTaskName => {\n        // do something\n    },\n    error.TimeoutTooBig => {\n        // do something\n    },\n    error.QueueNotFound => {\n        // do something\n    },\n    // and all the other error options ...\n}\n```\n:::\n\n\n\n### The `errdefer` keyword {#sec-errdefer2}\n\nA common pattern in C programs in general, is to clean resources when an error occurs during\nthe execution of the program. In other words, one common way to handle errors, is to perform\n\"cleanup actions\" before we exit our program. This guarantees that a runtime error does not make\nour program to leak resources of the system.\n\n\nThe `errdefer` keyword is a tool to perform such \"cleanup actions\" in hostile situations.\nThis keyword is commonly used to clean (or to free) allocated resources, before the execution of our program\ngets stopped because of an error value being generated.\n\nThe basic idea is to provide an expression to the `errdefer` keyword. Then,\n`errdefer` executes this expression if, and only if, an error occurs\nduring the execution of the current scope.\nIn the example below, we are using an allocator object (that we have presented in @sec-allocators)\nto create a new `User` object. If we are successful in creating and registering this new user,\nthis `create_user()` function will return this new `User` object as its return value.\n\nHowever, if for some reason, an error value is generated by some expression\nthat is after the `errdefer` line, for example, in the `db.add(user)` expression,\nthe expression registered by `errdefer` gets executed before the error value is returned\nfrom the function, and before the program enters in panic mode and stops the\ncurrent execution.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn create_user(db: Database, allocator: Allocator) !User {\n    const user = try allocator.create(User);\n    errdefer allocator.destroy(user);\n\n    // Register new user in the Database.\n    _ = try db.register_user(user);\n    return user;\n}\n```\n:::\n\n\nBy using `errdefer` to destroy the `user` object that we have just created,\nwe guarantee that the memory allocated for this `user` object\ngets freed, before the execution of the program stops.\nBecause if the expression `try db.add(user)` returns an error value,\nthe execution of our program stops, and we lose all references and control over the memory\nthat we have allocated for the `user` object.\nAs a result, if we do not free the memory associated with the `user` object before the program stops,\nwe cannot free this memory anymore. We simply lose our chance to do the right thing.\nThat is why `errdefer` is essential in this situation.\n\nJust to state clearly the differences between `defer` and `errdefer`\n(which I described in @sec-defer and @sec-errdefer1), it might be worth\nto discuss the subject a bit further. You might still have the question\n\"why use `errdefer` if we can use `defer` instead?\" in your mind.\n\nAlthough being similar, the key difference between `errdefer` and `defer` keyword\nis when the provided expression gets executed.\nThe `defer` keyword always execute the provided expression at the end of the\ncurrent scope, no matter how your code exits this scope.\nIn contrast, `errdefer` executes the provided expression only when an error occurs in the\ncurrent scope.\n\nThis becomes important if a resource that you allocate in the\ncurrent scope gets freed later in your code, in a different scope.\nThe `create_user()` functions is an example of this. If you think\nclosely about this function, you will notice that this function returns\nthe `user` object as the result.\n\nIn other words, the allocated memory for the `user` object does not get\nfreed inside the `create_user()` function, if it returns successfully.\nSo, if an error does not occur inside this function, the `user` object\nis returned from the function, and probably, the code that runs after\nthis `create_user()` function will be responsible for freeing\nthe memory of the `user` object.\n\nBut what if an error occurs inside the `create_user()` function? What happens then?\nThis would mean that the execution of your code would stop in this `create_user()`\nfunction, and, as a consequence, the code that runs after this `create_user()`\nfunction would simply not run, and, as a result, the memory of the `user` object\nwould not be freed before your program stops.\n\nThis is the perfect scenario for `errdefer`. We use this keyword to guarantee\nthat our program will free the allocated memory for the `user` object,\neven if an error occurs inside the `create_user()` function.\n\nIf you allocate and free some memory for an object inside the same scope, then,\njust use `defer` and be happy, i.e., `errdefer` have no use for you in such situation.\nBut if you allocate some memory in a scope A, but you only free this memory\nlater, in a scope B for example, then, `errdefer` becomes useful to avoid leaking memory\nin sketchy situations.\n\n\n\n## Union type in Zig {#sec-unions}\n\nA union type defines a set of types that an object can be. It's like a list of\noptions. Each option is a type that an object can assume. Therefore, unions in Zig\nhave the same meaning, or, the same role as unions in C. They are used for the same purpose.\nYou could also say that unions in Zig produces a similar effect to\n[using `typing.Union` in Python](https://docs.python.org/3/library/typing.html#typing.Union)[^pyunion].\n\n[^pyunion]: <https://docs.python.org/3/library/typing.html#typing.Union>\n\nFor example, you might be creating an API that sends data to a data lake, hosted\nin some private cloud infrastructure. Suppose you have created different structs in your codebase,\nto store the necessary information that you need, in order to connect to the services of\neach mainstream data lake service (Amazon S3, Azure Blob, etc.).\n\nNow, suppose you also have a function named `send_event()` that receives an event as input,\nand, a target data lake, and it sends the input event to the data lake specified in the\ntarget data lake argument. But this target data lake could be any of the three mainstream data lakes\nservices (Amazon S3, Azure Blob, etc.). Here is where an union can help you.\n\nThe union `LakeTarget` defined below allows the `lake_target` argument of `send_event()`\nto be either an object of type `AzureBlob`, or type `AmazonS3`, or type `GoogleGCP`.\nThis union allows the `send_event()` function to receive an object of any of these three types\nas input in the `lake_target` argument.\n\nRemember that each of these three types (`AmazonS3`, `GoogleGCP` and `AzureBlob`)\nare separate structs that we have defined in our source code. So, at first glance,\nthey are separate data types in our source code. But is the `union` keyword that\nunifies them into a single data type called `LakeTarget`.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst LakeTarget = union {\n    azure: AzureBlob,\n    amazon: AmazonS3,\n    google: GoogleGCP,\n};\n\nfn send_event(\n    event: Event,\n    lake_target: LakeTarget\n) bool {\n    // body of the function ...\n}\n```\n:::\n\n\nAn union definition is composed by a list of data members. Each data member is of a specific data type.\nIn the example above, the `LakeTarget` union have three data members (`azure`, `amazon`, `google`).\nWhen you instantiate an object that uses an union type, you can only use one of its data members\nin this instantiation.\n\nYou could also interpret this as: only one data member of an union type can be activated at a time, the other data\nmembers remain deactivated and unaccessible. For example, if you create a `LakeTarget` object that uses\nthe `azure` data member, you can no longer use or access the data members `google` or `amazon`.\nIt's like if these other data members didn't exist at all in the `LakeTarget` type.\n\nYou can see this logic in the example below. Notice that, we first instantiate the union\nobject using the `azure` data member. As a result, this `target` object contains only\nthe `azure` data member inside of it. Only this data member is active in this object.\nThat is why the last line in this code example is invalid. Because we are trying to instantiate the data member\n`google`, which is currently inactive for this `target` object, and as a result, the program\nenters in panic mode warning us about this mistake through a loud error message.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar target = LakeTarget {\n    .azure = AzureBlob.init()\n};\n// Only the `azure` data member exist inside\n// the `target` object, and, as a result, this\n// line below is invalid:\ntarget.google = GoogleGCP.init();\n```\n:::\n\n\n```\nthread 2177312 panic: access of union field 'google' while\n    field 'azure' is active:\n    target.google = GoogleGCP.init();\n          ^\n```\n\nSo, when you instantiate an union object, you must choose one of the data types (or, one of the data members)\nlisted in the union type. In the example above, I choose to use the `azure` data member, and, as a result,\nall other data members were automatically deactivated,\nand you can no longer use them after you instantiate the object.\n\nYou can activate another data member by completely redefining the entire enum object.\nIn the example below, I initially use the `azure` data member. But then, I redefine the\n`target` object to use a new `LakeTarget` object, which uses the `google` data member.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar target = LakeTarget {\n    .azure = AzureBlob.init()\n};\ntarget = LakeTarget {\n    .google = GoogleGCP.init()\n};\n```\n:::\n\n\nA curious fact about union types, is that, at first, you cannot use them in switch statements (which were presented in @sec-switch).\nIn other words, if you have an object of type `LakeTarget` for example, you cannot give this object\nas input to a switch statement.\n\nBut what if you really need to do so? What if you actually need to\nprovide an \"union object\" to a switch statement? The answer to this question relies on another special type in Zig,\nwhich are the *tagged unions*. To create a tagged union, all you have to do is to add\nan enum type into your union declaration.\n\nAs an example of a tagged union in Zig, take the `Registry` type exposed\nbelow. This type comes from the\n[`grammar.zig` module](https://github.com/ziglang/zig/blob/30b4a87db711c368853b3eff8e214ab681810ef9/tools/spirv/grammar.zig)[^grammar]\nfrom the Zig repository. This union type lists different types of registries.\nBut notice this time, the use of `(enum)` after the `union` keyword. This is what makes\nthis union type a tagged union. By being a tagged union, an object of this `Registry` type\ncan be used as input in a switch statement. This is all you have to do. Just add `(enum)`\nto your `union` declaration, and you can use it in switch statements.\n\n[^grammar]: <https://github.com/ziglang/zig/blob/30b4a87db711c368853b3eff8e214ab681810ef9/tools/spirv/grammar.zig>.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub const Registry = union(enum) {\n    core: CoreRegistry,\n    extension: ExtensionRegistry,\n};\n```\n:::\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/10-stack-project/execute-results/epub.json b/_freeze/Chapters/10-stack-project/execute-results/epub.json
deleted file mode 100644
index 8c071b38..00000000
--- a/_freeze/Chapters/10-stack-project/execute-results/epub.json
+++ /dev/null
@@ -1,21 +0,0 @@
-{
-  "hash": "801c378f39cbcf646c40a137880aa3b8",
-  "result": {
-    "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Project 3 - Building a stack data structure\n\nIn this chapter we are going to implement a stack data structure as our next small project\nin this book. Implementing basic data structures in any language is kind of a\n\"kindergarten task\" (if this term even exist) in computer science (CS), because\nwe normally learn and implement them in the first semesters of CS.\n\nBut this is actually good! Since this should be a very easy task, we don't need much to explain\nwhat a stack is, then, we can concentrate on what is really important here, which is learning\nhow the concept of \"generics\" is implemented in the Zig language, and how one of the key\nfeatures of Zig, which is comptime, works, and use the stack data structure to demonstrate\nthese concepts on the fly.\n\nBut before we get into building the stack data structure, we first need to understand\nwhat the `comptime` keyword does to your code, and after that, we also need to learn about\nhow generics work in Zig.\n\n\n## Understanding `comptime` in Zig {#sec-comptime}\n\nOne of the key features of Zig is `comptime`. This keyword introduces a whole\nnew concept and paradigm, that is tightly connected with the compilation process.\nIn @sec-compile-time we have described the importance and the role that \"compile-time versus runtime\"\nplays into Zig. In that section, we learned that the rules applied to a value/object change\na lot depending on whether this value is known at compile-time, or just at runtime.\n\nThe `comptime` keyword is strongly related to these two spaces in time (compile-time and runtime).\nLet's quickly recap the differences. Compile-time is the period of time when your\nZig source code is being compiled by the `zig` compiler, while the runtime is\nthe period of time when your Zig program is being executed, i.e., when we execute\nthe binary files that were generated by the `zig` compiler.\n\nThere are three ways in which you can apply the `comptime` keyword, which are:\n\n- apply `comptime` on a function argument.\n- apply `comptime` on an object.\n- apply `comptime` on a block of expressions.\n\n\n\n### Applying over a function argument\n\nWhen you apply the `comptime` keyword on a function argument, you are saying to the `zig` compiler\nthat the value assigned to that particular function argument must be known at compile-time.\nWe explained in detail in @sec-compile-time what exactly \"value known at compile-time\" means. So\nif you have any doubts about this idea, refer back to that section.\n\nNow let's think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement\nto that particular function argument. If the programmer accidentally tries to give a value to this\nfunction argument that is not known at compile time, the `zig` compiler will notice this problem, and\nas a consequence, it will raise a compilation error saying that it cannot compile your program. Because\nyou are providing a value that is \"runtime known\" to a function argument that must be \"compile-time known\".\n\nTake a look at this very simple example below, where we define a `twice()` function, that simply\ndoubles the input value named `num`. Notice that we use the `comptime` keyword before the name\nof the function argument. This keyword is marking the function argument `num` as a \"comptime argument\".\n\nThat is a function argument whose value must be compile-time known. This is why the expression\n`twice(5678)` is valid, and no compilation errors are raised. Because the value `5678`\nis compile-time known, so this is the expected behaviour for this function.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file3f5922d93418.test.test comptime...OKAll 1 \n   tests passed.\n```\n\n\n:::\n:::\n\n\n\nBut what if we provide a number that is not compile-time known to this function?\nFor example, your program might receive some input from the user through the `stdin`\nchannel of your system. This input from the user might be many different things,\nand cannot be predicted at compile-time. These circumstances make this \"input\nfrom the user\" a value that is runtime-known only.\n\nIn the example below, this \"input from the user\" is initially received as a string,\nwhich is then parsed and transformed into a integer value, and the result of this operation\nis stored inside the `n` object.\n\nBecause the \"input of the user\" is known only at runtime, the value of the object `n` is determined only at runtime.\nAs consequence, we cannot provide this object as input to the `twice()` function.\nThe `zig` compiler will not allow it, because we marked\nthe `num` argument as a \"comptime argument\". That is why the `zig` compiler raises\nthe compile-time error exposed below:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\n\npub fn main() !void {\n    var buffer: [5]u8 = .{ 0, 0, 0, 0, 0 };\n    const stdout = std.io.getStdOut().writer();\n    const stdin = std.io.getStdIn().reader();\n    _ = try stdout.write(\"Please write a 4-digit integer number\\n\");\n    _ = try stdin.readUntilDelimiter(&buffer, '\\n');\n\n    try stdout.print(\"Input: {s}\", .{buffer});\n    const n: u32 = try std.fmt.parseInt(\n        u32, buffer[0 .. buffer.len - 1], 10\n    );\n    const twice_result = twice(n);\n    try stdout.print(\"Result: {d}\\n\", .{twice_result});\n}\n```\n:::\n\n\n\n```\nt.zig:12:16: error: unable to resolve comptime value\n    const twice_result = twice(n);\n                               ^\n```\n\nComptime arguments are frequently used on functions that return some sort\nof generic structure. In fact, `comptime` is the essence (or the basis) to make generics in Zig.\nWe are going to talk more about generics in @sec-generics.\n\nFor now, let's take a look at this code example from @karlseguin_generics. You\ncan see that this `IntArray()` function has one argument named `length`.\nThis argument is marked as comptime, and receives a value of type `usize` as input. So the value given to this argument\nmust be compile-time known.\nWe can also see that this function returns an array of `i64` values as output.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n```\n:::\n\n\n\nNow, the key component of this function is the `length` argument. This argument\nis used to determine the size of the array that is produced by the function. Let's\nthink about the consequences of that. If the size of the array is dependent on\nthe value assigned to the `length` argument, this means that the data type of the\noutput of the function depends on the value of this `length` argument.\n\nLet this statement sink for a bit in your mind. As I described in @sec-root-file,\nZig is a strongly-typed language, especially on function declarations.\nSo every time we write a function in Zig, we have to annotate the data type of\nthe value returned by the function. But how can we do that, if this data type\ndepends on the value given to the argument of the function?\n\nThink about this for a second. If `length` is equal to 3 for example, then, the\nreturn type of the function is `[3]i64`. But if `length` is equal to 40, then,\nthe return type becomes `[40]i64`. At this point the `zig` compiler would be confused,\nand raise a compilation error, saying something like this:\n\n> Hey! You have annotated that this function should return a `[3]i64` value, but I got a `[40]i64` value instead! This doesn't look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when\nthe `type` keyword comes in. This `type` keyword is basically saying to the\n`zig` compiler that this function will return some data type as output, but it doesn't know yet\nwhat exactly data type that is. We will talk more about this in @sec-generics.\n\n\n\n### Applying over an expression\n\nWhen you apply the `comptime` keyword over an expression, then, it is guaranteed that the `zig` compiler will\nexecute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time\n(e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the `zig` compiler\nwill raise a compilation error.\n\nTake this example from the official documentation of Zig [@zigdocs]. We\nare executing the same `fibonacci()` function both at runtime, and, at compile-time.\nThe function is executed by default at runtime, but because we use the `comptime`\nkeyword in the second \"try expression\", this expression is executed at compile-time.\n\nThis might be a bit confusing for some people. Yes! When I say that this expression\nis executed at compile-time, I mean that this expression is compiled and executed\nwhile the `zig` compiler is compiling your Zig source code.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file3f596129a9ee.test.fibonacci...OKAll 1 test\n  ts passed.\n```\n\n\n:::\n:::\n\n\n\nA lot of your Zig source code might be potentially executed at compile-time,\nbecause the `zig` compiler can figure out the output of some expressions.\nEspecially if these expressions depend only on compile-time known values.\nWe have talked about this in @sec-compile-time.\n\nBut when you use the `comptime` keyword on an expression, there is no \"it might be executed\nat compile-time\" anymore. With the `comptime` keyword you are ordering the `zig` compiler\nto execute this expression at compile-time. You are imposing this rule, it is guaranteed\nthat the compiler will always execute it at compile-time. Or, at least, the compiler\nwill try to execute it. If the compiler cannot execute the expression for whatever reason,\nthe compiler will raise a compilation error.\n\n\n### Applying over a block\n\nBlocks were described in @sec-blocks. When you apply the `comptime` keyword to a\nblock of expressions, you get essentially the same effect as when you apply this keyword to\na single expression. That is, the entire block of expressions is executed at\ncompile-time by the `zig` compiler.\n\nIn the example below, we mark the block labeled of `blk` as a comptime block,\nand, therefore, the expressions inside this block are executed at compile-time.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file3f5947d42e1f.test.fibonacci in a block...O\n  OKAll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n## Introducing Generics {#sec-generics}\n\nFirst of all, what is a generic? Generic is the idea to allow a type\n(`f64`, `u8`, `u32`, `bool`, and also, user-defined types, like the `User` struct\nthat we defined in @sec-structs-and-oop) to be a parameter to methods, classes and\ninterfaces [@geeks_generics]. In other words, a \"generic\" is a class (or a method) that can work\nwith multiple data types.\n\nFor example, in Java, generics are created through the operator `<>`. With this operator,\na Java class is capable of receiving a data type as input, and therefore, the class can fit\nits features according to this input data type.\nAs another example, generics in C++ are supported through the concept of templates.\nClass templates in C++ are generics.\n\nIn Zig, generics are implemented through `comptime`. The `comptime` keyword\nallows us to collect a data type at compile time, and pass this data type as\ninput to a piece of code.\n\n\n### A generic function {#sec-generic-fun}\n\nTake the `max()` function exposed below as a first example.\nThis function is essentially a \"generic function\".\nIn this function, we have a comptime function argument named `T`.\nNotice that this `T` argument has a data type of `type`. Weird right? This `type` keyword is the\n\"father of all types\", or, \"the type of types\" in Zig.\n\nBecause we have used this `type` keyword in the `T` argument, we are telling\nthe `zig` compiler that this `T` argument will receive some data type as input.\nAlso notice the use of the `comptime` keyword in this argument.\nAs I described in @sec-comptime, every time you use this keyword in a function argument,\nthis means that the value of this argument must be known at compile-time.\nThis makes sense, right? Because there is no data type that is not known at compile-time.\n\nThink about this. Every data type that you will ever write is always\nknown at compile-time. Especially because data types are an essential\ninformation for the compiler to actually compile your source code.\nHaving this in mind, makes sense to mark this argument as a comptime argument.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\n```\n:::\n\n\n\nAlso notice that the value of the `T` argument is actually used\nto define the data type of the other arguments in the function, `a` and `b`, and also at the\nreturn type annotation of the function.\nThat is, the data type of these arguments (`a` and `b`), and, the return data type of the function itself,\nare determined by the input value given to the `T` argument.\n\nAs a result, we have a generic function that works with different data types.\nFor example, I can provide `u8` values to this `max()` function, and it will work as expected.\nBut if I provide `f64` values instead, it will also work as expected.\nWithout a generic function, I would have to write a different `max()` function\nfor each data type I wanted to use.\nThis generic function provides a very useful shortcut for us.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\ntest \"test max\" {\n    const n1 = max(u8, 4, 10);\n    std.debug.print(\"Max n1: {d}\\n\", .{n1});\n    const n2 = max(f64, 89.24, 64.001);\n    std.debug.print(\"Max n2: {d}\\n\", .{n2});\n}\n```\n:::\n\n\n\n```\nMax n1: 10\nMax n2: 89.24\n```\n\n\n### A generic data structure {#sec-generic-struct}\n\nEvery data structure that you find in the Zig Standard Library (e.g. `ArrayList`, `HashMap`, etc.)\nis essentially a generic data structure.\nThese data structures are generic in the sense that they work with any data type you want.\nYou just say which is the data type of the values that are going to be stored in this data\nstructure, and they just work as expected.\n\nA generic data structure in Zig is how you replicate a generic class from Java,\nor, a class template from C++. But you may ask yourself: how do we build a\ngeneric data structure in Zig?\n\nThe basic idea is to write a generic function that creates the data structure definition\nfor the specific type we want. In other words, this generic function behaves as a \"factory of data structures\".\nThe generic function outputs the `struct` definition that defines this data structure for a\nspecific data type.\n\nTo create such function, we need to add a comptime argument to this function that receives a data type\nas input. We already learned how to do this in the previous section (@sec-generic-fun).\nI think the best way to demonstrate how to create a generic data structure is to actually write one.\nThis where we go into our next small project in this book. This one is a very small project,\nwhich is to write a generic stack data structure.\n\n\n\n\n## What is a stack? {#sec-what-stack}\n\nA stack data structure is a structure that follows a LIFO (*last in, first out*) principle.\nOnly two operations are normally supported in a stack data structure, which are `push` and `pop`.\nThe `push` operation is used to add new values to the stack, while `pop` is used to remove\nvalues from the stack.\n\nWhen people try to explain how the stack data structure works, the most common analogy\nthat they use is a stack of plates. Imagine that you have a stack of plates,\nfor example, a stack of 10 plates in your table. Each plate represents a value that\nis currently stored in this stack.\n\nWe begin with a stack of 10 different values, or 10 different plates. Now, imagine that you want to\nadd a new plate (or a new value) to this stack, which translates to the `push` operation.\nYou would add this plate (or this value) by just putting the new plate\non the top of the stack. Then, you would increase the stack to 11 plates.\n\nBut how would you remove plates (or remove values) from this stack (a.k.a. the `pop` operation) ?\nTo do that, we would have to remove the plate on the top of the stack, and, as a result, we would\nhave, once again, 10 plates in the stack.\n\nThis demonstrates the LIFO concept, because the first plate in the stack, which is the plate\nin the bottom of the stack, is always the last plate to get out of the stack. Think about it. In order\nto remove this specific plate from the stack, we have to remove all plates in the\nstack. So every operation in the stack, either insertion or deletion, is always made at the top of the stack.\nThe @fig-stack below exposes this logic visually:\n\n![A diagram of a stack structure. Source: Wikipedia, the free encyclopedia.](./../Figures/lifo-stack.svg){#fig-stack}\n\n\n\n## Writing the stack data structure\n\nWe are going to write the stack data structure in two steps. First, we are going\nto implement a stack that can only store `u32` values. Then, after that, we are going\nto extend our implementation to make it generic, so that it works with any data type\nwe want.\n\nFirst, we need to decide how the values will be stored inside the stack. There are multiple\nways to implement the storage behind a stack structure. Some people prefer to use a doubly linked list,\nothers prefer to use a dynamic array, etc. In this example we are going to use an array behind the hood,\nto store the values in the stack, which is the `items` data member of our `Stack` struct definition.\n\nAlso notice in our `Stack` struct that we have three other data members: `capacity`, `length` and `allocator`.\nThe `capacity` member contains the capacity of the underlying array that stores the values in the stack.\nThe `length` contains the number of values that are currently being stored in the stack.\nAnd the `allocator` contains the allocator object that will be used by the stack structure whenever it\nneeds to allocate more space for the values that are being stored.\n\nWe begin by defining an `init()` method of this struct, which is going to be\nresponsible for instantiating a `Stack` object. Notice that, inside this\n`init()` method, we start by allocating an array with the capacity specified\nin the `capacity` argument.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst Stack = struct {\n    items: []u32,\n    capacity: usize,\n    length: usize,\n    allocator: Allocator,\n\n    pub fn init(allocator: Allocator, capacity: usize) !Stack {\n        var buf = try allocator.alloc(u32, capacity);\n        return .{\n            .items = buf[0..],\n            .capacity = capacity,\n            .length = 0,\n            .allocator = allocator,\n        };\n    }\n};\n```\n:::\n\n\n\n\n### Implementing the `push` operation\n\nNow that we have written the basic logic to create a new `Stack` object,\nwe can start writing the logic responsible for performing a push operation.\nRemember, a push operation in a stack data structure is the operation\nresponsible for adding a new value to the stack.\n\nSo how can we add a new value to the `Stack` object that we have?\nThe `push()` function exposed below is a possible answer to this question.\nRemember from what we discussed in @sec-what-stack that values are always added to the top of the stack.\nThis means that this `push()` function must always find the element in the underlying array\nthat currently represents the top position of the stack, and then, add the input value there.\n\nFirst, we have an if statement in this function. This if statement is\nchecking whether we need to expand the underlying array to store\nthis new value that we are adding to the stack. In other words, maybe\nthe underlying array does not have enough capacity to store this new\nvalue, and, in this case, we need to expand our array to get the capacity that we need.\n\nSo, if the logical test in this if statement returns true, it means that the array\ndoes not have enough capacity, and we need to expand it before we store this new value.\nSo inside this if statement we are executing the necessary expressions to expand the underlying array.\nNotice that we use the allocator object to allocate a new array that is twice as bigger\nthan the current array (`self.capacity * 2`).\n\nAfter that, we use a different built-in function named `@memcpy()`. This built-in function\nis equivalent to the `memcpy()` function from the C Standard Library[^cmemcpy]. It's used to\ncopy the values from one block of memory to another block of memory. In other words,\nyou can use this function to copy the values from one array into another array.\n\n[^cmemcpy]: <https://www.tutorialspoint.com/c_standard_library/c_function_memcpy.htm>\n\nWe are using this `@memcpy()` built-in function to copy the values that are currently stored\nin the underlying array of the stack object (`self.items`) into our new and bigger array that\nwe have allocated (`new_buf`). After we execute this function, the `new_buf` contains a copy\nof the values that are present at `self.items`.\n\nNow that we have secured a copy of our current values in the `new_buf` object, we\ncan now free the memory currently allocated at `self.items`. After that, we just need\nto assign our new and bigger array to `self.items`. This is the sequence\nof steps necessary to expand our array.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn push(self: *Stack, val: u32) !void {\n    if ((self.length + 1) > self.capacity) {\n        var new_buf = try self.allocator.alloc(\n            u32, self.capacity * 2\n        );\n        @memcpy(\n            new_buf[0..self.capacity], self.items\n        );\n        self.allocator.free(self.items);\n        self.items = new_buf;\n        self.capacity = self.capacity * 2;\n    }\n\n    self.items[self.length] = val;\n    self.length += 1;\n}\n```\n:::\n\n\n\nAfter we make sure that we have enough room to store this new value\nthat we are adding to the stack, all we have to do is to assign\nthis value to the top element in this stack, and, increase the\nvalue of the `length` attribute by one. We find the top element\nin the stack by using the `length` attribute.\n\n\n\n### Implementing the `pop` operation\n\nNow we can implement the pop operation of our stack object.\nThis is a much easier operation to implement, and the `pop()` method below summarises\nall the logic that is needed.\n\nWe just have to find the element in the underlying array that currently represents the top\nof the stack, and set this element to \"undefined\", to indicate that\nthis element is \"empty\". After that, we also need to decrease\nthe `length` attribute of the stack by one.\n\nIf the current length of the stack is zero, it means that there is\nno values being stored in the stack currently. So, in this case,\nwe could just return from the function and do nothing really.\nThis is what the if statement inside this function is checking for.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn pop(self: *Stack) void {\n    if (self.length == 0) return;\n\n    self.items[self.length - 1] = undefined;\n    self.length -= 1;\n}\n```\n:::\n\n\n\n\n\n### Implementing the `deinit` method\n\nWe have implemented the methods responsible for the two main operations\nassociated with the stack data structure, which is `pop()` and `push()`,\nand we also have implemented the method responsible for instantiating\na new `Stack` object, which is the `init()` method.\n\nBut now, we need to implement also the method responsible for destroying\na `Stack` object. In Zig, this task is commonly associated with the method\nnamed `deinit()`. Most struct objects in Zig have such method, and it\nis commonly nicknamed \"the destructor method\".\n\nIn theory, all we have to do to destroy the `Stack` object is to make\nsure that we free the allocated memory for the underlying array, using\nthe allocator object that is stored inside the `Stack` object.\nThis is what the `deinit()` method below is doing.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn deinit(self: *Stack) void {\n    self.allocator.free(self.items);\n}\n```\n:::\n\n\n\n\n\n\n## Making it generic\n\nNow that we have implemented the basic skeleton of our stack data structure,\nwe can now focus on discussing how we can make it generic. How can we make\nthis basic skeleton to work not only with `u32` values, but also with any other\ndata type we want?\nFor example, we might need to create a stack object to store `User` values\nin it. How can we make this possible? The answer lies in the use of generics\nand `comptime`.\n\nAs I described in @sec-generic-struct, the basic idea is to write a generic\nfunction that returns a struct definition as output.\nIn theory, we do not need much to transform our `Stack` struct into a generic\ndata structure. All that we need to do is to transform the underlying array\nof the stack into a generic array.\n\nIn other words, this underlying array needs to be a \"chameleon\". It needs to adapt,\nand transform it into an array of any data type that we want. For example, if we need to create\na stack that will store `u8` values, then this underlying array needs to be\na `u8` array (i.e., `[]u8`). But if we need to store `User` values instead, then,\nthis array needs to be a `User` array (i.e., `[]User`). Etc.\n\nWe do that by using a generic function. Because a generic function can receive a data type\nas input, and we can pass this data type to the struct definition of our `Stack` object.\nTherefore, we can use the generic function to create a `Stack` object that can store\nthe data type we want. If we want to create a stack structure that stores `User` values,\nwe pass the `User` data type to this generic function, and it will create for us\nthe struct definition that describes a `Stack` object that can store `User` values in it.\n\nLook at the code example below. I have omitted some parts of the `Stack` struct definition\nfor brevity. However, if a specific part of our `Stack` struct is not exposed here\nin this example, then it's because this part did not change from the previous example.\nIt remains the same.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn Stack(comptime T: type) type {\n    return struct {\n        items: []T,\n        capacity: usize,\n        length: usize,\n        allocator: Allocator,\n        const Self = @This();\n\n        pub fn init(allocator: Allocator,\n                    capacity: usize) !Stack(T) {\n            var buf = try allocator.alloc(T, capacity);\n            return .{\n                .items = buf[0..],\n                .capacity = capacity,\n                .length = 0,\n                .allocator = allocator,\n            };\n        }\n\n        pub fn push(self: *Self, val: T) !void {\n        // Truncate the rest of the struct\n    };\n}\n```\n:::\n\n\n\nNotice that we have created a function in this example named `Stack()`. This function\ntakes a type as input, and passes this type to the struct definition of our\n`Stack` object. The data member `items` is now, an array of type `T`, which is the\ndata type that we have provided as input to the function. The function argument\n`val` in the `push()` function is now a value of type `T` too.\n\nWe can just provide a data type to this function, and it will create a definition of a\n`Stack` object that can store values of the data type that we have provided. In the example below, we are creating\nthe definition of a\n`Stack` object that can store `u8` values in it. This definition is stored at the `Stacku8` object.\nThis `Stacku8` object becomes our new struct, that we are going to use\nto create our `Stack` object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst Stacku8 = Stack(u8);\nvar stack = try Stacku8.init(allocator, 10);\ndefer stack.deinit();\ntry stack.push(1);\ntry stack.push(2);\ntry stack.push(3);\ntry stack.push(4);\ntry stack.push(5);\ntry stack.push(6);\n\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\"Stack capacity: {d}\\n\", .{stack.capacity});\n\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\n    \"Stack state: {any}\\n\",\n    .{stack.items[0..stack.length]}\n);\n```\n:::\n\n\n\n```\nStack len: 6\nStack capacity: 10\nStack len: 5\nStack len: 4\nStack state: { 1, 2, 3, 4, 0, 0, 0, 0, 0, 0 }\n```\n\nEvery generic data structure in the Zig Standard Library (`ArrayList`, `HashMap`, `SinlyLinkedList`, etc.)\nis implemented through this logic. They use a generic function to create the struct definition that can work\nwith the data type that you provided as input.\n\n\n\n\n## Conclusion\n\nThe full source code of the stack structure discussed in this chapter is freely available in the official\nrepository of this book. Just checkout the [`stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig)[^zig-stack]\nfor the `u32` version of our stack,\nand the [`generic_stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig)[^zig-stack2]\nfor the generic version, available inside the `ZigExamples` folder of the repository.\n\n\n[^zig-stack]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig>\n[^zig-stack2]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig>\n",
-    "supporting": [
-      "10-stack-project_files"
-    ],
-    "filters": [
-      "rmarkdown/pagebreak.lua"
-    ],
-    "includes": {},
-    "engineDependencies": {
-      "knitr": [
-        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
-      ]
-    },
-    "preserve": null,
-    "postProcess": false
-  }
-}
\ No newline at end of file
diff --git a/_freeze/Chapters/10-stack-project/execute-results/html.json b/_freeze/Chapters/10-stack-project/execute-results/html.json
index 4afe632d..3ce0dd6d 100644
--- a/_freeze/Chapters/10-stack-project/execute-results/html.json
+++ b/_freeze/Chapters/10-stack-project/execute-results/html.json
@@ -2,7 +2,7 @@
   "hash": "801c378f39cbcf646c40a137880aa3b8",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 3 - Building a stack data structure\n\nIn this chapter we are going to implement a stack data structure as our next small project\nin this book. Implementing basic data structures in any language is kind of a\n\"kindergarten task\" (if this term even exist) in computer science (CS), because\nwe normally learn and implement them in the first semesters of CS.\n\nBut this is actually good! Since this should be a very easy task, we don't need much to explain\nwhat a stack is, then, we can concentrate on what is really important here, which is learning\nhow the concept of \"generics\" is implemented in the Zig language, and how one of the key\nfeatures of Zig, which is comptime, works, and use the stack data structure to demonstrate\nthese concepts on the fly.\n\nBut before we get into building the stack data structure, we first need to understand\nwhat the `comptime` keyword does to your code, and after that, we also need to learn about\nhow generics work in Zig.\n\n\n## Understanding `comptime` in Zig {#sec-comptime}\n\nOne of the key features of Zig is `comptime`. This keyword introduces a whole\nnew concept and paradigm, that is tightly connected with the compilation process.\nIn @sec-compile-time we have described the importance and the role that \"compile-time versus runtime\"\nplays into Zig. In that section, we learned that the rules applied to a value/object change\na lot depending on whether this value is known at compile-time, or just at runtime.\n\nThe `comptime` keyword is strongly related to these two spaces in time (compile-time and runtime).\nLet's quickly recap the differences. Compile-time is the period of time when your\nZig source code is being compiled by the `zig` compiler, while the runtime is\nthe period of time when your Zig program is being executed, i.e., when we execute\nthe binary files that were generated by the `zig` compiler.\n\nThere are three ways in which you can apply the `comptime` keyword, which are:\n\n- apply `comptime` on a function argument.\n- apply `comptime` on an object.\n- apply `comptime` on a block of expressions.\n\n\n\n### Applying over a function argument\n\nWhen you apply the `comptime` keyword on a function argument, you are saying to the `zig` compiler\nthat the value assigned to that particular function argument must be known at compile-time.\nWe explained in detail in @sec-compile-time what exactly \"value known at compile-time\" means. So\nif you have any doubts about this idea, refer back to that section.\n\nNow let's think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement\nto that particular function argument. If the programmer accidentally tries to give a value to this\nfunction argument that is not known at compile time, the `zig` compiler will notice this problem, and\nas a consequence, it will raise a compilation error saying that it cannot compile your program. Because\nyou are providing a value that is \"runtime known\" to a function argument that must be \"compile-time known\".\n\nTake a look at this very simple example below, where we define a `twice()` function, that simply\ndoubles the input value named `num`. Notice that we use the `comptime` keyword before the name\nof the function argument. This keyword is marking the function argument `num` as a \"comptime argument\".\n\nThat is a function argument whose value must be compile-time known. This is why the expression\n`twice(5678)` is valid, and no compilation errors are raised. Because the value `5678`\nis compile-time known, so this is the expected behaviour for this function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filef044375a1f16.test.test comptime...OKAll 1 \n   tests passed.\n```\n\n\n:::\n:::\n\n\n\n\nBut what if we provide a number that is not compile-time known to this function?\nFor example, your program might receive some input from the user through the `stdin`\nchannel of your system. This input from the user might be many different things,\nand cannot be predicted at compile-time. These circumstances make this \"input\nfrom the user\" a value that is runtime-known only.\n\nIn the example below, this \"input from the user\" is initially received as a string,\nwhich is then parsed and transformed into a integer value, and the result of this operation\nis stored inside the `n` object.\n\nBecause the \"input of the user\" is known only at runtime, the value of the object `n` is determined only at runtime.\nAs consequence, we cannot provide this object as input to the `twice()` function.\nThe `zig` compiler will not allow it, because we marked\nthe `num` argument as a \"comptime argument\". That is why the `zig` compiler raises\nthe compile-time error exposed below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\n\npub fn main() !void {\n    var buffer: [5]u8 = .{ 0, 0, 0, 0, 0 };\n    const stdout = std.io.getStdOut().writer();\n    const stdin = std.io.getStdIn().reader();\n    _ = try stdout.write(\"Please write a 4-digit integer number\\n\");\n    _ = try stdin.readUntilDelimiter(&buffer, '\\n');\n\n    try stdout.print(\"Input: {s}\", .{buffer});\n    const n: u32 = try std.fmt.parseInt(\n        u32, buffer[0 .. buffer.len - 1], 10\n    );\n    const twice_result = twice(n);\n    try stdout.print(\"Result: {d}\\n\", .{twice_result});\n}\n```\n:::\n\n\n\n\n```\nt.zig:12:16: error: unable to resolve comptime value\n    const twice_result = twice(n);\n                               ^\n```\n\nComptime arguments are frequently used on functions that return some sort\nof generic structure. In fact, `comptime` is the essence (or the basis) to make generics in Zig.\nWe are going to talk more about generics in @sec-generics.\n\nFor now, let's take a look at this code example from @karlseguin_generics. You\ncan see that this `IntArray()` function has one argument named `length`.\nThis argument is marked as comptime, and receives a value of type `usize` as input. So the value given to this argument\nmust be compile-time known.\nWe can also see that this function returns an array of `i64` values as output.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n```\n:::\n\n\n\n\nNow, the key component of this function is the `length` argument. This argument\nis used to determine the size of the array that is produced by the function. Let's\nthink about the consequences of that. If the size of the array is dependent on\nthe value assigned to the `length` argument, this means that the data type of the\noutput of the function depends on the value of this `length` argument.\n\nLet this statement sink for a bit in your mind. As I described in @sec-root-file,\nZig is a strongly-typed language, especially on function declarations.\nSo every time we write a function in Zig, we have to annotate the data type of\nthe value returned by the function. But how can we do that, if this data type\ndepends on the value given to the argument of the function?\n\nThink about this for a second. If `length` is equal to 3 for example, then, the\nreturn type of the function is `[3]i64`. But if `length` is equal to 40, then,\nthe return type becomes `[40]i64`. At this point the `zig` compiler would be confused,\nand raise a compilation error, saying something like this:\n\n> Hey! You have annotated that this function should return a `[3]i64` value, but I got a `[40]i64` value instead! This doesn't look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when\nthe `type` keyword comes in. This `type` keyword is basically saying to the\n`zig` compiler that this function will return some data type as output, but it doesn't know yet\nwhat exactly data type that is. We will talk more about this in @sec-generics.\n\n\n\n### Applying over an expression\n\nWhen you apply the `comptime` keyword over an expression, then, it is guaranteed that the `zig` compiler will\nexecute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time\n(e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the `zig` compiler\nwill raise a compilation error.\n\nTake this example from the official documentation of Zig [@zigdocs]. We\nare executing the same `fibonacci()` function both at runtime, and, at compile-time.\nThe function is executed by default at runtime, but because we use the `comptime`\nkeyword in the second \"try expression\", this expression is executed at compile-time.\n\nThis might be a bit confusing for some people. Yes! When I say that this expression\nis executed at compile-time, I mean that this expression is compiled and executed\nwhile the `zig` compiler is compiling your Zig source code.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filef0447cb16f4d.test.fibonacci...OKAll 1 test\n  ts passed.\n```\n\n\n:::\n:::\n\n\n\n\nA lot of your Zig source code might be potentially executed at compile-time,\nbecause the `zig` compiler can figure out the output of some expressions.\nEspecially if these expressions depend only on compile-time known values.\nWe have talked about this in @sec-compile-time.\n\nBut when you use the `comptime` keyword on an expression, there is no \"it might be executed\nat compile-time\" anymore. With the `comptime` keyword you are ordering the `zig` compiler\nto execute this expression at compile-time. You are imposing this rule, it is guaranteed\nthat the compiler will always execute it at compile-time. Or, at least, the compiler\nwill try to execute it. If the compiler cannot execute the expression for whatever reason,\nthe compiler will raise a compilation error.\n\n\n### Applying over a block\n\nBlocks were described in @sec-blocks. When you apply the `comptime` keyword to a\nblock of expressions, you get essentially the same effect as when you apply this keyword to\na single expression. That is, the entire block of expressions is executed at\ncompile-time by the `zig` compiler.\n\nIn the example below, we mark the block labeled of `blk` as a comptime block,\nand, therefore, the expressions inside this block are executed at compile-time.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 filef044524d5e27.test.fibonacci in a block...O\n  OKAll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n\n## Introducing Generics {#sec-generics}\n\nFirst of all, what is a generic? Generic is the idea to allow a type\n(`f64`, `u8`, `u32`, `bool`, and also, user-defined types, like the `User` struct\nthat we defined in @sec-structs-and-oop) to be a parameter to methods, classes and\ninterfaces [@geeks_generics]. In other words, a \"generic\" is a class (or a method) that can work\nwith multiple data types.\n\nFor example, in Java, generics are created through the operator `<>`. With this operator,\na Java class is capable of receiving a data type as input, and therefore, the class can fit\nits features according to this input data type.\nAs another example, generics in C++ are supported through the concept of templates.\nClass templates in C++ are generics.\n\nIn Zig, generics are implemented through `comptime`. The `comptime` keyword\nallows us to collect a data type at compile time, and pass this data type as\ninput to a piece of code.\n\n\n### A generic function {#sec-generic-fun}\n\nTake the `max()` function exposed below as a first example.\nThis function is essentially a \"generic function\".\nIn this function, we have a comptime function argument named `T`.\nNotice that this `T` argument has a data type of `type`. Weird right? This `type` keyword is the\n\"father of all types\", or, \"the type of types\" in Zig.\n\nBecause we have used this `type` keyword in the `T` argument, we are telling\nthe `zig` compiler that this `T` argument will receive some data type as input.\nAlso notice the use of the `comptime` keyword in this argument.\nAs I described in @sec-comptime, every time you use this keyword in a function argument,\nthis means that the value of this argument must be known at compile-time.\nThis makes sense, right? Because there is no data type that is not known at compile-time.\n\nThink about this. Every data type that you will ever write is always\nknown at compile-time. Especially because data types are an essential\ninformation for the compiler to actually compile your source code.\nHaving this in mind, makes sense to mark this argument as a comptime argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\n```\n:::\n\n\n\n\nAlso notice that the value of the `T` argument is actually used\nto define the data type of the other arguments in the function, `a` and `b`, and also at the\nreturn type annotation of the function.\nThat is, the data type of these arguments (`a` and `b`), and, the return data type of the function itself,\nare determined by the input value given to the `T` argument.\n\nAs a result, we have a generic function that works with different data types.\nFor example, I can provide `u8` values to this `max()` function, and it will work as expected.\nBut if I provide `f64` values instead, it will also work as expected.\nWithout a generic function, I would have to write a different `max()` function\nfor each data type I wanted to use.\nThis generic function provides a very useful shortcut for us.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\ntest \"test max\" {\n    const n1 = max(u8, 4, 10);\n    std.debug.print(\"Max n1: {d}\\n\", .{n1});\n    const n2 = max(f64, 89.24, 64.001);\n    std.debug.print(\"Max n2: {d}\\n\", .{n2});\n}\n```\n:::\n\n\n\n\n```\nMax n1: 10\nMax n2: 89.24\n```\n\n\n### A generic data structure {#sec-generic-struct}\n\nEvery data structure that you find in the Zig Standard Library (e.g. `ArrayList`, `HashMap`, etc.)\nis essentially a generic data structure.\nThese data structures are generic in the sense that they work with any data type you want.\nYou just say which is the data type of the values that are going to be stored in this data\nstructure, and they just work as expected.\n\nA generic data structure in Zig is how you replicate a generic class from Java,\nor, a class template from C++. But you may ask yourself: how do we build a\ngeneric data structure in Zig?\n\nThe basic idea is to write a generic function that creates the data structure definition\nfor the specific type we want. In other words, this generic function behaves as a \"factory of data structures\".\nThe generic function outputs the `struct` definition that defines this data structure for a\nspecific data type.\n\nTo create such function, we need to add a comptime argument to this function that receives a data type\nas input. We already learned how to do this in the previous section (@sec-generic-fun).\nI think the best way to demonstrate how to create a generic data structure is to actually write one.\nThis where we go into our next small project in this book. This one is a very small project,\nwhich is to write a generic stack data structure.\n\n\n\n\n## What is a stack? {#sec-what-stack}\n\nA stack data structure is a structure that follows a LIFO (*last in, first out*) principle.\nOnly two operations are normally supported in a stack data structure, which are `push` and `pop`.\nThe `push` operation is used to add new values to the stack, while `pop` is used to remove\nvalues from the stack.\n\nWhen people try to explain how the stack data structure works, the most common analogy\nthat they use is a stack of plates. Imagine that you have a stack of plates,\nfor example, a stack of 10 plates in your table. Each plate represents a value that\nis currently stored in this stack.\n\nWe begin with a stack of 10 different values, or 10 different plates. Now, imagine that you want to\nadd a new plate (or a new value) to this stack, which translates to the `push` operation.\nYou would add this plate (or this value) by just putting the new plate\non the top of the stack. Then, you would increase the stack to 11 plates.\n\nBut how would you remove plates (or remove values) from this stack (a.k.a. the `pop` operation) ?\nTo do that, we would have to remove the plate on the top of the stack, and, as a result, we would\nhave, once again, 10 plates in the stack.\n\nThis demonstrates the LIFO concept, because the first plate in the stack, which is the plate\nin the bottom of the stack, is always the last plate to get out of the stack. Think about it. In order\nto remove this specific plate from the stack, we have to remove all plates in the\nstack. So every operation in the stack, either insertion or deletion, is always made at the top of the stack.\nThe @fig-stack below exposes this logic visually:\n\n![A diagram of a stack structure. Source: Wikipedia, the free encyclopedia.](./../Figures/lifo-stack.svg){#fig-stack}\n\n\n\n## Writing the stack data structure\n\nWe are going to write the stack data structure in two steps. First, we are going\nto implement a stack that can only store `u32` values. Then, after that, we are going\nto extend our implementation to make it generic, so that it works with any data type\nwe want.\n\nFirst, we need to decide how the values will be stored inside the stack. There are multiple\nways to implement the storage behind a stack structure. Some people prefer to use a doubly linked list,\nothers prefer to use a dynamic array, etc. In this example we are going to use an array behind the hood,\nto store the values in the stack, which is the `items` data member of our `Stack` struct definition.\n\nAlso notice in our `Stack` struct that we have three other data members: `capacity`, `length` and `allocator`.\nThe `capacity` member contains the capacity of the underlying array that stores the values in the stack.\nThe `length` contains the number of values that are currently being stored in the stack.\nAnd the `allocator` contains the allocator object that will be used by the stack structure whenever it\nneeds to allocate more space for the values that are being stored.\n\nWe begin by defining an `init()` method of this struct, which is going to be\nresponsible for instantiating a `Stack` object. Notice that, inside this\n`init()` method, we start by allocating an array with the capacity specified\nin the `capacity` argument.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst Stack = struct {\n    items: []u32,\n    capacity: usize,\n    length: usize,\n    allocator: Allocator,\n\n    pub fn init(allocator: Allocator, capacity: usize) !Stack {\n        var buf = try allocator.alloc(u32, capacity);\n        return .{\n            .items = buf[0..],\n            .capacity = capacity,\n            .length = 0,\n            .allocator = allocator,\n        };\n    }\n};\n```\n:::\n\n\n\n\n\n### Implementing the `push` operation\n\nNow that we have written the basic logic to create a new `Stack` object,\nwe can start writing the logic responsible for performing a push operation.\nRemember, a push operation in a stack data structure is the operation\nresponsible for adding a new value to the stack.\n\nSo how can we add a new value to the `Stack` object that we have?\nThe `push()` function exposed below is a possible answer to this question.\nRemember from what we discussed in @sec-what-stack that values are always added to the top of the stack.\nThis means that this `push()` function must always find the element in the underlying array\nthat currently represents the top position of the stack, and then, add the input value there.\n\nFirst, we have an if statement in this function. This if statement is\nchecking whether we need to expand the underlying array to store\nthis new value that we are adding to the stack. In other words, maybe\nthe underlying array does not have enough capacity to store this new\nvalue, and, in this case, we need to expand our array to get the capacity that we need.\n\nSo, if the logical test in this if statement returns true, it means that the array\ndoes not have enough capacity, and we need to expand it before we store this new value.\nSo inside this if statement we are executing the necessary expressions to expand the underlying array.\nNotice that we use the allocator object to allocate a new array that is twice as bigger\nthan the current array (`self.capacity * 2`).\n\nAfter that, we use a different built-in function named `@memcpy()`. This built-in function\nis equivalent to the `memcpy()` function from the C Standard Library[^cmemcpy]. It's used to\ncopy the values from one block of memory to another block of memory. In other words,\nyou can use this function to copy the values from one array into another array.\n\n[^cmemcpy]: <https://www.tutorialspoint.com/c_standard_library/c_function_memcpy.htm>\n\nWe are using this `@memcpy()` built-in function to copy the values that are currently stored\nin the underlying array of the stack object (`self.items`) into our new and bigger array that\nwe have allocated (`new_buf`). After we execute this function, the `new_buf` contains a copy\nof the values that are present at `self.items`.\n\nNow that we have secured a copy of our current values in the `new_buf` object, we\ncan now free the memory currently allocated at `self.items`. After that, we just need\nto assign our new and bigger array to `self.items`. This is the sequence\nof steps necessary to expand our array.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn push(self: *Stack, val: u32) !void {\n    if ((self.length + 1) > self.capacity) {\n        var new_buf = try self.allocator.alloc(\n            u32, self.capacity * 2\n        );\n        @memcpy(\n            new_buf[0..self.capacity], self.items\n        );\n        self.allocator.free(self.items);\n        self.items = new_buf;\n        self.capacity = self.capacity * 2;\n    }\n\n    self.items[self.length] = val;\n    self.length += 1;\n}\n```\n:::\n\n\n\n\nAfter we make sure that we have enough room to store this new value\nthat we are adding to the stack, all we have to do is to assign\nthis value to the top element in this stack, and, increase the\nvalue of the `length` attribute by one. We find the top element\nin the stack by using the `length` attribute.\n\n\n\n### Implementing the `pop` operation\n\nNow we can implement the pop operation of our stack object.\nThis is a much easier operation to implement, and the `pop()` method below summarises\nall the logic that is needed.\n\nWe just have to find the element in the underlying array that currently represents the top\nof the stack, and set this element to \"undefined\", to indicate that\nthis element is \"empty\". After that, we also need to decrease\nthe `length` attribute of the stack by one.\n\nIf the current length of the stack is zero, it means that there is\nno values being stored in the stack currently. So, in this case,\nwe could just return from the function and do nothing really.\nThis is what the if statement inside this function is checking for.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn pop(self: *Stack) void {\n    if (self.length == 0) return;\n\n    self.items[self.length - 1] = undefined;\n    self.length -= 1;\n}\n```\n:::\n\n\n\n\n\n\n### Implementing the `deinit` method\n\nWe have implemented the methods responsible for the two main operations\nassociated with the stack data structure, which is `pop()` and `push()`,\nand we also have implemented the method responsible for instantiating\na new `Stack` object, which is the `init()` method.\n\nBut now, we need to implement also the method responsible for destroying\na `Stack` object. In Zig, this task is commonly associated with the method\nnamed `deinit()`. Most struct objects in Zig have such method, and it\nis commonly nicknamed \"the destructor method\".\n\nIn theory, all we have to do to destroy the `Stack` object is to make\nsure that we free the allocated memory for the underlying array, using\nthe allocator object that is stored inside the `Stack` object.\nThis is what the `deinit()` method below is doing.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn deinit(self: *Stack) void {\n    self.allocator.free(self.items);\n}\n```\n:::\n\n\n\n\n\n\n\n## Making it generic\n\nNow that we have implemented the basic skeleton of our stack data structure,\nwe can now focus on discussing how we can make it generic. How can we make\nthis basic skeleton to work not only with `u32` values, but also with any other\ndata type we want?\nFor example, we might need to create a stack object to store `User` values\nin it. How can we make this possible? The answer lies in the use of generics\nand `comptime`.\n\nAs I described in @sec-generic-struct, the basic idea is to write a generic\nfunction that returns a struct definition as output.\nIn theory, we do not need much to transform our `Stack` struct into a generic\ndata structure. All that we need to do is to transform the underlying array\nof the stack into a generic array.\n\nIn other words, this underlying array needs to be a \"chameleon\". It needs to adapt,\nand transform it into an array of any data type that we want. For example, if we need to create\na stack that will store `u8` values, then this underlying array needs to be\na `u8` array (i.e., `[]u8`). But if we need to store `User` values instead, then,\nthis array needs to be a `User` array (i.e., `[]User`). Etc.\n\nWe do that by using a generic function. Because a generic function can receive a data type\nas input, and we can pass this data type to the struct definition of our `Stack` object.\nTherefore, we can use the generic function to create a `Stack` object that can store\nthe data type we want. If we want to create a stack structure that stores `User` values,\nwe pass the `User` data type to this generic function, and it will create for us\nthe struct definition that describes a `Stack` object that can store `User` values in it.\n\nLook at the code example below. I have omitted some parts of the `Stack` struct definition\nfor brevity. However, if a specific part of our `Stack` struct is not exposed here\nin this example, then it's because this part did not change from the previous example.\nIt remains the same.\n\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn Stack(comptime T: type) type {\n    return struct {\n        items: []T,\n        capacity: usize,\n        length: usize,\n        allocator: Allocator,\n        const Self = @This();\n\n        pub fn init(allocator: Allocator,\n                    capacity: usize) !Stack(T) {\n            var buf = try allocator.alloc(T, capacity);\n            return .{\n                .items = buf[0..],\n                .capacity = capacity,\n                .length = 0,\n                .allocator = allocator,\n            };\n        }\n\n        pub fn push(self: *Self, val: T) !void {\n        // Truncate the rest of the struct\n    };\n}\n```\n:::\n\n\n\n\nNotice that we have created a function in this example named `Stack()`. This function\ntakes a type as input, and passes this type to the struct definition of our\n`Stack` object. The data member `items` is now, an array of type `T`, which is the\ndata type that we have provided as input to the function. The function argument\n`val` in the `push()` function is now a value of type `T` too.\n\nWe can just provide a data type to this function, and it will create a definition of a\n`Stack` object that can store values of the data type that we have provided. In the example below, we are creating\nthe definition of a\n`Stack` object that can store `u8` values in it. This definition is stored at the `Stacku8` object.\nThis `Stacku8` object becomes our new struct, that we are going to use\nto create our `Stack` object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst Stacku8 = Stack(u8);\nvar stack = try Stacku8.init(allocator, 10);\ndefer stack.deinit();\ntry stack.push(1);\ntry stack.push(2);\ntry stack.push(3);\ntry stack.push(4);\ntry stack.push(5);\ntry stack.push(6);\n\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\"Stack capacity: {d}\\n\", .{stack.capacity});\n\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\n    \"Stack state: {any}\\n\",\n    .{stack.items[0..stack.length]}\n);\n```\n:::\n\n\n\n\n```\nStack len: 6\nStack capacity: 10\nStack len: 5\nStack len: 4\nStack state: { 1, 2, 3, 4, 0, 0, 0, 0, 0, 0 }\n```\n\nEvery generic data structure in the Zig Standard Library (`ArrayList`, `HashMap`, `SinlyLinkedList`, etc.)\nis implemented through this logic. They use a generic function to create the struct definition that can work\nwith the data type that you provided as input.\n\n\n\n\n## Conclusion\n\nThe full source code of the stack structure discussed in this chapter is freely available in the official\nrepository of this book. Just checkout the [`stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig)[^zig-stack]\nfor the `u32` version of our stack,\nand the [`generic_stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig)[^zig-stack2]\nfor the generic version, available inside the `ZigExamples` folder of the repository.\n\n\n[^zig-stack]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig>\n[^zig-stack2]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig>\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n# Project 3 - Building a stack data structure\n\nIn this chapter we are going to implement a stack data structure as our next small project\nin this book. Implementing basic data structures in any language is kind of a\n\"kindergarten task\" (if this term even exist) in computer science (CS), because\nwe normally learn and implement them in the first semesters of CS.\n\nBut this is actually good! Since this should be a very easy task, we don't need much to explain\nwhat a stack is, then, we can concentrate on what is really important here, which is learning\nhow the concept of \"generics\" is implemented in the Zig language, and how one of the key\nfeatures of Zig, which is comptime, works, and use the stack data structure to demonstrate\nthese concepts on the fly.\n\nBut before we get into building the stack data structure, we first need to understand\nwhat the `comptime` keyword does to your code, and after that, we also need to learn about\nhow generics work in Zig.\n\n\n## Understanding `comptime` in Zig {#sec-comptime}\n\nOne of the key features of Zig is `comptime`. This keyword introduces a whole\nnew concept and paradigm, that is tightly connected with the compilation process.\nIn @sec-compile-time we have described the importance and the role that \"compile-time versus runtime\"\nplays into Zig. In that section, we learned that the rules applied to a value/object change\na lot depending on whether this value is known at compile-time, or just at runtime.\n\nThe `comptime` keyword is strongly related to these two spaces in time (compile-time and runtime).\nLet's quickly recap the differences. Compile-time is the period of time when your\nZig source code is being compiled by the `zig` compiler, while the runtime is\nthe period of time when your Zig program is being executed, i.e., when we execute\nthe binary files that were generated by the `zig` compiler.\n\nThere are three ways in which you can apply the `comptime` keyword, which are:\n\n- apply `comptime` on a function argument.\n- apply `comptime` on an object.\n- apply `comptime` on a block of expressions.\n\n\n\n### Applying over a function argument\n\nWhen you apply the `comptime` keyword on a function argument, you are saying to the `zig` compiler\nthat the value assigned to that particular function argument must be known at compile-time.\nWe explained in detail in @sec-compile-time what exactly \"value known at compile-time\" means. So\nif you have any doubts about this idea, refer back to that section.\n\nNow let's think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement\nto that particular function argument. If the programmer accidentally tries to give a value to this\nfunction argument that is not known at compile time, the `zig` compiler will notice this problem, and\nas a consequence, it will raise a compilation error saying that it cannot compile your program. Because\nyou are providing a value that is \"runtime known\" to a function argument that must be \"compile-time known\".\n\nTake a look at this very simple example below, where we define a `twice()` function, that simply\ndoubles the input value named `num`. Notice that we use the `comptime` keyword before the name\nof the function argument. This keyword is marking the function argument `num` as a \"comptime argument\".\n\nThat is a function argument whose value must be compile-time known. This is why the expression\n`twice(5678)` is valid, and no compilation errors are raised. Because the value `5678`\nis compile-time known, so this is the expected behaviour for this function.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file20a25a72e5e3.test.test comptime...OKAll 1 \n   tests passed.\n```\n\n\n:::\n:::\n\n\nBut what if we provide a number that is not compile-time known to this function?\nFor example, your program might receive some input from the user through the `stdin`\nchannel of your system. This input from the user might be many different things,\nand cannot be predicted at compile-time. These circumstances make this \"input\nfrom the user\" a value that is runtime-known only.\n\nIn the example below, this \"input from the user\" is initially received as a string,\nwhich is then parsed and transformed into a integer value, and the result of this operation\nis stored inside the `n` object.\n\nBecause the \"input of the user\" is known only at runtime, the value of the object `n` is determined only at runtime.\nAs consequence, we cannot provide this object as input to the `twice()` function.\nThe `zig` compiler will not allow it, because we marked\nthe `num` argument as a \"comptime argument\". That is why the `zig` compiler raises\nthe compile-time error exposed below:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\n\npub fn main() !void {\n    var buffer: [5]u8 = .{ 0, 0, 0, 0, 0 };\n    const stdout = std.io.getStdOut().writer();\n    const stdin = std.io.getStdIn().reader();\n    _ = try stdout.write(\"Please write a 4-digit integer number\\n\");\n    _ = try stdin.readUntilDelimiter(&buffer, '\\n');\n\n    try stdout.print(\"Input: {s}\", .{buffer});\n    const n: u32 = try std.fmt.parseInt(\n        u32, buffer[0 .. buffer.len - 1], 10\n    );\n    const twice_result = twice(n);\n    try stdout.print(\"Result: {d}\\n\", .{twice_result});\n}\n```\n:::\n\n\n```\nt.zig:12:16: error: unable to resolve comptime value\n    const twice_result = twice(n);\n                               ^\n```\n\nComptime arguments are frequently used on functions that return some sort\nof generic structure. In fact, `comptime` is the essence (or the basis) to make generics in Zig.\nWe are going to talk more about generics in @sec-generics.\n\nFor now, let's take a look at this code example from @karlseguin_generics. You\ncan see that this `IntArray()` function has one argument named `length`.\nThis argument is marked as comptime, and receives a value of type `usize` as input. So the value given to this argument\nmust be compile-time known.\nWe can also see that this function returns an array of `i64` values as output.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n```\n:::\n\n\nNow, the key component of this function is the `length` argument. This argument\nis used to determine the size of the array that is produced by the function. Let's\nthink about the consequences of that. If the size of the array is dependent on\nthe value assigned to the `length` argument, this means that the data type of the\noutput of the function depends on the value of this `length` argument.\n\nLet this statement sink for a bit in your mind. As I described in @sec-root-file,\nZig is a strongly-typed language, especially on function declarations.\nSo every time we write a function in Zig, we have to annotate the data type of\nthe value returned by the function. But how can we do that, if this data type\ndepends on the value given to the argument of the function?\n\nThink about this for a second. If `length` is equal to 3 for example, then, the\nreturn type of the function is `[3]i64`. But if `length` is equal to 40, then,\nthe return type becomes `[40]i64`. At this point the `zig` compiler would be confused,\nand raise a compilation error, saying something like this:\n\n> Hey! You have annotated that this function should return a `[3]i64` value, but I got a `[40]i64` value instead! This doesn't look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when\nthe `type` keyword comes in. This `type` keyword is basically saying to the\n`zig` compiler that this function will return some data type as output, but it doesn't know yet\nwhat exactly data type that is. We will talk more about this in @sec-generics.\n\n\n\n### Applying over an expression\n\nWhen you apply the `comptime` keyword over an expression, then, it is guaranteed that the `zig` compiler will\nexecute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time\n(e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the `zig` compiler\nwill raise a compilation error.\n\nTake this example from the official documentation of Zig [@zigdocs]. We\nare executing the same `fibonacci()` function both at runtime, and, at compile-time.\nThe function is executed by default at runtime, but because we use the `comptime`\nkeyword in the second \"try expression\", this expression is executed at compile-time.\n\nThis might be a bit confusing for some people. Yes! When I say that this expression\nis executed at compile-time, I mean that this expression is compiled and executed\nwhile the `zig` compiler is compiling your Zig source code.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file20a26d02bee1.test.fibonacci...OKAll 1 test\n  ts passed.\n```\n\n\n:::\n:::\n\n\nA lot of your Zig source code might be potentially executed at compile-time,\nbecause the `zig` compiler can figure out the output of some expressions.\nEspecially if these expressions depend only on compile-time known values.\nWe have talked about this in @sec-compile-time.\n\nBut when you use the `comptime` keyword on an expression, there is no \"it might be executed\nat compile-time\" anymore. With the `comptime` keyword you are ordering the `zig` compiler\nto execute this expression at compile-time. You are imposing this rule, it is guaranteed\nthat the compiler will always execute it at compile-time. Or, at least, the compiler\nwill try to execute it. If the compiler cannot execute the expression for whatever reason,\nthe compiler will raise a compilation error.\n\n\n### Applying over a block\n\nBlocks were described in @sec-blocks. When you apply the `comptime` keyword to a\nblock of expressions, you get essentially the same effect as when you apply this keyword to\na single expression. That is, the entire block of expressions is executed at\ncompile-time by the `zig` compiler.\n\nIn the example below, we mark the block labeled of `blk` as a comptime block,\nand, therefore, the expressions inside this block are executed at compile-time.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index < 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n1/1 file20a238222e11.test.fibonacci in a block...O\n  OKAll 1 tests passed.\n```\n\n\n:::\n:::\n\n\n\n\n\n\n## Introducing Generics {#sec-generics}\n\nFirst of all, what is a generic? Generic is the idea to allow a type\n(`f64`, `u8`, `u32`, `bool`, and also, user-defined types, like the `User` struct\nthat we defined in @sec-structs-and-oop) to be a parameter to methods, classes and\ninterfaces [@geeks_generics]. In other words, a \"generic\" is a class (or a method) that can work\nwith multiple data types.\n\nFor example, in Java, generics are created through the operator `<>`. With this operator,\na Java class is capable of receiving a data type as input, and therefore, the class can fit\nits features according to this input data type.\nAs another example, generics in C++ are supported through the concept of templates.\nClass templates in C++ are generics.\n\nIn Zig, generics are implemented through `comptime`. The `comptime` keyword\nallows us to collect a data type at compile time, and pass this data type as\ninput to a piece of code.\n\n\n### A generic function {#sec-generic-fun}\n\nTake the `max()` function exposed below as a first example.\nThis function is essentially a \"generic function\".\nIn this function, we have a comptime function argument named `T`.\nNotice that this `T` argument has a data type of `type`. Weird right? This `type` keyword is the\n\"father of all types\", or, \"the type of types\" in Zig.\n\nBecause we have used this `type` keyword in the `T` argument, we are telling\nthe `zig` compiler that this `T` argument will receive some data type as input.\nAlso notice the use of the `comptime` keyword in this argument.\nAs I described in @sec-comptime, every time you use this keyword in a function argument,\nthis means that the value of this argument must be known at compile-time.\nThis makes sense, right? Because there is no data type that is not known at compile-time.\n\nThink about this. Every data type that you will ever write is always\nknown at compile-time. Especially because data types are an essential\ninformation for the compiler to actually compile your source code.\nHaving this in mind, makes sense to mark this argument as a comptime argument.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\n```\n:::\n\n\nAlso notice that the value of the `T` argument is actually used\nto define the data type of the other arguments in the function, `a` and `b`, and also at the\nreturn type annotation of the function.\nThat is, the data type of these arguments (`a` and `b`), and, the return data type of the function itself,\nare determined by the input value given to the `T` argument.\n\nAs a result, we have a generic function that works with different data types.\nFor example, I can provide `u8` values to this `max()` function, and it will work as expected.\nBut if I provide `f64` values instead, it will also work as expected.\nWithout a generic function, I would have to write a different `max()` function\nfor each data type I wanted to use.\nThis generic function provides a very useful shortcut for us.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn max(comptime T: type, a: T, b: T) T {\n    return if (a > b) a else b;\n}\ntest \"test max\" {\n    const n1 = max(u8, 4, 10);\n    std.debug.print(\"Max n1: {d}\\n\", .{n1});\n    const n2 = max(f64, 89.24, 64.001);\n    std.debug.print(\"Max n2: {d}\\n\", .{n2});\n}\n```\n:::\n\n\n```\nMax n1: 10\nMax n2: 89.24\n```\n\n\n### A generic data structure {#sec-generic-struct}\n\nEvery data structure that you find in the Zig Standard Library (e.g. `ArrayList`, `HashMap`, etc.)\nis essentially a generic data structure.\nThese data structures are generic in the sense that they work with any data type you want.\nYou just say which is the data type of the values that are going to be stored in this data\nstructure, and they just work as expected.\n\nA generic data structure in Zig is how you replicate a generic class from Java,\nor, a class template from C++. But you may ask yourself: how do we build a\ngeneric data structure in Zig?\n\nThe basic idea is to write a generic function that creates the data structure definition\nfor the specific type we want. In other words, this generic function behaves as a \"factory of data structures\".\nThe generic function outputs the `struct` definition that defines this data structure for a\nspecific data type.\n\nTo create such function, we need to add a comptime argument to this function that receives a data type\nas input. We already learned how to do this in the previous section (@sec-generic-fun).\nI think the best way to demonstrate how to create a generic data structure is to actually write one.\nThis where we go into our next small project in this book. This one is a very small project,\nwhich is to write a generic stack data structure.\n\n\n\n\n## What is a stack? {#sec-what-stack}\n\nA stack data structure is a structure that follows a LIFO (*last in, first out*) principle.\nOnly two operations are normally supported in a stack data structure, which are `push` and `pop`.\nThe `push` operation is used to add new values to the stack, while `pop` is used to remove\nvalues from the stack.\n\nWhen people try to explain how the stack data structure works, the most common analogy\nthat they use is a stack of plates. Imagine that you have a stack of plates,\nfor example, a stack of 10 plates in your table. Each plate represents a value that\nis currently stored in this stack.\n\nWe begin with a stack of 10 different values, or 10 different plates. Now, imagine that you want to\nadd a new plate (or a new value) to this stack, which translates to the `push` operation.\nYou would add this plate (or this value) by just putting the new plate\non the top of the stack. Then, you would increase the stack to 11 plates.\n\nBut how would you remove plates (or remove values) from this stack (a.k.a. the `pop` operation) ?\nTo do that, we would have to remove the plate on the top of the stack, and, as a result, we would\nhave, once again, 10 plates in the stack.\n\nThis demonstrates the LIFO concept, because the first plate in the stack, which is the plate\nin the bottom of the stack, is always the last plate to get out of the stack. Think about it. In order\nto remove this specific plate from the stack, we have to remove all plates in the\nstack. So every operation in the stack, either insertion or deletion, is always made at the top of the stack.\nThe @fig-stack below exposes this logic visually:\n\n![A diagram of a stack structure. Source: Wikipedia, the free encyclopedia.](./../Figures/lifo-stack.svg){#fig-stack}\n\n\n\n## Writing the stack data structure\n\nWe are going to write the stack data structure in two steps. First, we are going\nto implement a stack that can only store `u32` values. Then, after that, we are going\nto extend our implementation to make it generic, so that it works with any data type\nwe want.\n\nFirst, we need to decide how the values will be stored inside the stack. There are multiple\nways to implement the storage behind a stack structure. Some people prefer to use a doubly linked list,\nothers prefer to use a dynamic array, etc. In this example we are going to use an array behind the hood,\nto store the values in the stack, which is the `items` data member of our `Stack` struct definition.\n\nAlso notice in our `Stack` struct that we have three other data members: `capacity`, `length` and `allocator`.\nThe `capacity` member contains the capacity of the underlying array that stores the values in the stack.\nThe `length` contains the number of values that are currently being stored in the stack.\nAnd the `allocator` contains the allocator object that will be used by the stack structure whenever it\nneeds to allocate more space for the values that are being stored.\n\nWe begin by defining an `init()` method of this struct, which is going to be\nresponsible for instantiating a `Stack` object. Notice that, inside this\n`init()` method, we start by allocating an array with the capacity specified\nin the `capacity` argument.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst Stack = struct {\n    items: []u32,\n    capacity: usize,\n    length: usize,\n    allocator: Allocator,\n\n    pub fn init(allocator: Allocator, capacity: usize) !Stack {\n        var buf = try allocator.alloc(u32, capacity);\n        return .{\n            .items = buf[0..],\n            .capacity = capacity,\n            .length = 0,\n            .allocator = allocator,\n        };\n    }\n};\n```\n:::\n\n\n\n### Implementing the `push` operation\n\nNow that we have written the basic logic to create a new `Stack` object,\nwe can start writing the logic responsible for performing a push operation.\nRemember, a push operation in a stack data structure is the operation\nresponsible for adding a new value to the stack.\n\nSo how can we add a new value to the `Stack` object that we have?\nThe `push()` function exposed below is a possible answer to this question.\nRemember from what we discussed in @sec-what-stack that values are always added to the top of the stack.\nThis means that this `push()` function must always find the element in the underlying array\nthat currently represents the top position of the stack, and then, add the input value there.\n\nFirst, we have an if statement in this function. This if statement is\nchecking whether we need to expand the underlying array to store\nthis new value that we are adding to the stack. In other words, maybe\nthe underlying array does not have enough capacity to store this new\nvalue, and, in this case, we need to expand our array to get the capacity that we need.\n\nSo, if the logical test in this if statement returns true, it means that the array\ndoes not have enough capacity, and we need to expand it before we store this new value.\nSo inside this if statement we are executing the necessary expressions to expand the underlying array.\nNotice that we use the allocator object to allocate a new array that is twice as bigger\nthan the current array (`self.capacity * 2`).\n\nAfter that, we use a different built-in function named `@memcpy()`. This built-in function\nis equivalent to the `memcpy()` function from the C Standard Library[^cmemcpy]. It's used to\ncopy the values from one block of memory to another block of memory. In other words,\nyou can use this function to copy the values from one array into another array.\n\n[^cmemcpy]: <https://www.tutorialspoint.com/c_standard_library/c_function_memcpy.htm>\n\nWe are using this `@memcpy()` built-in function to copy the values that are currently stored\nin the underlying array of the stack object (`self.items`) into our new and bigger array that\nwe have allocated (`new_buf`). After we execute this function, the `new_buf` contains a copy\nof the values that are present at `self.items`.\n\nNow that we have secured a copy of our current values in the `new_buf` object, we\ncan now free the memory currently allocated at `self.items`. After that, we just need\nto assign our new and bigger array to `self.items`. This is the sequence\nof steps necessary to expand our array.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn push(self: *Stack, val: u32) !void {\n    if ((self.length + 1) > self.capacity) {\n        var new_buf = try self.allocator.alloc(\n            u32, self.capacity * 2\n        );\n        @memcpy(\n            new_buf[0..self.capacity], self.items\n        );\n        self.allocator.free(self.items);\n        self.items = new_buf;\n        self.capacity = self.capacity * 2;\n    }\n\n    self.items[self.length] = val;\n    self.length += 1;\n}\n```\n:::\n\n\nAfter we make sure that we have enough room to store this new value\nthat we are adding to the stack, all we have to do is to assign\nthis value to the top element in this stack, and, increase the\nvalue of the `length` attribute by one. We find the top element\nin the stack by using the `length` attribute.\n\n\n\n### Implementing the `pop` operation\n\nNow we can implement the pop operation of our stack object.\nThis is a much easier operation to implement, and the `pop()` method below summarises\nall the logic that is needed.\n\nWe just have to find the element in the underlying array that currently represents the top\nof the stack, and set this element to \"undefined\", to indicate that\nthis element is \"empty\". After that, we also need to decrease\nthe `length` attribute of the stack by one.\n\nIf the current length of the stack is zero, it means that there is\nno values being stored in the stack currently. So, in this case,\nwe could just return from the function and do nothing really.\nThis is what the if statement inside this function is checking for.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn pop(self: *Stack) void {\n    if (self.length == 0) return;\n\n    self.items[self.length - 1] = undefined;\n    self.length -= 1;\n}\n```\n:::\n\n\n\n\n### Implementing the `deinit` method\n\nWe have implemented the methods responsible for the two main operations\nassociated with the stack data structure, which is `pop()` and `push()`,\nand we also have implemented the method responsible for instantiating\na new `Stack` object, which is the `init()` method.\n\nBut now, we need to implement also the method responsible for destroying\na `Stack` object. In Zig, this task is commonly associated with the method\nnamed `deinit()`. Most struct objects in Zig have such method, and it\nis commonly nicknamed \"the destructor method\".\n\nIn theory, all we have to do to destroy the `Stack` object is to make\nsure that we free the allocated memory for the underlying array, using\nthe allocator object that is stored inside the `Stack` object.\nThis is what the `deinit()` method below is doing.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn deinit(self: *Stack) void {\n    self.allocator.free(self.items);\n}\n```\n:::\n\n\n\n\n\n## Making it generic\n\nNow that we have implemented the basic skeleton of our stack data structure,\nwe can now focus on discussing how we can make it generic. How can we make\nthis basic skeleton to work not only with `u32` values, but also with any other\ndata type we want?\nFor example, we might need to create a stack object to store `User` values\nin it. How can we make this possible? The answer lies in the use of generics\nand `comptime`.\n\nAs I described in @sec-generic-struct, the basic idea is to write a generic\nfunction that returns a struct definition as output.\nIn theory, we do not need much to transform our `Stack` struct into a generic\ndata structure. All that we need to do is to transform the underlying array\nof the stack into a generic array.\n\nIn other words, this underlying array needs to be a \"chameleon\". It needs to adapt,\nand transform it into an array of any data type that we want. For example, if we need to create\na stack that will store `u8` values, then this underlying array needs to be\na `u8` array (i.e., `[]u8`). But if we need to store `User` values instead, then,\nthis array needs to be a `User` array (i.e., `[]User`). Etc.\n\nWe do that by using a generic function. Because a generic function can receive a data type\nas input, and we can pass this data type to the struct definition of our `Stack` object.\nTherefore, we can use the generic function to create a `Stack` object that can store\nthe data type we want. If we want to create a stack structure that stores `User` values,\nwe pass the `User` data type to this generic function, and it will create for us\nthe struct definition that describes a `Stack` object that can store `User` values in it.\n\nLook at the code example below. I have omitted some parts of the `Stack` struct definition\nfor brevity. However, if a specific part of our `Stack` struct is not exposed here\nin this example, then it's because this part did not change from the previous example.\nIt remains the same.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn Stack(comptime T: type) type {\n    return struct {\n        items: []T,\n        capacity: usize,\n        length: usize,\n        allocator: Allocator,\n        const Self = @This();\n\n        pub fn init(allocator: Allocator,\n                    capacity: usize) !Stack(T) {\n            var buf = try allocator.alloc(T, capacity);\n            return .{\n                .items = buf[0..],\n                .capacity = capacity,\n                .length = 0,\n                .allocator = allocator,\n            };\n        }\n\n        pub fn push(self: *Self, val: T) !void {\n        // Truncate the rest of the struct\n    };\n}\n```\n:::\n\n\nNotice that we have created a function in this example named `Stack()`. This function\ntakes a type as input, and passes this type to the struct definition of our\n`Stack` object. The data member `items` is now, an array of type `T`, which is the\ndata type that we have provided as input to the function. The function argument\n`val` in the `push()` function is now a value of type `T` too.\n\nWe can just provide a data type to this function, and it will create a definition of a\n`Stack` object that can store values of the data type that we have provided. In the example below, we are creating\nthe definition of a\n`Stack` object that can store `u8` values in it. This definition is stored at the `Stacku8` object.\nThis `Stacku8` object becomes our new struct, that we are going to use\nto create our `Stack` object.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar gpa = std.heap.GeneralPurposeAllocator(.{}){};\nconst allocator = gpa.allocator();\nconst Stacku8 = Stack(u8);\nvar stack = try Stacku8.init(allocator, 10);\ndefer stack.deinit();\ntry stack.push(1);\ntry stack.push(2);\ntry stack.push(3);\ntry stack.push(4);\ntry stack.push(5);\ntry stack.push(6);\n\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\"Stack capacity: {d}\\n\", .{stack.capacity});\n\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstack.pop();\nstd.debug.print(\"Stack len: {d}\\n\", .{stack.length});\nstd.debug.print(\n    \"Stack state: {any}\\n\",\n    .{stack.items[0..stack.length]}\n);\n```\n:::\n\n\n```\nStack len: 6\nStack capacity: 10\nStack len: 5\nStack len: 4\nStack state: { 1, 2, 3, 4, 0, 0, 0, 0, 0, 0 }\n```\n\nEvery generic data structure in the Zig Standard Library (`ArrayList`, `HashMap`, `SinlyLinkedList`, etc.)\nis implemented through this logic. They use a generic function to create the struct definition that can work\nwith the data type that you provided as input.\n\n\n\n\n## Conclusion\n\nThe full source code of the stack structure discussed in this chapter is freely available in the official\nrepository of this book. Just checkout the [`stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig)[^zig-stack]\nfor the `u32` version of our stack,\nand the [`generic_stack.zig`](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig)[^zig-stack2]\nfor the generic version, available inside the `ZigExamples` folder of the repository.\n\n\n[^zig-stack]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/stack.zig>\n[^zig-stack2]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/data-structures/generic_stack.zig>\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
diff --git a/_freeze/Chapters/12-file-op/execute-results/epub.json b/_freeze/Chapters/12-file-op/execute-results/epub.json
deleted file mode 100644
index acf050fc..00000000
--- a/_freeze/Chapters/12-file-op/execute-results/epub.json
+++ /dev/null
@@ -1,21 +0,0 @@
-{
-  "hash": "1e79228e1613c85b9e688833811e2fda",
-  "result": {
-    "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Filesystem and Input/Output (IO) {#sec-filesystem}\n\nIn this chapter we are going to discuss how to use the cross-platform structs and functions\nfrom the Zig Standard Library that can execute filesystem operations. Most of these functions and structs\ncomes from the `std.fs` module.\n\nWe are also going to talk about Input/Output (also known as IO) operations in Zig. Most of\nthese operations are made by using the structs and functions from `std.io` module, which defines\nfile descriptors for the *standard channels* of your system (`stdout` and `stdin`), and also,\nfunctions to create and use I/O streams.\n\n\n## Input/Output basics {#sec-io-basics}\n\nIf you have some experience in a high-level language, you have certainly used\nthese input and output functionalities before in this language. In other words, you certainly have\nbeen in a situation where you needed to sent some output to the user, or, to receive an input\nfrom the user.\n\nFor example, in Python we can receive some input from the user by using the `input()` built-in\nfunction. But we can also print (or \"show\") some output to the user by using the `print()`\nbuilt-in function. So yes, if you have programmed before in Python, you certainly have\nused these functions once before.\n\nBut do you know how these functions relate back to your operating system (OS)? How exactly\nthey are interacting with the resources of your OS to receive or sent some input/output.\nIn essence, these input/output functions from high-level languages are just abstractions\nover the *standard output* and *standard input* channels of your operating system.\n\nThis means that we receive an input, or send some output, through the operating system.\nIt's the OS that makes the bridge between the user and your program. Your program\ndoes not have a direct access to the user. It's the OS that intermediates every\nmessage exchanged between your program and the user.\n\nThe *standard output* and *standard input* channels of your OS are commonly known as the\n`stdout` and `stdin` channels of your OS, respectively. In some contexts, they are also\ncalled the *standard output device* and the *standard input device*. As the name suggests,\nthe *standard output* is the channel through which output flows, while the *standard input*\nis the channel in which input flows.\n\nFurthermore, OS's also normally create a dedicated channel for exchanging error messages, which is known as the\n*standard error* channel, or, the `stderr` channel. This is the channel to which error and warning messages\nare usually sent to. These are the messages that are normally displayed in red-like or orange-like colors\ninto your terminal.\n\nNormally, every OS (e.g. Windows, macOS, Linux, etc.) creates a dedicated and separate set of\n*standard output*, *standard error* and *standard input* channels for every single program (or process) that runs in your computer.\nThis means that every program you write have a dedicated `stdin`, `stderr` and `stdout` that are separate\nfrom the `stdin`, `stderr` and `stdout` of other programs and processes that are currently running.\n\nThis is a behaviour from your OS. This does not come from the programming language that you are using.\nBecause as I sad earlier, input and output in programming languages, especially\nin high-level ones, are just a simple abstraction over the `stdin`, `stderr` and `stdout` from your current OS.\nThat is, your OS is the intermediary between every input/output operation made in your program,\nregardless of the programming language that you are using.\n\n\n### The writer and reader pattern {#sec-writer-reader}\n\nIn Zig, there is a pattern around input/output (IO). I (the author of this book) don't know if there\nis an official name for this pattern. But here, in this book, I will call it the \"writer and reader pattern\".\nIn essence, every IO operation in Zig is made through either a `GenericReader` or a `GenericWriter` object[^gen-zig].\n\nThese two data types come from the `std.io` module of the Zig Standard Library. As their names suggests, a\n`GenericReader` is an object that offers tools to read data from \"something\" (or \"somewhere\"), while a `GenericWriter`\noffers tools to write data into this \"something\". This \"something\" might be different things: like a\nfile that exists in your filesystem; or, it might be a network socket in your system[^sock]; or,\na continuous stream of data, like a standard input device from your system, that might be constantly\nreceiving new data from users, or, as another example, a live chat in a game that is constantly\nreceiving and displaying new messages from the players of the game.\n\n[^gen-zig]: Previously, these objects were known as the `Reader` and `Writer` objects.\n[^sock]: The socket objects that we have created in @sec-create-socket, are examples of network sockets.\n\nSo, if you want to **read** data from something, or somewhere, it means that you need to use a `GenericReader` object.\nBut if you need instead, to **write** data into this \"something\", then, you need to use a `GenericWriter` object instead.\nBoth of these objects are normally created from a file descriptor object. More specifically, through the `writer()` and `reader()`\nmethods of this file descriptor object. If you are not familiar with this type of object, go to the next section.\n\nEvery `GenericWriter` object have methods like `print()`, which allows you to write/send a formatted string\n(i.e., this formatted string is like a `f` string in Python, or, similar to the `printf()` C function)\ninto the \"something\" (file, socket, stream, etc.) that you are using. It also have a `writeAll()` method, which allows you to\nwrite a string, or, an array of bytes into the \"something\".\n\nLikewise, every `GenericReader` object have methods like `readAll()`, which allows you to read the\ndata from the \"something\" (file, socket, stream, etc.) until it fills a particular array (i.e., a \"buffer\") object.\nIn other words, if you provide an array object of 300 `u8` values to `readAll()`, then, this method attempts to read 300 bytes\nof data from the \"something\", and it stores them into the array object that you have provided.\n\nWe also have other methods, like the `readAtLeast()` method, which allows you to specify how\nmany bytes exactly you want to read from the \"something\". In more details, if you give the\nnumber $n$ as input to this method, then, it will attempt to read at least $n$ bytes of data\nfrom the \"something\". The \"something\" might have less than $n$ bytes of data available for you\nto read, so, it's not guaranteed that you will get precisely $n$ bytes as result.\n\nAnother useful method is `readUntilDelimiterOrEof()`. In this method, you specify a \"delimiter character\".\nThe idea is that this function will attempt to read as many bytes of data as possible from the \"something\",\nuntil it encounters the end of the stream, or, it encounters the \"delimiter character\" that you have specified.\n\nIf you don't know exactly how many bytes will come from the \"something\", you may find the `readAllAlloc()` method\nuseful. In essence, you provide an allocator object to this method, so that it can allocate more space if needed.\nAs consequence, this method will try to read all bytes of the \"something\", and, if it runs out of space at some point\nduring the \"reading process\", it uses the allocator object to allocate more space to continue reading the bytes.\nAs result, this method returns a slice to the array object containing all the bytes read.\n\nThis is just a quick description of the methods present in these types of objects. But I recommend you\nto read the official docs, both for\n[`GenericWriter`](https://ziglang.org/documentation/master/std/#std.io.GenericWriter)[^gen-write] and\n[`GenericReader`](https://ziglang.org/documentation/master/std/#std.io.GenericReader)[^gen-read].\nI also think it's a good idea to read the source code of the modules in the Zig Standard Library\nthat defines the methods present in these objects, which are the\n[`Reader.zig`](https://github.com/ziglang/zig/blob/master/lib/std/io/Reader.zig)[^mod-read]\nand [`Writer.zig`]()[^mod-write].\n\n[^gen-read]: <https://ziglang.org/documentation/master/std/#std.io.GenericReader>.\n[^gen-write]: <https://ziglang.org/documentation/master/std/#std.io.GenericWriter>.\n[^mod-read]: <https://github.com/ziglang/zig/blob/master/lib/std/io/Reader.zig>.\n[^mod-write]: <https://github.com/ziglang/zig/blob/master/lib/std/io/Writer.zig>.\n\n\n\n### Introducing file descriptors {#sec-file-descriptor}\n\nA \"file descriptor\" object is a core component behind every IO operation that is made in any operating system (OS).\nSuch object is an identifier for a particular input/output (IO) resource from your OS [@wiki_file_descriptor].\nIt describes and identifies this particular resource. An IO resource might be:\n\n- an existing file in your filesystem.\n- an existing network socket.\n- other types of stream channels.\n- a pipeline (or just \"pipe\") in your terminal[^pipes].\n\n[^pipes]: A pipeline is a mechanism for inter-process communication, or, inter-process IO. You could also interpret a pipeline as a \"set of processes that are chained together, through the standard input/output devices of the system\". At Linux for example, a pipeline is created inside a terminal, by connecting two or more terminal commands with the \"pipe\" character (`|`).\n\nFrom the bullet points listed above, we know that although the term \"file\" is present,\na \"file descriptor\" might describe something more than just a file.\nThis concept of a \"file descriptor\" comes from the Portable Operating System Interface (POSIX) API,\nwhich is a set of standards that guide how operating systems across the world should be implemented,\nto maintain compatibility between them.\n\nA file descriptor not only identifies the input/output resource that you are using to receive or send some data,\nbut it also describes where this resource is, and also, which IO mode this resource is currently using.\nFor example, this IO resource might be using only the \"read\" IO mode, which means that this resource\nis open to \"read operations\", while \"write operations\" are not authorized.\nThese IO modes are essentially the modes that you provide to the argument `mode`\nfrom the `fopen()` C function, and also, from the `open()` Python built-in function.\n\nIn C, a \"file descriptor\" is a `FILE` pointer, but, in Zig, a file descriptor is a `File` object.\nThis data type (`File`) is described in the `std.fs` module of the Zig Standard Library.\nWe normally don't create a `File` object directly in our Zig code. Instead, we normally get such object as result when we\nopen an IO resource. In other words, we normally ask our OS to open a particular IO resource for us,\nand, if the OS do open successfully this IO resource, the OS normally handles back to us\na file descriptor to this particular IO resource.\n\nSo you usually get a `File` object by using functions and methods from the Zig Standard Library\nthat asks the OS to open some IO resource, like the `openFile()` method that opens a file in the\nfilesystem. The `net.Stream` object that we have created in @sec-create-socket is also a type of\nfile descriptor object.\n\n\n### The *standard output*\n\nYou already saw across this book, how can we access and use specifically the `stdout` in Zig\nto send some output to the user.\nFor that, we use the `getStdOut()` function from the `std.io` module. This function returns\na file descriptor that describes the `stdout` channel of your current OS. Through this file\ndescriptor object, we can read from or write stuff to the `stdout` of our program.\n\nAlthough we can read stuff recorded into the `stdout` channel, we normally only\nwrite to (or \"print\") stuff into this channel. The reason is very similar to what we discussed at\n@sec-read-http-message, when we were discussing what \"reading from\" versus \"writing to\" the connection\nobject from our small HTTP Server project would mean.\n\nWhen we write stuff into a channel, we are essentially sending data to the other end of this channel.\nIn contrast, when we read stuff from this channel, we are essentially reading the data that was sent\nthrough this channel. Since the `stdout` is a channel to send output to the user, the key verb here\nis **send**. We want to send something to someone, and, as consequence, we want to **write** something\ninto some channel.\n\nThat is why, when we use `getStdOut()`, most of the times, we also use the `writer()` method from the `stdout` file descriptor,\nto get access to a writer object that we can use to write stuff into this `stdout` channel.\nMore specifically, this `writer()` method returns a `GenericWriter` object. One of the\nmain methods of this `GenericWriter` object is the `print()` method that we have used\nbefore to write (or \"print\") a formatted string into the `stdout` channel.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    try stdout.writeAll(\n        \"This message was written into stdout.\\n\"\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nThis message was written into stdout.\n```\n\n\n:::\n:::\n\n\n\n\n\nThis `GenericWriter` object is like any other generic writer object that you would normally get from a file descriptor object.\nSo, the same methods from a generic writer object that you would use while writing files to the filesystem for example, you could also\nuse them here, from the file descriptor object of `stdout`, and vice-versa.\n\n\n### The *standard input*\n\nYou can access the *standard input* (i.e., `stdin`) in Zig by using the `getStdIn()` function from the `std.io` module.\nLike its brother (`getStdOut()`), this function also returns a file descriptor object that describes the `stdin` channel\nof your OS.\n\nBecause we want to receive some input from the user, the key verb here becomes **receive**, and, as consequence,\nwe usually want to **read** data from the `stdin` channel, instead of writing data into it. So, we normally use\nthe `reader()` method of the file descriptor object returned by `getStdIn()`, to get access to a `GenericReader`\nobject that we can use to read data from `stdin`.\n\nIn the example below, we are creating a small buffer capable of holding 20 characters. Then, we try to read\nthe data from the `stdin` with the `readUntilDelimiterOrEof()` method, and save this data into the `buffer` object.\nAlso notice that we are reading the data from the `stdin` until we hit a new line character (`'\\n'`).\n\nIf you execute this program, you will notice that it stops the execution, ands start to wait indefinitely\nfor some input from the user. In other words, you need to type your name into the terminal, and then, you press Enter to\nsend your name to `stdin`. After you send your name to `stdin`, the program reads this input, and continues with the execution,\nby printing the given name to `stdout`. In the example below, I typed my name (Pedro) into the terminal, and then, pressed Enter.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst stdin = std.io.getStdIn().reader();\npub fn main() !void {\n    try stdout.writeAll(\"Type your name\\n\");\n    var buffer: [20]u8 = undefined;\n    @memset(buffer[0..], 0);\n    _ = try stdin.readUntilDelimiterOrEof(buffer[0..], '\\n');\n    try stdout.print(\"Your name is: {s}\\n\", .{buffer});\n}\n```\n:::\n\n\n\n```\nType your name\nYour name is: Pedro\n\n```\n\n\n### The *standard error*\n\nThe *standard error* (a.k.a. the `stderr`) works exactly the same as `stdout` and `stdin`.\nYou just call the `getStdErr()` function from the `std.io` module, and you get the file descriptor to `stderr`.\nIdeally, you should write only error or warning messages to `stderr`, because this is\nthe purpose of this channel.\n\n\n\n\n\n## Buffered IO\n\nAs we described in @sec-io-basics, input/output (IO) operations are made directly by the operating system.\nIt's the OS that manages the IO resource that you want to use for your IO operations.\nThe consequence of this fact is that IO operations are heavily based on system calls (i.e., calling the operating system directly).\n\nJust to be clear, there is nothing particularly wrong with system calls. We use them all the time on\nany serious codebase written in any low-level programming language. However, system calls are\nalways orders of magnitude slower than many different types of operations.\n\nSo is perfectly fine to use a system call once in a while. But when these system calls are used often,\nyou can clearly notice most of the time the loss of performance in your application. So, the good rule of thumb\nis to use a system call only when it's needed, and also, only in infrequent situations, to reduce\nthe number of system calls performed to a minimum.\n\n\n### Understanding how buffered IO works\n\nBuffered IO is a strategy to achieve better performance. It's used to reduce the number of system calls made by IO operations, and, as\nconsequence, achieve a much higher performance. In @fig-unbuffered-io and @fig-buffered-io you can find two different diagrams\nwhich presents the difference between read operations performed in an unbuffered IO environment versus a buffered IO environment.\n\nTo give a better context to these diagrams, let's suppose that we have a text file that contains the famous Lorem ipsum text[^lorem]\nin our filesystem. Let's also suppose that these diagrams in @fig-unbuffered-io and @fig-buffered-io\nare showing the read operations that we are performing to read the Lorem ipsum text from this text file.\nThe first thing you will notice when looking at these diagrams, is that in an unbuffered environment\nthe read operations leads to many system calls.\nMore precisely, in the diagram exposed in @fig-unbuffered-io we get one system call per each byte that we read from the text file.\nOn the other hand, in @fig-buffered-io we have only one system call at the very beginning.\n\nWhen we use a buffered IO system, at the first read operation we perform, instead of sending one single byte directly\nto our program, the OS first sends a chunk of bytes from the file to a buffer object (i.e., an array).\nThis chunk of bytes are cached/stored inside this buffer object.\n\nTherefore, from now on, for every new read operation that you perform, instead of making a new system call to ask\nfor the next byte in the file to the OS, this read operation is redirected to the buffer object, that have\nthis next byte already cached and ready to go.\n\n\n[^lorem]: <https://www.lipsum.com/>.\n\n\n![Unbuffered IO](./../Figures/unbuffered-io.png){#fig-unbuffered-io width=60%}\n\n![Buffered IO](./../Figures/buffered-io.png){#fig-buffered-io}\n\n\n\nThis is the basic logic behind buffered IO systems. The size of the buffer object depends on multiple factors. But it's usually\nequal to the size of a full page of memory (4096 bytes). If we follow this logic, then, the OS reads the first 4096 bytes\nof the file and caches it into the buffer object. As long as your program does not consume all of these 4096 bytes from the buffer,\nyou will not create new system calls.\n\nHowever, as soon as you consume all of these 4096 bytes from the buffer, it means that there is no bytes left in the buffer.\nIn this situation, a new system call is made to ask the OS to send the next 4096 bytes in the file, and once again,\nthese bytes are cached into the buffer object, and the cycle starts once again.\n\n\n### Buffered IO across different languages\n\nIO operations made through a `FILE` pointer in C are buffered\nby default, so, at least in C, you don't need to worry about this subject. But in contrast, IO operations in both Rust and Zig are not\nbuffered depending on which functions from the standard libraries that you are using.\n\nFor example, in Rust, buffered IO is implemented through the `BufReader` and `BufWriter` structs, while in Zig, it's implemented\nthrough the `BufferedReader` and `BufferedWriter` structs.\nSo any IO operation that you perform through the `GenericWriter` and `GenericReader` objects\nthat I presented in @sec-writer-reader are not buffered, which means that these objects\nmight create a lot of system calls depending on the situation.\n\n\n### Using buffered IO in Zig\n\nUsing buffered IO in Zig is actually very easy. All you have to do is to just\ngive the `GenericWriter` object to the `bufferedWriter()` function, or, to give the `GenericReader`\nobject to the `bufferedReader()` function. These functions come from the `std.io` module,\nand they will construct the `BufferedWriter` or `BufferedReader` object for you.\n\nAfter you create this new `BufferedWriter` or `BufferedReader` object, you can call the `writer()`\nor `reader()` method of this new object, to get access to a new (and buffered) generic reader or\ngeneric writer.\n\nLet's describe the process once again. Every time that you have a file descriptor object, you first get the generic writer or generic reader\nobject from it, by calling the `writer()` or `reader()` methods of this file descriptor object.\nThen, you provide this generic writer or generic reader to the `bufferedWriter()` or `bufferedReader()`\nfunction, which creates a new `BufferedWriter` or `BufferedReader` object. Then, you call\nthe `writer()` or `reader()` methods of this buffered writer or buffered reader object,\nwhich gives you access to a generic writer or a generic reader object that is buffered.\n\nTake this program as an example. This program is demonstrating the process exposed in @fig-buffered-io.\nWe are simply opening a text file that contains the Lorem ipsum text, and then, we create a buffered IO reader object\nat `bufreader`, and we use this `bufreader` object to read the contents of this file into a buffer object, then,\nwe end the program by printing this buffer to `stdout`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar file = try std.fs.cwd().openFile(\n    \"ZigExamples/file-io/lorem.txt\", .{}\n);\ndefer file.close();\nvar buffered = std.io.bufferedReader(file.reader());\nvar bufreader = buffered.reader();\n\nvar buffer: [1000]u8 = undefined;\n@memset(buffer[0..], 0);\n\n_ = try bufreader.readUntilDelimiterOrEof(\n    buffer[0..], '\\n'\n);\ntry stdout.print(\"{s}\\n\", .{buffer});\n```\n:::\n\n\n\n```\nLorem ipsum dolor sit amet, consectetur\nadipiscing elit. Sed tincidunt erat sed nulla ornare, nec\naliquet ex laoreet. Ut nec rhoncus nunc. Integer magna metus,\nultrices eleifend porttitor ut, finibus ut tortor. Maecenas\nsapien justo, finibus tincidunt dictum ac, semper et lectus.\nVivamus molestie egestas orci ac viverra. Pellentesque nec\narcu facilisis, euismod eros eu, sodales nisl. Ut egestas\nsagittis arcu, in accumsan sapien rhoncus sit amet. Aenean\nneque lectus, imperdiet ac lobortis a, ullamcorper sed massa.\nNullam porttitor porttitor erat nec dapibus. Ut vel dui nec\nnulla vulputate molestie eget non nunc. Ut commodo luctus ipsum,\nin finibus libero feugiat eget. Etiam vel ante at urna tincidunt\nposuere sit amet ut felis. Maecenas finibus suscipit tristique.\nDonec viverra non sapien id suscipit.\n```\n\nDespite being a buffered IO reader, this `bufreader` object is similar to any other `GenericReader` object,\nand have the exact same methods. So, although these two types of objects perform very different IO operations,\nthey have the same interface, so you, the programmer, can interchangeably use them\nwithout the need to change anything in your source code.\nSo a buffered IO reader or a buffered IO writer objects have the same methods than its generic and unbuffered brothers,\ni.e., the generic reader and generic writer objects that I presented in @sec-writer-reader.\n\n::: {.callout-tip}\nIn general, you should always use a buffered IO reader or a buffered IO writer object to perform\nIO operations in Zig. Because they deliver better performance to your IO operations.\n:::\n\n\n## Filesystem basics\n\nNow that we have discussed the basics around Input/Output operations in Zig, we need to\ntalk about the basics around filesystems, which is another core part of any operating system.\nAlso, filesystems are related to input/output, because the files that we store and create in our\ncomputer are considered an IO resource, as we described in @sec-file-descriptor.\n\n\n### The concept of current working directory (CWD)\n\nThe working directory is the folder on your computer where you are currently rooted at.\nIn other words, it's the folder that your program is currently looking at.\nTherefore, whenever you are executing a program, this program is always working with\na specific folder on your computer. It's always in this folder that the program will initially\nlook for the files you require, and it's also in this folder that the program\nwill initially save all the files you ask it to save.\n\nThe working directory is determined by the folder from which you invoke your program\nin the terminal. In other words, if you are in the terminal of your OS, and you\nexecute a binary file (i.e., a program) from this terminal, the folder to which your terminal\nis pointing at is the current working directory of your program that is being executed.\n\nIn @fig-cwd we have an example of me executing a program from the terminal. We are executing\nthe program outputted by the `zig` compiler by compiling the Zig module named `hello.zig`.\nThe CWD in this case is the `zig-book` folder. In other words, while the `hello.zig` program\nis executing, it will be looking at the `zig-book` folder, and any file operation that we perform\ninside this program, will be using this `zig-book` folder as the \"starting point\", or, as the \"central focus\".\n\n![Executing a program from the terminal](./../Figures/cwd.png){#fig-cwd}\n\nJust because we are rooted inside a particular folder (in the case of @fig-cwd, the `zig-book` folder) of our computer,\nit doesn't mean that we cannot access or write resources in other locations of our computer.\nThe current working directory (CWD) mechanism just defines where your program will look first\nfor the files you ask for. This does not prevent you from accessing files that are located\nelsewhere on your computer. However, to access any file that is in a folder other than your\ncurrent working directory, you must provide a path to that file or folder.\n\n\n### The concept of paths\n\nA path is essentially a location. It points to a location in your filesystem. We use\npaths to describe the location of files and folders in our computer.\nOne important aspect about paths is that they are always written inside strings,\ni.e., they are always provided as text values.\n\nThere are two types of paths that you can provide to any program in any OS: a relative path, or an absolute path.\nAbsolute paths are paths that start at the root of your filesystem, and go all the way to the file name or the specific folder\nthat you are referring to. This type of path is called absolute, because it points to an unique and absolute location on your computer.\nThat is, there is no other existing location on your computer that corresponds to this path. It's an unique identifier.\n\nIn Windows, an absolute path is a path that starts with a hard disk identifier (e.g. `C:/Users/pedro`).\nOn the other hand, absolute paths in Linux and macOS, are paths that start with a forward slash character (e.g. `/usr/local/bin`).\nNotice that a path is composed by \"segments\". Each segment is connected to each other by a slash character (`\\` or `/`).\nOn Windows, the backward slash (`\\`) is normally used to connect the path segments. While on Linux and macOS, the forward\nslash (`/`) is the character used to connect path segments.\n\nA relative path is a path that start at the CWD. In other words, a relative path is\n\"relative to the CWD\". The path used to access the `hello.zig` file in @fig-cwd is an example of a relative path. This path\nis reproduced below. This path begins at the CWD, which in the context of @fig-cwd, is the `zig-book` folder,\nthen, it goes to the `ZigExamples` folder, then, into `zig-basics`, then, to the `hello.zig` file.\n\n```\nZigExamples/zig-basics/hello_world.zig\n```\n\n\n### Path wildcards\n\nWhen providing paths, especially relative paths, you have the option of using a *wildcard*.\nThere are two commonly used *wildcards* in paths, which are \"one period\" (.) and \"two periods\" (..).\nIn other words, these two specific characters have special meanings when used in paths,\nand can be used on any operating system (Mac, Windows, Linux, etc.). That is, they\nare \"cross platform\".\n\nThe \"one period\" represents an alias for the current directory.\nThis means that the relative paths `\"./Course/Data/covid.csv\"` and `\"Course/Data/covid.csv\"` are equivalent.\nOn the other hand, the \"two periods\" refers to the previous directory.\nFor example, the path `\"Course/..\"` is equivalent to the path `\".\"`, that is, the current working directory.\n\nTherefore, the path `\"Course/..\"` refers to the folder before the `Course` folder.\nAs another example, the path `\"src/writexml/../xml.cpp\"` refers to the file `xml.cpp`\nthat is inside the folder before the `writexml` folder, which in this example is the `src` folder.\nTherefore, this path is equivalent to `\"src/xml.cpp\"`.\n\n\n\n\n## The CWD handler\n\nIn Zig, filesystem operations are usually made through a directory handler object.\nA directory handler in Zig is an object of type `Dir`, which is an object that describes\na particular folder in the filesystem of our computer.\nYou normally create a `Dir` object, by calling the `std.fs.cwd()` function.\nThis function returns a `Dir` object that points to (or, that describes) the\ncurrent working directory (CWD).\n\nThrough this `Dir` object, you can create new files, or modify, or read existing ones that are\ninside your CWD. In other words, a `Dir` object is the main entrypoint in Zig to perform\nmultiple types of filesystem operations.\nIn the example below, we are creating this `Dir` object, and storing it\ninside the `cwd` object. Although we are not using this object at this code example,\nwe are going to use it a lot over the next examples.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\n_ = cwd;\n```\n:::\n\n\n\n\n\n\n\n\n\n\n## File operations\n\n### Creating files {#sec-creating-files}\n\nWe create new files by using the `createFile()` method from the `Dir` object.\nJust provide the name of the file that you want to create, and this function will\ndo the necessary steps to create such file. You can also provide a relative path to this function,\nand it will create the file by following this path, which is relative to the CWD.\n\nThis function might return an error, so, you should use `try`, `catch`, or any of the other methods presented\nin @sec-error-handling to handle the possible error. But if everything goes well,\nthis `createFile()` method returns a file descriptor object (i.e., a `File` object) as result,\nthrough which you can add content to the file with the IO operations that I presented before.\n\nTake this code example below. In this example, we are creating a new text file\nnamed `foo.txt`. If the function `createFile()` succeeds, the object named `file` will contain a file descriptor\nobject, which we can use to write (or add) new content to the file, like we do in this example, by using\na buffered writer object to write a new line of text to the file.\n\nNow, a quick note, when we create a file descriptor object in C, by using a C function like `fopen()`, we must always close the file\nat the end of our program, or, as soon as we complete all operations that we wanted to perform\non the file. In Zig, this is no different. So everytime we create a new file, this file remains\n\"open\", waiting for some operation to be performed. As soon as we are done with it, we always have\nto close this file, to free the resources associated with it.\nIn Zig, we do this by calling the method `close()` from the file descriptor object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.createFile(\"foo.txt\", .{});\n// Don't forget to close the file at the end.\ndefer file.close();\n// Do things with the file ...\nvar fw = file.writer();\n_ = try fw.writeAll(\n    \"Writing this line to the file\\n\"\n);\n```\n:::\n\n\n\n\nSo, in this example we not only have created a file into the filesystem,\nbut we also wrote some data into this file, using the file descriptor object\nreturned by `createFile()`. If the file that you are trying to create\nalready exists in your filesystem, this `createFile()` call will\noverwrite the contents of the file, or, in other words, it will\nin erase all the contents of the existing file.\n\nIf you don't want this to happen, meaning, that you don't want to overwrite\nthe contents of the existing file, but you want to write data to this file anyway\n(i.e., you want to append data to the file), you should use the `openFile()`\nmethod from the `Dir` object.\n\nAnother important aspect about `createFile()` is that this method creates a file\nthat is not open to read operations by default. It means that you cannot read this file.\nYou are not allowed to.\nSo for example, you might want to write some stuff into this file at the beginning of the execution\nof your program. Then, at a future point in your program you might need to read what you\nwrote in this file. If you try to read data from this file, you will likely\nget a `NotOpenForReading` error as result.\n\n\nBut how can you overcome this barrier? How can you create a file that is open\nto read operations? All you have to do, is to set the `read` flag to true\nin the second argument of `createFile()`. When you set this flag to true,\nthen the file gets create with \"read permissions\", and, as consequence,\na program like this one below becomes valid:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.createFile(\n    \"foo.txt\",\n    .{ .read = true }\n);\ndefer file.close();\n\nvar fw = file.writer();\n_ = try fw.writeAll(\"We are going to read this line\\n\");\n\nvar buffer: [300]u8 = undefined;\n@memset(buffer[0..], 0);\ntry file.seekTo(0);\nvar fr = file.reader();\n_ = try fr.readAll(buffer[0..]);\ntry stdout.print(\"{s}\\n\", .{buffer});\n```\n:::\n\n\n\n\n```\nWe are going to read this line\n```\n\n\nIf you are not familiar with position indicators, you might not recognize the method\n`seekTo()`. If that is your case, do not worry,\nwe are going to talk more about this method in @sec-indicators. But essentially\nthis method is moving the position indicator back to the beginning of the file,\nso that we can read the contents of the file from the beginning.\n\n\n### Opening files and appending data to it\n\nOpening files is easy. Just use the `openFile()` method instead of `createFile()`.\nIn the first argument of `openFile()` you provide the path to the file that\nyou want to open. Then, on the second argument you provide the flags (or, the options)\nthat dictates how the file is opened.\n\nYou can see the full list of options for `openFile()` by visiting the documentation for\n[`OpenFlags`](https://ziglang.org/documentation/master/std/#std.fs.File.OpenFlags)[^oflags].\nBut the main flag that you will most certainly use is the `mode` flag.\nThis flag specifies the IO mode that the file will be using when it gets opened.\nThere are three IO modes, or, three values that you can provide to this flag, which are:\n\n- `read_only`, allows only read operations on the file. All write operations are blocked.\n- `write_only`, allows only write operations on the file. All read operations are blocked.\n- `read_write`, allows both write and read operations on the file.\n\n[^oflags]: <https://ziglang.org/documentation/master/std/#std.fs.File.OpenFlags>\n\nThese modes are similar to the modes that you provide to the `mode` argument of the\n`open()` Python built-in function[^py-open], or, the `mode` argument of the\n`fopen()` C function[^c-open].\nIn the code example below, we are opening the `foo.txt` text file with a `write_only` mode,\nand appending a new line of text to the end of the file. We use `seekFromEnd()` this time\nto guarantee that we are going to append the text to the end of the file. Once again, methods\nsuch as `seekFromEnd()` are described in more depth in @sec-indicators.\n\n[^py-open]: <https://docs.python.org/3/tutorial/inputoutput.html#reading-and-writing-files>\n[^c-open]: <https://www.tutorialspoint.com/c_standard_library/c_function_fopen.htm>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.openFile(\n    \"foo.txt\", .{ .mode = .write_only }\n);\ndefer file.close();\ntry file.seekFromEnd(0);\nvar fw = file.writer();\n_ = try fw.writeAll(\"Some random text to write\\n\");\n```\n:::\n\n\n\n\n### Deleting files\n\nSometimes, we just need to delete/remove the files that we have.\nTo do that, we use the `deleteFile()` method. You just provide the path of the\nfile that you want to delete, and this method will try to delete the file located\nat this path.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.deleteFile(\"foo.txt\");\n```\n:::\n\n\n\n### Copying files\n\nTo copy existing files, we use the `copyFile()` method. The first argument in this method\nis the path to the file that you want to copy. The second argument is a `Dir` object, i.e., a directory handler,\nmore specifically, a `Dir` object that points to the folder in your computer where you want to\ncopy the file to. The third argument is the new path of the file, or, in other words, the new location\nof the file. The fourth argument is the options (or flags) to be used in the copy operation.\n\nThe `Dir` object that you provide as input to this method will be used to copy the file to\nthe new location. You may create this `Dir` object before calling the `copyFile()` method.\nMaybe you are planning to copy the file to a completely different location in your computer,\nso it might be worth to create a directory handler to that location. But if you are copying the\nfile to a subfolder of your CWD, then, you can just simply pass the CWD handler to this argument.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.copyFile(\n    \"foo.txt\",\n    cwd,\n    \"ZigExamples/file-io/foo.txt\",\n    .{}\n);\n```\n:::\n\n\n\n\n### Read the docs!\n\nThere are some other useful methods for file operations available at `Dir` objects,\nsuch as the `writeFile()` method, but I recommend you to read the docs for the\n[`Dir` type](https://ziglang.org/documentation/master/std/#std.fs.Dir)[^zig-dir]\nto explore the other available methods, since I already talked too much about them.\n\n\n[^zig-dir]: <https://ziglang.org/documentation/master/std/#std.fs.Dir>\n\n\n\n\n## Position indicators {#sec-indicators}\n\nA position indicator is like a type of cursor, or, an index. This \"index\" identifies the current\nlocation in the file (or, in the data stream) that the file descriptor object that you have\nis currently looking at.\nWhen you create a file descriptor, the position indicator starts at the beginning of the file,\nor, at the beginning of the stream. When you read from or write into the file (or socket, or data stream, etc.)\ndescribed by this file descriptor object, you end up moving the position indicator.\n\nIn other words, any IO operation have a common side effect, which is to move the position indicator.\nFor example, suppose that we have a file of 300 bytes total in size. If you\nread 100 bytes from the file, then, the position indicator moves 100 bytes forward. If you try\nto write 50 bytes into this same file, these 50 bytes will be written from the current\nposition indicated by the position indicator. Since the indicator is at a 100 bytes forward from\nthe beginning of the file, these 50 bytes would be written in the middle of the file.\n\nThis is why we have used the `seekTo()` method at the last code example presented in @sec-creating-files.\nWe have used this method to move the position indicator back to the beginning of the file, which\nwould make sure that we would write the text that we wanted to write from the beginning of the file,\ninstead of writing it from the middle of the file. Because before the write operation, we had\nperformed a read operation, which means that the position indicator was moved in this read operation.\n\nThe position indicators of a file descriptor object can be changed (or altered) by using the\n\"seek\" methods from this file descriptor, which are: `seekTo()`, `seekFromEnd()` and `seekBy()`.\nThese methods have the same effect, or, the same responsibility that the\n[`fseek()`](https://en.cppreference.com/w/c/io/fseek)[^c-fseek] C function.\n\n[^c-fseek]: <https://en.cppreference.com/w/c/io/fseek>\n\n\nConsidering that `offset` refers to the index that you provide as input to these \"seek\" methods,\nthe bullet points below summarises what is the effect of each of these methods.\nAs a quick note, in the case of `seekFromEnd()` and `seekBy()`, the `offset` provided can be either a\npositive or a negative index.\n\n- `seekTo()` will move the position indicator to the location that is `offset` bytes from the beginning of the file.\n- `seekFromEnd()` will move the position indicator to the location that is `offset` bytes from the end of the file.\n- `seekBy()` will move the position indicator to the location that is `offset` bytes from the current position in the file.\n\n\n\n\n\n\n\n## Directory operations\n\n### Iterating through the files in a directory\n\nOne of the most classic tasks related to filesystem is to be able\nto iterate through the existing files in a directory. To iterate over the\nfiles in a directory, we need to create an iterator object.\n\nYou can produce such iterator object by using either the `iterate()` or `walk()` methods\nof a `Dir` object. Both methods return an iterator object as output, which you can advance by using the\n`next()` method. The difference between these methods, is that `iterate()` returns a non-recursive iterator,\nwhile `walk()` does. It means that the iterator returned by `walk()` will not only iterate through\nthe files available in the current directory, but also, through the files from any subdirectory found\ninside the current directory.\n\nIn the example below, we are displaying the names of the files stored inside the\ndirectory `ZigExamples/file-io`. Notice that we had to open this directory through\nthe `openDir()` function. Also notice that we provided the flag `iterate` in the\nsecond argument of `openDir()`. This flag is important, because without this flag,\nwe would not be allowed to iterate through the files in this directory.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst dir = try cwd.openDir(\n    \"ZigExamples/file-io/\",\n    .{ .iterate = true }\n);\nvar it = dir.iterate();\nwhile (try it.next()) |entry| {\n    try stdout.print(\n        \"File name: {s}\\n\",\n        .{entry.name}\n    );\n}\n```\n:::\n\n\n\n```\nFile name: create_file_and_write_toit.zig\nFile name: create_file.zig\nFile name: lorem.txt\nFile name: iterate.zig\nFile name: delete_file.zig\nFile name: append_to_file.zig\nFile name: user_input.zig\nFile name: foo.txt\nFile name: create_file_and_read.zig\nFile name: buff_io.zig\nFile name: copy_file.zig\n```\n\n\n### Creating new directories\n\nThere are two methods that are important when it comes to\ncreating directories, which are `makeDir()` and `makePath()`.\nThe difference between these two methods is that `makeDir()` can\nonly create one single directory in the current directory in each call,\nwhile `makePath()` is capable of recursively create subdirectories in the same call.\n\n\nThis is why the name of this method is \"make path\". It will create as many\nsubdirectories as necessary to create the path that you provided as input.\nSo, if you provide the path `\"sub1/sub2/sub3\"` as input to this method,\nit will create three different subdirectories, `sub1`, `sub2` and `sub3`,\nwithin the same function call. In contrast, if you provided such path\nas input to `makeDir()`, you would likely get an error as result, since\nthis method can only create a single subdirectory.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.makeDir(\"src\");\ntry cwd.makePath(\"src/decoders/jpg/\");\n```\n:::\n\n\n\n### Deleting directories\n\nTo delete a directory, just provide the path to the directory that you want to delete\nas input to the `deleteDir()` method from a `Dir` object. In the example below,\nwe are deleting the `src` directory that we have just created in the previous example.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.deleteDir(\"src\");\n```\n:::\n\n\n\n\n## Conclusion\n\nIn this chapter, I have described how to perform in Zig the most common filesystem and IO operations.\nBut you might feel the lack of some other, less common, operation in this chapter, such as: how to rename files,\nor how to open a directory, or how to create symbolic links, or how to use `access()` to test if a particular\npath exists in your computer. But for all of these less common tasks, I recommend you to read\nthe documentation of the [`Dir` type](https://ziglang.org/documentation/master/std/#std.fs.Dir)[^zig-dir]\n, since you can find a good description of these cases there.\n",
-    "supporting": [
-      "12-file-op_files"
-    ],
-    "filters": [
-      "rmarkdown/pagebreak.lua"
-    ],
-    "includes": {},
-    "engineDependencies": {
-      "knitr": [
-        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
-      ]
-    },
-    "preserve": null,
-    "postProcess": false
-  }
-}
\ No newline at end of file
diff --git a/_freeze/Chapters/12-file-op/execute-results/html.json b/_freeze/Chapters/12-file-op/execute-results/html.json
index f21b00fa..5ebb0a55 100644
--- a/_freeze/Chapters/12-file-op/execute-results/html.json
+++ b/_freeze/Chapters/12-file-op/execute-results/html.json
@@ -2,10 +2,8 @@
   "hash": "1e79228e1613c85b9e688833811e2fda",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n\n# Filesystem and Input/Output (IO) {#sec-filesystem}\n\nIn this chapter we are going to discuss how to use the cross-platform structs and functions\nfrom the Zig Standard Library that can execute filesystem operations. Most of these functions and structs\ncomes from the `std.fs` module.\n\nWe are also going to talk about Input/Output (also known as IO) operations in Zig. Most of\nthese operations are made by using the structs and functions from `std.io` module, which defines\nfile descriptors for the *standard channels* of your system (`stdout` and `stdin`), and also,\nfunctions to create and use I/O streams.\n\n\n## Input/Output basics {#sec-io-basics}\n\nIf you have some experience in a high-level language, you have certainly used\nthese input and output functionalities before in this language. In other words, you certainly have\nbeen in a situation where you needed to sent some output to the user, or, to receive an input\nfrom the user.\n\nFor example, in Python we can receive some input from the user by using the `input()` built-in\nfunction. But we can also print (or \"show\") some output to the user by using the `print()`\nbuilt-in function. So yes, if you have programmed before in Python, you certainly have\nused these functions once before.\n\nBut do you know how these functions relate back to your operating system (OS)? How exactly\nthey are interacting with the resources of your OS to receive or sent some input/output.\nIn essence, these input/output functions from high-level languages are just abstractions\nover the *standard output* and *standard input* channels of your operating system.\n\nThis means that we receive an input, or send some output, through the operating system.\nIt's the OS that makes the bridge between the user and your program. Your program\ndoes not have a direct access to the user. It's the OS that intermediates every\nmessage exchanged between your program and the user.\n\nThe *standard output* and *standard input* channels of your OS are commonly known as the\n`stdout` and `stdin` channels of your OS, respectively. In some contexts, they are also\ncalled the *standard output device* and the *standard input device*. As the name suggests,\nthe *standard output* is the channel through which output flows, while the *standard input*\nis the channel in which input flows.\n\nFurthermore, OS's also normally create a dedicated channel for exchanging error messages, which is known as the\n*standard error* channel, or, the `stderr` channel. This is the channel to which error and warning messages\nare usually sent to. These are the messages that are normally displayed in red-like or orange-like colors\ninto your terminal.\n\nNormally, every OS (e.g. Windows, macOS, Linux, etc.) creates a dedicated and separate set of\n*standard output*, *standard error* and *standard input* channels for every single program (or process) that runs in your computer.\nThis means that every program you write have a dedicated `stdin`, `stderr` and `stdout` that are separate\nfrom the `stdin`, `stderr` and `stdout` of other programs and processes that are currently running.\n\nThis is a behaviour from your OS. This does not come from the programming language that you are using.\nBecause as I sad earlier, input and output in programming languages, especially\nin high-level ones, are just a simple abstraction over the `stdin`, `stderr` and `stdout` from your current OS.\nThat is, your OS is the intermediary between every input/output operation made in your program,\nregardless of the programming language that you are using.\n\n\n### The writer and reader pattern {#sec-writer-reader}\n\nIn Zig, there is a pattern around input/output (IO). I (the author of this book) don't know if there\nis an official name for this pattern. But here, in this book, I will call it the \"writer and reader pattern\".\nIn essence, every IO operation in Zig is made through either a `GenericReader` or a `GenericWriter` object[^gen-zig].\n\nThese two data types come from the `std.io` module of the Zig Standard Library. As their names suggests, a\n`GenericReader` is an object that offers tools to read data from \"something\" (or \"somewhere\"), while a `GenericWriter`\noffers tools to write data into this \"something\". This \"something\" might be different things: like a\nfile that exists in your filesystem; or, it might be a network socket in your system[^sock]; or,\na continuous stream of data, like a standard input device from your system, that might be constantly\nreceiving new data from users, or, as another example, a live chat in a game that is constantly\nreceiving and displaying new messages from the players of the game.\n\n[^gen-zig]: Previously, these objects were known as the `Reader` and `Writer` objects.\n[^sock]: The socket objects that we have created in @sec-create-socket, are examples of network sockets.\n\nSo, if you want to **read** data from something, or somewhere, it means that you need to use a `GenericReader` object.\nBut if you need instead, to **write** data into this \"something\", then, you need to use a `GenericWriter` object instead.\nBoth of these objects are normally created from a file descriptor object. More specifically, through the `writer()` and `reader()`\nmethods of this file descriptor object. If you are not familiar with this type of object, go to the next section.\n\nEvery `GenericWriter` object have methods like `print()`, which allows you to write/send a formatted string\n(i.e., this formatted string is like a `f` string in Python, or, similar to the `printf()` C function)\ninto the \"something\" (file, socket, stream, etc.) that you are using. It also have a `writeAll()` method, which allows you to\nwrite a string, or, an array of bytes into the \"something\".\n\nLikewise, every `GenericReader` object have methods like `readAll()`, which allows you to read the\ndata from the \"something\" (file, socket, stream, etc.) until it fills a particular array (i.e., a \"buffer\") object.\nIn other words, if you provide an array object of 300 `u8` values to `readAll()`, then, this method attempts to read 300 bytes\nof data from the \"something\", and it stores them into the array object that you have provided.\n\nWe also have other methods, like the `readAtLeast()` method, which allows you to specify how\nmany bytes exactly you want to read from the \"something\". In more details, if you give the\nnumber $n$ as input to this method, then, it will attempt to read at least $n$ bytes of data\nfrom the \"something\". The \"something\" might have less than $n$ bytes of data available for you\nto read, so, it's not guaranteed that you will get precisely $n$ bytes as result.\n\nAnother useful method is `readUntilDelimiterOrEof()`. In this method, you specify a \"delimiter character\".\nThe idea is that this function will attempt to read as many bytes of data as possible from the \"something\",\nuntil it encounters the end of the stream, or, it encounters the \"delimiter character\" that you have specified.\n\nIf you don't know exactly how many bytes will come from the \"something\", you may find the `readAllAlloc()` method\nuseful. In essence, you provide an allocator object to this method, so that it can allocate more space if needed.\nAs consequence, this method will try to read all bytes of the \"something\", and, if it runs out of space at some point\nduring the \"reading process\", it uses the allocator object to allocate more space to continue reading the bytes.\nAs result, this method returns a slice to the array object containing all the bytes read.\n\nThis is just a quick description of the methods present in these types of objects. But I recommend you\nto read the official docs, both for\n[`GenericWriter`](https://ziglang.org/documentation/master/std/#std.io.GenericWriter)[^gen-write] and\n[`GenericReader`](https://ziglang.org/documentation/master/std/#std.io.GenericReader)[^gen-read].\nI also think it's a good idea to read the source code of the modules in the Zig Standard Library\nthat defines the methods present in these objects, which are the\n[`Reader.zig`](https://github.com/ziglang/zig/blob/master/lib/std/io/Reader.zig)[^mod-read]\nand [`Writer.zig`]()[^mod-write].\n\n[^gen-read]: <https://ziglang.org/documentation/master/std/#std.io.GenericReader>.\n[^gen-write]: <https://ziglang.org/documentation/master/std/#std.io.GenericWriter>.\n[^mod-read]: <https://github.com/ziglang/zig/blob/master/lib/std/io/Reader.zig>.\n[^mod-write]: <https://github.com/ziglang/zig/blob/master/lib/std/io/Writer.zig>.\n\n\n\n### Introducing file descriptors {#sec-file-descriptor}\n\nA \"file descriptor\" object is a core component behind every IO operation that is made in any operating system (OS).\nSuch object is an identifier for a particular input/output (IO) resource from your OS [@wiki_file_descriptor].\nIt describes and identifies this particular resource. An IO resource might be:\n\n- an existing file in your filesystem.\n- an existing network socket.\n- other types of stream channels.\n- a pipeline (or just \"pipe\") in your terminal[^pipes].\n\n[^pipes]: A pipeline is a mechanism for inter-process communication, or, inter-process IO. You could also interpret a pipeline as a \"set of processes that are chained together, through the standard input/output devices of the system\". At Linux for example, a pipeline is created inside a terminal, by connecting two or more terminal commands with the \"pipe\" character (`|`).\n\nFrom the bullet points listed above, we know that although the term \"file\" is present,\na \"file descriptor\" might describe something more than just a file.\nThis concept of a \"file descriptor\" comes from the Portable Operating System Interface (POSIX) API,\nwhich is a set of standards that guide how operating systems across the world should be implemented,\nto maintain compatibility between them.\n\nA file descriptor not only identifies the input/output resource that you are using to receive or send some data,\nbut it also describes where this resource is, and also, which IO mode this resource is currently using.\nFor example, this IO resource might be using only the \"read\" IO mode, which means that this resource\nis open to \"read operations\", while \"write operations\" are not authorized.\nThese IO modes are essentially the modes that you provide to the argument `mode`\nfrom the `fopen()` C function, and also, from the `open()` Python built-in function.\n\nIn C, a \"file descriptor\" is a `FILE` pointer, but, in Zig, a file descriptor is a `File` object.\nThis data type (`File`) is described in the `std.fs` module of the Zig Standard Library.\nWe normally don't create a `File` object directly in our Zig code. Instead, we normally get such object as result when we\nopen an IO resource. In other words, we normally ask our OS to open a particular IO resource for us,\nand, if the OS do open successfully this IO resource, the OS normally handles back to us\na file descriptor to this particular IO resource.\n\nSo you usually get a `File` object by using functions and methods from the Zig Standard Library\nthat asks the OS to open some IO resource, like the `openFile()` method that opens a file in the\nfilesystem. The `net.Stream` object that we have created in @sec-create-socket is also a type of\nfile descriptor object.\n\n\n### The *standard output*\n\nYou already saw across this book, how can we access and use specifically the `stdout` in Zig\nto send some output to the user.\nFor that, we use the `getStdOut()` function from the `std.io` module. This function returns\na file descriptor that describes the `stdout` channel of your current OS. Through this file\ndescriptor object, we can read from or write stuff to the `stdout` of our program.\n\nAlthough we can read stuff recorded into the `stdout` channel, we normally only\nwrite to (or \"print\") stuff into this channel. The reason is very similar to what we discussed at\n@sec-read-http-message, when we were discussing what \"reading from\" versus \"writing to\" the connection\nobject from our small HTTP Server project would mean.\n\nWhen we write stuff into a channel, we are essentially sending data to the other end of this channel.\nIn contrast, when we read stuff from this channel, we are essentially reading the data that was sent\nthrough this channel. Since the `stdout` is a channel to send output to the user, the key verb here\nis **send**. We want to send something to someone, and, as consequence, we want to **write** something\ninto some channel.\n\nThat is why, when we use `getStdOut()`, most of the times, we also use the `writer()` method from the `stdout` file descriptor,\nto get access to a writer object that we can use to write stuff into this `stdout` channel.\nMore specifically, this `writer()` method returns a `GenericWriter` object. One of the\nmain methods of this `GenericWriter` object is the `print()` method that we have used\nbefore to write (or \"print\") a formatted string into the `stdout` channel.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    try stdout.writeAll(\n        \"This message was written into stdout.\\n\"\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nThis message was written into stdout.\n```\n\n\n:::\n:::\n\n\n\n\n\n\nThis `GenericWriter` object is like any other generic writer object that you would normally get from a file descriptor object.\nSo, the same methods from a generic writer object that you would use while writing files to the filesystem for example, you could also\nuse them here, from the file descriptor object of `stdout`, and vice-versa.\n\n\n### The *standard input*\n\nYou can access the *standard input* (i.e., `stdin`) in Zig by using the `getStdIn()` function from the `std.io` module.\nLike its brother (`getStdOut()`), this function also returns a file descriptor object that describes the `stdin` channel\nof your OS.\n\nBecause we want to receive some input from the user, the key verb here becomes **receive**, and, as consequence,\nwe usually want to **read** data from the `stdin` channel, instead of writing data into it. So, we normally use\nthe `reader()` method of the file descriptor object returned by `getStdIn()`, to get access to a `GenericReader`\nobject that we can use to read data from `stdin`.\n\nIn the example below, we are creating a small buffer capable of holding 20 characters. Then, we try to read\nthe data from the `stdin` with the `readUntilDelimiterOrEof()` method, and save this data into the `buffer` object.\nAlso notice that we are reading the data from the `stdin` until we hit a new line character (`'\\n'`).\n\nIf you execute this program, you will notice that it stops the execution, ands start to wait indefinitely\nfor some input from the user. In other words, you need to type your name into the terminal, and then, you press Enter to\nsend your name to `stdin`. After you send your name to `stdin`, the program reads this input, and continues with the execution,\nby printing the given name to `stdout`. In the example below, I typed my name (Pedro) into the terminal, and then, pressed Enter.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst stdin = std.io.getStdIn().reader();\npub fn main() !void {\n    try stdout.writeAll(\"Type your name\\n\");\n    var buffer: [20]u8 = undefined;\n    @memset(buffer[0..], 0);\n    _ = try stdin.readUntilDelimiterOrEof(buffer[0..], '\\n');\n    try stdout.print(\"Your name is: {s}\\n\", .{buffer});\n}\n```\n:::\n\n\n\n\n```\nType your name\nYour name is: Pedro\n\n```\n\n\n### The *standard error*\n\nThe *standard error* (a.k.a. the `stderr`) works exactly the same as `stdout` and `stdin`.\nYou just call the `getStdErr()` function from the `std.io` module, and you get the file descriptor to `stderr`.\nIdeally, you should write only error or warning messages to `stderr`, because this is\nthe purpose of this channel.\n\n\n\n\n\n## Buffered IO\n\nAs we described in @sec-io-basics, input/output (IO) operations are made directly by the operating system.\nIt's the OS that manages the IO resource that you want to use for your IO operations.\nThe consequence of this fact is that IO operations are heavily based on system calls (i.e., calling the operating system directly).\n\nJust to be clear, there is nothing particularly wrong with system calls. We use them all the time on\nany serious codebase written in any low-level programming language. However, system calls are\nalways orders of magnitude slower than many different types of operations.\n\nSo is perfectly fine to use a system call once in a while. But when these system calls are used often,\nyou can clearly notice most of the time the loss of performance in your application. So, the good rule of thumb\nis to use a system call only when it's needed, and also, only in infrequent situations, to reduce\nthe number of system calls performed to a minimum.\n\n\n### Understanding how buffered IO works\n\nBuffered IO is a strategy to achieve better performance. It's used to reduce the number of system calls made by IO operations, and, as\nconsequence, achieve a much higher performance. In @fig-unbuffered-io and @fig-buffered-io you can find two different diagrams\nwhich presents the difference between read operations performed in an unbuffered IO environment versus a buffered IO environment.\n\nTo give a better context to these diagrams, let's suppose that we have a text file that contains the famous Lorem ipsum text[^lorem]\nin our filesystem. Let's also suppose that these diagrams in @fig-unbuffered-io and @fig-buffered-io\nare showing the read operations that we are performing to read the Lorem ipsum text from this text file.\nThe first thing you will notice when looking at these diagrams, is that in an unbuffered environment\nthe read operations leads to many system calls.\nMore precisely, in the diagram exposed in @fig-unbuffered-io we get one system call per each byte that we read from the text file.\nOn the other hand, in @fig-buffered-io we have only one system call at the very beginning.\n\nWhen we use a buffered IO system, at the first read operation we perform, instead of sending one single byte directly\nto our program, the OS first sends a chunk of bytes from the file to a buffer object (i.e., an array).\nThis chunk of bytes are cached/stored inside this buffer object.\n\nTherefore, from now on, for every new read operation that you perform, instead of making a new system call to ask\nfor the next byte in the file to the OS, this read operation is redirected to the buffer object, that have\nthis next byte already cached and ready to go.\n\n\n[^lorem]: <https://www.lipsum.com/>.\n\n\n![Unbuffered IO](./../Figures/unbuffered-io.png){#fig-unbuffered-io width=60%}\n\n![Buffered IO](./../Figures/buffered-io.png){#fig-buffered-io}\n\n\n\nThis is the basic logic behind buffered IO systems. The size of the buffer object depends on multiple factors. But it's usually\nequal to the size of a full page of memory (4096 bytes). If we follow this logic, then, the OS reads the first 4096 bytes\nof the file and caches it into the buffer object. As long as your program does not consume all of these 4096 bytes from the buffer,\nyou will not create new system calls.\n\nHowever, as soon as you consume all of these 4096 bytes from the buffer, it means that there is no bytes left in the buffer.\nIn this situation, a new system call is made to ask the OS to send the next 4096 bytes in the file, and once again,\nthese bytes are cached into the buffer object, and the cycle starts once again.\n\n\n### Buffered IO across different languages\n\nIO operations made through a `FILE` pointer in C are buffered\nby default, so, at least in C, you don't need to worry about this subject. But in contrast, IO operations in both Rust and Zig are not\nbuffered depending on which functions from the standard libraries that you are using.\n\nFor example, in Rust, buffered IO is implemented through the `BufReader` and `BufWriter` structs, while in Zig, it's implemented\nthrough the `BufferedReader` and `BufferedWriter` structs.\nSo any IO operation that you perform through the `GenericWriter` and `GenericReader` objects\nthat I presented in @sec-writer-reader are not buffered, which means that these objects\nmight create a lot of system calls depending on the situation.\n\n\n### Using buffered IO in Zig\n\nUsing buffered IO in Zig is actually very easy. All you have to do is to just\ngive the `GenericWriter` object to the `bufferedWriter()` function, or, to give the `GenericReader`\nobject to the `bufferedReader()` function. These functions come from the `std.io` module,\nand they will construct the `BufferedWriter` or `BufferedReader` object for you.\n\nAfter you create this new `BufferedWriter` or `BufferedReader` object, you can call the `writer()`\nor `reader()` method of this new object, to get access to a new (and buffered) generic reader or\ngeneric writer.\n\nLet's describe the process once again. Every time that you have a file descriptor object, you first get the generic writer or generic reader\nobject from it, by calling the `writer()` or `reader()` methods of this file descriptor object.\nThen, you provide this generic writer or generic reader to the `bufferedWriter()` or `bufferedReader()`\nfunction, which creates a new `BufferedWriter` or `BufferedReader` object. Then, you call\nthe `writer()` or `reader()` methods of this buffered writer or buffered reader object,\nwhich gives you access to a generic writer or a generic reader object that is buffered.\n\nTake this program as an example. This program is demonstrating the process exposed in @fig-buffered-io.\nWe are simply opening a text file that contains the Lorem ipsum text, and then, we create a buffered IO reader object\nat `bufreader`, and we use this `bufreader` object to read the contents of this file into a buffer object, then,\nwe end the program by printing this buffer to `stdout`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar file = try std.fs.cwd().openFile(\n    \"ZigExamples/file-io/lorem.txt\", .{}\n);\ndefer file.close();\nvar buffered = std.io.bufferedReader(file.reader());\nvar bufreader = buffered.reader();\n\nvar buffer: [1000]u8 = undefined;\n@memset(buffer[0..], 0);\n\n_ = try bufreader.readUntilDelimiterOrEof(\n    buffer[0..], '\\n'\n);\ntry stdout.print(\"{s}\\n\", .{buffer});\n```\n:::\n\n\n\n\n```\nLorem ipsum dolor sit amet, consectetur\nadipiscing elit. Sed tincidunt erat sed nulla ornare, nec\naliquet ex laoreet. Ut nec rhoncus nunc. Integer magna metus,\nultrices eleifend porttitor ut, finibus ut tortor. Maecenas\nsapien justo, finibus tincidunt dictum ac, semper et lectus.\nVivamus molestie egestas orci ac viverra. Pellentesque nec\narcu facilisis, euismod eros eu, sodales nisl. Ut egestas\nsagittis arcu, in accumsan sapien rhoncus sit amet. Aenean\nneque lectus, imperdiet ac lobortis a, ullamcorper sed massa.\nNullam porttitor porttitor erat nec dapibus. Ut vel dui nec\nnulla vulputate molestie eget non nunc. Ut commodo luctus ipsum,\nin finibus libero feugiat eget. Etiam vel ante at urna tincidunt\nposuere sit amet ut felis. Maecenas finibus suscipit tristique.\nDonec viverra non sapien id suscipit.\n```\n\nDespite being a buffered IO reader, this `bufreader` object is similar to any other `GenericReader` object,\nand have the exact same methods. So, although these two types of objects perform very different IO operations,\nthey have the same interface, so you, the programmer, can interchangeably use them\nwithout the need to change anything in your source code.\nSo a buffered IO reader or a buffered IO writer objects have the same methods than its generic and unbuffered brothers,\ni.e., the generic reader and generic writer objects that I presented in @sec-writer-reader.\n\n::: {.callout-tip}\nIn general, you should always use a buffered IO reader or a buffered IO writer object to perform\nIO operations in Zig. Because they deliver better performance to your IO operations.\n:::\n\n\n## Filesystem basics\n\nNow that we have discussed the basics around Input/Output operations in Zig, we need to\ntalk about the basics around filesystems, which is another core part of any operating system.\nAlso, filesystems are related to input/output, because the files that we store and create in our\ncomputer are considered an IO resource, as we described in @sec-file-descriptor.\n\n\n### The concept of current working directory (CWD)\n\nThe working directory is the folder on your computer where you are currently rooted at.\nIn other words, it's the folder that your program is currently looking at.\nTherefore, whenever you are executing a program, this program is always working with\na specific folder on your computer. It's always in this folder that the program will initially\nlook for the files you require, and it's also in this folder that the program\nwill initially save all the files you ask it to save.\n\nThe working directory is determined by the folder from which you invoke your program\nin the terminal. In other words, if you are in the terminal of your OS, and you\nexecute a binary file (i.e., a program) from this terminal, the folder to which your terminal\nis pointing at is the current working directory of your program that is being executed.\n\nIn @fig-cwd we have an example of me executing a program from the terminal. We are executing\nthe program outputted by the `zig` compiler by compiling the Zig module named `hello.zig`.\nThe CWD in this case is the `zig-book` folder. In other words, while the `hello.zig` program\nis executing, it will be looking at the `zig-book` folder, and any file operation that we perform\ninside this program, will be using this `zig-book` folder as the \"starting point\", or, as the \"central focus\".\n\n![Executing a program from the terminal](./../Figures/cwd.png){#fig-cwd}\n\nJust because we are rooted inside a particular folder (in the case of @fig-cwd, the `zig-book` folder) of our computer,\nit doesn't mean that we cannot access or write resources in other locations of our computer.\nThe current working directory (CWD) mechanism just defines where your program will look first\nfor the files you ask for. This does not prevent you from accessing files that are located\nelsewhere on your computer. However, to access any file that is in a folder other than your\ncurrent working directory, you must provide a path to that file or folder.\n\n\n### The concept of paths\n\nA path is essentially a location. It points to a location in your filesystem. We use\npaths to describe the location of files and folders in our computer.\nOne important aspect about paths is that they are always written inside strings,\ni.e., they are always provided as text values.\n\nThere are two types of paths that you can provide to any program in any OS: a relative path, or an absolute path.\nAbsolute paths are paths that start at the root of your filesystem, and go all the way to the file name or the specific folder\nthat you are referring to. This type of path is called absolute, because it points to an unique and absolute location on your computer.\nThat is, there is no other existing location on your computer that corresponds to this path. It's an unique identifier.\n\nIn Windows, an absolute path is a path that starts with a hard disk identifier (e.g. `C:/Users/pedro`).\nOn the other hand, absolute paths in Linux and macOS, are paths that start with a forward slash character (e.g. `/usr/local/bin`).\nNotice that a path is composed by \"segments\". Each segment is connected to each other by a slash character (`\\` or `/`).\nOn Windows, the backward slash (`\\`) is normally used to connect the path segments. While on Linux and macOS, the forward\nslash (`/`) is the character used to connect path segments.\n\nA relative path is a path that start at the CWD. In other words, a relative path is\n\"relative to the CWD\". The path used to access the `hello.zig` file in @fig-cwd is an example of a relative path. This path\nis reproduced below. This path begins at the CWD, which in the context of @fig-cwd, is the `zig-book` folder,\nthen, it goes to the `ZigExamples` folder, then, into `zig-basics`, then, to the `hello.zig` file.\n\n```\nZigExamples/zig-basics/hello_world.zig\n```\n\n\n### Path wildcards\n\nWhen providing paths, especially relative paths, you have the option of using a *wildcard*.\nThere are two commonly used *wildcards* in paths, which are \"one period\" (.) and \"two periods\" (..).\nIn other words, these two specific characters have special meanings when used in paths,\nand can be used on any operating system (Mac, Windows, Linux, etc.). That is, they\nare \"cross platform\".\n\nThe \"one period\" represents an alias for the current directory.\nThis means that the relative paths `\"./Course/Data/covid.csv\"` and `\"Course/Data/covid.csv\"` are equivalent.\nOn the other hand, the \"two periods\" refers to the previous directory.\nFor example, the path `\"Course/..\"` is equivalent to the path `\".\"`, that is, the current working directory.\n\nTherefore, the path `\"Course/..\"` refers to the folder before the `Course` folder.\nAs another example, the path `\"src/writexml/../xml.cpp\"` refers to the file `xml.cpp`\nthat is inside the folder before the `writexml` folder, which in this example is the `src` folder.\nTherefore, this path is equivalent to `\"src/xml.cpp\"`.\n\n\n\n\n## The CWD handler\n\nIn Zig, filesystem operations are usually made through a directory handler object.\nA directory handler in Zig is an object of type `Dir`, which is an object that describes\na particular folder in the filesystem of our computer.\nYou normally create a `Dir` object, by calling the `std.fs.cwd()` function.\nThis function returns a `Dir` object that points to (or, that describes) the\ncurrent working directory (CWD).\n\nThrough this `Dir` object, you can create new files, or modify, or read existing ones that are\ninside your CWD. In other words, a `Dir` object is the main entrypoint in Zig to perform\nmultiple types of filesystem operations.\nIn the example below, we are creating this `Dir` object, and storing it\ninside the `cwd` object. Although we are not using this object at this code example,\nwe are going to use it a lot over the next examples.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\n_ = cwd;\n```\n:::\n\n\n\n\n\n\n\n\n\n\n\n## File operations\n\n### Creating files {#sec-creating-files}\n\nWe create new files by using the `createFile()` method from the `Dir` object.\nJust provide the name of the file that you want to create, and this function will\ndo the necessary steps to create such file. You can also provide a relative path to this function,\nand it will create the file by following this path, which is relative to the CWD.\n\nThis function might return an error, so, you should use `try`, `catch`, or any of the other methods presented\nin @sec-error-handling to handle the possible error. But if everything goes well,\nthis `createFile()` method returns a file descriptor object (i.e., a `File` object) as result,\nthrough which you can add content to the file with the IO operations that I presented before.\n\nTake this code example below. In this example, we are creating a new text file\nnamed `foo.txt`. If the function `createFile()` succeeds, the object named `file` will contain a file descriptor\nobject, which we can use to write (or add) new content to the file, like we do in this example, by using\na buffered writer object to write a new line of text to the file.\n\nNow, a quick note, when we create a file descriptor object in C, by using a C function like `fopen()`, we must always close the file\nat the end of our program, or, as soon as we complete all operations that we wanted to perform\non the file. In Zig, this is no different. So everytime we create a new file, this file remains\n\"open\", waiting for some operation to be performed. As soon as we are done with it, we always have\nto close this file, to free the resources associated with it.\nIn Zig, we do this by calling the method `close()` from the file descriptor object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.createFile(\"foo.txt\", .{});\n// Don't forget to close the file at the end.\ndefer file.close();\n// Do things with the file ...\nvar fw = file.writer();\n_ = try fw.writeAll(\n    \"Writing this line to the file\\n\"\n);\n```\n:::\n\n\n\n\n\nSo, in this example we not only have created a file into the filesystem,\nbut we also wrote some data into this file, using the file descriptor object\nreturned by `createFile()`. If the file that you are trying to create\nalready exists in your filesystem, this `createFile()` call will\noverwrite the contents of the file, or, in other words, it will\nin erase all the contents of the existing file.\n\nIf you don't want this to happen, meaning, that you don't want to overwrite\nthe contents of the existing file, but you want to write data to this file anyway\n(i.e., you want to append data to the file), you should use the `openFile()`\nmethod from the `Dir` object.\n\nAnother important aspect about `createFile()` is that this method creates a file\nthat is not open to read operations by default. It means that you cannot read this file.\nYou are not allowed to.\nSo for example, you might want to write some stuff into this file at the beginning of the execution\nof your program. Then, at a future point in your program you might need to read what you\nwrote in this file. If you try to read data from this file, you will likely\nget a `NotOpenForReading` error as result.\n\n\nBut how can you overcome this barrier? How can you create a file that is open\nto read operations? All you have to do, is to set the `read` flag to true\nin the second argument of `createFile()`. When you set this flag to true,\nthen the file gets create with \"read permissions\", and, as consequence,\na program like this one below becomes valid:\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.createFile(\n    \"foo.txt\",\n    .{ .read = true }\n);\ndefer file.close();\n\nvar fw = file.writer();\n_ = try fw.writeAll(\"We are going to read this line\\n\");\n\nvar buffer: [300]u8 = undefined;\n@memset(buffer[0..], 0);\ntry file.seekTo(0);\nvar fr = file.reader();\n_ = try fr.readAll(buffer[0..]);\ntry stdout.print(\"{s}\\n\", .{buffer});\n```\n:::\n\n\n\n\n\n```\nWe are going to read this line\n```\n\n\nIf you are not familiar with position indicators, you might not recognize the method\n`seekTo()`. If that is your case, do not worry,\nwe are going to talk more about this method in @sec-indicators. But essentially\nthis method is moving the position indicator back to the beginning of the file,\nso that we can read the contents of the file from the beginning.\n\n\n### Opening files and appending data to it\n\nOpening files is easy. Just use the `openFile()` method instead of `createFile()`.\nIn the first argument of `openFile()` you provide the path to the file that\nyou want to open. Then, on the second argument you provide the flags (or, the options)\nthat dictates how the file is opened.\n\nYou can see the full list of options for `openFile()` by visiting the documentation for\n[`OpenFlags`](https://ziglang.org/documentation/master/std/#std.fs.File.OpenFlags)[^oflags].\nBut the main flag that you will most certainly use is the `mode` flag.\nThis flag specifies the IO mode that the file will be using when it gets opened.\nThere are three IO modes, or, three values that you can provide to this flag, which are:\n\n- `read_only`, allows only read operations on the file. All write operations are blocked.\n- `write_only`, allows only write operations on the file. All read operations are blocked.\n- `read_write`, allows both write and read operations on the file.\n\n[^oflags]: <https://ziglang.org/documentation/master/std/#std.fs.File.OpenFlags>\n\nThese modes are similar to the modes that you provide to the `mode` argument of the\n`open()` Python built-in function[^py-open], or, the `mode` argument of the\n`fopen()` C function[^c-open].\nIn the code example below, we are opening the `foo.txt` text file with a `write_only` mode,\nand appending a new line of text to the end of the file. We use `seekFromEnd()` this time\nto guarantee that we are going to append the text to the end of the file. Once again, methods\nsuch as `seekFromEnd()` are described in more depth in @sec-indicators.\n\n[^py-open]: <https://docs.python.org/3/tutorial/inputoutput.html#reading-and-writing-files>\n[^c-open]: <https://www.tutorialspoint.com/c_standard_library/c_function_fopen.htm>\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.openFile(\n    \"foo.txt\", .{ .mode = .write_only }\n);\ndefer file.close();\ntry file.seekFromEnd(0);\nvar fw = file.writer();\n_ = try fw.writeAll(\"Some random text to write\\n\");\n```\n:::\n\n\n\n\n\n### Deleting files\n\nSometimes, we just need to delete/remove the files that we have.\nTo do that, we use the `deleteFile()` method. You just provide the path of the\nfile that you want to delete, and this method will try to delete the file located\nat this path.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.deleteFile(\"foo.txt\");\n```\n:::\n\n\n\n\n### Copying files\n\nTo copy existing files, we use the `copyFile()` method. The first argument in this method\nis the path to the file that you want to copy. The second argument is a `Dir` object, i.e., a directory handler,\nmore specifically, a `Dir` object that points to the folder in your computer where you want to\ncopy the file to. The third argument is the new path of the file, or, in other words, the new location\nof the file. The fourth argument is the options (or flags) to be used in the copy operation.\n\nThe `Dir` object that you provide as input to this method will be used to copy the file to\nthe new location. You may create this `Dir` object before calling the `copyFile()` method.\nMaybe you are planning to copy the file to a completely different location in your computer,\nso it might be worth to create a directory handler to that location. But if you are copying the\nfile to a subfolder of your CWD, then, you can just simply pass the CWD handler to this argument.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.copyFile(\n    \"foo.txt\",\n    cwd,\n    \"ZigExamples/file-io/foo.txt\",\n    .{}\n);\n```\n:::\n\n\n\n\n\n### Read the docs!\n\nThere are some other useful methods for file operations available at `Dir` objects,\nsuch as the `writeFile()` method, but I recommend you to read the docs for the\n[`Dir` type](https://ziglang.org/documentation/master/std/#std.fs.Dir)[^zig-dir]\nto explore the other available methods, since I already talked too much about them.\n\n\n[^zig-dir]: <https://ziglang.org/documentation/master/std/#std.fs.Dir>\n\n\n\n\n## Position indicators {#sec-indicators}\n\nA position indicator is like a type of cursor, or, an index. This \"index\" identifies the current\nlocation in the file (or, in the data stream) that the file descriptor object that you have\nis currently looking at.\nWhen you create a file descriptor, the position indicator starts at the beginning of the file,\nor, at the beginning of the stream. When you read from or write into the file (or socket, or data stream, etc.)\ndescribed by this file descriptor object, you end up moving the position indicator.\n\nIn other words, any IO operation have a common side effect, which is to move the position indicator.\nFor example, suppose that we have a file of 300 bytes total in size. If you\nread 100 bytes from the file, then, the position indicator moves 100 bytes forward. If you try\nto write 50 bytes into this same file, these 50 bytes will be written from the current\nposition indicated by the position indicator. Since the indicator is at a 100 bytes forward from\nthe beginning of the file, these 50 bytes would be written in the middle of the file.\n\nThis is why we have used the `seekTo()` method at the last code example presented in @sec-creating-files.\nWe have used this method to move the position indicator back to the beginning of the file, which\nwould make sure that we would write the text that we wanted to write from the beginning of the file,\ninstead of writing it from the middle of the file. Because before the write operation, we had\nperformed a read operation, which means that the position indicator was moved in this read operation.\n\nThe position indicators of a file descriptor object can be changed (or altered) by using the\n\"seek\" methods from this file descriptor, which are: `seekTo()`, `seekFromEnd()` and `seekBy()`.\nThese methods have the same effect, or, the same responsibility that the\n[`fseek()`](https://en.cppreference.com/w/c/io/fseek)[^c-fseek] C function.\n\n[^c-fseek]: <https://en.cppreference.com/w/c/io/fseek>\n\n\nConsidering that `offset` refers to the index that you provide as input to these \"seek\" methods,\nthe bullet points below summarises what is the effect of each of these methods.\nAs a quick note, in the case of `seekFromEnd()` and `seekBy()`, the `offset` provided can be either a\npositive or a negative index.\n\n- `seekTo()` will move the position indicator to the location that is `offset` bytes from the beginning of the file.\n- `seekFromEnd()` will move the position indicator to the location that is `offset` bytes from the end of the file.\n- `seekBy()` will move the position indicator to the location that is `offset` bytes from the current position in the file.\n\n\n\n\n\n\n\n## Directory operations\n\n### Iterating through the files in a directory\n\nOne of the most classic tasks related to filesystem is to be able\nto iterate through the existing files in a directory. To iterate over the\nfiles in a directory, we need to create an iterator object.\n\nYou can produce such iterator object by using either the `iterate()` or `walk()` methods\nof a `Dir` object. Both methods return an iterator object as output, which you can advance by using the\n`next()` method. The difference between these methods, is that `iterate()` returns a non-recursive iterator,\nwhile `walk()` does. It means that the iterator returned by `walk()` will not only iterate through\nthe files available in the current directory, but also, through the files from any subdirectory found\ninside the current directory.\n\nIn the example below, we are displaying the names of the files stored inside the\ndirectory `ZigExamples/file-io`. Notice that we had to open this directory through\nthe `openDir()` function. Also notice that we provided the flag `iterate` in the\nsecond argument of `openDir()`. This flag is important, because without this flag,\nwe would not be allowed to iterate through the files in this directory.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst dir = try cwd.openDir(\n    \"ZigExamples/file-io/\",\n    .{ .iterate = true }\n);\nvar it = dir.iterate();\nwhile (try it.next()) |entry| {\n    try stdout.print(\n        \"File name: {s}\\n\",\n        .{entry.name}\n    );\n}\n```\n:::\n\n\n\n\n```\nFile name: create_file_and_write_toit.zig\nFile name: create_file.zig\nFile name: lorem.txt\nFile name: iterate.zig\nFile name: delete_file.zig\nFile name: append_to_file.zig\nFile name: user_input.zig\nFile name: foo.txt\nFile name: create_file_and_read.zig\nFile name: buff_io.zig\nFile name: copy_file.zig\n```\n\n\n### Creating new directories\n\nThere are two methods that are important when it comes to\ncreating directories, which are `makeDir()` and `makePath()`.\nThe difference between these two methods is that `makeDir()` can\nonly create one single directory in the current directory in each call,\nwhile `makePath()` is capable of recursively create subdirectories in the same call.\n\n\nThis is why the name of this method is \"make path\". It will create as many\nsubdirectories as necessary to create the path that you provided as input.\nSo, if you provide the path `\"sub1/sub2/sub3\"` as input to this method,\nit will create three different subdirectories, `sub1`, `sub2` and `sub3`,\nwithin the same function call. In contrast, if you provided such path\nas input to `makeDir()`, you would likely get an error as result, since\nthis method can only create a single subdirectory.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.makeDir(\"src\");\ntry cwd.makePath(\"src/decoders/jpg/\");\n```\n:::\n\n\n\n\n### Deleting directories\n\nTo delete a directory, just provide the path to the directory that you want to delete\nas input to the `deleteDir()` method from a `Dir` object. In the example below,\nwe are deleting the `src` directory that we have just created in the previous example.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.deleteDir(\"src\");\n```\n:::\n\n\n\n\n\n## Conclusion\n\nIn this chapter, I have described how to perform in Zig the most common filesystem and IO operations.\nBut you might feel the lack of some other, less common, operation in this chapter, such as: how to rename files,\nor how to open a directory, or how to create symbolic links, or how to use `access()` to test if a particular\npath exists in your computer. But for all of these less common tasks, I recommend you to read\nthe documentation of the [`Dir` type](https://ziglang.org/documentation/master/std/#std.fs.Dir)[^zig-dir]\n, since you can find a good description of these cases there.\n",
-    "supporting": [
-      "12-file-op_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Filesystem and Input/Output (IO) {#sec-filesystem}\n\nIn this chapter we are going to discuss how to use the cross-platform structs and functions\nfrom the Zig Standard Library that can execute filesystem operations. Most of these functions and structs\ncomes from the `std.fs` module.\n\nWe are also going to talk about Input/Output (also known as IO) operations in Zig. Most of\nthese operations are made by using the structs and functions from `std.io` module, which defines\nfile descriptors for the *standard channels* of your system (`stdout` and `stdin`), and also,\nfunctions to create and use I/O streams.\n\n\n## Input/Output basics {#sec-io-basics}\n\nIf you have some experience in a high-level language, you have certainly used\nthese input and output functionalities before in this language. In other words, you certainly have\nbeen in a situation where you needed to sent some output to the user, or, to receive an input\nfrom the user.\n\nFor example, in Python we can receive some input from the user by using the `input()` built-in\nfunction. But we can also print (or \"show\") some output to the user by using the `print()`\nbuilt-in function. So yes, if you have programmed before in Python, you certainly have\nused these functions once before.\n\nBut do you know how these functions relate back to your operating system (OS)? How exactly\nthey are interacting with the resources of your OS to receive or sent some input/output.\nIn essence, these input/output functions from high-level languages are just abstractions\nover the *standard output* and *standard input* channels of your operating system.\n\nThis means that we receive an input, or send some output, through the operating system.\nIt's the OS that makes the bridge between the user and your program. Your program\ndoes not have a direct access to the user. It's the OS that intermediates every\nmessage exchanged between your program and the user.\n\nThe *standard output* and *standard input* channels of your OS are commonly known as the\n`stdout` and `stdin` channels of your OS, respectively. In some contexts, they are also\ncalled the *standard output device* and the *standard input device*. As the name suggests,\nthe *standard output* is the channel through which output flows, while the *standard input*\nis the channel in which input flows.\n\nFurthermore, OS's also normally create a dedicated channel for exchanging error messages, which is known as the\n*standard error* channel, or, the `stderr` channel. This is the channel to which error and warning messages\nare usually sent to. These are the messages that are normally displayed in red-like or orange-like colors\ninto your terminal.\n\nNormally, every OS (e.g. Windows, macOS, Linux, etc.) creates a dedicated and separate set of\n*standard output*, *standard error* and *standard input* channels for every single program (or process) that runs in your computer.\nThis means that every program you write have a dedicated `stdin`, `stderr` and `stdout` that are separate\nfrom the `stdin`, `stderr` and `stdout` of other programs and processes that are currently running.\n\nThis is a behaviour from your OS. This does not come from the programming language that you are using.\nBecause as I sad earlier, input and output in programming languages, especially\nin high-level ones, are just a simple abstraction over the `stdin`, `stderr` and `stdout` from your current OS.\nThat is, your OS is the intermediary between every input/output operation made in your program,\nregardless of the programming language that you are using.\n\n\n### The writer and reader pattern {#sec-writer-reader}\n\nIn Zig, there is a pattern around input/output (IO). I (the author of this book) don't know if there\nis an official name for this pattern. But here, in this book, I will call it the \"writer and reader pattern\".\nIn essence, every IO operation in Zig is made through either a `GenericReader` or a `GenericWriter` object[^gen-zig].\n\nThese two data types come from the `std.io` module of the Zig Standard Library. As their names suggests, a\n`GenericReader` is an object that offers tools to read data from \"something\" (or \"somewhere\"), while a `GenericWriter`\noffers tools to write data into this \"something\". This \"something\" might be different things: like a\nfile that exists in your filesystem; or, it might be a network socket in your system[^sock]; or,\na continuous stream of data, like a standard input device from your system, that might be constantly\nreceiving new data from users, or, as another example, a live chat in a game that is constantly\nreceiving and displaying new messages from the players of the game.\n\n[^gen-zig]: Previously, these objects were known as the `Reader` and `Writer` objects.\n[^sock]: The socket objects that we have created in @sec-create-socket, are examples of network sockets.\n\nSo, if you want to **read** data from something, or somewhere, it means that you need to use a `GenericReader` object.\nBut if you need instead, to **write** data into this \"something\", then, you need to use a `GenericWriter` object instead.\nBoth of these objects are normally created from a file descriptor object. More specifically, through the `writer()` and `reader()`\nmethods of this file descriptor object. If you are not familiar with this type of object, go to the next section.\n\nEvery `GenericWriter` object have methods like `print()`, which allows you to write/send a formatted string\n(i.e., this formatted string is like a `f` string in Python, or, similar to the `printf()` C function)\ninto the \"something\" (file, socket, stream, etc.) that you are using. It also have a `writeAll()` method, which allows you to\nwrite a string, or, an array of bytes into the \"something\".\n\nLikewise, every `GenericReader` object have methods like `readAll()`, which allows you to read the\ndata from the \"something\" (file, socket, stream, etc.) until it fills a particular array (i.e., a \"buffer\") object.\nIn other words, if you provide an array object of 300 `u8` values to `readAll()`, then, this method attempts to read 300 bytes\nof data from the \"something\", and it stores them into the array object that you have provided.\n\nWe also have other methods, like the `readAtLeast()` method, which allows you to specify how\nmany bytes exactly you want to read from the \"something\". In more details, if you give the\nnumber $n$ as input to this method, then, it will attempt to read at least $n$ bytes of data\nfrom the \"something\". The \"something\" might have less than $n$ bytes of data available for you\nto read, so, it's not guaranteed that you will get precisely $n$ bytes as result.\n\nAnother useful method is `readUntilDelimiterOrEof()`. In this method, you specify a \"delimiter character\".\nThe idea is that this function will attempt to read as many bytes of data as possible from the \"something\",\nuntil it encounters the end of the stream, or, it encounters the \"delimiter character\" that you have specified.\n\nIf you don't know exactly how many bytes will come from the \"something\", you may find the `readAllAlloc()` method\nuseful. In essence, you provide an allocator object to this method, so that it can allocate more space if needed.\nAs consequence, this method will try to read all bytes of the \"something\", and, if it runs out of space at some point\nduring the \"reading process\", it uses the allocator object to allocate more space to continue reading the bytes.\nAs result, this method returns a slice to the array object containing all the bytes read.\n\nThis is just a quick description of the methods present in these types of objects. But I recommend you\nto read the official docs, both for\n[`GenericWriter`](https://ziglang.org/documentation/master/std/#std.io.GenericWriter)[^gen-write] and\n[`GenericReader`](https://ziglang.org/documentation/master/std/#std.io.GenericReader)[^gen-read].\nI also think it's a good idea to read the source code of the modules in the Zig Standard Library\nthat defines the methods present in these objects, which are the\n[`Reader.zig`](https://github.com/ziglang/zig/blob/master/lib/std/io/Reader.zig)[^mod-read]\nand [`Writer.zig`]()[^mod-write].\n\n[^gen-read]: <https://ziglang.org/documentation/master/std/#std.io.GenericReader>.\n[^gen-write]: <https://ziglang.org/documentation/master/std/#std.io.GenericWriter>.\n[^mod-read]: <https://github.com/ziglang/zig/blob/master/lib/std/io/Reader.zig>.\n[^mod-write]: <https://github.com/ziglang/zig/blob/master/lib/std/io/Writer.zig>.\n\n\n\n### Introducing file descriptors {#sec-file-descriptor}\n\nA \"file descriptor\" object is a core component behind every IO operation that is made in any operating system (OS).\nSuch object is an identifier for a particular input/output (IO) resource from your OS [@wiki_file_descriptor].\nIt describes and identifies this particular resource. An IO resource might be:\n\n- an existing file in your filesystem.\n- an existing network socket.\n- other types of stream channels.\n- a pipeline (or just \"pipe\") in your terminal[^pipes].\n\n[^pipes]: A pipeline is a mechanism for inter-process communication, or, inter-process IO. You could also interpret a pipeline as a \"set of processes that are chained together, through the standard input/output devices of the system\". At Linux for example, a pipeline is created inside a terminal, by connecting two or more terminal commands with the \"pipe\" character (`|`).\n\nFrom the bullet points listed above, we know that although the term \"file\" is present,\na \"file descriptor\" might describe something more than just a file.\nThis concept of a \"file descriptor\" comes from the Portable Operating System Interface (POSIX) API,\nwhich is a set of standards that guide how operating systems across the world should be implemented,\nto maintain compatibility between them.\n\nA file descriptor not only identifies the input/output resource that you are using to receive or send some data,\nbut it also describes where this resource is, and also, which IO mode this resource is currently using.\nFor example, this IO resource might be using only the \"read\" IO mode, which means that this resource\nis open to \"read operations\", while \"write operations\" are not authorized.\nThese IO modes are essentially the modes that you provide to the argument `mode`\nfrom the `fopen()` C function, and also, from the `open()` Python built-in function.\n\nIn C, a \"file descriptor\" is a `FILE` pointer, but, in Zig, a file descriptor is a `File` object.\nThis data type (`File`) is described in the `std.fs` module of the Zig Standard Library.\nWe normally don't create a `File` object directly in our Zig code. Instead, we normally get such object as result when we\nopen an IO resource. In other words, we normally ask our OS to open a particular IO resource for us,\nand, if the OS do open successfully this IO resource, the OS normally handles back to us\na file descriptor to this particular IO resource.\n\nSo you usually get a `File` object by using functions and methods from the Zig Standard Library\nthat asks the OS to open some IO resource, like the `openFile()` method that opens a file in the\nfilesystem. The `net.Stream` object that we have created in @sec-create-socket is also a type of\nfile descriptor object.\n\n\n### The *standard output*\n\nYou already saw across this book, how can we access and use specifically the `stdout` in Zig\nto send some output to the user.\nFor that, we use the `getStdOut()` function from the `std.io` module. This function returns\na file descriptor that describes the `stdout` channel of your current OS. Through this file\ndescriptor object, we can read from or write stuff to the `stdout` of our program.\n\nAlthough we can read stuff recorded into the `stdout` channel, we normally only\nwrite to (or \"print\") stuff into this channel. The reason is very similar to what we discussed at\n@sec-read-http-message, when we were discussing what \"reading from\" versus \"writing to\" the connection\nobject from our small HTTP Server project would mean.\n\nWhen we write stuff into a channel, we are essentially sending data to the other end of this channel.\nIn contrast, when we read stuff from this channel, we are essentially reading the data that was sent\nthrough this channel. Since the `stdout` is a channel to send output to the user, the key verb here\nis **send**. We want to send something to someone, and, as consequence, we want to **write** something\ninto some channel.\n\nThat is why, when we use `getStdOut()`, most of the times, we also use the `writer()` method from the `stdout` file descriptor,\nto get access to a writer object that we can use to write stuff into this `stdout` channel.\nMore specifically, this `writer()` method returns a `GenericWriter` object. One of the\nmain methods of this `GenericWriter` object is the `print()` method that we have used\nbefore to write (or \"print\") a formatted string into the `stdout` channel.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    try stdout.writeAll(\n        \"This message was written into stdout.\\n\"\n    );\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nThis message was written into stdout.\n```\n\n\n:::\n:::\n\n\n\n\nThis `GenericWriter` object is like any other generic writer object that you would normally get from a file descriptor object.\nSo, the same methods from a generic writer object that you would use while writing files to the filesystem for example, you could also\nuse them here, from the file descriptor object of `stdout`, and vice-versa.\n\n\n### The *standard input*\n\nYou can access the *standard input* (i.e., `stdin`) in Zig by using the `getStdIn()` function from the `std.io` module.\nLike its brother (`getStdOut()`), this function also returns a file descriptor object that describes the `stdin` channel\nof your OS.\n\nBecause we want to receive some input from the user, the key verb here becomes **receive**, and, as consequence,\nwe usually want to **read** data from the `stdin` channel, instead of writing data into it. So, we normally use\nthe `reader()` method of the file descriptor object returned by `getStdIn()`, to get access to a `GenericReader`\nobject that we can use to read data from `stdin`.\n\nIn the example below, we are creating a small buffer capable of holding 20 characters. Then, we try to read\nthe data from the `stdin` with the `readUntilDelimiterOrEof()` method, and save this data into the `buffer` object.\nAlso notice that we are reading the data from the `stdin` until we hit a new line character (`'\\n'`).\n\nIf you execute this program, you will notice that it stops the execution, ands start to wait indefinitely\nfor some input from the user. In other words, you need to type your name into the terminal, and then, you press Enter to\nsend your name to `stdin`. After you send your name to `stdin`, the program reads this input, and continues with the execution,\nby printing the given name to `stdout`. In the example below, I typed my name (Pedro) into the terminal, and then, pressed Enter.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst stdin = std.io.getStdIn().reader();\npub fn main() !void {\n    try stdout.writeAll(\"Type your name\\n\");\n    var buffer: [20]u8 = undefined;\n    @memset(buffer[0..], 0);\n    _ = try stdin.readUntilDelimiterOrEof(buffer[0..], '\\n');\n    try stdout.print(\"Your name is: {s}\\n\", .{buffer});\n}\n```\n:::\n\n\n```\nType your name\nYour name is: Pedro\n\n```\n\n\n### The *standard error*\n\nThe *standard error* (a.k.a. the `stderr`) works exactly the same as `stdout` and `stdin`.\nYou just call the `getStdErr()` function from the `std.io` module, and you get the file descriptor to `stderr`.\nIdeally, you should write only error or warning messages to `stderr`, because this is\nthe purpose of this channel.\n\n\n\n\n\n## Buffered IO\n\nAs we described in @sec-io-basics, input/output (IO) operations are made directly by the operating system.\nIt's the OS that manages the IO resource that you want to use for your IO operations.\nThe consequence of this fact is that IO operations are heavily based on system calls (i.e., calling the operating system directly).\n\nJust to be clear, there is nothing particularly wrong with system calls. We use them all the time on\nany serious codebase written in any low-level programming language. However, system calls are\nalways orders of magnitude slower than many different types of operations.\n\nSo is perfectly fine to use a system call once in a while. But when these system calls are used often,\nyou can clearly notice most of the time the loss of performance in your application. So, the good rule of thumb\nis to use a system call only when it's needed, and also, only in infrequent situations, to reduce\nthe number of system calls performed to a minimum.\n\n\n### Understanding how buffered IO works\n\nBuffered IO is a strategy to achieve better performance. It's used to reduce the number of system calls made by IO operations, and, as\nconsequence, achieve a much higher performance. In @fig-unbuffered-io and @fig-buffered-io you can find two different diagrams\nwhich presents the difference between read operations performed in an unbuffered IO environment versus a buffered IO environment.\n\nTo give a better context to these diagrams, let's suppose that we have a text file that contains the famous Lorem ipsum text[^lorem]\nin our filesystem. Let's also suppose that these diagrams in @fig-unbuffered-io and @fig-buffered-io\nare showing the read operations that we are performing to read the Lorem ipsum text from this text file.\nThe first thing you will notice when looking at these diagrams, is that in an unbuffered environment\nthe read operations leads to many system calls.\nMore precisely, in the diagram exposed in @fig-unbuffered-io we get one system call per each byte that we read from the text file.\nOn the other hand, in @fig-buffered-io we have only one system call at the very beginning.\n\nWhen we use a buffered IO system, at the first read operation we perform, instead of sending one single byte directly\nto our program, the OS first sends a chunk of bytes from the file to a buffer object (i.e., an array).\nThis chunk of bytes are cached/stored inside this buffer object.\n\nTherefore, from now on, for every new read operation that you perform, instead of making a new system call to ask\nfor the next byte in the file to the OS, this read operation is redirected to the buffer object, that have\nthis next byte already cached and ready to go.\n\n\n[^lorem]: <https://www.lipsum.com/>.\n\n\n![Unbuffered IO](./../Figures/unbuffered-io.png){#fig-unbuffered-io width=60%}\n\n![Buffered IO](./../Figures/buffered-io.png){#fig-buffered-io}\n\n\n\nThis is the basic logic behind buffered IO systems. The size of the buffer object depends on multiple factors. But it's usually\nequal to the size of a full page of memory (4096 bytes). If we follow this logic, then, the OS reads the first 4096 bytes\nof the file and caches it into the buffer object. As long as your program does not consume all of these 4096 bytes from the buffer,\nyou will not create new system calls.\n\nHowever, as soon as you consume all of these 4096 bytes from the buffer, it means that there is no bytes left in the buffer.\nIn this situation, a new system call is made to ask the OS to send the next 4096 bytes in the file, and once again,\nthese bytes are cached into the buffer object, and the cycle starts once again.\n\n\n### Buffered IO across different languages\n\nIO operations made through a `FILE` pointer in C are buffered\nby default, so, at least in C, you don't need to worry about this subject. But in contrast, IO operations in both Rust and Zig are not\nbuffered depending on which functions from the standard libraries that you are using.\n\nFor example, in Rust, buffered IO is implemented through the `BufReader` and `BufWriter` structs, while in Zig, it's implemented\nthrough the `BufferedReader` and `BufferedWriter` structs.\nSo any IO operation that you perform through the `GenericWriter` and `GenericReader` objects\nthat I presented in @sec-writer-reader are not buffered, which means that these objects\nmight create a lot of system calls depending on the situation.\n\n\n### Using buffered IO in Zig\n\nUsing buffered IO in Zig is actually very easy. All you have to do is to just\ngive the `GenericWriter` object to the `bufferedWriter()` function, or, to give the `GenericReader`\nobject to the `bufferedReader()` function. These functions come from the `std.io` module,\nand they will construct the `BufferedWriter` or `BufferedReader` object for you.\n\nAfter you create this new `BufferedWriter` or `BufferedReader` object, you can call the `writer()`\nor `reader()` method of this new object, to get access to a new (and buffered) generic reader or\ngeneric writer.\n\nLet's describe the process once again. Every time that you have a file descriptor object, you first get the generic writer or generic reader\nobject from it, by calling the `writer()` or `reader()` methods of this file descriptor object.\nThen, you provide this generic writer or generic reader to the `bufferedWriter()` or `bufferedReader()`\nfunction, which creates a new `BufferedWriter` or `BufferedReader` object. Then, you call\nthe `writer()` or `reader()` methods of this buffered writer or buffered reader object,\nwhich gives you access to a generic writer or a generic reader object that is buffered.\n\nTake this program as an example. This program is demonstrating the process exposed in @fig-buffered-io.\nWe are simply opening a text file that contains the Lorem ipsum text, and then, we create a buffered IO reader object\nat `bufreader`, and we use this `bufreader` object to read the contents of this file into a buffer object, then,\nwe end the program by printing this buffer to `stdout`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar file = try std.fs.cwd().openFile(\n    \"ZigExamples/file-io/lorem.txt\", .{}\n);\ndefer file.close();\nvar buffered = std.io.bufferedReader(file.reader());\nvar bufreader = buffered.reader();\n\nvar buffer: [1000]u8 = undefined;\n@memset(buffer[0..], 0);\n\n_ = try bufreader.readUntilDelimiterOrEof(\n    buffer[0..], '\\n'\n);\ntry stdout.print(\"{s}\\n\", .{buffer});\n```\n:::\n\n\n```\nLorem ipsum dolor sit amet, consectetur\nadipiscing elit. Sed tincidunt erat sed nulla ornare, nec\naliquet ex laoreet. Ut nec rhoncus nunc. Integer magna metus,\nultrices eleifend porttitor ut, finibus ut tortor. Maecenas\nsapien justo, finibus tincidunt dictum ac, semper et lectus.\nVivamus molestie egestas orci ac viverra. Pellentesque nec\narcu facilisis, euismod eros eu, sodales nisl. Ut egestas\nsagittis arcu, in accumsan sapien rhoncus sit amet. Aenean\nneque lectus, imperdiet ac lobortis a, ullamcorper sed massa.\nNullam porttitor porttitor erat nec dapibus. Ut vel dui nec\nnulla vulputate molestie eget non nunc. Ut commodo luctus ipsum,\nin finibus libero feugiat eget. Etiam vel ante at urna tincidunt\nposuere sit amet ut felis. Maecenas finibus suscipit tristique.\nDonec viverra non sapien id suscipit.\n```\n\nDespite being a buffered IO reader, this `bufreader` object is similar to any other `GenericReader` object,\nand have the exact same methods. So, although these two types of objects perform very different IO operations,\nthey have the same interface, so you, the programmer, can interchangeably use them\nwithout the need to change anything in your source code.\nSo a buffered IO reader or a buffered IO writer objects have the same methods than its generic and unbuffered brothers,\ni.e., the generic reader and generic writer objects that I presented in @sec-writer-reader.\n\n::: {.callout-tip}\nIn general, you should always use a buffered IO reader or a buffered IO writer object to perform\nIO operations in Zig. Because they deliver better performance to your IO operations.\n:::\n\n\n## Filesystem basics\n\nNow that we have discussed the basics around Input/Output operations in Zig, we need to\ntalk about the basics around filesystems, which is another core part of any operating system.\nAlso, filesystems are related to input/output, because the files that we store and create in our\ncomputer are considered an IO resource, as we described in @sec-file-descriptor.\n\n\n### The concept of current working directory (CWD)\n\nThe working directory is the folder on your computer where you are currently rooted at.\nIn other words, it's the folder that your program is currently looking at.\nTherefore, whenever you are executing a program, this program is always working with\na specific folder on your computer. It's always in this folder that the program will initially\nlook for the files you require, and it's also in this folder that the program\nwill initially save all the files you ask it to save.\n\nThe working directory is determined by the folder from which you invoke your program\nin the terminal. In other words, if you are in the terminal of your OS, and you\nexecute a binary file (i.e., a program) from this terminal, the folder to which your terminal\nis pointing at is the current working directory of your program that is being executed.\n\nIn @fig-cwd we have an example of me executing a program from the terminal. We are executing\nthe program outputted by the `zig` compiler by compiling the Zig module named `hello.zig`.\nThe CWD in this case is the `zig-book` folder. In other words, while the `hello.zig` program\nis executing, it will be looking at the `zig-book` folder, and any file operation that we perform\ninside this program, will be using this `zig-book` folder as the \"starting point\", or, as the \"central focus\".\n\n![Executing a program from the terminal](./../Figures/cwd.png){#fig-cwd}\n\nJust because we are rooted inside a particular folder (in the case of @fig-cwd, the `zig-book` folder) of our computer,\nit doesn't mean that we cannot access or write resources in other locations of our computer.\nThe current working directory (CWD) mechanism just defines where your program will look first\nfor the files you ask for. This does not prevent you from accessing files that are located\nelsewhere on your computer. However, to access any file that is in a folder other than your\ncurrent working directory, you must provide a path to that file or folder.\n\n\n### The concept of paths\n\nA path is essentially a location. It points to a location in your filesystem. We use\npaths to describe the location of files and folders in our computer.\nOne important aspect about paths is that they are always written inside strings,\ni.e., they are always provided as text values.\n\nThere are two types of paths that you can provide to any program in any OS: a relative path, or an absolute path.\nAbsolute paths are paths that start at the root of your filesystem, and go all the way to the file name or the specific folder\nthat you are referring to. This type of path is called absolute, because it points to an unique and absolute location on your computer.\nThat is, there is no other existing location on your computer that corresponds to this path. It's an unique identifier.\n\nIn Windows, an absolute path is a path that starts with a hard disk identifier (e.g. `C:/Users/pedro`).\nOn the other hand, absolute paths in Linux and macOS, are paths that start with a forward slash character (e.g. `/usr/local/bin`).\nNotice that a path is composed by \"segments\". Each segment is connected to each other by a slash character (`\\` or `/`).\nOn Windows, the backward slash (`\\`) is normally used to connect the path segments. While on Linux and macOS, the forward\nslash (`/`) is the character used to connect path segments.\n\nA relative path is a path that start at the CWD. In other words, a relative path is\n\"relative to the CWD\". The path used to access the `hello.zig` file in @fig-cwd is an example of a relative path. This path\nis reproduced below. This path begins at the CWD, which in the context of @fig-cwd, is the `zig-book` folder,\nthen, it goes to the `ZigExamples` folder, then, into `zig-basics`, then, to the `hello.zig` file.\n\n```\nZigExamples/zig-basics/hello_world.zig\n```\n\n\n### Path wildcards\n\nWhen providing paths, especially relative paths, you have the option of using a *wildcard*.\nThere are two commonly used *wildcards* in paths, which are \"one period\" (.) and \"two periods\" (..).\nIn other words, these two specific characters have special meanings when used in paths,\nand can be used on any operating system (Mac, Windows, Linux, etc.). That is, they\nare \"cross platform\".\n\nThe \"one period\" represents an alias for the current directory.\nThis means that the relative paths `\"./Course/Data/covid.csv\"` and `\"Course/Data/covid.csv\"` are equivalent.\nOn the other hand, the \"two periods\" refers to the previous directory.\nFor example, the path `\"Course/..\"` is equivalent to the path `\".\"`, that is, the current working directory.\n\nTherefore, the path `\"Course/..\"` refers to the folder before the `Course` folder.\nAs another example, the path `\"src/writexml/../xml.cpp\"` refers to the file `xml.cpp`\nthat is inside the folder before the `writexml` folder, which in this example is the `src` folder.\nTherefore, this path is equivalent to `\"src/xml.cpp\"`.\n\n\n\n\n## The CWD handler\n\nIn Zig, filesystem operations are usually made through a directory handler object.\nA directory handler in Zig is an object of type `Dir`, which is an object that describes\na particular folder in the filesystem of our computer.\nYou normally create a `Dir` object, by calling the `std.fs.cwd()` function.\nThis function returns a `Dir` object that points to (or, that describes) the\ncurrent working directory (CWD).\n\nThrough this `Dir` object, you can create new files, or modify, or read existing ones that are\ninside your CWD. In other words, a `Dir` object is the main entrypoint in Zig to perform\nmultiple types of filesystem operations.\nIn the example below, we are creating this `Dir` object, and storing it\ninside the `cwd` object. Although we are not using this object at this code example,\nwe are going to use it a lot over the next examples.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\n_ = cwd;\n```\n:::\n\n\n\n\n\n\n\n\n\n## File operations\n\n### Creating files {#sec-creating-files}\n\nWe create new files by using the `createFile()` method from the `Dir` object.\nJust provide the name of the file that you want to create, and this function will\ndo the necessary steps to create such file. You can also provide a relative path to this function,\nand it will create the file by following this path, which is relative to the CWD.\n\nThis function might return an error, so, you should use `try`, `catch`, or any of the other methods presented\nin @sec-error-handling to handle the possible error. But if everything goes well,\nthis `createFile()` method returns a file descriptor object (i.e., a `File` object) as result,\nthrough which you can add content to the file with the IO operations that I presented before.\n\nTake this code example below. In this example, we are creating a new text file\nnamed `foo.txt`. If the function `createFile()` succeeds, the object named `file` will contain a file descriptor\nobject, which we can use to write (or add) new content to the file, like we do in this example, by using\na buffered writer object to write a new line of text to the file.\n\nNow, a quick note, when we create a file descriptor object in C, by using a C function like `fopen()`, we must always close the file\nat the end of our program, or, as soon as we complete all operations that we wanted to perform\non the file. In Zig, this is no different. So everytime we create a new file, this file remains\n\"open\", waiting for some operation to be performed. As soon as we are done with it, we always have\nto close this file, to free the resources associated with it.\nIn Zig, we do this by calling the method `close()` from the file descriptor object.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.createFile(\"foo.txt\", .{});\n// Don't forget to close the file at the end.\ndefer file.close();\n// Do things with the file ...\nvar fw = file.writer();\n_ = try fw.writeAll(\n    \"Writing this line to the file\\n\"\n);\n```\n:::\n\n\n\nSo, in this example we not only have created a file into the filesystem,\nbut we also wrote some data into this file, using the file descriptor object\nreturned by `createFile()`. If the file that you are trying to create\nalready exists in your filesystem, this `createFile()` call will\noverwrite the contents of the file, or, in other words, it will\nin erase all the contents of the existing file.\n\nIf you don't want this to happen, meaning, that you don't want to overwrite\nthe contents of the existing file, but you want to write data to this file anyway\n(i.e., you want to append data to the file), you should use the `openFile()`\nmethod from the `Dir` object.\n\nAnother important aspect about `createFile()` is that this method creates a file\nthat is not open to read operations by default. It means that you cannot read this file.\nYou are not allowed to.\nSo for example, you might want to write some stuff into this file at the beginning of the execution\nof your program. Then, at a future point in your program you might need to read what you\nwrote in this file. If you try to read data from this file, you will likely\nget a `NotOpenForReading` error as result.\n\n\nBut how can you overcome this barrier? How can you create a file that is open\nto read operations? All you have to do, is to set the `read` flag to true\nin the second argument of `createFile()`. When you set this flag to true,\nthen the file gets create with \"read permissions\", and, as consequence,\na program like this one below becomes valid:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.createFile(\n    \"foo.txt\",\n    .{ .read = true }\n);\ndefer file.close();\n\nvar fw = file.writer();\n_ = try fw.writeAll(\"We are going to read this line\\n\");\n\nvar buffer: [300]u8 = undefined;\n@memset(buffer[0..], 0);\ntry file.seekTo(0);\nvar fr = file.reader();\n_ = try fr.readAll(buffer[0..]);\ntry stdout.print(\"{s}\\n\", .{buffer});\n```\n:::\n\n\n\n```\nWe are going to read this line\n```\n\n\nIf you are not familiar with position indicators, you might not recognize the method\n`seekTo()`. If that is your case, do not worry,\nwe are going to talk more about this method in @sec-indicators. But essentially\nthis method is moving the position indicator back to the beginning of the file,\nso that we can read the contents of the file from the beginning.\n\n\n### Opening files and appending data to it\n\nOpening files is easy. Just use the `openFile()` method instead of `createFile()`.\nIn the first argument of `openFile()` you provide the path to the file that\nyou want to open. Then, on the second argument you provide the flags (or, the options)\nthat dictates how the file is opened.\n\nYou can see the full list of options for `openFile()` by visiting the documentation for\n[`OpenFlags`](https://ziglang.org/documentation/master/std/#std.fs.File.OpenFlags)[^oflags].\nBut the main flag that you will most certainly use is the `mode` flag.\nThis flag specifies the IO mode that the file will be using when it gets opened.\nThere are three IO modes, or, three values that you can provide to this flag, which are:\n\n- `read_only`, allows only read operations on the file. All write operations are blocked.\n- `write_only`, allows only write operations on the file. All read operations are blocked.\n- `read_write`, allows both write and read operations on the file.\n\n[^oflags]: <https://ziglang.org/documentation/master/std/#std.fs.File.OpenFlags>\n\nThese modes are similar to the modes that you provide to the `mode` argument of the\n`open()` Python built-in function[^py-open], or, the `mode` argument of the\n`fopen()` C function[^c-open].\nIn the code example below, we are opening the `foo.txt` text file with a `write_only` mode,\nand appending a new line of text to the end of the file. We use `seekFromEnd()` this time\nto guarantee that we are going to append the text to the end of the file. Once again, methods\nsuch as `seekFromEnd()` are described in more depth in @sec-indicators.\n\n[^py-open]: <https://docs.python.org/3/tutorial/inputoutput.html#reading-and-writing-files>\n[^c-open]: <https://www.tutorialspoint.com/c_standard_library/c_function_fopen.htm>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst file = try cwd.openFile(\n    \"foo.txt\", .{ .mode = .write_only }\n);\ndefer file.close();\ntry file.seekFromEnd(0);\nvar fw = file.writer();\n_ = try fw.writeAll(\"Some random text to write\\n\");\n```\n:::\n\n\n\n### Deleting files\n\nSometimes, we just need to delete/remove the files that we have.\nTo do that, we use the `deleteFile()` method. You just provide the path of the\nfile that you want to delete, and this method will try to delete the file located\nat this path.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.deleteFile(\"foo.txt\");\n```\n:::\n\n\n### Copying files\n\nTo copy existing files, we use the `copyFile()` method. The first argument in this method\nis the path to the file that you want to copy. The second argument is a `Dir` object, i.e., a directory handler,\nmore specifically, a `Dir` object that points to the folder in your computer where you want to\ncopy the file to. The third argument is the new path of the file, or, in other words, the new location\nof the file. The fourth argument is the options (or flags) to be used in the copy operation.\n\nThe `Dir` object that you provide as input to this method will be used to copy the file to\nthe new location. You may create this `Dir` object before calling the `copyFile()` method.\nMaybe you are planning to copy the file to a completely different location in your computer,\nso it might be worth to create a directory handler to that location. But if you are copying the\nfile to a subfolder of your CWD, then, you can just simply pass the CWD handler to this argument.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.copyFile(\n    \"foo.txt\",\n    cwd,\n    \"ZigExamples/file-io/foo.txt\",\n    .{}\n);\n```\n:::\n\n\n\n### Read the docs!\n\nThere are some other useful methods for file operations available at `Dir` objects,\nsuch as the `writeFile()` method, but I recommend you to read the docs for the\n[`Dir` type](https://ziglang.org/documentation/master/std/#std.fs.Dir)[^zig-dir]\nto explore the other available methods, since I already talked too much about them.\n\n\n[^zig-dir]: <https://ziglang.org/documentation/master/std/#std.fs.Dir>\n\n\n\n\n## Position indicators {#sec-indicators}\n\nA position indicator is like a type of cursor, or, an index. This \"index\" identifies the current\nlocation in the file (or, in the data stream) that the file descriptor object that you have\nis currently looking at.\nWhen you create a file descriptor, the position indicator starts at the beginning of the file,\nor, at the beginning of the stream. When you read from or write into the file (or socket, or data stream, etc.)\ndescribed by this file descriptor object, you end up moving the position indicator.\n\nIn other words, any IO operation have a common side effect, which is to move the position indicator.\nFor example, suppose that we have a file of 300 bytes total in size. If you\nread 100 bytes from the file, then, the position indicator moves 100 bytes forward. If you try\nto write 50 bytes into this same file, these 50 bytes will be written from the current\nposition indicated by the position indicator. Since the indicator is at a 100 bytes forward from\nthe beginning of the file, these 50 bytes would be written in the middle of the file.\n\nThis is why we have used the `seekTo()` method at the last code example presented in @sec-creating-files.\nWe have used this method to move the position indicator back to the beginning of the file, which\nwould make sure that we would write the text that we wanted to write from the beginning of the file,\ninstead of writing it from the middle of the file. Because before the write operation, we had\nperformed a read operation, which means that the position indicator was moved in this read operation.\n\nThe position indicators of a file descriptor object can be changed (or altered) by using the\n\"seek\" methods from this file descriptor, which are: `seekTo()`, `seekFromEnd()` and `seekBy()`.\nThese methods have the same effect, or, the same responsibility that the\n[`fseek()`](https://en.cppreference.com/w/c/io/fseek)[^c-fseek] C function.\n\n[^c-fseek]: <https://en.cppreference.com/w/c/io/fseek>\n\n\nConsidering that `offset` refers to the index that you provide as input to these \"seek\" methods,\nthe bullet points below summarises what is the effect of each of these methods.\nAs a quick note, in the case of `seekFromEnd()` and `seekBy()`, the `offset` provided can be either a\npositive or a negative index.\n\n- `seekTo()` will move the position indicator to the location that is `offset` bytes from the beginning of the file.\n- `seekFromEnd()` will move the position indicator to the location that is `offset` bytes from the end of the file.\n- `seekBy()` will move the position indicator to the location that is `offset` bytes from the current position in the file.\n\n\n\n\n\n\n\n## Directory operations\n\n### Iterating through the files in a directory\n\nOne of the most classic tasks related to filesystem is to be able\nto iterate through the existing files in a directory. To iterate over the\nfiles in a directory, we need to create an iterator object.\n\nYou can produce such iterator object by using either the `iterate()` or `walk()` methods\nof a `Dir` object. Both methods return an iterator object as output, which you can advance by using the\n`next()` method. The difference between these methods, is that `iterate()` returns a non-recursive iterator,\nwhile `walk()` does. It means that the iterator returned by `walk()` will not only iterate through\nthe files available in the current directory, but also, through the files from any subdirectory found\ninside the current directory.\n\nIn the example below, we are displaying the names of the files stored inside the\ndirectory `ZigExamples/file-io`. Notice that we had to open this directory through\nthe `openDir()` function. Also notice that we provided the flag `iterate` in the\nsecond argument of `openDir()`. This flag is important, because without this flag,\nwe would not be allowed to iterate through the files in this directory.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\nconst dir = try cwd.openDir(\n    \"ZigExamples/file-io/\",\n    .{ .iterate = true }\n);\nvar it = dir.iterate();\nwhile (try it.next()) |entry| {\n    try stdout.print(\n        \"File name: {s}\\n\",\n        .{entry.name}\n    );\n}\n```\n:::\n\n\n```\nFile name: create_file_and_write_toit.zig\nFile name: create_file.zig\nFile name: lorem.txt\nFile name: iterate.zig\nFile name: delete_file.zig\nFile name: append_to_file.zig\nFile name: user_input.zig\nFile name: foo.txt\nFile name: create_file_and_read.zig\nFile name: buff_io.zig\nFile name: copy_file.zig\n```\n\n\n### Creating new directories\n\nThere are two methods that are important when it comes to\ncreating directories, which are `makeDir()` and `makePath()`.\nThe difference between these two methods is that `makeDir()` can\nonly create one single directory in the current directory in each call,\nwhile `makePath()` is capable of recursively create subdirectories in the same call.\n\n\nThis is why the name of this method is \"make path\". It will create as many\nsubdirectories as necessary to create the path that you provided as input.\nSo, if you provide the path `\"sub1/sub2/sub3\"` as input to this method,\nit will create three different subdirectories, `sub1`, `sub2` and `sub3`,\nwithin the same function call. In contrast, if you provided such path\nas input to `makeDir()`, you would likely get an error as result, since\nthis method can only create a single subdirectory.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.makeDir(\"src\");\ntry cwd.makePath(\"src/decoders/jpg/\");\n```\n:::\n\n\n### Deleting directories\n\nTo delete a directory, just provide the path to the directory that you want to delete\nas input to the `deleteDir()` method from a `Dir` object. In the example below,\nwe are deleting the `src` directory that we have just created in the previous example.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst cwd = std.fs.cwd();\ntry cwd.deleteDir(\"src\");\n```\n:::\n\n\n\n## Conclusion\n\nIn this chapter, I have described how to perform in Zig the most common filesystem and IO operations.\nBut you might feel the lack of some other, less common, operation in this chapter, such as: how to rename files,\nor how to open a directory, or how to create symbolic links, or how to use `access()` to test if a particular\npath exists in your computer. But for all of these less common tasks, I recommend you to read\nthe documentation of the [`Dir` type](https://ziglang.org/documentation/master/std/#std.fs.Dir)[^zig-dir]\n, since you can find a good description of these cases there.\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/13-image-filter/execute-results/epub.json b/_freeze/Chapters/13-image-filter/execute-results/epub.json
deleted file mode 100644
index 31e3f7fe..00000000
--- a/_freeze/Chapters/13-image-filter/execute-results/epub.json
+++ /dev/null
@@ -1,21 +0,0 @@
-{
-  "hash": "99b3cf5d4ae363f25838f780686e3234",
-  "result": {
-    "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Project 4 - Developing an image filter\n\nIn this chapter we are going to build a new project. The objective of\nthis project is to write a program that applies a filter over an image.\nMore specifically, a \"grayscale filter\", which transforms\nany color image into a grayscale image.\n\nWe are going to use the image displayed in @fig-pascal in this project.\nIn other words, we want to transform this colored image into a grayscale image,\nby using our \"image filter program\" written in Zig.\n\n![A photo of the chilean-american actor Pedro Pascal. Source: Google Images.](../ZigExamples/image_filter/pedro_pascal.png){#fig-pascal}\n\nWe don't need to write a lot of code to build such \"image filter program\". However, we first need\nto understand how digital images work. That is why we begin this chapter\nby explaining the theory behind digital images and how colors are represented in modern computers.\nWe also give a brief explanation about the PNG (Portable Network Graphics) file format, which is the format used\nin the example images.\n\nAt the end of this chapter, we should have a full example of a program that takes the PNG image displayed in @fig-pascal\nas input, and writes a new image to the current working directory that is the grayscale version of this input image.\nThis grayscale version of @fig-pascal is exposed in @fig-pascal-gray.\nYou can find the full source code of this small project at the `ZigExamples/image_filter`\n[folder at the official repository of this book](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter)[^img-filter-folder].\n\n\n![The grayscale version of the photo.](../ZigExamples/image_filter/pedro_pascal_filter.png){#fig-pascal-gray}\n\n\n## How we see things? {#sec-eyes}\n\nIn this section, I want to briefly describe to you how we (humans) actually see things with our own eyes.\nI mean, how our eyes work? If you do have a very basic understanding of how our eyes work, you will understand\nmore easily how digital images are made. Because the techniques behind digital images\nwere developed by taking a lot of inspiration from how our human eyes work.\n\nYou can interpret a human eye as a light sensor, or, a light receptor. The eye receives some amount of light as input,\nand it interprets the colors that are present in this \"amount of light\".\nIf no amount of light hits the eye, then, the eye cannot extract color from it, and as result,\nwe end up seeing nothing, or, more precisely, we see complete blackness.\n\nTherefore, everything depends on light. What we actually see are the colors (blue, red, orange, green, purple, yellow, etc.) that\nare being reflected from the light that is hitting our eyes. **Light is the source of all colors!**\nThis is what Isaac Newton discovered on his famous prism experiment[^newton] in the 1660s.\n\n[^newton]: <https://library.si.edu/exhibition/color-in-a-new-light/science>\n\nInside our eyes, we have a specific type of cell called the \"cone cell\".\nOur eye have three different types, or, three different versions of these \"cone cells\".\nEach type of cone cell is very sensitive to a specific spectrum of the light. More specifically,\nto the spectrums that define the colors red, green and blue.\nSo, in summary, our eyes have specific types of cells that\nare highly sensitive to these three colors (red, green and blue).\n\nThese are the cells responsible for perceiving the color present in the light that hits our eyes.\nAs a result, our eyes perceives color as a mixture of these three colors (red, green and blue). By having an amount\nof each one of these three colors, and mixing them together, we can get any other visible color\nthat we want. So every color that we see is perceived as a specific mixture of blues, greens and reds,\nlike 30% of red, plus 20% of green, plus 50% of blue.\n\nWhen these cone cells perceive (or, detect) the colors that are found in the\nlight that is hitting our eyes, these cells produce electrical signals, which are sent to the brain.\nOur brain interprets these electrical signals, and use them to form the image that we are seeing\ninside our head.\n\nBased on what we have discussed here, the bullet points exposed below describes the sequence of events that\ncomposes this very simplified version of how our human eyes work:\n\n1. Light hits our eyes.\n1. The cone cells perceive the colors that are present in this light.\n1. Cone cells produce electrical signals that describes the colors that were perceived in the light.\n1. The electrical signals are sent to the brain.\n1. Brain interprets these signals, and form the image based on the colors identified by these electrical signals.\n\n\n## How digital images work? {#sec-digital-img}\n\nA digital image is a \"digital representation\" of an image that we see with our eyes.\nIn other words, a digital image is a \"digital representation\" of the colors that we see\nand perceive through the light.\nIn the digital world, we have two types of images, which are: vector images and raster images.\nVector images are not described here. So just remember that the content discussed here\n**is related solely to raster images**, and not vector images.\n\nA raster image is a type of digital image that is represented as a 2D (two dimensional) matrix\nof pixels. In other words, every raster image is basically a rectangle of pixels, and each pixel have a particular color.\nSo, a raster image is just a rectangle of pixels, and each of these pixels are displayed in the screen of your computer (or the screen\nof any other device, e.g. laptop, tablet, smartphone, etc.) as a color.\n\n@fig-raster demonstrates this idea. If you take any raster image, and you zoom into it very hard,\nyou will see the actual pixels of the image. JPEG, TIFF and PNG are file formats that are commonly\nused to store raster images.\n\n![Zooming over a raster image to see the pixels. Source: Google Images.](../Figures/imagem-raster.png){#fig-raster}\n\nThe more pixels the image has, the more information and detail we can include in the image.\nThe more accurate, sharp and pretty the image will look. This is why photographic cameras\nusually produce big raster images, with several megapixels of resolution, to include as much detail as possible into the final image.\nAs an example, a digital image with dimensions of 1920 pixels wide and 1080 pixels high, would be a image that\ncontains $1920 \\times 1080 = 2073600$ pixels in total. You could also say that the \"total area\" of the image is\nof 2073600 pixels, although the concept of \"area\" is not really used here in computer graphics.\n\nMost digital images we see in our modern world uses the RGB color model. RGB stands for (red, green and blue).\nSo the color of each pixel in these raster images are usually represented as a mixture of red, green and blue,\njust like in our eyes. That is, the color of each pixel is identified by a set of\nthree different integer values. Each integer value identifies the \"amount\" of each color (red, green and blue).\nFor example, the set `(199, 78, 70)` identifies a color that is more close to red. We have 199 of red, 78 of green,\nand 70 of blue. In contrast, the set `(129, 77, 250)` describes a color that is more close to purple. Et cetera.\n\n\n\n### Images are displayed from top to bottom\n\nThis is not a rule written in stone, but the big majority of digital images are displayed from top\nto bottom and left to right. Most computers screens also follow this pattern. So, the first pixels\nin the image are the ones that are at the top and left corner of the image. You can find a visual representation\nof this logic in @fig-img-display.\n\nAlso notice in @fig-img-display that, because a raster image is essentially a 2D matrix of pixels,\nthe image is organized into rows and columns of pixels. The columns are defined by the horizontal x axis,\nwhile the rows are defined by the vertical y axis.\n\nEach pixel (i.e., the gray rectangles) exposed in @fig-img-display contains a number inside of it.\nThese numbers are the indexes of the pixels. You can notice that the first pixels are in the top and left\ncorner, and also, that the indexes of these pixels \"grow to the sides\", or, in other words, they grow in the direction of the horizontal x axis.\nMost raster images are organized as rows of pixels. Thus, when these digital images are\ndisplayed, the screen display the first row of pixels, then, the second row, then, the third row, etc.\n\n![How the pixels of raster images are displayed.](./../Figures/image-display.png){#fig-img-display}\n\n\n\n\n\n\n### Representing the matrix of pixels in code {#sec-pixel-repr}\n\nOk, we know already that raster images are represented as 2D matrices of pixels.\nBut we do not have a notion of a 2D matrix in Zig. Actually, most low-level languages in general\n(Zig, C, Rust, etc.) do not have such notion.\nSo how can we represent such matrix of pixels in Zig, or any other low-level language?\nThe strategy that most programmers choose in this situation is to just use a normal 1D array to store the values of\nthis 2D matrix. In other words, you just create an normal 1D array, and store all values from both dimensions into this 1D array.\n\nAs an example, suppose we have a very small image of dimensions 4x3.\nSince a raster image is represented as a 2D matrix of pixels, and each pixel\nis represented by 3 \"unsigned 8-bit\" integer values, we have 12 pixels in\ntotal in this image, which are represented by $3 \\times 12 = 36$ integer values.\nTherefore, we need to create an array of 36 `u8` values to store this small image.\n\nThe reason why unsigned 8-bit integer (`u8`) values are used to represent the amounts of each color,\ninstead of any other integer type, is because they take the minimum amount of space as possible, or,\nthe minimum amount of bits as possible. Which helps to reduces the binary size of the image, i.e., the 2D matrix.\nAlso, they convey a good amount of precision and detail about the colors, even though they can represent\na relatively small range (from 0 to 255) of \"color amounts\".\n\nComing back to our initial example of a 4x3 image,\nthe `matrix` object exposed below could be an example of an 1D array that stores\nthe data that represents this 4x3 image.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst matrix = [_]u8{\n    201, 10, 25, 185, 65, 70,\n    65, 120, 110, 65, 120, 117,\n    98, 95, 12, 213, 26, 88,\n    143, 112, 65, 97, 99, 205,\n    234, 105, 56, 43, 44, 216,\n    45, 59, 243, 211, 209, 54,\n};\n```\n:::\n\n\n\nThe first three integer values in this array are the color amounts of the first pixel in the image.\nThe next three integers are the colors amounts for the second pixel.\nAnd the sequence goes on in this pattern. Having that in mind, the size of the array that stores\na raster image is usually a multiple of 3. In this case, the array have a size of 36.\n\nI mean, the size of the array is **usually** a multiple of 3, because in specific circumstances,\nit can also be a multiple of 4. This happens when a transparency amount is\nalso included into the raster image. In other words, there are some types of raster images\nthat uses a different color model, which is the RGBA (red, green, blue and alpha)\ncolor model. The \"alpha\" corresponds to an amount of transparency in the pixel.\nSo every pixel in a RGBA image is represented by a red, green, blue and alpha values.\n\nMost raster images uses the standard RGB model, so, for the most part, you will\nsee arrays sizes that are multiples of 3. But some images, especially the ones\nthat are stored in PNG files, might be using the RGBA model, and, therefore, are\nrepresented by an array whose size is a multiple of 4.\n\nIn our case here, the example image of our project (@fig-pascal) is a raster image\nstored in a PNG file, and this specific image is using the RGBA color model. Therefore,\neach pixel in the image is represented by 4 different integer values, and, as consequence,\nto store this image in our Zig code, we need to create an array whose size is a multiple of 4.\n\n\n## The PNG library that we are going to use\n\nLet's begin our project by focusing on writing the necessary Zig code to\nread the data from the PNG file. In other words, we want to read the PNG file exposed\nin @fig-pascal, and parse its data to extract the 2D matrix of pixels that represents the image.\n\nAs we have discussed in @sec-pixel-repr, the image that we are using as example here\nis a PNG file that uses the RGBA color model, and, therefore, each pixel of the image\nis represented by 4 integer values. You can download this image by visiting the `ZigExamples/image_filter`\n[folder at the official repository of this book](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter)[^img-filter-folder].\nYou can also find in this folder the complete source code of this small project that we\nare developing here.\n\n[^img-filter-folder]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter>\n\nThere are some C libraries available that we can use to read and parse PNG files.\nThe most famous and used of all is `libpng`, which is the \"official library\" for reading and writing\nPNG files. Although this library is available on most operating system, it's well known\nfor being complex and hard to use.\n\nThat is why, I'm going to use a more modern alternative here in this project, which is the `libspng` library.\nI choose to use this C library here, because it's much, much simpler to use than `libpng`,\nand it also offers very good performance for all operations. You can checkout the\n[official website of the library](https://libspng.org/)[^libspng]\nto know more about it. You will also find there some documentation that might help you to understand and\nfollow the code examples exposed here.\n\n[^libspng]: <https://libspng.org/>\n\n\nFirst of all, remember to build and install this `libspng` into your system. Because\nif you don't do this step, the `zig` compiler will not be able to find the files and resources of\nthis library in your computer, and link them with the Zig source code that we are writing together here.\nThere is good information about how to build and install the library at the\n[build section of the library documentation](https://libspng.org/docs/build/)[^lib-build].\n\n[^lib-build]: <https://libspng.org/docs/build/>\n\n\n\n\n## Reading the PNG file\n\nIn order to extract the pixel data from the PNG file, we need to read and decode the file.\nA PNG file is just a binary file written in the \"PNG format\". Luckily, the `libspng` library offers\na function called `spng_decode_image()` that does all this heavy work for us.\n\nNow, since `libspng` is a C library, most of the file and I/O operations in this library are made by using\na `FILE` C pointer. Because of that, is probably a better idea to use the `fopen()` C function\nto open our PNG file, instead of using the `openFile()` method that I introduced in @sec-filesystem.\nThat is why I'm importing the `stdio.h` C header in this project, and using the `fopen()` C function to open the file.\n\nIf you look at the snippet below, you can see that we are:\n\n1. opening the PNG file with `fopen()`.\n1. creating the `libspng` context with `spng_ctx_new()`.\n1. using `spng_set_png_file()` to specify the `FILE` object that reads the PNG file that we are going to use.\n\nEvery operation in `libspng` is made through a \"context object\". In our snippet below, this object is `ctx`.\nAlso, to perform an operation over a PNG file, we need to specify which exact PNG file we are referring to.\nThis is the job of `spng_set_png_file()`. We are using this function to specify the file descriptor\nobject that reads the PNG file that we want to use.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n    @cInclude(\"spng.h\");\n});\n\nconst path = \"pedro_pascal.png\";\nconst file_descriptor = c.fopen(path, \"rb\");\nif (file_descriptor == null) {\n    @panic(\"Could not open file!\");\n}\nconst ctx = c.spng_ctx_new(0) orelse unreachable;\n_ = c.spng_set_png_file(\n    ctx, @ptrCast(file_descriptor)\n);\n```\n:::\n\n\n\nBefore we continue, is important to emphasize the following: since we have opened the file with `fopen()`,\nwe have to remember to close the file at the end of the program, with `fclose()`.\nIn other words, after we have done everything that we wanted to do with the PNG file\n`pedro_pascal.png`, we need to close this file, by applying `fclose()` over the file descriptor object.\nWe could use also the `defer` keyword to help us in this task, if we want to.\nThis code snippet below demonstrates this step:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (c.fclose(file_descriptor) != 0) {\n    return error.CouldNotCloseFileDescriptor;\n}\n```\n:::\n\n\n\n\n\n\n### Reading the image header section\n\nNow, the context object `ctx` is aware of our PNG file `pedro_pascal.png`, because it has access to\na file descriptor object to this file. The first thing that we are going to do is to read the\n\"image header section\" of the PNG file. This \"image header section\" is the section\nof the file that contains some basic information about the PNG file, like, the bit depth of the pixel data\nof the image, the color model used in the file, the dimensions of the image (height and width in number of pixels),\netc.\n\nTo make things easier, I will encapsulate this \"read image header\" operation into a\nnice and small function called `get_image_header()`. All that this function needs to do\nis to call the `spng_get_ihdr()` function. This function from `libspng` is responsible\nfor reading the image header data, and storing it into a C struct named `spng_ihdr`.\nThus, an object of type `spng_ihdr` is a C struct that contains the data from the\nimage header section of the PNG file.\n\nSince this Zig function is receiving a C object (the `libspng` context object) as input, I marked\nthe function argument `ctx` as \"a pointer to the context object\" (`*c.spng_ctx`), following the recommendations\nthat we have discussed in @sec-pass-c-structs.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn get_image_header(ctx: *c.spng_ctx) !c.spng_ihdr {\n    var image_header: c.spng_ihdr = undefined;\n    if (c.spng_get_ihdr(ctx, &image_header) != 0) {\n        return error.CouldNotGetImageHeader;\n    }\n\n    return image_header;\n}\n\nvar image_header = try get_image_header(ctx);\n```\n:::\n\n\n\nAlso notice in this function, that I'm checking if the `spng_get_ihdr()` function call have\nreturned or not an integer value that is different than zero. Most functions from the\n`libspng` library return a code status as result, and the code status \"zero\" means\n\"success\". So any code status that is different than zero means that an error\noccurred while running `spng_get_ihdr()`. This is why I'm returning an error value from\nthe function in case the code status returned by the function is different than zero.\n\n\n### Allocating space for the pixel data\n\nBefore we read the pixel data from the PNG file, we need to allocate enough space to hold this data.\nBut in order to allocate such space, we first need to know how much space we need to allocate.\nThe dimensions of the image are obviously needed to calculate the size of this space. But there are\nother elements that also affect this number, such as the color model used in the image, the bit depth, and others.\n\nAnyway, all of this means that calculating the size of the space that we need, is not a simple task.\nThat is why the `libspng` library offers an utility function named\n`spng_decoded_image_size()` to calculate this size for us. Once again, I'm going\nto encapsulate the logic around this C function into a nice and small Zig function\nnamed `calc_output_size()`. You can see below that this function returns a nice\ninteger value as result, informing the size of the space that we need to allocate.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn calc_output_size(ctx: *c.spng_ctx) !u64 {\n    var output_size: u64 = 0;\n    const status = c.spng_decoded_image_size(\n        ctx, c.SPNG_FMT_RGBA8, &output_size\n    );\n    if (status != 0) {\n        return error.CouldNotCalcOutputSize;\n    }\n    return output_size;\n}\n```\n:::\n\n\n\n\n\nYou might quest yourself what the value `SPNG_FMT_RGBA8` means. This value is actually an enum\nvalue defined in the `spng.h` C header file. This enum is used to identify a \"PNG format\".\nMore precisely, it identifies a PNG file that uses the RGBA color model and 8 bit depth.\nSo, by providing this enum value as input to the `spng_decoded_image_size()` function,\nwe are saying to this function to calculate the size of the decoded pixel data, by considering\na PNG file that follows this \"RGBA color model with 8 bit depth\" format.\n\nHaving this function, we can use it in conjunction with an allocator object, to allocate an\narray of bytes (`u8` values) that is big enough to store the decoded pixel data of the image.\nNotice that I'm using `@memset()` to initialize the entire array to zero.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst output_size = try calc_output_size(ctx);\nvar buffer = try allocator.alloc(u8, output_size);\n@memset(buffer[0..], 0);\n```\n:::\n\n\n\n\n### Decoding the image data\n\nNow that we have the necessary space to store the decoded pixel data of the image,\nwe can start to actually decode and extract this pixel data from the image,\nby using the `spng_decode_image()` C function.\n\nThe `read_data_to_buffer()` Zig function exposed below summarises the necessary\nsteps to read this decoded pixel data, and store it into an input buffer.\nNotice that this function is encapsulating the logic around the `spng_decode_image()` function.\nAlso, we are using the `SPNG_FMT_RGBA8` enum value once again to inform the corresponding function,\nthat the PNG image being decoded, uses the RGBA color model and 8 bit depth.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn read_data_to_buffer(ctx: *c.spng_ctx, buffer: []u8) !void {\n    const status = c.spng_decode_image(\n        ctx,\n        buffer.ptr,\n        buffer.len,\n        c.SPNG_FMT_RGBA8,\n        0\n    );\n\n    if (status != 0) {\n        return error.CouldNotDecodeImage;\n    }\n}\n```\n:::\n\n\n\nHaving this function at hand, we can apply it over our context object, and also, over\nthe buffer object that we have allocated in the previous section to hold the decoded pixel data\nof the image:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry read_data_to_buffer(ctx, buffer[0..]);\n```\n:::\n\n\n\n\n### Looking at the pixel data\n\nNow that we have the pixel data stored in our \"buffer object\", we can take\na quick look at the bytes. In the example below, we are looking at the first\n12 bytes in the decoded pixel data.\n\nIf you take a close look at these values, you might notice that every 4 bytes\nin the sequence is 255. Which, coincidentally is the maximum possible integer value\nto be represented by a `u8` value. So, if the range from 0 to 255, which is the range\nof integer values that can be represented by an `u8` value, can be represented as a scale from 0% to 100%,\nthese 255 values are essentially 100% in that scale.\n\nIf you recall from @sec-pixel-repr, I have\ndescribed in that section that our `pedro_pascal.png` PNG file uses the RGBA color model,\nwhich adds an alpha (or transparency) byte to each pixel in the image.\nAs consequence, each pixel in the image is represented by 4 bytes. Since we are looking\nhere are the first 12 bytes in the image, it means that we are looking at the data from\nthe first $12 / 4 = 3$ pixels in the image.\n\nSo, based on how these first 12 bytes (or these 3 pixels) look, with these 255 values at every 4 bytes, we can say that is likely\nthat every pixel in the image have alpha (or transparency) setted to 100%. This might not be true,\nbut, is the most likely possibility. Also, if we look at the image itself, which if your recall is\nexposed in @fig-pascal, we can see that the transparency does not change across the image,\nwhich enforces this theory.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry stdout.print(\"{any}\\n\", .{buffer[0..12]});\n```\n:::\n\n\n\n```\n{\n    200, 194, 216, 255, 203, 197,\n    219, 255, 206, 200, 223, 255\n}\n```\n\n\nWe can see in the above result that the first pixel in this image have 200 of red, 194 of green, and 216 of blue.\nHow do I know the order in which the colors appears in the sequence? If you have not guessed that yet,\nis because of the acronym RGB. First RED, then GREEN, then BLUE. If we scale these integer values\naccording to our scale of 0% to 100% (0 to 255), we get 78% of red, 76% of green and 85% of blue.\n\n\n\n## Applying the image filter\n\nNow that we have the data of each pixel in the image, we can focus on applying our image\nfilter over these pixels. Remember, our objective here is to apply a grayscale filter over\nthe image. A grayscale filter is a filter that transforms a colored image into a grayscale image.\n\nThere are different formulas and strategies to transform a colored image into a grayscale image.\nBut all of these different strategies normally involve applying some math over the colors of each pixel.\nIn this project, we are going to use the most general formula, which is exposed below.\nThis formula considers $r$ as the red of the pixel, $g$ as the green, $b$ as the blue, and $p'$ as the\nlinear luminance of the pixel.\n\n$$\n    p' = (0.2126 \\times r) + (0.7152 \\times g) + (0.0722 \\times b)\n$${#eq-grayscale}\n\nThis @eq-grayscale is the formula to calculate the linear luminance of a pixel. It's worth noting that this formula\nworks only for images whose pixels are using the sRGB color space, which is the standard color space\nfor the web. Thus, ideally, all images on the web should use this color space. Luckily,\nthis is our case here, i.e., the `pedro_pascal.png` image is using this sRGB color space, and, as consequence,\nwe can use the @eq-grayscale. You can read more about this formula at the Wikipedia page for grayscale [@wiki_grayscale].\n\nThe `apply_image_filter()` function exposed below summarises the necessary steps to\napply @eq-grayscale over the pixels in the image. We just apply this function\nover our buffer object that contains our pixel data, and, as result, the pixel\ndata stored in this buffer object should now represent the grayscale version of our image.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn apply_image_filter(buffer:[]u8) !void {\n    const len = buffer.len;\n    const red_factor: f16 = 0.2126;\n    const green_factor: f16 = 0.7152;\n    const blue_factor: f16 = 0.0722;\n    var index: u64 = 0;\n    while (index < len) : (index += 4) {\n        const rf: f16 = @floatFromInt(buffer[index]);\n        const gf: f16 = @floatFromInt(buffer[index + 1]);\n        const bf: f16 = @floatFromInt(buffer[index + 2]);\n        const y_linear: f16 = (\n            (rf * red_factor) + (gf * green_factor)\n            + (bf * blue_factor)\n        );\n        buffer[index] = @intFromFloat(y_linear);\n        buffer[index + 1] = @intFromFloat(y_linear);\n        buffer[index + 2] = @intFromFloat(y_linear);\n    }\n}\n\ntry apply_image_filter(buffer[0..]);\n```\n:::\n\n\n\n\n\n## Saving the grayscale version of the image\n\nSince we have now the grayscale version of our image stored in our buffer object,\nwe need to encode this buffer object back into the \"PNG format\", and save the encoded data into\na new PNG file in our filesystem, so that we can access and see the grayscale version of our image\nthat was produced by our small program.\n\nTo do that, the `libspng` library help us once again by offering an \"encode data to PNG\" type of function,\nwhich is the `spng_encode_image()` function. But in order to \"encode data to PNG\" with `libspng`, we need\nto create a new context object. This new context object must use an \"encoder context\", which\nis identified by the enum value `SPNG_CTX_ENCODER`.\n\nThe `save_png()` function exposed below, summarises all the necessary steps to save the\ngrayscale version of our image into a new PNG file in the filesystem. By default, this\nfunction will save the grayscale image into a file named `pedro_pascal_filter.png` in the CWD.\n\nNotice in this code example that we are using the same image header object (`image_header`) that we have\ncollected previously with the `get_image_header()` function. Remember, this image header object\nis a C struct (`spng_ihdr`) that contains basic information about our PNG file, such as\nthe dimensions of the image, the color model used, etc.\n\nIf we wanted to save a very different image in this new PNG file, e.g. an image\nwith different dimensions, or, an image that uses a different color model, a different bit depth, etc.\nwe would have to create a new image header (`spng_ihdr`) object that describes the properties\nof this new image.\n\nBut we are essentially saving the same image that we have begin with here (the dimensions of\nthe image, the color model, etc. are all still the same). The only difference\nbetween the two images are the colors of the pixels, which are now \"shades of gray\".\nAs consequence, we can safely use the exact same image header data in this new PNG file.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn save_png(image_header: *c.spng_ihdr, buffer: []u8) !void {\n    const path = \"pedro_pascal_filter.png\";\n    const file_descriptor = c.fopen(path.ptr, \"wb\");\n    if (file_descriptor == null) {\n        return error.CouldNotOpenFile;\n    }\n    const ctx = (\n        c.spng_ctx_new(c.SPNG_CTX_ENCODER)\n        orelse unreachable\n    );\n    defer c.spng_ctx_free(ctx);\n    _ = c.spng_set_png_file(ctx, @ptrCast(file_descriptor));\n    _ = c.spng_set_ihdr(ctx, image_header);\n\n    const encode_status = c.spng_encode_image(\n        ctx,\n        buffer.ptr,\n        buffer.len,\n        c.SPNG_FMT_PNG,\n        c.SPNG_ENCODE_FINALIZE\n    );\n    if (encode_status != 0) {\n        return error.CouldNotEncodeImage;\n    }\n    if (c.fclose(file_descriptor) != 0) {\n        return error.CouldNotCloseFileDescriptor;\n    }\n}\n\ntry save_png(&image_header, buffer[0..]);\n```\n:::\n\n\n\nAfter we execute this `save_png()` function, we should have a new PNG file\ninside our CWD, named `pedro_pascal_filter.png`. If we open this PNG file,\nwe will see the same image exposed in @fig-pascal-gray.\n\n\n## Building our project\n\nNow that we have written the code, let's discuss how can we build/compile this project.\nTo do that, I'm going to create a `build.zig` file in the root directory of our project,\nand start writing the necessary code to compile the project, using the knowledge\nthat we have acquired from @sec-build-system.\n\n\nWe first create the build target for our executable file, that executes our\nZig code. Let's suppose that all of our Zig code was written into a Zig module\nnamed `image_filter.zig`. The `exe` object exposed in the build script below\ndescribes the build target for our executable file.\n\nSince we have used some C code from the `libspng` library in our Zig code,\nwe need to link our Zig code (which is in the `exe` build target) to both\nthe C Standard Library, and, to the `libspng` library. We do that, by calling\nthe `linkLibC()` and `linkSystemLibrary()` methods from our `exe` build target.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const target = b.standardTargetOptions(.{});\n    const optimize = b.standardOptimizeOption(.{});\n    const exe = b.addExecutable(.{\n        .name = \"image_filter\",\n        .root_source_file = b.path(\"src/image_filter.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n    exe.linkLibC();\n    // Link to libspng library:\n    exe.linkSystemLibrary(\"spng\");\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\nSince we are using the `linkSystemLibrary()` method, it means that the library\nfiles for `libspng` are searched in your system to be linked with the `exe` build target.\nIf you have not yet built and installed the `libspng` library into your system, this\nlinkage step will likely not work. Because it will not find the library files in your system.\n\nSo, just remember to install `libspng` in your system, if you want to build this project.\nHaving this build script above written, we can finally build our project by\nrunning the `zig build` command in the terminal.\n\n```bash\nzig build\n```\n",
-    "supporting": [
-      "13-image-filter_files"
-    ],
-    "filters": [
-      "rmarkdown/pagebreak.lua"
-    ],
-    "includes": {},
-    "engineDependencies": {
-      "knitr": [
-        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
-      ]
-    },
-    "preserve": null,
-    "postProcess": false
-  }
-}
\ No newline at end of file
diff --git a/_freeze/Chapters/13-image-filter/execute-results/html.json b/_freeze/Chapters/13-image-filter/execute-results/html.json
index 5564dfd4..2fd55048 100644
--- a/_freeze/Chapters/13-image-filter/execute-results/html.json
+++ b/_freeze/Chapters/13-image-filter/execute-results/html.json
@@ -2,10 +2,8 @@
   "hash": "99b3cf5d4ae363f25838f780686e3234",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Project 4 - Developing an image filter\n\nIn this chapter we are going to build a new project. The objective of\nthis project is to write a program that applies a filter over an image.\nMore specifically, a \"grayscale filter\", which transforms\nany color image into a grayscale image.\n\nWe are going to use the image displayed in @fig-pascal in this project.\nIn other words, we want to transform this colored image into a grayscale image,\nby using our \"image filter program\" written in Zig.\n\n![A photo of the chilean-american actor Pedro Pascal. Source: Google Images.](../ZigExamples/image_filter/pedro_pascal.png){#fig-pascal}\n\nWe don't need to write a lot of code to build such \"image filter program\". However, we first need\nto understand how digital images work. That is why we begin this chapter\nby explaining the theory behind digital images and how colors are represented in modern computers.\nWe also give a brief explanation about the PNG (Portable Network Graphics) file format, which is the format used\nin the example images.\n\nAt the end of this chapter, we should have a full example of a program that takes the PNG image displayed in @fig-pascal\nas input, and writes a new image to the current working directory that is the grayscale version of this input image.\nThis grayscale version of @fig-pascal is exposed in @fig-pascal-gray.\nYou can find the full source code of this small project at the `ZigExamples/image_filter`\n[folder at the official repository of this book](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter)[^img-filter-folder].\n\n\n![The grayscale version of the photo.](../ZigExamples/image_filter/pedro_pascal_filter.png){#fig-pascal-gray}\n\n\n## How we see things? {#sec-eyes}\n\nIn this section, I want to briefly describe to you how we (humans) actually see things with our own eyes.\nI mean, how our eyes work? If you do have a very basic understanding of how our eyes work, you will understand\nmore easily how digital images are made. Because the techniques behind digital images\nwere developed by taking a lot of inspiration from how our human eyes work.\n\nYou can interpret a human eye as a light sensor, or, a light receptor. The eye receives some amount of light as input,\nand it interprets the colors that are present in this \"amount of light\".\nIf no amount of light hits the eye, then, the eye cannot extract color from it, and as result,\nwe end up seeing nothing, or, more precisely, we see complete blackness.\n\nTherefore, everything depends on light. What we actually see are the colors (blue, red, orange, green, purple, yellow, etc.) that\nare being reflected from the light that is hitting our eyes. **Light is the source of all colors!**\nThis is what Isaac Newton discovered on his famous prism experiment[^newton] in the 1660s.\n\n[^newton]: <https://library.si.edu/exhibition/color-in-a-new-light/science>\n\nInside our eyes, we have a specific type of cell called the \"cone cell\".\nOur eye have three different types, or, three different versions of these \"cone cells\".\nEach type of cone cell is very sensitive to a specific spectrum of the light. More specifically,\nto the spectrums that define the colors red, green and blue.\nSo, in summary, our eyes have specific types of cells that\nare highly sensitive to these three colors (red, green and blue).\n\nThese are the cells responsible for perceiving the color present in the light that hits our eyes.\nAs a result, our eyes perceives color as a mixture of these three colors (red, green and blue). By having an amount\nof each one of these three colors, and mixing them together, we can get any other visible color\nthat we want. So every color that we see is perceived as a specific mixture of blues, greens and reds,\nlike 30% of red, plus 20% of green, plus 50% of blue.\n\nWhen these cone cells perceive (or, detect) the colors that are found in the\nlight that is hitting our eyes, these cells produce electrical signals, which are sent to the brain.\nOur brain interprets these electrical signals, and use them to form the image that we are seeing\ninside our head.\n\nBased on what we have discussed here, the bullet points exposed below describes the sequence of events that\ncomposes this very simplified version of how our human eyes work:\n\n1. Light hits our eyes.\n1. The cone cells perceive the colors that are present in this light.\n1. Cone cells produce electrical signals that describes the colors that were perceived in the light.\n1. The electrical signals are sent to the brain.\n1. Brain interprets these signals, and form the image based on the colors identified by these electrical signals.\n\n\n## How digital images work? {#sec-digital-img}\n\nA digital image is a \"digital representation\" of an image that we see with our eyes.\nIn other words, a digital image is a \"digital representation\" of the colors that we see\nand perceive through the light.\nIn the digital world, we have two types of images, which are: vector images and raster images.\nVector images are not described here. So just remember that the content discussed here\n**is related solely to raster images**, and not vector images.\n\nA raster image is a type of digital image that is represented as a 2D (two dimensional) matrix\nof pixels. In other words, every raster image is basically a rectangle of pixels, and each pixel have a particular color.\nSo, a raster image is just a rectangle of pixels, and each of these pixels are displayed in the screen of your computer (or the screen\nof any other device, e.g. laptop, tablet, smartphone, etc.) as a color.\n\n@fig-raster demonstrates this idea. If you take any raster image, and you zoom into it very hard,\nyou will see the actual pixels of the image. JPEG, TIFF and PNG are file formats that are commonly\nused to store raster images.\n\n![Zooming over a raster image to see the pixels. Source: Google Images.](../Figures/imagem-raster.png){#fig-raster}\n\nThe more pixels the image has, the more information and detail we can include in the image.\nThe more accurate, sharp and pretty the image will look. This is why photographic cameras\nusually produce big raster images, with several megapixels of resolution, to include as much detail as possible into the final image.\nAs an example, a digital image with dimensions of 1920 pixels wide and 1080 pixels high, would be a image that\ncontains $1920 \\times 1080 = 2073600$ pixels in total. You could also say that the \"total area\" of the image is\nof 2073600 pixels, although the concept of \"area\" is not really used here in computer graphics.\n\nMost digital images we see in our modern world uses the RGB color model. RGB stands for (red, green and blue).\nSo the color of each pixel in these raster images are usually represented as a mixture of red, green and blue,\njust like in our eyes. That is, the color of each pixel is identified by a set of\nthree different integer values. Each integer value identifies the \"amount\" of each color (red, green and blue).\nFor example, the set `(199, 78, 70)` identifies a color that is more close to red. We have 199 of red, 78 of green,\nand 70 of blue. In contrast, the set `(129, 77, 250)` describes a color that is more close to purple. Et cetera.\n\n\n\n### Images are displayed from top to bottom\n\nThis is not a rule written in stone, but the big majority of digital images are displayed from top\nto bottom and left to right. Most computers screens also follow this pattern. So, the first pixels\nin the image are the ones that are at the top and left corner of the image. You can find a visual representation\nof this logic in @fig-img-display.\n\nAlso notice in @fig-img-display that, because a raster image is essentially a 2D matrix of pixels,\nthe image is organized into rows and columns of pixels. The columns are defined by the horizontal x axis,\nwhile the rows are defined by the vertical y axis.\n\nEach pixel (i.e., the gray rectangles) exposed in @fig-img-display contains a number inside of it.\nThese numbers are the indexes of the pixels. You can notice that the first pixels are in the top and left\ncorner, and also, that the indexes of these pixels \"grow to the sides\", or, in other words, they grow in the direction of the horizontal x axis.\nMost raster images are organized as rows of pixels. Thus, when these digital images are\ndisplayed, the screen display the first row of pixels, then, the second row, then, the third row, etc.\n\n![How the pixels of raster images are displayed.](./../Figures/image-display.png){#fig-img-display}\n\n\n\n\n\n\n### Representing the matrix of pixels in code {#sec-pixel-repr}\n\nOk, we know already that raster images are represented as 2D matrices of pixels.\nBut we do not have a notion of a 2D matrix in Zig. Actually, most low-level languages in general\n(Zig, C, Rust, etc.) do not have such notion.\nSo how can we represent such matrix of pixels in Zig, or any other low-level language?\nThe strategy that most programmers choose in this situation is to just use a normal 1D array to store the values of\nthis 2D matrix. In other words, you just create an normal 1D array, and store all values from both dimensions into this 1D array.\n\nAs an example, suppose we have a very small image of dimensions 4x3.\nSince a raster image is represented as a 2D matrix of pixels, and each pixel\nis represented by 3 \"unsigned 8-bit\" integer values, we have 12 pixels in\ntotal in this image, which are represented by $3 \\times 12 = 36$ integer values.\nTherefore, we need to create an array of 36 `u8` values to store this small image.\n\nThe reason why unsigned 8-bit integer (`u8`) values are used to represent the amounts of each color,\ninstead of any other integer type, is because they take the minimum amount of space as possible, or,\nthe minimum amount of bits as possible. Which helps to reduces the binary size of the image, i.e., the 2D matrix.\nAlso, they convey a good amount of precision and detail about the colors, even though they can represent\na relatively small range (from 0 to 255) of \"color amounts\".\n\nComing back to our initial example of a 4x3 image,\nthe `matrix` object exposed below could be an example of an 1D array that stores\nthe data that represents this 4x3 image.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst matrix = [_]u8{\n    201, 10, 25, 185, 65, 70,\n    65, 120, 110, 65, 120, 117,\n    98, 95, 12, 213, 26, 88,\n    143, 112, 65, 97, 99, 205,\n    234, 105, 56, 43, 44, 216,\n    45, 59, 243, 211, 209, 54,\n};\n```\n:::\n\n\n\n\nThe first three integer values in this array are the color amounts of the first pixel in the image.\nThe next three integers are the colors amounts for the second pixel.\nAnd the sequence goes on in this pattern. Having that in mind, the size of the array that stores\na raster image is usually a multiple of 3. In this case, the array have a size of 36.\n\nI mean, the size of the array is **usually** a multiple of 3, because in specific circumstances,\nit can also be a multiple of 4. This happens when a transparency amount is\nalso included into the raster image. In other words, there are some types of raster images\nthat uses a different color model, which is the RGBA (red, green, blue and alpha)\ncolor model. The \"alpha\" corresponds to an amount of transparency in the pixel.\nSo every pixel in a RGBA image is represented by a red, green, blue and alpha values.\n\nMost raster images uses the standard RGB model, so, for the most part, you will\nsee arrays sizes that are multiples of 3. But some images, especially the ones\nthat are stored in PNG files, might be using the RGBA model, and, therefore, are\nrepresented by an array whose size is a multiple of 4.\n\nIn our case here, the example image of our project (@fig-pascal) is a raster image\nstored in a PNG file, and this specific image is using the RGBA color model. Therefore,\neach pixel in the image is represented by 4 different integer values, and, as consequence,\nto store this image in our Zig code, we need to create an array whose size is a multiple of 4.\n\n\n## The PNG library that we are going to use\n\nLet's begin our project by focusing on writing the necessary Zig code to\nread the data from the PNG file. In other words, we want to read the PNG file exposed\nin @fig-pascal, and parse its data to extract the 2D matrix of pixels that represents the image.\n\nAs we have discussed in @sec-pixel-repr, the image that we are using as example here\nis a PNG file that uses the RGBA color model, and, therefore, each pixel of the image\nis represented by 4 integer values. You can download this image by visiting the `ZigExamples/image_filter`\n[folder at the official repository of this book](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter)[^img-filter-folder].\nYou can also find in this folder the complete source code of this small project that we\nare developing here.\n\n[^img-filter-folder]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter>\n\nThere are some C libraries available that we can use to read and parse PNG files.\nThe most famous and used of all is `libpng`, which is the \"official library\" for reading and writing\nPNG files. Although this library is available on most operating system, it's well known\nfor being complex and hard to use.\n\nThat is why, I'm going to use a more modern alternative here in this project, which is the `libspng` library.\nI choose to use this C library here, because it's much, much simpler to use than `libpng`,\nand it also offers very good performance for all operations. You can checkout the\n[official website of the library](https://libspng.org/)[^libspng]\nto know more about it. You will also find there some documentation that might help you to understand and\nfollow the code examples exposed here.\n\n[^libspng]: <https://libspng.org/>\n\n\nFirst of all, remember to build and install this `libspng` into your system. Because\nif you don't do this step, the `zig` compiler will not be able to find the files and resources of\nthis library in your computer, and link them with the Zig source code that we are writing together here.\nThere is good information about how to build and install the library at the\n[build section of the library documentation](https://libspng.org/docs/build/)[^lib-build].\n\n[^lib-build]: <https://libspng.org/docs/build/>\n\n\n\n\n## Reading the PNG file\n\nIn order to extract the pixel data from the PNG file, we need to read and decode the file.\nA PNG file is just a binary file written in the \"PNG format\". Luckily, the `libspng` library offers\na function called `spng_decode_image()` that does all this heavy work for us.\n\nNow, since `libspng` is a C library, most of the file and I/O operations in this library are made by using\na `FILE` C pointer. Because of that, is probably a better idea to use the `fopen()` C function\nto open our PNG file, instead of using the `openFile()` method that I introduced in @sec-filesystem.\nThat is why I'm importing the `stdio.h` C header in this project, and using the `fopen()` C function to open the file.\n\nIf you look at the snippet below, you can see that we are:\n\n1. opening the PNG file with `fopen()`.\n1. creating the `libspng` context with `spng_ctx_new()`.\n1. using `spng_set_png_file()` to specify the `FILE` object that reads the PNG file that we are going to use.\n\nEvery operation in `libspng` is made through a \"context object\". In our snippet below, this object is `ctx`.\nAlso, to perform an operation over a PNG file, we need to specify which exact PNG file we are referring to.\nThis is the job of `spng_set_png_file()`. We are using this function to specify the file descriptor\nobject that reads the PNG file that we want to use.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n    @cInclude(\"spng.h\");\n});\n\nconst path = \"pedro_pascal.png\";\nconst file_descriptor = c.fopen(path, \"rb\");\nif (file_descriptor == null) {\n    @panic(\"Could not open file!\");\n}\nconst ctx = c.spng_ctx_new(0) orelse unreachable;\n_ = c.spng_set_png_file(\n    ctx, @ptrCast(file_descriptor)\n);\n```\n:::\n\n\n\n\nBefore we continue, is important to emphasize the following: since we have opened the file with `fopen()`,\nwe have to remember to close the file at the end of the program, with `fclose()`.\nIn other words, after we have done everything that we wanted to do with the PNG file\n`pedro_pascal.png`, we need to close this file, by applying `fclose()` over the file descriptor object.\nWe could use also the `defer` keyword to help us in this task, if we want to.\nThis code snippet below demonstrates this step:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (c.fclose(file_descriptor) != 0) {\n    return error.CouldNotCloseFileDescriptor;\n}\n```\n:::\n\n\n\n\n\n\n\n### Reading the image header section\n\nNow, the context object `ctx` is aware of our PNG file `pedro_pascal.png`, because it has access to\na file descriptor object to this file. The first thing that we are going to do is to read the\n\"image header section\" of the PNG file. This \"image header section\" is the section\nof the file that contains some basic information about the PNG file, like, the bit depth of the pixel data\nof the image, the color model used in the file, the dimensions of the image (height and width in number of pixels),\netc.\n\nTo make things easier, I will encapsulate this \"read image header\" operation into a\nnice and small function called `get_image_header()`. All that this function needs to do\nis to call the `spng_get_ihdr()` function. This function from `libspng` is responsible\nfor reading the image header data, and storing it into a C struct named `spng_ihdr`.\nThus, an object of type `spng_ihdr` is a C struct that contains the data from the\nimage header section of the PNG file.\n\nSince this Zig function is receiving a C object (the `libspng` context object) as input, I marked\nthe function argument `ctx` as \"a pointer to the context object\" (`*c.spng_ctx`), following the recommendations\nthat we have discussed in @sec-pass-c-structs.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn get_image_header(ctx: *c.spng_ctx) !c.spng_ihdr {\n    var image_header: c.spng_ihdr = undefined;\n    if (c.spng_get_ihdr(ctx, &image_header) != 0) {\n        return error.CouldNotGetImageHeader;\n    }\n\n    return image_header;\n}\n\nvar image_header = try get_image_header(ctx);\n```\n:::\n\n\n\n\nAlso notice in this function, that I'm checking if the `spng_get_ihdr()` function call have\nreturned or not an integer value that is different than zero. Most functions from the\n`libspng` library return a code status as result, and the code status \"zero\" means\n\"success\". So any code status that is different than zero means that an error\noccurred while running `spng_get_ihdr()`. This is why I'm returning an error value from\nthe function in case the code status returned by the function is different than zero.\n\n\n### Allocating space for the pixel data\n\nBefore we read the pixel data from the PNG file, we need to allocate enough space to hold this data.\nBut in order to allocate such space, we first need to know how much space we need to allocate.\nThe dimensions of the image are obviously needed to calculate the size of this space. But there are\nother elements that also affect this number, such as the color model used in the image, the bit depth, and others.\n\nAnyway, all of this means that calculating the size of the space that we need, is not a simple task.\nThat is why the `libspng` library offers an utility function named\n`spng_decoded_image_size()` to calculate this size for us. Once again, I'm going\nto encapsulate the logic around this C function into a nice and small Zig function\nnamed `calc_output_size()`. You can see below that this function returns a nice\ninteger value as result, informing the size of the space that we need to allocate.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn calc_output_size(ctx: *c.spng_ctx) !u64 {\n    var output_size: u64 = 0;\n    const status = c.spng_decoded_image_size(\n        ctx, c.SPNG_FMT_RGBA8, &output_size\n    );\n    if (status != 0) {\n        return error.CouldNotCalcOutputSize;\n    }\n    return output_size;\n}\n```\n:::\n\n\n\n\n\n\nYou might quest yourself what the value `SPNG_FMT_RGBA8` means. This value is actually an enum\nvalue defined in the `spng.h` C header file. This enum is used to identify a \"PNG format\".\nMore precisely, it identifies a PNG file that uses the RGBA color model and 8 bit depth.\nSo, by providing this enum value as input to the `spng_decoded_image_size()` function,\nwe are saying to this function to calculate the size of the decoded pixel data, by considering\na PNG file that follows this \"RGBA color model with 8 bit depth\" format.\n\nHaving this function, we can use it in conjunction with an allocator object, to allocate an\narray of bytes (`u8` values) that is big enough to store the decoded pixel data of the image.\nNotice that I'm using `@memset()` to initialize the entire array to zero.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst output_size = try calc_output_size(ctx);\nvar buffer = try allocator.alloc(u8, output_size);\n@memset(buffer[0..], 0);\n```\n:::\n\n\n\n\n\n### Decoding the image data\n\nNow that we have the necessary space to store the decoded pixel data of the image,\nwe can start to actually decode and extract this pixel data from the image,\nby using the `spng_decode_image()` C function.\n\nThe `read_data_to_buffer()` Zig function exposed below summarises the necessary\nsteps to read this decoded pixel data, and store it into an input buffer.\nNotice that this function is encapsulating the logic around the `spng_decode_image()` function.\nAlso, we are using the `SPNG_FMT_RGBA8` enum value once again to inform the corresponding function,\nthat the PNG image being decoded, uses the RGBA color model and 8 bit depth.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn read_data_to_buffer(ctx: *c.spng_ctx, buffer: []u8) !void {\n    const status = c.spng_decode_image(\n        ctx,\n        buffer.ptr,\n        buffer.len,\n        c.SPNG_FMT_RGBA8,\n        0\n    );\n\n    if (status != 0) {\n        return error.CouldNotDecodeImage;\n    }\n}\n```\n:::\n\n\n\n\nHaving this function at hand, we can apply it over our context object, and also, over\nthe buffer object that we have allocated in the previous section to hold the decoded pixel data\nof the image:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry read_data_to_buffer(ctx, buffer[0..]);\n```\n:::\n\n\n\n\n\n### Looking at the pixel data\n\nNow that we have the pixel data stored in our \"buffer object\", we can take\na quick look at the bytes. In the example below, we are looking at the first\n12 bytes in the decoded pixel data.\n\nIf you take a close look at these values, you might notice that every 4 bytes\nin the sequence is 255. Which, coincidentally is the maximum possible integer value\nto be represented by a `u8` value. So, if the range from 0 to 255, which is the range\nof integer values that can be represented by an `u8` value, can be represented as a scale from 0% to 100%,\nthese 255 values are essentially 100% in that scale.\n\nIf you recall from @sec-pixel-repr, I have\ndescribed in that section that our `pedro_pascal.png` PNG file uses the RGBA color model,\nwhich adds an alpha (or transparency) byte to each pixel in the image.\nAs consequence, each pixel in the image is represented by 4 bytes. Since we are looking\nhere are the first 12 bytes in the image, it means that we are looking at the data from\nthe first $12 / 4 = 3$ pixels in the image.\n\nSo, based on how these first 12 bytes (or these 3 pixels) look, with these 255 values at every 4 bytes, we can say that is likely\nthat every pixel in the image have alpha (or transparency) setted to 100%. This might not be true,\nbut, is the most likely possibility. Also, if we look at the image itself, which if your recall is\nexposed in @fig-pascal, we can see that the transparency does not change across the image,\nwhich enforces this theory.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry stdout.print(\"{any}\\n\", .{buffer[0..12]});\n```\n:::\n\n\n\n\n```\n{\n    200, 194, 216, 255, 203, 197,\n    219, 255, 206, 200, 223, 255\n}\n```\n\n\nWe can see in the above result that the first pixel in this image have 200 of red, 194 of green, and 216 of blue.\nHow do I know the order in which the colors appears in the sequence? If you have not guessed that yet,\nis because of the acronym RGB. First RED, then GREEN, then BLUE. If we scale these integer values\naccording to our scale of 0% to 100% (0 to 255), we get 78% of red, 76% of green and 85% of blue.\n\n\n\n## Applying the image filter\n\nNow that we have the data of each pixel in the image, we can focus on applying our image\nfilter over these pixels. Remember, our objective here is to apply a grayscale filter over\nthe image. A grayscale filter is a filter that transforms a colored image into a grayscale image.\n\nThere are different formulas and strategies to transform a colored image into a grayscale image.\nBut all of these different strategies normally involve applying some math over the colors of each pixel.\nIn this project, we are going to use the most general formula, which is exposed below.\nThis formula considers $r$ as the red of the pixel, $g$ as the green, $b$ as the blue, and $p'$ as the\nlinear luminance of the pixel.\n\n$$\n    p' = (0.2126 \\times r) + (0.7152 \\times g) + (0.0722 \\times b)\n$${#eq-grayscale}\n\nThis @eq-grayscale is the formula to calculate the linear luminance of a pixel. It's worth noting that this formula\nworks only for images whose pixels are using the sRGB color space, which is the standard color space\nfor the web. Thus, ideally, all images on the web should use this color space. Luckily,\nthis is our case here, i.e., the `pedro_pascal.png` image is using this sRGB color space, and, as consequence,\nwe can use the @eq-grayscale. You can read more about this formula at the Wikipedia page for grayscale [@wiki_grayscale].\n\nThe `apply_image_filter()` function exposed below summarises the necessary steps to\napply @eq-grayscale over the pixels in the image. We just apply this function\nover our buffer object that contains our pixel data, and, as result, the pixel\ndata stored in this buffer object should now represent the grayscale version of our image.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn apply_image_filter(buffer:[]u8) !void {\n    const len = buffer.len;\n    const red_factor: f16 = 0.2126;\n    const green_factor: f16 = 0.7152;\n    const blue_factor: f16 = 0.0722;\n    var index: u64 = 0;\n    while (index < len) : (index += 4) {\n        const rf: f16 = @floatFromInt(buffer[index]);\n        const gf: f16 = @floatFromInt(buffer[index + 1]);\n        const bf: f16 = @floatFromInt(buffer[index + 2]);\n        const y_linear: f16 = (\n            (rf * red_factor) + (gf * green_factor)\n            + (bf * blue_factor)\n        );\n        buffer[index] = @intFromFloat(y_linear);\n        buffer[index + 1] = @intFromFloat(y_linear);\n        buffer[index + 2] = @intFromFloat(y_linear);\n    }\n}\n\ntry apply_image_filter(buffer[0..]);\n```\n:::\n\n\n\n\n\n\n## Saving the grayscale version of the image\n\nSince we have now the grayscale version of our image stored in our buffer object,\nwe need to encode this buffer object back into the \"PNG format\", and save the encoded data into\na new PNG file in our filesystem, so that we can access and see the grayscale version of our image\nthat was produced by our small program.\n\nTo do that, the `libspng` library help us once again by offering an \"encode data to PNG\" type of function,\nwhich is the `spng_encode_image()` function. But in order to \"encode data to PNG\" with `libspng`, we need\nto create a new context object. This new context object must use an \"encoder context\", which\nis identified by the enum value `SPNG_CTX_ENCODER`.\n\nThe `save_png()` function exposed below, summarises all the necessary steps to save the\ngrayscale version of our image into a new PNG file in the filesystem. By default, this\nfunction will save the grayscale image into a file named `pedro_pascal_filter.png` in the CWD.\n\nNotice in this code example that we are using the same image header object (`image_header`) that we have\ncollected previously with the `get_image_header()` function. Remember, this image header object\nis a C struct (`spng_ihdr`) that contains basic information about our PNG file, such as\nthe dimensions of the image, the color model used, etc.\n\nIf we wanted to save a very different image in this new PNG file, e.g. an image\nwith different dimensions, or, an image that uses a different color model, a different bit depth, etc.\nwe would have to create a new image header (`spng_ihdr`) object that describes the properties\nof this new image.\n\nBut we are essentially saving the same image that we have begin with here (the dimensions of\nthe image, the color model, etc. are all still the same). The only difference\nbetween the two images are the colors of the pixels, which are now \"shades of gray\".\nAs consequence, we can safely use the exact same image header data in this new PNG file.\n\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn save_png(image_header: *c.spng_ihdr, buffer: []u8) !void {\n    const path = \"pedro_pascal_filter.png\";\n    const file_descriptor = c.fopen(path.ptr, \"wb\");\n    if (file_descriptor == null) {\n        return error.CouldNotOpenFile;\n    }\n    const ctx = (\n        c.spng_ctx_new(c.SPNG_CTX_ENCODER)\n        orelse unreachable\n    );\n    defer c.spng_ctx_free(ctx);\n    _ = c.spng_set_png_file(ctx, @ptrCast(file_descriptor));\n    _ = c.spng_set_ihdr(ctx, image_header);\n\n    const encode_status = c.spng_encode_image(\n        ctx,\n        buffer.ptr,\n        buffer.len,\n        c.SPNG_FMT_PNG,\n        c.SPNG_ENCODE_FINALIZE\n    );\n    if (encode_status != 0) {\n        return error.CouldNotEncodeImage;\n    }\n    if (c.fclose(file_descriptor) != 0) {\n        return error.CouldNotCloseFileDescriptor;\n    }\n}\n\ntry save_png(&image_header, buffer[0..]);\n```\n:::\n\n\n\n\nAfter we execute this `save_png()` function, we should have a new PNG file\ninside our CWD, named `pedro_pascal_filter.png`. If we open this PNG file,\nwe will see the same image exposed in @fig-pascal-gray.\n\n\n## Building our project\n\nNow that we have written the code, let's discuss how can we build/compile this project.\nTo do that, I'm going to create a `build.zig` file in the root directory of our project,\nand start writing the necessary code to compile the project, using the knowledge\nthat we have acquired from @sec-build-system.\n\n\nWe first create the build target for our executable file, that executes our\nZig code. Let's suppose that all of our Zig code was written into a Zig module\nnamed `image_filter.zig`. The `exe` object exposed in the build script below\ndescribes the build target for our executable file.\n\nSince we have used some C code from the `libspng` library in our Zig code,\nwe need to link our Zig code (which is in the `exe` build target) to both\nthe C Standard Library, and, to the `libspng` library. We do that, by calling\nthe `linkLibC()` and `linkSystemLibrary()` methods from our `exe` build target.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const target = b.standardTargetOptions(.{});\n    const optimize = b.standardOptimizeOption(.{});\n    const exe = b.addExecutable(.{\n        .name = \"image_filter\",\n        .root_source_file = b.path(\"src/image_filter.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n    exe.linkLibC();\n    // Link to libspng library:\n    exe.linkSystemLibrary(\"spng\");\n    b.installArtifact(exe);\n}\n```\n:::\n\n\n\n\nSince we are using the `linkSystemLibrary()` method, it means that the library\nfiles for `libspng` are searched in your system to be linked with the `exe` build target.\nIf you have not yet built and installed the `libspng` library into your system, this\nlinkage step will likely not work. Because it will not find the library files in your system.\n\nSo, just remember to install `libspng` in your system, if you want to build this project.\nHaving this build script above written, we can finally build our project by\nrunning the `zig build` command in the terminal.\n\n```bash\nzig build\n```\n",
-    "supporting": [
-      "13-image-filter_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n# Project 4 - Developing an image filter\n\nIn this chapter we are going to build a new project. The objective of\nthis project is to write a program that applies a filter over an image.\nMore specifically, a \"grayscale filter\", which transforms\nany color image into a grayscale image.\n\nWe are going to use the image displayed in @fig-pascal in this project.\nIn other words, we want to transform this colored image into a grayscale image,\nby using our \"image filter program\" written in Zig.\n\n![A photo of the chilean-american actor Pedro Pascal. Source: Google Images.](../ZigExamples/image_filter/pedro_pascal.png){#fig-pascal}\n\nWe don't need to write a lot of code to build such \"image filter program\". However, we first need\nto understand how digital images work. That is why we begin this chapter\nby explaining the theory behind digital images and how colors are represented in modern computers.\nWe also give a brief explanation about the PNG (Portable Network Graphics) file format, which is the format used\nin the example images.\n\nAt the end of this chapter, we should have a full example of a program that takes the PNG image displayed in @fig-pascal\nas input, and writes a new image to the current working directory that is the grayscale version of this input image.\nThis grayscale version of @fig-pascal is exposed in @fig-pascal-gray.\nYou can find the full source code of this small project at the `ZigExamples/image_filter`\n[folder at the official repository of this book](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter)[^img-filter-folder].\n\n\n![The grayscale version of the photo.](../ZigExamples/image_filter/pedro_pascal_filter.png){#fig-pascal-gray}\n\n\n## How we see things? {#sec-eyes}\n\nIn this section, I want to briefly describe to you how we (humans) actually see things with our own eyes.\nI mean, how our eyes work? If you do have a very basic understanding of how our eyes work, you will understand\nmore easily how digital images are made. Because the techniques behind digital images\nwere developed by taking a lot of inspiration from how our human eyes work.\n\nYou can interpret a human eye as a light sensor, or, a light receptor. The eye receives some amount of light as input,\nand it interprets the colors that are present in this \"amount of light\".\nIf no amount of light hits the eye, then, the eye cannot extract color from it, and as result,\nwe end up seeing nothing, or, more precisely, we see complete blackness.\n\nTherefore, everything depends on light. What we actually see are the colors (blue, red, orange, green, purple, yellow, etc.) that\nare being reflected from the light that is hitting our eyes. **Light is the source of all colors!**\nThis is what Isaac Newton discovered on his famous prism experiment[^newton] in the 1660s.\n\n[^newton]: <https://library.si.edu/exhibition/color-in-a-new-light/science>\n\nInside our eyes, we have a specific type of cell called the \"cone cell\".\nOur eye have three different types, or, three different versions of these \"cone cells\".\nEach type of cone cell is very sensitive to a specific spectrum of the light. More specifically,\nto the spectrums that define the colors red, green and blue.\nSo, in summary, our eyes have specific types of cells that\nare highly sensitive to these three colors (red, green and blue).\n\nThese are the cells responsible for perceiving the color present in the light that hits our eyes.\nAs a result, our eyes perceives color as a mixture of these three colors (red, green and blue). By having an amount\nof each one of these three colors, and mixing them together, we can get any other visible color\nthat we want. So every color that we see is perceived as a specific mixture of blues, greens and reds,\nlike 30% of red, plus 20% of green, plus 50% of blue.\n\nWhen these cone cells perceive (or, detect) the colors that are found in the\nlight that is hitting our eyes, these cells produce electrical signals, which are sent to the brain.\nOur brain interprets these electrical signals, and use them to form the image that we are seeing\ninside our head.\n\nBased on what we have discussed here, the bullet points exposed below describes the sequence of events that\ncomposes this very simplified version of how our human eyes work:\n\n1. Light hits our eyes.\n1. The cone cells perceive the colors that are present in this light.\n1. Cone cells produce electrical signals that describes the colors that were perceived in the light.\n1. The electrical signals are sent to the brain.\n1. Brain interprets these signals, and form the image based on the colors identified by these electrical signals.\n\n\n## How digital images work? {#sec-digital-img}\n\nA digital image is a \"digital representation\" of an image that we see with our eyes.\nIn other words, a digital image is a \"digital representation\" of the colors that we see\nand perceive through the light.\nIn the digital world, we have two types of images, which are: vector images and raster images.\nVector images are not described here. So just remember that the content discussed here\n**is related solely to raster images**, and not vector images.\n\nA raster image is a type of digital image that is represented as a 2D (two dimensional) matrix\nof pixels. In other words, every raster image is basically a rectangle of pixels, and each pixel have a particular color.\nSo, a raster image is just a rectangle of pixels, and each of these pixels are displayed in the screen of your computer (or the screen\nof any other device, e.g. laptop, tablet, smartphone, etc.) as a color.\n\n@fig-raster demonstrates this idea. If you take any raster image, and you zoom into it very hard,\nyou will see the actual pixels of the image. JPEG, TIFF and PNG are file formats that are commonly\nused to store raster images.\n\n![Zooming over a raster image to see the pixels. Source: Google Images.](../Figures/imagem-raster.png){#fig-raster}\n\nThe more pixels the image has, the more information and detail we can include in the image.\nThe more accurate, sharp and pretty the image will look. This is why photographic cameras\nusually produce big raster images, with several megapixels of resolution, to include as much detail as possible into the final image.\nAs an example, a digital image with dimensions of 1920 pixels wide and 1080 pixels high, would be a image that\ncontains $1920 \\times 1080 = 2073600$ pixels in total. You could also say that the \"total area\" of the image is\nof 2073600 pixels, although the concept of \"area\" is not really used here in computer graphics.\n\nMost digital images we see in our modern world uses the RGB color model. RGB stands for (red, green and blue).\nSo the color of each pixel in these raster images are usually represented as a mixture of red, green and blue,\njust like in our eyes. That is, the color of each pixel is identified by a set of\nthree different integer values. Each integer value identifies the \"amount\" of each color (red, green and blue).\nFor example, the set `(199, 78, 70)` identifies a color that is more close to red. We have 199 of red, 78 of green,\nand 70 of blue. In contrast, the set `(129, 77, 250)` describes a color that is more close to purple. Et cetera.\n\n\n\n### Images are displayed from top to bottom\n\nThis is not a rule written in stone, but the big majority of digital images are displayed from top\nto bottom and left to right. Most computers screens also follow this pattern. So, the first pixels\nin the image are the ones that are at the top and left corner of the image. You can find a visual representation\nof this logic in @fig-img-display.\n\nAlso notice in @fig-img-display that, because a raster image is essentially a 2D matrix of pixels,\nthe image is organized into rows and columns of pixels. The columns are defined by the horizontal x axis,\nwhile the rows are defined by the vertical y axis.\n\nEach pixel (i.e., the gray rectangles) exposed in @fig-img-display contains a number inside of it.\nThese numbers are the indexes of the pixels. You can notice that the first pixels are in the top and left\ncorner, and also, that the indexes of these pixels \"grow to the sides\", or, in other words, they grow in the direction of the horizontal x axis.\nMost raster images are organized as rows of pixels. Thus, when these digital images are\ndisplayed, the screen display the first row of pixels, then, the second row, then, the third row, etc.\n\n![How the pixels of raster images are displayed.](./../Figures/image-display.png){#fig-img-display}\n\n\n\n\n\n\n### Representing the matrix of pixels in code {#sec-pixel-repr}\n\nOk, we know already that raster images are represented as 2D matrices of pixels.\nBut we do not have a notion of a 2D matrix in Zig. Actually, most low-level languages in general\n(Zig, C, Rust, etc.) do not have such notion.\nSo how can we represent such matrix of pixels in Zig, or any other low-level language?\nThe strategy that most programmers choose in this situation is to just use a normal 1D array to store the values of\nthis 2D matrix. In other words, you just create an normal 1D array, and store all values from both dimensions into this 1D array.\n\nAs an example, suppose we have a very small image of dimensions 4x3.\nSince a raster image is represented as a 2D matrix of pixels, and each pixel\nis represented by 3 \"unsigned 8-bit\" integer values, we have 12 pixels in\ntotal in this image, which are represented by $3 \\times 12 = 36$ integer values.\nTherefore, we need to create an array of 36 `u8` values to store this small image.\n\nThe reason why unsigned 8-bit integer (`u8`) values are used to represent the amounts of each color,\ninstead of any other integer type, is because they take the minimum amount of space as possible, or,\nthe minimum amount of bits as possible. Which helps to reduces the binary size of the image, i.e., the 2D matrix.\nAlso, they convey a good amount of precision and detail about the colors, even though they can represent\na relatively small range (from 0 to 255) of \"color amounts\".\n\nComing back to our initial example of a 4x3 image,\nthe `matrix` object exposed below could be an example of an 1D array that stores\nthe data that represents this 4x3 image.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst matrix = [_]u8{\n    201, 10, 25, 185, 65, 70,\n    65, 120, 110, 65, 120, 117,\n    98, 95, 12, 213, 26, 88,\n    143, 112, 65, 97, 99, 205,\n    234, 105, 56, 43, 44, 216,\n    45, 59, 243, 211, 209, 54,\n};\n```\n:::\n\n\nThe first three integer values in this array are the color amounts of the first pixel in the image.\nThe next three integers are the colors amounts for the second pixel.\nAnd the sequence goes on in this pattern. Having that in mind, the size of the array that stores\na raster image is usually a multiple of 3. In this case, the array have a size of 36.\n\nI mean, the size of the array is **usually** a multiple of 3, because in specific circumstances,\nit can also be a multiple of 4. This happens when a transparency amount is\nalso included into the raster image. In other words, there are some types of raster images\nthat uses a different color model, which is the RGBA (red, green, blue and alpha)\ncolor model. The \"alpha\" corresponds to an amount of transparency in the pixel.\nSo every pixel in a RGBA image is represented by a red, green, blue and alpha values.\n\nMost raster images uses the standard RGB model, so, for the most part, you will\nsee arrays sizes that are multiples of 3. But some images, especially the ones\nthat are stored in PNG files, might be using the RGBA model, and, therefore, are\nrepresented by an array whose size is a multiple of 4.\n\nIn our case here, the example image of our project (@fig-pascal) is a raster image\nstored in a PNG file, and this specific image is using the RGBA color model. Therefore,\neach pixel in the image is represented by 4 different integer values, and, as consequence,\nto store this image in our Zig code, we need to create an array whose size is a multiple of 4.\n\n\n## The PNG library that we are going to use\n\nLet's begin our project by focusing on writing the necessary Zig code to\nread the data from the PNG file. In other words, we want to read the PNG file exposed\nin @fig-pascal, and parse its data to extract the 2D matrix of pixels that represents the image.\n\nAs we have discussed in @sec-pixel-repr, the image that we are using as example here\nis a PNG file that uses the RGBA color model, and, therefore, each pixel of the image\nis represented by 4 integer values. You can download this image by visiting the `ZigExamples/image_filter`\n[folder at the official repository of this book](https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter)[^img-filter-folder].\nYou can also find in this folder the complete source code of this small project that we\nare developing here.\n\n[^img-filter-folder]: <https://github.com/pedropark99/zig-book/tree/main/ZigExamples/image_filter>\n\nThere are some C libraries available that we can use to read and parse PNG files.\nThe most famous and used of all is `libpng`, which is the \"official library\" for reading and writing\nPNG files. Although this library is available on most operating system, it's well known\nfor being complex and hard to use.\n\nThat is why, I'm going to use a more modern alternative here in this project, which is the `libspng` library.\nI choose to use this C library here, because it's much, much simpler to use than `libpng`,\nand it also offers very good performance for all operations. You can checkout the\n[official website of the library](https://libspng.org/)[^libspng]\nto know more about it. You will also find there some documentation that might help you to understand and\nfollow the code examples exposed here.\n\n[^libspng]: <https://libspng.org/>\n\n\nFirst of all, remember to build and install this `libspng` into your system. Because\nif you don't do this step, the `zig` compiler will not be able to find the files and resources of\nthis library in your computer, and link them with the Zig source code that we are writing together here.\nThere is good information about how to build and install the library at the\n[build section of the library documentation](https://libspng.org/docs/build/)[^lib-build].\n\n[^lib-build]: <https://libspng.org/docs/build/>\n\n\n\n\n## Reading the PNG file\n\nIn order to extract the pixel data from the PNG file, we need to read and decode the file.\nA PNG file is just a binary file written in the \"PNG format\". Luckily, the `libspng` library offers\na function called `spng_decode_image()` that does all this heavy work for us.\n\nNow, since `libspng` is a C library, most of the file and I/O operations in this library are made by using\na `FILE` C pointer. Because of that, is probably a better idea to use the `fopen()` C function\nto open our PNG file, instead of using the `openFile()` method that I introduced in @sec-filesystem.\nThat is why I'm importing the `stdio.h` C header in this project, and using the `fopen()` C function to open the file.\n\nIf you look at the snippet below, you can see that we are:\n\n1. opening the PNG file with `fopen()`.\n1. creating the `libspng` context with `spng_ctx_new()`.\n1. using `spng_set_png_file()` to specify the `FILE` object that reads the PNG file that we are going to use.\n\nEvery operation in `libspng` is made through a \"context object\". In our snippet below, this object is `ctx`.\nAlso, to perform an operation over a PNG file, we need to specify which exact PNG file we are referring to.\nThis is the job of `spng_set_png_file()`. We are using this function to specify the file descriptor\nobject that reads the PNG file that we want to use.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n    @cInclude(\"spng.h\");\n});\n\nconst path = \"pedro_pascal.png\";\nconst file_descriptor = c.fopen(path, \"rb\");\nif (file_descriptor == null) {\n    @panic(\"Could not open file!\");\n}\nconst ctx = c.spng_ctx_new(0) orelse unreachable;\n_ = c.spng_set_png_file(\n    ctx, @ptrCast(file_descriptor)\n);\n```\n:::\n\n\nBefore we continue, is important to emphasize the following: since we have opened the file with `fopen()`,\nwe have to remember to close the file at the end of the program, with `fclose()`.\nIn other words, after we have done everything that we wanted to do with the PNG file\n`pedro_pascal.png`, we need to close this file, by applying `fclose()` over the file descriptor object.\nWe could use also the `defer` keyword to help us in this task, if we want to.\nThis code snippet below demonstrates this step:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nif (c.fclose(file_descriptor) != 0) {\n    return error.CouldNotCloseFileDescriptor;\n}\n```\n:::\n\n\n\n\n\n### Reading the image header section\n\nNow, the context object `ctx` is aware of our PNG file `pedro_pascal.png`, because it has access to\na file descriptor object to this file. The first thing that we are going to do is to read the\n\"image header section\" of the PNG file. This \"image header section\" is the section\nof the file that contains some basic information about the PNG file, like, the bit depth of the pixel data\nof the image, the color model used in the file, the dimensions of the image (height and width in number of pixels),\netc.\n\nTo make things easier, I will encapsulate this \"read image header\" operation into a\nnice and small function called `get_image_header()`. All that this function needs to do\nis to call the `spng_get_ihdr()` function. This function from `libspng` is responsible\nfor reading the image header data, and storing it into a C struct named `spng_ihdr`.\nThus, an object of type `spng_ihdr` is a C struct that contains the data from the\nimage header section of the PNG file.\n\nSince this Zig function is receiving a C object (the `libspng` context object) as input, I marked\nthe function argument `ctx` as \"a pointer to the context object\" (`*c.spng_ctx`), following the recommendations\nthat we have discussed in @sec-pass-c-structs.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn get_image_header(ctx: *c.spng_ctx) !c.spng_ihdr {\n    var image_header: c.spng_ihdr = undefined;\n    if (c.spng_get_ihdr(ctx, &image_header) != 0) {\n        return error.CouldNotGetImageHeader;\n    }\n\n    return image_header;\n}\n\nvar image_header = try get_image_header(ctx);\n```\n:::\n\n\nAlso notice in this function, that I'm checking if the `spng_get_ihdr()` function call have\nreturned or not an integer value that is different than zero. Most functions from the\n`libspng` library return a code status as result, and the code status \"zero\" means\n\"success\". So any code status that is different than zero means that an error\noccurred while running `spng_get_ihdr()`. This is why I'm returning an error value from\nthe function in case the code status returned by the function is different than zero.\n\n\n### Allocating space for the pixel data\n\nBefore we read the pixel data from the PNG file, we need to allocate enough space to hold this data.\nBut in order to allocate such space, we first need to know how much space we need to allocate.\nThe dimensions of the image are obviously needed to calculate the size of this space. But there are\nother elements that also affect this number, such as the color model used in the image, the bit depth, and others.\n\nAnyway, all of this means that calculating the size of the space that we need, is not a simple task.\nThat is why the `libspng` library offers an utility function named\n`spng_decoded_image_size()` to calculate this size for us. Once again, I'm going\nto encapsulate the logic around this C function into a nice and small Zig function\nnamed `calc_output_size()`. You can see below that this function returns a nice\ninteger value as result, informing the size of the space that we need to allocate.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn calc_output_size(ctx: *c.spng_ctx) !u64 {\n    var output_size: u64 = 0;\n    const status = c.spng_decoded_image_size(\n        ctx, c.SPNG_FMT_RGBA8, &output_size\n    );\n    if (status != 0) {\n        return error.CouldNotCalcOutputSize;\n    }\n    return output_size;\n}\n```\n:::\n\n\n\n\nYou might quest yourself what the value `SPNG_FMT_RGBA8` means. This value is actually an enum\nvalue defined in the `spng.h` C header file. This enum is used to identify a \"PNG format\".\nMore precisely, it identifies a PNG file that uses the RGBA color model and 8 bit depth.\nSo, by providing this enum value as input to the `spng_decoded_image_size()` function,\nwe are saying to this function to calculate the size of the decoded pixel data, by considering\na PNG file that follows this \"RGBA color model with 8 bit depth\" format.\n\nHaving this function, we can use it in conjunction with an allocator object, to allocate an\narray of bytes (`u8` values) that is big enough to store the decoded pixel data of the image.\nNotice that I'm using `@memset()` to initialize the entire array to zero.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst output_size = try calc_output_size(ctx);\nvar buffer = try allocator.alloc(u8, output_size);\n@memset(buffer[0..], 0);\n```\n:::\n\n\n\n### Decoding the image data\n\nNow that we have the necessary space to store the decoded pixel data of the image,\nwe can start to actually decode and extract this pixel data from the image,\nby using the `spng_decode_image()` C function.\n\nThe `read_data_to_buffer()` Zig function exposed below summarises the necessary\nsteps to read this decoded pixel data, and store it into an input buffer.\nNotice that this function is encapsulating the logic around the `spng_decode_image()` function.\nAlso, we are using the `SPNG_FMT_RGBA8` enum value once again to inform the corresponding function,\nthat the PNG image being decoded, uses the RGBA color model and 8 bit depth.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn read_data_to_buffer(ctx: *c.spng_ctx, buffer: []u8) !void {\n    const status = c.spng_decode_image(\n        ctx,\n        buffer.ptr,\n        buffer.len,\n        c.SPNG_FMT_RGBA8,\n        0\n    );\n\n    if (status != 0) {\n        return error.CouldNotDecodeImage;\n    }\n}\n```\n:::\n\n\nHaving this function at hand, we can apply it over our context object, and also, over\nthe buffer object that we have allocated in the previous section to hold the decoded pixel data\nof the image:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry read_data_to_buffer(ctx, buffer[0..]);\n```\n:::\n\n\n\n### Looking at the pixel data\n\nNow that we have the pixel data stored in our \"buffer object\", we can take\na quick look at the bytes. In the example below, we are looking at the first\n12 bytes in the decoded pixel data.\n\nIf you take a close look at these values, you might notice that every 4 bytes\nin the sequence is 255. Which, coincidentally is the maximum possible integer value\nto be represented by a `u8` value. So, if the range from 0 to 255, which is the range\nof integer values that can be represented by an `u8` value, can be represented as a scale from 0% to 100%,\nthese 255 values are essentially 100% in that scale.\n\nIf you recall from @sec-pixel-repr, I have\ndescribed in that section that our `pedro_pascal.png` PNG file uses the RGBA color model,\nwhich adds an alpha (or transparency) byte to each pixel in the image.\nAs consequence, each pixel in the image is represented by 4 bytes. Since we are looking\nhere are the first 12 bytes in the image, it means that we are looking at the data from\nthe first $12 / 4 = 3$ pixels in the image.\n\nSo, based on how these first 12 bytes (or these 3 pixels) look, with these 255 values at every 4 bytes, we can say that is likely\nthat every pixel in the image have alpha (or transparency) setted to 100%. This might not be true,\nbut, is the most likely possibility. Also, if we look at the image itself, which if your recall is\nexposed in @fig-pascal, we can see that the transparency does not change across the image,\nwhich enforces this theory.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\ntry stdout.print(\"{any}\\n\", .{buffer[0..12]});\n```\n:::\n\n\n```\n{\n    200, 194, 216, 255, 203, 197,\n    219, 255, 206, 200, 223, 255\n}\n```\n\n\nWe can see in the above result that the first pixel in this image have 200 of red, 194 of green, and 216 of blue.\nHow do I know the order in which the colors appears in the sequence? If you have not guessed that yet,\nis because of the acronym RGB. First RED, then GREEN, then BLUE. If we scale these integer values\naccording to our scale of 0% to 100% (0 to 255), we get 78% of red, 76% of green and 85% of blue.\n\n\n\n## Applying the image filter\n\nNow that we have the data of each pixel in the image, we can focus on applying our image\nfilter over these pixels. Remember, our objective here is to apply a grayscale filter over\nthe image. A grayscale filter is a filter that transforms a colored image into a grayscale image.\n\nThere are different formulas and strategies to transform a colored image into a grayscale image.\nBut all of these different strategies normally involve applying some math over the colors of each pixel.\nIn this project, we are going to use the most general formula, which is exposed below.\nThis formula considers $r$ as the red of the pixel, $g$ as the green, $b$ as the blue, and $p'$ as the\nlinear luminance of the pixel.\n\n$$\n    p' = (0.2126 \\times r) + (0.7152 \\times g) + (0.0722 \\times b)\n$${#eq-grayscale}\n\nThis @eq-grayscale is the formula to calculate the linear luminance of a pixel. It's worth noting that this formula\nworks only for images whose pixels are using the sRGB color space, which is the standard color space\nfor the web. Thus, ideally, all images on the web should use this color space. Luckily,\nthis is our case here, i.e., the `pedro_pascal.png` image is using this sRGB color space, and, as consequence,\nwe can use the @eq-grayscale. You can read more about this formula at the Wikipedia page for grayscale [@wiki_grayscale].\n\nThe `apply_image_filter()` function exposed below summarises the necessary steps to\napply @eq-grayscale over the pixels in the image. We just apply this function\nover our buffer object that contains our pixel data, and, as result, the pixel\ndata stored in this buffer object should now represent the grayscale version of our image.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn apply_image_filter(buffer:[]u8) !void {\n    const len = buffer.len;\n    const red_factor: f16 = 0.2126;\n    const green_factor: f16 = 0.7152;\n    const blue_factor: f16 = 0.0722;\n    var index: u64 = 0;\n    while (index < len) : (index += 4) {\n        const rf: f16 = @floatFromInt(buffer[index]);\n        const gf: f16 = @floatFromInt(buffer[index + 1]);\n        const bf: f16 = @floatFromInt(buffer[index + 2]);\n        const y_linear: f16 = (\n            (rf * red_factor) + (gf * green_factor)\n            + (bf * blue_factor)\n        );\n        buffer[index] = @intFromFloat(y_linear);\n        buffer[index + 1] = @intFromFloat(y_linear);\n        buffer[index + 2] = @intFromFloat(y_linear);\n    }\n}\n\ntry apply_image_filter(buffer[0..]);\n```\n:::\n\n\n\n\n## Saving the grayscale version of the image\n\nSince we have now the grayscale version of our image stored in our buffer object,\nwe need to encode this buffer object back into the \"PNG format\", and save the encoded data into\na new PNG file in our filesystem, so that we can access and see the grayscale version of our image\nthat was produced by our small program.\n\nTo do that, the `libspng` library help us once again by offering an \"encode data to PNG\" type of function,\nwhich is the `spng_encode_image()` function. But in order to \"encode data to PNG\" with `libspng`, we need\nto create a new context object. This new context object must use an \"encoder context\", which\nis identified by the enum value `SPNG_CTX_ENCODER`.\n\nThe `save_png()` function exposed below, summarises all the necessary steps to save the\ngrayscale version of our image into a new PNG file in the filesystem. By default, this\nfunction will save the grayscale image into a file named `pedro_pascal_filter.png` in the CWD.\n\nNotice in this code example that we are using the same image header object (`image_header`) that we have\ncollected previously with the `get_image_header()` function. Remember, this image header object\nis a C struct (`spng_ihdr`) that contains basic information about our PNG file, such as\nthe dimensions of the image, the color model used, etc.\n\nIf we wanted to save a very different image in this new PNG file, e.g. an image\nwith different dimensions, or, an image that uses a different color model, a different bit depth, etc.\nwe would have to create a new image header (`spng_ihdr`) object that describes the properties\nof this new image.\n\nBut we are essentially saving the same image that we have begin with here (the dimensions of\nthe image, the color model, etc. are all still the same). The only difference\nbetween the two images are the colors of the pixels, which are now \"shades of gray\".\nAs consequence, we can safely use the exact same image header data in this new PNG file.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn save_png(image_header: *c.spng_ihdr, buffer: []u8) !void {\n    const path = \"pedro_pascal_filter.png\";\n    const file_descriptor = c.fopen(path.ptr, \"wb\");\n    if (file_descriptor == null) {\n        return error.CouldNotOpenFile;\n    }\n    const ctx = (\n        c.spng_ctx_new(c.SPNG_CTX_ENCODER)\n        orelse unreachable\n    );\n    defer c.spng_ctx_free(ctx);\n    _ = c.spng_set_png_file(ctx, @ptrCast(file_descriptor));\n    _ = c.spng_set_ihdr(ctx, image_header);\n\n    const encode_status = c.spng_encode_image(\n        ctx,\n        buffer.ptr,\n        buffer.len,\n        c.SPNG_FMT_PNG,\n        c.SPNG_ENCODE_FINALIZE\n    );\n    if (encode_status != 0) {\n        return error.CouldNotEncodeImage;\n    }\n    if (c.fclose(file_descriptor) != 0) {\n        return error.CouldNotCloseFileDescriptor;\n    }\n}\n\ntry save_png(&image_header, buffer[0..]);\n```\n:::\n\n\nAfter we execute this `save_png()` function, we should have a new PNG file\ninside our CWD, named `pedro_pascal_filter.png`. If we open this PNG file,\nwe will see the same image exposed in @fig-pascal-gray.\n\n\n## Building our project\n\nNow that we have written the code, let's discuss how can we build/compile this project.\nTo do that, I'm going to create a `build.zig` file in the root directory of our project,\nand start writing the necessary code to compile the project, using the knowledge\nthat we have acquired from @sec-build-system.\n\n\nWe first create the build target for our executable file, that executes our\nZig code. Let's suppose that all of our Zig code was written into a Zig module\nnamed `image_filter.zig`. The `exe` object exposed in the build script below\ndescribes the build target for our executable file.\n\nSince we have used some C code from the `libspng` library in our Zig code,\nwe need to link our Zig code (which is in the `exe` build target) to both\nthe C Standard Library, and, to the `libspng` library. We do that, by calling\nthe `linkLibC()` and `linkSystemLibrary()` methods from our `exe` build target.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\npub fn build(b: *std.Build) void {\n    const target = b.standardTargetOptions(.{});\n    const optimize = b.standardOptimizeOption(.{});\n    const exe = b.addExecutable(.{\n        .name = \"image_filter\",\n        .root_source_file = b.path(\"src/image_filter.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n    exe.linkLibC();\n    // Link to libspng library:\n    exe.linkSystemLibrary(\"spng\");\n    b.installArtifact(exe);\n}\n```\n:::\n\n\nSince we are using the `linkSystemLibrary()` method, it means that the library\nfiles for `libspng` are searched in your system to be linked with the `exe` build target.\nIf you have not yet built and installed the `libspng` library into your system, this\nlinkage step will likely not work. Because it will not find the library files in your system.\n\nSo, just remember to install `libspng` in your system, if you want to build this project.\nHaving this build script above written, we can finally build our project by\nrunning the `zig build` command in the terminal.\n\n```bash\nzig build\n```\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/14-threads/execute-results/epub.json b/_freeze/Chapters/14-threads/execute-results/epub.json
deleted file mode 100644
index 430a96bc..00000000
--- a/_freeze/Chapters/14-threads/execute-results/epub.json
+++ /dev/null
@@ -1,21 +0,0 @@
-{
-  "hash": "5330e6bae2255d3ad46893b0641f0683",
-  "result": {
-    "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Introducing threads and parallelism in Zig {#sec-thread}\n\nThreads are available in Zig through the `Thread` struct from the Zig Standard Library.\nThis struct represents a kernel thread, and it follows a POSIX Thread pattern,\nmeaning that, it works similarly to a thread from the `pthread` C library, which is usually available on any distribution\nof the GNU C Compiler (`gcc`). If you are not familiar with threads, I will give you some theory behind it first, shall we?\n\n\n## What are threads? {#sec-what-thread}\n\nA thread is basically a separate context of execution.\nWe use threads to introduce parallelism into our program,\nwhich in most cases, makes the program run faster, because we have multiple tasks\nbeing performed at the same time, parallel to each other.\n\nPrograms are normally single-threaded by default. Which means that each program\nusually runs on a single thread, or, a single context of execution. When we have only one thread running, we have no\nparallelism. And when we don't have parallelism, the commands are executed sequentially, that is,\nonly one command is executed at a time, one after another. By creating multiple threads inside our program,\nwe start to execute multiple commands at the same time.\n\nPrograms that create multiple threads are very common in the wild. Because many different types\nof applications are well suited for parallelism. Good examples are video and photo-editing applications\n(e.g. Adobe Photoshop or DaVinci Resolve), games (e.g. The Witcher 3), and also web browsers\n(e.g. Google Chrome, Firefox, Microsoft Edge, etc).\nFor example, in web browsers, threads are normally used to implement tabs.\nThe tabs in a web browsers usually run as separate threads in the main process of\nthe web browser. That is, each new tab that you open in your web browser\nusually runs on a separate thread of execution.\n\nBy running each tab in a separate thread, we allow all open tabs in the browser to run at the same time,\nand independently from each other. For example, you might have YouTube or Spotify currently open in\na tab, and you are listening to some podcast in that tab while at the same time\nworking in another tab, writing an essay on Google Docs. Even if you are not looking\ninto the YouTube tab, you can still hear the podcast only because this YouTube tab is running in parallel\nwith the other tab where Google Docs is running.\n\nWithout threads, the other alternative would be to run each tab as a completely separate\nprocess in your computer. But that would be a bad choice because just a few tabs would already consume\ntoo much power and resources from your computer. In other words, it's very expensive to create a completely new process,\ncompared to creating a new thread of execution. Also, the chances of you experiencing lag and overhead\nwhile using the browser would be significant. Threads are faster to create, and they also consume\nmuch, much less resources from the computer, especially because they share some resources\nwith the main process.\n\nTherefore, it's the use of threads in modern web browsers that allow you to hear the podcast\nat the same time while you are writing something on Google Docs.\nWithout threads, a web browser would probably be limited to just one single tab.\n\nThreads are also well-suited for anything that involves serving requests or orders.\nBecause serving a request takes time, and usually involves a lot of \"waiting time\".\nIn other words, we spend a lot of time in idle, waiting for something to complete.\nFor example, consider a restaurant. Serving orders in a restaurant usually involves\nthe following steps:\n\n1. receive order from the client.\n1. pass the order to the kitchen, and wait for the food to be cooked.\n1. start cooking the food in the kitchen.\n1. when the food is fully cooked deliver this food to the client.\n\nIf you think about the bullet points above, you will notice that one big moment of waiting time\nis present in this whole process, which is while the food is being cooked\ninside the kitchen. While the food is being prepped, both the waiter and the client\nthemselves are waiting for the food to be ready and delivered.\n\nIf we write a program to represent this restaurant, more specifically, a single-threaded program, then\nthis program would be very inefficient. Because the program would stay in idle, waiting for a considerable amount\nof time on the \"check if food is ready\" step. Consider the code snippet exposed below that could\npotentially represent such program.\n\nThe problem with this program is the while loop. This program will spend a lot of time\nwaiting on the while loop, doing nothing more than just checking if the food is ready.\nThis is a waste of time. Instead of waiting for something to happen, the waiter\ncould just send the order to the kitchen, and just move on, and continue with receiving\nmore orders from other clients, and sending more orders to the kitchen, instead\nof doing nothing and waiting for the food to be ready.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst order = Order.init(\"Pizza Margherita\", n = 1);\nconst waiter = Waiter.init();\nwaiter.receive_order(order);\nwaiter.ask_kitchen_to_cook();\nvar food_not_ready = true;\nwhile (food_not_ready) {\n    food_not_ready = waiter.is_food_ready();\n}\nconst food = waiter.get_food_from_kitchen();\nwaiter.send_food_to_client(food);\n```\n:::\n\n\n\nThis is why threads would be a great fit for this program. We could use threads\nto free the waiters from their \"waiting duties\", so they can go on with their\nother tasks, and receive more orders. Take a look at the next example, where I have re-written the above\nprogram into a different program that uses threads to cook and deliver the orders.\n\nYou can see in this program that when a waiter receives a new order\nfrom a client, this waiter executes the `send_order()` function.\nThe only thing that this function does is to create a new thread\nand detaches it. Since creating a thread is a very fast operation,\nthis `send_order()` function returns almost immediately,\nso the waiter spends almost no time worrying about the order, and just\nmove on and tries to get the next order from the clients.\n\nInside the new thread created, the order gets cooked by a chef, and when the\nfood is ready, it's delivered to the client's table.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn cook_and_deliver_order(order: *Order) void {\n    const chef = Chef.init();\n    const food = chef.cook(order.*);\n    chef.deliver_food(food);\n}\nfn send_order(order: Order) void {\n    const cook_thread = Thread.spawn(\n        .{}, cook_and_deliver_order, .{&order}\n    );\n    cook_thread.detach();\n}\n\nconst waiter = Waiter.init();\nwhile (true) {\n    const order = waiter.get_new_order();\n    if (order) {\n        send_order(order);\n    }\n}\n```\n:::\n\n\n\n\n\n## Threads versus processes\n\nWhen we run a program, this program is executed as a *process* in the operating system.\nThis is a one to one relationship, each program or application that you execute\nis a separate process in the operating system. But each program, or each process,\ncan create and contain multiple threads inside of it. Therefore,\nprocesses and threads have a one to many relationship.\n\nThis also means that every thread that we create is always associated with a particular process in our computer.\nIn other words, a thread is always a subset (or a children) of an existing process.\nAll threads share some of the resources associated with the process from which they were created.\nAnd because threads share resources with the process, they are very good for making communication\nbetween tasks easier.\n\nFor example, suppose that you were developing a big and complex application\nthat would be much simpler if you could split it in two, and make these two separate pieces talk\nwith each other. Some programmers opt to effectively write these two pieces of the codebase as two\ncompletely separate programs, and then, they use IPC (*inter-process communication*) to make these\ntwo separate programs/processes talk to each other, and make them work together.\n\nHowever, some programmers find IPC hard to deal with, and, as consequence,\nthey prefer to write one piece of the codebase as the \"main part of the program\",\nor, as the part of the code that runs as the process in the operating system,\nwhile the other piece of the codebase is written as a task to be executed in\na new thread. A process and a thread can easily comunicate with each other\nthrough both control flow, and also, through data, because they share and have\naccess to the same standard file descriptors (`stdout`, `stdin`, `stderr`), and also to the\nsame memory space on the heap and global data section.\n\n\nIn more details, each thread that you create have a separate stack frame reserved just for that thread,\nwhich essentially means that each local object that you create inside this thread, is local to that\nthread, i.e., the other threads cannot see this local object. Unless this object that you have created\nis an object that lives on the heap. In other words, if the memory associated with this object\nis on the heap, then, the other threads can potentially access this object.\n\nTherefore, objects that are stored in the stack are local to the thread where they were created.\nBut objects that are stored on the heap are potentially accessible to other threads. All of this means that,\neach thread has its own separate stack frame, but, at the same time, all threads share\nthe same heap, the same standard file descriptors (which means that they share the same `stdout`, `stdin`, `stderr`),\nand the same global data section in the program.\n\n\n\n## Creating a thread\n\nWe create new threads in Zig by first importing the `Thread` struct into\nour current Zig module and then calling the `spawn()` method of this struct,\nwhich creates (or \"spawns\") a new thread of execution from our current process.\nThis method has three arguments, which are, respectively:\n\n1. a `SpawnConfig` object, which contains configurations for the spawn process.\n1. the name of the function that is going to be executed (or that is going to be \"called\") inside this new thread.\n1. a list of arguments (or inputs) to be passed to the function provided in the second argument.\n\nWith these three arguments, you can control how the thread gets created, and also, specify which\nwork (or \"tasks\") will be performed inside this new thread. A thread is just a separate context of execution,\nand we usually create new threads in our code because we want to perform some work inside this\nnew context of execution. And we specify which exact work, or which exact steps that are going to be\nperformed inside this context by providing the name of a function as the second argument of the `spawn()` method.\n\nThus, when this new thread gets created, this function that you provided as input to the `spawn()`\nmethod gets called, or gets executed inside this new thread. You can control the\narguments, or the inputs that are passed to this function when it gets called by providing\na list of arguments (or a list of inputs) in the third argument of the `spawn()` method.\nThese arguments are passed to the function in the same order that they are\nprovided to `spawn()`.\n\nFurthermore, the `SpawnConfig` is a struct object with only two possible fields, or, two possible members, that you\ncan set to tailor the spawn behaviour. These fields are:\n\n- `stack_size`: you can provide a `usize` value to specify the size (in bytes) of the thread's stack frame. By default, this value is: $16 \\times 1024 \\times 1024$.\n- `allocator`: you can provide an allocator object to be used when allocating memory for the thread.\n\nTo use one of these two fields (or \"configs\"), you just have to create a new object of type `SpawnConfig`,\nand provide this object as input to the `spawn()` method. But, if you are not interested in using\none of these configs, and you are ok with using just the defaults, you can just provide an anonymous\nstruct literal (`.{}`) in place of this `SpawnConfig` argument.\n\nAs our first, and very simple example, consider the code exposed below.\nInside the same program, you can create multiple threads of execution if you want to.\nBut, in this first example, we are creating just a single thread of execution, because\nwe call `spawn()` only once.\n\nAlso, notice in this example that we are executing the function `do_some_work()`\ninside the new thread. Since this function receives no inputs, because it has\nno arguments, we have passed an empty list in this instance, or more precisely,\nan empty, anonymous struct (`.{}`) in the third argument of `spawn()`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Thread = std.Thread;\nfn do_some_work() !void {\n    _ = try stdout.write(\"Starting the work.\\n\");\n    std.time.sleep(100 * std.time.ns_per_ms);\n    _ = try stdout.write(\"Finishing the work.\\n\");\n}\n\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, do_some_work, .{});\n    thread.join();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nStarting the work.Finishing the work.\n```\n\n\n:::\n:::\n\n\n\nNotice the use of `try` when calling the `spawn()` method. This means\nthat this method can return an error in some circumstances. One circumstance\nin particular is when you attempt to create a new thread, when you have already\ncreated too much (i.e., you have exceeded the quota of concurrent threads in your system).\n\nBut, if the new thread is successfully created, the `spawn()` method returns a handler\nobject (which is just an object of type `Thread`) to this new thread. You can use\nthis handler object to effectively control all aspects of the thread.\n\nWhen the thread gets created, the function that you provided as input to `spawn()`\ngets invoked (i.e., gets called) to start the execution on this new thread.\nIn other words, every time you call `spawn()`, not only is a new thread created,\nbut the \"start work button\" of this thread is also automatically pressed.\nSo the work being performed in this thread starts as soon as the thread is created.\nThis is similar to how `pthread_create()` from the `pthreads` library in C works,\nwhich also starts the execution as soon as the thread is created.\n\n\n## Returning from a thread\n\nWe have learned in the previous section that the execution of the thread starts as soon as\nthe thread is created. Now, we will learn how to \"join\" or \"detach\" a thread in Zig.\n\"Join\" and \"detach\" are operations that control how the thread returns to\nthe main thread, or to the main process in our program.\n\nWe perform these operations by using the methods `join()` and `detach()` from the thread handler object.\nEvery thread that you create can be marked as either *joinable* or *detached* [@linux_pthread_create].\nYou can turn a thread into a *detached* thread by calling the `detach()` method\nfrom the thread handler object. But if you call the `join()` method instead, then this thread\nbecomes a *joinable* thread.\n\nA thread cannot be both *joinable* and *detached*. Which in general means\nthat you cannot call both `join()` and `detach()` on the same thread.\nBut a thread must be one of the two, meaning that, you should always call\neither `join()` or `detach()` over a thread. If you don't call\none of these two methods over your thread, you introduce undefined behaviour into your program,\nwhich is described in @sec-not-call-join-detach.\n\nNow, let's describe what each of these two methods do to your thread.\n\n\n### Joining a thread\n\nWhen you join a thread, you are essentially saying: \"Hey! Could you please wait for the thread to finish,\nbefore you continue with your execution?\". For example, if we come back to our first and simplest example\nof a thread in Zig, we created a single thread inside the `main()` function of our program\nand just called `join()` on this thread at the end. This section of the code example is reproduced below.\n\nBecause we are joining this new thread inside the `main()`'s scope, it means that the\nexecution of the `main()` function is temporarily stopped, to wait for the execution of the thread\nto finish. That is, the execution of `main()` stops temporarily at the line where `join()` gets called,\nand it will continue only after the thread has finished its tasks.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, do_some_work, .{});\n    thread.join();\n}\n```\n:::\n\n\n\nBecause we have joined this new thread inside the `main()` scope, we have a\nguarantee that this new thread will finish before the end of the execution of `main()`.\nBecause it's guaranteed that `main()` will wait for the thread to finish its tasks.\n\nIn the example above, there are no more expressions after the `join()` call. We just have the end\nof the `main()`'s scope, and, therefore, the execution of our program just ends after the thread finishes its tasks,\nsince there is nothing more to do. But what if we had more stuff to do after the join call?\n\nTo demonstrate this other possibility, consider the next example exposed\nbelow. Here, we create a `print_id()` function, that just receives an id\nas input, and prints it to `stdout`. In this example, we are creating two\nnew threads, one after another. Then, we join the first thread, then,\nwe wait for two whole seconds, then, at last, we join the second thread.\n\nThe idea behind this example is that the last `join()` call is executed\nonly after the first thread finishes its task (i.e., the first `join()` call),\nand the two-second delay. If you compile and run this\nexample, you will notice that most messages are quickly printed to `stdout`,\ni.e., they appear almost instantly on your screen.\nHowever, the last message (\"Joining thread 2\") takes around 2 seconds to appear\non the screen.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_id(id: *const u8) !void {\n    try stdout.print(\"Thread ID: {d}\\n\", .{id.*});\n}\n\npub fn main() !void {\n    const id1: u8 = 1;\n    const id2: u8 = 2;\n    const thread1 = try Thread.spawn(.{}, print_id, .{&id1});\n    const thread2 = try Thread.spawn(.{}, print_id, .{&id2});\n\n    _ = try stdout.write(\"Joining thread 1\\n\");\n    thread1.join();\n    std.time.sleep(2 * std.time.ns_per_s);\n    _ = try stdout.write(\"Joining thread 2\\n\");\n    thread2.join();\n}\n```\n:::\n\n\n\n```\nThread ID: Joining thread 1\n1\nThread ID: 2\nJoining thread 2\n```\n\nThis demonstrates that both threads finish their work (i.e., printing the IDs)\nvery fast, before the two seconds of delay end. Because of that, the last `join()` call\nreturns pretty much instantly. Because when this last `join()` call happens, the second\nthread has already finished its task.\n\nNow, if you compile and run this example, you will also notice that, in some cases,\nthe messages intertwine with each other. In other words, you might see\nthe message \"Joining thread 1\" inserted in the middle of the message \"Thread 1\",\nor vice-versa. This happens because:\n\n- the threads are executing basically at the same time as the main process of the program (i.e., the `main()` function).\n- the threads share the same `stdout` from the main process of the program, which means that the messages that the threads produce are sent to exact same place as the messages produced by the main process.\n\nBoth of these points were described previously in @sec-what-thread.\nSo the messages might get intertwined because they are being produced and\nsent to the same `stdout` roughly at the same time.\nAnyway, when you call `join()` over a thread, the current process will wait\nfor the thread to finish before it continues, and, when the thread finishes its\ntask, the resources associated with this thread are automatically freed, and\nthe current process continues with its execution.\n\n\n### Detaching a thread\n\nWhen you detach a thread, the resources associated with this thread are automatically\nreleased back to the system, without the need for another thread to join with this terminated thread.\n\nIn other words, when you call `detach()` on a thread it's like when your children become adults,\ni.e., they become independent from you. A detached thread frees itself, and when this thread finishes its\ntasks, it does not report the results back to you. Thus, you normally mark a thread as *detached*\nwhen you don't need to use the return value of the thread, or when you don't care about\nwhen exactly the thread finishes its job, i.e., the thread solves everything by itself.\n\nTake the code example below. We create a new thread, detach it, and then, we just\nprint a final message before we end our program. We use the same `print_id()`\nfunction that we have used over the previous examples.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_id(id: *const u8) !void {\n    try stdout.print(\"Thread ID: {d}\\n\", .{id.*});\n}\n\npub fn main() !void {\n    const id1: u8 = 1;\n    const thread1 = try Thread.spawn(.{}, print_id, .{&id1});\n    thread1.detach();\n    _ = try stdout.write(\"Finish main\\n\");\n}\n```\n:::\n\n\n\n```\nFinish main\n```\n\nNow, if you look closely at the output of this code example, you will notice\nthat only the final message in main was printed to the console. The message\nthat was supposed to be printed by `print_id()` did not appear in the console.\nWhy? It's because the main process of our program has finished first,\nbefore the thread was able to say anything.\n\nAnd that is perfectly ok behaviour, because the thread was detached, so it was\nable to free itself, without the need to wait for the main process.\nIf you ask main to sleep (or \"wait\") for some extra nanoseconds, before it ends, you will likely\nsee the message printed by `print_id()`, because you give enough time for the thread to\nfinish before the main process ends.\n\n\n## Thread pools\n\nThread pools is a very popular programming pattern, which is used especially on servers and daemons processes.\nA thread pool is just a set of threads, or a \"pool\" of threads. Many programmers like to use this pattern because it makes\nit easier to manage and use multiple threads in your program, instead of manually creating the threads when you need them.\n\nAlso, using thread pools might increase performance as well in your program,\nespecially if your program is constantly creating threads to perform short-lived tasks.\nIn such instance, a thread pool might cause an increase in performance because you do not have be constantly\ncreating and destroying threads all the time, so you don't face a lot of the overhead involved\nin this constant process of creating and destroying threads.\n\nThe main idea behind a thread pool is to have a set of threads already created and ready to perform\ntasks at all times. You create a set of threads at the moment that your program starts, and keep\nthese threads alive while your program runs. Each of these threads will be either performing a task, or\nwaiting for a task to be assigned.\nEvery time a new task emerges in your program, this task is added to a \"queue of tasks\",\nand the moment that a thread becomes available and ready to perform a new task,\nthis thread takes the next task from the \"queue of tasks\", and it simply performs the task.\n\nThe Zig Standard Library offers a thread pool implementation on the `std.Thread.Pool` struct.\nYou create a new instance of a `Pool` object by providing a `Pool.Options` object\nas input to the `init()` method of this struct. A `Pool.Options` object, is a struct object that contains\nconfigurations for the pool of threads. The most important settings in this struct object are\nthe members `n_jobs` and `allocator`. As the name suggests, the member `allocator` should receive an allocator object,\nwhile the member `n_jobs` specifies the number of threads to be created and maintained in this pool.\n\nConsider the example exposed below, that demonstrates how can we create a new thread pool object.\nHere, we create a `Pool.Options` object that contains\na general purpose allocator object, and also, the `n_jobs` member was set to 4, which\nmeans that the thread pool will create and use 4 threads.\n\nAlso notice that the `pool` object was initially set to `undefined`. This allow us\nto initially declare the thread pool object, but not properly instantiate the\nunderlying memory of the object. You have to initially declare your thread pool object\nby using `undefined` like this, because the `init()` method of `Pool` needs\nto have an initial pointer to properly instantiate the object.\n\nSo, just remember to create your thread pool object by using `undefined`, and then,\nafter that, you call the `init()` method over the object.\nYou should also not forget to call the `deinit()` method over the thread pool\nobject, once you are done with it, to release the resources allocated for the thread pool. Otherwise, you will\nhave a memory leak in your program.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Pool = std.Thread.Pool;\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const opt = Pool.Options{\n        .n_jobs = 4,\n        .allocator = allocator,\n    };\n    var pool: Pool = undefined;\n    try pool.init(opt);\n    defer pool.deinit();\n}\n```\n:::\n\n\n\nNow that we know how to create `Pool` objects, we have\nto understand how to assign tasks to be executed by the threads in this pool object.\nTo assign a task to be performed by a thread, we need to call the `spawn()` method\nfrom the thread pool object.\n\nThis `spawn()` method works identical to the `spawn()` method from the\n`Thread` object. The method has almost the same arguments as the previous one,\nmore precisely, we don't have to provide a `SpawnConfig` object in this case.\nBut instead of creating a new thread, this `spawn()` method from\nthe thread pool object just registers a new task in the internal \"queue of tasks\" to be performed,\nand any available thread in the pool will get this task, and it will simply perform the task.\n\nIn the example below, we are using our previous `print_id()` function once again.\nBut you may notice that the `print_id()` function is a little different this time,\nbecause now we are using `catch` instead of `try` in the `print()` call.\nCurrently, the `Pool` struct only supports functions that don't return errors\nas tasks. Thus, when assigning tasks to threads in a thread pool, it is essential to use functions\nthat don't return errors. That is why we are using `catch` here, so that the\n`print_id()` function don't return an error.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_id(id: *const u8) void {\n    _ = stdout.print(\"Thread ID: {d}\\n\", .{id.*})\n        catch void;\n}\nconst id1: u8 = 1;\nconst id2: u8 = 2;\ntry pool.spawn(print_id, .{&id1});\ntry pool.spawn(print_id, .{&id2});\n```\n:::\n\n\n\nThis limitation should probably not exist, and, in fact, it's already on the radar of the\nZig team to fix this issue, and it's being tracked in an [open issue](https://github.com/ziglang/zig/issues/18810)[^issue].\nSo, if you do need to provide a function that might return an error as the task\nto be performed by the threads in the thread pool, then, you are either limited to:\n\n- implementing your own thread pool that does not have this limitation.\n- wait for the Zig team to actually fix this issue.\n\n[^issue]: <https://github.com/ziglang/zig/issues/18810>\n\n\n\n\n## Mutexes\n\nMutexes are a classic component of every thread library. In essence, a mutex is a *Mutually Exclusive Flag*, and this flag\nacts like a type of \"lock\", or as a gate keeper to a particular section of your code. Mutexes are related to thread synchronization,\nmore specifically, they prevent you from having some classic race conditions in your program,\nand, therefore, major bugs and undefined behaviour that are usually difficult to track and understand.\n\nThe main idea behind a mutex is to help us to control the execution of a particular section of the code, and to\nprevent two or more threads from executing this particular section of the code at the same time.\nMany programmers like to compare a mutex to a bathroom door (which typically has a lock).\nWhen a thread locks its own mutex object, it's like if the bathroom door was locked.\nTherefore, other people (in this case, other threads) who want to use the same bathroom at the same time\nmust be patient and simply wait for the current occupant (or thread) to unlock the door and get out of the bathroom.\n\nSome other programmers also like to explain mutexes by using the analogy of \"each person will have their turn to speak\".\nThis is the analogy used in the [*Multithreading Code* video from the Computerphile project](https://www.youtube.com/watch?v=7ENFeb-J75k&ab_channel=Computerphile)[^computerphile].\nImagine if you are in a conversation circle. There is a moderator in this circle, which is the person that decides who\nhas the right to speak at that particular moment. The moderator gives a green card (or some sort of an authorization card) to the person that\nis going to speak, and, as a result, everyone else must be silent and hear this person that has the green card.\nWhen the person finishes talking, they give the green card back to the moderator, and the moderator decides\nwho is going to talk next, and delivers the green card to that person. And the cycle goes on like this.\n\n[^computerphile]: <https://www.youtube.com/watch?v=7ENFeb-J75k&ab_channel=Computerphile>\n\n\nA mutex acts like the moderator in this conversation circle. The mutex authorizes one single thread to execute a specific section of the code,\nand it also blocks the other threads from executing this same section of the code. If these other threads want to execute this same\npiece of the code, they are forced to wait for the the authorized thread to finish first.\nWhen the authorized thread finishes executing this code, the mutex authorizes the next thread to execute this code,\nwhile the remaining threads remain blocked. Therefore, a mutex is like a moderator that does a \"each\nthread will have their turn to execute this section of the code\" type of control.\n\n\nMutexes are especially used to prevent data race problems from happening. A data race problem happens when two or more threads\nare trying to read from or write to the same shared object at the same time.\nSo, when you have an object that is shared will all threads, and, you want to avoid two or more threads from\naccessing this same object at the same time, you can use a mutex to lock the part of the code that access this specific object.\nWhen a thread tries to run this code that is locked by a mutex, this thread stops its execution,\nand patiently waits for this section of the codebase to be unlocked to continue.\n\nNotice that mutexes are normally used to lock areas of the codebase that access/modify data that is **shared** with all threads,\ni.e., objects that are either stored in the global data section, or in the heap space of your program.\nSo mutexes are not normally used on areas of the codebase that access/modify objects that are local to the thread.\n\n\n\n### Critical section {#sec-critical-section}\n\nCritical section is a concept commonly associated with mutexes and thread synchronization.\nIn essence, a critical section is the section of the program that a thread access/modify a shared resource\n(i.e., an object, a file descriptor, something that all threads have access to). In other words,\na critical section is the section of the program where race conditions might happen, and, therefore,\nwhere undefined behaviour can be introduced into the program.\n\nWhen we use mutexes in our program, the critical section defines the area of the codebase that we want to lock.\nSo we normally lock the mutex object at the beginning of the critical section,\nand then, we unlock it at the end of the critical section.\nThe two bullet points exposed below comes from the \"Critical Section\" article from GeekFromGeeks,\nand they summarise well the role that a critical section plays in the thread synchronization problem [@geeks_critical_section].\n\n\n1. The critical section must be executed as an atomic operation, which means that once one thread or process has entered the critical section, all other threads or processes must wait until the executing thread or process exits the critical section. The purpose of synchronization mechanisms is to ensure that only one thread or process can execute the critical section at a time.\n1. The concept of a critical section is central to synchronization in computer systems, as it is necessary to ensure that multiple threads or processes can execute concurrently without interfering with each other. Various synchronization mechanisms such as semaphores, mutexes, monitors, and condition variables are used to implement critical sections and ensure that shared resources are accessed in a mutually exclusive manner.\n\n\n### Atomic operations {#sec-atomic-operation}\n\nYou will also see the term \"atomic operation\" a lot when reading about threads, race conditions and mutexes.\nIn summary, an operation is categorized as \"atomic\" when a context switch cannot occur in\nthe middle of the operation. In other words, this operation is always done from beginning to end, without interruptions\nof another process or operation in the middle of its execution phase.\n\nNot many operations today are atomic. But why do atomic operations matter here? It's because data races\n(which is a type of a race condition) cannot happen on operations that are atomic.\nSo if a particular line in your code performs an atomic operation, then this line will never\nsuffer from a data race problem. Therefore, programmers sometimes use an atomic operation\nto protect themselves from data race problems in their code.\n\nWhen you have an operation that is compiled into just one single assembly instruction, this operation might be atomic,\nbecause it's just one assembly instruction. But this is not guaranteed. This is usually true for old CPU architectures\n(such as `x86`). But nowadays, most assembly instructions in modern CPU architectures are broken down into multiple micro-tasks,\nwhich inherently makes the operation non-atomic, even if it consists of a single assembly instruction.\n\nThe Zig Standard Library offers some atomic functionality in the `std.atomic` module.\nIn this module, you will find a public and generic function called `Value()`. With this function we create an \"atomic object\", which is\na value that contains some native atomic operations, most notably, a `load()` and a `fetchAdd()` operation.\nIf you have experience with multithreading in C++, you probably have recognized this pattern. So yes, this generic\n\"atomic object\" in Zig is essentially identical to the template struct `std::atomic` from the C++ Standard Library.\nIt's important to emphasize that only primitive data types (i.e., the types presented in @sec-primitive-data-types)\nare supported by these atomic operations in Zig.\n\n\n\n\n\n### Data races and race conditions\n\nTo understand why mutexes are used, we need to understand better the problem that they seek\nto solve, which can be summarized into data race problems. A data race problem is a type of a race condition,\nwhich happens when one thread is accessing a particular memory location (i.e., a particular shared object) at the same\ntime that another thread is trying to write/save new data into this same memory location (i.e., the same shared object).\n\nWe can simply define a race condition as any type of bug in your program that is based\non a \"who gets there first\" problem. A data race problem is a type of a race condition, because it occurs when two or more parties\nare trying to read and write into the same memory location at the same time, and, therefore, the end result of this operation\ndepends completely on who gets to this memory location first.\nAs a consequence, a program that has a data race problem will likely produce a different result each time that we execute it.\n\nThus, race conditions produce undefined behaviour and unpredictability because the program produces\na different answer each time a different person gets to the target location before the others.\nAnd, we have no easy way to either predict or control who is getting to this target location first.\nIn other words, each time your program runs, you may get a different answer because a different person,\nfunction, or part of the code finishes its tasks before the others.\n\nAs an example, consider the code snippet exposed below. In this example, we create a global counter\nvariable, and we also create an `increment()` function, whose job is to just increment this global counter\nvariable in a for loop.\n\nSince the for loop iterates 1 hundred thousand times, and, we create two separate threads\nin this code example, what number do you expect to see in the final message printed to `stdout`?\nThe answer should be 2 hundred thousand. Right? Well, in theory, this program was supposed\nto print 2 hundred thousand at the end, but in practice, every time that I execute this program\nI get a different answer.\n\nIn the example exposed below, you can see that this time the end\nresult was 117254, instead of the expected 200000. The second time I executed this program,\nI got the number 108592 as the result. So the end result of this program is varying, but it never gets\nto the expected 200000 that we want.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// Global counter variable\nvar counter: usize = 0;\n// Function to increment the counter\nfn increment() void {\n    for (0..100000) |_| {\n        counter += 1;\n    }\n}\n\npub fn main() !void {\n    const thr1 = try Thread.spawn(.{}, increment, .{});\n    const thr2 = try Thread.spawn(.{}, increment, .{});\n    thr1.join();\n    thr2.join();\n    try stdout.print(\"Couter value: {d}\\n\", .{counter});\n}\n```\n:::\n\n\n\n```\nCouter value: 117254\n```\n\n\nWhy this is happening? The answer is: because this program contains a data race problem.\nThis program would print the correct number 200000 if and only if the first thread finishes\nits tasks before the second thread starts to execute. But that is very unlikely to happen.\nBecause the process of creating the thread is too fast, and therefore, both threads start to execute roughly\nat the same time. If you change this code to add some nanoseconds of sleep between the first and the second calls to `spawn()`,\nyou will increase the chances of the program producing the \"correct result\".\n\nSo the data race problem happens because both threads are reading and writing to the same\nmemory location at roughly the same time. In this example, each thread is essentially performing\nthree basic operations at each iteration of the for loop, which are:\n\n1. reading the current value of `count`.\n1. incrementing this value by 1.\n1. writing the result back into `count`.\n\nIdeally, a thread B should read the value of `count`, only after the other thread A has finished\nwriting the incremented value back into the `count` object. Therefore, in the ideal scenario, which is demonstrated\nin @tbl-data-race-ideal, the threads should work in sync with each other. But the reality is that these\nthreads are out of sync, and because of that, they suffer from a data race problem, which is demonstrated\nin @tbl-data-race-not.\n\nNotice that, in the data race scenario (@tbl-data-race-not), the read performed by a thread B happens\nbefore the write operation of thread A, and that ultimately leads to wrong results at the end of the program.\nBecause when thread B reads the value of the `count` variable, thread A is still processing\nthe initial value from `count`, and has not yet written the new, incremented value back to `count`. As a result,\nthread B ends up reading the same initial (or \"old\") value from `count` instead of\nthe updated, incremented value that thread A would have written.\n\n\n::: {#tbl-data-race-ideal}\n\n| Thread 1    | Thread 2    | Integer value |\n|-------------|-------------|---------------|\n| read value  |             | 0             |\n| increment   |             | 1             |\n| write value |             | 1             |\n|             | read value  | 1             |\n|             | increment   | 2             |\n|             | write value | 2             |\n\n: An ideal scenario for two threads incrementing the same integer value\n:::\n\n::: {#tbl-data-race-not}\n\n| Thread 1    | Thread 2    | Integer value |\n|-------------|-------------|---------------|\n| read value  |             | 0             |\n|             | read value  | 0             |\n| increment   |             | 1             |\n|             | increment   | 1             |\n| write value |             | 1             |\n|             | write value | 1             |\n\n: A data race scenario when two threads are incrementing the same integer value\n:::\n\n\nIf you think about these diagrams exposed in form of tables, you will notice that they relate back to our discussion of atomic operations\nin @sec-atomic-operation. Remember, atomic operations are operations that the CPU executes\nfrom beginning to end, without interruptions from other threads or processes. So,\nthe scenario exposed in @tbl-data-race-ideal does not suffer from a data race, because\nthe operations performed by thread A are not interrupted in the middle by the operations\nfrom thread B.\n\nIf we also think about the discussion of critical section from @sec-critical-section, we can identify\nthe section that representes the critical section of the program, which is the section that is vulnerable\nto data race conditions. In this example, the critical section of the program is the line where we increment\nthe `counter` variable (`counter += 1`). So, ideally, we want to use a mutex, and lock right before this line, and then\nunlock right after this line.\n\n\n\n\n### Using mutexes in Zig\n\nNow that we know the problem that mutexes seek to solve, we can learn how to use them in Zig.\nMutexes in Zig are available through the `std.Thread.Mutex` struct from the Zig Standard Library.\nIf we take the same code from the previous example, and improve it with mutexes, to solve\nour data race problem, we get the code example below.\n\nNotice that this time, we had to alter the `increment()` function to receive a pointer to\nthe `Mutex` object as input. All that we need to do, to make this program safe against\ndata race problems, is to call the `lock()` method at the beginning of\nthe critical section, and then, call `unlock()` at the end of the critical section.\nNotice that the output of this program is now the correct number of 200000.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Thread = std.Thread;\nconst Mutex = std.Thread.Mutex;\nvar counter: usize = 0;\nfn increment(mutex: *Mutex) void {\n    for (0..100000) |_| {\n        mutex.lock();\n        counter += 1;\n        mutex.unlock();\n    }\n}\n\npub fn main() !void {\n    var mutex: Mutex = .{};\n    const thr1 = try Thread.spawn(.{}, increment, .{&mutex});\n    const thr2 = try Thread.spawn(.{}, increment, .{&mutex});\n    thr1.join();\n    thr2.join();\n    try stdout.print(\"Couter value: {d}\\n\", .{counter});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nCouter value: 200000\n```\n\n\n:::\n:::\n\n\n\n\n\n\n## Read/Write locks\n\nMutexes are normally used when it's not always safe for two or more threads running the same\npiece of code at the same time. In contrast, read/write locks are normally used in situations\nwhere you have a mixture of scenarios, i.e., there are some pieces of the codebase that are safe\nto run in parallel, and other pieces that are not safe.\n\nFor example, suppose that you have multiple threads that uses the same shared file in the filesystem to store some configurations, or\nstatistics. If two or more threads try to read the data from this same file at the same time, nothing bad happens.\nSo this part of the codebase is perfectly safe to be executed in parallel, with multiple threads reading the same file at the same time.\n\nHowever, if two or more threads try to write data into this same file at the same time, then we cause some race condition\nproblems. So this other part of the codebase is not safe to be executed in parallel.\nMore specifically, a thread might end up writing data in the middle of the data written by the other thread.\nThis process of two or more threads writing to the same location might lead to data corruption.\nThis specific situation is usually called a *torn write*.\n\nThus, what we can extract from this example is that there are certain types of operations that cause\na race condition, but there are also other types of operations that do not cause a race condition problem.\nYou could also say that there are types of operations that are susceptible to race condition problems,\nand there are other types of operations that are not.\n\nA read/write lock is a type of lock that acknowledges the existence of this specific scenario, and you can\nuse this type of lock to control which parts of the codebase are safe to run in parallel and which parts are not.\n\n\n\n### Exclusive lock vs shared lock\n\nTherefore, a read/write lock is a little different from a mutex. Because a mutex is always an *exclusive lock*, meaning that, only\none thread is allowed to execute at all times. With an exclusive lock, the other threads are always \"excluded\",\ni.e., they are always blocked from executing. But in a read/write lock, the other threads might be authorized\nto run at the same time, depending on the type of lock that they acquire.\n\nWe have two types of locks in a read/write lock, which are: an exclusive lock and a shared lock. An exclusive lock works exactly the same\nas a mutex, while a shared lock is a lock that does not block the other threads from running at the same time.\nIn the `pthreads` C library, read/write locks are available through the `pthread_rwlock_t` C struct. With\nthis C struct, you can create:\n\n- a \"write lock\", which corresponds to an exclusive lock.\n- a \"read lock\", which corresponds to a shared lock.\n\nThe terminology might be a little different compared to Zig. But the meaning is still the same.\nTherefore, just remember this relationship, write locks are exclusive locks, while read locks are shared locks.\n\nWhen a thread tries to acquire a read lock (i.e., a shared lock), this thread gets the shared lock\nif and only if another thread does not currently hold a write lock (i.e., an exclusive lock), and also\nif there are no other threads already in the queue,\nwaiting for their turn to acquire a write lock. In other words, the thread in the queue has attempted\nto get a write lock earlier, but this thread was blocked\nbecause there was another thread running that already had a write lock. As a consequence, this thread is in the queue to get a write lock,\nand it's currently waiting for the other thread with a write lock to finish its execution.\n\nWhen a thread tries to acquire a read lock, but it fails in acquiring this read lock, either because there is\na thread with a write lock already running, or because there is a thread in the queue to get a write lock,\nthe execution of this thread is instantly blocked, i.e., paused. This thread will indefinitely attempt to get the\nread lock, and its execution will be unblocked (or unpaused) only after this thread successfully acquires the read lock.\n\nIf you think deeply about this dynamic between read locks versus write locks, you might notice that a read lock is basically a safety mechanism.\nMore specifically, it's a way for us to\nallow a particular thread to run together with the other threads only when it's safe to. In other words, if there is currently\na thread with a write lock running, then it's very likely not safe for the thread that is trying to acquire the read lock to run now.\nAs a consequence, the read lock protects this thread from running into dangerous waters, and patiently waits for the\n\"write lock\" thread to finishes its tasks before it continues.\n\nOn the other hand, if there are only \"read lock\" (i.e., \"shared lock\") threads currently running\n(i.e., not a single \"write lock\" thread currently exists), then it\nis perfectly safe for this thread that is acquiring the read lock to run in parallel with the other\nthreads. As a result, the read lock just\nallows for this thread to run together with the other threads.\n\nThus, by using read locks (shared locks) in conjunction with write locks (exclusive locks), we can control which regions or sections\nof our multithreaded code is safe to have parallelism, and which sections are not safe to have parallelism.\n\n\n\n\n\n### Using read/write locks in Zig\n\nThe Zig Standard Library supports read/write locks through the `std.Thread.RwLock` module.\nIf you want a particular thread to acquire a shared lock (i.e., a read lock), you should\ncall the `lockShared()` method from the `RwLock` object. But, if you want this thread\nto acquire an exclusive lock (i.e., a write lock) instead, then you should call the\n`lock()` method from the `RwLock` object.\n\nAs with mutexes, we also have to unlock the shared or exclusive locks that we acquire through a read/write lock object,\nonce we are at the end of our \"critical section\". If you have acquired an exclusive lock, then, you unlock\nthis exclusive lock by calling the `unlock()` method from the read/write lock object. In contrast,\nif you have acquired a shared lock instead, then, call `unlockShared()` to unlock this shared lock.\n\nAs a simple example, the snippet below creates three separate threads responsible for reading the\ncurrent value in a `counter` object, and it also creates another thread responsible for writing\nnew data into the `counter` object (incrementing it, more specifically).\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar counter: u32 = 0;\nfn reader(lock: *RwLock) !void {\n    while (true) {\n        lock.lockShared();\n        const v: u32 = counter;\n        try stdout.print(\"{d}\", .{v});\n        lock.unlockShared();\n        std.time.sleep(2 * std.time.ns_per_s);\n    }\n}\nfn writer(lock: *RwLock) void {\n    while (true) {\n        lock.lock();\n        counter += 1;\n        lock.unlock();\n        std.time.sleep(2 * std.time.ns_per_s);\n    }\n}\n\npub fn main() !void {\n    var lock: RwLock = .{};\n    const thr1 = try Thread.spawn(.{}, reader, .{&lock});\n    const thr2 = try Thread.spawn(.{}, reader, .{&lock});\n    const thr3 = try Thread.spawn(.{}, reader, .{&lock});\n    const wthread = try Thread.spawn(.{}, writer, .{&lock});\n\n    thr1.join();\n    thr2.join();\n    thr3.join();\n    wthread.join();\n}\n```\n:::\n\n\n\n\n## Yielding a thread\n\nThe `Thread` struct supports yielding through the `yield()` method.\nYielding a thread means that the execution of the thread is temporarily stopped,\nand it moves to the end of the priority queue managed by the scheduler of\nyour operating system.\n\nThat is, when you yield a thread, you are essentially saying the following to your OS:\n\"Hey! Could you please stop executing this thread for now, and comeback to continue it later?\".\nYou could also interpret this yield operation as: \"Could you please deprioritize this thread,\nto focus on doing other things instead?\".\nSo this yield operation is also a way for you\nto stop a particular thread, so that you can work and prioritize other threads instead.\n\nIt's important to say that, yielding a thread is a \"not so common\" thread operation these days.\nIn other words, not many programmers use yielding in production, simply because it's hard to use\nthis operation and make it work properly, and also, there\nare better alternatives. Most programmers prefer to use `join()` instead.\nIn fact, most of the time, when you see someone using this \"yield\" operation in some code example,\nthey are usually doing so to help debug race conditions in their applications.\nThat is, this \"yield\" operation is mostly used as a debug tool nowadays.\n\nAnyway, if you want to yield a thread, just call the `yield()` method from it, like this:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nthread.yield();\n```\n:::\n\n\n\n\n\n\n\n\n## Common problems in threads\n\n\n\n### Deadlocks\n\nA deadlock occurs when two or more threads are blocked forever,\nwaiting for each other to release a resource. This usually happens when multiple locks are involved,\nand the order of acquiring them is not well managed.\n\nThe code example below demonstrates a deadlock situation. We have two different threads that execute\ntwo different functions (`work1()` and `work2()`) in this example. And we also have two separate\nmutexes. If you compile and run this code example, you will notice that the program just runs indefinitely,\nwithout ending.\n\nWhen we look into the first thread, which executes the `work1()` function, we can\nnotice that this function acquires the `mut1` lock first. Because this is the first operation\nthat is executed inside this thread, which is the first thread created in the program.\nAfter that, the function sleeps for 1 second, to\nsimulate some type of work, and then, the function tries to acquire the `mut2` lock.\n\nOn the other hand, when we look into the second thread, which executes the `work2()` function,\nwe can see that this function acquires the `mut2` lock first. Because when this thread gets created and it tries\nto acquire this `mut2` lock, the first thread is still sleeping on that \"sleep 1 second\" line.\nAfter acquiring `mut2`, the `work2()` function also sleeps for 1 second, to\nsimulate some type of work, and then the function tries to acquire the `mut1` lock.\n\nThis creates a deadlock situation, because after the \"sleep for 1 second\" line in both threads,\nthread 1 is trying to acquire the `mut2` lock, but this lock is currently being used by thread 2.\nHowever, at this moment, thread 2 is also trying to acquire the `mut1` lock, which is currently\nbeing used by thread 1. Therefore, both threads end up waiting for ever. Waiting for their peer to\nfree the lock that they want to acquire.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar mut1: Mutex = .{}; var mut2: Mutex = .{};\nfn work1() !void {\n    mut1.lock();\n    std.time.sleep(1 * std.time.ns_per_s);\n    mut2.lock();\n    _ = try stdout.write(\"Doing some work 1\\n\");\n    mut2.unlock(); mut1.unlock();\n}\n\nfn work2() !void {\n    mut2.lock();\n    std.time.sleep(1 * std.time.ns_per_s);\n    mut1.lock();\n    _ = try stdout.write(\"Doing some work 1\\n\");\n    mut1.unlock(); mut2.unlock();\n}\n\npub fn main() !void {\n    const thr1 = try Thread.spawn(.{}, work1, .{});\n    const thr2 = try Thread.spawn(.{}, work2, .{});\n    thr1.join();\n    thr2.join();\n}\n```\n:::\n\n\n\n\n### Not calling `join()` or `detach()` {#sec-not-call-join-detach}\n\nWhen you do not call either `join()` or `detach()` over a thread, then this thread becomes a \"zombie thread\",\nbecause it does not have a clear \"return point\".\nYou could also interpret this as: \"nobody is properly responsible for managing the thread\".\nWhen we don't establish if a thread is either *joinable* or *detached*,\nnobody becomes responsible for dealing with the return value of this thread, and also,\nnobody becomes responsible for clearing (or freeing) the resources associated with this thread.\n\nYou don't want to be in this situation, so remember to always use `join()` or `detach()`\non the threads that you create. When you don't use one of these methods, we lose\ncontrol over the thread, and its resources are never freed\n(i.e., you have leaked resources in the system).\n\n\n### Cancelling or killing a particular thread\n\nWhen we think about the `pthreads` C library, there is a possible way to asynchronously kill or cancel\na thread, which is by sending a `SIGTERM` signal to the thread through the `pthread_kill()` function.\nBut canceling a thread like this is bad. It's dangerously bad. As a consequence, the Zig implementation\nof threads does not have a similar function, or, a similar way to asynchronously cancel or kill\na thread.\n\nTherefore, if you want to cancel a thread in the middle of its execution in Zig,\nthen one good strategy that you can take is to use control flow in conjunction with `join()`.\nMore specifically, you can design your thread around a while loop that is constantly\nchecking if the thread should continue running.\nIf it's time to cancel the thread, we could make the while loop break, and join the thread with the main thread\nby calling `join()`.\n\nThe code example below demonstrates to some extent this strategy.\nHere, we are using control flow to break the while loop, and exit the thread earlier than\nwhat we have initially planned to. This example also demonstrates how can we use\natomic objects in Zig with the `Value()` generic function that we have mentioned in @sec-atomic-operation.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Thread = std.Thread;\nconst stdout = std.io.getStdOut().writer();\nvar running = std.atomic.Value(bool).init(true);\nvar counter: u64 = 0;\nfn do_more_work() void {\n    std.time.sleep(2 * std.time.ns_per_s);\n}\nfn work() !void {\n    while (running.load(.monotonic)) {\n        for (0..10000) |_| { counter += 1; }\n        if (counter < 15000) {\n            _ = try stdout.write(\n                \"Time to cancel the thread.\\n\"\n            );\n            running.store(false, .monotonic);\n        } else {\n            _ = try stdout.write(\"Time to do more work.\\n\");\n            do_more_work();\n            running.store(false, .monotonic);\n        }\n    }\n}\n\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, work, .{});\n    thread.join();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nTime to cancel the thread.\n```\n\n\n:::\n:::\n",
-    "supporting": [
-      "14-threads_files"
-    ],
-    "filters": [
-      "rmarkdown/pagebreak.lua"
-    ],
-    "includes": {},
-    "engineDependencies": {
-      "knitr": [
-        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
-      ]
-    },
-    "preserve": null,
-    "postProcess": false
-  }
-}
\ No newline at end of file
diff --git a/_freeze/Chapters/14-threads/execute-results/html.json b/_freeze/Chapters/14-threads/execute-results/html.json
index e68da4ad..6357f7e3 100644
--- a/_freeze/Chapters/14-threads/execute-results/html.json
+++ b/_freeze/Chapters/14-threads/execute-results/html.json
@@ -2,10 +2,8 @@
   "hash": "5330e6bae2255d3ad46893b0641f0683",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Introducing threads and parallelism in Zig {#sec-thread}\n\nThreads are available in Zig through the `Thread` struct from the Zig Standard Library.\nThis struct represents a kernel thread, and it follows a POSIX Thread pattern,\nmeaning that, it works similarly to a thread from the `pthread` C library, which is usually available on any distribution\nof the GNU C Compiler (`gcc`). If you are not familiar with threads, I will give you some theory behind it first, shall we?\n\n\n## What are threads? {#sec-what-thread}\n\nA thread is basically a separate context of execution.\nWe use threads to introduce parallelism into our program,\nwhich in most cases, makes the program run faster, because we have multiple tasks\nbeing performed at the same time, parallel to each other.\n\nPrograms are normally single-threaded by default. Which means that each program\nusually runs on a single thread, or, a single context of execution. When we have only one thread running, we have no\nparallelism. And when we don't have parallelism, the commands are executed sequentially, that is,\nonly one command is executed at a time, one after another. By creating multiple threads inside our program,\nwe start to execute multiple commands at the same time.\n\nPrograms that create multiple threads are very common in the wild. Because many different types\nof applications are well suited for parallelism. Good examples are video and photo-editing applications\n(e.g. Adobe Photoshop or DaVinci Resolve), games (e.g. The Witcher 3), and also web browsers\n(e.g. Google Chrome, Firefox, Microsoft Edge, etc).\nFor example, in web browsers, threads are normally used to implement tabs.\nThe tabs in a web browsers usually run as separate threads in the main process of\nthe web browser. That is, each new tab that you open in your web browser\nusually runs on a separate thread of execution.\n\nBy running each tab in a separate thread, we allow all open tabs in the browser to run at the same time,\nand independently from each other. For example, you might have YouTube or Spotify currently open in\na tab, and you are listening to some podcast in that tab while at the same time\nworking in another tab, writing an essay on Google Docs. Even if you are not looking\ninto the YouTube tab, you can still hear the podcast only because this YouTube tab is running in parallel\nwith the other tab where Google Docs is running.\n\nWithout threads, the other alternative would be to run each tab as a completely separate\nprocess in your computer. But that would be a bad choice because just a few tabs would already consume\ntoo much power and resources from your computer. In other words, it's very expensive to create a completely new process,\ncompared to creating a new thread of execution. Also, the chances of you experiencing lag and overhead\nwhile using the browser would be significant. Threads are faster to create, and they also consume\nmuch, much less resources from the computer, especially because they share some resources\nwith the main process.\n\nTherefore, it's the use of threads in modern web browsers that allow you to hear the podcast\nat the same time while you are writing something on Google Docs.\nWithout threads, a web browser would probably be limited to just one single tab.\n\nThreads are also well-suited for anything that involves serving requests or orders.\nBecause serving a request takes time, and usually involves a lot of \"waiting time\".\nIn other words, we spend a lot of time in idle, waiting for something to complete.\nFor example, consider a restaurant. Serving orders in a restaurant usually involves\nthe following steps:\n\n1. receive order from the client.\n1. pass the order to the kitchen, and wait for the food to be cooked.\n1. start cooking the food in the kitchen.\n1. when the food is fully cooked deliver this food to the client.\n\nIf you think about the bullet points above, you will notice that one big moment of waiting time\nis present in this whole process, which is while the food is being cooked\ninside the kitchen. While the food is being prepped, both the waiter and the client\nthemselves are waiting for the food to be ready and delivered.\n\nIf we write a program to represent this restaurant, more specifically, a single-threaded program, then\nthis program would be very inefficient. Because the program would stay in idle, waiting for a considerable amount\nof time on the \"check if food is ready\" step. Consider the code snippet exposed below that could\npotentially represent such program.\n\nThe problem with this program is the while loop. This program will spend a lot of time\nwaiting on the while loop, doing nothing more than just checking if the food is ready.\nThis is a waste of time. Instead of waiting for something to happen, the waiter\ncould just send the order to the kitchen, and just move on, and continue with receiving\nmore orders from other clients, and sending more orders to the kitchen, instead\nof doing nothing and waiting for the food to be ready.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst order = Order.init(\"Pizza Margherita\", n = 1);\nconst waiter = Waiter.init();\nwaiter.receive_order(order);\nwaiter.ask_kitchen_to_cook();\nvar food_not_ready = true;\nwhile (food_not_ready) {\n    food_not_ready = waiter.is_food_ready();\n}\nconst food = waiter.get_food_from_kitchen();\nwaiter.send_food_to_client(food);\n```\n:::\n\n\n\n\nThis is why threads would be a great fit for this program. We could use threads\nto free the waiters from their \"waiting duties\", so they can go on with their\nother tasks, and receive more orders. Take a look at the next example, where I have re-written the above\nprogram into a different program that uses threads to cook and deliver the orders.\n\nYou can see in this program that when a waiter receives a new order\nfrom a client, this waiter executes the `send_order()` function.\nThe only thing that this function does is to create a new thread\nand detaches it. Since creating a thread is a very fast operation,\nthis `send_order()` function returns almost immediately,\nso the waiter spends almost no time worrying about the order, and just\nmove on and tries to get the next order from the clients.\n\nInside the new thread created, the order gets cooked by a chef, and when the\nfood is ready, it's delivered to the client's table.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn cook_and_deliver_order(order: *Order) void {\n    const chef = Chef.init();\n    const food = chef.cook(order.*);\n    chef.deliver_food(food);\n}\nfn send_order(order: Order) void {\n    const cook_thread = Thread.spawn(\n        .{}, cook_and_deliver_order, .{&order}\n    );\n    cook_thread.detach();\n}\n\nconst waiter = Waiter.init();\nwhile (true) {\n    const order = waiter.get_new_order();\n    if (order) {\n        send_order(order);\n    }\n}\n```\n:::\n\n\n\n\n\n\n## Threads versus processes\n\nWhen we run a program, this program is executed as a *process* in the operating system.\nThis is a one to one relationship, each program or application that you execute\nis a separate process in the operating system. But each program, or each process,\ncan create and contain multiple threads inside of it. Therefore,\nprocesses and threads have a one to many relationship.\n\nThis also means that every thread that we create is always associated with a particular process in our computer.\nIn other words, a thread is always a subset (or a children) of an existing process.\nAll threads share some of the resources associated with the process from which they were created.\nAnd because threads share resources with the process, they are very good for making communication\nbetween tasks easier.\n\nFor example, suppose that you were developing a big and complex application\nthat would be much simpler if you could split it in two, and make these two separate pieces talk\nwith each other. Some programmers opt to effectively write these two pieces of the codebase as two\ncompletely separate programs, and then, they use IPC (*inter-process communication*) to make these\ntwo separate programs/processes talk to each other, and make them work together.\n\nHowever, some programmers find IPC hard to deal with, and, as consequence,\nthey prefer to write one piece of the codebase as the \"main part of the program\",\nor, as the part of the code that runs as the process in the operating system,\nwhile the other piece of the codebase is written as a task to be executed in\na new thread. A process and a thread can easily comunicate with each other\nthrough both control flow, and also, through data, because they share and have\naccess to the same standard file descriptors (`stdout`, `stdin`, `stderr`), and also to the\nsame memory space on the heap and global data section.\n\n\nIn more details, each thread that you create have a separate stack frame reserved just for that thread,\nwhich essentially means that each local object that you create inside this thread, is local to that\nthread, i.e., the other threads cannot see this local object. Unless this object that you have created\nis an object that lives on the heap. In other words, if the memory associated with this object\nis on the heap, then, the other threads can potentially access this object.\n\nTherefore, objects that are stored in the stack are local to the thread where they were created.\nBut objects that are stored on the heap are potentially accessible to other threads. All of this means that,\neach thread has its own separate stack frame, but, at the same time, all threads share\nthe same heap, the same standard file descriptors (which means that they share the same `stdout`, `stdin`, `stderr`),\nand the same global data section in the program.\n\n\n\n## Creating a thread\n\nWe create new threads in Zig by first importing the `Thread` struct into\nour current Zig module and then calling the `spawn()` method of this struct,\nwhich creates (or \"spawns\") a new thread of execution from our current process.\nThis method has three arguments, which are, respectively:\n\n1. a `SpawnConfig` object, which contains configurations for the spawn process.\n1. the name of the function that is going to be executed (or that is going to be \"called\") inside this new thread.\n1. a list of arguments (or inputs) to be passed to the function provided in the second argument.\n\nWith these three arguments, you can control how the thread gets created, and also, specify which\nwork (or \"tasks\") will be performed inside this new thread. A thread is just a separate context of execution,\nand we usually create new threads in our code because we want to perform some work inside this\nnew context of execution. And we specify which exact work, or which exact steps that are going to be\nperformed inside this context by providing the name of a function as the second argument of the `spawn()` method.\n\nThus, when this new thread gets created, this function that you provided as input to the `spawn()`\nmethod gets called, or gets executed inside this new thread. You can control the\narguments, or the inputs that are passed to this function when it gets called by providing\na list of arguments (or a list of inputs) in the third argument of the `spawn()` method.\nThese arguments are passed to the function in the same order that they are\nprovided to `spawn()`.\n\nFurthermore, the `SpawnConfig` is a struct object with only two possible fields, or, two possible members, that you\ncan set to tailor the spawn behaviour. These fields are:\n\n- `stack_size`: you can provide a `usize` value to specify the size (in bytes) of the thread's stack frame. By default, this value is: $16 \\times 1024 \\times 1024$.\n- `allocator`: you can provide an allocator object to be used when allocating memory for the thread.\n\nTo use one of these two fields (or \"configs\"), you just have to create a new object of type `SpawnConfig`,\nand provide this object as input to the `spawn()` method. But, if you are not interested in using\none of these configs, and you are ok with using just the defaults, you can just provide an anonymous\nstruct literal (`.{}`) in place of this `SpawnConfig` argument.\n\nAs our first, and very simple example, consider the code exposed below.\nInside the same program, you can create multiple threads of execution if you want to.\nBut, in this first example, we are creating just a single thread of execution, because\nwe call `spawn()` only once.\n\nAlso, notice in this example that we are executing the function `do_some_work()`\ninside the new thread. Since this function receives no inputs, because it has\nno arguments, we have passed an empty list in this instance, or more precisely,\nan empty, anonymous struct (`.{}`) in the third argument of `spawn()`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Thread = std.Thread;\nfn do_some_work() !void {\n    _ = try stdout.write(\"Starting the work.\\n\");\n    std.time.sleep(100 * std.time.ns_per_ms);\n    _ = try stdout.write(\"Finishing the work.\\n\");\n}\n\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, do_some_work, .{});\n    thread.join();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nStarting the work.Finishing the work.\n```\n\n\n:::\n:::\n\n\n\n\nNotice the use of `try` when calling the `spawn()` method. This means\nthat this method can return an error in some circumstances. One circumstance\nin particular is when you attempt to create a new thread, when you have already\ncreated too much (i.e., you have exceeded the quota of concurrent threads in your system).\n\nBut, if the new thread is successfully created, the `spawn()` method returns a handler\nobject (which is just an object of type `Thread`) to this new thread. You can use\nthis handler object to effectively control all aspects of the thread.\n\nWhen the thread gets created, the function that you provided as input to `spawn()`\ngets invoked (i.e., gets called) to start the execution on this new thread.\nIn other words, every time you call `spawn()`, not only is a new thread created,\nbut the \"start work button\" of this thread is also automatically pressed.\nSo the work being performed in this thread starts as soon as the thread is created.\nThis is similar to how `pthread_create()` from the `pthreads` library in C works,\nwhich also starts the execution as soon as the thread is created.\n\n\n## Returning from a thread\n\nWe have learned in the previous section that the execution of the thread starts as soon as\nthe thread is created. Now, we will learn how to \"join\" or \"detach\" a thread in Zig.\n\"Join\" and \"detach\" are operations that control how the thread returns to\nthe main thread, or to the main process in our program.\n\nWe perform these operations by using the methods `join()` and `detach()` from the thread handler object.\nEvery thread that you create can be marked as either *joinable* or *detached* [@linux_pthread_create].\nYou can turn a thread into a *detached* thread by calling the `detach()` method\nfrom the thread handler object. But if you call the `join()` method instead, then this thread\nbecomes a *joinable* thread.\n\nA thread cannot be both *joinable* and *detached*. Which in general means\nthat you cannot call both `join()` and `detach()` on the same thread.\nBut a thread must be one of the two, meaning that, you should always call\neither `join()` or `detach()` over a thread. If you don't call\none of these two methods over your thread, you introduce undefined behaviour into your program,\nwhich is described in @sec-not-call-join-detach.\n\nNow, let's describe what each of these two methods do to your thread.\n\n\n### Joining a thread\n\nWhen you join a thread, you are essentially saying: \"Hey! Could you please wait for the thread to finish,\nbefore you continue with your execution?\". For example, if we come back to our first and simplest example\nof a thread in Zig, we created a single thread inside the `main()` function of our program\nand just called `join()` on this thread at the end. This section of the code example is reproduced below.\n\nBecause we are joining this new thread inside the `main()`'s scope, it means that the\nexecution of the `main()` function is temporarily stopped, to wait for the execution of the thread\nto finish. That is, the execution of `main()` stops temporarily at the line where `join()` gets called,\nand it will continue only after the thread has finished its tasks.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, do_some_work, .{});\n    thread.join();\n}\n```\n:::\n\n\n\n\nBecause we have joined this new thread inside the `main()` scope, we have a\nguarantee that this new thread will finish before the end of the execution of `main()`.\nBecause it's guaranteed that `main()` will wait for the thread to finish its tasks.\n\nIn the example above, there are no more expressions after the `join()` call. We just have the end\nof the `main()`'s scope, and, therefore, the execution of our program just ends after the thread finishes its tasks,\nsince there is nothing more to do. But what if we had more stuff to do after the join call?\n\nTo demonstrate this other possibility, consider the next example exposed\nbelow. Here, we create a `print_id()` function, that just receives an id\nas input, and prints it to `stdout`. In this example, we are creating two\nnew threads, one after another. Then, we join the first thread, then,\nwe wait for two whole seconds, then, at last, we join the second thread.\n\nThe idea behind this example is that the last `join()` call is executed\nonly after the first thread finishes its task (i.e., the first `join()` call),\nand the two-second delay. If you compile and run this\nexample, you will notice that most messages are quickly printed to `stdout`,\ni.e., they appear almost instantly on your screen.\nHowever, the last message (\"Joining thread 2\") takes around 2 seconds to appear\non the screen.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_id(id: *const u8) !void {\n    try stdout.print(\"Thread ID: {d}\\n\", .{id.*});\n}\n\npub fn main() !void {\n    const id1: u8 = 1;\n    const id2: u8 = 2;\n    const thread1 = try Thread.spawn(.{}, print_id, .{&id1});\n    const thread2 = try Thread.spawn(.{}, print_id, .{&id2});\n\n    _ = try stdout.write(\"Joining thread 1\\n\");\n    thread1.join();\n    std.time.sleep(2 * std.time.ns_per_s);\n    _ = try stdout.write(\"Joining thread 2\\n\");\n    thread2.join();\n}\n```\n:::\n\n\n\n\n```\nThread ID: Joining thread 1\n1\nThread ID: 2\nJoining thread 2\n```\n\nThis demonstrates that both threads finish their work (i.e., printing the IDs)\nvery fast, before the two seconds of delay end. Because of that, the last `join()` call\nreturns pretty much instantly. Because when this last `join()` call happens, the second\nthread has already finished its task.\n\nNow, if you compile and run this example, you will also notice that, in some cases,\nthe messages intertwine with each other. In other words, you might see\nthe message \"Joining thread 1\" inserted in the middle of the message \"Thread 1\",\nor vice-versa. This happens because:\n\n- the threads are executing basically at the same time as the main process of the program (i.e., the `main()` function).\n- the threads share the same `stdout` from the main process of the program, which means that the messages that the threads produce are sent to exact same place as the messages produced by the main process.\n\nBoth of these points were described previously in @sec-what-thread.\nSo the messages might get intertwined because they are being produced and\nsent to the same `stdout` roughly at the same time.\nAnyway, when you call `join()` over a thread, the current process will wait\nfor the thread to finish before it continues, and, when the thread finishes its\ntask, the resources associated with this thread are automatically freed, and\nthe current process continues with its execution.\n\n\n### Detaching a thread\n\nWhen you detach a thread, the resources associated with this thread are automatically\nreleased back to the system, without the need for another thread to join with this terminated thread.\n\nIn other words, when you call `detach()` on a thread it's like when your children become adults,\ni.e., they become independent from you. A detached thread frees itself, and when this thread finishes its\ntasks, it does not report the results back to you. Thus, you normally mark a thread as *detached*\nwhen you don't need to use the return value of the thread, or when you don't care about\nwhen exactly the thread finishes its job, i.e., the thread solves everything by itself.\n\nTake the code example below. We create a new thread, detach it, and then, we just\nprint a final message before we end our program. We use the same `print_id()`\nfunction that we have used over the previous examples.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_id(id: *const u8) !void {\n    try stdout.print(\"Thread ID: {d}\\n\", .{id.*});\n}\n\npub fn main() !void {\n    const id1: u8 = 1;\n    const thread1 = try Thread.spawn(.{}, print_id, .{&id1});\n    thread1.detach();\n    _ = try stdout.write(\"Finish main\\n\");\n}\n```\n:::\n\n\n\n\n```\nFinish main\n```\n\nNow, if you look closely at the output of this code example, you will notice\nthat only the final message in main was printed to the console. The message\nthat was supposed to be printed by `print_id()` did not appear in the console.\nWhy? It's because the main process of our program has finished first,\nbefore the thread was able to say anything.\n\nAnd that is perfectly ok behaviour, because the thread was detached, so it was\nable to free itself, without the need to wait for the main process.\nIf you ask main to sleep (or \"wait\") for some extra nanoseconds, before it ends, you will likely\nsee the message printed by `print_id()`, because you give enough time for the thread to\nfinish before the main process ends.\n\n\n## Thread pools\n\nThread pools is a very popular programming pattern, which is used especially on servers and daemons processes.\nA thread pool is just a set of threads, or a \"pool\" of threads. Many programmers like to use this pattern because it makes\nit easier to manage and use multiple threads in your program, instead of manually creating the threads when you need them.\n\nAlso, using thread pools might increase performance as well in your program,\nespecially if your program is constantly creating threads to perform short-lived tasks.\nIn such instance, a thread pool might cause an increase in performance because you do not have be constantly\ncreating and destroying threads all the time, so you don't face a lot of the overhead involved\nin this constant process of creating and destroying threads.\n\nThe main idea behind a thread pool is to have a set of threads already created and ready to perform\ntasks at all times. You create a set of threads at the moment that your program starts, and keep\nthese threads alive while your program runs. Each of these threads will be either performing a task, or\nwaiting for a task to be assigned.\nEvery time a new task emerges in your program, this task is added to a \"queue of tasks\",\nand the moment that a thread becomes available and ready to perform a new task,\nthis thread takes the next task from the \"queue of tasks\", and it simply performs the task.\n\nThe Zig Standard Library offers a thread pool implementation on the `std.Thread.Pool` struct.\nYou create a new instance of a `Pool` object by providing a `Pool.Options` object\nas input to the `init()` method of this struct. A `Pool.Options` object, is a struct object that contains\nconfigurations for the pool of threads. The most important settings in this struct object are\nthe members `n_jobs` and `allocator`. As the name suggests, the member `allocator` should receive an allocator object,\nwhile the member `n_jobs` specifies the number of threads to be created and maintained in this pool.\n\nConsider the example exposed below, that demonstrates how can we create a new thread pool object.\nHere, we create a `Pool.Options` object that contains\na general purpose allocator object, and also, the `n_jobs` member was set to 4, which\nmeans that the thread pool will create and use 4 threads.\n\nAlso notice that the `pool` object was initially set to `undefined`. This allow us\nto initially declare the thread pool object, but not properly instantiate the\nunderlying memory of the object. You have to initially declare your thread pool object\nby using `undefined` like this, because the `init()` method of `Pool` needs\nto have an initial pointer to properly instantiate the object.\n\nSo, just remember to create your thread pool object by using `undefined`, and then,\nafter that, you call the `init()` method over the object.\nYou should also not forget to call the `deinit()` method over the thread pool\nobject, once you are done with it, to release the resources allocated for the thread pool. Otherwise, you will\nhave a memory leak in your program.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Pool = std.Thread.Pool;\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const opt = Pool.Options{\n        .n_jobs = 4,\n        .allocator = allocator,\n    };\n    var pool: Pool = undefined;\n    try pool.init(opt);\n    defer pool.deinit();\n}\n```\n:::\n\n\n\n\nNow that we know how to create `Pool` objects, we have\nto understand how to assign tasks to be executed by the threads in this pool object.\nTo assign a task to be performed by a thread, we need to call the `spawn()` method\nfrom the thread pool object.\n\nThis `spawn()` method works identical to the `spawn()` method from the\n`Thread` object. The method has almost the same arguments as the previous one,\nmore precisely, we don't have to provide a `SpawnConfig` object in this case.\nBut instead of creating a new thread, this `spawn()` method from\nthe thread pool object just registers a new task in the internal \"queue of tasks\" to be performed,\nand any available thread in the pool will get this task, and it will simply perform the task.\n\nIn the example below, we are using our previous `print_id()` function once again.\nBut you may notice that the `print_id()` function is a little different this time,\nbecause now we are using `catch` instead of `try` in the `print()` call.\nCurrently, the `Pool` struct only supports functions that don't return errors\nas tasks. Thus, when assigning tasks to threads in a thread pool, it is essential to use functions\nthat don't return errors. That is why we are using `catch` here, so that the\n`print_id()` function don't return an error.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_id(id: *const u8) void {\n    _ = stdout.print(\"Thread ID: {d}\\n\", .{id.*})\n        catch void;\n}\nconst id1: u8 = 1;\nconst id2: u8 = 2;\ntry pool.spawn(print_id, .{&id1});\ntry pool.spawn(print_id, .{&id2});\n```\n:::\n\n\n\n\nThis limitation should probably not exist, and, in fact, it's already on the radar of the\nZig team to fix this issue, and it's being tracked in an [open issue](https://github.com/ziglang/zig/issues/18810)[^issue].\nSo, if you do need to provide a function that might return an error as the task\nto be performed by the threads in the thread pool, then, you are either limited to:\n\n- implementing your own thread pool that does not have this limitation.\n- wait for the Zig team to actually fix this issue.\n\n[^issue]: <https://github.com/ziglang/zig/issues/18810>\n\n\n\n\n## Mutexes\n\nMutexes are a classic component of every thread library. In essence, a mutex is a *Mutually Exclusive Flag*, and this flag\nacts like a type of \"lock\", or as a gate keeper to a particular section of your code. Mutexes are related to thread synchronization,\nmore specifically, they prevent you from having some classic race conditions in your program,\nand, therefore, major bugs and undefined behaviour that are usually difficult to track and understand.\n\nThe main idea behind a mutex is to help us to control the execution of a particular section of the code, and to\nprevent two or more threads from executing this particular section of the code at the same time.\nMany programmers like to compare a mutex to a bathroom door (which typically has a lock).\nWhen a thread locks its own mutex object, it's like if the bathroom door was locked.\nTherefore, other people (in this case, other threads) who want to use the same bathroom at the same time\nmust be patient and simply wait for the current occupant (or thread) to unlock the door and get out of the bathroom.\n\nSome other programmers also like to explain mutexes by using the analogy of \"each person will have their turn to speak\".\nThis is the analogy used in the [*Multithreading Code* video from the Computerphile project](https://www.youtube.com/watch?v=7ENFeb-J75k&ab_channel=Computerphile)[^computerphile].\nImagine if you are in a conversation circle. There is a moderator in this circle, which is the person that decides who\nhas the right to speak at that particular moment. The moderator gives a green card (or some sort of an authorization card) to the person that\nis going to speak, and, as a result, everyone else must be silent and hear this person that has the green card.\nWhen the person finishes talking, they give the green card back to the moderator, and the moderator decides\nwho is going to talk next, and delivers the green card to that person. And the cycle goes on like this.\n\n[^computerphile]: <https://www.youtube.com/watch?v=7ENFeb-J75k&ab_channel=Computerphile>\n\n\nA mutex acts like the moderator in this conversation circle. The mutex authorizes one single thread to execute a specific section of the code,\nand it also blocks the other threads from executing this same section of the code. If these other threads want to execute this same\npiece of the code, they are forced to wait for the the authorized thread to finish first.\nWhen the authorized thread finishes executing this code, the mutex authorizes the next thread to execute this code,\nwhile the remaining threads remain blocked. Therefore, a mutex is like a moderator that does a \"each\nthread will have their turn to execute this section of the code\" type of control.\n\n\nMutexes are especially used to prevent data race problems from happening. A data race problem happens when two or more threads\nare trying to read from or write to the same shared object at the same time.\nSo, when you have an object that is shared will all threads, and, you want to avoid two or more threads from\naccessing this same object at the same time, you can use a mutex to lock the part of the code that access this specific object.\nWhen a thread tries to run this code that is locked by a mutex, this thread stops its execution,\nand patiently waits for this section of the codebase to be unlocked to continue.\n\nNotice that mutexes are normally used to lock areas of the codebase that access/modify data that is **shared** with all threads,\ni.e., objects that are either stored in the global data section, or in the heap space of your program.\nSo mutexes are not normally used on areas of the codebase that access/modify objects that are local to the thread.\n\n\n\n### Critical section {#sec-critical-section}\n\nCritical section is a concept commonly associated with mutexes and thread synchronization.\nIn essence, a critical section is the section of the program that a thread access/modify a shared resource\n(i.e., an object, a file descriptor, something that all threads have access to). In other words,\na critical section is the section of the program where race conditions might happen, and, therefore,\nwhere undefined behaviour can be introduced into the program.\n\nWhen we use mutexes in our program, the critical section defines the area of the codebase that we want to lock.\nSo we normally lock the mutex object at the beginning of the critical section,\nand then, we unlock it at the end of the critical section.\nThe two bullet points exposed below comes from the \"Critical Section\" article from GeekFromGeeks,\nand they summarise well the role that a critical section plays in the thread synchronization problem [@geeks_critical_section].\n\n\n1. The critical section must be executed as an atomic operation, which means that once one thread or process has entered the critical section, all other threads or processes must wait until the executing thread or process exits the critical section. The purpose of synchronization mechanisms is to ensure that only one thread or process can execute the critical section at a time.\n1. The concept of a critical section is central to synchronization in computer systems, as it is necessary to ensure that multiple threads or processes can execute concurrently without interfering with each other. Various synchronization mechanisms such as semaphores, mutexes, monitors, and condition variables are used to implement critical sections and ensure that shared resources are accessed in a mutually exclusive manner.\n\n\n### Atomic operations {#sec-atomic-operation}\n\nYou will also see the term \"atomic operation\" a lot when reading about threads, race conditions and mutexes.\nIn summary, an operation is categorized as \"atomic\" when a context switch cannot occur in\nthe middle of the operation. In other words, this operation is always done from beginning to end, without interruptions\nof another process or operation in the middle of its execution phase.\n\nNot many operations today are atomic. But why do atomic operations matter here? It's because data races\n(which is a type of a race condition) cannot happen on operations that are atomic.\nSo if a particular line in your code performs an atomic operation, then this line will never\nsuffer from a data race problem. Therefore, programmers sometimes use an atomic operation\nto protect themselves from data race problems in their code.\n\nWhen you have an operation that is compiled into just one single assembly instruction, this operation might be atomic,\nbecause it's just one assembly instruction. But this is not guaranteed. This is usually true for old CPU architectures\n(such as `x86`). But nowadays, most assembly instructions in modern CPU architectures are broken down into multiple micro-tasks,\nwhich inherently makes the operation non-atomic, even if it consists of a single assembly instruction.\n\nThe Zig Standard Library offers some atomic functionality in the `std.atomic` module.\nIn this module, you will find a public and generic function called `Value()`. With this function we create an \"atomic object\", which is\na value that contains some native atomic operations, most notably, a `load()` and a `fetchAdd()` operation.\nIf you have experience with multithreading in C++, you probably have recognized this pattern. So yes, this generic\n\"atomic object\" in Zig is essentially identical to the template struct `std::atomic` from the C++ Standard Library.\nIt's important to emphasize that only primitive data types (i.e., the types presented in @sec-primitive-data-types)\nare supported by these atomic operations in Zig.\n\n\n\n\n\n### Data races and race conditions\n\nTo understand why mutexes are used, we need to understand better the problem that they seek\nto solve, which can be summarized into data race problems. A data race problem is a type of a race condition,\nwhich happens when one thread is accessing a particular memory location (i.e., a particular shared object) at the same\ntime that another thread is trying to write/save new data into this same memory location (i.e., the same shared object).\n\nWe can simply define a race condition as any type of bug in your program that is based\non a \"who gets there first\" problem. A data race problem is a type of a race condition, because it occurs when two or more parties\nare trying to read and write into the same memory location at the same time, and, therefore, the end result of this operation\ndepends completely on who gets to this memory location first.\nAs a consequence, a program that has a data race problem will likely produce a different result each time that we execute it.\n\nThus, race conditions produce undefined behaviour and unpredictability because the program produces\na different answer each time a different person gets to the target location before the others.\nAnd, we have no easy way to either predict or control who is getting to this target location first.\nIn other words, each time your program runs, you may get a different answer because a different person,\nfunction, or part of the code finishes its tasks before the others.\n\nAs an example, consider the code snippet exposed below. In this example, we create a global counter\nvariable, and we also create an `increment()` function, whose job is to just increment this global counter\nvariable in a for loop.\n\nSince the for loop iterates 1 hundred thousand times, and, we create two separate threads\nin this code example, what number do you expect to see in the final message printed to `stdout`?\nThe answer should be 2 hundred thousand. Right? Well, in theory, this program was supposed\nto print 2 hundred thousand at the end, but in practice, every time that I execute this program\nI get a different answer.\n\nIn the example exposed below, you can see that this time the end\nresult was 117254, instead of the expected 200000. The second time I executed this program,\nI got the number 108592 as the result. So the end result of this program is varying, but it never gets\nto the expected 200000 that we want.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// Global counter variable\nvar counter: usize = 0;\n// Function to increment the counter\nfn increment() void {\n    for (0..100000) |_| {\n        counter += 1;\n    }\n}\n\npub fn main() !void {\n    const thr1 = try Thread.spawn(.{}, increment, .{});\n    const thr2 = try Thread.spawn(.{}, increment, .{});\n    thr1.join();\n    thr2.join();\n    try stdout.print(\"Couter value: {d}\\n\", .{counter});\n}\n```\n:::\n\n\n\n\n```\nCouter value: 117254\n```\n\n\nWhy this is happening? The answer is: because this program contains a data race problem.\nThis program would print the correct number 200000 if and only if the first thread finishes\nits tasks before the second thread starts to execute. But that is very unlikely to happen.\nBecause the process of creating the thread is too fast, and therefore, both threads start to execute roughly\nat the same time. If you change this code to add some nanoseconds of sleep between the first and the second calls to `spawn()`,\nyou will increase the chances of the program producing the \"correct result\".\n\nSo the data race problem happens because both threads are reading and writing to the same\nmemory location at roughly the same time. In this example, each thread is essentially performing\nthree basic operations at each iteration of the for loop, which are:\n\n1. reading the current value of `count`.\n1. incrementing this value by 1.\n1. writing the result back into `count`.\n\nIdeally, a thread B should read the value of `count`, only after the other thread A has finished\nwriting the incremented value back into the `count` object. Therefore, in the ideal scenario, which is demonstrated\nin @tbl-data-race-ideal, the threads should work in sync with each other. But the reality is that these\nthreads are out of sync, and because of that, they suffer from a data race problem, which is demonstrated\nin @tbl-data-race-not.\n\nNotice that, in the data race scenario (@tbl-data-race-not), the read performed by a thread B happens\nbefore the write operation of thread A, and that ultimately leads to wrong results at the end of the program.\nBecause when thread B reads the value of the `count` variable, thread A is still processing\nthe initial value from `count`, and has not yet written the new, incremented value back to `count`. As a result,\nthread B ends up reading the same initial (or \"old\") value from `count` instead of\nthe updated, incremented value that thread A would have written.\n\n\n::: {#tbl-data-race-ideal}\n\n| Thread 1    | Thread 2    | Integer value |\n|-------------|-------------|---------------|\n| read value  |             | 0             |\n| increment   |             | 1             |\n| write value |             | 1             |\n|             | read value  | 1             |\n|             | increment   | 2             |\n|             | write value | 2             |\n\n: An ideal scenario for two threads incrementing the same integer value\n:::\n\n::: {#tbl-data-race-not}\n\n| Thread 1    | Thread 2    | Integer value |\n|-------------|-------------|---------------|\n| read value  |             | 0             |\n|             | read value  | 0             |\n| increment   |             | 1             |\n|             | increment   | 1             |\n| write value |             | 1             |\n|             | write value | 1             |\n\n: A data race scenario when two threads are incrementing the same integer value\n:::\n\n\nIf you think about these diagrams exposed in form of tables, you will notice that they relate back to our discussion of atomic operations\nin @sec-atomic-operation. Remember, atomic operations are operations that the CPU executes\nfrom beginning to end, without interruptions from other threads or processes. So,\nthe scenario exposed in @tbl-data-race-ideal does not suffer from a data race, because\nthe operations performed by thread A are not interrupted in the middle by the operations\nfrom thread B.\n\nIf we also think about the discussion of critical section from @sec-critical-section, we can identify\nthe section that representes the critical section of the program, which is the section that is vulnerable\nto data race conditions. In this example, the critical section of the program is the line where we increment\nthe `counter` variable (`counter += 1`). So, ideally, we want to use a mutex, and lock right before this line, and then\nunlock right after this line.\n\n\n\n\n### Using mutexes in Zig\n\nNow that we know the problem that mutexes seek to solve, we can learn how to use them in Zig.\nMutexes in Zig are available through the `std.Thread.Mutex` struct from the Zig Standard Library.\nIf we take the same code from the previous example, and improve it with mutexes, to solve\nour data race problem, we get the code example below.\n\nNotice that this time, we had to alter the `increment()` function to receive a pointer to\nthe `Mutex` object as input. All that we need to do, to make this program safe against\ndata race problems, is to call the `lock()` method at the beginning of\nthe critical section, and then, call `unlock()` at the end of the critical section.\nNotice that the output of this program is now the correct number of 200000.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Thread = std.Thread;\nconst Mutex = std.Thread.Mutex;\nvar counter: usize = 0;\nfn increment(mutex: *Mutex) void {\n    for (0..100000) |_| {\n        mutex.lock();\n        counter += 1;\n        mutex.unlock();\n    }\n}\n\npub fn main() !void {\n    var mutex: Mutex = .{};\n    const thr1 = try Thread.spawn(.{}, increment, .{&mutex});\n    const thr2 = try Thread.spawn(.{}, increment, .{&mutex});\n    thr1.join();\n    thr2.join();\n    try stdout.print(\"Couter value: {d}\\n\", .{counter});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nCouter value: 200000\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n## Read/Write locks\n\nMutexes are normally used when it's not always safe for two or more threads running the same\npiece of code at the same time. In contrast, read/write locks are normally used in situations\nwhere you have a mixture of scenarios, i.e., there are some pieces of the codebase that are safe\nto run in parallel, and other pieces that are not safe.\n\nFor example, suppose that you have multiple threads that uses the same shared file in the filesystem to store some configurations, or\nstatistics. If two or more threads try to read the data from this same file at the same time, nothing bad happens.\nSo this part of the codebase is perfectly safe to be executed in parallel, with multiple threads reading the same file at the same time.\n\nHowever, if two or more threads try to write data into this same file at the same time, then we cause some race condition\nproblems. So this other part of the codebase is not safe to be executed in parallel.\nMore specifically, a thread might end up writing data in the middle of the data written by the other thread.\nThis process of two or more threads writing to the same location might lead to data corruption.\nThis specific situation is usually called a *torn write*.\n\nThus, what we can extract from this example is that there are certain types of operations that cause\na race condition, but there are also other types of operations that do not cause a race condition problem.\nYou could also say that there are types of operations that are susceptible to race condition problems,\nand there are other types of operations that are not.\n\nA read/write lock is a type of lock that acknowledges the existence of this specific scenario, and you can\nuse this type of lock to control which parts of the codebase are safe to run in parallel and which parts are not.\n\n\n\n### Exclusive lock vs shared lock\n\nTherefore, a read/write lock is a little different from a mutex. Because a mutex is always an *exclusive lock*, meaning that, only\none thread is allowed to execute at all times. With an exclusive lock, the other threads are always \"excluded\",\ni.e., they are always blocked from executing. But in a read/write lock, the other threads might be authorized\nto run at the same time, depending on the type of lock that they acquire.\n\nWe have two types of locks in a read/write lock, which are: an exclusive lock and a shared lock. An exclusive lock works exactly the same\nas a mutex, while a shared lock is a lock that does not block the other threads from running at the same time.\nIn the `pthreads` C library, read/write locks are available through the `pthread_rwlock_t` C struct. With\nthis C struct, you can create:\n\n- a \"write lock\", which corresponds to an exclusive lock.\n- a \"read lock\", which corresponds to a shared lock.\n\nThe terminology might be a little different compared to Zig. But the meaning is still the same.\nTherefore, just remember this relationship, write locks are exclusive locks, while read locks are shared locks.\n\nWhen a thread tries to acquire a read lock (i.e., a shared lock), this thread gets the shared lock\nif and only if another thread does not currently hold a write lock (i.e., an exclusive lock), and also\nif there are no other threads already in the queue,\nwaiting for their turn to acquire a write lock. In other words, the thread in the queue has attempted\nto get a write lock earlier, but this thread was blocked\nbecause there was another thread running that already had a write lock. As a consequence, this thread is in the queue to get a write lock,\nand it's currently waiting for the other thread with a write lock to finish its execution.\n\nWhen a thread tries to acquire a read lock, but it fails in acquiring this read lock, either because there is\na thread with a write lock already running, or because there is a thread in the queue to get a write lock,\nthe execution of this thread is instantly blocked, i.e., paused. This thread will indefinitely attempt to get the\nread lock, and its execution will be unblocked (or unpaused) only after this thread successfully acquires the read lock.\n\nIf you think deeply about this dynamic between read locks versus write locks, you might notice that a read lock is basically a safety mechanism.\nMore specifically, it's a way for us to\nallow a particular thread to run together with the other threads only when it's safe to. In other words, if there is currently\na thread with a write lock running, then it's very likely not safe for the thread that is trying to acquire the read lock to run now.\nAs a consequence, the read lock protects this thread from running into dangerous waters, and patiently waits for the\n\"write lock\" thread to finishes its tasks before it continues.\n\nOn the other hand, if there are only \"read lock\" (i.e., \"shared lock\") threads currently running\n(i.e., not a single \"write lock\" thread currently exists), then it\nis perfectly safe for this thread that is acquiring the read lock to run in parallel with the other\nthreads. As a result, the read lock just\nallows for this thread to run together with the other threads.\n\nThus, by using read locks (shared locks) in conjunction with write locks (exclusive locks), we can control which regions or sections\nof our multithreaded code is safe to have parallelism, and which sections are not safe to have parallelism.\n\n\n\n\n\n### Using read/write locks in Zig\n\nThe Zig Standard Library supports read/write locks through the `std.Thread.RwLock` module.\nIf you want a particular thread to acquire a shared lock (i.e., a read lock), you should\ncall the `lockShared()` method from the `RwLock` object. But, if you want this thread\nto acquire an exclusive lock (i.e., a write lock) instead, then you should call the\n`lock()` method from the `RwLock` object.\n\nAs with mutexes, we also have to unlock the shared or exclusive locks that we acquire through a read/write lock object,\nonce we are at the end of our \"critical section\". If you have acquired an exclusive lock, then, you unlock\nthis exclusive lock by calling the `unlock()` method from the read/write lock object. In contrast,\nif you have acquired a shared lock instead, then, call `unlockShared()` to unlock this shared lock.\n\nAs a simple example, the snippet below creates three separate threads responsible for reading the\ncurrent value in a `counter` object, and it also creates another thread responsible for writing\nnew data into the `counter` object (incrementing it, more specifically).\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar counter: u32 = 0;\nfn reader(lock: *RwLock) !void {\n    while (true) {\n        lock.lockShared();\n        const v: u32 = counter;\n        try stdout.print(\"{d}\", .{v});\n        lock.unlockShared();\n        std.time.sleep(2 * std.time.ns_per_s);\n    }\n}\nfn writer(lock: *RwLock) void {\n    while (true) {\n        lock.lock();\n        counter += 1;\n        lock.unlock();\n        std.time.sleep(2 * std.time.ns_per_s);\n    }\n}\n\npub fn main() !void {\n    var lock: RwLock = .{};\n    const thr1 = try Thread.spawn(.{}, reader, .{&lock});\n    const thr2 = try Thread.spawn(.{}, reader, .{&lock});\n    const thr3 = try Thread.spawn(.{}, reader, .{&lock});\n    const wthread = try Thread.spawn(.{}, writer, .{&lock});\n\n    thr1.join();\n    thr2.join();\n    thr3.join();\n    wthread.join();\n}\n```\n:::\n\n\n\n\n\n## Yielding a thread\n\nThe `Thread` struct supports yielding through the `yield()` method.\nYielding a thread means that the execution of the thread is temporarily stopped,\nand it moves to the end of the priority queue managed by the scheduler of\nyour operating system.\n\nThat is, when you yield a thread, you are essentially saying the following to your OS:\n\"Hey! Could you please stop executing this thread for now, and comeback to continue it later?\".\nYou could also interpret this yield operation as: \"Could you please deprioritize this thread,\nto focus on doing other things instead?\".\nSo this yield operation is also a way for you\nto stop a particular thread, so that you can work and prioritize other threads instead.\n\nIt's important to say that, yielding a thread is a \"not so common\" thread operation these days.\nIn other words, not many programmers use yielding in production, simply because it's hard to use\nthis operation and make it work properly, and also, there\nare better alternatives. Most programmers prefer to use `join()` instead.\nIn fact, most of the time, when you see someone using this \"yield\" operation in some code example,\nthey are usually doing so to help debug race conditions in their applications.\nThat is, this \"yield\" operation is mostly used as a debug tool nowadays.\n\nAnyway, if you want to yield a thread, just call the `yield()` method from it, like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nthread.yield();\n```\n:::\n\n\n\n\n\n\n\n\n\n## Common problems in threads\n\n\n\n### Deadlocks\n\nA deadlock occurs when two or more threads are blocked forever,\nwaiting for each other to release a resource. This usually happens when multiple locks are involved,\nand the order of acquiring them is not well managed.\n\nThe code example below demonstrates a deadlock situation. We have two different threads that execute\ntwo different functions (`work1()` and `work2()`) in this example. And we also have two separate\nmutexes. If you compile and run this code example, you will notice that the program just runs indefinitely,\nwithout ending.\n\nWhen we look into the first thread, which executes the `work1()` function, we can\nnotice that this function acquires the `mut1` lock first. Because this is the first operation\nthat is executed inside this thread, which is the first thread created in the program.\nAfter that, the function sleeps for 1 second, to\nsimulate some type of work, and then, the function tries to acquire the `mut2` lock.\n\nOn the other hand, when we look into the second thread, which executes the `work2()` function,\nwe can see that this function acquires the `mut2` lock first. Because when this thread gets created and it tries\nto acquire this `mut2` lock, the first thread is still sleeping on that \"sleep 1 second\" line.\nAfter acquiring `mut2`, the `work2()` function also sleeps for 1 second, to\nsimulate some type of work, and then the function tries to acquire the `mut1` lock.\n\nThis creates a deadlock situation, because after the \"sleep for 1 second\" line in both threads,\nthread 1 is trying to acquire the `mut2` lock, but this lock is currently being used by thread 2.\nHowever, at this moment, thread 2 is also trying to acquire the `mut1` lock, which is currently\nbeing used by thread 1. Therefore, both threads end up waiting for ever. Waiting for their peer to\nfree the lock that they want to acquire.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar mut1: Mutex = .{}; var mut2: Mutex = .{};\nfn work1() !void {\n    mut1.lock();\n    std.time.sleep(1 * std.time.ns_per_s);\n    mut2.lock();\n    _ = try stdout.write(\"Doing some work 1\\n\");\n    mut2.unlock(); mut1.unlock();\n}\n\nfn work2() !void {\n    mut2.lock();\n    std.time.sleep(1 * std.time.ns_per_s);\n    mut1.lock();\n    _ = try stdout.write(\"Doing some work 1\\n\");\n    mut1.unlock(); mut2.unlock();\n}\n\npub fn main() !void {\n    const thr1 = try Thread.spawn(.{}, work1, .{});\n    const thr2 = try Thread.spawn(.{}, work2, .{});\n    thr1.join();\n    thr2.join();\n}\n```\n:::\n\n\n\n\n\n### Not calling `join()` or `detach()` {#sec-not-call-join-detach}\n\nWhen you do not call either `join()` or `detach()` over a thread, then this thread becomes a \"zombie thread\",\nbecause it does not have a clear \"return point\".\nYou could also interpret this as: \"nobody is properly responsible for managing the thread\".\nWhen we don't establish if a thread is either *joinable* or *detached*,\nnobody becomes responsible for dealing with the return value of this thread, and also,\nnobody becomes responsible for clearing (or freeing) the resources associated with this thread.\n\nYou don't want to be in this situation, so remember to always use `join()` or `detach()`\non the threads that you create. When you don't use one of these methods, we lose\ncontrol over the thread, and its resources are never freed\n(i.e., you have leaked resources in the system).\n\n\n### Cancelling or killing a particular thread\n\nWhen we think about the `pthreads` C library, there is a possible way to asynchronously kill or cancel\na thread, which is by sending a `SIGTERM` signal to the thread through the `pthread_kill()` function.\nBut canceling a thread like this is bad. It's dangerously bad. As a consequence, the Zig implementation\nof threads does not have a similar function, or, a similar way to asynchronously cancel or kill\na thread.\n\nTherefore, if you want to cancel a thread in the middle of its execution in Zig,\nthen one good strategy that you can take is to use control flow in conjunction with `join()`.\nMore specifically, you can design your thread around a while loop that is constantly\nchecking if the thread should continue running.\nIf it's time to cancel the thread, we could make the while loop break, and join the thread with the main thread\nby calling `join()`.\n\nThe code example below demonstrates to some extent this strategy.\nHere, we are using control flow to break the while loop, and exit the thread earlier than\nwhat we have initially planned to. This example also demonstrates how can we use\natomic objects in Zig with the `Value()` generic function that we have mentioned in @sec-atomic-operation.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Thread = std.Thread;\nconst stdout = std.io.getStdOut().writer();\nvar running = std.atomic.Value(bool).init(true);\nvar counter: u64 = 0;\nfn do_more_work() void {\n    std.time.sleep(2 * std.time.ns_per_s);\n}\nfn work() !void {\n    while (running.load(.monotonic)) {\n        for (0..10000) |_| { counter += 1; }\n        if (counter < 15000) {\n            _ = try stdout.write(\n                \"Time to cancel the thread.\\n\"\n            );\n            running.store(false, .monotonic);\n        } else {\n            _ = try stdout.write(\"Time to do more work.\\n\");\n            do_more_work();\n            running.store(false, .monotonic);\n        }\n    }\n}\n\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, work, .{});\n    thread.join();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nTime to cancel the thread.\n```\n\n\n:::\n:::\n",
-    "supporting": [
-      "14-threads_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n# Introducing threads and parallelism in Zig {#sec-thread}\n\nThreads are available in Zig through the `Thread` struct from the Zig Standard Library.\nThis struct represents a kernel thread, and it follows a POSIX Thread pattern,\nmeaning that, it works similarly to a thread from the `pthread` C library, which is usually available on any distribution\nof the GNU C Compiler (`gcc`). If you are not familiar with threads, I will give you some theory behind it first, shall we?\n\n\n## What are threads? {#sec-what-thread}\n\nA thread is basically a separate context of execution.\nWe use threads to introduce parallelism into our program,\nwhich in most cases, makes the program run faster, because we have multiple tasks\nbeing performed at the same time, parallel to each other.\n\nPrograms are normally single-threaded by default. Which means that each program\nusually runs on a single thread, or, a single context of execution. When we have only one thread running, we have no\nparallelism. And when we don't have parallelism, the commands are executed sequentially, that is,\nonly one command is executed at a time, one after another. By creating multiple threads inside our program,\nwe start to execute multiple commands at the same time.\n\nPrograms that create multiple threads are very common in the wild. Because many different types\nof applications are well suited for parallelism. Good examples are video and photo-editing applications\n(e.g. Adobe Photoshop or DaVinci Resolve), games (e.g. The Witcher 3), and also web browsers\n(e.g. Google Chrome, Firefox, Microsoft Edge, etc).\nFor example, in web browsers, threads are normally used to implement tabs.\nThe tabs in a web browsers usually run as separate threads in the main process of\nthe web browser. That is, each new tab that you open in your web browser\nusually runs on a separate thread of execution.\n\nBy running each tab in a separate thread, we allow all open tabs in the browser to run at the same time,\nand independently from each other. For example, you might have YouTube or Spotify currently open in\na tab, and you are listening to some podcast in that tab while at the same time\nworking in another tab, writing an essay on Google Docs. Even if you are not looking\ninto the YouTube tab, you can still hear the podcast only because this YouTube tab is running in parallel\nwith the other tab where Google Docs is running.\n\nWithout threads, the other alternative would be to run each tab as a completely separate\nprocess in your computer. But that would be a bad choice because just a few tabs would already consume\ntoo much power and resources from your computer. In other words, it's very expensive to create a completely new process,\ncompared to creating a new thread of execution. Also, the chances of you experiencing lag and overhead\nwhile using the browser would be significant. Threads are faster to create, and they also consume\nmuch, much less resources from the computer, especially because they share some resources\nwith the main process.\n\nTherefore, it's the use of threads in modern web browsers that allow you to hear the podcast\nat the same time while you are writing something on Google Docs.\nWithout threads, a web browser would probably be limited to just one single tab.\n\nThreads are also well-suited for anything that involves serving requests or orders.\nBecause serving a request takes time, and usually involves a lot of \"waiting time\".\nIn other words, we spend a lot of time in idle, waiting for something to complete.\nFor example, consider a restaurant. Serving orders in a restaurant usually involves\nthe following steps:\n\n1. receive order from the client.\n1. pass the order to the kitchen, and wait for the food to be cooked.\n1. start cooking the food in the kitchen.\n1. when the food is fully cooked deliver this food to the client.\n\nIf you think about the bullet points above, you will notice that one big moment of waiting time\nis present in this whole process, which is while the food is being cooked\ninside the kitchen. While the food is being prepped, both the waiter and the client\nthemselves are waiting for the food to be ready and delivered.\n\nIf we write a program to represent this restaurant, more specifically, a single-threaded program, then\nthis program would be very inefficient. Because the program would stay in idle, waiting for a considerable amount\nof time on the \"check if food is ready\" step. Consider the code snippet exposed below that could\npotentially represent such program.\n\nThe problem with this program is the while loop. This program will spend a lot of time\nwaiting on the while loop, doing nothing more than just checking if the food is ready.\nThis is a waste of time. Instead of waiting for something to happen, the waiter\ncould just send the order to the kitchen, and just move on, and continue with receiving\nmore orders from other clients, and sending more orders to the kitchen, instead\nof doing nothing and waiting for the food to be ready.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst order = Order.init(\"Pizza Margherita\", n = 1);\nconst waiter = Waiter.init();\nwaiter.receive_order(order);\nwaiter.ask_kitchen_to_cook();\nvar food_not_ready = true;\nwhile (food_not_ready) {\n    food_not_ready = waiter.is_food_ready();\n}\nconst food = waiter.get_food_from_kitchen();\nwaiter.send_food_to_client(food);\n```\n:::\n\n\nThis is why threads would be a great fit for this program. We could use threads\nto free the waiters from their \"waiting duties\", so they can go on with their\nother tasks, and receive more orders. Take a look at the next example, where I have re-written the above\nprogram into a different program that uses threads to cook and deliver the orders.\n\nYou can see in this program that when a waiter receives a new order\nfrom a client, this waiter executes the `send_order()` function.\nThe only thing that this function does is to create a new thread\nand detaches it. Since creating a thread is a very fast operation,\nthis `send_order()` function returns almost immediately,\nso the waiter spends almost no time worrying about the order, and just\nmove on and tries to get the next order from the clients.\n\nInside the new thread created, the order gets cooked by a chef, and when the\nfood is ready, it's delivered to the client's table.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn cook_and_deliver_order(order: *Order) void {\n    const chef = Chef.init();\n    const food = chef.cook(order.*);\n    chef.deliver_food(food);\n}\nfn send_order(order: Order) void {\n    const cook_thread = Thread.spawn(\n        .{}, cook_and_deliver_order, .{&order}\n    );\n    cook_thread.detach();\n}\n\nconst waiter = Waiter.init();\nwhile (true) {\n    const order = waiter.get_new_order();\n    if (order) {\n        send_order(order);\n    }\n}\n```\n:::\n\n\n\n\n## Threads versus processes\n\nWhen we run a program, this program is executed as a *process* in the operating system.\nThis is a one to one relationship, each program or application that you execute\nis a separate process in the operating system. But each program, or each process,\ncan create and contain multiple threads inside of it. Therefore,\nprocesses and threads have a one to many relationship.\n\nThis also means that every thread that we create is always associated with a particular process in our computer.\nIn other words, a thread is always a subset (or a children) of an existing process.\nAll threads share some of the resources associated with the process from which they were created.\nAnd because threads share resources with the process, they are very good for making communication\nbetween tasks easier.\n\nFor example, suppose that you were developing a big and complex application\nthat would be much simpler if you could split it in two, and make these two separate pieces talk\nwith each other. Some programmers opt to effectively write these two pieces of the codebase as two\ncompletely separate programs, and then, they use IPC (*inter-process communication*) to make these\ntwo separate programs/processes talk to each other, and make them work together.\n\nHowever, some programmers find IPC hard to deal with, and, as consequence,\nthey prefer to write one piece of the codebase as the \"main part of the program\",\nor, as the part of the code that runs as the process in the operating system,\nwhile the other piece of the codebase is written as a task to be executed in\na new thread. A process and a thread can easily comunicate with each other\nthrough both control flow, and also, through data, because they share and have\naccess to the same standard file descriptors (`stdout`, `stdin`, `stderr`), and also to the\nsame memory space on the heap and global data section.\n\n\nIn more details, each thread that you create have a separate stack frame reserved just for that thread,\nwhich essentially means that each local object that you create inside this thread, is local to that\nthread, i.e., the other threads cannot see this local object. Unless this object that you have created\nis an object that lives on the heap. In other words, if the memory associated with this object\nis on the heap, then, the other threads can potentially access this object.\n\nTherefore, objects that are stored in the stack are local to the thread where they were created.\nBut objects that are stored on the heap are potentially accessible to other threads. All of this means that,\neach thread has its own separate stack frame, but, at the same time, all threads share\nthe same heap, the same standard file descriptors (which means that they share the same `stdout`, `stdin`, `stderr`),\nand the same global data section in the program.\n\n\n\n## Creating a thread\n\nWe create new threads in Zig by first importing the `Thread` struct into\nour current Zig module and then calling the `spawn()` method of this struct,\nwhich creates (or \"spawns\") a new thread of execution from our current process.\nThis method has three arguments, which are, respectively:\n\n1. a `SpawnConfig` object, which contains configurations for the spawn process.\n1. the name of the function that is going to be executed (or that is going to be \"called\") inside this new thread.\n1. a list of arguments (or inputs) to be passed to the function provided in the second argument.\n\nWith these three arguments, you can control how the thread gets created, and also, specify which\nwork (or \"tasks\") will be performed inside this new thread. A thread is just a separate context of execution,\nand we usually create new threads in our code because we want to perform some work inside this\nnew context of execution. And we specify which exact work, or which exact steps that are going to be\nperformed inside this context by providing the name of a function as the second argument of the `spawn()` method.\n\nThus, when this new thread gets created, this function that you provided as input to the `spawn()`\nmethod gets called, or gets executed inside this new thread. You can control the\narguments, or the inputs that are passed to this function when it gets called by providing\na list of arguments (or a list of inputs) in the third argument of the `spawn()` method.\nThese arguments are passed to the function in the same order that they are\nprovided to `spawn()`.\n\nFurthermore, the `SpawnConfig` is a struct object with only two possible fields, or, two possible members, that you\ncan set to tailor the spawn behaviour. These fields are:\n\n- `stack_size`: you can provide a `usize` value to specify the size (in bytes) of the thread's stack frame. By default, this value is: $16 \\times 1024 \\times 1024$.\n- `allocator`: you can provide an allocator object to be used when allocating memory for the thread.\n\nTo use one of these two fields (or \"configs\"), you just have to create a new object of type `SpawnConfig`,\nand provide this object as input to the `spawn()` method. But, if you are not interested in using\none of these configs, and you are ok with using just the defaults, you can just provide an anonymous\nstruct literal (`.{}`) in place of this `SpawnConfig` argument.\n\nAs our first, and very simple example, consider the code exposed below.\nInside the same program, you can create multiple threads of execution if you want to.\nBut, in this first example, we are creating just a single thread of execution, because\nwe call `spawn()` only once.\n\nAlso, notice in this example that we are executing the function `do_some_work()`\ninside the new thread. Since this function receives no inputs, because it has\nno arguments, we have passed an empty list in this instance, or more precisely,\nan empty, anonymous struct (`.{}`) in the third argument of `spawn()`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Thread = std.Thread;\nfn do_some_work() !void {\n    _ = try stdout.write(\"Starting the work.\\n\");\n    std.time.sleep(100 * std.time.ns_per_ms);\n    _ = try stdout.write(\"Finishing the work.\\n\");\n}\n\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, do_some_work, .{});\n    thread.join();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nStarting the work.Finishing the work.\n```\n\n\n:::\n:::\n\n\nNotice the use of `try` when calling the `spawn()` method. This means\nthat this method can return an error in some circumstances. One circumstance\nin particular is when you attempt to create a new thread, when you have already\ncreated too much (i.e., you have exceeded the quota of concurrent threads in your system).\n\nBut, if the new thread is successfully created, the `spawn()` method returns a handler\nobject (which is just an object of type `Thread`) to this new thread. You can use\nthis handler object to effectively control all aspects of the thread.\n\nWhen the thread gets created, the function that you provided as input to `spawn()`\ngets invoked (i.e., gets called) to start the execution on this new thread.\nIn other words, every time you call `spawn()`, not only is a new thread created,\nbut the \"start work button\" of this thread is also automatically pressed.\nSo the work being performed in this thread starts as soon as the thread is created.\nThis is similar to how `pthread_create()` from the `pthreads` library in C works,\nwhich also starts the execution as soon as the thread is created.\n\n\n## Returning from a thread\n\nWe have learned in the previous section that the execution of the thread starts as soon as\nthe thread is created. Now, we will learn how to \"join\" or \"detach\" a thread in Zig.\n\"Join\" and \"detach\" are operations that control how the thread returns to\nthe main thread, or to the main process in our program.\n\nWe perform these operations by using the methods `join()` and `detach()` from the thread handler object.\nEvery thread that you create can be marked as either *joinable* or *detached* [@linux_pthread_create].\nYou can turn a thread into a *detached* thread by calling the `detach()` method\nfrom the thread handler object. But if you call the `join()` method instead, then this thread\nbecomes a *joinable* thread.\n\nA thread cannot be both *joinable* and *detached*. Which in general means\nthat you cannot call both `join()` and `detach()` on the same thread.\nBut a thread must be one of the two, meaning that, you should always call\neither `join()` or `detach()` over a thread. If you don't call\none of these two methods over your thread, you introduce undefined behaviour into your program,\nwhich is described in @sec-not-call-join-detach.\n\nNow, let's describe what each of these two methods do to your thread.\n\n\n### Joining a thread\n\nWhen you join a thread, you are essentially saying: \"Hey! Could you please wait for the thread to finish,\nbefore you continue with your execution?\". For example, if we come back to our first and simplest example\nof a thread in Zig, we created a single thread inside the `main()` function of our program\nand just called `join()` on this thread at the end. This section of the code example is reproduced below.\n\nBecause we are joining this new thread inside the `main()`'s scope, it means that the\nexecution of the `main()` function is temporarily stopped, to wait for the execution of the thread\nto finish. That is, the execution of `main()` stops temporarily at the line where `join()` gets called,\nand it will continue only after the thread has finished its tasks.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, do_some_work, .{});\n    thread.join();\n}\n```\n:::\n\n\nBecause we have joined this new thread inside the `main()` scope, we have a\nguarantee that this new thread will finish before the end of the execution of `main()`.\nBecause it's guaranteed that `main()` will wait for the thread to finish its tasks.\n\nIn the example above, there are no more expressions after the `join()` call. We just have the end\nof the `main()`'s scope, and, therefore, the execution of our program just ends after the thread finishes its tasks,\nsince there is nothing more to do. But what if we had more stuff to do after the join call?\n\nTo demonstrate this other possibility, consider the next example exposed\nbelow. Here, we create a `print_id()` function, that just receives an id\nas input, and prints it to `stdout`. In this example, we are creating two\nnew threads, one after another. Then, we join the first thread, then,\nwe wait for two whole seconds, then, at last, we join the second thread.\n\nThe idea behind this example is that the last `join()` call is executed\nonly after the first thread finishes its task (i.e., the first `join()` call),\nand the two-second delay. If you compile and run this\nexample, you will notice that most messages are quickly printed to `stdout`,\ni.e., they appear almost instantly on your screen.\nHowever, the last message (\"Joining thread 2\") takes around 2 seconds to appear\non the screen.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_id(id: *const u8) !void {\n    try stdout.print(\"Thread ID: {d}\\n\", .{id.*});\n}\n\npub fn main() !void {\n    const id1: u8 = 1;\n    const id2: u8 = 2;\n    const thread1 = try Thread.spawn(.{}, print_id, .{&id1});\n    const thread2 = try Thread.spawn(.{}, print_id, .{&id2});\n\n    _ = try stdout.write(\"Joining thread 1\\n\");\n    thread1.join();\n    std.time.sleep(2 * std.time.ns_per_s);\n    _ = try stdout.write(\"Joining thread 2\\n\");\n    thread2.join();\n}\n```\n:::\n\n\n```\nThread ID: Joining thread 1\n1\nThread ID: 2\nJoining thread 2\n```\n\nThis demonstrates that both threads finish their work (i.e., printing the IDs)\nvery fast, before the two seconds of delay end. Because of that, the last `join()` call\nreturns pretty much instantly. Because when this last `join()` call happens, the second\nthread has already finished its task.\n\nNow, if you compile and run this example, you will also notice that, in some cases,\nthe messages intertwine with each other. In other words, you might see\nthe message \"Joining thread 1\" inserted in the middle of the message \"Thread 1\",\nor vice-versa. This happens because:\n\n- the threads are executing basically at the same time as the main process of the program (i.e., the `main()` function).\n- the threads share the same `stdout` from the main process of the program, which means that the messages that the threads produce are sent to exact same place as the messages produced by the main process.\n\nBoth of these points were described previously in @sec-what-thread.\nSo the messages might get intertwined because they are being produced and\nsent to the same `stdout` roughly at the same time.\nAnyway, when you call `join()` over a thread, the current process will wait\nfor the thread to finish before it continues, and, when the thread finishes its\ntask, the resources associated with this thread are automatically freed, and\nthe current process continues with its execution.\n\n\n### Detaching a thread\n\nWhen you detach a thread, the resources associated with this thread are automatically\nreleased back to the system, without the need for another thread to join with this terminated thread.\n\nIn other words, when you call `detach()` on a thread it's like when your children become adults,\ni.e., they become independent from you. A detached thread frees itself, and when this thread finishes its\ntasks, it does not report the results back to you. Thus, you normally mark a thread as *detached*\nwhen you don't need to use the return value of the thread, or when you don't care about\nwhen exactly the thread finishes its job, i.e., the thread solves everything by itself.\n\nTake the code example below. We create a new thread, detach it, and then, we just\nprint a final message before we end our program. We use the same `print_id()`\nfunction that we have used over the previous examples.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_id(id: *const u8) !void {\n    try stdout.print(\"Thread ID: {d}\\n\", .{id.*});\n}\n\npub fn main() !void {\n    const id1: u8 = 1;\n    const thread1 = try Thread.spawn(.{}, print_id, .{&id1});\n    thread1.detach();\n    _ = try stdout.write(\"Finish main\\n\");\n}\n```\n:::\n\n\n```\nFinish main\n```\n\nNow, if you look closely at the output of this code example, you will notice\nthat only the final message in main was printed to the console. The message\nthat was supposed to be printed by `print_id()` did not appear in the console.\nWhy? It's because the main process of our program has finished first,\nbefore the thread was able to say anything.\n\nAnd that is perfectly ok behaviour, because the thread was detached, so it was\nable to free itself, without the need to wait for the main process.\nIf you ask main to sleep (or \"wait\") for some extra nanoseconds, before it ends, you will likely\nsee the message printed by `print_id()`, because you give enough time for the thread to\nfinish before the main process ends.\n\n\n## Thread pools\n\nThread pools is a very popular programming pattern, which is used especially on servers and daemons processes.\nA thread pool is just a set of threads, or a \"pool\" of threads. Many programmers like to use this pattern because it makes\nit easier to manage and use multiple threads in your program, instead of manually creating the threads when you need them.\n\nAlso, using thread pools might increase performance as well in your program,\nespecially if your program is constantly creating threads to perform short-lived tasks.\nIn such instance, a thread pool might cause an increase in performance because you do not have be constantly\ncreating and destroying threads all the time, so you don't face a lot of the overhead involved\nin this constant process of creating and destroying threads.\n\nThe main idea behind a thread pool is to have a set of threads already created and ready to perform\ntasks at all times. You create a set of threads at the moment that your program starts, and keep\nthese threads alive while your program runs. Each of these threads will be either performing a task, or\nwaiting for a task to be assigned.\nEvery time a new task emerges in your program, this task is added to a \"queue of tasks\",\nand the moment that a thread becomes available and ready to perform a new task,\nthis thread takes the next task from the \"queue of tasks\", and it simply performs the task.\n\nThe Zig Standard Library offers a thread pool implementation on the `std.Thread.Pool` struct.\nYou create a new instance of a `Pool` object by providing a `Pool.Options` object\nas input to the `init()` method of this struct. A `Pool.Options` object, is a struct object that contains\nconfigurations for the pool of threads. The most important settings in this struct object are\nthe members `n_jobs` and `allocator`. As the name suggests, the member `allocator` should receive an allocator object,\nwhile the member `n_jobs` specifies the number of threads to be created and maintained in this pool.\n\nConsider the example exposed below, that demonstrates how can we create a new thread pool object.\nHere, we create a `Pool.Options` object that contains\na general purpose allocator object, and also, the `n_jobs` member was set to 4, which\nmeans that the thread pool will create and use 4 threads.\n\nAlso notice that the `pool` object was initially set to `undefined`. This allow us\nto initially declare the thread pool object, but not properly instantiate the\nunderlying memory of the object. You have to initially declare your thread pool object\nby using `undefined` like this, because the `init()` method of `Pool` needs\nto have an initial pointer to properly instantiate the object.\n\nSo, just remember to create your thread pool object by using `undefined`, and then,\nafter that, you call the `init()` method over the object.\nYou should also not forget to call the `deinit()` method over the thread pool\nobject, once you are done with it, to release the resources allocated for the thread pool. Otherwise, you will\nhave a memory leak in your program.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Pool = std.Thread.Pool;\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    const opt = Pool.Options{\n        .n_jobs = 4,\n        .allocator = allocator,\n    };\n    var pool: Pool = undefined;\n    try pool.init(opt);\n    defer pool.deinit();\n}\n```\n:::\n\n\nNow that we know how to create `Pool` objects, we have\nto understand how to assign tasks to be executed by the threads in this pool object.\nTo assign a task to be performed by a thread, we need to call the `spawn()` method\nfrom the thread pool object.\n\nThis `spawn()` method works identical to the `spawn()` method from the\n`Thread` object. The method has almost the same arguments as the previous one,\nmore precisely, we don't have to provide a `SpawnConfig` object in this case.\nBut instead of creating a new thread, this `spawn()` method from\nthe thread pool object just registers a new task in the internal \"queue of tasks\" to be performed,\nand any available thread in the pool will get this task, and it will simply perform the task.\n\nIn the example below, we are using our previous `print_id()` function once again.\nBut you may notice that the `print_id()` function is a little different this time,\nbecause now we are using `catch` instead of `try` in the `print()` call.\nCurrently, the `Pool` struct only supports functions that don't return errors\nas tasks. Thus, when assigning tasks to threads in a thread pool, it is essential to use functions\nthat don't return errors. That is why we are using `catch` here, so that the\n`print_id()` function don't return an error.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn print_id(id: *const u8) void {\n    _ = stdout.print(\"Thread ID: {d}\\n\", .{id.*})\n        catch void;\n}\nconst id1: u8 = 1;\nconst id2: u8 = 2;\ntry pool.spawn(print_id, .{&id1});\ntry pool.spawn(print_id, .{&id2});\n```\n:::\n\n\nThis limitation should probably not exist, and, in fact, it's already on the radar of the\nZig team to fix this issue, and it's being tracked in an [open issue](https://github.com/ziglang/zig/issues/18810)[^issue].\nSo, if you do need to provide a function that might return an error as the task\nto be performed by the threads in the thread pool, then, you are either limited to:\n\n- implementing your own thread pool that does not have this limitation.\n- wait for the Zig team to actually fix this issue.\n\n[^issue]: <https://github.com/ziglang/zig/issues/18810>\n\n\n\n\n## Mutexes\n\nMutexes are a classic component of every thread library. In essence, a mutex is a *Mutually Exclusive Flag*, and this flag\nacts like a type of \"lock\", or as a gate keeper to a particular section of your code. Mutexes are related to thread synchronization,\nmore specifically, they prevent you from having some classic race conditions in your program,\nand, therefore, major bugs and undefined behaviour that are usually difficult to track and understand.\n\nThe main idea behind a mutex is to help us to control the execution of a particular section of the code, and to\nprevent two or more threads from executing this particular section of the code at the same time.\nMany programmers like to compare a mutex to a bathroom door (which typically has a lock).\nWhen a thread locks its own mutex object, it's like if the bathroom door was locked.\nTherefore, other people (in this case, other threads) who want to use the same bathroom at the same time\nmust be patient and simply wait for the current occupant (or thread) to unlock the door and get out of the bathroom.\n\nSome other programmers also like to explain mutexes by using the analogy of \"each person will have their turn to speak\".\nThis is the analogy used in the [*Multithreading Code* video from the Computerphile project](https://www.youtube.com/watch?v=7ENFeb-J75k&ab_channel=Computerphile)[^computerphile].\nImagine if you are in a conversation circle. There is a moderator in this circle, which is the person that decides who\nhas the right to speak at that particular moment. The moderator gives a green card (or some sort of an authorization card) to the person that\nis going to speak, and, as a result, everyone else must be silent and hear this person that has the green card.\nWhen the person finishes talking, they give the green card back to the moderator, and the moderator decides\nwho is going to talk next, and delivers the green card to that person. And the cycle goes on like this.\n\n[^computerphile]: <https://www.youtube.com/watch?v=7ENFeb-J75k&ab_channel=Computerphile>\n\n\nA mutex acts like the moderator in this conversation circle. The mutex authorizes one single thread to execute a specific section of the code,\nand it also blocks the other threads from executing this same section of the code. If these other threads want to execute this same\npiece of the code, they are forced to wait for the the authorized thread to finish first.\nWhen the authorized thread finishes executing this code, the mutex authorizes the next thread to execute this code,\nwhile the remaining threads remain blocked. Therefore, a mutex is like a moderator that does a \"each\nthread will have their turn to execute this section of the code\" type of control.\n\n\nMutexes are especially used to prevent data race problems from happening. A data race problem happens when two or more threads\nare trying to read from or write to the same shared object at the same time.\nSo, when you have an object that is shared will all threads, and, you want to avoid two or more threads from\naccessing this same object at the same time, you can use a mutex to lock the part of the code that access this specific object.\nWhen a thread tries to run this code that is locked by a mutex, this thread stops its execution,\nand patiently waits for this section of the codebase to be unlocked to continue.\n\nNotice that mutexes are normally used to lock areas of the codebase that access/modify data that is **shared** with all threads,\ni.e., objects that are either stored in the global data section, or in the heap space of your program.\nSo mutexes are not normally used on areas of the codebase that access/modify objects that are local to the thread.\n\n\n\n### Critical section {#sec-critical-section}\n\nCritical section is a concept commonly associated with mutexes and thread synchronization.\nIn essence, a critical section is the section of the program that a thread access/modify a shared resource\n(i.e., an object, a file descriptor, something that all threads have access to). In other words,\na critical section is the section of the program where race conditions might happen, and, therefore,\nwhere undefined behaviour can be introduced into the program.\n\nWhen we use mutexes in our program, the critical section defines the area of the codebase that we want to lock.\nSo we normally lock the mutex object at the beginning of the critical section,\nand then, we unlock it at the end of the critical section.\nThe two bullet points exposed below comes from the \"Critical Section\" article from GeekFromGeeks,\nand they summarise well the role that a critical section plays in the thread synchronization problem [@geeks_critical_section].\n\n\n1. The critical section must be executed as an atomic operation, which means that once one thread or process has entered the critical section, all other threads or processes must wait until the executing thread or process exits the critical section. The purpose of synchronization mechanisms is to ensure that only one thread or process can execute the critical section at a time.\n1. The concept of a critical section is central to synchronization in computer systems, as it is necessary to ensure that multiple threads or processes can execute concurrently without interfering with each other. Various synchronization mechanisms such as semaphores, mutexes, monitors, and condition variables are used to implement critical sections and ensure that shared resources are accessed in a mutually exclusive manner.\n\n\n### Atomic operations {#sec-atomic-operation}\n\nYou will also see the term \"atomic operation\" a lot when reading about threads, race conditions and mutexes.\nIn summary, an operation is categorized as \"atomic\" when a context switch cannot occur in\nthe middle of the operation. In other words, this operation is always done from beginning to end, without interruptions\nof another process or operation in the middle of its execution phase.\n\nNot many operations today are atomic. But why do atomic operations matter here? It's because data races\n(which is a type of a race condition) cannot happen on operations that are atomic.\nSo if a particular line in your code performs an atomic operation, then this line will never\nsuffer from a data race problem. Therefore, programmers sometimes use an atomic operation\nto protect themselves from data race problems in their code.\n\nWhen you have an operation that is compiled into just one single assembly instruction, this operation might be atomic,\nbecause it's just one assembly instruction. But this is not guaranteed. This is usually true for old CPU architectures\n(such as `x86`). But nowadays, most assembly instructions in modern CPU architectures are broken down into multiple micro-tasks,\nwhich inherently makes the operation non-atomic, even if it consists of a single assembly instruction.\n\nThe Zig Standard Library offers some atomic functionality in the `std.atomic` module.\nIn this module, you will find a public and generic function called `Value()`. With this function we create an \"atomic object\", which is\na value that contains some native atomic operations, most notably, a `load()` and a `fetchAdd()` operation.\nIf you have experience with multithreading in C++, you probably have recognized this pattern. So yes, this generic\n\"atomic object\" in Zig is essentially identical to the template struct `std::atomic` from the C++ Standard Library.\nIt's important to emphasize that only primitive data types (i.e., the types presented in @sec-primitive-data-types)\nare supported by these atomic operations in Zig.\n\n\n\n\n\n### Data races and race conditions\n\nTo understand why mutexes are used, we need to understand better the problem that they seek\nto solve, which can be summarized into data race problems. A data race problem is a type of a race condition,\nwhich happens when one thread is accessing a particular memory location (i.e., a particular shared object) at the same\ntime that another thread is trying to write/save new data into this same memory location (i.e., the same shared object).\n\nWe can simply define a race condition as any type of bug in your program that is based\non a \"who gets there first\" problem. A data race problem is a type of a race condition, because it occurs when two or more parties\nare trying to read and write into the same memory location at the same time, and, therefore, the end result of this operation\ndepends completely on who gets to this memory location first.\nAs a consequence, a program that has a data race problem will likely produce a different result each time that we execute it.\n\nThus, race conditions produce undefined behaviour and unpredictability because the program produces\na different answer each time a different person gets to the target location before the others.\nAnd, we have no easy way to either predict or control who is getting to this target location first.\nIn other words, each time your program runs, you may get a different answer because a different person,\nfunction, or part of the code finishes its tasks before the others.\n\nAs an example, consider the code snippet exposed below. In this example, we create a global counter\nvariable, and we also create an `increment()` function, whose job is to just increment this global counter\nvariable in a for loop.\n\nSince the for loop iterates 1 hundred thousand times, and, we create two separate threads\nin this code example, what number do you expect to see in the final message printed to `stdout`?\nThe answer should be 2 hundred thousand. Right? Well, in theory, this program was supposed\nto print 2 hundred thousand at the end, but in practice, every time that I execute this program\nI get a different answer.\n\nIn the example exposed below, you can see that this time the end\nresult was 117254, instead of the expected 200000. The second time I executed this program,\nI got the number 108592 as the result. So the end result of this program is varying, but it never gets\nto the expected 200000 that we want.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n// Global counter variable\nvar counter: usize = 0;\n// Function to increment the counter\nfn increment() void {\n    for (0..100000) |_| {\n        counter += 1;\n    }\n}\n\npub fn main() !void {\n    const thr1 = try Thread.spawn(.{}, increment, .{});\n    const thr2 = try Thread.spawn(.{}, increment, .{});\n    thr1.join();\n    thr2.join();\n    try stdout.print(\"Couter value: {d}\\n\", .{counter});\n}\n```\n:::\n\n\n```\nCouter value: 117254\n```\n\n\nWhy this is happening? The answer is: because this program contains a data race problem.\nThis program would print the correct number 200000 if and only if the first thread finishes\nits tasks before the second thread starts to execute. But that is very unlikely to happen.\nBecause the process of creating the thread is too fast, and therefore, both threads start to execute roughly\nat the same time. If you change this code to add some nanoseconds of sleep between the first and the second calls to `spawn()`,\nyou will increase the chances of the program producing the \"correct result\".\n\nSo the data race problem happens because both threads are reading and writing to the same\nmemory location at roughly the same time. In this example, each thread is essentially performing\nthree basic operations at each iteration of the for loop, which are:\n\n1. reading the current value of `count`.\n1. incrementing this value by 1.\n1. writing the result back into `count`.\n\nIdeally, a thread B should read the value of `count`, only after the other thread A has finished\nwriting the incremented value back into the `count` object. Therefore, in the ideal scenario, which is demonstrated\nin @tbl-data-race-ideal, the threads should work in sync with each other. But the reality is that these\nthreads are out of sync, and because of that, they suffer from a data race problem, which is demonstrated\nin @tbl-data-race-not.\n\nNotice that, in the data race scenario (@tbl-data-race-not), the read performed by a thread B happens\nbefore the write operation of thread A, and that ultimately leads to wrong results at the end of the program.\nBecause when thread B reads the value of the `count` variable, thread A is still processing\nthe initial value from `count`, and has not yet written the new, incremented value back to `count`. As a result,\nthread B ends up reading the same initial (or \"old\") value from `count` instead of\nthe updated, incremented value that thread A would have written.\n\n\n::: {#tbl-data-race-ideal}\n\n| Thread 1    | Thread 2    | Integer value |\n|-------------|-------------|---------------|\n| read value  |             | 0             |\n| increment   |             | 1             |\n| write value |             | 1             |\n|             | read value  | 1             |\n|             | increment   | 2             |\n|             | write value | 2             |\n\n: An ideal scenario for two threads incrementing the same integer value\n:::\n\n::: {#tbl-data-race-not}\n\n| Thread 1    | Thread 2    | Integer value |\n|-------------|-------------|---------------|\n| read value  |             | 0             |\n|             | read value  | 0             |\n| increment   |             | 1             |\n|             | increment   | 1             |\n| write value |             | 1             |\n|             | write value | 1             |\n\n: A data race scenario when two threads are incrementing the same integer value\n:::\n\n\nIf you think about these diagrams exposed in form of tables, you will notice that they relate back to our discussion of atomic operations\nin @sec-atomic-operation. Remember, atomic operations are operations that the CPU executes\nfrom beginning to end, without interruptions from other threads or processes. So,\nthe scenario exposed in @tbl-data-race-ideal does not suffer from a data race, because\nthe operations performed by thread A are not interrupted in the middle by the operations\nfrom thread B.\n\nIf we also think about the discussion of critical section from @sec-critical-section, we can identify\nthe section that representes the critical section of the program, which is the section that is vulnerable\nto data race conditions. In this example, the critical section of the program is the line where we increment\nthe `counter` variable (`counter += 1`). So, ideally, we want to use a mutex, and lock right before this line, and then\nunlock right after this line.\n\n\n\n\n### Using mutexes in Zig\n\nNow that we know the problem that mutexes seek to solve, we can learn how to use them in Zig.\nMutexes in Zig are available through the `std.Thread.Mutex` struct from the Zig Standard Library.\nIf we take the same code from the previous example, and improve it with mutexes, to solve\nour data race problem, we get the code example below.\n\nNotice that this time, we had to alter the `increment()` function to receive a pointer to\nthe `Mutex` object as input. All that we need to do, to make this program safe against\ndata race problems, is to call the `lock()` method at the beginning of\nthe critical section, and then, call `unlock()` at the end of the critical section.\nNotice that the output of this program is now the correct number of 200000.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Thread = std.Thread;\nconst Mutex = std.Thread.Mutex;\nvar counter: usize = 0;\nfn increment(mutex: *Mutex) void {\n    for (0..100000) |_| {\n        mutex.lock();\n        counter += 1;\n        mutex.unlock();\n    }\n}\n\npub fn main() !void {\n    var mutex: Mutex = .{};\n    const thr1 = try Thread.spawn(.{}, increment, .{&mutex});\n    const thr2 = try Thread.spawn(.{}, increment, .{&mutex});\n    thr1.join();\n    thr2.join();\n    try stdout.print(\"Couter value: {d}\\n\", .{counter});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nCouter value: 200000\n```\n\n\n:::\n:::\n\n\n\n\n\n## Read/Write locks\n\nMutexes are normally used when it's not always safe for two or more threads running the same\npiece of code at the same time. In contrast, read/write locks are normally used in situations\nwhere you have a mixture of scenarios, i.e., there are some pieces of the codebase that are safe\nto run in parallel, and other pieces that are not safe.\n\nFor example, suppose that you have multiple threads that uses the same shared file in the filesystem to store some configurations, or\nstatistics. If two or more threads try to read the data from this same file at the same time, nothing bad happens.\nSo this part of the codebase is perfectly safe to be executed in parallel, with multiple threads reading the same file at the same time.\n\nHowever, if two or more threads try to write data into this same file at the same time, then we cause some race condition\nproblems. So this other part of the codebase is not safe to be executed in parallel.\nMore specifically, a thread might end up writing data in the middle of the data written by the other thread.\nThis process of two or more threads writing to the same location might lead to data corruption.\nThis specific situation is usually called a *torn write*.\n\nThus, what we can extract from this example is that there are certain types of operations that cause\na race condition, but there are also other types of operations that do not cause a race condition problem.\nYou could also say that there are types of operations that are susceptible to race condition problems,\nand there are other types of operations that are not.\n\nA read/write lock is a type of lock that acknowledges the existence of this specific scenario, and you can\nuse this type of lock to control which parts of the codebase are safe to run in parallel and which parts are not.\n\n\n\n### Exclusive lock vs shared lock\n\nTherefore, a read/write lock is a little different from a mutex. Because a mutex is always an *exclusive lock*, meaning that, only\none thread is allowed to execute at all times. With an exclusive lock, the other threads are always \"excluded\",\ni.e., they are always blocked from executing. But in a read/write lock, the other threads might be authorized\nto run at the same time, depending on the type of lock that they acquire.\n\nWe have two types of locks in a read/write lock, which are: an exclusive lock and a shared lock. An exclusive lock works exactly the same\nas a mutex, while a shared lock is a lock that does not block the other threads from running at the same time.\nIn the `pthreads` C library, read/write locks are available through the `pthread_rwlock_t` C struct. With\nthis C struct, you can create:\n\n- a \"write lock\", which corresponds to an exclusive lock.\n- a \"read lock\", which corresponds to a shared lock.\n\nThe terminology might be a little different compared to Zig. But the meaning is still the same.\nTherefore, just remember this relationship, write locks are exclusive locks, while read locks are shared locks.\n\nWhen a thread tries to acquire a read lock (i.e., a shared lock), this thread gets the shared lock\nif and only if another thread does not currently hold a write lock (i.e., an exclusive lock), and also\nif there are no other threads already in the queue,\nwaiting for their turn to acquire a write lock. In other words, the thread in the queue has attempted\nto get a write lock earlier, but this thread was blocked\nbecause there was another thread running that already had a write lock. As a consequence, this thread is in the queue to get a write lock,\nand it's currently waiting for the other thread with a write lock to finish its execution.\n\nWhen a thread tries to acquire a read lock, but it fails in acquiring this read lock, either because there is\na thread with a write lock already running, or because there is a thread in the queue to get a write lock,\nthe execution of this thread is instantly blocked, i.e., paused. This thread will indefinitely attempt to get the\nread lock, and its execution will be unblocked (or unpaused) only after this thread successfully acquires the read lock.\n\nIf you think deeply about this dynamic between read locks versus write locks, you might notice that a read lock is basically a safety mechanism.\nMore specifically, it's a way for us to\nallow a particular thread to run together with the other threads only when it's safe to. In other words, if there is currently\na thread with a write lock running, then it's very likely not safe for the thread that is trying to acquire the read lock to run now.\nAs a consequence, the read lock protects this thread from running into dangerous waters, and patiently waits for the\n\"write lock\" thread to finishes its tasks before it continues.\n\nOn the other hand, if there are only \"read lock\" (i.e., \"shared lock\") threads currently running\n(i.e., not a single \"write lock\" thread currently exists), then it\nis perfectly safe for this thread that is acquiring the read lock to run in parallel with the other\nthreads. As a result, the read lock just\nallows for this thread to run together with the other threads.\n\nThus, by using read locks (shared locks) in conjunction with write locks (exclusive locks), we can control which regions or sections\nof our multithreaded code is safe to have parallelism, and which sections are not safe to have parallelism.\n\n\n\n\n\n### Using read/write locks in Zig\n\nThe Zig Standard Library supports read/write locks through the `std.Thread.RwLock` module.\nIf you want a particular thread to acquire a shared lock (i.e., a read lock), you should\ncall the `lockShared()` method from the `RwLock` object. But, if you want this thread\nto acquire an exclusive lock (i.e., a write lock) instead, then you should call the\n`lock()` method from the `RwLock` object.\n\nAs with mutexes, we also have to unlock the shared or exclusive locks that we acquire through a read/write lock object,\nonce we are at the end of our \"critical section\". If you have acquired an exclusive lock, then, you unlock\nthis exclusive lock by calling the `unlock()` method from the read/write lock object. In contrast,\nif you have acquired a shared lock instead, then, call `unlockShared()` to unlock this shared lock.\n\nAs a simple example, the snippet below creates three separate threads responsible for reading the\ncurrent value in a `counter` object, and it also creates another thread responsible for writing\nnew data into the `counter` object (incrementing it, more specifically).\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar counter: u32 = 0;\nfn reader(lock: *RwLock) !void {\n    while (true) {\n        lock.lockShared();\n        const v: u32 = counter;\n        try stdout.print(\"{d}\", .{v});\n        lock.unlockShared();\n        std.time.sleep(2 * std.time.ns_per_s);\n    }\n}\nfn writer(lock: *RwLock) void {\n    while (true) {\n        lock.lock();\n        counter += 1;\n        lock.unlock();\n        std.time.sleep(2 * std.time.ns_per_s);\n    }\n}\n\npub fn main() !void {\n    var lock: RwLock = .{};\n    const thr1 = try Thread.spawn(.{}, reader, .{&lock});\n    const thr2 = try Thread.spawn(.{}, reader, .{&lock});\n    const thr3 = try Thread.spawn(.{}, reader, .{&lock});\n    const wthread = try Thread.spawn(.{}, writer, .{&lock});\n\n    thr1.join();\n    thr2.join();\n    thr3.join();\n    wthread.join();\n}\n```\n:::\n\n\n\n## Yielding a thread\n\nThe `Thread` struct supports yielding through the `yield()` method.\nYielding a thread means that the execution of the thread is temporarily stopped,\nand it moves to the end of the priority queue managed by the scheduler of\nyour operating system.\n\nThat is, when you yield a thread, you are essentially saying the following to your OS:\n\"Hey! Could you please stop executing this thread for now, and comeback to continue it later?\".\nYou could also interpret this yield operation as: \"Could you please deprioritize this thread,\nto focus on doing other things instead?\".\nSo this yield operation is also a way for you\nto stop a particular thread, so that you can work and prioritize other threads instead.\n\nIt's important to say that, yielding a thread is a \"not so common\" thread operation these days.\nIn other words, not many programmers use yielding in production, simply because it's hard to use\nthis operation and make it work properly, and also, there\nare better alternatives. Most programmers prefer to use `join()` instead.\nIn fact, most of the time, when you see someone using this \"yield\" operation in some code example,\nthey are usually doing so to help debug race conditions in their applications.\nThat is, this \"yield\" operation is mostly used as a debug tool nowadays.\n\nAnyway, if you want to yield a thread, just call the `yield()` method from it, like this:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nthread.yield();\n```\n:::\n\n\n\n\n\n\n\n## Common problems in threads\n\n\n\n### Deadlocks\n\nA deadlock occurs when two or more threads are blocked forever,\nwaiting for each other to release a resource. This usually happens when multiple locks are involved,\nand the order of acquiring them is not well managed.\n\nThe code example below demonstrates a deadlock situation. We have two different threads that execute\ntwo different functions (`work1()` and `work2()`) in this example. And we also have two separate\nmutexes. If you compile and run this code example, you will notice that the program just runs indefinitely,\nwithout ending.\n\nWhen we look into the first thread, which executes the `work1()` function, we can\nnotice that this function acquires the `mut1` lock first. Because this is the first operation\nthat is executed inside this thread, which is the first thread created in the program.\nAfter that, the function sleeps for 1 second, to\nsimulate some type of work, and then, the function tries to acquire the `mut2` lock.\n\nOn the other hand, when we look into the second thread, which executes the `work2()` function,\nwe can see that this function acquires the `mut2` lock first. Because when this thread gets created and it tries\nto acquire this `mut2` lock, the first thread is still sleeping on that \"sleep 1 second\" line.\nAfter acquiring `mut2`, the `work2()` function also sleeps for 1 second, to\nsimulate some type of work, and then the function tries to acquire the `mut1` lock.\n\nThis creates a deadlock situation, because after the \"sleep for 1 second\" line in both threads,\nthread 1 is trying to acquire the `mut2` lock, but this lock is currently being used by thread 2.\nHowever, at this moment, thread 2 is also trying to acquire the `mut1` lock, which is currently\nbeing used by thread 1. Therefore, both threads end up waiting for ever. Waiting for their peer to\nfree the lock that they want to acquire.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar mut1: Mutex = .{}; var mut2: Mutex = .{};\nfn work1() !void {\n    mut1.lock();\n    std.time.sleep(1 * std.time.ns_per_s);\n    mut2.lock();\n    _ = try stdout.write(\"Doing some work 1\\n\");\n    mut2.unlock(); mut1.unlock();\n}\n\nfn work2() !void {\n    mut2.lock();\n    std.time.sleep(1 * std.time.ns_per_s);\n    mut1.lock();\n    _ = try stdout.write(\"Doing some work 1\\n\");\n    mut1.unlock(); mut2.unlock();\n}\n\npub fn main() !void {\n    const thr1 = try Thread.spawn(.{}, work1, .{});\n    const thr2 = try Thread.spawn(.{}, work2, .{});\n    thr1.join();\n    thr2.join();\n}\n```\n:::\n\n\n\n### Not calling `join()` or `detach()` {#sec-not-call-join-detach}\n\nWhen you do not call either `join()` or `detach()` over a thread, then this thread becomes a \"zombie thread\",\nbecause it does not have a clear \"return point\".\nYou could also interpret this as: \"nobody is properly responsible for managing the thread\".\nWhen we don't establish if a thread is either *joinable* or *detached*,\nnobody becomes responsible for dealing with the return value of this thread, and also,\nnobody becomes responsible for clearing (or freeing) the resources associated with this thread.\n\nYou don't want to be in this situation, so remember to always use `join()` or `detach()`\non the threads that you create. When you don't use one of these methods, we lose\ncontrol over the thread, and its resources are never freed\n(i.e., you have leaked resources in the system).\n\n\n### Cancelling or killing a particular thread\n\nWhen we think about the `pthreads` C library, there is a possible way to asynchronously kill or cancel\na thread, which is by sending a `SIGTERM` signal to the thread through the `pthread_kill()` function.\nBut canceling a thread like this is bad. It's dangerously bad. As a consequence, the Zig implementation\nof threads does not have a similar function, or, a similar way to asynchronously cancel or kill\na thread.\n\nTherefore, if you want to cancel a thread in the middle of its execution in Zig,\nthen one good strategy that you can take is to use control flow in conjunction with `join()`.\nMore specifically, you can design your thread around a while loop that is constantly\nchecking if the thread should continue running.\nIf it's time to cancel the thread, we could make the while loop break, and join the thread with the main thread\nby calling `join()`.\n\nThe code example below demonstrates to some extent this strategy.\nHere, we are using control flow to break the while loop, and exit the thread earlier than\nwhat we have initially planned to. This example also demonstrates how can we use\natomic objects in Zig with the `Value()` generic function that we have mentioned in @sec-atomic-operation.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst Thread = std.Thread;\nconst stdout = std.io.getStdOut().writer();\nvar running = std.atomic.Value(bool).init(true);\nvar counter: u64 = 0;\nfn do_more_work() void {\n    std.time.sleep(2 * std.time.ns_per_s);\n}\nfn work() !void {\n    while (running.load(.monotonic)) {\n        for (0..10000) |_| { counter += 1; }\n        if (counter < 15000) {\n            _ = try stdout.write(\n                \"Time to cancel the thread.\\n\"\n            );\n            running.store(false, .monotonic);\n        } else {\n            _ = try stdout.write(\"Time to do more work.\\n\");\n            do_more_work();\n            running.store(false, .monotonic);\n        }\n    }\n}\n\npub fn main() !void {\n    const thread = try Thread.spawn(.{}, work, .{});\n    thread.join();\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\nTime to cancel the thread.\n```\n\n\n:::\n:::\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/14-zig-c-interop/execute-results/epub.json b/_freeze/Chapters/14-zig-c-interop/execute-results/epub.json
deleted file mode 100644
index d2ed7502..00000000
--- a/_freeze/Chapters/14-zig-c-interop/execute-results/epub.json
+++ /dev/null
@@ -1,21 +0,0 @@
-{
-  "hash": "7f0fb45d8337d93333a20759133b82dc",
-  "result": {
-    "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Zig interoperability with C\n\nIn this chapter, we are going to discuss the interoperability of Zig with C.\nWe have discussed in @sec-building-c-code how you can use the `zig` compiler to build C code.\nBut we haven't discussed yet how to actually use C code in Zig. In other words,\nwe haven't discussed yet how to call and use C code from Zig.\n\nThis is the main subject of this chapter.\nAlso, in our next small project in this book, we are going to use a C library in it.\nAs consequence, we will put in practice a lot of the knowledge discussed here on\nthis next project.\n\n\n## How to call C code from Zig\n\nInteroperability with C is not something new. Most high-level programming languages have FFI (foreign function interfaces),\nwhich can be used to call C code. For example, Python have Cython, R have `.Call()`, Javascript have `ccall()`, etc.\nBut Zig integrates with C in a deeper level, which affects not only the way that C code gets called, but also,\nhow this C code is compiled and incorporated into your Zig project.\n\nIn summary, Zig have great interoperability with C. If you want to call any C code from Zig,\nyou have to perform the following steps:\n\n- import a C header file into your Zig code.\n- link your Zig code with the C library.\n\n\n### Strategies to import C header files {#sec-strategy-c}\n\nUsing C code in Zig always involves performing the two steps cited above. However, when\nwe talk specifically about the first step listed above, there are currently two\ndifferent ways to perform this first step, which are:\n\n- translating the C header file into Zig code, through the `zig translate-c` command, and then, import and use the translated Zig code.\n- importing the C header file directly into your Zig module through the `@cImport()` built-in function.\n\nIf you are not familiar with `translate-c`, this is a subcommand inside the `zig` compiler that takes C files\nas input, and outputs the Zig representation of the C code present in these C files.\nIn other words, this subcommand works like a transpiler. It takes C code, and translates it into\nthe equivalent Zig code.\n\nI think it would be ok to interpret `translate-c` as a tool to generate Zig bindings\nto C code, similarly to the `rust-bindgen`[^bindgen] tool, which generates Rust FFI bindings to C code.\nBut that would not be a precise interpretation of `translate-c`. The idea behind this tool is\nto really translate the C code into Zig code.\n\n[^bindgen]: <https://github.com/rust-lang/rust-bindgen>\n\nNow, on a surface level, `@cImport()` versus `translate-c` might seem like\ntwo completely different strategies. But in fact, they are effectively the exact same strategy.\nBecause, under the hood, the `@cImport()` built-in function is just a shortcut to `translate-c`.\nBoth tools use the same \"C to Zig\" translation functionality. So when you use `@cImport()`,\nyou are essentially asking the `zig` compiler to translate the C header file into Zig code, then,\nto import this Zig code into your current Zig module.\n\nAt the present moment, there is an accepted proposal at the Zig project, to move `@cImport()`\nto the Zig build system[^cimport-issue]. If this proposal is completed, then, the \"use `@cImport()`\"\nstrategy would be transformed into \"call a translate C function in your Zig build script\".\nSo, the step of translating the C code into Zig code would be moved to\nthe build script of your Zig project, and you would only need to import the translated Zig code into\nyour Zig module to start calling C code from Zig.\n\n[^cimport-issue]: <https://github.com/ziglang/zig/issues/20630>\n\nIf you think about this proposal for a minute, you will understand that this is actually\na small change. I mean, the logic is the same, and the steps are still essentially the same.\nThe only difference is that one of the steps will be moved to the build script of your Zig project.\n\n\n\n### Linking Zig code with a C library {#sec-linking-c}\n\nRegardless of which of the two strategies from the previous section you choose,\nif you want to call C code from Zig, you must link your Zig code\nwith the C library that contains the C code that you want to call.\n\nIn other words, everytime you use some C code in your Zig code, **you introduce a dependency in your build process**.\nThis should come as no surprise to anyone that have any experience with C and C++.\nBecause this is no different in C. Everytime you use a C library in your C code, you also\nhave to build and link your C code with this C library that you are using.\n\nWhen we use a C library in our Zig code, the `zig` compiler needs to access the definition of the C functions that\nare being called in your Zig code. The C header file of this library provides the\ndeclarations of these C functions, but not their definitions. So, in order to access these definitions,\nthe `zig` compiler needs to build your Zig code and link it with the C library during the build process.\n\nAs we discussed across the @sec-build-system, there are different strategies to link something with a library.\nThis might involve building the C library first, and then, linking it with the Zig code. Or,\nit could also involve just the linking step, if this C library is already built and\ninstalled in your system. Anyway, if you have doubts about this, comeback to @sec-build-system.\n\n\n\n## Importing C header files {#sec-import-c-header}\n\nIn @sec-strategy-c, we have described that, currently, there are two different paths that\nyou can take to import a C header file into your Zig modules, `translate-c` or `@cImport()`.\nThis section describes each strategy separately in more details.\n\n### Strategy 1: using `translate-c`\n\nWhen we choose this strategy, we first need to use the `translate-c` tool to translate\nthe C header files that we want to use into Zig code. For example, suppose we wanted to\nuse the `fopen()` C function from the `stdio.h` C header file. We can translate the\n`stdio.h` C header file through the bash command below:\n\n```bash\nzig translate-c /usr/include/stdio.h \\\n    -lc -I/usr/include \\\n    -D_NO_CRT_STDIO_INLINE=1 > c.zig \\\n```\n\nNotice that, in this bash command, we are passing the necessary compiler flags (`-D` to define macros,\n`-l` to link libraries, `-I` to add an \"include path\") to compile and use the `stdio.h` header file.\nAlso notice that we are saving the results of the translation process inside a Zig module called `c.zig`.\n\nTherefore, after running this command, all we have to do is to import this `c.zig` module, and start\ncalling the C functions that you want to call from it. The example below demonstrates that.\nIt's important to remember what we've discussed in @sec-linking-c. In order to compile this\nexample you have to link this code with `libc`, by passing the flag `-lc` to the `zig` compiler.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @import(\"c.zig\");\npub fn main() !void {\n    const x: f32 = 1772.94122;\n    _ = c.printf(\"%.3f\\n\", x);\n}\n```\n:::\n\n\n\n```\n1772.941\n```\n\n\n### Strategy 2: using `@cImport()`\n\nTo import a C header file into our Zig code, we can use the built-in functions `@cInclude()` and `@cImport()`.\nInside the `@cImport()` function, we open a block (with a pair of curly braces). Inside this block\nwe can (if we need to) include multiple `@cDefine()` calls to define C macros when including this specific C header file.\nBut for the most part, you will probably need to use just a single call inside this block,\nwhich is a call to `@cInclude()`.\n\nThis `@cInclude()` function is equivalent to the `#include` statement in C.\nYou provide the name of the C header that you want to include as input to this `@cInclude()` function,\nthen, in conjunction with `@cImport()`, it will perform the necessary steps\nto include this C header file into your Zig code.\n\nYou should bind the result of `@cImport()` to a constant object, pretty much like you would do with\n`@import()`. You just assign the result to a constant object in your\nZig code, and, as consequence, all C functions, C structs, C macros, etc. that are defined inside the\nC header files will be available through this constant object.\n\nLook at the code example below, where we are importing the Standard I/O C Library (`stdio.h`),\nand calling the `printf()`[^printf] C function. Notice that we have also used in this example the C function `powf()`[^powf],\nwhich comes from the C Math Library (`math.h`).\nIn order to compile this example, you have to link this Zig code with both\nthe C Standard Library and the C Math Library, by passing the flags `-lc` and `-lm`\nto the `zig` compiler.\n\n[^printf]: <https://cplusplus.com/reference/cstdio/printf/>\n[^powf]: <https://en.cppreference.com/w/c/numeric/math/pow>\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n    @cInclude(\"math.h\");\n});\n\npub fn main() !void {\n    const x: f32 = 15.2;\n    const y = c.powf(x, @as(f32, 2.6));\n    _ = c.printf(\"%.3f\\n\", y);\n}\n```\n:::\n\n\n\n```\n1182.478\n```\n\n\n## About passing Zig values to C functions {#sec-zig-obj-to-c}\n\nZig objects have some intrinsic differences between their C equivalents.\nProbably the most noticeable one is the difference between C strings and Zig strings,\nwhich I described in @sec-zig-strings.\nZig strings are objects that contains both an array of arbitrary bytes and a length value.\nOn the other hand, a C string is usually just a pointer to a null-terminated array of arbitrary bytes.\n\nBecause of these intrinsic differences, in some specific cases, you cannot pass Zig objects directly\nas inputs to C functions before you convert them into C compatible values. However, in some other cases,\nyou are allowed to pass Zig objects and Zig literal values directly as inputs to C functions,\nand everything will work just fine, because the `zig` compiler will handle everything for you.\n\nSo we have two different scenarios being described here. Let's call them \"auto-conversion\" and \"need-conversion\".\nThe \"auto-conversion\" scenario is when the `zig` compiler handles everything for you, and automatically convert your\nZig objects/values into C compatible values. In contrast,\nthe \"need-conversion\" scenario is when you, the programmer, have the responsibility of converting\nthat Zig object into a C compatible value, before passing it to C code.\n\nThere is also a third scenario that is not being described here, which is when you create a C object, or, a C struct, or\na C compatible value in your Zig code, and you pass this C object/value as input to a C function in your Zig code.\nThis scenario will be described later in @sec-c-inputs. In this section, we are focused on the scenarios where\nwe are passing Zig objects/values to C code, instead of C objects/values being passed to C code.\n\n\n### The \"auto-conversion\" scenario\n\nAn \"auto-conversion\" scenario is when the `zig` compiler automatically converts our Zig objects into\nC compatible values for us. This specific scenario happens mostly in two instances:\n\n- with string literal values;\n- with any of the primitive data types that were introduced in @sec-primitive-data-types.\n\nWhen we think about the second instance described above, the `zig` compiler does automatically\nconvert any of the primitive data types into their C equivalents, because the compiler knows how\nto properly convert a `i16` into a `signed short`, or, a `u8` into a `unsigned char`, etc.\nNow, when we think about string literal values, they can be automatically\nconverted into C strings as well, especially because the `zig` compiler does not forces\na specific Zig data type into a string literal at first glance, unless you store this\nstring literal into a Zig object, and explicitly annotate the data type of this object.\n\nThus, with string literal values, the `zig` compiler has more freedom to infer which is the appropriate data type\nto be used in each situation. You could say that the string literal value \"inherits its data type\" depending on the context that\nit's used in. Most of the times, this data type is going to be the type that we commonly associate with Zig strings (`[]const u8`).\nBut it might be a different type depending on the situation. When the `zig` compiler detects that you are providing\na string literal value as input to some C function, the compiler automatically interprets this string\nliteral as a C string value.\n\nAs an example, look at the code exposed below. Here we are using\nthe `fopen()` C function to simply open and close a file. If you do not know how this `fopen()`\nfunction works in C, it takes two C strings as input. But in this code example below, we are passing some\nstring literals written in our Zig code directly as inputs to this `fopen()` C function.\n\nIn other words, we are not doing any conversion from a Zig string to a C string.\nWe are just passing the Zig string literals directly as inputs to the C function. And it works just fine!\nBecause the compiler interprets the string `\"foo.txt\"` as a C string given the current context.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n});\n\npub fn main() !void {\n    const file = c.fopen(\"foo.txt\", \"rb\");\n    if (file == null) {\n        @panic(\"Could not open file!\");\n    }\n    if (c.fclose(file) != 0) {\n        return error.CouldNotCloseFileDescriptor;\n    }\n}\n```\n:::\n\n\n\nLet's make some experiments, by writing the same code in different manners, and we\nsee how this affects the program. As a starting point, let's store the `\"foo.txt\"` string inside\na Zig object, like the `path` object below, and then, we pass this Zig object as input to the `fopen()` C function.\n\nIf we do this, the program still compiles and runs successfully. Notice that I have omitted most of the code in this example below.\nThis is just for brevity reasons, because the remainder of the program is still the same.\nThe only difference between this example and the previous one is just these two lines exposed below.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\nNow, what happens if you give an explicit data type to the `path` object? Well, if I force\nthe `zig` compiler to interpret this `path` object as a Zig string object,\nby annotating the `path` object with the data type `[]const u8`, then, I actually get a compile error\nas demonstrated below. We get this compile error because now I'm forcing the `zig` compiler\nto interpret `path` as a Zig string object.\n\nAccording to the error message, the `fopen()` C function was expecting to receive an\ninput value of type `[*c]const u8` (C string) instead of a value of type `[]const u8` (Zig string).\nIn more details, the type `[*c]const u8` is actually the Zig type representation of a C string.\nThe `[*c]` portion of this type identifies a C pointer. So, this Zig type essentially means: a C pointer to an array (`[*c]`) of\nconstant bytes (`const u8`).\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\n```\nt.zig:2:7 error: expected type '[*c]const u8', found '[]const u8':\n    const file = c.fopen(path, \"rb\");\n                         ^~~~\n```\n\nTherefore, when we talk exclusively about string literal values, as long as you don't give an\nexplicit data type to these string literal values, the `zig` compiler should be capable of automatically\nconverting them into C strings as needed.\n\nBut what about using one of the primitive data types that were introduced in @sec-primitive-data-types?\nLet's take code exposed below as an example of that. Here, we are giving some float literal values as input\nto the C function `powf()`. Notice that this code example compiles and runs successfully.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst cmath = @cImport({\n    @cInclude(\"math.h\");\n});\n\npub fn main() !void {\n    const y = cmath.powf(15.68, 2.32);\n    try stdout.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n\n```\n593.2023\n```\n\nOnce again, because the `zig` compiler does not associate a specific data type with the literal values\n`15.68` and `2.32` at first glance, the compiler can automatically convert these values\ninto their C `float` (or `double`) equivalents, before it passes to the `powf()` C function.\nNow, even if I give an explicit Zig data type to these literal values, by storing them into a Zig object,\nand explicit annotating the type of these objects, the code still compiles and runs successfully.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const x: f32 = 15.68;\n    const y = cmath.powf(x, 2.32);\n    // The remainder of the program\n```\n:::\n\n\n\n```\n593.2023\n```\n\n\n\n### The \"need-conversion\" scenario\n\nA \"need-conversion\" scenario is when we need to manually convert our Zig objects into C compatible values\nbefore passing them as input to C functions. You will fall in this scenario, when passing Zig string objects\nto C functions.\n\nWe have already seen this specific circumstance in the last `fopen()` example,\nwhich is reproduced below. You can see in this example, that we have given an explicit Zig data type\n(`[]const u8`) to our `path` object, and, as a consequence of that, we have forced the `zig` compiler\nto see this `path` object, as a Zig string object. Therefore, we need now to manually convert\nthis `path` object into a C string before we pass it to `fopen()`.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\n```\nt.zig:10:26: error: expected type '[*c]const u8', found '[]const u8'\n    const file = c.fopen(path, \"rb\");\n                         ^~~~\n```\n\n\nThere are different ways to convert a Zig string object into a C string.\nOne way to solve this problem is to provide the pointer to the underlying array\nof bytes, instead of providing the Zig object directly as input.\nYou can access this pointer by using the `ptr` property of the Zig string object.\n\nThe code example below demonstrates this strategy. Notice that, by giving the\npointer to the underlying array in `path` through the `ptr` property, we get no compile errors as result\nwhile using the `fopen()` C function.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path.ptr, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\nThis strategy works because this pointer to the underlying array found in the `ptr` property,\nis semantically identical to a C pointer to an array of bytes, i.e., a C object of type `*unsigned char`.\nThis is why this option also solves the problem of converting the Zig string into a C string.\n\nAnother option is to explicitly convert the Zig string object into a C pointer by using the\nbuilt-in function `@ptrCast()`. With this function we can convert\nan object of type `[]const u8` into an object of type `[*c]const u8`.\nAs I described at the previous section, the `[*c]` portion of the type\nmeans that it's a C pointer. This strategy is not-recommended. But it's\nuseful to demonstrate the use of `@ptrCast()`.\n\nYou may recall of `@as()` and `@ptrCast()` from @sec-type-cast. Just as a recap,\nthe `@as()` built-in function is used to explicitly convert (or cast) a Zig value\nfrom a type \"x\" into a value of type \"y\". But in our case here, we are converting\na pointer object. Everytime a pointer is involved in some \"type casting operation\" in Zig,\nthe `@ptrCast()` function is involved.\n\nIn the example below, we are using this function to cast our `path` object\ninto a C pointer to an array of bytes. Then, we pass this C pointer as input\nto the `fopen()` function. Notice that this code example compiles successfully\nwith no errors.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path: []const u8 = \"foo.txt\";\n    const c_path: [*c]const u8 = @ptrCast(path);\n    const file = c.fopen(c_path, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\n\n\n## Creating C objects in Zig {#sec-c-inputs}\n\nCreating C objects, or, in other words, creating instances of C structs in your Zig code\nis actually something quite easy to do. You first need to import the C header file (like I described in @sec-import-c-header) that defines\nthe C struct that you are trying to instantiate in your Zig code. After that, you can just\ncreate a new object in your Zig code, and annotate it with the data type of the C struct.\n\nFor example, suppose we have a C header file called `user.h`, and that this header file is declaring a new struct named `User`.\nThis C header file is exposed below:\n\n```c\n#include <stdint.h>\n\ntypedef struct {\n    uint64_t id;\n    char* name;\n} User;\n```\n\nThis `User` C struct have two distinct fields, or two struct members, named `id` and `name`.\nThe field `id` is an unsigned 64-bit integer value, while the field `name` is just a standard C string.\nNow, suppose that I want to create an instance of this `User` struct in my Zig code.\nI can do that by importing this `user.h` header file into my Zig code, and creating\na new object with type `User`. These steps are reproduced in the code example below.\n\nNotice that I have used the keyword `undefined` in this example. This allows me to\ncreate the `new_user` object without the need to provide an initial value to the object.\nAs consequence, the underlying memory associated with this `new_user` object is uninitialized,\ni.e., the memory is currently populated with \"garbage\" values.\nThus, this expression have the exact same effect of the expression `User new_user;` in C,\nwhich means \"declare a new object named `new_user` of type `User`\".\n\nIt's our responsibility to properly initialize this memory associated with this `new_user` object,\nby assigning valid values to the members (or the fields) of the C struct. In the example below,\nI'm assigning the integer 1 to the member `id`. I am also saving the string `\"pedropark99\"` into the member `name`.\nNotice in this example that I manually add the null character (zero byte) to the end of the allocated array\nfor this string. This null character marks the end of the array in C.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst c = @cImport({\n    @cInclude(\"user.h\");\n});\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n\n    var new_user: c.User = undefined;\n    new_user.id = 1;\n    var user_name = try allocator.alloc(u8, 12);\n    defer allocator.free(user_name);\n    @memcpy(user_name[0..(user_name.len - 1)], \"pedropark99\");\n    user_name[user_name.len - 1] = 0;\n    new_user.name = user_name.ptr;\n}\n```\n:::\n\n\n\nSo, in this example above, we are manually initializing each field of the C struct.\nWe could say that, in this instance, we are \"manually instantiating\nthe C struct object\". However, when we use C libraries in our Zig code, we rarely need\nto manually instantiate the C structs like that. Only because C libraries\nusually provide a \"constructor function\" in their public APIs. As consequence, we normally rely on\nthese constructor functions to properly initialize the C structs, and\nthe struct fields for us.\n\nFor example, consider the Harfbuzz C library. This a text shaping C library,\nand it works around a \"buffer object\", or, more specifically, an instance of\nthe C struct `hb_buffer_t`. Therefore, we need to create an instance of\nthis C struct if we want to use this C library. Luckily, this library offers\nthe function `hb_buffer_create()`, which we can use to create such object.\nSo the Zig code necessary to create such object would probably look something like this:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cInclude(\"hb.h\");\n});\nvar buf: c.hb_buffer_t = c.hb_buffer_create();\n// Do stuff with the \"buffer object\"\n```\n:::\n\n\n\nTherefore, we do not need to manually create an instance of the C struct\n`hb_buffer_t` here, and manually assign valid values to each field in this C struct.\nBecause the constructor function `hb_buffer_create()` is doing this heavy job for us.\n\nSince this `buf` object, and also, the `new_user` object from previous examples, are instances of C structs, these\nobjects are by themselves C compatible values. They are C objects defined in our Zig code. As consequence,\nyou can freely pass these objects as input to any C function that expects to receive this type\nof C struct as input. You do not need to use any special syntax, or, to convert them in\nany special manner to use them in C code. This is how we create and use C objects in our Zig code.\n\n\n\n## Passing C structs across Zig functions {#sec-pass-c-structs}\n\nNow that we have learned how to create/declare C objects in our Zig code, we\nneed to learn how to pass these C objects as inputs to Zig functions.\nAs I described in @sec-c-inputs, we can freely pass these C objects as inputs to C code\nthat we call from our Zig code. But what about passing these C objects to Zig functions?\n\nIn essence, this specific case requires one small adjustment in the Zig function declaration.\nAll you need to do, is to make sure that you pass your C object *by reference* to the function,\ninstead of passing it *by value*. To do that, you have to annotate the data type of the function argument\nthat is receiving this C object as \"a pointer to the C struct\", instead of annotating it as \"an instance of the C struct\".\n\nLet's consider the C struct `User` from the `user.h` C header file that we have used in @sec-c-inputs.\nNow, consider that we want to create a Zig function that sets the value of the `id` field\nin this C struct, like the `set_user_id()` function declared below.\nNotice that the `user` argument in this function is annotated as a pointer (`*`) to a `c.User` object.\n\nTherefore, all you have to do when passing C objects to Zig functions, is to add `*` to the\ndata type of the function argument that is receiving the C object. This will make sure that\nthe C object is passed *by reference* to the function.\n\nBecause we have transformed the function argument into a pointer,\neverytime that you have to access the value pointed by this input pointer inside the function body, for whatever reason (e.g. you want\nto read, update, or delete this value), you have to dereference the pointer with the `.*` syntax that we\nlearned from @sec-pointer. Notice that the `set_user_id()` function is using this syntax to alter\nthe value in the `id` field of the `User` struct pointed by the input pointer.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst c = @cImport({\n    @cInclude(\"user.h\");\n});\nfn set_user_id(id: u64, user: *c.User) void {\n    user.*.id = id;\n}\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n\n    var new_user: c.User = undefined;\n    new_user.id = 1;\n    var user_name = try allocator.alloc(u8, 12);\n    defer allocator.free(user_name);\n    @memcpy(user_name[0..(user_name.len - 1)], \"pedropark99\");\n    user_name[user_name.len - 1] = 0;\n    new_user.name = user_name.ptr;\n\n    set_user_id(25, &new_user);\n    try stdout.print(\"New ID: {any}\\n\", .{new_user.id});\n}\n```\n:::\n\n\n\n```\nNew ID: 25\n```\n",
-    "supporting": [
-      "14-zig-c-interop_files"
-    ],
-    "filters": [
-      "rmarkdown/pagebreak.lua"
-    ],
-    "includes": {},
-    "engineDependencies": {
-      "knitr": [
-        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
-      ]
-    },
-    "preserve": null,
-    "postProcess": false
-  }
-}
\ No newline at end of file
diff --git a/_freeze/Chapters/14-zig-c-interop/execute-results/html.json b/_freeze/Chapters/14-zig-c-interop/execute-results/html.json
index fe46362b..23876574 100644
--- a/_freeze/Chapters/14-zig-c-interop/execute-results/html.json
+++ b/_freeze/Chapters/14-zig-c-interop/execute-results/html.json
@@ -2,10 +2,8 @@
   "hash": "7f0fb45d8337d93333a20759133b82dc",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Zig interoperability with C\n\nIn this chapter, we are going to discuss the interoperability of Zig with C.\nWe have discussed in @sec-building-c-code how you can use the `zig` compiler to build C code.\nBut we haven't discussed yet how to actually use C code in Zig. In other words,\nwe haven't discussed yet how to call and use C code from Zig.\n\nThis is the main subject of this chapter.\nAlso, in our next small project in this book, we are going to use a C library in it.\nAs consequence, we will put in practice a lot of the knowledge discussed here on\nthis next project.\n\n\n## How to call C code from Zig\n\nInteroperability with C is not something new. Most high-level programming languages have FFI (foreign function interfaces),\nwhich can be used to call C code. For example, Python have Cython, R have `.Call()`, Javascript have `ccall()`, etc.\nBut Zig integrates with C in a deeper level, which affects not only the way that C code gets called, but also,\nhow this C code is compiled and incorporated into your Zig project.\n\nIn summary, Zig have great interoperability with C. If you want to call any C code from Zig,\nyou have to perform the following steps:\n\n- import a C header file into your Zig code.\n- link your Zig code with the C library.\n\n\n### Strategies to import C header files {#sec-strategy-c}\n\nUsing C code in Zig always involves performing the two steps cited above. However, when\nwe talk specifically about the first step listed above, there are currently two\ndifferent ways to perform this first step, which are:\n\n- translating the C header file into Zig code, through the `zig translate-c` command, and then, import and use the translated Zig code.\n- importing the C header file directly into your Zig module through the `@cImport()` built-in function.\n\nIf you are not familiar with `translate-c`, this is a subcommand inside the `zig` compiler that takes C files\nas input, and outputs the Zig representation of the C code present in these C files.\nIn other words, this subcommand works like a transpiler. It takes C code, and translates it into\nthe equivalent Zig code.\n\nI think it would be ok to interpret `translate-c` as a tool to generate Zig bindings\nto C code, similarly to the `rust-bindgen`[^bindgen] tool, which generates Rust FFI bindings to C code.\nBut that would not be a precise interpretation of `translate-c`. The idea behind this tool is\nto really translate the C code into Zig code.\n\n[^bindgen]: <https://github.com/rust-lang/rust-bindgen>\n\nNow, on a surface level, `@cImport()` versus `translate-c` might seem like\ntwo completely different strategies. But in fact, they are effectively the exact same strategy.\nBecause, under the hood, the `@cImport()` built-in function is just a shortcut to `translate-c`.\nBoth tools use the same \"C to Zig\" translation functionality. So when you use `@cImport()`,\nyou are essentially asking the `zig` compiler to translate the C header file into Zig code, then,\nto import this Zig code into your current Zig module.\n\nAt the present moment, there is an accepted proposal at the Zig project, to move `@cImport()`\nto the Zig build system[^cimport-issue]. If this proposal is completed, then, the \"use `@cImport()`\"\nstrategy would be transformed into \"call a translate C function in your Zig build script\".\nSo, the step of translating the C code into Zig code would be moved to\nthe build script of your Zig project, and you would only need to import the translated Zig code into\nyour Zig module to start calling C code from Zig.\n\n[^cimport-issue]: <https://github.com/ziglang/zig/issues/20630>\n\nIf you think about this proposal for a minute, you will understand that this is actually\na small change. I mean, the logic is the same, and the steps are still essentially the same.\nThe only difference is that one of the steps will be moved to the build script of your Zig project.\n\n\n\n### Linking Zig code with a C library {#sec-linking-c}\n\nRegardless of which of the two strategies from the previous section you choose,\nif you want to call C code from Zig, you must link your Zig code\nwith the C library that contains the C code that you want to call.\n\nIn other words, everytime you use some C code in your Zig code, **you introduce a dependency in your build process**.\nThis should come as no surprise to anyone that have any experience with C and C++.\nBecause this is no different in C. Everytime you use a C library in your C code, you also\nhave to build and link your C code with this C library that you are using.\n\nWhen we use a C library in our Zig code, the `zig` compiler needs to access the definition of the C functions that\nare being called in your Zig code. The C header file of this library provides the\ndeclarations of these C functions, but not their definitions. So, in order to access these definitions,\nthe `zig` compiler needs to build your Zig code and link it with the C library during the build process.\n\nAs we discussed across the @sec-build-system, there are different strategies to link something with a library.\nThis might involve building the C library first, and then, linking it with the Zig code. Or,\nit could also involve just the linking step, if this C library is already built and\ninstalled in your system. Anyway, if you have doubts about this, comeback to @sec-build-system.\n\n\n\n## Importing C header files {#sec-import-c-header}\n\nIn @sec-strategy-c, we have described that, currently, there are two different paths that\nyou can take to import a C header file into your Zig modules, `translate-c` or `@cImport()`.\nThis section describes each strategy separately in more details.\n\n### Strategy 1: using `translate-c`\n\nWhen we choose this strategy, we first need to use the `translate-c` tool to translate\nthe C header files that we want to use into Zig code. For example, suppose we wanted to\nuse the `fopen()` C function from the `stdio.h` C header file. We can translate the\n`stdio.h` C header file through the bash command below:\n\n```bash\nzig translate-c /usr/include/stdio.h \\\n    -lc -I/usr/include \\\n    -D_NO_CRT_STDIO_INLINE=1 > c.zig \\\n```\n\nNotice that, in this bash command, we are passing the necessary compiler flags (`-D` to define macros,\n`-l` to link libraries, `-I` to add an \"include path\") to compile and use the `stdio.h` header file.\nAlso notice that we are saving the results of the translation process inside a Zig module called `c.zig`.\n\nTherefore, after running this command, all we have to do is to import this `c.zig` module, and start\ncalling the C functions that you want to call from it. The example below demonstrates that.\nIt's important to remember what we've discussed in @sec-linking-c. In order to compile this\nexample you have to link this code with `libc`, by passing the flag `-lc` to the `zig` compiler.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @import(\"c.zig\");\npub fn main() !void {\n    const x: f32 = 1772.94122;\n    _ = c.printf(\"%.3f\\n\", x);\n}\n```\n:::\n\n\n\n\n```\n1772.941\n```\n\n\n### Strategy 2: using `@cImport()`\n\nTo import a C header file into our Zig code, we can use the built-in functions `@cInclude()` and `@cImport()`.\nInside the `@cImport()` function, we open a block (with a pair of curly braces). Inside this block\nwe can (if we need to) include multiple `@cDefine()` calls to define C macros when including this specific C header file.\nBut for the most part, you will probably need to use just a single call inside this block,\nwhich is a call to `@cInclude()`.\n\nThis `@cInclude()` function is equivalent to the `#include` statement in C.\nYou provide the name of the C header that you want to include as input to this `@cInclude()` function,\nthen, in conjunction with `@cImport()`, it will perform the necessary steps\nto include this C header file into your Zig code.\n\nYou should bind the result of `@cImport()` to a constant object, pretty much like you would do with\n`@import()`. You just assign the result to a constant object in your\nZig code, and, as consequence, all C functions, C structs, C macros, etc. that are defined inside the\nC header files will be available through this constant object.\n\nLook at the code example below, where we are importing the Standard I/O C Library (`stdio.h`),\nand calling the `printf()`[^printf] C function. Notice that we have also used in this example the C function `powf()`[^powf],\nwhich comes from the C Math Library (`math.h`).\nIn order to compile this example, you have to link this Zig code with both\nthe C Standard Library and the C Math Library, by passing the flags `-lc` and `-lm`\nto the `zig` compiler.\n\n[^printf]: <https://cplusplus.com/reference/cstdio/printf/>\n[^powf]: <https://en.cppreference.com/w/c/numeric/math/pow>\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n    @cInclude(\"math.h\");\n});\n\npub fn main() !void {\n    const x: f32 = 15.2;\n    const y = c.powf(x, @as(f32, 2.6));\n    _ = c.printf(\"%.3f\\n\", y);\n}\n```\n:::\n\n\n\n\n```\n1182.478\n```\n\n\n## About passing Zig values to C functions {#sec-zig-obj-to-c}\n\nZig objects have some intrinsic differences between their C equivalents.\nProbably the most noticeable one is the difference between C strings and Zig strings,\nwhich I described in @sec-zig-strings.\nZig strings are objects that contains both an array of arbitrary bytes and a length value.\nOn the other hand, a C string is usually just a pointer to a null-terminated array of arbitrary bytes.\n\nBecause of these intrinsic differences, in some specific cases, you cannot pass Zig objects directly\nas inputs to C functions before you convert them into C compatible values. However, in some other cases,\nyou are allowed to pass Zig objects and Zig literal values directly as inputs to C functions,\nand everything will work just fine, because the `zig` compiler will handle everything for you.\n\nSo we have two different scenarios being described here. Let's call them \"auto-conversion\" and \"need-conversion\".\nThe \"auto-conversion\" scenario is when the `zig` compiler handles everything for you, and automatically convert your\nZig objects/values into C compatible values. In contrast,\nthe \"need-conversion\" scenario is when you, the programmer, have the responsibility of converting\nthat Zig object into a C compatible value, before passing it to C code.\n\nThere is also a third scenario that is not being described here, which is when you create a C object, or, a C struct, or\na C compatible value in your Zig code, and you pass this C object/value as input to a C function in your Zig code.\nThis scenario will be described later in @sec-c-inputs. In this section, we are focused on the scenarios where\nwe are passing Zig objects/values to C code, instead of C objects/values being passed to C code.\n\n\n### The \"auto-conversion\" scenario\n\nAn \"auto-conversion\" scenario is when the `zig` compiler automatically converts our Zig objects into\nC compatible values for us. This specific scenario happens mostly in two instances:\n\n- with string literal values;\n- with any of the primitive data types that were introduced in @sec-primitive-data-types.\n\nWhen we think about the second instance described above, the `zig` compiler does automatically\nconvert any of the primitive data types into their C equivalents, because the compiler knows how\nto properly convert a `i16` into a `signed short`, or, a `u8` into a `unsigned char`, etc.\nNow, when we think about string literal values, they can be automatically\nconverted into C strings as well, especially because the `zig` compiler does not forces\na specific Zig data type into a string literal at first glance, unless you store this\nstring literal into a Zig object, and explicitly annotate the data type of this object.\n\nThus, with string literal values, the `zig` compiler has more freedom to infer which is the appropriate data type\nto be used in each situation. You could say that the string literal value \"inherits its data type\" depending on the context that\nit's used in. Most of the times, this data type is going to be the type that we commonly associate with Zig strings (`[]const u8`).\nBut it might be a different type depending on the situation. When the `zig` compiler detects that you are providing\na string literal value as input to some C function, the compiler automatically interprets this string\nliteral as a C string value.\n\nAs an example, look at the code exposed below. Here we are using\nthe `fopen()` C function to simply open and close a file. If you do not know how this `fopen()`\nfunction works in C, it takes two C strings as input. But in this code example below, we are passing some\nstring literals written in our Zig code directly as inputs to this `fopen()` C function.\n\nIn other words, we are not doing any conversion from a Zig string to a C string.\nWe are just passing the Zig string literals directly as inputs to the C function. And it works just fine!\nBecause the compiler interprets the string `\"foo.txt\"` as a C string given the current context.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n});\n\npub fn main() !void {\n    const file = c.fopen(\"foo.txt\", \"rb\");\n    if (file == null) {\n        @panic(\"Could not open file!\");\n    }\n    if (c.fclose(file) != 0) {\n        return error.CouldNotCloseFileDescriptor;\n    }\n}\n```\n:::\n\n\n\n\nLet's make some experiments, by writing the same code in different manners, and we\nsee how this affects the program. As a starting point, let's store the `\"foo.txt\"` string inside\na Zig object, like the `path` object below, and then, we pass this Zig object as input to the `fopen()` C function.\n\nIf we do this, the program still compiles and runs successfully. Notice that I have omitted most of the code in this example below.\nThis is just for brevity reasons, because the remainder of the program is still the same.\nThe only difference between this example and the previous one is just these two lines exposed below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\n\nNow, what happens if you give an explicit data type to the `path` object? Well, if I force\nthe `zig` compiler to interpret this `path` object as a Zig string object,\nby annotating the `path` object with the data type `[]const u8`, then, I actually get a compile error\nas demonstrated below. We get this compile error because now I'm forcing the `zig` compiler\nto interpret `path` as a Zig string object.\n\nAccording to the error message, the `fopen()` C function was expecting to receive an\ninput value of type `[*c]const u8` (C string) instead of a value of type `[]const u8` (Zig string).\nIn more details, the type `[*c]const u8` is actually the Zig type representation of a C string.\nThe `[*c]` portion of this type identifies a C pointer. So, this Zig type essentially means: a C pointer to an array (`[*c]`) of\nconstant bytes (`const u8`).\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\n\n```\nt.zig:2:7 error: expected type '[*c]const u8', found '[]const u8':\n    const file = c.fopen(path, \"rb\");\n                         ^~~~\n```\n\nTherefore, when we talk exclusively about string literal values, as long as you don't give an\nexplicit data type to these string literal values, the `zig` compiler should be capable of automatically\nconverting them into C strings as needed.\n\nBut what about using one of the primitive data types that were introduced in @sec-primitive-data-types?\nLet's take code exposed below as an example of that. Here, we are giving some float literal values as input\nto the C function `powf()`. Notice that this code example compiles and runs successfully.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst cmath = @cImport({\n    @cInclude(\"math.h\");\n});\n\npub fn main() !void {\n    const y = cmath.powf(15.68, 2.32);\n    try stdout.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n\n\n```\n593.2023\n```\n\nOnce again, because the `zig` compiler does not associate a specific data type with the literal values\n`15.68` and `2.32` at first glance, the compiler can automatically convert these values\ninto their C `float` (or `double`) equivalents, before it passes to the `powf()` C function.\nNow, even if I give an explicit Zig data type to these literal values, by storing them into a Zig object,\nand explicit annotating the type of these objects, the code still compiles and runs successfully.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const x: f32 = 15.68;\n    const y = cmath.powf(x, 2.32);\n    // The remainder of the program\n```\n:::\n\n\n\n\n```\n593.2023\n```\n\n\n\n### The \"need-conversion\" scenario\n\nA \"need-conversion\" scenario is when we need to manually convert our Zig objects into C compatible values\nbefore passing them as input to C functions. You will fall in this scenario, when passing Zig string objects\nto C functions.\n\nWe have already seen this specific circumstance in the last `fopen()` example,\nwhich is reproduced below. You can see in this example, that we have given an explicit Zig data type\n(`[]const u8`) to our `path` object, and, as a consequence of that, we have forced the `zig` compiler\nto see this `path` object, as a Zig string object. Therefore, we need now to manually convert\nthis `path` object into a C string before we pass it to `fopen()`.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\n\n```\nt.zig:10:26: error: expected type '[*c]const u8', found '[]const u8'\n    const file = c.fopen(path, \"rb\");\n                         ^~~~\n```\n\n\nThere are different ways to convert a Zig string object into a C string.\nOne way to solve this problem is to provide the pointer to the underlying array\nof bytes, instead of providing the Zig object directly as input.\nYou can access this pointer by using the `ptr` property of the Zig string object.\n\nThe code example below demonstrates this strategy. Notice that, by giving the\npointer to the underlying array in `path` through the `ptr` property, we get no compile errors as result\nwhile using the `fopen()` C function.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path.ptr, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\n\nThis strategy works because this pointer to the underlying array found in the `ptr` property,\nis semantically identical to a C pointer to an array of bytes, i.e., a C object of type `*unsigned char`.\nThis is why this option also solves the problem of converting the Zig string into a C string.\n\nAnother option is to explicitly convert the Zig string object into a C pointer by using the\nbuilt-in function `@ptrCast()`. With this function we can convert\nan object of type `[]const u8` into an object of type `[*c]const u8`.\nAs I described at the previous section, the `[*c]` portion of the type\nmeans that it's a C pointer. This strategy is not-recommended. But it's\nuseful to demonstrate the use of `@ptrCast()`.\n\nYou may recall of `@as()` and `@ptrCast()` from @sec-type-cast. Just as a recap,\nthe `@as()` built-in function is used to explicitly convert (or cast) a Zig value\nfrom a type \"x\" into a value of type \"y\". But in our case here, we are converting\na pointer object. Everytime a pointer is involved in some \"type casting operation\" in Zig,\nthe `@ptrCast()` function is involved.\n\nIn the example below, we are using this function to cast our `path` object\ninto a C pointer to an array of bytes. Then, we pass this C pointer as input\nto the `fopen()` function. Notice that this code example compiles successfully\nwith no errors.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path: []const u8 = \"foo.txt\";\n    const c_path: [*c]const u8 = @ptrCast(path);\n    const file = c.fopen(c_path, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\n\n\n\n## Creating C objects in Zig {#sec-c-inputs}\n\nCreating C objects, or, in other words, creating instances of C structs in your Zig code\nis actually something quite easy to do. You first need to import the C header file (like I described in @sec-import-c-header) that defines\nthe C struct that you are trying to instantiate in your Zig code. After that, you can just\ncreate a new object in your Zig code, and annotate it with the data type of the C struct.\n\nFor example, suppose we have a C header file called `user.h`, and that this header file is declaring a new struct named `User`.\nThis C header file is exposed below:\n\n```c\n#include <stdint.h>\n\ntypedef struct {\n    uint64_t id;\n    char* name;\n} User;\n```\n\nThis `User` C struct have two distinct fields, or two struct members, named `id` and `name`.\nThe field `id` is an unsigned 64-bit integer value, while the field `name` is just a standard C string.\nNow, suppose that I want to create an instance of this `User` struct in my Zig code.\nI can do that by importing this `user.h` header file into my Zig code, and creating\na new object with type `User`. These steps are reproduced in the code example below.\n\nNotice that I have used the keyword `undefined` in this example. This allows me to\ncreate the `new_user` object without the need to provide an initial value to the object.\nAs consequence, the underlying memory associated with this `new_user` object is uninitialized,\ni.e., the memory is currently populated with \"garbage\" values.\nThus, this expression have the exact same effect of the expression `User new_user;` in C,\nwhich means \"declare a new object named `new_user` of type `User`\".\n\nIt's our responsibility to properly initialize this memory associated with this `new_user` object,\nby assigning valid values to the members (or the fields) of the C struct. In the example below,\nI'm assigning the integer 1 to the member `id`. I am also saving the string `\"pedropark99\"` into the member `name`.\nNotice in this example that I manually add the null character (zero byte) to the end of the allocated array\nfor this string. This null character marks the end of the array in C.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst c = @cImport({\n    @cInclude(\"user.h\");\n});\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n\n    var new_user: c.User = undefined;\n    new_user.id = 1;\n    var user_name = try allocator.alloc(u8, 12);\n    defer allocator.free(user_name);\n    @memcpy(user_name[0..(user_name.len - 1)], \"pedropark99\");\n    user_name[user_name.len - 1] = 0;\n    new_user.name = user_name.ptr;\n}\n```\n:::\n\n\n\n\nSo, in this example above, we are manually initializing each field of the C struct.\nWe could say that, in this instance, we are \"manually instantiating\nthe C struct object\". However, when we use C libraries in our Zig code, we rarely need\nto manually instantiate the C structs like that. Only because C libraries\nusually provide a \"constructor function\" in their public APIs. As consequence, we normally rely on\nthese constructor functions to properly initialize the C structs, and\nthe struct fields for us.\n\nFor example, consider the Harfbuzz C library. This a text shaping C library,\nand it works around a \"buffer object\", or, more specifically, an instance of\nthe C struct `hb_buffer_t`. Therefore, we need to create an instance of\nthis C struct if we want to use this C library. Luckily, this library offers\nthe function `hb_buffer_create()`, which we can use to create such object.\nSo the Zig code necessary to create such object would probably look something like this:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cInclude(\"hb.h\");\n});\nvar buf: c.hb_buffer_t = c.hb_buffer_create();\n// Do stuff with the \"buffer object\"\n```\n:::\n\n\n\n\nTherefore, we do not need to manually create an instance of the C struct\n`hb_buffer_t` here, and manually assign valid values to each field in this C struct.\nBecause the constructor function `hb_buffer_create()` is doing this heavy job for us.\n\nSince this `buf` object, and also, the `new_user` object from previous examples, are instances of C structs, these\nobjects are by themselves C compatible values. They are C objects defined in our Zig code. As consequence,\nyou can freely pass these objects as input to any C function that expects to receive this type\nof C struct as input. You do not need to use any special syntax, or, to convert them in\nany special manner to use them in C code. This is how we create and use C objects in our Zig code.\n\n\n\n## Passing C structs across Zig functions {#sec-pass-c-structs}\n\nNow that we have learned how to create/declare C objects in our Zig code, we\nneed to learn how to pass these C objects as inputs to Zig functions.\nAs I described in @sec-c-inputs, we can freely pass these C objects as inputs to C code\nthat we call from our Zig code. But what about passing these C objects to Zig functions?\n\nIn essence, this specific case requires one small adjustment in the Zig function declaration.\nAll you need to do, is to make sure that you pass your C object *by reference* to the function,\ninstead of passing it *by value*. To do that, you have to annotate the data type of the function argument\nthat is receiving this C object as \"a pointer to the C struct\", instead of annotating it as \"an instance of the C struct\".\n\nLet's consider the C struct `User` from the `user.h` C header file that we have used in @sec-c-inputs.\nNow, consider that we want to create a Zig function that sets the value of the `id` field\nin this C struct, like the `set_user_id()` function declared below.\nNotice that the `user` argument in this function is annotated as a pointer (`*`) to a `c.User` object.\n\nTherefore, all you have to do when passing C objects to Zig functions, is to add `*` to the\ndata type of the function argument that is receiving the C object. This will make sure that\nthe C object is passed *by reference* to the function.\n\nBecause we have transformed the function argument into a pointer,\neverytime that you have to access the value pointed by this input pointer inside the function body, for whatever reason (e.g. you want\nto read, update, or delete this value), you have to dereference the pointer with the `.*` syntax that we\nlearned from @sec-pointer. Notice that the `set_user_id()` function is using this syntax to alter\nthe value in the `id` field of the `User` struct pointed by the input pointer.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst c = @cImport({\n    @cInclude(\"user.h\");\n});\nfn set_user_id(id: u64, user: *c.User) void {\n    user.*.id = id;\n}\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n\n    var new_user: c.User = undefined;\n    new_user.id = 1;\n    var user_name = try allocator.alloc(u8, 12);\n    defer allocator.free(user_name);\n    @memcpy(user_name[0..(user_name.len - 1)], \"pedropark99\");\n    user_name[user_name.len - 1] = 0;\n    new_user.name = user_name.ptr;\n\n    set_user_id(25, &new_user);\n    try stdout.print(\"New ID: {any}\\n\", .{new_user.id});\n}\n```\n:::\n\n\n\n\n```\nNew ID: 25\n```\n",
-    "supporting": [
-      "14-zig-c-interop_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Zig interoperability with C\n\nIn this chapter, we are going to discuss the interoperability of Zig with C.\nWe have discussed in @sec-building-c-code how you can use the `zig` compiler to build C code.\nBut we haven't discussed yet how to actually use C code in Zig. In other words,\nwe haven't discussed yet how to call and use C code from Zig.\n\nThis is the main subject of this chapter.\nAlso, in our next small project in this book, we are going to use a C library in it.\nAs consequence, we will put in practice a lot of the knowledge discussed here on\nthis next project.\n\n\n## How to call C code from Zig\n\nInteroperability with C is not something new. Most high-level programming languages have FFI (foreign function interfaces),\nwhich can be used to call C code. For example, Python have Cython, R have `.Call()`, Javascript have `ccall()`, etc.\nBut Zig integrates with C in a deeper level, which affects not only the way that C code gets called, but also,\nhow this C code is compiled and incorporated into your Zig project.\n\nIn summary, Zig have great interoperability with C. If you want to call any C code from Zig,\nyou have to perform the following steps:\n\n- import a C header file into your Zig code.\n- link your Zig code with the C library.\n\n\n### Strategies to import C header files {#sec-strategy-c}\n\nUsing C code in Zig always involves performing the two steps cited above. However, when\nwe talk specifically about the first step listed above, there are currently two\ndifferent ways to perform this first step, which are:\n\n- translating the C header file into Zig code, through the `zig translate-c` command, and then, import and use the translated Zig code.\n- importing the C header file directly into your Zig module through the `@cImport()` built-in function.\n\nIf you are not familiar with `translate-c`, this is a subcommand inside the `zig` compiler that takes C files\nas input, and outputs the Zig representation of the C code present in these C files.\nIn other words, this subcommand works like a transpiler. It takes C code, and translates it into\nthe equivalent Zig code.\n\nI think it would be ok to interpret `translate-c` as a tool to generate Zig bindings\nto C code, similarly to the `rust-bindgen`[^bindgen] tool, which generates Rust FFI bindings to C code.\nBut that would not be a precise interpretation of `translate-c`. The idea behind this tool is\nto really translate the C code into Zig code.\n\n[^bindgen]: <https://github.com/rust-lang/rust-bindgen>\n\nNow, on a surface level, `@cImport()` versus `translate-c` might seem like\ntwo completely different strategies. But in fact, they are effectively the exact same strategy.\nBecause, under the hood, the `@cImport()` built-in function is just a shortcut to `translate-c`.\nBoth tools use the same \"C to Zig\" translation functionality. So when you use `@cImport()`,\nyou are essentially asking the `zig` compiler to translate the C header file into Zig code, then,\nto import this Zig code into your current Zig module.\n\nAt the present moment, there is an accepted proposal at the Zig project, to move `@cImport()`\nto the Zig build system[^cimport-issue]. If this proposal is completed, then, the \"use `@cImport()`\"\nstrategy would be transformed into \"call a translate C function in your Zig build script\".\nSo, the step of translating the C code into Zig code would be moved to\nthe build script of your Zig project, and you would only need to import the translated Zig code into\nyour Zig module to start calling C code from Zig.\n\n[^cimport-issue]: <https://github.com/ziglang/zig/issues/20630>\n\nIf you think about this proposal for a minute, you will understand that this is actually\na small change. I mean, the logic is the same, and the steps are still essentially the same.\nThe only difference is that one of the steps will be moved to the build script of your Zig project.\n\n\n\n### Linking Zig code with a C library {#sec-linking-c}\n\nRegardless of which of the two strategies from the previous section you choose,\nif you want to call C code from Zig, you must link your Zig code\nwith the C library that contains the C code that you want to call.\n\nIn other words, everytime you use some C code in your Zig code, **you introduce a dependency in your build process**.\nThis should come as no surprise to anyone that have any experience with C and C++.\nBecause this is no different in C. Everytime you use a C library in your C code, you also\nhave to build and link your C code with this C library that you are using.\n\nWhen we use a C library in our Zig code, the `zig` compiler needs to access the definition of the C functions that\nare being called in your Zig code. The C header file of this library provides the\ndeclarations of these C functions, but not their definitions. So, in order to access these definitions,\nthe `zig` compiler needs to build your Zig code and link it with the C library during the build process.\n\nAs we discussed across the @sec-build-system, there are different strategies to link something with a library.\nThis might involve building the C library first, and then, linking it with the Zig code. Or,\nit could also involve just the linking step, if this C library is already built and\ninstalled in your system. Anyway, if you have doubts about this, comeback to @sec-build-system.\n\n\n\n## Importing C header files {#sec-import-c-header}\n\nIn @sec-strategy-c, we have described that, currently, there are two different paths that\nyou can take to import a C header file into your Zig modules, `translate-c` or `@cImport()`.\nThis section describes each strategy separately in more details.\n\n### Strategy 1: using `translate-c`\n\nWhen we choose this strategy, we first need to use the `translate-c` tool to translate\nthe C header files that we want to use into Zig code. For example, suppose we wanted to\nuse the `fopen()` C function from the `stdio.h` C header file. We can translate the\n`stdio.h` C header file through the bash command below:\n\n```bash\nzig translate-c /usr/include/stdio.h \\\n    -lc -I/usr/include \\\n    -D_NO_CRT_STDIO_INLINE=1 > c.zig \\\n```\n\nNotice that, in this bash command, we are passing the necessary compiler flags (`-D` to define macros,\n`-l` to link libraries, `-I` to add an \"include path\") to compile and use the `stdio.h` header file.\nAlso notice that we are saving the results of the translation process inside a Zig module called `c.zig`.\n\nTherefore, after running this command, all we have to do is to import this `c.zig` module, and start\ncalling the C functions that you want to call from it. The example below demonstrates that.\nIt's important to remember what we've discussed in @sec-linking-c. In order to compile this\nexample you have to link this code with `libc`, by passing the flag `-lc` to the `zig` compiler.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @import(\"c.zig\");\npub fn main() !void {\n    const x: f32 = 1772.94122;\n    _ = c.printf(\"%.3f\\n\", x);\n}\n```\n:::\n\n\n```\n1772.941\n```\n\n\n### Strategy 2: using `@cImport()`\n\nTo import a C header file into our Zig code, we can use the built-in functions `@cInclude()` and `@cImport()`.\nInside the `@cImport()` function, we open a block (with a pair of curly braces). Inside this block\nwe can (if we need to) include multiple `@cDefine()` calls to define C macros when including this specific C header file.\nBut for the most part, you will probably need to use just a single call inside this block,\nwhich is a call to `@cInclude()`.\n\nThis `@cInclude()` function is equivalent to the `#include` statement in C.\nYou provide the name of the C header that you want to include as input to this `@cInclude()` function,\nthen, in conjunction with `@cImport()`, it will perform the necessary steps\nto include this C header file into your Zig code.\n\nYou should bind the result of `@cImport()` to a constant object, pretty much like you would do with\n`@import()`. You just assign the result to a constant object in your\nZig code, and, as consequence, all C functions, C structs, C macros, etc. that are defined inside the\nC header files will be available through this constant object.\n\nLook at the code example below, where we are importing the Standard I/O C Library (`stdio.h`),\nand calling the `printf()`[^printf] C function. Notice that we have also used in this example the C function `powf()`[^powf],\nwhich comes from the C Math Library (`math.h`).\nIn order to compile this example, you have to link this Zig code with both\nthe C Standard Library and the C Math Library, by passing the flags `-lc` and `-lm`\nto the `zig` compiler.\n\n[^printf]: <https://cplusplus.com/reference/cstdio/printf/>\n[^powf]: <https://en.cppreference.com/w/c/numeric/math/pow>\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n    @cInclude(\"math.h\");\n});\n\npub fn main() !void {\n    const x: f32 = 15.2;\n    const y = c.powf(x, @as(f32, 2.6));\n    _ = c.printf(\"%.3f\\n\", y);\n}\n```\n:::\n\n\n```\n1182.478\n```\n\n\n## About passing Zig values to C functions {#sec-zig-obj-to-c}\n\nZig objects have some intrinsic differences between their C equivalents.\nProbably the most noticeable one is the difference between C strings and Zig strings,\nwhich I described in @sec-zig-strings.\nZig strings are objects that contains both an array of arbitrary bytes and a length value.\nOn the other hand, a C string is usually just a pointer to a null-terminated array of arbitrary bytes.\n\nBecause of these intrinsic differences, in some specific cases, you cannot pass Zig objects directly\nas inputs to C functions before you convert them into C compatible values. However, in some other cases,\nyou are allowed to pass Zig objects and Zig literal values directly as inputs to C functions,\nand everything will work just fine, because the `zig` compiler will handle everything for you.\n\nSo we have two different scenarios being described here. Let's call them \"auto-conversion\" and \"need-conversion\".\nThe \"auto-conversion\" scenario is when the `zig` compiler handles everything for you, and automatically convert your\nZig objects/values into C compatible values. In contrast,\nthe \"need-conversion\" scenario is when you, the programmer, have the responsibility of converting\nthat Zig object into a C compatible value, before passing it to C code.\n\nThere is also a third scenario that is not being described here, which is when you create a C object, or, a C struct, or\na C compatible value in your Zig code, and you pass this C object/value as input to a C function in your Zig code.\nThis scenario will be described later in @sec-c-inputs. In this section, we are focused on the scenarios where\nwe are passing Zig objects/values to C code, instead of C objects/values being passed to C code.\n\n\n### The \"auto-conversion\" scenario\n\nAn \"auto-conversion\" scenario is when the `zig` compiler automatically converts our Zig objects into\nC compatible values for us. This specific scenario happens mostly in two instances:\n\n- with string literal values;\n- with any of the primitive data types that were introduced in @sec-primitive-data-types.\n\nWhen we think about the second instance described above, the `zig` compiler does automatically\nconvert any of the primitive data types into their C equivalents, because the compiler knows how\nto properly convert a `i16` into a `signed short`, or, a `u8` into a `unsigned char`, etc.\nNow, when we think about string literal values, they can be automatically\nconverted into C strings as well, especially because the `zig` compiler does not forces\na specific Zig data type into a string literal at first glance, unless you store this\nstring literal into a Zig object, and explicitly annotate the data type of this object.\n\nThus, with string literal values, the `zig` compiler has more freedom to infer which is the appropriate data type\nto be used in each situation. You could say that the string literal value \"inherits its data type\" depending on the context that\nit's used in. Most of the times, this data type is going to be the type that we commonly associate with Zig strings (`[]const u8`).\nBut it might be a different type depending on the situation. When the `zig` compiler detects that you are providing\na string literal value as input to some C function, the compiler automatically interprets this string\nliteral as a C string value.\n\nAs an example, look at the code exposed below. Here we are using\nthe `fopen()` C function to simply open and close a file. If you do not know how this `fopen()`\nfunction works in C, it takes two C strings as input. But in this code example below, we are passing some\nstring literals written in our Zig code directly as inputs to this `fopen()` C function.\n\nIn other words, we are not doing any conversion from a Zig string to a C string.\nWe are just passing the Zig string literals directly as inputs to the C function. And it works just fine!\nBecause the compiler interprets the string `\"foo.txt\"` as a C string given the current context.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cDefine(\"_NO_CRT_STDIO_INLINE\", \"1\");\n    @cInclude(\"stdio.h\");\n});\n\npub fn main() !void {\n    const file = c.fopen(\"foo.txt\", \"rb\");\n    if (file == null) {\n        @panic(\"Could not open file!\");\n    }\n    if (c.fclose(file) != 0) {\n        return error.CouldNotCloseFileDescriptor;\n    }\n}\n```\n:::\n\n\nLet's make some experiments, by writing the same code in different manners, and we\nsee how this affects the program. As a starting point, let's store the `\"foo.txt\"` string inside\na Zig object, like the `path` object below, and then, we pass this Zig object as input to the `fopen()` C function.\n\nIf we do this, the program still compiles and runs successfully. Notice that I have omitted most of the code in this example below.\nThis is just for brevity reasons, because the remainder of the program is still the same.\nThe only difference between this example and the previous one is just these two lines exposed below.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\nNow, what happens if you give an explicit data type to the `path` object? Well, if I force\nthe `zig` compiler to interpret this `path` object as a Zig string object,\nby annotating the `path` object with the data type `[]const u8`, then, I actually get a compile error\nas demonstrated below. We get this compile error because now I'm forcing the `zig` compiler\nto interpret `path` as a Zig string object.\n\nAccording to the error message, the `fopen()` C function was expecting to receive an\ninput value of type `[*c]const u8` (C string) instead of a value of type `[]const u8` (Zig string).\nIn more details, the type `[*c]const u8` is actually the Zig type representation of a C string.\nThe `[*c]` portion of this type identifies a C pointer. So, this Zig type essentially means: a C pointer to an array (`[*c]`) of\nconstant bytes (`const u8`).\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n```\nt.zig:2:7 error: expected type '[*c]const u8', found '[]const u8':\n    const file = c.fopen(path, \"rb\");\n                         ^~~~\n```\n\nTherefore, when we talk exclusively about string literal values, as long as you don't give an\nexplicit data type to these string literal values, the `zig` compiler should be capable of automatically\nconverting them into C strings as needed.\n\nBut what about using one of the primitive data types that were introduced in @sec-primitive-data-types?\nLet's take code exposed below as an example of that. Here, we are giving some float literal values as input\nto the C function `powf()`. Notice that this code example compiles and runs successfully.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst cmath = @cImport({\n    @cInclude(\"math.h\");\n});\n\npub fn main() !void {\n    const y = cmath.powf(15.68, 2.32);\n    try stdout.print(\"{d}\\n\", .{y});\n}\n```\n:::\n\n\n```\n593.2023\n```\n\nOnce again, because the `zig` compiler does not associate a specific data type with the literal values\n`15.68` and `2.32` at first glance, the compiler can automatically convert these values\ninto their C `float` (or `double`) equivalents, before it passes to the `powf()` C function.\nNow, even if I give an explicit Zig data type to these literal values, by storing them into a Zig object,\nand explicit annotating the type of these objects, the code still compiles and runs successfully.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const x: f32 = 15.68;\n    const y = cmath.powf(x, 2.32);\n    // The remainder of the program\n```\n:::\n\n\n```\n593.2023\n```\n\n\n\n### The \"need-conversion\" scenario\n\nA \"need-conversion\" scenario is when we need to manually convert our Zig objects into C compatible values\nbefore passing them as input to C functions. You will fall in this scenario, when passing Zig string objects\nto C functions.\n\nWe have already seen this specific circumstance in the last `fopen()` example,\nwhich is reproduced below. You can see in this example, that we have given an explicit Zig data type\n(`[]const u8`) to our `path` object, and, as a consequence of that, we have forced the `zig` compiler\nto see this `path` object, as a Zig string object. Therefore, we need now to manually convert\nthis `path` object into a C string before we pass it to `fopen()`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n```\nt.zig:10:26: error: expected type '[*c]const u8', found '[]const u8'\n    const file = c.fopen(path, \"rb\");\n                         ^~~~\n```\n\n\nThere are different ways to convert a Zig string object into a C string.\nOne way to solve this problem is to provide the pointer to the underlying array\nof bytes, instead of providing the Zig object directly as input.\nYou can access this pointer by using the `ptr` property of the Zig string object.\n\nThe code example below demonstrates this strategy. Notice that, by giving the\npointer to the underlying array in `path` through the `ptr` property, we get no compile errors as result\nwhile using the `fopen()` C function.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path: []const u8 = \"foo.txt\";\n    const file = c.fopen(path.ptr, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\nThis strategy works because this pointer to the underlying array found in the `ptr` property,\nis semantically identical to a C pointer to an array of bytes, i.e., a C object of type `*unsigned char`.\nThis is why this option also solves the problem of converting the Zig string into a C string.\n\nAnother option is to explicitly convert the Zig string object into a C pointer by using the\nbuilt-in function `@ptrCast()`. With this function we can convert\nan object of type `[]const u8` into an object of type `[*c]const u8`.\nAs I described at the previous section, the `[*c]` portion of the type\nmeans that it's a C pointer. This strategy is not-recommended. But it's\nuseful to demonstrate the use of `@ptrCast()`.\n\nYou may recall of `@as()` and `@ptrCast()` from @sec-type-cast. Just as a recap,\nthe `@as()` built-in function is used to explicitly convert (or cast) a Zig value\nfrom a type \"x\" into a value of type \"y\". But in our case here, we are converting\na pointer object. Everytime a pointer is involved in some \"type casting operation\" in Zig,\nthe `@ptrCast()` function is involved.\n\nIn the example below, we are using this function to cast our `path` object\ninto a C pointer to an array of bytes. Then, we pass this C pointer as input\nto the `fopen()` function. Notice that this code example compiles successfully\nwith no errors.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\n    const path: []const u8 = \"foo.txt\";\n    const c_path: [*c]const u8 = @ptrCast(path);\n    const file = c.fopen(c_path, \"rb\");\n    // Remainder of the program\n```\n:::\n\n\n\n\n## Creating C objects in Zig {#sec-c-inputs}\n\nCreating C objects, or, in other words, creating instances of C structs in your Zig code\nis actually something quite easy to do. You first need to import the C header file (like I described in @sec-import-c-header) that defines\nthe C struct that you are trying to instantiate in your Zig code. After that, you can just\ncreate a new object in your Zig code, and annotate it with the data type of the C struct.\n\nFor example, suppose we have a C header file called `user.h`, and that this header file is declaring a new struct named `User`.\nThis C header file is exposed below:\n\n```c\n#include <stdint.h>\n\ntypedef struct {\n    uint64_t id;\n    char* name;\n} User;\n```\n\nThis `User` C struct have two distinct fields, or two struct members, named `id` and `name`.\nThe field `id` is an unsigned 64-bit integer value, while the field `name` is just a standard C string.\nNow, suppose that I want to create an instance of this `User` struct in my Zig code.\nI can do that by importing this `user.h` header file into my Zig code, and creating\na new object with type `User`. These steps are reproduced in the code example below.\n\nNotice that I have used the keyword `undefined` in this example. This allows me to\ncreate the `new_user` object without the need to provide an initial value to the object.\nAs consequence, the underlying memory associated with this `new_user` object is uninitialized,\ni.e., the memory is currently populated with \"garbage\" values.\nThus, this expression have the exact same effect of the expression `User new_user;` in C,\nwhich means \"declare a new object named `new_user` of type `User`\".\n\nIt's our responsibility to properly initialize this memory associated with this `new_user` object,\nby assigning valid values to the members (or the fields) of the C struct. In the example below,\nI'm assigning the integer 1 to the member `id`. I am also saving the string `\"pedropark99\"` into the member `name`.\nNotice in this example that I manually add the null character (zero byte) to the end of the allocated array\nfor this string. This null character marks the end of the array in C.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst c = @cImport({\n    @cInclude(\"user.h\");\n});\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n\n    var new_user: c.User = undefined;\n    new_user.id = 1;\n    var user_name = try allocator.alloc(u8, 12);\n    defer allocator.free(user_name);\n    @memcpy(user_name[0..(user_name.len - 1)], \"pedropark99\");\n    user_name[user_name.len - 1] = 0;\n    new_user.name = user_name.ptr;\n}\n```\n:::\n\n\nSo, in this example above, we are manually initializing each field of the C struct.\nWe could say that, in this instance, we are \"manually instantiating\nthe C struct object\". However, when we use C libraries in our Zig code, we rarely need\nto manually instantiate the C structs like that. Only because C libraries\nusually provide a \"constructor function\" in their public APIs. As consequence, we normally rely on\nthese constructor functions to properly initialize the C structs, and\nthe struct fields for us.\n\nFor example, consider the Harfbuzz C library. This a text shaping C library,\nand it works around a \"buffer object\", or, more specifically, an instance of\nthe C struct `hb_buffer_t`. Therefore, we need to create an instance of\nthis C struct if we want to use this C library. Luckily, this library offers\nthe function `hb_buffer_create()`, which we can use to create such object.\nSo the Zig code necessary to create such object would probably look something like this:\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c = @cImport({\n    @cInclude(\"hb.h\");\n});\nvar buf: c.hb_buffer_t = c.hb_buffer_create();\n// Do stuff with the \"buffer object\"\n```\n:::\n\n\nTherefore, we do not need to manually create an instance of the C struct\n`hb_buffer_t` here, and manually assign valid values to each field in this C struct.\nBecause the constructor function `hb_buffer_create()` is doing this heavy job for us.\n\nSince this `buf` object, and also, the `new_user` object from previous examples, are instances of C structs, these\nobjects are by themselves C compatible values. They are C objects defined in our Zig code. As consequence,\nyou can freely pass these objects as input to any C function that expects to receive this type\nof C struct as input. You do not need to use any special syntax, or, to convert them in\nany special manner to use them in C code. This is how we create and use C objects in our Zig code.\n\n\n\n## Passing C structs across Zig functions {#sec-pass-c-structs}\n\nNow that we have learned how to create/declare C objects in our Zig code, we\nneed to learn how to pass these C objects as inputs to Zig functions.\nAs I described in @sec-c-inputs, we can freely pass these C objects as inputs to C code\nthat we call from our Zig code. But what about passing these C objects to Zig functions?\n\nIn essence, this specific case requires one small adjustment in the Zig function declaration.\nAll you need to do, is to make sure that you pass your C object *by reference* to the function,\ninstead of passing it *by value*. To do that, you have to annotate the data type of the function argument\nthat is receiving this C object as \"a pointer to the C struct\", instead of annotating it as \"an instance of the C struct\".\n\nLet's consider the C struct `User` from the `user.h` C header file that we have used in @sec-c-inputs.\nNow, consider that we want to create a Zig function that sets the value of the `id` field\nin this C struct, like the `set_user_id()` function declared below.\nNotice that the `user` argument in this function is annotated as a pointer (`*`) to a `c.User` object.\n\nTherefore, all you have to do when passing C objects to Zig functions, is to add `*` to the\ndata type of the function argument that is receiving the C object. This will make sure that\nthe C object is passed *by reference* to the function.\n\nBecause we have transformed the function argument into a pointer,\neverytime that you have to access the value pointed by this input pointer inside the function body, for whatever reason (e.g. you want\nto read, update, or delete this value), you have to dereference the pointer with the `.*` syntax that we\nlearned from @sec-pointer. Notice that the `set_user_id()` function is using this syntax to alter\nthe value in the `id` field of the `User` struct pointed by the input pointer.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst c = @cImport({\n    @cInclude(\"user.h\");\n});\nfn set_user_id(id: u64, user: *c.User) void {\n    user.*.id = id;\n}\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n\n    var new_user: c.User = undefined;\n    new_user.id = 1;\n    var user_name = try allocator.alloc(u8, 12);\n    defer allocator.free(user_name);\n    @memcpy(user_name[0..(user_name.len - 1)], \"pedropark99\");\n    user_name[user_name.len - 1] = 0;\n    new_user.name = user_name.ptr;\n\n    set_user_id(25, &new_user);\n    try stdout.print(\"New ID: {any}\\n\", .{new_user.id});\n}\n```\n:::\n\n\n```\nNew ID: 25\n```\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/Chapters/15-vectors/execute-results/epub.json b/_freeze/Chapters/15-vectors/execute-results/epub.json
deleted file mode 100644
index 4b0fe519..00000000
--- a/_freeze/Chapters/15-vectors/execute-results/epub.json
+++ /dev/null
@@ -1,21 +0,0 @@
-{
-  "hash": "3da767c3f773d387d2d0a42df4405278",
-  "result": {
-    "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n# Introducing Vectors and SIMD {#sec-vectors-simd}\n\nIn this chapter, I want to discuss vectors in Zig, which are\nrelated to SIMD operations (i.e., they have no relationship with the `std::vector` class\nfrom C++).\n\n## What is SIMD?\n\nSIMD (*Single Instruction/Multiple Data*) is a group of operations that are widely used\non video/audio editing programs, and also in graphics applications. SIMD is not a new technology,\nbut the massive use of SIMD on normal desktop computers is somewhat recent. In the old days, SIMD\nwas only used on \"supercomputer models\".\n\nMost modern CPU models (from AMD, Intel, etc.) these days (either in a desktop or in a\nnotebook model) have support for SIMD operations. So, if you have a very old CPU model installed in your\ncomputer, then, it's possible that you have no support for SIMD operations in your computer.\n\nWhy have people started using SIMD in their software? The answer is performance.\nBut what does SIMD precisely do to achieve better performance? Well, in essence, SIMD operations are a different\nstrategy to get parallel computing in your program, and therefore, make faster calculations.\n\nThe basic idea behind SIMD is to have a single instruction that operates over multiple data\nat the same time. When you perform a normal scalar operation, like for example, four add instructions,\neach addition is performed separately, one after another. But with SIMD, these four add instructions\nare translated into a single instruction, and, as consequence, the four additions are performed\nin parallel, at the same time.\n\nCurrently, the `zig` compiler allows you to apply the following group of operators on vector objects.\nWhen you apply one of these operators on vector objects, SIMD is used to make the calculations, and,\ntherefore, these operators are applied element-wise and in parallel by default.\n\n- Arithmetic (`+`, `-`, `/`, `*`, `@divFloor()`, `@sqrt()`,  `@ceil()`, `@log()`, etc.).\n- Bitwise operators (`>>`, `<<`, `&`, `|`, `~`, etc.).\n- Comparison operators (`<`, `>`, `==`, etc.).\n\n\n## Vectors {#sec-what-vectors}\n\nA SIMD operation is usually performed through a *SIMD intrinsic*, which is just a fancy\nname for a function that performs a SIMD operation. These SIMD intrinsics (or \"SIMD functions\")\nalways operate over a special type of object, which are called \"vectors\". So,\nin order to use SIMD, you have to create a \"vector object\".\n\nA vector object is usually a fixed-sized block of 128 bits (16 bytes).\nAs a consequence, most vectors that you find in the wild are essentially arrays that contains 2 values of 8 bytes each,\nor, 4 values of 4 bytes each, or, 8 values of 2 bytes each, etc.\nHowever, different CPU models may have different extensions (or, \"implementations\") of SIMD,\nwhich may offer more types of vector objects that are bigger in size (256 bits or 512 bits)\nto accomodate more data into a single vector object.\n\nYou can create a new vector object in Zig by using the `@Vector()` built-in function. Inside this function,\nyou specify the vector length (number of elements in the vector), and the data type of the elements\nof the vector. Only primitive data types are supported in these vector objects.\nIn the example below, I'm creating two vector objects (`v1` and `v2`) of 4 elements of type `u32` each.\n\nAlso notice in the example below, that a third vector object (`v3`) is created from the\nsum of the previous two vector objects (`v1` plus `v2`). Therefore,\nmath operations over vector objects take place element-wise by default, because\nthe same operation (in this case, addition) is transformed into a single instruction\nthat is replicated in parallel, across all elements of the vectors.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1 = @Vector(4, u32){4, 12, 37, 9};\nconst v2 = @Vector(4, u32){10, 22, 5, 12};\nconst v3 = v1 + v2;\ntry stdout.print(\"{any}\\n\", .{v3});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 14, 34, 42, 21 }\n```\n\n\n:::\n:::\n\n\n\nThis is how SIMD introduces more performance in your program. Instead of using a for loop\nto iterate through the elements of `v1` and `v2`, and adding them together, one element at a time,\nwe enjoy the benefits of SIMD, which performs all 4 additions in parallel, at the same time.\n\nTherefore, the `@Vector` structure is essentially the Zig representation of SIMD vector objects.\nThe elements in these vector objects will be operated in parallel, if, and only if your current CPU model\nsupports SIMD operations. If your CPU model does not have support for SIMD, then, the `@Vector` structure will\nlikely produce a similar performance from a \"for loop solution\".\n\n\n### Transforming arrays into vectors\n\nThere are different ways to transform a normal array into a vector object.\nYou can either use implicit conversion (which is when you assign the array to\na vector object directly), or, use slices to create a vector object from a normal array.\n\nIn the example below, we are implicitly converting the array `a1` into a vector object (`v1`)\nof length 4. We first explicitly annotate the data type of the vector object,\nand then, we assign the array object to this vector object.\n\nAlso notice in the example below, that a second vector object (`v2`) is also created\nby taking a slice of the array object (`a1`), and then, storing the pointer to this\nslice (`.*`) into this vector object.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a1 = [4]u32{4, 12, 37, 9};\nconst v1: @Vector(4, u32) = a1;\nconst v2: @Vector(2, u32) = a1[1..3].*;\n_ = v1; _ = v2;\n```\n:::\n\n\n\n\nIt's worth emphasizing that only arrays and slices whose sizes\nare compile-time known can be transformed into vectors. Vectors in general\nare structures that work only with compile-time known sizes. Therefore, if\nyou have an array whose size is runtime known, then, you first need to\ncopy it into an array with a compile-time known size, before transforming it into a vector.\n\n\n\n### The `@splat()` function\n\nYou can use the `@splat()` built-in function to create a vector object that is filled\nwith the same value across all of its elements. This function was created to offer a quick\nand easy way to directly convert a scalar value (a.k.a. a single value, like a single character, or a single integer, etc.)\ninto a vector object.\n\nThus, we can use `@splat()` to convert a single value, like the integer `16` into a vector object\nof length 1. But we can also use this function to convert the same integer `16` into a\nvector object of length 10, that is filled with 10 `16` values. The example below demonstrates\nthis idea.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1: @Vector(10, u32) = @splat(16);\ntry stdout.print(\"{any}\\n\", .{v1});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 16, 16, 16, 16, 16, 16, 16, 16, 16, 16 }\n```\n\n\n:::\n:::\n\n\n\n\n\n### Careful with vectors that are too big\n\nAs I described in @sec-what-vectors, each vector object is usually a small block of 128, 256 or 512 bits.\nThis means that a vector object is usually small in size, and when you try to go in the opposite direction,\nby creating a vector object that is very big in size (i.e., sizes that are close to $2^{20}$),\nyou usually end up with crashes and loud errors from the compiler.\n\nFor example, if you try to compile the program below, you will likely face segmentation faults, or LLVM errors during\nthe build process. Just be careful to not create vector objects that are too big in size.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1: @Vector(1000000, u32) = @splat(16);\n_ = v1;\n```\n:::\n\n\n\n```\nSegmentation fault (core dumped)\n```\n",
-    "supporting": [
-      "15-vectors_files"
-    ],
-    "filters": [
-      "rmarkdown/pagebreak.lua"
-    ],
-    "includes": {},
-    "engineDependencies": {
-      "knitr": [
-        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
-      ]
-    },
-    "preserve": null,
-    "postProcess": false
-  }
-}
\ No newline at end of file
diff --git a/_freeze/Chapters/15-vectors/execute-results/html.json b/_freeze/Chapters/15-vectors/execute-results/html.json
index d68d2db0..3e76e5cf 100644
--- a/_freeze/Chapters/15-vectors/execute-results/html.json
+++ b/_freeze/Chapters/15-vectors/execute-results/html.json
@@ -2,10 +2,8 @@
   "hash": "3da767c3f773d387d2d0a42df4405278",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n\n# Introducing Vectors and SIMD {#sec-vectors-simd}\n\nIn this chapter, I want to discuss vectors in Zig, which are\nrelated to SIMD operations (i.e., they have no relationship with the `std::vector` class\nfrom C++).\n\n## What is SIMD?\n\nSIMD (*Single Instruction/Multiple Data*) is a group of operations that are widely used\non video/audio editing programs, and also in graphics applications. SIMD is not a new technology,\nbut the massive use of SIMD on normal desktop computers is somewhat recent. In the old days, SIMD\nwas only used on \"supercomputer models\".\n\nMost modern CPU models (from AMD, Intel, etc.) these days (either in a desktop or in a\nnotebook model) have support for SIMD operations. So, if you have a very old CPU model installed in your\ncomputer, then, it's possible that you have no support for SIMD operations in your computer.\n\nWhy have people started using SIMD in their software? The answer is performance.\nBut what does SIMD precisely do to achieve better performance? Well, in essence, SIMD operations are a different\nstrategy to get parallel computing in your program, and therefore, make faster calculations.\n\nThe basic idea behind SIMD is to have a single instruction that operates over multiple data\nat the same time. When you perform a normal scalar operation, like for example, four add instructions,\neach addition is performed separately, one after another. But with SIMD, these four add instructions\nare translated into a single instruction, and, as consequence, the four additions are performed\nin parallel, at the same time.\n\nCurrently, the `zig` compiler allows you to apply the following group of operators on vector objects.\nWhen you apply one of these operators on vector objects, SIMD is used to make the calculations, and,\ntherefore, these operators are applied element-wise and in parallel by default.\n\n- Arithmetic (`+`, `-`, `/`, `*`, `@divFloor()`, `@sqrt()`,  `@ceil()`, `@log()`, etc.).\n- Bitwise operators (`>>`, `<<`, `&`, `|`, `~`, etc.).\n- Comparison operators (`<`, `>`, `==`, etc.).\n\n\n## Vectors {#sec-what-vectors}\n\nA SIMD operation is usually performed through a *SIMD intrinsic*, which is just a fancy\nname for a function that performs a SIMD operation. These SIMD intrinsics (or \"SIMD functions\")\nalways operate over a special type of object, which are called \"vectors\". So,\nin order to use SIMD, you have to create a \"vector object\".\n\nA vector object is usually a fixed-sized block of 128 bits (16 bytes).\nAs a consequence, most vectors that you find in the wild are essentially arrays that contains 2 values of 8 bytes each,\nor, 4 values of 4 bytes each, or, 8 values of 2 bytes each, etc.\nHowever, different CPU models may have different extensions (or, \"implementations\") of SIMD,\nwhich may offer more types of vector objects that are bigger in size (256 bits or 512 bits)\nto accomodate more data into a single vector object.\n\nYou can create a new vector object in Zig by using the `@Vector()` built-in function. Inside this function,\nyou specify the vector length (number of elements in the vector), and the data type of the elements\nof the vector. Only primitive data types are supported in these vector objects.\nIn the example below, I'm creating two vector objects (`v1` and `v2`) of 4 elements of type `u32` each.\n\nAlso notice in the example below, that a third vector object (`v3`) is created from the\nsum of the previous two vector objects (`v1` plus `v2`). Therefore,\nmath operations over vector objects take place element-wise by default, because\nthe same operation (in this case, addition) is transformed into a single instruction\nthat is replicated in parallel, across all elements of the vectors.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1 = @Vector(4, u32){4, 12, 37, 9};\nconst v2 = @Vector(4, u32){10, 22, 5, 12};\nconst v3 = v1 + v2;\ntry stdout.print(\"{any}\\n\", .{v3});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 14, 34, 42, 21 }\n```\n\n\n:::\n:::\n\n\n\n\nThis is how SIMD introduces more performance in your program. Instead of using a for loop\nto iterate through the elements of `v1` and `v2`, and adding them together, one element at a time,\nwe enjoy the benefits of SIMD, which performs all 4 additions in parallel, at the same time.\n\nTherefore, the `@Vector` structure is essentially the Zig representation of SIMD vector objects.\nThe elements in these vector objects will be operated in parallel, if, and only if your current CPU model\nsupports SIMD operations. If your CPU model does not have support for SIMD, then, the `@Vector` structure will\nlikely produce a similar performance from a \"for loop solution\".\n\n\n### Transforming arrays into vectors\n\nThere are different ways to transform a normal array into a vector object.\nYou can either use implicit conversion (which is when you assign the array to\na vector object directly), or, use slices to create a vector object from a normal array.\n\nIn the example below, we are implicitly converting the array `a1` into a vector object (`v1`)\nof length 4. We first explicitly annotate the data type of the vector object,\nand then, we assign the array object to this vector object.\n\nAlso notice in the example below, that a second vector object (`v2`) is also created\nby taking a slice of the array object (`a1`), and then, storing the pointer to this\nslice (`.*`) into this vector object.\n\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a1 = [4]u32{4, 12, 37, 9};\nconst v1: @Vector(4, u32) = a1;\nconst v2: @Vector(2, u32) = a1[1..3].*;\n_ = v1; _ = v2;\n```\n:::\n\n\n\n\n\nIt's worth emphasizing that only arrays and slices whose sizes\nare compile-time known can be transformed into vectors. Vectors in general\nare structures that work only with compile-time known sizes. Therefore, if\nyou have an array whose size is runtime known, then, you first need to\ncopy it into an array with a compile-time known size, before transforming it into a vector.\n\n\n\n### The `@splat()` function\n\nYou can use the `@splat()` built-in function to create a vector object that is filled\nwith the same value across all of its elements. This function was created to offer a quick\nand easy way to directly convert a scalar value (a.k.a. a single value, like a single character, or a single integer, etc.)\ninto a vector object.\n\nThus, we can use `@splat()` to convert a single value, like the integer `16` into a vector object\nof length 1. But we can also use this function to convert the same integer `16` into a\nvector object of length 10, that is filled with 10 `16` values. The example below demonstrates\nthis idea.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1: @Vector(10, u32) = @splat(16);\ntry stdout.print(\"{any}\\n\", .{v1});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 16, 16, 16, 16, 16, 16, 16, 16, 16, 16 }\n```\n\n\n:::\n:::\n\n\n\n\n\n\n### Careful with vectors that are too big\n\nAs I described in @sec-what-vectors, each vector object is usually a small block of 128, 256 or 512 bits.\nThis means that a vector object is usually small in size, and when you try to go in the opposite direction,\nby creating a vector object that is very big in size (i.e., sizes that are close to $2^{20}$),\nyou usually end up with crashes and loud errors from the compiler.\n\nFor example, if you try to compile the program below, you will likely face segmentation faults, or LLVM errors during\nthe build process. Just be careful to not create vector objects that are too big in size.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1: @Vector(1000000, u32) = @splat(16);\n_ = v1;\n```\n:::\n\n\n\n\n```\nSegmentation fault (core dumped)\n```\n",
-    "supporting": [
-      "15-vectors_files"
-    ],
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Introducing Vectors and SIMD {#sec-vectors-simd}\n\nIn this chapter, I want to discuss vectors in Zig, which are\nrelated to SIMD operations (i.e., they have no relationship with the `std::vector` class\nfrom C++).\n\n## What is SIMD?\n\nSIMD (*Single Instruction/Multiple Data*) is a group of operations that are widely used\non video/audio editing programs, and also in graphics applications. SIMD is not a new technology,\nbut the massive use of SIMD on normal desktop computers is somewhat recent. In the old days, SIMD\nwas only used on \"supercomputer models\".\n\nMost modern CPU models (from AMD, Intel, etc.) these days (either in a desktop or in a\nnotebook model) have support for SIMD operations. So, if you have a very old CPU model installed in your\ncomputer, then, it's possible that you have no support for SIMD operations in your computer.\n\nWhy have people started using SIMD in their software? The answer is performance.\nBut what does SIMD precisely do to achieve better performance? Well, in essence, SIMD operations are a different\nstrategy to get parallel computing in your program, and therefore, make faster calculations.\n\nThe basic idea behind SIMD is to have a single instruction that operates over multiple data\nat the same time. When you perform a normal scalar operation, like for example, four add instructions,\neach addition is performed separately, one after another. But with SIMD, these four add instructions\nare translated into a single instruction, and, as consequence, the four additions are performed\nin parallel, at the same time.\n\nCurrently, the `zig` compiler allows you to apply the following group of operators on vector objects.\nWhen you apply one of these operators on vector objects, SIMD is used to make the calculations, and,\ntherefore, these operators are applied element-wise and in parallel by default.\n\n- Arithmetic (`+`, `-`, `/`, `*`, `@divFloor()`, `@sqrt()`,  `@ceil()`, `@log()`, etc.).\n- Bitwise operators (`>>`, `<<`, `&`, `|`, `~`, etc.).\n- Comparison operators (`<`, `>`, `==`, etc.).\n\n\n## Vectors {#sec-what-vectors}\n\nA SIMD operation is usually performed through a *SIMD intrinsic*, which is just a fancy\nname for a function that performs a SIMD operation. These SIMD intrinsics (or \"SIMD functions\")\nalways operate over a special type of object, which are called \"vectors\". So,\nin order to use SIMD, you have to create a \"vector object\".\n\nA vector object is usually a fixed-sized block of 128 bits (16 bytes).\nAs a consequence, most vectors that you find in the wild are essentially arrays that contains 2 values of 8 bytes each,\nor, 4 values of 4 bytes each, or, 8 values of 2 bytes each, etc.\nHowever, different CPU models may have different extensions (or, \"implementations\") of SIMD,\nwhich may offer more types of vector objects that are bigger in size (256 bits or 512 bits)\nto accomodate more data into a single vector object.\n\nYou can create a new vector object in Zig by using the `@Vector()` built-in function. Inside this function,\nyou specify the vector length (number of elements in the vector), and the data type of the elements\nof the vector. Only primitive data types are supported in these vector objects.\nIn the example below, I'm creating two vector objects (`v1` and `v2`) of 4 elements of type `u32` each.\n\nAlso notice in the example below, that a third vector object (`v3`) is created from the\nsum of the previous two vector objects (`v1` plus `v2`). Therefore,\nmath operations over vector objects take place element-wise by default, because\nthe same operation (in this case, addition) is transformed into a single instruction\nthat is replicated in parallel, across all elements of the vectors.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1 = @Vector(4, u32){4, 12, 37, 9};\nconst v2 = @Vector(4, u32){10, 22, 5, 12};\nconst v3 = v1 + v2;\ntry stdout.print(\"{any}\\n\", .{v3});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 14, 34, 42, 21 }\n```\n\n\n:::\n:::\n\n\nThis is how SIMD introduces more performance in your program. Instead of using a for loop\nto iterate through the elements of `v1` and `v2`, and adding them together, one element at a time,\nwe enjoy the benefits of SIMD, which performs all 4 additions in parallel, at the same time.\n\nTherefore, the `@Vector` structure is essentially the Zig representation of SIMD vector objects.\nThe elements in these vector objects will be operated in parallel, if, and only if your current CPU model\nsupports SIMD operations. If your CPU model does not have support for SIMD, then, the `@Vector` structure will\nlikely produce a similar performance from a \"for loop solution\".\n\n\n### Transforming arrays into vectors\n\nThere are different ways to transform a normal array into a vector object.\nYou can either use implicit conversion (which is when you assign the array to\na vector object directly), or, use slices to create a vector object from a normal array.\n\nIn the example below, we are implicitly converting the array `a1` into a vector object (`v1`)\nof length 4. We first explicitly annotate the data type of the vector object,\nand then, we assign the array object to this vector object.\n\nAlso notice in the example below, that a second vector object (`v2`) is also created\nby taking a slice of the array object (`a1`), and then, storing the pointer to this\nslice (`.*`) into this vector object.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst a1 = [4]u32{4, 12, 37, 9};\nconst v1: @Vector(4, u32) = a1;\nconst v2: @Vector(2, u32) = a1[1..3].*;\n_ = v1; _ = v2;\n```\n:::\n\n\n\nIt's worth emphasizing that only arrays and slices whose sizes\nare compile-time known can be transformed into vectors. Vectors in general\nare structures that work only with compile-time known sizes. Therefore, if\nyou have an array whose size is runtime known, then, you first need to\ncopy it into an array with a compile-time known size, before transforming it into a vector.\n\n\n\n### The `@splat()` function\n\nYou can use the `@splat()` built-in function to create a vector object that is filled\nwith the same value across all of its elements. This function was created to offer a quick\nand easy way to directly convert a scalar value (a.k.a. a single value, like a single character, or a single integer, etc.)\ninto a vector object.\n\nThus, we can use `@splat()` to convert a single value, like the integer `16` into a vector object\nof length 1. But we can also use this function to convert the same integer `16` into a\nvector object of length 10, that is filled with 10 `16` values. The example below demonstrates\nthis idea.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1: @Vector(10, u32) = @splat(16);\ntry stdout.print(\"{any}\\n\", .{v1});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n{ 16, 16, 16, 16, 16, 16, 16, 16, 16, 16 }\n```\n\n\n:::\n:::\n\n\n\n\n### Careful with vectors that are too big\n\nAs I described in @sec-what-vectors, each vector object is usually a small block of 128, 256 or 512 bits.\nThis means that a vector object is usually small in size, and when you try to go in the opposite direction,\nby creating a vector object that is very big in size (i.e., sizes that are close to $2^{20}$),\nyou usually end up with crashes and loud errors from the compiler.\n\nFor example, if you try to compile the program below, you will likely face segmentation faults, or LLVM errors during\nthe build process. Just be careful to not create vector objects that are too big in size.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst v1: @Vector(1000000, u32) = @splat(16);\n_ = v1;\n```\n:::\n\n\n```\nSegmentation fault (core dumped)\n```\n",
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],
diff --git a/_freeze/index/execute-results/epub.json b/_freeze/index/execute-results/epub.json
deleted file mode 100644
index 4df3471d..00000000
--- a/_freeze/index/execute-results/epub.json
+++ /dev/null
@@ -1,21 +0,0 @@
-{
-  "hash": "0b80ffe49bae68e2641a31569b9e19df",
-  "result": {
-    "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy a PDF, eBook or a physical copy\nof the book, either at Amazon, or at Leanpub:\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://leanpub.com/introductiontozigaproject-basedbook\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Leanpub!\n    </button>\n</a>\n\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e., open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.\nCurrently, he is a Senior Data Engineer at [DSM-Firmenich](https://www.dsm-firmenich.com)[^dsm], and\na Databricks Certified Associate Developer for Apache Spark 3.0.\n\n[^dsm]: <https://www.dsm-firmenich.com>\n\n\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nBrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer who loves to learn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2025 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n\n- System version: Linux, 6.12.21-4-MANJARO, NA, x86_64.\n- Zig version: 0.15.0-dev.635+7dbd21bd5.\n- Quarto version: 1.4.554.\n\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang), Tommaso Ricci (\\@Zorgatone), Primo Sabatini (\\@primos63), Santiago Fernandez (\\@santif), Hamza Wahed (\\@HamzaWahed), mwilbur (\\@mwilbur), Dima Budaragin (\\@dbud), Jorge Jímenez (\\@jorge-j1m), Alexander (\\@alexwheezy), Maarten Coopens (\\@maarteNNNN), Niklas Johansson (\\@Raphexion), glystik (\\@glystik), Michael Lynch (\\@mtlynch), Yashank (\\@stickyburn), _blf_ (\\@bengtfrost)\n",
-    "supporting": [
-      "index_files"
-    ],
-    "filters": [
-      "rmarkdown/pagebreak.lua"
-    ],
-    "includes": {},
-    "engineDependencies": {
-      "knitr": [
-        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
-      ]
-    },
-    "preserve": null,
-    "postProcess": false
-  }
-}
\ No newline at end of file
diff --git a/_freeze/index/execute-results/html.json b/_freeze/index/execute-results/html.json
index f43fa582..affa01a2 100644
--- a/_freeze/index/execute-results/html.json
+++ b/_freeze/index/execute-results/html.json
@@ -1,8 +1,8 @@
 {
-  "hash": "0b80ffe49bae68e2641a31569b9e19df",
+  "hash": "826210be244a6e675fa884a125b3c0f1",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n::: {.content-visible when-format=\"html\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy a PDF, eBook or a physical copy\nof the book, either at Amazon, or at Leanpub:\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://leanpub.com/introductiontozigaproject-basedbook\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Leanpub!\n    </button>\n</a>\n\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e., open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.\nCurrently, he is a Senior Data Engineer at [DSM-Firmenich](https://www.dsm-firmenich.com)[^dsm], and\na Databricks Certified Associate Developer for Apache Spark 3.0.\n\n[^dsm]: <https://www.dsm-firmenich.com>\n\n\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nBrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer who loves to learn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2025 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n- System version: Linux, 6.12.21-4-MANJARO, NA, x86_64.\n- Zig version: 0.15.0-dev.635+7dbd21bd5.\n- Quarto version: 1.4.554.\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang), Tommaso Ricci (\\@Zorgatone), Primo Sabatini (\\@primos63), Santiago Fernandez (\\@santif), Hamza Wahed (\\@HamzaWahed), mwilbur (\\@mwilbur), Dima Budaragin (\\@dbud), Jorge Jímenez (\\@jorge-j1m), Alexander (\\@alexwheezy), Maarten Coopens (\\@maarteNNNN), Niklas Johansson (\\@Raphexion), glystik (\\@glystik), Michael Lynch (\\@mtlynch), Yashank (\\@stickyburn), _blf_ (\\@bengtfrost)\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n:::: {.content-hidden when-format=\"epub\"}\n::: {.content-hidden when-format=\"pdf\"}\n\n# Welcome {.unnumbered}\n\nWelcome! This is the initial page for the \"Open Access\" HTML version of the book \"Introduction to Zig: a project-based book\",\nwritten by [Pedro Duarte Faria](https://pedro-faria.netlify.app/).\nThis is an open book that provides an introduction to the [Zig programming language](https://ziglang.org/),\nwhich is a new general-purpose, and low-level language for building robust and optimal software.\n\n## Support the project! {.unnumbered}\n\nIf you like this project, and you want to support it, you can buy a PDF, eBook or a physical copy\nof the book, either at Amazon, or at Leanpub:\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://www.amazon.com/dp/B0DJYMDRLP\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Amazon!\n    </button>\n</a>\n\n<style>\n  .btn {\n    border-radius: 5px;\n    background-color: #4f73e8;\n    border: #4f73e8;\n    opacity: 1;\n    transition: 0.3s;\n  }\n\n  .btn:hover {\n    background-color: #2144b6;\n    border: #2144b6;\n  }\n</style>\n\n\n<a href=\"https://leanpub.com/introductiontozigaproject-basedbook\">\n    <button class=\"btn btn-primary\" type=\"button\">\n\tBuy the book on Leanpub!\n    </button>\n</a>\n\n\n\n\n### Sending donations directly\n\nYou can also donate some amount directly to the author of the project via:\n\n- PayPal Donation.\n- Revolut.\n\nThese are good ways to support directly the author of the project, which helps to foster\nmore contents like this, and it makes possible for the author to keep writing helpful tools and\nmaterials for the community.\n\n### PayPal\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"https://www.paypal.com/donate/?business=D58J5LFEERC3N&no_recurring=0&item_name=These+donations+make+it+possible+for+me+to+continue+writing+new+and+useful+content+for+our+community%F0%9F%98%89+Thank+you%21%E2%9D%A4%EF%B8%8F%F0%9F%A5%B3&currency_code=USD\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Donate via PayPal 💵\n      </button>\n  </a>\n  \n\n\n\n### Revolut\n\nYou can send money via Swift Payment with the following bank and Swift details:\n\n```\nRecipient: Pedro Duarte Faria\nBIC/SWIFT Code: REVOSGS2\nAccount number: 6124512226\nName and address of the bank: Revolut Technologies Singapore Pte. Ltd, 6 Battery Road, Floor 6-01, 049909, Singapore, Singapore\nCorresponding BIC: CHASGB2L\n```\n\nIf you do have a Revolut account, you can scan the following QR code:\n\n<style>\n    .btn {\n      border-radius: 5px;\n      background-color: #4f73e8;\n      border: #4f73e8;\n      opacity: 1;\n      transition: 0.3s;\n    }\n  \n    .btn:hover {\n      background-color: #2144b6;\n      border: #2144b6;\n    }\n  </style>\n  \n  \n  <a href=\"http://revolut.me/pedroduartefaria\">\n      <button class=\"btn btn-primary\" type=\"button\">\n      Revolut QR Code 💵\n      </button>\n  </a>\n\n\n\n:::\n::::\n\n\n## About this book {.unnumbered}\n\nThis an open (i.e., open-source), technical and introductory book for the [Zig programming language](https://ziglang.org/),\nwhich is a new general purpose, and low-level programming language for building optimal and robust software.\n\nOfficial repository of the book: <https://github.com/pedropark99/zig-book>.\n\nThis book is designed for both beginners and experienced developers. It explores the exciting world of Zig through small\nand simple projects (in a similar style to the famous \"Python Crash Course\" book from Eric Matthes).\nSome of these projects are: a Base64 encoder/decoder, a HTTP Server and an image filter.\n\nAs you work through the book, you will learn:\n\n- The syntax of the language, and how it compares to C, C++ and Rust.\n- Data structures, memory allocators, filesystem and I/O.\n- Optionals as a new paradigm to handle nullability.\n- How to test and debug a Zig application.\n- Errors as values, and how to handle them.\n- How to build C and Zig code with the build system that is embedded into the language.\n- Zig interoperability with C.\n- Parallelism with threads and SIMD.\n- And more.\n\n\n## About the author {.unnumbered}\n\nPedro Duarte Faria has a bachelor's degree in Economics from the Federal University of Ouro Preto - Brazil.\nCurrently, he is a Senior Data Engineer at [DSM-Firmenich](https://www.dsm-firmenich.com)[^dsm], and\na Databricks Certified Associate Developer for Apache Spark 3.0.\n\n[^dsm]: <https://www.dsm-firmenich.com>\n\n\nThe author has more than 4 years of experience in the data industry, developing data products, pipelines,\nreports and analysis for research institutions and some of the largest companies in the\nBrazilian financial sector, such as the BMG Bank, Sodexo and Pan Bank.\n\nBut Pedro is also a passionate software developer who loves to learn and teach about programming.\nAlthough Pedro uses many different languages in his work, he is specialized in the R programming language, and have given several\nlectures and courses about it, inside graduate centers (such as PPEA-UFOP^[<https://ppea.ufop.br/>]),\nin addition to federal and state organizations (such as FJP-MG^[<http://fjp.mg.gov.br/>]).\n\n\nPersonal Website: <https://pedro-faria.netlify.app/>\n\nLinkedin: <https://www.linkedin.com/in/pedro-faria-a68140209/>\n\nMastodon: [\\@pedropark99\\@fosstodon.org](https://fosstodon.org/@pedropark99)\n\nTwitter (X): [\\@PedroPark9](https://twitter.com/PedroPark9)\n\n## License {.unnumbered}\n\nCopyright © 2025 Pedro Duarte Faria. This book is licensed by the [CC-BY 4.0 Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/)[^cc-license].\n\n[^cc-license]: <https://creativecommons.org/licenses/by/4.0/>\n\n![](Figures/creative-commoms-88x31.png){width=88px}\n\n\n## Book compilation metadata {.unnumbered}\n\nThis book was compiled using the following versions of [Zig](https://ziglang.org) and [Quarto](https://quarto.org):\n\n\n- System version: Linux, 6.12.21-4-MANJARO, NA, x86_64.\n- Zig version: 0.15.0-dev.635+7dbd21bd5.\n- Quarto version: 1.4.554.\n\n\n## Book citation {.unnumbered}\n\nYou can use the following BibTex entry to cite this book:\n\n```\n@book{pedro2024,\n    author = {Pedro Duarte Faria},\n    title = {Introduction to Zig},\n    subtitle = {a project-based book},\n    month = {October},\n    edition = {1},\n    year = {2024},\n    address = {Belo Horizonte},\n    url = {https://github.com/pedropark99/zig-book}\n}\n```\n\n## Corresponding author and maintainer {.unnumbered}\n\nPedro Duarte Faria\n\nContact: [pedropark99\\@gmail.com](mailto:pedropark99@gmail.com)\n\nPersonal website: <https://pedro-faria.netlify.app/>\n\n\n## Acknowledgments {.unnumbered}\n\nThis book is also a product of many conversations and exchanges that we had\nwith different people from the Zig community. I (Pedro Duarte Faria) am incredibly\ngrateful for these conversations, and also, for some direct contributions that we\nhad. Below we have a list of the people involved (name of the person with their usename in GitHub):\n\n\nCalin Martinconi (\\@martinconic), Steffen Roller (\\@sroller), Chris Boesch (\\@chrboesch), Lv Sihan (\\@Pokryton), saurabh sharma. (\\@esskayesss), slackline (\\@slackline), Markus Kurz (\\@kurz-m), Rubin Simons (\\@rubin55), Chris Boesch (\\@chrboesch), Bruno (\\@PoorlyDefinedBehaviour), Ilia Choly (\\@icholy), Korri Katti (\\@KorryKatti), Vedang Manerikar (\\@vedang), Tommaso Ricci (\\@Zorgatone), Primo Sabatini (\\@primos63), Santiago Fernandez (\\@santif), Hamza Wahed (\\@HamzaWahed), mwilbur (\\@mwilbur), Dima Budaragin (\\@dbud), Jorge Jímenez (\\@jorge-j1m), Alexander (\\@alexwheezy), Maarten Coopens (\\@maarteNNNN), Niklas Johansson (\\@Raphexion), glystik (\\@glystik), Michael Lynch (\\@mtlynch), Yashank (\\@stickyburn), _blf_ (\\@bengtfrost)\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
diff --git a/_freeze/references/execute-results/epub.json b/_freeze/references/execute-results/epub.json
deleted file mode 100644
index eb15b841..00000000
--- a/_freeze/references/execute-results/epub.json
+++ /dev/null
@@ -1,21 +0,0 @@
-{
-  "hash": "b3fb07f33430db017c1afb683e34205a",
-  "result": {
-    "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n::::: {.content-visible when-format=\"html\"}\n\n# References {.unnumbered}\n\n::: {#refs}\n:::\n\n:::::\n",
-    "supporting": [
-      "references_files"
-    ],
-    "filters": [
-      "rmarkdown/pagebreak.lua"
-    ],
-    "includes": {},
-    "engineDependencies": {
-      "knitr": [
-        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
-      ]
-    },
-    "preserve": null,
-    "postProcess": false
-  }
-}
\ No newline at end of file
diff --git a/_freeze/references/execute-results/html.json b/_freeze/references/execute-results/html.json
index ffc66cd5..f3e4a7c4 100644
--- a/_freeze/references/execute-results/html.json
+++ b/_freeze/references/execute-results/html.json
@@ -2,7 +2,7 @@
   "hash": "b3fb07f33430db017c1afb683e34205a",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n\n::::: {.content-visible when-format=\"html\"}\n\n# References {.unnumbered}\n\n::: {#refs}\n:::\n\n:::::\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"./Assets/zig.xml\"\n---\n\n\n\n\n\n\n::::: {.content-visible when-format=\"html\"}\n\n# References {.unnumbered}\n\n::: {#refs}\n:::\n\n:::::\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
diff --git a/_quarto.yml b/_quarto.yml
index 0bcbbafc..e12537fe 100644
--- a/_quarto.yml
+++ b/_quarto.yml
@@ -42,4 +42,7 @@ format:
     theme:
       light: cosmo
       dark: darkly
-
+  # epub:
+  #   toc: true
+  #   lang: en-US
+  #   date: "today"
diff --git a/docs/Chapters/03-structs.html b/docs/Chapters/03-structs.html
index 3be7925a..e9a0480d 100644
--- a/docs/Chapters/03-structs.html
+++ b/docs/Chapters/03-structs.html
@@ -476,7 +476,10 @@ <h4 data-number="2.1.2.4" class="anchored" data-anchor-id="labeled-switch-statem
 </section>
 <section id="sec-defer" class="level3" data-number="2.1.3">
 <h3 data-number="2.1.3" class="anchored" data-anchor-id="sec-defer"><span class="header-section-number">2.1.3</span> The <code>defer</code> keyword</h3>
-<p>With the <code>defer</code> keyword you can register an expression to be executed when you exit the current scope. Therefore, this keyword has a similar functionality as the <code>on.exit()</code> function from R. Take the <code>foo()</code> function below as an example. When we execute this <code>foo()</code> function, the expression that prints the message “Exiting function …” is getting executed only when the function exits its scope.</p>
+<p>Zig has a <code>defer</code> keyword, which plays a very important role in control flow, and also, in releasing resources. In summary, the <code>defer</code> keyword allows you to register an expression to be executed when you exit the current scope.</p>
+<p>At this point, you might attempt to compare the Zig <code>defer</code> keyword to it’s sibling in the Go language (i.e.&nbsp;<a href="https://go.dev/tour/flowcontrol/12">Go also has a <code>defer</code> keyword</a>). However, the Go <code>defer</code> keyword behaves slightly different than it’s sibling in Zig. More specifically, the <code>defer</code> keyword in Go always move an expression to be executed at the <strong>exit of the current function</strong>.</p>
+<p>If you think deeply about this statement, you will notice that the “exit of the current function” is something slightly different than the “exit of the current scope”. So, just be careful when comparing the two keywords together. A single function in Zig might contain many different scopes inside of it, and, therefore, the <code>defer</code> input expression might be executed at different places of the function, depending on which scope you are currently in.</p>
+<p>As a first example, consider the <code>foo()</code> function exposed below. When we execute this <code>foo()</code> function, the expression that prints the message “Exiting function …” is getting executed only when the function exits its scope.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb11"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> std = <span class="bu">@import</span>(<span class="st">"std"</span>);</span>
 <span id="cb11-2"><a href="#cb11-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> stdout = std.io.getStdOut().writer();</span>
@@ -988,7 +991,7 @@ <h2 data-number="2.5" class="anchored" data-anchor-id="sec-type-cast"><span clas
 <span id="cb57-6"><a href="#cb57-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(y) == <span class="dt">u32</span>);</span>
 <span id="cb57-7"><a href="#cb57-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file3fc93b4ea641.test_0...OKAll 1 tests passed
+<pre><code>1/1 file26f81ac33a52.test_0...OKAll 1 tests passed
   d.</code></pre>
 </div>
 </div>
@@ -1005,7 +1008,7 @@ <h2 data-number="2.5" class="anchored" data-anchor-id="sec-type-cast"><span clas
 <span id="cb59-6"><a href="#cb59-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(y) == <span class="dt">f32</span>);</span>
 <span id="cb59-7"><a href="#cb59-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file3fc91795a712.test_0...OKAll 1 tests passed
+<pre><code>1/1 file26f81f277e9b.test_0...OKAll 1 tests passed
   d.</code></pre>
 </div>
 </div>
@@ -1022,7 +1025,7 @@ <h2 data-number="2.5" class="anchored" data-anchor-id="sec-type-cast"><span clas
 <span id="cb61-8"><a href="#cb61-8" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect(<span class="bu">@TypeOf</span>(u32_ptr) == *<span class="kw">const</span> <span class="dt">u32</span>);</span>
 <span id="cb61-9"><a href="#cb61-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file3fc945f8b4b0.test_0...OKAll 1 tests passed
+<pre><code>1/1 file26f843ae7baf.test_0...OKAll 1 tests passed
   d.</code></pre>
 </div>
 </div>
diff --git a/docs/Chapters/03-unittests.html b/docs/Chapters/03-unittests.html
index 817670da..4e62a2cc 100644
--- a/docs/Chapters/03-unittests.html
+++ b/docs/Chapters/03-unittests.html
@@ -323,7 +323,7 @@ <h2 data-number="8.1" class="anchored" data-anchor-id="introducing-the-test-bloc
 <span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expect((a + b) == <span class="dv">4</span>);</span>
 <span id="cb1-7"><a href="#cb1-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file81c21dbf264e.test.testing simple sum...OKA
+<pre><code>1/1 file1ed835512cf8.test.testing simple sum...OKA
   All 1 tests passed.</code></pre>
 </div>
 </div>
@@ -396,7 +396,7 @@ <h2 data-number="8.4" class="anchored" data-anchor-id="testing-errors"><span cla
 <span id="cb7-14"><a href="#cb7-14" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> expectError(<span class="kw">error</span>.OutOfMemory, alloc_error(allocator));</span>
 <span id="cb7-15"><a href="#cb7-15" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file81c24fea00d1.test.testing error...OKAll 1 
+<pre><code>1/1 file1ed878d2d839.test.testing error...OKAll 1 
    tests passed.</code></pre>
 </div>
 </div>
@@ -433,8 +433,8 @@ <h2 data-number="8.5" class="anchored" data-anchor-id="testing-simple-equalities
 <span id="cb11-7"><a href="#cb11-7" aria-hidden="true" tabindex="-1"></a>    );</span>
 <span id="cb11-8"><a href="#cb11-8" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file81c25513148.test.arrays are equal?...OKAll
-  l 1 tests passed.</code></pre>
+<pre><code>1/1 file1ed83cbad6df.test.arrays are equal?...OKAl
+  ll 1 tests passed.</code></pre>
 </div>
 </div>
 <p>At last, you might also want to use the <code>expectEqualStrings()</code> function. As the name suggests, you can use this function to test if two strings are equal or not. Just provide the two string objects that you want to compare, as inputs to the function.</p>
diff --git a/docs/Chapters/05-pointers.html b/docs/Chapters/05-pointers.html
index 6a2731b5..d1341251 100644
--- a/docs/Chapters/05-pointers.html
+++ b/docs/Chapters/05-pointers.html
@@ -450,7 +450,7 @@ <h2 data-number="6.3" class="anchored" data-anchor-id="pointer-arithmetic"><span
 <h2 data-number="6.4" class="anchored" data-anchor-id="optionals-and-optional-pointers"><span class="header-section-number">6.4</span> Optionals and Optional Pointers</h2>
 <p>Let’s talk about optionals and how they relate to pointers in Zig. By default, objects in Zig are <strong>non-nullable</strong>. This means that, in Zig, you can safely assume that any object in your source code is not null.</p>
 <p>This is a powerful feature of Zig when you compare it to the developer experience in C. Because in C, any object can be null at any point, and, as consequence, a pointer in C might point to a null value. This is a common source of undefined behaviour in C. When programmers work with pointers in C, they have to constantly check if their pointers are pointing to null values or not.</p>
-<p>If for some reason, your Zig code produces a null value somewhere, and, this null value ends up in an object that is non-nullable, a runtime error is always raised by your Zig program. Take the program below as an example. The <code>zig</code> compiler can see the <code>null</code> value at compile time, and, as result, it raises a compile time error. But, if a <code>null</code> value is raised during runtime, a runtime error is also raised by the Zig program, with a “attempt to use null value” message.</p>
+<p>In contrast, when working in Zig, if for some reason, your Zig code produces a null value somewhere, and, this null value ends up in an object that is non-nullable, a runtime error is always raised by your Zig program. Take the program below as an example. The <code>zig</code> compiler can see the <code>null</code> value at compile time, and, as result, it raises a compile time error. But, if a <code>null</code> value is raised during runtime, a runtime error is also raised by the Zig program, with a “attempt to use null value” message.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb17"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> number: <span class="dt">u8</span> = <span class="dv">5</span>;</span>
 <span id="cb17-2"><a href="#cb17-2" aria-hidden="true" tabindex="-1"></a>number = <span class="cn">null</span>;</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
@@ -464,7 +464,7 @@ <h2 data-number="6.4" class="anchored" data-anchor-id="optionals-and-optional-po
 <section id="what-are-optionals" class="level3" data-number="6.4.1">
 <h3 data-number="6.4.1" class="anchored" data-anchor-id="what-are-optionals"><span class="header-section-number">6.4.1</span> What are optionals?</h3>
 <p>Ok, we know now that all objects are non-nullable by default in Zig. But what if we actually need to use an object that might receive a null value? Here is where optionals come in.</p>
-<p>An optional object in Zig is an object that can be null. To mark an object as optional, we use the <code>?</code> operator. When you put this <code>?</code> operator right before the data type of an object, you transform this data type into an optional data type, and the object becomes an optional object.</p>
+<p>An optional object in Zig is rather similar to a <a href="https://en.cppreference.com/w/cpp/utility/optional.html"><code>std::optional</code> object in C++</a>. It is an object that can either contain a value, or nothing at all (a.k.a. the object can be null). To mark an object in our Zig code as “optional”, we use the <code>?</code> operator. When you put this <code>?</code> operator right before the data type of an object, you transform this data type into an optional data type, and the object becomes an optional object.</p>
 <p>Take the snippet below as an example. We are creating a new variable object called <code>num</code>. This object have the data type <code>?i32</code>, which means that, this object contains either a signed 32-bit integer (<code>i32</code>), or, a null value. Both alternatives are valid values to the <code>num</code> object. That is why, I can actually change the value of this object to null, and, no errors are raised by the <code>zig</code> compiler, as demonstrated below:</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb19"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb19-1"><a href="#cb19-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> num: ?<span class="dt">i32</span> = <span class="dv">5</span>;</span>
diff --git a/docs/Chapters/09-error-handling.html b/docs/Chapters/09-error-handling.html
index 9ed073b5..49eeddc6 100644
--- a/docs/Chapters/09-error-handling.html
+++ b/docs/Chapters/09-error-handling.html
@@ -469,7 +469,7 @@ <h3 data-number="10.1.3" class="anchored" data-anchor-id="casting-error-values">
 <span id="cb8-20"><a href="#cb8-20" aria-hidden="true" tabindex="-1"></a>    );</span>
 <span id="cb8-21"><a href="#cb8-21" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 file826379a872a1.test.coerce error value...OKA
+<pre><code>1/1 file1f7f62fdbe33.test.coerce error value...OKA
   All 1 tests passed.</code></pre>
 </div>
 </div>
diff --git a/docs/Chapters/10-stack-project.html b/docs/Chapters/10-stack-project.html
index c9dddea2..989af503 100644
--- a/docs/Chapters/10-stack-project.html
+++ b/docs/Chapters/10-stack-project.html
@@ -370,7 +370,7 @@ <h3 data-number="12.1.1" class="anchored" data-anchor-id="applying-over-a-functi
 <span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a>    _ = twice(<span class="dv">5678</span>);</span>
 <span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 filef044375a1f16.test.test comptime...OKAll 1 
+<pre><code>1/1 file20a25a72e5e3.test.test comptime...OKAll 1 
    tests passed.</code></pre>
 </div>
 </div>
@@ -435,7 +435,7 @@ <h3 data-number="12.1.2" class="anchored" data-anchor-id="applying-over-an-expre
 <span id="cb6-11"><a href="#cb6-11" aria-hidden="true" tabindex="-1"></a>    <span class="kw">try</span> <span class="kw">comptime</span> expect(fibonacci(<span class="dv">7</span>) == <span class="dv">13</span>);</span>
 <span id="cb6-12"><a href="#cb6-12" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 filef0447cb16f4d.test.fibonacci...OKAll 1 test
+<pre><code>1/1 file20a26d02bee1.test.fibonacci...OKAll 1 test
   ts passed.</code></pre>
 </div>
 </div>
@@ -464,7 +464,7 @@ <h3 data-number="12.1.3" class="anchored" data-anchor-id="applying-over-a-block"
 <span id="cb8-15"><a href="#cb8-15" aria-hidden="true" tabindex="-1"></a>    _ = x;</span>
 <span id="cb8-16"><a href="#cb8-16" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output cell-output-stdout">
-<pre><code>1/1 filef044524d5e27.test.fibonacci in a block...O
+<pre><code>1/1 file20a238222e11.test.fibonacci in a block...O
   OKAll 1 tests passed.</code></pre>
 </div>
 </div>
diff --git a/docs/index.html b/docs/index.html
index 6a8a4913..cad13fc2 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -7,7 +7,7 @@
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 <meta name="author" content="Pedro Duarte Faria">
-<meta name="dcterms.date" content="2025-05-26">
+<meta name="dcterms.date" content="2025-05-28">
 
 <title>Introduction to Zig</title>
 <style>
@@ -287,7 +287,7 @@ <h1 class="title">Introduction to Zig</h1>
     <div>
     <div class="quarto-title-meta-heading">Published</div>
     <div class="quarto-title-meta-contents">
-      <p class="date">May 26, 2025</p>
+      <p class="date">May 28, 2025</p>
     </div>
   </div>
   
diff --git a/docs/search.json b/docs/search.json
index d218958c..887f9d22 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -234,7 +234,7 @@
     "href": "Chapters/03-structs.html#sec-zig-control-flow",
     "title": "2  Control flow, structs, modules and types",
     "section": "",
-    "text": "2.1.1 If/else statements\nAn if/else statement performs a “conditional flow operation”. A conditional flow control (or choice control) allows you to execute or ignore a certain block of commands based on a logical condition. Many programmers and computer science professionals also use the term “branching” in this case. In essence, an if/else statement allow us to use the result of a logical test to decide whether or not to execute a given block of commands.\nIn Zig, we write if/else statements by using the keywords if and else. We start with the if keyword followed by a logical test inside a pair of parentheses, followed by a pair of curly braces which contains the lines of code to be executed in case the logical test returns the value true.\nAfter that, you can optionally add an else statement. To do that, just add the else keyword followed by a pair of curly braces, with the lines of code to executed in case the logical test defined at if returns false.\nIn the example below, we are testing if the object x contains a number that is greater than 10. Judging by the output printed to the console, we know that this logical test returned false. Because the output in the console is compatible with the line of code present in the else branch of the if/else statement.\n\nconst x = 5;\nif (x &gt; 10) {\n    try stdout.print(\n        \"x &gt; 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x &lt;= 10!\\n\", .{}\n    );\n}\n\nx &lt;= 10!\n\n\n\n\n2.1.2 Switch statements\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust. As you would expect, to write a switch statement in Zig we use the switch keyword. We provide the value that we want to “switch over” inside a pair of parentheses. Then, we list the possible combinations (or “branches”) inside a pair of curly braces.\nLet’s take a look at the code example below. You can see that I’m creating an enum type called Role. We talk more about enums in Section 7.6. But in summary, this Role type is listing different types of roles in a fictitious company, like SE for Software Engineer, DE for Data Engineer, PM for Product Manager, etc.\nNotice that we are using the value from the role object in the switch statement, to discover which exact area we need to store in the area variable object. Also notice that we are using type inference inside the switch statement, with the dot character, as we are going to describe in Section 2.4. This makes the zig compiler infer the correct data type of the values (PM, SE, etc.) for us.\nAlso notice that, we are grouping multiple values in the same branch of the switch statement. We just separate each possible value with a comma. For example, if role contains either DE or DA, the area variable would contain the value \"Data & Analytics\", instead of \"Platform\" or \"Sales\".\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO =&gt; {\n            area = \"Platform\";\n        },\n        .DE, .DA =&gt; {\n            area = \"Data & Analytics\";\n        },\n        .KS =&gt; {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n\nPlatform\n\n\n\n2.1.2.1 Switch statements must exhaust all possibilities\nOne very important aspect about switch statements in Zig is that they must exhaust all existing possibilities. In other words, all possible values that could be found inside the role object must be explicitly handled in this switch statement.\nSince the role object has type Role, the only possible values to be found inside this object are PM, SE, DPE, PO, DE, DA and KS. There are no other possible values to be stored in this role object. Thus, the switch statements must have a combination (branch) for each one of these values. This is what “exhaust all existing possibilities” means. The switch statement covers every possible case.\nTherefore, you cannot write a switch statement in Zig, and leave an edge case with no explicit action to be taken. This is a similar behaviour to switch statements in Rust, which also have to handle all possible cases.\n\n\n2.1.2.2 The else branch\nTake a look at the dump_hex_fallible() function below as an example. This function comes from the Zig Standard Library. More precisely, from the debug.zig module1. There are multiple lines in this function, but I omitted them to focus solely on the switch statement found in this function. Notice that this switch statement has four possible cases (i.e., four explicit branches). Also, notice that we used an else branch in this case.\nAn else branch in a switch statement works as the “default branch”. Whenever you have multiple cases in your switch statement where you want to apply the exact same action, you can use an else branch to do that.\n\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' =&gt; try writer.writeAll(\"␊\"),\n        '\\r' =&gt; try writer.writeAll(\"␍\"),\n        '\\t' =&gt; try writer.writeAll(\"␉\"),\n        else =&gt; try writer.writeByte('.'),\n    }\n}\n\nMany programmers would also use an else branch to handle a “not supported” case. That is, a case that cannot be properly handled by your code, or, just a case that should not be “fixed”. Therefore, you can use an else branch to panic (or raise an error) in your program to stop the current execution.\nTake the code example below. We can see that, we are handling the cases for the level object being either 1, 2, or 3. All other possible cases are not supported by default, and, as consequence, we raise a runtime error in such cases through the @panic() built-in function.\nAlso notice that, we are assigning the result of the switch statement to a new object called category. This is another thing that you can do with switch statements in Zig. If a branch outputs a value as result, you can store the result value of the switch statement into a new object.\n\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 =&gt; \"beginner\",\n    3 =&gt; \"professional\",\n    else =&gt; {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n\n\n2.1.2.3 Using ranges in switch\nFurthermore, you can also use ranges of values in switch statements. That is, you can create a branch in your switch statement that is used whenever the input value is within the specified range. These “range expressions” are created with the operator .... It’s important to emphasize that the ranges created by this operator are inclusive on both ends.\nFor example, I could easily change the previous code example to support all levels between 0 and 100. Like this:\n\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 =&gt; \"beginner\",\n    26...75 =&gt; \"intermediary\",\n    76...100 =&gt; \"professional\",\n    else =&gt; {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n\nbeginner\n\n\nThis is neat, and it works with character ranges too. That is, I could simply write 'a'...'z', to match any character value that is a lowercase letter, and it would work fine.\n\n\n2.1.2.4 Labeled switch statements\nIn Section 1.7 we have talked about labeling blocks, and also, about using these labels to return a value from the block. Well, from version 0.14.0 and onwards of the zig compiler, you can also apply labels over switch statements, which makes it possible to almost implement a “C goto” like pattern.\nFor example, if you give the label xsw to a switch statement, you can use this label in conjunction with the continue keyword to go back to the beginning of the switch statement. In the example below, the execution goes back to the beginning of the switch statement two times, before ending at the 3 branch.\n\nxsw: switch (@as(u8, 1)) {\n    1 =&gt; {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 =&gt; continue :xsw 3,\n    3 =&gt; return,\n    4 =&gt; {},\n    else =&gt; {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n\n\n\n\n2.1.3 The defer keyword\nWith the defer keyword you can register an expression to be executed when you exit the current scope. Therefore, this keyword has a similar functionality as the on.exit() function from R. Take the foo() function below as an example. When we execute this foo() function, the expression that prints the message “Exiting function …” is getting executed only when the function exits its scope.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n\nAdding some numbers ...\nMultiplying ...\nExiting function ...\nTherefore, we can use defer to declare an expression that is going to be executed when your code exits the current scope. Some programmers like to interpret the phrase “exit of the current scope” as “the end of the current scope”. But this interpretation might not be entirely correct, depending on what you consider as “the end of the current scope”.\nI mean, what do you consider as the end of the current scope? Is it the closing curly bracket (}) of the scope? Is it when the last expression in the function gets executed? Is it when the function returns to the previous scope? Etc. For example, it would not be correct to interpret the “exit of the current scope” as the closing curly bracket of the scope. Because the function might exit from an earlier position than this closing curly bracket (e.g. an error value was generated at a previous line inside the function; the function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\nNow, if you remember of what we have discussed in Section 1.7, there are multiple structures in the language that create their own separate scopes. For/while loops, if/else statements, functions, normal blocks, etc. This also affects the interpretation of defer. For example, if you use defer inside a for loop, then, the given expression will be executed everytime this specific for loop exits its own scope.\nBefore we continue, it’s worth emphasizing that the defer keyword is an “unconditional defer”. Which means that the given expression will be executed no matter how the code exits the current scope. For example, your code might exit the current scope because of an error value being generated, or, because of a return statement, or, a break statement, etc.\n\n\n2.1.4 The errdefer keyword\nOn the previous section, we have discussed the defer keyword, which you can use to register an expression to be executed at the exit of the current scope. But this keyword has a brother, which is the errdefer keyword. While defer is an “unconditional defer”, the errdefer keyword is a “conditional defer”. Which means that the given expression is executed only when you exit the current scope on a very specific circumstance.\nIn more details, the expression given to errdefer is executed only when an error occurs in the current scope. Therefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope in a normal situation, without errors, the expression given to errdefer is not executed.\nThis makes the errdefer keyword one of the many tools available in Zig for error handling. In this section, we are more concerned with the control flow aspects around errdefer. But we are going to discuss errdefer later as a error handling tool in Section 10.2.4.\nThe code example below demonstrates three things:\n\nthat defer is an “unconditional defer”, because the given expression gets executed regardless of how the function foo() exits its own scope.\nthat errdefer is executed because the function foo() returned an error value.\nthat defer and errdefer expressions are executed in a LIFO (last in, first out) order.\n\n\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\nWhen I say that “defer expressions” are executed in a LIFO order, what I want to say is that the last defer or errdefer expressions in the code are the first ones to be executed. You could also interpret this as: “defer expressions” are executed from bottom to top, or, from last to first.\nTherefore, if I change the order of the defer and errdefer expressions, you will notice that the value of i that gets printed to the console changes to 1. This doesn’t mean that the defer expression was not executed in this case. This actually means that the defer expression was executed only after the errdefer expression. The code example below demonstrates this:\n\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n\n\n2.1.5 For loops\nA loop allows you to execute the same lines of code multiple times, thus, creating a “repetition space” in the execution flow of your program. Loops are particularly useful when we want to replicate the same function (or the same set of commands) over different inputs.\nThere are different types of loops available in Zig. But the most essential of them all is probably the for loop. A for loop is used to apply the same piece of code over the elements of a slice, or, an array.\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from other languages. You start with the for keyword, then, you list the items that you want to iterate over inside a pair of parentheses. Then, inside of a pair of pipes (|) you should declare an identifier that will serve as your iterator, or, the “repetition index of the loop”.\n\nfor (items) |value| {\n    // code to execute\n}\n\nTherefore, instead of using a (value in items) syntax, in Zig, for loops use the syntax (items) |value|. In the example below, you can see that we are looping through the items of the array stored at the object name, and printing to the console the decimal representation of each character in this array.\nIf we wanted, we could also iterate through a slice (or a portion) of the array, instead of iterating through the entire array stored in the name object. Just use a range selector to select the section you want. For example, I could provide the expression name[0..3] to the for loop, to iterate just through the first 3 elements in the array.\n\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n\n80 | 101 | 100 | 114 | 111 | \n\n\nIn the above example we are using the value itself of each element in the array as our iterator. But there are many situations where we need to use an index instead of the actual values of the items.\nYou can do that by providing a second set of items to iterate over. More precisely, you provide the range selector 0.. to the for loop. So, yes, you can use two different iterators at the same time in a for loop in Zig.\nBut remember from Section 1.4 that, every object you create in Zig must be used in some way. So if you declare two iterators in your for loop, you must use both iterators inside the for loop body. But if you want to use just the index iterator, and not use the “value iterator”, then, you can discard the value iterator by maching the value items to the underscore character, like in the example below:\n\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n\n0 | 1 | 2 | 3 | 4 |\n\n\n2.1.6 While loops\nA while loop is created from the while keyword. A for loop iterates through the items of an array, but a while loop will loop continuously, and infinitely, until a logical test (specified by you) becomes false.\nYou start with the while keyword, then, you define a logical expression inside a pair of parentheses, and the body of the loop is provided inside a pair of curly braces, like in the example below:\n\nvar i: u8 = 1;\nwhile (i &lt; 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n\n1 | 2 | 3 | 4 | \n\n\nYou can also specify the increment expression to be used at the beginning of a while loop. To do that, we write the increment expression inside a pair of parentheses after a colon character (:). The code example below demonstrates this other pattern.\n\nvar i: u8 = 1;\nwhile (i &lt; 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n\n1 | 2 | 3 | 4 | \n\n\n\n\n2.1.7 Using break and continue\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using the keywords break and continue, respectively. The while loop presented in the next code example is, at first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to true. But what makes this while loop stop when the i object reaches the count 10? It’s the break keyword!\nInside the while loop, we have an if statement that is constantly checking if the i variable is equal to 10. Since we are incrementing the value of i at each iteration of the while loop, this i object will eventually be equal to 10, and when it is, the if statement will execute the break expression, and, as a result, the execution of the while loop is stopped.\nNotice the use of the expect() function from the Zig Standard Library after the while loop. This expect() function is an “assert” type of function. This function checks if the logical test provided is equal to true. If so, the function do nothing. Otherwise (i.e., the logical test is equal to false), the function raises an assertion error.\n\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n\nEverything worked!\n\n\nSince this code example was executed successfully by the zig compiler, without raising any errors, we known that, after the execution of the while loop, the i object is equal to 10. Because if it wasn’t equal to 10, an error would have been raised by expect().\nNow, in the next example, we have a use case for the continue keyword. The if statement is constantly checking if the current index is a multiple of 2. If it is, we jump to the next iteration of the loop. Otherwise, the loop just prints the current index to the console.\n\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n\n1 | 3 | 5 |",
+    "text": "2.1.1 If/else statements\nAn if/else statement performs a “conditional flow operation”. A conditional flow control (or choice control) allows you to execute or ignore a certain block of commands based on a logical condition. Many programmers and computer science professionals also use the term “branching” in this case. In essence, an if/else statement allow us to use the result of a logical test to decide whether or not to execute a given block of commands.\nIn Zig, we write if/else statements by using the keywords if and else. We start with the if keyword followed by a logical test inside a pair of parentheses, followed by a pair of curly braces which contains the lines of code to be executed in case the logical test returns the value true.\nAfter that, you can optionally add an else statement. To do that, just add the else keyword followed by a pair of curly braces, with the lines of code to executed in case the logical test defined at if returns false.\nIn the example below, we are testing if the object x contains a number that is greater than 10. Judging by the output printed to the console, we know that this logical test returned false. Because the output in the console is compatible with the line of code present in the else branch of the if/else statement.\n\nconst x = 5;\nif (x &gt; 10) {\n    try stdout.print(\n        \"x &gt; 10!\\n\", .{}\n    );\n} else {\n    try stdout.print(\n        \"x &lt;= 10!\\n\", .{}\n    );\n}\n\nx &lt;= 10!\n\n\n\n\n2.1.2 Switch statements\nSwitch statements are also available in Zig, and they have a very similar syntax to a switch statement in Rust. As you would expect, to write a switch statement in Zig we use the switch keyword. We provide the value that we want to “switch over” inside a pair of parentheses. Then, we list the possible combinations (or “branches”) inside a pair of curly braces.\nLet’s take a look at the code example below. You can see that I’m creating an enum type called Role. We talk more about enums in Section 7.6. But in summary, this Role type is listing different types of roles in a fictitious company, like SE for Software Engineer, DE for Data Engineer, PM for Product Manager, etc.\nNotice that we are using the value from the role object in the switch statement, to discover which exact area we need to store in the area variable object. Also notice that we are using type inference inside the switch statement, with the dot character, as we are going to describe in Section 2.4. This makes the zig compiler infer the correct data type of the values (PM, SE, etc.) for us.\nAlso notice that, we are grouping multiple values in the same branch of the switch statement. We just separate each possible value with a comma. For example, if role contains either DE or DA, the area variable would contain the value \"Data & Analytics\", instead of \"Platform\" or \"Sales\".\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nconst Role = enum {\n    SE, DPE, DE, DA, PM, PO, KS\n};\n\npub fn main() !void {\n    var area: []const u8 = undefined;\n    const role = Role.SE;\n    switch (role) {\n        .PM, .SE, .DPE, .PO =&gt; {\n            area = \"Platform\";\n        },\n        .DE, .DA =&gt; {\n            area = \"Data & Analytics\";\n        },\n        .KS =&gt; {\n            area = \"Sales\";\n        },\n    }\n    try stdout.print(\"{s}\\n\", .{area});\n}\n\nPlatform\n\n\n\n2.1.2.1 Switch statements must exhaust all possibilities\nOne very important aspect about switch statements in Zig is that they must exhaust all existing possibilities. In other words, all possible values that could be found inside the role object must be explicitly handled in this switch statement.\nSince the role object has type Role, the only possible values to be found inside this object are PM, SE, DPE, PO, DE, DA and KS. There are no other possible values to be stored in this role object. Thus, the switch statements must have a combination (branch) for each one of these values. This is what “exhaust all existing possibilities” means. The switch statement covers every possible case.\nTherefore, you cannot write a switch statement in Zig, and leave an edge case with no explicit action to be taken. This is a similar behaviour to switch statements in Rust, which also have to handle all possible cases.\n\n\n2.1.2.2 The else branch\nTake a look at the dump_hex_fallible() function below as an example. This function comes from the Zig Standard Library. More precisely, from the debug.zig module1. There are multiple lines in this function, but I omitted them to focus solely on the switch statement found in this function. Notice that this switch statement has four possible cases (i.e., four explicit branches). Also, notice that we used an else branch in this case.\nAn else branch in a switch statement works as the “default branch”. Whenever you have multiple cases in your switch statement where you want to apply the exact same action, you can use an else branch to do that.\n\npub fn dump_hex_fallible(bytes: []const u8) !void {\n    // Many lines ...\n    switch (byte) {\n        '\\n' =&gt; try writer.writeAll(\"␊\"),\n        '\\r' =&gt; try writer.writeAll(\"␍\"),\n        '\\t' =&gt; try writer.writeAll(\"␉\"),\n        else =&gt; try writer.writeByte('.'),\n    }\n}\n\nMany programmers would also use an else branch to handle a “not supported” case. That is, a case that cannot be properly handled by your code, or, just a case that should not be “fixed”. Therefore, you can use an else branch to panic (or raise an error) in your program to stop the current execution.\nTake the code example below. We can see that, we are handling the cases for the level object being either 1, 2, or 3. All other possible cases are not supported by default, and, as consequence, we raise a runtime error in such cases through the @panic() built-in function.\nAlso notice that, we are assigning the result of the switch statement to a new object called category. This is another thing that you can do with switch statements in Zig. If a branch outputs a value as result, you can store the result value of the switch statement into a new object.\n\nconst level: u8 = 4;\nconst category = switch (level) {\n    1, 2 =&gt; \"beginner\",\n    3 =&gt; \"professional\",\n    else =&gt; {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n\nthread 13103 panic: Not supported level!\nt.zig:9:13: 0x1033c58 in main (switch2)\n            @panic(\"Not supported level!\");\n            ^\n\n\n2.1.2.3 Using ranges in switch\nFurthermore, you can also use ranges of values in switch statements. That is, you can create a branch in your switch statement that is used whenever the input value is within the specified range. These “range expressions” are created with the operator .... It’s important to emphasize that the ranges created by this operator are inclusive on both ends.\nFor example, I could easily change the previous code example to support all levels between 0 and 100. Like this:\n\nconst level: u8 = 4;\nconst category = switch (level) {\n    0...25 =&gt; \"beginner\",\n    26...75 =&gt; \"intermediary\",\n    76...100 =&gt; \"professional\",\n    else =&gt; {\n        @panic(\"Not supported level!\");\n    },\n};\ntry stdout.print(\"{s}\\n\", .{category});\n\nbeginner\n\n\nThis is neat, and it works with character ranges too. That is, I could simply write 'a'...'z', to match any character value that is a lowercase letter, and it would work fine.\n\n\n2.1.2.4 Labeled switch statements\nIn Section 1.7 we have talked about labeling blocks, and also, about using these labels to return a value from the block. Well, from version 0.14.0 and onwards of the zig compiler, you can also apply labels over switch statements, which makes it possible to almost implement a “C goto” like pattern.\nFor example, if you give the label xsw to a switch statement, you can use this label in conjunction with the continue keyword to go back to the beginning of the switch statement. In the example below, the execution goes back to the beginning of the switch statement two times, before ending at the 3 branch.\n\nxsw: switch (@as(u8, 1)) {\n    1 =&gt; {\n        try stdout.print(\"First branch\\n\", .{});\n        continue :xsw 2;\n    },\n    2 =&gt; continue :xsw 3,\n    3 =&gt; return,\n    4 =&gt; {},\n    else =&gt; {\n        try stdout.print(\n            \"Unmatched case, value: {d}\\n\", .{@as(u8, 1)}\n        );\n    },\n}\n\n\n\n\n2.1.3 The defer keyword\nZig has a defer keyword, which plays a very important role in control flow, and also, in releasing resources. In summary, the defer keyword allows you to register an expression to be executed when you exit the current scope.\nAt this point, you might attempt to compare the Zig defer keyword to it’s sibling in the Go language (i.e. Go also has a defer keyword). However, the Go defer keyword behaves slightly different than it’s sibling in Zig. More specifically, the defer keyword in Go always move an expression to be executed at the exit of the current function.\nIf you think deeply about this statement, you will notice that the “exit of the current function” is something slightly different than the “exit of the current scope”. So, just be careful when comparing the two keywords together. A single function in Zig might contain many different scopes inside of it, and, therefore, the defer input expression might be executed at different places of the function, depending on which scope you are currently in.\nAs a first example, consider the foo() function exposed below. When we execute this foo() function, the expression that prints the message “Exiting function …” is getting executed only when the function exits its scope.\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn foo() !void {\n    defer std.debug.print(\n        \"Exiting function ...\\n\", .{}\n    );\n    try stdout.print(\"Adding some numbers ...\\n\", .{});\n    const x = 2 + 2; _ = x;\n    try stdout.print(\"Multiplying ...\\n\", .{});\n    const y = 2 * 8; _ = y;\n}\n\npub fn main() !void {\n    try foo();\n}\n\nAdding some numbers ...\nMultiplying ...\nExiting function ...\nTherefore, we can use defer to declare an expression that is going to be executed when your code exits the current scope. Some programmers like to interpret the phrase “exit of the current scope” as “the end of the current scope”. But this interpretation might not be entirely correct, depending on what you consider as “the end of the current scope”.\nI mean, what do you consider as the end of the current scope? Is it the closing curly bracket (}) of the scope? Is it when the last expression in the function gets executed? Is it when the function returns to the previous scope? Etc. For example, it would not be correct to interpret the “exit of the current scope” as the closing curly bracket of the scope. Because the function might exit from an earlier position than this closing curly bracket (e.g. an error value was generated at a previous line inside the function; the function reached an earlier return statement; etc.). Anyway, just be careful with this interpretation.\nNow, if you remember of what we have discussed in Section 1.7, there are multiple structures in the language that create their own separate scopes. For/while loops, if/else statements, functions, normal blocks, etc. This also affects the interpretation of defer. For example, if you use defer inside a for loop, then, the given expression will be executed everytime this specific for loop exits its own scope.\nBefore we continue, it’s worth emphasizing that the defer keyword is an “unconditional defer”. Which means that the given expression will be executed no matter how the code exits the current scope. For example, your code might exit the current scope because of an error value being generated, or, because of a return statement, or, a break statement, etc.\n\n\n2.1.4 The errdefer keyword\nOn the previous section, we have discussed the defer keyword, which you can use to register an expression to be executed at the exit of the current scope. But this keyword has a brother, which is the errdefer keyword. While defer is an “unconditional defer”, the errdefer keyword is a “conditional defer”. Which means that the given expression is executed only when you exit the current scope on a very specific circumstance.\nIn more details, the expression given to errdefer is executed only when an error occurs in the current scope. Therefore, if the function (or for/while loop, if/else statement, etc.) exits the current scope in a normal situation, without errors, the expression given to errdefer is not executed.\nThis makes the errdefer keyword one of the many tools available in Zig for error handling. In this section, we are more concerned with the control flow aspects around errdefer. But we are going to discuss errdefer later as a error handling tool in Section 10.2.4.\nThe code example below demonstrates three things:\n\nthat defer is an “unconditional defer”, because the given expression gets executed regardless of how the function foo() exits its own scope.\nthat errdefer is executed because the function foo() returned an error value.\nthat defer and errdefer expressions are executed in a LIFO (last in, first out) order.\n\n\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    defer i = 2;\n    try foo();\n}\n\nValue of i: 2\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\nWhen I say that “defer expressions” are executed in a LIFO order, what I want to say is that the last defer or errdefer expressions in the code are the first ones to be executed. You could also interpret this as: “defer expressions” are executed from bottom to top, or, from last to first.\nTherefore, if I change the order of the defer and errdefer expressions, you will notice that the value of i that gets printed to the console changes to 1. This doesn’t mean that the defer expression was not executed in this case. This actually means that the defer expression was executed only after the errdefer expression. The code example below demonstrates this:\n\nconst std = @import(\"std\");\nfn foo() !void { return error.FooError; }\npub fn main() !void {\n    var i: usize = 1;\n    defer i = 2;\n    errdefer std.debug.print(\"Value of i: {d}\\n\", .{i});\n    try foo();\n}\n\nValue of i: 1\nerror: FooError\n/t.zig:6:5: 0x1037e48 in foo (defer)\n    return error.FooError;\n    ^\n\n\n2.1.5 For loops\nA loop allows you to execute the same lines of code multiple times, thus, creating a “repetition space” in the execution flow of your program. Loops are particularly useful when we want to replicate the same function (or the same set of commands) over different inputs.\nThere are different types of loops available in Zig. But the most essential of them all is probably the for loop. A for loop is used to apply the same piece of code over the elements of a slice, or, an array.\nFor loops in Zig use a syntax that may be unfamiliar to programmers coming from other languages. You start with the for keyword, then, you list the items that you want to iterate over inside a pair of parentheses. Then, inside of a pair of pipes (|) you should declare an identifier that will serve as your iterator, or, the “repetition index of the loop”.\n\nfor (items) |value| {\n    // code to execute\n}\n\nTherefore, instead of using a (value in items) syntax, in Zig, for loops use the syntax (items) |value|. In the example below, you can see that we are looping through the items of the array stored at the object name, and printing to the console the decimal representation of each character in this array.\nIf we wanted, we could also iterate through a slice (or a portion) of the array, instead of iterating through the entire array stored in the name object. Just use a range selector to select the section you want. For example, I could provide the expression name[0..3] to the for loop, to iterate just through the first 3 elements in the array.\n\nconst name = [_]u8{'P','e','d','r','o'};\nfor (name) |char| {\n    try stdout.print(\"{d} | \", .{char});\n}\n\n80 | 101 | 100 | 114 | 111 | \n\n\nIn the above example we are using the value itself of each element in the array as our iterator. But there are many situations where we need to use an index instead of the actual values of the items.\nYou can do that by providing a second set of items to iterate over. More precisely, you provide the range selector 0.. to the for loop. So, yes, you can use two different iterators at the same time in a for loop in Zig.\nBut remember from Section 1.4 that, every object you create in Zig must be used in some way. So if you declare two iterators in your for loop, you must use both iterators inside the for loop body. But if you want to use just the index iterator, and not use the “value iterator”, then, you can discard the value iterator by maching the value items to the underscore character, like in the example below:\n\nconst name = \"Pedro\";\nfor (name, 0..) |_, i| {\n    try stdout.print(\"{d} | \", .{i});\n}\n\n0 | 1 | 2 | 3 | 4 |\n\n\n2.1.6 While loops\nA while loop is created from the while keyword. A for loop iterates through the items of an array, but a while loop will loop continuously, and infinitely, until a logical test (specified by you) becomes false.\nYou start with the while keyword, then, you define a logical expression inside a pair of parentheses, and the body of the loop is provided inside a pair of curly braces, like in the example below:\n\nvar i: u8 = 1;\nwhile (i &lt; 5) {\n    try stdout.print(\"{d} | \", .{i});\n    i += 1;\n}\n\n1 | 2 | 3 | 4 | \n\n\nYou can also specify the increment expression to be used at the beginning of a while loop. To do that, we write the increment expression inside a pair of parentheses after a colon character (:). The code example below demonstrates this other pattern.\n\nvar i: u8 = 1;\nwhile (i &lt; 5) : (i += 1) {\n    try stdout.print(\"{d} | \", .{i});\n}\n\n1 | 2 | 3 | 4 | \n\n\n\n\n2.1.7 Using break and continue\nIn Zig, you can explicitly stop the execution of a loop, or, jump to the next iteration of the loop, by using the keywords break and continue, respectively. The while loop presented in the next code example is, at first sight, an infinite loop. Because the logical value inside the parenthese will always be equal to true. But what makes this while loop stop when the i object reaches the count 10? It’s the break keyword!\nInside the while loop, we have an if statement that is constantly checking if the i variable is equal to 10. Since we are incrementing the value of i at each iteration of the while loop, this i object will eventually be equal to 10, and when it is, the if statement will execute the break expression, and, as a result, the execution of the while loop is stopped.\nNotice the use of the expect() function from the Zig Standard Library after the while loop. This expect() function is an “assert” type of function. This function checks if the logical test provided is equal to true. If so, the function do nothing. Otherwise (i.e., the logical test is equal to false), the function raises an assertion error.\n\nvar i: usize = 0;\nwhile (true) {\n    if (i == 10) {\n        break;\n    }\n    i += 1;\n}\ntry std.testing.expect(i == 10);\ntry stdout.print(\"Everything worked!\", .{});\n\nEverything worked!\n\n\nSince this code example was executed successfully by the zig compiler, without raising any errors, we known that, after the execution of the while loop, the i object is equal to 10. Because if it wasn’t equal to 10, an error would have been raised by expect().\nNow, in the next example, we have a use case for the continue keyword. The if statement is constantly checking if the current index is a multiple of 2. If it is, we jump to the next iteration of the loop. Otherwise, the loop just prints the current index to the console.\n\nconst ns = [_]u8{1,2,3,4,5,6};\nfor (ns) |i| {\n    if ((i % 2) == 0) {\n        continue;\n    }\n    try stdout.print(\"{d} | \", .{i});\n}\n\n1 | 3 | 5 |",
     "crumbs": [
       "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
     ]
@@ -274,7 +274,7 @@
     "href": "Chapters/03-structs.html#sec-type-cast",
     "title": "2  Control flow, structs, modules and types",
     "section": "2.5 Type casting",
-    "text": "2.5 Type casting\nIn this section, I want to discuss type casting (or, type conversion) with you. We use type casting when we have an object of type “x”, and we want to convert it into an object of type “y”, i.e., we want to change the data type of the object.\nMost languages have a formal way to perform type casting. In Rust for example, we normally use the keyword as, and in C, we normally use the type casting syntax, e.g. (int) x. In Zig, we use the @as() built-in function to cast an object of type “x”, into an object of type “y”.\nThis @as() function is the preferred way to perform type conversion (or type casting) in Zig. Because it’s explicit, and, it also performs the casting only if it is unambiguous and safe. To use this function, you just provide the target data type in the first argument, and, the object that you want cast as the second argument.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n\n1/1 file3fc93b4ea641.test_0...OKAll 1 tests passed\n  d.\n\n\nThis is the general way to perform type casting in Zig. But remember, @as() works only when casting is unambiguous and safe. There are many situations where these assumptions do not hold. For example,\nwhen casting an integer value into a float value, or vice-versa, it’s not clear to the compiler how to perform this conversion safely.\nTherefore, we need to use specialized “casting functions” in such situations. For example, if you want to cast an integer value into a float value, then, you should use the @floatFromInt() function. In the inverse scenario, you should use the @intFromFloat() function.\nIn these functions, you just provide the object that you want to cast as input. Then, the target data type of the “type casting operation” is determined by the type annotation of the object where you are saving the results. In the example below, we are casting the object x into a value of type f32, because the object y, which is where we are saving the results, is annotated as an object of type f32.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n\n1/1 file3fc91795a712.test_0...OKAll 1 tests passed\n  d.\n\n\nAnother built-in function that is very useful when performing type casting operations is @ptrCast(). In essence, we use the @as() built-in function when we want to explicit convert (or cast) a Zig value/object from a type “x” to a type “y”, etc. However, pointers (we are going to discuss pointers in more depth in Chapter 6) are a special type of object in Zig, i.e., they are treated differently from “normal objects”.\nEverytime a pointer is involved in some “type casting operation” in Zig, the @ptrCast() function is used. This function works similarly to @floatFromInt(). You just provide the pointer object that you want to cast as input to this function, and the target data type is, once again, determined by the type annotation of the object where the results are being stored.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n\n1/1 file3fc945f8b4b0.test_0...OKAll 1 tests passed\n  d.",
+    "text": "2.5 Type casting\nIn this section, I want to discuss type casting (or, type conversion) with you. We use type casting when we have an object of type “x”, and we want to convert it into an object of type “y”, i.e., we want to change the data type of the object.\nMost languages have a formal way to perform type casting. In Rust for example, we normally use the keyword as, and in C, we normally use the type casting syntax, e.g. (int) x. In Zig, we use the @as() built-in function to cast an object of type “x”, into an object of type “y”.\nThis @as() function is the preferred way to perform type conversion (or type casting) in Zig. Because it’s explicit, and, it also performs the casting only if it is unambiguous and safe. To use this function, you just provide the target data type in the first argument, and, the object that you want cast as the second argument.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 500;\n    const y = @as(u32, x);\n    try expect(@TypeOf(y) == u32);\n}\n\n1/1 file26f81ac33a52.test_0...OKAll 1 tests passed\n  d.\n\n\nThis is the general way to perform type casting in Zig. But remember, @as() works only when casting is unambiguous and safe. There are many situations where these assumptions do not hold. For example,\nwhen casting an integer value into a float value, or vice-versa, it’s not clear to the compiler how to perform this conversion safely.\nTherefore, we need to use specialized “casting functions” in such situations. For example, if you want to cast an integer value into a float value, then, you should use the @floatFromInt() function. In the inverse scenario, you should use the @intFromFloat() function.\nIn these functions, you just provide the object that you want to cast as input. Then, the target data type of the “type casting operation” is determined by the type annotation of the object where you are saving the results. In the example below, we are casting the object x into a value of type f32, because the object y, which is where we are saving the results, is annotated as an object of type f32.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const x: usize = 565;\n    const y: f32 = @floatFromInt(x);\n    try expect(@TypeOf(y) == f32);\n}\n\n1/1 file26f81f277e9b.test_0...OKAll 1 tests passed\n  d.\n\n\nAnother built-in function that is very useful when performing type casting operations is @ptrCast(). In essence, we use the @as() built-in function when we want to explicit convert (or cast) a Zig value/object from a type “x” to a type “y”, etc. However, pointers (we are going to discuss pointers in more depth in Chapter 6) are a special type of object in Zig, i.e., they are treated differently from “normal objects”.\nEverytime a pointer is involved in some “type casting operation” in Zig, the @ptrCast() function is used. This function works similarly to @floatFromInt(). You just provide the pointer object that you want to cast as input to this function, and the target data type is, once again, determined by the type annotation of the object where the results are being stored.\n\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest {\n    const bytes align(@alignOf(u32)) = [_]u8{\n        0x12, 0x12, 0x12, 0x12\n    };\n    const u32_ptr: *const u32 = @ptrCast(&bytes);\n    try expect(@TypeOf(u32_ptr) == *const u32);\n}\n\n1/1 file26f843ae7baf.test_0...OKAll 1 tests passed\n  d.",
     "crumbs": [
       "<span class='chapter-number'>2</span>  <span class='chapter-title'>Control flow, structs, modules and types</span>"
     ]
@@ -524,7 +524,7 @@
     "href": "Chapters/05-pointers.html#optionals-and-optional-pointers",
     "title": "6  Pointers and Optionals",
     "section": "6.4 Optionals and Optional Pointers",
-    "text": "6.4 Optionals and Optional Pointers\nLet’s talk about optionals and how they relate to pointers in Zig. By default, objects in Zig are non-nullable. This means that, in Zig, you can safely assume that any object in your source code is not null.\nThis is a powerful feature of Zig when you compare it to the developer experience in C. Because in C, any object can be null at any point, and, as consequence, a pointer in C might point to a null value. This is a common source of undefined behaviour in C. When programmers work with pointers in C, they have to constantly check if their pointers are pointing to null values or not.\nIf for some reason, your Zig code produces a null value somewhere, and, this null value ends up in an object that is non-nullable, a runtime error is always raised by your Zig program. Take the program below as an example. The zig compiler can see the null value at compile time, and, as result, it raises a compile time error. But, if a null value is raised during runtime, a runtime error is also raised by the Zig program, with a “attempt to use null value” message.\n\nvar number: u8 = 5;\nnumber = null;\n\np5.zig:5:14: error: expected type 'u8',\n        found '@TypeOf(null)'\n    number = null;\n             ^~~~\nYou don’t get this type of safety in C. In C, you don’t get warnings or errors about null values being produced in your program. If for some reason, your code produces a null value in C, most of the times, you end up getting a segmentation fault error as result, which can mean many things. That is why programmers have to constantly check for null values in C.\nPointers in Zig are also, by default, non-nullable. This is another amazing feature in Zig. So, you can safely assume that any pointer that you create in your Zig code is pointing to a non-null value. Therefore, you don’t have this heavy work of checking if the pointers you create in Zig are pointing to a null value.\n\n6.4.1 What are optionals?\nOk, we know now that all objects are non-nullable by default in Zig. But what if we actually need to use an object that might receive a null value? Here is where optionals come in.\nAn optional object in Zig is an object that can be null. To mark an object as optional, we use the ? operator. When you put this ? operator right before the data type of an object, you transform this data type into an optional data type, and the object becomes an optional object.\nTake the snippet below as an example. We are creating a new variable object called num. This object have the data type ?i32, which means that, this object contains either a signed 32-bit integer (i32), or, a null value. Both alternatives are valid values to the num object. That is why, I can actually change the value of this object to null, and, no errors are raised by the zig compiler, as demonstrated below:\n\nvar num: ?i32 = 5;\nnum = null;\n\n\n\n6.4.2 Optional pointers\nYou can also mark a pointer object as an optional pointer, meaning that, this object contains either a null value, or, a pointer that points to a value. When you mark a pointer as optional, the data type of this pointer object becomes ?*const T or ?*T, depending if the value pointed by the pointer is a constant value or not. The ? identifies the object as optional, while the * identifies it as a pointer object.\nIn the example below, we are creating a variable object named num, and an optional pointer object named ptr. Notice that the data type of the object ptr indicates that it’s either a null value, or a pointer to an i32 value. Also, notice that the pointer object (ptr) can be marked as optional, even if the object num is not optional.\nWhat this code tells us is that, the num variable will never contain a null value. This variable will always contain a valid i32 value. But in contrast, the ptr object might contain either a null value, or, a pointer to an i32 value.\n\nvar num: i32 = 5;\nvar ptr: ?*i32 = &num;\nptr = null;\nnum = 6;\n\nBut what happens if we turn the table, and mark the num object as optional, instead of the pointer object. If we do that, then, the pointer object is not optional anymore. It would be a similar (although different) result. Because then, we would have a pointer to an optional value. In other words, a pointer to a value that is either a null value, or, a not-null value.\nIn the example below, we are recreating this idea. Now, the ptr object have a data type of *?i32, instead of ?*i32. Notice that the * symbol comes before of ? this time. So now, we have a pointer that points to a value that is either null , or, a signed 32-bit integer.\n\nvar num: ?i32 = 5;\n// ptr have type `*?i32`, instead of `?*i32`.\nconst ptr = &num;\n_ = ptr;\n\n\n\n6.4.3 Null handling in optionals\nWhen you have an optional object in your Zig code, you have to explicitly handle the possibility of this object being null. It’s like error-handling with try and catch. In Zig you also have to handle null values like if they were a type of error.\nWe can do that, by using either:\n\nan if statement, like you would do in C.\nthe orelse keyword.\nunwrap the optional value with the ? method.\n\nWhen you use an if statement, you use a pair of pipes to unwrap the optional value, and use this “unwrapped object” inside the if block. Using the example below as a reference, if the object num is null, then, the code inside the if statement is not executed. Otherwise, the if statement will unwrap the object num into the not_null_num object. This not_null_num object is guaranteed to be not null inside the scope of the if statement.\n\nconst num: ?i32 = 5;\nif (num) |not_null_num| {\n    try stdout.print(\"{d}\\n\", .{not_null_num});\n}\n\n5\n\n\nNow, the orelse keyword behaves like a binary operator. You connect two expressions with this keyword. On the left side of orelse, you provide the expression that might result in a null value, and on the right side of orelse, you provide another expression that will not result in a null value.\nThe idea behind the orelse keyword is: if the expression on the left side result in a not-null value, then, this not-null value is used. However, if this expression on the left side result in a null value, then, the value of the expression on the right side is used instead.\nLooking at the example below, since the x object is currently null, the orelse decided to use the alternative value, which is the number 15.\n\nconst x: ?i32 = null;\nconst dbl = (x orelse 15) * 2;\ntry stdout.print(\"{d}\\n\", .{dbl});\n\n30\n\n\nYou can use the if statement or the orelse keyword, when you want to solve (or deal with) this null value. However, if there is no clear solution to this null value, and the most logic and sane path is to simply panic and raise a loud error in your program when this null value is encountered, you can use the ? method of your optional object.\nIn essence, when you use this ? method, the optional object is unwrapped. If a not-null value is found in the optional object, then, this not-null value is used. Otherwise, the unreachable keyword is used. You can read more about this unreacheable keyword at the official documentation1. But in essence, when you build your Zig source code using the build modes ReleaseSafe or Debug, this unreacheable keyword causes the program to panic and raise an error during runtime, like in the example below:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn return_null(n: i32) ?i32 {\n    if (n == 5) return null;\n    return n;\n}\n\npub fn main() !void {\n    const x: i32 = 5;\n    const y: ?i32 = return_null(x);\n    try stdout.print(\"{d}\\n\", .{y.?});\n}\n\nthread 12767 panic: attempt to use null value\np7.zig:12:34: 0x103419d in main (p7):\n    try stdout.print(\"{d}\\n\", .{y.?});\n                                 ^\n\n\n\n\nZig Software Foundation. 2024. “Language Reference.” Zig Software Foundation. https://ziglang.org/documentation/master/.",
+    "text": "6.4 Optionals and Optional Pointers\nLet’s talk about optionals and how they relate to pointers in Zig. By default, objects in Zig are non-nullable. This means that, in Zig, you can safely assume that any object in your source code is not null.\nThis is a powerful feature of Zig when you compare it to the developer experience in C. Because in C, any object can be null at any point, and, as consequence, a pointer in C might point to a null value. This is a common source of undefined behaviour in C. When programmers work with pointers in C, they have to constantly check if their pointers are pointing to null values or not.\nIn contrast, when working in Zig, if for some reason, your Zig code produces a null value somewhere, and, this null value ends up in an object that is non-nullable, a runtime error is always raised by your Zig program. Take the program below as an example. The zig compiler can see the null value at compile time, and, as result, it raises a compile time error. But, if a null value is raised during runtime, a runtime error is also raised by the Zig program, with a “attempt to use null value” message.\n\nvar number: u8 = 5;\nnumber = null;\n\np5.zig:5:14: error: expected type 'u8',\n        found '@TypeOf(null)'\n    number = null;\n             ^~~~\nYou don’t get this type of safety in C. In C, you don’t get warnings or errors about null values being produced in your program. If for some reason, your code produces a null value in C, most of the times, you end up getting a segmentation fault error as result, which can mean many things. That is why programmers have to constantly check for null values in C.\nPointers in Zig are also, by default, non-nullable. This is another amazing feature in Zig. So, you can safely assume that any pointer that you create in your Zig code is pointing to a non-null value. Therefore, you don’t have this heavy work of checking if the pointers you create in Zig are pointing to a null value.\n\n6.4.1 What are optionals?\nOk, we know now that all objects are non-nullable by default in Zig. But what if we actually need to use an object that might receive a null value? Here is where optionals come in.\nAn optional object in Zig is rather similar to a std::optional object in C++. It is an object that can either contain a value, or nothing at all (a.k.a. the object can be null). To mark an object in our Zig code as “optional”, we use the ? operator. When you put this ? operator right before the data type of an object, you transform this data type into an optional data type, and the object becomes an optional object.\nTake the snippet below as an example. We are creating a new variable object called num. This object have the data type ?i32, which means that, this object contains either a signed 32-bit integer (i32), or, a null value. Both alternatives are valid values to the num object. That is why, I can actually change the value of this object to null, and, no errors are raised by the zig compiler, as demonstrated below:\n\nvar num: ?i32 = 5;\nnum = null;\n\n\n\n6.4.2 Optional pointers\nYou can also mark a pointer object as an optional pointer, meaning that, this object contains either a null value, or, a pointer that points to a value. When you mark a pointer as optional, the data type of this pointer object becomes ?*const T or ?*T, depending if the value pointed by the pointer is a constant value or not. The ? identifies the object as optional, while the * identifies it as a pointer object.\nIn the example below, we are creating a variable object named num, and an optional pointer object named ptr. Notice that the data type of the object ptr indicates that it’s either a null value, or a pointer to an i32 value. Also, notice that the pointer object (ptr) can be marked as optional, even if the object num is not optional.\nWhat this code tells us is that, the num variable will never contain a null value. This variable will always contain a valid i32 value. But in contrast, the ptr object might contain either a null value, or, a pointer to an i32 value.\n\nvar num: i32 = 5;\nvar ptr: ?*i32 = &num;\nptr = null;\nnum = 6;\n\nBut what happens if we turn the table, and mark the num object as optional, instead of the pointer object. If we do that, then, the pointer object is not optional anymore. It would be a similar (although different) result. Because then, we would have a pointer to an optional value. In other words, a pointer to a value that is either a null value, or, a not-null value.\nIn the example below, we are recreating this idea. Now, the ptr object have a data type of *?i32, instead of ?*i32. Notice that the * symbol comes before of ? this time. So now, we have a pointer that points to a value that is either null , or, a signed 32-bit integer.\n\nvar num: ?i32 = 5;\n// ptr have type `*?i32`, instead of `?*i32`.\nconst ptr = &num;\n_ = ptr;\n\n\n\n6.4.3 Null handling in optionals\nWhen you have an optional object in your Zig code, you have to explicitly handle the possibility of this object being null. It’s like error-handling with try and catch. In Zig you also have to handle null values like if they were a type of error.\nWe can do that, by using either:\n\nan if statement, like you would do in C.\nthe orelse keyword.\nunwrap the optional value with the ? method.\n\nWhen you use an if statement, you use a pair of pipes to unwrap the optional value, and use this “unwrapped object” inside the if block. Using the example below as a reference, if the object num is null, then, the code inside the if statement is not executed. Otherwise, the if statement will unwrap the object num into the not_null_num object. This not_null_num object is guaranteed to be not null inside the scope of the if statement.\n\nconst num: ?i32 = 5;\nif (num) |not_null_num| {\n    try stdout.print(\"{d}\\n\", .{not_null_num});\n}\n\n5\n\n\nNow, the orelse keyword behaves like a binary operator. You connect two expressions with this keyword. On the left side of orelse, you provide the expression that might result in a null value, and on the right side of orelse, you provide another expression that will not result in a null value.\nThe idea behind the orelse keyword is: if the expression on the left side result in a not-null value, then, this not-null value is used. However, if this expression on the left side result in a null value, then, the value of the expression on the right side is used instead.\nLooking at the example below, since the x object is currently null, the orelse decided to use the alternative value, which is the number 15.\n\nconst x: ?i32 = null;\nconst dbl = (x orelse 15) * 2;\ntry stdout.print(\"{d}\\n\", .{dbl});\n\n30\n\n\nYou can use the if statement or the orelse keyword, when you want to solve (or deal with) this null value. However, if there is no clear solution to this null value, and the most logic and sane path is to simply panic and raise a loud error in your program when this null value is encountered, you can use the ? method of your optional object.\nIn essence, when you use this ? method, the optional object is unwrapped. If a not-null value is found in the optional object, then, this not-null value is used. Otherwise, the unreachable keyword is used. You can read more about this unreacheable keyword at the official documentation1. But in essence, when you build your Zig source code using the build modes ReleaseSafe or Debug, this unreacheable keyword causes the program to panic and raise an error during runtime, like in the example below:\n\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn return_null(n: i32) ?i32 {\n    if (n == 5) return null;\n    return n;\n}\n\npub fn main() !void {\n    const x: i32 = 5;\n    const y: ?i32 = return_null(x);\n    try stdout.print(\"{d}\\n\", .{y.?});\n}\n\nthread 12767 panic: attempt to use null value\np7.zig:12:34: 0x103419d in main (p7):\n    try stdout.print(\"{d}\\n\", .{y.?});\n                                 ^\n\n\n\n\nZig Software Foundation. 2024. “Language Reference.” Zig Software Foundation. https://ziglang.org/documentation/master/.",
     "crumbs": [
       "<span class='chapter-number'>6</span>  <span class='chapter-title'>Pointers and Optionals</span>"
     ]
@@ -634,7 +634,7 @@
     "href": "Chapters/03-unittests.html",
     "title": "8  Unit tests",
     "section": "",
-    "text": "8.1 Introducing the test block\nIn Zig, unit tests are written inside a test declaration, or, how I prefer to call it, inside a test block. Every test block is written by using the keyword test. You can optionally use a string literal to write a label, which is responsible for identifying the specific group of unit tests that you are writing inside this specific test block.\nIn the example below, we are testing if the sum of two objects (a and b) is equal to 4. The expect() function from the Zig Standard Library is a function that receives a logical test as input. If this logical test results in true, then, the test passes. But if it results in false, then, the test fails.\nYou can write any Zig code you want inside a test block. Part of this code might be some necessary commands to setup your testing environment, or just initializing some objects that you need to use in your unit tests.\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest \"testing simple sum\" {\n    const a: u8 = 2;\n    const b: u8 = 2;\n    try expect((a + b) == 4);\n}\n\n1/1 file81c21dbf264e.test.testing simple sum...OKA\n  All 1 tests passed.\nYou can have multiple test blocks written on the same Zig module. Also, you can mix test blocks with your source code, with no problems or consequences. If you mix test blocks with your normal source code, when you execute the build, build-exe, build-obj or build-lib commands from the zig compiler that we exposed in Section 1.2.4, these test blocks are automatically ignored by the compiler.\nIn other words, the zig compiler builds and execute your unit tests only when you ask it to. By default, the compiler always ignore test blocks written in your Zig modules. The compiler normally checks only if there are any syntax errors in these test blocks.\nIf you take a look at the source code for most of the files present in the Zig Standard Library1, you can see that the test blocks are written together with the normal source code of the library. You can see this for example, at the array_list module2. So, the standard that the Zig developers decided to adopt is to keep their unit tests together with the source code of the functionality that they are testing.\nEach programmer might have a different opinion on this. Some of them might prefer to keep unit tests separate from the actual source code of their application. If that is your case, you can simply create a separate tests folder in your project, and start writing Zig modules that contains only unit tests (as you would normally do on a Python project with pytest, for example), and everything will work fine. It boils down to which is your preference here.",
+    "text": "8.1 Introducing the test block\nIn Zig, unit tests are written inside a test declaration, or, how I prefer to call it, inside a test block. Every test block is written by using the keyword test. You can optionally use a string literal to write a label, which is responsible for identifying the specific group of unit tests that you are writing inside this specific test block.\nIn the example below, we are testing if the sum of two objects (a and b) is equal to 4. The expect() function from the Zig Standard Library is a function that receives a logical test as input. If this logical test results in true, then, the test passes. But if it results in false, then, the test fails.\nYou can write any Zig code you want inside a test block. Part of this code might be some necessary commands to setup your testing environment, or just initializing some objects that you need to use in your unit tests.\nconst std = @import(\"std\");\nconst expect = std.testing.expect;\ntest \"testing simple sum\" {\n    const a: u8 = 2;\n    const b: u8 = 2;\n    try expect((a + b) == 4);\n}\n\n1/1 file1ed835512cf8.test.testing simple sum...OKA\n  All 1 tests passed.\nYou can have multiple test blocks written on the same Zig module. Also, you can mix test blocks with your source code, with no problems or consequences. If you mix test blocks with your normal source code, when you execute the build, build-exe, build-obj or build-lib commands from the zig compiler that we exposed in Section 1.2.4, these test blocks are automatically ignored by the compiler.\nIn other words, the zig compiler builds and execute your unit tests only when you ask it to. By default, the compiler always ignore test blocks written in your Zig modules. The compiler normally checks only if there are any syntax errors in these test blocks.\nIf you take a look at the source code for most of the files present in the Zig Standard Library1, you can see that the test blocks are written together with the normal source code of the library. You can see this for example, at the array_list module2. So, the standard that the Zig developers decided to adopt is to keep their unit tests together with the source code of the functionality that they are testing.\nEach programmer might have a different opinion on this. Some of them might prefer to keep unit tests separate from the actual source code of their application. If that is your case, you can simply create a separate tests folder in your project, and start writing Zig modules that contains only unit tests (as you would normally do on a Python project with pytest, for example), and everything will work fine. It boils down to which is your preference here.",
     "crumbs": [
       "<span class='chapter-number'>8</span>  <span class='chapter-title'>Unit tests</span>"
     ]
@@ -664,7 +664,7 @@
     "href": "Chapters/03-unittests.html#testing-errors",
     "title": "8  Unit tests",
     "section": "8.4 Testing errors",
-    "text": "8.4 Testing errors\nOne common style of unit tests are those that look for specific errors in your functions. In other words, you write a unit test that tries to assert if a specific function call returns any error, or a specific type of error.\nIn C++ you would normally write this style of unit tests using, for example, the functions REQUIRE_THROWS() or CHECK_THROWS() from the Catch2 test framework3. In the case of a Python project, you would probably use the raises() function from pytest4. While in Rust, you would probably use assert_eq!() in conjunction with Err().\nBut in Zig, we use the expectError() function, from the std.testing module. With this function, you can test if a specific function call returns the exact type of error that you expect it to return. To use this function, you first write try expectError(). Then, on the first argument, you provide the type of error that you are expecting from the function call. Then, on the second argument, you write the function call that you expect to fail.\nThe code example below demonstrates such type of unit test in Zig. Notice that, inside the function alloc_error() we are allocating 100 bytes of memory, or, an array of 100 elements, for the object ibuffer. However, in the test block, we are using the FixedBufferAllocator() allocator object, which is limited to 10 bytes of space, because the object buffer, which we provided to the allocator object, have only 10 bytes of space.\nThat is why, the alloc_error() function raises an OutOfMemory error on this case. Because this function is trying to allocate more space than the allocator object allows. So, in essence, we are testing for a specific type of error, which is OutOfMemory. If the alloc_error() function returns any other type of error, then, the expectError() function would make the entire test fail.\n\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst expectError = std.testing.expectError;\nfn alloc_error(allocator: Allocator) !void {\n    var ibuffer = try allocator.alloc(u8, 100);\n    defer allocator.free(ibuffer);\n    ibuffer[0] = 2;\n}\n\ntest \"testing error\" {\n    var buffer: [10]u8 = undefined;\n    var fba = std.heap.FixedBufferAllocator.init(&buffer);\n    const allocator = fba.allocator();\n    try expectError(error.OutOfMemory, alloc_error(allocator));\n}\n\n1/1 file81c24fea00d1.test.testing error...OKAll 1 \n   tests passed.",
+    "text": "8.4 Testing errors\nOne common style of unit tests are those that look for specific errors in your functions. In other words, you write a unit test that tries to assert if a specific function call returns any error, or a specific type of error.\nIn C++ you would normally write this style of unit tests using, for example, the functions REQUIRE_THROWS() or CHECK_THROWS() from the Catch2 test framework3. In the case of a Python project, you would probably use the raises() function from pytest4. While in Rust, you would probably use assert_eq!() in conjunction with Err().\nBut in Zig, we use the expectError() function, from the std.testing module. With this function, you can test if a specific function call returns the exact type of error that you expect it to return. To use this function, you first write try expectError(). Then, on the first argument, you provide the type of error that you are expecting from the function call. Then, on the second argument, you write the function call that you expect to fail.\nThe code example below demonstrates such type of unit test in Zig. Notice that, inside the function alloc_error() we are allocating 100 bytes of memory, or, an array of 100 elements, for the object ibuffer. However, in the test block, we are using the FixedBufferAllocator() allocator object, which is limited to 10 bytes of space, because the object buffer, which we provided to the allocator object, have only 10 bytes of space.\nThat is why, the alloc_error() function raises an OutOfMemory error on this case. Because this function is trying to allocate more space than the allocator object allows. So, in essence, we are testing for a specific type of error, which is OutOfMemory. If the alloc_error() function returns any other type of error, then, the expectError() function would make the entire test fail.\n\nconst std = @import(\"std\");\nconst Allocator = std.mem.Allocator;\nconst expectError = std.testing.expectError;\nfn alloc_error(allocator: Allocator) !void {\n    var ibuffer = try allocator.alloc(u8, 100);\n    defer allocator.free(ibuffer);\n    ibuffer[0] = 2;\n}\n\ntest \"testing error\" {\n    var buffer: [10]u8 = undefined;\n    var fba = std.heap.FixedBufferAllocator.init(&buffer);\n    const allocator = fba.allocator();\n    try expectError(error.OutOfMemory, alloc_error(allocator));\n}\n\n1/1 file1ed878d2d839.test.testing error...OKAll 1 \n   tests passed.",
     "crumbs": [
       "<span class='chapter-number'>8</span>  <span class='chapter-title'>Unit tests</span>"
     ]
@@ -674,7 +674,7 @@
     "href": "Chapters/03-unittests.html#testing-simple-equalities",
     "title": "8  Unit tests",
     "section": "8.5 Testing simple equalities",
-    "text": "8.5 Testing simple equalities\nIn Zig, there are some different ways you can test for an equality. You already saw that we can use expect() with the logical operator == to essentially reproduce an equality test. But we also have some other helper functions that you should know about, especially expectEqual(), expectEqualSlices() and expectEqualStrings().\nThe expectEqual() function, as the name suggests, is a classic test equality function. It receives two objects as input. The first object is the value that you expect to be in the second object. While second object is the object you have, or, the object that your application produced as result. So, with expectEqual() you are essentially testing if the values stored inside these two objects are equal or not.\nYou can see in the example below that, the test performed by expectEqual() failed. Because the objects v1 and v2 contain different values in them.\n\nconst std = @import(\"std\");\ntest \"values are equal?\" {\n    const v1 = 15;\n    const v2 = 18;\n    try std.testing.expectEqual(v1, v2);\n}\n\n1/1 ve.test.values are equal?...\n    expected 15, found 18\n    FAIL (TestExpectedEqual)\nve.zig:5:5: test.values are equal? (test)\n    try std.testing.expectEqual(v1, v2);\n    ^\n0 passed; 0 skipped; 1 failed.\nAlthough useful, the expectEqual() function does not work with arrays. For testing if two arrays are equal, you should use the expectEqualSlices() function instead. This function have three arguments. First, you provide the data type contained in both arrays that you are trying to compare. While the second and third arguments corresponds to the array objects that you want to compare.\nIn the example below, we are using this function to test if two array objects (array1 and array2) are equal or not. Since they are in fact equal, the unit test passed with no errors.\n\nconst std = @import(\"std\");\ntest \"arrays are equal?\" {\n    const array1 = [3]u32{1, 2, 3};\n    const array2 = [3]u32{1, 2, 3};\n    try std.testing.expectEqualSlices(\n        u32, &array1, &array2\n    );\n}\n\n1/1 file81c25513148.test.arrays are equal?...OKAll\n  l 1 tests passed.\n\n\nAt last, you might also want to use the expectEqualStrings() function. As the name suggests, you can use this function to test if two strings are equal or not. Just provide the two string objects that you want to compare, as inputs to the function.\nIf the function finds any existing differences between the two strings, then, the function will raise an error, and also, print an error message that shows the exact difference between the two string objects provided, as the example below demonstrates:\n\nconst std = @import(\"std\");\ntest \"strings are equal?\" {\n    const str1 = \"hello, world!\";\n    const str2 = \"Hello, world!\";\n    try std.testing.expectEqualStrings(\n        str1, str2\n    );\n}\n\n1/1 t.test.strings are equal?...\n====== expected this output: =========\nhello, world!␃\n======== instead found this: =========\nHello, world!␃\n======================================\nFirst difference occurs on line 1:\nexpected:\nhello, world!\n^ ('\\x68')\nfound:\nHello, world!\n^ ('\\x48')",
+    "text": "8.5 Testing simple equalities\nIn Zig, there are some different ways you can test for an equality. You already saw that we can use expect() with the logical operator == to essentially reproduce an equality test. But we also have some other helper functions that you should know about, especially expectEqual(), expectEqualSlices() and expectEqualStrings().\nThe expectEqual() function, as the name suggests, is a classic test equality function. It receives two objects as input. The first object is the value that you expect to be in the second object. While second object is the object you have, or, the object that your application produced as result. So, with expectEqual() you are essentially testing if the values stored inside these two objects are equal or not.\nYou can see in the example below that, the test performed by expectEqual() failed. Because the objects v1 and v2 contain different values in them.\n\nconst std = @import(\"std\");\ntest \"values are equal?\" {\n    const v1 = 15;\n    const v2 = 18;\n    try std.testing.expectEqual(v1, v2);\n}\n\n1/1 ve.test.values are equal?...\n    expected 15, found 18\n    FAIL (TestExpectedEqual)\nve.zig:5:5: test.values are equal? (test)\n    try std.testing.expectEqual(v1, v2);\n    ^\n0 passed; 0 skipped; 1 failed.\nAlthough useful, the expectEqual() function does not work with arrays. For testing if two arrays are equal, you should use the expectEqualSlices() function instead. This function have three arguments. First, you provide the data type contained in both arrays that you are trying to compare. While the second and third arguments corresponds to the array objects that you want to compare.\nIn the example below, we are using this function to test if two array objects (array1 and array2) are equal or not. Since they are in fact equal, the unit test passed with no errors.\n\nconst std = @import(\"std\");\ntest \"arrays are equal?\" {\n    const array1 = [3]u32{1, 2, 3};\n    const array2 = [3]u32{1, 2, 3};\n    try std.testing.expectEqualSlices(\n        u32, &array1, &array2\n    );\n}\n\n1/1 file1ed83cbad6df.test.arrays are equal?...OKAl\n  ll 1 tests passed.\n\n\nAt last, you might also want to use the expectEqualStrings() function. As the name suggests, you can use this function to test if two strings are equal or not. Just provide the two string objects that you want to compare, as inputs to the function.\nIf the function finds any existing differences between the two strings, then, the function will raise an error, and also, print an error message that shows the exact difference between the two string objects provided, as the example below demonstrates:\n\nconst std = @import(\"std\");\ntest \"strings are equal?\" {\n    const str1 = \"hello, world!\";\n    const str2 = \"Hello, world!\";\n    try std.testing.expectEqualStrings(\n        str1, str2\n    );\n}\n\n1/1 t.test.strings are equal?...\n====== expected this output: =========\nhello, world!␃\n======== instead found this: =========\nHello, world!␃\n======================================\nFirst difference occurs on line 1:\nexpected:\nhello, world!\n^ ('\\x68')\nfound:\nHello, world!\n^ ('\\x48')",
     "crumbs": [
       "<span class='chapter-number'>8</span>  <span class='chapter-title'>Unit tests</span>"
     ]
@@ -834,7 +834,7 @@
     "href": "Chapters/09-error-handling.html#learning-more-about-errors-in-zig",
     "title": "10  Error handling and unions",
     "section": "",
-    "text": "t.zig:8:17: error: error set is discarded\nt.zig:8:17: note: consider using 'try', 'catch', or 'if'\n\n10.1.1 Returning errors from functions\nAs we described in Section 1.2.3, when we have a function that might return an error value, this function normally includes an exclamation mark (!) in its return type annotation. The presence of this exclamation mark indicates that this function might return an error value as result, and, the zig compiler forces you to always handle explicitly the case of this function returning an error value.\nTake a look at the print_name() function below. This function might return an error in the stdout.print() function call, and, as a consequence, its return type (!void) includes an exclamation mark in it.\n\nfn print_name() !void {\n    const stdout = std.getStdOut().writer();\n    try stdout.print(\"My name is Pedro!\", .{});\n}\n\nIn the example above, we are using the exclamation mark to tell the zig compiler that this function might return some error. But which error exactly is returned from this function? For now, we are not specifying a specific error value. For now, we only know that some error value (whatever it is) might be returned.\nBut in fact, you can (if you want to) specify clearly which exact error values might be returned from this function. There are lot of examples of this in the Zig Standard Library. Take this fill() function from the http.Client module as an example. This function returns either a error value of type ReadError, or void.\n\npub fn fill(conn: *Connection) ReadError!void {\n    // The body of this function ...\n}\n\nThis idea of specifying the exact error values that you expect to be returned from the function is interesting. Because they automatically become some sort of documentation of your function, and also, this allows the zig compiler to perform some extra checks over your code. Because the compiler can check if there is any other type of error value that is being generated inside your function, and, that it’s not being accounted for in this return type annotation.\nAnyway, you can list the types of errors that can be returned from the function by listing them on the left side of the exclamation mark. While the valid values stay on the right side of the exclamation mark. So the syntax format become:\n&lt;error-value&gt;!&lt;valid-value&gt;\n\n\n10.1.2 Error sets\nBut what about when we have a single function that might return different types of errors? When you have such a function, you can list all of these different types of errors that can be returned from this function, through a structure in Zig that we call of an error set.\nAn error set is a special case of a union type. It’s a union that contains error values in it. Not all programming languages have a notion of a “union object”. But in summary, a union is just a set of data types. Unions are used to allow an object to have multiple data types. For example, a union of x, y and z, means that an object can be either of type x, or type y or type z.\nWe are going to talk in more depth about unions in Section 10.3. But you can write an error set by writing the keyword error before a pair of curly braces, then you list the error values that can be returned from the function inside this pair of curly braces.\nTake the resolvePath() function below as an example, which comes from the introspect.zig module of the Zig Standard Library. We can see in its return type annotation, that this function return either: 1) a valid slice of u8 values ([]u8); or, 2) one of the three different types of error values listed inside the error set (OutOfMemory, Unexpected, etc.). This is an usage example of an error set.\n\npub fn resolvePath(\n    ally: mem.Allocator,\n    p: []const u8,\n) error{\n    OutOfMemory,\n    CurrentWorkingDirectoryUnlinked,\n    Unexpected,\n}![]u8 {\n    // The body of the function ...\n}\n\nThis is a valid way of annotating the return value of a Zig function. But, if you navigate through the modules that composes the Zig Standard Library, you will notice that, for the majority of cases, the programmers prefer to give a descriptive name to this error set, and then, use this name (or this “label”) of the error set in the return type annotation, instead of using the error set directly.\nWe can see that in the ReadError error set that we showed earlier in the fill() function, which is defined in the http.Client module. So yes, I presented the ReadError as if it was just a standard and single error value, but in fact, it’s an error set defined in the http.Client module, and therefore, it actually represents a set of different error values that might happen inside the fill() function.\nTake a look at the ReadError definition reproduced below. Notice that we are grouping all of these different error values into a single object, and then, we use this object into the return type annotation of the function. Like the fill() function that we showed earlier, or, the readvDirect() function from the same module, which is reproduced below.\n\npub const ReadError = error{\n    TlsFailure,\n    TlsAlert,\n    ConnectionTimedOut,\n    ConnectionResetByPeer,\n    UnexpectedReadFailure,\n    EndOfStream,\n};\n// Some lines of code\npub fn readvDirect(\n        conn: *Connection,\n        buffers: []std.posix.iovec\n    ) ReadError!usize {\n    // The body of the function ...\n}\n\nSo, an error set is just a convenient way of grouping a set of possible error values into a single object, or a single type of an error value.\n\n\n10.1.3 Casting error values\nLet’s suppose you have two different error sets, named A and B. If error set A is a superset of error set B, then, you can cast (or coerce) error values from B into error values of A.\nError sets are just a set of error values. So, if the error set A contains all error values from the error set B, then A becomes a superset of B. You could also say that the error set B is a subset of error set A.\nThe example below demonstrates this idea. Because A contains all values from B, A is a superset of B. In math notation, we would say that \\(A \\supset B\\). As a consequence, we can give an error value from B as input to the cast() function, and, implicitly cast this input into the same error value, but from the A set.\n\nconst std = @import(\"std\");\nconst A = error{\n    ConnectionTimeoutError,\n    DatabaseNotFound,\n    OutOfMemory,\n    InvalidToken,\n};\nconst B = error {\n    OutOfMemory,\n};\n\nfn cast(err: B) A {\n    return err;\n}\n\ntest \"coerce error value\" {\n    const error_value = cast(B.OutOfMemory);\n    try std.testing.expect(\n        error_value == A.OutOfMemory\n    );\n}\n\n1/1 file826379a872a1.test.coerce error value...OKA\n  All 1 tests passed.",
+    "text": "t.zig:8:17: error: error set is discarded\nt.zig:8:17: note: consider using 'try', 'catch', or 'if'\n\n10.1.1 Returning errors from functions\nAs we described in Section 1.2.3, when we have a function that might return an error value, this function normally includes an exclamation mark (!) in its return type annotation. The presence of this exclamation mark indicates that this function might return an error value as result, and, the zig compiler forces you to always handle explicitly the case of this function returning an error value.\nTake a look at the print_name() function below. This function might return an error in the stdout.print() function call, and, as a consequence, its return type (!void) includes an exclamation mark in it.\n\nfn print_name() !void {\n    const stdout = std.getStdOut().writer();\n    try stdout.print(\"My name is Pedro!\", .{});\n}\n\nIn the example above, we are using the exclamation mark to tell the zig compiler that this function might return some error. But which error exactly is returned from this function? For now, we are not specifying a specific error value. For now, we only know that some error value (whatever it is) might be returned.\nBut in fact, you can (if you want to) specify clearly which exact error values might be returned from this function. There are lot of examples of this in the Zig Standard Library. Take this fill() function from the http.Client module as an example. This function returns either a error value of type ReadError, or void.\n\npub fn fill(conn: *Connection) ReadError!void {\n    // The body of this function ...\n}\n\nThis idea of specifying the exact error values that you expect to be returned from the function is interesting. Because they automatically become some sort of documentation of your function, and also, this allows the zig compiler to perform some extra checks over your code. Because the compiler can check if there is any other type of error value that is being generated inside your function, and, that it’s not being accounted for in this return type annotation.\nAnyway, you can list the types of errors that can be returned from the function by listing them on the left side of the exclamation mark. While the valid values stay on the right side of the exclamation mark. So the syntax format become:\n&lt;error-value&gt;!&lt;valid-value&gt;\n\n\n10.1.2 Error sets\nBut what about when we have a single function that might return different types of errors? When you have such a function, you can list all of these different types of errors that can be returned from this function, through a structure in Zig that we call of an error set.\nAn error set is a special case of a union type. It’s a union that contains error values in it. Not all programming languages have a notion of a “union object”. But in summary, a union is just a set of data types. Unions are used to allow an object to have multiple data types. For example, a union of x, y and z, means that an object can be either of type x, or type y or type z.\nWe are going to talk in more depth about unions in Section 10.3. But you can write an error set by writing the keyword error before a pair of curly braces, then you list the error values that can be returned from the function inside this pair of curly braces.\nTake the resolvePath() function below as an example, which comes from the introspect.zig module of the Zig Standard Library. We can see in its return type annotation, that this function return either: 1) a valid slice of u8 values ([]u8); or, 2) one of the three different types of error values listed inside the error set (OutOfMemory, Unexpected, etc.). This is an usage example of an error set.\n\npub fn resolvePath(\n    ally: mem.Allocator,\n    p: []const u8,\n) error{\n    OutOfMemory,\n    CurrentWorkingDirectoryUnlinked,\n    Unexpected,\n}![]u8 {\n    // The body of the function ...\n}\n\nThis is a valid way of annotating the return value of a Zig function. But, if you navigate through the modules that composes the Zig Standard Library, you will notice that, for the majority of cases, the programmers prefer to give a descriptive name to this error set, and then, use this name (or this “label”) of the error set in the return type annotation, instead of using the error set directly.\nWe can see that in the ReadError error set that we showed earlier in the fill() function, which is defined in the http.Client module. So yes, I presented the ReadError as if it was just a standard and single error value, but in fact, it’s an error set defined in the http.Client module, and therefore, it actually represents a set of different error values that might happen inside the fill() function.\nTake a look at the ReadError definition reproduced below. Notice that we are grouping all of these different error values into a single object, and then, we use this object into the return type annotation of the function. Like the fill() function that we showed earlier, or, the readvDirect() function from the same module, which is reproduced below.\n\npub const ReadError = error{\n    TlsFailure,\n    TlsAlert,\n    ConnectionTimedOut,\n    ConnectionResetByPeer,\n    UnexpectedReadFailure,\n    EndOfStream,\n};\n// Some lines of code\npub fn readvDirect(\n        conn: *Connection,\n        buffers: []std.posix.iovec\n    ) ReadError!usize {\n    // The body of the function ...\n}\n\nSo, an error set is just a convenient way of grouping a set of possible error values into a single object, or a single type of an error value.\n\n\n10.1.3 Casting error values\nLet’s suppose you have two different error sets, named A and B. If error set A is a superset of error set B, then, you can cast (or coerce) error values from B into error values of A.\nError sets are just a set of error values. So, if the error set A contains all error values from the error set B, then A becomes a superset of B. You could also say that the error set B is a subset of error set A.\nThe example below demonstrates this idea. Because A contains all values from B, A is a superset of B. In math notation, we would say that \\(A \\supset B\\). As a consequence, we can give an error value from B as input to the cast() function, and, implicitly cast this input into the same error value, but from the A set.\n\nconst std = @import(\"std\");\nconst A = error{\n    ConnectionTimeoutError,\n    DatabaseNotFound,\n    OutOfMemory,\n    InvalidToken,\n};\nconst B = error {\n    OutOfMemory,\n};\n\nfn cast(err: B) A {\n    return err;\n}\n\ntest \"coerce error value\" {\n    const error_value = cast(B.OutOfMemory);\n    try std.testing.expect(\n        error_value == A.OutOfMemory\n    );\n}\n\n1/1 file1f7f62fdbe33.test.coerce error value...OKA\n  All 1 tests passed.",
     "crumbs": [
       "<span class='chapter-number'>10</span>  <span class='chapter-title'>Error handling and unions</span>"
     ]
@@ -954,7 +954,7 @@
     "href": "Chapters/10-stack-project.html#sec-comptime",
     "title": "12  Project 3 - Building a stack data structure",
     "section": "",
-    "text": "apply comptime on a function argument.\napply comptime on an object.\napply comptime on a block of expressions.\n\n\n12.1.1 Applying over a function argument\nWhen you apply the comptime keyword on a function argument, you are saying to the zig compiler that the value assigned to that particular function argument must be known at compile-time. We explained in detail in Section 3.1.1 what exactly “value known at compile-time” means. So if you have any doubts about this idea, refer back to that section.\nNow let’s think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement to that particular function argument. If the programmer accidentally tries to give a value to this function argument that is not known at compile time, the zig compiler will notice this problem, and as a consequence, it will raise a compilation error saying that it cannot compile your program. Because you are providing a value that is “runtime known” to a function argument that must be “compile-time known”.\nTake a look at this very simple example below, where we define a twice() function, that simply doubles the input value named num. Notice that we use the comptime keyword before the name of the function argument. This keyword is marking the function argument num as a “comptime argument”.\nThat is a function argument whose value must be compile-time known. This is why the expression twice(5678) is valid, and no compilation errors are raised. Because the value 5678 is compile-time known, so this is the expected behaviour for this function.\n\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n\n1/1 filef044375a1f16.test.test comptime...OKAll 1 \n   tests passed.\n\n\nBut what if we provide a number that is not compile-time known to this function? For example, your program might receive some input from the user through the stdin channel of your system. This input from the user might be many different things, and cannot be predicted at compile-time. These circumstances make this “input from the user” a value that is runtime-known only.\nIn the example below, this “input from the user” is initially received as a string, which is then parsed and transformed into a integer value, and the result of this operation is stored inside the n object.\nBecause the “input of the user” is known only at runtime, the value of the object n is determined only at runtime. As consequence, we cannot provide this object as input to the twice() function. The zig compiler will not allow it, because we marked the num argument as a “comptime argument”. That is why the zig compiler raises the compile-time error exposed below:\n\nconst std = @import(\"std\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\n\npub fn main() !void {\n    var buffer: [5]u8 = .{ 0, 0, 0, 0, 0 };\n    const stdout = std.io.getStdOut().writer();\n    const stdin = std.io.getStdIn().reader();\n    _ = try stdout.write(\"Please write a 4-digit integer number\\n\");\n    _ = try stdin.readUntilDelimiter(&buffer, '\\n');\n\n    try stdout.print(\"Input: {s}\", .{buffer});\n    const n: u32 = try std.fmt.parseInt(\n        u32, buffer[0 .. buffer.len - 1], 10\n    );\n    const twice_result = twice(n);\n    try stdout.print(\"Result: {d}\\n\", .{twice_result});\n}\n\nt.zig:12:16: error: unable to resolve comptime value\n    const twice_result = twice(n);\n                               ^\nComptime arguments are frequently used on functions that return some sort of generic structure. In fact, comptime is the essence (or the basis) to make generics in Zig. We are going to talk more about generics in Section 12.2.\nFor now, let’s take a look at this code example from Seguin (2024). You can see that this IntArray() function has one argument named length. This argument is marked as comptime, and receives a value of type usize as input. So the value given to this argument must be compile-time known. We can also see that this function returns an array of i64 values as output.\n\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n\nNow, the key component of this function is the length argument. This argument is used to determine the size of the array that is produced by the function. Let’s think about the consequences of that. If the size of the array is dependent on the value assigned to the length argument, this means that the data type of the output of the function depends on the value of this length argument.\nLet this statement sink for a bit in your mind. As I described in Section 1.2.2, Zig is a strongly-typed language, especially on function declarations. So every time we write a function in Zig, we have to annotate the data type of the value returned by the function. But how can we do that, if this data type depends on the value given to the argument of the function?\nThink about this for a second. If length is equal to 3 for example, then, the return type of the function is [3]i64. But if length is equal to 40, then, the return type becomes [40]i64. At this point the zig compiler would be confused, and raise a compilation error, saying something like this:\n\nHey! You have annotated that this function should return a [3]i64 value, but I got a [40]i64 value instead! This doesn’t look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when the type keyword comes in. This type keyword is basically saying to the zig compiler that this function will return some data type as output, but it doesn’t know yet what exactly data type that is. We will talk more about this in Section 12.2.\n\n\n12.1.2 Applying over an expression\nWhen you apply the comptime keyword over an expression, then, it is guaranteed that the zig compiler will execute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time (e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the zig compiler will raise a compilation error.\nTake this example from the official documentation of Zig (Zig Software Foundation 2024). We are executing the same fibonacci() function both at runtime, and, at compile-time. The function is executed by default at runtime, but because we use the comptime keyword in the second “try expression”, this expression is executed at compile-time.\nThis might be a bit confusing for some people. Yes! When I say that this expression is executed at compile-time, I mean that this expression is compiled and executed while the zig compiler is compiling your Zig source code.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n\n1/1 filef0447cb16f4d.test.fibonacci...OKAll 1 test\n  ts passed.\n\n\nA lot of your Zig source code might be potentially executed at compile-time, because the zig compiler can figure out the output of some expressions. Especially if these expressions depend only on compile-time known values. We have talked about this in Section 3.1.1.\nBut when you use the comptime keyword on an expression, there is no “it might be executed at compile-time” anymore. With the comptime keyword you are ordering the zig compiler to execute this expression at compile-time. You are imposing this rule, it is guaranteed that the compiler will always execute it at compile-time. Or, at least, the compiler will try to execute it. If the compiler cannot execute the expression for whatever reason, the compiler will raise a compilation error.\n\n\n12.1.3 Applying over a block\nBlocks were described in Section 1.7. When you apply the comptime keyword to a block of expressions, you get essentially the same effect as when you apply this keyword to a single expression. That is, the entire block of expressions is executed at compile-time by the zig compiler.\nIn the example below, we mark the block labeled of blk as a comptime block, and, therefore, the expressions inside this block are executed at compile-time.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n\n1/1 filef044524d5e27.test.fibonacci in a block...O\n  OKAll 1 tests passed.",
+    "text": "apply comptime on a function argument.\napply comptime on an object.\napply comptime on a block of expressions.\n\n\n12.1.1 Applying over a function argument\nWhen you apply the comptime keyword on a function argument, you are saying to the zig compiler that the value assigned to that particular function argument must be known at compile-time. We explained in detail in Section 3.1.1 what exactly “value known at compile-time” means. So if you have any doubts about this idea, refer back to that section.\nNow let’s think about the consequences of this idea. First of all, we are imposing a limit, or, a requirement to that particular function argument. If the programmer accidentally tries to give a value to this function argument that is not known at compile time, the zig compiler will notice this problem, and as a consequence, it will raise a compilation error saying that it cannot compile your program. Because you are providing a value that is “runtime known” to a function argument that must be “compile-time known”.\nTake a look at this very simple example below, where we define a twice() function, that simply doubles the input value named num. Notice that we use the comptime keyword before the name of the function argument. This keyword is marking the function argument num as a “comptime argument”.\nThat is a function argument whose value must be compile-time known. This is why the expression twice(5678) is valid, and no compilation errors are raised. Because the value 5678 is compile-time known, so this is the expected behaviour for this function.\n\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\ntest \"test comptime\" {\n    _ = twice(5678);\n}\n\n1/1 file20a25a72e5e3.test.test comptime...OKAll 1 \n   tests passed.\n\n\nBut what if we provide a number that is not compile-time known to this function? For example, your program might receive some input from the user through the stdin channel of your system. This input from the user might be many different things, and cannot be predicted at compile-time. These circumstances make this “input from the user” a value that is runtime-known only.\nIn the example below, this “input from the user” is initially received as a string, which is then parsed and transformed into a integer value, and the result of this operation is stored inside the n object.\nBecause the “input of the user” is known only at runtime, the value of the object n is determined only at runtime. As consequence, we cannot provide this object as input to the twice() function. The zig compiler will not allow it, because we marked the num argument as a “comptime argument”. That is why the zig compiler raises the compile-time error exposed below:\n\nconst std = @import(\"std\");\nfn twice(comptime num: u32) u32 {\n    return num * 2;\n}\n\npub fn main() !void {\n    var buffer: [5]u8 = .{ 0, 0, 0, 0, 0 };\n    const stdout = std.io.getStdOut().writer();\n    const stdin = std.io.getStdIn().reader();\n    _ = try stdout.write(\"Please write a 4-digit integer number\\n\");\n    _ = try stdin.readUntilDelimiter(&buffer, '\\n');\n\n    try stdout.print(\"Input: {s}\", .{buffer});\n    const n: u32 = try std.fmt.parseInt(\n        u32, buffer[0 .. buffer.len - 1], 10\n    );\n    const twice_result = twice(n);\n    try stdout.print(\"Result: {d}\\n\", .{twice_result});\n}\n\nt.zig:12:16: error: unable to resolve comptime value\n    const twice_result = twice(n);\n                               ^\nComptime arguments are frequently used on functions that return some sort of generic structure. In fact, comptime is the essence (or the basis) to make generics in Zig. We are going to talk more about generics in Section 12.2.\nFor now, let’s take a look at this code example from Seguin (2024). You can see that this IntArray() function has one argument named length. This argument is marked as comptime, and receives a value of type usize as input. So the value given to this argument must be compile-time known. We can also see that this function returns an array of i64 values as output.\n\nfn IntArray(comptime length: usize) type {\n    return [length]i64;\n}\n\nNow, the key component of this function is the length argument. This argument is used to determine the size of the array that is produced by the function. Let’s think about the consequences of that. If the size of the array is dependent on the value assigned to the length argument, this means that the data type of the output of the function depends on the value of this length argument.\nLet this statement sink for a bit in your mind. As I described in Section 1.2.2, Zig is a strongly-typed language, especially on function declarations. So every time we write a function in Zig, we have to annotate the data type of the value returned by the function. But how can we do that, if this data type depends on the value given to the argument of the function?\nThink about this for a second. If length is equal to 3 for example, then, the return type of the function is [3]i64. But if length is equal to 40, then, the return type becomes [40]i64. At this point the zig compiler would be confused, and raise a compilation error, saying something like this:\n\nHey! You have annotated that this function should return a [3]i64 value, but I got a [40]i64 value instead! This doesn’t look right!\n\nSo how can you solve this problem? How do we overcome this barrier? This is when the type keyword comes in. This type keyword is basically saying to the zig compiler that this function will return some data type as output, but it doesn’t know yet what exactly data type that is. We will talk more about this in Section 12.2.\n\n\n12.1.2 Applying over an expression\nWhen you apply the comptime keyword over an expression, then, it is guaranteed that the zig compiler will execute this expression at compile-time. If for some reason, this expression cannot be executed at compile-time (e.g. for example, maybe this expression depends on a value that is only known at runtime), then, the zig compiler will raise a compilation error.\nTake this example from the official documentation of Zig (Zig Software Foundation 2024). We are executing the same fibonacci() function both at runtime, and, at compile-time. The function is executed by default at runtime, but because we use the comptime keyword in the second “try expression”, this expression is executed at compile-time.\nThis might be a bit confusing for some people. Yes! When I say that this expression is executed at compile-time, I mean that this expression is compiled and executed while the zig compiler is compiling your Zig source code.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci\" {\n    // test fibonacci at run-time\n    try expect(fibonacci(7) == 13);\n    // test fibonacci at compile-time\n    try comptime expect(fibonacci(7) == 13);\n}\n\n1/1 file20a26d02bee1.test.fibonacci...OKAll 1 test\n  ts passed.\n\n\nA lot of your Zig source code might be potentially executed at compile-time, because the zig compiler can figure out the output of some expressions. Especially if these expressions depend only on compile-time known values. We have talked about this in Section 3.1.1.\nBut when you use the comptime keyword on an expression, there is no “it might be executed at compile-time” anymore. With the comptime keyword you are ordering the zig compiler to execute this expression at compile-time. You are imposing this rule, it is guaranteed that the compiler will always execute it at compile-time. Or, at least, the compiler will try to execute it. If the compiler cannot execute the expression for whatever reason, the compiler will raise a compilation error.\n\n\n12.1.3 Applying over a block\nBlocks were described in Section 1.7. When you apply the comptime keyword to a block of expressions, you get essentially the same effect as when you apply this keyword to a single expression. That is, the entire block of expressions is executed at compile-time by the zig compiler.\nIn the example below, we mark the block labeled of blk as a comptime block, and, therefore, the expressions inside this block are executed at compile-time.\n\nconst expect = @import(\"std\").testing.expect;\nfn fibonacci(index: u32) u32 {\n    if (index &lt; 2) return index;\n    return fibonacci(index - 1) + fibonacci(index - 2);\n}\n\ntest \"fibonacci in a block\" {\n    const x = comptime blk: {\n        const n1 = 5;\n        const n2 = 2;\n        const n3 = n1 + n2;\n        try expect(fibonacci(n3) == 13);\n        break :blk n3;\n    };\n    _ = x;\n}\n\n1/1 file20a238222e11.test.fibonacci in a block...O\n  OKAll 1 tests passed.",
     "crumbs": [
       "<span class='chapter-number'>12</span>  <span class='chapter-title'>Project 3 - Building a stack data structure</span>"
     ]
diff --git a/index.qmd b/index.qmd
index 734973c3..2baf7a1f 100644
--- a/index.qmd
+++ b/index.qmd
@@ -15,7 +15,8 @@ knitr::opts_chunk$set(
 
 
 
-::: {.content-visible when-format="html"}
+:::: {.content-hidden when-format="epub"}
+::: {.content-hidden when-format="pdf"}
 
 # Welcome {.unnumbered}
 
@@ -66,6 +67,7 @@ If you do have a Revolut account, you can scan the following QR code:
 {{< include ./Assets/revolut-button.html >}}
 
 :::
+::::
 
 
 ## About this book {.unnumbered}

From 54826ddc1ac9d59a5a408b4cc97c274177068f28 Mon Sep 17 00:00:00 2001
From: pedropark99 <pedropark99@gmail.com>
Date: Wed, 28 May 2025 17:24:45 -0300
Subject: [PATCH 144/151] Remove epub

---
 .../05-pointers/execute-results/epub.json     | 21 -------------------
 1 file changed, 21 deletions(-)
 delete mode 100644 _freeze/Chapters/05-pointers/execute-results/epub.json

diff --git a/_freeze/Chapters/05-pointers/execute-results/epub.json b/_freeze/Chapters/05-pointers/execute-results/epub.json
deleted file mode 100644
index 8ff2a6f8..00000000
--- a/_freeze/Chapters/05-pointers/execute-results/epub.json
+++ /dev/null
@@ -1,21 +0,0 @@
-{
-  "hash": "8201d761dfd46af14c754587b77047a2",
-  "result": {
-    "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n\n# Pointers and Optionals {#sec-pointer}\n\nOn our next project we are going to build a HTTP server from scratch.\nBut in order to do that, we need to learn more about pointers and how they work in Zig.\nPointers in Zig are similar to pointers in C. But they come with some extra advantages in Zig.\n\nA pointer is an object that contains a memory address. This memory address is the address where\na particular value is stored in memory. It can be any value. Most of the times,\nit's a value that comes from another object (or variable) present in our code.\n\nIn the example below, I'm creating two objects (`number` and `pointer`).\nThe `pointer` object contains the memory address where the value of the `number` object\n(the number 5) is stored. So, that is a pointer in a nutshell. It's a memory\naddress that points to a particular existing value in the memory. You could\nalso say, that, the `pointer` object points to the memory address where the `number` object is\nstored.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number: u8 = 5;\nconst pointer = &number;\n_ = pointer;\n```\n:::\n\n\n\nWe create a pointer object in Zig by using the `&` operator. When you put this operator\nbefore the name of an existing object, you get the memory address of this object as result.\nWhen you store this memory address inside a new object, this new object becomes a pointer object.\nBecause it stores a memory address.\n\nPeople mostly use pointers as an alternative way to access a particular value.\nFor example, I can use the `pointer` object to access the value stored by\nthe `number` object. This operation of accessing the value that the\npointer \"points to\" is normally called of *dereferencing the pointer*.\nWe can dereference a pointer in Zig by using the `*` method of the pointer object. Like in the example\nbelow, where we take the number 5 pointed by the `pointer` object,\nand double it.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number: u8 = 5;\nconst pointer = &number;\nconst doubled = 2 * pointer.*;\nstd.debug.print(\"{d}\\n\", .{doubled});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n10\n```\n\n\n:::\n:::\n\n\n\n\nThis syntax to dereference the pointer is nice. Because we can easily chain it with\nmethods of the value pointed by the pointer. We can use the `User` struct that we have\ncreated in @sec-structs-and-oop as an example. If you comeback to that section,\nyou will see that this struct have a method named `print_name()`.\n\nSo, for example, if we have an user object, and a pointer that points to this user object,\nwe can use the pointer to access this user object, and, at the same time, call the method `print_name()`\non it, by chaining the dereference method (`*`) with the `print_name()` method. Like in the\nexample below:\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst u = User.init(1, \"pedro\", \"email@gmail.com\");\nconst pointer = &u;\ntry pointer.*.print_name();\n```\n:::\n\n\n\n```\npedro\n```\n\nWe can also use pointers to effectively alter the value of an object.\nFor example, I could use the `pointer` object to set\nthe value of the object `number` to 6, like in the example below.\n\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n6\n```\n\n\n:::\n:::\n\n\n\n\nTherefore, as I mentioned earlier, people use pointers as an alternative way to access a particular value.\nAnd they use it especially when they do not want to \"move\" these values around. There are situations where,\nyou want to access a particular value in a different scope (i.e., a different location) of your code,\nbut you do not want to \"move\" this value to this new scope (or location) that you are in.\n\nThis matters especially if this value is big in size. Because if it is, then,\nmoving this value becomes an expensive operation to do.\nThe computer will have to spend a considerable amount of time\ncopying this value to this new location.\n\nTherefore, many programmers prefer to avoid this heavy operation of copying the value\nto the new location, by accessing this value through pointers.\nWe are going to talk more about this \"moving operation\" over the next sections.\nFor now, just keep in mind that avoiding this \"move operation\" is\none of main reasons why pointers are used in programming languages.\n\n\n\n\n\n## Constant objects vs variable objects {#sec-pointer-var}\n\nYou can have a pointer that points to a constant object, or, a pointer that points to a variable object.\nBut regardless of who this pointer is, a pointer **must always respect the characteristics of the object that it points to**.\nAs a consequence, if the pointer points to a constant object, then, you cannot use this pointer\nto change the value that it points to. Because it points to a value that is constant. As we discussed in @sec-assignments, you cannot\nchange a value that is constant.\n\nFor example, if I have a `number` object, which is constant, I cannot execute\nthe expression below where I'm trying to change the value of `number` to 6 through\nthe `pointer` object. As demonstrated below, when you try to do something\nlike that, you get a compile time error:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst number = 5;\nconst pointer = &number;\npointer.* = 6;\n```\n:::\n\n\n\n```\np.zig:6:12: error: cannot assign to constant\n    pointer.* = 6;\n```\n\nIf I change the `number` object to be a variable object, by introducing the `var` keyword,\nthen, I can successfully change the value of this object through a pointer, as demonstrated below:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nconst pointer = &number;\npointer.* = 6;\ntry stdout.print(\"{d}\\n\", .{number});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n6\n```\n\n\n:::\n:::\n\n\n\nYou can see this relationship between \"constant versus variable\" on the data type of\nyour pointer object. In other words, the data type of a pointer object already gives you\nsome clues about whether the value that it points to is constant or not.\n\nWhen a pointer object points to a constant value, then, this pointer have a data type `*const T`,\nwhich means \"a pointer to a constant value of type `T`\".\nIn contrast, if the pointer points to a variable value, then, the type of the pointer is usually `*T`, which is\nsimply \"a pointer to a value of type `T`\".\nHence, whenever you see a pointer object whose data type is in the format `*const T`, then,\nyou know that you cannot use this pointer to change the value that it points to.\nBecause this pointer points to a constant value of type `T`.\n\n\nWe have talked about the value pointed by the pointer being constant or not,\nand the consequences that arises from it. But, what about the pointer object itself? I mean, what happens\nif the pointer object itself is constant or not? Think about it.\nWe can have a constant pointer that points to a constant value.\nBut we can also have a variable pointer that points to a constant value. And vice-versa.\n\nUntil this point, the `pointer` object was always constant,\nbut what does this mean for us? What is the consequence of the\n`pointer` object being constant? The consequence is that\nwe cannot change the pointer object, because it is constant. We can use the\npointer object in multiple ways, but we cannot change the\nmemory address that is inside this pointer object.\n\nHowever, if we mark the `pointer` object as a variable object,\nthen, we can change the memory address pointed by this `pointer` object.\nThe example below demonstrates that. Notice that the object pointed\nby the `pointer` object changes from `c1` to `c2`.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst c1: u8 = 5;\nconst c2: u8 = 6;\nvar pointer = &c1;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\npointer = &c2;\ntry stdout.print(\"{d}\\n\", .{pointer.*});\n```\n:::\n\n\n\n```\n5\n6\n```\n\nThus, by setting the `pointer` object to a `var` or `const` object,\nyou specify if the memory address contained in this pointer object can change or not\nin your program. On the other side, you can change the value pointed by the pointer,\nif, and only if this value is stored in a variable object. If this value\nis in a constant object, then, you cannot change this value through a pointer.\n\n\n## Types of pointer\n\nIn Zig, there are two types of pointers [@zigdocs], which are:\n\n- single-item pointer (`*`);\n- many-item pointer (`[*]`);\n\n\nSingle-item pointer objects are objects whose data types are in the format `*T`.\nSo, for example, if an object have a data type `*u32`, it means that, this\nobject contains a single-item pointer that points to an unsigned 32-bit integer value.\nAs another example, if an object have type `*User`, then, it contains\na single-item pointer to an `User` value.\n\nIn contrast, many-item pointers are objects whose data types are in the format `[*]T`.\nNotice that the star symbol (`*`) is now inside a pair of brackets (`[]`). If the star\nsymbol is inside a pair of brackets, you know that this object is a many-item pointer.\n\nWhen you apply the `&` operator over an object, you will always get a single-item pointer.\nMany-item pointers are more of a \"internal type\" of the language, more closely\nrelated to slices. So, when you deliberately create a pointer with the `&` operator,\nyou always get a single-item pointer as result.\n\n\n\n## Pointer arithmetic\n\nPointer arithmetic is available in Zig, and they work the same way they work in C.\nWhen you have a pointer that points to an array, the pointer usually points to\nthe first element in the array, and you can use pointer arithmetic to\nadvance this pointer and access the other elements in the array.\n\n\nNotice in the example below, that initially, the `ptr` object was pointing\nto the first element in the array `ar`. But then, I started to walk through the array, by advancing\nthe pointer with simple pointer arithmetic.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [_]i32{ 1, 2, 3, 4 };\nvar ptr: [*]const i32 = &ar;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\nptr += 1;\ntry stdout.print(\"{d}\\n\", .{ptr[0]});\n```\n:::\n\n\n\n```\n1\n2\n3\n```\n\nAlthough you can create a pointer to an array like that, and\nstart to walk through this array by using pointer arithmetic,\nin Zig, we prefer to use slices, which were presented in @sec-arrays.\n\nBehind the hood, slices already are pointers,\nand they also come with the `len` property, which indicates\nhow many elements are in the slice. This is good because the `zig` compiler\ncan use it to check for potential buffer overflows, and other problems like that.\n\nAlso, you don't need to use pointer arithmetic to walk through the elements\nof a slice. You can simply use the `slice[index]` syntax to directly access\nany element you want in the slice.\nAs I mentioned in @sec-arrays, you can get a slice from an array by using\na range selector inside brackets. In the example below, I'm creating\na slice (`sl`) that covers the entire `ar` array. I can access any\nelement of `ar` from this slice, and, the slice itself already is a pointer\nbehind the hood.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst ar = [_]i32{1,2,3,4};\nconst sl = ar[0..ar.len];\n_ = sl;\n```\n:::\n\n\n\n\n## Optionals and Optional Pointers\n\nLet's talk about optionals and how they relate to pointers in Zig.\nBy default, objects in Zig are **non-nullable**. This means that, in Zig,\nyou can safely assume that any object in your source code is not null.\n\nThis is a powerful feature of Zig when you compare it to the developer experience in C.\nBecause in C, any object can be null at any point, and, as consequence, a pointer in C\nmight point to a null value. This is a common source of undefined behaviour in C.\nWhen programmers work with pointers in C, they have to constantly check if\ntheir pointers are pointing to null values or not.\n\nIf for some reason, your Zig code produces a null value somewhere, and, this null\nvalue ends up in an object that is non-nullable, a runtime error is always\nraised by your Zig program. Take the program below as an example.\nThe `zig` compiler can see the `null` value at compile time, and, as result,\nit raises a compile time error. But, if a `null` value is raised during\nruntime, a runtime error is also raised by the Zig program, with a\n\"attempt to use null value\" message.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar number: u8 = 5;\nnumber = null;\n```\n:::\n\n\n```\np5.zig:5:14: error: expected type 'u8',\n        found '@TypeOf(null)'\n    number = null;\n             ^~~~\n```\n\n\nYou don't get this type of safety in C.\nIn C, you don't get warnings or errors about null values being produced in your program.\nIf for some reason, your code produces a null value in C, most of the times, you end up getting a segmentation fault error\nas result, which can mean many things.\nThat is why programmers have to constantly check for null values in C.\n\nPointers in Zig are also, by default, **non-nullable**. This is another amazing\nfeature in Zig. So, you can safely assume that any pointer that you create in\nyour Zig code is pointing to a non-null value.\nTherefore, you don't have this heavy work of checking if the pointers you create\nin Zig are pointing to a null value.\n\n\n### What are optionals?\n\nOk, we know now that all objects are non-nullable by default in Zig.\nBut what if we actually need to use an object that might receive a null value?\nHere is where optionals come in.\n\nAn optional object in Zig is an object that can be null.\nTo mark an object as optional, we use the `?` operator. When you put\nthis `?` operator right before the data type of an object, you transform\nthis data type into an optional data type, and the object becomes an optional object.\n\nTake the snippet below as an example. We are creating a new variable object\ncalled `num`. This object have the data type `?i32`, which means that,\nthis object contains either a signed 32-bit integer (`i32`), or, a null value.\nBoth alternatives are valid values to the `num` object.\nThat is why, I can actually change the value of this object to null, and,\nno errors are raised by the `zig` compiler, as demonstrated below:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: ?i32 = 5;\nnum = null;\n```\n:::\n\n\n\n### Optional pointers\n\nYou can also mark a pointer object as an optional pointer, meaning that,\nthis object contains either a null value, or, a pointer that points to a value.\nWhen you mark a pointer as optional, the data type of this pointer object\nbecomes `?*const T` or `?*T`, depending if the value pointed by the pointer\nis a constant value or not. The `?` identifies the object as optional, while\nthe `*` identifies it as a pointer object.\n\nIn the example below, we are creating a variable object named `num`, and an\noptional pointer object named `ptr`. Notice that the data type of the object\n`ptr` indicates that it's either a null value, or a pointer to an `i32` value.\nAlso, notice that the pointer object (`ptr`) can be marked as optional, even if\nthe object `num` is not optional.\n\nWhat this code tells us is that, the `num` variable will never contain a null value.\nThis variable will always contain a valid `i32` value. But in contrast, the `ptr` object might contain either a null\nvalue, or, a pointer to an `i32` value.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: i32 = 5;\nvar ptr: ?*i32 = &num;\nptr = null;\nnum = 6;\n```\n:::\n\n\n\nBut what happens if we turn the table, and mark the `num` object as optional,\ninstead of the pointer object. If we do that, then, the pointer object is\nnot optional anymore. It would be a similar (although different) result. Because then, we would have\na pointer to an optional value. In other words, a pointer to a value that is either a\nnull value, or, a not-null value.\n\nIn the example below, we are recreating this idea. Now, the `ptr` object\nhave a data type of `*?i32`, instead of `?*i32`. Notice that the `*` symbol comes before of `?`\nthis time. So now, we have a pointer that points to a value that is either null\n, or, a signed 32-bit integer.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar num: ?i32 = 5;\n// ptr have type `*?i32`, instead of `?*i32`.\nconst ptr = &num;\n_ = ptr;\n```\n:::\n\n\n\n\n### Null handling in optionals {#sec-null-handling}\n\nWhen you have an optional object in your Zig code, you have to explicitly handle\nthe possibility of this object being null. It's like error-handling with `try` and `catch`.\nIn Zig you also have to handle null values like if they were a type of error.\n\nWe can do that, by using either:\n\n- an if statement, like you would do in C.\n- the `orelse` keyword.\n- unwrap the optional value with the `?` method.\n\nWhen you use an if statement, you use a pair of pipes\nto unwrap the optional value, and use this \"unwrapped object\"\ninside the if block.\nUsing the example below as a reference, if the object `num` is null,\nthen, the code inside the if statement is not executed. Otherwise,\nthe if statement will unwrap the object `num` into the `not_null_num`\nobject. This `not_null_num` object is guaranteed to be not null inside\nthe scope of the if statement.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst num: ?i32 = 5;\nif (num) |not_null_num| {\n    try stdout.print(\"{d}\\n\", .{not_null_num});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n5\n```\n\n\n:::\n:::\n\n\n\nNow, the `orelse` keyword behaves like a binary operator. You connect two expressions with this keyword.\nOn the left side of `orelse`, you provide the expression that might result\nin a null value, and on the right side of `orelse`, you provide another expression\nthat will not result in a null value.\n\nThe idea behind the `orelse` keyword is: if the expression on the left side\nresult in a not-null value, then, this not-null value is used. However,\nif this expression on the left side result in a null value, then, the value\nof the expression on the right side is used instead.\n\nLooking at the example below, since the `x` object is currently null, the\n`orelse` decided to use the alternative value, which is the number 15.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst x: ?i32 = null;\nconst dbl = (x orelse 15) * 2;\ntry stdout.print(\"{d}\\n\", .{dbl});\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n30\n```\n\n\n:::\n:::\n\n\n\nYou can use the if statement or the `orelse` keyword, when you want to\nsolve (or deal with) this null value. However, if there is no clear solution\nto this null value, and the most logic and sane path is to simply panic\nand raise a loud error in your program when this null value is encountered,\nyou can use the `?` method of your optional object.\n\nIn essence, when you use this `?` method, the optional object is unwrapped.\nIf a not-null value is found in the optional object, then, this not-null value is used.\nOtherwise, the `unreachable` keyword is used. You can read more about this\n[`unreacheable` keyword at the official documentation](https://ziglang.org/documentation/master/#unreachable)[^un-docs].\nBut in essence, when you build your Zig source code using the build modes `ReleaseSafe` or `Debug`, this\n`unreacheable` keyword causes the program to panic and raise an error during runtime,\nlike in the example below:\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\nfn return_null(n: i32) ?i32 {\n    if (n == 5) return null;\n    return n;\n}\n\npub fn main() !void {\n    const x: i32 = 5;\n    const y: ?i32 = return_null(x);\n    try stdout.print(\"{d}\\n\", .{y.?});\n}\n```\n:::\n\n\n\n```\nthread 12767 panic: attempt to use null value\np7.zig:12:34: 0x103419d in main (p7):\n    try stdout.print(\"{d}\\n\", .{y.?});\n                                 ^\n```\n\n\n[^un-docs]: <https://ziglang.org/documentation/master/#unreachable>.\n",
-    "supporting": [
-      "05-pointers_files"
-    ],
-    "filters": [
-      "rmarkdown/pagebreak.lua"
-    ],
-    "includes": {},
-    "engineDependencies": {
-      "knitr": [
-        "{\"type\":\"list\",\"attributes\":{},\"value\":[]}"
-      ]
-    },
-    "preserve": null,
-    "postProcess": false
-  }
-}
\ No newline at end of file

From c4b68a23f93da5875435f6880ead9a8ecd6d9d2e Mon Sep 17 00:00:00 2001
From: Ariel Otilibili <otilibil@eurecom.fr>
Date: Wed, 4 Jun 2025 21:20:46 +0200
Subject: [PATCH 145/151] memory: base64: Fix typos

s/want to stablish/want to establish/
s/behaves lake/behaves like/

Signed-off-by: Ariel Otilibili <otilibil@eurecom.fr>
---
 Chapters/01-base64.qmd                               | 2 +-
 _freeze/Chapters/01-base64/execute-results/html.json | 2 +-
 docs/Chapters/01-base64.html                         | 2 +-
 docs/Chapters/01-memory.html                         | 2 +-
 docs/search.json                                     | 4 ++--
 5 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/Chapters/01-base64.qmd b/Chapters/01-base64.qmd
index 023250f3..fb9d0c4c 100644
--- a/Chapters/01-base64.qmd
+++ b/Chapters/01-base64.qmd
@@ -88,7 +88,7 @@ is to replace a runtime calculation (which can take a long time to be done) with
 operation.
 
 Instead of calculating the results everytime you need them, you calculate all possible results at once, and then, you store them in an array
-(which behaves lake a "table"). Then, every time you need to use one of the characters in the base64 scale, instead of
+(which behaves like a "table"). Then, every time you need to use one of the characters in the base64 scale, instead of
 using many resources to calculate the exact character to be used, you simply retrieve this character
 from the array where you stored all the possible characters in the base64 scale.
 We retrieve the character that we need directly from memory.
diff --git a/_freeze/Chapters/01-base64/execute-results/html.json b/_freeze/Chapters/01-base64/execute-results/html.json
index 875237c5..35a65af0 100644
--- a/_freeze/Chapters/01-base64/execute-results/html.json
+++ b/_freeze/Chapters/01-base64/execute-results/html.json
@@ -2,7 +2,7 @@
   "hash": "378ceb7f207e1c24d8ca75cf94cd22bf",
   "result": {
     "engine": "knitr",
-    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n# Project 1 - Building a base64 encoder/decoder {#sec-base64}\n\nAs our first small project, I want to implement a base64 encoder/decoder with you.\nBase64 is an encoding system which translates binary data to text.\nA big chunk of the web uses base64 to deliver binary data to systems\nthat can only read text data.\n\nThe most common example of a modern use case for base64 is essentially any email system,\nlike GMail, Outlook, etc. Because email systems normally use\nthe Simple Mail Transfer Protocol (SMTP), which is a web protocol\nthat supports only text data. So, if you need, for any reason, to\nsend a binary file (like for example, a PDF, or an Excel file) as\nan attachment in your email, these binary files are normally\nconverted to base64, before they are included in the SMTP message.\nSo, the base64 encoding is largely used in these email systems to include\nbinary data into the SMTP message.\n\n\n\n\n\n\n## How the base64 algorithm work?\n\nBut how exactly does the algorithm behind the base64 encoding work? Let's discuss that. First, I will\nexplain the base64 scale, which is the 64-character scale that is the basis for\nthe base64 encoding system.\n\nAfter that, I explain the algorithm behind a base64 encoder, which is the part of the algorithm that is responsible for encoding messages\ninto the base64 encoding system. Then, after that, I explain the algorithm behind a base64 decoder, which is\nthe part of the algorithm that is responsible for translating base64 messages back into their original meaning.\n\nIf you are unsure about the differences between an \"encoder\" and a \"decoder\",\ntake a look at @sec-encode-vs-decode.\n\n\n### The base64 scale {#sec-base64-scale}\n\nThe base64 encoding system is based on a scale that goes from 0 to 63 (hence the name).\nEach index in this scale is represented by a character (it's a scale of 64 characters).\nSo, in order to convert some binary data, to the base64 encoding, we need to convert each binary number to the corresponding\ncharacter in this \"scale of 64 characters\".\n\nThe base64 scale starts with all ASCII uppercase letters (A to Z) which represents\nthe first 25 indexes in this scale (0 to 25). After that, we have all ASCII lowercase letters\n(a to z), which represents the range 26 to 51 in the scale. After that, we\nhave the one digit numbers (0 to 9), which represents the indexes from 52 to 61 in the scale.\nFinally, the last two indexes in the scale (62 and 63) are represented by the characters `+` and `/`,\nrespectively.\n\nThese are the 64 characters that compose the base64 scale. The equal sign character (`=`) is not part of the scale itself,\nbut it is a special character in the base64 encoding system. This character is used solely as a suffix, to mark the end of the character sequence,\nor, to mark the end of meaningful characters in the sequence.\n\nThe bullet points below summarises the base64 scale:\n\n- range 0 to 25 is represented by: ASCII uppercase letters `-> [A-Z]`;\n- range 26 to 51 is represented by: ASCII lowercase letters `-> [a-z]`;\n- range 52 to 61 is represented by: one digit numbers `-> [0-9]`;\n- index 62 and 63 are represented by the characters `+` and `/`, respectively;\n- the character `=` represents the end of meaningful characters in the sequence;\n\n\n\n\n### Creating the scale as a lookup table {#sec-base64-table}\n\nThe best way to represent this scale in code, is to represent it as a *lookup table*.\nLookup tables are a classic strategy in computer science to speed up calculations. The basic idea\nis to replace a runtime calculation (which can take a long time to be done) with a basic array indexing\noperation.\n\nInstead of calculating the results everytime you need them, you calculate all possible results at once, and then, you store them in an array\n(which behaves lake a \"table\"). Then, every time you need to use one of the characters in the base64 scale, instead of\nusing many resources to calculate the exact character to be used, you simply retrieve this character\nfrom the array where you stored all the possible characters in the base64 scale.\nWe retrieve the character that we need directly from memory.\n\nWe can start building a Zig struct to store our base64 decoder/encoder logic.\nWe start with the `Base64` struct below. For now, we only have one single data member in this\nstruct, i.e., the member `_table`, which represents our lookup table. We also have an `init()` method,\nto create a new instance of a `Base64` object, and, a `_char_at()` method, which is a\n\"get character at index $x$\" type of function.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Base64 = struct {\n    _table: *const [64]u8,\n\n    pub fn init() Base64 {\n        const upper = \"ABCDEFGHIJKLMNOPQRSTUVWXYZ\";\n        const lower = \"abcdefghijklmnopqrstuvwxyz\";\n        const numbers_symb = \"0123456789+/\";\n        return Base64{\n            ._table = upper ++ lower ++ numbers_symb,\n        };\n    }\n\n    pub fn _char_at(self: Base64, index: usize) u8 {\n        return self._table[index];\n    }\n};\n```\n:::\n\n\n\nIn other words, the `_char_at()` method is responsible for getting the character in the lookup\ntable (i.e., the `_table` struct data member) that corresponds to a particular index in the\n\"base64 scale\". So, in the example below, we know that the character that corresponds to the\nindex 28 in the \"base64 scale\" is the character \"c\".\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst base64 = Base64.init();\ntry stdout.print(\n    \"Character at index 28: {c}\\n\",\n    .{base64._char_at(28)}\n);\n```\n:::\n\n\n```\nCharacter at index 28: c\n```\n\n\n\n### A base64 encoder {#sec-base64-encoder-algo}\n\nThe algorithm behind a base64 encoder usually works on a window of 3 bytes. Because each byte has\n8 bits, so, 3 bytes forms a set of $8 \\times 3 = 24$ bits. This is desirable for the base64 algorithm, because\n24 bits is divisible by 6, which forms $24 / 6 = 4$ groups of 6 bits each.\n\nTherefore, the base64 algorithm works by converting 3 bytes at a time\ninto 4 characters from the base64 scale. It keeps iterating through the input string,\n3 bytes at a time, and converting them into the base64 scale, producing 4 characters\nper iteration. It keeps iterating, and producing these \"new characters\"\nuntil it hits the end of the input string.\n\nNow you may think, what if you have a particular string that has a number of bytes\nthat is not divisible by 3 - what happens? For example, if you have a string\nthat contains only two characters/bytes, such as \"Hi\". How would the algorithm\nbehave in such situation? You find the answer in @fig-base64-algo1.\nYou can see in @fig-base64-algo1 that the string \"Hi\", when converted to base64,\nbecomes the string \"SGk=\":\n\n![The logic behind a base64 encoder](./../Figures/base64-encoder-flow.png){#fig-base64-algo1}\n\nTaking the string \"Hi\" as an example, we have 2 bytes, or, 16 bits in total. So, we lack a full byte (8 bits)\nto complete the window of 24 bits that the base64 algorithm likes to work on. The first thing that\nthe algorithm does, is to check how to divide the input bytes into groups of 6 bits.\n\nIf the algorithm notices that there is a group of 6 bits that it's not complete, meaning that, this group contains $nbits$, where $0 < nbits < 6$,\n\nthe algorithm simply adds extra zeros in this group to fill the space that it needs.\nThat is why in @fig-base64-algo1, in the third group after the 6-bit transformation,\n2 extra zeros were added to fill the gap.\n\nWhen we have a 6-bit group that is not completely full, like the third group, extra zeros\nare added to fill the gap. But what about when an entire 6-bit group is empty, or, it\nsimply doesn't exist? This is the case of the fourth 6-bit group exposed at\n@fig-base64-algo1.\n\nThis fourth group is necessary, because the algorithm works on 4 groups of 6 bits.\nBut the input string does not have enough bytes to create a fourth 6-bit group.\nEvery time this happens, where an entire group of 6 bits is empty,\nthis group becomes a \"padding group\". Every \"padding group\" is mapped to\nthe character `=` (equal sign), which represents \"null\", or, the end\nof meaningful characters in the sequence. Hence, everytime that the algorithm produces a\n\"padding group\", this group is automatically mapped to `=`.\n\nAs another example, if you give the string \"0\" as input to a base64 encoder, this string is\ntranslated into the base64 sequence \"MA==\".\nThe character \"0\" is, in binary, the sequence `00110000`[^zero-note]. So, with the 6-bit transformation\nexposed in @fig-base64-algo1, this single character would produce these two 6-bit groups: `001100`, `000000`.\nThe remaining two 6-bit groups become \"padding groups\". That is why the last\ntwo characters in the output sequence (MA==) are `==`.\n\n\n[^zero-note]: Notice that, the character \"0\" is different than the actual number 0, which is simply zero in binary.\n\n### A base64 decoder {#sec-base64-decoder-algo}\n\nThe algorithm behind a base64 decoder is essentially the inverse process of a base64 encoder.\nA base64 decoder needs to translate base64 messages back into their original meaning,\ni.e., into the original sequence of binary data.\n\nA base64 decoder usually works on a window of 4 bytes. Because it wants to convert these 4 bytes\nback into the original sequence of 3 bytes, that was converted into 4 groups of 6 bits by the\nbase64 encoder. Remember, in a base64 decoder we are essentially reverting the process made\nby the base64 encoder.\n\nEach byte in the input string (the base64 encoded string) normally contributes to re-create\ntwo different bytes in the output (the original binary data).\nIn other words, each byte that comes out of a base64 decoder is created by transforming merging two different\nbytes in the input together. You can visualize this relationship in @fig-base64-algo2:\n\n![The logic behind a base64 decoder](./../Figures/base64-decoder-flow.png){#fig-base64-algo2}\n\nThe exact transformations, or, the exact steps applied to each byte from the input to transform them\ninto the bytes of the output, are a bit tricky to visualize in a figure like this. Because of that, I have\nsummarized these transformations as \"Some bit shifting and additions ...\" in the figure. These transformations\nwill be described in depth later.\n\nBesides that, if you look again in @fig-base64-algo2, you will notice that the character `=` was completely\nignored by the algorithm. Remember, this is just a special character that marks the end of meaningful characters\nin the base64 sequence. So, every `=` character in a base64 encoded sequence should be ignored by a base64 decoder.\n\n\n## Difference between encode and decode {#sec-encode-vs-decode}\n\nIf you don't have any previous experience with base64, you might not understand the differences\nbetween \"encode\" and \"decode\". Essentially, the terms \"encode\" and \"decode\" here\nhave the exact same meaning as they have in the field of encryption (i.e., they mean the same thing as \"encode\" and \"decode\" in hashing\nalgorithms, like the MD5 algorithm).\n\nThus, \"encode\" means that we want to encode, or, in other words, we want to translate some message into\nthe base64 encoding system. We want to produce the sequence of base64 characters that represent this\noriginal message in the base64 encoding system.\n\nIn contrast, \"decode\" represents the inverse process.\nWe want to decode, or, in other words, translate a base64 message back to its original content.\nSo, in this process we get a sequence of base64 characters as input, and produce as output,\nthe binary data that is represented by this sequence of base64 characters.\n\nAny base64 library is normally composed of these two parts: 1) the encoder, which is a function that encodes\n(i.e., it converts) any sequence of binary data into a sequence of base64 characters; 2) the decoder, which is a function\nthat converts a sequence of base64 characters back into the original sequence of binary data.\n\n\n\n## Calculating the size of the output {#sec-base64-length-out}\n\nOne task that we need to do is to calculate how much space we need to reserve for the\noutput, both of the encoder and decoder. This is simple math, and can be done easily in Zig\nbecause every array has its length (its number of elements) easily accesible by consulting\nthe `.len` property of the array.\n\nFor the encoder, the logic is the following: for each 3 bytes that we find in the input,\n4 new bytes are created in the output. So, we take the number of bytes in the input, divide it\nby 3, use a ceiling function, then, we multiply the result by 4. That way, we get the total\nnumber of bytes that will be produced by the encoder in its output.\n\nThe `_calc_encode_length()` function below encapsulates this logic.\nInside this function, we take the length of the input array,\nwe divide it by 3, and apply a ceil operation over the result by using the\n`divCeil()` function from the Zig Standard Library. Lastly, we multiply\nthe end result by 4 to get the answer we need.\n\nAlso, you might have notice that, if the input length is less than 3 bytes, then, the output length of the encoder is\nalways 4 bytes. This is the case for every input with less than 3 bytes, because, as I described in @sec-base64-encoder-algo,\nthe algorithm always produces enough \"padding-groups\" in the end result, to complete the 4 bytes window.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_encode_length(input: []const u8) !usize {\n    if (input.len < 3) {\n        return 4;\n    }\n    const n_groups: usize = try std.math.divCeil(\n        usize, input.len, 3\n    );\n    return n_groups * 4;\n}\n```\n:::\n\n\n\nNow, the logic to calculate the length of the output from the decoder is a little bit more complicated. But, it is basically\njust the inverse logic that we've used for the encoder: for each 4 bytes in the input, 3 bytes\nwill be produced in the output of the decoder. However, this time we need to\ntake the `=` character into account, which is always ignored by the decoder, as we described in @sec-base64-decoder-algo, and,\nin @fig-base64-algo2.\n\nIn essence, we take the length of the input and divide it by 4, then we apply a floor function on the result, then\nwe multiply the result by 3, and then, we subtract from the result how much times the character `=` is found\nin the input.\n\nThe function `_calc_decode_length()` exposed below summarizes this logic that we described. It's similar\nto the function `_calc_encode_length()`. Notice that the division part is twisted. Also notice that this time, we apply\na floor operation over the output of the division, by using the `divFloor()`\nfunction (instead of a ceiling operation with `divCeil()`).\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_decode_length(input: []const u8) !usize {\n    if (input.len < 4) {\n        return 3;\n    }\n\n    const n_groups: usize = try std.math.divFloor(\n        usize, input.len, 4\n    );\n    var multiple_groups: usize = n_groups * 3;\n    var i: usize = input.len - 1;\n    while (i > 0) : (i -= 1) {\n        if (input[i] == '=') {\n            multiple_groups -= 1;\n        } else {\n            break;\n        }\n    }\n\n    return multiple_groups;\n}\n```\n:::\n\n\n\n## Building the encoder logic {#sec-encoder-logic}\n\nIn this section, we can start building the logic behind the `encode()` function, which\nwill be responsible for encoding messages into the base64 encoding system.\nIf you are an anxious person, and you want to see now the full source code of the implementation\nfor this base64 encoder/decoder, you can find it at the `ZigExamples` folder in the official repository of\nthis book[^zig-base64-algo].\n\n[^zig-base64-algo]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/base64/base64_basic.zig>.\n\n\n\n### The 6-bit transformation {#sec-6bit-transf}\n\nThe 6-bit transformation presented in @fig-base64-algo1 is the core part of the base64 encoder algorithm.\nBy understanding how this transformation is made in code, the rest of the algorithm becomes much simpler\nto comprehend.\n\nIn essence, this 6-bit transformation is made with the help of bitwise operators.\nBitwise operators are essential to any type of low-level operation that is done at the bit-level. For the specific case of the base64 algorithm,\nthe operators *bif shift to the left* (`<<`), *bit shift to the right* (`>>`), and the *bitwise and* (`&`) are used. They\nare the core solution for the 6-bit transformation.\n\nThere are 3 different scenarios that we need to take into account in this transformation. First, is the perfect scenario,\nwhere we have the perfect window of 3 bytes to work on. Second, we have the scenario where we have a window of only\ntwo bytes to work with. And last, we have the scenario where we have a window of one single byte.\n\nIn each of these 3 scenarios, the 6-bit transformation works a bit differently. To make the explanation\neasier, I will use the variable `output` to refer to the bytes in the output of the base64 encoder,\nand the variable `input` to refer to the bytes in the input of the encoder.\n\n\nSo, if you have the perfect window of 3 bytes, these are steps for the 6-bit transformation:\n\n1. `output[0]` is produced by moving the bits from `input[0]` two positions to the right.\n1. `output[1]` is produced by summing two components. First, take the last two bits from `input[0]`, then, move them four positions to the left. Second, move the bits from `input[1]` four positions to the right. Sum these two components.\n1. `output[2]` is produced by summing two components. First, take the last four bits from `input[1]`, then, move them two positions to the left. Second, move the bits from `input[2]` six positions to the right. Sum these two components.\n1. `output[3]` is produced by taking the last six bits from `input[2]`.\n\n\nThis is the perfect scenario, where we have a full window of 3 bytes to work on.\nJust to make things as clear as possible, the @fig-encoder-bitshift demonstrates visually how\nthe step 2 mentioned above works. So the 2nd byte in the `output` of the encoder, is made by taking the 1st byte (dark purple)\nand the 2nd byte (orange) from the input. You can see that, at the end of the process, we get a new\nbyte that contains the last 2 bits from the 1st byte in the `input`, and the first 4 bits\nfrom the 2nd byte in the `input`.\n\n![How the 2nd byte in the output of the encoder is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input.](../Figures/base64-encoder-bit-shift.png){#fig-encoder-bitshift}\n\nOn the other hand, we must be prepared for the instances where we do not have the perfect window of 3 bytes.\nIf you have a window of 2 bytes, then, the steps 3 and 4, which produces the bytes `output[2]` and `output[3]`, change a little bit,\nand they become:\n\n- `output[2]` is produced by taking the last 4 bits from `input[1]`, then, move them two positions to the left.\n- `output[3]` is the character `'='`.\n\n\nFinally, if you have a window of a single byte, then, the steps 2 to 4, which produces the bytes `output[1]`, `output[2]` and `output[3]` change,\nbecoming:\n\n- `output[1]` is produced by taking the last two bits from `input[0]`, then, move them four positions to the left.\n- `output[2]` and `output[3]` are the character `=`.\n\n\nIf these bullet points were a bit confusing for you, you may find the @tbl-transf-6bit more intuitive.\nThis table unifies all this logic into a simple table. Notice that\nthis table also provides the exact expression in Zig that creates the corresponding\nbyte in the output.\n\n\n::: {#tbl-transf-6bit}\n\n| Number of bytes in the window | Byte index in the output | In code                                    |\n|-------------------------------|--------------------------|--------------------------------------------|\n| 3                             | 0                        | input[0] >> 2                              |\n| 3                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 3                             | 2                        | ((input[1] & 0x0f) << 2) + (input[2] >> 6) |\n| 3                             | 3                        | input[2] & 0x3f                            |\n| 2                             | 0                        | input[0] >> 2                              |\n| 2                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 2                             | 2                        | ((input[1] & 0x0f) << 2)                   |\n| 2                             | 3                        | '='                                        |\n| 1                             | 0                        | input[0] >> 2                              |\n| 1                             | 1                        | ((input[0] & 0x03) << 4)                   |\n| 1                             | 2                        | '='                                        |\n| 1                             | 3                        | '='                                        |\n\n: How the 6-bit transformation translates into code in different window settings.\n\n:::\n\n\n\n\n\n\n### Bit-shifting in Zig\n\nBit-shifting in Zig works similarly to bit-shifting in C.\nAll bitwise operators that exist in C are available in Zig.\nHere, in the base64 encoder algorithm, they are essential\nto produce the result we want.\n\nFor those who are not familiar with these operators, they are\noperators that operates at the bit-level of your values.\nThis means that these operators takes the bits that form the value\nyou have, and change them in some way. This ultimately also changes\nthe value itself, because the binary representation of this value\nchanges.\n\nWe have already seen in @fig-encoder-bitshift the effect produced by a bit-shift.\nBut let's use the first byte in the output of the base64 encoder as another example of what\nbit-shifting means. This is the easiest byte of the 4 bytes in the output\nto build. Because we only need to move the bits from the first byte in the input two positions to the right,\nwith the *bit shift to the right* (`>>`) operator.\n\nIf we take the string \"Hi\" that we used in @fig-base64-algo1 as an example, the first byte in\nthis string is \"H\", which is the sequence `01001000` in binary.\nIf we move the bits of this byte, two places to the right, we get the sequence `00010010` as result.\nThis binary sequence is the value `18` in decimal, and also, the value `0x12` in hexadecimal.\nNotice that the first 6 bits of \"H\" were moved to the end of the byte.\nWith this operation, we get the first byte of the output.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const input = \"Hi\";\n    try stdout.print(\"{d}\\n\", .{input[0] >> 2});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n18\n```\n\n\n:::\n:::\n\n\nIf you recall @fig-base64-algo1, the first byte present in the output should\nbe equivalent to the 6-bit group `010010`. Although being visually different, the\nsequences `010010` and `00010010` are semantically equal. They mean the same thing.\nThey both represent the number 18 in decimal, and the value `0x12` in hexadecimal.\n\nSo, don't take the \"6-bit group\" factor so seriously. We do not need necessarily to\nget a 6-bit sequence as result. As long as the meaning of the 8-bit sequence we get is the same\nof the 6-bit sequence, we are in the clear.\n\n\n\n### Selecting specific bits with the `&` operator\n\nIf you comeback to @sec-6bit-transf, you will see that, in order to produce\nthe second and third bytes in the output, we need to select specific\nbits from the first and second bytes in the input string. But how\ncan we do that? The answer relies on the *bitwise and* (`&`) operator.\n\nThe @fig-encoder-bitshift already showed you what effect this `&` operator\nproduces in the bits of its operands. But let's make a clear description of it.\n\nIn summary, the `&` operator performs a logical conjunction operation\nbetween the bits of its operands. In more details, the operator `&`\ncompares each bit of the first operand to the corresponding bit of the second operand.\nIf both bits are 1, the corresponding result bit is set to 1.\nOtherwise, the corresponding result bit is set to 0 [@microsoftbitwiseand].\n\nSo, if we apply this operator to the binary sequences `1000100` and `00001101`\nthe result of this operation is the binary sequence `00000100`. Because only\nat the sixth position in both binary sequences we had a 1 value. So any\nposition where we do not have both binary sequences setted to 1, we get\na 0 bit in the resulting binary sequence.\n\nWe lose information about the original bit values\nfrom both sequences in this case. Because we no longer know\nif this 0 bit in the resulting binary sequence was produced by\ncombining 0 with 0, or 1 with 0, or 0 with 1.\n\nAs an example, suppose you have the binary sequence `10010111`, which is the number 151 in decimal. How\ncan we get a new binary sequence which contains only the third and\nfourth bits of this sequence?\n\nWe just need to combine this sequence with `00110000` (is `0x30` in hexadecimal) using the `&` operator.\nNotice that only the third and fourth positions in this binary sequence is setted to 1. As a consequence, only the\nthird and fourth values of both binary sequences are potentially preserved in the output. All the remaining positions\nare setted to zero in the output sequence, which is `00010000` (is the number 16 in decimal).\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const bits = 0b10010111;\n    try stdout.print(\"{d}\\n\", .{bits & 0b00110000});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n16\n```\n\n\n:::\n:::\n\n\n\n\n### Allocating space for the output\n\nAs I described in @sec-stack, to store an object in the stack,\nthis object needs to have a known and fixed length at compile-time. This is an important\nlimitation for our base64 encoder/decoder case. Because the size of\nthe output (from both the encoder and decoder) depends\ndirectly on the size of the input.\n\nHaving this in mind, we cannot know at compile time which is\nthe size of the output for both the encoder and decoder.\nSo, if we can't know the size of the output at compile time,\nthis means that we cannot store the output for both the encoder\nand decoder in the stack.\n\nConsequently, we need to store this output on the heap,\nand, as I commented in @sec-heap, we can only\nstore objects in the heap by using allocator objects.\nSo, one the arguments to both the `encode()` and `decode()`\nfunctions, needs to be an allocator object, because\nwe know for sure that, at some point inside the body of these\nfunctions, we need to allocate space on the heap to\nstore the output of these functions.\n\nThat is why, both the `encode()` and `decode()` functions that I\npresent in this book, have an argument called `allocator`,\nwhich receives a allocator object as input, identified by\nthe type `std.mem.Allocator` from the Zig Standard Library.\n\n\n\n### Writing the `encode()` function\n\nNow that we have a basic understanding on how the bitwise operators work, and how\nexactly they help us to achieve the result we want to achieve. We can now encapsulate\nall the logic that we have described in @fig-base64-algo1 and @tbl-transf-6bit into a nice\nfunction that we can add to our `Base64` struct definition, that we started in @sec-base64-table.\n\nYou can find the `encode()` function below. Notice that the first argument of this function,\nis the `Base64` struct itself. Therefore, this argument clearly signals\nthat this function is a method from the `Base64` struct.\n\nBecause the `encode()` function itself is fairly long,\nI intentionally omitted the `Base64` struct definition in this source code,\njust for brevity reasons. So, just remember that this function is a public function (or a public method) from the\n`Base64` struct.\n\nFurthermore, this `encode()` function has two other arguments:\n\n1. `input` is the input sequence of characters that you want to encode in base64;\n1. `allocator` is an allocator object to use in the necessary memory allocations.\n\nI described everything you need to know about allocator objects in @sec-allocators.\nSo, if you are not familiar with them, I highly recommend you to comeback to\nthat section, and read it.\nBy looking at the `encode()` function, you will see that we use this\nallocator object to allocate enough memory to store the output of\nthe encoding process.\n\nThe main for loop in the function is responsible for iterating through the entire input string.\nIn every iteration, we use a `count` variable to count how many iterations we had at the\nmoment. When `count` reaches 3, then, we try to encode the 3 characters (or bytes) that we have accumulated\nin the temporary buffer object (`buf`).\n\nAfter encoding these 3 characters and storing the result in the `output` variable, we reset\nthe `count` variable to zero, and start to count again on the next iteration of the loop.\nIf the loop hits the end of the string, and, the `count` variable is less than 3, then, it means that\nthe temporary buffer contains the last 1 or 2 bytes from the input.\nThat is why we have two `if` statements after the for loop. To deal which each possible case.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn encode(self: Base64,\n              allocator: std.mem.Allocator,\n              input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n\n    const n_out = try _calc_encode_length(input);\n    var out = try allocator.alloc(u8, n_out);\n    var buf = [3]u8{ 0, 0, 0 };\n    var count: u8 = 0;\n    var iout: u64 = 0;\n\n    for (input, 0..) |_, i| {\n        buf[count] = input[i];\n        count += 1;\n        if (count == 3) {\n            out[iout] = self._char_at(buf[0] >> 2);\n            out[iout + 1] = self._char_at(\n                ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n            );\n            out[iout + 2] = self._char_at(\n                ((buf[1] & 0x0f) << 2) + (buf[2] >> 6)\n            );\n            out[iout + 3] = self._char_at(buf[2] & 0x3f);\n            iout += 4;\n            count = 0;\n        }\n    }\n\n    if (count == 1) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            (buf[0] & 0x03) << 4\n        );\n        out[iout + 2] = '=';\n        out[iout + 3] = '=';\n    }\n\n    if (count == 2) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n        );\n        out[iout + 2] = self._char_at(\n            (buf[1] & 0x0f) << 2\n        );\n        out[iout + 3] = '=';\n        iout += 4;\n    }\n\n    return out;\n}\n```\n:::\n\n\n\n\n## Building the decoder logic {#sec-decoder-logic}\n\nNow, we can focus on writing the base64 decoder logic. Remember from @fig-base64-algo2 that,\na base64 decoder does the inverse process of an encoder. So, all we need to do, is to\nwrite a `decode()` function that performs the inverse process that I exposed in @sec-encoder-logic.\n\n\n### Mapping base64 characters to their indexes {#sec-map-base64-index}\n\nOne thing that we need to do, in order to decode a base64-encoded message, is to calculate\nthe index in the base64 scale of every base64 character that we encounter in the decoder input.\n\nIn other words, the decoder receives as input, a sequence of base64 characters. We need\nto translate this sequence of characters into a sequence of indexes. These indexes\nare the index of each character in the base64 scale. This way, we get the value/byte\nthat was calculated in the 6-bit transformation step of the encoder process.\n\nThere are probably better/faster ways to calculate this, especially using a \"divide and conquer\"\ntype of strategy. But for now, I am satisfied with a simple and \"brute force\" type of strategy.\nThe `_char_index()` function below contains this strategy.\n\nWe are essentially looping through the *lookup table* with the base64 scale,\nand comparing the character we got with each character in the base64 scale.\nIf these characters match, then, we return the index of this character in the\nbase64 scale as the result.\n\nNotice that, if the input character is `'='`, the function returns the index 64, which is\n\"out of range\" in the scale. But, as I described in @sec-base64-scale,\nthe character `'='` does not belong to the base64 scale itself.\nIt's a special and meaningless character in base64.\n\nAlso notice that this `_char_index()` function is a method from our `Base64` struct,\nbecause of the `self` argument. Again, I have omitted the `Base64` struct definition in this example\nfor brevity reasons.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn _char_index(self: Base64, char: u8) u8 {\n    if (char == '=')\n        return 64;\n    var index: u8 = 0;\n    for (0..63) |i| {\n        if (self._char_at(i) == char)\n            break;\n        index += 1;\n    }\n\n    return index;\n}\n```\n:::\n\n\n\n\n### The 6-bit transformation\n\nOnce again, the core part of the algorithm is the 6-bit transformation.\nIf we understand the necessary steps to perform this transformation, the rest\nof the algorithm becomes much easier.\n\nFirst of all, before we actually go to the 6-bit transformation,\nwe need to make sure that we use `_char_index()` to convert the sequence of base64 characters\ninto a sequence of indexes. So the snippet below is important for the job that will be done.\nThe result of `_char_index()` is stored in a temporary buffer, and this temporary buffer\nis what we are going to use in the 6-bit transformation, instead of the actual `input` object.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (0..input.len) |i| {\n    buf[i] = self._char_index(input[i]);\n}\n```\n:::\n\n\nNow, instead of producing 4 bytes (or 4 characters) as output per each window of 3 characters in the input,\na base64 decoder produces 3 bytes (or 3 characters) as output per each window of 4 characters in the input.\nOnce again, is the inverse process.\n\nSo, the steps to produce the 3 bytes in the output are:\n\n1. `output[0]` is produced by summing two components. First, move the bits from `buf[0]` two positions to the left. Second, move the bits from `buf[1]` 4 positions to the right. Then, sum these two components.\n1. `output[1]` is produced by summing two components. First, move the bits from `buf[1]` four positions to the left. Second, move the bits from `buf[2]` 2 positions to the right. Then, sum these two components.\n1. `output[2]` is produced by summing two components. First, move the bits from `buf[2]` six positions to the left. Then, you sum the result with `buf[3]`.\n\n\nBefore we continue, let's try to visualize how these transformations make the original bytes that we had\nbefore the encoding process. First, think back to the 6-bit transformation performed by the encoder exposed in @sec-encoder-logic.\nThe first byte in the output of the encoder is produced by moving the bits in the first byte of the input two positions to the right.\n\nIf for example the first byte in the input of the encoder was the sequence `ABCDEFGH`, then, the first byte in the output of the encoder would be\n`00ABCDEF` (this sequence would be the first byte in the input of the decoder). Now, if the second byte in the input of the encoder was the sequence\n`IJKLMNOP`, then, the second byte in the encoder output would be `00GHIJKL` (as we demonstrated in @fig-encoder-bitshift).\n\nHence, if the sequences `00ABCDEF` and `00GHIJKL` are the first and second bytes, respectively, in the input of the decoder, the\n@fig-decoder-bitshift demonstrates visually how these two bytes are transformed into the first byte of the output of the decoder.\nNotice that the output byte is the sequence `ABCDEFGH`, which is the original byte from the input of the encoder.\n\n![How the 1st byte in the decoder output is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input](../Figures/base64-decoder-bit-shift.png){#fig-decoder-bitshift}\n\nThe @tbl-6bit-decode presents how the three steps described earlier translate into Zig code:\n\n\n\n::: {#tbl-6bit-decode}\n\n| Byte index in the output | In code                       |\n|--------------------------|-------------------------------|\n| 0                        | (buf[0] << 2) + (buf[1] >> 4) |\n| 1                        | (buf[1] << 4) + (buf[2] >> 2) |\n| 2                        | (buf[2] << 6) + buf[3]        |\n\n: The necessary steps for the 6-transformation in the decode process.\n\n\n:::\n\n\n\n\n\n\n\n### Writing the `decode()` function\n\nThe `decode()` function below contains the entire decoding process.\nWe first calculate the size of the output, with\n`_calc_decode_length()`, then, we allocate enough memory for this output with\nthe allocator object.\n\nThree temporary variables are created: 1) `count`, to hold the window count\nin each iteration of the for loop; 2) `iout`, to hold the current index in the output;\n3) `buf`, which is the temporary buffer that holds the base64 indexes to be\nconverted through the 6-bit transformation.\n\nThen, in each iteration of the for loop we fill the temporary buffer with the current\nwindow of bytes. When `count` hits the number 4, then, we have a full window of\nindexes in `buf` to be converted, and then, we apply the 6-bit transformation\nover the temporary buffer.\n\nNotice that we check if the indexes 2 and 3 in the temporary buffer are the number 64, which, if you recall\nfrom @sec-map-base64-index, is when the `_calc_index()` function receives a `'='` character\nas input. So, if these indexes are equal to the number 64, the `decode()` function knows\nthat it can simply ignore these indexes. They are not converted because, as I described before,\nthe character `'='` has no meaning, despite being the end of meaningful characters in the sequence.\nSo we can safely ignore them when they appear in the sequence.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn decode(self: Base64,\n          allocator: std.mem.Allocator,\n          input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n    const n_output = try _calc_decode_length(input);\n    var output = try allocator.alloc(u8, n_output);\n    var count: u8 = 0;\n    var iout: u64 = 0;\n    var buf = [4]u8{ 0, 0, 0, 0 };\n\n    for (0..input.len) |i| {\n        buf[count] = self._char_index(input[i]);\n        count += 1;\n        if (count == 4) {\n            output[iout] = (buf[0] << 2) + (buf[1] >> 4);\n            if (buf[2] != 64) {\n                output[iout + 1] = (buf[1] << 4) + (buf[2] >> 2);\n            }\n            if (buf[3] != 64) {\n                output[iout + 2] = (buf[2] << 6) + buf[3];\n            }\n            iout += 3;\n            count = 0;\n        }\n    }\n\n    return output;\n}\n```\n:::\n\n\n\n## The end result\n\nNow that we have both `decode()` and `encode()` implemented. We have a fully functioning\nbase64 encoder/decoder implemented in Zig. Here is an usage example of our\n`Base64` struct with the `encode()` and `decode()` methods that we have implemented.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar memory_buffer: [1000]u8 = undefined;\nvar fba = std.heap.FixedBufferAllocator.init(\n    &memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst text = \"Testing some more stuff\";\nconst etext = \"VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=\";\nconst base64 = Base64.init();\nconst encoded_text = try base64.encode(\n    allocator, text\n);\nconst decoded_text = try base64.decode(\n    allocator, etext\n);\ntry stdout.print(\n    \"Encoded text: {s}\\n\", .{encoded_text}\n);\ntry stdout.print(\n    \"Decoded text: {s}\\n\", .{decoded_text}\n);\n```\n:::\n\n\n```\nEncoded text: VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=\nDecoded text: Testing some more stuff\n```\n\nYou can also see the full source code at once, by visiting the official repository of this book[^repo].\nMore precisely inside the `ZigExamples` folder[^zig-base64-algo].\n\n[^repo]: <https://github.com/pedropark99/zig-book>\n",
+    "markdown": "---\nengine: knitr\nknitr: true\nsyntax-definition: \"../Assets/zig.xml\"\n---\n\n\n\n\n\n\n# Project 1 - Building a base64 encoder/decoder {#sec-base64}\n\nAs our first small project, I want to implement a base64 encoder/decoder with you.\nBase64 is an encoding system which translates binary data to text.\nA big chunk of the web uses base64 to deliver binary data to systems\nthat can only read text data.\n\nThe most common example of a modern use case for base64 is essentially any email system,\nlike GMail, Outlook, etc. Because email systems normally use\nthe Simple Mail Transfer Protocol (SMTP), which is a web protocol\nthat supports only text data. So, if you need, for any reason, to\nsend a binary file (like for example, a PDF, or an Excel file) as\nan attachment in your email, these binary files are normally\nconverted to base64, before they are included in the SMTP message.\nSo, the base64 encoding is largely used in these email systems to include\nbinary data into the SMTP message.\n\n\n\n\n\n\n## How the base64 algorithm work?\n\nBut how exactly does the algorithm behind the base64 encoding work? Let's discuss that. First, I will\nexplain the base64 scale, which is the 64-character scale that is the basis for\nthe base64 encoding system.\n\nAfter that, I explain the algorithm behind a base64 encoder, which is the part of the algorithm that is responsible for encoding messages\ninto the base64 encoding system. Then, after that, I explain the algorithm behind a base64 decoder, which is\nthe part of the algorithm that is responsible for translating base64 messages back into their original meaning.\n\nIf you are unsure about the differences between an \"encoder\" and a \"decoder\",\ntake a look at @sec-encode-vs-decode.\n\n\n### The base64 scale {#sec-base64-scale}\n\nThe base64 encoding system is based on a scale that goes from 0 to 63 (hence the name).\nEach index in this scale is represented by a character (it's a scale of 64 characters).\nSo, in order to convert some binary data, to the base64 encoding, we need to convert each binary number to the corresponding\ncharacter in this \"scale of 64 characters\".\n\nThe base64 scale starts with all ASCII uppercase letters (A to Z) which represents\nthe first 25 indexes in this scale (0 to 25). After that, we have all ASCII lowercase letters\n(a to z), which represents the range 26 to 51 in the scale. After that, we\nhave the one digit numbers (0 to 9), which represents the indexes from 52 to 61 in the scale.\nFinally, the last two indexes in the scale (62 and 63) are represented by the characters `+` and `/`,\nrespectively.\n\nThese are the 64 characters that compose the base64 scale. The equal sign character (`=`) is not part of the scale itself,\nbut it is a special character in the base64 encoding system. This character is used solely as a suffix, to mark the end of the character sequence,\nor, to mark the end of meaningful characters in the sequence.\n\nThe bullet points below summarises the base64 scale:\n\n- range 0 to 25 is represented by: ASCII uppercase letters `-> [A-Z]`;\n- range 26 to 51 is represented by: ASCII lowercase letters `-> [a-z]`;\n- range 52 to 61 is represented by: one digit numbers `-> [0-9]`;\n- index 62 and 63 are represented by the characters `+` and `/`, respectively;\n- the character `=` represents the end of meaningful characters in the sequence;\n\n\n\n\n### Creating the scale as a lookup table {#sec-base64-table}\n\nThe best way to represent this scale in code, is to represent it as a *lookup table*.\nLookup tables are a classic strategy in computer science to speed up calculations. The basic idea\nis to replace a runtime calculation (which can take a long time to be done) with a basic array indexing\noperation.\n\nInstead of calculating the results everytime you need them, you calculate all possible results at once, and then, you store them in an array\n(which behaves like a \"table\"). Then, every time you need to use one of the characters in the base64 scale, instead of\nusing many resources to calculate the exact character to be used, you simply retrieve this character\nfrom the array where you stored all the possible characters in the base64 scale.\nWe retrieve the character that we need directly from memory.\n\nWe can start building a Zig struct to store our base64 decoder/encoder logic.\nWe start with the `Base64` struct below. For now, we only have one single data member in this\nstruct, i.e., the member `_table`, which represents our lookup table. We also have an `init()` method,\nto create a new instance of a `Base64` object, and, a `_char_at()` method, which is a\n\"get character at index $x$\" type of function.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst Base64 = struct {\n    _table: *const [64]u8,\n\n    pub fn init() Base64 {\n        const upper = \"ABCDEFGHIJKLMNOPQRSTUVWXYZ\";\n        const lower = \"abcdefghijklmnopqrstuvwxyz\";\n        const numbers_symb = \"0123456789+/\";\n        return Base64{\n            ._table = upper ++ lower ++ numbers_symb,\n        };\n    }\n\n    pub fn _char_at(self: Base64, index: usize) u8 {\n        return self._table[index];\n    }\n};\n```\n:::\n\n\n\nIn other words, the `_char_at()` method is responsible for getting the character in the lookup\ntable (i.e., the `_table` struct data member) that corresponds to a particular index in the\n\"base64 scale\". So, in the example below, we know that the character that corresponds to the\nindex 28 in the \"base64 scale\" is the character \"c\".\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst base64 = Base64.init();\ntry stdout.print(\n    \"Character at index 28: {c}\\n\",\n    .{base64._char_at(28)}\n);\n```\n:::\n\n\n```\nCharacter at index 28: c\n```\n\n\n\n### A base64 encoder {#sec-base64-encoder-algo}\n\nThe algorithm behind a base64 encoder usually works on a window of 3 bytes. Because each byte has\n8 bits, so, 3 bytes forms a set of $8 \\times 3 = 24$ bits. This is desirable for the base64 algorithm, because\n24 bits is divisible by 6, which forms $24 / 6 = 4$ groups of 6 bits each.\n\nTherefore, the base64 algorithm works by converting 3 bytes at a time\ninto 4 characters from the base64 scale. It keeps iterating through the input string,\n3 bytes at a time, and converting them into the base64 scale, producing 4 characters\nper iteration. It keeps iterating, and producing these \"new characters\"\nuntil it hits the end of the input string.\n\nNow you may think, what if you have a particular string that has a number of bytes\nthat is not divisible by 3 - what happens? For example, if you have a string\nthat contains only two characters/bytes, such as \"Hi\". How would the algorithm\nbehave in such situation? You find the answer in @fig-base64-algo1.\nYou can see in @fig-base64-algo1 that the string \"Hi\", when converted to base64,\nbecomes the string \"SGk=\":\n\n![The logic behind a base64 encoder](./../Figures/base64-encoder-flow.png){#fig-base64-algo1}\n\nTaking the string \"Hi\" as an example, we have 2 bytes, or, 16 bits in total. So, we lack a full byte (8 bits)\nto complete the window of 24 bits that the base64 algorithm likes to work on. The first thing that\nthe algorithm does, is to check how to divide the input bytes into groups of 6 bits.\n\nIf the algorithm notices that there is a group of 6 bits that it's not complete, meaning that, this group contains $nbits$, where $0 < nbits < 6$,\n\nthe algorithm simply adds extra zeros in this group to fill the space that it needs.\nThat is why in @fig-base64-algo1, in the third group after the 6-bit transformation,\n2 extra zeros were added to fill the gap.\n\nWhen we have a 6-bit group that is not completely full, like the third group, extra zeros\nare added to fill the gap. But what about when an entire 6-bit group is empty, or, it\nsimply doesn't exist? This is the case of the fourth 6-bit group exposed at\n@fig-base64-algo1.\n\nThis fourth group is necessary, because the algorithm works on 4 groups of 6 bits.\nBut the input string does not have enough bytes to create a fourth 6-bit group.\nEvery time this happens, where an entire group of 6 bits is empty,\nthis group becomes a \"padding group\". Every \"padding group\" is mapped to\nthe character `=` (equal sign), which represents \"null\", or, the end\nof meaningful characters in the sequence. Hence, everytime that the algorithm produces a\n\"padding group\", this group is automatically mapped to `=`.\n\nAs another example, if you give the string \"0\" as input to a base64 encoder, this string is\ntranslated into the base64 sequence \"MA==\".\nThe character \"0\" is, in binary, the sequence `00110000`[^zero-note]. So, with the 6-bit transformation\nexposed in @fig-base64-algo1, this single character would produce these two 6-bit groups: `001100`, `000000`.\nThe remaining two 6-bit groups become \"padding groups\". That is why the last\ntwo characters in the output sequence (MA==) are `==`.\n\n\n[^zero-note]: Notice that, the character \"0\" is different than the actual number 0, which is simply zero in binary.\n\n### A base64 decoder {#sec-base64-decoder-algo}\n\nThe algorithm behind a base64 decoder is essentially the inverse process of a base64 encoder.\nA base64 decoder needs to translate base64 messages back into their original meaning,\ni.e., into the original sequence of binary data.\n\nA base64 decoder usually works on a window of 4 bytes. Because it wants to convert these 4 bytes\nback into the original sequence of 3 bytes, that was converted into 4 groups of 6 bits by the\nbase64 encoder. Remember, in a base64 decoder we are essentially reverting the process made\nby the base64 encoder.\n\nEach byte in the input string (the base64 encoded string) normally contributes to re-create\ntwo different bytes in the output (the original binary data).\nIn other words, each byte that comes out of a base64 decoder is created by transforming merging two different\nbytes in the input together. You can visualize this relationship in @fig-base64-algo2:\n\n![The logic behind a base64 decoder](./../Figures/base64-decoder-flow.png){#fig-base64-algo2}\n\nThe exact transformations, or, the exact steps applied to each byte from the input to transform them\ninto the bytes of the output, are a bit tricky to visualize in a figure like this. Because of that, I have\nsummarized these transformations as \"Some bit shifting and additions ...\" in the figure. These transformations\nwill be described in depth later.\n\nBesides that, if you look again in @fig-base64-algo2, you will notice that the character `=` was completely\nignored by the algorithm. Remember, this is just a special character that marks the end of meaningful characters\nin the base64 sequence. So, every `=` character in a base64 encoded sequence should be ignored by a base64 decoder.\n\n\n## Difference between encode and decode {#sec-encode-vs-decode}\n\nIf you don't have any previous experience with base64, you might not understand the differences\nbetween \"encode\" and \"decode\". Essentially, the terms \"encode\" and \"decode\" here\nhave the exact same meaning as they have in the field of encryption (i.e., they mean the same thing as \"encode\" and \"decode\" in hashing\nalgorithms, like the MD5 algorithm).\n\nThus, \"encode\" means that we want to encode, or, in other words, we want to translate some message into\nthe base64 encoding system. We want to produce the sequence of base64 characters that represent this\noriginal message in the base64 encoding system.\n\nIn contrast, \"decode\" represents the inverse process.\nWe want to decode, or, in other words, translate a base64 message back to its original content.\nSo, in this process we get a sequence of base64 characters as input, and produce as output,\nthe binary data that is represented by this sequence of base64 characters.\n\nAny base64 library is normally composed of these two parts: 1) the encoder, which is a function that encodes\n(i.e., it converts) any sequence of binary data into a sequence of base64 characters; 2) the decoder, which is a function\nthat converts a sequence of base64 characters back into the original sequence of binary data.\n\n\n\n## Calculating the size of the output {#sec-base64-length-out}\n\nOne task that we need to do is to calculate how much space we need to reserve for the\noutput, both of the encoder and decoder. This is simple math, and can be done easily in Zig\nbecause every array has its length (its number of elements) easily accesible by consulting\nthe `.len` property of the array.\n\nFor the encoder, the logic is the following: for each 3 bytes that we find in the input,\n4 new bytes are created in the output. So, we take the number of bytes in the input, divide it\nby 3, use a ceiling function, then, we multiply the result by 4. That way, we get the total\nnumber of bytes that will be produced by the encoder in its output.\n\nThe `_calc_encode_length()` function below encapsulates this logic.\nInside this function, we take the length of the input array,\nwe divide it by 3, and apply a ceil operation over the result by using the\n`divCeil()` function from the Zig Standard Library. Lastly, we multiply\nthe end result by 4 to get the answer we need.\n\nAlso, you might have notice that, if the input length is less than 3 bytes, then, the output length of the encoder is\nalways 4 bytes. This is the case for every input with less than 3 bytes, because, as I described in @sec-base64-encoder-algo,\nthe algorithm always produces enough \"padding-groups\" in the end result, to complete the 4 bytes window.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_encode_length(input: []const u8) !usize {\n    if (input.len < 3) {\n        return 4;\n    }\n    const n_groups: usize = try std.math.divCeil(\n        usize, input.len, 3\n    );\n    return n_groups * 4;\n}\n```\n:::\n\n\n\nNow, the logic to calculate the length of the output from the decoder is a little bit more complicated. But, it is basically\njust the inverse logic that we've used for the encoder: for each 4 bytes in the input, 3 bytes\nwill be produced in the output of the decoder. However, this time we need to\ntake the `=` character into account, which is always ignored by the decoder, as we described in @sec-base64-decoder-algo, and,\nin @fig-base64-algo2.\n\nIn essence, we take the length of the input and divide it by 4, then we apply a floor function on the result, then\nwe multiply the result by 3, and then, we subtract from the result how much times the character `=` is found\nin the input.\n\nThe function `_calc_decode_length()` exposed below summarizes this logic that we described. It's similar\nto the function `_calc_encode_length()`. Notice that the division part is twisted. Also notice that this time, we apply\na floor operation over the output of the division, by using the `divFloor()`\nfunction (instead of a ceiling operation with `divCeil()`).\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nfn _calc_decode_length(input: []const u8) !usize {\n    if (input.len < 4) {\n        return 3;\n    }\n\n    const n_groups: usize = try std.math.divFloor(\n        usize, input.len, 4\n    );\n    var multiple_groups: usize = n_groups * 3;\n    var i: usize = input.len - 1;\n    while (i > 0) : (i -= 1) {\n        if (input[i] == '=') {\n            multiple_groups -= 1;\n        } else {\n            break;\n        }\n    }\n\n    return multiple_groups;\n}\n```\n:::\n\n\n\n## Building the encoder logic {#sec-encoder-logic}\n\nIn this section, we can start building the logic behind the `encode()` function, which\nwill be responsible for encoding messages into the base64 encoding system.\nIf you are an anxious person, and you want to see now the full source code of the implementation\nfor this base64 encoder/decoder, you can find it at the `ZigExamples` folder in the official repository of\nthis book[^zig-base64-algo].\n\n[^zig-base64-algo]: <https://github.com/pedropark99/zig-book/blob/main/ZigExamples/base64/base64_basic.zig>.\n\n\n\n### The 6-bit transformation {#sec-6bit-transf}\n\nThe 6-bit transformation presented in @fig-base64-algo1 is the core part of the base64 encoder algorithm.\nBy understanding how this transformation is made in code, the rest of the algorithm becomes much simpler\nto comprehend.\n\nIn essence, this 6-bit transformation is made with the help of bitwise operators.\nBitwise operators are essential to any type of low-level operation that is done at the bit-level. For the specific case of the base64 algorithm,\nthe operators *bif shift to the left* (`<<`), *bit shift to the right* (`>>`), and the *bitwise and* (`&`) are used. They\nare the core solution for the 6-bit transformation.\n\nThere are 3 different scenarios that we need to take into account in this transformation. First, is the perfect scenario,\nwhere we have the perfect window of 3 bytes to work on. Second, we have the scenario where we have a window of only\ntwo bytes to work with. And last, we have the scenario where we have a window of one single byte.\n\nIn each of these 3 scenarios, the 6-bit transformation works a bit differently. To make the explanation\neasier, I will use the variable `output` to refer to the bytes in the output of the base64 encoder,\nand the variable `input` to refer to the bytes in the input of the encoder.\n\n\nSo, if you have the perfect window of 3 bytes, these are steps for the 6-bit transformation:\n\n1. `output[0]` is produced by moving the bits from `input[0]` two positions to the right.\n1. `output[1]` is produced by summing two components. First, take the last two bits from `input[0]`, then, move them four positions to the left. Second, move the bits from `input[1]` four positions to the right. Sum these two components.\n1. `output[2]` is produced by summing two components. First, take the last four bits from `input[1]`, then, move them two positions to the left. Second, move the bits from `input[2]` six positions to the right. Sum these two components.\n1. `output[3]` is produced by taking the last six bits from `input[2]`.\n\n\nThis is the perfect scenario, where we have a full window of 3 bytes to work on.\nJust to make things as clear as possible, the @fig-encoder-bitshift demonstrates visually how\nthe step 2 mentioned above works. So the 2nd byte in the `output` of the encoder, is made by taking the 1st byte (dark purple)\nand the 2nd byte (orange) from the input. You can see that, at the end of the process, we get a new\nbyte that contains the last 2 bits from the 1st byte in the `input`, and the first 4 bits\nfrom the 2nd byte in the `input`.\n\n![How the 2nd byte in the output of the encoder is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input.](../Figures/base64-encoder-bit-shift.png){#fig-encoder-bitshift}\n\nOn the other hand, we must be prepared for the instances where we do not have the perfect window of 3 bytes.\nIf you have a window of 2 bytes, then, the steps 3 and 4, which produces the bytes `output[2]` and `output[3]`, change a little bit,\nand they become:\n\n- `output[2]` is produced by taking the last 4 bits from `input[1]`, then, move them two positions to the left.\n- `output[3]` is the character `'='`.\n\n\nFinally, if you have a window of a single byte, then, the steps 2 to 4, which produces the bytes `output[1]`, `output[2]` and `output[3]` change,\nbecoming:\n\n- `output[1]` is produced by taking the last two bits from `input[0]`, then, move them four positions to the left.\n- `output[2]` and `output[3]` are the character `=`.\n\n\nIf these bullet points were a bit confusing for you, you may find the @tbl-transf-6bit more intuitive.\nThis table unifies all this logic into a simple table. Notice that\nthis table also provides the exact expression in Zig that creates the corresponding\nbyte in the output.\n\n\n::: {#tbl-transf-6bit}\n\n| Number of bytes in the window | Byte index in the output | In code                                    |\n|-------------------------------|--------------------------|--------------------------------------------|\n| 3                             | 0                        | input[0] >> 2                              |\n| 3                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 3                             | 2                        | ((input[1] & 0x0f) << 2) + (input[2] >> 6) |\n| 3                             | 3                        | input[2] & 0x3f                            |\n| 2                             | 0                        | input[0] >> 2                              |\n| 2                             | 1                        | ((input[0] & 0x03) << 4) + (input[1] >> 4) |\n| 2                             | 2                        | ((input[1] & 0x0f) << 2)                   |\n| 2                             | 3                        | '='                                        |\n| 1                             | 0                        | input[0] >> 2                              |\n| 1                             | 1                        | ((input[0] & 0x03) << 4)                   |\n| 1                             | 2                        | '='                                        |\n| 1                             | 3                        | '='                                        |\n\n: How the 6-bit transformation translates into code in different window settings.\n\n:::\n\n\n\n\n\n\n### Bit-shifting in Zig\n\nBit-shifting in Zig works similarly to bit-shifting in C.\nAll bitwise operators that exist in C are available in Zig.\nHere, in the base64 encoder algorithm, they are essential\nto produce the result we want.\n\nFor those who are not familiar with these operators, they are\noperators that operates at the bit-level of your values.\nThis means that these operators takes the bits that form the value\nyou have, and change them in some way. This ultimately also changes\nthe value itself, because the binary representation of this value\nchanges.\n\nWe have already seen in @fig-encoder-bitshift the effect produced by a bit-shift.\nBut let's use the first byte in the output of the base64 encoder as another example of what\nbit-shifting means. This is the easiest byte of the 4 bytes in the output\nto build. Because we only need to move the bits from the first byte in the input two positions to the right,\nwith the *bit shift to the right* (`>>`) operator.\n\nIf we take the string \"Hi\" that we used in @fig-base64-algo1 as an example, the first byte in\nthis string is \"H\", which is the sequence `01001000` in binary.\nIf we move the bits of this byte, two places to the right, we get the sequence `00010010` as result.\nThis binary sequence is the value `18` in decimal, and also, the value `0x12` in hexadecimal.\nNotice that the first 6 bits of \"H\" were moved to the end of the byte.\nWith this operation, we get the first byte of the output.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const input = \"Hi\";\n    try stdout.print(\"{d}\\n\", .{input[0] >> 2});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n18\n```\n\n\n:::\n:::\n\n\nIf you recall @fig-base64-algo1, the first byte present in the output should\nbe equivalent to the 6-bit group `010010`. Although being visually different, the\nsequences `010010` and `00010010` are semantically equal. They mean the same thing.\nThey both represent the number 18 in decimal, and the value `0x12` in hexadecimal.\n\nSo, don't take the \"6-bit group\" factor so seriously. We do not need necessarily to\nget a 6-bit sequence as result. As long as the meaning of the 8-bit sequence we get is the same\nof the 6-bit sequence, we are in the clear.\n\n\n\n### Selecting specific bits with the `&` operator\n\nIf you comeback to @sec-6bit-transf, you will see that, in order to produce\nthe second and third bytes in the output, we need to select specific\nbits from the first and second bytes in the input string. But how\ncan we do that? The answer relies on the *bitwise and* (`&`) operator.\n\nThe @fig-encoder-bitshift already showed you what effect this `&` operator\nproduces in the bits of its operands. But let's make a clear description of it.\n\nIn summary, the `&` operator performs a logical conjunction operation\nbetween the bits of its operands. In more details, the operator `&`\ncompares each bit of the first operand to the corresponding bit of the second operand.\nIf both bits are 1, the corresponding result bit is set to 1.\nOtherwise, the corresponding result bit is set to 0 [@microsoftbitwiseand].\n\nSo, if we apply this operator to the binary sequences `1000100` and `00001101`\nthe result of this operation is the binary sequence `00000100`. Because only\nat the sixth position in both binary sequences we had a 1 value. So any\nposition where we do not have both binary sequences setted to 1, we get\na 0 bit in the resulting binary sequence.\n\nWe lose information about the original bit values\nfrom both sequences in this case. Because we no longer know\nif this 0 bit in the resulting binary sequence was produced by\ncombining 0 with 0, or 1 with 0, or 0 with 1.\n\nAs an example, suppose you have the binary sequence `10010111`, which is the number 151 in decimal. How\ncan we get a new binary sequence which contains only the third and\nfourth bits of this sequence?\n\nWe just need to combine this sequence with `00110000` (is `0x30` in hexadecimal) using the `&` operator.\nNotice that only the third and fourth positions in this binary sequence is setted to 1. As a consequence, only the\nthird and fourth values of both binary sequences are potentially preserved in the output. All the remaining positions\nare setted to zero in the output sequence, which is `00010000` (is the number 16 in decimal).\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nconst std = @import(\"std\");\nconst stdout = std.io.getStdOut().writer();\npub fn main() !void {\n    const bits = 0b10010111;\n    try stdout.print(\"{d}\\n\", .{bits & 0b00110000});\n}\n```\n\n\n::: {.cell-output .cell-output-stdout}\n\n```\n16\n```\n\n\n:::\n:::\n\n\n\n\n### Allocating space for the output\n\nAs I described in @sec-stack, to store an object in the stack,\nthis object needs to have a known and fixed length at compile-time. This is an important\nlimitation for our base64 encoder/decoder case. Because the size of\nthe output (from both the encoder and decoder) depends\ndirectly on the size of the input.\n\nHaving this in mind, we cannot know at compile time which is\nthe size of the output for both the encoder and decoder.\nSo, if we can't know the size of the output at compile time,\nthis means that we cannot store the output for both the encoder\nand decoder in the stack.\n\nConsequently, we need to store this output on the heap,\nand, as I commented in @sec-heap, we can only\nstore objects in the heap by using allocator objects.\nSo, one the arguments to both the `encode()` and `decode()`\nfunctions, needs to be an allocator object, because\nwe know for sure that, at some point inside the body of these\nfunctions, we need to allocate space on the heap to\nstore the output of these functions.\n\nThat is why, both the `encode()` and `decode()` functions that I\npresent in this book, have an argument called `allocator`,\nwhich receives a allocator object as input, identified by\nthe type `std.mem.Allocator` from the Zig Standard Library.\n\n\n\n### Writing the `encode()` function\n\nNow that we have a basic understanding on how the bitwise operators work, and how\nexactly they help us to achieve the result we want to achieve. We can now encapsulate\nall the logic that we have described in @fig-base64-algo1 and @tbl-transf-6bit into a nice\nfunction that we can add to our `Base64` struct definition, that we started in @sec-base64-table.\n\nYou can find the `encode()` function below. Notice that the first argument of this function,\nis the `Base64` struct itself. Therefore, this argument clearly signals\nthat this function is a method from the `Base64` struct.\n\nBecause the `encode()` function itself is fairly long,\nI intentionally omitted the `Base64` struct definition in this source code,\njust for brevity reasons. So, just remember that this function is a public function (or a public method) from the\n`Base64` struct.\n\nFurthermore, this `encode()` function has two other arguments:\n\n1. `input` is the input sequence of characters that you want to encode in base64;\n1. `allocator` is an allocator object to use in the necessary memory allocations.\n\nI described everything you need to know about allocator objects in @sec-allocators.\nSo, if you are not familiar with them, I highly recommend you to comeback to\nthat section, and read it.\nBy looking at the `encode()` function, you will see that we use this\nallocator object to allocate enough memory to store the output of\nthe encoding process.\n\nThe main for loop in the function is responsible for iterating through the entire input string.\nIn every iteration, we use a `count` variable to count how many iterations we had at the\nmoment. When `count` reaches 3, then, we try to encode the 3 characters (or bytes) that we have accumulated\nin the temporary buffer object (`buf`).\n\nAfter encoding these 3 characters and storing the result in the `output` variable, we reset\nthe `count` variable to zero, and start to count again on the next iteration of the loop.\nIf the loop hits the end of the string, and, the `count` variable is less than 3, then, it means that\nthe temporary buffer contains the last 1 or 2 bytes from the input.\nThat is why we have two `if` statements after the for loop. To deal which each possible case.\n\n\n\n::: {.cell}\n\n```{.zig .cell-code}\npub fn encode(self: Base64,\n              allocator: std.mem.Allocator,\n              input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n\n    const n_out = try _calc_encode_length(input);\n    var out = try allocator.alloc(u8, n_out);\n    var buf = [3]u8{ 0, 0, 0 };\n    var count: u8 = 0;\n    var iout: u64 = 0;\n\n    for (input, 0..) |_, i| {\n        buf[count] = input[i];\n        count += 1;\n        if (count == 3) {\n            out[iout] = self._char_at(buf[0] >> 2);\n            out[iout + 1] = self._char_at(\n                ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n            );\n            out[iout + 2] = self._char_at(\n                ((buf[1] & 0x0f) << 2) + (buf[2] >> 6)\n            );\n            out[iout + 3] = self._char_at(buf[2] & 0x3f);\n            iout += 4;\n            count = 0;\n        }\n    }\n\n    if (count == 1) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            (buf[0] & 0x03) << 4\n        );\n        out[iout + 2] = '=';\n        out[iout + 3] = '=';\n    }\n\n    if (count == 2) {\n        out[iout] = self._char_at(buf[0] >> 2);\n        out[iout + 1] = self._char_at(\n            ((buf[0] & 0x03) << 4) + (buf[1] >> 4)\n        );\n        out[iout + 2] = self._char_at(\n            (buf[1] & 0x0f) << 2\n        );\n        out[iout + 3] = '=';\n        iout += 4;\n    }\n\n    return out;\n}\n```\n:::\n\n\n\n\n## Building the decoder logic {#sec-decoder-logic}\n\nNow, we can focus on writing the base64 decoder logic. Remember from @fig-base64-algo2 that,\na base64 decoder does the inverse process of an encoder. So, all we need to do, is to\nwrite a `decode()` function that performs the inverse process that I exposed in @sec-encoder-logic.\n\n\n### Mapping base64 characters to their indexes {#sec-map-base64-index}\n\nOne thing that we need to do, in order to decode a base64-encoded message, is to calculate\nthe index in the base64 scale of every base64 character that we encounter in the decoder input.\n\nIn other words, the decoder receives as input, a sequence of base64 characters. We need\nto translate this sequence of characters into a sequence of indexes. These indexes\nare the index of each character in the base64 scale. This way, we get the value/byte\nthat was calculated in the 6-bit transformation step of the encoder process.\n\nThere are probably better/faster ways to calculate this, especially using a \"divide and conquer\"\ntype of strategy. But for now, I am satisfied with a simple and \"brute force\" type of strategy.\nThe `_char_index()` function below contains this strategy.\n\nWe are essentially looping through the *lookup table* with the base64 scale,\nand comparing the character we got with each character in the base64 scale.\nIf these characters match, then, we return the index of this character in the\nbase64 scale as the result.\n\nNotice that, if the input character is `'='`, the function returns the index 64, which is\n\"out of range\" in the scale. But, as I described in @sec-base64-scale,\nthe character `'='` does not belong to the base64 scale itself.\nIt's a special and meaningless character in base64.\n\nAlso notice that this `_char_index()` function is a method from our `Base64` struct,\nbecause of the `self` argument. Again, I have omitted the `Base64` struct definition in this example\nfor brevity reasons.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn _char_index(self: Base64, char: u8) u8 {\n    if (char == '=')\n        return 64;\n    var index: u8 = 0;\n    for (0..63) |i| {\n        if (self._char_at(i) == char)\n            break;\n        index += 1;\n    }\n\n    return index;\n}\n```\n:::\n\n\n\n\n### The 6-bit transformation\n\nOnce again, the core part of the algorithm is the 6-bit transformation.\nIf we understand the necessary steps to perform this transformation, the rest\nof the algorithm becomes much easier.\n\nFirst of all, before we actually go to the 6-bit transformation,\nwe need to make sure that we use `_char_index()` to convert the sequence of base64 characters\ninto a sequence of indexes. So the snippet below is important for the job that will be done.\nThe result of `_char_index()` is stored in a temporary buffer, and this temporary buffer\nis what we are going to use in the 6-bit transformation, instead of the actual `input` object.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfor (0..input.len) |i| {\n    buf[i] = self._char_index(input[i]);\n}\n```\n:::\n\n\nNow, instead of producing 4 bytes (or 4 characters) as output per each window of 3 characters in the input,\na base64 decoder produces 3 bytes (or 3 characters) as output per each window of 4 characters in the input.\nOnce again, is the inverse process.\n\nSo, the steps to produce the 3 bytes in the output are:\n\n1. `output[0]` is produced by summing two components. First, move the bits from `buf[0]` two positions to the left. Second, move the bits from `buf[1]` 4 positions to the right. Then, sum these two components.\n1. `output[1]` is produced by summing two components. First, move the bits from `buf[1]` four positions to the left. Second, move the bits from `buf[2]` 2 positions to the right. Then, sum these two components.\n1. `output[2]` is produced by summing two components. First, move the bits from `buf[2]` six positions to the left. Then, you sum the result with `buf[3]`.\n\n\nBefore we continue, let's try to visualize how these transformations make the original bytes that we had\nbefore the encoding process. First, think back to the 6-bit transformation performed by the encoder exposed in @sec-encoder-logic.\nThe first byte in the output of the encoder is produced by moving the bits in the first byte of the input two positions to the right.\n\nIf for example the first byte in the input of the encoder was the sequence `ABCDEFGH`, then, the first byte in the output of the encoder would be\n`00ABCDEF` (this sequence would be the first byte in the input of the decoder). Now, if the second byte in the input of the encoder was the sequence\n`IJKLMNOP`, then, the second byte in the encoder output would be `00GHIJKL` (as we demonstrated in @fig-encoder-bitshift).\n\nHence, if the sequences `00ABCDEF` and `00GHIJKL` are the first and second bytes, respectively, in the input of the decoder, the\n@fig-decoder-bitshift demonstrates visually how these two bytes are transformed into the first byte of the output of the decoder.\nNotice that the output byte is the sequence `ABCDEFGH`, which is the original byte from the input of the encoder.\n\n![How the 1st byte in the decoder output is produced from the 1st byte (dark purple) and the 2nd byte (orange) of the input](../Figures/base64-decoder-bit-shift.png){#fig-decoder-bitshift}\n\nThe @tbl-6bit-decode presents how the three steps described earlier translate into Zig code:\n\n\n\n::: {#tbl-6bit-decode}\n\n| Byte index in the output | In code                       |\n|--------------------------|-------------------------------|\n| 0                        | (buf[0] << 2) + (buf[1] >> 4) |\n| 1                        | (buf[1] << 4) + (buf[2] >> 2) |\n| 2                        | (buf[2] << 6) + buf[3]        |\n\n: The necessary steps for the 6-transformation in the decode process.\n\n\n:::\n\n\n\n\n\n\n\n### Writing the `decode()` function\n\nThe `decode()` function below contains the entire decoding process.\nWe first calculate the size of the output, with\n`_calc_decode_length()`, then, we allocate enough memory for this output with\nthe allocator object.\n\nThree temporary variables are created: 1) `count`, to hold the window count\nin each iteration of the for loop; 2) `iout`, to hold the current index in the output;\n3) `buf`, which is the temporary buffer that holds the base64 indexes to be\nconverted through the 6-bit transformation.\n\nThen, in each iteration of the for loop we fill the temporary buffer with the current\nwindow of bytes. When `count` hits the number 4, then, we have a full window of\nindexes in `buf` to be converted, and then, we apply the 6-bit transformation\nover the temporary buffer.\n\nNotice that we check if the indexes 2 and 3 in the temporary buffer are the number 64, which, if you recall\nfrom @sec-map-base64-index, is when the `_calc_index()` function receives a `'='` character\nas input. So, if these indexes are equal to the number 64, the `decode()` function knows\nthat it can simply ignore these indexes. They are not converted because, as I described before,\nthe character `'='` has no meaning, despite being the end of meaningful characters in the sequence.\nSo we can safely ignore them when they appear in the sequence.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nfn decode(self: Base64,\n          allocator: std.mem.Allocator,\n          input: []const u8) ![]u8 {\n\n    if (input.len == 0) {\n        return \"\";\n    }\n    const n_output = try _calc_decode_length(input);\n    var output = try allocator.alloc(u8, n_output);\n    var count: u8 = 0;\n    var iout: u64 = 0;\n    var buf = [4]u8{ 0, 0, 0, 0 };\n\n    for (0..input.len) |i| {\n        buf[count] = self._char_index(input[i]);\n        count += 1;\n        if (count == 4) {\n            output[iout] = (buf[0] << 2) + (buf[1] >> 4);\n            if (buf[2] != 64) {\n                output[iout + 1] = (buf[1] << 4) + (buf[2] >> 2);\n            }\n            if (buf[3] != 64) {\n                output[iout + 2] = (buf[2] << 6) + buf[3];\n            }\n            iout += 3;\n            count = 0;\n        }\n    }\n\n    return output;\n}\n```\n:::\n\n\n\n## The end result\n\nNow that we have both `decode()` and `encode()` implemented. We have a fully functioning\nbase64 encoder/decoder implemented in Zig. Here is an usage example of our\n`Base64` struct with the `encode()` and `decode()` methods that we have implemented.\n\n\n::: {.cell}\n\n```{.zig .cell-code}\nvar memory_buffer: [1000]u8 = undefined;\nvar fba = std.heap.FixedBufferAllocator.init(\n    &memory_buffer\n);\nconst allocator = fba.allocator();\n\nconst text = \"Testing some more stuff\";\nconst etext = \"VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=\";\nconst base64 = Base64.init();\nconst encoded_text = try base64.encode(\n    allocator, text\n);\nconst decoded_text = try base64.decode(\n    allocator, etext\n);\ntry stdout.print(\n    \"Encoded text: {s}\\n\", .{encoded_text}\n);\ntry stdout.print(\n    \"Decoded text: {s}\\n\", .{decoded_text}\n);\n```\n:::\n\n\n```\nEncoded text: VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=\nDecoded text: Testing some more stuff\n```\n\nYou can also see the full source code at once, by visiting the official repository of this book[^repo].\nMore precisely inside the `ZigExamples` folder[^zig-base64-algo].\n\n[^repo]: <https://github.com/pedropark99/zig-book>\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
diff --git a/docs/Chapters/01-base64.html b/docs/Chapters/01-base64.html
index 4fa946ca..e04a03b7 100644
--- a/docs/Chapters/01-base64.html
+++ b/docs/Chapters/01-base64.html
@@ -400,7 +400,7 @@ <h3 data-number="4.1.1" class="anchored" data-anchor-id="sec-base64-scale"><span
 <section id="sec-base64-table" class="level3" data-number="4.1.2">
 <h3 data-number="4.1.2" class="anchored" data-anchor-id="sec-base64-table"><span class="header-section-number">4.1.2</span> Creating the scale as a lookup table</h3>
 <p>The best way to represent this scale in code, is to represent it as a <em>lookup table</em>. Lookup tables are a classic strategy in computer science to speed up calculations. The basic idea is to replace a runtime calculation (which can take a long time to be done) with a basic array indexing operation.</p>
-<p>Instead of calculating the results everytime you need them, you calculate all possible results at once, and then, you store them in an array (which behaves lake a “table”). Then, every time you need to use one of the characters in the base64 scale, instead of using many resources to calculate the exact character to be used, you simply retrieve this character from the array where you stored all the possible characters in the base64 scale. We retrieve the character that we need directly from memory.</p>
+<p>Instead of calculating the results everytime you need them, you calculate all possible results at once, and then, you store them in an array (which behaves like a “table”). Then, every time you need to use one of the characters in the base64 scale, instead of using many resources to calculate the exact character to be used, you simply retrieve this character from the array where you stored all the possible characters in the base64 scale. We retrieve the character that we need directly from memory.</p>
 <p>We can start building a Zig struct to store our base64 decoder/encoder logic. We start with the <code>Base64</code> struct below. For now, we only have one single data member in this struct, i.e., the member <code>_table</code>, which represents our lookup table. We also have an <code>init()</code> method, to create a new instance of a <code>Base64</code> object, and, a <code>_char_at()</code> method, which is a “get character at index <span class="math inline">\(x\)</span>” type of function.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb1"><pre class="sourceCode zig code-with-copy"><code class="sourceCode zig"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> Base64 = <span class="kw">struct</span> <span class="op">{</span></span>
diff --git a/docs/Chapters/01-memory.html b/docs/Chapters/01-memory.html
index ae5388b5..db55654d 100644
--- a/docs/Chapters/01-memory.html
+++ b/docs/Chapters/01-memory.html
@@ -392,7 +392,7 @@ <h3 data-number="3.1.2" class="anchored" data-anchor-id="global-data-register"><
 <section id="stack-vs-heap" class="level3" data-number="3.1.3">
 <h3 data-number="3.1.3" class="anchored" data-anchor-id="stack-vs-heap"><span class="header-section-number">3.1.3</span> Stack vs Heap</h3>
 <p>If you are familiar with systems programming, or just low-level programming in general, you probably have heard of the “duel” between Stack vs Heap. These are two different types of memory, or different memory spaces, which are both available in Zig.</p>
-<p>These two types of memory don’t actually duel with each other. This is a common mistake that beginners have, when seeing “x vs y” styles of tabloid headlines. These two types of memory are actually complementary to each other. So, in almost every Zig program that you ever write, you will likely use a combination of both. I will describe each memory space in detail over the next sections. But for now, I just want to stablish the main difference between these two types of memory.</p>
+<p>These two types of memory don’t actually duel with each other. This is a common mistake that beginners have, when seeing “x vs y” styles of tabloid headlines. These two types of memory are actually complementary to each other. So, in almost every Zig program that you ever write, you will likely use a combination of both. I will describe each memory space in detail over the next sections. But for now, I just want to establish the main difference between these two types of memory.</p>
 <p>In essence, the stack memory is normally used to store values whose length is fixed and known at compile time. In contrast, the heap memory is a <em>dynamic</em> type of memory space, meaning that, it’s used to store values whose length might grow during the execution (runtime) of your program <span class="citation" data-cites="jenny2022">(<a href="../references.html#ref-jenny2022" role="doc-biblioref">Chen and Guo 2022</a>)</span>.</p>
 <p>Lengths that grow during runtime are intrinsically associated with “runtime known” type of values. In other words, if you have an object whose length might grow during runtime, then, the length of this object becomes not known at compile time. If the length is not known at compile-time, the value of this object also becomes not known at compile-time. These types of objects should be stored in the heap memory space, which is a dynamic memory space, which can grow or shrink to fit the size of your objects.</p>
 </section>
diff --git a/docs/search.json b/docs/search.json
index 887f9d22..695b7bc8 100644
--- a/docs/search.json
+++ b/docs/search.json
@@ -314,7 +314,7 @@
     "href": "Chapters/01-memory.html#memory-spaces",
     "title": "3  Memory and Allocators",
     "section": "",
-    "text": "Global data register (or the “global data section”);\nStack;\nHeap;\n\n\n3.1.1 Compile-time known versus runtime known\nOne strategy that Zig uses to decide where it will store each object that you declare, is by looking at the value of this particular object. More specifically, by investigating if this value is known at “compile-time” or at “runtime”.\nWhen you write a program in Zig, the values of some of the objects that you write in your program are known at compile time. Meaning that, when you compile your Zig source code, during the compilation process, the zig compiler can figure out the exact value of a particular object that exists in your source code. Knowing the length (or the size) of each object is also important. So the length (or the size) of each object that you write in your program is, in some cases, known at compile time.\nThe zig compiler cares more about knowing the length (or the size) of a particular object , than to know its actual value. But, if the zig compiler knows the value of the object, then, it automatically knows the size of this object. Because it can simply calculate the size of the object by looking at the size of the value.\nTherefore, the priority for the zig compiler is to discover the size of each object in your source code. If the value of the object in question is known at compile-time, then, the zig compiler automatically knows the size/length of this object. But if the value of this object is not known at compile-time, then, the size of this object is only known at compile-time if, and only if, the type of this object has a known fixed size.\nIn order for a type to have a known fixed size, this type must have data members whose size is fixed. If this type includes, for example, a variable sized array in it, then, this type does not have a known fixed size. Because this array can have any size at runtime (i.e., it can be an array of 2 elements, or 50 elements, or 1 thousand elements, etc.).\nFor example, a string object, which internally is an array of constant u8 values ([]const u8) has a variable size. It can be a string object with 100 or 500 characters in it. If we do not know at compile-time, which exact string will be stored inside this string object, then, we cannot calculate the size of this string object at compile-time. So, any type, or any struct declaration that you make, that includes a string data member that does not have an explicit fixed size, makes this type, or this new struct that you are declaring, a type that does not have a known fixed size at compile-time.\nIn contrast, if the type of this struct that you are declaring, includes a data member that is an array, but this array has a known fixed size, like [60]u8 (which declares an array of 60 u8 values), then, this type, or, this struct that you are declaring, becomes a type with a known fixed size at compile-time. And because of that, in this case, the zig compiler does not need to know at compile-time the exact value of any object of this type. Since the compiler can find the necessary size to store this object by looking at the size of its type.\nLet’s look at an example. In the source code below, we have two constant objects (name and array) declared. Because the values of these particular objects are written down, in the source code itself (\"Pedro\" and the number sequence from 1 to 4), the zig compiler can easily discover the values of these constant objects (name and array) during the compilation process. This is what “known at compile time” means. It refers to any object that you have in your Zig source code whose value can be identified at compile time.\n\nfn input_length(input: []const u8) usize {\n    const n = input.len;\n    return n;\n}\n\npub fn main() !void {\n    const name = \"Pedro\";\n    const array = [_]u8{1, 2, 3, 4};\n    _ = name; _ = array;\n}\n\nThe other side of the spectrum are objects whose values are not known at compile time. Function arguments are a classic example of this. Because the value of each function argument depends on the value that you assign to this particular argument, when you call the function.\nFor example, the function input_length() contains an argument named input, which is an array of constant u8 integers ([]const u8). It’s impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length of this particular argument. Because it’s an array that does not have a fixed size specified explicitly in the argument type annotation.\nSo, we know that this input argument will be an array of u8 integers. But we do not know at compile-time, its value, and neither its size. This information is known only at runtime, which is the period of time when you program is executed. As a consequence, the value of the expression input.len is also known only at runtime. This is an intrinsic characteristic of any function. Just remember that the value of function arguments is usually not “compile-time known”.\nHowever, as I mentioned earlier, what really matters to the compiler is to know the size of the object at compile-time, and not necessarily its value. So, although we don’t know the value of the object n, which is the result of the expression input.len, at compile-time, we do know its size. Because the expression input.len always returns a value of type usize, and the type usize has a known fixed size.\n\n\n3.1.2 Global data register\nThe global data register is a specific section of the executable of your Zig program, that is responsible for storing any value that is known at compile time.\nEvery constant object whose value is known at compile time that you declare in your source code, is stored in the global data register. Also, every literal value that you write in your source code, such as the string \"this is a string\", or the integer 10, or a boolean value such as true, is also stored in the global data register.\nHonestly, you don’t need to care much about this memory space. Because you can’t control it, you can’t deliberately access it or use it for your own purposes. Also, this memory space does not affect the logic of your program. It simply exists in your program.\n\n\n3.1.3 Stack vs Heap\nIf you are familiar with systems programming, or just low-level programming in general, you probably have heard of the “duel” between Stack vs Heap. These are two different types of memory, or different memory spaces, which are both available in Zig.\nThese two types of memory don’t actually duel with each other. This is a common mistake that beginners have, when seeing “x vs y” styles of tabloid headlines. These two types of memory are actually complementary to each other. So, in almost every Zig program that you ever write, you will likely use a combination of both. I will describe each memory space in detail over the next sections. But for now, I just want to stablish the main difference between these two types of memory.\nIn essence, the stack memory is normally used to store values whose length is fixed and known at compile time. In contrast, the heap memory is a dynamic type of memory space, meaning that, it’s used to store values whose length might grow during the execution (runtime) of your program (Chen and Guo 2022).\nLengths that grow during runtime are intrinsically associated with “runtime known” type of values. In other words, if you have an object whose length might grow during runtime, then, the length of this object becomes not known at compile time. If the length is not known at compile-time, the value of this object also becomes not known at compile-time. These types of objects should be stored in the heap memory space, which is a dynamic memory space, which can grow or shrink to fit the size of your objects.\n\n\n3.1.4 Stack\nThe stack is a type of memory that uses the power of the stack data structure, hence the name. A “stack” is a type of data structure that uses a “last in, first out” (LIFO) mechanism to store the values you give it to. I imagine you are familiar with this data structure. But, if you are not, the Wikipedia page1 , or, the Geeks For Geeks page2 are both excellent and easy resources to fully understand how this data structure works.\nSo, the stack memory space is a type of memory that stores values using a stack data structure. It adds and removes values from the memory by following a “last in, first out” (LIFO) principle.\nEvery time you make a function call in Zig, an amount of space in the stack is reserved for this particular function call (Chen and Guo 2022; Zig Software Foundation 2024). The value of each function argument given to the function in this function call is stored in this stack space. Also, every local object that you declare inside the function scope is usually stored in this same stack space.\nLooking at the example below, the object result is a local object declared inside the scope of the add() function. Because of that, this object is stored inside the stack space reserved for the add() function. The r object (which is declared outside of the add() function scope) is also stored in the stack. But since it’s declared in the “outer” scope, this object is stored in the stack space that belongs to this outer scope.\n\nfn add(x: u8, y: u8) u8 {\n    const result = x + y;\n    return result;\n}\n\npub fn main() !void {\n    const r = add(5, 27);\n    _ = r;\n}\n\nSo, any object that you declare inside the scope of a function is always stored inside the space that was reserved for that particular function in the stack memory. This also counts for any object declared inside the scope of your main() function for example. As you would expect, in this case, they are stored inside the stack space reserved for the main() function.\nOne very important detail about the stack memory is that it frees itself automatically. This is very important, remember that. When objects are stored in the stack memory, you don’t have the work (or the responsibility) of freeing/destroying these objects. Because they will be automatically destroyed once the stack space is freed at the end of the function scope.\nSo, once the function call returns (or ends, if you prefer to call it this way) the space that was reserved in the stack is destroyed, and all of the objects that were in that space goes away with it. This mechanism exists because this space, and the objects within it, are not necessary anymore, since the function “finished its business”. Using the add() function that we exposed above as an example, it means that the object result is automatically destroyed once the function returns.\n\n\n\n\n\n\nImportant\n\n\n\nLocal objects that are stored in the stack space of a function are automatically freed/destroyed at the end of the function scope.\n\n\nThis same logic applies to any other special structure in Zig that has its own scope by surrounding it with curly braces ({}). For loops, while loops, if else statements, etc. For example, if you declare any local object in the scope of a for loop, this local object is accessible only within the scope of this particular for loop. Because once the scope of this for loop ends, the space in the stack reserved for this for loop is freed. The example below demonstrates this idea.\n\n// This does not compile successfully!\nconst a = [_]u8{0, 1, 2, 3, 4};\nfor (0..a.len) |i| {\n    const index = i;\n    _ = index;\n}\n// Trying to use an object that was\n// declared in the for loop scope,\n// and that does not exist anymore.\nstd.debug.print(\"{d}\\n\", .{index});\n\nOne important consequence of this mechanism is that, once the function returns, you can no longer access any memory address that was inside the space in the stack reserved for this particular function. Because this space was destroyed. This means that, if this local object is stored in the stack, you cannot make a function that returns a pointer to this object.\nThink about that for a second. If all local objects in the stack are destroyed at the end of the function scope, why would you even consider returning a pointer to one of these objects? This pointer is at best, invalid, or, more likely, “undefined”.\nIn conclusion, it’s totally fine to write a function that returns the local object itself as result, because then, you return the value of that object as the result. But, if this local object is stored in the stack, you should never write a function that returns a pointer to this local object. Because the memory address pointed by the pointer no longer exists.\nSo, using again the add() function as an example, if you rewrite this function so that it returns a pointer to the local object result, the zig compiler will actually compile your program, with no warnings or errors. At first glance, it looks like this is good code that works as expected. But this is a lie!\nIf you try to take a look at the value inside of the r object, or, if you try to use this r object in another expression or function call, then, you would have undefined behaviour, and major bugs in your program (Zig Software Foundation 2024, see “Lifetime and Ownership”3 and “Undefined Behaviour”4 sections).\n\nfn add(x: u8, y: u8) *const u8 {\n    const result = x + y;\n    return &result;\n}\n\npub fn main() !void {\n    // This code compiles successfully. But it has\n    // undefined behaviour. Never do this!!!\n    // The `r` object is undefined!\n    const r = add(5, 27); _ = r;\n}\n\nThis “invalid pointer to stack variable” problem is well known across many programming language communities. If you try to do the same thing, for example, in a C or C++ program (i.e., returning an address to a local object stored in the stack), you would also get undefined behaviour in the program.\n\n\n\n\n\n\nImportant\n\n\n\nIf a local object in your function is stored in the stack, you should never return a pointer to this local object from the function. Because this pointer will always become undefined after the function returns, since the stack space of the function is destroyed at the end of its scope.\n\n\nBut what if you really need to use this local object in some way after your function returns? How can you do this? The answer is: “in the same way you would do if this were a C or C++ program. By returning an address to an object stored in the heap”. The heap memory has a much more flexible lifecycle, and allows you to get a valid pointer to a local object of a function that already returned from its scope.\n\n\n3.1.5 Heap\nOne important limitation of the stack, is that, only objects whose length/size is known at compile-time can be stored in it. In contrast, the heap is a much more dynamic (and flexible) type of memory. It’s the perfect type of memory to use for objects whose size/length might grow during the execution of your program.\nVirtually any application that behaves as a server is a classic use case of the heap. A HTTP server, a SSH server, a DNS server, a LSP server, … any type of server. In summary, a server is a type of application that runs for long periods of time, and that serves (or “deals with”) any incoming request that reaches this particular server.\nThe heap is a good choice for this type of system, mainly because the server does not know upfront how many requests it will receive from users, while it is active. It could be a single request, 5 thousand requests, or even zero requests. The server needs to have the ability to allocate and manage its memory according to how many requests it receives.\nAnother key difference between the stack and the heap, is that the heap is a type of memory that you, the programmer, have complete control over. This makes the heap a more flexible type of memory, but it also makes it harder to work with. Because you, the programmer, is responsible for managing everything related to it. Including where the memory is allocated, how much memory is allocated, and where this memory is freed.\n\nUnlike stack memory, heap memory is allocated explicitly by programmers and it won’t be deallocated until it is explicitly freed (Chen and Guo 2022).\n\nTo store an object in the heap, you, the programmer, needs to explicitly tells Zig to do so, by using an allocator to allocate some space in the heap. In Section 3.3, I will present how you can use allocators to allocate memory in Zig.\n\n\n\n\n\n\nImportant\n\n\n\nEvery memory you allocate in the heap needs to be explicitly freed by you, the programmer.\n\n\nThe majority of allocators in Zig do allocate memory on the heap. But some exceptions to this rule are ArenaAllocator() and FixedBufferAllocator(). The ArenaAllocator() is a special type of allocator that works in conjunction with a second type of allocator. On the other side, the FixedBufferAllocator() is an allocator that works based on buffer objects created on the stack. This means that the FixedBufferAllocator() makes allocations only on the stack.\n\n\n3.1.6 Summary\nAfter discussing all of these boring details, we can quickly recap what we learned. In summary, the Zig compiler will use the following rules to decide where each object you declare is stored:\n\nevery literal value (such as \"this is string\", 10, or true) is stored in the global data section.\nevery constant object (const) whose value is known at compile-time is also stored in the global data section.\nevery object (constant or not) whose length/size is known at compile time is stored in the stack space for the current scope.\nif an object is created with the method alloc() or create() of an allocator object, this object is stored in the memory space used by this particular allocator object. Most of allocators available in Zig use the heap memory, so, this object is likely stored in the heap (FixedBufferAllocator() is an exception to that).\nthe heap can only be accessed through allocators. If your object was not created through the alloc() or create() methods of an allocator object, then, it is most certainly not an object stored in the heap.",
+    "text": "Global data register (or the “global data section”);\nStack;\nHeap;\n\n\n3.1.1 Compile-time known versus runtime known\nOne strategy that Zig uses to decide where it will store each object that you declare, is by looking at the value of this particular object. More specifically, by investigating if this value is known at “compile-time” or at “runtime”.\nWhen you write a program in Zig, the values of some of the objects that you write in your program are known at compile time. Meaning that, when you compile your Zig source code, during the compilation process, the zig compiler can figure out the exact value of a particular object that exists in your source code. Knowing the length (or the size) of each object is also important. So the length (or the size) of each object that you write in your program is, in some cases, known at compile time.\nThe zig compiler cares more about knowing the length (or the size) of a particular object , than to know its actual value. But, if the zig compiler knows the value of the object, then, it automatically knows the size of this object. Because it can simply calculate the size of the object by looking at the size of the value.\nTherefore, the priority for the zig compiler is to discover the size of each object in your source code. If the value of the object in question is known at compile-time, then, the zig compiler automatically knows the size/length of this object. But if the value of this object is not known at compile-time, then, the size of this object is only known at compile-time if, and only if, the type of this object has a known fixed size.\nIn order for a type to have a known fixed size, this type must have data members whose size is fixed. If this type includes, for example, a variable sized array in it, then, this type does not have a known fixed size. Because this array can have any size at runtime (i.e., it can be an array of 2 elements, or 50 elements, or 1 thousand elements, etc.).\nFor example, a string object, which internally is an array of constant u8 values ([]const u8) has a variable size. It can be a string object with 100 or 500 characters in it. If we do not know at compile-time, which exact string will be stored inside this string object, then, we cannot calculate the size of this string object at compile-time. So, any type, or any struct declaration that you make, that includes a string data member that does not have an explicit fixed size, makes this type, or this new struct that you are declaring, a type that does not have a known fixed size at compile-time.\nIn contrast, if the type of this struct that you are declaring, includes a data member that is an array, but this array has a known fixed size, like [60]u8 (which declares an array of 60 u8 values), then, this type, or, this struct that you are declaring, becomes a type with a known fixed size at compile-time. And because of that, in this case, the zig compiler does not need to know at compile-time the exact value of any object of this type. Since the compiler can find the necessary size to store this object by looking at the size of its type.\nLet’s look at an example. In the source code below, we have two constant objects (name and array) declared. Because the values of these particular objects are written down, in the source code itself (\"Pedro\" and the number sequence from 1 to 4), the zig compiler can easily discover the values of these constant objects (name and array) during the compilation process. This is what “known at compile time” means. It refers to any object that you have in your Zig source code whose value can be identified at compile time.\n\nfn input_length(input: []const u8) usize {\n    const n = input.len;\n    return n;\n}\n\npub fn main() !void {\n    const name = \"Pedro\";\n    const array = [_]u8{1, 2, 3, 4};\n    _ = name; _ = array;\n}\n\nThe other side of the spectrum are objects whose values are not known at compile time. Function arguments are a classic example of this. Because the value of each function argument depends on the value that you assign to this particular argument, when you call the function.\nFor example, the function input_length() contains an argument named input, which is an array of constant u8 integers ([]const u8). It’s impossible to know the value of this particular argument at compile time. And it also is impossible to know the size/length of this particular argument. Because it’s an array that does not have a fixed size specified explicitly in the argument type annotation.\nSo, we know that this input argument will be an array of u8 integers. But we do not know at compile-time, its value, and neither its size. This information is known only at runtime, which is the period of time when you program is executed. As a consequence, the value of the expression input.len is also known only at runtime. This is an intrinsic characteristic of any function. Just remember that the value of function arguments is usually not “compile-time known”.\nHowever, as I mentioned earlier, what really matters to the compiler is to know the size of the object at compile-time, and not necessarily its value. So, although we don’t know the value of the object n, which is the result of the expression input.len, at compile-time, we do know its size. Because the expression input.len always returns a value of type usize, and the type usize has a known fixed size.\n\n\n3.1.2 Global data register\nThe global data register is a specific section of the executable of your Zig program, that is responsible for storing any value that is known at compile time.\nEvery constant object whose value is known at compile time that you declare in your source code, is stored in the global data register. Also, every literal value that you write in your source code, such as the string \"this is a string\", or the integer 10, or a boolean value such as true, is also stored in the global data register.\nHonestly, you don’t need to care much about this memory space. Because you can’t control it, you can’t deliberately access it or use it for your own purposes. Also, this memory space does not affect the logic of your program. It simply exists in your program.\n\n\n3.1.3 Stack vs Heap\nIf you are familiar with systems programming, or just low-level programming in general, you probably have heard of the “duel” between Stack vs Heap. These are two different types of memory, or different memory spaces, which are both available in Zig.\nThese two types of memory don’t actually duel with each other. This is a common mistake that beginners have, when seeing “x vs y” styles of tabloid headlines. These two types of memory are actually complementary to each other. So, in almost every Zig program that you ever write, you will likely use a combination of both. I will describe each memory space in detail over the next sections. But for now, I just want to establish the main difference between these two types of memory.\nIn essence, the stack memory is normally used to store values whose length is fixed and known at compile time. In contrast, the heap memory is a dynamic type of memory space, meaning that, it’s used to store values whose length might grow during the execution (runtime) of your program (Chen and Guo 2022).\nLengths that grow during runtime are intrinsically associated with “runtime known” type of values. In other words, if you have an object whose length might grow during runtime, then, the length of this object becomes not known at compile time. If the length is not known at compile-time, the value of this object also becomes not known at compile-time. These types of objects should be stored in the heap memory space, which is a dynamic memory space, which can grow or shrink to fit the size of your objects.\n\n\n3.1.4 Stack\nThe stack is a type of memory that uses the power of the stack data structure, hence the name. A “stack” is a type of data structure that uses a “last in, first out” (LIFO) mechanism to store the values you give it to. I imagine you are familiar with this data structure. But, if you are not, the Wikipedia page1 , or, the Geeks For Geeks page2 are both excellent and easy resources to fully understand how this data structure works.\nSo, the stack memory space is a type of memory that stores values using a stack data structure. It adds and removes values from the memory by following a “last in, first out” (LIFO) principle.\nEvery time you make a function call in Zig, an amount of space in the stack is reserved for this particular function call (Chen and Guo 2022; Zig Software Foundation 2024). The value of each function argument given to the function in this function call is stored in this stack space. Also, every local object that you declare inside the function scope is usually stored in this same stack space.\nLooking at the example below, the object result is a local object declared inside the scope of the add() function. Because of that, this object is stored inside the stack space reserved for the add() function. The r object (which is declared outside of the add() function scope) is also stored in the stack. But since it’s declared in the “outer” scope, this object is stored in the stack space that belongs to this outer scope.\n\nfn add(x: u8, y: u8) u8 {\n    const result = x + y;\n    return result;\n}\n\npub fn main() !void {\n    const r = add(5, 27);\n    _ = r;\n}\n\nSo, any object that you declare inside the scope of a function is always stored inside the space that was reserved for that particular function in the stack memory. This also counts for any object declared inside the scope of your main() function for example. As you would expect, in this case, they are stored inside the stack space reserved for the main() function.\nOne very important detail about the stack memory is that it frees itself automatically. This is very important, remember that. When objects are stored in the stack memory, you don’t have the work (or the responsibility) of freeing/destroying these objects. Because they will be automatically destroyed once the stack space is freed at the end of the function scope.\nSo, once the function call returns (or ends, if you prefer to call it this way) the space that was reserved in the stack is destroyed, and all of the objects that were in that space goes away with it. This mechanism exists because this space, and the objects within it, are not necessary anymore, since the function “finished its business”. Using the add() function that we exposed above as an example, it means that the object result is automatically destroyed once the function returns.\n\n\n\n\n\n\nImportant\n\n\n\nLocal objects that are stored in the stack space of a function are automatically freed/destroyed at the end of the function scope.\n\n\nThis same logic applies to any other special structure in Zig that has its own scope by surrounding it with curly braces ({}). For loops, while loops, if else statements, etc. For example, if you declare any local object in the scope of a for loop, this local object is accessible only within the scope of this particular for loop. Because once the scope of this for loop ends, the space in the stack reserved for this for loop is freed. The example below demonstrates this idea.\n\n// This does not compile successfully!\nconst a = [_]u8{0, 1, 2, 3, 4};\nfor (0..a.len) |i| {\n    const index = i;\n    _ = index;\n}\n// Trying to use an object that was\n// declared in the for loop scope,\n// and that does not exist anymore.\nstd.debug.print(\"{d}\\n\", .{index});\n\nOne important consequence of this mechanism is that, once the function returns, you can no longer access any memory address that was inside the space in the stack reserved for this particular function. Because this space was destroyed. This means that, if this local object is stored in the stack, you cannot make a function that returns a pointer to this object.\nThink about that for a second. If all local objects in the stack are destroyed at the end of the function scope, why would you even consider returning a pointer to one of these objects? This pointer is at best, invalid, or, more likely, “undefined”.\nIn conclusion, it’s totally fine to write a function that returns the local object itself as result, because then, you return the value of that object as the result. But, if this local object is stored in the stack, you should never write a function that returns a pointer to this local object. Because the memory address pointed by the pointer no longer exists.\nSo, using again the add() function as an example, if you rewrite this function so that it returns a pointer to the local object result, the zig compiler will actually compile your program, with no warnings or errors. At first glance, it looks like this is good code that works as expected. But this is a lie!\nIf you try to take a look at the value inside of the r object, or, if you try to use this r object in another expression or function call, then, you would have undefined behaviour, and major bugs in your program (Zig Software Foundation 2024, see “Lifetime and Ownership”3 and “Undefined Behaviour”4 sections).\n\nfn add(x: u8, y: u8) *const u8 {\n    const result = x + y;\n    return &result;\n}\n\npub fn main() !void {\n    // This code compiles successfully. But it has\n    // undefined behaviour. Never do this!!!\n    // The `r` object is undefined!\n    const r = add(5, 27); _ = r;\n}\n\nThis “invalid pointer to stack variable” problem is well known across many programming language communities. If you try to do the same thing, for example, in a C or C++ program (i.e., returning an address to a local object stored in the stack), you would also get undefined behaviour in the program.\n\n\n\n\n\n\nImportant\n\n\n\nIf a local object in your function is stored in the stack, you should never return a pointer to this local object from the function. Because this pointer will always become undefined after the function returns, since the stack space of the function is destroyed at the end of its scope.\n\n\nBut what if you really need to use this local object in some way after your function returns? How can you do this? The answer is: “in the same way you would do if this were a C or C++ program. By returning an address to an object stored in the heap”. The heap memory has a much more flexible lifecycle, and allows you to get a valid pointer to a local object of a function that already returned from its scope.\n\n\n3.1.5 Heap\nOne important limitation of the stack, is that, only objects whose length/size is known at compile-time can be stored in it. In contrast, the heap is a much more dynamic (and flexible) type of memory. It’s the perfect type of memory to use for objects whose size/length might grow during the execution of your program.\nVirtually any application that behaves as a server is a classic use case of the heap. A HTTP server, a SSH server, a DNS server, a LSP server, … any type of server. In summary, a server is a type of application that runs for long periods of time, and that serves (or “deals with”) any incoming request that reaches this particular server.\nThe heap is a good choice for this type of system, mainly because the server does not know upfront how many requests it will receive from users, while it is active. It could be a single request, 5 thousand requests, or even zero requests. The server needs to have the ability to allocate and manage its memory according to how many requests it receives.\nAnother key difference between the stack and the heap, is that the heap is a type of memory that you, the programmer, have complete control over. This makes the heap a more flexible type of memory, but it also makes it harder to work with. Because you, the programmer, is responsible for managing everything related to it. Including where the memory is allocated, how much memory is allocated, and where this memory is freed.\n\nUnlike stack memory, heap memory is allocated explicitly by programmers and it won’t be deallocated until it is explicitly freed (Chen and Guo 2022).\n\nTo store an object in the heap, you, the programmer, needs to explicitly tells Zig to do so, by using an allocator to allocate some space in the heap. In Section 3.3, I will present how you can use allocators to allocate memory in Zig.\n\n\n\n\n\n\nImportant\n\n\n\nEvery memory you allocate in the heap needs to be explicitly freed by you, the programmer.\n\n\nThe majority of allocators in Zig do allocate memory on the heap. But some exceptions to this rule are ArenaAllocator() and FixedBufferAllocator(). The ArenaAllocator() is a special type of allocator that works in conjunction with a second type of allocator. On the other side, the FixedBufferAllocator() is an allocator that works based on buffer objects created on the stack. This means that the FixedBufferAllocator() makes allocations only on the stack.\n\n\n3.1.6 Summary\nAfter discussing all of these boring details, we can quickly recap what we learned. In summary, the Zig compiler will use the following rules to decide where each object you declare is stored:\n\nevery literal value (such as \"this is string\", 10, or true) is stored in the global data section.\nevery constant object (const) whose value is known at compile-time is also stored in the global data section.\nevery object (constant or not) whose length/size is known at compile time is stored in the stack space for the current scope.\nif an object is created with the method alloc() or create() of an allocator object, this object is stored in the memory space used by this particular allocator object. Most of allocators available in Zig use the heap memory, so, this object is likely stored in the heap (FixedBufferAllocator() is an exception to that).\nthe heap can only be accessed through allocators. If your object was not created through the alloc() or create() methods of an allocator object, then, it is most certainly not an object stored in the heap.",
     "crumbs": [
       "<span class='chapter-number'>3</span>  <span class='chapter-title'>Memory and Allocators</span>"
     ]
@@ -364,7 +364,7 @@
     "href": "Chapters/01-base64.html#how-the-base64-algorithm-work",
     "title": "4  Project 1 - Building a base64 encoder/decoder",
     "section": "",
-    "text": "4.1.1 The base64 scale\nThe base64 encoding system is based on a scale that goes from 0 to 63 (hence the name). Each index in this scale is represented by a character (it’s a scale of 64 characters). So, in order to convert some binary data, to the base64 encoding, we need to convert each binary number to the corresponding character in this “scale of 64 characters”.\nThe base64 scale starts with all ASCII uppercase letters (A to Z) which represents the first 25 indexes in this scale (0 to 25). After that, we have all ASCII lowercase letters (a to z), which represents the range 26 to 51 in the scale. After that, we have the one digit numbers (0 to 9), which represents the indexes from 52 to 61 in the scale. Finally, the last two indexes in the scale (62 and 63) are represented by the characters + and /, respectively.\nThese are the 64 characters that compose the base64 scale. The equal sign character (=) is not part of the scale itself, but it is a special character in the base64 encoding system. This character is used solely as a suffix, to mark the end of the character sequence, or, to mark the end of meaningful characters in the sequence.\nThe bullet points below summarises the base64 scale:\n\nrange 0 to 25 is represented by: ASCII uppercase letters -&gt; [A-Z];\nrange 26 to 51 is represented by: ASCII lowercase letters -&gt; [a-z];\nrange 52 to 61 is represented by: one digit numbers -&gt; [0-9];\nindex 62 and 63 are represented by the characters + and /, respectively;\nthe character = represents the end of meaningful characters in the sequence;\n\n\n\n4.1.2 Creating the scale as a lookup table\nThe best way to represent this scale in code, is to represent it as a lookup table. Lookup tables are a classic strategy in computer science to speed up calculations. The basic idea is to replace a runtime calculation (which can take a long time to be done) with a basic array indexing operation.\nInstead of calculating the results everytime you need them, you calculate all possible results at once, and then, you store them in an array (which behaves lake a “table”). Then, every time you need to use one of the characters in the base64 scale, instead of using many resources to calculate the exact character to be used, you simply retrieve this character from the array where you stored all the possible characters in the base64 scale. We retrieve the character that we need directly from memory.\nWe can start building a Zig struct to store our base64 decoder/encoder logic. We start with the Base64 struct below. For now, we only have one single data member in this struct, i.e., the member _table, which represents our lookup table. We also have an init() method, to create a new instance of a Base64 object, and, a _char_at() method, which is a “get character at index \\(x\\)” type of function.\n\nconst Base64 = struct {\n    _table: *const [64]u8,\n\n    pub fn init() Base64 {\n        const upper = \"ABCDEFGHIJKLMNOPQRSTUVWXYZ\";\n        const lower = \"abcdefghijklmnopqrstuvwxyz\";\n        const numbers_symb = \"0123456789+/\";\n        return Base64{\n            ._table = upper ++ lower ++ numbers_symb,\n        };\n    }\n\n    pub fn _char_at(self: Base64, index: usize) u8 {\n        return self._table[index];\n    }\n};\n\nIn other words, the _char_at() method is responsible for getting the character in the lookup table (i.e., the _table struct data member) that corresponds to a particular index in the “base64 scale”. So, in the example below, we know that the character that corresponds to the index 28 in the “base64 scale” is the character “c”.\n\nconst base64 = Base64.init();\ntry stdout.print(\n    \"Character at index 28: {c}\\n\",\n    .{base64._char_at(28)}\n);\n\nCharacter at index 28: c\n\n\n4.1.3 A base64 encoder\nThe algorithm behind a base64 encoder usually works on a window of 3 bytes. Because each byte has 8 bits, so, 3 bytes forms a set of \\(8 \\times 3 = 24\\) bits. This is desirable for the base64 algorithm, because 24 bits is divisible by 6, which forms \\(24 / 6 = 4\\) groups of 6 bits each.\nTherefore, the base64 algorithm works by converting 3 bytes at a time into 4 characters from the base64 scale. It keeps iterating through the input string, 3 bytes at a time, and converting them into the base64 scale, producing 4 characters per iteration. It keeps iterating, and producing these “new characters” until it hits the end of the input string.\nNow you may think, what if you have a particular string that has a number of bytes that is not divisible by 3 - what happens? For example, if you have a string that contains only two characters/bytes, such as “Hi”. How would the algorithm behave in such situation? You find the answer in Figure 4.1. You can see in Figure 4.1 that the string “Hi”, when converted to base64, becomes the string “SGk=”:\n\n\n\n\n\n\nFigure 4.1: The logic behind a base64 encoder\n\n\n\nTaking the string “Hi” as an example, we have 2 bytes, or, 16 bits in total. So, we lack a full byte (8 bits) to complete the window of 24 bits that the base64 algorithm likes to work on. The first thing that the algorithm does, is to check how to divide the input bytes into groups of 6 bits.\nIf the algorithm notices that there is a group of 6 bits that it’s not complete, meaning that, this group contains \\(nbits\\), where \\(0 &lt; nbits &lt; 6\\),\nthe algorithm simply adds extra zeros in this group to fill the space that it needs. That is why in Figure 4.1, in the third group after the 6-bit transformation, 2 extra zeros were added to fill the gap.\nWhen we have a 6-bit group that is not completely full, like the third group, extra zeros are added to fill the gap. But what about when an entire 6-bit group is empty, or, it simply doesn’t exist? This is the case of the fourth 6-bit group exposed at Figure 4.1.\nThis fourth group is necessary, because the algorithm works on 4 groups of 6 bits. But the input string does not have enough bytes to create a fourth 6-bit group. Every time this happens, where an entire group of 6 bits is empty, this group becomes a “padding group”. Every “padding group” is mapped to the character = (equal sign), which represents “null”, or, the end of meaningful characters in the sequence. Hence, everytime that the algorithm produces a “padding group”, this group is automatically mapped to =.\nAs another example, if you give the string “0” as input to a base64 encoder, this string is translated into the base64 sequence “MA==”. The character “0” is, in binary, the sequence 001100001. So, with the 6-bit transformation exposed in Figure 4.1, this single character would produce these two 6-bit groups: 001100, 000000. The remaining two 6-bit groups become “padding groups”. That is why the last two characters in the output sequence (MA==) are ==.\n\n\n4.1.4 A base64 decoder\nThe algorithm behind a base64 decoder is essentially the inverse process of a base64 encoder. A base64 decoder needs to translate base64 messages back into their original meaning, i.e., into the original sequence of binary data.\nA base64 decoder usually works on a window of 4 bytes. Because it wants to convert these 4 bytes back into the original sequence of 3 bytes, that was converted into 4 groups of 6 bits by the base64 encoder. Remember, in a base64 decoder we are essentially reverting the process made by the base64 encoder.\nEach byte in the input string (the base64 encoded string) normally contributes to re-create two different bytes in the output (the original binary data). In other words, each byte that comes out of a base64 decoder is created by transforming merging two different bytes in the input together. You can visualize this relationship in Figure 4.2:\n\n\n\n\n\n\nFigure 4.2: The logic behind a base64 decoder\n\n\n\nThe exact transformations, or, the exact steps applied to each byte from the input to transform them into the bytes of the output, are a bit tricky to visualize in a figure like this. Because of that, I have summarized these transformations as “Some bit shifting and additions …” in the figure. These transformations will be described in depth later.\nBesides that, if you look again in Figure 4.2, you will notice that the character = was completely ignored by the algorithm. Remember, this is just a special character that marks the end of meaningful characters in the base64 sequence. So, every = character in a base64 encoded sequence should be ignored by a base64 decoder.",
+    "text": "4.1.1 The base64 scale\nThe base64 encoding system is based on a scale that goes from 0 to 63 (hence the name). Each index in this scale is represented by a character (it’s a scale of 64 characters). So, in order to convert some binary data, to the base64 encoding, we need to convert each binary number to the corresponding character in this “scale of 64 characters”.\nThe base64 scale starts with all ASCII uppercase letters (A to Z) which represents the first 25 indexes in this scale (0 to 25). After that, we have all ASCII lowercase letters (a to z), which represents the range 26 to 51 in the scale. After that, we have the one digit numbers (0 to 9), which represents the indexes from 52 to 61 in the scale. Finally, the last two indexes in the scale (62 and 63) are represented by the characters + and /, respectively.\nThese are the 64 characters that compose the base64 scale. The equal sign character (=) is not part of the scale itself, but it is a special character in the base64 encoding system. This character is used solely as a suffix, to mark the end of the character sequence, or, to mark the end of meaningful characters in the sequence.\nThe bullet points below summarises the base64 scale:\n\nrange 0 to 25 is represented by: ASCII uppercase letters -&gt; [A-Z];\nrange 26 to 51 is represented by: ASCII lowercase letters -&gt; [a-z];\nrange 52 to 61 is represented by: one digit numbers -&gt; [0-9];\nindex 62 and 63 are represented by the characters + and /, respectively;\nthe character = represents the end of meaningful characters in the sequence;\n\n\n\n4.1.2 Creating the scale as a lookup table\nThe best way to represent this scale in code, is to represent it as a lookup table. Lookup tables are a classic strategy in computer science to speed up calculations. The basic idea is to replace a runtime calculation (which can take a long time to be done) with a basic array indexing operation.\nInstead of calculating the results everytime you need them, you calculate all possible results at once, and then, you store them in an array (which behaves like a “table”). Then, every time you need to use one of the characters in the base64 scale, instead of using many resources to calculate the exact character to be used, you simply retrieve this character from the array where you stored all the possible characters in the base64 scale. We retrieve the character that we need directly from memory.\nWe can start building a Zig struct to store our base64 decoder/encoder logic. We start with the Base64 struct below. For now, we only have one single data member in this struct, i.e., the member _table, which represents our lookup table. We also have an init() method, to create a new instance of a Base64 object, and, a _char_at() method, which is a “get character at index \\(x\\)” type of function.\n\nconst Base64 = struct {\n    _table: *const [64]u8,\n\n    pub fn init() Base64 {\n        const upper = \"ABCDEFGHIJKLMNOPQRSTUVWXYZ\";\n        const lower = \"abcdefghijklmnopqrstuvwxyz\";\n        const numbers_symb = \"0123456789+/\";\n        return Base64{\n            ._table = upper ++ lower ++ numbers_symb,\n        };\n    }\n\n    pub fn _char_at(self: Base64, index: usize) u8 {\n        return self._table[index];\n    }\n};\n\nIn other words, the _char_at() method is responsible for getting the character in the lookup table (i.e., the _table struct data member) that corresponds to a particular index in the “base64 scale”. So, in the example below, we know that the character that corresponds to the index 28 in the “base64 scale” is the character “c”.\n\nconst base64 = Base64.init();\ntry stdout.print(\n    \"Character at index 28: {c}\\n\",\n    .{base64._char_at(28)}\n);\n\nCharacter at index 28: c\n\n\n4.1.3 A base64 encoder\nThe algorithm behind a base64 encoder usually works on a window of 3 bytes. Because each byte has 8 bits, so, 3 bytes forms a set of \\(8 \\times 3 = 24\\) bits. This is desirable for the base64 algorithm, because 24 bits is divisible by 6, which forms \\(24 / 6 = 4\\) groups of 6 bits each.\nTherefore, the base64 algorithm works by converting 3 bytes at a time into 4 characters from the base64 scale. It keeps iterating through the input string, 3 bytes at a time, and converting them into the base64 scale, producing 4 characters per iteration. It keeps iterating, and producing these “new characters” until it hits the end of the input string.\nNow you may think, what if you have a particular string that has a number of bytes that is not divisible by 3 - what happens? For example, if you have a string that contains only two characters/bytes, such as “Hi”. How would the algorithm behave in such situation? You find the answer in Figure 4.1. You can see in Figure 4.1 that the string “Hi”, when converted to base64, becomes the string “SGk=”:\n\n\n\n\n\n\nFigure 4.1: The logic behind a base64 encoder\n\n\n\nTaking the string “Hi” as an example, we have 2 bytes, or, 16 bits in total. So, we lack a full byte (8 bits) to complete the window of 24 bits that the base64 algorithm likes to work on. The first thing that the algorithm does, is to check how to divide the input bytes into groups of 6 bits.\nIf the algorithm notices that there is a group of 6 bits that it’s not complete, meaning that, this group contains \\(nbits\\), where \\(0 &lt; nbits &lt; 6\\),\nthe algorithm simply adds extra zeros in this group to fill the space that it needs. That is why in Figure 4.1, in the third group after the 6-bit transformation, 2 extra zeros were added to fill the gap.\nWhen we have a 6-bit group that is not completely full, like the third group, extra zeros are added to fill the gap. But what about when an entire 6-bit group is empty, or, it simply doesn’t exist? This is the case of the fourth 6-bit group exposed at Figure 4.1.\nThis fourth group is necessary, because the algorithm works on 4 groups of 6 bits. But the input string does not have enough bytes to create a fourth 6-bit group. Every time this happens, where an entire group of 6 bits is empty, this group becomes a “padding group”. Every “padding group” is mapped to the character = (equal sign), which represents “null”, or, the end of meaningful characters in the sequence. Hence, everytime that the algorithm produces a “padding group”, this group is automatically mapped to =.\nAs another example, if you give the string “0” as input to a base64 encoder, this string is translated into the base64 sequence “MA==”. The character “0” is, in binary, the sequence 001100001. So, with the 6-bit transformation exposed in Figure 4.1, this single character would produce these two 6-bit groups: 001100, 000000. The remaining two 6-bit groups become “padding groups”. That is why the last two characters in the output sequence (MA==) are ==.\n\n\n4.1.4 A base64 decoder\nThe algorithm behind a base64 decoder is essentially the inverse process of a base64 encoder. A base64 decoder needs to translate base64 messages back into their original meaning, i.e., into the original sequence of binary data.\nA base64 decoder usually works on a window of 4 bytes. Because it wants to convert these 4 bytes back into the original sequence of 3 bytes, that was converted into 4 groups of 6 bits by the base64 encoder. Remember, in a base64 decoder we are essentially reverting the process made by the base64 encoder.\nEach byte in the input string (the base64 encoded string) normally contributes to re-create two different bytes in the output (the original binary data). In other words, each byte that comes out of a base64 decoder is created by transforming merging two different bytes in the input together. You can visualize this relationship in Figure 4.2:\n\n\n\n\n\n\nFigure 4.2: The logic behind a base64 decoder\n\n\n\nThe exact transformations, or, the exact steps applied to each byte from the input to transform them into the bytes of the output, are a bit tricky to visualize in a figure like this. Because of that, I have summarized these transformations as “Some bit shifting and additions …” in the figure. These transformations will be described in depth later.\nBesides that, if you look again in Figure 4.2, you will notice that the character = was completely ignored by the algorithm. Remember, this is just a special character that marks the end of meaningful characters in the base64 sequence. So, every = character in a base64 encoded sequence should be ignored by a base64 decoder.",
     "crumbs": [
       "<span class='chapter-number'>4</span>  <span class='chapter-title'>Project 1 - Building a base64 encoder/decoder</span>"
     ]

From 307ce8a1ee04e8e86cd799d5a4c87335d7b1c744 Mon Sep 17 00:00:00 2001
From: Ben Scheirman <ben@scheirman.com>
Date: Mon, 9 Jun 2025 07:48:11 -0500
Subject: [PATCH 146/151] =?UTF-8?q?Fix=20typo=20(bif=20=E2=86=92=20bit)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 Chapters/01-base64.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/01-base64.qmd b/Chapters/01-base64.qmd
index 023250f3..68047d70 100644
--- a/Chapters/01-base64.qmd
+++ b/Chapters/01-base64.qmd
@@ -348,7 +348,7 @@ to comprehend.
 
 In essence, this 6-bit transformation is made with the help of bitwise operators.
 Bitwise operators are essential to any type of low-level operation that is done at the bit-level. For the specific case of the base64 algorithm,
-the operators *bif shift to the left* (`<<`), *bit shift to the right* (`>>`), and the *bitwise and* (`&`) are used. They
+the operators *bit shift to the left* (`<<`), *bit shift to the right* (`>>`), and the *bitwise and* (`&`) are used. They
 are the core solution for the 6-bit transformation.
 
 There are 3 different scenarios that we need to take into account in this transformation. First, is the perfect scenario,

From a487d21e2b589dde6280c841fb1081b0ee940ebc Mon Sep 17 00:00:00 2001
From: Karl Gaissmaier <karl.gaissmaier@uni-ulm.de>
Date: Thu, 12 Jun 2025 21:11:13 +0200
Subject: [PATCH 147/151] fixing typo

---
 Chapters/01-memory.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/01-memory.qmd b/Chapters/01-memory.qmd
index 54d71fe0..1b7195a9 100644
--- a/Chapters/01-memory.qmd
+++ b/Chapters/01-memory.qmd
@@ -760,7 +760,7 @@ should use `alloc()` and `free()`. But if you need to store just a single item,
 then, the `create()` and `destroy()` methods are ideal for you.
 
 In the example below, I'm defining a struct to represent an user of some sort.
-It could be a user for a game, or software to manage resources, it doesn't mater.
+It could be a user for a game, or software to manage resources, it doesn't matter.
 Notice that I use the `create()` method this time, to store a single `User` object
 in the program. Also notice that I use the `destroy()` method to free the memory
 used by this object at the end of the scope.

From f2f39063c7e96e99cc5aa290c4ac3ea3080e4f6d Mon Sep 17 00:00:00 2001
From: Karl Gaissmaier <karl.gaissmaier@uni-ulm.de>
Date: Fri, 13 Jun 2025 07:36:09 +0200
Subject: [PATCH 148/151] Update 01-base64.qmd

---
 Chapters/01-base64.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/01-base64.qmd b/Chapters/01-base64.qmd
index 68047d70..1448f86f 100644
--- a/Chapters/01-base64.qmd
+++ b/Chapters/01-base64.qmd
@@ -540,7 +540,7 @@ and decoder in the stack.
 Consequently, we need to store this output on the heap,
 and, as I commented in @sec-heap, we can only
 store objects in the heap by using allocator objects.
-So, one the arguments to both the `encode()` and `decode()`
+So, one of the arguments to both the `encode()` and `decode()`
 functions, needs to be an allocator object, because
 we know for sure that, at some point inside the body of these
 functions, we need to allocate space on the heap to

From 29a45091128b9ffb2af85445fb0732295d57c90c Mon Sep 17 00:00:00 2001
From: Karl Gaissmaier <karl.gaissmaier@uni-ulm.de>
Date: Fri, 13 Jun 2025 19:16:07 +0200
Subject: [PATCH 149/151] make allocatore first parameter

---
 ZigExamples/base64/base64_basic.zig | 8 ++++----
 ZigExamples/base64/base64_table.zig | 4 ++--
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/ZigExamples/base64/base64_basic.zig b/ZigExamples/base64/base64_basic.zig
index 5d395a58..c37decd4 100644
--- a/ZigExamples/base64/base64_basic.zig
+++ b/ZigExamples/base64/base64_basic.zig
@@ -35,7 +35,7 @@ const Base64 = struct {
         return index;
     }
 
-    fn encode(self: Base64, input: []const u8, allocator: std.mem.Allocator) ![]u8 {
+    fn encode(self: Base64, allocator: std.mem.Allocator, input: []const u8) ![]u8 {
         if (input.len == 0)
             return "";
 
@@ -76,7 +76,7 @@ const Base64 = struct {
         return output;
     }
 
-    fn decode(self: Base64, input: []const u8, allocator: std.mem.Allocator) ![]u8 {
+    fn decode(self: Base64, allocator: std.mem.Allocator, input: []const u8) ![]u8 {
         if (input.len == 0)
             return "";
 
@@ -146,8 +146,8 @@ pub fn main() !void {
     const text = "Testing some more stuff";
     const etext = "VGVzdGluZyBzb21lIG1vcmUgc3R1ZmY=";
     const base64 = Base64.init();
-    const encoded_text = try base64.encode(text, allocator);
-    const decoded_text = try base64.decode(etext, allocator);
+    const encoded_text = try base64.encode(allocator, text);
+    const decoded_text = try base64.decode(allocator, etext);
 
     try stdout.print("Encoded text: {s}\n", .{encoded_text});
     try stdout.print("Decoded text: {s}\n", .{decoded_text});
diff --git a/ZigExamples/base64/base64_table.zig b/ZigExamples/base64/base64_table.zig
index dbfab812..dddc2b0f 100644
--- a/ZigExamples/base64/base64_table.zig
+++ b/ZigExamples/base64/base64_table.zig
@@ -28,7 +28,7 @@ fn calc_output_length(input_length: usize) u8 {
     return @intFromFloat(@ceil(d));
 }
 
-fn decode(input: []const u8, allocator: std.mem.Allocator) !void {
+fn decode(allocator: std.mem.Allocator, input: []const u8) !void {
     try stdout.print("Start decoding of {s}\n", .{input});
     // var output = [_]u8{ 0, 0, 0, 0 };
     // _ = output;
@@ -50,5 +50,5 @@ pub fn main() !void {
     defer arena.deinit();
     const allocator = arena.allocator();
 
-    try decode(text, allocator);
+    try decode(allocator, text);
 }

From b173ac0007b70271a8873c291807b571840a9bf2 Mon Sep 17 00:00:00 2001
From: Karl Gaissmaier <karl.gaissmaier@uni-ulm.de>
Date: Fri, 13 Jun 2025 22:27:18 +0200
Subject: [PATCH 150/151] IMHO typo

in root folder -> in the root folder
---
 Chapters/01-zig-weird.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Chapters/01-zig-weird.qmd b/Chapters/01-zig-weird.qmd
index 99c710af..a03b1244 100644
--- a/Chapters/01-zig-weird.qmd
+++ b/Chapters/01-zig-weird.qmd
@@ -167,7 +167,7 @@ and install the library in your system, and just link your source code
 with the library at the build step of your project.
 
 However, if this external Zig library is available on GitHub for example,
-and it has a valid `build.zig.zon` file in root folder of the project,
+and it has a valid `build.zig.zon` file in the root folder of the project,
 which describes the project, you can easily include this library in
 your project by simply listing this external library in your `build.zig.zon` file.
 

From cd845793ae733c9922dd671e7592c68c850fe6d6 Mon Sep 17 00:00:00 2001
From: Pedro Faria <69123925+pedropark99@users.noreply.github.com>
Date: Sun, 15 Jun 2025 13:39:27 -0300
Subject: [PATCH 151/151] Add contributors to the list

---
 contributors.txt | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/contributors.txt b/contributors.txt
index e6f0f030..b7b307a2 100644
--- a/contributors.txt
+++ b/contributors.txt
@@ -26,3 +26,5 @@ glystik,@glystik
 Michael Lynch,@mtlynch
 Yashank,@stickyburn
 _blf_,@bengtfrost
+Karl Gaissmaier,@gaissmai
+Ben Scheirman,@subdigital